Oryx完整文档 - 技术栈

Oryx 概述与入门

本文档整理自 Oryx（ossrs/oryx）官方文档与社区资料，便于本地查阅与二次整理。

概述

Oryx（原 SRS Stack）是一款一体化、开箱即用的开源视频解决方案，专为构建具备直播和 WebRTC 功能的在线视频服务而设计。Oryx 专为云部署或自托管环境构建，将多种强大技术整合到统一平台中，简化了视频流基础设施的搭建与管理。

架构概览

Oryx 在 Docker 容器内采用微服务架构模式，集成了多个协同工作的关键组件，以提供完整的视频流解决方案：

核心技术

Oryx 基于成熟的开源技术构建，每个技术在视频流管道中承担特定角色：

组件	技术	主要角色	核心特性
媒体服务器	SRS 5.0	实时媒体处理	RTMP、WebRTC、HLS、HTTP-FLV、SRT 支持
后端 API	Go	服务编排	HTTP APIs、认证、流管理
前端 UI	React.js	管理界面	实时仪表板、配置、监控
数据存储	Redis	会话与元数据	流状态、用户会话、缓存
媒体处理	FFmpeg	转码与转换	格式转换、质量自适应
AI 集成	OpenAI API	智能功能	转录、配音、OCR、辅助

项目结构

代码仓库按功能目录组织，每个目录包含 Oryx 生态系统的特定组件：

复制代码

oryx/
├── platform/           # 核心 Go 后端服务
├── ui/                 # React.js 前端应用
├── scripts/            # 部署和安装脚本
├── test/               # 集成和 API 测试
├── mgmt/               # 管理工具
└── usr/                # 用户配置文件

platform 目录包含核心 Go 后端服务，负责流管理、API 端点和底层媒体服务器集成。ui 目录包含 React.js 前端，提供基于 Web 的管理界面。scripts 目录包含针对不同平台和云提供商的各种部署自动化工具。

核心功能

Oryx 为视频流场景提供全面的功能集：

流媒体协议

RTMP: 专业级推流与播放
WebRTC: 超低延迟实时通信（200-500ms）
HLS: 自适应码率流，广泛兼容各类设备
HTTP-FLV: 基于 HTTP 的低延迟流
SRT: 不可靠网络上的高质量可靠传输

高级能力

多平台转发: 同时推流至 YouTube、Twitch、Facebook
直播录制（DVR）: 本地磁盘或云存储录制
流转码: 使用 FFmpeg 实现实时质量自适应
虚拟直播: 将文件转换为直播流
AI 驱动功能: 转录、配音、OCR 和 AI 辅助

管理与安全

Web 管理界面: 直观的 React.js 仪表板
认证: 安全访问控制和 API 保护
自动 HTTPS: Let's Encrypt 证书管理
RESTful APIs: 完整的 HTTP OpenAPI 用于自动化

部署选项

Oryx 专为灵活的部署场景设计：

Docker 部署

主要部署方式使用包含所有组件的单一 Docker 容器：

bash 复制代码

docker run --restart always -d -it --name oryx -v $HOME/data:/data \
  -p 80:2022 -p 443:2443 -p 1935:1935 -p 8000:8000/udp -p 10080:10080/udp \
  ossrs/oryx:5

平台支持

云平台: DigitalOcean、AWS Lightsail、腾讯云轻量应用服务器
控制面板: aaPanel、宝塔面板集成
操作系统: Ubuntu Linux 搭配自动化安装脚本

数据管理

Oryx 采用结构化数据目录方式进行持久化存储：

目录	用途	内容
`/data/config`	配置	环境文件、SSL 证书
`/data/dvr`	录制	直播录制文件（MP4）
`/data/redis`	数据库	Redis 持久化文件
`/data/upload`	用户内容	上传的媒体文件
`/data/vlive`	虚拟直播	虚拟直播源文件
`/data/transcript`	AI 结果	转录和 AI 处理输出

快速入门

开始使用 Oryx 时，建议按以下路径推进：先用 Docker 部署第一个实例，再通过 Docker 部署指南熟悉容器与数据持久化，然后了解端口配置与网络、数据卷管理。下面从一次完整上手指南说起。

Oryx 是一站式、开箱即用的视频流方案，支持直播、WebRTC 与多种流媒体协议，几分钟内即可跑起来。

系统要求

在开始之前，请确保你的系统满足以下要求：

已安装并运行 Docker
至少 2GB 可用内存
10GB+ 可用磁盘空间用于数据存储
可访问网络以下载 Docker 镜像

Docker 快速部署

最快的启动方式是使用 Docker。Oryx 提供了一个预构建的容器镜像，包含所有必要的组件。

基础部署

使用单个 Docker 命令运行 Oryx：

bash 复制代码

docker run --restart always -d -it --name oryx -v $HOME/data:/data \
  -p 80:2022 -p 443:2443 -p 1935:1935 -p 8000:8000/udp -p 10080:10080/udp \
  ossrs/oryx:5

始终挂载 /data 卷以防止容器重启时数据丢失。你的流媒体录制、配置和其他重要数据都存储在这里。

端口配置

Oryx 使用以下关键端口：

端口	协议	用途
443/tcp	HTTPS	安全 Web 界面
1935/tcp	RTMP	RTMP 推流和播放
8000/udp	WebRTC	WebRTC 媒体传输
10080/udp	SRT	SRT 协议流媒体

访问 Oryx

部署完成后，通过 Web 浏览器访问 Oryx：

本地访问: http://localhost (或 http://127.0.0.1)
远程访问: http://your-server-ip

对于 WebRTC 功能，避免使用 localhost 或 127.0.0.1。请改用你的实际 IP 地址或域名。

架构概述

Oryx 采用微服务架构，集成了多个组件：外部服务、Oryx 容器、React 前端、Go 后端平台、SRS 媒体服务器、Redis 数据库、FFmpeg 转码器、Web 浏览器、RTMP/流媒体来源、CDN/平台。

数据卷结构

挂载的 /data 目录包含所有持久化数据：

复制代码

/data/
├── .well-known/
├── config/          # 配置文件和 SSL 证书
├── dvr/            # 直播录制文件
├── record/         # 其他录制文件
├── redis/          # Redis 数据库文件
├── upload/         # 上传文件
├── vlive/          # 虚拟直播文件
└── transcript/     # AI 转录结果

环境配置

使用环境变量自定义你的 Oryx 部署：

变量	默认值	描述
REACT_APP_LOCALE	en	UI 语言 (en 或 zh)

自定义设置示例：

bash 复制代码

docker run --restart always -d -it --name oryx -v $HOME/data:/data \
  -p 80:2022 -p 443:2443 -p 1935:1935 -p 8000:8000/udp -p 10080:10080/udp \
  -e MGMT_PASSWORD=your-secure-password \
  -e REACT_APP_LOCALE=en \
  ossrs/oryx:5

区域部署

对于中国用户，使用加速镜像仓库：

bash 复制代码

docker run --restart always -d -it --name oryx -v $HOME/data:/data \
  -p 80:2022 -p 443:2443 -p 1935:1935 -p 8000:8000/udp -p 10080:10080/udp \
  registry.cn-hangzhou.aliyuncs.com/ossrs/oryx:5

首次使用步骤

Oryx 运行后：

访问 Web 界面：打开浏览器并导航到你的 Oryx URL
设置认证：如果未通过环境变量设置，请配置管理员密码
测试流媒体：使用内置的流媒体工具测试 RTMP 或 WebRTC 推流
探索功能：浏览可用的流媒体协议和 AI 驱动的功能

验证命令

检查 Oryx 部署状态：

bash 复制代码

# 检查容器状态
docker ps | grep oryx

# 查看日志
docker logs oryx

# 访问容器 shell
docker exec -it oryx bash

# 检查 SRS 服务器状态
docker exec oryx curl http://localhost:2022/api/v1/summaries

后续步骤

完成快速入门后，探索这些高级主题：

Docker 部署指南 - 高级 Docker 配置
端口配置和网络 - 网络优化
数据卷管理 - 数据持久化策略
架构概述 - 深入了解系统架构

故障排除

常见问题：

端口冲突：确保端口 80、443、1935、8000 和 10080 可用
权限被拒绝：检查 Docker 权限和数据目录访问权限
WebRTC 不工作：验证你使用的是真实 IP 地址，而不是 localhost
内存使用过高：监控资源使用情况，必要时调整容器限制

如需更多支持，请访问 SRS 社区或查看 FAQ 文档。

Docker 部署指南

本指南提供了使用 Docker 容器部署 Oryx 的全面说明。Oryx 是一款一体化视频流解决方案，将多个服务组合成一个易于部署的软件包。

快速开始

使用单个 Docker 命令部署 Oryx：

bash 复制代码

docker run --restart always -d -it --name oryx -v $HOME/data:/data \
  -p 80:2022 -p 443:2443 -p 1935:1935 -p 8000:8000/udp -p 10080:10080/udp \
  ossrs/oryx:5

务必挂载 /data 卷以避免容器重启时数据丢失。所有配置、录制文件和持久化数据都存储在此卷中。

对于中国用户，请使用加速镜像仓库：

bash 复制代码

docker run --restart always -d -it --name oryx -v $HOME/data:/data \
  -p 80:2022 -p 443:2443 -p 1935:1935 -p 8000:8000/udp -p 10080:10080/udp \
  registry.cn-hangzhou.aliyuncs.com/ossrs/oryx:5

Docker 架构概览

Oryx 使用多阶段 Docker 构建流程，创建一个全面的流媒体平台：多阶段构建、Node.js 18 运行时、SRS 5 媒体服务器、Ubuntu 20 构建基础、Python 3.9 for youtube-dl、Ubuntu Focal 运行时、UI 构建工具、FFmpeg 集成、平台编译、媒体下载工具、最终 Oryx 镜像、运行时服务、平台服务、SRS 媒体服务器、Redis 数据库、Nginx Web 服务器。

端口配置

Oryx 为不同协议和服务暴露多个端口：

端口	协议	用途	默认容器端口
80/2022	HTTP	Web 界面和 API	2022
443/2443	HTTPS	安全 Web 界面	2443
1935	TCP	RTMP 流媒体	1935
8000	UDP	WebRTC 媒体传输	8000
10080	UDP	SRT 协议流媒体	10080

Dockerfile 会自动暴露这些端口。

bash 复制代码

EXPOSE 2022 2443 1935 8080 5060 9000 8000/udp 10080/udp

数据卷管理

/data 卷对持久化存储至关重要。它包含：

复制代码

