Linux 배포 예상 읽기 시간 14분

Linux에 Clash 배포하기: 데스크톱 클라이언트, mihomo CLI 및 서비스 자동 시작

데스크톱 환경부터 헤드리스 서버까지 설정 디렉터리, 실행 명령, systemd 서비스와 터미널 프록시 변수를 정리합니다.

먼저 배포 방식을 정하세요: 데스크톱, 명령줄 또는 상시 실행 서비스

Linux에서 Clash 배포는 보통 한 가지 방식으로 끝나지 않습니다. GNOME, KDE, Xfce 같은 데스크톱 환경을 사용하는 개인용 PC라면 그래픽 인터페이스를 제공하는 클라이언트가 적합합니다. 원격 서버, 개발 컨테이너 호스트 또는 SSH로만 관리하는 장비라면 mihomo 커널을 직접 실행하는 편이 낫습니다. 부팅 시 자동으로 시작해 로컬 프록시 포트를 장시간 제공해야 한다면 명령줄 실행에 systemd 서비스를 추가하는 것이 좋습니다.

mihomo는 현재 지속적으로 유지 관리되는 Clash Meta 커널의 이름입니다. YAML 설정을 읽고 프록시 연결을 수립하며, 규칙을 매칭하고 HTTP, SOCKS 또는 mixed 포트를 수신 대기합니다. 그래픽 클라이언트는 일반적으로 그 위에서 구독 관리, 노드 전환, 로그 확인, 시스템 프록시 전환 기능을 제공합니다. 즉 데스크톱 클라이언트는 조작 환경을 담당하고, 커널은 실제 트래픽 처리를 담당합니다. 연결에 문제가 생기면 화면에 표시된 상태, 설정 내용, 커널 실행 상태 중 무엇이 원인인지 구분해 확인해야 합니다.

사용 환경 권장 방식 주요 관리 수단
Linux 데스크톱 일상 사용 그래픽 클라이언트 트레이 메뉴, 클라이언트 설정 및 로그 페이지
헤드리스 서버 mihomo 명령줄 SSH, 설정 파일 및 실행 로그
장시간 실행하는 워크스테이션 또는 서버 mihomo와 systemd systemctl 및 journalctl
더 많은 애플리케이션 트래픽을 가로채야 하는 경우 TUN 모드 설정 파일, 라우팅 및 권한 설정

배포 전에 프로세서 아키텍처도 확인해야 합니다. 일반적인 개인용 PC와 클라우드 서버는 대개 amd64를 사용하며, 일부 개발 보드와 라우터 장비, ARM 클라우드 호스트는 arm64를 사용합니다. uname -m을 실행하면 시스템이 보고하는 값을 확인할 수 있습니다. x86_64는 amd64에, aarch64는 arm64에 해당합니다. 잘못된 아키텍처의 바이너리를 다운로드하면 Shell에서 실행할 수 없거나 형식이 잘못되었다는 오류가 표시되는 경우가 많습니다.

Linux 데스크톱 클라이언트: 설치 패키지, 설정 디렉터리 및 프록시 전환

데스크톱 환경에서는 계속 유지 관리되고 mihomo를 명확히 지원하는 그래픽 클라이언트를 우선 선택할 수 있습니다. 일반적인 배포 형식으로는 AppImage, Debian 계열의 .deb, Fedora와 openSUSE 등에서 사용하는 .rpm이 있습니다. 형식은 배포판의 패키지 관리 방식에 맞춰 선택하면 되며, 클라이언트 때문에 시스템 소프트웨어 저장소를 바꿀 필요는 없습니다.

AppImage 실행 방법

AppImage는 보통 단일 파일로 배포되며, 다운로드한 뒤 실행 권한을 추가해야 합니다. 아래 명령은 파일이 현재 디렉터리에 있다고 가정합니다. 실제로 실행할 때는 다운로드한 파일의 정확한 이름을 사용하세요.

chmod +x Clash-Linux.AppImage
./Clash-Linux.AppImage

