Ubuntu 22.04 安装 Apache ManifoldCF 2.31 指南

在 Ubuntu 22.04 上从零安装 Apache ManifoldCF 2.31，涵盖 OpenJDK 25 前置、官方 binary 发行版下载校验、combined 单进程与多进程两种部署方案、systemd 托管、登录凭据修改、JVM 堆 512MB 配置及常见失败回显，命令与回显均实测

Apache ManifoldCFApache ManifoldCF2026/10/11

Ubuntu 22.04 安装 Apache ManifoldCF 2.31 指南

目标：在真实 Ubuntu 22.04 服务器上从零安装 Apache ManifoldCF 2.31（内容仓库连接框架，统一对接文件系统、Web、SharePoint、数据库等数据源并推送至 Solr/Elasticsearch 等输出），覆盖前置依赖、官方下载校验、两种部署形态、systemd 托管、验证与常见失败排障。以下命令与回显均在 Ubuntu 22.04 真实环境逐步实测。

一、环境信息

  • 操作系统：Ubuntu 22.04 LTS（x86_64，内核 6.8.0-138-generic）
  • Java：OpenJDK 25.0.4.1（openjdk-25-jdk-headless，ManifoldCF 2.31 强制要求）
  • Apache ManifoldCF：2.31（官方 binary 发行版 apache-manifoldcf-2.31-bin.tar.gz，444,303,809 字节）
  • 安装目录：/opt/manifoldcf-2.31
  • Web/管理端口：8345（Jetty）
  • 多进程形态 HSQLDB 服务端口：9001
  • 内嵌数据库：HSQLDB（单进程 combined 示例内嵌运行；多进程示例为 HSQLDB Server 独立进程）
  • 运行用户：root

💡 说明：ManifoldCF 官方 binary 发行版自带 Jetty 12.1.8 与 HSQLDB 2.6.1/2.7.3，不依赖外部 Tomcat 与外部数据库，开箱即用；生产环境也可切换 PostgreSQL。

二、前置条件

  • 一台 Ubuntu 22.04 服务器，root 权限。
  • 已安装 openjdk-25-jdk-headless（含 jps）、wget、tar、net-tools（含 netstat）、procps、unzip。
  • 可访问外网（或内网镜像源）以下载发行包与 apt 依赖。

安装基础依赖：

apt-get update -qq
DEBIAN_FRONTEND=noninteractive apt-get install -y -qq \
    openjdk-25-jdk-headless wget tar net-tools procps unzip

真实回显（节选）：

update-alternatives: using /usr/lib/jvm/java-25-openjdk-amd64/bin/serialver to provide /usr/bin/serialver (serialver) in auto mode
update-alternatives: using /usr/lib/jvm/java-25-openjdk-amd64/bin/jhsdb to provide /usr/bin/jhsdb (jhsdb) in auto mode

验证 Java 版本：

java -version

回显：

openjdk version "25.0.4.1" 2026-08-18
OpenJDK Runtime Environment (build 25.0.4.1+1-1-22.04.4-Ubuntu)
OpenJDK 64-Bit Server VM (build 25.0.4.1+1-1-22.04.4-Ubuntu, mixed mode, sharing)

⚠️ ManifoldCF 2.31 的 class 文件版本为 69.0（Java 25 编译），必须使用 OpenJDK 25 及以上版本，Java 11 会直接启动失败（见「十、常见问题」问题 1）。Ubuntu 22.04 官方源已提供 openjdk-25-jdk-headless，无需第三方源。

三、版本选型说明

Apache 官方发行目录（https://dlcdn.apache.org/manifoldcf/）当前提供的版本分支：

版本分支状态说明
apache-manifoldcf-1.101.x 老版本分支
apache-manifoldcf-2.23 ~ 2.302.x 历史稳定版
apache-manifoldcf-2.31最新稳定版（2026-07-30 发布），本篇实测版本

apache-manifoldcf-2.31/ 目录下提供的发行包：

