Chibisafe v6.7.0 API 使用详解

目标：讲清 Chibisafe v6.7.0 的 REST API 体系——认证双通道（JWT 与 API Key）、11 个功能域共 86 个操作的端点全景，以及文件上传（单文件/分块）、短链、相册、管理设置等核心域的逐条实测调用与回显。全部请求与响应均为 2026-10-30 于 Ubuntu 22.04 实机（v6.7.0）curl 实测取得。

一、环境信息

• 操作系统：Ubuntu 22.04（x86_64）
• Chibisafe 版本：v6.7.0（GET /api/version 实测 {"version":"6.7.0"}）
• 部署形态：官方三服务 Compose（Web 入口端口 8152），部署步骤见 《Chibisafe v6.7.0 Docker Compose 部署指南》
• API 基地址：http://127.0.0.1:8152（公网部署替换为 https://<你的域名>）
• API 文档：后端自带 OpenAPI 3.0.3 交互文档，浏览器访问 http://127.0.0.1:8152/docs（Scalar 风格界面，spec 内嵌于页面，标题为「Chibisafe API」）
• 客户端工具：curl 7.81+（本文全部示例）；任何支持 REST 的工具均可
• 部署步骤：《Chibisafe v6.7.0 Docker Compose 部署指南》

二、前置条件

1. 已完成 v6.7.0 部署且 /api/health 返回 {"status":"yes"}；
2. 有一个可登录账号（本文用管理员 admin / q1w2e3r4，首次登录后改密的步骤见部署指南）；
3. 明确两种认证通道的分工（见下节）：浏览器/会话类操作用 JWT，脚本/程序化上传用 API Key。

三、API 总览

3.1 协议与风格

REST over HTTP/JSON（上传为 multipart/form-data）。所有响应为 JSON 对象；错误统一为 Fastify 风格四元组：

{"statusCode":400,"error":"Bad Request","message":"<人类可读原因>"}

3.2 认证方式（双通道）

3.3 限流约定

默认每秒每 IP 100 个请求（设置项 rateLimitWindow=1000 毫秒 / rateLimitMax=100，调整见 《Chibisafe v6.7.0 配置参数详解》）。实测每个响应都携带限流头：

X-Ratelimit-Limit: 100
X-Ratelimit-Remaining: 99
X-Ratelimit-Reset: 1

超限会收到 429，脚本端应按 X-Ratelimit-Reset 退避。

3.4 端点全景（11 域 86 操作）

以下为 OpenAPI 规范（GET /docs 页内嵌 spec，2026-10-30 实测提取）的完整端点清单：

Auth（4）

User（1）

Files（28）

（另有 Admin 域文件管理 11 个操作归入 Admin 段，见下。）

Albums（12）

Links（7，短链）

Snippets（6，代码片段）

Tags（4）

Server（9）

User Management（9，管理员）

Invites（3，管理员）

IP Management（3，管理员）与 Admin 文件管理（11）

四、认证与首次调用

4.1 登录获取 JWT

curl -s -X POST http://127.0.0.1:8152/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"q1w2e3r4"}'

实测回显（token 为 3 段式 JWT，节选）：

{"message":"Successfully logged in.","user":{"uuid":"6fd65081-c127-479d-8e21-f1d3c301f746","username":"admin","roles":[{"name":"owner"},{"name":"admin"}],"apiKey":null,"passwordEditedAt":"2026-10-30T05:22:24.018Z"},"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJjaGliaXNhZmUiLCJzdWIiOjEs…（JWT 其余部分略）"}

roles 含 owner/admin 时可调用全部 Admin 域端点。后续示例统一用变量承载：

