---
title: Self-Host 快速上手
description: 在自己的服务器或本机用 Docker 把 Multica 跑起来。约 10 分钟。
---

import { Callout } from "fumadocs-ui/components/callout";

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

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

## 前置要求

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

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

```bash
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 输出。升级版本时同样自动处理。

<Callout type="info">
**镜像还没发布？** 如果 `make selfhost` 报拉不到镜像，可能是你在某个未发布的版本标签上。切到稳定版本或直接从源码构建：`make selfhost-build`。
</Callout>

启动完成后：

- **前端**：[http://localhost:3000](http://localhost:3000)
- **后端**：[http://localhost:8080](http://localhost:8080)

## 2. 重要：保持生产安全配置

<Callout type="warning">
**`docker-compose.selfhost.yml` 默认把 `APP_ENV` 设成 `production`**，并让 `MULTICA_DEV_VERIFICATION_CODE` 为空，所以公网实例默认没有固定验证码。

只在本地或私有测试自动化里设置 `MULTICA_DEV_VERIFICATION_CODE`。如果在 `APP_ENV` 非 production 时启用了固定验证码，任何能请求验证码的人都能用这个固定值登录。详见 [登录与注册配置 → 固定本地测试验证码](/auth-setup#固定本地测试验证码)。

公网部署前一定检查 `.env` 里 `APP_ENV=production`，且 `MULTICA_DEV_VERIFICATION_CODE` 为空。
</Callout>

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

如果不配邮件，用户无法通过邮件收到验证码；server 会把生成的验证码打印到 stdout。

要真的发验证码邮件：

1. 在 [Resend](https://resend.com/) 注册并拿一个 API key
2. 验证一个你控制的发件域名
3. 在 `.env` 里设：

    ```bash
    RESEND_API_KEY=re_xxxxxxxxxxxx
    RESEND_FROM_EMAIL=noreply@yourdomain.com
    ```

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

更多 auth 配置（OAuth、注册白名单）见 [登录与注册配置](/auth-setup)。

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

打开 [http://localhost:3000](http://localhost:3000)：

- 输入你的邮箱
- 从 Resend 邮件里拿验证码（或者前面没配 Resend 的话从 server 容器的 stdout 里抄 `[DEV] Verification code` 这行）
- 不要直接使用 `888888`；只有在非 production 私有实例上显式设置 `MULTICA_DEV_VERIFICATION_CODE=888888` 后它才会生效
- 登录后创建第一个工作区

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

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

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

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

```bash
multica setup self-host
```

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

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

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

流程和 Cloud 一样——见 [Cloud 快速上手 → 5-6 步](/cloud-quickstart#5-创建智能体)。

## 常见问题

- **后端起不来**：看容器日志 `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 连不上](/troubleshooting#websocket-连不上)

## 下一步

- [环境变量](/environment-variables) —— 完整 env 清单
- [登录与注册配置](/auth-setup) —— Resend / OAuth / 注册白名单详细配置
- [故障排查](/troubleshooting) —— 遇到问题先来这里
- [桌面应用](/desktop-app) —— 发布版 Desktop 只连 Multica Cloud；要让 Desktop 连自部署后端需要自行构建（详见 desktop-app 页的提示）
