用 Git 版控你的 HA 設定：從零到「改完自動提交」

charles · 發表於 3 天前

「我昨天改了什麼？」
「這個自動化以前是怎麼寫的？」
「我把設定改壞了，能不能回到三天前？」

這三個問題 Git 都能回答，而且設定一次就一勞永逸。

為什麼備份不夠

HA 的備份是整包快照。你想知道「哪一行改了」它幫不上忙，
而且還原是全有全無 —— 不能只還原某個自動化。

Git 記的是每一次改動，可以：

看任兩個時間點之間改了哪幾行
只還原某一個檔案
寫下「為什麼改」（提交訊息）
在不同機器間同步設定

第一步：裝 Terminal 附加元件

設定 → 附加元件 → 附加元件商店 → Advanced SSH & Web Terminal

裝好後在設定裡把 Protection mode 關掉（不然它只能看到自己的容器）。

第二步：先寫 .gitignore（這步最重要）

千萬不要在寫 .gitignore 之前就 git add。
一旦密碼進了歷史紀錄，要清掉很麻煩。

在 /config 建立 .gitignore：

# 憑證與密碼 —— 絕對不能進版控
secrets.yaml
.storage/
*.key
*.pem
*.crt
ssh/
# 資料庫與日誌
*.db
*.db-*
*.log
home-assistant.log*
home-assistant_v2.db*
# 快取與暫存
__pycache__/
.cloud/
.uuid
tts/
deps/
image/
backups/
media/
www/community/
# 這個要不要納入自己決定
# custom_components/ （HACS 裝的東西，通常不用進版控）

複製代碼

為什麼 .storage 不能進版控

.storage 裡面有所有整合的存取權杖、雲端登入資訊、使用者密碼雜湊。
它是明文 JSON。進了版控就等於把家裡的鑰匙貼出去。

但這也代表：Git 不能取代備份。
.storage 只能靠 HA 的備份機制保護。兩個都要做。

第三步：初始化

cd /config
git init
git config user.name "charles"
git config user.email "charles@example.com"
# 先確認 .gitignore 有生效，再 add
git add .gitignore
git status # ← 仔細看清單裡有沒有 secrets.yaml 或 .storage
git add .
git commit -m "初始設定"

複製代碼

git status 那一步不要跳過。
我第一次做的時候，.storage 因為 .gitignore 少了斜線而被加進去了。

第四步：推到遠端（可選但建議）

本機的 Git 遇到硬碟壞掉一樣沒了。推到遠端才有異地保護。

重要：倉庫一定要設成私有（Private）。

# GitHub 建一個 private repo 之後
git remote add origin git@github.com:你的帳號/ha-config.git
git branch -M main
git push -u origin main

複製代碼

用 SSH 金鑰比較方便：

ssh-keygen -t ed25519 -C "ha-config" -f /config/ssh/gh_key
cat /config/ssh/gh_key.pub # 把這串貼到 GitHub 的 Deploy Keys

複製代碼

# /config/ssh/config
Host github.com
IdentityFile /config/ssh/gh_key
IdentitiesOnly yes

複製代碼

記得 chmod 600 /config/ssh/gh_key，權限太開 ssh 會拒絕。

第五步：讓它自動提交

手動提交一定會忘記。做一個腳本每天自動跑：

# /config/scripts/git_autocommit.sh
#!/bin/bash
cd /config || exit 1
# 沒有變更就什麼都不做（避免一堆空提交）
if [ -z "$(git status --porcelain)" ]; then
exit 0
fi
git add -A
git commit -m "自動提交 $(date '+%Y-%m-%d %H:%M')"
# 推不上去也不要讓腳本失敗（網路可能暫時不通）
git push origin main || echo "push 失敗，下次再試"

複製代碼

chmod +x /config/scripts/git_autocommit.sh

複製代碼

接進 HA：

shell_command:
git_autocommit: "bash /config/scripts/git_autocommit.sh >> /config/git.log 2>&1"

複製代碼

automation:
- alias: 每天自動提交設定
triggers:
- trigger: time
at: "03:30:00"
actions:
- action: shell_command.git_autocommit
mode: single

複製代碼

把輸出導到 git.log 是關鍵。
shell_command 失敗的話你只會看到一個 return code，什麼線索都沒有。

日常怎麼用

看最近改了什麼

git log --oneline -20
git log --stat -5 # 附帶哪些檔案改了幾行

複製代碼

看某一次改了哪幾行

git show <commit>
git show <commit> -- automations.yaml # 只看某個檔案

複製代碼

比較兩個時間點

git diff HEAD~5 HEAD -- automations.yaml

複製代碼

還原單一檔案到三天前

git log --oneline --since="4 days ago" --until="3 days ago"
git checkout <commit> -- automations.yaml
# 然後在 HA 重新載入自動化

複製代碼

這個是 Git 真正勝過備份的地方 ——
只還原一個檔案，其他設定完全不動。

找出某一行是什麼時候改的

git log -S "binary_sensor.走道感應" --oneline

複製代碼

會列出所有「增加或刪除這段文字」的提交。
查「這個實體到底哪時候改名的」超好用。

進階：用分支試新東西

要做一個大改動（例如把 !include 改成 packages），先開分支：

git checkout -b try-packages
# 改一堆東西，重啟測試
# 成功的話
git checkout main
git merge try-packages
# 失敗的話
git checkout main
git branch -D try-packages # 整個丟掉，主線完全不受影響

複製代碼

幾個實際踩過的坑

1. 換行符號

在 Windows 上編輯過的檔案會變成 CRLF，Linux 上的 HA 有時候會抱怨。
設定一下：

git config core.autocrlf input

複製代碼

2. automations.yaml 每次都整個變

UI 編輯器存檔時會重新排序整個檔案，diff 會很醜。
沒有好解法，習慣就好 —— 或者改用手寫 YAML 放在 packages 裡。

3. 提交訊息寫「更新」等於沒寫

# 沒用
git commit -m "更新"
# 有用
git commit -m "浴室感應燈改成 restart，修正人還在裡面就關燈的問題"

複製代碼

三個月後只有第二種救得了你。

4. 不要把 Git 當備份

再講一次：.storage 不在版控裡。
純靠 Git 還原的話，所有整合都要重新設定、所有實體 ID 會跑掉。

Git 管「你寫的邏輯」，HA 備份管「系統狀態」。兩個都要。

---

我自己用了一年多，最常用的其實不是還原，是 git log -S
—— 「這個奇怪的設定到底是誰、什麼時候、為什麼加的」。

答案通常是三個月前的我，而且當時有寫原因。感謝當時的自己。

		自動登入	找回密碼
密碼			立即註冊

用 Git 版控你的 HA 設定：從零到「改完自動提交」

瀏覽過的版塊