SeedDMS 6.0.42 配置参数详解

目标：以实测环境生成的 conf/settings.xml 全文为底本，逐类讲清 SeedDMS 6.0.42 的参数体系、默认值与生效方式（Web 后台 / 直接编辑 / dms:setconfig / --config / 环境变量），并给出可落地的生产配置模板。全文参数与回显取自 seeddms-server（Ubuntu 24.04.5 LTS + PHP 8.3.6 + MariaDB 10.11.14，SeedDMS 6.0.42）实测。

一、环境信息

操作系统：Ubuntu 24.04.5 LTS；主机名 seeddms-server，站点 http://seeddms-server/
应用：SeedDMS 6.0.42，quickstart 布局 /var/www/seeddms60x（conf/ 配置、data/ 内容库与索引缓存、www/ 文档根）
配置文件：/var/www/seeddms60x/conf/settings.xml（安装向导生成，XML 单文件承载全部参数）
数据库：MariaDB 10.11.14，库/账号 seeddms/seeddms（密码 q1w2e3r4，演示值）
管理账号：admin / q1w2e3r4

二、前置条件

已按《Ubuntu 24.04 安装 SeedDMS 6.0.42 指南》完成部署并通过安装向导生成 conf/settings.xml；
具备服务器 root 权限（编辑配置文件、执行 CLI）与 Web 管理员登录态（后台参数页）；
修改前备份：cp /var/www/seeddms60x/conf/settings.xml /var/www/seeddms60x/conf/settings.xml.bak（该文件是单点全量配置，改坏即全站不可用）。

三、参数查看与修改方式

SeedDMS 没有分散的多配置文件，全部参数集中在一棵 XML 树里，四种触达方式实测如下。

3.1 Web 管理后台

以 admin 登录，「管理」菜单下的站点设置/用户与分组等页面可改显示、编辑、通知类参数；后台写回的就是 conf/settings.xml，适合日常少量改动。

3.2 直接编辑 settings.xml

vi /var/www/seeddms60x/conf/settings.xml

XML 属性即参数名，改完保存即生效（PHP 每请求读取，无需重启服务）。文件每个节点上方保留了官方注释块，说明各属性含义与默认值——这也是最权威的参数文档（见 4.3 实测导出）。

3.3 命令行 dms:setconfig（推荐脚本化改单项）

内置 Symfony 命令可原子化改单项并写回文件（实测回显）：

$ cd /var/www/seeddms60x && php seeddms/utils/console dms:setconfig --name=baseUrl --value="http://seeddms-server/"
Changing 'baseUrl' from '' to 'http://seeddms-server/'.
$ grep -o 'baseUrl="[^"]*"' conf/settings.xml | head -1
baseUrl="http://seeddms-server/"

--name/--value 支持多次传入成对修改。命令自带 --help：dms:setconfig [options]，仅这两个业务选项。

3.4 替代配置文件 --config 与环境变量 SEEDDMS_CONFIG_FILE

传统 CLI 工具支持 --config <file> 指定另一份 settings.xml（实测用一份指向不存在库的替代配置跑 dbcheck，连接目标即切换、如实报错）：

$ /var/www/seeddms60x/seeddms/utils/seeddms-dbcheck --config=/tmp/alt-settings.xml
Could not connect to db-server "localhost"$

环境变量 SEEDDMS_CONFIG_FILE 同样被传统工具识别（未设置时 expireddocs 直接提示）：

You do not seem to have a valid configuration. Set SEEDDMS_CONFIG_FILE to the path of the configuration file.

⚠️ 注意：Symfony console（dms:* 命令族）不识别 SEEDDMS_CONFIG_FILE 环境变量——实测将环境变量指向一份坏库的替代配置后 dms:stats 仍正常读出主库数据（docs 3），即仍读默认 conf/settings.xml。多实例并行时传统工具用 --config 区分，console 命令需先切换默认配置。

四、参数总览

4.1 结构树

settings.xml 根节点 <configuration> 下三大域加扩展域（实测结构）：

域	子节点	管什么
`<site>`	display / edition / calendar / webdav / extensionmgr	界面展示、编辑行为、日历、WebDAV、扩展管理
`<system>`	server / authentication(+connectors) / database / smtp	路径与运行、认证策略与 LDAP/AD 连接器、数据库、邮件
`<advanced>`	display / authentication / edition / server / notification / converters×2	高级行为、API 密钥、工作流、核心路径、通知、全文/预览转换器
`<extensions>`	extension×N	已安装扩展及其参数

