手把手教你如何在自己的VPS上部署Suna AI

要想把 Suna 搬到 VPS 上跑？这思路你想到了吗！放自己机器上跑，要么吃资源，要么关机就没了，扔 VPS 上确实省心多了，还能 24/7 全天候待命。操作不算太复杂，但也得细心点儿，毕竟服务器环境跟咱自己电脑还是有点不一样。来，我跟你捋捋该怎么搞。

一、挑个合适的 VPS (服务器配置咋选？)

选服务器不能太抠，Suna 跟 AI 模型打交道，对资源还是有点要求的。

1. 操作系统 (OS): 首选 Ubuntu 20.04 / 22.04 LTS 或者 Debian。稳定，教程也多。后面命令基本都按 Ubuntu/Debian 的 apt 来。

2. 内存 (RAM): 底线 4GB，但这只是能跑起来。要想用得爽，强烈建议 8GB 起步，特别是你还打算跑点别的服务，或者处理复杂任务时，模型可是吃内存大户。16GB 当然更好。

3. CPU: 最少 2 核，推荐 4 核或更多。

4. 硬盘 (Disk): 30GB SSD 差不多够起步了，系统加 Docker 镜像、数据啥的。必须 SSD/NVMe，不然 IO 慢能卡死你。

5. GPU (显卡): 这玩意儿不是必须，但强烈推荐！很多 AI 推理任务在 GPU 上跑效率能翻几倍。如果你只是体验下基础功能，或者用的模型本身不大，CPU 也行。但想跑得溜，最好弄个带 NVIDIA GPU 的 VPS（比如 V100, T4, A100, 或者消费级的 RTX 30/40 系列也行，看服务商提供啥）。注意，用 GPU 还需要额外配置 Docker。（要选GPU看看：探寻算力新选择：聊聊 DigitalOcean 的 GPU 服务器-CSDN博客）

6. 网络: 带宽越高越好，尤其是你可能要下载大模型或者处理大量数据。按量付费的要留意流量消耗。

7. 访问权限: 你得有 root 或者带 sudo 权限的用户账号，能通过 SSH 连上去。

二、环境准备 (装点儿必备工具)

连上你的 VPS 后，先更新下系统，然后装几个关键家伙：

# 先更新下软件列表和已安装的包
sudo apt update && sudo apt upgrade -y
# 1. 安装 Git (用来拉取 Suna 代码)
sudo apt install git -y
# 2. 安装 Docker
# 官方推荐用脚本安装，比较省事
sudo apt install ca-certificates curl gnupg lsb-release -y # 安装依赖
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.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 docker-ce docker-ce-cli containerd.io docker-compose-plugin -y
# 把你当前用户加到 docker 用户组，这样就不用每次都 sudo docker ... 了
# (加完后需要退出 SSH 再重新登录才生效)
sudo usermod -aG docker ${USER}
echo "把当前用户 ${USER} 加入 docker 组了，重新登录 SSH 生效！"
# 验证 Docker 是否装好
docker --version
# 3. 安装 Docker Compose (新版 Docker 自带 compose 插件，上面已装)
# 如果上面没装插件，或者你需要独立版本的 Compose V2:
# sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
# sudo chmod +x /usr/local/bin/docker-compose
# docker-compose --version # 验证下版本
# 4. (如果需要 GPU 支持) 安装 NVIDIA Container Toolkit
# 这步比较关键，得确保你的 VPS 驱动装好了，并且有 NVIDIA 显卡
# 去 NVIDIA 官网找对应你系统版本的安装教程，大致是这样：
# distribution=$(. /etc/os-release;echo $ID$VERSION_ID) \
#       && curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg \
#       && curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | \
#             sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
#             sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
# sudo apt-get update
# sudo apt-get install -y nvidia-container-toolkit
# sudo nvidia-ctk runtime configure --runtime=docker # 配置 Docker 使用 NVIDIA runtime
# sudo systemctl restart docker # 重启 Docker 服务使配置生效
# 装完 nvidia-container-toolkit 后，docker-compose.yaml 文件里可能需要指定 runtime 为 nvidia

