wecom-ai-assistant/backend/docs/config.md

环境配置说明

多环境与加载顺序

• 系统环境变量 优先于任何文件。
• config/settings.py 会按 ENV 选择 dotenv 文件，再统一从环境变量或 DB_* 拼接数据库 URL。
• 若已设置 DATABASE_URL / DATABASE_URL_SYNC，则直接使用，否则用 DB_HOST、DB_PORT、DB_USER、DB_PASSWORD、DB_NAME 自动拼接。

环境与文件

环境	建议使用的文件	说明
dev	.env.dev	本地开发，DB_HOST=localhost
prod / Docker	.env.prod 或 compose 传入的 env	容器内 DB_HOST=db（compose 服务名）
任意	.env	可选，可覆盖部分变量

使用方式

本地开发（dev）

cd backend
cp .env.example .env.dev   # 首次可复制后按需修改
# 可选：设置 ENV=dev 以显式加载 .env.dev
export ENV=dev
# 或直接依赖系统已设置的 DB_* / DATABASE_URL
alembic upgrade head
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

使用 .env.dev 时，默认 DB_HOST=localhost，数据库连接本机 PostgreSQL。

Docker / 生产（prod）

• 在 docker-compose 或 k8s 中通过环境变量传入配置，不要写死 localhost。

• 示例：在 compose 中为 backend 服务设置：

  environment:
    - DB_HOST=db
    - DB_PORT=5432
    - DB_USER=wecom
    - DB_PASSWORD=xxx
    - DB_NAME=wecom_ai
  

  或使用 env_file: .env.prod（.env.prod 中 DB_HOST=db）。

• 容器内应用和 Alembic 迁移都会使用上述变量；不再依赖 localhost。

CI/CD

• 在流水线中设置 DB_HOST、DB_PORT、DB_USER、DB_PASSWORD、DB_NAME，或直接设置 DATABASE_URL / DATABASE_URL_SYNC。
• 无需在代码或镜像中写死数据库地址。

向后兼容

• 若仍在使用旧版只配置 DATABASE_URL 的 .env，无需修改，会继续生效。
• 未设置 DATABASE_URL 时，将使用 DB_* 拼接；未设置 DB_NAME 时默认库名为 wecom_ai。