# WorkBuddy Monitor

WorkBuddy Token 用量监控面板 + LLM API 调用 MITM 代理。

## 部署方式一览

| 方式 | 适用场景 | 难度 | 依赖 |
|------|----------|------|------|
| **① 独立 exe** | 其他 Windows 设备（无需环境） | ⭐ | 无 |
| **② Python 源码** | 有 Python 环境的任何设备 | ⭐⭐ | Python 3.9+ |
| **③ Docker** | 服务器 / Linux / macOS / Windows | ⭐⭐ | Docker |
| **④ Docker Compose** | 需要集群管理的设备 | ⭐⭐⭐ | Docker Compose |

---

## ① 独立 exe（Windows，最推荐）

> **无需安装 Python，一个 exe 直接运行。**

### 从本机打包

在已安装 Python 的开发机上运行：

```batch
cd wb_monitor
scripts\build_exe.bat
```

打包完成后得到：

- `artifacts\dist\web\wb-monitor-web.exe` — 完整面板（~15MB），包含 MITM 代理功能
- `artifacts\dist\proxy\wb-monitor-proxy.exe` — 仅 MITM 代理（可选）

### 部署到其他 Windows 设备

1. 将 `wb-monitor-web.exe` 复制到目标设备
2. **直接双击运行**（或命令行运行）
3. 浏览器访问 `http://127.0.0.1:5910`

> **注意**：exe 只包含监控面板本身。要查看数据，目标设备的 `C:\Users\<用户名>\.workbuddy\traces\` 下需要有 WorkBuddy 的 trace 文件。

### 命令行选项

```batch
wb-monitor-web.exe                       # 默认启动面板
wb-monitor-web.exe --proxy               # 同时启动 MITM 代理
wb-monitor-web.exe --port 8080           # 自定义端口
wb-monitor-web.exe --no-browser          # 不自动打开浏览器
wb-monitor-web.exe --help                # 查看全部选项
```

---

## ② Python 源码部署（跨平台）

> **任何安装了 Python 3.9+ 的设备均可使用。**

### 安装

```bash
# 克隆项目（或复制 wb_monitor 目录）
cd wb_monitor

# 安装依赖
pip install -r config\requirements.txt

# 启动
python run.py
```

### 可选：安装为系统命令

```bash
# 安装到 Python 的 site-packages
pip install .

# 启动（安装后全局可用）
wb-monitor
```

### 配合 MITM 代理

```bash
python run.py --proxy
```

然后在需要使用代理的应用中设置：
- **HTTPS 代理**: `http://127.0.0.1:5911`
- **首次使用**：将 `~/.workbuddy-monitor/proxy-ca/ca.crt` 安装为受信任根证书

---

## ③ Docker 部署（推荐服务器）

> **一键部署到任何支持 Docker 的设备（Linux / macOS / Windows）。**

### 构建并运行

```bash
cd wb_monitor

# 构建镜像
docker build -t wb-monitor -f docker\Dockerfile .

# 运行容器
docker run -d \
  --name wb-monitor \
  -p 5910:5910 \
  -v ~/.workbuddy/traces:/root/.workbuddy/traces:ro \
  -v wb-monitor-data:/root/.workbuddy-monitor \
  wb-monitor
```

挂载说明：
- `~/.workbuddy/traces` → 容器内读取 trace 数据（只读）
- `wb-monitor-data` 卷 → 持久化 SQLite 数据库

### 查看

```bash
# 查看日志
docker logs -f wb-monitor

# 停止
docker stop wb-monitor && docker rm wb-monitor

# 打开面板
open http://127.0.0.1:5910
```

---

## ④ Docker Compose 部署（推荐生产）

### 启动

```bash
cd wb_monitor

# 设置 trace 目录（可选，默认 ~/.workbuddy/traces）
export TRACES_DIR=/path/to/your/traces

# 启动
docker compose -f docker/docker-compose.yml up -d

# 查看日志
docker compose -f docker/docker-compose.yml logs -f

# 停止
docker compose -f docker/docker-compose.yml down
```

### 修改 docker-compose.yml

```yaml
services:
  monitor:
    # ... 默认配置 ...
    ports:
      - "5910:5910"
      - "5911:5911"   # 取消注释以暴露 MITM 代理端口
```

---

## 部署检查清单

- [ ] 目标设备能访问 WorkBuddy trace 文件（`~/.workbuddy/traces/`）
- [ ] 端口 5910（Web 面板）未被占用
- [ ] 如需 MITM 代理，端口 5911 也需可用
- [ ] 如需 MITM 代理，需安装 CA 证书到系统证书库

## 目录结构

```
wb_monitor/
├── run.py              # 统一入口（推荐使用）
├── monitor.py          # Web 面板主程序
├── llm_proxy.py        # MITM 代理模块
├── setup.py            # pip install 安装配置
│
├── config/             # 配置文件
│   ├── requirements.txt
│   └── .dockerignore
│
├── docker/             # Docker 部署
│   ├── Dockerfile
│   └── docker-compose.yml
│
├── scripts/            # 脚本工具
│   ├── start.bat       # Windows 启动脚本
│   └── build_exe.bat   # PyInstaller 打包
│
├── docs/
│   └── README.md       # 本文件
│
└── artifacts/          # 生成物 / 缓存
    ├── dist/
    ├── __pycache__/
    ├── monitor.log
    └── monitor_data.db
```
