Linux 헤드리스 환경의 Clash Meta: 설치, systemd 상주, 구독 자동 갱신

헤드리스 Linux 에서 Clash Meta 를 쓰는 이유

헤드리스에는 트레이도 프로필 마법사도 없습니다. 동작은 모두 설정 파일에 적고 init 계열이 강제합니다. Meta 계열 코어는 많은 프로바이더가 기대하는 기능·룰 생태를 따라가기 쉬워 노트북 클라이언트와 데이터센터 릴레이에 같은 패턴을 재사용하기 좋습니다. Clash 는 로컬 포트(대개 HTTP/SOCKS 겸용 mixed-port)에서 대기하고 룰에 따라 아웃바운드로 넘깁니다. 외부 컨트롤러는 REST API 를 열어 상태 확인·프로필 전환·리로드 요청을 자동화할 수 있어 UI 가 SSH 뿐일 때 특히 유용합니다.

데스크톱 튜토리얼과 달리 서버 운영에서는 세 가지 책임이 반복됩니다. 첫째, 아키텍처에 맞는 실행 파일을 배포하고 프로토콜 변화에 맞춰 갱신할 것. 둘째, 디렉터리 권한은 최소 권한으로—전용 계정으로 실행하고 비밀을 전 세계 읽기 경로에 두지 말며, 쓰기가 필요한 provider 캐시를 정적 설정과 분리할 것. 셋째, systemd 와 묶어 크래시를 일시적 현상으로 만들고 네트워크 준비 의존을 명시하며 journalctl 로 관측 가능하게 할 것. 여기까지 잡으면 투명 포워딩이나 TUN 식 흡수는 단계적 확장이 되고, 일회성으로 약한 구성이 되기 어렵습니다.

전제: 사용자, 포트, 콜드 스타트

사이드 라우터 독자는 커널 포워딩·nftables·DHCP 와 조합할 수도 있으나, 본문은 「그 머신에서 믿을 만한 SOCKS/HTTP 출구」까지를 범위로 합니다. systemd 로 경로와 로그가 안정되면 게이트웨이 연동 후속이 훨씬 쉬워집니다.

mihomo(Clash Meta) 바이너리 설치

GitHub Releases 등에서 현재 버전을 받아 아키텍처에 맞는 아카이브나 단일 바이너리를 /usr/local/bin/mihomo 같은 표준 경로에 둡니다. 공개된 체크섬이 있으면 검증하세요. 배포판 패키지나 AUR 도 가능하나, 오래된 빌드는 새 YAML 키를 거부해 바로 종료하고 로그에는 원인 불명 서비스 실패로 보일 수 있습니다.

1. uname -m 출력과 릴리스 자산 이름을 대조합니다.
2. 공개된 다이제스트가 있으면 무결성을 확인합니다.
3. sudo install -m 0755 mihomo /usr/local/bin/mihomo 등으로 설치합니다.
4. 서비스 사용자로 mihomo -v 를 실행해 동작과 의존성을 확인합니다.

설정 디렉터리와 최소 스켈레톤

운영에서는 /etc/mihomo 또는 /var/lib/mihomo 에 config.yaml 을 두고 소유자를 맞춥니다. 리스너, 모드, 로그, 컨트롤러 바인딩, 불러올 proxy-providers·rule-providers 를 선언합니다. 서버에서는 secret 을 반드시 두고, 노출 모델을 이해하지 않는 한 127.0.0.1 에 바인딩하는 것이 안전합니다.

아래 스켈레톤은 관계를 보이는 최소 예입니다. 실서비스 전에 실제 정책 그룹·파서·룰로 확장하고 URL 은 프로바이더 것으로 바꾸세요.

port: 7890
socks-port: 7891
mixed-port: 7893
mode: rule
log-level: info
external-controller: 127.0.0.1:9090
secret: "change-me"

proxy-providers:
  airport:
    type: http
    url: "https://example.com/subscription"
    path: ./providers/airport.yaml
    interval: 3600
    health-check:
      enable: true
      interval: 600
      url: https://www.gstatic.com/generate_204

proxies: []

proxy-groups:
  - name: PROXY
    type: select
    use:
      - airport

rules:
  - MATCH,PROXY

interval 은 코어가 구독을 다시 받아 메모리에 병합하는 주기입니다. 헬스 체크로 노드를 적극 시험해 수동 로테이션을 줄입니다. 프로바이더가 provider 조각이 아니라 전체 프로필을 돌려주면 사용 중인 버전 문서에 맞춰 구조를 조정하세요. 필드 이름은 진화하고 엄격한 파서는 실패 시 바로 종료합니다.

systemd 유닛 작성

