问题排查

以下按顺序列出各种现象，可在页面中搜索你遇到的情况。来自 herdr plugin 的 Os { NotFound } · update 提示 "not currently on a branch" · tailscale serve failed · 无响应（服务无法启动） · 手机无法打开 URL · 页面已加载但内容为空（空白页面，403） · 密码提示不接受输入 · 没有推送通知 · 重启后失效 · 窗格卡在较窄宽度 · Collie 拒绝打开 tmux 窗口 · tmux list: output did not parse · herdr plugin list 显示旧版本 · 重新构建后 UI 未更新。

herdr plugin … 失败并显示 Error: Os { code: 2, kind: NotFound, message: "No such file or directory" }（插件安装失败，操作调用失败）。 这不是 Collie 的问题；这表示 Herdr 服务器未运行，因此其 CLI 无法连接控制套接字（~/.config/herdr/herdr.sock）。迹象是 原始 Os {…} 错误：可访问的服务器会返回结构化 JSON 来响应路径/清单问题（例如 plugin_manifest_not_found），因此纯粹的 Os { NotFound } 表示套接字连接失败，发生在检查 Collie 或你的路径之前。它会影响 link、install、action invoke 等所有与服务器通信的子命令，而 herdr plugin --help 仍可正常工作（它从不打开套接字）。解决方法：先启动 Herdr（运行 herdr server &，或直接启动 Herdr TUI，它会启动服务器），确认 ls ~/.config/herdr/herdr.sock 现已存在，然后重试安装。herdr plugin list 是一个快速检测手段：如果它抛出相同的错误，说明服务器已停止运行。

update 失败并显示 You are not currently on a branch。 在 0.23.1（#63）之前完成的 GitHub 安装；herdr plugin install 执行了分离而非克隆，因此旧的 update 没有可供 git pull 的分支。修复代码包含在它所修复的代码检出中，因此需要重新安装一次才能生效：如果升级失败并提示 "You are not currently on a branch" 包含这三条命令。

start 打印 note: tailscale serve failed。 Collie 本身正常（仍在 127.0.0.1 上运行），仅 tailnet 入口未启动，tailscale 自身的错误信息显示在提示上方的终端中。常见原因：你的用户不是 Tailscale 操作员（sudo tailscale set --operator=$USER）、节点已登出（tailscale up），或者在 Headscale / .internal tailnet 域名上没有可用的 HTTPS 证书（这正是 COLLIE_SERVE_MODE=http 的用途）：在 .env 中设置它，然后运行 bin/collie restart。使用 tailscale serve status 进行验证。

serve 显示 HTTPS certificates are not enabled on this tailnet。 未发布任何内容，也没有正在等待的内容。打开 admin console，开启“Enable HTTPS”，然后再次运行 collie serve。在 Headscale / .internal 域名上没有可启用的证书；请改用 COLLIE_SERVE_MODE=http。

横幅显示 ⚠ 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 秒自动重启一次，因此原因修复后通常会自行恢复。

手机无法打开 tailnet URL。 按顺序排查：(1) 手机运行 Tailscale 应用且已连接到与主机相同的 tailnet；(2) 你打开的是横幅中的 tailnet URL（bin/collie url），而非 local URL（http://127.0.0.1:8787 仅在主机本地有效）；(3) tailnet 的 DNS 设置中启用了 MagicDNS（该 URL 为 MagicDNS 名称）；(4) 主机处于在线状态；在主机上检查 tailscale status，或从手机的 Tailscale 应用 ping 主机；(5) 你的 tailnet 策略确实允许对等节点连接到此节点；如果没有，横幅现在会在 tailnet 行下方注明，其他方式均无法体现：前台入口已正确发布，证书有效，且在主机本地执行 curl 返回 200，因为回环流量从不经过数据包过滤器。有两点极易造成误导：tailscale ping 成功（disco ping 会绕过 ACL），且被拦截的流量是被直接丢弃而非拒绝，因此手机端只会一直挂起并表现为“服务器不可用”。在 ACL 策略中修复此问题（Tailscale 在 <https://login.tailscale.com/admin/acls>；Headscale 则为你的策略文件）。此项检查基于尽力而为原则，并且故意保持保守：仅当该节点的过滤器允许接入 无内容 时才会提示（这也可能意味着尚未有其他设备加入 tailnet），无法确定时则保持静默。

页面已加载但保持空白（空白页面，白屏）；API 调用失败 403 cross-origin rejected。 你正在通过不受信任的来源访问 Collie：自定义域名，或重写了 Host 的代理。使用 COLLIE_ALLOWED_ORIGINS 允许确切的公共来源（参见 配置），或让代理原样转发 Host，即 docs/deployment.md 中的第四个代理要求。

