문제 해결

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

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

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

Chute iOS

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

Chute Mac

• System Proxy는 켜져 있는데 어떤 앱이 이를 무시함 — 많은 도구(특히 터미널 프로그램)는 시스템 프록시를 따르지 않습니다. 해당 도구가 Chute의 리스너를 명시적으로 가리키게 하거나(셸의 경우 메뉴의 Copy Shell Export Command가 이를 해 줍니다), 네트워크 계층에서 트래픽을 가로채는 Enhanced Mode를 사용하세요.
• Enhanced Mode가 시작되지 않음 — 네트워크 확장 프로그램 또는 헬퍼의 승인이 필요합니다; 정확한 시스템 설정 경로, "시스템 확장 프로그램 차단됨" 사례, 오래된 VPN 재설정 방법은 향상 모드 문제 해결을 참조하세요.
• LAN 주소로 향하는 트래픽은 의도적으로 Chute를 우회합니다 — 가로채기가 고장 났다고 단정하기 전에 기타 옵션의 skip-proxy와 tun-excluded-routes를 확인하세요.

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

• 경로를 격리하세요. 정책 그룹을 DIRECT로 전환하세요: 직접 연결로는 페이지가 열리는데 프록시를 거치면 실패한다면 문제는 프록시 서버입니다 — 잘못된 호스트/포트/자격 증명/암호화 방식이거나 서버가 다운된 것입니다. 그룹에 대해 지연 시간 테스트를 실행하세요; 다른 정책은 통과하는데 어떤 정책만 테스트를 결코 통과하지 못한다면 그것이 범인입니다.
• 잘못된 규칙이 일치함. 실시간 트래픽 화면에서 실패하는 연결이 일치한 규칙을 확인한 다음 규칙 평가 순서를 다시 읽어 보세요: 규칙은 두 단계로 평가되므로, 호스트명 기반 요청에서는 뒤에 있는 비 IP 규칙이 앞에 있는 IP 규칙보다 먼저 일치할 수 있습니다. no-resolve와 FINAL의 위치가 흔한 용의자입니다.
• DNS 응답이 이상해 보임. DNS 섹션을 확인하세요: 암호화된 DNS를 사용할 때는 DoH/DoT 서버 자체가 프록시 없이 도달 가능한지 확인하세요; 서버를 변경한 후에는 DNS 캐시를 비우세요(iOS 제어 패널의 스위치, 스크립트의 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에서 복호화는 라이선스가 필요한 기능입니다. 라이선스가 없으면 아무것도 복호화되지 않고 MitM 스위치도 효과가 없습니다 — 라이선스와 활성화를 보십시오.

로그 읽기

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

• 로그 수준을 일시적으로 올리세요: loglevel = verbose (사용 후 되돌리세요 — verbose는 느립니다).
• Chute Mac: 메인 창의 로그 탭. Chute iOS: 세션 로그 화면 — 내비게이션 바의 공유 버튼이 이번 실행의 모든 샤드를 넘겨줍니다. Chute tvOS: 세션 로그 화면, 위쪽의 심각도 필터(전체 / 알림 이상 / 경고 이상 / 치명적)로 리모컨만으로 범위를 좁힐 수 있습니다.
• 모든 플랫폼: 콘솔의 Logs 페이지, 또는 HTTP 제어 API의 GET /api/logs.
• 흥미로운 줄은 경고입니다: 알 수 없는 정책, 거부된 옵션, 해석할 수 없는 규칙은 설정이 로드될 때 모두 경고로 기록됩니다.
• 로그는 몇 MB 단위의 샤드로 나뉩니다. Chute는 한 번의 실행에서 최근 것들만 보관하므로, 가장 새 파일은 이야기의 끝일 뿐 전체가 아닙니다 — 전부 가져가십시오. (Chute Android는 대신 이번 실행의 로그를 메모리에 두며, 디스크에 샤드 파일이 없습니다.)
• macOS에서는 파일 자체가 ~/Chute/Share/<run id>/ 아래에 있습니다 — 파일 위치(macOS)를 보십시오.

진단 번들 보내기

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

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

• Chute iOS: 제어판 → 「로컬 프록시」 섹션의 마지막 행 런타임 진단 번들 — 항상 표시되며 터널이 연결되기 전까지는 회색이고, external-http-controller가 필요 없습니다. 누르면 번들을 만들고 공유 시트를 엽니다
• Chute Android: 제어판 → 런타임 진단 번들, HTTP API 행들 아래 — VPN이 실행되기 전까지는 비활성입니다
• Chute 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 필드가 어느 쪽인지 알려 줍니다.

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

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

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

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