歷史數據、Recorder 與資料導出

為什麼要學這個

前面幾章你已經把裝置接上、把自動化跑起來了。接下來會發生兩件事，而且幾乎一定會發生：

第一件：某天你想知道「上禮拜三晚上到底是誰把陽台的燈開了一整晚」，或是「這個月冷氣到底吃了多少電」。你點進去看，發現三天前的資料還在，三個月前的卻不見了 —— 但奇怪的是，用電量卻看得到去年的。這不是壞掉，是設計，這章會講清楚為什麼。

第二件：某天你的 Home Assistant 突然變得超慢，點一個燈要等三秒，重開機要跑十分鐘。八成是資料庫肥到不行了。如果你跑在 Raspberry Pi 的記憶卡上，再放著不管，下一步就是記憶卡直接掛掉，整台重灌。

讀完這一章，你會有這些能力：

• 分得清「歷史（History）」跟「活動（Activity，舊稱 Logbook）」該去哪一個找答案。
• 知道記錄器（Recorder）把資料放在哪個檔案、預設留幾天、大概會長到多大。
• 會用 include / exclude 把吵死人的實體踢出資料庫。
• 能從畫面上按幾下就下載 CSV，丟進 Excel 或 Google 試算表畫圖。
• 知道資料庫肥了怎麼清、壞了怎麼救、要長期保存該搬去哪。

備份的通則已經在 第 9 章 講過，這裡只補「備份跟資料庫的糾纏」那一段。實體命名與 entity_id 的規矩請看 第 4 章，這章的排除設定會大量用到。

歷史與活動：兩個側欄項目，兩種問題

側欄上會看到兩個長得有點像的東西：歷史（History） 跟 活動（Activity）。很多人以為是同一個，其實回答的是完全不同的問題。

用生活化的講法：歷史是體檢報告的曲線圖，活動是護理站的交班紀錄。前者告訴你「數字怎麼變的」，後者告訴你「誰做了什麼」。

還有一個實務上很重要的差別：活動預設會自動略過帶單位的感測器。溫度、濕度、功率這種每隔幾秒就跳一次數字的東西，如果全丟進活動，畫面會被洗版到完全沒法看，所以官方直接把「有單位的 sensor」排除在活動之外。想看它們就去歷史。

記錄器（Recorder）：所有歷史的源頭

歷史和活動自己不存資料，它們只是「顯示器」。真正在背後把每一次狀態變化寫進硬碟的，是叫做 記錄器（Recorder） 的整合。

你沒有裝過它，因為它一開始就開著了。官方文件寫得很清楚：歷史整合要靠記錄器來存資料、而且兩邊共用同一個資料庫設定；而只要你的 configuration.yaml 裡有那行 default_config:（全新安裝預設就有），這些東西就自動啟用。所以「我從來沒設定過，為什麼會有歷史？」的答案就是這一行。

資料存在哪個檔案

預設情況下，Home Assistant 用的是 SQLite，資料庫就是設定資料夾裡的一個檔案：

/config/home-assistant_v2.db

就這麼一個檔案，你全部的歷史都在裡面。它跟著 configuration.yaml 躺在同一個資料夾，也因此會被完整備份一起包走（後面會講這件事的麻煩）。

預設留幾天

記錄器有一個叫 purge_keep_days 的設定，預設值是 10 天。也就是說，超過 10 天的「逐筆狀態變化」會被自動刪掉。

配合它的還有兩個預設開著的開關：

資料庫會長多大

沒有標準答案，因為它完全取決於你有多少實體、以及那些實體多吵。但可以給你一個抓感覺的方式：

關鍵不是「幾個實體」，而是「每個實體每天寫幾筆」。一顆燈一天可能只變化 6 次；一個逐秒回報的功率插座，一天可以寫進去好幾萬筆。單一個這種插座就足以讓資料庫比其他所有東西加起來還大。

想看自己現在多大，官方文件給了兩條路：

後面的「SQL 整合」那節還會教你把這個數字做成一個感測器，直接釘在儀表板上盯著它，不用每次都翻進系統資訊。

長期統計：為什麼去年的電費看得到，去年的開關看不到

這是整章最容易讓人困惑、也最值得搞懂的一段。

剛剛說預設只留 10 天。但你打開能源儀表板，去年的用電量明明還在。這不是 bug，是因為 Home Assistant 同時在存兩種完全不同的東西。

