动手实践OpenHands系列学习笔记1：Docker基础与OpenHands容器结构

笔记1：Docker基础与OpenHands容器结构

一、引言

OpenHands作为AI驱动的软件开发代理平台，采用Docker容器技术实现环境隔离和快速部署。本笔记将介绍Docker基础知识，并深入分析OpenHands的容器架构，帮助我们理解其设计原理。

二、Docker基础知识

2.1 Docker核心概念

• 镜像(Image): 只读模板，包含创建容器的指令
• 容器(Container): 镜像的运行实例，相互隔离
• Dockerfile: 构建镜像的文本文件，包含一系列命令
• Docker Hub/Registry: 镜像仓库，用于存储和分发镜像
• Docker Compose: 定义和运行多容器应用的工具

2.2 Docker工作原理

• 分层文件系统
• 写时复制(CoW)机制
• 容器隔离原理(Namespace和Cgroup)
• Docker Engine与守护进程

三、OpenHands容器结构分析

3.1 OpenHands镜像层次

从README_CN.md分析，OpenHands使用了两个关键镜像：

docker.all-hands.dev/all-hands-ai/runtime:0.47-nikolaik
docker.all-hands.dev/all-hands-ai/openhands:0.47

• 运行时镜像(runtime): 提供执行环境
• 应用镜像(openhands): 包含核心应用逻辑

3.2 容器配置分析

docker run -it --rm --pull=always \
    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.47-nikolaik \
    -e LOG_ALL_EVENTS=true \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v ~/.openhands:/.openhands \
    -p 3000:3000 \
    --add-host host.docker.internal:host-gateway \
    --name openhands-app \
    docker.all-hands.dev/all-hands-ai/openhands:0.47

参数解析：

• -it: 交互式终端
• --rm: 容器停止后自动删除
• --pull=always: 始终拉取最新镜像
• -e: 设置环境变量
• -v: 挂载卷，实现数据持久化和Docker Socket访问
• -p: 端口映射，暴露3000端口
• --add-host: 添加主机名映射，允许容器访问宿主机
• --name: 指定容器名称

3.3 OpenHands容器架构特点

1. 嵌套容器设计：主容器通过Docker Socket创建和管理沙箱容器
2. 持久化机制：通过卷挂载(~/.openhands:/.openhands)保存会话状态
3. 网络桥接：使用host.docker.internal实现容器与宿主机通信
4. 环境隔离：使用专用运行时容器执行代码，增强安全性

四、实践项目：构建简化版OpenHands容器

4.1 创建基础Dockerfile

FROM node:18-alpine AS base

# 安装基础工具
RUN apk add --no-cache python3 docker-cli curl

# 创建工作目录
WORKDIR /app

# 复制项目文件
COPY package.json .
RUN npm install

# 设置入口点
ENTRYPOINT ["node", "server.js"]

4.2 实现简单的容器间通信

// server.js 示例代码
const { spawn } = require('child_process');
const express = require('express');
const app = express();

app.get('/run-container', async (req, res) => {
  // 使用Docker Socket启动沙箱容器
  const dockerRun = spawn('docker', [
    'run', '--rm',
    'docker.all-hands.dev/all-hands-ai/runtime:0.47-nikolaik',
    'echo', 'Hello from sandbox container'
  ]);
  
  let output = '';
  dockerRun.stdout.on('data', (data) => {
    output += data.toString();
  });
  
  dockerRun.on('close', (code) => {
    res.send({ output, exitCode: code });
  });
});

app.listen(3000, () => {
  console.log('Server running on port 3000');
});

4.3 构建与运行

# 构建简化版容器
docker build -t openhands-simplified .

# 运行简化版容器
docker run -it --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -p 3000:3000 \
  openhands-simplified

五、总结与思考

1. OpenHands通过嵌套容器设计实现了代码执行环境的隔离，增强了安全性
2. Docker Socket挂载是实现容器间通信的关键，但也引入了安全风险
3. 卷挂载机制确保了用户数据和配置的持久化
4. 环境变量配置使系统更灵活，便于定制化部署

六、下一步学习方向

1. 深入研究Docker网络模型，理解容器间通信机制
2. 探索Docker卷和数据持久化的最佳实践
3. 分析OpenHands沙箱环境的安全设计
4. 学习Docker Compose配置，实现更复杂的多容器应用

参考资源

1. Docker官方文档: https://docs.docker.com/
2. OpenHands文档: https://docs.all-hands.dev/
3. 容器安全最佳实践: https://docs.all-hands.dev/usage/runtimes/docker#hardened-docker-installation