STUN Webhook Worker

项目简介

本项目是一个运行在 Cloudflare Workers 上的服务，为 Lucky 的 STUN 内网穿透提供 Webhook 支持。它能够：

• 接收并处理 Lucky 发送的 Webhook 请求
• 支持 Lucky 提供的变量替换
• 提供一个导航页面，方便快速访问内网穿透的服务
• 支持通过域名访问内网穿透服务
• 支持两种访问模式：代理模式和重定向模式
• 自动配置 tmp 域名 DNS，解决 IP 变化问题

功能特性

1. Webhook 处理

• 接收 HTTP POST 请求
• 解析请求体中的数据
• 存储穿透信息到 Cloudflare KV
• 自动配置 tmp 域名 DNS 记录

2. 变量支持

• #{ruleName} : 规则名称
• #{ipAddr} : 当前STUN穿透获得的公网IP地址(含端口)
• #{ip} : 当前STUN穿透获得的公网IP地址的IP部分
• #{port} : 当前STUN穿透获得的公网IP地址中的端口部分
• #{time} : 触发Webhook的时间

3. 访问模式

支持两种访问模式，可在导航页面切换：

• 代理模式：https://xxx.stun.域名.top → Worker 代理请求到 http://tmp.域名.top:端口

  • 优点：保持域名显示，无需重定向
  • 缺点：需要 tmp 域名能正常解析

• 重定向模式：https://xxx.stun.域名.top → 302 跳转到 http://IP:端口

  • 优点：不需要 tmp 域名
  • 缺点：地址栏会变成 IP:端口

4. 导航页面

• 响应式设计，支持多种设备
• 显示所有可用的穿透服务
• 显示访问模式（代理模式/重定向模式）
• 支持点击切换访问模式
• 显示服务状态和最后更新时间
• 提供 IP 访问和域名访问链接

部署步骤

1. 准备工作

• 拥有一个 Cloudflare 账号
• 拥有一个已在 Cloudflare 托管的域名
• 安装 Node.js 和 npm

2. 安装依赖

npm install

3. 配置 Cloudflare

3.1 创建 KV 命名空间

1. 登录 Cloudflare 控制台
2. 进入 Workers & Pages
3. 点击 KV
4. 创建一个新的 KV 命名空间，命名为 STUN_WEBHOOK_STORAGE
5. 记下 KV 命名空间 ID

3.2 配置 wrangler.jsonc

编辑 wrangler.jsonc 文件，修改以下配置：

• kv_namespaces[].id: 填入上面创建的 KV 命名空间 ID
• vars.CF_ZONE_ID: 填入你的 Cloudflare Zone ID
• vars.CF_API_TOKEN: 填入你的 Cloudflare API Token
• vars.DOMAIN: 填入你的主域名（如 cswklt.top）

3.3 配置 DNS 记录

在 Cloudflare DNS 设置中添加以下记录：

类型	名称	内容	代理状态
A	tmp	你的公网 IP	开启
A	*.stun	192.0.2.1	开启

重要说明：

• tmp 域名：用于代理访问，Worker 会自动更新其 DNS 记录指向你的公网 IP
• *.stun 通配符：用于服务子域名访问，所有子域名都会路由到 Worker

3.4 配置路由

在 Cloudflare 控制台添加 Worker 路由：

