如何在Ubuntu 22.04上使用宝塔面板部署Django项目？

下面以 Ubuntu 22.04 + 宝塔面板（BT Panel）为例，给出从零部署 Django 项目的完整流程。假设你已安装好宝塔面板（Linux 版），且服务器已开放必要端口。

一、准备工作

1. 确认环境

• 系统：Ubuntu 22.04 LTS
• 宝塔面板：已安装并登录
• 已创建网站域名（或 IP 访问）
• 已有 Django 项目代码（本地打包上传，或通过 Git 拉取）

2. 安装必要软件（在宝塔“软件商店”中安装）

在宝塔面板左侧菜单 → 软件商店，依次安装/启用：

1. Nginx（推荐最新版）
2. MySQL / MariaDB（根据需求选择）
3. Python 3.x（宝塔通常自带 Python 管理工具，可不用单独装）
4. Supervisor（可选，用于进程守护；也可用 systemd）

如果宝塔已自动安装 Python 管理模块（如“宝塔 Python 管理器”），可直接使用。

二、创建网站与目录结构

1. 在宝塔中创建网站

1. 进入 网站 → 添加站点
2. 填写：
   • 域名：yourdomain.com（或留空仅用 IP）
   • 根目录：例如 /www/wwwroot/yourproject
   • 数据库：勾选“创建数据库”，设置用户名、密码、库名
3. 点击提交

此时宝塔会：

• 创建网站目录
• 创建 Nginx 配置文件
• 创建数据库

2. 准备项目目录

建议结构如下（示例）：

/www/wwwroot/yourproject
├─ code/          # Django 项目源码
│  ├─ manage.py
│  ├─ yourproject/  # Django 项目配置目录
│  └─ ...
├─ static/        # 静态文件（由 collectstatic 生成）
├─ media/         # 用户上传文件
└─ venv/          # Python 虚拟环境（可选，但推荐）

你可以手动在终端创建这些目录，或在宝塔的“文件”界面中创建。

三、上传或拉取 Django 项目代码

方式 A：通过 FTP/SFTP 上传压缩包

1. 本地将 Django 项目打包为 .zip 或 .tar.gz
2. 在宝塔 → 文件 → 找到网站根目录
3. 点击“上传”，解压到 code 目录

方式 B：使用 Git 克隆

1. 进入网站根目录：

   cd /www/wwwroot/yourproject
   mkdir code && cd code

2. 执行：

   git clone <你的仓库地址> .

3. 确保 .gitignore 合理，避免上传敏感文件（如 SECRET_KEY）。

四、配置 Python 环境与依赖

1. 使用宝塔 Python 管理器（推荐）

1. 在宝塔左侧菜单 → 软件商店 → 搜索并安装 Python 管理器（如果已有则跳过）
2. 进入 Python 项目管理（或类似入口）
3. 点击 添加项目：
   • 项目名称：自定义
   • 路径：指向你的项目根目录（如 /www/wwwroot/yourproject/code）
   • Python 版本：选择 3.10+（与项目要求一致）
   • 工作目录：同上
   • 启动命令：一般填 python3 manage.py runserver 0.0.0.0:8000（后面会被 Nginx+uWSGI/Gunicorn 替代，这里先测试）
4. 点击保存后，宝塔会自动：
   • 创建虚拟环境（venv）
   • 安装 pip 相关依赖
5. 在项目页面中，点击 依赖管理，上传 requirements.txt，一键安装依赖。

如果你不使用宝塔的 Python 管理器，也可以手动创建 venv：

cd /www/wwwroot/yourproject/code
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

五、配置 Django 项目

1. 修改 settings.py

打开 code/yourproject/settings.py（或使用宝塔编辑器）：

1. ALLOWED_HOSTS

   ALLOWED_HOSTS = ['yourdomain.com', 'localhost', '127.0.0.1']

2. DEBUG
   • 生产环境必须设为 False

     DEBUG = False

3. STATIC_ROOT / MEDIA_ROOT

   import os
   BASE_DIR = Path(__file__).resolve().parent.parent
   
   STATIC_URL = '/static/'
   STATIC_ROOT = os.path.join(BASE_DIR, 'static')
   
   MEDIA_URL = '/media/'
   MEDIA_ROOT = os.path.join(BASE_DIR, 'media')

4. 数据库配置
   • 使用宝塔创建的数据库信息：

     DATABASES = {
     'default': {
        'ENGINE': 'django.db.backends.mysql',
        'NAME': 'db_name',
        'USER': 'db_user',
        'PASSWORD': 'db_password',
        'HOST': 'localhost',
        'PORT': '3306',
        'OPTIONS': {
            'charset': 'utf8mb4',
        },
     }
     }

5. 安全设置（生产环境）
   • 设置 SECRET_KEY（不要写在代码里，可用环境变量）
   • 开启 HTTPS 后，注意 SECURE_SSL_REDIRECT 等设置。

六、迁移数据库 & 收集静态文件

1. 激活虚拟环境并迁移

cd /www/wwwroot/yourproject/code
# 如果使用宝塔 Python 管理器，可以点“运行命令”或在终端：
source venv/bin/activate

python manage.py migrate

如有初始数据脚本：

