ithtelab/workbuddy-manager · 上手攻略

  • 仓库：ithtelab/workbuddy-manager
  • 链接：https://github.com/ithtelab/workbuddy-manager
  • 分类：账号池管理 / OpenAI 兼容反代 / Web 控制台
  • 作者：spark
  • 更新：2026-09-16

是什么

workbuddy-manager 是一套给「腾讯 CodeBuddy 账号池」做 Web 可视化与运营的配套控制台。它不替代上游 workbuddy2api（Go 写的 OpenAI 兼容反代，负责账号轮询 / 并发调度 / 熔断 / 令牌刷新），而是在它前面再加一层"看得见、管得动"的面板：扫码批量纳管账号、自动签到、多密钥分发、IP 管控、调用日志、用量统计、Web UI 一站式完成。UI 设计对标 linux.do 社区 CDK 风格（卡片式、暗色、悬浮底栏、Q 弹气泡）。

仓库 Star ~79、周增 +63，处于 trending 状态（数据来自工作队列入榜快照）。MIT 协议，单进程单端口设计：FastAPI 同时托管 /api 管理接口、/v1 反代网关与 Next.js 静态导出的前端，不需 CORS。

解决什么问题

workbuddy2api 的能力完整但只有命令行：要加账号得跑 login.sh 脚本、看状态得 curl /status、发密钥没有界面，多账号运营、密钥分发、IP 风控、用量统计都缺。

workbuddy-manager 把这些运营环节补齐：

  1. 批量账号管理：微信 / QQ 扫码添加账号，成功后自动每日签到、写授权文件、热重载上游容器；账号列表按健康度 / 冷却 / 有效期实时展示。
  2. 多密钥分发：每把密钥独立设置限定版本（国内版 / 国际版）、有效期、最大 IP 数、IP 白名单、模型白名单、Token 配额；库中只存 SHA-256 哈希，明文仅创建时展示一次。
  3. 全量审计：每次调用记录密钥、IP、模型、状态码、首字延迟、总耗时、Token 消耗与实际扣费（取自上游 usage.credit）。
  4. 可视化设置：上游 config.json 不再手改 —— 签到 / 猫猫旅行 / 活跃上报 / 保活四类任务的整点数组（如 9, 21）、软限流冷却（600s / 2h）、单账号并发、熔断阈值、闲置补偿权重等全部可视化。
  5. 国内版 / 国际版切换：上游单实例双版本共存共账号池，页面右上角一键切换；账号、模型、测试台、任务记录、请求日志、用量统计全部按版本过滤；密钥也可限定版本（国内版密钥只能调国内版）。
  6. 聊天测试台：不建密钥直接试调模型，真实模型选择 + 思考强度（接 reasoning_effort，只列该模型支持的档位）+ 流式输出可中断，右下角实时显示本次消耗积分。仅管理员可用。
  7. 公网运营安全：管理端用户名密码登录（PBKDF2-SHA256 加盐）、签名 Cookie 鉴权（HMAC-SHA256）、同 IP 连续失败 5 次锁定 10 分钟、入站全局白/黑名单（支持 CIDR）、发布包强制验签。
  8. 网页内更新：管理端与上游（workbuddy2api）有更新时主动提醒，三种模式（全部更新 / 仅上游 / 仅管理端），更新器内置维护者公钥验签后解压。

快速安装

⚠️ 必须先有一个 workbuddy2api 实例（本地 :7863），workbuddy-manager 是它的前端面板。两者版本有对应关系，请按 Releases 与上游 README 的兼容矩阵选用。⚠️ 本攻略写作时点未在抓取内容中拿到显式最新版本号，请以 releases 列表顶部 tag 为准。

方式 A：源码本地跑

# 0) 可选：本机没有真实 workbuddy2api 时，起一个模拟上游
python dev/mock_upstream.py   # 监听 127.0.0.1:7863

# 1) 后端（终端 A）
python -m pip install -r server/requirements.txt
WB_ADMIN_PASSWORD=admin123 \
WB_DATA_DIR=./data \
WB_AUTH_DIR=/opt/workbuddy2api/auths \
WB2API_BASE=http://127.0.0.1:7863 \
python -m uvicorn server.main:app --reload --port 7864

# 2) 前端（终端 B）
cd web
npm install
npm run dev   # http://localhost:3000

首次启动自动生成 users.json 与随机签名密钥；未设 WB_ADMIN_PASSWORD 时日志会打印一次随机密码。

方式 B：Docker Compose

仓库自带 Dockerfile 与 docker-compose.yml，适合已经用 Docker 跑上游的用户：

