用户自助资料管理

返回 README

重要 — 身份层操作必须在 OAuth profile 完成，下游禁止代理

改邮箱、改密码、注销账号、管理登录设备这类操作只能走 OAuth 自己的前端（https://oauth.kungal.com/profile）。kungal / moyu / wiki 都不要在自己前端实现这些 UI，即使技术上可以代理 JWT。详细分类见下表。

身份操作 vs 展示操作

OAuth 的用户自助 API 在设计上分两层。下游接入时不要把所有写操作都拉到自己前端做——身份层修改强制走 OAuth profile，展示层可以站内提供 UI。

身份层（OAuth profile 专用，下游用跳转模式）

凡是涉及"账号所有权"的操作，必须由 OAuth 自己的前端承担。原因：流程敏感、需要集中审计、未来要加 2FA / 异地通知 / 安全日志时只改一处。

下游正确做法：在账号设置页放一个"跳转到 OAuth 账号中心"按钮，附带 return 参数让用户改完跳回：

<NuxtLink
  :to="`https://oauth.kungal.com/profile?return=${encodeURIComponent(currentUrl)}`"
  external
  class="..."
>
  修改邮箱 / 密码
  <Icon name="lucide:external-link" class="ml-1 size-3" />
</NuxtLink>

下面那些端点的文档保留为完整性目的——OAuth 自己的前端 (apps/web) 是唯一应该调用它们的客户端。kungal / moyu / wiki 前端不要直接 fetch 这些路径。

展示层（任何接入站都可以代理 / 自己实现 UI）

这些可以站内提供 UI（"代理模式"），也可以跳转（"跳转模式"，更一致），任选。PATCH /auth/me 和 POST /auth/me/avatar 要求带终端用户 JWT，不是 OAuth Client Basic Auth。

---

端点速览

---

GET /auth/me

获取当前登录用户的完整资料。与 /oauth/userinfo 的区别：/auth/me 是面向 OAuth 自己前端的内部端点，无 scope 过滤、字段更全（含 moemoepoint）。下游服务若用得着也可以调。

请求头：Authorization: Bearer <access_token>

成功响应：

{
  "code": 0,
  "data": {
    "uuid": "550e8400-e29b-...",
    "name": "kun",
    "email": "[email protected]",
    "avatar": "https://...",
    "bio": "...",
    "moemoepoint": 1234,
    "status": 0,
    "roles": ["user", "admin"],
    "created_at": "2024-01-01T00:00:00Z"
  }
}

---

PATCH /auth/me

修改当前登录用户的展示字段。所有字段都可选，不传的字段保持不变。

请求头：Authorization: Bearer <access_token>

请求体：

{
  "name": "newname",
  "avatar": "https://...",
  "avatar_image_hash": "abc123...",
  "bio": "新简介"
}

字段都用指针类型语义：没传 = 不动；传了 = 设为该值（包括传空字符串 = 清空）。

成功响应：返回更新后的完整 UserResponse（同 GET /auth/me 的 data shape）。

错误响应：

修改 email 不在这里 —— email 必须走 /auth/email/send-code + /auth/email（带验证码的两步流程，防止账号被劫持）。

修改 password 也不在这里 —— password 必须走 /auth/password（需要旧密码或重置 token）。

举例：仅改头像 hash（image_service 上传完毕之后）：

curl -X PATCH https://oauth.kungal.com/api/v1/auth/me \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"avatar_image_hash":"abc123def456..."}'

---

POST /auth/me/avatar

2026-05-23 新增：一次性"上传头像图片 → 写入用户记录"端点，避免下游 kungal / moyu 自己维护 image_service client。

直接接收图片二进制（multipart），OAuth 内部转发到 image_service，并在响应返回前把拿到的 hash 写入当前用户的 avatar_image_hash。调用方拿到响应时数据库已经更新，无需再调 PATCH /auth/me。

请求头：Authorization: Bearer <access_token>

请求 body：multipart/form-data

成功响应：直接透传 image_service 的上传结果。

