Open QuarterMaster 6.5.0 部署指南：Station Captain 单机安装与 Compose 编排

Open QuarterMaster 两条官方部署路径实操：Station Captain 一键安装（系统要求/向导/管理命令）与官方 Compose 编排（含 MongoDB 副本集改造实测），2026-10-24。

Open QuarterMaster库存管理自托管2026/10/24

Open QuarterMaster 6.5.0 部署指南：Station Captain 单机安装与 Compose 编排

Open QuarterMaster（OQM）是一个自带部署管理器的自托管仓储系统——官方把"在一台服务器上把它跑起来"做成了类似"装个 apt 包、跑个向导"的体验。本文给出两条官方部署路径的完整实操：Station Captain 单机安装（官方推荐，适合生产与家用）与官方 Compose 编排（官方标注为本地/非生产探索用途，适合先摸清内部结构）。

组合版本（2026-09-28 官方发布、2026-10-24 实测）：Core API 6.5.0 + Core Base Station 1.21.3 + Station Captain 2.13.1。

一、先选路径：Captain 还是 Compose？

路径定位适合
Station Captain（deb 安装）官方推荐。安装器把整套系统（含 MongoDB、PostgreSQL、Keycloak、Core API、Base Station、Traefik）装成 systemd 管理的容器栈，后续更新/证书/快照全由 oqm-captain 管理单台真实服务器，想长期用
Compose 编排官方仓库 deployment/Compose 提供，官方 README 原文标注为"barebones，用于本地/非生产测试探索"想看清组件拓扑、做集成测试、二次开发
Kubernetes官方提供目录与镜像，但官方明确 Captain 面向单机，K8s 属自建路线已有 K8s 运维体系

一句话：生产用 Captain，研究用 Compose。两条路最后跑起来的东西是同一套。

二、系统要求（官方实查）

官方在 deployment/Single Host/docs/System Requirements.md 给出的要求：

  • 操作系统：现代 Linux，当前只支持 Debian 系（apt）。已实测验证：Ubuntu 22.04、Lubuntu 22.04、Ubuntu 24.04（持续测试基线）、Raspbian（2024-12 当前版本）。Fedora/RHEL 支持在计划中。
  • 内存：4 GB 为测试最低线，真实使用建议 8 GB 起。依据：系统最低内存占用约 2 GiB，启动峰值可达 2.5 GiB，还需给 OS 与业务流量留余量。
  • CPU：无头服务器 2 核、带桌面环境的主机 4 核；架构要求 x64 或 ARM v8，其中 x64 必须支持 AVX 指令集（MongoDB 的硬性要求；官方明确指出 VirtualBox 虚拟机不透传 AVX，无法运行 OQM，KVM/LibVirt 与 Hyper-V 实测正常）。
  • 特殊硬件：官方验证过树莓派 5B（建议 8 GB 以上内存）。
  • 其他：官方强烈建议接 UPS 防断电损伤。

两个容易踩的"Gotchas"（官方排障页原文要求）：

  1. 主机名必须全小写（Keycloak 等组件对此敏感），安装前用 hostnamectl set-hostname 改好。
  2. 装在带 GUI 的桌面系统上会自动出现"OQM"应用快捷方式；无头服务器直接浏览器访问 IP 即可。

三、路径 A：Station Captain 单机安装（官方推荐）

3.1 一条命令装好仓库与管理器

官方 Quickstart 原文步骤，在目标服务器上执行：

