# AgenticTokenHub

**Repository Path**: coderpans/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**: 6
- **Created**: 2026-08-31
- **Last Updated**: 2026-08-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<p align="center">
  <img src="https://img.shields.io/badge/Go-1.25%2B-00ADD8.svg" alt="Go">
  <img src="https://img.shields.io/badge/React-18-61DAFB.svg" alt="React">
  <img src="https://img.shields.io/badge/Docker-20.10%2B-2496ED.svg" alt="Docker">
  <img src="https://img.shields.io/badge/Agentic--auto-deterministic-7B61FF.svg" alt="Agentic auto">
</p>

# AgenticTokenHub - AI Token 中转与结算平台

**AgenticTokenHub** 是 Agentic 生态中的 **AI 能力与 Token 结算底座**。项目以 Go/Gin/GORM 实现的 `new-api` 为唯一运行时后端，对外提供 OpenAI 兼容 API、模型路由、Token 额度与流水、订阅套餐、用量统计、API Key 管理，以及面向 AgenticCPS 的签名 Token 兑换 OpenAPI。

> 运行时边界：`new-api` 同时负责 API、鉴权、持久化、扣费和审计；CLIProxyAPI（CPA）只是可选的上游账号池。客户端和 Agent 不应直接访问 CPA，也不再部署独立的 Java `billing-service`。

---

## Agentic 生态闭环定位

AgenticTokenHub 与另外两个项目形成能力闭环，但每个项目只维护自己的权威数据：

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

典型商业闭环：

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

### 统一集成原则

- **用户与租户一致**：跨系统请求携带 `userId`、`tenantId`、来源系统/订单和 `X-App-Id`、`X-Tenant-Id`。
- **资产只在归属系统变更**：Token、返利和积分均通过业务订单、幂等键、ledger 与审计流水流转，禁止跨系统直接改余额。
- **签名与防重放**：使用 HMAC-SHA256、`X-Timestamp`、`X-Nonce`、`X-Signature`；写操作必须带 `X-Idempotency-Key`。
- **MCP 只封装 OpenAPI**：工具不能绕过鉴权、限额、幂等、风控和审计。

---

## 平台简介

### 核心能力

| 能力 | 描述 |
|------|------|
| **多模型统一接入** | 通过 OpenAI 兼容入口接入 OpenAI、Claude、Gemini、DeepSeek 等供应商和自定义渠道 |
| **`agentic-auto` 路由** | 根据上下文、能力、健康度、质量下限、预算、成本和延迟确定性选择真实模型 |
| **Token 计费与流水** | 统一处理预扣、用量、成本、Token 额度、ledger 和审计记录 |
| **订阅套餐** | `new-api` 内置套餐目录、购买和管理员绑定接口，不依赖独立计费服务 |
| **CPS 返利兑换** | 提供预览、提交、确认扣减、查询和回滚的签名 Token exchange API |
| **CPA 账号池** | 可选接入 CLIProxyAPI 账号池，自动同步模型和聚合账号健康状态 |
| **运营与观测** | 模型目录、路由规则、决策记录、成本/路由/缓存指标和管理控制台 |

### 技术架构

```text
用户 / Agent
      │
      ▼
Nginx（反向代理、SSE、限速、SSL 入口）
      ├── /       → LobeChat（聊天界面）
      ├── /v1/    → new-api（OpenAI 兼容 API）
      └── /api/   → new-api（管理、订阅、Token exchange）
                         │
                         ├── TokenAuth / 限流 / 预扣 / 结算 / 审计
                         ├── agentic-auto 硬规则路由（可选）
                         ├── OpenAI / Claude / Gemini 等 relay
                         ├── CPA 账号池（可选内部上游）
                         └── SQLite（默认）或 MySQL / PostgreSQL
                              Redis（production profile 可选）
```

`new-api` 是唯一对外 API 和持久化归属服务。CLIProxyAPI（CPA）仅作为可选上游账号池，客户端不得直接调用。

| 组件 | 说明 | 默认端口 |
|---|---|---|
| **Nginx** | 对外反向代理、SSE 流式转发、限速和安全响应头 | 80 / 443 |
| **LobeChat** | 通过 new-api 调用模型的聊天前端 | 3210 |
| **new-api** | Go API 网关、模型渠道、Token、订阅和管理控制台 | 3000 |
| **CPA** | 可选 CLIProxyAPI 上游账号池，仅绑定本机管理/OAuth 端口 | 8317、8085、1455、54545、51121、11451 |
| **MySQL** | production profile 的可选持久化数据库 | 3306 |
| **Redis** | production profile 的可选缓存/限流组件 | 6379 |

---

## 目录结构

