Initial commit: Luminary AI Gateway

OpenAI-compatible AI gateway with Vue admin UI, multi-provider egress, ingress key governance, monitoring, and security controls. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-06-23 21:46:16 +08:00
commit 76ba500417
134 changed files with 18988 additions and 0 deletions
@@ -0,0 +1,357 @@
+# Luminary
+
+OpenAI 兼容 AI 网关，带 Web 管理台。支持多 Provider 出口、入口密钥治理、看板监控与安全管控。控制面自研（Go + SQLite），数据面提供 OpenAI 兼容 `/v1/*` 推理 API。
+
+所有运行参数在 Web 管理台完成配置，**无需手写配置文件**。管理台支持**简体中文、英文**两种界面语言，可在顶栏随时切换。
+
+## 界面预览
+
+以下为 Web 管理台主要页面（点击可查看原图）。
+
+| 登录 | 看板监控 |
+|:---:|:---:|
+| ![登录页](docs/image/登陆页.png) | ![看板监控](docs/image/看板监控.png) |
+| 默认密码 `admin123`，首次登录后请修改 | Provider 健康、24h 请求/Token 与入口用量排行 |
+
+| 出口管理 | 入口管理 |
+|:---:|:---:|
+| ![出口管理](docs/image/出口管理.png) | ![入口管理](docs/image/入口管理.png) |
+| 多 Provider、多 Key 负载均衡与故障转移 | 入口密钥（`sk-lum-*`）、路由规则与预算限流 |
+
+| 请求日志 | IP 规则 |
+|:---:|:---:|
+| ![请求日志](docs/image/请求日志.png) | ![IP 规则](docs/image/IP规则.png) |
+| 全量请求记录与成本估算 | 精确 / CIDR 白黑名单（admin / proxy 范围） |
+
+| 系统设置 | |
+|:---:|:---:|
+| ![系统设置](docs/image/系统设置.png) | |
+| 加密密钥、会话、登录限流、健康检查与重试策略 | |
+
+## 功能概览
+
+| 模块 | 说明 |
+|------|------|
+| 出口管理 | OpenAI / Anthropic / Azure OpenAI / OpenRouter / Ollama / Custom，多 Key 加权负载均衡与故障转移 |
+| 入口管理 | OpenAI 兼容 API，入口密钥（`sk-lum-*`），Virtual Key 路由、预算与 RPM/TPM 限流 |
+| 看板监控 | Provider 健康检查、24h 请求/Token 统计、入口用量排行 |
+| 请求日志 | 全量请求记录、按模型定价的成本估算 |
+| IP 安全 | 管理员与推理入口分范围的白名单 / 黑名单（精确、CIDR） |
+| 系统设置 | 加密密钥、信任代理、会话、登录限流、用量刷盘、网关重试 |
+
+## 架构
+
+```
+客户端 SDK / curl
+    → /v1/*（入口密钥 sk-lum-*）
+        → Luminary Gateway（路由、限流、故障转移）
+            → Provider 出口（多 Key 加权负载均衡）
+                    ↑
+         管理台 REST API + Vue UI (:8293)
+                    ↓
+            SQLite + 内存缓存
+```
+
+## 快速开始（开发）
+
+### 依赖
+
+- Go 1.25+（见 `go.mod`）
+- Node.js 20+（仅开发/构建前端）
+
+依赖镜像（已写入 `Makefile`、`web/.npmrc`，国内网络友好）：
+
+- Go：`GOPROXY=https://goproxy.cn,direct`
+- npm：`registry=https://registry.npmmirror.com`
+
+海外用户可将 `GOPROXY` 改为 `https://proxy.golang.org,direct`，npm 使用默认 registry 即可。
+
+### 启动
+
+```bash
+cd web && npm install   # 安装前端依赖
+
+# 终端 1：后端
+go run ./cmd/luminary
+
+# 终端 2：前端（Vite 代理 /api、/v1 → :8293）
+cd web && npm run dev
+```
+
+访问 http://localhost:5173 ，默认账号 `admin` / `admin123`（**首次登录后请立即修改**）。
+
+```bash
+go test ./...   # 运行单元测试
+make build      # 构建 luminary 二进制（含嵌入前端）
+```
+
+## 部署
+
+镜像由 Gitea Actions 自动构建并发布到 Container Registry，**无需自行编译**。直接拉取运行即可。
+
+```bash
+docker pull git.rc707blog.top/rose_cat707/luminary:latest
+```
+
+| Tag | 说明 |
+|-----|------|
+| `latest` | `main` / `master` 分支最新构建 |
+| `sha-xxxxxxx` | 对应 commit 短 SHA |
+| `v1.2.3` | 推送 Git tag `v1.2.3` 时发布 |
+
+### docker run
+
+```bash
+docker pull git.rc707blog.top/rose_cat707/luminary:latest
+
+docker run -d --name luminary \
+  --restart unless-stopped \
+  -p 8293:8293 \
+  -v luminary-data:/data \
+  git.rc707blog.top/rose_cat707/luminary:latest
+```
+
+或使用项目内 `docker compose up -d`（通过环境变量 `LUMINARY_IMAGE` 指定镜像）。
+
+### 本地自行构建
+
+```bash
+make docker-build
+# 或
+docker build \
+  --build-arg IMAGE_PREFIX=docker.1panel.live/library/ \
+  --build-arg GOPROXY=https://goproxy.cn,direct \
+  -t luminary:local .
+```
+
+**端口（默认）**
+
+| 服务 | 端口 | 说明 |
+|------|------|------|
+| 管理 API / Web UI / 推理入口 | 8293 | 管理台与 `/v1/*` 共用同一监听地址 |
+
+监听地址可通过启动参数 `-addr` 或环境变量 `LUMINARY_ADDR` 修改。
+
+## 数据目录
+
+数据默认存储在 `./data/luminary.db`（SQLite），Docker 部署时挂载为 `/data`：
+
+```
+data/
+└── luminary.db    # Provider、入口密钥、规则、日志、系统设置
+```
+
+首次启动自动创建数据库与默认系统设置（含随机加密密钥）。默认管理账号 `admin` / `admin123`（仅当数据库中尚无管理员时创建）。
+
+## 入口 API（推理）
+
+客户端使用在管理台「入口管理」创建的**入口密钥**（`sk-lum-*`）调用，与 OpenAI SDK 兼容。
+
+**鉴权**
+
+```http
+Authorization: Bearer sk-lum-<your-key>
+```
+
+**Base URL**：`http://<host>:8293/v1`
+
+| 方法 | 路径 | 说明 | 状态 |
+|------|------|------|------|
+| `GET` | `/v1/models` | 列出当前入口密钥可用的模型 | 已支持 |
+| `POST` | `/v1/chat/completions` | 对话补全；`stream: true` 时返回 SSE 流式 | 已支持 |
+| `POST` | `/v1/responses` | OpenAI Responses API；`stream: true` 时返回 SSE 流式 | 已支持 |
+| `POST` | `/v1/completions` | 文本补全（Legacy） | 已支持 |
+| `POST` | `/v1/embeddings` | 向量嵌入 | 已支持 |
+| `POST` | `/v1/rerank` | Cohere 兼容重排序 | 已支持 |
+| `POST` | `/v1/audio/speech` | 语音合成 | 预留 |
+| `POST` | `/v1/audio/transcriptions` | 语音转写 | 预留 |
+| `POST` | `/v1/images/generations` | 图像生成 | 预留 |
+
+> 实际可访问的接口取决于上游 Provider 在「出口管理」中启用的 endpoint；未启用的接口网关不会转发。
+>
+> **Responses 适配**：若出口仅启用 `chat_completion` 而未启用 `responses`，网关会将 `/v1/responses` 自动转换为 `/v1/chat/completions` 请求，并将响应转回 Responses API 格式（含流式）。
+
+**示例：对话补全**
+
+```bash
+curl http://localhost:8293/v1/chat/completions \
+  -H "Authorization: Bearer sk-lum-..." \
+  -H "Content-Type: application/json" \
+  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Hello"}]}'
+```
+
+**示例：流式对话**
+
+```bash
+curl http://localhost:8293/v1/chat/completions \
+  -H "Authorization: Bearer sk-lum-..." \
+  -H "Content-Type: application/json" \
+  -d '{"model":"gpt-4o-mini","stream":true,"messages":[{"role":"user","content":"Hello"}]}'
+```
+
+**示例：Embeddings**
+
+```bash
+curl http://localhost:8293/v1/embeddings \
+  -H "Authorization: Bearer sk-lum-..." \
+  -H "Content-Type: application/json" \
+  -d '{"model":"text-embedding-3-small","input":"hello"}'
+```
+
+**示例：Rerank（Cohere 兼容）**
+
+```bash
+curl http://localhost:8293/v1/rerank \
+  -H "Authorization: Bearer sk-lum-..." \
+  -H "Content-Type: application/json" \
+  -d '{"model":"bge-reranker-v2-m3","query":"What is the capital of France?","documents":["Paris is the capital of France.","Berlin is in Germany."],"top_n":2}'
+```
+
+**示例：列出模型**
+
+```bash
+curl http://localhost:8293/v1/models \
+  -H "Authorization: Bearer sk-lum-..."
+```
+
+入口密钥的 Provider / Model 白名单、预算、RPM/TPM 限流与路由规则均在管理台「入口管理」配置；白名单为空表示不限制。
+
+## 使用攻略（简要）
+
+### 1. 首次登录
+
+1. 打开 `http://<主机>:8293`
+2. 默认账号 `admin` / `admin123`，登录后进入「系统设置」修改密码
+3. 顶栏切换界面语言（中文 / English）
+
+### 2. 配置出口
+
+1. 「出口管理」→ 新建 Provider，选择类型并填写 Base URL
+2. 添加 API Key，配置加权与故障转移
+3. 启用所需 endpoint 分类（语言模型 / 向量嵌入 / 重排序 / 图像等）
+
+### 3. 配置入口
+
+1. 「入口管理」→ 新建入口密钥（`sk-lum-*`）
+2. 配置 Provider / Model 白名单、预算与 RPM/TPM 限流
+3. 按需设置 Virtual Key 路由规则
+
+### 4. IP 安全
+
+1. 「IP 规则」添加白名单 / 黑名单（支持 CIDR）
+2. 规则可按 `admin`（管理台）或 `proxy`（推理入口）范围生效
+
+### 5. 日常运维
+
+| 操作 | 位置 |
+|------|------|
+| 查看流量与健康 | 看板监控 |
+| 管理 Provider 与 Key | 出口管理 |
+| 管理入口密钥 | 入口管理 |
+| 查看请求与成本 | 请求日志 |
+| 修改运行参数 | 系统设置 |
+
+## 系统设置
+
+所有运行参数在管理台 **系统设置** 页面维护，存入 SQLite。
+
+| 设置项 | 说明 |
+|------|------|
+| 加密密钥 | Provider API Key 加密密钥（首次启动自动生成） |
+| 信任代理 | 信任的反向代理 IP/CIDR；仅此时才读取 `X-Forwarded-For` |
+| 会话 / 登录限制 | 管理员 Session 有效期、登录尝试次数与锁定时长 |
+| 用量刷盘 / 健康检查 | 后台任务间隔 |
+| 网关重试 | 上游故障时的重试次数与退避 |
+
+启动参数（非阻塞，仅决定进程如何监听与数据存放位置）：
+
+| 参数 / 环境变量 | 说明 | 默认 |
+|------|------|------|
+| `-data-dir` / `LUMINARY_DATA` | SQLite 数据目录 | `./data` |
+| `-addr` / `LUMINARY_ADDR` | HTTP 监听地址 | `:8293` |
+
+可选环境变量 `LUMINARY_ENCRYPTION_KEY`：仅在首次初始化系统设置时写入加密密钥（一般无需设置，管理台可改）。
+
+## 应急恢复（容器内）
+
+当 IP 白名单或登录冷却导致无法进入管理台时，可在容器内执行恢复工具（已内置在镜像中）：
+
+```bash
+# 一键：重置密码为 admin123、清空 IP 规则与会话，并重启进程（清除内存中的登录冷却）
+docker exec luminary luminary-recover.sh --all
+
+# 指定新密码
+docker exec luminary luminary-recover.sh --all --password 'your-new-password'
+
+# 分项执行（不重启）
+docker exec luminary luminary-recover.sh \
+  --reset-password --clear-ip --clear-sessions --password 'your-new-password'
+
+# 仅清除登录冷却（需重启进程；登录冷却存在内存中）
+docker exec luminary luminary-recover.sh --restart
+```
+
+本地非容器环境：
+
+```bash
+chmod +x scripts/luminary-recover.sh
+./scripts/luminary-recover.sh --all
+# 或
+go run ./cmd/luminary-recover --all
+```
+
+| 参数 | 说明 |
+|------|------|
+| `--all` | 重置密码 + 清空 IP 规则 + 清空会话 + 重启进程 |
+| `--reset-password` | 重置管理员密码 |
+| `--clear-ip` | 删除全部 IP 规则 |
+| `--clear-sessions` | 删除全部管理员 Session |
+| `--restart` | 向 PID 1 发送 SIGTERM，由容器重启策略拉起新进程 |
+| `--password` | 新密码（默认 `admin123`） |
+| `--username` | 管理员用户名（默认 `admin`） |
+| `-data-dir` / `LUMINARY_DATA` | 数据目录（默认 `./data`，容器内为 `/data`） |
+
+## 命令行
+
+| 命令 | 说明 |
+|------|------|
+| `luminary` | 启动网关（默认 `-data-dir ./data`、`-addr :8293`） |
+| `luminary-recover` | 应急恢复 CLI（容器内 `luminary-recover.sh` 封装） |
+
+## 项目结构
+
+```
+cmd/luminary/          # 主服务入口
+cmd/luminary-recover/  # 应急恢复 CLI
+internal/
+  gateway/             # 路由、故障转移、健康检查
+  handler/             # 管理 API、推理代理、静态资源
+  provider/            # 各 Provider 客户端与适配
+  store/               # SQLite 与内存缓存
+  auth/                # 密码、登录限流
+  middleware/          # IP 过滤、客户端 IP
+  monitor/             # 监控统计
+  pricing/             # 成本估算
+web/                   # Vue 3 管理台
+  src/i18n/            # 多语言资源
+  src/views/           # 页面
+docs/
+  image/               # README 界面截图
+  UI-DESIGN-SYSTEM.md
+.gitea/workflows/      # Gitea Actions CI
+```
+
+## CI / 镜像发布
+
+推送 `main` / `master` 或 tag `v*` 时，Gitea Actions 构建多架构镜像并推送到 Registry。工作流与 Dockerfile 约定见 [.gitea/README.md](.gitea/README.md)；act_runner 部署参考见 [.gitea/act-runner/](.gitea/act-runner/)。
+
+**一次性配置**（仓库 Settings → Actions）：
+
+| 类型 | 名称 | 说明 |
+|------|------|------|
+| Secret | `REGISTRY_TOKEN` | Gitea PAT，需 `write:package` 权限 |
+| Variable | `REGISTRY` | 公网 Gitea 域名，如 `git.rc707blog.top` |
+
+## 许可
+
+[Luminary 采用 MIT License](LICENSE).