本章概要

从服务器准备到应用上线的完整部署操作清单，适用于生产环境首次部署和后续版本更新。

部署 Checklist

本章提供从服务器准备到应用上线的完整部署操作清单，适用于生产环境首次部署和后续版本更新。

首次部署 Checklist

第 1 阶段：服务器准备

• [ ] 服务器操作系统：CentOS 7+ / Ubuntu 20.04+ / Debian 11+
• [ ] 防火墙开放端口：80（HTTP）、443（HTTPS）、22（SSH）
• [ ] 创建部署用户（非 root）
• [ ] 配置 SSH 密钥登录
• [ ] 配置时区：timedatectl set-timezone Asia/Shanghai

第 2 阶段：环境安装

Python 环境：

• [ ] 安装 Python 3.12+
• [ ] 安装 pip：apt install python3-pip 或 yum install python3-pip
• [ ] 创建虚拟环境：python3 -m venv /opt/venv
• [ ] 激活虚拟环境：source /opt/venv/bin/activate
• [ ] 安装依赖：pip install -r requirements.txt

数据库：

• [ ] 安装 MySQL 8.0+
• [ ] 创建数据库：CREATE DATABASE djangoadmin.fastapi.elevue DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
• [ ] 创建数据库用户并授权
• [ ] 修改 .env 中的数据库配置
• [ ] 初始化数据库：python scripts/init_db.py

Redis：

• [ ] 安装 Redis 6.0+
• [ ] 配置密码
• [ ] 修改 .env 中的 Redis 配置
• [ ] 测试连接：redis-cli ping

Node.js（前端构建）：

• [ ] 安装 Node.js 18+
• [ ] 安装 pnpm：npm install -g pnpm
• [ ] 安装前端依赖：cd ui && pnpm install
• [ ] 构建前端：pnpm build

第 3 阶段：应用部署

后端：

• [ ] 上传项目代码到服务器
• [ ] 配置 .env 文件（数据库、Redis、JWT_SALT 等）
• [ ] 生成 JWT 密钥：python -c "import secrets; print(secrets.token_urlsafe(48))"
• [ ] 测试启动：python src/main.py
• [ ] 配置 Supervisor 进程管理
• [ ] 启动后端服务：supervisorctl start fastapi

前端：

• [ ] 构建产物上传到服务器（ui/dist/ 目录）
• [ ] 配置 Nginx 指向前端产物目录
• [ ] 配置 Nginx 反向代理后端 API

第 4 阶段：Nginx 配置

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

    # 前端静态文件
    root /opt/project/ui/dist;
    index index.html;

    # 前端路由
    location / {
        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;
    }

    # 上传文件访问
    location /uploads/ {
        alias /opt/project/uploads/;
        expires 30d;
    }
}

• [ ] 配置 Nginx
• [ ] 测试 Nginx 配置：nginx -t
• [ ] 重载 Nginx：nginx -s reload

第 5 阶段：SSL 证书（推荐）

• [ ] 申请 SSL 证书（Let's Encrypt / 购买）
• [ ] 配置 HTTPS
• [ ] 配置 HTTP 自动跳转 HTTPS
• [ ] 测试 HTTPS 访问

第 6 阶段：验证

• [ ] 访问前端页面，确认正常加载
• [ ] 登录测试（admin / 123456）
• [ ] 修改默认密码
• [ ] 测试核心功能（用户管理、角色管理等）
• [ ] 检查后端日志：tail -f logs/app.log
• [ ] 检查 Supervisor 状态：supervisorctl status

版本更新 Checklist

后端更新

• [ ] 拉取最新代码：git pull origin main
• [ ] 安装新依赖（如有）：pip install -r requirements.txt
• [ ] 执行数据库迁移（如有）：alembic upgrade head
• [ ] 重启后端服务：supervisorctl restart fastapi
• [ ] 检查日志：tail -f logs/app.log

前端更新

• [ ] 拉取最新代码：git pull origin main
• [ ] 安装新依赖（如有）：pnpm install
• [ ] 构建前端：pnpm build
• [ ] 替换服务器上的 ui/dist/ 目录
• [ ] 清除浏览器缓存测试

数据库迁移

• [ ] 备份数据库：mysqldump -uroot -p djangoadmin.fastapi.elevue > backup.sql
• [ ] 执行迁移：alembic upgrade head
• [ ] 验证迁移结果

Docker 部署 Checklist

• [ ] 安装 Docker 和 Docker Compose
• [ ] 配置 .env 文件
• [ ] 构建镜像：docker-compose build
• [ ] 启动服务：docker-compose up -d
• [ ] 检查容器状态：docker-compose ps
• [ ] 查看日志：docker-compose logs -f
• [ ] 初始化数据库（首次）：docker-compose exec app python scripts/init_db.py

监控 Checklist

• [ ] 配置健康检查端点
• [ ] 配置日志轮转（logrotate）
• [ ] 配置数据库自动备份（cron）
• [ ] 配置 Redis 持久化（AOF/RDB）
• [ ] 配置磁盘空间监控
• [ ] 配置内存使用监控

安全 Checklist

• [ ] 修改默认密码（admin / 123456）
• [ ] 设置强密码的 JWT_SALT
• [ ] 设置 FASTAPI_DEBUG=False
• [ ] 设置 FASTAPI_DEMO=False（生产环境）
• [ ] 配置 CORS 白名单（非 *）
• [ ] 配置 HTTPS
• [ ] 关闭不必要的端口
• [ ] 定期更新系统和依赖包

回滚方案

后端回滚

# 回滚代码
git checkout <上一个稳定版本tag>

# 回滚数据库迁移
alembic downgrade -1

# 重启服务
supervisorctl restart fastapi

前端回滚

# 替换为上一版本的构建产物
cp -r /opt/backup/dist /opt/project/ui/dist

数据库回滚

# 从备份恢复
mysql -uroot -p djangoadmin.fastapi.elevue < backup.sql

总结

部署 Checklist 覆盖了从服务器准备到应用上线的完整流程。首次部署建议按顺序逐项检查，版本更新时使用更新 Checklist 快速操作。生产环境务必做好备份和监控。