Apache ManifoldCF 2.31 配置参数详解

目标：以官方 binary 发行版的单进程示例为基础，逐项解析 Apache ManifoldCF 2.31 的全部配置载体——properties.xml、jetty.xml、logging.xml 与 JVM 参数文件，给出每个参数的实测值、作用、生效方式与验证手段。所有改动均经过启动/重启与登录/API 实测。

一、环境信息

• 操作系统：Ubuntu 22.04 LTS（x86_64，内核 6.8.0-138-generic）
• Java：OpenJDK 25.0.4.1（openjdk-25-jdk-headless）
• Apache ManifoldCF：2.31，安装目录 /opt/manifoldcf-2.31
• 部署形态：单进程 combined（example/，一个 JVM 运行 UI + authority + API + agents）
• 端口：8345（Jetty，JettyShutdownHandler 同端口）
• 管理账号：admin / q1w2e3r4（自改，见 5.6）
• JVM 堆：512MB（combined-options.env.unix）

二、前置条件

已完成《Ubuntu 22.04 安装 Apache ManifoldCF 2.31 指南》的安装与启动，jps -v 可见 ManifoldCFCombinedJettyRunner 进程：

4259 ManifoldCFCombinedJettyRunner -Xms512m -Xmx512m -Dorg.apache.manifoldcf.configfile=./properties.xml -Dorg.apache.manifoldcf.jettyshutdowntoken=secret_token -Djava.security.auth.login.config= --enable-preview

ManifoldCF 2.31 的配置载体共四类：

三、参数查看与修改方式

properties.xml 中每行参数的查看：

grep -E "property name|libdir" /opt/manifoldcf-2.31/example/properties.xml

回显（节选，已含自加的登录凭据）：

  <property name="org.apache.manifoldcf.versionstring" value="2.31"/>
  <property name="org.apache.manifoldcf.crawleruiwarpath" value="../web/war/mcf-crawler-ui.war"/>
  <property name="org.apache.manifoldcf.authorityservicewarpath" value="../web/war/mcf-authority-service.war"/>
  <property name="org.apache.manifoldcf.apiservicewarpath" value="../web/war/mcf-api-service.war"/>
  <property name="org.apache.manifoldcf.usejettyparentclassloader" value="true"/>
  <property name="org.apache.manifoldcf.jettyconfigfile" value="./jetty.xml"/>
  <property name="org.apache.manifoldcf.combinedwarpath" value="../web/war/mcf-combined-service.war"/>
  <property name="org.apache.manifoldcf.databaseimplementationclass" value="org.apache.manifoldcf.core.database.DBInterfaceHSQLDB"/>
  <property name="org.apache.manifoldcf.hsqldbdatabasepath" value="."/>
  <property name="org.apache.manifoldcf.database.maxhandles" value="100"/>
  <property name="org.apache.manifoldcf.crawler.threads" value="50"/>
  <property name="org.apache.manifoldcf.crawler.historycleanupinterval" value="2592000000"/>
  <property name="org.apache.manifoldcf.logconfigfile" value="./logging.xml"/>
  <property name="org.apache.manifoldcf.connectorsconfigurationfile" value="../connectors.xml"/>
  <property name="org.apache.manifoldcf.fileresources" value="../file-resources"/>
  <libdir path="../connector-lib"/>
  <libdir path="../connector-common-lib"/>
  <libdir path="../connector-lib-proprietary"/>
  <property name="org.apache.manifoldcf.login.name" value="admin"/>
  <property name="org.apache.manifoldcf.login.password" value="q1w2e3r4"/>
  <property name="org.apache.manifoldcf.apilogin.name" value="admin"/>
  <property name="org.apache.manifoldcf.apilogin.password" value="q1w2e3r4"/>

生效方式：除 org.apache.manifoldcf.logconfigfile 指向的日志级别等少量运行时读取项外，绝大多数参数在进程启动时读取，修改后必须重启。systemd 部署时：

systemctl restart manifoldcf
systemctl is-active manifoldcf

回显：

active

⚠️ 相对路径全部以进程工作目录为基准：单进程示例的工作目录是 example/，因此 ./jetty.xml 指 example/jetty.xml、../web/war/... 指发行包 web/war/。systemd 单元中 WorkingDirectory 改错位置会导致配置文件读不到（回显 Configuration file successfully read 不再出现）。

