hms/docs/archive/superpowers-completed/2026-04-26-observability-and-ops.md

可观测性与运维基础设施实施计划

设计规格: docs/superpowers/specs/2026-04-26-observability-and-ops-design.md 日期: 2026-04-26 | 总周期: 7-9 天

---

Phase 1: 健康检查 + Prometheus 指标（Day 1-2）

Task 1: 深度健康检查端点

涉及文件:

• 修改: crates/erp-server/src/handlers/health.rs

步骤:

1. 拆分为两个端点：
   • GET /health/live — 存活探针（仅返回 { status: "ok" }，不依赖任何外部服务）
   • GET /health/ready — 就绪探针（验证 DB ping + Redis ping + 模块状态）
2. /health/ready 实现：

async fn health_ready(State(state): State<AppState>) -> Json<HealthResponse> {
    let db_ok = sql_query("SELECT 1").execute(&state.db).await.is_ok();
    let redis_ok = state.redis.ping().await.is_ok();
    Json(HealthResponse { status: if db_ok && redis_ok { "ok" } else { "degraded" }, db: db_ok, redis: redis_ok, ... })
}

3. 保持旧 GET /health 兼容（重定向到 /health/ready）

验收: /health/ready 在 DB/Redis 正常时返回 200，任一不可达时返回 503 + 降级详情

Task 2: Prometheus 指标基础

涉及文件:

• 修改: crates/erp-server/Cargo.toml（添加 metrics + metrics-exporter-prometheus 依赖）
• 新增: crates/erp-server/src/middleware/metrics.rs
• 修改: crates/erp-server/src/main.rs（注册 metrics middleware + 路由）

步骤:

1. 在 Cargo.toml 添加:

metrics = "0.24"
metrics-exporter-prometheus = "0.16"

2. 创建 metrics.rs Axum middleware：
   • 记录每个请求的 http_request_duration_seconds（直方图，按 method/path/status 标签）
   • 记录 http_requests_total（计数器）
3. 在 main.rs 启动 Prometheus exporter（/metrics 端点，端口 9090）
4. 在 AppState 中注册 metrics recorder

验收: curl localhost:9090/metrics 返回 Prometheus 格式指标，包含请求延迟直方图

Task 3: DB 连接池 + EventBus 积压指标

涉及文件:

• 修改: crates/erp-server/src/main.rs
• 修改: crates/erp-core/src/events.rs

步骤:

1. DB 连接池指标：每 30 秒采样 db_pool_connections_active / db_pool_connections_idle
2. EventBus 积压指标：在 publish() 中递增 eventbus_pending_total，在 relay 处理后递减
3. 在 /metrics 端点暴露

验收: /metrics 包含 DB 连接池使用率和事件积压计数

---

Phase 2: OpenTelemetry + 生产 Docker（Day 3-5）

Task 4: OpenTelemetry 条件集成

涉及文件:

• 修改: crates/erp-server/Cargo.toml（添加 opentelemetry + tracing-opentelemetry + opentelemetry-otlp，optional feature）
• 新增: crates/erp-server/src/telemetry.rs
• 修改: crates/erp-server/src/main.rs

步骤:

1. 添加 optional 依赖:

[features]
tracing = ["opentelemetry", "tracing-opentelemetry", "opentelemetry-otlp"]

2. 创建 telemetry.rs：条件初始化 OpenTelemetry tracer（环境变量 ERP__TELEMETRY__ENABLED=true 时启用）
3. 配置 OTLP exporter（默认 http://localhost:4317，可通过环境变量覆盖）
4. 在 main.rs 的 tracing subscriber 中条件注册 OpenTelemetry layer
5. 在 SeaORM 的 DatabaseConnection 包装中添加 span（记录查询耗时）

验收: 启用后 Jaeger/Tempo 可看到请求 → SQL 查询 → 事件发布的完整链路；不启用时零开销

Task 5: 生产 Docker 多阶段构建

涉及文件:

• 新增: Dockerfile（项目根目录）
• 新增: docker/docker-compose.production.yml

步骤:

1. 多阶段 Dockerfile:

# Stage 1: Build
FROM rust:1.82-bookworm AS builder
COPY . /app
RUN cargo build --release -p erp-server

# Stage 2: Runtime
FROM debian:bookworm-slim
COPY --from=builder /app/target/release/erp-server /usr/local/bin/
COPY --from=builder /app/crates/erp-server/config/default.toml /etc/erp/config.toml
EXPOSE 3000 9090
CMD ["erp-server"]

2. docker-compose.production.yml:
   • erp-server 服务（限制 1 CPU / 512MB）
   • PostgreSQL 16 + Redis 7 作为独立服务
   • 健康检查配置（使用 /health/ready）
   • 环境变量注入（JWT secret / DB URL / Redis URL 通过 secrets）

验收: docker build -t hms-server . 成功，运行时镜像 < 80MB

Task 6: 前端生产构建 + Nginx

涉及文件:

• 新增: apps/web/Dockerfile
• 新增: apps/web/nginx.conf

步骤:

1. 多阶段构建：node 构建 → nginx 运行
2. Nginx 配置：SPA fallback + /api 代理到后端 3000 端口

验收: Docker 内前端可正常访问，API 代理工作

---

Phase 3: 日志聚合 + 告警（Day 5-7）

Task 7: Grafana Loki 日志集成

涉及文件:

• 新增: docker/loki-config.yaml
• 修改: docker/docker-compose.production.yml

步骤:

1. 在 production compose 中添加 Loki + Promtail 服务
2. Promtail 配置：读取 erp-server 的 JSON 日志输出
3. Grafana 数据源配置：Loki + Prometheus

验收: Grafana 可查询和过滤后端日志

Task 8: Prometheus 告警规则

涉及文件:

• 新增: docker/alert-rules.yml

步骤:

1. 定义 5 条告警规则:

- alert: HighRequestLatency    # P95 > 2s 持续 5 分钟
- alert: HighErrorRate          # 5xx 比率 > 5% 持续 3 分钟
- alert: EventBusBacklog        # 积压事件 > 100 持续 5 分钟
- alert: DatabasePoolExhausted  # 活跃连接 > 90% 持续 2 分钟
- alert: HealthCheckDegraded    # /health/ready 非 ok 持续 1 分钟

2. 配置 Alertmanager 通知渠道（Webhook/邮件）

验收: 触发告警条件时 Alertmanager 发送通知

Task 9: Grafana Dashboard 模板

涉及文件:

• 新增: docker/grafana/dashboards/hms-overview.json

步骤:

1. 创建 HMS Overview Dashboard，包含面板：
   • 请求速率 + 延迟分布（P50/P95/P99）
   • 错误率趋势（按 status code 分组）
   • DB 连接池使用率
   • EventBus 发布/消费速率
   • 健康检查状态

验收: Dashboard 展示实时指标

Task 10: 运维文档

涉及文件:

• 新增: wiki/observability.md

步骤:

1. 记录监控端点（/health/live, /health/ready, /metrics）
2. 记录告警规则和响应流程
3. 记录日志查询方法（Grafana Loki）
4. 记录 Docker 部署命令

验收: 新团队成员可通过文档独立部署和排查问题

---

执行原则

1. 条件编译 — OpenTelemetry 使用 feature gate，不启用时零开销
2. 渐进式 — Phase 1 可独立上线（无外部依赖），Phase 2/3 需要 Docker 环境
3. 性能优先 — 指标收集使用 metrics crate 的无锁实现，不影响请求延迟
4. 端口分离 — 业务 API (3000) + Metrics (9090) 分离，避免暴露内部指标