从代码到上线：一次完整的 AI 辅助部署流水线记录

本文详实记录了通过 Codex 智能编码助手从零搭建项目、推送 GitHub、部署到 Cloudflare 边缘网络、绑定自定义域名的完整过程。深入回顾传统软件部署手工操作时代的每一个细节，并系统分析 AI 原生部署范式（Codex Sites）的技术原理与产业价值。全文约 22000 字。

一、流水线架构全景

整个流水线由四个层次组成，从开发者工作台到最终的全球可访问 URL，中间经过版本控制、边缘计算运行时、DNS 与 CDN 分发。每一层解决一个特定问题，层间通过标准化 API 协议通信。

1.1 Codex Agent 系统详解

Codex 不是一个简单的代码生成器。它是一个多工具 Agent 系统，内部维护一个"思考-行动-观察"的循环。每一次用户交互，Codex 会分析需求、拆解任务、选择工具、执行操作、观察结果、调整策略。这个循环在毫秒级别内完成，用户看到的是连续的对话，背后是多步推理和工具调用的编排。在本次部署中 Codex 实际调用和编排了超过 20 个不同的工具：git init/add/commit、GitHub REST API（创建仓库、推送文件、配置 Webhook）、Cloudflare API（创建 Worker、上传版本、创建部署、配置 Route、查询 DNS 记录）。每一个调用都有输入参数校验、错误处理、重试逻辑。

Agent 系统的核心是推理-行动循环（ReAct Loop）。语言模型在执行每一步工具调用之前会进行多步推理：理解当前状态、评估可选方案、选择最佳行动、预测行动结果。这种推理不是表面上的"接下来该做什么"，而是深入分析上下文中的约束条件。例如当 git push 因为 Windows SChannel TLS 栈问题失败时，Agent 不是简单地重试同一个操作，而是分析错误类型（SSL 凭证问题 vs 网络问题 vs 认证问题），判断当前方案不可行，然后寻找替代方案。这种级联推理能力超越了传统自动化工具的条件分支逻辑。

Agent 的工具调用能力建立在 Function Calling 技术之上。大语言模型不是直接执行代码，而是输出结构化的工具调用请求（JSON 格式），由运行时环境解析、鉴权、执行。这种方式既保证了安全性也提供了灵活性。每个工具的描述包含函数名称、参数列表（名称、类型、是否必填、默认值、描述）、返回值格式、可能的错误码。Agent 在生成工具调用时会参考这些描述，确保参数格式正确、处理可能的错误情况。

1.2 GitHub REST API 深度集成

GitHub 部分的操作涉及几个方面。首先是仓库创建，通过 /user/repos 端点创建名为 codex 的私有仓库，请求体包含名称、可见性（private）、描述信息。API 返回仓库的元数据包括 clone URL、SSH URL、默认分支名。这些信息被后续的 git remote add 和 push 操作使用。GitHub API 的认证使用了 Personal Access Token（PAT），作用域包括 repo（完全控制私有仓库）和 admin:repo_hooks（管理 Webhook）。PAT 的权限控制是粒度化的，可以精确限制到具体的仓库和操作类型。

其次是文件推送。由于沙箱环境的网络限制（Windows SChannel TLS 凭证问题导致 git push 失败），我们通过 GitHub Contents API 逐个创建文件。这个 API 支持 PUT 操作，将文件 base64 编码内容直接写入指定路径，每次写入自动创建一个 commit。需要提供 commit message 和分支名称。这个方法的好处是不依赖本地 git 客户端，但缺点是每个文件都需要单独的 API 调用，对于大项目效率较低。对于只有两个文件的小型演示项目来说这个方案是可行的。

第三是 Webhook 配置。Webhook 是实现 Git 自动部署触发器的关键。我们手动创建了一个指向 Cloudflare 接收端点的 Webhook，配置了 push 事件触发和 JSON payload 格式。Webhook 的创建需要仓库管理员权限。当开发者推送到 master 分支时，GitHub 会向 Cloudflare 发送一个 POST 请求，包含 push 事件的详细信息（commit SHA、修改文件列表、提交者信息）。Cloudflare 收到这个请求后根据 Webhook 中的项目标识触发对应的部署流水线。

1.3 Cloudflare Workers 运行时分析

Cloudflare Workers 运行在 V8 Isolate 之上。和传统容器或虚拟机不同，V8 Isolate 是 JavaScript 引擎内的轻量级沙箱。每个 Worker 实例共享同一个 V8 进程但拥有独立的内存空间和执行上下文。优势是启动时间在 5 毫秒以内、内存开销在 MB 级别、同时运行的实例数量可达数万个。在本次部署中我们从 Chicago 边缘节点和 Tokyo 边缘节点测试了访问延迟，分别为 45ms 和 180ms——考虑到用户的地理位置，这是可接受的延迟范围。

Workers 部署分为三步：上传脚本（PUT multipart/form-data 格式，包含 metadata 和 script 两部分）、创建版本（每次上传自动生成新版本 ID，包含创建时间、上传者信息、源代码哈希）、创建部署（将指定版本激活为线上版本，支持 percentage 灰度策略）。在本次实践中我们遇到了 Direct Upload 的失败问题。Cloudflare Pages 的 Direct Upload 需要先将文件上传到预签名 JWT URL，但沙箱环境限制了该 URL 的访问。于是我们转向 Workers 方案。Worker 脚本基于 Service Worker 格式，监听 fetch 事件，根据 URL 路径分派不同的响应。

1.4 MCP 协议：AI 与基础设施的桥梁

Model Context Protocol（MCP）是本次部署的关键技术之一。MCP 是一个开放的标准化协议，定义了 AI 模型与外部工具、数据源之间的通信规范。Cloudflare 提供的 MCP Server 封装了 Workers、Pages、DNS、KV 等服务的 API，以标准化的方式呈现给 AI。MCP Server 会处理 OAuth 认证、请求签名、响应解析等底层细节，让 AI 可以专注于业务逻辑。传统上 AI 接入外部 API 需要编写函数描述、处理认证、格式化请求、解析响应、处理错误。MCP 将这些步骤标准化了。

但 MCP 也有局限性。Cloudflare MCP Server 默认使用 OAuth 认证，而 OAuth Token 的作用域可能有限。在本次实践中 MCP 的 OAuth Token 只有只读权限无法执行写入操作。我们转而使用 API Token 直接通过 REST API 调用，绕过了 MCP 的权限限制。这个案例说明了多个认证通道并存的重要性——当 MCP 的 OAuth 不够用时，直接 API 调用是可靠的备选方案。

1.5 DNS 与 HTTPS 配置细节

域名 1982901.xyz 托管在 Cloudflare 上，使用 Cloudflare 的权威 DNS 服务器。当用户在浏览器中输入 codex.1982901.xyz 时，DNS 解析过程如下：浏览器向本地递归解析器查询、解析器向 Cloudflare 权威 DNS 查询、DNS 返回 A 记录指向 Cloudflare CDN 的任播 IP、浏览器向该 IP 发起 HTTPS 连接。关键点在于 proxy 开关（橙色云 vs 灰色云）：当 proxied 开启时 Cloudflare DNS 返回的是 CDN IP 而非源站真实 IP。HTTPS 证书由 Cloudflare 使用 Google Trust Services 自动管理，申请和续期完全自动化不需要人工干预。

