tobiichiGPT/SETUP_GUIDE.md

TobiichiGPT - Rocket.Chat 整合指南

🚀 快速開始

1. 準備環境檔案

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

# 編輯 .env
notepad .env

設定以下變數：

DB_PASSWORD=your_secure_password_here
ROCKETCHAT_USER=admin
ROCKETCHAT_PASSWORD=your_secure_password_here

2. 啟動服務

# 啟動所有服務
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

正常回應：

{
  "status": "healthy",
  "database": "ok",
  "rocketchat": "ok"
}

查看日誌

# 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 無法啟動

症狀：容器一直重啟

解決方案：

# 檢查 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：

   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. 檢查容器網路：

   docker network inspect tobiichiGPT-network
   

3. 測試 API：

   curl http://localhost:18000/v1/models
   

🎨 進階配置

修改等待超時時間

編輯 api/server.py：

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

修改檢查間隔

編輯 api/server.py：

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

自訂頻道名稱格式

編輯 api/server.py：

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 程式碼

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

# 重啟服務
docker-compose restart api

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

更新 Docker 映像

# 拉取最新映像
docker-compose pull

# 重新啟動
docker-compose up -d

備份資料

# 備份 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 加入：

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

📞 技術支援

• GitHub Issues: open-webui/open-webui
• Rocket.Chat 文檔: docs.rocket.chat
• Discord: Rocket.Chat Community