用 Docker Compose 打造個人 Homelab 的第一步

這是 ycwang.dev 部落格的第一篇文章，順便當作寫作格式範本——之後要新增文章，照這個檔案的 frontmatter 抄一份就好。

為什麼用 monorepo 管理 Homelab

把所有服務放在同一個 git repo（monorepo），最大的好處是「一次 clone 就能在全新電腦上重建整套基礎架構」。每個服務一個資料夾、各自帶 docker-compose.yml，彼此用 Docker 網路溝通。

設計原則：憑證、API Key 直接寫在 compose 檔裡（私人 repo），不依賴 .env，集中好找。

網路怎麼切

我把流量分成兩層，避免內部服務直接暴露在外網：

web-net：對外流量，只有最外層的 Nginx 開 80/443。
app-net：服務之間的內部通訊，不直接對外開 port。

這樣做的理由是：內部服務（資料庫、API）只需要被同網路的容器連到，沒必要讓全世界都能戳。

一段範例設定

下面是新服務最常見的 compose 骨架，重點在 restart 與 container_name：

services:
  my-service:
    image: my-service:1.0
    container_name: my-service   # 固定名稱，方便 docker logs 與 Nginx proxy_pass
    restart: unless-stopped      # 不用 always，避免 daemon 重啟後難以控制
    networks:
      - app-net

我踩過的坑

Nginx 寫死 upstream 會整個崩潰：只要某個容器沒開，Nginx 啟動就失敗。改用 resolver + 變數動態解析才穩。
靜態檔改了沒生效：靜態檔是 build 時 COPY 進 image 的，改完一定要 --build 重建，重新整理瀏覽器沒用。

小結

Homelab 的精神是「自己的服務自己養」。從一個服務開始，慢慢長成一整片生態系，過程中學到的 Docker、網路、反向代理知識，比看十篇教學還扎實。

下一篇我會寫監控：怎麼用 Prometheus + Grafana + ELK 把所有服務的狀態與 log 集中起來看。