官方的資料文件把它講得很直白：狀態表是「把發生的事原樣記下來」，統計則是把資料壓成固定間隔的摘要，所以一天只產生 24 筆，用一點點空間就能存好幾年。

哪些實體會有長期統計

只有帶「狀態類別（state_class）」的實體才會進統計表。三種狀態類別分別代表什麼、怎麼設，第 17 章 已經整理成一張表講得很細了，這裡只講跟「留多久」有關的那一面：

所以答案就出來了：電表有 total_increasing，所以去年的用電活著；一顆燈的「開／關」不是數值、沒有狀態類別，所以它只活 10 天。

這也解釋了另一個常被誤會的現象：在歷史頁面把時間往回拉很遠的時候，曲線會突然變得又平又鈍，該有的尖峰都不見了。官方文件說明得很明確 —— 最近 10 天內是從記錄器讀完整解析度的原始資料，超過 10 天的部分改從長期統計來，而長期統計是每小時取樣平均一次。所以你看到的數字跟當年那一瞬間的實際讀數不會完全一樣，這是正常的。官方甚至在圖上做了區分：解析度高的那段線條顏色會比較深。

動手做：把歷史下載成 CSV

Home Assistant 內建就能把歷史匯出成 CSV，不用裝任何東西。步驟如下。

1. 打開側欄的「歷史（History）」

   如果側欄上看不到，點側欄最下面自己的名字進個人資料頁，確認它有沒有被藏起來；或者最快的辦法 —— 直接在網址列後面接 /history 按 Enter。

2. 選出你要的區域、裝置或實體

   頁面上方有選擇器，可以按區域（Area）、按裝置（Device），也可以直接指名實體。一次選一整個區域很方便 —— 例如把「客廳」整包選起來，就會拉出客廳所有東西的曲線。前提是你在 第 3 章 有好好分區域。

3. 設定時間範圍

   用時間區間選擇器挑「今天」「本週」或自訂起訖日。這一步決定 CSV 裡有多少列，範圍拉太大會等很久，建議先用一天試水溫。

4. 按右上角的「下載資料（Download data）」

   按鈕就在頁面右上角，英文介面寫 Download data，中文介面是「下載資料」之類的字樣。按下去瀏覽器就直接存一個 CSV 檔到你的下載資料夾，不會跳出什麼設定視窗。

   

5. 丟進試算表

   用 Excel、Numbers 或 Google 試算表打開。如果中文變成亂碼，用「匯入」而不是直接雙擊開啟，並在編碼選 UTF-8。

活動頁也能下載了

以前想匯出「誰在幾點做了什麼」這種事件流水帳，只能自己抄。Home Assistant 2026.8 之後，活動（Activity）頁面也多了 CSV 下載，以及一個「清空並重置」的動作。所以現在兩邊各有各的匯出：

工具 → 統計：修正那些歪掉的數字

從側欄進 設定 → 工具（Tools），裡面有好幾個分頁：YAML、狀態（States）、動作（Actions）、範本（Template）、事件（Events）、統計（Statistics）、Assist。

統計這一頁只做兩件事，但兩件都很關鍵。

一、它會列出有問題的統計實體

頁面會把所有「有長期統計」的實體列出來，並且對出問題的那幾個標上「修復問題（Fix issue）」的連結，點下去會告訴你偵測到什麼毛病。最常見的兩種是：

二、它可以直接改某一小時的數值

這是救場神器。最典型的災難情境：智慧電表在某一刻回報了一個離譜的數字（例如瞬間跳到 999999 度），結果第 17 章那個能源儀表板整個月的長條圖，被那一根爆表的柱子壓成一條貼著地面的線，什麼都看不到。

官方文件描述的操作是：在統計頁點該實體旁邊的圖示，用日期與時間欄位找到那個資料點，然後把值改掉。

1. 先在能源或歷史圖上找出出問題的時間點

   把滑鼠移到那根不合理的柱子上，記下日期跟小時。

2. 進 設定 → 工具 → 統計，找到那個實體

   用上面的搜尋框打實體名字比較快。

3. 打開調整介面，用日期時間定位到那一筆

   它會顯示那個小時記錄到的數值。

4. 改成合理的值，存檔後回去看圖

   圖表通常需要重新整理頁面才會反映。

用 include / exclude 精簡資料

資料庫變大的元凶，通常不是你天天在用的那幾顆燈，而是一堆你根本不會回頭看的雜訊。要瘦身，第一件事就是叫記錄器別再記它們。

