macOS 安装指南

欢迎使用 CueMate！本指南将帮助你在 macOS 系统上安装 CueMate，整个过程简单快捷，只需几分钟即可完成。

1. 系统要求

IMPORTANT

请在安装前确认你的 Mac 满足最低配置要求，否则可能导致安装失败或运行异常。

在安装 CueMate 之前，请确认你的 Mac 符合以下配置要求：

1.1 硬件与系统

序号	配置项	要求	说明
1	操作系统	macOS 13.0 (Ventura) 或更高版本	支持最新的 macOS 系统
2	处理器	Apple Silicon (M1/M2/M3) 或 Intel 芯片	支持两种架构
3	内存	>= 4GB RAM	确保流畅运行
4	磁盘空间	>= 10GB 可用空间	推荐使用 SSD 固态硬盘
5	网络连接	稳定的互联网连接	用于下载安装包和 AI 服务

1.2 端口占用检查

CueMate 需要使用以下端口，请确保这些端口未被其他程序占用：

序号	端口号	服务名称	用途说明
1	3001	Web API 服务	业务接口服务
2	3002	LLM Router 服务	大语言模型路由
3	3003	RAG 知识库服务	知识检索服务
4	3004	主窗口服务	提供主窗口界面访问
5	8000	ChromaDB 向量数据库	向量数据存储
6	10095	语音识别服务	实时语音转文字

注意：安装向导会自动检测端口占用情况，如有冲突会提供解决方案。详见 步骤 7：端口检查。

1.3 依赖环境

序号	依赖项	版本要求	说明
1	Docker Desktop	>= 4.0	CueMate 后端服务运行环境

TIP

• 离线包：包含 Docker Desktop 安装包，无需提前安装
• 在线包：需要用户自行安装 Docker Desktop

注意：如果未安装 Docker Desktop，安装向导会提供自动安装选项。详见 步骤 6：Docker 检查。

2. 下载安装包

2.1 选择安装包类型

CueMate 提供两种安装包类型，请根据你的需求选择：

类型	说明	体积	适用场景
离线包 (Offline)	包含 Docker Desktop、所有 Docker 镜像和语音模型，开箱即用	约 4.4GB	无网络环境、首次安装
在线包 (Online)	需自行安装 Docker Desktop，安装时从网络拉取镜像和语音模型	约 670MB	网络良好、已有 Docker

TIP

• 首次安装推荐使用离线包，包含所有依赖，无需额外下载
• 已安装 Docker Desktop 的用户可使用在线包，下载更快

IMPORTANT

在线包用户注意：首次启动 CueMate 时，语音识别服务（cuemate-asr）会自动下载 FunASR 语音模型（约 1.7GB）。下载期间语音识别功能暂时不可用，请确保网络畅通并耐心等待下载完成。

离线包已内置语音模型，无需额外下载，启动即可使用。

2.2 选择部署模式

CueMate 支持两种部署模式，安装时可以选择：

模式	说明	适用场景
本地模式	所有服务运行在本地 Mac 上	个人使用、本地开发
服务器模式	后端服务部署到远程 Linux 服务器，本地仅运行轻量客户端	多设备共享、服务器资源更强

详细的部署模式选择界面请参考 步骤 3：部署模式。

NOTE

• 本地模式：开箱即用，所有数据存储在本地
• 服务器模式：需要一台 Linux 服务器，客户端通过 SSH 连接服务器管理后端服务

2.3 确定你的 Mac 芯片类型

点击屏幕左上角的 Apple 菜单 → 关于本机，查看 芯片 或 处理器 信息：

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

2.4 选择下载渠道

CueMate 提供两种下载渠道，请根据网络环境选择：

方式一：百度网盘（推荐国内用户）

下载链接：https://pan.baidu.com/s/15jwZHy8YkDa4cEDLIYRo9Q?pwd=3477

提取码：3477

手机扫码访问：

下载步骤：

