shujakuin/shusub2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
31 Commits 1 Branch 0 Tags
main
T
Clone
Open with VS Code Open with VSCodium Open with Intellij IDEA
Download ZIP Download TAR.GZ Download BUNDLE

README.md

shusub2

  • 文档层级：客户端工具
  • 应用性质：客户端 TUI
  • 源码来源：repo 原生
  • 运行关系：客户端工具
  • 部署模型：无
  • 对应服务：无
  • 对应 stack：无
  • Secret 边界：本地用户配置
  • 目标 API：Pricing Monitor GET /api/ui-data?view=workspace
  • 分发方式：uvx / uv tool install
  • 包名：shusub2
  • 命令名：shusub2
  • 本地状态路径：~/.config/shusub2/
  • 默认数据源：Pricing Monitor GET /api/ui-data?view=workspace

shusub2 是 Sub2API 聚合运维 TUI。默认模式只读取 server2 Pricing Monitor 后台生成的内存 snapshot，不直接访问 Accounts helper、sub2api-status、Sub2API admin API、PostgreSQL、SSH 或 pricing upstream。每次数据刷新只请求一次 workspace projection；Dashboard、Accounts、Sources、Requests 和 Errors 共用同一份进程内缓存。缓存保留 服务端 workspace weak ETag；TTL 到期或按 r 后只做条件 GET，未变时 bodyless 304 会续期既有 已验证 snapshot，且不会附加 refresh=1 或触发服务端采集。workspace URL 必须直接指向最终 端点；客户端拒绝重定向，以免把内存 validator 带往其它 origin。后台 snapshot 读取之外，默认启动仍会进行一次短超时的 Gitea 版本检查；使用 --no-version-check 或 SHUSUB2_NO_VERSION_CHECK=1 可关闭它。

Quick Start

已安装时直接运行：

shusub2

默认 workspace URL 是 Tailscale HTTPS 入口：

https://price.tailbeb9ad.ts.net/api/ui-data?view=workspace

覆盖并保存 workspace URL：

shusub2 \
  --workspace-url https://price.tailbeb9ad.ts.net/api/ui-data?view=workspace \
  --save-config

从 Gitea 安装为用户命令：

uv tool install git+https://gitea.shujk.top/shujakuin/shusub2.git
shusub2

也可以一次性运行：

uvx --from git+https://gitea.shujk.top/shujakuin/shusub2.git shusub2

Data Contract

Pricing Monitor 在后台按固定节奏采集并裁剪数据。普通 workspace HTTP 读取只复制 最近一次内存 snapshot，不触发 SSH、生产 SQL、旧 helper refresh 或 pricing source refresh。组件失败时服务端保留对应 last-good 数据，并在 components / state 中标记 stale、partial 和更新时间。

Workspace 当前提供以下有界 projection：

  • accounts：按完整 (account_id, account_name) 对齐 server6/server4 fresh binding 和 scheduled-test plan 的账号摘要、quota window 与当日用量；active_state、schedulable_state 是 yes / partial / no，last_test_state 另可为 NA。每个节点先选择自身最新的有效测试结果，聚合 last_test_time / last_test_model 取两者中较早的一次；详情保留脱敏 node_status 用于定位 partial。当前 server6 upstream key-group binding 精确关联时仍包含 account_rate_multiplier 原始有效倍率和 account_rate_multiplier_cny 展示倍率。
  • status：channel monitor 摘要。
  • sources：Pricing Monitor 已有的脱敏 source 余额与健康状态。
  • traffic.requests：仅 server6 的最新有界请求样本；每行带对应 account 的当前 account_rate_multiplier / account_rate_multiplier_cny，无法稳定关联时为 null。
  • traffic.errors：server6/server4 的有界逐条错误事件，保留节点、时间、key/account、结构化错误类别和状态链路，不做错误分组或 per-row count。
  • traffic.keys：仅 server6 按 Asia/Shanghai 自然日完整聚合的 key 使用量；事件样本上限不会截断其 request/token/cost totals，payload 同时携带统计日期和时区。

投影允许展示 account/key 名称、稳定 ID、model、instance 和运维状态，但不包含 API key 原文、access/refresh token、cookie、密码、数据库凭据或请求/响应正文。ID 始终按 字符串处理，避免 JavaScript 或 Python 客户端误损失大整数精度。

Interface

默认首页是紧凑 Dashboard。页面信息架构为：

Dashboard | Accounts | Sources | Requests | Errors

快捷键：

  • a：聚焦 Accounts，或从独立页面打开 Accounts。
  • p：打开 Sources。
  • k：在 Dashboard 聚焦 Key usage。
  • l：聚焦 Requests，或从独立页面打开 Requests。
  • e：聚焦 Errors，或从独立页面打开 Errors。
  • d：从独立页面返回 Dashboard。
  • /：聚焦当前页面 filter；Dashboard filter 同时作用于全部表。
  • r：重新读取 workspace snapshot。该操作不会要求服务端立即采集上游。

窄终端中的长 key、account 和 model 使用横向滚动，不截短原字段。独立页面可通过 以下参数启动：

shusub2 --accounts
shusub2 --sources     # --pricing 保留为兼容别名
shusub2 --requests    # --logs 保留为兼容别名
shusub2 --errors

加上 --once 可输出对应 snapshot 并退出：

shusub2 --once --requests

Accounts 只在 canonical 名称 {family}-quota-{source} 或 {family}-quotaonly-{source} 与唯一健康 source 精确匹配时显示 CNY 余额。不会根据 provider、URL、display name 或模糊文本推断；source 为 error/stale 时保留名称和状态， 但不伪造 CNY 数值。

