7277b9c558
Critical修复： - CI配置MySQL→PostgreSQL对齐架构决策 - 错误码格式统一为分段格式(系统-模块-分类-序号) - 覆盖率指标统一(Domain 90%/Application 80%/新增 90%) Major修复： - 分支策略统一为trunk-based，去掉develop分支 - muse-studio部署描述修正为Vite SPA静态部署 - muse-studio提交类型统一为英文前缀 - API路径统一为/app-api，端口对齐48080 - DROP COLUMN措辞修正为条件性禁止 - 增加规范优先级声明 新增文档： - 05-安全开发规范.md（认证授权/输入校验/AI安全/审计） - 06-日志与可观测性规范.md（日志级别/结构化/链路追踪/监控） - muse-admin测试编写指南
101 lines
2.8 KiB
Markdown
101 lines
2.8 KiB
Markdown
# 日志与可观测性规范
|
||
|
||
## 1. 日志级别标准
|
||
|
||
| 级别 | 使用场景 | 示例 |
|
||
|------|----------|------|
|
||
| ERROR | 需要人工介入的故障 | 数据库连接失败、外部服务不可达、数据不一致 |
|
||
| WARN | 异常但可自动恢复 | 重试成功、降级触发、接近阈值 |
|
||
| INFO | 关键业务事件 | 用户登录、作品创建、AI 生成完成、支付成功 |
|
||
| DEBUG | 开发调试信息 | 方法入参、中间状态、SQL 语句 |
|
||
|
||
规则：
|
||
- 生产环境默认 INFO 级别
|
||
- ERROR 必须包含异常堆栈和上下文
|
||
- 禁止在循环中打 INFO/WARN 日志
|
||
- DEBUG 日志使用条件判断或 SLF4J 占位符，避免字符串拼接开销
|
||
|
||
## 2. 结构化日志格式
|
||
|
||
后端使用 JSON 格式输出：
|
||
|
||
```json
|
||
{
|
||
"timestamp": "2024-01-01T12:00:00.000Z",
|
||
"level": "INFO",
|
||
"traceId": "abc123",
|
||
"spanId": "def456",
|
||
"service": "muse-cloud",
|
||
"module": "content",
|
||
"message": "作品创建成功",
|
||
"userId": 12345,
|
||
"workId": 67890,
|
||
"duration": 150
|
||
}
|
||
```
|
||
|
||
前端错误上报格式：
|
||
|
||
```json
|
||
{
|
||
"timestamp": "...",
|
||
"level": "ERROR",
|
||
"source": "muse-studio",
|
||
"page": "/works/123/editor",
|
||
"message": "Block 保存失败",
|
||
"error": "NetworkError: timeout",
|
||
"userId": 12345,
|
||
"context": { "blockId": "...", "revision": 5 }
|
||
}
|
||
```
|
||
|
||
## 3. 敏感信息脱敏
|
||
|
||
日志中禁止出现：
|
||
- 密码、token、密钥的明文
|
||
- 完整的身份证号、银行卡号
|
||
- 用户的完整手机号、邮箱
|
||
|
||
脱敏规则：
|
||
- 手机号：138****1234
|
||
- 邮箱：u***@example.com
|
||
- token：前 4 位 + ****
|
||
|
||
## 4. 链路追踪
|
||
|
||
- 使用 traceId 贯穿请求全链路（网关 → 服务 → 数据库 → 外部调用）
|
||
- 前端请求携带 X-Request-Id header
|
||
- 异步任务继承父任务的 traceId
|
||
- SSE 连接使用 connectionId 关联同一会话的所有事件
|
||
|
||
## 5. 前端错误监控
|
||
|
||
- 全局错误边界捕获未处理异常
|
||
- API 请求失败自动上报（排除 4xx 客户端错误中的 401/403）
|
||
- 编辑器崩溃单独上报（含 Block 状态快照）
|
||
- 性能指标上报：FCP、LCP、CLS
|
||
|
||
## 6. 后端监控指标
|
||
|
||
关键指标：
|
||
- API 响应时间（P50/P95/P99）
|
||
- 错误率（5xx / 总请求）
|
||
- AI 生成延迟（首 token 时间、总生成时间）
|
||
- 数据库连接池使用率
|
||
- 消息队列积压量
|
||
|
||
告警阈值建议：
|
||
- API P99 > 3s：WARN
|
||
- API P99 > 10s：ERROR
|
||
- 错误率 > 1%：WARN
|
||
- 错误率 > 5%：ERROR
|
||
- DB 连接池 > 80%：WARN
|
||
|
||
## 7. Agent 日志行为规则
|
||
|
||
- 关键业务操作必须打 INFO 日志（创建、修改、删除、状态变更）
|
||
- 外部调用（AI API、文件存储、消息队列）必须打日志（入参摘要 + 耗时 + 结果）
|
||
- 异常处理必须打 ERROR 日志（含堆栈和上下文）
|
||
- 不在日志中输出大段正文内容（截取前 100 字符）
|
||
- 不在日志中输出完整的 AI prompt（只记录 token 数和模型名）
|