繁體中文

简体中文
English

繁體中文

简体中文
English

Appearance

技術架構 ​

CueMate 採用現代化的微服務架構設計，實現高效能、高可用、易擴充套件的智慧面試訓練工具。

1. 整體架構圖 ​

使用者層
桌面安裝器
(Electron)
系統檢測
Docker 管理
服務部署
版本更新
桌面用戶端
(Electron)
音訊擷取
即時識別顯示
懸浮視窗互動
本地儲存
主視窗應用
(React)
帳戶管理
系統配置
資料統計
知識庫管理
WebSocket/HTTP/HTTPS
Docker 服務管理
閘道層 (Nginx)
應用服務層
Web API
(3001)
使用者認證
業務邏輯
資料管理
LLM Router
(3002)
模型路由
串流回應
降級策略
RAG Service
(3003)
文件向量化
語意檢索
答案增強
SQLite 資料庫
使用者資料
面試記錄
知識庫元資料
系統配置
外部 LLM
OpenAI
Claude
Gemini
國內大型模型
本地模型
ChromaDB
向量資料庫
向量索引
文件儲存
相似度檢索
語音識別服務
cuemate-asr (10095)
本地語音識別中英文支援即時串流處理
文件與支援
線上文件
使用指南模型配置常見問題

2. 分層架構 ​

2.1 使用者層 ​

2.1.1 桌面安裝器 ​

macOS 平臺：

安裝包型別：

  • 線上安裝包：約 670MB，需聯網拉取 Docker 映象，適合網路良好的環境
  • 離線安裝包：約 4.4GB，包含所有 Docker 映象，開箱即用，適合網路受限環境

核心職責：

  1. 引導使用者完成首次安裝
  2. 檢測並安裝 Docker Desktop
  3. 自動部署後端 Docker 服務（本地或遠端伺服器）
  4. 管理系統版本更新

工作流程：

  1. 檢測系統環境（macOS 版本、晶片架構、可用空間）
  2. 檢測 Docker Desktop 狀態（未安裝/已安裝/需更新）
  3. 檢測埠占用情況（3001、3002、3003、3004、8000、10095）
  4. 選擇部署模式（本地模式/分散式模式）
  5. 拉取或載入 Docker 映象並啟動服務
  6. 驗證服務健康狀態

Windows 平臺：

安裝包型別：

  • 線上安裝包：約 700MB，需聯網拉取 Docker 映象，適合網路良好的環境
  • 離線安裝包：約 4.5GB，包含所有 Docker 映象，開箱即用，適合網路受限環境

核心職責：

  1. 引導使用者完成首次安裝
  2. 檢測並安裝 WSL 2 和 Docker Desktop
  3. 自動部署後端 Docker 服務（本地或遠端伺服器）
  4. 管理系統版本更新
  5. 支援自訂安裝路徑

工作流程：

  1. 檢測系統環境（Windows 版本、系統架構、可用空間）
  2. 檢測 WSL 2 狀態（未安裝/已安裝/需更新）
  3. 檢測 Docker Desktop 狀態（未安裝/已安裝/需更新）
  4. 選擇安裝路徑（支援自訂非 C 碟安裝）
  5. 檢測埠占用情況（3001、3002、3003、3004、8000、10095）
  6. 選擇部署模式（本地模式/分散式模式）
  7. 拉取或載入 Docker 映象並啟動服務
  8. 驗證服務健康狀態

2.1.2 桌面客戶端 ​

macOS 平臺：

核心功能：

  1. 全域性快捷鍵和懸浮窗
  2. 麥克風音訊採集
  3. 系統音訊捕獲（AudioTee）
  4. 實時語音識別顯示
  5. 本地語音合成（Piper TTS）
  6. 系統托盤整合

資料儲存：

  • 應用資料：~/Library/Application Support/cuemate-desktop-client
  • SQLite 資料庫：~/Library/Application Support/cuemate-desktop-client/data/sqlite/cuemate.db
  • 日誌檔案：~/Library/Application Support/cuemate-desktop-client/data/logs

Windows 平臺：

