如何在CPanel中借助Uvicorn服务器完成Django应用部署？

1. 前置环境确认 #

• 确认你的 CPanel 账户已开通 SSH 权限、Python 应用管理器功能（部分主机商需要额外申请开启）
• 确认服务器已安装 Python 3.8+ 版本（Django 4.x 及以上对 Python 版本有最低要求）
• 本地提前把 Django 项目的依赖列表导出为 requirements.txt，本地测试所有功能正常无报错

2. 上传项目文件到服务器 #

• 登录 CPanel 面板，进入「文件管理器」，在根目录（非 public_html 目录，避免源码暴露）新建专门的项目文件夹，比如 my_django_project
• 把本地 Django 项目所有文件压缩为 zip 包后上传到该文件夹，解压到当前目录
• 确认项目根目录下存在 manage.py 文件

3. 配置虚拟环境与依赖安装 #

• 登录 SSH 连接到服务器，cd 到刚才的项目目录：cd /home/你的CPanel用户名/my_django_project
• 创建虚拟环境：python3.9 -m venv venv（这里的Python版本替换为你服务器实际安装的高版本Python）
• 激活虚拟环境：source venv/bin/activate
• 升级pip：pip install --upgrade pip
• 安装所有依赖：pip install -r requirements.txt
• 额外安装 Uvicorn 依赖：pip install uvicorn

4. 修改 Django 项目配置 #

• 打开项目下的 settings.py 文件，做以下修改：
  • 把 DEBUG 改为 DEBUG = False
  • 在 ALLOWED_HOSTS 中添加你要绑定的域名，比如 ALLOWED_HOSTS = ['yourdomain.com', 'www.yourdomain.com']
  • 配置静态文件路径：添加 STATIC_ROOT = os.path.join(BASE_DIR, 'static')，媒体文件路径同理配置 MEDIA_ROOT
  • 确认 ASGI_APPLICATION 配置正确，默认值为 ASGI_APPLICATION = '你的项目名.asgi.application'
• 执行静态文件收集命令：python manage.py collectstatic，输入yes确认
• 执行数据库迁移：python manage.py migrate
• 测试项目基础可用性：python manage.py runserver 0.0.0.0:8000，确认无报错后关闭进程

5. 在 CPanel 中创建 Python 应用 #

• 回到 CPanel 面板，找到「软件」分类下的「Python 应用程序」，点击「创建应用」
• 按以下参数填写：
  • Python 版本：选择和你虚拟环境一致的版本，比如 3.9
  • 应用根目录：选择你刚才创建的项目文件夹，比如 my_django_project
  • 应用 URL：选择你要绑定的域名，路径留空即可
  • 应用启动文件：填写 asgi.py 的相对路径，比如 myproject/asgi.py（替换为你实际的项目名）
  • 应用入口点：填写 application
  • Passenger 日志文件：保持默认即可，后续排错可查看该日志
• 点击「创建」，创建完成后复制页面顶部的虚拟环境激活命令备用

6. 配置 Passenger 调用 Uvicorn #

• 回到项目根目录，新建 passenger_wsgi.py 文件，写入以下内容：

import os
import sys
from uvicorn import run

# 替换为你的实际项目名
os.environ.setdefault('DJANGO_SETTINGS_MODULE', '你的项目名.settings')
from 你的项目名.asgi import application

if __name__ == '__main__':
    run(application, host='127.0.0.1', port=int(os.environ.get('PORT', 8000)))

7. 配置静态文件映射 #

• 进入 CPanel 的「别名」功能，分别给 /static 和 /media 路径设置别名，目标路径指向你项目中 STATIC_ROOT 和 MEDIA_ROOT 对应的实际目录，权限设置为755
• 也可以直接编辑 public_html 目录下的 .htaccess 文件，添加以下规则：

RewriteEngine On
# 静态、媒体文件直接访问
RewriteCond %{REQUEST_URI} ^/static/ [OR]
RewriteCond %{REQUEST_URI} ^/media/
RewriteRule ^(.*)$ /$1 [L]

# 其他请求转发给Django应用
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^(.*)$ http://127.0.0.1:8000/$1 [P,L]

8. 重启应用并测试访问 #

• 回到 CPanel 的「Python 应用程序」页面，找到你创建的应用，点击右侧的「重启」按钮
• 等待30秒后，访问你绑定的域名，测试所有功能是否正常
• 如果出现报错，可以查看项目目录下的 stderr.log 或者 Passenger 日志排查问题

常见问题排查 #

• 启动失败优先检查虚拟环境的依赖是否全部安装成功，Uvicorn 版本是否和 Django 版本适配
• 静态文件无法加载时，检查 STATIC_ROOT 配置是否正确、collectstatic 命令是否执行成功、静态文件目录的权限是否为755
• 域名访问报503错误时，检查Python应用是否正常启动、端口是否被占用

内容的提问来源于stack exchange，提问作者Satya Kushwaha