启动参数与多环境配置

KBEngine Nex 支持在启动组件时选择不同的项目配置文件，用于隔离开发、测试、预发布和生产环境的数据库、网络、日志、管理 token 与业务参数。

本功能作用于每一个服务端进程。Machine、DBMgr、BaseApp、CellApp、LoginApp 等组件各自解析自己的命令行并加载配置，Machine 不会自动替已经由启动脚本直接拉起的其他组件选择配置。

配置加载规则

每个组件按以下顺序加载配置：

从 KBE_RES_PATH 加载引擎公共配置 server/kbengine_defaults.xml；
根据启动参数选择一个项目配置文件；
用项目配置中出现的节点覆盖公共默认值。

没有配置选择参数时，项目文件默认为：

text

server/kbengine.xml

环境配置不会继承项目的 kbengine.xml

使用 --prop=prod 后，引擎加载的是 kbengine_defaults.xml + kbengine_prod.xml，不会先加载 kbengine.xml 再叠加 kbengine_prod.xml。

因此，kbengine_prod.xml 必须包含生产环境需要的全部项目级覆盖项。不要只在其中写一个数据库地址，却把公共的项目设置留在 kbengine.xml 中。

引擎公共默认值应继续保留在 kbe/res/server/kbengine_defaults.xml，项目不要直接修改该文件。项目配置只覆盖自身需要改变的节点，具体规则见配置覆盖。

配置文件命名

推荐把环境文件放在 Assets 的 res/server/ 目录：

text

my_server_assets/
└─ res/server/
   ├─ kbengine.xml
   ├─ kbengine_dev.xml
   ├─ kbengine_test.xml
   ├─ kbengine_staging.xml
   └─ kbengine_prod.xml

文件	推荐用途
`kbengine.xml`	默认本地开发配置
`kbengine_dev.xml`	共享开发环境
`kbengine_test.xml`	自动测试或 QA 环境
`kbengine_staging.xml`	预发布环境
`kbengine_prod.xml`	生产环境

环境名可以自定义，但建议只使用字母、数字、短横线或下划线，避免 shell 转义和文件名兼容问题。

`--prop`：按环境名选择

参数格式必须使用等号：

text

--prop=<环境名>

引擎会将其转换为：

text

server/kbengine_<环境名>.xml

示例：

启动参数	实际选择的配置
无参数	`server/kbengine.xml`
`--prop=dev`	`server/kbengine_dev.xml`
`--prop=test`	`server/kbengine_test.xml`
`--prop=prod`	`server/kbengine_prod.xml`

可以直接启动单个组件验证：

powershell

# Windows
.\kbe\bin\server\dbmgr.exe --cid=4000 --gus=4 --prop=prod

# Linux/macOS
./kbe/bin/server/dbmgr --cid=4000 --gus=4 --prop=prod

组件启动头日志会输出 ConfigFile，应确认它显示预期文件：

text

ConfigFile: server/kbengine_prod.xml

`--location`：指定配置路径

--location 适合文件名不遵循 kbengine_<name>.xml、配置位于挂载目录，或由部署系统生成最终配置的场景。

从资源路径解析

text

--location=server/kbengine_prod.xml

相对路径通过 KBE_RES_PATH 查找。项目资源路径通常优先于后面的同名路径，启动前应检查脚本打印的实际 KBE_RES_PATH。

使用绝对路径

powershell

# Windows
--location=D:\Secrets\kbengine_prod.xml

# Linux/macOS
--location=/etc/kbengine/kbengine_prod.xml

路径参数本身包含空格时，必须引用整个参数：

powershell

"--location=D:\Server Config\kbengine_prod.xml"

'--location=/srv/server config/kbengine_prod.xml'

与 `--prop` 同时出现

不要同时传入两个参数。当前实现中只要 --location 非空，它的优先级就高于 --prop，与二者在命令行中的先后顺序无关。

所有组件必须使用同一配置

同一服务组中的所有组件必须选择同一个环境配置。混用配置可能造成：

DBMgr 与 BaseApp 使用不同数据库或 EntityDef 相关设置；
Machine 与其他组件使用不同网络接口或管理 token；
LoginApp 返回错误的 BaseApp 外部地址；
组件监听端口、日志级别和业务开关不一致；
一部分进程连接测试环境，另一部分连接生产环境。

