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

{
  "status": "ok"
}

​
概述

设置（替换）频道的完整黑名单。此操作会先清除所有现有黑名单条目，然后添加新的条目。如果UIDs为空，则清空整个黑名单。

​
请求体

​
必传参数

​
channel_id
string
required
频道ID，不能为空或包含特殊字符
​
channel_type
integer
required
频道类型
  • 1 - 个人频道
  • 2 - 群组频道

​
可选参数

​
uids
array
要设置为黑名单的用户ID列表。如果为空，则清空整个黑名单。
​
uids[]
string
用户ID
curl -X POST "http://localhost:5001/channel/blacklist_set" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "group123",
    "channel_type": 2,
    "uids": ["user1", "user2", "user3"]
  }'

{
  "status": "ok"
}

​
响应字段

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

​
状态码

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

​
功能说明

​
设置操作

设置操作会执行以下步骤：
  1. 清除现有黑名单：删除频道的所有现有黑名单条目
  2. 添加新条目：将提供的用户ID列表添加到黑名单
  3. 删除会话：自动删除黑名单用户的相关会话
  4. 权限更新：立即生效，黑名单用户无法发送或接收消息

​
清空操作

当 uids 为空数组时：
  • 清除频道的所有黑名单条目
  • 恢复所有用户的正常权限
  • 不影响现有会话

​
黑名单机制

​
权限限制

黑名单用户受到以下限制：
限制说明影响范围
无法发送消息被阻止向频道发送任何消息所有消息类型
无法接收消息不会收到频道内的消息所有频道消息
会话删除相关会话被自动删除除直播频道外
权限剥夺失去所有频道相关权限完全隔离

​
特殊情况

  • 直播频道：不处理会话删除操作
  • 个人频道：不支持黑名单操作
  • 系统用户：可能有特殊权限，不受黑名单影响

​
使用场景

​
批量管理

# 设置新的黑名单，替换所有现有条目
curl -X POST "/channel/blacklist_set" -d '{
  "channel_id": "group123",
  "channel_type": 2,
  "uids": ["spammer1", "spammer2", "violator1"]
}'

​
清空黑名单

# 清空所有黑名单，恢复所有用户权限
curl -X POST "/channel/blacklist_set" -d '{
  "channel_id": "group123",
  "channel_type": 2,
  "uids": []
}'

​
重置黑名单

# 完全重置黑名单为新的用户列表
curl -X POST "/channel/blacklist_set" -d '{
  "channel_id": "group123",
  "channel_type": 2,
  "uids": ["new_blocked_user"]
}'

​
与其他黑名单操作的区别

操作功能适用场景
blacklist_add添加用户到现有黑名单增量添加违规用户
blacklist_set替换整个黑名单批量管理、重置黑名单
blacklist_remove从黑名单移除特定用户解除特定用户的限制

​
最佳实践

  1. 谨慎使用：设置操作会清除所有现有黑名单，确保这是预期行为
  2. 备份现有数据：在设置前获取当前黑名单列表作为备份
  3. 权限验证：确保操作者有足够的管理权限
  4. 日志记录：记录黑名单变更以便审计
  5. 通知机制：考虑通知相关管理员黑名单变更
  6. 测试验证：在生产环境使用前进行充分测试

​
错误处理

​
常见错误

错误信息原因解决方案
频道ID不能为空未提供频道ID确保提供有效的频道ID
频道类型不能为0频道类型无效使用有效的频道类型（1或2）
频道ID不能包含特殊字符频道ID格式无效使用字母数字和下划线
移除所有黑名单失败清除操作失败检查频道状态和权限
添加黑名单失败添加操作失败检查用户ID有效性

​
相关接口