本文档详细说明企业微信 Python 插件的访问控制策略配置帮助开发者根据实际需求灵活配置机器人的访问权限。 目录策略概述DM私聊策略群聊策略配置示例获取用户ID和群ID策略选择指南常见问题策略概述企业微信机器人插件提供了两个维度的访问控制DM 策略dmPolicy- 控制私聊消息的访问权限群聊策略groupPolicy- 控制群聊消息的访问权限通过合理配置这两个策略可以实现精细化的权限管理确保机器人只响应授权用户或群组的消息。DM私聊策略策略类型1. pairing - 配对模式工作原理用户首次发送消息时需要进行配对配对成功后该用户可以继续与机器人交互适合需要用户主动激活的场景配置示例channels:wecom:botId:your_bot_idsecret:your_secretdmPolicy:pairingallowFrom:[]# 配对模式不需要预设白名单使用场景企业内部机器人需要用户主动激活需要记录使用者信息的场景防止未授权访问注意事项当前实现为简化版本实际使用时需要实现配对逻辑建议在数据库中记录已配对的用户列表2. open - 开放模式工作原理所有用户都可以直接与机器人私聊无需任何授权或配对最宽松的访问策略配置示例channels:wecom:botId:your_bot_idsecret:your_secretdmPolicy:openallowFrom:[]# 开放模式不需要白名单使用场景公共服务机器人如查询、帮助类企业内部通用工具测试和开发阶段优点配置简单无需维护白名单用户体验好即开即用缺点无法限制访问者可能被滥用3. allowlist - 白名单模式工作原理只有在白名单中的用户可以与机器人私聊其他用户的消息会被忽略提供最严格的访问控制配置示例channels:wecom:botId:your_bot_idsecret:your_secretdmPolicy:allowlistallowFrom:-user_id_1-user_id_2-user_id_3使用场景管理员专用机器人敏感操作机器人如审批、配置特定团队或项目使用优点安全性高精确控制访问权限防止未授权访问缺点需要手动维护白名单添加新用户需要修改配置最佳实践# 动态管理白名单classDynamicAccessController:def__init__(self):self.whitelistset()defadd_user(self,user_id:str):添加用户到白名单self.whitelist.add(user_id)defremove_user(self,user_id:str):从白名单移除用户self.whitelist.discard(user_id)defis_allowed(self,user_id:str)-bool:检查用户是否在白名单中returnuser_idinself.whitelist4. disabled - 禁用模式工作原理完全禁用私聊功能机器人不会响应任何私聊消息只能在群聊中使用配置示例channels:wecom:botId:your_bot_idsecret:your_secretdmPolicy:disabledallowFrom:[]# 禁用模式不需要白名单使用场景纯群聊机器人如群管理、公告发布防止私聊干扰强制用户在群内交互优点避免私聊消息干扰所有交互公开透明缺点无法处理私密请求用户体验可能受影响群聊策略策略类型1. open - 开放模式工作原理机器人可以在所有群聊中使用无需配置群聊白名单最宽松的群聊策略配置示例channels:wecom:botId:your_bot_idsecret:your_secretgroupPolicy:opengroupAllowFrom:[]# 开放模式不需要白名单使用场景通用服务机器人企业内部广泛使用的工具测试和开发阶段优点配置简单可以在任何群聊中使用缺点无法限制使用范围可能在不相关的群中被误用2. allowlist - 白名单模式工作原理只在指定的群聊中响应消息其他群聊的消息会被忽略精确控制机器人的使用范围配置示例channels:wecom:botId:your_bot_idsecret:your_secretgroupPolicy:allowlistgroupAllowFrom:-group_id_1-group_id_2-group_id_3使用场景特定项目或团队的机器人需要限制使用范围的场景付费或授权使用的机器人优点精确控制使用范围避免在无关群聊中被使用缺点需要手动维护群聊白名单添加新群需要修改配置获取群ID方法defon_message(msg:WeComMessage):ifmsg.chat_typegroup:print(f群聊ID:{msg.chat_id})print(f群聊名称: 需要从企业微信API获取)3. disabled - 禁用模式工作原理完全禁用群聊功能机器人不会响应任何群聊消息只能在私聊中使用配置示例channels:wecom:botId:your_bot_idsecret:your_secretgroupPolicy:disabledgroupAllowFrom:[]# 禁用模式不需要白名单使用场景纯私聊机器人如个人助手敏感操作机器人避免群聊干扰优点专注于一对一服务避免群聊消息干扰缺点无法在群聊中使用限制了使用场景配置示例示例 1完全开放测试环境适用于开发和测试阶段所有用户和群聊都可以使用。channels:wecom:botId:your_bot_idsecret:your_secretdmPolicy:openallowFrom:[]groupPolicy:opengroupAllowFrom:[]特点无任何限制快速测试功能不适合生产环境示例 2严格限制生产环境适用于生产环境只允许特定用户和群聊使用。channels:wecom:botId:your_bot_idsecret:your_secretdmPolicy:allowlistallowFrom:-admin_user_1-admin_user_2groupPolicy:allowlistgroupAllowFrom:-project_group_1-team_group_1特点安全性高精确控制访问权限需要维护白名单示例 3仅群聊模式适用于群管理、公告发布等场景。channels:wecom:botId:your_bot_idsecret:your_secretdmPolicy:disabledallowFrom:[]groupPolicy:opengroupAllowFrom:[]特点只在群聊中工作避免私聊干扰适合公共服务示例 4仅私聊模式适用于个人助手、敏感操作等场景。channels:wecom:botId:your_bot_idsecret:your_secretdmPolicy:openallowFrom:[]groupPolicy:disabledgroupAllowFrom:[]特点只在私聊中工作一对一服务隐私性好示例 5配对模式推荐适用于需要用户主动激活的场景。channels:wecom:botId:your_bot_idsecret:your_secretdmPolicy:pairingallowFrom:[]groupPolicy:allowlistgroupAllowFrom:-official_group_1-official_group_2特点私聊需要配对群聊限制在指定群组平衡安全性和易用性获取用户ID和群ID方法 1从日志中获取启动机器人后当用户发送消息时日志会显示相关信息defon_message(msg:WeComMessage):logger.info(f收到消息:)logger.info(f - 用户ID:{msg.from_user_id})logger.info(f - 用户名:{msg.from_user_name})logger.info(f - 会话类型:{msg.chat_type})logger.info(f - 会话ID:{msg.chat_id})方法 2打印原始消息体defon_message(msg:WeComMessage):importjsonprint(json.dumps(msg.raw_body,indent2,ensure_asciiFalse))方法 3使用企业微信管理后台登录企业微信管理后台进入通讯录查看成员信息成员详情中可以看到用户ID群聊ID需要通过API或日志获取示例输出{msgid:msg_123456,msgtype:text,chattype:single,from:{userid:zhangsan,name:张三},chatid:group_abc123,text:{content:你好}}从上面的输出可以得到用户ID:zhangsan群ID:group_abc123如果是群聊策略选择指南决策矩阵场景DM 策略群聊策略说明开发测试openopen快速测试无限制公共服务openopen面向所有用户团队工具allowlistallowlist限定团队使用管理工具allowlistdisabled仅管理员私聊群管理disabledallowlist仅在指定群使用个人助手pairingdisabled一对一服务安全性考虑高安全性场景使用allowlist模式定期审查白名单记录所有操作日志中等安全性场景使用pairing模式实现配对审批流程监控异常行为低安全性场景使用open模式适合公共服务注意防止滥用实际应用建议阶段 1开发测试dmPolicy:opengroupPolicy:open阶段 2内部测试dmPolicy:allowlistallowFrom:[tester1,tester2]groupPolicy:allowlistgroupAllowFrom:[test_group]阶段 3生产环境dmPolicy:pairing# 或 allowlistgroupPolicy:allowlistgroupAllowFrom:[official_group_1,official_group_2]常见问题Q1: 白名单为空时会发生什么A:如果策略设置为allowlist但白名单为空机器人将不会响应任何消息。# 错误配置示例dmPolicy:allowlistallowFrom:[]# 空白名单无人可以使用解决方案确保白名单中至少有一个用户/群ID或者改用open模式Q2: 如何动态修改白名单A:有两种方法方法 1修改配置文件后重启# 修改 config.yamlvimconfig.yaml# 重启机器人python src/main.py--configconfig.yaml方法 2实现动态白名单管理classDynamicWeComPlugin(WeComPlugin):def__init__(self,config:WeComConfig):super().__init__(config)self.dynamic_whitelistset(config.allow_from)defadd_to_whitelist(self,user_id:str):动态添加用户到白名单self.dynamic_whitelist.add(user_id)logger.info(f已添加用户到白名单:{user_id})defremove_from_whitelist(self,user_id:str):从白名单移除用户self.dynamic_whitelist.discard(user_id)logger.info(f已从白名单移除用户:{user_id})def_handle_message(self,msg:WeComMessage):# 使用动态白名单检查ifmsg.chat_typesingle:ifself.config.dm_policyallowlist:ifmsg.from_user_idnotinself.dynamic_whitelist:returnsuper()._handle_message(msg)Q3: pairing 模式如何实现配对逻辑A:当前实现为简化版本完整的配对逻辑需要classPairingController:def__init__(self):self.paired_usersset()self.pending_pairs{}defrequest_pairing(self,user_id:str)-str:用户请求配对codeself.generate_pairing_code()self.pending_pairs[code]user_idreturncodedefconfirm_pairing(self,code:str)-bool:管理员确认配对ifcodeinself.pending_pairs:user_idself.pending_pairs.pop(code)self.paired_users.add(user_id)returnTruereturnFalsedefis_paired(self,user_id:str)-bool:检查用户是否已配对returnuser_idinself.paired_usersdefgenerate_pairing_code(self)-str:生成配对码importrandomimportstringreturn.join(random.choices(string.ascii_uppercasestring.digits,k6))Q4: 如何实现基于角色的访问控制A:可以扩展访问控制器classRoleBasedAccessController(AccessController):def__init__(self,config:WeComConfig):super().__init__(config)self.user_roles{admin_user_1:admin,user_1:member,user_2:guest}defhas_permission(self,user_id:str,required_role:str)-bool:检查用户是否有指定角色权限user_roleself.user_roles.get(user_id,guest)role_hierarchy{admin:3,member:2,guest:1}returnrole_hierarchy.get(user_role,0)role_hierarchy.get(required_role,0)Q5: 群聊中如何限制特定成员A:可以实现群成员白名单classGroupMemberController:def__init__(self):self.group_member_whitelist{group_1:[user_1,user_2],group_2:[user_3,user_4]}defis_member_allowed(self,group_id:str,user_id:str)-bool:检查群成员是否在白名单中ifgroup_idnotinself.group_member_whitelist:returnTrue# 群没有限制允许所有成员returnuser_idinself.group_member_whitelist[group_id]Q6: 如何记录访问日志A:实现访问日志记录importloggingfromdatetimeimportdatetimeclassAccessLogger:def__init__(self,log_file:straccess.log):self.loggerlogging.getLogger(access)handlerlogging.FileHandler(log_file)handler.setFormatter(logging.Formatter(%(asctime)s - %(message)s))self.logger.addHandler(handler)self.logger.setLevel(logging.INFO)deflog_access(self,msg:WeComMessage,allowed:bool):记录访问日志statusALLOWEDifallowedelseDENIEDself.logger.info(f{status}- User:{msg.from_user_id}, fChat:{msg.chat_type}, fContent:{msg.content[:50]})Q7: 策略冲突如何处理A:策略优先级disabled优先级最高 - 直接拒绝allowlist次之 - 检查白名单pairing再次 - 检查配对状态open优先级最低 - 允许所有defcheck_access(self,msg:WeComMessage)-bool:检查访问权限按优先级ifmsg.chat_typesingle:policyself.config.dm_policy# 1. 检查是否禁用ifpolicydisabled:returnFalse# 2. 检查白名单ifpolicyallowlist:returnmsg.from_user_idinself.config.allow_from# 3. 检查配对状态ifpolicypairing:returnself.is_paired(msg.from_user_id)# 4. 开放模式returnTrue# 群聊逻辑类似returnTrue总结访问控制策略是企业微信机器人安全性的重要组成部分。合理配置策略可以提高安全性- 防止未授权访问优化体验- 为不同用户提供合适的访问方式便于管理- 集中管理访问权限灵活扩展- 支持自定义访问控制逻辑建议根据实际需求选择合适的策略组合并在不同阶段调整配置以平衡安全性和易用性。文档版本1.0最后更新2026-03-19维护者WeComPlugin Team