# new-api-java

**Repository Path**: huangjun1_admin/new-api-java

## Basic Information

- **Project Name**: new-api-java
- **Description**: AI 网关
- **Primary Language**: Java
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-01
- **Last Updated**: 2026-06-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# New-API-Java — AI 模型网关 (Java 版本)

## 项目概述

New-API-Java 是 [new-api](https://github.com/QuantumNous/new-api) 的 Java 版本实现，一个统一的 AI 模型 API 网关/代理，聚合 40+ 上游 AI 提供商（OpenAI、Claude、Gemini、Azure、AWS Bedrock 等）提供统一的 API 接口，具备用户管理、计费、限流和管理仪表板功能。

## 技术栈

| 组件 | 技术选型 |
|------|----------|
| 语言 | Java 17 |
| 框架 | Spring Boot 3.2.x |
| Web 层 | Spring WebFlux (Reactive) |
| ORM | MyBatis-Plus 3.5.x |
| 数据库 | H2 / MySQL / PostgreSQL |
| 缓存 | Redis (Lettuce) + Caffeine |
| 限流 | Bucket4j |
| 监控 | Micrometer + Prometheus |
| API 文档 | SpringDoc OpenAPI |
| 测试 | JUnit 5 + Mockito + Reactor Test |
| 构建 | Maven 3.9+ |

## 项目结构

```
new-api-java/
├── src/main/java/com/aigateway/newapi/
│   ├── NewApiApplication.java          # 应用入口
│   ├── config/                          # 配置类
│   │   ├── AppConfig.java              # 应用配置
│   │   ├── WebFluxConfig.java          # WebFlux 配置
│   │   ├── RedisConfig.java            # Redis 配置
│   │   └── CacheConfig.java            # 缓存配置
│   ├── entity/                          # 数据实体
│   │   ├── Channel.java                # 渠道/提供商
│   │   ├── Token.java                  # API 令牌
│   │   ├── User.java                   # 用户
│   │   ├── Log.java                    # 日志
│   │   └── Option.java                 # 系统选项
│   ├── mapper/                          # MyBatis Mapper
│   │   ├── ChannelMapper.java
│   │   ├── TokenMapper.java
│   │   ├── UserMapper.java
│   │   ├── LogMapper.java
│   │   └── OptionMapper.java
│   ├── service/                         # 业务服务
│   │   ├── ChannelService.java         # 渠道管理
│   │   ├── TokenService.java           # 令牌管理
│   │   ├── UserService.java            # 用户管理
│   │   ├── LogService.java             # 日志服务
│   │   ├── RelayService.java           # 核心中继服务
│   │   └── RateLimitService.java       # 限流服务
│   ├── controller/                      # 控制器
│   │   ├── RelayController.java        # API 中继控制器
│   │   └── DashboardController.java    # 管理仪表板
│   ├── filter/                          # WebFilter 中间件
│   │   ├── CorsFilter.java             # CORS 处理
│   │   ├── TokenAuthFilter.java        # 令牌认证
│   │   ├── RateLimitFilter.java        # 限流
│   │   └── StatsFilter.java            # 统计
│   ├── dto/                             # 数据传输对象
│   │   ├── OpenAIChatRequest.java      # OpenAI 请求
│   │   ├── OpenAIChatResponse.java     # OpenAI 响应
│   │   ├── OpenAIErrorResponse.java    # OpenAI 错误
│   │   ├── ClaudeRequest.java          # Claude 请求
│   │   ├── GeminiRequest.java          # Gemini 请求
│   │   └── ApiResponse.java            # 通用 API 响应
│   ├── relay/                           # 中继适配器
│   │   ├── RelayAdaptor.java           # 适配器接口
│   │   ├── RelayAdaptorRegistry.java   # 适配器注册表
│   │   ├── openai/OpenAIAdaptor.java   # OpenAI 适配器
│   │   ├── claude/ClaudeAdaptor.java   # Claude 适配器
│   │   ├── gemini/GeminiAdaptor.java   # Gemini 适配器
│   │   ├── deepseek/DeepSeekAdaptor.java
│   │   ├── ali/AliAdaptor.java
│   │   ├── baidu/BaiduAdaptor.java
│   │   ├── zhipu/ZhipuAdaptor.java
│   │   └── ollama/OllamaAdaptor.java
│   └── common/                          # 通用工具
│       ├── ChannelConstants.java        # 渠道类型常量
│       ├── LogConstants.java            # 日志类型常量
│       ├── RelayConstants.java          # 中继模式常量
│       └── CryptoUtils.java             # 加密工具
├── src/test/java/com/aigateway/newapi/
│   ├── service/
│   │   ├── ChannelServiceTest.java
│   │   └── TokenServiceTest.java
│   ├── controller/
│   │   └── RelayControllerTest.java
│   └── relay/
│       └── RelayAdaptorTest.java
├── src/main/resources/
│   └── application.yml
├── src/test/resources/
│   └── application-test.yml
├── pom.xml
└── README.md
```

## 快速开始

### 环境要求

- JDK 17+
- Maven 3.9+
- MySQL 8.0+ (或使用 Docker 内置的 H2 数据库快速体验)
- Redis 7.0+ (可选，用于分布式限流和缓存)

### 本地开发

```bash
# 克隆项目
cd new-api-java

# 编译
mvn clean compile

# 运行测试
mvn test

# 启动应用 (使用 H2 内存数据库)
mvn spring-boot:run

# 打包
mvn clean package -DskipTests
```

### Docker 部署 (推荐)

#### 一键启动 (使用 docker-compose)

```bash
# 启动所有服务 (MySQL + Redis + Application)
docker-compose up -d

# 查看日志
docker-compose logs -f new-api-java

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

访问 http://localhost:3000 即可使用系统。

默认管理员账号: `root` / `admin`

#### 仅部署应用 (连接外部数据库)

```bash
# 构建镜像
docker build -t new-api-java .

# 运行容器
docker run -d -p 3000:3000 \
  -e SQL_DSN="jdbc:mysql://host:3306/new-api" \
  -e DB_USERNAME=root \
  -e DB_PASSWORD=password \
  -e REDIS_HOST=redis \
  -e SESSION_SECRET="your-session-secret" \
  -e CRYPTO_SECRET="your-crypto-secret" \
  new-api-java
```

#### 使用外部 MySQL 和 Redis

```bash
# 启动应用，连接外部服务
docker run -d -p 3000:3000 \
  -e SQL_DSN="jdbc:mysql://192.168.1.100:3306/new-api?useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true" \
  -e DB_USERNAME=root \
  -e DB_PASSWORD="your-db-password" \
  -e REDIS_HOST=192.168.1.101 \
  -e REDIS_PORT=6379 \
  -e SESSION_SECRET="change-me-to-random-string" \
  -e CRYPTO_SECRET="change-me-to-another-random-string" \
  -v /path/to/data:/app/data \
  -v /path/to/logs:/app/logs \
  new-api-java
```

### 环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `SERVER_PORT` | 服务端口 | 3000 |
| `SPRING_PROFILES_ACTIVE` | Spring 环境 | default |
| `SQL_DSN` | 数据库连接 | jdbc:mysql://localhost:3306/new_api |
| `DB_DRIVER` | 数据库驱动 | com.mysql.cj.jdbc.Driver |
| `DB_USERNAME` | 数据库用户名 | root |
| `DB_PASSWORD` | 数据库密码 | - |
| `REDIS_HOST` | Redis 主机 | localhost |
| `REDIS_PORT` | Redis 端口 | 6379 |
| `REDIS_PASSWORD` | Redis 密码 | - |
| `RABBITMQ_HOST` | RabbitMQ 主机 | localhost |
| `RABBITMQ_PORT` | RabbitMQ 端口 | 5672 |
| `RABBITMQ_USERNAME` | RabbitMQ 用户名 | guest |
| `RABBITMQ_PASSWORD` | RabbitMQ 密码 | guest |
| `SESSION_SECRET` | 会话密钥 | - |
| `CRYPTO_SECRET` | 加密密钥 | - |
| `GLOBAL_API_RATE_LIMIT_ENABLE` | 全局 API 限流 | false |
| `GLOBAL_API_RATE_LIMIT` | API 限流阈值 | 100 |
| `DEBUG` | 调试模式 | false |
| `AUTOMATIC_DISABLE_CHANNEL_ENABLED` | 自动禁用渠道 | true |
| `RATE_LIMIT_USE_REDIS` | 使用 Redis 限流 | true |

## API 接口

### 中继 API (OpenAI 兼容)

所有接口与 OpenAI API 格式兼容，使用 `Authorization: Bearer {token}` 认证。

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/v1/chat/completions` | 聊天补全 |
| POST | `/v1/completions` | 文本补全 |
| POST | `/v1/embeddings` | 嵌入向量 |
| POST | `/v1/images/generations` | 图像生成 |
| POST | `/v1/audio/transcriptions` | 语音转文字 |
| POST | `/v1/audio/speech` | 文字转语音 |
| POST | `/v1/rerank` | 重排序 |
| GET | `/v1/models` | 模型列表 |
| GET | `/v1/models/{model}` | 模型详情 |

### 管理 API

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/status` | 系统状态 |
| GET | `/api/channels` | 渠道列表 |
| GET | `/api/channels/{id}` | 渠道详情 |
| POST | `/api/channels` | 创建渠道 |
| PUT | `/api/channels/{id}` | 更新渠道 |
| DELETE | `/api/channels/{id}` | 删除渠道 |
| GET | `/api/tokens` | 令牌列表 |
| GET | `/api/users` | 用户列表 |

## 核心架构

### 请求处理流程

```
Client Request
    │
    ▼
┌──────────────┐
│  CorsFilter   │  CORS 处理
└──────┬───────┘
       ▼
┌──────────────┐
│TokenAuthFilter│  令牌验证 + 用户加载
└──────┬───────┘
       ▼
┌──────────────┐
│RateLimitFilter│  全局限流检查
└──────┬───────┘
       ▼
┌──────────────┐
│ StatsFilter   │  请求统计
└──────┬───────┘
       ▼
┌──────────────┐
│RelayController│  请求解析
└──────┬───────┘
       ▼
┌──────────────┐
│ RelayService  │  渠道选择 + 请求转发
└──────┬───────┘
       ▼
┌──────────────┐
│ RelayAdaptor  │  协议转换 + 上游请求
└──────┬───────┘
       ▼
  Upstream AI API
```

### 渠道选择算法

1. 根据请求的 `model` 参数筛选支持该模型的渠道
2. 根据 Token 的 `group` 属性进一步筛选
3. 按权重（weight）进行加权随机选择
4. 失败时自动重试，排除已失败的渠道
5. 支持跨组重试（crossGroupRetry）

### 支持的 AI 提供商

| 类型 | 适配器 | 协议 |
|------|--------|------|
| OpenAI | OpenAIAdaptor | OpenAI |
| Azure | OpenAIAdaptor | OpenAI |
| Claude | ClaudeAdaptor | Anthropic |
| Gemini | GeminiAdaptor | Google |
| DeepSeek | DeepSeekAdaptor | OpenAI |
| 阿里 (Qwen) | AliAdaptor | OpenAI |
| 百度 (ERNIE) | BaiduAdaptor | OpenAI |
| 智谱 (GLM) | ZhipuAdaptor | OpenAI |
| Ollama | OllamaAdaptor | Ollama |
| +30+ 其他 | OpenAIAdaptor | OpenAI |

## 测试

```bash
# 运行所有测试
mvn test

# 运行特定测试类
mvn test -Dtest=ChannelServiceTest

# 生成测试报告
mvn test jacoco:report
```

## 监控

应用集成了 Micrometer + Prometheus 监控：

- 健康检查: `GET /actuator/health`
- 指标: `GET /actuator/metrics`
- Prometheus: `GET /actuator/prometheus`

## 与原 Go 版本的对应关系

| Go 模块 | Java 模块 |
|---------|-----------|
| `router/relay-router.go` | `RelayController.java` |
| `middleware/distributor.go` | `RelayService.java` (渠道选择) |
| `middleware/auth.go` | `TokenAuthFilter.java` |
| `middleware/rate-limit.go` | `RateLimitFilter.java` |
| `service/channel.go` | `ChannelService.java` |
| `service/token.go` | `TokenService.java` |
| `relay/channel/adaptor.go` | `RelayAdaptor.java` |
| `relay/channel/openai/` | `relay/openai/OpenAIAdaptor.java` |
| `relay/channel/claude/` | `relay/claude/ClaudeAdaptor.java` |
| `relay/channel/gemini/` | `relay/gemini/GeminiAdaptor.java` |
| `model/channel.go` | `entity/Channel.java` |
| `model/token.go` | `entity/Token.java` |
| `model/user.go` | `entity/User.java` |
| `dto/` | `dto/` |
| `common/` | `common/` |

## 常见问题

### 1. 数据库连接失败

确保 MySQL 已启动且连接信息正确：
```bash
# 检查 MySQL 容器
docker-compose ps mysql

# 查看 MySQL 日志
docker-compose logs mysql
```

### 2. 端口冲突

如果 3000 端口已被占用，修改 `docker-compose.yml` 中的端口映射：
```yaml
ports:
  - "3001:3000"  # 改为 3001:3000
```

### 3. 内存不足

修改 `Dockerfile` 中的 JVM 内存配置：
```dockerfile
ENV JAVA_OPTS="-Xms512m -Xmx2048m -XX:+UseG1GC"
```

### 4. 恢复数据

```bash
# 导入 SQL 文件
docker-compose exec mysql mysql -uroot -p new_api < sql/init.sql
```

### 5. 查看日志

```bash
# 应用日志
docker-compose logs -f new-api-java

# 所有服务日志
docker-compose logs -f
```