添加游戏盾代理支持

2026-03-03 18:11:09 +08:00
parent ae4a045451
commit 8e9b816a4e
13 changed files with 517 additions and 105 deletions
--- a/docs/SellySDK_直播推拉流接入文档_Android.md
+++ b/docs/SellySDK_直播推拉流接入文档_Android.md
@@ -1,6 +1,6 @@
 # Selly Live SDK 推拉流接入文档（Android）

-> 统一 SDK 名称：**SellyCloudSDK**  
+> 统一 SDK 名称：**SellyCloudSDK**
 > 本文档适用于 Android 客户端，面向对外集成方与内部使用。

 ---
@@ -19,6 +19,7 @@ Selly Live SDK 提供完整的音视频直播能力，支持 **推流（直播
 - 支持视频帧处理（美颜 / 滤镜 / 水印）
 - 基于 **Token 的安全鉴权机制**
 - 支持 **RTMP H264 + AAC payload XOR 保护（可选）**
+- 支持 **外部代理地址注入**（如洋葱盾等第三方安全代理）

 ---

@@ -34,8 +35,8 @@ Selly Live SDK 提供完整的音视频直播能力，支持 **推流（直播

 ### 3.1 项目结构参考

- `example/`：Android Demo 工程  
-  - 推流示例：`example/src/main/java/com/demo/SellyCloudSDK/live/LivePushActivity.kt`  
+- `example/`：Android Demo 工程
+  - 推流示例：`example/src/main/java/com/demo/SellyCloudSDK/live/LivePushActivity.kt`
  - 拉流示例：`example/src/main/java/com/demo/SellyCloudSDK/live/LivePlayActivity.kt`
 - `example/libs/`：本地 AAR 依赖存放目录

