Skip to content
MinG-98Public

About

FastAPI + Vue 3 的轻量代理节点订阅管理系统:集中维护 VLESS/Hysteria2 等节点、按用户分配订阅、采集节点状态与流量,生成 V2Ray/Clash 兼容订阅内容

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

SUB

CI License: MIT Python 3.10+

基于 FastAPI + Vue 3 的轻量节点订阅管理系统,用于集中维护代理节点、为不同用户分配节点、采集节点状态与流量,并生成 V2Ray/Shadowrocket/Clash 兼容的订阅内容。

代码开源以供参考;线上实例仅供本人个人使用,不开放注册,具体地址不在此公开。 管理台使用 Hash 路由,页面链接请保留 /#/overview、/#/nodes 等 #/ 部分;/nodes 这类无 Hash 的直链不是管理页面入口。 产品品牌和 GitHub 仓库统一为 SUB。SUB_APP_* 环境变量、sub-app 服务/数据路径、Agent 请求头与凭据派生域属于已部署实例的兼容接口,本次不做破坏性改名。

目录

功能

  • 管理代理节点:批量粘贴、启用/停用、排序、编辑和删除。
  • 支持解析 VLESS、VMess、Trojan、Hysteria2/Hy2 和 Shadowsocks URI。
  • 管理订阅用户:UID、备注、节点分配、启用/停用和订阅令牌轮换。
  • 设备访问记录:按订阅链接或旧版 UA/IP 归档访问标识、User-Agent、IP、拉取次数和最近活动;这些信号不等于真实硬件指纹。
  • 单独停用或删除设备,支持设备数量上限。
  • 生成 Base64/V2Ray/Shadowrocket 原始订阅,以及 Clash/Mihomo YAML 配置。
  • 仪表盘统计节点、用户、设备、24 小时拉取次数、活跃设备和最近拉取记录。
  • 通过哪吒 API 采集节点在线状态、心跳、速度和 30 天内的节点流量历史。
  • 为已适配节点维护用户级凭据状态;首批适配 Hysteria2 和 VLESS,旧凭据支持短暂兼容窗口。
  • 通过独立采集脚本读取代理核心的用户级流量,并将哪吒整机流量与用户配额统计分开。
  • 从管理机一键部署全新 Debian/Ubuntu Hy2 VPS/NAT 节点并注册 Agent;部署前只读预检,部署后核对中心心跳与应用版本。
  • 为设备生成可撤销、可轮换的专属订阅访问标识,同时保留旧版 UA/IP 设备记录用于审计。
  • 可选设备级代理凭据隔离:按“准备 → 节点确认 → 严格启用”切换;恢复时先确认兼容凭据已应用,再撤销设备级凭据。
  • 使用 SQLite 持久化数据;公开 /healthz 只提供最小存活状态,详细健康信息通过需要管理员登录的 /api/admin/healthz 查看。

设备级凭据隔离

设备管理记录的是“哪条登记订阅链接访问过服务”,并非手机/电脑的硬件指纹。登记链接是 bearer 凭据,可以被复制或转发;当前系统不读取 IMEI、序列号、MAC 地址等硬件标识,也不能证明请求来自某一台真实设备。

为减少一条订阅泄露影响其他客户端的范围,管理员可在用户编辑页启用设备级代理凭据隔离:

  1. 为每台客户端创建独立的登记链接,并在该客户端导入;旧 UA/IP 记录不会自动获得凭据。
  2. 在用户页点击“准备设备级凭据”。系统保留账户级凭据,同时为每个有效登记链接和已分配节点生成单独凭据。
  3. 等待所有目标节点确认应用后,再点击“启用严格隔离”。此后未登记链接不能刷新该用户订阅,代理认证也不再共享账户级凭据。
  4. 恢复兼容订阅时,系统先重新应用账户级凭据;确认目标节点均已生效后,再撤销设备级凭据并回到兼容模式。

严格模式只允许在全局功能开关启用、用户已启用独立凭据、至少有一条有效登记链接,且所有有效分配节点都支持并能应用独立凭据时切换。协议或节点能力不满足时,切换会被拒绝,不会静默回退到共享认证。

