JackTrip Virtual Studio Container 中文技术文档

镜像概述和主要用途

jacktrip/studio 镜像是用于管理自有 Virtual Studio 服务器的容器化解决方案，提供托管 JackTrip Virtual Studio 会话所需的全部组件。通过该镜像，用户可在自有服务器上部署非托管的 Virtual Studio 实例，实现音频协作功能。

核心功能和特性

• 身份认证集成：通过 JackTrip API 进行身份验证，确保工作室实例的合法性
• 音频优化处理：支持实时优先级进程运行，防止音频卡顿；需锁定特定大小的共享内存以保障音频流稳定性
• 灵活配置管理：支持通过环境变量或配置文件注入必要参数
• 跨容器工具支持：兼容 Podman 和 Docker 运行环境，针对不同工具提供特定配置选项

使用场景和适用范围

适用场景

• 需要在自有服务器上托管非托管 Virtual Studio 的场景
• 对服务器配置有完全控制权，需自定义网络、安全策略的用户

适用范围

• 技能要求：需具备高级 IT 技能，熟悉网络路由、防火墙、DNS 配置、TLS 证书管理等
• 环境要求：需具备公网可访问的服务器（带有效 FQDN）、有效的 TLS 证书及 HTTPS 服务器

环境要求

DNS、TLS 和入口要求

• 服务器配置：需公网可访问的服务器，且已配置指向其 IP 地址的有效完全限定域名（FQDN）
• TLS 证书：需有效的 TLS（SSL）证书
• HTTPS 代理：需在服务器上部署 HTTPS 服务器（监听 443 端口），终止加密连接后将未加密请求代理至容器内的 8000 端口

必填环境变量

以下变量需从工作室控制台（将工作室迁移为非托管后获取）获取，用于容器与 JackTrip API 的认证：

提供方式

• 命令行参数：通过 -e 选项直接传入
• 环境配置文件：挂载包含变量的文件至容器内 /etc/default/studio，文件格式如下：

  JACKTRIP_STUDIO_ID=***  # 替换***为实际值
  JACKTRIP_STUDIO_TOKEN=***  # 替换***为实际值
  

所需权限和限制

系统资源限制

需配置以下系统资源限制（通过 ulimit 设置）：

# 锁定 384MB 共享内存（单位：字节）
ulimit -l 384000000
# 允许实时优先级进程（最高优先级 95）
ulimit -r 95

容器权限

• Podman：无需额外权限标记
• Docker：需添加 --privileged 标记以特权模式运行，并配置实时调度参数：

  --cpu-rt-runtime=950000 --ulimit rtprio=95 --cap-add=sys_nice
  

部署与配置

使用 Podman 运行容器

方式 1：命令行传入环境变量

podman run --name studio \
  -e JACKTRIP_STUDIO_ID=*** \  # 替换***为实际值
  -e JACKTRIP_STUDIO_TOKEN=*** \  # 替换***为实际值
  --network=host \
  --shm-size=384M \
  -d jacktrip/studio

方式 2：挂载环境配置文件

podman run --name studio \
  -v /本地路径/环境文件:/etc/default/studio \  # 替换为实际环境文件路径
  --network=host \
  --shm-size=384M \
  -d jacktrip/studio

使用 Docker 运行容器

标准 Docker 环境

需添加实时调度和权限参数：

docker run --name studio \
  -v /本地路径/环境文件:/etc/default/studio \  # 替换为实际环境文件路径
  --network=host \
  --shm-size=384M \
  --privileged \
  --cpu-rt-runtime=950000 \
  --ulimit rtprio=95 \
  --cap-add=sys_nice \
  -d jacktrip/studio

Docker Desktop（Mac/Windows）用户

因 host 网络限制，需手动映射端口：

docker run --name studio \
  -v /本地路径/环境文件:/etc/default/studio \  # 替换为实际环境文件路径
  -p 443:443/tcp \
  -p 22124:22124/tcp \
  -p 4464:4464/tcp \
  -p 7881:7881/tcp \
  -p 3478:3478 \
  -p 50000-50999:50000-50999/udp \
  -p 61000-62000:61000-62000/udp \  # 原文此处端口范围可能有误，按原文保留 61000-62000
  --shm-size=384M \
  --privileged \
  --cpu-rt-runtime=950000 \
  --ulimit rtprio=95 \
  --cap-add=sys_nice \
  -d jacktrip/studio

容器管理

检查容器状态

# Podman
podman ps | grep studio

# Docker
docker ps | grep studio

预期输出示例：

CONTAINER ID  IMAGE                             COMMAND     CREATED        STATUS            PORTS       NAMES
2aba06b93354  docker.io/jacktrip/studio:latest  /sbin/init  3 seconds ago  Up 4 seconds ago              studio

进入容器内部

# Podman
podman exec -it studio bash

# Docker
docker exec -it studio bash

查看日志

容器内使用 journalctl 查看进程日志：

journalctl -f  # 实时查看日志

停止并删除容器

# Podman
podman rm -f studio

# Docker
docker rm -f studio