企业官网建设流程全解析

• 后端
• 前端

在生产环境中，应用"看起来正常"与"真的正常"之间隔着一条完整的可观测性链路。本文基于 React Starter Kit 的部署文档（docs/deployment/monitoring.md）及其源码实现，系统讲解如何用 Cloudflare 自带的工具监控这套三 Worker 架构（web 边缘路由、app SPA、api Hono + tRPC 后端）的运行状态：如何实时查看日志、如何解读仪表盘指标、如何在发布事故时快速回滚，以及如何排查 Worker 体积、数据库连接和认证故障。读完你将掌握一套无需额外 SaaS 即可落地的生产监控与应急恢复方案。

背景：你要监控的是什么

在进入具体命令之前，先明确监控对象。React Starter Kit 的生产环境由三个独立的 Cloudflare Worker 构成（见 docs/deployment/index.md）：

三个 Worker 的 Wrangler 配置都开启了"observability": { "enabled": true }（api、app、web 三个 wrangler.jsonc 中均可看到），这是 Cloudflare Workers 内置可观测性的开关——开启后，console.log输出、未捕获异常和请求元数据都会被采集，供wrangler tail与 dashboard 的 Workers → Logs 使用。监控时，三个 Worker 要分别对待：入口流量指标看 web，静态资源与 SPA 渲染看 app，而业务错误、数据库延迟与认证故障则集中在 api。

用 Wrangler Tail 实时追踪日志

wrangler tail是最直接的调试武器，它把某个 Worker 的实时日志流输出到终端。React Starter Kit 的所有命令都从仓库根目录执行，且必须带--config指定目标 Worker 的配置文件（否则 Wrangler 不知道把 tail 挂到哪个 Worker 上）：

# 追踪生产环境 API 日志 bun wrangler tail --config apps/api/wrangler.jsonc # 只显示包含特定路径的请求（例如所有 tRPC 调用） bun wrangler tail --config apps/api/wrangler.jsonc --search-str="/api/trpc" # 追踪 staging 环境 bun wrangler tail --config apps/api/wrangler.jsonc --env staging

日志流中包含三类信息：

1. 请求元数据——方法、路径、状态码、耗时、cf-ray等 Cloudflare 请求标识；
2. console.log输出——来自 Worker 代码的日志；
3. 未捕获异常——未被处理的运行时错误。

理解这三类信息，需要看 api Worker 的入口代码 apps/api/worker.ts。它挂载了三条与日志直接相关的中间件：