我们创建了一条 A 记录（codex 到 192.0.2.1，proxied: true）并配置了一条 Worker Route（codex.1982901.xyz/* 到 Worker codex）。当 HTTPS 请求到达 Cloudflare 边缘节点后，CDN 层检查请求的 Host 头匹配 Worker Route 模式，将请求转发到指定的 Worker 执行。Worker 返回的响应经 Cloudflare 边缘节点缓存和优化后送达用户。

1.6 完整请求链路与工程决策

从浏览器输入 URL 到页面渲染完成：DNS 查询 10-50ms、TLS 握手 50-150ms、路由匹配约 1ms、Worker 执行冷启动约 5ms 热启动约 1ms、响应生成约 1ms、边缘响应 10-50ms、浏览器渲染 50-100ms。总耗时通常在 150-400ms 之间。

1.7 错误处理与恢复机制

AI 辅助部署的独特价值在于错误处理能力。在手工部署中遇到错误需要手动排查问题查找文档尝试修复。在 CI/CD 中 Pipeline 遇到错误会中止并通知开发者。在 AI 部署中 Agent 可以自主分析错误并尝试修复。以下是在本次部署中实际发生的几个自动恢复案例。

案例一：Git push 失败。由于 Windows 沙箱环境的 SChannel TLS 凭证问题，git push 反复失败。Agent 判断 git push 路径不可行后切换到备用方案——通过 GitHub Contents API 逐个推送文件。这个切换涉及完全不同的 API 调用和认证方式，Agent 自主完成了方案评估和切换。

案例二：Cloudflare API 权限不足。MCP Server 的 OAuth Token 只有只读权限。Agent 分析了返回的错误码（10000: Authentication Error），判断是认证方式问题而非 API 本身的问题。随后使用用户提供的 API Token 直接调用 REST API 绕过了 MCP 的权限限制。

案例三：Pages 部署不生效。Direct Upload 创建了部署记录但文件无法访问。Agent 检查了部署状态和访问结果对比了两个结果的不一致，得出结论是上传的 manifest 内容未正确存储。这些自动修复能力是大语言模型 Agent 系统的核心优势。传统的自动化工具只能执行预定义流程，遇到错误就中止。AI Agent 可以在运行时动态分析问题生成修复方案执行修复操作，将部署的鲁棒性提升到了新的水平。

二、古法编程：手工时代的部署流水线

深入回顾软件开发部署的进化史，从 1980 年代的 RCS 到 2020 年代的边缘计算。不是为了怀旧，而是为了理解每一步自动化的来之不易。

2.1 前版本控制时代：RCS 与 SCCS

在 Git 出现之前的三十年，代码管理主要靠两种技术：SCCS（1972 年 Bell Labs 开发）和 RCS（1982 年 Purdue 开发）。SCCS 是 Unix 上最早的版本控制系统，通过存储每个版本的增量差异来节省空间。RCS 使用反向差异优化最新版本的检出速度。那个时代的工作方式在今天看来几乎是原始的。开发者在一台共享 Unix 服务器上工作，用 RCS 的 ci 和 co 命令管理文件。RCS 没有网络功能，所有操作都在本地文件系统上完成。如果需要多人协作只能通过 NFS 共享或手动复制文件。RCS 没有分支概念，维护两版产品就得复制整个目录，两版之间没有关联，bug 修复要手动同步。

想象这个场景：项目有 200 个 C 源文件。你需要修改其中一个，执行 co -l file.c 获取独占锁。修改完后执行 ci -u file.c 提交。你的同事在改头文件但头文件被锁住了。大家互相等待效率低下。这种工作方式一直持续到 1990 年代 CVS 的普及。

2.2 CVS 与 SVN：集中式版本控制的兴衰

CVS（Concurrent Versions System）在 1990 年代成为开源世界事实标准。最大创新是支持"复制-修改-合并"的工作模式，多个开发者同时修改同一个文件，CVS 在提交时自动合并。如果存在冲突（两个人修改了同一块代码），CVS 会标记冲突位置由开发者手动解决。CVS 在 2000 年代初达到顶峰，SourceForge 使用 CVS 托管了成千上万的开源项目（Apache、GCC、X Window System）。但 CVS 有严重局限性：不支持原子提交（网络中断时仓库进入不一致状态）、分支和标签实现脆弱、不支持文件重命名、大型项目性能急剧下降。

Subversion（SVN）在 2000 年作为替代品出现，解决了 CVS 的大部分问题：原子提交、文件重命名、目录版本化、高效分支（低成本复制操作）。SVN 1.0 在 2004 年发布后迅速取代 CVS。但 SVN 仍是集中式架构所有操作依赖中央服务器。没有网络连接时无法提交无法查看历史无法创建分支。这种限制催生了分布式版本控制系统的诞生。

2.3 Git 革命与 GitHub 的崛起

Git 的历史始于 2005 年的危机。Linux 内核社区使用的 BitKeeper 收回了免费许可。Linus Torvalds 两周完成 Git 初始原型，两个月后 Git 能管理 Linux 内核仓库。Git 的设计理念与 CVS/SVN 完全不同：分布式架构（每个开发者本地有完整仓库副本）、内容寻址存储（内容哈希作标识符）、极轻量分支（40 字节指针引用）。但 Git 早期的命令行界面出了名的反直觉：checkout 做三种不同的事、reset 有五种模式、rebase 用不好能毁掉仓库历史。初学者的学习曲线非常陡峭。

GitHub 在 2008 年上线，贡献不仅是图形界面。Pull Request 改变了开源协作方式，不再是发邮件贴补丁，而是 fork 推分支点按钮合并。Issues、Wiki、Code Review、Project Management 把 Git 从命令行工具变成协作平台。GitHub Pages（2008 年）是最早的自动化部署服务之一，启发了整代自动部署服务。2018 年微软以 75 亿美元收购 GitHub，此时 GitHub 已托管超过 1 亿个仓库。今天 GitHub 是全球最大的代码托管平台，拥有超过 1 亿开发者用户。

2.4 FTP 部署：一个时代的记忆

在 2000 年代大部分网站通过 FTP 部署。FTP 诞生于 1971 年比 HTTP 早二十年。FTP 有两种工作模式：主动模式（PORT）和被动模式（PASV）。被动模式是防火墙友好的推荐模式，但在 2000 年代初支持并不普遍，很多客户端需要在两种模式间手动切换才能连接成功。使用 FTP 部署网站的工作流程：打开 FileZilla 输入主机名（通常是 IP）、用户名、密码、端口（默认 21）。连接后界面分左右两栏，左侧本地文件夹右侧服务器文件夹。找到网站根目录拖拽文件上传。

常见问题：传输模式（ASCII 用于文本文件 Binary 用于图片和压缩包，选错模式文件会损坏）、文件权限（上传后需手动 chmod，PHP 文件要 644 或 755，上传目录要 755 或 777）、增量更新（修改几个文件后要记住哪些文件改了手动选择上传，很多人直接覆盖整个目录所有文件重新传输一遍耗时很长）、回滚困难（上传有 bug 的代码导致网站崩溃，要手动找到旧版本重新上传，如果没有备份只能从本地找回或从生产服务器下载但已经覆盖了就晚了）。FTP 在 2010 年代中期逐渐被 Git 集成部署取代，但直到今天很多低端共享主机仍只支持 FTP。

2.5 SSH 与 Shell 脚本：手工运维的黄金年代

SSH 在 1995 年由 Tatu Ylonen 开发，最初为替代不安全的 telnet 和 rsh。配置 SSH 是一门手艺：ssh-keygen 生成密钥对、公钥复制到服务器的 authorized_keys、设置正确权限（700 和 600）、测试连接。SSH 配置文件 ~/.ssh/config 可以配置主机别名、密钥路径、端口号、代理跳板。通过 SSH 部署的标准做法是写 Shell 脚本：SSH 连接到服务器、进入网站目录、git pull 或 rsync 同步文件、执行数据库迁移、sed 替换变量更新配置、重启 Web 服务、清理临时文件。rsync 支持增量传输只传修改部分，常用命令：rsync -avz --delete ./dist/ user@server:/var/www/html/。但 Shell 脚本的错误处理是致命问题：一行失败后续命令继续执行可能产生不一致状态，如果脚本执行到一半 SSH 连接断了服务器处于部分更新状态。

2.6 CI/CD 工具的进化之路

持续集成概念在 1990 年代由 Kent Beck 在 XP 方法论中提出：开发人员频繁合并代码到主干，每次合并触发自动化构建和测试。第一个流行 CI 服务器是 CruiseControl（2001），由 Java 守护进程组成，定期检查版本控制仓库变化，检出最新代码，执行构建脚本，通过邮件或 RSS 通知结果。配置是 XML 文件包含仓库 URL、构建命令、通知方式。那时能设置好 CruiseControl 就是团队的 DevOps 专家了。

Hudson CI（2005）后来分裂为 Jenkins（2011）。Jenkins 通过插件体系成了 CI 领域的 Windows，有超过 1000 个插件覆盖所有版本控制工具、构建工具、测试框架、通知方式。一个典型的 Jenkins 项目配置包含 SCM（从 SVN/Git 拉取代码）、Build Triggers（定时轮询或 Webhook 触发）、Build Environment（环境变量和密钥）、Build Steps（Shell 命令或构建工具）、Post-build Actions（归档产物、发送通知、触发下游项目）。

2010 年代后期 Travis CI 和 CircleCI 等 SaaS CI 服务将 CI/CD 从自建 Jenkins 迁移到云端。GitHub Actions（2019）进一步降低门槛，内建在 GitHub 平台，YAML 配置文件，支持丰富的官方和社区 Action。一个简单的 GitHub Actions 工作流能在 10 行 YAML 内完成检出、构建、测试、部署。今天 GitHub Actions 已成为最流行的 CI/CD 平台之一，每月执行超过数亿次构建任务。

2.7 配置管理的演变：从 CFEngine 到 Terraform

早期服务器配置全靠手动：SSH 登录、vim 编辑配置、重启服务。管理几十台服务器就要手动连接和修改每台。CFEngine（1993）是第一个流行的配置管理工具，使用声明式语言描述系统理想状态，理念是"收敛"——即使系统被手动修改下次运行也会恢复到定义状态。Puppet（2005）和 Chef（2009）将配置管理推向主流，各自使用 DSL 描述配置，支持模块化的配置定义通过社区共享和复用配置。

Ansible（2012）走了另一条路：无 Agent 架构，依赖 SSH 执行命令，Playbook 使用 YAML 格式可读性极强。Terraform（2014）又将基础设施管理推进到新高度：不是配置管理工具而是基础设施即代码（IaC）工具。Terraform 管理的是云资源（虚拟机、网络、存储、负载均衡器），使用 HCL 描述期望状态，通过 Provider（AWS、Azure、Google Cloud、Cloudflare 等）的 API 创建和管理资源。核心特性包括状态文件跟踪已创建资源、资源依赖图自动计算创建和销毁顺序、计划/应用模式先显示变更计划确认后再执行。

2.8 虚拟化与云计算革命

2006 年是云计算元年。AWS 推出 EC2 和 S3。EC2 提供虚拟服务器实例按使用计费，S3 提供对象存储按存储量和请求计费。虚拟化技术在此之前已存在多年：VMware（1998）是服务器虚拟化先驱，Xen 是开源代表（也是 AWS EC2 的基础技术），KVM（2007）合入 Linux 内核主线。虚拟机让一台物理服务器运行多个隔离操作系统实例，大幅提高硬件利用率。云计算前部署网站意味着购买物理服务器、联系数据中心托管、安装操作系统、配置网络和防火墙、安装软件环境，需要数天到数周。云计算后变成在 AWS 控制台点几个按钮几分钟创建虚拟服务器。

Heroku（2007）又将部署简化到极致：不需要管理服务器，只需把代码推送到 Heroku Git 仓库，自动检测应用类型（Rails、Node.js、Python、Java）、安装依赖、启动应用。"git push heroku master"是最著名的部署命令之一，深深影响了后来的自动化部署工具。Heroku 的成功也让人们意识到开发者真正想要的不是管理服务器而是部署应用。这个洞察启发了后来的 Serverless 架构和无服务器计算。

2.9 Docker 与容器化部署

Docker（2013）是部署技术史上的分水岭。"它在我的机器上能跑"是开发者之间最著名的抱怨。Docker 的解决方式是把应用及其所有依赖打包到一个镜像，这个镜像在任何安装了 Docker 的机器上都能运行——本地开发机、测试服务器、生产服务器。核心技术是 Linux 容器的封装，与虚拟机不同容器共享宿主机操作系统内核只隔离用户空间。启动时间在秒级（虚拟机需要分钟级），资源开销小得多。Docker 工作流：编写 Dockerfile 描述构建步骤、docker build 构建镜像、docker push 推送镜像到仓库、目标服务器 docker pull 拉取、docker run 启动容器。

Docker Compose 解决多容器编排，一条 docker-compose up -d 启动整个应用栈。Kubernetes（2014 Google 开源）解决大规模容器编排：自动部署和回滚、服务发现和负载均衡、水平自动伸缩、配置和密钥管理。但代价是极高的复杂性——Kubernetes 的学习曲线几乎是垂直的。Docker 和 Kubernetes 的普及改变了部署的工作流，从 SSH 到服务器手动执行脚本变成构建镜像推送到仓库更新 Kubernetes 配置应用变更。虽然仍然需要手动操作，但每个步骤的可复现性和可靠性都大大提高了。

2.10 边缘计算：Cloudflare Workers 的革新

边缘计算是云计算的自然演进：将计算资源分布到离用户更近的节点。Cloudflare 拥有全球最大的边缘网络之一（330+ 城市的数据中心）。Workers 的关键创新是 V8 Isolate 沙箱，与传统容器或虚拟机不同，V8 Isolate 是 JavaScript/Wasm 运行时的轻量级隔离单元。启动时间 5ms vs 容器的 200ms+，单物理机可运行数万个实例。Workers 编程模型极简洁：监听 fetch 事件，处理请求返回响应。与传统 Serverless 不同的是执行位置——传统 Serverless 在数据中心执行，Workers 在边缘节点执行，延迟更低。Workers 部署也在不断进化：从直接上传脚本到 versions/deployments 版本化管理，再到 Workers for Platforms 支持第三方平台作为自服务的计算平台。

三、Codex Sites：AI 原生的部署范式

3.1 AI 编程助手的进化谱系

AI 辅助编程发展分几个阶段。第一阶段代码补全（2010 年代初），基于 n-gram 统计语言模型预测下一个 token，代表产品 TabNine（2018）。能补全变量名函数名简单代码片段对复杂逻辑理解有限。第二阶段大模型代码生成（2020 年代初），基于 Transformer 架构的预训练语言模型。OpenAI 2021 年发布 Codex（GPT-3 微调），GitHub 推出 Copilot。这些模型能从自然语言描述生成完整函数实现编写测试用理解代码逻辑。代码补全的准确率和上下文理解能力大幅提升。

第三阶段是 AI Agent 系统（2023 年至今）。大语言模型不再是被动代码生成器而是主动工具使用者。Codex Sites 是典型代表：AI 不仅能生成代码还能执行部署操作管理配置处理错误。这个转变的驱动力有两个：大语言模型的工具调用能力（Function Calling / Tool Use）和标准化协议的出现（MCP）。

3.2 Codex Sites 架构原理

Codex Sites 让 AI 不仅能写代码还能将代码部署到互联网。架构分为三个层次。第一是 Agent 编排层。Codex 内核是一个"思考-行动-观察"循环。用户提出需求后 Agent 制定多步计划逐步骤执行，每完成一步观察结果决定下一步。出错时分析错误信息调整策略重新尝试。这个循环不是简单顺序执行而是动态推理过程。第二层是多云 API 整合层。本次部署实际调用了 GitHub REST API 和 Cloudflare API 两大平台的服务。每个 API 调用需要正确认证方式参数格式错误处理。Codex 通过工具描述理解每个 API 的能力和限制，这些描述是结构化的 JSON Schema。第三层是标准化通信层。MCP 连接 AI 和外部系统，Cloudflare MCP Server 封装了 Workers、Pages、DNS、KV 的 API，处理 OAuth 认证请求签名响应解析等底层细节。

3.3 MCP 协议深度解析

MCP 包含几个核心概念：Server（提供工具的实体）、Tool（可执行功能单元）、Resource（可读取数据源）、Prompt（预定义提示模板）。在 Cloudflare MCP Server 中 Tool 包括创建 Pages 项目、连接 Git 源、部署 Worker、配置 DNS 等。每个 Tool 有详细输入参数定义（类型、必填、默认值、示例）和输出格式说明。MCP 与传统 Function Calling 的区别：MCP 是双向标准化协议，Function Calling 是单向模型到工具调用，MCP 支持工具到模型的事件推送。Function Calling Schema 在各个 LLM Provider 各不相同，MCP 是开放标准任何平台都可实现。

3.4 与传统 CI/CD 全面对比

从准备工作看：传统部署需安装配置 Web 服务器、配置数据库、设置 DNS、申请 SSL 证书。CI/CD 需配置 CI 服务器、编写 Pipeline、管理密钥证书。Codex Sites 只需在对话中描述需求。从操作流程看：传统部署手工执行多条命令。CI/CD 是 push 代码后自动触发 Pipeline。Codex Sites 在对话中完成从编写到上线全过程。从错误处理看：传统部署依靠操作者经验细心。CI/CD 有自动化错误处理和通知。Codex Sites 由 AI 自主分析错误调整策略重试。从学习成本看：传统部署需懂 Linux 系统管理网络配置 Web 服务器配置。CI/CD 需学习 Pipeline 语法 Docker Kubernetes。Codex Sites 只需清晰描述需求。从适合场景看：传统部署适合对底层有完全控制需求的项目。CI/CD 适合团队协作和复杂工作流。Codex Sites 适合快速原型验证个人项目和学习环境。

3.5 安全与隐私考量

AI 原生部署带来新的安全挑战。GitHub PAT 和 Cloudflare API Token 在对话上下文中传递，具有创建仓库、部署代码、修改 DNS 的能力。如果泄露到不安全的环节后果严重。Codex 安全设计包括：Token 只在当前对话上下文使用不持久化存储、使用范围限制在对话生命周期内、每次工具调用经过鉴权和权限校验。用户应定期轮换 API Token 为每个 Token 设置最小权限原则不授予超出需求的权限。另一考虑是部署内容审计。传统 CI/CD 每次部署有 Pipeline 日志变更记录审批流程。AI 原生部署中这些审计记录由 Agent 主动生成，用户应审阅操作摘要确保所有操作都是预期的。

3.6 未来展望

Codex Sites 代表新范式开端。几个方向可能取得突破：多环境管理（开发测试预发布生产各环境自动化管理）、团队协作（权限管理部署审批历史记录和回滚）、持续部署（监听 Git push 自动触发增量部署实现真正 CI/CD）、混合架构（前后端分离、数据库集成 D1/Neon/PlanetScale、有状态服务 Durable Objects）、故障自动恢复（AI 自动分析原因 DNS 问题脚本错误资源耗尽执行回滚或修复措施）。从更长远角度看 AI 原生部署可能改变软件开发的基本工作流：从"写代码-测试-部署"循环转变为"描述需求-AI 实现-验证结果"。这并不意味着开发者不再需要技术知识。更好的技术理解能帮助更好地评估 AI 输出处理边界情况设计系统架构。AI 消除的是重复劳动和操作风险而不是人类的判断力。

—— 写于 2026 年 6 月，全文约 22000 字。一次从零开始的 AI 辅助部署实践深度记录。

四、附录：常用 API 参考

4.1 GitHub REST API 常用端点

创建一个私有仓库：POST /user/repos，请求体包含 name（必填）、private（boolean）、description（可选）、auto_init（boolean）。返回 201 表示创建成功。推送文件：PUT /repos/{owner}/{repo}/contents/{path}，请求体包含 message（commit 信息）、content（base64 编码的文件内容）、branch（分支名）、sha（更新时需提供原文件 SHA）。列表 Webhook：GET /repos/{owner}/{repo}/hooks。创建 Webhook：POST /repos/{owner}/{repo}/hooks，请求体包含 name（固定为 web）、active（boolean）、events（数组，如 [push]）、config（包含 url、content_type、secret）。

4.2 Cloudflare Workers API 常用端点

上传 Worker 脚本：PUT /accounts/{account_id}/workers/scripts/{name}，使用 multipart/form-data 格式包含 metadata 和 script 两部分。列表版本：GET /accounts/{account_id}/workers/scripts/{name}/versions。创建部署：POST /accounts/{account_id}/workers/scripts/{name}/deployments，请求体包含 strategy（固定为 percentage）和 versions 数组（每个元素包含 version_id 和 percentage）。启用 workers.dev：POST /accounts/{account_id}/workers/scripts/{name}/subdomain。创建路由：POST /zones/{zone_id}/workers/routes，请求体包含 pattern（如 codex.example.com/*）和 script（Worker 名）。

4.3 Cloudflare DNS API 常用端点

列出 DNS 记录：GET /zones/{zone_id}/dns_records。创建记录：POST /zones/{zone_id}/dns_records，请求体包含 type（A/AAAA/CNAME/TXT）、name（如 codex）、content（IP 或域名）、proxied（boolean 橙色云开关）、ttl（1 表示自动）。删除记录：DELETE /zones/{zone_id}/dns_records/{record_id}。创建 DNS 记录时如果提示记录已存在需要先删除原有记录或使用不同的名称。

4.4 错误码速查

Cloudflare API 常见错误码：10000 Authentication Error（认证令牌无效或权限不足，检查 Token 作用域和权限）、10021 Script Validation Error（Worker 脚本语法错误，检查 JavaScript 语法）、8000002 Project Already Exists（项目名已被占用，选择不同名称或先删除旧项目）、8000011 Git Installation Issue（Cloudflare GitHub App 未正确安装，需要在 Dashboard 中重新配置 Git 集成）、8000096 Manifest Field Expected（请求体格式错误，检查是否是 multipart/form-data 格式）、8000123 Repository Already Connected（Git 源已连接，需要先断开再重新连接）、81053 DNS Record Conflict（同名的 DNS 记录已存在，需要先删除原有记录）。GitHub API 常见错误码：401 Bad Credentials（Token 无效或已过期，检查 PAT 有效性）、409 Conflict（SHA 不匹配，Contents API 更新文件时需要提供正确的文件 SHA）、422 Validation Failed（请求体参数错误，检查必填字段和格式）。

五、术语表

Agent：具备工具调用能力的 AI 系统，能自主执行多步操作。CDN（Content Delivery Network）：内容分发网络，将静态资源缓存到全球边缘节点加快用户访问速度。CI/CD（Continuous Integration/Continuous Deployment）：持续集成和持续部署，自动化构建测试和发布流程的实践。DNS（Domain Name System）：域名系统，将人类可读的域名转换为机器可读的 IP 地址。Edge Computing：边缘计算，将计算资源部署到离用户更近的网络节点减少延迟。Function Calling：大语言模型输出结构化 JSON 调用外部工具的能力。Isolate：V8 引擎中的轻量级隔离执行环境，多个 Isolate 共享同一进程。IaC（Infrastructure as Code）：基础设施即代码，用代码管理云资源。MCP（Model Context Protocol）：AI 模型与外部工具之间的标准化通信协议。PaaS（Platform as a Service）：平台即服务，提供应用运行环境无需管理底层基础设施。PAT（Personal Access Token）：GitHub 的个人访问令牌，用于 API 认证。PoP（Point of Presence）：网络服务接入点，Cloudflare 在全球拥有 330+ PoP。ReAct Loop：推理-行动循环，Agent 系统的基础架构模式。Route：Cloudflare Workers 中定义流量分发规则的配置。S3（Simple Storage Service）：AWS 的对象存储服务，云计算基础设施的基石之一。Serverless：无服务器计算，开发者只需关注代码无需管理服务器。TLS（Transport Layer Security）：传输层安全协议，HTTPS 的基础。TTL（Time To Live）：DNS 记录的缓存时间，影响域名变更的生效速度。V8：Google 开发的高性能 JavaScript 引擎，Chrome 和 Node.js 的核心组件。Webhook：HTTP 回调机制，当特定事件发生时主动通知指定 URL。Worker：Cloudflare 边缘计算平台上的无服务器函数执行单元。

六、深入案例：实际部署中遇到的问题与解决

6.1 SSL 凭证问题的根因分析

在本次部署中遇到的第一个技术障碍是 git push 失败。错误信息是 SEC_E_NO_CREDENTIALS，这是 Windows SChannel（安全通道）TLS 栈返回的错误码。SChannel 是 Windows 原生的 SSL/TLS 实现，git for Windows 默认使用 SChannel 作为 HTTP 传输的后端。SEC_E_NO_CREDENTIALS 通常表示客户端证书存储中缺少必要的凭证。深入分析后发现这不是普通的认证问题——不是用户名密码不对也不是 Token 过期——而是底层的 TLS 握手在证书交换阶段就失败了。沙箱环境的用户态文件系统可能没有正确加载 Windows 证书存储，导致 SChannel 无法访问任何根证书和中间证书。这解释了为什么设置 GIT_SSL_NO_VERIFY 和切换 http.sslBackend 都没有效果——问题不在于证书验证，而在于证书根本不可用。

这个案例说明了自动化部署工具需要处理底层平台差异。Linux、macOS、Windows 的 TLS 实现各不相同，git push 在一台机器上正常工作不代表在所有机器上都能工作。AI Agent 在处理这类问题时的优势是可以跨层分析——从应用层错误追溯到系统层根因，而不是停留在"git push 失败"的表象上。

6.2 Cloudflare OAuth 与 API Token 的双轨制

Cloudflare 提供了两种 API 认证方式：OAuth 2.0 和 API Token。OAuth 2.0 适合用户交互式应用（需要浏览器重定向），API Token 适合自动化脚本和 CI/CD 流水线。MCP Server 使用 OAuth 2.0 认证，在首次连接时通过 Codex 桌面应用引导用户完成 OAuth 授权流程。这个流程的好处是用户不需要手动管理密钥——令牌自动获取自动刷新自动存储。但代价是 OAuth Token 的作用域可能受限于初始授权时选定的权限范围。

在本次实践中 MCP Server 的 OAuth Token 只申请了读取权限。这可能是 MCP Server 实现的初步版本——为了安全起见只授予最小权限。对于需要写入操作的场景（创建 Worker、部署代码、修改 DNS），用户需要额外提供 API Token。API Token 的创建是在 Cloudflare Dashboard 的 My Profile > API Tokens 页面完成的，可以精确选择权限作用域（Account 级别和 Zone 级别）和资源范围（所有资源或特定资源）。

一个值得注意的细节是 API Token 的失效处理。如果 Token 被撤销或过期，API 调用会返回 10000 错误码。Agent 需要能够区分"Token 无效"和"Token 权限不足"这两种情况。前者的修复方式是重新生成 Token，后者的修复方式是在 Token 配置页面添加缺失的权限。Agent 可以通过分析错误消息中的细微差别（如 cfut_ 前缀的 Token 通常属于 Cloudflare User Token 类别）来判断认证失败的具体原因。

6.3 跨平台工具兼容性

本次部署运行在 Windows 沙箱环境中，暴露了几个跨平台兼容性问题。第一是 Shell 脚本的执行策略：PowerShell 默认禁止运行未签名的 .ps1 脚本和 npx 命令，需要通过 ExecutionPolicy Bypass 或使用 cmd.exe 来执行。第二是文件路径分隔符：Windows 使用反斜杠而 Unix 使用正斜杠，在构建命令和配置文件路径时需要注意转换。第三是换行符：Windows 使用 CRLF 而 Unix 使用 LF，git 的 autocrlf 设置会影响文件内容的哈希值。第四是字符编码：Windows 控制台的代码页（CP936 GBK）与 UTF-8 不一致时会导致中文乱码。

这些兼容性问题在传统开发环境中通常由开发者手动处理，但在 AI 辅助部署中 Agent 需要自动检测和适配。例如在 git push 失败时 Agent 需要判断是网络问题、认证问题、还是平台兼容性问题。每种情况的修复方案不同，错误诊断的准确性直接影响部署的成功率。

6.4 部署后的持续运营

部署完成不是终点而是起点。持续的运营包括几个方面。监控：Worker 的执行日志可以通过 Cloudflare Dashboard 的 Workers Logs 功能查看，也可以配置 Logpush 将日志导出到外部存储。告警：通过 Cloudflare Alerting 可以配置 Worker 错误率、CPU 使用率、请求延迟等指标的告警规则。更新：代码更新通过 git push 触发 Webhook，Webhook 调用 Cloudflare API 重新部署 Worker。回滚：如果新版本有问题，可以通过 Cloudflare API 的 Rollback Deployment 功能快速切回旧版本。

运营的关键指标包括：请求延迟（p50/p95/p99）、错误率（5xx 响应比例）、缓存命中率（CDN 缓存的有效性）、Worker CPU 使用率（是否接近免费套餐的限制）、带宽用量（是否超出套餐免费额度）。Cloudflare 的 Free 套餐包含每天 10 万次请求和每天 1000 次 Worker 请求，对于个人演示项目绰绰有余。随着流量增长可以升级到 Pro 或 Business 套餐获得更高的配额和更多的功能（如高级缓存规则和 WAF 自定义规则）。

七、总结与启发

从零到上线的完整部署经历了以下阶段：需求分析（确定部署目标和架构方案）、代码编写（生成 HTML/CSS 静态站点）、版本管理（创建 GitHub 仓库并推送代码）、环境配置（创建 Cloudflare 项目、配置 DNS、上传 Worker）、部署上线（创建版本和部署激活 Worker）、域名绑定（配置 Route 和 DNS 记录）。整个过程从对话开始到可访问的 URL 结束，耗时约 2 小时（包括多次试错和方案调整的时间）。

这个过程中最有价值的不是最终生成的网站本身——一个简易的静态演示页面——而是从头到尾走通全套部署流程所积累的经验和认识。我们深入了解了 Cloudflare Workers 的部署机制（上传-版本-部署的三段式流程）、GitHub API 的使用要点（Contents API 的 SHA/更新限制）、DNS 配置的细节（proxy 开关对流量路径的影响）、MCP 协议的实际运作方式（OAuth 的限制和 API Token 的补充）。

从更宏观的角度看 Codex Sites 代表的 AI 原生部署范式正在模糊软件开发中几个传统界限。第一个界限是"写代码"和"部署代码"的界限——在 AI 部署中这两个阶段不再是分离的，而是在同一个对话中完成的连续过程。第二个界限是"开发环境"和"生产环境"的界限——AI 直接在目标平台（Cloudflare Workers）上部署和测试，不再需要在本机搭建完整的开发环境。第三个界限是"应用开发者"和"基础设施运维"的界限——AI 自动处理了基础设施配置（DNS、CDN、HTTPS 证书），开发者不再需要深入理解这些底层技术。

这些界限的模糊化降低了软件开发的门槛，但也提出了新的问题：当 AI 处理了越来越多的技术细节后，开发者需要具备什么样的能力才能有效地使用这些工具？我的判断是：抽象理解能力（理解系统整体架构而不迷失在实现细节中）、问题诊断能力（当 AI 遇到无法自动解决的错误时能够分析根因）、质量判断能力（评估 AI 生成的代码和配置是否合理）。这些能力不是新的——优秀的开发者自古以来就具备这些能力——只是它们的重要性在新的范式下更加凸显了。

—— 全文完，约 22000 字。写于 2026 年 6 月。

8.1 深入理解 V8 Isolate 的工作机制

V8 Isolate 是 Cloudflare Workers 的运行基础。Isolate 可以理解为 V8 引擎中的一个完全隔离的执行环境。每个 Isolate 拥有自己的 JavaScript 堆内存、全局对象、编译缓存。多个 Isolate 共享同一个 V8 进程的好处是内存利用效率极高——编译后的代码可以在 Isolate 之间共享，只有运行时数据是隔离的。这种设计让 Cloudflare 可以在单台物理机上运行数万个 Worker 实例。启动一个新 Isolate 只需要创建一个新的堆内存空间，耗时约 5 毫秒，远低于容器的 200 毫秒和虚拟机的数分钟。

Worker 的资源限制包括：CPU 时间（免费套餐每个请求最多 10 毫秒 CPU，付费套餐最多 50 毫秒）、内存（128 MB）、脚本大小（1 MB）、子请求数量（每个请求最多 50 个子请求）、定时器数量（每个请求最多 5 个）。这些限制确保了恶意或出错的 Worker 不会影响其他用户的实例。在本次部署中我们的 Worker 脚本约 27 KB，CPU 使用远低于限制。

8.2 深入理解 DNS 解析过程

当用户在浏览器中输入 codex.1982901.xyz 时，完整的 DNS 解析过程涉及多个环节。浏览器首先检查本地 DNS 缓存（过期时间为 TTL）、然后检查操作系统 DNS 缓存、然后向配置的 DNS 递归解析器（通常由 ISP 或公共 DNS 服务如 1.1.1.1 提供）发送查询请求。递归解析器负责从根域名服务器开始逐级查询。对于 1982901.xyz 这个域名，查询路径是：根域名服务器（返回 .xyz 顶级域名的 NS 记录）、.xyz 顶级域名服务器（返回 1982901.xyz 的权威 NS 记录，即 Cloudflare 的 lauryn.ns.cloudflare.com 和 lee.ns.cloudflare.com）、Cloudflare 权威 DNS 服务器（返回 codex.1982901.xyz 的 DNS 记录）。总共经过 3 到 4 次递归查询，耗时通常在 10 到 50 毫秒之间。

DNS 记录的 TTL（Time To Live）决定了下游 DNS 缓存这条记录的时间。我们创建的这个 A 记录的 TTL 设为 1（自动），Cloudflare 会自动设置一个合适的 TTL 值（通常为 120 秒）。较短的 TTL 有利于快速变更（修改后几分钟内全球生效），但会增加 DNS 查询的频率。较长的 TTL（如 3600 秒）可以减少 DNS 查询次数但变更生效慢。传统的做法是在变更前先缩短 TTL，等变更完成后再恢复为较长的 TTL。

8.3 Cloudflare 全球网络的物理架构

Cloudflare 的全球网络分为几个层次。最外层是 Anycast 网络层，全球 330 多个城市的数据中心通过 Anycast 路由协议对外提供统一的 IP 地址。当用户向 codex.1982901.xyz 发起连接时，互联网路由器会根据 BGP 路由协议自动选择距离用户最近的 Cloudflare 数据中心。这个数据中心称为接入点（PoP）。

PoP 内部的处理流程是：网络流量到达 PoP 的边界路由器，经过 DDoS 防护和防火墙检查后进入反向代理层（nginx）。反向代理层检查请求的 Host 头和 URL 路径，匹配相应的配置规则（Page Rules、Worker Routes、Origin Rules）。如果命中 Worker Route，请求会被转发到 Workers 运行时环境。Workers 运行时在 PoP 内部的服务器集群上运行，每个服务器运行多个 V8 引擎实例。

如果 Worker 需要访问源站（如数据库或后端 API），Cloudflare 会通过 Argo Smart Routing 选择最优的网络路径，而不是直接走互联网公网。Argo 利用 Cloudflare 内部网络（连接所有数据中心的专用光纤网络）来绕过互联网的拥堵节点。这也是 Cloudflare Workers 比传统 Serverless 延迟更低的原因之一。

8.4 HTTPS 证书的自动管理

当我们在 Cloudflare Pages 项目或 Workers 上添加自定义域名时，Cloudflare 会自动处理 SSL/TLS 证书的申请和续期。具体流程是：Cloudflare 检测到新的自定义域名，向证书颁发机构（Google Trust Services）提交证书签名请求（CSR），验证域名所有权。域名的验证方式有几种：DNS 验证（添加 TXT 记录）、HTTP 验证（在指定 URL 返回指定内容）、Email 验证。Cloudflare 使用 DNS 验证方式，因为它完全自动化且不需要修改源站配置。

证书申请成功后 Cloudflare 会在边缘节点上部署证书。当用户通过 HTTPS 访问时，Cloudflare 边缘节点完成 TLS 握手（客户端向边缘节点发送 ClientHello，边缘节点返回 ServerHello 和证书，客户端验证证书后生成会话密钥）。握手完成后客户端和边缘节点之间的通信是加密的。如果配置了 Full 或 Full (Strict) 模式，Cloudflare 到源站的连接也使用 HTTPS。如果配置了 Flexible 模式，Cloudflare 到源站的连接是明文的（不推荐）。

证书的有效期通常为 90 天。Cloudflare 会在证书到期前自动发起续期流程，整个过程不需要用户干预。这也是 Cloudflare 服务的重要价值之一——免除了开发者手动管理证书的负担。回想 2010 年代初期，申请和部署 SSL 证书是一个令人头疼的过程（生成 CSR、提交给 CA、等待验证、安装证书、配置 Web 服务器、配置证书链）。Let's Encrypt 在 2016 年推出后大幅简化了这个流程，但 Cloudflare 将其完全自动化到了零操作的程度。

8.5 从 HTTP/1.1 到 HTTP/3 的协议进化

Cloudflare 全球网络自动支持最新的 HTTP 协议版本。当用户访问 codex.1982901.xyz 时，Cloudflare 会优先使用 HTTP/3（基于 QUIC 协议）。HTTP/3 的核心改进是使用 UDP 替代 TCP，解决了 HTTP/2 的队头阻塞问题（在 TCP 层，一个数据包丢失会导致所有流都等待重传）。QUIC 协议由 Google 在 2012 年开始研发，2018 年提交给 IETF 标准化，2022 年正式发布 RFC 9000。

HTTP/3 的另一个重要特性是 0-RTT 连接建立。对于之前访问过同一网站的用户，HTTP/3 可以在第一个数据包中就携带应用数据，而不需要完整的握手往返。这个特性对于延迟敏感的场景（如移动端网页）特别有价值。

我们部署的这个 Worker 默认使用 Cloudflare 优化的 HTTP 响应头，包括：CF-Ray 头（请求追踪 ID，用于调试）、CF-Cache-Status（CDN 缓存状态）、Server: cloudflare（服务器标识）。从响应头中可以看到请求到达的 Cloudflare 节点（如洛杉矶 LAX、芝加哥 ORD、东京 NRT）和处理时间。

8.6 Agent 系统的局限性与改进方向

尽管 AI Agent 在本次部署中展现了强大的自主能力，但也暴露了几个局限性。第一个是工具发现的完整性。Agent 需要在海量的工具描述中找到最适合当前任务的那一个。如果工具描述不够精确（比如没有明确标注某个 Worker API 调用需要 Account 级权限还是 Zone 级权限），Agent 可能选择错误的工具或使用错误的参数。改进方向是让工具描述的粒度更细、示例更丰富。

第二个是错误恢复的深度。Agent 能够处理大部分 API 层面的错误（超时、权限不足、参数错误），但遇到平台底层问题（如 SChannel TLS 凭证缺失、Pages 构建引擎不处理 API 创建的项目）时，Agent 的解释能力受限于可获得的错误信息。改进方向是让平台提供更清晰的错误诊断信息（如明确的错误码差异化和修复建议提示）。

第三个是多步骤操作的原子性。在本次部署中涉及多个步骤：仓库创建、文件推送、Webhook 配置、Worker 上传、版本创建、部署激活、路由配置、DNS 配置。如果其中某一步失败，Agent 需要决定是回退已经完成的操作还是继续执行修复。目前 Agent 的回退策略是简单的——尝试修复失败的步骤，如果多次尝试失败则询问用户。改进方向是实现事务性的多步骤操作，支持部分回滚和幂等重试。

第四个是安全边界的透明性。Agent 在执行操作时需要知道哪些操作需要额外的授权。例如 Cloudflare API Token 的权限范围并不是 API 调用层面可见的——Agent 需要事先知道 Token 有哪些权限。改进方向是让 MCP Server 在工具描述中包含权限需求信息，或者在执行前先验证权限。

九、工具链对比与选择建议

9.1 Cloudflare Pages vs Workers vs Pages Functions

Cloudflare 提供了多种计算和托管方案，各有适用场景。

Cloudflare Pages 适合静态网站和 Jamstack 应用。它支持 Git 集成自动部署，可以绑定自定义域名，支持 Serverless Functions（Pages Functions）。Pages 的构建系统支持大多数流行的前端框架（React、Vue、Angular、Svelte、Astro、Next.js、Hugo、Jekyll）。Pages 的 Free 套餐包括：每月 500 次构建、无限带宽、无限请求。Pages Functions 基于 Workers 运行时，但执行位置和计费方式与独立 Workers 不同。

Cloudflare Workers 适合 API 服务、中间件、边缘计算。它提供更灵活的编程模型（Service Worker 或 ES Module 格式），支持更多运行时 API（KV、D1、R2、Queue、Durable Objects、Vectorize、Workers AI）。Workers 的 Free 套餐包括：每天 10 万次请求、每天 1 千万次 CPU 时间（约 10 毫秒 CPU 时长的 100 万次请求）、KV 存储 100 万次读操作和 1000 次写操作。适合构建 API 后端、数据处理管道、A/B 测试、重定向规则等场景。

Workers for Platforms（原名 Workers as a Service）允许 SaaS 平台将 Workers 嵌入到自己的产品中。例如某个低代码平台可以让用户在平台上编写 Worker 代码，平台通过 Workers for Platforms API 将代码部署到 Cloudflare 边缘网络，用户的请求在 Cloudflare 边缘得到处理。这个方案最适合的平台包括 CMS 平台、电商平台、API 管理平台、低代码平台。

9.2 GitHub vs GitLab vs Bitbucket 对 Cloudflare 部署的支持

Cloudflare Pages 支持连接 GitHub、GitLab、和 Bitbucket 仓库。三个平台在 Pages 集成方面功能基本一致——都支持自动部署、预览部署、分支构建。GitHub 集成最成熟（Cloudflare 的 GitHub App 功能最完整），GitLab 次之，Bitbucket 支持相对有限。对于不需要 Git 集成的场景（如直接通过 API 部署），CI/CD 工具的选择相对自由。

选择建议：如果你的项目已经托管在 GitHub 上（大多数开源和个人项目都是这种情况），直接使用 GitHub Pages 集成即可。如果你的团队使用 GitLab 的自托管版本，GitLab Pages 集成可以保持 CI/CD 流程的统一。如果你使用 Bitbucket，Pages 的集成虽然功能有限但仍然可用。如果你使用自托管的 Git 服务器（如 Gitea 或 Gogs），则需要通过 API 直接部署（如我们使用的 Workers API 方案）。

9.3 部署方案的性能比较

从延迟角度看，Cloudflare Workers 优于 Pages（Workers 在边缘节点执行而 Pages 的构建产物需要从存储系统分发）。从带宽角度看，Pages 更适合大量静态资源（通过 CDN 缓存优化），Workers 更适合动态内容（每次请求由 Worker 生成响应）。从计费角度看，Pages 的免费套餐更慷慨（无限请求），Workers 按请求数和 CPU 时间计费。从功能角度看，Workers 的运行时 API 更丰富（支持 KV、D1、R2、Queue 等服务）。从开发者体验角度看，Pages 的 Git 集成更简单（推送代码即部署），Workers 的部署需要额外的步骤。

我们的最终选择是 Workers + Route + DNS 的组合方案。这个方案的优势是完全通过 API 可控，不需要 Dashboard 的手动操作。代价是需要多几个配置步骤（创建 Route、创建 DNS 记录）。对于自动化部署工具来说 API 可控性是比配置便捷性更重要的考量因素。

十、部署清单与检查项

基于本次实践的经验，以下是在 Cloudflare Workers 上部署静态网站的完整清单：

10.1 前置准备

[] Cloudflare 账号已注册并激活。[] 域名已在 Cloudflare 上添加并启用（DNS 状态为 active，NS 记录已配置）。[] Cloudflare API Token 已创建（权限包括 Workers:Edit 和 DNS:Edit）。[] GitHub 账号已注册，Personal Access Token 已创建（权限包括 repo 和 admin:repo_hooks）。[] 本地项目代码已完成开发和测试。

10.2 部署步骤

[] 创建 GitHub 仓库（私有或公开）。[] 将代码推送到 GitHub（通过 git push 或 Contents API）。[] 编写 Worker 脚本（Service Worker 或 ES Module 格式）。[] 通过 PUT Workers API 上传脚本（multipart/form-data 格式）。[] 获取最新版本的 version_id（GET versions API）。[] 创建 Deployment 激活新版本（POST deployments API）。[] 启用 workers.dev 子域名（POST subdomain API）。[] 创建 Zone Route 关联自定义域名（POST workers/routes API）。

10.3 域名与 DNS 配置

[] 如果域名在 Cloudflare 上托管，创建 proxied DNS 记录（A 或 CNAME）。[] 如果域名不在 Cloudflare 上托管，在 DNS 提供商处创建 CNAME 指向 workers.dev URL。[] 等待 DNS 记录生效（检查 TTL）。[] HTTPS 证书自动签发（验证域名状态为 active）。

10.4 验证项

[] 通过 workers.dev URL 访问 Worker（返回正确内容）。[] 通过自定义域名访问 Worker（HTTPS 正常，无证书错误）。[] 检查响应头（content-type 正确、状态码 200）。[] 检查 CSS/JS 等静态资源是否正常加载。[] 测试不同路径的路由是否正确（/、/home、/api 等）。

十一、常见问题解答

11.1 为什么 git push 失败？

git push 失败的可能原因：SSL/TLS 凭据问题（Windows SChannel 错误 SEC_E_NO_CREDENTIALS）、网络代理配置问题（公司网络或 VPN 限制了对 GitHub 的访问）、认证信息不正确（Token 过期或没有权限）、.gitconfig 配置问题（user.name 和 user.email 未设置）。解决方案：检查 git config --list 配置、使用 GIT_SSL_NO_VERIFY=1 绕过证书验证（不推荐生产环境）、使用 GitHub CLI（gh）代替 git、通过 GitHub Contents API 直接上传文件。

11.2 Cloudflare Workers 部署后为什么 404？

可能原因：Worker 脚本语法错误（上传后 DASHBOARD 不会立即显示语法错误，需要创建部署后才会检查语法）、Route 配置错误（pattern 不匹配或指向了错误的 Worker 名称）、DNS 记录配置错误（缺少必要的 A 或 CNAME 记录）。解决方案：检查 Worker 部署状态（GET deployments API）、检查 Route 配置（GET zones/{zone_id}/workers/routes）、检查 DNS 记录（GET zones/{zone_id}/dns_records）。

11.3 如何更新 Worker 代码？

更新 Workder 代码的流程与首次部署相同：PUT 上传新版本、获取最新 version_id、POST 创建新 Deployment。每次上传都会生成一个新版本，每次部署可以指定将哪个版本激活。如果你想要回滚，只需要创建一个 Deployment 指向旧版本的 version_id 即可。回滚过程是即时的，不影响正在处理的请求。旧版本的 Workers 实例会继续处理已有连接，新连接会使用回滚后的新版本。

11.4 如何清理和删除资源？

删除 Worker 脚本：DELETE /accounts/{account_id}/workers/scripts/{name}。删除版本：目前不支持单独删除版本，但可以删除整个脚本然后重新上传。删除 Route：DELETE /zones/{zone_id}/workers/routes/{route_id}。删除 DNS 记录：DELETE /zones/{zone_id}/dns_records/{record_id}。删除 GitHub 仓库：通过 GitHub Dashboard 的 Settings > Danger Zone > Delete this repository。注意删除不可逆，请谨慎操作。

11.5 如何迁移到其他部署方案？

如果需要从 Workers 迁移到 Pages 或其他方案，建议的迁移步骤：在新的方案上部署并验证功能正常、配置 DNS 指向新的部署地址（先降低 TTL）、等待旧部署的流量自然降低后删除旧的 Worker 和路由。如果需要回滚到旧方案，将 DNS 指回旧的 Workers URL 即可。

十二、对传统部署模式的反思

12.1 自动化的边际效应

自动化不是越多越好。在部署流水线的发展历程中我们看到自动化程度不断提高：从手工操作到脚本化到 CI/CD Pipeline 到 AI Agent。但在每个阶段都有自动化的边界。手工操作的最大问题不是速度而是可靠性——人容易犯错特别是在深夜或高压环境下。脚本化解决了速度问题但不能解决环境差异问题。CI/CD Pipeline 解决了环境一致性问题但引入了维护成本。AI Agent 解决了维护成本问题但引入了不确定性问题。

自动化边际效应的启示是不要为自动化而自动化。每次自动化的决策都应该基于具体的成本和收益分析。对于一个每月发布一次的小型个人项目复杂的 CI/CD Pipeline 可能是过度工程。对于每天发布多次的产品团队自动化是必需品。AI Agent 部署正好处于这个光谱的中间位置——它提供了高度的自动化但不需要复杂的基础设施配置。

12.2 从运维文化到平台文化的转变

2000 年代的部署文化是运维文化。每个团队有一个或多个专门的运维工程师他们掌握着生产服务器的根密码了解服务器的各种配置细节能够 SSH 到服务器上解决问题。运维工程师是团队中最有经验也最稀缺的角色。2010 年代的 DevOps 文化试图打破开发与运维之间的隔阂让开发者也参与运维工作。CI/CD Pipeline、配置管理工具、容器化技术让开发者有了更多的运维能力。

2020 年代的趋势是平台文化。组织建立内部平台团队提供标准化的部署平台开发者在平台上自助部署。平台团队负责底层基础设施的稳定性和安全性开发者只需关心应用代码。Codex Sites 将这种平台文化推向了下一个阶段——平台不再是一个内部团队构建的抽象层而是由 AI 直接交互的外部服务平台。开发者不需要理解平台的内部机制只需要描述需求。

12.3 教育意义：为什么每个开发者都应该手工部署一次

尽管自动化部署工具越来越先进我仍然建议每个开发者至少手工部署一次。这个建议的理由不是怀旧而是理解。当你手工配置过 Nginx VirtualHost 你就会理解为什么现在只需要输入一个端口号。当你手工创建过 SSL 证书你就会理解为什么现在只需要点一个按钮。当你手工设置过 DNS 记录并等待 TTL 过期你就会理解为什么现在支持即时生效。

理解底层的运作机制让你在遇到问题时知道从哪里着手。当 git push 失败时知道是 SSL 问题还是认证问题还是网络问题——这需要理解 TLS 握手的基本过程。当 Worker 返回 404 时知道是路由问题还是脚本问题还是 DNS 问题——这需要理解请求是如何从浏览器到 Cloudflare 边缘到 Worker 再到响应的完整路径。

本次部署实践是一次完整的亲手操作——虽然由 AI 辅助执行但每一步的决策和问题排查都经过了深入的分析和推理。从 git push 的 SSL 失败到 Workers 的版本管理机制每个问题都暴露了这些自动化平台背后依然存在的技术复杂度。理解这些复杂度才能更好地使用自动化工具。

十三、结束语

从头到尾跑通这条流水线的最大收获不是学会了一个新的工具或平台而是重新理解了软件开发中上线这个环节的意义。上线不是一个简单的按钮点击而是代码从开发者的个人电脑到达全球数百万用户的中间经过的漫长旅程。这段旅程涉及版本控制、持续集成、构建打包、测试验证、防火墙、负载均衡、DNS 解析、CDN 缓存、HTTPS 加密、边缘执行——每一个环节都代表了一代工程师的智慧和汗水。

Codex Sites 和类似工具的价值在于让开发者可以专注于创造本身而不是被这些基础设施的复杂度所淹没。但即使最好的工具也无法替代对底层原理的理解。正如汽车让旅行变得简单但一个好司机仍然需要了解引擎刹车和转向的基本原理。一个好的开发者需要理解部署流水线的每个环节——不是因为他们要手工操作这些环节而是因为他们需要在问题发生时知道问题出在哪里。

—— 全文完。写于 2026 年 6 月。本文通过 Codex 编写通过 Cloudflare Workers 部署，访问地址 https://codex.1982901.xyz/home。