XBackBone 3.8.2 常用操作与 API 详解

目标：系统梳理 XBackBone 3.8.2 的日常操作入口——Web 控制台（媒体管理、个人 Token、系统与用户管理）、HTTP 上传 API（Token 鉴权上传、直链/下载/删除）、客户端配置下发（ShareX/Linux 脚本）与自带 CLI 维护命令，逐条给出真实请求与实测回显。已在 Ubuntu 24.04 LTS（x86_64）+ XBackBone 3.8.2 环境实测通过（2026-11-01）。

一、环境信息

• 操作系统：Ubuntu 24.04 LTS（x86_64）；
• 软件版本：XBackBone 3.8.2（打包发行版，页脚自标 XBackBone v3.8.2）；
• 服务地址：http://localhost:8145（下文所有请求直接对准该地址）；
• 演示账号：admin@example.com（管理员，安装向导创建），密码 q1w2e3r4；
• 演示 Token：token_aba1f875ae18736e2b76327659b072cb（Profile 页生成，实测值，读者环境以自己的为准）；
• 客户端工具：curl（命令行）、ShareX（Windows 桌面端）、系统自带 bash。

二、入口概览

XBackBone 的日常操作围绕五个入口展开：

💡 技术拓展：Token 上传鉴权常见三种形态——HTTP 头（Authorization: Bearer/自定义头）、查询参数（?token=）、multipart 表单字段。XBackBone 3.8.2 采用表单字段（token）随文件一起提交，优点是客户端配置只需一份 multipart 描述、不依赖头注入能力；注意这与「REST 风格 API」不同，删除等页面内操作则使用会话 Cookie 鉴权。

三、前置条件：登录与获取个人 Token

API 上传依赖「个人 Token」，该值在 Web 控制台 Profile 页生成，也可用 curl 从登录态刷新获取。以下命令可独立执行（演示账号即第一章所列）。

3.1 登录获取会话 Cookie

curl -s -c /tmp/xbb-cookies.txt -D- -o /dev/null -X POST http://localhost:8145/login \
  --data-urlencode 'username=admin@example.com' \
  --data-urlencode 'password=q1w2e3r4' | grep -iE 'HTTP|Location'

实测回显：

HTTP/1.1 302 Found
Location: http://localhost:8145/home

302 → /home 即登录成功，会话已写入 /tmp/xbb-cookies.txt。

3.2 刷新/获取 API Token

管理员 admin 是首个用户，其用户 ID 为 1：

curl -s -b /tmp/xbb-cookies.txt -X POST http://localhost:8145/user/1/refreshToken

实测回显：

token_aba1f875ae18736e2b76327659b072cb

⚠️ 注意：每次调用刷新接口都会更换 Token（旧 Token 立即失效），Profile 页的 Token 输入框与各客户端配置也随之更新；请把返回值妥善保存后再进入上传环节。

四、上传 API：POST /upload

4.1 端点与参数

4.2 上传实测

echo 'hello from XBackBone demo' > demo.txt
curl -s -F "upload=@demo.txt" -F "token=token_aba1f875ae18736e2b76327659b072cb" \
  http://localhost:8145/upload

实测回显：

{"message":"OK","version":"3.8.2","url":"http:\/\/localhost:8145\/YoTE6\/YIBaqIYu45.txt","raw_url":"http:\/\/localhost:8145\/YoTE6\/YIBaqIYu45\/raw.txt"}

链接结构解读：/YoTE6/ 为分享短路径，YIBaqIYu45.txt 为带扩展名的文件标识；url 在浏览器打开是媒体预览页，raw_url（.txt → /raw.txt）直接返回文件原始内容。

4.3 错误响应实测

⚠️ 注意：/api/v1/upload 是 XBackBone 下一代重构版宣传中的 REST 端点，3.8.2 稳定版不存在该路由；3.x 的上传端点始终是 /upload。若照抄新版文档示例会得到 404。

五、下载、直链与删除

5.1 原样内容直链（raw_url）

curl -s "http://localhost:8145/YoTE6/YIBaqIYu45/raw.txt"

实测回显：

hello from XBackBone demo

5.2 强制下载

在 url 路径后追加 /download，响应为附件下载（浏览器触发另存）：

curl -s -o /dev/null -w '%{http_code} %{content_type}\n' \
  "http://localhost:8145/YoTE6/YIBaqIYu45.txt/download"