/data/
├── .well-known/
├── config/               # 配置文件和 SSL 证书
├── dvr/                  # DVR 录制存储
├── lego/                 # LEGO ACME 质询目录
├── record/               # 流录制文件
├── redis/                # Redis 数据库文件
├── signals/              # 服务协调信号文件
├── upload/               # 用户上传文件
├── vlive/                # 虚拟直播流文件
├── transcript/           # AI 转录文件
├── nginx-cache/          # Nginx 缓存文件
└── srs-s3-bucket/        # S3 兼容存储挂载点

平台引导脚本会创建数据目录并设置符号链接。

bash 复制代码

# 准备数据目录
RUN mkdir -p /data && \
    cd /usr/local/oryx/platform/containers && \
    rm -rf data && ln -sf /data .

环境变量

使用环境变量配置 Oryx 行为：

变量	默认值	描述
MGMT_PASSWORD	-	管理界面密码
REACT_APP_LOCALE	en	UI 语言（en 或 zh）
CANDIDATE	-	用于 NAT 穿透的 WebRTC ICE candidate
AUTO_SELF_SIGNED_CERTIFICATE	on	自动生成 SSL 证书

基础 Docker 镜像设置了默认环境变量。

bash 复制代码

ENV PORT=":2024" NODE_ENV=production CLOUD=DOCKER PLATFORM_DOCKER=on

容器启动过程

当 Oryx 容器启动时，它遵循以下顺序：容器启动 → 执行引导脚本 → 启动 Redis 服务 → 启动 SRS 媒体服务器 → 启动平台服务 → 监控服务健康状态 → 服务正在运行则准备接受连接，否则停止所有服务并错误退出。

引导脚本协调服务启动：

bash 复制代码

# 启动 redis
bash auto/start_redis
# 启动 SRS
bash auto/start_srs
# 启动平台
./platform $APP_ARGS &

构建自定义镜像

对于自定义部署，构建你自己的 Oryx 镜像：

bash 复制代码

# 构建 Docker 镜像
docker build -t my-oryx:latest -f Dockerfile .

# 使用自定义配置运行
docker run --restart always -d -it --name oryx \
  -v $HOME/data:/data \
  -p 80:2022 -p 443:2443 -p 1935:1935 \
  -p 8000:8000/udp -p 10080:10080/udp \
  -e MGMT_PASSWORD=your-secure-password \
  my-oryx:latest

构建过程包含多个优化阶段：Node.js 阶段（准备 UI 构建工具）、SRS 阶段（集成媒体服务器组件）、构建阶段（编译平台和 UI）、压缩阶段（使用 UPX 减小二进制文件大小）、运行时阶段（创建最终部署镜像）。

生产环境部署

对于生产环境，使用管理引导脚本：

bash 复制代码

# 使用内置的管理脚本
./mgmt/bootstrap

此脚本提供额外功能：故障时自动重启容器、日志轮转管理、优雅关机的信号处理、Nginx 配置重新加载。

对于 WebRTC WHIP 功能，避免使用 localhost 或 127.0.0.1。请使用私有 IP、公网 IP 或配置了 HTTPS 的域名。

故障排除

常见问题

容器启动失败：检查数据卷权限
WebRTC 不工作：验证 CANDIDATE 环境变量
HTTPS 证书问题：确保域名配置正确
端口冲突：检查端口是否已被占用

容器日志

监控容器日志以进行调试：

bash 复制代码

# 查看实时日志
docker logs -f oryx

# 检查最近日志
docker logs --tail 100 oryx

后续步骤

成功部署 Docker 后，探索以下主题：端口配置与网络（了解高级网络设置）、数据卷管理（了解持久化存储策略）、架构概览（了解系统组件）。对于开发场景，请参考开发者指南获取本地开发和调试说明。

端口配置与网络

Oryx 需要仔细的网络配置来同时处理多种流媒体协议和服务。本指南涵盖了不同流媒体场景所需的基本端口配置，并为常见网络问题提供故障排除指导。

网络架构概述

Oryx 使用多端口架构来支持各种流媒体协议和 Web 服务。理解此架构对于正确部署和防火墙配置至关重要。

基本端口配置

核心服务端口

端口	协议	用途	必需
80	HTTP	Web UI 访问、API 端点	是
443	HTTPS	安全 Web 访问	可选
1935	RTMP	RTMP 推流/播放	是
8080	HTTP	HTTP-FLV 和 HLS 流媒体	是
8000	HTTP/WebSocket	WebRTC 信令	可选
2022	HTTP	管理 API	可选
6379	TCP	Redis 连接	是

Docker 端口映射

使用 Docker 部署 Oryx 时，请确保在 Docker 配置中进行正确的端口映射：

bash 复制代码

ports:
  - "80:80"        # HTTP Web 界面
  - "443:443"      # HTTPS（如果使用 SSL）
  - "1935:1935"    # RTMP 协议
  - "8080:8080"    # HTTP-FLV 和 HLS
  - "8000:8000"    # WebRTC 信令
  - "2022:2022"    # 管理 API

协议特定网络配置

RTMP 配置

RTMP（实时消息传输协议）默认运行在端口 1935。该端口处理来自编码器的入站推流和向客户端的出站播放。确保防火墙中的端口 1935 对 TCP 入站和出站流量都开放，以支持完整的 RTMP 功能。

基于 HTTP 的流媒体

HTTP-FLV 和 HLS 流媒体共享端口 8080，通过标准 HTTP 连接提供低延迟流媒体。此方法使用标准 Web 协议，简化了防火墙配置。

WebRTC 网络

WebRTC 需要额外的网络考虑：端口 8000 用于信令服务器通信；动态 UDP 端口用于媒体传输（通常是 10000-20000）；STUN/TURN 服务器配置用于 NAT 穿透。

防火墙配置

必需的防火墙规则

对于使用 ufw 的 Linux 系统：

bash 复制代码

# 允许 HTTP/HTTPS
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

# 允许 RTMP
sudo ufw allow 1935/tcp

# 允许 HTTP-FLV/HLS
sudo ufw allow 8080/tcp

# 允许 WebRTC 信令
sudo ufw allow 8000/tcp

# 允许 Redis（如果需要外部访问）
sudo ufw allow 6379/tcp

云安全组

在云平台上部署时，配置安全组以允许所需端口的流量。确保入站和出站规则都正确设置。

网络故障排除

常见问题和解决方案

问题	原因	解决方案
无法访问 Web UI	端口 80 被阻止	在防火墙中开放端口 80
RTMP 推流失败	端口 1935 被阻止	开放端口 1935，检查编码器设置
HLS 播放不工作	端口 8080 被阻止	开放端口 8080，验证 CORS 设置
WebRTC 连接失败	UDP 端口被阻止	开放 UDP 范围 10000-20000

网络测试命令

bash 复制代码

# 测试端口连通性
telnet your-server-ip 80
telnet your-server-ip 1935
telnet your-server-ip 8080

# 检查监听端口
netstat -tlnp | grep -E ':(80|443|1935|8080|8000|2022)'

# 测试 RTMP 连接
ffmpeg -f lavfi -i testsrc -f flv rtmp://your-server-ip/live/test

高级网络场景

反向代理配置

对于生产环境部署，考虑使用 Nginx 作为反向代理：

bash 复制代码

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:80;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    location /live/ {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
    }
}

SSL/TLS 配置

要支持 HTTPS，请配置 SSL 证书并更新端口绑定。该平台支持自签名和 CA 签名证书。

容器网络

使用 Docker 容器时，Oryx 会创建隔离的网络环境。平台自动处理像 Redis 和 SRS 这类服务的容器间通信。使用 Docker 网络或 Docker Compose 进行多容器部署，以确保正确的服务发现和通信。

下一步

配置网络设置后，继续阅读数据卷管理以了解 Oryx 如何处理持久化数据存储和备份策略。有关底层架构的更深入技术细节，请探索架构概述以了解这些网络组件如何与整体系统设计集成。

数据卷管理

数据量管理是 Oryx 流媒体平台的关键组成部分，它为配置文件、媒体录制和系统数据提供持久化存储。本指南介绍 Oryx 如何通过 Docker 卷处理数据持久化，以及不同类型数据使用的目录结构。

容器数据架构

Oryx 平台采用结构化的数据管理方法，将不同类型的数据组织到容器 /data 挂载点内的特定目录中。这种设计确保了数据在容器重启和系统更新后的持久性。

核心数据目录

配置数据 (/data/config/)

配置目录存储定义平台运行方式的基本系统配置文件：.env（包含数据库凭据、API 密钥和系统设置的环境变量）、nginx.conf（用于 HTTP/HTTPS 服务和反向代理的 Web 服务器配置）、redis.conf（用于缓存和会话管理的 Redis 数据库配置）、srs.release.conf（用于流媒体协议的 SRS 媒体服务器配置）。.env 文件尤为重要，因为它包含敏感信息，如数据库密码和 API 令牌。在系统初始化期间，平台会自动创建和管理此文件。

数据库存储 (/data/redis/)

Redis 数据持久化确保应用状态、用户会话和缓存数据在容器重启后仍然存在。平台使用 Redis 作为其主要数据存储：流状态和元数据、录制和 DVR 任务信息、云存储配置、用户认证令牌。

媒体录制存储

本地录制 (/data/record/)：本地磁盘录制存储为本地 DVR 配置的流的 HLS 段和元数据：HLS 段（来自直播流的 .ts 视频块）、M3U8 播放列表（HLS 播放的清单文件）、录制元数据（包含流信息和录制状态的 JSON 对象）。

云 DVR (/data/dvr/)：云 DVR 存储管理 destined for 云存储平台（如腾讯 COS）的录制：临时存储（上传到云之前的本地缓存）、上传队列（待上传和重试信息）、元数据（云存储凭据和文件映射）。

用户内容目录

上传存储 (/data/upload/)：用户上传的媒体文件存储于此，用于处理和流媒体传输：视频文件（MP4、FLV、TS、MKV、MOV 格式）、音频文件（MP3、AAC、M4A 格式）、处理队列（等待转码或分析的文件）。

虚拟直播内容 (/data/vlive/)：虚拟直播流资产包括：源媒体（用于虚拟流的视频文件）、流配置（虚拟频道的 JSON 定义）、输出缓存（处理后的流段）。

AI 驱动的功能存储

AI Talk (/data/ai-talk/)：用于 AI 驱动的直播间辅助和聊天功能的数据。

配音 (/data/dubbing/)：AI 配音项目和处理的音频文件：源音频（原始语言音轨）、配音输出（生成的翻译）、项目元数据（语言对和处理状态）。

OCR 处理 (/data/ocr/)：来自视频流的光学字符识别数据：帧提取（用于文本识别的截图）、OCR 结果（提取的文本和时间戳）、处理缓存（中间分析数据）。

数据持久化机制

Redis 哈希存储

平台使用 Redis 哈希集来维护结构化数据关系：

