GenarrativeAI/Genarrative

Fork 0

Files

高物 f19e482c8f 1

2026-04-10 15:37:02 +08:00

6.5 KiB

Raw Blame History

Node 后端测试、观测与部署基线

日期：2026-04-08

1. 文档目标

这份文档用于落实 EXPRESS_BACKEND_PARALLEL_WORKSTREAM_PLAN_2026-04-08.md 中的任务 9：

给 Node 后端补最小自动回归
给请求链路补最小可追踪基线
给部署、回滚、迁移补最小操作清单

当前目标不是一次性把监控平台、CI/CD、容器编排全部做完，而是先确保：

后端改动后有脚本能快速验证主链路
线上或联调失败时能快速定位到具体请求
发布前后有统一检查口径

2. 当前基线命令

推荐在仓库根目录执行：

npm run server-node:db:migrate
npm run server-node:test:baseline
npm run server-node:smoke
npm run server-node:smoke:proxy

说明：

npm run server-node:db:migrate
- 用当前 DATABASE_URL 主动校验 PostgreSQL 基线是否可连接、可初始化
- 会确保 schema_migrations 和运行时基础表已补齐
npm run server-node:test:baseline
- 当前先固定为任务 9 自己维护的观测基线测试
- 已覆盖 requestId 回传、访问日志字段、错误日志链路
npm run server-node:smoke
- 启动一套基于 pg-mem 的临时 Express 服务
- 不依赖本地 PostgreSQL
- 走真实 HTTP 调用验证 healthz -> auth -> runtime save/settings -> logout
npm run server-node:smoke:proxy
- 基于已构建的 dist + server-node/dist
- 自动拉起 server-node + 同域反向代理 harness
- 用 pg-mem 跑同域反向代理链路 smoke
- 验证 web -> reverse proxy -> /api/* -> server-node 主链路

如果要一口气跑完整发布前基线，可执行：

npm run server-node:check:deploy

补充说明：

npm run server-node:test 仍然可以继续作为更大范围的后端接口套件入口
但它会跟随其他并行任务一起变化，不应替代任务 9 自己的稳定基线

2.1 任务 9 对照清单

当前按并行任务规划中的任务 9 逐项对照：

后端接口测试：npm run server-node:test
关键主链路 smoke：npm run server-node:smoke
request/response 日志校验：npm run server-node:test:baseline
同域部署基线：本文第 6 节与 npm run server-node:smoke:proxy
反向代理 smoke 测试脚本：scripts/smoke-same-origin-stack.ts
回滚、备份、迁移检查清单：本文第 8 节与 npm run server-node:db:migrate
发布前一键检查：npm run server-node:check:deploy

3. 当前 smoke 覆盖范围

当前 smoke 脚本验证以下链路：

GET /healthz
POST /api/auth/entry
GET /api/auth/me
PUT /api/runtime/save/snapshot
GET /api/runtime/save/snapshot
PUT /api/runtime/settings
GET /api/runtime/settings
DELETE /api/runtime/save/snapshot
POST /api/auth/logout

当前代理 smoke 额外验证：

GET /
GET /healthz（本地反向代理健康探针）
POST /api/auth/entry 经反代可用
GET /api/auth/me 经反代可用
PUT /api/runtime/save/snapshot 经反代可用
GET /api/runtime/save/snapshot 经反代可用
X-Request-Id 能穿过反向代理返回给调用方

当前 smoke 的定位是：

优先覆盖后端化后最容易断的基础链路
优先覆盖前端最依赖的鉴权和持久化能力
不把 AI 上游依赖拉进最小回归集，避免把第三方波动误判成主链路回归

4. 当前观测基线

当前请求链路至少要满足以下约束：

支持读取外部传入的 X-Request-Id
如果调用方没有传 X-Request-Id，后端自动生成
响应头回写 x-request-id
访问日志至少包含：
- request_id
- user_id
- method
- path
- status
- latency_ms
错误日志至少包含：
- request_id
- user_id
- err

当前目的很明确：

浏览器、反向代理、Node 后端至少有一个共同可追踪的请求标识
接口失败后，能从日志里快速找到对应请求

5. 部署前检查清单

发布前至少执行一次：

npm run check:encoding
npm run server-node:db:migrate
npm run server-node:test:baseline
npm run server-node:smoke
npm run server-node:build
npm run build
npm run server-node:smoke:proxy

环境变量至少确认：

DATABASE_URL
JWT_SECRET
NODE_SERVER_ADDR
LOG_LEVEL
LLM_API_KEY 或 ARK_API_KEY
DASHSCOPE_API_KEY

部署前数据库检查：

确认目标 PostgreSQL 可连接
确认发布账号具备建表或执行初始化所需权限
确认已执行 npm run server-node:db:migrate 或等效迁移步骤
确认现网数据已完成备份

6. 同域部署基线

当前推荐仍然是同域部署：

Web 静态资源：https://game.example.com/
Node API：https://game.example.com/api/*

最小拓扑：

Browser
  -> Nginx / Caddy
    -> dist
    -> server-node

反向代理至少要保留这些头：

Host
X-Forwarded-For
X-Forwarded-Proto
X-Request-Id

流式接口还要确保：

proxy_buffering off
X-Accel-Buffering: no

7. 发布后 smoke 清单

发布完成后至少人工或脚本确认一次：

GET /healthz 返回 200
响应头里能看到 x-request-id
POST /api/auth/entry 可正常注册或恢复账号
GET /api/auth/me 可正常识别 token
PUT /api/runtime/save/snapshot 和 GET /api/runtime/save/snapshot 正常
日志中能用同一个 request_id 串起访问记录

如果线上使用反向代理生成请求 ID，还要额外确认：

代理传入的 X-Request-Id 没有在 Node 层丢失
同域入口 / 与 /api/* 可以通过同一个站点域名访问

8. 回滚与备份清单

回滚前先确认：

当前发布包版本号或 commit 可定位
当前数据库备份可恢复
当前 .env 或 secret 版本可回退

需要回滚时按顺序执行：

停止新版本 Node 进程
切回上一个稳定前端静态包和 Node 构建产物
恢复上一个稳定环境变量版本
如果本次发布包含数据库结构变更，先确认是否需要回滚数据
回滚后重新执行 healthz + auth + runtime save 最小 smoke

如果本次发布已经写入了不兼容数据结构：

不要只回滚代码不验证数据兼容性
必须先确认旧版本代码是否还能读取当前数据

9. 后续扩展方向

任务 9 的下一轮可以继续补：

把 smoke 纳入 CI
为关键 API 增加结构化 contract 测试
给上游 AI 调用补 vendor/model/errorCode 维度日志
增加数据库迁移前后的自动检查脚本
增加反向代理与正式环境的联调 smoke

6.5 KiB Raw Blame History Unescape Escape