设置频道白名单

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"]
  }'

curl -X POST "http://localhost:5001/channel/whitelist_set" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "group123",
    "channel_type": 2,
    "uids": []
  }'

// 设置白名单
const response = await fetch('http://localhost:5001/channel/whitelist_set', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    channel_id: 'group123',
    channel_type: 2,
    uids: ['user1', 'user2', 'user3']
  })
});

const data = await response.json();
console.log(data);

// 清空白名单
const clearResponse = await fetch('http://localhost:5001/channel/whitelist_set', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    channel_id: 'group123',
    channel_type: 2,
    uids: []
  })
});

import requests

# 设置白名单
data = {
    "channel_id": "group123",
    "channel_type": 2,
    "uids": ["user1", "user2", "user3"]
}

response = requests.post('http://localhost:5001/channel/whitelist_set', json=data)
result = response.json()
print(result)

# 清空白名单
clear_data = {
    "channel_id": "group123",
    "channel_type": 2,
    "uids": []
}

clear_response = requests.post('http://localhost:5001/channel/whitelist_set', json=clear_data)
clear_result = clear_response.json()
print(clear_result)

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    // 设置白名单
    data := map[string]interface{}{
        "channel_id":   "group123",
        "channel_type": 2,
        "uids":         []string{"user1", "user2", "user3"},
    }
    
    jsonData, _ := json.Marshal(data)
    
    resp, err := http.Post(
        "http://localhost:5001/channel/whitelist_set",
        "application/json",
        bytes.NewBuffer(jsonData),
    )
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()
    
    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    fmt.Printf("%+v\n", result)
    
    // 清空白名单
    clearData := map[string]interface{}{
        "channel_id":   "group123",
        "channel_type": 2,
        "uids":         []string{},
    }
    
    clearJsonData, _ := json.Marshal(clearData)
    
    clearResp, err := http.Post(
        "http://localhost:5001/channel/whitelist_set",
        "application/json",
        bytes.NewBuffer(clearJsonData),
    )
    if err != nil {
        panic(err)
    }
    defer clearResp.Body.Close()
    
    var clearResult map[string]interface{}
    json.NewDecoder(clearResp.Body).Decode(&clearResult)
    fmt.Printf("%+v\n", clearResult)
}

{
  "status": "ok"
}

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"]
  }'

curl -X POST "http://localhost:5001/channel/whitelist_set" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "group123",
    "channel_type": 2,
    "uids": []
  }'

// 设置白名单
const response = await fetch('http://localhost:5001/channel/whitelist_set', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    channel_id: 'group123',
    channel_type: 2,
    uids: ['user1', 'user2', 'user3']
  })
});

const data = await response.json();
console.log(data);

// 清空白名单
const clearResponse = await fetch('http://localhost:5001/channel/whitelist_set', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    channel_id: 'group123',
    channel_type: 2,
    uids: []
  })
});

import requests

# 设置白名单
data = {
    "channel_id": "group123",
    "channel_type": 2,
    "uids": ["user1", "user2", "user3"]
}

response = requests.post('http://localhost:5001/channel/whitelist_set', json=data)
result = response.json()
print(result)

# 清空白名单
clear_data = {
    "channel_id": "group123",
    "channel_type": 2,
    "uids": []
}

clear_response = requests.post('http://localhost:5001/channel/whitelist_set', json=clear_data)
clear_result = clear_response.json()
print(clear_result)

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    // 设置白名单
    data := map[string]interface{}{
        "channel_id":   "group123",
        "channel_type": 2,
        "uids":         []string{"user1", "user2", "user3"},
    }
    
    jsonData, _ := json.Marshal(data)
    
    resp, err := http.Post(
        "http://localhost:5001/channel/whitelist_set",
        "application/json",
        bytes.NewBuffer(jsonData),
    )
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()
    
    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    fmt.Printf("%+v\n", result)
    
    // 清空白名单
    clearData := map[string]interface{}{
        "channel_id":   "group123",
        "channel_type": 2,
        "uids":         []string{},
    }
    
    clearJsonData, _ := json.Marshal(clearData)
    
    clearResp, err := http.Post(
        "http://localhost:5001/channel/whitelist_set",
        "application/json",
        bytes.NewBuffer(clearJsonData),
    )
    if err != nil {
        panic(err)
    }
    defer clearResp.Body.Close()
    
    var clearResult map[string]interface{}
    json.NewDecoder(clearResp.Body).Decode(&clearResult)
    fmt.Printf("%+v\n", clearResult)
}

{
  "status": "ok"
}

