연결 문제 해결 · Clash 기술 블로그

Clash Verge Rev SSH 개인 키 오류: 서비스 모드 복구

Clash Verge Rev에서 SSH 개인 키 파일을 지정한 뒤 서비스 코어나 TUN이 시작되지 않나요? 최초 경로 오류와 앱 설정 디렉터리, v2.5.10 수정 사항을 확인하세요. 키와 설정은 보존하고 기존 노드로 복구 여부를 검증합니다.

본문 읽기블로그로 돌아가기
  • Clash Verge Rev
  • SSH
  • private-key
  • 서비스 모드
  • v2.5.10
이 글의 목차
글 작성자
Clash 공식
게시일
예상 읽기 시간
약 8분

설정에 SSH 개인 키 파일을 추가한 뒤 서비스 모드나 TUN을 켜면 코어 시작 실패가 표시될 수 있습니다. 먼저 가장 이른 파일 경로 오류를 확인하세요. 모든 시작 실패를 권한 부족으로 판단하면 원인을 놓칠 수 있습니다.

SSH 개인 키 파일을 추가한 뒤 코어가 시작되지 않는 이유

공식 issue #8445에는 Windows 11에서 Clash Verge Rev v2.5.8에 SSH 개인 키 파일을 지정한 뒤 TUN을 켤 수 없었다는 보고가 있습니다. 상대 경로에서는 파일을 찾지 못했고 절대 경로로 바꾸자 SAFE_PATHS 제한에 걸렸습니다. 뒤에 나온 code 1006은 코어가 준비되지 않아 표시된 상위 오류입니다.

공식 v2.5.10에는 서비스 모드의 SSH 개인 키 파일 처리 수정이 포함되어 있습니다. 이 글은 파일을 서비스 코어에 전달하는 문제를 다룹니다. 모든 TUN 오류의 해결을 보장하거나 Windows 보고 한 건을 세 운영체제에서 직접 검증한 결과로 제시하지 않습니다.

최초 오류로 이 글의 적용 여부 확인하기

실제 증상다음 확인 사항
설정에 type: ssh와 파일 형태의 private-key가 있고, 이후 경로 또는 SAFE_PATHS 오류가 발생함파일 위치와 앱의 수정 사항을 계속 확인
code 1006 또는 IPC 준비 안 됨만 표시되고 개인 키 관련 오류가 없음더 이른 코어 로그를 보존한 뒤 실제 원인부터 확인
코어는 시작되지만 SSH 인증 또는 호스트 키 검증에 실패함SSH 자격 증명, 서버, 호스트 키를 확인해야 하며 시작 오류 수정과 구분
설정에서 SSH 개인 키 파일을 사용하지 않음실제 서비스, 네트워크 또는 설정 오류를 기준으로 점검

상대 경로의 기준이 다르면 절대 경로도 해결책이 아닙니다

Mihomo의 private-key에는 개인 키 내용이나 파일 경로를 지정할 수 있습니다. 이 글은 파일 경로만 다룹니다. 경로 오류를 피하려고 전체 개인 키를 구독, 공개 설정 또는 문의용 스크린샷에 붙여 넣지 마세요.

서비스 코어는 별도의 실행 디렉터리를 사용하므로 앱 디렉터리의 상대 경로 파일을 그대로 읽는다고 가정하면 안 됩니다. v2.5.10은 조건에 맞는 로컬 개인 키를 서비스 실행 디렉터리에 임시로 준비하고 서비스에 전달할 설정을 변경합니다. 사용자가 서비스 디렉터리에 파일을 직접 넣을 필요는 없습니다.

이 수정에도 조건이 있습니다. 파일이 실제로 존재해야 하고, 경로를 해석한 뒤의 실제 위치가 앱 실행 설정의 상위 디렉터리 안에 있어야 합니다. 상대 경로는 이 상위 디렉터리를 기준으로 해석합니다. 절대 경로에도 같은 제한이 적용되므로 디스크의 모든 파일을 읽을 수 있다는 뜻은 아닙니다.

최상위 proxies와 proxy-providers의 payload 안에 있는 SSH 항목을 처리합니다. 원격 provider 파일의 모든 노드까지 재귀적으로 검사한다는 보장은 없습니다. 인라인 개인 키, Windows UNC 및 장치 경로도 이번 일반 로컬 파일 임시 준비 처리의 범위에 포함되지 않습니다.

기존 설정과 개인 키를 보존하고 실제 파일 위치 확인하기

