Juxingyi Configure

SKILL.md

---
name: huo15-juxingyi-configure
display_name: "Juxingyi 聚星逸配置指南"
description: "LLM 大模型聚合 SaaS 平台的配置与运维指南。涵盖供应商接入、模型路由、定价策略、网关增强、部署运维等。"
tags:
  - llm
  - gateway
  - saas
  - openai-compatible
  - api-aggregation
  - devops
version: 1.0.0
---

# Juxingyi 聚星逸配置指南

> 聚星逸（Juxingyi / Fireworks Hub）— LLM 大模型聚合 SaaS 平台。一个 OpenAI 兼容密钥调用 50+ 主流大模型，按量计费、多供应商自动故障切换。

## 平台架构

| 层 | 技术栈 | 域名/位置 |
|---|---|---|
| 后端 | Node + Fastify + Prisma + PostgreSQL 18 + Redis 7 | `fireworks-simulator-api.huo15.com` → `127.0.0.1:8787` |
| 前端控制台 | Vue3 + Vite + TS + Pinia | `fireworks-simulator.huo15.com/app/` |
| 营销静态页 | 原生 HTML/CSS/JS | `fireworks-simulator.huo15.com` |
| 部署 | Docker Compose + 宝塔 Nginx 反代 | 服务器 `47.104.78.121` |

## 核心能力

- **OpenAI 兼容网关**：`/v1/chat/completions`、`/v1/models`、`/v1/images/generations`、`/v1/videos/generations`
- **多供应商故障切换**：`Model`（对外模型+售价）↔ `ModelRoute`（→Provider 上游模型+优先级/成本/健康度）↔ `Provider`；按 priority 选路，失败自动切下一家，连续失败 3 次熔断 60s
- **Cheapest-First 选路**：多供应商路由按 `costInputPrice + costOutputPrice` 综合成本排序，成本最低的优先
- **多 Key 轮询**：一个供应商挂多把上游 key（`ProviderKey` 表），每 key 独立健康度
- **欠费动态降级**：上游报「余额不足」即该线路长冷却 30min 自动下线
- **协议感知选路**：同优先级内入站协议（openai/anthropic）匹配的上游优先
- **三账户钱包**：现金余额 / 赠送额度 / 佣金；扣费先扣赠送再扣现金
- **计费**：词元订阅套餐 + 阶梯预充；分段倍率定价；缓存命中折价；分组倍率
- **邀请返佣**：注册双方赠额度 + 好友消费按比例返现金佣金

## 供应商接入指南

### 当前已接入供应商

| 供应商 | Slug | 协议 | Base URL | 说明 |
|---|---|---|---|---|
| Sidus / Sophnet | `sidus` | OpenAI | `https://model.sidus-ai.com/api/open-apis/v1` | 主供应商，7+ 模型 |
| 润嘉云 | `alipower` | OpenAI | `https://llm.ai-token.com.cn/v1` | 8 文本 + 2 生图 |
| OpenSand | `opensand` / `opensand-anthropic` | OpenAI + Anthropic | `https://api.opensand.ai/v1` | 双协议 new-api 站 |
| DeepSeek 官方 | `deepseek-offical` / `deepseek-anthropic` | OpenAI + Anthropic | `api.deepseek.com` / `api.deepseek.com/anthropic/v1` | 原生双协议 |
| 智谱清言 | `zhipu` | OpenAI | `https://open.bigmodel.cn/api/paas/v4` | GLM 直连 |
| MiniMax | `minimax` | OpenAI | `https://api.minimaxi.com/v1` | Token Plan 套餐 |

### 添加新供应商步骤

1. **后台新增供应商**：「供应商」→ 新增，填写 Base URL（含 `/v1`）+ API Key
2. **测试连通性**：点「测试」按钮，拉 `/models` 看该 key 能用哪些模型（注意：`/v1/models` 列表 ≠ 授权子集，需逐个实调验证）
3. **给模型加路由**：到「模型」→ 选对外模型 → 加该供应商「路由」（填上游模型名 + 成本 + 优先级）
4. **设定优先级**：按 Cheapest-First 原则，成本最低的 priority=1，次便宜=2，兜底=999

### ⚠️ 常见坑

- **列表 ≠ 授权**：`/v1/models` 返回的是平台全目录，不一定都是 key 授权的，要逐个实调验证
- **Key 格式**：智谱清言 key 格式为 `{apiKey}.{secret}`
- **URL 清洗**：客户粘贴的 URL/key 入库前用 `cleanUrl()` 清洗隐形字符
- **AES 加密**：上游 Key 落库必须 AES 加密（`src/lib/crypto.ts` encryptSecret），不存明文
- **OpenClaw 接入**：provider ID 必须用 `yanhua`，严禁用 `fireworks`（会触发 OpenClaw 专属改写）

