Linux에서 mihomo 설치하기: 데스크톱 클라이언트와 systemd 무인 실행

환경에 맞는 방식 선택: 데스크톱 클라이언트 또는 독립 실행형 코어

mihomo는 Clash 설정과 호환되는 프록시 코어로, Clash Meta로 표시된 설정 및 클라이언트에서 흔히 사용됩니다. 코어는 프록시 포트를 열고 규칙을 적용해 연결을 처리합니다. GUI 클라이언트는 여기에 구독 관리, 노드 선택, 시스템 프록시 전환 기능을 제공합니다. 코어만 설치해도 트레이 아이콘이 생기거나 브라우저 프록시 설정이 자동으로 바뀌지는 않습니다.

사용 환경	권장 방식	주요 관리 방법
GNOME, KDE 등 일반 데스크톱	Linux를 지원하는 GUI 클라이언트	앱에서 구독을 가져오고 규칙과 노드를 선택
SSH로 관리하는 서버	mihomo 바이너리와 systemd	YAML 편집 및 서비스 로그 확인
컨테이너 또는 경량 배포판	먼저 초기화 시스템 확인	PID 1이 systemd가 아니라면 해당 환경의 프로세스 관리 방식을 사용하세요

이 문서의 서비스 구성은 systemd를 사용하는 일반적인 Linux 호스트를 대상으로 하며, 우선 로컬에서만 사용할 수 있는 명시적 프록시를 설정합니다. 명시적 프록시는 앱이 지정된 포트로 요청을 보내는 방식입니다. 투명 프록시가 아니며 서버의 모든 연결을 자동으로 가로채지 않습니다.

데스크톱에서 설정하기: Linux 클라이언트 설치 및 구성 가져오기

배포판과 프로세서 아키텍처 확인

터미널을 열고 다음 두 명령을 실행하세요. 첫 번째 명령은 배포판을 확인하고, 두 번째 명령은 커널이 보고하는 프로세서 아키텍처를 확인합니다. x86_64는 보통 설치 패키지의 x64 또는 amd64에 해당하고, aarch64는 보통 arm64에 해당합니다. Intel 또는 AMD 프로세서를 사용한다고 해서 ARM 패키지를 다운로드하면 안 됩니다.

cat /etc/os-release
uname -m

설치 패키지 페이지를 열고 Clash Verge Rev 또는 FlClash처럼 Linux 배포 패키지를 제공하는 클라이언트를 선택하세요. 다운로드하기 전에 해당 배포판이 지원하는 플랫폼과 아키텍처를 확인하세요.
Debian 및 Ubuntu 계열에서는 해당 DEB 패키지를, Fedora 등에서는 해당 RPM 패키지를 선택하세요. AppImage는 배포처에서 제공하는지, 그리고 FUSE 같은 실행 종속성이 시스템에 설치되어 있는지에 따라 사용할 수 있습니다.
클라이언트를 실행하고 구독 또는 설정 관리 화면에서 구독 URL을 추가한 다음 업데이트하고 해당 설정을 선택하세요. 클라이언트에 따라 메뉴 이름이 ‘구독’ 또는 ‘설정’일 수 있습니다. 노드 공유 문자열을 완성된 YAML 파일인 것처럼 가져오지 마세요.
먼저 규칙 모드와 사용할 수 있는 노드를 선택한 뒤 시스템 프록시를 켜세요. 연결 기록을 확인해 요청이 현재 클라이언트로 전달되는지 점검합니다.

다운로드한 설치 패키지의 이름을 client.deb로 바꾼 경우, 해당 디렉터리에서 sudo apt install ./client.deb를 실행하면 됩니다. 파일명은 사용자가 직접 변경한 것이며 이 사이트의 설치 패키지 주소가 아닙니다. RPM 패키지도 같은 방식으로 client.rpm으로 이름을 바꾼 뒤 sudo dnf install ./client.rpm을 실행할 수 있습니다.

시스템 프록시와 터미널 프록시 구분하기

GNOME 데스크톱에서는 ‘설정’ → ‘네트워크’ → ‘네트워크 프록시’에서 현재 설정을 확인할 수 있습니다. 데스크톱 버전에 따라 메뉴 위치는 조금 다를 수 있습니다. 브라우저는 이 설정을 따를 수 있지만 터미널의 명령줄 도구는 그렇지 않을 수 있습니다. 먼저 클라이언트에 표시된 혼합 포트를 확인하세요. 포트가 7890이라면 시스템 프록시를 반복해서 전환하는 대신 아래의 curl --proxy로 별도 테스트하세요.