数据库 schema migration v17 为现有用户默认写入 off,给既有设备补充随机内部 scope,并为设备凭据新增可空关联;它不会重写任何现存凭据。发布前仍应按运维流程备份数据库。旧服务路径、环境变量和 Agent 协议继续兼容,不需要因品牌更名手工迁移目录。

封锁设备或撤销登记链接会立即阻止后续使用该链接刷新订阅,并将该设备凭据标记为撤销;远端节点要等 Agent 下一次成功应用配置后才会移除旧代理凭据。已经导入客户端的配置在节点完成同步前仍可能可用。轮换订阅链接本身不会轮换已缓存的代理凭据;如怀疑代理凭据泄露,请同时轮换设备凭据并确认节点同步完成。

设备页的代理流量按最近 30 天已采集的 Hysteria2/VLESS 用户计数器汇总。没有独立计数器的节点不贡献设备流量;显示 0 不代表没有实际使用。

观测与拓扑

  • /api/admin/overview/topology 从当前分配关系生成管理拓扑,保留用户、节点和服务器三层关系。
  • /api/admin/latency 与 /api/admin/latency/probe 提供受控的真实探测:控制面、节点入口 TCP 和代理出口分别记录;探测临时文件使用 root-only 权限,凭据不会写入状态文件或 API 响应。
  • 仪表盘桌面端使用横向流量/活跃度柱状图;拓扑中的用户名在图外显示并稳定分色。mobile-enhancements 资源负责跨视口的品牌标记和紧凑布局。
  • /healthz 只返回 ok 和时间戳,避免向未认证访问者暴露数据库、采集器、协调器和 Agent 详情;管理员登录后通过 /api/admin/healthz 获取完整状态。

运维脚本与定时任务