더블 클릭해도 창이 나타나지 않으면 터미널에서 한 번 실행해 출력 내용을 확인하세요. 최신 배포판에는 AppImage에 필요한 FUSE 호환 구성 요소가 없을 수 있고, 데스크톱 샌드박스, 디스플레이 서버 또는 권한 설정 때문에 실행이 차단될 수도 있습니다. 터미널 출력은 데스크톱에 표시되는 짧은 안내보다 원인을 찾는 데 더 유용한 경우가 많습니다.

deb 및 rpm 설치

Debian, Ubuntu 및 파생 시스템에서는 패키지 관리자를 사용해 로컬 deb 파일을 설치할 수 있으며, 의존성 처리는 시스템에 맡길 수 있습니다.

sudo apt install ./clash-client-linux-amd64.deb

Fedora에서는 다음 명령을 사용할 수 있습니다.

sudo dnf install ./clash-client-linux-x86_64.rpm

설치가 끝나면 애플리케이션 메뉴에서 클라이언트를 실행하세요. 처음 실행할 때는 보통 세 가지 작업이 필요합니다. 구독 또는 YAML 설정을 가져오고, 정책 그룹에서 사용할 수 있는 노드를 선택한 다음, 시스템 프록시를 켭니다. 시스템 프록시를 켜도 데스크톱 프록시 설정을 따르는 애플리케이션에만 적용됩니다. 일부 터미널 프로그램, 컨테이너, 게임 및 자체 네트워크 스택을 구현한 소프트웨어는 이 설정을 자동으로 읽지 않습니다.

그래픽 클라이언트의 설정 디렉터리는 프로젝트마다 다르지만, 일반적으로 ~/.config/ 아래의 애플리케이션 전용 디렉터리나 ~/.local/share/ 아래의 데이터 디렉터리를 사용합니다. 클라이언트가 실행 중일 때 데이터베이스나 관리되는 설정을 직접 덮어쓰지 마세요. 마이그레이션이 필요하면 먼저 클라이언트를 종료한 뒤 애플리케이션 디렉터리를 백업하세요. 클라이언트에 내보내기 기능이 있다면 해당 내보내기 절차를 우선 이용하는 것이 좋습니다.

데스크톱 프록시를 켠 뒤에는 먼저 클라이언트 로그에 포트 수신 대기가 성공했다는 메시지가 있는지 확인한 다음 브라우저 접속을 테스트하세요. 브라우저는 정상인데 터미널 명령만 실패한다면, 대개 커널이나 노드가 고장 난 것이 아니라 터미널 프로그램이 시스템 프록시를 읽지 않는다는 뜻입니다.

mihomo 명령줄 배포: 디렉터리, 설정 및 실행 확인

그래픽 환경이 없다면 실행 파일, 설정 파일, 실행 데이터를 분리해 관리하는 것이 좋습니다. 시스템 전체에 배포할 때는 바이너리를 /usr/local/bin/mihomo에, 설정 디렉터리를 /etc/mihomo에 둘 수 있습니다. 현재 사용자만 사용할 경우에는 설정을 ~/.config/mihomo에 저장할 수 있습니다. 커널이 캐시, 규칙 데이터, 실행 상태를 저장할 수 있으므로 설정 디렉터리는 실행 계정에 읽기 및 쓰기 권한을 허용해야 합니다.

바이너리를 설치한 뒤 먼저 실행 가능한지 확인하세요.

mihomo -v
mihomo -h

터미널에 명령을 찾을 수 없다는 메시지가 표시되면 파일이 PATH에 포함된 디렉터리에 있는지, 실행 권한이 있는지 확인하세요. 바이너리가 현재 디렉터리에 있다면 ./mihomo를 사용해야 합니다. Shell은 기본적으로 현재 디렉터리에서 명령을 검색하지 않습니다.

mihomo는 YAML 설정을 사용합니다. 다음은 수신 대기 포트와 규칙 엔진을 확인하기 위한 최소 예시입니다. 모든 트래픽을 직접 연결하며 원격 노드는 포함하지 않습니다.

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
ipv6: false

proxies: []
proxy-groups: []

rules:
  - MATCH,DIRECT

파일을 config.yaml로 저장한 뒤 먼저 설정을 검사할 수 있습니다. 버전에 따라 지원되는 명령 인자가 조금 다를 수 있으므로 mihomo -h의 출력을 기준으로 하세요. 일반적인 확인 방법은 다음과 같습니다.

