bingshuo/fifth-domain
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
fifth-domain/server-tools/deployment-receiver
History

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