news 2026/9/11 13:16:33

如何用 Docker Compose 自建部署 Multica 并确认服务就绪

作者头像

张小明

前端开发工程师

1.2k 24
文章封面图
如何用 Docker Compose 自建部署 Multica 并确认服务就绪

如何用 Docker Compose 自建部署 Multica 并确认服务就绪

【免费下载链接】multicaMake humans and AI agents work as one team — open-source and self-hostable.项目地址: https://gitcode.com/GitHub_Trending/mu/multica

Multica 是一个可自托管的服务，让你把 AI agent 和团队成员放进同一个工作区协作。自建分两部分：一部分是Multica 服务（Web、API 和 PostgreSQL，跑在一台装有 Docker 的机器上），另一部分是各开发者机器上的daemon（跑 Multica CLI 和 AI 编码工具）。本文覆盖前半部分：用 Docker Compose 把服务拉起，并确认数据库迁移完成、服务真正就绪，而不是仅仅"容器在跑"。

部署前确认环境

运行服务的机器需要满足以下条件（来自快速开始文档）：

  • Docker Engine 或 Docker Desktop，且docker compose（v2 语法）可用；
  • Git、Make、curl、OpenSSL；
  • 机器上的3000和8080端口空闲。

Multica 使用 Compose v2（docker compose调用），不支持旧版docker-composev1。先确认前两项：

docker info docker compose version

一条命令启动服务

克隆仓库并运行make selfhost：

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

首次运行时，make selfhost会依次做这些事（定义见 Makefile 的selfhost目标）：

  1. 从.env.example创建.env；
  2. 生成随机的JWT_SECRET、PostgreSQL 密码和MULTICA_VCS_SECRET_KEY；
  3. 从 GHCR 拉取 PostgreSQL、backend、frontend 三个镜像（镜像为pgvector/pgvector:pg17、ghcr.io/multica-ai/multica-backend与ghcr.io/multica-ai/multica-web，tag 由.env的MULTICA_IMAGE_TAG控制，默认latest）；
  4. 创建持久卷（pgdata存数据库，backend_uploads存上传文件）并启动三个容器；
  5. 轮询/health最多约 60 秒，就绪后打印前端/后端地址（等待逻辑在 scripts/selfhost-wait.sh）。

再次运行make selfhost会复用已有的.env和卷，不会重新生成密钥。

两点限制需要注意：

  • make selfhost只拉已发布的镜像，不从当前 checkout 构建代码。如果 GHCR 上对应 tag 还没发布，命令会失败并提示改用make selfhost-build（该目标用本地multica-backend:dev/multica-web:devtag 构建，不会覆盖拉下来的:latest镜像）。
  • 如果.env里把MULTICA_IMAGE_TAG固定到了某个精确版本，后续pull只会重复拉同一 tag，升级不会发生——升级前先用grep MULTICA_IMAGE_TAG .env确认。

手动执行 Docker Compose 步骤（可选）

如果想逐条手动操作而不是走make selfhost，流程是（见 SELF_HOSTING.md 的 "Manual Docker Compose Setup"）：

git clone https://github.com/multica-ai/multica.git cd multica cp .env.example .env

编辑.env，必须设置JWT_SECRET——docker compose 没设置它时会拒绝启动，生产环境的 backend 也会拒绝使用开发默认值或已知占位符。生成方式：

JWT_SECRET=$(openssl rand -hex 32)

然后拉镜像并启动：

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

确认服务就绪

"容器在运行"不等于服务可用。按以下顺序验证：

1. 查容器状态

docker compose -f docker-compose.selfhost.yml ps

postgres应显示healthy，backend和frontend应在运行中。

2. 查后端就绪端点/readyz

curl -fsS http://localhost:8080/readyz

预期响应：

{"status":"ok","checks":{"db":"ok","migrations":"ok"}}

这里要区分两个端点：/health是存活探针，只要进程活着就返回{"status":"ok"}，即使迁移失败也一样；/readyz会检查数据库连接和已应用的迁移集合，是真正能抓住"升级坏掉"的检查。非 HTTP 200 或任一检查不是ok，都说明新版本没有完成迁移，先看后端日志再对外提供服务。

