初始化（快速入门）

本页是私有化部署的主快速入门：从一台刚按部署页启动的空机，到用自己网关发出第一个模型回复——管理员账户、上游渠道、价格、用户、令牌、验收请求，每一步都有明确的点击路径与字段说明。

全程在浏览器里完成，不需要命令行（最后一个验收请求除外）。按顺序走完约 10 分钟。

0. 你现在在哪

按部署页验证过 needs_setup:true 之后：

打开浏览器访问 http://<服务器地址>:8081（管理控制台地址）。
系统检测到还没有管理员，会自动跳转到初始化引导页——你不需要记住任何入口地址。

两个地址从现在开始要区分清楚：

地址	用途
`http://<服务器地址>:8081`	管理控制台（浏览器里用的）+ 用户自助 + 全部 `/api/` 管理接口
`http://<服务器地址>:6200`	API 网关本体——你的程序用 `sk-` 令牌调 `/v1/chat/completions` 的地方

1. 初始化引导页

引导页只有一屏表单，全部字段如下：

1.1 激活码（仅部署配置了激活码时出现）

部署时如果设置了 CIYI_SETUP_CODE 环境变量，页面上会多出第一个输入框「激活码」：填入交付方提供给你的激活码即可。
没配置则不显示这一栏，直接进入下一步。不确定有没有配置？看接口 curl http://<服务器>:8081/api/v1/setup/status 返回的 code_required 字段。
连续输错 5 次会锁定 5 分钟（防爆破），锁定期间正确激活码也会被拒绝，等待即可。

1.2 管理员账户与密码

管理员用户名：你今后的登录名（admin、root 等都可以，1–64 字符）。
密码：至少 8 个字符，输入两遍确认。

这就是你的管理员账户

引导页创建的是最高权限管理员。密码只存在你脑子里（bcrypt 加密入库，任何人不可查看），忘了只能进库删用户重来——请设置成你管得住的密码。

1.3 完成与后续入口

点击「初始化」后自动登录（引导流程直接给你签发了会话，不需要再登一次），页面切换为成功态，给出两个入口：

进入管理控制台，配置渠道 → 直达渠道页（本页第 3 节的内容）。
文档站快速入门 → 就是你现在看的这页。

初始化窗口在创建管理员的瞬间关闭：之后再访问 /setup 会被送回登录页，initialize 接口从此返回 409。也就是说这一步只能做一次，做好就翻篇。

跳过引导页的替代方式

部署时设置 CIYI_ADMIN_PASSWORD 环境变量可以不经引导页，首次启动自动 seed 一个用户名为 admin 的管理员（密码为该值）。两种方式二选一即可；适合脚本化无人值守部署。后续修改密码都在控制台里做。

2. 认识管理台

登录后左侧边栏是管理员的全部工作台，按组分：

组	页面	干什么
管理员	概览 / 渠道 / 用户 / 企业 / 项目 / Token / 使用日志 / 审计日志 / 流水 / 划拨	日常运营主体
计费与路由	定价 / 模型目录 / 路由策略 / 模型别名	价格与转发规则
账户	API 密钥 / 个人资料	管理员本人的用户面（自签密钥等）
系统	设置	引擎运行开关（计费、限流、自签等）

本页接下来的路径都用「组 → 页面」表示。

3. 接入第一个上游渠道

渠道 = 一条到上游 AI 服务商的线路（凭证 + 模型清单 + 调度参数）。进入管理员 → 渠道，点击右上角新建，抽屉里的字段逐一说明：

3.1 基础信息

字段	说明
名称	备注用，随便起（如「智谱主力」）
适配器	上游协议基座，三个选项：OpenAI 兼容（`openai-generic`，一切 OpenAI 兼容官方/中转端点——智谱、阿里百炼、火山方舟等都提供这种端点）、Anthropic（`anthropic` 协议端点）、MCP 网关（`mcp`）。不确定就选 OpenAI 兼容——市面上的中转站几乎全是这个协议
Base URL	上游 API 根地址（如 `https://api.openai.com`）。结尾多敲了 `/v1` 之类的路径会自动归一掉，不用担心
凭证	上游 API Key（`sk-` 开头那串）。入库即加密存储，之后任何页面不再显示明文

3.2 调度参数

