跳转到内容
  • zh
  • deploy 07 troubleshooting

07. 上线检查和常见报错

这一章是最后的验收清单。

建议你边看边对照，不要凭感觉说”应该好了”。

1. 上线检查清单

Section titled “1. 上线检查清单”

前端访问

Section titled “前端访问”
  • 主站首页能打开
  • 后台登录页能打开

后台访问

Section titled “后台访问”
  • 你能用 ADMIN_SECRET 登录后台
  • Projects 页面能看到你创建的项目
  • Health 页面能看到主要服务状态

用户主流程

Section titled “用户主流程”
  • 用户可以注册
  • 用户可以登录
  • 用户可以打开 pricing 页面
  • 用户可以打开 dashboard 页面

可选模块

Section titled “可选模块”
  • 博客列表能正常显示
  • banner 能正常显示
  • friend links 能正常显示
  • AI chat 不报错
  • check-in 不报错

2. 线上排查：Cloudflare Observability（报错日志）

Section titled “2. 线上排查：Cloudflare Observability（报错日志）”

生产环境出问题、本地又难以复现时，可以直接在 Cloudflare 控制台看 线上 Worker / Pages 的运行日志与异常。

路径（以认证服务为例）：

  1. 登录 Cloudflare Dashboard
  2. 左侧进入 Compute（计算） → Workers & Pages
  3. 点开目标资源，例如 zship-node1-auth（名称以你 wrangler 里 name 为准）
  4. 打开 Observability（可观测性）

在 Observability 中可查看请求、报错堆栈、控制台输出 等，用于定位 5xx、未捕获异常、上游调用失败等。

若看不到日志： 该项目的 Observability 可能尚未开启。在同一 Worker / Pages 项目设置里找到 Observability 相关选项，先 Enable（启用），再重试请求后刷新查看。

提示：对每个出问题的 Worker（如 zship-node3-pay、zship-node10-ai、前端 Pages 项目等）重复上述步骤，分别查看对应服务的线上日志。

3. CDN / R2 异常：CDN_PUBLIC_URL 必须与 R2 公网访问域名一致

Section titled “3. CDN / R2 异常：CDN_PUBLIC_URL 必须与 R2 公网访问域名一致”

上传失败、文件 404、或 node6-cdn-service 报错时，先核对 Worker 环境变量里的公开访问根 URL 与 R2 上绑定的自定义域名 是否为同一个——否则 Worker 会把文件写到桶里，但返回给前端的 URL 与真实可访问地址不一致。

下面分两条路径：§3.1–§3.4 全部在 Cloudflare 控制台网页里操作（适合首次绑定域名、逐项核对）；§3.5 在 ZShip Dev Console 里完成变量推送与部署衔接——日常改 CDN_PUBLIC_URL 时，优先用 Dev Console，不必在 CF 菜单里来回找 Variables and Secrets。

方式一：Cloudflare 控制台（§3.1–§3.4）

Section titled “方式一：Cloudflare 控制台（§3.1–§3.4）”

以下步骤均在 Cloudflare Dashboard 中完成：创建 R2 自定义域名、在 Worker 里填 CDN_PUBLIC_URL、以及（可选）给 CDN Worker 绑公网域名。

3.1 在 Dashboard 修改 CDN_PUBLIC_URL

Section titled “3.1 在 Dashboard 修改 CDN_PUBLIC_URL”
  1. Compute（计算） → Workers & Pages → 打开 zship-node6-cdn
  2. Settings（设置） → Variables and Secrets
  3. 将 CDN_PUBLIC_URL 设为你的 R2 对外访问根地址（需带 https://，末尾一般不加路径）

3.2 R2 的公网 URL 在哪里配？

Section titled “3.2 R2 的公网 URL 在哪里配？”
  1. Storage & databases（存储与数据库） → R2 object storage
  2. Overview 中打开你的 bucket（默认示例名 zship-cdn，以你实际创建为准）
  3. Settings → Custom Domains（自定义域名）
    在这里为 R2 绑定公网访问用的域名（例如 https://cdn.example.com）。该域名经 Cloudflare 代理后，即文件对外访问的根。

3.3 两个值必须一致

