kkfileview部署后，有些小伙伴觉得直接用ip+端口访问多少有点别扭，那么现在讲一下怎么使用域名访问

本教程基于宝塔面板的域名反代功能实现域名直接访问，如果你是直接在服务器手搓的运行环境，自行设置nginx反代即可

在此之前首先你得有一个域名，国内服务器需要备案域名，海外服务器可直接使用，域名自己去准备即可，这里就不多演示了

域名准备好后现在域名提供商去解析绑定到服务器，这个过程各大服务商操作方式差不多都一样，很简单的，就不演示了

域名解析完成后打开宝塔面板，在左侧菜单栏选择 网站→反向代理→添加反代

在这里填写域名以及反代的链接：默认是http://127.0.0.1:8012（127.0.0.1替换为服务器ip，端口如果改过填写正确端口号即可）

填写完成后确定即可

然后试试域名访问，如果没有问题的话是可以正常访问的

接下来讲讲配置SSL证书

点击刚刚创建的域名反代，依次点击SSL→免费证书→申请证书 （如果你有付费的长期证书可以在配置页面填写密钥(KEY)以及证书(PEM格式)）

这个免费证书申请没有什么要求，但是只有90天有效期，过期后重新申请即可

配置后启用证书，域名前加https即可生效

证书启用后会有一些问题，会导某些格式的文件预览出现了乱码以及空白或者直接无法预览，这是一个非常经典的问题。这通常不是因为程序本身有 Bug，而是因为 协议不一致 或 网络配置 导致的链路中断

以下是导致问题的核心原因：

---

1. 核心原因：协议不匹配 (Mixed Content)

当你通过 HTTPS 访问 kkFileView 的预览页面时，如果后端返回的资源地址（如图片、样式、JS 或转换后的文件流）仍然使用的是 http://，浏览器会出于安全考虑拦截这些请求。

2. 关键配置检查清单

A. 修改 application.properties 配置

你必须告诉 kkFileView 它现在运行在 HTTPS 环境下。

• 配置项： base.url
• 操作： 确保该参数包含了正确的协议头。Properties# 示例 base.url = https://your-domain.com/kkFileView/ 注意： 如果你使用了 Nginx 转发，这个地址应该是用户浏览器访问的外网地址。

B. Nginx 反向代理配置（最常见痛点）

如果 kkFileView 放在 Nginx 后面，Nginx 需要将 SSL 的状态传递给后端的 Java 程序。如果缺少必要的 Header，后端可能无法正确识别当前的请求协议。

在你的 Nginx location 块中，必须包含以下配置：

Nginx

proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

# 关键：告诉后端这是一个 HTTPS 请求
proxy_set_header X-Forwarded-Proto https; 

C. 预览链接的编码问题

开启 SSL 后，预览请求的 URL 也会变长。

• 问题： 如果你预览的源文件地址是 http 的，而预览插件是 https 的，某些浏览器会直接挂掉。
• 解决： 确保传给 previewUrl 的参数是经过 Base64 编码 的，避免特殊字符和协议头引起解析错误。

---

3. 常见报错现象与对策

现象	可能原因	解决方法
页面空白/控制台报错 Mixed Content	资源请求被浏览器拦截	检查 base.url 是否为 https
PDF 预览正常，Office 预览失败	转换引擎（LibreOffice）在内网通信失败	检查服务器 hosts，确保域名指向正确
验证码或静态资源 404	Nginx location 匹配路径不对	检查 proxy_pass 后的斜杠 / 是否一致
证书无效导致无法预览	使用了自签名证书	在服务器端信任该证书，或在浏览器中手动永久信任

---

4. 调试建议

1. 打开浏览器开发者工具 (F12)： 查看 Console 里的报错。如果是红色报错提示 Blocked loading mixed active content，那就是上述的 X-Forwarded-Proto 或 base.url 没配好。
2. 检查网络面板 (Network)： 查看那些失败的请求（Status 0 或 404），看它们的请求 URL 到底是 http 还是 https。

接下来解决这些问题

1. 修改宝塔反向代理配置

宝塔默认的反代配置比较通用，你需要手动添加几行关键指令，让 kkFileView 知道前端是 HTTPS 访问。

1. 进入宝塔面板，点击左侧 “网站”。
2. 找到你为 kkFileView 配置的域名，点击 “设置”。
3. 在左侧菜单中选择 “反向代理”，点击对应条目的 “配置文件”。
4. 在 proxy_set_header 相关的代码块中，确保包含以下内容（如果没有请手动补全）：

Nginx

# 关键：告诉后端当前的协议是 https
proxy_set_header X-Forwarded-Proto https;
proxy_set_header X-Forwarded-Port 443;

# 保持原有的配置
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

5. 点击 “保存”。

---

2. 修改 kkFileView 的配置文件

如果你在服务器是直接运行（通过 startup.sh 或 java -jar），你需要修改 config 目录下的 application.properties。

1. 找到你的 kkFileView 安装目录。
2. 打开 config/application.properties。
3. 定位到 base.url 这一行，将其修改为你的 HTTPS 完整域名：Properties# 必须以 https:// 开头，结尾通常要带 / base.url = https://你的域名/

1. 重启 kkFileView 服务（一定要重启，否则配置不生效）。

---

3. 常见避坑指南

• 浏览器缓存问题： 修改完配置后，建议开启浏览器的 无痕模式 测试。因为浏览器可能会缓存旧的 HTTP 静态资源路径。
• 控制台报错 404： 如果开启 HTTPS 后发现样式（CSS/JS）加载不出，且路径里还带着 http://，说明步骤 2 的 base.url 没生效或没改对。
• 前端调用方式： 在你的前端业务代码中，传给 kkFileView 的 url 参数建议使用 Base64 编码。
  • 错误示例： https://kk.com/preview?url=http://file.com/test.docx (容易被防火墙拦截)
  • 正确示例： https://kk.com/preview?url=base64编码后的字符串

4. 验证是否成功

打开预览页面，按 F12 进入开发者模式，看 Network (网络) 标签页：

• 检查加载的 JS 和 CSS 文件，它们的 Remote Address 应该是你的 HTTPS 地址。
• 检查响应头（Response Headers），看有没有出现协议冲突。

最后，测试文件预览，常见的办公格式都没有问题，我这里尝试了.dwg格式的图纸，也是正常预览了

接下来又测试在其他应用中调用也是非常的nice~

完美解决https协议下文件显示不正常的问题！