kkFileView 内网 ARM 服务器全链路部署：从「找不到 office」到全绿通关（超详细排障实录）

kkFileView 内网 ARM 服务器全链路部署：从「找不到 office」到全绿通关（超详细排障实录）

作者按：这篇文章记录了我把 kkFileView 4.2.0 部署到一台纯内网、鲲鹏 ARM（aarch64）、华为云 HCE 2.0 服务器上的全过程。中间踩了一个叫「依赖地狱」的大坑，前后换了四五种方案才爬出来。我会把每一步的思考、每一次失败的原因都讲清楚，争取让完全没接触过 Linux 部署的同学也能看懂、能照着做。

（文中所有 IP、主机名、路径均已脱敏，用 10.0.0.x、/opt/app/... 这类占位符表示。）

---

〇、写在前面：为什么这篇值得看

大多数 kkFileView 教程都是这么写你的：

# 三分钟部署，简单！
tar -zxf kkFileView-4.2.0.tar.gz
cd kkFileView-4.2.0/bin
./startup.sh

然后你就打开了浏览器，看到了熟悉的首页，心想"就这？"。

但你有没有想过：这些教程的服务器，要么是 x86、要么能上外网。 一旦你的场景变成------

• 服务器是国产 ARM 芯片（鲲鹏、飞腾，信创环境一大把）；
• 服务器连不上外网（政企内网常态）；
• 系统是个精简版国产发行版（HCE、欧拉、龙蜥......）；

那么"三分钟部署"会在第一步就给你甩一句冷冰冰的报错：

RuntimeException: 找不到office组件，请确认'office.home'配置是否有误

然后陷入无尽的"装库 → 报错 → 换版本 → 又报错"循环。我就是这样一路爬出来的。下面开始。

---

一、先建立正确认知：kkFileView 到底靠什么干活

很多人（包括当年的我）以为 kkFileView 是个"纯 Java 应用"，打个 jar 就能跑。这是最大的误解，也是所有坑的根源。

真实架构是两段式：

┌────────────────────────────┐        ┌──────────────────────────────┐
│  kkFileView（Java 服务）    │        │  LibreOffice（外部独立程序）  │
│  端口 8012                  │  调用   │  端口 2001 / 2002             │
│  ─────────────────────────  │ ─────> │  ─────────────────────────── │
│  · 网页/PDF/图片/视频/压缩包 │        │  · Word/Excel/PPT → PDF/图片  │
│  · CAD（jar 内置 aspose）   │        │  · wps/odt/visio 等办公格式   │
│  · 上传、缓存、权限、页面    │        │  · 字体渲染、分页、排版还原   │
└────────────────────────────┘        └──────────────────────────────┘
        你打的 jar 包只管这半边              这半边不在 jar 里！

一句话 ：Word/Excel/PPT 的格式解析是个几十年历史的巨型 C++ 工程（.doc 二进制流、排版引擎、字体度量），Java 生态里没有任何库能完整还原，所以 kkFileView 走的是业界通用路线------把办公文档丢给本机的 LibreOffice 进程去转换。

这就带来一个铁律：

jar 包里不含 LibreOffice。你的服务器上必须单独装一个能跑的 LibreOffice，否则 Office 文档一律转不了。

理解了这一点，后面所有的报错和折腾，你都能明白"它在急什么"。

补充一个打包小知识（用 jar -tf / unzip -l 可以亲眼验证）：

产物	里面有没有 LibreOffice	说明
kkFileView-4.2.0.jar（fat jar）	❌ 一个文件都没有	只装了 Java 代码和依赖
kkFileView-4.2.0.zip（Windows 发行包）	✅ 整个 libreoffice/ 目录	便携版，但只能在 Windows 用
kkFileView-4.2.0.tar.gz（Linux 发行包）	❌ 不含	Linux 上要你自己装系统级 LibreOffice