包名用途
apache-manifoldcf-2.31-bin.tar.gz / .zipbinary 完整发行版（含 example、多进程示例、连接器、Web war）
apache-manifoldcf-2.31-lib.tar.gz / .zip仅依赖库（用于已有部署的库级集成）
apache-manifoldcf-2.31-src.tar.gz / .zip源码包（自行构建时使用）
各包对应 .asc / .sha512签名与校验文件
配套组件推荐版本说明
OpenJDK25class 文件版本 69.0，Java 25 编译运行
Jetty12.1.8binary 包内自带，无需单独安装
HSQLDB2.6.1 / 2.7.3binary 包内自带（示例默认数据库）
PostgreSQL42.7.10 驱动需要外部数据库时的可选切换

四、方案 A：官方 binary 发行版单进程安装（推荐）

单进程方式使用发行包自带的 example/ 目录：一个 JVM 同时运行爬虫 UI、authority service、API service 与 agents 调度线程，默认使用内嵌 HSQLDB，最适合单机安装与验证。

4.1 下载发行包与校验

优先使用国内镜像下载（速度明显优于官方源；官方 dlcdn 直连下载约 100KB/s）：

cd /opt
wget -O apache-manifoldcf-2.31-bin.tar.gz \
  https://mirrors.tuna.tsinghua.edu.cn/apache/manifoldcf/apache-manifoldcf-2.31/apache-manifoldcf-2.31-bin.tar.gz

下载完成后确认文件大小：

ls -la /opt/apache-manifoldcf-2.31-bin.tar.gz

回显：

-rw-r--r-- 1 root root 444303809 Jul 30 10:03 /opt/apache-manifoldcf-2.31-bin.tar.gz

下载官方 sha512 校验文件并核对（校验文件从 dlcdn 获取）：

wget https://dlcdn.apache.org/manifoldcf/apache-manifoldcf-2.31/apache-manifoldcf-2.31-bin.tar.gz.sha512
cat apache-manifoldcf-2.31-bin.tar.gz.sha512
sha512sum apache-manifoldcf-2.31-bin.tar.gz

回显：

apache-manifoldcf-2.31-bin.tar.gz: 6975EA2C 5243E485 21B2259E 3B17297B 93B49CB1
                                   EEAE0E87 24B3BAC6 1A2E1FEF E1038E47 5A3CDE19
                                   0925E883 FBF5172D 327CB7E4 295C30B4 C542958F
                                   ED260B28
6975ea2c5243e48521b2259e3b17297b93b49cb1eeae0e8724b3bac61a2e1fefe1038e475a3cde190925e883fbf5172d327cb7e4295c30b4c542958fed260b28  apache-manifoldcf-2.31-bin.tar.gz

两组值一致（忽略大小写与空格），校验通过。

⚠️ 清华镜像目录下未提供 .sha512 文件（实测 404），校验文件请从 dlcdn.apache.org 或 archive.apache.org 获取。

4.2 解压安装

cd /opt
tar xzf apache-manifoldcf-2.31-bin.tar.gz
mv apache-manifoldcf-2.31 manifoldcf-2.31
find /opt/manifoldcf-2.31 -name "*.sh" -exec chmod +x {} \;

查看目录结构：

ls /opt/manifoldcf-2.31/

回显：

DEPENDENCIES.txt
LICENSE.txt
NOTICE.txt
README.txt
connector-build.xml
connector-common-lib
connector-lib
connector-lib-proprietary
connectors.xml
doc
example
file-resources
lib
lib-proprietary
multiprocess-file-example
obfuscation-utility
plugins
script-engine
test-lib
web

关键目录说明：

目录用途
example/单进程（combined）示例：启动脚本、properties.xml、jetty.xml、内嵌 HSQLDB 数据
multiprocess-file-example/多进程示例：数据库、Web、agents 分进程启动（见方案 B）
web/war/mcf-crawler-ui.war、mcf-authority-service.war、mcf-api-service.war、mcf-combined-service.war
lib/核心 jar（mcf-core.jar、mcf-agents.jar 等 101 个）
connector-lib/各连接器 jar
script-engine/脚本引擎（可执行 .mcf 脚本）
obfuscation-utility/密码混淆工具
doc/各连接器 Javadoc

