# Luminary

OpenAI 兼容 AI 网关，带 Web 管理台。支持多 Provider 出口、入口密钥治理、看板监控与安全管控。控制面自研（Go + SQLite），数据面统一通过入口密钥对外提供 **OpenAI 兼容推理 API** 与 **Replicate 兼容 Predictions 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 / ComfyUI，多 Key 加权负载均衡与故障转移 |
| 入口管理 | OpenAI 兼容 API，入口密钥（`sk-lum-*`），Virtual Key 路由、预算与 RPM/TPM 限流 |
| 看板监控 | Provider 健康检查、24h 请求/Token 统计、入口用量排行 |
| 请求日志 | 全量请求记录、按模型定价的成本估算 |
| IP 安全 | 管理员与推理入口分范围的白名单 / 黑名单（精确、CIDR） |
| 系统设置 | 加密密钥、信任代理、会话、登录限流、用量刷盘、网关重试 |

## 架构

```
客户端 SDK / curl
    → /v1/*（入口密钥 sk-lum-*）
        ├─ OpenAI 兼容推理（chat / embeddings / rerank …）
        └─ Replicate 兼容 Predictions（ComfyUI 工作流）
            → Luminary Gateway（路由、限流、故障转移）
                → Provider 出口（多 Key 加权负载均衡）
                        ↑
         管理台 REST API + Vue UI (:8293)
                    ↓
            SQLite + 内存缓存
```

## 入口协议

Luminary 的核心是 **AI 网关**：客户端用入口密钥（`sk-lum-*`）调用，网关负责鉴权、路由、限流与上游故障转移。对外提供两套兼容协议，Base URL 均为 `http://<host>:8293/v1`：

| 协议 | 兼容标准 | 典型场景 |
|------|----------|----------|
| **OpenAI 兼容推理 API** | [OpenAI `/v1/*`](https://platform.openai.com/docs/api-reference) | 语言模型对话、向量嵌入、重排序等同步推理 |
| **Replicate Predictions API** | [Replicate `/v1/predictions`](https://replicate.com/docs/reference/http) | ComfyUI 工作流异步图像生成 |

两套协议共用同一入口密钥；具体可调用的 endpoint 取决于「出口管理」中为 Provider 启用的能力分类。

## 快速开始（开发）

### 依赖

- 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 |
|------|------|----------------|
| **文本（OpenAI）** | LLM / Embedding / Rerank | `/v1/chat/completions`、`/v1/embeddings` 等 |
| **图片（Replicate）** | ComfyUI 文生图 / 图生图 | `/v1/predictions`、`GET /v1/models`（Replicate 格式） |

已有密钥默认归类为**文本**，可在管理台编辑修改为**图片**。

同一密钥不能混用两套协议：用文本密钥访问 `/v1/predictions` 或用图片密钥访问 `/v1/chat/completions` 将返回 `403`。

## 入口 API（OpenAI 兼容）

客户端使用协议为**文本**的入口密钥（`sk-lum-*`）调用，与 OpenAI SDK 兼容。

**鉴权**（二选一）

```http
Authorization: Bearer sk-lum-<your-key>
```

```http
X-Api-Key: sk-lum-<your-key>
```

**Base URL**：`http://<host>:8293/v1`

| 方法 | 路径 | 说明 | 状态 |
|------|------|------|------|
| `GET` | `/v1/models` | 列出当前文本密钥可用的模型（OpenAI 格式） | 已支持 |
| `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 限流与路由规则均在管理台「入口管理」配置；白名单为空表示不限制。

## Predictions API（Replicate 兼容）

ComfyUI 出口的异步任务接口，需使用协议为**图片**的入口密钥。

| 方法 | 路径 | 说明 | 状态 |
|------|------|------|------|
| `GET` | `/v1/models` | 列出当前图片密钥可用的工作流模型（Replicate 格式） | 已支持 |
| `POST` | `/v1/predictions` | 创建异步任务；请求头 `Prefer: wait` 时同步等待完成 | 已支持 |
| `GET` | `/v1/predictions` | 列出任务（`cursor` 分页） | 已支持 |
| `GET` | `/v1/predictions/:id` | 查询任务状态与输出 | 已支持 |
| `POST` | `/v1/predictions/:id/cancel` | 取消进行中的任务 | 已支持 |
| `GET` | `/v1/predictions/:id/stream` | SSE 流式推送任务进度 | 已支持 |

请求体中 `version` 为入口 Model ID，支持 `owner/name` 或短 `name`（与 `GET /v1/models` 返回的 `latest_version.id` / `owner`+`name` 一致）；`input` 字段见模型 `openapi_schema.components.schemas.Input`。

**示例：列出工作流模型**

```bash
curl http://localhost:8293/v1/models \
  -H "Authorization: Bearer sk-lum-..."   # 图片协议密钥
```

**示例：创建 Predictions 任务**

```bash
curl -X POST http://localhost:8293/v1/predictions \
  -H "Authorization: Bearer sk-lum-..." \
  -H "Content-Type: application/json" \
  -d '{"version":"luminary/flux-txt2img","input":{"prompt":"a cat"}}'
```

任务完成后，输出图像通过网关签名的 URL 返回（`/files/:id?exp=&sig=`）。

## 使用攻略（简要）

### 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).