本文档主要介绍 openUBMC Studio Docker 管理插件的使用方法，包括打开连接管理页面、拉取社区镜像、创建并连接容器、直连现存容器以及容器生命周期管理等内容，适用于需要在 Docker 容器中构建 openUBMC 的开发者。

Docker 管理插件（bmcstudio Remote - Docker）是 openUBMC Studio 的内置插件，用于将本机 Docker 容器接入为远程开发环境。

插件的核心能力如下：

• 零配置接入：无需编写 Dockerfile，也无需在容器内安装和配置 SSH 服务，选择镜像即可完成容器的创建与连接。
• 社区镜像集成：自动展示 openUBMC 社区发布的构建镜像，未拉取到本地的镜像也可以直接选择，插件在创建容器时自动拉取。
• 容器复用：创建的容器常驻保留，停止后可再次启动并连接；同一份代码还可以同时挂载给多个不同版本的容器，用于多版本切换对比。
• 现存容器直连：对已存在的容器（包括非插件创建的容器）提供直连能力，容器仅作构建环境使用时无需迁移。

使用前准备 ​

• 软件：安装最新版本的 openUBMC Studio，安装方法请参见《openUBMC Studio安装指南》。Docker 管理插件为 Studio 内置插件，随 Studio 一起发布，无需单独安装。

• Docker 环境：先在本机下载安装并启动 Docker，未安装 Docker 时连接管理页面为空，无法展示镜像和容器列表。

• 网络：首次使用需要访问以下网络资源：

  • 社区镜像仓（默认为 swr.cn-north-4.myhuaweicloud.com），用于获取社区镜像列表和拉取镜像。
  • REH Server 下载地址（默认为 https://repo.openubmc.cn/tools/bmc_studio/downloads），首次连接容器时需要下载远程服务端。

下载并安装 Docker Desktop ​

连接管理页面依赖本机 Docker 环境。

下载 Docker Desktop ​

1. 使用浏览器打开 Docker 官网下载页面：https://www.docker.com/products/docker-desktop/。
2. 下载 Docker Desktop for Windows 安装包。

安装并启动 Docker Desktop ​

1. 双击下载的 Docker Desktop Installer.exe，按照安装引导完成安装。

2. 安装完成后启动 Docker Desktop，等待界面左下角显示 Docker 引擎已运行（Engine running）。

打开连接管理页面 ​

Docker 管理插件的连接管理页面位于远程资源管理器（Remote Explorer）中，打开方式如下：

1. 启动 openUBMC Studio，单击活动栏中的“远程资源管理器”图标，打开远程资源管理器。

2. 在远程资源管理器中找到“DOCKER CONTAINERS”区域，即为 Docker 管理插件的连接管理页面。

除远程资源管理器外，还可以通过以下任一入口使用 Docker 连接功能：

• 单击窗口左下角的远程连接按钮，在弹出的菜单中选择“Connect to Docker Container...”。
• 使用快捷键 Ctrl + Shift + P 打开命令面板，输入并执行“Remote-Docker: Connect to Docker Container...”。

连接管理页面分为三个区域：

其中“Images”区域的镜像分为三组：

• LTS：社区推荐的长期稳定版本镜像。
• Non-LTS：社区常规版本及补丁版本镜像。
• Local Custom：本机自行构建、仓库名包含 openubmc 的镜像。

页面顶部提供两个按钮：“+”（Add Image，固定常用镜像，参见固定常用镜像）和刷新按钮（刷新容器与镜像列表）。

拉取社区镜像 ​

查看社区镜像 ​

插件默认从 openUBMC 社区镜像仓（swr.cn-north-4.myhuaweicloud.com/openubmc/ubuntu）获取镜像列表，每个镜像条目由镜像名称和状态组成，状态含义如下：

社区镜像的 tag 命名规则为 Ubuntu版本_openUBMC版本_lts（LTS 版本）或 Ubuntu版本_openUBMC版本_补丁号（补丁版本）。例如 24.04.2_25.12_lts 表示基于 Ubuntu 24.04.2 的 openUBMC 25.12 LTS 版本镜像，在列表中显示为“openUBMC 25.12 LTS”。

拉取镜像到本地 ​

1. 在连接管理页面展开“Images”分组，找到目标镜像。

2. 展开镜像条目，单击“Pull image”；也可以右键镜像条目选择“Pull Image”，或直接单击条目右侧的下载图标。

3. 等待右下角进度通知结束，镜像状态变为“pulled”，表示拉取完成。“Pull image”隐藏，显示“Connect and create if needed”。

按名称拉取指定镜像 ​

对于镜像列表未覆盖的镜像（例如内网私有镜像），可以按名称拉取：

1. 打开命令面板，执行“Remote-Docker: Connect to Docker Container...”。
2. 在镜像选择框中选择“Pull image by name...”。
3. 输入完整镜像地址并回车，插件开始拉取该镜像。镜像地址须携带 tag，例如 swr.cn-north-4.myhuaweicloud.com/openubmc/ubuntu:24.04.2_25.12_lts。

该入口在拉取完成后会继续进入容器创建流程，如只需拉取镜像，在后续步骤中按 Esc 取消即可。

固定常用镜像 ​

将常用镜像固定到列表中，方便快速定位：

1. 单击连接管理页面顶部的“+”（Add Image）按钮。
2. 在镜像选择框中选择镜像；列表中没有时，可选择“Enter image manually...”手动输入镜像地址。
3. 输入该镜像的显示名称并回车，镜像以“pinned”状态固定在镜像列表中。

固定的镜像保存在设置项 remote.Docker.images 中，修改或删除固定项可以直接编辑该设置，参见容器管理相关配置。