python manage.py loaddata initial_data.json

2. 收集静态文件

python manage.py collectstatic --noinput

这会生成 static/ 目录，里面是合并后的静态文件。

七、配置 uWSGI / Gunicorn + Nginx

Django 本身不适合直接对外提供 HTTP，应使用 WSGI 服务器（Gunicorn/uWSGI）+ Nginx。

方案 A：使用宝塔自带的 “Web 应用” 功能（推荐新手）

1. 在宝塔 → 软件商店 安装 Python 应用管理（如果有）
2. 或者在 网站 → 找到你的站点 → 设置 → PHP 版本 下方有 Python 应用 或 FastCGI 选项（不同版本略有差异）
3. 配置：
   • 启动类型：uWSGI 或 Gunicorn
   • 项目目录：/www/wwwroot/yourproject/code
   • 启动命令（Gunicorn 示例）：

     gunicorn yourproject.wsgi:application --bind 127.0.0.1:8000

   • 监听端口：127.0.0.1:8000
   • 工作目录：同上
4. 保存后，宝塔会自动：
   • 启动 WSGI 进程
   • 配置 Nginx 反向X_X到 127.0.0.1:8000

如果找不到该功能，可以使用下面的手动方案。

方案 B：手动配置 Gunicorn + Nginx

1. 创建 Gunicorn 服务（systemd）

sudo nano /etc/systemd/system/django.service

内容示例：

[Unit]
Description=Django Application (gunicorn)
After=network.target

[Service]
User=www-data
Group=www-data
WorkingDirectory=/www/wwwroot/yourproject/code
Environment="PATH=/www/wwwroot/yourproject/code/venv/bin"
ExecStart=/www/wwwroot/yourproject/code/venv/bin/gunicorn 
    --workers 3 
    --bind unix:/tmp/django.sock 
    yourproject.wsgi:application

Restart=always

[Install]
WantedBy=multi-user.target

然后：

sudo systemctl daemon-reload
sudo systemctl enable django
sudo systemctl start django
sudo systemctl status django

2. 配置 Nginx

在宝塔 → 网站 → 你的站点 → 配置文件，编辑 Nginx 配置，改为类似：

server {
    listen 80;
    server_name yourdomain.com www.yourdomain.com;

    root /www/wwwroot/yourproject;

    location /static/ {
        alias /www/wwwroot/yourproject/static/;
        expires 30d;
        add_header Cache-Control "public, immutable";
    }

    location /media/ {
        alias /www/wwwroot/yourproject/media/;
        expires 30d;
        add_header Cache-Control "public";
    }

    location / {
        include uwsgi_params;
        uwsgi_pass unix:/tmp/django.sock;
        uwsgi_param SCRIPT_NAME "";
    }
}

若使用 Gunicorn 绑定的是 TCP（如 127.0.0.1:8000），则 uwsgi_pass 改为 proxy_pass http://127.0.0.1:8000; 并使用 proxy_set_header 等。

保存后重启 Nginx：

sudo systemctl restart nginx

八、开启 HTTPS（可选但推荐）

1. 在宝塔 → 网站 → 你的站点 → SSL
2. 选择免费证书（Let’s Encrypt）
3. 按提示验证域名所有权（TXT 或 HTTP 验证）
4. 申请成功后，勾选“强制 HTTPS”
5. 宝塔会自动更新 Nginx 配置，并重定向 HTTP → HTTPS

九、测试与常见问题排查

1. 访问测试

• 浏览器访问：http(s)://yourdomain.com
• 检查：
  • 是否能正常显示首页
  • 静态资源是否正常加载（查看 Network 标签）
  • 数据库连接是否正常（查看日志）

2. 常见错误及处理

1. 502 Bad Gateway

   • 检查 Gunicorn/uWSGI 是否启动：

     sudo systemctl status django

   • 查看日志：

     sudo journalctl -u django -f

   • 检查 Nginx 配置是否正确指向 socket 或端口。

2. 403 Forbidden / 权限问题

   • 确保目录所有者正确：

     sudo chown -R www-data:www-data /www/wwwroot/yourproject

   • 检查 media/、static/ 目录权限。

3. 数据库连接失败

   • 检查 settings.py 中的 DB 配置是否与宝塔创建的一致
   • 确认 MySQL 允许本地连接（默认允许 localhost）
   • 检查防火墙是否阻止 3306（宝塔通常已放行）

4. 静态文件不生效

   • 确认 collectstatic 已执行
   • 确认 Nginx 的 alias 路径正确
   • 检查 STATIC_ROOT 和 MEDIA_ROOT 是否对应

十、后续维护建议

• 定期备份数据库（宝塔 → 数据库 → 备份）
• 使用 .env 或环境变量管理 SECRET_KEY、数据库密码等敏感信息
• 使用 pip freeze > requirements.txt 保持依赖清单同步
• 开启宝塔的日志监控和报警功能

如果你愿意，可以告诉我：

• 你的 Django 项目结构（是否有 manage.py、requirements.txt）
• 是否已经安装宝塔 Python 管理器
• 使用的是 Gunicorn 还是 uWSGI

我可以给你一份更贴合你环境的具体命令和配置文件模板。