Multica 部署与实践教程

Multica 是一个开源的人类与 AI 智能体协作工作区：把 Claude Code、Codex、Cursor、Hermes 等 26 种 AI 编程工具当成"同事"一样分配任务、跟踪进度、沉淀方法。本文基于官方文档（multica.ai/docs/zh）+ 开源仓库（github.com/multica-ai/multica）实测整理，给出可直接照着做的部署 + 实践路径。

一、Multica 是什么（3 分钟认知）

1. 一句话定位

Agents that show up on the board. —— 你已经装了 Claude Code、Codex 好几个 agent，但每个都活在独立终端标签里，session 一断就失忆。Multica 把这些 agent 和你的队友放进同一个工作区：给 agent 分配任务，它自己领取、在你控制的机器上跑、边跑边评论，最后把结果交回给你审。

2. 架构（自托管视角）

组件	职责	技术栈
Backend	REST API + WebSocket 实时	Go（单二进制，Chi 路由 + sqlc + gorilla/websocket）
Frontend	Web 应用	Next.js 16
Database	主数据存储	PostgreSQL 17（`pgvector/pgvector:pg17`，含 pgcrypto + pg_trgm）
守护进程 (daemon)	运行在你自己的电脑上，领取运行、调用本地 AI 工具	`multica` CLI 附带
AI 编程工具	实际执行任务（写代码、跑命令）	Claude Code / Codex / Hermes / DeepSeek Harness 等 26 种

关键边界：Multica 只负责"记录 + 协调"，执行发生在你自己的电脑上。服务器保存任务/评论/配置/执行记录；代码目录、本地文件、工具凭据都留在执行电脑上。

3. 核心对象（一张图记全）

对象	是什么
工作区	团队协作的隔离边界，所有配置都在其中
任务 (issue)	一项工作，负责人可以是成员/智能体/小队
项目	组织相关任务，可绑定仓库/目录做上下文
智能体 (agent)	可复用的配置：名称、指令、模型、skill、Access、运行时。不是常驻进程
Skill	可复用的方法包（SKILL.md + 脚本/模板），挂给多个智能体
运行时 (runtime)	执行发生的地方 = 一台电脑 + 一款 AI 工具
运行 (task/run)	智能体的一次具体执行记录
小队 (squad)	leader 智能体 + 成员，负责路由分配
自动化 (autopilot)	按 cron 或 webhook 自动触发

4. 一次执行的完整链路

分配任务 → Multica 创建"运行"入队 → 执行电脑上的守护进程领取
→ 守护进程调用本地 AI 工具（读取工作目录、跑命令、生成结果）
→ 进度/评论/结果写回任务时间线 → 人类审阅

二、部署教程（Docker Compose）

1. 前提条件

运行 Multica 服务的机器需要：

要求	说明
Docker Engine / Desktop	且 `docker compose`（Compose v2）可用
Git、Make、curl、OpenSSL	一键脚本依赖
端口 3000、8080 空闲	前端 3000，后端 8080
执行电脑至少 1 款 AI 工具	Claude Code / Codex / Hermes 等，需已安装并登录

验证：

docker info
docker compose version

⚠️ Multica 使用 Compose v2（docker compose 带空格），旧版 docker-compose（v1 连字符）不支持。

2. 方式 A：一键安装（推荐）

# 1. 安装 CLI + 拉取镜像 + 启动服务（--with-server 同时部署服务端）
curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash -s -- --with-server

# 2. 配置 CLI、登录、启动守护进程
multica setup self-host

这条命令会：拉取 GHCR 官方镜像、启动三容器、把 CLI 指向 localhost、打开浏览器登录、后台启动守护进程。

3. 方式 B：手动安装（git clone + make）

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

make selfhost 首次运行会： 1. 从 .env.example 生成 .env 2. 随机生成 JWT_SECRET、PostgreSQL 密码、VCS 加密密钥 3. 拉取 postgres / backend / frontend 三个镜像 4. 创建持久化数据卷并启动三个容器 5. 等待 backend 健康检查通过

再次运行 make selfhost 会沿用现有 .env 和数据卷，不会重新生成密钥。

