Gumu's treasure box
IT

Home Assistant 아이콘 색 하나 바꾸려다 백업 파일을 뜯어본 날

2026. 6. 5. · Gugu

Home Assistant 백업 파일을 조심스럽게 살펴보는 작업대

Home Assistant를 쓰다 보면 가끔 아주 작은 것이 신경 쓰인다. 기능이 안 되는 것도 아니고, 자동화가 깨진 것도 아닌데 화면을 볼 때마다 괜히 눈에 걸리는 것들이다.

이번에는 iOS 테마의 아이콘 색이 그랬다. 불이 꺼진 상태의 아이콘 색이 조금 진하게 보여서, 연한 회색으로 맞추고 싶었다. 정확히는 #333333 쪽으로 되어 있던 값을 #6b7280 정도로 바꾸고 싶었다.

처음 생각은 간단했다.

테마 YAML 파일 하나 열어서 색상 값만 바꾸면 끝날 줄 알았다.

그런데 Home Assistant OS에서는 이 작은 수정도 생각보다 돌아가는 길이 필요했다. 나중에 또 비슷한 일을 하게 될 것 같아서 정리해둔다.

먼저 백업부터 만들었다

Home Assistant는 집 자동화의 중심이라서 아무 파일이나 바로 건드리면 안 된다. 특히 HAOS 쪽은 예전에 복구하느라 고생한 적이 있어서 더 조심해야 한다.

그래서 제일 먼저 전체 백업을 만들었다. 백업 이름은 대충 알아보기 쉽게 pre-theme-gray-icons-2026-05-12 같은 식으로 잡았다.

작업 목표는 딱 하나였다.

/config/themes/ios-themes/ios-themes.yaml 안에 있는 iOS light theme의 아이콘 기본 색을 바꾸는 것.

대상은 이런 값들이었다.

복잡한 자동화나 저장소 쪽은 건드리지 않고, 테마 파일만 바꾸는 방향으로 잡았다.

API로 바로 바꾸면 되지 않을까?

처음에는 Home Assistant API로 해결할 수 있을 줄 알았다. Long-Lived Access Token을 만들면 Core API와 WebSocket에는 접근할 수 있다.

실제로 /api/config 같은 기본 API는 잘 됐다. WebSocket으로 상태를 보는 것도 가능했다.

