194 lines (138 loc) · 3.95 KB

TGO Network 运维运行手册

1. 目的

本文档把架构与部署决策转成发版和运维检查清单。

重点关注：

发版前准备
预发环境验证
生产发布顺序
回滚与恢复
例行巡检

2. 运维职责

最少建议覆盖以下角色：

发版负责人：协调发布窗口与检查项
后端负责人：确认 API、迁移、内部任务与日志
前端负责人：确认前台与后台部署可用
数据负责人：确认备份与恢复准备

小团队可以一人兼多岗，但责任不能缺位。

3. 发版前置条件

每次发版前至少确认：

main 分支 CI 通过
API 镜像构建通过
npm run typecheck 通过
npm run build 通过
npm run test 通过
数据库变更已写入迁移
环境变量文档与 .env.example 同步
已知前台、后台、API 的回滚版本
npm run env:check:api -- production 通过

如果本次变更涉及：

权限
公开表单
存储
数据迁移
首页或核心路由

则必须做预发验证，不可跳过。

4. 标准发布顺序

推荐顺序：

确认目标提交 CI 为绿色
确认数据库备份新鲜
运行环境变量校验
构建 API 镜像
先部署 api 到预发
执行预发迁移
部署 admin 到预发
部署 site 到预发
完成预发验收
部署 api 到生产
执行生产迁移
部署 admin 到生产
部署 site 到生产
完成生产验收

原因：

前后台都依赖 API 契约
迁移必须先于依赖新结构的前端上线

5. 预发环境验证清单

预发环境至少验证：

GET /health
GET /ready
GET /version
任意成功响应带有 X-Request-ID
任意错误响应包含 error.requestId
后台登录成功
首页正常加载
分会董事会页正常加载
成员列表与详情页正常加载
活动列表与详情页正常加载
文章列表与详情页正常加载
/join 与 /apply 正常加载
/about 正常加载
GET /api/admin/v1/me 返回有效工作人员信息

推荐的预发写操作检查：

发布一篇文章或编辑已发布文章
发布一个活动
提交一次公开活动报名
提交一次公开加入申请
修改一个成员或分会信息
查看一条审计日志是否写入

6. 生产环境验证清单

生产环境至少验证：

健康检查通过
首页可访问
成员列表可访问
活动详情可访问
文章详情可访问
/join 与 /apply 可访问
后台登录可用
仪表盘可用
审计日志页可用

生产环境尽量避免做无必要的写操作。如果必须验证写链路，优先选低风险、可回滚的测试数据。

7. 回滚策略

`site` 回滚

适用场景：

前台渲染异常
API 仍然健康

动作：

回滚到上一个可用的前台构建

`admin` 回滚

适用场景：

后台页面或交互异常
API 与数据库兼容旧版本后台

动作：

回滚到上一个可用的后台构建

`api` 回滚

适用场景：

鉴权、接口契约、上传、审核流异常

动作：

仅在数据库兼容时回滚 API

数据库恢复

只有在以下情况才考虑：

数据破坏
迁移造成不可逆逻辑损伤
应用回滚无法恢复

数据库恢复属于重大事故处理，不应作为常规回滚方案。

8. 备份与恢复演练

至少要定期验证：

能拿到最近备份
能在预发环境完成恢复
恢复后关键表可读
恢复后 API 能正常启动

关键表至少包括：

staff_accounts
roles
branches
members
articles
events
event_registrations
join_applications
audit_logs
assets

9. 例行巡检建议

上线后应定期检查：

公开首页、成员、活动、文章是否有空白数据
活动报名与加入申请是否仍能落库
审计日志是否持续写入
对象存储预览图是否可访问
定时发布任务是否正常
API 日志与错误率是否异常