# 邀请、工单与账号

控制台里和账号相关的功能：登录注册、会话安全、邀请返利、提交工单、个人资料、通知邮箱、密码修改、TOTP 双因素认证、第三方 OAuth 授权绑定。网页端 AI 与技能市场已拆到 [AI Studio](#/console-ai-studio) 和 [技能市场与创作者中心](#/console-skills)。这些都是控制台用户功能,不要和公开模型网关 API 混淆。


---

## 登录、注册与会话安全

控制台登录注册走用户认证接口,不是网关 API Key 接口:

- 邮箱密码登录: `/auth/login`;如果返回 `requires_2fa`,页面会继续调用 `/auth/login/2fa` 输入 TOTP 动态码。
- 注册: `/auth/register`;如果站点开启邮箱验证或邀请码/推广码校验,页面会先调用 `/auth/send-verify-code`、`/auth/validate-invitation-code` 或 `/auth/validate-promo-code`。
- 当前用户: `/auth/me`,可带 `touch_active=true` 刷新活跃时间。
- 退出登录: `/auth/logout`;如果请求带 refresh token,服务端会撤销当前 token,前端无论撤销是否成功都会清理本地 `auth_token`、`refresh_token`、`token_expires_at`、`auth_user`。
- Token 刷新: `/auth/refresh`;refresh token 会轮换,过期、不存在、疑似复用/重放或 backend mode 禁止普通用户刷新时,页面会要求重新登录。安全页的“退出所有设备/吊销全部会话”走 `/auth/revoke-all-sessions`,会撤销当前用户全部 token。
- 忘记/重置密码: `/auth/forgot-password` 发送重置流程,`/auth/reset-password` 提交邮箱、token 和新密码。

密码重置功能可被站点关闭。关闭时 `/auth/forgot-password` 和 `/auth/reset-password` 都会返回 `PASSWORD_RESET_DISABLED`;功能开启时,为了防止枚举用户,不存在的邮箱、邮件队列异常或发送失败通常会静默成功,页面只提示“如果邮箱存在将收到邮件”。因此“忘记密码页面显示成功但没收到邮件”要同时检查垃圾箱、邮箱拼写、邮件配置和站点开关。

第三方登录/绑定可能进入 pending 流程:例如 OAuth 返回后需要补邮箱验证码、确认创建新账号、绑定到当前账号或采用第三方头像/昵称时,前端会使用 `/auth/oauth/pending/send-verify-code`、`/auth/oauth/pending/exchange`、`/auth/oauth/pending/create-account`、`/auth/oauth/pending/bind-login`。这些步骤只在对应入口和站点配置开启时出现。

OAuth pending 关键字段与真实错误:

| 流程 | 端点 | 主要字段 | 常见错误 |
|---|---|---|---|
| pending 新账号 | `/auth/oauth/pending/create-account` | `email`、`verify_code`、`password`、`invitation_code`、`aff_code`、`adopt_display_name`、`adopt_avatar` | `PENDING_AUTH_NOT_READY`、`SERVICE_UNAVAILABLE`、`PENDING_AUTH_ACCOUNT_ROLLBACK_FAILED`、`Pending oauth session provider mismatch` |
| pending 绑定已有账号 | `/auth/oauth/pending/bind-login` | `email`、`password`、`adopt_display_name`、`adopt_avatar` | `PENDING_AUTH_TARGET_USER_MISMATCH`、`Failed to create 2FA session`;若目标账号启用 2FA,响应可能带 `requires_2fa`、`temp_token`、`user_email_masked` |
| GitHub/Google 补注册 | `/auth/oauth/{github|google}/complete-registration` | `password`、`invitation_code`、`aff_code` | `Invalid request: ...`、`Pending oauth session provider mismatch` |
| LinuxDo/Wechat/OIDC/DingTalk 旧路径 | `/auth/oauth/{provider}/complete-registration` 或 `/bind-login` | 复用 pending create/bind 字段 | provider mismatch 或 pending session 过期 |

常见请求字段和限流口径:

| 场景 | 主要字段 | 限流参考 |
|------|----------|----------|
| 注册 `/auth/register` | `email`、`password`(至少 6 位)、`verify_code`、`turnstile_token`、`promo_code`、`invitation_code`、`aff_code` | 约 5 次/分钟 |
| 登录 `/auth/login` | `email`、`password`、`turnstile_token`;若返回 `requires_2fa` 再调 `/auth/login/2fa` | 约 20 次/分钟 |
| 发送验证码 `/auth/send-verify-code` | `email`、`turnstile_token` | 约 5 次/分钟 |
| 忘记/重置密码 | `/auth/forgot-password`、`/auth/reset-password` | 约 5/10 次/分钟 |
| 刷新 token `/auth/refresh` | refresh token | 约 30 次/分钟 |

`/auth/me?touch_active=true` 会刷新 last active,响应里还会带 `run_mode`。如果看到“登录态还在但刷新失败”,优先清理本地 token 后重新登录,不要把控制台 JWT 当模型 API Key 使用。

邀请码/推广码验证会返回更细的 `error_code`,例如 `PROMO_CODE_DISABLED`、`PROMO_CODE_NOT_FOUND`、`PROMO_CODE_EXPIRED`、`PROMO_CODE_MAX_USED`、`PROMO_CODE_ALREADY_USED`、`PROMO_CODE_INVALID`、`INVITATION_CODE_DISABLED`、`INVITATION_CODE_NOT_FOUND`、`INVITATION_CODE_INVALID`、`INVITATION_CODE_USED`。

注册邮箱后缀白名单开启时,不在允许范围内会返回 `EMAIL_SUFFIX_NOT_ALLOWED`。错误 metadata 里会带 `allowed_suffixes` 和 `allowed_suffix_count`;前端可直接提示允许的域名后缀,不要把它当成验证码或密码错误。

认证接口限流依赖 Redis;若 Redis 异常,服务按 fail-close 处理,可能表现为验证码/登录/重置被临时限制。常见错误包括 `Invalid request: ...`、`Failed to generate token`、`登录暂不可用`。

---

## 邀请返利

通过你的专属**邀请链接**邀请他人注册使用，可获得返利。该页来自 `/user/aff`,明细 ledger 来自 `/user/aff/invitees/{id}/ledger`,转余额走 `/user/aff/transfer`。

- 在「**邀请**」页拿到你的专属链接或邀请码，分享出去
- 页面会显示**邀请人数**、**累计返利**和可转余额
- 被邀请人充值/消费后，按规则给你返利（具体比例、冻结期、上限以页面说明为准）
- 可把已解冻返利**转入账户余额**，转入后就能像普通余额一样用于 API 调用

邀请功能可能受站点开关控制。如果页面没有「邀请」入口,说明当前站点未开放或你的账号暂不可用。

### 邀请明细与 ledger

邀请页可查看每个被邀请人的明细：注册时间、充值/消费、返利记录、冻结/解冻状态、转余额记录等。遇到“为什么这笔还没到账”时，先看对应 invitee 的 ledger；如果仍不清楚，提交工单并附上被邀请人、时间和记录截图。

---

## 工单

遇到账户、充值、退款、报错等问题，提交**工单**联系支持。

- 入口：控制台「**工单**」→ 新建；列表来自 `/tickets`,详情来自 `/tickets/{id}`
- 工单支持咨询、退款、并发/限速、倍率/计费、其他问题等类型；创建/编辑会提交 `title`、`category`、`form_payload`、`expected_revision_no`
- 可上传附件：截图、日志、CSV、报错文本等；附件上传走 `/media/upload`,并带 `biz_type=ticket`、`biz_id`、`visibility=private`,回复时用 `attachments: [{ media_id }]` 关联
- 提交后可在工单列表查看回复与状态流转；回复走 `/tickets/{id}/messages`,草稿提交走 `/tickets/{id}/submit`,撤回/关闭分别走 `/withdraw`、`/close`
- 草稿/待提交工单可继续编辑、提交或撤回;已关闭工单如问题复现,建议新建工单并引用旧工单号。

工单功能也可能受站点开关控制;入口不可见时可使用站点提供的其他联系方式。

列表筛选支持 `page`、`page_size`、`status`、`category`、`search`、`start_date`、`end_date`、`timezone`、`sort_by`、`sort_order`。日期格式不合法会返回 `invalid start_date` / `invalid end_date`;开始时间晚于结束时间会返回 `invalid date range`。

编辑和提交草稿使用乐观锁:请求体可带 `expected_revision_no`,也可用 `If-Match` header。多人或多标签页同时编辑时,可能返回 `TICKET_REVISION_REQUIRED`、`TICKET_REVISION_CONFLICT`、`TICKET_NOT_EDITABLE`;处理方式是刷新详情,基于最新 revision 重新编辑。回复正文为空或过大会返回 `TICKET_MESSAGE_REQUIRED` / `TICKET_MESSAGE_TOO_LARGE`;附件上传若媒体服务关闭会返回 `MEDIA_STORAGE_DISABLED`,工单被锁定时回复会返回 `TICKET_REPLY_LOCKED`。

### 附件与媒体上传

用户媒体接口包括 `/media/upload`、`/media/{id}`、删除、可见性更新、预签名下载和缩略图下载；公开访问/签名下载有独立路由。工单附件一般使用 `biz_type=ticket`、`visibility=private`;`visibility` 只接受 `private` 或 `public`,默认 `private`,空 `biz_id` 会归到 `unassigned`。默认单文件大小约 64MB。常见媒体错误码:`MEDIA_FILE_REQUIRED`、`MEDIA_FILE_TOO_LARGE`、`MEDIA_BIZ_TYPE_INVALID`、`MEDIA_VISIBILITY_INVALID`、`MEDIA_SIGNATURE_INVALID`、`MEDIA_SIGNATURE_EXPIRED`、`MEDIA_FORBIDDEN`、`MEDIA_NOT_FOUND`。

常见状态：

| 状态 | 含义 |
|------|------|
| 待处理 / Open | 已提交，等待支持查看 |
| 处理中 / In Progress | 支持正在排查或等待外部结果 |
| 等待用户 / Waiting User | 需要你补充截图、订单号、Request ID 等信息 |
| 已解决 / Resolved | 已给出处理结果 |
| 已关闭 / Closed | 工单结束；如问题复现可重新提交 |

**怎么提问效率高：**

- 带上**完整报错截图**（别只截一部分）
- 说明你的密钥**分组名**和用的**工具/模型**
- 提供 Request ID、错误请求 `id`、订单号、发票号或时间范围
- 描述复现步骤：什么命令、Base URL/端点、模型、Key 名称/分组、是否流式、是否换过线路、出现什么
- 附件只做补充:请在正文里写出关键字段,再上传终端 `curl -i` 输出、工具配置截图、用量/错误详情截图或支付凭证

> 报错类问题，先对照 [故障排查](#/troubleshooting) 自助排查——大部分（分组不匹配、余额不足、网络/代理）都能自己解决，省去等待。

---

## 个人资料与通知邮箱

「**个人中心**」可管理账号信息：

- 查看资料：`/user/profile`
- 编辑资料：`PUT /user` 支持 `username`、`avatar_url`、余额通知开关与阈值、额外通知邮箱列表；头像支持 http(s) URL 或有效 image data URL,内联头像最大约 100KB
- 修改密码：`PUT /user/password`,提交 `old_password` 和 `new_password`
- 设置**通知邮箱**：用于余额提醒、账号通知、工单/发票/支付相关通知
- 查看**平台额度**：`/user/platform-quotas` 会返回当前用户各平台额度与已用量（入口可见时显示）

资料响应可能展示 `avatar_source`、`username_source`、`display_name_source`、`nickname_source`、`profile_sources`,用于说明资料来自本地还是第三方 OAuth。用户对象还可能含 `last_login_at`、`last_active_at`、余额通知字段和订阅摘要。

通知邮箱通过 `/user/notify-email/send-code` 发送验证码,再用 `/user/notify-email/verify` 添加；之后可用 `/user/notify-email/toggle` 启停某个邮箱,或 `DELETE /user/notify-email` 移除。额外通知邮箱最多 3 个；验证码 15 分钟有效,同邮箱 1 分钟冷却,最多 5 次尝试,用户级发送限制约 10 分钟 5 次。`NotifyEmailEntry` 包含 `email`、`disabled`、`verified`。常见错误:`VERIFY_CODE_TOO_FREQUENT`、`VERIFY_CODE_MAX_ATTEMPTS`、`NOTIFY_CODE_USER_RATE_LIMIT`、`TOO_MANY_NOTIFY_EMAILS`、`EMAIL_NOT_FOUND`。

---

## TOTP 双因素认证

TOTP（2FA）可用 Google Authenticator、1Password、Microsoft Authenticator 等动态验证码 App 提升登录安全。

基本流程：

1. 进入「个人中心」→「双因素认证」；页面先用 `/user/totp/status` 判断功能是否开启、当前账号是否已启用
2. 页面会先请求 `/user/totp/verification-method`,按返回结果用邮箱验证码或密码验证身份
3. 如验证方式需要邮箱码,先调用 `/user/totp/send-code`;验证通过后 `/user/totp/setup` 返回二维码、密钥和 `setup_token`,再扫描二维码或复制密钥到验证器 App
4. 输入 6 位动态验证码和 `setup_token`,调用 `/user/totp/enable` 完成启用

关闭 TOTP 走 `/user/totp/disable`,也需要再次验证身份。启用后请妥善保存恢复方式，避免换手机后无法登录。

字段细节:

- `/user/totp/setup` 可提交 `email_code`、`password` 做身份确认;成功返回 `secret`、`qr_code_url`、`setup_token`、`countdown`。
- `/user/totp/enable` 要提交 6 位 `totp_code` 和 `setup_token`。
- `/user/totp/disable` 可提交 `email_code`、`password`。未登录会返回 `User not authenticated`,字段不对会返回 `Invalid request: ...`。
- 身份确认方式由 `/user/totp/verification-method` 决定:返回 `email` 时需要先 `/user/totp/send-code`,再带 `email_code`;返回 `password` 时带当前密码。若邮箱验证未开启却调用发送验证码,会返回 `EMAIL_VERIFY_NOT_ENABLED`;缺字段会返回 `VERIFY_CODE_REQUIRED` 或 `PASSWORD_REQUIRED`。
- 常见 TOTP 错误码:`TOTP_NOT_ENABLED`、`TOTP_ALREADY_ENABLED`、`TOTP_NOT_SETUP`、`TOTP_INVALID_CODE`、`TOTP_SETUP_EXPIRED`、`TOTP_TOO_MANY_ATTEMPTS`。短时间多次输错动态码后,先等冷却再试。

---

## 绑定 / 解绑第三方授权

支持把账号与多种登录方式绑定，绑定后即可用对应方式快捷登录。具体可见方式取决于 `/settings/public` 和站点开关：

| 方式 | 说明 |
|------|------|
| 邮箱 | 基础登录，用于找回与通知 |
| LinuxDo | 社区账号登录 |
| GitHub | 开发者常用 |
| Google | 谷歌账号 |
| 微信 | 扫码登录 |
| 钉钉 | 企业场景 |
| OIDC | 企业统一身份 |

在「个人中心」找到对应入口，前端会先请求 `/auth/oauth/bind-token`,再跳转到 `/auth/oauth/{provider}/bind/start?intent=bind_current_user` 完成绑定；不再使用时可调用 `/user/account-bindings/{provider}` 解绑。邮箱绑定单独走 `/user/account-bindings/email/send-code` 和 `/user/account-bindings/email`,需要邮箱验证码和当前密码。第三方绑定 start 可带 `provider`、`redirect_to`;邮箱绑定提交 `email`、`verify_code`、`password`。解绑第三方身份成功后会撤销当前用户全部 token,页面可能要求重新登录。建议至少保留一种稳定可用的登录方式，避免误解绑导致无法登录。

补注册差异要注意:GitHub/Google 的 `/complete-registration` 只补 `password`、`invitation_code`、`aff_code`;LinuxDo/Wechat/OIDC/DingTalk 等旧路径会复用 pending create/bind 流程,可能要求邮箱、验证码、密码以及是否采用第三方昵称/头像。看到 `Pending oauth session provider mismatch` 时,通常是授权入口和补注册入口的 provider 不一致或旧 pending session 被复用。

> **绑定/登录时遇到 OAuth 验证错误？** 多为代理环境所致——请先**完全关闭翻墙/代理软件**再授权；若浏览器没自动跳转，可复制终端/页面里的链接手动打开完成验证。详见 [故障排查](#/troubleshooting)。

如果绑定邮箱或通知邮箱时收不到验证码,先检查垃圾箱、邮箱拼写和发送频率限制;短时间内多次点击发送可能触发冷却,等待几分钟再试。


---

## 网页端 AI 与技能市场入口

网页端 AI、提示词、图库、图片编辑详见 [AI Studio：网页 AI、图片图库与 Prompt 模板](#/console-ai-studio)。技能市场、安装、版本审核、运行记录和收益详见 [技能市场与创作者中心](#/console-skills)。

> 这些入口服务的是浏览器内体验;终端、SDK 和 Claude Code/Codex/Grok 的模型调用仍使用你创建的 API Key 和公开网关端点。充值与发票见 [订阅与余额](#/console-billing)；用量见 [用量明细](#/console-usage)。