# 从源码到边缘：基于 GitHub 与 Cloudflare Workers 的全自动持续交付

> 摒弃沉重的动态服务器与数据库，解析 Maplen 的静态技术路线选型、Git 源码资产沉淀，以及基于 Cloudflare Workers 静态资产网络的全自动持续交付流水线

- HTML: /nodes/deployment-showcase/
- Markdown: /nodes/deployment-showcase.md
- Section: Nodes / 实践
- Published: 2026.11.09
- Column: Maplen
- Tags: 功能展示

---

export const deliveryPipeline = `
flowchart TD
  subgraph Local["一、本地创作与版本沉淀 (Git)"]
    direction LR
    A1["本地写作与调试<br/>(Markdown / MDX)"] --> A2["Git 提交版本<br/>(git commit)"]
  end

  subgraph Cloud["二、云端代码仓库 (GitHub)"]
    direction LR
    B1["推送到远程分支<br/>(git push origin main)"] --> B2["GitHub Webhook<br/>(自动发出部署触发)"]
  end

  subgraph Build["三、自动化编译管线 (Workers Builds)"]
    direction LR
    C1["云端拉取提交<br/>(复用构建缓存)"] --> C2["执行静态构建<br/>(npm run build:pages)"] --> C3["Wrangler 部署产物<br/>(wrangler deploy)"]
  end

  subgraph Edge["四、全球边缘网络交付 (Cloudflare Workers)"]
    direction LR
    D1["推送到 300+ 边缘节点"] --- D2["Workers 挂载 maplen.top"] --- D3["毫秒级就近缓存命中"]
  end

  Local ==> Cloud
  Cloud ==> Build
  Build ==> Edge
`;

在搭建一个个人网站时，很多作者都会陷入一种常见的「运维内耗」：

租一台云服务器，装上 Linux、Nginx、MySQL 和 PHP，部署一套 WordPress 或自建后端；接着每隔几个月就要应付一次数据库升级、修复未知的安全补丁、配置即将过期的 SSL 证书；甚至当有一篇文章偶然迎来较大访问量时，服务器的内存和 CPU 还会直接报警宕机。

在搭建 [Maplen](/wiki/maplen.md) 之初，我就明确了一个原则：**我希望把所有精力倾注在思考、写作与工程验证本身，而不是把时间浪费在服务器运维上。**

一个真正具备生命力的数字花园，应当能够承受得起时间的洗刷——即使十年、二十年过去，内容依然完整无损，不需要维护任何复杂的后台服务，依然能以最快速度呈现在读者眼前。

这篇手记阐述 Maplen 的技术路线选型逻辑，以及我是如何通过 **GitHub 源码沉淀** 与 **Cloudflare Workers 静态资产网络持续交付（CD）**，实现这套零运维、全自动流水线的。

---

## 一、技术路线选型：为什么选择「纯静态优先 + Cloudflare Workers」

在架构设计中，每一个技术决策都是对现实约束的权衡。Maplen 的技术路线遵循三个核心判断：

### 1. 为什么坚决拒绝动态后端与数据库？
- **零安全维护负担**：没有数据库，就意味着从根本上杜绝了 SQL 注入攻击；没有动态后端守护进程，就不存在进程崩溃、内存泄漏或端口暴露的风险；
- **内容资产的永久存活性**：保存在数据库二进制表里的文章极其脆弱；而用 [Markdown (.md)](/wiki/md.md) 与 [MDX (.mdx)](/wiki/mdx.md) 编写的纯文本，在任何操作系统、任何编辑器下都能随时阅读，天生具备抵抗技术周期更迭的能力；
- **确定性的极致速度**：动态页面每一次访问都需要耗费 CPU 进行模板拼装和数据库查表；而纯静态页面在被请求的瞬间，文件就已经完整生成并常驻于内存缓存，响应时间只取决于物理网络时延。

### 2. 为什么选择 [Astro](/wiki/astro.md) 作为静态基座？
在现有的静态生成器中，许多现代前端框架（如 Next.js、Nuxt）倾向于将整站渲染为一个庞大的单页应用（SPA），即使是一篇纯文本随笔，首屏也需要加载数百 KB 的 JavaScript 运行时进行全量水合。

Astro 的**「默认零 JS（Zero-JS by Default）」**理念与 Maplen 的「纸墨质感」不谋而合：
- 渲染出的所有常规文章均为 100% 纯净语义的 HTML 与 CSS；
- 只有当文章需要呈现诸如阻尼振子模拟、微处理器状态机或函数图表时，才通过 `client:visible` 按需激活微小的 React 孤岛（Islands），兼得极致的文字阅读体验与富交互表现力。

### 3. 为什么选择 Cloudflare Workers 静态资产托管（Workers Static Assets）？
传统的静态托管（如自购 VPS 挂载 Nginx）依然摆脱不了单点机房的地理限制，国内访问快的节点国外慢，反之亦然，且带宽成本昂贵。

