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

Rakazo 自架教學:VPS 部署與硬體需求建議

完整指南教您在 VPS 上自架 Rakazo AI 機器人。涵蓋 Node 22、pnpm、Postgres 與 Docker Compose 配置,並分析為何 1GB RAM 無法負荷其運算需求。

Rakazo 自架運作架構

自架 Rakazo 意味著在單一台 Linux 伺服器上執行五個組件:PostgreSQL、Graphile Worker 程序、API、網頁應用程式,以及作為機器人運算環境的沙盒容器。Rakazo 是 Grok Bot 的開源替代方案,由 elie222 依據 Apache 2.0 授權發布。每個機器人擁有獨立的對話、記憶、常規與歷史紀錄;除非配置了 Private Computer,否則會與工作區內的其他機器人共用一個 Team Computer,並可產生對等節點或短暫存在的子代理(subagent)。若您對記憶、子代理與工具呼叫等術語感到陌生,建議先花一個下午閱讀 代理運作機制的分階段指南,因為只有理解機器人啟動時的行為,才能正確設定下述參數。

這正是為何此服務應部署於 VPS(虛擬專用伺服器)而非桌上型電腦的原因。機器人需要維護記憶並執行排程工作,因此必須在您睡眠時保持連線。若筆記型電腦進入休眠,佇列將會中斷。

截至 2026 年 10 月,Rakazo 仍將自身定義為 beta 版本,儘管目前已發布穩定版編號的 release,請將此視為開發中的設定而非成品。整個技術堆疊皆為 TypeScript:網頁應用程式使用 React 19 與 Vite,API 使用 Hono,資料庫使用 Postgres 搭配 Prisma,帳號系統使用 Better Auth,背景任務則由 Graphile Worker 處理。Graphile Worker 將佇列儲存於 Postgres 內部,因此無需執行 Redis 或其他額外的資料儲存服務。.env.example 設定了 WAKEUP_DRIVER=graphile,這代表機器人的喚醒動作是由 Postgres 支援的任務。若停止 Postgres,所有排程中的機器人動作也會隨之停止。若您傾向於自行組裝代理而非執行現成的產品,從組件建構您自己的代理 是另一種選擇。

為什麼 1 GB 方案無法容納這些元件

先計算程序數量。Postgres 是一個程序。API 是一個 Node 程序。worker 是第二個。web app 是第三個。sandbox supervisor 是第四個。接著是 bots 使用的電腦:預設為一個共用的 Team Computer 容器,其中執行圖形化 Linux 桌面;每個目前啟用的 bot 都會使用獨立的 X display 和 Chrome 程序。

專案的 self-host 文件已不再提供主機規格。v0.3.5 的文件在 27 October 2026 查閱時,只列出軟體需求。文件提供的是每台電腦的上限:使用 Docker sandboxes 時,RAKAZO_COMPUTER_MEMORY 預設為 2g,RAKAZO_COMPUTER_CPUS 預設為 2。這個上限套用到每台電腦,而不是每個 bot。每個 workspace 預設取得一台 Team Computer,每個啟用中的 Team bot 都會在其中執行自己的桌面與瀏覽器,因此所有 bot 共用這 2 GB 與 2 個核心。只有移至 Private Computer 的 bot,才會獲得專屬的容器與資源上限。設定 SANDBOX_PROVIDER=docker 後,這些桌面會移至你的 VPS,並與 control plane 共用資源,因此 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 實際需要多少 RAM 與 CPU,其中會詳細說明測量方式。

有一項設定可避免情況進一步惡化。.env.example 預設提供 SANDBOX_IDLE_MS=600000,其註解表示電腦會在閒置達到指定的毫秒數後暫停或停止。閒置 10 分鐘後,電腦就會停止。可接受的最小值為 30000,設定為 0 則停用閒置睡眠。同一則註解建議 Docker self-host 使用 0,因為閒置電腦不會產生費用,長時間執行的應用程式與工作階段也能保持運作。但這只適用於費用,不適用於記憶體。在小型 VPS 上,請保留計時器;否則,你曾啟動的每台電腦,以及其中的每個瀏覽器,都會持續執行。