그런데 Supervisor 쪽 REST API, 예를 들면 /api/hassio/* 계열은 401이 났다. 토큰이 있는데도 안 되는 것이다. 처음에는 권한을 잘못 줬나 싶었는데, Home Assistant에서는 Core API와 Supervisor API의 접근 방식이 조금 다르다.

다행히 완전히 막힌 것은 아니었다. WebSocket의 supervisor/api 명령을 쓰면 Supervisor 정보나 백업 목록 같은 것은 확인할 수 있었다.

즉 정리하면 이렇다.

이때 간단한 WebSocket helper를 만들어두니 편했다. Home Assistant는 웹 UI만으로는 확인이 번거로운 것들이 있어서, 이런 작은 스크립트가 꽤 도움이 된다.

Studio Code Server add-on도 만져봤다

다음으로 생각한 방법은 Studio Code Server add-on이었다. HAOS에서 VS Code add-on을 띄워두면 /config를 볼 수 있으니, 거기서 파일을 바꾸면 될 것 같았다.

하지만 원격에서 자동으로 명령을 넣기에는 애매했다. add-on의 실행 상태, 옵션, 재시작 여부는 확인할 수 있었지만, 내가 원하는 방식으로 stdin을 넣거나 원격 명령을 바로 실행하는 구조는 아니었다.

임시로 init_commands를 넣고 add-on을 재시작하는 방법도 시도했지만, 테마 파일 수정에는 실패했다. 게다가 add-on이 잠깐 error 상태로 들어가기도 했다.

다행히 stop/start를 해주면 startup을 거쳐 다시 started로 돌아왔다. 그래도 이 방법은 좋은 길이 아니었다.

작은 색상 하나 바꾸려고 add-on을 흔드는 건 좀 찝찝했다.

돌아 돌아 백업 파일까지 갔다

그래서 그때 선택한 방법은 백업 파일을 내려받아서 수정한 뒤 다시 올리는 것이었다.

지금 다시 생각하면 이게 정답이라기보다는, SMB나 SSH로 /config에 바로 접근할 길을 먼저 만들어두지 않아서 너무 멀리 돌아간 쪽에 가깝다. 테마 YAML 하나 바꾸는 일이라면 사실 백업을 뜯고 다시 묶을 일이 아니다. Samba share나 SSH add-on으로 실제 파일을 열어서 수정하고, 저장한 뒤 테마만 다시 불러오는 게 훨씬 자연스럽다.

그래도 이미 백업 파일까지 간 김에, 어디서 문제가 생겼는지 기록해둔다.

흐름은 이렇다.

  1. Home Assistant에서 전체 백업을 만든다.
  2. 백업 tar 파일을 내려받는다.
  3. 그 안에 있는 homeassistant.tar.gz를 꺼낸다.
  4. homeassistant.tar.gz 안의 /config/themes/ios-themes/ios-themes.yaml만 수정한다.
  5. 수정한 homeassistant.tar.gz를 원래 백업 tar 구조에 다시 넣는다.
  6. 새 백업으로 업로드한다.
  7. partial restore로 Home Assistant 설정만 복원한다.

말로 쓰면 조금 길지만, 핵심은 단순하다.

원본 백업의 전체 구조는 최대한 그대로 두고, 그 안의 homeassistant.tar.gz만 바꾸는 것이다.

처음에는 부분 백업처럼 보이게 하려고 backup.json에서 addons나 folders 정보를 줄이는 방식도 생각했다. 하지만 그렇게 만든 tar는 업로드할 때 Unknown error가 났다.

반대로 원본 전체 백업 구조를 유지하고 homeassistant.tar.gz만 교체하니 업로드가 성공했다.

이 부분이 중요했다.

Home Assistant 백업은 그냥 압축 파일처럼 보이지만, Supervisor가 기대하는 구조가 있다. 그래서 괜히 깔끔하게 줄이려고 하기보다 원래 모양을 유지하는 것이 안전했다.

macOS tar가 만든 함정

여기서 한 번 더 걸렸다.

처음에는 macOS에서 기본 tar를 써서 homeassistant.tar.gz를 다시 묶었다. 그런데 업로드하거나 복원 검증을 할 때 이상한 에러가 났다.

에러 메시지만 보면 백업 비밀번호가 틀린 것처럼 보였다.

대충 이런 느낌이었다.

Invalid password for backup

처음 보면 당연히 비밀번호 문제라고 생각하게 된다. 그런데 실제 원인은 비밀번호가 아니었다.

macOS의 tar 또는 bsdtar가 압축을 만들면서 ._로 시작하는 AppleDouble 파일을 같이 넣을 수 있다. macOS에서 파일 메타데이터를 보존하려고 만드는 파일인데, Linux나 HAOS 입장에서는 필요 없는 파일이다.

이게 백업 tar 안에 섞이면서 Supervisor의 검증이 꼬인 것으로 보인다.

이 구간에서의 결론은 간단했다.

HAOS 백업 tar를 수정할 때는 macOS tar로 새로 묶지 않는 것이 좋다.

대신 Python의 tarfile을 사용해서 원본 멤버 순서와 이름을 최대한 유지하면서 다시 만들었다. 그렇게 하니 이상한 ._ 파일도 들어가지 않고, 백업 업로드와 partial restore가 정상적으로 진행됐다.

하지만 이건 어디까지나 이미 백업 tar를 직접 만져야 하는 상황에서의 이야기다.

이건 꽤 기억해둘 만하다.

에러 메시지는 비밀번호 문제처럼 보여도, 실제로는 압축 파일 안에 들어간 불필요한 macOS 메타데이터 때문일 수 있다.

복원 중에는 잠깐 끊길 수 있다

partial restore를 호출했을 때도 조금 당황스러운 장면이 있었다.

WebSocket이 끊기거나 바이너리 프레임 디코딩 오류처럼 보이는 메시지가 나왔다. 처음에는 복원이 실패한 줄 알았다.

그런데 실제로는 복원이 진행 중이었다.

Home Assistant가 설정을 복원하면서 잠깐 웹 응답이 끊겼고, 20~30초 정도 지나니 다시 살아났다. 이후에는 다음 순서로 확인했다.

  1. /api/config로 Home Assistant가 다시 응답하는지 확인
  2. frontend/reload_themes 호출
  3. frontend/get_themes로 테마 값 확인

최종적으로 iOS light theme 14개에서 꺼진 상태 아이콘 색 관련 값들이 #6b7280으로 바뀐 것을 확인했다. 남아 있는 #333333 값도 없었다.

작업은 성공했다.

정리

이번 작업은 처음에는 정말 작은 수정이었다.

아이콘 색 하나 바꾸는 일.

그런데 실제로는 다음을 한 번씩 다 지나갔다.

하고 나니 별것 아닌 것처럼 보이지만, 중간에는 꽤 헷갈렸다. 특히 Invalid password for backup처럼 보이는 에러가 실제로는 비밀번호 문제가 아니었다는 점이 제일 함정이었다.

그래서 진짜 결론은 이쪽에 가깝다.

앞으로 HAOS에서 /config 아래 파일을 고칠 일이 있으면, 백업 tar부터 뜯지 말고 먼저 파일 접근 경로를 제대로 마련해두는 게 좋겠다.

  1. 먼저 전체 백업은 만든다.
  2. 가능하면 SMB나 SSH로 /config에 직접 접근해서 수정한다.
  3. 수정 후에는 frontend/reload_themes처럼 필요한 부분만 다시 불러온다.
  4. 백업 tar를 직접 수정하는 방식은 마지막 수단으로 둔다.
  5. 정말 tar를 만져야 한다면 macOS tar로 다시 묶지 말고, 원본 구조를 유지하면서 조심스럽게 처리한다.
  6. 복원 후에는 UI만 보지 말고 API로 값까지 확인한다.

Home Assistant는 집에서 계속 돌아가는 시스템이라서, 작은 수정도 조심해서 나쁠 것이 없다.

나중에 또 “색 하나만 바꾸면 되겠지” 하고 시작한다면, 이번에는 백업 파일부터 해부하지 말고 SSH나 SMB부터 열어보자. 그게 훨씬 덜 무섭고, 훨씬 덜 돌아가는 길이다.

Comments

댓글

GitHub 로그인 후 댓글을 남길 수 있습니다.

댓글을 불러오는 중입니다.