看到没？Windows 发行包贴心地带了便携版 LibreOffice，所以你在 Windows 上双击 startup.bat 就能跑。但那个便携版是 Windows 的 .exe/.dll，在 Linux 服务器上完全不可用。 这就是为什么换到 Linux，就得自己面对"装 LibreOffice"这件事。

---

二、我的战场环境（务必对号入座）

项目	我的值	意味着什么
CPU 架构	aarch64（鲲鹏 ARM）	所有下载的包必须是 ARM 版，x86 包直接作废
操作系统	Huawei Cloud EulerOS 2.0（HCE 2.0）	HCE 基于 openEuler，glibc 版本是命门
系统 glibc	2.34	⭐ 全文最关键的数字，决定你能装哪些库
系统 libstdc++	最高 GLIBCXX_3.4.28（gcc 10.3）	LibreOffice 25.8 要 3.4.29，不够！
网络	纯内网，无外网	不能 yum install、不能自动下载，一切靠手动传包
JDK	1.8.0_422	kkFileView 按 JDK8 编译，正常
应用路径	/opt/app/kkFileView-4.2.0/	下文统一用这个占位

请把 glibc 2.34 这个数字刻在脑门上，第三幕它会是绝对主角。

---

三、第一幕：应用包就位，但服务拒绝启动

把 tar.gz 传上服务器，解压：

cd /opt/app/kkFileView-4.2.0
tar -zxf kkFileView-4.2.0.tar.gz
cd kkFileView-4.2.0/bin
chmod +x *.sh

目录结构长这样（bin / config / lib / log）：

kkFileView-4.2.0/
├── bin/        startup.sh  shutdown.sh  showlog.sh  install.sh  kkFileView.pid
├── config/     application.properties   ← 主配置
├── lib/        kkFileView-4.2.0.jar     ← 你的 fat jar
└── log/        kkFileView.log           ← 日志在这

启动脚本 startup.sh 很聪明，它会自动在一大堆标准路径里找 LibreOffice （/opt/libreoffice7.3、/usr/lib/libreoffice ...），找不到还会尝试跑 install.sh 联网下载。可惜我们是纯内网，联网安装注定失败。

先起一把看看（./startup.sh），然后 tail -f ../log/kkFileView.log，果然：

Error creating bean with name 'officePluginManager':
  ... java.lang.RuntimeException: 找不到office组件，请确认'office.home'配置是否有误

定位 ：这个 officePluginManager Bean 在初始化时会去探测 LibreOffice，探测不到就直接抛异常，导致整个 Spring 启动失败、端口不监听。翻译成人话："你没给我装 LibreOffice，我不伺候了。"

顺带一个坑：这版代码启动失败后 JVM 里有个非守护线程没退干净，会留下一个"僵尸" java 进程（ps 能查到，但不监听任何端口）。重启服务前务必先 kill -9 清干净，否则端口和进程状态会把你绕晕。

第一幕结论：应用没问题，就差 LibreOffice 本体。

---

四、第二幕：纯内网 + ARM，怎么把 LibreOffice 装上？

x86 的朋友在这步大多很轻松（yum install libreoffice 或下个 rpm 装）。但我们是 ARM + 无外网，两条路都被堵：

1. 系统 yum 源里的 LibreOffice 版本对 ARM 支持/字体效果参差不齐；
2. 我们干脆连 yum 源都访问不了。

于是选择最通用、最可控 的方案：从 LibreOffice 官网下 aarch64 的 DEB 离线包，传到服务器，用"解包法"手动铺开。

4.1 为什么是 DEB 包 + 解包法？

• LibreOffice 官方对 ARM64（aarch64）发布的是 .deb 格式的 tar 包（rpm 版反而没有 ARM 的）。
• 我们的 HCE 是 rpm 系（没有 dpkg），装不了 deb。
• 但 deb 本质是个 ar 归档 + tar 压缩，我们可以绕过包管理器，直接把里面的文件"倒"到系统目录里。这叫"解包安装法"，适合离线/跨发行版。

