容器管理

通过 Umoo 控制台管理远程设备上的 Docker 容器、镜像、卷和网络。

概述

container 插件为边缘设备上的 Docker 资源提供服务端管理界面。命令通过消息总线使用请求-响应模式和关联 ID 进行代理 — 后端向设备 Agent 发送命令并等待响应（默认超时：30 秒）。

所有路由挂载在 /api/v1/plugins/container/devices/{device_id}/ 下。

前提条件

1. 必须为租户启用 container 插件（设置 → 插件配置 → 容器 → 启用）。
2. 目标设备必须在线且 Agent 已连接。
3. 设备上必须安装并运行 Docker。
4. 你的用户角色必须具有相应的 container/* 权限。

容器

列出容器

GET /api/v1/plugins/container/devices/{device_id}/containers

返回设备上的所有容器（运行中和已停止）。

检查容器

GET /api/v1/plugins/container/devices/{device_id}/containers/{id}

返回特定容器的详细信息。

创建容器

POST /api/v1/plugins/container/devices/{device_id}/containers

在设备上创建新容器。请求体：

{
  "image": "nginx:latest",
  "name": "my-nginx",
  "ports": ["80:80"],
  "env": ["ENV_VAR=value"],
  "volumes": ["/host/path:/container/path"],
  "restart_policy": "always"
}

容器生命周期操作

所有生命周期操作都是 POST 请求：

操作	端点	描述
启动	/containers/{id}/start	启动已停止的容器
停止	/containers/{id}/stop	优雅停止运行中的容器
重启	/containers/{id}/restart	停止并启动容器
强制终止	/containers/{id}/kill	强制终止容器（SIGKILL）
暂停	/containers/{id}/pause	冻结容器中的所有进程
恢复	/containers/{id}/unpause	恢复已暂停的容器

删除容器

DELETE /api/v1/plugins/container/devices/{device_id}/containers/{id}

容器日志

GET /api/v1/plugins/container/devices/{device_id}/containers/{id}/logs

获取容器日志输出。最大行数由 max_log_lines 配置控制（默认：1000）。

容器统计

GET /api/v1/plugins/container/devices/{device_id}/containers/{id}/stats

返回运行中容器的 CPU、内存、网络和 I/O 统计信息。

镜像

列出镜像

GET /api/v1/plugins/container/devices/{device_id}/images

检查镜像

GET /api/v1/plugins/container/devices/{device_id}/images/{id}

拉取镜像

POST /api/v1/plugins/container/devices/{device_id}/images/pull

请求体：

{
  "image": "nginx:latest"
}

插件设置中配置的私有镜像仓库会自动用于认证。

删除镜像

DELETE /api/v1/plugins/container/devices/{device_id}/images/{id}

卷

列出卷

GET /api/v1/plugins/container/devices/{device_id}/volumes

创建卷

POST /api/v1/plugins/container/devices/{device_id}/volumes

请求体：

{
  "name": "my-data",
  "driver": "local"
}

删除卷

DELETE /api/v1/plugins/container/devices/{device_id}/volumes/{name}

网络

列出网络

GET /api/v1/plugins/container/devices/{device_id}/networks

创建网络

POST /api/v1/plugins/container/devices/{device_id}/networks

请求体：

{
  "name": "my-network",
  "driver": "bridge"
}

删除网络

DELETE /api/v1/plugins/container/devices/{device_id}/networks/{id}

配置

在设置 → 插件配置 → 容器（租户级）或按设备组配置容器插件。

设置	默认值	描述
镜像仓库	—	用于拉取镜像的私有 Docker 镜像仓库 URL
命令超时	30	等待设备响应的超时秒数
最大日志行数	1000	每次请求返回的最大日志行数

分组级镜像仓库覆盖

设备组可以覆盖租户级的镜像仓库列表，允许不同分组从不同镜像仓库拉取。打开设备 → 分组 → [分组] → 插件 → 容器设置覆盖。

RBAC 权限

资源	操作	描述	默认角色
container/container	read	查看容器、日志、统计	viewer, operator, tenant_admin
container/container	manage	创建、启动、停止、重启、终止、暂停、恢复、删除	operator, tenant_admin
container/image	read	查看镜像	viewer, operator, tenant_admin
container/image	manage	拉取和删除镜像	operator, tenant_admin
container/volume	read	查看卷	viewer, operator, tenant_admin
container/volume	manage	创建和删除卷	operator, tenant_admin
container/network	read	查看网络	viewer, operator, tenant_admin
container/network	manage	创建和删除网络	operator, tenant_admin

工作原理

浏览器 → HTTP API → 后端容器插件
                    → 消息总线（cmd.plugin.container.request）
                    → 设备上的 umoo-agent
                    → Docker 守护进程
                    ← 响应（evt.plugin.container.response）
                    ← HTTP 响应返回浏览器

1. 浏览器向容器插件 API 发送 HTTP 请求。
2. 插件创建带有唯一关联 ID 的 CommandEnvelope。
3. 命令发布到设备的总线主题。
4. Agent 执行 Docker 命令并发布 ResponseEnvelope。
5. 插件通过关联 ID 匹配响应并返回给浏览器。

故障排除

"设备超时"（504）：

• 设备可能离线或不可达。检查设备状态。
• 设备上可能没有运行 Docker。
• Agent 可能没有启用容器插件。
• 对于慢操作（如大镜像拉取），增加 command_timeout。

"权限被拒绝"：

• 你的角色可能缺少所需的 container/* 权限。联系你的租户管理员。

镜像拉取失败：

• 验证镜像名称和标签是否存在。
• 对于私有镜像仓库，确保在插件设置中配置了镜像仓库 URL。
• 检查设备日志中的 Docker 认证错误。