概述

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

请求体

必传参数

string

必填

频道ID，不能为空或包含特殊字符

integer

必填

频道类型

1 - 个人频道
2 - 群组频道

可选参数

array

要设置为白名单的用户ID列表。如果为空，则清空整个白名单。

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"]
  }'

curl -X POST "http://localhost:5001/channel/whitelist_set" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "group123",
    "channel_type": 2,
    "uids": []
  }'

// 设置白名单
const response = await fetch('http://localhost:5001/channel/whitelist_set', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    channel_id: 'group123',
    channel_type: 2,
    uids: ['user1', 'user2', 'user3']
  })
});

const data = await response.json();
console.log(data);

// 清空白名单
const clearResponse = await fetch('http://localhost:5001/channel/whitelist_set', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    channel_id: 'group123',
    channel_type: 2,
    uids: []
  })
});

import requests

# 设置白名单
data = {
    "channel_id": "group123",
    "channel_type": 2,
    "uids": ["user1", "user2", "user3"]
}

response = requests.post('http://localhost:5001/channel/whitelist_set', json=data)
result = response.json()
print(result)

# 清空白名单
clear_data = {
    "channel_id": "group123",
    "channel_type": 2,
    "uids": []
}

clear_response = requests.post('http://localhost:5001/channel/whitelist_set', json=clear_data)
clear_result = clear_response.json()
print(clear_result)

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    // 设置白名单
    data := map[string]interface{}{
        "channel_id":   "group123",
        "channel_type": 2,
        "uids":         []string{"user1", "user2", "user3"},
    }
    
    jsonData, _ := json.Marshal(data)
    
    resp, err := http.Post(
        "http://localhost:5001/channel/whitelist_set",
        "application/json",
        bytes.NewBuffer(jsonData),
    )
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()
    
    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    fmt.Printf("%+v\n", result)
    
    // 清空白名单
    clearData := map[string]interface{}{
        "channel_id":   "group123",
        "channel_type": 2,
        "uids":         []string{},
    }
    
    clearJsonData, _ := json.Marshal(clearData)
    
    clearResp, err := http.Post(
        "http://localhost:5001/channel/whitelist_set",
        "application/json",
        bytes.NewBuffer(clearJsonData),
    )
    if err != nil {
        panic(err)
    }
    defer clearResp.Body.Close()
    
    var clearResult map[string]interface{}
    json.NewDecoder(clearResp.Body).Decode(&clearResult)
    fmt.Printf("%+v\n", clearResult)
}

{
  "status": "ok"
}

响应字段

string

必填

操作状态，成功时返回 "ok"

状态码

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

功能说明

设置操作

设置操作会执行以下步骤：

清除现有白名单：删除频道的所有现有白名单条目
添加新条目：将提供的用户ID列表添加到白名单
权限更新：立即生效，只有白名单用户可以发送消息（如果启用白名单模式）
会话管理：为个人频道自动创建相关会话

清空操作

当 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`	从白名单移除特定用户	移除特定用户的特权

权限层级

白名单在权限体系中的位置：

系统用户 > 管理员 > 黑名单 > 白名单 > 普通用户

冲突处理

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

最佳实践

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

错误处理

常见错误

错误信息	原因	解决方案
频道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;
  }
}

路由管理

消息管理

频道管理

用户管理

会话管理

连接管理

事件管理

监控

系统

集成接口

管理员

设置频道白名单

概述

请求体

必传参数

可选参数

响应字段

状态码

功能说明

设置操作

清空操作

白名单机制

权限特性

白名单模式

使用场景

批量管理

清空白名单

重置白名单

与其他白名单操作的区别

权限层级

冲突处理

最佳实践

错误处理

常见错误

错误恢复策略

监控和分析

性能指标

分析维度

相关接口

​概述

​请求体

​必传参数

​可选参数

​响应字段

​状态码

​功能说明

​设置操作

​清空操作

​白名单机制

​权限特性

​白名单模式

​使用场景

​批量管理

​清空白名单

​重置白名单

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

​权限层级

​冲突处理

​最佳实践

​错误处理

​常见错误

​错误恢复策略

​监控和分析

​性能指标

​分析维度

​相关接口

概述

请求体

必传参数

可选参数

响应字段

状态码

功能说明

设置操作

清空操作

白名单机制

权限特性

白名单模式

使用场景

批量管理

清空白名单

重置白名单

与其他白名单操作的区别

权限层级

冲突处理

最佳实践

错误处理

常见错误

错误恢复策略

监控和分析

性能指标

分析维度

相关接口