企业官网建设流程全解析

Multica 自托管完全指南：从 Docker Compose 到 Kubernetes 的私有化部署实战

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

Multica 是一套开源的「AI 原生任务管理」平台，让人类与 AI Agent 在同一张工作台上协作。本文以仓库根目录的 SELF_HOSTING.md 为主干，面向希望将 Multica 部署到自己基础设施上的团队，完整讲解架构、一条命令快速安装、手工分步部署、Kubernetes Helm 部署、用量看板聚合调度、升级与回滚等全生命周期操作。读完本文，你将掌握如何在自有服务器或 k3s/K8s 集群上跑起一套生产可用的 Multica，并让团队成员的本地 Agent（daemon）接入该自托管服务。

总体架构与部署模型

自托管 Multica 的最小拓扑只有三个组件：

在 docker-compose.selfhost.yml 中，三个服务分别对应postgres（pgvector/pgvector:pg17镜像，实际仅作为标准 PostgreSQL 17 使用）、backend与frontend。其中后端容器在每次启动时自动执行数据库迁移（见 docker/entrypoint.sh），因此没有单独的迁移命令需要运维手动执行。

关键的一点是：自托管只替换掉「Multica Cloud」那部分云端能力。每个需要在本地运行 AI Agent 的用户，还要在自己机器上安装multicaCLI 并运行 agent daemon——daemon 负责探测本机已安装的 AI 编码工具（如 Claude Code、Codex、Cursor 等），把它们注册到服务器，并在任务被分配给 Agent 时在本机执行。也就是说，部署模型天然是「一台服务机 + 若干开发机」的分布式结构，服务端与执行端可以同机，也可以完全分离。

快速安装（推荐）：两条命令搞定

如果服务机与开发机都满足前提条件，官方推荐用安装脚本一条命令完成「服务器部署 + CLI 安装」。

macOS / Linux：

# 1. Install CLI + provision the self-host server curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash -s -- --with-server # 2. Configure CLI, authenticate, and start the daemon multica setup self-host

Windows（PowerShell）：

# 1. Install CLI + provision the self-host server $env:MULTICA_MODE="with-server"; irm https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.ps1 | iex # 2. Configure CLI, authenticate, and start the daemon multica setup self-host

这一过程实际完成的工作包括：安装multicaCLI、检出最新的 self-host 资产、从 GHCR 拉取官方镜像、把全部配置指向localhost。完成后打开 http://localhost:3000 即可开始使用。

前提条件：机器上必须已安装 Docker 与 Docker Compose（脚本会检测并给出缺失时的安装链接）。注意仓库明确要求 Compose v2（docker compose），Makefile 中的REQUIRE_COMPOSE检查会在遇到 legacy v1docker-compose时直接报错退出。

只要 CLI？如果自托管服务器已在运行，仅需在 macOS/Linux 上安装 CLI，直接用 Homebrew：

brew install multica-ai/tap/multica

关于登录：首次打开 http://localhost:3000 时，需要在.env中配置RESEND_API_KEY（推荐，走邮件验证码）；如果保持 Resend 未配置，验证码会打印在后端日志里，从日志中复制即可。详见下文「Step 2 — 登录」。

分步手工部署（Docker Compose 路线）

偏好手动控制每一步的团队，可以完全脱离安装脚本：

Step 1 — 启动服务器

前置条件同样是 Docker 与 Docker Compose。

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

make selfhost这个目标（对应 Makefile 中的selfhost）会自动完成三件事：

1. 若.env不存在，从.env.example复制生成；
2. 用openssl rand生成随机JWT_SECRET、POSTGRES_PASSWORD与MULTICA_VCS_SECRET_KEY并回填进.env；
3. 通过docker compose -f docker-compose.selfhost.yml pull && up -d拉取镜像并启动全套服务，随后调用 scripts/selfhost-wait.sh 等待后端通过健康检查。