현재 Profile, 사용자 지정 덮어쓰기, 기존 프록시 모드와 복원 가능한 외부 사본부터 저장하세요. 개인 키 파일 원본도 별도로 보존해야 합니다. 설정 ZIP만 있다고 외부 SSH 파일까지 포함된 것은 아닙니다. 백업은 직접 관리하는 곳에 두고, 문의할 때는 민감 정보를 제거한 별도 사본을 만드세요.

"설정 → Verge 고급 설정 → 설정 디렉터리 열기"를 선택하세요. 이곳은 앱 설정 디렉터리이자 실행 설정 파일의 상위 디렉터리입니다. profiles 하위 디렉터리를 상대 경로의 기준으로 삼거나 서비스 실행 디렉터리에 파일을 직접 넣지 마세요.

열린 디렉터리 안의 ssh 하위 디렉터리에 신뢰할 수 있는 개인 키 사본을 두고 접근 권한을 제한하세요. 직접 관리하는 Profile이나 지속 적용되는 덮어쓰기 설정에 private-key: 'ssh/id_ed25519'를 지정하되 실제 파일명에 맞추세요. 되돌릴 수 있도록 개인 키 원본은 그대로 보존합니다.

대상이 앱에서 읽을 수 있는 일반 파일이며 디렉터리 밖을 가리키는 심볼릭 링크가 아닌지 확인하세요. 확장자만 바꿔 없는 파일을 대신하지 마세요. 다시 생성되는 실행 YAML을 직접 편집하거나 개인 키를 공개 저장소에 올리지 말고 기존 파일 보호도 해제하지 마세요.

업데이트 전에 기록할 사항

  • 전체 앱 버전, 운영체제, 현재 서비스 모드와 TUN 사용 여부.
  • 실제 실행 설정의 상위 디렉터리, private-key 지정 방식과 파일 위치. 공개 문의에서는 사용자 이름과 민감한 경로를 가리세요.
  • 최초 파일 또는 안전 경로 오류와 이후 코어 시작 오류가 발생한 순서.
  • 기존 설정과 개인 키 원본, 원래 사용 가능했던 노드 및 트래픽 처리 설정.

v2.5.10을 설치해 서비스용 파일을 앱에서 다시 준비하기

수정된 부분은 Clash Verge Rev가 서비스 실행 리소스를 준비하는 앱 코드입니다. Mihomo만 업데이트하거나 구독을 새로 고치거나 TUN을 반복해서 켜고 끄는 것으로는 전체 앱 업데이트를 대신할 수 없습니다. 같은 수정이 포함되었다는 근거가 있는 후속 정식 버전이라면 이 글 때문에 v2.5.10으로 내릴 필요도 없습니다.

참고 자료의 공식 v2.5.10 Release에서 운영체제와 칩 아키텍처, 기존 설치 방식에 맞춰 업데이트하세요. 이번 작업에서는 이 사이트에 보관된 설치 파일을 교체하지 않습니다. 이전 파일을 내려받을 수 있다는 사실이 이 수정까지 적용되었다는 뜻은 아닙니다.

기존 설치 방식으로 업데이트하고 다시 열기

  1. 작업을 저장하고 앱 정상 종료하기

    네트워크 연결을 중단할 수 있을 때 기존 설정을 기록하고, 앱에서 지원하는 방식으로 현재 트래픽 처리를 중지한 뒤 트레이에서 완전히 종료하세요. 설정과 개인 키를 보존하고 데이터 디렉터리를 삭제하거나 서비스 내부 파일을 직접 교체하지 마세요.

  2. 공식 앱 업데이트 완료하기

    운영체제와 아키텍처에 맞는 정식 설치 파일을 사용하고 기존 설치 방식을 유지하세요. 설치나 서명 검사에 실패하면 해당 오류부터 해결해야 합니다. 계속 진행하려고 시스템 보안 검사를 끄지 마세요.

  3. 다시 열고 실제 실행 버전 확인하기

    실제 앱이 v2.5.10 또는 같은 수정이 확인된 후속 정식 버전인지 확인하고 기존 Profile과 지속 적용되는 덮어쓰기 설정이 남아 있는지도 살펴보세요. 경로 변경은 원본 설정에 저장하고 다시 활성화한 뒤 최종 설정의 SSH 항목을 확인합니다.

  4. 원래 필요했던 서비스 코어와 TUN 시작하기

    기존에 필요했던 트래픽 처리 방식을 유지하고 다시 시작한 뒤 가장 이른 로그를 확인하세요. DNS, 노드 자격 증명, 여러 스위치를 한꺼번에 바꾸면 결과를 비교하기 어렵습니다.

