用户与档案
| 方法 | 路径 | 鉴权 | 说明 |
|---|---|---|---|
| GET | /users/me |
需认证 | 我的完整档案 |
| PUT | /users/me |
account.profile.edit |
改用户名/昵称/简介 |
| GET | /users/me/permissions |
需认证 | 我的权限键与用户组 |
| POST | /users/me/avatar |
account.avatar.edit |
上传头像 |
| POST | /users/me/banner |
account.banner.edit |
上传横幅 |
| PUT | /users/me/locale |
需认证 | 区域与语言 |
| PUT | /users/me/privacy |
需认证 | 隐私开关 |
| PUT | /users/me/name-style |
account.profile.edit |
名称样式(会员能力) |
| PUT | /users/me/e2ee-key |
需认证 | 发布 X25519 公钥 |
| POST | /users/me/claim-daily-bonus |
需认证 | 领取每日奖励 |
| POST | /users/me/heartbeat |
需认证 | 在线心跳 |
| POST | /users/me/deletion-request |
需认证 | 申请注销 |
| DELETE | /users/me/deletion-request |
需认证 | 撤回注销申请 |
| GET | /users/search?q=&limit= |
需认证 | 搜索用户 |
| GET | /users/:user_id |
公开 | 他人档案 |
| PUT | /users/:user_id/exp |
user.adjust_exp |
调整他人经验 |
| PUT | /users/:user_id/membership |
user.membership.grant |
授予会员 |
| POST/DELETE | /users/:user_id/follow |
account.follow |
关注 / 取关 |
| GET | /users/:user_id/followers |
公开 | 粉丝列表 |
| GET | /users/:user_id/following |
公开 | 关注列表 |
| GET | /users/:user_id/friends |
公开 | 好友(互关)列表 |
| GET | /users/storage-buckets |
需认证 | 存储桶清单与锁定状态 |
| PUT | /users/me/storage-bucket |
需认证 | 切换存储桶 |
GET /users/me{ "id": 1, "username": "alice", "nickname": "Alice", "avatar_url": "https://...", "storage_quota": 104857600, "storage_used": 2048000}返回还包含会员字段、名称样式字段与 is_bot(bot 账号)。storage_quota 是有效配额(基础配额 + 生效中的会员加成)。
PUT /users/me{ "username": "alice", "nickname": "Alice", "bio": "..." }三个字段均可选,但至少提供一个。用户名沿用注册时的唯一性规则。调用后清除 needs_registration。
这个接口只接受
username/nickname/bio——改不到 bot 标记与归属关系。
POST /users/me/avatar Content-Type: multipart/form-data file=<图片>POST /users/me/banner Content-Type: multipart/form-data file=<图片>两者都计入存储配额。
PUT /users/me/locale{ "region": "CN", "lang": "zh-CN" }用于日期边界与推送语言。
POST /users/me/heartbeat → 200 {"online": true}更新 last_seen。
GET /users/me/permissions{ "permissions": ["posts.view", "posts.create", "chat.send"], "groups": ["admin", "beta-users"] }该接口不需要任何权限即可调用(否则无法完成注册收尾),是启动时确认“我到底能做什么”的可靠方式。完整键表见服务端概览。
用户搜索与查看
Section titled “用户搜索与查看”GET /users/search?q=alice&limit=20 # 按用户名或昵称子串匹配GET /users/:user_id # 公开档案{ "users": [{ "id": 2, "username": "alice", "nickname": "Alice", "avatar_url": null }] }GET /users/:user_id 是 authPublic:带 token 时结果会附带 is_following / is_friend 等个性化字段。
POST /users/:user_id/follow # 关注DELETE /users/:user_id/follow # 取关互相关注的两人成为好友。列表:
GET /users/:user_id/followersGET /users/:user_id/followingGET /users/:user_id/friends档案里带 follower_count / following_count 与 is_following / is_friend。
PUT /users/me/privacy{ "hide_follow_lists": true }开启后,三个列表对除本人以外的所有人返回 403,且他/她的档案中不再返回粉丝/关注数。
名称样式(会员能力)
Section titled “名称样式(会员能力)”PUT /users/me/name-style可设置 name_color、name_color_to(渐变第二色)、name_dynamic(动态渐变)。按会员等级限制:
| 等级 | 允许 |
|---|---|
| Lv.1 薄雾 | 仅预设调色板 |
| Lv.2 篝火 | 任意合法十六进制色 |
| Lv.3 明月 | 追加渐变第二色 |
| Lv.4 孤星 | 追加动态渐变 |
Lv.1 的“仅预设”由服务端强制校验,不依赖客户端。
经验与会员(管理操作)
Section titled “经验与会员(管理操作)”PUT /users/:user_id/exp { "..." } # 权限 user.adjust_expPUT /users/:user_id/membership { "level": 2, "days": 30 } # 权限 user.membership.grant会员授予传 level: 0 表示清除。经验加成在 GrantExp 内按生效会员倍率放大。详见任务与会员。
服务端支持物理多桶对象存储:每个逻辑桶映射到独立的 S3 桶,并可要求最低会员等级。
GET /users/storage-buckets返回桶的 name、label、default_quota、min_member_level、is_default、locked(当前用户是否可用),以及用户当前的 current 桶。
PUT /users/me/storage-bucket{ "bucket": "star" }- 未知桶 →
400;会员等级不足 →403; - 切换后配额重置为目标桶的
default_quota; - 已有附件不会迁移,其记录保留上传时的桶,删除时仍解析到正确的物理存储;
- 会员加成配额只在默认桶生效。
每日奖励与注销
Section titled “每日奖励与注销”POST /users/me/claim-daily-bonus按服务器日(GAME_TIMEZONE 定义的边界)发放一次经验与货币(默认 100 exp / 20 币)。返回含连续签到天数。
POST /users/me/deletion-request # 申请注销DELETE /users/me/deletion-request # 撤回申请后账号立即从各处隐藏、登录被拒,数据行在 30 天后清除;期间可撤回。
bot 与普通账号不同:删除 bot(或删除其所有者)会级联删除它的帖子、评论、消息、附件与会话/营地成员关系,不可恢复。
GET /storage/usage返回已用字节数,配合 storage_quota 展示配额进度。详见附件与存储。