Docker 實戰操作全手冊：從基礎到進階維護

在操作前，請確保您已透過 SSH 連線至 NAS，並使用 cd /volume1/docker/halo 進入專案目錄。

一、容器生命週期管理 (Docker Compose)

當您擁有 compose.yaml (或 docker-compose.yaml) 時，應優先使用 Compose 指令，這能確保 halo 與 halodb 的連動關係。

啟動並背景執行：
Bash
```
sudo docker compose up -d
```
- -d (Detached)：讓容器在背景執行，不會因為關閉終端機視窗而停止。
停止並移除專案容器：
Bash
```
sudo docker compose down
```
- 這會停止並移除該專案定義的所有容器與網路，但不會刪除掛載在硬碟上的資料夾（如 db、themes）。
重新啟動專案：
Bash
```
sudo docker compose restart
```
- 注意：這只是重新啟動現有容器。如果您修改了 compose.yaml 的環境變數，必須使用 up -d 才會生效。

有時 Docker Compose 會因為狀態不一致（如您遇到的 undefined 或亂碼容器）失效，這時需動用底層指令。

列出所有容器：
Bash
```
sudo docker ps -a
```
- 查看所有狀態（運行中、已停止）的容器。這能幫您找回那些「隱形成員」。
強制刪除特定容器：
Bash
```
sudo docker rm -f <容器名稱或ID>
```
- -f (Force)：即使容器正在運行也能強制拔除。
清理「孤兒」網路與資源：
Bash
```
sudo docker network prune -f
sudo docker system prune -f
```
- 當啟動報錯「Network already exists」時的救命丹。

這是您進行「客製化開發」最核心的操作。

在 Mac 上導出映像檔：

Bash

docker save <映像檔名稱>:<標籤> > <檔名>.tar

在 NAS 上匯入映像檔：
Bash
```
sudo docker load < <檔名>.tar
```
清理舊的映像檔：
Bash
```
sudo docker rmi <映像檔ID>
```
- 如果您重複 Load 了很多個版本的 my-halo，記得刪除舊的以節省 NAS 空間。

這是「碼農」與「一般使用者」的分水嶺。

即時查看日誌：
Bash
```
sudo docker logs -f <容器名稱>
```
- -f (Follow)：像看直播一樣追蹤最新日誌。這對於觀察 Halo 啟動是否成功至關重要。
潛入容器內部 (登入 Shell)：
Bash
```
sudo docker exec -it <容器名稱> /bin/bash
```
- -it：開啟一個互動式的終端機。您可以直接在容器裡檢查檔案路徑或網路連通性。
檢查環境變數是否生效：
Bash
```
sudo docker exec <容器名稱> env
```
- 這能驗證您的 HALO_EXTERNAL_URL 是否真的被讀取進去。

Synology 的權限管理 (ACL) 經常會導致 Docker 無法寫入 db 或 themes 資料夾。

暴力賦予最高權限 (適合測試期)：
Bash
```
sudo chmod -R 777 db themes logs attachments
```
更改所有者為 Docker 預設帳號：
Bash
```
sudo chown -R 1000:1000 .
```
- 許多官方 Image 預設會以 UID 1000 執行，對齊所有者能解決大部分的寫入失敗。

在您每次進行重大修改（如換主題、改 Java 代碼）前，請執行：

Bash

# 備份整個 halo 資料夾為一個壓縮檔
tar -cvf halo_backup_$(date +%Y%m%d).tar /volume1/docker/halo