KiteKite

文件管理

文件列表、详情、删除与批量操作接口。

所有文件管理端点均要求 Bearer 认证，并遵循「用户只能操作自己的文件」原则（管理员端点除外）。

文件对象结构

TYPESCRIPT
interface File {
  id:                string
  user_id:           string
  album_id:          string | null
  storage_config_id: string
  original_name:     string    // 用户上传时的原始文件名
  storage_key:       string    // 存储后端的 key
  hash_md5:          string
  size_bytes:        number
  mime_type:         string
  file_type:         "image" | "video" | "audio" | "file"
  width:             number | null    // 仅图片
  height:            number | null    // 仅图片
  duration:          number | null    // 仅视频/音频，秒
  url:               string           // 短链相对路径（/i/xxx）
  thumb_url:         string | null
  source_url:        string | null    // 存储后端直链（可选）
  is_deleted:        boolean
  created_at:        string           // ISO 8601
}

列表

Endpoint

GET · /api/v1/files · 需认证

返回当前用户的文件。管理员调用时返回全站文件。

查询参数

参数类型说明
pageint页码（默认 1）
sizeint每页（默认 20，最大 100）
album_idstring按相册筛选
file_typestringimage / video / audio / file
keywordstring按 original_name 模糊搜索
order_bystringcreated_at / size_bytes / original_name
orderstringASC / DESC

响应

JSON
{
  "code": 0,
  "data": {
    "items": [
      {
        "id": "file-uuid",
        "user_id": "user-uuid",
        "original_name": "photo.jpg",
        "size_bytes": 245760,
        "mime_type": "image/jpeg",
        "file_type": "image",
        "url": "https://kite.your-domain.com/i/a1b2c3d4",
        "thumb_url": "https://kite.your-domain.com/t/a1b2c3d4",
        "source_url": "https://cdn.example.com/2026/04/a1b2c3d4/uuid.jpg",
        "created_at": "2026-04-17T10:00:00Z"
      }
    ],
    "total": 128,
    "page": 1,
    "size": 20
  }
}

详情

Endpoint

GET · /api/v1/files/:id · 需认证

响应

JSON
{
  "code": 0,
  "data": {
    "id": "file-uuid",
    "original_name": "photo.jpg",
    "mime_type": "image/jpeg",
    "file_type": "image",
    "size_bytes": 245760,
    "hash_md5": "a1b2c3d4e5f6...",
    "width": 1920,
    "height": 1080,
    "url": "/i/a1b2c3d4",
    "thumb_url": "/t/a1b2c3d4",
    "created_at": "2026-04-17T10:00:00Z"
  }
}

错误

Code条件
40400文件不存在

删除

Endpoint

DELETE · /api/v1/files/:id · 需认证

删除一条文件记录。若该文件的 MD5 没有其他用户引用，同时会从存储后端删除实际字节。

错误

Code条件
40300非文件所有者
40400文件不存在

批量删除

Endpoint

POST · /api/v1/files/batch-delete · 需认证

请求

JSON
{
  "ids": ["file-uuid-1", "file-uuid-2", "file-uuid-3"]
}

响应

全部成功：

JSON
{
  "code": 0,
  "data": { "deleted": 3 }
}

部分失败：

JSON
{
  "code": 0,
  "data": {
    "deleted": 2,
    "errors": [
      "file-uuid-3: not the owner of this file"
    ]
  }
}

批量操作不会因单条失败而中断，每条独立处理后汇总。

公开文件广场

Endpoint

GET · /api/v1/public/files · 无需认证

仅当 allow_public_gallery = true 时可用。返回全站公开文件，不区分用户。

查询参数

参数说明
page页码（默认 1）
size每页（默认 24，最大 100）
file_typeimage / video / audio / file

响应

结构与 /files 相同。

错误

HTTPCode条件
40340300广场未开启

公开统计

Endpoint

GET · /api/v1/public/stats · 无需认证

返回全站公开统计，供前台展示。

JSON
{
  "code": 0,
  "data": {
    "total_files": 12450,
    "total_size": 83952386048,
    "images": 10023,
    "videos": 431,
    "audios": 86
  }
}

用户统计

Endpoint

GET · /api/v1/stats · 需认证

返回包含用户总数在内的详细统计，需要 Bearer Token（非管理员也可调用）。

JSON
{
  "code": 0,
  "data": {
    "users": 12,
    "total_files": 12450,
    "total_size": 83952386048,
    "images": 10023,
    "videos": 431,
    "audios": 86,
    "others": 1910
  }
}

下一步