再次运行make selfhost会复用已有的.env与数据卷，不会重新生成密钥。默认情况下它会拉取 GHCR 上最新稳定版镜像；如果 GHCR 上还没有当前选中的 tag，make selfhost会提示改用make selfhost-build。

make selfhost-build

selfhost-build使用本地构建的multica-backend:dev/multica-web:dev标签（叠加 docker-compose.selfhost.build.yml 构建），因此不会覆盖已拉取的:latest镜像。若要从当前 checkout 本地构建镜像调试源码，这是正确的入口。

启动完成后：

• 前端（Frontend）：http://localhost:3000
• 后端 API（Backend）：http://localhost:8080

容器内部端口固定为 8080/3000，暴露到宿主机的端口可通过.env中PORT（默认8080，另支持BACKEND_PORT→API_PORT→SERVER_PORT三级别名，顺序固定）与FRONTEND_PORT（默认3000）调整，改动无需重建镜像。

想手动跑 Compose 而不是make selfhost？见文末「手动 Docker Compose 安装」小节。

Step 2 — 登录

打开 http://localhost:3000，输入邮箱请求验证码。Docker self-host 栈默认把APP_ENV设为production（见 docker-compose.selfhost.yml），默认没有固定验证码，从以下三种方式中选择：

• 推荐（生产）：在.env配置RESEND_API_KEY后重启后端，真实验证码将发送到你输入的邮箱。参见 SELF_HOSTING_ADVANCED.md → Email（认证必需）。

• 未配置邮件：验证码由服务端生成并打印在后端容器日志中，搜索关键字即可看到形如[DEV] Verification code for ...:的行，适合单机一次性测试：

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

• 确定性的本地/私有测试：在.env中设置APP_ENV=development与MULTICA_DEV_VERIFICATION_CODE=888888后重启后端，即可使用固定验证码888888。该固定码在APP_ENV=production时会被忽略。

另外，ALLOW_SIGNUP、DISABLE_WORKSPACE_CREATION、GOOGLE_CLIENT_ID三项的变更同样在重启后端/Compose 栈后生效——Web UI 在运行时通过/api/config读取这三项，无需重新构建前端。锁定工作区创建的推荐顺序见 SELF_HOSTING_ADVANCED.md → Signup Controls。

警告：绝不要在公网可达的实例上设置MULTICA_DEV_VERIFICATION_CODE——任何知道某个邮箱地址的人都能用这个固定码直接登录。

Step 3 — 安装 CLI 并启动 daemon

daemon 运行在本地机器上（而不是 Docker 内），它检测已安装的 AI Agent CLI、向服务器注册，并在 Agent 被分配任务时在本机执行。每一位要在本地跑 Agent 的成员都需要完成 a、b 两步。

a) 安装 CLI 与至少一个 AI Agent

brew install multica-ai/tap/multica

同时至少要安装一个 AI Agent CLI（可执行文件需在PATH上），仓库当前支持并检测的长名单包括：Claude Code（claude）、Antigravity CLI（agy）、CodeBuddy Code（codebuddy）、DevEco Code（deveco）、Codex（codex）、GitHub Copilot CLI（copilot）、OpenClaw（openclaw）、OpenCode（opencode）、Hermes（hermes）、Pi（pi）、Cursor Agent（cursor-agent）、Kimi（kimi）、Reasonix（reasonix，需先reasonix setup）、Dim（dim）、Kiro CLI（kiro-cli）、Qoder CLI（qodercli）、Qoder CN CLI（qoderclicn）、Trae CLI（traecli）、Grok Build CLI（grok）、Qwen Code（qwen）、QwenPaw（qwenpaw，模型在 QwenPaw 自身配置中选择）、MiniMax Code CLI（mcode≥ 0.1.2，需要 Node>=22.19 <23或>=24 <27，先npm install --global @minimax-ai/code@latest再mcode login）以及 DeepSeek Harness（dsh，需安装 Multica runtime profile 并设置DEEPSEEK_API_KEY）。