Section titled “3.3 两个值必须一致”
位置变量 / 配置应填什么
Worker zship-node6-cdnCDN_PUBLIC_URL与 R2 Custom Domain 对应的 根 URL（https://你的 CDN 域名）
R2 bucketCustom Domains同上一条的 主机名（控制台里配置）

二者必须指向同一套公网入口，zship-node6-cdn 才会在上传后生成正确的文件 URL，且浏览器能通过该 URL 命中同一 R2 桶中的对象。

3.4 需要把 CDN Worker 暴露到公网时

Section titled “3.4 需要把 CDN Worker 暴露到公网时”

若希望 上传 API / CDN Worker 本身也有独立公网入口（而不仅是 R2 静态域名），请在 Workers & Pages → zship-node6-cdn → Settings → Domains & Routes（或 Custom Domains）中为该 Worker 绑定域名。是否绑定取决于你的架构：仅文件走 R2 自定义域名时，重点仍是 §3.3 两处 URL 一致。

方式二：ZShip Dev Console（§3.5）— 日常更推荐

Section titled “方式二：ZShip Dev Console（§3.5）— 日常更推荐”

为什么值得用 Dev Console： 改 CDN_PUBLIC_URL、推送到线上 Worker、再与 重部署 串在同一套工作流里，不用反复登录 Cloudflare、在 Workers & Pages → 某个 Worker → Settings → Variables 里逐字段保存。和本仓库的 Deploy / 环境变量 心智一致，排障与发版时少切上下文，尤其适合已经习惯用 Dev Console 管密钥与部署的团队。

3.5 在 Dev Console 里推送 CDN_PUBLIC_URL 并重部署

Section titled “3.5 在 Dev Console 里推送 CDN_PUBLIC_URL 并重部署”
  1. 打开 Dev Console → Shipping → Deploy（菜单名称以你本地 Dev Console 为准）
  2. 进入 Environment variables → Worker environment
  3. 选择 cdn backend（对应 zship-node6-cdn）
  4. 修改 CDN_PUBLIC_URL，执行 Push to zship-node6-cdn（或等价「推送到 Worker」），将变量直接写入线上 Worker
  5. 重新部署 zship-node6-cdn，使配置生效

说明：R2 的 Custom Domain 若尚未在 Cloudflare 控制台创建过，仍需先在 §3.2 完成绑定；之后日常只改 URL 时，用 §3.5 即可。

4. 最常见报错 1：service binding target not found

Section titled “4. 最常见报错 1：service binding target not found”

典型原因

Section titled “典型原因”
  • 你改了 Worker 名称（与 wrangler.jsonc 中 name 不一致）
  • 你登录错了 Cloudflare 账号
  • 部署顺序导致：有 service binding 的 Worker 依赖的 target 尚未部署

处理办法

Section titled “处理办法”
  1. 确认 wrangler.jsonc 中的 name 与仓库默认一致
  2. 执行 npx wrangler whoami，确认当前账号没错
  3. 按依赖顺序部署（无 binding 的 Worker 先部署）

5. 最常见报错 2：D1 / KV / R2 资源找不到

Section titled “5. 最常见报错 2：D1 / KV / R2 资源找不到”

典型原因

Section titled “典型原因”
  • 你没创建资源
  • 你创建了资源，但没写回 wrangler.jsonc
  • 你创建在另一个账号或另一个环境下

处理办法

Section titled “处理办法”

先执行：

