multica：面向多Agent协同的操作系统级部署指南

1. 项目概述：为什么“multica”不是又一个Agent框架，而是一套协同操作系统？

最近两周，我在三个不同行业的客户现场反复被问到同一个问题：“你们说的multica，和Dify、Hermes、Ollama这些到底有什么区别？是不是换个名字的Agent封装？”——这问题问得特别实在。我直接打开本地终端，用docker ps -a | grep multica拉出正在运行的容器列表：一个叫multica-coordinator的主控服务，两个multica-worker-ai（分别挂载了Qwen2.5-7B和DeepSeek-V3模型），一个multica-db-sync做向量与结构化数据双写，还有一个multica-audit-tracer在持续记录所有Agent之间的调用链路、响应耗时、token消耗和决策依据快照。这不是几个独立Agent拼在一起，而是一个有心跳、有调度、有仲裁、有回滚能力的协同体。

multica的核心定位，是解决“多Agent系统中‘人’的缺席”这个根本矛盾。Dify擅长单点任务编排，Hermes强在桌面端交互，Ollama专注本地模型托管——但当业务需要“销售Agent查CRM、法务Agent审合同条款、财务Agent核验付款条件、最后由运营Agent生成执行摘要并同步给钉钉群”，这四个角色之间如何协商优先级？谁来判断“法务审核未完成前，财务不得触发付款”这条规则是否被绕过？谁来发现“销售Agent连续三次把客户投诉误判为普通咨询”并自动降权？这些不是靠Prompt Engineering能解决的，而是需要一套轻量级但具备状态感知、策略仲裁和行为审计能力的协同底座。multica正是为此而生：它不替代任何具体Agent的能力，而是让它们能像真实团队一样分工、对齐、复盘。

关键词“multica”“Agent”“部署教程”“智能协同系统”背后的真实需求，从来不是“怎么装上”，而是“怎么让多个AI角色真正协作起来，而不是各自为战”。我见过太多团队花三个月部署好Dify+Ollama+RAG，结果上线后发现销售Agent和客服Agent对同一客户画像的理解完全割裂，因为没人设计跨Agent的上下文同步机制；也见过用Hermes做桌面助手的团队，每个员工启动一个独立Agent实例，彼此间毫无信息共享，知识沉淀为零。multica的部署过程，本质上是在搭建一套“AI团队的组织架构图”——Coordinator是项目经理，Workers是各职能专家，DB Sync是共享知识库，Audit Tracer是每日站会记录。所以这篇教程不会只告诉你docker-compose up -d，而是带你亲手配置它的“汇报线”“审批流”和“复盘机制”。

适合谁看？如果你正面临以下任一场景，这篇就是为你写的：

• 已经用Dify或LangChain搭出单个Agent，但业务方开始提“能不能让几个Agent一起干活”；
• 技术选型卡在“该用Hermes还是自己写Worker”之间，本质是没想清楚协同逻辑该由谁定义；
• 运维同事盯着满屏Agent日志发愁：“哪个环节出错了？是模型崩了，还是协调逻辑错了？”；
• 产品同学拿着PRD问：“这个需求要调用3个Agent，响应超时怎么算？失败重试策略谁定？”。
  它不假设你精通Kubernetes，但要求你熟悉Docker基本命令；不要求你手写LLM推理代码，但需理解模型服务化的基本形态。接下来的所有步骤，都基于一个原则：先让协同逻辑可观察、可配置、可干预，再谈性能优化。

2. 系统架构与核心组件拆解：Coordinator不是调度器，而是“协同协议栈”

multica的架构设计，明显区别于传统微服务或单体Agent框架。它没有采用“中心化API网关+无状态Worker”的经典模式，而是构建了一个三层协同协议栈：语义层 → 协议层 → 执行层。这个分层不是为了炫技，而是为了解决多Agent系统中最棘手的三个现实问题：异构模型兼容性、动态角色授权、以及跨Agent事务一致性。

2.1 语义层：统一Agent身份与能力契约

所有接入multica的Agent，必须先注册一份agent-spec.yaml，内容类似这样：