mihomo -t -d /etc/mihomo

검사가 통과되면 포그라운드 방식으로 시작하세요.

mihomo -d /etc/mihomo

-d는 작업 디렉터리를 지정하며, 커널은 해당 디렉터리에서 기본 설정과 관련 데이터를 읽습니다. 처음 배포할 때는 바로 백그라운드로 보내지 말고 먼저 시작 로그를 확인하세요. YAML 파싱 여부, 포트 사용 여부, 규칙 파일 읽기 가능 여부를 점검해야 합니다. mixed 포트가 성공적으로 수신 대기 상태가 되면 다른 SSH 세션을 열어 프록시를 테스트하세요.

curl --proxy http://127.0.0.1:7890 https://example.com/

실제로 사용하는 구독 설정에는 보통 프록시 노드, 정책 그룹, 규칙, DNS 및 규칙 프로바이더가 포함됩니다. 설정을 업데이트할 때는 YAML 문법만 확인해서는 안 됩니다. 정책 그룹이 참조하는 노드나 프로바이더 이름이 존재하는지, 규칙 마지막에 합리적인 기본 처리 항목이 있는지, 사용한 필드가 현재 mihomo 버전에서 지원되는지도 확인해야 합니다.

systemd 서비스 자동 시작: 실행 계정, 재시작 정책 및 로그

장시간 실행해야 한다면 mihomo를 systemd 시스템 서비스로 등록할 수 있습니다. 시스템 서비스는 부팅 직후 프록시 포트를 제공해야 하는 장비에 적합하며, 종료 상태와 실행 로그를 한곳에서 확인하기도 쉽습니다. 서비스를 만들기 전에 전용 계정과 설정 디렉터리를 준비하세요.

sudo useradd --system --home-dir /var/lib/mihomo --create-home --shell /usr/sbin/nologin mihomo
sudo mkdir -p /etc/mihomo
sudo chown -R mihomo:mihomo /etc/mihomo /var/lib/mihomo
sudo chmod 750 /etc/mihomo

그런 다음 /etc/systemd/system/mihomo.service를 만드세요.

[Unit]
Description=mihomo proxy service
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=mihomo
Group=mihomo
WorkingDirectory=/etc/mihomo
ExecStart=/usr/local/bin/mihomo -d /etc/mihomo
Restart=on-failure
RestartSec=5
LimitNOFILE=1048576

[Install]
WantedBy=multi-user.target

서비스 파일을 작성한 뒤 systemd 설정을 다시 불러오고 시작하세요.

sudo systemctl daemon-reload
sudo systemctl enable --now mihomo
sudo systemctl status mihomo

이번 부팅에서 발생한 로그는 다음 명령으로 확인할 수 있습니다.

sudo journalctl -u mihomo -b
sudo journalctl -u mihomo -f

-b는 이번 부팅 이후의 기록만 표시하고, -f는 새 로그를 계속 추적합니다. YAML을 수정했다면 먼저 별도로 설정을 검사한 후 서비스를 재시작하는 것이 좋습니다.

sudo -u mihomo /usr/local/bin/mihomo -t -d /etc/mihomo
sudo systemctl restart mihomo

현재 사용자가 로그인한 뒤에만 실행하려면 systemd 사용자 서비스를 사용할 수도 있습니다. 유닛 파일을 ~/.config/systemd/user/에 넣고 systemctl --user로 관리하세요. 사용자 서비스에는 전용 시스템 계정이 필요하지 않지만, 기본적으로 사용자 세션의 수명 주기에 영향을 받습니다. 로그아웃 후에도 계속 실행해야 한다면 시스템의 linger 설정과 권한 및 유지 관리 방식을 함께 검토해야 합니다.

서비스를 조건 없이 빠르게 재시작하도록 설정하지 마세요. 설정 문법 오류, 포트 충돌 또는 파일 권한 오류는 연속 재시작으로 해결되지 않으며 오히려 반복 로그가 대량으로 쌓일 수 있습니다. Restart=on-failure에 수 초의 간격을 두는 방식이 일시적인 프로세스 종료를 처리하는 데 더 적합합니다.

터미널 프록시 변수: HTTP_PROXY, ALL_PROXY 및 NO_PROXY

