跳转到主要内容
POST
/
channel
/
blacklist_remove
curl -X POST "http://localhost:5001/channel/blacklist_remove" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "group123",
    "channel_type": 2,
    "uids": ["user1", "user2"]
  }'
{
  "status": "ok"
}

概述

从频道黑名单中移除指定用户。被移除的用户将恢复正常权限,可以重新发送和接收频道消息。如果适用,会恢复相关会话。

请求体

必传参数

channel_id
string
required
频道ID,不能为空或包含特殊字符
channel_type
integer
required
频道类型
  • 1 - 个人频道
  • 2 - 群组频道
uids
array
required
要从黑名单中移除的用户ID列表
uids[]
string
用户ID
curl -X POST "http://localhost:5001/channel/blacklist_remove" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "group123",
    "channel_type": 2,
    "uids": ["user1", "user2"]
  }'
{
  "status": "ok"
}

响应字段

status
string
required
操作状态,成功时返回 "ok"

状态码

状态码说明
200用户从黑名单移除成功
400请求参数错误
403没有管理权限
404频道不存在
500服务器内部错误

功能说明

移除操作

移除操作会执行以下步骤:
  1. 验证用户:检查指定用户是否在黑名单中
  2. 移除条目:从频道黑名单中删除指定用户
  3. 恢复权限:用户重新获得发送和接收消息的权限
  4. 恢复会话:如果适用,恢复用户的相关会话

权限恢复

被移除的用户将恢复:
权限说明生效时间
发送消息可以向频道发送消息立即生效
接收消息可以接收频道消息立即生效
会话访问恢复频道会话(如果适用)立即生效
正常交互恢复所有正常的频道交互权限立即生效

特殊情况

直播频道

  • 不处理会话恢复:直播频道不会自动恢复会话
  • 权限立即生效:用户仍可立即恢复发送和接收权限

个人频道

  • 不支持黑名单:个人频道不支持黑名单操作
  • 返回错误:尝试操作会返回相应错误信息

使用场景

解除误封

# 解除误加入黑名单的用户
curl -X POST "/channel/blacklist_remove" -d '{
  "channel_id": "group123",
  "channel_type": 2,
  "uids": ["innocent_user"]
}'

批量恢复

# 批量移除多个用户
curl -X POST "/channel/blacklist_remove" -d '{
  "channel_id": "group123",
  "channel_type": 2,
  "uids": ["user1", "user2", "user3"]
}'

临时解封

# 临时解除用户限制
curl -X POST "/channel/blacklist_remove" -d '{
  "channel_id": "group123",
  "channel_type": 2,
  "uids": ["temp_banned_user"]
}'

黑名单管理策略

操作对比

操作功能影响范围适用场景
blacklist_add添加到黑名单新增限制处罚违规用户
blacklist_remove从黑名单移除解除限制恢复用户权限
blacklist_set替换整个黑名单全面重置批量管理

管理流程

  1. 评估情况:确认用户是否应该被移除
  2. 执行移除:调用API移除用户
  3. 验证结果:确认用户权限已恢复
  4. 记录操作:记录移除原因和时间
  5. 后续监控:观察用户后续行为

最佳实践

  1. 权限验证:确保操作者有足够的管理权限
  2. 操作记录:记录所有黑名单变更操作
  3. 通知机制:通知相关管理员和用户
  4. 渐进式解封:对于严重违规用户,考虑渐进式恢复权限
  5. 监控机制:移除后继续监控用户行为
  6. 备份策略:在大批量操作前备份当前黑名单状态

错误处理

常见错误

错误信息原因解决方案
频道ID不能为空未提供频道ID确保提供有效的频道ID
频道类型不能为0频道类型无效使用有效的频道类型(1或2)
uids不能为空未提供用户列表提供要移除的用户ID列表
移除黑名单失败移除操作失败检查用户是否在黑名单中
添加会话失败会话恢复失败检查会话系统状态

错误恢复

async function removeFromBlacklistWithRetry(channelId, channelType, uids, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch('/channel/blacklist_remove', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          channel_id: channelId,
          channel_type: channelType,
          uids: uids
        })
      });
      
      if (response.ok) {
        return await response.json();
      }
      
      if (response.status >= 400 && response.status < 500) {
        // 客户端错误,不重试
        throw new Error(`Client error: ${response.status}`);
      }
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await new Promise(resolve => setTimeout(resolve, Math.pow(2, i) * 1000));
    }
  }
}

监控和审计

操作日志

建议记录以下信息:
  • 操作时间
  • 操作者ID
  • 频道信息
  • 被移除的用户列表
  • 操作结果
  • 失败原因(如果有)

审计报告

定期生成审计报告:
  • 黑名单变更统计
  • 用户权限恢复情况
  • 操作频率分析
  • 异常操作检测

相关接口