跳至主要内容

Docker 與 Docker Compose 基礎觀念

在 Homelab 中，絕大多數的自託管服務（如 Home Assistant、Jellyfin、Vaultwarden 等）都是透過 Docker 與 Docker Compose 進行部署與管理。

什麼是 Docker？​

Docker 是一種容器化技術 (Containerization)。

  • 核心概念：將應用程式及其所需要的所有函式庫、環境與設定打包成一個標準化的「容器 (Container)」。
  • 解決的痛點：過去在 Linux 主機上安裝軟體常遇到相依性套件衝突或版本不合（「在我的電腦可以跑，在你的電腦跑不起來」）。Docker 讓軟體在任何有安裝 Docker Engine 的主機上都能一致運行。
  • 輕量高效：容器直接共享宿主機作業系統核心，不需像傳統虛擬機 (VM) 那樣模擬完整的硬體與載入獨立 OS，啟動只需數秒且極省記憶體。

什麼是 Docker Compose？​

如果說 Docker 是單一容器的執行引擎，那麼 Docker Compose 就是多容器的編排與設定工具。

傳統 docker run 的問題​

若只用原生 Docker 指令啟動一個 Home Assistant，指令會長成這樣：

docker run -d \
  --name home-assistant \
  --restart unless-stopped \
  -p 8123:8123 \
  -v /opt/stacks/homeassistant/config:/config \
  -e TZ=Asia/Taipei \
  homeassistant/home-assistant:stable

這種指令難以記憶，日後要修改 Port、調整路徑或移轉主機時很容易遺漏參數。

Docker Compose 的優勢​

Docker Compose 允許我們使用宣告式的 compose.yaml (或 docker-compose.yml) 檔案，將所有參數結構化記錄下來：

services:
  home-assistant:
    image: homeassistant/home-assistant:stable
    container_name: home-assistant
    restart: unless-stopped
    ports:
      - "8123:8123"
    volumes:
      - /opt/stacks/homeassistant/config:/config
    environment:
      - TZ=Asia/Taipei

優點：

  1. 設定即文件：所有參數清楚明瞭，直接存放在資料夾中。
  2. 多服務關聯：可以在同一個檔案中同時定義 Web 服務與後端資料庫（例如 WordPress + MySQL），一鍵同時啟動。
  3. 極速遷移與備份：換主機時只需複製資料夾，執行 docker compose up -d 即可滿血復活。

compose.yaml 核心欄位說明​

欄位名稱說明範例
services定義要運行的服務清單services:
image指定 Docker 映像檔名稱與版本標籤image: homeassistant/home-assistant:stable
container_name自訂容器運行時的名稱container_name: home-assistant
ports連接埠對應（宿主機Port:容器內Port）- "8123:8123"
volumes資料持久化掛載（宿主機路徑:容器內路徑）- /opt/stacks/ha/config:/config
environment傳入容器的環境變數- TZ=Asia/Taipei
restart容器崩潰或主機重開時的重啟原則restart: unless-stopped

常用指令​

在 compose.yaml 所在的目錄下執行：

# 建立並在背景啟動容器
docker compose up -d

# 停止並移除容器與網路（資料卷 volumes 會保留）
docker compose down

# 檢視容器即時運行日誌
docker compose logs -f

# 拉取最新版本的映像檔
docker compose pull

# 重啟服務
docker compose restart

相關連結​