webmail-gateway/README.md

WebMail Gateway

多租戶 WebMail Gateway，整合 Keycloak SSO 和 IMAP/SMTP 郵件服務。

功能

• 🔐 Keycloak SSO 整合 (支援 PKCE)
• 📧 IMAP/SMTP 郵件收發
• 🏢 多租戶支援 (路徑參數路由)
• 🔄 Redis Session 管理
• 🎨 多主題支援 (待恢復)
• 📎 附件支援 (待恢復)

技術架構

• 後端: FastAPI + Python 3.11
• 資料庫: PostgreSQL (Virtual MIS Database)
• 快取: Redis
• 認證: Keycloak OAuth 2.0 + PKCE
• 郵件: IMAP (port 143) / SMTP (port 587)
• 部署: Docker + Traefik

開發環境

目錄結構

webmail-gateway/
├── app.py                 # 主程式
├── requirements.txt       # Python 依賴
├── Dockerfile            # Docker 映像檔定義
├── docker-compose.yml    # Docker Compose 配置
└── README.md            # 說明文件

本地開發

# 安裝依賴
pip install -r requirements.txt

# 設定環境變數
export REDIS_HOST=10.1.0.20
export REDIS_PORT=6379
export REDIS_PASSWORD=DC1qaz2wsx
export REDIS_DB=2
export DATABASE_URL=postgresql://admin:DC1qaz2wsx@10.1.0.20:5433/virtual_mis
export KEYCLOAK_SERVER_URL=https://auth.lab.taipei

# 啟動開發伺服器
uvicorn app:app --host 0.0.0.0 --port 8000 --reload

部署到正式環境

# 1. 推送到 Gitea
git add .
git commit -m "Update WebMail Gateway"
git push origin main

# 2. SSH 到伺服器
ssh porsche@10.1.0.254

# 3. 拉取最新代碼
cd /home/porsche/services/webmail-gateway
git pull

# 4. 重建並啟動容器
docker compose down
docker compose build
docker compose up -d

多租戶路由

訪問方式

• vmis-admin 租戶: https://webmail.lab.taipei/vmis-admin
• porsche1 租戶: https://webmail.lab.taipei/porsche1
• 其他租戶: https://webmail.lab.taipei/{tenant_code}

自動導向邏輯

1. 使用者訪問 /{tenant_code}
2. 查詢租戶資訊 (從 Virtual MIS Database)
3. 取得對應的 Keycloak Realm
4. 生成 PKCE 參數
5. 導向 Keycloak 登入頁面
6. 回調處理並驗證 PKCE
7. 建立 Session 並導向收件匣

Keycloak 配置

每個租戶的 Realm 都需要建立 webmail client：

• Client ID: webmail
• Client Type: Public Client
• PKCE: Enabled (S256)
• Standard Flow: Enabled
• Redirect URI: https://webmail.lab.taipei/{tenant_code}/callback

待辦事項

• 恢復完整 Gmail 風格 UI
• 恢復主題切換功能
• 恢復郵件詳情 Modal
• 恢復批次刪除功能
• 恢復 Rich Text 編輯器
• 建立 Gitea 遠端倉庫
• 設定 CI/CD 流程

版本歷史

• v1.0 (2026-03-04): 基礎 PKCE 支援 + 多租戶路由