核心功能：

  1. 全域性快捷鍵和懸浮窗
  2. 麥克風音訊採集
  3. 系統音訊捕獲（Electron Audio Loopback）
  4. 實時語音識別顯示
  5. 本地語音合成（Piper TTS）
  6. 系統托盤整合

資料儲存：

  • 應用資料：%APPDATA%\cuemate-desktop-client
  • SQLite 資料庫：%APPDATA%\cuemate-desktop-client\data\sqlite\cuemate.db
  • 日誌檔案：%APPDATA%\cuemate-desktop-client\data\logs

2.1.3 主視窗應用 ​

核心功能：

  1. 使用者註冊和登入
  2. 模型配置管理
  3. 知識庫文件上傳
  4. 預置題庫管理
  5. 面試記錄檢視
  6. 系統設定配置
  7. 資料統計分析

2.2 閘道器層 ​

2.2.1 Nginx 反向代理 ​

執行方式：Docker 容器（cuemate-web）

埠：3004

職責：

  1. 提供 Web 前端靜態檔案服務
  2. API 請求路由和轉發
  3. WebSocket 連線代理

2.3 應用服務層 ​

2.3.1 Web API 服務 ​

執行方式：Docker 容器（cuemate-web-api）

埠：3001

核心職責：

  1. 使用者認證和授權（JWT Token）
  2. 業務邏輯處理
  3. 資料持久化（SQLite）
  4. REST API 介面提供

主要功能模組：

  1. 使用者管理（登入、個人資訊）
  2. 模型配置管理（新增、編輯、刪除、測試）
  3. 知識庫管理（文件上傳、分類、檢索）
  4. 面試記錄管理（建立、查詢、統計）
  5. 系統設定管理（通知、主題、語言）

2.3.2 LLM Router 服務 ​

執行方式：Docker 容器（cuemate-llm-router）

埠：3002

核心職責：

  1. 統一的 LLM 呼叫介面
  2. 多模型服務商適配（24 個）
  3. 流式響應處理（Server-Sent Events）
  4. 基礎錯誤處理和狀態監控
  5. 請求超時控制

支援的 LLM 服務商：24 個

  • 國際服務商：OpenAI、Azure OpenAI、Anthropic、Google Gemini、AWS Bedrock
  • 國內服務商：阿里雲百鍊、智譜 AI、百川智慧、百度千帆、位元組豆包、訊飛星火、騰訊混元、騰訊雲知識引擎、Kimi、MiniMax、DeepSeek、商湯日日新、階躍星辰、矽基流動
  • 本地模型：Ollama、vLLM、Xinference、Regolo

工作機制：

  1. 接收前端指定的 provider 和 model 引數
  2. 根據 provider 選擇對應的介面卡
  3. 呼叫相應的 LLM API 並返回結果
  4. 失敗時記錄錯誤日誌和狀態資訊
  5. 支援流式和非流式兩種呼叫模式

2.3.3 RAG 服務 ​

執行方式：Docker 容器（cuemate-rag-service）

埠：3003

核心職責：

  1. 文件解析和分塊處理
  2. 文字向量化
  3. 語義檢索
  4. 答案增強生成
  5. 知識庫版本管理

工作流程：

  1. 接收文件上傳（PDF、DOCS、Markdown、純文字）
  2. 提取文字內容並智慧分塊
  3. 使用嵌入模型生成向量
  4. 儲存到 ChromaDB 向量資料庫
  5. 提供語義檢索介面
  6. 結合檢索結果增強 LLM 回答

2.4 資料層 ​

2.4.1 SQLite 資料庫 ​

執行位置：宿主機檔案系統

儲存路徑：

  • macOS：~/Library/Application Support/cuemate-desktop-client/data/sqlite/cuemate.db
  • Windows：%APPDATA%\cuemate-desktop-client\data\sqlite\cuemate.db

儲存內容：

  1. 使用者賬戶資訊
  2. 模型配置資訊
  3. 面試記錄資料
  4. 知識庫後設資料
  5. 系統配置引數

2.4.2 ChromaDB 向量資料庫 ​

執行方式：Docker 容器（cuemate-chroma）

埠：8000

儲存方式：Docker Volume（chroma_data）

儲存內容：

  1. 文件向量索引
  2. 文件原始內容
  3. 文件後設資料
  4. 相似度檢索快取