bash <(wget -q -O - https://deployment.openquartermaster.com/repos/main/deb/setup-repo.sh)

这个脚本做两件事：配置 OQM 的 apt 仓库，并安装 oqm-captain 包。若系统没有 wget，先 sudo apt install wget。

想要自己编译镜像变体的话，官方还提供带额外选项的包名（如 oqm-captain[rebuild-prod-image-locally]），普通用户不需要。

3.2 跑向导

sudo oqm-captain

第一次运行会进入 setup wizard，按提示走完（设置主机信息、管理员等），向导完成后整套系统就装好了。退出向导脚本即可。

3.3 安装后的服务面

向导结束后，系统里会多出一组 OQM 资产（这也是判断安装是否成功的快速核对清单）：

  • apt list oqm-\*：可以看到 oqm-captain 及相关 oqm 组件包；
  • systemctl：出现 oqm 系列服务，开机自启；
  • docker ps：整套系统以容器栈运行（MongoDB、PostgreSQL、Keycloak、Core API、Base Station 等），由 Captain 管理；
  • 浏览器访问 http://<服务器IP>：对外只有 80/443 两个端口，由 Traefik 统一反向代理，内部各服务不再单独暴露。

oqm-captain 不带参数进入交互菜单，其中 Info / Status → Host / Base OS 能直接看到本机 IP。

3.4 Captain 的日常管理命令（源码实查）

oqm-captain 是一个 Python 3 CLI，除交互式主菜单外提供以下非交互子命令（依据仓库 Station-Captain 源码中各模块的参数定义）：

命令作用
oqm-captain snapshot take-snapshot [manual|scheduled|preemptive]（别名 snap）拍快照。manual 手动 / scheduled 计划 / preemptive 危险操作前自动拍。支持 --skip-data --skip-infra --skip-config 按块跳过、--dry-run 演练、--run-in-foreground 前台执行
oqm-captain container prune-resources（别名 prune）清理 Docker 未使用镜像/网络/缓存（可 --skip-images --skip-networks --skip-cache）
oqm-captain container ensure-setup确保容器运行时与网络配置就绪
oqm-captain package-logs打包日志（排障时发给社区）
oqm-captain utils calcRamLimit [--min N]按本机内存算出各服务内存上限，官方推荐装完先跑一次
oqm-captain demo enable <snapshotFile> / disable把演示数据快照灌入系统
oqm-captain certs regen重新生成自签证书
oqm-captain certs ensure-system-present / certs write-internal <service> <destination>证书补齐 / 把某内部服务证书导出到指定路径
oqm-captain registration register [id]（别名 reg）注册实例 ID
oqm-captain registration ensureInstanceId（别名 eid）确保实例 ID 存在
oqm-captain -v / --version查看版本

配置体系：Captain 的主配置在 /etc/oqm/config/mainConfig.json，自定义覆盖写到 /etc/oqm/config/configs/ 下的 99-custom.json / 99-main.json（按字典序后加载者生效）。逐项参数说明见配置篇。

四、数据依赖链：这套栈里谁连谁

无论 Captain 还是 Compose，跑起来的组件拓扑一致。下面是实测梳理出的完整依赖链：

Base Station(Web前端, host网络)
   ├─→ Keycloak : OIDC 认证（realm=oqm, client=oqm-app）
   └─→ Core API : 所有库存数据读写
Core API(Quarkus, :8080)
   ├─→ MongoDB : 库存主存储（必须副本集模式）
   ├─→ Keycloak : JWT 公钥校验（smallrye.jwt.verify.key.location）
   └─→ Kafka : 可选，事件外发（mp.messaging.outgoing.events-outgoing.enabled=false 时关闭）
Keycloak(:8080)
   └─→ PostgreSQL : Keycloak 自己的数据库（realm 导入文件挂载 /opt/keycloak/data/import/）

最关键的一条坑在这里：Core API 的库存事务（入库/出库流水）使用 MongoDB 多文档事务，MongoDB 必须以副本集（replica set）模式运行。用单机（standalone）MongoDB 时，所有库存事务请求都会 500 并留下这样的日志（实测回显）：

com.mongodb.MongoQueryException: Command execution failed on MongoDB server
with error 20 (IllegalOperation): 'Transaction numbers are only allowed on a
replica set member or mongos'

Captain 安装的副本集由官方镜像与参数处理，用户无感；走 Compose 路径时必须自己补上副本集（见下节实测步骤）。

五、路径 B：官方 Compose 编排（实测记录）

官方对该文件的定位是本地/非生产测试。以下为在一台干净 Linux 服务器上的完整实测过程，可作为摸底环境的标准做法。

5.1 准备编排文件

从官方仓库取两个文件：deployment/Compose/compose/compose.yaml 与同目录 .env.example，放在同一目录（如 ~/oqm/compose/），并把 .env.example 复制为 .env。

在 .env 中按需调整（以下为本次实测的取值，密码请自行替换）：

SYS_RESTART=unless-stopped
SYS_DATA_DIR=/var/oqm/compose-data

MONGO_IMAGE_TAG=6
MONGO_ROOT_USERNAME=oqmadmin
MONGO_ROOT_PASSWORD=q1w2e3r4
MONGO_DATABASE=oqm

POSTGRES_IMAGE_TAG=18
POSTGRES_USER=kcadmin
POSTGRES_PASSWORD=q1w2e3r4
POSTGRES_DATABASE=keycloak

KEYCLOAK_PORT=8138
KEYCLOAK_IMAGE_TAG=26.5
KEYCLOAK_REALM_FILE=./setup/oqm-realm.json
KEYCLOAK_ADMIN_USER=admin
KEYCLOAK_ADMIN_PASSWORD=q1w2e3r4

CORE_API_PORT=8139
CORE_API_PORT_IMAGE_TAG=6.5.0

CORE_BASE_STATION_PORT=8133
CORE_BASE_STATION_IMAGE_TAG=1.21.3
CORE_BASE_STATION_CLIENT=oqm-app
CORE_BASE_STATION_CLIENT_SECRET="**********"

注意三点：

  • KEYCLOAK_REALM_FILE 指向的 oqm-realm.json 来自官方仓库 deployment/Compose/compose/setup/，它定义了 oqm realm 与 oqm-app 客户端；CORE_BASE_STATION_CLIENT_SECRET 的默认值就是该文件中客户端 secret 的字面值（一串星号），两处必须一致。
  • 端口默认为 8080/8100/8081，实测改为 8133（Web）/8138（Keycloak）/8139（Core API），与宿主机已有服务错开即可。
  • 建议在 compose.yaml 顶部加 name: 显式指定项目名，避免目录名成为项目名。

5.2 MongoDB 必须改成单节点副本集（实测必做）

官方 Compose 里的 MongoDB 默认是 standalone，跑事务会 500（原因见第四节）。实测的改造步骤：

  1. compose.yaml 的 mongo 服务追加启动参数与密钥文件：
services:
  mongo:
    # ...原有 image/volumes/environment 配置不变，追加：
    volumes:
      - ${SYS_DATA_DIR}/mongo:/data/db
      - ./mongo-keyfile:/etc/mongo-keyfile:ro
    command: ["mongod", "--replSet", "rs0", "--bind_ip_all", "--keyFile", "/etc/mongo-keyfile"]
  1. 生成副本集内部认证密钥文件（副本集 + 开启认证时 keyFile 是必需项，缺了 mongo 会以退出码 2 拒绝启动，日志报 BadValue: security.keyFile is required when authorization is enabled with replica sets）：
openssl rand -base64 756 | tr -d '\n' > mongo-keyfile
chmod 600 mongo-keyfile
chown 999:999 mongo-keyfile
  1. Core API 的连接串加副本集参数（.env 或 compose.yaml 的 QUARKUS_MONGODB_CONNECTION-STRING）：
mongodb://oqmadmin:q1w2e3r4@openquartermaster-6.5.0-mongo:27017/?replicaSet=rs0&authSource=admin
  1. 拉起 mongo 并初始化副本集：
docker compose up -d mongo
docker exec openquartermaster-6.5.0-mongo mongosh -u oqmadmin -p q1w2e3r4 --quiet \
  --eval 'rs.initiate({_id:"rs0",members:[{_id:0,host:"openquartermaster-6.5.0-mongo:27017"}]})'

实测回显：{ ok: 1 }。等约 10 秒后 rs.status() 中成员进入 PRIMARY 状态。

  1. 整栈拉起：
docker compose up -d

5.3 启动结果（实测回显）

NAME                                    STATUS
openquartermaster-6.5.0-base-station    Up (healthy)
openquartermaster-6.5.0-core-api        Up (healthy)
openquartermaster-6.5.0-keycloak        Up (healthy)
openquartermaster-6.5.0-mongo           Up (healthy)
openquartermaster-6.5.0-postgres        Up (healthy)

五个服务全部进入 healthy（Core API 与 Base Station 镜像自带 /q/health 健康检查）。Core API 冷启动约 30~60 秒（Quarkus 初始化 + 连接 MongoDB/Keycloak）。

5.4 部署后验证清单（实测命令）

# 1. Core API 健康
curl http://localhost:8139/q/health
# 实测回显：{"status":"UP","checks":[...database UP, keycloak UP...]}

# 2. OpenAPI 规范（注意路径带 /q 前缀）
curl http://localhost:8139/q/openapi
# 实测：HTTP 200，完整 JSON 规范，78 个端点；/openapi 不带 /q 返回 404

# 3. Base Station 登录入口
curl -sS -o /dev/null -w "HTTP %{http_code} -> %{redirect_url}\n" http://localhost:8133/overview
# 实测回显：HTTP 302 -> http://localhost:8138/realms/oqm/protocol/openid-connect/auth?...&client_id=oqm-app&...

浏览器打开 http://<服务器IP>:8133，会 302 跳到 Keycloak 登录页（realm=oqm）。首次使用可在 Keycloak（http://<服务器IP>:8138，用 .env 里的 KEYCLOAK_ADMIN_USER/KEYCLOAK_ADMIN_PASSWORD 登录管理台）创建用户并设密码。

密码策略注意：oqm-realm.json 默认启用强密码策略（大写+小写+数字+特殊字符+8 位），简单口令会被拒绝，实测设置 q1w2e3r4 时回显：

HTTP 400 {"error":"invalidPasswordMinSpecialCharsMessage",
"error_description":"Invalid password: must contain at least 1 special characters."}

按策略改口令后设置即成功（HTTP 204）。新用户默认获得 inventoryView / inventoryEdit / itemCheckout / inventoryAdmin 等库存角色，登录 Base Station 即可开用。

六、两条路径怎么选（结论重申）

  • 要真正用起来：走 Captain。一条安装命令 + 一个向导，副本集、证书、开机自启、快照全都有人管。
  • 要研究内部：走 Compose。五个组件的依赖关系、连接串、realm 导入都在眼前，出问题时日志也最容易翻。

两条路的验证标准一致：Core API /q/health 全 UP、浏览器打开 Web 能跳 Keycloak 登录、登录后能进库存界面。

本专栏其他文章

参考来源

  • 官方 Quickstart 与系统要求：仓库 deployment/Single Host/docs/（Quickstart Guide.md、System Requirements.md、tgf.md），2026-10-24 实查
  • Station Captain 命令定义：仓库 deployment/Single Host/Station-Captain/src/ 源码，2026-10-24 实查
  • 官方 Compose：仓库 deployment/Compose/compose/compose.yaml 与 .env.example（core-api-6.5.0 / base_station-1.21.3 tag 时点），2026-10-24 实查
  • 实测环境：Core API 6.5.0 + Base Station 1.21.3 + MongoDB 6（副本集）+ PostgreSQL 18 + Keycloak 26.5，2026-10-24