4.2 出厂关键默认值速查（实测值）

参数	节点	出厂值
siteName	site/display	`SeedDMS`
theme / language	site/display	`bootstrap4` / `en_GB`
enableFullSearch / fullSearchEngine	site/edition	`true` / `sqlitefts`
contentDir / cacheDir / backupDir	system/server	`/var/www/seeddms60x/data/` 下对应子目录
logFileEnable / logFileRotation	system/server	`true` / `d`（按天）
restricted	system/authentication	`true`（仅本地库用户可登录）
encryptionKey	system/authentication	32 位随机十六进制（安装时生成）
workflowMode	advanced/edition	`traditional`
contentOffsetDir	advanced/server	`1048576`
maxExecutionTime / cmdTimeout	advanced/server	`30` / `10` 秒
dbDriver	system/database	`mysql`

4.3 参数文档就在文件里

settings.xml 各节点上方有官方注释块逐属性说明（节选实测原文）：

<!--
   - enableGuestLogin: If you want anybody to login as guest, set the following line to true
   -                   note: guest login should be used only in a trusted environment
   - passwordStrength: minimum strength of password, set to 0 to disable
   - loginFailure: maximum allowed login failures before an account is disabled
   - quota: maximum allowed space on disc for each user
   - cookieLifetime: lifetime of cookie in seconds, set to 0 for session cookies
-->

改任何不确定的参数前先读对应注释块，这是官方随包文档。

五、核心参数分类详解

5.1 site/display：站点展示

实测出厂行：

<display siteName="SeedDMS" footNote="SeedDMS free document management system - www.seeddms.org"
  printDisclaimer="true" language="en_GB" theme="bootstrap4"
  previewWidthList="40" previewWidthDetail="100" onePageMode="true"
  maxItemsInDropFolderMenu="10" markdownComments="false" actiondropdown="false"/>

siteName/footNote：页面标题与页脚文案；
language：默认语言，en_GB 改 zh_CN 即中文界面（languages/ 下有对应目录）；
theme：bootstrap4（当前主线唯一现代主题）；
previewWidthList/previewWidthDetail：列表页/文档页预览图宽度（像素），调大增加渲染开销；
onePageMode：单页模式；markdownComments：批注是否按 Markdown 渲染。

5.2 site/edition：编辑与检索行为

关键实测值：strictFormCheck="false"、enableFullSearch="true"、fullSearchEngine="sqlitefts"、enableDropUpload="true"、enableFolderTree="true"、expandFolderTree="1"、enableClipboard="false"、enableRecursiveCount="false"、viewOnlineFileTypes=".txt;.text;.html;.htm;.xml;.pdf;.gif;.png;.jpg;.jpeg;.mp4"。

strictFormCheck：true 时表单所有字段必填（含关键词/备注），内网规范化归档建议开；
viewOnlineFileTypes：允许在线查看的扩展名白名单，只用小写（官方注释强调），新增可在线预览类型在此追加；
enableFullSearch：关闭后全文检索入口消失，元数据检索不受影响；
expandFolderTree：0 隐藏树 / 1 展开一层 / 2 全展开；
enableRecursiveCount + maxRecursiveCount：递归统计文件夹内文档数，柜体大时开销明显，默认关。

💡 技术拓展：fullSearchEngine 可选两种实现——

引擎存储特点
lucene luceneDir 多文件段 Zend Search 老实现，兼容历史索引
sqlitefts data/content.db 单文件 SQLite FTS5，PHP 原生 sqlite3 扩展支撑，当前默认

本环境实测采用 sqlitefts；切换引擎后必须 seeddms-indexer -c 全量重建，否则新引擎查不到旧索引内容。sqlitefts 以连字符为分词边界（实测 QUZUO-PROBE-20261102 需按 quzuoprobe2026 检索命中）。

引擎	存储	特点
lucene	`luceneDir` 多文件段	Zend Search 老实现，兼容历史索引
sqlitefts	`data/content.db` 单文件	SQLite FTS5，PHP 原生 sqlite3 扩展支撑，当前默认

5.3 system/server：路径与运行

实测出厂行（节选）：

<server rootDir="/var/www/seeddms60x/www/" httpRoot="/"
  contentDir="/var/www/seeddms60x/data/" stagingDir=".../data/staging/"
  luceneDir=".../data/lucene/" cacheDir=".../data/cache/" backupDir=".../data/backup/"
  logFileEnable="true" logFileRotation="d" logFileMaxLevel="6"
  enableLargeFileUpload="false" partitionSize="2000000" baseUrl="" .../>

