Update

2025-12-20 01:09:27 +08:00
parent 55a527a1b1
commit 506836f22e
9 changed files with 875 additions and 1 deletions
--- a/README.md
+++ b/README.md
@@ -1,2 +1,251 @@
-# tobiichiGPT
+# TobiichiGPT - 人工回覆系統

+將 AI 對話系統改造成由真人管理員回覆的極簡方案。
+
+## 🎯 特色
+
+- ✅ **零修改** - 不需要修改 Open WebUI 程式碼
+- ✅ **極簡化** - 單一 Python 檔案即可運行
+- ✅ **即插即用** - 偽裝成 OpenAI API，直接在 Open WebUI 設定中使用
+- ✅ **視覺化後台** - 美觀的網頁介面供管理員回覆
+
+## 🚀 快速開始
+
+### 方法 1: Docker (推薦)
+
+```powershell
+# 進入 docker-stack 目錄
+cd docker-stack
+
+# 設定環境變數（首次使用）
+Copy-Item .env.example .env
+notepad .env  # 填入 Cloudflare Tunnel Token（若要使用）
+
+# 使用 Docker Compose 啟動
+docker-compose up -d
+
+# 查看日誌
+docker-compose logs -f
+
+# 停止服務
+docker-compose down
+```
+
+### 方法 2: 直接執行
+
+```powershell
+# 1. 進入 docker 目錄
+cd docker
+
+# 2. 安裝依賴
+pip install -r requirements.txt
+
+# 3. 啟動伺服器
+python human_reply_server.py
+```
+
+啟動後會看到：
+```
+🚀 人工回覆伺服器啟動中...
+📌 管理員後台: http://localhost:8000/admin
+📌 API 端點: http://localhost:8000/v1
+```
+
+## 🌐 服務訪問
+
+啟動後可訪問以下服務：
+
+| 服務 | 網址 | 說明 |
+|------|------|------|
+| **Open WebUI** | http://localhost:3000 | 用戶對話介面 |
+| **管理員後台** | http://localhost:8000/admin | 真人回覆訊息 |
+| **NPM 管理面板** | http://localhost:82 | Nginx Proxy Manager |
+| **Cloudflare Tunnel** | 自動連線 | 無需手動訪問 |
+
+預設帳號密碼（NPM）：
+- Email: `admin@example.com`
+- Password: `changeme`
+
+### 在 Open WebUI 中設定
+
+1. 開啟 http://localhost:3000
+2. 進入 **Settings** → **Connections**
+3. 點擊 **+ Add OpenAI Connection**
+4. 填入設定：
+   - **API Base URL**: `http://human-reply-server:8000/v1`
+   - **API Key**: 隨便填 (例如: `sk-human`)
+5. 儲存後，模型列表會出現 **human-admin**
+
+### 開始使用
+
+1. **用戶端**: 在 Open WebUI (http://localhost:3000) 選擇 `human-admin` 模型，發送訊息
+2. **管理員**: 訪問 http://localhost:8000/admin，查看並回覆訊息
+3. **自動刷新**: 後台每 5 秒自動刷新，顯示新訊息
+
+## 📋 運作流程
+
+```
+用戶發送訊息
+    ↓
+Open WebUI 調用 API (轉圈圈等待)
+    ↓
+訊息進入待處理隊列
+    ↓
+管理員在後台看到訊息
+    ↓
+管理員輸入並送出回覆
+    ↓
+API 回傳給 Open WebUI
+    ↓
+用戶收到回覆
+```
+
+## 🔧 技術架構
+
+- **FastAPI**: 輕量級 Python Web 框架
+- **AsyncIO**: 異步等待管理員回覆
+- **偽裝 OpenAI API**: 
+  - `/v1/models` - 模型列表
+  - `/v1/chat/completions` - 聊天完成端點
+
+## 🐳 Docker 部署
+
+### 檔案結構
+```
+tobiichiGPT/
+├── docker/                   # Docker 相關檔案
+│   ├── human_reply_server.py # 主程式
+│   ├── requirements.txt      # Python 依賴
+│   ├── Dockerfile            # Docker 映像檔
+│   └── .dockerignore         # Docker 忽略檔案
+├── docker-stack/             # Docker Compose 配置
+│   ├── docker-compose.yml    # 服務編排檔案
+│   └── .env.example          # 環境變數範例
+├── README.md                 # 專案說明
+├── QUICKSTART.md             # 快速開始指南
+└── LICENSE                   # 授權檔案
+```
+
+### Docker 指令
+
+```powershell
+# 建立映像檔
+cd docker
+docker build -t tobiichi-gpt .
+
+# 直接執行容器
+docker run -d -p 8000:8000 --name tobiichi-gpt tobiichi-gpt
+
+# 使用 Docker Compose（推薦）
+cd .\docker-stack
+docker-compose up -d
+
+# 查看容器狀態
+docker ps
+
+# 查看日誌
+docker logs -f tobiichi-gpt
+
+# 停止並移除
+docker-compose down
+```
+
+### 與 Open WebUI 整合
+
+如果 Open WebUI 也在 Docker 中運行，將兩者加入同一網路：
+
+```yaml
+# 在 docker-compose.yml 中加入 Open WebUI
+version: '3.8'
+
+services:
+  human-reply-server:
+    build: .
+    container_name: tobiichi-gpt
+    ports:
+      - "8000:8000"
+    networks:
+      - tobiichi-network
+
+  open-webui:
+    image: ghcr.io/open-webui/open-webui:main
+    container_name: open-webui
+    ports:
+      - "3000:8080"
+    volumes:
+      - open-webui:/app/backend/data
+    networks:
+      - tobiichi-network
+
+networks:
+  tobiichi-network:
+    driver: bridge
+
+volumes:
+  open-webui:
+```
+
+然後在 Open WebUI 中使用：
+- **API Base URL**: `http://human-reply-server:8000/v1`
+
+## 📝 進階設定
+
+### 修改等待超時時間
+
+編輯 `docker/human_reply_server.py` 第 79 行：
+
+```python
+timeout = 600  # 預設 10 分鐘，可改為其他秒數
+```
+
+### 修改伺服器埠號
+
+**方法 1: 修改 docker-compose.yml**
+```yaml
+# 編輯 docker-stack/docker-compose.yml
+ports:
+  - "9000:8000"  # 本機 9000 對應容器 8000
+```
+
+**方法 2: 修改程式碼**
+```python
+# 編輯 docker/human_reply_server.py
+uvicorn.run(app, host="0.0.0.0", port=8000)  # 改為其他埠號
+```
+
+### 設定 Cloudflare Tunnel
+
+詳細設定步驟請參考專案根目錄的說明文件，或參考 `docker-stack/.env.example`：
+
+```powershell
+cd docker-stack
+Copy-Item .env.example .env
+notepad .env  # 填入您的 CLOUDFLARE_TUNNEL_TOKEN
+```
+
+### 支援多管理員
+
+目前版本採「先搶先贏」機制，任何管理員都可以回覆任何訊息。若需要分配機制，可以加入：
+- 管理員登入系統
+- 訊息認領機制
+- 管理員負載平衡
+
+## ⚠️ 注意事項
+
+- 此為**最簡化版本**，適合小規模使用
+- 訊息儲存在記憶體中，重啟會遺失
+- 沒有身份驗證，建議僅在內網使用
+- 若需生產環境，建議加入：
+  - 資料庫持久化
+  - 身份驗證
+  - WebSocket 即時推送
+  - 訊息隊列系統
+
+## 🎨 管理員後台截圖
+
+後台提供：
+- 待處理訊息列表
+- 用戶訊息顯示
+- 回覆文字框
+- 一鍵送出功能
+- 自動刷新