⚠️ binary 包内所有 .sh 脚本默认无执行权限，直接 ./xxx.sh 会报 Permission denied，必须先执行上述 chmod +x（见「十、常见问题」问题 2）。

4.3 修改管理登录凭据

发行包默认凭据为 admin/admin（UI 登录），API 登录默认空用户名/空密码。安装后应立即修改。编辑 /opt/manifoldcf-2.31/example/properties.xml，在文件末尾 <!-- Any additional properties go here --> 注释前插入：

  <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"/>

修改后核对：

grep -n "manifoldcf.login\|manifoldcf.apilogin" /opt/manifoldcf-2.31/example/properties.xml

回显：

47:  <property name="org.apache.manifoldcf.login.name" value="admin"/>
48:  <property name="org.apache.manifoldcf.login.password" value="q1w2e3r4"/>
49:  <property name="org.apache.manifoldcf.apilogin.name" value="admin"/>
50:  <property name="org.apache.manifoldcf.apilogin.password" value="q1w2e3r4"/>

💡 密码可用发行包自带的混淆工具处理后再写入（obfuscation-utility/obfuscate.sh，详见《Apache ManifoldCF 2.31 常用 CLI 命令与工具详解》）。

4.4 限制 JVM 堆内存

默认 JVM 参数位于 /opt/manifoldcf-2.31/example/combined-options.env.unix（启动脚本逐行读取该文件作为 java 参数），前两行为堆设置，默认已是 512MB：

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

单机内存紧张时可改为 256MB（直接编辑该文件前两行）：

-Xms256m
-Xmx256m

4.5 启动与停止

启动（前台运行，配合 nohup 转后台）：

export JAVA_HOME=/usr/lib/jvm/java-25-openjdk-amd64
cd /opt/manifoldcf-2.31/example
nohup bash start-combined.sh > /opt/mcf-start.log 2>&1 &

启动日志（/opt/mcf-start.log，节选）：

Configuration file successfully read
Starting jetty...
Configuration file successfully read
Successfully unregistered all domains
Successfully unregistered all output connectors
Successfully unregistered all transformation connectors
Successfully unregistered all mapping connectors
Successfully unregistered all authority connectors
Successfully unregistered all repository connectors
Successfully registered output connector 'org.apache.manifoldcf.agents.output.solr.SolrConnector'
Successfully registered repository connector 'org.apache.manifoldcf.crawler.connectors.alfrescowebscript.AlfrescoConnector'
Successfully registered notification connector 'org.apache.manifoldcf.crawler.notifications.email.EmailConnector'
Jetty started.

停止：

cd /opt/manifoldcf-2.31/example
bash stop-combined.sh

回显（无输出、退出码 0），随后确认端口关闭：

stop exit: 0
port 8345 closed

💡 stop-combined.sh 通过 Jetty ShutdownHandler 向 http://localhost:8345 发送停止令牌（令牌即 combined-options.env.unix 中的 org.apache.manifoldcf.jettyshutdowntoken），进程会在数秒内优雅退出。

4.6 验证

端口与进程验证：

netstat -tlnp | grep 8345
jps -v | grep -v Jps

回显：

tcp6       0      0 :::8345                 :::*                    LISTEN      4259/java
4259 ManifoldCFCombinedJettyRunner -Xms512m -Xmx512m -Dorg.apache.manifoldcf.configfile=./properties.xml -Dorg.apache.manifoldcf.jettyshutdowntoken=secret_token -Djava.security.auth.login.config= --enable-preview

jps -v 中可直接确认堆参数 -Xms512m -Xmx512m 已生效。

Web 访问验证（combined 模式所有 Web 应用统一部署在 /mcf 上下文）：

curl -s -o /dev/null -w "%{http_code} -> %{redirect_url}\n" http://localhost:8345/mcf/
curl -s http://localhost:8345/mcf/ | grep -o "<title>[^<]*</title>"

回显：

302 -> http://localhost:8345/mcf/login.jsp
<title>Apache ManifoldCF™ Login</title>

