Lumina 图床 · RESTful API 文档#

[object Object]

概述#

统一响应结构#

成功：

{
  "success": true,
  "data": { },
  "pagination": { }
}

失败：

{
  "success": false,
  "error": {
    "code": "FILE_TOO_LARGE",
    "message": "文件超过游客单文件上限 5.00 MB",
    "status": 413
  }
}

[object Object]

权限模型#

鉴权 Authentication#

POST /api/auth/login#

管理员登录，返回访问令牌。

请求体

curl -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"password":"admin123"}'

响应

{
  "success": true,
  "data": {
    "token": "eyJzdWIiOiJhZG1pbi...xyz",
    "token_type": "Bearer",
    "expires_at": 1789977600,
    "expires_in": 604800,
    "user": { "name": "admin", "role": "admin" }
  }
}

[object Object]

POST /api/auth/logout 🔒#

吊销当前 Token。🔒 表示需要管理员 Token。

GET /api/auth/me 🔒#

查询当前登录态，返回 { user, expires_at, default_password }。 default_password=true 表示仍在使用初始密码。

POST /api/auth/password 🔒#

修改管理员密码，所有已签发的 Token 会立即失效，并在响应中返回新的 Token。

{ "old_password": "admin123", "new_password": "s3cure-pass" }

上传 Upload#

POST /api/upload#

上传一张或多张图片。支持任意字段名，推荐 file（单张）或 files（多张）。

# 单张（游客）
curl -X POST http://localhost:3000/api/upload -F "file=@cat.png"

# 多张（管理员，带 Token）
curl -X POST http://localhost:3000/api/upload \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@a.jpg" -F "file=@b.webp" -F "file=@c.svg"

响应（单张时 data 为对象，多张时为数组）

{
  "success": true,
  "data": {
    "id": "4fWYCKda9s",
    "filename": "cat.png",
    "ext": "png",
    "mime": "image/png",
    "size": 235312,
    "size_human": "229.80 KB",
    "width": 1920,
    "height": 1080,
    "pages": 1,
    "animated": false,
    "vector": false,
    "storage_driver": "local",
    "uploader": "guest",
    "created_at": 1789489113196,
    "created_at_text": "2026-09-15T16:18:33.196Z",

    "url": "http://localhost:3000/i/2026/09/4fWYCKda9s.png",
    "page_url": "http://localhost:3000/img/4fWYCKda9s",
    "thumb_url": "http://localhost:3000/t/4fWYCKda9s",

    "formats": {
      "url": "http://localhost:3000/i/2026/09/4fWYCKda9s.png",
      "thumbnail": "http://localhost:3000/t/4fWYCKda9s",
      "html": "<img src=\"...\" alt=\"cat.png\" />",
      "html_thumb": "<a href=\"...\" target=\"_blank\"><img src=\"...\" alt=\"cat.png\" /></a>",
      "markdown": "![cat.png](http://localhost:3000/i/2026/09/4fWYCKda9s.png)",
      "markdown_thumb": "[![cat.png](...thumb)](...url)",
      "bbcode": "[img]http://localhost:3000/i/2026/09/4fWYCKda9s.png[/img]",
      "bbcode_thumb": "[url=...][img]...[/img][/url]"
    },

    "duplicated": false,
    "compression": {
      "original_size": 943216,
      "final_size": 235312,
      "saved_bytes": 707904,
      "saved_percent": 75.1,
      "note": "已优化"
    }
  },
  "uploaded": 1,
  "failed": 0,
  "errors": []
}

关键字段说明

部分失败：多文件上传时，只要有一张成功即返回 200， 失败明细放在 errors 数组（[{ filename, code, message }]）；全部失败才返回错误码。

GET /api/upload/limits#

查询当前身份的实际上传限额，前端可据此做前置校验与提示。

{
  "success": true,
  "data": {
    "identity": "guest",
    "guest_upload_enabled": true,
    "max_file_size": 5242880,
    "max_file_size_human": "5.00 MB",
    "max_files": 20,
    "allowed_formats": ["jpg", "jpeg", "png", "gif", "webp", "svg", "avif"]
  }
}

图片管理 Images#

GET /api/images 🔒#

分页查询图片列表。

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:3000/api/images?page=1&limit=24&order=largest&uploader=guest"

响应 除 data 外还包含分页信息：