Linux 데스크톱의 ‘시스템 프록시’가 모든 Shell 명령에 자동으로 적용되는 것은 아닙니다. curl, Git, 일부 패키지 관리자와 개발 도구는 환경 변수를 읽으므로 명령줄 환경에서 별도로 설정해야 합니다. mihomo의 mixed 포트가 7890이라고 가정하면 현재 터미널에서 다음을 실행할 수 있습니다.

export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export ALL_PROXY=socks5h://127.0.0.1:7890
export NO_PROXY=localhost,127.0.0.1,::1

더 많은 도구와 호환하려면 대문자와 소문자 변수를 함께 설정하세요.

export http_proxy="$HTTP_PROXY"
export https_proxy="$HTTPS_PROXY"
export all_proxy="$ALL_PROXY"
export no_proxy="$NO_PROXY"

socks5h의 h는 도메인 이름 해석도 SOCKS 프록시 측에서 처리한다는 뜻입니다. 로컬 DNS 경로의 차이를 줄이고 싶은 명령줄 요청에 적합합니다. 다만 도구마다 프록시 프로토콜과 변수 우선순위를 구현하는 방식이 완전히 같지는 않습니다. 문제가 발생하면 먼저 curl에서 프록시를 명시해 테스트한 뒤 해당 도구의 문서를 확인하세요.

장시간 활성화해야 한다면 내보내기 명령을 Bash의 ~/.bashrc나 Zsh의 ~/.zshrc 같은 Shell 설정에 넣을 수 있습니다. 더 안전한 방법은 전환 함수를 정의하는 것입니다. 그래야 로컬 네트워크 서비스에 접근하거나 네트워크 문제를 진단할 때 프록시를 끄는 것을 잊지 않습니다.

proxy_on() {
  export HTTP_PROXY=http://127.0.0.1:7890
  export HTTPS_PROXY=http://127.0.0.1:7890
  export ALL_PROXY=socks5h://127.0.0.1:7890
  export NO_PROXY=localhost,127.0.0.1,::1
  export http_proxy="$HTTP_PROXY"
  export https_proxy="$HTTPS_PROXY"
  export all_proxy="$ALL_PROXY"
  export no_proxy="$NO_PROXY"
}

proxy_off() {
  unset HTTP_PROXY HTTPS_PROXY ALL_PROXY NO_PROXY
  unset http_proxy https_proxy all_proxy no_proxy
}

sudo를 실행하면 환경 변수가 필터링되는 경우가 많습니다. 따라서 일반 사용자 터미널에서 프록시를 켰다고 해서 sudo로 시작한 프로그램도 프록시를 사용하는 것은 아닙니다. 편의를 위해 모든 환경 변수를 광범위하게 보존하지 말고, 패키지 관리자나 특정 명령이 지원하는 프록시 설정을 사용하세요.

컨테이너도 호스트의 127.0.0.1 프록시를 자동으로 상속하지 않습니다. 컨테이너 내부의 루프백 주소는 호스트가 아니라 컨테이너 자체를 가리킵니다. 컨테이너에서 호스트 프록시에 접근해야 한다면 Docker, Podman 및 네트워크 모드에 맞춰 접근 가능한 호스트 주소를 설정하고, mihomo의 수신 주소, LAN 접근 설정 및 방화벽 규칙을 확인하세요. 프록시 포트를 LAN에 노출하기 전에는 허용할 네트워크 범위도 제한해야 합니다.

TUN 모드: 권한, 라우팅 및 DNS 연동

시스템 프록시와 환경 변수는 프록시 설정을 능동적으로 읽는 애플리케이션에만 적용됩니다. 프록시 설정을 지원하지 않는 프로그램의 경우 mihomo가 TUN 가상 네트워크 장치를 통해 트래픽을 가로챌 수 있습니다. TUN 모드는 라우팅을 변경하고 더 많은 연결을 처리하므로 일반 포트 프록시보다 배포가 복잡합니다.

Linux 시스템에는 먼저 /dev/net/tun이 제공되어야 합니다. 다음 명령으로 확인할 수 있습니다.

ls -l /dev/net/tun

