Linux mihomo 설치 가이드: GUI 클라이언트와 systemd 헤드리스 실행

1. 데스크톱은 GUI 클라이언트, 서버는 systemd

Linux에서 프록시를 사용하는 방법은 크게 두 가지입니다. 데스크톱 환경에서 트레이 아이콘으로 노드를 바꾸려면 mihomo 엔진이 포함된 GUI 클라이언트를 설치하세요. SSH 터미널만 사용할 수 있고 로그아웃 후에도 계속 실행해야 하는 서버라면 mihomo 엔진을 직접 설치해 systemd로 관리하면 됩니다. 두 방법은 설정 개념은 같지만 설정 파일 위치, 구독 업데이트, 권한 관리 방식은 다릅니다.

ClashX는 macOS용 클라이언트이며 Linux 설치 패키지는 제공하지 않습니다. Linux 데스크톱에서는 배포판에 맞는 Clash Verge Rev, FlClash 등의 패키지를 선택할 수 있습니다. 서버에서 프록시를 사용하려고 데스크톱 환경을 설치하거나 GUI 클라이언트 창을 실행할 필요는 없습니다.

사용 환경	권장 방식	설정 및 자동 실행 위치
개인용 Linux 데스크톱	GUI 클라이언트	클라이언트 설정 화면, 데스크톱 로그인 시 자동 실행
SSH 서버	mihomo와 systemd	/etc/mihomo/config.yaml, 시스템 서비스
특정 명령에만 프록시 적용	로컬 HTTP / SOCKS 리스너	앱 옵션 또는 프로세스 환경 변수
더 많은 시스템 트래픽을 처리해야 하는 경우	권한을 확인한 뒤 TUN 설정	엔진 설정, 라우팅, DNS

2. Linux 데스크톱에 설치하고 설정 가져오기

아키텍처와 패키지 형식 확인

먼저 다음 명령으로 시스템 정보를 확인하세요. x86_64는 보통 amd64 / x64 패키지, aarch64는 보통 arm64 패키지에 해당하며 서로 호환되지 않습니다. Ubuntu와 Debian에서는 주로 DEB, Fedora에서는 RPM을 선택합니다. 배포판 버전에 따라 시스템 라이브러리 호환성이 다를 수 있으므로 설치 전에 사용할 클라이언트의 최신 릴리스 노트를 확인하세요.

uname -m
cat /etc/os-release

설치 패키지 페이지에서 Linux를 선택한 뒤 아키텍처와 패키지 형식에 맞는 클라이언트를 받으세요.
파일 관리자에서 다운로드한 DEB 또는 RPM 파일을 열고 시스템 패키지 설치 도구로 설치하세요. 의존성 문제로 설치가 실패하면 패키지 관리자가 안내한 의존성을 먼저 해결하고, 오류를 무시하도록 강제하지 마세요.
클라이언트를 실행하고 ‘설정’ 또는 ‘Profiles’ 화면에서 구독 주소나 로컬 YAML 파일을 가져오세요. 메뉴 이름은 클라이언트와 버전에 따라 다를 수 있으니 실제 화면을 기준으로 확인하세요.
가져온 설정을 선택한 다음 노드 목록과 정책 그룹이 표시되는지 확인하세요. 이어서 ‘설정’에서 프록시 포트를 확인해 실제 리스닝 포트를 파악합니다.
먼저 아래의 명시적 프록시 명령으로 연결을 테스트한 뒤 클라이언트의 ‘시스템 프록시’ 옵션을 켜세요.

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

여기서 7890은 예시 포트이며 모든 클라이언트가 이 포트를 사용하는 것은 아닙니다. HTTP 응답을 받으면 요청 경로가 연결된 것이지만, 특정 원격 노드를 거쳤다고 단정할 수는 없습니다. 규칙이 DIRECT와 일치하면 요청은 직접 연결됩니다. 연결 기록에서 규칙, 정책 그룹, 아웃바운드 노드를 함께 확인하세요.

데스크톱 자동 실행은 시스템 서비스와 다릅니다