默认 start_server.bat/.sh 逐行直接启动全部组件，不会自动把传给脚本的 %* 或 "$@" 转发给子进程。因此下面的命令在当前模板中不会全局生效：

# 错误示例：模板没有转发参数
sh start_server.sh --prop=prod

Windows 启动脚本

在 start_server.bat 中定义一次配置参数，并追加到每一个组件命令：

bat

@echo off

set "KBE_CONFIG_ARGS=--prop=prod"

start "" "%KBE_BIN_PATH%\machine.exe" --cid=1000 --gus=1 %KBE_CONFIG_ARGS%
start "" "%KBE_BIN_PATH%\logger.exe" --cid=2000 --gus=2 %KBE_CONFIG_ARGS%
start "" "%KBE_BIN_PATH%\interfaces.exe" --cid=3000 --gus=3 %KBE_CONFIG_ARGS%
start "" "%KBE_BIN_PATH%\dbmgr.exe" --cid=4000 --gus=4 %KBE_CONFIG_ARGS%
start "" "%KBE_BIN_PATH%\baseappmgr.exe" --cid=5000 --gus=5 %KBE_CONFIG_ARGS%
start "" "%KBE_BIN_PATH%\cellappmgr.exe" --cid=6000 --gus=6 %KBE_CONFIG_ARGS%
start "" "%KBE_BIN_PATH%\baseapp.exe" --cid=7001 --gus=7 %KBE_CONFIG_ARGS%
start "" "%KBE_BIN_PATH%\cellapp.exe" --cid=8001 --gus=9 %KBE_CONFIG_ARGS%
start "" "%KBE_BIN_PATH%\loginapp.exe" --cid=9000 --gus=11 %KBE_CONFIG_ARGS%

使用 --location 时：

bat

set "KBE_CONFIG_ARGS=--location=D:\KBEConfig\kbengine_prod.xml"

若需要让脚本接收调用方参数，应先验证并限制允许的值，再统一转发。生产脚本不应未经检查地把任意 %* 交给所有组件。

Linux/macOS `sh` 启动脚本

脚本需要保持 POSIX sh 兼容。只有一个不含空格的 --prop 参数时，可以直接使用变量：

#!/bin/sh
set -eu

KBE_ENVIRONMENT="${KBE_ENVIRONMENT:-prod}"

"$KBE_BIN_PATH/machine" --cid=1000 --gus=1 --prop="$KBE_ENVIRONMENT" &
"$KBE_BIN_PATH/logger" --cid=2000 --gus=2 --prop="$KBE_ENVIRONMENT" &
"$KBE_BIN_PATH/interfaces" --cid=3000 --gus=3 --prop="$KBE_ENVIRONMENT" &
"$KBE_BIN_PATH/dbmgr" --cid=4000 --gus=4 --prop="$KBE_ENVIRONMENT" &
"$KBE_BIN_PATH/baseappmgr" --cid=5000 --gus=5 --prop="$KBE_ENVIRONMENT" &
"$KBE_BIN_PATH/cellappmgr" --cid=6000 --gus=6 --prop="$KBE_ENVIRONMENT" &
"$KBE_BIN_PATH/baseapp" --cid=7001 --gus=7 --prop="$KBE_ENVIRONMENT" &
"$KBE_BIN_PATH/cellapp" --cid=8001 --gus=9 --prop="$KBE_ENVIRONMENT" &
"$KBE_BIN_PATH/loginapp" --cid=9000 --gus=11 --prop="$KBE_ENVIRONMENT" &

启动时选择环境：

KBE_ENVIRONMENT=staging sh start_server.sh

使用可能包含空格的绝对路径时，不要把完整命令行保存在一个字符串中再依赖单词拆分。应直接引用参数：

KBE_CONFIG_FILE="${KBE_CONFIG_FILE:-/etc/kbengine/kbengine_prod.xml}"

"$KBE_BIN_PATH/dbmgr" \
  --cid=4000 \
  --gus=4 \
  --location="$KBE_CONFIG_FILE" &

