PinAI - 轻量级大语言模型路由网关

PinAI 是一个基于 Go 语言开发的轻量级大语言模型路由网关，专为简化访问各种大语言模型（LLM）而设计。目前项目支持 OpenAI、Anthropic 和 Gemini 兼容的 API 格式，可以轻松集成到您的 AI 应用中。

[!IMPORTANT]

本项目仅供个人学习使用，不保证稳定性，且不提供任何技术支持。

根据《生成式人工智能服务管理暂行办法》的要求，请勿对中国地区公众提供一切未经备案的生成式人工智能服务。

🖥️ 前端项目

本项目为后端服务，配套前端项目请访问：

• 前端仓库：pinai-frontend
• 在线演示：https://pinai-frontend.pages.dev

🌟 特性

• 轻量级架构：基于 Go 语言和 Gin 框架构建，性能优异，资源占用少
• 多平台兼容：完全兼容 OpenAI、Anthropic 和 Gemini API 格式，可直接替换现有调用
• 多模型支持：支持多种大语言模型的统一访问和管理
• 模型映射：支持自定义模型名称映射，统一不同平台的模型名称
• 流式响应：完整支持流式响应，提供实时交互体验
• 健康状态管理：支持平台、密钥、模型的健康状态监控和管理
• 请求统计与仪表盘：提供概览、实时统计、调用排行、用量排行、请求日志与仪表盘接口
• 原生透传能力：支持 /multi/native/* 原生接口，保留上游响应格式
• 请求头透传：支持将客户端 HTTP 请求头透传到上游请求
• 可控代理能力：可按配置启用 /api/proxy 管理代理端点
• 多数据库支持：支持 SQLite（默认）、MySQL 和 PostgreSQL 数据库
• 数据库 TLS 支持：支持 MySQL 和 PostgreSQL 数据库的 TLS 加密连接
• 易于部署：提供 Docker 镜像，支持容器化部署

🚀 快速开始

使用 Docker（推荐）

# 拉取并运行最新版本（自行设置 token）
docker run -d \
  -p 3000:3000 \
  -e ENABLE_WEB=true \
  -e API_TOKEN=<业务token> \
  -e ADMIN_TOKEN=<管理token> \
  ghcr.io/meowsalty/pinai:latest

如果需要持久化数据，请将 PinAI 的数据目录 /app/data 映射到宿主机的目录

本地运行

# 克隆项目
git clone https://github.com/MeowSalty/pinai.git
cd pinai

# 运行项目
go run app.go -api-token=<业务token> -admin-token=<管理token> -enable-web=true

服务默认在 http://localhost:3000 上运行。

🛠️ 配置选项

PinAI 支持多种配置选项，可以通过命令行参数或环境变量进行设置：

配置参数说明

命令行参数	环境变量	说明	默认值
-port	PORT	监听端口	:3000
-prod	PROD	在生产环境中启用 prefork 模式	false
-enable-web	ENABLE_WEB	启用前端支持	false
-web-dir	WEB_DIR	前端文件目录	web
-enable-frontend-update	ENABLE_FRONTEND_UPDATE	启用前端更新检查	true
-passthrough-headers	PASSTHROUGH_HEADERS	是否透传 HTTP 请求头到上游 portal 请求	true
-github-proxy	GITHUB_PROXY	GitHub 代理地址，用于加速 GitHub 访问
-proxy-enabled	PROXY_ENABLED	启用管理代理端点 /api/proxy（仍需配置 ADMIN_TOKEN）	false
-db-type	DB_TYPE	数据库类型 (sqlite, mysql, postgres)	sqlite
-db-host	DB_HOST	数据库主机地址
-db-port	DB_PORT	数据库端口
-db-user	DB_USER	数据库用户名
-db-pass	DB_PASS	数据库密码
-db-name	DB_NAME	数据库名称
-db-ssl-mode	DB_SSL_MODE	PostgreSQL SSL 模式 (disable, require, verify-ca, verify-full)	disable
-db-tls-config	DB_TLS_CONFIG	MySQL TLS 配置 (true, false, skip-verify, preferred)	false
-api-token	API_TOKEN	API Token，用于业务接口身份验证
-admin-token	ADMIN_TOKEN	管理 API Token，用于管理接口身份验证（可选）
-model-mapping	MODEL_MAPPING	模型映射规则，格式：key1:value1,key2:value2
-user-agent	USER_AGENT	User-Agent 配置（见下方说明）	空（透传）
-log-level	LOG_LEVEL	日志输出等级 (DEBUG, INFO, WARN, ERROR)	INFO

[!NOTE]

• 命令行参数优先级高于环境变量。
• 如果只设置了 API_TOKEN 而没有设置 ADMIN_TOKEN，则管理接口和业务接口将使用相同的令牌，程序启动时会输出警告。
• 业务接口包括 /openai/v1/*、/anthropic/v1/* 和 /multi/*，管理接口指 /api/* 路径下的接口。

请求头透传配置说明

通过 -passthrough-headers 或 PASSTHROUGH_HEADERS 可控制是否将客户端请求头透传到上游请求，默认开启。

• true：透传客户端请求头，便于保留调用方上下文
• false：不透传客户端请求头，仅发送服务端构造的上游请求头

[!NOTE]

• 该配置主要作用于 /multi 统一网关转发流程。
• 建议在需要精细控制上游请求头时关闭此选项。

代理功能配置说明

通过 -proxy-enabled 或 PROXY_ENABLED 可以显式启用管理代理接口。

• 仅当 PROXY_ENABLED=true 且已配置 ADMIN_TOKEN 时，才会注册 POST /api/proxy
• 适合用于后端代发管理类请求或临时调试上游接口

[!NOTE]

• 代理接口属于管理接口，不使用 API_TOKEN，而是使用 ADMIN_TOKEN 认证。
• 默认不启用，避免在未评估风险时暴露通用代理能力。

数据库 TLS 配置说明

• PostgreSQL 使用 -db-ssl-mode 参数：
• disable: 禁用 SSL
• require: 要求 SSL（不验证证书）
• verify-ca: 验证证书颁发机构

• verify-full: 完全验证证书（主机名和颁发机构）

• MySQL 使用 -db-tls-config 参数：

• true: 启用 SSL
• false: 禁用 SSL
• skip-verify: 启用 SSL 但跳过证书验证
• preferred: 优先使用 SSL，如果服务器不支持则回退到非加密连接

模型映射配置说明

模型映射功能允许您将客户端请求的模型名称映射到实际使用的模型名称。这在以下场景中非常有用：

• 将 AI 应用中固定访问的模型名称映射到拼好 AI 中的模型名称

配置格式：原始模型名:目标模型名,原始模型名2:目标模型名2

示例：

如果需要在 Claude Code 中使用 DeepSeek 模型，您可以将模型映射规则设置为：claude-sonnet-4-20250514:deepseek-v3

# 命令行方式
./pinai -model-mapping="claude-sonnet-4-20250514:deepseek-v3"

# 环境变量方式
export MODEL_MAPPING="claude-sonnet-4-20250514:deepseek-v3"
./pinai

# Docker 方式
docker run -d \
  -p 3000:3000 \
  -e MODEL_MAPPING="claude-sonnet-4-20250514:deepseek-v3" \
  ghcr.io/meowsalty/pinai:latest

[!NOTE]

• 如果不配置模型映射规则，将不会进行任何模型名称转换
• 映射规则区分大小写
• 只有在映射规则中定义的模型才会被转换，未定义的模型将保持原名称

GitHub 代理配置说明

如果您在访问 GitHub 时遇到网络问题，可以使用 GitHub 代理来加速前端文件的下载和更新。配置方法：

# 命令行方式
./pinai -enable-web=true -github-proxy=[GitHub 加速地址]

# 环境变量方式
export GITHUB_PROXY=[GitHub 加速地址]
./pinai -enable-web=true

# Docker 方式
docker run -d \
  -p 3000:3000 \
  -e ENABLE_WEB=true \
  -e GITHUB_PROXY=[GitHub 加速地址] \
  ghcr.io/meowsalty/pinai:latest

代理工作原理：

• 原始地址：https://api.github.com/repos/...
• 使用代理后：[GitHub 加速地址]/https://api.github.com/repos/...

[!NOTE]

• 代理服务仅用于加速 GitHub 访问，不会影响其他功能
• 请选择可信的代理服务，避免使用不明来源的代理
• 如果不设置此参数，将直接访问 GitHub

User-Agent 配置说明

User-Agent 配置用于控制向上游 AI 服务发送请求时的 User-Agent 头部。支持三种模式：

1. 透传模式（默认）：不设置或设置为空字符串时，将透传客户端请求的 User-Agent
2. 默认模式：设置为 "default" 时，不添加 User-Agent 头部，使用 Go net/http 的默认值
3. 自定义模式：设置为其他任意字符串时，使用该字符串作为 User-Agent

配置示例：

# 命令行方式 - 透传客户端 User-Agent（默认行为）
./pinai

# 命令行方式 - 使用 fasthttp 默认 User-Agent
./pinai -user-agent="default"

# 命令行方式 - 自定义 User-Agent
./pinai -user-agent="MyCustomAgent/1.0"

# 环境变量方式
export USER_AGENT="MyCustomAgent/1.0"
./pinai

# Docker 方式
docker run -d \
  -p 3000:3000 \
  -e USER_AGENT="MyCustomAgent/1.0" \
  ghcr.io/meowsalty/pinai:latest

[!NOTE]

• User-Agent 配置对 OpenAI、Anthropic 和 Gemini 兼容接口均有效
• 透传模式可以保留客户端的原始 User-Agent 信息
• 自定义模式适用于需要统一标识的场景

📚 API 接口

PinAI 提供以下平台兼容的 API 接口：

代理接口

基础路径：/api

• POST /api/proxy - 通过后端代理访问任意上游端点

启用条件：需要同时满足 PROXY_ENABLED=true 与已配置 ADMIN_TOKEN

认证方式：使用 Authorization: Bearer <ADMIN_TOKEN> 头进行身份验证

使用示例（获取 OpenAI 模型列表）：

curl https://your-domain.com/api/proxy \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.openai.com/v1/models",
    "method": "GET",
    "headers": {
      "Authorization": "Bearer YOUR_UPSTREAM_TOKEN"
    }
  }'

Provider 管理接口

Provider 管理接口用于管理 LLM 供应商的平台、模型、密钥和端点。

认证方式：使用 Authorization: Bearer <ADMIN_TOKEN> 头进行身份验证

平台管理

方法	路径	说明
POST	/api/platforms	创建平台
GET	/api/platforms	获取平台列表
GET	/api/platforms/:platformId	获取平台详情
PUT	/api/platforms/:platformId	更新平台
DELETE	/api/platforms/:platformId	删除平台
PATCH	/api/platforms/:platformId/health	更新平台健康状态

模型管理

方法	路径	说明
POST	/api/platforms/:platformId/models	添加模型
POST	/api/platforms/:platformId/models/batch	批量添加模型
GET	/api/platforms/:platformId/models	获取平台模型列表
PUT	/api/platforms/:platformId/models/batch	批量更新模型
DELETE	/api/platforms/:platformId/models/batch	批量删除模型
PUT	/api/models/:modelId	更新模型
DELETE	/api/models/:modelId	删除模型
PATCH	/api/models/:modelId/health	更新模型健康状态

密钥管理

方法	路径	说明
POST	/api/platforms/:platformId/keys	添加密钥
GET	/api/platforms/:platformId/keys	获取平台密钥列表
PUT	/api/keys/:keyId	更新密钥
DELETE	/api/keys/:keyId	删除密钥
PATCH	/api/keys/:keyId/health	更新密钥健康状态

端点管理

方法	路径	说明
POST	/api/platforms/:platformId/endpoints	添加端点
POST	/api/platforms/:platformId/endpoints/batch	批量添加端点
GET	/api/platforms/:platformId/endpoints	获取平台端点列表
PUT	/api/platforms/:platformId/endpoints/batch	批量更新端点
GET	/api/endpoints/:endpointId	获取端点详情
PUT	/api/endpoints/:endpointId	更新端点
DELETE	/api/endpoints/:endpointId	删除端点

统计接口

统计接口用于查看 API 使用情况和请求日志。

认证方式：使用 Authorization: Bearer <ADMIN_TOKEN> 头进行身份验证

方法	路径	说明
GET	/api/stats/dashboard	获取统计仪表盘
GET	/api/stats/overview	获取统计概览
GET	/api/stats/requests	获取请求日志列表
GET	/api/stats/realtime	获取实时统计
GET	/api/stats/models/call-rank	获取模型调用排名
GET	/api/stats/platforms/call-rank	获取平台调用排名
GET	/api/stats/models/usage-rank	获取模型使用量排名
GET	/api/stats/platforms/usage-rank	获取平台使用量排名

健康状态接口

健康状态接口用于监控和管理平台、密钥、模型的健康状态。

认证方式：使用 Authorization: Bearer <ADMIN_TOKEN> 头进行身份验证

方法	路径	说明
GET	/api/health/summary	获取健康状态摘要
GET	/api/health/issues	获取异常资源列表
GET	/api/health/platforms	获取平台健康状态列表
GET	/api/health/keys	获取密钥健康状态列表
GET	/api/health/models	获取模型健康状态列表

Multi 接口

Multi 接口是一个统一的 API 网关，支持 OpenAI、Anthropic 和 Gemini 三种 API 格式。系统根据请求路径、查询参数或请求头自动识别所需格式。

提供两种接口模式：

模式	路径前缀	说明
兼容接口	/multi/v1、/multi/v1beta	自动转换请求/响应格式，适合跨平台调用
原生接口	/multi/native/v1、/multi/native/v1beta	直接透传请求，不进行格式转换，保留原始 API 响应

接口列表

OpenAI 格式：

• GET /multi/v1/models 或 GET /multi/native/v1/models - 获取模型列表
• POST /multi/v1/chat/completions 或 POST /multi/native/v1/chat/completions - 聊天补全
• POST /multi/v1/responses 或 POST /multi/native/v1/responses - Responses API

Anthropic 格式：

• GET /multi/v1/models 或 GET /multi/native/v1/models - 获取模型列表
• POST /multi/v1/messages 或 POST /multi/native/v1/messages - 消息补全

Gemini 格式：

• GET /multi/v1beta/models 或 GET /multi/native/v1beta/models - 获取模型列表
• POST /multi/v1beta/models/{model}:generateContent 或 POST /multi/native/v1beta/models/{model}:generateContent - 生成内容
• POST /multi/v1beta/models/{model}:streamGenerateContent 或 POST /multi/native/v1beta/models/{model}:streamGenerateContent - 流式生成

认证方式

接口类型	认证方式	说明
OpenAI	Authorization: Bearer <API_TOKEN>	Bearer Token 认证
Anthropic	x-api-key: <API_TOKEN>	需同时携带 anthropic-version 头
Gemini	x-goog-api-key: <API_TOKEN> 或 ?key=<API_TOKEN>	请求头或查询参数

Provider 识别规则

系统按以下优先级识别请求的 Provider：

1. 路径识别：根据请求路径自动识别
2. /chat/completions、/responses → OpenAI
3. /messages → Anthropic

4. /generateContent、/streamGenerateContent、/v1beta/models → Gemini

5. 查询参数：?provider=openai|anthropic|gemini

6. 请求头识别：

7. 同时携带 x-api-key 和 anthropic-version → Anthropic
8. 携带 x-goog-api-key 或 key 查询参数 → Gemini
9. 默认 → OpenAI

使用示例

OpenAI 格式：

curl https://your-domain.com/multi/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "model": "gpt-4",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

**A