星空 AI / ai-getaway

星空 AI 是一个轻量级 AI API 中转与运营系统，后端使用 Go + Gin + GORM，前端使用 Vue 3 + Vite。项目面向 OpenAI-compatible 接入场景，提供用户注册登录、套餐订阅、余额充值、API Key 管理、模型计价、上游渠道管理、调用日志、公告文档、支付审核和渠道监控等能力。

当前仓库包含 Go 后端和 Vue 前端。后端入口位于仓库根目录 main.go，前端位于 frontend/。

功能概览

OpenAI-compatible API 代理：支持 /v1/* 路径转发和 /messages 兼容入口。
多上游接入：支持用户独立上游、公共渠道、轮询号池、余额专用渠道。
GPT / Claude 协议标记：渠道、公共渠道、号池账号均可声明支持协议。
用户体系：注册、登录、JWT 会话、邮箱验证码、滑块验证码、密码修改。
第三方登录：支持 GitHub、Google OAuth 的登录、绑定、解绑。
套餐体系：日套餐、周/月订阅、公共套餐、余额套餐、免费套餐、抽奖套餐。
订单流程：在线支付、人工支付、管理员审核、拒绝、关闭、订单超时清理。
余额模式：余额充值后按调用成本扣费，可选择公开可用的分组倍率。
模型计价：按 token 或按请求计费，支持缓存输入、输出、倍率、精选模型展示。
分组倍率：后台可维护计费分组，并绑定到渠道、用户上游或余额通道。
API Key 管理：用户创建、查看、轮换、启用、禁用，后台可管理全部 Key。
用量统计：记录请求模型、token、估算成本、延迟、首 token 时间和错误信息。
公告与文档：后台维护 Markdown 文档和公告，前台展示教程、历史公告和模型列表。
渠道监控：定时探测监控地址，前台展示可用、降级、不可用状态和延迟。
管理后台：用户、订单、套餐、兑换码、模型、渠道、号池、设置、邮件模板等管理。
集群辅助：实例注册、内部节点信息、节点日志、后台任务分布式锁。

技术栈

模块	技术
后端	Go 1.21、Gin、GORM
数据库	MariaDB / MySQL
缓存与锁	Redis
前端	Vue 3、Vite、Pinia、Element Plus、TailwindCSS
文档编辑	Markdown / wangEditor
认证	JWT、邮箱验证码、OAuth
支付	易支付接口、人工收款审核

项目结构

.
├── main.go                 # Gin 服务入口
├── config/                 # 环境变量、配置加载与生产校验
├── database/               # MariaDB、Redis 初始化，自动迁移，初始化数据，后台清理任务
├── router/                 # HTTP 路由、CORS、健康检查、集群内部接口
├── middleware/             # JWT 鉴权、管理员鉴权、API Key 鉴权、限流
├── controller/             # API 控制器
├── service/                # 业务服务、额度、邮件、OAuth、监控、集群等逻辑
├── model/                  # GORM 数据模型
├── upstream/               # OpenAI-compatible / Claude-compatible 上游代理
├── response/               # 统一响应封装
├── utils/                  # 密码、加密、辅助方法
├── scripts/                # 辅助脚本
├── logs/                   # 本地运行日志目录
├── md/                     # 项目说明文档
├── frontend/               # Vue 前端项目
└── 部署流程.md             # 部署流程说明

运行环境

Windows / Linux 均可运行，本地开发建议使用 Windows PowerShell 或 Bash。
Go 1.21+
Node.js 18+
MariaDB 10.5+ 或 MySQL 8+
Redis 6+

创建数据库：

CREATE DATABASE ai_gateway CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

复制环境变量：

Copy-Item .env.example .env

如果手写 MariaDB DSN，loc=Asia/Shanghai 需要写成 loc=Asia%2FShanghai。

环境变量

变量	默认值	说明
`APP_ENV`	`development`	运行环境。生产环境填 `production` 后会启用关键配置校验。
`APP_PORT`	`8080`	后端监听端口。
`DB_DSN`	示例 DSN	MariaDB / MySQL 连接串。
`REDIS_ADDR`	`127.0.0.1:6379`	Redis 地址。
`REDIS_PASSWORD`	空	Redis 密码。
`REDIS_DB`	`0`	Redis DB 编号。
`JWT_SECRET`	示例值	JWT 签名密钥，生产环境必须修改。
`DEFAULT_ADMIN_EMAIL`	`admin@example.com`	首次启动自动创建的管理员邮箱。
`DEFAULT_ADMIN_PASSWORD`	`admin123456`	首次启动自动创建的管理员密码，生产环境必须修改。
`UPSTREAM_TIMEOUT`	`120s`	请求上游接口超时时间。
`MAX_PROXY_BODY_BYTES`	`10485760`	代理请求体最大字节数。
`MAX_SSE_USAGE_BUFFER_BYTES`	`1048576`	SSE 统计用缓冲区大小。
`API_KEY_RATE_LIMIT_PER_MINUTE`	`120`	单个 API Key 分钟级限流。
`PUBLIC_BASE_URL`	示例域名	对外访问域名，生产环境必填，用于支付回调等场景。
`ALLOWED_ORIGINS`	示例域名	CORS 允许来源，生产环境不能使用通配符。
`CLUSTER_MODE`	`false`	是否启用集群模式。
`INSTANCE_ID`	自动生成	当前实例 ID。
`INSTANCE_ADVERTISE_URL`	`http://127.0.0.1:8080`	当前实例对内通告地址。
`CLUSTER_INTERNAL_TOKEN`	JWT 密钥	集群内部接口访问令牌。
`RUN_BACKGROUND_JOBS`	`true`	是否运行后台任务。多实例部署时可配合集群锁。

生产环境会强制检查：JWT_SECRET、DEFAULT_ADMIN_PASSWORD、PUBLIC_BASE_URL 和 ALLOWED_ORIGINS，避免使用默认密钥、默认密码或通配符 CORS。

后端启动

go mod tidy
go run .

首次启动会自动迁移数据表、初始化默认套餐、内置文档、邮件模板和默认管理员账号。

健康检查：

Invoke-WebRequest http://127.0.0.1:8080/health
Invoke-WebRequest http://127.0.0.1:8080/ready

前端启动

Set-Location frontend
npm install
npm run dev

Vite 开发服务会将 /api 转发到后端。

构建与测试

后端构建：

go build .

后端测试：

$env:GOCACHE='D:\python\ai-getaway\.gocache'
$env:GOMODCACHE='D:\python\ai-getaway\.gomodcache'
go test ./...

前端生产构建：

Set-Location frontend
npm run build

如果本机 npm 全局入口异常，可以直接使用项目本地 Vite 入口完成等价构建：

Set-Location frontend
node node_modules\vite\bin\vite.js build

仓库也提供 Windows 发布脚本：

.\build-release.bat

脚本会构建 Linux amd64 后端二进制 ai-getaway-linux-amd64，并生成 frontend/dist/。

核心业务流程

套餐订阅流程

用户注册并登录。
用户在定价页选择套餐。
系统创建订单，订单初始状态为 pending_payment。
用户选择在线支付或人工支付。
在线支付回调或用户主动标记已支付后，订单进入审核或自动完成流程。
管理员审核通过后，用户状态变为 approved，套餐、额度周期和过期时间生效。
管理员为用户绑定上游账号或用户使用公共/余额通道。

余额扣费流程

用户选择余额充值套餐或自定义充值金额。
支付完成并经审核后，余额以 USD cents 计入用户账户。
用户没有可用订阅或配置了余额访问时，请求可走余额通道。
实际扣费按模型基础计价、模型倍率、分组倍率和 token / request 统计计算。

API 调用流程

用户在控制台创建平台 API Key。
客户端使用 Authorization: Bearer ag_xxx 请求 /v1/* 或 /messages。
中间件校验 API Key、用户状态、套餐/余额、限流和额度预留。
代理层选择用户上游、公共渠道、余额通道或轮询号池账号。
网关将平台 Key 替换为上游 API Key，并转发请求。
系统记录调用日志、token 用量、估算成本、延迟和错误信息。

API 路由概览

公开接口

方法	路径	说明
`GET`	`/health`	基础健康检查。
`GET`	`/ready`	数据库、Redis、集群就绪检查。
`GET`	`/api/settings/public`	前台公开配置。
`POST`	`/api/captcha/slide`	创建滑块验证码。
`POST`	`/api/auth/email-code`	发送邮箱验证码。
`POST`	`/api/auth/register`	注册账号。
`POST`	`/api/auth/login`	登录账号。
`GET`	`/api/auth/oauth/:provider/start`	OAuth 登录跳转。
`GET`	`/api/auth/oauth/:provider/callback`	OAuth 登录回调。
`GET`	`/api/plans`	前台套餐列表。
`GET`	`/api/models`	前台模型列表。
`GET`	`/api/docs`	前台文档列表。
`GET`	`/api/docs/:slug`	文档详情。
`GET`	`/api/announcements`	公告列表。
`GET`	`/api/status/monitors`	渠道监控状态。
`GET`	`/api/payment/manual`	人工支付配置。
`ANY`	`/api/payment/epay/notify`	易支付异步通知。
`ANY`	`/v1/*path`	OpenAI-compatible 代理入口。
`ANY`	`/messages`	Messages 兼容代理入口。

登录用户接口

方法	路径	说明
`GET`	`/api/auth/me`	当前用户信息。
`PATCH`	`/api/auth/password`	修改密码。
`GET`	`/api/auth/oauth/accounts`	已绑定 OAuth 账号。
`GET`	`/api/auth/oauth/:provider/bind`	发起 OAuth 绑定。
`DELETE`	`/api/auth/oauth/:provider`	解绑 OAuth 账号。
`GET`	`/api/balance/billing-groups`	可选余额计费分组。
`PUT`	`/api/balance/billing-group`	更新余额计费分组。
`POST`	`/api/orders`	创建套餐订单。
`POST`	`/api/balance/recharge`	创建余额充值订单。
`GET`	`/api/orders`	我的订单。
`POST`	`/api/orders/:id/pay`	获取在线支付链接。
`POST`	`/api/orders/:id/manual-payment`	提交人工付款信息。
`PATCH`	`/api/orders/:id/paid`	用户标记在线订单已支付。
`POST`	`/api/redeem-codes/redeem`	兑换套餐码。
`POST`	`/api/endpoint-speed`	测试线路速度。
`GET`	`/api/keys/secret`	查看当前用户密钥辅助信息。
`GET`	`/api/keys`	API Key 列表。
`POST`	`/api/keys`	创建 API Key。
`POST`	`/api/keys/rotate`	轮换 API Key。
`PATCH`	`/api/keys/:id/disable`	禁用 API Key。
`PATCH`	`/api/keys/:id/enable`	启用 API Key。
`GET`	`/api/usage/logs`	当前用户调用日志。

管理员接口

管理员接口均位于 /api/admin 下，需要登录且角色为 admin。

模块	主要路径
用户管理	`/users`、`/users/:id`、`/users/:id/upstream`、`/users/:id/upstreams/:access_type`、`/users/reset-quota-batch`
订单审核	`/orders`、`/orders/:id/approve`、`/orders/:id/reject`、`/orders/:id/close`、`/orders/:id/complete-payment`
套餐管理	`/plans`、`/plans/:id`、`/plans/:id/draw-lottery`
兑换码	`/redeem-codes`、`/redeem-codes/:id/disable`
系统设置	`/settings`、`/settings/test-smtp`
邮件模板	`/email-templates`、`/email-templates/:type`
文档管理	`/docs`、`/docs/:id`
公告管理	`/announcements`、`/announcements/:id`
模型管理	`/models`、`/models/:id`、`/models/sync-official`
分组倍率	`/billing-groups`、`/billing-groups/:id`
上游渠道	`/upstream-channels`、`/upstream-channels/:id`
公共渠道	`/public-channels`、`/public-channels/:id`
轮询号池	`/polling-pools`、`/polling-pools/:id`
OpenAI OAuth 导入	`/openai-oauth/auth-url`、`/openai-oauth/exchange-code`、`/openai-oauth/refresh-token`
渠道监控	`/channel-monitors`、`/channel-monitors/:id`、`/channel-monitors/:id/ping`
API Key 管理	`/keys`、`/keys/:id`
使用记录	`/usage/logs`
运营统计	`/stats`
实时日志	`/logs/ws`
负载均衡	`/load-balancer/nodes`、`/load-balancer/nodes/:id/ping`、`/load-balancer/nodes/:id/logs`

集群内部接口

方法	路径	说明
`GET`	`/internal/cluster/info`	当前节点信息，需要 `X-Cluster-Token`。
`GET`	`/internal/cluster/logs`	当前节点运行日志，需要 `X-Cluster-Token`。

OpenAI-compatible 调用示例

普通请求：

curl.exe http://127.0.0.1:8080/v1/chat/completions `
  -H "Authorization: Bearer ag_xxx" `
  -H "Content-Type: application/json" `
  -d "{\"model\":\"gpt-4o-mini\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}"

流式请求：

curl.exe http://127.0.0.1:8080/v1/chat/completions `
  -H "Authorization: Bearer ag_xxx" `
  -H "Content-Type: application/json" `
  -d "{\"model\":\"gpt-4o-mini\",\"stream\":true,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}"

客户端配置通常填写：

Base URL: https://your-domain.example/v1
API Key: ag_xxx
Model: 后台启用的模型 ID

后台配置建议

首次登录后台后建议按顺序配置：

修改默认管理员密码，并确认 .env 中默认密码不再使用弱口令。
在系统设置中配置站点标题、联系邮箱、导航、支付方式、SMTP 和 OAuth。
在模型管理中新增或同步模型计价，确认模型 ID 与上游一致。
在分组倍率中创建默认倍率和不同渠道倍率。
在渠道管理中配置上游渠道、公共渠道或轮询号池账号。
在套餐管理中配置订阅套餐、公共套餐、余额套餐、免费套餐或抽奖套餐。
在文档和公告中维护前台用户可见的接入教程和服务通知。
在渠道监控中添加上游健康检查地址。

支付说明

系统支持在线支付和人工支付。在线支付通过易支付参数生成跳转链接，异步通知路径为 /api/payment/epay/notify；人工支付由后台上传收款二维码，用户提交付款备注，管理员审核订单。

支付相关配置在后台系统设置中维护，主要字段包括易支付提交地址、商户 ID、商户 KEY、回调地址、返回地址、在线支付开关、人工支付开关和余额充值汇率。PUBLIC_BASE_URL 会参与支付回调地址生成，生产环境必须配置为真实外网域名。

后台任务

服务启动后会根据配置运行以下后台任务：滑块验证码过期清理、待支付订单超时清理、订阅到期邮件提醒、渠道监控定时探测、集群节点注册与心跳。

如果 RUN_BACKGROUND_JOBS=false，相关后台任务会停止运行。多实例部署时，后台任务通过 Redis 集群锁避免重复执行。

安全注意事项

不要提交真实 .env、JWT 密钥、数据库密码、Redis 密码、上游 API Key、OAuth Secret、支付商户 KEY。
生产环境必须修改 JWT_SECRET 和 DEFAULT_ADMIN_PASSWORD。
生产环境必须配置 PUBLIC_BASE_URL 和明确的 ALLOWED_ORIGINS。
后台绑定的上游 API Key、支付 KEY、SMTP 密码和 OAuth Secret 不会在接口中明文返回。
用户平台 API Key 以哈希和加密字段保存，调用时使用 ag_xxx 形式。
建议将后端服务放在反向代理后，并启用 HTTPS。

常见问题

Redis 不可用会怎样？

服务会记录 Redis 不可用日志。部分 Redis 支撑的功能会降级，集群模式下 /ready 会将 Redis 视为关键依赖。

为什么生产环境启动失败？

当 APP_ENV=production 时，系统会拒绝默认 JWT 密钥、默认管理员密码、空 PUBLIC_BASE_URL 或通配符 CORS。

用户调用提示没有可用上游？

通常是用户套餐未生效、余额不足、后台未绑定计划上游、公共渠道无剩余额度，或余额模式没有可用余额通道。

模型计费不准确怎么办？

检查后台模型管理中的模型 ID、计费模式、输入/缓存输入/输出价格、请求价格、模型倍率和分组倍率，确认和上游返回的 usage 字段匹配。

前端构建 npm 入口缺失怎么办？

可以在 frontend/ 目录直接运行：

node node_modules\vite\bin\vite.js build

这与 npm run build 中的 Vite 构建等价。

开发规范

Go 代码使用 gofmt。
请求处理放在 controller/。
业务逻辑放在 service/。
数据模型放在 model/。
路由集中维护在 router/router.go。
前端组件使用 PascalCase 命名。
前端 API 封装放在 frontend/src/api/client.js。
修改后端共享逻辑后建议运行 go test ./...。
修改前端后至少运行生产构建。

许可证

当前仓库未声明开源许可证。对外分发或商用前，请先补充明确的 LICENSE 文件。

星空 - 奇怪的银河系