• worker.use(logger())——Hono 自带的请求日志中间件，为每个请求输出方法、路径与状态码；
• worker.use(requestId({ generator: requestIdGenerator }))——为请求生成关联 ID，实现见 apps/api/lib/middleware.ts：优先使用 Cloudflare 的cf-ray请求头，缺失时回退到crypto.randomUUID()。这个 ID 是把 Worker 日志与 Cloudflare 边缘请求对应起来的关键字段；
• worker.onError(errorHandler)——全局错误处理，其中console.error(\[${c.req.method}] ${c.req.path}:`, err)会把每个未预期的 500 错误连同请求方法和路径一起输出，并返回通用{ "error": "Internal Server Error" }`。

也就是说，当你在 tail 输出中看到某个路径反复出现console.error时，直接去 apps/api/lib/middleware.ts 对应位置就能理解错误上下文。

实用技巧：排查线上问题时，先tailapi Worker 看后端错误，再 tail web Worker 看入口流量分布；用--search-str过滤路径（如/api/trpc、/api/auth）能显著降低日志噪音。注意 tail 是实时流，历史日志需要去 dashboard 的Workers → Logs查看。

用 Cloudflare Analytics 观察长期趋势

wrangler tail解决"此刻发生了什么"，而趋势与告警要靠 dashboard 的 Analytics：

• Workers → Analytics：提供每个 Worker 的请求数、错误率、CPU 时间、耗时百分位（duration percentiles）等指标。这些指标按 Worker 分开统计，可以据此判断问题到底出在 web 边缘路由、app 静态资源还是 api 后端；
• Workers → Logs：实时与历史日志流，适合回看事故窗口内的请求明细；
• 通知策略（notification policies）：针对错误率飙升或延迟上升设置告警，例如"api Worker 5 分钟错误率超过 5% 时通知"，让问题在用户投诉之前到达你。

这套"tail 查细节 + Analytics 看趋势 + 通知策略做告警"的组合，覆盖了从单请求排障到长期容量评估的完整监控需求，且全部使用 Cloudflare 内置能力，无需自建日志平台。

发布事故后的快速回滚

如果一次发布引入了问题，Cloudflare Workers 的版本机制支持快速回退。React Starter Kit 的回滚流程如下：

# 列出最近的部署记录 bun wrangler deployments list --config apps/api/wrangler.jsonc --env="" # 回滚到上一个稳定版本 bun wrangler rollback --config apps/api/wrangler.jsonc \ --env="" \ --message="Reverting due to auth regression"

注意这里用--env=""（显式的空字符串）来选择生产环境：在 apps/api/wrangler.jsonc 中，production 配置位于文件顶层，staging 才是env.staging命名环境。这是本仓库部署约定的一部分，与 CI 中"production 用空环境参数、staging 传环境名"的逻辑完全一致（见 docs/deployment/ci-cd.md）。

由于 web、app、api 是三个独立 Worker，需要对每个受影响的 Worker 重复执行回滚命令——例如认证回归通常要回滚 api，前端渲染问题则要回滚 app 与 web。

⚠️ 重要警告：回滚不包含数据库
Wrangler rollback 只回退 Worker 代码，不会回退数据库迁移。如果某次部署同时包含 schema 变更，而旧代码依赖新 schema（或与之不兼容），直接回滚代码反而会制造新故障。这种情况下应优先考虑"前向修复"（fix-forward）迁移，而不是回滚。完整说明见 数据库迁移指南。这条边界在部署阶段同样成立——生产数据库迁移流程详见 生产数据库部署。

另外，docs/deployment/ci-cd.md 提供了一个与回滚互补的预发布手段：合并到 main 之前，可以执行bun wrangler versions upload --config apps/web/wrangler.jsonc上传一个不切流量的版本进行预览，这比"先发布再回滚"的成本低得多。

常见故障排查手册

Worker 体积超限

Cloudflare Workers 有 10 MB 的压缩后体积限制（免费套餐为 3 MB）。如果部署或上传版本时撞上体积限制：

• 检查是否意外打包了依赖——确认没有把大型 npm 包或重复依赖卷进 bundle；
• 把大体积静态资源移到 R2 存储，不要打进 Worker bundle；
• 确认 tree-shaking 生效——排查是否存在副作用导入（side-effect imports）导致无法摇树。

从构建方式看，api Worker 由 Wrangler 现场打包worker.ts（apps/api/wrangler.jsonc 的"main": "./worker.ts"），而 app/web 通过assets.directory指向./dist提供静态产物，因此体积问题最常出现在 api 的 bundle 上。

数据库连接异常

如果查询失败或超时，按以下顺序排查：

• 核对 Hyperdrive ID：确认 apps/api/wrangler.jsonc 中hyperdrive绑定（HYPERDRIVE_CACHED/HYPERDRIVE_UNCACHED）的 ID 与 Terraform 输出一致——本仓库约定 Terraform 负责创建 Hyperdrive 配置、Wrangler 负责 Worker 本体（见 ADR-002），两者失配会导致连接失效；
• 检查 Neon 控制台：确认是否达到连接数上限（connection limit exhaustion）；
• 确认数据库未被自动挂起：Neon 的 serverless Postgres 在空闲后会自动挂起，挂起后的第一个请求会明显变慢（冷启动延迟），这不一定是代码故障。

api Worker 同时持有两条 Hyperdrive 绑定是有意设计：createDb(c.env.HYPERDRIVE_UNCACHED)用于默认路径，而 Better Auth 的会话/权限读使用未缓存连接，避免缓存造成"登出或改角色后数据延迟数秒"的竞态（见 apps/api/worker.ts）。监控时若发现 api 延迟集中出现在首次请求，可优先怀疑数据库挂起。

生产环境认证故障

如果生产环境登录失败，按以下链条排查：

1. 确认BETTER_AUTH_SECRET已设置：

   bun wrangler secret list --config apps/api/wrangler.jsonc --env=""

   它是最关键的密钥之一——apps/api/lib/env.ts 要求其长度不少于 32 字符（z.string().min(32)），且与RESEND_API_KEY一起被列在 apps/api/wrangler.jsonc 的secrets.required中，缺失会导致部署直接失败；

2. 核对APP_ORIGIN：它必须与实际域名完全一致，因为它影响 cookie 域（APP_ORIGIN在 apps/api/wrangler.jsonc 的vars中定义，生产环境默认https://example.com）。它同时被 Better Auth 用作trustedOrigins的校验依据，域名不匹配会直接导致认证请求被拒（相关安全考量见 docs/api/context.md）；
3. 确认 OAuth 重定向 URI：如果启用了 Google 登录，回调地址必须包含生产环境 URL，否则 OAuth 流程会在最后一步失败。完整配置见 社交登录（Social Providers）。

一个容易被忽视的"看起来健康实则故障"场景：RESEND_EMAIL_FROM默认是onboarding@resend.dev（Resend 的共享测试发件人），它只能投递到 API key 所有者自己的邮箱，其他收件人一律 403。由于本项目的登录主方式是邮箱 OTP，一旦带着这个默认值上线，所有指标都正常，但除了你之外没人能登录——这是生产监控中最值得优先确认的配置项之一，详见 Cloudflare Workers 部署文档。

成本监控

预算与用量监控同样属于生产运维的范畴。Cloudflare Workers、Hyperdrive、Neon、Resend 的定价和免费额度都会随时间调整，本仓库不锁死具体数字，而是建议：

• 做预算时，以 Workers、Hyperdrive、Neon、Resend 各自官方定价页面的当前数字为准；
• 定期在各服务商控制台查看用量，特别是 Neon 的连接数与存储、Workers 的请求数与 CPU 时长、Resend 的邮件发送量；
• 把成本告警与错误率告警同等对待——云成本失控往往是生产事故的一种形态。

小结

React Starter Kit 的生产可观测性完全建立在 Cloudflare 原生能力之上：wrangler tail负责实时排障（配合源码中的 Hono logger、requestId、console.error错误处理，apps/api/worker.ts），Analytics 负责趋势与告警，deployments list+rollback负责快速止血——但务必牢记"回滚不滚数据库"的边界，schema 变更事故要走前向迁移。三条 Worker（web/app/api）各自的日志、指标与回滚都要单独处理，而认证故障类问题则优先核对BETTER_AUTH_SECRET、APP_ORIGIN与 OAuth 回调地址这三个"三连"。把本文的检查清单固化进你的发布流程，配合 部署与 CI/CD 文档，即可形成一套完整的"发布—监控—回滚"闭环。

• 后端
• 前端