Yukon 安装指南

Yukon（禹贡）是基于 openGauss、PostgreSQL 和 GaussDB 数据库扩展地理空间数据存储和管理能力的空间数据库插件。它提供专业的 GIS 功能，支持二三维一体化的空间数据存储，包括矢量、栅格、三维模型、空间网格编码等数据类型。

Yukon for PostgreSQL 源码仓库地址：https://gitee.com/isupermap/yukon4pgsql，适用于PostgreSQL数据库。

1. 概述

Yukon 支持以下数据库：

数据库类型	数据库	说明
开源数据库	openGauss	支持 CentOS、欧拉（openEuler）操作系统，兼容模式仅支持 Oracle（datcompatibility=A）。Yukon2.2 未发布 Yukon for openGauss，如果您选择的数据库是openGauss，请转到 Yukon2.1文档。
开源数据库	PostgreSQL	支持 CentOS、麒麟操作系统
商用数据库	GaussDB	支持麒麟 v10、欧拉操作系统，兼容 Oracle 和 PostgreSQL 两种数据库平台兼容模式

2. 安装前准备

2.1 软硬件环境

硬件环境：建议参考 openGauss 的硬件环境要求。

操作系统：

架构	操作系统
ARM	openEuler 20.03 LTS、麒麟 v10
X86	openEuler 20.03 LTS、CentOS 7.6

数据库版本：

数据库	版本
GaussDB	请联系高斯数据库服务提供商获取 Yukon for GaussDB 版本
PostgreSQL	16

软件依赖（仅安装包安装需要，安装包已自带与操作系统软件源版本一致的依赖）：

软件名称	CentOS 7.6	openEuler 20.03 LTS
libtiff	4.0.3	4.1.0
libcurl	7.29.0	7.71.1
gmp	6.0.0	6.2.0
mpfr	3.1.1	4.1.0
libuuid	2.23.2	2.35.2
json-c	0.11	0.15
libxml2	2.9.1	2.9.10

2.2 数据库安装与配置

在安装 Yukon 之前，必须先安装并配置好数据库,数据库大版本需要和 Yukon 需要的数据库版本保持一致。

PostgreSQL：安装指导参见 PostgreSQL 官方下载页面
GaussDB：请联系高斯数据库服务提供商

2.2.1 GaussDB GUC 参数配置要求

安装 Yukon 前，请检查并调整以下 GaussDB GUC 参数。参数详细说明和设置方法请参考 GaussDB 官方文档。

1. 关闭部分 GUC 兼容性配置项

检查 behavior_compat_options 参数，确保以下配置项处于关闭状态，否则可能导致插件功能不可用或执行结果异常：

参数名	要求
allow_procedure_compile_check	关闭
proc_implicit_for_loop_variable	关闭
plpgsql_dependency	关闭
proc_outparam_override	关闭

2. 检查以下参数是否符合要求

参数名	取值	说明
enable_default_ustore_table	off	目前不支持 ustore 存储模式，默认值为 on，需设置为 off
a_format_version	‘’（空字符串）	必须设为空字符串，默认值即为空；若值为 “10c” 会导致 postgis_raster 模块创建失败

3. Yukon 安装

Yukon 提供两种安装方式，您可以根据使用场景选择：

安装方式	适用场景	特点
Docker 安装	快速体验、开发测试	一键启动，预装所有扩展，无需手动配置
安装包安装	生产环境部署	稳定可靠，支持多节点和集群部署

下面以Yukon for PostgreSQL版本为例，说明三种安装方式的操作步骤。

3.1 Docker 安装

Note 下载镜像前请先添加阿里云镜像源。

可用镜像：

镜像名称	数据库	架构
supermap/yukon:2.2-postgresql16-amd64	PostgreSQL 16	amd64
supermap/yukon:2.2-postgresql16-arm64	PostgreSQL 16	arm64

启动容器：

# PostgreSQL 镜像
docker run --name Yukon --privileged=true -d \
    -e POSTGRES_PASSWORD=Bigdata@123 \
    supermap/yukon:2.2-postgresql16-amd64

环境变量：

环境变量	必选/可选	适用镜像	说明
POSTGRES_PASSWORD	必须设置	PostgreSQL	设置 PostgreSQL 密码

数据持久化：

容器删除后数据会丢失，建议通过 -v 参数挂载宿主机目录：

