支持 Jenkins 灰度发布与独立运行数据

2026-10-29 16:25:09 +08:00
parent ab5b3580c1
commit 27151b3ee5
30 changed files with 1284 additions and 14 deletions
@@ -20,6 +20,7 @@ PowerShell 下把目录和 `-g '*.py'` 分开传给 `rg`。报价字典可能整
 | 业务范围 | 实际文件与搜索锚点 | 联动位置 |
 |---|---|---|
 | 应用入口与配置 | `am.py`：`main`、延迟访问的 `app`；`logistics_chat/__init__.py`：`create_app`；`config.py`：`default_config`、`get_setting`；`runtime.py`：`serve_app` | `start.bat`、`.env.example` |
+| Jenkins 灰度部署 | `Jenkinsfile`、`Dockerfile`；`deploy/gray_config.py`：`GrayConfig`；`publish-gray.sh`、`activate-gray.sh`、`prepare-gray-tls.sh`、`renew-gray-tls.sh` | [部署指南](deployment.md)；独立持久化数据、证书和回环端口；`wsgi.py` 提供容器内路径 |
 | 请求钩子 | `logistics_chat/hooks.py`：`rate_limit`、`no_cache_html` | 工厂注册钩子；限流状态在 `app.extensions['rate_hits']` |
 | SQLite 与维护 | `logistics_chat/db.py`：`connect`、`close_connections`、`init_db`、`backup_db`、`save_message`、`last_user_question`、`load_context` | 维护 CLI 在 `scripts/`；旧会话自动清理仍未启用 |
 | 历史接口 | `logistics_chat/history_service.py`：`new_chat`、`get_history`、`get_messages`、`del_history`、`clear_all`；对应 `routes/history.py` | `static/js/chat.js`：`ensureConv`、`loadHistory`、`openConversation` |
@@ -31,7 +32,7 @@ PowerShell 下把目录和 `-g '*.py'` 分开传给 `rg`。报价字典可能整
 | 附件 | `logistics_chat/file_service.py`：`upload_file`、`cleanup_uploads`；`routes/files.py`：`uploaded_file` | 扩展名/大小/目录由配置提供；客户端 `addMsg`，客服端 `appendMsg` |
 | 登录、统计、订单、留言、导出 | `logistics_chat/business_service.py`：`admin_login`、`admin_stats`、`my_orders`、`add_ticket`、`list_tickets`、`export_chat` | `routes/admin.py`、`routes/business.py`；登录页 `static/js/admin_login.js` |
 | 页面 | `templates/index.html`、`templates/admin.html`、`templates/admin_login.html` | 先加载共享 `static/css/theme.css`，再加载对应 `chat`、`admin`、`admin_login` 的 CSS/JS；保留全局事件入口 |
-| 回归 | `tests/test_rules.py`、`test_storage.py`、`test_api.py`、`test_config.py`、`test_startup.py`、`test_maintenance_scripts.py`、`test_frontend.py`；`tests/frontend/admin.test.cjs` | 配置测试隔离 `.env` 和环境变量；数据、HTTP 与 SSE 使用隔离配置和模拟模型；Node 内置测试验证草稿、异步发送和服务资料抽屉；浏览器使用临时测试库 |
+| 回归 | `tests/test_rules.py`、`test_storage.py`、`test_api.py`、`test_config.py`、`test_deployment.py`、`test_gray_config.py`、`test_gray_activation.py`、`test_startup.py`、`test_maintenance_scripts.py`、`test_frontend.py`；`tests/frontend/admin.test.cjs` | Linux 回退模拟基础设施、实际操作临时文件；模型、数据库及上传隔离；Node 验证异步交互 |

 除标明的根目录文件外，表内缩写的 Python 文件均相对 `logistics_chat/`。

@@ -76,6 +77,7 @@ tests/                        # 按业务模块组织的回归

 - 路由只解析请求并包装响应；服务组织业务；规则模块提供确定性计算。依赖方向为 `routes → services → rules / db / ai_client`，下层不导入路由或根入口。
 - `db.py` 统一连接、schema 和历史持久化。人工与管理业务的 SQL 放在所属服务，HTTP 路由不执行 SQL。请求及流式请求结束时关闭连接，未提交事务回滚。