클라이언트의 ‘시작 시 실행’은 대개 데스크톱 세션에 의존하므로 사용자가 로그인한 뒤에 실행됩니다. 서버를 재부팅한 후 로그인하는 사용자가 없다면 백그라운드 프록시로 적합하지 않습니다. 또한 GUI 클라이언트와 아래 systemd 서비스가 동시에 127.0.0.1:7890을 사용하지 않도록 하세요. 둘 중 하나만 실행하거나 포트를 다르게 지정해야 합니다.

3. mihomo 엔진과 설정 파일 배치

다음 절차는 systemd를 사용하는 Linux 시스템을 대상으로 하며, 명령은 sudo 권한이 있는 일반 사용자로 실행합니다. 예시는 Debian / Ubuntu에서 흔히 쓰는 시스템 도구를 사용합니다. 다른 배포판에서 useradd 등의 명령을 사용할 수 없다면 패키지 관리자로 해당 도구를 먼저 설치하세요. 컨테이너나 일부 경량 시스템에는 systemd가 없을 수 있으므로 이 절의 서비스 설정을 그대로 적용할 수 없습니다.

실행 파일 설치

mihomo 프로젝트의 공식 릴리스 페이지에서 아키텍처와 CPU 명령어 집합에 맞는 Linux 빌드를 선택하세요. 압축을 푼 뒤 실행 파일을 /tmp/mihomo에 둡니다. 파일명은 실제 다운로드한 파일에 맞춰야 하며, 압축 파일을 실행 파일로 사용하면 안 됩니다. 구형 CPU에서는 더 높은 명령어 집합을 요구하는 빌드를 무작정 선택하지 마세요.

file /tmp/mihomo
sudo install -m 0755 /tmp/mihomo /usr/local/bin/mihomo
/usr/local/bin/mihomo -v

-v로 실제 엔진 버전을 확인할 수 있습니다. Exec format error가 발생하면 CPU 아키텍처를 확인하고, Illegal instruction이 발생하면 빌드의 명령어 집합 요구 사항을 확인하세요. 이 글에서는 서비스 파일에 특정 버전을 고정하지 않으므로 이후에도 같은 설치 경로를 사용해 업그레이드할 수 있습니다.

전용 계정과 디렉터리 만들기

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
sudo install -d -o mihomo -g mihomo -m 0750 /var/lib/mihomo

계정이 이미 있다면 생성 단계를 건너뛰고 소속 그룹을 확인하세요. 배포판에 따라 nologin 경로가 다를 수 있으므로 command -v nologin으로 확인한 뒤 필요하면 경로를 수정합니다. 설정은 /etc/mihomo에, 캐시와 런타임 데이터는 /var/lib/mihomo에 둡니다. 서비스 계정에는 설정을 읽을 권한만 있으면 되며, 구독 인증 정보가 들어 있는 파일을 수정할 권한은 필요하지 않습니다.

최소 설정으로 프로세스 확인

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 /var/lib/mihomo -f /etc/mihomo/config.yaml

서비스 제공업체의 설정을 가져올 때는 mihomo가 읽을 수 있는 YAML인지 확인하세요. 웹페이지나 로그인 안내, 노드 URI만 포함된 텍스트일 수 있습니다. 설정을 교체한 뒤에는 리스닝 주소, 컨트롤 포트, 규칙 마지막의 기본 정책을 다시 확인하세요. 구독 설정이 이 문서의 로컬 리스닝 제한을 덮어쓸 수도 있습니다.

-t는 설정 파일을 검사하는 옵션일 뿐, 원격 노드나 규칙 다운로드 주소, 대상 웹사이트에 연결할 수 있는지 확인하지는 않습니다. 검사 과정에서 설정이 참조하는 데이터 파일을 처리할 수도 있습니다. 실패하면 로그를 확인해 YAML 문법 오류, 경로 권한 오류, 리소스 가져오기 오류를 구분하세요.

4. systemd 서비스 작성 및 부팅 시 자동 실행