mkdir -p /Yukon/postgresql
docker run --name Yukon --privileged=true -d \
    -e GS_PASSWORD=Bigdata@123 \
    -v /Yukon/postgresql:/var/run/postgresql/pg16/data \
    -p 5432:5432 \
     supermap/yukon:2.2-postgresql16-amd64

外部访问：

通过 -p 参数进行端口映射后，即可从容器外部访问数据库。映射后可使用 DBeaver 等工具连接。

3.2 安装包安装

请联系超图支持获取安装包。

安装步骤：

安装时请使用数据库所属用户：openGauss/GaussDB 为 omm，PostgreSQL 为 postgres。

1. 解压安装包

tar -xf yukon-2.2-xxx-xxx.tar.gz -C /opt/software/yukon

2. 进入解压目录并检查权限

cd /opt/software/yukon

Warning 请检查文件夹权限，所属用户必须为数据库所属用户（omm 或 postgres）。如果误操作为 root 用户，请使用正确用户重新解压！

3. 检查数据库环境变量

# 检查 pg_config 命令是否正常运行
pg_config

# 检查 PGDATA 环境变量
echo $PGDATA

# 检查 LD_LIBRARY_PATH 环境变量
echo $LD_LIBRARY_PATH

4. 配置数据库环境变量（如步骤 3 检查存在问题）

PostgreSQL 配置参考：

# 设置数据库安装目录
export PGHOME=/opt/pg16
# 设置 PATH
export PATH=$PATH:$PGHOME/bin
# 设置数据目录
export PGDATA=$PGHOME/data
# 设置 LD_LIBRARY_PATH
echo export LD_LIBRARY_PATH='$LD_LIBRARY_PATH':$PGHOME/lib >> /home/pg16/.bashrc
source /home/pg16/.bashrc

GaussDB 配置参考：

# 手动加载环境变量文件（通常 PATH/LD_LIBRARY_PATH 会自动加载）
source /home/omm/env_single
# 设置数据目录（根据实际 datanode 路径设置）
export PGDATA=$GAUSSHOME/dn1

5. 执行安装

sh install.sh -i

显示如下信息表示安装成功。

\ \   / /     | |
 \ \_/ /_   _ | | __ ___   _ __
  \   /| | | || |/ // _ \ |  _ \
   | | | |_| ||   <| (_) || | | |
   |_|  \____||_|\_\\___/ |_| |_|

Note

安装脚本通过 pg_config 命令确定文件安装位置，请先确认 pg_config 路径是否正确。

Yukon for PostgreSQL 如需支持 Citus 插件，需在 postgresql.conf 中添加 shared_preload_libraries = citus。该文件通常位于 PGDATA 变量指向的数据目录内。

多节点安装： 每个节点分别执行上述单节点安装步骤即可。

主备集群安装：

前置条件：主机之间必须已建立 SSH 互信。

sh install_cluster.sh -f hostfile -U username

hostfile：包含所有主机 IP 的配置文件，每行一个 IP
```
192.168.0.1
192.168.0.2
192.168.0.3
```
username：集群安装用户，默认为 omm

4. 创建扩展

Yukon 安装完成后，二进制文件已部署到数据库目录中，但还需要在数据库中创建扩展（Extension）才能使用其功能。

Note： postgis 是基础扩展，被其他所有扩展依赖，因此必须先创建 postgis，再创建其他扩展。

4.1 Docker 安装

Docker 镜像的 postgres 数据库默认已预装所有扩展，无需手动创建。如果您需要在其他数据库中使用 Yukon，可在新建的数据库中执行 4.2 中的 CREATE EXTENSION 语句。

4.2 安装包安装

安装包安装方式需要手动创建扩展，请根据您的数据库类型执行对应的命令。

GaussDB：

# 登录数据库
gsql -d postgres

-- 创建扩展（按需添加）
CREATE EXTENSION postgis;
CREATE EXTENSION postgis_raster;
CREATE EXTENSION postgis_topology; 
CREATE EXTENSION yukon_geomodel;
CREATE EXTENSION yukon_geogridcoder;
CREATE EXTENSION yukon_vector_pyramid;
CREATE EXTENSION pgrouting;
CREATE EXTENSION pointcloud;
CREATE EXTENSION postgis_sfcgal; -- 如果编译时启用了 SFCGAL，可创建 postgis_sfcgal 扩展

PostgreSQL：

# 登录数据库
psql -d postgres