## 定价体系

### 定价规则

- **售价**挂 `Model`（`inputPrice` / `outputPrice`），单位：元/千 token
- **成本**挂 `ModelRoute`（`costInputPrice` / `costOutputPrice`）
- **利润**：售价 ≈ 成本 × 1.4~1.5（分段倍率：≤0.01×1.7 / ≤0.05×1.55 / ≤0.30×1.45 / >0.30×1.4）
- **生图按张**：`outputPrice` = 每张售价，张数记 `Usage.completionTokens`
- **视频按秒**：`outputPrice` = 每秒售价，秒数记 `Usage.completionTokens`（以轮询返回的 `usage.duration` 为准）
- **缓存命中折价**：命中缓存输入按 `售价 × Setting('pricing.cacheSellRatio', 0.5)` 计
- **分组倍率**：`User.priceGroup` × `Setting('group.multipliers')`（default=1 / vip=0.9 / enterprise=0.82 / reseller=0.75）

### 向客户展示

- **模型广场**：`/model-square.html`，未登录隐藏价格，登录后显示价格 + 官网折扣
- **控制台模型页**：`/app/#/models`，显示每百万 token 价格 + 模型 ID 复制

## 部署运维

### 服务器信息

- **服务器**：`47.104.78.121`（阿里云 + 宝塔 + Nginx + Docker）
- **后端目录**：`/www/wwwroot/fireworks-simulator/backend`（docker compose：api + db + redis）
- **前端目录**：`/www/wwwroot/fireworks-simulator/frontend`（根=营销页，`app/`=SPA）

### 前端部署

```bash
cd frontend && npm run build
rsync -av --delete frontend/dist/ root@47.104.78.121:/www/wwwroot/fireworks-simulator/frontend/app/
scp site/*.html site/*.js site/*.svg root@47.104.78.121:/www/wwwroot/fireworks-simulator/frontend/
ssh root@47.104.78.121 "chown -R www-data:www-data /www/wwwroot/fireworks-simulator/frontend"
```

### 后端部署

```bash
rsync -av --delete --exclude='node_modules' --exclude='.env' --exclude='dist' backend/ root@47.104.78.121:/www/wwwroot/fireworks-simulator/backend/
ssh root@47.104.78.121 "cd /www/wwwroot/fireworks-simulator/backend && docker compose build api && docker compose up -d"
```

### 常用运维命令

```bash
# 查看容器状态
ssh root@47.104.78.121 "cd /www/wwwroot/fireworks-simulator/backend && docker compose ps"

# 查看后端日志
ssh root@47.104.78.121 "cd /www/wwwroot/fireworks-simulator/backend && docker compose logs --tail=50 api"

# 重启后端
ssh root@47.104.78.121 "cd /www/wwwroot/fireworks-simulator/backend && docker compose restart api"

# 查看数据库
ssh root@47.104.78.121 "cd /www/wwwroot/fireworks-simulator/backend && docker compose exec db psql -U fireworks -d fireworks -c 'SQL_HERE'"

# 重置路由熔断状态
ssh root@47.104.78.121 "cd /www/wwwroot/fireworks-simulator/backend && docker compose exec db psql -U fireworks -d fireworks -c 'UPDATE \"ModelRoute\" SET \"consecutiveFailures\"=0, \"disabledUntil\"=NULL, \"lastError\"=NULL;'"
```

## 红线

- ❌ 不提交 secrets：`backend/.env` 已 gitignore，永不入库
- ❌ 上游 Key 落库必须 AES 加密，不存明文
- ❌ 用户网关 Key 只存 sha256，明文仅创建时返回一次
- ❌ 发版仅 `git push origin master`（gitee 单 remote）

## 关键文件索引

| 文件 | 作用 |
|---|---|
| `backend/src/lib/gateway.ts` | 网关核心：选路、故障切换、熔断、SSE 流式 |
| `backend/src/lib/pricing.ts` | 分段倍率定价 |
| `backend/src/lib/billing.ts` | 钱包扣费逻辑 |
| `backend/src/lib/orders.ts` | 邀请返佣 |
| `backend/src/routes/admin.ts` | 管理后台 API |
| `backend/src/routes/gateway.ts` | OpenAI 兼容网关路由 |
| `backend/src/routes/public.ts` | 公开 API（模型广场用） |
| `backend/prisma/schema.prisma` | 数据库 schema |
| `frontend/src/views/admin/Admin.vue` | 管理后台界面 |
| `frontend/src/views/Models.vue` | 控制台模型价格页 |
| `site/model-square.html` | 营销页模型广场 |
| `docs/供应商比价与路由策略.md` | 各模型路由优先级表 |
| `docs/PRD.md` | 产品需求全貌 |
| `docs/接手指南.md` | 部署 SOP / 凭据 / 常见操作 |