SSD Nodes Learn Hosting plans →
指南 Matt Connor作者: Matt Connor

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

了解如何在 VPS 上用 Docker Compose 部署 Rakazo,涵盖 Node 22、pnpm、Postgres、Graphile Worker、sandbox 提供商、密钥管理,以及为何 1 GB 不够、4 GB 仅是最低配置。

Rakazo 自托管实际运行的内容

Rakazo 自托管意味着在一台 Linux 服务器上运行五个组件:PostgreSQL、Graphile Worker 进程、API、Web 应用,以及作为机器人计算机的沙盒容器。Rakazo 是 Grok Bot 的开源替代方案,由 elie222 以 Apache 2.0 许可证发布。每个机器人都有自己的对话、记忆、例程和历史记录。除非为其分配 Private Computer,否则它会与工作区中的其他机器人共享一个 Team Computer。机器人还可以创建对等机器人或短生命周期的子代理。如果您不熟悉该句中 memory、subagent 和 tool call 的含义,建议先花一个下午阅读逐步了解代理实际如何工作,因为只有先理解机器人唤醒后会执行什么,下面的大多数设置才有意义。

这也是应将其部署在 VPS(虚拟专用服务器)上,而不是桌面电脑上的原因。持有记忆并运行计划任务的机器人必须在您休息时仍可访问。笔记本电脑进入挂起状态后,队列就会停止处理。

截至 2026 年 10 月,Rakazo 仍将自身描述为 beta,尽管现在已经发布带有稳定版本号的版本。因此,应将其视为可用的部署方案,而不是已经完成的设备。整个技术栈都使用 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 使用的计算机:默认情况下,这是一个共享的 Team Computer 容器,其中运行图形化 Linux 桌面;每个处于活动状态的 bot 还会使用独立的 X 显示和 Chrome 进程。

项目的自托管文档已不再给出主机规格。27 October 2026 检查的 v0.3.5 文档只列出了软件要求。该文档提供的是每台计算机的上限:使用 Docker sandbox 时,RAKAZO_COMPUTER_MEMORY 默认为 2g,RAKAZO_COMPUTER_CPUS 默认为 2。这个上限适用于每台计算机,而不是每个 bot。默认情况下,每个工作区有一个 Team Computer;每个处于活动状态的 Team bot 都在其中运行自己的桌面和浏览器,因此它们共享这 2 GB 内存和两个 CPU 核。只有迁移到 Private Computer 的 bot 才会获得独立的容器和独立上限。设置 SANDBOX_PROVIDER=docker 后,这些桌面会迁移到您的 VPS,并叠加在控制平面之上,因此 4 GB 只是最低配置,不是目标配置。如果计划同时保持多个 bot 运行,请从 8 GB 开始;提高 RAKAZO_COMPUTER_MEMORY,让共享计算机能够实际使用这些内存;bot 工作期间使用 docker stats 测量实际占用量。内存占用变化主要来自 sandbox 内的浏览器,因此规格表无法准确说明需求。若要避免小型主机同时运行过多浏览器,请设置正值 SANDBOX_TEAM_SCREEN_LIMIT,以限制 Docker Team Computer 上处于活动状态的桌面数量。默认提供的 0 不设置上限。如果整体内存紧张,RAKAZO_COMPUTER_MEMORY 也接受较小的值,例如 1536m。关于如何为 agent 工作负载评估主机规格,请参阅agent VPS 实际需要多少内存和 CPU,其中详细介绍了测量方法。

有一个设置可以防止情况进一步恶化。.env.example 提供的默认值是 SANDBOX_IDLE_MS=600000,其注释说明计算机会在空闲达到该毫秒数后暂停或停止。空闲 10 分钟后,计算机就会停止。接受的最小值是 30000,0 表示禁用空闲休眠。同一注释建议 Docker 自托管环境使用 0,因为空闲计算机不会产生费用,这样长期运行的应用和会话可以保持运行。但这只适用于费用,不适用于内存。在小型 VPS 上应启用此计时器,否则您启动过的每台计算机及其中的每个浏览器都会持续运行。

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

克隆前固定版本

Rakazo 更新很快,main 不是一个发行版本。截至 9 November 2026,v0.8.0 于 4 November 2026 发布,并标记为 Latest。本指南仍固定使用 v0.3.5,该版本于 25 October 2026 发布。

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

