Collie 故障排查清单:连不上、推送不响、配对失败等 8 类症状的快速解决方案
Collie 故障排查清单:连不上、推送不响、配对失败等 8 类症状的快速解决方案
Collie 是一款自托管 PWA 手机客户端,让你从 iPhone 或 Android 远程控制 Herdr、tmux、zellij 中的 Claude Code、Codex、Pi、OpenCode 等 AI 编码代理,并支持推送通知。日常使用中偶尔会遇到连不上、白屏、推送不响等问题。本文把 docs/troubleshooting.md 中的官方故障排查经验,按 8 类高频症状 整理成一份快速解决方案清单,帮你定位并修复问题。
30 秒速查:8 类症状对照表
| # | 症状 | 快速解法 |
|---|---|---|
| 1 | 手机连不上 / 打不开 URL | 先查 Herdr 服务与 Tailscale 链路 |
| 2 | 服务启动后不响应 | 看日志:多半是端口被占用 |
| 3 | 页面加载但空白(403) | 用 COLLIE_ALLOWED_ORIGINS 放行来源 |
| 4 | 推送通知不响 | collie push-test 定位三叉原因 |
| 5 | 重启后 Collie 消失 | 启用 linger(Linux)或检查 launchd(macOS) |
| 6 | 窗口窄条 / 拒绝开 tmux 窗口 | 终端真窄或 tmux 版本过旧 |
| 7 | 配对失败 / 密码框卡住 | 核对 COLLIE_TRUSTED_USER;用 Type 而不是 Send |
| 8 | 界面过期 / 更新卡 staging | 固定单一 HTTPS 来源,看 build stamp |
建议同时运行一次 collie doctor——它能直接报出 PATH 问题、未上报的 agent session、缺失的 journal 适配器等,是排查第一选择(见 docs/commands.md)。
1️⃣ 症状一:手机连不上、打不开 Collie URL
典型信号:手机上 tailnet URL 一直转圈或加载失败;或者 herdr plugin … 报 Os { code: 2, kind: NotFound };或 start 提示 tailscale serve failed。
排查顺序(由内而外):
- Herdr 服务是否在运行?
herdr plugin命令直接报原始Os { NotFound }说明 CLI 连不上控制 socket(~/.config/herdr/herdr.sock)。先启动 Herdr(herdr server &或打开 Herdr TUI 即可拉起服务端),再用herdr plugin list快速探测。 - Tailscale 链路五连查:手机装有 Tailscale 并已连接到同一 tailnet;你打开的是
bin/collie url输出的 tailnet 地址(http://127.0.0.1:8787只能在主机本机打开);tailnet 已开启 MagicDNS;主机在线(tailscale status);ACL 策略允许该 peer 访问此节点。 - HTTPS 证书问题:
tailscale serve报HTTPS certificates are not enabled on this tailnet时,去 Tailscale 管理控制台开启 "Enable HTTPS";Headscale /.internal域没有证书可开,改用COLLIE_SERVE_MODE=http写入.env后bin/collie restart。
⚠️ 一个隐蔽陷阱:ACL 拦截时
tailscale ping依然成功(disco ping 绕过 ACL),流量是被静默丢弃而非拒绝,手机只会表现为"卡死",极易误判为服务器挂了。横幅(banner)在tailnet行下方会提示 ACL 不通过,看到它就直接去改 ACL 策略。
2️⃣ 症状二:服务起来了但 Collie 不响应
典型信号:横幅显示 ⚠ Collie isn't answering on :8787 yet、连接被拒绝。
服务单元已拉起但 HTTP 服务没应答。按顺序检查:
systemctl --user status collie # 先看单元状态
bin/collie logs # 或 journalctl --user -u collie -f 实时跟踪
最常见原因:端口被占用。在 .env 里设置新的 COLLIE_PORT,再 bin/collie restart(该命令会重新对新端口执行 tailscale serve)。另一类原因是首次构建失败,日志会直接说明,修好后运行 bin/collie build。单元每 5 秒自动重试,原因修好后服务通常自己就能恢复。
3️⃣ 症状三:页面能打开却空白(白屏、403)
典型信号:页面加载成功但一片空白;API 调用失败报 403 cross-origin rejected。
你在用一个 Collie 未预期的 origin 访问——自定义域名,或改写了 Host 头的反向代理。两种解法:
- 在
.env中用COLLIE_ALLOWED_ORIGINS放行确切的公开 origin(写法见 docs/configure.md); - 或者让代理原样转发
Host头——这是 docs/deployment.md 中变体 B(identity-aware proxy)的四条代理要求之一。
安全提醒:Collie 设计上提供远程 shell 能力,URL 等同 root 登录。请固定使用 tailnet 内的 HTTPS 来源,设置 COLLIE_TRUSTED_USER,永远不要使用 tailscale funnel(那会把端口暴露到公网)。详见 docs/security.md。
4️⃣ 症状四:推送通知不响
典型信号:agent 等待输入了,手机却没收到任何推送。
先在主机上手动发一条:
bin/collie push-test
该命令会按顺序区分三种原因:
- 推送显示未启用 —— VAPID 密钥没进到 bridge。运行
collie push-keys生成密钥对(写入.env的COLLIE_VAPID_PUBLIC/COLLIE_VAPID_PRIVATE,权限 600),再collie restart。 - 没有已订阅设备 —— 这台手机从未在 Settings → Alerts 里开启过通知,去开启即可。
- 显示已发送但收不到 —— 手机当前用的是纯 HTTP origin(非安全上下文),Settings 里会标记
insecure。Web Push 必须运行在 HTTPS 来源下。
完整推送设置流程见 docs/voice-and-push.md 的 Web Push 小节。
5️⃣ 症状五:重启后 Collie 消失了
典型信号:主机重启或重新登录后,Collie 服务没了。
-
Linux:几乎都是 lingering 未开启导致的。systemd 用户服务默认随用户会话退出而停止:
loginctl enable-linger $USER更多细节见 docs/upgrading.md 的 "Surviving reboots" 小节。
-
macOS:launchd agent 在用户登录时启动。确认你真的登录了(而不是停在登录窗口),并检查 agent 是否已加载:
launchctl print gui/$(id -u)/herdr.collie。若collie status显示 "loaded, not running",手动拉起:launchctl kickstart gui/$(id -u)/herdr.collie。
6️⃣ 症状六:窗口是窄条 / 终端显示异常
典型信号:全屏应用(如 top、Copilot CLI)被挤成一条;手机新建标签页被拒绝(提示 window-size);日志出现 tmux list: output did not parse。
- 窄条窗口:pane 里的终端真的就这么宽,Collie 是忠实镜像。在 pane 里运行
tput cols可量出真实宽度。Herdr 的 pane 宽度来自分屏网格,且只在有桌面客户端附着时才应用几何变化——没附着时关闭一个分屏,幸存者会卡在旧窄宽,socket 上的pane.zoom/pane.resize也推不动它。修复方式:连接一个 Herdr 客户端,在里面放大(herdr pane zoom <pane-id> --on)或调整大小;或直接关掉该 pane 新建一个。 - 拒绝开 tmux 窗口:tmux 3.7 以下、
window-size为manual时,创建窗口会崩掉整个 tmux 服务器,Collie 主动拒绝并提示。执行它打印的那行修复命令tmux set -g window-size latest,或升级 tmux 3.7+。 output did not parse:个别 tmux 版本(如 3.4)转义分隔符的方式不同,或启动时没有 UTF-8 locale。新版 Collie 已兼容两种形态且强制以-u运行 tmux 命令;仍复现的话,记录tmux -V版本并提 issue。
7️⃣ 症状七:配对失败 / 认证不通过
典型信号:浏览器打开 Collie 只看到配对界面、请求全部被拒;或密码框输入卡住。
- Collie 的设备配对常开:每个设备需要对每一个请求出示 token,未配对的浏览器只能看到配对页。核对
.env里的COLLIE_TRUSTED_USER与你的 tailnet 登录名完全一致(tailscale serve会注入Tailscale-User-Login头,Collie 据此拒绝其他人),并只配对你实际使用的那台物理手机。配对流程详见 docs/security.md。 - 密码 /
sudo/ SSH 口令框收不到你的回复:这是设计行为。Send 会先回读屏幕来校验输入,而密码提示会关闭回显,导致无内容可校验。请改用键盘上方的 Type——它把按键(含 Enter)直接送入 pane,不存储、不回显,识别到密码提示后 Collie 还会顺手丢弃已存的草稿。
8️⃣ 症状八:界面看着像旧的 / 更新卡住
典型信号:rebuild 后手机显示旧 UI;页脚 build stamp 与主机版本不一致;手机上点更新停在 staging。
- stale UI:PWA 的 service worker 按 origin 缓存——你同时用自定义域名和裸
host:8787访问,就等于装了两套,各自缓存。页脚 build stamp(vX.Y.Z · sha · time)显示你实际运行的 bundle;不一致时页脚会出现 "new build — tap to update",点它即可;也可以重开 PWA 几次让 SW 自动更新,或清除该 origin 的站点数据。最佳实践:固定使用一个 HTTPS origin。 - 手机更新卡在 staging(1.6.0 之前):
collie update --status报staging(超 10 分钟变interrupted)、新版本目录存在、runner 日志 0 字节——三者同时出现即为此缺陷。新版已修复交接等待逻辑;已卡住的机器可等 10 分钟让锁自动失效,或按 docs/troubleshooting.md 的步骤核对 pid 后清理~/.local/state/collie/下的update.json、update.lock和update-staging-*.log(正在更新时切勿删除,versions/目录保持原样)。 - macOS 手机更新后 agent 未加载:在 Mac 上运行
collie restart即可重写并加载 plist(1.9.0 起 runner 独立会话启动,已根治)。 - agent 在 New 页置灰:名字后括号里就是原因。"not installed" 说明登录 shell 的
PATH里找不到该命令——在目标机器上跑bash -lc 'command -v claude'验证,装好或修好登录文件里的 PATH 行后重开页面。 - Start 提示 "There is no folder …":不带
/或~前缀的名字按家目录下解释,projects即~/projects;创建该文件夹或从 Recent 里选一个。提示 "could not confirm the start" 只是手机没收到回执,先看 dashboard——pane 很可能已经存在,点 Try again 重发同一请求即可,不会开出第二个 pane。
附:常用诊断命令速记
| 命令 | 作用 |
|---|---|
collie doctor |
全面体检:PATH、agent session、journal 适配器、缓存规则 |
collie push-test |
手动发一条推送,区分推送三叉故障 |
collie push-keys |
生成 VAPID 密钥对写入 .env |
bin/collie url |
输出应打开的 tailnet 地址 |
bin/collie logs |
查看服务日志(等价 journalctl --user -u collie -f) |
collie version / 页脚 build stamp |
确认真正运行的版本 |
💡 遇到读不出的对话框或发送进不了输入框:用
herdr pane list找到 pane id,运行herdr pane read <pane-id> --source recent --lines 200 --format ansi > pane.txt,把脱敏后的pane.txt连同 agent 版本一起提 issue——原始终端文本能揭示截图看不见的颜色与暗色信息。
更多按"搜索词"组织的完整症状列表,见仓库官方文档 docs/troubleshooting.md;所有 CLI 命令的完整说明见 docs/commands.md。
