从0到1部署OpenHands：Docker Compose多服务协调最佳实践
项目地址: https://gitcode.com/GitHub_Trending/ope/OpenHands 你还在为多服务部署的环境依赖冲突头疼吗？还在手动配置容器网络和数据卷映射吗？本文将带你通过Docker Compose实现OpenHands的一键化部署，解决服务依赖、端口冲突、数据持久化三大核心问题。读完本文你将掌握：
- 多阶段构建优化的Docker镜像设计
- Docker Compose服务编排实战
- 开发环境与生产环境配置隔离方案
- 容器化部署常见问题排查指南
部署架构概览
OpenHands容器化方案采用前后端分离架构，通过Docker Compose协调单服务实例，实现开发环境的快速搭建。核心架构包含：
- 前端服务：基于Node.js构建的React应用，通过Nginx提供静态资源
- 后端服务：Python FastAPI应用，处理核心业务逻辑
- 数据持久化：通过Docker卷挂载实现状态数据持久化
- 容器通信：基于Docker网络的服务间通信
环境准备与依赖检查
系统要求
- Docker Engine 20.10+
- Docker Compose 2.10+
- 至少2GB内存（推荐4GB+）
- 网络连接（用于拉取基础镜像）
依赖检查命令
docker --version
docker compose version
配置文件解析
Docker Compose核心配置
docker-compose.yml定义了OpenHands的服务组合：
services:
openhands:
build:
context: ./
dockerfile: ./containers/app/Dockerfile
image: openhands:latest
ports:
- "3000:3000"
volumes:
- /var/run/docker.sock:/var/run/docker.sock
- ~/.openhands-state:/.openhands-state
- ${WORKSPACE_BASE:-$PWD/workspace}:/opt/workspace_base
environment:
- SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.28-nikolaik
stdin_open: true
tty: true
关键配置说明：
| 配置项 | 作用 | 风险提示 |
|---|---|---|
/var/run/docker.sock挂载 | 允许容器内操作宿主机Docker | 生产环境需限制权限 |
~/.openhands-state卷 | 持久化应用状态数据 | 定期备份该目录 |
| 3000端口映射 | 暴露Web服务端口 | 生产环境建议修改为非默认端口 |
多阶段构建Dockerfile
containers/app/Dockerfile采用三阶段构建优化镜像体积：
- 前端构建阶段：使用Node.js环境编译React应用
FROM node:21.7.2-bookworm-slim AS frontend-builder
WORKDIR /app
COPY ./frontend/package*.json ./
RUN npm ci
COPY ./frontend ./
RUN npm run build
- 后端构建阶段：使用Python环境安装依赖
FROM python:3.12.3-slim AS backend-builder
WORKDIR /app
RUN python3 -m pip install poetry==1.8.2
COPY ./pyproject.toml ./poetry.lock ./
RUN poetry install --without evaluation,llama-index
- 最终镜像阶段：合并前后端产物并配置运行环境
FROM python:3.12.3-slim AS openhands-app
COPY --from=frontend-builder /app/build ./frontend/build
COPY --from=backend-builder /app/.venv ./.venv
部署步骤详解
1. 克隆代码仓库
git clone https://gitcode.com/GitHub_Trending/ope/OpenHands.git
cd OpenHands
2. 配置环境变量
复制配置模板并修改必要参数：
cp config.template.toml config.toml
# 编辑配置文件设置必要参数
配置文件说明：config.template.toml
3. 构建并启动服务
# 构建镜像并启动服务
docker compose up -d --build
# 查看服务状态
docker compose ps
# 查看日志
docker compose logs -f
4. 验证部署
服务启动后，访问http://localhost:3000，出现OpenHands界面即表示部署成功。
开发环境特殊配置
开发模式启动
containers/dev目录提供了开发环境配置：
# 使用开发模式启动
cd containers/dev
docker compose up -d
开发环境配置特点：
- 代码热重载
- 调试工具集成
- 开发依赖自动安装
常见问题排查
端口冲突解决
若3000端口已被占用，修改docker-compose.yml中的端口映射：
ports:
- "3001:3000" # 将宿主机3001端口映射到容器3000端口
数据卷权限问题
当出现权限错误时，执行以下命令修复：
sudo chown -R $USER:$USER ~/.openhands-state
镜像构建失败
若前端构建失败，检查Node.js版本兼容性：
# 查看Dockerfile中的Node.js版本
cat containers/app/Dockerfile | grep "node:"
官方构建文档：containers/README.md
部署方案对比
| 部署方式 | 优点 | 缺点 | 适用场景 |
|---|---|---|---|
| Docker Compose | 配置简单，一键部署 | 不适合大规模集群 | 开发环境、小型部署 |
| Kubernetes | 可扩展性强，高可用 | 配置复杂，资源占用高 | 生产环境、大规模部署 |
| 单机部署 | 无容器化 overhead | 环境依赖复杂 | 资源受限环境 |
总结与最佳实践
OpenHands的Docker Compose部署方案通过多阶段构建优化了镜像体积，使用卷挂载实现了数据持久化，通过环境变量实现了配置灵活性。推荐部署流程：
- 先在测试环境验证配置
- 使用环境变量区分配置，避免硬编码
- 定期备份挂载卷数据
- 监控容器资源使用情况
官方部署文档：containers/README.md
扩展阅读
- Docker多阶段构建最佳实践：Docker官方文档
- Docker Compose生产环境配置指南：Docker Compose文档
- OpenHands开发指南：Development.md
本文档版本：OpenHands容器化部署方案 v1.0
最后更新时间：2025-10-31
若本文对你有帮助，请点赞收藏，关注获取更多OpenHands使用技巧。下期预告：《OpenHands微服务架构设计与实践》。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