磁碟空間也必須計算。sandbox image、Node modules 與 Postgres volume 共用同一個磁碟,因此 40 GB 是合理的起始值。

在複製前固定版本

Rakazo 更新快速,而 main 並不是正式發行版本。截至 9 November 2026,v0.8.0(published on 4 November 2026)是標示為 Latest 的版本。本指南固定使用 v0.3.5,published on 25 October 2026。

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

該 commit 就是 v0.3.5 所指向的版本。請固定 commit,不要固定 branch 或 tag。下一次 git pull 時,branch 可能在你不知情的情況下變更;tag 也是可移動的標籤,維護者可以重新指向其他位置,因此兩者都無法識別出你日後能返回的 tree。Commit identifier 不會移動。請將它記錄在其他伺服器資訊旁,因為升級造成問題時,最簡單的修復方式是 git checkout <old commit> 並重新建置;但這只有在你知道哪個 commit 正常運作時才有效。固定版本的 README 將 Rakazo 標示為 beta,因此值得花少量時間精確固定版本。若專案長期維持明確的正式發行紀錄,也可以改用已發布的 tag;較小型的自架堆疊,例如 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 plugin 即可涵蓋其餘需求。自架服務文件要求 Docker Engine 26 或更新版本,以及 API 1.45 或更新版本,才能使用 bot home volume subpaths,另外還需要 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 留空。這些預留位置全部都已發布在 repository 中,因此保留任何一個預留位置進行部署,都等於使用任何人都能讀取的 secret。請為每個項目設定各自的隨機值。ENCRYPTION_KEY 必須是 64 個隨機十六進位字元,openssl rand -hex 32 會準確輸出所需格式。其他 secret 需要 32 個以上的字元,因此請針對每個項目各執行一次 base64 指令。兩個 Postgres 密碼則依 self-host 文件的要求使用 URL-safe 值;最後一行會產生這類值,因此也請針對每個密碼各執行一次。資料庫有兩組登入帳號。DATABASE_MIGRATION_URL 會提供為 postgres://rakazo:REPLACE_WITH_POSTGRES_PASSWORD@127.0.0.1:5433/rakazo,這是負責執行 migrations 的 owner;DATABASE_URL 則提供為 postgres://rakazo_app:REPLACE_WITH_POSTGRES_APP_PASSWORD@127.0.0.1:5433/rakazo,這是應用程式自己的登入帳號,沒有 superuser 權限,並受 row-level security 限制。請將每個密碼填入對應的 URL。pnpm db:migrate 會使用你設定的密碼建立 rakazo_app 登入帳號。

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

接著單獨啟動資料庫,並執行 migrations。

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 computer image。這是 graphical image,因此第一次建置會下載大量內容並需要一些時間。使用 docker image ls rakazo/computer 確認建置結果;它應輸出一列。

基礎 compose file 完全不發布 Postgres port。該指令中的 docker-compose.postgres-host.yml overlay 會將它發布為 127.0.0.1:5433,且僅限 loopback,因此 host 端工具,例如 pnpm db:migrate 和 pnpm dev,才能連線到它。請維持此設定。若 .env 中沒有 POSTGRES_PASSWORD,Compose 會拒絕啟動 Postgres;但可從網際網路連線的 Postgres port 會招致密碼攻擊。production compose file 讀取相同的變數,且不發布任何 database port。

第一次執行

pnpm dev

這會啟動 4 個項目:3100 埠上的 API、Graphile Worker、5173 埠上的 Vite web app,以及預設在 7091 埠上的 sandbox supervisor。如果這些埠已被占用,pnpm dev 會選擇其他可用的連續埠區段,並輸出 URL。使用預設埠時,應用程式位於 http://127.0.0.1:5173,你應該會看到登入頁面。

在 VPS 上,你並不位於該機器上,也不應公開發布 5173 埠來連線。請改用 SSH(secure shell)從自己的機器轉送這些埠。

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

