本章概要

生产环境部署实战指南，包含完整的部署流程、配置示例、常见问题处理和性能优化建议。基于实际生产环境经验总结。

生产环境部署实战

本文档提供从零开始的生产环境部署实战指南，包含完整的命令操作、配置文件和常见问题处理。

环境准备

服务器配置建议

项目	最低配置	推荐配置
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

总结

生产环境部署需要注意以下几点：

安全配置：修改默认密码、JWT_SALT、FLASK_DEBUG=false
性能配置：Gunicorn 工作进程数、MySQL 缓冲池、Redis 内存限制
监控日志：配置日志轮转、健康检查、错误告警
备份策略：定期备份数据库、上传文件、配置文件
版本更新：使用部署脚本、支持快速回滚

Become a sponsor

企业级中台解决方案

企业级中台解决方案

生产环境部署实战 ​

环境准备 ​

服务器配置建议 ​

一键安装依赖（Ubuntu） ​

一键安装依赖（CentOS） ​

数据库配置 ​

MySQL 生产环境配置 ​

创建数据库和用户 ​

Redis 配置 ​

生产环境配置 ​

项目部署 ​

部署目录结构 ​

后端部署 ​

Gunicorn 配置 ​

Supervisor 配置 ​

Nginx 配置 ​

完整配置示例 ​

环境变量配置 ​

生产环境 .env 示例 ​

部署验证 ​

检查清单 ​

登录测试 ​

常见问题处理 ​

1. 502 Bad Gateway ​

2. 数据库连接失败 ​

3. Redis 连接失败 ​

4. 上传文件失败 ​

5. 前端页面空白 ​

性能优化 ​

1. 数据库优化 ​

2. Redis 优化 ​

3. Nginx 优化 ​

4. 应用优化 ​

监控与日志 ​

日志查看 ​

健康检查 ​

版本更新 ​

更新流程 ​

总结 ​

生产环境部署实战

环境准备

服务器配置建议

一键安装依赖（Ubuntu）

一键安装依赖（CentOS）

数据库配置

MySQL 生产环境配置

创建数据库和用户

Redis 配置

生产环境配置

项目部署

部署目录结构

后端部署

Gunicorn 配置

Supervisor 配置

Nginx 配置

完整配置示例

环境变量配置

生产环境 .env 示例

部署验证

检查清单

登录测试

常见问题处理

1. 502 Bad Gateway

2. 数据库连接失败

3. Redis 连接失败

4. 上传文件失败

5. 前端页面空白

性能优化

1. 数据库优化

2. Redis 优化

3. Nginx 优化

4. 应用优化

监控与日志

日志查看

健康检查

版本更新

更新流程

总结