手动方式也可以完全手工执行（等价于 make selfhost 背后做的事）：

cp .env.example .env
# 编辑 .env，必须设置 JWT_SECRET：
#   JWT_SECRET=$(openssl rand -hex 32)
docker compose -f docker-compose.selfhost.yml pull
docker compose -f docker-compose.selfhost.yml up -d

4. 确认服务就绪

docker compose -f docker-compose.selfhost.yml ps
# postgres 应显示 healthy，backend / frontend 运行中

curl -fsS http://localhost:8080/readyz
# 正常响应：{"status":"ok","checks":{"db":"ok","migrations":"ok"}}

/readyz 才真正检查数据库 + migration；/health 只是存活探针，进程活着就返回 ok。升级/排障用 /readyz 验证，不要用 /health。

5. 登录并创建工作区

打开 http://localhost:3000，输入邮箱获取验证码。默认没配邮件，验证码从 backend 日志读：

docker compose -f docker-compose.selfhost.yml logs backend | grep "Verification code"
# 输出类似：[DEV] Verification code for you@example.com: 123456

生产环境：配置 Resend 或 SMTP（见下文），验证码走邮件。
本地测试：可设 APP_ENV=development + MULTICA_DEV_VERIFICATION_CODE=888888（固定验证码）。

⚠️ 不要在公网实例上设 MULTICA_DEV_VERIFICATION_CODE——知道邮箱的人都能用固定码登录。

6. 连接执行电脑（CLI + 守护进程）

在运行 AI 工具的那台电脑上（不一定是 Docker 服务器）：

# 安装 CLI（macOS/Linux）
curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash
# 或 Homebrew（仅需 CLI 时）
brew install multica-ai/tap/multica

# 若服务在本机：
multica setup self-host

# 若服务在另一台机器：
multica setup self-host \
  --server-url https://api.example.com \
  --app-url https://app.example.com

# 确认状态
multica daemon status
# 应显示：Daemon: running + Agents 含已装工具 + Workspaces > 0

7. 远程访问（反向代理，生产必读）

Docker Compose 默认只绑定 127.0.0.1，不要直接改成 0.0.0.0 暴露公网（Docker 会绕过防火墙）。用 Caddy/Nginx 反向代理 + HTTPS。

.env 设置：

FRONTEND_ORIGIN=https://app.example.com
MULTICA_APP_URL=https://app.example.com
MULTICA_PUBLIC_URL=https://api.example.com

Caddy 配置（单 origin 模式，最省事）：

multica.example.com {
    handle /health { reverse_proxy 127.0.0.1:8080 }        # CLI 探测
    handle /ws { reverse_proxy 127.0.0.1:8080 { flush_interval -1 } }   # 网页实时
    handle /api/daemon/ws { reverse_proxy 127.0.0.1:8080 { flush_interval -1 } } # 守护进程长连接
    handle { reverse_proxy 127.0.0.1:3000 }                  # 其余交给前端
}

三条路径（/health、/ws、/api/daemon/ws）必须直通 backend（8080），缺了 /api/daemon/ws 守护进程会静默回退到轮询。

改 .env 后用 up -d 重建（docker compose restart 不重读 .env）：

docker compose -f docker-compose.selfhost.yml up -d

8. 邮件 / 登录 / 注册范围（生产）

邮件二选一（同时配了 SMTP 优先）：

# 方式 1：Resend（推荐）
RESEND_API_KEY=re_xxx
RESEND_FROM_EMAIL=noreply@example.com

# 方式 2：SMTP
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USERNAME=multica
SMTP_PASSWORD=<password>
SMTP_FROM_EMAIL=noreply@example.com

注册范围（生产锁定）：

ALLOW_SIGNUP=false
ALLOWED_EMAIL_DOMAINS=company.com      # 只允许公司域名
ALLOWED_EMAILS=partner@example.net     # 额外放行某位协作者

9. 升级 / 备份 / 停止

# 升级（git pull 更新 compose 文件，pull 拉新镜像，up -d 重建）
git pull --ff-only
docker compose -f docker-compose.selfhost.yml pull
docker compose -f docker-compose.selfhost.yml up -d
curl -fsS http://localhost:8080/readyz

