INTERNAL · v0.1 · 2026-09

荣迈 AI 能力平台管理使用操作手册

面向公司内部运营 / 商务 / 财务 / 客户支持团队，覆盖平台部署、管理后台、客户门户、API 接入、计费、安全合规等日常操作的完整指引。

1. 平台简介

荣迈 AI 能力平台是公司面向自有智能体产品的统一 AI 能力中转服务，向下对接多家上游大模型（DeepSeek / 阿里云百炼 / Kimi / 智谱等），向上为公司自研智能体与外部签约客户提供统一的 OpenAI-compatible 接口、平台 Key 鉴权、用量计费、账单与运营治理能力。

1.1 商业定位（必读）

本平台销售"公司自有智能体产品 + AI 能力套餐"，不转售上游裸 API / Token。客户持有的是公司平台 Key，仅能访问公司提供的服务与模型能力，不构成对上游 API 的分许可。涉及对外宣传或商务谈判时，禁止使用"官方代理""某厂商 Token 转售"等未经授权表述。

1.2 系统边界

统一 API 网关/v1/chat/completions、/v1/models（OpenAI 兼容）

策略中心平台 Key 鉴权、模型权限、分层限流、预算护栏

计费账本价格版本、预检冻结、调用结算、退款补偿、幂等防重

供应商适配层OpenAI-compatible + 自定义，标准请求/响应/usage/工具调用

1.3 模块清单

模块	状态	说明
Phase A 网关底座	已交付	统一对话接口、平台 Key、基础路由、调用日志
Phase B 计费治理	已交付	余额冻结/结算、价格版本、账单、分层限流
Phase C 真实 PoC	待配置	填入企业 API Key，跑通真实上游调用
Phase D 商业扩展	规划中	支付、发票、套餐、多供应商扩展（按业务节奏推进）

2. 快速开始

2.1 环境要求

Node.js ≥ 20（原生 fetch / AbortController）
MySQL 8.0+（持久化：租户、Key、钱包、日志、账单）
Redis 6+（限流原子计数）
Windows / Linux 均可

2.2 安装与启动

cd token-gateway
npm install
cp .env.example .env   # 编辑：DB / Redis / 供应商 Key
npm run db:migrate
npm run db:seed        # 输出 demo 平台 Key（明文仅展示一次）
npm start              # 或 npm run dev（nodemon --watch）

2.3 演示模式（无 MySQL/Redis）

DEMO_MODE=1 PORT=8090 node src/server.js

启动后访问 http://127.0.0.1:8090/demo 获取演示 Key，可直接调用 /v1/chat/completions 验证全链路。模型名含 fail 触发模拟上游故障，含 slow 触发延迟。

2.4 冒烟测试

npm run smoke           # 单元冒烟（8 项）
node scripts/httpSmoke.js  # HTTP 鉴权（5 项）
node scripts/demoSmoke.js  # DEMO 端到端（12 项）
node scripts/extendedSmoke.js  # 流式+计费+管理 API（18 项）

共 43 项，全部通过即代表平台底座功能闭环。

3. 管理后台使用

管理后台地址：http://<host>:8080/，登录凭据为 ADMIN_TOKEN 环境变量（默认 rongmai-admin-dev，生产环境必须修改）。

3.1 工作台（dashboard）

今日调用概览：最近 50 条调用的请求数、成功率、Token 消耗
钱包余额 / 冻结金额：当前租户账户的可用与冻结
上游健康：每个供应商的健康度（5 秒 / 探测）
最近调用 / 上游状态：辅助巡检

3.2 平台 Key 管理

每个 Key 是客户的唯一身份凭证。明文仅在创建时展示一次，数据库只保存 SHA-256 摘要。

新建 Key：填写租户 ID、名称、模型权限（JSON 数组，["*"] 全部）、日/月预算（元，0 为不限）、总额度（元，0 为不限）
撤销 Key：点操作列的"撤销"，立即生效，状态置 revoked
公开标识格式：sk-rm-****-<8位hex>，用于在日志和客户门户中安全展示