4.2 下载（在有外网的 Windows 上）

从清华镜像站下 ARM 版（官网直连慢，镜像快）：

https://mirrors.tuna.tsinghua.edu.cn/libreoffice/libreoffice/stable/25.8.7/deb/aarch64/LibreOffice_25.8.7_Linux_aarch64_deb.tar.gz

经验：LibreOffice 国内下载一律走清华等镜像站，官网 download.documentfoundation.org 在国内经常超时。

4.3 上传 + 解包安装（在服务器）

cd /opt/app/kkFileView-4.2.0
tar -zxf LibreOffice_25.8.7_Linux_aarch64_deb.tar.gz

解压出来的目录名带构建号，先进去确认实际名字 （别照抄别人的，差一个字符就 cd 失败，然后所有命令在错误目录里空跑------我就栽过）：

ls -d LibreOffice_*/          # 例如 LibreOffice_25.8.7.3_Linux_aarch64_deb/

进入里面的 DEBS 目录，把每个 .deb 拆开、内容铺到 /：

cd LibreOffice_25.8.7.3_Linux_aarch64_deb/DEBS

for d in *.deb; do
  ar x "$d"                                   # deb 是 ar 归档，先解开
  tar -xJf data.tar.xz -C / 2>/dev/null \
    || tar --zstd -xf data.tar.zst -C / 2>/dev/null \
    || tar -xf data.tar.gz -C /               # 真正的文件在 data.tar.* 里
  rm -f data.tar.* control.tar.* debian-binary
done

跑完，LibreOffice 会被铺到 /opt/libreoffice25.8/。建个软链，让各种探测路径都能命中：

ln -sfn /opt/libreoffice25.8 /opt/libreoffice
ls /opt/libreoffice25.8/program/soffice.bin && echo INSTALL-OK

看到 INSTALL-OK，别急着高兴------文件铺上了 ≠ 能跑起来。它只是一堆二进制，还得看系统库配不配套。

---

五、第三幕（高潮）：依赖地狱与「glibc 只向下兼容」的铁律

先别急着起 kkFileView，直接用 LibreOffice 自己做个体检，这是最聪明的排障顺序------把"引擎本身"和"Java 调用"两个变量分开：

/opt/libreoffice25.8/program/soffice.bin --headless --norestore --version

结果它啪地给你甩一堆：

error while loading shared libraries: libssl3.so: cannot open shared object file

再用 ldd 把缺的库一次性列全：

ldd /opt/libreoffice25.8/program/soffice.bin | grep 'not found'

我的机器上暴露出两类问题：

# 类型一：系统带的安全/加密库缺失（NSS 全家桶）
libssl3.so => not found
libsmime3.so => not found
libnss3.so => not found
libnssutil3.so => not found
libplds4.so => not found
libplc4.so => not found
libnspr4.so => not found

# 类型二：C++ 运行库版本太老，缺少新符号
/usr/lib64/libstdc++.so.6: version `GLIBCXX_3.4.29' not found
/usr/lib64/libstdc++.so.6: version `CXXABI_1.3.13' not found

5.1 讲透原理：为什么"版本对不上"会致命

这是全文最该被小白看懂的一段。

libstdc++.so.6 是 C++ 程序的"运行时地基"。它内部用一组符号版本号 （GLIBCXX_3.4.28、GLIBCXX_3.4.29......）来标记"我这个版本支持哪些新特性"。编译器版本越新，产出的程序要求的符号版本号就越高。

• LibreOffice 25.8 是用**新 gcc（11+）**编译的，它的二进制里"点名"要 GLIBCXX_3.4.29；
• 我系统自带的 libstdc++ 是 gcc 10.3 时代的，最高只到 GLIBCXX_3.4.28；
• 28 < 29，点名点到系统没有的符号 → 加载失败 → 程序起不来。

