# 部署指南

本文档介绍 DjangoAdmin FastAPI + EleVue 版本的多种部署方式，包括本地开发、Docker 容器化部署以及生产环境部署。


## 📋 环境要求

### 后端

| 依赖 | 最低版本 | 说明 |
|---|---|---|
| Python | 3.10+ | 推荐 3.11 或 3.12 |
| MySQL | 5.7+ | 默认数据库，推荐 8.0+ |
| PostgreSQL | 12+ | 可选，设置 `DB_DRIVER=postgresql` |
| SQL Server | 2017+ | 可选，设置 `DB_DRIVER=mssql` |
| Oracle | 19c+ | 可选，设置 `DB_DRIVER=oracle` |
| Redis | 6.0+ | 必需，用于缓存/会话/限流 |

### 前端

| 依赖 | 最低版本 | 说明 |
|---|---|---|
| Node.js | 18+ | 推荐 20 LTS |
| npm | 8+ | 或使用 pnpm / yarn |


## 🚀 方式一：本地开发环境

### 1. 克隆项目

```bash
git clone https://gitee.com/djangoadmin/DjangoAdmin_Fastapi_EleVue.git
cd DjangoAdmin_Fastapi_EleVue
```

### 2. 配置环境变量

```bash
cp .env.example .env
```

编辑 `.env` 文件，配置以下关键变量：

```env
# ============ 数据库配置 ============
DB_DRIVER=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_USER=root
DB_PASSWORD=your_password
DB_NAME=djangoadmin
DB_PREFIX=fastapi_

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

# ============ JWT 配置 ============
JWT_SALT=your-secret-key-change-in-production
JWT_EXPIRE_MINUTES=120

# ============ 应用配置 ============
APP_HOST=127.0.0.1
APP_PORT=8031
FASTAPI_DEMO=False
```

### 3. 安装依赖

```bash
# 运行 + 开发依赖
pip install -r requirements.txt -r requirements-dev.txt

# 或使用 Makefile
make install
```

### 4. 初始化数据库

```bash
# 自动建库 + 导入 SQL + 创建表 + Alembic stamp
python scripts/init_db.py

# 或使用 Makefile
make db-init
```

### 5. 初始化字典数据（可选）

```bash
python scripts/seed_dict.py
make seed-dict
```

### 6. 启动后端服务

```bash
python src/main.py
# 或使用 Makefile
make dev

# 默认监听 http://127.0.0.1:8031
# API 文档：http://127.0.0.1:8031/docs
```

### 7. 启动前端服务

```bash
cd ui
npm install
npm run dev

# 默认监听 http://localhost:3000
```


## 🐳 方式二：Docker Compose 部署

### 1. 配置环境变量

```bash
cp .env.example .env
# 编辑 .env，将 DB_HOST 和 REDIS_HOST 改为容器名或宿主机 IP
```

> ⚠️ Docker `host` 网络模式下，`DB_HOST` 和 `REDIS_HOST` 可直接使用 `127.0.0.1`。
> 若使用 `bridge` 网络模式，需改为 `host.docker.internal` 或宿主机实际 IP。

### 2. 构建并启动

```bash
docker-compose up --build -d
```

### 3. 查看日志

```bash
docker-compose logs -f fastapi_elevue
```

### 4. 停止服务

```bash
docker-compose down
```

### Docker Compose 配置说明

```yaml
services:
  fastapi_elevue:
    image: fastapi_elevue
    container_name: fastapi_elevue
    build:
      context: ./
      dockerfile: Dockerfile
    restart: always
    network_mode: host        # host 模式，直接连通宿主机网络
    ports:
      - 8031:8031             # bridge 模式下的端口映射
    volumes:
      - ./uploads:/data/apps/uploads  # 上传文件持久化
    env_file:
      - .env                  # 注入环境变量
    command: python src/main.py
    logging:
      driver: "json-file"
      options:
        max-size: "500m"      # 单个日志文件最大 500MB
        max-file: "10"        # 最多保留 10 个日志文件
```


## 🏭 方式三：生产环境部署

### 使用 Gunicorn + Uvicorn Worker

生产环境推荐使用 Gunicorn 管理 Uvicorn Worker：

```bash
pip install gunicorn

gunicorn main:app \
  --app-dir src \
  --workers 4 \
  --worker-class uvicorn.workers.UvicornWorker \
  --bind 0.0.0.0:8031 \
  --timeout 120 \
  --access-logfile - \
  --error-logfile -
```

**Worker 数量建议**：
- CPU 密集型：`workers = CPU 核心数 + 1`
- IO 密集型：`workers = CPU 核心数 * 2 + 1`
- 一般推荐：4 ~ 8 个 Worker

### 使用 Supervisor 进程管理

项目已提供 `deploy/supervisor.conf` 配置文件：

```ini
[program:fastapi_elevue]
command=/path/to/venv/bin/gunicorn main:app
    --app-dir /path/to/project/src
    --workers 4
    --worker-class uvicorn.workers.UvicornWorker
    --bind 0.0.0.0:8031
directory=/path/to/project
user=www
autostart=true
autorestart=true
redirect_stderr=true
stdout_logfile=/var/log/fastapi_elevue/stdout.log
stderr_logfile=/var/log/fastapi_elevue/stderr.log
```

```bash
# 启动
sudo supervisorctl start fastapi_elevue

# 查看状态
sudo supervisorctl status fastapi_elevue

# 重启
sudo supervisorctl restart fastapi_elevue
```

