简介这份PDF教程面向需要在Linux服务器上部署Python Web应用的开发者与运维人员聚焦CentOS系统下借助宝塔面板完成Django项目的上线流程适合具备基础Django开发经验、希望摆脱手工配置Nginx与uWSGI的读者参考。资源包内仅含1个PDF文件大小约139KB内容以图文步骤形式呈现涵盖基础环境准备、代码上传、Python项目管理器创建项目、网站映射与静态文件代理配置、重启与重载配置等关键环节并给出static与media目录的Nginx配置示例。教程对uswgi启动方式、端口设置、模块依赖安装等细节均有说明可帮助读者快速搭建可外部访问的Django站点同时理解静态资源与媒体文件的代理思路。目前已有2371人学习下载适合作为部署实践中的操作对照与排错参考。1. 宝塔部署 Django为什么 CentOS 上这套组合拳最省心很多新手第一次在 CentOS 上部署 Django上来就手撸 uWSGI 配置文件、手写 systemd 服务、手动配 Nginx 转发结果卡在权限、路径、Python 版本上折腾一整天。宝塔面板的 Python 项目管理器把这一整套流程封装成了可视化操作你只需要填几个路径和端口它自动帮你拉起 uWSGI 进程、生成守护配置、映射 Nginx 反向代理。这篇笔记拆的就是这套流程的完整落地路径从环境准备、代码上传、项目创建到静态文件代理配置和重启验证。适合手里有一个能跑通的 Django 项目、想在 CentOS 服务器上快速上线、又不想被底层配置细节拖住的开发者。读完你至少能拿到一份可复现的操作清单以及几个我踩过的坑的规避方案。2. 环境准备与代码上传把地基打对2.1 宝塔面板与 Python 项目管理器的安装确认CentOS 上装宝塔面板本身不复杂官方提供了一键安装脚本。但这里有个前置条件容易被忽略CentOS 7.9 和 CentOS 8 的 yum 源状态不一样CentOS 8 已经停止维护直接跑安装脚本大概率报镜像源 404。常见做法是先确认系统版本再决定是否需要更换 yum 源。# 查看当前 CentOS 版本 cat /etc/centos-release # 如果是 CentOS 7.x直接执行宝塔安装脚本 # 安装完成后会输出面板地址、用户名和密码安装完宝塔面板后登录面板进入软件商店搜索并安装两个东西Python 项目管理器和 Nginx。Python 项目管理器是宝塔专门为 Python 项目做的进程管理工具它内置了 virtualenv 隔离、依赖安装、uWSGI 启动和开机自启。Nginx 则负责处理 HTTP 请求和反向代理。这两个装好之后基础环境就算齐了。提示Python 项目管理器安装时会自动检测系统已有的 Python 版本。如果你的项目需要特定版本比如 Python 3.10建议先在宝塔的软件商店里安装对应的 Python 版本管理器再装项目管理器。2.2 代码上传的两种方式与目录规范代码上传有两种路径选哪种取决于你的工作流。方法一是服务器上装 Git直接git clone到目标目录。方法二是用宝塔自带的 FTP 工具上传压缩包再解压。我一般推荐 Git 方式因为后续更新只需要git pull不用反复传文件。不管用哪种方式目录规范必须遵守在/www/wwwroot/下新建一个文件夹把代码放进去。比如你的项目叫 myblog那就建/www/wwwroot/myblog/确保manage.py就在这个目录下。# 方法一Git 克隆 cd /www/wwwroot/ mkdir myblog cd myblog git clone 你的仓库地址 . # 方法二FTP 上传后解压 cd /www/wwwroot/myblog/ unzip your_project.zip这里有个细节如果你用 Git 克隆注意仓库地址后面的.它表示克隆到当前目录而不是新建子目录。另外上传完成后检查一下manage.py的路径确认它在/www/wwwroot/myblog/manage.py而不是多套了一层文件夹。2.3 Python 版本与依赖的预检查在创建项目之前先确认服务器上的 Python 版本和项目requirements.txt里的依赖是否兼容。宝塔的 Python 项目管理器支持多版本共存但你在创建项目时选的版本必须和项目实际运行的版本一致。# 查看系统默认 Python 版本 python3 --version # 查看项目依赖清单 cat /www/wwwroot/myblog/requirements.txt如果项目里有mysqlclient或psycopg2这类需要编译的包建议先在服务器上装好对应的开发库否则依赖安装阶段会报编译错误。常见做法是提前装好gcc、python3-devel和mysql-devel如果用 MySQL 的话。3. 创建 Python 项目参数怎么填、为什么这么填3.1 添加项目时的关键字段解析打开宝塔首页的 Python 项目管理器点击「添加项目」会弹出一个表单。这个表单里的每个字段都直接影响项目能不能跑起来逐个说清楚。项目名称随便填只是面板上的标识。路径必须定位到manage.py所在的目录也就是/www/wwwroot/myblog。Python 版本选你项目对应的版本选错了会在启动时报模块找不到或语法错误。框架选 Django。启动方式选 uwsgi这是宝塔封装好的 WSGI 服务器比自带的runserver稳定得多。启动文件/文件夹定位到wsgi.py所在的路径。通常 Django 项目的wsgi.py在项目主包目录下比如/www/wwwroot/myblog/myblog/wsgi.py。端口自定义但必须大于 1024因为 1024 以下需要 root 权限宝塔的进程管理不会用 root 跑你的项目。最后勾选「是否安装模块依赖」和「开机启动」。前者会让宝塔自动执行pip install -r requirements.txt后者保证服务器重启后项目自动拉起。# 创建完成后宝塔会在项目目录下生成一个虚拟环境 # 路径通常在 /www/server/pyporject_evn/ 下 # 你可以手动进入虚拟环境检查依赖是否装全 source /www/server/pyporject_evn/your_project_name/bin/activate pip list3.2 依赖安装失败的排查思路勾选了「安装模块依赖」不代表一定能装成功。最常见的失败原因是网络问题导致 pip 超时或者某个包需要系统级依赖但服务器上没装。如果创建项目后日志里显示依赖安装失败先看日志里的报错关键词。如果是TimeoutError常见做法是在宝塔的 Python 项目管理器设置里把 pip 源换成国内镜像。如果是error: command gcc failed说明缺少编译工具执行yum install gcc python3-devel -y补上。如果是mysql_config not found装mysql-devel即可。# 手动补装依赖的示例 cd /www/wwwroot/myblog source /www/server/pyporject_evn/your_project_name/bin/activate pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple注意手动在虚拟环境里装完依赖后需要在 Python 项目管理器里重启一次项目否则新装的包不会被加载。3.3 数据库迁移与静态文件收集项目创建成功、依赖装好之后还有两步不能漏数据库迁移和静态文件收集。这两步不在宝塔的可视化界面里需要手动执行。cd /www/wwwroot/myblog source /www/server/pyporject_evn/your_project_name/bin/activate # 执行数据库迁移 python manage.py migrate # 收集静态文件到 STATIC_ROOT python manage.py collectstatic --noinputmigrate会根据你的 models 创建数据库表结构。collectstatic会把各个 app 里的静态文件统一复制到STATIC_ROOT指定的目录。如果你在settings.py里没有配置STATIC_ROOTcollectstatic会报错。常见做法是设成STATIC_ROOT os.path.join(BASE_DIR, static)然后 Nginx 的alias指向这个目录。4. 网站映射与 Nginx 静态文件代理让外部能访问4.1 映射域名或 IP 并理解反向代理链路项目在内部跑起来之后外部还访问不到。需要在 Python 项目管理器里点击「映射」填入你的域名或外网 IP。映射成功后宝塔会自动在 Nginx 里创建一个站点配置把外部请求反向代理到你的 Django 项目端口。这时候你去面板侧边栏的「网站」菜单能看到刚才映射出来的站点。此时通过域名或 IP 已经可以访问了但页面大概率是没有样式的——因为静态文件还没配。反向代理的链路是这样的用户请求 → Nginx80/443→ 反向代理到 127.0.0.1:你的端口 → uWSGI → Django 应用。静态文件不走这条链路Nginx 直接根据location规则从磁盘读取并返回。4.2 在反向代理配置文件中插入静态文件规则在「网站」菜单里点击你映射出的域名弹出设置窗口选择「反向代理」→「配置文件」。在这个配置文件里找一个合适的位置插入静态文件和媒体资源的location块。# 静态文件代理CSS、JS、图片等 location /static/ { alias /www/wwwroot/myblog/static/; } # 媒体资源代理用户上传的文件 location /media/ { alias /www/wwwroot/myblog/media/; }alias后面的路径必须和你settings.py里的STATIC_ROOT和MEDIA_ROOT一致。location /static/的意思是当请求 URL 以/static/开头时Nginx 直接去alias指定的目录里找文件不再转发给 Django。这样做的好处是静态文件由 Nginx 直接处理性能比走 Django 高一个数量级。提示alias和root的区别容易搞混。alias会把location匹配的部分替换成指定路径而root是拼接。这里用alias是对的用root会导致路径多一层。4.3 重启项目与重载 Nginx 配置的顺序配置改完之后操作顺序很重要先重启 Python 项目再重载 Nginx 配置。反过来做的话Nginx 重载后静态文件规则生效了但 Django 进程还是旧的可能出现静态文件能加载但页面报 502 的情况。# 在宝塔面板操作 # 1. Python 项目管理器 → 选择项目 → 重启 # 2. Nginx 管理界面 → 重载配置 # 如果想在命令行验证 Nginx 配置语法 nginx -t重启完成后通过你设置的域名或 IP 访问页面样式应该正常加载了。如果静态文件仍然 404检查alias路径末尾有没有斜杠、目录权限是不是www用户可读。5. 避坑与排查那些让你怀疑人生的报错5.1 502 Bad GatewayuWSGI 进程没起来现象是浏览器访问显示 502Nginx 日志里写connect() failed (111: Connection refused) while connecting to upstream。原因通常是 uWSGI 进程启动失败或端口没监听。解决方式是去 Python 项目管理器的日志里看具体报错常见的是ModuleNotFoundError或ImportError说明依赖没装全或wsgi.py路径填错了。修正后重启项目即可。5.2 静态文件 404alias 路径与 STATIC_ROOT 不一致现象是页面 HTML 能加载但 CSS 和 JS 全部 404。原因几乎都是 Nginx 配置里的alias路径和 Djangosettings.py里的STATIC_ROOT对不上。解决方式是先在服务器上确认collectstatic把文件收在了哪个目录然后把alias改成那个目录的绝对路径。另外检查STATIC_URL是不是/static/如果改成了别的location也要跟着改。5.3 端口冲突多个项目用了同一个端口现象是创建第二个项目后第一个项目突然访问不了了。原因是两个项目配了同一个端口uWSGI 只能有一个进程监听该端口。解决方式是在 Python 项目管理器里给每个项目分配不同的端口建议从 8001 开始递增避免和系统服务冲突。5.4 权限问题www 用户读不到项目文件现象是日志里报Permission denied或者静态文件返回 403。原因是项目文件的所有者不是www用户而 Nginx 和 uWSGI 都以www身份运行。解决方式是执行chown -R www:www /www/wwwroot/myblog把项目目录的所有者改成www。注意不要用chmod 777那会带来安全隐患。5.5 数据库连接失败settings.py 里的 host 配置现象是项目启动时报Cant connect to MySQL server。原因是settings.py里DATABASES的HOST填了localhost但宝塔的 MySQL 可能只监听127.0.0.1或 socket 连接。解决方式是把HOST改成127.0.0.1并确认数据库用户有从127.0.0.1访问的权限。如果用的是宝塔自带的 MySQL可以在面板的数据库管理里直接看到连接信息。6. 进阶技巧用 Git 钩子实现一键更新部署项目上线之后每次改代码都要手动上传或登录服务器git pull再重启项目次数多了很烦。我一般会在服务器上配一个 bare 仓库加 post-receive 钩子本地git push之后服务器自动拉取代码、装依赖、收集静态文件、重启项目。# 在服务器上创建 bare 仓库 mkdir -p /www/repos/myblog.git cd /www/repos/myblog.git git init --bare # 创建 post-receive 钩子 cat hooks/post-receive EOF #!/bin/bash WORK_TREE/www/wwwroot/myblog GIT_DIR/www/repos/myblog.git git --work-tree$WORK_TREE --git-dir$GIT_DIR checkout -f cd $WORK_TREE source /www/server/pyporject_evn/your_project_name/bin/activate pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple python manage.py migrate --noinput python manage.py collectstatic --noinput # 重启项目宝塔的项目重启命令 # 具体命令可以在 Python 项目管理器的日志里找到 EOF chmod x hooks/post-receive本地仓库添加远程地址后git push production main就能触发整套流程。这个钩子脚本里最关键的是checkout -f它强制把 bare 仓库的内容同步到工作目录避免合并冲突。另外migrate和collectstatic放在钩子里执行保证每次部署后数据库和静态文件都是最新的。注意钩子脚本里的虚拟环境路径和项目名称要换成你自己的。重启项目的命令每个宝塔版本可能不一样建议先在命令行手动执行一次确认。从那以后我每次部署新项目都会先把这套钩子配好再开始写业务代码后面省下来的时间远超配置的十分钟。希望帮到你。本文还有配套的精品资源点击获取