如何在香港服务器上用Codex开发Django网站并完成基础部署?

发布人:A5数据发布时间:2026-10-11 15:49阅读量:195

要在香港服务器上用 Codex 开发 Django 网站并完成基础部署,需要把“代码开发”和“生产运行”分开处理:Codex 用于生成、修改和检查项目代码,Django 由 Gunicorn 运行,Nginx 负责网站入口和静态文件,systemd 负责进程管理。下面以 Ubuntu Server 24.04 LTS、Python 3.12、Django 5.2 系列为例,完成一个带首页、健康检查和后台管理的小型网站部署。

上线目标是通过 https://www.example.com 访问网站,并做到重启后自动运行、密钥不进入代码仓库、数据库不放在发布目录中、应用端口不向公网开放。示例采用 SQLite,适合单机、低写入量的基础网站;涉及订单、频繁并发写入或多实例部署时,应改用 PostgreSQL 等数据库,不能直接照搬本文的数据层方案。

针对 Django 网站、业务后台和接口服务等部署场景,A5数据提供中国香港物理服务器资源,覆盖入门建站、Xeon Gold 与 AMD EPYC 等配置,并配备 SSD 或 NVMe 存储及 CN2、国际带宽线路。不同硬件与网络组合可承载从常规网站到数据库、多任务应用的运行需求,为 Gunicorn、Nginx 及 HTTPS 组成的生产环境提供服务器基础。

一、确认服务器环境与使用边界

准备条件

开始前准备以下条件:

  • 一台可通过 SSH 登录、拥有 sudo 管理权限的香港服务器。
  • 已安装 Ubuntu Server 24.04 LTS,并有足够磁盘空间保存应用、虚拟环境和备份。
  • 一个可管理 DNS 的域名,示例使用 www.example.com。
  • 域名的 A 记录指向服务器公网 IPv4;如果配置 AAAA 记录,IPv6 也必须能够正常到达服务器。
  • 管理入口可用,能够在防火墙误配置时通过服务商控制台恢复。
  • 可正常使用的 Codex 账户或 API 授权,以及符合相关服务地区要求的开发环境。

先检查系统:

cat /etc/os-release
python3 --version
df -h /
free -h

本文命令按 Ubuntu 24.04 编写,Python 应为 3.12 系列。示例可从 2 核、2 GB 内存的小型实例开始验证,但这不是容量承诺,实际资源需求取决于请求量、页面逻辑和后台任务。

香港服务器能够托管 Django,不等于该服务器所在地区一定满足 Codex 的服务使用条件。 安装前应核对 OpenAI 的支持地区、账户资格和组织策略。若香港服务器所在网络不符合使用条件,应在符合条件的开发环境中使用 Codex,再通过代码仓库或受控文件传输发布到香港服务器;不要把服务不可用当成 Django 部署问题处理。

下文的 Codex 命令仅适用于已确认具备使用资格、能够正常连接相关服务的环境。若采用异地开发方式,生产部署步骤仍可在香港服务器执行。

确定目录与权限边界

本文使用以下目录:

路径用途写入主体
/home/deploy/a5siteCodex 开发工作区deploy
/srv/a5django/releases/版本号已审核的发布文件发布阶段写入,完成后由 root 持有
/srv/a5django/current指向当前版本的软链接管理员
/srv/a5django/dataSQLite 数据库a5web
/etc/a5django.env生产环境变量管理员

开发账户不加入运行账户的组,也不授予 sudo 权限。这样,即使开发过程出现错误,Codex 也不能直接修改生产密钥或生产数据库。

二、安装依赖,并让 Codex 完成开发任务

1. 安装系统软件与账户

以下命令由原有的 sudo 管理员执行。软件安装会改变系统状态,建议先创建服务器快照;已有生产业务的机器应先评估端口、软件包和配置冲突。

sudo apt update
sudo apt install -y \
  python3-venv python3-pip \
  nginx git curl ca-certificates xz-utils rsync \
  ufw certbot python3-certbot-nginx

sudo adduser --disabled-password --gecos "" deploy
sudo useradd --system --user-group \
  --home-dir /nonexistent --shell /usr/sbin/nologin a5web