일반 프록시는 먼저 root가 아닌 계정으로 실행하세요. 7890과 같은 높은 포트를 사용하는 데는 root 권한이 필요하지 않습니다. 아래 서비스는 TUN 권한을 설정하지 않으므로 명시적 HTTP / SOCKS 프록시에 적합하며 투명 게이트웨이 용도로는 적합하지 않습니다.

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
WorkingDirectory=/var/lib/mihomo
ExecStart=/usr/local/bin/mihomo -d /var/lib/mihomo -f /etc/mihomo/config.yaml
Restart=on-failure
RestartSec=5s
UMask=0027
NoNewPrivileges=true
PrivateTmp=true
ProtectHome=true
ProtectSystem=strict
ReadWritePaths=/var/lib/mihomo

[Install]
WantedBy=multi-user.target
UNIT

sudo systemctl daemon-reload
sudo systemctl enable --now mihomo.service
sudo systemctl status mihomo.service --no-pager
sudo journalctl -u mihomo.service -b -n 80 --no-pager

enable --now는 부팅 시 자동 실행을 설정하고 서비스를 즉시 시작합니다. network-online.target이 실제로 대기하는지는 배포판에 해당 네트워크 대기 서비스가 설정되어 있는지에 따라 달라집니다. 인터넷이나 구독 주소에 연결할 수 있다는 보장은 없으므로 원격 리소스의 재시도와 업데이트를 적절히 설정하세요.

config.yaml을 수정했다면 먼저 설정을 검사한 다음 sudo systemctl restart mihomo를 실행하세요.
서비스 유닛을 수정했다면 sudo systemctl daemon-reload를 실행한 뒤 서비스를 재시작하세요.
상태만 확인하려면 systemctl is-active mihomo와 systemctl is-enabled mihomo를 실행하세요.
서비스를 중지하고 부팅 시 자동 실행을 해제하려면 sudo systemctl disable --now mihomo를 실행하세요.

이 유닛에는 ExecReload가 선언되어 있지 않으므로 systemctl reload mihomo를 일반적인 업데이트 명령으로 사용하지 마세요. 재시작하면 새 설정이 적용됐는지 확인하기 쉽지만 기존 연결이 끊길 수 있습니다. 중단 없이 업데이트하려면 현재 엔진의 컨트롤 API 문서를 참고해 별도의 절차를 설계해야 합니다.

5. 포트, 프록시 연결, 앱 동작 확인

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/

혼합 포트는 HTTP 프록시와 SOCKS 프록시 요청을 모두 받을 수 있습니다. 위의 socks5h는 curl이 대상 도메인 처리를 프록시에 맡기도록 합니다. 반면 socks5는 보통 로컬에서 대상 도메인을 먼저 조회합니다. 이 차이는 DNS 문제를 진단할 때 영향을 주므로 포트가 같다는 이유만으로 두 방식의 동작이 같다고 보면 안 됩니다.

현재 셸에서 일부 프로그램에만 프록시 적용

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 --connect-timeout 10 --max-time 20 -I https://example.com/

unset http_proxy https_proxy no_proxy

https_proxy의 값에 http://를 사용해도 됩니다. 이는 HTTP 프록시를 통해 CONNECT 터널을 만든다는 뜻이며, 로컬 프록시 포트 자체가 TLS를 제공해야 한다는 뜻은 아닙니다. 환경 변수는 해당 변수를 읽는 프로그램과 그 자식 프로세스에만 적용됩니다. 브라우저, 다른 systemd 서비스, 모든 UDP 트래픽에 자동으로 적용되지는 않습니다.

패키지 관리자, 컨테이너 데몬, 백그라운드 서비스는 별도의 프록시 설정을 사용할 수 있습니다. 터미널에서 curl이 성공해도 Docker 이미지 다운로드나 시스템 업데이트가 프록시를 사용한다는 뜻은 아닙니다. 각 프로그램의 프록시 설정 위치를 따로 확인하세요. 인증 정보가 포함된 프록시 환경 변수를 모든 사용자가 읽을 수 있는 파일에 함부로 저장하지 마세요.

6. SSH 터널로 컨트롤 API와 대시보드 접속

