Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
 nomdn
|
d7cc9d45e7 | ||
|
nomdn
|
56d6bc6c08 | ||
|
nomdn
|
981b2fec9c |
No files matched your search
@@ -63,6 +63,15 @@ jobs:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v4
|
||||
|
||||
# 版本注入 src/Dockerfile（build-args 见下方构建步骤）：
|
||||
# VERSION 取 ref 名——打 v* 标签时与 build_and_release.yml 的二进制产物一致（带 v 前缀），
|
||||
# 手动触发时为分支名（与 merge 阶段打的 main 标签对应）
|
||||
- name: Set version metadata
|
||||
run: |
|
||||
echo "VERSION=${GITHUB_REF_NAME}" >> "$GITHUB_ENV"
|
||||
echo "COMMIT=${GITHUB_SHA}" >> "$GITHUB_ENV"
|
||||
echo "BUILD_TIME=$(date -u +%Y-%m-%dT%H:%M:%SZ)" >> "$GITHUB_ENV"
|
||||
|
||||
- name: Set up Docker Buildx
|
||||
uses: docker/setup-buildx-action@v3
|
||||
|
||||
@@ -87,6 +96,11 @@ jobs:
|
||||
with:
|
||||
context: ${{ matrix.context }}
|
||||
platforms: ${{ matrix.platforms }}
|
||||
# 只有 src/Dockerfile 声明了这三个 ARG；middleware-go 未声明，BuildKit 会静默忽略
|
||||
build-args: |
|
||||
VERSION=${{ env.VERSION }}
|
||||
COMMIT=${{ env.COMMIT }}
|
||||
BUILD_TIME=${{ env.BUILD_TIME }}
|
||||
labels: ${{ steps.meta.outputs.labels }}
|
||||
outputs: type=image,name=ghcr.io/${{ github.repository }}/${{ matrix.image }},push-by-digest=true,name-canonical=true,push=true
|
||||
cache-from: type=gha,scope=${{ matrix.image }}-${{ matrix.platform_id }}
|
||||
|
||||
@@ -20,6 +20,8 @@ node_modules/
|
||||
docs/.vitepress/.temp/
|
||||
docs/.vitepress/cache/
|
||||
docs/.vitepress/dist/
|
||||
# 构建期临时配置文件（vitepress 每次构建生成，用完即弃）
|
||||
docs/.vitepress/*.timestamp-*
|
||||
tmp/
|
||||
setting.json
|
||||
*.BIN
|
||||
@@ -12,11 +12,14 @@ curl -fsSL https://raw.githubusercontent.com/nomdn/ipw-cn/main/install.sh -o ins
|
||||
|
||||
完整部署（后端节点 / 独立中间件 / 前端）与配置说明见 [文档](https://github.com/nomdn/ipw-cn/tree/main/docs)：
|
||||
|
||||
- [功能总览](docs/info/features.md)（探测能力、IP 数据源、可靠性设计）
|
||||
- [快速开始](docs/guide/getting-started.md)
|
||||
- [后端节点部署](docs/guide/deploy-node.md)
|
||||
- [中间件部署](docs/guide/deploy-middleware.md)
|
||||
- [前端部署](docs/guide/deploy-frontend.md)
|
||||
- [配置文件](docs/guide/config.md)
|
||||
- [节点 API 与协议](docs/guide/node-api.md)（业务接口、管理接口、WS 协议、上报协议）
|
||||
- [公开 API（/api/v1）](docs/guide/public-api.md)（收集中心程序化接口：鉴权、端点与响应示例、公开状态接口）
|
||||
|
||||
## 项目结构
|
||||
|
||||
|
||||
@@ -52,6 +52,7 @@ export default defineConfig({
|
||||
text: '简介',
|
||||
items: [
|
||||
{ text: '概述', link: '/info/overview' },
|
||||
{ text: '功能总览', link: '/info/features' },
|
||||
{ text: '快速入门', link: '/guide/getting-started' },
|
||||
{ text: '配置文件', link: '/guide/config' },
|
||||
],
|
||||
@@ -66,6 +67,14 @@ export default defineConfig({
|
||||
{ text: '前端', link: '/guide/deploy-frontend' },
|
||||
],
|
||||
},
|
||||
// 参考
|
||||
{
|
||||
text: '参考',
|
||||
items: [
|
||||
{ text: '节点 API 与协议', link: '/guide/node-api' },
|
||||
{ text: '公开 API（/api/v1）', link: '/guide/public-api' },
|
||||
],
|
||||
},
|
||||
],
|
||||
|
||||
socialLinks: [
|
||||
|
||||
+63
-9
@@ -20,17 +20,44 @@
|
||||
- `port`：监听端口
|
||||
- `dns-server`：DNS 解析服务器，支持**主从 failover**——逗号分隔多地址（如 `"119.28.28.28:53,223.5.5.5:53"`），第一个为主，主查询失败（超时/网络错误）自动切换下一个；每项支持 `ip:port`（UDP）或 `https://` URL（DoH）；**留空则启动时自动探测系统 DNS**（`IP:Port` 逗号分隔串）兜底
|
||||
- `dnssec-server`：**DNSSEC 专用** DNS 服务器（同样支持主从逗号分隔）；留空则沿用 `dns-server`；`dns-server` 与 `dnssec-server` **都留空时自动探测系统 DNS** 兜底
|
||||
- `block-private-ips`：SSRF 防护开关
|
||||
- `ipdb`：IP 数据库开关（首次启动自动下载约 450MB，之后每 24h 更新）
|
||||
- `block-private-ips`：SSRF 防护开关（拒绝出站连接内网/私有地址；探测目标命中私有网段时直接返回伪造结果，禁止跨跳重定向）
|
||||
- `single-stack`：单栈模式，`ipv4` / `ipv6` / 留空（双栈）。声明单栈的节点跳过另一栈的探测（直接返回 `Skipped due to SINGLE_STACK=...`），EdgeOne / Vercel 等 IPv4-only 环境建议设为 `ipv4`
|
||||
- `ipdb`：IP 数据库开关。**不配置时默认启用**（首次启动自动下载约 450MB，之后每 24h 更新）；仓库的 `setting.json.example` 里显式写为 `"false"`，即**示例配置是关闭状态**——关闭后不加载任何数据库，`/v1/location`、`/v1/asn` 路由不注册，适合只做网络拨测的轻量节点
|
||||
- `cors`：允许的请求来源（逗号分隔）
|
||||
- `trusted-proxies`：可信代理 IP/CIDR（逗号分隔，如 `"10.0.0.0/8,173.245.48.0/20"`）。配置后 `ClientIP` 与 `/v1/location` 归属地接口只信任这些代理转发的 `X-Forwarded-For`，直连公网的节点可防止访客伪造 XFF；**留空保持默认行为（信任所有代理，XFF 可被伪造）**
|
||||
- `access-token`：API 访问令牌，留空则不启用鉴权
|
||||
- `access-token`：API 访问令牌，留空则不启用鉴权。**它同时是 HTTP 管理面的开关**：留空时 `/v1/config`、`/v1/ota` 整组返回 `403`，只能走 WS 通道管理
|
||||
- `gh-proxy`：GitHub 下载代理前缀（如 `"https://ghproxy.com/"`），用于 IP 数据库拉取与 OTA 下载加速；留空直连
|
||||
- `node-ota`：OTA 开关，缺省 `true`（允许收集中心下发）。设为 `false` 时节点拒绝一切 OTA 指令并回传原因，适合只读文件系统 / 编排托管（升级走各自部署渠道）的部署。**支持运行时热改**（`PATCH /v1/config` 或 WS `config` 下发即时生效，改后按新值判定后续 OTA 指令）
|
||||
- `ws-url`：WS 通道地址——接入独立中间件的 WebSocket 地址（如 `"wss://middleware-1.api-ipw.wsmdn.top/ws"`，须含 `wss://` 前缀与 `/ws` 路径）；支持**逗号分隔多个中间件，同时连接全部（多活）**，任一断开只重连自己，不影响其他连接；留空 = 不启用 WS 客户端，走原 HTTP 接口
|
||||
- `node-id`：WS 节点 id（与中间件 `api-keys`/`ws-keys` 键、前端配置的节点 `id` 一致；建议用 UUID 唯一标识）
|
||||
- `node-key`：WS 注册 key（与中间件 `ws-keys[节点id]` 一致；**必填**——节点未配置该 key 时中间件拒绝注册并返回 401）
|
||||
- `node-ota`：**OTA 自更新开关**（`"true"` 启用）。启用后节点定期检查本仓库 GitHub Release，发现新版本时下载与当前平台匹配的二进制、**替换自身并重启**（旧二进制保留为 `<程序名>.old` 便于回滚）；默认关闭
|
||||
- `report-url`：**数据上报收集中心** HTTP 基址（如 `"https://collector.example.com"`，即 ipw-boce 中间件）。节点把自身观测的统计/拨测按 `report-interval-seconds` 周期上报；`ws-url` 已启用时优先走 WS `report` 消息（所有已连接中间件广播），WS 未启用或全部掉线时 HTTP POST 到 `<report-url>/report` 兜底；远端配置可覆盖（在 `remote-ignore-config` 里加上 `report-url` 可禁止覆盖）
|
||||
- `report-token`：收集中心 `/report` 鉴权 token（与中间件 `report-token` 配置一致）；属凭据类键，GET 快照里遮蔽为 `***`；**不随远端配置覆盖**（硬编码保护，清单见本页末的「远端配置」一节）
|
||||
- `report-interval-seconds`：上报周期秒，缺省 15
|
||||
|
||||
以上字段均可用环境变量覆盖（`PORTS` / `DNS_SERVER` / `DNSSEC_DNS_SERVER` / `BLOCK_PRIVATE_IPS` / `IPDB` / `CORS` / `TRUSTED_PROXIES` / `ACCESS_TOKEN` / `WS_URL` / `NODE_ID` / `NODE_KEY` / `NODE_OTA`）。需要从远端拉取配置时，设置 `remote-config-url` 或环境变量 `REMOTE_CONFIG_URL`（优先级：远端 > 环境变量 > setting.json）。
|
||||
以上字段均可用环境变量覆盖（`PORTS` / `SINGLE_STACK` / `DNS_SERVER` / `DNSSEC_DNS_SERVER` / `BLOCK_PRIVATE_IPS` / `IPDB` / `CORS` / `TRUSTED_PROXIES` / `GH_PROXY` / `ACCESS_TOKEN` / `WS_URL` / `NODE_ID` / `NODE_KEY` / `NODE_OTA` / `REPORT_URL` / `REPORT_TOKEN` / `REPORT_INTERVAL_SECONDS`）。需要从远端拉取配置时，设置 `remote-config-url` 或环境变量 `REMOTE_CONFIG_URL`（优先级：远端 > 环境变量 > setting.json）；`remote-ignore-config` 对应的环境变量为 `REMOTE_IGNORE_CONFIG`（JSON 数组字符串）。
|
||||
|
||||
### 运行时配置管理
|
||||
|
||||
除启动加载外，节点（v1.4+）还支持被**远程读写当前生效配置**——收集中心控制台可以改配置而不必登录节点主机，节点也可以在运行中刷新远端配置。
|
||||
|
||||
| 动作 | HTTP | WS | 说明 |
|
||||
|------|------|----|------|
|
||||
| 读取 | `GET /v1/config` | `config` + `action=get` | 返回生效配置快照 + `secretKeys` + `restartRequiredKeys` |
|
||||
| 修改 | `PATCH /v1/config`（`?persist=1` 时写回本地 setting.json） | `config` + `action=patch` | 逐键应用，只改传入的键 |
|
||||
| 刷新远端 | `POST /v1/config/refresh` | `config` + `action=refresh` | 重新拉取 `remote-config-url` 并应用 |
|
||||
|
||||
三条约定：
|
||||
|
||||
- **凭据类键不回显明文**：`access-token` / `node-key` / `report-token` 在快照里是 `***`。下发时必须剔除这些键，否则会把真值覆盖成三个星号（收集中心控制台已自动剔除）。
|
||||
- **凭据类键中 `access-token` / `report-token` 不受远端配置影响**：它们被硬编码进节点侧的保护名单（`configRemoteProtectedKeys`），远端配置里写了也会被跳过，并在应答 `protectedIgnored` 与日志中如实回报；本地 PATCH 不受此限。原因见本页末的「远端配置」一节。
|
||||
- **节点不自行重启**：`port` / `cors` / `ipdb` / `report-interval-seconds` / `trusted-proxies` / `node-id` / `node-key` / `access-token` 是启动期固定的，改动后在应答 `restartRequired` 里如实列出，但**不会自动重启**；只有"值真的变了"才报，避免每次全量下发都误报。**`ws-url` 是例外，热生效**（控制器按新地址多退少补）；`dns-server` / `dnssec-server` / `block-private-ips` / `single-stack` / `node-ota` 每次消费重读，同样即时生效。
|
||||
- **内存改动会被重启顶掉**：节点侧优先级为 远端 > 环境变量 > `setting.json`。只 PATCH 内存（或 `persist` 写本地文件）时，重启后仍可能被 ENV 顶掉；要长期生效应 **`refresh`**（改远端配置）或把改动合并进托管配置。
|
||||
|
||||
> [!NOTE]
|
||||
> **与托管配置的区别**：托管配置（收集中心的 `node_configs`，经 `GET /remote-config/:nodeId` 下发）是**节点启动时拉的远端配置**，是持久来源；运行时配置读写的是**节点进程内存里当前生效的值**。前者决定"重启后是什么"，后者反映"现在是什么"。
|
||||
|
||||
接口细节见 [节点 API 与协议参考](/guide/node-api) 的「管理接口」一节。
|
||||
|
||||
---
|
||||
|
||||
@@ -141,6 +168,22 @@ APIBaseURL: {
|
||||
|
||||
也可以在 `nuxt.config.ts` 的 `runtimeConfig.apiKeys` 里直接写死（不推荐，密钥不应进仓库）。
|
||||
|
||||
### 内置中间件数据上报（调一次上报一次）
|
||||
|
||||
内置中间件可作为数据上报入口：每转发一次请求，向收集中心（ipw-boce 中间件）`POST /report` 上报一次统计与拨测明细。**配置全部经环境变量注入**（敏感项不进仓库）：
|
||||
|
||||
| 环境变量 | 说明 |
|
||||
|------|------|
|
||||
| `NUXT_BOCE_REPORT_URL` | 收集中心基址（如 `https://collector.example.com`）；**留空 = 不上报**（此时转发也不带标记头，由节点兜底记账） |
|
||||
| `NUXT_BOCE_REPORT_TOKEN` | 收集中心 `/report` 鉴权 token（敏感，与收集中心 `report-token` 配置一致） |
|
||||
| `NUXT_BOCE_REPORT_INSTANCE` | 上报方标识（存收集库 `probe_results.origin`）；默认 `frontend-ssr` |
|
||||
|
||||
行为约定：
|
||||
|
||||
- 配置了上报后，内置中间件转发请求会带 `X-Boce-Reporter` 标记头——后端节点据此跳过这些请求的统计（防双算，见后端节点"数据上报"一节）
|
||||
- 上报为 fire-and-forget：失败静默丢弃、不重试（统计是增量累加语义，重试会双算），不影响转发响应
|
||||
- 上报失败不影响主链路；超时 5 秒
|
||||
|
||||
---
|
||||
|
||||
## 独立中间件（middleware-go）
|
||||
@@ -179,7 +222,7 @@ APIBaseURL: {
|
||||
- `remote-ignore-config`：**不被远端配置覆盖的配置项列表**（数组），如 `["port", "rate-limit"]`；也可用环境变量 `REMOTE_IGNORE_CONFIG`（JSON 数组字符串，优先于 setting.json）
|
||||
- `api-keys`：用于向后端注入 `Authorization: Bearer <key>`，优先级：setting.json `api-keys` > 环境变量 `API_KEYS`（JSON 字符串）。**敏感凭据，强制忽略，不随远端配置覆盖**
|
||||
- `ws-keys`：WS 注册校验表（`节点id → key`）：节点经 WS 注册时，`register` 消息的 `key` 必须与 `ws-keys[节点id]` 一致，否则返回 401 并断开；优先级：setting.json `ws-keys` > 环境变量 `WS_KEYS`（JSON 字符串）。**敏感凭据，强制忽略，不随远端配置覆盖**。与 `api-keys` **相互独立**——`api-keys` 管 HTTP 转发鉴权，`ws-keys` 管 WS 注册校验，可分别配置不同 key（例如 WS 节点单独换 key 不影响 HTTP 转发）
|
||||
- 节点池与前端 `config/index.ts` 结构一致：`APIBaseURL` 为拨测节点池（含 `DualStack` / `IPv4` / `IPv6` 三栈），`IPLocationAPI` 为 IP 归属地 / ASN 节点池（纯数组，无栈）；节点加 `"ws": true` 可让该节点走 WS 通道通信，详见 [中间件部署 - WS 通道](/guide/deploy-middleware#ws-通道拨测数据经-websocket-传输)
|
||||
- 节点池与前端 `config/index.ts` 结构一致：`APIBaseURL` 为拨测节点池（含 `DualStack` / `IPv4` / `IPv6` 三栈），`IPLocationAPI` 为 IP 归属地 / ASN 节点池（纯数组，无栈）；节点加 `"ws": true` 可让该节点走 WS 通道通信，详见 [中间件部署](/guide/deploy-middleware) 的「WS 通道」一节
|
||||
|
||||
### WS 通道配置一览
|
||||
|
||||
@@ -193,7 +236,15 @@ WS 通道涉及**中间件（服务端）**与**后端节点（客户端）**两
|
||||
| 节点（客户端） | `node-id` | `NODE_ID` | 节点 id，与中间件 `api-keys`/`ws-keys` 键一致（建议 UUID） |
|
||||
| 节点（客户端） | `node-key` | `NODE_KEY` | 注册 key，与中间件 `ws-keys[节点id]` 一致，**必填** |
|
||||
|
||||
**链路**：中间件收到 `ws:true` 节点的拨测请求 → 经 WS 发 `probe` → 节点执行探针（直调 webtest 函数 + 缓存）→ `probe_result` 回传 → 中间件返回 HTTP 响应（`Content-Type: application/json`）。节点侧接入步骤见 [后端节点部署 - WS 通道接入](/guide/deploy-node#ws-通道接入可选)。
|
||||
**数据上报通道**（节点把自身观测的统计/拨测上报到收集中心，归属规则防双算——中间件转发的请求由中间件上报，节点只报直连/前端/边缘流量）：
|
||||
|
||||
| 角色 | 配置项 | 环境变量 | 说明 |
|
||||
|------|--------|----------|------|
|
||||
| 节点（客户端） | `report-url` | `REPORT_URL` | 收集中心（ipw-boce 中间件）HTTP 基址；WS 在线时优先走 WS 广播，掉线时 POST `<report-url>/report` 兜底 |
|
||||
| 节点（客户端） | `report-token` | `REPORT_TOKEN` | `/report` 鉴权 token，与收集中心 `report-token` 一致；属凭据类键，快照遮蔽为 `***`，**不随远端配置覆盖** |
|
||||
| 节点（客户端） | `report-interval-seconds` | `REPORT_INTERVAL_SECONDS` | 上报周期秒，缺省 15 |
|
||||
|
||||
**链路**：中间件收到 `ws:true` 节点的拨测请求 → 经 WS 发 `probe` → 节点执行探针（直调 webtest 函数 + 缓存）→ `probe_result` 回传 → 中间件返回 HTTP 响应（`Content-Type: application/json`）。节点侧接入步骤见 [后端节点部署](/guide/deploy-node) 的「WS 通道接入」一节。
|
||||
|
||||
---
|
||||
|
||||
@@ -216,8 +267,11 @@ WS 通道涉及**中间件（服务端）**与**后端节点（客户端）**两
|
||||
- 部分字段缺省不会冲掉本地配置——远端只需包含要覆盖的字段
|
||||
- **敏感凭据强制忽略，永远不被远端覆盖**（代码写死，无需配置）：
|
||||
- 后端 `access-token`：不随远端覆盖（保持 环境变量 > setting.json），远端里的 `access-token` 会被忽略
|
||||
- 后端 `report-token`：同上。收集中心的托管配置里写了也不生效，节点会在日志与控制台应答的 `protectedIgnored` 里列出被跳过的键
|
||||
- 中间件 `api-keys` / `ws-keys`：不随远端覆盖，远端里的 `api-keys`/`ws-keys` 会被忽略
|
||||
- `remote-ignore-config`（后端键名 `remote-ignore-config` / env `REMOTE_IGNORE_CONFIG`）：额外指定**不被远端覆盖的配置项列表**，数组中的键即使远端下发也不生效。适用于 access-token / api-keys / ws-keys 之外的敏感项（如 `node-key`、`dns-server` 等），也可覆盖"非空才覆盖"规则
|
||||
|
||||
为什么把这两项写死：它们被远端改错时的故障形态都是「远端一错、本地失联、且无法再远程修回」——`report-token` 被改 → 上报被收集中心 `/report` 拒收，控制台上节点仍显示在线、数据却静默断了；`access-token` 被改 → 控制台再也连不上该节点的管理面，连改回去的通道都没了。所以这层解耦必须由节点自己兜底，不能依赖「配置源别写错」。`node-key` 有意**不在**保护名单里（托管部署下常由远端统一下发节点身份），需要一并锁死时把它写进 `remote-ignore-config`。保护名单只增不减，且**只约束远端下发**，本地 `PATCH` 不受影响。
|
||||
- `remote-ignore-config`（后端键名 `remote-ignore-config` / env `REMOTE_IGNORE_CONFIG`）：额外指定**不被远端覆盖的配置项列表**，数组中的键即使远端下发也不生效。适用于 Node 身份类与其它不想被远端左右的项（如 `node-key`、`dns-server` 等），也可覆盖"非空才覆盖"规则
|
||||
|
||||
**拉取行为**：
|
||||
|
||||
@@ -225,7 +279,7 @@ WS 通道涉及**中间件（服务端）**与**后端节点（客户端）**两
|
||||
- HTTP 超时 **10 秒**，仅接受 **200** 响应（404/5xx 视为失败）
|
||||
- 拉取或 JSON 解析失败：打印警告日志 `WARN failed to fetch remote config, fallback to local: ...`，**自动回退本地配置**，服务正常启动，不会崩溃
|
||||
- 拉取成功：启动日志打印 `remote config applied from <url>`
|
||||
- **没有重试、没有定时刷新**：改远端配置后需要重启进程才会重新拉取
|
||||
- **启动时拉取一次，运行中可手动刷新**：进程启动的配置加载阶段拉取一次；此后不会自动轮询远端，但可经 `POST /v1/config/refresh`（或 WS `config` + `action=refresh`）**主动重新拉取并应用**，无需重启——收集中心控制台的「刷新远端」按钮即走这条路
|
||||
|
||||
**示例一：后端**（主线，远端 JSON 放在 `https://example.com/ipw-config.json`）：
|
||||
|
||||
|
||||
@@ -26,7 +26,7 @@ pnpm dev
|
||||
|
||||
## 配置说明
|
||||
|
||||
前端所有配置集中在 `frontend-ssr/config/index.ts`，完整配置项见 [配置文件 - 前端](/guide/config#前端-configindexts)：
|
||||
前端所有配置集中在 `frontend-ssr/config/index.ts`，完整配置项见 [配置文件](/guide/config) 的「前端」一节：
|
||||
|
||||
| 配置项 | 说明 |
|
||||
|--------|------|
|
||||
@@ -106,4 +106,4 @@ node .output/server/index.mjs # 默认监听 3000 端口
|
||||
## 常见问题
|
||||
|
||||
- **部署后接口 403 / 跨域**：检查后端 `cors` 配置（独立中间件见 `middleware-go/setting.json` 的 `cors` 字段，逗号分隔允许域名）；服务端转发请求不带 `Origin`，浏览器直接调用才受 CORS 限制。
|
||||
- **出站 IP 检测接口被浏览器拦截**：页面直连的 IP 检测接口需要 CORS，详见 [配置文件 - 出站 IP 检测接口](/guide/config#出站-ip-检测接口v4onlyapi--v6onlyapi--dualstackapi)。
|
||||
- **出站 IP 检测接口被浏览器拦截**：页面直连的 IP 检测接口需要 CORS，详见 [配置文件](/guide/config) 的「出站 IP 检测接口」一节。
|
||||
@@ -50,9 +50,9 @@ CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o middleware-go-linux-amd64 .
|
||||
|
||||
**OTA 自更新**（可选，默认关闭）：配置 `"ota": "true"`（或环境变量 `OTA=true`）后，中间件定期检查本仓库 Release，下载与当前平台匹配的 `middleware-go-*` 资产并替换自身重启。下载加速可配 `"gh-proxy": ""`（或 `GH_PROXY` 环境变量）。交接流程与后端节点一致：预检 → 原子替换 → 优雅停机 → 拉起新进程 → 健康检查确认；失败自动回滚 `.old` 备份。
|
||||
|
||||
所有配置可用环境变量覆盖（`API_BASE_URLS` / `IP_LOCATION_APIS` / `CORS` / `TRUSTED_PROXIES` / `API_KEYS` / `WS_KEYS` / `RATE_LIMIT` 等，数组/对象用 JSON 字符串），优先级：**环境变量 > setting.json > 默认值**（远端配置 `REMOTE_CONFIG_URL` 高于两者，详见 [配置文件 - 远端配置](/guide/config#远端配置remoteconfigurl)）。
|
||||
所有配置可用环境变量覆盖（`API_BASE_URLS` / `IP_LOCATION_APIS` / `CORS` / `TRUSTED_PROXIES` / `API_KEYS` / `WS_KEYS` / `RATE_LIMIT` 等，数组/对象用 JSON 字符串），优先级：**环境变量 > setting.json > 默认值**（远端配置 `REMOTE_CONFIG_URL` 高于两者，详见 [配置文件](/guide/config) 的「远端配置」一节）。
|
||||
|
||||
需要守护运行时，参考 [后端节点部署 - 方案五：一键安装](/guide/deploy-node#方案五一键安装installsh) 的 systemd 管理方式（`ExecStart` 指向中间件二进制，`WorkingDirectory` 指向 `middleware-go/setting.json` 所在目录）。
|
||||
需要守护运行时，参考 [后端节点部署](/guide/deploy-node) 的「方案五：一键安装」一节的 systemd 管理方式（`ExecStart` 指向中间件二进制，`WorkingDirectory` 指向 `middleware-go/setting.json` 所在目录）。
|
||||
|
||||
## WS 通道（拨测数据经 WebSocket 传输）
|
||||
|
||||
@@ -101,7 +101,7 @@ middleware-go 内置 WS 服务端，后端节点可作为 **WS 客户端**连入
|
||||
|
||||
### 节点侧接入（WS 客户端）
|
||||
|
||||
1. 连接 `ws://<中间件IP>:8092/ws`（本仓库后端节点接入方式见 [后端节点部署 - WS 通道接入](/guide/deploy-node#ws-通道接入可选)，配置 `WS_URL` / `NODE_ID` / `NODE_KEY` 即可自动连接注册；`WS_URL` 支持逗号分隔多个中间件地址，节点会**同时连接全部（多活）**，任一断开只重连自己）
|
||||
1. 连接 `ws://<中间件IP>:8092/ws`（本仓库后端节点接入方式见 [后端节点部署](/guide/deploy-node) 的「WS 通道接入」一节，配置 `WS_URL` / `NODE_ID` / `NODE_KEY` 即可自动连接注册；`WS_URL` 支持逗号分隔多个中间件地址，节点会**同时连接全部（多活）**，任一断开只重连自己）
|
||||
2. 首条消息发 `register { "nodeId": "<与中间件配置一致的节点 id>", "key": "<注册凭证>" }`（节点在 setting.json `ws-keys` 里配了 key 就必须传对；未配置 key 的开放节点可不传）
|
||||
3. 收到 `probe` → 执行拨测 → 回 `probe_result`（必须携带原 `requestId`，支持乱序返回，同一连接可并发多个拨测）
|
||||
4. 收到 `ping` → 回 `pong`；`status` 可忽略或记录
|
||||
|
||||
+74
-15
@@ -18,6 +18,22 @@ npx edgeone pages deploy -n ipw-cn -t $EDGEONE_API_TOKEN
|
||||
|
||||
`serverless/edgeone/` 版本的配置来源为 环境变量 + 远端配置（`REMOTE_CONFIG_URL`）。
|
||||
|
||||
### 数据上报（可选）
|
||||
|
||||
`serverless/edgeone/` 版本**没有 WS 客户端**（边缘函数不维持长连接），因此上报只走 HTTP 一条路：按周期把统计与拨测明细 `POST <report-url>/report` 到收集中心。下列键同样支持环境变量与远端配置两种来源（远端配置优先）：
|
||||
|
||||
| 配置键 | 环境变量 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `node-id` | `NODE_ID` | 上报身份（写入 `probe_results.origin`）；留空回退 hostname |
|
||||
| `report-url` | `REPORT_URL` | 收集中心基址；留空则不上报 |
|
||||
| `report-token` | `REPORT_TOKEN` | `/report` 鉴权，请求头 `Authorization: Bearer <token>`；收集中心未配 token 时可留空 |
|
||||
| `report-interval-seconds` | `REPORT_INTERVAL_SECONDS` | 上报间隔秒，缺省 15 |
|
||||
|
||||
记账口径与主节点完全一致（节点是唯一记录者、`stats` 为增量累加、上报 at-most-once），报文格式见 [节点 API 与协议](/guide/node-api) 的「数据上报协议」一节。
|
||||
|
||||
> [!NOTE]
|
||||
> 上报依赖进程存活期内的内存计数。若所用平台会把实例缩容到零，缓冲区会随实例回收丢失——上报只在实例存活期内累积。长驻部署（Docker / 二进制）不受此限。
|
||||
|
||||
## 方案二：Vercel
|
||||
|
||||
点击下方按钮一键导入仓库（部署目标为 `serverless/edgeone/cloud-functions` 目录，即 Go 边缘函数版本）：
|
||||
@@ -42,10 +58,13 @@ docker run -d --restart unless-stopped -p 8080:8080 \
|
||||
lemon-ipw
|
||||
```
|
||||
|
||||
> `--restart unless-stopped`：主进程退出时 Docker 自动拉起容器（OTA 更新失败自愈依赖它）；手动 `docker stop` 不会触发重启。
|
||||
> `--restart unless-stopped`：主进程意外退出时 Docker 自动拉起容器；手动 `docker stop` 不会触发重启。
|
||||
|
||||
配置通过挂载 `setting.json` 提供（注意挂载到容器工作目录 `/home/appuser`），也可用环境变量覆盖（`PORTS` / `CORS` / `TRUSTED_PROXIES` / `ACCESS_TOKEN` 等）。
|
||||
|
||||
> [!TIP]
|
||||
> 容器内 OTA 替换二进制意义有限（重建容器即回滚到镜像版本），如需彻底关闭可设 `NODE_OTA=false`；镜像**不含 IP 库数据**，首次启动若 `ipdb` 未关闭会现场拉取约 450MB 到容器可写层，轻量部署建议直接 `IPDB=false`。
|
||||
|
||||
**多架构**：Dockerfile 已适配 buildx——构建阶段固定在构建机原生平台交叉编译（`TARGETOS`/`TARGETARCH`），目标架构无需 QEMU 模拟。本机为其他架构构建：
|
||||
|
||||
```bash
|
||||
@@ -151,22 +170,62 @@ NODE_KEY=<注册key，与中间件 ws-keys[节点id] 一致；节点未配置 ke
|
||||
|
||||
**注意**：`NODE_ID` 必须与中间件 `APIBaseURL` / `IPLocationAPI` 池中的节点 `id` 一致，且该节点需配置 `"ws": true` 才会走 WS 通道。未连接中间件时，`ws:true` 节点的拨测会返回 502。
|
||||
|
||||
## OTA 自更新（可选）
|
||||
## 运行时配置管理（可选）
|
||||
|
||||
节点支持**自动升级**：检测到本仓库有新 Release 时，下载对应平台的二进制、**替换自身并重启**。
|
||||
节点暴露 `/v1/config`，供收集中心读写该节点**当前生效**的配置（内存值），是「控制台改配置不用登机器」的基础：
|
||||
|
||||
| 动作 | HTTP | WS | 说明 |
|
||||
|------|------|----|------|
|
||||
| 读取 | `GET /v1/config` | `config` + `action=get` | 返回生效配置快照 + `secretKeys` + `restartRequiredKeys` |
|
||||
| 修改 | `PATCH /v1/config`（`?persist=1` 写回本地文件） | `config` + `action=patch` | 只应用传入的键，其余不动 |
|
||||
| 刷新远端 | `POST /v1/config/refresh` | `config` + `action=refresh` | 重新拉 `remote-config-url` 并应用 |
|
||||
|
||||
三条重要约定：
|
||||
|
||||
- **凭据类键不回显明文**：`access-token` / `node-key` / `report-token` 在快照中为 `***`。调用方下发配置时必须剔除这些键，否则会把真值覆盖成三个星号。收集中心控制台已自动剔除。
|
||||
- **节点不自行重启**：`port` / `cors` / `ipdb` / `report-interval-seconds` / `trusted-proxies` / `node-id` / `node-key` / `access-token` 这些启动期固定的键，改动后在应答的 `restartRequired` 中如实列出，但**不会自动重启进程**——重启会中断在途服务，时机由运维 / 编排层掌握。`ws-url` 是例外：热生效，控制器按新地址多退少补。
|
||||
- **只 PATCH 内存的改动会被重启顶掉**：节点侧优先级是 远端 > 环境变量 > `setting.json`，长期生效需写回托管配置或本地文件，详见 [配置文件](/guide/config) 的「运行时配置管理」一节。
|
||||
|
||||
> [!NOTE]
|
||||
> **HTTP 管理面需要凭据**：节点未配置 `access-token` 时，`/v1/config` 与 `/v1/ota` 整组返回 `403`（此时业务接口也无鉴权，开放配置读写等于公网可改配置）。**WS 通道不受此限制**——节点是 WS 客户端，指令只来自已通过中间件 `ws-keys` 校验的连接。
|
||||
|
||||
## OTA 升级（收集中心下发，可选）
|
||||
|
||||
节点支持由收集中心下发**一次性升级任务**：下载新二进制 → 校验 → 预检 → 原子替换 → 重启，全程无需登录节点主机。
|
||||
|
||||
**触发方式**：收集中心经 WS `ota` 消息下发（HTTP 回退 `POST /v1/ota`）。请求体三选一指定下载源：
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| `version` | 按版本号下发。节点按自身平台拼资产名 `lemonipw-{goos}-{goarch}[.exe]`，到资产基址 `{assetBase}/{tag}/` 下取；`assetBase` 缺省为 GitHub Releases，自建镜像源可覆盖 |
|
||||
| `url` | 直发下载地址（完全自定义） |
|
||||
| `sha256` | 可选，提供即强校验（hex64，兼容 `sha256:` 前缀） |
|
||||
|
||||
**执行流程**：下载到与目标同分区的临时文件（保证 `rename` 原子）→ 体积下限 1MB（防错误页）→ sha256 校验 → **预检**（试运行新二进制 `-v`，确认架构匹配、可执行，在停机前拦下损坏文件）→ 当前二进制改名 `.old` → 新文件就位 → 重启。任一步失败都会回滚 `.old`。
|
||||
|
||||
**进度回传**：经 WS `ota_result` 依次回报 `accepted` → `downloading` → `verifying` → `installing` → `restarting`，失败时带 `error`。重启后连接必然断开，**最终结果由收集中心以重连注册上报的新版本号判定**（15 分钟未观测到新版本即判超时失败）。
|
||||
|
||||
**并发与开关**：
|
||||
|
||||
- 同一时刻只允许一个 OTA 任务，重复下发直接拒绝。
|
||||
- `node-ota: false`（env `NODE_OTA`）可完全禁用：节点拒绝一切 OTA 指令并回传原因。**只读文件系统 / 编排托管**（Docker Swarm、K8s 等自行管理镜像）的部署建议关闭。
|
||||
- 部署方式受限导致替换失败（如容器只读层）时，升级会失败并回滚，此时仍按传统方式人工升级。
|
||||
|
||||
手动更新（OTA 不可用时）：
|
||||
|
||||
```bash
|
||||
# 启用（环境变量，或 setting.json 的 "node-ota": "true"）
|
||||
NODE_OTA=true ./lemonipw
|
||||
# Docker：拉取新镜像后重建容器
|
||||
docker pull lemon-ipw && docker stop lemon-ipw && docker run ... lemon-ipw
|
||||
# systemd：替换二进制后重启服务
|
||||
systemctl restart lemon-ipw
|
||||
```
|
||||
|
||||
- **默认关闭**，需显式开启；远端配置（`node-ota`）也可统一开关，除非列入 `remote-ignore-config`
|
||||
- **检查时机**：启动 5 分钟后首次检查，之后每 6 小时 + 随机 0~1h 抖动
|
||||
- **major 变化不自动更新**：仅 minor/patch 升级自动跟进（如 3.1.0 → 3.2.0）；主版本变化（如 3.x → 4.x，通常含破坏性变更）会跳过并告警，需人工升级
|
||||
- **更新流程**：查询 GitHub 最新 Release → 按 `GOOS/GOARCH` 匹配资产（如 `lemonipw-linux-amd64`、`lemonipw-windows-amd64.exe`）→ 下载到同目录临时文件（经 `gh-proxy` 前缀加速，文件过小则丢弃）→ 当前二进制改名备份为 `<程序名>.old` → 新二进制就位 → 重启
|
||||
- **重启方式**：Linux/macOS 用 `exec` 原地替换进程镜像（PID 不变，systemd / Docker 无感）；Windows 另起新进程后退出当前进程
|
||||
- **失败处理**：下载/替换失败仅记录日志并继续运行，下次周期重试；替换过程中断会自动回滚到 `.old`
|
||||
- **注意事项**：
|
||||
- 二进制所在目录需**可写**（Docker 只读层或只读挂载会导致替换失败）
|
||||
- 建议保留 `.old` 备份以便手动回滚：`mv lemonipw.old lemonipw`
|
||||
- systemd 部署时若 OTA 重启未被托管，可配 `Restart=always` 兜底
|
||||
## 版本与能力上报
|
||||
|
||||
节点无论是否接入 WS，都会上报自身版本与支持的管理能力：
|
||||
|
||||
- **版本号**来自构建时注入的 `VERSION`，随 WS `register` 报文上报（字段 `version`）；纯 HTTP 节点（无 WS 连接）由收集中心探活 `GET /` 时一并取回（响应体含 `version`）。
|
||||
- **能力清单**（`capabilities`）取值为 `probe` / `report` / `config` / `ota`，用于让收集中心在下发管理指令前判断该节点能否理解——老版本节点的消息循环没有对应分支，收到管理消息会**静默忽略**，只能靠超时暴露。
|
||||
- 收集中心「节点状态」页展示每个节点的版本号，并据此判断哪些节点需要升级；节点升级部署后重新注册即为新版本。
|
||||
|
||||
能力清单的取值与三态判定规则见 [节点 API 与协议参考](/guide/node-api) 的「能力清单」一节。
|
||||
@@ -0,0 +1,207 @@
|
||||
# 节点 API 与协议参考
|
||||
|
||||
后端节点（`src/`）对外暴露的全部接口与协议。配置项说明见 [配置文件](/guide/config)，部署方式见 [后端节点部署](/guide/deploy-node)。
|
||||
|
||||
> 本文描述 `src/` 主节点。边缘函数版本（`serverless/edgeone/`）是**精简形态**：只有 `/v1/*` 探测端点与 `GET /`（仅返回 `{"status":"ok"}`，不回报版本与能力），没有 WS 通道、管理接口与 OTA；但同样支持 HTTP 数据上报，见下文「数据上报协议」。
|
||||
|
||||
## 鉴权总则
|
||||
|
||||
| 通道 | 鉴权方式 | 未配置凭据时 |
|
||||
|------|----------|--------------|
|
||||
| 业务探测 `/v1/*` | `access-token` 非空时校验 `Authorization: Bearer <access-token>`，不符返回 `401` | 不启用鉴权，公开可访问 |
|
||||
| 健康检查 `/` | 无 | — |
|
||||
| 管理接口 `/v1/config`、`/v1/ota`（HTTP） | 同业务接口，复用 `tokenCheck` | **整组关闭**，一律返回 `403`（节点未配 `access-token` 时业务接口本身也无鉴权，暴露配置读写等于公网可改配置） |
|
||||
| WS 通道 | 中间件 `ws-keys` 校验注册报文 | WS **常开**：节点是客户端，指令只来自已通过中间件校验的连接，与节点是否配 `access-token` 无关 |
|
||||
|
||||
> 结论：**HTTP 管理面是"有凭据才开"的**；只想用 WS 通道管理节点时，节点无需配置 `access-token`。
|
||||
|
||||
---
|
||||
|
||||
## 一、健康检查
|
||||
|
||||
```
|
||||
GET / → {"status":"ok","version":"v1.2.3","capabilities":["probe","report","config","ota"]}
|
||||
```
|
||||
|
||||
无鉴权、不计入统计。除存活外同时回报**版本号**与**能力清单**：收集中心对纯 HTTP 节点（无 WS 连接）探活时一并取回，用于节点状态页展示版本、以及下发管理指令前判断该节点能否理解对应指令。
|
||||
|
||||
---
|
||||
|
||||
## 二、业务探测接口
|
||||
|
||||
全部挂在 `/v1` 组下，共用 CORS + 可选 `tokenCheck` + 统计中间件（`nodeReportMiddleware`，见下文「数据上报」）。
|
||||
|
||||
| 方法 | 路径 | 参数 | 说明 |
|
||||
|------|------|------|------|
|
||||
| GET | `/v1/detail/*url` | 目标 URL（路径传入，自动补全协议） | 网站探测明细：DNS/TCP/HTTP 各阶段耗时、状态码、页面体积、下载速度、可达性；双栈分别返回 |
|
||||
| GET | `/v1/ssl/*url` | 目标 URL | SSL 证书检查：剩余有效天数、颁发/主体、TLS 版本、是否过期；双栈分别返回 |
|
||||
| GET | `/v1/speed/:version/*url` | `version` = `v4` / `v6`，目标 URL | 下载测速 |
|
||||
| GET | `/v1/tcping/:ip` | `port`（默认 80）、`count`（默认 4，上限 20） | TCP 连通性与 RTT 统计 |
|
||||
| GET | `/v1/dns/:type/*domain` | `type` ∈ `a`/`aaaa`/`cname`/`mx`/`ns`/`ptr`/`srv`/`txt`/`caa` | DNS 记录查询（`dns-server` 支持主从 failover 与 DoH） |
|
||||
| GET | `/v1/dnssec/:domain` | 域名 | DNSSEC 链式验证（`dnssec-server`，留空沿用 `dns-server`） |
|
||||
| GET | `/v1/whois/:domain` | 域名 | Whois 注册信息 |
|
||||
| GET | `/v1/location/:ip` | IP | 多源 IP 归属地聚合（见 [功能总览](/info/features)） |
|
||||
| GET | `/v1/location` | 无（取请求方 IP） | 查询访问者自身归属地；配置 `trusted-proxies` 后只信任这些代理转发的 `X-Forwarded-For` |
|
||||
| GET | `/v1/asn/:ip` | IP | ASN 查询（三套 ASN 库 + ASN Whois 解析） |
|
||||
|
||||
**条件注册**：`/v1/location/*`、`/v1/asn/:ip` 仅在 `ipdb` 未关闭时注册——IP 库未加载时这些接口无意义。
|
||||
|
||||
**单栈模式**：`single-stack` 配为 `ipv4` / `ipv6` 时只跑对应栈，另一栈直接返回 `Skipped due to SINGLE_STACK=...`，不发起无意义的探测与超时。
|
||||
|
||||
**SSRF 防护**：`block-private-ips` 开启时，`detail` / `ssl` 对解析到内网/私有地址的目标直接返回伪造结果，出站客户端同时拒绝连接私有 IP、禁止跨跳重定向。
|
||||
|
||||
---
|
||||
|
||||
## 三、管理接口
|
||||
|
||||
### 3.1 运行时配置 `/v1/config`
|
||||
|
||||
读写节点**当前生效**的配置（内存值），与收集中心的「托管配置」是两回事——后者是节点启动时拉的远端配置，见 [配置文件](/guide/config) 的「运行时配置管理」一节。
|
||||
|
||||
| 方法 | 路径 | 作用 |
|
||||
|------|------|------|
|
||||
| GET | `/v1/config` | 返回当前生效配置快照 + `secretKeys` + `restartRequiredKeys` + `remoteProtectedKeys` |
|
||||
| PATCH | `/v1/config` | 按下发 map 逐键应用；`?persist=1` 时同时写回本地 `setting.json` |
|
||||
| POST | `/v1/config/refresh` | 重新拉取 `remote-config-url` 并应用（远端是持久来源，不写回本地文件） |
|
||||
|
||||
行为要点：
|
||||
|
||||
- **凭据遮蔽**：`access-token` / `node-key` / `report-token` 在 GET 快照里回显 `***`，不泄露明文；下发时原样提交会把真值覆盖成三个星号，因此调用方必须**剔除这些键**（收集中心控制台已自动剔除）。
|
||||
- **`access-token` / `report-token` 不随远端配置覆盖**：这两项硬编码在保护名单 `configRemoteProtectedKeys` 里，`remote-config-url`（含收集中心托管配置）下发时会被跳过，并在 `refresh` 应答的 `protectedIgnored` 与节点日志里列出被跳过的键。**只约束远端下发**，本地 `PATCH` 照常可改。理由与清单见 [配置文件](/guide/config) 的「远端配置」一节。
|
||||
- **未持久化的改动会被重启顶掉**：节点侧优先级是 远端 > 环境变量 > `setting.json`，只 PATCH 内存时重启即回到旧值。需要长期生效应 `refresh`（改远端配置）或把改动合并进托管配置——受保护凭据例外，只能落到本地 ENV / `setting.json`。
|
||||
- **`restartRequired` 只如实回报**：`port` / `cors` / `ipdb` / `report-interval-seconds` / `trusted-proxies` / `node-id` / `node-key` / `access-token` 这些启动期固定的键，改动后节点**不会自行重启**，只在应答里列出键名，重启时机交给运维。
|
||||
- **`ws-url` 例外，热生效**：WS 客户端控制器按新地址"多退少补"，无需重启。 `node-ota` 同样即时生效：该开关在每次下发 OTA 指令时才读取，不属需重启类键。
|
||||
|
||||
### 3.2 OTA 升级 `/v1/ota`
|
||||
|
||||
收集中心 HTTP 回退通道（WS 在线时优先走 WS `ota` 消息）。
|
||||
|
||||
```
|
||||
POST /v1/ota
|
||||
{
|
||||
"requestId": "可选，回执关联用",
|
||||
"version": "v1.4.0", // 二选一：按版本号下发
|
||||
"url": "https://.../lemonipw-linux-amd64", // 二选一：直发下载地址
|
||||
"assetBase": "https://.../releases/download", // 可选，配合 version 使用
|
||||
"sha256": "可选，hex64（兼容 sha256: 前缀），提供则强校验"
|
||||
}
|
||||
→ 202 {"ok":true,"started":true}
|
||||
```
|
||||
|
||||
响应仅为**受理回执**（下载可能数分钟，HTTP 无进度通道）。执行阶段见 [后端节点部署](/guide/deploy-node) 的「OTA 升级」一节。
|
||||
|
||||
---
|
||||
|
||||
## 四、WebSocket 协议
|
||||
|
||||
节点作为 **WS 客户端**连接收集中心（或独立中间件）的 `/ws` 端点：`ws(s)://<中间件>:<ws-port>/ws`。`ws-url` 支持逗号分隔多个地址，**同时连接全部（多活）**，由 per-URL 连接控制器统一收敛。
|
||||
|
||||
### 4.1 消息信封
|
||||
|
||||
```json
|
||||
{ "type": "...", "nodeId": "...", "ts": 1710000000, "data": { } }
|
||||
```
|
||||
|
||||
### 4.2 消息类型
|
||||
|
||||
**节点 → 中间件**
|
||||
|
||||
| type | data 字段 | 作用 |
|
||||
|------|-----------|------|
|
||||
| `register` | `nodeId` / `key`（配了 ws-keys 时必填）/ `version` / `capabilities[]` | 注册接入，建立身份 |
|
||||
| `ping` | — | 心跳，每 10s |
|
||||
| `pong` | — | 应答中间件 ping |
|
||||
| `probe_result` | `requestId` / `status` / `body` | 拨测结果回传 |
|
||||
| `report` | 统计 + 拨测明细（同 `/report` body） | 周期数据上报 |
|
||||
| `config_result` | `requestId` / `action` / `ok` / `error` / 配置快照 / `applied` / `unknown` / `restartRequired` / `persisted` | 配置指令应答 |
|
||||
| `ota_result` | `requestId` / `ok` / `stage` / `error` | OTA 进度与失败原因 |
|
||||
|
||||
**中间件 → 节点**
|
||||
|
||||
| type | data 字段 | 作用 |
|
||||
|------|-----------|------|
|
||||
| `register_ok` | `heartbeatSeconds` | 注册通过，告知心跳周期 |
|
||||
| `register_error` | `code` / `command` | 注册被拒（如 key 不匹配），30s 后重试 |
|
||||
| `probe` | `requestId` / `apiType` / `raw` / `query` / `scheduler` | 下发拨测 |
|
||||
| `config` | `requestId` / `action` / `config` / `persist` | 下发配置指令 |
|
||||
| `ota` | `requestId` / `url` 或 `version`+`assetBase` / `sha256` | 下发升级任务 |
|
||||
| `ping` | — | 中间件心跳（节点回 `pong`） |
|
||||
| `status` | 统计字段 | 中间件状态，节点仅记录日志 |
|
||||
|
||||
### 4.3 心跳与重连
|
||||
|
||||
- 节点每 **10s** 发 `ping`；发送连续失败 **3 次**判定通道不可用，主动断开并在 **3s** 后重连。
|
||||
- 注册被拒（key 错误等）时 **30s** 后重试。
|
||||
- 中间件侧每 20s 发 `ping` + `status`，空闲 **75s** 未收到任何报文即剔除该节点并记离线事件。
|
||||
|
||||
### 4.4 OTA 进度阶段
|
||||
|
||||
节点经 `ota_result` 依次回报：`accepted` → `downloading` → `verifying` → `installing` → `restarting`；任一阶段失败即终止并带 `error`。重启后连接必然断开，"最终结果"由收集中心以**重连注册上报的新版本号**判定。
|
||||
|
||||
---
|
||||
|
||||
## 五、数据上报协议
|
||||
|
||||
统计与拨测明细**由节点自己上报**，收集中心不在转发路径上采集——节点是唯一记录者，不存在双算。
|
||||
|
||||
| 通道 | 条件 | 形式 |
|
||||
|------|------|------|
|
||||
| WS `report` 消息 | 已连接中间件 | 向所有在线中间件广播 |
|
||||
| HTTP `POST <report-url>/report` | WS 未启用或全部掉线 | 携带 `Authorization: Bearer <report-token>` |
|
||||
|
||||
```json
|
||||
{
|
||||
"instance": "cn-jiangsu",
|
||||
"stats": [
|
||||
{ "nodeId": "cn-jiangsu", "apiType": "tcping",
|
||||
"total": 1, "errors": 0, "latencySumMs": 12, "latencyMaxMs": 12, "minute": 29821676 }
|
||||
],
|
||||
"probes": [
|
||||
{ "nodeId": "cn-jiangsu", "apiType": "tcping", "raw": "qq.com",
|
||||
"status": 200, "latencyMs": 33, "body": { } }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
- 上报周期由 `report-interval-seconds` 控制（缺省 15s）。
|
||||
- `stats` 是**增量**，收集器按 `(分钟 × 节点 × apiType)` 累加；上报为 at-most-once（失败丢弃并记日志，不重试——重试会双算）。
|
||||
- 单次报文上限 500 条 stats / 500 条 probes / 4MB；超出或队列（缓冲 2048）打满时丢弃并计数。
|
||||
- **只上报第一方观测**：节点自己处理的请求才记账，不转播从别处收到的数据。
|
||||
- `minute` 是 unix 分钟桶（按节点时钟）；上报方传 `0` 表示"由收集器按自身时钟入桶"，收集端另有"不接受未来 1 小时以外"的漂移容忍。
|
||||
- **部署形态差异**：`serverless/edgeone/` 版本不维持长连接（无 WS 客户端），只走 HTTP `POST /report` 一条通道，配置方式见 [后端节点部署](/guide/deploy-node) 的 EdgeOne 一节。
|
||||
|
||||
---
|
||||
|
||||
## 六、能力清单（capabilities）
|
||||
|
||||
节点在 `register` 报文与 `GET /` 中上报自身支持的管理能力，取值为 `probe` / `report` / `config` / `ota` 的数组。
|
||||
|
||||
收集中心据此做**三态判定**，绝不能把"未知"当作"不支持"：
|
||||
|
||||
| 上报情况 | 收集中心行为 |
|
||||
|----------|--------------|
|
||||
| 清单含该能力 | 正常下发对应指令 |
|
||||
| 清单明确不含 | 该能力确实没有：立刻拒绝，不发起指令、不等超时 |
|
||||
| 清单为空（未上报） | 老版本节点，能力**未知**：仍尝试下发；超时后主动探活，区分"节点活着但静默忽略（程序过旧）"与"连接已僵死" |
|
||||
|
||||
新增一类管理指令时应在此追加能力标识，并保持取值稳定（收集中心按字符串比对）。
|
||||
|
||||
---
|
||||
|
||||
## 七、缓存与并发
|
||||
|
||||
业务探测结果在节点侧缓存，避免同 key 洪打把上游打崩：
|
||||
|
||||
| 缓存 | 键 | TTL |
|
||||
|------|-----|-----|
|
||||
| `detail` | 归一化 URL | 5 分钟 |
|
||||
| `ssl` | URL | 5 分钟 |
|
||||
| `speed` | `url:version` | 5 分钟 |
|
||||
| `tcping` | `host:port:count` | 5 分钟 |
|
||||
| `whois` | 域名 | 5 分钟 |
|
||||
| `asn whois` | `AS<asn>` | 5 分钟 |
|
||||
| Bilibili 归属地（在线 API） | IP | 24 小时 |
|
||||
|
||||
- **失败结果 30s 后删除**：探测失败（如目标不可达）不缓存整 5 分钟，避免故障恢复后长时间返回旧结论。
|
||||
- **singleflight 合并**：`detail` / `ssl` / `tcping` / `speed` 的并发同 key 请求合并为一次真实探测。
|
||||
- **定时清扫**：每 10 分钟清理过期缓存条目与 Bilibili 缓存，防止只靠"同 key 重访才淘汰"时内存无限增长。
|
||||
@@ -0,0 +1,361 @@
|
||||
# 公开 API（/api/v1）
|
||||
|
||||
收集中心（`ipw-boce` 中间件）对外提供的**程序化接口**，资源按 REST 规范组织：名词复数、裸资源 + HTTP 状态码、无信封。
|
||||
|
||||
- **面向任何持有凭据的调用方**：控制台用户生成一枚个人 API Token 即可用，适合脚本、巡检、看板、CI 取数。
|
||||
- 与内部 `/admin/*` 共用**同一套鉴权与可见性**，只是对外形态更规范。
|
||||
- 拨测**节点**自身的接口不在这里，见 [节点 API 与协议](/guide/node-api)。
|
||||
|
||||
> 下文 `<collector>` 指收集中心实例的 origin，例如 `https://collector.example.com`。
|
||||
|
||||
## 端点一览
|
||||
|
||||
| 方法 | 路径 | 作用 |
|
||||
|------|------|------|
|
||||
| GET | `/api/v1/tasks` | 任务列表（分页 + 标签过滤） |
|
||||
| GET | `/api/v1/tasks/:id` | 单任务详情 |
|
||||
| GET | `/api/v1/tasks/:id/sla` | 任务 SLA 聚合（顶层汇总 + 按节点明细） |
|
||||
| GET | `/api/v1/probes` | 拨测明细（分页 + 过滤） |
|
||||
| POST | `/api/v1/probes` | 一键拨测（同步聚合；本层唯一的写操作） |
|
||||
| GET | `/api/v1/nodes` | 节点池简表（脱敏） |
|
||||
| GET | `/api/v1/usage` | 用量聚合 |
|
||||
|
||||
---
|
||||
|
||||
## 快速开始
|
||||
|
||||
```bash
|
||||
# 1) 取一枚个人 API Token（控制台「个人资料 → 个人 API Token」同效）
|
||||
curl -sX POST "https://<collector>/admin/me/token" -H "Authorization: Bearer <你的 JWT>"
|
||||
# → {"token":"ipt_9f3c...e1a7","hint":"e1a7","createdAt":"2026-09-13T07:00:00Z"}
|
||||
|
||||
# 2) 调用公开 API
|
||||
curl -s -H "Authorization: Bearer ipt_9f3c...e1a7" \
|
||||
"https://<collector>/api/v1/tasks?page=1&pageSize=20"
|
||||
```
|
||||
|
||||
- Token **明文只在生成时返回一次**（`token` 字段）；库里只存 bcrypt 哈希，`hint` 是末 4 位供列表辨识。
|
||||
- 再次 `POST /admin/me/token` 会**立即作废旧 Token**；`DELETE /admin/me/token` 吊销。
|
||||
- 静态 `admin-token` 没有账号，不能生成个人 Token（返回 400）。
|
||||
|
||||
---
|
||||
|
||||
## 鉴权
|
||||
|
||||
三轨，与 `/admin/*` 完全一致：
|
||||
|
||||
| 凭据 | 特征 | 身份 | 适用场景 |
|
||||
|------|------|------|----------|
|
||||
| 个人 API Token | `ipt_` 前缀 | 其账号（角色随账号） | 程序化访问的推荐方式，可随时吊销 |
|
||||
| JWT | 无前缀 | 其账号（角色随账号） | `POST /admin/login` 签发，有过期时间 |
|
||||
| 静态 `admin-token` | 无前缀 | 恒为 admin（`uid=0`） | 向后兼容；无归属，脚本慎用 |
|
||||
|
||||
请求头固定 `Authorization: Bearer <凭据>`。失败一律 `401`：
|
||||
|
||||
| message | 场景 |
|
||||
|---------|------|
|
||||
| `missing bearer token` | 未携带 `Authorization: Bearer ` 前缀 |
|
||||
| `invalid or revoked token` | `ipt_` 开头但库中查不到（未生成 / 已吊销 / 被轮换） |
|
||||
| `invalid credentials` | 其它凭据无效 |
|
||||
|
||||
> **API Token 等价于其账号登录**：权限随账号角色。普通用户只看得见自己的资源。
|
||||
> 若收集中心既没配 `admin-token` 也没启用 JWT，则管理面**不鉴权**（仅限内网/联调部署，勿用于公网）。
|
||||
|
||||
---
|
||||
|
||||
## 通用约定
|
||||
|
||||
### 错误体
|
||||
|
||||
非 2xx 统一为：
|
||||
|
||||
```json
|
||||
{ "error": { "code": "not_found", "message": "task not found" } }
|
||||
```
|
||||
|
||||
| code | HTTP | 含义 |
|
||||
|------|------|------|
|
||||
| `unauthorized` | 401 | 缺凭据 / 凭据无效或已吊销 |
|
||||
| `forbidden` | 403 | 凭据有效但无权访问该资源（如别人的任务） |
|
||||
| `not_found` | 404 | 资源不存在（任务、分享令牌） |
|
||||
| `bad_request` | 400 | 参数非法 |
|
||||
| `rate_limited` | 429 | 请求过于频繁（仅免登录的公开状态接口） |
|
||||
| `internal` | 500 | 服务端错误 |
|
||||
|
||||
### 分页
|
||||
|
||||
两套参数，**互不通用**：
|
||||
|
||||
| 端点 | 参数 | 缺省 | 边界处理 | 返回字段 |
|
||||
|------|------|------|----------|----------|
|
||||
| `/tasks` | `page`（1 起）、`pageSize`（别名 `limit`） | 1 / 50 | `page<1` → 1；`pageSize` 夹在 1~200 | `{items,total,page,pageSize}` |
|
||||
| `/probes` | `limit`、`offset` | 50 / 0 | `limit` 夹在 1~500；`offset<0` → 0 | `{items,total,limit,offset}` |
|
||||
|
||||
越界值是**夹到边界**而非报错（`pageSize=9999` → 200，`page=0` → 1）。`total` 为符合过滤条件的总数，与当前页无关。两个列表均按 `id` 倒序（最新在前）。
|
||||
|
||||
### 可见性
|
||||
|
||||
| 角色 | 任务 | 拨测明细 |
|
||||
|------|------|----------|
|
||||
| admin / 静态 token | 全量 | 全量 |
|
||||
| 普通用户 | 仅 `ownerId` = 本人 | 定时样本按「本人任务」归属、业务拨测按发起者 |
|
||||
|
||||
访问**单个**他人的任务返回 `403`（而非 404），便于区分"不存在"与"不是你的"。
|
||||
|
||||
### 限流
|
||||
|
||||
`/api/v1` **不挂限流**——限流只作用于转发口 `/v1` 与 `/middleware`。唯一例外是免登录的公开状态接口（见文末）。
|
||||
|
||||
---
|
||||
|
||||
## 一、任务
|
||||
|
||||
### 1.1 `GET /api/v1/tasks`
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `page` | 否 | 页码，1 起，缺省 1 |
|
||||
| `pageSize` | 否 | 每页条数，缺省 50，上限 200（`limit` 为别名） |
|
||||
| `tag` | 否 | 按标签**子串**过滤（标签以逗号分隔存储） |
|
||||
|
||||
```json
|
||||
{
|
||||
"items": [
|
||||
{
|
||||
"id": 5, "name": "官网可用性", "ownerId": 2, "ownerUsername": "alice",
|
||||
"enabled": true, "apiType": "detail", "target": "example.com", "stack": "",
|
||||
"recordType": "", "nodeScope": "all", "nodeIds": "", "intervalSec": 60,
|
||||
"slowMs": 800, "expectStatus": "2xx", "bothProtocols": false,
|
||||
"requireAllStacks": true, "certExpiredDown": false, "notifyRecover": true,
|
||||
"quietHours": "23:00-07:00", "hideTarget": false, "tags": "prod,官网",
|
||||
"updatedAt": "2026-09-13T06:12:00Z"
|
||||
}
|
||||
],
|
||||
"total": 1, "page": 1, "pageSize": 50
|
||||
}
|
||||
```
|
||||
|
||||
任务对象字段：
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `id` | number | 任务 id |
|
||||
| `name` | string | 任务名 |
|
||||
| `ownerId` | number | 所有者用户 id；`0` = 无归属（静态 token 建的旧任务） |
|
||||
| `ownerUsername` | string | 派生字段：所有者用户名（无归属为空串） |
|
||||
| `enabled` | bool | 是否启用调度 |
|
||||
| `apiType` | string | `tcping` / `speed` / `ssl` / `detail` / `dns` |
|
||||
| `target` | string | `detail`/`ssl`/`dns` = 域名；`tcping` = `host[:port]`；`speed` = `v4/`或`v6/`+URL |
|
||||
| `stack` | string | `""`(按类型) / `v4` / `v6`，仅 `speed` 想固定单栈时用 |
|
||||
| `recordType` | string | `dns` 专用：`a`/`aaaa`/`cname`/`mx`/`ns`/`ptr`/`srv`/`txt`/`caa`（缺省 `a`） |
|
||||
| `nodeScope` | string | `all`（全池）/ `custom`（指定） |
|
||||
| `nodeIds` | string | `custom` 时的逗号分隔节点 id；`all` 忽略 |
|
||||
| `intervalSec` | number | 调度间隔（秒），最小 10 |
|
||||
| `slowMs` | number | 慢阈值（ms），超过计一次"未达标"；0 = 不启用 |
|
||||
| `expectStatus` | string | 期望状态码：`"2xx"` 或 `"200"` / `"200,301,302"` |
|
||||
| `bothProtocols` | bool | `detail`：http 与 https 都要命中才算成功 |
|
||||
| `requireAllStacks` | bool | 双栈全通才算该节点可用 |
|
||||
| `certExpiredDown` | bool | `ssl`：证书过期视为不可用 |
|
||||
| `notifyRecover` | bool | 从 down 恢复时也通知一次 |
|
||||
| `quietHours` | string | 免打扰时段 `"HH:MM-HH:MM"`（服务器本地时区，支持跨零点） |
|
||||
| `hideTarget` | bool | 公开状态页隐藏探测目标 |
|
||||
| `tags` | string | 逗号分隔标签 |
|
||||
| `updatedAt` | string | 最后更新时间（RFC3339） |
|
||||
|
||||
> 分享令牌 `shareToken` **不在 JSON 里**（`json:"-"`），只经管理接口读写。
|
||||
|
||||
### 1.2 `GET /api/v1/tasks/:id`
|
||||
|
||||
返回单个任务对象（字段同 1.1）。
|
||||
|
||||
| 状态 | 场景 |
|
||||
|------|------|
|
||||
| `404 not_found` | `task not found` |
|
||||
| `403 forbidden` | `not your task`（普通用户访问他人任务） |
|
||||
|
||||
### 1.3 `GET /api/v1/tasks/:id/sla?hours=24`
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `hours` | 否 | 统计窗口（小时），缺省 24，夹在 1 ~ 2160（90 天） |
|
||||
|
||||
```json
|
||||
{
|
||||
"taskId": 5, "hours": 24,
|
||||
"window": { "from": "2026-09-12T07:00:00Z", "to": "2026-09-13T07:00:00Z" },
|
||||
"samples": 1440, "up": 1432, "down": 8,
|
||||
"availability": 99.44, "avgMs": 128, "maxMs": 2103, "p95Ms": 402,
|
||||
"byNode": [
|
||||
{ "nodeId": "cn-jiangsu", "up": 720, "down": 0, "availability": 100,
|
||||
"avgMs": 96, "p95Ms": 180, "latestMs": 88 }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
- **只统计 `source=sched` 的定时样本**：节点自主上报与手动一键拨测不进 SLA（详见 [节点 API 与协议](/guide/node-api) 的「数据上报协议」一节）。
|
||||
- 判定配置（`expectStatus` / `bothProtocols` / `requireAllStacks` / `certExpiredDown`）在**读取时**生效，改配置立刻作用于历史样本，无需回填重算。
|
||||
- `availability` 是**百分数**（0~100，两位小数）。两处口径略有差异：
|
||||
- 顶层 `availability` = `up/(up+down)`；
|
||||
- `byNode[].availability` = `up/samples`（分母含无法判定的 `invalid` 样本，故通常略低）。
|
||||
- `byNode[].latestMs` 是该节点窗口内最新一条可达样本的延迟。
|
||||
|
||||
---
|
||||
|
||||
## 二、拨测明细
|
||||
|
||||
### 2.1 `GET /api/v1/probes`
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `node` | 否 | 节点 id 精确匹配 |
|
||||
| `type` | 否 | `apiType` 精确匹配（`detail`/`ssl`/`dns`/`tcping`/`speed` …） |
|
||||
| `source` | 否 | `sched`（定时）或 `biz`（业务拨测）；**其它取值返回 400** |
|
||||
| `since` | 否 | 起始时间，**RFC3339**（如 `2026-09-13T00:00:00Z`），非法返回 400 |
|
||||
| `limit` | 否 | 缺省 50，上限 500 |
|
||||
| `offset` | 否 | 缺省 0 |
|
||||
|
||||
```json
|
||||
{
|
||||
"items": [
|
||||
{ "nodeId": "cn-jiangsu", "apiType": "tcping", "raw": "example.com:443",
|
||||
"status": 200, "latencyMs": 33, "source": "sched", "error": "",
|
||||
"createdAt": "2026-09-13T07:01:12Z" }
|
||||
],
|
||||
"total": 1440, "limit": 50, "offset": 0
|
||||
}
|
||||
```
|
||||
|
||||
- 为控制体积，`items` **精简且不含 `body`**（原始响应体）。需要看原始 body 请用控制台「拨测明细」页。
|
||||
- 不传 `source` 时按可见性返回全部来源：admin 含节点上报的 `ws`/`http` 样本，普通用户仅自己的 `sched` + `biz`。
|
||||
- **`source=biz` 的边界**：admin 身份下等价于「非 `sched` 的全部来源」（含节点上报的 `ws`/`http`）；普通用户下严格等于「自己发起的 `biz`」。要精确取节点上报样本，请按 `node` / `type` 过滤。
|
||||
|
||||
### 2.2 `POST /api/v1/probes`
|
||||
|
||||
一键拨测：对节点池（或指定节点）并发发起一轮探测，**同步**聚合后一次性返回。这是公开 API 上唯一的写操作——结果会落库（`source=biz`）并归属 Token 主人。
|
||||
|
||||
请求体：
|
||||
|
||||
```json
|
||||
{
|
||||
"apiType": "detail",
|
||||
"raw": "example.com",
|
||||
"query": { "port": "443" },
|
||||
"nodes": ["cn-jiangsu", "cn2-sichuan"]
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `apiType` | 是 | 探测类型；`location`/`asn` 走 IP 定位池，其余走 API 节点池 |
|
||||
| `raw` | 是 | 探测目标；前导 `/` 会被去掉 |
|
||||
| `query` | 否 | 透传给节点的查询参数对象（空值项被忽略） |
|
||||
| `nodes` | 否 | 限定节点 id 列表；缺省 = 池内全部节点 |
|
||||
|
||||
```json
|
||||
{
|
||||
"apiType": "detail", "raw": "example.com",
|
||||
"targeted": 2, "ok": 2, "failed": 0, "unknown": [], "persisted": 2,
|
||||
"results": [
|
||||
{ "nodeId": "cn-jiangsu", "label": "中国 江苏 移动", "channel": "http",
|
||||
"status": 200, "latencyMs": 412, "body": { "ipv4": { "http_status_code": 200 } } },
|
||||
{ "nodeId": "cn2-sichuan", "label": "中国 四川 电信", "channel": "ws",
|
||||
"status": 0, "latencyMs": 15000, "error": "probe timeout" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
- **HTTP 200 即便部分节点失败**：单节点成败看 `results[i].status` 与 `results[i].error`。`results[i].channel` 为 `ws` / `http`，表示该节点实际走的通道。
|
||||
- `unknown`：`nodes` 里指定了但不在池中的节点 id。
|
||||
- `persisted`：实际落库条数。仅 `detail`/`ssl`/`dns`/`tcping`/`speed` 这类拨测型入库；`whois`/`dnssec`/`location`/`asn` 等诊断型不入库。
|
||||
- **400** 的几种情况：池为空、`nodes` 全部不在池中（错误信息里会列出已知节点 id）、`apiType` 与 `raw` 缺失。
|
||||
- 这是**并发同步**调用，耗时取决于最慢的节点（WS 通道有独立超时）。客户端超时应放宽到 **30s 以上**。
|
||||
|
||||
---
|
||||
|
||||
## 三、节点与用量
|
||||
|
||||
### 3.1 `GET /api/v1/nodes`
|
||||
|
||||
节点池简表，**脱敏**——只有启用中的节点，不含上游地址。
|
||||
|
||||
```json
|
||||
{
|
||||
"items": [
|
||||
{ "nodeId": "cn-jiangsu", "label": "中国 江苏 移动",
|
||||
"ws": false, "pools": "api,location", "stack": "", "online": true, "version": "v1.4.0" }
|
||||
],
|
||||
"total": 1
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| `ws` | 该节点拨测是否走 WS 通道 |
|
||||
| `pools` | 归属池，逗号分隔：`api` / `location` / `api,location` |
|
||||
| `stack` | 仅 `api` 池有意义：`DualStack` / `IPv4` / `IPv6` |
|
||||
| `online` | 是否在线（来自节点在线快照） |
|
||||
| `version` | 节点上报的版本号；从未上线则为 `""` |
|
||||
|
||||
### 3.2 `GET /api/v1/usage?hours=24`
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `hours` | 否 | 统计窗口（小时），缺省 24，夹在 1 ~ 2160 |
|
||||
|
||||
```json
|
||||
{
|
||||
"hours": 24, "total": 1440, "up": 1432, "down": 8, "invalid": 0,
|
||||
"byType": [
|
||||
{ "apiType": "detail", "total": 1200, "up": 1194, "down": 6, "invalid": 0, "avgMs": 128 }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
- 口径：admin = 全站（`sched` + `biz` 样本）；普通用户 = 自己任务的定时样本 + 自己发起的业务拨测。
|
||||
- `byType` 按 `total` 倒序；`invalid` = 无法判定的样本，不计入成败。
|
||||
|
||||
---
|
||||
|
||||
## 附：免登录的公开状态接口
|
||||
|
||||
SLA 任务的**分享组**对外开放状态页，无需任何凭据。它不属于 `/api/v1`（不挂鉴权），但因同样面向公众而并列在此。
|
||||
|
||||
| 方法 | 路径 | 说明 |
|
||||
|------|------|------|
|
||||
| GET | `/s/:token` | 只读状态页（Vue SPA，30s 自刷新；需托管侧提供 SPA fallback） |
|
||||
| GET | `/api/public/status/:token` | 同数据的 JSON（页面用），参数 `hours` 同上 |
|
||||
|
||||
```json
|
||||
{
|
||||
"token": "a1b2c3", "hours": 24,
|
||||
"tasks": [
|
||||
{ "taskId": 5, "name": "官网可用性", "apiType": "detail", "target": "example.com",
|
||||
"hours": 24, "samples": 1440, "up": 1432, "down": 8, "availability": 99.44,
|
||||
"avgMs": 128, "maxMs": 2103, "p95Ms": 402,
|
||||
"byNode": [ { "nodeId": "cn-jiangsu", "up": 720, "down": 0,
|
||||
"availability": 100, "avgMs": 96, "p95Ms": 180, "latestMs": 88 } ],
|
||||
"series": [ { "time": "2026-09-13T07:00:00Z", "minute": 29758260, "samples": 10,
|
||||
"up": 10, "down": 0, "availability": 100, "avgMs": 120.5 } ] }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
- 同一令牌的任务**同页展示**（令牌即"分享组"）；令牌为 3~32 位小写字母/数字/连字符，可自定义，管理接口见控制台「SLA 监控 → 分享」。
|
||||
- **暴露面刻意收窄**：只有任务名/类型/目标 + 窗口聚合与延迟时序（`series` 为每轮多节点平均；多节点时另给 `nodeSeries` 分节点曲线）；不含 owner、上游地址、内部字段。任务勾选 `hideTarget` 时，`target` 字段**整体不出现在 JSON 里**。
|
||||
- 令牌未知或已关闭分享 → `404 not_found`（`invalid share link`）。
|
||||
- **防枚举限流**：每 IP 60 次/分，超限 `429 rate_limited`（随机令牌仅 24-bit 熵，必须有这层保护）；响应带 `Cache-Control: no-store`。
|
||||
|
||||
---
|
||||
|
||||
## 排错
|
||||
|
||||
| 现象 | 原因与处理 |
|
||||
|------|------------|
|
||||
| `401 missing bearer token` | 没带 `Authorization: Bearer ` 前缀（注意 `Bearer` 后有一个空格） |
|
||||
| `401 invalid or revoked token` | Token 被重新生成过或已吊销 → 重新生成一枚 |
|
||||
| `403 not your task` | 用普通用户的 Token 去读别人的任务 |
|
||||
| `400 source 只能是 sched / biz` | `?source=` 传了其它取值 |
|
||||
| `400 since 须为 RFC3339 时间` | 时间必须带时区，如 `2026-09-13T00:00:00Z` |
|
||||
| `POST /probes` 400 且提示 known nodes | `nodes` 里的 id 都不在节点池 → 先用 `GET /api/v1/nodes` 取真实 id |
|
||||
| `POST /probes` 耗时很久 | 同步聚合要等最慢节点 → 客户端超时设到 30s 以上 |
|
||||
| 列表查不到自己刚建的任务 | 列表按 `id` 倒序；确认用的是同一个账号的 Token（普通用户只见自己的） |
|
||||
@@ -26,6 +26,10 @@ features:
|
||||
details: 多节点并发查询，支持 A / AAAA / CNAME / MX / TXT / NS / SRV / PTR / CAA 等记录类型，并提供 DNSSEC 链式信任验证。
|
||||
- title: SSRF 防护
|
||||
details: 自动拦截对内网 / 私有 IP 的出站请求，校验安全跳转，避免服务端请求伪造风险。
|
||||
- title: 分布式节点与 WS 通道
|
||||
details: 节点可作为客户端接入中间件，拨测请求经 WebSocket 下发与回传；支持多地址同时连接（多活）、断线自动重连，`ws-url` 改动热生效无需重启。
|
||||
- title: 远程运维
|
||||
details: 节点上报版本号与能力清单，收集中心展示版本、远程读写运行时配置，并可下发一次性 OTA 升级任务（下载 → 校验 → 替换 → 重启，失败自动回滚）。
|
||||
- title: 多平台部署
|
||||
details: 支持二进制，Docker，乃至AWS Lambda，EdgeOne Makers，Vercel和阿里云函数计算
|
||||
---
|
||||
@@ -0,0 +1,79 @@
|
||||
# 功能总览
|
||||
|
||||
后端节点（`src/`，Go + Gin）承担全部检测能力，可在任意地区部署组成去中心化测试网络。接口清单见 [节点 API 与协议参考](/guide/node-api)。
|
||||
|
||||
## 探测能力矩阵
|
||||
|
||||
| 能力 | 路由 | 依赖 | 说明 |
|
||||
|------|------|------|------|
|
||||
| 网站探测明细 | `/v1/detail/*url` | 出站 HTTP（v4/v6 双客户端） | DNS 解析、TCP 连接、TLS 握手、首字节、总耗时、状态码、页面体积、下载速度、可达性 |
|
||||
| SSL 证书检查 | `/v1/ssl/*url` | TLS 握手 | 证书有效期/剩余天数、颁发机构、主体、TLS 版本、是否过期 |
|
||||
| 网站测速 | `/v1/speed/:version/*url` | 出站下载 | 指定栈的下载速度测试 |
|
||||
| TCPing | `/v1/tcping/:ip` | TCP 拨号 | 端口连通性 + RTT 统计（次数可配） |
|
||||
| DNS 解析 | `/v1/dns/:type/*domain` | `dns-server` | 9 种记录类型；DNS 服务器支持主从 failover 与 DoH |
|
||||
| DNSSEC 验证 | `/v1/dnssec/:domain` | `dnssec-server` | DNSKEY / RRSIG / DS 链式信任校验 |
|
||||
| Whois | `/v1/whois/:domain` | 上游 whois 服务器 | 域名注册商、注册/到期时间等 |
|
||||
| IP 归属地 | `/v1/location`、`/v1/location/:ip` | IP 数据库（10 源） | 多源聚合，含国家/省/市/ISP/经纬度/时区 |
|
||||
| ASN 查询 | `/v1/asn/:ip` | 3 套 ASN 库 + Whois | 自治系统号与所属组织 |
|
||||
|
||||
**双栈**：除 IP 归属地/ASN 外的能力均按 IPv4 / IPv6 分别执行并同时返回（`single-stack` 可声明单栈节点以跳过另一栈）。
|
||||
**统计口径**：所有 `/v1/*` 请求经统计中间件计数，由节点按周期上报收集中心（见 [节点 API · 数据上报](/guide/node-api)）。
|
||||
|
||||
## IP 数据源
|
||||
|
||||
`ipdb` 未关闭时启动加载，共 10 个源；任一本地文件缺失即从远端拉取全部数据库（首次约 450MB，之后每 24h + 随机抖动更新一次）。
|
||||
|
||||
| 源 | 用途 | 形式 |
|
||||
|----|------|------|
|
||||
| ip2region | 国家 / 省 / 市 / ISP | 本地 xdb（v4 + v6） |
|
||||
| IP2Location LITE DB11 | 国家 / 省 / 市 / ISP / 经纬度 / 时区 | 本地 BIN |
|
||||
| IP2Location LITE ASN | ASN | 本地 BIN |
|
||||
| qqwry | 国家 / 省 / 市 / ISP / 国家码 | 本地 ipdb |
|
||||
| MaxMind GeoLite2 City | 国家 / 省 / 市 / 经纬度 | 本地 MMDB |
|
||||
| MaxMind GeoLite2 ASN | ASN / 组织 | 本地 MMDB |
|
||||
| DbIP City Lite | 国家 / 省 / 市 / 经纬度 | 本地 MMDB |
|
||||
| DbIP ASN Lite | ASN / 组织 | 本地 MMDB |
|
||||
| GeoCN | 中国行政区划码 + ISP + 类型 | 本地 MMDB + 行政区划表 |
|
||||
| Bilibili | 国家 / 省 / 市 / ISP / 经纬度 | **在线 API**，24h 缓存 |
|
||||
|
||||
- `/v1/location` 聚合全部 10 源（结果按源分组返回，便于交叉比对）；`/v1/asn` 只查三套 ASN 库并对 MaxMind ASN 做 Whois 解析。
|
||||
- `gh-proxy` 可给 GitHub 下载加代理前缀加速；GeoCN 走 jsDelivr CDN。
|
||||
- `ipdb=false` 时整体关闭：不加载数据库，`/v1/location`、`/v1/asn` 路由不注册，适合只做网络拨测的轻量节点。
|
||||
|
||||
## 可靠性设计
|
||||
|
||||
- **结果缓存**：7 类缓存（6 个业务缓存 5 分钟 + Bilibili 24 小时），失败结果 30s 后即失效；每 10 分钟定时清扫过期条目。详见 [节点 API · 缓存与并发](/guide/node-api)。
|
||||
- **singleflight**：`detail` / `ssl` / `tcping` / `speed` 的并发同 key 请求合并为一次真实探测。
|
||||
- **SSRF 防护**（`block-private-ips`）：拒绝出站连接私有/内网地址，探测目标命中私有网段时直接返回伪造结果，禁止跨跳重定向；`trusted-proxies` 控制 `X-Forwarded-For` 信任范围，防止访客伪造来源 IP。
|
||||
- **DNS 兜底**：`dns-server` / `dnssec-server` 留空时自动探测系统 DNS，避免容器环境下解析不可用。
|
||||
|
||||
## 与收集中心 / 中间件的关系
|
||||
|
||||
```
|
||||
┌───────────────────────────────┐
|
||||
浏览器 / 前端 ───▶│ 中间件（ipw-cn/middleware-go │
|
||||
│ 或 ipw-boce 收集中心） │
|
||||
└───────┬───────────────┬───────┘
|
||||
HTTP │ │ WS（/ws）
|
||||
转发 ▼ ▼
|
||||
┌───────────────────────────────┐
|
||||
│ 后端节点（本仓库） │
|
||||
│ 执行探测 → 结果原路回传 │
|
||||
│ 统计/明细 → 周期上报收集中心 │
|
||||
└───────────────────────────────┘
|
||||
```
|
||||
|
||||
- **转发链路**：前端不直连节点，而是经中间件按池轮询转发；节点也可以直接对外提供 `/v1/*`（自建纯节点模式）。
|
||||
- **WS 通道**：节点作为客户端接入中间件，拨测请求经 WS 下发、结果经 WS 回传；同时承载配置管理（`config`）与升级（`ota`）指令。
|
||||
- **数据上报**：统计与拨测明细只由节点上报，中间件不在转发路径上采集，避免双算。
|
||||
- **版本与能力上报**：节点上报版本号与能力清单，收集中心据此展示版本、判断能否下发管理指令。
|
||||
|
||||
## 部署形态
|
||||
|
||||
| 形态 | 说明 |
|
||||
|------|------|
|
||||
| 二进制 / systemd | `install.sh` 一键安装，配置以环境变量注入 |
|
||||
| Docker | `src/Dockerfile` 多阶段构建，多架构（amd64 / arm64 / armv7）；镜像不含 IP 库，首次运行现场拉取 |
|
||||
| Serverless | EdgeOne Makers、Vercel、AWS Lambda、阿里云函数计算等（均为 IPv4-only，需声明 `SINGLE_STACK=ipv4`） |
|
||||
|
||||
各形态的详细步骤见 [后端节点部署](/guide/deploy-node)。
|
||||
@@ -20,6 +20,9 @@ Lemon IPW（柠檬味 ipw.cn 替代品）是一个开源的分布式站点测试
|
||||
- TCPing（IPv4/IPv6 双栈）
|
||||
- 网站测速
|
||||
- 网站截图
|
||||
- 远程运维（版本 / 能力上报、运行时配置下发、一次性 OTA 升级）
|
||||
|
||||
完整的能力矩阵、IP 数据源与可靠性设计见 [功能总览](/info/features)。
|
||||
|
||||
## 架构
|
||||
|
||||
|
||||
@@ -21,6 +21,8 @@ function checkRateLimit(ip: string, limit: number): boolean {
|
||||
return entry.count <= limit
|
||||
}
|
||||
|
||||
// 数据上报已移除：统计与拨测明细统一由下游节点（lemon-ipw/src）自行上报，
|
||||
// 本转发入口不再计数、不再 POST /report，转发请求也不再携带 X-Boce-Reporter 归属头（防双算协议已废除）。
|
||||
export default defineEventHandler(async (event) => {
|
||||
// 1) Origin / Referer 校验：跨域浏览器调用一律拒绝。
|
||||
// 注意：无 Origin/Referer 的服务端 SSR 调用与命令行请求无法区分，仅靠下方限流约束。
|
||||
@@ -77,9 +79,9 @@ export default defineEventHandler(async (event) => {
|
||||
throw createError({ statusCode: 400, statusMessage: 'Invalid path' })
|
||||
}
|
||||
const query = getQuery(event)
|
||||
const runtimeConfig = useRuntimeConfig(event)
|
||||
|
||||
// 从运行时变量读取 APIKEYS (JSON字符串)，解析后按 backendID 查找 token
|
||||
const runtimeConfig = useRuntimeConfig(event)
|
||||
let apiKey: string | undefined
|
||||
try {
|
||||
const apiKeysMap: Record<string, string> = (runtimeConfig.apiKeys || {}) as Record<string, string>
|
||||
@@ -90,7 +92,7 @@ export default defineEventHandler(async (event) => {
|
||||
} catch (e) {
|
||||
console.debug('[middleware debug] JSON parse FAILED:', e)
|
||||
}
|
||||
// 转发头：不透传 Origin，避免上游 CORS 误判；仅按需注入 Authorization
|
||||
// 转发头：不透传 Origin，避免上游 CORS 误判；仅按需注入 Authorization。
|
||||
const authHeaders: Record<string, string> = {}
|
||||
if (apiKey) {
|
||||
authHeaders['Authorization'] = `Bearer ${apiKey}`
|
||||
@@ -98,7 +100,6 @@ export default defineEventHandler(async (event) => {
|
||||
} else {
|
||||
console.debug('[middleware debug] authHeaders NO Authorization header')
|
||||
}
|
||||
|
||||
if (apiType === 'whois' || apiType === 'dns' || apiType === 'location' || apiType === 'ssl' || apiType === 'asn' || apiType === 'dnssec' || apiType === 'detail') {
|
||||
let apiBaseUrls: Array<{ id: string, url: string ,label: string}> = []
|
||||
switch (apiType) {
|
||||
|
||||
-10
@@ -121,14 +121,6 @@ case "${WS_CHOICE,,}" in
|
||||
;;
|
||||
esac
|
||||
|
||||
echo ""
|
||||
echo "--- OTA 自更新（可选）---"
|
||||
read -r -p "启用 OTA 自动升级（跟随 GitHub Release，major 版本不自动升）？[y/N]: " OTA_CHOICE
|
||||
NODE_OTA=""
|
||||
case "${OTA_CHOICE,,}" in
|
||||
y|yes) NODE_OTA="true" ;;
|
||||
esac
|
||||
|
||||
echo ""
|
||||
echo "--- 其他环境变量（可选）---"
|
||||
echo "输入额外的 Environment= 项，每行一个（如 GH_PROXY=https://ghproxy.com/），空行结束："
|
||||
@@ -157,7 +149,6 @@ echo "access-token: ${ACCESS_TOKEN:+已设置 (隐藏)}"
|
||||
echo "DNS: $DNS_SERVER"
|
||||
echo "ipdb: $IPDB"
|
||||
echo "WS 接入: $(if [ -n "$WS_URL" ]; then printf '%s (id=%s, key=%s)' "$WS_URL" "$NODE_ID" "${NODE_KEY:+已设置}"; else printf '未启用'; fi)"
|
||||
echo "OTA 自更新: ${NODE_OTA:-未启用}"
|
||||
echo "========================================"
|
||||
read -r -p "确认安装？[Y/n]: " CONFIRM
|
||||
case "${CONFIRM,,}" in
|
||||
@@ -216,7 +207,6 @@ add_env REMOTE_CONFIG_URL "$REMOTE_CONFIG_URL"
|
||||
add_env WS_URL "$WS_URL"
|
||||
add_env NODE_ID "$NODE_ID"
|
||||
add_env NODE_KEY "$NODE_KEY"
|
||||
add_env NODE_OTA "$NODE_OTA"
|
||||
if [ -n "$EXTRA_ENVS" ]; then
|
||||
while IFS= read -r line; do
|
||||
[ -n "$line" ] || continue
|
||||
|
||||
@@ -61,6 +61,11 @@ var (
|
||||
V4Client *resty.Client
|
||||
CORS string
|
||||
ACCEPT_DOMAINS []string
|
||||
// 数据上报（上报到收集中心 ipw-boce，详见 report.go）
|
||||
NODE_ID string // 上报身份（node-id），留空回退 hostname
|
||||
REPORT_URL string // 收集中心 HTTP 基址（report-url），留空则不上报
|
||||
REPORT_TOKEN string // /report 鉴权 token（report-token）
|
||||
REPORT_INTERVAL int // 上报间隔秒（report-interval-seconds），缺省 15
|
||||
)
|
||||
|
||||
func fakePerfectWebsiteResult(host string) *WebsiteCheckDetail {
|
||||
@@ -1183,6 +1188,23 @@ func applyRemoteConfig() {
|
||||
if v := configValue(CONFIG, "block-private-ips"); v != "" {
|
||||
ssrf.SetEnabled(v != "false" && v != "0")
|
||||
}
|
||||
// 数据上报（详见 report.go）
|
||||
if v := configValue(CONFIG, "node-id"); v != "" {
|
||||
NODE_ID = v
|
||||
}
|
||||
if v := configValue(CONFIG, "report-url"); v != "" {
|
||||
REPORT_URL = v
|
||||
}
|
||||
// report-token 属受保护凭据：远端下发**不覆盖**（与主线 configRemoteProtectedKeys 同口径）。
|
||||
// 远端一写错，上报会被收集中心 /report 拒收，而节点侧毫无察觉，故不交给配置源自律。
|
||||
if configValue(CONFIG, "report-token") != "" {
|
||||
slog.Warn("远端配置里的 report-token 已被忽略（凭据由节点本地管理）", "url", url)
|
||||
}
|
||||
if v := configValue(CONFIG, "report-interval-seconds"); v != "" {
|
||||
if n, err := strconv.Atoi(v); err == nil && n > 0 {
|
||||
REPORT_INTERVAL = n
|
||||
}
|
||||
}
|
||||
if CORS != "" {
|
||||
ACCEPT_DOMAINS = splitAndTrim(CORS, ",")
|
||||
}
|
||||
@@ -1213,6 +1235,21 @@ func readConfig() {
|
||||
if v := os.Getenv("BLOCK_PRIVATE_IPS"); v != "" {
|
||||
ssrf.SetEnabled(v != "false" && v != "0")
|
||||
}
|
||||
// 数据上报（详见 report.go）：node-id / report-url / report-token / report-interval-seconds
|
||||
if v := os.Getenv("NODE_ID"); v != "" {
|
||||
NODE_ID = strings.TrimSpace(v)
|
||||
}
|
||||
if v := os.Getenv("REPORT_URL"); v != "" {
|
||||
REPORT_URL = strings.TrimSpace(v)
|
||||
}
|
||||
if v := os.Getenv("REPORT_TOKEN"); v != "" {
|
||||
REPORT_TOKEN = strings.TrimSpace(v)
|
||||
}
|
||||
if v := os.Getenv("REPORT_INTERVAL_SECONDS"); v != "" {
|
||||
if n, err := strconv.Atoi(strings.TrimSpace(v)); err == nil && n > 0 {
|
||||
REPORT_INTERVAL = n
|
||||
}
|
||||
}
|
||||
|
||||
// 2) 远端配置（最高优先级，覆盖环境变量）
|
||||
applyRemoteConfig()
|
||||
@@ -1280,6 +1317,9 @@ func main() {
|
||||
webtest.SetDNSSecServer(DNSSEC_DNS_SERVER)
|
||||
slog.Info("Starting server", "port", PORTS, "single_stack", SINGLE_STACK)
|
||||
|
||||
// 数据上报：周期把本节点的统计与拨测明细上报到收集中心（详见 report.go）
|
||||
startNodeReporter()
|
||||
|
||||
// 缓存清扫：定期淘汰过期条目
|
||||
go func() {
|
||||
for {
|
||||
@@ -1296,6 +1336,7 @@ func main() {
|
||||
corsConfig.AllowAllOrigins = true
|
||||
}
|
||||
r.Use(cors.New(corsConfig))
|
||||
r.Use(nodeReportMiddleware()) // 数据上报统计：/v1/* 请求计数与拨测明细（详见 report.go）
|
||||
|
||||
r.GET("/v1/detail/*url", checkWebsiteHandler)
|
||||
r.GET("/v1/ssl/*url", sslCheckHandler)
|
||||
|
||||
@@ -0,0 +1,291 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"log/slog"
|
||||
"net/http"
|
||||
"os"
|
||||
"strings"
|
||||
"sync"
|
||||
"time"
|
||||
|
||||
"github.com/gin-gonic/gin"
|
||||
)
|
||||
|
||||
// ==================== 数据上报（EO 节点 → 收集中心 ipw-boce） ====================
|
||||
//
|
||||
// 自主线 ipw-cn/src/report.go 提取，按 EO 部署形态裁剪：EO 版不连中间件 WS 通道
|
||||
// （无 WebSocket 客户端），因此上报只走一条路——HTTP POST 收集中心 /report。
|
||||
// 报文协议与 ipw-boce/report.go 完全一致：
|
||||
//
|
||||
// POST /report body = {"instance":"上报方标识","stats":[...],"probes":[...]}
|
||||
//
|
||||
// 节点是唯一记录者：统计与拨测明细都由本节点上报，收集中心不在转发路径上计数。
|
||||
// 覆盖的请求来源只有一条：HTTP 接口收到的 /v1/*（nodeReportMiddleware 计数）。
|
||||
//
|
||||
// 进程模型前提：本实现假定云函数运行时是**长驻进程**（与 index.go 里缓存清扫 goroutine
|
||||
// 同一假设）。若部署为按需冷启动，内存中的计数与明细缓冲会随实例回收丢失——上报只在
|
||||
// 实例存活期内累积，间隔到期后即发出。
|
||||
//
|
||||
// 配置（env 优先，远端配置 REMOTE_CONFIG_URL 最高，见 index.go 的 readConfig/applyRemoteConfig）：
|
||||
//
|
||||
// NODE_ID 上报身份（node-id），留空回退 hostname
|
||||
// REPORT_URL 收集中心 HTTP 基址（report-url），留空则不上报
|
||||
// REPORT_TOKEN /report 鉴权 token（report-token）
|
||||
// REPORT_INTERVAL 上报间隔秒（report-interval-seconds），缺省 15
|
||||
|
||||
const (
|
||||
reportMaxProbes = 500
|
||||
reportMaxStats = 500
|
||||
)
|
||||
|
||||
var (
|
||||
nodeStatsMu sync.Mutex
|
||||
nodeStats = map[string]*nodeStatVal{} // apiType → 计数
|
||||
nodeProbeCh chan nodeProbeRec
|
||||
nodeProbeDropN int64
|
||||
nodeDropMu sync.Mutex
|
||||
)
|
||||
|
||||
type nodeStatVal struct {
|
||||
total, errs, latSum, latMax int64
|
||||
}
|
||||
|
||||
// nodeProbeRec 一条拨测明细（结构与 ipw-boce reportProbe 对齐）
|
||||
type nodeProbeRec struct {
|
||||
RequestID string `json:"requestId,omitempty"`
|
||||
NodeID string `json:"nodeId"`
|
||||
APIType string `json:"apiType"`
|
||||
Raw string `json:"raw"`
|
||||
Query string `json:"query,omitempty"`
|
||||
Status int `json:"status"`
|
||||
LatencyMs int64 `json:"latencyMs"`
|
||||
Error string `json:"error,omitempty"`
|
||||
Source string `json:"source,omitempty"`
|
||||
Body string `json:"body,omitempty"`
|
||||
CreatedAt int64 `json:"createdAt,omitempty"`
|
||||
}
|
||||
|
||||
// nodeIsProbeType 拨测类接口（结果需明细上报）。
|
||||
// 明细覆盖：连通性/证书类 detail、ssl，DNS 查询类 dns，直连类 tcping/speed。
|
||||
// dnssec 属功能性校验（结果是否签名/可信），不逐条进明细，只进统计聚合。
|
||||
func nodeIsProbeType(apiType string) bool {
|
||||
switch apiType {
|
||||
case "tcping", "speed", "detail", "ssl", "dns":
|
||||
return true
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
// startNodeReporter 启动上报循环（main() 调用，须在 readConfig 之后）。
|
||||
// 循环常驻：即使当前没有配置 REPORT_URL 也照常起——留空只是"本轮不上报"，
|
||||
// 便于将来接入热更新/远端配置后无需重启即可开启上报。
|
||||
func startNodeReporter() {
|
||||
if REPORT_INTERVAL <= 0 {
|
||||
REPORT_INTERVAL = 15
|
||||
}
|
||||
nodeProbeCh = make(chan nodeProbeRec, 2048)
|
||||
go nodeReportLoop()
|
||||
slog.Info("node reporter enabled", "httpReport", REPORT_URL, "interval", REPORT_INTERVAL, "nodeId", nodeReportNodeID())
|
||||
}
|
||||
|
||||
// nodeReportMiddleware /v1 组统计中间件：归属规则过滤 → 计数 → 拨测类补明细
|
||||
func nodeReportMiddleware() gin.HandlerFunc {
|
||||
return func(c *gin.Context) {
|
||||
start := time.Now()
|
||||
c.Next()
|
||||
|
||||
// 收集中心(ipw-boce)主动调度下发的拨测带 X-Scheduler-Probe 头：
|
||||
// 该次执行由收集中心侧本地落库(source=sched/biz)，本节点跳过计数与明细上报，避免双算。
|
||||
// 真实业务请求（用户/中间件转发）不带此头，仍按"节点是唯一记录者"正常上报。
|
||||
if c.Request.Header.Get("X-Scheduler-Probe") != "" {
|
||||
return
|
||||
}
|
||||
|
||||
apiType, raw := nodeAPIFromPath(c)
|
||||
if apiType == "" {
|
||||
return
|
||||
}
|
||||
latency := time.Since(start)
|
||||
status := c.Writer.Status()
|
||||
nodeRecordAPI(apiType, status, latency)
|
||||
if nodeIsProbeType(apiType) {
|
||||
nodeRecordProbe(nodeProbeRec{
|
||||
NodeID: nodeReportNodeID(), APIType: apiType, Raw: raw,
|
||||
Query: c.Request.URL.RawQuery, Status: status, LatencyMs: latency.Milliseconds(),
|
||||
Source: "http", CreatedAt: time.Now().Unix(),
|
||||
})
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func nodeRecordAPI(apiType string, status int, latency time.Duration) {
|
||||
ms := latency.Milliseconds()
|
||||
nodeStatsMu.Lock()
|
||||
v, ok := nodeStats[apiType]
|
||||
if !ok {
|
||||
v = &nodeStatVal{}
|
||||
nodeStats[apiType] = v
|
||||
}
|
||||
v.total++
|
||||
if status == 0 || status >= 500 {
|
||||
v.errs++
|
||||
}
|
||||
v.latSum += ms
|
||||
if ms > v.latMax {
|
||||
v.latMax = ms
|
||||
}
|
||||
nodeStatsMu.Unlock()
|
||||
}
|
||||
|
||||
func nodeRecordProbe(rec nodeProbeRec) {
|
||||
if nodeProbeCh == nil {
|
||||
return
|
||||
}
|
||||
select {
|
||||
case nodeProbeCh <- rec:
|
||||
default:
|
||||
nodeDropMu.Lock()
|
||||
nodeProbeDropN++
|
||||
n := nodeProbeDropN
|
||||
nodeDropMu.Unlock()
|
||||
if n%100 == 1 {
|
||||
slog.Warn("node report probe queue full", "dropped", n)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// nodeReportNodeID 上报身份：优先 node-id（NODE_ID），否则 hostname
|
||||
func nodeReportNodeID() string {
|
||||
if NODE_ID != "" {
|
||||
return NODE_ID
|
||||
}
|
||||
if h, err := os.Hostname(); err == nil && h != "" {
|
||||
return h
|
||||
}
|
||||
return "unknown"
|
||||
}
|
||||
|
||||
// nodeAPIFromPath 从 gin 路由模板提取 apiType 与拨测目标（对齐主线 WS probe 的 raw 格式）
|
||||
func nodeAPIFromPath(c *gin.Context) (apiType, raw string) {
|
||||
path := c.FullPath() // 形如 /v1/tcping/:ip
|
||||
if !strings.HasPrefix(path, "/v1/") {
|
||||
return "", ""
|
||||
}
|
||||
seg := strings.SplitN(strings.TrimPrefix(path, "/v1/"), "/", 2)
|
||||
if len(seg) == 0 || seg[0] == "" {
|
||||
return "", ""
|
||||
}
|
||||
apiType = seg[0]
|
||||
switch apiType {
|
||||
case "tcping", "dnssec", "whois":
|
||||
raw = c.Param("ip")
|
||||
if raw == "" {
|
||||
raw = c.Param("domain")
|
||||
}
|
||||
case "speed":
|
||||
raw = c.Param("version") + c.Param("url") // v4/example.com
|
||||
case "dns":
|
||||
raw = c.Param("type") + c.Param("domain") // a/example.com
|
||||
case "detail", "ssl":
|
||||
raw = strings.TrimPrefix(c.Param("url"), "/")
|
||||
case "location", "asn":
|
||||
raw = c.Param("ip")
|
||||
}
|
||||
return apiType, raw
|
||||
}
|
||||
|
||||
// nodeReportLoop 周期上报：取走计数与明细缓冲 → HTTP POST 收集中心 /report
|
||||
func nodeReportLoop() {
|
||||
ticker := time.NewTicker(time.Duration(REPORT_INTERVAL) * time.Second)
|
||||
defer ticker.Stop()
|
||||
for range ticker.C {
|
||||
if REPORT_URL == "" {
|
||||
continue // 未配置收集中心地址：本轮不上报（配置就绪后自动开始）
|
||||
}
|
||||
payload := nodeBuildPayload()
|
||||
if payload == nil {
|
||||
continue
|
||||
}
|
||||
if err := nodeHTTPReport(payload); err != nil {
|
||||
slog.Warn("node http report failed", "error", err)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// nodeBuildPayload 取走当前计数与拨测缓冲，组装上报报文；无数据返回 nil。
|
||||
// minute 传节点自己的分钟桶（收集端另有 minute=0 → 按自身时钟入桶的兜底口径）
|
||||
func nodeBuildPayload() map[string]any {
|
||||
nodeStatsMu.Lock()
|
||||
snap := nodeStats
|
||||
nodeStats = make(map[string]*nodeStatVal, len(snap))
|
||||
nodeStatsMu.Unlock()
|
||||
|
||||
probes := make([]nodeProbeRec, 0, reportMaxProbes)
|
||||
if nodeProbeCh != nil {
|
||||
drain:
|
||||
for len(probes) < reportMaxProbes {
|
||||
select {
|
||||
case r := <-nodeProbeCh:
|
||||
probes = append(probes, r)
|
||||
default:
|
||||
break drain // 队列已空，本轮结束
|
||||
}
|
||||
}
|
||||
}
|
||||
if len(snap) == 0 && len(probes) == 0 {
|
||||
return nil
|
||||
}
|
||||
minute := time.Now().UTC().Unix() / 60
|
||||
stats := make([]map[string]any, 0, len(snap))
|
||||
for apiType, v := range snap {
|
||||
stats = append(stats, map[string]any{
|
||||
"minute": minute, "nodeId": nodeReportNodeID(), "apiType": apiType,
|
||||
"total": v.total, "errors": v.errs, "latencySumMs": v.latSum, "latencyMaxMs": v.latMax,
|
||||
})
|
||||
}
|
||||
payload := map[string]any{
|
||||
"instance": nodeReportNodeID(),
|
||||
"stats": stats,
|
||||
}
|
||||
if len(probes) > 0 {
|
||||
payload["probes"] = probes
|
||||
}
|
||||
return payload
|
||||
}
|
||||
|
||||
// nodeHTTPReport 上报到收集中心 /report。
|
||||
// at-most-once：失败只记日志不重试——统计是累加语义，重试会导致重复计算。
|
||||
func nodeHTTPReport(payload map[string]any) error {
|
||||
body, err := json.Marshal(payload)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
url := strings.TrimSuffix(REPORT_URL, "/") + "/report"
|
||||
req, err := http.NewRequest(http.MethodPost, url, bytes.NewReader(body))
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
req.Header.Set("Content-Type", "application/json")
|
||||
if REPORT_TOKEN != "" {
|
||||
req.Header.Set("Authorization", "Bearer "+REPORT_TOKEN)
|
||||
}
|
||||
client := &http.Client{Timeout: 10 * time.Second}
|
||||
resp, err := client.Do(req)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
defer resp.Body.Close()
|
||||
if resp.StatusCode < 200 || resp.StatusCode >= 300 {
|
||||
return &httpStatusError{status: resp.StatusCode}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
type httpStatusError struct{ status int }
|
||||
|
||||
func (e *httpStatusError) Error() string {
|
||||
return fmt.Sprintf("collector returned status %d", e.status)
|
||||
}
|
||||
+7
-1
@@ -5,6 +5,12 @@ FROM --platform=$BUILDPLATFORM golang:1.26-alpine AS build
|
||||
ARG TARGETOS
|
||||
ARG TARGETARCH
|
||||
ARG TARGETVARIANT
|
||||
# 版本信息：CI（docker.yml）注入，与 build_and_release.yml 的二进制产物同源；
|
||||
# BUILD_TIME 每次构建都变，会使 go build 层缓存失效（go mod download 层不受影响），
|
||||
# 未传时用兜底值，本地 docker build 也能识别出容器构建
|
||||
ARG VERSION=dev
|
||||
ARG COMMIT=unknown
|
||||
ARG BUILD_TIME=unknown
|
||||
ENV GO111MODULE=on \
|
||||
CGO_ENABLED=0 \
|
||||
GOOS=${TARGETOS} \
|
||||
@@ -22,7 +28,7 @@ RUN set -eux; \
|
||||
v7) export GOARM=7 ;; \
|
||||
v6) export GOARM=6 ;; \
|
||||
esac; \
|
||||
go build -o main .
|
||||
go build -ldflags "-X main.VERSION=${VERSION} -X main.COMMIT=${COMMIT} -X main.BUILD_TIME=${BUILD_TIME}" -o main .
|
||||
|
||||
# 运行阶段
|
||||
FROM alpine:latest
|
||||
|
||||
@@ -0,0 +1,559 @@
|
||||
package main
|
||||
|
||||
// ==================== 运行时配置接口（HTTP + WS） ====================
|
||||
//
|
||||
// 三个动作：
|
||||
//
|
||||
// get 查看当前生效配置（凭据类键遮蔽为 ***）
|
||||
// patch 修改运行时配置（可选写回 setting.json）
|
||||
// refresh 重新从 REMOTE_CONFIG_URL 拉取远端配置并应用
|
||||
//
|
||||
// 通道：
|
||||
//
|
||||
// HTTP /v1/config (GET/PATCH) · /v1/config/refresh (POST)
|
||||
// 鉴权与业务接口一致（tokenCheck）。刻意不挂 v1 组的 nodeReportMiddleware：
|
||||
// 配置管理不是拨测请求，不该被计入拨测统计。
|
||||
// WS type=config，data.action = get|patch|refresh，应答 type=config_result。
|
||||
// 节点是 WS 客户端，消息来自已注册的中间件连接，鉴权由注册时的 node-key 保证。
|
||||
//
|
||||
// 备注：远端下发（applyRemoteConfig）与本地 patch 共用 applyConfigMap，避免两处键映射漂移。
|
||||
// 远端下发的忽略名单统一由 remoteIgnoreList() 给出（受保护凭据 + remote-ignore-config），
|
||||
// 凭据保护见 configRemoteProtectedKeys。
|
||||
//
|
||||
// 需重启的键（configRestartKeys）：patch / refresh 里出现**值真的变了**的这类键时，
|
||||
// 只在应答的 restartRequired 里如实报出，**节点不会自行重启**——重启会中断在途服务，
|
||||
// 时机由运维掌握（容器编排 / supervisor 也可能接管重启）。端口、CORS 中间件、WS 连接等
|
||||
// 启动期固定的东西，要等进程真正重启后才换过来。
|
||||
//
|
||||
// 通道鉴权差异（重要）：
|
||||
//
|
||||
// HTTP access-token 未配置时整个管理面关闭——此时节点业务接口也无鉴权，
|
||||
// 暴露配置读写等于公网可改配置。
|
||||
// WS 常开。节点是 WS 客户端，指令只来自已通过中间件 ws-keys 校验的注册连接，
|
||||
// 鉴权在中间件侧完成，与节点是否配 access-token 无关。
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"errors"
|
||||
"log/slog"
|
||||
"net/http"
|
||||
"sort"
|
||||
"strconv"
|
||||
"strings"
|
||||
"time"
|
||||
|
||||
"github.com/coder/websocket"
|
||||
"github.com/gin-gonic/gin"
|
||||
"github.com/spf13/viper"
|
||||
"lemon-ipw/ssrf"
|
||||
"lemon-ipw/webtest"
|
||||
)
|
||||
|
||||
// wsClientReconcileDelay ws-url 热更新后延后多久收敛 WS 连接（见 ws.go reconcileWSClient）。
|
||||
// 改 ws-url 会取消"承载这次指令的那条旧连接"，同步收敛会把应答一起掐断：控制台只能看到超时，
|
||||
// 未配 access-token 的节点连 HTTP 回退都没有。延后一点让应答先写回去。
|
||||
const wsClientReconcileDelay = 300 * time.Millisecond
|
||||
|
||||
// errNoRemoteURL 未配置 remote-config-url 却要求刷新远端配置
|
||||
var errNoRemoteURL = errors.New("remote-config-url 未配置")
|
||||
|
||||
// configSecretKeys 凭据类键：GET 快照里遮蔽，PATCH 仍可写（本地管理员的显式行为）
|
||||
var configSecretKeys = map[string]bool{
|
||||
"access-token": true,
|
||||
"node-key": true,
|
||||
"report-token": true,
|
||||
}
|
||||
|
||||
// configRemoteProtectedKeys 远端下发（remote-config-url，含收集中心的"托管配置"）**永不覆盖**的凭据键。
|
||||
//
|
||||
// 为什么硬编码、而不交给 remote-ignore-config：
|
||||
//
|
||||
// 这两把凭据被远端改错的故障形态都是"远端一错、本地失联、且无法再远程修回"——
|
||||
// report-token 被改 → 节点上报被收集中心 /report 拒收，控制台上节点仍显示在线，数据却静默断了；
|
||||
// access-token 被改 → 控制台再也连不上该节点的管理面，连 PATCH 回去的通道都没了。
|
||||
// 所以这层解耦必须由节点自己兜底，不能依赖"配置源别写错"。
|
||||
//
|
||||
// node-key 有意不在此列：托管部署下常由远端统一下发节点身份；若要一并锁死，
|
||||
// 把它写进 remote-ignore-config 即可（本名单只增不减，且对本地 PATCH 无影响）。
|
||||
var configRemoteProtectedKeys = []string{"access-token", "report-token"}
|
||||
|
||||
// remoteIgnoreList 远端下发的忽略名单 = 受保护凭据 + 操作员自选的 remote-ignore-config。
|
||||
// 本地 PATCH（HTTP /v1/config、WS patch）传 nil，不受本名单限制——那是管理员的显式操作。
|
||||
func remoteIgnoreList() []string {
|
||||
out := make([]string, 0, len(configRemoteProtectedKeys)+len(REMOTE_IGNORE_CONFIG))
|
||||
out = append(out, configRemoteProtectedKeys...)
|
||||
out = append(out, REMOTE_IGNORE_CONFIG...)
|
||||
return out
|
||||
}
|
||||
|
||||
// protectedKeysIn 取 cfg 中命中远端保护名单的键（升序）。
|
||||
// 远端下发里出现这些键会被跳过，如实回报 / 记日志，避免"托管配置里写了却不生效"的困惑。
|
||||
func protectedKeysIn(cfg map[string]any) []string {
|
||||
var out []string
|
||||
for _, k := range configRemoteProtectedKeys {
|
||||
if configValue(cfg, k) != "" {
|
||||
out = append(out, k)
|
||||
}
|
||||
}
|
||||
sort.Strings(out)
|
||||
return out
|
||||
}
|
||||
|
||||
// configRestartKeys 改了内存变量但需重启进程才完全生效的键：
|
||||
//
|
||||
// - port / trusted-proxies / cors：监听地址与 gin 中间件在启动时构建并固定
|
||||
// - ipdb：ipdb.Init 与 location / asn 路由注册都按启动时的值判定
|
||||
// - report-interval-seconds：上报 ticker 在启动时按该值创建
|
||||
// - node-id / node-key：WS 注册身份在启动时确立；运行中改动只改内存变量，
|
||||
// 已建立的连接不会换身份，必须重启进程才生效
|
||||
// - access-token：HTTP 管理面路由是否注册、v1 组是否挂 tokenCheck 都在启动时判定
|
||||
//
|
||||
// **不在本表但也不是"每次消费重读"的特例：`ws-url` 是热生效的**——由 WS 客户端控制器
|
||||
// （ws.go 的 reconcileWSClient）按新地址多退少补，连接集合随配置变化，无需重启。
|
||||
//
|
||||
// 不在其中的键即为热生效：`dns-server` / `dnssec-server` / `block-private-ips` /
|
||||
// `single-stack` / `node-ota` 每次消费时重新读变量。
|
||||
//
|
||||
// 判定口径：只有**值真的变了**才算需重启（见 applyConfigMap）——远端/托管配置每次都带全部键，
|
||||
// 若按"键出现过"判定，每次 refresh 都会把节点误报成"需重启"。
|
||||
//
|
||||
// 本表只用于**如实回报** restartRequired，节点不据此自动重启（重启时机交给运维）。
|
||||
var configRestartKeys = map[string]bool{
|
||||
"port": true,
|
||||
"cors": true,
|
||||
"ipdb": true,
|
||||
"report-interval-seconds": true,
|
||||
"trusted-proxies": true,
|
||||
"node-id": true,
|
||||
"node-key": true,
|
||||
"access-token": true,
|
||||
}
|
||||
|
||||
// applyConfigMap 把配置 map 逐键应用到运行时变量（远端下发与本地 patch 共用）。
|
||||
// ignore 里的键直接跳过（远端用它实现 remote-ignore-config，本地 patch 传 nil 表示不限制）。
|
||||
//
|
||||
// 返回：
|
||||
//
|
||||
// applied 实际生效的键（升序）
|
||||
// unknown 不认识的键（不静默丢弃，交调用方回给请求方，便于发现拼错的键）
|
||||
// restart 已改内存、需重启才完全生效、且**值确实变了**的键（升序）
|
||||
func applyConfigMap(cfg map[string]any, ignore []string) (applied, unknown, restart []string) {
|
||||
skip := func(key string) bool {
|
||||
for _, k := range ignore {
|
||||
if k == key {
|
||||
return true
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
mark := func(key string) {
|
||||
applied = append(applied, key)
|
||||
}
|
||||
|
||||
// 需重启类键的"改动前"取值：用于判断值是否真的变了。
|
||||
// applied 的口径是"请求方给了这个键"，不是"值变了"——直接拿它当重启依据的话，
|
||||
// 每次都带全量键的托管配置会让节点每 refresh 一次就误报一次"需重启"。
|
||||
before := make(map[string]string, len(configRestartKeys))
|
||||
for k := range configRestartKeys {
|
||||
before[k] = restartKeyValue(k)
|
||||
}
|
||||
|
||||
// ws-url 改动后要收敛 WS 连接集合：这里只置标志位，循环结束后统一收敛一次（见下）。
|
||||
// 与需重启键同口径——**值真的变了**才算，否则每次带全量键的托管配置 refresh 都会白跑一次收敛。
|
||||
beforeWSURL := WS_URL
|
||||
wsClientDirty := false
|
||||
|
||||
for _, key := range sortedKeys(cfg) {
|
||||
v := configValue(cfg, key) // 空值视为"不覆盖"，与远端配置一致
|
||||
if v == "" || skip(key) {
|
||||
continue
|
||||
}
|
||||
switch key {
|
||||
case "port":
|
||||
PORTS = v
|
||||
case "gh-proxy":
|
||||
GH_PROXY = v
|
||||
case "single-stack":
|
||||
SINGLE_STACK = strings.ToLower(v)
|
||||
case "dns-server":
|
||||
DNS_SERVER = v
|
||||
webtest.SetDNSServer(v)
|
||||
case "dnssec-server":
|
||||
DNSSEC_DNS_SERVER = v
|
||||
webtest.SetDNSSecServer(v)
|
||||
case "ipdb":
|
||||
// 仅改变量不够：ipdb.Init 与 location/asn 路由注册都在启动时按该值判定，运行中不重建
|
||||
IPDB = v
|
||||
case "cors":
|
||||
CORS = v
|
||||
ACCEPT_DOMAINS = splitAndTrim(CORS, ",")
|
||||
case "block-private-ips":
|
||||
ssrf.SetEnabled(v != "false" && v != "0")
|
||||
case "trusted-proxies":
|
||||
TRUSTED_PROXIES = v
|
||||
case "remote-config-url":
|
||||
REMOTE_CONFIG_URL = v
|
||||
case "remote-ignore-config":
|
||||
if arr, ok := cfg[key].([]any); ok { // setting.json 里是数组，也可给逗号分隔串
|
||||
out := make([]string, 0, len(arr))
|
||||
for _, item := range arr {
|
||||
if s, ok := item.(string); ok {
|
||||
if s = strings.TrimSpace(s); s != "" {
|
||||
out = append(out, s)
|
||||
}
|
||||
}
|
||||
}
|
||||
REMOTE_IGNORE_CONFIG = out
|
||||
} else {
|
||||
REMOTE_IGNORE_CONFIG = splitAndTrim(v, ",")
|
||||
}
|
||||
case "access-token":
|
||||
ACCESS_TOKEN = v
|
||||
case "ws-url":
|
||||
WS_URL = v
|
||||
wsClientDirty = WS_URL != beforeWSURL
|
||||
case "node-id":
|
||||
WS_NODE_ID = v
|
||||
case "node-key":
|
||||
WS_NODE_KEY = v
|
||||
case "report-url":
|
||||
REPORT_URL = v
|
||||
case "report-token":
|
||||
REPORT_TOKEN = v
|
||||
case "report-interval-seconds":
|
||||
n, err := strconv.Atoi(v)
|
||||
if err != nil || n <= 0 {
|
||||
unknown = append(unknown, key) // 值非法：不覆盖原值，明确报给调用方
|
||||
continue
|
||||
}
|
||||
REPORT_INTERVAL = n
|
||||
case "node-ota":
|
||||
// 热生效：下发 OTA 指令时才读 NODE_OTA（见 ota.go），故不在 configRestartKeys
|
||||
enabled, known := parseOTASwitch(v)
|
||||
if !known {
|
||||
unknown = append(unknown, key) // 值非法：不覆盖原值，明确报给调用方
|
||||
continue
|
||||
}
|
||||
NODE_OTA = enabled
|
||||
default:
|
||||
unknown = append(unknown, key)
|
||||
continue
|
||||
}
|
||||
mark(key)
|
||||
}
|
||||
|
||||
// 需重启的键：值真的变了才报（见 before 注释）。仅作为信息回报给调用方，
|
||||
// 节点不据此重启——重启时机会中断在途服务，由运维决定。
|
||||
for _, key := range applied {
|
||||
if configRestartKeys[key] && restartKeyValue(key) != before[key] {
|
||||
restart = append(restart, key)
|
||||
}
|
||||
}
|
||||
|
||||
// ws-url 热更新：把在跑的连接收敛到新地址（多退少补）。
|
||||
// 放在循环外是为了避免一条指令里 ws-url 重复出现时收敛多次；
|
||||
// 异步延后则是为了先让本次请求的应答写回去——收敛会取消承载它自己的那条旧连接。
|
||||
if wsClientDirty {
|
||||
go func() {
|
||||
time.Sleep(wsClientReconcileDelay)
|
||||
reconcileWSClient()
|
||||
}()
|
||||
}
|
||||
|
||||
sort.Strings(applied)
|
||||
sort.Strings(unknown)
|
||||
sort.Strings(restart)
|
||||
return applied, unknown, restart
|
||||
}
|
||||
|
||||
// restartKeyValue 取需重启类键的当前值（字符串化），只用于比对改动前后是否真的变了。
|
||||
// 不认识的键返回 ""。
|
||||
func restartKeyValue(key string) string {
|
||||
switch key {
|
||||
case "port":
|
||||
return PORTS
|
||||
case "cors":
|
||||
return CORS
|
||||
case "ipdb":
|
||||
return IPDB
|
||||
case "trusted-proxies":
|
||||
return TRUSTED_PROXIES
|
||||
case "ws-url":
|
||||
return WS_URL
|
||||
case "node-id":
|
||||
return WS_NODE_ID
|
||||
case "node-key":
|
||||
return WS_NODE_KEY
|
||||
case "access-token":
|
||||
return ACCESS_TOKEN
|
||||
case "report-interval-seconds":
|
||||
return strconv.Itoa(REPORT_INTERVAL)
|
||||
}
|
||||
return ""
|
||||
}
|
||||
|
||||
// configSnapshot 当前生效配置的快照（凭据类键只回显 ***，不泄露明文）
|
||||
func configSnapshot() map[string]any {
|
||||
out := map[string]any{
|
||||
"port": PORTS,
|
||||
"gh-proxy": GH_PROXY,
|
||||
"single-stack": SINGLE_STACK,
|
||||
"dns-server": DNS_SERVER,
|
||||
"dnssec-server": DNSSEC_DNS_SERVER,
|
||||
"ipdb": IPDB,
|
||||
"cors": CORS,
|
||||
"block-private-ips": ssrf.Enabled(),
|
||||
"trusted-proxies": TRUSTED_PROXIES,
|
||||
"remote-config-url": REMOTE_CONFIG_URL,
|
||||
"remote-ignore-config": REMOTE_IGNORE_CONFIG,
|
||||
"ws-url": WS_URL,
|
||||
"node-id": WS_NODE_ID,
|
||||
"node-ota": NODE_OTA,
|
||||
"report-url": REPORT_URL,
|
||||
"report-interval-seconds": REPORT_INTERVAL,
|
||||
}
|
||||
if ACCESS_TOKEN != "" {
|
||||
out["access-token"] = "***"
|
||||
} else {
|
||||
out["access-token"] = ""
|
||||
}
|
||||
if WS_NODE_KEY != "" {
|
||||
out["node-key"] = "***"
|
||||
} else {
|
||||
out["node-key"] = ""
|
||||
}
|
||||
if REPORT_TOKEN != "" {
|
||||
out["report-token"] = "***"
|
||||
} else {
|
||||
out["report-token"] = ""
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
// persistConfig 把已应用的键写回 setting.json（viper 保留文件中其它未改动的键）。
|
||||
// 无 setting.json（纯环境变量部署）时新建一份。
|
||||
func persistConfig(body map[string]any, applied []string) error {
|
||||
for _, key := range applied {
|
||||
viper.Set(key, body[key])
|
||||
}
|
||||
if err := viper.WriteConfig(); err == nil {
|
||||
return nil
|
||||
}
|
||||
return viper.SafeWriteConfigAs("setting.json")
|
||||
}
|
||||
|
||||
// sortedKeys 配置键升序，保证 applied/unknown 输出顺序稳定（便于日志 diff 与测试）
|
||||
func sortedKeys(m map[string]any) []string {
|
||||
out := make([]string, 0, len(m))
|
||||
for k := range m {
|
||||
out = append(out, k)
|
||||
}
|
||||
sort.Strings(out)
|
||||
return out
|
||||
}
|
||||
|
||||
// refreshRemoteConfig 重新拉取远端配置并应用；受保护凭据（access-token / report-token）
|
||||
// 永不随远端下发，保持"ENV / setting.json 本地管理"的口径（见 configRemoteProtectedKeys）。
|
||||
func refreshRemoteConfig() (map[string]any, error) {
|
||||
url := strings.TrimSpace(REMOTE_CONFIG_URL)
|
||||
if url == "" {
|
||||
return nil, errNoRemoteURL
|
||||
}
|
||||
cfg, err := fetchRemoteConfig(url)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
applied, unknown, restart := applyConfigMap(cfg, remoteIgnoreList())
|
||||
protected := protectedKeysIn(cfg)
|
||||
if len(protected) > 0 {
|
||||
slog.Warn("远端配置里的凭据键已被忽略（凭据由节点本地管理）", "keys", protected, "url", url)
|
||||
}
|
||||
// 远端配置本身就是持久来源（重启后会重新拉取），因此不需要补写 setting.json；
|
||||
// restart 里的键只如实回报，重启时机交给运维
|
||||
return map[string]any{
|
||||
"source": url,
|
||||
"applied": applied,
|
||||
"unknown": unknown,
|
||||
"restartRequired": restart,
|
||||
"config": configSnapshot(),
|
||||
"protectedIgnored": protected,
|
||||
"remoteProtectedKeys": configRemoteProtectedKeys,
|
||||
}, nil
|
||||
}
|
||||
|
||||
// ==================== HTTP ====================
|
||||
|
||||
// registerConfigRoutes 注册运行时配置接口（/v1/config 组：与业务接口同鉴权，但不计入拨测统计）。
|
||||
//
|
||||
// access-token 未配置时**关闭整个 HTTP 管理面**：此时节点业务接口本身也无鉴权，
|
||||
// 再暴露配置读写等于公网任何人可改节点配置。WS 通道不受影响——它由节点主动外连中间件，
|
||||
// 注册需通过中间件的 ws-keys 校验，指令只发给已注册连接，天然有鉴权。
|
||||
func registerConfigRoutes(r *gin.Engine) {
|
||||
g := r.Group("/v1/config")
|
||||
if ACCESS_TOKEN == "" {
|
||||
slog.Warn("config HTTP API disabled: access-token not set, use WS channel instead")
|
||||
disabled := func(c *gin.Context) {
|
||||
c.AbortWithStatusJSON(http.StatusForbidden, gin.H{
|
||||
"error": "配置管理接口已关闭：节点未配置 access-token，请通过 WS 通道操作",
|
||||
})
|
||||
}
|
||||
g.GET("", disabled)
|
||||
g.PATCH("", disabled)
|
||||
g.POST("/refresh", disabled)
|
||||
return
|
||||
}
|
||||
g.Use(tokenCheck())
|
||||
g.GET("", configGetHandler)
|
||||
g.PATCH("", configPatchHandler)
|
||||
g.POST("/refresh", configRefreshHandler)
|
||||
}
|
||||
|
||||
func configGetHandler(c *gin.Context) {
|
||||
c.JSON(http.StatusOK, gin.H{
|
||||
"config": configSnapshot(),
|
||||
"secretKeys": sortedKeysBool(configSecretKeys),
|
||||
"restartRequiredKeys": sortedKeysBool(configRestartKeys),
|
||||
"remoteProtectedKeys": configRemoteProtectedKeys,
|
||||
})
|
||||
}
|
||||
|
||||
func configPatchHandler(c *gin.Context) {
|
||||
var body map[string]any
|
||||
if err := c.ShouldBindJSON(&body); err != nil {
|
||||
c.JSON(http.StatusBadRequest, gin.H{"error": "请求体须为 JSON 对象：" + err.Error()})
|
||||
return
|
||||
}
|
||||
if len(body) == 0 {
|
||||
c.JSON(http.StatusBadRequest, gin.H{"error": "请求体为空"})
|
||||
return
|
||||
}
|
||||
// 本地显式 PATCH 不受 remote-ignore-config 限制：那是"防远端覆盖"的白名单
|
||||
applied, unknown, restart := applyConfigMap(body, nil)
|
||||
|
||||
persisted := false
|
||||
if p := c.Query("persist"); p == "1" || strings.EqualFold(p, "true") {
|
||||
if err := persistConfig(body, applied); err != nil {
|
||||
c.JSON(http.StatusInternalServerError, gin.H{
|
||||
"error": "写回 setting.json 失败：" + err.Error(),
|
||||
"applied": applied,
|
||||
})
|
||||
return
|
||||
}
|
||||
persisted = true
|
||||
}
|
||||
// 未要求持久化时只改内存：需重启的键不落盘，进程重启后会回到 setting.json / 远端配置的值。
|
||||
// 这是刻意的语义——PATCH 是"当前进程内的即时改动"，要不要固化由调用方用 persist 明确决定。
|
||||
c.JSON(http.StatusOK, gin.H{
|
||||
"applied": applied,
|
||||
"unknown": unknown,
|
||||
"restartRequired": restart,
|
||||
"persisted": persisted,
|
||||
"config": configSnapshot(),
|
||||
})
|
||||
}
|
||||
|
||||
func configRefreshHandler(c *gin.Context) {
|
||||
res, err := refreshRemoteConfig()
|
||||
if err == errNoRemoteURL {
|
||||
c.JSON(http.StatusBadRequest, gin.H{"error": "remote-config-url 未配置，无法刷新"})
|
||||
return
|
||||
}
|
||||
if err != nil {
|
||||
c.JSON(http.StatusBadGateway, gin.H{"error": "拉取远端配置失败：" + err.Error(), "source": REMOTE_CONFIG_URL})
|
||||
return
|
||||
}
|
||||
c.JSON(http.StatusOK, res)
|
||||
}
|
||||
|
||||
// sortedKeysBool 取 map 键的升序列表（用于向调用方说明哪些键是凭据/需重启）
|
||||
func sortedKeysBool(m map[string]bool) []string {
|
||||
out := make([]string, 0, len(m))
|
||||
for k := range m {
|
||||
out = append(out, k)
|
||||
}
|
||||
sort.Strings(out)
|
||||
return out
|
||||
}
|
||||
|
||||
// ==================== WS ====================
|
||||
|
||||
// wsConfigResult 配置指令的 WS 应答（type=config_result）
|
||||
type wsConfigResult struct {
|
||||
RequestID string `json:"requestId,omitempty"`
|
||||
Action string `json:"action"`
|
||||
OK bool `json:"ok"`
|
||||
Error string `json:"error,omitempty"`
|
||||
Source string `json:"source,omitempty"`
|
||||
Applied []string `json:"applied,omitempty"`
|
||||
Unknown []string `json:"unknown,omitempty"`
|
||||
RestartRequired []string `json:"restartRequired,omitempty"`
|
||||
Persisted bool `json:"persisted,omitempty"`
|
||||
Config map[string]any `json:"config,omitempty"`
|
||||
// ProtectedIgnored 本次 refresh 中因凭据保护被跳过的键：远端配置里写了也不生效（见 configRemoteProtectedKeys）
|
||||
ProtectedIgnored []string `json:"protectedIgnored,omitempty"`
|
||||
// 元信息：与 HTTP GET 一致，供控制台标注「凭据键不下发」「远端不可覆盖」「该键改动需重启」
|
||||
SecretKeys []string `json:"secretKeys,omitempty"`
|
||||
RestartKeys []string `json:"restartRequiredKeys,omitempty"`
|
||||
RemoteProtectedKeys []string `json:"remoteProtectedKeys,omitempty"`
|
||||
}
|
||||
|
||||
// wsHandleConfig 处理中间件下发的配置指令：get / patch / refresh
|
||||
func wsHandleConfig(c *websocket.Conn, msg wsMsg) {
|
||||
var req struct {
|
||||
RequestID string `json:"requestId"`
|
||||
Action string `json:"action"`
|
||||
Config map[string]any `json:"config"`
|
||||
Persist bool `json:"persist"`
|
||||
}
|
||||
_ = json.Unmarshal(msg.Data, &req)
|
||||
|
||||
action := strings.ToLower(strings.TrimSpace(req.Action))
|
||||
if action == "" {
|
||||
action = "get"
|
||||
}
|
||||
res := wsConfigResult{RequestID: req.RequestID, Action: action, OK: true}
|
||||
|
||||
switch action {
|
||||
case "get":
|
||||
res.Config = configSnapshot()
|
||||
|
||||
case "patch":
|
||||
if len(req.Config) == 0 {
|
||||
res.OK, res.Error = false, "config 为空"
|
||||
break
|
||||
}
|
||||
applied, unknown, restart := applyConfigMap(req.Config, nil)
|
||||
// 未要求持久化时只改内存（同 HTTP PATCH）：需重启的键不落盘，重启后会回到原值
|
||||
if req.Persist {
|
||||
if err := persistConfig(req.Config, applied); err != nil {
|
||||
res.OK, res.Error = false, "写回 setting.json 失败："+err.Error()
|
||||
break
|
||||
}
|
||||
res.Persisted = true
|
||||
}
|
||||
res.Applied, res.Unknown, res.RestartRequired = applied, unknown, restart
|
||||
res.Config = configSnapshot()
|
||||
|
||||
case "refresh":
|
||||
out, err := refreshRemoteConfig()
|
||||
if err != nil {
|
||||
res.OK, res.Error = false, err.Error()
|
||||
break
|
||||
}
|
||||
res.Source, _ = out["source"].(string)
|
||||
res.Applied, _ = out["applied"].([]string)
|
||||
res.Unknown, _ = out["unknown"].([]string)
|
||||
res.RestartRequired, _ = out["restartRequired"].([]string)
|
||||
res.ProtectedIgnored, _ = out["protectedIgnored"].([]string)
|
||||
res.Config, _ = out["config"].(map[string]any)
|
||||
|
||||
default:
|
||||
res.OK, res.Error = false, "未知 action："+action
|
||||
}
|
||||
|
||||
// 元信息随每次应答带上，控制台据此标注凭据键、远端不可覆盖键与需重启键（与 HTTP GET 保持一致）
|
||||
res.SecretKeys = sortedKeysBool(configSecretKeys)
|
||||
res.RestartKeys = sortedKeysBool(configRestartKeys)
|
||||
res.RemoteProtectedKeys = configRemoteProtectedKeys
|
||||
wsSend(c, wsMsg{Type: "config_result", Data: wsRaw(res)})
|
||||
}
|
||||
+1
-1
@@ -3,6 +3,7 @@ module lemon-ipw
|
||||
go 1.26.6
|
||||
|
||||
require (
|
||||
github.com/AdguardTeam/golibs v0.35.16
|
||||
github.com/coder/websocket v1.8.15
|
||||
github.com/gin-contrib/cors v1.7.7
|
||||
github.com/gin-gonic/gin v1.12.0
|
||||
@@ -20,7 +21,6 @@ require (
|
||||
)
|
||||
|
||||
require (
|
||||
github.com/AdguardTeam/golibs v0.35.16 // indirect
|
||||
github.com/bytedance/gopkg v0.1.3 // indirect
|
||||
github.com/bytedance/sonic v1.15.0 // indirect
|
||||
github.com/bytedance/sonic/loader v0.5.0 // indirect
|
||||
|
||||
+3
-10
@@ -11,9 +11,9 @@ github.com/cloudwego/base64x v0.1.6/go.mod h1:OFcloc187FXDaYHvrNIjxSe8ncn0OOM8gE
|
||||
github.com/coder/websocket v1.8.15 h1:6B2JPeOGlpff2Uz6vOEH1Vzpi0iUz20A+lPVhPHtNUA=
|
||||
github.com/coder/websocket v1.8.15/go.mod h1:NX3SzP+inril6yawo5CQXx8+fk145lPDC6pumgx0mVg=
|
||||
github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
|
||||
github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
|
||||
github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
|
||||
github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM=
|
||||
github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
|
||||
github.com/frankban/quicktest v1.14.6 h1:7Xjx+VpznH+oBnejlPUj8oUpdxnVs4f8XU8WnHkI4W8=
|
||||
github.com/frankban/quicktest v1.14.6/go.mod h1:4ptaffx2x8+WTWXmUCuVU6aPUX1/Mz7zb5vbUoiM6w0=
|
||||
github.com/fsnotify/fsnotify v1.9.0 h1:2Ml+OJNzbYCTzsxtv8vKSFD9PbJjmhYF14k/jKC7S9k=
|
||||
@@ -80,16 +80,15 @@ github.com/oschwald/maxminddb-golang/v2 v2.3.0 h1:PnXjMGjkSQlwOBSyZ7hk6Fd75t7erk
|
||||
github.com/oschwald/maxminddb-golang/v2 v2.3.0/go.mod h1:NSQvgFwPxODpBTJI5+5Ns1AAucnx7ggW9PSRRifAT1s=
|
||||
github.com/pelletier/go-toml/v2 v2.2.4 h1:mye9XuhQ6gvn5h28+VilKrrPoQVanw5PMw/TB0t5Ec4=
|
||||
github.com/pelletier/go-toml/v2 v2.2.4/go.mod h1:2gIqNv+qfxSVS7cM2xJQKtLSTLUE9V8t9Stt+h56mCY=
|
||||
github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
|
||||
github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
|
||||
github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
|
||||
github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
|
||||
github.com/quic-go/qpack v0.6.0 h1:g7W+BMYynC1LbYLSqRt8PBg5Tgwxn214ZZR34VIOjz8=
|
||||
github.com/quic-go/qpack v0.6.0/go.mod h1:lUpLKChi8njB4ty2bFLX2x4gzDqXwUpaO1DP9qMDZII=
|
||||
github.com/quic-go/quic-go v0.59.1 h1:0Gmua0HW1Tv7ANR7hUYwRyD0MG5OJfgvYSZasGZzBic=
|
||||
github.com/quic-go/quic-go v0.59.1/go.mod h1:upnsH4Ju1YkqpLXC305eW3yDZ4NfnNbmQRCMWS58IKU=
|
||||
github.com/rogpeppe/go-internal v1.10.0 h1:TMyTOH3F/DB16zRVcYyreMH6GnZZrwQVAoYjRBZyWFQ=
|
||||
github.com/rogpeppe/go-internal v1.10.0/go.mod h1:UQnix2H7Ngw/k4C5ijL5+65zddjncjaFoBhdsK/akog=
|
||||
github.com/rogpeppe/go-internal v1.15.0 h1:D0RCU5rMAp+SpgkiNdrjfJ+LX4J1M32V2NeCY7EJ6hc=
|
||||
github.com/rogpeppe/go-internal v1.15.0/go.mod h1:DrUVZyrJU+txYW5/1kwtXQSMFio52ZOxX7yM1VHvnxs=
|
||||
github.com/sagikazarmark/locafero v0.11.0 h1:1iurJgmM9G3PA/I+wWYIOw/5SyBtxapeHDcg+AAIFXc=
|
||||
github.com/sagikazarmark/locafero v0.11.0/go.mod h1:nVIGvgyzw595SUSUE6tvCp3YYTeHs15MvlmU87WwIik=
|
||||
github.com/sourcegraph/conc v0.3.1-0.20240121214520-5f936abd7ae8 h1:+jumHNA0Wrelhe64i8F6HNlS8pkoyMv5sreGx2Ry5Rw=
|
||||
@@ -129,8 +128,6 @@ golang.org/x/arch v0.23.0 h1:lKF64A2jF6Zd8L0knGltUnegD62JMFBiCPBmQpToHhg=
|
||||
golang.org/x/arch v0.23.0/go.mod h1:dNHoOeKiyja7GTvF9NJS1l3Z2yntpQNzgrjh1cU103A=
|
||||
golang.org/x/crypto v0.54.0 h1:YLIA59K4fiNzHzjnZt2tUJQjQtUWfWbeHBqKtk3eScw=
|
||||
golang.org/x/crypto v0.54.0/go.mod h1:KWL8ny2AZdGR2cWmzeHrp2azQPGogOv+HeQaVEXC2dk=
|
||||
golang.org/x/mod v0.37.0 h1:vF1DjpVEshcIqoEaauuHebaLk1O1forxjxBaVn884JQ=
|
||||
golang.org/x/mod v0.37.0/go.mod h1:m8S8VeM9r4dzDwjrKO0a1sZP3YjeMamRRlD+fmR2Q/0=
|
||||
golang.org/x/mod v0.38.0 h1:MECBjubtXD7yj4HrhIUcywNaGeNVUdfVnxmPajOk4yk=
|
||||
golang.org/x/mod v0.38.0/go.mod h1:V6Xz0pq8TQ3dGqVQ1FVHuelZpAL0uNhSkk9ogYP3c40=
|
||||
golang.org/x/net v0.57.0 h1:K5+3DljvIuDG9/Jv9rvyMywYNFCQ9RSUY6OOTTkT+tE=
|
||||
@@ -142,12 +139,8 @@ golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs=
|
||||
golang.org/x/sys v0.47.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
|
||||
golang.org/x/text v0.40.0 h1:Ub2Z6/xjgF1WrYQz2nuITOEegKFtiIy+rieRJ5lHZKs=
|
||||
golang.org/x/text v0.40.0/go.mod h1:hpnzDAfGV753zIKo+wk3u1bVKCGPbrnF7+7LBF/UHVY=
|
||||
golang.org/x/tools v0.47.0 h1:7Kn5x/d1svx/PzryTsqeoZN4TZwqeH5pGWjefhLi/1Q=
|
||||
golang.org/x/tools v0.47.0/go.mod h1:dFHnyTvFWY212G+h7ZY4Vsp/K3U4/7W9TyVaAul8uCA=
|
||||
golang.org/x/tools v0.48.0 h1:3+hClM1aLL5mjMKm5ovokw9epgRXPuu2tILgismM6RE=
|
||||
golang.org/x/tools v0.48.0/go.mod h1:08xX0orndb/F7jJxGDicx061tyd5pcMto75YMAXr6lk=
|
||||
google.golang.org/protobuf v1.36.10 h1:AYd7cD/uASjIL6Q9LiTjz8JLcrh/88q5UObnmY3aOOE=
|
||||
google.golang.org/protobuf v1.36.10/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
|
||||
google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE=
|
||||
google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
|
||||
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
|
||||
|
||||
+73
-79
@@ -15,10 +15,11 @@ import (
|
||||
"net/http"
|
||||
"net/url"
|
||||
"os"
|
||||
"runtime"
|
||||
"os/signal"
|
||||
"strconv"
|
||||
"strings"
|
||||
"sync"
|
||||
"syscall"
|
||||
"time"
|
||||
|
||||
"github.com/AdguardTeam/golibs/netutil/sysresolv"
|
||||
@@ -241,10 +242,12 @@ var (
|
||||
WS_URL string // WS 客户端：中间件 WS 地址（ws://host:port/ws）
|
||||
WS_NODE_ID string // WS 客户端：节点 id（与中间件 ws-keys 键一致）
|
||||
WS_NODE_KEY string // WS 客户端：注册 key（与中间件 ws-keys[节点id] 一致，可空）
|
||||
NODE_OTA string // OTA 自更新开关（node-ota / NODE_OTA），"true" 时启用
|
||||
REPORT_URL string // 数据上报：收集中心 HTTP 接口基址（report-url / REPORT_URL），WS 全部掉线时的兜底通道
|
||||
REPORT_TOKEN string // 数据上报：/report 鉴权 token（report-token / REPORT_TOKEN）
|
||||
REPORT_INTERVAL int // 数据上报间隔秒（report-interval-seconds / REPORT_INTERVAL_SECONDS），缺省 15
|
||||
TRUSTED_PROXIES string // 可信代理列表（trusted-proxies / TRUSTED_PROXIES），逗号分隔 IP/CIDR，供 ClientIP 判定
|
||||
httpServer *http.Server // 显式持有的 HTTP 服务（Windows OTA 优雅重启需要先 Shutdown）
|
||||
otaHandoverWait chan struct{} // 非 nil 表示 Windows OTA 优雅重启模式：Serve 关闭后 main 停在此等待老进程退出
|
||||
NODE_OTA bool // OTA 升级开关（node-ota / NODE_OTA）：缺省允许收集中心下发；只读容器等不可自更新部署显式设 false，节点拒绝指令并回传原因
|
||||
httpServer *http.Server // 显式持有的 HTTP 服务（收到退出信号时优雅停机需要先 Shutdown）
|
||||
VERSION string
|
||||
COMMIT string
|
||||
BUILD_TIME string
|
||||
@@ -954,9 +957,15 @@ func pingHandler(c *gin.Context) {
|
||||
c.JSON(200, rawResult.(*TCPingResult))
|
||||
}
|
||||
|
||||
// healchCheck 健康检查（GET /）。除 status 外回报版本号：中间件对 HTTP 版节点（无 WS 连接）
|
||||
// 正是靠这个接口探活，顺带取版本用于节点状态页展示。
|
||||
func healchCheck(c *gin.Context) {
|
||||
c.JSON(http.StatusOK, gin.H{
|
||||
"status": "ok",
|
||||
"version": VERSION,
|
||||
// 能力清单同 register 报文：中间件对纯 HTTP 节点探活时一并取回，
|
||||
// 用于在下发 config 前判断该节点能否理解对应指令（见 ws.go nodeCapabilities）
|
||||
"capabilities": nodeCapabilities(),
|
||||
})
|
||||
}
|
||||
func tokenCheck() gin.HandlerFunc {
|
||||
@@ -1026,63 +1035,18 @@ func applyRemoteConfig() {
|
||||
slog.Warn("Failed to fetch remote config, falling back to local config", "url", url, "error", err)
|
||||
return
|
||||
}
|
||||
// ignore 列表：数组中的配置项不被远端覆盖（逐键判断跳过）
|
||||
ignored := func(key string) bool {
|
||||
for _, k := range REMOTE_IGNORE_CONFIG {
|
||||
if k == key {
|
||||
return true
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
if v := configValue(CONFIG, "port"); v != "" && !ignored("port") {
|
||||
PORTS = v
|
||||
}
|
||||
if v := configValue(CONFIG, "gh-proxy"); v != "" && !ignored("gh-proxy") {
|
||||
GH_PROXY = v
|
||||
}
|
||||
if v := configValue(CONFIG, "single-stack"); v != "" && !ignored("single-stack") {
|
||||
SINGLE_STACK = strings.ToLower(v)
|
||||
}
|
||||
if v := configValue(CONFIG, "dns-server"); v != "" && !ignored("dns-server") {
|
||||
DNS_SERVER = v
|
||||
}
|
||||
if v := configValue(CONFIG, "dnssec-server"); v != "" && !ignored("dnssec-server") {
|
||||
DNSSEC_DNS_SERVER = v
|
||||
}
|
||||
if v := configValue(CONFIG, "ipdb"); v != "" && !ignored("ipdb") {
|
||||
IPDB = v
|
||||
}
|
||||
if v := configValue(CONFIG, "cors"); v != "" && !ignored("cors") {
|
||||
CORS = v
|
||||
}
|
||||
// block-private-ips 与 setting.json 格式一致，允许远端覆盖
|
||||
if v := configValue(CONFIG, "block-private-ips"); v != "" && !ignored("block-private-ips") {
|
||||
ssrf.SetEnabled(v != "false" && v != "0")
|
||||
}
|
||||
// WS 客户端配置（远端可覆盖，除非在 ignore 列表中）
|
||||
if v := configValue(CONFIG, "ws-url"); v != "" && !ignored("ws-url") {
|
||||
WS_URL = v
|
||||
}
|
||||
if v := configValue(CONFIG, "node-id"); v != "" && !ignored("node-id") {
|
||||
WS_NODE_ID = v
|
||||
}
|
||||
if v := configValue(CONFIG, "node-key"); v != "" && !ignored("node-key") {
|
||||
WS_NODE_KEY = v
|
||||
}
|
||||
// OTA 自更新开关（远端可统一开启/关闭节点的自更新）
|
||||
if v := configValue(CONFIG, "node-ota"); v != "" && !ignored("node-ota") {
|
||||
NODE_OTA = v
|
||||
}
|
||||
// 可信代理列表（远端可统一下发）
|
||||
if v := configValue(CONFIG, "trusted-proxies"); v != "" && !ignored("trusted-proxies") {
|
||||
TRUSTED_PROXIES = v
|
||||
}
|
||||
// access-token 不在此覆盖：保持原有优先级（环境变量 > setting.json）
|
||||
// 键映射统一在 applyConfigMap（与本地 PATCH / WS 指令共用，见 config_api.go）；
|
||||
// 忽略名单由 remoteIgnoreList() 给出：受保护凭据（access-token / report-token）
|
||||
// + 操作员自选的 remote-ignore-config —— 凭据始终保持"ENV > setting.json"的本地优先级
|
||||
applied, unknown, _ := applyConfigMap(CONFIG, remoteIgnoreList())
|
||||
if CORS != "" {
|
||||
ACCEPT_DOMAINS = splitAndTrim(CORS, ",")
|
||||
}
|
||||
slog.Info("Remote config applied", "url", url)
|
||||
slog.Info("Remote config applied", "url", url, "applied", applied, "unknown", unknown)
|
||||
if protected := protectedKeysIn(CONFIG); len(protected) > 0 {
|
||||
slog.Warn("远端配置里的凭据键已被忽略（凭据由节点本地管理，见 configRemoteProtectedKeys）",
|
||||
"keys", protected, "url", url)
|
||||
}
|
||||
}
|
||||
|
||||
func readConfig() {
|
||||
@@ -1098,7 +1062,6 @@ func readConfig() {
|
||||
CORS = os.Getenv("CORS")
|
||||
ACCESS_TOKEN = os.Getenv("ACCESS_TOKEN")
|
||||
TRUSTED_PROXIES = os.Getenv("TRUSTED_PROXIES")
|
||||
ssrf.SetEnabled(os.Getenv("BLOCK_PRIVATE_IPS") != "false" && os.Getenv("BLOCK_PRIVATE_IPS") != "0")
|
||||
|
||||
// SINGLE_STACK is intentionally excluded: empty string is a valid value (dual-stack).
|
||||
|
||||
@@ -1132,6 +1095,20 @@ func readConfig() {
|
||||
if TRUSTED_PROXIES == "" {
|
||||
TRUSTED_PROXIES = viper.GetString("trusted-proxies")
|
||||
}
|
||||
// block-private-ips：SSRF 防护开关，env 优先、其次 setting.json，缺省开启（见 ssrf 包）。
|
||||
// 必须在 viper.ReadInConfig 之后解析：早期版本只读 ENV，setting.json 里的同名键在启动阶段
|
||||
// 被静默忽略（只有运行中 patch / 远端配置才会生效），与本文件其余键的"env > setting.json"口径不一致。
|
||||
blockPrivateRaw := strings.TrimSpace(os.Getenv("BLOCK_PRIVATE_IPS"))
|
||||
if blockPrivateRaw == "" {
|
||||
blockPrivateRaw = strings.TrimSpace(viper.GetString("block-private-ips"))
|
||||
}
|
||||
ssrf.SetEnabled(blockPrivateRaw != "false" && blockPrivateRaw != "0")
|
||||
// OTA 升级开关：仅显式关闭才禁用（缺省允许收集中心下发 OTA，见 ota.go）
|
||||
otaRaw := strings.TrimSpace(os.Getenv("NODE_OTA"))
|
||||
if otaRaw == "" {
|
||||
otaRaw = strings.TrimSpace(viper.GetString("node-ota"))
|
||||
}
|
||||
NODE_OTA, _ = parseOTASwitch(otaRaw)
|
||||
if PORTS == "" {
|
||||
PORTS = "8080"
|
||||
}
|
||||
@@ -1159,10 +1136,22 @@ func readConfig() {
|
||||
if WS_NODE_KEY == "" {
|
||||
WS_NODE_KEY = viper.GetString("node-key")
|
||||
}
|
||||
// NODE_OTA：OTA 自更新开关（环境变量 NODE_OTA 或 setting.json 的 node-ota）
|
||||
NODE_OTA = os.Getenv("NODE_OTA")
|
||||
if NODE_OTA == "" {
|
||||
NODE_OTA = viper.GetString("node-ota")
|
||||
// 数据上报（report-url / report-token / report-interval-seconds），env 优先；详见 report.go
|
||||
REPORT_URL = os.Getenv("REPORT_URL")
|
||||
if REPORT_URL == "" {
|
||||
REPORT_URL = viper.GetString("report-url")
|
||||
}
|
||||
REPORT_TOKEN = os.Getenv("REPORT_TOKEN")
|
||||
if REPORT_TOKEN == "" {
|
||||
REPORT_TOKEN = viper.GetString("report-token")
|
||||
}
|
||||
REPORT_INTERVAL = viper.GetInt("report-interval-seconds")
|
||||
if v := os.Getenv("REPORT_INTERVAL_SECONDS"); v != "" {
|
||||
if n, err := strconv.Atoi(v); err == nil && n > 0 {
|
||||
REPORT_INTERVAL = n
|
||||
}
|
||||
} else if REPORT_INTERVAL <= 0 {
|
||||
REPORT_INTERVAL = 15
|
||||
}
|
||||
// REMOTE_IGNORE_CONFIG：不被远端覆盖的配置项列表（JSON 数组字符串，env 优先）
|
||||
if raw := os.Getenv("REMOTE_IGNORE_CONFIG"); raw != "" {
|
||||
@@ -1270,14 +1259,13 @@ func main() {
|
||||
|
||||
slog.Info("Starting server", "port", PORTS, "gh_proxy", GH_PROXY, "single_stack", SINGLE_STACK, "dns_server", DNS_SERVER, "CORS_ACCEPT", ACCEPT_DOMAINS)
|
||||
|
||||
// WS 客户端：接入中间件 WS 通道（配置 WS_URL 时启用，HTTP 接口不变）
|
||||
if WS_URL != "" {
|
||||
go wsClientLoop()
|
||||
slog.Info("WS client enabled", "url", WS_URL, "nodeId", WS_NODE_ID)
|
||||
}
|
||||
// WS 客户端：接入中间件 WS 通道（HTTP 接口不变）。
|
||||
// 控制器常驻——即使当前 ws-url 为空也启动，否则运行中把 ws-url 热更新进来时没有协程去接管；
|
||||
// 改 ws-url 由 reconcileWSClient 多退少补（无需重启），改 node-id / node-key 需重启进程。
|
||||
startWSClientController()
|
||||
|
||||
// OTA 自更新：定期检查 GitHub Release 并替换二进制（配置 NODE_OTA / node-ota 启用）
|
||||
initOTA(GH_PROXY)
|
||||
// 数据上报：WS 在线走 WS 广播，否则 HTTP POST 收集中心 /report（详见 report.go）
|
||||
startNodeReporter()
|
||||
|
||||
// 缓存清扫：各 sync.Map 只在同 key 重访时惰性淘汰过期条目，
|
||||
// 公网端点被唯一 key 洪打时内存会无限增长，这里定期清扫
|
||||
@@ -1315,6 +1303,7 @@ func main() {
|
||||
if ACCESS_TOKEN != "" {
|
||||
v1.Use(tokenCheck()) // Apply token check middleware to the v1 group
|
||||
}
|
||||
v1.Use(nodeReportMiddleware()) // 数据上报统计：归属规则过滤后计数（详见 report.go）
|
||||
{
|
||||
v1.GET("/detail/*url", checkWebsiteHandler)
|
||||
v1.GET("/ssl/*url", sslCheckHandler)
|
||||
@@ -1331,10 +1320,15 @@ func main() {
|
||||
}
|
||||
}
|
||||
|
||||
// 运行时配置接口（/v1/config）：鉴权同业务接口，但不计入拨测统计
|
||||
registerConfigRoutes(r)
|
||||
|
||||
// OTA 升级接口（POST /v1/ota）：收集中心 HTTP 回退通道，鉴权语义同 config（见 ota.go）
|
||||
registerOTARoute(r)
|
||||
|
||||
r.GET("/", healchCheck)
|
||||
|
||||
// 显式持有 http.Server：Windows OTA 优雅重启需要先 Shutdown 释放端口再拉起新进程，
|
||||
// 避免 r.Run 的隐式 Server 无法受控关闭、父子进程抢端口
|
||||
// 显式持有 http.Server：收到退出信号时先 Shutdown 释放端口，避免 r.Run 的隐式 Server 无法受控关闭
|
||||
httpServer = &http.Server{Handler: r}
|
||||
ln, err := net.Listen("tcp", ":"+PORTS)
|
||||
if err != nil {
|
||||
@@ -1349,16 +1343,16 @@ func main() {
|
||||
}
|
||||
}()
|
||||
|
||||
// Windows OTA：Server 被 restartSelf 的优雅停机关闭后，main 停在这里不退出，
|
||||
// 由 restartSelf 在新进程健康检查通过后 os.Exit 结束整个老进程
|
||||
if otaEnabled() && runtime.GOOS == "windows" {
|
||||
otaHandoverWait = make(chan struct{})
|
||||
<-otaHandoverWait
|
||||
}
|
||||
// main 必须阻塞，否则 Server goroutine 随 main 返回而消亡，进程启动后立即退出。
|
||||
// 阻塞在退出信号上，收到后走优雅停机。
|
||||
sigCh := make(chan os.Signal, 1)
|
||||
signal.Notify(sigCh, os.Interrupt, syscall.SIGTERM)
|
||||
<-sigCh
|
||||
gracefulShutdown()
|
||||
}
|
||||
|
||||
// gracefulShutdown 优雅停止 HTTP 服务：停止接收新请求，等待在途请求完成（上限 30s）。
|
||||
// 供 Windows OTA 在拉起新进程前调用，确保监听端口先释放、子进程能正常绑定。
|
||||
// 供收到退出信号时调用，确保监听端口先释放再退出进程。
|
||||
func gracefulShutdown() {
|
||||
if httpServer == nil {
|
||||
return
|
||||
|
||||
+304
-268
@@ -2,74 +2,247 @@ package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"crypto/sha256"
|
||||
"encoding/hex"
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"io"
|
||||
"log/slog"
|
||||
"math/rand"
|
||||
"net/http"
|
||||
"os"
|
||||
"os/exec"
|
||||
"path/filepath"
|
||||
"runtime"
|
||||
"strconv"
|
||||
"strings"
|
||||
"sync"
|
||||
"syscall"
|
||||
"time"
|
||||
|
||||
"resty.dev/v3"
|
||||
"github.com/coder/websocket"
|
||||
"github.com/gin-gonic/gin"
|
||||
)
|
||||
|
||||
// OTA 自更新：定期检查 GitHub Release，下载与当前平台匹配的新版二进制替换自身并重启。
|
||||
// 默认关闭，需显式开启（环境变量 NODE_OTA 或 setting.json 的 node-ota）。
|
||||
// ==================== OTA 升级（收集中心下发，节点执行） ====================
|
||||
//
|
||||
// 控制台（ipw-boce）经 WS 下发 type=ota 指令（或 HTTP 回退 POST /v1/ota，同 config 的鉴权语义），
|
||||
// 节点下载新二进制 → 校验 → 预检 → 原子替换 → 重启。下载源二选一：
|
||||
// - url 直发：直接下载该地址
|
||||
// - version + assetBase：节点按自身平台计算资产名 lemonipw-{goos}-{goarch}[.exe]
|
||||
// （GOARCH=arm 无法在运行时区分 GOARM，依次尝试 armv7/armv6/arm），拼出
|
||||
// {assetBase}/{version}/lemonipw-... 逐一尝试
|
||||
// - sha256 提供时强校验（hex，兼容 "sha256:" 前缀）
|
||||
//
|
||||
// 进度经 WS 回 type=ota_result {requestId, ok, stage, error}：
|
||||
// accepted → downloading → verifying → installing → restarting（ok=false 时 error 说明原因）。
|
||||
// 进程重启后连接必然断开，"最终结果"无法经原连接回传——收集中心以节点重连注册上报的
|
||||
// 新版本号判定成败（见 ipw-boce ota.go 的任务追踪）。
|
||||
//
|
||||
// 本地开关：node-ota=false（env NODE_OTA）时节点拒绝一切 OTA 指令并回传原因，
|
||||
// 供只读文件系统 / 编排托管的部署使用（替换二进制不可行，升级走各自部署渠道）。
|
||||
//
|
||||
// 交接逻辑与 middleware-go/ota.go 保持一致：
|
||||
// 预检 → 原子替换 → 优雅停机 → 拉起新进程 → 健康检查确认 → 老进程退出；失败回滚 .old。
|
||||
|
||||
const (
|
||||
otaReleaseAPI = "https://api.github.com/repos/nomdn/ipw-cn/releases/latest"
|
||||
otaFirstDelay = 5 * time.Minute // 启动后首次检查的延迟（避免与数据库下载冲突）
|
||||
otaCheckInterval = 6 * time.Hour // 常规检查间隔
|
||||
otaMinSize = 1 * 1024 * 1024 // 下载文件最小体积，防止拿到错误页/占位文件
|
||||
otaMinSize = 1 * 1024 * 1024 // 下载文件最小体积，防止拿到错误页/占位文件
|
||||
otaDownloadTimeout = 10 * time.Minute // 单次下载超时
|
||||
)
|
||||
|
||||
var (
|
||||
otaMu sync.Mutex
|
||||
otaLastRun time.Time
|
||||
)
|
||||
// otaAssetBaseDefault 按版本下发且未指定 assetBase 时的默认发布地址
|
||||
const otaAssetBaseDefault = "https://github.com/nomdn/ipw-cn/releases/download"
|
||||
|
||||
type otaRelease struct {
|
||||
TagName string `json:"tag_name"`
|
||||
Assets []struct {
|
||||
Name string `json:"name"`
|
||||
BrowserDownloadURL string `json:"browser_download_url"`
|
||||
Size int64 `json:"size"`
|
||||
} `json:"assets"`
|
||||
}
|
||||
|
||||
// otaEnabled 判断是否启用 OTA（"true" / "1" / "yes" / "on" 视为开启）
|
||||
func otaEnabled() bool {
|
||||
switch strings.ToLower(strings.TrimSpace(NODE_OTA)) {
|
||||
case "true", "1", "yes", "on":
|
||||
return true
|
||||
// parseOTASwitch 解析 OTA 开关的字面值——启动加载（ENV / setting.json）、远端下发、运行时 PATCH
|
||||
// 三处共用，保证什么算关闭的口径只有一份。
|
||||
//
|
||||
// 语义是缺省允许、显式关闭（见本文件头）：true/1/yes/on 与空值都算开启，
|
||||
// false/0/no/off 算关闭。known=false 表示写法认不出来——运行时 PATCH 据此回
|
||||
// unknown 且不覆盖原值，启动期与远端下发则按缺省（允许）处理，不因一个手滑的
|
||||
// 字面值把节点锁死。
|
||||
func parseOTASwitch(raw string) (enabled, known bool) {
|
||||
switch strings.ToLower(strings.TrimSpace(raw)) {
|
||||
case "", "true", "1", "yes", "on":
|
||||
return true, true
|
||||
case "false", "0", "no", "off":
|
||||
return false, true
|
||||
}
|
||||
return false
|
||||
return true, false
|
||||
}
|
||||
|
||||
// initOTA 在后台启动 OTA 检查循环，未启用时直接返回
|
||||
func initOTA(ghproxy string) {
|
||||
if !otaEnabled() {
|
||||
slog.Debug("OTA disabled")
|
||||
// otaMu 单飞：同一时刻只允许一个 OTA 任务（重复下发直接拒绝）
|
||||
var otaMu sync.Mutex
|
||||
|
||||
// otaRequest OTA 下发报文（WS ota 消息的 data 与 POST /v1/ota 的 body 同构）
|
||||
type otaRequest struct {
|
||||
RequestID string `json:"requestId"`
|
||||
URL string `json:"url"` // 直发下载地址（与 version 二选一，url 优先）
|
||||
Version string `json:"version"` // 目标版本（release tag，如 v1.2.3 / 1.2.3 均可）
|
||||
AssetBase string `json:"assetBase"` // 发布资产基址（version 模式用；空 = otaAssetBaseDefault）
|
||||
SHA256 string `json:"sha256"` // 可选，内容校验（hex64）
|
||||
}
|
||||
|
||||
// otaProgress 阶段回报函数：WS 触发时回 ota_result，HTTP 触发时为 nil（只记日志）
|
||||
type otaProgress func(ok bool, stage, errMsg string)
|
||||
|
||||
// ==================== WS 入口 ====================
|
||||
|
||||
// wsHandleOTA 处理收集中心下发的 OTA 指令（ws.go type=ota 调用）。
|
||||
// 先同步回 accepted 表明节点认识该指令（老版本节点静默忽略，收集中心据此给出过旧提示），
|
||||
// 再异步执行下载/替换/重启。
|
||||
func wsHandleOTA(c *websocket.Conn, data []byte) {
|
||||
var req otaRequest
|
||||
if err := json.Unmarshal(data, &req); err != nil {
|
||||
otaReport(c, req.RequestID, false, "accepted", "bad payload: "+err.Error())
|
||||
return
|
||||
}
|
||||
slog.Info("OTA enabled", "current_version", VERSION, "check_interval", otaCheckInterval.String())
|
||||
// 本地开关（node-ota=false，只读容器等不可自更新部署）：明确拒绝并回传原因，
|
||||
// 收集中心据此立即判任务失败，而不是干等超时
|
||||
if !NODE_OTA {
|
||||
otaReport(c, req.RequestID, false, "accepted", "节点已禁用 OTA（node-ota=false）")
|
||||
return
|
||||
}
|
||||
otaReport(c, req.RequestID, true, "accepted", "")
|
||||
go otaRun(req, func(ok bool, stage, errMsg string) {
|
||||
otaReport(c, req.RequestID, ok, stage, errMsg)
|
||||
})
|
||||
}
|
||||
|
||||
go func() {
|
||||
// 首次延迟，避免启动瞬间与数据库下载抢占带宽或触发重启
|
||||
time.Sleep(otaFirstDelay)
|
||||
for {
|
||||
checkOTAUpdate(ghproxy)
|
||||
jitter := time.Duration(rand.Int63n(int64(time.Hour)))
|
||||
time.Sleep(otaCheckInterval + jitter)
|
||||
// otaReport 回一帧 ota_result（进度或失败原因）
|
||||
func otaReport(c *websocket.Conn, requestID string, ok bool, stage, errMsg string) {
|
||||
if c == nil {
|
||||
return
|
||||
}
|
||||
wsSend(c, wsMsg{Type: "ota_result", Data: wsRaw(map[string]any{
|
||||
"requestId": requestID, "ok": ok, "stage": stage, "error": errMsg,
|
||||
})})
|
||||
}
|
||||
|
||||
// ==================== HTTP 入口 ====================
|
||||
|
||||
// registerOTARoute 注册 POST /v1/ota（收集中心 HTTP 回退通道）。
|
||||
// 鉴权与 /v1/config 一致：access-token 未配置时整个 HTTP OTA 管理面关闭（RCE 面不能裸奔）。
|
||||
func registerOTARoute(r *gin.Engine) {
|
||||
g := r.Group("/v1/ota")
|
||||
if ACCESS_TOKEN == "" {
|
||||
slog.Warn("ota HTTP API disabled: access-token not set, use WS channel instead")
|
||||
g.POST("", func(c *gin.Context) {
|
||||
c.AbortWithStatusJSON(http.StatusForbidden, gin.H{
|
||||
"error": "OTA 接口已关闭：节点未配置 access-token，请通过 WS 通道下发",
|
||||
})
|
||||
})
|
||||
return
|
||||
}
|
||||
g.Use(tokenCheck())
|
||||
g.POST("", func(c *gin.Context) {
|
||||
if !NODE_OTA {
|
||||
c.JSON(http.StatusForbidden, gin.H{"error": "节点已禁用 OTA（node-ota=false）"})
|
||||
return
|
||||
}
|
||||
}()
|
||||
var req otaRequest
|
||||
if err := c.ShouldBindJSON(&req); err != nil {
|
||||
c.JSON(http.StatusBadRequest, gin.H{"error": "invalid payload: " + err.Error()})
|
||||
return
|
||||
}
|
||||
if err := otaValidate(&req); err != nil {
|
||||
c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
|
||||
return
|
||||
}
|
||||
// 异步执行：下载可能耗时数分钟，HTTP 无进度通道，结果看节点日志与重连后的版本号
|
||||
go otaRun(req, nil)
|
||||
c.JSON(http.StatusAccepted, gin.H{"ok": true, "started": true})
|
||||
})
|
||||
}
|
||||
|
||||
// otaValidate 校验下发参数（url 与 version 至少其一；sha256 合法时规整为小写 hex64）
|
||||
func otaValidate(req *otaRequest) error {
|
||||
req.URL = strings.TrimSpace(req.URL)
|
||||
req.Version = strings.TrimSpace(req.Version)
|
||||
req.SHA256 = strings.TrimSpace(strings.TrimPrefix(strings.TrimSpace(req.SHA256), "sha256:"))
|
||||
if req.URL == "" && req.Version == "" {
|
||||
return fmt.Errorf("url 与 version 至少填一项")
|
||||
}
|
||||
if req.URL != "" {
|
||||
if !strings.HasPrefix(req.URL, "http://") && !strings.HasPrefix(req.URL, "https://") {
|
||||
return fmt.Errorf("url 必须是 http(s) 地址")
|
||||
}
|
||||
}
|
||||
if req.SHA256 != "" {
|
||||
if len(req.SHA256) != 64 {
|
||||
return fmt.Errorf("sha256 必须是 64 位 hex")
|
||||
}
|
||||
if _, err := hex.DecodeString(req.SHA256); err != nil {
|
||||
return fmt.Errorf("sha256 必须是合法 hex")
|
||||
}
|
||||
req.SHA256 = strings.ToLower(req.SHA256)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// ==================== 执行引擎 ====================
|
||||
|
||||
// otaRun 执行 OTA：解析下载源 → 下载校验 → 预检 → 替换 → 重启。
|
||||
// 每个 ok=false 的阶段回报后终止；重启前的最后回报是 "restarting"（连接随后断开）。
|
||||
func otaRun(req otaRequest, progress otaProgress) {
|
||||
report := func(ok bool, stage, errMsg string) {
|
||||
if errMsg == "" {
|
||||
slog.Info("[ota]", "stage", stage, "ok", ok)
|
||||
} else {
|
||||
slog.Info("[ota]", "stage", stage, "ok", ok, "msg", errMsg)
|
||||
}
|
||||
if progress != nil {
|
||||
progress(ok, stage, errMsg)
|
||||
}
|
||||
}
|
||||
|
||||
if !otaMu.TryLock() {
|
||||
report(false, "accepted", "已有 OTA 任务在执行中，请稍后再试")
|
||||
return
|
||||
}
|
||||
defer otaMu.Unlock()
|
||||
|
||||
if err := otaValidate(&req); err != nil {
|
||||
report(false, "accepted", err.Error())
|
||||
return
|
||||
}
|
||||
|
||||
exePath, err := os.Executable()
|
||||
if err != nil {
|
||||
report(false, "accepted", "cannot locate executable: "+err.Error())
|
||||
return
|
||||
}
|
||||
exePath, err = filepath.EvalSymlinks(exePath)
|
||||
if err != nil {
|
||||
report(false, "accepted", "cannot resolve executable path: "+err.Error())
|
||||
return
|
||||
}
|
||||
|
||||
// 下载到与目标同分区（保证 rename 原子替换）
|
||||
tmpPath := filepath.Join(filepath.Dir(exePath), "ota-update.tmp")
|
||||
report(true, "downloading", "")
|
||||
if err := otaDownload(req, tmpPath); err != nil {
|
||||
_ = os.Remove(tmpPath)
|
||||
report(false, "downloading", err.Error())
|
||||
return
|
||||
}
|
||||
|
||||
// 预检：试运行新二进制（-v 打印版本即退出），损坏/架构不符的文件在停机前就拦下
|
||||
report(true, "verifying", "")
|
||||
if err := preflightBinary(tmpPath); err != nil {
|
||||
_ = os.Remove(tmpPath)
|
||||
report(false, "verifying", err.Error())
|
||||
return
|
||||
}
|
||||
|
||||
report(true, "installing", "")
|
||||
if err := replaceBinary(tmpPath, exePath); err != nil {
|
||||
report(false, "installing", err.Error())
|
||||
return
|
||||
}
|
||||
|
||||
report(true, "restarting", "")
|
||||
// 给 WS 把 restarting 帧写出去留一点时间，然后交接（连接随进程结束断开）
|
||||
time.Sleep(300 * time.Millisecond)
|
||||
slog.Info("[ota] binary replaced, restarting")
|
||||
restartSelf(exePath)
|
||||
}
|
||||
|
||||
// otaAssetNames 按优先级返回当前平台可能的发布资产名（与 build_and_release.yml 命名一致）
|
||||
@@ -78,223 +251,103 @@ func otaAssetNames() []string {
|
||||
if runtime.GOOS == "windows" {
|
||||
suffix = ".exe"
|
||||
}
|
||||
arch := runtime.GOARCH
|
||||
// GOARCH=arm 时无法在运行时区分 GOARM（armv7/armv6），依次尝试
|
||||
if runtime.GOOS == "linux" && arch == "arm" {
|
||||
return []string{
|
||||
"lemonipw-linux-armv7",
|
||||
"lemonipw-linux-armv6",
|
||||
"lemonipw-linux-arm",
|
||||
}
|
||||
if runtime.GOOS == "linux" && runtime.GOARCH == "arm" {
|
||||
return []string{"lemonipw-linux-armv7", "lemonipw-linux-armv6", "lemonipw-linux-arm"}
|
||||
}
|
||||
return []string{fmt.Sprintf("lemonipw-%s-%s%s", runtime.GOOS, arch, suffix)}
|
||||
return []string{fmt.Sprintf("lemonipw-%s-%s%s", runtime.GOOS, runtime.GOARCH, suffix)}
|
||||
}
|
||||
|
||||
// compareVersion 比较版本号：latest > current 返回正数，相等返回 0，否则返回负数；
|
||||
// 非数字段按字典序比较。latest 为空（无法获取远端版本）时返回 0，不做更新。
|
||||
func compareVersion(latest, current string) int {
|
||||
if strings.TrimSpace(latest) == "" {
|
||||
return 0
|
||||
}
|
||||
trim := func(s string) string {
|
||||
s = strings.TrimSpace(s)
|
||||
s = strings.TrimPrefix(s, "v")
|
||||
s = strings.TrimPrefix(s, "V")
|
||||
if i := strings.IndexAny(s, "-+"); i >= 0 { // 忽略预发布后缀
|
||||
s = s[:i]
|
||||
// otaDownload 把下发参数解析成候选下载地址并下载到 dst（url 直发只有一个候选；
|
||||
// version 模式按平台资产名生成多个候选逐一尝试）
|
||||
func otaDownload(req otaRequest, dst string) error {
|
||||
var urls []string
|
||||
if req.URL != "" {
|
||||
urls = []string{req.URL}
|
||||
} else {
|
||||
base := strings.TrimSuffix(strings.TrimSpace(req.AssetBase), "/")
|
||||
if base == "" {
|
||||
base = otaAssetBaseDefault
|
||||
}
|
||||
return s
|
||||
}
|
||||
a := strings.Split(trim(latest), ".")
|
||||
b := strings.Split(trim(current), ".")
|
||||
for i := 0; i < len(a) || i < len(b); i++ {
|
||||
var x, y int
|
||||
var xe, ye error
|
||||
if i < len(a) {
|
||||
x, xe = strconv.Atoi(a[i])
|
||||
tag := req.Version
|
||||
if !strings.HasPrefix(tag, "v") {
|
||||
tag = "v" + tag // 本仓库 release 一律 v 前缀（CI 由 v* 标签触发），宽容无前缀写法
|
||||
}
|
||||
if i < len(b) {
|
||||
y, ye = strconv.Atoi(b[i])
|
||||
}
|
||||
switch {
|
||||
case xe == nil && ye == nil:
|
||||
if x != y {
|
||||
return x - y
|
||||
}
|
||||
case xe == nil: // 只有当前版本非数字
|
||||
return 1
|
||||
case ye == nil:
|
||||
return -1
|
||||
default: // 两段都非数字，按字典序
|
||||
if a[i] != b[i] {
|
||||
if a[i] > b[i] {
|
||||
return 1
|
||||
}
|
||||
return -1
|
||||
for _, name := range otaAssetNames() {
|
||||
u := fmt.Sprintf("%s/%s/%s", base, tag, name)
|
||||
// 延续原版自更新的加速语义：GitHub 官方基址且节点配了 gh-proxy 时自动加前缀；
|
||||
// url 直发不改写（管理员指定的地址保持原样）
|
||||
if GH_PROXY != "" && strings.Contains(base, "github.com") {
|
||||
u = strings.TrimRight(GH_PROXY, "/") + "/" + u
|
||||
}
|
||||
urls = append(urls, u)
|
||||
}
|
||||
}
|
||||
return 0
|
||||
}
|
||||
|
||||
// majorSame 判断 latest 与 current 的 major 段是否相同。
|
||||
// 任一段无法解析（如本地构建 VERSION 为空）时返回 true（放行，不拦截更新）。
|
||||
func majorSame(latest, current string) bool {
|
||||
parseMajor := func(s string) (int, bool) {
|
||||
s = strings.TrimSpace(s)
|
||||
s = strings.TrimPrefix(s, "v")
|
||||
s = strings.TrimPrefix(s, "V")
|
||||
if i := strings.IndexAny(s, "-+."); i >= 0 {
|
||||
s = s[:i]
|
||||
var lastErr error
|
||||
for _, u := range urls {
|
||||
err := otaDownloadOne(u, dst, req.SHA256)
|
||||
if err == nil {
|
||||
return nil
|
||||
}
|
||||
n, err := strconv.Atoi(s)
|
||||
if err != nil {
|
||||
return 0, false
|
||||
}
|
||||
return n, true
|
||||
slog.Warn("[ota] download candidate failed", "url", u, "error", err)
|
||||
lastErr = err
|
||||
_ = os.Remove(dst)
|
||||
}
|
||||
lm, lok := parseMajor(latest)
|
||||
cm, cok := parseMajor(current)
|
||||
if !lok || !cok {
|
||||
return true
|
||||
}
|
||||
return lm == cm
|
||||
return lastErr
|
||||
}
|
||||
|
||||
// fetchLatestRelease 查询 GitHub 最新 Release 信息
|
||||
func fetchLatestRelease() (*otaRelease, error) {
|
||||
client := resty.New().SetTimeout(30 * time.Second)
|
||||
defer client.Close()
|
||||
|
||||
resp, err := client.R().
|
||||
SetHeader("Accept", "application/vnd.github+json").
|
||||
SetHeader("User-Agent", "lemon-ipw-ota").
|
||||
Get(otaReleaseAPI)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
if resp.IsError() {
|
||||
return nil, fmt.Errorf("HTTP %d", resp.StatusCode())
|
||||
}
|
||||
var rel otaRelease
|
||||
if err := json.Unmarshal(resp.Bytes(), &rel); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
if rel.TagName == "" {
|
||||
return nil, fmt.Errorf("empty tag_name")
|
||||
}
|
||||
return &rel, nil
|
||||
}
|
||||
|
||||
// findAssetURL 在 Release 资产中查找当前平台的下载链接，同时返回资产大小用于完整性校验
|
||||
func findAssetURL(rel *otaRelease) (string, string, int64) {
|
||||
for _, want := range otaAssetNames() {
|
||||
for _, a := range rel.Assets {
|
||||
if a.Name == want {
|
||||
return a.BrowserDownloadURL, a.Name, a.Size
|
||||
}
|
||||
}
|
||||
}
|
||||
return "", "", 0
|
||||
}
|
||||
|
||||
// checkOTAUpdate 执行一次检查：有新版本则下载替换并重启
|
||||
func checkOTAUpdate(ghproxy string) {
|
||||
otaMu.Lock()
|
||||
defer otaMu.Unlock()
|
||||
otaLastRun = time.Now()
|
||||
|
||||
rel, err := fetchLatestRelease()
|
||||
if err != nil {
|
||||
slog.Warn("OTA check failed", "error", err)
|
||||
return
|
||||
}
|
||||
|
||||
cmp := compareVersion(rel.TagName, VERSION)
|
||||
if cmp <= 0 {
|
||||
slog.Debug("OTA already up to date", "latest", rel.TagName, "current", VERSION)
|
||||
return
|
||||
}
|
||||
|
||||
// major 版本变化（如 3.x → 4.x）通常含破坏性变更，不自动更新，需人工升级
|
||||
if !majorSame(rel.TagName, VERSION) {
|
||||
slog.Warn("OTA skipped: major version upgrade requires manual action",
|
||||
"latest", rel.TagName, "current", VERSION)
|
||||
return
|
||||
}
|
||||
|
||||
assetURL, assetName, assetSize := findAssetURL(rel)
|
||||
if assetURL == "" {
|
||||
slog.Warn("OTA no matching asset for this platform",
|
||||
"tag", rel.TagName, "goos", runtime.GOOS, "goarch", runtime.GOARCH)
|
||||
return
|
||||
}
|
||||
|
||||
slog.Info("OTA new version found", "tag", rel.TagName, "current", VERSION, "asset", assetName)
|
||||
|
||||
exePath, err := os.Executable()
|
||||
if err != nil {
|
||||
slog.Error("OTA cannot locate executable", "error", err)
|
||||
return
|
||||
}
|
||||
exePath, err = filepath.EvalSymlinks(exePath)
|
||||
if err != nil {
|
||||
slog.Error("OTA cannot resolve executable path", "error", err)
|
||||
return
|
||||
}
|
||||
|
||||
// 下载到同目录（保证与目标同分区，rename 原子替换），
|
||||
// 临时文件使用远端资产名（如 lemonipw-linux-amd64）+ .tmp 后缀，避免与运行中的 exe 冲突
|
||||
tmpPath := filepath.Join(filepath.Dir(exePath), assetName+".tmp")
|
||||
if err := downloadOTA(ghproxy+assetURL, tmpPath, assetSize); err != nil {
|
||||
slog.Error("OTA download failed", "error", err)
|
||||
os.Remove(tmpPath)
|
||||
return
|
||||
}
|
||||
|
||||
// 预检：停机前先试运行新二进制（-v 打印版本即退出），确认文件可执行、架构匹配。
|
||||
// 损坏/被杀毒隔离的文件若直到交接时才发现，子进程会秒退导致服务中断
|
||||
if err := preflightBinary(tmpPath); err != nil {
|
||||
slog.Error("OTA preflight failed, keep current version", "error", err)
|
||||
os.Remove(tmpPath)
|
||||
return
|
||||
}
|
||||
|
||||
if err := replaceBinary(tmpPath, exePath); err != nil {
|
||||
slog.Error("OTA replace failed", "error", err)
|
||||
return
|
||||
}
|
||||
|
||||
slog.Info("OTA binary replaced, restarting", "tag", rel.TagName)
|
||||
restartSelf(exePath)
|
||||
}
|
||||
|
||||
// downloadOTA 下载二进制到临时文件，并做体积校验（Release 声明的资产大小精确比对 + 最小体积兜底）。
|
||||
// 注意：GitHub Release 未提供签名/哈希清单，无法做内容级认证，体积校验只能防截断与错装文件。
|
||||
func downloadOTA(url, dst string, expectSize int64) error {
|
||||
client := resty.New().SetTimeout(10 * time.Minute)
|
||||
defer client.Close()
|
||||
|
||||
resp, err := client.R().SetOutputFileName(dst).SetSaveResponse(true).Get(url)
|
||||
// otaDownloadOne 下载单个地址到 dst：体积下限 + 可选 sha256 强校验
|
||||
func otaDownloadOne(url, dst, wantSHA string) error {
|
||||
client := &http.Client{Timeout: otaDownloadTimeout}
|
||||
resp, err := client.Get(url)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
if resp.IsError() {
|
||||
return fmt.Errorf("HTTP %d", resp.StatusCode())
|
||||
defer resp.Body.Close()
|
||||
if resp.StatusCode != http.StatusOK {
|
||||
return fmt.Errorf("HTTP %d", resp.StatusCode)
|
||||
}
|
||||
f, err := os.Create(dst)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
hash := sha256.New()
|
||||
_, copyErr := io.Copy(io.MultiWriter(f, hash), resp.Body)
|
||||
closeErr := f.Close()
|
||||
if copyErr != nil || closeErr != nil {
|
||||
_ = os.Remove(dst)
|
||||
if copyErr != nil {
|
||||
return copyErr
|
||||
}
|
||||
return closeErr
|
||||
}
|
||||
fi, err := os.Stat(dst)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
if fi.Size() < otaMinSize {
|
||||
_ = os.Remove(dst)
|
||||
return fmt.Errorf("downloaded file too small: %d bytes", fi.Size())
|
||||
}
|
||||
if expectSize > 0 && fi.Size() != expectSize {
|
||||
return fmt.Errorf("downloaded size mismatch: got %d, want %d", fi.Size(), expectSize)
|
||||
if wantSHA != "" {
|
||||
got := hex.EncodeToString(hash.Sum(nil))
|
||||
if !strings.EqualFold(got, wantSHA) {
|
||||
_ = os.Remove(dst)
|
||||
return fmt.Errorf("sha256 mismatch: got %s", got)
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// preflightBinary 试运行新二进制（-v 自检：打印版本后立即退出，不读配置不占端口），
|
||||
// 确认文件可执行、架构匹配。10s 超时防损坏文件卡死。
|
||||
func preflightBinary(path string) error {
|
||||
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
|
||||
defer cancel()
|
||||
return exec.CommandContext(ctx, path, "-v").Run()
|
||||
}
|
||||
|
||||
// replaceBinary 用新二进制替换当前可执行文件：
|
||||
// 1) 当前二进制改名为 .old（Windows 下运行中的 exe 不能删除，但可以重命名）
|
||||
// 2) 新文件 rename 到原位置；失败则回滚
|
||||
@@ -311,20 +364,16 @@ func replaceBinary(tmpPath, exePath string) error {
|
||||
}
|
||||
if runtime.GOOS != "windows" {
|
||||
if err := os.Chmod(exePath, 0o755); err != nil {
|
||||
slog.Warn("OTA chmod failed", "error", err)
|
||||
slog.Warn("[ota] chmod failed", "error", err)
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// restartSelf 用新二进制重启进程：
|
||||
// - Unix：syscall.Exec 原地替换进程镜像（PID 不变，systemd/Docker 无感；Go 的 socket 带
|
||||
// CLOEXEC，exec 瞬间旧监听关闭、新进程正常重绑）
|
||||
// - Unix：syscall.Exec 原地替换进程镜像（PID 不变，systemd/Docker 无感）
|
||||
// - Windows：运行中的 exe 只能重命名不能替换，采用优雅交接：
|
||||
// 1) 优雅停机：停止接收新请求并等待在途请求完成，端口释放
|
||||
// 2) 拉起新进程：端口已空闲，子进程可正常绑定（旧实现先 os.Exit 再赌子进程抢端口，
|
||||
// 输了就"Server failed to start"退出且 Windows 无守护接管，节点直接下线）
|
||||
// 3) 轮询子进程健康检查通过后老进程才退出；超时则以退出码 1 结束
|
||||
// 优雅停机（端口释放）→ 拉起新进程 → 健康检查通过后老进程退出；失败回滚 .old
|
||||
func restartSelf(exePath string) {
|
||||
if runtime.GOOS == "windows" {
|
||||
gracefulShutdown()
|
||||
@@ -334,45 +383,32 @@ func restartSelf(exePath string) {
|
||||
cmd.Stderr = os.Stderr
|
||||
cmd.Env = os.Environ()
|
||||
if err := cmd.Start(); err != nil {
|
||||
slog.Error("OTA restart failed, waiting for supervisor", "error", err)
|
||||
slog.Error("[ota] restart failed, waiting for supervisor", "error", err)
|
||||
os.Exit(1)
|
||||
}
|
||||
|
||||
if waitChildReady(cmd, 10*time.Minute) {
|
||||
slog.Info("OTA new process ready, old process exiting", "new_pid", cmd.Process.Pid)
|
||||
if otaWaitChildReady(cmd, 10*time.Minute) {
|
||||
slog.Info("[ota] new process ready, old process exiting", "new_pid", cmd.Process.Pid)
|
||||
os.Exit(0)
|
||||
}
|
||||
slog.Error("OTA new process not ready (exited or timed out), rolling back", "new_pid", cmd.Process.Pid)
|
||||
slog.Error("[ota] new process not ready (exited or timed out), rolling back", "new_pid", cmd.Process.Pid)
|
||||
|
||||
// 回滚：新版本起不来，用 .old 备份恢复服务，而不是陪它一起下线
|
||||
if rollbackToOld(exePath) {
|
||||
slog.Warn("OTA rolled back to previous version, old process exiting")
|
||||
if otaRollbackToOld(exePath) {
|
||||
slog.Warn("[ota] rolled back to previous version, old process exiting")
|
||||
os.Exit(0)
|
||||
}
|
||||
os.Exit(1)
|
||||
}
|
||||
|
||||
if err := syscall.Exec(exePath, os.Args, os.Environ()); err != nil {
|
||||
slog.Error("OTA exec failed, wait for supervisor to restart", "error", err)
|
||||
slog.Error("[ota] exec failed, wait for supervisor to restart", "error", err)
|
||||
os.Exit(1)
|
||||
}
|
||||
}
|
||||
|
||||
// preflightBinary 试运行新二进制（-v 自检：打印版本后立即退出，不读配置不占端口），
|
||||
// 确认文件可执行、架构匹配。10s 超时防损坏文件卡死。
|
||||
func preflightBinary(path string) error {
|
||||
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
|
||||
defer cancel()
|
||||
// Stdout/Stderr 为 nil 时输出直接丢弃
|
||||
return exec.CommandContext(ctx, path, "-v").Run()
|
||||
}
|
||||
|
||||
// waitChildReady 轮询新进程的健康检查接口（GET /），确认其完成端口绑定并对外服务。
|
||||
// otaWaitChildReady 轮询新进程的健康检查接口（GET /），确认其完成端口绑定并对外服务。
|
||||
// 返回 true = 就绪；false = 子进程启动期间退出（立即判定失败）或超时未就绪。
|
||||
// 超时给足 10 分钟：子进程在数据库文件缺失时（首次启动/文件损坏）会同步拉取约 450MB
|
||||
// 库文件后才监听端口，属正常慢启动而非故障——所以判定失败的依据是"子进程退出"
|
||||
// （进程死了立即返回），而不是固定超时。
|
||||
func waitChildReady(cmd *exec.Cmd, timeout time.Duration) bool {
|
||||
func otaWaitChildReady(cmd *exec.Cmd, timeout time.Duration) bool {
|
||||
client := &http.Client{Timeout: 2 * time.Second}
|
||||
url := "http://127.0.0.1:" + PORTS + "/"
|
||||
deadline := time.Now().Add(timeout)
|
||||
@@ -400,22 +436,22 @@ func waitChildReady(cmd *exec.Cmd, timeout time.Duration) bool {
|
||||
}
|
||||
}
|
||||
|
||||
// rollbackToOld 用 .old 备份恢复服务：新版本起不来时，把旧二进制换回原位并重新拉起。
|
||||
// 返回 true 表示旧版本已就绪。恢复失败时尽力把新二进制挪回原位后返回 false。
|
||||
func rollbackToOld(exePath string) bool {
|
||||
// otaRollbackToOld 用 .old 备份恢复服务：新版本起不来时，把旧二进制换回原位并重新拉起。
|
||||
// 返回 true 表示旧版本已就绪。
|
||||
func otaRollbackToOld(exePath string) bool {
|
||||
oldPath := exePath + ".old"
|
||||
if _, err := os.Stat(oldPath); err != nil {
|
||||
slog.Error("OTA rollback skipped: no .old backup", "error", err)
|
||||
slog.Error("[ota] rollback skipped: no .old backup", "error", err)
|
||||
return false
|
||||
}
|
||||
failed := exePath + ".failed"
|
||||
_ = os.Remove(failed)
|
||||
if err := os.Rename(exePath, failed); err != nil {
|
||||
slog.Error("OTA rollback: cannot move failed binary", "error", err)
|
||||
slog.Error("[ota] rollback: cannot move failed binary", "error", err)
|
||||
return false
|
||||
}
|
||||
if err := os.Rename(oldPath, exePath); err != nil {
|
||||
slog.Error("OTA rollback: cannot restore old binary", "error", err)
|
||||
slog.Error("[ota] rollback: cannot restore old binary", "error", err)
|
||||
_ = os.Rename(failed, exePath) // 尽力恢复现场
|
||||
return false
|
||||
}
|
||||
@@ -424,13 +460,13 @@ func rollbackToOld(exePath string) bool {
|
||||
cmd.Stderr = os.Stderr
|
||||
cmd.Env = os.Environ()
|
||||
if err := cmd.Start(); err != nil {
|
||||
slog.Error("OTA rollback: cannot start old binary", "error", err)
|
||||
slog.Error("[ota] rollback: cannot start old binary", "error", err)
|
||||
return false
|
||||
}
|
||||
if waitChildReady(cmd, 10*time.Minute) {
|
||||
slog.Warn("OTA rollback serving traffic on previous version", "pid", cmd.Process.Pid)
|
||||
if otaWaitChildReady(cmd, 10*time.Minute) {
|
||||
slog.Warn("[ota] rollback serving traffic on previous version", "pid", cmd.Process.Pid)
|
||||
return true
|
||||
}
|
||||
slog.Error("OTA rollback: old binary also failed to become ready")
|
||||
slog.Error("[ota] rollback: old binary also failed to become ready")
|
||||
return false
|
||||
}
|
||||
+322
@@ -0,0 +1,322 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"log/slog"
|
||||
"net/http"
|
||||
"os"
|
||||
"strings"
|
||||
"sync"
|
||||
"time"
|
||||
|
||||
"github.com/coder/websocket"
|
||||
"github.com/gin-gonic/gin"
|
||||
)
|
||||
|
||||
// ==================== 数据上报（节点 → 收集中心 ipw-boce） ====================
|
||||
//
|
||||
// 节点是唯一记录者：统计与拨测明细都由本节点上报，中间件不在转发路径上计数，不存在双算。
|
||||
// 上报通道（报文同构，协议定义见 ipw-boce 的 report.go）：
|
||||
// - WS 客户端启用（WS_URL 配置且至少一条连接在线）→ 经 WS 发 {"type":"report","data":...}
|
||||
// - WS 未启用或全部连接掉线 → HTTP POST 到收集中心 /report（REPORT_URL）
|
||||
//
|
||||
// 两条来源都要上报：
|
||||
// - HTTP 接口收到的请求（/v1/*）→ nodeReportMiddleware 计数
|
||||
// - 中间件经 WS 下发的拨测（probe）→ nodeRecordWSProbe 计数
|
||||
|
||||
const (
|
||||
reportMaxProbes = 500
|
||||
reportMaxStats = 500
|
||||
)
|
||||
|
||||
var (
|
||||
nodeStatsMu sync.Mutex
|
||||
nodeStats = map[string]*nodeStatVal{} // apiType → 计数
|
||||
nodeProbeCh chan nodeProbeRec
|
||||
nodeProbeDropN int64
|
||||
nodeDropMu sync.Mutex
|
||||
)
|
||||
|
||||
type nodeStatVal struct {
|
||||
total, errs, latSum, latMax int64
|
||||
}
|
||||
|
||||
// nodeProbeRec 一条拨测明细（结构与 ipw-boce reportProbe 对齐）
|
||||
type nodeProbeRec struct {
|
||||
RequestID string `json:"requestId,omitempty"`
|
||||
NodeID string `json:"nodeId"`
|
||||
APIType string `json:"apiType"`
|
||||
Raw string `json:"raw"`
|
||||
Query string `json:"query,omitempty"`
|
||||
Status int `json:"status"`
|
||||
LatencyMs int64 `json:"latencyMs"`
|
||||
Error string `json:"error,omitempty"`
|
||||
Source string `json:"source,omitempty"`
|
||||
Body string `json:"body,omitempty"`
|
||||
CreatedAt int64 `json:"createdAt,omitempty"`
|
||||
}
|
||||
|
||||
// nodeIsProbeType 拨测类接口（结果需明细上报）。
|
||||
// 明细覆盖：连通性/证书类 detail、ssl，DNS 查询类 dns，直连类 tcping/speed。
|
||||
// dnssec 属功能性校验（结果是否签名/可信），不逐条进明细，只进统计聚合。
|
||||
func nodeIsProbeType(apiType string) bool {
|
||||
switch apiType {
|
||||
case "tcping", "speed", "detail", "ssl", "dns":
|
||||
return true
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
// startNodeReporter 启动上报循环（main() 调用）。
|
||||
// 循环常驻：上报通道（ws-url / report-url）都可能被热更新启用；若沿用"启动时没有通道就不启动"，
|
||||
// 后续热更新出通道也不会有人上报。
|
||||
func startNodeReporter() {
|
||||
if REPORT_INTERVAL <= 0 {
|
||||
REPORT_INTERVAL = 15
|
||||
}
|
||||
nodeProbeCh = make(chan nodeProbeRec, 2048)
|
||||
go nodeReportLoop()
|
||||
slog.Info("node reporter enabled", "ws", WS_URL != "", "httpFallback", REPORT_URL, "interval", REPORT_INTERVAL)
|
||||
}
|
||||
|
||||
// nodeReportMiddleware /v1 组统计中间件：归属规则过滤 → 计数 → 拨测类补明细
|
||||
func nodeReportMiddleware() gin.HandlerFunc {
|
||||
return func(c *gin.Context) {
|
||||
start := time.Now()
|
||||
c.Next()
|
||||
|
||||
// 收集中心(ipw-boce)主动调度下发的拨测带 X-Scheduler-Probe 头：
|
||||
// 该次执行由收集中心侧本地落库(source=sched/biz)，本节点跳过计数与明细上报，避免双算。
|
||||
// 真实业务请求（用户/中间件转发）不带此头，仍按"节点是唯一记录者"正常上报。
|
||||
if c.Request.Header.Get("X-Scheduler-Probe") != "" {
|
||||
return
|
||||
}
|
||||
|
||||
apiType, raw := nodeAPIFromPath(c)
|
||||
if apiType == "" {
|
||||
return
|
||||
}
|
||||
latency := time.Since(start)
|
||||
status := c.Writer.Status()
|
||||
nodeRecordAPI(apiType, status, latency)
|
||||
if nodeIsProbeType(apiType) {
|
||||
nodeRecordProbe(nodeProbeRec{
|
||||
NodeID: nodeReportNodeID(), APIType: apiType, Raw: raw,
|
||||
Query: c.Request.URL.RawQuery, Status: status, LatencyMs: latency.Milliseconds(),
|
||||
Source: "http", CreatedAt: time.Now().Unix(),
|
||||
})
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// nodeRecordWSProbe WS 拨测出口（ws.go wsHandleProbe 调用）。
|
||||
// 中间件已不在转发路径上计数，WS 下发的拨测同样由本节点上报（唯一记录者）；
|
||||
// requestId 只作为明细的关联标识带出，不参与归属判断。
|
||||
func nodeRecordWSProbe(requestID, apiType, raw string, query map[string]string, status int, latency time.Duration) {
|
||||
if apiType == "" {
|
||||
return
|
||||
}
|
||||
nodeRecordAPI(apiType, status, latency)
|
||||
if nodeIsProbeType(apiType) {
|
||||
q := ""
|
||||
for k, v := range query {
|
||||
if q != "" {
|
||||
q += "&"
|
||||
}
|
||||
q += k + "=" + v
|
||||
}
|
||||
nodeRecordProbe(nodeProbeRec{
|
||||
RequestID: requestID,
|
||||
NodeID: nodeReportNodeID(), APIType: apiType, Raw: raw, Query: q,
|
||||
Status: status, LatencyMs: latency.Milliseconds(), Source: "ws",
|
||||
CreatedAt: time.Now().Unix(),
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
func nodeRecordAPI(apiType string, status int, latency time.Duration) {
|
||||
ms := latency.Milliseconds()
|
||||
nodeStatsMu.Lock()
|
||||
v, ok := nodeStats[apiType]
|
||||
if !ok {
|
||||
v = &nodeStatVal{}
|
||||
nodeStats[apiType] = v
|
||||
}
|
||||
v.total++
|
||||
if status == 0 || status >= 500 {
|
||||
v.errs++
|
||||
}
|
||||
v.latSum += ms
|
||||
if ms > v.latMax {
|
||||
v.latMax = ms
|
||||
}
|
||||
nodeStatsMu.Unlock()
|
||||
}
|
||||
|
||||
func nodeRecordProbe(rec nodeProbeRec) {
|
||||
if nodeProbeCh == nil {
|
||||
return
|
||||
}
|
||||
select {
|
||||
case nodeProbeCh <- rec:
|
||||
default:
|
||||
nodeDropMu.Lock()
|
||||
nodeProbeDropN++
|
||||
n := nodeProbeDropN
|
||||
nodeDropMu.Unlock()
|
||||
if n%100 == 1 {
|
||||
slog.Warn("node report probe queue full", "dropped", n)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// nodeReportNodeID 上报身份：优先 node-id（WS_NODE_ID），否则 hostname
|
||||
func nodeReportNodeID() string {
|
||||
if WS_NODE_ID != "" {
|
||||
return WS_NODE_ID
|
||||
}
|
||||
if h, err := os.Hostname(); err == nil && h != "" {
|
||||
return h
|
||||
}
|
||||
return "unknown"
|
||||
}
|
||||
|
||||
// nodeAPIFromPath 从 gin 路由模板提取 apiType 与拨测目标（对齐 WS probe 的 raw 格式）
|
||||
func nodeAPIFromPath(c *gin.Context) (apiType, raw string) {
|
||||
path := c.FullPath() // 形如 /v1/tcping/:ip
|
||||
if !strings.HasPrefix(path, "/v1/") {
|
||||
return "", ""
|
||||
}
|
||||
seg := strings.SplitN(strings.TrimPrefix(path, "/v1/"), "/", 2)
|
||||
if len(seg) == 0 || seg[0] == "" {
|
||||
return "", ""
|
||||
}
|
||||
apiType = seg[0]
|
||||
switch apiType {
|
||||
case "tcping", "dnssec", "whois":
|
||||
raw = c.Param("ip")
|
||||
if raw == "" {
|
||||
raw = c.Param("domain")
|
||||
}
|
||||
case "speed":
|
||||
raw = c.Param("version") + c.Param("url") // v4/example.com（对齐 WS probe raw 格式）
|
||||
case "dns":
|
||||
raw = c.Param("type") + c.Param("domain") // a/example.com
|
||||
case "detail", "ssl":
|
||||
raw = strings.TrimPrefix(c.Param("url"), "/")
|
||||
case "location", "asn":
|
||||
raw = c.Param("ip")
|
||||
}
|
||||
return apiType, raw
|
||||
}
|
||||
|
||||
// nodeReportLoop 周期上报：WS 在线走 WS 广播（所有已注册中间件），否则 HTTP POST 收集中心
|
||||
func nodeReportLoop() {
|
||||
ticker := time.NewTicker(time.Duration(REPORT_INTERVAL) * time.Second)
|
||||
defer ticker.Stop()
|
||||
for range ticker.C {
|
||||
payload := nodeBuildPayload()
|
||||
if payload == nil {
|
||||
continue
|
||||
}
|
||||
sent := wsBroadcastReport(payload)
|
||||
if !sent && REPORT_URL != "" {
|
||||
if err := nodeHTTPReport(payload); err != nil {
|
||||
slog.Warn("node http report failed", "error", err)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// nodeBuildPayload 取走当前计数与拨测缓冲，组装上报报文；无数据返回 nil。
|
||||
// minute 传 0 = 收集器按自己时钟入桶（节点时钟不可信时不影响聚合口径）
|
||||
func nodeBuildPayload() map[string]any {
|
||||
nodeStatsMu.Lock()
|
||||
snap := nodeStats
|
||||
nodeStats = make(map[string]*nodeStatVal, len(snap))
|
||||
nodeStatsMu.Unlock()
|
||||
|
||||
probes := make([]nodeProbeRec, 0, reportMaxProbes)
|
||||
if nodeProbeCh != nil {
|
||||
drain:
|
||||
for len(probes) < reportMaxProbes {
|
||||
select {
|
||||
case r := <-nodeProbeCh:
|
||||
probes = append(probes, r)
|
||||
default:
|
||||
break drain // 队列已空，本轮结束
|
||||
}
|
||||
}
|
||||
}
|
||||
if len(snap) == 0 && len(probes) == 0 {
|
||||
return nil
|
||||
}
|
||||
minute := time.Now().UTC().Unix() / 60
|
||||
stats := make([]map[string]any, 0, len(snap))
|
||||
for apiType, v := range snap {
|
||||
stats = append(stats, map[string]any{
|
||||
"minute": minute, "nodeId": nodeReportNodeID(), "apiType": apiType,
|
||||
"total": v.total, "errors": v.errs, "latencySumMs": v.latSum, "latencyMaxMs": v.latMax,
|
||||
})
|
||||
}
|
||||
payload := map[string]any{
|
||||
"instance": nodeReportNodeID(),
|
||||
"stats": stats,
|
||||
}
|
||||
if len(probes) > 0 {
|
||||
payload["probes"] = probes
|
||||
}
|
||||
return payload
|
||||
}
|
||||
|
||||
// wsBroadcastReport 经 WS 通道向所有在线中间件广播 report 消息；无在线连接返回 false（触发 HTTP 兜底）
|
||||
func wsBroadcastReport(payload map[string]any) bool {
|
||||
sent := false
|
||||
data, _ := json.Marshal(payload)
|
||||
wsActiveConns.Range(func(_, v any) bool {
|
||||
if c, ok := v.(*websocket.Conn); ok && c != nil {
|
||||
if err := wsSendErr(c, wsMsg{Type: "report", NodeID: WS_NODE_ID, Data: data}); err != nil {
|
||||
slog.Warn("node ws report send failed", "error", err)
|
||||
} else {
|
||||
sent = true
|
||||
}
|
||||
}
|
||||
return true
|
||||
})
|
||||
return sent
|
||||
}
|
||||
|
||||
// nodeHTTPReport HTTP 兜底上报（WS 未启用/全部掉线时）
|
||||
func nodeHTTPReport(payload map[string]any) error {
|
||||
body, err := json.Marshal(payload)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
url := strings.TrimSuffix(REPORT_URL, "/") + "/report"
|
||||
req, err := http.NewRequest(http.MethodPost, url, bytes.NewReader(body))
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
req.Header.Set("Content-Type", "application/json")
|
||||
if REPORT_TOKEN != "" {
|
||||
req.Header.Set("Authorization", "Bearer "+REPORT_TOKEN)
|
||||
}
|
||||
client := &http.Client{Timeout: 10 * time.Second}
|
||||
resp, err := client.Do(req)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
defer resp.Body.Close()
|
||||
if resp.StatusCode < 200 || resp.StatusCode >= 300 {
|
||||
return &httpStatusError{status: resp.StatusCode}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
type httpStatusError struct{ status int }
|
||||
|
||||
func (e *httpStatusError) Error() string {
|
||||
return fmt.Sprintf("collector returned status %d", e.status)
|
||||
}
|
||||
@@ -14,5 +14,8 @@
|
||||
"ws-url": "",
|
||||
"node-id": "",
|
||||
"node-key": "",
|
||||
"node-ota": "false"
|
||||
}
|
||||
"node-ota": "true",
|
||||
"report-url": "",
|
||||
"report-token": "",
|
||||
"report-interval-seconds": 15
|
||||
}
|
||||
@@ -133,7 +133,9 @@ func wsProbe(apiType, raw string, query map[string]string) (int, any) {
|
||||
return webtest.TCPingRun(host, port, n, v, 10*time.Second, 100*time.Millisecond)
|
||||
},
|
||||
func(err error) *webtest.TCPingStats { return &webtest.TCPingStats{IP: "Error: " + err.Error()} },
|
||||
func(v string) *webtest.TCPingStats { return &webtest.TCPingStats{IP: "Skipped due to SINGLE_STACK=" + v} },
|
||||
func(v string) *webtest.TCPingStats {
|
||||
return &webtest.TCPingStats{IP: "Skipped due to SINGLE_STACK=" + v}
|
||||
},
|
||||
)
|
||||
result := &TCPingResult{IPv4: ipv4, IPv6: ipv6}
|
||||
pingCache.Store(cacheKey, pingCacheEntry{result: result, timestamp: time.Now()})
|
||||
@@ -334,19 +336,30 @@ func wsRaw(v any) json.RawMessage {
|
||||
return b
|
||||
}
|
||||
|
||||
// wsHandleProbe 处理中间件下发的拨测请求（并发执行）：取数 → probe_result
|
||||
// wsActiveConns 当前已注册的中间件连接（url → conn）：注册成功写入、断开移除，数据上报广播用（report.go）
|
||||
var wsActiveConns sync.Map
|
||||
|
||||
// wsHandleProbe 处理中间件/收集中心经 WS 下发的拨测请求（并发执行）：取数 → probe_result。
|
||||
// 归属规则：报文带 Scheduler=true = 收集中心主动调度拨测（收集中心侧已本地落库 sched/biz），
|
||||
// 本节点跳过 data 上报，避免双算；仅回 probe_result。不带 Scheduler 的 WS probe
|
||||
// （如中间件转发真实业务）仍由本节点上报（节点是唯一记录者，见 report.go）。
|
||||
func wsHandleProbe(c *websocket.Conn, data json.RawMessage) {
|
||||
var req struct {
|
||||
RequestID string `json:"requestId"`
|
||||
APIType string `json:"apiType"`
|
||||
Raw string `json:"raw"`
|
||||
Query map[string]string `json:"query"`
|
||||
Scheduler bool `json:"scheduler"`
|
||||
}
|
||||
if err := json.Unmarshal(data, &req); err != nil || req.RequestID == "" || req.APIType == "" {
|
||||
slog.Warn("ws client bad probe message")
|
||||
return
|
||||
}
|
||||
start := time.Now()
|
||||
status, body := wsProbe(req.APIType, req.Raw, req.Query)
|
||||
if !req.Scheduler {
|
||||
nodeRecordWSProbe(req.RequestID, req.APIType, req.Raw, req.Query, status, time.Since(start))
|
||||
}
|
||||
payload := struct {
|
||||
RequestID string `json:"requestId"`
|
||||
Status int `json:"status"`
|
||||
@@ -372,21 +385,51 @@ const (
|
||||
wsHeartbeatTimeout = 5 * time.Second
|
||||
)
|
||||
|
||||
// nodeCapabilities 本节点支持的远程管理能力清单，随 register 报文上报给中间件，
|
||||
// 同时也在 HTTP 健康检查 `/` 里返回（供中间件对纯 HTTP 节点探活时一并取回）。
|
||||
//
|
||||
// 存在的意义：中间件下发 config 指令前先查这份清单，
|
||||
// - 清单里没有该能力 → 立刻给出明确错误（旧版节点会静默忽略这类消息，只能白白等满超时）
|
||||
// - 未上报清单（老版本节点）→ 中间件按"未知"处理，仍会尝试但会给出旧版本提示
|
||||
//
|
||||
// 新增一类管理指令时在此追加，并保持取值稳定（中间件按字符串比对）。
|
||||
func nodeCapabilities() []string {
|
||||
return []string{
|
||||
"probe", // 拨测（WS probe / HTTP 转发）
|
||||
"report", // 统计与拨测明细上报
|
||||
"config", // 运行时配置读写（/v1/config、WS config）
|
||||
"ota", // OTA 升级（WS ota / HTTP POST /v1/ota，见 ota.go）
|
||||
}
|
||||
}
|
||||
|
||||
// wsClientOnce 连接并服务单个中间件 URL，返回下次重试前的等待时长（由 per-URL 连接循环调用）：
|
||||
// - 连接/读循环断开 → 3s（重试同一 URL）
|
||||
// - 注册被拒（register_error）→ 30s（多为 key 配置错误，加大间隔避免空转刷日志）
|
||||
// - 心跳连续失败 wsHeartbeatRetry 次 → 主动断开，3s
|
||||
// - 返回 0 = 配置缺失（不再重试）
|
||||
func wsClientOnce(url string) time.Duration {
|
||||
ctx := context.Background()
|
||||
//
|
||||
// ctx 由 per-URL 连接循环（wsClientOnceLoop）传入：ws-url 热更新移除该 URL 时会 cancel，
|
||||
// Dial / Read 立即返回错误，协程随即退出，不必等满退避。
|
||||
func wsClientOnce(ctx context.Context, url string) time.Duration {
|
||||
c, _, err := websocket.Dial(ctx, url, nil)
|
||||
if err != nil {
|
||||
slog.Warn("ws client dial failed", "url", url, "error", err)
|
||||
return 3 * time.Second
|
||||
}
|
||||
defer c.CloseNow()
|
||||
defer func() {
|
||||
wsActiveConns.Delete(url)
|
||||
c.CloseNow()
|
||||
}()
|
||||
|
||||
reg := map[string]string{"nodeId": WS_NODE_ID}
|
||||
// 注册报文带上版本号与能力清单：
|
||||
// version → 中间件落到 nodes 表，节点状态页展示（升级部署后重新注册即为新版本）
|
||||
// capabilities → 中间件在下发管理指令前据此判断本节点能否理解 config，
|
||||
// 老节点不认这类消息又不会回错，只能靠超时暴露（白等 15s）
|
||||
reg := map[string]any{
|
||||
"nodeId": WS_NODE_ID,
|
||||
"version": VERSION,
|
||||
"capabilities": nodeCapabilities(),
|
||||
}
|
||||
if WS_NODE_KEY != "" {
|
||||
reg["key"] = WS_NODE_KEY
|
||||
}
|
||||
@@ -413,6 +456,7 @@ func wsClientOnce(url string) time.Duration {
|
||||
return 3 * time.Second
|
||||
}
|
||||
slog.Info("ws client registered", "nodeId", WS_NODE_ID, "url", url)
|
||||
wsActiveConns.Store(url, c)
|
||||
|
||||
// 心跳 goroutine：每 10s 发 ping，失败重试，连续 3 次失败主动断开（per-URL 循环重连同一中间件）
|
||||
stopHeartbeat := make(chan struct{})
|
||||
@@ -452,6 +496,10 @@ func wsClientOnce(url string) time.Duration {
|
||||
switch msg.Type {
|
||||
case "probe":
|
||||
go wsHandleProbe(c, msg.Data)
|
||||
case "config":
|
||||
go wsHandleConfig(c, msg) // 远端配置管理：get / patch / refresh（见 config_api.go）
|
||||
case "ota":
|
||||
go wsHandleOTA(c, msg.Data) // 收集中心下发的 OTA 升级（见 ota.go）
|
||||
case "ping":
|
||||
wsSend(c, wsMsg{Type: "pong"})
|
||||
case "status":
|
||||
@@ -460,35 +508,85 @@ func wsClientOnce(url string) time.Duration {
|
||||
}
|
||||
}
|
||||
|
||||
// wsClientLoop 同时连接所有配置的中间件 URL（逗号分隔，多活）：
|
||||
// 每个 URL 由独立 goroutine 负责，各自注册并保持连接，任一断开只重连自己，不影响其他中间件。
|
||||
// 注意：多个 URL 指向同一中间件实例时，中间件按 nodeId 单连接，后注册的连接会顶掉先前的。
|
||||
func wsClientLoop() {
|
||||
urls := splitWSURLs(WS_URL)
|
||||
if len(urls) == 0 {
|
||||
slog.Info("ws client disabled (WS_URL not set)")
|
||||
return
|
||||
}
|
||||
var wg sync.WaitGroup
|
||||
for _, url := range urls {
|
||||
wg.Add(1)
|
||||
go func(u string) {
|
||||
defer wg.Done()
|
||||
wsClientOnceLoop(u)
|
||||
}(url)
|
||||
}
|
||||
wg.Wait()
|
||||
// wsClientController WS 客户端连接的运行时控制器：持有每个中间件 URL 的独立连接协程，
|
||||
// 使 ws-url 支持热更新（见 reconcileWSClient，多退少补）。
|
||||
// node-id / node-key 仍是"需重启"配置项（见 config_api.go configRestartKeys），不在收敛范围内。
|
||||
var wsClientController = struct {
|
||||
mu sync.Mutex
|
||||
started bool
|
||||
conns map[string]context.CancelFunc // 在跑的 url → 取消函数
|
||||
}{conns: map[string]context.CancelFunc{}}
|
||||
|
||||
// startWSClientController 启动 WS 客户端控制器（进程启动时调用一次）。
|
||||
// 注意：即使此刻 WS_URL 为空也必须调用——否则运行中把 ws-url 热更新进来时没有协程去接管。
|
||||
func startWSClientController() {
|
||||
c := &wsClientController
|
||||
c.mu.Lock()
|
||||
c.started = true
|
||||
c.mu.Unlock()
|
||||
reconcileWSClient()
|
||||
}
|
||||
|
||||
// wsClientOnceLoop 单个中间件 URL 的持续连接循环：连接 → 注册 → 心跳/读循环 → 断开重试
|
||||
func wsClientOnceLoop(url string) {
|
||||
// reconcileWSClient 把在跑的连接收敛到 WS_URL 的当前值（多退少补）：
|
||||
// - URL 已从配置移除 → 取消对应协程，断开该中间件连接
|
||||
// - 新增 URL → 起新协程连接
|
||||
//
|
||||
// 幂等：只做差集增删，因此启动时"远端配置触发的收敛 + startWSClientController 的兜底收敛"
|
||||
// 两次调用不会重复建连；conns 是"当前在跑哪些连接"的唯一事实来源。
|
||||
// ctx 取消只是信号，真正的收尾（wsActiveConns.Delete + CloseNow）由该 URL 自己的协程在 defer 里完成，
|
||||
// 控制器从不持有 *websocket.Conn，因此不存在"控制器关连接、协程还在读"的竞态。
|
||||
func reconcileWSClient() {
|
||||
c := &wsClientController
|
||||
c.mu.Lock()
|
||||
defer c.mu.Unlock()
|
||||
if !c.started {
|
||||
return // 控制器尚未启动（启动早期应用远端配置时），startWSClientController 会兜底收敛
|
||||
}
|
||||
|
||||
urls := splitWSURLs(WS_URL)
|
||||
want := make(map[string]bool, len(urls))
|
||||
for _, u := range urls {
|
||||
want[u] = true
|
||||
}
|
||||
|
||||
for u, cancel := range c.conns {
|
||||
if !want[u] {
|
||||
slog.Info("ws client url removed", "url", u)
|
||||
cancel()
|
||||
delete(c.conns, u)
|
||||
}
|
||||
}
|
||||
|
||||
for _, u := range urls {
|
||||
if _, ok := c.conns[u]; ok {
|
||||
continue
|
||||
}
|
||||
ctx, cancel := context.WithCancel(context.Background())
|
||||
c.conns[u] = cancel
|
||||
slog.Info("ws client url added", "url", u, "nodeId", WS_NODE_ID)
|
||||
go wsClientOnceLoop(ctx, u)
|
||||
}
|
||||
|
||||
if len(c.conns) == 0 {
|
||||
slog.Info("ws client disabled (no ws-url)")
|
||||
}
|
||||
}
|
||||
|
||||
// wsClientOnceLoop 单个中间件 URL 的持续连接循环：连接 → 注册 → 心跳/读循环 → 断开重试。
|
||||
// ctx 取消（该 URL 被热更新移除）时立即退出，不再重试。
|
||||
func wsClientOnceLoop(ctx context.Context, url string) {
|
||||
for {
|
||||
retryDelay := wsClientOnce(url)
|
||||
retryDelay := wsClientOnce(ctx, url)
|
||||
if retryDelay == 0 {
|
||||
slog.Info("ws client stopped", "url", url)
|
||||
return
|
||||
}
|
||||
time.Sleep(retryDelay)
|
||||
select {
|
||||
case <-ctx.Done():
|
||||
slog.Info("ws client stopped", "url", url)
|
||||
return
|
||||
case <-time.After(retryDelay):
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
Reference in new issue
Block a user