503错误表明后端模型服务集群不可用，需依次验证端点连通性、集群健康状态、MCP协议兼容性及资源限制。具体操作包括探测API健康接口、检查Pod/容器状态与日志、核对协议版本与认证凭证、调整并发策略并监控资源指标。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在WorkBuddy中调用自定义模型时收到“503 Service Temporarily Unavailable”错误，表明请求已抵达网关层，但后端模型服务集群未能正常响应。该错误通常指向服务端资源不可用、过载或健康检查失败，而非客户端配置问题。以下是排查与恢复服务可用性的具体操作：
一、验证模型服务端点连通性与基础响应
该步骤用于确认自定义模型HTTP端点是否可被WorkBuddy网络环境访问，排除DNS解析失败、防火墙拦截或服务进程未启动等基础故障。
1、打开WorkBuddy主界面，点击右上角头像 → 【设置】→ 【高级】→ 【模型调试】
2、在「自定义模型测试」区域，粘贴您配置的模型API地址（如http://localhost:8080/v1/chat/completions）
3、点击【发送健康探测请求】，观察返回状态码与响应体；若返回非200状态或超时，说明端点本身异常
4、若本地部署，请在终端执行：curl -I http://localhost:8080/health 或 telnet localhost 8080 验证服务进程存活与端口监听状态
二、检查模型服务集群健康检查结果
WorkBuddy依赖MCP协议向模型服务发起/health或/.well-known/readyz探针，若集群未通过健康检查，网关将主动拒绝路由流量，直接返回503。
1、登录模型服务所在服务器，执行：kubectl get pods -n model-serving（K8s环境）或 docker ps --filter "name=model-api" --format "{{.Status}}"（Docker环境）
2、确认Pod/容器状态为Running且就绪（Ready列显示1/1或N/N），若出现CrashLoopBackOff、Error或0/1，则服务未通过就绪探针
3、查看对应Pod日志：kubectl logs -n model-serving <pod-name> --tail=50，重点搜索"health check failed"、"OOMKilled"或"bind: address already in use"
4、若使用Nginx或Traefik作为反向代理，请检查其上游服务健康状态页（如http://nginx-host/status 或 http://traefik-host/dashboard/#/http/services）
使用 draw.io（.drawio 格式）和 SVG 生成兼容 Microsoft Visio 的架构图。当用户需要以下任一场景时触发： - 用于 Visio 或技术文档的架构/系统/网络图 - 带连接标注的分层控制系统图 - 将 draw.io XML 转换为稳定、可嵌入的 SVG - 修复 Visio 或 draw.io 无法打开的故障排查类图表 - 任何需专业级布局且文本可编辑的图表
三、校验MCP协议版本兼容性与认证凭证有效性
503错误可能由MCP客户端（WorkBuddy）与模型服务端对协议字段解析不一致引发，尤其当服务端强制要求v1.2+协议但WorkBuddy仍以v1.1模式发起请求时，部分网关会返回503而非400。
1、进入WorkBuddy【设置】→ 【高级】→ 【协议配置】，确认「MCP协议版本」与模型服务文档声明的版本严格一致
2、在模型服务配置文件（如config.yaml或.env）中核对MCP_AUTH_REQUIRED: true是否启用；若启用，需确保WorkBuddy中已填入正确的MCP_API_KEY
3、临时禁用模型服务端认证中间件（如FastAPI的BearerAuthMiddleware），再次调用测试；若503消失，则问题锁定在密钥分发或签名逻辑
4、使用Postman构造标准MCP v1.2请求头：X-MCP-Version: 1.2、Authorization: Bearer <valid-key>，直连模型端点验证
四、排查资源限制与过载熔断机制
模型服务集群常配置CPU/内存限制及并发请求数熔断策略，当WorkBuddy高频调用触发限流阈值时，网关或服务自身会返回503而非429，造成误判。
1、检查模型服务部署配置中的resource limits：确认limits.memory不低于2Gi、limits.cpu不低于1000m（单副本场景）
2、在WorkBuddy中降低技能调用频率：进入【设置】→ 【模型】→ 【调用策略】，将「最大并发请求数」从默认5降至2，观察503是否缓解
3、登录模型服务监控面板（如Prometheus + Grafana），查看model_serving_http_requests_total{code=~"503"}指标突增时段，并关联container_memory_usage_bytes与process_cpu_seconds_total确认是否达上限
4、若使用K8s HPA，检查kubectl get hpa -n model-serving输出，确认扩缩容条件（如cpuUtilization > 70%）是否持续触发但副本未增加——可能因节点资源不足导致扩容失败
