ResourceSpace 11.0 配置参数详解

目标：系统梳理 ResourceSpace 11.0 的配置体系——配置从哪里加载、优先级如何、在哪里查看、通过什么方式修改，并按功能分类详解核心参数的默认值与生产建议。本文所有参数默认值均逐行摘自官方源码 include/config.default.php，所有机制验证均在下述实测环境中完成。

一、环境信息

本文实测环境与版本信息（2026-11-01 实测）：

• 操作系统：Ubuntu 24.04.5 LTS（x86_64），宿主机 IP 192.168.1.172
• ResourceSpace：11.0（官方稳定发布线，SVN releases/11.0 revision 30001）
• 部署方式：Docker Compose（应用容器基于 php:8.3-apache 镜像，实际 PHP 8.3.36；数据库 mariadb:11.8，实测 11.8.9-MariaDB）
• 访问地址：http://192.168.1.172:8132（容器 8132→80 端口映射）
• 示例管理员账号：admin / q1w2e3r4
• 源码参考：官方分发源码包内 include/config.default.php 共 3285 行，其中以 $ 开头的顶层参数定义 743 项

部署环境沿用本专栏《ResourceSpace 11.0 Docker Compose 部署指南》搭建的栈，配置文件位于 include/config.php。

二、前置条件

• 已按部署指南完成 ResourceSpace 11.0 安装并能正常登录（安装向导会生成基础 config.php）
• 具备应用容器的执行权限（docker exec），用于查看生效配置与修改文件
• 具备数据库容器执行权限（docker exec），用于核对数据库侧配置存储
• 管理员账号可访问后台 Admin → System configuration 页面

三、配置体系与加载优先级

ResourceSpace 的配置分散在三处，加载顺序决定了优先级。以下为 include/boot.php 实际加载代码（摘自 11.0 源码 69-82 行）：

# Load the default config first, if it exists, so any new settings are present even if missing from config.php
if (file_exists(__DIR__ . "/config.default.php")) {
    include __DIR__ . "/config.default.php";
}
if (file_exists(__DIR__ . "/config.deprecated.php")) {
    include __DIR__ . "/config.deprecated.php";
}

# Load the real config
if (!(file_exists(__DIR__ . "/config.php") && filesize(__DIR__ . "/config.php") > 0)) {
    header("Location: pages/setup.php");
    die(0);
}
include __DIR__ . "/config.php";

两点值得注意：

1. PHP 层是"后加载者覆盖先加载者"：config.default.php（全部默认值）先加载，config.php（站点配置）后加载，同名变量以后者为准。
2. config.php 存在性检查是双条件：file_exists() 且 filesize() > 0。文件缺失或为 0 字节都会跳转安装向导 pages/setup.php。这个检查在 Docker 单文件挂载场景下有一个经典陷阱——宿主文件不存在时 Docker 会自动创建一个目录挂载过去，而目录恰好能骗过 file_exists + filesize > 0 检查（目录 stat 大小 4096），导致错误页以 HTTP 200 返回（实测排障过程见部署指南 FAQ）。

在 PHP 配置之后，boot.php 还会从数据库加载系统级配置（摘自 boot.php 335 行附近）：

// Load system wide config options from database and then store them to distinguish between the system wide and user preference
process_config_options(array());
$system_wide_config_options = get_defined_vars();

认证阶段再叠加两级覆盖（摘自 include/authenticate.php 250-251 行）：

process_config_options(array('usergroup' => $usergroup));
process_config_options(array('user' => $userref));

process_config_options() 的实现（include/config_functions.php 532 行）会把查到的值直接写回变量表：$GLOBALS[$config_option['parameter']] = $param_value;。查询的是 user_preferences 表，并且回退逻辑明确——数据库无记录时使用 PHP 配置文件中的值（config_functions.php 371-372 行）。

最终优先级（从高到低）：

优先级实测（在实测环境完整复现）：先通过容器 CLI 确认当前生效值来自 config.php：

