XBackBone 3.8.2 配置参数详解

目标：逐层讲清 XBackBone 3.8.2 的全部可配置项——应用主配置 config.php、PHP ini 覆盖、站点 Nginx 配置、Web 系统设置页与运行参数，给出实测值、生效方式与生产推荐模板。已在 Ubuntu 24.04 LTS（x86_64）+ XBackBone 3.8.2 打包发行版环境实测通过（2026-11-01）。

一、环境信息

• 操作系统：Ubuntu 24.04 LTS（x86_64）；
• 软件版本：XBackBone 3.8.2（LinuxServer.io 打包发行版，集成 Nginx + PHP-FPM 8.5，构建号 3.8.2-ls247）；
• 安装根目录：/opt/xbackbone/（持久化根，下称「安装根」），配置与数据位于 /opt/xbackbone/config/；
• 服务监听：8145 端口（HTTP），管理地址 http://localhost:8145；
• 数据库：SQLite（/opt/xbackbone/config/www/xbackbone/resources/database/xbackbone.db）；
• 存储驱动：local（/opt/xbackbone/config/www/xbackbone/storage/）。

二、前置条件

• 已按 《XBackBone 3.8.2 Docker Compose 部署指南》完成部署并通过安装向导初始化（config.php 已生成）；
• 具备管理员账号（本文示例为安装时创建的 admin@example.com）；
• 修改配置前了解三层生效机制：config.php 与 Nginx 站点配置、PHP ini 覆盖均需重启服务生效；系统设置页参数保存即生效。

三、参数查看与修改方式

XBackBone 3.8.2 的配置分散在四个层面，先建立全景再逐层详解：

查看与修改示例：

# 查看应用主配置
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',
  ),
);

# 查看 PHP 生效值（上传与内存相关）
php -i | grep -E '^(upload_max_filesize|post_max_size|memory_limit)'

实测回显（调整前默认值）：

memory_limit => 128M => 128M
post_max_size => 8M => 8M
upload_max_filesize => 2M => 2M

⚠️ 注意：config.php 是标准 PHP 数组文件，手工编辑后可先 php -l <文件> 做语法校验再重启服务，避免语法错误导致整站不可用。

四、参数总览

4.1 config.php 参数表

4.2 php-local.ini 常用键

4.3 系统设置页参数表（存数据库）

五、核心参数分类详解

5.1 base_url：站点对外地址

base_url 决定应用生成的一切链接：分享链接、直链、客户端上传配置、邮件内链接。实测初始值 http://localhost:8145，对应部署时向导所填站点地址。

• 换域名或加 HTTPS 后必须同步修改，否则页面样式资源仍按旧地址加载（浏览器混合内容拦截）且新上传返回旧域名链接；
• 修改方法：编辑 config.php 中 'base_url' => 'https://share.example.com'，重启服务生效；
• 客户端（ShareX 等）引用的是 Token 配置内的完整地址，base_url 变更后需在客户端重新下载配置。

💡 技术拓展：自托管 Web 应用的「对外地址」有 base_url 直写与反代自动推导两类实现。直写式（XBackBone 3.x 采用）把地址固化为配置，行为确定、不受代理头影响，但换域名必须改配置；推导式按请求 Host/X-Forwarded-* 动态拼链接，免改配置但代理头透传不当时会生成错误链接。XBackBone 的选择让分享链接在任意代理形态下都稳定可预期。

5.2 db：数据库连接

安装向导提供 sqlite 与 mysql 两种连接（实测向导选项），对应 config.php 的 db 数组：

• SQLite（默认起步）：dsn 即数据库文件路径，向导默认值 /app/www/public/resources/database/xbackbone.db，该路径位于安装根映射内，随持久化目录落盘。实测确认文件生成于 config/www/xbackbone/resources/database/xbackbone.db。零外部依赖，适合个人与小团队；
• MySQL（规模化）：需先自备 MySQL 实例与库，向导选择 mysql 后填写主机库名（dsn）与 username/password，凭据写入 config.php。适合多实例共享或已有 MySQL 运维体系的场景。

💡 技术拓展：SQLite 与 MySQL 的取舍——SQLite 单文件、零部署、读写为文件锁粒度，并发写多时可能触发出错，适合「几人以下、写频率低」的分享站；MySQL 连接级并发、易备份复制，适合用户多或接入了自动化上传客户端持续写入的场景。XBackBone 个人分享场景写频率通常很低，SQLite 即为官方默认推荐。

5.3 storage：存储后端

storage.driver 六种取值（安装向导实测列出）：local、ftp、s3、google-cloud、azure、dropbox。不同驱动对应不同凭据字段（向导表单实测字段名）：

• local 驱动 path 默认落在安装根内，随目录持久化与备份；改到独立数据盘时同步迁移存量文件并保证目录可写；
• S3 系驱动把上传文件外移到对象存储，数据库仍在本机，适合「本地盘小、已有对象存储」的场景。

5.4 php-local.ini：上传上限与运行参数

文件位于 config/php/php-local.ini，初始内容由安装程序生成（实测含一行时区）：

