麒麟系统 KingbaseES 安装 PostGIS 插件

作者：emanjusaka
本文为原创内容，后续可能会更新修正。转载时请保留原文链接，避免因版本差异产生误导。
📝 博客：彼岸花开可奈何 · www.emanjusaka.com · 博客园：cnblogs.com/emanjusaka · 公众号：emanjusaka的编程栈

KingbaseES V9 的安装包不包含 PostGIS，需要单独向金仓申请后手工部署。它属于增值模块，标准版和开发版授权不支持。

安装分四步：申请插件包、部署文件、重启实例、创建扩展。

一、适用环境

PostGIS 扩展只支持 Linux。 金仓官方明确说明 GIS 扩展不支持 Windows 平台。

二、安装前确认

2.1 授权版本

金仓 License 手册对标准版和开发版的描述是「提供除集群、GIS 以外的全部应用开发与系统管理功能」。GIS 属于增值模块，需要在专业版或企业版之上额外选购授权。

下载授权文件时选专业版或企业版，标准版和开发版的授权装不了 PostGIS。

2.2 版本号和 CPU 架构

PostGIS 的 .so 是针对金仓 server 内部 ABI 编译的，KES 版本或 CPU 架构不同都不通用。申请包时需要提供这两个信息：

# 数据库版本号
ls -l /opt/Kingbase/ES/V9/KESRealPro/
# 形如 V009R003C018

# CPU 架构
uname -m
# x86_64 或 aarch64

2.3 申请插件包

金仓官网没有 PostGIS 的公开下载页面，只能找官方申请。

报上版本号和 CPU 架构，拿到的包名形如 postgis-3.1.2_aarch64_V009R003C018B0003.tar.gz。包名里的架构（X86 / ARM）和版本号要和 2.2 查出的对应。

三、确认安装目录

金仓 V9 的安装目录分两层，根目录下的 Server 是软链接，实际内容在 KESRealPro/<版本号>/：

/opt/Kingbase/ES/V9/
├── KESRealPro/
│   └── V009R003C018/
│       ├── Server/
│       │   ├── bin/                  # 二进制
│       │   ├── lib/                  # .so 库文件
│       │   └── share/extension/      # 扩展元数据和安装脚本
│       ├── ClientTools/
│       ├── Interface/
│       └── license.dat
├── Server -> KESRealPro/V009R003C018/Server
└── data/

打补丁升级时 KESRealPro/ 下的版本号目录会更换，软链接跟随指向新目录。所以部署统一用软链接路径，升级后不用改。

ls -l /opt/Kingbase/ES/V9/Server   # 确认指向

本文命令统一使用 /opt/Kingbase/ES/V9/Server。

四、备份 Server 目录

cd /opt/Kingbase/ES/V9
tar czf ~/Server_$(date +%F).tar.gz KESRealPro/V009R003C018/Server

五、部署插件文件

5.1 解压并修改权限

金仓的运行用户默认是 kingbase，文件属主必须是它，否则加载时报权限拒绝。

mkdir -p /home/kingbase/postgis && cd /home/kingbase/postgis
tar xzf postgis-3.1.2_*.tar.gz
ls
# 应看到三个目录：bin  lib  share

chown -R kingbase:kingbase postgis-3.1.2
chmod -R 755 postgis-3.1.2

5.2 拷贝到 Server 目录

SERVER=/opt/Kingbase/ES/V9/Server

