# Apache Superset 部署指南

## 概述

Apache Superset 是 MOMO Pro System 的 BI 分析平台，用於建立進階分析儀表板。

## 架構

```
                         ┌─────────────────────────────────────┐
                         │        Apache Superset (UAT)        │
                         │   https://monitor.wooo.work/superset│
                         └──────────────┬──────────────────────┘
                                        │
            ┌───────────────────────────┼───────────────────────────┐
            │                           │                           │
            ▼                           ▼                           ▼
    ┌───────────────┐          ┌───────────────┐          ┌───────────────┐
    │  UAT 資料庫   │          │  GCP 資料庫   │          │  DEV 資料庫   │
    │ 192.168.0.110 │          │35.194.233.141 │          │  127.0.0.1    │
    │ momo_analytics│          │ momo_analytics│          │ momo_database │
    └───────────────┘          └───────────────┘          └───────────────┘
```

## 快速部署

```bash
# 1. SSH 到 UAT 主機
ssh wooo@192.168.0.110

# 2. 進入 Superset 目錄
cd /home/wooo/momo_pro_system/docker/superset

# 3. 執行部署腳本
chmod +x deploy.sh
./deploy.sh deploy

# 4. 設定 Nginx 反向代理 (見下方)

# 5. 設定資料庫唯讀用戶 (見下方)
```

## 服務管理

```bash
# 查看狀態
./deploy.sh status

# 查看日誌
./deploy.sh logs

# 重啟服務
./deploy.sh restart

# 停止服務
./deploy.sh stop

# 清除所有資料 (危險)
./deploy.sh clean
```

## 訪問資訊

| 項目 | 值 |
|------|-----|
| 內部 URL | `http://127.0.0.1:8088` |
| 外部 URL | `https://monitor.wooo.work/superset/` |
| 帳號 | `admin` |
| 密碼 | `<SUPERSET_ADMIN_PASSWORD>` |

## Nginx 配置

將以下內容加入 `/etc/nginx/sites-available/monitor`:

```nginx
# Superset BI 分析平台
location /superset/ {
    proxy_pass http://127.0.0.1:8088/;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Script-Name /superset;

    # WebSocket 支援
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";

    # 超時設定
    proxy_connect_timeout 300;
    proxy_send_timeout 300;
    proxy_read_timeout 300;
}
```

然後重啟 Nginx:
```bash
sudo nginx -t && sudo systemctl reload nginx
```

## 資料庫連線設定

### 1. 建立唯讀用戶

在 UAT PostgreSQL 執行:
```bash
kubectl exec -it momo-postgres-0 -n momo -- psql -U momo -d momo_analytics
```

執行 SQL:
```sql
CREATE ROLE superset_readonly WITH LOGIN PASSWORD 'Wooo_Superset_RO_2026';
GRANT CONNECT ON DATABASE momo_analytics TO superset_readonly;
GRANT USAGE ON SCHEMA public TO superset_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO superset_readonly;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO superset_readonly;
```

### 2. 在 Superset 新增資料庫連線

登入 Superset 後:
1. 點擊右上角 `+` → `Database`
2. 選擇 `PostgreSQL`
3. 輸入連線資訊

**UAT 環境連線:**
```
postgresql+psycopg2://superset_readonly:Wooo_Superset_RO_2026@host.docker.internal:5432/momo_analytics
```

> 注意: 使用 `host.docker.internal` 連接主機上的 K8s PostgreSQL

**GCP 環境連線:**
```
postgresql+psycopg2://superset_readonly:Wooo_Superset_RO_2026@35.194.233.141:5432/momo_analytics
```

> 注意: GCP 需要先設定防火牆規則允許 UAT IP (114.32.151.246)

## 預計實作的儀表板

| 儀表板 | 對應功能 | 資料表 |
|--------|---------|--------|
| 銷售分析總覽 | `/sales_analysis` | daily_sales_snapshot, realtime_sales_monthly |
| 當日業績追蹤 | `/daily_sales` | daily_sales_snapshot |
| 成長分析 | `/growth_analysis` | realtime_sales_monthly |
| 月度總結 | `/monthly_summary_analysis` | monthly_summary_analysis |
| ABC 分析 | `/abc_analysis/detail` | products, price_records |
| 商品價格趨勢 | `/` (首頁看板) | products, price_records |

## 資源需求

| 項目 | 最低需求 | 建議配置 |
|------|----------|----------|
| CPU | 2 核心 | 4 核心 |
| RAM | 4 GB | 8 GB |
| 硬碟 | 10 GB | 20 GB |

## 故障排除

### 問題: 容器啟動失敗

```bash
# 查看日誌
docker compose logs superset

# 檢查資料庫連線
docker compose logs superset-db
```

### 問題: 無法連線到外部資料庫

1. 確認防火牆規則
2. 確認資料庫用戶權限
3. 測試連線:
```bash
docker exec -it momo-superset bash
pip install psycopg2-binary
python -c "import psycopg2; conn = psycopg2.connect('postgresql://...')"
```

### 問題: SQL Lab 查詢超時

修改 `superset_config.py`:
```python
SQLLAB_TIMEOUT = 600  # 秒
```

## 備份

```bash
# 備份 Superset 資料
docker exec superset-postgres pg_dump -U superset superset > superset_backup.sql

# 還原
docker exec -i superset-postgres psql -U superset superset < superset_backup.sql
```

## 更新日誌

- **2026-02-08**: 初始部署