IOT/Home Assistant

Home Assistant 외부 접속 중 untrusted proxy 오류 해결하기

wookingwoo 2025. 11. 16. 00:34

스마트홈을 구축하면서 가장 중요한 요소 중 하나는 외부에서도 안전하게 시스템에 접근할 수 있는가이다.

나는 Home Assistant(이하 HA)를 외부에서 접속하기 위해 Nginx Proxy Manager(NPM) 를 이용한 Reverse Proxy 구조를 구성했고, 외부 접근은 특정 IP만 허용하는 화이트리스트 방식으로 제한하고 있었다.

 

 

이 구조는 한동안 문제없이 안정적으로 동작했다. 그러나 어느 날 갑자기 Home Assistant UI에 접속할 수 없게 되었고, 로그에는 다음 메시지가 끊임없이 출력되기 시작했다.

 

ERROR (MainThread) [homeassistant.components.http.forwarded]
Received X-Forwarded-For header from an untrusted proxy 172.*,*,* (ip는 마스킹처리함)

 

 

분명 trusted_proxies 설정에 Nginx Proxy Manager의 IP를 등록해 두었는데도 발생한 오류였다.
무엇이 바뀐 걸까?

 

 

이 글은
문제 발생 → 원인 분석 → 네트워크 구조 이해 → 해결 → 보안 관점에서의 통찰
까지의 과정을 정리한 기록이다.

 

 

 

1. 내가 구성했던 외부 접속 구조

내 Home Assistant 외부 접속 구조는 다음과 같았다.

 

외부 접속 (특정 Allowed IP만 허용)
        ↓
[Nginx Proxy Manager]
        ↓
https://my-domain.com → Home Assistant

 

구성의 핵심은 다음과 같다.

  • NPM에서 도메인별 SSL 인증서 관리
  • 외부 접근은 화이트리스트 기반으로 특정 IP만 허용
  • Home Assistant와 NPM은 동일 장비 내부, Home Assistant OS의 Add-on(Docker) 으로 실행
  • HA는 프록시 뒤에서 동작하므로 use_x_forwarded_for: true 사용

 

즉, 외부에서 Home Assistant로 직접 접근하는 경로는 존재하지 않고,
모든 요청은 반드시 NPM → Home Assistant 를 거치도록 설계된 구조였다.

 

 

 

2. 문제 상황 — 갑자기 접속 불가 & untrusted proxy 오류

기존 Home Assistant 설정은 다음과 같았다.

http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 192.168.*.*   # 공유기 (ip 주소는 마스킹 처리)
    - 172.*.*.1    # 과거 NPM 컨테이너 IP (ip 주소는 마스킹 처리)

 

 

그런데 어느 순간부터 다음 IP 에서 요청이 들어오기 시작했다.

172.*.*.2

 

 

문제는 이 IP가 trusted_proxies 에 등록되어 있지 않았다는 점이다.
그 결과 Home Assistant는 해당 요청을 신뢰할 수 없는 프록시에서 온 요청으로 판단했고,
모든 접근을 차단했다.

 

처음에는 다음과 같은 의심이 들었다.

  • 외부에서 허용되지 않은 IP로 접근한 것 아닐까?
  • NPM 화이트리스트 설정이 깨졌나?
  • 혹시 보안 공격인가?

하지만 로그를 자세히 분석해보니,
문제는 외부가 아니라 Home Assistant 내부 네트워크에서 발생하고 있었다.

 

 

 

3. Root Cause — Nginx Proxy Manager Add-on의 내부 IP 변경

Home Assistant OS에서 Add-on은 Supervisor가 관리하는 Docker 컨테이너다.
이 Add-on 컨테이너들은 모두 172.*.x.x 대역의 내부 네트워크에서 자동으로 IP를 할당받는다.

