291 lines
10 KiB
Markdown
291 lines
10 KiB
Markdown
# 工程師交接說明
|
||
|
||
## 後臺方案更換建議：Streamlit
|
||
|
||
若未來認為 Rocket.Chat 部署過重或整合不便，可轉用 **Streamlit** 開發自定義管理後台。此方案能針對 Open WebUI 的資料結構進行 100% 客製化。
|
||
|
||
### 核心優勢
|
||
|
||
1. **極簡開發**：純 Python 即可構建前端，約 200 行程式碼可完成完整後台。
|
||
2. **超輕量級**：單一容器（~100MB 記憶體），無需額外資料庫（直接讀取現有 Postgres）。
|
||
3. **完全客製**：可完美呈現「用戶 → 對話 → 訊息」的三層結構，不受限於聊天軟體的頻道邏輯。
|
||
4. **部署簡單**：標準 Docker image `python:3.11-slim` + `pip install streamlit`。
|
||
|
||
### 實作架構
|
||
|
||
* **前端**：Streamlit Web App (Port 8501)
|
||
* **後端邏輯**：直連 PostgreSQL `reply_queue` 表格
|
||
* **功能**：自動刷新、用戶篩選、歷史回覆查詢
|
||
|
||
### 程式碼範例 (admin.py)
|
||
|
||
```python
|
||
import streamlit as st
|
||
import psycopg2
|
||
import pandas as pd
|
||
|
||
# 自動刷新設定 (每 5 秒)
|
||
from streamlit_autorefresh import st_autorefresh
|
||
st_autorefresh(interval=5000, key="msg_refresh")
|
||
|
||
st.set_page_config(layout="wide", page_title="TobiichiGPT Admin")
|
||
|
||
# 1. 連接資料庫
|
||
conn = psycopg2.connect("postgresql://user:pass@postgres:5432/tobiichiGPT")
|
||
|
||
# 2. 側邊欄：用戶列表
|
||
st.sidebar.title("用戶列表")
|
||
users = pd.read_sql("SELECT DISTINCT user_id FROM reply_queue", conn)
|
||
selected_user = st.sidebar.radio("選擇用戶", users['user_id'])
|
||
|
||
# 3. 主畫面：顯示該用戶的對話
|
||
if selected_user:
|
||
st.header(f"用戶: {selected_user}")
|
||
|
||
# 撈取該用戶訊息
|
||
msgs = pd.read_sql(
|
||
f"SELECT * FROM reply_queue WHERE user_id='{selected_user}' ORDER BY created_at DESC",
|
||
conn
|
||
)
|
||
|
||
for _, row in msgs.iterrows():
|
||
with st.expander(f"對話 {row['chat_id']} ({row['status']})", expanded=True):
|
||
st.info(f"用戶: {row['user_message']}")
|
||
|
||
if row['status'] == 'pending':
|
||
with st.form(key=f"form_{row['id']}"):
|
||
reply = st.text_area("回覆內容")
|
||
if st.form_submit_button("送出"):
|
||
# 更新資料庫
|
||
cur = conn.cursor()
|
||
cur.execute(
|
||
"UPDATE reply_queue SET admin_reply=%s, status='replied' WHERE id=%s",
|
||
(reply, row['id'])
|
||
)
|
||
conn.commit()
|
||
st.success("已回覆")
|
||
st.rerun()
|
||
else:
|
||
st.success(f"管理員: {row['admin_reply']}")
|
||
```
|
||
|
||
### 部署配置 (Docker)
|
||
|
||
**Dockerfile**:
|
||
```dockerfile
|
||
FROM python:3.11-slim
|
||
WORKDIR /app
|
||
RUN pip install streamlit psycopg2-binary pandas streamlit-autorefresh
|
||
COPY admin.py .
|
||
CMD ["streamlit", "run", "admin.py", "--server.port=8501", "--server.address=0.0.0.0"]
|
||
```
|
||
|
||
**docker-compose.yml**:
|
||
```yaml
|
||
admin-ui:
|
||
build: ./admin-ui
|
||
ports: ["8501:8501"]
|
||
environment:
|
||
- DB_HOST=postgres
|
||
- DB_PASSWORD=${DB_PASSWORD}
|
||
networks:
|
||
- tobiichiGPT-network
|
||
```
|
||
|
||
### 與 Rocket.Chat/Chatwoot比較
|
||
|
||
| 特性 | Streamlit (自建) | Rocket.Chat | Chatwoot |
|
||
| :--- | :--- | :--- | :--- |
|
||
| **對應 Open WebUI 結構** | ⭐⭐⭐⭐⭐ (完全貼合) | ⭐⭐⭐ (需用頻道模擬) | ⭐ (結構扁平) |
|
||
| **即時性** | ⭐⭐ (輪詢刷新) | ⭐⭐⭐⭐⭐ (WebSocket) | ⭐⭐⭐⭐⭐ (WebSocket) |
|
||
| **手機 App** | ⭐ (網頁版) | ⭐⭐⭐⭐⭐ (原生 App) | ⭐⭐⭐⭐⭐ (原生 App) |
|
||
| **資源消耗** | 低 (~100MB) | 中 (~500MB) | 高 (~1GB) |
|
||
| **適用場景** | 單人/少數管理員，追求輕量與精準管理 | 多人團隊協作，需要 App 通知 | 專業客服團隊 |
|
||
|
||
### 建議切換時機
|
||
|
||
若遇到以下情況，建議切換至 Streamlit 方案：
|
||
1. Rocket.Chat 的頻道/執行緒管理變得混亂，難以追蹤用戶對話。
|
||
2. 伺服器資源不足，無法負擔 Rocket.Chat + MongoDB。
|
||
3. 需要針對特定業務邏輯（如：查看用戶餘額、審核特定關鍵字）進行客製化開發。
|
||
|
||
## Rocket.Chat 實作紀錄
|
||
|
||
### 實作日期
|
||
2026年2月1日
|
||
|
||
### 系統架構
|
||
|
||
```
|
||
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
|
||
│ Open WebUI │────▶│ API 轉接層 │────▶│ Rocket.Chat │
|
||
│ (Port 10060) │ │ (Port 18000) │ │ (Port 13000) │
|
||
│ 用戶前端 │◀────│ FastAPI │◀────│ 管理員後台 │
|
||
└─────────────────┘ └──────────────────┘ └─────────────────┘
|
||
│ │
|
||
▼ ▼
|
||
┌──────────────────┐ ┌─────────────────┐
|
||
│ PostgreSQL │ │ MongoDB │
|
||
│ (Port 5432) │ │ (Port 27017) │
|
||
└──────────────────┘ └─────────────────┘
|
||
```
|
||
|
||
### 工作流程
|
||
|
||
1. **用戶發送訊息** → Open WebUI 呼叫 `/v1/chat/completions`
|
||
2. **API 轉接層接收** → 提取用戶資訊 (user_name, chat_id)
|
||
3. **創建 Rocket.Chat 頻道** → 頻道名稱: `{用戶名}-{對話ID前8位}`
|
||
4. **發送用戶訊息** → 顯示格式: `💬 用戶名: 訊息內容`
|
||
5. **輪詢等待回覆** → 每 2 秒檢查是否有管理員新訊息
|
||
6. **回傳給用戶** → 以 OpenAI 格式回傳管理員的回覆
|
||
|
||
### 已完成的修改
|
||
|
||
#### 1. docker-compose.yml
|
||
|
||
**新增服務：**
|
||
- `mongo`: MongoDB 7.0 (Rocket.Chat 8.0.1 需要 7.0+)
|
||
- `mongo-init-replica`: 初始化 MongoDB Replica Set
|
||
- `rocketchat`: Rocket.Chat 8.0.1
|
||
|
||
**修改服務：**
|
||
- `openwebui`: 新增 `ENABLE_FORWARD_USER_INFO_HEADERS=True` 環境變數
|
||
|
||
**關鍵配置：**
|
||
```yaml
|
||
mongo:
|
||
image: mongo:7.0 # 從 5.0 升級，因為 Rocket.Chat 8.0.1 不支援 5.0
|
||
command: mongod --oplogSize 128 --replSet rs0
|
||
|
||
rocketchat:
|
||
image: registry.rocket.chat/rocketchat/rocket.chat:latest
|
||
ports:
|
||
- "13000:3000"
|
||
environment:
|
||
MONGO_URL: mongodb://mongo:27017/rocketchat?replicaSet=rs0
|
||
MONGO_OPLOG_URL: mongodb://mongo:27017/local?replicaSet=rs0
|
||
|
||
openwebui:
|
||
environment:
|
||
- ENABLE_FORWARD_USER_INFO_HEADERS=True # 轉發用戶資訊到 API
|
||
```
|
||
|
||
#### 2. api/server.py
|
||
|
||
**新增 imports：**
|
||
```python
|
||
import json
|
||
import hashlib
|
||
```
|
||
|
||
**核心函數重寫：**
|
||
|
||
| 函數名稱 | 功能說明 |
|
||
|---------|---------|
|
||
| `rocketchat_login()` | 使用帳密登入 Rocket.Chat，取得 Auth Token |
|
||
| `get_or_create_chat_channel()` | 為每個對話創建專屬頻道 (不使用 Thread) |
|
||
| `send_user_message()` | 發送用戶訊息到頻道，回傳訊息 ID |
|
||
| `wait_for_admin_reply()` | 輪詢等待管理員回覆，過濾機器人訊息 |
|
||
|
||
**Headers 提取邏輯：**
|
||
```python
|
||
# Open WebUI 轉發的 Headers
|
||
user_id = headers_dict.get("x-openwebui-user-id")
|
||
chat_id = headers_dict.get("x-openwebui-chat-id")
|
||
user_name = headers_dict.get("x-openwebui-user-name")
|
||
user_email = headers_dict.get("x-openwebui-user-email")
|
||
```
|
||
|
||
**系統任務過濾：**
|
||
```python
|
||
# 跳過 Open WebUI 的標題/標籤/後續問題生成請求
|
||
if user_message.strip().startswith("### Task:"):
|
||
return {"choices": [{"message": {"content": "{}"}}], ...}
|
||
```
|
||
|
||
### 遇到的問題與解決方案
|
||
|
||
#### 問題 1: MongoDB 版本不相容
|
||
- **錯誤**: `MongoServerSelectionError`
|
||
- **原因**: Rocket.Chat 8.0.1 需要 MongoDB 7.0+，但配置的是 5.0
|
||
- **解決**: 將 `mongo:5.0` 升級為 `mongo:7.0`
|
||
|
||
#### 問題 2: postMessage 返回 400 錯誤
|
||
- **錯誤**: `alias` 參數需要特殊權限
|
||
- **原因**: Rocket.Chat API 的 `alias` 欄位需要 bot 權限
|
||
- **解決**: 移除 `alias` 參數，改用訊息內文標註用戶名
|
||
|
||
#### 問題 3: Open WebUI 不發送用戶資訊 Headers
|
||
- **錯誤**: `user_name` 始終為 `None`
|
||
- **原因**: Open WebUI 預設不轉發用戶資訊
|
||
- **解決**: 設置環境變數 `ENABLE_FORWARD_USER_INFO_HEADERS=True`
|
||
|
||
#### 問題 4: 奇怪的系統訊息被發送到 Rocket.Chat
|
||
- **錯誤**: `### Task: Generate a concise title...` 等訊息出現
|
||
- **原因**: Open WebUI 會額外發送標題/標籤/後續問題生成請求
|
||
- **解決**: 過濾以 `### Task:` 開頭的訊息，直接回傳空 JSON
|
||
|
||
#### 問題 5: 重複回傳相同的管理員回覆
|
||
- **錯誤**: 每次用戶訊息都收到同一個回覆
|
||
- **原因**: Thread 架構複雜，難以正確追蹤新回覆
|
||
- **解決**: 改用簡化架構 (每個對話一個 Channel，不用 Thread)
|
||
|
||
### 最終架構決策
|
||
|
||
**放棄 Thread 架構，改用 Channel 架構：**
|
||
|
||
| 項目 | Thread 架構 (放棄) | Channel 架構 (採用) |
|
||
|-----|-------------------|-------------------|
|
||
| 結構 | 用戶→頻道→多個Thread | 對話→專屬頻道 |
|
||
| 追蹤 | 需要追蹤 Thread ID | 只需追蹤訊息 ID |
|
||
| 複雜度 | 高 | 低 |
|
||
| 可讀性 | 中 (Thread 內對話) | 高 (直接看頻道) |
|
||
|
||
**頻道命名規則：**
|
||
```
|
||
{用戶名小寫}-{chat_id前8位}
|
||
例: ckliu-67b4341e
|
||
```
|
||
|
||
### 待辦事項
|
||
|
||
- [ ] 實作管理員回覆後的通知機制
|
||
- [ ] 處理超時後的重試邏輯
|
||
- [ ] 新增管理員身份驗證 (目前使用單一 admin 帳號)
|
||
- [ ] 考慮切換到 Streamlit 方案 (更輕量、完全客製化)
|
||
|
||
### 相關檔案
|
||
|
||
```
|
||
tobiichiGPT/
|
||
├── docker-compose.yml # 容器編排配置
|
||
├── api/
|
||
│ ├── server.py # API 轉接層主程式
|
||
│ └── requirements.txt # Python 依賴
|
||
└── exchange.md # 本文件
|
||
```
|
||
|
||
### 環境變數清單
|
||
|
||
| 變數名稱 | 用途 | 預設值 |
|
||
|---------|------|-------|
|
||
| `ROCKETCHAT_URL` | Rocket.Chat API 位址 | `http://rocketchat:3000` |
|
||
| `ROCKETCHAT_USER` | 登入帳號 | `admin` |
|
||
| `ROCKETCHAT_PASSWORD` | 登入密碼 | `admin` |
|
||
| `DB_HOST` | PostgreSQL 主機 | `postgres` |
|
||
| `DB_PASSWORD` | 資料庫密碼 | (必填) |
|
||
|
||
### 測試指令
|
||
|
||
```bash
|
||
# 重建並重啟 API 容器
|
||
cd /mnt/data/External/tobiichiGPT
|
||
sudo docker-compose up -d --build api
|
||
|
||
# 查看 API 日誌
|
||
sudo docker logs tobiichiGPT-api --tail 100
|
||
|
||
# 重啟 Open WebUI (套用 Headers 設定)
|
||
sudo docker-compose up -d openwebui
|
||
```
|