技术架构
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 平台：
核心职责：
- 引导用户完成首次安装
- 检测并安装 Docker Desktop
- 自动部署后端 Docker 服务
- 管理系统版本更新
工作流程：
- 检测系统环境（macOS 版本、芯片架构、可用空间）
- 检测 Docker Desktop 状态（未安装/已安装/需更新）
- 检测端口占用情况（80、3001、3002、3003、8000、10095）
- 拉取 Docker 镜像并启动服务
- 验证服务健康状态
Windows 平台：
开发中
Windows 版本正在开发中，敬请期待。
如果你对 Windows 版本有任何建议或需求，欢迎通过以下方式反馈：
- GitHub Issues：https://github.com/cuemate-chat/cuemate/issues
- 邮箱：nuneatonhydroplane@gmail.com
2.1.2 桌面客户端
macOS 平台：
核心功能：
- 全局快捷键和悬浮窗
- 麦克风音频采集
- 系统音频捕获（AudioTee）
- 实时语音识别显示
- 本地语音合成（Piper TTS）
- 系统托盘集成
数据存储：
- 应用数据：
~/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 平台：
开发中
Windows 版本正在开发中，敬请期待。
如果你对 Windows 版本有任何建议或需求，欢迎通过以下方式反馈：
- GitHub Issues：https://github.com/cuemate-chat/cuemate/issues
- 邮箱：nuneatonhydroplane@gmail.com
2.1.3 主窗口应用
核心功能：
- 用户注册和登录
- 模型配置管理
- 知识库文档上传
- 预置题库管理
- 面试记录查看
- 系统设置配置
- 数据统计分析
2.2 网关层
2.2.1 Nginx 反向代理
运行方式：Docker 容器（cuemate-web）
端口：80
职责：
- 提供 Web 前端静态文件服务
- API 请求路由和转发
- WebSocket 连接代理
2.3 应用服务层
2.3.1 Web API 服务
运行方式：Docker 容器（cuemate-web-api）
端口：3001
核心职责：
- 用户认证和授权（JWT Token）
- 业务逻辑处理
- 数据持久化（SQLite）
- REST API 接口提供
主要功能模块：
- 用户管理（登录、个人信息）
- 模型配置管理（添加、编辑、删除、测试）
- 知识库管理（文档上传、分类、检索）
- 面试记录管理（创建、查询、统计）
- 系统设置管理（通知、主题、语言）
2.3.2 LLM Router 服务
运行方式：Docker 容器（cuemate-llm-router）
端口：3002
核心职责：
- 统一的 LLM 调用接口
- 多模型服务商适配（24 个）
- 流式响应处理（Server-Sent Events）
- 基础错误处理和状态监控
- 请求超时控制
支持的 LLM 服务商：24 个
- 国际服务商：OpenAI、Azure OpenAI、Anthropic、Google Gemini、AWS Bedrock
- 国内服务商：阿里云百炼、智谱 AI、百川智能、百度千帆、字节豆包、讯飞星火、腾讯混元、腾讯云知识引擎、Kimi、MiniMax、DeepSeek、商汤日日新、阶跃星辰、硅基流动
- 本地模型：Ollama、vLLM、Xinference、Regolo
工作机制：
- 接收前端指定的 provider 和 model 参数
- 根据 provider 选择对应的适配器
- 调用相应的 LLM API 并返回结果
- 失败时记录错误日志和状态信息
- 支持流式和非流式两种调用模式
2.3.3 RAG 服务
运行方式：Docker 容器（cuemate-rag-service）
端口：3003
核心职责：
- 文档解析和分块处理
- 文本向量化
- 语义检索
- 答案增强生成
- 知识库版本管理
工作流程：
- 接收文档上传（PDF、DOCS、Markdown、纯文本）
- 提取文本内容并智能分块
- 使用嵌入模型生成向量
- 存储到 ChromaDB 向量数据库
- 提供语义检索接口
- 结合检索结果增强 LLM 回答
2.4 数据层
2.4.1 SQLite 数据库
运行位置：宿主机文件系统
存储路径：~/Library/Application Support/cuemate-desktop-client/data/sqlite/cuemate.db
存储内容：
- 用户账户信息
- 模型配置信息
- 面试记录数据
- 知识库元数据
- 系统配置参数
2.4.2 ChromaDB 向量数据库
运行方式：Docker 容器（cuemate-chroma）
端口：8000
存储方式：Docker Volume（chroma_data）
存储内容：
- 文档向量索引
- 文档原始内容
- 文档元数据
- 相似度检索缓存
2.4.3 外部 LLM API
调用方式：HTTP/HTTPS API 请求
支持的服务：共 24 个服务商
国际服务商（5 个）：
- OpenAI（GPT 系列）
- Anthropic（Claude 系列）
- Azure OpenAI（微软 Azure 托管的 OpenAI 模型）
- Google Gemini（Google AI 平台）
- AWS Bedrock（AWS 多模型托管平台）
国内服务商（15 个）：
- Moonshot（Kimi 月之暗面）
- 阿里云百炼（Alibaba Cloud Bailian）
- 通义千问（Qwen）
- 智谱 AI（GLM 系列）
- DeepSeek（深度求索）
- 百度千帆（Baidu Qianfan）
- 字节豆包（Volcengine）
- 讯飞星火（Xunfei Spark）
- 腾讯混元（Tencent Hunyuan）
- 腾讯云知识引擎（Tencent Cloud）
- MiniMax（稀宇科技）
- 阶跃星辰（StepFun）
- 商汤日日新（SenseNova）
- 百川智能（Baichuan）
- 硅基流动（SiliconFlow）
本地模型服务（4 个）：
- Ollama（本地模型运行时）
- vLLM（高性能推理引擎）
- Xinference（Xorbits 推理框架）
- Regolo（本地模型服务）
2.5 外部服务层
2.5.1 语音识别服务
运行方式：Docker 容器（cuemate-asr）
端口：10095
通信协议：WebSocket
核心特点：
- 本地运行，无需云端 API
- 支持中文和英文识别
- 实时流式识别
- 低延迟（< 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. 文档上传
用户 → 主窗口应用 (80) → 上传 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 微服务架构
优势：
- 服务独立部署，互不影响
- 按需水平扩展，增加服务实例
- 故障隔离，单个服务异常不影响整体
- 技术栈灵活，可按需选择最适合的语言和框架
4.2 容器化部署
实现方式：Docker + Docker Compose
优势：
- 一键启动所有服务
- 环境一致性保证（开发、测试、生产）
- 资源隔离和限制
- 快速回滚和版本切换
服务列表：
- cuemate-web（Web 前端 + Nginx）
- cuemate-web-api（业务 API）
- cuemate-llm-router（大模型路由）
- cuemate-rag-service（知识库检索）
- cuemate-asr（语音识别）
- cuemate-chroma（向量数据库）
4.3 实时通信
技术方案：
- WebSocket - 双向实时通信（语音识别）
- Server-Sent Events - 单向流式推送（LLM 回答）
- HTTP/HTTPS - 标准 API 请求
应用场景：
- 实时语音转文字（WebSocket）
- 流式答案生成（SSE）
- 数据查询和修改（HTTP）
4.4 混合存储
存储方案：
- SQLite - 结构化数据（用户、配置、记录）
- ChromaDB - 向量数据（文档嵌入、语义检索）
- 文件系统 - 日志文件、临时文件、上传文件
数据路径：
- SQLite：
~/Library/Application Support/cuemate-desktop-client/data/sqlite/ - ChromaDB：Docker Volume
chroma_data - 日志：
~/Library/Application Support/cuemate-desktop-client/data/logs/
4.5 安全设计
安全措施：
- API Key 加密存储（AES-256）
- JWT Token 身份认证
- HTTPS 加密传输（生产环境）
- 权限细粒度控制（RBAC）
- 敏感数据本地存储（不上传云端）
4.6 可观测性
监控方案：
- 统一日志收集（按级别分类：info、warn、error）
- 服务健康检查（定时探测服务状态）
- 错误追踪和告警（异常自动记录）
- 使用统计分析（API 调用次数、Token 消耗）
5. 性能优化
5.1 缓存策略
缓存内容：
- LLM 响应缓存（相同问题直接返回，节省成本）
- 向量检索结果缓存（加速重复查询）
- 静态文件 CDN 加速（提升页面加载速度）
5.2 异步处理
异步任务：
- 文档向量化（避免阻塞用户操作）
- 日志写入（批量写入，减少 IO）
5.3 资源限制
限制措施：
- Docker 容器资源配额（CPU、内存）
- API 请求限流（防止滥用）
- 文件上传大小限制（防止服务器存储耗尽）
6. 扩展性设计
6.1 水平扩展
可扩展服务：
- LLM Router - 部署多个实例，Nginx 负载均衡
- RAG Service - 部署多个实例，并行处理
- Web API - 部署多个实例，分担请求压力
6.2 垂直扩展
扩展方式：
- 增加 Docker 容器资源配额
- 使用更强大的服务器
- GPU 加速（向量化和模型推理）
6.3 插件系统
扩展能力：
- 支持接入第三方 LLM 服务商
- 支持自定义嵌入模型
- 支持自定义提示词模板
- 支持自定义语音识别引擎
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 后端技术
运行时与框架：
数据库：
- SQLite - 世界上使用最广泛的嵌入式数据库引擎
- better-sqlite3 - 高性能的 Node.js SQLite3 绑定库
- ChromaDB - 开源向量数据库，为 AI 应用提供语义检索能力
7.3 AI 服务
语音识别：
音频处理：
- AudioTee - 系统音频捕获工具
大语言模型服务商：
7.4 开发与部署工具
容器化与编排：
- Docker - 容器化平台，让应用部署更加简单可靠
- Docker Compose - 多容器应用编排工具
- Nginx - 高性能 Web 服务器和反向代理
文档解析：
- pdf2json - PDF 文件解析库
- mammoth.js - Word 文档解析库
7.5 开源社区
特别感谢：
- GitHub - 提供代码托管和协作平台
- npm - JavaScript 包管理生态系统
- Stack Overflow - 开发者社区，解决了无数技术难题
- 所有在 GitHub 上提交 Issue 和 Pull Request 的贡献者
7.6 致谢声明
CueMate 是站在巨人的肩膀上构建的。每一个开源项目的维护者、每一位贡献代码的开发者、每一个提供技术支持的社区成员，都是 CueMate 能够诞生的重要力量。
我们承诺：
- 遵守所有开源项目的许可证要求
- 积极参与开源社区，回馈技术生态
- 持续改进 CueMate，为用户提供更好的服务
再次向所有开源项目和技术社区表示最诚挚的感谢！🙏