Multica 私有化部署指南
# Multica 私有化部署指南
Multica 是一款 AI 编程助手，支持私有化部署。本文档介绍如何在自己的服务器上部署 Multica 服务端、客户端和 CLI 工具。
# 一、环境要求
# 服务端要求
| 项目 | 要求 |
|---|---|
| 操作系统 | Linux / macOS / Windows |
| Docker | 已安装 Docker 和 Docker Compose |
| 内存 | 建议 4GB 以上 |
| 磁盘 | 10GB 以上 |
| 端口 | 3000（前端）、8080（后端） |
# 客户端要求
- 已安装 AI 编程工具（如 Claude Code、Cursor 等）
- 能访问服务端网络
# 二、服务端部署
# 2.1 克隆仓库
git clone https://github.com/multica-ai/multica.git
cd multica
1
2
2
# 2.2 一键启动
make selfhost
1
该命令会自动完成以下操作：
- 从
.env.example生成.env配置文件 - 生成随机的 JWT_SECRET 和 PostgreSQL 密码
- 拉取 Docker 镜像（PostgreSQL、Backend、Frontend）
- 启动所有服务
# 2.3 服务地址
启动完成后：
- 前端：http://localhost:3000
- 后端：http://localhost:8080
默认只监听 127.0.0.1，外部无法直接访问。
# 2.4 配置邮件（可选）
如需邮件验证码功能，在 .env 中配置：
方式一：Resend（推荐公网部署）
RESEND_API_KEY=re_xxxxxxxxxxxx
RESEND_FROM_EMAIL=noreply@yourdomain.com
1
2
2
方式二：SMTP（内网部署）
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USERNAME=your_username
SMTP_PASSWORD=your_password
RESEND_FROM_EMAIL=noreply@yourdomain.com
1
2
3
4
5
2
3
4
5
# 2.5 开放外部访问
默认配置只监听 localhost，如需外部访问，推荐使用反向代理。
# 使用 Caddy（推荐）
创建 Caddyfile：
multica.example.com {
# WebSocket 路由
@ws path /ws /ws/*
handle @ws {
reverse_proxy 127.0.0.1:8080 {
flush_interval -1
}
}
# Backend API
handle /api/* {
reverse_proxy 127.0.0.1:8080
}
# 其他请求 → 前端
reverse_proxy 127.0.0.1:3000
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
在 .env 中设置：
FRONTEND_ORIGIN=https://multica.example.com
1
重启后端：
docker compose -f docker-compose.selfhost.yml restart backend
1
# 三、CLI 安装与配置
# 3.1 安装 CLI
macOS（Homebrew）
brew install multica-ai/tap/multica
1
Linux / macOS（脚本安装）
curl -fsSL https://get.multica.ai | sh
1
Windows（PowerShell）
irm https://get.multica.ai/windows | iex
1
# 3.2 配置 CLI 连接服务端
假设服务端 IP 为 IP:3000，配置方式如下：
方式一：逐步配置
multica config set server_url http://IP:3000:8080
multica config set app_url http://IP:3000:3000
1
2
2
方式二：一步完成（推荐）
multica setup self-host \
--server-url http://IP:3000:8080 \
--app-url http://IP:3000:3000
1
2
3
2
3
# 3.3 验证配置
# 查看当前所有配置
multica config get
# 检查是否已连接
multica auth status
1
2
3
4
5
2
3
4
5
# 3.4 重启守护进程
配置完成后，重启 daemon 使配置生效：
multica daemon restart
1
# 四、首次登录
- 打开浏览器访问前端地址（如 http://IP:3000:3000）
- 输入邮箱获取验证码
- 如果未配置邮件服务，可从服务端日志查看验证码：
docker logs -f --tail=222 multica-backend-1
1
查找 [DEV] Verification code 行
- 输入验证码完成登录
- 创建第一个工作区
# 五、注意事项
# 5.1 网络配置
- IP 直连时通常用
http而不是https - 确保服务器防火墙已放行 8080（后端）和 3000（前端）端口
- 如果服务器和 CLI 机器不在同一局域网，建议加反向代理 + HTTPS，否则 WebSocket 容易出问题
# 5.2 安全建议
- 生产环境务必设置
APP_ENV=production - 确保
.env中MULTICA_DEV_VERIFICATION_CODE为空 - 使用强密码保护数据库
- 定期备份数据
# 5.3 端口说明
| 端口 | 服务 | 说明 |
|---|---|---|
| 3000 | Frontend | Web 前端界面 |
| 8080 | Backend | API 服务 |
| 5432 | PostgreSQL | 数据库（容器内部） |
# 六、常用命令
# 查看服务状态
docker compose -f docker-compose.selfhost.yml ps
# 查看后端日志
docker compose -f docker-compose.selfhost.yml logs -f backend
# 重启所有服务
docker compose -f docker-compose.selfhost.yml restart
# 停止所有服务
docker compose -f docker-compose.selfhost.yml down
# 更新到最新版本
git pull
make selfhost
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 七、故障排查
# 7.1 WebSocket 连接失败
- 检查反向代理是否正确配置 WebSocket 转发
- 确认
FRONTEND_ORIGIN配置正确 - 查看浏览器控制台是否有 CORS 错误
# 7.2 无法收到验证码
- 检查邮件服务配置
- 从服务端日志获取验证码（开发模式）
- 确认
APP_ENV=production时没有启用固定验证码
# 7.3 CLI 连接失败
- 检查网络是否可达服务端
- 确认防火墙已开放端口
- 使用
multica auth status诊断连接状态