浏览器访问 http://<服务器IP>:8345/mcf/，使用 admin / q1w2e3r4 登录即进入爬虫管理界面。

登录行为实测（setupAdminProfile.jsp 为登录处理页）：

curl -s -c /tmp/cj -o /dev/null -w "%{http_code} -> %{redirect_url}\n" \
  -d "userID=admin&password=q1w2e3r4" http://localhost:8345/mcf/setupAdminProfile.jsp
curl -s -o /dev/null -w "%{http_code} -> %{redirect_url}\n" \
  -d "userID=admin&password=admin" http://localhost:8345/mcf/setupAdminProfile.jsp

回显：

302 -> http://localhost:8345/mcf/index.jsp
302 -> http://localhost:8345/mcf/login.jsp?loginfailed=true

新凭据登录成功（302 → index.jsp），旧默认凭据 admin/admin 已被拒绝（302 → loginfailed）。

日志文件：/opt/manifoldcf-2.31/example/logs/manifoldcf.log（由 example/logging.xml 定义，Root 级别 error）。

4.7 systemd 托管

创建 /etc/systemd/system/manifoldcf.service：

[Unit]
Description=Apache ManifoldCF 2.31 (combined example)
After=network.target

[Service]
Type=simple
User=root
Environment=JAVA_HOME=/usr/lib/jvm/java-25-openjdk-amd64
WorkingDirectory=/opt/manifoldcf-2.31/example
ExecStart=/opt/manifoldcf-2.31/example/start-combined.sh
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

启用并启动：

systemctl daemon-reload
systemctl enable manifoldcf
systemctl start manifoldcf
systemctl is-active manifoldcf

回显：

Created symlink /etc/systemd/system/multi-user.target.wants/manifoldcf.service → /etc/systemd/system/manifoldcf.service.
active

服务状态：

systemctl status manifoldcf --no-pager | head -9

回显：

● manifoldcf.service - Apache ManifoldCF 2.31 (combined example)
     Loaded: loaded (/etc/systemd/system/manifoldcf.service; enabled; vendor preset: enabled)
     Active: active (running) since Sun 2026-10-11 15:29:26 UTC; 30s ago
   Main PID: 13917 (start-combined.)
      Tasks: 63 (limit: 5753)
     Memory: 510.9M
        CPU: 17.247s

⚠️ systemd 单元中 WorkingDirectory 必须指向 example/ 目录：properties.xml、jetty.xml、内嵌 HSQLDB 数据文件均按相对路径读写，改工作目录会导致启动失败。

日志与重启验证：

journalctl -u manifoldcf --no-pager | grep -E "Started|Starting" | tail -2
systemctl restart manifoldcf
systemctl is-active manifoldcf
systemctl stop manifoldcf
systemctl is-active manifoldcf

回显：

Oct 11 15:29:26 70fbfb7e3e4b systemd[1]: Started Apache ManifoldCF 2.31 (combined example).
Oct 11 15:29:27 70fbfb7e3e4b start-combined.sh[13919]: Starting jetty...
active
inactive

💡 systemd stop 直接终止进程组（SIGTERM）；如需走 ManifoldCF 自身的优雅停止（等待抽取线程收尾），可先执行 bash stop-combined.sh 再等待 systemd 标记停止。

五、方案 B：多进程部署（multiprocess-file-example）

多进程形态将数据库（HSQLDB Server 独立进程）、Web（ManifoldCFJettyRunner）与 agents（AgentRun 调度进程）拆分为独立 JVM，便于分别调优与扩展，是生产部署的参考形态。目录：/opt/manifoldcf-2.31/multiprocess-file-example/。

⚠️ 执行顺序必须为：启动数据库 → 初始化 → 启动 Web → 启动 agents。未先启动数据库就执行 initialize.sh 会报 Socket 拒绝连接（见「十、常见问题」问题 3）。

5.1 启动数据库（HSQLDB Server）

export JAVA_HOME=/usr/lib/jvm/java-25-openjdk-amd64
cd /opt/manifoldcf-2.31/multiprocess-file-example
nohup bash start-database.sh > /opt/mcf-db.log 2>&1 &