同理还有 glibc（更底层的 C 库）。这里有一条必须记住的铁律：

🥇 glibc 只向下兼容，不向上兼容。

在"新 glibc 系统"上编译的程序，拿到"老 glibc 系统"上跑，会报 GLIBC_2.38 not found 直接死掉；反之则没事。

这条铁律，直接决定了我后面选包的生死。

5.2 排障哲学：私有部署，绝不碰系统库

有人会想："升级系统 libstdc++ 不就好了？" ------ 千万别。 系统库是牵一发动全身的，覆盖它可能把别的程序搞挂。

正确姿势叫私有部署 ：把需要的库文件只放进 LibreOffice 自己的目录 （/opt/libreoffice25.8/program/），让它加载时优先用自己的。

这靠的是 ELF 里的 $ORIGIN 运行路径 （rpath）：程序会先在自己所在目录 找依赖库。把对的 .so 丢进 program 目录，就实现了"精准投喂、互不干扰"。

5.3 类型一：补 NSS（踩坑：oe2403 太新，全崩）

正确姿势 ：找一个 glibc 2.34 基线发行的 NSS 包（和服务器同源，天然兼容）。

我第一次选的是 openEuler 24.03（oe2403） 的 NSS------结果 rpm -ivh 直接拒装：

错误：依赖检测失败：
  libc.so.6(GLIBC_2.38)(64bit) 被 nspr-4.35.0-3.oe2403 需要

为什么？ 因为 openEuler 24.03 的基线是 glibc 2.38 ，而我的服务器是 glibc 2.34 。2.38 > 2.34，按上面那条铁律，"更新的库"要"更新的 glibc"，我的老系统给不起。（这坑我专门记了笔记：HCE 2.0 千万别用 openEuler 24.03 的高版本 RPM。）

换对基线 ：改用 openEuler 22.03-LTS-SP4 的 NSS------它的基线正好是 glibc 2.34 ，和服务器严丝合缝。下载这几个包（认准 oe2203sp4 + aarch64）：

nss-3.72.0-9.oe2203sp4.aarch64.rpm
nss-util-3.72.0-9.oe2203sp4.aarch64.rpm
nspr-4.32.0-5.oe2203sp4.aarch64.rpm
nss-softokn-3.72.0-9.oe2203sp4.aarch64.rpm

踩坑提醒 1：从镜像站下 RPM，务必下完先 file *.rpm 验货！有好几次我下回来的文件是 empty（0 字节）或 HTML 错误页------因为内网镜像代理把某些路径给拦了/URL 拼错了，返回一个空文件你还以为下载成功。正常应显示 RPM v3.0 bin。

踩坑提醒 2：这些 deb/rpm 都不要真去 install ，我们只是"借"里面的 .so 文件，用 rpm2cpio 抽出来丢进 program 目录即可（还是那句：不动系统库）。

抽库命令：

mkdir -p /tmp/nssx && cd /tmp/nssx
for r in nspr nss-util nss-3 nss-softokn; do
  rpm2cpio /opt/app/kkFileView-4.2.0/tmp/${r}-*.aarch64.rpm | cpio -idmu
done
find /tmp/nssx -name '*.so*' -type f -exec cp -a {} /opt/libreoffice25.8/program/ \;

NSS 这批库文件名本身就带 .so 后缀，拷进去就能被直接加载，不用建软链。

5.4 类型二：补 libstdc++（连环踩坑三连，主角登场）

这个最折腾，我换了三四个方案才找对，逐个讲，全是价值：

❌ 方案一：CentOS 的 gcc-toolset-11-libstdc+±devel

想着"要新符号，装个带 gcc11 的 devel 包不就有 .so 了？" 结果解包后 find 只有一个 libstdc++.so，cat 一看：

/* GNU ld script ... */
INPUT ( /usr/lib64/libstdc++.so.6 -lstdc++_nonshared )