cp -a postgis-3.1.2/bin/*              $SERVER/bin/
cp -a postgis-3.1.2/lib/*              $SERVER/lib/
cp -a postgis-3.1.2/share/extension/*  $SERVER/share/extension/

chown -R kingbase:kingbase $SERVER/bin $SERVER/lib $SERVER/share/extension

cp -a 保留文件和权限位。同名文件直接覆盖。

5.3 确认扩展元数据

CREATE EXTENSION 执行的是扩展的安装脚本，脚本和元数据都在 share/extension：

• postgis.control：扩展元数据（版本、依赖、默认 schema）
• postgis--3.1.2.sql：安装脚本

ls $SERVER/share/extension/ | grep -i postgis
# 期望：postgis.control  postgis--3.1.2.sql

.control 里声明的版本号必须和 .sql 文件名一致。声明 3.1.2 但脚本叫 postgis--3.1.1.sql，CREATE EXTENSION 会失败。

5.4 检查依赖库

PostGIS 3.1.2 依赖 GEOS（几何运算）、PROJ（坐标投影）、GDAL（栅格格式）：

ldd $SERVER/lib/postgis-3.so | grep "not found"

没有输出说明依赖齐全。有输出就把缺失的 .so 补到 $SERVER/lib 下（金仓启动时会搜索这个目录）。也可以在启动脚本里追加：

export LD_LIBRARY_PATH=/opt/Kingbase/ES/V9/Server/lib:$LD_LIBRARY_PATH

六、配置文件

MySQL 兼容模式下 kingbase.conf 不需要任何修改。PostGIS 也不需要在配置文件里注册。

Oracle 模式需要在数据目录的 kingbase.conf 末尾追加：

NLS_LENGTH_SEMANTICS=char
enable_upper_colname=false
ora_numop_style=false
ora_input_emptystr_isnull=off

不要给 PostGIS 配 shared_preload_libraries。

这个参数用于需要预留共享内存、保留轻量级锁或启动后台进程的库（统计类扩展是典型）。PostGIS 是普通函数库，CREATE EXTENSION 注册后由会话按需加载，不占用这些资源。

该参数只在实例启动时读取，且指定的库找不到时服务器会启动失败。写上不存在的库名会导致数据库起不来。

七、重启实例

插件文件在实例启动时扫描，必须重启。

# 确认实例数据目录
ps -ef | grep kingbase | grep -v grep
# 看 -D 后面的路径，通常是 /opt/Kingbase/ES/V9/data

su - kingbase
cd /opt/Kingbase/ES/V9/Server/bin
./sys_ctl restart -D /opt/Kingbase/ES/V9/data

-D 换成实际数据目录。

八、创建扩展

8.1 连接

cd /opt/Kingbase/ES/V9/Server/bin
./ksql -U system -d <库名>

CREATE EXTENSION 需要超级用户，金仓里 system 是超级用户。普通用户执行会报 permission denied to create extension "postgis"。

8.2 创建

SHOW database_mode;                    -- 应返回 mysql

CREATE EXTENSION postgis;              -- 必需
CREATE EXTENSION postgis_raster;       -- 可选，栅格支持
CREATE EXTENSION fuzzystrmatch;        -- 可选，模糊字符串匹配

其余扩展的取舍：

• postgis_tiger_geocoder 依赖美国行政区划数据，国内场景用不上。
• postgis_sfcgal 需要 CGAL 库，官方插件包里通常不含。
• postgis_topology 见 8.3。

8.3 postgis_topology

postgis_topology 的安装脚本用 level 作标识符（拓扑层级），而 level 在金仓里是关键字，直接创建会报语法错误。

exclude_reserved_words 参数可以把指定关键字从语法分析器里排除，让它们回到普通标识符：

SET exclude_reserved_words = 'level';
CREATE EXTENSION postgis_topology;

被排除的关键字，其相关语法全部失效。比如设置之后 show transaction isolation level 会报语法错误。所以这个 SET 只在这个会话里执行，不要写进 kingbase.conf。会话结束影响消失。

九、验证

SELECT postgis_full_version();

再用一个实际计算确认函数链路可用：

-- 天安门到外滩的球面距离
SELECT ST_Distance(
    ST_SetSRID(ST_MakePoint(116.403874, 39.914885), 4326)::geography,
    ST_SetSRID(ST_MakePoint(121.473701, 31.230416), 4326)::geography
) AS distance_m;

确认扩展已登记：

SELECT * FROM sys_extension WHERE extname = 'postgis';

十、MySQL 兼容模式

10.1 CREATE EXTENSION 语法一致

MySQL 模式下语法与其他模式相同，第八章的语句直接用。

SHOW database_mode;   -- mysql / oracle / pg

10.2 database 和 schema

MySQL 里 database 兼作命名空间（db.table），金仓里 database 是连接边界，schema 才是命名空间（schema.table）。

PostGIS 的扩展对象（含 geometry 类型）建在当前默认 schema，通常是 public：

SELECT current_database(), current_user, current_schema();
SHOW search_path;      -- 默认 "$user", public

如果业务用同名 schema 隔离，确保 search_path 里保留 public，否则会出现扩展装了但找不到 geometry 类型。

10.3 引号

金仓里双引号始终是标识符引用符，不像 MySQL 默认把双引号当字符串。MySQL 兼容模式额外支持反引号。从 MySQL 迁移的 SQL 如果用了 "..." 包字符串，需要先改。

十一、常见问题

排查时先看金仓日志：

tail -n 100 /opt/Kingbase/ES/V9/data/log/kingbase.log

十二、小结

完整步骤：

1. 确认授权是专业版或企业版，且已选购 GIS 模块
2. 记录 KESRealPro/ 下的版本号和 uname -m，向金仓申请对应插件包
3. 备份 Server 目录
4. 解压插件包，chown kingbase:kingbase、chmod 755
5. 把 bin / lib / share/extension 拷到 Server 对应目录
6. 确认 share/extension 下有 postgis.control 和版本号一致的 .sql
7. ldd 检查 postgis-3.so 的依赖
8. 不修改 kingbase.conf
9. sys_ctl restart 重启实例
10. ksql -U system 连接后执行 CREATE EXTENSION postgis;
11. SELECT postgis_full_version(); 验证

装 postgis_topology 时，先在同一个会话里执行 SET exclude_reserved_words = 'level';。