Home Assistant 2026.8 HTTP 설정 마이그레이션: YAML에서 UI로 변경된 이유와 대응 방법
Home Assistant를 2025.12.1에서 2026.10.4로 업그레이드한 뒤, HTTP YAML 설정을 정리하라는 문제 해결 알림을 만났다. Nginx Proxy Manager를 통해 외부에서 접속하고 있었기에, 설정을 지워도 되는지 먼저 확인할 필요가 있었다.
private ip 이지만 개인정보 보호를 위해 ip 주소는 xxx.xx.xx.x/xx 로 표시했음을 참고 바랍니다.
1. 기존 환경과 HTTP YAML 설정
| 항목 | 기존 환경 |
|---|---|
| Home Assistant | 2025.12.1 → 2026.10.4 |
| 리버스 프록시 | Nginx Proxy Manager |
| 외부 접속 | HTTPS 사용자 정의 도메인 |
| Home Assistant HTTP 포트 | 8123 |
| 신뢰할 프록시 대역 | xxx.xx.xx.x/xx |
요청은 외부 클라이언트 → HTTPS 도메인 → Nginx Proxy Manager → Home Assistant:8123 순서로 전달된다. 프록시가 전달하는 원래 클라이언트 주소를 처리하기 위해 configuration.yaml에 다음 설정을 사용했다.
# nginx 역방향 프록시를 위해 허용
http:
use_x_forwarded_for: true
trusted_proxies:
- xxx.xx.xx.x/xx- use_x_forwarded_for: true — 리버스 프록시가 전달하는 X-Forwarded-For 헤더를 사용하도록 설정한다.
- trusted_proxies — 이 헤더를 전달할 수 있도록 신뢰하는 프록시의 IP 주소 또는 CIDR 네트워크를 지정한다.
- xxx.xx.xx.x/xx — 이 환경에서 기존에 사용하던 내부 프록시 네트워크 대역이다. 다른 환경에 그대로 복사할 공통 기본값은 아니다.
trusted_proxies는 외부 클라이언트의 접속 허용 목록이 아니라, Home Assistant가 신뢰할 리버스 프록시의 목록이다. 실제 프록시 주소나 필요한 네트워크 범위만 지정해야 한다.
2. 2026.8에서 YAML이 UI로 바뀐 이유
Home Assistant 2026.8 공식 릴리스 노트는 더 쉽게 접근할 수 있는 사용 경험을 주요 방향으로 설명한다. HTTP 서버 설정도 웹 화면에서 관리할 수 있게 되었으며, 업그레이드 후 첫 시작 때 기존 YAML 값이 UI로 자동으로 이전된다.
이제 관리 위치는 설정 → 시스템 → 네트워크 → HTTP 서버다. 포트, 수신 주소, SSL/TLS, X-Forwarded-For 신뢰, 신뢰할 프록시 등의 항목을 이 화면에서 확인하고 수정한다.
사용자 입장에서의 의미는 분명하다. 설정 파일의 키를 직접 편집하던 작업을 UI에서 할 수 있고, 서버 설정 변경 후 접속 여부를 확인하는 복구 절차도 함께 제공된다. 이는 공식 문서에 설명된 기능을 바탕으로 정리한 운영상의 장점이다.
왜 기존 http: 블록을 제거해야 할까?
캡처는 못했지만 당시 화면의 경고는 마이그레이션 후 HTTP YAML 구성이 무시됨이라는 내용이었다. configuration.yaml의 HTTP 설정이 이미 이전되었으므로 남은 http: 블록을 제거하고 UI에서 관리하라는 안내다. 화면에는 2027.2.0 전에 해결하라는 기한도 표시되었다.
여기서 중요한 것은 마이그레이션이 끝난 YAML은 현재에도 적용되지 않는다는 점이다. YAML을 그대로 남겨 두면 파일을 수정해도 실제 서버 설정이 바뀌지 않아 운영자가 혼동할 수 있다. 따라서 UI에 이전된 값을 확인한 다음 오래된 설정을 정리한다.
이 경고는 Nginx Proxy Manager나 리버스 프록시 기능이 제거된다는 뜻이 아니다. 2027.2.0 표기는 당시 문제 해결 화면에 나온 기존 YAML 방식의 지원 종료 안내로 이해해야 한다. 경고 유형과 처리 절차는 공식 HTTP YAML 마이그레이션 문서에서 확인할 수 있다.
3. UI로 이전된 실제 값 비교
기존 YAML을 지우기 전에 설정 → 시스템 → 네트워크 → HTTP 서버로 이동해 값을 비교한다. 기록해 둔 HTTP 서버 스크린샷에는 다음과 같이 표시되어 있었다.
| 확인 항목 | 기존 YAML 또는 기존 값 | HTTP 서버 UI |
|---|---|---|
| 서버 포트 | 기존 사용 포트 8123 (제시한 YAML에는 별도 server_port 없음) |
8123 |
| X-Forwarded-For 신뢰 | use_x_forwarded_for: true | 활성화 |
| 신뢰할 수 있는 프록시 | xxx.xx.xx.x/xx | xxx.xx.xx.x/xx |
기존 포트 8123을 80으로 바꿔야 할까?
공식 릴리스 노트에 따르면 2026.8부터 새로 설치하는 Home Assistant OS는 기본 포트 80을 사용하지만, 기존 설치는 사용하던 포트를 유지한다. Home Assistant Container의 기본 포트는 8123이다.
따라서 이번 환경에서는 8123을 유지하면 된다. 마이그레이션을 완료하려고 포트를 변경할 필요는 없다. Nginx Proxy Manager의 대상 포트도 실제 Home Assistant 포트와 일치해야 한다.
4. 기존 YAML 정리와 검증 순서
UI 값이 올바르게 이전되었는지 확인했다면, configuration.yaml에서 앞서 제시한 http: 블록과 해당 설명용 주석을 제거한다. 다른 최상위 설정과 들여쓰기를 건드리지 않도록 주의한다.
변경 전
# nginx 역방향 프록시를 위해 허용
http:
use_x_forwarded_for: true
trusted_proxies:
- xxx.xx.xx.x/xx
변경 후
# HTTP 서버 설정은 설정 → 시스템 → 네트워크에서 관리
# 기존 http: 블록은 제거
위 주석은 설명을 위한 예시이며, 실제 파일에는 남기지 않아도 된다. 빈 http: 키를 남기는 대신 블록 전체를 제거한다.
- 변경 전에 Home Assistant 전체 백업을 만든다.
- HTTP 서버 UI에서 포트 8123, X-Forwarded-For 활성화, trusted_proxies xxx.xx.xx.x/xx 를 확인한다.
- configuration.yaml의 기존 http: 블록을 제거하고 저장한다.
- 제공되는 구성 검사 기능으로 설정을 확인한 뒤 Home Assistant를 재시작한다.
- 기존 리버스 프록시 도메인으로 접속해 로그인 및 화면 동작을 확인한다.
- 설정 → 시스템 → 문제 해결에서 해당 경고가 해제되었는지 확인한다.
UI의 저장 버튼은 별도로 주의하자
공식 HTTP 문서에 따르면 UI에서 HTTP 서버 설정을 저장하면 Home Assistant가 재시작된다. 이후 관리자가 새 설정을 확인해야 하며, 5분 안에 확인하지 않으면 이전 설정으로 자동 복구된다.
이번처럼 이미 이전된 값이 일치하고 YAML의 중복 블록만 정리하는 경우에는 UI 값을 불필요하게 바꿀 이유가 없다. 단순 확인과 설정 변경·저장을 구분해서 진행한다.
5. 리버스 프록시와 백업에서 주의할 점
프록시 설정은 앞으로 UI에서 관리한다
리버스 프록시를 사용하는 경우 X-Forwarded-For 신뢰와 실제 프록시의 IP 또는 CIDR 대역을 함께 확인한다. 마이그레이션 후 무시되는 YAML에 trusted_proxies를 다시 추가해도 실제 설정을 바꾸는 방법이 되지 않는다.
CIDR은 호스트 주소가 아닌 네트워크 주소로 입력한다. xxx.xx.xx.x/xx 는 이 환경의 기존 값이며, 다른 설치에서는 실제 네트워크 구성을 확인해야 한다. 자세한 설명은 공식 리버스 프록시 문서를 참고한다.