feat: initial commit for HookPilot

2026-09-27 20:09:10 +08:00
commit e998d4defc
73 changed files with 10782 additions and 0 deletions
@@ -0,0 +1,101 @@
+# Lucky 对接示例：DDNS 更新后同步家庭 IP
+
+本示例演示设计文档中的验收场景：Lucky 检测到公网 IP 变化后调用 HookPilot，脚本把新 IP 写入指定文件。你可以在此基础上改为更新防火墙白名单、重写 Nginx 配置等。
+
+## 1. 在 HookPilot 中创建接口
+
+进入“接口管理 → 新建接口”：
+
+**基本配置**
+
+| 配置项 | 值 |
+|---|---|
+| 接口名称 | 更新家庭 IP |
+| 接口标识 | `home-ip`（调用地址为 `/hooks/home-ip`） |
+| 请求方式 | POST |
+
+**参数**
+
+| 环境变量 | 来源 | 字段 | 类型 | 必填 |
+|---|---|---|---|---|
+| `HOOK_IP` | JSON 请求体 | `ip` | IP 地址 | ✓ |
+
+**脚本**：在“插入示例模板”中选择“更新家庭 IP”，按需修改 `TARGET_FILE`：
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+TARGET_FILE="/var/lib/hookpilot/workspace/home-ip.txt"
+
+old_ip=""
+if [[ -f "$TARGET_FILE" ]]; then
+  old_ip="$(cat "$TARGET_FILE")"
+fi
+
+if [[ "$old_ip" == "$HOOK_IP" ]]; then
+  echo "IP 未变化：$HOOK_IP"
+  exit 0
+fi
+
+printf '%s\n' "$HOOK_IP" > "$TARGET_FILE.tmp"
+mv "$TARGET_FILE.tmp" "$TARGET_FILE"
+echo "IP 已更新：${old_ip:-无} -> $HOOK_IP"
+```
+
+**执行策略**
+
+| 配置项 | 值 | 说明 |
+|---|---|---|
+| 响应模式 | 同步 | Lucky 可以根据响应判断脚本是否成功 |
+| 超时时间 | 30 秒 | |
+| 接口并发数 | 1 | 连续多次调用按接收顺序执行 |
+
+点击“创建接口”，**立即复制弹窗中的 Token**（只显示一次）。
+
+创建后切到“测试”标签，点击“按参数生成示例”→“预览参数映射”确认映射正确，再点击“执行（真实运行）”验证脚本。
+
+## 2. 在 Lucky 中配置 Webhook
+
+在 Lucky 的“动态域名”任务中打开 Webhook 设置（不同版本界面位置和名称可能略有差异，以实际界面为准）：
+
+| Lucky 配置项 | 值 |
+|---|---|
+| 接口地址 | `https://hooks.example.com/hooks/home-ip` |
+| 请求方法 | POST |
+| 请求头 | `Authorization: Bearer hp_xxxxxxxx`<br>`Content-Type: application/json` |
+| 请求主体 | `{"ip":"#{ipAddr}"}` |
+| 接口调用成功包含的字符串 | `"ok":true` |
+
+- `#{ipAddr}` 是 Lucky 提供的“当前 IP”变量，具体变量名请以你所用 Lucky 版本 Webhook 设置页的提示为准。
+- 如果 Lucky 版本不支持自定义请求头，可以把 Token 放在地址中：`https://hooks.example.com/hooks/home-ip?token=hp_xxxxxxxx`。这种方式的 Token 可能出现在代理访问日志中，示例 Nginx 配置已去掉日志中的 query。
+
+## 3. 响应说明
+
+同步模式下 HookPilot 的响应：
+
+| 情况 | HTTP 状态 | 响应体示例 |
+|---|---|---|
+| 脚本成功（退出码 0） | 200 | `{"ok":true,"executionId":12,"status":"success","exitCode":0,"durationMs":25}` |
+| 脚本失败（非零退出码） | 500 | `{"ok":false,"executionId":13,"status":"failed","exitCode":1,...}` |
+| 脚本超时 | 504 | `{"ok":false,...,"status":"timeout"}` |
+| 被手动终止 / 取消 | 409 | `{"ok":false,...,"status":"killed"}` |
+| Token 错误 | 401 | `{"ok":false,"error":"unauthorized","message":"Token 无效"}` |
+| 参数缺失或 IP 非法 | 400 | `{"ok":false,"error":"invalid_params","details":["HOOK_IP：不是合法的 IP 地址"]}` |
+| 接口已停用 | 403 | `{"ok":false,"error":"disabled",...}` |
+| 请求方式不符 | 405 | `{"ok":false,"error":"method_not_allowed",...}` |
+
+Token 错误、参数校验失败等情况**不会执行脚本**，也不会生成执行记录。脚本输出只在管理界面查看，不返回给 Lucky。
+
+异步模式下只要任务入队就返回 `202 {"ok":true,"executionId":12,"status":"queued"}`，表示已接收，不代表脚本执行成功。
+
+## 4. 用 curl 手动验证
+
+```bash
+curl -i -X POST 'https://hooks.example.com/hooks/home-ip' \
+  -H 'Authorization: Bearer hp_xxxxxxxx' \
+  -H 'Content-Type: application/json' \
+  -d '{"ip":"203.0.113.10"}'
+```
+
+然后在“执行记录”中查看本次执行的参数、脚本版本、stdout / stderr 与退出码。