常见问题

🚧 本章节持续完善中，问题分类与答案将陆续补充。欢迎在 GitHub Issues 提问。

部署相关

• Docker 启动后无法访问，如何排查？
• 数据库迁移失败 / 卡住怎么办？
• 如何从旧版本升级？会不会丢数据？

系统配置相关

系统添加模型的步骤是怎么样的？

1. 新增模型：在管理后台 → 模型配置新增模型，填写模型标识（即 API 请求中的 model 参数，创建后不可修改）、分类、上下文 / 输出上限等参数，可点击「拉取官方数据」自动填充；
2. 渠道承接：新增渠道或选择已有渠道，进入渠道详情，在「模型能力」中添加该模型（上游模型名不同时需填写映射），添加完成后到「测试」Tab 发一条真实请求，验证模型真实可用（当前仅支持文本对话类模型）；
3. 授权：将新模型加入特定模型分组，或授权给指定租户；
4. 设置价格：在模型列表点击「定价」设置基准价——没有价格的模型无法调用。

详细操作见模型配置与渠道配置。

如何设置套餐？

系统当前仅支持按量付费：用户充值进入钱包余额，按实际用量实时扣费，不支持套餐订阅。

模型定价层面支持按量 / 按次 / 阶梯三种计费模式，见模型定价。

用户如何付款？

1. 管理员在系统中配置易支付；
2. 用户在租户控制台的钱包充值页选择面额、完成支付，到账后余额实时增加。

充值面额、折扣、汇率、支付说明等全局参数见支付配置。

什么是易支付？

易支付（EPay）是国内广泛使用的一套聚合支付接口协议及配套自建系统（最早源于开源项目「彩虹易支付」）。平台方部署易支付系统后，统一对接支付宝、微信支付等收款渠道；商户侧只需对接易支付一套接口即可收款，无需逐个申请支付宝 / 微信官方商户号。

对接流程：

1. 用户发起充值，系统按易支付协议提交订单（submit.php 接口），跳转到收银台；
2. 用户扫码 / 完成支付；
3. 易支付平台通过异步通知（notify_url）回调系统确认到账，钱包余额随即入账。

对接时通常需要填入网关地址、商户 ID（pid）、商户密钥三类参数。

谨慎选择服务商

易支付平台多为第三方「四方支付」，资质与资金安全参差不齐，存在掉单、跑路与合规风险。请选择可靠的服务商，大额或长期业务建议使用官方支付渠道。

渠道相关

• 渠道测试通过但正式请求报错？
• 为什么请求没有走优先级最高的渠道？
• 如何配置渠道权重与故障转移？

计费相关

• 流式响应的 Token 用量如何统计？
• 预扣和实际结算金额为什么有差额？
• 套餐额度与钱包余额的扣费顺序？

账号与权限

• 忘记管理员密码怎么办？
• 租户成员角色有哪些权限区别？

API 调用相关

• 报 401 / 403 是什么原因？
• 报 429 限额错误如何定位是哪一层额度不足？
• 图片 / 语音 / 实时接口有什么特殊要求？