字段	说明	建议值
分组	该渠道挂在哪个转发分组下，令牌按分组圈定可用渠道	`default`（起步）
资源池（Pools）	更细的流量隔离（coding / agent 等专用池）	留空
优先级	数字越大越先被选；同优先级再按权重分摊	`100`
权重	同优先级内的流量分摊比例	`1`
层级（Tier）	计费定价档位键，与定价规则匹配（见第 4 节）	留空（走默认价）
最大并发	该渠道同时在途请求上限，`0` = 不限；满了自动重试其他渠道	`0`（单渠道起步不限）
状态	启用 / 手动停用	启用

3.3 模型投影

模型投影是「对外模型名 → 上游模型名」的映射表，决定这条渠道能转发哪些模型：

一行一个投影：左边的模型名是你的用户在请求里写的名字，右边（可选）填上游真实模型名——留空表示两边同名。
例：对外统一叫 gpt-4o-mini，上游其实用的是 gpt-4o-2024-08-06，就填左 gpt-4o-mini、右 gpt-4o-2024-08-06。
没有投影也能保存，但渠道不可路由（没有任何模型名能命中它，验收请求会 404）——所以实际使用至少要配一条。

3.4 探活（推荐配置）

抽屉底部的「探活」区块用于主动监测渠道健康：

探活模型：用哪个模型发探测请求，默认取第一个投影。
探活全部模型：开关，逐个投影都探（更准也更费额度）。
探活载荷：自定义探测请求体（JSON），留空用内置最小载荷。

刚起步可以先不配探活——转发失败自动重试其他渠道的兜底始终存在；配了则保存后即触发首轮探测，是验证凭证最快的方式。

3.5 保存并验证

保存后渠道出现在列表里。验证凭证是否真的能用，两条路：

在抽屉里配好探活区块（3.4 节）再保存——保存即触发首轮探测，列表的健康列亮绿就是通过。
或直接跳到第 7 节发一个验收请求，能回模型就是全对。

探活成功 = Base URL + 凭证 + 至少一个模型全部正确。渠道行操作里没有单发探活的按钮（编辑 / 轮换凭证 / 禁用 / 删除），主动探测都在抽屉的探活区块里配置后自动执行。

保存成功但探活失败

常见原因：① 凭证复制时带了空格/换行——重新粘贴；② Base URL 写错协议头（少了 https://）；③ 上游账号没开通该模型；④ 上游有 IP 白名单没放行你的服务器出口 IP。

4. 配置价格

价目规则决定每次调用从用户额度里扣多少。进入计费与路由 → 定价：

4.1 新建价目规则

点击「新建价目规则」，核心字段：

字段	说明
模型	匹配的模型名，留空 = 通配所有模型
提示 / 1M（配额）	输入侧每百万 token 单价
补全 / 1M（配额）	输出侧每百万 token 单价
缓存写 / 读（配额）	可留空——留空自动按提示价 ×1.25 / ×0.1 推导
按次（配额）	每次调用固定计费；填了大于 0 的值该模型切换为按次计费
倍率（bps）	面向分组的整体价格倍率（10000 = 1.0×）
资源池 / 域	限定规则生效范围，留空全适用
时段窗口	分时定价：留空 = 全天一价；填两个时间 = 该时段另一价（见 4.2）
状态	启用 / 停用（停用的规则留在表里但不参与匹配）

4.2 分时定价（时段窗口）

模型厂商普遍分时定价（如夜间便宜）。同一模型的「时段窗口」填了起止时间后，该规则只在对应时段参与匹配并优先于全天规则；窗口外自动回退到留空（全天）的那条规则或默认价。语义要点：

北京时间（UTC+8）：窗口按 CST 墙上时间解释，与服务器时区无关。
半开区间：10:00-12:00 覆盖 10:00:00–11:59:59，12:00 整起不再命中。
跨午夜：结束时间早于开始时间即跨夜，如 22:00-06:00 覆盖 22:00–次日 06:00。
同模型同维度（域/池/层级）的多个窗口不可重叠，重叠会被拒绝；首尾相接可以（06:00-09:00 接 09:00-12:00）。
全天请留空，不要填 00:00-23:59——那会丢掉每天最后一分钟。
典型配置：一条全天基础价（窗口留空）+ 一条 22:00-06:00 夜间价，两条规则独立设价。

4.3 默认价格

规则没匹配到时的兜底单价在页面顶部的「默认价格」里设置（未配置时用引擎内置回退值）。刚起步配一条你主力模型的规则即可，其余交给默认价。

4.4 计费总开关

「系统 → 设置」里有计费开关（billing.enabled）。关掉计费 = 调用不扣费（适合先跑通链路再谈钱）；默认状态以你部署版本为准，验收前在设置页确认一眼。价目规则随时可改，下一次调用即生效。