git clone https://github.com/ithtelab/workbuddy-manager.git
cd workbuddy-manager
# 按需改 compose 里的 WB2API_BASE 与卷路径（默认假设上游在 ../workbuddy2api）
docker compose up -d --build
docker compose logs workbuddy-manager | grep -A2 密码   # 首启随机密码

预构建镜像同步推到 GHCR：

docker pull ghcr.io/ithtelab/workbuddy-manager:latest

镜像同时提供 linux/amd64 与 linux/arm64（Apple Silicon、ARM 云主机可直接拉取，无需 QEMU 模拟）。

⚠️ 代理坑

若本机装有 Clash / V2Ray 等代理软件（尤其是 TUN 模式），访问 127.0.0.1:7863 可能被劫持，表现为接口长时间无响应。本项目对内部请求默认 trust_env=False（不读系统代理）；TUN 模式下请在代理软件里把 127.0.0.1 加进直连 / 绕过列表。确需走代理时设 WB_HTTP_PROXY。

⚠️ docker.sock 取舍

容器版默认挂 /var/run/docker.sock 让管理端能重启 / 重建上游容器（"更新上游"、"保存设置后自动重载"、"读上游日志"）。挂它等于把宿主 root 权限交给本容器 —— 但这不是新增风险等级，宿主部署时本服务本来就是 root 运行（systemd 单元无 User=）。如果不能接受，把 docker 任务改为手动在宿主机执行即可。

核心用法

1. 添加账号

仪表盘 → 「添加账号」→ 选国内版 / 国际版 → 微信 / QQ 扫码 → 自动每日签到 + 写授权文件 + 重载上游容器。国际版会走地区注册与一次性 trial，积分仅一次性（无签到 / 猫猫旅行 / 开学季 / 夜猫，任务页会显式标注原因，不会显示成空白）。

2. 密钥分发（给下游用）

/v1 网关接受 OpenAI SDK 直连，Authorization 头用 Bearer wbk_xxx。每把密钥可独立设置：

  • 限定版本（国内版 / 国际版，互不串）
  • 有效期、最大 IP 数、IP 白名单
  • 模型白名单（如只允许 gpt-4o-mini）
  • Token 配额（按天 / 按总量）

模型别名映射：把 gpt-4o-mini 之类映射到实际模型，下游无感迁移。

3. 上游配置可视化

设置页 → 上游配置：

  • 定时任务：签到 / 猫猫旅行 / 活跃上报 / 保活四类各自独立开关 + 整点数组（输入即校验时刻 0-23 且去重排序）
  • 系统提示词：prompt.mode 在 passthrough（默认透传客户端 system） 与 custom（网关提示词替换客户端 system）之间切换；custom 模式还可指定自定义提示词文件 —— 依赖网关提示词稳定行为或想从源头消除模板句误报时改用
  • 限流与冷却：软限流冷却基数与退避上限（600s / 2h 这类时长，服务端二次兜底，非法值直接拒绝）
  • 并发与熔断：单账号并发、失败阈值、熔断冷却与封顶、闲置补偿权重、快过期积分窗口
  • 功能开关 / 会话粘性：出站指纹脱敏、会话绑定时长与清理周期

只提交改动项，不会误覆盖未展示的配置；冷门参数保留「高级设置」直接编辑；读取失败时锁定保存，杜绝空配置覆盖真实文件。

4. 请求日志与用量统计

  • 请求日志：按时间 / 密钥 / 状态 / 模型 / IP 筛选，含首字延迟（首字 = 从发起上游请求到收到第一个含正文的 delta，反映上游响应快慢）、总耗时（模型生成全程，回答越长越大）、Token 计量。非流式请求首字显示 —。
  • 用量统计：按天、按模型、按密钥多维统计 Token 消耗。

5. 模型中心

直连腾讯模型接口（比上游 /v1/models 字段更全：显示名、上下文、最大输出、推理档位、积分倍率、多模态 / 仅推理等能力标记），按系列分组，支持搜索、能力筛选、按积分倍率排序（挑省积分的模型时最实用）。取不到时回退上游清单并如实标注来源，不编造数据。

6. 自动任务与积分记录

底栏「任务」标签：签到记录、上游原始日志、自动任务与积分收益（猫猫旅行 +100、领养 Buddy +300 等）集中一处，30 秒自动刷新。已适配上游签到健壮性改造后的日志：今日已签到显示为正常（幂等成功），每轮签到有汇总行（共 4 个，成功 1，已签到 1，失败 1，跳过 1）。上游原始日志是英文，展示时已翻成中文（"领奖成功：第 12 次行程，获得 100 积分"），悬浮看英文原文。

7. 网页内更新

