# openai_proxy

**Repository Path**: TonyDon/openai_proxy

## Basic Information

- **Project Name**: openai_proxy
- **Description**: No description available
- **Primary Language**: NodeJS
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-01
- **Last Updated**: 2026-04-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OpenAI Proxy Service

OpenAI 兼容代理服务，采用模块化架构设计，支持多模型提供商配置。本项目提供标准的 OpenAI API 接口，外部调用时自动代理到配置的模型提供商。

## 功能特性

- ✅ **OpenAI API 兼容**：完全兼容 OpenAI API 接口规范
- ✅ **多提供商支持**：支持 OpenAI、DeepSeek、Anthropic、DeepSeek Anthropic、Azure OpenAI、DashScope Coding、自定义提供商
- ✅ **动态切换**：通过请求头动态切换模型提供商
- ✅ **配置热加载**：settings.json 修改后自动生效，无需重启
- ✅ **默认模型配置**：支持为每个提供商配置 defaultModel
- ✅ **模块化架构**：Proxy/Plugin 分离设计，易于扩展新提供商
- ✅ **高性能日志**：基于 pino 的异步结构化日志系统，支持日志轮转
- ✅ **Docker 部署**：支持 Docker Compose 一键部署

## 快速开始

### 1. 安装依赖

```bash
npm install
```

### 2. 配置服务

复制示例配置文件：

```bash
cp settings.example.json settings.json
```

编辑 `settings.json` 文件：

```json
{
  "service": {
    "port": 8000,
    "host": "0.0.0.0",
    "defaultProvider": "qwen_codeplan",
    "logLevel": "info"
  },
  "providers": {
    "qwen_codeplan": {
      "name": "qwen",
      "baseUrl": "https://coding.dashscope.aliyuncs.com/v1",
      "apiKey": "${QWEN_API_KEY}",
      "headers": {
        "Content-Type": "application/json",
        "Authorization": "Bearer ${QWEN_API_KEY}"
      },
      "defaultModel": "qwen3-coder-plus",
      "endpoints": {
        "/v1/chat/completions": "/chat/completions",
        "/v1/completions": "/completions",
        "/v1/embeddings": "/embeddings",
        "/v1/models": "/models"
      }
    }
  }
}
```

**配置说明**：
- `baseUrl`: 提供商 API 基础 URL（支持包含版本号如 `/v1`）
- `apiKey`: API 密钥，支持 `${ENV_VAR}` 格式引用环境变量
- `defaultModel`: 调用者未指定 model 时使用的默认模型
- `endpoints`: 端点映射配置（可选，用于自定义路径映射）
- `headers`: 自定义请求头（可选）

### 3. 设置环境变量

```bash
export QWEN_API_KEY=sk-sp-your-api-key-here
```

### 4. 启动服务

```bash
# 生产环境
npm start

# 开发环境
npm run dev
```

启动后访问：http://localhost:8000

## API 接口

### 基础信息

| 接口 | 描述 |
|------|------|
| `GET /` | API 根路径信息 |
| `GET /health` | 健康检查 |
| `GET /status` | 服务状态信息 |
| `GET /providers` | 获取所有提供商配置（脱敏） |

### OpenAI 兼容接口

| 接口 | 描述 |
|------|------|
| `POST /v1/chat/completions` | 聊天补全（支持 SSE 流式） |
| `POST /v1/completions` | 文本补全 |
| `POST /v1/embeddings` | 嵌入向量 |
| `GET /v1/models` | 模型列表 |
| `GET /v1/models/:model` | 模型详情 |

### 请求头参数

| 请求头 | 描述 | 必填 |
|--------|------|------|
| `X-Model-Provider` | 指定模型提供商 | 否，默认使用 defaultProvider |
| `X-Stream` | 启用 SSE 流式响应 (true/false) | 否 |

## 支持的提供商

| 提供商 | Provider 名称 | 说明 | 文档 |
|--------|--------------|------|------|
| OpenAI | `openai` | OpenAI 官方 API | - |
| DeepSeek | `deepseek` | DeepSeek API（OpenAI 兼容格式） | [DeepSeek 插件文档](docs/DEEPSEEK_PLUGIN.md) |
| Anthropic | `anthropic` | Anthropic API（Claude 模型） | [Anthropic 插件文档](docs/ANTHROPIC_PLUGIN.md) |
| DeepSeek Anthropic | `deepseek_anthropic` | DeepSeek Anthropic 兼容接口 | [DeepSeek Anthropic 插件文档](docs/DEEPSEEK_ANTHROPIC_PLUGIN.md) |
| Azure OpenAI | `azure` | Azure OpenAI 服务 | - |
| DashScope Coding | `qwen_codeplan` | 阿里通义灵码 | - |

