Rakazo 自托管 VPS 部署：配置与内存需求

Rakazo 自托管实际运行的组件

自托管 Rakazo，意味着在一台 Linux 服务器上运行 5 个组件：PostgreSQL、一个 Graphile Worker 进程、API、Web 应用，以及每个处于唤醒状态的机器人对应的一个 sandbox 容器。Rakazo 是 Grok Bot 的开源替代品，由 elie222 以 Apache 2.0 许可证发布。每个机器人都有自己的线程、计算机、记忆和历史记录，也可以创建对等机器人或短生命周期的子代理。如果您不熟悉这句话中的“记忆”“子代理”和“工具调用”等概念，建议先阅读了解代理实际工作方式的分阶段路径，因为只有先理解机器人唤醒时正在执行什么，下面的大多数设置才有意义。

最后这一点正是它应运行在 VPS（虚拟专用服务器）上，而不是桌面电脑上的原因。持有记忆并运行计划任务的机器人，在您休息时也必须能够访问。笔记本电脑进入睡眠状态后，队列就会停止处理。

截至 2026 年 8 月，Rakazo 仍处于早期测试阶段，因此应将本文视为可用的部署方案，而不是成熟的成品设备。整个技术栈都使用 TypeScript：Web 应用使用 React 19 和 Vite，API 使用 Hono，数据库使用带 Prisma 的 Postgres，账户系统使用 Better Auth，后台任务使用 Graphile Worker。Graphile Worker 将队列存储在 Postgres 中，因此无需运行 Redis，也无需维护第二个数据存储。.env.example 设置 WAKEUP_DRIVER=graphile，这意味着机器人唤醒会对应一个由 Postgres 支持的任务。停止 Postgres 后，所有计划中的机器人操作也会随之停止。如果您希望从各个组件自行组装代理，而不是运行他人开发的产品，从组件自行构建代理是另一条路线。

为什么 1 GB 方案无法承载这些服务

先统计进程数量。Postgres 占用一个进程。API 是一个 Node 进程。worker 是第二个。Web 应用是第三个。sandbox supervisor 是第四个。随后，每个正在运行的 bot 都会启动一个容器，其中包含图形化 Linux 桌面和浏览器。

项目自己的托管文档给出了一个明确的数字：当 E2B 负责 bot 桌面时，2 vCPU 和 4 GB 内存的机器足以运行 API、worker 和 Postgres。这只是控制平面的资源需求，实际占用较高的部分托管在其他位置。设置 SANDBOX_PROVIDER=docker 后，这些桌面会迁移到您的 VPS，因此 4 GB 只能作为最低配置，而不是目标配置。如果计划让多个 bot 同时保持运行，请从 8 GB 开始，并在 bot 工作期间使用 docker stats 测量实际占用。真正推高内存需求的是 sandbox 中的浏览器，因此仅查看规格表无法确定所需配置。关于如何为 agent 工作负载评估服务器配置，agent VPS 实际需要多少 RAM 和 CPU会详细介绍测量方法。

有一个设置可以防止资源占用继续增加。.env.example 会附带 SANDBOX_IDLE_MS=600000，并在注释中说明：经过指定的空闲毫秒数后，它会暂停 E2B computer，或停止 Docker computer。空闲 10 分钟后，computer 就会被释放。接受的最小值为 30000。没有这个设置，您曾经启动过的每个 bot 都会永久占用内存。

磁盘空间也需要计算。sandbox 镜像、Node modules 和 Postgres 卷共用同一块磁盘，因此 40 GB 是一个合理的起始配置。

克隆前固定版本

Rakazo 更新很快，main 不是一个发布版本。截至 16 August 2026，该仓库只有一个标签：v0.1.0-beta。该标签于 13 August 2026 发布，并标记为预发布版本。

git clone https://github.com/elie222/rakazo.git
cd rakazo
git checkout 53b119a68d9ef843d23aa3b7e3719b6be7b51fdb
git log -1 --format='%H %ci'

