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
  ```bash
  cd /home/wooo/registry
  docker compose up -d
  ```
- [ ] 確認 Registry 運行中
  ```bash
  curl http://127.0.0.1:5000/v2/
  # 應返回 {}
  ```

#### 1.2 Nginx 反向代理
- [ ] 複製 Nginx 配置
  ```bash
  sudo cp config/nginx/sites-available/registry /etc/nginx/sites-available/
  sudo ln -sf /etc/nginx/sites-available/registry /etc/nginx/sites-enabled/
  ```
- [ ] 建立 htpasswd 認證
  ```bash
  sudo htpasswd -Bbn admin Wooo_Registry_2026 > /etc/nginx/conf.d/.htpasswd
  ```
- [ ] 申請 SSL 證書
  ```bash
  sudo certbot certonly --webroot -w /var/www/certbot -d registry.wooo.work
  ```
- [ ] 重載 Nginx
  ```bash
  sudo nginx -t && sudo systemctl reload nginx
  ```

#### 1.3 驗證外部連線
- [ ] 測試 HTTPS 連線
  ```bash
  curl -I https://registry.wooo.work/v2/
  # 應返回 401 (需要認證)
  ```
- [ ] 測試 Docker 登入
  ```bash
  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
```bash
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 配置
```bash
kubectl apply -f k8s/04-momo-app.yaml
kubectl apply -f k8s/05-scheduler.yaml
```

### 4. 測試 CI/CD 流程

#### 4.1 觸發測試部署
```bash
git add .
git commit -m "test: 測試新 CI/CD 流程"
git push gitlab main
```

#### 4.2 驗證部署結果
- [ ] GitLab Pipeline 全部成功 (test, build, deploy-uat)
- [ ] Telegram 收到部署通知
- [ ] 檢查 K8s Pod 狀態
  ```bash
  kubectl get pods -n momo
  ```
- [ ] 健康檢查通過
  ```bash
  curl https://mo.wooo.work/health
  ```

### 5. GCP 部署

#### 5.1 手動觸發 GCP 部署
- 在 GitLab UI 點擊 `deploy-gcp` 手動執行

#### 5.2 或使用本地部署腳本
```bash
# SSH 到 GCP
ssh wooo@35.194.233.141
cd ~/momo-pro-system
./k8s/gcp/deploy.sh --full
```

#### 5.3 驗證 GCP 部署
```bash
curl https://momo.wooo.work/health
```

---

## 驗證腳本

執行完整驗證：
```bash
./scripts/verify-registry-cicd.sh
```

---

## 快速回滾

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

### 回滾 K8s 到舊版本
```bash
kubectl rollout undo deployment/momo-app -n momo
kubectl rollout undo deployment/momo-scheduler -n momo
```

### 手動構建並部署（繞過 CI/CD）
```bash
# 本地構建
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：
```bash
kubectl get secret registry-secret -n momo -o yaml
kubectl describe pod <pod-name> -n momo
```

### Q: GCP 部署失敗
**A**: 使用本地映像推送方式：
```bash
# 本地構建
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