KBEngine Nex

Appearance

kbengine.xml 配置 ​

kbengine.xml 是项目对引擎默认配置的覆盖文件，通常位于：

text
{项目 Assets}/res/server/kbengine.xml

引擎默认值位于：

text
{引擎目录}/kbe/res/server/kbengine_defaults.xml

项目文件只需要填写需要覆盖的节点。不要复制整份默认配置后长期独立维护，否则引擎升级新增配置或调整安全默认值时，项目很容易继续使用旧值。

文件名

当前默认文件名是 kbengine_defaults.xml，末尾包含 s。早期文档中的 kbengine_default.xml 已不准确。

配置加载、继承和多环境选择方式见 配置覆盖 和 启动参数与多环境配置。

最小项目配置 ​

开发环境通常只需要覆盖数据库、管理 Token 和必要的外部地址：

xml
<root>
    <!-- 远程管理协议共享 Token；项目必须替换示例值，空值会关闭认证。 -->
    <management>
        <adminToken>replace-with-a-random-secret</adminToken>
    </management>

    <dbmgr>
        <databaseInterfaces>
            <!-- 至少需要一个名为 default 的数据库接口。 -->
            <default>
                <!-- 数据库类型支持 mysql、mongodb、postgresql。 -->
                <type>mysql</type>
                <!-- 数据库地址和端口；生产环境通常由部署配置覆盖。 -->
                <host>127.0.0.1</host>
                <port>3306</port>
                <auth>
                    <!-- 此处是明文示例，因此 encrypt 必须为 false。 -->
                    <username>kbe</username>
                    <password>replace-with-database-password</password>
                    <encrypt>false</encrypt>
                </auth>
                <!-- Entity 持久化使用的业务数据库名。 -->
                <databaseName>kbe</databaseName>
            </default>
        </databaseInterfaces>
    </dbmgr>
</root>

正式环境不应使用默认 Token、默认数据库密码或示例 Telnet 密码。敏感配置应通过受控配置文件、部署系统 Secret 或文件挂载提供，不要提交到公开仓库。

根级配置 ​

当前根级配置包括：

xml
<root>
    <!-- 服务端游戏逻辑 Tick 频率，单位 Hz。 -->
    <gameUpdateHertz>10</gameUpdateHertz>

    <!-- 组件主线程驱动 asyncio 的间隔，单位秒；0 表示关闭。 -->
    <asyncioRepeatOffset>0</asyncioRepeatOffset>

    <!-- 高频性能探针会增加计数、时钟读取和统计内存开销。 -->
    <performanceProbes>
        <enabled>false</enabled>
    </performanceProbes>

    <!-- GUIConsole、PyCluster 等管理端共用的认证 Token。 -->
    <management>
        <adminToken>replace-with-a-random-secret</adminToken>
    </management>

    <!-- 单客户端发送带宽限制，单位 bit/s。 -->
    <bitsPerSecondToClient>20000</bitsPerSecondToClient>

    <!-- 非 0 时，固定长度消息也强制携带包长。 -->
    <packetAlwaysContainLength>0</packetAlwaysContainLength>

    <!-- Entity 和 EntityDef 调试日志开关，生产环境应保持关闭。 -->
    <debugEntity>0</debugEntity>

    <publish>
        <!-- 脚本可读取的发布状态：0 开发、1 发布，也可自定义。 -->
        <state>0</state>
        <!-- 客户端登录时使用的脚本版本标识。 -->
        <script_version>0.1.0</script_version>
    </publish>

    <!-- 正常关服倒计时，单位秒。 -->
    <shutdown_time>30.0</shutdown_time>
    <!-- 关服阶段检查未完成任务的间隔，单位秒。 -->
    <shutdown_waittick>1.0</shutdown_waittick>
    <!-- 引擎回调的默认超时时间，单位秒。 -->
    <callback_timeout>300.0</callback_timeout>

    <!-- KBEngine.urlopen 的超时和低速中止策略。 -->
    <urlopen>
        <!-- 完整请求最大耗时，0 表示不限制，单位秒。 -->
        <timeout>10</timeout>
        <!-- 建立连接最大耗时，0 使用 libcurl 默认值，单位秒。 -->
        <connectTimeout>10</connectTimeout>
        <!-- 持续低速达到该时间后中止，单位秒。 -->
        <lowSpeedTime>5</lowSpeedTime>
        <!-- 低速阈值，单位 bytes/s；任一低速参数为 0 时关闭检测。 -->
        <lowSpeedLimit>30</lowSpeedLimit>
    </urlopen>

    <!-- 后台任务线程池；提高线程数会增加栈内存和后端并发压力。 -->
    <thread_pool>
        <!-- 线程任务默认超时时间，单位秒。 -->
        <timeout>300.0</timeout>
        <!-- 初始线程数、预创建线程数和最大线程数。 -->
        <init_create>1</init_create>
        <pre_create>2</pre_create>
        <max_create>8</max_create>
    </thread_pool>

    <!-- 邮件服务配置文件在 KBE_RES_PATH 中的相对路径。 -->
    <email_service_config>server/email_service_defaults.xml</email_service_config>
