# Yukon 安装指南

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

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

## 1. 概述

Yukon 支持以下数据库：

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

## 2. 安装前准备

### 2.1 软硬件环境

**硬件环境**：建议参考 openGauss 的 [硬件环境要求](https://docs.opengauss.org/zh/docs/3.1.0/docs/BriefTutorial/%E5%87%86%E5%A4%87%E8%BD%AF%E7%A1%AC%E4%BB%B6%E5%AE%89%E8%A3%85%E7%8E%AF%E5%A2%83.html)。

**操作系统**：

| 架构 | 操作系统 |
|------|---------------|
| 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 官方下载页面](https://www.postgresql.org/download/)
- **GaussDB**：请联系高斯数据库服务提供商

#### 2.2.1 GaussDB GUC 参数配置要求

安装 Yukon 前，请检查并调整以下 GaussDB GUC 参数。参数详细说明和设置方法请参考 [GaussDB 官方文档](https://docs.opengauss.org/zh/docs/3.1.0/docs/Toolreference/gs_guc.html)。

**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 |

**启动容器：**

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

**环境变量：**

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

**数据持久化：**

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

```bash
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. 解压安装包**

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

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

```bash
cd /opt/software/yukon
```

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

**3. 检查数据库环境变量**

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

# 检查 PGDATA 环境变量
echo $PGDATA

# 检查 LD_LIBRARY_PATH 环境变量
echo $LD_LIBRARY_PATH
```

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

PostgreSQL 配置参考：

```bash
# 设置数据库安装目录
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 配置参考：

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

**5. 执行安装**

```bash
sh install.sh -i
```

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

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

> **Note**
> - 安装脚本通过 `pg_config` 命令确定文件安装位置，请先确认 `pg_config` 路径是否正确。
> - Yukon for PostgreSQL 如需支持 Citus 插件，需在 `postgresql.conf` 中添加 `shared_preload_libraries = citus`。该文件通常位于 PGDATA 变量指向的数据目录内。

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

**主备集群安装：**

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

```bash
sh install_cluster.sh -f hostfile -U username
```

- `hostfile`：包含所有主机 IP 的配置文件，每行一个 IP

  ```text
  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](#42-安装包安装和编译安装) 中的 `CREATE EXTENSION` 语句。

### 4.2 安装包安装

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

**GaussDB：**

```bash
# 登录数据库
gsql -d postgres
```

```sql
-- 创建扩展（按需添加）
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：**

```bash
# 登录数据库
psql -d postgres
```

```sql
-- 创建扩展（按需添加）
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` 参数：
>   ```sql
>   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. 修改监听地址**

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

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

**2. 配置远程访问白名单**

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

```text
# pg_hba.conf
host    all    all    192.168.13.0/24    md5
```

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

> **Note**
> GaussDB 提供了 `gs_guc` 工具用于设置配置文件中的参数，详见 [openGauss gs_guc 文档](https://docs.opengauss.org/zh/docs/3.1.0/docs/Toolreference/gs_guc.html)。
>
> `gs_guc` 工具不支持包含 `.` 符号的参数（如 `postgis.backend`），此类参数可通过 `SET` 命令进行修改。

### 5.2 重启数据库

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

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

## 6. 验证安装

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

```bash
# 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，需对每个扩展模块分别执行升级。

```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 兼容性文档](https://docs.opengauss.org/zh/docs/3.1.0/docs/Developerguide/%E5%B9%B3%E5%8F%B0%E5%92%8C%E5%AE%A2%E6%88%B7%E7%AB%AF%E5%85%BC%E5%AE%B9%E6%80%A7.html)


## 8. 卸载

### 8.1 Docker 方式卸载

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

### 8.2 安装包方式卸载

```bash
sh install.sh -r
```

或使用 `yk_tool` 工具卸载（详见 [参考工具 - yk_tool](referencetool.rst)）：

```bash
yk_tool -r
```