fifth-domain/server-tools/deployment-receiver/README.md

Guanghu Deployment Receiver v1.0

这是 fifth-domain 的服务器端 Forgejo Webhook 接收器。它把仓库提交转换为受控、可审计的服务器动作，但不接受提交中的任意 shell 命令。

第一版能力

• 校验 Forgejo/Gitea X-Forgejo-Signature / X-Gitea-Signature HMAC-SHA256。
• 只接受 bingshuo/fifth-domain 的 refs/heads/main 推送。
• 只读取 deployment/requests/*.json。
• 请求只能包含 request_id/module/action/approved/note，出现 cmd 等额外字段直接拒绝。
• 动作和模块必须在服务器本地 config.json 双重白名单中登记。
• 使用参数数组和 shell:false，禁止 shell 拼接。
• 单实例部署锁、执行超时、输出上限和本地 JSON 审计回执。
• 当前只登记 inspect-gatekeeper：读取线上 Gatekeeper 文件哈希、认证特征与 PM2 状态，不读取任何凭证，不修改服务。

交给服务器编程 AI 的部署步骤

1. 在目标服务器准备只读部署用户与目录：

   sudo useradd --system --home /var/lib/guanghu-deployment-receiver --shell /usr/sbin/nologin guanghu-deploy
   sudo mkdir -p /opt/zhuyuan /etc/guanghu-deployment-receiver /var/lib/guanghu-deployment-receiver/receipts
   sudo chown -R guanghu-deploy:guanghu-deploy /var/lib/guanghu-deployment-receiver
   

2. 将 fifth-domain 克隆或更新到 /opt/zhuyuan/fifth-domain。确保 guanghu-deploy 可以执行仓库的 git fetch，但不要给系统 root 权限。

3. 复制配置：

   sudo cp server-tools/deployment-receiver/config.example.json /etc/guanghu-deployment-receiver/config.json
   

4. 生成至少 32 字节的随机 Webhook 密钥，只放服务器：

   umask 077
   printf 'FORGEJO_WEBHOOK_SECRET=%s\n' "$(openssl rand -hex 32)" | sudo tee /etc/guanghu-deployment-receiver/secret.env >/dev/null
   

   不要把密钥提交到仓库。将同一个值配置到 Forgejo 仓库 Webhook 的 Secret。

5. 安装并启动 systemd 服务：

   sudo cp server-tools/deployment-receiver/guanghu-deployment-receiver.service /etc/systemd/system/
   sudo systemctl daemon-reload
   sudo systemctl enable --now guanghu-deployment-receiver
   curl -fsS http://127.0.0.1:3981/health
   

6. 使用 Nginx 暴露单一 HTTPS 路径，反代到 127.0.0.1:3981/forgejo/deploy。不要直接开放 3981 公网端口。

7. 在 Forgejo 的 bingshuo/fifth-domain 添加 Push Webhook：

   • URL：服务器编程 AI 配置的 HTTPS 地址，例如 https://deploy.example.com/forgejo/deploy
   • Secret：步骤 4 的随机值
   • Event：Push events
   • Branch filter：main

8. 部署完成后，重新提交或轻微更新：

   deployment/requests/WORK-PROBE-20260713-002.json

   接收器会在服务器本地写入：

   /var/lib/guanghu-deployment-receiver/receipts/WORK-PROBE-20260713-002-*.json

重要边界

• v1 不自动修改或重启 Gatekeeper。
• 新增真实部署动作时，服务器端 config.json 必须登记一个固定脚本路径；请求文件不能决定命令。
• 每个部署脚本必须自行实现备份、健康检查和失败回滚，再加入白名单。
• 不要把仓库 PAT、服务器 Token、邮箱、Webhook Secret 或环境变量写进回执。