ubuntu22.04宝塔部署django项目？

2026-06-08 12:00:29 分类：云知识

在 Ubuntu 22.04 上使用宝塔面板（BT Panel）部署 Django 项目，通常有两种主流方式：一种是使用宝塔自带的“宝塔应用商店”一键部署 Django（适合快速上手），另一种是手动配置 Nginx + Gunicorn/Uwsgi（适合生产环境，更灵活稳定）。

考虑到 Ubuntu 22.04 的 Python 版本默认较新（Python 3.10+），且宝塔对新版 Python 的支持正在完善，以下提供最推荐的手动部署方案（基于 Nginx + Gunicorn），这种方式性能更好，也更容易排查问题。

第一步：准备环境与依赖

  1. 安装宝塔面板
    如果你还没安装宝塔，请先运行官方安装脚本（以 root 用户执行）：

    # 下载并执行安装脚本
wget -O install.sh http://download.bt.cn/install/install-ubuntu_6.0.sh && sudo bash install.sh ed8484bec

    安装完成后，记住面板的访问地址、用户名和密码。

  2. 创建网站目录与数据库

    • 登录宝塔面板 -> 网站 -> 添加站点。
    • 域名填写你的真实域名或 localhost（如果是本地测试）。
    • 根目录建议设置为 /www/wwwroot/你的域名。
    • 数据库：点击左侧菜单 数据库 -> 添加，创建一个 MySQL 数据库和对应的用户，记下名称、密码和用户名。

  3. 安装 Python 环境
    Ubuntu 22.04 默认自带 Python 3.10，但为了配合宝塔，建议先安装 Python 3.10 的完整开发包（如果宝塔已自动识别可跳过）：

    sudo apt update
sudo apt install python3-pip python3-dev python3-venv -y

第二步：上传代码与安装依赖

  1. 上传代码
    使用宝塔的 文件管理器，将你的 Django 项目代码上传到刚才创建的网站根目录（例如 /www/wwwroot/yourdomain.com）。
    注意：确保 .git 文件夹不要上传到 Web 根目录，或者在 Nginx 配置中禁止访问。

  2. 创建虚拟环境
    打开宝塔的 终端，进入项目目录：

    cd /www/wwwroot/你的域名
python3 -m venv venv
source venv/bin/activate

  3. 安装依赖
    激活虚拟环境后，安装 requirements.txt 中的依赖：

    pip install -r requirements.txt

    如果没有 requirements.txt，请手动安装常用库，如 django, gunicorn, psycopg2-binary (MySQL 驱动), python-decouple (管理环境变量) 等。

  4. 收集静态文件
    Django 项目必须收集静态文件才能被 Nginx 正确加载：

    python manage.py collectstatic --noinput

    如果提示 STATIC_ROOT 未设置，请在 settings.py 中添加：

    STATIC_ROOT = '/www/wwwroot/你的域名/staticfiles/'

  5. 配置数据库连接
    修改项目根目录下的 settings.py：

    • 找到 DATABASES 部分，将 NAME, USER, PASSWORD, HOST 替换为你在宝塔创建的数据库信息。
    • 重要：Ubuntu 22.04 的 MySQL/MariaDB 认证插件可能不同。如果遇到 Access denied 错误，尝试在宝塔数据库设置中，将该用户的主机权限设为 %，或者在 MySQL 命令行执行： 
      ALTER USER '你的用户名'@'%' IDENTIFIED WITH mysql_native_password BY '你的密码';
FLUSH PRIVILEGES;

第三步：启动服务 (Gunicorn)

Django 自带的 runserver 仅用于开发，生产环境必须使用 WSGI 服务器（如 Gunicorn）。

  1. 编写启动脚本
    在项目目录下创建一个 start_gunicorn.sh：

    nano start_gunicorn.sh

    填入以下内容（根据你的实际情况修改路径）：

    #!/bin/bash