{
  "code": 0,
  "data": {
    "hash": "abc123def456...",
    "url": "https://image.kungal.iloveren.link/ab/c1/abc123def456....webp",
    "variant_urls": {
      "256": "https://image.kungal.iloveren.link/ab/c1/abc123def456..._256.webp",
      "100": "https://image.kungal.iloveren.link/ab/c1/abc123def456..._100.webp"
    },
    "width": 512,
    "height": 512,
    "size_bytes": 38241,
    "deduplicated": false
  }
}

variant_urls 提供 256 / 100 像素的预生成缩略图，前端列表 / 评论场景直接用 100，主页 / 个人页用 256，原图（url）一般不需要展示。deduplicated=true 表示同 hash 文件以前传过，image_service 复用了已有对象，没有额外存储成本。

错误响应：

和现有方式的关系：

两种方式可以并存，下游想用哪种都行。avatar 和 avatar_image_hash 仍是独立字段（参见 PATCH /auth/me 节）。

配额归属：图片走的是 OAuth 自己的 image_service client，配额从 OAuth 这一侧扣，下游 kungal / moyu 不需要为头像单独申请 image_service client。

CORS：浏览器直传需要 OAuth 在 CORS 配置里允许下游 origin 上 POST + Authorization header，目前 *.kungal.com 已包含；新增子域接入前请确认。后端代理模式（kungal/moyu 后端接 multipart 再转发）天然不受 CORS 影响。

举例：

curl -X POST https://oauth.kungal.com/api/v1/auth/me/avatar \
  -H "Authorization: Bearer <access_token>" \
  -F "[email protected]"

浏览器版本：

const fd = new FormData()
fd.append('file', file)  // <input type="file"> 的 File 对象
const r = await fetch('https://oauth.kungal.com/api/v1/auth/me/avatar', {
  method: 'POST',
  headers: { Authorization: `Bearer ${accessToken}` },
  body: fd  // 注意：不要手动设 Content-Type，让浏览器自动带 boundary
})
const { data } = await r.json()
// data.hash 已经被 OAuth 写入了用户记录，下一次 GET /auth/me 就能看到新头像

---

身份层端点

下面三个端点仅供 OAuth 自己的前端（apps/web）使用。kungal / moyu / wiki 等下游接入站不应直接调用，应该跳转到 OAuth profile 让用户在那里完成。原因和跳转示例见本文档开头的"身份操作 vs 展示操作"小节。

POST /auth/email/send-code

发送邮箱变更验证码。验证码寄到用户当前的旧邮箱（不是新邮箱）—— 这是关键的安全设计：JWT 被窃后，攻击者也无法收到验证码完成劫持。

请求头：Authorization: Bearer <access_token>

请求体：

{ "new_email": "[email protected]" }

成功响应：

{ "code": 0, "message": "验证码已发送到当前邮箱", "data": null }

验证码 6 位数字，默认有效期 15 分钟（由 KUN_AUTH_VERIFICATION_CODE_TTL_MINUTES 配置；改邮箱 / 注册 / 任何走 Redis 6 位码的流程共用此值）。

错误响应：

---

PUT /auth/email

用旧邮箱收到的验证码确认换邮箱。

请求头：Authorization: Bearer <access_token>

请求体：

{
  "code": "123456",
  "new_email": "[email protected]"
}

成功响应：返回更新后的完整 UserResponse（同 GET /auth/me）。

错误响应：

不一致检测：如果用户在 send-code 时填的 new_email 是 [email protected]，但 PUT /auth/email 提交 [email protected]，会按 10010（验证码错误）拒绝——验证码绑定的是 send-code 当时的新邮箱。

---

PUT /auth/password

改密码。

请求头：Authorization: Bearer <access_token>

请求体：

{
  "old_password": "oldpass123",
  "new_password": "newpass456"
}

成功响应：

{ "code": 0, "message": "密码修改成功", "data": null }

不会自动登出其他设备——其他 access_token 直到自然过期（15 分钟）才失效，refresh_token 直到自然过期（7 天）才失效。要立即下线所有设备需要走"撤销 refresh_token"流程（未来加），或 admin 手动 DELETE /admin/users/:uuid/sessions。

错误响应：

---

完整错误码表见 04-tokens-and-errors.md。