安装与卸载 ========== 目前 Yukon 2.0.1 版本支持开源数据库openGauss和PostgreSQL,以及商用数据库GaussDB。 在安装 Yukon 之前必须先安装数据库。 开源数据库安装指导参见: `openGauss `__ 或 `PostgreSQL `__ 。 商用数据库GaussDB请联系高斯数据库服务提供商。 .. note:: 1、openGauss 支持的操作系统有: centos_x86_64、openeuler_aarch64、openeuler_x86_64,请优先在这些操作系统进行安装。 2、openGauss/GaussDB 的数据库兼容模式,Yukon目前只支持默认oracle模式,即datcompatibility=A。 数据库安装成功后,开始 Yukon 产品的安装。 获取安装包 ---------- 下载地址: 链接: https://pan.baidu.com/s/19uXmbXQwgObRYyCPtdm51w?pwd=pxhv 提取码: pxhv 安装包 ===================== ============== ==================================================== ================================================================== 2.0.1 版本 操作系统 安装包名称 sha256 ===================== ============== ==================================================== ================================================================== Yukon for AgensGraph Windows Yukon-2.0.1-Agensgraph_2.13-Win64.zip Yukon for AgensGraph CentOS7.6 Yukon-2.0.1-Agensgraph_2.13-CentOS_x64.tar.gz a1a4a3896aa160356eef179e199abaa9c3381f252ec5c040cd1244871fd9301e Yukon for openGauss CentOS7.6 Yukon-2.0.1-openGauss_5.0.0-CentOS_x64.tar.gz dd998280c976200a6fbfb87db13197604f51052e20c5121833255728e1687875 Yukon for openGauss openEuler Yukon-2.0.1-openGauss_5.0.0-openEuler_aarch64.tar.gz Yukon for GaussDB Kylin10 Yukon_Pro-2.0.1-GaussDB-Kylin10_aarch64.tar.gz 5dc305b19158d6e3aaaff0d8cefd18b6fcd70015b1c59ca1af6fc230dd0d5243 Yukon for GaussDB Kylin10 Yukon_Pro-2.0.1-GaussDB-Kylin10_x86.tar.gz Yukon for PostgreSQL CentOS7.6 Yukon-2.0.1-postgres_13-CentOS_x64.tar.gz 201fcd07145a2e0b83149f2a8b9109bb4096c6a853503f8832aeedcbfafd6a4f ===================== ============== ==================================================== ================================================================== .. note:: Yukon for AgensGraph 的 Windows版本为免安装版本,并且包含数据库,只需解压后按照readme.txt指导内容,初始化后即可使用。 1. 从 Yukon 开源仓库下载对应平台的安装包 1. 登录 `Yukon For openGauss 源码 `__\ 托管网站下载适配 openGauss5.0.0的安装包。 2. 登录 `Yukon For PostgreSQL `__ 源码托管网站下载适配 PostgreSQL13 的安装包 3. 登录账号,点击 ``Yukon-2.0.1-xxx-xxx.tar.gz`` 下载。 2. | 检查安装包 | 解压安装包,检查安装目录及文件是否齐全。在安装包所在目录执行以下命令: .. code:: bash mkdir yukon tar -xf Yukon-2.0.1-xxx-xxx.tar.gz -C yukon ls -l yukon 执行 ls 命令,显示类似如下信息: .. code:: bash ls -l drwxr-xr-x 8 root root 138 Dec 29 21:52 . dr-xr-x---. 20 root root 4096 Dec 30 14:33 .. drwxr-xr-x 2 root root 75 Dec 29 21:52 bin drwxr-xr-x 2 root root 278 Dec 29 21:52 data drwxr-xr-x 2 root root 8192 Dec 29 21:52 extension -rw-r--r-- 1 root root 7649776 Dec 29 21:52 Yukon 2.0.1 产品文档.pdf -rw-r--r-- 1 root root 4367 Dec 29 21:52 install.sh drwxr-xr-x 2 root root 220 Dec 29 21:52 lib drwxr-xr-x 2 root root 4096 Dec 29 21:52 license drwxr-xr-x 2 root root 4096 Dec 29 21:52 yukon_dep 软硬件环境要求 -------------- 硬件环境要求 ~~~~~~~~~~~~ 硬件环境建议参考 openGauss 的\ `硬件环境要求 `__\ 。 软件环境要求 ~~~~~~~~~~~~ +-----------------+-----------------------+ | 软件类型 | 配置描述 | +=================+=======================+ || || ARM: | || || - openEuler 20.03LTS | || || - 麒麟 v10 | || Linux 操作系统 || X86: | || || - openEuler 20.03LTS | || || - Centos 7.6 | || || | +-----------------+-----------------------+ || || - openGuass5.0.0 | || 数据库 || - GuassDB | || || - PostgreSQL 13 | +-----------------+-----------------------+ 软件依赖要求 ------------ 为了尽可能的与操作系统的默认软件保持兼容,我们在软件的安装包中自带和操作系统软件源中版本一致的依赖软件,列表如下: ======== =================== ======================== 软件名称 **Centos(7.6)版本** **openEuler(20.03)版本** ======== =================== ======================== 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 ======== =================== ======================== GaussDB相关GUC参数要求 ------------ GUC参数详细说明和设置方法请参考GaussDB官方文档。 1、检查GUC兼容性配置参数behavior_compat_options,关闭部分GUC兼容性配置项,如果未关闭可能会出现插件功能不可用或执行结果异常的情况。 具体参数如下: allow_procedure_compile_check proc_implicit_for_loop_variable plpgsql_dependency proc_outparam_override 2、检查GUC参数是否符合以下取值要求 enable_default_ustore_table=off 说明:目前不支持ustore存储模式,默认值为on,需要关闭设置为off。 a_format_version='' 说明:必须设为'',默认值即为空,若值为"10c"会导致postgis_raster模块创建失败。 安装包安装 ---------- 单节点安装 ~~~~~~~~~~ 安装时请使用数据库所属用户,这里假设 openGauss/GaussDB 数据库所属用户为 omm, PostgreSQL 所属用户为 postgres。 1. 使用 omm/postgres 用户登录到 Yukon 包要安装的主机,解压 Yukon 压缩包到任意目录(假定目录为 /opt/software/yukon) .. code:: tar -xf Yukon-2.0.1-Beta-xxx-xxx.tar.gz -C /opt/software/yukon 2. 进入解压后的目录 .. code:: cd /opt/software/yukon .. note:: 注意检查文件夹权限,所属用户必须为第1步中的数据库所属用户,如果误操作为root用户,请及时使用正确用户重新解压! 3.检查数据库环境变量 .. code:: --检查pg_config命令是否正常运行以及输出结果是否正确 pg_config --检查PGDATA环境变量,输出结果是否为空以及是否正确 echo $PGDATA --检查LD_LIBRARY_PATH环境变量,输出结果是否为空以及是否包含数据库lib目录 echo $LD_LIBRARY_PATH 4.配置数据库环境变量[可选] 如果检查数据库环境变量存在问题,请按照以下步骤重新配置PATH、LD_LIBRARY_PATH、PGDATA环境变量,并且配置后需要重新检查。 (1)PostgreSQL配置参考 .. code:: --设置PGHOME环境变量,指定数据库安装目录,请根据实际数据库安装参数进行设置 export PGHOME=/opt/pg13 --设置PATH环境变量 export PATH=$PATH:$PGHOME/bin --设置PGDATA环境变量,指定数据库的数据目录位置,请根据实际数据库安装参数进行设置 export PGDATA=$PGHOME/data --设置LD_LIBRARY_PATH环境变量 echo export LD_LIBRARY_PATH='$LD_LIBRARY_PATH':$PGHOME/lib >>/home/pg13/.bashrc source /home/pg13/.bashrc (2)openGauss/GaussDB配置参考 openGauss/GaussDB数据库安装后会生成用户环境变量文件,PATH/LD_LIBRARY_PATH一般会自动加载,不需要手动; 如果遇到需要手动加载的情况,可直接source用户环境变量文件。 .. code:: --手动source环境变量文件 source /home/omm/env_single --设置PGDATA环境变量,需要根据数据库的数据目录datanode进行设置,可查看数据库配置文件cluster_config.xml export PGDATA=$GAUSSHOME/dn1 5. 执行安装脚本安装 Yukon .. code:: sh install.sh -i 上述命令中使用 ``-i`` 参数表示安装,卸载时可使用 ``-r`` 参数。 6. 安装完成后会显示如下界面 .. code:: \ \ / / | | \ \_/ /_ _ | | __ ___ _ __ \ /| | | || |/ // _ \ | _ \ | | | |_| || <| (_) || | | | |_| \____||_|\_\\___/ |_| |_| .. note:: 安装脚本是通过 pg_config 命令获取 Yukon 的文件应该被安装到那些位置。因此你首先应该确定 pg_config 的位置是否正确,同时 Yukon for Postgres 需要在 postgresql.conf 中添加 `shared_preload_libraries = citus` 才能支持 citus 插件。而该文件一般在数据库实例的数据目录文件夹内,并由 PGDATA 变量表示。 多节点安装 ~~~~~~~~~~~~ 每个节点分别执行单节点安装,具体步骤参考“单节点安装”。 编译安装 -------- 1. 获取 Yukon 源码 安装 git 工具,在 Yukon 的 Gitee 仓库获取源码,以 Yukon for openGauss 为例: .. code:: bash git clone https://gitee.com/opengauss/Yukon.git 2. 准备编译环境 安装下列软件依赖包 - `gcc/g++ `__ - `gdal-devel `__ - `geos-devel `__ - `json-c-devel `__ - `proj-devel `__ - `libxml2-devel `__ - `sfcgal `__ 以上安装包可以通过源码安装,也可以直接使用 yum 工具直接安装。如果还缺少其他依赖,可自行安装。 三方库的编译过程可参考 :ref:`appendixb_label` 。 3. 开始编译 准备好编译环境以后,就可以开始进行编译安装: .. code:: bash # 如果您想使用 SFCGAL 作为 PostGIS 的处理后端,那么在准备安装环境时,需要预先安装 SFCGAL 进入Yukon目录后运行配置文件: cd Yukon ./configure --with-pgconfig=/pg_config --without-topology --without-address-standardizer \ --without-interrupt-tests CFLAGS='-O2 -fpermissive -DPGXC -pthread ' CC=g++ make make install .. note:: 安装时可能会提示 openGauss 目录下缺少部分头文件,此时需要从 `openGauss源码库 `__ 中的 src/include 目录 下拷贝对应文件到提示的目录下,出于方便也可以直接全部覆盖。 如果在安装 gdal、 geos、 json-c、 libxml2、porj、 sfcgal时自定义了安装路径,那么运行配置文件时需要添加以下的配置选项: .. code:: bash --with-gdalconfig=/path/gdal-config --with-geosconfig=/path/geos-config \ --with-xml2config=/path/xml2-config --with-jsondir=/path/json-c \ --with-projdir=/path/proj4 --with-sfcgal=/path/sfcgal-config 同时,需要将这些依赖的动态库的路径添加到 /etc/ld.so.conf 文件中,然后使用 ``ldconfig`` 命令加载路径,或者将路径添加到 `LD_LIARARY_PATH` 环境变量中。 4. 开始使用 以上安装完成后,可以进入数据库操作。这里我们以 openGauss 为例: .. code:: bash --- 切换到 omm (数据库安装用户) su omm --- 连接到 postgres 数据库 gsql -d postgres .. code:: sql --- 创建 postgis 扩展 CREATE EXTENSION postgis; --- 创建 postgis_raster 扩展 CREATE EXTENSION postgis_raster; --- 创建 yukon_geomodel 扩展 CREATE EXTENSION yukon_geomodel; --- 创建 yukon_geogridcoder 扩展 CREATE EXTENSION yukon_geogridcoder; -- 如果在编译时支持了 SFCGAL 则可以创建 SFCGAL 扩展 CREATE EXTENSION postgis_sfcgal; 容器安装 -------- .. note:: 下载镜像前请先添加阿里云镜像源。 目前 2.0.1 版本提供的 Docker 镜像如下: + supermap/yukon:2.0.1-opengauss5.0.0-amd64 + supermap/yukon:2.0.1-opengauss5.0.0-arm64 + supermap/yukon:2.0.1-postgresql13-amd64 + supermap/yukon:2.0.1-agensgraph213-amd64 启动Yukon ~~~~~~~~~~~ .. code:: bash --Yukon for openGauss docker run --name Yukon --privileged=true -d -e GS_PASSWORD=Bigdata@123 supermap/yukon:2.0.1-opengauss5.0.0-amd64 --Yukon for PostgreSQL docker run --name Yukon --privileged=true -d -e POSTGRES_PASSWORD=Bigdata@123 supermap/yukon:2.0.1-postgresql13-amd64 环境变量 ~~~~~~~~~~~ openGauss镜像支持以下变量的设定: - ``GS_PASSWORD`` :【\ **必须设置**\ 】,该参数设置了 openGauss 数据库的超级用户 omm 以及外部连接用户 gaussdb 的密码。openGauss 安装时默认会创建 omm 超级用户,测试用户 gaussdb 是在 `entrypoint.sh `__ 中自定义创建的用户,openGauss 设置的密码要符合复杂度要求: - 最少包含8个字符。 - 不能和用户名、当前密码(ALTER)、或当前密码反序相同。 - 至少包含大写字母(A-Z),小写字母(a-z),数字,非字母数字字符(限定为~!@#$%^&\*()-\_=+\|[{}];:,<.>/?)四类字符中的三类字符。 - ``GS_NODENAME``\ :【可选设置】,该参数设置了 openGauss 数据库的节点名称,默认为 gaussdb,可以在 ``entrypoint.sh`` 中进行查看 - ``GS_USERNAME``\ :【可选设置】,该参数设置了 openGauss 数据库的外部连接用户名,默认为 gaussdb,可以在 ``entrypoint.sh`` 中进行查看 - ``GS_PORT``:【可选设置】,该参数设置了 openGauss 数据库的连接端口,默认为 5432,可以在 ``entrypoint.sh`` 中进行查看。 PostgreSQL 镜像支持以下变量的设定: - ``POSTGRES_PASSWORD`` :【**必须设置**】,设置 PostgreSQL 密码 体验 Yukon ~~~~~~~~~~ 稍等片刻,等 Yukon 启动后,可以使用如下命令体验 Yukon。以 Yukon for openGauss 为例: .. code:: bash sudo docker exec -it Yukon /bin/bash su omm gsql -d postgres 连接成功后,可以看到类似如下的字符: .. code:: bash [omm@367dd3bb5d10 /]$ gsql -d postgres gsql ((openGauss 2.1.0 build 590b0f8e) compiled at 2021-09-30 14:29:04 commit 0 last mr ) Non-SSL connection (SSL connection is recommended when requiring high-security) Type "help" for help. openGauss=# postgres 数据库默认已经创建了 `postgis` , `postgis_raster` , `postgis_sfcgal` , `yukon_geomodel`, `yukon_geogridcoder` 扩展,可以直接使用。 .. code:: text -- 查询 yukon_geomodel 的版本及其编译时间 select yukon_version(); -- 输出 2.0(Community Edition) BUILDID:20230821 Compiled at:2023-08-21 10:10:58 Commit ID:7dc2a5 外部连接数据库 ~~~~~~~~~~~~~~~~~~~~ openGauss 的默认监听端口为 5432 ,如果想要从容器外部访问数据库,则需要在 ``docker run`` 的时候指定 ``-p`` 进行端口映射: .. code:: bash docker run --name Yukon --privileged=true -d -e GS_PASSWORD=Bigdata@123 -p 5432:5432 supermap/yukon:2.0.1-opengauss5.0.0-amd64 现在就可以使用 openGauss 的数据库管理工具 DataStudio,或者使用开源的 DBeaver 连接数据库(第一次连接时间可能较长,需要等待数据库安装初始化完成)。 持久化存储数据 ~~~~~~~~~~~~~~ 容器一旦被删除,容器内的所有数据和配置也均会丢失,而从镜像重新运行一个容器的话,则所有数据又都是呈现在初始化状态,因此对于数据库容器来说,为了防止因为容器的消亡或者损坏导致的数据丢失,需要进行持久化存储数据的操作。通过在 ``docker run`` 的时候指定 ``-v`` 参数来实现,或者可以指定已经建立好的 Volume 。使用以下命令将 openGauss 的所有数据文件存储在宿主机的 /Yukon/opengauss 下。 .. code:: bash mkdir -p /Yukon/opengauss docker run --name Yukon --privileged=true -d -e GS_PASSWORD=Bigdata@123 \ -v /Yukon/opengauss:/var/lib/opengauss -p 5432:5432 \ supermap/yukon:2.0.1-opengauss5.0.0-amd64 主备节点安装 ------------ 如果是在 openGauss 集群下安装 Yukon,需要在主机间执行命令,传送文件等操作。 在主机之间建立互信的基础上,只需执行安装包里的脚本文件 ``sh install_cluster.sh -f hostfile -U username`` 即可(openGauss安装集群时,会在主机间建立互信,如果此时没有互信,可以再重新手动建立互信)。 - ``hostfile`` :存放有openGauss中所有主机IP的配置文件。 例: /opt/software/openGauss> vim hostfile .. code::text 192.168.0.1 192.168.0.2 192.168.0.3 - ``username`` :openGauss集群所使用的安装用户,默认为 ``omm`` 用户。 数据库参数修改 -------------- 数据库参数的修改均位于数据目录下的 ``postgresql.conf`` 和 ``pg_hba.conf`` 两个文件中,下面为假定的配置文件所在位置: openGauss/GaussDB .. code:: bash /opt/openGauss/cluster/dn1/postgresql.conf /opt/openGauss/cluster/dn1/pg_hba.conf PostgreSQL13 .. code:: bash /opt/postgres13/data/postgresql.conf /opt/postgres13/data/pg_hba.conf 1. 修改 openGauss/GaussDB 的加密方式 对于 openGauss/GaussDB 来说,需要将其加密方式改为 MD5,否则将会导致数据库工具软件无法连接。 .. code:: bash # openGauss/GaussDB: /opt/openGauss/cluster/dn1/postgresql.conf 将 password_encryption_type 修改为 0 ,并取消注释 password_encryption_type = 0 2. 修改监听地址 一般情况下,我们并不会只在本地连接到数据库,也会在其他主机连接数据库,因此,我们需要修改一下监听的网卡 IP 地址,使其他主机也能够连接到数据库。这里我们修改为 ``*`` 表示监听所有网卡地址。 .. code:: bash # openGauss/GaussDB: /opt/openGauss/cluster/dn1/postgresql.conf # PostgreSQL: /opt/postgres13/data/postgresql.conf listen_addresses = '*' # what IP address(es) to listen on; 3. 修改可接受的远程 IP 地址 一般情况下,我们会通过 IP 将数据库可接受的连接接限制在某个范围。因此我们可以在 ``pg_hba.conf`` 加入下面的一行表示可接受位于 ``192.168.13.1/24`` 网段内的所有主机。如果想接受所有请求,可以将子网掩码设置为 0. .. code:: bash # openGauss/GaussDB: /opt/openGauss/cluster/dn1/pg_hba.conf # PostgreSQL: /opt/postgres13/data/pg_hba.conf host all all 192.168.13.1/24 md5 4. openGauss/GaussDB 数据库提供了gs_guc工具设置配置文件(“postgresql.conf”、“pg_hba.conf”)中的参数,详见 `openGauss `__ .. note:: gs_guc 工具不支持包含'.'符号的参数设置。例如:postgis.backend 无法通过 gs_guc 进行配置。可以通过 set 命令进行修改。 数据库参数修改完成后重新启动数据库,使参数生效。 验证 ---- 在本节我们会使用一款开源的数据库工具软件 `DBeaver(22.3.0) `__ 来连接数据库。 1. 创建用户 - openGauss/GaussDB openGauss/GaussDB 在外部连接时不能使用 omm 用户,因此这里我们新建一个用户用于测试,后续您可以将其删除。 1. 连接到数据库 .. code:: bash gsql -d postgres -p 5432 2. 创建用户 创建一个用户名为 test 密码为 Bigdata@123 的新用户。 .. code:: sql CREATE USER test with PASSWORD 'Bigdata@123' SYSADMIN; 输出如下则说明创建成功: .. code:: sql NOTICE: The encrypted password contains MD5 ciphertext, which is not secure. CREATE ROLE 如果没有输出 MD5 的提示,请检查是否将 openGauss/GaussDB 的加密方式修改为 MD5。 - PostgreSQL 1. 连接到数据库 .. code:: bash psql -d postgres -p 5432 2. 创建用户 创建一个用户名为 test 密码为 Bigdata@123 的新用户。 .. code:: sql CREATE USER test WITH PASSWORD 'Bigdata@123' Superuser; 输出如下则说明创建成功: .. code:: sql CREATE ROLE 2. 新建一个 数据库连接 这里我们统一使用 PostgreSQL JDBC 来连接数据库 |newconnection| 1. 输入数据库连接信息 填写我们第一步创建好的用户信息 |userinfo| 在 Host 位置写入数据库主机的 IP 地址,在 Username 写入我们刚刚创建的用户名 ``test``\ ,在 Password 位置写入我们的密码 ``Bigdata@123``\ 。 2. 测试连接 点击左下角的 Test Connection 测试是否可以连接到数据库。如果连接成功会显示数据库的信息。第一次连接时需要下载 JDBC 驱动,点击下载即可。 |driverdownload| openGauss/GaussDB 连接成功时,显示如下: |gs_connected| PostgreSQL 连接成功时,显示如下: |pg_connected| 3. 显示矢量数据 DBeaver 自带了显示 GIS 数据的能力,我们可以使用他来查看 GIS 数据。 首先创建 postgis 扩展 .. code:: sql CREATE EXTENSION POSTGIS; 查询矢量数据 .. code:: sql select 'SRID=4326;Point(116.4034318 39.9237871)'::geometry; |gisdisplay| 升级 ---- Yukon提供扩展模块的升级功能,支持从1.0升级到当前2.0.1版本。 以Yukon for openGauss为例,操作过程: 安装新版本Yukon 2.0.1 ,登录到需要升级的数据库,对不同的扩展模块执行SQL: .. code:: text ALTER EXTENSION name UPDATE [ TO new_version ] 比如,要将yukon_geogridcoder更新到版本 2.0.1 ,请执行: .. code:: text #升级到最新版本 alter extension yukon_geogridcoder update; 或 .. code:: text #升级到指定版本 alter extension yukon_geogridcoder update to '1.0.1'; .. note:: 建议重启数据库后再进行升级操作,openGauss/GaussDB需要启用兼容参数且重启数据库后才能正常升级,参数可以使用gs_guc工具进行修改,执行"gs_guc reload -D datadir -c "support_extended_features=on",另外openGauss也可以通过在数据库中执行"ALTER SYSTEM SET support_extended_features to on "进行修改,详情参考 `openGauss文档 `__ 。 卸载 ---- 如果使用安装包进行安装,执行 ``sh install.sh -r`` 命令即可卸载,也可以使用yk_tool -r 进行卸载,详情见 :ref:`yk_toolremove_label` 工具说明 。 如果使用源码进行编译安装,在源码根目录下,执行命令 ``make uninstall`` 进行卸载。 如果使用 Docker 进行安装,直接删除 Docker 容器和镜像即可。 您也可以手动检查以下三个地方查看是否有卸载残留,以openGauss为例: - ``$GAUSSHOME/lib/postgresql/`` 目录下与 postgis 和 yukon 相关的文件 - ``$GAUSSHOME/share/postgresql/extension/`` 目录下与 postgis 和 yukon 相关的文件 - ``$GAUSSHOME/lib`` 目录下是否有yukon相关的三方库文件 .. |newconnection| image:: /../_static/images/newconnection.png :width: 600px .. |userinfo| image:: /../_static/images/userinfo.png :width: 600px .. |driverdownload| image:: /../_static/images/driverdownload.png :width: 600px .. |gs_connected| image:: /../_static/images/gs_connected.png :width: 600px .. |pg_connected| image:: /../_static/images/pg_connected.png :width: 600px .. |gisdisplay| image:: /../_static/images/gisdisplay.png :width: 600px