2.4.3 外部 LLM API ​

呼叫方式：HTTP/HTTPS API 請求

支援的服務：共 24 個服務商

國際服務商（5 個）：

  1. OpenAI（GPT 系列）
  2. Anthropic（Claude 系列）
  3. Azure OpenAI（微軟 Azure 託管的 OpenAI 模型）
  4. Google Gemini（Google AI 平臺）
  5. AWS Bedrock（AWS 多模型託管平臺）

國內服務商（15 個）：

  1. Moonshot（Kimi 月之暗面）
  2. 阿里雲百鍊（Alibaba Cloud Bailian）
  3. 通義千問（Qwen）
  4. 智譜 AI（GLM 系列）
  5. DeepSeek（深度求索）
  6. 百度千帆（Baidu Qianfan）
  7. 位元組豆包（Volcengine）
  8. 訊飛星火（Xunfei Spark）
  9. 騰訊混元（Tencent Hunyuan）
  10. 騰訊雲知識引擎（Tencent Cloud）
  11. MiniMax（稀宇科技）
  12. 階躍星辰（StepFun）
  13. 商湯日日新（SenseNova）
  14. 百川智慧（Baichuan）
  15. 矽基流動（SiliconFlow）

本地模型服務（4 個）：

  1. Ollama（本地模型執行時）
  2. vLLM（高效能推理引擎）
  3. Xinference（Xorbits 推理框架）
  4. Regolo（本地模型服務）

2.5 外部服務層 ​

2.5.1 語音識別服務 ​

執行方式：Docker 容器（cuemate-asr）

埠：10095

通訊協議：WebSocket

核心特點：

  1. 本地執行，無需雲端 API
  2. 支援中文和英文識別
  3. 實時流式識別
  4. 低延遲（< 200ms）

3. 資料流 ​

3.1 系統安裝流程 ​

1. 下載安裝包
   使用者 → 官網/百度網盤/GitHub Releases → 下載 DMG

2. 啟動安裝器
   使用者 → 開啟 DMG → 拖拽到應用程式資料夾 → 啟動

3. 環境檢測
   安裝器 → 檢測系統環境（macOS 版本、晶片架構、可用空間 或 Windows 版本、系統架構、可用空間）

4. Docker 檢測
   安裝器 → 檢測 Docker Desktop 狀態 → 未安裝則引導安裝

5. 埠檢測
   安裝器 → 檢測 6 個埠占用情況 → 提示解決衝突

6. 服務部署
   安裝器 → 拉取 Docker 映象 → 啟動 6 個容器

7. 健康檢查
   安裝器 → 驗證服務狀態 → 顯示安裝完成

8. 啟動應用
   使用者 → 開啟桌面客戶端 → 開始使用

3.2 實時面試訓練流程 ​

1. 音訊採集
   桌面客戶端 → 捕獲麥克風/系統音訊

2. 語音識別
   音訊流 → WebSocket → cuemate-asr (10095) → 實時文字轉錄

3. 問題理解
   轉錄文字 → LLM Router (3002) → 提取問題意圖

4. 知識檢索
   問題 → RAG Service (3003) → ChromaDB (8000) → 相關文件片段

5. 答案生成
   問題 + 上下文 → LLM Router → 外部 LLM API → 生成答案

6. 流式返回
   LLM 流式輸出 → Server-Sent Events → 桌面客戶端 → 實時顯示

7. 資料持久化
   面試記錄 → Web API (3001) → SQLite 資料庫 → 儲存

3.3 知識庫管理流程 ​

1. 文件上傳
   使用者 → 主視窗應用 (3004) → 上傳 PDF/Word/Markdown 檔案

2. 檔案解析
   檔案 → Web API (3001) → 儲存到臨時目錄

3. 文件處理
   檔案路徑 → RAG Service (3003) → 提取文字內容

4. 智慧分塊
   長文字 → 按語義邊界分塊 → 保持上下文完整性

5. 向量化
   文字塊 → 嵌入模型 → 生成向量表示

6. 儲存索引
   向量 + 原文 + 後設資料 → ChromaDB (8000) → 持久化儲存