仪表盘和健康检查展示的采集/协调状态并非由应用自动刷新,而是由以下独立脚本写入 /var/lib/sub-app/*.json 状态文件,需要通过 cron 或 systemd timer 周期执行:

脚本 作用 关键环境变量(均有默认值,可省略)
scripts/nezha_collector.py 单次采集哪吒整机状态与流量 NEZHA_BASE_URL、NEZHA_API_TOKEN(或写入 NEZHA_ENV_FILE 指向的文件,默认为 /etc/sub-app/nezha.env)
scripts/proxy_collector.py 单次采集 Hysteria2/VLESS 用户级流量计数器 SUB_APP_VLESS_STATS_BINARY(默认 /usr/local/libexec/sub-app-vless-stats)、SUB_APP_PROXY_STATUS
scripts/reconciler.py 将用户分配与本机代理适配器配置做最终一致性协调(新增/轮换/吊销凭据的重试循环) SUB_APP_PROXY_ADAPTERS_ENV(默认 /etc/sub-app/proxy-adapters.env)、SUB_APP_RECONCILER_STATUS
scripts/latency_probe.py 触发一次真实延迟探测(控制面/节点入口/代理出口) SUB_APP_LATENCY_STATUS、SUB_APP_LATENCY_LOCK、SUB_APP_HYSTERIA_BIN、SUB_APP_SING_BOX_PROBE_BIN、SUB_APP_XRAY_PROBE_BIN

VLESS REALITY 出口优先使用官方 Xray 客户端探针(默认 /usr/local/libexec/sub-app-xray-probe),避免 sing-box 与 Xray 新版 REALITY 的 ML-KEM ClientHello 差异造成误报。Linux x86-64 可在部署机上运行 sudo bash ./scripts/install_xray_probe.sh 安装固定版本并校验 SHA-256;其他架构应自行安装受信任的 Xray 版本并通过 SUB_APP_XRAY_PROBE_BIN 指定路径。未安装时,现有 sing-box 探针仍作为回退。

生产服务启动前会检查 SUB_APP_DB 指向的数据库。已有应用表但两张核心表都没有记录时,默认拒绝启动,以免误把空库当成正式数据;只有在明确创建全新空实例时,才可临时在 /etc/sub-app/app.env 设置 SUB_APP_ALLOW_EMPTY_DB=1 完成首次初始化,确认数据已创建后应移除此项。

延迟探测通常由仪表盘按需触发(POST /api/admin/latency/probe),无需单独定时;其余三个脚本建议用 systemd timer 定期执行,例如:

仪表盘触发探测时,/api/admin/latency/probe 用当前运行 FastAPI 进程的解释器去启动 scripts/latency_probe.py(即 sys.executable),所以正常情况下不需要单独配置。仅当你想让它用另一个解释器(比如手动跑的场景与服务进程的 venv 不一致)时才需要设置 SUB_APP_PYTHON 覆盖。

# /etc/systemd/system/sub-app-nezha-collector.service
[Service]
Type=oneshot
User=sub-app
EnvironmentFile=/etc/sub-app/app.env
ExecStart=/opt/sub-app/.venv/bin/python /opt/sub-app/scripts/nezha_collector.py

# /etc/systemd/system/sub-app-nezha-collector.timer
[Timer]
OnBootSec=1min
OnUnitActiveSec=5min

[Install]
WantedBy=timers.target

proxy_collector.py 和 reconciler.py 可按相同方式配置各自的 .service/.timer,运行间隔按节点数量和流量精度需求调整。

scripts/pilot_hysteria_client.py 与 scripts/pilot_vless_client.py 是一次性人工诊断脚本,用于在排查某个节点握手问题时手动运行,不应加入定时任务。

节点 Agent(agent/ 目录,独立于以上中心侧脚本)的部署方式见 agent/README.md。

节点的 adapter_kind 是显式持久化配置,不再以数据库自增 ID 决定适配器。新建节点默认 shared;管理员可在节点编辑页将其设为 remote_agent、local_hy2 或 local_vless,后两者分别绑定本机唯一的 HY2/VLESS 适配器。SQLite v5 迁移仅对实际存在且协议匹配的旧 ID 一次性回填,缺失或协议不匹配的记录保持 shared,不会新建节点或改动分配。

新节点一键接入

针对全新的 Debian/Ubuntu VPS 或 NAT 小鸡,可以从已验证管理机运行 scripts/bootstrap_node.py:先只读检查 SSH 主机身份、目标机空闲情况、TLS 材料、端口和美国控制面的健康状态;确认后加 --apply 安装固定摘要校验的 Hysteria2 和本项目 Agent,自动按两位序号、地区旗帜/名称和 Hy2 协议后缀生成规范节点名,创建节点并注册 Agent。订阅 URI 的名称始终由管理面板节点名生成,所以 Clash 与 V2Ray/小火箭订阅显示一致,即使旧 URI 缺少名称片段也不例外。最终验收要求收到新鲜且 generation 匹配的心跳,并用本地 Hy2 认证验证控制面凭据确已下发。

示例、证书/端口映射准备、失败处理和支持边界见 新节点部署手册。脚本不会接管现有 Xray/sing-box/Hy2 服务器,不会修改 SSH、系统防火墙、提供商 NAT 映射或 DNS,也不会给新节点分配用户。未提供 --client 执行公网客户端探测时,成功输出不代表公网代理链路已验证。VLESS/Xray 新机自动部署目前不支持。

订阅公告使用独立的 announcements 与 announcement_allocations 表,不参与节点采集、探测、适配器和流量统计;公告仍按订阅格式输出兼容的提示条目。SQLite v14 迁移旧版本明确生成的端口 1 占位 URI;v16 幂等核验端口 1,并补迁移同一全零 UUID / 127.0.0.1 的端口 2、3 占位 URI,严格检查端口边界后复制原有用户分配。旧 Node 行和原分配记录保留作兼容核对,不会因迁移级联删除。

远程 Agent 注册使用 POST /api/admin/agents,明文 token 仅返回一次且响应禁止缓存;注册不会启用用户级凭据。节点侧配置需要由操作者按实际服务名、代理引擎和配置路径补齐,不能仅从订阅 URI 推断。轮换先生成 24 小时有效的观察 token,旧 token 继续有效;新 token 成功心跳后由管理员确认切换,确认后旧 token 即失效。完整节点侧字段见 agent/README.md。

支持的订阅格式

订阅接口由 target 参数选择输出格式:

  • v2ray、base64、shadowrocket:将原始节点 URI 按行编码为标准 Base64;shadowrocket 是给小火箭使用的明确格式入口。
  • raw:按行输出原始节点 URI。
  • clash、clashmeta、mihomo:输出包含代理、自动测速组和节点选择组的 YAML。

实际订阅地址由系统为每个用户生成,不要把包含用户令牌的完整订阅链接提交到 Git 或公开分享。

技术栈

  • Python 3.10+
  • FastAPI / Uvicorn
  • SQLAlchemy + SQLite
  • itsdangerous 会话签名
  • PyYAML
  • Vue 3 + Vite 前端(源码见 frontend/,线上使用构建后的静态 JS/CSS 资源)
  • httpx(哪吒 API 和本地采集器)

项目结构

.
├── app/
│   ├── converter.py   # 节点 URI 解析与订阅格式转换
│   ├── credentials.py # 用户节点凭据的派生、加密和脱敏输出
│   ├── proxy_adapters.py # Hysteria2/VLESS 代理适配器
│   ├── traffic.py     # 哪吒采集和流量增量归一化
│   ├── agent_api.py   # 节点 Agent 接入
│   ├── main.py        # FastAPI 应用、管理 API 和订阅接口
│   └── models.py      # SQLAlchemy 数据模型
├── scripts/           # 采集/同步脚本与新节点一键接入入口
├── deploy/
│   ├── NEW-NODE.md    # 新节点准备、端口/TLS、验收和故障处理
│   └── bootstrap_worker.py # 仅经 SSH 在目标新机运行的安装工作进程
├── frontend/          # 管理界面源码(Vue 3 + Vite,构建产物输出到 static/)
├── static/
│   ├── index.html     # 管理界面入口(由 frontend/ 构建生成,不要手改)
│   └── assets/        # 前端构建产物
├── .github/
│   ├── workflows/ci.yml          # lint、格式检查和测试
│   └── pull_request_template.md
├── requirements.txt       # 运行依赖
├── requirements-dev.txt   # 运行依赖 + ruff/black/pytest
├── pyproject.toml         # ruff/black 配置
├── .pre-commit-config.yaml
├── .gitignore
└── README.md

运行时的 .env、SQLite 数据库、虚拟环境和缓存目录不属于源代码,均由 .gitignore 排除。

配置

启动前必须设置以下环境变量:

变量 作用
SUB_APP_ADMIN_PASSWORD 管理后台登录密码
SUB_APP_ADMIN_USERNAME 管理台显示的管理员名称,默认为 admin
SUB_APP_SECRET Cookie 会话签名密钥,应使用随机长字符串
SUB_APP_SESSION_MAX_AGE 管理会话有效期秒数,默认 8 小时
SUB_APP_DB SQLite 数据库路径;文件数据库必须使用绝对路径;不设置时默认为项目根目录下的 data.db
SUB_APP_PUBLIC_BASE 生成订阅链接时使用的公网基地址

示例(请替换所有占位值,不要把真实值写入仓库):

export SUB_APP_ADMIN_PASSWORD='change-this-password'
export SUB_APP_ADMIN_USERNAME='admin'
export SUB_APP_SECRET='generate-a-long-random-secret'
export SUB_APP_SESSION_MAX_AGE='28800'
export SUB_APP_DB='/var/lib/sub-app/data.db'
export SUB_APP_PUBLIC_BASE='https://your-domain.example'

本地运行

git clone https://github.com/MinG-98/SUB.git
cd SUB

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

export SUB_APP_ADMIN_PASSWORD='change-this-password'
export SUB_APP_SECRET="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
export SUB_APP_DB="$PWD/data.db"
export SUB_APP_PUBLIC_BASE='https://your-domain.example'

uvicorn app.main:app --host 127.0.0.1 --port 8080 --no-access-log

数据库表会在应用首次启动时自动创建。正式部署时建议让 Caddy、Nginx 或其他反向代理负责 HTTPS,并将 Uvicorn 仅绑定在回环地址或受控内网地址。

前端开发

管理界面源码在 frontend/(Vue 3 + Vite),构建产物直接输出到 static/,由 FastAPI 在 / 和 /static 提供服务:

cd frontend
npm ci
npm run dev     # 本地开发,通过 vite 代理转发 /api、/sub、/healthz 到 127.0.0.1:8080
npm run build   # 默认写入 ../static;常规验证请指定临时 outDir

npm run dev 默认将 API 请求代理到 http://127.0.0.1:8080(对应上一节的本地运行命令),需要本地已启动后端。常规开发和 CI 应把构建输出到临时目录(例如 npm run build -- --outDir /tmp/sub-ui-build);不要因此自动覆盖或提交 static/。CI 会将同一提交的后端源码与临时目录构建出的前端 static/ 组装为保留 7 天的 GitHub Actions artifact;这只是未部署的发布候选,不会发布到生产或更新仓库 static/。下载后仍须先做 UI 验收并核实目标机的路径、环境文件、数据库和回滚方案。

deploy/systemd/sub-app.service 是单机参考单元:假设代码安装在 /opt/sub-app、运行账号为 sub-app、环境文件为 /etc/sub-app/app.env、反向代理连接 127.0.0.1:8080;Uvicorn 使用单 worker,状态目录为权限受限的 /var/lib/sub-app,并关闭会记录 /sub/{token} 路径的访问日志。部署前须确认 SUB_APP_DB 等变量指向现有生产数据,而不是让新服务意外创建一份空数据库。此模板未在生产启用,也不替代现有 HTTPS 代理与定时采集服务。

deploy/systemd/sub-app-backup-root.service 使用同一环境文件中的 SUB_APP_DB 和仓库脚本 /opt/sub-app/scripts/backup_db.py;该 root 变体只授予 CAP_DAC_READ_SEARCH 以读取受限应用数据库,备份写入独立的 /var/lib/sub-app-backup。常规 sub-app-backup.service 则以应用账号运行。两者均只生成同机副本,异地备份与恢复演练仍需另行配置。

本机 VLESS 同步不要求 Web 服务获得 root 或 /etc/sing-box-reality 写权限。需要将 scripts/vless_sync_helper.py 安装为 root 所有的 /usr/local/libexec/sub-app-vless-sync-root.py,安装 deploy/systemd/sub-app-vless-sync.socket 与 sub-app-vless-sync@.service 后启用 socket。Unix socket 仅开放给 sub-app 组;root helper 固定只改 reality-in 的 VLESS 用户列表、固定执行 sing-box 校验及 sing-box-reality.service 重启,并在失败时恢复原配置。不要给 Web 服务配置通用 sudo、shell 或任意路径写入权限。

主要接口

接口 说明
GET / 管理后台页面
GET /healthz 公开最小存活检查,不返回内部组件详情
GET /api/admin/healthz 管理员登录后查看数据库、采集器、协调器、Agent 和适配器详情
GET /api/admin/audit-logs?limit=100 查看最近的成功管理员写入操作元数据(最多 250 条)
POST /api/admin/login 管理员登录
/api/admin/nodes 节点增删改查
/api/admin/nodes/{id}/traffic 节点流量曲线和时间范围汇总
POST /api/admin/agents 为已设为 remote_agent 的节点一次性签发 token
/api/admin/agents/{id}/rotate 分阶段轮换或取消 Agent token
POST /api/admin/friends/{id}/device-credentials/prepare 保留兼容凭据并准备设备独立凭据
POST /api/admin/friends/{id}/device-credentials/activate 所有节点确认后启用严格设备隔离
POST /api/admin/friends/{id}/device-credentials/restore 分阶段恢复账户级兼容凭据
/api/admin/collector/status 哪吒、代理流量和节点 Agent 采集状态
/api/admin/friends 订阅用户增删改查
/api/admin/devices 设备记录管理
GET /api/admin/stats 统计和最近拉取记录
GET /sub/{token} 生成订阅内容,使用 target 选择格式

除公开最小存活检查和订阅接口外,管理接口需要登录 Cookie。订阅响应显式设置 private, no-store;订阅令牌本身等同于访问凭据,应按密码处理。

开发规范

分阶段演进与验收

保留当前界面和原生 Xray / Hysteria2 / sing-box 适配器,不以整体重写替代渐进修复。

  1. 凭据与设备正确性:协议隔离;已有 Agent 或凭据历史的节点通过新节点迁移,不直接覆盖协议。旧设备记录可在原名额上转换为专属订阅链接,保留访问历史。
  2. 用户订阅体检:用户页提供只读体检,分别报告账户限制、设备准入、节点分配、所选格式的预期下发和凭据同步结果;不新增设备、不产生真实拉取记录、不公开凭证。
  3. 节点替换(待实现):候选实例接入、配置检查、测试用户同步、外部认证与出口验证完成后才切换;旧实例保留明确的回退窗口,回退涵盖凭据状态。
  4. 状态可信度(待完善):区分主机在线、Agent 心跳、指定配置版本已应用、外部代理验证;过期数据为未知,自报成功不替代外部验证。
  5. 安装与接管(部分完成):新机安装与已有原生服务接管分开;接管提供只读预览、凭据比对、候选配置和状态准备,保留回退步骤。短时入网凭证、已有计量基线迁移和全自动事务接管仍待完善。
  6. 发布验收(待完善):绑定源码、前端产物、迁移版本、备份、UI 基线、订阅与代理验证;明确数据库回退限制。单元测试通过不代表已经上线。

每一阶段按“复现 → 最小修复 → 回归测试 → 独立复核 → 发布验收”推进,未完成的阶段不标为已交付。

只读订阅体检

用户页点击 订阅体检,选择 Clash、小火箭或 V2Ray。默认模拟“新设备”;已有设备可单独选择,帮助区分设备名额不足、封锁、专属链接撤销、配额/到期限制与节点凭据未同步。

接口为 GET /api/admin/friends/{id}/subscription-diagnostics?target=shadowrocket,可追加 device_id,仅限管理员,响应禁止缓存。它与真实订阅复用节点选择逻辑,但不会拉取真实订阅、改变设备访问记录、返回 URI/密码/UUID/token 或触发网络探针。节点渲染数量以通过账户和设备准入为前提;公告单独计数。选择设备记录只是模拟,不证明客户端持有该记录的链接或匹配其 UA/IP 指纹。Agent 心跳及自报配置代次与外部代理可用性分开看待。

发布目录预检

CI 发布候选解压后,先执行 python3 scripts/verify_release.py --release-dir /absolute/release/path。工具只读检查目录结构、入口资源完整性、路径边界、符号链接及 macOS ._* 元数据,并输出静态文件哈希。保留现有样式的发布可以加 --expected-css-sha256 <原线上CSS哈希>;不通过时不要切换生产目录。

这不是源码来源认证、完整 JS/CSS 依赖分析或线上验收。当前 artifact 名含提交号,目录内部未带签名来源证明;仍需核对 GitHub Actions 运行的提交与产物,备份数据库、保留旧 release,并验证公网入口及代理出口。

设备名额已满时的无删除恢复

在设备页确认对应的旧访问记录,选择 原名额转专属链接,将返回的 Clash、小火箭或 V2Ray 链接导入对应客户端。该操作复用原记录,不增加名额、不清除历史,也不会解除封锁。

使用专属链接后,IP 或 UA 变化会更新该记录而不创建新设备。普通订阅链接不会自动升级,仍采用旧的 UA+IP 识别与全部设备行计数;历史记录不会自动过期或合并。专属链接是可转发的 bearer 凭证,不是硬件身份或严格的物理设备数量证明。转换不会撤销用户的普通订阅令牌;轮换专属链接会使此前该设备的专属链接失效。

python -m pip install -r requirements-dev.txt
pre-commit install   # 可选:提交前自动跑 ruff/black 和基础检查
  • 代码风格由 black 统一格式化,静态检查用 ruff;配置见 pyproject.toml。

  • 提交前建议本地跑一遍:

    ruff check .
    black --check .
    pytest -q
  • GitHub Actions(.github/workflows/ci.yml)在每次 push/PR 到 master 时执行同样的检查,PR 请保持 CI 全绿再合并。

  • CI 也会运行前端测试和 Vite 生产构建(构建到临时目录,不覆盖仓库 static/);static/ 仍是 FastAPI 当前直接服务的运行资产,CI 只验证其入口引用有效文件,不代表它与源码构建内容一致。生产发布应使用经 UI 验收的构建产物,不能把 CI 成功当成已部署或视觉验收。

  • PR 请使用 .github/pull_request_template.md 中的 Summary/Test plan 结构描述改动。

安全注意事项

  • 不要提交 .env、data.db、订阅令牌、节点 URI、密码、私钥或其他运行时凭据。
  • 哪吒 Token、代理适配器密钥和节点配置应通过 VPS 上的 root-only 环境文件注入,不写入仓库、数据库或页面。
  • 管理密码和 SUB_APP_SECRET 应使用随机且互不重复的值,并通过服务管理器或安全的环境文件注入。
  • 生产环境必须使用 HTTPS;应用设置的会话 Cookie 启用了 HttpOnly、Secure 和 SameSite=Lax,默认有效期为 8 小时。
  • 应用会为管理页和 API 添加 HSTS(仅 HTTPS 请求)、CSP、nosniff、Referrer-Policy 和禁止 iframe 嵌入等响应头;反向代理应正确转发 X-Forwarded-Proto。
  • 限制管理后台的公网访问范围,并定期轮换暴露过的管理员密码、会话密钥和订阅令牌。
  • 管理员登录在 SQLite 中按 ASGI 对端地址持久化失败次数,默认 15 分钟内 8 次失败后暂时锁定 15 分钟;仅在可信代理配置正确时才应让 Uvicorn 解析转发地址,应用不会直接信任请求中的 X-Forwarded-For 或 CF-Connecting-IP。登出会在服务端撤销对应会话;管理员凭据变更会轮换持久化会话纪元,因此即使之后恢复旧密码,旧 Cookie 也不会复活。数据库仅保存会话 ID 的 HMAC 摘要,不保存 Cookie 原文。
  • 已认证管理员的成功写入操作会记录到只追加的 admin_audit_logs 表,可通过 GET /api/admin/audit-logs 查看;仅记录会话指纹、方法、路径和状态码,不记录请求正文或凭证值。因管理员仍共用一个账号,该指纹只能区分会话,不能证明具体操作者;失败尝试和字段级前后值目前不在该日志范围内。
  • SQLite 数据库包含用户、设备、IP、User-Agent 和拉取记录,应设置合适的文件权限并纳入独立备份。
  • SQLite 文件数据库启动时启用 WAL;管理健康页会报告运行时 SQLite 版本,并对尚未确认包含 WAL-reset 修复的版本显示警告(发行版可能有回补,需按实际构建核实;参考 SQLite WAL 文档)。不要直接复制仍在运行的 .db 文件;使用 scripts/backup_db.py 的在线备份(包含已提交的 WAL 数据),它会验证 quick_check、以 0600 保存快照,并仅按配置清理专用备份目录中超过保留期的 sub-app-backup-*.sqlite3。应用与备份服务都必须显式配置 SUB_APP_DB,指向绝对路径下已初始化且服务账号可写的数据库;应用 systemd 模板会在启动前拒绝空库或错库。直接运行备份脚本时,默认目录为 /var/backups/sub-app;systemd 备份单元使用受限的 /var/lib/sub-app-backup(由 StateDirectory 创建),默认保留 30 天。该脚本只生成同机备份,异地副本和恢复演练仍需由部署环境单独配置。

License

本项目采用 MIT License。

About

FastAPI + Vue 3 的轻量代理节点订阅管理系统:集中维护 VLESS/Hysteria2 等节点、按用户分配订阅、采集节点状态与流量,生成 V2Ray/Clash 兼容订阅内容

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages