문제 해결

어떤 문제든 먼저 두 가지 질문으로 나누세요: 트래픽이 Chute에 도달하기는 하는가(가로채기 문제), 그리고 Chute가 그것을 전달할 수 있는가(전달 문제)? 실시간 트래픽 화면이 이에 답해 줍니다 — 대시보드(iOS) 또는 메인 창의 트래픽 탭(Mac)을 열고 웹을 탐색해 보세요: 아무것도 나타나지 않으면 Chute가 트래픽을 받지 못하는 것이고, 연결이 나타나지만 실패한다면 Chute가 이를 전달하지 못하는 것입니다. 두 경우의 해결 방법은 완전히 다릅니다.

이 페이지는 "안 된다"를 위한 것입니다. 질문이 "무엇을 하고 있나" — 요청 읽기, 본문 보관, 응답 바꾸기, 장애 흉내 내기 — 라면 대신 네트워크 디버깅에서 시작하세요.

아무것도 나타나지 않음: 가로채기 문제

Chute iOS

• 스위치가 켜지기를 거부하고 구성 바가 흔들림 — 선택된 구성이 없습니다. 구성 바를 탭하고, 구성을 탭해 체크 표시가 나타나게 한 다음 완료를 탭하세요("먼저 구성을 선택해 주세요").
• VPN 권한 대화 상자를 거부함 — 스위치를 다시 켜고 승인하세요. VPN 프로파일이 꼬였다면(스위치가 즉시 원위치로 돌아감) 앱 설정의 VPN 구성 재설정을 사용하세요; 다음 시작 시 프로파일이 다시 생성되고 권한을 다시 요청합니다.
• 다른 VPN 앱이 연결되어 있음 — iOS는 한 번에 하나의 VPN 터널만 실행합니다. 다른 앱의 연결을 해제하세요(또는 터널을 소리 없이 다시 가로챌 수 있는 해당 앱의 온디맨드 규칙을 비활성화하세요).

Chute Mac

• 시스템 프록시는 켜져 있는데 어떤 앱이 이를 무시함 — 많은 도구(특히 터미널 프로그램)는 시스템 프록시를 따르지 않습니다. 해당 도구가 Chute의 리스너를 명시적으로 가리키게 하거나(셸의 경우 메뉴의 셸 export 명령 복사가 이를 해 줍니다), 네트워크 계층에서 트래픽을 가로채는 향상 모드를 사용하세요.
• 시스템 프록시나 향상 모드가 켜지지 않음 — 둘 다 Chute의 권한 있는 도우미에 의존합니다. 도우미를 처음 설치할 때는 Chute가 이유를 설명한 뒤(Chute에 도우미가 필요합니다) 승인을 요청합니다. macOS 13 이상에서는 시스템 설정 → 일반 → 로그인 항목 및 확장 프로그램에서 허용해야 할 수도 있으며, Chute는 승인 필요 또는 로그인 항목에서 Chute 허용으로 이를 알려 줍니다. 도우미는 앱이 기대하는 버전(현재 0.8.6)이어야 합니다: 버전이 다르면 자동으로 다시 설치되므로, Chute를 업데이트한 뒤에는 그 요청을 승인하세요.
• 향상 모드가 시작되지 않음 — PacketTunnel 유형에서는 네트워크 확장 프로그램의 승인도 필요합니다; 정확한 시스템 설정 경로, "시스템 확장 프로그램 차단됨" 사례, 오래된 VPN 재설정 방법은 향상 모드 문제 해결을 참조하세요.
• LAN 주소로 향하는 트래픽은 의도적으로 Chute를 우회합니다 — 가로채기가 고장 났다고 단정하기 전에 기타 옵션의 skip-proxy를 확인하세요. 여기서 tun-excluded-routes는 답이 아닙니다: 이 키는 Chute iOS, Chute tvOS, Chute Android의 터널만 읽으며 macOS에서는 아무 일도 하지 않습니다. Mac에서 LAN 대역을 향상 모드로 끌어들이려면 tun-included-routes에 적으세요. 두 향상 모드 유형 모두 이를 따릅니다.