bash 复制代码

// 录制元数据存储模式
SRS_RECORD_M3U8_WORKING  = "SRS_RECORD_M3U8_WORKING"  // 活动录制
SRS_RECORD_M3U8_ARTIFACT = "SRS_RECORD_M3U8_ARTIFACT" // 已完成录制
SRS_DVR_M3U8_WORKING    = "SRS_DVR_M3U8_WORKING"     // 云 DVR 活动中
SRS_DVR_M3U8_ARTIFACT   = "SRS_DVR_M3U8_ARTIFACT"    // 云 DVR 已完成

文件系统操作

平台执行原子文件操作以确保数据完整性：JSON 序列化（配置和元数据以 JSON 格式存储）、锁机制（互斥锁防止并发访问问题）、清理例程（自动删除过期数据和临时文件）。

卷挂载配置

Docker Compose 设置

部署 Oryx 时，确保正确的卷挂载：

bash 复制代码

services:
  oryx:
    volumes:
      - ./data:/data
      - ./containers/data:/data

目录权限

平台要求数据目录具有特定权限：写访问权限（平台需要对所有数据子目录具有写权限）、用户映射（容器用户应与主机目录所有权匹配）、备份考虑（确保备份进程可以访问挂载的卷）。

数据生命周期管理

自动清理

平台实施自动清理机制：过期录制（根据保留策略删除旧录制数据）、临时文件（清理处理缓存和临时上传）、日志轮转（管理日志文件以防止磁盘空间耗尽）。

备份策略

对于生产部署，实施定期备份：配置文件（/data/config/ 目录）、数据库（来自 /data/redis/ 的 Redis 数据转储）、用户内容（/data/upload/ 和 /data/vlive/）、录制（/data/record/ 和 /data/dvr/）。

下一步

理解数据量管理对系统管理至关重要。继续学习：架构概述（数据管理如何融入整体系统设计）、Redis 数据管理（深入了解 Redis 配置和优化）、直播录制 (DVR)（录制配置详细指南）、云存储集成 (S3)（设置录制云存储）。适当的数据量管理可确保你的 Oryx 部署保持数据完整性，支持备份和恢复操作，并为流媒体应用程序提供可靠服务。

架构概览（深入）

Oryx 流媒体平台是一个基于微服务架构构建的综合性云原生解决方案，结合了实时媒体处理与 AI 驱动的功能。本概述面向希望了解平台设计原则的中级开发者，介绍系统的架构模式、组件关系和数据流。

系统架构

该平台采用分层微服务架构，在前端展示、后端服务和媒体基础设施三个主要层之间实现清晰的职责分离。这种设计确保了可扩展性、可维护性和功能模块化。数据层、媒体基础设施、后端服务、前端层；HTTP/REST、HTTP 回调、数据操作、AI 服务、云存储、RTMP/WebRTC/HLS、钩子；React 前端、平台服务 - Go、SRS 媒体服务器、Redis 缓存、OpenAI、COS/VOD、客户端、云存储。

核心组件

平台服务（Go 后端）

平台服务作为中央编排层，采用 Go 实现以获得高性能和并发能力。主入口点是 platform/main.go，通过结构化启动序列初始化系统：配置加载（基于环境的配置，支持 .env 文件）、服务发现（自动检测和初始化依赖项）、目录结构（为容器、DVR 和 AI 功能创建必要的数据目录）、HTTP 服务器（具有管理和 API 端点的多端口服务架构）。服务架构遵循 HTTP 处理器模式，具有广泛的路由管理：管理 API（/terraform/v1/mgmt/）系统配置、监控和控制；钩子 API（/terraform/v1/hooks/）SRS 媒体服务器回调处理；服务 API（/terraform/v1/）核心流媒体和 AI 功能。

React 前端架构

React 前端提供了一个响应式的多语言界面，采用现代 Web 技术构建：基于组件的架构（模块化 React 组件，具有错误边界）、路由系统（React Router 用于 SPA 导航，支持本地化）、状态管理（Context API 用于全局状态和环境配置）、认证流程（基于令牌的认证，具有会话管理）。前端遵循渐进式加载模式：环境检测和初始化、认证状态验证、基于用户权限的动态路由渲染。

SRS 媒体服务器集成

**SRS（Simple Realtime Server）**集成通过 HTTP 回调处理，实现事件驱动的媒体处理：流生命周期事件（on_publish、on_unpublish、on_hls）、录制事件（on_record_begin、on_record_end）、AI 处理事件（on_ocr 用于视频内容分析）、认证（可配置的流验证和授权）。回调机制确保了媒体服务器与应用程序逻辑之间的松耦合，同时保持实时响应性。

数据流模式

流媒体管道 / 回调处理

该平台实现了异步回调工作者模式，高效处理 SRS 事件：基于队列的处理（使用工作池的非阻塞事件处理）、重试机制（具有指数退避的弹性回调传递）、事件路由（智能消息分发到适当的处理器）。

AI 集成架构

AI 功能作为模块化扩展构建，与流媒体管道无缝集成：OpenAI 集成（用于聊天和内容分析的自然语言处理）、视频转录（语音转文本转换，提高可访问性）、AI 配音（自动翻译和语音合成）、OCR 处理（从视频帧中提取文本）。

存储和持久化

该平台采用混合存储策略：Redis（用于会话数据、流元数据和实时状态的高速缓存）、本地文件系统（录制和处理工件的临时存储）、云存储（与腾讯 COS/VOD 集成的长期归档）。

部署架构

该系统专为容器化部署而设计，支持 Docker：多阶段构建（生产环境的优化 Docker 镜像）、卷管理（通过 Docker 卷实现持久化数据存储）、服务编排（自动化启动和关闭序列）。

安全模型

安全通过深度防御原则实现：基于令牌的认证（JWT 令牌用于 API 访问）、HTTPS 强制（使用 Let's Encrypt 的自动 SSL 证书管理）、流认证（可配置的 RTMP/WebRTC 安全性）、API 速率限制（防止滥用和过载）。该架构强调事件驱动设计，SRS 回调触发异步处理，确保媒体服务器在复杂操作（AI 处理、转码、存储）在后台进行时保持响应。平台的模块化结构允许单个组件（AI 功能、存储后端、流媒体协议）独立开发、测试和部署，支持敏捷开发和便捷的功能实验。

下一步

要深入了解特定组件，请探索这些详细的架构指南：平台服务（Go 后端）、React 前端架构、SRS 媒体服务器集成、Redis 数据管理。有关实际实现指导，请转到快速开始设置开发环境并亲身体验架构的运作。

平台服务（Go 后端）

Platform Service 是 Oryx 流媒体平台的核心 Go 后端服务，负责协调所有流媒体操作、管理系统配置，并提供 RESTful API。该服务采用模块化架构构建，作为连接 SRS 媒体服务器、Redis 数据存储和各种 AI 功能的中央枢纽。

架构概览

平台服务采用分层架构，具有清晰的关注点分离。

核心组件

HTTP 服务层

HTTP 服务为平台提供主要的 API 接口。它实现了多服务器架构，为不同功能提供专用端点：主 HTTP 服务器（处理流媒体操作、配置管理和功能 API）、调试服务器（运行在 127.0.0.1:22022，用于开发和监控）、管理 API（提供系统管理功能）。该服务使用优雅关闭模式，结合上下文取消和超时处理，确保服务干净终止。

SRS Hook 集成

平台通过 HTTP 回调与 SRS 深度集成，处理流生命周期事件：on_publish（客户端开始推流时触发）、on_unpublish（流结束时触发）、on_hls（HLS 切片生成事件）、on_record_begin/end（录制生命周期事件）、on_ocr（视频内容分析触发）。这些 hook 实现实时流管理、自动录制和 AI 驱动的内容处理。

配置管理

平台使用集中式配置系统管理：云服务提供商设置（AWS、腾讯云和其他提供商配置）、网络配置（IP 发现、接口绑定和端口管理）、版本管理（自动版本检查和升级协调）、环境变量（通过 .env 文件和系统环境进行动态配置）。配置采用分层加载，环境变量优先于默认值。

功能模块

IP 摄像头流媒体

摄像头流媒体模块提供强大的 IP 摄像头集成：自动发现（支持各种 IP 摄像头协议和格式）、FFmpeg 集成（使用 FFmpeg 进行转码和流处理）、健康监控（持续流健康检查和自动恢复）、任务管理（后台工作器处理多个并发摄像头流）。

直播间管理

直播间提供 AI 辅助的交互式流媒体体验：房间生命周期（直播会话的创建、配置和清理）、AI 助手集成（OpenAI 驱动的聊天、ASR 和 TTS 功能）、舞台管理（动态控制房间参与者和功能）、实时交互（基于 WebSocket 的实时互动通信）。

后台工作器

平台使用多个专用工作器处理不同任务：摄像头工作器（管理 IP 摄像头流和健康监控）、虚拟流工作器（处理基于文件和 URL 的虚拟流）、转码工作器（管理 FFmpeg 转码操作）、AI 服务工作器（协调 OCR、转录和配音任务）。

数据管理

Redis 集成

Redis 作为中央数据存储，具有全面的密钥管理：流状态（活跃流、SRT 连接和 WebRTC 会话）、配置存储（系统设置、功能标志和用户偏好）、任务队列（后台作业管理和协调）、缓存层（为频繁访问的数据提供性能优化）。

文件系统组织

平台维护结构化的文件系统布局：/data（持久存储的主数据目录）、upload/（用户上传的媒体文件）、vlive/（虚拟直播资产）、dub/（AI 配音项目文件）。

安全与认证

平台实施全面的安全措施：JWT 令牌认证（使用签名令牌确保 API 访问安全）、流认证（可选的推流认证）、HTTPS 支持（TLS 证书管理与 Let's Encrypt 集成）、CORS 处理（正确的跨域资源共享配置）。

性能与监控

内置性能功能包括：Pprof 集成（用于性能分析的 Go 分析工具）、优雅关闭（带超时保护的干净服务终止）、健康检查（全面的系统和流健康监控）、日志记录（贯穿应用程序的结构化日志与上下文传播）。

后续步骤

要了解完整的系统架构，请探索以下相关组件：React 前端架构、SRS 媒体服务器集成、Redis 数据管理、HTTP OpenAPI 参考。

React 前端架构

Oryx 中的 React 前端架构为流媒体操作提供了全面的管理界面，采用现代 React 模式和强大的错误处理机制构建。该架构作为流媒体平台的主要用户交互层。

技术栈和依赖项