# 升级前先备份 Postgres（注意：不要 pg_dump | gzip 直接管道）
docker compose -f docker-compose.selfhost.yml exec -T postgres \
  pg_dump -U multica multica > multica-backup.sql && gzip multica-backup.sql

# 停止（保留数据卷）
docker compose -f docker-compose.selfhost.yml down

关键坑：git pull 更新的是 compose 文件，不是程序版本；真正决定版本的是 docker compose pull（去 GHCR 拉 latest 镜像）。若 .env 里钉死了 MULTICA_IMAGE_TAG=v0.4.5，怎么 pull 都升不上去——先改回 latest。

10. Kubernetes 部署（可选）

有 K8s 集群可用 Helm chart：

kubectl create namespace multica

kubectl -n multica create secret generic multica-secrets \
  --from-literal=JWT_SECRET="$(openssl rand -hex 32)" \
  --from-literal=POSTGRES_PASSWORD="$(openssl rand -hex 16)" \
  --from-literal=RESEND_API_KEY="" \
  --from-literal=GOOGLE_CLIENT_SECRET="" \
  --from-literal=MULTICA_DEV_VERIFICATION_CODE=""

helm install multica oci://ghcr.io/multica-ai/charts/multica \
  --version <chart-version> -n multica

chart 创建 postgres（pgvector:pg17，10Gi PVC）+ backend（5Gi uploads PVC）+ frontend + 两个 Ingress。Helm 升级路径比 Compose 更可控（改 tag = 改 pod spec = 滚动更新）。

三、实践教程

1. 创建第一个智能体

前提：已有在线运行时（前文第 6 步完成）。

路径：工作区 → 智能体 → 新建智能体。必填仅两项：名称 + 运行时。其余可后补。

关键配置项：

配置	作用	示例
指令	每次执行都给：职责、边界、先查什么、允许改什么、如何交付、何时确认	"你负责审查前端 PR，只检查 React/TS 正确性、可访问性、组件模式一致性，不直接改代码，结论写在评论里"
Skills	挂载可复用的方法包	无障碍检查清单
运行时 + 模型	在哪台机器、哪款工具、哪个模型执行	Codex / deepseek-chat
Access	谁能运行它	仅自己 / 整个工作区 / 指定成员
并发上限	默认 6，daemon 全局默认 20，取较小值	—
环境变量	注入工具启动环境（放有限权限凭据）	只读 API key

环境变量 custom_env 在服务端明文存储，别放生产高价值凭据。默认新建智能体仅创建者本人可运行。

CLI 创建：

multica agent create \
  --name "Frontend Reviewer" \
  --runtime-id <runtime-id> \
  --instructions "先读改动和测试，只在评论里提交审查结论。"

2. 分配任务 & 四种触发方式

触发方式	说明
分配任务	智能体设为负责人，入队后开始
评论中 @智能体	不改负责人，只处理这条评论
直接对话	不依附任务的交流，每条消息触发一轮
自动化	cron 或 webhook 触发

快速上手：点"新建任务"（快捷键 C）→ 选智能体为创建者 → 一句话描述 → 提交。打开任务即可看到执行日志 + 时间线。

3. Skills：把成功经验沉淀成方法

Skill = SKILL.md 主文件 + 可选 references/、templates/、scripts/ 支持文件。四种导入方式：

方式	场景
手动创建	空白 SKILL.md 开始
从本地导入	含 SKILL.md 的文件夹 / .skill / .zip
从 URL 导入	GitHub / ClawHub / Skills.sh 已发布 skill
从运行时复制	扫描执行电脑上的 skill 快照

SKILL.md 写清：适用场景 → 开始前检查 → 执行步骤 → 结果交付形式 → 何时停下问人。

注意：部分 AI 工具也直接读仓库里的项目级 skill（如 .claude/skills/、.agents/skills/），这些由仓库管理，Multica 不会自动登记为工作区 skill。

4. 小队：多智能体协作

小队 = 1 个 leader 智能体 + 若干成员（智能体或人）。分配给小队后不会并发跑所有成员，而是先唤醒 leader，由它读上下文、用 @成员 派活、记 evaluation、派完就停。

