> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wuji.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Docker 部署

在 Linux Docker 容器中运行 Wuji SDK 应用，将应用与 SDK 依赖放在独立环境中。容器可通过宿主机网络连接设备，并共享宿主机的 SDK 用户数据。按应用使用的能力配置网络访问和数据目录后，可在容器中完成设备连接、数据订阅、设备支持的控制、参数管理和数据录制。接口用法见 [Wuji SDK 阅读指引](https://docs.wuji.tech/docs/zh/wuji-sdk/latest/index.md)。

## 准备环境

在 Linux 主机上安装 [Docker Engine](https://docs.docker.com/engine/install/ubuntu/)，运行 `docker version` 确认客户端与服务端均可用。镜像使用 Ubuntu 22.04 和 Python 3.10。容器默认用户为 `wuji`，UID/GID 均为 1000。

按设备说明完成接线和供电，并确认宿主机能发现设备。接线步骤见 [Wuji Hand 2 实机运行](https://docs.wuji.tech/docs/zh/wuji-hand/latest/quick-start.md#实机运行)和 [Wuji Glove 使用前准备](https://docs.wuji.tech/docs/zh/wuji-glove/latest/getting-started.md)，连接方式见 [设备发现与连接](https://docs.wuji.tech/docs/zh/wuji-sdk/latest/device-connection.md)。宿主机网卡需与设备 IP 位于同一网段，并允许 UDP 广播和 SDK 数据通信。

## 构建与更新

克隆 [Wuji SDK 公开仓库](https://github.com/wuji-technology/wuji-sdk)，使用仓库中的 [Dockerfile](https://github.com/wuji-technology/wuji-sdk/blob/main/docker/Dockerfile) 构建镜像：

```bash theme={null}
git clone https://github.com/wuji-technology/wuji-sdk.git
cd wuji-sdk/docker
docker build --pull --no-cache -t wuji-sdk:local .
```

镜像在构建时从 PyPI 安装最新稳定版 SDK。已有镜像保留构建时的 SDK 版本，启动容器不会更新 SDK。构建后检查版本并保存镜像 ID：

```bash theme={null}
docker image inspect wuji-sdk:local --format '{{.Id}}'
docker run --rm wuji-sdk:local python -m pip show wuji-sdk
```

更新已有镜像前，执行 `docker image tag wuji-sdk:local wuji-sdk:rollback` 保留回退标签，再重新执行带 `--pull --no-cache` 的构建命令。

## 运行应用

按公开仓库的 [Docker README](https://github.com/wuji-technology/wuji-sdk/blob/main/docker/README.md) 启动容器，挂载仓库中的 Python 示例并运行只读订阅示例。以太网和 USB 设备的运行命令及权限配置均见该 README。

`--network host` 保留以太网设备发现需要的广播条件。将宿主 `~/.wuji` 挂载到容器的 `/home/wuji/.wuji`，可保存用户档案、标定数据和日志。该目录及已有文件需允许容器用户（UID/GID 1000）读写。

## 使用 SDK 能力

容器内的应用可调用镜像中安装的 SDK。按应用使用的能力提供对应资源：

| SDK 能力 | 容器所需资源 | 参考 |
| - | - | - |
| 设备连接、数据订阅与设备支持的控制 | 宿主机网络可访问设备。控制设备前，先停止其他占用目标设备的应用 | [设备发现与连接](https://docs.wuji.tech/docs/zh/wuji-sdk/latest/device-connection.md)、[数据订阅](https://docs.wuji.tech/docs/zh/wuji-sdk/latest/data-subscription.md) |
| 参数读写、SDK 用户与标定数据 | 宿主 `~/.wuji` 目录允许容器用户读写 | [设备参数与用户数据](https://docs.wuji.tech/docs/zh/wuji-sdk/latest/device-params.md) |
| 数据录制与离线处理 | 将宿主可写目录挂载到容器，并让录制应用将文件写入该目录 | [数据录制与离线处理](https://docs.wuji.tech/docs/zh/wuji-sdk/latest/data-recording.md) |

## 恢复与问题定位

更新后出现连接问题时，将运行命令中的 `wuji-sdk:local` 换为 `wuji-sdk:rollback`，继续挂载原数据目录，再检查 SDK 导入、设备发现和只读数据。

向技术支持提供镜像 ID、SDK/Python 版本、主机架构、Docker 版本、设备固件版本和失败步骤。在 Jetson 上附上型号及 JetPack/L4T 版本。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.