OpenHands 多账户方案（一）: Backend Server Setup and Deployment with SSL

OpenHands 是一个基于 Python 的后端服务，使用 FastAPI 框架构建。本文将详细记录如何从源码独立编译部署 OpenHands 的 Server 端，并为其配置 SSL/HTTPS，以实现安全的生产环境服务。

FastAPI、Poetry、Uvicorn、Nginx 和 SSL 的关系

FastAPI： FastAPI 是一个现代的 Python Web 框架，专注于快速开发和高性能。它支持异步编程，能够处理高并发请求。FastAPI 提供了自动生成的交互式 API 文档（如 Swagger UI 和 ReDoc），使开发者能够轻松测试和调试 API。它的类型提示和数据验证功能基于 Python 的 pydantic，确保了数据的可靠性和安全性。
Poetry： Poetry 是一个强大的 Python 项目管理工具，用于管理依赖、虚拟环境和项目构建。它通过 pyproject.toml 文件定义项目的依赖关系和元数据，确保开发环境的一致性。Poetry 的虚拟环境隔离功能使得项目之间的依赖不会相互干扰，同时简化了依赖安装和版本管理。
Uvicorn： Uvicorn 是一个高性能的 ASGI 服务器，用于运行基于 FastAPI 的应用。ASGI（Asynchronous Server Gateway Interface）是 WSGI 的异步版本，支持 WebSocket 和 HTTP/2 等现代协议。Uvicorn 的轻量化设计使其能够快速启动并处理大量并发请求，是运行 FastAPI 应用的理想选择。
Nginx： Nginx 是一个功能强大的 Web 服务器和反向代理工具，广泛用于处理静态资源、负载均衡和 SSL/HTTPS 配置。在本项目中，Nginx 充当反向代理，将外部请求转发到运行在 Uvicorn 上的 FastAPI 应用，同时负责管理 SSL 证书和加密通信。Nginx 的高性能和灵活性使其成为生产环境的首选。
SSL： SSL（Secure Sockets Layer）是一种加密协议，用于保护客户端与服务器之间的通信安全。通过 HTTPS（HTTP over SSL），可以确保数据在传输过程中不会被窃取或篡改。SSL 证书由受信任的证书颁发机构（CA）签发，验证服务器的身份。在本项目中，SSL 通过 Nginx 或 Caddy 自动管理，提供安全的访问通道。

部署架构

                      +-------------+
                      |             |
                      |  Internet   |
                      |             |
                      +------+------+
                             |
                             | HTTPS (443)
                             |
                      +------+------+
                      |             |
                      |   Nginx     | SSL 终止
                      |             |
                      +------+------+
                             |
                             | HTTP (localhost:54013)
                             |
       +-----------------+---+---+-----------------+
       |                 |       |                 |
       |                 |       |                 |
+------+------+    +-----+------+     +------+-----+
|             |    |            |     |            |
|  Uvicorn    |    |  Uvicorn   | ... |  Uvicorn   | ASGI 服务器
|  Worker 1   |    |  Worker 2  |     |  Worker n  |
|             |    |            |     |            |
+------+------+    +------+-----+     +------+-----+
       |                 |                  |
       |                 |                  |
+------+------+    +-----+------+     +-----+------+
|             |    |            |     |            |
|  FastAPI    |    |  FastAPI   |     |  FastAPI   | Web 框架
|  App        |    |  App       |     |  App       |
|             |    |            |     |            |
+-------------+    +------------+     +------------+

实现步骤

1. 从源码编译 OpenHands Server

安装依赖

确保服务器上安装以下工具：

Python 3.8 或更高版本
Poetry
Make

克隆源码

# 克隆 OpenHands 仓库
git clone https://github.com/Polly2014/OpenHands.git
cd OpenHands

安装依赖

进入后端目录并安装依赖：

cd openhands
poetry install

启动服务

使用 Uvicorn 启动 FastAPI 应用：

poetry run uvicorn openhands.server.app:app --host 0.0.0.0 --port 54013

此命令会启动 OpenHands 的后端服务，监听端口 54013。

2. 配置 SSL/HTTPS

为了为后端服务添加 HTTPS 支持，可以使用 Nginx 或 Caddy 作为反向代理。

使用 Nginx 配置 HTTPS

安装 Nginx：
```
sudo apt update
sudo apt install nginx
```