즉, NPM은 다음과 같이 실행될 수 있다.

  • 어느 날은 172.*.*.1 (ip 주소는 마스킹 처리)
  • 다음 재시작 후에는 ``172.*.*.2` (ip 주소는 마스킹 처리)

실제로 다음과 같은 이벤트가 발생하면 컨테이너가 재생성(recreate) 되며 IP가 바뀐다.

  • NPM Add-on 업데이트
  • Add-on 재시작
  • Home Assistant 또는 Supervisor 업데이트
  • 시스템 리부팅
  • 설정 변경 후 Add-on 재생성

이번 경우도 마찬가지였다.
기존에 동작하던 NPM 컨테이너가 제거되고,
새로운 컨테이너가 172.*.*.2 IP로 생성된 것이다.

하지만 Home Assistant는 여전히 이전 IP만 trusted proxy로 알고 있었기 때문에, 새로운 NPM을 신뢰하지 않는 프록시로 판단했고 접근을 차단했다.

 

 

 

4. 왜 X-Forwarded-For 를 신뢰하지 않으면 접속이 막힐까?

Home Assistant는 X-Forwarded-For 헤더를 매우 엄격하게 검증한다.
이 헤더는 위조가 가능하기 때문에, 신뢰된 프록시에서 온 요청만 인정한다.

내 환경에서는 다음이 필수 조건이었다.

  • NPM이 외부 접근을 화이트리스트로 제한
  • HA는 NPM이 전달하는 실제 클라이언트 IP 를 기준으로 인증 및 접근 제어

 

“NPM이 전달하는 클라이언트 IP를 HA가 신뢰해야만 정상 동작하는 구조”


 

프록시를 신뢰하지 않으면 Home Assistant는 다음과 같이 동작한다.

  • 클라이언트 IP를 올바르게 인식하지 못함
  • 로그인 시도 차단
  • UI 접근 불가
  • 로그에 untrusted proxy 경고 반복 출력

 

결국,
HA 입장에서는 ‘누가 문지기인지 모르는 상황’이 되어버린 것이다.

 

 

 

5. 해결 — 개별 IP 대신 네트워크 대역(CIDR) 등록

Add-on 컨테이너의 IP가 고정되지 않는 구조에서
IP를 하나씩 trusted_proxies 에 추가하는 방식은 근본적인 해결책이 아니다.

그래서 Supervisor가 사용하는 내부 네트워크 대역 전체를 등록했다.

 

http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 192.168.*.* #  (ip 주소는 마스킹 처리)
    - 172.*.0.0/16 #  (ip 주소는 마스킹 처리)

 

 

172.*.0.0/16 은 Home Assistant OS 내부에서만 사용하는 전용 네트워크이므로
보안적으로도 외부 노출 위험이 없다.

이 설정을 적용하자,
즉시 모든 문제가 해결되었고 외부 접속도 정상적으로 복구되었다.

 

 

 

6. 기술적 통찰 — 왜 이 문제는 반복적으로 발생할 수밖에 없는가?

1) Supervisor의 Add-on 재생성 정책

Home Assistant OS는 Add-on 컨테이너를 항상 재생성(recreate) 한다.
→ IP가 유지될 것을 기대하면 안 된다.

 

2) Reverse Proxy 환경에서의 보안 기본 원칙

X-Forwarded-For 는 위조 가능하다.
→ 반드시 신뢰 가능한 프록시 IP만 허용해야 한다.

 

 

3) 프록시 + IP 기반 접근 제어의 민감성

  • 외부 접근은 프록시가 제한
  • HA는 프록시가 전달한 IP를 신뢰
  • 프록시 IP가 바뀌면 전체 시스템이 마비될 수 있음

 

4) CIDR 대역 등록은 사실상 표준 해법

Home Assistant 공식 문서에서도
Add-on 기반 프록시는 개별 IP가 아닌 네트워크 대역 등록을 권장한다.

 

 

 

7. 배운 점

이번 문제를 통해 얻은 교훈은 명확하다.

  • Home Assistant Add-on은 Docker 컨테이너다 → IP는 고정되지 않는다
  • Reverse Proxy 뒤에서는 trusted_proxies 설정이 필수다
  • 외부 접근 보안은 프록시와 HA 간의 신뢰 관계가 핵심이다
  • 스마트홈은 단일 서비스가 아니라 여러 네트워크 레이어의 조합이다

 

 

8. 마무리

겉으로 보면 단순히

“IP 하나가 바뀌어서 생긴 오류”

 

 

처럼 보일 수 있지만,
실제로는 Home Assistant의 보안 모델, Reverse Proxy의 역할,
Supervisor의 컨테이너 관리 방식이 모두 얽힌 문제였다.

 

 

결론적으로,

스마트홈 시스템을 안전하게 외부에 공개하려면
네트워크 구조와 보안 정책을 구조적으로 이해하고 설계해야 한다.

 

 

이번 경험을 통해 Home Assistant 내부 동작과 Nginx Proxy Manager 연동 구조를 훨씬 깊이 이해하게 되었다~