name: "sales-assistant-v2" version: "1.3.0" description: "负责客户线索分级、跟进话术生成、商机阶段更新" capabilities: - "query_crm_by_phone" - "generate_followup_script" - "update_opportunity_stage" input_schema: type: "object" properties: phone: { type: "string", pattern: "^1[3-9]\\d{9}$" } context: { type: "string", maxLength: 2000 } output_schema: type: "object" properties: confidence_score: { type: "number", minimum: 0, maximum: 1 } next_action: { type: "string", enum: ["call", "email", "meeting"] } crm_update_payload: { type: "object" }

这个文件不是简单的描述文档，而是multica Coordinator进行能力路由的依据。当用户输入“请跟进昨天咨询的王总”，Coordinator不会直接转发给某个Agent，而是先解析意图，匹配到sales-assistant-v2的generate_followup_script能力，再检查其input_schema是否满足（比如是否提供了phone字段）。如果缺失，就触发预设的fallback_strategy: "request_missing_fields"，自动生成追问：“请问王总的手机号是多少？”。这种基于Schema的契约式交互，彻底规避了传统方案中靠关键词匹配导致的误触发——我亲眼见过某金融客户因Agent把“余额不足”误判为“查询余额”，导致自动触发了错误的还款提醒。

提示：agent-spec.yaml必须通过multica register --file agent-spec.yaml命令注册，而非手动修改数据库。每次注册都会生成唯一agent_id，后续所有调用链路、审计日志、权限控制均以此ID为锚点。这是保证协同可追溯性的第一道防线。

2.2 协议层：Coordinator的核心不是转发，而是仲裁

Coordinator服务的核心逻辑，藏在它的orchestration-policy.json配置中。这不是一个静态路由表，而是一套支持条件分支、超时熔断、权重轮询的动态策略引擎。以一个典型采购审批流程为例：

{ "policy_id": "procurement-approval-v1", "steps": [ { "step_id": "validate-budget", "agent_id": "finance-validator", "timeout_ms": 8000, "retry": { "max_attempts": 2, "backoff_ms": 1000 }, "on_failure": { "action": "abort", "reason": "budget_validation_failed" } }, { "step_id": "check-supplier-risk", "agent_id": "risk-analyzer", "timeout_ms": 12000, "retry": { "max_attempts": 1, "backoff_ms": 2000 }, "on_failure": { "action": "skip", "next_step": "generate-contract" } }, { "step_id": "generate-contract", "agent_id": "legal-draftsman", "timeout_ms": 15000, "retry": { "max_attempts": 3, "backoff_ms": 500 }, "on_failure": { "action": "escalate", "to_agent": "compliance-officer" } } ], "global_timeout_ms": 45000 }

关键点在于on_failure策略：它允许你明确定义“某个Agent失败时，整个流程是终止、跳过、降级还是升级”。这解决了多Agent系统最脆弱的一环——单点故障引发雪崩。实测中，当risk-analyzer因网络抖动超时，系统不会卡死，而是按策略跳过该步骤，继续生成合同，并在审计日志中标记“risk_check_skipped_due_to_timeout”。这种显式声明失败处理逻辑的设计，比任何自动重试机制都更可控。我建议所有新项目从第一天起就编写orchestration-policy.json，哪怕初始版本只有两步，因为后期补策略的成本远高于前期设计。

2.3 执行层：Worker不是裸跑模型，而是带“工牌”的执行单元

multica Worker服务的启动命令，远比ollama run qwen:7b复杂：

docker run -d \ --name multica-worker-sales \ --network multica-net \ -e MULTICA_COORDINATOR_URL=http://coordinator:8000 \ -e MULTICA_AGENT_ID=agent-5f8a2c1d \ -e MULTICA_MODEL_PATH=/models/qwen2.5-7b.Q4_K_M.gguf \ -e MULTICA_CONTEXT_WINDOW=4096 \ -v /path/to/models:/models \ -p 8081:8080 \ multica/worker:latest

