b715755b76
Some checks failed
Build and Deploy / test-backend (push) Has been cancelled
Build and Deploy / build-backend (push) Has been cancelled
Build and Deploy / build-admin (push) Has been cancelled
Deploy to Production / build-backend (push) Has been cancelled
Deploy to Production / deploy (push) Has been cancelled
Co-authored-by: Cursor <cursoragent@cursor.com>
60 lines
2.0 KiB
Markdown
60 lines
2.0 KiB
Markdown
# 环境配置说明
|
||
|
||
## 多环境与加载顺序
|
||
|
||
- **系统环境变量** 优先于任何文件。
|
||
- **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）
|
||
|
||
```bash
|
||
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 服务设置：
|
||
|
||
```yaml
|
||
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`。
|