# AWOOOI 部署拓撲與服務位置定義

> **版本**: v1.0
> **建立日期**: 2026-03-20
> **負責人**: CIO
> **強制等級**: 絕對遵守

---

## 概述

**每個服務必須明確定義其部署位置**：
- **Host (主機直裝)**: 直接安裝在主機上的服務
- **Docker**: 使用 Docker / Docker Compose 運行的容器
- **K3s**: 部署在 K3s 叢集中的 Pod

---

## 四主機部署總覽

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                           AWOOOI 部署拓撲圖                                  │
└─────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────┐    ┌─────────────────────────┐
│   192.168.0.110         │    │   192.168.0.112         │
│   DevOps 金庫           │    │   Kali Security         │
├─────────────────────────┤    ├─────────────────────────┤
│ [Docker]                │    │ [Docker]                │
│  ├─ Harbor :5000        │    │  └─ Scanner API :8080   │
│  └─ GH Runner           │    │                         │
└─────────────────────────┘    └─────────────────────────┘
           │                              │
           └──────────────┬───────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                         192.168.0.188                                        │
│                         AI + Web 中心 (Gateway)                              │
├─────────────────────────────────────────────────────────────────────────────┤
│ [Host 直裝]                                                                  │
│  ├─ Nginx (SSL Gateway) :443                                                │
│  └─ PostgreSQL :5432                                                        │
│                                                                              │
│ [Docker]                                                                     │
│  ├─ Ollama :11434                                                           │
│  ├─ OpenClaw :8089                                                          │
│  ├─ OpenClaw Legacy :8088 (凍結)                                            │
│  ├─ Redis Stack :6380                                                       │
│  └─ SigNoz :3301                                                            │
└─────────────────────────────────────────────────────────────────────────────┘
                          │
                          │ Nginx Proxy
                          ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                     K3s 叢集 (192.168.0.120 + 121)                           │
├─────────────────────────────────────────────────────────────────────────────┤
│ [K3s - awoooi-prod Namespace]                                               │
│  ├─ awoooi-web (Frontend) → NodePort :32335                                 │
│  ├─ awoooi-api (Backend)  → NodePort :32334                                 │
│  └─ (未來擴充服務)                                                           │
│                                                                              │
│ [K3s - wooo-aiops Namespace] (凍結)                                         │
│  ├─ Legacy Frontend → NodePort :31235                                       │
│  └─ Legacy API      → NodePort :31234                                       │
└─────────────────────────────────────────────────────────────────────────────┘
```

---

## 服務部署位置詳細定義

### 192.168.0.110 (DevOps 金庫)

| 服務 | 部署方式 | Port | 說明 |
|------|---------|------|------|
| **Harbor** | Docker | 5000 | 映像倉庫，Project: `awoooi/` |
| **GitHub Runner** | Docker | - | CI/CD 執行器，Label: `awoooi-runner` |

```yaml
# docker-compose.yaml (110)
services:
  harbor:
    image: goharbor/harbor:v2.x
    ports:
      - "5000:5000"
    volumes:
      - /data/harbor:/data

  gh-runner:
    image: myoung34/github-runner:latest
    labels:
      - "awoooi-runner"
```

---

### 192.168.0.112 (Kali Security)

| 服務 | 部署方式 | Port | 說明 |
|------|---------|------|------|
| **Scanner API** | Docker | 8080 | 安全掃描 API，Header: `X-Source: awoooi` |

```yaml
# docker-compose.yaml (112)
services:
  scanner-api:
    image: kali-scanner:latest
    ports:
      - "8080:8080"
    environment:
      - ALLOWED_SOURCES=awoooi,wooo-aiops