注意MULTICA_AGENT_ID环境变量——它不是随机字符串，而是必须与你在Coordinator注册时获得的agent_id严格一致。Worker启动后，会主动向Coordinator发起注册请求，携带自己的agent_id、当前负载（CPU/Mem使用率）、模型版本哈希值、以及支持的capability列表。Coordinator据此构建实时Worker拓扑图，并在调度时考虑负载均衡。例如，当sales-assistant-v2有10个并发请求，而multica-worker-sales负载已达85%，Coordinator会自动将新请求路由至另一台同ID的Worker实例（如果你部署了集群）。

注意：Worker容器必须与Coordinator在同一Docker网络（如multica-net）中，且不能依赖外部DNS。我在测试环境曾因Worker使用host.docker.internal解析Coordinator地址，在生产K8s环境中失效——正确做法是通过--network-alias coordinator固定服务名，所有Worker统一用http://coordinator:8000通信。

3. 部署全流程详解：从单机验证到生产就绪的七步法

部署multica不是一次性的docker-compose up，而是一个渐进式验证过程。我把它拆成七个不可跳过的步骤，每一步都有明确的成功标志和常见陷阱。这套流程已在Ubuntu 22.04、macOS Sonoma和Windows WSL2三种环境下实测通过，所有命令均适配主流Shell（bash/zsh/powershell）。

3.1 步骤一：环境准备与依赖校验（5分钟）

首先确认基础环境。multica对硬件要求不高，但对软件版本有硬性约束：

# 检查Docker版本（必须≥24.0.0） docker --version # 输出应为：Docker version 24.0.7, build afdd53b # 检查Docker Compose版本（必须≥2.20.0） docker compose version # 输出应为：Docker Compose version v2.20.2 # 检查可用内存（Worker需至少4GB空闲内存） free -h | awk '/^Mem:/ {print $7}' # 输出应为：>=4.0G # 创建专用网络（避免端口冲突） docker network create multica-net

最容易被忽略的是SELinux状态。在CentOS/RHEL系系统上，若SELinux处于enforcing模式，Worker容器可能无法挂载模型文件：

# 临时禁用（仅用于验证） sudo setenforce 0 # 永久禁用（生产环境不推荐，改用semanage） sudo sed -i 's/SELINUX=enforcing/SELINUX=permissive/g' /etc/selinux/config

实操心得：不要在root用户下直接运行docker命令。创建docker用户组并把当前用户加入：

sudo groupadd docker sudo usermod -aG docker $USER newgrp docker # 刷新组权限

这能避免后续所有操作都需要sudo，减少权限混乱风险。

3.2 步骤二：Coordinator服务部署（8分钟）

Coordinator是整个系统的“大脑”，必须最先启动。我们使用官方提供的docker-compose.coordinator.yml：

# 下载配置文件（官方镜像已内置最新版） curl -O https://raw.githubusercontent.com/multica-org/multica/main/deploy/docker-compose.coordinator.yml # 启动Coordinator（后台运行） docker compose -f docker-compose.coordinator.yml up -d # 验证是否健康 docker compose -f docker-compose.coordinator.yml logs coordinator | tail -20 # 成功标志：出现 "Coordinator started on http://0.0.0.0:8000" 和 "Health check passed"

此时访问http://localhost:8000/health应返回JSON{"status":"healthy"}。如果返回Connection refused，大概率是端口被占用。multica Coordinator默认监听8000端口，可通过修改docker-compose.coordinator.yml中的ports字段调整：

services: coordinator: ports: - "8080:8000" # 改为8080映射到容器内8000

提示：Coordinator的数据库默认使用SQLite，足够单机验证。但生产环境必须切换为PostgreSQL。切换方法：在docker-compose.coordinator.yml中注释掉sqlite服务，取消postgres服务的注释，并修改coordinator服务的环境变量：

environment: - MULTICA_DB_URL=postgresql://multica:multica@postgres:5432/multica

3.3 步骤三：注册首个Agent（3分钟）

Coordinator启动后，即可注册你的第一个Agent。以销售助手为例，创建sales-spec.yaml：

name: "sales-assistant-demo" version: "1.0.0" description: "演示用销售助手，仅返回固定话术" capabilities: - "generate_followup_script" input_schema: type: "object" properties: phone: { type: "string" } context: { type: "string" } output_schema: type: "object" properties: script: { type: "string" } confidence: { type: "number" }

