Voquill企业版部署完全指南:自托管、SSO单点登录与全局词典配置

原创2026-10-16 15:07:10362 阅读

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 配置步骤

  1. 在 Keycloak 管理台创建 Realm(如 voquill)
  2. Clients → Create client,Client ID 填 voquill-desktop,打开 Client authentication
  3. Login settings 中设置 Valid redirect URI:https://your-gateway-url/auth/oidc/callback(必须与网关地址完全一致,含端口与 http/https)
  4. 在 Credentials 页复制 Client secret
  5. 创建用户时务必填写 Email——OIDC 流程依赖 email 声明来匹配/创建用户

Azure Entra ID 配置要点

  1. 在 Entra admin center 注册应用,Redirect URI 选择 Web 平台,填 https://your-gateway-url/auth/oidc/callback
  2. 记录 Application (client) ID 与 Directory (tenant) ID
  3. 创建 Client secret 并立即复制 Value(只显示一次)
  4. 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 提供商:

Voquill企业版管理后台添加本地转写提供商

AI Providers 页同理添加 Ollama 提供商,保存后系统自动拉取模型并显示同步状态(Syncing… → Synced):

Voquill企业版管理后台配置Ollama本地后处理提供商

两种场景均可横向扩展:在多台机器上各跑一个实例,全部添加为提供商,Voquill 自动负载均衡。硬件建议 GPU + 至少 16 GB 内存,纯 CPU 也能跑但明显更慢。

日常运维:更新与许可证续期

升级服务端(数据存在 Postgres 卷中,更新不受影响):

docker compose pull
docker compose up -d

桌面端随开源客户端自动更新。许可证到期日可在管理后台 Settings 页直接查看:

Voquill企业版管理后台Settings页面查看许可证到期时间

续期流程非常简单:获取新许可证密钥 → 替换 docker-compose.yml 中的 LICENSE_KEY → 重启 gateway(docker compose up -d gateway)。用户、配置与数据全部保留。详见 on-premise/renewal.md。

写在最后

到这里,一套完整可控的 Voquill 企业语音基础设施就搭建完成了:Docker Compose 三步完成自托管,OIDC 一行配置接入现有身份体系,全局词典让专业词汇全员共享。配合本地转写与本地后处理,敏感语音数据可以做到零外流——这就是"用嘴打字"的企业级答案。

登录后查看全文
voquill