這組設定要寫在 configuration.yaml，改完需要重新啟動 Home Assistant 才會生效。

做法 A：黑名單（exclude）—— 推薦新手用

預設全記，只把吵的踢掉。心理負擔小，不會不小心漏掉重要東西。

recorder:
  purge_keep_days: 10
  exclude:
    domains:
      - automation
      - update
    entity_globs:
      - sensor.sun*
      - weather.*
    entities:
      - sensor.date
      - sensor.last_boot
    event_types:
      - my_custom_event

做法 B：白名單（include）—— 資料庫已經失控時用

反過來：預設什麼都不記，只記你點名的。效果最猛，但很容易把重要東西一起關掉，之後才發現「咦我要的歷史怎麼沒了」。

recorder:
  include:
    domains:
      - sensor
      - switch
      - media_player
  exclude:
    entities:
      - sensor.last_boot
      - sensor.date
    entity_globs:
      - sensor.weather_*

兩種可以混用：先用 include 圈出大範圍，再用 exclude 把裡面幾顆討厭鬼挑掉。官方文件列了完整的優先順序規則，大原則是越精確的設定越優先 —— 明確寫在 entities 的贏過萬用字元，萬用字元贏過整個 domain。

四種過濾條件

哪些是常見的吵鬼

清理（Purge）：把已經存進去的垃圾倒掉

設好過濾只能止血，已經肥起來的資料庫還是得手動清。記錄器提供這幾個動作（Action，舊稱服務／Service）：

recorder.purge 的三個參數

最常用的「大掃除」組合：剛剛在上一節加好排除規則、重開機之後，跑一次這個把過去的殘骸也一起清掉。

action: recorder.purge
data:
  keep_days: 7
  repack: true
  apply_filter: true

執行方式：設定 → 工具（Tools）→ 動作，找到 recorder.purge，切到 YAML 模式貼上，按執行。（這個頁面舊版叫「開發者工具」，而且掛在側欄上，2026.2 之後搬進設定裡。）

只清某一個吵死人的實體

如果只有一個功率插座在爆量，不需要把全部歷史陪葬。recorder.purge_entities 可以指定 entity_id、domains 或 entity_globs，其中 keep_days 預設是 0，也就是「符合的資料全部立刻刪掉」。

官方文件裡有一個很實用的自動化範例：每天凌晨只保留這顆插座最近 5 天的資料。

alias: 每天清掉吵鬧功率感測器的舊資料
triggers:
  - trigger: time
    at: "04:15:00"
actions:
  - action: recorder.purge_entities
    data:
      keep_days: 5
      entity_id: sensor.power_sensor_0
mode: single

這個寫法的好處是：你既保留了看最近幾天曲線的能力，又不讓它無限累積。而且因為長期統計不受影響，這顆感測器如果有狀態類別，年度趨勢照樣看得到。

另外，預設的自動清理（auto_purge）每天凌晨 04:12 就會跑，所以正常情況下你根本不需要手動 purge。手動只有在兩種時候用：剛改完過濾規則要套用到舊資料，或是資料庫已經失控要緊急瘦身。

備份含不含資料庫？資料庫壞掉怎麼救？

備份會把資料庫一起包走

因為 home-assistant_v2.db 就躺在設定資料夾裡，完整備份自然會把它一起收進去。這帶來一個很現實的副作用：資料庫多大，每一份備份就跟著多大。資料庫 2 GB，你存三份備份就是 6 GB 憑空消失。

官方那篇「清出空間（Clear up storage）」的建議其實很單純，就三件事：把資料庫清一清（purge）、用記錄器的過濾少記一點、以及把 purge_keep_days 調小。備份那邊則是叫你設好保留幾份的規則，別讓備份檔在機器上一直堆，並且盡量把備份存到 Home Assistant 以外的地方。

順序上建議這樣做：先設好 exclude → 重開機 → 跑一次 recorder.purge 帶 repack → 再建立備份。這樣備份檔會小非常多。

換資料庫等於放棄舊歷史

資料庫壞掉的症狀與處理

SQLite 損毀最常見的原因是「寫到一半斷電」或「記憶卡老化」。你會看到的症狀通常是：Home Assistant 開得起來，但歷史一片空白、活動也是空的，日誌裡出現一堆資料庫相關的錯誤。

1. 先確認是不是真的壞了

   去 設定 → 系統 → 日誌 看有沒有 sqlite 或 database 相關的錯誤訊息。

