宝塔面板部署 Python 项目（详细教程）

宝塔面板部署 Python 项目（详细教程）

一、核心概念

宝塔面板不内置一键部署 Python 应用的功能，部署 Flask/Django 等 Python Web 项目需要手动配置以下核心组件：

Flask/Django 应用 → Gunicorn (WSGI服务器) → Nginx (反向代理) → 用户访问

⚠️ 常见错误：使用 python app.py 或 python manage.py runserver 在生产环境下会导致进程容易崩溃、性能极差。正确做法是使用 Gunicorn 或 uWSGI 作为 WSGI 服务器。

二、环境准备

2.1 安装 Python 环境

  1. 登录宝塔面板，进入「软件商店」
  2. 搜索「Python项目管理器」，点击安装
  3. 安装完成后，在「Python项目管理器」中点击「版本管理」
  4. 安装与本地开发环境一致的 Python 版本（推荐 3.8+）

2.2 准备项目代码

项目需包含以下核心文件：

  • requirements.txt —— 项目依赖列表
  • app.py（Flask）或 manage.py/wsgi.py（Django）
  • 完整的项目源码

三、项目部署步骤

3.1 上传项目文件

方法一：宝塔文件管理器

  1. 进入「文件」菜单
  2. 进入 /www/wwwroot/ 目录
  3. 点击「上传」按钮，将项目压缩包上传后解压

方法二：FTP/SFTP 工具

  1. 在宝塔「FTP」中创建 FTP 账号
  2. 使用 FileZilla 等工具连接并上传

3.2 创建虚拟环境（推荐手动创建）

  1. 在宝塔面板中打开「终端」功能
  2. 进入项目目录：
    cd /www/wwwroot/项目目录名
  3. 创建虚拟环境：
    python3 -m venv venv
  4. 激活虚拟环境并安装依赖：
    source venv/bin/activate
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

3.3 安装 Gunicorn（WSGI 服务器）

在虚拟环境中执行：

pip install gunicorn

3.4 配置 Nginx 反向代理

步骤一：添加站点

  1. 进入「网站」菜单，点击「添加站点」
  2. 填写域名（无域名可暂时填写服务器 IP）
  3. 将运行环境切换为「纯静态」或禁用 PHP
  4. 点击提交

步骤二：配置反向代理

  1. 进入该站点的「设置」→「反向代理」
  2. 点击「添加反向代理」，配置如下：
    • 目标 URL：http://127.0.0.1:8000
    • 代理名称：自定义
  3. 保存后，点击「Nginx 配置」手动添加以下内容：
    location /static/ {
    alias /www/wwwroot/项目目录名/static/;
}
location /media/ {
    alias /www/wwwroot/项目目录名/media/;
}
  4. 重载 Nginx：
    nginx -t
nginx -s reload

3.5 启动 Python 应用

Flask 项目：

gunicorn -w 4 -b 127.0.0.1:8000 --chdir /www/wwwroot/项目目录名 主文件名:app实例名

示例：

gunicorn -w 4 -b 127.0.0.1:8000 --chdir /www/wwwroot/flask_app app:app

Django 项目：

gunicorn -w 4 -b 127.0.0.1:8000 --chdir /www/wwwroot/项目目录名 项目名.wsgi:application

示例：

gunicorn -w 4 -b 127.0.0.1:8000 --chdir /www/wwwroot/mydjango myproject.wsgi:application

💡 参数说明：

  • -w 4：启动 4 个工作进程
  • -b 127.0.0.1:8000：绑定到本地 8000 端口
  • --chdir：指定项目工作目录

四、配置进程守护（Supervisor）

安装 Supervisor

pip install supervisor

生成配置文件

echo_supervisord_conf > /etc/supervisord.conf

编辑配置文件（在末尾添加）

Flask 示例：

[program:my_flask_app]
command=/www/wwwroot/项目目录名/venv/bin/gunicorn -w 4 -b 127.0.0.1:8000 --chdir /www/wwwroot/项目目录名 app:app
directory=/www/wwwroot/项目目录名
autostart=true
autorestart=true
user=www
redirect_stderr=true
stdout_logfile=/www/wwwlogs/myapp.log

Django 示例：

[program:my_django_app]
command=/www/wwwroot/项目目录名/venv/bin/gunicorn -w 4 -b 127.0.0.1:8000 --chdir /www/wwwroot/项目目录名 myproject.wsgi:application
directory=/www/wwwroot/项目目录名
autostart=true
autorestart=true
user=www
redirect_stderr=true
stdout_logfile=/www/wwwlogs/myapp.log

启动 Supervisor

supervisord -c /etc/supervisord.conf
supervisorctl update
supervisorctl start my_flask_app
supervisorctl status

五、静态文件处理（Django 专属）

收集静态文件：

cd /www/wwwroot/项目目录名
python manage.py collectstatic --noinput

确认 settings.py 配置：

STATIC_URL = '/static/'
STATIC_ROOT = '/www/wwwroot/项目目录名/staticfiles'

配置 Nginx：

location /static/ {
    alias /www/wwwroot/项目目录名/staticfiles/;
}

六、域名绑定与 SSL 证书

  1. 域名解析：将域名 A 记录解析到服务器 IP
  2. 域名绑定：进入「网站」→ 站点设置 →「域名管理」中添加域名
  3. SSL 证书：在「SSL」标签页中点击「申请 Let's Encrypt」

⚠️ 务必在 Django 的 settings.py 中配置 ALLOWED_HOSTS：

ALLOWED_HOSTS = ['yourdomain.com', 'www.yourdomain.com']

七、常见问题与排错

问题现象 常见原因 解决方法
访问报 502 Bad Gateway Gunicorn 未启动或端口不匹配 检查进程：ps aux | grep gunicorn
访问报 500 错误 Django 配置问题 查看 gunicorn 错误日志
CSS/JS 无法加载 静态文件配置错误 检查 Nginx alias 路径
ModuleNotFoundError 依赖未安装或路径不对 确保在正确的虚拟环境中安装依赖
虚拟环境缺失 迁移后环境未同步 手动创建同名虚拟环境
依赖安装失败 pip 源慢或缺少编译依赖 使用清华镜像源；CentOS 执行 yum install -y libffi-devel
项目无法启动 使用了 runserver 改用 Gunicorn 启动

八、快速排错流程

  1. 检查进程：ps aux | grep gunicorn
  2. 检查端口：netstat -tlnp | grep 8000
  3. 查看应用日志：Gunicorn 添加 --access-logfile 和 --error-logfile 参数
  4. 手动运行测试：直接执行 Gunicorn 启动命令，观察报错
  5. 检查 Nginx 日志：查看 /www/wwwlogs/ 目录下的错误日志

九、完整部署清单

posted @ 2026-06-14 12:12  鹿聚GEO  阅读(550)  评论(0)    收藏  举报