PROJECT_DIR=/www/wwwroot/你的域名
VENV_DIR=$PROJECT_DIR/venv

# 激活虚拟环境并启动 gunicorn
source $VENV_DIR/bin/activate
export DJANGO_SETTINGS_MODULE=你的项目名.settings  # 替换为你的 settings 模块路径

gunicorn your_project_name.wsgi:application 
  --bind 127.0.0.1:8000 
  --workers 4 
  --timeout 120 
  --chdir $PROJECT_DIR

    (注意：your_project_name 是你的包含 wsgi.py 的那个文件夹的名字)

  2. 赋予执行权限并启动

    chmod +x start_gunicorn.sh
./start_gunicorn.sh &

    此时，如果命令直接返回，说明后台启动了。你可以用 ps -ef | grep gunicorn 查看进程是否存活。

    进阶建议（使用 Supervisor 管理）：
    为了防止进程意外退出导致服务挂掉，建议在宝塔 软件商店 安装 Supervisor，然后在 Supervisor 面板中配置该脚本为守护进程，实现开机自启和断线重连。

第四步：配置 Nginx 反向X_X

这是最关键的一步，让外部请求通过 Nginx 转发给 Gunicorn。

  1. 进入网站配置
    在宝塔面板 -> 网站 -> 点击你的域名 -> 配置文件。

  2. 修改配置
    找到 location / 块，将其修改为如下内容（保留原有的 try_files 逻辑，重点看 proxy_pass）：

    server {
    listen 80;
    server_name 你的域名; # 替换为你的域名

    # ... 其他 SSL 配置 ...

    location / {
        proxy_pass http://127.0.0.1:8000; # 指向 Gunicorn 监听的端口

        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;

        # 处理 WebSocket (如果需要)
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }

    # 静态文件配置 (可选，如果 collectstatic 后的路径不同需调整)
    location /static/ {
        alias /www/wwwroot/你的域名/staticfiles/; # 对应 collectstatic 的路径
        expires 30d;
    }

    # 防止访问 .git 等敏感文件
    location ~ /.git {
        deny all;
    }
}

  3. 保存并重载
    点击保存按钮，宝塔会自动重载 Nginx。

第五步：常见问题排查

  1. 页面无法访问 (502 Bad Gateway)

    • 检查 Gunicorn 进程是否在运行：ps -ef | grep gunicorn。
    • 检查终端日志：查看 start_gunicorn.sh 是否有报错。
    • 检查防火墙：确保 8000 端口（Gunicorn 监听端口）未被拦截（虽然 Nginx 只监听 80/443，但内部通信通常不受影响，除非有严格的安全组限制）。

  2. 静态文件不显示

    • 确认 collectstatic 执行成功，且生成的 staticfiles 目录存在。
    • 确认 Nginx 配置中的 alias 路径与实际物理路径完全一致。
    • 检查目录权限：sudo chown -R www-data:www-data /www/wwwroot/你的域名/staticfiles。

  3. 中文乱码

    • 确保 settings.py 中 LANGUAGE_CODE = 'zh-hans'。
    • 确保 Nginx 配置中包含 charset utf-8;。

  4. 数据库连接失败

    • 再次检查 settings.py 中的密码是否正确（注意特殊字符转义）。
    • 确认 MySQL 用户权限允许远程连接（Host 为 %）。

替代方案：宝塔“应用商店”一键部署

如果你不想手动配置上述步骤，也可以尝试：

  1. 进入宝塔 应用商店。
  2. 搜索 Django。
  3. 点击 安装。
  4. 按照向导输入项目路径、数据库信息等。
    • 缺点：这种方式有时会对代码结构有特定要求（如必须放在指定目录），且自定义程度较低，适合纯模板化项目。对于复杂的业务逻辑，推荐上面的手动部署方案。

完成以上步骤后，你的 Django 项目应该已经可以通过域名正常访问了。

未经允许不得转载：CLOUD云枢 » ubuntu22.04宝塔部署django项目？

相关推荐