tobiichiGPT/SETUP_GUIDE.md

# TobiichiGPT - Rocket.Chat 整合指南

## 🚀 快速開始

### 1. 準備環境檔案

```powershell
# 複製環境變數範例
Copy-Item .env.example .env

# 編輯 .env
notepad .env
```

設定以下變數：
```env
DB_PASSWORD=your_secure_password_here
ROCKETCHAT_USER=admin
ROCKETCHAT_PASSWORD=your_secure_password_here
```

### 2. 啟動服務

```powershell
# 啟動所有服務
docker-compose up -d

# 查看啟動狀態
docker-compose ps

# 查看日誌
docker-compose logs -f
```

**啟動順序**：
1. PostgreSQL (資料庫)
2. MongoDB (Rocket.Chat 資料庫)
3. MongoDB Replica Set 初始化
4. Rocket.Chat (管理員介面)
5. API (轉接層)
6. Open WebUI (用戶介面)

### 3. 初始化 Rocket.Chat

訪問 http://localhost:13000

#### 首次設定步驟：

1. **創建管理員帳號**
   - Username: `admin` (必須與 .env 中的 ROCKETCHAT_USER 一致)
   - Password: 設定密碼 (必須與 .env 中的 ROCKETCHAT_PASSWORD 一致)
   - Email: 填寫郵箱

2. **基本設定**
   - Organization Name: TobiichiGPT
   - Language: 繁體中文（可選）
   - Server Type: Private

3. **關閉註冊（可選）**
   - 進入 Administration → Settings → Accounts
   - 關閉 "Allow User Registration"

### 4. 配置 Open WebUI

1. 訪問 http://localhost:10060
2. 首次訪問會要求創建管理員帳號
3. 登入後，進入 **Settings** → **Connections**
4. 新增 OpenAI Connection:
   - **API Base URL**: `http://tobiichiGPT-api:8000/v1`
   - **API Key**: `sk-anything` (任意值即可)
5. 點選 **Save**
6. 模型列表會出現 **tobiichiGPT**

## 💬 使用流程

### 用戶端（Open WebUI）

1. 在 Open WebUI 中選擇 **tobiichiGPT** 模型
2. 開始對話
3. 訊息會被轉發到 Rocket.Chat
4. 等待管理員回覆（畫面會顯示 "Thinking..."）

### 管理員端（Rocket.Chat）

1. 登入 Rocket.Chat: http://localhost:13000
2. 左側會看到新增的用戶頻道，格式為 `#user-{user_id}`
3. 點開頻道，會看到執行緒列表（每個對話一個執行緒）
4. 點開執行緒，查看用戶訊息
5. **在執行緒中回覆**（重要！必須在執行緒內回覆）
6. 回覆後，用戶端會在 3 秒內收到回覆

### 回覆方式說明

**正確回覆方式**：
1. 點擊訊息右側的 **Reply in Thread** 圖標
2. 在執行緒視窗中輸入回覆
3. 按 Enter 送出

**錯誤回覆方式**：
- ❌ 直接在頻道主畫面回覆（不會被系統偵測到）
- ❌ 私訊用戶（系統無法接收）

## 📊 系統監控

### 健康檢查

訪問 http://localhost:18000/health

正常回應：
```json
{
  "status": "healthy",
  "database": "ok",
  "rocketchat": "ok"
}
```

### 查看日誌

```powershell
# API 日誌
docker-compose logs -f api

# Rocket.Chat 日誌
docker-compose logs -f rocketchat

# Open WebUI 日誌
docker-compose logs -f openwebui
```

### 常見日誌訊息

**API 正常運作**：
```
✅ 資料庫連接成功
✅ Rocket.Chat 登入成功
📝 收到訊息
   用戶: 張三
   對話: chat-abc
   內容: 如何學習 Python?...
✅ 創建頻道: user-abc123 (張三)
✅ 創建執行緒訊息: xyz789
✅ 收到管理員回覆
✅ 完成回覆 [chat:chat-abc]
```

**錯誤訊息**：
```
⚠️  Rocket.Chat 登入失敗: 401
❌ Rocket.Chat 頻道操作錯誤: ...
⚠️  等待回覆超時 (600秒)
```

## 🔧 故障排除

### 問題 1: Rocket.Chat 無法啟動

**症狀**：容器一直重啟