## 使用示例

### 聊天补全请求

```bash
# 使用默认提供商，自动使用 defaultModel
curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "你好"}]
  }'

# 指定提供商和模型
curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "X-Model-Provider: qwen_codeplan" \
  -d '{
    "model": "qwen3.5-plus",
    "messages": [{"role": "user", "content": "你好"}]
  }'

# SSE 流式响应
curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "X-Stream: true" \
  -d '{
    "model": "qwen3-coder-plus",
    "messages": [{"role": "user", "content": "你好"}]
  }'
```

### Python 示例

```python
import requests

response = requests.post(
    'http://localhost:8000/v1/chat/completions',
    headers={
        'Content-Type': 'application/json',
        'X-Model-Provider': 'qwen_codeplan'
    },
    json={
        'model': 'qwen3-coder-plus',
        'messages': [
            {'role': 'user', 'content': 'Hello!'}
        ]
    }
)

print(response.json())
```

## 配置说明

> 📖 **完整配置文档**：查看 [settings.json 完整配置说明](docs/SETTINGS_GUIDE.md) 了解所有配置选项和示例。

### settings.json 配置

| 参数 | 描述 | 必填 |
|------|------|------|
| `service.port` | 服务端口 | 否，默认 8000 |
| `service.host` | 服务地址 | 否，默认 0.0.0.0 |
| `service.defaultProvider` | 默认提供商 | 否，默认 openai |
| `service.logLevel` | 日志级别 | 否，默认 info |
| `service.log.dir` | 日志目录 | 否，默认 ./logs |
| `service.log.rotateType` | 日志轮转类型 (daily/hourly) | 否，默认 daily |
| `service.log.retentionDays` | 日志保留天数 | 否，默认 15 |
| `providers.<name>.name` | 提供商名称 | 是 |
| `providers.<name>.baseUrl` | API 基础 URL | 是 |
| `providers.<name>.apiKey` | API 密钥 | 是 |
| `providers.<name>.defaultModel` | 默认模型 | 否 |
| `providers.<name>.endpoints` | 端点映射 | 否 |

### 环境变量占位符

配置文件中可使用 `${VAR_NAME}` 格式引用环境变量：

```json
{
  "providers": {
    "qwen_codeplan": {
      "apiKey": "${QWEN_API_KEY}",
      "baseUrl": "https://coding.dashscope.aliyuncs.com/v1"
    }
  }
}
```

### 配置热加载

修改 `settings.json` 后，服务会自动检测并重新加载配置，无需重启。

## 项目结构

```
/app
├── modules/                 # 模块化架构
│   ├── api/
│   │   └── ApiRouter.js     # API 路由工厂
│   └── proxy/
│       ├── abstract/        # 抽象类
│       │   ├── ProxyBase.js
│       │   └── ModelProviderPlugin.js
│       ├── core/            # 核心实现
│       │   ├── NormalProxy.js
│       │   ├── SSEProxy.js
│       │   └── ProxyFactory.js
│       ├── plugins/         # 插件实现
│       │   ├── BaseProviderPlugin.js
│       │   ├── OpenAIPlugin.js
│       │   ├── DeepSeekPlugin.js
│       │   ├── AnthropicPlugin.js
│       │   ├── DeepSeekAnthropicPlugin.js
│       │   └── QwenCodeplanePlugin.js
│       ├── logger/          # 日志模块
│       │   ├── Logger.js    # pino 日志类
│       │   └── index.js
│       └── utils/           # 工具类
│           ├── RequestBuilder.js
│           └── ResponseHandler.js
├── routes/                  # 路由
│   ├── api.js               # API 路由工厂调用
│   ├── v1.js                # API v1 路由
│   ├── v2.js                # API v2 路由
│   ├── v3.js                # API v3 路由
│   └── health.js            # 健康检查路由
├── middleware/              # 中间件
│   ├── logger.js            # 日志中间件
│   └── proxy.js             # 代理中间件
├── config/                  # 配置管理
│   └── providers.js         # 配置管理器（支持热加载）
├── tests/                   # 测试文件
├── settings.json            # 主配置文件
├── server.js                # 主入口
└── package.json             # 项目配置
```

## 环境变量