1. 点击上方链接或扫描二维码访问百度网盘
2. 输入提取码 3477
3. 选择对应的版本文件夹（如 v0.1.0）
4. 根据芯片类型和安装包类型下载对应的安装包：

芯片类型	离线包	在线包
Apple Silicon (M1/M2/M3)	CueMate-v0.1.1-macos-arm64-offline.dmg	CueMate-v0.1.1-macos-arm64-online.dmg
Intel	CueMate-v0.1.1-macos-x64-offline.dmg	CueMate-v0.1.1-macos-x64-online.dmg

5. 点击「下载」按钮，保存到本地

优势：国内下载速度快，无需科学上网

方式二：GitHub Release（推荐海外用户）

访问 GitHub Releases 页面下载最新版本或历史版本：

版本列表：

版本	发布日期	类型	主要更新	下载链接
v0.1.1	2025-12-26	功能更新	在线/离线安装包、服务器部署模式、多语言支持	GitHub Release 页面
v0.1.0	2025-12-10	首发版本	核心功能发布	GitHub Release 页面

选择安装包类型：

• 在线包（约 670MB）：下载快，安装时需要网络拉取 Docker 镜像和语音模型
• 离线包（约 4.4GB）：体积大，开箱即用无需网络

---

在线包下载（推荐网络良好的用户）：

1. 访问 GitHub Release 页面
2. 根据你的芯片类型，下载对应的在线安装包：
   • Apple Silicon (M1/M2/M3)：CueMate-vX.X.X-macos-arm64-online.dmg
   • Intel 芯片：CueMate-vX.X.X-macos-x64-online.dmg
3. 下载完成后，双击 .dmg 文件开始安装

---

离线包下载（推荐网络不稳定的用户）：

NOTE

由于离线包体积较大（约 4.4GB），超过 GitHub 单文件 2GB 限制，已拆分为多个分卷上传。

1. 访问 GitHub Release 页面
2. 根据你的芯片类型，下载对应的所有分卷文件：
   • Apple Silicon (M1/M2/M3)：下载所有 CueMate-vX.X.X-macos-arm64-offline.dmg.part* 文件
   • Intel 芯片：下载所有 CueMate-vX.X.X-macos-x64-offline.dmg.part* 文件
3. 将所有分卷文件放在同一个目录下
4. 打开终端（Terminal），执行以下命令合并分卷：

# Apple Silicon (ARM64) 版本
cat CueMate-vX.X.X-macos-arm64-offline.dmg.part* > CueMate-vX.X.X-macos-arm64-offline.dmg

# Intel (x64) 版本
cat CueMate-vX.X.X-macos-x64-offline.dmg.part* > CueMate-vX.X.X-macos-x64-offline.dmg

5. 合并完成后，双击 .dmg 文件开始安装

---

优势：全球 CDN 加速，版本管理清晰，支持校验和验证

下载完成后，安装包会保存在你的"下载"文件夹中。

2.5 打开安装包

双击下载的 .dmg 文件，macOS 会自动挂载磁盘镜像，弹出安装窗口。

2.6 处理安全提示

首次运行时，macOS 可能会显示安全提示："无法打开 CueMate 安装向导，因为它来自身份不明的开发者"。

NOTE

这是 macOS 的 Gatekeeper 安全机制。CueMate 安装向导是安全的，但因未经过 Apple 公证，首次打开需要手动授权。

解决方法：

1. 打开 系统设置（或 系统偏好设置）
2. 进入 隐私与安全性
3. 向下滚动，找到提示信息"CueMate 安装向导已被阻止"
4. 点击 仍要打开 按钮

3. 安装步骤

安装向导包含 10 个步骤，会自动引导你完成整个安装过程。

安装向导界面提供以下信息和功能：

• 语言切换（右上角）：支持简体中文、繁体中文、English 三种语言，可随时切换
• 安装模式（顶部标签）：显示当前安装包类型，如"离线安装"或"在线安装"
• 部署模式（顶部标签）：显示当前部署模式，如"本地模式"或"服务器模式"，可在步骤 3 中修改
• 版本信息（左下角）：显示当前安装向导的版本号