这些账户名应尚未存在。若已存在,先用 id deploy、id a5web 检查身份与权限,不要重复创建。

验证软件:

nginx -v
python3 --version
git --version
id deploy
id a5web

进入开发账户:

sudo -iu deploy

后续开发操作都在这个普通账户下进行,不用 root 运行 Codex。

2. 安装 Node.js 和 Codex CLI

Codex CLI 的安装方式与运行要求可能随版本变化。先检查现有环境:

node --version
npm --version

若没有合适的 Node.js,可在开发账户内安装 Node.js 22 系列的最新维护版本。下面从 Node.js 发布目录获取二进制文件,并校验 SHA-256,不修改系统自带软件:

case "$(uname -m)" in
  x86_64) NODE_ARCH=x64 ;;
  aarch64) NODE_ARCH=arm64 ;;
  *) echo "请为该架构选择受支持的安装方式"; exit 1 ;;
esac

mkdir -p "$HOME/.local/lib" "$HOME/.local/bin"
WORKDIR=$(mktemp -d)
cd "$WORKDIR"

curl -fSLO https://nodejs.org/dist/latest-v22.x/SHASUMS256.txt
NODE_FILE=$(awk -v arch="$NODE_ARCH" \
  '$2 ~ ("-linux-" arch "\\.tar\\.xz$") {print $2; exit}' \
  SHASUMS256.txt)

test -n "$NODE_FILE"
curl -fSLO "https://nodejs.org/dist/latest-v22.x/$NODE_FILE"
grep "  $NODE_FILE$" SHASUMS256.txt | sha256sum -c -

tar -xJf "$NODE_FILE" -C "$HOME/.local/lib"
NODE_DIR="${NODE_FILE%.tar.xz}"

ln -sfn "$HOME/.local/lib/$NODE_DIR/bin/node" "$HOME/.local/bin/node"
ln -sfn "$HOME/.local/lib/$NODE_DIR/bin/npm" "$HOME/.local/bin/npm"

export PATH="$HOME/.local/bin:$PATH"

校验结果应显示对应文件为 OK。失败时停止安装,不要继续解压或执行。

再安装 Codex:

npm config set prefix "$HOME/.local"
npm install -g @openai/codex

node --version
codex --version
codex --help
codex login --help

将下面一行添加到 ~/.profile,便于以后登录时找到命令:

export PATH="$HOME/.local/bin:$PATH"

按当前版本的帮助信息完成登录。交互式账户登录可从 codex login 开始;无浏览器服务器应按 CLI 提示使用其支持的授权流程。

登录凭据可能保存在开发账户目录中,应限制账户访问。不要把 API 密钥粘贴进项目文件、提交到 Git,或写入公开的部署日志。

3. 创建 Django 项目

mkdir -p "$HOME/a5site"
cd "$HOME/a5site"
umask 027

python3 -m venv .venv
source .venv/bin/activate

python -m pip install --upgrade pip
python -m pip install "Django>=5.2,<5.3" "gunicorn>=23,<24"

django-admin startproject config .
python manage.py startapp pages

git init
cat > .gitignore <<'EOF'
.venv/
.env
db.sqlite3
__pycache__/
*.py[cod]
staticfiles/
node_modules/
EOF

python -m pip freeze > requirements.txt

这里的版本范围用于首次安装,requirements.txt 保存实际安装版本。之后发布应使用该文件,不要让生产服务器每次自行选择不同依赖版本。

4. 给 Codex 明确的开发任务

在项目目录运行:

export DJANGO_DEBUG=1
codex

可以使用下面的任务描述:

请在当前 Django 项目中实现一个基础网站:

1. 注册 pages 应用。
2. 首页使用 Django 模板,显示站点名称和“服务运行正常”。
3. 添加 /healthz/,执行数据库 SELECT 1。
   成功返回 {"status":"ok"};数据库异常返回 503,
   不向客户端暴露异常堆栈。
4. 保留 Django admin 路由。
5. 添加首页和健康检查测试,测试使用 Django 测试数据库。
6. 不安装无关依赖,不读取生产密钥,不执行 sudo,
   不修改系统服务、Nginx、防火墙或项目目录之外的文件。