{
  "success": true,
  "data": [ { "id": "...", "url": "..." } ],
  "pagination": {
    "page": 1, "limit": 24, "total": 137, "pages": 6,
    "has_next": true, "has_prev": false
  }
}

GET /api/images/:id#

获取单张图片的元数据（公开接口，无需 Token）。 适合「已知 ID 要拿直链」的场景。

DELETE /api/images/:id 🔒#

删除图片：同时移除存储中的原图、本地缩略图，并对数据库记录做软删除。

curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  http://localhost:3000/api/images/4fWYCKda9s

{
  "success": true,
  "data": {
    "id": "4fWYCKda9s",
    "storage_key": "2026/09/4fWYCKda9s.png",
    "shared": false,
    "hard": false,
    "message": "删除成功"
  }
}

[object Object]

POST /api/images/batch-delete 🔒#

批量删除，单次最多 200 张。

{ "ids": ["4fWYCKda9s", "vbsNkGd2qU"] }

{
  "success": true,
  "data": {
    "deleted": ["4fWYCKda9s"],
    "failed": [ { "id": "vbsNkGd2qU", "message": "图片不存在：vbsNkGd2qU" } ],
    "requested": 2
  }
}

GET /api/images/stats 🔒#

站点统计。

{
  "success": true,
  "data": {
    "total": 137,
    "totalBytes": 48234112,
    "total_human": "46.00 MB",
    "todayCount": 12,
    "todayBytes": 3145728,
    "today_bytes_human": "3.00 MB",
    "animatedCount": 4,
    "vectorCount": 7,
    "byExt": [ { "ext": "png", "count": 90, "bytes": 30123456 } ],
    "byDriver": [ { "driver": "local", "count": 137 } ]
  }
}

配置 Configuration#

GET /api/config#

公开配置（无需 Token），前端渲染用。不包含任何敏感字段。

{
  "success": true,
  "data": {
    "site_name": "Lumina 图床",
    "guest_upload_enabled": true,
    "guest_max_file_size": 5242880,
    "max_file_size": 20971520,
    "max_files": 20,
    "allowed_formats": ["jpg", "jpeg", "png", "gif", "webp", "svg", "avif"],
    "thumbnail_width": 480,
    "storage_driver": "local",
    "webdav_configured": false
  }
}

GET /api/settings 🔒#

完整配置（管理员）。WebDAV 密码不会回传明文，仅返回 webdav_password_set 布尔值。

PATCH /api/settings 🔒#

热更新配置，立即生效、无需重启。

# 把游客上传上限调整为 8MB，并开启游客上传
curl -X PATCH http://localhost:3000/api/settings \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"guest_upload_enabled":true,"guest_max_file_size":8388608}'

{
  "success": true,
  "data": {
    "updated": ["guest_upload_enabled", "guest_max_file_size"],
    "config": { "guest_max_file_size": 8388608, "guest_max_file_size_human": "8.00 MB" },
    "warnings": []
  }
}

DELETE /api/settings/:key 🔒#

把某项配置恢复为环境变量 / 代码默认值。

GET /api/storage/health 🔒#

存储驱动自检。WebDAV 会实际写入并删除一个探针文件，验证读写权限。

{
  "success": true,
  "data": {
    "mode": "hybrid",
    "ok": true,
    "drivers": [
      { "driver": "local", "ok": true, "message": "本地磁盘可写", "detail": "/app/storage" },
      { "driver": "webdav", "ok": true, "message": "连接成功，读写权限正常", "detail": "https://dav.example.com/remote.php/dav/files/me" }
    ]
  }
}

系统 System#

GET /api/health#

健康检查，无需鉴权。适合容器探针 / 负载均衡健康检查。

{
  "success": true,
  "data": {
    "status": "ok",
    "service": "lumina-image-hosting",
    "version": "1.0.0",
    "node": "v22.22.2",
    "uptime_seconds": 3612,
    "storage_driver": "local",
    "images": 137,
    "time": "2026-09-16T00:11:45.000Z"
  }
}

资源与页面路由#

错误码#

限流#

默认基于 IP 的滑动窗口限流，可通过环境变量调整或关闭（置 0 即关闭）：

响应头携带 X-RateLimit-Limit、X-RateLimit-Remaining，被限流时附加 Retry-After。

格式支持#

[object Object]