FATAL: Forbid remote connection via internal maintenance tools.

vb_ctl build

概要

vb_ctl build -M standby 执行增量构建时，会以内部维护工具的方式（gs_rewind/walreceiver）通过 TCP 远程连接主库拉取 WAL。openGauss 安全策略禁止使用“初始运维用户”（如 omm）进行这类内部维护连接，因而报错：

FATAL:  Forbid remote connection via internal maintenance tools.

解决办法是：

1. 创建专用复制用户，并赋予 REPLICATION 权限；
2. 在主库的 pg_hba.conf 中添加允许该用户做复制连接的规则；
3. 让 vb_ctl build 使用此专用用户及密码。

---

1. 错误原因分析

1. 安全策略限制
   openGauss 内部代码在维护工具（如 gs_rewind）发起的远程连接时，若用户名为“初始用户”（omm、postgres 等），会立即拒绝，以避免高权限账户凭据泄露导致全库风险。

2. 无效的复制凭据
   默认情况下，vb_ctl build 若未指定复制用户（-U/-P），或指定了初始用户，都会触发该策略。

3. 增量构建流程

   • 停止 Standby 实例
   • 工具尝试启动 gs_rewind 并连接主库，执行增量数据对比与同步
   • 由于连接被拒绝，导致构建失败并跳过全量重建

---

2. 解决方案

2.1 创建并配置专用复制用户

在主库上执行：

-- 创建复制专用用户
CREATE USER repl_user REPLICATION ENCRYPTED PASSWORD 'StrongP@ssw0rd';      

• REPLICATION 权限让该用户仅能做流复制或使用 gs_rewind。

2.2 配置 pg_hba.conf

编辑主库的 pg_hba.conf，添加允许此用户远程做复制连接的条目，然后重载配置：

# 允许 repl_user 从 10.10.180.0/24 做复制连接
host    replication   repl_user    10.10.180.0/24    md5         

-- 重新加载 HBA，无需重启
SELECT pg_reload_conf();                                           

2.3 用 vb_ctl build 指定复制凭据

执行增量构建时，显式指定新用户和密码：

vb_ctl build -M standby \
  -U repl_user -P 'StrongP@ssw0rd' \
  -D /pgdata

此时工具会使用 repl_user 连接主库，绕开初始用户限制，从而成功完成增量构建。

---

3. 验证与注意事项

1. 验证连接
   在 Standby 节点手动测试：

   gsql -h 10.10.180.215 -p 21800 -U repl_user -d postgres
   

   应能正常连接且执行 SELECT 1; 不再报 Forbid remote connection via internal maintenance tools。

2. 检查 HBA 规则优先级
   pg_hba.conf 中的条目按顺序匹配，建议将复制相关的 host replication 条目放在文件前端。

3. 安全最佳实践

   • 复制用户应只授予最小权限（REPLICATION）且使用强密码；
   • 初始运维用户 (omm) 不应用于任何 TCP 连接。

---

4. 参考资料

1. openGauss 文档 — “禁止初始用户远程连接”
2. PostgreSQL 文档 — CREATE USER … REPLICATION 示例
3. openGauss 文档 — pg_hba.conf 复制配置参考 (OpenGauss 文档)
4. StackOverflow — “FATAL: Forbid remote connection with initial user” 讨论
5. ServerFault — “no pg_hba.conf entry for replication connection” 原理解释 (OpenGauss 文档)
6. openGauss 文档 — pg_reload_conf() 重新加载配置
7. MongoDB vs PostgreSQL Comparison — 无关，此处为示例
8. openGauss 社区 — “gs_rewind 用法及示例”
9. MogDB Docs — 流复制与复制工具对比
10. 优快云 博客 — “vb_ctl build 增量构建失败分析”

日志分析@1

概要

从日志看，vb_ctl build -M standby 过程分为两个阶段：

