v1.3 Gitea Webhook实时构建

背景：需求迭代/2026-04/v1.3-Gitea-Webhook实时构建.md

---

1. 技术选型

方案	延迟	说明
仅缩短 cron	仍与 Obsidian 推送周期叠加，分钟级	不推荐作为唯一手段
Gitea Webhook + 宿主机钩子	通常秒级	push 即触发，与客户端定时解耦
cron 低频	兜底	防 Webhook 偶发失败

接收器选用 adnanh/webhook：HTTP → 执行 /opt/rebuild-notes.sh。

---

2. 架构

Gitea（容器） --HTTP Webhook--> 宿主机 :9000（webhook） --> /opt/rebuild-notes.sh
                                                      --> git pull + mkdocs build
Nginx root --> /opt/mkdocs-site（或你的 site_dir）

Gitea 在容器内访问宿主机 不能用 127.0.0.1（指向容器自身）。推荐：

• --add-host=host.docker.internal:host-gateway 后 URL 使用 http://host.docker.internal:9000/...
• 或桥接网关 IP（如 172.17.0.1），以 docker inspect gitea 为准。

---

3. 模块

组件	说明
rebuild-notes.sh	cd 工作副本、git pull、export NO_MKDOCS_2_WARNING=1、mkdocs build
hooks.json	id: rebuild-mkdocs，execute-command 指向上款脚本；URL ?token= 校验
systemd webhook-mkdocs	拉起 webhook，需 Environment=HOME=/root（或运行用户 HOME）
Gitea app.ini	[webhook] ALLOWED_HOST_LIST = private,loopback,external

---

4. 方案细节

4.1 安装 webhook 二进制

VER=2.8.1
ARCH=linux-amd64
curl -fsSL -o /tmp/webhook.tgz \
  "https://github.com/adnanh/webhook/releases/download/${VER}/webhook-${ARCH}.tar.gz"
tar -xzf /tmp/webhook.tgz -C /tmp
install -m 755 "/tmp/webhook-${ARCH}/webhook" /usr/local/bin/webhook

GitHub 不可达时：本机下载后 scp 到服务器（同 搭建轻量个人知识库.md 镜像策略）。

4.2 /etc/webhook/hooks.json（示例）

mkdir -p /etc/webhook
openssl rand -hex 32 | tee /etc/webhook/secret.txt
chmod 600 /etc/webhook/secret.txt

将 YOUR_SECRET_FROM_FILE 换成 secret 内容：

[
  {
    "id": "rebuild-mkdocs",
    "execute-command": "/opt/rebuild-notes.sh",
    "command-working-directory": "/",
    "response-message": "ok",
    "trigger-rule": {
      "match": {
        "type": "value",
        "value": "YOUR_SECRET_FROM_FILE",
        "parameter": { "source": "url", "name": "token" }
      }
    }
  }
]

4.3 systemd

[Unit]
Description=Webhook receiver for MkDocs rebuild
After=network.target

[Service]
Environment=HOME=/root
Environment=NO_MKDOCS_2_WARNING=1
ExecStart=/usr/local/bin/webhook -hooks /etc/webhook/hooks.json -port 9000 -ip 0.0.0.0 -verbose
Restart=always

[Install]
WantedBy=multi-user.target

安全：安全组勿对公网开放 9000；仅容器网桥访问。监听策略见 维护手册细则.md。

systemctl daemon-reload
systemctl enable --now webhook-mkdocs
journalctl -u webhook-mkdocs -f

4.4 Gitea：app.ini

[webhook]
ALLOWED_HOST_LIST = private,loopback,external

docker restart gitea。

4.5 Gitea 后台 Webhook

• URL：http://host.docker.internal:9000/hooks/rebuild-mkdocs?token=<密钥>（或网关 IP 形式）。
• 触发：Push events；可按分支过滤。

4.6 本地试调

curl -sS "http://127.0.0.1:9000/hooks/rebuild-mkdocs?token=$(cat /etc/webhook/secret.txt)"

4.7 cron 兜底

0 * * * * /opt/rebuild-notes.sh >> /var/log/mkdocs-build.log 2>&1

4.8 典型故障

• Delivery 超时：是否误用容器内 127.0.0.1。
• 200 但站点未更新：HOME / safe.directory / pull 路径，见 问题 014、002。
• Material MkDocs 2.0 长告警：NO_MKDOCS_2_WARNING=1，见问题 015。

全文排错表：维护手册细则.md。