Voquill企业版部署完全指南:自托管、SSO单点登录与全局词典配置
Voquill企业版部署完全指南:自托管、SSO单点登录与全局词典配置
Voquill 是一款开源的 AI 语音输入工具,让你"用嘴打字",比键盘快 4 倍。它的企业版(Voquill Enterprise)支持三种部署形态:托管云、自有云自托管和完全本地化部署。本篇指南带你从零完成 Voquill 企业版部署:用 Docker Compose 一键自托管,接入 Keycloak 或 Azure Entra ID 实现 SSO 单点登录,并配置全局词典让全员共享专业词汇。所有语音数据都留在你的基础设施内,代码完全开源可审计。
三种部署方式怎么选?
| 方式 | 说明 | 适合场景 |
|---|---|---|
| Managed Cloud(托管云) | 官方为你部署并运维专属云实例 | 不想运维、快速上手 |
| Self-Hosted Cloud(自托管云) | 部署在自有 AWS / GCP / Azure 云账号 | 有云资源,希望数据自控 |
| On-Premise(本地化部署) | 完全跑在自有硬件,零外部依赖 | 金融、医疗等高合规行业 |
三种方式的数据控制权完全归你所有——除非你主动配置,否则没有任何数据会离开你的环境。官方文档入口:enterprise/overview.md。
💡 企业版代码完全开源(AGPLv3),运行需商业许可证;安全团队可以逐行审计你环境里跑的每一行代码。
一键自托管:Docker Compose 部署步骤
前置条件:一台网络可达的服务器,装好 Docker 和 Docker Compose,并持有 Voquill Enterprise 许可证。
仓库内已内置一套可直接参考的完整编排文件(含 Keycloak、Speaches、Ollama):enterprise/docker-compose.yml,核心部署文档见 on-premise/setup.md。
生产环境最小部署只需 3 个服务:admin(管理后台)、gateway(网关)、postgres(数据库),关键配置如下:
services:
admin:
image: ghcr.io/voquill/voquill/enterprise-admin:latest
ports: ["5100:5173"]
environment:
- VOQUILL_GATEWAY_URL=http://localhost:4630
gateway:
image: ghcr.io/voquill/voquill/enterprise-gateway:latest
ports: ["4630:4630"]
environment:
- DATABASE_URL=postgres://postgres:postgres@postgres:5432/voquill
- JWT_SECRET=fill-me-in # 生产环境务必换成强随机值
- ENCRYPTION_SECRET=fill-me-in # 同上
- LICENSE_KEY=your-license-key # 开通时提供的许可证密钥
postgres:
image: postgres:16-alpine
volumes: [postgres_data:/var/lib/postgresql/data]
许可证密钥的格式可参考样例文件 enterprise/docs/config.sample.json。然后执行:
docker compose pull # 拉取镜像
docker compose up -d # 启动服务
桌面客户端接入网关
每个 Voquill 桌面客户端需要一个 enterprise.json 文件,告诉它网关地址:
| 平台 | 路径 |
|---|---|
| macOS | ~/Library/Application Support/com.voquill.desktop/enterprise.json |
| Linux | ~/.config/com.voquill.desktop/enterprise.json |
| Windows | C:\Users\<User>\AppData\Roaming\com.voquill.desktop\enterprise.json |
文件内容只有一行核心配置:
{ "gatewayUrl": "http://your-host:4630" }
该文件的读取逻辑在桌面端 Tauri 源码 enterprise_oidc.rs 与前端 enterprise.utils.ts 中实现。如果使用 Intune 等工具分发客户端,可以在部署时自动下发这个文件,无需逐台手配。
创建第一个管理员
浏览器打开 http://your-host:5100 即为企业版管理后台。第一个注册的用户自动成为组织管理员——请务必使用强密码并妥善保存,初始管理员账户没有密码找回功能。
SSO 单点登录配置:Keycloak 与 Azure Entra ID
Voquill 企业版支持任意 OIDC 兼容的身份提供商,用户首次登录时自动创建账户(JIT 即时开通),无需管理员逐个建号。整体流程:管理员在后台添加提供商 → 用户点击登录页的 SSO 按钮 → 跳转身份提供商认证 → 自动回跳并登录。
Keycloak 配置步骤
- 在 Keycloak 管理台创建 Realm(如
voquill) - Clients → Create client,Client ID 填
voquill-desktop,打开 Client authentication - Login settings 中设置 Valid redirect URI:
https://your-gateway-url/auth/oidc/callback(必须与网关地址完全一致,含端口与 http/https) - 在 Credentials 页复制 Client secret
- 创建用户时务必填写 Email——OIDC 流程依赖
email声明来匹配/创建用户
Azure Entra ID 配置要点
- 在 Entra admin center 注册应用,Redirect URI 选择 Web 平台,填
https://your-gateway-url/auth/oidc/callback - 记录 Application (client) ID 与 Directory (tenant) ID
- 创建 Client secret 并立即复制 Value(只显示一次)
- Issuer URL 格式为
https://login.microsoftonline.com/{tenant-id}/v2.0(结尾不能带斜杠)
在 Voquill 管理后台添加提供商
进入 Identity Providers → Add Provider,填写:
| 字段 | 说明 |
|---|---|
| Name | 登录按钮上显示的文案,如 Microsoft |
| Issuer URL | Keycloak 为 https://kc-url/realms/{realm};Entra ID 见上文格式 |
| Client ID | 身份提供商中创建的客户端 ID |
| Client Secret | 对应密钥 |
| Enabled | 开启 |
必填声明只有两个:sub(用户唯一标识)和 email,name 可选。提供商数据的落库迁移见 017_add_oidc_providers.sql,后台界面源码在 oidc-providers/。
常见报错速查 🛠️
| 报错 | 原因与解法 |
|---|---|
Discovery failed |
Issuer URL 写错或多了结尾斜杠;网关无法连通身份提供商(防火墙) |
Redirect mismatch / AADSTS50011 |
重定向 URI 不精确匹配,检查 http/https、端口、完整路径 /auth/oidc/callback |
Application not found |
用错 ID——应填 Application (client) ID 而非 Object ID |
| 登录成功但用户未创建 | 身份提供商中该用户没有设置邮箱 |
详细步骤文档:sso/overview.md、keycloak.md、azure-entra-id.md。
全局词典:一次配置,全员生效
Voquill 的全局词典(Global Dictionary)让你定义组织级的术语表与替换规则,自动推送到每一台桌面客户端,无需逐人配置。它和桌面端个人词典的机制一致(可参考 dictionary.png 界面),区别在于作用范围:全局词条覆盖全员,个人词条管私有,两者在转写时自动合并。
全局词典包含两类条目:
- Glossary Terms(术语提示):在语音识别阶段提示转写模型正确识别领域词汇——产品名、内部项目代号、人名等。例如公司天天提到 "Kubernetes"、"Terraform",加入术语表后识别准确率立刻提升。
- Replacement Rules(替换规则):在 AI 后处理之前对原始转写做查找替换,适合修复固定错误。
| 输入 | 输出 |
|---|---|
| V quill | Voquill |
| kube | Kubernetes |
经验法则:全公司通用的词放全局词典(公司缩写、产品线、行业黑话),个人工作流相关的词留个人词典。管理界面在 admin-portal/global-dictionary.md,前端源码位于 terms/。
语音链路全私有:本地转写与本地后处理
追求彻底离线时,可以把语音链路的两步也搬到内网:
- 本地转写:部署 Speaches(OpenAI 兼容的 faster-whisper 服务),音频不出内网
- 本地后处理:部署 Ollama 运行 LLM 清理转写文本
在管理后台 Transcription Providers 页添加 Speaches 提供商:
AI Providers 页同理添加 Ollama 提供商,保存后系统自动拉取模型并显示同步状态(Syncing… → Synced):
两种场景均可横向扩展:在多台机器上各跑一个实例,全部添加为提供商,Voquill 自动负载均衡。硬件建议 GPU + 至少 16 GB 内存,纯 CPU 也能跑但明显更慢。
日常运维:更新与许可证续期
升级服务端(数据存在 Postgres 卷中,更新不受影响):
docker compose pull
docker compose up -d
桌面端随开源客户端自动更新。许可证到期日可在管理后台 Settings 页直接查看:
续期流程非常简单:获取新许可证密钥 → 替换 docker-compose.yml 中的 LICENSE_KEY → 重启 gateway(docker compose up -d gateway)。用户、配置与数据全部保留。详见 on-premise/renewal.md。
写在最后
到这里,一套完整可控的 Voquill 企业语音基础设施就搭建完成了:Docker Compose 三步完成自托管,OIDC 一行配置接入现有身份体系,全局词典让专业词汇全员共享。配合本地转写与本地后处理,敏感语音数据可以做到零外流——这就是"用嘴打字"的企业级答案。