确认启动：

tail -3 /opt/mcf-db.log
netstat -tlnp | grep 9001

回显：

[Server@55a561cf]: 2026-10-11 15:18:51.257 HSQLDB server 2.6.1 is online on port 9001
[Server@55a561cf]: To close normally, connect and execute SHUTDOWN SQL
[Server@55a561cf]: From command line, use [Ctrl]+[C] to abort abruptly
tcp6       0      0 :::9001                 :::*                    LISTEN      12036/java

5.2 初始化数据库并注册连接器

cd /opt/manifoldcf-2.31/multiprocess-file-example
bash initialize.sh

回显（尾部）：

Successfully registered notification connector 'org.apache.manifoldcf.crawler.notifications.slack.SlackConnector'
Successfully registered notification connector 'org.apache.manifoldcf.crawler.notifications.rocketchat.RocketChatConnector'
Successfully registered notification connector 'org.apache.manifoldcf.crawler.notifications.email.EmailConnector'
Successfully initialized database and registered all connectors

5.3 启动 Web 应用

nohup bash start-webapps.sh > /opt/mcf-web.log 2>&1 &

确认：

tail -1 /opt/mcf-web.log
netstat -tlnp | grep 8345

回显：

Jetty started.
tcp6       0      0 :::8345                 :::*                    LISTEN      12227/java

多进程形态下三个 Web 应用是独立上下文（与 combined 的 /mcf 不同）：

curl -s -o /dev/null -w "/mcf-crawler-ui/ -> %{http_code}\n" http://localhost:8345/mcf-crawler-ui/
curl -s -o /dev/null -w "/mcf-api-service/json/jobs -> %{http_code}\n" http://localhost:8345/mcf-api-service/json/jobs
curl -s -o /dev/null -w "/mcf-authority-service/ -> %{http_code}\n" http://localhost:8345/mcf-authority-service/

回显：

/mcf-crawler-ui/ -> 302
/mcf-api-service/json/jobs -> 200
/mcf-authority-service/ -> 200

5.4 启动 agents 调度进程

nohup bash start-agents.sh > /opt/mcf-agents.log 2>&1 &

确认：

tail -2 /opt/mcf-agents.log
jps -l

回显：

Running...
Configuration file successfully read
12227 org.apache.manifoldcf.jettyrunner.ManifoldCFJettyRunner
12036 org.hsqldb.Server
12294 org.apache.manifoldcf.agents.AgentRun

三个进程各自 JVM 参数（jps -v 实测）：

12576 AgentRun -Xms512m -Xmx512m -Dorg.apache.manifoldcf.configfile=./properties.xml ...
12227 ManifoldCFJettyRunner -Xms256m -Xmx256m -Dorg.apache.manifoldcf.configfile=./properties.xml ...
12036 Server -Xms256m -Xmx256m --enable-preview

agents 堆参数在 options.env.unix（-Xms512m/-Xmx512m），Web 堆参数在 jetty-options.env.unix（-Xms256m/-Xmx256m），数据库堆参数在 hsqldb-options.env.unix（-Xms256m/-Xmx256m），按需修改。

多进程形态的管理员凭据同样在 multiprocess-file-example/properties.xml 中修改（插入位置与 4.3 相同），修改后重启 Web 进程生效。

5.5 停止 agents 与清理

停止 agents（发送停止信号，进程优雅退出）：

bash stop-agents.sh

回显：

Configuration file successfully read
Shutdown signal sent

agents 日志尾部与进程确认：

Running...
Configuration file successfully read
Shutting down...

随后 jps -l 中 org.apache.manifoldcf.agents.AgentRun 消失。

清理锁与同步存储（agents 停止后执行）：

bash lock-clean.sh

回显：

Configuration file successfully read
Synchronization storage cleaned up

停止 Web 进程（使用 jetty 类路径执行 Shutdown 类）：

"$JAVA_HOME/bin/java" $(cat jetty-options.env.unix | tr "\n" " ") \
  org.apache.manifoldcf.jettyrunner.ManifoldCFJettyShutdown http://localhost:8345