| 变量 | 描述 | 默认值 |
|------|------|--------|
| `PORT` | 服务端口 | 8000 |
| `HOST` | 服务地址 | 0.0.0.0 |
| `DEFAULT_PROVIDER` | 默认提供商 | qwen_codeplan |
| `OPENAI_API_KEY` | OpenAI API Key | - |
| `DEEPSEEK_API_KEY` | DeepSeek API Key | - |
| `ANTHROPIC_API_KEY` | Anthropic API Key | - |
| `QWEN_API_KEY` | DashScope Coding API Key | - |
| `LOG_LEVEL` | 日志级别 | info |
| `NODE_ENV` | 运行环境 | production |

## Docker 部署

### 使用 Docker Compose（推荐）

```bash
# 设置环境变量
export QWEN_API_KEY=sk-sp-your-api-key-here

# 构建并启动
docker-compose up -d
```

### 验证部署

```bash
# 检查健康状态
curl http://localhost:8000/health

# 查看日志
docker logs -f openai-proxy

# 停止服务
docker-compose down
```

## 注意事项

1. **API Key 安全**：请妥善保管 API Key，不要提交到版本控制
2. **超时设置**：默认请求超时为 120 秒
3. **请求体大小**：限制为 50MB
4. **配置热加载**：修改 settings.json 后约 100ms 自动生效
5. **日志系统**：
   - 日志文件位于 `./logs/` 目录
   - 默认按天轮转，保留 15 天
   - 异步写入，不阻塞请求处理
   - 同时输出到 stdout（Docker 日志）和文件

## 日志系统

### 配置示例

```json
{
  "service": {
    "log": {
      "dir": "./logs",
      "rotateType": "daily",
      "retentionDays": 15
    }
  }
}
```

### 日志轮转

| rotateType | 说明 | 文件命名 |
|-----------|------|---------|
| `daily` | 按天轮转 | `app-YYYYMMDD.log` |
| `hourly` | 按小时轮转 | `app-YYYYMMDDHH.log` |

### 日志格式

**生产环境（JSON）：**
```json
{"level":"INFO","timestamp":"2026-04-18T12:00:00.000Z","message":"HTTP Request","method":"POST","url":"/chat/completions","status":200,"duration_ms":150}
```

**开发环境（美化）：**
```
[2026-04-18 12:00:00.000] INFO: HTTP Request
    method: POST
    url: /chat/completions
    status: 200
    duration_ms: 150
```

### 高性能设计

- ✅ **异步写入**：使用 pino 的异步流式输出，不阻塞事件循环
- ✅ **缓冲写入**：4KB 缓冲区，减少系统调用次数
- ✅ **多流输出**：同时输出到 stdout 和文件
- ✅ **自动清理**：每天凌晨 2 点自动清理过期日志

## 扩展新提供商

新增模型提供商只需两步：

### 1. settings.json 添加配置

```json
{
  "providers": {
    "my_provider": {
      "name": "My Provider",
      "baseUrl": "https://api.myprovider.com/v1",
      "apiKey": "${MY_PROVIDER_API_KEY}",
      "defaultModel": "model-v1",
      "endpoints": {
        "/v1/chat/completions": "/chat/completions"
      }
    }
  }
}
```

### 2. 创建 Plugin（可选）

如需特殊处理逻辑，在 `modules/proxy/plugins/` 下创建新 Plugin 类：

- **OpenAI 兼容接口**：继承 `BaseProviderPlugin`
- **Anthropic 兼容接口**：继承 `AnthropicPlugin`

### 3. 注册到 ProxyFactory

在 `modules/proxy/core/ProxyFactory.js` 中注册新插件：

```javascript
const { MyPlugin } = require('../plugins/MyPlugin');

const BUILTIN_PLUGINS = {
  // ...
  my_provider: MyPlugin,
};
```

## 插件开发指南

### OpenAI 兼容插件

```javascript
const { BaseProviderPlugin } = require('./BaseProviderPlugin');

class MyOpenAICompatiblePlugin extends BaseProviderPlugin {
  getName() {
    return 'my_provider';
  }
  
  // 可选：自定义请求转换
  _customTransformRequest(requestBody, headers, context) {
    return { headers, requestBody };
  }
  
  // 可选：自定义响应转换
  _customTransformResponse(response, context) {
    return { data: response.data };
  }
}

module.exports = { MyOpenAICompatiblePlugin };
```

### Anthropic 兼容插件

```javascript
const { AnthropicPlugin } = require('./AnthropicPlugin');

class MyAnthropicCompatiblePlugin extends AnthropicPlugin {
  getName() {
    return 'my_anthropic_provider';
  }
  
  // 可选：自定义端点映射
  getDefaultEndpoints() {
    return {
      ...super.getDefaultEndpoints(),
      '/v1/custom': '/v1/custom',
    };
  }
}

module.exports = { MyAnthropicCompatiblePlugin };
```

## License

Apache License 2.0