数据库迁移在 backend 每次启动时自动执行（docker/entrypoint.sh 中运行./migrate up），没有需要手动执行的迁移命令。想观察迁移过程：

docker compose -f docker-compose.selfhost.yml logs -f backend

3. 打开前端

浏览器访问 http://localhost:3000，能进入登录页说明前端正常。注意 docker-compose.selfhost.yml 把3000/8080只绑定到127.0.0.1，不要改成0.0.0.0直接暴露到公网；需要远程访问时用反向代理加 HTTPS（快速开始文档中给出了 Caddy 的双域名与单域名示例配置）。

首次登录验证

Docker 自托管栈默认APP_ENV=production，默认没有固定验证码，也没有配置邮件服务。请求验证码后，从后端日志读取它：

docker compose -f docker-compose.selfhost.yml logs backend \ | grep "Verification code"

日志里会有类似这样的一行（文档示例）：

[DEV] Verification code for you@example.com: 123456

填入验证码即可创建第一个工作区。配置好 Resend（.env中设置RESEND_API_KEY）或 SMTP 后，验证码会直接发到邮箱，见 Auth setup。警告：APP_ENV=production会禁用固定验证码，公开实例上不要设置MULTICA_DEV_VERIFICATION_CODE。

服务就绪后的常用命令与限制

从multica仓库目录执行：

# 查看状态 docker compose -f docker-compose.selfhost.yml ps # 跟踪后端日志 docker compose -f docker-compose.selfhost.yml logs -f backend # 应用 .env 的修改（重新读取 .env 并重建容器） docker compose -f docker-compose.selfhost.yml up -d # 停止服务，保留卷 docker compose -f docker-compose.selfhost.yml down

两条容易踩坑的限制：

  • docker compose restart只重启已有容器，不会重新读取.env。改了配置必须用up -d重建容器才生效。
  • docker compose down保留pgdata和backend_uploads两个卷；加-v会连数据库一起删掉，除非确实要清空实例，不要执行docker compose down -v。

验证不通过时先查什么

快速开始文档给出的对照表：

现象先检查
/readyz不返回ok运行docker compose -f docker-compose.selfhost.yml logs backend postgres
收不到验证码请求验证码后，在后端日志里搜索Verification code
daemon 列表里没有Agents确认 AI 编码工具在PATH上且已登录，然后运行multica daemon restart
issue 一直排队运行multica daemon status确认 daemon 在运行且连到了工作区

更多场景见仓库中的 Troubleshooting 文档。

下一步

服务就绪后，在跑 AI 编码工具的电脑上安装 Multica CLI 并执行multica setup self-host，daemon 会在本地启动；用multica daemon status确认输出中Daemon: running、Agents列出已装的编码工具、Workspaces大于0。完整的 CLI 与 daemon 步骤见 SELF_HOSTING.md 的 Step 3/Step 4。

<输出文章> </输出文章>

等等——我发现刚才的输出里误加了外层标签说明，重新按规范只输出一次完整文章：

<输出文章>

如何用 Docker Compose 自建部署 Multica 并确认服务就绪

Multica 是一个可自托管的服务，让你把 AI agent 和团队成员放进同一个工作区协作。自建分两部分：一部分是Multica 服务（Web、API 和 PostgreSQL，跑在一台装有 Docker 的机器上），另一部分是各开发者机器上的daemon（跑 Multica CLI 和 AI 编码工具）。本文覆盖前半部分：用 Docker Compose 把服务拉起，并确认数据库迁移完成、服务真正就绪，而不是仅仅"容器在跑"。

部署前确认环境

运行服务的机器需要满足以下条件（来自快速开始文档）：

  • Docker Engine 或 Docker Desktop，且docker compose（v2 语法）可用；
  • Git、Make、curl、OpenSSL；
  • 机器上的3000和8080端口空闲。

Multica 使用 Compose v2（docker compose调用），不支持旧版docker-composev1。先确认前两项：

