签入版本

2026-09-12 23:12:15 +08:00
commit 91998056ca
1841 changed files with 341325 additions and 0 deletions
@@ -0,0 +1,695 @@
+:::tip 本章概要
+生产环境部署实战指南，包含完整的部署流程、配置示例、常见问题处理和性能优化建议。基于实际生产环境经验总结。
+:::
+
+# 生产环境部署实战
+
+本文档提供从零开始的生产环境部署实战指南，包含完整的命令操作、配置文件和常见问题处理。
+
+## 环境准备
+
+### 服务器配置建议
+
+| 项目 | 最低配置 | 推荐配置 |
+|:---|:---|:---|
+| CPU | 2 核 | 4 核 |
+| 内存 | 2 GB | 4 GB |
+| 磁盘 | 40 GB SSD | 100 GB SSD |
+| 操作系统 | Ubuntu 20.04 / CentOS 7 | Ubuntu 22.04 / CentOS 8 |
+
+### 一键安装依赖（Ubuntu）
+
+```bash
+#!/bin/bash
+# install_deps.sh - Ubuntu 22.04 一键安装依赖
+
+# 更新系统
+sudo apt update && sudo apt upgrade -y
+
+# 安装 Python 3.11
+sudo apt install -y python3.11 python3.11-venv python3-pip
+
+# 安装 MySQL 8.0
+sudo apt install -y mysql-server
+sudo systemctl start mysql
+sudo systemctl enable mysql
+
+# 安装 Redis
+sudo apt install -y redis-server
+sudo systemctl start redis-server
+sudo systemctl enable redis-server
+
+# 安装 Nginx
+sudo apt install -y nginx
+sudo systemctl start nginx
+sudo systemctl enable nginx
+
+# 安装 Supervisor
+sudo apt install -y supervisor
+sudo systemctl start supervisor
+sudo systemctl enable supervisor
+
+# 安装 Node.js 18
+curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
+sudo apt install -y nodejs
+sudo npm install -g pnpm
+
+echo "依赖安装完成！"
+```
+
+### 一键安装依赖（CentOS）
+
+```bash
+#!/bin/bash
+# install_deps.sh - CentOS 8 一键安装依赖
+
+# 安装 Python 3.11
+sudo dnf install -y python3.11 python3.11-pip
+
+# 安装 MySQL 8.0
+sudo dnf install -y mysql-server
+sudo systemctl start mysqld
+sudo systemctl enable mysqld
+
+# 安装 Redis
+sudo dnf install -y redis
+sudo systemctl start redis
+sudo systemctl enable redis
+
+# 安装 Nginx
+sudo dnf install -y nginx
+sudo systemctl start nginx
+sudo systemctl enable nginx
+
+# 安装 Supervisor
+sudo dnf install -y supervisor
+sudo systemctl start supervisord
+sudo systemctl enable supervisord
+
+# 安装 Node.js 18
+curl -fsSL https://rpm.nodesource.com/setup_18.x | sudo bash -
+sudo dnf install -y nodejs
+sudo npm install -g pnpm
+
+echo "依赖安装完成！"
+```
+
+## 数据库配置
+
+### MySQL 生产环境配置
+
+```ini
+# /etc/mysql/mysql.conf.d/mysqld.cnf
+[mysqld]
+# 基础配置
+port = 3306
+bind-address = 127.0.0.1
+character-set-server = utf8mb4
+collation-server = utf8mb4_general_ci
+
+# 连接配置
+max_connections = 200
+wait_timeout = 600
+interactive_timeout = 600
+
+# 缓冲配置
+innodb_buffer_pool_size = 1G  # 建议为物理内存的 50-70%
+innodb_log_file_size = 256M
+innodb_flush_log_at_trx_commit = 1
+
+# 慢查询日志
+slow_query_log = 1
+slow_query_log_file = /var/log/mysql/slow.log
+long_query_time = 2
+```
+
+### 创建数据库和用户
+
+```sql
+-- 登录 MySQL
+mysql -uroot -p
+
+-- 创建数据库
+CREATE DATABASE `djangoadmin.flask.elevue` 
+  DEFAULT CHARACTER SET utf8mb4 
+  COLLATE utf8mb4_general_ci;
+
+-- 创建专用用户（生产环境不要用 root）
+CREATE USER 'flask_user'@'localhost' IDENTIFIED BY 'YourStrongPassword123!';
+GRANT ALL PRIVILEGES ON `djangoadmin.flask.elevue`.* TO 'flask_user'@'localhost';
+FLUSH PRIVILEGES;
+
+-- 导入数据
+USE `djangoadmin.flask.elevue`;
+SOURCE /opt/project/document/mysql/djangoadmin.flask.elevue.sql;
+```
+
+## Redis 配置
+
+### 生产环境配置
+
+```ini
+# /etc/redis/redis.conf
+# 绑定地址
+bind 127.0.0.1
+
+# 密码（生产环境必须设置）
+requirepass YourRedisPassword123!
+
+# 内存配置
+maxmemory 256mb
+maxmemory-policy allkeys-lru
+
+# 持久化
+appendonly yes
+appendfsync everysec
+
+# 连接超时
+timeout 300
+```
+
+## 项目部署
+
+### 部署目录结构
+
+```
+/opt/project/
+├── src/                  # 后端源码
+├── config/               # 配置模块
+├── static/               # 静态资源
+├── uploads/              # 上传文件目录
+├── logs/                 # 日志目录
+├── ui/                   # 前端源码
+│   └── dist/             # 前端构建产物
+├── document/             # 数据库脚本
+├── scripts/              # 工具脚本
+├── app.py                # 应用入口
+├── requirements.txt      # Python 依赖
+├── .env                  # 环境变量
+└── gunicorn.conf.py      # Gunicorn 配置
+```
+
+### 后端部署
+
+```bash
+# 1. 创建部署目录
+sudo mkdir -p /opt/project
+sudo chown $USER:$USER /opt/project
+
+# 2. 上传项目代码
+# scp -r ./project/* user@server:/opt/project/
+
+# 3. 创建虚拟环境
+cd /opt/project
+python3.11 -m venv venv
+source venv/bin/activate
+
+# 4. 安装依赖
+pip install -r requirements.txt
+pip install gunicorn
+
+# 5. 配置环境变量
+cp .env.example .env
+# 编辑 .env 文件，配置数据库、Redis、JWT_SALT 等
+
+# 6. 创建必要目录
+mkdir -p uploads logs
+
+# 7. 初始化数据库
+python scripts/setup_db.py
+
+# 8. 测试启动
+python app.py
+```
+
+### Gunicorn 配置
+
+```python
+# gunicorn.conf.py
+import multiprocessing
+
+# 绑定地址
+bind = "127.0.0.1:8021"
+
+# 工作进程数（建议 CPU 核心数 * 2 + 1）
+workers = multiprocessing.cpu_count() * 2 + 1
+
+# 工作模式
+worker_class = "sync"
+
+# 超时时间
+timeout = 120
+
+# 最大请求数（防止内存泄露）
+max_requests = 1000
+max_requests_jitter = 50
+
+# 日志配置
+accesslog = "/opt/project/logs/access.log"
+errorlog = "/opt/project/logs/error.log"
+loglevel = "info"
+
+# 进程名称
+proc_name = "flask_app"
+
+# 预加载应用
+preload_app = True
+```
+
+### Supervisor 配置
+
+```ini
+# /etc/supervisor/conf.d/flask.conf
+[program:flask]
+command=/opt/project/venv/bin/gunicorn -c gunicorn.conf.py app:app
+directory=/opt/project
+user=www-data
+autostart=true
+autorestart=true
+redirect_stderr=true
+stdout_logfile=/opt/project/logs/supervisor.log
+stdout_logfile_maxbytes=10MB
+stdout_logfile_backups=5
+environment=
+    PATH="/opt/project/venv/bin:%(ENV_PATH)s",
+    LANG="en_US.UTF-8",
+    LC_ALL="en_US.UTF-8"
+```
+
+```bash
+# 加载配置
+sudo supervisorctl reread
+sudo supervisorctl update
+
+# 启动服务
+sudo supervisorctl start flask
+
+# 查看状态
+sudo supervisorctl status flask
+
+# 重启服务
+sudo supervisorctl restart flask
+
+# 查看日志
+tail -f /opt/project/logs/supervisor.log
+```
+
+## Nginx 配置
+
+### 完整配置示例
+
+```nginx
+# /etc/nginx/sites-available/flask
+server {
+    listen 80;
+    server_name your-domain.com;
+    
+    # 重定向到 HTTPS（可选）
+    # return 301 https://$server_name$request_uri;
+    
+    # 前端静态文件
+    root /opt/project/ui/dist;
+    index index.html;
+    
+    # 前端路由（SPA 必须）
+    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;
+        
+        # 超时配置
+        proxy_connect_timeout 60s;
+        proxy_send_timeout 60s;
+        proxy_read_timeout 60s;
+        
+        # 缓冲配置
+        proxy_buffering on;
+        proxy_buffer_size 4k;
+        proxy_buffers 8 4k;
+    }
+    
+    # 上传文件访问
+    location /uploads/ {
+        alias /opt/project/uploads/;
+        expires 30d;
+        add_header Cache-Control "public, immutable";
+    }
+    
+    # 静态资源缓存
+    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf)$ {
+        expires 7d;
+        add_header Cache-Control "public, immutable";
+    }
+    
+    # 安全配置
+    client_max_body_size 50m;  # 上传文件大小限制
+    
+    # Gzip 压缩
+    gzip on;
+    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
+    gzip_min_length 1000;
+    gzip_comp_level 6;
+}
+
+# HTTPS 配置（可选）
+server {
+    listen 443 ssl http2;
+    server_name your-domain.com;
+    
+    ssl_certificate /etc/nginx/ssl/your-domain.com.pem;
+    ssl_certificate_key /etc/nginx/ssl/your-domain.com.key;
+    ssl_protocols TLSv1.2 TLSv1.3;
+    ssl_ciphers HIGH:!aNULL:!MD5;
+    
+    # ... 同上配置 ...
+}
+```
+
+```bash
+# 启用站点
+sudo ln -s /etc/nginx/sites-available/flask /etc/nginx/sites-enabled/
+sudo nginx -t  # 测试配置
+sudo systemctl reload nginx
+```
+
+## 环境变量配置
+
+### 生产环境 .env 示例
+
+```bash
+# 应用配置
+FLASK_HOST=127.0.0.1
+FLASK_PORT=8021
+FLASK_SECRET_KEY=your-flask-secret-key-at-least-16-chars
+FLASK_DEBUG=false
+
+# 数据库配置
+DB_HOST=127.0.0.1
+DB_PORT=3306
+DB_DRIVER=mysql
+DB_DATABASE=djangoadmin.flask.elevue
+DB_USERNAME=flask_user
+DB_PASSWORD=YourStrongPassword123!
+
+# Redis 配置
+REDIS_HOST=127.0.0.1
+REDIS_PORT=6379
+REDIS_PASSWORD=YourRedisPassword123!
+
+# JWT 配置（必须修改！）
+JWT_SALT=your-random-secret-key-at-least-32-bytes-long
+JWT_EXPIRE_MINUTES=120
+
+# 安全配置
+PERMISSION_ENABLED=true
+FLASK_DEMO=false
+
+# 文件上传
+FLASK_FILE_URL=http://your-domain.com
+UPLOAD_DIR=uploads
+
+# 代理配置（Nginx 反向代理时设置为 1）
+PROXY_NUM=1
+```
+
+## 部署验证
+
+### 检查清单
+
+```bash
+# 1. 检查后端服务
+curl http://127.0.0.1:8021/api/v1/captcha
+# 应返回 JSON 数据
+
+# 2. 检查 Nginx 代理
+curl http://your-domain.com/api/v1/captcha
+# 应返回 JSON 数据
+
+# 3. 检查前端页面
+curl http://your-domain.com
+# 应返回 HTML 页面
+
+# 4. 检查 Supervisor 状态
+sudo supervisorctl status flask
+# 应显示 RUNNING
+
+# 5. 检查日志
+tail -f /opt/project/logs/error.log
+# 应无错误信息
+
+# 6. 检查数据库连接
+cd /opt/project
+source venv/bin/activate
+python -c "from src.app import create_app; app = create_app(); print('OK')"
+```
+
+### 登录测试
+
+```bash
+# 获取验证码
+curl http://your-domain.com/api/v1/captcha
+
+# 登录
+curl -X POST http://your-domain.com/api/v1/login \
+  -H "Content-Type: application/json" \
+  -d '{"username":"admin","password":"123456","code":"xxxx","key":"captcha:xxxx"}'
+```
+
+## 常见问题处理
+
+### 1. 502 Bad Gateway
+
+**原因**：后端服务未启动或 Nginx 代理配置错误。
+
+```bash
+# 检查后端服务
+sudo supervisorctl status flask
+
+# 检查端口监听
+netstat -tlnp | grep 8021
+
+# 检查 Nginx 配置
+sudo nginx -t
+
+# 查看错误日志
+tail -f /var/log/nginx/error.log
+```
+
+### 2. 数据库连接失败
+
+```bash
+# 检查 MySQL 服务
+sudo systemctl status mysql
+
+# 检查连接
+mysql -u flask_user -p -h 127.0.0.1
+
+# 检查 .env 配置
+grep DB_ /opt/project/.env
+```
+
+### 3. Redis 连接失败
+
+```bash
+# 检查 Redis 服务
+sudo systemctl status redis-server
+
+# 测试连接
+redis-cli -a YourRedisPassword123! ping
+
+# 检查 .env 配置
+grep REDIS_ /opt/project/.env
+```
+
+### 4. 上传文件失败
+
+```bash
+# 检查目录权限
+ls -la /opt/project/uploads/
+sudo chown -R www-data:www-data /opt/project/uploads/
+
+# 检查 Nginx 配置
+grep client_max_body_size /etc/nginx/sites-available/flask
+
+# 检查磁盘空间
+df -h
+```
+
+### 5. 前端页面空白
+
+```bash
+# 检查构建产物
+ls -la /opt/project/ui/dist/
+
+# 检查 Nginx 配置
+grep "try_files" /etc/nginx/sites-available/flask
+
+# 检查浏览器控制台是否有 404 错误
+```
+
+## 性能优化
+
+### 1. 数据库优化
+
+```sql
+-- 查看慢查询
+SHOW VARIABLES LIKE 'slow_query%';
+
+-- 分析慢查询
+EXPLAIN SELECT * FROM flask_user WHERE username = 'admin';
+
+-- 添加索引
+ALTER TABLE flask_user ADD INDEX idx_username (username);
+```
+
+### 2. Redis 优化
+
+```bash
+# 查看内存使用
+redis-cli info memory
+
+# 查看命中率
+redis-cli info stats | grep -E "keyspace_hits|keyspace_misses"
+```
+
+### 3. Nginx 优化
+
+```nginx
+# 启用 HTTP/2
+listen 443 ssl http2;
+
+# 启用 Brotli 压缩（需要安装模块）
+# brotli on;
+# brotli_types text/plain text/css application/json application/javascript;
+```
+
+### 4. 应用优化
+
+```bash
+# 增加 Gunicorn 工作进程
+# gunicorn.conf.py
+workers = 9  # CPU 核心数 * 2 + 1
+
+# 启用预加载
+preload_app = True
+```
+
+## 监控与日志
+
+### 日志查看
+
+```bash
+# 应用日志
+tail -f /opt/project/logs/error.log
+
+# 访问日志
+tail -f /opt/project/logs/access.log
+
+# Supervisor 日志
+tail -f /opt/project/logs/supervisor.log
+
+# Nginx 日志
+tail -f /var/log/nginx/access.log
+tail -f /var/log/nginx/error.log
+
+# 系统日志
+journalctl -u supervisor -f
+```
+
+### 健康检查
+
+```bash
+# 创建健康检查脚本
+cat > /opt/project/health_check.sh << 'EOF'
+#!/bin/bash
+response=$(curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:8021/api/v1/captcha)
+if [ "$response" != "200" ]; then
+    echo "Health check failed: $response"
+    sudo supervisorctl restart flask
+fi
+EOF
+
+chmod +x /opt/project/health_check.sh
+
+# 添加到 crontab（每 5 分钟检查一次）
+(crontab -l 2>/dev/null; echo "*/5 * * * * /opt/project/health_check.sh") | crontab -
+```
+
+## 版本更新
+
+### 更新流程
+
+```bash
+#!/bin/bash
+# deploy.sh - 版本更新脚本
+
+set -e
+
+PROJECT_DIR="/opt/project"
+BACKUP_DIR="/opt/backup/$(date +%Y%m%d_%H%M%S)"
+
+echo "=== 开始部署 ==="
+
+# 1. 备份当前版本
+echo "1. 备份当前版本..."
+mkdir -p $BACKUP_DIR
+cp -r $PROJECT_DIR/src $BACKUP_DIR/
+cp -r $PROJECT_DIR/ui/dist $BACKUP_DIR/
+cp $PROJECT_DIR/.env $BACKUP_DIR/
+
+# 2. 更新代码
+echo "2. 更新代码..."
+cd $PROJECT_DIR
+git pull origin main
+
+# 3. 更新依赖
+echo "3. 更新依赖..."
+source venv/bin/activate
+pip install -r requirements.txt
+
+# 4. 数据库迁移
+echo "4. 数据库迁移..."
+flask db upgrade
+
+# 5. 构建前端
+echo "5. 构建前端..."
+cd ui
+pnpm install
+pnpm build:prod
+cd ..
+
+# 6. 重启服务
+echo "6. 重启服务..."
+sudo supervisorctl restart flask
+
+# 7. 验证
+echo "7. 验证服务..."
+sleep 3
+response=$(curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:8021/api/v1/captcha)
+if [ "$response" = "200" ]; then
+    echo "=== 部署成功 ==="
+else
+    echo "=== 部署失败，回滚中 ==="
+    cp -r $BACKUP_DIR/src/* $PROJECT_DIR/src/
+    cp -r $BACKUP_DIR/dist/* $PROJECT_DIR/ui/dist/
+    sudo supervisorctl restart flask
+    exit 1
+fi
+```
+
+## 总结
+
+生产环境部署需要注意以下几点：
+
+1. **安全配置**：修改默认密码、JWT_SALT、FLASK_DEBUG=false
+2. **性能配置**：Gunicorn 工作进程数、MySQL 缓冲池、Redis 内存限制
+3. **监控日志**：配置日志轮转、健康检查、错误告警
+4. **备份策略**：定期备份数据库、上传文件、配置文件
+5. **版本更新**：使用部署脚本、支持快速回滚