7. 後設資料管理
   文件資訊（標題、分類、上傳時間） → Web API → SQLite 資料庫

8. 檢索驗證
   測試查詢 → 驗證檢索效果 → 調整引數

3.4 版本更新流程 ​

1. 檢測更新
   桌面客戶端 → 定期檢查更新伺服器 → 發現新版本

2. 下載更新包
   桌面客戶端 → 從 CDN/GitHub 下載 → 儲存到臨時目錄

3. 校驗完整性
   更新包 → SHA256 校驗 → 確保檔案完整

4. 停止服務
   安裝器 → 停止 Docker 容器 → 備份當前配置

5. 替換檔案
   安裝器 → 解壓更新包 → 替換應用檔案和 Docker 映象

6. 啟動服務
   安裝器 → 啟動新版本容器 → 驗證健康狀態

7. 資料遷移
   安裝器 → 執行資料庫遷移指令碼 → 更新版本號

8. 重啟應用
   桌面客戶端 → 重新啟動 → 顯示新版本

4. 技術特點 ​

4.1 微服務架構 ​

優勢：

  1. 服務獨立部署，互不影響
  2. 按需水平擴充套件，增加服務例項
  3. 故障隔離，單個服務異常不影響整體
  4. 技術棧靈活，可按需選擇最適合的語言和框架

4.2 容器化部署 ​

實現方式：Docker + Docker Compose

優勢：

  1. 一鍵啟動所有服務
  2. 環境一致性保證（開發、測試、生產）
  3. 資源隔離和限制
  4. 快速回滾和版本切換

服務列表：

  1. cuemate-web（Web 前端 + Nginx）
  2. cuemate-web-api（業務 API）
  3. cuemate-llm-router（大模型路由）
  4. cuemate-rag-service（知識庫檢索）
  5. cuemate-asr（語音識別）
  6. cuemate-chroma（向量資料庫）

4.3 部署模式 ​

本地模式（預設）：

  • Docker 服務執行在本地機器（macOS 或 Windows）
  • 桌面客戶端直接訪問 localhost
  • 適合個人使用，資料完全本地化
  • 無需額外伺服器資源

分散式模式：

  • Docker 服務部署到遠端 Linux 伺服器
  • 桌面客戶端透過 SSH 隧道安全連線
  • 適合團隊共享或效能要求高的場景
  • 支援密碼或私鑰兩種 SSH 認證方式
  • 伺服器配置透過系統設定或托盤選單管理

4.4 實時通訊 ​

技術方案：

  1. WebSocket - 雙向實時通訊（語音識別）
  2. Server-Sent Events - 單向流式推送（LLM 回答）
  3. HTTP/HTTPS - 標準 API 請求

應用場景：

  1. 實時語音轉文字（WebSocket）
  2. 流式答案生成（SSE）
  3. 資料查詢和修改（HTTP）

4.5 混合儲存 ​

儲存方案：

  1. SQLite - 結構化資料（使用者、配置、記錄）
  2. ChromaDB - 向量資料（文件嵌入、語義檢索）
  3. 檔案系統 - 日誌檔案、臨時檔案、上傳檔案

資料路徑：

  • SQLite：
    • macOS：~/Library/Application Support/cuemate-desktop-client/data/sqlite/
    • Windows：%APPDATA%\cuemate-desktop-client\data\sqlite\
  • ChromaDB：Docker Volume chroma_data
  • 日誌：
    • macOS：~/Library/Application Support/cuemate-desktop-client/data/logs/
    • Windows：%APPDATA%\cuemate-desktop-client\data\logs\

4.6 安全設計 ​

安全措施：

  1. API Key 加密儲存（AES-256）
  2. JWT Token 身份認證
  3. HTTPS 加密傳輸（生產環境）
  4. 許可權細粒度控制（RBAC）
  5. 敏感資料本地儲存（不上傳雲端）

4.7 可觀測性 ​

監控方案：

  1. 統一日誌收集（按級別分類：info、warn、error）
  2. 服務健康檢查（定時探測服務狀態）
  3. 錯誤追蹤和告警（異常自動記錄）
  4. 使用統計分析（API 呼叫次數、Token 消耗）

5. 效能最佳化 ​

5.1 快取策略 ​