执行注册：

# 安装multica CLI工具（需Python 3.8+） pip install multica-cli # 注册Agent（输出包含agent_id，务必复制保存！） multica register --file sales-spec.yaml --coordinator http://localhost:8000 # 输出示例：Agent registered successfully. agent_id: agent-9a2b3c4d

注册成功后，访问http://localhost:8000/api/v1/agents可看到该Agent详情。agent_id是后续所有操作的关键凭证，丢失需重新注册。

3.4 步骤四：Worker服务部署与模型加载（12分钟）

Worker需要加载模型文件。multica官方提供两种方式：

• 方式A（推荐新手）：使用预编译的GGUF格式模型（如Qwen2.5-0.5B.Q4_K_M.gguf），体积小、加载快；
• 方式B（高级用户）：自行转换HuggingFace模型为GGUF，需安装llama.cpp工具链。

我们采用方式A，下载轻量模型：

# 创建模型目录 mkdir -p ./models # 下载Qwen2.5-0.5B量化模型（约380MB） curl -L https://huggingface.co/Qwen/Qwen2.5-0.5B-GGUF/resolve/main/qwen2.5-0.5b.Q4_K_M.gguf \ -o ./models/qwen2.5-0.5b.Q4_K_M.gguf # 启动Worker（替换YOUR_AGENT_ID为上一步获取的ID） docker run -d \ --name multica-worker-demo \ --network multica-net \ -e MULTICA_COORDINATOR_URL=http://coordinator:8000 \ -e MULTICA_AGENT_ID=agent-9a2b3c4d \ -e MULTICA_MODEL_PATH=/models/qwen2.5-0.5b.Q4_K_M.gguf \ -e MULTICA_CONTEXT_WINDOW=2048 \ -v $(pwd)/models:/models \ -p 8081:8080 \ multica/worker:latest

等待约30秒，检查Worker日志：

docker logs multica-worker-demo | tail -10 # 成功标志：出现 "Worker registered with agent_id: agent-9a2b3c4d" 和 "Model loaded successfully"

注意：MULTICA_CONTEXT_WINDOW必须小于等于模型实际支持的上下文长度。Qwen2.5-0.5B最大支持2048，若设为4096会导致启动失败。查看模型支持长度的方法：用llama.cpp的llama-cli工具执行llama-cli -m ./models/qwen2.5-0.5b.Q4_K_M.gguf -p "test" --ctx-size 2048，观察是否报错。

3.5 步骤五：定义并激活协同策略（5分钟）

创建demo-policy.json，定义一个极简的两步流程：

{ "policy_id": "demo-simple-v1", "steps": [ { "step_id": "generate-script", "agent_id": "agent-9a2b3c4d", "timeout_ms": 5000, "on_failure": { "action": "abort" } } ], "global_timeout_ms": 10000 }

通过Coordinator API激活策略：

# 使用curl激活（需安装jq解析JSON） curl -X POST http://localhost:8000/api/v1/policies \ -H "Content-Type: application/json" \ -d @demo-policy.json | jq '.' # 成功返回：{"policy_id":"demo-simple-v1","status":"active"}

此时策略已生效，但尚未关联到任何入口。下一步将创建API网关。

3.6 步骤六：API网关与入口配置（7分钟）

multica本身不提供HTTP网关，需额外部署一个轻量级代理。我们使用官方推荐的multica-gateway（基于FastAPI）：

# 下载网关配置 curl -O https://raw.githubusercontent.com/multica-org/multica/main/deploy/docker-compose.gateway.yml # 修改网关配置，指定要暴露的策略 # 编辑 docker-compose.gateway.yml，找到 gateway 服务的 environment，添加： # - MULTICA_POLICY_ID=demo-simple-v1 # - MULTICA_COORDINATOR_URL=http://coordinator:8000 # 启动网关 docker compose -f docker-compose.gateway.yml up -d # 验证网关健康 curl http://localhost:8001/health # 应返回 {"status":"healthy"}

网关启动后，即可通过标准HTTP POST调用协同流程：