</root>
配置默认值说明
gameUpdateHertz10服务端游戏 Tick 频率。提高该值会增加脚本、移动、AOI 和网络调度频率，应通过压测决定。
asyncioRepeatOffset0组件主线程调度 asyncio 的间隔，单位秒。0 关闭引擎托管的 asyncio；正值最低按 0.01 秒处理。
performanceProbes.enabledfalse开启网络、Witness、Space 等高频性能探针。会增加计数、时钟读取和统计窗口开销，正式环境默认关闭。
management.adminToken示例 Token远程管理协议共享 Token。GUIConsole、PyCluster 等管理端必须使用相同值；空值会关闭认证，只适合隔离环境中的临时本机调试。
bitsPerSecondToClient20000单客户端发送带宽限制，单位 bit/s。过低会造成积压，过高会放大慢客户端和突发流量。
packetAlwaysContainLength0非零时，固定长度消息也携带包长。通常保持默认协议优化。
debugEntity0输出 Entity 创建、属性访问、初始化和 EntityDef 调试信息。高负载环境不要长期开启。
publish.state0脚本可读取的发布状态。通常 0 为开发、1 为发布，也可使用项目自定义值。
publish.script_version0.1.0客户端登录时使用的脚本版本标识。
shutdown_time30.0正常关服通知客户端的倒计时秒数。
shutdown_waittick1.0关闭阶段等待未完成任务时的检查间隔。
callback_timeout300.0引擎回调默认超时秒数。
urlopen.timeout10KBEngine.urlopen 完整请求最大耗时，单位秒；0 表示不限制。
urlopen.connectTimeout10建立连接最大耗时，单位秒；0 使用 libcurl 默认行为。
urlopen.lowSpeedTime5持续低速达到该秒数后中止；与 lowSpeedLimit 任一为 0 时关闭低速检测。
urlopen.lowSpeedLimit30低速阈值，单位 bytes/s。
thread_pool.timeout/init_create/pre_create/max_create300.0 / 1 / 2 / 8线程任务超时、初始线程数、预创建数量和最大线程数。增加线程会增加栈内存和数据库、IO 后端的并发压力。
email_service_configserver/email_service_defaults.xml邮件服务配置文件在 KBE_RES_PATH 中的路径。

数据包跟踪 ​

xml
<trace_packet>
    <!-- 0 关闭，1 十六进制，2 字符流，3 十进制。 -->
    <debug_type>0</debug_type>
    <!-- 是否写入独立的 packet 日志文件。 -->
    <use_logfile>false</use_logfile>
    <!-- 排除不需要跟踪的高频消息，可配置多个 item。 -->
    <disables>
        <item>Client::onUpdateVolatileData</item>
    </disables>
</trace_packet>
配置默认值说明
debug_type00 不输出，1 十六进制，2 字符流，3 十进制。
use_logfilefalse是否写入独立 packet 日志。
disables/item预置高频消息列表不输出的消息名称，可配置多个。

数据包跟踪会产生明显的格式化、磁盘 IO 和日志网络开销，只应短时间定位问题。

Channel 通用配置 ​

channelCommon 同时作用于内部组件通道和客户端外部通道：

xml
<channelCommon>
    <!-- 内部组件通道和外部客户端通道的空闲超时，单位秒。 -->
    <timeout>
        <internal>60.0</internal>
        <external>60.0</external>
    </timeout>

    <!-- Socket 读缓冲区，单位字节；0 使用操作系统默认值。 -->
    <readBufferSize>
        <internal>16777216</internal>
        <external>0</external>
    </readBufferSize>
    <!-- Socket 写缓冲区，单位字节；0 使用操作系统默认值。 -->
    <writeBufferSize>
        <internal>16777216</internal>
        <external>0</external>
    </writeBufferSize>

    <!-- Completion 后端每 Tick 的处理公平性预算。 -->
    <completionBudget>
        <!-- 一次主循环最多处理的完成事件数。 -->
        <maxCompletionsPerTick>1024</maxCompletionsPerTick>
        <!-- 最大处理时间，单位毫秒；0 关闭时间让步。 -->
        <maxProcessingTimeMS>8</maxProcessingTimeMS>
    </completionBudget>

    <!-- 外部通道加密类型：0 无加密、1 Blowfish、2 RSA。 -->
    <encrypt_type>1</encrypt_type>
    <!-- HTTPS、WSS 或 SSL 通道使用的证书和私钥。 -->
    <sslCertificate>key/server_cert.pem</sslCertificate>
    <sslPrivateKey>key/server_key.pem</sslPrivateKey>
</channelCommon>
配置默认值说明
timeout.internal/external60.0 / 60.0通道最后通信时间超过该秒数后判定超时。
readBufferSize.internal/external16777216 / 0Socket 读缓冲区字节数；0 使用系统默认值。
writeBufferSize.internal/external16777216 / 0Socket 写缓冲区字节数；0 使用系统默认值。
completionBudget.maxCompletionsPerTick1024一次主循环最多处理的完成事件数，最小为 1。未处理事件留到下一 Tick，不会丢失。
completionBudget.maxProcessingTimeMS8完成事件处理的时间预算上限；0 关闭按时间让步，但数量上限仍生效。
encrypt_type1外部通道加密类型：0 无加密、1 Blowfish、2 RSA。
sslCertificate/sslPrivateKeykey/server_cert.pem / key/server_key.pemHTTPS、WSS 或 SSL 通道使用的证书和私钥路径。

发送和接收窗口 ​

xml
<windowOverflow>
    <send>
        <!-- 单 Tick 发送字节数限制；0 表示不限制。 -->
        <tickSentBytes>
            <internal>0</internal>
            <external>0</external>
        </tickSentBytes>
        <!-- 发送窗口的消息数阈值。critical 用于告警或处置。 -->
        <messages>
            <critical>1024</critical>
            <internal>65535</internal>
            <external>512</external>
        </messages>
        <!-- 发送窗口的字节数限制；0 表示不限制。 -->
        <bytes>
            <internal>0</internal>
            <external>1048576</external>
        </bytes>
    </send>
    <receive>
        <!-- 接收窗口的消息数阈值。critical 不代表预分配队列大小。 -->
        <messages>
            <critical>192</critical>
            <internal>65535</internal>
            <external>256</external>
        </messages>
        <!-- 接收窗口的字节数限制；0 表示不限制。 -->
        <bytes>
            <internal>0</internal>
            <external>65535</external>
        </bytes>
    </receive>
</windowOverflow>

messages 控制消息数量，bytes 控制字节数，tickSentBytes 控制单 Tick 发送量；0 表示不限制。critical 是警告或处置阈值，不代表预分配对应大小的队列。

不要为了消除告警直接把阈值无限放大。应先确认是正常 AOI/KCP 突发、恶意客户端、脚本高频 RPC，还是主线程 Tick 堵塞造成的队列增长。

Reliable UDP/KCP ​