前端基于 React 17.0.2 构建，并精心选择了一系列提供流媒体管理核心功能的库生态系统：React 17.0.2、React Router DOM 6.2.1、React Bootstrap 2.1.1、React i18next 11.16.2、Axios 1.6.0（客户端路由、UI 组件、国际化、HTTP 客户端）；其他库包括 React Error Boundary、React QR Code、Recharts、Country Flag Icons。关键依赖包括用于响应式设计的 Bootstrap 5.1.3、用于组件集成的 React Bootstrap 2.1.1，以及用于 API 通信的 axios。应用还集成了专门用于二维码生成 (react-qr-code)、数据可视化 (recharts) 和国际化 (i18next) 的库。

应用结构和路由

应用遵循分层组件架构，采用集中式路由逻辑：App.js → SrsEnvContext Provider、错误边界、AppPreImpl（环境加载）、AppImpl（初始化检查）、AppRoute（BrowserRouter、路由定义）、设置路由、登录路由、认证路由、弹出路由。路由系统实现了基于状态的访问控制模式，根据初始化状态和认证状态条件渲染路由。应用通过 URL 前缀支持多语言环境，并自动重定向到用户首选语言。

状态管理架构

前端采用基于上下文的状态管理方法，为不同关注点提供专门的上下文：SrsEnvContext（来自后端 API 的全局环境配置）、认证状态（通过工具函数管理，使用 localStorage 持久化）、语言环境管理（集中式语言偏好处理）。状态管理模式确保可预测的数据流，UI 状态和业务逻辑之间清晰分离。

组件架构

核心组件

应用具有模块化组件结构，按功能组织：导航系统（根据认证状态自适应的动态导航）、错误处理（全面的错误边界实现，提供用户友好的错误消息）、场景管理（用于不同流媒体场景的选项卡界面）。

专用组件

前端包含用于流媒体操作的领域特定组件：AI 集成（用于 AI 驱动功能的组件，如配音、OCR 和转录）、流管理（用于直播、录制和转码场景的组件）、媒体播放器（集成各种流媒体协议 RTMP、HLS、WebRTC、SRT）。

国际化架构

应用使用 react-i18next 实现全面的 i18n 系统，支持动态语言切换，具有持久化用户偏好和基于 URL 的语言环境路由。

开发和构建配置

开发代理设置

前端包含精密的开发代理，在开发期间将 API 请求路由到后端服务器：/terraform/、/api/、/rtc/ 代理到 http://127.0.0.1:2022/。此配置实现无缝开发，支持热重载，同时保持适当的 API 集成。

构建和部署

应用支持多环境构建：英文构建 (npm run start-en)、中文构建 (npm run start-zh)、生产构建 (npm run build)。构建系统确保为生产部署提供优化包，具有适当的资源管理和代码分割。

错误处理和弹性

前端实现多层错误处理策略：全局错误边界（优雅地捕获和处理 React 组件错误）、API 错误处理（集中式错误处理，提供用户友好的消息）、网络错误恢复（针对临时故障的自动重试机制）。错误边界系统根据错误代码提供上下文相关的错误消息，对认证失败、Redis 连接问题和 HTTPS 配置问题进行专门处理。

安全考虑

前端实现了几项安全措施：基于令牌的认证（安全的 JWT 处理，具有自动刷新功能）、XSS 防护（内置 React 保护和输入清理）、CSRF 防护（适当的请求头和令牌验证）、安全存储（敏感数据在 localStorage 中加密）。

性能优化

架构包括几项性能优化：代码分割（基于路由的动态导入代码分割）、懒加载（按需加载组件）、记忆化（React.memo 和 useCallback 用于昂贵操作）、资源优化（压缩图像和优化包大小）。应用广泛使用 React 内置优化模式，包括事件处理器的 useCallback 和昂贵计算的 useMemo，即使在复杂的流媒体操作中也能确保流畅性能。

集成模式

前端遵循与后端服务一致的集成模式：RESTful API 通信（标准化的基于 axios 的 HTTP 客户端）、实时更新（WebSocket 集成用于实时状态更新）、流媒体协议支持（多协议流媒体集成）、文件上传处理（媒体上传的进度跟踪和错误恢复）。该架构为流媒体管理提供了可扩展的基础，同时保持出色的用户体验和开发人员生产力。

SRS 媒体服务器集成

SRS（Simple Realtime Server）媒体服务器集成构成了 Oryx 的核心流基础设施，为实时媒体处理和分发提供了坚实的基础。该集成利用了 SRS 强大的流媒体处理能力，同时通过复杂的回调机制和状态管理，与 Oryx 平台保持无缝协调。

架构概述

该集成遵循分布式架构模式，其中 SRS 作为独立的媒体服务器运行，而 Oryx 提供管理层、认证层和编排层。这些组件之间的通信通过 HTTP 回调和基于 Redis 的状态同步进行。

核心集成组件

Hook 处理器系统

hook 处理器作为 SRS 与 Oryx 之间的主要接口，通过 HTTP 回调处理所有流媒体事件。该系统位于 platform/srs-hooks.go，处理多种事件类型：发布事件（流认证和注册）、停止发布事件（流清理和资源释放）、HLS 事件（分片生成和清单更新）、录制事件（DVR 功能触发）、OCR 事件（视频内容分析启动）。处理器实现了灵活的认证机制，支持房间特定和全局发布密钥。这种双层安全方法允许细粒度访问控制，同时保持系统级安全策略。

流状态管理

流状态通过基于 Redis 的数据结构进行维护，提供对活动流的实时可见性：SRS_STREAM_ACTIVE（所有活动流）、SRS_STREAM_SRT_ACTIVE（SRT 协议流）、SRS_STREAM_RTC_ACTIVE（WebRTC 流）、SRS_STAT_COUNTER（统计计数器）。每个流条目包含全面的元数据，包括流 URL、编解码器信息和时间戳。这实现了高效的流监控、管理和故障排除能力。

认证框架

认证系统支持多种验证方法：基于房间的认证（使用房间特定的发布密钥实现隔离环境）、全局认证（应用系统级发布密钥进行通用访问）、基于参数的认证（允许通过 URL 参数或流名称传递密钥）。这种灵活的方法适应各种编码器功能和部署场景，同时保持安全标准。

配置和部署

SRS 配置管理

SRS 配置通过位于 platform/containers/conf/ 的模板文件进行动态生成和管理。主要配置文件包括：srs.release.conf（生产环境配置）、srs.release-local.conf（本地开发设置）、srs.release-mac.conf（macOS 特定调整）。启动脚本 platform/auto/start_srs 编排 SRS 初始化，从 .srs.env 加载环境变量，并在启动媒体服务器之前确保正确的配置文件结构。

服务编排

平台服务通过自动化脚本管理 SRS 生命周期：启动脚本（使用正确的配置和环境初始化 SRS）、停止脚本（优雅终止 SRS 进程）、健康监控（持续检查 SRS 进程状态）。这种编排确保高可用性和服务中断的自动恢复。

回调处理流程

回调系统通过结构化工作流处理流媒体事件。此流程确保所有流媒体事件都根据配置的业务规则进行适当的认证、记录和处理。

错误处理和监控

错误代码系统

该集成实现了在 platform/srs-errors.go 中定义的全面错误代码系统，提供标准化错误报告：回调错误（100-200）录制和回调相关故障、认证错误（访问控制和验证失败）、系统错误（基础设施和资源问题）。

监控能力

实时监控通过以下方式实现：流计数器（跟踪发布/播放统计）、进程监控（确保 SRS 服务可用性）、回调日志（记录所有 HTTP 回调交互）、性能指标（监控资源利用率和响应时间）。

集成优势

SRS 媒体服务器集成提供了几个关键优势：可扩展性（分布式架构支持水平扩展）、可靠性（强大的错误处理和恢复机制）、灵活性（支持多种流协议和认证方法）、可观测性（全面的监控和日志记录能力）、安全性（多层认证和访问控制）。此集成作为高级流功能的基础，包括 DVR、转码和 AI 驱动能力，使其成为 Oryx 流平台的重要组成部分。有关特定流协议的详细信息，请参阅 RTMP 发布和播放、WebRTC 实时通信和 HLS 和 HTTP-FLV 流。

Redis 数据管理

Oryx 平台利用 Redis 作为其核心数据持久化层，用于管理平台状态、配置和运行时信息。本文档深入探讨了全面的 Redis 数据管理架构，从初始化和生命周期管理到数据结构和操作模式。

Redis 基础架构

Redis 集成采用分层架构，将基础设施管理、服务初始化和数据访问模式分离。

Redis 服务器生命周期管理

平台通过专用的 Shell 脚本提供自动化的 Redis 服务器生命周期管理，处理启动、配置和优雅关闭过程。

服务器启动配置

Redis 服务器初始化过程采用系统化方法，确保正确的配置和数据持久化。启动脚本 platform/auto/start_redis 使用可配置参数（包括身份验证、端口绑定和持久化数据存储）建立 Redis 服务器。服务器以守护进程模式运行，并通过 PID 跟踪进行进程管理。

优雅关闭过程

关闭机制通过受控的进程终止确保数据完整性。platform/auto/stop_redis 脚本实现了带超时保护的优雅关闭模式，防止服务终止期间的数据损坏。

Redis 客户端集成

平台利用 go-redis/v8 客户端库进行 Redis 连接，在整个应用程序中实现集中化客户端模式。客户端初始化在 platform/main.go 的平台启动期间进行，建立的服务连接供所有后续 Redis 操作跨不同服务模块使用。

数据管理模式

平台密钥管理

Redis 作为平台身份验证令牌和密钥的安全存储。platform/main.go 实现展示了基于 UUID 的令牌自动生成，确保无需手动干预即可安全访问 API。

启动状态跟踪

Redis 维护特定版本的启动状态，以启用一次性初始化任务。platform/main.go 中的此模式确保跨平台升级和部署的幂等初始化。Redis 数据管理策略采用基于环境的配置和合理的默认值，实现在不同环境中无缝部署，同时保持操作一致性。

服务集成架构

HTTP 服务 Redis 依赖

HTTP 服务层集成 Redis 用于会话管理、配置存储和运行时状态持久化。platform/service.go 中的服务初始化为所有 HTTP 端点建立 Redis 连接。

快速缓存实现

平台实现了专门的快速缓存层，利用 Redis 实现高性能数据访问。platform/fastcache.go 为优化的数据检索模式提供抽象层。

配置管理

环境变量集成

Redis 配置通过带有平台特定默认值的环境变量进行管理：REDIS_DATABASE、REDIS_HOST、REDIS_PORT。platform/main.go 实现确保跨部署场景的一致 Redis 连接。

多环境支持

平台支持管理和操作上下文的独立 Redis 配置：管理上下文（使用 MGMT_LISTEN 和相关配置进行管理操作）、平台上下文（利用 PLATFORM_LISTEN 提供面向用户的服务）。这种分离使不同服务层能够独立扩展和管理。