它是个 217 字节的链接脚本，指向系统的旧库！ 真相是：CentOS 的 gcc-toolset 只提供"编译器"，不提供"可再分配的新版运行库"。此路不通。

❌ 方案二：Fedora 35 的 libstdc++

（Fedora 35 也是 glibc 2.34 + gcc 11.3，理论上完美。）结果镜像站打不开------Fedora 35 已 EOL（停止维护），它的 aarch64 归档从主流镜像下架了，路径 404/403。

✅ 方案三：CentOS Stream 9 的 libstdc++（最终通关）

灵光一闪：CentOS Stream 9 的基线正好是 glibc 2.34 + gcc 11.5 ------glibc 和服务器一致（满足向下兼容铁律），gcc 够新（提供 GLIBCXX_3.4.29/CXXABI_1.3.13）。而且它在清华镜像上是活的、可达的。

在页面上按名字找到运行库包（约 706KB）：

https://mirrors.tuna.tsinghua.edu.cn/centos-stream/9-stream/BaseOS/aarch64/os/Packages/libstdc++-11.5.0-15.el9.aarch64.rpm

小技巧：镜像站的包列表页动辄几千行，浏览器 Ctrl+F 搜 libstdc++ 最快。注意 CentOS Stream 是扁平目录 （一个大 Packages/ 全列出来），和 Debian 那种按首字母分小目录不一样，别在 URL 后面自己加 /l/。

抽库 + 建软链：

mkdir -p /tmp/el9std && cd /tmp/el9std
rpm2cpio /opt/app/kkFileView-4.2.0/tmp/libstdc++-11.5.0-15.el9.aarch64.rpm | cpio -idmu

find /tmp/el9std -name 'libstdc++.so.6*'
# → /tmp/el9std/usr/lib64/libstdc++.so.6.0.29   ← 真身在这里（版本号 6.0.29）

cp -a /tmp/el9std/usr/lib64/libstdc++.so.6.0.29 /opt/libreoffice25.8/program/
cd /opt/libreoffice25.8/program && ln -sf libstdc++.so.6.0.29 libstdc++.so.6

5.5 见证奇迹：LibreOffice 终于能跑了

再跑一遍 ldd 终检：

ldd /opt/libreoffice25.8/program/soffice.bin | grep -E 'not found|GLIBCXX|CXXABI'

零输出！ 所有缺失的库和符号全补齐了。再敲：

/opt/libreoffice25.8/program/soffice.bin --headless --norestore --version

LibreOffice 25.8.7.3 30742500f2d3eb4366ac312fa33d3dcabdb3eba5

打印出版本号 = LibreOffice 本体在纯内网 ARM 上彻底活了。 长舒一口气。

---

六、第四幕：中文字体（不做这步，中文文档全是豆腐块）

LibreOffice 转换靠字体渲染。国产服务器普遍不预置中文字体，Word 里的中文会变成一个个"口"字方块。

我把 Windows 自带的字体拷了几个上传到服务器（宋体/黑体/楷体/仿宋/微软雅黑基本覆盖公文和办公场景），装法：