xml
<reliableUDP>
    <!-- 单通道接收队列的数据段上限。 -->
    <readPacketsQueueSize>
        <internal>1024</internal>
        <external>128</external>
    </readPacketsQueueSize>
    <!-- 单通道发送队列的数据段上限。 -->
    <writePacketsQueueSize>
        <internal>1024</internal>
        <external>128</external>
    </writePacketsQueueSize>
    <!-- 外部单通道自有发送 payload 上限，单位字节；0 仅使用段数限制。 -->
    <writeQueueMaxBytes>
        <external>65536</external>
    </writeQueueMaxBytes>
    <!-- 一次 flush 最多输出的数据段数；0 表示不限制。 -->
    <flushSegmentsBudget>
        <internal>0</internal>
        <external>4</external>
    </flushSegmentsBudget>
    <!-- 达到高水位时暂停 Witness 位置和方向生产，回落到低水位后恢复。 -->
    <volatileBackpressure>
        <highSegments>128</highSegments>
        <lowSegments>32</lowSegments>
        <highBytes>32768</highBytes>
        <lowBytes>8192</lowBytes>
    </volatileBackpressure>
    <!-- KCP 更新周期和最小重传超时，单位毫秒。 -->
    <tickInterval>10</tickInterval>
    <minRTO>50</minRTO>
    <!-- 快速重传前允许跳过的 ACK 次数。 -->
    <missAcksResend>2</missAcksResend>
    <!-- KCP MTU；0 使用实现默认值。 -->
    <mtu>0</mtu>
    <!-- 是否启用拥塞控制和低延迟模式。 -->
    <congestionControl>false</congestionControl>
    <nodelay>true</nodelay>
</reliableUDP>
配置默认值说明
readPacketsQueueSize.internal/external1024 / 128单通道接收 UDP 包队列的段数限制。
writePacketsQueueSize.internal/external1024 / 128单通道发送队列的段数限制。
writeQueueMaxBytes.external65536外部 KCP 单通道自有发送 payload 的字节硬上限；0 只保留段数限制。
flushSegmentsBudget.internal/external0 / 4一次 flush 最多输出的数据段数，包含首次发送和重传；ACK 和窗口探测不受此限制，0 表示无限制。
volatileBackpressure.highSegments/lowSegments128 / 32外部 KCP 发送队列的数据段高低水位。
volatileBackpressure.highBytes/lowBytes32768 / 8192外部 KCP 发送 payload 的字节高低水位。达到任一高水位后暂停对应 Witness 的位置和方向生产，两项都降低到低水位后恢复；高水位为 0 时关闭对应判断。
tickInterval10KCP 更新周期，单位毫秒。
minRTO50最小重传超时，单位毫秒。
missAcksResend2快速重传使用的 ACK 跳过次数。
mtu0KCP MTU；0 使用实现默认值。必须结合公网路径 MTU 验证，避免 IP 分片。
congestionControlfalse是否启用 KCP 拥塞控制。
nodelaytrue是否启用 KCP 低延迟模式。

这些参数会同时影响延迟、CPU、重传、内存和网络突发。正式修改前应在接近真实丢包率、RTT、同屏 Entity 数量和客户端数量的环境中压测。

组件通用字段 ​

多个组件支持以下通用节点，具体是否存在以 kbengine_defaults.xml 为准：

配置默认值说明
entryScriptFilekbemainPython 入口模块。
internalInterface空组件内部通信网卡、IP 或接口。多网卡部署应显式设置。
externalInterface空面向客户端的外部接口。
externalAddress空下发给客户端的公网 IP 或域名，适用于 NAT、端口映射和负载均衡入口。引擎不会验证其可达性。
SOMAXCONN通常为 511TCP listen backlog，最终还受操作系统上限约束。
telnet_service.port按组件配置Telnet 调试端口，占用时会继续尝试后续端口。
telnet_service.passwordpwd123456Telnet 密码。正式环境必须修改并限制网络访问。
telnet_service.default_layerpython默认命令层。
profiles.cprofile/pyprofile/eventprofile/networkprofilefalse组件启动时是否立即开始相应的性能采集。

Telnet 和内部组件接口不应直接暴露到公网。

LoginApp ​

xml
<loginapp>
    <!-- Python 入口模块。 -->
    <entryScriptFile>kbemain</entryScriptFile>
    <!-- 内部组件通信和外部客户端监听接口；空值表示自动选择。 -->
    <internalInterface></internalInterface>
    <externalInterface></externalInterface>
    <!-- 下发给客户端的公网 IP 或域名；NAT 环境可显式填写。 -->
    <externalAddress></externalAddress>

    <!-- 登录 TCP 监听端口范围；max=0 时从 min 开始选择可用端口。 -->
    <externalTcpPorts_min>20013</externalTcpPorts_min>
    <externalTcpPorts_max>0</externalTcpPorts_max>
    <!-- -1 表示不创建 UDP 登录端点；登录阶段始终使用 TCP。 -->
    <externalUdpPorts_min>-1</externalUdpPorts_min>
    <externalUdpPorts_max>-1</externalUdpPorts_max>

    <!-- 登录信息加密：0 无加密、1 Blowfish、2 RSA。 -->
    <encrypt_login>2</encrypt_login>
    <!-- TCP listen backlog，最终还受操作系统上限约束。 -->
    <SOMAXCONN>511</SOMAXCONN>
    <!-- 账号类型：1 普通、2 Email、3 智能识别。 -->
    <account_type>3</account_type>
    <!-- 认证、激活和密码重置等 HTTP 回调服务地址。 -->
    <http_cbhost>localhost</http_cbhost>
    <http_cbport>21103</http_cbport>
</loginapp>
配置默认值说明
externalTcpPorts_min/max20013 / 0LoginApp 对客户端监听的 TCP 端口范围。max=0 表示从最小值开始选择可用端口。
externalUdpPorts_min/max-1 / -1-1 表示 LoginApp 不提供 UDP 登录端口。登录阶段始终使用 TCP。
encrypt_login2登录信息加密方式：0 无加密、1 Blowfish、2 RSA。
account_type31 普通账号、2 Email 账号、3 智能识别账号。
http_cbhost/http_cbportlocalhost / 21103认证、激活和密码重置等 HTTP 回调服务地址；通常只由首个 LoginApp 开启。

早期文档中的 externalPorts_min/max 已被 TCP/UDP 独立端口范围替代。

BaseApp ​

