故障排查

按症状查问题。每条问题都给症状 / 可能原因 / 怎么查 / 怎么修四段。如果你的情况不在下面，到 GitHub 提 issue，或联系支持。

守护进程连不上服务器

症状：aacworkflow daemon 的 status 命令显示 offline 或 connection refused；AACWorkflow Cloud 上也看不到这个 runtime 的最近活动。守护进程机制详见 守护进程与运行时。

可能原因：

1. AACWORKFLOW_SERVER_URL 指错地址 —— 应该保持不设置，或者和默认值 wss://api.aacworkflow.com/ws 一致
2. 网络 / 防火墙阻挡 —— 你机器上的出站 WebSocket 流量被挡了
3. Token 过期或无效 —— 你从来没跑过 aacworkflow login，或 PAT 被撤销
4. 不是目标工作区的成员 —— 你登录的账号不在你想注册 daemon 的那个工作区（register 返 403）
5. DNS 解析失败 —— api.aacworkflow.com 在 daemon 机器上解不出来

怎么查：

aacworkflow daemon logs --lines 100    # 看 daemon 侧错误
echo $AACWORKFLOW_SERVER_URL          # 如果你设过，确认地址对不对
cat ~/.aacworkflow/config.json        # 看 api_token 是否存在
aacworkflow workspace list            # 确认你是目标工作区成员

怎么修：按上面原因对症处理。最常见的两个是清掉自定义的 AACWORKFLOW_SERVER_URL 后重启 daemon（aacworkflow daemon restart）和重新登录（aacworkflow logout && aacworkflow login）。

任务一直卡在 queued

症状：把 issue 分给 agent 后，issue 状态立刻变 in_progress，但过了很久页面没有 agent 执行的迹象；aacworkflow daemon status 显示 daemon online。

可能原因（按触发概率排）：

1. 智能体并发上限已满 —— 该 agent 的 max_concurrent_tasks（默认 6）已经被其他正在跑的任务占满
2. 同一 issue 上有另一个同 agent 的任务还没结束 —— 同 agent × 同 issue 强制串行（防止重复执行）
3. 智能体已经被 archive —— 被归档后新任务仍能入队，但无法被 claim，会卡到 5 分钟超时
4. Daemon 没在当前工作区注册该 runtime —— 重启 daemon 或在 UI 重新选一次 runtime
5. 守护进程失联 —— 最近 45 秒没心跳。daemon status 看起来 online 也可能是刚失联

怎么查：

aacworkflow daemon status --output json       # runtime 列表 + last_seen_at
aacworkflow agent list                         # 查 agent 的 archived 状态
aacworkflow issue show <issue-id>             # 看 task 历史

怎么修：

• 并发打满 → 等现有任务跑完，或 aacworkflow agent update <id> --max-concurrent-tasks 10 提升上限
• 同 issue 串行 → 等前一个任务结束，或改分给不同 agent
• Agent 被 archive → aacworkflow agent restore <id>
• Runtime 未注册 → aacworkflow daemon restart，daemon 会重新注册

WebSocket 连不上

症状：浏览器控制台报 WebSocket is closed；页面不显示实时更新（任务进度、评论、inbox），刷新才能看到；但 agent 任务仍在后台执行。

可能原因：

1. 公司代理或防火墙挡了 WebSocket upgrade —— 有些网络放行普通 HTTPS，但会剥掉 Upgrade header
2. JWT cookie 过期或丢失 —— 30 天过期后没重登
3. 浏览器扩展干扰 —— 部分隐私 / 广告拦截扩展会选择性拦截 wss:// 连接

怎么查：

• 浏览器 DevTools → Network → 筛选 "WS"，看连接状态和状态码
• 换一个网络试试（比如手机热点），排除是不是公司代理的问题

怎么修：

• Cookie 过期 → 刷新页面重新登录
• 代理 / 防火墙拦截 → 换个网络，或者请网络管理员放行 wss://api.aacworkflow.com
• 还是不行 → 带上 DevTools Network 面板的截图联系支持

邮件没收到

症状：登录或接受邀请时提交邮箱后，收件箱和垃圾邮件里都没有验证码。

可能原因：

1. 投递延迟 —— 偶尔要等到一分钟左右
2. 垃圾邮件 / 促销邮件文件夹 —— 验证邮件有时会被分类进去
3. 公司邮件过滤 —— 部分企业邮件网关会隔离自动发送的邮件
4. 邮箱地址打错了 —— 检查一下登录页面里输入的内容

怎么修：

• 等一分钟，再看看垃圾邮件 / 促销文件夹
• 点登录页面上的重新发送验证码
• 如果你所在的组织会过滤收件，请 IT 把 noreply@aacworkflow.com 加入白名单
• 等了几分钟还没收到 → 联系支持

端口冲突（守护进程）

症状：aacworkflow daemon start 启动失败，报 address already in use。

可能原因：

1. Daemon health 端口被占用（默认 19514，每个 profile 偏移一个 hash 值）
2. 另一个 daemon profile 已经占用了同一个端口

怎么查：

lsof -i :19514        # macOS / Linux
netstat -ano | findstr :19514    # Windows

怎么修：结束冲突的进程，或者用不同的 profile 跑多个 daemon（aacworkflow daemon start --profile <name>）——每个 profile 会自动选一个不同的 health 端口。

在哪看日志

后台模式下 daemon.log 会按大小轮转（默认 20MB × 5 份 gzip 备份；可用 AACWORKFLOW_DAEMON_LOG_MAX_SIZE_MB / _MAX_BACKUPS / _MAX_AGE_DAYS 调整），所以文件不会大到打不开。

需要更详细的 daemon 日志，把它从后台挪到前台跑：aacworkflow daemon stop && aacworkflow daemon start --foreground。前台运行会把日志实时打到终端，而不是写入轮转文件。