适用：工作需要多种能力、且创建任务时定不了具体负责人。范围明确时直接分配单个智能体即可。

multica squad create --name "Product Delivery" --leader delivery-lead
multica squad member add <squad-id> --member-id <agent-id> --type agent --role "负责前端实现"

5. 自动化：cron + webhook

创建：自动化 → 选模板/空白 → 填 Runbook（智能体每次读的目标/背景/步骤）+ 执行方（智能体/小队）+ 输出模式 + 触发器。

输出模式	行为	适合
创建任务	每次触发先建任务再分配，记录留任务里	需团队跟进的工作
仅运行	直接建运行，不产生任务	后台无协作记录

时间表（标准 5 字段 cron，不含秒）：

0 9 * * 1-5        # 工作日 9:00（Asia/Shanghai）
*/30 * * * *       # 每 30 分钟（UTC）

Webhook：生成唯一 URL，POST JSON 触发（Body ≤ 256 KiB，可用 Idempotency-Key 去重）：

curl -X POST "$MULTICA_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: demo-001" \
  -d '{"event":"build.completed","eventPayload":{"status":"success"}}'

Webhook URL 里的 token 就是凭证，别进公开仓库/截图。泄漏后点"重新生成 URL"。

6. 飞书 Bot 集成（自托管需先配密钥）

自托管先设置加密密钥（.env）：

MULTICA_LARK_SECRET_KEY=$(openssl rand -base64 32)
# 重启 API 服务后，再到 智能体 → 集成 → 绑定到飞书 扫码授权

绑定后：私聊直接发消息；群里 @Bot；/issue 标题 + 描述创建任务。成员首次使用需通过绑定链接关联 Multica 账号。

7. CLI 常用命令速查

multica version                 # 版本
multica auth status             # 登录状态
multica daemon status           # 守护进程状态
multica daemon start|stop|restart
multica daemon logs -f          # 跟随日志
multica agent create|copy|get   # 智能体管理
multica issue rerun <issue-id>  # 重跑任务
multica skill import --file ./x.skill
multica skill refresh <skill-id>
multica squad create ...
multica autopilot trigger <autopilot-id>
multica config show              # 查看当前 profile 配置

四、安全模型（务必理解）

边界 = 运行守护进程的那个操作系统用户。 Multica 对文件系统沙箱不作任何保证：Codex 用 danger-full-access，Claude Code 用 --permission-mode bypassPermissions，以无人值守方式运行，审批请求自动应答。

这意味着：守护进程跑在谁的用户下，运行就能读写谁的一切文件、用谁的凭据、访问网络。

推荐隔离方式（从轻到重）： 1. 专用 Unix 用户 —— 建 multica 用户，只给它需要的仓库和凭据，用它跑守护进程。 2. 容器 —— 容器里跑守护进程，只挂载需要的目录和密钥。 3. 虚拟机 —— 隔离最彻底。

Multica 真正隔离的只有：每次运行独立 workdir（~/multica_workspaces/）、运行级 Codex/Hermes HOME、运行级 API token（绑定到该智能体+该运行）。

五、结合你的场景：关键决策（对抗式审查）

决策 1：用哪个 AI 编程工具当运行时？

候选（你已具备的）：

方案	优势	攻击点 / 失败模式
Hermes（`hermes`）	你正在用的就是它；skill 体系可复用；Multica 官方支持，skill 注入到单次执行 `HERMES_HOME/skills/`	需确认本机 `hermes` 命令在 PATH 且已登录；Hermes 在 Multica 里按运行隔离 skill
DeepSeek Harness（`dsh`）	你研究过（clone 过源码）；走 DeepSeek 模型，国内直连、便宜	需 `npm i -g @deepseek-ai/dsh` + `dsh plugin --profile multica add <bundle>` + `DEEPSEEK_API_KEY`；模型 id 用 `deepseek-official/deepseek-chat` 这种完整形式
Claude Code / Codex	生态最成熟	国外模型，国内需代理 + 海外账号，你当前环境不友好

结论：DeepSeek Harness 是你的最优解——模型走 DeepSeek（国内直连、你已有 key），且你已研究过它的架构。Hermes 作为备选（你更熟，但要看 hermes 命令是否已全局可调用）。被否决：Claude Code/Codex（国内网络 + 账号门槛，当前环境不划算）。

