# KingbaseShellInstall **Repository Path**: astrisk2011/KingbaseShellInstall ## Basic Information - **Project Name**: KingbaseShellInstall - **Description**: 🚀 KingbaseES V9 企业级自动化安装脚本 - 支持完整的错误处理、自动回退和详细日志记录 - **Primary Language**: Shell - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 13 - **Created**: 2026-06-20 - **Last Updated**: 2026-06-21 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # KingbaseShellInstall `KingbaseShellInstall.sh` 是一个面向 Linux 的 KingbaseES 自动化安装脚本，当前版本支持 V8/V9 安装介质识别、官方静默安装模板复用、系统服务注册、单机安装、主备安装和分级清理。脚本按安装阶段拆成函数，最后由 `main` 调用，便于后续扩展多节点集群时按节点角色选择不同阶段。 ## 当前能力 - 支持从 ISO 自动挂载并提取安装介质。 - 自动识别 `V8` / `V9`，也支持 `--force-version 8|9` 强制指定。 - 优先使用介质内的 `silent.cfg` / `response*.cfg` / `.rsp` 模板。 - 支持 `Oracle`、`MySQL`、`SQL Server` 兼容模式，并按模式写入对应初始化参数和 `shared_preload_libraries`。 - 默认采用保守安装策略，不无条件修改 PAM、firewalld、sysctl；相关操作必须显式传参。 - 安装失败时生成回滚脚本，可通过 `--auto-rollback` 自动执行。 - 安装完成后自动探测并调用 Kingbase 官方 `install/script/root.sh` 注册 `kingbased` 系统服务。 - 支持 `standalone`、`primary`、`standby` 三类节点角色。 - 支持独立清理模式：`stop`、`uninstall`、`purge`。 - 安装结束会打印部署信息，包括安装目录、数据目录、端口、数据库用户、实例状态、登录验证状态、系统服务状态和连接命令。 ## 已知前提 - 脚本需要以 `root` 执行。 - ISO 文件必须位于目标机器本地路径，或先复制到目标机器。 - 生产环境建议显式指定安装目录、数据目录、端口、系统用户、数据库用户和密码。 - 主备安装要求主库端口可从备库访问，防火墙需要提前关闭或放行数据库端口。 - Kingbase 客户端使用 `KINGBASE_PASSWORD`、`KINGBASE_PASSFILE` / `~/.kbpass`，不是 PostgreSQL 的 `PGPASSWORD` / `.pgpass`。脚本内部已统一使用 Kingbase 官方客户端认证方式。 ## 参数说明 | 参数 | 说明 | | --- | --- | | `--mode install\|cleanup` | 运行模式，默认 `install` | | `--cleanup-level stop\|uninstall\|purge` | 清理级别，仅 `cleanup` 模式使用 | | `--node-role standalone\|primary\|standby` | 节点角色，默认 `standalone` | | `--primary-host HOST` | 主库地址，`standby` 角色必填 | | `--repl-user USER` | 复制用户，`primary/standby` 使用 | | `--repl-pass PASS` | 复制用户密码，`primary/standby` 使用 | | `--repl-slot SLOT` | 复制槽名称，`standby` 可选；已存在时复用，不存在时创建 | | `--standby-source-data-dir DIR` | 备库基线同步目录，默认复用 `-d` 指定的数据目录 | | `-f FILE` | ISO 文件路径，安装模式必填 | | `-m MODE` | 兼容模式，支持 `Oracle`、`MySQL`、`SQL Server` | | `-i DIR` | 安装目录；未指定时按识别版本设置为 `/KingbaseES/V8` 或 `/KingbaseES/V9` | | `-d DIR` | 数据目录，默认 `/data` | | `-p PORT` | 数据库端口，默认 `54321` | | `-u USER` | 数据库用户名，默认 `system` | | `-P PASS` | 数据库密码，默认 `kingbase` | | `-U USER` | Linux 系统用户，默认 `kingbase` | | `-l FILE` | 日志文件路径 | | `--force-version 8\|9` | 强制指定主版本 | | `--auto-rollback` | 安装失败时自动执行回滚脚本 | | `--tune-os` | 写入 Kingbase 相关 `sysctl` 和 `limits.d` 配置 | | `--disable-firewalld` | 停止并禁用 `firewalld` | | `--relax-password-policy` | 临时放宽 PAM 密码复杂度策略 | ## 安装示例 ### 简易安装 适合临时测试或验证安装介质。使用默认端口 `54321`、默认数据库用户 `system`、默认系统用户 `kingbase`。 ```bash chmod +x KingbaseShellInstall.sh sudo ./KingbaseShellInstall.sh \ --mode install \ --node-role standalone \ -f /root/KingbaseES_V008R006C009B0014_Lin64_install.iso \ --force-version 8 \ -m Oracle \ -P 'Kb@2026Test#001' \ --auto-rollback ``` ### 生产环境单机安装 生产环境建议显式指定目录、端口、日志、密码，并开启 OS 调优。`firewalld` 是否关闭由现场安全策略决定；如果不能关闭，需要提前放行数据库端口。 ```bash sudo ./KingbaseShellInstall.sh \ --mode install \ --node-role standalone \ -f /root/KingbaseES_V008R006C009B0014_Lin64_install.iso \ --force-version 8 \ -m Oracle \ -i /KingbaseES/V8 \ -d /data/kingbase/v8 \ -p 54321 \ -u system \ -P 'Kb@2026Test#001' \ -U kingbase \ -l /root/kingbase-standalone-install.log \ --auto-rollback \ --tune-os ``` 安装完成后脚本会调用官方 `root.sh` 注册 `kingbased`，并输出部署信息。连接测试示例： ```bash sudo -u kingbase env KINGBASE_PASSWORD='Kb@2026Test#001' \ /KingbaseES/V8/Server/bin/ksql \ -d "host=127.0.0.1 port=54321 user=system password=Kb@2026Test#001 dbname=template1" \ -c 'select current_user, current_database();' ``` ### 生产环境主库安装 主库会在单机安装基础上写入复制参数、HBA 复制访问规则、复制用户和归档相关配置。 ```bash sudo ./KingbaseShellInstall.sh \ --mode install \ --node-role primary \ -f /root/KingbaseES_V008R006C009B0014_Lin64_install.iso \ --force-version 8 \ -m Oracle \ -i /KingbaseES/V8 \ -d /data/kingbase/v8 \ -p 54321 \ -u system \ -P 'Kb@2026Test#001' \ -U kingbase \ -l /root/kingbase-primary-install.log \ --auto-rollback \ --tune-os \ --repl-user esrep \ --repl-pass 'Esrep@2026#001' ``` 主库安装后建议执行： ```bash sudo -u kingbase /KingbaseES/V8/Server/bin/ksql \ -d "host=127.0.0.1 port=54321 user=system password=Kb@2026Test#001 dbname=template1" \ -A -t \ -c "select rolname, rolreplication, rolcanlogin from sys_roles where rolname='esrep';" ``` 预期结果类似： ```text esrep|t|t ``` ### 生产环境备库安装 备库会先完成软件安装和服务注册。由于官方 `root.sh` 会自动启动临时实例，脚本会先停止这个临时实例，再用 `sys_basebackup -R` 从主库拉取基线，并写入 `standby.signal`、`primary_conninfo` 和可选复制槽。 ```bash sudo ./KingbaseShellInstall.sh \ --mode install \ --node-role standby \ --primary-host 10.0.0.90 \ -f /root/KingbaseES_V008R006C009B0014_Lin64_install.iso \ --force-version 8 \ -m Oracle \ -i /KingbaseES/V8 \ -d /data/kingbase/v8 \ -p 54321 \ -u system \ -P 'Kb@2026Test#001' \ -U kingbase \ -l /root/kingbase-standby-install.log \ --auto-rollback \ --tune-os \ --repl-user esrep \ --repl-pass 'Esrep@2026#001' \ --repl-slot node1_slot ``` 如果 `node1_slot` 已存在，脚本会复用；如果不存在，脚本会通过 `sys_basebackup -S node1_slot -C` 创建。 备库安装后建议执行： ```bash sudo -u kingbase /KingbaseES/V8/Server/bin/ksql \ -d "host=127.0.0.1 port=54321 user=system password=Kb@2026Test#001 dbname=template1" \ -A -t \ -c 'select sys_is_in_recovery(), current_user, current_database();' ``` 预期结果类似： ```text t|system|template1 ``` ### 主备联通验证 在主库执行： ```bash sudo -u kingbase /KingbaseES/V8/Server/bin/ksql \ -d "host=127.0.0.1 port=54321 user=system password=Kb@2026Test#001 dbname=template1" \ -A -t \ -c "select pid, usename, application_name, client_addr, state, sync_state from sys_stat_replication;" sudo -u kingbase /KingbaseES/V8/Server/bin/ksql \ -d "host=127.0.0.1 port=54321 user=system password=Kb@2026Test#001 dbname=template1" \ -A -t \ -c "select slot_name, slot_type, active from sys_replication_slots;" ``` 预期结果类似： ```text 8160|esrep|node1|10.0.0.56|streaming|async node1_slot|physical|t ``` ## 安装完成输出 安装完成后脚本会打印“部署信息”，用于交付记录和现场核对。示例： ```text ================================== 部署信息 主机: node1 安装目录: /KingbaseES/V8 数据目录: /data/kingbase/v8 端口: 54321 数据库用户: system ksql 路径: /KingbaseES/V8/Server/bin/ksql 软件安装状态: software_installed 实例状态: cluster_started_existing 登录验证状态: verified 系统服务状态: registered 系统服务名: kingbased 日志文件: /root/final-standalone-fixed2.log 连接命令: sudo -u kingbase env KINGBASE_PASSWORD='***' /KingbaseES/V8/Server/bin/ksql -d "host=127.0.0.1 port=54321 user=system password=*** dbname=template1" ================================== ``` 常见状态说明： - `软件安装状态: software_installed` 表示官方安装器完成。 - `实例状态: service_started` 表示通过系统服务启动成功。 - `实例状态: cluster_started_existing` 表示官方 `root.sh` 已启动实例，脚本检测到实例可用后跳过重复启动。 - `登录验证状态: verified` 表示单机/主库数据库连接验证成功。 - `登录验证状态: standby_verified` 表示备库已启动并处于恢复模式。 - `系统服务状态: registered` 表示 `/etc/init.d/kingbased` 已由官方 `root.sh` 注册。 ## 清理示例 ### 停止实例 ```bash sudo ./KingbaseShellInstall.sh \ --mode cleanup \ --cleanup-level stop \ -i /KingbaseES/V8 \ -d /data/kingbase/v8 \ -U kingbase \ -l /root/kingbase-cleanup-stop.log ``` ### 卸载服务和配置，保留软件和数据 ```bash sudo ./KingbaseShellInstall.sh \ --mode cleanup \ --cleanup-level uninstall \ -i /KingbaseES/V8 \ -d /data/kingbase/v8 \ -U kingbase \ -l /root/kingbase-cleanup-uninstall.log ``` ### 彻底清理 ```bash sudo ./KingbaseShellInstall.sh \ --mode cleanup \ --cleanup-level purge \ -i /KingbaseES/V8 \ -d /data/kingbase/v8 \ -U kingbase \ -l /root/kingbase-cleanup-purge.log ``` `purge` 会删除系统服务、安装目录、数据目录、系统用户和 `/install/kingbase_*` 暂存目录。生产环境执行前必须确认数据已备份。 ## 阶段化结构 当前脚本已按安装阶段拆分为独立函数，由 `main` 统一调度： 1. `run_preflight_stage`：权限、参数、依赖和日志准备。 2. `run_install_precheck_stage`：用户、OS 调优、端口和安装前环境准备。 3. `run_media_prepare_stage`：挂载 ISO、识别版本、准备静默响应文件。 4. `run_software_install_stage`：调用官方安装器完成软件安装和初始实例初始化。 5. `run_service_registration_stage`：调用官方 `root.sh` 注册 `kingbased`；备库会停止 `root.sh` 自动启动的临时实例。 6. `run_role_configuration_stage`：按 `standalone/primary/standby` 执行角色配置。 7. `run_instance_start_stage`：启动实例或识别已运行实例。 8. `run_verification_stage`：验证二进制、数据目录、连接状态或备库恢复状态。 9. `run_cleanup_stage`：按 `stop/uninstall/purge` 做分级清理。 ## 主备实现说明 当前默认仍是单机安装，即 `--node-role standalone`。 - `primary`：在单机安装基础上追加复制参数、归档配置、复制用户和复制访问控制。 - `standby`：软件安装后停止官方脚本自动启动的临时实例，通过 `sys_basebackup -R` 执行基线同步，并生成 `standby.signal` 与 `primary_conninfo`。 主备安装顺序： 1. 在主库执行 `--node-role primary`。 2. 确认主库端口可从备库访问。 3. 在备库执行 `--node-role standby --primary-host <主库IP>`。 4. 在主库查询 `sys_stat_replication` 和 `sys_replication_slots`。 5. 在备库查询 `sys_is_in_recovery()`。 ## 模式差异与主备关系 主备复制机制在 `PG / Oracle / MySQL` 兼容模式下总体一致，底层都基于流复制、复制槽和 `sys_basebackup -R`。 模式差异主要体现在初始化参数和兼容库： - 初始化模式值不同：如 `ORACLE`、`MySQL`。 - `CASE_SENSITIVE_PARAM` 不同：MySQL 模式默认 `NO`，其他模式默认 `YES`。 - `shared_preload_libraries` 不同： - PG 模式：`repmgr` - Oracle 模式：`liboracle_parser, repmgr` - MySQL 模式：`libmysql_parser, repmgr` 脚本结构上将“节点角色”和“兼容模式”拆成两个维度： - 角色决定执行哪些阶段：`standalone / primary / standby` - 模式决定阶段内部采用哪套兼容参数：`Oracle / MySQL / SQL Server` ## 本轮真实回归记录 测试介质：`KingbaseES_V008R006C009B0014_Lin64_install.iso` 测试端口：`54321` 测试数据库用户：`system` 测试系统用户：`kingbase` | 场景 | 主机 | 结果 | 证据 | | --- | --- | --- | --- | | 单机安装 | `10.0.0.56` | 通过 | `final-standalone-fixed2.log`：`登录验证状态: verified`，`系统服务状态: registered`，部署信息已打印 | | 主库安装 | `10.0.0.90` | 通过 | `final-ha-primary-fixed3.log`：复制用户输出 `CREATE ROLE`、`esrep|t|t`，登录验证 `verified` | | 备库安装 | `10.0.0.56` | 通过 | `final-ha-standby-fixed3.log`：`复用已存在复制槽`、`standby_verified` | | 主备复制 | `10.0.0.90` / `10.0.0.56` | 通过 | 主库 `sys_stat_replication`：`10.0.0.56|streaming|async`；复制槽 `node1_slot|physical|t`；备库 `sys_is_in_recovery()` 返回 `t` | | 系统服务 | `10.0.0.90` / `10.0.0.56` | 通过 | 两节点 `service kingbased restart/status` 后数据库连接和恢复状态正常 | | 备库清理 | `10.0.0.56` | 通过 | `final-cleanup-standby.log`：服务、安装目录、数据目录、系统用户均清理 | ## 重要修复点 - 使用 Kingbase 官方客户端认证方式：`KINGBASE_PASSWORD` 和连接串 `password=`。 - 复制用户创建改为 SQL 文件执行，并验证 `rolreplication=t`、`rolcanlogin=t`，避免日志假成功。 - 备库 `sys_basebackup` 复用已存在复制槽，避免重跑时 `replication slot already exists`。 - 备库在 `root.sh` 注册服务后会停止临时实例，再执行 basebackup，避免端口占用。 - 单机/主库如果 `root.sh` 已经启动实例，脚本会识别已运行状态，避免重复启动导致 `kingbase.pid already exists` 被误判为失败。 - cleanup 会同步删除 `/etc/init.d/kingbased` 并注销服务。 ## 注意事项 - `--disable-firewalld` 会停止并禁用防火墙，生产环境必须按安全要求评估后使用。 - `--relax-password-policy` 会临时放宽 PAM 密码复杂度，生产环境不建议默认使用。 - `purge` 是破坏性清理，会删除数据目录和系统用户。 - 主备切换、自动故障转移、VIP、repmgr 守护进程不在当前脚本范围内；当前实现覆盖基础流复制主备安装。