其余组件使用相同的 --location="$KBE_CONFIG_FILE"。

分布式部署

多台机器共同运行一个服务组时，每个节点都必须具备：

相同版本的环境配置内容；
相同的服务组 UID；
一致的 management token；
可互通的内部网卡和 Machine 发现配置；
唯一的组件 cid 和合适的 gus；
对各自职责正确的外部地址和端口。

可以将同一份只读配置部署到所有节点，也可以为组件生成不同文件，但共享项必须保持一致。若确实需要按组件覆盖个别节点，建议由配置发布系统生成最终完整文件，并在发布前做结构化差异检查。

不要把“开发/生产环境选择”和“BaseApp/CellApp 节点差异”混在一个含大量条件分支的启动脚本中。环境文件负责业务环境，进程管理器负责组件数量、节点和启动参数。

systemd 示例

生产 Linux 更适合让每个组件由 systemd 单独管理，而不是由一个 shell 脚本后台拉起所有进程。

下面以 DBMgr 为例：

ini

[Unit]
Description=KBEngine DBMgr
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=kbe
Group=kbe
WorkingDirectory=/srv/kbengine/server_assets/scripts
Environment=KBE_ROOT=/srv/kbengine
Environment=KBE_RES_PATH=/srv/kbengine/kbe/res/:/srv/kbengine/server_assets:/srv/kbengine/server_assets/res
Environment=KBE_BIN_PATH=/srv/kbengine/kbe/bin/server
ExecStart=/srv/kbengine/kbe/bin/server/dbmgr --cid=4000 --gus=4 --prop=prod
Restart=on-failure
RestartSec=3
LimitCORE=infinity

[Install]
WantedBy=multi-user.target

为其他组件建立对应 unit，并使用相同的 --prop=prod 或 --location=...。不要简单复制 unit 后忘记修改 cid、gus 和组件程序。

配置更新后执行：

sudo systemctl daemon-reload
sudo systemctl restart kbengine-dbmgr
sudo systemctl status kbengine-dbmgr

正式关闭应走引擎的安全关闭流程；systemd 的强制终止超时只作为最后保护。完整部署还应配置启动依赖、日志、资源限制和发布回滚。

Docker 示例

推荐一个容器运行一个组件，使容器参数直接传给目标程序：

yaml

services:
  dbmgr:
    image: your-kbengine-image:tag
    working_dir: /opt/kbengine/server_assets/scripts
    command:
      - /opt/kbengine/kbe/bin/server/dbmgr
      - --cid=4000
      - --gus=4
      - --prop=prod
    volumes:
      - ./server_assets:/opt/kbengine/server_assets:ro

如果镜像入口仍是默认 start_server.sh，Compose 的 command 或 args 只会成为脚本参数；在脚本没有转发参数的情况下，组件仍不会收到 --prop。应修改入口脚本，或直接以组件程序作为容器命令。

数据库密码、管理 token 和私钥不应写进镜像或公开 Compose 文件。可由部署系统生成最终配置并只读挂载，再使用 --location 指向它。

Kubernetes 示例

Kubernetes 同样推荐一个容器运行一个组件。先从已经验证过的完整环境配置创建 ConfigMap：

kubectl create configmap kbengine-config \
  --from-file=kbengine_prod.xml=./res/server/kbengine_prod.xml

下面只展示配置选择和挂载相关部分：

yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: kbengine-dbmgr
spec:
  replicas: 1
  selector:
    matchLabels:
      app: kbengine-dbmgr
  template:
    metadata:
      labels:
        app: kbengine-dbmgr
    spec:
      containers:
        - name: dbmgr
          image: your-kbengine-image:tag
          command:
            - /opt/kbengine/kbe/bin/server/dbmgr
          args:
            - --cid=4000
            - --gus=4
            - --location=/etc/kbengine/kbengine_prod.xml
          volumeMounts:
            - name: config
              mountPath: /etc/kbengine/kbengine_prod.xml
              subPath: kbengine_prod.xml
              readOnly: true
      volumes:
        - name: config
          configMap:
            name: kbengine-config

