在群暉上用 Docker Compose 跑智能家居全家桶（完整設定檔）

charles

NAS 開著也是開著，拿來跑智能家居服務很划算。

這篇給一份完整的 compose 檔，以及每個服務的注意事項。



先講架構決定

HA 要不要跑在 NAS 上？

我的建議是不要，理由：

• Docker 版的 HA 不能用附加元件（Add-on）
  
• NAS 更新或重開的時候，整個智能家居會停擺
  
• USB 直通（Zigbee 棒）在群暉上比較麻煩
  

比較好的分工：

• HA 跑在獨立的小主機（HAOS，完整功能）
  
• NAS 跑「支援性服務」：MQTT、Frigate、InfluxDB、Grafana、備份
  

但如果你就是想省一台機器，Docker 版的 HA 也能用，
只是要接受上面那些限制。

群暉的前置設定

1. 安裝 Container Manager（舊版叫 Docker）

套件中心 → 搜尋 Container Manager → 安裝

2. 建立資料夾結構

1. /volume1/docker/
2. ├── homeassistant/
3. │   └── config/
4. ├── mosquitto/
5. │   ├── config/
6. │   ├── data/
7. │   └── log/
8. ├── zigbee2mqtt/
9. │   └── data/
10. ├── frigate/
11. │   ├── config/
12. │   └── media/
13. ├── influxdb/
14. │   ├── data/
15. │   └── config/
16. ├── grafana/
17. │   └── data/
18. └── docker-compose.yml

複製代碼

3. 開啟 SSH（控制台 → 終端機和 SNMP → 啟用 SSH）

完整的 docker-compose.yml

1. services:
3.   # ---------------------------------------------- MQTT Broker
4.   mosquitto:
5.     image: eclipse-mosquitto:2
6.     container_name: mosquitto
7.     restart: unless-stopped
8.     ports:
9.       - "1883:1883"
10.       - "9001:9001"
11.     volumes:
12.       - /volume1/docker/mosquitto/config:/mosquitto/config
13.       - /volume1/docker/mosquitto/data:/mosquitto/data
14.       - /volume1/docker/mosquitto/log:/mosquitto/log
15.     environment:
16.       - TZ=Asia/Taipei
18.   # ---------------------------------------------- Zigbee2MQTT
19.   zigbee2mqtt:
20.     image: koenkk/zigbee2mqtt:latest
21.     container_name: zigbee2mqtt
22.     restart: unless-stopped
23.     depends_on:
24.       - mosquitto
25.     ports:
26.       - "8080:8080"
27.     volumes:
28.       - /volume1/docker/zigbee2mqtt/data:/app/data
29.       - /run/udev:/run/udev:ro
30.     devices:
31.       # 用 by-id 而不是 /dev/ttyUSB0，拔插之後才不會跑掉
32.       - /dev/serial/by-id/usb-XXXX:/dev/ttyACM0
33.     environment:
34.       - TZ=Asia/Taipei
36.   # ---------------------------------------------- InfluxDB
37.   influxdb:
38.     image: influxdb:2
39.     container_name: influxdb
40.     restart: unless-stopped
41.     ports:
42.       - "8086:8086"
43.     volumes:
44.       - /volume1/docker/influxdb/data:/var/lib/influxdb2
45.       - /volume1/docker/influxdb/config:/etc/influxdb2
46.     environment:
47.       - TZ=Asia/Taipei
48.       - DOCKER_INFLUXDB_INIT_MODE=setup
49.       - DOCKER_INFLUXDB_INIT_USERNAME=admin
50.       - DOCKER_INFLUXDB_INIT_PASSWORD_FILE=/run/secrets/influx_pw
51.       - DOCKER_INFLUXDB_INIT_ORG=home
52.       - DOCKER_INFLUXDB_INIT_BUCKET=homeassistant
53.       - DOCKER_INFLUXDB_INIT_RETENTION=520w
54.     secrets:
55.       - influx_pw
57.   # ---------------------------------------------- Grafana
58.   grafana:
59.     image: grafana/grafana-oss:latest
60.     container_name: grafana
61.     restart: unless-stopped
62.     depends_on:
63.       - influxdb
64.     ports:
65.       - "3000:3000"
66.     volumes:
67.       - /volume1/docker/grafana/data:/var/lib/grafana
68.     environment:
69.       - TZ=Asia/Taipei
70.       - GF_SECURITY_ADMIN_PASSWORD__FILE=/run/secrets/grafana_pw
71.       - GF_USERS_ALLOW_SIGN_UP=false
72.     secrets:
73.       - grafana_pw
75. secrets:
76.   influx_pw:
77.     file: ./secrets/influx_pw.txt
78.   grafana_pw:
79.     file: ./secrets/grafana_pw.txt

