# 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. 在目标服务器准备只读部署用户与目录：

   ```bash
   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. 复制配置：

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

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

   ```bash
   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 服务：

   ```bash
   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 或环境变量写进回执。