三、下载 Suna 代码

找个你觉得合适的地儿，比如 /opt 或者你的用户主目录 /home/your_user 下，把 Suna 的代码 clone 下来：

# 比如放在 /opt 目录下
cd /opt
sudo git clone https://github.com/kortix-ai/suna.git
cd suna # 进入项目目录，根据实际 clone 下来的文件夹名调整

四、配置你的 Suna

跟本地部署一样，关键是搞定 .env 配置文件。

cd backend # 进入后端目录 (如果项目结构是这样)
sudo cp .env.example .env # 复制模板文件
sudo nano .env # 用 nano (或者 vim) 编辑配置文件

你需要重点关注和修改的配置项：

• OPENAI_API_KEY / ANTHROPIC_API_KEY / GPT API Key: 把你的 Key 填进去。这是必须的。

• 数据库相关 (如 POSTGRES_PASSWORD): 最好改成你自己设置的强密码。

  
  （图片来源网络，侵删）

• HOST / PORT: 有时候在 VPS 上，你可能需要指定监听的 IP 地址（比如 0.0.0.0 意味着监听所有网络接口）和端口。默认值通常能用，但如果你用反向代理或者有端口冲突，可能需要调整。

• PLAYWRIGHT_HEADLESS: 在服务器上通常设为 true，除非你需要看到浏览器界面 (但这需要 VNC 之类的桌面环境，一般 VPS 不会装)。