請注意這幾種執行方式的差異。pnpm dev 會在 host 上執行 Vite,並只繫結本機。開發用 compose file 的 web service 會發布 127.0.0.1:5173:5173,其 api service 則 127.0.0.1:3100:3100,兩者都只繫結 loopback,因此使用相同的 tunnel 即可。Production file 中,web app 不會發布 host port,只會在自身的 networks 上向 containers 暴露 5173;只有 Caddy 會發布 80 和 443 埠。因此,任何要持續執行的部署都應使用 production file 及其 reverse proxy。

哪個 sandbox provider 適合在伺服器上安全使用?

這是最需要正確設定的一項。SANDBOX_PROVIDER 在 .env 中預設為 docker,而固定版本的 checkout 也支援 Railway,以及 self-host 文件中列出的其他 provider。

  • docker 是預設值。Bot computer 會在你的機器上以 container 執行;container 由 pnpm sandbox:build 建立的 image 建置,並由 supervisor 執行。工作區中的 bot 預設共用一台 Team Computer,只有在 Private Computer 上,bot 才會取得專用 container。不需要 E2B 帳戶。
  • e2b 會在 E2B 上執行 bot computer,並需要 E2B_API_KEY。在 v0.3.5 中,只要提供該 key,factory 就會在 production 接受此設定,且沒有 NODE_ENV 限制。self-host 文件指出,這適合公開或多使用者的 production,因為 bot computer 不會接觸執行 API 與 database 的 host。
  • daytona、createos 和 boat 是其他遠端 provider,各自需要專用 key:DAYTONA_API_KEY、CREATEOS_SANDBOX_API_KEY 或 BOAT_API_KEY。
  • railway 會在 Railway 上執行 computer,並需要 RAILWAY_API_TOKEN,以及在 API 和 worker 上明確選取的 RAILWAY_ENVIRONMENT_ID。請為 sandbox 使用專用的 Railway project 或 environment。
  • desktop 會如文件所述,直接在 API 和 worker host 上執行 bot 的命令。在 v0.3.5 中,除非 NODE_ENV 為 development 或 test,否則 API 和 worker 會拒絕此設定;但 .env.example 會隨附 NODE_ENV=development,因此執行 pnpm dev 的伺服器仍會接受此設定。請勿在公開或共用的服務上啟用它。
  • fake 僅供驗證使用,是 emulator,不是 runtime。
  • none 啟動產品時完全不需要 computer host。

請確實依照上述行為理解。在 desktop mode 中完全沒有隔離邊界,因此 bot 會以執行 API process 的使用者身分執行 shell command,並可存取該使用者的 home directory、SSH key、cloud credential 以及 .env。bot 讀取網頁中的文字後,可能會將其轉為伺服器上的命令。在伺服器上使用 desktop mode,等同於讓 bot 取得你的 credential。請只在你能直接操作的機器上使用,否則不要使用。切換 provider 會在這條網頁處理路徑外加上 container,但不會關閉該路徑;為 bot 提供專用的 SearXNG search backend,則可從搜尋端涵蓋相同的 injection surface。

docker 能在 bot 與 host 之間提供實際的隔離邊界,但 bot 彼此之間的隔離較弱。預設情況下,所有 bot 共用一台 Team Computer;computer runtime 文件指出,Team bot 共用 OS user、workspace、browser profile,以及 shell 和 X11 access,且每個 bot 的資料夾只用來整理工作,不是 security boundary。因此,任何 Team bot 都能讀取其他 Team bot 的檔案。需要獨立隔離的 bot 應使用 Private Computer;docker provider 會將其作為獨立的 sibling container,並配置專用 network。不過,建立這些 container 的 supervisor 會掛載 /var/run/docker.sock;self-host 文件也明確指出:存取該 socket 等同於控制 Docker host。因此,請將 supervisor 保持在私人網路中。.env.example 將 SANDBOX_SUPERVISOR_TOKEN 視為專用 credential,與 BETTER_AUTH_SECRET 不同;Docker sandbox 在 local development 以外的環境需要此 credential,而產品附帶的 placeholder 任何人都能在 GitHub 上讀取。請為它設定獨立的隨機值。若要取得此處可用的最強隔離,請使用 e2b,或為 Rakazo 提供一台不存放其他內容的機器。這也是在可丟棄的 VM 中執行 coding agent背後的相同理由:agent 做錯事時,最便宜的應對方式,就是讓它使用的機器沒有任何重要價值。