四、properties.xml 参数总览

五、核心参数分类详解

5.1 版本与 Web 应用参数

• org.apache.manifoldcf.versionstring：UI 页面显示的版本字符串，实测值 2.31。仅展示用途，不影响功能。
• org.apache.manifoldcf.crawleruiwarpath / authorityservicewarpath / apiservicewarpath：三个 Web 应用的 war 路径，ManifoldCFJettyRunner（多进程 Web 进程）按此部署。修改 war 位置（如自定义构建的 UI）时同步修改。
• org.apache.manifoldcf.combinedwarpath：单进程 combined 模式使用的合并 war（UI + authority + API 打包一体），决定 combined 模式所有 Web 应用挂在 /mcf 上下文下——这就是 combined 模式访问 http://<IP>:8345/mcf/ 而多进程模式访问 /mcf-crawler-ui/ 的原因（combined 下访问 /mcf-crawler-ui/ 实测 404）。
• org.apache.manifoldcf.usejettyparentclassloader：War 类加载器是否使用 Jetty 父加载器。单进程示例为 true，多进程示例为 false，与两种形态的类路径差异匹配，无特殊需求不要互改。
• org.apache.manifoldcf.jettyconfigfile：指向 ./jetty.xml（见 5.7）。

5.2 数据库参数（HSQLDB）

单进程示例（内嵌模式，数据文件随工作目录）：

<property name="org.apache.manifoldcf.databaseimplementationclass" value="org.apache.manifoldcf.core.database.DBInterfaceHSQLDB"/>
<property name="org.apache.manifoldcf.hsqldbdatabasepath" value="."/>

• hsqldbdatabasepath="."：内嵌 HSQLDB 数据直接生成在 example/ 工作目录下，升级/迁移时需整体备份该目录。
• 多进程示例额外指定协议、地址与实例（HSQLDB Server 模式，独立进程监听 9001）：

<property name="org.apache.manifoldcf.hsqldbdatabaseprotocol" value="hsql"/>
<property name="org.apache.manifoldcf.hsqldbdatabaseserver" value="localhost"/>
<property name="org.apache.manifoldcf.hsqldbdatabaseinstance" value="xdb"/>
<property name="org.apache.manifoldcf.dbsuperusername" value="sa"/>
<property name="org.apache.manifoldcf.dbsuperuserpassword" value=""/>

（start-database.sh 以 -database.0 "file:extdb;..." -dbname.0 xdb 启动服务端，与以上参数对应。）

• org.apache.manifoldcf.database.maxhandles：数据库连接句柄上限，默认 100。爬取线程多、输出连接多时可上调；过小会在并发爬取时排队等待。
• 切换 PostgreSQL：将 databaseimplementationclass 换为 org.apache.manifoldcf.core.database.DBInterfacePostgreSQL 并补充分页、连接串相关属性（官方 how-to-build-and-deploy 文档第 PostgreSQL 节），不在本篇默认实测范围。

5.3 爬取引擎参数

• org.apache.manifoldcf.crawler.threads：全局爬取工作线程数上限，默认 50。实测 2.31 单进程 512MB 堆下以默认值完成 3714 个文档的文件系统爬取（作业 40 秒内跑完）。调大需同步评估堆与 database.maxhandles。
• org.apache.manifoldcf.crawler.historycleanupinterval：历史记录清理间隔（毫秒），默认 2592000000（30 天）。

5.4 日志参数

org.apache.manifoldcf.logconfigfile 指向 ./logging.xml，其中文件输出定义为相对路径：

fileName="logs/manifoldcf.log"

即日志落在 example/logs/manifoldcf.log。日志级别（Root）默认 error，排障时可临时调为 debug 并重启。实测日志中记录了 API 校验失败等异常：

org.apache.manifoldcf.core.interfaces.ManifoldCFException: Job 1791731450272 is not active
org.apache.manifoldcf.core.interfaces.ManifoldCFException: Job 1791731450272 is not paused

5.5 连接器注册参数