複製代碼

密碼用 secrets 而不是直接寫在環境變數裡 ——
環境變數在 docker inspect 裡看得到，而且會進 compose 檔的版控。



群暉特有的五個坑

坑一：USB 裝置名稱會變

用 /dev/ttyUSB0 的話，拔插或重開之後可能變成 ttyUSB1。

正確做法：

1. ls -l /dev/serial/by-id/

複製代碼

會看到類似：

1. usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_xxxx-if00-port0

複製代碼

用這個完整路徑，它是綁在裝置本身的，不會變。

坑二：群暉的 DSM 更新會重啟 Docker

所有容器都會停一下。

• 一定要設 restart: unless-stopped
  
• 關鍵服務（MQTT）不要只放 NAS，不然 NAS 一重開，
    所有 Zigbee 裝置在 HA 裡都會變成不可用
  

我自己就踩過這個：NAS 每週自動維護重開一次，
那段時間家裡的自動化全部失效，查了好久才發現關聯。

後來把 MQTT 搬到 HA 主機上就解決了。

坑三：權限問題

群暉的共用資料夾權限跟一般 Linux 不同。

容器裡的使用者可能沒有寫入權限，症狀是容器一直重啟。

解法：

1. # 在 compose 裡指定 UID/GID
2.     user: "1026:100"       # 用你的群暉使用者 ID

複製代碼

查自己的 ID：

1. id 你的帳號

複製代碼

坑四：Container Manager 的專案功能會改寫你的 compose

用 DSM 介面的「專案」功能匯入 compose 檔時，
它可能會自動加東西或改格式。

我的做法是用 SSH 直接跑：

1. cd /volume1/docker
2. sudo docker compose up -d
3. sudo docker compose logs -f

複製代碼

這樣 compose 檔完全由你控制。

坑五：通訊埠衝突

群暉本身佔用了不少埠：

• 5000 / 5001 —— DSM
  
• 80 / 443 —— Web Station
  
• 8080 —— 有時候被其他套件佔用
  

衝突的話容器會起不來，日誌會說 port is already allocated。

1. # 看誰佔用了
2. sudo netstat -tulpn | grep 8080

複製代碼

Mosquitto 的必要設定

預設的 eclipse-mosquitto:2 不允許匿名連線，
沒有設定檔的話會直接拒絕所有連線。

建立 /volume1/docker/mosquitto/config/mosquitto.conf：

1. listener 1883
2. protocol mqtt
4. listener 9001
5. protocol websockets
7. persistence true
8. persistence_location /mosquitto/data/
9. log_dest file /mosquitto/log/mosquitto.log
11. allow_anonymous false
12. password_file /mosquitto/config/passwd

複製代碼

建立密碼檔：

1. sudo docker exec -it mosquitto sh
2. mosquitto_passwd -c /mosquitto/config/passwd hauser
3. # 輸入密碼
5. mosquitto_passwd -b /mosquitto/config/passwd z2m 另一組密碼
6. exit
8. sudo docker restart mosquitto

複製代碼

每個客戶端用不同帳號（HA 一個、Z2M 一個），
這樣出問題可以單獨撤銷。

備份

compose 檔和設定檔一定要備份。

1. #!/bin/bash
2. # /volume1/docker/backup.sh
3. DEST=/volume1/backup/docker-$(date +%F)
4. mkdir -p "$DEST"
6. # 只備份設定，不備份資料（資料太大而且可以重建）
7. tar czf "$DEST/configs.tar.gz" \
8.   -C /volume1/docker \
9.   docker-compose.yml \
10.   mosquitto/config \
11.   zigbee2mqtt/data/configuration.yaml \
12.   frigate/config
14. # 保留最近 14 份
15. ls -1dt /volume1/backup/docker-* | tail -n +15 | xargs rm -rf

複製代碼

zigbee2mqtt/data 裡的 coordinator_backup.json 和 database.db 特別重要 ——
沒有它們的話，Zigbee 網路要全部重新配對。

---

最後一個建議：一次只加一個服務。

我第一次是把 compose 檔一口氣寫完然後 up -d，
結果三個服務起不來，而且互相影響，debug 了一整晚。

一個一個加，每個都確認能跑、能連、資料有存下來，再加下一個。