给 kkFileView 接上人大金仓：备份链路一次跑通

给 kkFileView 接上人大金仓：备份链路一次跑通

【免费下载链接】kkFileViewUniversal File Online Preview Project based on Spring-Boot项目地址: https://gitcode.com/GitHub_Trending/kk/kkFileView

kkFileView 是 Spring Boot 做的在线预览服务，默认不落任何数据库。本文以人大金仓 KingbaseES 为目标，带你落地四步：把服务元数据指到国产数据库上，再把备份链路跑通一遍。

一、为什么是这套组合

选型就三条理由：

• KingbaseES V8R6 兼容 PostgreSQL 协议，JDBC 驱动拿来即用，改造成本低；
• 工具链成熟：ksql 查询、sys_dump 备份，都是现成命令；
• kkFileView 5.0.0 跑在 Spring Boot 3.5.6 + Java 21 上，落到库里的只是低频元数据写入，KingbaseES 扛得动。

预览效果不受影响，要备份的正是这类文档的元信息：

二、从 0 到 1：落地四步

1. 装 KingbaseES 并建库

这步干啥：把数据库装起来，建一个专用库。

chmod +x KingbaseES_V8R6_*.run ./KingbaseES_V8R6_*.run # 按向导安装，默认端口 54321 ksql -U system -d postgres -c "CREATE DATABASE kkfileview;"

它在干什么：装完库后用 ksql 建一个 kkfileview 专用库。确认跑通：ksql -U system -d kkfileview -c 'select version();'能回出版本号即可。

库起来之后，预览服务这边还不用碰数据库，先把服务跑起来。

2. 编译并启动 kkFileView 预览服务

这步干啥：拿到可运行的预览服务。

git clone https://gitcode.com/GitHub_Trending/kk/kkFileView cd kkFileView && mvn clean package -DskipTests java -jar server/target/kkFileView-5.0.0.jar

它在干什么：产物在 server/target 下，启动后监听 8012 端口。确认跑通：打开http://localhost:8012看到首页文件列表；/actuator/health返回 UP。

服务跑起来之后，预览服务这边只动一个文件。

3. 接上 KingbaseES 数据源与连接池

这步干啥：让应用连上库。⚠️ 先说清楚一件事：默认发行版不带 JDBC 依赖，pom.xml 里没有数据源组件，这一步要自己补。

先把官方 JDBC 驱动装进本地仓库：

mvn install:install-file -Dfile=kingbase8.jar \ -DgroupId=com.kingbase -DartifactId=kingbase8 -Dversion=8.6.0

它在干什么：把驱动 jar 登记到本地 Maven 仓库，pom 里才能声明这条依赖。随后在 pom 中补一个 JDBC starter，并把数据源配置追加到 application.properties 末尾：

# 数据源指向 KingbaseES spring.datasource.url=jdbc:kingbase8://localhost:54321/kkfileview spring.datasource.username=system spring.datasource.password=yourpassword spring.datasource.driver-class-name=com.kingbase8.Driver # Hikari 连接池 spring.datasource.hikari.maximum-pool-size=10 spring.datasource.hikari.minimum-idle=5 spring.datasource.hikari.idle-timeout=300000

改的是哪几行：前 4 行定连接，后 3 行定池子。库侧再建一张元数据表，名叫 document_meta，字段就几个：文件名、格式、大小、上传时间、备份状态。预览服务自身的 trust.host 等安全项另行配置，见 SECURITY_CONFIG.md，与备份链路互不干扰。

确认跑通：重新打包启动，日志无连接池报错，ksql 里能查到 document_meta 表。

4. 跑一次备份并验证结果

这步干啥：全量备份执行一次，调度接上。

sys_dump -U system -p 54321 -F p -f kkfileview_$(date +%F).sql kkfileview

它在干什么：sys_dump 是 KingbaseES 自带的全量备份命令，跑一次产出一个 SQL 文件。定时调度照项目现有风格配：SchedulerCleanConfig.java 里缓存清理用的就是每天凌晨 3 点的 cron，备份任务照抄即可。

✅ 验证两条：

ls -lh kkfileview_$(date +%F).sql # 备份文件已生成 ksql -U system -d kkfileview -c "SELECT count(*) FROM document_meta;"

文件在、行数和服务写入量对得上，链路就跑通了。

三、两个最容易问的点

KingbaseES 连接池参数怎么给

• 现象：预览高峰连接池耗尽，低谷又大量空闲。
• 原因：预览转换是长 IO 任务，连接被占住还不上来。
• 建议值：maximum-pool-size 取并发转换线程数的一半左右，minimum-idle 取 1/4，idle-timeout 给 300000。

定时备份任务粒度怎么选

• 现象：整点备份撞上预览高峰，互相抢 IO。
• 原因：全量备份 IO 重，必须避开高峰时段。
• 建议值：全量放每天凌晨 3 点（与项目现有 0 0 3 * * ? 一致），增量每小时一次。

四、踩坑速查

到这里，预览服务的元数据已落在 KingbaseES 上，全量备份也验证通过，链路完整。下一步可以把备份结果接进监控告警，或给 KingbaseES 配一套主从做热备。

【免费下载链接】kkFileViewUniversal File Online Preview Project based on Spring-Boot项目地址: https://gitcode.com/GitHub_Trending/kk/kkFileView