xml
<baseapp>
    <!-- 客户端 TCP 游戏连接端口范围。 -->
    <externalTcpPorts_min>20015</externalTcpPorts_min>
    <externalTcpPorts_max>20019</externalTcpPorts_max>
    <!-- 客户端 KCP 游戏连接使用的 UDP 端口范围。 -->
    <externalUdpPorts_min>20005</externalUdpPorts_min>
    <externalUdpPorts_max>20009</externalUdpPorts_max>

    <!-- Entity 自动归档和自动备份周期，单位秒。 -->
    <archivePeriod>300</archivePeriod>
    <backupPeriod>300</backupPeriod>
    <!-- 是否保留已从当前 EntityDef 删除的旧备份属性。 -->
    <backUpUndefinedProperties>0</backUpUndefinedProperties>
    <!-- 负载均衡使用的平滑系数。 -->
    <loadSmoothingBias>0.01</loadSmoothingBias>

    <!-- 资源下载总带宽和单客户端带宽限制，单位 bit/s。 -->
    <downloadStreaming>
        <bitsPerSecondTotal>1000000</bitsPerSecondTotal>
        <bitsPerSecondPerClient>100000</bitsPerSecondPerClient>
    </downloadStreaming>

    <!-- 本地 Entity ID 资源低于该值时申请新批次。 -->
    <ids>
        <criticallyLowSize>1000</criticallyLowSize>
    </ids>
    <!-- 灾难恢复时每批恢复的 Entity 数量。 -->
    <entityRestoreSize>32</entityRestoreSize>

    <!-- 正常关服阶段每秒销毁的 Base Entity 数量。 -->
    <shutdown>
        <perSecsDestroyEntitySize>100</perSecsDestroyEntitySize>
    </shutdown>

    <!-- 小资源缓存池：准入大小 KB、空闲超时秒数和检查周期秒数。 -->
    <respool>
        <buffer_size>1024</buffer_size>
        <timeout>600</timeout>
        <checktick>60</checktick>
    </respool>
</baseapp>
配置默认值说明
externalTcpPorts_min/max20015 / 20019客户端 TCP 游戏连接端口范围。
externalUdpPorts_min/max20005 / 20009客户端 KCP 游戏连接使用的 UDP 端口范围。
archivePeriod300自动归档周期，单位秒。缩短周期会增加脚本回调和数据库写入压力。
backupPeriod300自动备份周期，单位秒。缩短周期会增加 BaseApp 与 CellApp 间的消息和内存复制。
backUpUndefinedProperties0是否保留 EntityDef 中已经不存在的备份属性，仅在迁移旧备份数据时启用。
loadSmoothingBias0.01负载平滑系数。
downloadStreaming.bitsPerSecondTotal1000000BaseApp 资源下载总带宽限制，单位 bit/s。
downloadStreaming.bitsPerSecondPerClient100000单客户端资源下载带宽限制，单位 bit/s。
ids.criticallyLowSize1000Entity ID 资源低于该数量时申请新批次。
entityRestoreSize32灾难恢复时每批恢复的 Entity 数量。批量过大会造成单 Tick CPU、内存和数据库突发。
shutdown.perSecsDestroyEntitySize100正常关闭阶段每秒销毁的 Base Entity 数量。
respool.buffer_size1024可进入资源池的最大单资源大小，单位 KB。
respool.timeout600资源在池中超过该秒数未访问后销毁。
respool.checktick60资源池过期检查周期，单位秒。

CellApp ​

xml
<cellapp>
    <!-- 默认 View 半径及离开 View 时的滞回区域。 -->
    <defaultViewRadius>
        <radius>80.0</radius>
        <hysteresisArea>5.0</hysteresisArea>
    </defaultViewRadius>

    <!-- Entity ID、客户端属性和方法 UID 的紧凑别名协议开关。 -->
    <aliasEntityID>true</aliasEntityID>
    <entitydefAliasID>true</entitydefAliasID>

    <!-- 本地 Entity ID 资源低于该值时申请新批次。 -->
    <ids>
        <criticallyLowSize>1000</criticallyLowSize>
    </ids>

    <!-- CellApp 负载平滑系数。 -->
    <loadSmoothingBias>0.01</loadSmoothingBias>
    <!-- Cell 边界 Ghost 距离、单次处理上限和更新频率 Hz。 -->
    <ghostDistance>500.0</ghostDistance>
    <ghostingMaxPerCheck>64</ghostingMaxPerCheck>
    <ghostUpdateHertz>30</ghostUpdateHertz>

    <coordinate_system>
        <!-- 关闭后 View、Trap、Move 等空间能力不可用。 -->
        <enable>true</enable>
        <!-- 是否把 Y 轴纳入范围管理；启用会增加空间索引开销。 -->
        <rangemgr_y>false</rangemgr_y>
        <!-- 停止移动后继续发送的位置更新次数；0 表示持续发送。 -->
        <entity_posdir_additional_updates>2</entity_posdir_additional_updates>

        <!-- 单 Witness 和单 CellApp 每 Tick 的 AOI 发送预算；0 表示不限制。 -->
        <witness_volatile_bytes_per_tick>512</witness_volatile_bytes_per_tick>
        <witness_total_bytes_per_tick>2048</witness_total_bytes_per_tick>
        <witness_global_bytes_per_tick>1048576</witness_global_bytes_per_tick>
        <witness_global_updates_per_tick>1024</witness_global_updates_per_tick>

        <!-- 高密度 View 中按距离降低位置和方向刷新频率。 -->
        <witness_volatile_lod>
            <enable>true</enable>
            <!-- View 数量低于该值时保持每 Tick 更新。 -->
            <minimumViewEntities>32</minimumViewEntities>
            <!-- 近距离每 Tick 更新，中距离和远距离按下方 Tick 间隔更新。 -->
            <nearDistance>20</nearDistance>
            <mediumDistance>50</mediumDistance>
            <mediumIntervalTicks>2</mediumIntervalTicks>
            <farIntervalTicks>4</farIntervalTicks>
        </witness_volatile_lod>

        <!-- 位置协议：0 高精度、1 紧凑、2 按同屏数量智能选择。 -->
        <entity_posdir_updates>
            <type>2</type>
            <smartThreshold>10</smartThreshold>
        </entity_posdir_updates>
    </coordinate_system>

    <!-- 不再被观察后，延迟恢复未观察状态的秒数。 -->
    <witness>
        <timeout>15</timeout>
    </witness>