如果你用的是桌面应用（apps/desktop），daemon 能力同样被内置其中，接入自托管服务的方式一致。各 Agent 的二进制路径与模型也可通过 CLI 配置覆盖，见 SELF_HOSTING_ADVANCED.md → CLI / Daemon。

b) 一条命令完成配置

multica setup self-host

该命令自动完成 4 件事：

1. 配置 CLI 连接localhost（端口 8080/3000）；
2. 打开浏览器完成认证；
3. 发现你的工作区（workspaces）；
4. 在后台启动 daemon。

对于使用自定义域名的内网（on-premise）部署：

multica setup self-host --server-url https://api.example.com --app-url https://app.example.com

验证 daemon 是否在运行：

multica daemon status

输出应包含Daemon: running、本机已安装的 Agents 列表，以及大于 0 的 Workspaces 数量。

替代方案：想手动逐条配置 CLI，见文末「手动 CLI 配置」小节。

Step 4 — 验证并开始使用

1. 在 Web 应用打开你的工作区（http://localhost:3000）；
2. 进入Settings → Runtimes，应能看到你的机器已上线；
3. 进入Settings → Agents新建一个 agent；
4. 创建一个 issue 并指派给你的 agent——它会自动领取并执行任务。

Kubernetes 部署（Helm 备选路线）

已有 Kubernetes 集群的团队可以直接部署，不需要 Docker Compose。发布在oci://ghcr.io/multica-ai/charts/multica的 OCI Helm chart，或仓库源码目录 deploy/helm/multica/ 下的 chart，目标环境是典型的 k3s/k8s：带 Ingress Controller 与默认ReadWriteOnceStorageClass（官方按 k3s + Traefik +local-path验证编写，其他集群略作调整即可）。

chart 会在目标命名空间创建以下资源：

• multica-postgres—pgvector/pgvector:pg17，挂载 10Gi PVC；
• multica-backend— Go API/WS 服务，默认挂载 5GiReadWriteOnceuploads PVC；若已配置 S3（backend.config.s3Bucket）且不希望 chart 声明该 PVC，可设backend.uploads.persistence.enabled=false；
• multica-frontend— Next.js standalone 服务器；
• 两个Ingress资源（web host 与 backend host 各一个，默认traefikclassName）；
• multica-configConfigMap（由values.yaml渲染，见 deploy/helm/multica/values.yaml）。

multica-secretsSecret不由 chart 管理——你需要用kubectl手工创建一次，确保真实密钥从不落进 git。

运行时前端上游：当前multica-web镜像在 Next.js 服务器运行时读取REMOTE_API_URL与DOCS_URL，因此 API/docs 上游变更不需要重建前端。chart 默认把REMOTE_API_URL指向本次发布的 backend Service。frontend.compatibility.backendAlias仅为兼容那些构建时写死REMOTE_API_URL=http://backend:8080的旧镜像而存在，新镜像保持false即可。

前提条件：kubectl与helm（--take-ownership需要 v3.13+，或 v4+）已配置目标集群，有 Ingress Controller（Traefik/NGINX）与默认 StorageClass。

Step 1 — 把主机名指向集群

chart 默认主机名为multica.dev.lan（web）与api.multica.dev.lan（backend）。两种选择：

• /etc/hosts（每台需要访问的机器，包括跑 daemon 的开发机）：

  192.168.1.206 multica.dev.lan api.multica.dev.lan

  把192.168.1.206换成任意一个 Ingress Controller Service 可达的节点 IP。

• 本地 DNS（Pi-hole、Unbound 等）：为两个主机名添加指向集群 Ingress IP 的 A 记录。

要换主机名，安装时覆盖ingress.frontend.host、ingress.backend.host以及backend.config.appUrl、backend.config.frontendOrigin、backend.config.localUploadBaseUrl、backend.config.googleRedirectUri等对应值（见下文 Step 4）。

Step 2 — 创建命名空间

kubectl create namespace multica