• 路由：*.stun.你的域名.top/*
• 环境：生产

或者通过 wrangler.jsonc 配置（推荐）：

{
  "routes": [
    {
      "pattern": "*.stun.你的域名.top/*",
      "zone_name": "你的域名.top"
    },
    {
      "pattern": "stun.你的域名.top",
      "zone_name": "你的域名.top",
      "custom_domain": true
    }
  ]
}

4. 部署 Worker

npm run deploy
# 或
wrangler deploy

5. 配置 Lucky

在 Lucky 中配置 Webhook URL 和请求参数：

Webhook URL

https://stun.你的域名.top/webhook

请求方式

• 方法：POST
• Content-Type：application/json

请求参数

Lucky 发送的 JSON 请求体应包含以下字段：

参数	说明	示例	必需
ruleName	规则名称	"minifile"	是
ipAddr	公网IP(含端口)	"58.20.119.146:12781"	是
ip	公网IP	"58.20.119.146"	是
port	端口	"12781"	是
time	触发时间	"2026-04-14T12:00:00Z"	是
accessMode	访问模式	"proxy" 或 "redirect"	否（默认 proxy）

Lucky 配置示例

在 Lucky 的 Webhook 设置中：

1. URL：填写 https://stun.你的域名.top/webhook
2. 请求方式：选择 POST
3. Content-Type：选择 application/json
4. 请求体：可以使用 Lucky 的变量，例如：

   {
     "ruleName": "#{ruleName}",
     "ipAddr": "#{ipAddr}",
     "ip": "#{ip}",
     "port": "#{port}",
     "time": "#{time}",
     "accessMode": "proxy"
   }
   

使用方法

1. 访问导航页面

在浏览器中访问：

https://stun.你的域名.top/

2. 查看穿透服务

导航页面会显示所有可用的穿透服务，包括：

• 服务名称
• IP 地址和端口
• 完整地址
• 更新时间
• 访问模式（代理模式/重定向模式）
• IP 访问链接
• 域名访问链接

3. 切换访问模式

1. 在导航页面找到对应的服务
2. 点击"代理模式"或"重定向模式"按钮
3. 模式会立即切换
4. 点击"域名访问"测试不同模式的效果

4. 访问内网服务

通过以下方式访问内网服务：

• IP 访问：http://{IP}:{端口}
• 域名访问：https://{规则名称}.stun.你的域名.top

5. 自动 DNS 更新

当 Lucky 触发 Webhook 时：

1. Worker 自动更新 tmp 域名的 A 记录指向新的 IP
2. 如果 IP 没变，不会重复更新
3. 代理请求自动使用 tmp.你的域名.top:端口 格式访问

配置说明

wrangler.jsonc 文件

{
  "name": "stunwebhook",
  "compatibility_date": "2026-04-14",
  "main": "worker.js",
  "routes": [
    {
      "pattern": "*.stun.你的域名.top/*",
      "zone_name": "你的域名.top"
    },
    {
      "pattern": "stun.你的域名.top",
      "zone_name": "你的域名.top",
      "custom_domain": true
    }
  ],
  "kv_namespaces": [
    {
      "binding": "KV",
      "id": "你的KV命名空间ID",
      "preview_id": "你的KV命名空间ID"
    }
  ],
  "vars": {
    "CF_ZONE_ID": "你的Cloudflare Zone ID",
    "CF_API_TOKEN": "你的Cloudflare API Token",
    "DOMAIN": "stun.你的域名.top"
  }
}

Cloudflare API Token 权限

确保 API Token 有以下权限：

• Zone - DNS - Edit
• Worker - Worker Scripts - Edit

常见问题

1. Error 1003: Direct IP access not allowed

这是 Cloudflare 安全限制，禁止 Worker 直接访问 IP 地址。

解决方案：

• 使用代理模式访问（推荐）
• 或切换到重定向模式

2. 域名访问失败 (Error 522)

可能原因：

• *.stun 通配符 DNS 记录未配置
• tmp 域名 DNS 记录未配置或 IP 不正确
• Cloudflare API Token 缺少 DNS 编辑权限
• Worker 未正确部署
• 运营商限制，Cloudflare 无法连接到你的服务器

解决方案：

1. 检查 DNS 记录是否正确配置
2. 切换到重定向模式试试
3. 检查 Worker 日志

3. 导航页面不显示服务

可能原因：

• KV 存储未正确绑定
• Webhook 未被调用或调用失败
• 网络问题

解决方案：

1. 检查 KV 命名空间是否正确绑定
2. 手动调用 Webhook 测试
3. 查看浏览器控制台错误信息

4. 切换访问模式失败

解决方案：

1. 检查网络连接
2. 查看浏览器控制台的错误信息

5. 代理模式无法访问（522 错误）

这是因为 Cloudflare 无法连接到 tmp 域名。

解决方案：

1. 确认 tmp.你的域名.top 的 DNS 记录指向正确的 IP
2. 确认代理状态是开启的
3. 等待 DNS 生效（可能需要几分钟）
4. 切换到重定向模式

6. IP 变化后无法访问

解决方案：

1. 确保 tmp 域名 DNS 记录已配置
2. 等待 DNS 生效（通常几分钟）
3. 检查 Worker 日志中的 DNS 更新状态
4. 手动触发一次 Webhook 更新 IP

注意事项

1. 安全：保护好 Cloudflare API Token，避免泄露
2. 权限：确保 Cloudflare API Token 有足够的权限（DNS 编辑权限）
3. 限制：Cloudflare Worker 有执行时间和请求大小的限制
4. 费用：Cloudflare Workers 有免费额度，超出后会产生费用
5. 域名：确保域名已在 Cloudflare 托管
6. DNS 生效：DNS 记录更改可能需要几分钟生效
7. 国内访问：Cloudflare 在国内访问可能不稳定，建议使用重定向模式

技术栈

• Cloudflare Workers
• JavaScript
• HTML/CSS
• JSON
• Cloudflare API
• Cloudflare KV

许可证

MIT License