BUG-0345project-11高待处理deploy

compose --env-file 不等于容器环境变量 —— 密钥写进 .env.prod 后端永远读不到

发现：2026-10-01验证：2026-10-09置信度：95%

症状

按 Runbook 把密钥追加进 .env.prod 并重建容器后，应用仍然读不到密钥——排查时容易误判为 key 无效或加载逻辑问题。

根因

docker compose 的 --env-file 只用于 compose 文件本身的 ${VAR} 插值，【不会】注入容器环境；容器只拿到 environment:（或 env_file:）里显式声明的变量。漏写透传行时故障被延迟暴露，且与『key 无效』症状混在一起。

修复方案

1) compose 的 backend.environment 显式加透传行（如 BAILIAN_API_KEY、SETTINGS_ENCRYPTION_KEY）； 2) 验收锚点改为容器内实测：docker compose exec backend env | grep <KEY>； 3) Runbook 中所有『写入 .env.prod』的步骤后必须跟一步容器内可见性验证。

检测命令

docker compose exec <svc> sh -c 'env | grep -c <KEY_NAME>'  # 0 即未透传

修复命令

在 compose 服务 environment: 段补 <KEY_NAME>: ${<KEY_NAME>:-} 后 up -d 重建

错误签名

.env.prod 已写入 API_KEY；容器内 env 无此变量；/ai/models 报无可用 provider

技术信息

来源项目

project-11

涉及文件

docker-compose.prod.yml

标签

docker-compose, env-file, container-env, api-key, runbook