curl -X POST http://localhost:8001/v1/execute \ -H "Content-Type: application/json" \ -d '{ "input": { "phone": "13800138000", "context": "客户咨询企业微信私有化部署方案" } }' | jq '.'

成功响应示例：

{ "execution_id": "exec-1a2b3c4d", "status": "completed", "output": { "script": "您好！感谢咨询企业微信私有化部署。我们提供标准版（含基础功能）和旗舰版（支持定制开发）...", "confidence": 0.92 }, "trace_id": "trace-5e6f7g8h" }

trace_id是关键——它关联了Coordinator调度日志、Worker执行日志、审计追踪日志，是问题排查的唯一索引。

3.7 步骤七：审计追踪与监控启用（10分钟）

协同系统的价值，70%体现在可观测性上。multica默认启用审计追踪，但需手动开启Elasticsearch集成以实现全链路检索：

# 启动Elasticsearch（单节点开发模式） docker run -d \ --name multica-es \ --network multica-net \ -p 9200:9200 -p 9300:9300 \ -e "discovery.type=single-node" \ -e "ES_JAVA_OPTS=-Xms512m -Xmx512m" \ -v $(pwd)/es-data:/usr/share/elasticsearch/data \ docker.elastic.co/elasticsearch/elasticsearch:8.12.2 # 等待ES启动（约30秒），然后配置Coordinator连接 # 编辑 docker-compose.coordinator.yml，添加环境变量： # - MULTICA_AUDIT_ES_URL=http://multica-es:9200 # - MULTICA_AUDIT_INDEX_PREFIX=multica_audit_ # 重启Coordinator docker compose -f docker-compose.coordinator.yml down docker compose -f docker-compose.coordinator.yml up -d

此时所有执行记录将自动写入Elasticsearch。你可以用Kibana可视化，或直接用curl查询：

# 查询最近10条审计记录 curl "http://localhost:9200/multica_audit_*/_search?size=10" -H "Content-Type: application/json" -d ' { "query": { "match_all": {} }, "sort": [{ "@timestamp": { "order": "desc" } }] }'

审计日志包含：execution_id、step_id、agent_id、start_time、end_time、status（success/failed/aborted）、input_hash、output_hash、error_message（如有）。这才是真正的“AI团队工作日志”。

4. 核心配置参数详解与避坑指南：那些文档里不会写的细节

multica的配置项看似简单，但每个参数背后都有深意。以下是我在12个生产项目中踩过的坑，以及对应的参数调优逻辑。这些不是“最佳实践”，而是“血泪教训”。

4.1 Coordinator关键参数：别让global_timeout_ms成为背锅侠

global_timeout_ms常被误解为“整个流程最长运行时间”，其实它是Coordinator自身调度超时阈值。当Coordinator在global_timeout_ms内未能完成所有步骤的调度（包括等待Worker响应、序列化输入、写入审计日志等），它会强制终止流程并标记为coordinator_timeout。

问题来了：如果Worker处理一个请求实际需要15秒，但你把global_timeout_ms设为10秒，流程会因Coordinator超时失败，而非Worker超时。此时日志里找不到Worker的任何错误，只有Coordinator的timeout记录，排查方向完全错误。

正确做法：global_timeout_ms应设为所有step.timeout_ms之和 + 5000ms（预留调度开销）。例如三步流程，各步超时为5s/8s/10s，则global_timeout_ms = 5000+8000+10000+5000 = 28000。

实操心得：在orchestration-policy.json中，永远为每个step显式设置timeout_ms，不要依赖全局默认值。我见过某电商客户因未设timeout_ms，导致促销活动期间Worker积压，Coordinator无限等待，最终拖垮整个订单系统。

4.2 Worker模型加载参数：MULTICA_CONTEXT_WINDOW不是越大越好

MULTICA_CONTEXT_WINDOW参数控制Worker加载模型时分配的KV Cache大小。很多人认为“设大点更保险”，结果导致Worker启动失败或OOM。

真相是：KV Cache内存占用 ≈context_window × hidden_size × 2 × sizeof(float16)。以Qwen2.5-7B为例，hidden_size=3584，若设context_window=8192，仅KV Cache就需约1.1GB内存（8192×3584×2×2 bytes），加上模型权重（约4.2GB），总内存需求超5.3GB。而Worker容器默认内存限制为4GB，必然失败。

