跳到主要内容

系统部署指南（Docker Compose）

本指南帮助你使用一键安装脚本，通过 Docker Compose 在单机上部署 BK‑Lite 社区版，并按需启用 APM（应用性能监控）、RUM、Workflow（流程编排）、OpsPilot 和本地模型推理服务。

1. 环境要求​

  • Docker >= 20.10.23
  • Docker Compose >= v2.27.0
  • 智能版：在基础版之上，由于启用了 VLLM 内置的 OCR、Embedding 和 Rerank 模型，需要配备 Nvidia GPU，且可用显存 > 8 GB

2. 在线安装（快速开始）​

2.1 基础版（可选模块默认关闭）​

首次安装默认不启用 APM、RUM、Workflow、OpsPilot、MLOps、MLflow，也不部署 vLLM。APM、RUM 和 Workflow 可独立启用，无需为了使用它们部署本地模型：

curl -fLsS https://bklite.cn/install.run | bash -s --

2.2 启用 OpsPilot（对接已有模型服务）​

如需使用 OpsPilot，在安装命令中增加 --opspilot：

curl -fLsS https://bklite.cn/install.run | bash -s -- --opspilot

社区版一键脚本中的 --opspilot 是组合开关，会同时启用 OpsPilot、MLOps、MLflow。该命令不部署 vLLM，无需为本地模型推理配备 GPU；安装后需在 OpsPilot 中配置已有私有模型或公有云模型服务，知识库等功能还需按需配置 Embedding、Rerank 等模型。

2.3 智能版（OpsPilot 与本地模型环境）​

需要在本机部署 OCR、Embedding 和 Rerank 模型时，同时增加 --opspilot --vllm。vLLM 配套模型不包含 LLM 大语言模型，仍需另行配置 LLM 服务：

curl -fLsS https://bklite.cn/install.run | bash -s -- --opspilot --vllm

该方式需要满足前述 Nvidia GPU 和显存要求。--vllm 仅启用本地模型推理服务，不会自动启用 OpsPilot。

2.4 已有社区版补启用 OpsPilot​

在现有部署目录执行（默认目录为 /opt/bk-lite）：

cd /opt/bk-lite
bash bootstrap.sh --opspilot

此命令同样会启用 OpsPilot、MLOps、MLflow，并重新部署相关服务。离线环境须先按下文准备包含 --opspilot 所需镜像的离线包。

重跑安装会复用已保存的配置；不传组件开关时沿用已有组件状态。不要为补启用组件添加 --clean，该参数会清理现有数据。

2.5 启用 RUM（前端体验监控）​

首次安装时增加 --rum：

curl -fLsS https://bklite.cn/install.run | bash -s -- --rum

RUM 复用平台的 Redis、NATS 和 MinIO，额外部署 Gateway、Controller、Maintainer、初始化容器以及独立的 VictoriaLogs/VictoriaTraces 存储。

已有环境应先备份配置和数据，确认部署文件及 Server/Web 镜像版本支持 RUM，再在实际部署目录执行：

cd /opt/bk-lite
bash bootstrap.sh --rum

这是完整部署入口，会重新应用整套服务，请安排维护窗口。首次接入生成的专用凭据、HMAC、回放签名密钥和 RUM_REPLAY_INDEX_EPOCH 会保存并复用。已有 RUM 环境缺失这些配置时应恢复原值；若脚本检测到旧 data/rum/queue，应先停写、备份并完成队列迁移，再重跑，不能直接删除目录绕过检查。

关闭 RUM 使用 bash bootstrap.sh --no-rum，保留持久化数据和密钥。

2.6 启用 Workflow（流程编排）​

Workflow 需要可用的 Conductor 引擎。首次安装增加 --workflow，默认自动部署内置单机引擎，无需手动设置地址：

curl -fLsS https://bklite.cn/install.run | bash -s -- --workflow

脚本会自动设置 CONDUCTOR_BASE_URL=http://conductor:8080/api，选择 Conductor 3.32.1 和持久化卷 compose_conductor（挂载到 /data），无需手动合并 Compose 文件。引擎仅供容器内部访问，不发布宿主机端口。

已有环境先备份，再在实际部署目录执行：

cd /opt/bk-lite
bash bootstrap.sh --workflow

--workflow 会保留已配置的引擎地址；未配置或地址为空时选择内置引擎。脚本自动将 workflow 加入 Server 的 INSTALL_APPS 并持久化地址，后续不带开关重跑时沿用已保存状态。此操作会重新应用整套服务，请安排维护窗口。

