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

77 lines
7.2 KiB
Markdown
Raw 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 不能调用模型。
- 在线调试:模型和分组直接下拉选择;无需返回模型广场。
- 用户与额度:管理员可直接开通普通账号、创建邀请、发放人民币金额并查看流水;只有超级管理员能升降管理员角色。
`/api/models` 保留 `models`(分组/调用路由列表),新增 `logicalModels`(模型定义)。调用仍使用分组的 `id` 作为 `/v1/chat/completions` 的 `model` 值;`modelKey` 是可编辑的展示标识,不是自动路由或授权通配符。
## 旧数据升级
Flyway V10 自动将每条旧目录项转换为一个模型和一个既有分组;保留旧调用 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 万元。发放必须填写原因,记录操作者、时间、金额和发放后余额;使用事务、钱包行锁和请求编号去重。发放请求遇到网络不确定状态时,原弹窗重试沿用同一个编号,不会重复发放。
本次完成的是余额、发放、查询、流水与审计;不是充值支付或自动扣费。分组价格目前是报价元数据,不能把美元报价或每千/百万 token 单位直接用于人民币扣费。网关尚不根据余额拦截或结算;对外收费前仍必须实现明确币种和计费单位、预占额度、成功结算、失败退回及对账。优先级也尚未用于自动故障切换。
## 本地验证
`PlatformAdminPostgresTest` 仅接受 `127.0.0.1` 的 `MOYI_AUTH_TEST_JDBC_URL`,使用 `moyi_role_test` 测试角色与随机 schema;覆盖迁移、精确分组授权、编辑/停用、直接开户权限、额度并发去重,以及邮箱/手机验证码、锁定、过期、重复提交与发送失败。测试发送器不接入外部服务。