LiveKit 部署配置生成器 Docker 镜像文档

一、镜像概述和主要用途

本镜像（livekit/config-generator）是一个用于自动生成 LiveKit 部署配置的工具镜像。LiveKit 是一个开源的实时音视频平台，部署过程涉及多个组件配置（如服务端、媒体节点、依赖组件等），本镜像通过简化配置生成流程，帮助用户快速生成可直接使用的部署配置文件（如 docker-compose.yml、livekit.yaml、环境变量文件等），降低 LiveKit 部署门槛。

二、核心功能和特性

2.1 核心功能

• 自动生成 LiveKit 完整部署配置文件集，包括服务编排、组件依赖、环境变量等
• 支持根据部署场景（开发/生产）动态调整配置参数
• 集成 LiveKit 依赖组件（如 Redis、NATS、TURN 服务器）的默认配置
• 生成配置后自动验证格式有效性，避免语法错误

2.2 关键特性

• 轻量级：基于 Alpine 构建，镜像体积小，启动速度快
• 可定制：支持通过环境变量或命令行参数自定义配置细节（如域名、端口、组件版本等）
• 多环境适配：内置开发环境（本地测试）和生产环境（高可用配置）模板
• 输出灵活：支持将配置文件导出到宿主机指定目录，或直接输出到标准输出

三、使用场景和适用范围

3.1 适用场景

• 初次部署 LiveKit：帮助新手用户快速生成可用配置，避免手动编写复杂配置文件
• 快速测试环境搭建：开发者可通过本工具一键生成开发环境配置，加速功能验证
• 标准化部署流程：企业或团队可基于本镜像统一部署配置模板，确保环境一致性
• 配置迁移/升级：支持根据 LiveKit 版本自动调整配置项，简化版本升级流程

3.2 适用范围

• LiveKit 初学者及开发者
• 需要快速交付 LiveKit 部署环境的运维人员
• 对部署配置规范性有要求的团队

四、详细使用方法和配置说明

4.1 前置条件

• 已安装 Docker 环境（推荐 Docker 20.10+）
• 宿主机需有可写目录用于挂载输出配置文件（如 ./livekit-config）

4.2 基本使用流程

4.2.1 拉取镜像

docker pull livekit/config-generator:latest

4.2.2 生成配置文件

通过运行容器生成配置，默认将配置文件输出到宿主机 ./livekit-config 目录：

docker run -it --rm \
  -v $(pwd)/livekit-config:/output \
  -e ENVIRONMENT=production \
  -e DOMAIN=livekit.example.com \
  -e ENABLE_HTTPS=true \
  livekit/config-generator:latest

4.2.3 使用生成的配置部署 LiveKit

生成的配置文件位于 ./livekit-config 目录，包含：

• docker-compose.yml：服务编排配置（含 LiveKit 服务端、媒体节点、Redis 等）
• livekit.yaml：LiveKit 核心配置（含 API 密钥、媒体设置等）
• .env：环境变量文件（敏感信息如密钥、证书路径等）
• nginx.conf（可选）：反向代理配置（若启用 HTTPS）

部署命令：

cd ./livekit-config
docker-compose up -d

4.3 配置参数说明

4.3.1 环境变量参数

4.4 高级用法：自定义配置模板

若默认模板不满足需求，可通过挂载自定义模板目录覆盖默认模板：

docker run -it --rm \
  -v $(pwd)/livekit-config:/output \
  -v $(pwd)/custom-templates:/templates \  # 挂载自定义模板目录
  -e ENVIRONMENT=production \
  livekit/config-generator:latest

模板目录需包含与默认模板同名文件（如 docker-compose.tpl.yml、livekit.tpl.yaml），支持 Go 模板语法。

五、Docker 部署方案示例

5.1 本地开发环境快速部署

# 生成开发环境配置（默认输出到 ./livekit-dev-config）
docker run -it --rm \
  -v $(pwd)/livekit-dev-config:/output \
  -e ENVIRONMENT=development \
  -e LIVEKIT_VERSION=v1.5.0 \
  livekit/config-generator:latest

# 启动服务
cd ./livekit-dev-config && docker-compose up -d

5.2 生产环境部署（带 HTTPS）

# 生成生产环境配置（输出到 ./livekit-prod-config）
docker run -it --rm \
  -v $(pwd)/livekit-prod-config:/output \
  -e ENVIRONMENT=production \
  -e DOMAIN=livekit.example.com \
  -e ENABLE_HTTPS=true \
  -e LIVEKIT_VERSION=v1.5.0 \
  -e REDIS_URL=redis://external-redis.example.com:6379 \  # 使用外部 Redis
  livekit/config-generator:latest

# 启动服务（生产环境建议先检查配置）
cd ./livekit-prod-config && docker-compose config  # 验证配置
cd ./livekit-prod-config && docker-compose up -d   # 启动服务

六、注意事项

1. 生产环境需确保 DOMAIN 可解析且端口（80/443）开放，HTTPS 依赖 Let's Encrypt 证书（默认自动生成，需域名可访问）
2. 生成的 .env 文件包含敏感信息（如 API 密钥），需妥善保管，避免提交至代码仓库
3. 自定义外部组件（如 Redis、NATS）时，需确保网络互通且权限正确
4. 若宿主机目录权限不足，可添加 --user $(id -u):$(id -g) 到 docker run 命令，避免文件权限问题