```text
AgenticTokenHub/
├── new-api-source/              # 唯一运行时后端（Go/Gin/GORM）
│   ├── router/                  # API、relay 和管理路由
│   ├── controller/              # 模型、路由、兑换和网关控制器
│   ├── service/                 # agentic-auto、预算、兑换状态机、签名校验
│   ├── model/                   # GORM 模型、迁移、Token ledger 和审计
│   ├── relay/                   # OpenAI、Claude、Gemini 等供应商适配器
│   ├── web/                     # React 管理控制台和用户界面
│   ├── Dockerfile               # Bun 构建前端并编译 Go 二进制
│   └── LICENSE                  # GNU AGPLv3
├── script/
│   ├── docker/                  # Docker Compose、Nginx、CPA 和数据库脚本
│   │   ├── docker-compose.yml   # 默认服务编排；production profile 含 MySQL/Redis
│   │   ├── docker-compose.cpa.yml # CPA 独立编排（可选）
│   │   ├── cpa/                 # CPA 配置模板和本地配置
│   │   ├── nginx/conf.d/        # 边缘代理配置
│   │   └── db-init/             # MySQL 初始化说明
│   └── shell/manage.bat         # Windows 菜单式管理脚本
├── docs/                        # 迁移、项目地图和开发说明
└── .image/                      # 社区与赞助图片
```

## 快速部署

```powershell
cd script/docker
# 仓库提供 .env 作为本地模板；部署前请替换默认密钥
notepad .env
docker compose up -d --build
docker compose ps
```

`SQL_DSN` 未设置或为 `local` 时使用 SQLite，数据写入 `script/docker/data/new-api`。
MySQL 和 PostgreSQL 可用于生产部署；Compose 的 `production` profile 会启动 MySQL 和 Redis：

```powershell
docker compose --profile production up -d --build
```

首次构建会在镜像内先用 Bun 构建 React 前端，再编译 Go 服务。生产环境请修改 `.env` 中的管理员初始密码、LobeChat 访问码、CPA API Key 和数据库密码，并不要提交真实密钥。

部署完成后可使用以下入口：

| 入口 | 地址 | 说明 |
|---|---|---|
| 聊天界面 | http://localhost | Nginx 代理到 LobeChat |
| LobeChat 直连 | http://localhost:3210 | 容器端口直连 |
| new-api 控制台 | http://localhost:3000 | 管理、渠道、令牌和订阅 |
| 订阅套餐页 | http://localhost:3000/plans | new-api 内置订阅页面 |
| CPA 管理台 | http://localhost:8317/management.html | 启用 CPA 后使用，仅本机绑定 |
| OpenAI 兼容 API | http://localhost/v1/chat/completions | 经 Nginx 的统一 API 入口 |

## API 与集成

```text
POST /v1/chat/completions                  OpenAI 兼容对话接口
GET  /v1/models                            包含虚拟模型 agentic-auto
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
```

Agentic 管理接口使用 RootAuth：

```text
/api/agentic/models
/api/agentic/rules
/api/agentic/route-decisions
/api/agentic/explain/{requestId}
/api/agentic/metrics/{cost,routing,cache}
/api/agentic/cpa/status
/api/agentic/cpa/sync
```

CPA 可在 new-api 控制台的 `/console/cpa` 查看。服务启动及定时同步时，Go `CPAClient` 会检查 `/healthz`、读取 OpenAI 兼容的 `/v1/models`，聚合受保护的账号列表，并维护 `cpa-managed` 渠道和 Agentic 模型目录。可在 Compose 环境中设置 `CPA_ENABLED`、`CPA_BASE_URL`、`CPA_API_KEY` 和可选的 `CPA_MANAGEMENT_KEY`；管理密钥只在服务端使用，OAuth 文件和上游凭据不会进入 new-api 数据库或浏览器。

兑换接口要求 `X-App-Id`、`X-Tenant-Id`、`X-Timestamp`、`X-Nonce`、`X-Signature` 和 `X-Idempotency-Key`。签名使用 HMAC-SHA256 与请求体哈希；重复幂等键返回原订单，重复 source order 会被拒绝。

## `agentic-auto` MVP

请求 `model: "agentic-auto"` 时，路由器按上下文、能力、质量下限、预算、健康度、成本和延迟等硬约束确定性选择模型；MVP 不依赖额外分类器或强化学习。模型目录包含上下文窗口、输入/输出价格、缓存价格、延迟、质量等级、健康度、并发度和版本。

每次决策都会持久化候选、拒绝原因、预算、预估成本、解析模型、压缩状态、升级状态和最终结果。

## CPS Token exchange 状态机

```text
pending -> credited -> confirmed
pending -> failed
credited -> rollback_required
```

重复幂等键返回原订单，重复 source order 会被拒绝。Token 入账、ledger、用户额度更新和审计记录在同一数据库事务中原子提交。

## 数据与迁移

Java `billing-service` 运行时与 `ai_token_platform` 初始化 schema 已移除。已有安装在切换到 Go 服务前应先完成旧数据备份、校验、导入和回滚准备；当前仓库不再提供 Java 服务的兼容运行入口。

- `SQL_DSN` 未设置或为 `local` 时使用 SQLite，数据写入 `script/docker/data/new-api`。
- 可配置 MySQL 或 PostgreSQL；Compose 的 `production` profile 会启动 MySQL 和 Redis。
- new-api 通过 GORM AutoMigrate 管理用户、订阅、模型目录、路由决策、兑换订单、Token ledger 和审计表。
- `script/docker/db-init/` 只包含 MySQL 初始化设置，不会重新创建旧的 `ai_token_platform` 数据库。

