difyz9/whisper-go-base repository overview

⁠whisper-go-base

difyz9/whisper-go-base 是 whisper_with_go 项目的基础运行镜像，面向需要快速启动 Whisper Go 服务、统一开发环境，或避免重复编译 whisper.cpp 的使用场景。

该镜像预装以下组件：

• Go 1.23.4
• FFmpeg
• whisper.cpp
• CGO 编译和运行依赖

支持平台：

• linux/amd64
• linux/arm64

⁠镜像定位

这不是一个已经打包好业务代码的最终应用镜像。

它的定位是“基础环境镜像”：

• 负责提供 Whisper 运行和 Go 编译环境
• 由业务项目在运行时挂载源码目录
• 用于快速启动、开发调试和轻量部署

对于 whisper_with_go 项目，这种方式可以避免每次都重新构建 whisper.cpp 和系统依赖，从而显著缩短启动准备时间。

⁠快速开始

如果你已经拿到 whisper_with_go 项目源码，推荐直接在项目根目录运行：

docker compose up -d

这条命令会完成以下工作：

1. 拉取 difyz9/whisper-go-base
2. 将当前项目目录挂载到容器内 /workspace
3. 在容器内执行 go mod download && go run cmd/server/main.go

启动前请确认：

1. Docker 已安装并正常运行
2. Docker Compose 可用
3. 模型文件 models/ggml-base.bin 已存在
4. 当前目录为项目根目录

⁠常用命令

启动服务：

docker compose up -d

查看日志：

docker compose logs -f

查看状态：

docker compose ps

停止服务：

docker compose down

⁠拉取镜像

拉取最新版本：

docker pull difyz9/whisper-go-base:latest

拉取指定版本：

docker pull difyz9/whisper-go-base:v0.0.2

指定平台拉取：

docker pull --platform linux/amd64 difyz9/whisper-go-base:latest
docker pull --platform linux/arm64 difyz9/whisper-go-base:latest

⁠版本策略

推荐策略如下：

• 生产环境使用明确版本 tag，例如 v0.0.2
• 测试环境或日常体验使用 latest

版本映射规则：

• Git tag v0.0.2 会生成 Docker tag v0.0.2
• 同时生成无前缀版本 tag 0.0.2
• 可选更新 latest

示例：

docker pull difyz9/whisper-go-base:v0.0.2
docker pull difyz9/whisper-go-base:0.0.2
docker pull difyz9/whisper-go-base:latest

⁠配置自定义镜像版本

项目默认从 ../.env⁠ 读取 WHISPER_BASE_IMAGE。如果你需要临时切换版本，可以直接覆盖它。

Linux / macOS：

WHISPER_BASE_IMAGE=difyz9/whisper-go-base:v0.0.2 docker compose up -d

Windows PowerShell：

$env:WHISPER_BASE_IMAGE="difyz9/whisper-go-base:v0.0.2"
docker compose up -d

⁠辅助启动脚本

如果你希望用脚本统一处理镜像拉取和 compose 启动，可以使用项目自带脚本。

Windows PowerShell：

.\scripts\compose-base.ps1 -Action up -Image difyz9/whisper-go-base:latest

Linux / macOS：

chmod +x ./scripts/compose-base.sh
./scripts/compose-base.sh --action up --image difyz9/whisper-go-base:latest

⁠适用场景

推荐用于：

• 快速运行 whisper_with_go 当前项目
• 团队统一开发和测试环境
• 避免重复编译底层依赖
• 在多台机器上快速复用相同基础环境

不适合用于：

• 希望交付完全独立、已包含业务代码的最终应用镜像
• 完全离线且无法访问 Docker Hub 的环境

⁠常见问题

⁠docker compose up -d 启动失败

建议优先检查：

1. Docker 服务是否正常
2. 当前目录是否为项目根目录
3. 模型文件 models/ggml-base.bin 是否存在
4. WHISPER_BASE_IMAGE 指向的 tag 是否存在

⁠镜像拉取失败

建议检查：

1. Docker Hub 仓库名是否正确
2. 指定 tag 是否已发布
3. 当前网络是否可访问 Docker Hub

⁠服务启动成功但转录失败

通常与以下问题相关：

1. 模型文件缺失
2. uploads 或 outputs 目录权限异常
3. 输入音频格式不受支持

⁠如何切换到本地构建镜像流程

如果你仍然需要使用本地 build 方式，可以执行：

docker compose -f docker-compose.build.yml up -d --build

⁠维护者发布说明

工作流文件： build-base-image.yml⁠

发布前需要在 GitHub 仓库中配置以下 Secrets：

1. DOCKERHUB_USERNAME
2. DOCKERHUB_TOKEN

建议使用 Docker Hub Access Token，而不是账号密码。

⁠通过 Git tag 发布

示例：

git tag v0.0.2
git push origin v0.0.2

工作流会自动：

1. 解析 tag
2. 在 workflow 内动态写入构建脚本和 Dockerfile
3. 使用 Buildx 构建多架构镜像
4. 推送到 Docker Hub

默认发布的 tags：

• difyz9/whisper-go-base:v0.0.2
• difyz9/whisper-go-base:0.0.2
• difyz9/whisper-go-base:latest

⁠手动触发参数

GitHub Actions 页面支持传入：

1. tag
2. platforms
3. push_latest