部署 FAQ

📄字数 1.8K

👁️阅读量 加载中...

本文档记录部署虚谷数据库时常见的相关问题，共有以下两个类别：

• 安全关闭数据库
• 启动失败排查

目录

• 部署 FAQ
  • 目录
  • 正文
    • 安全关闭数据库
    • 启动失败排查
      • 操作系统Page Size异常导致无法启动
      • 数据库监听端口被占用
      • 集群UDP端口冲突
      • 启动日志卡死
      • 报错程序不存在
      • Windows 单机部署报bind-udp-recv-port-0-failed
      • 其他启动异常速查表
      • 登录失败的常见原因
      • 附表-系统环境快速检查清单

正文

安全关闭数据库

前置条件：sysdba 用户登录系统库 system。

-- 普通关闭，等待会话结束
SQL> shutdown;

-- 强制关闭，自动回滚未提交事务
SQL> shutdown immediate;

注意

强制关闭可能导致大事务回滚，耗时取决于事务体量。

启动失败排查

注意

本章节使用$XUGU_HOME表示数据库服务端安装目录

操作系统Page Size异常导致无法启动

平台	检查命令	推荐值	处理方案
Linux	getconf PAGESIZE	≤ 32768	当值大于 32 KB 时，请在 $XUGU_HOME/SETUP/xugu.ini 中设置 redo_write_through = false 后重启
Windows	powershell -NoProfile -Command "[System.Environment]::SystemPageSize"	≤ 32768	同上

数据库监听端口被占用

• 症状

启动日志报 “Fatal: socket bind error! create_server_port failed”。

• 定位步骤

1. 找到数据库的侦听端口 (listen_port) 号

   grep -i listen_port $XUGU_HOME/SETUP/xugu.ini

2. 检查端口是否被占用

   • Linux lsof -i:<端口>
   • Windows netstat -ano | findstr :<端口>

• 解决方案

将 listen_port 修改为空闲端口并重启数据库。

集群UDP端口冲突

提示

端口号在报错中可能是 任意值，此处统一以 xxxx 表示。

• 症状

启动日志出现 “bind udp recv port xxxx failed”。

• 原因

• $XUGU_HOME/SETUP/cluster.ini 中配置的 接收端口(PORTS)或发送端口 已被其他进程占用。

• 发送端口 = 接收端口 + 20，由系统自动配置，同样需要空闲。

• 排查与修复

1. 打开 cluster.ini，确认集群接收端口在所有节点唯一且未被占用。
2. 修改为未占用的端口；多节点部署时各节点端口需保持一致。
3. 若单机测试无需集群，可将 cluster.ini 重命名为 cluster.ini.bak 并重启。

启动日志卡死

• 常见场景

场景	可能原因	处理建议
日志停留在 “打印配置信息”	cluster.ini 中 UDP 端口数量与 MSG_PORT_NUM 不一致	保持二者一致
启动后瞬间退出，无报错	物理内存不足或数据目录剩余空间不足	核实实际可用资源是否足够支持 xugu.ini 中缓冲区相关系统设置

报错程序不存在

• 原因一：服务端可执行文件名变化。

  • 处理办法：

    • 方法一：编辑 xugu_start.bat/xugu_start.sh，将不可用文件名替换为实际文件名。

    • 方法二：直接手动执行服务端程序。

• 原因二：可执行文件的格式与操作系统环境不匹配。

  • 处理办法：

    • 请确认下载并解压与操作系统环境匹配的安装包。

Windows 单机部署报bind-udp-recv-port-0-failed

1. 检查 $XUGU_HOME/SETUP 是否存在 cluster.ini。
2. 单机版无需集群文件；删除或重命名后重新启动即可。

其他启动异常速查表

现象	重点检查项
集群节点无法互联	cluster.ini 中的 MY_NID／NID、IP、端口顺序是否一一对应
进程直接退出，提示缺少库 libodbc.so.2	- 核心引擎 不依赖 ODBC。 - 部分管理工具或插件需 libodbc.so.2（Linux）。如缺失：yum install unixODBC 或 apt install unixodbc。
长时间无响应	- 防火墙是否放行； - 物理内存与数据目录空间是否满足 xugu.ini 中的系统参数配置

登录失败的常见原因

1. 账户／密码不匹配；
2. 登录 IP 不在 trust.ini 的可信段；
3. 账户已过期或系统当前时间不在有效期内；
4. 同一 IP 连续输错密码超过阈值（默认 3 次，锁定 3 分钟）；
5. 应用侧密码加密失败导致空密码。

附表-系统环境快速检查清单

步骤	命令／文件	目标
CPU 架构	uname -m / wmic cpu get architecture	x86_64／AARCH64
内核参数	getconf PAGESIZE	≤ 32768
端口可用性	lsof / netstat	服务端口、集群 UDP 端口均空闲
资源足够	free -h / 任务管理器	系统相关配置小于可用内存
依赖完整	ldd xugu*	无缺失库
防火墙	firewall-cmd --state	端口已放行