使用 bash bootstrap.sh --no-workflow 关闭：脚本清空并保存地址，从 INSTALL_APPS 移除 workflow，停止内置引擎容器并保留数据卷和业务历史；外部引擎不受操作。--workflow 与 --no-workflow 不能同时使用。重新启用内置引擎会复用原卷，切换内置/外部引擎不会自动迁移数据。Server 镜像须包含 Workflow 及其后台进程。

Workflow 本身无需启用 OpsPilot；智能体、意图分类、记忆等节点还需按功能配置 OpsPilot 的相应能力。安装时 --workflow 启用模块；package --workflow 只打包内置引擎镜像，不会自动启用目标环境的模块。

2.7 组合启用与安装验证​

例如，新装同时启用 RUM、Workflow 和 OpsPilot（不部署本地模型）：

curl -fLsS https://bklite.cn/install.run | bash -s -- --rum --workflow --opspilot

安装后在实际部署目录检查 docker compose ps -a 和相关服务日志：

  • RUM：rum-init、rum-minio-init 应成功退出，其余 RUM 服务正常运行。按 RUM 快速入门 验证真实浏览器采集、查询和回放。
  • Workflow：使用内置引擎时确认 conductor 健康，检查 Server 日志及 Workflow Worker、触发调度和制品清理进程，再按 Workflow 快速入门 发布并运行一条无副作用的流程。

2.8 启用 APM（应用性能监控）​

APM 平台端包含 APM 应用、VictoriaTraces 链路存储和 apm-system-collector 中心采集器，复用平台 NATS。它与 OpsPilot、RUM、Workflow 独立，不要求 GPU，也不会随 --opspilot 或 --rum 自动启用。

在线安装与已有环境补启用​

首次安装增加 --apm：

curl -fLsS https://bklite.cn/install.run | bash -s -- --apm

已有环境先备份并确认部署文件及 Server/Web 镜像支持 APM，再在实际部署目录执行：

cd /opt/bk-lite
bash bootstrap.sh --apm

脚本自动将 apm 加入 Server 的 INSTALL_APPS，保存 APM_ENABLED=true，生成采集器配置，并初始化 APM_TRACES 流和 BKLITE_APM_SYSTEM 消费者。无需手动修改应用列表。此操作会重新应用整套服务，应安排维护窗口，不要添加会清理数据的 --clean。

普通重跑不传 APM 开关时沿用已保存状态；旧单机 Compose 配置缺少 APM 字段时兼容历史启用态，不会按新装规则自动关闭。关闭使用：

cd /opt/bk-lite
bash bootstrap.sh --no-apm

--apm 与 --no-apm 互斥。关闭会移除 APM 专用容器，保留数据库记录、链路数据卷、探针制品和已有 NATS 数据，不会关闭共享的 NATS、Fusion-Collector 或 RUM。关闭期间不继续提供 APM 采集与查询能力，重新启用后仍需验证端到端链路。

离线安装与更新​

基础离线包默认不含 APM Collector 和 VictoriaTraces 镜像。联网机器制作包含 APM 的离线包：

curl -fLsS https://bklite.cn/install.run | bash -s -- package --apm

按第 3 节分发、解压并在目标机设置 OFFLINE=true 后，执行 bash bootstrap.sh --apm。可组合打包，例如 package --apm --rum --workflow；打包参数不等于目标环境启用状态。

离线更新已有 APM 环境时，即使本次不再传 --apm，已保存的开启状态仍会要求 APM 镜像齐全。应补齐镜像；若明确不再使用 APM，可用 --no-apm 关闭并保留数据。不能仅因为 RUM 包中已有 VictoriaTraces 镜像，就认为 APM Collector 也已入包。

镜像架构及其他可选组件应与目标环境一致。APM 与 RUM 使用独立的链路存储，关闭 APM 不应删除 RUM 存储。

接入与安装验证​

平台端部署完成后，还需要配置接入区域的区域采集器及业务应用探针。数据路径为：应用探针 → 区域采集器 → NATS JetStream → 中心采集器 → VictoriaTraces。

  • 单机在实际部署目录检查 docker compose ps -a，并用 docker compose logs --tail=100 apm-system-collector victoria-traces 排查中心采集与存储。
  • 按 APM 快速入门 创建应用、配置区域并安装探针，产生一次真实请求，确认服务目录、拓扑和调用链中出现本次数据。
  • 单机 APM 存储默认映射宿主机 10428，这是内部存储端口，不是业务探针的接入地址；应限制访问。探针使用产品指引给出的区域接入点，不能直接指向该端口或 RUM 浏览器采集地址。参见 安全加固手册。