该提交就是 v0.1.0-beta 所指向的提交。请固定提交，而不是固定分支或标签。分支会在下一次 git pull 时发生变化，标签是可移动的标识，维护者可以重新指向其他提交，因此二者都不能标识一个可恢复的代码树。提交标识符不会变化。请将它与其他服务器信息记录在一起，因为升级导致故障时，最简单的修复方法是 git checkout <old commit> 并重新构建；但这只有在知道哪个提交可正常工作时才有效。精确固定提交是 beta 阶段的额外成本，并非通用规则。对于按计划发布正式版本的项目，也可以固定到已发布的标签，例如 较小的自托管堆栈 openGym 就采用这种方式。

要求：Node 22、pnpm 9 和 Docker

node -v
pnpm -v
docker --version

package.json 声明了 "engines": { "node": ">=22" } 和 "packageManager": "pnpm@9.15.0"，因此 node -v 必须输出 v22 或更高版本。Ubuntu 软件仓库中的 Node 软件包通常低于此版本，因此请从 NodeSource 或 nvm 安装。pnpm 通过 corepack 随 Node 一起提供：

corepack enable
corepack prepare pnpm@9.15.0 --activate

Docker Engine 和 compose 插件可以满足其余要求，同时您的用户必须能够访问 daemon。如果 docker ps 返回 permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock，请将您的用户加入 docker 组，然后打开新的登录 shell。请先了解这会授予什么权限：属于 docker 组实际上等同于拥有该机器的 root 权限，因为该组中的任何人都可以启动一个挂载主机文件系统的容器。

配置 .env，然后启动 Postgres

cp .env.example .env
chmod 600 .env

在任何服务接入网络前，必须修改两个值。.env.example 会提供 BETTER_AUTH_SECRET=replace-with-32-plus-character-secret 和 ENCRYPTION_KEY=replace-with-64-char-hex-or-passphrase。Rakazo 在开发环境之外会拒绝这些占位值，因此配置不完整的部署会直接报错，而不会使用已发布在代码仓库中的密钥运行。

openssl rand -base64 48
openssl rand -hex 32

然后单独启动数据库并运行迁移。

docker compose --env-file .env -f infra/compose/docker-compose.yml up postgres -d
pnpm install
pnpm db:generate
pnpm db:migrate
pnpm sandbox:build

pnpm sandbox:build 会构建机器人计算机镜像，该镜像在 package.json 中定义为 docker build -t rakazo/computer:local infra/sandboxes/computer。这是一个图形化镜像，因此首次构建会下载大量内容并需要一段时间。使用 docker image ls rakazo/computer 确认镜像已成功生成；该命令应输出一行。

Compose 文件将 Postgres 发布为 127.0.0.1:5433:5432，这只允许通过 loopback 访问。保持此配置不变。开发环境凭据是 rakazo:rakazo，并且已存储在代码仓库中。如果 Postgres 端口可从互联网访问，同时使用已公开的密码，扫描器会在数小时内发现它。生产环境的 Compose 文件改为读取 POSTGRES_PASSWORD，进入生产配置时将其设置为随机字符串。

首次运行

pnpm dev

这会启动4项服务：监听3100端口的 API、Graphile Worker、监听5173端口的 Vite Web 应用，以及监听7091端口的沙箱监管程序。应用地址为 http://127.0.0.1:5173，打开后应显示登录页面。

在 VPS 上，您并不在该服务器本机上操作，因此不应通过公开5173端口访问应用。请改为从自己的计算机通过 SSH（安全 shell）转发端口。

ssh -L 5173:127.0.0.1:5173 -L 3100:127.0.0.1:3100 you@your-server

请注意这两种运行方式的区别。pnpm dev 会在主机上运行 Vite，并仅绑定本地地址。compose 文件中的 web 服务会在所有网络接口上发布 5173:5173。如果在公网 VPS 上启动完整的开发 compose 堆栈，应用就会暴露在公网中。因此，对于需要持续运行的服务，请使用生产配置文件及其反向代理。

