CodexRouter

AI API 路由中继 —— 协议转换、指纹伪装、代理池、Vue 管理控制台，一条命令启动/停止/重启。

CodexRouter 是一个轻量级 AI API 路由网关，坐在 AI 编码工具（OpenCode、Codex CLI 等）与上游 API 网关（sub2api、new-api 等）之间，负责协议转换和客户端指纹伪装，让上游 codex_cli_only 校验通过。

特性

• 协议转换：Chat Completions / Responses / Messages 三种格式自动互转
• 指纹伪装：TLS JA3 指纹 + User-Agent 伪装为 codex_cli
• 代理池：HTTP/HTTPS/SOCKS5 代理池，每个上游可绑定独立出口 IP
• 分组路由：按顺序 / 轮询 / 加权策略，支持粘性会话
• 鉴权 Key：自动生成 sk-cr-* 密钥，绑定分组、速率限制
• 管理控制台：Vue 3 + Element Plus 单页应用，仪表盘 / 上游 / 分组 / 密钥 / 代理 / 记录 / 备份
• 单二进制部署：前端 SPA 通过 embed.FS 编译进 Go 二进制
• 终端生命周期管理：coderouter start/stop/restart/status/logs

安装

方式一：npm 全局安装（推荐）

npm install -g coderouter

安装后 coderouter 命令即可全局使用。postinstall 脚本会尝试：

1. 使用已捆绑的二进制（vendor/coderouter）
2. 从 CODEROUTER_BIN 环境变量复制
3. 若系统已装 Go，则从源码编译

方式二：从源码构建

git clone <repo-url> coderouter
cd coderouter

# 构建前端 SPA
cd frontend && npm install && npm run build && cd ..

# 构建 Go 二进制（CGO_ENABLED=0 生成静态二进制）
CGO_ENABLED=0 go build -o coderouter ./cmd/coderouter

# （可选）链接为全局命令
cd npm/coderouter && npm link

快速开始

1. 创建配置文件

cat > config.yaml << 'EOF'
server:
  host: "0.0.0.0"
  port: 8443
  api_key: "sk-coderouter-dev"
cloak:
  codex_version: "0.142.5"
  tls_fingerprint_enabled: true
cache:
  enabled: true
  max_size: 1000
  ttl: 5m
storage:
  enabled: true
  path: "data/coderouter.db"
admin:
  enabled: true
  path: "/admin"
  token: ""        # 留空则 /api/v1/ 无鉴权（仅建议本地开发）
  db_path: "coderouter.db"
EOF

2. 启动服务

# 后台启动（守护进程）
coderouter start --config config.yaml

# 或前台运行（日志直接输出到终端）
coderouter serve --config config.yaml

3. 访问管理面板

浏览器打开 http://127.0.0.1:8443/admin

若 admin.token 为空，登录页输入任意值即可；生产环境请设置强 token。

4. 生命周期管理

coderouter status              # 查看运行状态
coderouter logs --lines 100    # 查看最近 100 行日志
coderouter restart             # 重启
coderouter stop                # 停止

命令参考

| 命令 | 说明 | |------|------| | coderouter serve [--config <path>] | 前台运行，日志输出到终端 | | coderouter start [--config <path>] | 后台守护进程启动 | | coderouter stop | 停止后台实例 | | coderouter restart [--config <path>] | 重启后台实例 | | coderouter status | 查看运行状态与 PID | | coderouter logs [--lines N] | 查看日志（默认 80 行） |

环境变量

| 变量 | 默认值 | 说明 | |------|--------|------| | CODEROUTER_BIN | — | 指定二进制路径（覆盖自动查找） | | CODEROUTER_CONFIG | config.yaml | 配置文件路径 | | CODEROUTER_DATA | ~/.coderouter | PID 文件与日志目录 |

管理控制台功能

| 页面 | 功能 | |------|------| | 仪表盘 | 服务运行时间、请求总数、错误率、缓存命中率、各实体计数、模型/客户端/后端分布图 | | 上游管理 | 第三方配置直接编辑、拖拽排序请求优先级、绑定代理 IP、启用/禁用 | | 分组管理 | 创建分组、策略（顺序/轮询/加权）、粘性会话、成员拖拽排序 | | 鉴权 Key | 自动生成密钥、绑定分组、速率限制、掩码显示、一键复制 | | 代理池 | HTTP/HTTPS/SOCKS5 代理、健康检查延迟、查看绑定上游 | | 请求记录 | 请求历史、状态筛选、耗时展示 | | 数据备份 | JSON 导出/导入、配置文件路径展示 | | 系统设置 | 版本信息、运行时间、重启服务 |

架构

┌─────────────────────────────────────────────────┐
│                   浏览器 :8443/admin              │
│              Vue 3 SPA (Element Plus)            │
└────────────────────┬────────────────────────────┘
                     │ /api/v1/* (Bearer Token)
┌────────────────────▼────────────────────────────┐
│              Go 二进制 (单文件部署)               │
│  ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
│  │ Router   │ │ Protocol │ │ Fingerprint Cloak│ │
│  │ Failover │ │ Convert  │ │ (JA3 + UA)       │ │
│  └────┬─────┘ └────┬─────┘ └────────┬─────────┘ │
│  ┌────▼─────┐ ┌────▼─────┐          │           │
│  │ SQLite   │ │ ProxyPool│          │           │
│  │ Store    │ │ (egress) │          │           │
│  └──────────┘ └────┬─────┘          │           │
└─────────────────────┼────────────────┼──────────┘
                      │                │
              ┌───────▼───────┐  ┌────▼─────┐
              │ 上游 API 网关  │  │ 代理服务器 │
              │ sub2api/newapi│  │ (出口 IP) │
              └───────────────┘  └──────────┘

技术栈

• 后端：Go 1.23、modernc.org/sqlite（纯 Go，无 CGO）、embed.FS
• 前端：Vue 3.5、Vite 5、Element Plus 2.8、ECharts 5、Pinia、vue-router 4
• CLI 包装：Node.js ≥18、ESM、PID 文件生命周期管理

许可证

MIT