构建系统

相关源文件

• .github/workflows/clean-up.yml
• .github/workflows/fe-unit-tests.yml
• .github/workflows/ghcr-build.yml
• .github/workflows/lint-fix.yml
• .github/workflows/lint.yml
• .github/workflows/py-unit-tests.yml
• .github/workflows/stale.yml
• Makefile
• containers/app/Dockerfile
• containers/app/entrypoint.sh
• containers/build.sh
• dev_config/python/.pre-commit-config.yaml
• docs/static/img/backend_architecture.puml
• tests/unit/frontend/test_translation_completeness.py

本文档涵盖了OpenHands中使用的构建编排、依赖管理和容器化基础设施。构建系统包括本地开发工作流、Docker镜像创建、CI/CD管道和代码质量强制执行。

有关开发设置和安装的信息，请参阅设置与安装。有关代码质量工具和 linting 配置的信息，请参阅代码风格与 linting。

概述

OpenHands采用多层构建系统，支持本地开发和生产部署。该系统通过Poetry协调Python后端依赖，通过npm协调前端依赖，通过Docker容器化，并通过GitHub Actions实现自动化CI/CD。

构建编排

主要的构建编排通过全面的Makefile处理，该Makefile为开发、测试和部署工作流提供了标准化的目标。

Makefile架构

构建目标和依赖项

Makefile定义了几个关键目标来协调构建过程

• build：协调所有构建步骤的主构建目标
• check-dependencies：验证系统需求和工具版本
• install-python-dependencies：管理基于Poetry的Python依赖安装
• install-frontend-dependencies：处理npm包安装
• run：启动完整的开发环境

来源： Makefile24-31 Makefile33-44 Makefile138-174 Makefile244-248

系统需求验证

构建系统在继续安装之前执行全面的环境验证

系统验证特定的版本要求，并在缺少依赖项时提供详细的错误消息和安装说明。

来源： Makefile46-61 Makefile63-70 Makefile81-95 Makefile118-136

Docker构建系统

OpenHands使用复杂的Docker构建系统，创建支持多架构的应用程序和运行时镜像。

容器构建架构

多阶段应用构建

应用程序Docker镜像使用containers/app/Dockerfile中定义的多阶段构建过程

1. 前端构建器阶段：使用Node.js构建React前端
2. 后端构建器阶段：使用Poetry安装Python依赖项
3. 最终应用阶段：将构建的产物合并到运行时镜像中

构建过程创建了一个具有特定UID/GID配置以兼容沙箱的openhands用户，并设置了具有适当权限的工作区目录。

来源： containers/app/Dockerfile2-12 containers/app/Dockerfile13-29 containers/app/Dockerfile31-99

构建脚本配置

该containers/build.sh脚本为构建所有容器镜像提供了一个统一的接口

该脚本处理多架构构建、基于Git上下文的标签生成以及与容器注册表的集成。

来源： containers/build.sh13-22 containers/build.sh45-76 containers/build.sh137-144

CI/CD 流水线

GitHub Actions通过复杂的构建矩阵和测试策略来协调持续集成和部署管道。

构建工作流架构

容器构建矩阵

CI系统使用动态矩阵策略构建多个运行时变体

矩阵根据触发上下文动态调整——拉取请求仅构建nikolaik变体，而主分支构建包含两个变体。

来源： .github/workflows/ghcr-build.yml31-53 .github/workflows/ghcr-build.yml112-114

运行时测试策略

CI管道包含在不同用户上下文中进行全面运行时测试

• Root测试：以root用户执行运行时测试（RUN_AS_OPENHANDS=false）
• OpenHands用户测试：以openhands用户执行运行时测试（RUN_AS_OPENHANDS=true）

两个测试套件都使用pytest-xdist进行并行执行，并包含对不稳定测试的重试逻辑。

来源： .github/workflows/ghcr-build.yml307-315 .github/workflows/ghcr-build.yml377-382

依赖管理

OpenHands为后端和前端组件采用了不同的依赖管理策略。

Python依赖项

Poetry通过基于环境变量的条件安装来管理Python依赖项

• POETRY_GROUP：控制安装哪些依赖组
• INSTALL_PLAYWRIGHT：控制Playwright浏览器的安装
• 平台特定处理：macOS和Manjaro Linux的特殊配置

来源： Makefile150-155 Makefile156-173

前端依赖

前端使用npm进行包管理，强制执行锁定文件并检测Node.js版本

构建系统包含Node.js版本检测并强制执行兼容性要求。

来源： Makefile176-182 .github/workflows/lint.yml29-32

代码质量集成

构建系统通过预提交钩子和自动化linting集成代码质量检查。

预提交钩子安装

系统会自动安装预提交钩子，在提交前强制执行代码质量标准。

来源： Makefile184-188 dev_config/python/.pre-commit-config.yaml21-44

Linting集成

前端和后端linting都已集成到构建过程中

• 后端：使用ruff进行linting和格式化，mypy进行类型检查
• 前端：使用ESLint进行TypeScript编译检查
• CI集成：具有修复功能的自动化linting工作流

系统同时提供手动（make lint）和自动（CI）linting执行。

来源： Makefile190-200 .github/workflows/lint.yml40-56