用户部署指南

这套文档是写给第一次接触 ZShip、第一次部署 Cloudflare、甚至第一次碰 monorepo 的用户看的。

如果你只想知道一句话版流程，就是下面这 6 步：

1. 先准备好 Cloudflare 账号、本地 Node.js、pnpm、Wrangler。
2. 先打开 Dev Console，熟悉项目提供的图形化工具。
3. 在 Cloudflare 里先把需要的资源创建出来。
4. 先部署后端 Worker。
5. 再部署前端 Pages（只部署 web 和 admin）。
6. 最后绑定域名、补环境变量、登录后台完成初始化。

请严格按顺序看，不要跳步。

获取源码的两种方式

用户拿到这套模板，通常有两种做法：

方式 1：GitHub Fork

意思是：

• 用户直接在 GitHub 上把官方仓库 fork 到自己的账号或组织下面

优点：

• 还保留和官方仓库的上游关系
• 后续官方模板更新时，用户更容易手动同步
• 更适合你们这种”官方持续迭代模板，用户基于模板二次开发”的场景

缺点：

• 不会自动更新
• 官方仓库有新提交后，用户仍然需要自己手动同步
• 如果用户改动很多，后续同步时可能有冲突

方式 2：直接复制代码后自己新建仓库

意思是：

• 用户下载官方代码
• 然后自己重新创建一个全新的 Git 仓库

优点：

• 仓库历史更干净
• 对有些客户来说，心理上更像”这已经是我自己的项目”

缺点：

• 和官方仓库没有上游关系
• 后续官方模板更新时，用户不会有现成的同步入口
• 想吃到官方更新，通常只能手动比对、手动拷贝，维护成本更高

推荐方式

推荐用户优先使用：

• GitHub Fork

原因很简单：

• 你们官方模板后续还会继续更新
• fork 至少保留了后续手动同步官方更新的路径
• 对用户来说，长期维护成本明显低于”自己复制一份重新建仓库”

但是一定要把这句话写清楚：

• Fork 不等于自动获得官方更新

也就是说：

• 你们官方模板更新了
• 用户不会自动收到这些更新
• 用户需要自己手动同步 upstream

这套文档覆盖什么

本指南覆盖这套模板的 Cloudflare 上线路径：

• backend/node1-auth-service
• backend/node2-support-service
• backend/node3-pay-service
• backend/node4-notify-service
• backend/node5-blog-service
• backend/node6-cdn-service
• backend/node7-site-service
• backend/node8-prompt-service
• backend/node9-checkin-service
• backend/node10-ai-service
• apps/web
• apps/admin

推荐阅读顺序

1. 先认识 Dev Console
2. 开始之前
3. 准备 Cloudflare 资源
4. 部署后端 Workers
5. 部署前端 Pages
6. 绑定域名和环境变量
7. 首次初始化你的系统
8. 上线检查和常见报错

先记住 4 条死规矩

1. 第一遍部署，不要改 Worker 名称

项目里的 service binding 都已经写死在各个 wrangler.jsonc / wrangler.toml 里了。

例如：

• zship-node1-auth
• zship-node2-support
• zship-node3-pay
• zship-node10-ai

如果你第一遍部署就改名字，你后面会多出一堆绑定错误。

第一遍部署请全部使用仓库默认名字。

2. 第一遍部署，不要改 Pages 项目名

前端项目当前默认按下面这些名字理解：

• admin

第一遍不要自作聪明改成别的。

3. 第一遍部署，先用默认 app_key

第一次跑通时，建议先用：

• demo

原因很简单：仓库很多地方默认就是这个值。

等你确认整套系统能跑通，再把前端环境变量改成你自己的 app_key。

4. 遇到错误，不要一次改 5 个地方

你每次只改一个点，然后重试。

不然你最后根本不知道是哪里改坏的。