docker info docker compose version

一条命令启动服务

克隆仓库并运行make selfhost：

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

首次运行时，make selfhost会依次做这些事（定义见 Makefile 的selfhost目标）：

  1. 从.env.example创建.env；
  2. 生成随机的JWT_SECRET、PostgreSQL 密码和MULTICA_VCS_SECRET_KEY；
  3. 从 GHCR 拉取 PostgreSQL、backend、frontend 三个镜像（镜像为pgvector/pgvector:pg17、ghcr.io/multica-ai/multica-backend与ghcr.io/multica-ai/multica-web，tag 由.env的MULTICA_IMAGE_TAG控制，默认latest）；
  4. 创建持久卷（pgdata存数据库，backend_uploads存上传文件）并启动三个容器；
  5. 轮询/health最多约 60 秒，就绪后打印前端/后端地址（等待逻辑在 scripts/selfhost-wait.sh）。

再次运行make selfhost会复用已有的.env和卷，不会重新生成密钥。

两点限制需要注意：

  • make selfhost只拉已发布的镜像，不从当前 checkout 构建代码。如果 GHCR 上对应 tag 还没发布，命令会失败并提示改用make selfhost-build（该目标用本地multica-backend:dev/multica-web:devtag 构建，不会覆盖拉下来的:latest镜像）。
  • 如果.env里把MULTICA_IMAGE_TAG固定到了某个精确版本，后续pull只会重复拉同一 tag，升级不会发生——升级前先用grep MULTICA_IMAGE_TAG .env确认。

手动执行 Docker Compose 步骤（可选）

如果想逐条手动操作而不是走make selfhost，流程是（见 SELF_HOSTING.md 的 "Manual Docker Compose Setup"）：

git clone https://github.com/multica-ai/multica.git cd multica cp .env.example .env

编辑.env，必须设置JWT_SECRET——docker compose 没设置它时会拒绝启动，生产环境的 backend 也会拒绝使用开发默认值或已知占位符。生成方式：

JWT_SECRET=$(openssl rand -hex 32)

然后拉镜像并启动：

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

确认服务就绪

"容器在运行"不等于服务可用。按以下顺序验证：

1. 查容器状态

docker compose -f docker-compose.selfhost.yml ps

postgres应显示healthy，backend和frontend应在运行中。

2. 查后端就绪端点/readyz

curl -fsS http://localhost:8080/readyz

预期响应：

{"status":"ok","checks":{"db":"ok","migrations":"ok"}}

这里要区分两个端点：/health是存活探针，只要进程活着就返回{"status":"ok"}，即使迁移失败也一样；/readyz会检查数据库连接和已应用的迁移集合，是真正能抓住"升级坏掉"的检查。非 HTTP 200 或任一检查不是ok，都说明新版本没有完成迁移，先看后端日志再对外提供服务。

数据库迁移在 backend 每次启动时自动执行（docker/entrypoint.sh 中运行./migrate up），没有需要手动执行的迁移命令。想观察迁移过程：

docker compose -f docker-compose.selfhost.yml logs -f backend

3. 打开前端

浏览器访问 http://localhost:3000，能进入登录页说明前端正常。注意 docker-compose.selfhost.yml 把3000/8080只绑定到127.0.0.1，不要改成0.0.0.0直接暴露到公网；需要远程访问时用反向代理加 HTTPS（快速开始文档中给出了 Caddy 的双域名与单域名示例配置）。

首次登录验证

Docker 自托管栈默认APP_ENV=production，默认没有固定验证码，也没有配置邮件服务。请求验证码后，从后端日志读取它：

docker compose -f docker-compose.selfhost.yml logs backend \ | grep "Verification code"

日志里会有类似这样的一行（文档示例）：

[DEV] Verification code for you@example.com: 123456

填入验证码即可创建第一个工作区。配置好 Resend（.env中设置RESEND_API_KEY）或 SMTP 后，验证码会直接发到邮箱，见 Auth setup。警告：APP_ENV=production会禁用固定验证码，公开实例上不要设置MULTICA_DEV_VERIFICATION_CODE。

