222 lines
5.3 KiB
Markdown
222 lines
5.3 KiB
Markdown
# Token Usage Viewer
|
||
|
||
一个基于 **TanStack Start + Bun + Tauri** 的桌面应用，用于监控 Claude API 账户的 Token 配额使用情况。
|
||
|
||
采用 [OpenBridge Design System](https://github.com/oicl/openbridge-webcomponents) 设计规范，提供专业的航海仪表盘风格界面。
|
||
|
||
## 功能特点
|
||
|
||
- **实时配额监控**: 显示 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](https://bun.sh/) >= 1.0
|
||
- [Rust](https://www.rust-lang.org/) (Tauri 桌面应用需要)
|
||
|
||
### 安装与运行
|
||
|
||
```bash
|
||
# 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
|
||
```
|
||
|
||
### 构建
|
||
|
||
```bash
|
||
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` 配置：
|
||
|
||
1. **系统环境变量** (最高优先级)
|
||
2. **可执行文件同目录的 `.env` 文件**
|
||
3. **默认值**: `http://10.0.1.1:8318/usage`
|
||
|
||
#### 方式 1: 环境变量
|
||
|
||
```bash
|
||
# 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` 文件：
|
||
|
||
```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. 结束所有相关进程
|
||
|
||
```powershell
|
||
# 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
|
||
```
|
||
|
||
```bash
|
||
# Linux/macOS
|
||
pkill -f "app-desktop" || true
|
||
pkill -f "bun" || true
|
||
```
|
||
|
||
#### 2. 清除所有缓存
|
||
|
||
```bash
|
||
# 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 分钟)
|
||
|
||
```bash
|
||
# 清除 Rust 编译缓存
|
||
rm -rf src-tauri/target
|
||
```
|
||
|
||
#### 4. 确认端口已释放
|
||
|
||
```bash
|
||
# Windows
|
||
netstat -ano | findstr :3000
|
||
|
||
# Linux/macOS
|
||
lsof -i :3000
|
||
```
|
||
|
||
#### 5. 重新构建
|
||
|
||
```bash
|
||
bun run build
|
||
```
|
||
|
||
### 常见问题
|
||
|
||
#### "An unhandled error happened!" 错误
|
||
|
||
1. 确保没有其他进程占用端口 3000
|
||
2. 尝试完全清理缓存后重新构建
|
||
3. 检查 `.env` 文件中的 `TOKEN_USAGE_URL` 配置是否正确
|
||
|
||
#### 端口被占用 (EADDRINUSE)
|
||
|
||
```powershell
|
||
# 查找占用端口的进程
|
||
netstat -ano | findstr :3000
|
||
|
||
# 结束进程 (替换 PID 为实际进程 ID)
|
||
taskkill /F /PID <PID>
|
||
```
|
||
|
||
#### MSI 安装后无法运行
|
||
|
||
1. 卸载旧版本: 控制面板 → 程序和功能 → 卸载 app-desktop
|
||
2. 重新安装新的 MSI
|
||
3. 确保安装目录有写入权限
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
├── 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
|