컨테이너나 제한된 가상 환경에서는 이 장치가 매핑되지 않았을 수 있습니다. 장치가 존재하더라도 mihomo를 실행하는 계정에는 네트워크 관리 권한이 필요합니다. systemd 서비스에는 필요에 따라 권한을 추가할 수 있습니다.

CapabilityBoundingSet=CAP_NET_ADMIN CAP_NET_BIND_SERVICE
AmbientCapabilities=CAP_NET_ADMIN CAP_NET_BIND_SERVICE

두 줄은 서비스 파일의 [Service] 구간에 넣어야 합니다. 수정한 뒤 systemctl daemon-reload를 실행하고 서비스를 재시작하세요. 일반 프록시 포트가 1024보다 크다면 대개 CAP_NET_BIND_SERVICE가 필요하지 않습니다. 유지할지는 실제 수신 포트에 따라 결정하세요.

TUN을 설정할 때는 자동 라우팅, 송신 인터페이스 자동 감지, DNS 하이재킹 및 IPv6 동작을 확인해야 합니다. mihomo 버전에 따라 지원 필드가 변경될 수 있으므로 현재 버전의 문서와 시작 로그를 기준으로 하세요. 배포 후에는 최소한 다음 항목을 검증해야 합니다.

  1. mihomo를 중지한 뒤 시스템 기본 라우트와 DNS가 복구되는가.
  2. 현재 SSH 연결이 안정적으로 유지되며 원격 관리 주소가 잘못 프록시로 전달되지 않는가.
  3. LAN 대역, 게이트웨이, NAS 및 개발 서비스가 예상대로 직접 연결되는가.
  4. IPv4와 IPv6에 일관된 정책이 적용되어 한쪽 트래픽만 규칙을 우회하지 않는가.
  5. 절전 모드 해제, 네트워크 전환 또는 VPN 연결 후 TUN 라우트를 다시 만들어야 하는가.

문제 해결: 프로세스, 포트, 설정, 규칙 순서로 점검하기

Linux의 연결 문제는 계층별로 점검하는 것이 좋습니다. 처음부터 노드를 계속 바꾸거나 클라이언트를 재설치하지 마세요. 먼저 프로세스가 존재하는지 확인하고, 그다음 포트 수신 대기, 프록시 요청, DNS, 규칙 매칭 순서로 확인합니다.

프로세스가 시작 직후 종료되는 경우

systemd를 사용한다면 먼저 systemctl status mihomo와 journalctl -u mihomo -b를 실행하세요. 흔한 원인으로는 YAML 들여쓰기 오류, 현재 커널에서 지원하지 않는 설정 필드, 쓰기 불가능한 작업 디렉터리, 존재하지 않는 규칙 파일 참조가 있습니다. mihomo -t -d /etc/mihomo를 직접 실행하면 설정 오류가 발생한 위치를 더 정확히 확인할 수 있습니다.

포트가 이미 사용 중인 경우

7890 포트를 수신 대기 중인 프로세스를 확인하세요.

ss -lntp | grep 7890

이전 인스턴스, 다른 프록시 클라이언트 또는 중복 실행된 서비스가 같은 포트를 점유하고 있을 수 있습니다. 필요 없는 인스턴스를 중지하거나 설정에서 포트를 변경하고 터미널 프록시 변수도 함께 수정하세요. 한쪽만 바꾸면 프로그램이 계속 이전 포트에 접속할 수 있습니다.

이 컴퓨터에서는 사용할 수 있지만 다른 장치에서는 연결할 수 없는 경우

먼저 allow-lan, 수신 주소 및 호스트 방화벽을 확인하세요. 127.0.0.1에서만 수신 대기하면 서비스는 로컬 연결만 허용합니다. LAN 접근을 허용한 뒤에도 방화벽의 출발지 범위를 제한하고, 제어 인터페이스를 신뢰할 수 없는 네트워크에 직접 노출하지 않아야 합니다. external-controller를 설정했다면 루프백 주소에 바인딩하고 접근 인증 정보를 설정하는 것이 좋습니다.

브라우저는 되지만 Git 또는 curl이 연결되지 않는 경우