데스크톱의 ‘로그인 시 시작’과 서버의 ‘부팅 시 시작’은 다릅니다. 전자는 보통 사용자가 그래픽 세션에 로그인해야 실행되지만, 후자는 로그인하지 않아도 실행할 수 있습니다. SSH 접속 직후 프록시를 사용해야 하는 호스트에는 아래의 systemd 방식이 더 적합합니다.

서버 준비: 바이너리 설치 및 전용 실행 계정 생성

먼저 ps -p 1 -o comm=를 실행해 출력이 systemd인지 확인하세요. 그런 다음 uname -m 결과에 맞는 mihomo Linux 바이너리를 받아 압축을 풀고 파일명을 mihomo로 변경합니다. x86 빌드는 CPU 명령어 집합 수준에 따라 나뉠 수 있습니다. Illegal instruction 오류가 발생하면 프로그램 권한을 추가하기보다 빌드 요구 사항을 다시 확인하세요.

아래 명령은 현재 터미널 디렉터리에 압축을 푼 mihomo 파일이 있다고 가정합니다. 먼저 실행 권한을 부여한 다음 프로그램이 실행되는지 확인하세요. -v는 설치된 버전을 출력하므로 이후 기록하거나 이전 버전으로 되돌릴 때 참고할 수 있습니다.

chmod +x ./mihomo
./mihomo -v
sudo install -m 0755 ./mihomo /usr/local/bin/mihomo

sudo useradd --system --user-group \
  --home-dir /var/lib/mihomo \
  --shell /usr/sbin/nologin mihomo

sudo install -d -o root -g mihomo -m 0750 /etc/mihomo

여기서는 대화형 로그인에 사용하지 않는 전용 시스템 계정을 만듭니다. 시스템에 이미 mihomo 계정이 있다면 먼저 id mihomo로 계정과 그룹을 확인하고 생성 단계는 건너뛰세요. 전용 계정을 사용하면 설정 파일 읽기 권한과 실행 데이터 디렉터리를 더 쉽게 관리할 수 있습니다. 이 구성에서는 서비스를 root로 실행할 필요가 없습니다.

/usr/local/bin/mihomo: mihomo 실행 파일을 저장합니다.
/etc/mihomo/config.yaml: 관리자가 유지하는 설정 파일을 저장합니다.
/var/lib/mihomo: 실행 데이터를 저장합니다. 이후 systemd 유닛에서 디렉터리를 만들고 권한을 설정합니다.

최소 YAML 설정으로 구성과 포트 확인

YAML은 들여쓰기로 필드를 구분하는 텍스트 설정 형식입니다. 들여쓰기에는 공백을 사용하고 Tab은 사용하지 마세요. 먼저 다음 최소 설정으로 실행 기준을 마련합니다. 로컬의 7890 혼합 포트만 열어 HTTP 프록시와 SOCKS5 연결을 모두 받고, 모든 요청은 직접 연결합니다. 프록시 노드는 포함하지 않습니다.

sudo tee /etc/mihomo/config.yaml > /dev/null <<'YAML'
mixed-port: 7890
allow-lan: false
bind-address: 127.0.0.1
mode: rule
log-level: info
ipv6: false

rules:
  - MATCH,DIRECT
YAML

sudo chown root:mihomo /etc/mihomo/config.yaml
sudo chmod 0640 /etc/mihomo/config.yaml

sudo -u mihomo /usr/local/bin/mihomo \
  -t -d /tmp -f /etc/mihomo/config.yaml

설정 검사를 통과했다고 프록시 노드까지 사용할 수 있는 것은 아닙니다. -t는 설정을 불러올 수 있는지 확인합니다. 여기서 MATCH,DIRECT는 프로그램, 권한, 리스닝 설정을 점검하기 위한 최종 직접 연결 규칙일 뿐이며 요청을 원격 프록시로 전달하지 않습니다.

실제 트래픽을 분리하려면 신뢰할 수 있는 출처에서 제공한 완전한 mihomo 설정으로 교체하세요. 완전한 설정에는 보통 proxies, proxy-groups, rules가 포함되며 규칙에서 참조하는 정책 그룹 이름도 실제로 존재해야 합니다. 노드 목록만 있는 provider 파일, Base64 노드 문자열, 구독 웹페이지는 -f에 바로 전달할 수 있는 완전한 설정과 다릅니다.

설정을 교체한 뒤에도 로컬 리스닝의 보안 경계를 유지하고 설정 검사를 다시 실행하세요. 구독 URL에 접근 토큰이 포함될 수 있고 파일에 노드 인증 정보가 들어갈 수도 있으므로 공개 로그, 스크린샷, 셸 기록에 붙여 넣지 마세요. 설정에서 상대 경로를 사용하는 경우 이 서비스는 /var/lib/mihomo를 데이터 디렉터리로 사용합니다. 규칙 파일과 provider 파일을 읽을 수 있는지도 함께 확인하세요.

