Podman 部署 kkFileView 及 HTTPS 混合内容报错解决全记录

一、问题现象

部署 kkFileView 后，在浏览器中访问 https://zdocs.zhaopeng.site 预览文件时，控制台报错：

Mixed Content: The page at 'https://zdocs.zhaopeng.site/onlinePreview?url=...' 
was loaded over HTTPS, but requested an insecure frame 
'http://zdocs.zhaopeng.site/pdfjs/web/viewer.html?file=...'. 
This request has been blocked; the content must be served over HTTPS.

根本原因：kkFileView 生成的预览 iframe 链接为 HTTP 协议，但主页面通过 HTTPS 加载，浏览器出于安全策略拦截了混合内容。

二、环境信息

项目	信息
部署工具	Podman + Podman-Compose
kkFileView 镜像	docker.1ms.run/keking/kkfileview:latest
kkFileView 版本	4.1.0
反向代理	Caddy（自动 HTTPS）
域名	zdocs.zhaopeng.site
容器网络	znet（外部网络）

三、解决方案

方案一：通过环境变量强制 kkFileView 生成 HTTPS 链接（推荐）

kkFileView 4.1.0 支持通过环境变量 KK_BASE_URL 覆盖预览链接的基础地址。

1. 配置 docker-compose.yml

networks:
  znet:
    external: true

services:
  kkfile:
    container_name: kkfile
    environment:
      JAVA_OPTS: "-Xmx512m -Xms256m"
      KK_BASE_URL: "https://zdocs.zhaopeng.site"
      KK_FILE_DIR: "/data/file"
      TZ: "Asia/Shanghai"
    image: docker.1ms.run/keking/kkfileview:latest
    logging:
      driver: none
    networks:
      - znet
    restart: unless-stopped
    volumes:
      - ./datafile:/data/file

2. 关键配置说明

环境变量	作用	示例值
`KK_BASE_URL`	强制预览链接使用指定协议和域名	`https://zdocs.zhaopeng.site`
`JAVA_OPTS`	JVM 内存参数	`-Xmx512m -Xms256m`
`KK_FILE_DIR`	文件存储目录	`/data/file`

3. 启动命令

podman-compose down
podman-compose up -d

4. 验证环境变量是否生效

podman exec kkfile env | grep KK_BASE_URL

预期输出：

KK_BASE_URL=https://zdocs.zhaopeng.site

方案二：修改 application.properties 配置文件（备选）

如果环境变量方式不生效，可挂载修改后的配置文件。

1. 从容器中拷贝配置文件

注意确认实际版本号：

# 进入容器查看版本
podman exec -it kkfile /bin/bash
cd /opt/
ls
# 假设版本为 kkFileView-4.1.0

# 拷贝配置文件到宿主机
podman cp kkfile:/opt/kkFileView-4.1.0/config/application.properties ./application.properties

2. 修改配置文件

找到并修改 base.url 配置项：

# 原配置（注释状态）
# base.url = https://file.keking.cn

# 修改为
base.url = https://zdocs.zhaopeng.site

3. 挂载配置启动

services:
  kkfile:
    volumes:
      - ./application.properties:/opt/kkFileView-4.1.0/config/application.properties

四、Caddy 反向代理配置

Caddyfile 完整配置：

zdocs.zhaopeng.site {
    reverse_proxy kkfile:8012 {
        header_up X-Forwarded-Proto https
        header_up X-Forwarded-Host {host}
        header_up X-Forwarded-For {remote_host}
    }
}

关键点：X-Forwarded-Proto https 告诉后端当前请求来自 HTTPS，配合 KK_BASE_URL 确保生成的链接使用 HTTPS。

五、遇到的问题及解决

问题一：配置文件路径不存在

报错：

Error: "/opt/kkFileView-4.0.0/config/application.properties" could not be found

原因：版本号与实际不符。

解决：进入容器确认实际版本号：

podman exec -it kkfile /bin/bash
cd /opt/
ls
# 输出: kkFileView-4.1.0

问题二：环境变量值带有多余引号

报错：

index:206 Uncaught SyntaxError: Unexpected identifier 'https'

原因：docker-compose.yml 中环境变量写法错误：

# 错误写法（双层引号）
KK_BASE_URL: '"https://zdocs.zhaopeng.site"'

实际传给容器的值是 "https://zdocs.zhaopeng.site"（包含引号），导致 JavaScript 解析错误。

解决：去掉多余引号：

# 正确写法
KK_BASE_URL: "https://zdocs.zhaopeng.site"

YAML 引号规则说明：

写法	实际值	是否正确
`KK_BASE_URL: https://zdocs.zhaopeng.site`	`https://zdocs.zhaopeng.site`	正确
`KK_BASE_URL: "https://zdocs.zhaopeng.site"`	`https://zdocs.zhaopeng.site`	正确
`KK_BASE_URL: '"https://zdocs.zhaopeng.site"'`	`"https://zdocs.zhaopeng.site"`	错误

六、验证步骤

启动服务：

podman-compose up -d

查看容器状态：

podman ps

查看内存使用：

podman stats kkfile --no-stream

访问 https://zdocs.zhaopeng.site，上传并预览一个文档。
按 F12 打开开发者工具，查看 iframe 的 src 属性，应显示为 https://... 开头的链接。

七、关键知识点总结

知识点	说明
Mixed Content 拦截	HTTPS 页面不允许加载 HTTP 子资源，必须全站 HTTPS
kkFileView 预览链接生成	由 `base.url` 或 `KK_BASE_URL` 控制，不会自动识别请求头
反向代理需传递协议头	使用 `X-Forwarded-Proto: https` 告知后端实际协议
YAML 环境变量写法	值中的引号会成为实际值的一部分，需避免嵌套引号
kkFileView 4.1.0 配置优先级	环境变量 `KK_BASE_URL` > 配置文件 `base.url`

八、相关命令速查

# 查看容器环境变量
podman exec kkfile env | grep KK_

# 进入容器 Shell
podman exec -it kkfile /bin/bash

# 查看容器资源使用
podman stats kkfile

# 查看容器日志
podman logs kkfile

# 重启服务
podman-compose down && podman-compose up -d

# 验证配置文件语法
podman-compose config

Podman部署kkFileView