实测回显：

200 application/octet-stream

5.3 媒体预览页

url 直接访问即为预览页（图片/视频/音频/PDF/代码/文本按类型渲染）。浏览器访问返回 HTML 页面；curl 默认请求头下同一地址会按内容协商直接返回文件内容，脚本取回内容用 raw_url 更明确：

curl -s -o /dev/null -w '%{http_code}\n' -H 'Accept: text/html' \
  "http://localhost:8145/YoTE6/YIBaqIYu45.txt"

实测回显：

200

5.4 删除（DeletionURL 形态）

上传响应的 url 后拼接 /delete/<Token>，以 GET 访问即删除该文件：

echo 'second file for delete test' > del.txt
RES=$(curl -s -F "upload=@del.txt" -F "token=token_aba1f875ae18736e2b76327659b072cb" http://localhost:8145/upload)
echo "$RES"

实测回显：

{"message":"OK","version":"3.8.2","url":"http:\/\/localhost:8145\/YoTE6\/nEHEdUyA55.txt","raw_url":"http:\/\/localhost:8145\/YoTE6\/nEHEdUyA55\/raw.txt"}

curl -s -o /dev/null -w '%{http_code}\n' \
  "http://localhost:8145/YoTE6/nEHEdUyA55.txt/delete/token_aba1f875ae18736e2b76327659b072cb"
curl -s -o /dev/null -w 'raw after delete: %{http_code}\n' \
  "http://localhost:8145/YoTE6/nEHEdUyA55/raw.txt"

实测回显：

200
raw after delete: 404

删除请求返回 200，随后原直链 404，删除生效。该形态即 ShareX 配置中 DeletionURL 的拼接规则（见第六章）。

六、客户端对接：ShareX 与 Linux 脚本

6.1 ShareX（Windows）

Profile 页提供按用户预填的 ShareX 自定义上传器配置，直接下载（会话态）：

curl -s -b /tmp/xbb-cookies.txt http://localhost:8145/user/1/config/sharex

实测回显（原文照抄，JSON）：

{
    "Version": "16.1.0",
    "Name": "admin-ShareX",
    "DestinationType": "ImageUploader, TextUploader, FileUploader",
    "RequestMethod": "POST",
    "RequestURL": "http://localhost:8145/upload",
    "Body": "MultipartFormData",
    "Arguments": {
        "file": "{filename}",
        "text": "{input}",
        "token": "token_aba1f875ae18736e2b76327659b072cb"
    },
    "FileFormName": "upload",
    "URL": "{json:url}",
    "ThumbnailURL": "{json:url}/raw",
    "DeletionURL": "{json:url}/delete/token_aba1f875ae18736e2b76327659b072cb"
}

接入步骤：ShareX → 目标（Destinations）→ 自定义上传器（Custom uploader）→ 导入（从文件导入 .sxcu 或粘贴上述 JSON）→ 设为默认。配置中已自动带上服务地址与个人 Token，之后截图/粘贴/拖拽即直传本站，分享链接自动复制到剪贴板。

说明：配置里的 Arguments.token 即第四章的鉴权字段，URL/ThumbnailURL/DeletionURL 分别对应上传响应 JSON 的 url 字段、其 /raw 形态与第五章的删除端点——与 curl 实测行为完全一致。

6.2 Linux 桌面脚本

Profile 页同样提供 Linux 上传脚本配置下载：

curl -s -b /tmp/xbb-cookies.txt http://localhost:8145/user/1/config/script | head -8

实测回显（节选，实测首尾）：

#!/bin/bash

am_i_root() {
    if [ "$EUID" -ne 0 ]; then
        echo "Please run as root or with sudo";
        exit;
    fi
}

该脚本内置桌面入口生成（写入 /usr/share/applications/xbackbone-uploader-*.desktop），装好后文件管理器「通过 XBackBone 上传」即可把选中文件直传站点并取回链接；脚本本体亦可直接 xbackbone-uploader <文件> 调用。

七、Web 控制台常用操作

7.1 媒体列表与检索

登录后首页 http://localhost:8145/home 为个人媒体列表，支持排序与视图切换（URL 参数实测）：?sort=name|size|time（排序字段）、&order=ASC（升序）、/home/switchView（列表/网格视图切换）。列表项内可逐条操作：发布/隐藏（publish/unpublish）、自定义短链（vanity）、加标签、删除。

7.2 Profile 页（Token 与客户端配置）

http://localhost:8145/profile 集中管理个人凭据：Token 查看/复制/刷新（刷新即 3.2 接口）、Hide media by default（新上传默认隐藏）、三种客户端配置下载（ShareX/Screencloud/Linux Script）。

7.3 系统与用户管理（管理员）

• http://localhost:8145/users：用户列表管理（新建/编辑/删除用户，配额调整）；
• http://localhost:8145/system：系统设置（注册开关、自动标签、图片嵌入、主题/语言、配额、reCAPTCHA、自定义 head）、孤儿上传清理、配额重算与应用内升级；参数逐项说明见 《XBackBone 3.8.2 配置参数详解》5.6 节。

八、维护 CLI

应用自带两个命令行维护工具（位于应用目录 bin/ 下，均为 PHP 脚本）：

8.1 bin/clean：缓存与会话清理

php bin/clean help

实测回显：

Usage: php /app/www/public/bin/clean <cache|sessions|all|help>

三个动作档位：cache（清模板/资源缓存目录）、sessions（清会话文件）、all（两者皆清）。上传过期文件清理、系统升级提示升级后维护等场景执行 php bin/clean all。

8.2 bin/migrate：数据库结构迁移

php bin/migrate

实测回显（升级场景，节选）：

If you are upgrading from a previous version, please run a "php bin/clean".
Done.

版本升级（替换新版本应用文件）后执行一次，输出 Done. 即库结构已就绪；紧接官方提示执行 php bin/clean。若应用目录由受限运行用户管理，迁移末尾对旧安装向导残留目录的清理可能报 Permission denied 警告（unlink/rmdir .../install/...）——不影响迁移结果（以 Done. 为准），以目录属主身份执行可消除。

九、注意事项

1. Token 即上传凭据：持有 Token 即可向站点上传内容，泄漏后立即在 Profile 页刷新使其作废；
2. 上传端点唯一：3.x 系列只有 POST /upload，路径不带版本号；带版本号的 /api/v1/upload 属于下一代版本，勿混用；
3. 体积三重上限：实际可传体积受 PHP upload_max_filesize/post_max_size 与 Nginx client_max_body_size 共同约束，调整方法见 《XBackBone 3.8.2 配置参数详解》5.4/5.5 节；
4. 删除链接即凭据：/delete/<Token> 形态的 DeletionURL 含 Token 明文，勿公开传播自己的删除链接；
5. base_url 变更联动：服务器换地址后，上传响应里的 url/raw_url 与客户端配置均按新 base_url 生成，需重新下发客户端配置。

十、常见问题（FAQ）

Q1：curl 上传返回 Token not specified.？ Token 必须与文件同在一个 multipart 请求体里：-F "upload=@文件" -F "token=<Token>"；放进 HTTP 头或 URL 参数均不被 3.8.2 识别。

Q2：上传返回 OK 但链接打不开？ 确认链接中的主机地址与实际访问地址一致（base_url 生成），并确认服务在监听；域名变更场景见注意事项 5。

Q3：Token 刷新后 ShareX 全部失效？ 正常现象，Token 是唯一上传凭据。在 ShareX 里重新导入 Profile 页新配置（或只替换 token 字段值）。

Q4：浏览器能打开预览页，脚本里 curl 同一 URL 返回的却是文件内容？ 内容协商行为：带 Accept: text/html 的请求返回预览页，其余返回内容。脚本场景固定使用 raw_url 最稳。

Q5：管理员密码忘了怎么办？ 注册开关关闭时无法自助找回。可在数据库侧将目标用户重置为新口令哈希（应用注册流程会写入标准哈希），或临时开启注册新建账号再提升为管理员后清理旧账号；操作前先备份 SQLite 数据库文件。

十一、参考链接

• 官方仓库：https://github.com/sergix44/XBackBone
• 官方文档（3.x）：https://sergix44.github.io/XBackBone/
• ShareX 官网：https://getsharex.com/
• 配套系列：《XBackBone 3.8.2 介绍与选型指南》、《XBackBone 3.8.2 Docker Compose 部署指南》、《XBackBone 3.8.2 配置参数详解》