多机场节点管理、检测与统一订阅系统。一个自包含的 Web 服务:管理多个机场订阅,本地缓存节点池,按可配置的检测组验证节点,最后输出唯一一个 /sub/all 统一订阅。
不依赖 Subs-Check-Pro、Sub-Store 或任何第三方订阅转换服务。单个 Docker 容器即可运行,SQLite 存业务数据,前端由后端直接托管。
- 多机场、独立周期:每个机场独立拉取(按分钟/小时间隔,或每天固定时刻),支持手动拉取、失败重试、拉取历史。
- 拉取与检测解耦:检测只读取 SQLite 本地缓存,永远不会因为检测而重新拉取机场订阅。
- 失败保护:下载失败、空内容、解析失败时旧缓存原样保留;新数据先完整解析校验,再事务性替换。
- 指纹去重:按协议 + 服务器 + 端口 + 关键参数生成指纹,同名不同参数不会被误合并;默认只在同一机场内去重。
- 配置驱动检测组:默认 ChatGPT(G)、Telegram(TG)、YouTube(Y),可在 UI 增删改自定义检测组,成功条件支持状态码区间、响应内容与延迟。
- 真实 HTTP 语义检测:内置 Mihomo 内核,为每个节点生成独立 SOCKS 入口,检测拿到真实状态码与响应体,而不是只做 TCP 握手。
- 随机化与相似节点分散:每轮重新打乱,按同 IP / 同网段交错排列,配合全局并发、单组并发、同 IP、同网段四层限流。
- 批次完整性:所有启用检测组处理完本轮目标节点后才算完整批次,完整后才生成并原子替换订阅;中断、崩溃不发布半成品。
- 唯一统一订阅:
/sub/all,Token 保护,支持 Clash/Mihomo YAML、sing-box JSON、通用 Base64 三种格式,不暴露机场原始 URL。 - 动态名称标识:
机场名.检测标识 原始名称,改机场名不必重写节点记录。 - 可运维:仪表盘、日志、系统设置、数据库备份/恢复、健康检查、重启自动恢复。
机场订阅 1..N
↓ 独立周期 / 手动 / 重试
订阅拉取器 ──→ 下载 → 解析 → 校验 → 事务性写入
↓
节点解析器(ss / vmess / vless / trojan / hysteria2 / tuic / socks / http + Clash YAML 导入)
↓
SQLite 本地节点池(指纹去重)
↓ 只读缓存
检测调度器(随机化 + 相似分散 + 四层并发 + 请求间隔)
↓
默认检测组 G / TG / Y + 自定义检测组
↓
检测结果与历史(连续失败计数、可用性状态)
↓
完整批次汇总 → 动态名称标识 → 合格节点筛选
↓
Clash YAML / sing-box JSON / Base64(格式校验后原子替换)
↓
/sub/all (Token 保护)
↓
Clash / Mihomo / sing-box / v2rayN 等客户端
三个模块只通过数据库与文件交换状态:拉取、检测、输出互不阻塞。
mkdir -p /opt/nodepool/{data,config,logs,backup}
cd /opt/nodepool
curl -fsSLO https://raw.githubusercontent.com/laoxuhome/NodePoolME/main/docker-compose.yml
curl -fsSL https://raw.githubusercontent.com/laoxuhome/NodePoolME/main/.env.example -o .env
# 编辑 .env:设置 NODEPOOL_ADMIN_PASSWORD、NODEPOOL_SECRET、NODEPOOL_IMAGE
docker compose up -d打开 http://<主机IP>:8080,用 .env 中的管理密码登录。
docker run -d --name nodepool --restart unless-stopped \
-p 8080:8080 \
-e NODEPOOL_ADMIN_PASSWORD='change-me' \
-e NODEPOOL_SECRET='long-random-string' \
-v /opt/nodepool/data:/data \
-v /opt/nodepool/config:/config \
-v /opt/nodepool/logs:/logs \
-v /opt/nodepool/backup:/backup \
ghcr.io/laoxuhome/nodepoolme:latest| 来源 | 地址 |
|---|---|
| GHCR(GitHub Actions 构建,多架构) | ghcr.io/laoxuhome/nodepoolme:latest |
| 版本标签 | ghcr.io/laoxuhome/nodepoolme:v1.0.0、sha-xxxxxxx |
支持 linux/amd64 与 linux/arm64(含 Mihomo 内核)。
| 变量 | 默认值 | 说明 |
|---|---|---|
NODEPOOL_DATA_DIR |
/data(镜像内) |
数据根目录,SQLite 与订阅文件所在 |
NODEPOOL_CONFIG_DIR |
/config |
配置与 Mihomo 工作目录 |
NODEPOOL_LOG_DIR |
/logs |
轮转日志 |
NODEPOOL_BACKUP_DIR |
/backup |
备份文件 |
NODEPOOL_ADMIN_PASSWORD |
nodepool |
首次启动的管理密码(登录后可在 UI 修改) |
NODEPOOL_SECRET |
内置默认值 | 会话签名密钥,生产环境务必修改 |
NODEPOOL_PORT(compose) |
8080 |
宿主端口 |
NODEPOOL_TEST_ENGINE |
mihomo |
mihomo 全协议检测;tcp 仅连通性,用于无内核环境 |
NODEPOOL_MIHOMO_BIN |
/usr/local/bin/mihomo |
内核路径 |
NODEPOOL_MIHOMO_API |
http://127.0.0.1:9090 |
内核控制接口(仅监听回环) |
NODEPOOL_MIHOMO_BASE_PORT |
31000 |
每个节点 SOCKS 入口起始端口(仅回环) |
NODEPOOL_UA |
clash.meta/... NodePoolME/1.0 |
拉取订阅时使用的 UA |
持久化目录:
/opt/nodepool/
├── config/ # 配置、Mihomo 工作目录(可重建)
├── data/ # nodepool.db(SQLite)、sub/(订阅输出)
├── logs/ # nodepool.log(5MB×3 轮转)
└── backup/ # 手动/自动备份、恢复前安全副本
容器重建不会丢数据;镜像升级不清除机场、缓存、检测历史与订阅设置。
- 添加机场:机场管理 → 添加机场,填写名称与订阅地址,设置拉取周期(或每天定时),保存后点「立即拉取」。
- 等待缓存:拉取成功会显示节点数;失败会保留旧缓存并在列表中显示失败原因。
- 确认检测组:默认已有 G / TG / Y。需要时新增自定义组(名称、URL、标识、方法、超时、状态码、响应内容、最大延迟、周期)。
- 运行检测:仪表盘「立即检测」,或等待调度按批次间隔自动运行。检测进度实时显示。
- 查看节点池:按机场、协议、检测组、结果筛选,查看每个节点的各检测项延迟与历史。
- 复制订阅:订阅输出页复制
/sub/all地址到客户端;需要固定格式时加&format=clash|singbox|base64。
| 名称 | 标识 | 目标 | 成功条件 |
|---|---|---|---|
| ChatGPT | G |
https://chatgpt.com/ |
状态码 200–399 |
| Telegram | TG |
https://telegram.org/ |
状态码 200–399 |
| YouTube | Y |
https://www.youtube.com/generate_204 |
状态码 204 |
Google 与 Gemini 不默认启用,需要时通过「新增检测组」添加。自定义组可使用任意标识,标识顺序按「排序值、ID」稳定输出。
一个组是否通过不影响其他组;停用的组不参与合格判断,其标识也不出现在名称中。
机场名称.检测标识 原始节点名称
默认顺序 G.TG.Y,自定义标识按排序值追加在后面:
| 检测结果 | 输出名称 |
|---|---|
| 三项全过 | 机场A.G.TG.Y 香港01 |
| 仅 ChatGPT | 机场A.G 日本02 |
| Telegram + YouTube | 机场B.TG.Y 新加坡01 |
| 增加自定义 CL 且通过 | 机场A.G.TG.Y.CL 香港02 |
- 标识随结果动态变化,检测失败即移除该标识;原始节点名称始终不改写。
- 改机场名只影响输出组合,不动节点记录。
- 同一客户端配置内名称自动去重(重复时追加
#2)。
- 只有一个地址:
/sub/all,不会按检测项目拆成多个订阅。 - 访问保护:
?token=<订阅Token>或/sub/all/<token>,Token 可在订阅输出页修改/重新生成。 - 合格规则:至少通过
最低通过组数个启用检测组,另可叠加最大延迟、最大节点数、连续失败过滤。 - 内容不含机场原始订阅 URL,也不含机场凭据。
- 格式:
| 参数 | 格式 | 说明 |
|---|---|---|
format=clash(默认给 Clash UA) |
Mihomo / Clash YAML | proxies + proxy-groups(选择/自动测速)+ MATCH |
format=singbox |
sing-box JSON | mixed 入站 + selector / urltest 出站 |
format=base64 |
通用 Base64 节点列表 | 供 v2rayN 等客户端导入 |
不带参数时按 User-Agent 自动选择:含 sing-box → JSON,含 clash/mihomo/meta → YAML,其余 → Base64。
新订阅先写入临时文件,格式校验通过后再原子替换;客户端始终读到上一版完整订阅,直到新版发布完成。
- mihomo(默认):容器内启动 Mihomo 内核,按工作块(每 200 个节点)生成配置,为块内每个节点绑定一个回环 SOCKS 监听口,然后并发发起真实 HTTP 请求,记录状态码、响应体与耗时。
- 支持 ss / vmess / vless(含 REALITY) / trojan / hysteria2 / tuic / socks5 / http。
- 内核只监听
127.0.0.1,不对外暴露任何端口。
- tcp(降级):内核不可用时自动回退,只验证
server:port能否建立 TCP 连接(不校验状态码/响应体,日志会标注)。也可用NODEPOOL_TEST_ENGINE=tcp强制启用。
| 项目 | 默认 | 可配置范围 |
|---|---|---|
| 单检测组并发 | 5 | 1–20(系统设置) |
| 全局并发 | 10 | 1–300,优先级最高 |
| 同 IP 并发 | 1 | 1–10 |
| 同 /24 并发 | 2 | 1–20 |
| 随机请求间隔 | 200–800 ms | 0–10000 ms |
| 单次检测超时 | 8 s | 1–60 s |
| 检测批次间隔 | 30 min | 1–1440 min |
| 相似分散粒度 | /24 | /32、/24、/16、/8 |
| 连续失败阈值 | 3 | 1–20 |
| 历史保留 | 30 天 | 7–365 天 |
调度顺序:每轮取节点 → 打乱 → 按分散键分桶 → 桶间轮转交错(相同/相近地址不会连续出现)→ 受四层信号量约束 → 每次请求前随机间隔。域名节点按主机名分桶,IP 节点按网段分桶。
- 单次失败不删除节点。
- 连续失败达到阈值标记
unavailable,任意一次成功立即恢复available并清零计数。 - 错误分类:
timeout、connect、status、content、slow、engine。 - 检测历史写入
results,按保留期自动清理。
- 一轮检测创建批次,记录目标数(节点数 × 参与组数)。
- 每个启用组处理块内全部目标;成功/失败/超时都算「已处理」,不会因为一个节点失败无限等待。
- 所有参与组完成后批次才
complete,随后汇总最近一次结果、计算标识、筛选节点、生成三种格式并校验。 - 校验成功才原子替换线上文件;任一步失败则保留旧订阅并记录错误。
- 进程崩溃或重启时,遗留
running批次自动标记aborted,上一版订阅继续可用。 - 若本轮没有任何节点合格且上一版订阅非空,跳过发布并告警,避免把空订阅推给客户端。
备份
- UI:系统设置 → 「创建备份」/「下载数据库」。
- 命令行:
docker exec nodepool python -c "import sqlite3; s=sqlite3.connect('/data/nodepool.db'); b=sqlite3.connect('/backup/manual.db'); s.backup(b)"
恢复
- UI:系统设置 → 选择
.db文件 → 「上传并恢复」。会校验 SQLite 表结构,覆盖前把旧库保存为backup/pre-restore-<时间>.db,恢复后自动重建订阅。
升级
cd /opt/nodepool
docker compose pull
docker compose up -d数据卷不变,配置与历史全部保留。升级后可在订阅输出页「立即重新生成」以套用新版本逻辑。
# 后端
python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
NODEPOOL_DATA_DIR=./data NODEPOOL_TEST_ENGINE=tcp \
.venv/bin/uvicorn backend.main:app --reload --port 8080
# 前端(Vite 开发服务器,代理 /api 到 8080)
cd frontend && npm install && npm run dev
# 生产构建(输出到 backend/static,由后端托管)
cd frontend && npm run build测试:
python tests/test_parsers.py # 解析、指纹、输出格式
python tests/test_engine_live.py # 需要 /tmp/mihomo 内核,验证真实 HTTP 检测链路所有管理接口需登录 Cookie(/api/auth/login),订阅接口使用订阅 Token。
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /api/auth/login /logout /api/auth/password |
登录 / 退出 / 改密码 |
| GET | /api/dashboard |
统计、检测组通过数、运行状态、日志 |
| GET/POST/PATCH/DELETE | /api/airports[/{id}] |
机场增删改查 |
| POST | /api/airports/{id}/fetch |
立即拉取 |
| GET | /api/airports/{id}/logs |
拉取历史 |
| GET | /api/nodes |
搜索、筛选、排序、分页 |
| GET | /api/nodes/{id} |
节点详情与检测历史 |
| POST | /api/nodes/{id}/test |
手动检测单个节点 |
| GET/POST/PATCH/DELETE | /api/groups[/{id}] |
检测组管理 |
| POST | /api/run |
手动触发批次(可指定组) |
| GET | /api/batches /api/runtime |
批次历史 / 实时状态 |
| GET/PATCH | /api/subscription |
订阅设置与链接 |
| POST | /api/subscription/rebuild |
立即重新生成 |
| GET | /api/subscription/preview?fmt= |
预览输出 |
| GET/PATCH | /api/settings |
调度参数 |
| GET | /api/logs |
系统日志 |
| POST/GET | /api/system/backup /download /restore |
备份 / 下载 / 恢复 |
| GET | /sub/all?token=...&format=... |
统一订阅 |
| GET | /healthz |
健康检查 |
包含:多机场管理、独立拉取、缓存与去重、三种默认检测组、自定义检测组、随机化与分散、四层并发、连续失败保护、完整批次与原子发布、动态标识、唯一统一订阅、三种输出、备份恢复、健康检查、多架构镜像。
暂不包含:下载/上传速度测试、ISP 与流媒体解锁检测、复杂节点评分、多订阅输出、第三方订阅转换、独立 Redis/MySQL、多用户权限体系。
已知限制:
- 单进程单容器设计,面向个人/小规模使用;数千节点时检测批次会变长(每个工作块需要重载内核配置)。
- 相似分散只能降低集中请求风险,无法识别共用机房、反代或同一上游出口。
- 输出格式兼容性以 Clash/Mihomo、sing-box、v2rayN 实测为准,其他客户端可能需要额外适配。
- 检测通过 ≠ 服务一定可用(目标站点风控、地区策略会变化),建议同时观察延迟与连续失败。
MIT