shujakuin/shusub2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
81e9ce1530af56528260a7640d00f9df7e629cf8
shusub2/README.md
T

13 KiB
Raw Blame History

shusub2

  • 文档层级：客户端工具
  • 应用性质：客户端 TUI
  • 源码来源：repo 原生
  • 运行关系：客户端工具
  • 部署模型：无
  • 对应服务：无
  • 对应 stack：无
  • Secret 边界：本地用户配置
  • 分发方式：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。

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.

Quick Start

Run once from a public Git repo with uvx:

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:

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:

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

Configure the default public API URL for shusub2:

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:

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:

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:

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.

Errors Page

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.

The page pulls the latest admin ops error logs from both cn and us in parallel, then merges them by created_at:

  • cn default: https://sub2apicn.shujk.top/api/v1/admin/ops/errors
  • us default: https://us.sub2.shujk.top/api/v1/admin/ops/errors

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:

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.

Local Development

cd apps/sub2api-quota-tui
uv run shusub2

Run inside zellij:

zellij action new-pane --name sub2api-quota -- \
  bash -lc 'cd /home/shujakuin/infra/apps/sub2api-quota-tui && uv run shusub2'

Configuration:

  • --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

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.

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.

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.

The dedicated Accounts page keeps the full columns for scanning inside zellij:

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 -.

Reference in New Issue View Git Blame Copy Permalink