Alist配置kkFileView
Alist 配置 kkFileView 实现 Office 文件在线预览完整指南
一、环境概述
部署环境为 Podman，目前运行两个容器：
- Alist 容器（ID: 45f7b335f21b）
- kkFileView 容器（ID: 200d92888da0）
目标：通过 Alist 调用 kkFileView 实现 Office 文件（doc/docx/xls/xlsx/ppt/pptx）的在线预览。
二、kkFileView 首页测试代码说明
访问 kkFileView 首页（http://服务器IP:8012）时，页面通常会显示如下测试代码：
var url = 'http://127.0.0.1:8080/file/test.txt'; //要预览文件的访问地址
window.open('http://127.0.0.1:8012/onlinePreview?url='+encodeURIComponent(base64Encode(url)));该代码是 kkFileView 官方提供的功能测试示例，用于验证预览服务是否正常工作。测试时应将 url 变量的值替换为一个真实可访问的文件链接。
三、网络连通性关键点
3.1 容器网络特性
- Alist 和 kkFileView 均运行在 Podman 容器中
- 容器内部的
127.0.0.1指向容器自身，而非宿主机 - 因此 Alist 容器无法通过
127.0.0.1:8012访问 kkFileView
3.2 解决方案
在 Alist 后台配置预览地址时，应使用：
- 宿主机的局域网 IP 地址（例如
http://192.168.1.100:8012） - 或配置域名访问时使用域名地址
3.3 网络连通性测试方法
进入 Alist 容器内部测试与 kkFileView 的网络连通性：
# 进入 Alist 容器
podman exec -it 45f7b335f21b /bin/sh
# 测试网络连通性
wget -qO- http://宿主机局域网IP:8012
# 或使用 curl
curl http://宿主机局域网IP:8012- 执行成功：网络连通，检查 Alist 配置格式
- 超时或失败：容器网络不通，需要将两个容器置于同一 Podman 网络，或确保 kkFileView 端口正确映射（
-p 8012:8012）
四、Alist Iframe 预览配置
4.1 操作路径
登录 Alist 管理后台 → 设置 → 预览 → Iframe 预览
4.2 配置模板
在文本框中添加或修改 JSON 配置：
{
"doc,docx,xls,xlsx,ppt,pptx": {
"在线预览": "http://宿主机局域网IP:8012/onlinePreview?url=$eb_url"
}
}4.3 关键变量说明
Alist 提供以下变量用于动态替换文件地址：
| 变量 | 说明 |
|---|---|
$url | 文件的原始下载链接 |
$e_url | 对 $url 进行 encodeURIComponent 编码 |
$eb_url | 先对 $url 进行 Base64 编码，再用 encodeURIComponent 编码一次，即 encodeURIComponent(btoa($url)) |
对于 kkFileView，推荐使用 $eb_url，这是其标准参数格式要求。
五、关于 Alist 内置“飞书预览”配置的说明
5.1 配置内容
Alist 预览管理中默认存在一条配置：
内置
^Lark$5.2 ^Lark$ 的含义
- 这是一个正则表达式，用于匹配文件名
^表示开头，$表示结尾- 因此
^Lark$仅匹配文件名完全等于Lark（无任何后缀名）的文件
5.3 是否会连接外网
^Lark$ 配置本身不会导致 Alist 主动连接外网，原因如下：
- 它仅是一个文件名匹配规则，不是完整的网络请求地址
- 该配置更倾向于一个功能示例或占位符，展示如何接入第三方预览服务
- 只有在
^Lark$规则后面配置了真实的公网 URL 地址时，才会产生外网流量
5.4 该配置的实际用途
- 开发者留下的示例，展示可接入飞书、Google Docs、微软 Office Online 等第三方预览服务
- 演示如何使用正则表达式精确控制哪些文件使用特定预览服务
- 可作为配置模板，替换为自建 kkFileView 的内网地址
六、优化建议
6.1 反向代理配置
如果为 kkFileView 配置了反向代理（如 Nginx），需修改 kkFileView 容器内的 application.properties 配置文件，将 base.url 设置为代理访问地址，避免预览时内容显示异常。
6.2 预览性能调整
在 kkFileView 的配置文件中，可通过 office.preview.type 参数调整预览模式：
pdf：兼容性好image：速度可能更快
可根据实际需求选择。
6.3 安全与隐私
使用自建 kkFileView 并配置内网地址，文件仅在内网流转，不经过任何第三方公网服务，兼顾安全、速度和数据隐私。
七、配置流程总结
| 步骤 | 操作内容 |
|---|---|
| 1 | 确认 kkFileView 容器正常运行，访问 http://服务器IP:8012 验证 |
| 2 | 测试 Alist 容器与 kkFileView 容器的网络连通性 |
| 3 | 在 Alist 后台「设置 → 预览 → Iframe 预览」中添加 JSON 配置 |
| 4 | 配置中使用宿主机局域网 IP 或域名，而非 127.0.0.1 |
| 5 | 使用 $eb_url 变量传递文件地址给 kkFileView |
| 6 | 保存配置后，在文件列表中测试点击 Office 文件预览 |
| 7 | 根据实际使用情况调整 kkFileView 的预览模式和反向代理设置 |