echo "exit: $?"

回显：

exit: 0

⚠️ 不要用 agents 的 executecommand.sh 执行 Shutdown 类：agents 类路径（options.env.unix）不含 mcf-jetty-runner.jar，实测会报 ClassNotFoundException: org.apache.manifoldcf.jettyrunner.ManifoldCFJettyShutdown。

六、多方案对比与选择建议

维度方案 A：combined 单进程方案 B：multiprocess 多进程
进程数1 个 JVM（Web+agents 一体）3 个 JVM（HSQLDB Server / Web / agents）
数据库内嵌 HSQLDB（数据在 example/ 下）HSQLDB Server 模式（端口 9001，数据在 extdb）
Web 入口http://<IP>:8345/mcf/http://<IP>:8345/mcf-crawler-ui/
JVM 堆默认值512MB（combined-options.env.unix）Web 256MB / agents 512MB / DB 256MB（各 env 文件）
systemd 托管单单元即可（实测通过）需为每个进程分别建单元
适用场景单机安装、功能验证、小规模爬取生产部署、分进程调优、agents 独立伸缩
启停脚本start/stop-combined.shstart-database / initialize / start-webapps / start-agents / stop-agents

选择建议：单机快速上线选方案 A；需要分别控制 agents 与 Web 资源、或后续切换 PostgreSQL 的生产环境选方案 B。

七、配置说明

两种方案共用的核心配置文件为各目录下的 properties.xml，关键属性：

属性实测值说明
org.apache.manifoldcf.versionstring2.31UI 显示版本号
org.apache.manifoldcf.combinedwarpath../web/war/mcf-combined-service.warcombined 模式 war 路径
org.apache.manifoldcf.databaseimplementationclassorg.apache.manifoldcf.core.database.DBInterfaceHSQLDB数据库实现（可换 PostgreSQL 实现）
org.apache.manifoldcf.hsqldbdatabasepath.（example）内嵌 HSQLDB 数据目录
org.apache.manifoldcf.database.maxhandles100数据库连接句柄上限
org.apache.manifoldcf.crawler.threads50爬取线程上限
org.apache.manifoldcf.login.name / login.passwordadmin / q1w2e3r4（自改）UI 登录凭据（默认 admin/admin）
org.apache.manifoldcf.apilogin.name / apilogin.passwordadmin / q1w2e3r4（自改）API 登录凭据（默认空/空）
org.apache.manifoldcf.logconfigfile./logging.xml日志配置（logs/manifoldcf.log，Root=error）
org.apache.manifoldcf.connectorsconfigurationfile../connectors.xml连接器注册清单

完整参数说明见《Apache ManifoldCF 2.31 配置参数详解》。

八、注意事项

  • Java 版本必须 ≥ 25：2.31 class 文件版本 69.0，低版本 JVM 直接报 UnsupportedClassVersionError。
  • 首次安装必须 chmod +x 全部 .sh 脚本，发行包内脚本不带执行位。
  • 修改 properties.xml 后需重启对应进程方可生效（UI 登录凭据、数据库路径等均在启动时读取）。
  • combined 与多进程的 Web 路径不同（/mcf/ 与 /mcf-crawler-ui/），爬虫 UI 书签、反向代理规则不要混用。
  • stop-combined.sh/stop-agents.sh 走优雅停止；强杀进程后再次启动前建议执行 lock-clean.sh 清理同步存储。
  • 内嵌 HSQLDB 数据目录随 hsqldbdatabasepath 走，升级/迁移时连同该目录一起备份。

九、升级、降级与多版本管理

  • 升级：停止服务 → 备份旧版本目录与数据库路径（如 /opt/manifoldcf-2.31/example/ 下数据文件）→ 按第 4.1/4.2 步安装新版本目录（如 /opt/manifoldcf-2.32/）→ 将数据库路径指向原数据 → 启动（首次启动自动执行 schema 升级）。
  • 降级：不建议跨大版本降级；2.x 小版本间可备份数据后以旧版本程序指向原数据目录启动，若 schema 已升级需恢复备份。
  • 多版本并存：各版本解压为独立目录（如 /opt/manifoldcf-2.30、/opt/manifoldcf-2.31），不同端口运行（修改 jetty.xml 中的 8345），互不影响。

