137 lines
3.6 KiB
Markdown
137 lines
3.6 KiB
Markdown
# 自动部署指南 - 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. 上传文件
|
||
|
||
```bash
|
||
# 将 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` 换成你生成的随机字符串：
|
||
|
||
```bash
|
||
# 生成随机 secret
|
||
python3 -c "import secrets; print(secrets.token_hex(16))"
|
||
```
|
||
|
||
### 3. 安装并启动服务
|
||
|
||
```bash
|
||
# 重载 systemd
|
||
systemctl daemon-reload
|
||
|
||
# 启用开机自启
|
||
systemctl enable webhook_receiver
|
||
|
||
# 启动
|
||
systemctl start webhook_receiver
|
||
|
||
# 确认状态
|
||
systemctl status webhook_receiver
|
||
```
|
||
|
||
### 4. 确认 webhook receiver 监听
|
||
|
||
```bash
|
||
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 上观察：
|
||
|
||
```bash
|
||
# 实时看 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`）：
|
||
|
||
```bash
|
||
node --version # 需 >= 20
|
||
npm --version
|
||
```
|
||
|
||
### Docker 镜像构建
|
||
- 首次部署需要较长时间（npm install + Docker build）
|
||
- 后续增量部署会快很多
|
||
|
||
### 端口 41733
|
||
- 已确认映射到外网
|
||
- HTTPS 访问：`https://www.1415243231.top:41733/webhook`
|
||
|
||
### 验证自动部署
|
||
|
||
```bash
|
||
# 查看最近一次 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 上跑一次确认能成功：
|
||
```bash
|
||
cd /vol1/1000/docker/publish
|
||
npm install && npm run build
|
||
docker-compose -f docker-compose.yml up --build -d
|
||
```
|