该提交就是 v0.3.5 所指向的提交。请固定提交,而不要固定分支或标签。下一次 git pull 时,分支可能已经发生变化;标签只是可移动的名称,维护者可以重新指向其他提交。因此,它们都不能唯一标识一个可返回的代码树。提交标识符不会移动。请将它记录在其他服务器信息旁边,因为升级导致故障时,最简单的修复方法是 git checkout <old commit> 并重新构建;但前提是你知道哪个提交可以正常工作。固定版本的 README 将 Rakazo 标为 beta,因此精确固定版本值得付出这点 effort。对于长期保持稳定、按计划发布版本的项目,也可以固定已发布的标签;较小的自托管堆栈 openGym就是这样做的。

要求:Node 22、pnpm 9 和 Docker

node -v
pnpm -v
docker --version

package.json声明了 "engines": { "node": "^22.22.2 || ^24.0.0 || >=26.0.0" } 和 "packageManager": "pnpm@9.15.0"。因此,node -v 必须输出 v22.22.2 或更高版本的 22.x、任意 v24,或 v26 及更高版本。低于 22.22.2 的 v22 不在支持范围内,README 也明确说明不支持 Node.js 23.x 和 25.x。请从 NodeSource 或 nvm 安装受支持的 Node 版本。Node 22 和 24 自带 Corepack;在 Node 26 及更高版本上,请先使用 npm install -g corepack 安装 Corepack。然后启用 pnpm:

corepack enable
corepack prepare pnpm@9.15.0 --activate

其余依赖由 Docker Engine 和 compose 插件提供。自托管文档要求 Docker Engine 26 或更高版本、API 1.45 或更高版本,以支持 bot home 卷子路径;同时还需要 curl 和 OpenSSL。您的用户还必须能够访问 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-random-hex-characters、SCREEN_PROXY_SECRET=replace-with-32-plus-character-screen-proxy-secret 和 SANDBOX_SUPERVISOR_TOKEN=replace-with-32-plus-character-supervisor-token,并将 POSTGRES_PASSWORD 和 POSTGRES_APP_PASSWORD 留空。仓库公开了所有这些占位符,因此保留其中任何一个的部署都在使用任何人都能读取的密钥。为每个占位符设置独立的随机值。ENCRYPTION_KEY 必须是 64 个随机十六进制字符,运行 openssl rand -hex 32 即可准确生成。其他密钥需要 32 个或更多字符,因此对每个密钥分别运行一次 base64 命令。对于两个 Postgres 密码,独立部署文档要求使用 URL 安全值,最后一行命令会生成这种值,因此也要分别运行一次。数据库有两个登录账号。DATABASE_MIGRATION_URL 默认值为 postgres://rakazo:REPLACE_WITH_POSTGRES_PASSWORD@127.0.0.1:5433/rakazo,这是用于运行迁移的所有者账号;DATABASE_URL 默认值为 postgres://rakazo_app:REPLACE_WITH_POSTGRES_APP_PASSWORD@127.0.0.1:5433/rakazo,这是应用自己的登录账号,没有 superuser 权限,并受行级安全策略限制。将每个密码分别填入对应的 URL。pnpm db:migrate 会使用你设置的密码创建 rakazo_app 登录账号。

openssl rand -base64 48
openssl rand -hex 32
openssl rand -hex 24

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

docker compose --env-file .env -f infra/compose/docker-compose.yml -f infra/compose/docker-compose.postgres-host.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 定义的 bot 计算机镜像。它是图形化镜像,因此首次构建会下载大量内容并耗时较长。使用 docker image ls rakazo/computer 确认镜像已生成;该命令应输出一行。

基础 compose 文件完全不发布 Postgres 端口。该命令中的 docker-compose.postgres-host.yml 覆盖文件会将其发布为 127.0.0.1:5433,且仅绑定到 loopback,因此主机上的 pnpm db:migrate 和 pnpm dev 等工具可以访问它。保持此配置不变。如果 .env 中没有 POSTGRES_PASSWORD,Compose 将拒绝启动 Postgres;但可从互联网访问的 Postgres 端口会招致密码攻击。生产环境的 compose 文件读取同一个变量,并且不发布数据库端口。

首次运行

pnpm dev