数据持久化策略

卷挂载

Redis 数据持久化通过专用卷挂载确保。platform/auto/start_redis 脚本配置持久化存储，在容器重启和系统故障期间保护数据。

配置持久化

Redis 配置文件维护在版本控制的位置：配置文件 containers/conf/redis.conf、环境文件 containers/data/config/.env。此方法支持配置版本控制和环境特定定制。

操作注意事项

高可用性模式

Redis 架构通过客户端分片和连接池支持水平扩展。go-redis 客户端库为集群配置和故障转移机制提供内置支持。

监控和可观测性

Redis 操作与平台的日志框架集成，为数据访问模式和性能指标提供全面的可观测性。

安全实现

Redis 安全通过多层强制执行：身份验证（通过 REDIS_PASSWORD 进行基于密码的访问控制）、网络隔离（默认 localhost 绑定，可配置暴露）、数据加密（TLS 支持安全通信通道）。Redis 集成遵循深度防御原则，在网络、身份验证和应用层实施安全控制，确保全面的数据保护。

性能优化

连接管理

平台通过以下方式实现高效的 Redis 连接模式：连接池（可重用连接以减少开销）、上下文感知操作（适当的超时和取消处理）、批量操作（支持多个 Redis 命令的管道）。

缓存策略

Redis 既作为主存储又作为缓存层，实现：直写缓存（关键数据的即时持久化）、直读缓存（数据访问时自动缓存填充）、TTL 管理（临时数据的可配置过期）。

集成点

服务依赖

多个平台服务依赖 Redis 实现核心功能：直播间（会话状态、流元数据，Hash/String）、AI 服务（模型缓存、处理结果，String/List）、转发（目标配置、状态，Hash/Set）、DVR 服务（录制元数据、文件跟踪，Hash/Sorted Set）。

API 集成

Redis 数据通过 RESTful API 暴露，提供：配置管理（平台设置的动态更新）、状态监控（实时系统和服务健康状况）、管理操作（用户管理和访问控制）。

后续步骤

要全面了解平台架构，请探索：平台服务 (Go 后端)、架构概述、HTTP OpenAPI 参考。Redis 数据管理系统为 Oryx 的状态管理提供基础，实现可扩展、可靠和高性能的流媒体服务。

RTMP 推流与播放

RTMP (Real-Time Messaging Protocol) 作为 Oryx 中的基础流媒体协议，能够实现低延迟的实时视频发布和播放。该协议构成了直播操作的骨干，支持直接 RTMP 流以及到其他格式的协议转换。

RTMP 架构概览

Oryx 中的 RTMP 实现采用分布式架构，平台服务通过 Redis 协调和 SRS 媒体服务器集成来管理流的生命周期。

流管理系统

活跃流注册表

Oryx 使用 Redis 哈希存储维护活跃 RTMP 流的实时注册表。系统通过 SRS_STREAM_ACTIVE 键跟踪流元数据，包括客户端 ID、URL 和流状态。每个流对象包含完整的元数据：Vhost（虚拟主机标识符）、App（应用名称，通常为 live）、Stream（流密钥/名称）、Client（用于连接管理的 SRS 客户端 ID）、URL（完整的 RTMP 流 URL）。

流查询 API

平台暴露用于流管理的 RESTful 端点：/terraform/v1/mgmt/streams/query (POST) 检索所有活跃流；/terraform/v1/mgmt/streams/kickoff (POST) 断开特定 RTMP 客户端连接。流查询 API 从 Redis 检索所有活跃流，并返回包含流元数据的结构化 JSON 数据。

流发布工作流

直接 RTMP 发布

发布者使用标准 RTMP URL 直接连接到 SRS：rtmp://oryx-server:1935/live/stream-key。发布工作流包括：客户端建立到 SRS 的 RTMP 连接（端口 1935）；SRS 通过平台回调在 Redis 中注册流；流变得可用于播放和转发。

摄像头流采集

对于 IP 摄像头集成，Oryx 使用 FFmpeg 将各种协议转换为 RTMP。摄像头流系统处理 RTSP、HTTP 和其他输入格式。系统支持为无音频的摄像头插入可选音频流，生成静音音频轨道以保持流兼容性。

流转发和分发

多平台转发

Oryx 使用 FFmpeg 实现 RTMP 流向多个平台的转发。转发任务使用流复制 (-c copy) 以保持原始质量，同时最小化 CPU 开销。这种方法保留了源流的确切编码参数。

协议支持矩阵

Input Protocol：RTMP/RTSP/HTTP/SRT；Output Support：RTMP/RTS/SRT；FFmpeg Parameters：-f flv for RTMP、-rtsp_transport tcp、Direct URL input、-f mpegts for SRT。

流控制和管理

客户端断开连接

平台通过 SRS 管理 API 提供对 RTMP 连接的细粒度控制。流断开功能在断开连接前验证客户端存在性。系统优雅地处理 ERROR_RTMP_CLIENT_NOT_FOUND 错误代码，允许安全清理断开连接的客户端。

播放集成

RTMP 播放 URL

播放器使用标准 RTMP URL 消费流：rtmp://oryx-server:1935/live/stream-key。平台通过 Redis 注册表维持流可用性，确保播放器接收准确的流状态信息。

低延迟优化

RTMP 配置通过以下方式优先考虑低延迟：缓冲最小化（-fflags nobuffer 参数减少缓冲延迟）、TCP 传输（保证 RTSP 源的可靠传输）、直接流复制（保留原始时序并减少处理开销）。

监控和诊断

流健康监控

平台通过 FFmpeg 心跳机制实现全面的流健康监控。每个流任务维护：进程 PID 跟踪、启动时间和首次就绪时间指标、逐帧日志记录用于调试、自动重启能力。流任务实现优雅关闭，在重启周期之间有 1 秒延迟，以防止快速重启循环并确保适当的资源清理。

后续步骤

要加深你对 Oryx 流媒体能力的理解：协议多样性（探索 WebRTC 实时通信用于超低延迟应用）、HTTP 流媒体（了解 HLS 和 HTTP-FLV 流媒体以获得更广泛的设备兼容性）、高级功能（发现直播录制 DVR 用于持久化存储选项）、系统架构（查看 SRS 媒体服务器集成以获得更深入的技术洞察）。Oryx 中的 RTMP 实现为直播操作提供了强大的基础，对各种输入源和分发目标具有广泛的灵活性，同时保持低延迟和高可靠性。

WebRTC 实时通信

WebRTC (Web Real-Time Communication) 支持在 Web 浏览器之间直接进行点对点的实时音频、视频和数据传输，无需中间服务器。在 Oryx 平台中，WebRTC 作为核心流媒体协议与 RTMP、HLS 和 HTTP-FLV 一同集成，为互动直播场景提供超低延迟通信。

WebRTC 架构概述

Oryx 平台通过复杂的多层架构实现 WebRTC，该架构利用 SRS (Simple Realtime Server) 作为媒体引擎，同时通过 Go 平台服务和 React 前端提供全面的管理功能。

核心组件

候选管理

平台通过 CandidateWorker 服务实现了复杂的 ICE (Interactive Connectivity Establishment) 候选管理。该组件处理网络拓扑发现并确保最佳的点对点连接：主机解析（通过 NAME_LOOKUP 环境变量可配置的智能主机名到 IP 解析行为）、本地主机处理（针对本地主机场景的特殊逻辑，区分 Docker 和主机环境）、IP 验证（直接 IP 地址解析和验证，以实现高效的候选处理）。

HTTP 服务集成

WebRTC 信令集成到主要的 HTTP 服务架构中，提供：CORS 支持（为 WebRTC 客户端启用跨域资源共享）、身份验证（信令端点的基于令牌的安全性）、多路复用路由（WebRTC 端点与其他 API 服务共存）。

直播间 WebRTC 集成

直播间系统通过 React 前端提供全面的 WebRTC 支持：流类型选择（用户可以选择 RTMP、SRT 和 WebRTC 发布协议）、URL 生成（动态生成带身份验证令牌的 WebRTC 发布和播放 URL）、实时配置（在不中断服务的情况下实时切换流媒体协议）。

WebRTC 流媒体协议

发布协议

Oryx 支持多种 WebRTC 发布方法：WHIP (WebRTC-HTTP Ingestion Protocol) 端口 8000/1935、标准 WebRTC 发布、延迟 < 100ms；WebRTC Direct 端口 8000、点对点发布、< 50ms；SRT over WebRTC 端口 10080、通过 WebRTC 实现可靠传输、< 200ms。

播放协议

WebRTC 播放选项包括：WebRTC 播放器（直接点对点播放，延迟低于 100ms）、WHIP 播放（基于 HTTP 的 WebRTC 播放，确保浏览器兼容性）、低延迟 HLS（针对不支持 WebRTC 的客户端的回退选项）。

实现细节

信令流程

WebRTC 信令过程遵循标准化流程：Offer/交换（客户端创建 SDP offer 并发送到信令服务器）、Answer 生成（服务器通过 SRS 处理 offer 并生成 answer）、ICE 候选交换（交换网络候选以进行点对点发现）、连接建立（建立直接的点对点连接）。

身份验证和安全

WebRTC 流继承 Oryx 平台的全面安全模型：流级身份验证（每个直播间都有唯一的发布密钥）、基于令牌的访问（用于 API 和信令访问的 JWT 令牌）、网络隔离（用于网络安全的 ICE 候选过滤）。

网络遍历

平台实现了强大的 NAT 遍历：STUN 服务器集成（自动公网 IP 发现）、TURN 服务器回退（针对受限网络环境的中继服务器）、ICE 候选优先级（连接质量的最佳路径选择）。

配置和管理

环境变量

关键的 WebRTC 配置选项：WEBRTC_ENABLED=on；STUN_SERVER、TURN_SERVER；NAME_LOOKUP=on、CANDIDATE=auto。

直播间 WebRTC 设置

通过 React 界面，用户可以：创建直播间、配置协议、生成 URL、监控质量。

性能优化

延迟降低：直接点对点连接、UDP 传输、自适应比特率。资源管理：连接池、内存优化、CPU 效率。

故障排除和监控

常见问题：ICE 连接失败、身份验证错误、网络限制。监控指标：连接质量、比特率统计、错误率。WebRTC 与 Oryx 生态系统中的其他流媒体协议无缝集成：协议桥接、统一身份验证、集中管理。Oryx 中的 WebRTC 实现提供了企业级实时通信功能，同时保持与现有流媒体基础设施的兼容性，使其成为互动直播、视频会议和超低延迟广播场景的理想选择。

HLS 与 HTTP-FLV 流媒体