建议：每个客户独立租户；测试 / 生产环境分别建 Key；预算为 0 表示不设限，但 RPM / 并发仍受默认策略约束。

3.3 模型路由

平台模型名 → 供应商 + 上游模型名的映射表。新建模型时指定：

平台模型名：如 deepseek-flash，客户调用时使用
供应商 ID：deepseek / kimi / zhipu / aliyun 等
上游模型名：供应商实际接受的模型名
能力：chat / tool / vision

未注册的模型名会按供应商前缀回退到该供应商默认模型，仅建议在过渡期使用，正式环境请明确注册。

3.4 供应商管理

注册上游厂商、查看健康度、查看是否已配置 API Key。

API Key 必须配置在服务端的 .env 文件中（如 PROVIDER_DEEPSEEK_API_KEY=sk-...），不会写入数据库、不出现在日志中。生产环境请使用企业 API Key，禁止把个人会员 / Coding Plan / Agent Plan 等权益类 Key 接入公共计费池。

3.5 价格版本

平台对客户展示与计费依据。表头字段：

字段	说明
input_price	未命中缓存的输入价（元/百万 token）
cache_input_price	命中缓存的输入价
output_price	输出价
time_band	`all` / `peak` / `offpeak`（DeepSeek 高峰：周一至五 09:00-12:00、14:00-18:00）
effective_at	生效时间（向上兼容：生效后取最新版本）

3.6 调用记录

展示请求级元数据：Request ID、模型、供应商、Token、费用、延迟、状态、错误码。不记录请求 / 响应正文，不记录上游 API Key。CSV 导出可对账与审计。

3.7 计费与余额

充值：管理端直接对租户钱包入账（建议用于测试 / 补偿）
生成账单：按租户 + 月份聚合，状态 draft → published → paid
状态流转：published 视为出账，paid 视为回款

3.8 充值审批

客户在 /customer.html 提交的对公转账申请在此处理。详见第 7 节。

4. 客户门户使用

客户门户地址：http://<host>:8080/customer.html。客户用平台 Key 登录，页面自动获取该 Key 所属租户的余额、用量、账单与价格标准。

4.1 客户视角的功能

账户概览：余额、冻结、本月请求、Token 消耗、本月消费
可用模型：当前 Key 可调用的模型列表（含能力标记）
余额充值：填写金额 + 转账凭证提交申请
用量明细：最近 30 条调用记录
价格标准：展示当前生效的所有价格版本（含峰谷价）
充值记录：申请状态、到账时间、处理说明

4.2 充值操作流程

客户向公司对公账户转账，转账备注写公司名称
客户在门户"余额充值"页填写金额、备注、转账凭证 / 单号，点击提交
状态变为"待确认"，管理员在后台"充值审批"中核对到账后点"确认到账"
系统自动入账，状态变为"已到账"，客户余额立即增加

4.3 给客户的简短说明（可直接复制）

尊敬的客户：您的平台 Key 可登录 http://<host>:8080/customer.html，随时查看余额、用量明细、价格标准与充值记录。充值请按页面上的收款信息对公转账，并在系统中提交申请（请填写转账单号以便核验），管理员核验到账后自动入账。

5. 客户 API 接入

5.1 Base URL 与认证

Base URL: http://<host>:8080/v1
Authorization: Bearer sk-rm-xxxxxxxx-xxxxxxxxxxxxxxxx

5.2 获取可用模型

curl -s http://<host>:8080/v1/models \
  -H "Authorization: Bearer sk-rm-..."

5.3 对话补全（非流式）

curl -X POST http://<host>:8080/v1/chat/completions \
  -H "Authorization: Bearer sk-rm-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-flash",
    "messages": [
      {"role": "user", "content": "你好"}
    ]
  }'

5.4 对话补全（流式 SSE）

curl -N -X POST http://<host>:8080/v1/chat/completions \
  -H "Authorization: Bearer sk-rm-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-flash",
    "stream": true,
    "stream_options": {"include_usage": true},
    "messages": [{"role":"user","content":"写一首诗"}]
  }'