模型 API 金鑰應放在哪裡?

Rakazo 的選用模型額度計費功能,只有在同時設定兩個 Stripe secret 後才會啟用。金鑰由你自行提供。.env.example 會設定 PI_DEFAULT_PROVIDER=openrouter,因此 OPENROUTER_API_KEY 通常是存放位置,供應商金鑰也會透過相同設定運作。

請將金鑰存放在 .env,不要放入任何會提交的檔案。儲存庫中的兩個 compose 指令都會傳遞 --env-file .env,因此值會傳入容器,不會寫入由 git 追蹤的 YAML。你也可以將 OPENROUTER_API_KEY 留空,註冊後再於應用程式中連線模型;這也是 ENCRYPTION_KEY 必須使用真正的隨機值,而非隨附預留位置的另一個原因。

在 bot 首次使用金鑰前,先於供應商端為金鑰設定支出上限。bot 若陷入迴圈,就會持續產生費用。Rakazo 也提供 MAX_TOOL_CALLS_PER_TURN:設定正整數後,當某一輪超過工具呼叫額度時,會柔性停止該輪,但仍會產生最後的 assistant 訊息。未設定、空白或設為 0 時,則不設上限。此設定計算的是工具呼叫次數,不是費用,因此不能取代供應商的支出上限。請為此金鑰設定專用名稱,以便單獨撤銷。如果你是為團隊而非自己設定,OneCLI 將所有人的 agent 集中在同一個 gateway 前方是同一問題的另一種解法,因為它會將供應商金鑰集中存放,而不是每人各存一組。

從開發模式轉為可長期執行的環境

此儲存庫提供 production compose 檔案,會執行 Postgres、API、worker、web app,以及自動取得 TLS(transport layer security)憑證的 Caddy。只有 Caddy 會發布連接埠。預設情況下,bot computers 使用 E2B。選擇性啟用的 overlay infra/compose/docker-compose.prod.docker.yml 則會在同一個 stack 中改用本機 Docker computers;文件也警告,該 overlay 加入的 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 帳號,並在執行 script 前確認可以使用該帳號登入。harden-host.sh 會停用 SSH 密碼登入與 root 登入、限制 SSH 速率,透過 UFW(uncomplicated firewall)加入 SSH、HTTP 和 HTTPS 允許規則,同時保留現有的私有網路規則,並啟用 fail2ban、無人值守安全性更新、AppArmor 與 audit 規則。沒有 SSH_CONNECTION 時,該 script 會拒絕執行;因此指令會透過 sudo 傳入此參數。除非你在三分鐘內從新的 SSH 工作階段確認,否則它會回復防火牆變更。執行前請先閱讀內容,因為它會改變登入方式並重新載入 SSH。在新的 SSH 登入成功前,請保持 provider 的主控台開啟。

production .env 的需求比 development 版本多。self-host 文件列出以下最低需求,以及各項 secret。

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 record 指向伺服器。Caddy 會為 RAKAZO_HOST 中的名稱申請憑證;該名稱必須解析到這台主機,且 port 80(用於 HTTP validation)或 port 443(用於 TLS-ALPN validation)必須可從外部連線。這兩種 challenge 預設都已啟用,因此單獨關閉 port 80 並不能阻止透過 port 443 申請憑證。

從一開始就將 SIGNUP_ALLOWLIST 設為你自己的地址。.env.example 會提供 SIGNUPS_ENABLED=true,而且每次 API 啟動時都會從環境讀取這兩項設定。因此,如果 instance 使用公開名稱、開啟註冊且沒有 allowlist,任何找到它的人都能註冊。非空的 allowlist 會在每次啟動時套用,並取代已儲存的清單。allowlist signup 包含第一個帳號在內,都需要進行 mailbox verification,因此請在註冊前先設定 email delivery。沒有 email 時,文件建議先以 SIGNUPS_ENABLED=false 啟動,再使用文件提供的 server-side bootstrap command 建立帳號;該指令會建立一般且已驗證的帳號,不具備 server privileges。先設定 allowlist。之後若有需要,再放寬限制。如果你已在同一台主機上執行多個服務,希望維護一份使用者清單,而不是每個 app 各自維護 allowlist,可以在它們前方放置 Authentik instance,將這項決策移至 proxy;不過它位於 Rakazo 自己的 Better Auth 帳號之前,而不是取代這些帳號。