rootDir/httpRoot/contentDir：安装向导三大必填项，分别对应代码目录、URL 相对路径、内容库；contentDir 官方注释明确要求不可被 Web 访问到；
stagingDir：分片上传暂存；luceneDir：lucene 引擎索引位（sqlitefts 时不用）；
logFileEnable/logFileRotation（h/d/m）/logFileMaxLevel（0=None…7=Debug，默认 6=Info）：应用日志开关与粒度，排障时临时调到 7；
baseUrl：站点基址。出厂空串时 CLI 场景产生 HTTP_HOST 相关警告噪音，建议安装后立即设置（3.3 实测命令）；
enableLargeFileUpload+partitionSize：jumploader 大文件分片上传，默认关；
enableMemcached：预览缓存可挂 memcached，默认关。

5.4 system/authentication：认证与安全

实测出厂行（节选）：

<authentication enableGuestLogin="false" enablePasswordForgotten="false" restricted="true"
  passwordStrength="0" passwordStrengthAlgorithm="simple" passwordExpiration="0"
  passwordHistory="0" loginFailure="0" quota="0"
  encryptionKey="b8c75fa53c0c7a18a84adb6ca815bd94" cookieLifetime="0"
  enable2FactorAuthentication="false" defaultAccessDocs="0">

restricted="true"：即使 LDAP 认证成功，也必须本地库有账号才放行（混合认证的安全闸）；
passwordStrength（0 关闭）/passwordExpiration/passwordHistory/loginFailure：密码策略四件套，生产建议 passwordStrength="2"、loginFailure="5"；
encryptionKey：表单 token 密钥，安装时随机生成；改动会使全部在线表单与登录态失效，属高危项；
cookieLifetime="0"：会话 cookie；改 86400 即「保持登录一天」；
quota：每用户空间配额（字节，0 不限）；
enable2FactorAuthentication：TOTP 双因子开关。

连接器（LDAP/AD）在子节点 <connectors> 声明，出厂为两条 enable="false" 模板：

<connector enable="false" type="ldap" host="ldaps://ldap.host.com" port="389"
  baseDN="" bindDN="" bindPw="" filter="" groupField=""/>
<connector enable="false" type="AD" host="ldap.example.com" port="389"
  baseDN="" accountDomainName="example.com" bindDN="" bindPw="" filter="" groupField=""/>

💡 技术拓展：SeedDMS 认证路线可选——

路线配置适用
本地库出厂默认独立小站
LDAP 连接器 type="ldap" + baseDN/filter 标准 OpenLDAP 目录
AD 连接器 type="AD" + accountDomainName 微软域，支持用户主名

连接器可多条并存，groupField 支持按目录组成员映射 SeedDMS 分组；本环境实测采用本地库路线。

路线	配置	适用
本地库	出厂默认	独立小站
LDAP 连接器	`type="ldap"` + baseDN/filter	标准 OpenLDAP 目录
AD 连接器	`type="AD"` + accountDomainName	微软域，支持用户主名

5.5 system/database：元数据库

<database dbDriver="mysql" dbHostname="localhost" dbDatabase="seeddms"
  dbUser="seeddms" dbPass="q1w2e3r4" doNotCheckVersion="false"/>

dbDriver 走 adodb，mysql（含 MariaDB）为主线，sqlite 可单机免装数据库服务；doNotCheckVersion 跳过模式版本校验，仅迁移排障时临时开。演示密码 q1w2e3r4 生产务必更换并同步此节点。

5.6 system/smtp：邮件通知

<smtp smtpServer="localhost" smtpPort="25" smtpSendFrom="seeddms@localhost"
  smtpUser="" smtpPassword="" smtpForceFrom="false" smtpLazySSL="false"/>

审阅/批准/到期提醒等通知依赖此节点；有认证中继时填 smtpUser/smtpPassword（生产密码建议用系统级密钥管理注入而非长期明文留存于该文件），smtpLazySSL 对 587 STARTTLS 中继开启。

5.7 advanced/server：核心路径与执行限制

<server coreDir="" luceneClassDir="" contentOffsetDir="1048576" maxDirID="0"
  updateNotifyTime="86400" maxExecutionTime="30" cmdTimeout="10"
  cmdFailOnStderr="false" cmdFailOnRetcode="false" enableDebugMode="false"/>