+- `init_db` 包括客服账号、订单与留言表，首次启动只建空表；不内置账号。重复初始化保留已有数据，业务测试从真实初始化结果插入夹具，不另建缺失表。
 - 所有模型 HTTP 经 `ai_client.post_completion`。保留流式问答 `(5, 90)`、压缩 `(5, 30)`、追问 `(5, 15)` 三组连接/读取超时；不能因共用客户端而合并期限。流结束或取消时释放 HTTP 响应。
 - 模块导入不建库、不备份、不清理附件、不访问模型。`create_app` 默认显式初始化运行目录、数据库、备份与旧附件清理；`INITIALIZE_RUNTIME=False` 可禁止这些动作，此时调用方负责提供已有 schema。访问兼容入口 `am.app` 视为显式创建应用。
 - `config.ROOT_DIR` 指向仓库根目录，模板/静态目录显式提供给 Flask。数据库、上传、备份、日志使用配置中的绝对路径，避免包文件移动改变数据位置。
@@ -105,7 +107,7 @@ tests/                        # 按业务模块组织的回归
 - 人工申请使用 `conv_id`，返回 `session_id`，后续用 `sid`。状态为 `waiting/active/closed`，消息方向为 `customer/agent`。
 - 计费档位、单位换算和舍入保持原样。`calc_freight.total` 仅含基础运费；附加费尚未统一并入。知识文档与 `knowledge_list` 同步维护。
 - 上传 URL 保留 `/uploads/`，默认 10MB，扩展名配置保持不变。原附件保留本地、继续忽略，目录迁移不另建一份数据。
- `agents`、`orders`、`tickets` 缺少初始化、后台鉴权不完整、轨迹为模拟数据，仍是已知限制。临时 UI/接口测试中补表只属于测试夹具，不代表修复生产初始化。
+- 后台鉴权和会话隔离仍不完整，轨迹为模拟数据。Linux 公网验收用 Nginx 全站密码隔离访问，不代表已修复面向客户开放所需的应用权限。

 ## 验证与维护