$ docker exec resourcespace-11.0-app php -r '$_SERVER["HTTP_HOST"]="192.168.1.172:8132"; include "/var/www/html/include/boot.php"; echo "applicationname=" . $applicationname . PHP_EOL;'
CLI_BOOT_OK applicationname=ResourceSpace

向系统级配置表插入一条覆盖记录，再读生效值：

# 数据库侧插入系统级覆盖（user/usergroup 均为 NULL 即系统级）
$ docker exec resourcespace-11.0-db mariadb -uroot -pq1w2e3r4 resourcespace \
  -e "insert into user_preferences (user,usergroup,parameter,value) values (null,null,'applicationname','RS-DB-OVERRIDE');"
# 清除查询缓存后读取
$ docker exec resourcespace-11.0-app sh -c 'rm -f /var/www/html/filestore/tmp/querycache/preferences_*.json'
$ docker exec resourcespace-11.0-app php -r '$_SERVER["HTTP_HOST"]="192.168.1.172:8132"; include "/var/www/html/include/boot.php"; echo $applicationname . PHP_EOL;'
RS-DB-OVERRIDE          # 数据库配置覆盖了 config.php
# 删除记录、清缓存后还原
$ docker exec resourcespace-11.0-db mariadb -uroot -pq1w2e3r4 resourcespace \
  -e "delete from user_preferences where parameter='applicationname';"
$ docker exec resourcespace-11.0-app php -r '$_SERVER["HTTP_HOST"]="192.168.1.172:8132"; include "/var/www/html/include/boot.php"; echo $applicationname . PHP_EOL;'
ResourceSpace           # 回退到 config.php 的值

实验验证了优先级表中的第 3 级 > 第 4 级，以及数据库无记录时回退 PHP 配置的行为。

四、参数查看与修改方式

4.1 查看参数默认值

全部参数默认值集中在 include/config.default.php（3285 行、743 项）。该文件随版本分发，升级时会被覆盖，切勿直接修改。官方惯例是把需要自定义的参数复制到 config.php 中赋值（文件头注释原文：All custom settings should be entered in this file. Options may be copied from config.default.php and configured here.）。

4.2 查看当前生效值

用容器 CLI 引导完整启动流程后读取变量，看到的就是"经过全链路覆盖后的最终值"：

$ docker exec resourcespace-11.0-app php -r '$_SERVER["HTTP_HOST"]="192.168.1.172:8132"; include "/var/www/html/include/boot.php"; echo $session_length . PHP_EOL;'
300

注意 CLI 方式必须提供 $_SERVER["HTTP_HOST"]（或与 $baseurl 一致的值），否则部分依赖主机名的逻辑行为可能与 Web 端不同。

4.3 修改方式一：编辑 config.php（推荐用于服务器级参数）

config.php 是安装向导生成的站点配置文件，实测环境中的完整内容如下（敏感值已按实际部署保留结构，口令为演示口令）：

<?php
###############################
## ResourceSpace
## Local Configuration Script
###############################

# All custom settings should be entered in this file.
# Options may be copied from config.default.php and configured here.

# MySQL database settings
$mysql_server = 'db';
$mysql_username = 'resourcespace';
$mysql_password = 'q1w2e3r4';
$mysql_db = 'resourcespace';

$mysql_bin_path = '/usr/bin';

# Base URL of the installation
$baseurl = 'http://192.168.1.172:8132';

# Email settings
$email_notify = 'admin@example.com';
$email_from = 'admin@example.com';
# Secure keys
$scramble_key = '720edec7005c283c7b1f01abb9cdcc04f55f304e54a9148cc88cebbf1641407c';
$api_scramble_key = '070147602f0038f487645ac82186c134ad0adb55fd74a606de30c3e0fd8777df';

# Paths
$imagemagick_path = '/usr/bin';
$ghostscript_path = '/usr/bin';
$ffmpeg_path = '/usr/bin';
$exiftool_path = '/usr/bin';
$pdftotext_path = '/usr/bin';

$applicationname = 'ResourceSpace';
$homeanim_folder = 'filestore/system/slideshow_15c88b73b40bea8';