contentOffsetDir="1048576"：内容目录偏移基址，实测落盘路径 data/1048576/<docid>/<version>.<ext> 即由此而来，官方建议保持默认；
maxExecutionTime/cmdTimeout：脚本秒级上限与外部转换器命令超时（转换器超时是索引漏文档的常见根因）；
cmdFailOnStderr：开为 true 时外部命令有任何 stderr 输出即判失败——catdoc 对部分 doc 文件会打警告，默认关是对的。

5.8 advanced/edition：工作流与版本策略

实测关键值：workflowMode="traditional"、enableVersionDeletion="true"、enableVersionModification="true"、enableDuplicateDocNames="true"、enableAdminRevApp="false"、enableOwnerRevApp="false"、initialDocumentStatus="0"、advancedAcl="false"。

💡 技术拓展：workflowMode 两种模型——

模式机制适用
traditional 固定状态流：New→Under review→Approved/Rejected + 签收常规审批，开箱即用
advanced 自定义状态机（tblWorkflows/tblWorkflowStates/Transitions）复杂流程，需在后台建模

本环境实测为出厂 traditional；改 advanced 前需先在 Web 后台定义流程，否则文档无状态可流转。

模式	机制	适用
traditional	固定状态流：New→Under review→Approved/Rejected + 签收	常规审批，开箱即用
advanced	自定义状态机（tblWorkflows/tblWorkflowStates/Transitions）	复杂流程，需在后台建模

enableDuplicateDocNames 出厂 true（同柜允许重名文档），审计场景建议关；enableOwnerRevApp/enableSelfRevApp 控制「提交者自审自批」，合规归档应保持 false。

5.9 advanced/authentication：REST API 与访客

<authentication guestID="2" adminIP="" apiKey="" apiUserId="0" apiOrigin=""/>

guestID：访客登录映射的用户 id；
apiKey+apiUserId+apiOrigin：REST API 的免会话密钥三件套（配 apiOrigin 限定来源），与 cookie 会话认证二选一，用法实测见《SeedDMS 6.0.42 常用 CLI 命令与工具详解》的 REST API 节；
adminIP：限定管理员登录来源 IP（仅本地认证时生效）。

5.10 advanced/converters：全文抽取与预览管道

<converters target="fulltext">
  <converter mimeType="application/pdf">pdftotext -nopgbrk %s -</converter>
  <converter mimeType="application/msword">catdoc %s</converter>
  <converter mimeType="text/plain">cat %s</converter>
  <converter mimeType="application/vnd.openxmlformats-officedocument.wordprocessingml.document">docx2txt %s -</converter>
</converters>
<converters target="preview">
  <converter mimeType="image/png">convert -resize %wx '%f' '%o'</converter>
  ...
</converters>

占位符语义：%s/%f 源文件、%o 输出、%w 目标宽度。工具链安装与版本实测（pdftotext version 24.02.0、ImageMagick 6.9.12-98）见《Ubuntu 24.04 安装 SeedDMS 6.0.42 指南》 4.2 节。扫描件要进全文检索，可加 OCR 转换器（官方 README.ocr.md 路线）：

<converter mimeType="image/tiff">tesseract %s - -l chi_sim+eng 2>/dev/null</converter>

⚠️ 注意：转换器命令里 2>/dev/null 这类 stderr 抑制在 cmdFailOnStderr="true" 策略下才显重要；tesseract 未装时对应 MIME 文档静默不进索引，排查用 seeddms-indexer 输出的 error 计数。

5.11 extensions：扩展节点

实测 ext:list 回显：

$ php seeddms/utils/console ext:list
- example                                                 1.0.1    2018-03-21
  Example Extension
  Author: Uwe Steinmann (MMK GmbH)
- pdfviewer                                               1.0.1    2025-12-04
  Javascript PDF Viewer
  Author: Uwe Steinmann (MMK GmbH)

2 extensions, 0 enabled, 2 disabled, 0 has errors

<extensions> 节点按扩展名记录 disable 与 <parameter> 键值；ext:configure 命令或 Web 扩展页写回。site/extensionmgr 的 enableExtensionDownload/enableExtensionImport 控制扩展仓库在线安装开关。

六、生产配置模板

适用场景：8GB 内存、NVMe SSD、50 人内网合同/制度归档，域账号统一认证。在出厂值基础上改动如下（其余保持默认）：

<site>
  <display siteName="ACME 文档中心" language="zh_CN" theme="bootstrap4" footNote="内部系统，请遵守保密制度"/>
  <edition strictFormCheck="true" enableFullSearch="true" fullSearchEngine="sqlitefts"
    enableEmail="true" enableDropUpload="true" enableRecursiveCount="true" maxRecursiveCount="5000"/>
