在香港云服务器上部署Django网站,如何配置Gunicorn与Nginx?

发布人:A5数据发布时间:2026-11-15 11:59阅读量:26

在香港云服务器上部署 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
Awww香港云服务器公网 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

只删除本次新增且确认有问题的规则,不要为了排障直接关闭所有防火墙。

八、上线后的结果检查

建议按照由外到内的顺序验收:

检查项目命令或方法合格表现
DNSdig +short example.com返回正确公网 IP
Gunicornsystemctl is-active django-site返回 active
Unix Socketstat /run/gunicorn/django-site.sock文件存在且 Nginx 可访问
Nginx 配置sudo nginx -ttest 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

相关推荐