daily_publish/WEBHOOK_SETUP.md

自动部署指南 - Gitea Webhook → NAS

架构

本地 push
  → Gitea (远程)
  → POST webhook: https://你的域名:41733/webhook
  → 前端容器 server.js 代理
  → Python webhook receiver (NAS host:5000)
  → git pull + npm install + npm run build + docker-compose up --build

需要上传到 NAS 的文件

将以下文件上传到 NAS 的 /vol1/1000/docker/publish/ 目录：

• webhook_receiver.py — Python Webhook 接收器（跑在 NAS 宿主机）
• webhook_receiver.service — Systemd 服务配置

NAS 端操作步骤

1. 上传文件

# 将 webhook_receiver.py 和 webhook_receiver.service 传到 NAS
scp webhook_receiver.py root@192.168.31.41:/vol1/1000/docker/publish/
scp webhook_receiver.service root@192.168.31.41:/etc/systemd/system/

2. 配置 Webhook Secret（可选但强烈建议）

编辑 webhook_receiver.service，把 YOUR_SECRET_HERE 换成你生成的随机字符串：

# 生成随机 secret
python3 -c "import secrets; print(secrets.token_hex(16))"

3. 安装并启动服务

# 重载 systemd
systemctl daemon-reload

# 启用开机自启
systemctl enable webhook_receiver

# 启动
systemctl start webhook_receiver

# 确认状态
systemctl status webhook_receiver

4. 确认 webhook receiver 监听

curl http://localhost:5000/health
# 应返回: OK

5. 防火墙放行 5000 端口（仅本地监听，可不开放）

webhook_receiver.py 监听 0.0.0.0:5000，仅接收来自 Docker 容器内（通过 host.docker.internal）的请求，不对外暴露，无需防火墙规则。

Gitea Webhook 配置

1. 打开 Gitea 仓库：https://www.1415243231.top:8418/panda/daily_publish
2. 进入 Settings → Webhooks → Add Webhook → Gitea
3. 填写：
   • Target URL: https://www.1415243231.top:41733/webhook
   • HTTP Method: POST
   • Secret: 你上面生成的 secret（需与 webhook_receiver.service 中的保持一致）
   • Trigger On: ✅ Push Events
   • Active: ✅
4. 点 Add Webhook

测试 Webhook

1. Gitea Webhook 列表页，点击刚创建的 webhook 右边 Test 按钮
2. 查看 Gitea 显示的 delivery 日志（200 OK 表示成功）
3. 同时在 NAS 上观察：

# 实时看 webhook receiver 日志
journalctl -u webhook_receiver -f

本地开发流程

1. 本地改代码 → git add . → git commit -m "xxx" → git push
2. Gitea 收到 push → 触发 webhook
3. NAS 自动：git pull → npm install → vite build → 重建前端镜像 → 重启容器
4. 全程无需手动操作

注意事项

Node.js 版本

NAS 宿主机需要 Node.js 20+（运行 npm install 和 npm run build）：

node --version   # 需 >= 20
npm --version

Docker 镜像构建

• 首次部署需要较长时间（npm install + Docker build）
• 后续增量部署会快很多

端口 41733

• 已确认映射到外网
• HTTPS 访问：https://www.1415243231.top:41733/webhook

验证自动部署

# 查看最近一次 webhook 触发后的 deploy 日志
journalctl -u webhook_receiver --since "5 minutes ago"

故障排查

Gitea 显示 webhook 失败（Connection refused） → 确认 NAS 41733 端口映射正常，curl http://localhost:41733/webhook 测试

Webhook 触发但 deploy 没执行 → journalctl -u webhook_receiver 看报错；检查 secret 是否匹配

Docker build 失败 → 手动在 NAS 上跑一次确认能成功：

cd /vol1/1000/docker/publish
npm install && npm run build
docker-compose -f docker-compose.yml up --build -d