Meetily 后端如何通过 build-docker.sh 与 run-docker.sh 完成 CPU 版 Docker 部署并查看服务状态

Meetily 后端如何通过 build-docker.sh 与 run-docker.sh 完成 CPU 版 Docker 部署并查看服务状态

【免费下载链接】meetilyPrivacy first, AI meeting assistant with 4x faster Parakeet/Whisper live transcription, speaker diarization, and Ollama summarization built on Rust. 100% local processing. no cloud required. Meetily (Meetly Ai - https://meetily.ai) is the #1 Self-hosted, Open-source Ai meeting note taker for macOS & Windows. Understand How to write meeting minutes项目地址: https://gitcode.com/GitHub_Trending/me/meetily

Meetily 后端的 Docker 部署由两个脚本协作完成：build-docker.sh负责构建镜像，run-docker.sh负责启动和管理容器。两者都位于backend目录，面向 macOS/Linux 的 Bash 环境（Windows 对应build-docker.ps1/run-docker.ps1）。部署成功后会在本机得到两个服务：Whisper 语音转写服务（默认端口 8178）和 FastAPI 会议应用（默认端口 5167），全部运行在 Docker 容器内。

部署前需要满足的条件

• 已安装 Docker：Linux 使用 Docker Engine，macOS 使用 Docker Desktop；
• Docker Buildx 可用——build-docker.sh 会执行docker buildx version检查，不可用会直接报错退出；首次构建时脚本会创建一个名为whisper-builder的 buildx 构建器；
• backend目录下存在whisper.cpp目录，脚本检查不到时会输出 "whisper.cpp directory not found" 并退出；
• 给 Docker 分配 8GB 以上内存。backend/README.md 要求为容器分配 8GB+ RAM；docker-compose.yml 的注释进一步建议每个服务 8GB 内存起、2 个以上 CPU 核心；
• 能访问外网：Whisper 模型不在本地时由脚本或容器下载。

用 build-docker.sh 构建 CPU 版镜像

在backend目录下执行：

cd backend ./build-docker.sh cpu

cpu参数指定构建 CPU 版 whisper server，会议应用镜像会一并构建。脚本按以下顺序执行：

1. 创建data/、models/、config/目录；
2. 检查 Docker、Buildx 与whisper.cpp目录；
3. 进入whisper.cpp目录执行git submodule update --init --recursive（会更新该子模块的检出状态），并把whisper-custom/server/下的自定义 server 文件复制到whisper.cpp/examples/server/；
4. 基于 Dockerfile.server-cpu 构建whisper-server镜像，基于 Dockerfile.app 构建meetily-backend镜像。两个镜像都会打上「类型-日期-githash」形式的完整标签，并额外打一个短标签（whisper-server:cpu、meetily-backend:app）。

每个镜像构建成功会输出Successfully built: <镜像名:标签>，全部结束后输出=== Build Complete ===，本地构建还会列出已构建的镜像清单，可据此确认两个镜像都已生成。

两点说明：

• 在 macOS 上执行cpu时，脚本检测到系统后会自动改用 macOS 优化构建（Dockerfile.server-macos），这是脚本内置行为，无需额外操作。
• run-docker.sh 的start在启动前会检查whisper-server:cpu和meetily-backend镜像是否存在，缺失时会自动调用build-docker.sh构建。所以这一步可以省略，但预先构建能让你在启动阶段之前就看到构建错误。

可选参数：--no-cache（不使用缓存构建）、--dry-run（只打印将执行的命令），常规部署不需要。./run-docker.sh build cpu也可以作为入口，它会原样转发给build-docker.sh。

用 run-docker.sh 启动两个服务

首次部署：交互式启动

./run-docker.sh start --interactive

向导依次要求确认：

• 模型：默认base.en，支持 tiny 到 large-v3 及 q5_1、turbo 变体，大小参考（来自 README）：tiny ~39 MB、base ~142 MB、small ~244 MB、medium ~769 MB、large-v3 ~1550 MB；
• 语言：默认 auto，也支持直接输入语言代码；
• 端口：Whisper 端口默认 8178、应用端口默认 5167，带冲突检测；
• 数据库：全新安装（在backend/data/下创建空的meeting_minutes.db）或从已有安装迁移；
• GPU 模式：自动检测，未检测到 GPU 的机器会提示 "No GPU detected, using CPU mode"；
• 翻译：是否启用转写成英文。

选择会保存到backend/.docker-preferences，下次启动可直接复用。

如果所选模型不在本地backend/models/目录，脚本会提示 "Download model now? (Y/n)"：选 Y 会立即下载到backend/models/ggml-<model>.bin；选 N 或非交互环境时，模型在容器启动过程中自动下载，启动时间会更长。

非交互启动

./run-docker.sh start --detach

注意：在终端中执行且未传自定义模型/语言时，脚本仍会先进入设置流程——首次运行直接进入上面的完整设置向导；如果已存在.docker-preferences，则先出现「1 复用上次设置 / 2 自定义 / 3 使用默认值」菜单，选 3 即可按默认值继续，随后在后台启动。也可以把参数一次给全，完全跳过交互（README 中的示例）：

./run-docker.sh start --model base --language es --detach

不带--detach时，脚本启动服务后会持续跟随容器日志，按 Ctrl+C 会弹出「继续看日志 / 退出（服务保持运行）/ 停止服务 / 重启 / 查看状态」的选项菜单。

其他常用选项见./run-docker.sh --help：--port（Whisper 端口）、--app-port（应用端口）、--cpu/--gpu（强制模式，CPU-only 机器默认就是 CPU 镜像，可不传）、--env-file。环境变量WHISPER_MODEL、WHISPER_PORT、APP_PORT也能覆盖对应默认值。

验证服务是否就绪

启动时的自动检查

--detach启动成功后，脚本先输出两个服务地址（Whisper Server: http://localhost:<port>、Meeting App: http://localhost:<app_port>），然后自动等待两个阶段：

1. 等待容器内模型文件就绪，最长 5 分钟（对应模型下载）；
2. 轮询http://localhost:8178/与http://localhost:5167/get-meetings两个端点，最长 1 分钟。

两个端点都有响应时输出 "All services are ready!"；某一项超时则输出对应服务的日志排查命令（logs --service whisper -f或logs --service app -f）。

用 status 命令查看

./run-docker.sh status

该命令先执行docker compose ps显示容器状态，再检查容器端口映射，并对两个服务做连通性检查，输出形如：

Whisper Server: http://localhost:8178 Whisper Server is responding Meeting App: http://localhost:5167 Meeting App is responding

（端口以脚本实际显示的映射端口为准；服务无响应时会输出 "not responding"。）如果两个容器都不在运行，会输出 "No services are running"。

手动访问确认

• Whisper Server：http://localhost:8178，健康检查为GET /，转写接口为POST /inference，另提供 WebSocket（ws://localhost:8178/）；
• 会议应用：http://localhost:5167，API 文档在http://localhost:5167/docs（Swagger UI），健康检查为GET /get-meetings，WebSocket 为ws://localhost:5167/ws。

运行中的常见处理与适用边界

端口冲突：先./run-docker.sh stop停掉服务，再用lsof -i :8178（macOS/Linux）或netstat -an | grep :8178查看占用进程。交互式启动的端口选择菜单在检测到端口被占用时，也可以选择直接终止占用进程——该操作会对目标端口进程执行kill -9，执行前请确认该进程可以终止。

模型下载失败：确认网络连接与磁盘空间后手动下载：

./run-docker.sh models download base.en

脚本从 Hugging Face 的 whisper.cpp 仓库拉取ggml-<model>.bin到backend/models/，成功后输出 "Model downloaded successfully"。模型名必须在脚本支持列表内（tiny 到 large-v3 及其 q5_1、turbo 变体），否则报错并列出可用模型。

停止与清理：./run-docker.sh stop执行docker compose down停止服务。./run-docker.sh clean执行down --volumes --remove-orphans，除容器外还会删除 compose 定义的数据卷，包括存放已下载模型的whisper_models卷（模型下次需要重新下载；backend/data/是 bind mount，数据库文件不受影响），加--images还会删除镜像。执行前确认不再需要当前运行数据。

资源不足导致丢音频：容器内存/CPU 不足时，音频处理队列（上限 10 条）会被写满，日志出现 "Dropped old audio chunk X due to queue overflow"，症状是转写缺失或不完整、处理延迟。对策是增大 Docker 的内存与 CPU 分配（README 建议 8GB+ 内存），并选择与硬件匹配的 Whisper 模型大小。

适用边界：

• 本文只覆盖 CPU 路径；GPU 构建需要 NVIDIA 驱动和 nvidia-container-toolkit，属于另一条路径（./build-docker.sh gpu）；
• README 的脚本参考列出了--diarize启动选项，但在 run-docker.sh 中该选项已被注释（"Feature not available yet"），当前版本暂不可用；
• 脚本运行会修改本地文件：创建data/、models/、config/目录，生成.docker-preferences偏好文件和data/meeting_minutes.db，并在whisper.cpp内更新子模块。

更多脚本说明可参考 backend/SCRIPTS_DOCUMENTATION.md，服务编排细节见 backend/docker-compose.yml。

【免费下载链接】meetilyPrivacy first, AI meeting assistant with 4x faster Parakeet/Whisper live transcription, speaker diarization, and Ollama summarization built on Rust. 100% local processing. no cloud required. Meetily (Meetly Ai - https://meetily.ai) is the #1 Self-hosted, Open-source Ai meeting note taker for macOS & Windows. Understand How to write meeting minutes项目地址: https://gitcode.com/GitHub_Trending/me/meetily