XBackBone 3.8.2 Docker Compose 部署指南

目标：在装有 Docker 的服务器上以 Docker Compose 部署 XBackBone 3.8.2 文件与媒体分享服务，覆盖镜像选型、编排文件编写、启动、安装向导、上传下载验证、数据持久化、上传上限调整与日常运维。已在 Ubuntu 24.04 LTS（x86_64）+ Docker 29.x + Docker Compose v2 环境实测通过（2026-11-01，应用版本 3.8.2）。

一、环境信息

操作系统：Ubuntu 24.04 LTS（x86_64）；
Docker：已安装并运行（docker --version 自查）；Docker Compose 使用 v2 插件语法（docker compose）；
应用版本：XBackBone 3.8.2（LinuxServer.io 打包版，构建号 3.8.2-ls247，构建日期 2026-10-25）；
部署形态：单节点，应用 + Nginx + PHP-FPM 集成于一个服务单元；
端口规划：宿主机 8145 → 服务 80（HTTP；443 同步在容器内监听但未映射，TLS 交由反向代理）；
数据目录：/opt/xbackbone/（compose 文件与持久化目录同置）；
数据库：SQLite（零依赖起步，可换 MySQL，见配套《XBackBone 3.8.2 配置参数详解》）。

二、镜像选型说明

XBackBone 官方未在公共仓库发布自带运行时的应用镜像，但 LinuxServer.io（社区知名打包组织）提供了官方收录的打包版本，本文采用该路径：

项	取值	说明
镜像	`lscr.io/linuxserver/xbackbone:latest`	lsio 官方仓库构建，多架构（x86-64 / arm64）
应用版本	3.8.2（镜像标签 `build_version: Linuxserver.io version:- 3.8.2-ls247`）	与上游最新稳定版一致
运行时	Alpine 3.24 + Nginx + PHP-FPM（PHP 8.5）	应用、Web 服务、PHP 集成打包
内部端口	80（HTTP）、443（HTTPS，自签证书）	映射 80 即可，TLS 建议外置反代
持久化点	`/config` 单目录	站点配置、数据库、上传文件、证书全在其中

💡 说明：latest 标签当前对应 3.8.2-ls247，生产环境可锁定到具体版本标签以固定行为；lsio 镜像的应用升级方式是「拉新镜像 + 重建服务单元」，配置与数据均在 /config 持久化，重建不丢数据。

三、前置条件

服务器已安装 Docker 与 Docker Compose v2，且当前用户在 docker 组或具备等效权限；
服务器可访问公网镜像仓库（lscr.io）；拉取缓慢时可为 Docker 守护进程配置代理后再拉取；
宿主机 8145 端口未被占用（ss -ltn | grep 8145 应无输出，被占用则改用其他空闲端口并同步修改编排文件）；
部署目录规划：/opt/xbackbone/（不存在则创建）。

四、部署步骤

4.1 创建目录与编排文件

mkdir -p /opt/xbackbone/config && cd /opt/xbackbone

创建 docker-compose.yml：

name: xbackbone-3.8.2-stack
services:
  xbackbone:
    image: lscr.io/linuxserver/xbackbone:latest
    container_name: xbackbone-3.8.2-web
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Asia/Shanghai
    volumes:
      - ./config:/config
    ports:
      - "8145:80"
    networks:
      - ts-net
    restart: unless-stopped
networks:
  ts-net:
    name: xbackbone-3.8.2-net
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.61.0/24

说明：

PUID/PGID=1000：以宿主机普通用户身份运行，避免挂载目录出现权限问题；若 /opt/xbackbone/config 目录属主不是 uid/gid 1000，先 chown -R 1000:1000 /opt/xbackbone/config；

TZ：容器内时区，影响日志与上传时间戳；

./config:/config：唯一持久化挂载点；

网络段显式指定为 10.89.61.0/24：避免与其他 Compose 项目默认网段冲突，与其他项目并行部署时各自选不同网段；

restart: unless-stopped：随守护进程自启（手工停止除外）。

4.2 启动服务

cd /opt/xbackbone && docker compose up -d

实测回显：

[+] Running 3/3
 ✔ Network xbackbone-3.8.2-net  Created
 ✔ Container xbackbone-3.8.2-web  Created
 ✔ Container xbackbone-3.8.2-web  Started

4.3 确认启动状态

docker compose ps

实测回显：

NAME                  IMAGE                                  COMMAND   SERVICE     CREATED          STATUS          PORTS
xbackbone-3.8.2-web   lscr.io/linuxserver/xbackbone:latest   "/init"   xbackbone   12 seconds ago   Up 12 seconds   443/tcp, 0.0.0.0:8145->80/tcp, [::]:8145->80/tcp

首次启动日志（节选）：

Linuxserver.io version: 3.8.2-ls247
Build-date: 2026-10-25T07:30:09+00:00
───────────────────────────────────────
GID/UID
───────────────────────────────────────
User UID:    1000
User GID:    1000
───────────────────────────────────────
generating self-signed keys in /config/keys, you can replace these with your own keys if required
[custom-init] No custom files found, skipping...
[ls.io-init] done.

