在香港云服务器上部署Django网站,如何配置Gunicorn与Nginx?
在香港云服务器上部署 Django 网站时,建议把 Gunicorn 和 Nginx 分工处理:Gunicorn 负责加载 Django 应用并处理 Python 请求,Nginx 作为公网入口负责 80/443 端口、静态文件、HTTPS 和反向代理。Gunicorn 只监听本机 Unix Socket,不直接暴露到公网,可以减少端口暴露并方便由 systemd 统一管理。

以下以 Ubuntu 22.04 或 Ubuntu 24.04 LTS、Python 3、域名 example.com 为例。香港地域只决定服务器所在网络和公网地址,不会改变 Django、Gunicorn、Nginx 的部署方式。示例中的域名、项目包名、目录和密钥需要替换为实际值。
围绕 Django 网站的公网入口、应用进程与数据库等部署需求,A5idc数据提供中国香港物理服务器租用,覆盖入门建站、Xeon Gold 和 AMD EPYC 等配置,并配备 SSD 或 NVMe 存储及不同带宽线路。企业网站、业务后台、数据库和接口服务可结合访问地区、程序负载与数据规模,获得相应的计算、存储和网络资源基础。
一、准备域名、服务器和项目
1. 确认基础条件
开始操作前,至少需要准备以下内容:
- 一台具有公网 IPv4 地址的香港云服务器。
- 一个已经备案或可正常解析的域名,例如
example.com。 - 云平台安全组放行 TCP 22、80、443 端口。
- 可以通过 SSH 登录服务器的普通用户,尽量不要长期使用 root 运行 Django。
- Django 项目已经包含
manage.py、依赖文件和 WSGI 入口。 - 项目使用的数据库已经创建,并准备好数据库备份或恢复方案。
- 项目中已经明确生产环境的
SECRET_KEY、ALLOWED_HOSTS、静态文件目录和媒体文件目录。
域名解析建议至少配置以下记录:
| 类型 | 主机记录 | 指向 |
|---|---|---|
| A | @ | 香港云服务器公网 IPv4 |
| A | www | 香港云服务器公网 IPv4 |
如果服务器没有可用 IPv6,不要仅因为域名服务商默认提供 IPv6 选项就添加 AAAA 记录。错误的 AAAA 记录可能导致部分客户端优先访问不可用的 IPv6 地址。
在本地或服务器上检查解析结果:
dig +short example.com
dig +short www.example.com
预期结果应包含服务器公网 IPv4。如果没有结果,先处理 DNS 记录和 TTL,不要继续排查 Nginx 或 Gunicorn。
2. 约定部署目录
为了让后续命令容易对应,下面使用这些示例值:
| 项目 | 示例值 |
|---|---|
| 部署用户 | deploy |
| 项目目录 | /srv/django-site |
| Python 虚拟环境 | /srv/django-site/.venv |
| Django 配置包 | config |
| 静态文件目录 | /srv/django-site/staticfiles |
| 上传文件目录 | /srv/django-site/media |
| systemd 服务名 | django-site |
| Gunicorn Socket | /run/gunicorn/django-site.sock |
如果实际项目的 WSGI 文件是 mysite/wsgi.py,Gunicorn 入口就应改为 mysite.wsgi:application,不能直接照搬 config.wsgi:application。
3. 登录服务器并检查系统
先确认发行版、Python 版本和当前监听端口:
cat /etc/os-release
python3 --version
sudo ss -lntp
如果系统版本不是 Ubuntu LTS,软件包名称和 systemd、Nginx 默认路径可能存在差异,应先根据实际发行版调整命令。
安装基础软件:
sudo apt update
sudo apt install -y python3-venv python3-pip build-essential nginx certbot python3-certbot-nginx
某些 Python 依赖需要额外的数据库开发包,例如 PostgreSQL 或 MySQL 的客户端开发包。遇到 pip install 报缺少头文件时,应根据具体报错安装对应系统包,不要盲目安装一整套无关组件。
创建部署用户和目录。确认服务器上没有同名用户后执行:
id deploy >/dev/null 2>&1 || sudo adduser --disabled-password --gecos "" deploy
sudo install -d -o deploy -g deploy -m 0755 /srv/django-site
如果 /srv/django-site 已经存放其他项目,先检查目录内容和所有权,不要直接覆盖。
二、上传项目并准备 Django 运行环境
1. 上传代码
可以使用代码仓库、云平台文件传输功能或 rsync 上传项目。使用 rsync 时,在本地项目目录执行类似命令:
rsync -av --exclude '.venv/' --exclude '__pycache__/' ./ deploy@SERVER_IP:/srv/django-site/
将 SERVER_IP 替换为服务器公网地址。不要把本地虚拟环境、缓存目录和开发环境中的敏感文件上传到服务器。
上传后,在服务器上确认关键文件:
sudo -u deploy ls -la /srv/django-site
sudo -u deploy test -f /srv/django-site/manage.py
sudo -u deploy test -f /srv/django-site/requirements.txt
如果项目没有 requirements.txt,可以使用项目实际采用的依赖文件,但应确保 Gunicorn 已经被列入生产依赖。
2. 创建虚拟环境并安装依赖
sudo -u deploy -H bash -c 'cd /srv/django-site && python3 -m venv .venv && .venv/bin/pip install --upgrade pip wheel && .venv/bin/pip install -r requirements.txt'
检查 Django 和 Gunicorn 是否可用:
sudo -u deploy -H bash -c 'cd /srv/django-site && .venv/bin/python -m django --version && .venv/bin/gunicorn --version'
预期结果应分别显示 Django 版本和 Gunicorn 版本。如果提示命令不存在,先检查虚拟环境路径和 requirements.txt 内容。
3. 设置生产环境变量
生产密钥不要直接写入公开代码仓库。可以使用 systemd 的 EnvironmentFile 统一提供环境变量。
如果配置文件尚不存在,先创建一个只允许 root 和 deploy 组读取的文件:
if [ ! -e /etc/django-site.env ]; then
sudo install -o root -g deploy -m 0640 /dev/null /etc/django-site.env
fi
sudoedit /etc/django-site.env
示例内容如下:
DJANGO_SETTINGS_MODULE=config.settings
DJANGO_SECRET_KEY=replace-with-a-long-random-value
DJANGO_DEBUG=False
DJANGO_ALLOWED_HOSTS=example.com,www.example.com
DJANGO_CSRF_TRUSTED_ORIGINS=https://example.com,https://www.example.com
可以使用以下命令生成随机密钥,再将结果写入配置文件:
openssl rand -hex 32
这些变量名只是常见示例。Django 不会自动把所有变量应用到配置中,项目的 settings 文件必须通过 os.environ 或其他配置库读取它们。如果项目使用 config.settings.production,则应同步调整 DJANGO_SETTINGS_MODULE 和 Gunicorn 入口所使用的配置方式。
生产 settings 至少应确认以下内容:
DEBUG为False。ALLOWED_HOSTS只包含实际域名,不要为了绕过错误设置为*。STATIC_ROOT指向/srv/django-site/staticfiles。MEDIA_ROOT指向/srv/django-site/media。CSRF_TRUSTED_ORIGINS使用包含协议的完整地址。- 数据库连接信息通过环境变量或受保护的配置文件提供。
检查部署用户是否可以读取环境变量文件:
sudo -u deploy test -r /etc/django-site.env && echo "environment file is readable"
4. 执行 Django 检查、数据库迁移和静态文件收集
先执行 Django 的部署检查:
sudo -u deploy -H bash -c 'cd /srv/django-site && set -a && . /etc/django-site.env && set +a && .venv/bin/python manage.py check --deploy'
check --deploy 的警告需要逐项判断。密钥、调试模式、允许的 Host、Cookie 安全属性等问题不应被忽略;HSTS 等配置则应在 HTTPS 验证完成后再逐步启用。
如果项目使用数据库,先查看待执行的迁移计划:
sudo -u deploy -H bash -c 'cd /srv/django-site && set -a && . /etc/django-site.env && set +a && .venv/bin/python manage.py migrate --plan'
确认迁移内容后,先对现有数据库做可恢复的备份,再执行迁移:
sudo -u deploy -H bash -c 'cd /srv/django-site && set -a && . /etc/django-site.env && set +a && .venv/bin/python manage.py migrate'
数据库迁移可能修改表结构,影响范围包括当前数据库及依赖它的应用实例。迁移前应确认备份可以恢复,回滚不能简单理解为执行一次相反命令;部分迁移不可逆,应用代码回退也可能与新数据库结构不兼容。
创建静态文件和媒体文件目录:
sudo install -d -o deploy -g deploy -m 0755 /srv/django-site/staticfiles
sudo install -d -o deploy -g deploy -m 0755 /srv/django-site/media
执行静态文件收集:
sudo -u deploy -H bash -c 'cd /srv/django-site && set -a && . /etc/django-site.env && set +a && .venv/bin/python manage.py collectstatic --noinput'
如果这是已有站点,执行收集前应保留当前静态目录副本。collectstatic 可能覆盖同名资源,回滚时需要恢复之前的静态文件版本。
Nginx 需要读取静态文件和媒体文件。只调整这两个目录的组权限,不要对整个项目目录执行 chmod -R 777:
sudo chgrp -R www-data /srv/django-site/staticfiles /srv/django-site/media
sudo chmod -R g+rX /srv/django-site/staticfiles /srv/django-site/media
如果媒体文件包含不应公开访问的内容,不要在 Nginx 中直接暴露 /media/,应通过 Django 鉴权或其他受保护的文件服务提供。
三、先单独验证 Gunicorn
在建立 systemd 服务前,可以让 Gunicorn 临时监听本机 8000 端口,以区分 Django 应用问题和 Nginx 配置问题:
sudo -u deploy -H bash -c 'cd /srv/django-site && set -a && . /etc/django-site.env && set +a && .venv/bin/gunicorn --bind 127.0.0.1:8000 --workers 2 config.wsgi:application'
这个进程会占用当前终端。在另一个 SSH 会话中测试:
curl -I -H 'Host: example.com' http://127.0.0.1:8000/
首页可能返回 200、301、302 或应用自身的错误页面,具体取决于项目路由。关键是 Gunicorn 能建立连接,且终端没有导入错误、数据库连接错误或配置异常。
测试完成后,在运行 Gunicorn 的终端按 Ctrl+C 停止进程。Gunicorn 不应长期以手动前台方式运行,否则 SSH 断开后服务也会停止。
四、使用 systemd 管理 Gunicorn
创建服务文件:
sudoedit /etc/systemd/system/django-site.service
写入以下内容:
[Unit]
Description=Gunicorn service for Django site
After=network.target
[Service]
User=deploy
Group=www-data
WorkingDirectory=/srv/django-site
EnvironmentFile=/etc/django-site.env
RuntimeDirectory=gunicorn
RuntimeDirectoryMode=0755
UMask=0007
ExecStart=/srv/django-site/.venv/bin/gunicorn \
--workers 2 \
--bind unix:/run/gunicorn/django-site.sock \
--access-logfile - \
--error-logfile - \
--capture-output \
--timeout 60 \
--graceful-timeout 30 \
config.wsgi:application
Restart=on-failure
RestartSec=5
PrivateTmp=true
TimeoutStopSec=30
[Install]
WantedBy=multi-user.target
--workers 2 只是小型实例的起始示例。工作进程越多,内存消耗通常越高;应结合 free -h、应用响应时间和实际并发逐步调整,不要机械套用固定公式。1 核、低内存实例不适合直接启动大量 Worker。
加载服务并启动:
sudo systemctl daemon-reload
sudo systemctl enable --now django-site.service
sudo systemctl status django-site.service --no-pager
查看最近 50 条应用日志:
sudo journalctl -u django-site.service -n 50 --no-pager
确认 Socket 已创建:
sudo stat -c '%A %U %G %n' /run/gunicorn/django-site.sock
常见的正常结果类似于:
srw-rw---- deploy www-data /run/gunicorn/django-site.sock
再直接通过 Socket 测试应用:
curl --unix-socket /run/gunicorn/django-site.sock -I -H 'Host: example.com' http://localhost/
如果服务启动失败,优先查看 journalctl 中的第一条 Python 异常。导入模块失败通常是项目目录、虚拟环境或依赖问题;DisallowedHost 通常是 ALLOWED_HOSTS 未包含请求域名;数据库连接失败则应检查环境变量和数据库访问权限。
五、配置 Nginx 作为公网入口
1. 创建站点配置
创建 Nginx 配置文件:
sudoedit /etc/nginx/sites-available/django-site
写入:
upstream django_site {
server unix:/run/gunicorn/django-site.sock;
}
server {
listen 80;
server_name example.com www.example.com;
client_max_body_size 20m;
location /static/ {
alias /srv/django-site/staticfiles/;
expires 7d;
add_header Cache-Control "public";
}
location /media/ {
alias /srv/django-site/media/;
}
location / {
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;
proxy_read_timeout 60s;
proxy_redirect off;
proxy_pass http://django_site;
}
}
client_max_body_size 20m 是示例值,只影响通过 Nginx 上传的单次请求大小。如果业务需要上传更大的文件,应同时检查 Django、Gunicorn 和前端表单限制,不能只修改 Nginx。
启用配置:
sudo ln -s /etc/nginx/sites-available/django-site /etc/nginx/sites-enabled/django-site
先检查语法,确认无误后再重新加载:
sudo nginx -t
sudo systemctl reload nginx
预期结果应包含:
syntax is ok
test is successful
如果直接访问服务器公网地址看到默认 Nginx 页面,先检查请求使用的 Host 和 server_name 是否匹配。默认站点只处理没有匹配到其他域名的请求,不要在未备份的情况下删除系统默认配置。
2. 验证 Nginx 到 Gunicorn 的连接
在服务器本机发起带 Host 的请求:
curl -I -H 'Host: example.com' http://127.0.0.1/
如果返回 Django 的响应,说明 Nginx、Unix Socket 和 Gunicorn 已经连通。如果出现 502 Bad Gateway,先检查:
sudo systemctl is-active django-site.service
sudo stat -c '%A %U %G %n' /run/gunicorn/django-site.sock
sudo tail -n 50 /var/log/nginx/error.log
Nginx 工作进程通常属于 www-data 组,Socket 或其父目录没有相应访问权限时会出现 Permission denied。应修正 systemd 的 Group、Socket 权限或目录遍历权限,不要使用 chmod 777 作为临时解决方案。
六、配置 HTTPS 和 Django 安全选项
确认以下条件后再申请证书:
example.com和www.example.com已解析到当前服务器。- 云平台安全组和服务器防火墙允许 TCP 80、443。
curl -I -H 'Host: example.com' http://127.0.0.1/已经能够获得 Nginx 响应。- 站点配置中使用的是实际域名。
修改证书工具可能改写 Nginx 配置,先备份当前站点文件:
sudo cp -a /etc/nginx/sites-available/django-site /etc/nginx/sites-available/django-site.before-certbot
申请证书并配置 HTTP 到 HTTPS 的跳转:
sudo certbot --nginx --redirect -d example.com -d www.example.com
证书工具执行后检查配置:
sudo nginx -t
sudo systemctl reload nginx
从外部验证:
curl -I http://example.com/
curl -I https://example.com/
HTTP 请求通常应返回 301 或 308 跳转,HTTPS 请求则应返回应用自身的 200、301 或 302。如果证书申请失败,先检查 DNS、80 端口和域名是否能从公网访问,不要反复修改 Django 配置。
确认自动续期任务:
sudo systemctl list-timers | grep certbot
sudo certbot renew --dry-run
HTTPS 正常工作后,再在 Django 生产 settings 中启用与反向代理匹配的配置:
SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https")
SESSION_COOKIE_SECURE = True
CSRF_COOKIE_SECURE = True
SECURE_SSL_REDIRECT = True
SECURE_SSL_REDIRECT 应在 Nginx 已经正确传递 X-Forwarded-Proto 后启用,否则可能造成错误重定向。SECURE_HSTS_SECONDS 不建议首次上线就设置很长时间,应该先确认主域名、子域名和所有资源都能通过 HTTPS 访问,再逐步启用。
修改 Django 配置后重启应用:
sudo systemctl restart django-site.service
sudo systemctl status django-site.service --no-pager
重启会中断正在处理的请求,适合在首次上线或低流量时执行。仅修改 Nginx 配置时,优先使用 reload,避免不必要地停止服务。
七、配置防火墙和端口边界
云平台安全组和操作系统防火墙是两层不同的访问控制。对外只需要开放 SSH、HTTP 和 HTTPS,Gunicorn 的 Unix Socket 不占用公网 TCP 端口。
如果使用 UFW,先确认 SSH 当前端口。SSH 不是默认 22 端口时,必须先放行实际端口,再启用防火墙:
sudo ufw allow OpenSSH
sudo ufw allow 'Nginx Full'
sudo ufw status verbose
确认规则无误并确保当前 SSH 会话仍然可用后,再根据服务器现状启用:
sudo ufw enable
启用防火墙可能造成当前远程连接中断,尤其是在 SSH 端口、云平台安全组或 IPv6 规则配置错误时。调整规则前应保留云平台控制台或带外登录方式。回滚时先查看编号:
sudo ufw status numbered
只删除本次新增且确认有问题的规则,不要为了排障直接关闭所有防火墙。
八、上线后的结果检查
建议按照由外到内的顺序验收:
| 检查项目 | 命令或方法 | 合格表现 |
|---|---|---|
| DNS | dig +short example.com | 返回正确公网 IP |
| Gunicorn | systemctl is-active django-site | 返回 active |
| Unix Socket | stat /run/gunicorn/django-site.sock | 文件存在且 Nginx 可访问 |
| Nginx 配置 | sudo nginx -t | test is successful |
| HTTP 跳转 | curl -I http://example.com/ | 返回 HTTPS 跳转 |
| HTTPS 页面 | curl -I https://example.com/ | 返回应用预期状态码 |
| 静态文件 | 浏览器或 curl 请求实际静态资源 | 返回资源而非 404/403 |
| 应用日志 | journalctl -u django-site -n 50 | 无持续异常重启 |
| Nginx 日志 | /var/log/nginx/access.log、error.log | 无持续 502 或权限错误 |
| 证书续期 | sudo certbot renew --dry-run | 模拟续期成功 |
浏览器检查时,还应打开开发者工具确认:
- 页面资源没有混合内容警告。
- CSS、JavaScript 和图片没有大量 404。
- 登录、退出、表单提交没有 CSRF 错误。
- 上传文件大小符合业务预期。
- 访问不存在的页面时,返回的是项目设计的 404 页面,而不是泄露调试信息。
九、常见异常处理
1. 域名能解析,但浏览器连接超时
先在服务器检查监听状态:
sudo ss -lntp | grep -E ':80|:443'
如果没有监听 80 或 443,检查 Nginx 状态:
sudo systemctl status nginx --no-pager
sudo journalctl -u nginx -n 50 --no-pager
如果服务器本机访问正常、外部访问超时,重点检查云平台安全组、UFW、服务器公网 IP 和错误的 AAAA 记录。
2. Nginx 返回 502
依次检查:
sudo systemctl status django-site.service --no-pager
sudo journalctl -u django-site.service -n 100 --no-pager
sudo ls -l /run/gunicorn/django-site.sock
sudo tail -n 50 /var/log/nginx/error.log
不同结果对应的方向不同:
- 没有 Socket:Gunicorn 没有启动成功,检查 Python 导入、依赖和环境变量。
Permission denied:检查 Socket 所属用户、组以及/run/gunicorn的目录权限。Connection refused:如果配置的是 TCP 端口,检查 Gunicorn 是否监听该端口;当前示例使用 Unix Socket,则应检查 Socket 是否存在。- Worker 反复退出:检查内存、数据库连接和应用启动日志。
3. 返回 DisallowedHost
确认请求域名已经加入 ALLOWED_HOSTS,并重新加载 Django 服务。不要直接设置为 * 来掩盖域名配置错误。
4. 表单提交出现 CSRF 错误
确认 CSRF_TRUSTED_ORIGINS 使用完整的 HTTPS 地址,例如:
https://example.com,https://www.example.com
同时检查 Nginx 是否传递了:
proxy_set_header X-Forwarded-Proto $scheme;
修改后重启 Gunicorn。若只在 HTTPS 下报错,还要检查 SECURE_PROXY_SSL_HEADER 是否与当前代理链一致。
5. 静态文件返回 404 或 403
检查 Django 的 STATIC_ROOT、collectstatic 结果和 Nginx 的 alias 路径:
sudo find /srv/django-site/staticfiles -maxdepth 2 -type f | head
sudo namei -l /srv/django-site/staticfiles
location /static/ 使用 alias 时,目录路径通常应保留结尾斜杠。还要确认 Nginx 用户可以穿过 /srv/django-site 的父目录。
6. 上传返回 413
这是 Nginx 的请求体大小限制。检查 client_max_body_size 是否小于业务所需值,同时确认 Django 表单和应用服务器也允许相同大小。调整前应评估磁盘空间、内存和带宽影响,不要无限制放大上传上限。
7. 请求超时或服务器内存持续升高
先查看资源和进程:
free -h
nproc
ps -eo pid,user,%mem,%cpu,cmd --sort=-%mem | head
再检查 Gunicorn 日志和 Nginx 错误日志。不要只把 --timeout 调得很大;慢查询、外部接口调用、文件处理和 Worker 数量都可能是根因。低内存实例应优先减少 Worker,或拆分耗时任务,而不是继续增加并发进程。
十、上线失败时的回滚方式
首次配置前,至少保留 Nginx、systemd 和 Django 环境文件的备份:
sudo cp -a /etc/nginx/sites-available/django-site /etc/nginx/sites-available/django-site.backup
sudo cp -a /etc/systemd/system/django-site.service /etc/systemd/system/django-site.service.backup
sudo cp -a /etc/django-site.env /etc/django-site.env.backup
回滚配置时,先停止应用服务,恢复文件,再进行语法检查:
sudo systemctl stop django-site.service
sudo cp -a /etc/systemd/system/django-site.service.backup /etc/systemd/system/django-site.service
sudo cp -a /etc/nginx/sites-available/django-site.backup /etc/nginx/sites-available/django-site
sudo systemctl daemon-reload
sudo nginx -t
sudo systemctl start django-site.service
sudo systemctl reload nginx
如果只是代码版本异常,应恢复经过验证的代码目录或部署包,不要在没有备份的情况下直接删除当前目录。后续多次发布时,可以采用 /srv/releases/版本目录 加软链接的方式,每次发布保留上一版本,从而只切换应用目录而不覆盖正在运行的文件。
如果已经执行数据库迁移,代码回滚前必须确认旧版本是否兼容新的数据库结构。数据库回滚应使用迁移前备份和经过验证的恢复流程,不能把 migrate 的反向操作当作通用回滚方案。
最终验收可以按以下清单逐项确认:
- 域名解析到正确的香港云服务器公网地址。
- 云安全组和 UFW 仅放行必要端口。
- Gunicorn 由 systemd 启动,服务器重启后能够自动恢复。
- Gunicorn 只通过本机 Unix Socket 提供服务。
- Nginx 配置检查通过,80 端口可以跳转到 HTTPS。
- HTTPS 证书有效,
certbot renew --dry-run通过。 - Django 的
DEBUG已关闭,Host 和 CSRF 域名配置准确。 - 静态资源、媒体文件、登录和表单提交均按预期工作。
- Nginx 和 Gunicorn 日志中没有持续的 502、403、导入错误或 Worker 重启。
- 配置备份、代码版本和数据库恢复路径均已保留,可以在出现问题时恢复到上一个可用状态。
本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/9558.html