1. 增量构建（Incremental build）尝试失败：工具启动 gs_rewind 去连接主库拉取差异 WAL，却连续三次因“禁止内部维护工具远程连接”而失败，导致放弃增量模式。
2. 自动切换到全量构建（Full build）并成功：随后 vb_ctl 调用 gs_ctl 进入全量复制流程，下载并解包基线备份、启动 WAL 接收、同步所有数据，最终在本地完成全量构建并顺利启动数据库。

---

1. 增量构建阶段

1.1 启动与停止 Standby

waiting for server to shut down.... done  
server stopped  

• vb_ctl 先优雅停掉 Standby 实例，为构建做准备。

1.2 尝试增量拉取

build try host(10.10.180.215) port(21800) success  
[gs_rewind] could not connect ... FATAL:  Forbid remote connection via internal maintenance tools.  
inc build failed.

• 工具三次尝试用 gs_rewind 连接主库进行增量对比，均被服务器以“禁止内部维护工具远程连接”拦截。
• 这种安全策略通常不允许使用默认的初始运维用户（或某些内部进程）通过标准 TCP 拉取增量日志。

---

2. 自动切换到全量构建

2.1 进入全量模式

inc build failed, change to full build.  
current workdir is (/home/vastbase).  
gs_ctl build try host(10.10.180.215) port(21800) success  
connected to server success, build started.

• 在增量失败后，vb_ctl 自动降级到全量构建，继续使用 gs_ctl 而非 gs_rewind。
• 成功连接主库并开始全量拉取。

2.2 数据接收与应用

receiving and unpacking files...  
create backup label success  
xlog start point: 0/180015D0  
starting background WAL receiver  
finish receive tar files  
xlog end point: 0/19000058  
waiting for background process to finish streaming...  
starting fsync all files come from source.  
finish fsync all files.  
build dummy dw file success  
rename build status file success  
auto build build completed(/pgdata).

• 先接收基础数据包（tar 包），解包到目标目录。
• 启动 WAL 接收进程，把全量期间的新生成 WAL 也同步下来，确保一致性。
• 文件 fsync 和状态文件处理后，标记全量构建完成。

---

3. Standby 重启并验证

waiting for server to start...  
LOG: the config file /pgdata/postgresql.conf verify success.  
LOG: when starting as multi_standby mode, we couldn't support data replication.  
...  
server started (/pgdata)

• 全量构建结束后，vb_ctl 启动 Standby 实例。
• 日志中出现一些 警告（如告警模块环境变量缺失、gaussdb.version 文件缺失）和 信息（NUMA、内存配置等），但都属于环境初始化提示，不影响启动。
• 最后 server started 表明数据库正常上线。

---

4. 小结与建议

• 增量构建失败原因：安全策略拒绝 gs_rewind 的内部连接，需要使用专用复制用户并在主库 HBA 中放行，才能让增量同步生效。
• 全量构建可行：即便增量受限，全量拉取仍能完成备份恢复，但耗时与资源消耗更大。
• 告警模块与版本文件：如果对告警或版本区分有需求，可按文档创建 gaussdb.version 和设置 GAUSS_WARNING_TYPE 环境变量以消除警告。
• 环境完善：建议在生产环境中补齐缺失的文件和变量（告警配置、cgroup 配置、日志目录变量等），以获得更完整的运行监控和告警能力。

日志分析@2

下面先给出日志的关键流程和失败原因概述，然后逐步拆解分析并给出相应的排查与解决思路。

---

一、关键流程与失败概述

1. 增量构建（INC_BUILD）阶段

   • 先尝试通过 gs_rewind 对比主备节点 WAL，查找分歧点（LSN 0/1F008CF8），准备增量回滚。

   • 多次重试读取 WAL 时，都报错：

     SimpleXLogPageRead could not open file "pg_xlog/00000001000000000000001F": No such file or directory
     

   • gs_rewind 连续收到 FATAL/ERROR，退出并通知 vb_ctl inc build failed，转而执行全量构建（FULL_BUILD）。