⚠️ 注意：generating self-signed keys ... 表示镜像自动在 /config/keys 生成了自签证书（供容器内 443 使用）。生产走外部反向代理终止 TLS 时无需理会；若直接使用容器 443，可替换为自有证书。

4.4 验证服务可达

curl -sI http://localhost:8145/ | head -6

实测回显（未初始化时 302 到安装向导）：

HTTP/1.1 302 Found
Server: nginx
X-Powered-By: PHP/8.5.12
Location: ./install/
Strict-Transport-Security: max-age=63072000

302 → ./install/ 说明应用已就绪，等待初始化。

4.5 浏览器完成安装向导

浏览器打开 http://<服务器IP>:8145/，自动跳转安装向导，逐项填写：

表单项	填写值	说明
Base URL	`http://<服务器IP>:8145`	站点对外地址，生成分享链接与客户端配置的基准；上反代域名后需修改（见第九章 FAQ）
Database connection	`sqlite`	起步推荐；MySQL 需先具备外部 MySQL 实例
DSN（SQLite）	`/app/www/public/resources/database/xbackbone.db`	保持默认即可（该路径在 `/config` 映射覆盖范围内，随目录持久化）
Storage driver	`local`	本地磁盘存储；另有 FTP/S3/Google Cloud/Azure/Dropbox 可选
Storage path（local）	`/app/www/public/storage`	保持默认（同样落在 `/config` 覆盖范围内）
Email	`admin@example.com`	管理员登录账号（邮箱即登录名）
Password	自设强密码	管理员密码

提交后自动跳回首页并提示安装完成。用 curl 观察此时的初始化提交形态（等效于向导提交的请求体字段）：

curl -s -D- -o /dev/null -X POST http://localhost:8145/install/ \
  --data-urlencode 'base_url=http://localhost:8145' \
  --data-urlencode 'connection=sqlite' \
  --data-urlencode 'dsn=/app/www/public/resources/database/xbackbone.db' \
  --data-urlencode 'storage_driver=local' \
  --data-urlencode 'storage_path=/app/www/public/storage' \
  --data-urlencode 'email=admin@example.com' \
  --data-urlencode 'password=<管理员密码>'

实测回显（安装成功标志为 302 到 afterInstall）：

HTTP/1.1 302 Found
Server: nginx
X-Powered-By: PHP/8.5.12
Set-Cookie: xbackbone_session=0c16f3fc47f00ffc50cbeafca8d8fbd6; path=/; HttpOnly; SameSite=Strict
Location: http://localhost:8145/?afterInstall=true

向导完成后，持久化目录内生成应用配置文件：

cat /opt/xbackbone/config/www/xbackbone/config.php

实测回显：

<?php
return array (
  'base_url' => 'http://localhost:8145',
  'db' =>
  array (
    'connection' => 'sqlite',
    'dsn' => '/app/www/public/resources/database/xbackbone.db',
    'username' => NULL,
    'password' => NULL,
  ),
  'storage' =>
  array (
    'driver' => 'local',
    'path' => '/app/www/public/storage',
  ),
);

4.6 登录并验证功能闭环

浏览器访问 http://<服务器IP>:8145/login，用安装时填写的邮箱与密码登录，进入 Home 媒体列表页（页面标题 Home | XBackBone，页脚显示 XBackBone v3.8.2）。

命令行验证登录与首页可达：

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=<管理员密码>' | grep -iE 'HTTP|Location'
curl -s -b /tmp/xbb-cookies.txt -o /dev/null -w 'home: %{http_code}\n' http://localhost:8145/home

实测回显：

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

上传下载闭环验证（完整 API 参数见《XBackBone 3.8.2 常用操作与 API 详解》）：