3.1 步骤 1：欢迎

安装向导启动后，首先显示欢迎界面，介绍 CueMate 的功能和安装前准备事项。

阅读欢迎信息后，点击 下一步 按钮继续。

3.2 步骤 2：许可协议

阅读 CueMate 的软件许可协议。

如果你同意协议条款，勾选"我同意许可协议"，然后点击 下一步 按钮。

3.3 步骤 3：部署模式

选择 CueMate 的部署模式。

模式	说明	适用场景
本地模式	所有服务运行在本地 Mac 上，开箱即用	个人使用、本地开发、首次体验
服务器模式	后端服务部署到远程 Linux 服务器，本地仅运行轻量客户端	多设备共享、服务器资源更强、团队协作

本地模式（默认推荐）：

• 所有服务运行在本地，无需额外配置
• 数据存储在本地，隐私性更好
• 适合大多数用户

服务器模式：

• 需要一台 Linux 服务器（Ubuntu 20.04+ 或 CentOS 7+）
• 本地 Mac 仅作为客户端，资源占用少
• 支持多台 Mac 共享同一个后端服务
• 安装向导会引导你配置服务器 SSH 连接信息

TIP

如果你不确定选择哪种模式，建议选择 本地模式。后续可以在系统设置中切换到服务器模式。

服务器模式配置要求

如果选择 服务器模式，需要确保远程 Linux 服务器满足以下条件：

服务器硬件要求：

配置项	最低要求	推荐配置
CPU	2 核	4 核或以上
内存	4GB	8GB 或以上
磁盘	20GB 可用空间	50GB SSD
系统	Ubuntu 20.04+ / CentOS 7+	Ubuntu 22.04 LTS

服务器软件要求：

• Docker 20.10+ 和 Docker Compose 2.0+
• 安装向导会自动检测，未安装时会提示

安全组/防火墙端口配置：

服务器需要开放以下端口，供本地客户端访问后端服务：

端口	协议	服务	用途	必须开放
22	TCP	SSH	安装向导连接服务器	是
3001	TCP	Web API	业务接口	是
3002	TCP	LLM Router	大模型路由	是
3003	TCP	RAG Service	知识检索	是
3004	TCP	Web 服务	主界面访问	是
8000	TCP	ChromaDB	向量数据库	是
10095	TCP	ASR	语音识别	是

IMPORTANT

云服务器安全组配置：

• 阿里云/腾讯云/华为云等云服务器，需要在控制台的「安全组」中添加入站规则
• 授权对象可设置为 0.0.0.0/0（允许所有 IP）或指定你的本地公网 IP
• 建议仅开放给你的办公网络 IP，提高安全性

云服务器安全组配置示例（以阿里云为例）：

1. 登录阿里云控制台，进入 ECS 实例页面
2. 点击实例 ID，进入实例详情
3. 点击左侧「安全组」菜单
4. 点击「配置规则」按钮
5. 点击「手动添加」，添加以下入站规则：

协议类型: 自定义 TCP
端口范围: 22,3001-3004,8000,10095
授权对象: 0.0.0.0/0（或你的公网 IP）
描述: CueMate 服务端口

选择部署模式后，点击 下一步 按钮继续。

3.4 步骤 4：安装位置

根据上一步选择的部署模式，界面会有所不同。

本地模式

• 安装路径：固定为 /Applications，macOS 应用必须安装到此目录
• 磁盘空间要求：约 10GB（应用程序 + Docker 镜像）

TIP

Docker 镜像和运行数据将自动存储在系统目录中，无需手动配置。

服务器模式

服务器模式需要配置远程服务器的 SSH 连接信息。

本地客户端安装路径：

• 固定为 /Applications，与本地模式相同

远程服务器配置：

• 服务器地址：远程服务器的 IP 地址或域名
• SSH 端口：默认 22
• 用户名：SSH 登录用户名（如 root）
• 服务器名称：自定义名称，便于识别
• 认证方式：密码认证或密钥认证（点击小眼睛可查看输入内容）
• 部署路径（高级选项）：后端服务在服务器上的安装路径，默认 /opt/cuemate

