图图床管理后台
↗ 打开上传页
© 没有灵魂的卖家

首次安装

创建管理员账号和普通用户上传密码。

管理员登录

这里仅供站点管理员使用。

仪表盘

查看图床运行概况与上传统计

Cloudflare Workers 调用量

使用官方 GraphQL Analytics 查询，5 分钟缓存；不会为每个访问写 D1。

加载中…

最近 30 天上传统计



资源管理（图片 + 文件）


目录 / 相册




存储节点
前台“上传到”会自动显示所有“已启用 + 普通用户可选择”的存储节点；达到两个及以上时自动允许切换。可直接使用节点卡片右上角开关一键启用/停用。
可同时启用多个 R2 / Hugging Face / S3，并决定哪些节点开放给普通用户选择。




新增存储节点
每个节点都可以拥有独立目录、访问方式和密钥。












Hugging Face Storage Bucket
使用 Storage Bucket 的 S3 凭证：Access Key 应以 HFAK 开头，Endpoint 自动使用 https://s3.hf.co/<namespace>，Region 固定 us-east-1。


Cloudflare R2 S3 API


通用 S3






API 密钥
管理型 API 使用 Authorization: Bearer YOUR_API_KEY。密钥只在创建时显示一次，请妥善保存。





API 接口文档
Base URL：。每个接口均附字段说明、请求示例和返回示例，可一键复制。





通用认证


Authorization: Bearer YOUR_API_KEY


其中 YOUR_API_KEY 是在上方“API 密钥”区域生成的完整密钥，例如 img_xxxxxxxxx。





1. 上传图片　POST /api/v1/images



用途：上传一张图片到指定存储节点，并可选择关联相册及是否展示到公开相册。


Content-Type：multipart/form-data


字段必填类型说明


file是File要上传的图片文件本体，例如 JPG、PNG、WebP、GIF。该接口只接受图片。


storage_node_id否整数存储节点的数据库 ID，决定文件上传到哪一个 R2 / Hugging Face / S3 节点。例如填 2 表示 ID=2 的存储节点。不填时按后台“默认存储节点 / 负载策略”自动选择。可通过 GET /api/v1/storage-nodes 查询。


album_id否整数相册的数据库 ID，只用于给图片分类。例如后台创建“产品图”相册后得到 ID=3，则上传时传 album_id=3。不填表示“不归属任何相册”。它不是相册名称，也不是目录路径。可通过 GET /api/v1/albums 查询。


is_public否布尔true 表示允许该图片出现在 /gallery/ 公开相册；false 表示不展示。不填时使用后台默认设置。





cURL 示例


curl -X POST "$BASE/api/v1/images" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@photo.jpg" \
  -F "storage_node_id=2" \
  -F "album_id=3" \
  -F "is_public=true"



成功返回示例


{
  "success": true,
  "id": "f0b8829c-df1a-40bc-8b33-1e81950f6419",
  "url": "https://example.com/p/Ab3Kx9Q",
  "direct_url": "https://example.com/object/2/uploads/2026/09/14/xxx.jpg",
  "mime": "image/jpeg",
  "isImage": true,
  "storage": "hf",
  "storageNodeId": 2,
  "storageName": "HF 图片库",
  "key": "uploads/2026/09/14/xxx.jpg",
  "isPublic": true,
  "shortCode": "Ab3Kx9Q"
}


返回字段说明


id资源 UUID。删除、修改、移动资源时使用这个值，不是数据库自增 ID。


url建议对外使用的链接。开启短链接时通常是本站 /p/短码。


direct_url资源当前的直接访问地址或本站代理地址。


storageNodeId实际使用的存储节点 ID。


key对象在 R2 / HF / S3 内的真实对象路径。


isPublic是否出现在公开相册。







2. 上传普通文件　POST /api/v1/files



用途：上传 ZIP、PDF、TXT、MP4、DOCX 等普通文件。普通文件不会进入公开相册。


字段必填类型说明


file是File要上传的文件本体。


storage_node_id否整数目标存储节点 ID。不填时使用后台默认节点或负载策略。




curl -X POST "$BASE/api/v1/files" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@archive.zip" \
  -F "storage_node_id=2"


返回：结构与上传图片基本一致，但 isImage=false，并且不会设置公开相册状态。





3. 查询相册 ID　GET /api/v1/albums



用途：查询 album_id 应该填写什么。


curl "$BASE/api/v1/albums" \
  -H "Authorization: Bearer YOUR_API_KEY"


[
  {
    "id": 3,
    "name": "产品图",
    "slug": "产品图",
    "image_count": 25
  }
]


