DjangoAdmin_FastAPI_EleVue/docs/DEPLOYMENT.md

部署指南

本文档介绍 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. 克隆项目

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

2. 配置环境变量

cp .env.example .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. 安装依赖

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

# 或使用 Makefile
make install

4. 初始化数据库

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

# 或使用 Makefile
make db-init

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

python scripts/seed_dict.py
make seed-dict

6. 启动后端服务

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

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

7. 启动前端服务

cd ui
npm install
npm run dev

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

🐳 方式二：Docker Compose 部署

1. 配置环境变量

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. 构建并启动

docker-compose up --build -d

3. 查看日志

docker-compose logs -f fastapi_elevue

4. 停止服务

docker-compose down

Docker Compose 配置说明

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：

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 配置文件：

[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

# 启动
sudo supervisorctl start fastapi_elevue

# 查看状态
sudo supervisorctl status fastapi_elevue

# 重启
sudo supervisorctl restart fastapi_elevue

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;
    }
}

前端构建

cd ui

# 安装依赖
npm install

# 生产构建
npm run build

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

🗄️ 数据库配置

MySQL（默认）

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

PostgreSQL

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

安装驱动：

pip install "psycopg[binary]"

SQL Server

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

安装驱动：

pip install pymssql

Oracle

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

安装驱动：

pip install oracledb

SQLite

DB_DRIVER=sqlite
DB_NAME=djangoadmin.db

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

🔄 跨库数据迁移

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

# 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。

🧪 测试

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

# 单元测试
pytest tests/unit

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

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

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

🔍 健康检查

API 健康检查端点

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

# 检查 Redis 连接
redis-cli ping

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

日志查看

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

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

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

⚙️ 性能调优

数据库连接池

在 .env 中配置：

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

Redis 连接池

REDIS_MAX_CONNECTIONS=20

Uvicorn Worker

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

# 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 时自动调用刷新接口