TIP

服务器配置信息存储在 ~/Library/Application Support/cuemate-desktop-client/config/server.json，可以手动编辑此文件修改配置。安装完成后，也可以通过托盘菜单修改服务器配置，详见 托盘菜单 - 服务器配置。

填写完成后，点击 测试连接 按钮验证配置：

测试通过后，点击 下一步 按钮继续。

3.5 步骤 5：磁盘空间检测

安装向导会自动检测磁盘空间是否满足安装要求。

本地模式

检测本地 Mac 的磁盘空间，显示：

• 总空间、已使用空间、可用空间
• 操作系统版本、架构、内存大小

服务器模式

同时检测两个位置的磁盘空间：

• 本地磁盘 (macOS)：用于安装桌面客户端，需要约 2GB
• 服务器磁盘：用于部署后端服务，需要约 10GB

IMPORTANT

空间需求：

• 本地模式：约 10GB（应用 + Docker 镜像 + 数据）
• 服务器模式：本地约 2GB + 服务器约 10GB

检测通过后自动进入下一步。如果空间不足，请清理磁盘后点击"重新检测"。

3.6 步骤 6：Docker 检查

安装向导会检测 Docker 环境是否就绪。

本地模式

检测本地 Mac 的 Docker Desktop：

• Docker Desktop 是否已安装
• Docker Engine 是否正在运行
• Docker Compose 是否可用

如果 Docker 未安装：

• 离线包：点击"安装到本地"按钮，自动安装内置的 Docker Desktop
• 在线包：点击"下载 Docker Desktop"按钮，跳转到官方下载页面

服务器模式

检测远程 Linux 服务器的 Docker：

• Docker Engine 是否已安装
• Docker 服务是否正在运行
• Docker Compose 是否可用

如果 Docker 未安装：

• 离线包：点击"安装到服务器"按钮，自动通过 SSH 在远程服务器上安装 Docker
• 在线包：点击"查看 Docker 文档"按钮，跳转到 Docker Engine 安装文档

检测通过后，点击 下一步 按钮继续。

3.7 步骤 7：端口检查

安装向导会检测 CueMate 需要使用的网络端口是否被占用。

本地模式

检测本地 Mac 的端口占用情况，需要检查 6 个端口：

端口	服务	状态显示
3001	Web API 服务	(可用) 或 (不可用)
3002	LLM Router 服务	(可用) 或 (不可用)
3003	RAG 服务	(可用) 或 (不可用)
3004	Web 服务	(可用) 或 (不可用)
8000	ChromaDB 向量数据库	(可用) 或 (不可用)
10095	语音识别服务	(可用) 或 (不可用)

服务器模式

检测远程服务器的端口占用情况，检查的端口与本地模式相同：

端口	服务	状态显示
3001	Web API 服务	(可用) 或 (不可用)
3002	LLM Router 服务	(可用) 或 (不可用)
3003	RAG 服务	(可用) 或 (不可用)
3004	Web 服务	(可用) 或 (不可用)
8000	ChromaDB 向量数据库	(可用) 或 (不可用)
10095	语音识别服务	(可用) 或 (不可用)

如果检测到端口冲突：

• 点击端口旁的"结束进程"按钮终止占用该端口的程序
• 或点击"自动解决所有冲突"按钮批量处理

端口检测通过后，点击 下一步 按钮继续。

3.8 步骤 8：镜像加载

安装向导开始加载 CueMate 的后端服务镜像。页面标题旁会显示当前的部署环境标签。

本地模式

标签显示"本地环境"，镜像加载到本地 Mac 的 Docker 环境：

• 离线包：执行 docker load 从安装包中加载预置镜像
• 在线包：执行 docker pull 从 Docker Hub 拉取镜像

预计时间：1-2 分钟（离线）或 5-10 分钟（在线，取决于网络速度）

服务器模式

标签显示"服务器"，镜像加载到远程 Linux 服务器：

