token-proxy

多提供商 API Token 代理：认证网关 + key 轮询 + 请求日志，为 Claude Code 等 AI 客户端提供统一接入。

English

为什么需要它

Claude Code 连接自定义端点时只发送 Authorization: Bearer <token>，而部分上游（如 opencode go）只接受 x-api-key，且对 Claude Code 的 User-Agent 有风控。token-proxy 作为中间层，负责：

• 认证：多用户（用户名 + key），三种认证方式，开放给团队
• 认证头转换：Bearer → 上游要求的头（x-api-key 等）
• User-Agent 伪装：绕过上游对 AI 客户端 UA 的风控
• key 轮询：多个上游 key 按 round-robin 轮询，分摊配额
• 多上游：通过适配器支持 anthropic / openai 兼容端点，配置化新增
• 全量日志：每个请求的完整请求/响应详情入库，并统计 token 用量与费用

功能特性

• SQLite 管理：用户 / 后端 / key 池 / 路由 / 模型 / 别名 / 管理员全部入库，单一 token-proxy.<env>.db（WAL 模式，高性能）
• 热路径零 DB：认证 / 路由 / 后端 / 模型全部走内存快照，管理端改动 ~1s 内热加载生效，无需重启
• 用量与费用统计：从流式 / 非流式响应的 usage 字段解析 tokens，按模型单价计算费用
• 模型管理：模型目录、定价、别名（客户端名自动重写为真实模型名）、启停、按模型选后端
• Web 管理台（/admin）：仪表盘、用户、后端、路由、模型、请求日志、系统设置、操作审计、维护；全站国际化（英文为主，支持中文）
• 环境隔离：dev / test / prod 各自独立配置文件、端口、数据库，通过 .env 切换
• pm2 集群：生产默认 2 实例部署

架构

客户端 (Claude Code / codex / ...)
   │  认证: Bearer 用户名@后端:key（Basic / x-api-key 亦可）
   ▼
token-proxy (Fastify, 生产 :3501)
   │  ① 认证解析 {user, key, upstream}
   │  ② 按路由选适配器 (anthropic / openai / anthropic-to-openai)
   │  ③ 认证头转换 + UA 伪装 + key 轮询 + 模型解析
   ▼
上游 (opencode go / DeepSeek / OpenAI 兼容...)

数据：
  配置      config.<env>.json（项目根 / XDG 配置目录）
  数据库    token-proxy.<env>.db（WAL，用户/后端/路由/模型/日志）
  文本日志  logs/token-proxy.YYYY-MM-DD.log（按天）
  管理台    http://<host>:<port>/admin

快速开始

环境要求

• Node.js >= 24（推荐 volta install [email protected]）

安装与启动

方式一：CLI 全局安装（推荐，快速上手）

npm install -g token-proxy
token-proxy init          # 生成配置（仅此一次打印初始管理员密码）
token-proxy set-password  # 设置超级管理员密码（scrypt 哈希）
token-proxy start         # 后台启动服务
token-proxy logs          # 查看实时请求日志
token-proxy status        # 查看运行状态
token-proxy stop          # 停止服务

方式二：源码开发

npm install
npm run dev               # 开发热重载（端口 3502）
npm test                  # 全部测试

# 生产（pm2 集群，2 实例，端口 3501）
pm2 start ecosystem.config.cjs
pm2 logs token-proxy

环境隔离

运行环境来自 .env 的 TOKEN_PROXY_ENV（默认 dev），模板见 .env.example。各环境互不干扰：

| 环境 | 配置文件 | 数据库 | 默认端口 | |--------|--------------------|------------------------|---------| | prod | config.prod.json | token-proxy.prod.db | 3501 | | dev | config.dev.json | token-proxy.dev.db | 3502 | | test | config.test.json | token-proxy.test.db | 3503 |

配置文件位于项目根目录（源码模式）或 ~/.config/token-proxy/（CLI 全局模式）。首次启动会把旧版 config.json 中的 users/backends/routes 一次性迁移入库。