7. 完成后说明修改文件、测试命令和待人工检查事项。

Codex 适合执行边界明确的代码任务,不适合接收“全权接管服务器”的指令。保留操作审批,逐项检查它准备执行的命令。

5. 配置生产参数并验证

检查 config/settings.py,删除或替换原有同名配置,确保包含以下逻辑。os 和 ImproperlyConfigured 的导入放在文件顶部,其余配置放在 BASE_DIR 定义之后:

import os

from django.core.exceptions import ImproperlyConfigured

DEBUG = os.environ.get("DJANGO_DEBUG", "0") == "1"

SECRET_KEY = os.environ.get("DJANGO_SECRET_KEY")
if not SECRET_KEY:
    if DEBUG:
        SECRET_KEY = "development-only-not-for-production"
    else:
        raise ImproperlyConfigured("DJANGO_SECRET_KEY is required")

ALLOWED_HOSTS = [
    value.strip()
    for value in os.environ.get(
        "DJANGO_ALLOWED_HOSTS", "localhost,127.0.0.1"
    ).split(",")
    if value.strip()
]

DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.sqlite3",
        "NAME": os.environ.get(
            "DJANGO_DB_PATH", str(BASE_DIR / "db.sqlite3")
        ),
    }
}

STATIC_URL = "/static/"
STATIC_ROOT = BASE_DIR / "staticfiles"

CSRF_TRUSTED_ORIGINS = [
    value.strip()
    for value in os.environ.get(
        "DJANGO_CSRF_TRUSTED_ORIGINS", ""
    ).split(",")
    if value.strip()
]

SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https")
SECURE_SSL_REDIRECT = os.environ.get("DJANGO_HTTPS", "0") == "1"
SESSION_COOKIE_SECURE = SECURE_SSL_REDIRECT
CSRF_COOKIE_SECURE = SECURE_SSL_REDIRECT

HTTPS 判断依赖 Nginx 设置的请求头,因此后面必须让 Gunicorn 只监听回环地址,不能允许公网客户端直接访问它。

执行检查:

DJANGO_DEBUG=1 python manage.py check
DJANGO_DEBUG=1 python manage.py makemigrations --check --dry-run
DJANGO_DEBUG=1 python manage.py test

git diff
git status --short

测试通过后提交:

git add .
git commit -m "Add basic Django site and health check"
git rev-parse --short HEAD

正常情况下,系统检查不应出现错误,测试应全部通过。示例测试输出可能是 Ran 2 tests ... OK,具体数量取决于实际编写的测试,并非本文的执行记录。

三、生成发布版本并配置 Gunicorn

1. 建立独立发布目录

退出开发账户,回到 sudo 管理员:

exit

以下命令适用于首次发布,目录名使用时间戳,避免覆盖已有版本:

RELEASE=$(date -u +%Y%m%d%H%M%S)

sudo install -d -m 0755 /srv/a5django/releases
sudo install -d -o a5web -g a5web -m 0750 /srv/a5django/data
sudo install -d -o deploy -g deploy -m 0750 \
  "/srv/a5django/releases/$RELEASE"

sudo rsync -a --chown=deploy:deploy \
  --exclude='.git/' --exclude='.venv/' \
  --exclude='.env' --exclude='db.sqlite3' \
  --exclude='__pycache__/' --exclude='node_modules/' \
  --exclude='staticfiles/' \
  /home/deploy/a5site/ "/srv/a5django/releases/$RELEASE/"

复制前确认开发工作区已通过测试且没有未提交修改。生产目录不包含 Codex 凭据、开发数据库或环境密钥。

在新目录建立虚拟环境并收集静态文件:

sudo -u deploy bash -c '
set -e
umask 027
cd "$1"
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
DJANGO_DEBUG=1 .venv/bin/python manage.py check
DJANGO_DEBUG=1 .venv/bin/python manage.py collectstatic --noinput
' bash "/srv/a5django/releases/$RELEASE"

sudo chown -R root:root "/srv/a5django/releases/$RELEASE"
sudo chmod -R u+rwX,go+rX,go-w "/srv/a5django/releases/$RELEASE"

