KBEngine Nex

Appearance

常见错误 ​

这里收集开发期间常见的错误及解决方案。

启动与连接 ​

Q: finding dbmgr 字样一直出现，如何解决？ ​

这种情况一般是没有发现 DBMgr，很大可能是 DBMgr 初始化时出现错误。请查看 DBMgr 的启动日志（{项目资产库}/logs 下的 dbmgr.xxx.log 或 logger_dbmgr.xx.log）。常见原因：数据库连接失败（数据库名、账号密码错误等）。

Q: 启动报错 IoUringPoller::IoUringPoller: io_uring setup failed: Operation not permitted ​

此错误出现在较新的 Linux 内核（5.10+）上，原因是 kernel.io_uring_disabled 这个 sysctl 限制了 io_uring 的使用。

背景：io_uring 自 2019 年引入 Linux 内核后连续爆出大量严重 CVE 漏洞。Linux 5.10 专门添加了 kernel.io_uring_disabled 进行安全加固。内核上游默认值为 0（开启 io_uring），但部分发行版出于安全考虑，主动将其设为 2（完全禁用）。

已知默认禁用 io_uring 的环境：

  • RHEL 9+ / CentOS Stream 9+ / Rocky Linux 9+ / AlmaLinux 9+：Red Hat 生态较新版本默认设为 2
  • Fedora：较新版本同样收紧
  • Google Container-Optimized OS (COS)：显式设为 2
  • Docker 容器：某些版本的默认 seccomp profile 会拦截 io_uring 相关 syscall
  • Kubernetes：部分 K8s 发行版的安全策略限制
  • 加固过的 VPS / 云主机：服务商使用了定制安全内核

而 Ubuntu、Debian、Arch Linux 等发行版通常保持内核默认值 0，不受影响。

解决方法（在宿主机或特权容器中执行）：

bash
# 查看当前状态
sysctl kernel.io_uring_disabled

# 临时启用（重启后失效）
sudo sysctl -w kernel.io_uring_disabled=0

# 永久启用：编辑 /etc/sysctl.conf 或 /etc/sysctl.d/ 下配置文件，添加
# kernel.io_uring_disabled = 0

若为 Docker 容器环境，还需确保容器的 seccomp profile 放行 io_uring 相关 syscall（如 io_uring_setup、io_uring_enter、io_uring_register），或使用 --privileged / --security-opt seccomp=unconfined 启动容器。

注意：若运行环境有严格安全策略，请在启用 io_uring 前评估安全风险。

Q: 启动报错 BundleBroadcast::receive: failed! / Machine::findBroadcastInterface: Broadcast discovery [...] not a valid interface ​

此错误表示 Machine 进程的广播发现失败，常见日志如下：

[ERROR]: BundleBroadcast::receive: failed! It can be caused by the firewall, the broadcastaddr, etc.
        Maybe broadcastaddr is not a LAN ADDR, or the Machine process is not running.
[ERROR]: Machine::findBroadcastInterface: Broadcast discovery [0.0.0.0] not a valid interface.
[ERROR]: Machine::initNetwork: Failed to determine default broadcast interface.

原因：防火墙拦截了广播包，或 kbengine.xml 中配置的 broadcastAddr / internalInterface 与实际网络接口不匹配。

解决方法：

  1. 关闭防火墙（快速验证）：

    bash
    # Linux (firewalld)
sudo systemctl stop firewalld

# Linux (iptables)
sudo iptables -F

# Linux (ufw)
sudo ufw disable

  2. 放行端口（推荐，保持防火墙开启）：确保以下 Machine 端口在防火墙中放行（具体端口号见 kbengine.xml 各组件配置）：

    端口协议说明
    20086TCP接收广播端口
    20087TCP服务发现广播端口
    20088TCP对外提供 TCP 服务端口
    20099TCP客户端通讯端口

    此外各组件（BaseApp、CellApp、LoginApp 等）的监听端口（TCP/UDP）也需按 kbengine.xml 实际配置放行。

    以 firewalld 为例：

    bash
    sudo firewall-cmd --add-port=20086/tcp --permanent
