# AgenticTokenHub

**Repository Path**: ldwallen/AgenticTokenHub

## Basic Information

- **Project Name**: AgenticTokenHub
- **Description**: AgenticTokenHub 是一款企业级 AI Token 中转平台，提供 多模型 AI 网关 与 企业级会员管理 核心能力。平台以“统一 API 接入 + 灵活计费策略 + 企业级会员体系”为核心理念，提供多模型统一管理、精细化 Token 计费、会员套餐管理等核心能力，打造可扩展、可计费、可运营的新一代 AI 服务平台。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2026-06-02
- **Last Updated**: 2026-06-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<p align="center">
  <img src="https://img.shields.io/badge/Spring%20Boot-3.2.0-blue.svg" alt="Spring Boot">
  <img src="https://img.shields.io/badge/Java-17-orange.svg" alt="Java">
  <img src="https://img.shields.io/badge/Docker-20.10+-blue.svg" alt="Docker">
  <img src="https://img.shields.io/badge/AI%20Models-10+-purple.svg" alt="AI Models">
</p>

# AgenticTokenHub - AI Token 中转平台

**AgenticTokenHub** 是一款**企业级 AI Token 中转平台**，提供 **多模型 AI 网关** 与 **企业级会员管理** 核心能力。平台以“统一 API 接入 + 灵活计费策略 + 企业级会员体系”为核心理念，提供多模型统一管理、精细化 Token 计费、会员套餐管理等核心能力，打造**可扩展、可计费、可运营**的新一代 AI 服务平台。

---

## Agentic 生态闭环定位

AgenticTokenHub 是 Agentic 生态中的 **AI 能力与 Token 结算底座**。它与另外两个项目形成闭环：

| 项目 | 生态定位 | 权威边界 |
|---|---|---|
| **AgenticTokenHub** | 多模型网关、Token 钱包、Token 兑换、API 鉴权、用量统计、MCP Token 工具 | Token 余额、Token 流水、模型调用、API Key、租户额度 |
| **AgenticCPS** | 商品搜索、比价、转链、订单追踪、返利结算、CPS MCP 工具 | 返利余额、返利状态、商品与订单真实性、佣金和推广链接 |
| **AgenticAIoT** | 设备接入、告警分析、数据流转、规则引擎、AI 运维、采购建议 | 设备、指标、告警、AI 分析任务、采购需求和审批流程 |

三者的商业闭环是：

```text
AgenticCPS 产生可用返利
        ↓
返利兑换 AgenticTokenHub Token
        ↓
AgenticAIoT / CPS / Agent 消耗 Token 调用 AI
        ↓
AIoT 设备分析生成采购需求
        ↓
AgenticCPS 推荐商品、转链、成交并再次产生返利
```

### 统一集成原则

- **统一用户与租户**：跨系统接口必须传递 `userId` 与 `tenantId`，后续由生态中台统一绑定外部账号。
- **统一资产流转**：Token、返利、积分都必须有钱包余额、业务订单、幂等键和资产流水；禁止跨系统直接改对方余额。
- **统一开放鉴权**：跨系统调用必须使用 AppKey/AppSecret、HMAC-SHA256、timestamp、nonce、`X-Idempotency-Key`。
- **统一事件流水**：订单结算、返利可用、Token 发放、AIoT 告警、推荐结果等动作要能记录和重试。
- **统一 MCP 工具**：MCP 工具只封装稳定 OpenAPI，不绕过鉴权、幂等、限额、风控和审计。

### 当前优先级

P0 已优先落在本仓库：返利兑换 Token 的 Token 平台侧能力。核心接口包括：

```http
POST /api/v1/openapi/token/exchange/preview
POST /api/v1/openapi/token/exchange/submit
GET  /api/v1/openapi/token/exchange/orders/{exchangeOrderId}
POST /api/v1/openapi/token/exchange/{exchangeOrderId}/confirm-source-deduct
POST /api/v1/openapi/token/exchange/{exchangeOrderId}/rollback
```

兑换状态机：

```text
pending → credited → confirmed
pending → failed
credited → rollback_required
```

含义：

- `pending`：兑换订单已创建，等待 Token 发放。
- `credited`：Token 已发放，等待 AgenticCPS 确认返利扣减。
- `confirmed`：AgenticCPS 已确认扣减返利，兑换闭环完成。
- `failed`：Token 发放失败，AgenticCPS 应解冻返利。
- `rollback_required`：Token 已发放但 CPS 扣减失败，需要对账补偿。

---