响应为 text/event-stream，逐块产出，最后一帧包含完整 usage，末尾 data: [DONE]。流结束后按实际 usage 结算，差额退款。

5.5 工具调用（Function Calling）

工具调用字段由适配层标准化透传。在请求中按 OpenAI 格式声明 tools 即可：

{
  "model": "deepseek-flash",
  "tools": [{"type":"function","function":{...}}],
  "messages": [...]
}

上游返回的 tool_calls 字段会原样回传，无需客户端处理协议差异。模型注册表中的 capability=tool 表示支持工具调用。

5.6 幂等键

推荐为重试场景添加 Idempotency-Key 头，避免因重试造成重复扣费：

curl ... -H "Idempotency-Key: order-20260902001-req-1" ...

5.7 错误码

HTTP	code	含义	建议处理
400	`NO_MODEL`	请求缺 model	补齐 model 字段
400	`UNKNOWN_MODEL`	模型未注册	调用 `/v1/models` 确认可用名
401	`NO_KEY` / `INVALID_KEY`	鉴权失败	检查 `Authorization` 头
402	`INSUFFICIENT_BALANCE`	余额不足	在客户门户提交充值
403	`MODEL_FORBIDDEN`	该 Key 无此模型权限	联系管理员调整 Key 权限
429	`RATE_LIMITED` / `CONCURRENCY_LIMITED` / `DAILY_BUDGET_EXCEEDED`	触发限流 / 预算	降频或申请提高预算
500	`NO_PROVIDER_KEY`	上游 Key 未配置	服务端 `.env` 配置
5xx	`UPSTREAM_ERROR` / `UPSTREAM_CONNECT_FAILED`	上游错误	查看 `request_id` 对照上游

所有错误响应均带 request_id 字段，可与日志关联追溯。

6. 供应商配置

在 .env 中按供应商 ID 配置 Base URL 和 API Key（API Key 必须从厂商开发者平台获取企业按量 API Key）：

PROVIDER_DEEPSEEK_BASE_URL=https://api.deepseek.com
PROVIDER_DEEPSEEK_API_KEY=sk-xxxxxxxxxxxx

PROVIDER_KIMI_BASE_URL=https://api.moonshot.cn/v1
PROVIDER_KIMI_API_KEY=sk-xxxxxxxxxxxx

PROVIDER_ZHIPU_BASE_URL=https://open.bigmodel.cn/api/paas/v4
PROVIDER_ZHIPU_API_KEY=xxxxxxxxxxxx.xxxxxxxx

PROVIDER_ALIYUN_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode
PROVIDER_ALIYUN_API_KEY=sk-xxxxxxxxxxxx

合规要点（来自可行性报告）：

禁止把个人会员 / Coding Plan / Agent Plan 等权益类 Key 接入公共计费池
未取得书面许可前，禁止以任何形式明示 / 暗示平台为上游厂商的"官方代理"
供应商授权边界以双方商务合同为准；任何新增上游供应商必须先走合同评审

7. 充值审批流程

客户通过客户门户提交的对公转账充值申请，在管理后台 充值审批 视图中处理。

7.1 操作步骤

登录管理后台，左侧导航点击"充值审批"
在"待处理"列表中核对申请：金额、租户、凭证 / 单号、提交时间
到公司对公账户核实转账是否实际到账（含金额、付款方）
确认到账 → 点"确认到账"（可选填写处理说明，例如"已核对银行流水"）
或金额 / 凭证不符 → 点"驳回"并填写原因（如"金额与转账记录不符，请核实"）

7.2 状态机

pending客户已提交，待管理员处理

approved管理员已确认到账，余额已入账

rejected管理员驳回，余额未变

已处理的申请不可再次审批（系统返回 ALREADY_HANDLED）。如需更正，请走管理端"钱包充值"手工入账。

7.3 审批注意事项

