Menu

Polly's Blog

OpenHands 开发环境配置指南

  1. 安装 Docker
sudo apt update
sudo apt install -y apt-transport-https ca-certificates curl software-properties-common
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io
  1. 安装 Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/download/$(curl -s https://api.github.com/repos/docker/compose/releases/latest | grep -oP '"tag_name": "\K[^"]+')/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
  1. 验证安装：
docker --version
docker-compose --version
  1. (Optional) 创建 docker 用户组并加入当前用户，上一步验证失败时运行
sudo usermod -aG docker $USER
newgrp docker
sudo systemctl restart docker
  1. 安装miniforge3 (python环境)
wget "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
bash Miniforge3-$(uname)-$(uname -m).sh
  1. 安装NodeJS
# Download and install nvm:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

# in lieu of restarting the shell
\. "$HOME/.nvm/nvm.sh"

# Download and install Node.js:
nvm install 22

# Verify the Node.js version:
node -v # Should print "v22.14.0".
nvm current # Should print "v22.14.0".

# Verify npm version:
npm -v # Should print "10.9.2".
  1. 安装Poetry
curl -sSL https://install.python-poetry.org | python3 -
  1. 安装系统依赖
sudo apt-get install -y build-essential
  1. 非sudo开发配置
# Download and install Mamba (a faster version of conda)
curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
bash Miniforge3-$(uname)-$(uname -m).sh

# Install Python 3.12, nodejs, and poetry
mamba install python=3.12
mamba install conda-forge::nodejs
mamba install conda-forge::poetry
  1. 安装nginx与SSL证书
sudo apt-get install -y nginx
sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.com
  1. 配置nginx
vim /etc/nginx/sites-available/aicoder
sudo ln -s /etc/nginx/sites-available/aicoder /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

Nginx配置文件

server {
    listen 80;
    server_name localhost;

    # 反向代理到 OpenHands 后端服务
    location / {
        proxy_pass http://127.0.0.1:3000; # OpenHands 后端服务的地址和端口
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # WebSocket 支持配置
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 86400; # 保持连接时间更长

        # 解决 CORS 问题
        add_header Access-Control-Allow-Origin *;
        add_header Access-Control-Allow-Methods 'GET, POST, OPTIONS';
        add_header Access-Control-Allow-Headers 'Content-Type, Authorization';
    }
}
  1. 配置Linux系统服务
sudo vim /etc/systemd/system/aicoder.service
sudo systemctl daemon-reload
# 启动服务
sudo systemctl start aicoder.service
# 停止服务
sudo systemctl stop aicoder.service
# 重启服务
sudo systemctl restart aicoder.service
# 查看服务状态
sudo systemctl status aicoder.service
# 查看服务日志
sudo journalctl -u aicoder.service
# 实时查看日志
sudo journalctl -u aicoder.service -f

[Unit]
Description=AICoder AI Coding Assistant
After=network.target

[Service]
Type=simple
User=ubuntu
WorkingDirectory=/home/ubuntu/GitHub_Workspace/AICoder
ExecStart=/home/ubuntu/miniforge3/envs/AICoder/bin/poetry run uvicorn openhands.server.listen:app --host 0.0.0.0 --port 3000 --reload-exclude ".workspace"
Restart=on-failure
RestartSec=5
StandardOutput=journal
StandardError=journal
Environment="PATH=home/ubuntu/miniforge3/envs/AICoder/bin:/home/ubuntu/miniforge3/bin:/home/ubuntu/.local/bin:/usr/local/bin:/usr/bin:/bin"

[Install]
WantedBy=multi-user.target

常见问题及解决方案

在配置过程中，开发者可能会遇到以下常见问题：

  • 端口权限问题：非 root 用户无法绑定 1024 以下端口，请使用 Nginx 代理或 setcap 命令解决
  • WebSocket 连接失败：确保 Nginx 配置中包含完整的 WebSocket 支持参数
  • Python 依赖冲突：使用虚拟环境和 Poetry 进行隔离管理
  • Docker 权限问题：将用户添加到 docker 用户组，避免频繁使用 sudo

总结

本指南详细介绍了配置 OpenHands 开发环境的完整流程，从基础依赖安装到服务部署和网络配置。通过以上步骤，您可以在本地或服务器上搭建一个完整的 OpenHands 开发环境，为 AI 辅助编程工具的开发和使用提供坚实基础。

主要配置包括：

  • Docker 环境：安装 Docker 和 Docker Compose，为容器化开发和部署提供支持
  • Python 环境：使用 Miniforge3 配置 Python 运行环境，支持不同 Python 版本的开发需求
  • Node.js 环境：安装 Node.js 以支持前端开发和 JavaScript 工具链
  • 依赖管理工具：集成 Poetry 实现 Python 依赖的精确管理
  • 网络服务配置：通过 Nginx 设置反向代理，实现 OpenHands 的 HTTP 和 WebSocket 服务访问
  • 安全配置：包含 SSL 证书申请和配置，确保服务通信安全
  • 对于开发者而言，这套配置不仅适用于 OpenHands 项目，也可作为其他 AI 工具和 Web 应用开发环境的参考。随着 AI 编程助手的快速发展，掌握这些环境配置技能将有助于开发者更好地参与到相关项目中，创建和优化自己的 AI 辅助工具。

留言与讨论