安全公式：MAX_CONTEXT_WINDOW ≈ (Available_RAM - Model_Size) / (Hidden_Size × 2 × 2)。对于4GB内存Worker，Qwen2.5-7B模型（4.2GB）根本无法加载——必须换用0.5B模型或升级硬件。

提示：用docker stats multica-worker-demo实时监控Worker内存使用。若MEM USAGE持续接近LIMIT，立即降低MULTICA_CONTEXT_WINDOW。我通常保留20%内存余量作为安全缓冲。

4.3 Agent能力契约：input_schema的pattern校验是防错第一道门

很多团队把input_schema当成可选文档，结果线上出现大量phone字段为空的请求，Worker因无法处理而崩溃。pattern正则校验是Coordinator在请求进入Worker前的拦截器。

但要注意：JSON Schema的pattern只支持ECMAScript正则语法，不支持PCRE扩展。例如，想校验手机号，不能用\d{11}（\d在部分JSON Schema实现中不被识别），必须写为^[0-9]{11}$。

更关键的是，pattern校验发生在Coordinator层，失败时返回HTTP 400，附带详细错误信息：

{ "error": "Input validation failed", "details": [ { "field": "phone", "message": "does not match pattern '^[0-9]{11}$'" } ] }

这比Worker内部抛异常友好得多——前端可直接提取field和message展示给用户，无需解析晦涩的stack trace。

注意：maxLength和minLength对字符串字段同样重要。曾有客户因未设maxLength，用户提交了10MB的PDF Base64文本，直接撑爆Worker内存。现在我的规范是：所有string类型必设maxLength: 5000（约5KB文本）。

4.4 审计追踪配置：MULTICA_AUDIT_LEVEL决定日志颗粒度

MULTICA_AUDIT_LEVEL环境变量有三个值：minimal、standard、verbose。默认standard，记录execution_id、step_id、status、duration。但生产环境强烈建议设为verbose，它会额外记录：

• input_hash和output_hash：SHA256哈希值，用于检测相同输入是否产生不同输出（模型漂移预警）；
• worker_id：精确到容器ID，当同一agent_id部署多个Worker时，可定位具体实例；
• model_version_hash：模型文件的SHA256，确保审计日志与实际运行模型版本绑定。

代价是日志体积增大3-5倍，但换来的是可回溯性。某金融客户曾因监管审查，需证明“2024年Q3所有贷款审批结果均由V2.1.0模型生成”，verbose模式下的model_version_hash成了唯一证据。

提示：Elasticsearch索引需提前规划。multica_audit_*索引按天滚动（如multica_audit_2024-06-01），并在docker-compose.coordinator.yml中配置：

environment: - MULTICA_AUDIT_ES_ROLLOVER_DAYS=7 - MULTICA_AUDIT_ES_RETENTION_DAYS=90

4.5 网络与安全配置：--network multica-net不是可选项

multica所有组件（Coordinator、Worker、Gateway、ES）必须部署在同一Docker网络，原因有三：

1. 服务发现：Worker通过coordinator服务名连接Coordinator，而非IP。若不在同一网络，DNS解析失败；
2. 性能隔离：multica-net使用bridge驱动，流量不经过宿主机iptables，延迟降低30%-50%；
3. 安全边界：所有内部通信走multica-net，对外仅暴露Gateway的8001端口，符合最小权限原则。

曾有客户为“方便调试”，让Worker直连宿主机localhost:8000，结果在K8s迁移时全部失效——因为localhost在容器内指向自身，而非宿主机。

正确做法：始终用docker network create multica-net创建专用网络，并在所有docker run或docker compose命令中显式指定--network multica-net。不要依赖默认bridge网络。

5. 常见问题与实战排查技巧：从“Connection refused”到“Agent not found”的全链路诊断

部署multica最耗时的环节，往往不是安装，而是诊断。我把高频问题按发生位置归类，给出可直接执行的排查命令和根因分析。这些不是理论，而是我在凌晨三点救火时的真实记录。

5.1 Coordinator层问题：当/health返回503

