10分钟自建AI助手：部署Rakazo并接入自选模型

10分钟自建AI助手：部署Rakazo并接入自选模型

市面上 AI 助手越来越多，但收费门槛也在不断提高。用着方便，一旦服务调整价格或限制功能，只能被动接受。有没有一种方式，可以自己跑一个功能完整的 AI 助手，自带持久记忆、多端同步，还能自由选择模型？

这篇教程带你用一台有 Docker 的机器（本地 Mac、Windows、Linux 或云服务器均可），花 10 分钟左右部署好 Rakazo——一个开源的自建 AI Agent。部署完成后接入你自己的 API Key，创建第一个 Persistent Bot。完成后，你将拥有一台完全属于自己、随时可调用的 AI 助手。

前置条件

开始前确认环境满足以下要求：

MacBook 或 Windows 安装 Docker Desktop 后通常已自带 Compose 插件。Linux 用户确认 docker compose version 能正常输出版本号即可。

第一步：一键下载并启动服务

官方提供了一键安装脚本，不需要 git clone，也不需要本地装 Node.js。创建目录、下载脚本、执行：

mkdir -p rakazo && cd rakazo && \
curl -fsSLO https://raw.githubusercontent.com/elie222/rakazo/main/infra/compose/install-images.sh && \
bash install-images.sh

这段脚本完成了三件事：

1. 从 GitHub 拉取 Docker Compose 配置文件，包含 Web 前端、API 服务、Worker、Postgres 容器等全部定义
2. 自动生成 .env 文件，内部填充随机生成的安全密钥（数据库密码、认证密钥、加密密钥等）
3. 执行 docker compose up，拉取镜像并启动所有服务容器

运行过程中会看到多个镜像的下载进度，通常 2～5 分钟完成。脚本支持断点续跑，中途网络断开或后续想拉取更新镜像时重新执行即可，它会保留已有的 .env 配置不覆盖。

网络受限提示：如果直接访问 raw.githubusercontent.com 不通，可在运行前设置环境变量 RAKAZO_DOWNLOAD_BASE 为你的镜像加速地址，或用 --local 参数跳过下载 Compose 文件（前提是你已手动放好了 compose 文件）。

启动成功后，浏览器打开 http://127.0.0.1:5173，会看到 Rakazo 的注册页面。创建账号后进入下一步。

第二步：接入你自己的模型

Rakazo 的核心优势之一是"Bring Your Own Model"。它不绑定某家模型服务，而是通过 Pi 中间层让你自由接入 API。

首次登录后，界面会引导你连接模型。手头有 OpenAI、Anthropic 或 OpenRouter 的 API Key 直接填入即可。推荐用 OpenRouter——它聚合了几乎所有主流模型，一个 Key 就能切换不同模型，调试非常方便。

接入流程：

1. 在设置中找到模型连接入口
2. 填入 API Key 和想要使用的模型标识（如 openai/gpt-6.1-sol、anthropic/claude-sonnet-5.5）
3. 保存后做一条测试对话，确认能正常返回结果

模型是你自己的，用量可控、成本透明。如果未来某家模型涨价或服务不稳定，随时可以在设置里切换到另一个，不用迁移数据、重部署服务。

第三步：创建你的第一个 Persistent Bot

Rakazo 里的 Bot 是持久化的——每个 Bot 有自己独立的对话历史、记忆、甚至日常任务（Routines）。可以理解为专属自己的 AI 同事。

操作路径：登录 → Create a new bot → 取名（比如「代码助手」）→ 保存。

创建完成后进入该 Bot 的对话界面。试试看跟它聊点实际的：

请帮我用 Python 写一个快速排序函数，并附带单元测试。

回复就是真实的、完整的代码。这次对话会被保留，下次进来还能继续追问或修改。这就是 Persistent Bot 的核心价值：上下文不丢失、记忆不中断。

进阶：部署到云服务器，随时随地访问

本地跑通后，想随时用手机或公司电脑连上自己的 AI 助手，可以部署到云服务器。步骤几乎一样，多几行配置：

bash install-images.sh --prepare-only
## 编辑生成的 .env 文件：
## SANDBOX_PROVIDER=box  （或其他沙箱提供商如 e2b / daytona / createos）
## RAKAZO_HOST=your.domain  （你的服务器域名）
## 填入对应沙箱提供商的 API Key
bash install-images.sh

部署到公网后，强烈建议在前面加一层 HTTPS 反向代理。官方文档推荐用 Caddy，配置简单。然后在 Electron 桌面客户端或手机 App 里选择 Existing instance，输入你的 https://your.domain 地址就能连上。

桌面客户端首次启动时会在两个选项间选择：「在这台电脑上运行 Rakazo」还是「连接到已有实例」。「在这台电脑」模式会自动用 Docker Compose 启动本地容器；如果已跑好本地开发服务，选「连接到已有实例」指向 http://127.0.0.1:5173。

常见问题与踩坑提醒

1. 启动后 5173 端口访问不了

先确认容器状态：docker compose ps，看 Web 容器是否在 Running 状态，端口映射 0.0.0.0:5173 是否正常。容器反复重启时，用 docker compose logs 查看具体报错。

2. 模型连接测试失败

确认三件事：① API Key 没抄错；② 模型 ID 格式正确（如 openai/gpt-6.1-sol 不是 gpt-6.1-sol）；③ 服务器有外网访问权限（部分云服务器默认安全组会拦截出站的 443 端口）。

3. Postgres 密码在 .env 里改了但还是连不上

Postgres 的 volume 保留了首次初始化时的用户、密码和数据库名，之后改 .env 里的 POSTGRES_PASSWORD 不会自动同步到数据库。改法：用 docker compose down -v 重建 volume（⚠️ 会丢失所有数据，请先备份），或直接在数据库内执行 ALTER ROLE。

4. 端口 5433 被占用

本机已有其他 Postgres 占用 5433 时，在 .env 里修改 POSTGRES_HOST_PORT，同时调整 DATABASE_URL 连接串里的端口号即可。

5. 想用源码级开发

做二次开发需要 Node.js 22（22.22.2 或更新的 22.x）、24.x 或 26+，pnpm 9，拉代码后配置 .env，依次执行 pnpm install → pnpm db:generate → pnpm db:migrate → pnpm sandbox:build → pnpm dev。这属于二开范畴，日常用镜像部署已经足够。

总结

回顾完成的内容：

1. 用官方脚本一键部署 Docker Compose，启动 Postgres + Web + Worker 全套服务
2. 注册账号后接入自己的模型 API Key，实现"模型自由"
3. 创建 Persistent Bot，体验带记忆和上下文的 AI 对话
4. 了解将服务迁移到云服务器以及用桌面/手机多端访问的方法

Rakazo 的定位很清晰：不是大厂的封闭产品线，而是一个可以完全掌控、自己跑起来的 AI Agent。模型自己选、数据自己存、服务自己维护。

接下来可以探索的方向：

• 试试语音模式（接入 ElevenLabs、OpenAI 或 Fish Audio 的 Key）
• 研究 App 集成，用 Composio 或 Pipedream Connect 把 Rakazo 接到现有工作流
• 配置 Bot 的 Routines，让 Bot 定时跑任务、发通知
• 看官方 Self-hosting Guide 里关于备份、升级的文档

部署过程中遇到问题，或者跑出了有趣的用法，欢迎交流。这个项目目前 4400+ Star，还在 Beta 阶段，社区活跃度不错，值得关注。

项目地址：elie222/rakazo | Docker 一键部署，自带持久记忆和自选模型，5 分钟拥有一个属于自己的 AI 助手。