用户与权限管理

先确认身份和操作对象

只有服务端认定的管理员才能访问 /admin/users 和对应的管理 API。401 表示身份无效，403 表示不是管理员——不要试图通过修改页面状态或 access token 内容来获得权限。

用户列表 API GET /api/v1/admin/users 支持 query 或 q 搜索、page、pageSize，默认每页 20 条，最多 100 条。详情接口是 GET /api/v1/admin/users/{userId}。请按明确的 userId 操作，不要只凭列表顺序或相似邮箱来决定目标。

查看文件与额度

用户详情可以帮你核对角色和空间。查看指定用户文件用 GET /api/v1/admin/users/{userId}/files，同样需要遵循 cursor 分页。查看记录不代表你获得了所有者专属的分享和发布权限。

配额调整用 PATCH /api/v1/admin/users/{userId}/quota，传字符串 limitBytes。服务端会拒绝低于当前已记账与预留之和的上限。调整前先读取当前值，调整后重新读取来确认结果。不要把空缺、请求失败或 null 当成零。具体含义见配额。

角色变更

PATCH /api/v1/admin/users/{userId}/role 接受 {"role":"user"} 或 {"role":"admin"}。这是权限变更，确认好目标和目的再执行。变更后重新读取用户详情确认，必要时让目标用户重新进入管理页面。

CORE_ADMIN_EMAILS 只在首次创建用户时决定是否初始化为 admin，不是每次登录都会重写已有账户的角色。不要以为修改了环境中的邮箱列表，已有用户的角色就自动变了。

当前不应承诺的操作

活跃的用户路由目前没有通用的删除用户、封禁/解封状态切换、密码重置或全设备退出的管理 API。数据表里有 status 字段，并不等于公开接口提供了其全部生命周期的操作。旧的归档管理文档或演示组件也不能作为当前可用操作的依据。

权限变更不等于删除浏览器里已获取的信息。管理员应该避免把用户邮箱、文件记录、Cookie 或授权值放到截图和公共报告里。报告问题时，使用操作类型、脱敏状态码、时间和处理过的关联标识就够了。

验证管理操作

建议先在可丢弃的测试实例或专门的测试账户上验证查询、翻页和额度冲突的行为。角色变更会影响后续的权限检查，避免在你唯一的管理账户上做实验。管理指标和通知分别见仪表盘和通知。