# 在 Profile 页获取个人 Token 后执行；Token 亦可由命令行刷新获取
TOKEN=$(curl -s -b /tmp/xbb-cookies.txt -X POST http://localhost:8145/user/1/refreshToken)
echo "hello from XBackBone demo" > demo.txt
curl -s -F "upload=@demo.txt" -F "token=$TOKEN" 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"}

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

实测回显：

hello from XBackBone demo

至此部署完成：上传返回分享链接与直链，直链取回内容与原文件一致。

五、数据持久化说明

全部状态收敛在宿主机 /opt/xbackbone/config/（容器内 /config），重建服务不丢数据：

宿主机路径（相对 `/opt/xbackbone/config/`）	内容	说明
`www/xbackbone/config.php`	应用主配置	安装向导生成，含 base_url/数据库/存储
`www/xbackbone/resources/database/xbackbone.db`	SQLite 数据库	用户、上传记录、标签、系统设置
`www/xbackbone/storage/`	上传文件（local 驱动）	按内容指纹寻址存放
`php/php-local.ini`	PHP ini 覆盖	上传上限等（见第七章）
`nginx/site-confs/default.conf`	站点 Nginx 配置	含 `client_max_body_size 2G`
`keys/`	自签证书	可替换为自有证书
`log/`	nginx/php 日志	排障入口

⚠️ 注意：升级/迁移服务器时整目录打包 /opt/xbackbone/config/ 即可带走全部数据；仅备份数据库与 storage/ 两个子目录亦可满足最小备份集。

六、环境变量表

环境变量	默认值	说明
`PUID`	无（建议显式 1000）	应用进程运行用户 ID，与挂载目录属主一致可避免权限问题
`PGID`	无（建议显式 1000）	应用进程运行组 ID
`TZ`	`Etc/UTC`	时区（日志、上传时间戳）；本文取 `Asia/Shanghai`
`UMASK`	022	新建文件权限掩码，一般无需调整
`FILE__<变量名>`	无	以文件内容注入任意环境变量（值填文件路径），用于敏感信息

说明：XBackBone 应用层自身不读取部署类环境变量（站点配置都在 config.php 与数据库中），上述变量均为打包层（运行身份/时区/权限）约定。

七、配置参数说明

7.1 应用配置（config.php）

安装向导生成 /opt/xbackbone/config/www/xbackbone/config.php，三组键：base_url（对外地址）、db（connection/dsn/username/password）、storage（driver/path 或云存储凭据）。改后重启服务生效。逐参数详解见《XBackBone 3.8.2 配置参数详解》。

7.2 上传体积上限（php-local.ini）

默认 PHP 限制：upload_max_filesize = 2M、post_max_size = 8M，应用内展示的最大可传体积取 8MB。调大方式——编辑 /opt/xbackbone/config/php/php-local.ini：

; Edit this file to override php.ini directives
date.timezone = Asia/Shanghai
upload_max_filesize = 25M
post_max_size = 25M

重启使 PHP-FPM 重新加载：

cd /opt/xbackbone && docker compose restart

验证生效（页面内嵌配置的最大上传字节数应变为 26214400）：

curl -s -H 'Accept: text/html' -H 'User-Agent: Mozilla/5.0' \
  http://localhost:8145/<任一媒体页路径> | grep -A2 max_upload_size

实测回显：

            'max_upload_size': 26214400,

⚠️ 注意：上传链路同时受站点 Nginx 的 client_max_body_size（该镜像站点配置默认 2G）约束，调 PHP 上限超过 2G 时需同步修改 /opt/xbackbone/config/nginx/site-confs/default.conf 后重启。

八、配置文件挂载

挂载（宿主机 → 容器内）	用途	修改后生效方式
`./config → /config`	全部持久化状态	配置类改动重启服务
`./config/php/php-local.ini → /config/php/php-local.ini`	PHP ini 覆盖	`docker compose restart`
`./config/nginx/site-confs/default.conf → /config/nginx/site-confs/default.conf`	站点 Nginx 配置	`docker compose restart`

镜像首次启动若挂载目录为空，会自动铺设默认配置（nginx 站点配置、php-local.ini、目录结构），因此无需手工预置任何文件。

九、常见问题（FAQ）

Q1：启动后访问 80 端口对应的页面一直是安装向导，重装也一样？ 安装向导完成后配置写入 config/www/xbackbone/config.php；若该文件未生成，多为挂载目录权限问题（uid 1000 无写权限）。执行 chown -R 1000:1000 /opt/xbackbone/config 后重启服务重试。

Q2：上传大文件失败/413？ 三个上限取最小值：PHP upload_max_filesize（默认 2M）、PHP post_max_size（默认 8M）、Nginx client_max_body_size（默认 2G）。按第七章调 php-local.ini；超过 2G 再改站点 Nginx 配置。

Q3：换域名/上 HTTPS 反代后，页面样式丢失或分享链接仍是旧地址？ 应用按 config.php 的 base_url 生成全部链接。将 base_url 改为新对外地址（如 https://share.example.com）后重启服务；反代需透传 Host 头并支持较大请求体。

Q4：命令行执行数据库迁移时报 install 目录清理警告？ 应用自带维护命令在容器内以 uid 1000 执行时，对安装目录的收尾清理可能报 Permission denied 警告（unlink/rmdir .../install/...）。该警告只影响安装向导残留目录的删除，不影响迁移本身（迁移输出以 Done. 为准）；如需消除，可以属主身份执行该命令。

Q5：端口 8145 被其他服务占用？ ss -ltn | grep 8145 确认占用后，改编排文件的 ports（如 "8146:80"），并同步更新安装向导 base_url 与客户端配置中的服务地址。

十、参考链接

官方仓库：https://github.com/sergix44/XBackBone
官方文档（3.x）：https://sergix44.github.io/XBackBone/
LinuxServer.io 镜像文档：https://docs.linuxserver.io/images/docker-xbackbone/
配套系列：《XBackBone 3.8.2 介绍与选型指南》、《XBackBone 3.8.2 配置参数详解》、《XBackBone 3.8.2 常用操作与 API 详解》