金额必须严格一致，不一致先驳回让客户核实
处理说明建议填写，例如"已核对 9/2 工商银行流水 #20260902001"，便于事后追溯
每天下班前清理当日 pending 申请

8. 限流与预算

分层限流为每个 Key 提供多重护栏：

维度	默认	环境变量	说明
RPM	60 / 分 / Key+模型	`RPM_LIMIT`	每分钟请求数
并发	8	`CONCURRENCY_LIMIT`	同时在线请求（含流式长连接）
日预算	0（不限）	Key 创建时填写	按 Key 累计消费
月预算	0（不限）	Key 创建时填写	按 Key 累计消费

任何维度被触发都会立即返回 429。客户端应做退避（指数退避）。

8.1 熔断

同一供应商连续 5 次失败 → 熔断打开 30 秒（快速失败不调用上游），冷却后进入 half-open 探测 1 次，成功则恢复。

9. 计费与价格

9.1 计费三步

预检冻结：请求前按 model + max_tokens 估算最大费用，从余额冻结到 frozen
调用采集：按上游 usage 实际用量计算（含缓存命中 / 输出）
幂等结算：从冻结中扣除实际费用，差额自动退款；流式断线全退

9.2 价格版本示例（DeepSeek）

# DeepSeek Flash 系（deepseek-flash / deepseek-v4-flash / deepseek-v4.1-flash）
model=deepseek-flash    time_band=offpeak input=1.0 cache=0.02 output=4.0
model=deepseek-flash    time_band=peak    input=2.0 cache=0.04 output=8.0

# DeepSeek V4 Pro
model=deepseek-v4-pro   time_band=offpeak input=4.5 cache=0.15 output=13.5
model=deepseek-v4-pro   time_band=peak    input=9.0 cache=0.30 output=27.0

单位均为 元 / 百万 token。DeepSeek 高峰定义：北京时间周一至周五 09:00-12:00、14:00-18:00（其余为空闲时段，空闲价为高峰价的一半）。

9.2.1 DeepSeek 模型命名与能力（2026-09 官方口径）

平台模型名	上游模型名	官方模型版本	能力
`deepseek-flash`（推荐）	`deepseek-flash`	DeepSeek-V4.1-Flash	工具调用 / 图像理解 / 思考模式
`deepseek-v4.1-flash`	`deepseek-flash`	同上（别名）	同上
`deepseek-v4-flash`	`deepseek-flash`	同上（旧名兼容）	同上
`deepseek-v4-pro`	`deepseek-v4-pro`	DeepSeek-V4-Pro-0813	工具调用 / 思考模式

官方说明：模型名请使用 deepseek-flash；旧模型名 deepseek-v4-flash、deepseek-v4-flash-vision-exp 仍可调用，但对应模型已下线，请求将由 DeepSeek-V4.1-Flash 提供服务并按 Flash 价格计费。本平台已将上述三个平台模型统一映射到上游 deepseek-flash，客户可按习惯沿用旧名。

能力参考：Flash 上下文 1M、输出上限 384K，支持思考模式（请求体可传 "thinking": {"type":"enabled"} 与 "reasoning_effort":"high"）、JSON 输出、工具调用、图像理解；Pro 上下文 1M，支持工具调用与思考模式，不支持图像理解。上游并发限制：Flash 2500 / Pro 500，平台侧另有限流护栏（见第 8 节）。

9.3 分类计量

单次请求的费用 = （未命中输入 × input_price） + （命中输入 × cache_input_price） + （输出 × output_price）。各厂商字段命名差异由适配层统一。

10. 安全与合规

平台 Key：数据库只存 SHA-256 摘要 + 服务端盐，明文仅创建时展示一次
上游 API Key：仅通过环境变量注入，不落库、不落日志
请求 / 响应正文：默认不记录，只记元数据与 usage
管理端 ADMIN_TOKEN：.env 中设置，生产环境必须修改且定期轮换
对外表述：销售自有智能体软件 + AI 能力套餐，不得使用"官方代理""Token 转售"等表述
套餐入池：禁止把个人会员 / Coding Plan / Agent Plan 等权益类 API 接入公共计费池
审计留存：调用日志 + 钱包流水 + 充值申请按月归档，建议 ≥ 12 个月