使用 subPath 挂载单个文件，避免用 ConfigMap 覆盖镜像中已有的整个资源目录。镜像仍需包含 kbe/res/server/kbengine_defaults.xml，因为所选项目配置只负责覆盖公共默认值。

ConfigMap 不适合保存密钥

数据库密码、management token 和证书应使用 Kubernetes Secret 或外部密钥系统。ConfigMap 和 Secret 不会自动把多个 XML 片段合并；需要由 init container、模板工具或发布流程生成一个最终完整配置文件，再通过 --location 加载。

所有其他 KBEngine Deployment 也必须使用同一配置选择。为 BaseApp、CellApp 扩容时，每个同时运行的实例仍需要唯一 cid/gus；不要让多个副本使用完全相同的静态组件 ID。

配置验证

每次部署后至少验证：

每个组件启动头中的 ConfigFile 一致；
没有 config file not found；
DBMgr 连接的是目标环境数据库；
LoginApp/BaseApp 发布的外部地址属于目标环境；
Machine 和组件使用相同的 management token；
日志级别、publish.state 和业务开关符合环境预期；
客户端没有连接到其他环境。

可以在上线前收集所有组件启动头并自动检查 ConfigFile、UID、版本和协议摘要，避免只有部分组件更新配置。

常见错误

`config file not found`

检查：

--prop 是否拼出了真实存在的 server/kbengine_<name>.xml；
--location 是否使用等号；
相对路径是否能从 KBE_RES_PATH 找到；
容器挂载的文件名与参数是否一致；
服务账号是否有读取权限。

只有部分组件使用了新配置

默认启动脚本没有转发参数，或新增 BaseApp/CellApp 时遗漏了配置参数。检查每一条进程命令和每个 systemd/Kubernetes workload，而不是只检查 Machine。

`--prop=prod` 后丢失了原来 `kbengine.xml` 中的设置

这是配置选择语义导致的：环境文件替代默认项目文件，不会继承 kbengine.xml。将必要的项目覆盖项合并进 kbengine_prod.xml，或由配置生成流程从公共项目模板生成完整环境文件。

`--location` 和 `--prop` 结果与顺序不符

两者同时出现时 --location 优先，而不是最后出现的参数优先。删除多余参数，让每个组件只有一个明确配置来源。

Space空间-HOWTOs

分布式部署

启动参数与多环境配置

配置加载规则

配置文件命名

`--prop`：按环境名选择

`--location`：指定配置路径

从资源路径解析

使用绝对路径

与 `--prop` 同时出现

所有组件必须使用同一配置

Windows 启动脚本

Linux/macOS `sh` 启动脚本

分布式部署

systemd 示例

Docker 示例

Kubernetes 示例

配置验证

常见错误

`config file not found`

只有部分组件使用了新配置

`--prop=prod` 后丢失了原来 `kbengine.xml` 中的设置

`--location` 和 `--prop` 结果与顺序不符

相关文档

启动参数与多环境配置 ​

配置加载规则 ​

配置文件命名 ​

--prop：按环境名选择 ​

--location：指定配置路径 ​

从资源路径解析 ​

使用绝对路径 ​

与 --prop 同时出现 ​

所有组件必须使用同一配置 ​

Windows 启动脚本 ​

Linux/macOS sh 启动脚本 ​

分布式部署 ​

systemd 示例 ​

Docker 示例 ​

Kubernetes 示例 ​

配置验证 ​

常见错误 ​

config file not found ​

只有部分组件使用了新配置 ​

--prop=prod 后丢失了原来 kbengine.xml 中的设置 ​

--location 和 --prop 结果与顺序不符 ​

相关文档 ​

启动参数与多环境配置

配置加载规则

配置文件命名

`--prop`：按环境名选择

`--location`：指定配置路径

从资源路径解析

使用绝对路径

与 `--prop` 同时出现

所有组件必须使用同一配置

Windows 启动脚本

Linux/macOS `sh` 启动脚本

分布式部署

systemd 示例

Docker 示例

Kubernetes 示例

配置验证

常见错误

`config file not found`

只有部分组件使用了新配置

`--prop=prod` 后丢失了原来 `kbengine.xml` 中的设置

`--location` 和 `--prop` 结果与顺序不符

相关文档