mirror of
https://github.com/multica-ai/multica.git
synced 2026-07-29 06:28:23 +02:00
6ef711cd35
* fix: gate dev verification code behind explicit env * docs: fold dev verification code into env table * docs: clarify fixed verification code opt-in --------- Co-authored-by: Eve <eve@multica.ai>
169 lines
8.4 KiB
Plaintext
169 lines
8.4 KiB
Plaintext
---
|
||
title: 故障排查
|
||
description: self-host Multica 遇到的 Top 7 常见问题——症状、原因、怎么查、怎么修。
|
||
---
|
||
|
||
import { Callout } from "fumadocs-ui/components/callout";
|
||
|
||
按症状查问题。每条问题都给**症状 / 可能原因 / 怎么查 / 怎么修**四段。如果你的情况不在下面，到 [GitHub](https://github.com/multica-ai/multica/issues) 提 issue。
|
||
|
||
## 守护进程连不上服务器
|
||
|
||
**症状**：[`multica daemon`](/cli) 的 `status` 命令显示 `offline` 或 `connection refused`；服务器日志里没有 `/api/daemon/register` 或 `/api/daemon/heartbeat` 的请求。守护进程机制详见 [守护进程与运行时](/daemon-runtimes)。
|
||
|
||
**可能原因**：
|
||
|
||
1. **`MULTICA_SERVER_URL` 指错地址** —— 默认是 `ws://localhost:8080/ws`，self-host 要改成你自己的 server 地址
|
||
2. **网络 / 防火墙阻挡** —— daemon 和 server 不在同一网络，或出站被 block
|
||
3. **Token 过期或无效** —— 你从来没跑过 `multica login`，或 PAT 被撤销
|
||
4. **服务器拒绝注册** —— 你登录的账号不在目标工作区（register 返 403）
|
||
5. **DNS 解析失败** —— hostname 在 daemon 机器上解不出来
|
||
|
||
**怎么查**：
|
||
|
||
```bash
|
||
multica daemon logs --lines 100 # 看 daemon 侧错误
|
||
echo $MULTICA_SERVER_URL # 确认地址配对
|
||
curl -i http://<server-host>:8080/health # 直接戳 server
|
||
curl -i http://<server-host>:8080/readyz # 连同 DB + migration readiness 一起检查
|
||
cat ~/.multica/config.json # 看 api_token 是否存在
|
||
multica workspace list # 确认你是目标工作区成员
|
||
```
|
||
|
||
**怎么修**：按上面原因对症处理。最常见的两个是**改 `MULTICA_SERVER_URL` 重启 daemon**（`multica daemon restart`）和**重新登录**（`multica logout && multica login`）。
|
||
|
||
## 任务一直卡在 queued
|
||
|
||
**症状**：把 issue 分给 agent 后，issue 状态立刻变 `in_progress`，但过了很久页面没有 agent 执行的迹象；`multica daemon status` 显示 daemon `online`。
|
||
|
||
**可能原因**（按触发概率排）：
|
||
|
||
1. **智能体并发上限已满** —— 该 agent 的 `max_concurrent_tasks`（默认 6）已经被其他正在跑的任务占满
|
||
2. **同一 issue 上有另一个同 agent 的任务还没结束** —— 同 agent × 同 issue 强制串行（防止重复执行）
|
||
3. **智能体已经被 archive** —— 被归档后新任务仍能入队，但无法被 claim，会卡到 5 分钟超时（code-issue G-01）
|
||
4. **Daemon 没在当前工作区注册该 runtime** —— 重启 daemon 或在 UI 重新选一次 runtime
|
||
5. **守护进程失联** —— 最近 45 秒没心跳。`daemon status` 看起来 `online` 也可能是刚失联
|
||
|
||
**怎么查**：
|
||
|
||
```bash
|
||
multica daemon status --output json # runtime 列表 + last_seen_at
|
||
multica agent list # 查 agent 的 archived 状态
|
||
multica issue show <issue-id> # 看 task 历史
|
||
```
|
||
|
||
服务器侧（self-host）可以 grep `"no_tasks"` / `"no_capacity"` 看 claim 的结果。
|
||
|
||
**怎么修**：
|
||
|
||
- 并发打满 → 等现有任务跑完，或 `multica agent update <id> --max-concurrent-tasks 10` 提升上限
|
||
- 同 issue 串行 → 等前一个任务结束，或改分给不同 agent
|
||
- Agent 被 archive → `multica agent restore <id>`
|
||
- Runtime 未注册 → `multica daemon restart`，daemon 会重新注册
|
||
|
||
## WebSocket 连不上
|
||
|
||
**症状**：浏览器控制台报 `WebSocket is closed`；页面不显示实时更新（任务进度、评论、inbox），刷新才能看到；但后台任务仍在执行。
|
||
|
||
**可能原因**：
|
||
|
||
1. **Origin 校验失败** —— 你的前端域名不在 server 的 CORS 白名单里。默认白名单只包含 `localhost:3000/5173/5174`，self-host 到公网必须配 `FRONTEND_ORIGIN`
|
||
2. **协议不匹配** —— 前端用 `https://` 需要 `wss://`，HTTP 用 `ws://`
|
||
3. **反向代理没开 WebSocket upgrade** —— Nginx / Envoy / HAProxy 默认不转发 `Upgrade` header
|
||
4. **JWT cookie 过期或丢失** —— 30 天过期后没重登
|
||
|
||
**怎么查**：
|
||
|
||
- 浏览器 DevTools → Network → 筛选 "WS"，看连接状态和状态码
|
||
- Server 日志里 grep `"rejected origin"` / `"websocket"` —— 如果是 origin 问题会明确写出来
|
||
- `curl -i http://<server-host>:8080/ws` 应该返回 `101 Switching Protocols`（需要带 `Upgrade` header）
|
||
|
||
**怎么修**：
|
||
|
||
- Origin 错 → 在 server 的 `.env` 设 `FRONTEND_ORIGIN=https://multica.yourdomain.com`（或逗号分隔的 `CORS_ALLOWED_ORIGINS`），重启 server
|
||
- 协议不匹配 → 确保 `FRONTEND_ORIGIN` 的协议和前端一致
|
||
- 反向代理 → 在 Nginx 加 `proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade";`
|
||
- Cookie 过期 → 刷新页面重新登录
|
||
|
||
## 邮件没收到
|
||
|
||
**症状**：登录或邀请时提交邮箱后，收件箱（和垃圾邮件）里都没有验证码邮件。
|
||
|
||
**可能原因**：
|
||
|
||
1. **`RESEND_API_KEY` 没配** —— server 会静默回落，**把验证码打到自己的 stdout 里**，不报错。生产部署很容易踩
|
||
2. **Resend API key 无效 / 余额不足** —— server 日志会有 `"failed to send verification code"`
|
||
3. **`RESEND_FROM_EMAIL` 的域名没在 Resend 验证** —— Resend 会拒发
|
||
4. **邮件发出去了但被收件人 ISP 判垃圾** —— 查 Resend dashboard 和 spam 目录
|
||
|
||
**怎么查**：
|
||
|
||
- Server 日志里搜 `"[DEV] Verification code for"` —— 如果有，说明 Resend 没配，验证码被打到 stdout
|
||
- [Resend dashboard](https://resend.com/) → Emails 看发送记录
|
||
- 确认 `RESEND_FROM_EMAIL` 的域名在 Resend console 的 "Verified Domains" 列表里
|
||
|
||
**怎么修**：
|
||
|
||
- 没配 API key → 照 [登录与注册配置 → 怎么配 Email](/auth-setup#email--验证码登录怎么工作) 的步骤配完重启 server
|
||
- 域名没验证 → Resend console 里走 DNS 验证流程（加 SPF / DKIM 记录）
|
||
- 紧急情况下（如内部测试）→ 从 server 日志里抄 `[DEV]` 打印出的验证码
|
||
|
||
## 固定本地测试验证码登不进去
|
||
|
||
**症状**：自部署实例，想用 `888888` 这类固定本地测试验证码登录，但被拒 `invalid or expired code`。
|
||
|
||
**可能原因**（互斥）：
|
||
|
||
1. **`MULTICA_DEV_VERIFICATION_CODE` 为空** —— 固定验证码默认关闭
|
||
2. **`APP_ENV=production`** —— 这是正确的生产配置；固定本地测试验证码在 production 中会被忽略
|
||
3. **配置的验证码不是 6 位数字** —— 这个快捷码只接受 6 位数字
|
||
|
||
**怎么查**：
|
||
|
||
```bash
|
||
cat .env | grep -E 'APP_ENV|MULTICA_DEV_VERIFICATION_CODE'
|
||
docker exec <container> env | grep -E 'APP_ENV|MULTICA_DEV_VERIFICATION_CODE'
|
||
```
|
||
|
||
检查邮箱（含 spam）看有没有收到真实验证码。
|
||
|
||
**怎么修**：
|
||
|
||
- 生产环境保持 `MULTICA_DEV_VERIFICATION_CODE` 为空，配好 Resend 后使用真实验证码
|
||
- 本地开发或内网测试可以从 server 日志抄生成的验证码；如果需要 `888888`，设置 `APP_ENV=development` 和 `MULTICA_DEV_VERIFICATION_CODE=888888`。不要在公网实例启用固定验证码（详见 [登录与注册配置 → 固定本地测试验证码](/auth-setup#固定本地测试验证码)）
|
||
|
||
## 端口冲突
|
||
|
||
**症状**：`multica server` 或 `multica daemon start` 启动失败，报 `address already in use`。
|
||
|
||
**可能原因**：
|
||
|
||
1. **Server 端口被占用**（默认 `8080`）
|
||
2. **Daemon health 端口被占用**（默认 `19514`，每个 profile 偏移一个 hash 值）
|
||
3. **Web dev server 端口冲突**（`3000` / `5173`）
|
||
4. **端口权限不足**（绑 `< 1024` 的 privileged port 需要 sudo）
|
||
|
||
**怎么查**：
|
||
|
||
```bash
|
||
lsof -i :8080 # macOS / Linux
|
||
netstat -ano | findstr :8080 # Windows
|
||
```
|
||
|
||
**怎么修**：
|
||
|
||
- 杀占用进程（`kill -9 <PID>`），或改环境变量 `PORT=9000` 换端口
|
||
- 要用 80 / 443 → 别直接绑，用反向代理（Nginx / Caddy）转发到高位端口
|
||
|
||
## 在哪看日志
|
||
|
||
| 组件 | 位置 | 命令 |
|
||
|---|---|---|
|
||
| **守护进程** | `~/.multica/daemon.log`（后台模式）或前台 stdout | `multica daemon logs -f --lines 100` |
|
||
| **服务器（Docker）** | container stdout | `docker logs -f <container>` |
|
||
| **服务器（systemd）** | journal | `journalctl -u multica-server -f` |
|
||
| **前端（dev）** | `pnpm dev` 所在终端 | 直接看 |
|
||
| **前端（browser）** | DevTools → Console | 按 `F12` |
|
||
|
||
需要更详细的 daemon 日志，把它从后台挪到前台跑：`multica daemon stop && multica daemon start --foreground`。
|