• 离线包：通过 SCP 上传镜像 tar 文件到服务器，然后 SSH 执行 docker load
• 在线包：通过 SSH 在服务器上执行 docker pull

预计时间：5-15 分钟（取决于网络速度和服务器性能）

WARNING

请不要关闭安装向导，否则需要重新开始加载。

镜像加载完成后，点击 下一步 按钮继续。

3.9 步骤 9：安装客户端

镜像加载完成后，安装向导会进入桌面客户端安装步骤。

本地模式

执行 4 个步骤：

1. 复制 CueMate.app：安装到 /Applications 目录
2. 配置 Docker Compose：复制 docker-compose.yml 到本地数据目录
3. 挂载 ASR 语音模型：解压模型到 ~/Library/Application Support/cuemate-desktop-client/data/funasr_models/
4. 保存版本信息：记录安装版本

预计时间：约 1 分钟

服务器模式

执行 4 个步骤：

1. 复制 CueMate.app：安装到本地 /Applications 目录
2. 配置 Docker Compose：通过 SSH 上传 docker-compose.yml 到远程服务器 /opt/cuemate/
3. 挂载 ASR 语音模型：通过 SCP 上传约 1GB 模型文件到服务器，并解压到 /opt/cuemate/data/funasr_models/
4. 保存版本信息：记录安装版本

预计时间：几分钟到十几分钟（取决于网络速度）

TIP

请确保完成此步骤后再关闭向导，否则桌面客户端将不会被正确安装。

安装完成后，点击 下一步 按钮进入最后一步。

3.10 步骤 10：完成

当所有步骤完成后，安装向导会显示成功界面。

点击 完成 按钮，安装向导会自动：

1. 关闭安装窗口
2. 启动 CueMate 桌面应用

4. 首次使用

4.1 系统权限授权

CueMate 使用语音识别功能时，需要授予必要的系统权限。

4.1.1 麦克风权限

首次使用麦克风功能时，系统会自动弹出授权提示框，请点击 允许 按钮授予 CueMate 访问麦克风的权限。

如果误点了"不允许"或意外关闭了授权窗口：

1. 打开 系统设置 > 隐私与安全性
2. 在左侧菜单中找到并点击 麦克风

3. 在右侧应用列表中找到 CueMate，勾选其右侧的开关以启用麦克风权限

4.1.2 录屏与系统录音权限

为了实现面试官语音识别功能，CueMate 需要"录屏与系统录音"权限来捕获系统音频。

NOTE

为什么需要这个权限？

• CueMate 使用"录屏与系统录音"权限来捕获系统音频
• 仅用于音频捕获，不会录制屏幕画面
• 用于识别面试软件（如腾讯会议、钉钉等）播放的面试官语音

首次使用扬声器测试功能时，系统会自动弹出授权提示框，请点击 允许 按钮授予 CueMate 访问系统音频的权限。

如果误点了"不允许"或意外关闭了授权窗口：

1. 打开 系统设置 > 隐私与安全性
2. 在左侧菜单中找到并点击 录屏与系统录音

3. 在右侧应用列表中找到 CueMate，勾选其右侧的开关以启用系统音频捕获权限
4. 如果列表中没有 CueMate，可以点击列表底部的 "+" 按钮手动添加

TIP

授权后无需重启应用，直接返回 CueMate 即可使用

4.2 登录系统

安装完成后，在启动台搜索 CueMate 应用图标，单击左键打开应用程序。

应用启动后会打开登录界面：

内置账户信息：

• 用户名：admin
• 密码：cuemate

在登录界面输入上述账户信息，点击 登录 按钮即可进入系统。

4.3 开始使用

登录成功后，CueMate 的控制窗口会悬浮在屏幕正上方。

控制窗口按钮说明（从左到右）：