这会启动 4 个组件:监听 3100 端口的 API、Graphile Worker、监听 5173 端口的 Vite Web 应用,以及默认监听 7091 端口的沙箱监督器。如果这些端口已被占用,pnpm dev 会选择其他空闲端口段,并输出对应 URL。使用默认端口时,应用地址为 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 服务会发布 127.0.0.1:5173:5173,其 api 服务会 127.0.0.1:3100:3100,两者都只绑定回环地址,因此使用相同的 SSH 隧道即可访问。生产环境文件中的 Web 应用不会发布主机端口,只会在自身网络中向容器暴露 5173;只有 Caddy 会发布 80 和 443 端口。因此,对于需要持续运行的服务,请使用生产环境文件及其反向代理。

服务器上哪种沙箱提供商安全?

这是必须正确配置的设置。SANDBOX_PROVIDER 中的 .env 默认设置为 docker;固定版本的代码检出还支持 Railway,以及自托管文档中列出的其他提供商。

  • docker 是默认选项。Bot 计算机以容器形式运行在您的机器上,由 supervisor 根据 pnpm sandbox:build 构建并启动。默认情况下,同一工作区中的 bot 共享一个 Team Computer;只有在 Private Computer 上,bot 才会获得独立容器。不需要 E2B 账户。
  • e2b 会在 E2B 上运行 bot 计算机,并需要 E2B_API_KEY。在 v0.3.5 中,只要提供密钥,工厂模式即可在生产环境接受该选项,不受 NODE_ENV 限制。自托管文档称其适合公开或多用户生产环境,因为它会将 bot 计算机与运行 API 和数据库的主机隔离。
  • daytona、createos 和 boat 是其他远程提供商,各自需要对应的密钥:DAYTONA_API_KEY、CREATEOS_SANDBOX_API_KEY 或 BOAT_API_KEY。
  • railway 会在 Railway 上运行计算机,并需要在 API 和 worker 上设置 RAILWAY_API_TOKEN,同时显式选择 RAILWAY_ENVIRONMENT_ID。请为沙箱使用专用的 Railway 项目或环境。
  • desktop 会按照文档的描述,直接在 API 和 worker 主机上执行 bot 命令。在 v0.3.5 中,除非 NODE_ENV 为 development 或 test,否则 API 和 worker 会拒绝该选项;但 .env.example 会发布 NODE_ENV=development,因此运行 pnpm dev 的服务器仍会接受它。不要在公共或共享服务上启用它。
  • fake 仅用于验证的模拟器,不是运行时。
  • none 在完全没有计算机主机的情况下启动产品。

请按字面理解这一点。在桌面模式下,完全不存在隔离边界。因此,bot 会以运行 API 进程的用户身份执行 shell 命令,并拥有该用户的主目录、SSH 密钥、云凭据以及该用户的 .env。bot 读取网页中的文本后,这些文本就可能变成您服务器上的命令。在服务器上使用桌面模式,最终可能导致 bot 掌握您的凭据。请仅在您实际操作的机器上使用它,否则不要使用。切换提供商只是将容器放在这条网页路径外,而不是关闭这条路径;为 bot 提供独立的 SearXNG 搜索后端则可以从搜索侧覆盖相同的提示注入面。

docker 能在 bot 与主机之间提供真正的隔离边界,但 bot 之间的隔离较弱。默认情况下,所有 bot 共享一个 Team Computer;计算机运行时文档说明,Team bot 共享 OS 用户、工作区、浏览器配置文件以及 shell 和 X11 访问权限,并明确指出每个 bot 的目录只是用于组织工作,不是安全边界。因此,任何 Team bot 都可以读取其他 Team bot 的文件。需要独立隔离边界的 bot 应运行在 Private Computer 上;docker 提供商会将其作为独立的同级容器运行,并为其配置独立网络。不过,创建这些容器的 supervisor 会挂载 /var/run/docker.sock。自托管文档明确指出:访问该 socket 等同于控制 Docker 主机。因此,请确保 supervisor 仅供内部使用。.env.example 将 SANDBOX_SUPERVISOR_TOKEN 视为独立凭据,与 BETTER_AUTH_SECRET 不同;Docker 沙箱在本地开发之外的环境中需要该凭据,并且其默认值是任何人都能在 GitHub 上读取的占位值。请为它设置独立的随机值。若要获得此处可用的最强隔离,请使用 e2b,或者为 Rakazo 提供一台不承载其他内容的机器。这与在一次性 VM 中运行编码代理的理由相同:代理出错时,最廉价的应对方式是让它所运行的机器不具备任何价值。

模型 API 密钥放在哪里?

