Violin Docker生产部署实战：Compose+Caddy一键上线，自动开启HTTPS

Violin 视频翻译服务的生产级部署方案

Violin 是一款开源的 AI 视频翻译工具：上传视频后，它会自动转写语音、翻译台词、合成母语级配音并重新对齐回视频。本文介绍如何使用 Docker + docker compose + Caddy 三件套，把 Violin 的 Web 版（FastAPI API + 浏览器界面）一键部署到服务器，并自动申请 Let's Encrypt 证书开启 HTTPS——这正是官方线上 demo 同款的生产部署方式。

部署架构一览：为什么选 Compose + Caddy

仓库中已内置三个生产部署文件，无需自己搭建：

文件	作用
Dockerfile	构建镜像：python:3.13-slim + ffmpeg + uv，启动 API 服务（监听 8000 端口）
docker-compose.yml	编排 violin（应用）与 caddy（反向代理）两个容器，自动挂载 3 个数据卷
Caddyfile	Caddy 反代配置：域名 → violin:8000，证书全自动签发

架构非常简洁：

浏览器 (https://你的域名)
      │
      ▼
  Caddy 容器 ── 80/443 端口对外
      │  reverse_proxy violin:8000
      ▼
Violin 容器（FastAPI，仅 expose 8000，不对外暴露）
      │
      ▼
jobs_data 卷（持久化任务文件）

几个值得新手注意的设计细节：

• 应用容器不暴露端口：violin 服务只 expose: 8000，80/443 完全由 Caddy 容器接管，外部流量一律走 HTTPS；
• 任务数据持久化：翻译产出的视频/SRT 存放在命名卷 jobs_data（映射到容器内 /app/jobs），容器重建不丢数据；
• 自动重启：两个容器都设置了 restart: unless-stopped，服务器重启后服务自动拉起。

五步完成部署：从克隆到 HTTPS 上线

1. 克隆仓库

git clone https://gitcode.com/gh_mirrors/violi/violin
cd violin

服务器需提前安装 Docker 与 Docker Compose 插件。

2. 配置 API 密钥

复制环境变量模板并填入密钥：

cp .env.example .env
vim .env

.env.example 中支持三个供应商，只需填写你实际使用的：

变量	何时需要
TOGETHER_API_KEY	默认配置（Whisper 转写 + LLM 翻译 + TTS），推荐，填这一个即可跑通全流程
OPENAI_API_KEY	任一阶段使用 provider: openai 时
ELEVENLABS_API_KEY	TTS 使用 provider: elevenlabs 时

3. 修改 Caddyfile 填入你的域名

编辑 Caddyfile，把示例域名换成你自己的：

your-domain.com {
    reverse_proxy violin:8000
}

⚠️ 前提：域名的 DNS A 记录已指向服务器公网 IP。Caddy 启动后会自动向 Let's Encrypt 申请并续期 TLS 证书，无需任何手动操作——这就是"自动开启 HTTPS"的关键。

🔧 没有域名想先本地测试？ 按 Caddyfile 顶部注释，临时改用 :80 { reverse_proxy violin:8000 } 即可走纯 HTTP 端口 80 访问。

4. 一键构建并启动

docker compose up -d --build

这一条命令完成全部工作：构建 Violin 镜像（依赖锁定在 uv.lock，环境可复现）→ 拉取 caddy:2-alpine → 创建数据卷 → 后台启动两个容器。

5. 验证部署结果

docker compose ps          # 两个容器应为 Up
docker compose logs violin # 查看 API 启动日志

打开浏览器访问 https://你的域名 看到 Web 界面即部署成功；访问 https://你的域名/docs 可打开交互式 REST API 文档。

生产配置解读：config/prod.yaml 做了什么

容器启动时，Dockerfile 默认以 config/prod.yaml 作为配置加载（入口为 run_api.py）。它只覆盖与 config/default.yaml 不同的字段，其余全部沿用默认值：

参数	值	生产意义
api.max_workers	2	并发任务数，控制 ffmpeg 总进程数，防止内存打爆
merge_video.workers	4	每个任务内并发的 ffmpeg 数（每个约 300MB 内存）
api.job_ttl_hours	24	24 小时自动清理完成任务，防止磁盘被占满
api.url_upload	false	禁用 URL 拉取视频，规避滥用风险
api.max_duration_seconds	1800	拒绝超过 30 分钟的视频，控制 API 开销
api.max_file_size_mb	500	上传大小上限
api.free_trial_jobs	1	每个 IP 可免费试跑 1 次，之后需提供自己的 key

💡 以上参数基于 4 vCPU / 8GB 内存的机器调优（峰值约 4.4GB），配置更小或更大的服务器时可按注释中的内存估算自行调整。

另外，启动时 run_api.py 会校验环境变量：free_trial_jobs > 0 但 .env 中缺少对应密钥时，服务会直接拒绝启动并给出明确提示，避免半配置状态上线。

常用运维命令速查

docker compose ps                    # 查看状态
docker compose logs -f violin         # 跟踪应用日志
docker compose down                   # 停止并移除容器（数据卷保留）
docker compose up -d --build          # 拉取新代码后重建上线
docker volume ls | grep jobs_data     # 查看任务数据卷

常见问题排查

• HTTPS 证书申请失败：99% 是 DNS 还没生效。用 dig 你的域名 确认 A 记录已指向服务器 IP，等待解析生效后 Caddy 会自动重试，无需重启。
• 服务启动即退出，日志提示 missing required environment variable：.env 未填 TOGETHER_API_KEY，或想改成纯 BYOK 模式（用户自带 key）则需把配置中 api.free_trial_jobs 设为 0。
• 磁盘越来越大：确认运行的是 prod 配置（job_ttl_hours: 24 会自动清理旧任务）；如自定义了配置，记得设置该参数。
• 视频翻译特别慢：正常现象——转写、翻译、配音、ffmpeg 对齐每一步都在真实跑模型，几分钟内出片属正常水平。

总结

Violin 的生产部署链路非常"开箱即用"：Dockerfile 管构建、docker-compose.yml 管编排、Caddyfile 管域名与自动 HTTPS，配合 config/prod.yaml 的一套安全护栏（任务 TTL、上传限制、并发上限），只需一条 docker compose up -d --build 就能把开源视频翻译服务稳定地跑在任何 Docker 主机上。对新手而言，这是学习"应用 + 反代 + 自动证书"标准生产架构的一个绝佳范例。