sudo ln -s "/srv/a5django/releases/$RELEASE" /srv/a5django/current

发布文件仅包含可公开读取的代码和静态资源,密钥另行保存。最后的权限调整使运行账户不能修改代码。首次部署时 current 不应存在;后续更新不要重复执行最后一条命令,使用本文末尾的链接切换方式。

三、生成发布版本并配置 Gunicorn/建立独立发布目录配图

2. 创建生产环境变量

下面仅创建不存在的配置文件,避免误覆盖现有密钥。执行前把域名改为实际值:

sudo python3 - <<'PY'
import os
import secrets

content = (
    f"DJANGO_SECRET_KEY={secrets.token_urlsafe(48)}\n"
    "DJANGO_DEBUG=0\n"
    "DJANGO_ALLOWED_HOSTS=www.example.com,127.0.0.1,localhost\n"
    "DJANGO_CSRF_TRUSTED_ORIGINS=https://www.example.com\n"
    "DJANGO_DB_PATH=/srv/a5django/data/db.sqlite3\n"
    "DJANGO_HTTPS=0\n"
)

fd = os.open(
    "/etc/a5django.env",
    os.O_WRONLY | os.O_CREAT | os.O_EXCL,
    0o640,
)
with os.fdopen(fd, "w") as stream:
    stream.write(content)
PY

sudo chown root:a5web /etc/a5django.env
sudo chmod 0640 /etc/a5django.env

暂时关闭强制 HTTPS,是为了先验证 HTTP 链路和申请证书。不要将这份文件加入 Git。

定义一个管理命令函数,确保迁移以运行账户执行,并加载生产配置:

dj() {
  sudo bash -c '
    set -a
    source /etc/a5django.env
    set +a
    cd /srv/a5django/current
    exec runuser -u a5web -- .venv/bin/python manage.py "$@"
  ' bash "$@"
}

该文件同时按 shell 环境文件读取,只应由管理员维护,使用简单的 KEY=value 格式,不写入任意 shell 语句。

执行首次迁移和后台账户创建:

dj check
dj migrate --plan
dj migrate
dj createsuperuser

迁移会改变数据库结构。这里按空数据库首次安装执行;更新已有网站之前必须先备份数据库,不能把首次安装命令当作无风险更新流程。

3. 配置 systemd

创建 /etc/systemd/system/a5django.service:

[Unit]
Description=A5 Django website
After=network.target

[Service]
User=a5web
Group=a5web
WorkingDirectory=/srv/a5django/current
EnvironmentFile=/etc/a5django.env
ExecStart=/srv/a5django/current/.venv/bin/python -m gunicorn config.wsgi:application --bind 127.0.0.1:8000 --workers 2 --timeout 30 --access-logfile - --error-logfile -
Restart=on-failure
RestartSec=3
UMask=0027
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/srv/a5django/data

[Install]
WantedBy=multi-user.target

两个 worker 是起步配置,不是性能保证。SQLite 场景应尽量保持写事务短小;反复出现数据库锁等待时,应评估数据库方案,而不是继续增加 worker。

启动并验证:

sudo systemctl daemon-reload
sudo systemctl enable --now a5django
sudo systemctl status a5django --no-pager

curl -i http://127.0.0.1:8000/healthz/

预期服务状态为 active (running),健康检查返回 HTTP 200 和 {"status":"ok"}。失败时先查看日志,不要反复重启掩盖错误:

sudo journalctl -u a5django -n 80 --no-pager

四、配置 Nginx、网络入口和 HTTPS

1. 创建网站配置

在 /etc/nginx/sites-available/a5django 写入以下内容,替换域名:

server {
    listen 80;
    server_name www.example.com;

    client_max_body_size 2m;

    location /static/ {
        alias /srv/a5django/current/staticfiles/;
    }

    location / {
        proxy_pass http://127.0.0.1:8000;
        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_connect_timeout 5s;
        proxy_read_timeout 30s;
    }
}

启用前确认不存在同域名配置,避免请求命中错误站点:

sudo nginx -T
sudo ln -s /etc/nginx/sites-available/a5django \
  /etc/nginx/sites-enabled/a5django

