一、Docker 部署（最新版）
1.拉取官方镜像
docker pull keking/kkfileview:latest2.启动容器（推荐配置）
docker run -d \
--name kkfileview \
--restart always \
--privileged=true \
-p 8012:8012 \
-v /data/kkfileview/file:/opt/kkFileView/file \
-v /data/kkfileview/config:/opt/kkFileView/config \
-e KK_JVM_OPTS="-Xms512m -Xmx1024m" \
keking/kkfileview:latest3.验证部署
浏览器访问：http://你的服务器IP:8012，看到演示页面即部署成功。
二、前端接入（完整代码）
1.纯原生 JS（无依赖，可直接在控制台运行）
// ===== 配置区（修改为你的实际地址）=====
const kkHost = "http://172.18.10.31:8012"; // kkFileView服务地址
const fileUrl = "http://172.18.10.31/IqcBill/09fe838d04354b4f814473a8e1692e62/13_001.png";
// ===== Base64编码函数（浏览器原生实现）=====
function base64Encode(str) {
return btoa(encodeURIComponent(str).replace(/%([0-9A-F]{2})/g, (match, p1) => {
return String.fromCharCode('0x' + p1);
}));
}
// ===== 生成预览地址并打开=====
const base64Str = base64Encode(fileUrl);
const finalUrl = `${kkHost}/onlinePreview?url=${encodeURIComponent(base64Str)}`;
console.log("预览地址：", finalUrl);
window.open(finalUrl);2.标准 HTML 页面（引入官方库）
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>kkFileView 预览测试</title>
<!-- 引入官方js-base64库 -->
<script src="https://cdn.jsdelivr.net/npm/js-base64@3.6.0/base64.min.js"></script>
</head>
<body>
<button onclick="previewFile()">点击预览图片</button>
<script>
// 配置信息
const kkHost = "http://172.18.10.31:8012";
const fileUrl = "http://172.18.10.31/IqcBill/09fe838d04354b4f814473a8e1692e62/13_001.png";
function previewFile() {
// 核心编码步骤：先Base64，再URL编码
const base64Str = Base64.encode(fileUrl);
const previewUrl = `${kkHost}/onlinePreview?url=${encodeURIComponent(base64Str)}`;
window.open(previewUrl);
}
</script>
</body>
</html>3.Vue 组件示例（Vue2/Vue3 通用）
<template>
<button @click="handlePreview">预览文件</button>
</template>
<script>
import { Base64 } from 'js-base64'; // 需先安装：npm install js-base64
export default {
methods: {
handlePreview() {
const kkHost = "http://172.18.10.31:8012";
const fileUrl = "http://172.18.10.31/IqcBill/09fe838d04354b4f814473a8e1692e62/13_001.png";
// 编码生成最终地址
const encodedUrl = encodeURIComponent(Base64.encode(fileUrl));
window.open(`${kkHost}/onlinePreview?url=${encodedUrl}`);
}
}
}
</script>三、直接可用的预览地址（你的示例文件）
四、常见问题与排查
Uncaught SyntaxError: missing ) after argument list
原因：JS 代码中 base64Encode 函数的参数（文件地址）未加引号，或 base64Encode 不是浏览器原生方法。
解决：使用上述笔记中的编码函数，或引入 js-base64 库。
2. 500 Whitelabel Error Page
原因 1：URL 参数错误，地址栏中直接写了 JS 代码（如 encodeURIComponent(base64Encode(...))），kkFileView 无法解析。
解决：必须先在前端完成编码，地址栏只能传编码后的字符串。
原因 2：kkFileView 容器无法访问文件地址。
进入容器测试文件地址连通性
docker exec -it kkfileview curl http://172.18.10.31/IqcBill/09fe838d04354b4f814473a8e1692e62/13_001.png
原因 3：文件地址不可访问（如权限不足、网络不通）。
排查：用浏览器直接打开文件地址，确认能正常加载。
3. 中文乱码 / 方框字
解决：挂载中文字体到容器，或修改配置文件指定字体路径。
五、常用运维命令
查看实时日志
docker logs -f kkfileview重启容器
docker restart kkfileview停止并删除容器
docker stop kkfileview && docker rm kkfileview更新镜像（重新拉取最新版并重建容器）
docker pull keking/kkfileview:latest
docker stop kkfileview && docker rm kkfileview