# open-code-api

**Repository Path**: naka507/open-code-api

## Basic Information

- **Project Name**: open-code-api
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-26
- **Last Updated**: 2026-04-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Cloud Code API

AI Provider 网关服务，支持多种 AI 模型供应商的统一接入、协议转换和负载均衡。

## 特性

- **多 Provider 支持** — Gemini、Claude、OpenAI、Grok、通义千问、Codex、iFlow、Forward 透传
- **协议转换** — OpenAI / Gemini / Claude / Grok / Codex 格式自动互转
- **TLS 指纹模拟** — wreq-js 模拟 Chrome 131+ 浏览器指纹，无需额外 sidecar 进程
- **账号池管理** — 多账号轮询、健康检查、错误计数、故障转移
- **流式响应** — SSE 流式输出，兼容 OpenAI / Claude / Gemini 流格式
- **OAuth 支持** — Google OAuth、Kiro OAuth、文件凭证自动刷新
- **管理面板** — Web UI 仪表盘，实时监控 Provider 状态、用量统计
- **插件系统** — 可扩展的认证、监控、API 多路复用插件
- **低资源占用** — Fastify 框架 + PM2 cluster，适合 1GB 内存 VPS 部署

## 技术栈

| 组件 | 技术 |
|------|------|
| Runtime | Node.js 20+ |
| 语言 | TypeScript 5.x |
| Web 框架 | Fastify 5.x |
| HTTP 客户端 | wreq-js (浏览器 TLS 指纹) |
| WebSocket | @fastify/websocket |
| 数据验证 | Zod |
| 日志 | Pino |
| 进程管理 | PM2 |

## 快速开始

```bash
# 安装依赖
npm install

# 复制配置
cp configs/config.example.json configs/config.json

# 可选：如果你要自定义 CONFIG_PATH / NODE_ENV / LOG_LEVEL
cp .env.example .env

# 编辑配置（至少设置 API Keys 和一个 Provider）
vim configs/config.json

# 开发模式
npm run dev

# 生产构建
npm run build
npm start
```

## 项目结构

```
cloud-code-api/
├── src/
│   ├── index.ts                     # 入口，初始化 Provider 和插件
│   ├── server.ts                    # Fastify 服务器配置
│   ├── config/                      # 配置管理（json + CLI + Zod 验证）
│   ├── core/
│   │   ├── http-client.ts           # wreq-js 封装（重试、指数退避）
│   │   ├── plugin-manager.ts        # 插件生命周期管理
│   │   ├── provider-pool.ts         # Provider 池（轮询/随机/故障转移）
│   │   └── system-prompt.ts         # 系统提示词注入
│   ├── providers/                   # 10 个 Provider 实现
│   │   ├── base.ts                  # 基类（账号轮询、健康追踪）
│   │   ├── registry.ts              # Provider 注册表
│   │   ├── gemini/                  # Gemini + Antigravity (OAuth)
│   │   ├── claude/                  # Claude + Kiro (OAuth)
│   │   ├── openai/                  # OpenAI + Qwen + Codex + iFlow
│   │   ├── grok/                    # Grok（Cookie/API Key 认证）
│   │   └── forward/                 # 通用透传
│   ├── converters/                  # 5 个格式转换器
│   ├── routes/                      # API 路由
│   │   ├── api.ts                   # /v1/* AI API 端点
│   │   ├── health.ts                # 健康检查 + Token 计数
│   │   └── admin/                   # /api/* 管理端点
│   ├── middleware/                   # 认证 + Provider 选择
│   ├── plugins/                     # 内置插件
│   └── utils/                       # 工具函数
├── static/                          # 管理面板前端
├── configs/                         # 配置文件
├── ecosystem.config.cjs             # PM2 配置
└── package.json
```

## API 端点

### AI API（需要 API Key 认证）

| 端点 | 方法 | 说明 |
|------|------|------|
| `/v1/chat/completions` | POST | OpenAI 兼容 Chat Completions |
| `/v1/messages` | POST | Claude 兼容 Messages API |
| `/v1/responses` | POST | OpenAI Responses 格式 |
| `/v1/models` | GET | 模型列表 |
| `/v1/{provider}/chat/completions` | POST | 指定 Provider 的 Chat Completions |
| `/v1/{provider}/messages` | POST | 指定 Provider 的 Messages |
| `/v1/{provider}/models` | GET | 指定 Provider 的模型列表 |

### 公开端点

| 端点 | 方法 | 说明 |
|------|------|------|
| `/health` | GET | 健康检查 |
| `/provider_health` | GET | Provider 健康状态 |
| `/count_tokens` | POST | Token 计数估算 |

### 管理 API（需要 Admin 密码认证）

| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/auth/login` | POST | 管理员登录 |
| `/api/auth/check` | GET | 检查认证状态 |
| `/api/config` | GET/PUT | 配置查看/更新 |
| `/api/config/reload` | POST | 重载配置文件 |
| `/api/providers` | GET | Provider 状态列表 |
| `/api/providers/:name/test` | POST | 测试指定 Provider |
| `/api/usage` | GET | 用量统计 |
| `/api/system` | GET | 系统信息 |
| `/api/plugins` | GET | 插件列表 |
| `/api/events` | GET | SSE 实时事件流 |
| `/api/events/ws` | WS | WebSocket 实时事件 |
| `/api/oauth/providers` | GET | OAuth Provider 列表 |
| `/api/oauth/upload-credentials` | POST | 上传 OAuth 凭证 |

## 部署

### PM2 生产部署

```bash
npm run build
pm2 start ecosystem.config.cjs
```

### 启动环境变量

```
CONFIG_PATH=configs/config.json   # 可选：自定义配置文件路径
NODE_ENV=production               # 进程模式
LOG_LEVEL=info                    # 日志级别
```

### 运行配置

`server`、`auth`、`providers`、`proxy`、`tls` 等运行配置统一放在 `configs/config.json`。

示例：

```json
{
  "server": {
    "port": 3000,
    "host": "0.0.0.0",
    "publicUrl": "https://your-api.com"
  },
  "auth": {
    "adminPassword": "changeme",
    "apiKeys": ["sk-your-key"]
  },
  "proxy": {
    "url": "socks5://127.0.0.1:40000",
    "enabledProviders": ["grok"]
  },
  "tls": {
    "impersonate": "chrome_131"
  }
}
```

说明：

- 不要在 `.env` 里重复设置 `PORT`、`HOST`、`PUBLIC_URL`、`ADMIN_PASSWORD`、`API_KEYS`。
- 不要在 `.env` 里长期设置 `HTTP_PROXY` / `HTTPS_PROXY`；应用代理统一用 `configs/config.json` 的 `proxy.url`。

## 许可证

MIT