部署故障排查

容器启动失败

现象： docker run 后容器立即退出。

排查步骤：

1. 查看容器日志：docker logs <container-id>。
2. 确认 dab-config.json 已正确复制到镜像中。检查 Dockerfile 中的 COPY 指令路径。
3. 确认容器能访问数据库——host.docker.internal 在 Linux Docker 上可能需要额外配置 --add-host。
4. 连接字符串中的环境变量是否能被容器读取——docker run -e SQL_CONN_STRING="..."。

端口冲突

现象： 启动时报 address already in use。

解决方案：

1. 更换宿主机映射端口：docker run -p 5001:5000 ...（宿主机 5001 映射到容器 5000）。
2. 或修改数据墙DBW 的监听端口：在配置中添加 "urls": "http://localhost:5001"。
3. 检查是否已有其他进程占用目标端口：netstat -ano | findstr :5000（Windows）/ lsof -i :5000（Linux/macOS）。

健康检查失败

现象： 容器健康检查（/health）不通过，容器被标记为 unhealthy。

排查步骤：

1. 手动访问 /health 端点确认返回状态：curl http://localhost:5000/health。
2. 确认 runtime.health.enabled 未被设为 false。
3. 确认数据库连接正常——数据源健康检查失败是 /health 返回 unhealthy 的最常见原因。
4. 检查 cache-ttl-seconds 是否过短导致频繁检查，但不会导致失败。

Docker 健康检查配置

docker run \
  --health-cmd="curl -f http://localhost:5000/health || exit 1" \
  --health-interval=30s \
  --health-timeout=5s \
  --health-retries=3 \
  ...

确认 curl 在容器镜像中可用（部分精简镜像不包含 curl，可改用 wget）。

Kubernetes 部署问题

Pod 反复重启

排查步骤：

1. kubectl describe pod <pod-name> 查看事件和退出原因。
2. kubectl logs <pod-name> 查看启动日志。
3. 确认 ConfigMap 正确挂载——文件路径和 subPath 是否正确。
4. 确认 Secret 中的环境变量能被容器读取。

就绪探测失败

现象： Pod 处于 Running 状态但 READY 0/1，不接收流量。

排查步骤：

1. 确认 /health 端点返回 Healthy。
2. 确认 readinessProbe 的 httpGet.path 和 port 配置正确。
3. 确认 initialDelaySeconds 足够长——数据库连接慢时可能需要更长的初始化时间。

ConfigMap 更新不生效

原因： ConfigMap 变更后 Pod 不会自动重启。

解决： 执行 kubectl rollout restart deployment <deployment-name> 触发滚动重启。

Docker Compose 部署问题

服务间无法通信

排查步骤：

1. 确认服务在同一 Docker 网络或默认 Compose 网络中。
2. 容器间通信使用服务名而非 localhost。例如：Server=db,1433，不是 Server=localhost,1433。
3. depends_on 只保证启动顺序，不等待服务就绪。数据库启动较慢时，数据墙DBW 可能启动过早。

环境变量中 @env() 与 Compose 的 @env() 冲突

Docker Compose 的 environment 中 @env('VAR') 会被 Compose 的变量插值语法误解。在 Compose 中应直接写完整的连接字符串而非数据墙DBW 的 @env() 语法：

# 正确：Compose 直接写值
environment:
  SQL_CONN_STRING: "Server=db;Database=mydb;..."

# 配置文件中仍然使用 @env()
# "connection-string": "@env('SQL_CONN_STRING')"

反向代理和 HTTPS 问题

代理后返回 HTTP 而非 HTTPS

原因： 代理与数据墙DBW 之间是 HTTP 通信，数据墙DBW 返回的 Location 头或 nextLink 使用 HTTP。

解决： 在代理中设置转发头：

proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host $host;

CORS 错误经过代理后仍存在

排查步骤：

1. 确认代理是否正确传递了 Origin 头。
2. 检查数据墙DBW 的 cors.origins 是否包含了前端域名（而非代理域名）。
3. 本地开发中可以暂时用 "origins": ["*"] 排除 CORS 问题。

资源不足

现象： 容器运行缓慢、OOM（内存溢出）被杀、或请求超时。

解决：

• 增加容器内存限制：--memory="512m"。
• 监控数据库连接池使用情况——大量并发请求可能耗尽连接池。
• 启用缓存（L1 + L2）减少数据库查询频率。
• 水平扩展实例数量。

日志不输出

排查步骤：

1. 确认日志级别不是 None。
2. 生产模式（host.mode: production）默认日志级别为 Error，可能看不到 Info/Debug 级别信息。临时调至 --LogLevel Information 排查。
3. 容器中确认 stdout 未被重定向。
4. 如果配置了 runtime.telemetry.file.path，确认日志文件路径可写。

下一步

• 数据库连接故障排查 — 数据库相关问题。
• 配置故障排查 — 配置文件错误。