决策 2：部署方式选哪个？

方案	优势	攻击点
一键 install.sh	最快，脚本自动拉镜像+启动	依赖 raw.githubusercontent.com（国内可能被墙）
git clone + make selfhost	可控，能看到每一步	同样要 GitHub + GHCR 镜像
K8s/Helm	生产级、升级可控	你现在没 K8s 集群，过度设计

结论：git clone + make selfhost（或等价的 manual docker compose）——你本机 M4 Mac mini 有 Docker 即可跑，可控可排查。被否决：K8s（当前无集群，单机场景过度设计）。

决策 3：国内网络怎么办（关键！）

环节	风险	对策
`raw.githubusercontent.com`（install.sh）	国内常被墙/超时	用镜像 `raw.gitmirror.com` / `ghproxy` 前缀，或手动 `git clone` 仓库再 `make selfhost`
`ghcr.io` 镜像（backend/frontend）	国内拉取极慢	配置 Docker registry mirror，或改 `docker-compose.selfhost.yml` 里的镜像为国内 GHCR 代理（如 `ghcr.nju.edu.cn` 等，需实测当前可用性）
`brew install multica-ai/tap/multica`	brew tap 国内慢	用清华 brew 镜像，或直接 curl install.sh（同样有 raw 问题）

结论：手动 git clone 仓库（你的记忆里有 GitHub push 走 IP 直连的成功经验，clone 同理）+ 给 Docker 配国内 registry mirror 拉 GHCR 镜像，是当前最稳路径。安装 CLI 优先 brew（配清华镜像）或从仓库的 release 直接下载二进制。

六、落地清单（照着做）

[ ] 准备：确认 Docker + Compose v2 可用；本机 3000/8080 空闲
[ ] 部署服务：git clone --depth 1 https://github.com/multica-ai/multica.git && cd multica && make selfhost
[ ] 验证：curl -fsS http://localhost:8080/readyz 返回 {"status":"ok",...}
[ ] 登录：打开 localhost:3000，docker compose logs backend | grep "Verification code" 读码
[ ] 装运行时：npm i -g @deepseek-ai/dsh + dsh plugin --profile multica add <bundle> + 设 DEEPSEEK_API_KEY（或确认 hermes 在 PATH）
[ ] 装 CLI + 连接：brew install multica-ai/tap/multica → multica setup self-host → multica daemon status
[ ] 创建智能体：名称 + 选运行时（dsh/hermes）+ 写指令
[ ] 第一次任务：新建任务 → 选智能体 → 一句话描述 → 看执行日志跑通
[ ] （可选）配邮件：Resend/SMTP，告别日志读码
[ ] （可选）接飞书：.env 设 MULTICA_LARK_SECRET_KEY，智能体 → 集成 → 绑定飞书
[ ] （可选）沉淀 skill：把常用方法写成 SKILL.md 挂给智能体

附：26 种支持的工具（检测命令）

工具	命令	工具	命令
Antigravity	`agy`	Claude Code	`claude`
CodeBuddy	`codebuddy`	CodeArts	`codearts`
Codex	`codex`	Copilot CLI	`copilot`
Cursor Agent	`cursor-agent`	DeepSeek Harness	`dsh`
DevEco Code	`deveco`	Grok	`grok`
Hermes	`hermes`	Kimi	`kimi`
Kiro	`kiro-cli`	MiniMax Code	`mcode`
OpenClaw	`openclaw`	OpenCode	`opencode`
Pi / Oh-My-Pi	`pi` / `omp`	Qoder (CN)	`qodercli` / `qoderclicn`
Qwen Code / QwenPaw	`qwen` / `qwenpaw`	Reasonix	`reasonix`
Trae	`traecli`	Dim	`dim`

数据来源：multica.ai/docs/zh（22 个文档页）+ github.com/multica-ai/multica（SELF_HOSTING.md、docker-compose.selfhost.yml、README、AGENTS.md），2026-08 抓取。镜像地址、国内网络对策需以实际连通性为准（标注"需实测"处建议部署前先验证）。