mihomo의 컨트롤 API와 프록시 포트는 서로 다릅니다. 7890은 프록시 요청을 받고, 아래 설정의 9090은 컨트롤 API에 사용합니다. 서버 대시보드는 SSH 로컬 포트 포워딩으로 접속하는 것이 좋습니다. 원격 접속을 위해 컨트롤 API를 공인 네트워크에 직접 바인딩하지 마세요.

로컬 컨트롤 API 활성화

아래 명령은 앞서 만든 최소 설정을 기준으로 하며 한 번만 실행하세요. 기존 설정에 external-controller 또는 secret이 이미 있다면 키를 중복해서 추가하지 말고 기존 항목을 수정하세요. 명령은 임의의 비밀 키를 생성해 권한이 제한된 설정 파일에 기록하며 터미널에는 출력하지 않습니다.

controller_secret=$(openssl rand -hex 32)

printf '\nexternal-controller: 127.0.0.1:9090\nsecret: "%s"\n' \
  "$controller_secret" | \
  sudo tee -a /etc/mihomo/config.yaml > /dev/null

unset controller_secret

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

이 단계에는 OpenSSL이 설치되어 있어야 합니다. 비밀 키는 컨트롤 인증 정보입니다. 대시보드에 입력하기 전에 보안이 확보된 관리 터미널에서 설정의 secret 항목을 확인하세요. 설정 파일 전체를 공개된 지원 티켓에 붙여 넣지 마세요. 컨트롤 API를 활성화하는 것만으로 웹 대시보드가 제공되지는 않습니다.

대시보드 정적 파일 배포

선택한 호환 대시보드 프로젝트의 공식 릴리스 패키지에서 빌드된 정적 파일을 받으세요. index.html이 들어 있는 디렉터리의 내용을 /etc/mihomo/ui에 배치합니다. 빌드 전 소스 코드 디렉터리를 정적 페이지로 사용하거나 디렉터리를 한 단계 더 중첩해 진입 파일 경로가 달라지지 않도록 하세요.

sudo install -d -o root -g mihomo -m 0750 /etc/mihomo/ui
sudoedit /etc/mihomo/config.yaml

설정 최상위에 다음 항목을 추가하고 서비스 계정이 대시보드 디렉터리의 파일을 읽을 수 있도록 하세요.

external-ui: /etc/mihomo/ui

설정을 검사한 뒤 서비스를 재시작하세요. 로컬 컴퓨터에서 SSH 명령을 실행해 로컬 9090 포트를 서버의 루프백 주소 9090으로 전달합니다. 아래의 mihomo-server는 SSH 설정에 직접 만든 호스트 별칭입니다. 실제로 연결할 수 있는 호스트 이름이나 등록된 별칭을 사용하세요.

ssh -N -L 127.0.0.1:9090:127.0.0.1:9090 mihomo-server

SSH 세션을 유지한 상태에서 로컬 브라우저로 http://127.0.0.1:9090/ui/를 여세요. 대시보드의 백엔드 주소에는 http://127.0.0.1:9090을 입력하고, 비밀 키에는 설정의 secret 값을 입력합니다. 여기서 로컬 주소는 SSH 터널을 통해 서버에 연결하는 브라우저 실행 컴퓨터를 가리킵니다. 브라우저가 서버의 루프백 주소에 직접 접속하는 것은 아닙니다.

7. TUN, 구독 업데이트, 자주 발생하는 문제

TUN은 옵션 하나만 바꿔서는 사용할 수 없습니다

Linux에서 TUN을 사용하려면 /dev/net/tun을 사용할 수 있어야 하며, 일반적으로 네트워크 관리 권한도 필요합니다. 자동 라우팅, 정책 라우팅, DNS 처리도 함께 고려해야 합니다. 이 문서의 전용 사용자 서비스에는 관련 권한이 부여되지 않았으므로 tun.enable: true만 추가하면 권한 오류가 날 수 있습니다. 모든 구성 요소를 장기간 root로 실행하는 것을 첫 번째 해결책으로 삼지 마세요.