Requests 展示 server6 的最新有界明细：key、account、当前 account multiplier、model、token bucket、actual cost、first-token latency、 duration 和 decode throughput。该 multiplier 来自当前 account binding，不代表请求发生时的历史计费倍率。Errors 展示 server6/server4 的逐条 instance、事件时间、status path、key、 account、model、phase/type/owner，不显示聚合次数。Key usage 和对应 Traffic Account usage 是 server6 完整当天 rollup；Errors 与 Requests 仍是事件样本。所有 workspace Traffic 都使用服务器声明的 Asia/Shanghai 自然日，不依赖客户端本地日期或滚动 24 小时窗口；每个 Traffic projection 显式携带日期、时区和 [00:00, 次日 00:00) 边界。

Legacy Direct

--legacy-direct 仅用于迁移对账和故障诊断。它恢复旧拓扑：

  • Accounts helper /api/tui/accounts
  • sub2api-status /api/status（历史接口，已归档下线；仅作为旧客户端参数的兼容说明）
  • Pricing Monitor view=accounts
  • Sub2API admin usage/key/error API
shusub2 --legacy-direct --accounts
shusub2 --legacy-direct --requests

显式传入空 --workspace-url '' 也会进入 legacy direct 模式。legacy Requests、Errors 和 Key usage 需要 Sub2API admin API key；默认 workspace 模式不会读取该凭据文件。legacy Key usage 也固定按 Asia/Shanghai 当日查询；legacy Errors 的 --errors-time-range 保留为与 上游诊断 API 对账的独立兼容参数，不能代表 workspace 的当天 Traffic 口径。

legacy token 仅允许放在 SHUSUB2_LOGS_TOKEN 或权限为 0600 的 ~/.config/shusub2/logs-token：

mkdir -p ~/.config/shusub2
chmod 700 ~/.config/shusub2
printf '%s\n' '<sub2api-admin-api-key>' > ~/.config/shusub2/logs-token
chmod 600 ~/.config/shusub2/logs-token

Configuration

Workspace-first 配置：

  • --workspace-url / SHUSUB2_WORKSPACE_URL / SHUSUB2_WORKSPACE_URL_FILE
  • --refresh-seconds / SUB2API_QUOTA_TUI_REFRESH_SECONDS
  • --timeout / SUB2API_QUOTA_TUI_TIMEOUT
  • --accounts / --sources / --requests / --errors
  • --once
  • --save-config
  • --install
  • --version-check-url / SHUSUB2_VERSION_CHECK_URL
  • --no-version-check / SHUSUB2_NO_VERSION_CHECK

Legacy-only 配置：

  • --legacy-direct
  • --api-url / SUB2API_QUOTA_TUI_API_URL
  • --status-url / SHUSUB2_STATUS_URL
  • --pricing-url / SHUSUB2_PRICING_URL
  • --logs-url / SHUSUB2_LOGS_URL
  • --logs-token / SHUSUB2_LOGS_TOKEN
  • --errors-cn-url / SHUSUB2_ERRORS_CN_URL
  • --errors-us-url / SHUSUB2_ERRORS_US_URL
  • --logs-limit、--errors-limit、--errors-time-range

URL config 文件默认位于 ~/.config/shusub2/。环境变量优先于 config 文件。

Local Development

cd apps/sub2api-quota-tui
uv run shusub2

运行完整测试和静态检查：

uv run python -m unittest discover -s tests -p 'test_*.py' -v
uv run python -m py_compile sub2api_quota_tui.py
uv lock --check

Maintenance Notes

Workspace adapter 只负责把 server projection 映射为现有渲染模型，不得在普通刷新中 重新引入 legacy HTTP 请求。当前 sub2api-status 与旧 Accounts helper 已归档下线，Pricing Monitor 受管模型中的 Workspace 输入已成对清空。由于含用户未提交 Rule Control 改动的 companion 不在本次部署范围， 远端 collector 暂保留旧环境并会显示 stale / partial；下一次安全的 selected deployment 或重启后，默认 shusub2 Workspace 入口将返回 503 workspace data unavailable。新增替代 projection 字段时应同时验证：字段 allowlist、字符串 ID、 finite number、payload 上限、单请求 cache、错误聚合次数和 legacy fallback。

cliproxy-codex-quota 可继续作为 Aggregation Hub 的过渡采集输入；sub2api-status 已归档下线， 不得再作为采集输入或双读对照。恢复 Workspace 前，必须先完成新的服务端 projection、server2 聚合字段 对账和 AstrBot view=alerts 连续性验证。

Tests And Release

发布遵循本仓库 client-tui-gitea-uv 流程：完成 scoped diff 审阅和测试后，将 apps/sub2api-quota-tui/ 同步到独立 Gitea 仓库，再通过 git source 执行 uv tool install --force。安装后检查 uv-receipt.toml，确保来源仍是 Gitea git URL， 而不是本地目录。

Secret Boundary

默认 workspace 模式不需要任何客户端 secret，也不读取 legacy token 文件。服务端 workspace 不聚合原始凭据或请求/响应正文。legacy direct 模式的 admin API key 仅保存在 本机用户配置或进程环境中，不得写入仓库、文档、日志或测试 fixture。

Reference in New Issue View Git Blame Copy Permalink
S
Description
Installable TUI for token-safe Sub2API account quota and daily usage
Readme MIT 1 MiB
Languages
Python 100%