文件后半段是 11.0 安装器为新装实例预置的默认特性开关（$ffmpeg_preview_force、$upload_then_edit、$filestore_evenspread、$use_zip_extension 等）以及插件激活行 $plugins[] = "brand_guidelines";。

修改后对 Web 生效需要重启 PHP 进程或重建容器（标准镜像下 Apache mod_php 在请求间复用配置文件的场景少，但 CLI 长驻脚本与 opcache 可能缓存旧值，稳妥做法）：

$ docker restart resourcespace-11.0-app

Docker 场景关键提醒：容器文件系统是临时的，config.php 必须以单文件 bind mount 挂载持久化（部署指南 compose 中 - ../config.php:/var/www/html/include/config.php 一行），且宿主文件必须先于 docker compose up 存在，否则会被自动创建成目录（详见部署指南 FAQ Q2）。

4.4 修改方式二：后台 System configuration 页面（数据库存储，立即生效）

以管理员登录后进入 Admin → System configuration（URL：/pages/admin/admin_system_config.php）。实测页面说明文字：

The options on this page are system wide and can change some of the functionality available to the users. Please note that any option that is also user specific will take precedence if set.

页面是单个长表单，含 "Only show modified values" 复选框（实测 DOM 中 name="only_modified"）。实测页面字段包括：System 区块的 Application name（applicationname）、Email from address（email_from）、Email notify（email_notify）、时区（user_local_timezone）、session_length、minyear、recent_search_quantity、watermark、download_filename_format、inactive_user_disable_days、resource_share_expire_days_default 等。

保存机制（源码实证）：该页面由 $page_def 数组驱动（pages/admin/admin_system_config.php 20-24 行定义 System 区块），提交后经 set_config_option() 写入数据库 user_preferences 表（config_functions.php 133 行 INSERT INTO user_preferences (user,parameter,value)，系统级记录 user/usergroup 为 NULL），并在保存后立即调用 clear_query_cache("preferences")（config_functions.php 168 行）——因此通过后台页面修改的参数无需重启、立即生效。

4.5 修改方式三：用户偏好与用户组偏好

user_preferences 表的另外两类记录（user=用户ID / usergroup=组ID）分别对应用户个人设置（My preferences）与管理员在用户管理中为用户组设定的偏好。同一参数同时存在多级记录时按第三节优先级表取值。页面原话也提示了这一点："any option that is also user specific will take precedence if set"。

4.6 查看数据库侧配置记录

$ docker exec resourcespace-11.0-db mariadb -uroot -pq1w2e3r4 resourcespace \
  -e "select ref,user,usergroup,parameter,left(value,40) as value from user_preferences;"

实测环境未通过后台做过任何修改时该表为空（count = 0），所有值回落到 config.php / config.default.php——这正是 "Only show modified values" 的数据来源语义。

五、核心参数分类详解

以下默认值均逐行摘自 include/config.default.php（标注行号），说明列为源码注释或实测行为。

5.1 数据库连接

5.2 站点基础

5.3 安全密钥与登录会话

密码哈希算法与 $scramble_key 的关系（include/login_functions.php 实测源码）：

password_hash(hash_hmac('sha256', "RS{username}{password}", $scramble_key), PASSWORD_BCRYPT, ['cost'=>12])

即先以 RS用户名口令 做 HMAC-SHA256（盐为 $scramble_key），再对结果做 bcrypt(cost=12)。忘记管理员口令时按此公式生成新哈希写入 user.password 即可（部署指南 FAQ Q3 有完整操作）。

5.4 邮件与 SMTP

5.5 存储与文件管理

实测 boot.php 兜底行回显：

246: $storagedir ??= dirname(__DIR__) . '/filestore';

5.6 图像处理与预览生成

工具路径核对命令（容器内实测）：

$ docker exec resourcespace-11.0-app sh -c 'which convert gs ffmpeg exiftool pdftotext'
/usr/bin/convert
/usr/bin/gs
/usr/bin/ffmpeg
/usr/bin/exiftool
/usr/bin/pdftotext

5.7 上传限制

