跳转到主要内容
POST
/
channel
/
whitelist_set
curl -X POST "http://localhost:5001/channel/whitelist_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/whitelist_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/whitelist_set" -d '{
  "channel_id": "group123",
  "channel_type": 2,
  "uids": ["admin1", "admin2", "moderator1"]
}'

​
清空白名单

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

​
重置白名单

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

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

操作功能适用场景
whitelist_add添加用户到现有白名单增量添加特权用户
whitelist_set替换整个白名单批量管理、重置白名单
whitelist_remove从白名单移除特定用户移除特定用户的特权

​
权限层级

白名单在权限体系中的位置： 
系统用户 > 管理员 > 黑名单 > 白名单 > 普通用户

​
冲突处理

情况结果说明
同时在黑白名单按黑名单处理黑名单优先级更高
只在白名单享受白名单权限正常白名单用户
只在黑名单受黑名单限制正常黑名单用户
都不在名单普通用户权限按默认权限处理

​
最佳实践

  1. 谨慎使用：设置操作会清除所有现有白名单，确保这是预期行为
  2. 备份现有数据：在设置前获取当前白名单列表作为备份
  3. 权限验证：确保操作者有足够的管理权限
  4. 渐进式管理：对于大型频道，考虑渐进式白名单管理
  5. 监控效果：设置后监控频道活动和用户反馈
  6. 文档记录：记录白名单变更原因和预期效果

​
错误处理

​
常见错误

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

​
错误恢复策略

async function setWhitelistWithFallback(channelId, channelType, uids) {
  try {
    // 先备份当前白名单
    const currentWhitelist = await getCurrentWhitelist(channelId, channelType);
    
    // 执行设置操作
    const response = await fetch('/channel/whitelist_set', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        channel_id: channelId,
        channel_type: channelType,
        uids: uids
      })
    });
    
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}`);
    }
    
    return await response.json();
  } catch (error) {
    console.error('设置白名单失败，尝试恢复:', error);
    // 如果设置失败，尝试恢复原白名单
    if (currentWhitelist) {
      await restoreWhitelist(channelId, channelType, currentWhitelist);
    }
    throw error;
  }
}

​
监控和分析

​
性能指标

  • 白名单设置成功率
  • 操作响应时间
  • 用户活跃度变化
  • 消息发送量变化

​
分析维度

  • 白名单用户行为分析
  • 频道活跃度对比
  • 权限变更影响评估
  • 用户满意度调查

​
相关接口