ewoooc/docs/REGISTRY_DEPLOYMENT_CHECKLIST.md

Docker Registry CI/CD 部署檢查清單

概述

本文檔記錄從 Harbor 遷移到自建 Docker Registry 的完整部署流程和檢查清單。

---

架構變更總覽

之前 (Harbor)

GitLab CI → Docker Build → Push to Harbor (192.168.0.110:5050) → K8s Pull

之後 (Docker Registry)

GitLab CI → Docker Build → Push to Registry (registry.wooo.work) → K8s Pull (UAT)
                                                                → SCP + Import (GCP)

---

部署檢查清單

1. UAT 環境準備

1.1 Docker Registry 部署

• 安裝 Docker Registry

  cd /home/wooo/registry
  docker compose up -d
  

• 確認 Registry 運行中

  curl http://127.0.0.1:5000/v2/
  # 應返回 {}
  

1.2 Nginx 反向代理

• 複製 Nginx 配置

  sudo cp config/nginx/sites-available/registry /etc/nginx/sites-available/
  sudo ln -sf /etc/nginx/sites-available/registry /etc/nginx/sites-enabled/
  

• 建立 htpasswd 認證

  sudo htpasswd -Bbn admin Wooo_Registry_2026 > /etc/nginx/conf.d/.htpasswd
  

• 申請 SSL 證書

  sudo certbot certonly --webroot -w /var/www/certbot -d registry.wooo.work
  

• 重載 Nginx

  sudo nginx -t && sudo systemctl reload nginx
  

1.3 驗證外部連線

• 測試 HTTPS 連線

  curl -I https://registry.wooo.work/v2/
  # 應返回 401 (需要認證)
  

• 測試 Docker 登入

  docker login registry.wooo.work -u admin
  

2. GitLab CI/CD 設定

2.1 設定 CI/CD 變數

• 進入 GitLab > 專案 > Settings > CI/CD > Variables
• 新增以下變數:
  • REGISTRY_USER: admin
  • REGISTRY_PASSWORD: Wooo_Registry_2026 (設為 Protected & Masked)
  • UAT_SSH_PRIVATE_KEY: UAT SSH 私鑰 (設為 Protected)
  • GCP_SSH_PRIVATE_KEY: GCP SSH 私鑰 (設為 Protected)
  • TELEGRAM_BOT_TOKEN: Telegram Bot Token
  • TELEGRAM_CHAT_ID: Telegram Chat ID

2.2 更新 .gitlab-ci.yml

• 確認已更新為新的 CI/CD 配置
• 移除所有 Harbor 引用

3. K8s 設定

3.1 建立 Registry Secret

kubectl delete secret registry-secret -n momo 2>/dev/null || true
kubectl create secret docker-registry registry-secret \
  --docker-server=registry.wooo.work \
  --docker-username=admin \
  --docker-password=Wooo_Registry_2026 \
  -n momo

3.2 套用 K8s 配置

kubectl apply -f k8s/04-momo-app.yaml
kubectl apply -f k8s/05-scheduler.yaml

4. 測試 CI/CD 流程

4.1 觸發測試部署

git add .
git commit -m "test: 測試新 CI/CD 流程"
git push gitlab main

4.2 驗證部署結果

• GitLab Pipeline 全部成功 (test, build, deploy-uat)
• Telegram 收到部署通知
• 檢查 K8s Pod 狀態

  kubectl get pods -n momo
  

• 健康檢查通過

  curl https://mo.wooo.work/health
  

5. GCP 部署

5.1 手動觸發 GCP 部署

• 在 GitLab UI 點擊 deploy-gcp 手動執行

5.2 或使用本地部署腳本

# SSH 到 GCP
ssh wooo@35.194.233.141
cd ~/momo-pro-system
./k8s/gcp/deploy.sh --full

5.3 驗證 GCP 部署

curl https://momo.wooo.work/health

---

驗證腳本

執行完整驗證：

./scripts/verify-registry-cicd.sh

---

快速回滾

如果新 CI/CD 有問題，可以暫時回滾：

回滾 K8s 到舊版本

kubectl rollout undo deployment/momo-app -n momo
kubectl rollout undo deployment/momo-scheduler -n momo

手動構建並部署（繞過 CI/CD）

# 本地構建
docker build -t momo-pro-system:latest .

# 傳輸到 UAT
docker save momo-pro-system:latest | ssh wooo@192.168.0.110 'sudo k3s ctr images import -'

# 重啟
ssh wooo@192.168.0.110 'kubectl rollout restart deployment/momo-app deployment/momo-scheduler -n momo'

---

變更記錄

新增檔案

• docker/registry/docker-compose.yml - Registry 服務配置
• docker/registry/config.yml - Registry 內部配置
• docker/registry/setup.sh - Registry 安裝腳本
• config/nginx/sites-available/registry - Nginx 配置
• deploy/lib/registry.sh - Registry 管理函數庫
• scripts/registry_health_monitor.sh - Registry 健康監控
• scripts/verify-registry-cicd.sh - CI/CD 驗證腳本
• k8s/gcp/ - GCP 專用 K8s 配置

修改檔案

• .gitlab-ci.yml - 完全重寫，使用 Docker Registry
• k8s/04-momo-app.yaml - 映像來源改為 Registry
• k8s/05-scheduler.yaml - 映像來源改為 Registry
• docker-compose.yml - 映像來源改為 Registry
• CLAUDE.md - 文檔更新，移除 Harbor 引用

刪除檔案

• deploy/lib/harbor.sh - 已被 registry.sh 取代
• scripts/harbor_health_monitor.sh - 已被 registry_health_monitor.sh 取代

---

常見問題

Q: Registry 無法存取

A: 檢查以下項目：

1. Docker Registry 容器是否運行 (docker ps | grep registry)
2. Nginx 是否正確代理 (nginx -t)
3. SSL 證書是否有效 (certbot certificates)

Q: K8s 映像拉取失敗

A: 檢查 Registry Secret：

kubectl get secret registry-secret -n momo -o yaml
kubectl describe pod <pod-name> -n momo

Q: GCP 部署失敗

A: 使用本地映像推送方式：

# 本地構建
docker build -t momo-pro-system:latest .
docker save momo-pro-system:latest | gzip > /tmp/momo.tar.gz

# SCP 傳輸
scp /tmp/momo.tar.gz wooo@35.194.233.141:/tmp/

# SSH 匯入
ssh wooo@35.194.233.141 'gunzip -c /tmp/momo.tar.gz | sudo k3s ctr images import -'

---

聯絡資訊

如有問題，請聯繫：

• Telegram: @wooowooowooobot (Chat ID: 5619078117)
• GitLab Issues: http://192.168.0.110:8929/root/momo-pro-system/-/issues