Terminal window
rg -n "00000000-0000-0000-0000-000000000000|placeholder-replace-after-create" backend/*/wrangler.jsonc

如果还能搜到占位符，先回去把资源补齐。

6. 最常见报错 3：后台登录 401

Section titled “6. 最常见报错 3：后台登录 401”

典型原因

Section titled “典型原因”
  • ADMIN_SECRET 输入错了
  • 你修改了 wrangler.jsonc 但没重新部署 node1-auth-service
  • 线上跑的不是你当前本地看到的配置

处理办法

Section titled “处理办法”
  1. 确认 backend/node1-auth-service/wrangler.jsonc 里的值
  2. 重新执行：
Terminal window
pnpm --dir backend/node1-auth-service deploy
  1. 再重新登录后台

7. 最常见报错 4：页面能开，但数据全是空

Section titled “7. 最常见报错 4：页面能开，但数据全是空”

典型原因

Section titled “典型原因”
  • 你的 APP_KEY 和后台项目不一致
  • 后台根本没有这个 app_key
  • 你先改了前端变量，没在后台创建对应项目

处理办法

Section titled “处理办法”

第一遍部署最稳妥的做法就是：

  • 先用 demo
  • 后台也先创建 demo

等完全跑通，再换成你自己的 app_key

8. 最常见报错 5：支付页能打开，但不能支付

Section titled “8. 最常见报错 5：支付页能打开，但不能支付”

典型原因

Section titled “典型原因”
  • node3-pay-service 没有配置 Stripe / Creem 密钥
  • 后台没有创建 Price Config
  • 项目没有绑定支付通道

处理办法

Section titled “处理办法”

去后台逐项检查：

  • Pay Channels
  • Price Config
  • 项目绑定关系

9. 最常见报错 6：AI 页面能打开，但发消息报错

Section titled “9. 最常见报错 6：AI 页面能打开，但发消息报错”

典型原因

Section titled “典型原因”
  • node10-ai-service 没有配置 Cloudflare AI Gateway 变量
  • 后台 AI 模型没有启用
  • 模型价格和配置没有补齐

处理办法

Section titled “处理办法”

同时检查两边：

  • backend/node10-ai-service/wrangler.jsonc
  • 后台 AI 页面

10. 最常见报错 7：Pages 部署报 Invalid binding SESSION

Section titled “10. 最常见报错 7：Pages 部署报 Invalid binding SESSION”

原因

Section titled “原因”

apps/web 的 Cloudflare 运行时里需要 SESSION KV binding。

处理办法

Section titled “处理办法”
  1. 创建一个 KV namespace
  2. 进入对应 Pages 项目
  3. Settings -> Functions
  4. 添加一个名字叫 SESSION 的 KV binding
  5. 重新部署

11. 邮件发不出或大量进垃圾箱

Section titled “11. 邮件发不出或大量进垃圾箱”

典型原因

Section titled “典型原因”
  • 发信域名 DNS 记录未配齐（SPF、DKIM、DMARC 等，以你邮件服务商要求为准）
  • node4-notify-service 或第三方 SMTP 的 密钥 / 发件人 在后台或 Worker 环境变量中配置错误
  • 模板、收件人字段在后台 邮件模板 中配错，或请求未走到 notify Worker

处理办法

Section titled “处理办法”
  1. 对照 邮件集成 检查 DNS 与后台渠道配置
  2. 在 Observability 中查看 zship-node4-notify（或你改名后的 notify Worker）是否有报错
  3. 用后台「发测试邮件」或最小复现请求验证，再查服务商投递日志（若提供）

12. 支付或第三方 Webhook 收不到、状态长期不对

Section titled “12. 支付或第三方 Webhook 收不到、状态长期不对”

典型原因

Section titled “典型原因”
  • 回调 URL 不是公网可访问域名（仍在使用 *.workers.dev 或内网地址）— 与 绑定域名 一章一致，node3-pay 必须绑自定义域名
  • Stripe / Creem 后台填写的 Webhook URL、密钥 与线上一致性不一致（环境切错、多环境混用）
  • 支付服务商侧 重试已过期，仅能在后台或对账里补状态

处理办法

Section titled “处理办法”
  1. 确认 zship-node3-pay 的公网域名与 Dashboard / 支付渠道里配置的 Webhook 地址完全一致（含 https://）
  2. 在 Observability 打开 zship-node3-pay，看回调请求是否到达、是否 4xx/5xx
  3. 查阅 支付集成 核对 Price、渠道与项目绑定

若浏览器端报 CORS 或跨域，多半是前端域名与 API 允许的 Origin 不一致 — 先对齐 SITE_URL、后台项目域名与网关配置，再重试。

13. 最后一个建议

Section titled “13. 最后一个建议”

第一版部署成功以后，你下一步不要立刻做”大改造”。

先做这三件事：

  1. 把你修改过的 wrangler.jsonc 和文档一起保存好
  2. 记下你所有生产资源名称
  3. 把当前能成功部署的步骤固化成团队内部 SOP

这样你以后换电脑、换同事、换客户项目时，才不会重新踩一遍坑。