DSpace 配置参数详解（env/local.cfg/dspace.cfg 三层优先级链与关键项）

目标：以 2026-11-01 实测的 DSpace 10.1 安装（安装目录 /dspace，部署过程见《DSpace 10.1 Docker Compose 部署指南》）为样本，讲清 DSpace 配置体系的加载顺序与优先级链（环境变量 > local.cfg > dspace.cfg）、变量注入拼写、变量插值、5 秒热重载与关键参数，全部结论均有命令实录支撑。产品背景见《DSpace 介绍与选型指南》。

一、环境信息与配置体系总览

/dspace/config 目录实测清单（节选）：

ant.properties
config-definition.xml
controlled-vocabularies
crosswalks
default.context.xml
default.license
dspace.cfg
dspace.cfg.default
dstat.cfg
dstat.map
ehcache.xml
emails
entities
hibernate-ehcache-config.xml
hibernate.cfg.xml
item-submission.dtd
item-submission.xml
launcher.xml
ldn
...

DSpace 配置体系一句话总览：一个定义文件（config-definition.xml）规定加载顺序，一个主配置（dspace.cfg）通过 include 聚合模块配置，一个可选覆写（local.cfg）承接本地定制，环境变量层压顶——四层叠加后由 Commons Configuration 合成单一视图，应用与 CLI 读到的都是合成结果。

二、加载顺序与优先级链（源码 + 三态实测）

2.1 定义文件原文

config-definition.xml 的 override 段决定优先级，注释原文即规则本身：

    <!-- Configurations in this section override one another.
         Earlier values take precedence, and override any values in later config files -->
    <override>
        <!-- Load Java System properties (does not automatically reload) -->
        <system/>
        <!-- Load Environment variables (does not automatically reload) -->
        <env/>
        <!-- Load Environment variables that contain two underlines in their names. ... -->
        <dspaceenv/>

        <!-- Allow user to override any configs in a local.cfg -->
        <properties fileName="local.cfg" throwExceptionOnMissing="false" config-name="local" config-optional="true"
                    encoding="UTF-8" config-reload="true" reloadingRefreshDelay="5000"/>

        <!-- Load our dspace.cfg (which in turn loads all module configs via "include=" statements) -->
        <properties fileName="dspace.cfg" throwExceptionOnMissing="true" encoding="UTF-8" config-reload="true"
                    reloadingRefreshDelay="5000"/>
    </override>

即最终优先级链：JVM 系统属性 > 环境变量 > local.cfg > dspace.cfg（含全部 include 的模块配置）。

2.2 三态实测（同一参数 dspace.name）

三态闭环验证了 2.1 的链序。dsprop 读到的最终值与 API 回显一致：

$ /dspace/bin/dspace dsprop -p dspace.name
DSpace via local.cfg

三、环境变量注入拼写（__P__ / __D__）

配置项名里大量出现点号与短横线（dspace.server.url、oai.enabled），而 shell 变量名不允许这些字符。DSpace 为此提供专用 dspaceenv provider，定义文件注释原文：

This provider translates "__P__" to periods and "__D__" to dashes in environment variables.

本部署实测环境变量清单（后端进程 env 节选）与还原映射：

注意 db__P__url、solr__P__server 这类不带 dspace 前缀的键同样适用该拼写；标准 Java 系统属性（-Ddb.url=...）走 <system/> 层，优先级更高。

四、变量插值与派生配置

dspace.cfg 与模块配置大量使用 ${key} 插值，合成视图解析后上游覆写会级联传导。实测链条：oai.cfg 原文

oai.url = ${dspace.server.url}/${oai.path}
oai.path = oai

dspace.server.url 被环境变量覆写后，派生值同步改变：

$ /dspace/bin/dspace dsprop -p oai.url
http://192.168.1.200:8139/server/oai

端点可达性实测：GET /server/oai?verb=Identify 返回 HTTP 302，Location: http://127.0.0.1:8139/server/oai/，跟随后输出 OAI 索引页（模板注释原文 "DSpace OAI default index template"）。同理：

$ /dspace/bin/dspace dsprop -p assetstore.dir
/dspace/assetstore

对应 assetstore.cfg 原文 assetstore.dir = ${dspace.dir}/assetstore。

💡 排查提示：改了 dspace.server.url 却发现 OAI/SWORD/邮件链接等"跟着变"或"该变没变"，先 dsprop 读派生项最终值，确认是插值传导还是该模块写死了字面量。

五、5 秒热重载实测