Step 3 — 创建multica-secretsSecret

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=CLOUDFRONT_PRIVATE_KEY="" \ --from-literal=MULTICA_DEV_VERIFICATION_CODE=""

可选值先留空，之后可随时补（见 Step 5）。

Step 4 — 安装 chart

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

版本号对应关系：发布的 chart 版本会去掉 Git tag 前导的v——例如 release tagv0.3.5会发布成 chart 版本0.3.5，chart 默认把 backend/frontend 镜像 tag 指向v0.3.5。

覆盖默认值的方式是先导出 values 修改后再以-f传入：

helm show values oci://ghcr.io/multica-ai/charts/multica \ --version <chart-version> > my-values.yaml # edit my-values.yaml — e.g. change ingress hosts, image tags, resource limits helm install multica oci://ghcr.io/multica-ai/charts/multica \ --version <chart-version> \ -n multica \ -f my-values.yaml

从源码 checkout 开发时，直接使用本地 chart 路径：

helm install multica deploy/helm/multica -n multica

随后观察 Pod 启动：

kubectl -n multica get pods -w

冷集群上后端可能会先处于Running但迟迟不Ready——它在等 PostgreSQL 就绪并跑迁移，startupProbe会吸收这段等待期，Pod 不应因此重启。后端一旦报告Ready，说明迁移已完成，/healthz返回 OK：

curl -H "Host: api.multica.dev.lan" http://<ingress-ip>/healthz # {"status":"ok","checks":{"db":"ok","migrations":"ok"}}

然后浏览器打开 http://multica.dev.lan。

更可靠的就绪判断建议使用/readyz（/healthz是其别名，对应 server/cmd/server/router.go）：它同时检查数据库与已应用的迁移集；而/health只是存活探针，进程在即返回 ok，无法发现迁移失败。两种升级场景下官方都推荐用/readyz验证。

Step 5 — 登录

chart 默认APP_ENV=production（values.yaml中backend.config.appEnv），同样没有固定验证码。与 Docker 路线完全一致的三个选项：

• 推荐（生产）：给 Secret 打补丁填入真实的 Resend key，然后重启后端：

  kubectl -n multica patch secret multica-secrets --type=merge \ -p '{"stringData":{"RESEND_API_KEY":"re_xxx"}}' kubectl -n multica rollout restart deploy/multica-backend

  真实验证码会发送到输入的邮箱，参见 SELF_HOSTING_ADVANCED.md → Email。

• 未配置邮件：验证码打印在后端 Pod 日志中：

  kubectl -n multica logs -f deploy/multica-backend | grep "Verification code"

• 确定性本地/私有测试：在 values 中设backend.config.appEnv: development，在 Secret 中设MULTICA_DEV_VERIFICATION_CODE=888888，然后升级并重启：

  helm upgrade multica oci://ghcr.io/multica-ai/charts/multica \ --version <chart-version> \ -n multica \ -f my-values.yaml --set backend.config.appEnv=development kubectl -n multica patch secret multica-secrets --type=merge \ -p '{"stringData":{"MULTICA_DEV_VERIFICATION_CODE":"888888"}}' kubectl -n multica rollout restart deploy/multica-backend

ALLOW_SIGNUP、DISABLE_WORKSPACE_CREATION、GOOGLE_CLIENT_ID在values.yaml中分别对应backend.config.allowSignup、disableWorkspaceCreation、googleClientId。helm upgrade后 ConfigMap 哈希变化会自动触发后端 Pod 滚动；Web UI 在运行时从/api/config读取这三项，无需重建前端。

警告：同 Docker 路线——不要在公网实例上设置MULTICA_DEV_VERIFICATION_CODE。

Step 6 — 安装 CLI 并启动 daemon

daemon 运行在本地机器而非集群内。先按上文「Step 3」安装 CLI 与一个 AI Agent，再把 CLI 指向 Ingress 主机名：

multica setup self-host \ --server-url http://api.multica.dev.lan \ --app-url http://multica.dev.lan

