Files
moyi-model-intelligence-hub/docs/13-model-groups-registration-credit.md

80 lines
7.8 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 模型分组、注册验证与人民币额度
## 本次变更
- 渠道:独立维护名称、Code、来源类型、协议、Base URL、凭据和启停状态。编辑时凭据留空保留原值;选择“不使用凭据”才清除。
- 模型:独立维护名称、标识、能力类型和调用模式。
- 分组:在模型下添加,自定义名称、选择渠道、填写上游模型 ID、报价、并发上限;均可再次编辑。
- Key:先选模型,再勾选该模型的分组,可继续切换模型配置其他分组。授权只包含已保存的分组,不自动扩展到未来新增分组。清空授权后 Key 不能调用模型。
- 在线调试:模型和分组直接下拉选择;无需返回模型广场。
- 用户与额度:管理员可直接开通普通账号、创建邀请、发放人民币金额并查看流水;只有超级管理员能升降管理员角色。
- 邀请记录:新创建的邀请码会以加密形式保存在专用数据库中,管理员可在“用户与额度 → 邀请码记录”再次复制或停用;升级前已经创建的旧邀请码只保留哈希和前缀,不能恢复原文。
- 账号设置:用户菜单中的“账号设置”可以修改显示名称和密码;修改密码必须验证当前密码,普通用户新密码至少 8 位,超级管理员沿用其自定义长度规则。
- 统一 API 地址:生产前端按当前访问域名生成 `https://<域名>/v1`,本地开发仍使用开发环境的 Control Plane 地址。
`/api/models` 保留 `models`(分组/调用路由列表),新增 `logicalModels`(模型定义)。调用仍使用分组的 `id` 作为 `/v1/chat/completions` 的 `model` 值;`modelKey` 是可编辑的展示标识,不是自动路由或授权通配符。
## 旧数据升级
Flyway V10 自动将每条旧目录项转换为一个模型和一个既有分组;V11 为新邀请码增加加密副本;保留旧调用 ID、Key 权限及凭据。为避免错误合并,不按名称自动合并旧模型。需要合并时,在“编辑分组”中更改所属模型,再停用已无分组的旧模型即可。
停用渠道、模型或分组后,对应调用立即不可用;旧 Key 的既有授权仍保留,重新启用后恢复。不能给 Key 新增已停用分组的权限。同一模型内分组名称不能重复。
升级前备份 RDS 的专用数据库、`.env.cloud`、认证 pepper、凭据加密密钥及证书。不要连接或修改其他业务库。V10 上线后不要直接回滚到会写入旧目录结构的旧程序;需要回滚时使用升级前备份和对应旧版本。
旧版 `20260917-202503-f5ba6cb2` 尚无验证码实现和 SMTP/SMS 环境变量映射;只改 `.env.cloud` 或重启旧容器不会启用验证码。必须升级后端、前端及 Compose。复制旧配置到新发布目录,保留所有密钥和新填的 SMTP/SMS 参数,只更新镜像版本与运行时 Dockerfile 设置。
新包提供 `infra/moyi/backup_database.py`,在运行新版本 `up` 之前执行:
```bash
# 在新发布目录的 infra/moyi 下运行;指向当前仍在运行的旧版本。
python3 backup_database.py --deployment-dir /opt/moyi/releases/20260917-202503-f5ba6cb2/infra/moyi --mode https
```
工具核对运行容器、数据库及加密配置,只导出 `moyi_control`;同时保存旧 `.env.cloud`(含 SMTP/SMS)和证书,在 `/opt/moyi/backups/pre-upgrade-*` 创建私有备份。导出后读取整个归档并生成校验清单,成功才输出 `BACKUP_OK`。此检查不等同于向独立数据库实际恢复的演练。备份期间停止人工测试并保持配置不变;命令失败时不要继续升级。备份是一个一致性快照,备份后的新写入不包含在其中。
升级后运行 `python3 deploy.py smoke --mode https --login` 和 `curl --fail --silent --show-error https://moyi.soulofmodel.com/api/auth/verification`。后者只检查发送通道是否配置,不发送验证码;`email: true` 不是投递成功的证明。再通过注册页面用有效邀请码和自己控制的邮箱/手机号完成真实收发与注册验收。
## 邮箱和短信配置
注册现在同时要求有效邀请码和 6 位验证码。邮箱、手机号二选一注册,不要求每个人同时验证两种联系方式。手机目前支持中国大陆号码(可带 `+86`)。登录仍使用账号和密码。管理员直接开户不需要验证码,不会自动取得管理员权限。
未配置的发送通道显示“暂不可用”,不会生成假成功;管理员仍能直接开户。密码找回不在本次实现范围内。
在服务器当前发布目录的 `infra/moyi/.env.cloud` 中填写以下变量,不提交到 Git,不将完整凭据发到聊天中。包含 `$`、`#` 等字符的值用单引号。
| 邮箱变量 | 内容 |
| --- | --- |
| `MOYI_SMTP_HOST` | 邮箱服务商的 SMTP 主机 |
| `MOYI_SMTP_PORT` | 通常为 `465`(SSL)或 `587`(STARTTLS),以服务商为准 |
| `MOYI_SMTP_FROM` | 已验证的发件邮箱 |
| `MOYI_SMTP_USERNAME` | SMTP 登录账号 |
| `MOYI_SMTP_PASSWORD` | SMTP 密码或邮箱授权码 |
| `MOYI_SMTP_SSL` | 465 通常设为 `true`;587 通常为 `false` |
| `MOYI_SMTP_STARTTLS` | 587 通常设为 `true`;465 通常为 `false` |
阿里云短信操作:
1. 打开短信服务控制台,完成资质并申请中国大陆短信签名。
2. 申请验证码模板,模板变量使用 `${code}`,有效期文案为 5 分钟;等待签名和模板审核通过。
3. 建立专用于本项目短信发送的 RAM 凭据,按官方文档授予 `dysms:SendSms` 所需最小权限,不复用其他业务或主账号 AccessKey。
4. 填入 `MOYI_SMS_ACCESS_KEY_ID`、`MOYI_SMS_ACCESS_KEY_SECRET`、`MOYI_SMS_SIGN_NAME`、`MOYI_SMS_TEMPLATE_CODE`。
5. 在阿里云设置发送频率及费用预警,确认短信余额与服务器到短信服务的 HTTPS 出站连接。
6. 使用部署脚本重建/重启新版本容器,让环境变量生效;不要只在页面刷新。用自己控制的邮箱和手机号各做一次真实验证码收发验收。
官方资料:[短信 API 接入](https://help.aliyun.com/zh/sms/getting-started/use-sms-api)。本地测试不调用真实发送服务,配置完成后仍需上述真实发送验收。
验证码 5 分钟有效,错误 5 次后失效,一次性使用。发送限制为同一账号 60 秒间隔、每账号每日 10 次、每来源 IP 每小时 30 次、全平台每日 1000 次;失败的发送请求也占用频率额度。哈希存储验证码,不写入日志或返回前端。发送记录保留最近 2 天。公司共享出口 IP 也共享来源 IP 额度。
云端 Nginx 覆盖客户端转发 IP,并清除外部 `Forwarded`,Java 后端不直接发布公网端口。自行新增代理时需维护这一信任边界,否则来源 IP 限制可能失效或合并。
## 人民币额度边界
发放金额以人民币元输入,最多两位小数、必须大于 0,单笔上限 100 万元。发放必须填写原因,记录操作者、时间、金额和发放后余额;使用事务、钱包行锁和请求编号去重。发放请求遇到网络不确定状态时,原弹窗重试沿用同一个编号,不会重复发放。
最初版本只提供人工余额调整;V13 已补充文本聊天余额预留、成功结算、失败释放和防重复扣费,见 [流式与计费](16-streaming-chat-billing.md)。分组必须明确人民币 / 百万 Token 的输入、输出售价,不能直接沿用美元报价。支付充值和按优先级自动故障切换仍未实现。
## 本地验证
`PlatformAdminPostgresTest` 仅接受 `127.0.0.1` 的 `MOYI_AUTH_TEST_JDBC_URL`,使用 `moyi_role_test` 测试角色与随机 schema;覆盖迁移、精确分组授权、编辑/停用、直接开户权限、额度并发去重,以及邮箱/手机验证码、锁定、过期、重复提交与发送失败。测试发送器不接入外部服务。