API 参考
PicFast 在 /api/v1 路径下提供 REST API。除标注为公开的端点外，其余均需认证。API 支持 JWT access token 或带权限范围的 API token（以 img_ 为前缀），通过 Authorization: Bearer 请求头传递。
系统
| 方法 | 路径 | 认证 | 说明 |
|---|
| GET | /health | 否 | 健康检查（数据库 + 存储） |
| GET | /metrics | 否 | Prometheus 指标端点 |
| GET | /api/v1/config | 否 | 公开站点配置 |
| GET | /api/v1/version | 否 | 服务器版本信息 |
| GET | /openapi.yaml | 否 | OpenAPI 规范（YAML） |
| GET | /openapi.json | 否 | OpenAPI 规范（JSON） |
| GET | /docs | 否 | Scalar API 文档界面（支持在线调试） |
初始化
| 方法 | 路径 | 认证 | 说明 |
|---|
| GET | /api/v1/setup/status | 否 | 检查是否需要进行首次初始化（无管理员账号） |
| POST | /api/v1/setup | 否 | 创建首个管理员账号（仅在没有任何用户时可用） |
认证
| 方法 | 路径 | 认证 | 说明 |
|---|
| POST | /api/v1/auth/register | 否 | 注册新账号 |
| POST | /api/v1/auth/login | 否 | 登录，返回 JWT + refresh token |
| POST | /api/v1/auth/refresh | 否 | 刷新 access token |
| POST | /api/v1/auth/logout | JWT | 注销，作废所有 refresh token |
| POST | /api/v1/auth/verify-email | 否 | 使用 token 验证邮箱 |
| POST | /api/v1/auth/resend-verification | 否 | 重新发送验证邮件 |
用户
| 方法 | 路径 | 认证 | 说明 |
|---|
| GET | /api/v1/users/me | JWT | 获取当前用户信息 |
| PUT | /api/v1/users/me | JWT | 更新个人信息（名称、密码、设置） |
API Token
| 方法 | 路径 | 认证 | 说明 |
|---|
| GET | /api/v1/api-tokens | JWT | 列出你的 API token |
| POST | /api/v1/api-tokens | JWT | 创建 API token（可设权限范围、过期时间） |
| DELETE | /api/v1/api-tokens/{id} | JWT | 删除指定 API token |
图片
| 方法 | 路径 | 认证 | 说明 |
|---|
| POST | /api/v1/images | JWT / token | 上传图片（multipart） |
| GET | /api/v1/images | JWT / token | 分页查看图片列表（可按 album_id 筛选） |
| GET | /api/v1/images/{key} | JWT / token | 按 key 获取图片详情 |
| PATCH | /api/v1/images/{key} | JWT / token | 更新图片（album_id、permission） |
| DELETE | /api/v1/images/{key} | JWT / token | 按 key 删除图片 |
上传字段
POST /api/v1/images 使用 multipart/form-data 格式：
| 字段 | 类型 | 说明 |
|---|
file | file | 图片文件（必填） |
album_id | int | 相册 ID，用于分组 |
permission | int | 0 = 私有，1 = 公开（默认） |
expires_in | string | 过期时间，如 24h、7d |
strategy_id | int | 目标存储后端 ID |
相册
| 方法 | 路径 | 认证 | 说明 |
|---|
| GET | /api/v1/albums | JWT / token | 列出你的相册 |
| POST | /api/v1/albums | JWT / token | 创建相册 |
| PUT | /api/v1/albums/{id} | JWT / token | 更新相册（名称、简介） |
| DELETE | /api/v1/albums/{id} | JWT / token | 删除相册 |
存储策略
| 方法 | 路径 | 认证 | 说明 |
|---|
| GET | /api/v1/strategies | JWT / token | 查看你所在分组可用的存储策略 |
游客上传
| 方法 | 路径 | 认证 | 说明 |
|---|
| POST | /api/v1/upload | 可选 | 游客上传（需在管理后台启用） |
ShareX
| 方法 | 路径 | 认证 | 说明 |
|---|
| GET | /api/v1/sharex/config | 否 | 下载 ShareX .sxcu 配置文件 |
| POST | /api/v1/sharex/upload | 可选 | ShareX 兼容上传端点 |
管理 API
所有管理端点需要具备 admin 角色的 JWT。前缀：/api/v1/admin。
| 方法 | 路径 | 说明 |
|---|
| GET | /admin/users | 列出用户（可按关键词、状态筛选） |
| GET / PUT / DELETE | /admin/users/{id} | 查看、更新或删除用户 |
| GET / POST | /admin/groups | 列出或创建分组 |
| GET / PUT / DELETE | /admin/groups/{id} | 查看、更新或删除分组 |
| GET / POST | /admin/strategies | 列出或创建存储策略 |
| GET / PUT / DELETE | /admin/strategies/{id} | 查看、更新或删除策略 |
| GET | /admin/images | 列出所有图片（可按关键词、邮箱、扩展名筛选） |
| DELETE | /admin/images/{id} | 按 ID 删除任意图片 |
| GET | /admin/moderation/pending | 列出待审核图片 |
| POST | /admin/moderation/{id}/approve | 批准图片 |
| POST | /admin/moderation/{id}/reject | 驳回图片（可选原因） |
| GET / PUT | /admin/settings | 查看或更新站点设置（运行时热加载） |
| GET | /admin/audit-logs | 查看审计日志（可按操作、资源类型筛选） |
| GET | /admin/observability/summary | 系统概览（运行时间、健康状态、数据库连接池、用量统计） |
AI Agent 集成（MCP）
PicFast 内置 MCP 服务器，支持 Claude、Cursor、VS Code Copilot 等 AI Agent 接入。完整的安装说明、工具参考与配置请查看 MCP 集成页面。
OpenAPI 规范
完整的机器可读 API 规范文件：
/openapi.yaml — YAML 格式/openapi.json — JSON 格式/docs — 交互式 Scalar UI，支持在线调试