项目介绍

SubscribeManager 是一个自托管的订阅管理后台。你可以在网页里维护代理节点，并生成 Surge / Clash / V2RayN 等客户端可用的订阅地址。整站基于 Node.js，数据写入 SQLite，不需要额外数据库；节点录入、排序、导入导出都在后台里完成。

📦

Docker Compose 启动

一条 Compose 命令同时启动前后端。迁移时把目录拷到新机器，再执行 docker compose up -d 即可。

🎛️

网页里维护

节点、订阅、Clash 模板都在网页上维护。顺序可以拖动调整，不用手改 JSON。

🔗

多格式输出

同一批节点可以输出 Raw / Base64 / Surge / Clash 四种格式，每种格式对应一条订阅地址，互不冲突。

🔒

Session + Cookie

后台使用 Session 登录，Cookie 默认启用安全属性；启用 HTTPS 后会再加安全头。

适合谁用？ 适合已有 VPS 或自托管环境、需要整理多来源代理节点的人。它更偏个人和小团队使用，不适合大型公开服务、多租户计费或企业接入这类场景。

功能一览

支持的协议

后端会根据贴入的文本识别协议；前端也有录入引导，按字段填写即可。

🔐

SS

✈️

VMess

🪂

Trojan

⚡

VLESS

🧦

SOCKS5

🌀

Snell

🚀

Hysteria2

🎯

TUIC

订阅能做什么

可以创建多条订阅，每条订阅对应独立路径。
节点可以按协议或关键词过滤，只把需要的节点放进订阅。
整段贴入节点文本，后台会按 host + port 自动去重。
拖动即可调整顺序，客户端会按这个顺序读取节点。

四种订阅输出

Format	Path	适用客户端
`/sub/<id>`	原生	V2RayN、NekoBox 可直接订阅
`/v2ray/<id>`	Base64	Shadowrocket 及较旧的客户端
`/surge/<id>`	Surge	Surge、Stash 可直接订阅
`/clash/<id>`	Clash	Clash Verge / Mihomo / ClashX

Clash 特性

默认模板自带 3900 多条规则
rule-provider 里声明的规则会被自动展开为正式规则
可外接一个 Subconverter 后端，加载你自己写的模板
兼容 ClashMeta 与 ClashX

部署方式

部署前准备

Method	要求
源码部署	Node.js 20+、npm
Docker Compose	Docker 20+、Docker Compose v2+

部署前先复制一份配置文件，并按你的环境做必要修改：

cp .env.example .env
# 至少把 ADMIN_USERNAME / ADMIN_PASSWORD / SESSION_SECRET 改掉

Docker Compose

生产环境建议使用这种方式。前后端分别运行，Nginx 把 /api 反向代理给后端。

源码部署

一个进程同时托管 API 与静态前端，适合本地调试或小规模自用。

Docker Compose 部署

git clone https://github.com/baixiaoshengofficial/SubscribeManager.git
cd SubscribeManager
cp .env.example .env     # 见下方字段说明
docker compose up -d

停下服务、看实时日志：

docker compose down
docker compose logs -f

如果不使用 Docker Hub 镜像，也可以从当前源码构建：

docker compose up -d --build
# 等价于
make buildup

源码部署

cp .env.example .env
make install       # 安装前后端依赖
make frontend-build
make backend-dev   # 或 cd backend && BACKEND_PORT=5100 npm start