systemd 서비스 생성 및 부팅 시 자동 시작 설정

systemd 서비스 유닛은 프로세스의 실행 방법, 사용할 계정, 실패 시 처리 방식을 정의합니다. 아래 내용을 /etc/systemd/system/mihomo.service에 저장하세요. 이 유닛은 일반 프록시 포트를 대상으로 하며 TUN을 설정하거나 네트워크 관리 권한을 부여하지 않습니다.

sudo tee /etc/systemd/system/mihomo.service > /dev/null <<'UNIT'
[Unit]
Description=mihomo local proxy service
Wants=network-online.target
After=network-online.target

[Service]
Type=simple
User=mihomo
Group=mihomo
StateDirectory=mihomo
StateDirectoryMode=0750
ExecStartPre=/usr/local/bin/mihomo -t -d /var/lib/mihomo -f /etc/mihomo/config.yaml
ExecStart=/usr/local/bin/mihomo -d /var/lib/mihomo -f /etc/mihomo/config.yaml
Restart=on-failure
RestartSec=5s
UMask=0077
NoNewPrivileges=true
PrivateTmp=true
ProtectHome=true
ProtectSystem=strict

[Install]
WantedBy=multi-user.target
UNIT

sudo systemctl daemon-reload
sudo systemctl enable --now mihomo
systemctl status mihomo --no-pager
systemctl is-enabled mihomo

active (running)이 표시되면 프로세스가 실행 중입니다. is-enabled의 출력이 enabled이면 부팅 시 자동 시작이 설정된 것입니다. 두 항목을 각각 확인하세요. 자동 시작이 설정되어 있어도 설정 오류로 서비스가 실행되지 않을 수 있습니다.

StateDirectory=mihomo는 쓰기 가능한 데이터 디렉터리를 만듭니다. ProtectSystem=strict는 나머지 파일 시스템에 대한 쓰기를 제한하고, ProtectHome=true는 사용자 홈 디렉터리 접근을 제한합니다. 따라서 설정에서 /home 아래의 구독 파일을 참조하지 마세요. 추가 리소스가 필요하면 적절한 데이터 디렉터리에 두고 소유권과 권한을 확인하세요.

network-online.target은 네트워크가 준비된 뒤 시작하도록 순서를 지정하지만, 실제 효과는 배포판에서 해당 네트워크 대기 서비스가 활성화되어 있는지에 따라 달라집니다. 구독 서버에 지금 접속할 수 있다는 보장은 없습니다. 원격에서 규칙을 내려받는 설정이라면 로그를 확인해 네트워크 대기 문제인지 원격 리소스 문제인지 구분하세요.

설정 변경 후 실행 순서

sudo -u mihomo /usr/local/bin/mihomo \
  -t -d /var/lib/mihomo -f /etc/mihomo/config.yaml
sudo systemctl restart mihomo
sudo journalctl -u mihomo -n 80 --no-pager

앞선 설정 검사가 성공한 경우에만 재시작하세요. YAML을 수정할 때는 daemon-reload가 필요하지 않으며 서비스 유닛을 수정했을 때만 필요합니다. 이 예시에는 ExecReload가 정의되어 있지 않으므로 systemctl reload mihomo를 재시작 대신 사용하지 마세요. 재시작하면 기존 프록시 연결이 끊기므로 장시간 다운로드나 원격 작업 중에는 피하세요.

요청 확인: 리스닝, HTTP 프록시, SOCKS5

‘프로세스 실행 → 포트 리스닝 → 앱 요청 → 규칙 적용’ 순서로 확인하세요. 먼저 7890 포트를 확인합니다. 리스닝 주소는 외부 공개 인터페이스가 아니라 127.0.0.1:7890이어야 합니다.

sudo ss -lntp 'sport = :7890'

curl --proxy http://127.0.0.1:7890 \
  --connect-timeout 10 --max-time 20 \
  -I https://example.com

curl --proxy socks5h://127.0.0.1:7890 \
  --connect-timeout 10 --max-time 20 \
  -I https://example.com

여기서 10초는 연결 제한 시간이고 20초는 전체 요청 제한 시간이며 성능 측정 결과가 아닙니다. socks5h를 사용하면 프록시가 대상 도메인을 조회하고, socks5는 보통 curl이 로컬에서 도메인을 조회합니다. 이 차이가 DNS 문제를 진단할 때 영향을 줍니다.

최소 설정에서 요청이 성공하면 로컬 프록시 연결과 직접 연결 경로가 작동한다는 점만 확인할 수 있습니다. 실제 설정으로 바꾼 뒤에는 로그에서 규칙과 정책 그룹 선택을 확인해 트래픽이 DIRECT에 적용되지 않았는지 점검하세요. HTTP 상태 코드만으로는 요청이 특정 원격 노드를 사용했다고 판단할 수 없습니다.

