管理员 API

用户管理、存储配置、系统设置、安装向导等管理员专用接口。

管理员 API 位于 /api/v1/admin/* 与部分共享端点，要求：

Bearer 认证通过
用户的 role == "admin"

注意

基于安全策略，API Token 不具备管理员权限；管理员操作必须使用浏览器登录或直接调用接口时使用 Access Token。

安装向导

安装向导无需认证，仅在首次部署时生效。

检查安装状态

Endpoint

GET · /api/v1/setup/status · 无需认证

{
  "code": 0,
  "data": {
    "initialized": false
  }
}

该端点同时被 Docker HEALTHCHECK 使用。

执行初始化

Endpoint

POST · /api/v1/setup · 无需认证（仅首次）

仅当 initialized == false 时可调用。

{
  "site_name": "My Kite",
  "site_url": "https://kite.example.com",
  "admin_username": "alice",
  "admin_email": "alice@example.com",
  "admin_password": "strong-password"
}

成功后：

把站点配置写入 settings 表
使用传入的凭据替换默认 admin/admin 账号
后续调用 /api/v1/setup 将被拒绝

用户管理

列出全部用户

Endpoint

GET · /api/v1/admin/users · 需管理员

参数	说明
`page`	页码
`size`	每页数量

{
  "code": 0,
  "data": {
    "items": [
      {
        "id": "uuid",
        "username": "alice",
        "email": "alice@example.com",
        "role": "user",
        "storage_limit": 10737418240,
        "storage_used": 521308864,
        "is_active": true,
        "created_at": "2026-01-01T00:00:00Z"
      }
    ],
    "total": 12,
    "page": 1,
    "size": 20
  }
}

创建用户

Endpoint

POST · /api/v1/admin/users · 需管理员

{
  "username": "bob",
  "nickname": "Bob",
  "email": "bob@example.com",
  "password": "initial-pass",
  "role": "user",
  "storage_limit": 10737418240
}

字段	约束
`username`	必填，3-32 字符
`email`	必填，RFC 邮箱
`password`	必填，6-64 字符
`role`	`admin` / `user`
`storage_limit`	字节，`-1` 表示不限额

更新用户

Endpoint

PUT · /api/v1/admin/users/:id · 需管理员

所有字段可选：

{
  "nickname": "Bob L.",
  "email": "bob-new@example.com",
  "password": "reset-password",
  "role": "admin",
  "is_active": true,
  "storage_limit": 21474836480
}

删除用户

Endpoint

DELETE · /api/v1/admin/users/:id · 需管理员

软删除：将用户标记为不可用，文件数据保留，可供审计与恢复。

存储配置

列出存储

Endpoint

GET · /api/v1/storage · 需管理员

返回所有存储配置（不包含敏感凭据字段）：

{
  "code": 0,
  "data": [
    {
      "id": "storage-uuid",
      "name": "本机存储",
      "driver": "local",
      "is_default": true,
      "is_active": true
    }
  ]
}

创建存储

Endpoint

POST · /api/v1/storage · 需管理员

{
  "name": "Cloudflare R2",
  "driver": "s3",
  "config": {
    "endpoint": "https://<account_id>.r2.cloudflarestorage.com",
    "region": "auto",
    "bucket": "my-kite",
    "access_key_id": "...",
    "secret_access_key": "...",
    "base_url": "https://files.example.com",
    "force_path_style": false
  }
}

driver 可选值为 local 或 s3，对应的 config 字段结构详见存储配置。

请求提交后服务器会立即尝试构造驱动；若配置非法会返回 40000。

更新存储

Endpoint

PUT · /api/v1/storage/:id · 需管理员

请求结构与创建相同，整体替换现有配置。

删除存储

Endpoint

DELETE · /api/v1/storage/:id · 需管理员

注意

删除存储不会检查是否仍有文件引用它。请在后台核实「该存储下的文件已迁移或不再需要访问」后再执行。

测试连接

Endpoint

POST · /api/v1/storage/:id/test · 需管理员

执行一次 PUT → GET → DELETE 往返，验证凭据与权限：

{ "code": 0, "data": { "ok": true } }

失败：

{ "code": 0, "data": { "ok": false, "error": "AccessDenied: ..." } }

测试文件使用固定前缀 .kite-test-connection，执行完立即清除。

系统设置

读取全部设置

Endpoint

GET · /api/v1/settings · 需管理员

{
  "code": 0,
  "data": {
    "site_name": "My Kite",
    "site_url": "https://kite.example.com",
    "allow_registration": "true",
    "allow_guest_upload": "false",
    "allow_public_gallery": "true",
    "max_file_size": "104857600",
    "allowed_types": "[\"image/\",\"video/\",\"audio/\"]",
    "thumb_width": "300",
    "thumb_quality": "80",
    "auto_webp": "false"
  }
}

所有值均以字符串形式存储；布尔、数字、数组需要由客户端解析。

更新设置

Endpoint

PUT · /api/v1/settings · 需管理员

部分更新：

{
  "allow_registration": "false",
  "max_file_size": "209715200"
}

仅传入需要修改的字段；未传入的字段保持不变。

全站文件管理

管理员还可以跨用户查看与删除文件。

全站文件列表

Endpoint

GET · /api/v1/admin/files · 需管理员

参数	说明
`user_id`	按用户筛选
`file_type`	`image` / `video` / `audio` / `file`
`keyword`	按文件名搜索
`page`、`size`、`order_by`、`order`	同 `/files`

管理员删除文件

Endpoint

DELETE · /api/v1/admin/files/:id · 需管理员

删除任意用户的文件，不做所有者校验。