대개 시스템 프록시와 터미널 환경이 분리되어 있기 때문입니다. env | grep -i proxy를 실행해 현재 변수를 확인하고, curl의 --proxy 인자로 비교 테스트를 진행하세요. 도구 자체에 이전 프록시 주소가 저장되어 있는지도 확인해야 합니다. 예를 들어 Git의 전역 프록시 설정이 현재 환경을 덮어쓸 수 있습니다.

프록시는 연결되지만 대상 트래픽이 잘못된 정책으로 처리되는 경우

로그 수준을 잠시 높여 요청이 어떤 규칙과 정책 그룹에 매칭되는지 확인하세요. Clash 규칙은 순서대로 매칭되므로 앞에 있는 포괄적인 규칙이 트래픽을 먼저 가로챌 수 있습니다. 도메인 규칙, IP 규칙, GEOIP 또는 규칙 세트의 순서를 확인하고 목록 마지막에 명확한 기본 처리 규칙이 있는지 점검하세요. 규칙을 수정한 뒤 먼저 설정을 검사하고, 무중단 리로드 또는 서비스 재시작을 수행하세요.

커널과 설정을 업데이트하는 순서

커널 업데이트와 설정 업데이트는 분리해서 진행해야 합니다. 먼저 현재 실행 가능한 바이너리와 설정 사본을 보존한 뒤 둘 중 하나만 교체하고 검증하세요. mihomo를 업데이트했다면 먼저 버전 명령과 설정 검사를 실행해 기존 필드를 계속 파싱할 수 있는지 확인합니다. 구독을 업데이트한 경우에는 정책 그룹 참조, 규칙 프로바이더 및 노드 이름을 중점적으로 점검하세요. 한 번에 핵심 변수 하나만 변경하면 문제가 생겼을 때 되돌리고 원인을 찾기 쉽습니다.

장기간 실행하는 서버라면 서비스 종료 상태, 로그 용량 및 설정 업데이트 시점을 정기적으로 확인하는 것이 좋습니다. 구독 자동 업데이트가 커널의 자동 리로드를 의미하는 것은 아닙니다. 파일이 변경된 뒤 사용하는 클라이언트나 스크립트가 설정 로드를 다시 실행하는지 확인하세요. 읽는 중인 설정 파일을 직접 덮어쓸 때는 먼저 임시 파일에 작성하고 문법 검사를 완료한 뒤 정식 파일로 원자적 교체를 수행하는 것이 좋습니다. 일부만 기록된 상태를 읽을 위험을 줄일 수 있습니다.

배포 완료 후 점검 목록

  • 다운로드한 빌드의 아키텍처가 uname -m으로 확인한 프로세서 아키텍처와 일치하는지 확인하세요.
  • 설정 디렉터리의 소유자가 실행 계정이며 민감한 설정을 다른 로컬 사용자가 읽을 수 없도록 되어 있는지 확인하세요.
  • 포그라운드 시작 단계에서 YAML, 수신 대기 포트 및 기본 프록시 요청 테스트를 완료하세요.
  • systemd 서비스에 명확한 작업 디렉터리, 실행 계정 및 실패 시 재시작 정책이 설정되어 있는지 확인하세요.
  • 터미널 프록시 변수가 mihomo의 실제 포트와 일치하고, 로컬 및 LAN 주소에 합리적인 직접 연결 범위가 설정되어 있는지 확인하세요.
  • TUN을 활성화하기 전에 장치 노드, 네트워크 권한, SSH 관리 경로 및 라우팅 복구 방법을 점검하세요.
  • 구독, 규칙 또는 커널 버전을 수정한 뒤 항목별로 검증하여 여러 실행 조건을 동시에 변경하지 않도록 하세요.

데스크톱 클라이언트, mihomo 명령줄 및 systemd는 서로 배타적인 방식이 아닙니다. 개인 워크스테이션에서는 그래픽 클라이언트로 일상적인 노드를 관리하면서 로그 진단에 명령줄을 함께 사용할 수 있습니다. 헤드리스 서버에서는 mihomo와 systemd를 이용해 안정적이고 감사 가능한 실행 방식을 구성할 수 있습니다. 배포 방식을 정한 뒤 애플리케이션이 시스템 프록시를 읽는지에 따라 환경 변수 또는 TUN을 선택하면 전체 설정이 더 명확해집니다.

Clash 다운로드