Change platform to rocket.chat

2026-02-01 01:24:56 +08:00
parent f1761cb25d
commit 809a65056d
6 changed files with 1069 additions and 230 deletions
--- a/SETUP_GUIDE.md
+++ b/SETUP_GUIDE.md
@@ -0,0 +1,331 @@
+# 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)