Skip to content
laoXuHomePublic

About

多机场订阅管理、节点检测与统一订阅系统 — FastAPI + Vue3 + SQLite + Docker Compose

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

Repository files navigation

NodePool

多机场订阅管理与统一订阅系统。把多个机场的订阅汇聚成一个节点池,统一拉取、统一检测、统一输出订阅,节点可用性由你自己掌控。全程自建解析与转换,不依赖任何第三方订阅转换服务,订阅内容中不会泄露机场原始订阅地址。

技术栈:后端 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 Compose)

前置条件:已安装 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/data

config/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 对已有数据库不生效。


首次登录

  1. 浏览器打开 http://<服务器IP>:8000/。
  2. 使用管理 Token 登录,默认值为 admin(或你在 .env 中设置的 NODEPOOL_ADMIN_TOKEN)。
  3. 登录后请立即在「系统设置」中修改管理 Token;订阅 Token 也可在「订阅管理」中重新生成。

默认 token 仅用于首次体验,生产环境务必替换,且不要提交含真实 token 的 .env 到版本库。


使用流程

  1. 添加机场:进入「机场管理」,新增机场,填写名称与订阅地址,设置拉取周期(或每天定时拉取时间)。

  2. 拉取节点:对机场点击「立即拉取」,系统在后台解析并入库;可在「拉取历史」查看结果与节点数。

  3. 配置检测组:在「检测组」确认启用的组(默认 G/TG/Y 三组),按需新增自定义组与目标 URL。

  4. 运行检测:进入「检测调度」手动触发一轮检测,或等待定时调度;在「节点池」查看每个节点的检测结果与动态名称。

  5. 生成订阅:进入「订阅管理」配置过滤策略(延迟门槛、最小通过组数、最大节点数等),点击「生成订阅」。

  6. 客户端导入:复制订阅地址导入客户端:

    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 表为准,可在管理界面「系统设置」中调整。

About

多机场订阅管理、节点检测与统一订阅系统 — FastAPI + Vue3 + SQLite + Docker Compose

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages