Linux服务器从零部署kkFileView的完全指南

# ubuntu / debian
sudo apt update && sudo apt upgrade -y

# centos / rocky linux
sudo yum update -y
# 或者 rocky linux 8/9 用 dnf
sudo dnf update -y

# ubuntu
sudo apt install -y curl wget vim htop net-tools unzip

# centos
sudo yum install -y curl wget vim htop net-tools unzip

# ubuntu (ufw)
sudo ufw allow 22/tcp      # ssh
sudo ufw allow 80/tcp      # http
sudo ufw allow 443/tcp     # https
sudo ufw allow 8012/tcp    # kkfileview（如果不用 nginx 代理的话）
sudo ufw enable

# centos (firewalld)
sudo systemctl start firewalld
sudo systemctl enable firewalld
sudo firewall-cmd --zone=public --add-port=22/tcp --permanent
sudo firewall-cmd --zone=public --add-port=80/tcp --permanent
sudo firewall-cmd --zone=public --add-port=443/tcp --permanent
sudo firewall-cmd --zone=public --add-port=8012/tcp --permanent
sudo firewall-cmd --reload

sudo timedatectl set-timezone asia/shanghai

curl -fssl https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

curl -fssl https://get.docker.com | bash -s docker --mirror aliyun

# 卸载旧版本（如果有的话）
sudo apt remove -y docker docker-engine docker.io containerd runc

# 安装依赖
sudo apt install -y ca-certificates curl gnupg lsb-release

# 添加 docker 官方 gpg 密钥
sudo mkdir -p /etc/apt/keyrings
curl -fssl https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# 添加软件源
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 安装 docker engine
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# 卸载旧版本
sudo yum remove -y docker docker-client docker-client-latest docker-common \
    docker-latest docker-latest-logrotate docker-logrotate docker-engine

# 安装依赖
sudo yum install -y yum-utils

# 添加 docker 软件源
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

# 安装
sudo yum install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

sudo systemctl start docker
sudo systemctl enable docker

sudo mkdir -p /etc/docker

sudo tee /etc/docker/daemon.json <<-'eof'
{
  "registry-mirrors": [
    "https://docker.1ms.run",
    "https://docker.xuanyuan.me"
  ],
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "100m",
    "max-file": "3"
  },
  "storage-driver": "overlay2"
}
eof

sudo systemctl daemon-reload
sudo systemctl restart docker

sudo groupadd docker 2>/dev/null
sudo usermod -ag docker $user
newgrp docker

docker run hello-world

docker --version
docker compose version

# ubuntu
sudo apt install -y openjdk-8-jdk

# centos
sudo yum install -y java-1.8.0-openjdk-devel

# 验证
java -version

docker pull keking/kkfileview:4.1.0

# 也可以拉 latest
docker pull keking/kkfileview

# 在有网的机器上下载离线包
wget https://kkview.cn/resource/kkfileview-4.1.0-docker.tar

# 传到内网服务器后加载
docker load -i kkfileview-4.1.0-docker.tar

# 有网机器上导出
docker save -o kkfileview-4.1.0.tar keking/kkfileview:4.1.0

# 内网机器上导入
docker load -i kkfileview-4.1.0.tar

sudo mkdir -p /data/kkfileview/config
sudo mkdir -p /data/kkfileview/file
sudo mkdir -p /data/kkfileview/logs
sudo mkdir -p /data/kkfileview/fonts

# 启动一个临时容器
docker run -d --name kkfileview-temp keking/kkfileview:4.1.0

# 等几秒钟让容器完全启动，然后拷贝配置文件
docker cp kkfileview-temp:/opt/kkfileview-4.1.0/config/application.properties /data/kkfileview/config/

# 拷贝完成后删除临时容器
docker stop kkfileview-temp
docker rm kkfileview-temp

docker run -d \
  --name kkfileview \
  -p 8012:8012 \
  --restart=always \
  keking/kkfileview:4.1.0

docker run -d \
  --name kkfileview \
  -p 8012:8012 \
  -v /data/kkfileview/config/application.properties:/opt/kkfileview-4.1.0/config/application.properties \
  -v /data/kkfileview/file:/opt/kkfileview-4.1.0/file \
  -v /data/kkfileview/logs:/opt/kkfileview-4.1.0/log \
  -v /data/kkfileview/fonts:/usr/share/fonts/chinese \
  -e kk_jvm_options="-xms1g -xmx2g -xx:maxdirectmemorysize=1g" \
  --memory=4g \
  --memory-swap=4g \
  --restart=always \
  keking/kkfileview:4.1.0

# 查看容器状态
docker ps | grep kkfileview

# 查看启动日志
docker logs -f kkfileview

http://你的服务器ip:8012

mkdir -p /data/kkfileview && cd /data/kkfileview
vim docker-compose.yml

version: '3.8'
services:
  kkfileview:
    image: keking/kkfileview:4.1.0
    container_name: kkfileview
    restart: always
    ports:
      - "8012:8012"
    volumes:
      - ./config/application.properties:/opt/kkfileview-4.1.0/config/application.properties
      - ./file:/opt/kkfileview-4.1.0/file
      - ./logs:/opt/kkfileview-4.1.0/log
      - ./fonts:/usr/share/fonts/chinese
    environment:
      - kk_jvm_options=-xms1g -xmx2g -xx:maxdirectmemorysize=1g
    deploy:
      resources:
        limits:
          memory: 4g
        reservations:
          memory: 1g
    healthcheck:
      test: ["cmd", "curl", "-f", "http://localhost:8012"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s
    logging:
      driver: "json-file"
      options:
        max-size: "100m"
        max-file: "3"

# 启动（后台运行）
docker compose up -d

# 查看状态
docker compose ps

# 查看日志
docker compose logs -f kkfileview

# 停止
docker compose down

# 重启
docker compose restart

# 更新镜像后重新创建容器
docker compose pull
docker compose up -d

# 服务端口，默认 8012，一般不用改
server.port=8012

# 上下文路径，如果你要通过 nginx 代理到某个子路径下，需要改这里
# 默认是 /，如果 nginx 代理路径是 /preview，这里就改成 /preview
server.servlet.context-path=/

# 预览文件的存储路径，默认是程序根目录下的 file 目录
# 生产环境建议指向一个磁盘空间充裕的路径
file.dir=/opt/kkfileview-4.1.0/file

# 缓存过期时间（秒），默认 86400 即 24 小时
# 过期后再次预览会重新转换，如果文件很大转换会很慢
# 根据业务需要调整，设太长占磁盘，设太短影响体验
cache.expired.time=86400

# kkfileview 首页有一个演示上传功能
# 生产环境强烈建议关掉，避免被人当文件中转站
file.upload.disable=false

# 配置信任的主机，防止 ssrf 攻击
# 多个用英文逗号隔开
# 如果不配置，默认信任所有来源（不安全）
trust.host=your-domain.com,192.168.1.0/24

# libreoffice 安装路径（docker 镜像里一般已经配好了，不用动）
office.home=/opt/libreoffice7.1

# 预览服务端口（libreoffice 内部通信用的），默认 2002
office.port=2002

# 文档转换超时时间（毫秒），大文件可能需要调大
office.timeout=120000

docker restart kkfileview
# 或者用 compose
docker compose restart kkfileview

wget http://kkfileview.keking.cn/fonts.zip
unzip fonts.zip -d /data/kkfileview/fonts/

# 进入容器
docker exec -it kkfileview bash

# 安装字体工具（如果容器里没有的话）
apt-get update && apt-get install -y fontconfig

# 刷新字体缓存
fc-cache -fv

# 验证字体是否识别
fc-list | grep -i "sim"

# 退出容器
exit

docker restart kkfileview

# ubuntu
sudo apt install -y nginx

# centos
sudo yum install -y epel-release
sudo yum install -y nginx

# 启动并设置开机自启
sudo systemctl start nginx
sudo systemctl enable nginx

sudo vim /etc/nginx/conf.d/kkfileview.conf

upstream kkfileview_backend {
    server 127.0.0.1:8012;
    keepalive 32;
}

server {
    listen 80;
    server_name preview.yourdomain.com;

    # 如果需要自定义上下文路径，比如 /preview
    # location /preview {
    #     proxy_pass http://kkfileview_backend/;
    # }

    location / {
        proxy_pass http://kkfileview_backend;
        proxy_set_header host $host;
        proxy_set_header x-real-ip $remote_addr;
        proxy_set_header x-forwarded-for $proxy_add_x_forwarded_for;
        proxy_set_header x-forwarded-proto $scheme;

        # 文件预览可能比较大，超时时间设长一点
        proxy_connect_timeout 300s;
        proxy_send_timeout 300s;
        proxy_read_timeout 300s;

        # 大文件上传/转换需要
        client_max_body_size 200m;
    }
}

sudo nginx -t
sudo systemctl reload nginx

# http 强制跳转 https
server {
    listen 80;
    server_name preview.yourdomain.com;
    return 301 https://$server_name$request_uri;
}

# https 主配置
server {
    listen 443 ssl http2;
    server_name preview.yourdomain.com;

    ssl_certificate     /etc/nginx/ssl/yourdomain.com.pem;
    ssl_certificate_key /etc/nginx/ssl/yourdomain.com.key;
    ssl_protocols       tlsv1.2 tlsv1.3;
    ssl_ciphers         high:!anull:!md5;
    ssl_session_cache   shared:ssl:10m;
    ssl_session_timeout 10m;

    upstream kkfileview_backend {
        server 127.0.0.1:8012;
        keepalive 32;
    }

    location / {
        proxy_pass http://kkfileview_backend;
        proxy_set_header host $host;
        proxy_set_header x-real-ip $remote_addr;
        proxy_set_header x-forwarded-for $proxy_add_x_forwarded_for;
        proxy_set_header x-forwarded-proto https;

        proxy_connect_timeout 300s;
        proxy_send_timeout 300s;
        proxy_read_timeout 300s;

        client_max_body_size 200m;
    }
}

location /preview {
    proxy_pass http://127.0.0.1:8012/;
    proxy_set_header host $host;
    proxy_set_header x-real-ip $remote_addr;
    proxy_set_header x-forwarded-for $proxy_add_x_forwarded_for;
    proxy_set_header x-forwarded-proto $scheme;
}

server.servlet.context-path=/preview

docker run -d \
  -e kk_base_url="https://www.yourdomain.com/preview" \
  -e kk_context_path="/preview" \
  -e kk_trust_host="www.yourdomain.com" \
  -p 8012:8012 \
  keking/kkfileview:4.1.0

# application.properties
file.upload.disable=true

# 只允许来自这些域名的预览请求
trust.host=your-business-domain.com,another-domain.com

location / {
    # 只允许内网访问
    allow 10.0.0.0/8;
    allow 172.16.0.0/12;
    allow 192.168.0.0/16;
    deny all;

    proxy_pass http://kkfileview_backend;
    # ... 其他 proxy 配置
}

# 创建清理脚本
cat > /data/kkfileview/clean_cache.sh << 'eof'
#!/bin/bash
# 清理 7 天前的缓存文件
find /data/kkfileview/file -type f -mtime +7 -delete
echo "[$(date)] cache cleaned." >> /data/kkfileview/logs/clean.log
eof

chmod +x /data/kkfileview/clean_cache.sh

# 添加 crontab 定时任务，每天凌晨 3 点执行
(crontab -l 2>/dev/null; echo "0 3 * * * /data/kkfileview/clean_cache.sh") | crontab -

-e kk_jvm_options="-xms2g -xmx4g -xx:maxdirectmemorysize=1g -xx:+useg1gc"

# 转换任务超时时间（毫秒），大文件建议调大
office.timeout=300000

# 预览接口超时
server.tomcat.connection-timeout=300000

# 缓存 7 天
cache.expired.time=604800

from keking/kkfileview:4.1.0

# 安装字体工具
run apt-get update && apt-get install -y fontconfig && rm -rf /var/lib/apt/lists/*

# 拷贝中文字体
copy fonts/ /usr/share/fonts/chinese/

# 刷新字体缓存
run fc-cache -fv

# 拷贝自定义配置文件（如果需要覆盖默认配置）
# copy config/application.properties /opt/kkfileview-4.1.0/config/application.properties

expose 8012

cd /data/kkfileview
docker build -t my-kkfileview:4.1.0 .

docker run -d \
  --name kkfileview \
  -p 8012:8012 \
  -v /data/kkfileview/file:/opt/kkfileview-4.1.0/file \
  -v /data/kkfileview/logs:/opt/kkfileview-4.1.0/log \
  --restart=always \
  my-kkfileview:4.1.0

# 查看运行状态
docker ps -a | grep kkfileview

# 查看容器资源占用（cpu、内存实时数据）
docker stats kkfileview --no-stream

# 进入容器排查问题
docker exec -it kkfileview bash

# 重启
docker restart kkfileview

# 停止
docker stop kkfileview

# 启动已停止的容器
docker start kkfileview

# 删除容器（数据卷不受影响）
docker stop kkfileview && docker rm kkfileview

# 查看容器详细信息（ip、挂载、环境变量等）
docker inspect kkfileview

# 实时查看日志
docker logs -f kkfileview

# 查看最近 200 行
docker logs --tail 200 kkfileview

# 查看最近 1 小时的日志
docker logs --since 1h kkfileview

# 查看本地镜像
docker images | grep kkfileview

# 拉取新版本
docker pull keking/kkfileview:4.4.0

# 删除旧镜像
docker rmi keking/kkfileview:4.1.0

# 1. 停止并删除旧容器
docker stop kkfileview && docker rm kkfileview

# 2. 拉取新镜像
docker pull keking/kkfileview:4.4.0

# 3. 用新镜像重新启动（注意版本号对应的路径可能变了）
docker run -d \
  --name kkfileview \
  -p 8012:8012 \
  -v /data/kkfileview/config/application.properties:/opt/kkfileview-4.4.0/config/application.properties \
  -v /data/kkfileview/file:/opt/kkfileview-4.4.0/file \
  -v /data/kkfileview/fonts:/usr/share/fonts/chinese \
  --restart=always \
  keking/kkfileview:4.4.0

# 先看退出原因
docker ps -a | grep kkfileview    # 看 status 列
docker logs kkfileview            # 看报错信息

docker logs --tail 100 kkfileview

# 查看缓存目录大小
du -sh /data/kkfileview/file

# 手动清理
find /data/kkfileview/file -type f -mtime +3 -delete

http://你的服务器地址:8012/onlinepreview?url={base64编码的文件url}

ahr0chm6ly9vc3muew91cmrvbwfpbi5jb20vzmlszxmvy29udhjhy3quzg9jea==

http://preview.yourdomain.com/onlinepreview?url=ahr0chm6ly9vc3muew91cmrvbwfpbi5jb20vzmlszxmvy29udhjhy3quzg9jea==

// 假设你有一个文件的下载链接
const fileurl = 'https://oss.yourdomain.com/files/contract.docx';

// base64 编码
const encodedurl = btoa(fileurl);

// 拼接预览地址
const previewurl = `http://preview.yourdomain.com/onlinepreview?url=${encodeuricomponent(encodedurl)}`;

// 打开预览
window.open(previewurl);

import java.util.base64;
import java.net.urlencoder;

public class kkfileviewutil {
    
    private static final string kk_base_url = "http://preview.yourdomain.com";
    
    public static string getpreviewurl(string fileurl) {
        string encoded = base64.getencoder().encodetostring(fileurl.getbytes());
        return kk_base_url + "/onlinepreview?url=" + urlencoder.encode(encoded, "utf-8");
    }
}

#!/bin/bash
status=$(docker inspect --format='{{.state.health.status}}' kkfileview 2>/dev/null)
if [ "$status" != "healthy" ]; then
    echo "[$(date)] kkfileview 状态异常: $status" >> /data/kkfileview/logs/alert.log
    docker restart kkfileview
fi

# 检查 /data 分区使用率
usage=$(df -h /data | awk 'nr==2 {print $5}' | sed 's/%//')
if [ "$usage" -gt 85 ]; then
    echo "[$(date)] 磁盘使用率 ${usage}%，请及时清理缓存" >> /data/kkfileview/logs/alert.log
fi

#!/bin/bash
set -e

echo "=========================================="
echo "  kkfileview docker 一键部署脚本"
echo "=========================================="

# ---- 1. 安装 docker ----
if ! command -v docker &> /dev/null; then
    echo "[1/7] 安装 docker..."
    curl -fssl https://get.docker.com | sh
    systemctl start docker
    systemctl enable docker
    usermod -ag docker $user
    echo "docker 安装完成。注意：需要重新登录终端才能免 sudo 使用 docker。"
else
    echo "[1/7] docker 已安装，跳过。"
fi

# ---- 2. 创建目录结构 ----
echo "[2/7] 创建目录结构..."
mkdir -p /data/kkfileview/{config,file,logs,fonts}

# ---- 3. 下载字体包 ----
echo "[3/7] 下载中文字体包..."
if [ ! -f /data/kkfileview/fonts/simsun.ttc ]; then
    wget -q http://kkfileview.keking.cn/fonts.zip -o /tmp/fonts.zip
    unzip -o /tmp/fonts.zip -d /data/kkfileview/fonts/
    rm -f /tmp/fonts.zip
    echo "字体下载完成。"
else
    echo "字体已存在，跳过。"
fi

# ---- 4. 拉取镜像 ----
echo "[4/7] 拉取 kkfileview 镜像..."
docker pull keking/kkfileview:4.1.0

# ---- 5. 提取默认配置 ----
echo "[5/7] 提取默认配置文件..."
if [ ! -f /data/kkfileview/config/application.properties ]; then
    docker run -d --name kkfileview-temp keking/kkfileview:4.1.0
    sleep 10
    docker cp kkfileview-temp:/opt/kkfileview-4.1.0/config/application.properties \
        /data/kkfileview/config/application.properties
    docker stop kkfileview-temp && docker rm kkfileview-temp
    echo "配置文件已提取到 /data/kkfileview/config/"
else
    echo "配置文件已存在，跳过。"
fi

# ---- 6. 启动容器 ----
echo "[6/7] 启动 kkfileview 容器..."
docker run -d \
  --name kkfileview \
  -p 8012:8012 \
  -v /data/kkfileview/config/application.properties:/opt/kkfileview-4.1.0/config/application.properties \
  -v /data/kkfileview/file:/opt/kkfileview-4.1.0/file \
  -v /data/kkfileview/logs:/opt/kkfileview-4.1.0/log \
  -v /data/kkfileview/fonts:/usr/share/fonts/chinese \
  -e kk_jvm_options="-xms1g -xmx2g -xx:maxdirectmemorysize=1g" \
  --memory=4g \
  --restart=always \
  keking/kkfileview:4.1.0

# ---- 7. 刷新字体缓存 ----
echo "[7/7] 刷新容器内字体缓存..."
sleep 15
docker exec kkfileview fc-cache -fv > /dev/null 2>&1 || true
docker restart kkfileview

echo ""
echo "=========================================="
echo "  部署完成！"
echo "  访问地址: http://$(hostname -i | awk '{print $1}'):8012"
echo "  配置文件: /data/kkfileview/config/application.properties"
echo "  缓存目录: /data/kkfileview/file"
echo "  日志目录: /data/kkfileview/logs"
echo "=========================================="

chmod +x deploy_kkfileview.sh
sudo ./deploy_kkfileview.sh