上传上限实际由三层决定：PHP upload_max_filesize/post_max_size（本部署镜像实配 1024M）→ $upload_max_file_size（应用层，默认未启用）→ 反向代理层 client_max_body_size（若有）。排查上传失败按此顺序逐层核对（部署指南 FAQ Q5）。

5.8 搜索与性能

查询缓存的物理位置是 filestore/tmp/querycache/（include/database_functions.php 808-815 行 get_query_cache_location()），以 JSON 文件存储、按 $cache 分组（如 preferences_*.json）。实测容器内该目录有 39 个缓存文件。这个机制是"改了配置不生效"问题的高频根因，见第七节 Q1。

5.9 API 与集成

API 签名算法与调用实操见本专栏《ResourceSpace 11.0 API 使用详解》。

5.10 后台任务

ResourceSpace 的后台任务（预览生成、邮件发送、元数据提取等）由 batch/cron.php 入口驱动，需要外部 cron 周期触发，未配置时任务在 job_queue 表中持续排队（表现为缩略图不生成，部署指南 FAQ Q6）。推荐配置：

*/5 * * * * docker exec resourcespace-11.0-app php /var/www/html/batch/cron.php

5.11 插件

插件也可通过后台 Admin → Plugin manager 启用（写入 plugins 表）；config.php 方式激活的插件需在插件表中存在对应记录（boot.php 279-280 行逻辑）。

六、生产环境 config.php 模板

以下模板按最小可用 + 生产加固整理，可直接复制修改（值与注释均来自上文实测/源码默认值）：

<?php
# ---- 数据库 ----
$mysql_server = 'db';                    # Compose 服务名
$mysql_server_port = 3306;
$mysql_username = 'resourcespace';
$mysql_password = 'CHANGE_ME_DB_PASSWORD';
$mysql_db = 'resourcespace';
$mysql_bin_path = '/usr/bin';

# ---- 站点 ----
$baseurl = 'https://dam.example.com';    # 与对外访问地址完全一致，无尾斜杠
$applicationname = 'My Company DAM';
$defaultlanguage = 'en';                 # 'zh' 需确认语言包可用性
$user_local_timezone = 'Asia/Shanghai';

# ---- 安全（安装向导已生成的两个 key 保持不变）----
$scramble_key = 'KEEP_THE_GENERATED_64CHAR_KEY';      # 换了所有密码失效
$api_scramble_key = 'KEEP_THE_GENERATED_64CHAR_KEY';  # API 签名盐

# ---- 登录加固 ----
$session_length = 240;                   # 4 小时
$max_login_attempts_per_username = 5;
$max_login_attempts_wait_minutes = 15;

# ---- 邮件 ----
$email_from = 'dam-noreply@example.com';
$email_notify = 'dam-admin@example.com';
$use_phpmailer = true;
$smtp_host = 'smtp.example.com';
$smtp_port = 587;
$smtp_secure = 'tls';
$smtp_auth = true;
$smtp_username = 'dam-noreply@example.com';
$smtp_password = 'CHANGE_ME_SMTP_PASSWORD';

# ---- 存储与清理 ----
# $storagedir 默认安装目录 filestore/，Docker 下挂载该目录即可，不必显式配置
$filestore_evenspread = true;
$file_checksums = true;
$purge_temp_folder_age = 90;

# ---- 上传 ----
$upload_max_file_size = '500mb';         # 按业务需要，同时核对 PHP 层
$upload_chunk_size = '50mb';
$upload_concurrent_limit = 3;

# ---- 预览 ----
$ffmpeg_preview = true;
$ffmpeg_preview_seconds = 120;
$imagemagick_quality = 90;
$preview_generate_max_file_size = 100;

# ---- API ----
$enable_remote_apis = true;              # 不对外提供 API 时置 false
$api_upload_urls = array('files.example.com');  # upload_file_by_url 源站白名单

# ---- 后台任务 ----
$cron_job_time_limit = 1800;

# ---- 插件（开源插件逐个追加）----
$plugins[] = 'brand_guidelines';

