上线验收与日常维护

部署脚本结束后，还要在正式环境验证用户实际会走的流程。验收使用生产环境中新建的测试账户，不要假设本地账户和测试订单已经存在于远程数据库。

按照自己的功能开关选择检查项。没有启用的 OAuth、博客、联盟或收费功能无需临时打开，但页面也不应展示不可用的入口。

一、先记录验收环境

记录正式地址、代码版本、部署时间和测试账户。涉及支付时，再记录使用的是 Stripe 测试模式还是正式模式，以及对应的连接标识。

初次上线应完整检查下表。后续更新可以重点覆盖受影响功能，同时保留首页、登录和核心业务的基本验证。

二、验证用户流程

如果跟做了收藏链接教程，分别用两个账户创建和查询收藏，确认用户隔离。如果跟做了 WebpageToPDF，按教程检查匿名体验、注册用户、Pro 用户的转换和额度规则。

不要把用户看到的成功提示作为唯一证据。对于写入操作，再读取一次结果。对于异步任务，继续查看执行状态。

三、验证支付与权益

先在独立的测试配置和数据环境中走通 Checkout、Webhook、购买记录与权益发放。正式站点的验收使用正式配置，不能只替换 Secret Key，却保留测试 Price 或测试端点的签名密钥。

按以下顺序检查：

1. 购买入口对应正确产品和 Plan，显示价格与支付页一致。
2. 取消付款返回后，不会凭返回地址获得权益。
3. 支付成功后，检查订单或订阅记录与后续权益状态。
4. 实际调用受保护业务，确认权限或额度已经生效。
5. 打开 Billing Portal，确认管理的是当前用户的客户与订阅。
6. 在测试环境验证周期结束、取消、失败付款和退款等相关状态。

设置“周期结束时取消”不等于立即失去所有权益，应按订阅有效期和权益来源判断。退款也不应直接等同于“所有权限已自动撤销”，验收结果要与产品实际退款规则一致。

正式模式下的购买会产生真实交易。如确需完成正式交易验收，按自己的收款与退款安排操作，并记录对应订单，不要使用测试卡或把测试交易结论当作正式验收结果。

如果支付平台已经收到款，而网站权益没有变化，先检查 Webhook 投递、签名验证、支付同步和 Reaction 执行，再检查套餐 access 配置。不要让用户反复付款来触发修复。

四、验证文件、工单与后台任务

按启用情况完成：

• 上传一张测试图片或一个业务文件，再通过返回地址读取，确认使用的是生产存储。
• 普通用户创建工单，管理员读取并回复，确认状态与附件可用。
• 在公开页面产生一次访问，再检查统计数据是否进入后台。
• 触发一项正常业务事件，检查 Reaction 事件与命令执行结果。
• 查看 Queue 消费、重试或积压情况，以及 Cron 的配置和执行日志。

Reaction 记录可从管理后台对应入口查看，例如：

/dashboard/reaction/events
/dashboard/reaction/commands

队列成功接收消息只说明入队成功，Cron 触发成功也只说明入口被调用。最终要看命令执行记录与业务数据，不能只看触发次数。

统计数据可能经过队列异步处理，不必在刷新页面后立刻认定采集失败。按访问统计的链路检查请求、队列和统计库。其他后台流程见后台任务与定时任务。

五、上线后观察什么

正式开放后，优先观察会阻断用户流程的信号：

查看实时 Worker 日志可以在项目根目录执行：

npx wrangler tail

结合 Cloudflare 中的 Worker、Queue 和 D1 状态，以及站内管理后台的日志判断。分享排查信息时保留请求、事件和订单标识，隐藏令牌、签名密钥与无关的用户数据。

如果已配置通知渠道，可以让重要业务失败发送到实际有人查看的目标。配置方式见通知，不要只创建了目标却从未验证送达。

六、常见问题按哪条链路排查

首页正常，注册失败

先检查 Turnstile 与邮件配置，再看数据库和 Reaction。首页通常不需要完整经过这些模块，首页能打开不能证明注册依赖已经就绪。

OAuth 返回地址错误或反复跳转

核对正式 VITE_SITE_URL、应用允许主机、OAuth Client ID 对应的应用，以及平台保存的 Callback URL。确认浏览器没有从旧 Origin 进入，也没有把语言路径拼进 API 回调。

支付成功，后台状态没有更新

先检查事件是否到达正式端点，签名密钥是否属于该端点，再检查同步与后续命令。确认失败原因已经修复后，使用提供商或项目已有的重试方式，并验证不会重复产生业务结果。

文档或博客 404

先确认功能已启用、该语言确实存在对应文章，再检查 MAIN_KV 和同步输出。文章已删但侧边栏还在时，也要检查 meta.json，不要只重新构建首页。

数据库出现 no such table 或 no such column

确认报错请求使用的绑定与迁移操作指向同一个库，再检查迁移记录和实际字段。不要为了恢复访问而执行生产 Reset，也不要只在远程手工修表却不补回迁移文件。

七、发布出错时如何恢复

先判断影响范围，必要时暂停受影响的购买或业务入口，再保留错误日志、事件状态和本次发布记录。优先修复具体失败环节，避免把不相关的模块一起改动。

如果考虑退回旧 Worker 版本，先确认它仍能读取当前数据库结构和数据格式。Worker 回滚不会恢复 D1、KV 或 R2 的内容，绑定变化和 Durable Objects 迁移也可能限制回滚。具体条件见Cloudflare 回滚说明。

数据库恢复则是另一项操作，应按生产数据库与内容准备的记录评估。恢复到过去的时间点后，支付平台、邮件、已发送通知和已消费的队列消息不会跟着自动回到过去，需要单独核对。

例如付款已经成功，但数据库被恢复到付款之前，不能只因本地订单消失就认为这笔交易不存在。应基于支付平台记录与项目幂等处理方式完成对账和补偿。

八、把验收结果带到下一次发布

保存一份简短记录即可：本次版本、变更内容、迁移和配置变化、完成的验收项目，以及暂未启用的功能。后续更新时用它确认哪些行为必须保持。

日常更新继续使用 npm run deploy:update。增加业务功能参考开发实践，调整内置模块参考常用功能。备份是否可恢复、通知是否有人接收，也应定期实际检查，而不是只保留一段配置。