2. 知道 Home Assistant 會自己自救

   官方文件說明：當 SQLite 遇到無法修復的損毀時，系統會自動把壞掉的資料庫移到旁邊，然後開一個全新的。你的設定、自動化、裝置都不會不見，不見的只有歷史。

3. 確認磁碟空間夠

   官方特別提到，處理損毀的 SQLite 資料庫時，準備約 2.5 倍資料庫大小的可用空間是必要的。空間不夠的話連自救都做不到。

4. 接受歷史損失，然後找根因

   與其花幾小時搶救那個 .db 檔（官方也只是指向 SQLite 官方的復原說明），不如把那個舊檔案刪掉騰出空間，去處理真正的問題：記憶卡是不是該換了？是不是常常直接拔電？

進階一：從 SQLite 換成 MariaDB

SQLite 是單一檔案的資料庫，簡單、零設定，但在實體數量多、寫入頻繁的時候會顯得吃力。這時候可以換成正規的資料庫伺服器。

官方文件列出支援的版本下限：

如果你跑的是 Home Assistant OS，最省事的路線是裝官方倉庫裡的 MariaDB App。路徑是 設定 → Apps —— 沒錯，Home Assistant 2026.2 把介面上的「附加元件（Add-ons）」全面改名成「Apps」，官方的說法是「大家都知道 app 是什麼，打開手機商店挑一個裝起來就對了」。舊教學裡的「Add-on 商店」講的就是它。（順帶一提，Apps 只有 Home Assistant OS 的安裝方式才有。）裝好之後在 configuration.yaml 加上：

recorder:
  db_url: mysql://homeassistant:你的密碼@core-mariadb/homeassistant?charset=utf8mb4
  purge_keep_days: 14

其中 core-mariadb 是那個 App 在內部網路上的主機名稱，帳號密碼和資料庫名稱要跟你在 App 設定裡填的一致。連到別台機器的話，官方文件給的通用格式是：

mysql://user:password@SERVER_IP/DB_NAME?charset=utf8mb4
postgresql://user:password@SERVER_IP/DB_NAME

進階二：InfluxDB + Grafana 長期存放與繪圖

這是「玩真的」路線。概念很簡單：

Home Assistant 官方有 InfluxDB 整合，會把狀態變化額外再寫一份到 InfluxDB。注意是「額外」—— 本地的 recorder 照樣跑，兩邊是獨立的。所以你可以在 recorder 那邊只留 7 天保持輕巧，同時在 InfluxDB 留 3 年。

設定上的重點：

• InfluxDB 1.x 用的是網址、帳號密碼、資料庫名稱那一組，而且驗證是選配的（預設不開）。
• InfluxDB 2.x 與 3.x 改用組織（organization）、儲存桶（bucket）與存取權杖（token），驗證是必填的，設定裡還要多寫一個 api_version: 2 告訴整合「我是新版」。官方整合文件目前 1.x／2.x／3.x 三種都有寫。
• 不管哪一版，都一定要設過濾。它同樣支援 domains、entities、entity_globs 的 include / exclude 寫法。把家裡所有東西無差別往 InfluxDB 灌，只是把肥大問題換個地方發生。

安裝方面，InfluxDB 與 Grafana 都有社群維護的 App（hassio-addons 那個「Home Assistant Community Apps」倉庫，舊名 Community Add-ons），不是官方出品的，安裝前要先把那個社群倉庫加進 App 商店。怎麼加第三方倉庫 第 20 章 和 附錄 A 已經講過，這裡不重複。另外提醒一句：App（原本叫 Add-on）只有 Home Assistant OS 的安裝方式才有，用 Docker 或 Core 裝的人要自己另外架 InfluxDB 和 Grafana。

進階三：用 SQL 整合把查詢變成感測器

SQL 整合可以讓你寫一句 SQL 查詢，把結果變成一個實體，然後就能放上儀表板、拿來觸發自動化。官方文件說明它可以透過設定流程（UI）加入，也可以寫 YAML。

最經典的用途只有一個：把資料庫大小做成感測器，直接顯示在儀表板上盯著它。

1. 設定 → 裝置與服務 → 新增整合

   右下角的按鈕，搜尋「SQL」。

2. 資料庫網址留空

   官方文件說 db_url 是選填的，留空就會用記錄器現在用的那個資料庫。你不用知道路徑。

