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