sudo nginx -t
sudo systemctl reload nginx

只有 nginx -t 成功才执行 reload。不要为了这个站点批量删除其他配置;在全新服务器上,默认站点可以保留,正确的 server_name 会匹配指定域名。

本机验证:

curl -i -H 'Host: www.example.com' \
  http://127.0.0.1/healthz/

这里返回 200,说明 Nginx 到 Gunicorn 的链路已连通。

2. 开放必要端口

服务器侧防火墙和服务商安全组都要核对,只开放实际需要的入口:

  • SSH 管理端口:尽可能限制管理来源地址。
  • TCP 80:HTTP 访问及证书验证。
  • TCP 443:HTTPS 访问。
  • TCP 8000:不向公网开放。

先核对 SSH 端口:

sudo sshd -T | grep '^port '
sudo ufw status verbose

下面只适用于 SSH 使用 22 端口的机器。启用 UFW 前保留现有会话,并准备控制台恢复入口:

sudo cp -a /etc/ufw "/root/ufw-backup-$(date +%Y%m%d%H%M%S)"
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status verbose

若使用自定义 SSH 端口,先放行实际端口,不能直接照抄 22/tcp。误配置时可从控制台临时执行 sudo ufw disable 恢复访问,再修正规则;不要长期以关闭防火墙代替配置。

从其他网络验证域名:

curl -i http://www.example.com/healthz/

本机正常而外部失败,应优先检查 DNS、服务器公网地址和入站规则,不要先改 Django 代码。

3. 申请证书并开启 HTTPS

确认证书域名的所有地址都能到达本机后,先备份 Nginx 配置:

sudo cp -a /etc/nginx \
  "/root/nginx-before-tls-$(date +%Y%m%d%H%M%S)"

sudo certbot --nginx -d www.example.com

按提示填写邮箱,并选择将 HTTP 重定向到 HTTPS。证书签发成功后再开启 Django 的安全选项:

sudo cp -a /etc/a5django.env /etc/a5django.env.before-https
sudo sed -i 's/^DJANGO_HTTPS=0$/DJANGO_HTTPS=1/' /etc/a5django.env

sudo systemctl restart a5django
sudo nginx -t
sudo certbot renew --dry-run

这一步会重启应用,已有请求可能受影响。若新配置导致异常,可恢复环境文件并重启应用;Nginx 的回退以之前保存的配置为准,恢复后仍须通过语法检查。

验证最终结果:

curl -I http://www.example.com/
curl -i https://www.example.com/healthz/

HTTP 应跳转到 HTTPS,HTTPS 健康检查应返回 200。浏览器打开首页和 /admin/,确认后台登录页样式正常,并验证管理员能够登录。

浏览器在香港服务器边界之外;边界内 Nginx 接收公网请求,静态路径读取 staticfiles,动态路径转到回环 Gunicorn/Django,再访问独立

五、按由外到内的顺序处理常见失败

不要同时修改 DNS、防火墙、Nginx 和 Django。先确定请求在哪一层中断,再处理对应配置。

现象优先检查判断与处理
域名无法访问,公网 IP 也不通安全组、UFW、Nginx 监听状态先解决网络入口,不调整应用
公网 IP 可访问,域名异常A、AAAA 记录与缓存删除错误地址或修正解析
Nginx 返回 502systemctl status a5django、应用日志Gunicorn 未启动、启动报错或监听地址不一致
Django 返回 400DJANGO_ALLOWED_HOSTS加入实际域名,不用 * 掩盖配置错误
后台提交返回 403HTTPS、CSRF 来源配置核对实际访问域名和 CSRF_TRUSTED_ORIGINS
页面正常但后台无样式staticfiles、Nginx alias、目录读取权限检查静态文件是否收集到当前发布目录
健康检查返回 503数据库路径、权限、磁盘空间数据库检查失败,不应伪装为健康
日志出现 database is locked写事务持续时间、并发写入缩短事务,必要时迁移数据库
HTTPS 出现重定向循环Nginx 转发头、Django HTTPS 判断确认 X-Forwarded-Proto 被 Nginx 正确覆盖