**解決方案**：
```powershell
# 檢查 MongoDB 狀態
docker-compose logs mongo

# 重新初始化 Replica Set
docker-compose restart mongo-init-replica
```

### 問題 2: API 無法登入 Rocket.Chat

**症狀**：API 日誌顯示 "Rocket.Chat 登入失敗"

**解決方案**：
1. 確認 Rocket.Chat 已完成初始化
2. 確認 .env 中的 ROCKETCHAT_USER 和 ROCKETCHAT_PASSWORD 正確
3. 重啟 API：
   ```powershell
   docker-compose restart api
   ```

### 問題 3: 管理員回覆後用戶沒收到

**可能原因**：
1. ❌ 沒有在執行緒中回覆（在頻道主畫面回覆）
2. ❌ 回覆的訊息為空

**解決方案**：
1. 確認在執行緒視窗中回覆
2. 確認回覆內容不為空
3. 檢查 API 日誌是否有 "收到管理員回覆"

### 問題 4: 等待超時

**症狀**：用戶收到 "抱歉，目前客服繁忙，請稍後再試。"

**原因**：管理員在 10 分鐘內未回覆

**解決方案**：
- 修改 `api/server.py` 第 timeout 參數（預設 600 秒）
- 或者加快回覆速度

### 問題 5: Open WebUI 無法連接 API

**症狀**：模型列表為空或顯示錯誤

**解決方案**：
1. 確認 API URL 正確: `http://tobiichiGPT-api:8000/v1`
2. 檢查容器網路：
   ```powershell
   docker network inspect tobiichiGPT-network
   ```
3. 測試 API：
   ```powershell
   curl http://localhost:18000/v1/models
   ```

## 🎨 進階配置

### 修改等待超時時間

編輯 `api/server.py`：

```python
async def wait_for_thread_reply(room_id: str, thread_id: str, timeout: int = 600):
    # 改為 1200 秒（20 分鐘）
    timeout: int = 1200
```

### 修改檢查間隔

編輯 `api/server.py`：

```python
async def wait_for_thread_reply(room_id: str, thread_id: str, timeout: int = 600):
    check_interval = 3  # 改為 5 秒檢查一次
```

### 自訂頻道名稱格式

編輯 `api/server.py`：

```python
async def get_or_create_channel(user_id: str, user_name: str = None):
    # 原本: channel_name = f"user-{user_id[:8]}"
    # 改為使用用戶名稱
    channel_name = f"{user_name}" if user_name else f"user-{user_id[:8]}"
```

## 📦 資料持久化

所有資料都會持久化保存：

```
/mnt/data/External/tobiichiGPT/
├── db_data/          # PostgreSQL 資料
├── mongo_data/       # Rocket.Chat 資料
├── api_data/         # API 程式碼
└── ui_data/          # Open WebUI 資料
```

## 🔄 更新與維護

### 更新 API 程式碼

```powershell
# 編輯程式碼
notepad api\server.py

# 重啟服務
docker-compose restart api

# 查看日誌確認
docker-compose logs -f api
```

### 更新 Docker 映像

```powershell
# 拉取最新映像
docker-compose pull

# 重新啟動
docker-compose up -d
```

### 備份資料

```powershell
# 備份 PostgreSQL
docker exec tobiichiGPT-postgres pg_dump -U tobiichi3227 tobiichiGPT > backup.sql

# 備份 MongoDB
docker exec tobiichiGPT-mongo mongodump --out /backup
```

## 🎯 效能優化

### 建議配置

**最小需求**：
- CPU: 2 核心
- RAM: 4 GB
- 磁碟: 20 GB

**推薦配置**：
- CPU: 4 核心
- RAM: 8 GB
- 磁碟: 50 GB

### 容器資源限制

編輯 `docker-compose.yml` 加入：

```yaml
rocketchat:
  # ... 其他設定
  deploy:
    resources:
      limits:
        cpus: '2'
        memory: 2G
      reservations:
        cpus: '0.5'
        memory: 512M
```

## 📞 技術支援

- GitHub Issues: [open-webui/open-webui](https://github.com/open-webui/open-webui/issues)
- Rocket.Chat 文檔: [docs.rocket.chat](https://docs.rocket.chat)
- Discord: [Rocket.Chat Community](https://discord.gg/rocketchat)