# 环境规划

## 概述

 项目支持多环境部署，通过 `.env` 文件管理各环境的配置差异。合理的环境规划能确保开发、测试、生产环境的隔离性，降低配置错误导致的线上风险。

:::tip 核心原则
各环境之间保持代码一致，仅通过环境变量（`.env`）区分配置。禁止在代码中硬编码环境相关的值。
:::

## 环境划分

| 环境 | 用途 | 域名示例 | DEBUG | 数据库 | Redis | 日志级别 |
|------|------|---------|-------|--------|-------|---------|
| Dev（开发） | 本地开发调试 | localhost:8031 | True | 开发库 | 开发实例 | DEBUG |
| Test（测试） | 功能/集成测试 | test.example.com | False | 测试库 | 测试实例 | INFO |
| Prod（生产） | 正式对外服务 | www.example.com | False | 生产库 | 生产集群 | WARNING |

:::tip 环境隔离要求
1. 三个环境的数据库必须完全隔离，禁止共用同一库。
2. Redis 实例建议分离，避免测试数据污染生产缓存。
3. 生产环境的 `.env` 文件权限应设为 `600`，仅运行用户可读。
:::

## .env 配置示例

### Dev 环境

```bash
# 应用配置
FASTAPI_ENV=dev
FASTAPI_DEBUG=True
FASTAPI_DEMO=False
FASTAPI_PORT=8031

# 数据库配置
DB_DRIVER=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_USER=root
DB_PASS=root
DB_NAME=djangoadmin_dev
DB_PREFIX=fastapi_

# Redis 配置
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_DB=0

# JWT 配置
JWT_SALT=dev-salt-change-in-production
JWT_EXPIRE_MINUTES=1440
```

### Prod 环境

```bash
# 应用配置
FASTAPI_ENV=prod
FASTAPI_DEBUG=False
FASTAPI_DEMO=False
FASTAPI_PORT=8031

# 数据库配置
DB_DRIVER=mysql
DB_HOST=10.0.1.100
DB_PORT=3306
DB_USER=djangoadmin
DB_PASS=<强密码>
DB_NAME=djangoadmin_prod
DB_PREFIX=fastapi_

# Redis 配置
REDIS_HOST=10.0.1.101
REDIS_PORT=6379
REDIS_PASSWORD=<强密码>
REDIS_DB=0

# JWT 配置
JWT_SALT=<随机生成的64位字符串>
JWT_EXPIRE_MINUTES=720
```

:::tip 安全提醒
生产环境的 `JWT_SALT` 必须使用随机强密码（推荐 64 位以上），禁止与开发环境共用同一值。可通过以下命令生成：
```bash
python -c "import secrets; print(secrets.token_urlsafe(48))"
```
:::

## 环境切换机制

项目通过 `python-dotenv` 加载 `.env` 文件，启动时自动读取当前目录下的 `.env`：

```bash
# Dev：本地启动
python src/main.py

# Prod：指定 .env 路径（或在部署目录放置 .env）
cd /data/apps/djangoadmin && python src/main.py
```

:::tip Docker 环境
Docker 部署时，`docker-compose.yml` 通过 `env_file: .env` 注入环境变量，容器内无需额外配置。详见 [Docker容器化](/zh/volume6/docker) 章节。
:::

## 数据库驱动切换

通过 `DB_DRIVER` 环境变量切换数据库类型（配置在 `src/core/config/database.py`）：

| DB_DRIVER | 数据库 | 依赖包 | 连接串格式 |
|-----------|--------|--------|-----------|
| mysql（默认） | MySQL 8.x | PyMySQL | `mysql+pymysql://user:pass@host:3306/db` |
| postgresql | PostgreSQL 14+ | psycopg[binary] | `postgresql+psycopg://user:pass@host:5432/db` |
| mssql | SQL Server 2019+ | pymssql | `mssql+pymssql://user:pass@host:1433/db` |
| sqlite | SQLite 3 | 内置 | `sqlite:///path/to/db.sqlite3` |
| oracle | Oracle 12c+ | oracledb | `oracle+oracledb://user:pass@host:1521/db` |

:::tip 切换数据库后
切换数据库驱动后，需要重新初始化数据库结构。项目 Makefile 提供常用命令：
```bash
make db-init # 初始化数据库（建库 + SQL 导入 + 补表 + alembic stamp）
make migrate-revision # 生成增量迁移脚本
make migrate-upgrade # 应用迁移
make migrate-stamp # 标记当前库已到基线
make db-migrate ARGS="..." # 跨库数据迁移
```
:::

## 总结

环境规划的核心是隔离与一致性：代码统一，配置分离。通过 `.env` 文件管理各环境差异，`DB_DRIVER` 支持多数据库切换。生产环境务必关注安全配置（DEBUG=False、强密码、JWT_SALT 独立），确保线上服务稳定可靠。