477 lines
9.1 KiB
Markdown
477 lines
9.1 KiB
Markdown
# 部署指南
|
||
|
||
本文档介绍 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 时自动调用刷新接口
|