rakazo 部署全流程（实测版）

这篇教程是我们在一台真实服务器（4 核 / 8 GB / ARM）上从零跑通的完整记录：顺利时约 25–40 分钟。先说清三个必踩的坑（第 5、6、7 步），很多人卡住都不是因为装不上，而是卡在这三处。

第 0 步：准备

你需要：一台 VPS（选型看 VPS 选型指南）、一个域名或子域名（没有也能先用临时地址验证）、一个模型账号（Claude/ChatGPT 订阅，或 API key，见接模型指南）。

第 1 步：装 Docker

curl -fsSL https://get.docker.com | sh
docker --version && docker compose version

实测版本 Docker 29.x / Compose v5.x 正常。系统选 Ubuntu 24.04 LTS。

第 2 步：官方脚本部署

只从官方仓库 elie222/rakazo 取安装脚本，不要用任何第三方改版：

mkdir -p ~/rakazo && cd ~/rakazo
curl -fsSLO https://raw.githubusercontent.com/elie222/rakazo/main/infra/compose/install-images.sh
bash install-images.sh --prepare-only   # 先生成 .env
bash install-images.sh                  # 正式安装

先备份 .env：里面的 ENCRYPTION_KEY 丢了不可恢复。把 .env 复制一份到你自己的密码管理器或离线位置，不要发给任何人。

安装完成后检查服务状态，postgres / api / worker / supervisor / web 都应为 Healthy；本机访问 http://127.0.0.1:5173 应返回 200。

第 3 步：HTTPS（Caddy 反代）

把 .env 里的 RAKAZO_HOST / BETTER_AUTH_URL / WEB_ORIGIN / API_URL 改成你的最终 https 地址，重跑一次安装脚本，再用 Caddy 反代到本机 5173：

# /etc/caddy/Caddyfile
bot.example.com {
    reverse_proxy 127.0.0.1:5173
}

外网打开 https 能看到登录页、证书正常，才算通。桌面/移动客户端之后用这个 https 地址以 Existing instance 方式连接。

第 4 步：先做一次备份

docker exec rakazo-postgres-1 sh -c 'pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB"' | gzip > backup-base.sql.gz

空库基线先备一份；以后每次升级前都重复这个动作（升级与回滚的完整流程见 FAQ）。

第 5 步（坑 1）：注册后登录报 Email not verified

这是默认部署的已知问题：没配 SMTP 时验证邮件根本发不出去，新账号必然卡住，不是你操作错了。两条正解任选其一（详解见 Email not verified 怎么办）：配好 SMTP 发信（长期方案），或单人使用时由管理员在数据库把 owner 的邮箱置为已验证（临时方案）。处理好再继续。

第 6 步（坑 2）：连模型只能你本人

在 rakazo 里连接你的模型账号：订阅 OAuth 要你本人登录＋过 MFA；API key 要你本人新建一把专用 key 再粘进去。任何一步都别把密码、验证码、完整 key 发给别人（包括帮你部署的人）。细节见接模型指南。

第 7 步（坑 3）：立刻关闭公开注册

时间窗风险：公网上线后到你注册完成前，注册口是开的，谁先注册谁就可能抢到第一个账号。注册完 owner 后马上关掉：

# .env 中设置后重跑安装脚本
SIGNUPS_ENABLED=false
SIGNUP_ALLOWLIST=你的owner邮箱

验收：再打开注册页提交应被拒；owner 登录正常。

第 8 步：验收第一个 bot

新建 bot 后用一条消息同时验三件事（我们实测用的就是这条）：

Hi! Three quick tasks: 1) Remember my code word: BANANA-42. I will ask you for it later.
2) Use your computer: list the files in your home folder, then create a file named
hello-test.txt there and write today's date in it. 3) Tell me the current time in Berlin.
Report the result of each task.

三项都对，再追问一句 What was my code word?——答对说明记忆与工具调用都真的通了。到这里，你的 AI 队友正式上岗。

卡住了？

先看 FAQ；仍解决不了，或者你想直接跳过以上全部步骤——代部署服务就是替你把这篇教程执行一遍。

本教程基于 2026-10 的 rakazo 版本与实测环境整理；官方迭代很快，命令与界面如有出入以官方文档为准。