源码模式下，后端同时响应 /api/* 请求并托管 frontend/dist 里的静态文件，因此只需对外暴露 BACKEND_PORT 一个端口。

访问应用

访问地址：

Docker：http://<host>:<FRONTEND_PORT>/
源码模式：http://<host>:<BACKEND_PORT>/

在线演示 https://subscribe.baixiaosheng.de ，体验账号 / 密码均为 admin；仅用于功能演示，不要保存真实节点。

环境配置

所有环境变量都在项目根目录的 .env 文件里配置，Makefile、Docker Compose 和 Node 进程都从这里读取。

字段说明

Variable	必须	说明
`ADMIN_USERNAME`	是	后台登录账号
`ADMIN_PASSWORD`	是	后台登录密码（正式部署前务必改掉默认值）
`SESSION_SECRET`	是	长随机串，用于签名会话 cookie
`BACKEND_PORT`	是	后端 API 端口；源码模式对外只需要这个端口
`FRONTEND_PORT`	是	前端端口（Docker 模式 / Vite 开发服务器）
`DB_PATH`	否	SQLite 相对路径，默认 `./data/subscriptions.db`
`COOKIE_SECURE`	否	HTTPS 部署时设为 `true`
`PUBLIC_BASE_URL`	否	仅当 Subconverter 在外网时才需要

研发常用命令

Command	用途
`make install`	安装 frontend 与 backend 依赖
`make dev`	启动前后端（会先处理端口冲突）
`make test`	运行后端 Jest
`make test-frontend`	运行前端 Vitest
`make frontend-build`	构建前端产物到 frontend/dist
`make check`	运行完整检查：后端测试 + 前端测试 + 前端构建

界面导览

打开后台后，默认进入「控制台」视图。右上角可以切换中 / 英文和深浅主题，也能跳到 GitHub；顶部 tab 在「控制台」与「配置管理」之间切换。

后台布局 / Console

控制台

节点列表 / 创建 / 编辑 / 删除
订阅管理、路径与规则配置
Clash 模板编辑器
批量导入、拖拽排序

配置管理

协议录入对照、订阅路径编辑和告警入口都在这里。

协议与订阅

节点是什么

节点是一条代理链路配置，由 host + port + protocol 区分，包含协议参数、传输层、TLS、流控等信息。

订阅是什么

一份订阅就是「一批节点 + 一套输出规则」，对应一条 URL。客户端用这条 URL 拉配置。

每条订阅挂一条单独的路径
可按协议或关键词预先过滤，只把需要的节点放进订阅
每种输出格式都有单独的 URL：/sub、/v2ray、/surge、/clash

客户端配置示例

# Surge / Stash
https://sub.example.com/surge/myid    # 订阅地址

# Clash Verge / Mihomo
https://sub.example.com/clash/myid

# V2RayN / NekoBox (原始格式)
https://sub.example.com/sub/myid

# Shadowrocket (Base64)
https://sub.example.com/v2ray/myid

路径安全 订阅没有单独的访问权限；路径本身就是密钥。一旦泄露，别人就能拿到订阅内容。建议用 UUID 作路径。

Clash 模板

默认 Clash 模板自带 3900 多条规则，rule-provider 会在输出时自动展开为正式规则；模板以 YAML 格式存储。

如果想用自己的模板接管 Clash 输出，可以接入 Subconverter。SubscribeManager 会把节点 inline 进模板后生成最终配置：

# 配合 Subconverter 时，节点会被 inline 进模板，客户端直接从 URL 获取 Clash 配置
# 客户端无需自己订阅或拼接

架构概览

系统分三层：Vue 3 负责浏览器界面，Express 5 提供 HTTP API，SQLite 存数据。

Browser Vue 3 + Element Plus

→

Nginx / Vite proxy /api

→

Express 5 routes · services

→

SQLite data/subscriptions.db

Docker 模式下

Container	Role
`backend`	提供 API 和订阅内容，宿主机的 `./data` 会挂载给 SQLite 使用
`frontend`	Nginx 提供静态前端，反代 `/api` 给 `backend`

目录职责

Path	Purpose
`backend/`	Express 业务代码、入口 `index.js`、数据库初始化
`backend/routes/`	路由与鉴权
`backend/services/`	节点/订阅的业务逻辑
`backend/utils/`	Clash 模板展开、协议解析等
`frontend/src/`	Vue 3 源码
`frontend/dist/`	Vite 构建产物
`data/`	SQLite 数据库（工作目录）

安全要点

默认配置较简单，公开到公网前先做这四件事：

把 ADMIN_USERNAME / ADMIN_PASSWORD 从默认的 admin/admin 改掉。
设置一个足够长的 SESSION_SECRET，部署前用 pwgen 或 openssl rand 生成。
通过 HTTPS 访问时，把 COOKIE_SECURE 设成 true，避免 Cookie 通过明文传输。
订阅路径建议使用 UUID，不要使用容易猜到的名称。

反代注意 如果前面再套一层 Nginx / Caddy 做 TLS，要把 X-Forwarded-* 头透传给后端；后端会根据这些头判断订阅 URL 的协议。

常见问题

源码部署可以只开放一个端口吗？

可以。源码模式下后端既提供 /api/*，也托管 frontend/dist 静态文件，只需要开放 BACKEND_PORT。FRONTEND_PORT 只在 make dev（Vite 开发服务器）时使用。

Docker 模式下 .env 里的端口是容器内的还是宿主机的？

.env 同时用于 docker compose ports 映射和容器内进程监听，映射两端的端口号一致。所以 FRONTEND_PORT 既决定容器监听端口，也决定宿主机暴露的端口。

能不能把后端放在内网，只公开前端？

可以，生产环境也建议这样做。后端绑定到内网端口，前端通过反向代理访问它，并把 VITE_BACKEND_TARGET 指向内网地址。对外只开放 FRONTEND_PORT。

订阅路径能改成不带 /sub//v2ray//surge//clash 前缀吗？

目前 URL 结构写在路由里：/sub/:id、/v2ray/:id、/surge/:id、/clash/:id。如果想换别的路径（例如 /mysub），需要在 fork 里改路由表，或在前面加一层反向代理规则。不建议改，这些路径已经被不少客户端默认识别，改了下游也要同步调整。

版本升级会丢数据吗？

不会，数据和代码是完全分离的。SQLite 数据库放在 ./data/subscriptions.db（源码模式），或宿主机的 ./data（Docker 模式下挂载进容器）。升级只需 docker compose down 后换新镜像再 up -d；源码模式 git pull 加 make install 即可。

怎样给默认账号加二次验证？

目前只做到 Session 登录，TOTP / FIDO2 还没接入。现阶段能用上的额外防线是强密码、HTTPS、COOKIE_SECURE=true 和 IP 白名单。

Clash 订阅需要 Subconverter 后端吗？

默认不用。内置 Clash 模板已经会展开 rule-provider，输出的 YAML 可以直接给客户端使用。只有想用自己的模板接管输出时，才需要另外接入 Subconverter。