基于 FastAPI + Vue 3 的轻量节点订阅管理系统,用于集中维护代理节点、为不同用户分配节点、采集节点状态与流量,并生成 V2Ray/Shadowrocket/Clash 兼容的订阅内容。
代码开源以供参考;线上实例仅供本人个人使用,不开放注册,具体地址不在此公开。
管理台使用 Hash 路由,页面链接请保留 /#/overview、/#/nodes 等 #/ 部分;/nodes 这类无 Hash 的直链不是管理页面入口。
产品品牌和 GitHub 仓库统一为 SUB。SUB_APP_* 环境变量、sub-app 服务/数据路径、Agent 请求头与凭据派生域属于已部署实例的兼容接口,本次不做破坏性改名。
- 管理代理节点:批量粘贴、启用/停用、排序、编辑和删除。
- 支持解析
VLESS、VMess、Trojan、Hysteria2/Hy2和ShadowsocksURI。 - 管理订阅用户: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 地址等硬件标识,也不能证明请求来自某一台真实设备。
为减少一条订阅泄露影响其他客户端的范围,管理员可在用户编辑页启用设备级代理凭据隔离:
- 为每台客户端创建独立的登记链接,并在该客户端导入;旧 UA/IP 记录不会自动获得凭据。
- 在用户页点击“准备设备级凭据”。系统保留账户级凭据,同时为每个有效登记链接和已分配节点生成单独凭据。
- 等待所有目标节点确认应用后,再点击“启用严格隔离”。此后未登记链接不能刷新该用户订阅,代理认证也不再共享账户级凭据。
- 恢复兼容订阅时,系统先重新应用账户级凭据;确认目标节点均已生效后,再撤销设备级凭据并回到兼容模式。
严格模式只允许在全局功能开关启用、用户已启用独立凭据、至少有一条有效登记链接,且所有有效分配节点都支持并能应用独立凭据时切换。协议或节点能力不满足时,切换会被拒绝,不会静默回退到共享认证。
数据库 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.targetproxy_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;常规验证请指定临时 outDirnpm 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 适配器,不以整体重写替代渐进修复。
- 凭据与设备正确性:协议隔离;已有 Agent 或凭据历史的节点通过新节点迁移,不直接覆盖协议。旧设备记录可在原名额上转换为专属订阅链接,保留访问历史。
- 用户订阅体检:用户页提供只读体检,分别报告账户限制、设备准入、节点分配、所选格式的预期下发和凭据同步结果;不新增设备、不产生真实拉取记录、不公开凭证。
- 节点替换(待实现):候选实例接入、配置检查、测试用户同步、外部认证与出口验证完成后才切换;旧实例保留明确的回退窗口,回退涵盖凭据状态。
- 状态可信度(待完善):区分主机在线、Agent 心跳、指定配置版本已应用、外部代理验证;过期数据为未知,自报成功不替代外部验证。
- 安装与接管(部分完成):新机安装与已有原生服务接管分开;接管提供只读预览、凭据比对、候选配置和状态准备,保留回退步骤。短时入网凭证、已有计量基线迁移和全自动事务接管仍待完善。
- 发布验收(待完善):绑定源码、前端产物、迁移版本、备份、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 和基础检查-
提交前建议本地跑一遍:
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 天。该脚本只生成同机备份,异地副本和恢复演练仍需由部署环境单独配置。
本项目采用 MIT License。