繁體中文

简体中文
English

繁體中文

简体中文
English

Appearance

安裝問題 ​

本文件彙總了 CueMate 安裝過程中的常見問題和解決方案。

提示

如果你是第一次安裝 CueMate，建議先閱讀 macOS 安裝指南 瞭解完整的安裝流程。

1. macOS 平臺 ​

1.1 如何確定我的 Mac 晶片型別？ ​

問題描述：不知道自己的 Mac 是 Apple Silicon 還是 Intel 晶片，不確定下載哪個版本。

解決方法：

點選螢幕左上角的 Apple 選單 → 關於本機，檢視 晶片 或 處理器 資訊：

  • 如果看到 "Apple M1"、"Apple M2" 或 "Apple M3"，下載 Apple Silicon 版本（arm64）
  • 如果看到 "Intel"，下載 Intel 版本（x64）

檢視晶片型別

1.2 我的 Mac 符合系統要求嗎？ ​

問題描述：不確定自己的 Mac 是否滿足 CueMate 的安裝要求。

系統要求

CueMate 需要：

  • 作業系統：macOS 13.0 (Ventura) 或更高版本
  • 處理器：Apple Silicon (M1/M2/M3) 或 Intel 晶片
  • 記憶體：>= 8GB RAM
  • 磁碟空間：>= 10GB 可用空間
  • 網路連線：穩定的網際網路連線

檢查方法：

  1. 點選 Apple 選單 → 關於本機
  2. 檢視 macOS 版本、晶片型別、記憶體大小
  3. 檢視儲存空間是否充足

詳見 macOS 安裝指南 - 系統要求。

1.3 下載速度太慢怎麼辦？ ​

問題描述：下載 CueMate 安裝包速度很慢，或者下載中斷。

選擇下載渠道建議

  • 國內使用者：優先使用百度網盤（速度快、穩定）
  • 海外使用者：使用 GitHub Releases（全球 CDN）

下載渠道對比：

序號渠道適用地區下載速度優勢劣勢
1百度網盤中國大陸極快無需科學上網需要百度賬號
2GitHub Releases全球快官方更新快國內可能較慢

百度網盤下載：

GitHub Releases 下載：

1.4 安裝嚮導無法開啟 ​

問題描述：雙擊安裝嚮導圖示後沒有反應，或提示"無法開啟 CueMate 安裝嚮導，因為它來自身份不明的開發者"。

安全提示

macOS 安全機制

這是 macOS 的 Gatekeeper 安全機制。CueMate 安裝嚮導是安全的，但因未經過 Apple 公證，首次開啟需要手動授權。

解決方法：

方式一：系統設定中允許（推薦）

  1. 開啟 系統設定（或 系統偏好設定）
  2. 進入 隱私與安全性
  3. 向下滾動，找到提示資訊"CueMate 安裝嚮導已被阻止"
  4. 點選 仍要開啟 按鈕

允許開啟應用

方式二：右鍵開啟

  1. 右鍵點選（或按住 Control 鍵點選）安裝嚮導圖示
  2. 選擇"開啟"
  3. 在彈出的對話方塊中點選"開啟"按鈕

最佳實踐

如果仍然無法開啟：

  • 重新下載安裝包（可能檔案損壞）
  • 檢查下載的檔案是否完整（離線包約 4.4GB，線上包約 670MB）
  • 嘗試使用終端命令移除隔離屬性：sudo xattr -rd com.apple.quarantine /Applications/CueMate\ 安裝嚮導.app

1.5 磁碟空間不足 ​

問題描述：安裝嚮導提示"磁碟空間不足，無法繼續安裝"。

IMPORTANT

CueMate 安裝需要至少 10GB 可用磁碟空間，包括：

  • 應用本身：約 2GB
  • Docker 映象：約 6GB
  • 執行資料和日誌：約 2GB