11. 故障排查 FAQ

Q1：调用返回 `NO_PROVIDER_KEY`

原因：上游厂商的 API Key 未配置到服务端环境变量。

排查：检查 .env 中 PROVIDER_<ID>_API_KEY，重启网关使环境变量生效。控制台 echo $PROVIDER_DEEPSEEK_API_KEY 验证。

Q2：调用返回 `402 INSUFFICIENT_BALANCE`

租户钱包余额不足。客户需登录 /customer.html 提交充值申请；管理员在管理后台"充值审批"中确认到账。

Q3：流式调用只产出几个块就停了

可能原因：上游超时（默认 300s）、网络中断、流被关闭。
平台处理：流式断线时已消费部分会全部退款，可在"用量明细"中看到 stream_interrupted 状态记录。

Q4：同一请求被扣了两次

请确认是否携带了 Idempotency-Key 头。带相同 Key 的请求视为同一笔，不会重复扣费。如未带且确实被多扣，请联系管理员查看 request_logs 与 wallet_entries。

Q5：管理后台无法登录

检查 ADMIN_TOKEN 环境变量是否与页面输入一致。服务端启动日志会打印当前使用的 ADMIN_TOKEN，生产环境务必修改默认值。

Q6：上游返回 401/403 等鉴权错误

说明上游 API Key 失效或无权限。检查 .env 中的 Key 状态，必要时登录厂商开发者后台重新生成。

Q7：服务启动报 Redis 连接失败

Redis 不可用时，限流会被自动禁用（平台继续工作但无限流保护）。检查 REDIS_HOST / REDIS_PORT，确认 Redis 服务运行中。

Q8：演示模式（DEMO_MODE）能用于生产吗？

不能。演示模式用内存存储，重启清空、无法持久化、无法水平扩展。仅用于本机试运行和功能演示。

本文档随平台版本持续更新 · v0.1 · 2026-09 · 内部文档，请勿外传

荣迈 AI 能力平台管理使用操作手册

1. 平台简介

1.1 商业定位（必读）

1.2 系统边界

1.3 模块清单

2. 快速开始

2.1 环境要求

2.2 安装与启动

2.3 演示模式（无 MySQL/Redis）

2.4 冒烟测试

3. 管理后台使用

3.1 工作台（dashboard）

3.2 平台 Key 管理

3.3 模型路由

3.4 供应商管理

3.5 价格版本

3.6 调用记录

3.7 计费与余额

3.8 充值审批

4. 客户门户使用

4.1 客户视角的功能

4.2 充值操作流程

4.3 给客户的简短说明（可直接复制）

5. 客户 API 接入

5.1 Base URL 与认证

5.2 获取可用模型

5.3 对话补全（非流式）

5.4 对话补全（流式 SSE）

5.5 工具调用（Function Calling）

5.6 幂等键

5.7 错误码

6. 供应商配置

7. 充值审批流程

7.1 操作步骤

7.2 状态机

7.3 审批注意事项

8. 限流与预算

8.1 熔断

9. 计费与价格

9.1 计费三步

9.2 价格版本示例（DeepSeek）

9.2.1 DeepSeek 模型命名与能力（2026-09 官方口径）

9.3 分类计量

10. 安全与合规

11. 故障排查 FAQ

Q1：调用返回 NO_PROVIDER_KEY

Q2：调用返回 402 INSUFFICIENT_BALANCE

Q3：流式调用只产出几个块就停了

Q4：同一请求被扣了两次

Q5：管理后台无法登录

Q6：上游返回 401/403 等鉴权错误

Q7：服务启动报 Redis 连接失败

Q8：演示模式（DEMO_MODE）能用于生产吗？

Q1：调用返回 `NO_PROVIDER_KEY`

Q2：调用返回 `402 INSUFFICIENT_BALANCE`