注册 API
注册 API
XSI 内置邮箱自助注册。注册通过激活链接完成:用户提交邮箱,收到邮件后打开链接确认,账号随即创建,API Key 显示在确认页面并通过欢迎邮件发送。
- 总开关:环境变量
SIGN_ENABLE(默认true)。关闭时所有/x-sign请求返回403 {"success": false, "message": "Self-registration is currently disabled"}。 - 依赖邮件服务:激活邮件通过 Redis 队列交给独立的邮件服务投递,开放注册前请先完成邮件配置。
- 新账号的归属取决于部署模式,见账号归属。
流程
POST /x-sign ──▶ 激活邮件(链接 10 分钟内有效)
│
▼
GET /x-sign/activate?token=... ──▶ 确认页面
│ (用户点击确认)
▼
POST /x-sign/activate ──▶ 创建账号,页面显示 API Key,并发送欢迎邮件打开链接(GET)只显示确认页面,不会创建账号,以免邮件安全扫描器预取链接造成误激活。
发送激活邮件
curl -X POST "$XSI_BASE_URL/x-sign" \
-H "Content-Type: application/json" \
-d '{"email": "[email protected]", "referral_code": "pk-Xvs..."}'| 字段 | 必填 | 说明 |
|---|---|---|
email | 是 | 邮箱,自动转为小写 |
referral_code | 否 | 推荐人的公开标识(pk-Xvs...,见 GET /dashboard/status 的 public_key)。XAI_REFERRAL_REWARD_RATE 为 0 时忽略 |
成功响应:
{"success": true, "message": "Verification code sent successfully", "data": {"email": "[email protected]"}}所有响应都是 {"success", "message", "data"} 结构。业务错误返回 400,message 为原因:
message | 原因 |
|---|---|
Invalid email address | 邮箱格式不正确 |
Email domain is not allowed for self-registration | 不满足注册域名策略 |
Email already registered | 邮箱已注册 |
invalid referral code | 推荐码不存在或推荐人已停用 |
Please wait before requesting another verification code | 同一邮箱 2 分钟内重复请求 |
Too many verification codes requested from this IP today | 同一 IP 当日超过 10 次 |
Failed to send verification email | 邮件入队失败 |
激活
激活邮件中的链接为 https://<XAI_API>/x-sign/activate?token=<48 位令牌>。
GET /x-sign/activate?token=...:返回 HTML 确认页面。POST /x-sign/activate(表单字段token):创建账号并返回 HTML 成功页,页面显示新账号的 API Key,并提供进入控制台的按钮(多租户部署指向XAI_ADMIN,单租户指向XAI_MANAGE)。- 令牌无效或过期时显示
Invalid or expired activation link。
创建的账号:
| 属性 | 值 |
|---|---|
| 账号名 | 随机系统名(单租户 u_ 前缀,多租户 o_ 前缀) |
| 显示名 | 由邮箱前缀生成 |
| API Key | 新生成的 51 位 sk-Xvs Key,另生成公开标识 pk-Xvs... |
| 注册赠金 | XAI_CREDIT(代码默认单租户 2、多租户 120;部署模板为 0),有效期 1 个月 |
| 子账号名额 | 1 |
账号归属
| 部署模式 | 新账号 |
|---|---|
单租户(SINGLE_TENANT=true,默认) | 成为 root 租户下的普通账号,继承 root 的 Level、Gear、Role、价格与限速 |
多租户(SINGLE_TENANT=false) | 成为一个新的租户所有者,拥有独立的 Key 池、配置与价格,登录配置管理控制台后录入自己的上游 Key |
注册域名策略
由 root 通过 /x-config 的 SIGNUP_ALLOW_DOMAINS 与 SIGNUP_DENY_DOMAINS 设置,对所有注册生效,语法见《租户配置 API》。
反滥用保护
SAFE_ENABLE(默认 true)开启时生效。除“不同邮箱数”只在 POST /x-sign 中检查(超限返回 400)外,其余限制由 POST /x-sign 与 POST /x-sign/activate 共享:
| 限制 | 默认值 |
|---|---|
| 每分钟 / 每小时 / 每天请求数 | 3 / 10 / 20 |
| 每 IP 每天不同邮箱数 | 5 |
| 全站每日注册请求 | 10000 |
| 渐进延迟 | 同一小时内请求越多,服务端等待越久(最长 15 秒) |
| 自动封禁 | 可疑行为累计达到阈值后封禁 3 小时 |
被频率或全站配额拒绝时返回 429,正文为 {"success": false, "message": "..."}。识别出的客户端 IP 仍是受信代理地址时,按 IP 的限制不生效。客户端 IP 的识别依赖 TRUSTED_PROXY_CIDRS,请确保反向代理正确传递真实 IP,见《反向代理》。