3. 离线安装​

当目标服务器无法访问外网时，先在一台 可联网 且满足版本要求的机器上制作离线包，再拷贝到目标服务器进行安装。

3.1 制作离线包（联网机器执行）​

根据目标环境选择一种打包方式：

  • 基础版（不启用 APM、RUM、Workflow、OpsPilot、MLOps、MLflow、vLLM）：
curl -fLsS https://bklite.cn/install.run | bash -s -- package
  • 启用 OpsPilot（同时启用 MLOps、MLflow，对接已有模型服务）：
curl -fLsS https://bklite.cn/install.run | bash -s -- package --opspilot
  • 智能版（OpsPilot 与本地 OCR、Embedding、Rerank 模型，不含 LLM）：
curl -fLsS https://bklite.cn/install.run | bash -s -- package --opspilot --vllm
  • 按需增加 RUM、内置 Workflow 引擎（可与 --opspilot、--vllm 组合）：
curl -fLsS https://bklite.cn/install.run | bash -s -- package --rum --workflow

--rum 补齐 RUM 所需镜像，--workflow 补齐内置 Conductor 镜像。

执行完成后，安装文件和镜像保存在 /opt/bk-lite 目录，脚本会自动生成 /opt/bklite-offline.tar.gz。package --opspilot 会额外打包 MLflow 镜像；目标机安装时仍需显式传入相应组件开关。

3.2 打包与分发离线包（联网机器执行）​

将生成的 /opt/bklite-offline.tar.gz 拷贝到目标服务器（离线环境）。

3.3 在目标服务器安装（离线机器执行）​

解压离线包并进入部署目录：

sudo mkdir -p /opt/bk-lite
sudo tar -xzvf bklite-offline.tar.gz -C /opt/bk-lite
cd /opt/bk-lite
export OFFLINE=true

在同一终端中，按打包时选择的组件执行以下对应的一条命令：

# 基础版
bash bootstrap.sh

# 或：APM（需已打包 --apm 镜像）
bash bootstrap.sh --apm

# 或：启用 OpsPilot、MLOps、MLflow，对接已有模型服务
bash bootstrap.sh --opspilot

# 或：智能版，另启用本地 OCR、Embedding、Rerank 模型（需要 GPU）
bash bootstrap.sh --opspilot --vllm

# 或：RUM + 内置 Workflow 引擎（首次安装）
bash bootstrap.sh --rum --workflow

已有离线部署应先补齐所选组件镜像。打包开关不会自动启用目标环境的模块。备份与恢复要求见 备份与还原。

4. 卸载​

如需完全卸载系统：

curl -sSL https://bklite.cn/uninstall.sh | bash -s -

常见问题​

  • APM 与 RUM 是否一起启用？ 不会。APM 使用 --apm，RUM 使用 --rum；两者存储独立，需要时可同时传入。安装 APM 平台端后还需完成区域采集器和业务探针接入，见 APM 部署说明。

  • 安装可以重复执行吗？ 可以。重跑会复用已保存的配置，并重新部署相关服务；不传组件开关时保留已有状态。--clean 会清理现有数据，不应用于补启用组件。

  • 没有配置 MIRROR 可以安装吗？ 可以，但在国内网络环境下建议配置以提升下载速度与稳定性。

  • 没有 GPU，能否使用 OpsPilot？ 可以。安装时增加 --opspilot，不加 --vllm，然后在 OpsPilot 中配置已有私有模型或公有云模型服务；所需模型类型取决于使用的功能。基础版首次安装默认不启用 OpsPilot。

  • 访问入口可以使用域名吗？ 可以。在交互式安装时输入 HOST_IP 处可填写 IPv4 地址或域名（如 bklite.example.com），脚本会按形态自动写入证书 SAN：

    • 填 IP → 证书 SAN 包含 IP:<your-ip>，行为同旧版本。
    • 填域名 → SAN 包含 DNS:<your-domain>，并尽力解析对应 A 记录追加 IP:<resolved>（解析失败仅给出警告，不阻断签发）。
    • 域名必须满足 RFC 1123 主机名字符集（字母、数字、-、.），含下划线或空格等非法字符会直接报错退出。
    • 注意：证书在首次部署时签发，后续变更 HOST_IP 不会自动重签——需要先清理 conf/certs/ 后重跑脚本。