75 lines
3.2 KiB
Markdown
75 lines
3.2 KiB
Markdown
# 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 或环境变量写进回执。
|