十、常见问题（FAQ）

Q1：启动报 UnsupportedClassVersionError？

现象（OpenJDK 11 实测）：

Error: LinkageError occurred while loading main class org.apache.manifoldcf.jettyrunner.ManifoldCFCombinedJettyRunner
        java.lang.UnsupportedClassVersionError: org/apache/manifoldcf/jettyrunner/ManifoldCFCombinedJettyRunner has been compiled by a more recent version of the Java Runtime (class file version 69.0), this version of the Java Runtime only recognizes class file versions up to 55.0

解决：安装 OpenJDK 25（apt-get install -y openjdk-25-jdk-headless）并确保 JAVA_HOME=/usr/lib/jvm/java-25-openjdk-amd64 后重新启动。

Q2：执行脚本报 Permission denied？

现象（实测）：

initialize.sh: line 21: ./executecommand.sh: Permission denied

原因：binary 包内 .sh 未带执行位。解决：

find /opt/manifoldcf-2.31 -name "*.sh" -exec chmod +x {} \;

Q3：initialize.sh 报 Socket 拒绝连接？

现象（实测栈尾）：

        at java.base/java.net.Socket.connect(Socket.java:659)
        at java.base/java.net.Socket.connect(Socket.java:597)
        at org.hsqldb.server.HsqlSocketFactory.createSocket(Unknown Source)

原因：未先执行 start-database.sh（HSQLDB Server 未在 9001 监听）。解决：按 5.1 → 5.2 顺序执行。

Q4：访问 http://<IP>:8345/mcf-crawler-ui/ 返回 404？

combined 模式下 Web 应用统一在 /mcf 上下文，/mcf-crawler-ui/ 只存在于多进程形态。实测：

# curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8345/mcf-crawler-ui/
404
# curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8345/mcf/
302

Q5：UI 登录页输入 admin/admin 提示登录失败？

发行包默认凭据为 admin/admin；若已按 4.3 改为 admin/q1w2e3r4，旧密码会 302 到 login.jsp?loginfailed=true（实测回显见 4.6）。使用新凭据登录即可；忘记凭据时重新检查 properties.xml 中 org.apache.manifoldcf.login.* 并重启。

Q6：API 调用返回 401？

API 登录凭据由 org.apache.manifoldcf.apilogin.name / org.apache.manifoldcf.apilogin.password 控制（默认空/空）。POST /mcf/api/json/LOGIN 提交与配置一致的凭据（实测 {"userID":"admin","password":"q1w2e3r4"} 返回 HTTP 200 {}），后续请求携带返回的会话 Cookie。

Q7：官方源下载极慢或中断？

dlcdn.apache.org 直连实测约 100KB/s 且易中断。改用清华镜像 mirrors.tuna.tsinghua.edu.cn/apache/manifoldcf/（实测 444MB 约 20 秒内完成），校验文件从 dlcdn 补取。

十一、卸载与清理

systemd 托管场景先停止并取消服务：

systemctl stop manifoldcf
systemctl disable manifoldcf

回显：

Removed "/etc/systemd/system/multi-user.target.wants/manifoldcf.service".

删除单元文件并重载：

rm -f /etc/systemd/system/manifoldcf.service
systemctl daemon-reload

删除程序与数据（多进程方案还需清理 extdb 数据目录）：

rm -rf /opt/manifoldcf-2.31
rm -f /opt/apache-manifoldcf-2.31-bin.tar.gz /opt/apache-manifoldcf-2.31-bin.tar.gz.sha512
rm -f /opt/mcf-start.log /opt/mcf-db.log /opt/mcf-web.log /opt/mcf-agents.log

如需卸载 Java（无其他组件使用时）：

apt-get purge -y openjdk-25-jdk-headless && apt-get autoremove -y

十二、参考链接