运行 daemon 的机器必须配好 Step 1 中的/etc/hosts（或 DNS）记录。

升级（Kubernetes）

• 追浮动 tag（latest）：当 values 仍使用可变的latest镜像 tag、且不想改动 chart 版本时：

  kubectl -n multica rollout restart deploy/multica-backend deploy/multica-frontend

  注意 chart 默认pullPolicy: IfNotPresent——节点上若已缓存同名 tag 会复用旧镜像，重启不生效；要追浮动 tag 需先改成Always。升级的可靠路径是改 tag 后helm upgrade。

• 升级到指定 release：升级到配套 chart 版本即可，发布版 chart 会把应用镜像默认到对应的 Git tag：

  helm upgrade multica oci://ghcr.io/multica-ai/charts/multica \ --version <chart-version> \ -n multica \ -f my-values.yaml

• 独立于 chart 版本覆盖镜像 tag：在 values 文件中显式设置：

  images: backend: tag: v0.2.4 frontend: tag: v0.2.4

  再执行同样的helm upgrade -f my-values.yaml。

• 回滚：

  helm -n multica rollback multica

v0.3.4→v0.3.5+升级报refusing to drop legacy daily rollups: ...？这是迁移103的 fail-closed 保护：丢弃 legacy daily rollups 之前要求task_usage_hourly已播种数据。自 MUL-2957 起migrate up会在应用迁移103前自动运行幂等的按月切片 backfill，正常升级就是一次helm upgrade+ backend 滚动。若仍在使用 MUL-2957 之前的二进制或自动钩子失败，可对同一数据库手工执行独立 backfill（kubectl -n multica exec deploy/multica-backend -- ./backfill_task_usage_hourly --sleep-between-slices=2s），再重启 backend 重新应用迁移。完整恢复流程见 SELF_HOSTING_ADVANCED.md → Usage Dashboard Rollup。

拆除

# 移除工作负载但保留 PVC 与 Secret helm -n multica uninstall multica # 全部清除，包括 PostgreSQL 数据与上传文件 kubectl delete namespace multica

Usage Dashboard 用量看板聚合：进程内调度器与兼容路径

用量（Usage）/运行时（Runtime）看板读取派生表task_usage_hourly，该表由rollup_task_usage_hourly()填充。自 MUL-2957 起，后端通过 DB-backed 调度器（sys_cron_executions表）在每个副本进程内运行该聚合：全新 self-host 安装无需任何运维操作，内置的pgvector/pgvector:pg17镜像原样可用——不需要换成内置pg_cron的镜像，不需要注册外部 cron、systemd timer，也不需要 KubernetesCronJob。

多副本是安全的：每个副本每 30 秒 tick 一次并尝试认领当前 5 分钟 UTC 计划，而(job_name, scope_kind, scope_id, plan_time)唯一键保证每个计划只有一个赢家。用下面的查询观察稳态运行：

SELECT plan_time, status, attempt, runner_id, error_code, error_msg, started_at, finished_at FROM sys_cron_executions WHERE job_name = 'rollup_task_usage_hourly' ORDER BY plan_time DESC LIMIT 20;

例外 — WeCom（企业微信）智能机器人必须单副本运行。与出站为无状态 HTTP（任意副本均可执行）的 Slack、Lark 不同，WeCom 智能机器人唯一的出站通道是进程内 WebSocket 长连接：Agent 回复与 inbox 推送只由当前持有某机器人连接租约的副本投递。若启用 WeCom（设置了MULTICA_WECOM_SECRET_KEY）却运行了多个后端副本，未持有租约副本上产生的响应会被静默丢弃，WeCom 用户什么都看不到。在跨副本出站路由落地之前，请把启用 WeCom 的后端作为单副本运行；其余一切（包括上述聚合调度器）多副本均安全。