## 平台简介

### 核心能力

| 能力 | 描述 |
|------|------|
| **多模型统一接入** | 支持 OpenAI、Claude、Gemini、DeepSeek 等 10+ 主流大模型，统一 API 格式 |
| **会员套餐体系** | 日卡/周卡/月卡/年卡多档套餐，支持激活码兑换 |
| **Token 计费** | 按量计费 + 套餐包量，Spring Boot 计费服务直连 MySQL |
| **积分互转** | 支持外部平台积分兑换 Token，可配置转换比例与审核规则 |
| **生态返利兑换** | 支持 AgenticCPS 已结算返利兑换 AI Token，含幂等、签名、流水和补偿状态 |
| **多渠道支付** | 支持微信支付、支付宝、激活码等多种充值方式 |

### 技术架构

```
用户 → Nginx (反代+限速+SSL)
         ├── / → LobeChat (AI 聊天前端)
         ├── /v1/ → new-api (多模型 API 网关)
         └── /api/billing/ → billing-service (Java 计费服务)
                               ├── MySQL 8.0 (数据存储)
                               └── Redis 7 (缓存+限流)
```

| 组件 | 说明 | 端口 |
|---|---|---|
| **Nginx** | 反向代理、SSL、限速、SSE 流式输出 | 80 / 443 |
| **LobeChat** | AI 聊天前端（1:1 官网体验） | 3210 |
| **new-api** | API 网关（多模型管理、渠道轮询、会员套餐页） | 3000 |
| **billing-service** | Java 计费服务（套餐、用量、积分互转） | 8081 |
| **MySQL** | 数据持久化 | 3306 |
| **Redis** | 缓存 & 会话管理 | 6379 |

---

## 目录结构

```
AgenticTokenHub/
├── billing-service/             # Java 计费服务（Spring Boot + MySQL）
│   ├── src/main/java/           # 源代码
│   │   └── com/aitoken/billing/
│   │       ├── BillingServiceApplication.java
│   │       ├── controller/      # REST API 接口
│   │       ├── service/         # 业务逻辑
│   │       ├── entity/          # 数据实体
│   │       ├── repository/      # 数据访问
│   │       ├── dto/             # 数据传输对象
│   │       ├── config/          # 配置类
│   │       └── exception/       # 异常处理
│   ├── src/main/resources/
│   │   └── application.yml      # 应用配置
│   ├── pom.xml                  # Maven 配置
│   ├── Dockerfile               # Docker 多阶段构建
│   └── README.md                # 服务详细说明
├── new-api-source/              # new-api 前端定制源码（会员套餐/积分互转页面）
├── script/
│   ├── docker/                  # Docker 部署文件
│   │   ├── .env                 # 环境变量配置（含密码，勿提交）
│   │   ├── .env.example         # 环境变量示例
│   │   ├── docker-compose.yml   # 主编排文件（6 个服务）
│   │   ├── nginx/
│   │   │   └── conf.d/
│   │   │       └── default.conf # Nginx 反代配置
│   │   ├── db-init/             # 数据库初始化脚本
│   │   ├── data/                # 持久化数据（自动生成）
│   │   └── logs/                # 日志目录
│   └── shell/
│       └── manage.bat           # Windows 管理脚本（菜单式）
└── docs/                        # 文档目录
```

---

## 快速部署

### 前置要求