• CueMate 图标：点击打开 CueMate 官方网站
• 语音识别：点击启动语音识别功能，打开面试功能窗口
• 提问 AI：点击打开 AI 提问窗口，快速向 AI 提问
• 交互模式：切换窗口的点击穿透模式（交互/穿透）
• 主应用窗口：点击打开主应用窗口，进入后台管理界面
• 显示/隐藏：点击隐藏或显示控制栏及所有窗口

此外，CueMate 也会在菜单栏显示图标，点击可以快速访问常用功能。

5. 常见问题

5.1 安装向导无法打开

问题：双击安装向导图标后没有反应

解决方法：

1. 确认你已经按照"处理安全提示"章节的步骤，在系统设置中允许打开应用
2. 尝试右键点击安装向导图标，选择"打开"
3. 如果仍然无法打开，请重新下载安装包

5.2 磁盘空间不足

问题：安装向导提示磁盘空间不足

解决方法：

1. 清理磁盘，确保至少有 10GB 可用空间
2. 删除不需要的文件和应用
3. 清空废纸篓
4. 返回安装向导，点击"重新检测"

5.3 Docker Desktop 无法启动

问题：安装向导提示 Docker 无法启动

可能原因：

• macOS 版本过低
• 系统虚拟化功能未启用
• Docker Desktop 安装不完整

解决方法：

1. 确认 macOS 版本符合要求（13 或更高）
2. 重新安装 Docker Desktop
3. 重启 Mac 后再次尝试

5.4 端口冲突无法解决

问题：安装向导提示端口被占用，且自动解决失败

解决方法：

1. 记下冲突的端口号和程序名称
2. 手动退出这些程序：
   • 打开"活动监视器"（应用程序 > 实用工具）
   • 找到占用端口的程序
   • 选中程序，点击左上角的"×"按钮强制退出
3. 返回安装向导，点击"重新检测"

5.5 镜像加载失败

问题：安装向导在"镜像加载"步骤失败

可能原因：

• 网络连接中断
• Docker 服务异常
• 磁盘空间不足

解决方法：

1. 检查网络连接
2. 确认 Docker Desktop 正在运行
3. 检查磁盘空间
4. 点击"重试"按钮，重新执行加载

5.6 权限授予后仍无法使用

问题：已经授予了麦克风权限，但语音识别仍不工作

解决方法：

1. 完全退出 CueMate：
   • 点击菜单栏的 CueMate 图标
   • 选择"退出 CueMate"
2. 重新启动 CueMate
3. 再次测试语音功能

如果仍然无法使用，请进入 系统设置 > 隐私与安全性 > 麦克风，确认 CueMate 已被勾选。

5.7 主应用窗口无法打开

问题：点击控制窗口的"主应用窗口"按钮后无反应

解决方法：

1. 确认 CueMate 应用正在运行（菜单栏有图标）
2. 确认后端服务正常运行（点击菜单栏图标查看服务状态）
3. 如果服务异常，点击菜单栏图标，选择"重启服务"
4. 等待服务重启完成（约 30 秒），再次尝试打开主应用窗口

6. 卸载 CueMate

6.1 卸载步骤

1. 退出 CueMate 应用（点击菜单栏图标 > 退出）
   • 退出时会自动停止所有后端 Docker 服务
2. 打开"应用程序"文件夹，将 CueMate.app 拖到废纸篓
3. 清理数据文件（可选）：
   • 打开 Finder
   • 按 Command + Shift + G 键
   • 输入 ~/Library/Application Support
   • 找到 cuemate-desktop-client 文件夹，删除它
4. 清空废纸篓

注意：

• 删除 cuemate-desktop-client 文件夹会清除你的所有面试记录、配置和语音识别模型（约 1.6GB）
• 如果将来想重新安装 CueMate，建议保留这个文件夹，可以节省重新下载/解压模型的时间

下一步

安装完成后，建议你：

1. 阅读 快速开始指南，了解基本使用方法
2. 查看 功能手册，探索 CueMate 的所有功能
3. 配置 AI 模型，开始使用智能功能
4. 进行 语音测试，确保音频设备正常

如果遇到问题，可以查看 常见问题 或联系技术支持。

祝你使用愉快，面试顺利！