定义文件中 local.cfg 与 dspace.cfg 均声明 config-reload="true" reloadingRefreshDelay="5000"——配置读取层每 5 秒重扫文件。端到端实测（改 local.cfg、不重启任何进程）：

### 改前 API 回显
DSpace via local.cfg
### 写入 local.cfg: dspace.name = DSpace hot-reload test，等待 8 秒
### 改后 API 回显（无重启）
DSpace hot-reload test
### 恢复 local.cfg 原值，等待 8 秒
DSpace via local.cfg

热重载边界（实践守则）：dsprop/API 回显这类每次读取动态取值的参数即时生效；而数据库连接、Solr 客户端、Spring Bean 初始化时固化的参数（如 db.url、solr.server）改完仍需重启进程。判断标准：看该值是在"用时读取"还是"启动注入"。

六、关键参数详解（出厂默认 vs 本部署实测）

三点展开：

1. 站点标识三件套联动：dspace.server.url/dspace.ui.url 决定 API 根资源回显与全部 HAL _links、Handle 解析页地址（实测 dc.identifier.uri 生成为 http://192.168.1.200:8139/handle/123456789/1）——改入口不改这两项，对外链接全部指向旧地址。
2. 口令策略在模块层：密码长度校验不在 dspace.cfg 而在 modules/authentication-password.cfg，local.cfg 直接写 authentication-password.regex-validation.pattern = ... 即可覆写（键名无层级限制，见第七节）。
3. 出厂默认值即排障线索：db.url/solr.server 默认 localhost 只适用于单机同机部署；多组件分离部署必须覆写（部署篇第十节问题 4）。

七、dspace.cfg 的 include 机制与 modules 目录

dspace.cfg（2072 行）尾部实测 53 行 include 声明（行号 2020–2072），形如：

include = ${module_dir}/actuator.cfg
include = ${module_dir}/altcha.cfg
...
include = ${module_dir}/authentication.cfg
include = ${module_dir}/authentication-password.cfg
...
include = ${module_dir}/oai.cfg
...
include = ${module_dir}/workflow.cfg
include = ${module_dir}/audit.cfg

${module_dir} 即 dspace.dir 下的 config/modules，实测目录与 include 一一对应（节选）：

actuator.cfg
altcha.cfg
altmetrics.cfg
assetstore.cfg
audit.cfg
authentication-ip.cfg
authentication-ldap.cfg
authentication-oidc.cfg
authentication-password.cfg
authentication-saml.cfg
authentication-shibboleth.cfg
authentication.cfg
authority.cfg
bulkedit.cfg
...

模块化的实际意义：功能开关集中在模块 cfg（如 LDAP/OIDC/SAML 认证、S3 资产存储、OAI、IIIF、统计），定制时把对应 cfg 的关键项抄进 local.cfg 覆写，不动 dspace.cfg 本体，升级无痛。

八、改配置生效方式速查

九、常见问题

1. "配置改过又变回去了"：改动落在可写层（直接编辑实例内文件）而非持久卷，重建即丢。实测：态 2 重建后 dspaceName 回落出厂值。解法：local.cfg 用挂载卷固化，或干脆全部走环境变量。
2. 想经 API 读配置值，全部 404：GET /server/api/config/properties/dspace.name、.../authentication.password.enabled、.../dspace.environment 实测均 HTTP 404（{"status":404,...,"path":"/server/api/config/properties/dspace.name"}）。10.1 该端点不暴露常规配置项；读最终值用 dspace dsprop -p <key>（本文通篇用法）。
3. 改了 dspace.server.url，OAI 链接没变/变了：插值级联所致，用 dsprop -p oai.url 验证派生链（第四节方法）。
4. local.cfg 里写 dspace.dir 不生效：安装根在启动早期固化，属"启动注入"类参数，热重载救不了——放环境变量或系统属性层。
5. 优先级判断没把握时：复制第二节三态实验法——同一参数在 env/local.cfg/dspace.cfg 各写不同值，dsprop 读一次即知谁赢。

十、参考链接

1. 站内：《DSpace 介绍与选型指南》
2. 站内：《DSpace 10.1 Docker Compose 部署指南》
3. 站内同类配置篇对照：《EPrints 配置参数详解（cfg.d 分层体系与关键项）》
4. DSpace 官方文档 DSDOC10x（Configuration 章节，查询日期 2026-11-01）：https://wiki.lyrasis.org/display/DSDOC10x
5. Apache Commons Configuration CombinedBuilder（config-definition.xml 注释原文引用的规范，查询日期 2026-11-01）：https://commons.apache.org/proper/commons-configuration/userguide/howto_combinedbuilder.html