JWT_TOKEN=$(curl -s -X POST http://127.0.0.1:8152/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"q1w2e3r4"}' | sed -n 's/.*"token":"\([^"]*\)".*/\1/p')

密码错误的实测回执：

{"statusCode":401,"error":"Unauthorized","message":"Invalid credentials."}

4.2 修改密码（含 400 错误示范）

password/change 必须同时带当前密码 password 与新密码 newPassword。只带其一的实测报错（zod 校验）：

curl -s -X POST http://127.0.0.1:8152/api/auth/password/change \
  -H "Authorization: Bearer $JWT_TOKEN" -H 'Content-Type: application/json' \
  -d '{"password":"q1w2e3r4"}'

实测回显：

{"statusCode":400,"error":"Bad Request","message":"[\n  {\n    \"code\": \"invalid_type\",\n    \"expected\": \"string\",\n    \"received\": \"undefined\",\n    \"path\": [\n      \"newPassword\"\n    ],\n    \"message\": \"Required\"\n  }\n]"}

补全后的成功回执：

{"message":"The password was changed successfully"}

4.3 生成 API Key

curl -s -X POST http://127.0.0.1:8152/api/auth/apikey/change \
  -H "Authorization: Bearer $JWT_TOKEN" -H 'Content-Type: application/json' -d '{}'

实测回显（本文演示实例生成的 Key，实例已销毁，读者以自己回执为准）：

{"message":"Successfully created new api key","apiKey":"3ZTZQ9Q4aH2ahJet7WcSdAyRTOYcKL9XtWZREOxFhlYFzR962HMRFJZdPYfrFwm5"}

注意：再次调用会生成新 Key 并使旧 Key 失效（每用户同时只有一个 Key）。之后所有请求可用 X-Api-Key 头替代 JWT。

五、各 API 域详解

5.1 Files 域：单文件上传

POST /api/upload，multipart 表单，文件字段名固定 file；认证可 JWT 也可 X-Api-Key：

echo "hello from chibisafe v6.7.0 test" > hello.txt
curl -s -X POST http://127.0.0.1:8152/api/upload \
  -H "X-Api-Key: $API_KEY" \
  -F "file=@hello.txt;type=text/plain"

实测回显：

{"name":"1jkv6Zyr1Moz.txt","uuid":"beb59519-598f-4343-917c-b97f547b0eba","url":"http://chibisafe_server:8000/1jkv6Zyr1Moz.txt"}

字段解读：name 为服务端生成的 12 位标识文件名（直链即 http://<入口地址>/<name>）；uuid 为内部标识，删除/打标签/入相册等操作都用它；url 是后端视角地址，公网直链以入口地址为准。

直链下载（GET，无需认证，由 Caddy 静态直出）实测回显：

HTTP/1.1 200 OK
Accept-Ranges: bytes
Content-Length: 33
Content-Type: text/plain; charset=utf-8
Server: Caddy

5.2 Files 域：分块上传（大文件）

大文件按设置项 chunkSize（默认约 81MB）切片。每个分块都是一次 POST /api/upload，需带三个请求头（chibi-uuid 文件会话标识、chibi-chunk-number 当前块号、chibi-chunks-total 总块数）和三个表单字段（name 原始文件名、type MIME、size 总大小）——分块模式下 name 等字段必须补齐，否则服务端合并阶段会因缺元数据报错（v6.7.0 实测复现 The "path" argument must be of type string）。

以 3MB 文件切 3 块为例（块 1、块 2 实测回执为 HTTP 204，块 3 完成合并返回 200）：

chunk1 http=204
chunk2 http=204
{"name":"GK9xP21EayQv.bin","uuid":"ba90bfa3-64d0-4dd4-ac6f-64efd3529e18","url":"http://chibisafe_server:8000/GK9xP21EayQv.bin"}

合并结果与原文件 md5 一致（实测）：

60c9386ab1e446458d9fce89d8bb9a97  big.bin
60c9386ab1e446458d9fce89d8bb9a97  downloaded.bin

完整命令序列见本专栏部署指南篇 4.7 节。S3 存储模式下流程不同：先 POST /api/upload（JSON 体 {size,name,contentType}）取得预签名 PUT URL 与 identifier，客户端直传对象存储，最后调 POST /api/upload/process（体 {identifier,name,type,sourceUrl}）入库。

5.3 Files 域：列表与删除

curl -s "http://127.0.0.1:8152/api/files" -H "X-Api-Key: $API_KEY"

实测回显（节选）：

{"message":"Successfully retrieved files","files":[{"name":"1jkv6Zyr1Moz.txt","createdAt":"2026-10-30T05:28:26.536Z","ip":"10.89.56.1","original":"hello.txt","uuid":"beb59519-598f-4343-917c-b97f547b0eba","hash":"de9d58174d960507650659e62a5da2e8f8b8f1e12bdb006ffcd68599314a5684","size":33,"type":"text/plain","url":"http://chibisafe_server:8000/1jkv6Zyr1Moz.txt","thumb":"","preview":"","quarantine":false,"sourceUrl":null}],"count":1}

每条记录含 hash（SHA-256）、size、type、ip（上传者 IP）、quarantine（是否被隔离）等字段。删除文件用 DELETE /api/file/{uuid}（成功回执 {"message":"Successfully deleted file"}，实测口径同域内其他回执格式）。

5.4 Albums 域：创建相册

curl -s -X POST http://127.0.0.1:8152/api/album/create \
  -H "X-Api-Key: $API_KEY" -H 'Content-Type: application/json' \
  -d '{"name":"demo-album"}'

实测回显：

{"message":"Successfully created album","album":{"uuid":"bee1d579-a467-48ea-be1d-405842e6de2f","name":"demo-album","createdAt":"2026-10-30T05:28:35.741Z"}}

文件入相册用 POST /api/file/{uuid}/album/{albumUuid}，相册分享链接用 POST /api/album/{uuid}/link。

5.5 Links 域：短链

默认关闭时实测回执（开关见配置篇 5.5 节）：

{"statusCode":501,"error":"Not Implemented","message":"URL shortener is disabled"}

开启后创建（vanity 可选，自定义短链码）：

curl -s -X POST http://127.0.0.1:8152/api/link/create \
  -H "Authorization: Bearer $JWT_TOKEN" -H 'Content-Type: application/json' \
  -d '{"url":"https://github.com/chibisafe/chibisafe","vanity":"chibisafe-repo"}'

实测回显：

{"message":"Successfully created link","link":{"uuid":"7801153a-f405-4be4-9529-daaa0243fcb5","identifier":"chibisafe_repo","link":"http://chibisafe_server:8000/l/chibisafe_repo"}}

注意 vanity 中的连字符被规范化为下划线（chibisafe-repo → chibisafe_repo），跳转以返回的 identifier 为准。访问 GET /l/chibisafe_repo 实测 307 Temporary Redirect 到 /api/link/chibisafe_repo 并最终跳目标 URL。

5.6 Server 域：版本、健康与公开设置

curl -s http://127.0.0.1:8152/api/version
curl -s http://127.0.0.1:8152/api/health

实测回显：

{"version":"6.7.0"}
{"status":"yes"}

这两个端点匿名可访问，适合做监控探针。GET /api/settings 返回匿名可读的设置子集（站点名、上传限制、开放模式等，前端渲染首页用）。

5.7 Admin 域：设置读写与统计

读全量设置、写设置（settings 数组每项必须带 key/value/type 三元组，缺 type 报 400，实测回显见 《Chibisafe v6.7.0 配置参数详解》 3.2 节）。服务器统计实测：

curl -s http://127.0.0.1:8152/api/admin/service/statistics -H "Authorization: Bearer $JWT_TOKEN"

实测回显（节选）：

{"statistics":[{"system":{"Platform":"linux x64","Distro":"Alpine Linux v3.24","Kernel":"7.0.0-38-generic","CPU":"6 × Intel Core™ i7-14700KF @ 0.00GHz","CPU Load":"36.2%","CPUs Load":"37.0%, 36.1%, 36.0%, 36.2%, 35.8%, 35.8%","CPU Temperature":{"value":null,"type":"unavailable"},"Memory":{"value":{"used":6518321152,"total":16715763712},"type":"byteUsage"},"Memory Usage":{"value":147779584,"type…

（输出节选，实测首段——含 CPU/内存/磁盘/带宽等系统面板数据，另有用户/文件计数段。）

管理员文件治理常用组合：GET /api/admin/files 全量巡检 → POST /api/admin/file/{uuid}/quarantine 隔离可疑文件 → POST /api/admin/files/purge/public 一键清空公开区。

六、分页/过滤/排序通用约定

• GET /api/files、GET /api/admin/files、GET /api/admin/users、GET /api/albums 等列表端点支持 page/limit（或 offset）查询参数做分页，响应体固定为 {"message":…,"files":…,"count":…} 形态，count 为总数——分页循环以 count 为准；
• 排序维度由设置项 defaultSortOrder（默认 createdAt:desc）给出全局默认；
• 过滤类操作（按相册/标签/IP）走专用端点而非查询串：文件按相册用 POST /api/files/albums，按 IP 用 POST /api/admin/ip/files；
• 批量操作（删除/隔离/入相册）一律 POST + JSON 数组体，无批量 DELETE 端点。

七、常见问题

Q1：/api/user/me 返回 500 Something went wrong？ v6.7.0 实测确认该端点对 JWT 与 X-Api-Key 两种认证均返回 500（实测回显 {"statusCode":500,"error":"Internal Server Error","message":"Something went wrong"}，服务端日志 GET /api/user/me 500 4ms）。用户信息可从 POST /api/auth/login 回执的 user 字段获取，功能不受影响；升级到更新版本观察是否修复。

Q2：上传返回 200 但 body 为空？ 向 /api/upload 发了 JSON 而不是 multipart 表单。上传端点用 busboy 解析 multipart（OpenAPI 里标注的 JSON 体仅用于 S3 预签名流程），curl 用 -F 而非 -d。

Q3：分块上传最后一块报 The "path" argument must be of type string？ 分块模式漏了 name/type/size 表单字段（服务端靠 name 推导合并文件扩展名）。补齐三个字段即可，见 5.2 节。

Q4：X-Api-Key 认证 401？ 检查三点：Key 是否最近被重新生成过（apikey/change 每次覆盖旧 Key）；头名必须是 X-Api-Key（大小写不敏感但拼写要对）；Key 值前后无空格换行。

Q5：短链创建 501？ useUrlShortener 默认关闭（产品语义），管理后台开启后再调，见 5.5 节。

Q6：批量上传被限流 429？ 默认每秒 100 请求。脚本端读取 X-Ratelimit-Remaining，低于阈值时按 X-Ratelimit-Reset 睡眠；或在管理后台调大 rateLimitMax。

八、参考链接

• 后端自带 API 文档（部署后访问）：http://<你的实例地址>/docs
• 官方仓库（API 源码位于 packages/backend/src/routes/）：https://github.com/chibisafe/chibisafe
• 官方文档站：https://chibisafe.app
• 本专栏配套篇目：《Chibisafe 介绍与选型指南》、《Chibisafe v6.7.0 配置参数详解》、《Chibisafe v6.7.0 Docker Compose 部署指南》

（文中全部请求与响应均为 2026-10-30 于 Ubuntu 22.04 实机 v6.7.0 的 curl 实测回显；端点全景提取自实例自带的 OpenAPI 3.0.3 规范。）