申请 SSL 证书（使用 Let's Encrypt 和 Certbot）：

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.com

配置 Nginx 反向代理：编辑 /etc/nginx/sites-available/openhands：

server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name your-domain.com;

    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:54013; # 后端服务的地址
        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;
    }
}

启用配置并重启 Nginx：

sudo ln -s /etc/nginx/sites-available/openhands /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

使用 Caddy 配置 HTTPS

安装 Caddy：

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo tee /usr/share/keyrings/caddy-archive-keyring.asc
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/deb.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy

配置 Caddyfile：编辑 /etc/caddy/Caddyfile：

your-domain.com {
   reverse_proxy 127.0.0.1:54013
}

启动 Caddy：
```
sudo systemctl restart caddy
```

Caddy 会自动申请和管理 SSL 证书。

3. [Optional] 生产环境优化

4. [Optional] 进程管理与自启动

使用 Systemd 管理服务进程：

创建服务配置：

sudo nano /etc/systemd/system/openhands.service

添加以下内容：

[Unit]
Description=OpenHands FastAPI Server
After=network.target

[Service]
User=ubuntu
WorkingDirectory=/path/to/OpenHands/openhands
ExecStart=/path/to/poetry/bin/poetry run uvicorn openhands.server.app:app --host 0.0.0.0 --port 54013
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

启用并启动服务

sudo systemctl daemon-reload
sudo systemctl enable openhands
sudo systemctl start openhands

5. 验证部署

确保后端服务正在运行：
```
curl http://127.0.0.1:54013
```
通过浏览器访问 https://your-domain.com，验证 HTTPS 是否正常工作。

Nginx性能优化

修改 /etc/nginx/nginx.conf，添加以下优化：

worker_processes auto;
worker_connections 1024;

http {
    # 启用 gzip 压缩
    gzip on;
    gzip_comp_level 5;
    gzip_types text/plain text/css application/json application/javascript;
    
    # 调整缓冲区大小
    client_body_buffer_size 10K;
    client_header_buffer_size 1k;
    
    # 启用 HTTP/2
    http2 on;
    
    # SSL 优化
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers off;
}

常见问题排查

服务无法启动

检查端口是否被占用：sudo lsof -i:54013
检查 Python 环境：python --version
查看日志：poetry run uvicorn openhands.server.app:app --log-level debug

SSL 配置问题

证书路径错误：确认证书文件路径正确
Nginx 配置测试：运行 sudo nginx -t 检查配置
防火墙设置：确保 80/443 端口已开放 sudo ufw status

域名解析问题

确认 DNS 记录已正确设置：dig your-domain.com
等待 DNS 缓存更新（可能需要 24-48 小时）

总结

通过以上步骤，我们成功实现了 OpenHands Server 端的独立编译部署，并为其配置了 SSL/HTTPS。FastAPI、Poetry、Uvicorn、Nginx 和 SSL 的协作确保了服务的高效性和安全性。

这种部署架构具有显著的可扩展性优势：

水平扩展：当负载增加时，可以轻松添加更多 Uvicorn 工作进程或部署多个服务实例，由 Nginx 进行负载均衡，实现无缝扩容。
技术栈灵活性：架构的各组件可以单独升级或替换（如 Caddy 替代 Nginx），无需重新设计整个系统。
资源隔离：使用 Poetry 创建的虚拟环境确保应用依赖独立，便于多个项目在同一服务器上共存。
容器化潜力：此架构可轻松迁移至 Docker 容器或 Kubernetes 集群，进一步提升部署的一致性和可靠性。

通过这种方式部署的 OpenHands 后端服务既安全可靠，又具备了应对未来业务增长的技术基础。如果有其他问题或需求，请随时联系！

OpenHands 多账户方案（一）: Backend Server Setup and Deployment with SSL

FastAPI、Poetry、Uvicorn、Nginx 和 SSL 的关系

部署架构

实现步骤

1. 从源码编译 OpenHands Server

安装依赖

克隆源码

安装依赖

启动服务

2. 配置 SSL/HTTPS

使用 Nginx 配置 HTTPS

使用 Caddy 配置 HTTPS

3. [Optional] 生产环境优化

4. [Optional] 进程管理与自启动

5. 验证部署

Nginx性能优化

常见问题排查

服务无法启动

SSL 配置问题

域名解析问题

总结

留言与讨论