현재 터미널에서만 프록시 사용하기

export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890
export no_proxy=localhost,127.0.0.1,::1

curl -I --max-time 20 https://example.com

unset http_proxy https_proxy no_proxy

https_proxy 값에 http://를 사용해도 됩니다. 클라이언트가 HTTP 프록시를 통해 CONNECT 터널을 만드는 것이며 대상 HTTPS 연결을 평문으로 바꾸는 것은 아닙니다. 환경 변수는 해당 변수를 읽는 프로그램에만 적용됩니다. 이미 실행 중인 systemd 서비스는 현재 터미널 설정을 자동으로 물려받지 않습니다. 여기서는 소문자 변수를 사용해 일부 도구가 대문자 HTTP_PROXY를 특별하게 처리하는 경우도 피합니다.

자주 발생하는 문제와 구성 범위

시작 실패 또는 반복 재시작

203/EXEC 오류가 발생하는 경우: ExecStart 경로, 파일 실행 권한, 바이너리 아키텍처를 확인하세요. 압축을 풀지 않은 파일을 실행 경로에 두지 마세요.
address already in use 오류가 발생하는 경우: ss로 7890 포트를 사용하는 프로세스를 찾으세요. 다른 데스크톱 클라이언트나 이전 코어가 흔한 원인입니다.
permission denied 오류가 발생하는 경우: 설정 파일의 그룹이 mihomo인지, 경로의 각 상위 디렉터리에 접근할 수 있는지 확인하세요. 민감한 설정 파일을 모든 사용자가 읽을 수 있도록 바꾸지 마세요.
YAML 구문 오류가 발생하는 경우: 들여쓰기, 콜론, 목록 계층을 확인하고 웹페이지에서 복사하며 들어간 탭 문자가 없는지 살펴보세요. -t 검사에 통과한 뒤 시작하세요.
시작 빈도 제한에 걸린 경우: 먼저 원인을 해결한 뒤 sudo systemctl reset-failed mihomo와 sudo systemctl start mihomo를 실행하세요. 재시작만 반복하지 마세요.

구독 업데이트, 제어 API, TUN

독립 코어는 GUI 클라이언트의 ‘구독 업데이트’ 절차를 자동으로 제공하지 않습니다. 원격 설정 파일 전체를 사용하려면 별도로 가져오고 교체하는 절차를 마련하세요. 업데이트할 때는 먼저 임시 파일로 다운로드하고 권한을 제한한 뒤 구문을 확인하고 현재 설정과 교체해야 합니다. 설정의 proxy-providers는 지정된 업데이트 간격에 따라 노드 목록을 갱신할 수 있지만, 주 설정 파일 전체가 함께 갱신되는 것은 아닙니다.

이 예시에서는 external-controller를 활성화하지 않으므로 관리 API를 제공하지 않습니다. 대시보드가 꼭 필요하다면 먼저 루프백 리스닝, 접근 키, SSH 터널을 계획하고 관리 포트를 인터넷에 직접 공개하지 마세요. allow-lan: false와 로컬 리스닝을 함께 사용하면 다른 LAN 기기에서 이 서버를 프록시로 직접 이용할 수도 없습니다.

TUN은 가상 네트워크 인터페이스로 트래픽을 전달하는 방식이며 /dev/net/tun, 라우팅, DNS, 네트워크 권한도 고려해야 합니다. 이 문서의 일반 사용자 계정과 보안 강화 유닛은 TUN 구성용이 아닙니다. enable: true 한 줄만 추가했다고 구성이 완료되는 것은 아닙니다. 특히 SSH로 관리하는 서버에서는 투명 프록시를 구성하기 전에 관리 연결이 직접 연결 경로를 유지하도록 설계하세요.

업그레이드 및 서비스 중지

업그레이드 전에 mihomo -v 결과를 기록하고 현재 바이너리와 설정을 백업하세요. 서비스를 중지한 뒤 바이너리를 교체하고 새 파일의 아키텍처와 버전, 설정 호환성을 확인한 다음 서비스를 시작해 포트와 요청을 다시 점검합니다. 실행과 부팅 시 자동 시작을 해제하려면 아래 명령을 실행하세요. 설정과 실행 데이터는 삭제되지 않습니다.

sudo systemctl disable --now mihomo

최종 점검 결과로 다음 네 가지를 확인하세요. 설정 검사 통과, 서비스 실행 상태, 예상한 리스닝 주소, 실제 앱 요청에 적용된 규칙입니다. 데스크톱 사용자는 설정 선택과 시스템 프록시를, 서버 사용자는 계정 권한과 서비스 로그, 반복 가능한 시작 절차를 중점적으로 확인하세요.