Stev_Wang
00ae12435e
项目尚无统一工程规范，AI 助手与研发各自发挥导致返工风险。建立 总纲 + 细则两层结构：AGENTS.md 只写硬约束与索引（14 条红线、技术栈 基线、仓库结构、命令契约），细则拆为 10 份文档覆盖 Git、代码风格、 格式化、API 与路由、数据库、测试与 CI、Review、日志、密钥、资产命名。 影响面：仅文档。约束力从本轮起对新建代码生效；与现状冲突处以文档为准。 回滚方式：git revert 本提交。
113 lines
5.7 KiB
Markdown
113 lines
5.7 KiB
Markdown
# 08 · 日志与可观测性规范
|
||
|
||
| 项 | 内容 |
|
||
| --- | --- |
|
||
| 文档版本 | V1.0（2026-11-02） |
|
||
| 依据 | 技术架构 §2.7（可观测性）、§9.7、§5.4.5（审计表） |
|
||
| 适用范围 | `apps/api`、`apps/worker`、`apps/web`（错误上报） |
|
||
| 强制级别 | 强制 |
|
||
|
||
---
|
||
|
||
## 1 日志（Pino，结构化 JSON）
|
||
|
||
**必带字段**（每条日志）
|
||
|
||
| 字段 | 说明 |
|
||
| --- | --- |
|
||
| `ts` | ISO 8601 UTC |
|
||
| `level` | `error` / `warn` / `info` / `debug` |
|
||
| `msg` | 稳定短句（可被聚合），变量放字段里 |
|
||
| `trace_id` | 贯穿请求链路；HTTP 入口生成，响应头 `x-trace-id` 回传 |
|
||
| `module` | 模块名（`media` / `script` / `identity`…） |
|
||
| `action` | 动作（`media.task.submit`、`script.generate`） |
|
||
|
||
**按需字段**：`user_id`、`customer_id`、`task_id`、`item_id`、`duration_ms`、`error.code`、`error.stack`（仅后端内部日志）、`retry_count`、`provider`、`model`。
|
||
|
||
- `LOG-01` 禁止 `console.log`；后端用注入的 logger，前端用统一 logger + 错误上报。
|
||
- `LOG-02` `msg` 用英文短句 + 常量，禁止拼业务变量（`"task 123 failed"`），便于聚合统计。
|
||
- `LOG-03` 禁止记录：密码、Token、密钥、Cookie、签名 URL、`Authorization` 头、完整手机号 / 身份证、客户素材原始内容。
|
||
- `LOG-04` 大对象（请求体 / 模型响应）必须先裁剪：≤ 2 KB，且标注 `truncated: true`。
|
||
- `LOG-05` AI 调用日志记录：供应商、模型、任务类型、耗时、token 数、费用、是否降级；**不记录 prompt 全文**（敏感客户信息），需要复现时用引用 ID。
|
||
- `LOG-06` 日志级别语义：`error` = 需人处理；`warn` = 已降级 / 重试；`info` = 业务里程碑与状态变更；`debug` = 仅开发环境默认关闭。
|
||
- `LOG-07` 生产默认 `info`，可按模块动态调级（不重启）；禁止长期开 `debug`。
|
||
|
||
---
|
||
|
||
## 2 链路追踪（OpenTelemetry）
|
||
|
||
- `LOG-08` HTTP 入口创建 span，`trace_id` 写入响应头、错误体、日志三处，便于用户报错时定位。
|
||
- `LOG-09` 跨队列传递 `traceparent`（BullMQ job data 中携带），worker 侧继续同一 trace。
|
||
- `LOG-10` 外部调用（AI / 存储 / ffmpeg）必须建子 span，记录目标、耗时、结果状态。
|
||
- `LOG-11` 采样率：生产默认 10%，错误与慢请求 100%；采样配置走环境变量。
|
||
|
||
---
|
||
|
||
## 3 审计（与日志严格分离）
|
||
|
||
| 维度 | 日志 | 审计 |
|
||
| --- | --- | --- |
|
||
| 存储 | 日志系统（可轮转、可丢弃） | `audit_logs` 表（append-only） |
|
||
| 用途 | 排障 | 追责、合规、回溯「为什么这样」 |
|
||
| 内容 | 技术细节 | actor / action / target / before / after / ip / ua / trace_id |
|
||
| 修改 | 可删可改 | **仅 INSERT**，任何角色不可改（PRD 9.2） |
|
||
|
||
- `LOG-12` 必须审计的操作：登录 / 登出、权限点与角色变更、客户创建与状态变更、导出、分享链接创建与作废、AI 配置变更、行业包发布、字段变更与审批、资产删除 / 停用、跨客户复用授权。
|
||
- `LOG-13` 审计写入与业务写在同一事务内（或 outbox 保证最终一致），**禁止**业务成功但审计丢失。
|
||
- `LOG-14` 审计查询本身也要留痕（谁查了审计）。
|
||
|
||
---
|
||
|
||
## 4 指标（Prometheus 命名）
|
||
|
||
命名：`<domain>_<metric>_<unit>`，如 `media_task_finished_total`、`queue_depth`、`ai_cost_cny_total`。
|
||
|
||
| 类别 | 必含指标 |
|
||
| --- | --- |
|
||
| HTTP | 请求量、错误率、P50/P95 延迟（按路由模板，不按原始 URL） |
|
||
| 队列 | 各队列深度、等待时长、失败率、重试次数 |
|
||
| 业务 | 任务成功率、单条成本、图片有效率、抠图降级率、低质量产出率 |
|
||
| AI | 调用次数、失败 / 降级率、token 用量、费用（预算占比） |
|
||
| 存储 | 桶容量、上传失败率、签名 URL 下发量 |
|
||
| 依赖 | PG 连接数 / 慢查询、Redis 内存 / 命中率 |
|
||
|
||
- `LOG-15` 标签基数受控：禁止把 `user_id`、`customer_id`、`task_id` 作为指标标签（用日志 / trace 查）。
|
||
- `LOG-16` 派生指标（汇总 / 均值 / 占比）运行时计算，**不落库**（技术架构 §5.7）。
|
||
|
||
---
|
||
|
||
## 5 告警
|
||
|
||
| 告警 | 阈值（起步，可调） | 处置 |
|
||
| --- | --- | --- |
|
||
| 接口错误率 | 5 分钟内 > 5% | 查 trace → 定位依赖 → 必要时回滚 |
|
||
| 队列积压 | 单队列深度 > 1000 或等待 > 10 分钟 | 扩 worker / 查卡死任务 |
|
||
| AI 预算 | 达软限 80% 告警、硬限 100% 阻断 | 降级路由 / 通知负责人 |
|
||
| 任务失败率 | 10 分钟内 > 10% | 查供应商 / 依赖 → 切路由 |
|
||
| 磁盘 / 存储 | 使用率 > 80% | 清理 temp / 扩容 |
|
||
| 证书到期 | < 14 天 | 续签 |
|
||
| 抠图降级率 | 单批次 > 30% | 排查模型 / 输入质量 |
|
||
|
||
- `LOG-17` 每条告警必须可执行：附 runbook 链接（`docs/runbook/`）与负责人。
|
||
- `LOG-18` 禁止「告警风暴」：同一根因聚合，5 分钟内同一告警只发一次。
|
||
|
||
---
|
||
|
||
## 6 前端可观测
|
||
|
||
- `LOG-19` 前端错误上报必须带：`release` 版本、`trace_id`（若有）、路由、浏览器、是否客户数据脱敏。
|
||
- `LOG-20` 禁止上报用户隐私与客户素材内容；上报前统一脱敏。
|
||
- `LOG-21` 关键交互（生成、预览、勾选、导出）埋点事件名稳定，带 `customer_id` / `batch_id` / `user_id` 三维（PRD 8.1）。
|
||
|
||
---
|
||
|
||
## 7 检查清单
|
||
|
||
- [ ] 日志结构化，必带 `trace_id` / `module` / `action`
|
||
- [ ] `msg` 稳定可聚合，变量进字段
|
||
- [ ] 无敏感信息、无签名 URL、无 prompt 全文
|
||
- [ ] 跨队列传递 `traceparent`
|
||
- [ ] 审计与日志分离，关键操作全部入 `audit_logs`
|
||
- [ ] 新增关键路径有指标与告警
|
||
- [ ] 指标标签基数受控，派生指标不落库
|