</cellapp>

View、Ghost 和坐标系统 ​

配置默认值说明
defaultViewRadius.radius80.0默认 View 半径，脚本可通过 Entity.setViewRadius 修改。
defaultViewRadius.hysteresisArea5.0离开 View 使用的滞回区域，减少边界抖动。
aliasEntityIDtrueView 内 Entity 少于 255 个时使用 1 字节 Entity ID 别名协议。
entitydefAliasIDtrue客户端属性或方法数量不超过 255 时使用 1 字节 UID 别名协议。
ids.criticallyLowSize1000Entity ID 资源低于该数量时申请新批次。
loadSmoothingBias0.01负载平滑系数。
ghostDistance500.0Cell 边界 Ghost 区域距离。增大会提高跨 Cell 内存和消息量。
ghostingMaxPerCheck64单次 Ghost 检查处理上限。批量过大会增加单 Tick 工作。
ghostUpdateHertz30Ghost 更新频率，单位 Hz。
coordinate_system.enabletrue关闭后 View、Trap 和移动等坐标系统能力不可用。
coordinate_system.rangemgr_yfalse是否把 Y 轴纳入范围管理。会增加空间索引和范围计算成本。
entity_posdir_additional_updates2位置停止变化后继续发送的更新次数；0 表示持续发送。
entity_posdir_updates.type20 高精度、1 紧凑位置协议、2 按同屏数量智能选择。紧凑和智能模式的 View 范围限制在 500 以内。
entity_posdir_updates.smartThreshold10type=2 时，同屏数量超过该值后切换到紧凑协议。
witness.timeout15Entity 不再被任何 Witness 观察后，延迟恢复未观察状态的秒数。

Witness 发送预算 ​

配置默认值说明
witness_volatile_bytes_per_tick512单个 Witness 每 Tick 的位置/方向字节预算。结构消息不受此限制；0 关闭预算。
witness_total_bytes_per_tick2048单个 Witness 每 Tick 的全部 AOI 软预算，包括 Enter、Leave、属性和 Volatile。完整消息不会被截断；0 不限制。
witness_global_bytes_per_tick1048576单个 CellApp 每 Tick 的 Witness 总发送目标，按活跃 Witness 计算公平份额；0 不限制。
witness_global_updates_per_tick1024单个 CellApp 每 Tick 最多准入的 Witness 数量，窗口跨 Tick 轮转；0 不限制。

预算过低会增加 AOI 数据延迟，预算过高会导致单 Tick 序列化和网络突发。调优时应同时观察 Tick 延迟、积压、客户端视图收敛时间和总带宽。

Witness Volatile LOD ​

witness_volatile_lod 是 CellApp 底层位置/方向刷新频率优化，不是 EntityDef 的属性 DetailLevel。Enter、Leave、普通属性和方法消息不受该 LOD 频率影响。

配置默认值说明
enabletrue是否启用位置和方向刷新频率 LOD；关闭后恢复每 Tick 刷新。
minimumViewEntities32View 内 Entity 少于该数量时，不启用距离降频，每 Tick 更新。
nearDistance20距离不超过该值时每 Tick 更新。
mediumDistance50nearDistance 到该距离使用 mediumIntervalTicks；该值不会小于 nearDistance。
mediumIntervalTicks2中距离位置和方向更新间隔，限制在 1 - 64 Tick。
farIntervalTicks4超过 mediumDistance 后的更新间隔，限制在 1 - 64 Tick。

CellAppMgr 和 BaseAppMgr ​

xml
<cellappmgr>
    <!-- TCP listen backlog 和内部组件通信接口。 -->
    <SOMAXCONN>511</SOMAXCONN>
    <internalInterface></internalInterface>
    <!-- Space 数量最大偏差；0 关闭硬约束，只使用负载评分。 -->
    <spaceAllocationMaxSkew>2</spaceAllocationMaxSkew>
    <!-- Witness pending/active 压力评分权重；0 关闭该项评分。 -->
    <witnessPendingPressureWeight>1.0</witnessPendingPressureWeight>
</cellappmgr>

<baseappmgr>
    <!-- TCP listen backlog 和内部组件通信接口。 -->
    <SOMAXCONN>511</SOMAXCONN>
    <internalInterface></internalInterface>
</baseappmgr>
配置默认值说明
cellappmgr.SOMAXCONN511CellAppMgr 的 TCP listen backlog。
cellappmgr.internalInterface空CellAppMgr 内部通信接口。
spaceAllocationMaxSkew2自动分配 Space 时，各 CellApp 已确认加待确认 Space 数量允许的最大差值。0 关闭硬约束，只使用负载评分。
witnessPendingPressureWeight1.0新 Space 分配时 Witness pending/active 压力的评分权重；负数按 0 处理，0 关闭该项评分。
baseappmgr.SOMAXCONN511BaseAppMgr 的 TCP listen backlog。
baseappmgr.internalInterface空BaseAppMgr 内部通信接口。

这两个参数影响 Space 放置和 CellApp 负载均衡。不要只看平均 CPU，应同时观察 Entity 数量、Space 数量、Witness 活跃量和待处理 AOI 工作。

DBMgr ​

