API 文档（RESTful v1）
统一前缀 /api/v1；会话基于 cookie（HttpOnly/Secure/SameSite，withCredentials）。
成功响应 {"data": ...}；失败响应 {"error": "..."}，HTTP 状态码语义化
（400 参数/401 未登录/403 无权限/404 不存在/409 冲突/429 限速/500 内部）。
权限：- 公开，admin 管理员会话，user 外部用户会话。
认证 /auth
| 方法 |
路径 |
说明 |
权限 |
| GET |
/auth/captcha |
图形验证码 {captcha_id, image}（base64 PNG data URI） |
- |
| POST |
/auth/otp/send |
外部用户：用户名+图形验证码 → 发 OTP 邮件（60s 冷却）。body: {username, captcha_id, captcha_code} |
- |
| POST |
/auth/otp/login |
{username, code} → 建 cookie 会话 |
- |
| POST |
/auth/admin/login |
{username, password} → 建 cookie 会话 |
- |
| POST |
/auth/admin/forgot |
{username} → 发密码重置邮件（不存在也返回成功，防枚举） |
- |
| POST |
/auth/admin/reset |
{token, new_password} → 重置密码 |
- |
| POST |
/auth/logout |
登出（删会话 + 清 cookie） |
admin/user |
| GET |
/auth/me |
当前主体 {user_type, id, username, email} |
admin/user |
用户 /users（admin）
| 方法 |
路径 |
说明 |
| GET |
/users?page=&page_size=&status=&supervisor= |
列表（分页 {total, items}） |
| POST |
/users |
创建。body: {username(不含ext_), email, supervisor, purpose, ttl_days(0=默认)} → {id, username, status, expire_at} |
| GET |
/users/:id |
详情 |
| PATCH |
/users/:id |
更新（可空字段省略）。body: {email?, supervisor?, purpose?} |
| POST |
/users/:id/disable |
禁用（清空 authorized_keys，SSH 立即失效） |
| POST |
/users/:id/enable |
启用（按 DB 密钥恢复） |
| POST |
/users/:id/extend |
延期。body: {days(0=默认)} → {expire_at}；已过期在回收期内可恢复 |
| DELETE |
/users/:id |
删除并回收（系统账号+家目录+密钥，保留审计） |
| GET |
/users/:id/keys |
用户密钥列表 |
我的 /me（user）
| 方法 |
路径 |
说明 |
| GET |
/me/keys |
我的密钥列表 |
| POST |
/me/keys |
上传公钥 {name, public_key}（格式/重复校验 + 同步 authorized_keys） |
| PATCH |
/me/keys/:id |
重命名 {name} |
| DELETE |
/me/keys/:id |
吊销（立即失效） |
| GET |
/me/audit?page=&page_size= |
我的审计痕迹（本人为操作者或对象） |
申请审批 /approvals
| 方法 |
路径 |
说明 |
权限 |
| POST |
/approvals |
提交申请 {username, email, supervisor, purpose}（不含 ext_） |
- |
| GET |
/approvals?status= |
列表（pending/approved/rejected） |
admin |
| POST |
/approvals/:id/review |
审批 {approve: bool, reason}（拒绝必填理由） |
admin |
审计 /audit（admin）
| 方法 |
路径 |
说明 |
| GET |
/audit?page=&page_size=&actor=&action=&resource_type=&resource_id=&since=&until= |
查询（since/until 为 RFC3339） |
| GET |
/audit/export?since=&until= |
CSV 导出（UTF-8 BOM，Content-Disposition 下载） |
系统设置 /settings（admin）
| 方法 |
路径 |
说明 |
| GET |
/settings |
全部设置项 {items: [{key, value, overridden}]}（config 默认 + settings 覆盖） |
| PUT |
/settings |
更新 {key, value}（白名单 key：policy.default_ttl / policy.recycle_period / policy.audit_retention，值为时长） |
仪表盘 /admin（admin）
| 方法 |
路径 |
说明 |
| GET |
/admin/stats |
{total, active, disabled, expired, expiring_soon[], pending_approvals}（近 30 天待过期） |
其他
| 方法 |
路径 |
说明 |
权限 |
| GET |
/healthz |
健康检查 {status, version, uptime, go, timestamp} |
- |
审计动作一览
auth.admin_login、auth.otp_send、auth.otp_login、auth.logout、
user.create/update/disable/enable/extend/delete、key.create/rename/revoke、
approval.submit/review、lifecycle.expire（到期锁定）、lifecycle.recycle（回收删除）。
detail 为 JSON 字符串；result ∈ success|failed。
