Rakazo 自托管 VPS 部署与配置要求

自托管 Rakazo 实际运行的组件

自托管 Rakazo 意味着在一台 Linux 服务器上运行五类组件：PostgreSQL、一个 Graphile Worker 进程、API、Web 应用，以及每个处于唤醒状态的机器人对应的一个沙箱容器。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 计算机，或停止 Docker 计算机。空闲 10 分钟后，计算机就会被释放。接受的最小值是 30000。没有这个设置，您启动过的每个 bot 都会永久占用内存。

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

克隆前固定版本

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

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> 并重新构建，但这只有在您知道哪个提交可以正常工作时才有效。

要求：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。机器人读取网页中的文本后，这些文本可能会变成您服务器上的命令。在服务器上使用桌面模式，可能导致机器人获得您的凭据。请仅在您实际操作的计算机上使用它，否则不要使用。

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 更需要设置为真正的随机值，而不能使用随软件提供的占位符。

在机器人首次使用该密钥之前，先在供应商处为密钥设置消费限额。陷入循环的机器人会持续产生消费，而按密钥设置的限额是不依赖您持续监控的唯一停止措施。为该密钥设置独立名称，以便单独撤销。

从开发模式转为可长期运行的部署

仓库提供了生产环境 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（简单防火墙）规则，启用 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 的默认值允许公开名称上的实例接受任何人的注册，因此每个新账户都会获得一台计算机。请先配置允许列表。如果需要，再放宽限制。

将仓库中的 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，因此机器人计算机中的单条命令运行五分钟后就会被终止。对于构建时间较长的任务，应提高该值，不要直接认为 sandbox 已崩溃。

pnpm install以难以判断的方式失败。 首先检查 node -v。工作区声明了 >=22，而较旧的 Node 会在依赖代码中失败，不会直接提示版本不匹配。

本地登录正常，但通过域名登录失败。 BETTER_AUTH_URL、WEB_ORIGIN和 API_URL必须都使用与地址栏相同的公网 origin，包括 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 应用会同时运行；使用 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 文件。您也可以将其留空，然后在初次设置过程中将 key 粘贴到应用中。请在提供商处为该 key 设置支出上限，因为陷入循环的 bot 会持续调用模型，直到某个机制将其停止。

我需要域名和 TLS 吗？

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