HLS (HTTP Live Streaming) 和 HTTP-FLV 是自适应比特率流媒体协议，能够通过 HTTP 网络高效传输直播和点播视频内容。Oryx 为这两种协议提供全面支持，具备可配置的性能选项和 CDN 集成功能。

协议架构

流媒体架构采用多层方法，其中 SRS (Simple Realtime Server) 负责核心媒体处理，而 Oryx 管理配置和编排：RTMP 输入 → SRS 媒体服务器 → HLS 处理 / HTTP-FLV 处理 → TMP/TS 分片 / FLV 流 → Nginx CDN 缓存 → 客户端播放器；Oryx 平台、Redis 配置存储、HLS 设置、性能调优。

HLS 配置管理

Oryx 通过基于 Redis 的设置提供动态 HLS 配置，这些设置可以在不重启服务器的情况下更新。系统支持标准和低延迟 HLS 模式。标准 HLS 模式：分片时长 10 秒、窗口大小 60 秒、目标用例 VOD 播放与标准直播。低延迟 HLS 模式：分片时长 2 秒、窗口大小 16 秒、目标用例互动直播与低延迟场景。配置通过 platform/utils.go 中的 srsGenerateConfig 函数管理，该函数根据 Redis 设置动态构建 SRS 配置。

性能优化功能

高性能 HLS 设置

Oryx 包含可通过 noHlsCtx 设置切换的高级 HLS 性能优化：上下文感知处理（禁用时通过禁用 HLS 上下文跟踪减少 CPU 开销）、内存优化（配置音频溢出比例为 2.1）、清理管理（15 秒后自动清除分片）。

配置 API

系统暴露 RESTful API 用于动态 HLS 管理：/terraform/v1/mgmt/hphls/update (POST)、/terraform/v1/mgmt/hphls/query (POST)、/terraform/v1/mgmt/hlsll/update (POST)、/terraform/v1/mgmt/hlsll/query (POST)。这些 API 在 platform/service.go 中实现，需要通过令牌验证进行身份认证。

与 Nginx 的 CDN 集成

Oryx 为通过 CDN 边缘服务器传输 HLS 内容提供预配置的 Nginx 模板。配置包括：M3U8 播放列表缓存、TS 分片缓存、缓存锁机制（300 秒超时防止缓存击穿）、缓存验证（404 响应缓存 10 秒）。scripts/nginx-hls-cdn/nginx.edge.http.conf.template 中的 Nginx 模板展示了缓存策略。

HLS 钩子处理

SRS 在生成 HLS 分片时通过 on_hls 回调通知 Oryx。handleOnHls 函数处理这些事件并触发下游工作流。可用处理器：录制（启用 SRS_RECORD_PATTERNS 时存储分片用于 VOD）、DVR（通过 SRS_DVR_PATTERNS 集成云存储）、VOD 处理（通过 SRS_VOD_PATTERNS 进行视频点播转换）、转录（AI 驱动的语音转文本转换）、OCR（视频内容的光学字符识别）。每个处理器可通过 Redis 配置键独立配置和启用/禁用。

流 URL 构造

HLS 流可通过标准化 URL 模式访问：直播 HLS http://domain/live/stream.m3u8、HTTP-FLV http://domain/live/stream.flv。系统根据流配置自动生成这些 URL，并通过管理 API 提供访问。

配置持久化

所有 HLS 设置使用以下键持久化在 Redis 中：SRS_HP_HLS（高性能 HLS 配置）、SRS_LL_HLS（低延迟 HLS 设置）。这些设置在系统启动时自动加载，可通过管理 API 动态修改，无需重启服务。

与其他协议的集成

HLS 与 Oryx 中的其他流媒体协议协同工作：RTMP（直播流的主要推流协议）、WebRTC（超低延迟实时通信）、SRT（不可靠网络上的可靠传输）。通过 RTMP 发布的流会自动转换为 HLS 和 HTTP-FLV 以实现广泛的客户端兼容性。有关全面的流媒体设置，请参阅 RTMP 推流和播放和 WebRTC 实时通信。

SRT 协议支持

集成在 ORYX 中的 SRS (Simple Realtime Server) 媒体服务器提供了全面的 SRT (Secure Reliable Transport) 协议支持，能够在不可预测的网络中实现安全可靠的低延迟流传输。SRT 对于远程贡献和网络条件具有挑战性的场景尤其有价值。

SRT 服务器配置

SRT 服务器在 SRS 配置中默认启用，并针对广播质量的流传输进行了优化设置。关键配置参数：listen 10080（SRT 连接的 UDP 端口）、maxbw 1000000000（最大带宽 1 Gbps）、connect_timeout 4000ms、latency 20ms、tlpktdrop off、tsbpdmode off。

SRT 到 RTMP 集成

ORYX 支持从 SRT 到 RTMP 的无缝协议转换，允许 SRT 贡献流通过标准流协议进行分发。此集成支持：来自远程编码器或贡献源的 SRT 采集、到 RTMP 的自动协议转换用于下游分发、通过 ORYX 平台的统一流管理。

多协议转发支持

ORYX 中的转发系统支持 SRT 作为输出协议，能够分发到各种流媒体平台。平台支持通过管理 API 将流转发到 SRT 目标，具有自动协议检测和适当的 FFmpeg 参数配置：协议检测（自动识别 SRT URL）、格式优化（SRT 流使用 MPEG-TS 容器）、载荷配置（优化的数据包大小设置）。

流管理和监控

所有 SRT 流都通过统一的流管理系统进行管理，具有：通过 Redis 存储的活跃流跟踪、流状态和健康状况的实时监控、自动故障转移和恢复机制。系统维护全面的流元数据，包括协议信息，能够基于流特性实现复杂的路由和管理决策。

与直播间功能集成

SRT 流与直播间系统无缝集成，支持：SRT 贡献的安全认证、基于房间的流组织、SRT 流的 AI 驱动功能、来自 SRT 源的多平台分发。

用例和优势

远程贡献：在不可靠网络上的可靠传输、可配置延迟缓冲区的低延迟、安全内容交付的加密支持。广播工作流：具有丢包恢复功能的专业级质量、自适应码率的灵活带宽管理、贡献和分发之间的协议桥接。多平台分发：混合协议环境的统一管理、自动转码和协议转换、大规模流传输的可扩展架构。

后续步骤

为了获得全面的流协议覆盖，请探索：RTMP 推流和播放（用于传统流工作流）、WebRTC 实时通信（用于超低延迟应用）、HLS 和 HTTP-FLV 流传输（用于自适应码率传输）。ORYX 中的 SRT 协议支持为需要在具有挑战性的网络条件下实现可靠传输的专业流工作流提供了坚实的基础，同时与现有流基础设施保持无缝集成。

直播录制（DVR）

ORYX 中的直播录制 (DVR) 功能能够自动捕获和存储直播流，以供点播播放。该功能支持包括本地磁盘和云存储解决方案在内的多种存储后端，为各种部署场景提供灵活的录制选项。

架构概述

DVR 系统围绕三个主要存储后端构建，每个后端都作为平台服务中的独立 Go 模块实现。

存储后端

ORYX 实现了三种不同的 DVR 存储解决方案：本地磁盘 (dvr-local-disk.go)，用例本地部署，关键特性直接文件访问与低延迟；腾讯云对象存储 (dvr-tencent-cos.go)，用例云对象存储，可扩展存储与 CDN 集成；腾讯云点播 (dvr-tencent-vod.go)，用例专业媒体平台，高级处理与转码。本地磁盘实现提供简单的基于文件的录制，配置要求最少。COS 集成支持基于云的录制，具有自动同步和备份功能。VOD 后端提供专业级媒体存储，具有内置转码、内容保护和分发功能。

配置和管理

DVR 功能通过平台服务 API 进行管理，提供：录制配置设置、存储后端选择、录制计划管理、文件检索和播放。DVR 系统自动处理流检测，并在直播流开始时启动录制，确保即使是非计划直播也不会遗漏内容。

集成点

DVR 系统与 ORYX 的几个核心组件集成：SRS 媒体服务器、Redis 数据管理、平台服务、前端界面。

文件管理和播放

录制的文件使用基于时间戳的命名约定自动组织，并根据所选后端的结构进行存储。系统为每个录制维护元数据，包括流信息、录制时长、文件大小和格式、存储位置。播放通过 ORYX 的标准流媒体协议支持，确保与现有播放器实现的兼容性。对于高可用性部署，建议配置多个存储后端以提供冗余和关键录制的备份。

后续步骤

要探索相关的流媒体功能，请考虑：云存储集成 (S3)、使用 FFmpeg 进行流转码、HLS 和 HTTP-FLV 流媒体、HTTP OpenAPI 参考。有关实现细节和 API 规范，请参阅平台服务目录中的 DVR 相关源模块。

云存储集成（S3）

Oryx 平台提供全面的云存储集成功能，专门支持腾讯云 COS（Cloud Object Storage）实现 DVR（数字视频录像）功能。该集成功能通过最少的配置即可实现直播流的自动录制和云存储。

架构概览

云存储集成采用模块化架构，将录制逻辑与存储操作分离。

核心组件

DVR Worker 服务

DvrWorker 是负责管理云存储操作的核心组件：消息处理（通过缓冲通道处理来自 SRS 的 HLS 切片通知）、流管理（使用 sync.Map 维护活跃的录制流，支持并发访问）、凭证管理（从 Redis 动态更新腾讯云凭证）、上传操作（管理文件上传到 COS 存储桶，具备完善的错误处理机制）。

存储配置

系统需要在 Redis 中存储三个关键配置参数：Secret ID (SRS_TENCENT_CAM:secretId)、Secret Key (SRS_TENCENT_CAM:secretKey)、存储桶名称 (SRS_TENCENT_COS:bucket)。当任何凭证参数发生变化时，COS 客户端会自动重新创建，确保无缝轮换凭证而不中断服务。

流录制工作流

HLS 流处理与文件上传流程

上传机制确保媒体片段的可靠存储：文件验证、密钥生成、内容类型（video/MP2T）、执行上传、元数据更新。流完成后，系统生成 VOD 兼容的 M3U8 播放列表：内容组装、时长计算、上传播放列表、清理。

数据结构管理

流元数据包括 M3u8URL、UUID、NN、Update、Done、Messages。Redis 存储键：SRS_DVR_M3U8_WORKING、SRS_DVR_M3U8_ARTIFACT、SRS_DVR_PATTERNS。

API 端点

GET /terraform/v1/hooks/dvr/query（查询当前 DVR 配置和凭证状态）、POST /terraform/v1/hooks/dvr/apply（应用新的 DVR 设置和模式）。所有 API 端点都需要使用平台的 API 密钥令牌进行身份验证。

存储目录结构