解決方法：

  1. 清理磁碟：

    • 刪除不需要的檔案和應用
    • 清空"下載"資料夾
    • 清空廢紙簍
    • 使用 macOS 自帶的"儲存空間管理"工具

  2. 檢視磁碟空間：

    • 點選 Apple 選單 → 關於本機 → 儲存空間
    • 確保至少有 10GB 可用空間

  3. 更換安裝位置：

    • 在安裝嚮導的"安裝位置"步驟
    • 點選"選擇其他位置"
    • 選擇空間充足的其他磁碟

  4. 清理後重新檢測：

    • 返回安裝嚮導
    • 點選"重新檢測"按鈕

1.6 Docker Desktop 未安裝 ​

問題描述：安裝嚮導提示"Docker Desktop 未安裝"。

Docker 檢查

解決方法：

方式一：透過安裝嚮導自動安裝（推薦）

  1. 點選安裝嚮導中的 自動安裝 按鈕
  2. 安裝嚮導會開啟 Docker Desktop 官方下載頁面
  3. 下載並安裝 Docker Desktop：
    • 雙擊下載的 .dmg 檔案
    • 拖拽 Docker 圖示到"應用程式"資料夾
    • 開啟 Docker Desktop，完成初始化設定
  4. 返回 CueMate 安裝嚮導，點選 重新檢測

方式二：手動下載安裝

  1. 訪問 Docker 官網：https://www.docker.com/products/docker-desktop/
  2. 根據你的晶片型別選擇對應版本下載
  3. 安裝完成後，啟動 Docker Desktop
  4. 等待 Docker 啟動完成（底部狀態列顯示 "Docker Desktop is running"）
  5. 返回 CueMate 安裝嚮導，點選 重新檢測

1.7 Docker Desktop 無法啟動 ​

問題描述：Docker Desktop 已安裝，但安裝嚮導提示"Docker 服務未執行"。

NOTE

Docker Desktop 是 CueMate 執行的核心依賴，所有後端服務都執行在 Docker 容器中。如果 Docker 無法啟動，CueMate 將無法正常工作。

可能原因：

  • macOS 版本過低（需要 macOS 13.0 (Ventura) 或更高）
  • 系統虛擬化功能未啟用
  • Docker Desktop 安裝不完整
  • 其他虛擬化軟體衝突（如 VirtualBox、VMware）

解決方法：

  1. 手動啟動 Docker：

    • 開啟"應用程式"資料夾
    • 雙擊啟動 Docker Desktop
    • 等待啟動完成（約 10-30 秒）
    • 返回安裝嚮導，點選"重新檢測"

  2. 檢查 macOS 版本：

    • 點選 Apple 選單 → 關於本機
    • 確認版本號 >= macOS 13.0 (Ventura)

  3. 重新安裝 Docker Desktop：

    • 解除安裝當前 Docker Desktop
    • 重新下載最新版本
    • 重新安裝

  4. 重啟 Mac：

    • 完全關機後重新啟動
    • 啟動後先開啟 Docker Desktop
    • 再執行 CueMate 安裝嚮導

  5. 檢查虛擬化衝突：

    • 解除安裝其他虛擬化軟體（VirtualBox、VMware 等）
    • 或暫時退出這些軟體
    • 重新啟動 Docker

1.8 埠被佔用 ​

問題描述：安裝嚮導提示"埠被佔用，無法啟動服務"。

埠檢查

CueMate 使用的埠

請確保以下埠未被其他程式佔用：

埠服務說明
3001web-api業務 API 服務
3002llm-routerLLM 路由服務
3003rag-service知識庫檢索服務
3004NginxWeb 前端服務
8000ChromaDB向量資料庫
10095CueMate-ASR語音識別服務

解決方法：

方式一：使用安裝嚮導自動解決（推薦）

  1. 安裝嚮導會顯示佔用埠的程式名稱
  2. 點選 自動解決 按鈕
  3. 安裝嚮導會嘗試關閉佔用埠的程式
  4. 自動重新檢測埠狀態

