gyxx-flow/docs/deployment.md

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。

环境要求

• Python 3.12 和 uv
• 可访问的 PostgreSQL 13+ 云端实例及运行时注入的 GYXX_POSTGRES_DSN
• 本机 Hermes data-analyzer 与 data-collector
• Chrome 与 Scrapling 浏览器运行时，以及个别业务入口仍需要的 PowerShell 运行条件
• 可访问现有飞书身份的专用系统用户

创建生产目录和服务账户：

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

将代码发布到 /opt/gyxx-flow 后安装锁定依赖：

cd /opt/gyxx-flow
sudo -u gyxx-flow uv sync --python 3.12 --no-group dev --frozen
sudo -u gyxx-flow uv run scrapling install

业务采集代码只使用 Scrapling；其动态与隐身抓取器所需的底层浏览器由 Scrapling 安装和管理。具体边界与验证命令见 architecture.md。

凭据放入 /etc/gyxx-flow/gyxx-flow.env，权限设为 0640。该文件不提交到 Git，至少按实际环境注入数据库密码、飞书身份和可选 Hermes 密钥。

控制台和调度器都支持可重复的 --env-file，只加载显式列出的文件。systemd 的 EnvironmentFile= 或当前进程环境优先于文件中的同名值，避免本地文件意外覆盖密钥系统 注入值。

三平台电商费用日报部署边界

product.ecommerce_costs.daily 是包含天猫万相台、京东京准通和抖音千川分支的电商费用工作流；三个 平台下载节点并行，导入节点分别等待本平台下载完成。当前项目对其中天猫万相台这条 浏览器链路按 Windows Server + NSSM 验收；Linux 上的通用调度器说明不等于万相台浏览器流程 已经完成 Linux/无头浏览器验收。部署到 Windows Server 时使用项目内的 NSSM 服务包装器，业务 时间仍只由 config/schedules.json 管理，不创建 Windows Task Scheduler 条目。

该工作流需要由服务账户注入以下环境变量，真实值不要写入 Git、命令参数或文档：

GYXX_DATA_ROOT=D:\gyxx-flow-data
GYXX_POSTGRES_DSN=<云端 PostgreSQL DSN>
WANXIANG_ACCOUNT=<万相台账号>
WANXIANG_PASSWORD=<万相台密码>

未显式设置 WANXIANG_USER_DATA_DIR 时，登录态保存在 <GYXX_DATA_ROOT>\state\browser-profiles\wanxiang-ads。这个 Profile 是该脚本的独立登录态， 不要与其他淘宝/万相台脚本共用。使用 NSSM 的 AppEnvironmentExtra 或服务器密码管理器注入 凭据；不要把真实密码写进 PowerShell 脚本或 nssm 命令历史。

安装 Windows 常驻服务：

cd D:\gyxx-flow
uv sync --python 3.12 --group dev
.\deploy\windows-service\install.ps1 -ProjectRoot D:\gyxx-flow -DataRoot D:\gyxx-flow-data
# 按服务器密码管理器的方式为 gyxx-flow-scheduler 注入上述环境变量
nssm start gyxx-flow-scheduler

首次上线先在有头浏览器中建立登录态并导入一日数据；验证码或滑块必须在同一 Profile 中人工 完成：

$env:GYXX_DATA_ROOT = 'D:\gyxx-flow-data'
$env:WANXIANG_ACCOUNT = '<从密码管理器读取>'
$env:WANXIANG_PASSWORD = '<从密码管理器读取>'
uv run gyxx doctor --json
uv run gyxx scripts run product.tmall_wanxiang_ads.collect --date 2026-08-17 --execute
uv run gyxx scripts run product.import.tmall_ads --date 2026-08-17 --execute

确认手工链路成功后，再让唯一的 gyxx schedule run 常驻服务接管；不要为 19:30 另建系统定时 任务。完整的服务重启和 dry-run 流程见本文件的“systemd 调度服务”章节以及 runbook.md 的万相台小节。

PostgreSQL

从受限环境文件加载云端数据库连接：

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

启动并验证两个独立角色：

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。飞书消息投递本身统一依赖运行服务账户的 hermes-analyzer lark-cli user 授权。

例外：content.summary.weekly / content.summary.monthly 的内容报告、product.style_analysis.interval 的款式周期分析，以及 product.video_upload / product.jd_video_upload 的视频标题与视觉颜色识别，均配置为显式直连 MiniMax。内容报告使用 CONTENT_ANALYSIS_LLM_BASE_URL、CONTENT_ANALYSIS_LLM_MODEL 和 CONTENT_ANALYSIS_LLM_API_KEY；商品/视频链路使用 STYLE_ANALYSIS_LLM_*（视频链路也支持 GYXX_DIRECT_LLM_* 覆盖）。这些链路不读取 Hermes 分析端口，但仍保留本地结果校验、断点、EffectLedger、飞书和 PostgreSQL 写入链路。

上线前验证

使用生产服务账户运行：

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

开发或发布流水线另外执行：

uv run ruff check src tests
uv run pytest
uv build
uv run gyxx acceptance status --json

systemd 调度服务

项目提供 deploy/gyxx-flow.service。安装并启动：

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 的唯一业务入口是：

/opt/gyxx-flow/.venv/bin/python -m gyxx_flow schedule run

若 unit 不使用 systemd EnvironmentFile=，入口必须显式追加：

--env-file /etc/gyxx-flow/gyxx-flow.env

调度状态写入 /var/lib/gyxx-flow/state/scheduler，日志和子进程产物写入同一外置数据根。修改 config/schedules.json 后先运行一次 dry-run，再重启服务：

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 条目，也不得同时运行两个调度器实例。

发布更新

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 为准。