React Starter Kit 生产环境监控指南：Wrangler Tail、Cloudflare Analytics 与快速回滚实战

后端前端【免费下载链接】react-starter-kitModern React starter kit with Bun, TypeScript, Tailwind CSS, tRPC, Stripe, and Cloudflare Workers. Production-ready monorepo for building fast web apps.项目地址https://gitcode.com/gh_mirrors/rea/react-starter-kit点击查看免费下载在生产环境中应用看起来正常与真的正常之间隔着一条完整的可观测性链路。本文基于 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.mdWorker配置位置职责webapps/web/wrangler.jsonc边缘路由器接收全部流量通过 service binding 转发到 app/apiappapps/app/wrangler.jsonc托管 React SPA 与静态资源apiapps/api/wrangler.jsoncHono tRPC 服务端负责认证与数据库访问三个 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日志流中包含三类信息请求元数据——方法、路径、状态码、耗时、cf-ray等 Cloudflare 请求标识console.log输出——来自 Worker 代码的日志未捕获异常——未被处理的运行时错误。理解这三类信息需要看 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 的 AnalyticsWorkers → 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 \ --messageReverting 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.tsapps/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 延迟集中出现在首次请求可优先怀疑数据库挂起。生产环境认证故障如果生产环境登录失败按以下链条排查确认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中缺失会导致部署直接失败核对APP_ORIGIN它必须与实际域名完全一致因为它影响 cookie 域APP_ORIGIN在 apps/api/wrangler.jsonc 的vars中定义生产环境默认https://example.com。它同时被 Better Auth 用作trustedOrigins的校验依据域名不匹配会直接导致认证请求被拒相关安全考量见 docs/api/context.md确认 OAuth 重定向 URI如果启用了 Google 登录回调地址必须包含生产环境 URL否则 OAuth 流程会在最后一步失败。完整配置见 社交登录Social Providers。一个容易被忽视的看起来健康实则故障场景RESEND_EMAIL_FROM默认是onboardingresend.devResend 的共享测试发件人它只能投递到 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.tsAnalytics 负责趋势与告警deployments listrollback负责快速止血——但务必牢记回滚不滚数据库的边界schema 变更事故要走前向迁移。三条 Workerweb/app/api各自的日志、指标与回滚都要单独处理而认证故障类问题则优先核对BETTER_AUTH_SECRET、APP_ORIGIN与 OAuth 回调地址这三个三连。把本文的检查清单固化进你的发布流程配合 部署与 CI/CD 文档即可形成一套完整的发布—监控—回滚闭环。赞分享后端前端【免费下载链接】react-starter-kitModern React starter kit with Bun, TypeScript, Tailwind CSS, tRPC, Stripe, and Cloudflare Workers. Production-ready monorepo for building fast web apps.项目地址https://gitcode.com/gh_mirrors/rea/react-starter-kit点击查看免费下载相关推荐ToolJet 应用发布与回滚指南版本发布、生产环境推广与快速回滚实践ToolJet 应用发布与回滚指南版本发布、生产环境推广与快速回滚实践 ToolJet 允许你将应用通过版本管理系统安全地发布给最终用户并在线上出现问题时快低代码后端前端AI 应用MCP 服务May协程库Rust版Goroutine的完整入门指南May协程库Rust版Goroutine的完整入门指南 May是一个高性能的栈式协程库让你能够轻松开发和维护大规模并发程序可视为Rust版的Gorouti并发编程后端3分钟完成Windows和Office免费激活的完整实用指南3分钟完成Windows和Office免费激活的完整实用指南 还在为Windows系统未激活而烦恼吗想免费使用正版Office却不想花大价钱KMS_VL_A运维上一篇掌握Game Programming Patterns从零开始构建高效游戏开发架构下一篇CodeGuide可访问性测试WCAG标准实践指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考