Self-Host 快速上手

这一页带你用 Docker 把 Multica 的服务器（后端 + 前端 + PostgreSQL）跑在自己的机器或服务器上。走完这一篇你的数据就完全在自己手里——包括 工作区、issue、评论、智能体 配置。

智能体执行还是靠你本地跑的 守护进程 + 本地装好的 AI 编程工具——这点和 Cloud 完全一样。Self-host 换掉的是服务器那一层，不是执行那一层。

前置要求

• Docker 安装好并且能跑 docker compose
• Git 可选（推荐——可以拉源码）
• 一台能长期开机的机器（本地 / 内网 / 云主机都行）
• 至少一款 AI 编程工具装在运行守护进程的机器上（不一定是跑服务器的机器——可以是你开发用的笔记本）

1. 拉取项目 + 一键启动后端

git clone https://github.com/multica-ai/multica.git
cd multica
make selfhost

make selfhost 会：

1. 如果没有 .env 文件，从 .env.example 自动生成一份并生成随机 JWT_SECRET
2. 拉取官方 Docker 镜像（PostgreSQL、Multica backend、Multica frontend）
3. 用 docker-compose.selfhost.yml 启动全部服务
4. 等后端 /health 端点准备就绪

如果是启动完成后的生产探针，想让数据库或 migration 异常也体现为失败，请改用 /readyz。

后端容器启动时会自动跑数据库 migration（docker/entrypoint.sh 在启动 server 前执行 ./migrate up）——你会在 backend 日志里看到 migration 输出。升级版本时同样自动处理。

启动完成后：

• 前端：http://localhost:3000
• 后端：http://localhost:8080

2. 重要：改 APP_ENV 成 production

3. 配置邮件服务（可选但推荐）

如果不配邮件，你的用户无法收到验证码——但如果 APP_ENV != production 你可以用 888888 登录（见上方警告）。

要真的发验证码邮件：

1. 在 Resend 注册并拿一个 API key

2. 验证一个你控制的发件域名

3. 在 .env 里设：

   RESEND_API_KEY=re_xxxxxxxxxxxx
   RESEND_FROM_EMAIL=noreply@yourdomain.com

4. 重启：docker compose -f docker-compose.selfhost.yml restart backend

更多 auth 配置（OAuth、注册白名单）见 登录与注册配置。

4. 首次登录 + 创建工作区

打开 http://localhost:3000：

• 输入你的邮箱
• 从 Resend 邮件里拿验证码（或者前面没配 Resend 的话从 server 容器的 stdout 里抄 [DEV] Verification code 这行）
• 登录后创建第一个工作区

5. 连接命令行工具到你自己的 server

命令行装法和 Cloud 快速上手 → 2. 装命令行工具 一样——Homebrew / 脚本 / PowerShell 任选。装好之后，用 self-host 版本的 setup 命令：

multica setup self-host --server-url http://<你的服务器地址>:8080 --app-url http://<你的服务器地址>:3000

本地就是一台电脑跑整套的话：

multica setup self-host

默认连 http://localhost:8080（backend）+ http://localhost:3000（frontend）。

setup self-host 会让你在浏览器里完成登录，把 PAT 存到本地，自动启动守护进程。

6. 创建智能体 + 分配第一个任务

流程和 Cloud 一样——见 Cloud 快速上手 → 5-6 步。

常见问题

• 后端起不来：看容器日志 docker compose -f docker-compose.selfhost.yml logs backend；常见是 .env 里 DATABASE_URL 或 JWT_SECRET 有问题
• 验证码收不到：没配 Resend → 从 docker compose logs backend 里找 [DEV] Verification code
• WebSocket 连不上：公网部署必须设 FRONTEND_ORIGIN 成你真实的前端域名；见 故障排查 → WebSocket 连不上

下一步

• 环境变量 —— 完整 env 清单
• 登录与注册配置 —— Resend / OAuth / 注册白名单详细配置
• 故障排查 —— 遇到问题先来这里
• 桌面应用 —— 桌面应用也能连你的自部署后端