如何用Distant操作Docker容器：文件读写、命令执行与隧道一站搞定

如何用Distant操作Docker容器：文件读写、命令执行与隧道一站搞定

【免费下载链接】distant🚧 (Alpha stage software) Library and tooling that supports remote filesystem and process operations. 🚧项目地址: https://gitcode.com/gh_mirrors/di/distant

Distant 是一款基于 Rust 的开源远程文件系统与进程操作工具库。借助内置的 Docker 插件，Distant 可以直接连接并操作 Docker 容器：容器内文件读写、命令执行、端口隧道一站搞定——无需登录容器内部，也无需在容器里安装任何守护进程。

下面从原理到实战，带你 5 分钟上手 Distant 操作 Docker 容器。

为什么 Distant 能直接管理 Docker 容器？

Distant 采用「一个协议、多种后端」的设计。Docker 能力由独立的插件模块 distant-docker 提供，它注册了docker插件名并处理docker://协议的目的地地址，核心实现在 DockerPlugin。

它的工作原理非常轻量：

• 直连 Docker 守护进程：通过 bollard 客户端连接docker.sock（自动探测DOCKER_HOST与 Docker Desktop 套接字），不往容器里塞任何东西
• 文件读写走 tar 归档 API：读文件、写文件直接调用容器的归档接口（见 api.rs 中的 tar 读文件调用），比cat/echo更稳定高效
• 命令执行走容器 exec：进程、目录操作、搜索都通过 Docker exec 完成
• 内存内传输：管理器进程内直接挂起一个内存服务端，不占用容器端口

💡 因此只要你的机器能访问 Docker 守护进程，就能操作任意已运行的 Unix 容器（Linux/macOS/Windows 宿主均可，容器须为 Unix 系统）。

快速上手：3 步完成准备

第 1 步：安装 Distant（Docker 功能默认开启，见 Cargo.toml 的 default features）

# Unix curl -L https://sh.distant.dev | sh # 或从源码构建 git clone https://gitcode.com/gh_mirrors/di/distant cargo build --release

第 2 步：确认 Docker 守护进程正在运行

docker ps

第 3 步：连接你的第一个容器

# 连接一个正在运行的容器 distant connect docker://my-container

成功连接后，后续命令默认作用于该连接，无需反复指定容器。

场景一：连接已有容器，或一键拉起新容器

Distant 对 Docker 有两种操作模式：

拉起模式下有个贴心的细节：容器默认开启auto_remove，当你断开连接后，Distant 会自动停止并删除这个临时容器（清理逻辑见 lib.rs），不会留下垃圾容器。

常用连接选项

通过选项可以精细控制 Docker 连接行为（解析逻辑见 plugin.rs）：

场景二：容器文件读写（fs 命令）

连接后，容器文件系统就像本地目录一样操作。文件读写底层走 Docker 的tar 归档 API，写入失败时还有 exec 兜底，可靠性不错：

# 读取容器内文件 distant fs read /etc/os-release # 写入文件 / 复制文件 / 建目录 distant fs write /tmp/hello.txt distant fs copy /src /dst distant fs make_dir /tmp/newdir -a # 查看元数据、检查存在性 distant fs metadata /var distant fs exists /app/config.yml # 重命名、删除、修改权限 distant fs rename /tmp/a /tmp/b distant fs remove /tmp/a distant fs set_permissions /tmp/hello.txt 644 # 容器内文件搜索（自动探测 rg / grep / find） distant fs search "*.rs" /app

📌 搜索是「尽力而为」的：Distant 连接时会自动探测容器里有哪些搜索工具（探测逻辑在 api.rs），没有rg就降级用grep或find。

场景三：命令执行与交互式 shell

通过容器 exec 在容器里跑命令，就像 SSH 一样自然：

# 执行一次性命令 distant spawn -- ls -la /var/log # 打开交互式 shell（PTY，支持终端 resize） distant shell # 杀掉之前 spawn 的进程 distant kill <进程ID>

Distant 对每个进程做了完整跟踪：stdin 写入、stdout/stderr 流式回传、PTY 尺寸调整、优雅终止都有对应通道（实现见 process.rs）。跑top、vim这类交互程序也没有问题。

场景四：端口隧道，直接访问容器里的服务

容器里起了 MySQL、Redis 或调试端口，但没做端口映射？用 Distant 的正向隧道打通：

# 本地 3307 -> 容器内 127.0.0.1:3306 distant tunnel open 3307:127.0.0.1:3306

之后本地程序连接127.0.0.1:3307，流量就会被转发进容器。

⚠️ 两个限制需要知道（说明见 PROTOCOL.md）：

• 正向隧道需要容器内装有socat 或 nc（netcat）之一，Distant 会自动探测并选择
• 反向隧道不受支持——Docker exec 只有单一 stdin/stdout 通道，无法复用多个入站连接

功能支持一览

来自官方协议文档（docs/PROTOCOL.md）的支持矩阵：

常见问题 FAQ

Q1：提示Container 'xxx' is not running？Distant 连接前会校验容器状态，容器没启动时直接报ConnectionRefused（见 lib.rs）。先docker start xxx再连接，或直接用distant launch从镜像拉起。

Q2：搜索时报「No search tools available」？容器里没有rg/grep/find任一工具。换一个带标准 POSIX 工具的镜像（如ubuntu）即可。

Q3：隧道打不通？检查容器里是否装了socat或nc；distant connect时 Distant 会探测并在版本能力里如实声明。

Q4：Windows 容器支持吗？目前仅支持 Unix 容器。宿主机的 Docker Desktop（含 Windows/macOS）没问题。

核心代码导航

想深入 Distant 的 Docker 实现，可以从这些入口读起：

• Docker 插件入口（docker://协议解析）：distant-docker/src/plugin.rs
• 连接与拉起容器：distant-docker/src/lib.rs
• Docker API 实现（tar 文件 I/O + exec）：distant-docker/src/api.rs
• 容器进程管理（PTY/kill）：distant-docker/src/process.rs
• 协议与后端能力矩阵：docs/PROTOCOL.md
• 插件规范（如何自写插件）：docs/PLUGINS.md

总结

Distant 把「操作 Docker 容器」这件事压缩成了三类直觉命令：connect/launch管连接，fs管文件，spawn/shell/tunnel管进程与网络。不用进容器、不用装代理、不用配端口映射——一条docker://地址搞定全部。如果你经常在容器里折腾文件、调试服务，值得装一个试试 🚀

【免费下载链接】distant🚧 (Alpha stage software) Library and tooling that supports remote filesystem and process operations. 🚧项目地址: https://gitcode.com/gh_mirrors/di/distant