shujakuin/shusub2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add cached pricing workspace

Browse Source
This commit is contained in:
yunyaozhou
2026-08-04 00:16:34 +08:00
parent 81e9ce1530
commit 311236d28f
5 changed files with 1156 additions and 376 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+159 -237
View File
@@ -8,190 +8,175 @@
- 对应服务：无
- 对应 stack：无
- Secret 边界：本地用户配置
- 分发方式：`uvx` / `uv tool install`。
- 目标 API：Pricing Monitor `GET /api/ui-data?view=workspace`
- 分发方式：`uvx` / `uv tool install`
- 包名：`shusub2`
- 命令名：`shusub2`
- 本地状态路径：`~/.config/shusub2/`
- 目标 API：`cliproxy-codex-quota` 的 `/api/tui/accounts`、可选 `sub2api-status` `/api/status`、可选 Pricing Monitor `/api/ui-data?view=accounts`，以及可选 Sub2API `/api/v1/admin/usage` 和 `/api/v1/admin/ops/errors`。
- 备注：账号数据无 secret，不需要 SSH、数据库访问、API key、OAuth credentials 或 plaintext env；请求与错误日志可选持有 Sub2API admin API key，仅存本机 `~/.config/shusub2/logs-token`（0600）或 `SHUSUB2_LOGS_TOKEN`。
- 默认数据源：Pricing Monitor `GET /api/ui-data?view=workspace`
Single-page terminal dashboard for the token-safe Sub2API account feed,
request logs, and merged cn/us error logs. Dedicated full-table views remain
available for each data set.
`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 共用同一份进程内缓存。后台 snapshot
读取之外，默认启动仍会进行一次短超时的 Gitea 版本检查；使用
`--no-version-check` 或 `SHUSUB2_NO_VERSION_CHECK=1` 可关闭它。
## Quick Start
Run once from a public Git repo with `uvx`:
已安装时直接运行：
```bash
uvx --from git+https://gitea.shujk.top/shujakuin/shusub2.git shusub2 \
--api-url https://codex.server2.shujk.top/1232131231313123/api/tui/accounts
```
Bootstrap a new machine from `uvx`: save the API URL, install `shusub2` as a
user command, then run it later as `shusub2`:
```bash
uvx --from git+https://gitea.shujk.top/shujakuin/shusub2.git shusub2 \
--api-url https://codex.server2.shujk.top/1232131231313123/api/tui/accounts \
--install
shusub2
```
Install as a user command:
默认 workspace URL 是 Tailscale HTTPS 入口：
```text
https://price.tailbeb9ad.ts.net/api/ui-data?view=workspace
```
覆盖并保存 workspace URL：
```bash
shusub2 \
--workspace-url https://price.tailbeb9ad.ts.net/api/ui-data?view=workspace \
--save-config
```
从 Gitea 安装为用户命令：
```bash
uv tool install git+https://gitea.shujk.top/shujakuin/shusub2.git
shusub2 --api-url https://codex.server2.shujk.top/1232131231313123/api/tui/accounts --save-config
shusub2
```
Configure the default public API URL for `shusub2`:
也可以一次性运行：
```bash
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`：账号摘要、quota window、当日用量和 provider/group/status 字段。
- `status`：channel monitor 摘要。
- `sources`：Pricing Monitor 已有的脱敏 source 余额与健康状态。
- `traffic.requests`：最近的有界请求样本。
- `traffic.errors`：有界错误聚合，保留聚合次数和状态链路。
- `traffic.keys`：24 小时 key 使用聚合。
投影允许展示 account/key 名称、稳定 ID、model、instance 和运维状态，但不包含 API
key 原文、access/refresh token、cookie、密码、数据库凭据或请求/响应正文。ID 始终按
字符串处理，避免 JavaScript 或 Python 客户端误损失大整数精度。
## Interface
默认首页是紧凑 Dashboard。页面信息架构为：
```text
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 使用横向滚动，不截短原字段。独立页面可通过
以下参数启动：
```bash
shusub2 --accounts
shusub2 --sources # --pricing 保留为兼容别名
shusub2 --requests # --logs 保留为兼容别名
shusub2 --errors
```
加上 `--once` 可输出对应 snapshot 并退出：
```bash
shusub2 --once --requests
```
Accounts 只在 canonical 名称 `{family}-quota-{source}` 或
`{family}-quotaonly-{source}` 与唯一健康 source 精确匹配时显示 CNY 余额。不会根据
provider、URL、display name 或模糊文本推断；source 为 error/stale 时保留名称和状态，
但不伪造 CNY 数值。
Requests 展示 key、account、model、token bucket、actual cost、first-token latency、
duration 和 decode throughput。Errors 展示 instance、聚合次数、status path、key、
account、model、phase/type/owner 和时间。Key usage 使用 workspace 的 24 小时窗口，
不再宣称是客户端本地“今日”查询。
## Legacy Direct
`--legacy-direct` 仅用于迁移对账和故障诊断。它恢复旧拓扑：
- Accounts helper `/api/tui/accounts`
- `sub2api-status` `/api/status`
- Pricing Monitor `view=accounts`
- Sub2API admin usage/key/error API
```bash
shusub2 --legacy-direct --accounts
shusub2 --legacy-direct --requests
```
显式传入空 `--workspace-url ''` 也会进入 legacy direct 模式。legacy Requests、Errors
和 Key usage 需要 Sub2API admin API key；默认 workspace 模式不会读取该凭据文件。
legacy token 仅允许放在 `SHUSUB2_LOGS_TOKEN` 或权限为 `0600` 的
`~/.config/shusub2/logs-token`：
```bash
mkdir -p ~/.config/shusub2
chmod 700 ~/.config/shusub2
printf '%s\n' 'https://codex.server2.shujk.top/1232131231313123/api/tui/accounts' > ~/.config/shusub2/api-url
chmod 600 ~/.config/shusub2/api-url
shusub2
```
Environment variables override the config file:
- `SHUSUB2_API_URL`
- `SUB2API_QUOTA_TUI_API_URL`
- `SHUSUB2_API_URL_FILE`
- `SHUSUB2_STATUS_URL`
- `SHUSUB2_STATUS_URL_FILE`
- `SHUSUB2_PRICING_URL`
- `SHUSUB2_PRICING_URL_FILE`
- `SHUSUB2_LOGS_URL`
- `SHUSUB2_LOGS_URL_FILE`
- `SHUSUB2_LOGS_TOKEN`
- `SHUSUB2_LOGS_TOKEN_FILE`
- `SHUSUB2_LOGS_REFRESH_SECONDS`
- `SHUSUB2_LOGS_LIMIT`
- `SHUSUB2_ERRORS_CN_URL`
- `SHUSUB2_ERRORS_CN_URL_FILE`
- `SHUSUB2_ERRORS_US_URL`
- `SHUSUB2_ERRORS_US_URL_FILE`
- `SHUSUB2_ERRORS_REFRESH_SECONDS`
- `SHUSUB2_ERRORS_LIMIT`
- `SHUSUB2_ERRORS_TIME_RANGE`
- `SHUSUB2_VERSION_CHECK_URL`
- `SHUSUB2_VERSION_CHECK_TIMEOUT`
- `SHUSUB2_NO_VERSION_CHECK`
## Unified Dashboard
`shusub2` opens a compact dashboard for Accounts, Keys, Logs, and Errors. Its
summary also reports Pricing Monitor upstream health and CNY total. The
Accounts table attaches a source balance only when an account has a canonical
quota-source name and the sanitized Pricing Monitor projection has one
unambiguous matching source. Press `a`, `k`, `l`, or `e` to focus a dashboard
table; press `p` to open the full Upstreams source-balance page. `/` filters
the active table and `r` refreshes all data immediately. Automatic Accounts
and Upstreams, Keys/Logs, and Errors refresh defaults to every five minutes. The client requests
gzip-compressed JSON and transparently decodes it when the upstream supports it.
The two-line detail area follows the selected row. Accounts, Keys, Logs, and
Errors use green, yellow, magenta, and red section styling respectively.
The dashboard sizes every column from the fetched content so wide terminals show
complete keys, accounts, and models. On a narrow terminal, a table scrolls
horizontally instead of truncating a field:
```text
ACCOUNT | Group | Source | Src CNY | Src state | Today | Daily | 5h | 7d | Avail
UPSTREAMS (p) | Source | Kind | Balance | CNY | Unit | Status | Updated | Age
KEY | Today | Tokens | Req
LOG KEY | Account | Model | First | Duration | Tok/s | Input | Output | Cache | Tokens | Cost | Time | Age
ERR | Status | Key | Account | Model | Time | Age
```
The Keys table shows today's usage sorted by actual cost, including key name,
tokens, and request count. It uses the same admin API key as Logs and Errors;
without that token the table is hidden and the summary remains compact.
Use `--accounts`, `--pricing`, `--logs`, or `--errors` to start a dedicated
full-table view. The corresponding `--once` form still prints only that data set.
## Request Logs Page
The middle dashboard table shows request logs, and `l` focuses it.
`shusub2 --logs` starts the dedicated logs page, while
`shusub2 --once --logs` prints one logs snapshot to stdout.
The logs page reads the latest requests (default 100, `--logs-limit`) from the
Sub2API admin usage API and refreshes every five minutes by default
(`--logs-refresh-seconds` / `SHUSUB2_LOGS_REFRESH_SECONDS`). Columns:
```text
Key | Account | Model | Effort | Type | Input | Output | Cache | Tokens | Cost | First | Duration | Tok/s | Time | Age
```
`Type` is the Sub2API `request_type` (`sync` / `stream` / `ws_v2` / `cyber`).
`Tokens` is input + output + cache write + cache read; the detail line below
the table shows the per-bucket breakdown, actual cost, first-token latency,
decode speed, upstream model mapping, user, and request id.
`Effort` is the request's `reasoning_effort` (`-` when absent). `First` is the
first-token latency and `Duration` the total request time, both shown in
seconds. `Tok/s` is the decode throughput computed as
`output_tokens / (duration - first_token)`; it shows `-` when there is no
output or no positive decode window. `Input`, `Output`, and `Cache` are token
buckets; `Cache` combines cache write and cache read. `Tokens` is their total.
`Age` is relative to local current time (`now`, `5m ago`, `2h ago`, etc.). In the TUI each
API key name is rendered in a stable per-key color so rows from the same
key are easy to group visually (`--once --logs` output stays plain text).
The logs URL defaults to `https://sub2apicn.shujk.top/api/v1/admin/usage` and
can be overridden with `--logs-url` / `SHUSUB2_LOGS_URL` /
`~/.config/shusub2/logs-url`.
The page needs a Sub2API **admin API key** (generated in the Sub2API web UI
under Settings). Configure it once:
```bash
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
```
or via `SHUSUB2_LOGS_TOKEN`. The key is sent as the `x-api-key` header and is
never written anywhere else by the client. Without a token the dashboard Logs
and Errors tables stay empty and show a configuration hint; the Accounts table
keeps working without any secret.
## Configuration
## Errors Page
Workspace-first 配置：
The bottom dashboard table shows merged errors, and `e` focuses it.
`shusub2 --errors` starts the dedicated errors page, while
`shusub2 --once --errors` prints one merged snapshot to stdout.
- `--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`
The page pulls the latest admin ops error logs from **both** cn and us in
parallel, then merges them by `created_at`:
Legacy-only 配置：
- cn default: `https://sub2apicn.shujk.top/api/v1/admin/ops/errors`
- us default: `https://us.sub2.shujk.top/api/v1/admin/ops/errors`
- `--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`
`us.sub2.shujk.top` is the DNS-only standard HTTPS direct entry for the same
server4 backend. It avoids the Cloudflare 1010 behavior sometimes returned by
`sub2apius.shujk.top` to non-browser clients while avoiding the fixed `:19857`
port in the default client configuration. Use `--errors-us-url` to select a
different direct origin when required.
The dashboard and dedicated errors page refresh every five minutes by default
(`--errors-refresh-seconds` / `SHUSUB2_ERRORS_REFRESH_SECONDS`). Query window
defaults to `24h` (`--errors-time-range` / `SHUSUB2_ERRORS_TIME_RANGE`); each source uses
`page=1` and `page_size` from `--errors-limit` (default 100, max 500).
Columns:
```text
Node | Status | Key | Account | Model | Phase | Type | Owner | Time | Age
```
`Age` is relative to local current time (`now`, `5m ago`, `2h ago`, etc.).
Auth reuses the same admin API key as the logs page.
URL config 文件默认位于 `~/.config/shusub2/`。环境变量优先于 config 文件。
## Local Development
@@ -200,96 +185,33 @@ cd apps/sub2api-quota-tui
uv run shusub2
```
Run inside zellij:
运行完整测试和静态检查：
```bash
zellij action new-pane --name sub2api-quota -- \
bash -lc 'cd /home/shujakuin/infra/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
```
Configuration:
## Maintenance Notes
- `--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`
- `--logs-refresh-seconds` / `SHUSUB2_LOGS_REFRESH_SECONDS`
- `--logs-limit` / `SHUSUB2_LOGS_LIMIT`
- `--errors-refresh-seconds` / `SHUSUB2_ERRORS_REFRESH_SECONDS`
- `--errors-limit` / `SHUSUB2_ERRORS_LIMIT`
- `--errors-time-range` / `SHUSUB2_ERRORS_TIME_RANGE`
- `--accounts` / `--pricing` / `--logs` / `--errors`
- `--save-config`
- `--install`
- `--refresh-seconds` / `SUB2API_QUOTA_TUI_REFRESH_SECONDS`
- `--timeout` / `SUB2API_QUOTA_TUI_TIMEOUT`
Workspace adapter 只负责把 server projection 映射为现有渲染模型，不得在普通刷新中
重新引入 legacy HTTP 请求。新增 projection 字段时应同时验证：字段 allowlist、字符串 ID、
finite number、payload 上限、单请求 cache、错误聚合次数和 legacy fallback。
The dashboard reads `/api/tui/accounts`, can optionally read `sub2api-status`
`/api/status` for channel monitor health, and reads Pricing Monitor's
`/api/ui-data?view=accounts` for upstream source balances. The default pricing URL
is the Tailscale HTTPS service; `--pricing-url`, `SHUSUB2_PRICING_URL`, or
`~/.config/shusub2/pricing-url` can override it. This is a cached, read-only
projection collected by Pricing Monitor on its own cadence: `shusub2` neither
contacts upstream providers directly nor asks Pricing Monitor to refresh. The Accounts table does not need SSH,
database access, API keys, OAuth credentials, or plaintext env files. The Keys,
Logs, and Errors tables authenticate to the Sub2API admin APIs with
an admin API key stored only in `~/.config/shusub2/logs-token` (0600) or
`SHUSUB2_LOGS_TOKEN`.
`cliproxy-codex-quota` 与 `sub2api-status` 当前仍可作为 Aggregation Hub 的过渡采集输入和
双读对照，但不再是默认 TUI 客户端直连依赖。移除这些过渡输入前，必须先完成 server2
聚合字段对账和 AstrBot `view=alerts` 连续性验证。
When `--status-url` is omitted, `shusub2` infers a sibling `/api/status` URL
from account URLs ending in `/api/tui/accounts`, so the public Codex endpoint
automatically enables monitor availability. On startup it also checks the
public Gitea repo for a newer package version and prints a short upgrade hint
when one is available.
## Tests And Release
On the dedicated `--accounts` page, a per-key panel shows today's usage for
each API key (`Key | Today | Tokens | Req`, sorted by cost, key names in the
same per-key colors as the logs page). It combines the Sub2API admin
`dashboard/api-keys-trend` and `dashboard/api-keys-usage` endpoints and
needs the same admin API key as the logs page; without a token the panel
stays empty and the status line shows a hint. `--once` prints the same
panel after the accounts table when a token is configured.
发布遵循本仓库 `client-tui-gitea-uv` 流程：完成 scoped diff 审阅和测试后，将
`apps/sub2api-quota-tui/` 同步到独立 Gitea 仓库，再通过 git source 执行
`uv tool install --force`。安装后检查 `uv-receipt.toml`，确保来源仍是 Gitea git URL，
而不是本地目录。
The dedicated Accounts page keeps the full columns for scanning inside zellij:
## Secret Boundary
```text
Name | Provider | Group | Source | Src CNY | Src state | Daily | Today | Tokens | Req | Kind | 5h | 7d | Reset | Status | Availability
```
`Provider` distinguishes `openai` and `anthropic` accounts from the public
`platform` field returned by the API.
`Daily` is shown as `used/limit` when Sub2API has `quota_daily_*` fields in
`accounts.extra`; otherwise it is `-`.
`5h` / `7d` are only the account feed's used/remaining quota percentages. They
are not upstream provider balances and therefore never claim to be a cash or
source-account balance.
`Source`, `Src CNY`, and `Src state` use Pricing Monitor's cached, sanitized
`view=accounts` projection. A balance is attached only for exact canonical
account names of the form `{family}-quota-{source}` or
`{family}-quotaonly-{source}`, where `{source}` is one or more lowercase
alphanumeric segments joined by single hyphens, and a single normalized source
name. Provider, URL, display-name, and fuzzy matching are deliberately not used. Accounts
without a unique mapping show `-`; an `error` or `stale` source retains its
source/state label but does not show a CNY amount.
The dedicated `--pricing` page shows Pricing Monitor source rows such as
`code-plan`, `codexapis`, `testvideo`, `kedaya`, `ycy`, and `mdkj`: raw available
balance with its source unit, derived CNY when supplied, health state, and last
successful collection time. It reads only the existing sanitized source projection.
`Group` is the derived Sub2API tier alias group. Higher tiers win when multiple
aliases exist: `id < slow < fast < sfast`. The table shows `sfast` first, then
`fast`, `slow`, `id`, and ungrouped accounts.
When `--status-url` is configured, the status line shows channel monitor
health, and the selected account detail shows the matching monitor status when
one exists. Monitor binding first uses the shared `base_url_hash` emitted by
the account API and `sub2api-status`; name-token matching remains only as a
fallback for older status payloads.
`Availability` is derived from the bound channel monitor. Accounts without a
matching monitor show `-`.
默认 workspace 模式不需要任何客户端 secret，也不读取 legacy token 文件。服务端
workspace 不聚合原始凭据或请求/响应正文。legacy direct 模式的 admin API key 仅保存在
本机用户配置或进程环境中，不得写入仓库、文档、日志或测试 fixture。