方式二：手動關閉佔用程式

  1. 開啟"活動監視器"（應用程式 > 實用工具）
  2. 在搜尋框中輸入埠號或程式名稱
  3. 找到佔用埠的程式
  4. 選中程式，點選左上角的"×"按鈕強制退出
  5. 返回安裝嚮導，點選 重新檢測
方式三：使用終端命令查詢並關閉（高階使用者）
bash
# 檢視埠占用情況
lsof -i :3001
lsof -i :3004

# 強制關閉佔用程序（替換 <PID> 為實際程序 ID）
kill -9 <PID>

WARNING

使用 kill -9 強制結束程序前，請確認該程序不是系統關鍵服務！強制結束系統服務可能導致 macOS 執行異常。

如果無法關閉佔用程式：

  • 檢查是否為系統關鍵服務
  • 重啟 Mac 後再次嘗試安裝
  • 或更換其他埠（需要修改 CueMate 配置檔案，不推薦新手操作）

1.9 映象載入失敗 ​

問題描述：安裝嚮導在"映象載入"步驟失敗，提示"映象載入失敗，請重試"。

映象載入

可能原因：

  • 網路連線中斷
  • Docker 服務異常
  • 磁碟空間不足
  • 安裝包損壞

解決方法：

  1. 檢查網路連線：

    • 確認網路連線正常
    • 嘗試訪問其他網站測試網路
    • 如果使用 Wi-Fi，嘗試切換到有線網路

  2. 檢查 Docker 狀態：

    • 開啟 Docker Desktop
    • 確認底部狀態列顯示 "Docker Desktop is running"
    • 如果 Docker 異常，重啟 Docker Desktop

  3. 檢查磁碟空間：

    • 確認至少有 10GB 可用空間
    • Docker 映象會佔用約 3-5GB 空間
    • 清理磁碟後點選"重試"

  4. 重試載入：

    • 點選安裝嚮導中的 重試 按鈕
    • 等待重新載入（可能需要 3-5 分鐘）

  5. 重新下載安裝包：

    • 如果多次重試失敗，可能是安裝包損壞
    • 重新下載安裝包
    • 確認下載完整（離線包約 4.4GB，線上包約 670MB）

  6. 檢視詳細日誌：

    • 點選安裝嚮導中的"檢視日誌"按鈕
    • 記錄錯誤資訊
    • 聯絡技術支援

1.10 映象載入時間過長 ​

問題描述：映象載入步驟等待時間超過 10 分鐘。

TIP

映象載入時間因裝置配置而異：

  • 高配 Mac（M1/M2/M3 + SSD）：3-5 分鐘
  • 低配 Mac 或機械硬碟：5-10 分鐘
  • 超過 15 分鐘：可能出現問題，建議重試

原因：

  • 首次載入需要從安裝包中解壓並載入約 3GB 的 Docker 映象
  • 低配置 Mac 或使用機械硬碟會較慢
  • Docker 服務響應緩慢

解決方法：

  1. 耐心等待：

    • 正常情況下需要 3-5 分鐘
    • 低配置裝置可能需要 5-10 分鐘
    • 不要關閉安裝嚮導

  2. 檢查進度指示：

    • 安裝嚮導會顯示當前載入的映象名稱
    • 顯示百分比進度
    • 如果進度長時間不變（超過 5 分鐘），可能出現問題

  3. 最佳化 Docker 效能：

    • 開啟 Docker Desktop 設定
    • 增加分配給 Docker 的記憶體和 CPU
    • 建議：記憶體 4GB+，CPU 2 核+

  4. 使用 SSD 硬碟：

    • 機械硬碟載入速度會很慢
    • 建議將 CueMate 安裝到 SSD 上

1.11 安裝完成但無法啟動應用 ​

問題描述：安裝嚮導顯示"安裝完成"，但點選"完成"後應用無法啟動。