Claude Code 接入

export ANTHROPIC_BASE_URL="http://<host>:<port>/v1"
export ANTHROPIC_AUTH_TOKEN="用户名:你的APIKey"

Token 格式：用户名[@后端]:key —— 可选的 @后端 用于覆盖路由绑定的后端。

配置

config.json（或 config.<env>.json）只保留静态设置：

{
  "server": { "host": "0.0.0.0", "port": 3502, "apiPrefix": "/v1", "basePath": "" },
  "admin":  { "username": "admin", "passwordHash": "$scrypt$16384,8,1$..." },
  "security": { "sessionTtlHours": 168 },
  "auth":   { "methods": ["bearer", "basic", "apiKey"] },
  "logging": {
    "directory": "./logs",
    "retentionDays": 365,
    "detailRetentionDays": 30,
    "enableDetailDatabase": true,
    "enableTextLog": true
  },
  "database": { "path": "" }
}

其余一切——用户、后端、key 池、路由、模型、别名、管理员——均在 Web 管理台（/admin）管理，存入 SQLite，改动即生效。

Web 管理台

访问 http://<host>:<port>/admin，用 config.json 中的超级管理员账号登录。功能：

• 首页：欢迎页 + 系统概览 + 快速开始示例
• 仪表盘：请求量、成功率、延迟、Token 与费用趋势（7/30 天）、Top 用户、状态分布、最近请求
• 用户管理：创建/启停用户、重置 Key（仅显示一次）、配额设置、用量统计
• 后端管理：上游连接信息、key 池管理、连通性测试
• 路由管理：入口路径 → 协议适配器 → 后端
• 模型管理：模型目录、定价、别名、按模型选后端、启停
• 模型自动同步：每 12 小时自动同步 OpenCode Zen / Go 的模型目录（控制台也有一键同步），按后端分行存储，可获取官方定价
• 请求日志归档：过期日志以 gzip 归档而非删除（可下载 .db.gz / .db、支持按时间区间归档、仅超级管理员可下载），既留存历史又不撑大主库
• 请求日志：分页 + 多维过滤 + 请求/响应体详情
• 系统设置：认证方式、日志保留、详情存储、子管理员、操作审计、VACUUM

语言（English / 中文）可在侧栏切换，并记住浏览器偏好。

CLI

token-proxy start | stop | restart | status
token-proxy logs [N]
token-proxy stats
token-proxy init
token-proxy set-password
token-proxy migrate       # 导入旧版按天日志库
token-proxy backup        # SQLite 在线备份

开发

npm run dev        # 热重载（端口 3502）
npm run check      # 语法检查
npm test           # 全部测试（单元 + 集成）
npm run cli -- --help

目录结构：

src/
├── index.js               # 入口：Fastify 装配、转发、生命周期
├── config.js              # 配置热加载 + 校验（server/admin/security/logging/database）
├── env.js                 # 环境（.env）+ 各环境默认值
├── daemon.js              # 进程守护（pid 文件 + detached）
├── db/                    # SQLite：schema/迁移、记录、旧日志导入
├── store/                 # 内存快照 + 1s 轮询热加载
├── usage.js               # token 用量与费用解析
├── auth/                  # 入站认证（bearer / basic / x-api-key）
├── upstream/              # 路由、后端选择、适配器、协议转换
├── logger/                # 文本摘要 + SQLite 详情日志
└── admin/                 # Web 管理台：会话、REST API、静态 SPA（i18n）

安全

• 超级管理员密码以 scrypt 哈希 存入 config.json（绝不明文），用 token-proxy set-password 设置
• 缺少管理员凭据时拒绝启动，防止空密码可登录
• 上游 key 明文存本地 SQLite（文件权限 0600），UI 掩码显示；共享主机请谨慎
• 登录限速（连续 5 次失败锁定 5 分钟）+ 全操作审计
• 公网部署建议前置 nginx + HTTPS

许可证

MIT