-- 创建扩展（按需添加）
CREATE EXTENSION postgis;
CREATE EXTENSION postgis_raster;
CREATE EXTENSION postgis_topology;
CREATE EXTENSION yukon_geomodel;
CREATE EXTENSION yukon_geogridcoder;
CREATE EXTENSION yukon_vector_pyramid;
CREATE EXTENSION pgrouting;
CREATE EXTENSION pointcloud;
CREATE EXTENSION mobilitydb;
CREATE EXTENSION postgis_sfcgal; -- 如果编译时启用了 SFCGAL，可创建 postgis_sfcgal 扩展
CREATE EXTENSION timescaledb; -- 安装时序扩展时，需要在 postgresql.conf 的 shared_preload_libraries 添加 timescaledb

扩展说明：

扩展名	功能	依赖
postgis	矢量数据支持	无
postgis_raster	栅格数据支持	postgis
postgis_topology	拓扑分析支持	postgis
yukon_geomodel	三维模型数据支持	postgis
yukon_geogridcoder	空间网格编码支持	postgis
yukon_vector_pyramid	矢量金字塔支持	postgis
pgrouting	路由功能支持	postgis
pointcloud	点云功能支持	postgis
mobilitydb	轨迹功能支持，仅 Yukon for PostgreSQL 支持	postgis
postgis_sfcgal	三维算法支持	postgis
timescaledb	时序管理功能支持，仅 Yukon for PostgreSQL 支持	无

Note

postgis 是基础模块，被其他所有模块依赖，需优先创建。

GaussDB 非初始化用户使用扩展时不支持 public 模式，如需扩展到 public 下，必须使用数据库初始化用户进行扩展。
GaussDB 的 yukon_geogridcoder、yukon_geomodel、yukon_vector_pyramid 为试用模块，创建这些扩展前需要启用 enable_extension 参数：
SET enable_extension = on;
CREATE EXTENSION yukon_geomodel;
CREATE EXTENSION yukon_geogridcoder;

5. 安装后配置

安装完成后，可能需要修改数据库连接参数以支持外部访问。

数据库配置文件位于数据目录下：

数据库	配置文件路径（示例）
PostgreSQL 16	`/opt/postgres16/data/postgresql.conf`、`/opt/postgres16/data/pg_hba.conf`

5.1 修改数据库连接参数

1. 修改监听地址

# postgresql.conf（PostgreSQL 通用）
listen_addresses = '*'

设置为 * 表示监听所有网卡地址。

2. 配置远程访问白名单

在 pg_hba.conf 中添加一行，允许指定网段的主机连接：

# pg_hba.conf
host    all    all    192.168.13.0/24    md5

如需接受所有请求，可将子网掩码设置为 0。

Note GaussDB 提供了 gs_guc 工具用于设置配置文件中的参数，详见 openGauss gs_guc 文档。

gs_guc 工具不支持包含 . 符号的参数（如 postgis.backend），此类参数可通过 SET 命令进行修改。

5.2 重启数据库

参数修改完成后，需要重启数据库使配置生效：

# PostgreSQL
pg_ctl restart -D /opt/postgres16/data

6. 验证安装

安装完成后，可通过以下命令快速验证 Yukon 是否安装成功：

# PostgreSQL
psql -d postgres -c "SELECT yukon_version();"

正常输出类似：

yukon_version
--------------------------------------------------------------------------------
2.2(Community Edition) BUILDID:20260521 Compiled at:2026-05-21 10:10:58 Commit ID:7dc2a5

7. 版本升级

Yukon 支持从 2.1 版本升级到当前 2.2 版本。

Warning： 升级前请先备份数据库。

安装包安装方式升级

安装新版本 Yukon 后，登录数据库对扩展模块执行升级 SQL，需对每个扩展模块分别执行升级。

-- 升级到最新版本
ALTER EXTENSION yukon_geogridcoder UPDATE;

-- 或升级到指定版本
ALTER EXTENSION yukon_geogridcoder UPDATE TO '1.0.2';

Note：

建议重启数据库后再进行升级操作。

GaussDB 需要启用兼容参数后才能正常升级：

使用 gs_guc 工具：gs_guc reload -D datadir -c "support_extended_features=on"

或在数据库中执行：ALTER SYSTEM SET support_extended_features TO on

详见 openGauss 兼容性文档

8. 卸载

8.1 Docker 方式卸载

直接删除 Docker 容器和镜像即可。

8.2 安装包方式卸载

sh install.sh -r

或使用 yk_tool 工具卸载（详见参考工具 - yk_tool）：

yk_tool -r