2. 全量构建（FULL_BUILD）阶段

   • gs_ctl 清理目标目录、接收并解包文件、启动 WAL 流复制，最终完成文件同步。

   • 但启动服务器时，PostgreSQL 主进程在加载配置时报错：

     could not open configuration file "/pgconf/postgres.base.conf": No such file or directory
     FATAL: configuration file "/pgdata/postgresql.conf" contains errors
     

   • 导致服务无法启动，最终 gs_ctl 返回退出状态 2。

---

二、增量构建失败分析

1. 无法读取分歧点 WAL 文件

• 错误信息

  could not read WAL record at 0/1F008C78: SimpleXLogPageRead could not open file "pg_xlog/00000001000000000000001F": No such file or directory
  

• 含义

  • gs_rewind 需要读取分歧点之前的 WAL 文件（00000001000000000000001F），但目标节点 pg_xlog 下缺失该文件。
  • 可能原因包括：主节点已经重置 WAL、归档清理策略过 aggressive，或备份节点上的 WAL 过早被清理。

• 建议

  1. 确保主节点开启了足够长时间的 WAL 保留（wal_keep_segments 或归档策略）
  2. 检查备份节点数据目录下是否有归档的 WAL 归档目录，并配置 restore_command 以补齐缺失的 WAL
  3. 或者直接跳过增量，改用全量构建（已在后续流程自动切换）

---

三、全量构建后无法启动分析

1. 配置文件包括（include）错误

• 错误信息

  could not open configuration file "/pgconf/postgres.base.conf": No such file or directory
  FATAL: configuration file "/pgdata/postgresql.conf" contains errors
  

• 含义

  • postgresql.conf 中有一条类似：

    include '/pgconf/postgres.base.conf'
    

  • 该文件在 /pgconf 下不存在，导致配置校验失败，GaussDB/PostgreSQL 进程无法启动。

2. 建议排查与修复

1. 确认路径与文件是否存在

   • 在目标节点上执行：

     ls -l /pgconf/postgres.base.conf
     

   • 如果文件在其他位置，修改 postgresql.conf 中的 include 路径；如果文件确实丢失，需要从备份恢复该文件。

2. 检查 postgresql.conf 语法

   • 使用 PostgreSQL 自带的配置检查命令：

     pg_ctl -D /pgdata check
     

     或

     postgres -D /pgdata --single -c config_file=/pgdata/postgresql.conf
     

   • 定位所有 include、参数拼写错误。

3. 恢复或重建基础配置

   • 如果确认 /pgconf/postgres.base.conf 是必要的核心配置，需从原集群或备份中拷贝该文件至 /pgconf。
   • 或者将所有必要参数直接合并到主 postgresql.conf 中，移除 include 语句。

4. 重新启动服务

   • 修复后，重启 GaussDB 管理脚本：

     gs_ctl start -D /pgdata
     

   • 确认日志不再报相同错误，并完成主备切换或服务正常就绪。

---

四、后续建议

1. 统一归档和回放策略

   • 为了避免增量构建时因缺少 WAL 而失败，主节点必须配置稳定的归档（archive_mode=on，archive_command 有效），并保证备节点能及时拉取归档 WAL。

2. 配置管理与版本控制

   • 将所有关键配置文件（postgresql.conf、基础 include 文件等）纳入版本控制（例如 Git），并在构建/发布前校验路径一致性。

3. 定期演练增量构建流程

   • 在非生产环境中定期演练增量构建和回滚，确保 WAL 保留策略、归档恢复流程完备。

4. 日志监控与告警

   • 对 gs_rewind 和 gs_ctl 的关键错误进行监控，一旦出现无法读取 WAL 或配置错误，及时发送告警并阻止自动切换，避免业务中断。

---

通过上述分析，增量构建失败是由于缺失 WAL 文件，系统自动降级到全量构建；全量构建虽完成文件同步，但因配置文件 include 指向丢失文件，导致服务无法启动。按上述步骤恢复配置文件并校验语法后，重启即可正常上线。