• APP_BASE_URL: 如果你打算通过域名访问，这里最好填上你的完整域名 (如 https://suna.yourdomain.com)。

• (GPU 相关) 如果你用了 GPU，并且 docker-compose.yaml 需要指定 runtime，检查下 compose 文件里 service 定义，可能需要类似这样加一句：

  services:
    your_service_using_gpu: # 假设是这个服务用 GPU
      runtime: nvidia # 指定使用 nvidia runtime
      environment:
        - NVIDIA_VISIBLE_DEVICES=all # 让容器能看到所有 GPU
      # ... 其他配置 ...

  改完后按 Ctrl+X，然后按 Y 保存，回车确认文件名。

  五、启动 Suna 服务 (用 Docker Compose)

  配置都搞定后，就可以用 Docker Compose 一把梭把所有服务拉起来了：

  # 确保你在包含 docker-compose.yml 文件的目录下 (通常是 backend 或项目根目录)
  sudo docker compose up -d # -d 表示在后台运行 (detached mode)

  这个命令会：

  1. 读取 docker-compose.yml 文件。

  2. 下载所有需要的 Docker 镜像（第一次会比较慢，看你网速和镜像大小）。

  3. 根据 .env 和 docker-compose.yml 的配置创建并启动容器。

  查看服务状态：

  sudo docker compose ps # 查看由 compose 启动的容器状态
  sudo docker compose logs -f # 实时查看所有服务的日志 (-f 是 follow)
  sudo docker compose logs -f  # 查看特定服务的日志，比如 suna-backend

  六、访问你的 Suna 实例

  默认情况下，Suna 的前端可能是通过某个端口暴露的，比如 3000。你需要确保这个端口在 VPS 的防火墙上是打开的。

  1. 防火墙设置 (以 ufw 为例，Ubuntu 常用):

     sudo ufw status # 查看防火墙状态
     sudo ufw allow ssh # 确保 SSH 端口是开的 (通常是 22)
     sudo ufw allow 3000/tcp # 假设前端跑在 3000 端口，打开它
     # 如果你修改了端口，改成你用的端口
     sudo ufw enable # 如果防火墙没启用，启用它
     sudo ufw status # 再次确认规则已添加

  2. 访问:

     在你的浏览器里输入 http://:3000 如果一切顺利，你应该能看到 Suna 的界面了。

  3. (可选但推荐) 配置反向代理 (Nginx / Caddy):

     直接用 IP + 端口访问不太优雅也不安全。推荐用 Nginx 或 Caddy 做反向代理，可以：

     • 使用域名访问 (例如 suna.yourdomain.com)。

     • 自动配置 HTTPS (SSL 证书，推荐 Let's Encrypt 免费证书)。

     • 隐藏后端服务的端口。

     • 做一些负载均衡或缓存（如果需要）。

       配置反代稍微复杂点，需要单独装 Nginx/Caddy，并修改它们的配置文件。这个可以另外找教程。

  七、常见问题与排错 (VPS 上的坑)

  • 端口冲突: 启动时报错说端口已被占用 (Address already in use)。

    • 解决: sudo ss -tulnp | grep  看看哪个进程占用了端口，停掉它，或者修改 .env 或 docker-compose.yml 里 Suna 使用的端口。

    • 防火墙没开对端口: 容器跑起来了，但浏览器访问不了。

      • 解决: 检查 VPS 的防火墙规则 (sudo ufw status) 和云服务商的安全组规则，确保访问端口是开放的。

      • Docker 权限问题: 执行 docker 命令提示 permission denied。

        • 解决: 要么每次都用 sudo docker ...，要么把你当前用户加到 docker 用户组（推荐，参考前面步骤），然后重新登录 SSH 会话生效。

        • 资源不足导致容器崩溃: 服务跑着跑着就挂了，看日志 (docker compose logs ) 可能会有 OOMKilled (内存不足) 之类的错误。

          • 解决: docker stats 或者 htop 监控下资源使用情况。可能需要升级 VPS 配置 (加内存/CPU)。

          • 无法连接外部服务: 比如 Suna 后端无法访问 OpenAI API。

            • 解决:

              1. 检查 .env 里的 API Key 是否正确。

              2. 在 VPS 上 ping 或 curl 对应的 API 地址，看看网络通不通。可能是 VPS 的网络出口策略限制，或者目标服务本身的问题。

            • GPU 在 Docker 中不可用: 配置了 GPU，但服务没用上，或者报错说找不到 GPU 设备。

              • 解决:

                1. 确认 VPS 上的 NVIDIA 驱动正确安装。

                2. 确认 nvidia-container-toolkit 正确安装并配置 Docker runtime。

                3. 检查 docker-compose.yml 文件是否正确指定了 runtime: nvidia 并且设置了 NVIDIA_VISIBLE_DEVICES 环境变量。

                4. 重启 Docker 服务 (sudo systemctl restart docker)。

                八、维护与安全

                • 保持运行: docker compose up -d 会让容器在后台跑，并且 Docker 通常配置为开机自启。所以一般 VPS 重启后服务也会跟着起来。

                • 更新 Suna:

                  cd /opt/suna # 进入项目目录
                  sudo git pull # 拉取最新的代码
                  sudo docker compose pull # 拉取镜像更新 (如果 compose 文件里镜像有更新)
                  sudo docker compose up -d --build # 重新构建镜像并启动 (如果代码有变动需要重新构建)

                • 备份: 定期备份你的 .env 文件和 Docker volumes 里存储的数据（比如数据库数据、用户文件等）。卷通常在 /var/lib/docker/volumes/ 下。

                • 安全:

                  • 别泄露 API Key: .env 文件权限设置好，别上传到公共 Git 仓库。

                  • 强密码: 数据库、可能有的后台管理密码都要强。

                  • 防火墙: 只开放必要的端口。

                  • 及时更新: 系统、Docker、Suna 本身都要留意安全更新。

                  • HTTPS: 用反向代理配置 HTTPS 加密访问。

                    结语

                    好了，大概就是这些步骤和注意事项。把 Suna 弄到 VPS 上跑起来，比在本地玩肯定更有意思，也能干更多正事儿。过程中遇到啥问题，多看看 docker compose logs 的输出，或者去 Suna 的社区、GitHub issues 里找找答案。