启动与停止

本页以 SDK 模板生成的启动脚本为基础，说明开发环境中的完整启动和关闭流程。

启动服务端

进入 Assets 的 scripts 目录执行启动脚本。

Windows

cd D:\Projects\my_server_assets\scripts
.\start_server.bat

默认脚本会为各组件打开独立控制台窗口。需要隐藏窗口运行本地开发服务时可以使用：

.\start_server_background.bat

Linux/macOS

cd /srv/my_server_assets/scripts
sh start_server.sh

当前 .sh 模板使用 POSIX sh 语法，不要求 Bash。

启动脚本会先强制清理同名进程

模板 start_server.bat/.sh 会先调用 kill_server。该脚本按进程名强制结束组件，不区分 Assets 或服务组。同一主机需要并行运行多套 KBEngine 服务时，必须改用按 UID/组件 ID 管理的进程编排方案，不能直接复用默认模板。

组件启动顺序

模板会启动以下组件：

1. Machine；
2. Logger；
3. Interfaces；
4. DBMgr；
5. BaseAppMgr；
6. CellAppMgr；
7. BaseApp；
8. CellApp；
9. LoginApp。

脚本可能并发拉起这些进程，组件通过 Machine 发现依赖并等待目标就绪。短时间出现 finding dbmgr 等等待日志不一定是错误；如果持续出现，应检查 DBMgr 最早的 EntityDef、Python 或数据库错误。

cid 是组件 ID，同一服务组内必须唯一；gus 用于 KBEngine.genUUID64() 的区段，参与跨进程唯一 ID 生成。复制或扩展 BaseApp/CellApp 启动项时，必须为每个进程分配不同的 cid 和合适的 gus。

检查启动是否成功

不要只以“窗口已经打开”判断成功。至少检查：

1. 各组件进程没有立即退出；
2. DBMgr 完成 EntityDef 和数据库初始化；
3. BaseApp、CellApp、管理组件完成相互发现；
4. LoginApp 正常监听外部端口；
5. 日志中没有未处理的 Python traceback 或持续 ERROR；
6. 客户端能够登录、创建/恢复 Proxy 并进入 Space。

日志位于 Assets 的日志目录。首次连接空数据库时，DBMgr 需要创建或同步 Entity 表结构，耗时取决于 EntityDef 数量和数据库性能。

反复出现 finding dbmgr、EntityDef 错误、Python 导入错误或数据库认证失败时，参见 Python 逻辑层常见错误。

启动 Bots

服务端正常启动后，可以运行：

Windows

.\start_bots.bat

Linux/macOS

sh start_bots.sh

Bots 是开发和压力测试工具。普通启动不会在生产模式下向 Logger/Machine 上报为常规组件；需要 IDE 集中日志时可按工具约定使用 --dev。压力测试前应调整 Bots 数量、批次和日志级别，避免测试工具本身放大 Logger 与网络压力。

详见 Bots 调试 和 Bots 压测。

正常关闭与强制停止

正常关闭

优先使用：

# Windows
.\safe_kill.bat

# Linux/macOS
XUID="$(id -u)" sh safe_kill.sh

safe_kill 通过 pycluster/cluster_controller.py 请求组件按生命周期关闭，使 Entity 保存、回调清理和组件状态有机会收敛。它需要系统中存在可执行的 Python。

Windows 脚本会通过 kbcmd --getuid 获取 UID；Linux/macOS 模板读取 XUID。默认以当前系统用户启动时使用 XUID="$(id -u)"，显式使用其他服务组 UID 时必须传入相同值：

XUID=10103 sh safe_kill.sh

UID 不一致时，集群控制器无法找到需要关闭的服务组。

强制停止

仅在服务失去响应或正常关闭失败时使用：

.\kill_server.bat

sh kill_server.sh

强制停止会直接结束同名进程，可能中断数据库任务、跳过 Python 清理并影响同主机其他 KBEngine 服务。使用前应确认目标主机上没有其他需要保留的同名组件。