### Nginx 反向代理

```nginx
server {
    listen 80;
    server_name your-domain.com;

    # 前端静态文件
    location / {
        root /path/to/ui/dist;
        try_files $uri $uri/ /index.html;
    }

    # 后端 API 代理
    location /api/ {
        proxy_pass http://127.0.0.1:8031;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 120s;
    }

    # 上传文件访问
    location /uploads/ {
        alias /path/to/project/uploads/;
        expires 7d;
    }
}
```

### 前端构建

```bash
cd ui

# 安装依赖
npm install

# 生产构建
npm run build

# 构建产物在 ui/dist/ 目录
```


## 🗄️ 数据库配置

### MySQL（默认）

```env
DB_DRIVER=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_USER=root
DB_PASSWORD=your_password
DB_NAME=djangoadmin
```

### PostgreSQL

```env
DB_DRIVER=postgresql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=your_password
DB_NAME=djangoadmin
```

安装驱动：
```bash
pip install "psycopg[binary]"
```

### SQL Server

```env
DB_DRIVER=mssql
DB_HOST=127.0.0.1
DB_PORT=1433
DB_USER=sa
DB_PASSWORD=your_password
DB_NAME=djangoadmin
```

安装驱动：
```bash
pip install pymssql
```

### Oracle

```env
DB_DRIVER=oracle
DB_HOST=127.0.0.1
DB_PORT=1521
DB_USER=system
DB_PASSWORD=your_password
DB_NAME=ORCL
```

安装驱动：
```bash
pip install oracledb
```

### SQLite

```env
DB_DRIVER=sqlite
DB_NAME=djangoadmin.db
```

> 💡 SQLite 无需额外驱动，Python 内置支持。适合开发/测试环境。


## 🔄 跨库数据迁移

将现有 MySQL 数据迁移到其他数据库：

```bash
# 1. 干跑 — 只连接源库，逐表数行数，打印迁移计划
make db-migrate-dry-run ARGS="--src-driver=mysql --src-host=127.0.0.1 --src-db=djangoadmin --src-user=root --src-password=xxx --dst-driver=postgresql --dst-host=127.0.0.1 --dst-db=djangoadmin --dst-user=postgres --dst-password=xxx"

# 2. 正式迁移
make db-migrate ARGS="--src-driver=mysql --src-host=127.0.0.1 --src-db=djangoadmin --src-user=root --src-password=xxx --dst-driver=postgresql --dst-host=127.0.0.1 --dst-db=djangoadmin --dst-user=postgres --dst-password=xxx"

# 3. 幂等重跑（加 --drop-target-first）
make db-migrate ARGS="... --drop-target-first"
```

详细操作手册参阅 [数据库迁移 Runbook](../document/数据库迁移_runbook.md)。


## 🧪 测试

```bash
# 运行全部测试（默认跳过集成测试）
pytest

# 单元测试
pytest tests/unit

# 契约快照测试（守护路由/权限/表名）
pytest tests/contract -m contract

# 集成测试（需真实 MySQL/Redis）
pytest tests/integration -m integration

# 查看覆盖率
pytest --cov=src --cov-report=html
```


## 🔍 健康检查

### API 健康检查端点

```bash
# 检查后端服务是否正常
curl http://127.0.0.1:8031/api/v1/auth/captcha

# 检查 Redis 连接
redis-cli ping

# 检查 MySQL 连接
mysql -u root -p -e "SELECT 1"
```

### 日志查看

```bash
# 应用日志
tail -f logs/app.log

# 错误日志
tail -f logs/error.log

# Docker 日志
docker-compose logs -f --tail=100
```


## ⚙️ 性能调优

### 数据库连接池

在 `.env` 中配置：

```env
# 连接池大小
DB_POOL_SIZE=10
# 最大溢出连接数
DB_MAX_OVERFLOW=20
# 连接超时（秒）
DB_POOL_TIMEOUT=30
# 连接回收时间（秒）
DB_POOL_RECYCLE=1800
```

### Redis 连接池

```env
REDIS_MAX_CONNECTIONS=20
```

### Uvicorn Worker

根据服务器配置调整 Worker 数量：

```bash
# 4 核 8G 内存服务器
gunicorn main:app --app-dir src --workers 4 --worker-class uvicorn.workers.UvicornWorker

# 8 核 16G 内存服务器
gunicorn main:app --app-dir src --workers 8 --worker-class uvicorn.workers.UvicornWorker
```


## ❓ 常见问题

### Q: 数据库连接失败？

1. 检查数据库服务是否启动
2. 检查 `.env` 中的连接参数是否正确
3. 检查防火墙是否开放对应端口
4. 检查数据库用户是否有远程访问权限

### Q: Redis 连接失败？

1. 检查 Redis 服务是否启动：`redis-cli ping`
2. 检查 `.env` 中的 Redis 配置
3. 如设置了密码，确认 `REDIS_PASSWORD` 正确

### Q: 前端请求 404？

1. 确认后端服务已启动
2. 检查前端代理配置（`vite.config.ts` 中的 `proxy`）
3. 确认 API 前缀为 `/api/v1`

### Q: Token 过期后无法刷新？

1. 检查 Redis 是否正常运行（Token 黑名单存储在 Redis 中）
2. 确认 `JWT_EXPIRE_MINUTES` 配置合理
3. 前端应在收到 401 时自动调用刷新接口