</site>
<system>
  <server ... logFileEnable="true" logFileRotation="d" logFileMaxLevel="6"
    baseUrl="https://dms.acme.internal" enableMemcached="true" memcachedHost="127.0.0.1"/>
  <authentication restricted="true" passwordStrength="2" passwordExpiration="180"
    passwordHistory="3" loginFailure="5" cookieLifetime="28800" quota="2147483648"
    enable2FactorAuthentication="true">
    <connectors>
      <connector enable="true" type="AD" host="ldap.acme.internal" port="636"
        baseDN="OU=Users,DC=acme,DC=internal" accountDomainName="acme.internal"
        bindDN="CN=seeddms-svc,OU=Service,DC=acme,DC=internal" bindPw="${AD_BIND_PW}"
        filter="(objectClass=user)" groupField="memberOf"/>
    </connectors>
  </authentication>
  <database dbDriver="mysql" dbHostname="127.0.0.1" dbDatabase="seeddms"
    dbUser="seeddms" dbPass="${SEEDDMS_DB_PW}"/>
  <smtp smtpServer="relay.acme.internal" smtpPort="587" smtpSendFrom="dms@acme.internal"
    smtpLazySSL="true"/>
</system>
<advanced>
  <edition workflowMode="traditional" enableDuplicateDocNames="false"
    enableVersionDeletion="false" enableOwnerRevApp="false"/>
  <server maxExecutionTime="120" cmdTimeout="60"/>
  <authentication adminIP="10.0.0.0/24" apiKey="${SEEDDMS_API_KEY}" apiUserId="1" apiOrigin="https://dms.acme.internal"/>
</advanced>

要点解说：

passwordStrength="2"+loginFailure="5"+2FA：账号安全基线；cookieLifetime="28800" 平衡体验与风险；
${AD_BIND_PW}/${SEEDDMS_DB_PW}/${SEEDDMS_API_KEY} 为系统级真实密钥占位，部署时用密钥管理注入（如 sed -i "s|\${SEEDDMS_DB_PW}|$DB_PW|" 渲染后落盘，settings.xml 权限 chmod 600、属主 www-data）；
enableVersionDeletion="false"+enableDuplicateDocNames="false"：审计合规两件套；
maxExecutionTime="120"/cmdTimeout="60"：给大 PDF 的 pdftotext/OCR 留余量；
备份：backupDir 配合 seeddms-xmldump + 数据库逻辑备份 + data/ 内容目录整树快照，三者同周期（详见《SeedDMS 6.0.42 常用 CLI 命令与工具详解》工具节）。

七、常见问题

Q1：CLI 跑命令时报 HTTP_HOST 相关 PHP 警告噪音？ baseUrl 出厂为空串所致。dms:setconfig --name=baseUrl --value="http://seeddms-server/" 设置后消失（3.3 实测）。

Q2：改了 fullSearchEngine 后检索全部失效？ 两种引擎索引互不相通，切换后必须全量重建：seeddms-indexer -c（重建模式，实测用法见《SeedDMS 6.0.42 常用 CLI 命令与工具详解》）。

Q3：修改 encryptionKey 后所有页面报表单校验失败？ 该 key 用于生成表单 token，改动使既有会话 token 全部失效；清 cookie 重新登录即恢复。非泄露场景不要动它。

Q4：带连字符的关键词全文检索不命中？ sqlitefts 分词以连字符为边界，索引 token 与原文不同形（实测 QUZUO-PROBE-20261102 按 quzuoprobe2026 命中）；属引擎行为，非配置错误。

Q5：settings.xml 改坏导致全站白屏怎么办？ 用 4.2 前置条件里的 .bak 覆盖回滚；若未备份，参照安装向导重新生成（rootDir/contentDir/database 三节点按 5.3/5.5 手工补齐即可恢复运行，数据无损）。

Q6：SEEDDMS_CONFIG_FILE 环境变量对 dms:* 命令没效果？ 已知行为：该变量只被传统工具族识别，Symfony console 恒读默认 conf/settings.xml（3.4 实测）。多配置场用 --config 或部署多套应用目录。

八、参考链接

官方站点与文档：https://www.seeddms.org（查询日期 2026-11-02）
参数权威出处：conf/settings.xml 内置注释块、quickstart 包 doc/ 目录
站内相关：《SeedDMS 6.0.42 介绍与选型指南》、《Ubuntu 24.04 安装 SeedDMS 6.0.42 指南》、《SeedDMS 6.0.42 常用 CLI 命令与工具详解》