@@ -60,9 +61,81 @@ dependencies {

 ---

-## 4. Token 鉴权机制（重点）
+## 4. SDK 初始化与代理配置

-### 4.1 Token 注入方式
+### 4.1 SDK 初始化
+
+在使用任何推流 / 拉流功能前，必须先初始化 SDK：
+
+```kotlin
+SellyCloudManager.initialize(
+    context = applicationContext,
+    appId = "your-app-id",
+    config = SellyCloudConfig(
+        vhost = "your-vhost",
+        vhostKey = "your-vhost-key",
+        defaultStreamId = "default-stream",
+        defaultLiveMode = SellyLiveMode.RTMP
+    )
+)
+```
+
+`initialize` 参数说明：
+
+| 参数 | 类型 | 说明 |
+| ---- | ---- | ---- |
+| `context` | Context | 应用上下文 |
+| `appId` | String | 应用 ID（权威值，会覆盖 config 中的 appId） |
+| `config` | SellyCloudConfig? | 可选配置，不传则使用默认值 |
+
+`SellyCloudConfig` 字段说明：
+
+| 字段 | 类型 | 说明 |
+| ---- | ---- | ---- |
+| `vhost` | String | 虚拟主机 |
+| `vhostKey` | String | vhost 密钥（用于鉴权签名） |
+| `defaultStreamId` | String | 默认流 ID |
+| `logEnabled` | Boolean | 是否启用日志，默认 true |
+| `defaultLiveMode` | SellyLiveMode | 默认推拉流模式（RTMP / RTC） |
+| `appName` | String | 应用名称，为空时自动使用 appId，一般无需设置 |
+
+> `config.appId` 无需设置，SDK 内部会用 `initialize(appId=)` 参数覆盖。
+
+### 4.2 代理地址配置（可选）
+
+SDK 支持通过外部代理（如洋葱盾等安全加速服务）进行流媒体连接。代理地址由业务方在 SDK 外部获取，然后通过以下接口注入：
+
+```kotlin
+// 设置代理地址
+SellyCloudManager.setProxyAddress("http://127.0.0.1:12345")
+
+// 清除代理（恢复直连）
+SellyCloudManager.setProxyAddress(null)
+
+// 查询当前代理地址
+val proxy = SellyCloudManager.getProxyAddress()  // null 表示未设置
+```
+
+**格式要求：**
+- 必须以 `http://` 或 `https://` 开头
+- 传 `null` 或空字符串表示清除代理
+- 格式不合法时抛出 `IllegalArgumentException`
+
+**生效范围：**
+- 设置后对 RTMP 推拉流、RTC（WHEP/WHIP）播放推流、Signaling 信令连接均生效
+- SDK 内部通过代理地址解析真实服务器 IP，对上层透明
+
+**时机要求：**
+- 必须在推流 / 拉流 **开始之前** 设置
+- 推流 / 拉流过程中修改代理地址，需停止后重新开始才能生效
+
+> Demo 中使用 `KiwiHelper` 封装了洋葱盾 SDK 的初始化与代理地址获取流程，通过 `SellyCloudManager.setProxyAddress()` 将结果传给 SDK。详见 `example/src/main/java/com/demo/SellyCloudSDK/KiwiHelper.kt`。
+
+---
+
+## 5. Token 鉴权机制（重点）
+
+### 5.1 Token 注入方式

 | 场景 | 设置位置 |
 | ---- | ---- |
@@ -76,7 +149,7 @@ dependencies {
 - SDK 内部在建立连接时自动携带当前 Token
 - 直接使用 RTMP 地址推/拉流不需要 Token，可不设置

-### 4.2 Token 设置时机（强约束）
+### 5.2 Token 设置时机（强约束）

 #### 推流

@@ -91,9 +164,9 @@ dependencies {
 - `prepareToPlay()`
 - `play()`

-> ⚠️ 在连接建立后修改 Token，不会影响当前连接。
+> 在连接建立后修改 Token，不会影响当前连接。

-### 4.3 Token 刷新机制说明
+### 5.3 Token 刷新机制说明

 - SDK **不提供自动刷新**
 - 业务层可在任意时刻 **重新设置 token 属性**
@@ -104,7 +177,7 @@ dependencies {
 2. 调用 `pusher.token = newToken` / `player.token = newToken`
 3. 停止并重新开始推流 / 拉流流程

-### 4.4 RTMP Payload XOR 保护（可选）
+### 5.4 RTMP Payload XOR 保护（可选）

 用途：

@@ -131,9 +204,9 @@ Key 格式：

 ---

-## 5. 推流接入详解
+## 6. 推流接入详解

-### 5.1 创建推流实例
+### 6.1 创建推流实例

 ```kotlin
 val pusher = SellyLiveVideoPusher.initWithLiveMode(
@@ -147,7 +220,7 @@ pusher.delegate = object : SellyLiveVideoPusherDelegate {
 }
 ```

-### 5.2 视频参数配置与预览
+### 6.2 视频参数配置与预览

 ```kotlin
 val config = SellyLiveVideoConfiguration.defaultConfiguration().apply {
@@ -166,7 +239,7 @@ pusher.startRunning(
 )
 ```

-### 5.3 设置推流 Token（使用 streamId 时）
+### 6.3 设置推流 Token（使用 streamId 时）

 ```kotlin
 pusher.token = pushToken
@@ -183,7 +256,7 @@ pusher.setXorKey(xorKeyHex)

 > 若在推流中修改 key，需停止并重新开始推流后才会使用新 key。

-### 5.4 开始/停止推流
+### 6.4 开始/停止推流

 ```kotlin
 pusher.startLiveWithStreamId(streamId)
@@ -212,7 +285,7 @@ pusher.stopLive { error ->
 }
 ```

-### 5.5 常用控制接口
+### 6.5 常用控制接口

 - `setMuted(true/false)`：静音
 - `switchCameraPosition(...)`：切换摄像头
@@ -226,7 +299,7 @@ pusher.stopLive { error ->
 - `setBeautyLevel(level)`：设置美颜强度
 - `setBitmapAsVideoSource(...)` / `restoreCameraVideoSource()`：背景图推流

-### 5.6 生命周期建议
+### 6.6 生命周期建议

 在宿主 Activity 中对齐生命周期：

@@ -234,7 +307,7 @@ pusher.stopLive { error ->
 - `onPause()` → `pusher.onPause()`
 - `onDestroy()` → `pusher.release()`

-### 5.7 状态与统计回调
+### 6.7 状态与统计回调

 **状态枚举：**

@@ -252,7 +325,7 @@ pusher.stopLive { error ->
 - rttMs
 - cpu 使用率（Demo 通过 `CpuUsage` 读取）

-### 5.8 推流 API 速览（含 Demo 未覆盖）
+### 6.8 推流 API 速览（含 Demo 未覆盖）

 初始化与预览：

@@ -293,9 +366,9 @@ pusher.stopLive { error ->

 ---

-## 6. 拉流接入详解
+## 7. 拉流接入详解

-### 6.1 创建播放器
+### 7.1 创建播放器

 ```kotlin
 val player = SellyLiveVideoPlayer.initWithStreamId(
@@ -323,14 +396,14 @@ val player = SellyLiveVideoPlayer.initWithStreamId(

 > 使用 RTMP 加密流时，请在创建播放器时传入 `xorKeyHex`；后续如需换 key，请重建播放器实例。

-### 6.2 设置拉流 Token（使用 streamId 时）
+### 7.2 设置拉流 Token（使用 streamId 时）

 ```kotlin
 player.token = playToken
 ```
 > 直接使用 RTMP 地址拉流不需要 Token，可不设置。

-### 6.3 播放流程
+### 7.3 播放流程

 ```kotlin
 player.attachRenderView(renderContainer)
@@ -351,7 +424,7 @@ player.play()
 - `setRenderView(view)`：手动指定渲染 View
 - `seekBy(deltaMs)`：播放进度跳转（仅在流支持快进/回放时有效）

-### 6.4 播放回调
+### 7.4 播放回调

 ```kotlin
 player.delegate = object : SellyLiveVideoPlayerDelegate {
@@ -374,7 +447,7 @@ player.delegate = object : SellyLiveVideoPlayerDelegate {
 - `Reconnecting`
 - `Failed`

-### 6.5 播放 API 速览（含 Demo 未覆盖）
+### 7.5 播放 API 速览（含 Demo 未覆盖）

 创建与渲染：

@@ -397,7 +470,7 @@ player.delegate = object : SellyLiveVideoPlayerDelegate {

 ---

-## 7. 错误处理与重试建议
+## 8. 错误处理与重试建议

 ### Token 错误

@@ -414,24 +487,25 @@ player.delegate = object : SellyLiveVideoPlayerDelegate {

 ---

-## 8. 最佳实践
+## 9. 最佳实践

 - 推流前先完成采集预览
 - Token 即将过期前提前刷新
 - 使用统计回调做质量监控
 - 拉流失败避免无限重试
+- 使用代理时，确保在推拉流开始前代理地址已设置完毕

 ---

-## 9. 常见问题（FAQ）
+## 10. 常见问题（FAQ）

 ### Q1：Token 可以拼接到 URL 吗？
-**A：** 不可以。  
+**A：** 不可以。
 SDK 不解析 URL 中的鉴权信息，所有鉴权均通过 `token` 属性完成。

 ### Q2：运行中修改 Token 是否生效？
 **A：**
-运行中修改 Token **不会影响当前已建立的连接**。  
+运行中修改 Token **不会影响当前已建立的连接**。
 **下次重连或重新启动推流 / 拉流时会使用新的 Token**。

 ### Q3：播放器出现黑屏怎么办？
@@ -449,3 +523,15 @@ SDK 不解析 URL 中的鉴权信息，所有鉴权均通过 `token` 属性完
 - key 格式是否为合法 hex（偶数长度，支持 `0x` 前缀）
 - 当前是否为 RTMP + H264 + AAC
 - 变更 key 后是否已重启推流 / 重建播放器
+
+### Q5：如何接入代理/加速服务（如洋葱盾）？
+**A：**
+SDK 本身不集成任何第三方代理 SDK。业务方需在 SDK 外部完成代理初始化与地址获取，然后通过 `SellyCloudManager.setProxyAddress(proxyUrl)` 注入。SDK 内部会自动通过代理地址解析真实服务器 IP。
+
+示例流程：
+1. 在 Application 或 Activity 中初始化代理 SDK
+2. 获取本地代理地址（如 `http://127.0.0.1:12345`）
+3. 调用 `SellyCloudManager.setProxyAddress("http://127.0.0.1:12345")`
+4. 正常进行推流 / 拉流
+
+> Demo 中的 `KiwiHelper` 展示了洋葱盾的完整接入流程，可作为参考。
--- a/docs/SellySDK_音视频通话接入文档_Android.md
+++ b/docs/SellySDK_音视频通话接入文档_Android.md
@@ -8,16 +8,17 @@ SDK 核心以 `InteractiveRtcEngine` 为中心，通过 `InteractiveRtcEngineEve

 ## 目录

-1. 准备工作  
-2. 快速开始  
-3. 基础通话流程  
-4. 常用功能  
-5. 屏幕分享  
-6. 视频帧前后处理  
-7. 事件回调（EventHandler）  
-8. 通话统计  
-9. Token 机制  
-10. 常见问题（FAQ）
+1. 准备工作
+2. 快速开始
+3. 基础通话流程
+4. 常用功能
+5. 屏幕分享
+6. 视频帧前后处理
+7. 事件回调（EventHandler）
+8. 通话统计
+9. Token 机制
+10. 代理地址配置
+11. 常见问题（FAQ）

 ---

@@ -38,19 +39,40 @@ SDK 核心以 `InteractiveRtcEngine` 为中心，通过 `InteractiveRtcEngineEve

 ## 快速开始

-### 1. 创建引擎
+### 1. SDK 初始化
+
+在使用音视频通话功能前，需先初始化 SDK：
+
+```kotlin
+SellyCloudManager.initialize(
+    context = applicationContext,
+    appId = "your-app-id"
+)
+```
+
+> `initialize` 的 `appId` 参数为权威值。可选传入 `SellyCloudConfig` 配置 `vhost`、`logEnabled` 等，详见推拉流文档。
+
+### 2. 代理地址设置（可选）
+
+若需通过代理（如洋葱盾）连接信令服务器，在创建引擎前设置：
+
+```kotlin
+SellyCloudManager.setProxyAddress("http://127.0.0.1:12345")
+```
+
+> SDK 内部通过代理地址解析真实信令服务器 IP。不设置则使用直连。详见「代理地址配置」章节。
+
+### 3. 创建引擎

 ```kotlin
 val appId = getString(R.string.signaling_app_id)
 val token = getString(R.string.signaling_token).takeIf { it.isNotBlank() }
-val kiwiRsName = getString(R.string.signaling_kiwi_rsname).trim()

 val rtcEngine = InteractiveRtcEngine.create(
    InteractiveRtcEngineConfig(
        context = applicationContext,
        appId = appId,
-        defaultToken = token,
-        kiwiRsName = kiwiRsName
+        defaultToken = token
    )
 ).apply {
    setEventHandler(eventHandler)
@@ -68,9 +90,20 @@ val rtcEngine = InteractiveRtcEngine.create(
 }
 ```

-> `InteractiveRtcEngineConfig` 与默认 token 配置见 `example/src/main/java/com/demo/SellyCloudSDK/interactive/InteractiveLiveActivity.kt`。
+`InteractiveRtcEngineConfig` 参数说明：

-### 2. 设置本地/远端画布
+| 参数 | 类型 | 说明 |
+| ---- | ---- | ---- |
+| `context` | Context | 应用上下文 |
+| `appId` | String | 应用 ID |
+| `defaultCallType` | CallType | 默认通话类型，默认 ONE_TO_ONE |
+| `defaultToken` | String? | 默认 Token |
+| `signalingUrlPrefix` | String | 信令 URL 前缀，默认 `ws://` |
+| `signalingUrlSuffix` | String | 信令 URL 后缀，默认 `/ws/signaling` |
+
+> 完整 Demo 见 `example/src/main/java/com/demo/SellyCloudSDK/interactive/InteractiveLiveActivity.kt`。
+
+### 4. 设置本地/远端画布

 ```kotlin
 val localRenderer = SurfaceViewRenderer(this)
@@ -82,7 +115,7 @@ val remoteRenderer = SurfaceViewRenderer(this)
 rtcEngine.setupRemoteVideo(InteractiveVideoCanvas(remoteRenderer, remoteUserId))
 ```

-### 3. 加入通话
+### 5. 加入通话

 ```kotlin
 val options = InteractiveChannelMediaOptions(callType = CallType.ONE_TO_ONE)
@@ -109,23 +142,9 @@ rtcEngine.leaveChannel()
 InteractiveRtcEngine.destroy(rtcEngine)
 ```

-### 4. 进阶配置（Demo 未覆盖）
+### 6. 进阶配置（Demo 未覆盖）

-#### 4.1 InteractiveRtcEngineConfig 高级字段
-
-```kotlin
-val config = InteractiveRtcEngineConfig(
-    context = applicationContext,
-    appId = appId,
-    defaultCallType = CallType.ONE_TO_ONE,
-    defaultToken = token,
-    kiwiRsName = kiwiRsName,
-    signalingUrlPrefix = "https://",
-    signalingUrlSuffix = "/signaling"
-)
-```
-
-#### 4.2 InteractiveChannelMediaOptions 订阅控制
+#### 6.1 InteractiveChannelMediaOptions 订阅控制

 ```kotlin
 val options = InteractiveChannelMediaOptions(
@@ -135,7 +154,7 @@ val options = InteractiveChannelMediaOptions(
 )
 ```

-#### 4.3 InteractiveVideoEncoderConfig 更多参数
+#### 6.2 InteractiveVideoEncoderConfig 更多参数

 可选项（按需设置）：

@@ -150,14 +169,16 @@ val options = InteractiveChannelMediaOptions(

 ## 基础通话流程

-1. 创建 `InteractiveRtcEngine`
-2. 设置 `EventHandler`
-3. 配置 `InteractiveVideoEncoderConfig`
-4. 设置本地画布 `setupLocalVideo`
-5. `joinChannel` 加入频道
-6. `onUserJoined` 后设置远端画布
-7. 通话中进行音视频控制
-8. `leaveChannel` 并释放资源
+1. 初始化 SDK（`SellyCloudManager.initialize`）
+2. 设置代理地址（可选，`SellyCloudManager.setProxyAddress`）
+3. 创建 `InteractiveRtcEngine`
+4. 设置 `EventHandler`
+5. 配置 `InteractiveVideoEncoderConfig`
+6. 设置本地画布 `setupLocalVideo`
+7. `joinChannel` 加入频道
+8. `onUserJoined` 后设置远端画布
+9. 通话中进行音视频控制
+10. `leaveChannel` 并释放资源

 ---

@@ -260,7 +281,7 @@ rtcEngine.setRenderVideoFrameInterceptor { frame, userId ->
 }
 ```

-> Demo 中的美颜示例见：  
+> Demo 中的美颜示例见：
 > `example/src/main/java/com/demo/SellyCloudSDK/beauty/FuVideoFrameInterceptor.kt`

 ---
@@ -321,6 +342,61 @@ rtcEngine.renewToken(newToken, expiresAtSec)

 ---

+## 代理地址配置
+
+SDK 支持通过外部代理（如洋葱盾等安全加速服务）连接信令服务器。代理地址由业务方在 SDK 外部获取，然后注入 SDK。
+
+### 设置方式
+
+```kotlin
+// 设置代理地址（在 joinChannel 之前）
+SellyCloudManager.setProxyAddress("http://127.0.0.1:12345")
+
+// 清除代理（恢复直连）
+SellyCloudManager.setProxyAddress(null)
+
+// 查询当前代理地址
+val proxy = SellyCloudManager.getProxyAddress()  // null 表示未设置
+```
+
+### 格式要求
+
+- 必须以 `http://` 或 `https://` 开头
+- 传 `null` 或空字符串表示清除代理
+- 格式不合法时抛出 `IllegalArgumentException`
+
+### 生效范围
+
+设置后，SDK 内部通过代理地址解析真实信令服务器 IP，对上层接口透明。
+
+### 时机要求
+
+- 必须在 `joinChannel()` **之前** 设置
+- 通话过程中修改代理地址，需 `leaveChannel` 后重新 `joinChannel` 才能生效
+
+### Demo 中的接入示例
+
+Demo 使用 `KiwiHelper` 封装洋葱盾的初始化与代理获取，采用三阶段模式：
+
+```kotlin
+// 阶段 1：Application.onCreate() 异步初始化
+KiwiHelper.initializeAsync()
+
+// 阶段 2：Activity 初始化时启动代理获取（非阻塞）
+KiwiHelper.startProxySetup(enableKiwi = true, rsName = "your-rs-name")
+
+// 阶段 3：joinChannel 前确保代理已就绪
+lifecycleScope.launch {
+    KiwiHelper.awaitProxyReady()
+    rtcEngine.joinChannel(...)
+}
+```
+
+> `KiwiHelper` 内部通过 `SellyCloudManager.setProxyAddress()` 将代理地址传给 SDK。
+> 详见 `example/src/main/java/com/demo/SellyCloudSDK/KiwiHelper.kt`。
+
+---
+
 ## 更多 API 速览（含 Demo 未覆盖）

 引擎创建与销毁：
@@ -328,6 +404,12 @@ rtcEngine.renewToken(newToken, expiresAtSec)
 - `InteractiveRtcEngine.create(config)`：创建引擎
 - `InteractiveRtcEngine.destroy(engine)` / `engine.destroy()`：释放引擎

+SDK 初始化与代理：
+
+- `SellyCloudManager.initialize(context, appId, config)`：初始化 SDK
+- `SellyCloudManager.setProxyAddress(address)`：设置代理地址
+- `SellyCloudManager.getProxyAddress()`：获取当前代理地址
+
 通话控制：

 - `setEventHandler(handler)`：设置事件回调
@@ -369,7 +451,11 @@ rtcEngine.renewToken(newToken, expiresAtSec)
 1. 检查 `signaling_app_id` 是否正确
 2. Token 是否为空或已过期
 3. 网络是否受限
+4. 若使用代理，检查代理地址是否已正确设置

 ### Q：屏幕分享失败？
 1. 是否已获取 `MediaProjection` 授权
 2. Android 14+ 是否启动前台服务
+
+### Q：如何接入代理/加速服务？
+SDK 本身不集成任何第三方代理 SDK。业务方需在外部完成代理初始化，获取本地代理地址后，通过 `SellyCloudManager.setProxyAddress()` 注入。详见「代理地址配置」章节。