- [Docker](https://www.docker.com/) 20.10+
- [Docker Compose](https://docs.docker.com/compose/) v2.0+
- 至少一个 AI 模型的 API Key（OpenAI / Claude / DeepSeek 等）

### 一、配置环境变量

```bash
cd script/docker

# 复制示例配置
cp .env.example .env

# 修改 .env 中的密码和配置
# 重点修改：MYSQL_ROOT_PASSWORD、REDIS_PASSWORD、LOBE_ACCESS_CODE
```

### 二、启动所有服务

```bash
# 首次部署（构建镜像 + 启动，包含 billing-service 本地构建）
docker compose up -d --build

# 查看各服务状态
docker compose ps

# 等待所有服务 healthy 后，查看日志确认无报错
docker compose logs -f --tail=50
```

> **说明**：首次启动会在容器内编译 billing-service 和 new-api，约需 5-10 分钟，请耐心等待。

### 三、配置 AI 模型渠道

1. 访问 **http://localhost:3000** → new-api 管理面板
2. 默认账号：`root` / `123456`（首次登录请立即修改密码）
3. 进入 **渠道管理** → **添加渠道**
4. 选择类型（OpenAI / Claude / DeepSeek 等），填入你的 API Key
5. 测试渠道连通性

### 四、生成令牌并对接 LobeChat

1. 在 new-api 中进入 **令牌管理** → **创建令牌**
2. 复制生成的 Key（格式如 `sk-xxx`）
3. 编辑 `.env`，将 Key 填入 `OPENAI_API_KEY`：
   ```
   OPENAI_API_KEY=sk-你复制的令牌Key
   ```
4. 重启 LobeChat：
   ```bash
   docker compose restart lobe-chat
   ```

### 五、开始使用

| 入口 | 地址 | 说明 |
|---|---|---|
| 聊天界面 | http://localhost | 通过 Nginx 代理 |
| 聊天界面（直连） | http://localhost:3210 | LobeChat 直连 |
| API 管理面板 | http://localhost:3000 | new-api 后台 |
| 会员套餐页 | http://localhost:3000/plans | 用户购买套餐 |
| 积分互转页 | http://localhost:3000/credit-transfer | 外部积分兑换 Token |
| 计费服务健康检查 | http://localhost:8081/api/v1/billing/health | billing-service 状态 |
| API 接口 | http://localhost/v1/chat/completions | 兼容 OpenAI 格式 |

---

## 数据库说明

初始化脚本（`script/docker/db-init/`）创建以下数据库：

| 数据库 | 用途 |
|---|---|
| `new_api` | new-api 自动管理（渠道、令牌、日志等） |
| `ai_token_platform` | 平台业务数据（用户、订单、套餐、积分互转等） |

`ai_token_platform` 主要数据表：

| 表名 | 说明 |
|---|---|
| `user` | 用户表（含套餐、余额、API Key） |
| `plan_config` | 套餐配置（日卡/周卡/月卡/年卡） |
| `orders` | 订单表（微信/支付宝/激活码） |
| `activation_code` | 激活码表 |
| `usage_log` | Token 用量记录 |
| `credit_source` | 积分来源系统配置 |
| `credit_transfer_record` | 积分转入记录 |
| `notice` | 平台公告 |

### 默认账号

- **new-api 管理员**：root / 123456（请首次登录后立即修改）
- **数据库管理员**：root / `.env` 中配置的 `MYSQL_ROOT_PASSWORD`
- **平台管理员**（`ai_token_platform.user`）：admin / admin123456

---

## 支持的模型

通过 new-api 网关，可接入以下模型（持续扩展）：

| 厂商 | 模型 |
|---|---|
| OpenAI | GPT-4o、GPT-4o-mini、o1、o3 等 |
| Anthropic | Claude 3.5 Sonnet、Claude 3 Opus 等 |
| Google | Gemini 2.5 Pro、Gemini 2.0 Flash 等 |
| DeepSeek | DeepSeek-V3、DeepSeek-R1 等 |
| 其他 | 通义千问、智谱 GLM、Mistral、Llama 等 |

---

## Nginx 配置要点

| 特性 | 配置 |
|---|---|
| SSE 流式输出 | `proxy_buffering off` + `chunked_transfer_encoding on` |
| WebSocket | `Upgrade` + `Connection "upgrade"` 头 |
| AI 超时 | `proxy_read_timeout 300s`（5 分钟） |
| API 限速 | 30 次/分钟（可调整） |
| 聊天限速 | 60 次/分钟 |
| 文件上传 | `client_max_body_size 50m` |
| 安全头 | X-Frame-Options、X-Content-Type-Options 等 |

### 启用 HTTPS

1. 将 SSL 证书放入 `nginx/ssl/` 目录（`fullchain.pem` + `privkey.pem`）
2. 编辑 `nginx/conf.d/default.conf`，取消 HTTPS server 块的注释
3. 重启 Nginx：`docker-compose restart nginx`

---

## 管理脚本

`manage.bat` 提供菜单式管理：

```
1. 启动所有服务        5. 查看服务日志
2. 停止所有服务        6. 仅启动基础服务 (MySQL + Redis)
3. 重启所有服务        7. 重建并启动 (首次部署)
4. 查看服务状态        8. 清理数据 (危险!)
```

---

## 常用命令

```bash
# 进入 Docker 目录
cd script/docker

# 查看服务状态
docker compose ps

# 查看实时日志（所有服务）
docker compose logs -f --tail=100

# 查看单个服务日志
docker compose logs -f billing-service
docker compose logs -f new-api

# 重启单个服务
docker compose restart lobe-chat
docker compose restart new-api
docker compose restart billing-service

# 重新构建并启动（代码有变更时）
docker compose up -d --build billing-service
docker compose up -d --build new-api

# 更新官方镜像并重启
docker compose pull lobe-chat
docker compose up -d lobe-chat

# 进入 MySQL
docker exec -it ai-mysql mysql -uroot -p

# 进入 Redis
docker exec -it ai-redis redis-cli -a 你的Redis密码

# 健康检查
curl http://localhost:8081/api/v1/billing/health
curl http://localhost:3000/api/status
```

---

## 技术栈

### 后端技术

| 技术 | 说明 | 版本 |
|------|------|------|
| [Spring Boot](https://spring.io/projects/spring-boot) | Java 计费服务框架 | 3.2.0 |
| [Spring Data JPA](https://spring.io/projects/spring-data-jpa) | ORM 数据访问层 | - |
| [MySQL](https://www.mysql.com/) | 关系型数据库 | 8.0 |
| [Redis](https://redis.io/) | 缓存数据库 | 7.0 |
| [Lombok](https://projectlombok.org/) | 代码简化工具 | 1.18.30 |

### 前端与网关

| 技术 | 说明 | 版本 |
|------|------|------|
| [LobeChat](https://github.com/lobehub/lobe-chat) | AI 聊天前端 | latest |
| [new-api](https://github.com/Calcium-Ion/new-api) | API 网关（定制版，含会员套餐/积分互转页） | latest |
| [React](https://react.dev/) | new-api 前端框架 | 18 |
| [Nginx](https://nginx.org/) | 反向代理 | 1.25 |

---

## 交流社区

欢迎加入 **AgenticTokenHub 开发者社区**，与 AI 服务开发者、创业者一起交流技术、分享经验！

| 渠道 | 说明 | 二维码 |
|:---------:|:-----------------------------------------------------------------|:--------:|
| **知识星球** | 付费精品社区，提供完整部署教程、源码解析、创业经验分享 | ![知识星球](/.image/知识星球.jpg) |
| **微信社群** | 添加群主微信，备注"进技术交流群" | ![微信](/.image/微信.png) |
| **技术交流群** | 扫码直接入群，获取最新动态、技术答疑 | ![微信群](/.image/微信群.jpg) |

---

## 开源协议

本项目采用 **MIT License** 开源协议。

---

## 赞助支持

开源项目的发展离不开社区的支持。如果您觉得本项目对您有帮助，欢迎赞助支持持续开发！

<p align="center">
  <img src="./.image/微信收款.jpg" alt="微信支付" width="300">
  <img src="./.image/支付宝收款.jpg" alt="支付宝" width="300">
</p>

> 💡 请在备注中留下您的 GitHub ID，我们将列在赞助者名单中
---

## CPA 账号池接入

CPA 作为账号池反代层，new-api 仍然是唯一对外 API 出口和 Token 分发层。客户端不要直连 CPA。

部署步骤：

1. 进入 Docker 目录并复制 CPA 配置模板：
   ```bash
   cd script/docker
   cp cpa/config.example.yaml cpa/config.yaml
   ```
2. 修改 `cpa/config.yaml`：
   - `remote-management.secret-key`：CPA 管理后台登录密钥。
   - `api-keys`：给 new-api 渠道使用的 CPA API Key。
3. 启动 CPA：
   ```bash
   docker compose up -d cpa
   ```
4. 打开 **http://localhost:8317/management.html**，用管理密钥登录 CPA 后台。
5. 在 CPA 后台完成 OAuth 登录或导入合法持有的上游 Key。
6. 在 new-api 后台添加渠道：
   - 类型：OpenAI 或自定义 OpenAI 兼容渠道。
   - API 地址：`http://cpa:8317`。
   - 密钥：`cpa/config.yaml` 中 `api-keys` 的值。
   - 分组：默认 `default`，也可以按现有 new-api 分组配置。
   - 标签：建议填 `cpa`。
   - 模型：与 CPA 输出的模型名保持一致。

配置项：

- `CPA_PORT`：CPA 本机管理入口端口，默认 `8317`。
- `CPA_IMAGE`：CPA Docker 镜像，默认 `eceasy/cli-proxy-api:latest`。
- `script/docker/data/cpa/auths`：OAuth/账号授权数据目录，不要提交真实数据。
- `script/docker/logs/cpa`：CPA 日志目录。

排查顺序：先看 `docker compose logs -f cpa`，再确认 CPA API Key、模型名、Docker 网络和 new-api 模型价格配置。