一个轻量级的VPS流量监控工具，帮助自建节点用户实时掌握各节点的流量使用情况。通过获取VPS服务商的流量数据并注入到订阅文件中，让你在使用代理客户端时直观地了解每个节点的流量状态。
- 实时监控: 获取VPS流量使用数据，包括已用流量、剩余流量、总流量和重置时间
- 订阅集成: 自动将流量信息注入到订阅文件，支持在代理软件中直观显示
- 灵活展示: 支持自定义流量单位、日期格式和分组位置
- 路由配置更灵活:
providers与routes分层配置，支持账号复用，并允许对外访问路径与本地订阅文件独立映射 - 全局默认与局部覆盖: 先设全局默认，再按路由单独覆盖缓存、超时、流量展示等
- 高效缓存: 多级缓存机制，智能避免API限速，接口异常时降级返回原始文件
- 容器部署: 支持Docker容器化部署，便于维护和迁移
- 多服务商: 支持多种VPS服务商API，持续扩展中
服务商 |
流量查询 |
重置日期 |
配置参数映射 |
|---|---|---|---|
| BandwagonHost | ✅ | ✅ | api_id: VEIDapi_key: API KEY |
| RackNerd | ✅ | ✅ 每月 1 日（美西时区）[1] |
api_id: API Hashapi_key: API Key |
| 更多服务商 | 🔄 | 🔄 | 敬请期待 |
| Passthrough * | — | — | api_id: 无需api_key: 无需 |
*
passthrough为特殊类型，不调用服务商 API，订阅文件原样返回，不附加任何流量信息。
VPSub 通过以下步骤处理每个订阅请求：
- 根据请求路径匹配对应的
route配置 - 通过
provider_ref找到对应的服务商账号 - 调用服务商 API 获取流量数据（带缓存机制）
- 读取
route中指定的本地订阅文件 - 将流量信息写入 HTTP 响应头
- 如果启用
usage_display，将流量信息追加到订阅分组中 - 返回处理后的订阅内容（API 异常时降级返回原始文件）
# 克隆仓库
git clone https://github.com/djx30103/vpsub.git
cd vpsub
# 直接运行
go run ./cmd/server
# 或者构建后运行
go build -o vpsub ./cmd/server
./vpsubdocker run -d \
--name vpsub \
-p 30103:30103 \
-v $(pwd)/config:/app/config \
-v $(pwd)/subscriptions:/app/subscriptions \
ghcr.io/djx30103/vpsub:latestservices:
vpsub:
image: ghcr.io/djx30103/vpsub:latest
container_name: vpsub
ports:
- "30103:30103"
volumes:
- ./data/config:/app/config
- ./data/subscriptions:/app/subscriptions
restart: unless-stopped
environment:
TZ: Asia/Shanghai运行：
docker-compose up -d- config: 存放配置文件
config.yml - subscriptions: 存放订阅文件（支持子目录组织）
providers 定义服务商账号，routes 定义订阅路径并引用账号：
providers:
hk-bwh:
type: bandwagonhost
api_id: "VEID"
api_key: "API KEY"
routes:
- path: "/client-a"
file: "hk/proxy.yaml"
provider_ref: "hk-bwh"| 配置项 | 说明 |
|---|---|
providers.<name> |
服务商账号，名称自定义，供 provider_ref 引用 |
providers.<name>.type |
服务商类型，见支持的服务商；大小写不敏感（如 bandwagonhost、BandwagonHost、BANDWAGONHOST 均可） |
providers.<name>.api_id |
服务商账号标识，各服务商含义不同（passthrough 类型无需填写） |
providers.<name>.api_key |
服务商 API 密钥（passthrough 类型无需填写） |
routes[].path |
对外访问路径，必须以 / 开头；末尾多余 / 会被自动归一化；禁止根路径 /、..、. 与空路径段（如 //）；归一化后必须唯一 |
routes[].file |
本地订阅文件路径，使用相对路径并相对于 subscriptions/ 目录；禁止绝对路径、..、. 与空路径段（如 //） |
routes[].provider_ref |
引用的服务商账号名，必须已在 providers 中定义 |
修改配置文件后需重启服务生效，订阅文件修改后无需重启。
如果只需要将订阅文件原样对外暴露，无需流量信息，可使用 passthrough 类型，不需要填写 api_id 和 api_key：
providers:
static-sub:
type: passthrough
routes:
- path: "/client-b"
file: "static.yaml"
provider_ref: "static-sub"启用后，会在订阅分组中追加流量和重置日期信息：
defaults:
usage_display:
enable: true
prepend: false # true: 置顶，false: 末尾
traffic_format: "⛽ 已用流量 {{.used}} / {{.total}}"
traffic_unit: "G" # 可选: K、M、G、T
reset_time_format: "📅 重置日期 {{.year}}-{{.month}}-{{.day}}"模板变量说明：
| 变量 | 用途 | 所属字段 |
|---|---|---|
{{.used}} |
已用流量 | traffic_format |
{{.total}} |
总流量 | traffic_format |
{{.year}} |
重置年份 | reset_time_format |
{{.month}} |
重置月份 | reset_time_format |
{{.day}} |
重置日期 | reset_time_format |
traffic_format必须同时包含{{.used}}和{{.total}}；reset_time_format至少包含一个日期变量，且只支持{{.year}}、{{.month}}、{{.day}}。
也可以在单个 route 中覆盖，未覆盖的字段继续继承 defaults：
routes:
- path: "/client-a"
file: "hk/proxy.yaml"
provider_ref: "hk-bwh"
usage_display:
enable: true
prepend: true
traffic_unit: "M"可按 User-Agent 限制订阅路径的访问来源，未配置时不校验：
routes:
- path: "/client-a"
file: "hk/proxy.yaml"
provider_ref: "hk-bwh"
access_control:
user_agent: "ClashX" # 仅允许 User-Agent 与 "ClashX" 完全一致的请求在 defaults 中设置全局默认值，在单个 provider 的 overrides 中按需覆写：
defaults:
provider:
api_ttl: 300s # 服务商 API 缓存时间，0 表示不缓存
request_timeout: 10s # API 请求超时
update_interval: 24h # 客户端订阅更新间隔
providers:
us-bwh:
type: bandwagonhost
api_id: "VEID"
api_key: "API KEY"
overrides: # 覆盖该账号的默认值
api_ttl: 120s
request_timeout: 15s
update_interval: 12h- 最小配置示例：config/config.yml
- 完整配置示例：config/config.full.yml
path 即完整对外路径，订阅链接格式为：
http://your-server:30103<path>
例如 path: "/client-a" 对应：
http://your-server:30103/client-a
本项目采用MIT许可证，详见LICENSE文件。