服务就绪后的常用命令与限制

从multica仓库目录执行：

# 查看状态 docker compose -f docker-compose.selfhost.yml ps # 跟踪后端日志 docker compose -f docker-compose.selfhost.yml logs -f backend # 应用 .env 的修改（重新读取 .env 并重建容器） docker compose -f docker-compose.selfhost.yml up -d # 停止服务，保留卷 docker compose -f docker-compose.selfhost.yml down

两条容易踩坑的限制：

  • docker compose restart只重启已有容器，不会重新读取.env。改了配置必须用up -d重建容器才生效。
  • docker compose down保留pgdata和backend_uploads两个卷；加-v会连数据库一起删掉，除非确实要清空实例，不要执行docker compose down -v。

验证不通过时先查什么

快速开始文档给出的对照表：

现象先检查
/readyz不返回ok运行docker compose -f docker-compose.selfhost.yml logs backend postgres
收不到验证码请求验证码后，在后端日志里搜索Verification code
daemon 列表里没有Agents确认 AI 编码工具在PATH上且已登录，然后运行multica daemon restart
issue 一直排队运行multica daemon status确认 daemon 在运行且连到了工作区

更多场景见仓库中的 Troubleshooting 文档。

下一步

服务就绪后，在跑 AI 编码工具的电脑上安装 Multica CLI 并执行multica setup self-host，daemon 会在本地启动；用multica daemon status确认输出中Daemon: running、Agents列出已装的编码工具、Workspaces大于0。完整的 CLI 与 daemon 步骤见 SELF_HOSTING.md 的 Step 3/Step 4。

【免费下载链接】multicaMake humans and AI agents work as one team — open-source and self-hostable.项目地址: https://gitcode.com/GitHub_Trending/mu/multica

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

版权声明: 本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若内容造成侵权/违法违规/事实不符，请联系邮箱：809451989@qq.com进行投诉反馈，一经查实，立即删除！
网站建设 2026/9/11 13:08:51

从 Armoury Crate 迁移到 G-Helper：卸载与配置完整指南

从 Armoury Crate 迁移到 G-Helper&#xff1a;卸载与配置完整指南 【免费下载链接】g-helper Lightweight Armoury Crate alternative for Asus laptops with nearly the same functionality. Works with ROG Zephyrus, Flow, TUF, Strix, Scar, ProArt, Vivobook, Zenbook, E…

作者头像 李华
网站建设 2026/9/11 13:02:21

不联网也能把语音转成文字：Vosk 离线语音识别实用笔记

不联网也能把语音转成文字&#xff1a;Vosk 离线语音识别实用笔记 【免费下载链接】vosk-api Offline speech recognition API for Android, iOS, Raspberry Pi and servers with Python, Java, C# and Node 项目地址: https://gitcode.com/GitHub_Trending/vo/vosk-api …

作者头像 李华
网站建设 2026/9/11 13:02:00

车载Android USB开发：从即插即用到车规级系统工程

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

作者头像 李华
网站建设 2026/9/11 12:59:26

context-mode：用作用域控制让AI编程上下文瘦身十余倍

做 AI 辅助开发大半年&#xff0c;我最大的感受不是模型不够聪明&#xff0c;而是它经常被"塞进上下文的无关代码"带偏。明明只改一个支付模块的 bug&#xff0c;AI 却把订单、库存、用户积分全翻了一遍&#xff0c;最后给出一段逻辑错乱的代码。后来我做了个小工具c…

作者头像 李华
网站建设 2026/9/11 12:59:08

Maestro移动UI自动化测试：3分钟从零跑通第一条YAML流程

Maestro移动UI自动化测试&#xff1a;3分钟从零跑通第一条YAML流程 【免费下载链接】Maestro Painless E2E Automation for Mobile and Web 项目地址: https://gitcode.com/GitHub_Trending/ma/Maestro 当你想验证 App 里"点按钮→出结果"这条链路&#xff0c…

作者头像 李华