請將儲存庫中的 docs/self-host.md 視為 production settings 的權威來源,因為它會隨程式碼變更,而本指南不會同步更新。由於實際工作由 Compose 執行,一般規則仍然適用;VPS 的 Docker Compose 基礎說明了為何當 stack 需要閒置執行數月時,--env-file 與 named volumes 會更加重要。

備份

在此設定中,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;預設最多保留 3 個經驗證的快照,數量由 RAKAZO_BACKUP_KEEP 設定,總容量上限為 50 GiB,由 RAKAZO_BACKUP_MAX_GB 設定。每次執行前,它會清除未完成的快照與超過保留數量的歷史快照,因此不必手動輪替。它也能使用 age,透過你在 /etc/rakazo/backup.env 列出的公開接收者,對每份備份加密,讓伺服器寫入無法自行讀取的備份。請在你能控制的機器上產生該金鑰組,並將私密金鑰保存在伺服器之外。未設定接收者時,備份會維持明文,並記錄警告;但在首次建立加密備份後,若未設定接收者,後續執行會失敗,除非透過 RAKAZO_BACKUP_ALLOW_PLAINTEXT=1 明確允許使用明文。與資料庫位於同一磁碟上的備份不算備份,因此請將其複製到伺服器之外。接著在需要使用之前,先於備用伺服器上還原一次。

失敗原因與你會看到的現象

pnpm db:migrate 無法連線至資料庫。 Migration 回報無法連線至 127.0.0.1:5433 的資料庫伺服器。原因可能是 Postgres container 尚未啟動、已啟動但尚未就緒,或啟動時未套用 docker-compose.postgres-host.yml overlay;該 overlay 會將 5433 發布至 host。執行 docker compose --env-file .env -f infra/compose/docker-compose.yml ps,確認 postgres service 回報 healthy,因為 compose file 已設定每三秒執行一次 health check。如果 container 持續重新啟動,請查看其日誌:在遷移至 Postgres 18 前,固定版本的 Compose stack 不會在舊版 Postgres 16 volume 上啟動。docker compose ... down -v 會清除該 volume,也會一併刪除其中的資料。

連接埠已被占用。 啟動 Postgres 時,如果其他程式已占用 5433,bind: address already in use 會導致啟動失敗。最常見的原因是忘記停止較早建立的 Rakazo stack。sudo ss -lntp | grep 5433 會顯示使用中的程序。Overlay 會從 POSTGRES_HOST_PORT 讀取 host port,因此可以變更該連接埠,但 DATABASE_URL 和 DATABASE_MIGRATION_URL 也必須一併變更。

Bot 始終無法取得電腦。 使用 SANDBOX_PROVIDER=docker 卻沒有 rakazo/computer:local image 時,沒有可啟動的項目。docker image ls rakazo/computer 會用一行輸出說明原因,而 pnpm sandbox:build 可修正問題。如果 supervisor 無法連線至 Docker socket,也無法建立 container;訊息會指出該路徑: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 電腦中的單一命令執行 5 分鐘後就會逾時。若建置速度較慢,請提高這項設定,不要直接判定 sandbox 已當機。

pnpm install 以難以理解的方式失敗。 先檢查 node -v。Workspace 宣告 ^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 error 拒絕不支援的 Node 版本。

本機登入成功,但透過網域登入失敗。 BETTER_AUTH_URL、WEB_ORIGIN 和 API_URL 都必須與網址列顯示的公開 origin 相同,包括 scheme。通常是其中一項仍保留過期的 http://127.0.0.1:5173,導致 session 始終無法維持。

固定版本 checkout 的更新方式

針對從 checkout 建置的正式環境 Compose stack,自架文件中的升級流程很簡短:拉取新的原始碼,然後重新建置並重新啟動 API、worker 與 web app。API 啟動時會執行 migration,因為它的啟動命令會先套用 migration,再開始提供服務。

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