常用检查命令:

sudo ss -lntp
sudo journalctl -u a5django -n 100 --no-pager
sudo tail -n 80 /var/log/nginx/error.log
sudo namei -l /srv/a5django/current/staticfiles/admin/css/base.css
sudo ls -ld /srv/a5django/data
df -h

上线后的本机应用检查要携带 HTTPS 转发头,因为 Django 已启用强制 HTTPS:

curl -i \
  -H 'Host: www.example.com' \
  -H 'X-Forwarded-Proto: https' \
  http://127.0.0.1:8000/healthz/

该命令只用于本机诊断。公网客户端不应能够直接连接 Gunicorn。

另外,SECURE_PROXY_SSL_HEADER 不能修复证书问题,放宽 ALLOWED_HOSTS 不能修复数据库权限,关闭 CSRF 也不是后台登录故障的合理解决方式。

六、完成验收,并保留可执行的回滚路径

上线验收

执行生产安全检查:

dj check --deploy

对警告逐项解释和处理。HSTS 可在证书、续期和全部访问链路验证稳定后再启用;不要首次上线就设置长期策略并包含所有子域名。

验收至少核对:

  • 首页与 /healthz/ 均可通过 HTTPS 访问。
  • HTTP 按预期跳转,证书域名匹配,续期演练成功。
  • DEBUG=0,生产密钥未出现在 Git、页面或共享日志中。
  • Gunicorn 仅监听 127.0.0.1:8000。
  • 静态文件可访问,后台登录、提交和退出正常。
  • 数据库位于独立数据目录,运行账户能写数据库但不能改代码。
  • a5django 和 Nginx 均配置为开机启动。
  • 已记录当前发布路径、Git 提交号和依赖版本。

可在维护窗口做一次应用重启验证;整机重启会影响所有服务,应在确认其他业务允许后执行。

后续发布前的备份

SQLite 文件不能在持续写入时随意复制并当作可靠备份。本文的小型站点采用短暂停机方式,备份时确保没有其他进程写入数据库:

BACKUP=$(date -u +%Y%m%d%H%M%S)
sudo install -d -m 0700 "/root/a5django-backups/$BACKUP"

readlink -f /srv/a5django/current |
  sudo tee "/root/a5django-backups/$BACKUP/release.txt" >/dev/null

sudo systemctl stop a5django
sudo cp -a /srv/a5django/data \
  "/root/a5django-backups/$BACKUP/data"
sudo cp -a /etc/a5django.env \
  "/root/a5django-backups/$BACKUP/a5django.env"
sudo systemctl start a5django

备份包含数据库和密钥,应限制访问并保存到受控的异机位置。只有备份文件而没有恢复验证,仍不足以确认可回滚。

代码回滚与数据库回滚分开处理

后续版本继续使用新的发布目录。切换前记录旧目录;不要直接覆盖 current 中的文件。

若新版本仅修改页面或业务代码、数据库结构保持兼容,可切回旧版本:

OLD_RELEASE=/srv/a5django/releases/替换为实际旧版本号

test -d "$OLD_RELEASE"
sudo ln -s "$OLD_RELEASE" /srv/a5django/current.next
sudo mv -Tf /srv/a5django/current.next /srv/a5django/current
sudo systemctl restart a5django

执行前确认 current 是软链接、current.next 不存在。链接替换只改变版本指向,不删除版本文件;若路径填写错误,可按同样方法切回正确版本。

代码回滚不会撤销数据库迁移。 新版本若改变表结构、删除字段或转换数据,应提前检查反向迁移是否可行。需要恢复数据库备份时,先停止应用,保留故障现场,再恢复与旧代码匹配的数据目录和权限。恢复旧备份会丢失备份之后的写入,必须明确这一影响,不能在持续写入期间直接覆盖数据库文件。

六、完成验收,并保留可执行的回滚路径/代码回滚与数据库回滚分开处理配图

回滚后重新核对 HTTPS 首页、健康检查、后台登录和日志,并确认旧版本静态文件正常。保留故障版本、备份和迁移记录,完成原因分析后再清理,不要用删除发布目录代替回滚。

本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/3170.html

相关推荐