📦️ Docker 部署

大约 4 分钟

以下是基于 KBEngine Nex使用 Docker 镜像 kbenginelab/kbengine-nex的入门使用教程。你可以基于此在本地或服务器环境快速部署一个 KBE 服务端示例。后续可根据业务需要调整。
（假设你熟悉 Docker 的基础操作；如需 Docker 基础可先查阅官方教程。）

请注意！

本机开发时，如果使用 127.0.0.1 连接Docker，Docker NAT 把流量转发到容器内部的 172.xx.xx.xx:port，对于容器来说，请求来源是 docker0 网桥，不再是你的本地 127.0.0.1，会导致所有需要回包的流程中断，建议使用容器的局域网IP地址，或使用KBEX插件，会自动获取容器IP。

1. 前置准备

确保你有 Docker Hub 镜像访问权限，并确认镜像 kbenginelab/kbengine-nex 可拉取。
准备一个用于挂载资产（assets）宿主机目录（建议单独目录以便管理），这里假设为：/home/server_assets。
准备好数据库服务（MySQL），并确保数据库网络可达，记下连接信息（IP、端口、用户名、密码、数据库名等）。
对于生产环境，你应该考虑数据持久化、日志管理、网络配置、容器编排（如 Docker Compose 或 Kubernetes）等（本教程不会提供这些需求教程，请自行完善）。

2. 安装 Docker 环境（Linux / macOS / Windows 均可）。

提示

若在 Windows/macOS，可安装 Docker Desktop。
（详见 Docker 官方文档）

例如在 Ubuntu 上：

卸载旧版本Docker

为避免冲突，需先卸载可能存在的旧版本Docker及相关组件：

sudo apt-get remove docker docker-engine docker.io containerd runc

安装依赖包

更新软件包索引并安装必要的依赖：

sudo apt-get update
sudo apt-get install ca-certificates curl gnupg lsb-release -y

添加Docker官方GPG密钥

添加Docker的GPG密钥以验证软件包签名：

sudo mkdir -p /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

配置Docker软件源

将Docker的官方软件源添加到系统中：

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update

安装Docker

安装Docker核心组件及工具：

sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y

验证安装

运行测试容器以确认Docker是否安装成功：

sudo docker run hello-world

若看到Hello from Docker!的欢迎信息，则表示安装成功。

3. 拉取镜像并试运行

拉取 KBEngine Nex Docker 镜像：

提示

如果你需要特定版本，可以替换 latest 为版本号

docker pull kbenginelab/kbengine-nex:latest

运行镜像：

  docker run -d \       
  --name kbenginex-nex-server \
  -p 20013-20025:20013-20025/tcp \
  -p 20005-20009:20005-20009/udp \
  -v /home/server_assets:/KBE/server_assets \
  kbenginelab/kbengine-nex:latest

说明：

--name kbenginex-nex-server：容器名称自定义。
-d：后台运行。
-p 20013-20025:20013-20025/tcp -p 20005-20009:20005-20009/udp：例子端口映射（实际端口请参考镜像内 KBE 配置文件）。
-v /home/server_assets:/KBE/server_assets：将宿主机目录挂载为服务端资产目录。

启动后可以查看日志以确认服务端是否启动正常：

docker logs -f kbenginex-nex-server

3. 上传 server_assets并配置相关参数

将你的游戏服务端资源文件夹 server_assets/ 上传到 /home/server_assets 下。

在 server_assets/res/server/kbengine.xml 文件中，配置好MySQL相关参数。

<root>
    <dbmgr>
        <databaseInterfaces>
            <default>
                <host> MySQL IP </host>
                <databaseName> 数据库名 </databaseName>

                <auth>
                    <username> 数据库用户名 </username>									<!-- Type: String -->
                    <password> 数据库密码 </password>							<!-- Type: String -->
                    <encrypt> true </encrypt>
                </auth>

            </default>
        </databaseInterfaces>
    </dbmgr>
</root>

4. 防火墙配置（单机/本地部署）

KBEngine 运行过程中需要开放如下端口：

LoginApp + BaseApp（客户端通信端口）:

20013-20025/tcp

BaseApp 客户端 UDP 通讯:

20005-20009/udp

Machine 服务相关端口:

20086/tcp (machine 接收广播端口)
20087/tcp (machine 服务发现广播端口)
20088/tcp (machine 对外提供 TCP 服务端口)

Linux 防火墙配置示例

提示

服务器本机防火墙可以选择关闭或者放行必要端口，二选其一即可

各系统使用的防火墙各不一样，此处以firewalld为例，其他防火墙使用方式请自行百度

关闭防火墙：

sudo systemctl stop firewalld
sudo systemctl disable firewalld

放行必要端口：

sudo firewall-cmd --add-port=20013-20025/tcp --permanent
sudo firewall-cmd --add-port=20005-20009/udp --permanent
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 --reload

5. 云服务器安全组

仅需要对外开放客户端通信端口：

必须开放：

20013-20025/tcp
20005-20009/udp

不应暴露公网的端口：

20086/tcp
20087/tcp
20088/tcp

Machine 端口仅用于服务器内部服务发现。

6. 启动服务

进入 server_assets/scripts 目录：
sh ./start_server.sh

查看日志：
tail -f logs/* -n 200

关闭服务：
sh ./stop_server.sh

部署成功标志

machine.log、baseapp.log、cellapp.log 中无报错
客户端可正常连接 loginapp