請先備份。Migration 只會向前套用,而 beta 版本不提供可依賴的回復路徑。如果你的 checkout 早於 30 August 2026,包含 v0.1.0-beta commit,請在升級前閱讀文件中關於 20260830200000_space_scope_names_and_user_credentials migration 的說明。這是協調式切換,因此請先停止舊的 API 與 worker,並執行文件提供的 Space 隱私邊界檢查。若要從早於獨立 app login 的 checkout 升級,請在重新建置前於 .env 設定 POSTGRES_APP_PASSWORD;正式環境 Compose 檔案未設定該值時會拒絕啟動。source-checkout 與正式環境 Compose 檔案也會執行 Postgres 18;現有的 Postgres 16 安裝必須先依照文件中的 infra/compose/upgrade-postgres.sh 程序處理,才能在新的配置中啟動。採用新版本前,請閱讀固定 SHA 與新 SHA 之間的 commit,因為這個專案仍相當新,可能未公告就重新命名環境變數,而缺少變數會表現為服務啟動後立即結束。如果你仍在評估 Rakazo 是否適合執行,自架 AI agent 的整理說明了這個類別還有哪些選項,以及維持各項服務運作的成本。

FAQ

我可以在 1 GB VPS 上執行 Rakazo 嗎?

不行。Postgres、API、worker、sandbox supervisor 和 web app 會同時執行;使用 SANDBOX_PROVIDER=docker 時,bots' computer 還會加入一個包含圖形桌面的 container。每個 active bot 都會在其中使用獨立的 X display 和 Chrome process,而全部內容都受限於預設的 2 GB memory 和 2 CPUs。自架文件 v0.3.5 沒有提供 host size。請將 4 GB 視為 control plane 的最低需求;如果 desktops 在你的機器上執行,則需要更高規格。

在伺服器上使用 desktop sandbox provider 安全嗎?

不安全。自架文件指出,desktop 會直接在 API 和 worker host 上執行 commands,因此 bot 會以執行該 process 的使用者身分運作,並能存取該使用者的 files 和 credentials。在 v0.3.5 中,API 和 worker 會在 development 和 test mode 以外拒絕使用它;但執行 pnpm dev 的伺服器處於 development mode,會接受它。請勿在公開或共用伺服器上啟用。若 bot 不得與 workspace 的其他 bots 共用 files,請使用 docker,為 bot 提供 Private Computer;若有超過 1 人登入,請使用 e2b。

我應該安裝哪個版本的 Rakazo?

截至 9 November 2026,最新 release 是 v0.8.0,published 4 November 2026,並標示為 Latest。若要依照本指南操作,請 checkout 固定的 v0.3.5 commit:f31e3c0699f086d663637c4107858c238a086fb3,不要追蹤 main 或 August v0.1.0-beta prerelease。Branch 會在你不知情的情況下變更,tag 也可以被重新指向,因此兩者都無法識別出你日後能返回的 tree。請記錄該 commit,因為只有知道哪個版本正常運作,才能 rollback。

我應該將 OpenRouter API key 放在哪裡?

放在 .env 中,名稱為 OPENROUTER_API_KEY;絕對不要放在你會 commit 的 compose file 中。Repository 中的兩個 compose commands 都會傳入 --env-file .env,因此該值會傳到 containers,而不會寫入受追蹤的 YAML。你也可以將它留空,並在 signup 後於 app 中連接 model。請在 provider 端為該 key 設定 spending limit,因為陷入迴圈的 bot 會持續呼叫 model,直到某個機制停止它。

我需要 domain name 和 TLS 嗎?

只要超過第一次測試,就需要。Production compose file 會執行 Caddy 並自動取得 certificates;請將 RAKAZO_HOST 設為 public hostname,並將 BETTER_AUTH_URL、WEB_ORIGIN 和 API_URL 設為相同的 public HTTPS origin。第一次查看時可以略過 domain:執行 pnpm dev,再透過 SSH 轉送 5173 埠,而不要發布該埠。

這篇文章對您有幫助嗎?