; Edit this file to override php.ini directives

date.timezone = Asia/Shanghai

追加上传上限调整（示例调到 25M）：

upload_max_filesize = 25M
post_max_size = 25M

重启服务后实测生效：

php -i | grep -E '^(upload_max_filesize|post_max_size)'

实测回显：

post_max_size => 25M => 25M
upload_max_filesize => 25M => 25M

同时，应用前端展示的最大上传体积联动变化——媒体页内嵌配置实测从 8388608（8MB）变为 26214400（25MB）：

'max_upload_size': 26214400,

⚠️ 注意：post_max_size 必须 ≥ upload_max_filesize，且整个链路还受站点 Nginx client_max_body_size 约束，三者取最小值才是实际可传体积（见 5.5）。

5.5 站点 Nginx 配置：请求体上限与 TLS

站点配置位于 config/nginx/site-confs/default.conf，与上传直接相关的实测值：

client_max_body_size 2G;

• PHP 上限调到 2G 以上时，同步调大该值并重启服务；
• 该文件同时承载 TLS 证书引用（自签证书在 config/keys/，可替换为自有证书）与反代所需配置；外置反向代理时，代理侧同样需要放行大请求体。

5.6 系统设置页：站点行为参数

管理员登录后访问 http://<主机>:8145/system（实测页面标题 System Settings），参数明细见第四章 4.3 表。三个高频操作：

1. 关闭注册：Registrations enabled 开关置关并保存——个人站防陌生人注册的第一道闸（实测页面默认即关闭状态）；
2. 启用配额：Enable user quota 置开后，Default User Quota 填写默认配额（如 1G），页内提示支持的写法为 512M, 2G, 1T, ...；页内另提供 Recalculate user quota from disk（按磁盘实际重算各用户用量）；
3. 清理孤儿数据：Clean Orphaned Uploads 按钮扫描并清理数据库无记录的残留文件。

设置页同屏还提供系统升级面板（检查新版本并在页内一键升级应用）与自定义 head 注入（custom_head，可放统计脚本或全局样式）。

5.7 运行参数：部署编排注入

运行身份（PUID/PGID）、时区（TZ）、权限掩码（UMASK）等由部署编排层注入，明细与实测值见 《XBackBone 3.8.2 Docker Compose 部署指南》环境变量表；应用层配置不读取这些变量，二者职责分离。

六、生产配置模板

适用场景：3–10 人团队内部素材/截图分享站；服务器 2 核 4GB 内存、100GB 数据盘；MySQL 已有实例或独立数据盘 SQLite。

6.1 config.php 模板（SQLite + 独立数据盘）

<?php
return array (
  'base_url' => 'https://share.example.com',
  'db' =>
  array (
    'connection' => 'sqlite',
    'dsn' => '/data/xbackbone/xbackbone.db',
    'username' => NULL,
    'password' => NULL,
  ),
  'storage' =>
  array (
    'driver' => 'local',
    'path' => '/data/xbackbone/storage',
  ),
);

要点：base_url 写最终对外 HTTPS 域名；dsn 与 path 指向独立数据盘挂载点 /data/xbackbone/（迁移时把旧数据库文件与 storage 内容移入并保证运行用户可写）。

6.2 php-local.ini 模板（100M 上限）

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

要点：memory_limit 适度上调以兜住大文件上传处理；同步确认站点 Nginx client_max_body_size ≥ 100M。

6.3 系统设置项推荐

注册关闭（register_enabled 关）、启用配额（quota_enabled 开 + default_user_quota: 10G）、reCAPTCHA 仅在必须开放注册时开启。

七、常见问题（FAQ）

Q1：调了 php-local.ini 上传仍失败？ 实际上限 = min(PHP upload_max_filesize，PHP post_max_size，Nginx client_max_body_size)。三层逐一核对（php -i 与 config/nginx/site-confs/default.conf），取最小值改齐；PHP 层改动必须重启服务。

Q2：从 SQLite 换 MySQL 会丢数据吗？ 应用未内置库间迁移工具。换库属于「重新初始化」：新装实例走向导选 MySQL，旧 SQLite 的用户与上传记录不会自动带过去，上传文件本身可整目录保留（内容按指纹寻址，不依赖库内记录则无法在页面展示，需重新上传或自行做库间搬运）。

Q3：config.php 改坏了整站打不开？ 先 php -l config/www/xbackbone/config.php 校验语法；仍异常时，把文件还原为「三组键最小结构」（base_url/db/storage，见第三章实测回显）即可恢复启动，再逐项加回修改。

Q4：页面样式错乱、链接仍指向旧地址？ base_url 与实际访问地址不一致所致，按 5.1 改齐并重启；浏览器侧清缓存后复测。

Q5：上传目录属主与运行用户不一致导致向导无法保存？ 保证安装根下 config/ 全部文件属主与运行身份（PUID/PGID）一致；出现写不进的报错时统一 chown 后重启服务。

八、参考链接

• 官方仓库：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 Docker Compose 部署指南》、《XBackBone 3.8.2 常用操作与 API 详解》