7.2 KiB
GYXX Flow 运维手册
日常检查
uv run gyxx doctor --json
uv run gyxx schedule status
uv run gyxx list
Linux 服务同时检查：
systemctl status gyxx-flow.service
journalctl -u gyxx-flow.service --since today
工作流失败时，使用 workflow_id、业务日期和 run_id 对照 <GYXX_DATA_ROOT>/logs、运行记录、节点产物和副作用账本。
手工执行
uv run gyxx run <workflow_id> --date 2026-08-01
uv run gyxx run <workflow_id> --date 2026-08-01 --execute
uv run gyxx scripts list --json
uv run gyxx scripts run <command_id> --date 2026-08-01
uv run gyxx scripts run <command_id> --date 2026-08-01 --execute
gyxx run 只接受 22 个调度工作流；补采和维护操作使用 gyxx scripts run。两类入口都默认 dry-run，只有业务日期、凭据、浏览器登录态、PostgreSQL 和对应 Hermes 角色全部确认后才使用 --execute。
| 手动场景 | 命令 ID | 日期行为 |
|---|---|---|
| 内容映射重建 | content.mapping.rebuild |
业务日期只用于运行审计 |
| 内容失败任务重试 | content.failed.retry |
业务日期只用于运行审计 |
| 内容日报重跑 | gyxx backfill content.metrics.daily |
使用 --from/--to 指定日期范围 |
| 京东自营品牌单日回采 | shop.jd_self_operated.collect_brand |
--date 自动成为起止日期 |
| 商品历史补采 | product.backfill.run |
--date 自动成为 --from/--to |
| 商品评价补采 | product.review.orchestrate |
--date 自动成为目标日期 |
| 采购单更新 | supply.workflow.run |
自动选择 mcp-run purchase-order-update |
命令的额外脚本参数使用可重复的 --arg=<值> 传入。supply.workflow.run --execute 会进入真实 ERP 修改链路，必须在任务文件、目标范围和回滚条件全部复核后执行。
主图周工作流
主图调度的唯一工作流 ID 是 product.main_image.weekly，每周日 08:30 启动。图同时运行 JD、TM 两个无依赖分支；一个平台失败不会取消、跳过或回滚另一个平台的采集、PG upsert 和飞书插入。两个分支全部结束后再汇总工作流状态：任一平台失败时整体状态为失败，并在错误摘要中标明具体平台和错误，另一平台已经成功的结果继续保留。
两个平台默认都在采集后执行飞书主图表插入和本地 PostgreSQL main_image_creatives upsert。执行前必须同时确认两套浏览器登录态、飞书身份和本地数据库；排障时分别检查 jd、tmall 节点以及对应插入脚本日志，不能只以采集文件存在判断双 sink 已完成。
调度操作
uv run gyxx schedule run --dry-run --once
uv run gyxx schedule status
sudo systemctl restart gyxx-flow.service
调度服务也只加载显式指定的受控环境文件：
uv run gyxx schedule run --env-file /etc/gyxx-flow/gyxx-flow.env
业务时间只在 config/schedules.json 中维护。systemd 负责进程守护，Python scheduler 负责全部业务定时；不要重复注册 cron、systemd timer 或 Windows 任务计划。
需要停用单个工作流时，优先修改该工作流的调度启用状态，先 dry-run，再重启服务。其他模块继续运行。
数据和浏览器状态
生产 GYXX_DATA_ROOT 必须位于源码目录之外，Linux 推荐 /var/lib/gyxx-flow：
data/raw/<module>：原始采集结果，不按临时文件清理。data/normalized、data/curated：清洗、标准化和聚合数据。data/exports：Markdown、Excel 等交付文件。state/browser/<module>/<script>：独立 Cookie、Profile 和 storage state。state/scheduler、state/locks、运行账本：调度和幂等状态。tmp：仅存放可重建临时文件。
项目不会自动搬动或删除已有 var/。迁移数据根时应停止调度器，完整备份和复制原目录，修改环境变量后依次运行 doctor、dry-run 和一次指定日期的对账执行。
清理和保留
可以在确认没有任务运行后清理缓存、tmp、dry-run 目录和可重建构建产物。以下内容不得作为普通缓存删除：
data/raw原始数据；state/scheduler和资源锁；- EffectLedger、运行 journal 和浏览器状态；
- 尚未核对或尚未导入数据库的 Excel、JSON、Markdown 导出。
旧 Windows 任务计划 XML 只属于历史部署证据，确认 Python scheduler 已接管且完成备份后再归档。
故障处理
- 按
workflow_id、业务日期和run_id定位失败节点。 - 检查本机 PostgreSQL、对应 Hermes 角色、飞书身份和脚本专属 CDP 端口。
- 检查 Cookie/storage state 是否存在且未失效。
- 修复后按同一业务日期重跑，依靠唯一键和 EffectLedger 防止重复写入。
- 仍失败时停用该工作流，不停止其他模块。
副作用账本对账
正式节点失败后，EffectLedger 会保留 ambiguous 回执，避免不确定状态下重复写库或重复
发送飞书。不要删除或手工修改回执文件。只有先从 PostgreSQL、飞书消息回执和目标文档
确认该节点是否已产生外部效果，才可执行审计式对账：
uv run gyxx effects reconcile <workflow_id> \
--date 2026-08-04 \
--step <step_id> \
--expected-run-id <原失败run_id> \
--action retry \
--operator <操作人> \
--reason <重试原因> \
--evidence <已核对的证据> \
--execute
retry 仅在证明确实没有完成外部写入时允许同日重试；若证据表明外部写入已经完成，使用
--action applied。命令只接受当前仍为 ambiguous 且 run_id 精确匹配的回执，并保留
操作人、原因、证据和时间，不能用于绕过正在执行的节点。
回滚
代码回滚时先停止 gyxx-flow.service，切换到上一个已验收版本，重新安装锁定依赖并执行 doctor 和调度 dry-run；确认后再启动服务。不得用代码回滚覆盖 GYXX_DATA_ROOT。
数据撤销必须针对明确表、业务键和 run_id，先备份 PostgreSQL，再执行经过复核的 SQL。不得删除整个数据库、数据卷或数据根。
浏览器状态异常时，只备份并处理目标脚本的 state/browser/<module>/<script>，不要清理其他脚本状态。调度状态异常时先停止唯一调度进程并备份 state/scheduler，不要同时启动第二实例。
业务源码同步
外部业务源码目录只用于发现更新，GYXX Flow 运行时不导入或挂载这些目录。只读检查：
uv run gyxx sources status `
--source-root content_marketing=<内容源码目录> `
--source-root product_commerce=<商品源码目录> `
--source-root shop_intelligence=<店铺源码目录> `
--source-root supply_chain=<供应链源码目录> `
--json
只有未转换、无冲突的 source_changed 可以显式执行：
uv run gyxx sources apply ... --execute --json
经过统一路径、数据库、Hermes、飞书或浏览器适配的文件必须人工合并并运行回归测试。新增可执行脚本还需登记工作流、调度和独立 CDP 绑定。同步完成后执行测试、doctor、acceptance 和 source status；真实采集不在源码同步过程中自动触发。