而 Cloudflare 推出的 **Workers 静态资产模式（Workers Static Assets）** 代表了现代无服务器边缘架构的最新演进：
- **静态请求完全免费且不限流量**：静态页面与资源直接由 Cloudflare 全球 300 多个城市的 Anycast 边缘网络无损吐出，没有任何流量账单焦虑；
- **原生边缘运行时集成**：通过 `wrangler.jsonc` 声明，既享有纯静态秒开的确定性，又在底层预留了未来按需接入边缘轻量计算（如边缘鉴权或动态重定向）的延展空间；
- **开箱即用的高阶网络特性**：全自动配置 HTTP/3、最新 TLS 证书与自动路径斜杠规整，省去所有反向代理的繁琐调优。

---

## 二、使用 GitHub 保存：把 Git 作为唯一的真实数据源

在 Maplen 的架构中，没有独立的后台管理系统（CMS）。**Git 版本控制系统，就是整座站点唯一的真实数据源（Single Source of Truth）。**

### 1. 写作即编码，思想即提交
- 无论是随笔（Notes）、纪事（Narrative），还是硬核的工程手记（Nodes），每一篇文章都与网站的主题样式、排版插件受同一套 Git 仓库统一管理；
- 每一次观点的推敲、段落的重构、甚至是一处错别字的勘误，都会生成一次清晰的 `git commit`；
- 借助 Git 的历史日志与 Diff 比对，我可以精确追溯任何一个概念在数月或数年间的认识演进轨迹。

### 2. 本地验证与远程同步
日常写作与调试的流程极其自然：
```bash
# 1. 本地启动实时热重载开发服务
npm run dev

# 2. 随时运行静态编译与编码健康检查
npm run build:pages

# 3. 确认无误后，提交并推送到 GitHub 远程仓库
git add .
git commit -m "feat: 发布全新的持续交付工程手记"
git push origin main
```

代码推送到 GitHub 远程仓库后，GitHub 不仅充当了高可靠的云端异地灾备节点，更重要的是，它将作为自动化流水线的起点，触发后续的整个部署流程。

---

## 三、持续交付到 Cloudflare Workers：从代码推送至边缘上线

当本地执行完 `git push origin main` 之后，剩下的所有事情全部由机器自动化完成。



整个持续交付流水线主要由以下环节紧密咬合：

### 1. Workers Builds 自动化监听
Cloudflare Workers Builds 深度集成到项目 GitHub 仓库。只要 `main` 生产分支接收到新的 Push 提交，Cloudflare 会立刻捕获 Webhook 通知，在云端拉起一个独立的沙箱构建容器。

### 2. 构建与部署命令配置
在 Cloudflare Workers 控制台中，构建流程配置极其清爽：
- **构建命令（Build command）**：`npm run build:pages`（负责文本编码健康校验与 Astro 全量静态编译）；
- **部署命令（Deploy command）**：`npx wrangler deploy`（将生成的静态产物一键推向 Workers Assets 边缘网络）；
- **环境变量**：指定现代运行时环境，例如 `NODE_VERSION = 22` 与主站域名 `PUBLIC_SITE_URL = https://maplen.top`。

### 3. 构建侦听过滤与构建缓存优化
为了不浪费云端构建配额，并提升部署速度，流水线加入了针对性的调优：
- **路径侦听过滤（Build Watch Paths）**：将触发范围限定在代码与文章核心目录，自动排除 `README.md` 与内部设计文档的变更。纯文档修改不会触发徒劳的线上部署；
- **构建缓存（Build Cache）**：开启云端构建缓存后，Cloudflare 会在多轮构建之间持久化复用包管理器与编译中间缓存，将后续的构建耗时压缩至极短。

### 4. 自定义域名接入与全自动证书
产物发布后：
- 在 Worker 的 **Custom Domains** 中绑定独立域名 `maplen.top`；
- Cloudflare 全球 DNS 会自动接管流量路由，现代 TLS 证书的申请、续期完全自动化；
- 全球各地的读者发起访问时，流量均被最近的边缘数据中心承接，在数毫秒内完成响应。

---

## 四、极简架构带来的从容

回顾整套工程实现：
- 没有常驻的 Linux 虚拟主机与后台进程；
- 没有需要备份和维护的脆弱数据库；
- 没有需要每季度手动续期的 SSL 证书；
- 没有复杂的第三方发布平台或 CMS 依赖。

从在键盘上敲下 Markdown 文字，到通过 Git 提交，再到 Cloudflare Workers 将其推向全球边缘，整个流程如行云流水般自然。

这种高度自洽且克制的工程设计，让技术彻底回归为创作的坚实后盾——无论何时打开电脑，我只需专注于文字与代码本身，而世界彼端的读者，则能在毫秒之间，翻开这页安静的纸墨。