创建并连接容器 ​

从镜像一键创建并连接 ​

1. 在连接管理页面“Images”分组中，右键目标镜像，选择“Connect with this Image”；也可以展开镜像条目，单击“Connect and create if needed”（镜像已拉取时展示），或直接单击条目右侧的连接图标。

2. 选择要挂载到容器的本地工程目录：

   • 当前窗口只打开了一个文件夹时，默认使用该文件夹，无需选择。
   • 打开了多个文件夹时，在弹出的选择框中选择其中一个。
   • 未打开文件夹时，在弹出的目录选择框中选择一个本地目录。

3. 输入容器名称。插件按“bmcstudio-工程目录名-镜像名-后缀”规则生成默认名称，其中后缀由工程目录和镜像地址生成，用于保证同一工程同一镜像名称唯一，直接回车使用默认名称，也可以自定义。名称为 1~128 个字符，仅支持字母、数字、点、下划线和中划线，且以字母或数字开头。

4. 输入容器内挂载路径。默认为 /workspace（由设置项 remote.Docker.defaultMountPath 决定），直接回车确认。

5. 插件打开新窗口，并自动完成以下动作：拉取镜像（本机不存在时）、创建并启动容器、在容器内部署 REH Server、建立连接。

6. 连接成功后，新窗口标题栏显示“Docker”，资源管理器展示容器内挂载路径下的工程文件，终端也在容器内执行，此时即可在容器中执行构建。

创建容器（可选高级配置） ​

创建容器时如需注入环境变量或挂载额外目录，使用“Create Container”入口：

1. 在连接管理页面“Images”分组中，右键目标镜像，选择“Create Container”；也可以展开镜像条目，单击“Create container...”。

2. 按提示依次选择工程目录、输入容器名称和容器内挂载路径，操作与从镜像一键创建并连接中的步骤 2~4 相同。

3. 输入环境变量（可选）。多个变量用英文逗号分隔，格式为 KEY=VALUE，例如 CCACHE_DIR=/workspace/.ccache,OPENUBMC_BUILD=1。不需要时直接回车跳过。

4. 输入额外挂载（可选）。多个挂载用英文逗号分隔，格式为 宿主机路径=>容器内路径，例如 C:\cache=>/cache。不需要时直接回车跳过。

5. 插件创建并启动容器，完成后弹出提示“Container ... is ready”，单击“Connect”即可打开新窗口连接。

如果输入的容器名称已被占用，插件会弹出确认框，按以下方式处理：

• 已有容器与当前工程的镜像、挂载配置一致时，可选择“Reuse Existing”直接复用，或选择“Rebuild”删除后重建。
• 已有容器的镜像或挂载与当前配置不一致时，只能选择“Rebuild”删除后重建，或取消后更换容器名称。

连接现存容器 ​

连接插件管理的容器 ​

“Containers”区域列出 openUBMC Studio 创建的全部容器（含已停止的容器），连接方式如下：

1. 单击运行中的容器，直接在新窗口连接。

2. 也可以右键容器，选择“Connect to Container in New Window”（新窗口连接）或“Connect to Container in Current Window”（当前窗口连接）。

3. 已停止的容器需要先启动：单击条目右侧的启动图标，或右键选择“Start Container”，启动后再连接。

直连外部容器 ​

非 openUBMC Studio 创建、正在运行的容器（例如通过 docker run 手动启动的构建容器），会显示在“Other Running Containers”区域，可以直接接入而无需迁移：

1. 在 Docker Desktop 桌面应用的“Images”页签下，启动一个镜像作为外部容器。

   输入容器名后，单击“Run”运行容器。

   启动完成后容器处于运行状态：

2. 回到连接插件管理页面，单击“刷新”按钮更新容器列表。

3. 在“Other Running Containers”区域会显示外部运行的容器，找到目标容器，单击容器，或右键选择“Connect to Container in New Window”。

   插件在容器内部署 REH Server 并建立连接，容器内的目录会作为工作空间打开。

管理容器生命周期 ​

对“Containers”区域中插件管理的容器，可以执行以下操作：

• 启动：已停止的容器，右键选择“Start Container”。
• 停止：运行中的容器，右键选择“Stop Container”。停止后容器保留，可以再次启动连接；宿主机上的代码不受影响。
• 删除：右键选择“Remove Container”，在确认框中单击“Remove”。删除容器后，宿主机上挂载的工程文件安全无损，但仅保存在容器内的文件（例如在容器里手动安装的工具）会随之丢失，同时该容器的连接配置也会被删除。

容器管理相关配置 ​

在设置界面搜索 remote.Docker，或直接编辑 settings.json，可以调整插件行为：

settings.json 配置示例：

{
    "remote.Docker.defaultMountPath": "/workspace",
    "remote.Docker.images": [
        {
            "label": "openUBMC 25.12 LTS",
            "image": "swr.cn-north-4.myhuaweicloud.com/openubmc/ubuntu:24.04.2_25.12_lts"
        }
    ],
    "remote.Docker.communityRegistries": [
        {
            "label": "openUBMC Community",
            "registry": "swr.cn-north-4.myhuaweicloud.com",
            "repository": "openubmc/ubuntu"
        }
    ]
}

常见问题 ​

视图提示 Docker is unavailable 或页面为空 ​

本机未安装或未启动 Docker。请先参见下载并安装 Docker Desktop完成安装，启动 Docker 后单击连接管理页面顶部的刷新按钮。

如何查看插件日志 ​

打开命令面板，执行“Remote-Docker: Show Log”；或在“输出”面板的通道列表中选择“Docker Remote”。连接失败时，日志中会记录镜像拉取、容器创建和服务端部署各阶段的失败原因。