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 --versionpackage.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 --activateDocker 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:buildpnpm 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_TIMESTAMPbackup.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 埠,而不要發布該埠。