feat: complete production workflow migration
This commit is contained in:
+132
-27
@@ -1,39 +1,144 @@
|
||||
# 部署手册
|
||||
# GYXX Flow 部署
|
||||
|
||||
## 推荐部署方式
|
||||
|
||||
生产环境推荐使用 Linux 主机：
|
||||
|
||||
- PostgreSQL 使用云端服务，完整 DSN 由服务器密钥环境注入。
|
||||
- Python 调度器、本机 Hermes 和需要登录状态的浏览器运行在宿主机。
|
||||
- systemd 只守护一个 Python 调度进程，所有业务时间规则仍来自 `config/schedules.json`。
|
||||
- 运行数据使用 `/var/lib/gyxx-flow`，不得把生产 `GYXX_DATA_ROOT` 指向源码目录中的 `var/`。
|
||||
|
||||
这种方式能够直接访问两个本机 Hermes 角色和浏览器 CDP，也不会把业务定时规则复制到 systemd timer、cron 或 Windows Task Scheduler。
|
||||
|
||||
## 环境要求
|
||||
|
||||
- Windows 10/11 或 Windows Server，系统时区 `China Standard Time`
|
||||
- Python 3.12、`uv`、Windows Task Scheduler
|
||||
- 凭据由环境变量或外部密钥系统提供，不写入源码或清单
|
||||
- Python 3.12 和 `uv`
|
||||
- 可访问的 PostgreSQL 13+ 云端实例及运行时注入的 `GYXX_POSTGRES_DSN`
|
||||
- 本机 Hermes `data-analyzer` 与 `data-collector`
|
||||
- Chrome/Playwright，以及个别业务入口仍需要的 PowerShell 运行条件
|
||||
- 可访问现有飞书身份的专用系统用户
|
||||
|
||||
## 安装
|
||||
创建生产目录和服务账户：
|
||||
|
||||
```powershell
|
||||
cd D:\gyxx-flow
|
||||
uv sync --python 3.12 --extra test
|
||||
$env:GYXX_DATA_ROOT = 'D:\gyxx-flow\var'
|
||||
.\.venv\Scripts\python.exe -m gyxx_flow doctor --json
|
||||
.\.venv\Scripts\python.exe -m pytest
|
||||
```bash
|
||||
sudo useradd --system --create-home --shell /usr/sbin/nologin gyxx-flow
|
||||
sudo install -d -o gyxx-flow -g gyxx-flow /opt/gyxx-flow
|
||||
sudo install -d -o gyxx-flow -g gyxx-flow /var/lib/gyxx-flow
|
||||
sudo install -d -o root -g gyxx-flow -m 0750 /etc/gyxx-flow
|
||||
```
|
||||
|
||||
不再配置任何 `GYXX_LEGACY_*_ROOT`。运行代码和资源随 `gyxx_flow` 包部署，
|
||||
四个旧项目可以不挂载。商品模块需要独立配置时，可设置 `GYXX_PRODUCT_CONFIG`；
|
||||
该变量只指向新部署的配置文件。
|
||||
将代码发布到 `/opt/gyxx-flow` 后安装锁定依赖：
|
||||
|
||||
## 生成候选调度计划
|
||||
|
||||
```powershell
|
||||
.\.venv\Scripts\python.exe -m gyxx_flow schedule plan `
|
||||
--output D:\gyxx-flow\var\schedule-plan\candidate `
|
||||
--start-date 2026-07-27 `
|
||||
--python-executable D:\gyxx-flow\.venv\Scripts\python.exe
|
||||
```bash
|
||||
cd /opt/gyxx-flow
|
||||
sudo -u gyxx-flow uv sync --python 3.12 --no-group dev --frozen
|
||||
```
|
||||
|
||||
输出包含 21 个 XML、`install.ps1`、`plan.json` 和 `drift.json`。生成计划不会
|
||||
注册任务。只有生产门禁通过并获得明确授权后，才能人工审阅并逐个使用
|
||||
`install.ps1 -Apply -WorkflowId <id>`；安装器强制一次只处理一个任务。
|
||||
凭据放入 `/etc/gyxx-flow/gyxx-flow.env`，权限设为 `0640`。该文件不提交到 Git，至少按实际环境注入数据库密码、飞书身份和可选 Hermes 密钥。
|
||||
|
||||
## 可迁移部署
|
||||
控制台和调度器都支持可重复的 `--env-file`，只加载显式列出的文件。systemd 的
|
||||
`EnvironmentFile=` 或当前进程环境优先于文件中的同名值，避免本地文件意外覆盖密钥系统
|
||||
注入值。
|
||||
|
||||
复制项目或安装 wheel 后，只需重新设置 `GYXX_DATA_ROOT` 和凭据。禁止在生产任务
|
||||
命令中出现旧项目盘符、用户目录解释器或旧项目工作目录。
|
||||
## PostgreSQL
|
||||
|
||||
从受限环境文件加载云端数据库连接：
|
||||
|
||||
```bash
|
||||
cd /opt/gyxx-flow
|
||||
set -a
|
||||
source /etc/gyxx-flow/gyxx-flow.env
|
||||
set +a
|
||||
uv run gyxx doctor --json
|
||||
```
|
||||
|
||||
生产环境必须设置 `GYXX_POSTGRES_DSN`，且 DSN 主机必须是非回环地址。项目不会把云端地址、用户名或密码写入源码；`deploy/postgres.compose.yml` 仅保留为开发和恢复场景的可选本地工具，不是当前生产数据库入口。
|
||||
|
||||
## 本机 Hermes
|
||||
|
||||
启动并验证两个独立角色：
|
||||
|
||||
```text
|
||||
data-analyzer: API base http://127.0.0.1:8642/v1
|
||||
data-collector: API base http://127.0.0.1:8643/v1
|
||||
```
|
||||
|
||||
`28790/28791` 不作为工作流业务端点。
|
||||
|
||||
运行时配置必须保持回环地址。Hermes 不可用时，纯采集、文件处理和数据库同步仍可运行；依赖 Hermes 分析或通知的工作流应保持停用或手工执行，不得静默改用远程 AI。
|
||||
|
||||
## 上线前验证
|
||||
|
||||
使用生产服务账户运行：
|
||||
|
||||
```bash
|
||||
cd /opt/gyxx-flow
|
||||
sudo -u gyxx-flow env GYXX_DATA_ROOT=/var/lib/gyxx-flow uv run gyxx doctor --json
|
||||
sudo -u gyxx-flow env GYXX_DATA_ROOT=/var/lib/gyxx-flow uv run gyxx schedule run --dry-run --once
|
||||
sudo -u gyxx-flow env GYXX_DATA_ROOT=/var/lib/gyxx-flow uv run gyxx list --json
|
||||
```
|
||||
|
||||
开发或发布流水线另外执行：
|
||||
|
||||
```bash
|
||||
uv run ruff check src tests
|
||||
uv run pytest
|
||||
uv build
|
||||
uv run gyxx acceptance status --json
|
||||
```
|
||||
|
||||
## systemd 调度服务
|
||||
|
||||
项目提供 `deploy/gyxx-flow.service`。安装并启动：
|
||||
|
||||
```bash
|
||||
sudo cp /opt/gyxx-flow/deploy/gyxx-flow.service /etc/systemd/system/gyxx-flow.service
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable --now gyxx-flow.service
|
||||
sudo systemctl status gyxx-flow.service
|
||||
```
|
||||
|
||||
unit 的唯一业务入口是：
|
||||
|
||||
```text
|
||||
/opt/gyxx-flow/.venv/bin/python -m gyxx_flow schedule run
|
||||
```
|
||||
|
||||
若 unit 不使用 systemd `EnvironmentFile=`，入口必须显式追加：
|
||||
|
||||
```text
|
||||
--env-file /etc/gyxx-flow/gyxx-flow.env
|
||||
```
|
||||
|
||||
调度状态写入 `/var/lib/gyxx-flow/state/scheduler`，日志和子进程产物写入同一外置数据根。修改 `config/schedules.json` 后先运行一次 dry-run，再重启服务：
|
||||
|
||||
```bash
|
||||
sudo -u gyxx-flow env GYXX_DATA_ROOT=/var/lib/gyxx-flow \
|
||||
/opt/gyxx-flow/.venv/bin/python -m gyxx_flow schedule run --dry-run --once
|
||||
sudo systemctl restart gyxx-flow.service
|
||||
```
|
||||
|
||||
不要为单个工作流创建 systemd timer 或 cron 条目，也不得同时运行两个调度器实例。
|
||||
|
||||
## 发布更新
|
||||
|
||||
```bash
|
||||
sudo systemctl stop gyxx-flow.service
|
||||
cd /opt/gyxx-flow
|
||||
# 切换到已验收版本后：
|
||||
sudo -u gyxx-flow uv sync --python 3.12 --no-group dev --frozen
|
||||
sudo -u gyxx-flow env GYXX_DATA_ROOT=/var/lib/gyxx-flow uv run gyxx doctor --json
|
||||
sudo -u gyxx-flow env GYXX_DATA_ROOT=/var/lib/gyxx-flow uv run gyxx schedule run --dry-run --once
|
||||
sudo systemctl start gyxx-flow.service
|
||||
```
|
||||
|
||||
代码发布和回滚都不得覆盖 `/var/lib/gyxx-flow`。
|
||||
|
||||
## Docker 边界
|
||||
|
||||
当前 Compose 只负责 PostgreSQL。完整应用若进入容器，容器内 `127.0.0.1` 不再指向宿主机的两个 Hermes 和浏览器 CDP；同时部分工作流仍可能依赖可见桌面登录或 PowerShell。因此在完成网络、安全、浏览器 Profile 持久化和目标工作流验收前，不将完整生产应用声明为纯容器部署。
|
||||
|
||||
## Windows 兼容入口
|
||||
|
||||
`deploy/windows-service/` 暂时保留为 legacy NSSM 兼容入口。NSSM 只守护同一个 `gyxx schedule run` 进程，不注册 Windows Task Scheduler，也不保存业务时间规则。新服务器部署以 Linux systemd 为准。
|
||||
|
||||
Reference in New Issue
Block a user