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

# 部署 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.flask.naivevue DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;`
- [ ] 创建数据库用户并授权
- [ ] 修改 `.env` 中的数据库配置
- [ ] 初始化数据库：`python scripts/setup_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 app.py`
- [ ] 配置 Supervisor 进程管理
- [ ] 启动后端服务：`supervisorctl start flask`

**前端**：

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

### 第 4 阶段：Nginx 配置

```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:8021;
        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`
- [ ] 执行数据库迁移（如有）：`flask db upgrade`
- [ ] 重启后端服务：`supervisorctl restart flask`
- [ ] 检查日志：`tail -f logs/app.log`

### 前端更新

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

### 数据库迁移

- [ ] 备份数据库：`mysqldump -uroot -p djangoadmin.flask.naivevue > backup.sql`
- [ ] 执行迁移：`flask db upgrade`
- [ ] 验证迁移结果

## 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/setup_db.py`

## 监控 Checklist

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

## 安全 Checklist

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

## 回滚方案

### 后端回滚

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

# 回滚数据库迁移
flask db downgrade -1

# 重启服务
supervisorctl restart flask
```

### 前端回滚

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

### 数据库回滚

```bash
# 从备份恢复
mysql -uroot -p djangoadmin.flask.naivevue < backup.sql
```

## 总结

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