fifth-domain/server-tools/fifth-domain-sync-agent/README.md

第五域自动同步 Agent

这是第 5 域的第一个常驻自动 Agent：它只接收 Forgejo 的已签名 main 推送，将新提交快进同步到受控工作副本，复跑导航记忆校验，并留下脱敏回执。

它不是“任意命令 Agent”，也不是生产部署器：没有来自 webhook 的命令字段；不读取或执行仓库内任意脚本；不因普通 Git push 执行服务重启、迁移或生产发布。

职责

Forgejo 已签名 push
  → 验证仓库、main 分支、提交 SHA 与 HMAC
  → 拒绝脏工作副本与非快进变更
  → fetch 后确认 fetched SHA = webhook after
  → 仅 fast-forward 同步
  → 检查导航记忆守卫
  → /var/lib/.../receipts 写入回执

部署边界

1. 在 /etc/guanghu/fifth-domain-sync-agent.json 按 config.example.json 配置，不提交真实配置。
2. 在 /etc/guanghu/fifth-domain-sync-agent.env 设置仅服务器持有的 FORGEJO_WEBHOOK_SECRET。
3. Forgejo webhook 指向 /forgejo/sync，使用相同 HMAC secret，并仅选择 push 事件。
4. 安装 systemd unit 前，安装器必须把 User=__RUN_AS_USER__ 替换为现有受控接收器的实际系统运行用户；不得假定旧架构目录名就是 Linux 用户。随后执行 daemon-reload、enable --now；健康检查为 /health。
5. 发布动作仍通过广播塔三阶段与受限 deployment receiver；此 Agent 不替代 GLSV 人格体发起的服务器操作流程。