서버에서는 특히 SSH 관리 연결을 보호해야 합니다. 기본 경로 설정 오류, DNS 가로채기, 프록시 루프가 발생하면 연결이 끊길 수 있습니다. TUN을 활성화하려면 먼저 클라우드 콘솔이나 직렬 콘솔을 통한 복구 경로를 준비하고, 현재 엔진 문서에서 권한 요구 사항을 확인한 뒤 서비스 권한, 라우팅 제외 규칙, 롤백 절차를 각각 설계하세요. 데스크톱 클라이언트의 TUN 서비스 모드는 이 문서의 일반 프록시 유닛과 다릅니다.

구독 업데이트는 별도로 관리해야 합니다

전체 구독 YAML을 config.yaml로 다운로드해 두었다고 해서 엔진이 전체 설정을 주기적으로 다시 받는 것은 아닙니다. GUI 클라이언트에는 보통 설정 업데이트 작업이 있습니다. 헤드리스 환경에서는 전체 설정을 업데이트하는 스크립트를 사용할지, proxy-providers의 url, path, interval을 이용해 노드 제공자를 갱신할지 명확히 정해야 합니다.

노드 제공자 파일과 전체 설정은 구조가 다르므로 아무 구독 주소나 provider에 넣을 수 없습니다. provider 캐시 경로는 서비스가 쓸 수 있는 /var/lib/mihomo 아래에 두세요. 전체 설정을 업데이트할 때는 임시 파일로 다운로드해 형식을 확인한 다음 정식 파일로 교체하세요. 네트워크에서 받은 파일로 유일하게 실행 가능한 설정을 바로 덮어쓰지 마세요.

증상	우선 확인할 항목	해결 방법
address already in use	`sudo ss -lntp`	GUI 클라이언트나 다른 엔진 프로세스가 7890 / 9090 포트를 사용 중인지 확인하세요.
permission denied	설정 파일 읽기 권한, 캐시 경로, systemd 쓰기 제한	설정 파일은 읽기 전용으로 유지하고 캐시와 provider 파일은 쓰기 가능한 데이터 디렉터리로 옮기세요.
서비스가 계속 재시작됨	`journalctl -u mihomo -b`	로그에 처음 나타난 설정, 리소스 또는 권한 오류를 먼저 해결한 뒤 다시 시작하세요.
대시보드가 비어 있거나 404 오류가 발생함	`/etc/mihomo/ui/index.html`	빌드 결과물을 사용했는지, 디렉터리 구조가 올바른지, 서비스 계정에 파일 읽기 권한이 있는지 확인하세요.
대시보드에서 인증 실패 메시지가 표시됨	백엔드 주소, SSH 포워딩 포트, secret	프록시 포트가 아닌 컨트롤 포트를 사용하고 현재 설정의 키를 확인하세요.
프록시 요청은 성공하지만 직접 연결됨	연결 기록, 규칙 일치 결과, 정책 그룹 선택	규칙이 DIRECT와 일치하는지 확인하세요. 최소 테스트 설정에는 직접 연결 규칙만 있습니다.

업그레이드 및 롤백 확인

업그레이드 전에 기존 바이너리, 설정, 서비스 유닛을 보관하고 mihomo -v 출력도 기록하세요. 새 바이너리로 기존 설정을 먼저 -t 검사한 뒤 교체 및 재시작을 진행합니다. 업그레이드 후에는 서비스 상태, 7890 리스닝, 명시적 프록시 요청, 대시보드 연결 순으로 확인하세요. 문제가 있으면 네트워크 옵션을 여러 개 연달아 바꾸기보다 이전 바이너리와 호환되는 설정으로 복구하세요.

배포 완료의 최소 기준은 시스템 재부팅 후 서비스 상태가 active이고, 프록시 포트가 예상한 주소에서만 리스닝하며, 앱이 규칙에 따라 요청을 보내고, 보호된 관리 경로로 컨트롤 API에 접속할 수 있는 것입니다. 프로세스가 실행 중인지 확인하는 것보다 이 네 가지를 각각 검증하는 편이 확실합니다.