工程交付
Docker Compose 与可观测的本地交付
把 API、PostgreSQL、Redis 与观测组件组织成可重复启动的开发环境。
重点能力DockerOpenTelemetry
能在自己电脑运行，不等于别人能复现。项目需要固定依赖、健康检查、迁移命令和观测入口。
Compose 最小拓扑
api 依赖 postgres 和 redis，但启动顺序不能替代健康检查。数据库使用具名卷；应用镜像固定基础版本；配置来自环境变量；密钥只在本地 .env 或部署平台设置。
健康检查分层
- /live：进程是否存活，不访问外部依赖。
- /ready：数据库、缓存和关键配置是否就绪。
- 启动探针：迁移或模型加载期间延长容忍时间。
OpenTelemetry 信号
Trace 展示请求路径，Metric 汇总速率、错误和延迟，Log 记录离散事件。三者通过 trace_id 关联。优先给 HTTP、数据库、模型调用和工具调用建立 span。
可复现验收
在全新目录运行一条启动命令；等待健康检查通过；执行数据库迁移；发送样例请求；打开追踪查看完整链路；停止并重启后数据仍存在。
官方资料
Docker Compose Quickstart 展示多容器开发流程；OpenTelemetry Signals 定义 traces、metrics、logs 与 baggage。