完整的参考信息（审计表语义、advisory lock 4246、独立 backfill 命令、各 flag 说明、v0.3.4 → v0.3.5+迁移自动钩子）见 SELF_HOSTING_ADVANCED.md → Usage Dashboard Rollup。

兼容路径（仅限既有部署）

在 MUL-2957 之前，外部调度器——注册在数据库上的pg_cron、外部 cron job、systemd timer 或 KubernetesCronJob——直接调用SELECT rollup_task_usage_hourly()是唯一选项，现在仍属于受支持的兼容路径，只是不再是推荐做法；新部署应依赖进程内调度器。SQL 函数内部持有 advisory lock4246，所以进程内调度器与任何已存在的外部调度可以共存，绝不会重复写 rollup。

如果生产环境已有pg_cron任务，安全退役顺序如下：

1. 确认进程内调度器健康——至少在某个后端副本上，sys_cron_executions中应持续出现rollup_task_usage_hourly的 SUCCESS 行：

   SELECT plan_time, status, runner_id, finished_at FROM sys_cron_executions WHERE job_name = 'rollup_task_usage_hourly' AND status = 'SUCCESS' ORDER BY plan_time DESC LIMIT 5;

2. 按计划稳定出现 SUCCESS 后，取消冗余的pg_cron注册：

   SELECT cron.unschedule('rollup_task_usage_hourly') FROM cron.job WHERE jobname = 'rollup_task_usage_hourly';

3. 除非确定没有其他工作负载依赖pg_cron，否则保留该扩展本身。内置pgvector/pgvector:pg17镜像并不带pg_cron，Multica 默认安装完全不需要它；若你自定义镜像里还有别的任务在用它，是否卸载是独立的决定。

外部 cron / systemd timer / KubernetesCronJob这类直接调用SELECT rollup_task_usage_hourly()的部署可同样退役——一旦sys_cron_executions稳定出现来自进程内调度器的 SUCCESS 行，外部任务即冗余，可以移除。

停止服务

用安装脚本部署的实例：

curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash -s -- --stop

手动 clone 仓库的实例：

# 停止 Docker Compose 服务（backend、frontend、database） make selfhost-stop # 停止本地 daemon multica daemon stop

注意docker compose down（不含-v）会保留pgdata与backend_uploads两个命名卷；只有加了-v才会连数据库一起删除，非必要不要执行。

切换到 Multica Cloud

如果原本在自托管，现在想将 CLI 切换回官方云服务（https://multica.ai）：

multica setup

这会重新配置 CLI 指向云端、重新认证并重启 daemon，覆盖既有配置前会先征求你的确认。本地 Docker 服务不受影响——不需要它们时可自行停止。

升级（Docker Compose 路线）

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

想要停留在特定版本，可在.env中把MULTICA_IMAGE_TAG钉到精确版本（如v0.2.4）。后端启动时自动执行迁移。若 GHCR 尚未发布所选 tag，回退到make selfhost-build或docker compose -f docker-compose.selfhost.yml -f docker-compose.selfhost.build.yml up -d --build。

这里要特别澄清一个常见误区：git pull更新的是docker-compose.selfhost.yml本身（新的环境变量、新服务、变更的健康检查），不是获取新版本的方式。实际运行的版本由docker compose pull决定——它询问 GHCR 当前 tag 指向什么。所以几个月前的 checkout 也会拉到今天的latest镜像；反之只git pull而不重新 pull 镜像、重建容器，版本不会有任何变化。另外，如果你的.env钉死了MULTICA_IMAGE_TAG（如v0.4.5），上述两条升级命令都不会带来新版本——先确认：

grep MULTICA_IMAGE_TAG .env

make selfhost只在.env缺失时生成它；对既有安装重复执行不会覆盖你的JWT_SECRET、Postgres 密码、邮件设置与FRONTEND_ORIGIN。

升级前先备份数据库（迁移只进不退）：

docker compose -f docker-compose.selfhost.yml exec -T postgres \ pg_dump -U multica multica > multica-backup.sql && gzip multica-backup.sql