/etc/systemd/system/mihomo.service 를 만듭니다. Type=simple, WorkingDirectory 는 설정 루트, 실행은 mihomo -d /path. Restart=on-failure 와 적절한 RestartSec, 부하를 위한 LimitNOFILE 을 둡니다. PPPoE 나 VPN 으로 링크가 불안하면 After=network-online.target 에 맞추고, 배포판이 실제로 라우팅 가능해질 때까지 기다리는지 확인하세요. 그렇지 않으면 첫 수집이 레이스해 provider 가 비어 있을 수 있습니다.

[Unit]
Description=mihomo (Clash Meta) daemon
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=65535

[Install]
WantedBy=multi-user.target

1. sudo systemctl daemon-reload
2. sudo systemctl enable --now mihomo.service
3. systemctl status mihomo 로 active (running) 확인
4. YAML 오류, DNS 실패, 포트 충돌은 journalctl -u mihomo -e 로 추적

환경 변수로 CLI·자동화

mixed-port 가 로컬에서 대기하면 많은 도구가 http_proxy, https_proxy, all_proxy 를 해석합니다. curl, wget, 각종 패키지 매니저, 표준 변수를 지원하는 CI 에서 마찰이 가장 적은 경로입니다. 예(포트는 설정에 맞게 변경):

export http_proxy="http://127.0.0.1:7893/"
export https_proxy="http://127.0.0.1:7893/"
export all_proxy="socks5://127.0.0.1:7893/"

대문자만·소문자만 읽는 도구도 있습니다. 관리 트래픽은 직접 보내고 싶다면 전역 프로필에 쓰지 말고 셸 단위나 env http_proxy=... curl ... 처럼 명령 단위로 넘기세요. 프록시를 무시하는 앱은 proxychains·redsocks·TUN 층이 필요해 운영 면이 넓어지므로, 환경 변수로 부족할 때의 확장으로 보시면 됩니다.

구독 갱신과 설정 리로드

interval 로 provider 를 가져오면 대개 프로세스 전체를 재시작하지 않고 노드 목록을 갱신합니다. config.yaml 자체를 고치며(provider 추가, 룰 파일·리스너 변경 등) 완전 재로드가 필요하면 외부 컨트롤러 API 에 시크릿을 붙여 호출하는 패턴이 일반적입니다(경로는 릴리스마다 다르고 /configs PUT 이 흔함). 단순히 systemctl restart mihomo 도 되지만 짧은 끊김이 생깁니다.

선택으로 systemd timer 를 두고 시간마다 curl 스크립트로 강제 갱신할 수 있습니다. 프로바이더 엔드포인트가 불규칙하게 바뀌고 모든 interval 을 짧게 쓰기 싫을 때 유효합니다. 토큰은 모드 600 인 EnvironmentFile 에 두고 유닛에서 참조하며, 전 세계 읽기 가능한 헬퍼 스크립트에 넣지 마세요.

서버에서는 관측 가능성이 중요합니다. 구조화 로그 외에 컨트롤러 헬스 경로가 있으면 HTTP GET, 또는 mixed-port 경유 주기 curl 로 자동화 스택보다 먼저 provider 침묵을 잡으세요.

자주 묻는 질문

기동 직후 종료되며 «address already in use»

ss -lntp 나 lsof -i :7893 로 대기 소켓을 확인하세요. 수동 실행 잔재나 다른 프록시가 mixed/controller 포트를 잡았을 수 있습니다. 슈퍼바이저는 systemd 로 일원화하고 이중 포그라운드 실행을 중지하세요.

구독 다운로드가 항상 실패한다

같은 호스트에서 curl -v 로 DNS·TLS·경로를 분리합니다. 기존 프록시 없이는 닿지 않는 URL 이면 신뢰하는 머신에서 초기 providers 를 만들거나, 잠시 닿는 네트워크에서 받은 뒤 노드가 통하면 주기 갱신에 맡깁니다. 다른 호스트 이름 라인을 시도하는 편이 interval 만 믿고 막히는 것보다 콜드 스타트에 잘 통합니다.

provider 캐시 쓰기에서 권한 오류

실행 사용자와 디렉터리 소유자를 맞추고 WorkingDirectory 아래에 ./providers 를 만드세요. 문서 샘플을 root 소유로 복사한 채 비 root 로 돌리는 전형적인 실수입니다.

요약 체크리스트

데스크톱 클라이언트도 필요하다면

서버는 YAML 과 systemd 로 유지하고, 워크스테이션은 가져오기 보조가 있는 GUI 가 잘 맞습니다. 이 헤드리스 구성을 상류나 게이트웨이로 쓰면서 Windows·macOS 에서 쓰기 편한 통합 빌드가 필요하면 다운로드 페이지 도 함께 이용하세요.

Clash 를 무료로 다운로드하고 더 매끄러운 설정을 시작하세요