除非同时设置两个 Stripe 密钥,否则 Rakazo 的可选模型额度计费不会启用。密钥由您提供。.env.example 会设置 PI_DEFAULT_PROVIDER=openrouter,因此 OPENROUTER_API_KEY 通常是存放位置,提供商密钥也通过同一设置生效。

将密钥放在 .env 中,不要放入您提交的任何文件。仓库中的两个 compose 命令都会传递 --env-file .env,因此值会传入容器,不会写入由 git 跟踪的 YAML 文件。您也可以将 OPENROUTER_API_KEY 留空,并在注册后通过应用连接模型。这也是 ENCRYPTION_KEY 必须使用真实随机值而不能使用随附占位符的另一个原因。

在机器人首次使用密钥前,先在提供商处为该密钥设置消费上限。机器人陷入循环就会持续产生费用。Rakazo 还提供 MAX_TOOL_CALLS_PER_TURN:将其设为正整数,可在某次处理超过工具调用预算时软停止,同时仍生成最终的 assistant 消息。未设置、为空或设置为 0 时,不限制预算。该设置统计工具调用次数,而不是费用,因此不能替代提供商的消费上限。为此密钥设置独立名称,以便单独撤销。如果您是在为团队而不是自己配置,OneCLI 在所有人的 agent 前设置一个网关是同一问题的另一种解决方案,因为它将提供商密钥集中存放,而不是每人存放一份。

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

仓库提供了生产环境 Compose 文件,用于运行 Postgres、API、worker、Web 应用,以及自动申请 TLS(传输层安全)证书的 Caddy。该文件中只有 Caddy 会发布端口。默认情况下,机器人计算机使用 E2B。可选叠加文件 infra/compose/docker-compose.prod.docker.yml 会改为在同一堆栈中运行本地 Docker 计算机;文档警告,该文件添加的 supervisor 在主机上具有等同于 root 的权限。

sudo --preserve-env=SSH_CONNECTION DEPLOY_USER=deploy bash infra/compose/harden-host.sh
docker compose --env-file .env -f infra/compose/docker-compose.prod.yml \
  build --build-arg GIT_SHA=$(git rev-parse HEAD)
docker compose --env-file .env -f infra/compose/docker-compose.prod.yml \
  up -d --wait --pull never
curl --fail https://app.example.com/health

创建仅允许密钥登录的 deploy 账户,并在运行脚本前确认可以使用该账户登录。harden-host.sh 会禁用 SSH 密码登录和 root 登录、限制 SSH 连接速率,通过 UFW(不复杂防火墙)添加 SSH、HTTP 和 HTTPS 放行规则,同时保留现有的私有网络规则,并启用 fail2ban、无人值守安全更新、AppArmor 和审计规则。没有 SSH_CONNECTION 时,它会拒绝运行;因此命令会通过 sudo 传入该参数。除非您在三分钟内从新的 SSH 会话确认,否则它会回滚防火墙更改。运行前先阅读脚本,因为它会改变登录方式并重新加载 SSH。在新的 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
SIGNUPS_ENABLED=true
SIGNUP_ALLOWLIST=you@example.com
SANDBOX_PROVIDER=e2b
AGENT_RUNTIME=pi
WAKEUP_DRIVER=graphile
DATA_DIR=/data
RAKAZO_DEPLOY_DIR=/srv/rakazo
RAKAZO_IMAGE_TAG=local
POSTGRES_PASSWORD=<random, URL-safe>
POSTGRES_APP_PASSWORD=<random, URL-safe>
BETTER_AUTH_SECRET=<random>
ENCRYPTION_KEY=<64 random hex characters>
SCREEN_PROXY_SECRET=<random>
E2B_API_KEY=<your key>
OPENROUTER_API_KEY=<your key>

在首次 up 之前,将 A 记录指向该服务器。Caddy 会为 RAKAZO_HOST 中的名称申请证书;该名称必须解析到此服务器,并且外部必须可以访问 80 端口以进行 HTTP 验证,或访问 443 端口以进行 TLS-ALPN 验证。默认情况下两种验证方式都会启用,因此仅关闭 80 端口并不能阻止通过 443 端口申请证书。

