mdy/openbridge-token-usage-viewer

Fork 0

Files

MAO Dongyang a77fcdd3dc 🏁 Final commit: Project Token Usage Viewer completed

2026-01-21 14:21:43 +08:00

5.3 KiB

Raw Permalink Blame History

Token Usage Viewer

一个基于 TanStack Start + Bun + Tauri 的桌面应用，用于监控 Claude API 账户的 Token 配额使用情况。

采用 OpenBridge Design System 设计规范，提供专业的航海仪表盘风格界面。

功能特点

实时配额监控: 显示 4 个账户的 Claude Opus 4.5 (Thinking) 模型配额使用情况
可视化仪表盘: Apple Health 风格的圆环进度指示器
智能告警系统:
- 当配额剩余 < 20% 时显示警告 (Warning)
- 当配额剩余 < 5% 时显示紧急告警 (Alarm)
主题切换: 支持白天/夜间模式切换
自动刷新: 配额数据每 5 分钟自动刷新
倒计时显示: 显示配额重置剩余时间

技术栈

层级	技术
前端框架	React 19 + TanStack Router
UI 组件	OpenBridge Web Components
状态管理	TanStack Query
样式	Tailwind CSS v4
RPC 通信	ORPC (类型安全)
桌面壳	Tauri v2
运行时	Bun
构建	Vite + Turbo

快速开始

前置要求

Bun >= 1.0
Rust (Tauri 桌面应用需要)

安装与运行

# 1. 克隆项目
git clone <your-repo-url>
cd openbridge-token-usage-viewer

# 2. 安装依赖
bun install

# 3. 启动开发服务器
bun run dev:vite    # 仅 Web (http://localhost:3000)
bun run dev         # Tauri 桌面应用 + Web

构建

bun run build:vite   # 构建 Web 版本
bun run build        # 构建 Tauri 桌面安装包

构建产物位置：

MSI 安装包: src-tauri/target/release/bundle/msi/app-desktop_0.1.0_x64_en-US.msi
NSIS 安装包: src-tauri/target/release/bundle/nsis/app-desktop_0.1.0_x64-setup.exe

配置

环境变量

应用会按以下优先级读取 TOKEN_USAGE_URL 配置：

系统环境变量 (最高优先级)
可执行文件同目录的 .env 文件
默认值: http://10.0.1.1:8318/usage

方式 1: 环境变量

# Windows PowerShell
$env:TOKEN_USAGE_URL = "http://your-server:8318/usage"
.\app-desktop.exe

# Linux/macOS
TOKEN_USAGE_URL=http://your-server:8318/usage ./app-desktop

方式 2: 配置文件

在可执行文件同目录创建 .env 文件：

TOKEN_USAGE_URL=http://your-server:8318/usage

常用命令

命令	说明
`bun dev`	启动 Tauri + Vite 开发服务器
`bun dev:vite`	仅启动 Vite 开发服务器
`bun dev:tauri`	仅启动 Tauri (需先启动 Vite)
`bun build`	完整构建 (Tauri 桌面应用)
`bun build:vite`	仅构建 Web 版本
`bun typecheck`	TypeScript 类型检查
`bun fix`	自动修复格式和 Lint 问题

故障排除

清理缓存与重置

如果遇到构建问题、端口占用或缓存问题，按以下步骤重置：

1. 结束所有相关进程

# Windows PowerShell (管理员)
taskkill /F /IM "app.exe" 2>$null
taskkill /F /IM "app-desktop.exe" 2>$null
taskkill /F /IM "bun.exe" 2>$null
taskkill /F /IM "node.exe" 2>$null

# Linux/macOS
pkill -f "app-desktop" || true
pkill -f "bun" || true

2. 清除所有缓存

# Turbo 缓存
rm -rf .turbo

# Vite 缓存
rm -rf node_modules/.vite
rm -rf node_modules/.cache

# 构建输出
rm -rf .output

# Tauri sidecar binaries
rm -rf src-tauri/binaries/app-*

3. 完全清理 (可选，需要重新编译 Rust，耗时 2-5 分钟)

# 清除 Rust 编译缓存
rm -rf src-tauri/target

4. 确认端口已释放

# Windows
netstat -ano | findstr :3000

# Linux/macOS
lsof -i :3000

5. 重新构建

bun run build

常见问题

"An unhandled error happened!" 错误

确保没有其他进程占用端口 3000
尝试完全清理缓存后重新构建
检查 .env 文件中的 TOKEN_USAGE_URL 配置是否正确

端口被占用 (EADDRINUSE)

# 查找占用端口的进程
netstat -ano | findstr :3000

# 结束进程 (替换 PID 为实际进程 ID)
taskkill /F /PID <PID>

MSI 安装后无法运行

卸载旧版本: 控制面板 → 程序和功能 → 卸载 app-desktop
重新安装新的 MSI
确保安装目录有写入权限

项目结构

├── src/
│   ├── components/
│   │   ├── HealthRing.tsx      # 圆环进度指示器
│   │   ├── TokenUsageDashboard.tsx  # 主仪表盘
│   │   └── ...
│   ├── hooks/
│   │   └── useTheme.ts         # 主题切换 Hook
│   ├── orpc/
│   │   ├── contracts/usage.ts  # API 契约
│   │   └── handlers/usage.ts   # 数据获取逻辑
│   ├── routes/
│   │   ├── __root.tsx          # 根布局
│   │   └── index.tsx           # 首页
│   └── env.ts                  # 环境变量配置
│
├── src-tauri/                  # Tauri 桌面应用
│   ├── src/
│   │   ├── lib.rs              # Tauri 入口
│   │   └── sidecar.rs          # Sidecar 管理
│   ├── binaries/               # 编译后的 sidecar
│   └── tauri.conf.json         # Tauri 配置
│
└── .output/                    # Vite 构建输出

许可证

MIT

5.3 KiB Raw Permalink Blame History Unescape Escape