解決方法：

  1. 手動啟動應用：

    • 開啟"應用程式"資料夾
    • 找到 CueMate.app
    • 雙擊啟動

  2. 檢查服務狀態：

    • 開啟 Docker Desktop
    • 檢視容器列表
    • 確認 CueMate 相關容器是否在執行
    • 如果容器未執行，詳見 服務管理

  3. 檢視應用日誌：

    • 開啟"終端"應用
    • 執行命令檢視日誌：
      bash
      tail -f ~/Library/Application\ Support/cuemate-desktop-client/data/logs/*/$(date +%Y-%m-%d)/error.log

  4. 重新安裝：

    • 如果以上方法都無效
    • 先解除安裝 CueMate（詳見 解除安裝指南）
    • 重新執行安裝嚮導

1.12 麥克風許可權未授予 ​

問題描述：使用語音識別功能時，提示"麥克風許可權未授予"或"無法訪問麥克風"。

麥克風許可權請求

解決方法：

  1. 授予許可權（首次使用）：

    • 使用麥克風功能時會自動彈出授權提示
    • 點選 好 按鈕授予許可權

  2. 手動檢查許可權設定：

    • 開啟 系統設定 > 隱私與安全性
    • 在左側選單中找到並點選 麥克風
    • 在右側應用列表中找到 CueMate
    • 勾選其右側的開關

  3. 重啟應用：

    • 完全退出 CueMate（選單欄圖示 > 退出）
    • 重新啟動 CueMate
    • 再次測試語音功能

1.13 錄屏與系統錄音許可權未授予 ​

問題描述：無法使用面試官語音識別功能，提示"需要錄屏與系統錄音許可權"。

NOTE

為什麼需要這個許可權？

  • CueMate 使用"錄屏與系統錄音"許可權來捕獲系統音訊
  • 僅用於音訊捕獲，不會錄製螢幕畫面
  • 用於識別面試軟體（如騰訊會議、釘釘等）播放的面試官語音

解決方法：

首次使用揚聲器測試功能時，系統會自動彈出授權提示框，請點選 允許 按鈕授予 CueMate 訪問系統音訊的許可權。

揚聲器授權

如果誤點了"不允許"或意外關閉了授權視窗：

  1. 開啟 系統設定 > 隱私與安全性
  2. 在左側選單中找到並點選 錄屏與系統錄音

錄屏與系統錄音許可權入口

  1. 在右側應用列表中找到 CueMate，勾選其右側的開關以啟用系統音訊捕獲許可權
  2. 如果列表中沒有 CueMate，可以點選列表底部的 "+" 按鈕手動新增

勾選 CueMate 許可權

  1. 授權後無需重啟應用，直接返回 CueMate 即可使用

1.14 授予許可權後仍無法使用 ​

問題描述：已經授予了麥克風或錄屏許可權，但功能仍然不工作。

解決方法：

  1. 完全重啟 CueMate：

    • 點選選單欄的 CueMate 圖示
    • 選擇 退出 CueMate（確保完全退出，不是最小化）
    • 重新從"應用程式"資料夾啟動 CueMate

  2. 檢查許可權設定：

    • 進入 系統設定 > 隱私與安全性
    • 分別檢查 麥克風 和 錄屏與系統錄音
    • 確認 CueMate 已被勾選

  3. 重置許可權：

    • 在系統設定中取消勾選 CueMate
    • 完全退出 CueMate
    • 重新啟動 CueMate
    • 使用相關功能時會再次彈出授權提示
    • 重新授權

  4. 檢查裝置連線：

    • 確認麥克風裝置已正確連線
    • 開啟"系統設定" > "聲音"
    • 確認輸入裝置選擇正確
    • 對著麥克風說話，觀察輸入電平是否有變化

  5. 重啟 Mac：

    • 如果以上方法都無效
    • 嘗試重啟 Mac
    • 重啟後重新測試

1.15 無法登入系統 ​

問題描述：輸入賬戶資訊後提示"使用者名稱或密碼錯誤"。

登入介面

解決方法：

  1. 使用內建賬戶：

    • 使用者名稱：admin
    • 密碼：cuemate
    • 注意：密碼區分大小寫，全部小寫

  2. 檢查輸入：

    • 確認沒有多餘的空格
    • 確認沒有開啟大寫鎖定
    • 嘗試複製貼上賬戶資訊

  3. 檢查服務狀態：

    • 點選選單欄的 CueMate 圖示
    • 選擇"容器監控"
    • 確認 cuemate-web-api 服務正在執行
    • 如果服務未執行，點選"重啟"按鈕

  4. 清除快取重試：

    • 完全退出 CueMate
    • 清除瀏覽器快取（如果使用的是 Web 介面）
    • 重新啟動 CueMate

1.16 主應用視窗無法開啟 ​

問題描述：點選控制視窗的"主應用視窗"按鈕後無反應。

控制視窗

可能原因：

  • 後端服務未啟動
  • 埠被佔用
  • 網路連線問題

解決方法：

  1. 檢查服務狀態：

    • 點選選單欄的 CueMate 圖示
    • 選擇"容器監控"
    • 確認所有 6 個服務都顯示為"執行中"（綠色標籤）
    • 重點檢查 cuemate-web 和 cuemate-web-api 服務

  2. 重啟服務：

    • 在容器監控頁面
    • 點選異常服務的"重啟"按鈕
    • 等待服務重啟完成（約 30 秒）
    • 再次嘗試開啟主應用視窗

  3. 檢查埠：

    • 開啟"終端"應用
    • 執行命令檢查埠：
      bash
      lsof -i :3004
    • 確認埠未被其他程式佔用

  4. 使用瀏覽器直接訪問：

    • 開啟瀏覽器
    • 訪問：http://localhost:3004
    • 如果能正常開啟，說明服務正常
    • 問題可能在桌面應用本身

  5. 重啟 CueMate：

    • 完全退出 CueMate
    • 重新啟動
    • 再次嘗試

1.17 服務啟動失敗 ​

問題描述：在"容器監控"頁面看到某些服務狀態為"已停止"或"錯誤"。

解決方法：

詳見 服務管理 - 服務啟動失敗。

1.18 安裝包檔案損壞 ​

問題描述：提示"安裝包檔案損壞或不完整"。

解決方法：

  1. 刪除已下載的安裝包
  2. 重新下載完整的安裝包
  3. 確認檔案大小正確（離線包約 4.4GB，線上包約 670MB）
  4. 使用 MD5 或 SHA256 驗證檔案完整性（如果提供了校驗值）

1.19 安裝過程中斷 ​

問題描述：安裝過程中意外退出或中斷。

解決方法：

  1. 重新執行安裝嚮導
  2. 安裝嚮導會自動檢測已完成的步驟
  3. 從中斷的位置繼續安裝
  4. 如果無法繼續，先解除安裝已安裝的部分，重新開始

1.20 解除安裝後重新安裝 ​

問題描述：解除安裝 CueMate 後重新安裝出現問題。

解決方法：

  1. 完全清理殘留檔案：

    bash
    # 刪除應用資料
rm -rf ~/Library/Application\ Support/cuemate-desktop-client

# 刪除 Docker 容器和映象
docker compose -f ~/Library/Application\ Support/cuemate-desktop-client/docker-compose.yml down
docker system prune -a

  2. 重啟 Mac：

    • 清理完成後重啟 Mac
    • 重啟後重新執行安裝嚮導

  3. 使用全新安裝包：

    • 刪除舊的安裝包
    • 下載最新版本的安裝包
    • 使用新的安裝包進行安裝

詳見 解除安裝指南。

2. Windows 平臺 ​

開發中

Windows 版本正在開發中，敬請期待。

如果你對 Windows 版本有任何建議或需求，歡迎透過以下方式反饋：

獲取更多幫助 ​

如果以上方法都無法解決你的問題，可以透過以下方式獲取幫助：

檢視文件 ​

聯絡技術支援 ​

提交問題時，請提供：

  1. macOS 版本號和晶片型別
  2. CueMate 版本號
  3. 詳細的錯誤資訊和截圖
  4. 已嘗試的解決方法

Released under the GPL-3.0 License.

Copyright © 2025-present CueMate Team