## 开发与验证

```powershell
cd new-api-source
go test ./...
go build -o new-api

cd web
bun run lint
bun run build
```

CPA 配置及 OAuth/账号数据属于本地运行时状态，尤其是 `script/docker/data/cpa/auths` 和日志目录，禁止提交真实内容。

---

## CPA 账号池接入（可选）

CPA 是内部上游账号池，new-api 仍是唯一对外 API 和 Token 分发层。启用 CPA 前先准备配置：

```powershell
cd script/docker
Copy-Item cpa/config.example.yaml cpa/config.yaml
# 编辑 cpa/config.yaml 中的 remote-management.secret-key 和 api-keys
docker compose up -d cpa
```

访问 **http://localhost:8317/management.html** 完成 OAuth 或导入合法持有的上游 Key。new-api 会通过 `CPA_BASE_URL`、`CPA_API_KEY` 定期读取 `/healthz` 和 `/v1/models`，聚合管理账号状态，并维护一个 `cpa-managed` 渠道及 Agentic 模型目录。

| 配置项 | 说明 |
|---|---|
| `CPA_ENABLED` | 是否启用 new-api 的 CPA 同步，默认 `true` |
| `CPA_BASE_URL` | 容器内地址，默认 `http://cpa:8317` |
| `CPA_API_KEY` | 必须与 CPA `api-keys` 中的值匹配 |
| `CPA_MANAGEMENT_KEY` | 可选，必须与 `remote-management.secret-key` 匹配 |
| `CPA_SYNC_INTERVAL_SECONDS` | 同步间隔，默认 60 秒 |
| `script/docker/data/cpa/auths` | OAuth/账号授权数据，不要提交真实内容 |

需要独立运行 CPA 时可使用 `docker-compose.cpa.yml`：

```powershell
cd script/docker
docker compose -f docker-compose.cpa.yml up -d
```

---

## Nginx 配置要点

| 特性 | 当前配置 |
|---|---|
| SSE 流式输出 | `/` 与 `/v1/` 使用 `proxy_buffering off` |
| WebSocket | 转发 `Upgrade` 与 `Connection` 头 |
| AI 超时 | `proxy_read_timeout 300s` |
| API 限速 | `/v1/` 约 30 次/分钟，`/api/` 约 30 次/分钟（可调整） |
| 聊天限速 | `/` 约 60 次/分钟 |
| 文件上传 | `client_max_body_size 50m` |
| 安全头 | X-Frame-Options、X-Content-Type-Options、Referrer-Policy |

仓库提供的 `default.conf` 默认监听 HTTP 80 端口。启用 HTTPS 时，请在 `script/docker/nginx/ssl/` 放置证书并按实际域名补充 HTTPS server 配置，再重启 Nginx。

---

## 管理脚本

Windows 可运行 `script/shell/manage.bat`，菜单包括：

```text
1. 启动服务              5. 查看日志
2. 停止服务              6. 启动生产依赖（MySQL + Redis profile）
3. 重启服务              7. 重新构建并启动
4. 查看状态              8. 清理容器（不删除数据卷）
0. 退出
```

---

## 常用命令

```powershell
# 启动默认服务
cd script/docker
docker compose up -d

# 查看状态和日志
docker compose ps
docker compose logs -f --tail=100
docker compose logs -f new-api
docker compose logs -f cpa

# 重建单个服务
docker compose up -d --build new-api
docker compose restart lobe-chat

# 启动 MySQL + Redis production profile
docker compose --profile production up -d

# 健康检查
curl http://localhost:3000/api/status
curl http://localhost:8317/healthz

# 本地开发验证
cd ../../new-api-source
go test ./...
go build -o new-api
cd web
bun install
bun run lint
bun run build
cd ../../script/docker
docker compose config
```

---

## 技术栈

| 层级 | 技术 |
|---|---|
| 后端 | Go 1.25+、Gin、GORM、SQLite / MySQL / PostgreSQL |
| 前端 | React 18、Vite、Semi UI、Ant Design、Bun |
| 网关 | Nginx 1.25、OpenAI 兼容 API、SSE / WebSocket |
| 上游适配 | OpenAI、Claude、Gemini 及其他 relay 渠道 |
| 可选基础设施 | CLIProxyAPI（CPA）、Redis 7、MySQL 8 |

---

## 交流社区

欢迎加入 **AgenticTokenHub 开发者社区**，与 AI 服务开发者和 Agentic 生态参与者交流部署与集成经验。

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

---

## 开源协议

`new-api-source` 使用 **GNU Affero General Public License v3.0（AGPLv3）**，详见 [new-api-source/LICENSE](new-api-source/LICENSE)。CPA、LobeChat 和各模型供应商遵循其各自的许可证与服务条款。

---

## 赞助支持

开源项目的发展离不开社区支持。如果项目对你有帮助，欢迎赞助持续开发：

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

> 请在备注中留下您的 GitHub ID，便于记录赞助信息。