sudo firewall-cmd --add-port=20087/tcp --permanent
sudo firewall-cmd --add-port=20088/tcp --permanent
sudo firewall-cmd --add-port=20099/tcp --permanent
sudo firewall-cmd --reload

  3. 检查配置文件：确认 kbengine.xml 中 broadcastAddr 设为局域网地址，internalInterface 设为正确的网卡接口名。

  4. 添加广播路由：若网络接口缺少广播路由，手动添加（将 eth0 替换为 internalInterface 对应的网卡名）：

    bash
    sudo /sbin/ip route add broadcast 255.255.255.255 dev eth0

MySQL 数据库 ​

Q: dbmgr 报错：mysql_errno=1045, Access denied for user 'kbe'@'localhost' ​

请进入 MySQL 命令行后输入如下指令删除匿名用户，再重启服务器：

sql
mysql> use mysql;
mysql> delete from user where user='';
mysql> FLUSH PRIVILEGES;

Q: dbmgr 报错：lower_case_table_names != 2 or 0, curr=1 ​

Windows 下 MySQL 默认为大小写不敏感，Linux 默认为敏感，引擎统一要求为敏感。

找到 MySQL 配置文件 my.ini（Windows 通常在 C:\ProgramData\MySQL\MySQL Server x.x\ 下），修改：

ini
[mysqld]
lower_case_table_names = 2

Q: MySQL 8.0+ 连接报 SSL 错误 ​

MySQL 8.0+ 默认尝试 SSL 连接，如果服务端使用自签名证书会导致认证失败。

解决方案：Nex 已内置处理，在 kbengine.xml 的 DBMgr 配置中检查是否开启了 SSL 或者配置证书即可：

Q: MySQL 9.x 下 md5 函数报错 ​

MySQL 9 移除了内置的 md5() 函数。Nex 2.7.2 及以上版本已兼容，请升级引擎。

Q: sync_item_to_db 每次启动都重复同步 UNICODE 字段 ​

utf8mb4 下 UNICODE 字段的同步 BUG 已在 Nex 2.6.3 修复，升级即可。

MariaDB ​

Q: MariaDB 连接时 RSA 公钥认证失败 ​

MariaDB C 客户端在某些版本下需要手动配置 RSA 公钥。Nex 已内置自动处理认证流程，无需显式设置 RSA 公钥。确保使用最新版本即可。

MongoDB ​

Q: MongoDB authSource 应该验证哪个数据库？ ​

应该验证对应的数据库，而不是默认的 admin。Nex 2.7.1 已修复此问题。

Q: 同时启动多个不同类型数据库，watcher 冲突 ​

这是 Nex 2.7.1 修复的 BUG，升级即可解决。

Python 脚本 ​

Q: KBEngine.MemoryStream 内存泄漏 ​

销毁时没有减少 PyGC tracing 计数，在长时间运行的服务中会累积。Nex 2.8.1 已修复。

Q: 脚本热更后部分文件未生效 ​

reloadScript 默认只更新逻辑层，且只重新加载被修改过的文件。确保保存了文件后再触发热更。

推荐使用 KBEX 插件，插件提供了快速热更入口。

编译与安装 ​

Q: 编译报错 snprintf output 109 or more bytes ​

旧版本编译器的兼容性警告，升级到最新 CMake + 编译器版本即可消除。Nex 使用 vcpkg 管理依赖，确保 vcpkg 已正确安装并联网。

Q: Linux 首次启动日志目录不存在导致 log4cxx 初始化失败 ​

Nex 2.8.2 已自动处理：初始化前自动创建日志目录。旧版本需手动创建 logs/ 目录。

Q: Debug 模式下编译第三方 Python 包无法使用 ​

KBE 以 Debug 模式编译时链接 Python Debug ABI，导致第三方包不兼容。Nex 2.8.2 已修复，Debug 下编译 Release Python。

客户端 ​

Q: Navmesh 导航后 entity 乱跳 ​

使用 navigateToDetour 时结束移动后状态同步问题。Nex 2.8.1 已修复。

Q: navigate 不绕过障碍物 / 持续触发卡顿 ​

Nex 2.7.3 已修复。如仍遇到，检查 recastnavigation 是否正确通过 vcpkg 导入。

Q: C++ SDK TCP 下时序错乱 ​

Nex 2.8.1 已修复 ObjectPool 和 TCP 时序问题。