从一开始就将 SIGNUP_ALLOWLIST 设置为您自己的地址。.env.example 默认启用 SIGNUPS_ENABLED=true,并且这两个设置会在每次 API 启动时从环境中读取。因此,如果实例使用公开名称、启用了注册且没有允许列表,任何找到它的人都可以注册。每次启动时都会应用非空允许列表,并替换已存储的列表。允许列表中的注册仍需验证邮箱,包括第一个账户,因此请在注册前配置邮件投递。如果没有邮件功能,文档建议先使用 SIGNUPS_ENABLED=false 启动,再使用文档提供的服务器端引导命令创建账户;该命令会创建普通的已验证账户,不授予服务器权限。先配置允许列表。如果需要,之后再放宽限制。如果您已经在同一台服务器上运行多个服务,并且希望维护一份人员列表,而不是为每个应用维护一份允许列表,可以在这些服务前面部署 Authentik 实例,将该决策交给代理层。不过,AuthentiK 位于 Rakazo 自有的 Better Auth 账户之前,而不是替代这些账户。

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

备份

在此配置中,Postgres 和 data/ 目录保存实例数据;恢复还需要 ENCRYPTION_KEY 以及所有已配置的内容主密钥,因此应在服务器之外保留副本。

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

backup.sh 会转储 Postgres,并将 data/ 归档。restore.sh 适用于开发用 Compose 堆栈:目标必须是空数据库,且应用服务必须已停止;它不会读取生产环境的备份文件。对于需要长期依赖的机器,请将 infra/compose/backup-prod.sh 安装为 /usr/local/sbin/rakazo-backup,并使用仓库提供的计时器。它会将经过验证的转储和应用数据归档写入 /var/backups/rakazo;默认最多保留三个经过验证的快照,该数量由 RAKAZO_BACKUP_KEEP 设置;总容量上限为 50 GiB,由 RAKAZO_BACKUP_MAX_GB 设置。每次运行前,它会清理未完成的快照和超出保留数量的历史记录,因此无需手动执行轮换。它还可以使用 age,为 /etc/rakazo/backup.env 中列出的公钥接收者加密每份备份,这样服务器写入的备份无法由服务器自身读取。请在您控制的机器上生成该密钥对,并将私钥保留在服务器之外。未配置接收者时,备份会以明文保存并记录警告;但完成首次加密备份后,如果未配置接收者,后续运行会失败,除非通过 RAKAZO_BACKUP_ALLOW_PLAINTEXT=1 明确允许明文备份。与数据库位于同一磁盘上的备份不是真正的备份,因此应将其复制到服务器之外。然后在需要恢复之前,先在备用服务器上执行一次恢复测试。

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

pnpm db:migrate无法连接数据库。 迁移操作报告无法连接到位于 127.0.0.1:5433 的数据库服务器。原因可能是 Postgres 容器未运行、容器已运行但尚未就绪,或者启动时未使用 docker-compose.postgres-host.yml overlay;该 overlay 会将 5433 发布到主机。运行 docker compose --env-file .env -f infra/compose/docker-compose.yml ps,检查 postgres 服务是否报告 healthy。Compose 文件为该服务配置了健康检查,每三秒执行一次。如果容器不断重启,请查看其日志:在迁移到 Postgres 18 之前,固定版本的 Compose 堆栈拒绝在旧的 Postgres 16 卷上启动。docker compose ... down -v 会清除该卷,同时也会删除其中的数据。

端口已被占用。 如果其他程序占用了 5433,启动 Postgres 时会因 bind: address already in use 失败。最常见的情况是之前的 Rakazo 堆栈仍在运行,而你忘记停止它。sudo ss -lntp | grep 5433 会显示占用该端口的进程。该 overlay 从 POSTGRES_HOST_PORT 读取主机端口,因此你可以修改该端口,但必须同时修改 DATABASE_URL 和 DATABASE_MIGRATION_URL。

bot 始终无法获得计算机。 使用 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,因此 bot 的计算机内运行的单条命令会在五分钟后被终止。对于构建时间较长的任务,应提高该值,不要直接假设 sandbox 已崩溃。

pnpm install以难以理解的方式失败。 首先检查 node -v。工作区声明了 ^22.22.2 || ^24.0.0 || >=26.0.0,因此 23.x、25.x 以及 22.22.2 之前的任何 22.x 版本都不在支持范围内。固定版本的 .npmrc 设置了 engine-strict=true,因此 pnpm install 会在应用依赖代码运行前,以 engine/version 错误拒绝不受支持的 Node 版本。

本地登录正常,但通过域名登录失败。 BETTER_AUTH_URL、WEB_ORIGIN 和 API_URL 都必须与地址栏中的地址使用相同的公共 origin,包括 scheme。通常是其中某一项残留的旧 http://127.0.0.1:5173,导致会话始终无法保持。