# 假设字体已传到 /opt/app/kkFileView-4.2.0/fonts
mkdir -p /usr/share/fonts/chinese
cp /opt/app/kkFileView-4.2.0/fonts/* /usr/share/fonts/chinese/
fc-cache -fv                       # 刷新字体缓存
fc-list :lang=zh | head -5         # 能列出"宋体/黑体/微软雅黑"即成功

需要哪几个字体文件（在 Windows C:\Windows\Fonts 下）：

simsun.ttc (宋体)   simhei.ttf (黑体)   simkai.ttf (楷体)
simfang.ttf (仿宋)  msyh.ttc / msyhbd.ttc (微软雅黑 常规/粗)

Linux 区分大小写，SimsunExtG.ttf 这种首字母大写的拷贝时用通配符 * 别手写错。

---

七、第五幕：起服务，一次全绿

先告诉 kkFileView 我们的 LibreOffice 装在哪（改配置，office.home 指到实际目录）：

sed -i 's|^office.home = .*|office.home = /opt/libreoffice25.8|' \
  /opt/app/kkFileView-4.2.0/kkFileView-4.2.0/config/application.properties

清残留、启动、看日志，一气呵成：

ps -ef | grep kkFileView | grep -v grep | awk '{print $2}' | xargs -r kill -9
cd /opt/app/kkFileView-4.2.0/kkFileView-4.2.0/bin
> kkFileView.pid
./startup.sh
sleep 40 && tail -n 40 ../log/kkFileView.log

日志里三个"全绿"信号：

Connected: 'socket,host=127.0.0.1,port=2001,tcpNoDelay=1'
Connected: 'socket,host=127.0.0.1,port=2002,tcpNoDelay=1'
kkFileView 服务启动完成，耗时:4.40s，演示页请访问: http://127.0.0.1:8012

端口确认：

ss -lntp | grep -E '8012|2001|2002'
curl -s -o /dev/null -w 'HTTP %{http_code}\n' http://127.0.0.1:8012/   # 期望 200

关于日志里那句 Office process died with exit code 81; restarting it ：看到"重启"别慌，这不是故障。是 jodconverter 首次初始化 profile 时第一个进程退出，守护线程立刻拉起第二个，随后两条端口都 Connected 成功了------自愈型重试，正常现象。

---

八、端到端测试 + 一个必知的编码规则

浏览器打开 http://<你的服务器IP>:8012/，上传一个 .docx，能渲染出预览页，即全链路通过。

这里附一个 kkFileView 的"暗知识"------它的预览链接 URL 是双重编码的：

/onlinePreview?url = urlencode( Base64( 文件真实http地址 ) )

即先把文件地址做 Base64 ，再做一次 URL 编码 。很多二次开发/集成方在这翻车（传进去的 url 解不出来）。原理是 OnlinePreviewController 收到请求后先 decodeUrl 反解，再交给预览工厂分发。理解了"Base64 + urlencode 双编码"，你就懂它的预览链路了。

---

九、加餐：上线自测时又撞到的两个坑

服务全绿后我开始真实文件自测，外加通过反向代理（https://外网IP:端口 → 内网 http://内网IP:8012）访问，结果又抓到两个坑，都属于"部署成功但不好用"的那类，非常实战。

9.1 坑一：文件名带空格，预览直接废掉

我把一个 PDF（文件名里带空格）放进 data 目录，按第八章的双编码规则拼好链接，结果预览页报：

该(pdf%3d)文件，系统暂不支持在线预览

眼尖吗？提取到的扩展名是 pdf%3d，不是 pdf ------解码链被打碎了。翻源码看 4.2.0 的解码过程（WebUtils.decodeBase64String）：

Base64Utils.decodeFromString(source.replaceAll(" ", "+").replaceAll("\n", ""))

即"容器先做一次 % 解码 → 空格还原成 + → Base64 解码"。当文件名带空格时，%20、Base64 里的 +、结尾的 = 三者在"双重编码 + 容器解一轮"的链子里互相打架，解出来的 URL 尾部残留 %3d，扩展名识别必然失败。把文件名里的空格去掉，同一个链接机制立刻正常。

结论与建议：交给 kkFileView 预览的文件，文件名不要带空格（中文没问题，空格是硬伤）。业务系统对接时在落盘环节做一次文件名 sanitize 是最省事的办法，别指望编码层兜底。

9.2 坑二：走反向代理后，图片加载不出来

docx 预览页出来了，但满屏裂图。F12 一看，图片请求的地址是 http://外网IP/xxx/0.jpg------既丢了端口，协议也掉回了 http 。这不是要你去开新端口，根源是 base.url 的自动拼接（BaseUrlFilter）：

baseUrl = request.getScheme() + "://" + request.getServerName() + ":" + request.getServerPort() + ...;

经过代理后，应用拿到的 Host/Port 是转发规则给你的内部值，外部真实端口没了，拼出来的资源地址自然全错（https 页面加载 http 资源还会被浏览器混合内容拦截）。

修复 ：配置文件里 base.url 默认值是 ${KK_BASE_URL:default}（即自动探测）。把它显式写成浏览器地址栏实际使用的完整前缀（协议 + 域名/IP + 端口，一个字符都别差），重启即好：

sed -i 's|^base.url *= *.*|base.url = https://外网IP:外网端口|' config/application.properties

配套三个要点：

• url= 参数里指向内网源文件（如 http://内网IP:8012/xxx.pdf）的部分不用改 ------那是服务端自己环回取文件用的，内网通就行；给浏览器用的一切资源前缀都由 base.url 控制。
• base.url 写死后就"单入口"了；多域名/多入口场景可让代理透传 X-Base-Url 头（BaseUrlFilter 源码第一优先级支持），灵活度换回来。
• 改完必须重启，配置类改动在这项目里一律是重启生效。

---

十、给同样在信创/内网环境折腾的你：速查清单

排障顺序（把变量拆开，从底往上验证）：

1. soffice.bin --version 能出版本号吗？------先保证引擎本体活。
2. ldd soffice.bin | grep 'not found' ------缺哪个库补哪个。
3. grep 'GLIBCXX|CXXABI' ------符号不够就补 libstdc++。
4. 引擎活了再起 kkFileView，看 2001/2002 是否 Connected。
5. 最后才测端到端上传预览。
6. 上过反向代理的，F12 检查图片/子资源请求的协议和端口是否与浏览器地址栏一致。

选包铁律（信创 ARM 离线）：

目标库	选它	别选它	原因
NSS 全家桶	openEuler 22.03-SP4	openEuler 24.03	24.03 是 glibc 2.38，老系统跑不动
libstdc++	CentOS Stream 9（gcc11.5/glibc2.34）	CentOS gcc-toolset / Fedora 35	toolset 无运行库；F35 已下架
通用判断	包的 glibc 基线 ≤ 服务器 glibc	包基线 > 服务器 glibc	glibc 只向下兼容

操作纪律：

• 下的每个包先 file *.rpm 验货（RPM v3.0 bin 才算成功，empty/ASCII text 都是坑）。
• 一律 rpm2cpio | cpio 抽库进 LibreOffice 目录，绝不 rpm -ivh 覆盖系统库。
• 别整段往终端粘多行脚本------Windows 换行符 \r 会让 bash 报 $'\r'；关键循环一条一条敲。
• 目录名带构建号（如 25.8.7.3），先 ls 确认再 cd。
• 预览文件名别带空格 （pdf%3d 事件，见 9.1）。
• 反向代理/端口映射场景，base.url 必须显式写成浏览器实际前缀，别靠自动探测（见 9.2）。

---

十一、结语

写到这里，从内网解压到外网代理预览，整条链路才算真正闭环。这次部署没有任何"高深"技术，难的是一环扣一环的环境错配：ARM 架构、离线网络、精简系统、新旧工具的 glibc 代差。真正的解药是两条最朴素的原则：

1. 把系统切成最小可验证的块（引擎 / 库 / Java 服务 / 前端，逐层点亮），而不是把整个服务起来后对着满屏堆栈发呆；
2. 看懂底层规则再选包------"glibc 只向下兼容""gcc 版本决定符号版本""$ORIGIN 优先加载"这三句话，一旦刻进脑子，选包就从"碰运气"变成了"精确制导"。

如果你也在信创/内网环境折腾 kkFileView，希望这篇能帮你少走点弯路。有问题评论区见。

---

（本文场景：kkFileView 4.2.0 + LibreOffice 25.8 + HCE 2.0 aarch64 + JDK 1.8，纯内网离线部署。所有 IP/主机名/密码等敏感信息已脱敏。）