HookPilot/docs/lucky.md

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：

#!/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 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 手动验证

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 与退出码。