generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Deployment-Template wiki_url: https://git.ilapage.cn/OPC/chorus/wiki/Deployment-Template.- wiki_revision: 140d8bbf71ba8ec2ab5c9880241a824aae57a06a synchronized_at: 2026-08-20T03:29:49Z # 部署文档模板 > 使用说明：本页是 DevHarness 模板，不描述任何真实服务。有常驻服务的项目复制本页，在自己的 Gitea Wiki 创建 `Deployment-and-Operations` 页面，并在本项目 `wiki-docs.json` 增加映射（建议镜像到 `docs/10-deployment-and-operations.md`）。填写时删除全部说明性文字，不得保留“待填写”后直接交付。没有常驻服务的项目不要创建部署页，在初始化工单记录原因即可。 > > 本模板面向项目内部维护者。面向客户或外部运维岗位的部署说明属于交付文档，使用[岗位文档模板](Audience-Document-Template.-)。 > > 标准栈为 nginx 反向代理 + supervisor 进程托管，示例按 Python 服务（gunicorn / uvicorn）编写。实际技术栈不同时替换命令，但保留章节结构和“每条命令写明预期结果”的要求。 ## 本页用途 让维护者能够在一台干净的服务器上完成首次部署、日常运维、健康检查和回滚。所有命令默认以具备 sudo 权限的账号在服务器上执行，示例以 Linux 为主。 ## 安全边界 - 本页只写配置项的**名称和来源**，不写任何真实密码、令牌、私钥、证书内容、生产数据库地址或个人数据。 - 需要凭据的步骤写明“从哪里取”，例如运维密码库条目名或环境变量名。 - 涉及删除数据、数据库迁移和不可逆操作的步骤必须给出醒目警告、影响范围和回退条件。 ## 服务概览 | 项目 | 内容 | |---|---| | 服务名（supervisor program） | `` | | 代码部署目录 | `/srv/` | | 运行账号 | `` | | 运行时 | Python `<3.x>` | | 应用服务器 | gunicorn / uvicorn | | 本地监听地址 | `127.0.0.1:<8000>` | | 进程数 | `` | | 对外域名与路径 | `https:///` | | 依赖的外部服务 | 数据库 / 缓存 / 对象存储 / 无 | | 日志目录 | `/var/log//` | 服务只监听 `127.0.0.1`，不直接对外暴露端口；所有外部访问经 nginx 转发。 ## 环境要求 | 组件 | 版本要求 | 检查命令 | 预期结果 | |---|---|---|---| | 操作系统 | `` | `cat /etc/os-release` | 输出与要求一致 | | Python | `<3.11+>` | `python3 --version` | 输出版本号且不低于要求 | | nginx | `<1.18+>` | `nginx -v` | 输出版本号 | | supervisor | `<4.2+>` | `supervisord --version` | 输出版本号 | 未安装时： ```bash sudo apt update sudo apt install -y nginx supervisor python3-venv ``` **预期结果**：`systemctl status nginx` 与 `systemctl status supervisor` 均为 `active (running)`。 ## 首次部署 ### 1. 创建运行账号与目录 ```bash sudo useradd --system --home /srv/ --shell /usr/sbin/nologin sudo mkdir -p /srv/ /var/log/ sudo chown -R : /srv/ /var/log/ ``` **预期结果**：`id ` 输出该账号；两个目录存在且属主为 ``。 服务账号使用 `nologin`，不允许直接登录。 ### 2. 取得代码 ```bash sudo -u git clone <仓库地址> /srv//app cd /srv//app && sudo -u git rev-parse HEAD ``` **预期结果**：输出本次部署的完整提交哈希，记录到部署记录中。 ### 3. 安装依赖 ```bash sudo -u python3 -m venv /srv//venv sudo -u /srv//venv/bin/pip install -r /srv//app/requirements.txt ``` **预期结果**：pip 以 `Successfully installed ...` 结束，无 ERROR。 ### 4. 落位配置文件 ```bash sudo install -o -g -m 600 /dev/null /srv//app.env sudo -u vi /srv//app.env ``` **预期结果**：`ls -l /srv//app.env` 显示权限 `-rw-------` 且属主为 ``。 配置项清单见下方“配置与凭据来源”。配置文件不进入 Git。 ### 5. 数据库初始化或迁移 > **注意**：迁移可能不可逆。执行前必须先备份，并确认回退方式。 ```bash sudo -u /srv//venv/bin/python -m .manage migrate ``` **预期结果**：输出全部迁移已应用，无失败项。 ## supervisor 配置 写入 `/etc/supervisor/conf.d/.conf`： ```ini [program:] command=/srv//venv/bin/gunicorn .wsgi:application --workers --bind 127.0.0.1:<8000> --timeout 60 directory=/srv//app user= environment=PATH="/srv//venv/bin",APP_ENV_FILE="/srv//app.env" autostart=true autorestart=true startsecs=5 stopasgroup=true killasgroup=true stopwaitsecs=30 stdout_logfile=/var/log//stdout.log stderr_logfile=/var/log//stderr.log stdout_logfile_maxbytes=50MB stdout_logfile_backups=5 ``` > 异步框架使用 uvicorn 时把 `command` 换成： > `/srv//venv/bin/uvicorn .asgi:app --host 127.0.0.1 --port <8000> --workers ` 不要在 `environment` 里写明文密码或令牌；敏感值放在 `app.env`，由应用读取。 加载配置并启动： ```bash sudo supervisorctl reread sudo supervisorctl update sudo supervisorctl start sudo supervisorctl status ``` **预期结果**：`reread` 输出 `: available`；`status` 显示 `RUNNING` 且 uptime 持续增长。出现 `BACKOFF` 或 `FATAL` 时查看 `stderr.log`。 ## nginx 配置 写入 `/etc/nginx/sites-available/.conf` 并软链到 `sites-enabled`： ```nginx server { listen 80; server_name ; access_log /var/log/nginx/.access.log; error_log /var/log/nginx/.error.log; client_max_body_size <20m>; location /static/ { alias /srv//app/static/; expires 7d; } location / { proxy_pass http://127.0.0.1:<8000>; proxy_http_version 1.1; 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 <60s>; } } ``` 启用并生效： ```bash sudo ln -sf /etc/nginx/sites-available/.conf /etc/nginx/sites-enabled/.conf sudo nginx -t sudo systemctl reload nginx ``` **预期结果**：`nginx -t` 输出 `syntax is ok` 与 `test is successful`；reload 无输出且 `systemctl status nginx` 仍为 `active (running)`。 `nginx -t` 未通过时不要 reload，先修正配置。 ## 配置与凭据来源 | 配置项 | 用途 | 来源 | 是否敏感 | |---|---|---|---| | `APP_ENV_FILE` | 指向配置文件路径 | supervisor 配置 | 否 | | `` | 数据库连接 | `/srv//app.env`，值取自运维密码库条目 `<条目名>` | 是 | | `` | 会话与签名 | 同上 | 是 | | `` | 日志级别 | `/srv//app.env` | 否 | 敏感值只记录取用位置，不在本页、工单、日志和提交中出现真实内容。 ## 日常运维 | 操作 | 命令 | 预期结果 | |---|---|---| | 查看状态 | `sudo supervisorctl status ` | `RUNNING`，uptime 持续增长 | | 重启服务 | `sudo supervisorctl restart ` | 输出 `stopped` 后 `started` | | 停止服务 | `sudo supervisorctl stop ` | 输出 `stopped` | | 实时日志 | `sudo supervisorctl tail -f stderr` | 持续输出应用日志 | | 应用日志 | `sudo tail -n 200 /var/log//stderr.log` | 输出最近日志 | | 接入层日志 | `sudo tail -n 200 /var/log/nginx/.error.log` | 输出 nginx 错误 | | 重载 nginx | `sudo nginx -t && sudo systemctl reload nginx` | 测试通过后无中断生效 | 修改 supervisor 配置后必须 `reread` + `update`，只 `restart` 不会加载新配置。 ## 健康检查 每次部署、重启和回滚后必须全部执行： ```bash sudo supervisorctl status curl -sS -o /dev/null -w "%{http_code}\n" http://127.0.0.1:<8000><健康检查路径> curl -sS -o /dev/null -w "%{http_code}\n" https://<健康检查路径> sudo tail -n 50 /var/log//stderr.log ``` **预期结果**：状态为 `RUNNING`；两个 `curl` 均返回 `200`；日志无新增异常堆栈。 任何一项不符合时不视为部署成功，按“升级与回滚”处理。 ## 升级与回滚 ### 升级 ```bash cd /srv//app sudo -u git rev-parse HEAD # 记录当前提交，回滚需要 sudo -u git fetch --all sudo -u git checkout <目标提交或标签> sudo -u /srv//venv/bin/pip install -r requirements.txt sudo -u /srv//venv/bin/python -m .manage migrate # 无数据库时删除 sudo supervisorctl restart ``` **预期结果**：restart 后 `status` 为 `RUNNING`，随后健康检查全部通过。 升级前必须记录当前提交哈希；涉及数据库迁移时必须先备份。 ### 回滚 ```bash cd /srv//app sudo -u git checkout <升级前记录的提交> sudo -u /srv//venv/bin/pip install -r requirements.txt sudo supervisorctl restart ``` **预期结果**：健康检查全部通过。 > **注意**：已执行的数据库迁移通常不能通过切回代码撤销。存在迁移时必须先确认迁移是否向后兼容；不兼容时按备份恢复流程处理，并停止自行操作、联系负责人。 ### 备份与恢复 ## 已知限制 -