设置 → 系统更新 → 选模式（全部 / 仅上游 / 仅管理端）→ 实时进度与日志。账号授权、上游配置、密钥、日志数据全部保留；上游更新后自动重新施加端口收敛。发布包强制验签（维护者公钥内置），签名缺失 / 被篡改 / 不匹配都会拒绝安装；面板显示「已验签」标记。deploy/（验签逻辑本身）不随包自动替换。

8. 凭据清理（应急）

被入侵后跑 python3 deploy/purge_credentials.py：轮换会话密钥 + 清空遗留 api_keys + 吊销全部会话，写盘前自动备份。

典型适用场景

  1. 小团队 / 社区共用 CodeBuddy 账号池：避免单人多账号混乱，密钥按人分发 + IP 白名单 + 用量统计 + 审计全留痕。
  2. 公网运营 / 二级分发：把"账号池"打包成 OpenAI 兼容 API，对外卖 wbk_xxx 密钥赚积分差（注意腾讯 CodeBuddy 服务条款，不当使用有封号风险）。
  3. 个人多账号轮询：自己在多地多设备上跑 Codex / Claude Code，用 workbuddy-manager 统一签到 + 看积分。
  4. 教学 / 演示场景：自带 dev/mock_upstream.py 模拟上游，零真实账号也能跑完整界面。
  5. 运维监控：仪表盘看 14 天调用趋势、账号健康度、积分余额浮动（每 45 秒采集上游日志翻译落库，旅行领奖 +100 这种上游只打容器日志的活动也能长期留痕）。

坑与注意

  • ⚠️ 依赖上游 workbuddy2api：本仓库只是面板，账号调度、令牌刷新、限流熔断都在 :7863 那边的 Go 进程；面板出问题不会断上游，但上游挂了面板也只能看历史。
  • ⚠️ 国际版能力边界：无签到 / 猫猫旅行 / 开学季 / 夜猫，积分仅一次性 trial；保活与活跃上报照常。
  • ⚠️ 积分查询直连腾讯：上游 /status 积分滞后可达数小时；面板每 45 秒直查腾讯接口，因此面板数字是「实时」（或缓存 N 秒前），上游那边是历史值。两者不一致是正常的。
  • ⚠️ TUN 模式代理坑：见上文快速安装。
  • ⚠️ docker.sock = 宿主机 root：见上文。
  • ⚠️ 管理端 vs 网关密钥分离：网关的 API 密钥（wbk_xxx）不能用于登录管理端 —— 密钥只授权 /v1 的模型调用，与后台权限彻底分离。改密码 / 改角色 / 删用户会立即吊销该用户的全部登录态（其他用户不受影响）。
  • ⚠️ 手机端 UI 自适应：任务记录页在手机整合为单卡片，顶部分段切换「签到记录 / 自动任务 / 原始日志」；账号列表与任务记录在窄屏自动改为纵向卡片。
  • ⚠️ 完整安装步骤、模型中心可用模型来源解释、签名密钥生成细节见 docs/（仓库自述较细，未在 README 一一展开）；本攻略仅覆盖 README 抓取到的能力面。
  • ⚠️ 合规与封号风险：腾讯 CodeBuddy 是面向个人开发者的服务，把账号池当 CDN 二次售卖违反其服务条款，README 与上游文档均未对本面板适用边界给出明文声明。本仓库与 workbuddy2api 上游的运营能力（多密钥分发、IP 白名单、用量统计、积分查询）在能力面上与"账号池 CDN 化"重合 —— 使用前自行评估合规边界，作者免责。

与同类对比

  • one-api / new-api：通用 OpenAI 兼容聚合 + 计费平台（Go），不绑特定上游。workbuddy-manager 是"workbuddy2api 专用垂直面板"，深度集成：扫码加号、积分实时查询、版本切换、任务翻译、验签更新 —— 通用聚合平台做不来这些。
  • OpenAI-Sidebar / ChatGPT-Next-Web：纯前端客户端，不管理后端账号。workbuddy-manager 是后端运营面板，前端用 Next.js 只是为了有 UI。
  • linux.do CDK 主题面板：UI 设计对标 linux.do 社区的 CDK 风格，但功能完全不同（CDK 是 key 兑换，本面板是账号池运营）。
  • 青龙面板 / NodeSeek 签到：通用定时任务 + 签到，workbuddy-manager 把签到嵌入到完整的 OpenAI 网关 + 账号池上下文中，不是孤立的 cron。

一句话推荐结论

如果你正在运营多个腾讯 CodeBuddy 账号并希望它们稳定地、可见地、可控地服务一群下游，workbuddy-manager 是当前唯一深度配套 workbuddy2api 的中文面板；如果只是自己用一两个账号，CLI + 几个 cron 脚本就够了，不必上这套。