服务器上哪个沙箱提供商是安全的？

这是必须正确设置的一项配置。SANDBOX_PROVIDER 中的 .env 接受 4 个值。

• docker 是默认值。每个机器人都会在你的计算机上获得一个独立容器，该容器由生成的镜像 pnpm sandbox:build 构建。这是最快的自托管方案。
• e2b 会在 E2B 上运行机器人计算机，并需要 E2B_API_KEY。项目建议在公共部署或多用户部署中使用它，因为它能将机器人计算机与运行 API 和数据库的主机隔离。
• desktop 会直接在 API 和 worker 主机上执行机器人的命令。代码库中的说明十分明确：不要在公共服务器或共享服务器上使用它。
• fake 是用于测试的进程内模拟器。它不是运行时环境。

请严格按照桌面模式的警告执行。在桌面模式下，完全不存在隔离边界。因此，机器人会以运行 API 进程的用户身份执行 shell 命令，并拥有该用户的主目录、SSH 密钥、云凭据和 .env。机器人读取的网页文本会变成服务器上的命令。在服务器上使用桌面模式，最终会让机器人持有你的凭据。请只在你亲自使用的计算机上使用它，否则不要使用。切换提供商会在这条网页处理路径外增加一个容器，但不会关闭这条路径；为机器人提供独立的 SearXNG 搜索后端则可从搜索侧覆盖相同的提示注入攻击面。

docker 是真实的隔离边界，但并不完善。一个机器人无法读取另一个机器人的文件，因为每个机器人都有自己的容器。但是，负责创建这些容器的 supervisor 会挂载 /var/run/docker.sock，而控制主机 Docker socket 就等同于控制主机。因此，请将 supervisor 保持为私有服务。.env.example 将 SANDBOX_SUPERVISOR_TOKEN 记录为可选的独立服务凭据；为空时，该凭据默认为 BETTER_AUTH_SECRET。这意味着，如果将该密钥保留为占位符，就会使用任何人都能在 GitHub 上读取的字符串保护创建容器的服务。请同时设置这两个值。若要获得这里可用的最强隔离，请使用 e2b，或者为 Rakazo 提供一台不承载其他内容的计算机。这与在一次性 VM 中运行代码代理的理由相同：代理执行错误操作时，最廉价的应对方式是让它所在的计算机没有任何价值。

模型 API 密钥应放在哪里？

Rakazo 不负责模型计费。您需要自行提供密钥。.env.example 会设置 PI_DEFAULT_PROVIDER=openrouter，因此 OPENROUTER_API_KEY 是通常的存放位置，且各提供商的密钥都通过同一设置生效。

将密钥保存在 .env 中，不要写入任何会提交到仓库的文件。仓库中的两个 compose 命令都会传递 --env-file .env，因此值会进入容器，而不会写入由 git 跟踪的 YAML 文件。您也可以将 OPENROUTER_API_KEY 留空，然后在引导过程中将密钥粘贴到应用中。这也是 ENCRYPTION_KEY 必须使用真正的随机值，而不能使用随附占位值的另一个原因。

在机器人首次使用该密钥之前，先在提供商处为密钥设置支出上限。会循环运行的机器人也会持续产生费用，而按密钥设置的上限是唯一不依赖您持续监控的停止机制。为该密钥设置独立名称，以便单独撤销。如果您是在为团队而不是自己进行设置，OneCLI 为所有人的代理提供统一网关是同一问题的另一种解决方案，因为它会将提供商密钥集中在一个位置，而不是为每个人分别配置一个。

从开发模式切换到可长期运行的配置

代码仓库提供了生产环境的 Compose 文件。它会运行 Postgres、API、worker、Web 应用和 Caddy。Caddy 会自动获取 TLS（传输层安全）证书。该配置要求使用 E2B 提供 bot computers。

sudo DEPLOY_USER=deploy bash infra/compose/harden-host.sh
docker compose --env-file .env -f infra/compose/docker-compose.prod.yml up -d --build

