Open QuarterMaster 6.5.0 配置参数详解
Open QuarterMaster 三层配置体系逐项详解：Captain 的 mainConfig.json 与覆盖机制、Compose 环境变量、Keycloak realm 默认策略，关键项均附实测回显（2026-10-24）。
Open QuarterMaster库存管理自托管2026/10/24
Open QuarterMaster 6.5.0 配置参数详解
Open QuarterMaster 的配置分散在三层：Station Captain 的 JSON 配置（单机部署的管理面）、Compose 编排的环境变量（容器编排面）、Keycloak realm 配置（认证面）。本文基于 2026-10-24 实查的官方源码（Station-Captain/src/mainConfig.json、lib/ConfigManager.py）与官方 Compose 的 .env.example，逐项说明每个参数的含义、默认值与生效方式，关键行为均经实测验证。
一、三层配置体系总览
| 层 | 载体 | 谁读它 | 典型用途 |
|---|---|---|---|
| Captain 配置 | /etc/oqm/config/mainConfig.json + 覆盖文件 | oqm-captain、systemd 服务 | 主机名、数据目录、快照、证书、资源档位 |
| Compose 环境变量 | .env 文件 + compose.yaml | docker compose | 镜像版本、端口、数据库账号、组件间连接串 |
| Keycloak realm | setup/oqm-realm.json（Compose 导入） | Keycloak | 用户/角色/客户端/密码策略 |
Captain 路径写的是真实服务器上 /etc/oqm 的固定布局；Compose 路径全部通过环境变量注入，两者不混用。
二、Captain 文件系统布局（源码实查）
Station Captain 源码 lib/ConfigManager.py 中定义的固定路径，全部服务于单机部署形态：
| 路径 | 用途 |
|---|---|
| /data/oqm | 主数据目录（system.systemDataDir + /oqm） |
| /etc/oqm | 共享配置根目录 |
| /etc/oqm/config | Captain 主配置目录（mainConfig.json 所在） |
| /etc/oqm/config/configs | 自定义覆盖目录（99-main.json、99-custom.json） |
| /etc/oqm/serviceConfig | 各服务自己的配置 |
| /etc/oqm/snapshots/scripts | 快照前后钩子脚本 |
| /etc/oqm/certs | 证书体系（自签 CA、服务证书、trustStore） |
| /etc/oqm/certs/trustStores | 系统外部信任库目录 |
| /data/oqm-snapshots | 快照默认存放点（可改） |
覆盖机制：Captain 加载 mainConfig.json 后，按字典序依次加载 configs/ 目录里的覆盖文件（官方约定用 99-main.json、99-custom.json 命名，保证最后加载），同名键后到者覆盖先到者。改配置别直接动 mainConfig.json——那是官方默认文件，升级会被覆盖；自己的定制一律写进 99-custom.json。
三、mainConfig.json 逐项详解
以下为默认值（原文件实查），<secret> 表示由系统生成后写入的密文。
3.1 system 块——主机与资源
| 键 | 默认值 | 说明 |
|---|---|---|
| system.hostname | （向导写入） | 本机对内服务的主机名。官方要求全小写，Keycloak 对大小写敏感 |
| system.altHostnameIps | [] | 额外主机名/IP 列表，会加进证书 SAN |
| system.systemDataDir | /data | 数据总根目录 |
| system.dataDir | #{system.systemDataDir}/oqm | OQM 数据目录（支持引用其他键） |
| system.automaticContainerPruneFrequency | monthly | 容器资源自动清理频率（月度） |
| system.defaultUi | {custom:false, type:core, name:base-station, path:/} | 默认进入的前端；装了多个 UI 插件时可切换 |
| system.resources.ramLimitProfile | SLIM | 各容器内存档位。装完官方建议跑 oqm-captain utils calcRamLimit 按本机内存重算 |
3.2 snapshots 块——快照与备份
| 键 | 默认值 | 说明 |
|---|---|---|
| snapshots.location | /data/oqm-snapshots | 快照输出目录 |
| snapshots.numToKeep | 5 | 本地保留快照数，超出轮转删除 |
| snapshots.frequency | weekly | 计划快照频率 |
| snapshots.compressionAlg | xz | 压缩算法，可选 xz/gz/bz2 |
| snapshots.encryption.enabled / pass | false / <secret> | 快照对称加密开关与口令 |
| snapshots.backup.method | local | 备份方式：local / ssh / objStorage 三选一 |
| snapshots.backup.enabled | false | 快照后自动外送备份的开关 |
| snapshots.backup.local.path | "" | 本地备份目标路径 |
| snapshots.backup.ssh.path | "" | SSH 远端路径（需自行配好免密） |
| snapshots.backup.objStorage.* | accessKey/secretKey/bucket/prefix/endpointUrl/region/skipVerifySsl | S3 兼容对象存储参数 |
手动拍快照不依赖 frequency：oqm-captain snapshot take-snapshot manual。
3.3 cert 块——证书体系
| 键 | 默认值 | 说明 |
|---|---|---|
| cert.externalDefault | self | 对外证书来源：self（自签） |
| cert.additionalExternalSANs | [] | 追加的对外 SAN |
| cert.selfSigned.rootCaTtl | 2920 | 自签根 CA 有效期（天，约 8 年） |
| cert.selfSigned.systemCertTtl | 365 | 系统证书有效期（天） |
| cert.selfSigned.daysBeforeExpiryToRegen | 30 | 到期前多少天自动重签 |
| cert.selfSigned.certInfo.* | countryName:US 等 | 证书主题信息（caCommonName 默认取 organizationName） |
| cert.selfSigned.generateKeystore | false | 是否生成 Java keystore |
| cert.acme.contactEmail / caServer / eab | "" | ACME（Let's Encrypt 等）签发配置；eab 用于需要外部账户绑定的 CA |
| cert.provided.enabled / cert / key | false | 自带证书开关与路径 |
| cert.trustStore.* | /etc/oqm/certs/trustStores/... | 根证书信任库文件位置 |
证书相关的管理命令：oqm-captain certs regen（重签）、certs ensure-system-present（补齐）、certs write-internal <service> <destination>（导出某内部服务证书给外部程序信任）。
3.4 captain / registration / plugin 块
| 键 | 默认值 | 说明 |
|---|---|---|
| captain.demoMode.frequency | hourly | 演示模式重置频率（配合 oqm-captain demo enable） |
| captain.demoMode.snapshotFile | "" | 演示数据快照文件 |
| registration.instanceId | null | 实例注册 ID（oqm-captain registration ensureInstanceId 生成） |
| registration.registrationId / registrationSecret | null | 注册凭据 |
| plugin | {} | 插件配置挂载点，装插件后各自在此添加键 |
四、Compose 编排的环境变量（官方 .env.example 逐项）
官方 Compose 的 .env.example 分四组，取值即 2026-09-28 稳定套件版本：
4.1 系统组
| 变量 | 默认 | 说明 |
|---|---|---|
| SYS_RESTART | unless-stopped | 注入所有服务的 restart 策略 |
| SYS_DATA_DIR | （无默认，必填） | 数据卷宿主根目录，下面挂 mongo/、postgres/ 子卷 |
4.2 MongoDB（库存主存储）
| 变量 | 默认 | 说明 |
|---|---|---|
| MONGO_IMAGE_TAG | 6 | 镜像 tag（MongoDB 6.x，x64 需 AVX） |
| MONGO_ROOT_USERNAME / MONGO_ROOT_PASSWORD | oqmadmin / <secret> | root 账号，Core API 连接串引用 |
| MONGO_DATABASE | oqm | 初始库名 |
4.3 PostgreSQL + Keycloak（认证域）
| 变量 | 默认 | 说明 |
|---|---|---|
| POSTGRES_IMAGE_TAG | 18 | 镜像 tag |
| POSTGRES_USER / POSTGRES_PASSWORD / POSTGRES_DATABASE | kcadmin / <secret> / keycloak | Keycloak 的 DB 账号 |
| KEYCLOAK_PORT | 8100 | 对外端口（实测环境用 8138） |
| KEYCLOAK_IMAGE_TAG | 26.5 | 镜像 tag |
| KEYCLOAK_REALM_FILE | ./setup/oqm-realm.json | realm 导入文件，挂载到 /opt/keycloak/data/import/，配合 start --import-realm |
| KEYCLOAK_ADMIN_USER / KEYCLOAK_ADMIN_PASSWORD | oqm_admin / <secret> | Keycloak 管理台账号 |
4.4 Core API + Base Station
| 变量 | 默认 | 说明 |
|---|---|---|
| CORE_API_PORT | 8081 | Core API 对外端口（实测环境用 8139） |
| CORE_API_PORT_IMAGE_TAG | 6.5.0 | oqm-core-api 镜像版本 |
| CORE_BASE_STATION_PORT | 8080 | Web 前端端口（实测环境用 8133）；Base Station 以 host 网络运行，该值即宿主监听端口 |
| CORE_BASE_STATION_IMAGE_TAG | 1.21.3 | oqm-core-base_station 镜像版本 |
| CORE_BASE_STATION_CLIENT | oqm-app | OIDC 客户端 ID |
| CORE_BASE_STATION_CLIENT_SECRET | "**********" | 客户端密钥，字面值就是一串星号，与 oqm-realm.json 中 oqm-app 的 secret 一致；整体加引号防止 shell 吃掉星号 |
除 .env 外，compose.yaml 里还注入了组件间连接参数（一般不用改，改了要前后一致）：
| 服务 | 变量 | 作用 |
|---|---|---|
| core-api | smallrye.jwt.verify.key.location | JWT 公钥地址，指向 Keycloak http://<keycloak主机>:8080/realms/oqm/protocol/openid-connect/certs |
| core-api | QUARKUS_MONGODB_CONNECTION-STRING | Mongo 连接串。事务功能要求加 replicaSet=rs0&authSource=admin 并配合副本集模式启动（实测：standalone 时库存事务 500） |
| core-api | QUARKUS_MONGODB_DATABASE | 库名，同 MONGO_DATABASE |
| core-api | mp.messaging.outgoing.events-outgoing.enabled | 事件外发（Kafka）开关，默认 false；装 Kafka 类插件时打开 |
| core-base_station | QUARKUS_HTTP_PORT | 前端监听端口 |
| core-base_station | QUARKUS_OIDC_CLIENT-ID / CREDENTIALS-SECRET | OIDC 客户端与密钥 |
| core-base_station | QUARKUS_OIDC_AUTH-SERVER-URL | 认证域地址 http://localhost:<KEYCLOAK_PORT>/realms/oqm |
| core-base_station | OQM_CORE_API_BASEURI | 后端 API 地址 http://localhost:<CORE_API_PORT> |
五、Keycloak realm 层（认证面）实测
oqm-realm.json 导入后生成 realm oqm，关键默认值（实测取证）：
- 客户端：
oqm-app（Base Station 与 REST API 共用），开启 direct access grants——支持 OAuth2 password grant 直接拿 token（API 实战篇依赖此特性）。 - 密码策略：长度≥8、须含大小写、数字、特殊字符。实测用
q1w2e3r4设置密码被拒：
HTTP 400
{"error":"invalidPasswordMinSpecialCharsMessage","error_description":"Invalid password: must contain at least 1 special characters."}
改用满足策略的口令后设置成功（HTTP 204）。要放宽策略，在 Keycloak 管理台 → Realm settings → Password policy 中调整，或改 oqm-realm.json 的 passwordPolicy 后重建 realm。
- 默认角色：新建用户自动获得 inventoryView / inventoryEdit / itemCheckout / inventoryAdmin / user 等角色（实测 role-mappings 回显），即"开箱即用就是库存管理员"。最小权限场景需在 Keycloak 里手工收敛。
六、改配置怎么生效（实测结论）
- Compose 路径：改 .env 或 compose.yaml 后
docker compose up -d（会重建受影响服务）；只改端口映射不影响数据卷，数据安全。 - Captain 路径：写 /etc/oqm/config/configs/99-custom.json，然后按提示重启对应 oqm 服务；证书类改动用
oqm-captain certs regen显式重签。 - 验证手段：
curl http://localhost:<CORE_API_PORT>/q/health应返回"status":"UP"且 checks 里 database、keycloak 均 UP；Base Station 端口 curl 应 302 跳 Keycloak 授权端点。
本专栏其他文章
- Open QuarterMaster 6.5.0 介绍与选型指南
- Open QuarterMaster 6.5.0 部署指南：Station Captain 单机安装与 Compose 编排
- Open QuarterMaster 6.5.0 REST API 实战：从认证到库存事务
参考来源
- Station Captain 源码：deployment/Single Host/Station-Captain/src/mainConfig.json、lib/ConfigManager.py（2026-10-24 实查）
- 官方 Compose：deployment/Compose/compose/.env.example、compose.yaml（core-api-6.5.0 时点，2026-10-24 实查）
- Keycloak realm：deployment/Compose/compose/setup/oqm-realm.json + 实测回显（2026-10-24）
- 实测环境：Core API 6.5.0 + Base Station 1.21.3 + MongoDB 6（副本集）+ PostgreSQL 18 + Keycloak 26.5
章节目录