xml
<dbmgr>
    <!-- Python 入口模块。 -->
    <entryScriptFile>kbemain</entryScriptFile>
    <!-- 数据库读写调试日志，生产环境应保持关闭。 -->
    <debug>false</debug>
    <!-- 是否允许多个服务组共享同一数据库。 -->
    <shareDB>false</shareDB>
    <!-- 是否允许客户端使用空 EntityDef 摘要；不应作为协议兼容绕过手段。 -->
    <allowEmptyDigest>false</allowEmptyDigest>
    <!-- DBMgr 内部组件通信接口；空值表示自动选择。 -->
    <internalInterface></internalInterface>

    <!-- 仅过滤脚本 executeRawDatabaseCommand 提交的危险原始命令。 -->
    <rawDatabaseCommandBlacklist>
        <enable>false</enable>
        <!-- 各数据库后端使用独立、逗号分隔且不区分大小写的规则。 -->
        <mysql>delete,drop,truncate,alter</mysql>
        <mongodb>drop,dropDatabase,deleteMany</mongodb>
        <postgresql>delete,drop,truncate,alter</postgresql>
    </rawDatabaseCommandBlacklist>

    <!-- 账号及外部服务请求是否转发到 Interfaces。 -->
    <InterfacesServiceAddr>
        <enable>true</enable>
        <!-- 自动把根级 interfaces 地址加入地址池。 -->
        <addDefaultAddress>true</addDefaultAddress>
    </InterfacesServiceAddr>

    <databaseInterfaces>
        <!-- 至少需要一个 default 接口，也可增加其他命名数据库接口。 -->
        <default>
            <!-- true 表示纯业务数据库，引擎不会创建 Entity 表。 -->
            <pure>false</pure>
            <!-- 支持 mysql、mongodb、postgresql。 -->
            <type>mysql</type>
            <!-- port=0 时使用对应数据库驱动的默认端口。 -->
            <host>127.0.0.1</host>
            <port>0</port>
            <!-- Default 使用后端默认 ID 策略；UUID64 统一由引擎生成。 -->
            <idType>Default</idType>
            <!-- 新建 MySQL 自增表的起始 ID，仅在 Default 模式生效。 -->
            <autoIncrementInit>1</autoIncrementInit>

            <auth>
                <!-- 正式环境必须通过受控配置或 Secret 覆盖凭据。 -->
                <username>kbe</username>
                <password>replace-with-database-password</password>
                <!-- MongoDB 认证数据库；空值回退到 databaseName。 -->
                <authSource></authSource>
                <!-- 此示例密码为明文，因此设置为 false。 -->
                <encrypt>false</encrypt>
                <MySQL>
                    <!-- 是否要求 TLS，以及是否验证服务器证书。 -->
                    <ssl>false</ssl>
                    <sslVerifyServerCert>true</sslVerifyServerCert>
                    <!-- 可选 CA、客户端证书和私钥路径。 -->
                    <sslCa></sslCa>
                    <sslCert></sslCert>
                    <sslKey></sslKey>
                </MySQL>
            </auth>

            <!-- 业务数据库名和连接池大小。 -->
            <databaseName>kbe</databaseName>
            <numConnections>5</numConnections>
            <!-- MySQL 字符集和排序规则。 -->
            <unicodeString>
                <characterSet>utf8mb4</characterSet>
                <collation>utf8mb4_bin</collation>
            </unicodeString>
        </default>
    </databaseInterfaces>

    <!-- 本地 Entity ID 资源低于该数量时向管理器申请新范围。 -->
    <ids>
        <increasing_range>2000</increasing_range>
    </ids>
</dbmgr>

DBMgr 通用项 ​

配置默认值说明
debugfalse输出数据库读写调试信息，正式环境不应长期开启。
shareDBfalse是否允许多个服务组共享数据库。启用前必须明确账号、Entity ID、表结构和服务组隔离策略。
allowEmptyDigestfalse是否允许客户端使用空 EntityDef 摘要。不要作为绕过协议不一致的常规手段。
rawDatabaseCommandBlacklist.enablefalse拦截脚本直接提交到 executeRawDatabaseCommand 的危险原始命令。
rawDatabaseCommandBlacklist.mysql/mongodb/postgresql预置黑名单逗号分隔、不区分大小写的后端独立规则。它不替代数据库账号权限和审计。
InterfacesServiceAddr.enabletrue是否把相关账号及外部服务请求转发到 Interfaces。
InterfacesServiceAddr.addDefaultAddresstrue是否自动把根级 <interfaces> 地址加入地址池；也可以配置额外 item/host/port。
ids.increasing_range2000本地 Entity ID 资源低于该数量时向管理器申请新范围。

数据库接口 ​

每个 <databaseInterfaces> 子节点代表一个命名数据库接口，至少需要 default：

配置默认值说明
purefalsetrue 时作为纯数据库连接，引擎不创建 Entity 表。
typemysql当前支持 mysql、mongodb、postgresql。Redis 已从当前数据库后端列表移除。
host/port127.0.0.1 / 0数据库地址和端口。port=0 使用对应驱动默认端口。
idTypeDefaultDefault：MySQL/PostgreSQL 使用数据库生成 ID，MongoDB 使用 UUID64；UUID64：所有后端统一由引擎生成。
autoIncrementInit1新建 MySQL 自增表的起始 ID，只在 Default 模式生效，必须是正整数。不会自动迁移已有表。
auth.username/passwordkbe / pwd123456数据库凭据，正式环境必须覆盖。
auth.encrypttrue密码是否为引擎约定的 RSA 密文。填写明文密码时必须设为 false。
auth.authSource空MongoDB 独立认证数据库；为空时回退到业务 databaseName。
databaseNamekbe业务数据库名。
numConnections5连接池大小。提高它会增加数据库并发、内存和服务器连接数。
unicodeString.characterSet/collationutf8mb4 / utf8mb4_binMySQL 字符集和排序规则。

MongoDB 还支持在接口节点配置 replicaSet，指定后驱动从种子节点发现副本集并跟随主节点切换。

MySQL TLS ​

配置默认值说明
auth.MySQL.sslfalse启用并要求 MySQL TLS。
auth.MySQL.sslVerifyServerCerttrue验证服务器证书，正式环境应保持 true。
auth.MySQL.sslCa空CA 文件路径。
auth.MySQL.sslCert/sslKey空可选客户端证书和私钥。

证书相对路径从 KBE_RES_PATH 解析。开启 TLS 前应确认服务端证书名称、CA 链和数据库账号权限。

账号系统 ​

配置默认值说明
accountEntityScriptTypeAccount登录成功后使用的账号 Entity 类型名。
accountDefaultFlags0新账号默认标记，可按位组合。
accountDefaultDeadline0新账号有效期秒数，0 表示不额外设置期限。
account_resetPassword.enablefalse是否开放密码重置；启用时还需配置 Interfaces 和邮件服务。
account_registration.enablefalse是否开放注册。
account_registration.loginAutoCreatefalse合法登录但游戏数据库不存在账号时是否自动创建。