渠道层级怎么影响价格

第 3.2 节的「层级（Tier）」填了值后，定价规则可以按 tier 键给同一模型在不同渠道上定不同价（如专线贵、 pooled 便宜）。起步全留空最省心。

5. 创建用户并充值

进入管理员 → 用户：

添加用户：填用户名、初始密码、角色（普通用户 user）、所属企业（可选）。平台不开放自助注册——新用户都从这里创建。
充值：用户行操作 →「调整余额」：
- 金额单位 USD，正数充值、负数扣回；
- 备注原因（可选，会记入流水，方便日后对账）。
流水（管理员 → 流水）里能看到每一笔余额变动与每次调用的计费明细——用户余额 == 流水净额 恒等，对不上就是 bug。

6. 签发令牌

令牌（sk- 开头）是程序调用网关的凭证。两条路：

管理员代发：管理员 → Token，新建令牌时选属主用户、可限额、可圈定分组/模型。
用户自助（推荐）：让用户自己登录控制台，在「账户 → API 密钥」页自签——管理员只在系统 → 设置里确认用户自签开关（keys.self_issue_enabled）开着即可；要收紧就关掉，改为全部走管理员代发。

明文查看规则（新签发的密钥都走了密文可逆存储）：

新建成功时立即复制最稳妥；忘了也不怕——管理员的 Token 页与用户的 API 密钥页都提供「显示密钥」重看（管理员侧重看受系统 → 设置的 keys.admin_reveal_enabled 开关门控，每次揭示留审计）。
管理面渠道凭证同理（轮换凭证入口旁的揭示）。
唯一例外：部署早于密文存储功能的历史令牌，再也无法重看——只能作废重建。

7. 发出第一个请求（验收）

现在链路上的一切都齐了：渠道（出口）→ 价格（扣费）→ 用户（账户）→ 令牌（凭证）。用第 0 节的网关地址（6200 端口，不是控制台那个端口）验收：

bash

curl http://<服务器地址>:6200/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的令牌" \
  -d '{
    "model": "你在模型投影里写的模型名",
    "messages": [{"role": "user", "content": "你好，词驿"}]
  }'

收到模型的 JSON 回复 = 从空机到转发成功的全链路打通。随后检查三处应发生的变化：

管理员 → 使用日志：出现这次调用的明细（模型、token 数、渠道）。
管理员 → 流水：出现这次调用的计费条目，用户余额相应减少（计费开着时）。
SDK 一样用——任何 OpenAI 兼容 SDK 把 base_url 指到 http://<服务器地址>:6200/v1 即可：

python

from openai import OpenAI

client = OpenAI(
    api_key="sk-你的令牌",
    base_url="http://<服务器地址>:6200/v1",
)
resp = client.chat.completions.create(
    model="你在模型投影里写的模型名",
    messages=[{"role": "user", "content": "你好，词驿"}],
)
print(resp.choices[0].message.content)

401 invalid token

令牌打错或被禁用。回令牌页用「显示密钥」重新复制；实在不行作废重建一个。

404 no routable channel / model not found

模型名不在任何启用渠道的模型投影里。回渠道页核对「对外模型名」与你请求里的 model 是否逐字一致。

402 余额不足

用户余额扣完了（或按次价格设得太高）。回用户页调整余额。

8. 验收清单

全部打勾，私有化部署就算完整落地：

[ ] 引导页完成，管理员能登录
[ ] 至少一条启用渠道，探活通过
[ ] 价目规则（或默认价）已配置
[ ] 已建用户并充值（或确认计费关闭）
[ ] 已签发 sk- 令牌
[ ] curl / SDK 第一次请求成功返回
[ ] 使用日志与流水出现该次调用记录

下一步

初始化（快速入门） ​

0. 你现在在哪 ​

1. 初始化引导页 ​

1.1 激活码（仅部署配置了激活码时出现） ​

1.2 管理员账户与密码 ​

1.3 完成与后续入口 ​

2. 认识管理台 ​

3. 接入第一个上游渠道 ​

3.1 基础信息 ​

3.2 调度参数 ​

3.3 模型投影 ​

3.4 探活（推荐配置） ​

3.5 保存并验证 ​

4. 配置价格 ​

4.1 新建价目规则 ​

4.2 分时定价（时段窗口） ​

4.3 默认价格 ​

4.4 计费总开关 ​

5. 创建用户并充值 ​

6. 签发令牌 ​

7. 发出第一个请求（验收） ​

8. 验收清单 ​