3. 貼上查詢語句

   SQLite 版本官方給的範例是這一句：

   SELECT ROUND(page_count * page_size / 1024 / 1024, 1) as size
   FROM pragma_page_count(), pragma_page_size();

4. 欄位填 size

   對應查詢裡 as size 那個名字。查詢必須只回傳一列結果。

5. 設好名稱與單位

   名稱可以取「資料庫大小」，結果的單位是 MiB。官方提到可以把裝置類別設成資料量（Data size），讓介面自動幫你換算單位。

做好之後，把它丟到儀表板上（第 6 章），甚至可以搭一個自動化：超過某個門檻就推播通知給你（第 7 章）。

alias: 資料庫太肥就通知我
triggers:
  - trigger: numeric_state
    entity_id: sensor.database_size
    above: 2000
    for: "01:00:00"
conditions: []
actions:
  - action: notify.persistent_notification
    data:
      title: 資料庫警告
      message: 資料庫已經超過 2000 MiB（大約 2 GB），該去看看是誰在灌水了。
mode: single

上面用的 notify.persistent_notification 只會在 Home Assistant 介面裡跳一則常駐通知，不用先設定任何東西，最適合拿來測試。想改成推到手機上，把那一行換成 第 7 章 建立的通知動作就好。for: "01:00:00" 的意思是「連續超過一小時才通知」，避免它在門檻附近抖來抖去一直吵你。

常見卡關

1. Home Assistant 整個變超慢，點什麼都要等

   先懷疑資料庫。到設定 → 系統 → 儲存空間看看磁碟剩多少，再去修復頁看資料庫估算大小。如果是幾 GB 等級，照這個順序處理：先找出吵鬼（通常是手機 App 的感測器、逐秒回報的功率插座），加進 exclude，重新啟動，然後跑一次 recorder.purge 帶 repack: true 和 apply_filter: true。跑 repack 之前記得確認磁碟空間夠。

2. 記憶卡壞了、系統開不起來

   Home Assistant 每 commit_interval 秒就寫一次硬碟，資料庫又是持續在長的檔案，這對消費級的 microSD 卡是相當重的負擔。這件事沒有官方的規格數字可以引用，但在社群裡是公認最常見的死法之一。務實的做法有三個，效果由弱到強：把 commit_interval 調大、把吵鬧實體排除掉、以及最根本的 —— 改用 SSD 或工業級儲存裝置開機。真的要長期穩定跑，換掉記憶卡是唯一根治的辦法。

3. 重開機之後歷史全部不見了

   兩個可能。一是資料庫損毀，Home Assistant 自動把壞的移開、開了一個新的空白資料庫，這時候日誌裡會有明顯的錯誤訊息可以佐證。二是你剛剛從 SQLite 換到了 MariaDB —— 官方不支援資料遷移，換了就是重新開始，這是預期行為不是故障。先去看日誌就能分辨是哪一種。

4. 某個實體在歷史裡完全查不到

   依序檢查：(1) 它是不是被 exclude 掉了，或是被 include 白名單漏掉了；(2) 它是不是在 第 11 章 講的地方被停用了；(3) 如果只是在「活動」看不到但歷史看得到，那是正常的 —— 帶單位的感測器本來就會被活動自動略過。

5. 清理跑完了，硬碟空間卻沒有變多

   這是正常的。官方文件講得很明白：purge 不會立刻把空間還給作業系統，要 repack 才會真的重寫檔案釋放空間。而預設的 auto_repack 是每隔一週的星期日才跑一次，所以等個幾天空間也會自己回來。急的話就手動跑一次帶 repack: true 的清理。

6. 能源圖表被一根爆表的柱子壓扁

   去 設定 → 工具 → 統計，找到那個實體，用日期時間定位到那一筆離譜的數值改掉。改之前先備份。詳細步驟看本章「工具 → 統計」那一節。

7. 下載的 CSV 打開是亂碼

   不要用雙擊直接開。在 Excel 用「資料 → 從文字/CSV」匯入，編碼選 UTF-8；Google 試算表則是「檔案 → 匯入」，通常會自動判斷正確。

8. 找不到 recorder 的動作，或是按了沒反應

   先確認你走對路：現在是 設定 → 工具 → 動作，不是側欄上的「開發者工具」（2026.2 之後那個位置已經沒有了）。再來，記錄器的動作需要管理員權限才能執行，用一般使用者帳號登入時整個設定區都進不去。切換回管理員帳號再試。

常見問題