연결은 나타나지만 실패함: 전달 문제

• 경로를 격리하세요. 정책 그룹을 DIRECT로 전환하세요: 직접 연결로는 페이지가 열리는데 프록시를 거치면 실패한다면 문제는 프록시 서버입니다 — 잘못된 호스트/포트/자격 증명/암호화 방식이거나 서버가 다운된 것입니다. 그룹에 대해 지연 시간 테스트를 실행하세요; 다른 정책은 통과하는데 어떤 정책만 테스트를 결코 통과하지 못한다면 그것이 범인입니다.
• 잘못된 규칙이 일치함. 실시간 트래픽 화면에서 실패하는 연결이 일치한 규칙을 확인한 다음 규칙 평가 순서를 다시 읽어 보세요: 규칙은 두 단계로 평가되므로, 호스트명 기반 요청에서는 뒤에 있는 비 IP 규칙이 앞에 있는 IP 규칙보다 먼저 일치할 수 있습니다. no-resolve와 FINAL의 위치가 흔한 용의자입니다.
• DNS 응답이 이상해 보임. DNS 섹션을 확인하세요: 암호화된 DNS를 사용할 때는 DoH/DoT 서버 자체가 프록시 없이 도달 가능한지 확인하세요; 서버를 변경한 후에는 DNS 캐시를 비우세요(iOS 제어판의 DNS 캐시 삭제 행, 스크립트의 flushDNS, 또는 HTTP 제어 API의 DELETE /api/dns/cache).
• UDP에 의존하는 앱이 오작동함 — 선택된 정책이 UDP 릴레이를 지원하는지 확인하고(프록시 서버의 기능 매트릭스 참조), Tailscale은 ICMP를 전달하지 않는다는 점을 기억하세요 — 출구 노드를 통한 ping은 아무 응답이 없습니다.

HTTPS 복호화가 복호화하지 않음

• CA는 설치되고 신뢰까지 되어야 합니다 — iOS에서는 두 개의 별도 단계이며, 두 번째 단계(설정 → 일반 → 정보 → 인증서 신뢰 설정)가 모두가 놓치는 부분입니다. CA 인증서 설치 및 신뢰를 참조하세요.
• 호스트가 [MITM]의 hostname 목록과 일치해야 합니다 — 선언된 호스트만 복호화되며, :port/:0 접미사가 달리 지정하지 않는 한 포트 443에서만 복호화됩니다.
• 일부 앱은 자체 인증서를 고정(pin)하여 복호화되는 동안 실패합니다 — 맞서 싸우기보다 - 접두사로 해당 호스트를 제외하세요.
• QUIC/HTTP-3은 복호화할 수 없습니다 — 호환되는 클라이언트를 TCP로 되돌리는 방법은 block-quic을 참조하세요.
• iPhone과 Apple TV, Android에서 복호화는 라이선스가 필요한 기능입니다. 라이선스가 없으면 구성이나 제어 API가 무엇을 요구하든 아무것도 복호화되지 않습니다 — 라이선스와 활성화를 보세요. iPhone에서 그 스위치는 제어판의 MitM 행입니다. Apple TV에는 MitM 행 자체가 없으므로, 거기서는 프로필 [MITM]의 enable = true로 켜거나 실행 중에 웹 콘솔이나 Chute Dashboard, PUT /api/features/mitm으로 켭니다.

로그 읽기

위 섹션들로 해결되지 않을 때는 보통 로그가 해결해 줍니다:

• 로그 수준을 일시적으로 올리세요: loglevel = verbose (사용 후 되돌리세요 — verbose는 느립니다).
• Chute Mac: 메인 창의 로그 탭. Chute iOS: 세션 로그 화면 — 내비게이션 바의 공유 버튼이 이번 실행의 모든 샤드를 넘겨줍니다. Chute tvOS: 세션 로그 화면, 위쪽의 심각도 필터(전체 / 알림 이상 / 경고 이상 / 치명적)로 리모컨만으로 범위를 좁힐 수 있습니다. Chute Android: 여기서는 엔진의 로그가 파일로 기록되지 않습니다 — 콘솔의 Logs 페이지(다음 항목)에서 읽거나, 런타임 진단 번들로 가져가거나, adb logcat으로 따라가며 보세요. 대시보드의 로그 탭과 세션 목록에서 세션의 로그 탭은 앱 자신의 서비스 로그(시작, 중지, 네트워크 변경)만 보여 주며, 설정의 로컬 로그 정리가 그것을 비웁니다.
• 모든 플랫폼: 콘솔의 Logs 페이지, 또는 HTTP 제어 API의 GET /api/logs.
• 흥미로운 줄은 경고입니다: 알 수 없는 정책, 거부된 옵션, 해석할 수 없는 규칙은 구성이 로드될 때 모두 경고로 기록됩니다.
• 로그는 몇 MB 단위의 샤드로 나뉩니다. Chute는 한 번의 실행에서 최근 것들만 보관하므로, 가장 새 파일은 이야기의 끝일 뿐 전체가 아닙니다 — 전부 가져가세요. (Chute Android는 샤드로 나누지 않습니다: 엔진 자신의 로그는 메모리 링에 머물고, 앱은 자체 서비스 로그를 하나의 logs/runtime.log에 덧붙이며 sessions/<run id>/ 아래에 실행별 사본을 남깁니다. 둘 다 앱의 비공개 저장소 안에 있습니다.)
• macOS에서는 파일 자체가 ~/Chute/Share/<run id>/ 아래에 있습니다 — 파일 위치(macOS)를 보세요.

진단 번들 보내기

다른 사람이 봐야 할 때는, 공유 시트에서 찾아낸 파일 여섯 개와 기억에 의존한 오류 설명보다 아카이브 하나가 낫습니다. 앱은 두 종류를 구분합니다. 실행 중인 엔진이 만드는 런타임 진단 번들과 앱 혼자서 만드는 오프라인 진단 번들입니다. 둘 다 비밀번호와 토큰, 쿠키, URL 안의 자격 증명은 <redacted>로 바뀌며, 요청과 응답 본문은 포함되지 않습니다.

런타임 진단 번들 — 실행 중인 엔진이 만듭니다. 민감 정보를 지운 구성 사본, 엔진 상태 스냅샷(이전 실행이 어떻게 끝났는지 포함), 이번 실행의 주요 사건, 로드된 규칙과 정책, DNS, 트래픽, 그리고 로그 끝부분(Android에서는 엔진 자체가 파일을 쓰지 않으므로 엔진의 메모리 내 로그 링)이 들어 있습니다. 터널이 실행 중이어야 합니다.

• Chute iOS: 제어판 → "로컬 프록시" 섹션의 마지막 행 런타임 진단 번들 — 항상 표시되며 터널이 연결되기 전까지는 회색이고, external-http-controller가 필요 없습니다. 누르면 번들을 만들고 공유 시트를 엽니다
• Chute Android: 제어판 → 런타임 진단 번들, HTTP API 행들 아래 — VPN이 실행되기 전까지는 비활성입니다
• Chute Mac: 메뉴 막대 → 진단 번들 저장… — 엔진이 앱 안에서 실행되므로 번들은 그 자리에서 만들어지며, 엔진이 실행 중이든 멈춰 있든 동작합니다. 언제나 런타임 종류이고, Mac은 오프라인 번들을 만들지 않습니다
• Chute tvOS: 이 기기에는 공유 시트도 파일 브라우저도 없으니 콘솔의 Download diagnostic bundle(진단 번들 다운로드)이 유일한 방법입니다 — 앱의 QR 코드를 스캔해 메일을 보낼 수 있는 기기에서 Diagnostics 페이지를 여세요
• 모든 플랫폼, 콘솔에서: Diagnostics 페이지의 다운로드 버튼, 또는 POST /api/diagnostics/bundle

