webmail-gateway/DEPLOYMENT.md

# WebMail Gateway 部署指南

## 環境架構

### 開發環境 (Development)
- **主機**: 10.1.0.245 (Windows 桌機)
- **目錄**: `D:\_Develop\porscheworld_develop\webmail-gateway\`
- **Port**: 8100
- **啟動**: `START_DEVELOPMENT.bat`
- **用途**: 開發、測試、功能迭代

### 正式環境 (Production)
- **主機**: 10.1.0.254 (Ubuntu Server - home)
- **目錄**: `/home/porsche/services/webmail-gateway/`
- **Port**: 8000 (容器內)
- **啟動**: `docker compose up -d`
- **用途**: 對外服務、穩定運行

---

## 開發流程

### 1. 在開發環境啟動服務

```batch
cd D:\_Develop\porscheworld_develop\webmail-gateway
START_DEVELOPMENT.bat
```

### 2. 切換 Traefik 路由到開發機

在伺服器上執行：

```bash
ssh porsche@10.1.0.254

# 停止正式環境容器
cd /home/porsche/services/webmail-gateway
docker compose down

# 建立 Traefik dynamic 配置目錄 (如果不存在)
mkdir -p /home/porsche/traefik/dynamic

# 上傳開發路由配置
# (從開發機執行)
scp traefik-dev-route.yml porsche@10.1.0.254:/home/porsche/traefik/dynamic/webmail-dev.yml

# Traefik 會自動重新載入配置
```

### 3. 開發與測試

現在訪問 https://webmail.lab.taipei 會自動路由到開發機 (10.1.0.245:8100)

- ✅ 支援熱重載 (`--reload`)
- ✅ 可以即時修改程式碼
- ✅ 可以使用 debugger

### 4. 切換回正式環境

```bash
ssh porsche@10.1.0.254

# 刪除開發路由配置
rm /home/porsche/traefik/dynamic/webmail-dev.yml

# 啟動正式環境容器
cd /home/porsche/services/webmail-gateway
docker compose up -d
```

---

## 部署到正式環境

### 方案 A: 直接複製 (快速)

```bash
# 1. 停止開發伺服器 (Ctrl+C)

# 2. 從開發機上傳到伺服器
scp app.py porsche@10.1.0.254:/home/porsche/services/webmail-gateway/

# 3. 重建容器
ssh porsche@10.1.0.254 'cd /home/porsche/services/webmail-gateway && docker compose down && docker compose build && docker compose up -d'
```

### 方案 B: 透過 Git (推薦)

```bash
# 1. 在開發機提交變更
cd D:\_Develop\porscheworld_develop\webmail-gateway
git add .
git commit -m "Feature: 完整 Gmail 風格 UI"
git push gitea main

# 2. 在伺服器拉取
ssh porsche@10.1.0.254
cd /home/porsche/services/webmail-gateway
git pull
docker compose down && docker compose build && docker compose up -d
```

---

## 多租戶服務部署架構

當需要為每個租戶部署獨立服務時 (例如 10 個租戶 = 10 個服務)：

### 架構設計

```
Traefik (Reverse Proxy)
    │
    ├─── webmail.lab.taipei/vmis-admin  → webmail-vmis-admin:8000
    ├─── webmail.lab.taipei/porsche1    → webmail-porsche1:8000
    ├─── webmail.lab.taipei/porsche2    → webmail-porsche2:8000
    ├─── ...
    └─── webmail.lab.taipei/tenant10    → webmail-tenant10:8000
```

### 部署腳本範例

```bash
#!/bin/bash
# deploy_tenant_service.sh

TENANT_CODE=$1

if [ -z "$TENANT_CODE" ]; then
    echo "Usage: ./deploy_tenant_service.sh <tenant_code>"
    exit 1
fi

# 建立租戶專屬目錄
mkdir -p /home/porsche/services/webmail-${TENANT_CODE}

# 複製基礎配置
cp -r /home/porsche/services/webmail-gateway/Dockerfile /home/porsche/services/webmail-${TENANT_CODE}/
cp -r /home/porsche/services/webmail-gateway/app.py /home/porsche/services/webmail-${TENANT_CODE}/
cp -r /home/porsche/services/webmail-gateway/requirements.txt /home/porsche/services/webmail-${TENANT_CODE}/

# 建立專屬 docker-compose.yml
cat > /home/porsche/services/webmail-${TENANT_CODE}/docker-compose.yml << EOF
services:
  webmail-${TENANT_CODE}:
    build: .
    container_name: webmail-${TENANT_CODE}
    environment:
      - REDIS_HOST=10.1.0.20
      - REDIS_PORT=6379
      - REDIS_PASSWORD=DC1qaz2wsx
      - REDIS_DB=2
      - DATABASE_URL=postgresql://admin:DC1qaz2wsx@10.1.0.20:5433/virtual_mis
      - KEYCLOAK_SERVER_URL=https://auth.lab.taipei
      - TENANT_CODE=${TENANT_CODE}
    networks:
      - traefik-network
      - mailserver_mailserver-internal
    labels:
      - "traefik.enable=true"
      - "traefik.docker.network=traefik-network"
      - "traefik.http.routers.webmail-${TENANT_CODE}.rule=Host(\`webmail.lab.taipei\`) && PathPrefix(\`/${TENANT_CODE}\`)"
      - "traefik.http.routers.webmail-${TENANT_CODE}.entrypoints=web,websecure"
      - "traefik.http.routers.webmail-${TENANT_CODE}.tls.certresolver=letsencrypt"
      - "traefik.http.services.webmail-${TENANT_CODE}.loadbalancer.server.port=8000"
    restart: always

networks:
  traefik-network:
    external: true
  mailserver_mailserver-internal:
    external: true
EOF

# 啟動容器
cd /home/porsche/services/webmail-${TENANT_CODE}
docker compose up -d

echo "Tenant ${TENANT_CODE} service deployed!"
echo "Access: https://webmail.lab.taipei/${TENANT_CODE}"
```

### 使用方式

```bash
# 部署 porsche1 租戶服務
./deploy_tenant_service.sh porsche1

# 部署 porsche2 租戶服務
./deploy_tenant_service.sh porsche2

# ... 依此類推
```

---

## 注意事項

### 開發環境切換
- ⚠️ 開發時請確保正式環境容器已停止 (`docker compose down`)
- ⚠️ 開發完成後記得切換回正式環境
- ⚠️ 不要在開發環境直接操作正式資料庫

### 多租戶部署
- 🔄 每個租戶獨立容器，互不影響
- 📊 可以針對不同租戶調整資源限制
- 🔍 容易追蹤各租戶的日誌和效能
- 💰 資源消耗較高 (10 個租戶 = 10 個容器)

### 替代方案：單一服務多租戶
目前的設計 (路徑參數路由) 已經支援多租戶，不需要為每個租戶部署獨立服務。除非有特殊需求 (例如：租戶要求獨立部署、資源隔離等)。