Cara Self-Host Rakazo AI Bot pada VPS Sendiri
Panduan lengkap memasang Rakazo menggunakan Node 22, pnpm, Postgres dan Graphile Worker dalam Docker Compose. Ketahui cara mengurus kunci API serta saiz VPS yang tepat.
Perkara yang sebenarnya dijalankan oleh Rakazo dalam self-hosting
Self-hosting Rakazo bermaksud menjalankan lima perkara pada satu pelayan Linux: PostgreSQL, proses Graphile Worker, API, aplikasi web, dan kontena sandbox yang berfungsi sebagai komputer untuk bot. Rakazo ialah alternatif sumber terbuka kepada Grok Bot, yang diterbitkan oleh elie222 di bawah lesen Apache 2.0. Setiap bot mempunyai perbualan, memori, rutin dan sejarahnya sendiri, berkongsi satu Team Computer dengan bot lain dalam ruang kerja kecuali jika ia diberikan Private Computer, serta boleh menjana rakan setara atau subagent yang berjangka hayat pendek. Jika istilah seperti memori, subagent dan panggilan alat (tool call) kedengaran asing dalam ayat tersebut, laluan berperingkat tentang cara ejen sebenarnya berfungsi wajar diluangkan masa selama satu petang terlebih dahulu, kerana kebanyakan tetapan di bawah hanya akan difahami sebaik sahaja anda dapat membayangkan apa yang dilakukan oleh bot apabila ia aktif.
Bahagian terakhir itulah sebabnya perkara ini perlu diletakkan pada VPS (virtual private server) dan bukannya pada komputer meja. Bot yang menyimpan memori dan menjalankan kerja berjadual perlu boleh dihubungi semasa anda tidur. Komputer riba yang memasuki mod gantung (suspend) akan menggugurkan baris gilir (queue).
Rakazo masih melabelkan dirinya sebagai beta setakat Oktober 2026, walaupun ia kini menerbitkan release dengan nombor versi stabil, jadi anggaplah ini sebagai persediaan yang berfungsi dan bukannya perkakas yang siap sepenuhnya. Keseluruhan stack menggunakan TypeScript: React 19 dan Vite untuk aplikasi web, Hono untuk API, Postgres dengan Prisma, Better Auth untuk akaun, dan Graphile Worker untuk tugasan latar belakang. Graphile Worker menyimpan baris gilirnya di dalam Postgres, jadi tiada Redis dan tiada storan data kedua yang perlu dijalankan. .env.example menetapkan WAKEUP_DRIVER=graphile, yang bermaksud bot yang aktif merupakan tugasan yang disokong oleh Postgres. Hentikan Postgres dan setiap tindakan bot yang berjadual akan terhenti bersamanya. Jika anda lebih suka memasang ejen daripada bahagian-bahagian komponen berbanding menjalankan produk orang lain, membina ejen anda sendiri daripada komponen adalah laluan yang satu lagi.
Mengapa pelan 1 GB tidak mencukupi
Kira proses yang terlibat. Postgres adalah satu proses. API adalah satu proses Node. Worker adalah proses kedua. Aplikasi web adalah proses ketiga. Penyelia sandbox adalah proses keempat. Kemudian, terdapat komputer bot: secara lalai, satu kontena Team Computer berkongsi desktop Linux grafik, dengan paparan X dan proses Chrome berasingan bagi setiap bot yang aktif.
Dokumentasi self-host projek ini tidak lagi menyatakan saiz hos. Dokumentasi di v0.3.5, yang disemak pada 27 Oktober 2026, hanya menyenaraikan keperluan perisian. Apa yang dinyatakan ialah had siling bagi setiap komputer: dengan sandbox Docker, RAKAZO_COMPUTER_MEMORY ditetapkan secara lalai kepada 2g dan RAKAZO_COMPUTER_CPUS kepada 2. Had siling itu terpakai untuk setiap komputer, bukan untuk setiap bot. Setiap ruang kerja mendapat satu Team Computer secara lalai, dan setiap bot Team yang aktif menjalankan desktop serta pelayar di dalamnya, jadi kesemuanya berkongsi 2 GB RAM dan dua teras tersebut. Hanya bot yang dipindahkan ke Private Computer akan mendapat kontena dan had silingnya sendiri. Tetapkan SANDBOX_PROVIDER=docker dan desktop tersebut akan berpindah ke VPS anda, di atas control plane, jadi 4 GB adalah tahap minimum dan bukannya sasaran. Mulakan dengan 8 GB jika anda bercadang untuk memastikan lebih daripada satu bot aktif, tingkatkan RAKAZO_COMPUTER_MEMORY supaya komputer kongsi tersebut benar-benar boleh menggunakan memori itu, dan ukur jumlah sebenar dengan docker stats semasa bot sedang bekerja. Pelayar di dalam sandbox adalah punca penggunaan memori meningkat, jadi helaian spesifikasi tidak akan memberitahu anda perkara sebenar. Untuk menghalang pelayan kecil daripada menjalankan terlalu banyak pelayar serentak, tetapkan nilai positif pada SANDBOX_TEAM_SCREEN_LIMIT, yang mengehadkan desktop aktif pada Docker Team Computer. Nilai 0 yang dibekalkan membiarkannya tanpa had. Jika memori terhad secara keseluruhan, RAKAZO_COMPUTER_MEMORY juga menerima nilai yang lebih kecil seperti 1536m. Bagi kaedah umum menentukan saiz pelayan untuk kerja ejen, berapa banyak RAM dan CPU yang sebenarnya diperlukan oleh VPS ejen menerangkan proses pengukuran tersebut dengan terperinci.
Satu tetapan menghalang keadaan ini daripada menjadi lebih buruk. .env.example dibekalkan dengan SANDBOX_IDLE_MS=600000, dan komennya menyatakan bahawa komputer akan dijeda atau dihentikan selepas tempoh milisaat melahu tersebut. Sepuluh minit melahu dan komputer akan ditamatkan. Nilai minimum yang diterima ialah 30000, dan 0 akan melumpuhkan mod tidur melahu. Komen yang sama mencadangkan 0 untuk self-host Docker, di mana komputer yang melahu tidak menelan kos, supaya aplikasi dan sesi yang berjalan lama kekal aktif. Ini terpakai untuk kos wang, bukan memori. Pada VPS yang kecil, biarkan pemasa tersebut aktif, kerana tanpanya setiap komputer yang pernah anda mulakan, dan setiap pelayar di dalamnya, akan terus berjalan.
Kapasiti cakera juga penting. Imej sandbox, modul Node dan volum Postgres berkongsi satu cakera, jadi 40 GB adalah titik permulaan yang munasabah.
Tetapkan versi sebelum anda melakukan clone
Rakazo berkembang dengan pantas dan main bukanlah satu release. Setakat 9 November 2026, v0.8.0, yang diterbitkan pada 4 November 2026, ialah release yang ditandakan sebagai Latest. Panduan ini kekal ditetapkan pada v0.3.5, yang diterbitkan pada 25 Oktober 2026.
git clone https://github.com/elie222/rakazo.git
cd rakazo
git checkout f31e3c0699f086d663637c4107858c238a086fb3
git log -1 --format='%H %ci'Commit tersebut adalah commit yang ditunjuk oleh v0.3.5. Tetapkan commit tersebut dan bukannya branch atau tag. Branch akan berubah tanpa pengetahuan anda pada git pull seterusnya, dan tag ialah label boleh alih yang boleh diubah oleh penyelenggara, jadi kedua-duanya tidak mengenal pasti tree yang boleh anda kembalikan. Pengecam commit tidak boleh berubah. Catatkan milik anda bersama fakta pelayan anda yang lain, kerana apabila naik taraf menyebabkan kerosakan, penyelesaian murahnya ialah git checkout <old commit> dan bina semula, dan itu hanya berfungsi jika anda tahu commit mana yang berfungsi. README yang ditetapkan memanggil Rakazo sebagai beta, jadi menetapkan versi ini dengan tepat adalah berbaloi dengan usaha kecil tersebut. Projek dengan rekod release yang sengaja dibuat boleh dikekalkan pada tag yang diterbitkan, iaitu apa yang dilakukan oleh stack self-hosted yang lebih kecil seperti openGym.
Keperluan: Node 22, pnpm 9, dan Docker
node -v
pnpm -v
docker --versionpackage.json mengisytiharkan "engines": { "node": "^22.22.2 || ^24.0.0 || >=26.0.0" } dan "packageManager": "pnpm@9.15.0". Oleh itu, node -v mesti memaparkan v22.22.2 atau versi 22.x yang lebih baharu, mana-mana v24, atau v26 ke atas. v22 yang lebih lama daripada 22.22.2 adalah di luar julat tersebut, dan README menyatakan secara jelas bahawa Node.js 23.x dan 25.x tidak disokong. Pasang versi Node yang disokong daripada NodeSource atau nvm. Corepack disertakan bersama Node 22 dan 24; pada Node 26 ke atas, pasangkannya dahulu dengan npm install -g corepack. Kemudian, aktifkan pnpm:
corepack enable
corepack prepare pnpm@9.15.0 --activateDocker Engine berserta pemalam compose merangkumi keperluan selebihnya. Dokumentasi self-host memerlukan Docker Engine 26 atau lebih baharu, API 1.45 atau lebih baharu, untuk subpath volum bot, berserta curl dan OpenSSL. Pengguna anda juga perlu mempunyai akses kepada daemon. Jika docker ps memberikan jawapan permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock, tambahkan pengguna anda ke dalam kumpulan docker dan buka sesi log masuk (login shell) yang baharu. Fahami implikasinya terlebih dahulu: keahlian dalam docker adalah setara dengan root pada mesin tersebut, kerana sesiapa sahaja dalam kumpulan itu boleh memulakan kontena yang melekapkan (mount) sistem fail hos.
Konfigurasi .env, kemudian mulakan Postgres
cp .env.example .env
chmod 600 .envBeberapa nilai perlu ditukar sebelum apa-apa dimulakan. .env.example dibekalkan dengan 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 dan SANDBOX_SUPERVISOR_TOKEN=replace-with-32-plus-character-supervisor-token, serta membiarkan POSTGRES_PASSWORD dan POSTGRES_APP_PASSWORD kosong. Setiap satu daripada pemegang tempat tersebut diterbitkan dalam repositori, jadi penggunaan yang mengekalkannya akan berjalan dengan rahsia yang boleh dibaca oleh sesiapa sahaja. Berikan setiap satu nilai rawak tersendiri. ENCRYPTION_KEY mestilah 64 aksara heksadesimal rawak, yang merupakan hasil tepat daripada openssl rand -hex 32. Rahsia lain memerlukan 32 aksara atau lebih, jadi jalankan baris base64 sekali untuk setiap satu. Bagi dua kata laluan Postgres yang diminta oleh dokumentasi self-host, gunakan nilai yang selamat untuk URL, yang diberikan oleh baris terakhir, jadi jalankan ia sekali untuk setiap satu juga. Pangkalan data mempunyai dua log masuk. DATABASE_MIGRATION_URL dibekalkan sebagai postgres://rakazo:REPLACE_WITH_POSTGRES_PASSWORD@127.0.0.1:5433/rakazo, pemilik yang menjalankan migrasi, dan DATABASE_URL sebagai postgres://rakazo_app:REPLACE_WITH_POSTGRES_APP_PASSWORD@127.0.0.1:5433/rakazo, log masuk aplikasi itu sendiri, yang tidak mempunyai hak superuser dan tertakluk kepada row-level security. Masukkan setiap kata laluan ke dalam URL masing-masing. pnpm db:migrate mencipta log masuk rakazo_app dengan kata laluan yang anda tetapkan.
openssl rand -base64 48
openssl rand -hex 32
openssl rand -hex 24Kemudian naikkan pangkalan data secara berasingan dan jalankan migrasi.
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 membina imej komputer bot, yang ditakrifkan dalam package.json sebagai docker build -t rakazo/computer:local infra/sandboxes/computer. Ia merupakan imej grafik, jadi binaan pertama akan menarik banyak data dan mengambil masa. Sahkan ia telah dimuatkan dengan docker image ls rakazo/computer, yang sepatutnya memaparkan satu baris.
Fail compose asas tidak menerbitkan sebarang port Postgres. Overlay docker-compose.postgres-host.yml dalam arahan tersebut menerbitkannya sebagai 127.0.0.1:5433, yang hanya untuk loopback, supaya alatan di sisi hos seperti pnpm db:migrate dan pnpm dev boleh mencapainya. Kekalkan tetapan tersebut. Compose enggan memulakan Postgres tanpa POSTGRES_PASSWORD dalam .env, tetapi port Postgres yang boleh dicapai dari internet mengundang serangan kata laluan. Fail compose pengeluaran membaca pemboleh ubah yang sama dan tidak menerbitkan sebarang port pangkalan data.
Jalankan buat kali pertama
pnpm devPerintah itu memulakan empat perkara: API pada port 3100, Graphile Worker, aplikasi web Vite pada 5173, dan penyelia sandbox pada 7091 secara lalai. Jika port tersebut sibuk, pnpm dev memilih blok bebas lain dan mencetak URL tersebut. Pada port lalai, aplikasi berada di http://127.0.0.1:5173, dan anda sepatutnya melihat halaman daftar masuk.
Pada VPS, anda tidak duduk di hadapan mesin tersebut, dan anda tidak sepatutnya menerbitkan 5173 untuk mencapainya. Sebaliknya, forward port tersebut melalui SSH (secure shell) dari mesin anda sendiri.
ssh -L 5173:127.0.0.1:5173 -L 3100:127.0.0.1:3100 you@your-serverBerhati-hati dengan perbezaan antara cara menjalankan ini. pnpm dev menjalankan Vite pada hos, terikat secara setempat. Perkhidmatan web dalam fail compose pembangunan menerbitkan 127.0.0.1:5173:5173 dan perkhidmatan api menerbitkan 127.0.0.1:3100:3100, kedua-duanya hanya untuk loopback, jadi tunnel yang sama berfungsi untuknya. Dalam fail pengeluaran, aplikasi web tidak menerbitkan port hos dan hanya mendedahkan 5173 kepada container pada rangkaiannya sendiri, dan Caddy sahaja yang menerbitkan port 80 dan 443, jadi gunakan fail pengeluaran dan reverse proxy-nya untuk apa sahaja yang anda biarkan berjalan.
Penyedia sandbox manakah yang selamat pada pelayan?
Ini adalah satu tetapan yang perlu dilakukan dengan betul. SANDBOX_PROVIDER dalam .env ditetapkan kepada docker secara lalai, dan checkout yang dipinkan juga menyokong Railway di samping penyedia yang disenaraikan dalam dokumen self-host.
dockerialah lalai. Komputer bot berjalan sebagai kontena pada mesin anda, dibina daripada imejpnpm sandbox:buildyang dihasilkan dan dijalankan di bawah penyelia. Bot ruang kerja berkongsi satu Team Computer secara lalai, dan bot hanya mendapat kontena sendiri pada Private Computer. Tiada akaun E2B diperlukan.e2bmenjalankan komputer bot pada E2B dan memerlukanE2B_API_KEY. Padav0.3.5, kilang menerimanya dalam pengeluaran apabila kunci dibekalkan, tanpa sekatanNODE_ENV. Dokumen self-host menyatakannya sesuai untuk pengeluaran awam atau berbilang pengguna, kerana ia menjauhkan komputer bot daripada hos yang menjalankan API dan pangkalan data anda.daytona,createosdanboatadalah penyedia jauh yang lain, setiap satunya memerlukan kunci sendiri:DAYTONA_API_KEY,CREATEOS_SANDBOX_API_KEYatauBOAT_API_KEY.railwaymenjalankan komputer pada Railway dan memerlukanRAILWAY_API_TOKENsertaRAILWAY_ENVIRONMENT_IDyang dipilih secara eksplisit pada API dan worker. Gunakan projek atau persekitaran Railway yang khusus untuk sandbox.desktopmenjalankan arahan bot secara terus pada hos API dan worker, seperti yang dinyatakan dalam dokumen. Padav0.3.5, API dan worker menolaknya melainkanNODE_ENVditetapkan kepadadevelopmentatautest, tetapi.env.examplemenghantarNODE_ENV=development, jadi pelayan yang menjalankanpnpm devmasih menerimanya. Jangan aktifkannya pada perkhidmatan awam atau dikongsi.fakeialah emulator untuk pengesahan sahaja. Ia bukan runtime.nonememulakan produk tanpa hos komputer sama sekali.
Ambil perkara itu secara literal. Dalam mod desktop, tiada sempadan pengasingan langsung, jadi bot menjalankan arahan shell sebagai pengguna yang menjalankan proses API, dengan direktori home pengguna tersebut, kunci SSH pengguna tersebut, kelayakan awan pengguna tersebut dan .env pengguna tersebut. Teks dalam halaman web yang dibaca oleh bot menjadi arahan pada pelayan anda. Mod desktop pada pelayan ialah cara bot akhirnya memegang kelayakan anda. Gunakannya pada mesin yang anda duduki, atau jangan gunakannya langsung. Menukar penyedia meletakkan kontena di sekitar laluan halaman web itu dan bukannya menutupnya, dan memberikan bot backend carian SearXNG sendiri meliputi permukaan suntikan yang sama dari sisi carian.
docker ialah sempadan sebenar antara bot dan hos anda, dan sempadan yang lemah antara bot itu sendiri. Secara lalai, mereka berkongsi satu Team Computer, dan dokumen runtime komputer menyatakan bot Team berkongsi pengguna OS, ruang kerja, profil pelayar serta akses shell dan X11, dan folder setiap bot menyusun kerja tetapi bukan sempadan keselamatan. Jadi, mana-mana bot Team boleh membaca fail bot Team yang lain. Bot yang memerlukan dindingnya sendiri diletakkan pada Private Computer, yang dijalankan oleh penyedia docker sebagai kontena adik-beradik yang berasingan pada rangkaiannya sendiri. Walau bagaimanapun, penyelia yang mencipta kontena tersebut melekapkan /var/run/docker.sock, dan dokumen self-host menyatakannya dengan jelas: akses kepada soket itu adalah setara dengan kawalan hos Docker. Jadi, pastikan penyelia itu peribadi. .env.example melayan SANDBOX_SUPERVISOR_TOKEN sebagai kelayakan khusus, berbeza daripada BETTER_AUTH_SECRET, yang diperlukan oleh sandbox Docker di luar pembangunan tempatan, dan ia dihantar dengan pemegang tempat yang boleh dibaca oleh sesiapa sahaja di GitHub. Berikannya nilai rawak sendiri. Untuk pemisahan paling kuat yang tersedia di sini, gunakan e2b, atau berikan Rakazo mesin yang tidak menyimpan apa-apa lagi. Itu adalah alasan yang sama di sebalik menjalankan ejen pengekodan dalam VM pakai buang: cara paling murah untuk bertahan daripada ejen yang melakukan sesuatu yang salah adalah dengan memastikan mesinnya tidak bernilai apa-apa.
Di manakah kunci API model disimpan?
Pengebilan kredit model pilihan Rakazo kekal dimatikan melainkan kedua-dua rahsia Stripe ditetapkan. Anda perlu menyediakan kunci tersebut. .env.example menetapkan PI_DEFAULT_PROVIDER=openrouter, jadi OPENROUTER_API_KEY ialah lokasi biasa, dan kunci pembekal berfungsi melalui tetapan yang sama.
Simpan kunci tersebut dalam .env dan jangan masukkan ke dalam mana-mana fail yang anda komit. Kedua-dua arahan compose dalam repositori menghantar --env-file .env, jadi nilai tersebut sampai ke dalam kontena tanpa perlu ditulis ke dalam YAML yang dijejaki oleh git. Anda juga boleh membiarkan OPENROUTER_API_KEY kosong dan menyambungkan model dalam aplikasi selepas pendaftaran, yang merupakan satu lagi sebab mengapa ENCRYPTION_KEY memerlukan nilai rawak sebenar dan bukannya pemegang tempat (placeholder) yang dibekalkan.
Tetapkan had perbelanjaan pada kunci tersebut di pihak pembekal sebelum bot menggunakannya. Bot yang bergelung (loop) ialah bot yang membelanjakan wang. Rakazo juga menyediakan MAX_TOOL_CALLS_PER_TURN: tetapkan integer positif untuk menghentikan giliran (turn) yang melebihi bajet panggilan alatnya sambil tetap menghasilkan mesej pembantu terakhir. Jika tidak ditetapkan, kosong, atau 0, ia akan dibiarkan tanpa had. Ini mengira panggilan alat, bukan wang, jadi ia tidak menggantikan had perbelanjaan pembekal. Berikan kunci ini nama tersendiri supaya anda boleh membatalkannya secara berasingan. Jika anda menyediakan ini untuk pasukan dan bukan untuk diri sendiri, Satu gateway OneCLI di hadapan ejen setiap orang ialah jawapan berbeza bagi masalah yang sama, kerana ia menyimpan kunci pembekal di satu tempat dan bukannya satu kunci bagi setiap orang.
Beralih daripada mod pembangunan kepada persekitaran produksi
Repositori ini membekalkan fail compose produksi yang menjalankan Postgres, API, worker, aplikasi web, dan Caddy untuk sijil TLS (transport layer security) yang diperoleh secara automatik. Caddy merupakan satu-satunya servis di dalamnya yang mendedahkan port. Secara lalai, ia menggunakan E2B untuk komputer bot. Overlay pilihan, infra/compose/docker-compose.prod.docker.yml, menjalankan komputer Docker tempatan pada stack yang sama, dan dokumentasi memberi amaran bahawa supervisor yang ditambah adalah setara dengan root pada hos.
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/healthCipta akaun deploy berasaskan kunci sahaja dan sahkan anda boleh log masuk dengannya sebelum menjalankan skrip. harden-host.sh melumpuhkan kata laluan SSH dan log masuk root, mengehadkan kadar SSH, menambah kebenaran SSH, HTTP dan HTTPS melalui UFW (uncomplicated firewall) sambil mengekalkan peraturan rangkaian peribadi sedia ada, serta mengaktifkan fail2ban, kemas kini keselamatan automatik, AppArmor dan peraturan audit. Ia enggan berjalan tanpa SSH_CONNECTION, itulah sebabnya arahan tersebut melaluinya melalui sudo, dan ia akan membatalkan perubahan firewall melainkan anda mengesahkannya daripada sesi SSH baharu dalam masa tiga minit. Baca skrip tersebut sebelum anda menjalankannya, kerana ia mengubah cara anda log masuk dan memuat semula SSH. Pastikan konsol pembekal anda terbuka sehingga log masuk SSH baharu berjaya.
.env produksi memerlukan lebih banyak sumber berbanding versi pembangunan. Dokumentasi self-host menyenaraikan keperluan minimum ini, berserta rahsia (secrets).
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>Halakan rekod A ke pelayan sebelum up pertama. Caddy meminta sijil untuk nama dalam RAKAZO_HOST; nama tersebut mesti diselesaikan (resolve) ke kotak ini, dan sama ada port 80 untuk pengesahan HTTP atau port 443 untuk pengesahan TLS-ALPN mestilah boleh diakses dari luar. Kedua-dua cabaran ini didayakan secara lalai, jadi menutup port 80 sahaja tidak menghalang pengeluaran sijil melalui port 443.
Pastikan SIGNUP_ALLOWLIST ditetapkan kepada alamat anda sendiri sejak awal. .env.example membekalkan SIGNUPS_ENABLED=true, dan kedua-dua tetapan dibaca daripada persekitaran pada setiap permulaan API, jadi instans pada nama awam dengan pendaftaran dibuka dan tiada allowlist akan menerima pendaftaran daripada sesiapa sahaja yang menemuinya. Allowlist yang tidak kosong akan digunakan pada setiap permulaan dan menggantikan senarai yang disimpan. Pendaftaran yang disenaraikan dalam allowlist memerlukan pengesahan peti mel, akaun pertama yang disertakan, jadi sediakan penghantaran e-mel sebelum anda mendaftar. Tanpa e-mel, laluan dalam dokumentasi adalah dengan bermula menggunakan SIGNUPS_ENABLED=false dan cipta akaun anda dengan arahan bootstrap sebelah pelayan yang diberikan, yang menghasilkan akaun biasa yang disahkan tanpa keistimewaan pelayan. Utamakan allowlist dahulu. Longgarkannya kemudian jika anda mahu. Jika anda sudah menjalankan beberapa servis pada kotak yang sama dan lebih suka mengekalkan satu senarai pengguna berbanding satu allowlist bagi setiap aplikasi, meletakkan instans Authentik di hadapannya memindahkan keputusan itu kepada proksi, walaupun ia berada di hadapan akaun Better Auth milik Rakazo sendiri dan bukannya menggantikannya.
Anggap docs/self-host.md dalam repositori sebagai autoriti untuk tetapan produksi, kerana ia berubah mengikut kod dan panduan ini tidak. Memandangkan Compose melakukan kerja tersebut, peraturan biasa terpakai, dan asas Docker Compose untuk VPS merangkumi sebab mengapa --env-file dan named volumes lebih penting apabila stack tersebut dibiarkan berjalan selama berbulan-bulan.
Sandaran
Postgres dan direktori data/ menyimpan data instans dalam persediaan ini; pemulihan juga memerlukan ENCRYPTION_KEY dan sebarang kunci induk kandungan yang dikonfigurasikan, jadi simpan salinan di luar pelayan.
./scripts/backup.sh
./scripts/restore.sh backups/BACKUP_TIMESTAMPbackup.sh melakukan dump Postgres dan mengarkibkan data/. restore.sh berfungsi pada stack Compose pembangunan, ke dalam pangkalan data kosong dengan servis aplikasi dihentikan, dan ia tidak membaca fail sandaran pengeluaran. Bagi mesin yang anda bergantung padanya, pasang infra/compose/backup-prod.sh sebagai /usr/local/sbin/rakazo-backup dengan pemasa yang dibekalkan oleh repositori. Ia menulis dump yang disahkan dan arkib data aplikasi ke /var/backups/rakazo, menyimpan sehingga tiga syot kilat (snapshot) yang disahkan secara lalai, ditetapkan oleh RAKAZO_BACKUP_KEEP, dalam had 50 GiB yang ditetapkan oleh RAKAZO_BACKUP_MAX_GB, dan membersihkan syot kilat separa serta sejarah berlebihan sebelum setiap pelaksanaan, jadi putaran berlaku tanpa perlu campur tangan anda. Ia juga boleh menyulitkan setiap sandaran dengan age kepada penerima awam yang anda senaraikan dalam /etc/rakazo/backup.env, supaya pelayan menulis sandaran yang tidak boleh dibacanya sendiri. Jana pasangan kunci tersebut pada mesin yang anda kawal dan simpan kunci peribadi di luar pelayan. Tanpa penerima, sandaran kekal dalam teks biasa dan mencatat amaran, tetapi selepas sandaran disulitkan yang pertama, pelaksanaan tanpa penerima akan gagal melainkan anda membenarkan teks biasa secara eksplisit dengan RAKAZO_BACKUP_ALLOW_PLAINTEXT=1. Sandaran yang berada pada cakera yang sama dengan pangkalan data bukanlah sandaran, jadi salin ia keluar dari mesin tersebut. Kemudian, pulihkan ia sekali, pada pelayan ganti, sebelum anda memerlukannya.
Sebab kegagalan dan perkara yang akan dilihat
pnpm db:migrate tidak dapat mencapai pangkalan data. Migrasi melaporkan bahawa ia tidak dapat mencapai pelayan pangkalan data di 127.0.0.1:5433. Sama ada kontena Postgres tidak berjalan, ia sedang berjalan tetapi belum sedia, atau ia dimulakan tanpa overlay docker-compose.postgres-host.yml, yang berfungsi menerbitkan port 5433 ke hos. Jalankan docker compose --env-file .env -f infra/compose/docker-compose.yml ps dan pastikan servis postgres melaporkan status healthy, kerana fail compose memberikan pemeriksaan kesihatan yang berjalan setiap tiga saat. Jika kontena tersebut memulakan semula secara berulang, baca lognya: tindanan Compose yang dipin (pinned) enggan bermula pada volum Postgres 16 lama sehingga ia dimigrasikan ke Postgres 18. docker compose ... down -v akan membersihkannya, dan ia memadamkan data tersebut bersamanya.
Port sudah digunakan. Menjalankan Postgres gagal dengan bind: address already in use apabila sesuatu yang lain memegang port 5433, biasanya tindanan Rakazo lama yang anda terlupa untuk hentikan. sudo ss -lntp | grep 5433 akan menamakan proses tersebut. Overlay membaca port hos daripada POSTGRES_HOST_PORT, jadi anda boleh mengubahnya, selagi DATABASE_URL dan DATABASE_MIGRATION_URL turut diubah bersamanya.
Bot tidak mendapat komputer. Dengan SANDBOX_PROVIDER=docker dan tiada imej rakazo/computer:local, tiada apa yang boleh dimulakan. docker image ls rakazo/computer menjawab perkara itu dalam satu baris, dan pnpm sandbox:build membaikinya. Jika penyelia tidak dapat mencapai soket Docker, ia juga tidak dapat mencipta kontena, dan mesej tersebut menamakan laluan: permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock.
Perintah panjang terhenti di tengah jalan. .env.example menetapkan SANDBOX_COMMAND_TIMEOUT_MS=300000, jadi satu perintah di dalam komputer bot akan diputuskan selepas lima minit. Tingkatkan nilainya untuk binaan (build) yang perlahan dan jangan terus menganggap sandbox telah ranap.
pnpm install rosak dengan cara yang mengelirukan. Semak node -v sebelum perkara lain. Ruang kerja mengisytiharkan ^22.22.2 || ^24.0.0 || >=26.0.0, jadi 23.x, 25.x dan mana-mana 22.x sebelum 22.22.2 adalah di luar julatnya. .npmrc yang dipin menetapkan engine-strict=true, jadi pnpm install akan menolak versi Node yang tidak disokong dengan ralat engine/version sebelum kod dependensi aplikasi dijalankan.
Daftar masuk berfungsi secara lokal tetapi tidak melalui domain. BETTER_AUTH_URL, WEB_ORIGIN dan API_URL kesemuanya perlu memegang origin awam yang sama seperti bar alamat, termasuk skema. http://127.0.0.1:5173 lapuk yang tertinggal dalam salah satu daripadanya adalah punca biasa bagi sesi yang tidak pernah kekal.
Mengemas kini checkout yang dipinkan
Laluan naik taraf dalam dokumentasi self-host untuk stack Compose pengeluaran yang dibina daripada checkout anda adalah ringkas: tarik sumber baharu, kemudian bina semula dan mulakan semula API, worker dan aplikasi web. Migrasi dijalankan apabila API bermula, kerana arahan mulanya melaksanakannya sebelum ia beroperasi.
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 webBuat sandaran terlebih dahulu. Migrasi bergerak ke hadapan, dan versi beta tidak memberikan anda laluan undur yang boleh dipercayai. Jika checkout anda lebih lama daripada 30 Ogos 2026, yang merangkumi commit v0.1.0-beta, baca nota dokumentasi mengenai migrasi 20260830200000_space_scope_names_and_user_credentials sebelum anda menaik taraf. Ia merupakan peralihan yang diselaraskan, jadi hentikan API dan worker lama terlebih dahulu dan jalankan semakan sempadan privasi Space yang diberikan dalam dokumentasi. Apabila menaik taraf daripada checkout yang mendahului log masuk aplikasi berasingan, tetapkan POSTGRES_APP_PASSWORD dalam .env sebelum membina semula; fail compose pengeluaran enggan bermula tanpanya. Fail source-checkout dan Compose pengeluaran juga menjalankan Postgres 18: pemasangan Postgres 16 sedia ada memerlukan prosedur infra/compose/upgrade-postgres.sh dalam dokumentasi sebelum ia boleh bermula pada susun atur baharu. Baca commit antara SHA yang dipinkan dan yang baharu sebelum mengambilnya, kerana projek yang masih muda ini menamakan semula pemboleh ubah persekitaran tanpa pengumuman, dan pemboleh ubah yang hilang akan menyebabkan servis bermula kemudian terhenti. Jika anda masih membuat keputusan sama ada Rakazo adalah pilihan yang tepat untuk dijalankan, ringkasan ejen AI yang dihoskan sendiri merangkumi apa lagi yang terdapat dalam kategori ini dan kos untuk mengekalkan setiap satunya.
FAQ
Bolehkah saya menjalankan Rakazo pada VPS 1 GB?
Tidak. Postgres, API, worker, penyelia sandbox dan aplikasi web semuanya berjalan pada masa yang sama, dan dengan SANDBOX_PROVIDER=docker, komputer bot menambah container yang memegang desktop grafik, dengan paparan X dan proses Chrome yang berasingan untuk setiap bot yang aktif, semuanya di dalam satu had lalai 2 GB memori dan dua CPU. Dokumen self-host di v0.3.5 tidak memberikan saiz hos. Anggap 4 GB sebagai lantai untuk control plane, dan gunakan saiz yang lebih tinggi apabila desktop berjalan pada mesin anda.
Adakah penyedia sandbox desktop selamat pada pelayan?
Tidak. Dokumen self-host menyatakan desktop menjalankan perintah secara terus pada hos API dan worker, jadi bot bertindak sebagai pengguna yang menjalankan proses tersebut, dengan fail dan kelayakan pengguna tersebut dalam jangkauan. Pada v0.3.5, API dan worker menolaknya di luar mod pembangunan dan ujian, tetapi pelayan yang menjalankan pnpm dev berada dalam mod pembangunan dan menerimanya. Jauhkan ia daripada mana-mana pelayan awam atau kongsi. Gunakan docker, memberikan bot Komputer Peribadi apabila ia tidak boleh berkongsi fail dengan bot lain dalam ruang kerja, atau e2b apabila lebih daripada seorang pengguna mendaftar masuk.
Versi Rakazo yang manakah perlu saya pasang?
Setakat 9 November 2026, release terbaharu ialah v0.8.0, diterbitkan pada 4 November 2026 dan ditandakan sebagai Latest. Untuk mengikuti panduan ini, semak commit v0.3.5 yang ditetapkan, f31e3c0699f086d663637c4107858c238a086fb3, dan bukannya menjejaki main atau prerelease bulan Ogos v0.1.0-beta. Branch akan berubah tanpa pengetahuan anda dan tag boleh diubah, jadi kedua-duanya tidak mengenal pasti tree yang boleh anda kembalikan. Rekodkan commit tersebut, kerana rollback hanya boleh dilakukan apabila anda tahu yang mana satu berfungsi.
Di manakah saya perlu meletakkan kunci API OpenRouter saya?
Dalam .env sebagai OPENROUTER_API_KEY, dan jangan sekali-kali dalam fail compose yang anda commit. Kedua-dua perintah compose dalam repositori melepasi --env-file .env, jadi nilai tersebut sampai ke container tanpa ditulis ke dalam YAML yang dijejaki. Anda juga boleh membiarkannya kosong dan menyambungkan model dalam aplikasi selepas mendaftar. Tetapkan had perbelanjaan pada kunci tersebut di penyedia, kerana bot dalam gelung akan terus memanggil model sehingga sesuatu menghentikannya.
Adakah saya memerlukan nama domain dan TLS?
Untuk apa-apa selain ujian pertama, ya. Fail compose pengeluaran menjalankan Caddy dan mendapatkan sijil secara automatik; tetapkan RAKAZO_HOST kepada hostname awam dan BETTER_AUTH_URL, WEB_ORIGIN serta API_URL kepada origin HTTPS awam yang sama. Untuk percubaan pertama, anda boleh melangkau domain: jalankan pnpm dev dan forward port 5173 melalui SSH dan bukannya menerbitkannya.