系统为云存储操作创建专用目录 containers/data/srs-s3-bucket/。用户可以挂载此目录用于自定义存储集成或备份目的。

错误处理和恢复

凭证验证、上传重试、流恢复、资源清理。性能考虑：并发处理、缓冲通道（1024 消息缓冲区）、高效内存管理、连接池。集成点：SRS 钩子集成、平台服务集成。云存储集成为构建具有持久录制功能的可扩展直播应用提供了坚实的基础。

FFmpeg 流媒体转码

Oryx 中的 FFmpeg 流转码功能提供强大的实时视频处理能力，支持自适应码率流、格式转换和多协议输出，适用于直播场景。这一综合系统将 FFmpeg 作为转码引擎，集成了智能流管理和监控功能。

架构概览

转码系统采用基于工作器的架构，配备集中式任务管理，提供具备自动故障转移和实时监控能力的强大流处理。

核心组件

TranscodeWorker

TranscodeWorker 是所有转码操作的核心协调器：任务管理（维护一个活动的 TranscodeTask 实例）、API 处理器（暴露用于配置控制的 REST 端点）、生命周期控制（处理工作器的启动、关闭和重启操作）。系统采用单任务设计来简化资源管理，防止多个转码操作之间的冲突。

TranscodeTask 与 TranscodeConfig

TranscodeTask 代表一个独立的转码操作，具备进程控制、流选择、上下文管理、帧监控。配置通过 TranscodeConfig 处理，参数包括 All、VideoCodec (libx264/libx265)、AudioCodec (aac/mp3)、VideoBitrate、AudioBitrate、VideoProfile、VideoPreset、AudioChannels、Server、Secret 等。

FFmpeg 集成

命令构建

系统构建优化的 FFmpeg 命令，专为低延迟流传输设计：-re、-rtsp_transport tcp、-vcodec/-profile:v/-preset/v/-tune zerolatency、-b:v、-r 25 -g 50、-bf 0、-acodec/-b:a。FFmpeg 配置通过禁用 B 帧和使用 2 秒 GOP 大小专门优化 WebRTC 兼容性。

协议支持

RTMP/RTMPS（FLV 容器）、SRT（MPEG-TS 容器）、根据输出 URL 自动选择格式。

API 接口

查询配置 GET /terraform/v1/ffmpeg/transcode/query；应用配置 POST /terraform/v1/ffmpeg/transcode/apply；任务状态 POST /terraform/v1/ffmpeg/transcode/task。流选择算法：活动流发现、自我过滤、时间优先级、故障转移处理。

进程管理与监控

生命周期控制：基于上下文的取消、PID 跟踪、自动重启（指数退避）、资源清理。监控：帧解析、心跳系统、日志聚合、状态更新。Redis 集成：SRS_TRANSCODE_CONFIG、SRS_STREAM_ACTIVE、任务状态。错误处理：优雅降级、重试逻辑、错误传播、恢复机制。

性能考虑与使用场景

资源优化：单任务设计、延迟加载、内存管理、CPU 优化。延迟优化：zerolatency、GOP 2 秒、无 B 帧、RTSP TCP。使用场景：自适应码率流、格式转换（RTMP↔SRT、RTSP→RTMP）、质量优化（低延迟/高质量/带宽效率）。转码系统为高级流工作流提供了坚实的基础，具备生产环境所需的可靠性和可扩展性。

虚拟直播

Oryx 中的虚拟直播功能通过 FFmpeg 将视频文件转换为连续直播流，实现全天候 24/7 自动化直播。该功能对于无人值守直播间和需要持续在线的自动化内容分发场景具有特殊价值。

架构概览

虚拟直播系统采用基于 worker 的架构，管理多个并发流任务，每个任务负责将输入视频源转换为不同平台的直播流。

核心组件

VLiveWorker

中央协调器，管理所有虚拟直播任务，处理配置更新的 HTTP 请求，并通过 Redis 支持的持久化管理流任务的生命周期。

VLiveTask 与 VLiveConfigure

VLiveTask 封装了特定平台的 FFmpeg 进程，维护 UUID、Platform、Input、Output、PID、config。每个任务维护自己的 FFmpeg 进程，通过心跳轮询监控流状态，并提供自动恢复功能。VLiveConfigure 定义 Platform、Server、Secret、Enabled、Customed、Label、Files 等。

流程与 FFmpeg 集成

系统根据输入类型和输出协议动态构建 FFmpeg 命令：-stream_loop -1、-re、-rtsp_transport tcp、-c copy。RTMP 输出使用 -f flv，SRT 输出使用 -f mpegts，文件输入使用 -stream_loop -1 实现持续循环。

平台支持

微信 (wx)、哔哩哔哩、快手：预设支持与自定义配置，RTMP/RTMPS。自定义：支持任何 RTMP/SRT 端点，命名约定 vlive-{index}-{id}。

状态管理与 API

Redis：SRS_VLIVE_CONFIG、SRS_VLIVE_TASK。状态监控：启动时间、就绪时间、帧更新、进程健康。前端：ScenarioVLive 组件，配置管理、源选择、实时监控、多语言支持。API：POST /terraform/v1/ffmpeg/vlive/secret（配置管理）、POST /terraform/v1/ffmpeg/vlive/streams（状态监控）。

错误处理与性能考虑

进程监控、优雅关闭、配置验证、速率限制。性能：CPU、内存、网络带宽、存储 I/O。为获得最佳性能，考虑使用具有充足网络带宽的专用流媒体服务器或云实例。

多平台转发

多平台转发功能支持将流同时分发到微信视频号、哔哩哔哩和快手等多个平台，通过服务器端处理多个转发任务，而非客户端多路推流，从而优化带宽使用。

架构概览

转发系统采用基于 worker 的架构，通过管理 FFmpeg 进程实现流重分发。

核心组件

ForwardWorker

管理所有转发任务的核心协调器：任务管理（维护平台特定的 ForwardTask 实例 sync.Map）、生命周期控制、配置加载（从 Redis 动态加载转发配置）。

ForwardConfigure 与 ForwardTask

ForwardConfigure 定义 Platform、Stream、Server、Secret、Enabled、Customed、Label。ForwardTask 管理 FFmpeg 进程的独立转发任务：进程管理、流选择、健康监控、错误恢复。

流转发流程

输入流选择：活跃流发现、优先级选择、回退处理。FFmpeg 配置：-re -i [INPUT_URL] -c copy -f [FORMAT] [OUTPUT_URL]；RTMP 使用 -f flv，SRT 使用 -pes_payload_size 0 -f mpegts，RTSP 使用 -rtsp_transport tcp。系统会自动重建流 URL 以处理特殊字符。

平台支持

内置平台：微信视频号 (wx)、哔哩哔哩 (bilibili)、快手 (kuaishou)。自定义平台：以 "forwarding-" 为前缀动态注册、自定义服务器 URL 和认证、标签管理。

API 管理与前端集成

配置 API：/terraform/v1/ffmpeg/forward/secret（更新、查询、认证）。状态监控：/terraform/v1/ffmpeg/forward/streams（PID、流 URL、帧日志、启动时间）。React 界面 ScenarioForward.js：平台配置、实时监控（每 10 秒更新）、批量操作、自定义平台支持。

性能考虑与错误处理

资源管理：进程隔离、内存效率、优雅关闭。带宽优化：单次上传、服务器端分发、可靠性。自动重启：指数退避（300ms/3.5s）、配置重载。进程清理：SIGKILL 终止、资源释放、状态同步。后续步骤：RTMP 发布和播放、直播录制 (DVR)、使用 FFmpeg 流转码。

OpenAI 集成

ORYX 中的 OpenAI 集成为直播应用提供了全面的 AI 驱动功能，包括自动语音识别（ASR）、智能聊天辅助、OCR 处理和文本转语音合成。该集成利用 OpenAI 的 GPT 模型和视觉能力，通过实时 AI 交互增强直播体验。

架构概述

OpenAI 集成采用模块化架构，为不同的 AI 任务配备专门的 Worker：OpenAI 配置、管理 API、AI 服务（查询/更新端点、身份验证）；转录 Worker（ASR 处理）、AI 对话服务器（聊天补全）、OCR Worker（视觉分析）、TTS 服务（语音合成）；Redis 存储、SRS 媒体服务器。

配置管理

OpenAI 设置存储在 Redis：Secret Key (SRS_SYS_OPENAI:key)、Base URL、Organization。管理 API：POST /terraform/v1/mgmt/openai/query（查询配置）、POST /terraform/v1/mgmt/openai/update（更新配置，要求非空 secret key 和 base URL）。

模型兼容层

platform/openai.go 包含智能模型兼容处理：gptModelSupportSystem（对 o1 系列禁用系统消息）、gptModelSupportStream（对 o1 禁用流式）、gptModelSupportMaxTokens、gptModelSupportTemperature（o1 强制 0.0）。o1 系列模型需要特殊处理，兼容层根据模型前缀自动调整。

AI 服务组件

转录服务 (platform/transcript.go)：来自 HLS 片段的实时 ASR、基于队列的片段管理、持久化任务状态、接收 SRS 的 HLS 通知 → 加入 ASR 队列 → 提交 Whisper API → 存储结果与字幕叠加。2. AI 对话服务器 (platform/ai-talk.go)：ASR（Whisper）、聊天（GPT 补全）、TTS；阶段管理、实时广播、请求排队、会话持久化。3. OCR 处理 (platform/ocr.go)：从 HLS 片段捕获帧 → base64 → OpenAI Vision API → 提取文本 → 存储；队列管理（传入片段、OCR、回调、清理）。

集成模式、错误处理与性能

身份验证流程一致。错误处理：连接验证、优雅降级、重试逻辑、资源清理。性能：可配置片段限制（最多 9 个）、并发处理流水线。测试框架 test/openai_test.go：连接测试、转录测试、流式测试、直播间集成。后续步骤：直播间 AI 助手、视频转录服务、AI 配音和翻译、视频流 OCR。

直播间 AI 助手

直播间的 AI 助手是一个集成在 Oryx 流媒体平台中的复杂对话式 AI 系统，支持用户与 AI 在直播过程中进行实时语音交互。该功能结合了语音识别、自然语言处理和文本转语音技术，为直播间参与者打造沉浸式对话体验。

架构概览

AI 助手系统围绕多阶段处理管道构建，处理语音输入、转换为文本、生成 AI 响应并将响应转换回音频。架构由多个协同工作的核心组件组成。

核心组件

舞台管理：舞台作为直播间内 AI 对话的核心协调器 (platform/ai-talk.go)。每个舞台维护对话状态（历史用户输入和 AI 响应）、AI 配置（模型设置、语言偏好和提示词模板）、服务集成（ASR、聊天、TTS）、用户管理（多并发用户和订阅者）。Stage 结构包含 sid、update、aiConfig、histories、chatModel、prompt、replyLimit、chatWindow 等。