模板要点：两个 scramble key 沿用安装向导生成值；$storagedir 在 Docker 部署下靠默认兜底 + 目录挂载即可；对外提供 API 时必须设置 $api_upload_urls 白名单。

七、常见问题

Q1：改了配置但不生效？先查查询缓存。

实测发现的过程：直接向 user_preferences 表插入系统级覆盖记录后，CLI 读取生效值仍是旧值；删除 filestore/tmp/querycache/preferences_*.json 后立即读到新值。原因是 ps_query() 对带缓存分组的查询写文件缓存（$storagedir/tmp/querycache/，有效期 $query_cache_expires_minutes=30 分钟），绕过应用层直改数据库不会清缓存。三条结论：

• 通过后台 System configuration 页修改：保存即调用 clear_query_cache("preferences")，立即生效，无需任何操作；
• 通过 config.php 修改：重启容器（docker restart resourcespace-11.0-app）并按需清缓存目录；
• 直连数据库修改（不建议）：必须手动删除对应分组缓存文件，否则最长 30 分钟内旧值继续生效。

Q2：后台页面和 config.php 里的同一个参数值不一致，以谁为准？

以优先级高者为准：用户偏好 > 用户组偏好 > System configuration（数据库系统级）> config.php > config.default.php。System configuration 页面上的输入框初值来自 config.php（get_config_option 回退 $GLOBALS 的行为），一旦在页面保存过，数据库记录接管，之后再改 config.php 中同名参数不会反映到界面。要回到"以 config.php 为准"，删除 user_preferences 表中对应 parameter 的记录即可（注意清缓存）。

Q3：$baseurl 填错导致登录后一直弹回登录页/跳错域名？

$baseurl 同时决定 Cookie 作用域与站内跳转目标。实测中用 http://127.0.0.1:8132 访问而 $baseurl 是 http://192.168.1.172:8132 时，登录后的重定向把请求带离登录域，会话 Cookie 不跟随，表现无限回到 nocookies=true 的登录页。修改 config.php 中 $baseurl 与实际访问地址一致并重启容器。

Q4：升级后 config.default.php 被覆盖，我的改动丢了？

这是预期行为。自定义参数只应存在于 config.php（升级不动它）；config.default.php 永远保持官方原样。若曾直接改过 default 文件，升级前应先 diff 备份并迁移到 config.php。官方升级指南同样强调 config.php 是唯一的自定义配置落点。

Q5：同一个参数在哪里查当前实际值最快？

容器 CLI 一行命令（第三节 4.2 的方法）：

$ docker exec resourcespace-11.0-app php -r '$_SERVER["HTTP_HOST"]="192.168.1.172:8132"; include "/var/www/html/include/boot.php"; echo $参数名 . PHP_EOL;'

数组类参数可用 var_export($参数名, true)。该方法读到的是完整优先级链覆盖后的最终值，且不需要登录后台。

Q6：System configuration 页面上没有我想改的参数？

后台页面只暴露 $page_def 注册过的参数子集（本版本实测含 applicationname、email、session_length、watermark、recent_search_quantity 等 30 余项），且 $system_config_hide（2976 行）可再隐藏一部分。绝大多数参数（本文第五节列出的 743 项中的其余全部）只能走 config.php 修改。

八、参考链接

• 官方配置总览（System configuration）：https://www.resourcespace.com/knowledge-base/systemadmin/system_configuration
• 官方 config.php 说明：https://www.resourcespace.com/knowledge-base/systemadmin/install_overview
• 官方升级指南（config.php 与 config.default.php 的关系）：https://www.resourcespace.com/knowledge-base/systemadmin/upgrading
• 官方 API 知识库（$api_scramble_key 与签名）：https://www.resourcespace.com/knowledge-base/api/
• 参数默认值权威来源：随版本分发的 include/config.default.php（本文行号以 SVN releases/11.0 revision 30001 为准）
• 本专栏系列：《ResourceSpace 11.0 介绍与选型指南》、《ResourceSpace 11.0 Docker Compose 部署指南》、《ResourceSpace 11.0 API 使用详解》