```

---

### 192.168.0.188 (AI + Web 中心)

| 服務 | 部署方式 | Port | 說明 |
|------|---------|------|------|
| **Nginx** | **Host 直裝** | 443 | SSL Gateway，路由分流 |
| **PostgreSQL** | **Host 直裝** | 5432 | 主資料庫 |
| **Ollama** | Docker | 11434 | 本地 LLM 推理 |
| **OpenClaw** | Docker | 8089 | AI 大腦 (唯一決策中心) |
| **OpenClaw Legacy** | Docker | 8088 | 凍結版本 |
| **Redis Stack** | Docker | 6380 | 快取 + 向量搜尋 |
| **SigNoz** | Docker | 3301 | APM / 觀測平台 |

#### Nginx (Host 直裝)

```bash
# 安裝方式
sudo apt install nginx
sudo systemctl enable nginx

# 配置檔位置
/etc/nginx/conf.d/awoooi-prod.conf
```

#### PostgreSQL (Host 直裝)

```bash
# 安裝方式
sudo apt install postgresql-15
sudo systemctl enable postgresql

# 資料庫
awoooi_prod  # AWOOOI 專用
wooo_aiops   # Legacy (凍結)
```

#### Docker 服務

```yaml
# docker-compose.yaml (188)
services:
  ollama:
    image: ollama/ollama:latest
    ports:
      - "11434:11434"
    volumes:
      - /data/ollama:/root/.ollama
    deploy:
      resources:
        reservations:
          devices:
            - capabilities: [gpu]

  openclaw:
    image: 192.168.0.110:5000/awoooi/openclaw:latest
    ports:
      - "8089:8089"
    environment:
      - OLLAMA_URL=http://localhost:11434
      - REDIS_URL=redis://localhost:6380/10

  openclaw-legacy:
    image: 192.168.0.110:5000/wooo-aiops/openclaw:frozen
    ports:
      - "8088:8088"
    # 凍結版本，不再更新

  redis-stack:
    image: redis/redis-stack:latest
    ports:
      - "6380:6379"
    volumes:
      - /data/redis:/data

  signoz:
    image: signoz/signoz:latest
    ports:
      - "3301:3301"
```

---

### 192.168.0.120 / 121 (K3s 叢集)

| 節點 | 角色 | 說明 |
|------|------|------|
| 192.168.0.120 | Master | K3s 控制平面 + Worker |
| 192.168.0.121 | Worker | HA 備援節點 |

#### K3s Namespace 定義

| Namespace | 用途 | 狀態 |
|-----------|------|------|
| `awoooi-prod` | AWOOOI 正式環境 | **Active** |
| `wooo-aiops` | Legacy 系統 | **凍結** |

#### AWOOOI 服務 (K3s)

| 服務 | Deployment | Service | NodePort |
|------|------------|---------|----------|
| **Frontend** | awoooi-web | awoooi-web-svc | 32335 |
| **Backend** | awoooi-api | awoooi-api-svc | 32334 |

```yaml
# k8s/awoooi-prod/03-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: awoooi-web
  namespace: awoooi-prod
spec:
  replicas: 2
  selector:
    matchLabels:
      app: awoooi-web
  template:
    metadata:
      labels:
        app: awoooi-web
    spec:
      containers:
        - name: web
          image: 192.168.0.110:5000/awoooi/web:${IMAGE_TAG}
          ports:
            - containerPort: 3000
          resources:
            requests:
              cpu: "100m"
              memory: "256Mi"
            limits:
              cpu: "500m"
              memory: "512Mi"

---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: awoooi-api
  namespace: awoooi-prod
spec:
  replicas: 2
  selector:
    matchLabels:
      app: awoooi-api
  template:
    metadata:
      labels:
        app: awoooi-api
    spec:
      containers:
        - name: api
          image: 192.168.0.110:5000/awoooi/api:${IMAGE_TAG}
          ports:
            - containerPort: 8000
          env:
            - name: DATABASE_URL
              valueFrom:
                secretKeyRef:
                  name: awoooi-secrets
                  key: DATABASE_URL
            - name: REDIS_URL
              value: "redis://192.168.0.188:6380/10"
            - name: OLLAMA_URL
              value: "http://192.168.0.188:11434"
            - name: OPENCLAW_URL
              value: "http://192.168.0.188:8088"
          resources:
            requests:
              cpu: "200m"
              memory: "512Mi"
            limits:
              cpu: "1"
              memory: "1Gi"