sudo（或 SSH 密码短语，或 gpg）提示不接受你的输入。 使用控制行中的 键入，而非 Send。Send 会在按下 Enter 之前通过从屏幕回读来验证其输入的内容（#34），而密码提示会关闭回显，因此无法回读任何内容；键入 会将按键直接发送至面板，包括 Enter。在 键入 中输入的任何内容都不会被存储、回显到草稿中或在稍后恢复，Collie 一旦识别到密码提示，就会立即丢弃已存储的草稿（#103）。

未收到推送通知。 手动触发一次：bin/collie push-test。有三个原因，命令按以下顺序区分它们：push 显示已禁用（密钥从未到达网桥；运行 push-keys 并重启，参见 Web Push）；显示没有订阅的设备（此手机从未在“设置 → 通知”中启用它们）；或者报告已发送但未收到任何内容（手机处于纯 HTTP 来源上，这并非安全上下文；“设置”会将其标记为 insecure）。

重启后 Collie 消失。 在 Linux 上这几乎总是 lingering 导致的，因此运行 loginctl enable-linger $USER（在系统重启后保持运行）。在 macOS 上，launchd agent 在 login 启动，因此请检查你是否实际已登录（而不是停留在登录窗口）并且 agent 已加载：launchctl print gui/$(id -u)/herdr.collie。

窗格的终端卡在较窄宽度，且其中的全屏应用被挤压（Copilot CLI、top，以及任何只渲染成一条、镜像其余部分留白的 TUI）。 该窗格的终端本身就只有这么宽，Collie 只是如实镜像它。Herdr 窗格的宽度取决于它在标签页分割网格中的矩形区域，因此共享标签页的窗格只会分到一部分列宽。Herdr 仅在连接了桌面客户端时应用窗格尺寸（herdr#1709）：在未连接任何客户端的情况下，关闭某个分屏后，剩余窗格仍会卡在原本的窄宽度，通过 socket 发送 pane.zoom 和 pane.resize 也无法调整它。Collie 无法在自身这一侧修复此问题；它完全不写入窗格尺寸数据（ADR 0031：手机仅在点击 Show in terminal 时调整操作终端）。此现象与具体应用无关：在 54 列的窗格中运行 top 效果完全一样。若要测量实际尺寸，可在窗格中运行 tput cols。这是真实宽度，可能与 herdr pane layout 报告的值不一致。若要修复，连接一个 Herdr 客户端并在其中缩放或调整窗格大小（一旦有客户端连接，herdr pane zoom <pane-id> --on 就会调整终端尺寸），或者关闭该窗格并重新打开一个（#167）。

Collie 拒绝打开 tmux 窗口（手机的 new tab 返回拒绝，并指明 window-size）。 这不是请求本身的错误：在低于 3.7 的 tmux 版本中，当服务器的 window-size 为 manual 时生成窗口会导致整个服务器崩溃（tmux #4849，已在 3.7 中修复），而崩溃的服务器会带走所有窗口。Collie 会直接拒绝，并指出检测到的 tmux 版本。解决方法是其打印的那行命令（在该服务器上运行 tmux set -g window-size latest），或者升级到 tmux 3.7。其他内容不受影响：这些窗格上的所有其他操作继续正常工作（环境要求 带有相同的注意事项）。

Collie 记录 tmux list: output did not parse 且仪表盘显示为空。 这不是崩溃：某些 tmux 版本（如 3.4，而非 3.6b）在输出 -F 列表时会转义该适配器读取的分隔符。Collie 现在能读取这两种格式，因此解析为零行的列表会被报告为 mux 错误，而不会被存储为空 herd；错误信息中会指出 tmux 版本及其看到的行数。如果仍然遇到此问题，请记录 tmux -V 版本并提交 issue；修复应该在适配器中进行，而不是在你的 .env 中。

update 后 herdr plugin list 仍显示旧版本。 符合预期：Herdr 会缓存其在安装或链接时读取的清单。实际运行版本的判定依据是页脚 build stamp 或 bin/collie version。对于链接的克隆，update 会重新链接并自动恢复（使用 herdr plugin link "$(pwd)" 强制执行）；在 Herdr ≥0.8.0 上，清单无论如何都会从磁盘重新读取。

重新构建后手机显示陈旧的 UI。 PWA 的 service-worker 缓存是按 origin 划分的，因此通过两个 origin 访问 Collie（自定义域名 和 原始 host:8787）会生成两个安装实例，各自缓存其对应的 bundle。页脚 build stamp (vX.Y.Z · sha · time) 显示你当前运行的 bundle；Collie 通过 X-Collie-Build 头和 /api/config 报告其提供的版本。若不匹配，页脚会提示 "new build — tap to update." 否则可以多重新打开几次 PWA（SW 会自动更新）或清除该 origin 的网站数据。最佳实践：选定一个 HTTPS origin 并始终使用它。（在纯 HTTP 下 SW 无法注册，虽然始终保持最新，但无法使用 PWA 功能。）