语音识别服务 (ASR)：使用 OpenAI Whisper，音频预处理（FFmpeg 转 AAC）、静音检测、语言支持、错误处理。

聊天服务：使用 OpenAI 聊天模型，上下文管理、提示词工程、流式响应、模型兼容性。

文本转语音服务 (TTS)：OpenAI 语音合成，CreateSpeech（TTSModel1、VoiceNova、ResponseFormatAac）。

请求处理管道

StageRequest 表示完整用户交互周期：音频上传 → ASR（Whisper）→ 聊天（GPT）→ TTS → 投递给房间订阅者。

配置与自定义、API、前端、性能与错误处理

AI 模型设置：chatModel、replyLimit、chatWindow、asrLanguage、prompt。服务开关：aiASREnabled、aiChatEnabled、aiPostEnabled、aiTtsEnabled。API：/terraform/v1/ai-talk/stage/start（舞台创建）、Bearer 令牌、房间绑定、生命周期管理。React 前端 ScenarioLiveRoom：创建和管理带 AI 助手的直播间、配置 AI 设置、监控对话状态。性能：后台清理例程、FFmpeg 低延迟设置。错误处理：静音检测、请求验证、服务降级、性能指标。后续步骤：OpenAI 集成、视频转录服务、AI 配音与翻译、视频流 OCR；流媒体协议见 RTMP 推流与播放、WebRTC 实时通信。

视频转录服务

Oryx 支持对直播流或录制内容进行语音转文字（ASR），便于生成字幕、检索与归档。转录服务通常与 HLS 分片联动：收到新分片后送入队列，调用 OpenAI Whisper 等引擎得到文本，再写入存储或通过回调推送给业务。配置与开关可通过管理界面或 API 完成，更多细节可参考官方文档中的「视频转录」专题。

AI 配音与翻译

Oryx 中的 AI 配音和翻译功能提供了一套自动化工作流，通过 AI 驱动的语音识别、翻译和文本转语音合成，将视频内容从一种语言转换为另一种语言。系统利用 OpenAI Whisper 转录、GPT 翻译与改写、TTS 语音合成。

架构与核心组件

配音系统采用多阶段管道架构。SrsDubbingProject：UUID、Title、FileType、AI Assistants（ASR/翻译/改写/TTS）、Source Metadata。SrsDubbingTask 状态：init → extract → asr → translating → tts → rephrasing → merging → done。音频处理管道：音频提取（16kHz 单声道 AAC）、分段（25MB 块）、ASR（Whisper-1）、智能合并（间隔 <10ms 且 <30 词）。翻译与 TTS：GPT 翻译、前序组引用、OpenAI TTS、时长分析与自动改写。

API、前端与配置

项目管理：/terraform/v1/dubbing/create、list、remove。任务控制：start、stop、query。配置：/dubbing/asr、trans、tts。React 前端：工作区、视频播放器、音频控制、组管理、状态指示器。ASR 配置：Whisper-1、AAC 16kHz；翻译：GPT-3.5/4、上下文感知；TTS：时长匹配、高质量合成。Redis：SRS_DUBBING_PROJECTS、SRS_DUBBING_TASKS；文件：containers/data/dubbing/。错误处理：重试最多 30 次、优雅降级、状态恢复、资源清理。性能：并行处理、智能缓存、流式音频、批操作。下一步：OpenAI 集成、直播间 AI 助手、视频转录服务、视频流 OCR。

视频流 OCR

Oryx 中的 OCR（光学字符识别）功能通过 AI 驱动的视觉模型，实现对视频流的实时文本提取。系统结合媒体处理、AI 推理和回调通知，将实时视频内容转换为可搜索的文本数据。

架构与核心组件

OCR 系统通过多阶段处理管道运行：RTMP 流 → SRS → HLS TS 分片 → 实时队列 → FFmpeg 帧提取 → OCR 队列 → AI 视觉 API → 文本识别 → 回调队列 → 外部回调 → 清理队列。四核心队列：LiveQueue、OCRQueue、CallbackQueue、CleanupQueue。OCRWorker 协调 OCR 操作，管理全局 OCR 任务与异步 HLS 分片消息。OCRTask：UUID、Input、Queues、Configuration、History。OCRConfig：All、SrsAssistantProvider、SrsAssistantChat。

处理管道

阶段 1 实时队列：分片验证、FFmpeg 帧提取（-frames:v 1 -q:v 10）、传入 OCR 队列。阶段 2 AI 识别：图像转 base64、发送视觉模型（GPT-4V 等）、上下文/对话历史、响应格式化。阶段 3 回调：外部通知、数据格式化、重试逻辑。阶段 4 清理：临时文件与内存管理。配置：all、aiProvider、aiChatModel、aiChatPrompt、aiChatMaxWindow、aiChatMaxWords；maxCallbackSegments 最多 9 个分片。

API、前端与性能

管理端点：/terraform/v1/ai/ocr/query、apply、reset及队列监控。React ScenarioOCR.js：3 秒刷新、配置管理、阶段状态、任务重置。性能：并发处理、内存效率、队列限制、上下文重用；Redis 持久化、故障恢复。集成：AI 提供商标准化接口、可配置回调（CMS、搜索、分析、通知）。后续：SRS 媒体服务器集成、OpenAI 集成、Redis 数据管理、HTTP OpenAPI 参考。

HTTP OpenAPI 参考

Oryx 提供一整套 RESTful API，用于程序化控制流媒体、AI 与系统管理。所有端点统一使用 JSON 请求/响应和基于令牌的身份验证；基础 URL 形如 http://your-oryx-server/terraform/v1/{category}/{action}。身份验证分为两类：管理 API 使用密码或会话令牌，服务 API 使用 API 密钥；均支持 Bearer 头与速率限制、登录锁定等安全策略。

常用管理类端点包括：POST /terraform/v1/mgmt/init 初始化系统、GET /terraform/v1/mgmt/check 健康检查、GET /terraform/v1/mgmt/versions 获取版本、POST /terraform/v1/mgmt/login 密码登录、POST /terraform/v1/mgmt/token 令牌刷新。直播间：POST /terraform/v1/live/room/create、query。配置与证书：POST /terraform/v1/mgmt/lets-encrypt、cert/query、nginx/hls/update、hls/lowlatency/update。流媒体：POST /terraform/v1/mgmt/streams/query 查询活跃流、kickoff 断开指定客户端。AI 相关：POST /terraform/v1/mgmt/openai/query、update，以及转录 /transcript/*、OCR /ocr/*、配音 /dubbing/*、AI 对话 /ai-talk/* 等。成功响应一般为 { code: 0, data, server }，错误为 { code, data: null, message, server }；常见错误码包括 401（未认证）、403（无权限）、404（资源不存在）、2049（RTMP 客户端未找到）。建议在请求中带上版本头、实现重试与令牌刷新，并注意速率限制与指数退避。更细的端点说明与请求示例可参考官方文档中的流媒体管理 API、配置 API 与管理 API 专题。

系统状态监控

Oryx 中的系统状态监控为平台的健康状况、性能和运行状态提供全面的可视化。监控系统通过一组明确定义的 API 端点和状态检查，使管理员和开发者能够跟踪系统组件、诊断问题并保持流媒体服务的最佳性能。

监控架构与核心状态端点

监控系统围绕中心化 HTTP 服务构建，通过 /terraform/v1/ API 命名空间公开状态端点。系统状态 API ：/terraform/v1/mgmt/status 提供系统当前状态概览，需身份验证，返回当前版本、发布信息、升级状态、策略信息；使用 SRS_UPGRADING 等 Redis 键。系统健康检查 ：/terraform/v1/mgmt/check 验证 Redis 连接、数据库状态（SRS_AUTH_SECRET、SRS_FIRST_BOOT、SRS_TENCENT_LH 等）。版本管理 API ：/terraform/v1/host/versions、/terraform/v1/mgmt/versions、/terraform/v1/ffmpeg/versions 返回 version/stable/latest。调试与诊断：/terraform/v1/debug/goroutines 提供 goroutine 与堆栈跟踪，无需认证，用于性能与死锁排查。监控数据流依赖 Redis：SRS_UPGRADING、SRS_AUTH_SECRET、SRS_FIRST_BOOT、SRS_TENCENT_LH。集成模式：JWT/API 密钥、标准化 JSON 响应。操作注意：速率限制、错误处理、缓存、调试端点安全。相关文档：平台服务（Go 后端）、Redis 数据管理、Prometheus 集成。

Prometheus 集成

Oryx 内置的监控能力可与 Prometheus 配合使用，实现对流媒体基础设施的可观测性。平台本身不直接暴露 Prometheus 指标格式，但提供若干 HTTP 监控端点和调试接口，可供采集与转换。

监控端点

系统 Status API ：/terraform/v1/mgmt/status 提供系统级状态（版本、升级状态、运行策略），需身份验证，返回 JSON，可由 Exporter 采集并转换为 Prometheus 指标。版本信息 ：/terraform/v1/host/versions、/terraform/v1/mgmt/versions。调试与性能 ：通过 Go pprof，/terraform/v1/debug/goroutines 可查看 Goroutine 堆栈，便于排查性能与死锁问题。

指标架构与集成策略

需要自建 Prometheus Exporter ：使用平台 token 做认证、定期请求上述监控端点、将 JSON 转为 Prometheus 指标格式，并在 /metrics 暴露给 Prometheus 拉取。可关注几类指标：System Status（平台版本与升级状态）、Performance（Goroutine 数量与堆栈）、Feature Usage（如 Redis 中的 SRS_STAT_COUNTER 等使用统计）。实现上，Exporter 请求 status 等接口、解析 JSON，再用 prometheus.MustNewConstMetric 等输出指标即可。

配置注意事项

身份验证需在请求中携带 API 密钥；监控接口并非为高频调用设计，建议采集间隔 30--60 秒，并对网络异常、认证失败与 API 变更做好错误处理与兼容。结合 Prometheus 的查询与告警即可构建完整的可观测性方案。

延伸阅读与参考链接

仓库与社区 ：ossrs/oryx（GitHub）
官方文档与解析：入门（快速入门、Docker 部署、端口与网络、数据卷）、架构与组件（架构概览、Go 后端、React 前端、SRS 集成、Redis）、协议（RTMP、WebRTC、HLS/HTTP-FLV、SRT）、高级能力（DVR、S3、FFmpeg 转码、虚拟直播、多平台转发）、AI（OpenAI、直播间助手、转录、配音、OCR）、API 与监控（OpenAPI、管理/流媒体/配置 API、系统状态、Prometheus）等专题，可在官方或社区文档站中按主题查阅。