```

---

## 環境對照表 (最終版)

| 環境 | 用途 | 域名 | 部署位置 |
|------|------|------|---------|
| **Dev** | 本機開發 | `localhost:3000` | 開發者本機 |
| **Prod** | 正式環境 | `awoooi.wooo.work` | K3s (awoooi-prod) |

> ⚠️ **無 UAT 環境**: 測試驗收在 Dev 完成後直接部署 Prod

---

## 網路流量走向

```
用戶 (Internet)
       │
       ▼
┌─────────────────────────────────────────────────────────────────┐
│ Cloudflare (CDN + WAF)                                          │
└─────────────────────────────────────────────────────────────────┘
       │
       ▼ HTTPS :443
┌─────────────────────────────────────────────────────────────────┐
│ 192.168.0.188 - Nginx (Host 直裝)                               │
│ server_name: awoooi.wooo.work                               │
└─────────────────────────────────────────────────────────────────┘
       │
       ├──────────────────────────────────────┐
       │                                      │
       ▼ /api/* → :32334                      ▼ /* → :32335
┌─────────────────────┐              ┌─────────────────────┐
│ awoooi-api (K3s)    │              │ awoooi-web (K3s)    │
│ 120:32334, 121:32334│              │ 120:32335, 121:32335│
└─────────────────────┘              └─────────────────────┘
       │
       ├─────────────────────────────────────────────────┐
       │                    │                            │
       ▼                    ▼                            ▼
┌─────────────┐    ┌─────────────┐              ┌─────────────┐
│ PostgreSQL  │    │ Redis       │              │ Ollama      │
│ 188:5432    │    │ 188:6380    │              │ 188:11434   │
│ (Host)      │    │ (Docker)    │              │ (Docker)    │
└─────────────┘    └─────────────┘              └─────────────┘
                                                       │
                                                       ▼
                                               ┌─────────────┐
                                               │ OpenClaw     │
                                               │ 188:8089    │
                                               │ (Docker)    │
                                               └─────────────┘
```

---

## 部署位置決策原則

| 服務類型 | 建議部署方式 | 原因 |
|---------|-------------|------|
| **Gateway (Nginx)** | Host 直裝 | SSL 終止、效能關鍵 |
| **資料庫 (PostgreSQL)** | Host 直裝 | 資料持久性、備份策略 |
| **AI 服務 (Ollama)** | Docker | GPU 資源管理、版本切換 |
| **應用服務 (Web/API)** | K3s | 水平擴展、滾動更新 |
| **快取 (Redis)** | Docker | 簡易管理、資料可失 |
| **監控 (SigNoz)** | Docker | 獨立運行、不影響業務 |

---

## K8s 資源配置

### Namespace 資源配額

```yaml
# k8s/awoooi-prod/01-namespace-quota.yaml
apiVersion: v1
kind: Namespace
metadata:
  name: awoooi-prod
  labels:
    environment: prod
    system: awoooi
---
apiVersion: v1
kind: ResourceQuota
metadata:
  name: awoooi-prod-quota
  namespace: awoooi-prod
spec:
  hard:
    requests.cpu: "4"
    requests.memory: 8Gi
    limits.cpu: "8"
    limits.memory: 16Gi
    pods: "20"
```

### 零信任網路策略

```yaml
# k8s/awoooi-prod/02-network-policy.yaml
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: prod-isolation-policy
  namespace: awoooi-prod
spec:
  podSelector: {}
  policyTypes:
    - Ingress
    - Egress
  ingress:
    # 僅允許來自 Nginx Gateway (188) 的流量
    - from:
        - ipBlock:
            cidr: 192.168.0.188/32
      ports:
        - protocol: TCP
          port: 3000
        - protocol: TCP
          port: 8000
  egress:
    # 允許訪問 188 主機服務
    - to:
        - ipBlock:
            cidr: 192.168.0.188/32
      ports:
        - protocol: TCP
          port: 5432   # PostgreSQL
        - protocol: TCP
          port: 6380   # Redis
        - protocol: TCP
          port: 11434  # Ollama
        - protocol: TCP
          port: 8089   # OpenClaw
    # 允許訪問 112 安全掃描
    - to:
        - ipBlock:
            cidr: 192.168.0.112/32
      ports:
        - protocol: TCP
          port: 8080
    # 允許 DNS
    - to:
        - namespaceSelector: {}
          podSelector:
            matchLabels:
              k8s-app: kube-dns
      ports:
        - protocol: UDP
          port: 53
```

---

## Nginx 正式環境路由

```nginx
# /etc/nginx/conf.d/awoooi-prod.conf

upstream awoooi_prod_api {
    server 192.168.0.120:32334;
    server 192.168.0.121:32334;
    keepalive 32;
}

upstream awoooi_prod_web {
    server 192.168.0.120:32335;
    server 192.168.0.121:32335;
    keepalive 16;
}

server {
    listen 443 ssl http2;
    server_name awoooi.wooo.work;

    ssl_certificate /etc/nginx/ssl/awoooi.crt;
    ssl_certificate_key /etc/nginx/ssl/awoooi.key;

    # 系統標識
    proxy_set_header X-System "awoooi-prod";

    # SSE 串流優化 (關鍵！)
    location ~ ^/api/v1/(agent|dashboard)/stream {
        proxy_pass http://awoooi_prod_api;
        proxy_buffering off;
        proxy_read_timeout 3600s;
        proxy_send_timeout 3600s;
        proxy_set_header Connection '';
        proxy_http_version 1.1;
        chunked_transfer_encoding on;
        proxy_set_header X-Accel-Buffering no;
    }

    # 一般 API
    location /api/ {
        proxy_pass http://awoooi_prod_api;
        proxy_http_version 1.1;
        proxy_set_header Connection "keep-alive";
    }

    # 前端
    location / {
        proxy_pass http://awoooi_prod_web;
        proxy_http_version 1.1;
    }

    # 共用 Headers
    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;
}
```

---

## 服務啟動順序

```
1. 192.168.0.188 (Host 服務)
   └─ systemctl start nginx
   └─ systemctl start postgresql

2. 192.168.0.188 (Docker 服務)
   └─ docker-compose up -d redis-stack
   └─ docker-compose up -d ollama
   └─ docker-compose up -d openclaw-awoooi
   └─ docker-compose up -d signoz

3. 192.168.0.110 (DevOps)
   └─ docker-compose up -d harbor
   └─ docker-compose up -d gh-runner

4. 192.168.0.112 (Security)
   └─ docker-compose up -d scanner-api

5. 192.168.0.120/121 (K3s)
   └─ kubectl apply -f k8s/awoooi-prod/
```

---

## 驗證清單

```bash
# 1. 驗證 Host 服務
systemctl status nginx
systemctl status postgresql
psql -U postgres -c "SELECT 1"

# 2. 驗證 Docker 服務 (188)
docker ps | grep -E "(ollama|openclaw|redis|signoz)"
curl http://localhost:11434/api/tags
curl http://localhost:8088/health
redis-cli -p 6380 PING

# 3. 驗證 K3s 服務
kubectl get pods -n awoooi-prod
kubectl get svc -n awoooi-prod
curl http://192.168.0.120:32334/health
curl http://192.168.0.120:32335

# 4. 驗證 Nginx 路由
curl -k https://awoooi.wooo.work/api/health
curl -k https://awoooi.wooo.work/
```

---

## 變更記錄

| 日期 | 版本 | 變更 | 作者 |
|------|------|------|------|
| 2026-03-20 | v1.0 | 初版建立，明確定義部署位置 | CIO |

---

*此文件由 CIO 維護，所有服務部署必須遵守此拓撲定義。*