注意：不要把pg_dump直接管道给gzip——shell 报告的是管道最后一个命令的退出码，pg_dump … | gzip > backup.sql.gz即使 dump 失败也返回 0，只会留下一个看似正常的空档案。先重定向到文件，再用&&压缩，才能真正以pg_dump自身的退出码为准。

v0.3.4→v0.3.5+升级报refusing to drop legacy daily rollups: ...？这是迁移103的 fail-closed 保护：丢弃 legacy daily rollups 前要求task_usage_hourly已播种。自 MUL-2957 起migrate up会在应用103前自动运行 backfill，单次调用即可完成升级。若仍用旧版二进制或自动钩子失败，先手动运行backfill_task_usage_hourly再重试升级，完整说明见 SELF_HOSTING_ADVANCED.md → Usage Dashboard Rollup。

手动 Docker Compose 安装

偏好手工执行 Compose 步骤而非make selfhost：

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

编辑.env，设置JWT_SECRET（必填）：没有它 docker compose 拒绝启动，而生产后端拒绝使用 dev 默认值或任何已知占位符启动。

JWT_SECRET=$(openssl rand -hex 32)

然后启动一切：

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

公网注意：Compose 文件把 8080/3000 只绑定到127.0.0.1（见 docker-compose.selfhost.yml 顶部注释）。不要把绑定改成0.0.0.0——Docker 默认绕过宿主机防火墙（UFW/iptables），原始端口会直接暴露到公网而凭据仍处于弱状态。跨机器或公网访问请用反向代理（Caddy/nginx/Cloudflare Tunnel）终结 TLS 并转发到本地端口。分域名与单域名两种 Caddy 代理拓扑在 apps/docs/content/docs/self-host-quickstart.mdx 中有完整示例（含/ws、/api/daemon/ws、/health等关键路径直连后端的要求）。

手动 CLI 配置

偏好逐步配置而不是multica setup：

# 让 CLI 指向本地服务器 multica config set server_url http://localhost:8080 multica config set app_url http://localhost:3000 # 登录（打开浏览器） multica login # 启动 daemon multica daemon start

生产环境走 TLS：

multica config set app_url https://app.example.com multica config set server_url https://api.example.com multica login multica daemon start

进阶配置入口

环境变量完整清单（含数据库连接池调优、SMTP/Resend 双邮件通道、Google OAuth、注册管控、本地磁盘与 S3/CloudFront 文件存储、Cookie 域、反向代理、Redis 限流与频道租约、各 IM 机器人集成、插件与 GitHub/自建 Git 集成等）、无 Docker 的裸机部署方式、外部 PostgreSQL 接入及数据库扩展要求（pgcrypto与pg_trgm为必需，pg_bigm/pg_cron可选）、反向代理配置等，全部见 SELF_HOSTING_ADVANCED.md。可作为写作参考的快速起手式另有仓库内的 apps/docs/content/docs/self-host-quickstart.mdx（Docker Compose 精简版）。多语言版本同样存在（.zh.mdx、.ja.mdx、.ko.mdx）。

自检清单：部署完成后应当核对的事项

• 服务就绪判断用/readyz而非/health：curl -fsS http://localhost:8080/readyz应返回{"status":"ok","checks":{"db":"ok","migrations":"ok"}}，任一非 ok 即说明新版本未完成迁移。
• daemon 就绪判断用multica daemon status，确认Daemon: running、Agents 非空、Workspaces > 0。
• 公网实例务必检查：未设置MULTICA_DEV_VERIFICATION_CODE；APP_ENV=production；ALLOW_SIGNUP/DISABLE_WORKSPACE_CREATION已按需收紧；反向代理只暴露 80/443。
• 升级类操作遵循「先备份、再 pull、up -d重建、最后/readyz验证」的固定流程；K8s 场景则坚持「改 tag →helm upgrade」的可靠路线，避免IfNotPresent+ 浮动 tag 造成的静默不升级。

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