更新固定版本的代码检出

自托管文档中针对由代码检出构建的生产 Compose 栈,升级步骤很简单:拉取新源代码,然后重新构建并重启 API、worker 和 Web 应用。API 启动时会运行迁移,因为其启动命令会先应用迁移,再开始提供服务。

sudo /usr/local/sbin/rakazo-backup
git fetch --all --tags
git checkout NEW_COMMIT_SHA
export GIT_SHA=$(git rev-parse HEAD)
docker compose --env-file .env -f infra/compose/docker-compose.prod.yml \
  up -d --wait --pull never --build api worker web

先备份。迁移只会向前执行,而 beta 版本不提供可依赖的回滚路径。如果您的代码检出早于 30 August 2026,其中包括 v0.1.0-beta 提交,请在升级前阅读文档中关于 20260830200000_space_scope_names_and_user_credentials 迁移的说明。这是一次需要协调的切换,因此请先停止旧的 API 和 worker,然后运行文档提供的 Space 隐私边界检查。从早于独立应用登录功能的代码检出升级时,请在重新构建前,在 .env 中设置 POSTGRES_APP_PASSWORD;否则生产 Compose 文件会拒绝启动。源代码检出和生产 Compose 文件还会运行 Postgres 18;现有的 Postgres 16 安装必须先执行文档中的 infra/compose/upgrade-postgres.sh 流程,才能在新的布局下启动。在采用新版本前,请阅读固定 SHA 与新 SHA 之间的提交,因为如此年轻的项目可能在未提前说明的情况下重命名环境变量,而缺少变量会表现为服务启动后立即退出。如果您还在判断 Rakazo 是否适合运行,自托管 AI agent 汇总介绍了这一类别中的其他选项,以及维持每个选项运行的成本。

FAQ

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

不可以。Postgres、API、worker、沙箱监督器和 Web 应用会同时运行;使用 SANDBOX_PROVIDER=docker 时,机器人的计算环境还会添加一个包含图形桌面的容器。每个活动机器人都有独立的 X 显示和 Chrome 进程,所有这些组件都受默认的 2 GB 内存和 2 个 CPU 上限限制。v0.3.5 中的自托管文档没有说明主机规格。对于控制平面,请将 4 GB 视为最低配置;如果桌面环境运行在你的机器上,则需要更高配置。

在服务器上使用桌面沙箱提供程序安全吗?

不安全。自托管文档说明,desktop 会直接在 API 和 worker 所在的主机上执行命令。因此,机器人会以运行该进程的用户身份运行,并可以访问该用户的文件和凭据。在 v0.3.5 下,API 和 worker 会在开发和测试模式之外拒绝使用它;但运行 pnpm dev 的服务器处于开发模式,会接受该配置。不要在公网服务器或共享服务器上启用它。如果机器人不能与工作区中的其他机器人共享文件,请使用 docker,为机器人分配 Private Computer;如果需要允许多个人登录,请使用 e2b。

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

截至 9 November 2026,最新发行版本是 v0.8.0,于 4 November 2026 发布,并标记为 Latest。若要按照本指南操作,请检出固定的 v0.3.5 提交 f31e3c0699f086d663637c4107858c238a086fb3,而不要跟踪 main 或 August v0.1.0-beta 预发行版本。分支可能发生变化,标签也可能被重新指向其他提交,因此二者都不能唯一标识一个可返回的代码树。请记录该提交,因为只有知道哪个提交可以正常工作,才能回滚。

我应该在哪里配置 OpenRouter API key?

在 .env 中将其设置为 OPENROUTER_API_KEY,绝不要将其写入已提交的 compose 文件。仓库中的两个 compose 命令都会传递 --env-file .env,因此该值会进入容器,而不会写入受版本控制的 YAML 文件。你也可以将其留空,并在注册后通过应用连接模型。请在提供程序处为该 key 设置消费上限,因为陷入循环的机器人会持续调用模型,直到某个机制将其停止。

我需要域名和 TLS 吗?

如果要进行首次测试以外的使用,需要。生产环境 compose 文件会运行 Caddy 并自动获取证书;请将 RAKAZO_HOST 设置为公网主机名,并将 BETTER_AUTH_URL、WEB_ORIGIN 和 API_URL 设置为相同的公网 HTTPS origin。首次查看时可以跳过域名:运行 pnpm dev,然后通过 SSH 转发 5173 端口,而不要发布该端口。

这篇文章对您有帮助吗?