• org.apache.manifoldcf.connectorsconfigurationfile：指向 ../connectors.xml，其中逐行列出要加载的输出/转换/映射/权限/仓库/通知连接器实现类。启动日志的 Successfully registered ... connector 序列即按此文件注册（实测单进程启动注册全部内置连接器，日志共 70 行）。
• org.apache.manifoldcf.fileresources：连接器可写的资源目录。
• libdir：连接器 jar 搜索路径，发行包默认三项 ../connector-lib、../connector-common-lib、../connector-lib-proprietary；新增第三方连接器 jar 时放入目录即可，无需改此列表。

5.6 登录与安全参数

爬虫 UI 与 REST API 各有一组独立凭据：

修改后重启，实测验证（登录处理页 setupAdminProfile.jsp）：

admin/q1w2e3r4: HTTP 302 -> http://localhost:8345/mcf/index.jsp          ← 新凭据登录成功
admin/admin: HTTP 302 -> http://localhost:8345/mcf/login.jsp?loginfailed=true   ← 旧默认凭据被拒

API 侧（POST /mcf/api/json/LOGIN）：

{"userID":"admin","password":"q1w2e3r4"} → HTTP 200 {}

密码混淆写法（实测）：明文密码可改为混淆形式，使用发行包自带工具生成混淆串：

# cd /opt/manifoldcf-2.31/obfuscation-utility && bash obfuscate.sh q1w2e3r4
m/s6WoTCdVjAr7/FCSYBnv8o3zcVzVixwjGP/+rgAeA=

混淆串必须写入同名但带 .obfuscated 后缀的属性（反编译 ManifoldCFConfiguration.getPossiblyObfuscatedStringProperty 证实：先读 <name>.obfuscated 并解混淆，无则回退明文 <name>）：

  <property name="org.apache.manifoldcf.login.password.obfuscated" value="m/s6WoTCdVjAr7/FCSYBnv8o3zcVzVixwjGP/+rgAeA="/>

写入后重启，admin/q1w2e3r4 登录实测成功（302 → index.jsp）。⚠️ 两种错误写法均实测失败（登录跳转 loginfailed）：把裸混淆串直接写在原属性 org.apache.manifoldcf.login.password 上；或加 {Obfuscated} 前缀写在原属性上。

5.7 jetty.xml 与 JVM 参数文件

• example/jetty.xml 定义监听端口，实测片段：

      <Item>
        <New class="org.eclipse.jetty.server.ServerConnector">
          <Arg><Ref refid="server"/></Arg>
          <Set name="port">8345</Set>
        </New>
      </Item>

改端口即改此处 <Set name="port">，重启后用 netstat -tlnp | grep <新端口> 验证；停止脚本 stop-combined.sh 内的 http://localhost:8345 需同步修改，否则优雅停止失效。

• JVM 参数文件（启动脚本逐行读取，作为 java 命令参数）：

堆内存调整即编辑文件前两行（如 256MB 改为 -Xms256m、-Xmx256m 两行）。生效后验证：

# jps -v | grep -v Jps
4259 ManifoldCFCombinedJettyRunner -Xms512m -Xmx512m -Dorg.apache.manifoldcf.configfile=./properties.xml ...
12036 Server -Xms256m -Xmx256m --enable-preview

其中 -Dorg.apache.manifoldcf.jettyshutdowntoken=secret_token 为优雅停止令牌，生产环境建议修改，并同步更新停止脚本中携带的令牌。多进程方案中 properties.xml 的 org.apache.manifoldcf.synchdirectory 指向 ./syncharea，是各进程间锁与同步文件目录，多进程分离部署（不同主机）时需置于共享存储。

六、生产配置模板

单进程形态生产建议配置（在 example/properties.xml 基础上）：

  <!-- 版本展示 -->
  <property name="org.apache.manifoldcf.versionstring" value="2.31"/>
  <!-- 数据库：默认 HSQLDB 内嵌，数据路径显式指定到独立目录便于备份 -->
  <property name="org.apache.manifoldcf.hsqldbdatabasepath" value="/var/lib/manifoldcf"/>
  <property name="org.apache.manifoldcf.database.maxhandles" value="100"/>
  <!-- 爬取线程按负载调整 -->
  <property name="org.apache.manifoldcf.crawler.threads" value="50"/>
  <!-- 管理凭据（.obfuscated 写法示例，值由 obfuscate.sh 生成） -->
  <property name="org.apache.manifoldcf.login.name" value="admin"/>
  <property name="org.apache.manifoldcf.login.password.obfuscated" value="m/s6WoTCdVjAr7/FCSYBnv8o3zcVzVixwjGP/+rgAeA="/>
  <property name="org.apache.manifoldcf.apilogin.name" value="admin"/>
  <property name="org.apache.manifoldcf.apilogin.password" value="q1w2e3r4"/>