Interfaces ​

xml
<interfaces>
    <!-- Python 入口模块。 -->
    <entryScriptFile>kbemain</entryScriptFile>
    <!-- Interfaces 服务地址。 -->
    <host>localhost</host>
    <!-- 监听端口范围。 -->
    <port_min>30099</port_min>
    <port_max>30199</port_max>
    <!-- 订单或外部请求上下文超时，单位秒。 -->
    <orders_timeout>3600</orders_timeout>
    <!-- TCP listen backlog，最终还受操作系统上限约束。 -->
    <SOMAXCONN>511</SOMAXCONN>
</interfaces>
配置默认值说明
hostlocalhostInterfaces 服务地址。
port_min/port_max30099 / 30199监听端口范围。早期文档中的单一 <port> 已不准确。
orders_timeout3600订单或外部请求上下文的超时秒数。

Machine ​

xml
<machine>
    <!-- 工具和管理连接使用的 TCP 端口范围；max=0 时从 min 开始选择。 -->
    <externalTcpPorts_min>20099</externalTcpPorts_min>
    <externalTcpPorts_max>0</externalTcpPorts_max>
    <!-- UDP 广播无法跨主机发现组件时，显式填写探测地址。 -->
    <addresses>
        <item>192.168.10.18</item>
    </addresses>
</machine>
配置默认值说明
externalTcpPorts_min/max20099 / 0工具和管理连接使用的 TCP 端口范围；max=0 时从最小端口开始选择可用端口。
addresses/item空UDP 广播无法跨主机发现组件时，显式填写需要探测的主机地址，可配置多个。

当前版本不再读取 Machine 的 externalUdpPorts_min/max。从旧 Nex 配置迁移时应删除这两个无效节点。

Bots ​

xml
<bots>
    <!-- Python 入口模块和内部通信接口。 -->
    <entryScriptFile>kbemain</entryScriptFile>
    <internalInterface></internalInterface>
    <!-- BaseApp 下发公网地址时，是否强制 Bots 使用内网地址。 -->
    <forceInternalLogin>false</forceInternalLogin>
    <!-- 登录后的游戏连接协议；LoginApp 登录阶段始终使用 TCP。 -->
    <transport>kcp</transport>
    <!-- KCP 建立失败时是否允许回退 TCP。 -->
    <allowTcpFallback>true</allowTcpFallback>

    <!-- LoginApp 地址和 TCP 端口范围；max=0 时从 min 开始选择。 -->
    <host>localhost</host>
    <port_min>20013</port_min>
    <port_max>0</port_max>
    <!-- Entity 初始化时是否触发属性 set_* 回调。 -->
    <isOnInitCallPropertysSetMethods>true</isOnInitCallPropertysSetMethods>

    <!-- 启动后自动创建的总数、批次间隔秒数和每批数量。 -->
    <defaultAddBots>
        <totalCount>10</totalCount>
        <tickTime>0.1</tickTime>
        <tickCount>5</tickCount>
    </defaultAddBots>

    <!-- 压测账号生成规则和登录密码；必须替换示例密码。 -->
    <account_infos>
        <account_name_prefix>bot_</account_name_prefix>
        <!-- 0 使用随机递增策略，否则按配置值递增。 -->
        <account_name_suffix_inc>0</account_name_suffix_inc>
        <account_password>replace-with-bot-password</account_password>
    </account_infos>
</bots>
配置默认值说明
forceInternalLoginfalseBaseApp 对外下发公网地址时，Bots 是否强制使用内网地址。
transportkcp登录成功后的 BaseApp 游戏连接使用 kcp 或 tcp；LoginApp 登录阶段始终使用 TCP。
allowTcpFallbacktrueKCP 建立失败时是否允许回退 TCP。纯 KCP 压测应设为 false，避免样本混合。
host/port_min/port_maxlocalhost / 20013 / 0LoginApp 地址和端口范围。早期单一 <port> 写法已不准确。
isOnInitCallPropertysSetMethodstrue客户端 Entity 初始化时是否触发属性 set_* 回调。
defaultAddBots.totalCount/tickTime/tickCount10 / 0.1 / 5启动后自动创建总数、批次间隔秒数和每批数量。批量过大会形成登录、数据库、AOI 和 Logger 峰值。
account_infos.account_name_prefixbot_机器人账号前缀。
account_infos.account_name_suffix_inc0账号后缀增量；0 使用随机递增策略。
account_infos.account_passwordpwd123456机器人账号密码，压测环境必须替换默认值。

Bots 会产生真实的登录、AOI、RPC、数据库和 Logger 压力。压测配置应固定连接协议、账号规模和日志级别。

Logger ​

xml
<logger>
    <!-- Python 入口模块和内部通信接口。 -->
    <entryScriptFile>kbemain</entryScriptFile>
    <internalInterface></internalInterface>
    <!-- 单个组件一个 Tick 最多缓存的日志数量。 -->
    <tick_max_buffered_logs>131070</tick_max_buffered_logs>
    <!-- 单 Tick 同步给 Logger 的日志数量；0 表示全部同步。 -->
    <tick_sync_logs>0</tick_sync_logs>
    <!-- TCP listen backlog。 -->
    <SOMAXCONN>511</SOMAXCONN>
</logger>
配置默认值说明
tick_max_buffered_logs131070单个组件进程一个 Tick 最多缓存的日志数量。提高它会扩大组件内存和突发日志量。
tick_sync_logs0一个 Tick 同步给 Logger 的日志数量，0 表示同步全部。设置上限可平滑流量，但会增加组件侧积压。

过高日志量会增加组件内存、内部网络和 Logger 磁盘 IO。生产环境应从日志级别和高频日志源头治理，而不是只提高缓冲上限。

自定义业务配置 ​

customCfg 只供服务端 Python 逻辑读取：