id 就是上传图片接口里的 album_id。例如这里应填写 3。





4. 查询存储节点 ID　GET /api/v1/storage-nodes



用途：查询 storage_node_id。返回内容会隐藏 Secret Key。


curl "$BASE/api/v1/storage-nodes" \
  -H "Authorization: Bearer YOUR_API_KEY"


[
  {
    "id": 2,
    "name": "HF 图片库",
    "type": "hf",
    "enabled": true,
    "public_selectable": true,
    "delivery_mode": "proxy",
    "path_prefix": "uploads/{yyyy}/{mm}/{dd}"
  }
]


这里的 id=2 就是上传接口中的 storage_node_id=2。





5. 获取资源列表　GET /api/v1/resources



用途：分页读取已经上传的资源。


Query 参数必填说明


limit否每次返回多少条，默认 100，最大 200。


cursor否分页游标。第一次不要传；下一页直接使用上一次返回的 nextCursor。它不是页码。




GET /api/v1/resources?limit=100
GET /api/v1/resources?limit=100&cursor=123
GET /api/v1/images?limit=100
GET /api/v1/files?limit=100


{
  "items": [
    {
      "id": 123,
      "uid": "资源 UUID",
      "original_name": "photo.jpg",
      "mime": "image/jpeg",
      "size": 123456,
      "is_image": true,
      "copy_url": "https://example.com/p/xxxx",
      "storage_name": "HF 图片库"
    }
  ],
  "nextCursor": 98,
  "hasMore": true
}


hasMore=true 时，把 nextCursor 传给下一次请求；为 false 时已经到底。





6. 修改资源信息　PATCH /api/v1/resources/:id



:id 是上传接口返回的资源 UUID，例如 f0b8829c-df1a-...。


JSON 字段必填说明


original_name否修改数据库中显示的资源名称。仅修改显示名称，不自动改变对象存储里的文件名；要改真实对象名请使用“移动 / 重命名”接口。


album_id否把图片归入某个相册。传相册数字 ID；传 null 或 0 表示移出相册。


is_public否图片是否展示到公开相册。普通文件固定为 false。




curl -X PATCH "$BASE/api/v1/resources/资源UUID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "original_name": "新名称.jpg",
    "album_id": 3,
    "is_public": false
  }'





7. 移动 / 重命名真实对象　POST /api/v1/resources/:id/move



JSON 字段必填说明


path否目标目录，例如 products/2026/09。这是对象存储中的目录前缀，不是服务器本地磁盘目录。


filename否目标文件名，例如 demo.webp。填写后会真正更改 R2 / HF / S3 中的对象 Key。


original_name否同时更新后台展示名称；不填则保留旧展示名称。




curl -X POST "$BASE/api/v1/resources/资源UUID/move" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "products/2026/09",
    "filename": "demo.webp"
  }'





8. 删除资源　DELETE /api/v1/resources/:id



删除数据库记录，并删除对应 R2 / Hugging Face / S3 中的真实对象。操作不可恢复。


curl -X DELETE "$BASE/api/v1/resources/资源UUID" \
  -H "Authorization: Bearer YOUR_API_KEY"


{ "ok": true }





9. 查看存储状态　GET /api/v1/storage/status



Query 参数必填说明


probe否默认不连接远端，只读取数据库统计；传 probe=1 才实际请求各 R2 / HF / S3 节点测试连通性。频繁调用 probe 会增加外部请求。




GET /api/v1/storage/status
GET /api/v1/storage/status?probe=1





10. 公开相册接口　GET /api/gallery



无需 API Key。只返回设置为公开展示的图片，不返回普通文件。


Query 参数说明


limit每次读取数量，默认 48，最大 100。


cursor下一页游标。第一次不传，后续使用上一次返回的 nextCursor。




GET /api/gallery?limit=48
GET /api/gallery?limit=48&cursor=123





通用错误返回

{ "error": "错误说明" }


常见 HTTP 状态：400 参数错误、401 API Key/登录无效、403 功能未开放或权限不足、404 资源不存在、409 状态冲突、413 文件过大、415 文件类型不符合接口要求、500 服务端错误。








普通用户上传设置










网站与图库设置


基础设置



Cloudflare Workers 调用量配置
为了不把 Cloudflare API Token 明文存入 D1，请在 Worker 的 Settings → Variables and Secrets 配置以下三个变量：
CF_ACCOUNT_IDCloudflare Account ID
CF_WORKER_SCRIPT_NAMEWorker 脚本名称，例如 soul-less-imagebed
CF_ANALYTICS_TOKENSecret，建议只授予 Account Analytics Read 权限