harden-host.sh 会禁用 SSH 密码登录，为 SSH、HTTP 和 HTTPS 设置 UFW（uncomplicated firewall）规则，启用 fail2ban，并应用 AppArmor 配置文件。运行前请先阅读该脚本，因为它会改变登录方式。运行期间请保持第二个 SSH 会话处于打开状态。

生产环境的 .env 比开发环境的要求更多。自托管文档列出了最低要求。

NODE_ENV=production
RAKAZO_HOST=app.example.com
BETTER_AUTH_URL=https://app.example.com
WEB_ORIGIN=https://app.example.com
API_URL=https://app.example.com
POSTGRES_PASSWORD=<random>
BETTER_AUTH_SECRET=<random>
ENCRYPTION_KEY=<random>
E2B_API_KEY=<your key>
OPENROUTER_API_KEY=<your key>
SANDBOX_PROVIDER=e2b
AGENT_RUNTIME=pi
DATA_DIR=/data

在首次运行 up 前，先将 A 记录指向此服务器。Caddy 会为 RAKAZO_HOST 中的名称申请证书。如果该名称未解析到此服务器，或端口 80 未对外开放，申请就会失败。

还要设置 SIGNUP_ALLOWLIST=you@example.com。SIGNUPS_ENABLED=true 的默认值会导致使用公网名称的实例接受任何找到它的人注册，并为每个新账户分配一台 computer。请先配置允许列表。之后如有需要，再放宽限制。如果同一台服务器上已经运行多个服务，不希望为每个应用分别维护允许列表，可以在它们前面部署 Authentik 实例，将这项决策交给代理层。不过，Authentik 位于 Rakazo 自有的 Better Auth 账户系统前面，而不是替代该系统。

将仓库中的 docs/self-host.md 视为生产环境设置的权威来源，因为它会随代码变化，而本指南不会同步更新。由于实际工作由 Compose 完成，常规规则仍然适用；VPS 的 Docker Compose 基础知识解释了为什么当一个堆栈需要连续数月无人维护时，--env-file 和命名卷会更加重要。

备份

Postgres 和 data/ 目录构成整个实例。

./scripts/backup.sh
./scripts/restore.sh backups/BACKUP_TIMESTAMP

backup.sh 会转储 Postgres，并将 data/ 归档。对于依赖的机器，请将 infra/compose/backup-prod.sh 安装为 /usr/local/sbin/rakazo-backup，并使用仓库提供的定时器，这样就无需手动处理轮换。与数据库位于同一磁盘上的备份不是真正的备份，因此请将其复制到服务器之外。然后在备用服务器上执行一次恢复，确保在真正需要时可以使用。

失败原因及你将看到的现象

pnpm db:migrate无法连接数据库。 迁移报告无法连接到 127.0.0.1:5433 上的数据库服务器。原因可能是 Postgres 容器未运行，也可能是容器已运行但尚未就绪。运行 docker compose --env-file .env -f infra/compose/docker-compose.yml ps，查看 postgres 服务是否报告 healthy，因为 compose 文件为该服务配置了每三秒运行一次的健康检查。容器反复重启通常表示 pgdata 卷是使用不同的凭据创建的。docker compose ... down -v 会清除该卷，同时删除其中的数据。

端口已被占用。 如果其他程序占用了 5433，启动 Postgres 时会失败并显示 bind: address already in use。最常见的原因是之前的 Rakazo 堆栈仍在运行，而你忘记停止它。sudo ss -lntp | grep 5433 可显示占用该端口的进程。

机器人始终无法获得计算机。 使用 SANDBOX_PROVIDER=docker 且未提供 rakazo/computer:local 镜像时，没有可启动的内容。docker image ls rakazo/computer 会在一行中说明原因，pnpm sandbox:build 可修复该问题。如果 supervisor 无法访问 Docker socket，也无法创建容器；错误消息会指出路径：permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock。

