# 封禁用户权限 (/zh-CN/realtime-media/rtc/build/security-and-auth/user-privilege)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

本文介绍声网频道管理 RESTful API 中封禁用户权限 API 的使用说明，包括使用原则，适用场景，不适用场景以及接口调用异常处理的最佳实践。

API 参考详见[封禁用户权限](/zh-CN/api-reference/api-ref/rtc/create-ban-rule)。

## 使用原则 [#使用原则]

在使用封禁用户权限 API 时请遵循以下原则：

- 避免业务主流程强依赖封禁用户权限 API。
- 集成上应进行充分考虑，以尽量避免 RESTful 请求的失败最终影响业务主流程。

## 适用场景 [#适用场景]

### 封禁非法用户 [#封禁非法用户]

#### 使用方式 [#使用方式]
根据用户 ID 封禁该用户的加入频道权限，即：将 `privileges` 设为 `join_channel` ，填写 `uid`，不填写 `cname` 和 `ip`，`time` 设置为 `0` 以外的值。

#### 示例场景 [#示例场景]
发现有违规用户，无法通过你的业务信令彻底封禁该用户时，通过封禁接口禁止该 UID 进入频道。

#### 注意事项 [#注意事项]

在业务信令无法完全封禁非法用户的情况下，可以将使用服务端封禁接口作为一种兜底手段，但需要考虑是否有解封需求。对非法用户的解封通常不应集成进业务主流程，以防解封失败对业务产生影响。

- 正确的使用方式示例：用户主动申诉后人工解封。
- 不正确的使用方式示例：用户下次加入频道时自动解封。这会导致调用解封接口失败时用户无法加入频道。

### 封禁用户音视频权限 [#封禁用户音视频权限]

#### 使用方式 [#使用方式-1]
根据用户 ID 封禁该用户的音视频发流权限，即：将 `privileges` 设为 `publish_audio` 或 `publish_video`，填写 `uid`，不填写 `cname` 和 `ip`，`time` 设置为 `0` 以外的值。

#### 示例场景 [#示例场景-1]
当业务上发现用户已经下麦或者没有发流权限的用户可以发音视频流，即可调用封禁接口封禁该 UID 的发流权限。

#### 注意事项 [#注意事项-1]

- 通过封禁接口封禁用户的发流权限是一个很危险的操作，应当作为业务信令通知用户下麦失败，且造成实际影响之后的兜底手段。
- 充分考虑当用户需要再次上麦时，解封发流权限封禁调用的延迟、失败会对用户再次发言带来的影响。
- 封禁的时长尽量设置短一些。

<a name="kick_user" />

### 将用户一次性踢出频道 [#将用户一次性踢出频道]

#### 使用方式 [#使用方式-2]

根据频道名和用户 ID 将该用户一次性踢出频道（不封禁，只是对用户进行下线一次的操作，用户可以重新登录进入频道），即：将 `privileges` 设为 `join_channel` ，填写 `cname` 和 `uid`，不填写 `ip`，`time` 设为 `0`。

#### 示例场景 [#示例场景-2]

- 主播有多个设备，在设备 1 登录后将其遗忘在家中，使用设备 2 开始直播时发现有 2 个设备在以相同的 `uid` 发流导致异常。在这种情况下，可以用本方法将设备 1 和设备 2 一次性踢出频道，此时设备 1 不会重连，设备 2 重新加入频道即可。
- 通过自己业务服务器发送的离开频道信令失效，此时可以使用本方法将用户一次性踢出频道。

#### 注意事项 [#注意事项-2]

`time` 设置为 `0` 的一次性踢人是一种较为安全的使用方式。当踢人请求到达边缘节点的时刻，SDK 正好和边缘节点断连的情况下会导致一次性踢人失效。如果发现在踢人后 SDK 又重连上了边缘节点，可以再次调用踢人接口。

### 解散频道 [#解散频道]

#### 使用方式 [#使用方式-3]

频道结束后，根据频道名将所有用户一次性踢出频道，即：将 `privileges` 设为 `join_channel` ，填写 `cname` ，不填写 `uid` 和  `ip`，`time` 设为 `0`。

#### 示例场景 [#示例场景-3]

该方法用于一次性解散结束的频道，快速将所有用户踢出频道。 如果频道确认短时间内不会再开启，也可以将 `time` 设为 1 分钟或其他时间。

:::warning[注意]
将 `cname` 作为封禁规则相当于销毁该频道，请确认符合你的业务要求。
:::

#### 注意事项 [#注意事项-3]

在该场景中，请先使用自己的信令在频道结束后通知 SDK 调用 `leave channel`。在业务信令无法满足需求的情况下，可将强制解散频道作为兜底手段。如完全依赖 RESTful 请求，会导致请求失败引起的影响被扩大。

- 在频道不会复用的情况下，可以用封禁一段时间来确保频道结束后不会有用户再加入这个频道。
- 如果频道会复用，且能知道下次频道创建的确切时间，请确保频道封禁的结束时间不晚于下次频道的创建时间。不建议长时间封禁，等到频道开始的时候才调用解封接口。因为一旦解封失败，用户将无法加入频道。
- 如果频道会复用，但不知道下次频道创建的确切时间，建议将[用户踢出频道](/zh-CN/realtime-media/rtc/build/security-and-auth/user-privilege)，或者将封禁时间设置为 1 分钟。

### 封禁非法 IP [#封禁非法-ip]

#### 使用方式 [#使用方式-4]
根据 IP 封禁用户的加入频道权限，即：将 `privileges` 设为 `join_channel` ，填写 `ip`，不填写 `cname` 和 `uid`，`time` 设置为 `0` 以外的值。

#### 示例场景 [#示例场景-4]
当业务上被攻击并且识别出攻击来源的 IP 时，可以使用 `ip` 字段对该 IP 进行封禁。

#### 注意事项 [#注意事项-4]
使用 IP 作为封禁规则时可能会误伤他人，如多人共享一个 IP 出口的情况。

## 不适用场景 [#不适用场景]

### 用封禁接口实现用户麦位管理 [#用封禁接口实现用户麦位管理]

操作：用户下麦时封禁发流权限，用户上麦时解封。

不适用原因：RTC 业务逻辑依赖封禁用户权限 API 的可用性，如解封失败则用户无法发流。

### 用封禁接口实现用户频道权限管理 [#用封禁接口实现用户频道权限管理]

操作：用户离开频道时封禁用户加入频道权限，重新申请加入时解封。

不适用原因：RTC 业务逻辑依赖踢人接口的可用性，如解封失败则用户无法再次加入频道。离开频道时推荐使用一次性踢人以确保用户离开频道。

:::info[信息]
为了更好地实现麦位管理，声网提供了频道状态查询和消息通知服务 (NCS)，可以通过该服务获得频道实时状态并设计后续的业务逻辑。详见[使用消息通知服务](/zh-CN/realtime-media/rtc/build/optimize-and-operate/receive_webhook)。
:::

## 接口调用异常处理最佳实践 [#接口调用异常处理最佳实践]

### 超时设置 [#超时设置]
请求的客户端超时时间建议设置为 20s 以上的值（最低不低于 5s）以对抗网络波动。并在重试超时的请求时，适当增大超时时间以提高网络波动情况下的请求成功率。

### 重试请求 [#重试请求]
可以基于自己的业务逻辑来决定是否需要失败后重试请求以及重试次数。

当请求返回大于等于 `500` 的错误码或者请求超时时，可以继续重试请求，并在多次重试之间以退避的方式增加等待间隔。