现象：curl http://localhost:8000/health返回{"status":"unhealthy"}或直接Connection refused。

排查路径：

1. 检查容器状态：

   docker ps -a | grep coordinator # 若状态为Exited，查看日志 docker logs multica-coordinator | tail -50

2. 常见根因与修复：

   • 数据库初始化失败：日志出现sqlite3.OperationalError: unable to open database file。原因是挂载的SQLite文件路径不存在。修复：mkdir -p ./data && chmod 777 ./data，然后在docker-compose.coordinator.yml中确保volumes指向./data:/app/data。
   • 端口冲突：日志出现Address already in use。用lsof -i :8000查占用进程，kill -9 <PID>释放端口。
   • 配置文件语法错误：orchestration-policy.json有非法逗号或引号。用jq . < policy.json验证JSON格式。

实操心得：Coordinator启动时会执行/app/scripts/wait-for-db.sh脚本，等待数据库就绪。若该脚本超时（默认30秒），Coordinator会退出。可在docker-compose.coordinator.yml中增加超时：

environment: - WAIT_FOR_DB_TIMEOUT=120

5.2 Worker层问题：“Worker registered but no logs”

现象：docker logs multica-worker-demo显示Worker registered...，但后续无任何日志，curl调用无响应。

排查路径：

1. 确认Worker是否真在multica-net中：

   docker inspect multica-worker-demo | grep NetworkMode # 应输出 "NetworkMode": "multica-net"

2. 检查Worker能否连通Coordinator：

   docker exec -it multica-worker-demo curl -v http://coordinator:8000/health # 若返回`Failed to connect`，说明网络不通

3. 常见根因与修复：

   • 服务名解析失败：coordinator服务名在multica-net中未注册。检查docker-compose.coordinator.yml中services.coordinator.networks是否包含multica-net。
   • Coordinator未就绪：Worker启动时Coordinator还未完全启动。Worker有重试机制（默认每5秒重试），但若Coordinator长期不可用，Worker会停止重试。解决方案：先docker compose -f coordinator.yml up -d，等待curl http://localhost:8000/health返回healthy，再启动Worker。
   • MULTICA_AGENT_ID不匹配：Worker的agent_id与Coordinator注册的ID不一致。用docker logs multica-coordinator | grep "registered agent"确认注册ID，确保Worker环境变量完全一致。

5.3 策略执行问题：“Execution timeout but Worker is healthy”

现象：调用/v1/execute返回{"status":"timeout"}，但Worker日志显示Model loaded successfully，且docker stats显示CPU/内存正常。

排查路径：

1. 检查Coordinator调度日志：

   docker logs multica-coordinator | grep "exec-.*timeout" # 查找具体execution_id

2. 检查对应Worker日志：

   docker logs multica-worker-demo | grep "exec-1a2b3c4d" # 若无输出，说明请求根本没到达Worker

3. 常见根因与修复：

   • 策略未激活：orchestration-policy.json已上传，但未调用POST /api/v1/policies激活。用curl http://localhost:8000/api/v1/policies确认status为active。
   • Agent能力不匹配：请求的input字段不满足input_schema，Coordinator在路由前就拒绝了。检查Coordinator日志中input validation failed错误。
   • Gateway配置错误：MULTICA_POLICY_ID环境变量在Gateway中拼写错误（如demo-simple-v1写成demo-simple-v1多了一个空格）。用docker inspect multica-gateway | grep POLICY_ID确认。

提示：启用Coordinator调试日志，临时添加环境变量- MULTICA_LOG_LEVEL=debug，可看到详细的路由决策过程，如Routing input to agent-9a2b3c4d based on capability generate_followup_script。

5.4 审计追踪问题：“Elasticsearch index not created”

现象：curl http://localhost:9200/_cat/indices?v不显示multica_audit_*索引，审计日志丢失。

排查路径：

1. 检查Coordinator是否连接ES：

   docker logs multica-coordinator | grep "audit.*connected" # 应出现 "Connected to Elasticsearch at http://multica-es:9200"

2. 检查ES健康状态：

   curl http://localhost:9200/_cluster/health?pretty # `status`应为`green`或`yellow`