快取內容：

  1. LLM 響應快取（相同問題直接返回，節省成本）
  2. 向量檢索結果快取（加速重複查詢）
  3. 靜態檔案 CDN 加速（提升頁面載入速度）

5.2 非同步處理 ​

非同步任務：

  1. 文件向量化（避免阻塞使用者操作）
  2. 日誌寫入（批次寫入，減少 IO）

5.3 資源限制 ​

限制措施：

  1. Docker 容器資源配額（CPU、記憶體）
  2. API 請求限流（防止濫用）
  3. 檔案上傳大小限制（防止伺服器儲存耗盡）

6. 擴充套件性設計 ​

6.1 水平擴充套件 ​

可擴充套件服務：

  1. LLM Router - 部署多個例項，Nginx 負載均衡
  2. RAG Service - 部署多個例項，並行處理
  3. Web API - 部署多個例項，分擔請求壓力

6.2 垂直擴充套件 ​

擴充套件方式：

  1. 增加 Docker 容器資源配額
  2. 使用更強大的伺服器
  3. GPU 加速（向量化和模型推理）

6.3 外掛系統 ​

擴充套件能力：

  1. 支援接入第三方 LLM 服務商
  2. 支援自定義嵌入模型
  3. 支援自定義提示詞模板
  4. 支援自定義語音識別引擎

7. 技術致謝 ​

CueMate 的誕生離不開眾多優秀開源專案和技術社羣的支援。我們在此向所有為這些技術做出貢獻的開發者和團隊表示衷心的感謝！

7.1 前端技術 ​

Web 應用框架與構建工具：

  • React - Meta 開源的現代化前端框架，讓 UI 開發更加高效
  • TypeScript - Microsoft 開發的 JavaScript 超集，提供強大的型別系統
  • Vite - Evan You 建立的下一代前端構建工具，開發體驗極佳
  • Ant Design - 螞蟻集團開源的企業級 UI 元件庫，設計精美、功能完善
  • Tailwind CSS - 原子化 CSS 框架，讓樣式開發更加靈活高效

桌面應用框架：

  • Electron - GitHub 開源的跨平臺桌面應用框架，讓 Web 技術構建原生應用成為可能

7.2 後端技術 ​

執行時與框架：

  • Node.js - 高效能 JavaScript 執行時，讓後端開發更加簡單
  • Fastify - 極速 Web 框架，效能卓越、外掛生態豐富
  • pnpm - 快速、節省磁碟空間的包管理器

資料庫：

  • SQLite - 世界上使用最廣泛的嵌入式資料庫引擎
  • better-sqlite3 - 高效能的 Node.js SQLite3 繫結庫
  • ChromaDB - 開源向量資料庫，為 AI 應用提供語義檢索能力

7.3 AI 服務 ​

語音識別：

  • FunASR - 阿里達摩院開源的語音識別工具包，支援實時流式識別
  • Piper TTS - 快速的本地神經網路文字轉語音系統

音訊處理：

大語言模型服務商：

7.4 開發與部署工具 ​

容器化與編排：

  • Docker - 容器化平臺，讓應用部署更加簡單可靠
  • Docker Compose - 多容器應用編排工具
  • Nginx - 高效能 Web 伺服器和反向代理

文件解析：

7.5 開源社羣 ​

特別感謝：

  • GitHub - 提供程式碼託管和協作平臺
  • npm - JavaScript 包管理生態系統
  • Stack Overflow - 開發者社羣，解決了無數技術難題
  • 所有在 GitHub 上提交 Issue 和 Pull Request 的貢獻者

7.6 致謝宣告 ​

CueMate 是站在巨人的肩膀上構建的。每一個開源專案的維護者、每一位貢獻程式碼的開發者、每一個提供技術支援的社羣成員，都是 CueMate 能夠誕生的重要力量。

我們承諾：

  1. 遵守所有開源專案的許可證要求
  2. 積極參與開源社羣，回饋技術生態
  3. 持續改進 CueMate，為使用者提供更好的服務

再次向所有開源專案和技術社羣表示最誠摯的感謝！🙏

相關頁面 ​

Released under the GPL-3.0 License.

Copyright © 2026-present CueMate Team