문제 해결

아래의 증상 목록에서 해당하는 항목을 검색하십시오. 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)에 접근할 수 없음을 의미합니다. 단서는 raw 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는 복제하는 대신 분리(detach)되므로 이전 update에는 git pull할 브랜치가 없었습니다. 수정 사항은 복구 대상인 체크아웃 내부에 포함되어 제공되므로, 이를 적용하려면 한 번 다시 설치해야 합니다. "You are not currently on a branch" 오류가 발생하며 실패하는 경우에 세 가지 명령이 있습니다.

start 실행 시 note: tailscale serve failed 메시지를 출력합니다. Collie 자체는 정상 작동 중입니다(127.0.0.1에서 여전히 실행 중). tailnet ingress만 시작되지 않았으며, 터미널의 안내 문구 위에 tailscale 자체 오류가 표시됩니다. 일반적인 원인으로는 사용자가 Tailscale operator가 아니거나(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을(를) 안내합니다. 게시된 항목이 없으며 대기 중인 항목도 없습니다. 관리 콘솔을(를) 열고 "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) local URL이 아닌 배너의 tailnet URL(bin/collie 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을 우회함), 차단된 트래픽은 거부(refused)되지 않고 삭제(dropped)되므로 휴대폰에서는 응답 없이 멈추며 "서버 다운"으로 인식됩니다. ACL 정책(Tailscale의 경우 <https://login.tailscale.com/admin/acls>, Headscale의 경우 정책 파일)에서 이를 수정하십시오. 이 검사는 최선형(best-effort)으로 동작하며 의도적으로 확정하지 않습니다. 이 노드의 필터가 아무것도 허용하지 않을 때만 허용할 때만 알림을 표시하며(이는 다른 장치가 아직 tailnet에 연결되지 않았음을 의미할 수도 있음), 판단할 수 없을 때는 아무 것도 표시하지 않습니다.

페이지가 로드되지만 빈 상태로 유지됩니다. (빈 페이지, 흰색 화면); API 호출이 403 cross-origin rejected 실패합니다. Collie가 예상하지 않은 오리진(커스텀 도메인 또는 Host 헤더를 재작성하는 프록시)을 통해 접근하고 있습니다. COLLIE_ALLOWED_ORIGINS를 사용하여 정확한 공개 오리진을 허용하거나(설정 참조), 프록시가 Host를 변경 없이 전달하도록 설정하십시오(docs/deployment.md의 네 번째 프록시 요구사항).

sudo (또는 SSH 패스프레이즈, 또는 gpg) 프롬프트에 입력이 전달되지 않습니다. Send 대신 Controls 행의 Type을 사용하십시오. Send는 Enter 키를 누르기 전에 화면에서 입력 내용을 다시 읽어 입력한 내용을 확인하는데(#34), 비밀번호 프롬프트는 에코를 끄므로 다시 읽을 내용이 없습니다. 반면 Type는 Enter 키를 포함하여 키 입력을 창으로 직접 전송합니다. Type에 입력한 내용은 저장되거나 임시 저장본(draft)으로 에코되거나 나중에 복원되지 않으며, Collie가 비밀번호 프롬프트를 인식하는 즉시 저장된 임시 저장본도 삭제합니다(#103).

푸시 알림이 도착하지 않습니다. 수동으로 하나를 전송해 보십시오: bin/collie push-test. 명령이 구분하는 순서대로 세 가지 원인이 있습니다. 푸시가 비활성화되어 있다고 표시되는 경우(키가 브리지에 도달하지 않음 - push-keys를 실행하고 재시작하십시오. Web Push 참조), 구독된 장치가 없다고 표시되는 경우(이 휴대폰의 설정 → 알림에서 알림을 활성화하지 않음), 또는 전송되었다고 표시되지만 아무것도 도착하지 않는 경우(휴대폰이 일반 HTTP 오리진에 연결되어 있으며 이는 보안 컨텍스트가 아님 - 설정에 insecure로 표시됨)입니다.

재부팅 후 Collie가 사라집니다. Linux에서는 거의 항상 lingering 문제이므로 loginctl enable-linger $USER을(를) 실행하십시오(재부팅 후에도 유지하기). macOS에서는 launchd 에이전트가 login에서 시작되므로 실제로 로그인되어 있는지(로그인 화면에 머물러 있지 않은지), 에이전트가 로드되었는지 확인하십시오: launchctl print gui/$(id -u)/herdr.collie.

창의 터미널이 좁게 고정되어 내부의 전체 화면 앱이 찌그러짐 (Copilot CLI, top, 미러의 나머지 영역이 비어 있는 동안 띠 형태로 렌더링되는 모든 TUI). 해당 창의 터미널이 실제로 그만큼 좁으며, Collie는 이를 그대로 미러링합니다. Herdr 창의 너비는 탭의 분할 그리드 내 직사각형 영역에 따라 결정되므로, 탭을 공유하는 창은 열(column)을 나누어 갖습니다. Herdr는 창 지오메트리를 데스크톱 클라이언트가 연결되어 있을 때만에만 적용합니다 (herdr#1709). 연결된 클라이언트가 없으면 분할 창을 닫아도 남은 창이 이전의 좁은 너비로 고정되며, 소켓을 통한 pane.zoom 및 pane.resize 작업으로도 변경되지 않습니다. Collie 측에서는 이를 해결할 수 없습니다. 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.6b가 아닌 3.4)은 -F 목록을 출력할 때 이 어댑터가 읽는 구분자를 이스케이프합니다. Collie는 이제 두 형식을 모두 읽으므로, 0개의 행으로 파싱되는 목록은 빈 herd로 저장되는 대신 mux 오류로 보고됩니다. 오류 줄에는 tmux 버전과 확인된 줄 수가 표시됩니다. 이 문제가 계속 발생하면 tmux -V 버전을 기록하고 이슈를 등록하십시오. 수정은 귀하의 .env이(가) 아닌 어댑터에 적용되어야 합니다.

update 이후에도 herdr plugin list에 이전 버전이 표시됩니다. 정상적인 동작입니다. Herdr는 설치 또는 링크 시점에 읽은 매니페스트를 캐시합니다. 현재 실행 중인 항목에 대한 신뢰할 수 있는 기준은 바닥글의 build stamp 또는 bin/collie version입니다. 링크된 클론의 경우 update이(가) 다시 링크되어 자체 복구되며(herdr plugin link "$(pwd)"을(를) 사용하여 강제 실행), Herdr ≥0.8.0에서는 매니페스트를 디스크에서 다시 읽습니다.

재빌드 후 휴대폰에 이전 UI가 표시됩니다. PWA의 service-worker 캐시는 오리진별로 관리되므로 두 개의 오리진(사용자 지정 도메인 및 원시 host:8787)에서 Collie에 접근하면 각각 고유한 번들을 캐시하는 두 개의 설치본이 생성됩니다. 바닥글의 build stamp(vX.Y.Z · sha · time)에는 현재 실행 중인 번들이 표시됩니다. Collie는 X-Collie-Build 헤더 및 /api/config을(를) 통해 제공 중인 항목을 보고합니다. 불일치 시 바닥글에 "새 빌드 — 탭하여 업데이트."이(가) 표시됩니다. 그렇지 않은 경우 PWA를 몇 번 다시 열거나(SW가 자동 업데이트됨) 해당 오리진의 사이트 데이터를 삭제하십시오. 권장 사항: 하나의 HTTPS 오리진을 선택하여 계속 사용하십시오. (일반 HTTP에서는 SW를 등록할 수 없으므로 항상 최신 상태이지만 PWA 기능은 사용할 수 없습니다.)