吴璨
102 lines
3.9 KiB
Markdown
102 lines
3.9 KiB
Markdown
# 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 与退出码。
|