코어가 시작되어도 기존 SSH 노드의 실제 통신까지 확인하세요

먼저 코어가 준비되었고 개인 키 경로나 SAFE_PATHS 오류로 종료되지 않는지 확인하세요. 그런 다음 원래 필요했던 SSH 노드를 선택해 새로운 실제 요청을 보내세요. 클라이언트의 "연결" 페이지에서 요청이 예상한 SSH 출구를 거쳤는지 살펴보고 실제 작업도 성공하는지 확인합니다.

코어 시작 성공이 SSH 로그인 성공을 뜻하지는 않습니다. 지연 시간이 표시되거나 TUN 스위치가 켜졌다는 사실만으로 인증, 호스트 키 검증, 실제 트래픽이 모두 정상이라고 판단할 수 없습니다. 이후 인증 오류가 발생하면 SSH 서버와 자격 증명을 계속 점검하고, 검증을 없애려고 host-key를 삭제하지 마세요.

수정 후 확인 목록

  • 실제 앱 버전에 서비스 모드 개인 키 임시 준비 수정이 포함되어 있고 최종 설정이 예상한 SSH 항목을 사용합니다.
  • 개인 키가 허용된 앱 설정 범위 안에 실제로 존재하며 다시 시작한 뒤에도 읽을 수 있습니다.
  • 서비스 코어가 준비 상태에 도달하고 해당 파일 경로 오류로 종료되지 않습니다.
  • 새 연결이 예상한 SSH 노드를 사용하고 실제 요청이 완료되며 기존 작업도 정상 작동합니다.
  • 평소 모드와 기존 선택, 필요한 트래픽 처리 설정으로 복원한 뒤 결과를 다시 확인합니다.

이 사이트는 실제 클라이언트에 설치하거나 해당 문제를 직접 재현하지 않았습니다. 이 글은 공식 사용자 보고, 정식 릴리스, 고정된 버전의 소스 코드와 SSH 설정 문서를 근거로 합니다. 웹사이트의 번역, 소스 수준 검사 또는 브라우저 검사가 사용자 기기에서의 실제 연결 검증을 대신하지는 않습니다.

계속 실패하면 최초 오류에 따라 복원하고 파일 보호 유지하기

private key is unavailable below the config root가 표시됨

실행 설정의 상위 디렉터리, 파일 존재 여부, 해석된 실제 위치와 앱의 읽기 권한을 다시 확인하세요. 디렉터리 밖 파일, 범위를 벗어나는 심볼릭 링크 또는 원격 경로는 이번 자동 준비 처리의 보장 대상이 아닙니다. SAFE_PATHS를 무작정 바꾸지 마세요.

파일 오류는 사라졌지만 code 1006 또는 다른 종료 오류가 남음

새로 발생한 최초 코어 오류와 실제 버전을 보존하고 해당 오류를 기준으로 원인을 찾으세요. 마지막 IPC 오류만 보고 시스템 서비스를 재설치하지 마세요.

업데이트 후 앱이나 기존 설정을 사용할 수 없음

추가 변경을 멈추고 현재 상태를 저장하세요. 먼저 사용 가능하다고 확인된 설정과 노드로 복원하세요. 앱 버전을 되돌려야 한다면 프로젝트에서 지원하는 방식과 그에 맞는 백업을 사용해 새 프로그램과 이전 프로그램이 유일한 데이터 디렉터리를 동시에 사용하지 않도록 하세요.

당장 업그레이드할 수 없다면 사용 가능하다고 확인한 SSH가 아닌 노드나 기존 설정으로 돌아가 작업부터 복구할 수 있습니다. 그렇다고 이전 서비스 모드의 개인 키 문제가 해결된 것은 아닙니다. 제한을 피하려고 디스크 전체의 읽기 권한이나 모든 사용자의 쓰기 권한을 열거나 키를 서비스 디렉터리에 옮기는 방식을 영구 해결책으로 삼지 마세요.

문의할 때는 운영체제, 전체 앱 버전, 서비스 모드, private-key가 파일인지 내용인지, 민감 정보를 제거한 디렉터리 관계와 최초 오류를 제공하세요. 개인 키, 비밀번호, 구독 토큰 또는 전체 설정 묶음은 업로드하지 마세요.

참고 자료