配套动作清单：

1. 数据路径改为独立目录（如 /var/lib/manifoldcf）并纳入备份。
2. 管理员/UI/API 凭据全部修改（或用 .obfuscated 混淆写法）。
3. jettyshutdowntoken 修改为随机值并同步停止脚本。
4. 堆按机器内存设定（512MB 起步，重负载爬取按 5.3 评估上调）。
5. 日志按需调整 logging.xml 级别与轮转。

七、参数修改流程与验证

以「修改爬取线程 50 → 30」为例的完整实测链路：

1. 编辑：sed -i 's|name="org.apache.manifoldcf.crawler.threads" value="50"|name="org.apache.manifoldcf.crawler.threads" value="30"|' /opt/manifoldcf-2.31/example/properties.xml
2. 核对：grep "crawler.threads" /opt/manifoldcf-2.31/example/properties.xml

  <property name="org.apache.manifoldcf.crawler.threads" value="30"/>

3. 重启：systemctl restart manifoldcf（或手动 bash stop-combined.sh && nohup bash start-combined.sh ...），等待日志再次出现 Jetty started.
4. 验证进程与端口：systemctl is-active manifoldcf → active；netstat -tlnp | grep 8345 → tcp6 0 0 :::8345 :::* LISTEN <pid>/java
5. 验证 Web：curl -s -o /dev/null -w "%{http_code} -> %{redirect_url}\n" http://localhost:8345/mcf/ → 302 -> http://localhost:8345/mcf/login.jsp

八、常见问题（FAQ）

Q1：修改了 properties.xml 但没生效？

参数在启动时读取，修改后必须重启对应进程（systemd restart 或 stop/start 脚本）。另外确认工作目录正确：systemd 部署时 WorkingDirectory 必须是 example/（多进程为 multiprocess-file-example/），否则读的是另一份相对路径文件。

Q2：修改管理密码后旧密码仍能登录？

确认重启过进程；并检查是否存在同名 .obfuscated 属性——它优先于明文属性（实测优先级见 5.6）。

Q3：混淆密码写在哪里？为什么按明文属性名写不生效？

混淆串写入 <属性名>.obfuscated（实测成功）；写回原属性名（无论裸串还是加 {Obfuscated} 前缀）实测均失败，登录跳转 login.jsp?loginfailed=true。

Q4：如何改端口？

example/jetty.xml 中 <Set name="port">8345</Set> 改为新端口，同步修改 stop-combined.sh 中的 http://localhost:8345，重启后 netstat 验证。

Q5：堆内存限制不生效？

确认改的是与启动形态匹配的 options 文件：combined 用 combined-options.env.unix；多进程 Web/agents/DB 分别用 jetty/options/hsqldb 三个文件。启动后用 jps -v 直接核对（回显见 5.7）。脚本引擎另有一份 script-engine/options.env.unix（默认仅 -Xms8m/-Xmx8m，跑示例脚本会 OOM，需自行调大）。

Q6：多进程与单进程可以共用一份配置吗？

不建议。两形态 properties.xml 存在实质差异（usejettyparentclassloader true/false、多进程多出 hsqldb protocol/server/instance 与 synchdirectory），混用会导致 HSQLDB 连接方式错乱（多进程示例报 Socket 拒绝连接的根因之一）。

九、参考链接

• 2.31 最终用户文档（含 properties 说明）：https://manifoldcf.apache.org/release/release-2.31/en_US/end-user-documentation.html
• 构建与部署文档（数据库切换等）：https://manifoldcf.apache.org/release/release-2.31/en_US/how-to-build-and-deploy.html
• Jetty 配置参考：https://jetty.org/docs/jetty12/
• HSQLDB 文档：http://hsqldb.org/doc/2.0/
• 项目主页：https://manifoldcf.apache.org/