오프라인 진단 번들 — 엔진 없이 앱이 만들므로 터널이 끊겼거나 한 번도 시작되지 않았을 때도 동작합니다. 앱의 호스트 보고서(버전, 기기, VPN 상태, 구성 요약, 그리고 텍스트로 옮긴 "네트워크 / 프록시 / 라우트 테이블" 진단 페이지), 이전 실행의 종료 마커(엔진이 실제로 실행 중이면 "running"으로 보고됨), 그리고 앱이 접근할 수 있는 로그 파일이 들어 있습니다.

• Chute iOS: 설정 → "진단" 섹션 → 오프라인 진단 번들
• Chute Android: 설정 → "진단" 섹션 → 오프라인 진단 번들 저장
• Chute tvOS: 설정 → 오프라인 진단 번들 — Apple TV가 번들을 만들고 QR 코드를 표시합니다. 같은 네트워크의 휴대전화로 스캔하면(또는 컴퓨터에서 표시된 주소를 열면) zip을 내려받을 수 있습니다 — 이 링크는 그 화면이 열려 있는 동안에만 유효합니다
• Chute Mac: 여기에는 오프라인 번들이 없고, 필요하지도 않습니다 — 메뉴 막대의 진단 번들 저장…은 엔진이 멈춰 있어도 런타임 종류를 만들어 마지막 종료 기록과 로그 끝부분, 구성을 담아 줍니다. 그것이 모으는 재료는 바로 첨부할 수 있는 평범한 파일들입니다. ~/Chute/Share/<run id>/ 아래의 로그 샤드와 실행 마커 ~/Chute/Share/last-run.json — 파일 위치(macOS)를 보세요

둘 다 만드는 플랫폼에서는 파일 이름이 어느 쪽인지 알려 줍니다. 런타임 번들은 diagnostics-<timestamp>.zip, 오프라인 번들은 diagnostics-offline-<timestamp>.zip이며, 둘 다 manifest.json을 담고 있고 그 kind 필드가 어느 쪽인지 알려 줍니다. Chute Mac에서 저장한 번들은 언제나 런타임 종류이므로 이름에 offline-이 붙는 일이 없습니다.

보내기 전에 콘솔 Diagnostics 페이지의 이전 종료 줄을 읽어 볼 만합니다. 메모리 부족으로 종료됨(Killed for memory)은 Chute가 실패한 것이 아니라 시스템이 회수했다는 뜻이며, 다음에 무엇을 봐야 할지가 달라집니다.

재작성이 아무 일도 하지 않는 이유는?

한 번도 일치하지 않은 재작성 규칙에는 증상이 없습니다. 아무 일도 일어나지 않는데, 그것은 "일치했지만 눈에 띄는 변화가 없었다"와 똑같아 보입니다. 콘솔이 이에 직접 답합니다: Rules(규칙) 페이지는 이번 실행에서 적용된 모든 재작성/모의 응답 규칙과 횟수를 보여 줍니다. 이 표는 서로 다른 규칙을 최대 512개까지 추적하며, 그 이상은 추적되지 않은 채 실행된 규칙 수를 보고하고(API의 rewrite_hit_dropped_rules) 그때부터는 일부만 보여 주는 표가 됩니다.

• 그 목록에 없는 규칙은 한 번도 일치한 적이 없습니다 — 그 표가 추적되지 않은 규칙을 보고하고 있지 않은 한 그렇습니다. URL 재작성의 URL 형태에 비추어 패턴을 확인하세요. 헤더 재작성을 포함한 모든 재작성 계열은 URL의 어느 위치에서든 패턴과 일치합니다.
• 일치했는데 변화가 보이지 않는다면 다른 문제입니다 — 콘솔에서 해당 연결을 펼쳐 적용된 재작성 줄을 읽으세요. 규칙이 자신의 문장으로 지목됩니다.
• 해당 호스트에 HTTPS 복호화가 켜져 있을 때에만 규칙이 HTTPS 트래픽을 볼 수 있습니다.