长命令执行到一半退出。 .env.example 设置了 SANDBOX_COMMAND_TIMEOUT_MS=300000，因此机器人计算机中的单条命令运行五分钟后就会被终止。对于耗时较长的构建，应适当增大该值，不要直接认为沙箱已崩溃。

pnpm install以令人困惑的方式失败。 首先检查 node -v。工作区声明了 >=22，而旧版本的 Node 会在依赖代码中失败，不会直接显示版本不兼容信息。

本地登录成功，但通过域名无法登录。 BETTER_AUTH_URL、WEB_ORIGIN 和 API_URL 都必须与地址栏中的地址使用相同的公网来源，包括 scheme。通常是其中某一项仍保留过时的 http://127.0.0.1:5173，导致会话始终无法保持。

更新固定版本的代码检出

自托管文档中的升级流程很简短：拉取新源代码，运行数据库迁移，然后重启 API 和 worker。

./scripts/backup.sh
git fetch --all
git checkout NEW_COMMIT_SHA
pnpm install
pnpm --filter @rakazo/db migrate
docker compose --env-file .env -f infra/compose/docker-compose.prod.yml up -d --build

先备份。迁移会向前推进，而 beta 版本不会提供可依赖的回滚路径。在应用这些更改前，先阅读固定 SHA 与新 SHA 之间的提交记录。这个项目还很早期，可能会在不提前通知的情况下重命名环境变量；缺少变量时，服务可能会启动后立即退出。如果您还在决定是否应该运行 Rakazo，请参阅自托管 AI agent 汇总，其中介绍了这一类别中的其他项目，以及持续运行每个项目的成本。

FAQ

我可以在 1 GB VPS 上运行 Rakazo 吗？

不可以。Postgres、API、worker、sandbox supervisor 和 web app 会同时运行；使用 SANDBOX_PROVIDER=docker 时，每个处于唤醒状态的 bot 还会额外占用一个包含图形桌面和浏览器的容器。项目文档说明，只有在 E2B 托管 bot 桌面的情况下，2 vCPU 和 4 GB 内存才足以运行 API、worker 和 Postgres。对于控制平面，应将 4 GB 视为最低配置。如果桌面运行在您自己的机器上，则需要更高配置。

在服务器上使用桌面 sandbox 提供程序安全吗？

不安全。desktop 会以运行该进程的用户身份，直接在 API 和 worker 主机上执行 bot 的命令；该用户可访问的文件和凭据也都可能被访问。仓库明确表示，不要在公网服务器或共享服务器上使用它。请使用 docker 为每个 bot 创建一个容器；如果需要允许多人登录，请使用 e2b。

我应该安装哪个版本的 Rakazo？

截至 16 August 2026，只有一个标签 v0.1.0-beta。该标签于 13 August 2026 发布，并标记为预发布版本。请检出它指向的提交 53b119a68d9ef843d23aa3b7e3719b6be7b51fdb，不要跟踪 main。分支可能在您使用期间继续变化，标签也可能被重新指向，因此二者都不能标识一个可稳定返回的代码树。请记录该提交，因为只有知道哪个提交正常工作，才能回滚。

我应该在哪里放置 OpenRouter API key？

将其放在 .env 中，变量名为 OPENROUTER_API_KEY；不要将其写入会提交到仓库的 compose 文件。仓库中的两个 compose 命令都会传递 --env-file .env，因此该值可以进入容器，而不会写入受版本控制的 YAML 文件。您也可以将其留空，然后在 onboarding 期间将 key 粘贴到应用中。请在提供商处为该 key 设置消费上限，因为陷入循环的 bot 会持续调用模型，直到某个机制将其停止。

我需要域名和 TLS 吗？

如果不只是进行首次测试，则需要。生产 compose 文件会运行 Caddy 并自动获取证书，同时 RAKAZO_HOST、BETTER_AUTH_URL、WEB_ORIGIN 和 API_URL 都必须使用同一个公网 HTTPS origin。首次查看时可以跳过域名：运行 pnpm dev，然后通过 SSH 转发 5173 端口，而不是将其发布到公网。