xml
<customCfg>
    <!-- name 是查询键，type 决定 Python 返回类型，desc 仅供维护者阅读。 -->
    <param name="battle.maxPlayers" type="int" desc="单场人数">100</param>
    <param name="battle.enableRank" type="bool">true</param>
    <param name="battle.speedScale" type="float">1.0</param>
    <param name="battle.welcome" type="string">hello</param>
    <!-- dict 和 list 使用 Python 字面量，由 ast.literal_eval 安全解析。 -->
    <param name="battle.dropRates" type="dict">{"gold": 1.2, "item": 0.05}</param>
    <param name="battle.spawnPoints" type="list">[1, 2, 3]</param>
</customCfg>

Python 中读取：

python
max_players = KBEngine.getCustomCfg("battle.maxPlayers", 100)
drop_rates = KBEngine.getCustomCfg("battle.dropRates", {})
字段默认值说明
name必填查询键，建议使用分组命名。
typestring支持 bool、int、float、string、dict、list。
desc空仅用于维护说明，不进入运行时结果。
节点文本空字符串dict/list 使用 Python 字面量，并通过 ast.literal_eval 安全解析。配置存在时，返回类型由 type 决定，不根据调用时的默认值推断。

配置不存在时，传入默认值则返回默认值，否则返回 None。

customCfg 是只读配置入口，不适合保存运行时状态，也不应替代数据库、配置中心或 Secret 管理。

与 KBEngine-Nex 配置的差异 ​

本节的“旧版”专指本机 D:\KBELAB\kbengine\KBEngine-Nex，不是更早的 KBEngine 官方版本或旧文档。对比来源如下：

版本对比文件
旧 NexD:\KBELAB\kbengine\KBEngine-Nex\kbe\res\server\kbengine_defaults.xml
当前项目D:\KBELAB\kbengine\kbengine1x\kbe\res\server\kbengine_defaults.xml

对比按完整 XML 叶子路径进行，重复的 item 节点按同一路径归并；同时结合两边 ServerConfig 的实际解析代码确认移除项是否仍然生效。

统计项旧 Nex当前版本差异
唯一叶子配置路径207230+23
当前版本新增路径-25+25
当前版本移除路径2--2
同路径默认值变化-55

当前版本新增配置 ​

分组当前版本新增的完整配置路径默认值
性能探针performanceProbes.enabledfalse
管理认证management.adminToken示例 Token，项目必须覆盖
KCP 队列channelCommon.reliableUDP.writeQueueMaxBytes.external65536
KCP flushchannelCommon.reliableUDP.flushSegmentsBudget.internal0
KCP flushchannelCommon.reliableUDP.flushSegmentsBudget.external4
KCP 背压channelCommon.reliableUDP.volatileBackpressure.highSegments128
KCP 背压channelCommon.reliableUDP.volatileBackpressure.lowSegments32
KCP 背压channelCommon.reliableUDP.volatileBackpressure.highBytes32768
KCP 背压channelCommon.reliableUDP.volatileBackpressure.lowBytes8192
MongoDBdbmgr.databaseInterfaces.default.auth.authSource空，回退到业务数据库名
MySQL TLSdbmgr.databaseInterfaces.default.auth.MySQL.sslVerifyServerCerttrue
Witness 预算cellapp.coordinate_system.witness_volatile_bytes_per_tick512
Witness 预算cellapp.coordinate_system.witness_total_bytes_per_tick2048
Witness 预算cellapp.coordinate_system.witness_global_bytes_per_tick1048576
Witness 预算cellapp.coordinate_system.witness_global_updates_per_tick1024
Volatile LODcellapp.coordinate_system.witness_volatile_lod.enabletrue
Volatile LODcellapp.coordinate_system.witness_volatile_lod.minimumViewEntities32
Volatile LODcellapp.coordinate_system.witness_volatile_lod.nearDistance20
Volatile LODcellapp.coordinate_system.witness_volatile_lod.mediumDistance50
Volatile LODcellapp.coordinate_system.witness_volatile_lod.mediumIntervalTicks2
Volatile LODcellapp.coordinate_system.witness_volatile_lod.farIntervalTicks4
Space 分配cellappmgr.spaceAllocationMaxSkew2
Space 分配cellappmgr.witnessPendingPressureWeight1.0
Bots 协议bots.transportkcp
Bots 回退bots.allowTcpFallbacktrue

当前版本移除配置 ​

旧 Nex 配置路径旧 Nex 默认值当前状态
machine.externalUdpPorts_min0已从默认 XML 和 Machine 配置解析中移除
machine.externalUdpPorts_max0已从默认 XML 和 Machine 配置解析中移除

Machine 的工具管理入口只保留 TCP 端口范围。旧项目即使继续保留这两个 XML 节点，当前版本也不会读取它们。

默认值变化 ​

配置老 Nex当前版本影响
channelCommon.completionBudget.maxProcessingTimeMS58单次主循环允许 completion 处理更久，减少高 IO 下跨 Tick 积压，但需关注 Tick 尾延迟。
channelCommon.reliableUDP.minRTO1050降低过于激进的重传和 CPU、网络放大，更适合真实公网 RTT。
channelCommon.windowOverflow.receive.messages.critical24192提高外部接收窗口警告阈值，减少正常 KCP 或 AOI 突发造成的日志放大。
channelCommon.windowOverflow.receive.messages.external32256提高外部接收消息数量上限。
channelCommon.windowOverflow.receive.bytes.external204865535提高外部接收字节上限，避免正常扇出突发被过早判定异常。

如果项目 kbengine.xml 显式覆盖了这些旧值，引擎升级后仍会继续使用项目值，不会自动采用新默认值。迁移时应根据真实流量重新评估，而不是机械删除或照抄。

配置修改建议 ​

  1. 项目只覆盖真正需要改变的节点。
  2. 同一服务组所有组件必须加载同一套环境配置。
  3. 网络、Witness、KCP 和线程池参数必须通过压测修改，不要只看单次功能测试。
  4. 修改端口、地址、数据库和 Token 后，同时检查防火墙、容器端口、Secret 与管理工具。
  5. 更新引擎时自动对比项目覆盖项与新的 kbengine_defaults.xml，重点检查默认值变化和已移除字段。
  6. 配置修改后至少验证登录、进入 Space、AOI、RPC、写库、重连、Bots 和正常关服。