@@ -0,0 +1,154 @@
+# Linux 单机手动部署参考
+
+现行灰度环境使用 [Jenkins 部署流程](deployment.md)。本页保留独立主机的安装方法，不用于覆盖已有灰度服务。
+
+适用场景：Ubuntu / Debian、已有域名、仅自己验收。使用系统 Python 3.10+，无需前端构建或 GPU。入口为 HTTPS → Nginx 全站访问密码 → 本机 Waitress → Flask / SQLite。
+
+当前应用尚无完整登录会话、权限和会话数据隔离。验收期间必须保留全站访问密码，不能只保护 `/admin`，因为历史、导出和人工接口也能直接调用。此配置不代表已具备面向客户开放的权限体系。
+
+## 1. 域名与网络
+
+- 将验收子域名的 A 记录解析到服务器公网 IPv4；只有正确配置服务器 IPv6 后才添加 AAAA。
+- 服务器安全组和防火墙允许 TCP 80、443，保留实际使用的 SSH 管理端口。不要开放应用端口 5000。
+- 服务器需要能够出站访问 Python 包源及 `https://api.deepseek.com`。
+- 下文的 `chat.example.com` 均需替换成真实域名，包括 Nginx 配置内的证书路径。
+
+## 2. 上传源码并安装依赖
+
+首次部署使用 `baiyue-logistics-chat-linux-acceptance.tar.gz`。部署包包含本次工作区的部署文件和缺表修复，不含 `.git`、`.env`、虚拟环境、日志、数据库或本机附件。之前 Git 推送因认证失败未完成；若改用 Git 拉取，须先确认远端版本包含这些变更。
+
+将部署包上传到服务器 `/tmp/`，以下命令均在服务器执行。首次部署假设 `/opt/baiyue-logistics-chat` 尚不存在；已有安装请使用文末更新流程。
+
+```bash
+sudo apt update
+sudo apt install -y python3 python3-venv python3-pip nginx apache2-utils certbot
+python3 --version
+sudo tar --no-same-owner -xzf /tmp/baiyue-logistics-chat-linux-acceptance.tar.gz -C /opt
+sudo adduser --system --group --home /nonexistent --no-create-home baiyue
+sudo chown root:baiyue /opt/baiyue-logistics-chat
+sudo chmod 750 /opt/baiyue-logistics-chat
+cd /opt/baiyue-logistics-chat
+sudo python3 -m venv .venv
+sudo .venv/bin/python -m pip install -r requirements.txt
+```
+
+若系统已有专用 `baiyue` 用户，跳过 `adduser`。代码与虚拟环境归 root 所有；服务数据另存到 `/var/lib/`，无需让 Web 进程修改源码。
+
+## 3. 配置 DS 密钥
+
+仅首次复制配置，已有 `.env` 时跳过复制；不要把本机配置打进部署包。
+
+```bash
+sudo install -o root -g baiyue -m 640 .env.example .env
+sudoedit /opt/baiyue-logistics-chat/.env
+```
+
+在编辑器内填写 `DEEPSEEK_API_KEY=你的密钥`，无需加 `export`，不要在终端命令或日志中输出密钥。文件由应用工厂读取；本方案的 systemd 单元不再注入同名环境变量。更换密钥后重启服务。
+
+## 4. 启动应用服务
+
+```bash
+sudo install -m 644 deploy/baiyue-logistics-chat.service /etc/systemd/system/baiyue-logistics-chat.service
+sudo systemd-analyze verify /etc/systemd/system/baiyue-logistics-chat.service
+sudo systemctl daemon-reload
+sudo systemctl enable --now baiyue-logistics-chat
+sudo systemctl status baiyue-logistics-chat --no-pager
+curl -I http://127.0.0.1:5000/
+```
+
+本机检查应返回 HTTP 200。服务使用独立系统用户、单进程 8 线程并仅监听 `127.0.0.1:5000`，不走 `am.py` 的 Flask 开发服务器回退。单进程保留当前应用的内存输入状态和限流行为；暂不配置多进程或多个副本。
+
+systemd 自动创建并授权以下目录，重启与更新源码不会替换其中的数据：
+
+| 内容 | 服务器路径 |
+|---|---|
+| SQLite | `/var/lib/baiyue-logistics-chat/history.db` |
+| 上传附件 | `/var/lib/baiyue-logistics-chat/uploads/` |
+| 启动备份 | `/var/lib/baiyue-logistics-chat/backups/` |
+| 应用日志 | `/var/log/baiyue-logistics-chat/app.log` |
+| 密钥配置 | `/opt/baiyue-logistics-chat/.env` |
+
+首次启动创建八张业务表，不插入演示数据、默认客服账号或密码。已有表和记录保持兼容。应用当前仍会在启动时清理超过 7 天的上传文件，并执行启动备份；启动备份不能替代定时备份。
+
+## 5. 申请 HTTPS 证书
+
+先安装只提供证书验证路径的 HTTP 配置，此时不会转发到应用：
+
+```bash
+sudo install -d -m 755 /var/www/letsencrypt
+sudo install -m 644 deploy/nginx-bootstrap.conf.example /etc/nginx/sites-available/baiyue-logistics-chat
+sudoedit /etc/nginx/sites-available/baiyue-logistics-chat
+sudo ln -s /etc/nginx/sites-available/baiyue-logistics-chat /etc/nginx/sites-enabled/baiyue-logistics-chat
+sudo nginx -t
+sudo systemctl enable --now nginx
+sudo systemctl reload nginx
+sudo certbot certonly --webroot -w /var/www/letsencrypt --cert-name chat.example.com -d chat.example.com
+```
+
+编辑配置时替换域名，申请证书时也替换两处域名；按 Certbot 提示填写邮箱和确认条款。若申请失败，先核对 DNS 和外网 80 端口，保留引导配置排查，暂不安装下一步需要证书的 TLS 配置。
+
+## 6. 设置访问密码并开放 HTTPS 验收
+
+创建验收账号 `preview`，密码由命令交互输入，不写入项目配置。`-c` 仅首次创建密码文件时使用；以后修改密码应去掉 `-c`。
+
+```bash
+sudo htpasswd -cB /etc/nginx/.baiyue-preview.htpasswd preview
+sudo chown root:www-data /etc/nginx/.baiyue-preview.htpasswd
+sudo chmod 640 /etc/nginx/.baiyue-preview.htpasswd
+sudo install -m 644 deploy/nginx.conf.example /etc/nginx/sites-available/baiyue-logistics-chat
+sudoedit /etc/nginx/sites-available/baiyue-logistics-chat
+sudo nginx -t
+sudo systemctl reload nginx
+```
+
+替换 TLS 配置中所有域名及证书路径；`nginx -t` 失败时先修正，不要继续 reload。模板的访问密码覆盖页面、附件、静态资源和全部 API，后端 5000 端口继续只对本机开放。不能只在导航层隐藏后台页面。
+
+Nginx 已关闭代理响应缓冲及压缩，并将等待上游数据的超时设为 300 秒，供 AI SSE 分段输出；上传入口允许 12 MiB 请求体以容纳应用 10 MiB 文件上限外的表单开销。
+
+## 7. 验收和证书续期
+
+```bash
+curl -I https://chat.example.com/
+curl -I https://chat.example.com/api/export_chat
+curl -u preview -I https://chat.example.com/
+```
+
+前两条应返回 401，证明页面和数据接口都受保护；第三条交互输入访问密码后应返回 200。浏览器也会先弹出访问密码：
+
+- 客户页：`https://chat.example.com/`，发送消息检查 DS 实际回复及流式显示。
+- 验收工作台：`https://chat.example.com/admin/dashboard`，从客户页申请人工，再检查接待和双向消息。
+- 当前未预置应用内客服登录账号；Nginx 的 `preview` 是整站验收密码，不是 `/admin` 页里的客服账号。
+
+安装证书续期后的 Nginx 重载钩子，并检查续期定时器：
+
+```bash
+sudo install -d -m 755 /etc/letsencrypt/renewal-hooks/deploy
+sudo install -m 755 deploy/reload-nginx.sh /etc/letsencrypt/renewal-hooks/deploy/baiyue-reload-nginx
+sudo systemctl enable --now certbot.timer
+sudo certbot renew --dry-run --run-deploy-hooks
+```
+
+最终配置保留 HTTP 的 `/.well-known/acme-challenge/` 路径，供 webroot 续期使用；其他 HTTP 请求跳转到 HTTPS。不要删除验证路径或只对自己的 IP 开放证书验证端口，否则后续续期会失败。
+
+## 维护、更新和问题定位
+
+```bash
+sudo journalctl -u baiyue-logistics-chat -n 100 --no-pager
+sudo tail -n 100 /var/log/baiyue-logistics-chat/app.log
+sudo systemctl restart baiyue-logistics-chat
+sudo nginx -t
+```
+
+- **502**：先查应用状态、journal 日志、依赖安装及 5000 端口本机检查。
+- **一直弹访问密码**：检查 Nginx 密码文件和 `www-data` 读权限；不要用应用内客服密码替代验收密码。
+- **AI 无回复**：确认服务器 `.env` 已填写并重启，检查服务器能否访问 DS；本机验收成功不代表服务器网络已验证。
+- **输出集中到最后**：检查实际生效的 Nginx 配置和 CDN 是否重新启用了缓冲。
+- **429**：目前反向代理后的请求共享应用默认限流桶，适合单人验收；多人开放前需正确配置可信代理和业务限流。
+
+更新前停止应用并备份 `/var/lib/baiyue-logistics-chat/`，另行保护 `.env`。源码更新只替换项目文件，不复制本机数据库或 `work/`，不覆盖服务器 `.env`；按需重新安装依赖后重启。若修改 systemd 单元，重新安装单元并执行 `daemon-reload`；若修改 Nginx，先检查再 reload。回退源码时仍保留数据副本，本项目尚无数据库降级迁移工具。
+
+本地已通过应用工厂和全新数据库回归；目标服务器的 `systemd-analyze verify`、`nginx -t`、DNS、证书签发及真实 DS 请求仍需在部署时验证。
+
+## 参考
+
+工厂调用与监听参数依据 [Waitress 官方文档](https://docs.pylonsproject.org/projects/waitress/en/stable/runner.html)。流式转发配置依据 [Nginx 代理模块](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering)，全站密码依据 [Nginx Basic Auth 模块](https://nginx.org/en/docs/http/ngx_http_auth_basic_module.html)。证书和续期使用 [Certbot webroot](https://eff-certbot.readthedocs.io/en/stable/using.html#webroot)；服务目录与只读保护依据 [systemd.exec](https://www.freedesktop.org/software/systemd/man/latest/systemd.exec.html)。
@@ -0,0 +1,96 @@
+# Jenkins 灰度部署
+
+现有灰度环境使用 `Jenkinsfile`、`Dockerfile` 和 `deploy/` 发布独立物流聊天服务。流水线构建并测试镜像，通过严格校验主机指纹的 SSH 发送到专用 Docker Compose 服务，Nginx 提供 HTTPS 和全站访问密码。
+
+应用使用单个 Waitress 进程、8 个线程和 UID 10001，宿主机端口仅绑定回环地址。运行密钥、聊天数据、附件和证书不进入镜像。后台鉴权与会话隔离仍不完整，灰度验收须保留全站密码；此流程不代表已具备面向多个客户开放的权限体系。
+
+## Jenkins 任务
+
+任务名为 `baiyue-logistics-chat-gray`。定义选择 Pipeline script from SCM，本项目 Git 地址为仓库，分支字段为 `${SOURCE_REF}`，脚本路径为 `Jenkinsfile`。公开仓库可匿名读取；转为私有后配置只读 SCM 凭据。
+
+`java-builder` 标签代理须有 Docker、Bash、Python 3、Node.js 18+、OpenSSL、SSH，并能下载所选 Python 基础镜像和 PyPI 依赖。标签不表示固定物理节点。
+
+以下参数由私有灰度配置提供，实际地址和凭据值不写入源码：
+
+| 参数 | 含义 |
+|---|---|
+| `ENVIRONMENT` | 单选 `gray`，流水线拒绝其他值 |
+| `SOURCE_REF` | 本次发布的不可变标签或提交，也可明确选择开发分支 |
+| `PYTHON_BASE_IMAGE` | 已验证的官方 Python 3.12 基础镜像 |
+| `PUBLIC_ORIGIN` | 独立 HTTPS 域名，不带子路径 |
+| `HOST_PORT` | 已确认空闲的宿主机回环端口，如 `29013` |
+| `GRAY_DEPLOY_DIR` | 专用目录，末级必须为 `gray-logistics-chat` |
+| `GRAY_PROXY_CONF_DIR` | 宿主机 Nginx 实际加载的站点目录 |
+| `GRAY_TLS_CERT_FILE` / `GRAY_TLS_KEY_FILE` | 本服务独立证书和私钥路径 |
+| `SSH_CREDENTIAL_ID` | SSH 用户与私钥凭据引用 |
+| `SSH_HOST_CREDENTIAL_ID` | SSH 目标的 Secret text 引用 |
+| `SSH_KNOWN_HOSTS_CREDENTIAL_ID` | 已核实的 known_hosts 文件引用 |
+| `DEEPSEEK_CREDENTIAL_ID` | 本服务模型密钥的 Secret text 引用 |
+| `PREVIEW_AUTH_CREDENTIAL_ID` | 专用验收用户名和密码引用 |
+
+运行密钥和验收账号保存在私有灰度配置与 Jenkins 凭据库，供后续发布持续复用；轮换时同步更新。不要将密钥放在构建参数、Git URL、镜像 ARG、日志或示例文件中。
+
+## 发布步骤
+
+1. 完成检查并提交代码，创建 `gray-chat-YYYYMMDD-<commit12>` 一类不可变发布标签。不要重写已有标签或强推覆盖远端分支；分支有其他更新时先明确发布基线。
+2. 推送标签，在任务 `SOURCE_REF` 选择该标签。Jenkins 按此引用加载流水线并检出代码，镜像记录完整提交 SHA。
+3. 流水线检查 Bash 语法，运行 Node 回归，再构建 `test` 目标执行 Python 回归；通过后构建 `production` 应用镜像及 `certbot` 运维镜像。
+4. 构建完成后才绑定运行凭据。发布脚本校验路径、域名、源提交和镜像 ID，生成私有配置并发送镜像及发布文件。
+5. 首次签发域名证书，等待应用健康，再安装本服务的 Nginx 配置。已有业务的容器和站点配置不参与本次发布。
+6. Jenkins 使用验收账号验证公网 HTTPS `/healthz`；之后在浏览器验证 AI 流式回复、上传、转人工和工作台。
+
+应用镜像必须选择 `production` 构建目标；`certbot` 仅用于证书运维。每个构建生成独立镜像标签，接收主机再次核验镜像 ID，不依赖 `latest`。
+
+## 数据与失败回退
+
+`GRAY_DEPLOY_DIR` 如 `/data/services/gray-logistics-chat`，包含：
+
+| 路径 | 内容 |
+|---|---|
+| `.project` | 服务所有权标记，拒绝复用未知目录 |
+| `data/` | SQLite、附件和备份，跨发布保留 |
+| `logs/` | 应用日志 |
+| `releases/<commit12>-b<build>/` | Compose、镜像坐标、私有运行配置和站点候选 |
+| `current-release` | 已通过应用及入口检查的发布目录 |
+| `tls/` | 独立 ACME 账号、证书、日志和续期脚本 |
+
+模型密钥写入权限为 600 的 `runtime.env`，由 Compose 注入进程。验收密码只在 Jenkins 生成 Nginx 哈希，服务器保存哈希文件。
+
+更新前执行 SQLite 在线备份。应用启动或 Nginx 检查失败时，仅恢复本服务之前的 Compose 和站点配置，保留数据；不自动用旧库覆盖新记录。失败发布目录保留供定位，数据库降级及删除数据需另行处理。
+
+新环境自动创建八张业务表，不创建默认客服账号或演示数据。验收用全站密码直接进入工作台；Nginx 验收账号不是应用内客服账号。
+
+## HTTPS 及续期
+
+域名须解析到已核实的灰度入口，公网 80、443 端口可达。其他域名的证书不能直接用于新域名。
+
+独立 Certbot 镜像通过 HTTP-01 webroot 签发证书；首次只新增本服务的 HTTP 验证站点，业务接口尚不公开。验证目录为 `/var/lib/baiyue-logistics-chat-acme`，最终配置持续保留该 HTTP 路径。
+
+证书参数须指向：
+
+```text
+<GRAY_DEPLOY_DIR>/tls/config/live/<域名>/fullchain.pem
+<GRAY_DEPLOY_DIR>/tls/config/live/<域名>/privkey.pem
+```
+
+ACME 账号和私钥仅保存在服务器私有目录，当前使用无邮箱账号。专用 `baiyue-logistics-chat-tls-renew.timer` 每日检查本服务证书，内容变化后检查并重载 Nginx，不接管其他证书任务。
+
+## 排查
+
+先从 Jenkins 构建记录核对阶段及源 SHA。服务器检查：
+
+```bash
+docker ps --filter name=baiyue-logistics-chat-gray
+docker logs --tail 100 baiyue-logistics-chat-gray
+systemctl status baiyue-logistics-chat-tls-renew.timer --no-pager
+nginx -t
+```
+
+- 构建失败：核对镜像和 PyPI 网络，不跳过测试发布。
+- SSH 失败：核对受管凭据和 known_hosts，不禁用指纹检查。
+- 证书失败：核对 DNS 和 HTTP 验证路径，保留本服务的验证站点与私有 ACME 状态。
+- 容器不健康：检查独立目录的 UID 10001 权限、日志和 `/healthz`；健康检查不计入业务限流。
+- 入口 401：未登录时为预期，使用专用验收密码后应返回 200。
+- 流式显示延迟：检查实际 Nginx 或 CDN 是否重新启用了响应缓冲。
+
+独立主机安装另见 [Linux 手动参考](deployment-linux.md)。凭据与 API 依据 [Jenkins 官方文档](https://www.jenkins.io/doc/pipeline/steps/credentials-binding/) 和 [Remote API](https://www.jenkins.io/doc/book/using/remote-access-api/)，证书验证与续期依据 [Certbot 文档](https://eff-certbot.readthedocs.io/en/stable/using.html#webroot)。