75 lines
3.7 KiB
Markdown
75 lines
3.7 KiB
Markdown
# goaiapi — 插件化 AI API 中继
|
||
|
||
一个**一切皆插件**的 AI API 流量中继。内核只是加载器：负责启动插件、版本管理、依赖解析、插件互调与动态加载/更新。中继的全部业务能力（反向代理转发、用量解析、留存、管理界面）都由独立进程插件实现，经内核 InvocationBroker 用 gRPC 互相调用。
|
||
|
||
## 设计要点
|
||
|
||
- **进程隔离插件**：每个插件是独立二进制，经 [hashicorp/go-plugin](https://github.com/hashicorp/go-plugin) 用 gRPC 与内核通信。插件崩溃不会拖垮内核。
|
||
- **内核中转互调**：插件之间从不直连。A 调 B 时，A → 内核 Broker → B，请求/响应是 proto-wire 字节，内核不感知任何插件的具体类型。
|
||
- **三层插件**（由内核依据依赖图复算校验，不信插件自报）：
|
||
- **base**：无插件依赖（如 `echo-base`、`recorder-base`、`usage-base`）
|
||
- **mid**：仅依赖 base（如 `transform-mid`、`dashboard`）
|
||
- **complex**：依赖至少一个非 base（如 `proxy`、`streaming-demo`）
|
||
- **版本管理**：依赖用 semver 约束声明，内核加载时校验已注册版本是否满足，并支持热升级（原子换 + 旧进程延迟排空）。
|
||
- **流量路径**：外部 HTTP（默认 `:8080`）→ 内核 → Broker → `proxy` 插件 → 上游；`proxy` 再经 Broker 调 `usage-base` 解析、`recorder-base` 留存。
|
||
|
||
## 目录结构
|
||
|
||
| 目录 | 说明 |
|
||
|---|---|
|
||
| `proto/` | **语言中立的 API 契约源**（`contract.proto`）。其它语言从此生成客户端 |
|
||
| `src/` | 全部源码（见 `src/go/`） |
|
||
| `scripts/` | 构建与代码生成脚本（`build.ps1`、`genproto.ps1`） |
|
||
| `build/` | 编译产物（`relay.exe` + `plugins/`）与运行数据。**不入库** |
|
||
| `tools/` | 预留的本地工具目录（当前为空） |
|
||
|
||
每个一级子目录另有自己的 README。跨语言接入本系统，先看 `proto/README.md`。
|
||
|
||
## 快速开始
|
||
|
||
构建（生成 proto、编译内核与全部插件）：
|
||
|
||
```powershell
|
||
.\scripts\build.ps1
|
||
```
|
||
|
||
运行（内核默认监听 `:8080` 收流量、`:8082` 控制端口，自动加载 `build/plugins/` 下的插件）：
|
||
|
||
```powershell
|
||
.\build\relay.exe -u https://your-upstream.example.com
|
||
```
|
||
|
||
内核入口的命令行参数（见 `src/go/cmd/relay/main.go`）：
|
||
|
||
| 参数 | 默认 | 说明 |
|
||
|---|---|---|
|
||
| `-l` | `127.0.0.1:8080` | 外部流量监听地址 |
|
||
| `-pd` | `build/plugins` | 插件目录（扫描 `*.exe` 自动加载；空字符串则不自动加载） |
|
||
| `-pa` | `127.0.0.1:0` | 内核 Broker gRPC 地址（`:0` = 随机端口） |
|
||
| `-ca` | `127.0.0.1:8082` | 插件管理控制端口（空字符串关闭） |
|
||
| `-proxy` | `proxy` | 处理外部流量的代理插件名 |
|
||
| `-drain` | `5000` | 热升级时旧插件进程排空等待毫秒数 |
|
||
|
||
> 上游地址（`-u`）等参数由 `proxy` 插件接收。
|
||
|
||
## 控制端口 API（默认 `:8082`）
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|---|---|---|
|
||
| GET | `/api/plugins` | 列出已加载插件 |
|
||
| GET | `/api/plugins/{name}` | 单个插件详情 |
|
||
| POST | `/api/plugins/load` | `{"binary_path"}` 加载注册 |
|
||
| POST | `/api/plugins/unload` | `{"name"}` 卸载（被依赖则拒绝） |
|
||
| POST | `/api/plugins/upgrade` | `{"name","binary_path"}` 热升级 |
|
||
|
||
## 工具链
|
||
|
||
构建依赖外部工具链（不在 PATH 上时脚本内已硬编码路径，按本机实际调整）：
|
||
|
||
- Go 1.26.3
|
||
- protoc + `protoc-gen-go` / `protoc-gen-go-grpc`（仅在改 `contract.proto` 时需要；生成代码已入库）
|
||
|
||
## 主要依赖
|
||
|
||
`github.com/hashicorp/go-plugin`（插件进程框架）、`google.golang.org/grpc`（互调传输）、`github.com/Masterminds/semver/v3`（版本约束）、`modernc.org/sqlite`（留存索引，纯 Go 无需 CGO）。
|