管理员接口

以下端点仅管理员可访问。普通用户请求会返回 403 Forbidden。

服务器配置

方法	路径	说明
GET	/api/v1/server-config	获取运行时配置
PATCH	/api/v1/server-config	修改运行时配置

服务器配置控制系统运行时行为，如最大上传大小、默认配额等。该配置为单例——系统中只有一条记录。

JWT 密钥管理

该端点族已于 2026-09-14 删除（原 /api/v1/jwt-keys）。

它从未接入运行时：JWTManager.decode_token 只用环境变量 USER_JWT_SECRET_KEY 验签、 不查 JWTKey 表，因此建密钥不会让新 Token 改用它、删密钥也不会让任何已签发 Token 失效。 本节此前的「删除会导致所有已签发 Token 失效」是错误描述，且该假象足以让运维在密钥泄露时 误以为已完成处置。

密钥泄露的正确处置

修改 .env 中的 USER_JWT_SECRET_KEY 并重启所有 backend 进程。没有任何 API 能替代该流程。

短信验证码服务

方法	路径	说明
GET	/api/v1/verification-code-providers	服务商列表
POST	/api/v1/verification-code-providers	添加服务商
GET	/api/v1/verification-code-providers/{id}	服务商详情
PATCH	/api/v1/verification-code-providers/{id}	更新服务商
DELETE	/api/v1/verification-code-providers/{id}	删除服务商

微信支付配置

方法	路径	说明
GET	/api/v1/wechat-api	获取微信 API 配置
PATCH	/api/v1/wechat-api	修改微信 API 配置

用户管理（管理员视角）

管理员可通过 scope=all 访问所有用户及其资源：

• GET /api/v1/users?scope=all — 查看所有用户
• GET /api/v1/users/stats — 用户统计数据
• PATCH /api/v1/users/{id} — 修改任意用户信息
• PATCH /api/v1/users/{id}/permission — 修改用户权限（提权/降权）
• DELETE /api/v1/users/{id} — 删除用户

测试要点

测试建议

1. 权限拦截：所有管理员端点对普通用户应返回 403
2. 单例配置：server-config 只有一条记录，创建/删除行为
3. JWT 密钥轮换：创建新密钥 → 删除旧密钥 → 旧 Token 是否仍有效
4. 短信服务降级：删除所有短信服务商后，获取验证码应返回 501
5. 管理员自降权：管理员尝试移除自己的管理员权限时的行为
6. 配置修改生效：修改运行时配置后相关行为是否立即生效