通过cPanel在Linux共享主机配置现有Django项目遇到上线问题

我帮你梳理下在cPanel共享主机上部署Django项目的完整流程和常见坑，亲测能解决大部分上线配置问题：

1. 先确认主机环境支持 #

首先登录你的cPanel面板，找到「Setup Python App」（有些主机叫「Python Selector」），确认主机提供了对应你Django版本的Python环境（比如Django 4.x需要Python 3.8+）。如果没有合适的版本，可以联系主机商升级。

2. 创建并激活虚拟环境 #

• 在「Setup Python App」里点击「Create Application」，选择目标Python版本，设置应用名称（比如my_django_app），然后点击「Create」。
• 记住生成的虚拟环境路径，比如/home/your_username/virtualenv/my_django_app/3.10/bin/，后面会用到。
• 点击应用列表里的「Enter Shell」，就能进入激活好的虚拟环境，接下来的命令都在这里运行。

3. 上传Django项目文件 #

• 不要把项目直接传到public_html目录（敏感文件容易暴露），建议传到/home/your_username/下的独立目录，比如/home/your_username/my_django_project/。
• 可以用cPanel的「File Manager」上传压缩包后解压，或者用Git克隆你的项目仓库（如果cPanel支持Git的话）。

4. 安装项目依赖 #

在虚拟环境的shell里，切换到项目根目录：

cd /home/your_username/my_django_project/

然后安装依赖：

pip install -r requirements.txt

如果没有requirements.txt，手动安装核心包：

pip install django gunicorn

（gunicorn是WSGI服务器，cPanel的Passenger模块会用到它）

5. 配置Django核心参数 #

修改项目根目录下的settings.py，重点改这几个地方：

• 关闭调试模式（上线必须做）：

  DEBUG = False
  

• 允许你的域名访问：

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

• 配置静态文件路径：

  STATIC_URL = '/static/'
  STATIC_ROOT = '/home/your_username/public_html/static/'
  

• 配置媒体文件（如果有上传功能）：

  MEDIA_URL = '/media/'
  MEDIA_ROOT = '/home/your_username/public_html/media/'
  

• 配置数据库（如果用MySQL）：
  先在cPanel的「MySQL Databases」里创建数据库和用户，然后把信息填入：

  DATABASES = {
      'default': {
          'ENGINE': 'django.db.backends.mysql',
          'NAME': 'your_username_dbname',
          'USER': 'your_username_dbuser',
          'PASSWORD': 'your_db_password',
          'HOST': 'localhost',
          'PORT': '',
      }
  }
  

6. 执行Django上线前命令 #

在虚拟环境shell里运行：

• 收集静态文件到STATIC_ROOT（让web服务器能访问）：

  python manage.py collectstatic
  

  输入yes确认操作。
• 执行数据库迁移：

  python manage.py makemigrations
  python manage.py migrate
  

• 创建超级用户（如果需要后台管理）：

  python manage.py createsuperuser
  

7. 配置WSGI入口和cPanel应用 #

• 在项目根目录创建passenger_wsgi.py文件，内容如下（替换your_project_name为你的Django项目名）：

  import sys, os
  sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
  os.environ['DJANGO_SETTINGS_MODULE'] = 'your_project_name.settings'
  from django.core.wsgi import get_wsgi_application
  application = get_wsgi_application()
  

• 回到cPanel的「Setup Python App」，编辑之前创建的应用：
  • 设置「Application root」为你的项目根目录：/home/your_username/my_django_project/
  • 设置「Startup file」为passenger_wsgi.py
  • 「Domain」选择你要绑定的域名
  • 点击「Save」，cPanel会自动生成对应的.htaccess规则。

8. 常见问题排查 #

• 500内部错误：查看项目根目录下的passenger.log文件，里面有详细错误信息，比如依赖缺失、settings配置错误、数据库连接失败。
• 静态文件不显示：确认collectstatic执行成功，STATIC_ROOT目录权限为755，并且.htaccess没有拦截静态文件请求。
• 域名跳转到cPanel默认页：检查「Setup Python App」里的域名绑定是否正确，.htaccess是否有冲突规则（比如之前的WordPress规则）。
• 权限问题：确保项目目录、public_html/static和public_html/media的所有者是你的cPanel用户名，权限设置为755（文件644）。

内容的提问来源于stack exchange，提问作者zeeshan kamal