多机场订阅管理与统一订阅系统。把多个机场的订阅汇聚成一个节点池,统一拉取、统一检测、统一输出订阅,节点可用性由你自己掌控。全程自建解析与转换,不依赖任何第三方订阅转换服务,订阅内容中不会泄露机场原始订阅地址。
技术栈:后端 FastAPI + SQLite,前端 Vue 3 + Vite,单容器部署,前端构建产物由 FastAPI 直接托管。
- 多机场汇聚:添加多个机场订阅,自动拉取、解析、按机场去重存档(不同机场同节点各自保留)。
- 拉取保护:先暂存再解析,校验非空后事务性替换;失败或为空时保留旧缓存,只写拉取历史。
- 多组并发检测:默认 ChatGPT / Telegram / YouTube 三组,可自定义检测组与目标;全局并发、单组并发、请求间隔均可配置。
- 智能过滤:连续失败过滤、相似度去重、延迟门槛、最小通过组数等策略,只把可用节点送进订阅。
- 动态命名:按检测结果给节点追加
G.TG.Y等标识,例如机场A.G.TG.Y 香港01。 - 统一订阅输出:同时生成 Clash/Mihomo YAML、sing-box JSON、通用 Base64 三种格式,原子发布,失败保留上一版。
- 访问保护:管理端 Bearer Token,订阅使用独立 sub_token,两者互不相同。
- 可视化管理:仪表盘、节点池、检测组、订阅配置、备份恢复、日志等界面。
前置条件:已安装 Docker 与 Docker Compose 插件。
# 1. 进入项目目录(替换为你的实际路径)
cd /opt/nodepool
# 2. 生成环境变量文件并设置 token
cp .env.example .env
# 编辑 .env,至少把 NODEPOOL_ADMIN_TOKEN 改成强随机字符串
# 3. 构建并后台启动
docker compose up -d --build启动后访问:
- 管理界面:
http://<服务器IP>:8000/ - 订阅地址:
http://<服务器IP>:8000/sub/all?token=<你的订阅Token>
查看运行状态与日志:
docker compose ps
docker compose logs -f nodepool停止服务:
docker compose down
docker compose down不会删除数据目录,数据仍保留在宿主机挂载目录中。
容器内固定数据根目录为 /app/data,其下结构:
/app/data
├── nodepool.db # SQLite 数据库
├── config/ # 运行期配置
├── logs/ # 日志
└── backup/ # 备份文件
该目录通过卷映射到宿主机,默认值如下(与 .env 对应):
| 路径 | 宿主机默认 | 说明 |
|---|---|---|
| 数据根 | ./data(即项目目录下 data/) |
由 NODEPOOL_DATA_DIR 控制 |
| 容器数据根 | /app/data |
固定,不随宿主机路径变化 |
容器重建、镜像升级、重启都不会丢数据——只要宿主机挂载目录还在,数据库与配置就都还在。
生产环境建议把 NODEPOOL_DATA_DIR 设为独立目录,例如 /opt/nodepool/data:
# .env
NODEPOOL_DATA_DIR=/opt/nodepool/dataconfig/settings.example.json 是默认配置样例(对应数据库 settings 表的键),仅供参考,真正生效的值以数据库为准。
| 变量名 | 默认值 | 作用 |
|---|---|---|
NODEPOOL_ADMIN_TOKEN |
admin |
管理端 Bearer Token,首次启动写入 settings.auth_token |
NODEPOOL_SUB_TOKEN |
未设置(随机) | 订阅访问 Token,首次启动写入 settings.sub_token;不设置则自动生成 |
NODEPOOL_PORT |
8000 |
宿主机映射端口,容器内部固定 8000 |
NODEPOOL_DATA_DIR |
./data |
宿主机数据持久化根目录,映射到容器 /app/data |
环境变量只在首次启动初始化时写入相应 token;之后请在管理界面「系统设置」中修改并持久化到数据库。修改
.env中的 token 对已有数据库不生效。
- 浏览器打开
http://<服务器IP>:8000/。 - 使用管理 Token 登录,默认值为
admin(或你在.env中设置的NODEPOOL_ADMIN_TOKEN)。 - 登录后请立即在「系统设置」中修改管理 Token;订阅 Token 也可在「订阅管理」中重新生成。
默认 token 仅用于首次体验,生产环境务必替换,且不要提交含真实 token 的
.env到版本库。
-
添加机场:进入「机场管理」,新增机场,填写名称与订阅地址,设置拉取周期(或每天定时拉取时间)。
-
拉取节点:对机场点击「立即拉取」,系统在后台解析并入库;可在「拉取历史」查看结果与节点数。
-
配置检测组:在「检测组」确认启用的组(默认 G/TG/Y 三组),按需新增自定义组与目标 URL。
-
运行检测:进入「检测调度」手动触发一轮检测,或等待定时调度;在「节点池」查看每个节点的检测结果与动态名称。
-
生成订阅:进入「订阅管理」配置过滤策略(延迟门槛、最小通过组数、最大节点数等),点击「生成订阅」。
-
客户端导入:复制订阅地址导入客户端:
http://<服务器IP>:8000/sub/all?token=<你的订阅Token>可用
format参数指定格式:clash(默认)、singbox、base64。http://<服务器IP>:8000/sub/all?token=<你的订阅Token>&format=singbox
只有至少通过一个启用检测组的节点才会进入订阅;一轮批次未完整跑完前不会生成新订阅。
- 界面操作:进入「系统设置」→「备份」,点击生成备份;在「备份列表」查看与下载。
- 命令行(备份宿主机挂载目录):
# 假设 NODEPOOL_DATA_DIR=/opt/nodepool/data
cd /opt/nodepool/data
tar czf nodepool-backup-$(date +%F).tar.gz nodepool.db config logs backup- 界面操作:进入「系统设置」→「备份」,选择备份文件执行恢复,按提示重启生效。
- 命令行(先停止容器再覆盖文件):
docker compose down
cd /opt/nodepool/data
tar xzf nodepool-backup-<日期>.tar.gz
docker compose up -d恢复会覆盖当前数据库与配置,操作前建议先对现状再做一次备份。
cd /opt/nodepool
docker compose down
# 拉取/更新源码后重新构建镜像
docker compose up -d --build数据在挂载目录中,升级不会丢失。升级后可用 docker compose ps 观察 health 状态。
容器设置了 restart: unless-stopped,宿主机重启或容器异常退出后会自动拉起。数据库、配置与订阅产物都在 /app/data 挂载目录中,重启后直接恢复上次状态;正在执行的检测批次会在服务恢复后由调度器接管。
| 格式 | format 值 |
说明 | 兼容客户端 |
|---|---|---|---|
| Clash / Mihomo YAML | clash(默认) |
标准 Clash 配置,含 proxies / proxy-groups / rules | Clash、Clash.Meta、Mihomo、OpenClash |
| sing-box JSON | singbox |
sing-box outbounds 配置 | sing-box 及兼容内核 |
| 通用 Base64 | base64 |
每行一个标准订阅链接(ss:// / vmess:// / trojan:// 等)整体 Base64 | 多数支持通用订阅的客户端 |
节点名称采用动态命名规则:{机场名称}.{检测标识} {原始节点名称},检测标识按 sort_order 升序拼接(默认 G.TG.Y)。
token 错误返回 401;从未生成过订阅时返回 503。
在宿主机分别启动前端与后端(需 Node.js 20+ 与 Python 3.11+)。
# 终端 1:启动后端
cd backend
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt
export NODEPOOL_DATA_DIR=./devdata # Windows: set NODEPOOL_DATA_DIR=./devdata
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
# 终端 2:启动前端
cd frontend
npm install
npm run dev前端 dev server 默认通过代理把 /api 与 /sub 请求转发到后端 http://localhost:8000(具体以 vite.config.js 配置为准)。开发模式下数据写入本地 NODEPOOL_DATA_DIR,与容器互不影响。
默认配置样例见 config/settings.example.json,关键键含义:
| Key | 默认值 | 说明 |
|---|---|---|
auth_token |
admin |
管理端 Token |
sub_token |
随机 | 订阅 Token |
global_concurrency |
10 |
全局并发 |
group_concurrency |
5 |
单组并发 |
request_delay_min / request_delay_max |
200 / 800 |
请求间隔(毫秒) |
sim_threshold |
0.75 |
相似度阈值 |
history_retention_days |
30 |
检测历史保留天数 |
sub_max_latency |
null |
订阅节点最大延迟(null 不限) |
sub_min_pass_groups |
1 |
至少通过的检测组数 |
sub_max_nodes |
null |
订阅最大节点数(null 不限) |
sub_consecutive_fail_filter |
3 |
连续失败过滤阈值 |
sub_name |
NodePool |
订阅名称 |
实际生效值以数据库
settings表为准,可在管理界面「系统设置」中调整。