行政同事第18次敲开我工位“访客又问WiFi密码了咱们那个新密码是多少来着”我翻聊天记录上一次改密码是两周前改完顺手发到对接群结果那串密码整层楼都传遍了连保洁阿姨都能背出来。这应该是很多行政和IT都经历过的循环密码写小纸条访客拍个照下个访客再用同一个密码最后半个行业都知道你办公室的网随便连。痛点是三重的访客体验差来了还要等人工给密码安全不可控蹭网的人多了带宽被拖垮出了事还查不到人日志里只有一串不知道为什么能连上来的IP。前两个月我终于把所有办公区的访客WiFi全部改成了扫码连WiFi模式用的正是公司已经在用的企业微信接完效果很理想行政再没来找我要过密码。后来我又把同样的思路在客户那边分别用飞书和钉钉各搭了一套也都跑通了。下面就把这三套打法完整写出来。不光是教你怎么扫个码而是把背后的认证链路、网关联动、访客授权、审计排查都讲清楚适合行政、IT运维、网管以及任何需要给会议室、前台、展厅做访客网络的人。1. 为什么办公室的WiFi总在密码和投诉之间反复横跳1.1 访客联网的真实痛点先别急着看代码得先把需求盘明白。我在好几个公司做过访客网络改造发现大家吐槽的点几乎一模一样固定密码一旦发给外部人员这个密码就再也收不回来了。访客拍张照下次不用问你直接能连甚至可能转发给他们的同事。纸质访客登记表基本流于形式登记了手机号也未必和上网行为关联出了问题根本定位不到是哪台设备、哪个人干的。大量访客集中在会议时间上网视频会议卡成PPT行政还找不到原因只能怪运营商。这些问题靠“定期改密码”解决不了因为改密码只会让行政和IT更忙访客更烦。真正要解决的是三件事第一访客能不能上网得有一个临时、受控的凭证第二谁连了网、什么时候连的、什么时候断开要有记录第三访客和内部员工的网络必须隔离访客网不能碰内网资源。扫码连WiFi这套方案恰好能把这三点一次做完。1.2 “扫码连WiFi”到底是怎么工作的先打破一个常见误会企业微信、飞书、钉钉本身并不会“放WiFi信号”它们只负责“确认你是谁”。真正放行网络的是你办公室里的无线AP、AC或者认证网关。我们做的事情是把“身份确认”和“网络放行”这两个环节接起来。一整套标准链路长这样访客手机连接访客SSID → 被Portal认证页面拦住 → 跳转到企业微信/飞书/钉钉的扫码授权页 → 访客扫码后平台确认身份 → 平台带着code回调我们自己的后端服务 → 后端校验这个人是内部员工还是访客 → 调用网关API下发网络放行指令 → 手机自动跳回原页面并上网。你可以把它想象成小区门禁WiFi网关是那道闸机企业微信/飞书/钉钉是个在线访客登记本我们自己写的后端服务是那个看到登记本才开闸的保安。闸机本身不关心你是谁它只认保安的指令。这样设计的优势很明显身份判断逻辑全部由我们自己的后端控制换平台只是换了一本“登记本”核心认证服务和网关对接完全不用重写。而且员工和访客的识别规则可以做得非常灵活比如市场部来访客户自动放行2小时面试候选人只放行到前台所在网段。2. 三个平台怎么选企业微信、飞书、钉钉的能力差异2.1 各自开放平台的切入点先说结论绝大多数公司不需要为了WiFi去更换办公平台哪个平台你们已经在用就优先用哪个。我用下来三家的能力是有差异的但都能覆盖扫码连WiFi的核心流程。企业微信的切入点是“微信生态”。来访客户十有八九有微信扫码授权几乎没有上手成本。企业微信后台的“自建应用”能拿到成员UserID配合通讯录标签可以快速区分员工和访客。这块文档最全历史案例最多遇到问题搜一搜基本都有答案。飞书的强项是“多维表格机器人”这套组合。访客扫码授权后后端可以把访客姓名、手机号、接入时间、MAC地址写进多维表格同时用机器人把“某总来了已经接入WiFi”这种消息推送给对应接待人。后续如果想把访客数据和AI知识库、低代码平台打通飞书这块的接口做得比较顺手。钉钉最突出的是“审批流”。如果你们公司对访客上网有严格的申请流程比如必须部门主管审批通过才放行钉钉的API和审批引擎是最成熟的。钉钉机器人做事件通知也很快很多网管会把无线AC的告警也一起推送到钉钉群统一在一个App里处理。2.2 用一张表把方案选型说清楚对比维度企业微信飞书钉钉认证方式OAuth2扫码授权OAuth2扫码授权OAuth2扫码授权用户标识UserIDopen_id / union_idunionId通讯录同步能力强支持部门标签强支持部门用户组强支持部门角色机器人能力群机器人应用消息机器人多维表格卡片群机器人工作通知二次开发语言任意官方有SDK任意官方有SDK任意官方有SDK最推荐场景客户来访多的公司重视数据沉淀、做访客台账审批流程严格的企业有一点必须提醒三家的开放平台接口都在迭代网上很多老教程里的URL已经失效。我下面给的地址和参数只做思路参考实际配置前一定要以“企业微信服务商文档”“飞书开放平台文档”“钉钉开放平台文档”当天显示的内容为准。尤其是企业微信这两年接口调整过好几次直接复制两年前博客里的代码会报错的。3. 企业微信扫码连WiFi落地实操保姆级步骤3.1 前置条件与整体流程企业微信这套是我最先跑通的原因很简单访客基本都有微信扫码体验最顺。开工之前你得准备这些东西一台或一套支持Portal认证的AP/AC/上网行为管理设备。主流厂商都有开放的认证接口或者支持对接第三方Radius/Portal服务器实在不行还有动态密码的兜底方案。一个公网可访问的域名强制HTTPS并且有正规证书。自签名证书在这个场景里基本可以放弃测试时还能凑合真实访客手机上会各种拦截。企业微信管理员后台权限能创建自建应用、配置可信域名和可信IP。一台能跑Python或者Node的小服务器用来写回调服务。公司没有公网服务器的话用一台海外云主机或者内网穿透都行但注意要稳定。整体流程我用一条线表示访客连SSID → Portal弹出页面 → 点“企业微信扫码登录” → 微信扫一扫 → 企业微信授权页确认 → 302带回授权code → 后端接收code换取UserID → 查通讯录判断身份 → 判断通过则调用网关API放行 → 手机自动上网。3.2 自建应用与可信域名配置登录企业微信管理后台找到“应用管理 → 自建 → 创建应用”填个名字比如“访客WiFi认证”然后进入应用详情页你会看到两个关键参数CorpID 和 Secret。CorpID 在“我的企业”里也能看到Secret 只在创建后展示一次没记住就重置。这俩相当于你应用的账号密码调用所有企业微信API都要用。接着配置“企业微信授权登录”功能填写可信域名。这个域名必须和你后面回调服务用同一个域名不能随便写。填完之后企业微微信会要求你下载一个校验文件放到服务器根目录保证通过https://你的域名/校验文件名.txt能访问到这一步是为了证明域名是你的不配置的话扫码授权会直接报“redirect_uri参数错误”或者白屏。还有一处不要漏企业微信API调用有IP白名单限制。在应用详情里的“企业可信IP”里把你后端服务器的公网出口IP填进去。否则后面调用 getUserInfo 之类的接口会报错提示“not allow to access from your ip”。我就因为这个卡了半小时明明参数都对结果就是拿不到用户信息。3.3 扫码授权与回调链路代码实现配置完成后访客扫码需要一个入口URL。企业微信的扫码授权本质上是构造一个授权链接然后引导访客在微信里打开。链接大概长这样https://open.weixin.qq.com/connect/oauth2/authorize?appidCORPIDredirect_urihttps%3A%2F%2Fwifi.example.com%2Fcallbackresponse_typecodescopesnsapi_basestatevisitor#wechat_redirect参数解读appid填企业微信的CorpID。redirect_uri扫码后用户同意授权企业微信回调到你后端的地址必须URL编码。response_type固定填code。scope填snsapi_base表示静默获取用户身份不需要用户手动输入手机号之类。state自定义参数回调时会原样带回用来标识是访客还是员工或者带上访客来的门禁编号。这个链接是给Portal认证页面用的。当访客连接WiFi并弹出认证页时认证页里放一个iframe或者整页跳转到这个链接就完成了“扫码授权”的入口。后端收到code之后需要用code换取用户的UserID。核心代码用Flask写很简单import requests from flask import Flask, request, redirect CORPID ww1234567890abcdef SECRET 你的应用Secret REDIRECT_URI https://wifi.example.com/callback app Flask(__name__) def get_access_token(): 获取调用企业微信API的access_token建议缓存不要每次请求都调用 url ( https://qyapi.weixin.qq.com/cgi-bin/gettoken f?corpid{CORPID}corpsecret{SECRET} ) r requests.get(url, timeout5).json() if r.get(errcode) ! 0: raise RuntimeError(r) return r[access_token] app.route(/) def index(): Portal认证页跳转过来的入口 target ( https://open.weixin.qq.com/connect/oauth2/authorize f?appid{CORPID} fredirect_uri{REDIRECT_URI} response_typecodescopesnsapi_base statevisitor#wechat_redirect ) return redirect(target) app.route(/callback) def callback(): 企业微信授权后的回调地址 code request.args.get(code) token get_access_token() r requests.get( https://qyapi.weixin.qq.com/cgi-bin/auth/getuserinfo, params{access_token: token, code: code}, timeout5, ).json() if r.get(errcode) ! 0: return f换取用户信息失败{r}, 400 userid r.get(userid) # 根据实际情况在这里判断 userid 是否在访客白名单分组中。 # 如果通过就调用网关API放行具体见下一节。 if userid: authorize_gateway(request.remote_addr, userid) return 认证成功稍后会自动联网 return 未识别到员工身份如需访客上网请联系前台, 403 def authorize_gateway(client_ip, userid): 调用网关API放行占位函数下一节实现 pass if __name__ __main__: app.run(host0.0.0.0, port8080)这里有几个坑是真实踩过的code一定要用一次就丢。企业微信的code一次性有效且有效期只有5分钟。拿同一个code连续换两次UserID第二次必失败。后端服务器系统时间要准。服务器时间偏差超过几分钟API调用会报认证失败用NTP同步一下就解决了。回调URL不要拼错。redirect_uri里的URL编码解码问题很常见尤其是域名带端口的情况容易被坑。3.4 联动认证网关下发WiFi凭证拿到身份只是第一步真正让访客手机能上网是把放行指令下发给认证网关。不同厂家的AC/网关API差别很大有的叫Portal认证接口有的叫免认证RADIUS有的支持OpenPortal标准协议。但业务逻辑都一样告诉网关“这个MAC地址/IP地址在哪个SSID下允许上网多长时间分到哪个VLAN”。我拿一个抽象接口做示例实际对接时替换成你家设备的真实API即可curl -X POST http://ac.example.internal/api/v1/portal/authorize \ -H Content-Type: application/json \ -d { client_mac: AA:BB:CC:00:11:22, client_ip: 10.10.10.88, ssid: Visitor, vlan: 20, bandwidth_down: 5, bandwidth_up: 2, expire: 2025-01-01T18:00:00Z, user: 张三, channel: wecom }参数里的几个关键项解释一下client_mac 和 client_ip 是访客手机在无线网络里的地址一般在Portal认证重定向时网关上前置参数里会带出来需要从前端授权入口那里取再原样传递到回调服务。vlan 是访客所在网段必须和办公网隔离开。如果你只开了一个访客SSIDVLAN直接沿用访客SSID的VLAN就行。bandwidth_down/up 是下行/上行的带宽上限单位Mbps。访客网建议下行5、上行2保证视频会议不卡但也不会有人拿访客网跑大流量。expire 填过期时间推荐统一给2小时到点自动断网避免“访客走了手机还挂在公司WiFi上”这种长期占用。如果你家的网关没有这种对外开放的API也有兜底方案后端在访客扫码成功后生成一个一次性动态密码并在页面上展示访客拿着这个密码去连那个需要密码的访客SSID。虽然没有那么自动化但至少解决了密码永久有效的问题。4. 飞书和钉钉的接入路线4.1 飞书扫码登录 多维表格访客登记 机器人通知飞书这套做下来体验感是三家里最好的。因为飞书后台做得很清爽权限配置也直白重点是可以把访客信息直接沉淀到多维表格对行政做月报、对账非常有用。先在飞书开放平台创建一个企业自建应用拿到 App ID 和 App Secret。在“安全设置”里配置重定向URL填你自己的回调地址比如https://wifi.example.com/feishu/callback。再在“权限管理”里开通contact:user.base:readonly和contact:user.employee_id:readonly不然拿不到用户信息。飞书的扫码授权链接格式https://accounts.feishu.cn/open-apis/authen/v1/index?app_idcli_xxxredirect_urihttps%3A%2F%2Fwifi.example.com%2Ffeishu%2Fcallbackstatevisitor后端拿到授权码之后用它换取user_access_tokencurl -X POST https://open.feishu.cn/open-apis/authen/v2/oauth/token \ -H Content-Type: application/json \ -d { grant_type: authorization_code, client_id: cli_xxx, client_secret: 你的应用Secret, code: 授权码, redirect_uri: https://wifi.example.com/feishu/callback }响应里会带access_token和open_id。然后用这个token去调用户信息接口就能拿到姓名、手机号这些字段用来判断是内部员工还是外部访客。飞书这套我做得比企业微信多一点访客认证成功后我会往一个叫“访客WiFi台账”的多维表格里写入一条记录字段包括访客姓名、手机号、接待人、接入时间、到期时间、MAC地址。同时用飞书机器人往行政群里推送一条消息类似“访客张总由市场部李雷接待已接入访客网络2小时”。这样前台不用时刻盯着后台也能知道谁来访了。这里有个额外技巧飞书机器人是可以发送“多维表格卡片”的直接把访客台账的视图分享到群里群成员点进去就能实时看到当前有哪些访客在线。飞书机器人的webhook还不受群里文件容量限制不像钉钉群发文件那样容易碰到钉盘容量不足的问题。4.2 钉钉小程序/扫码登录 钉钉机器人审批钉钉的接入思路和企业微信、飞书基本一致但它的组织架构权限控制更细。如果你希望访客联网必须走审批流钉钉是最合适的选择。在钉钉开放平台创建应用选择“扫码登录”能力拿到 AppKey 和 AppSecret新版里也叫 Client ID 和 Client Secret。然后在“安全设置”里配置回调域名和应用首页。拉起钉钉扫码的链接格式https://login.dingtalk.com/oauth2/auth?redirect_urihttps%3A%2F%2Fwifi.example.com%2Fdingtalk%2Fcallbackresponse_typecodeclient_id你的ClientIDscopeopenidstatevisitorpromptconsent回调后同样是用code换token再拿用户信息curl -X POST https://api.dingtalk.com/v1.0/oauth2/userAccessToken \ -H Content-Type: application/json \ -d { clientId: 你的ClientID, clientSecret: 你的ClientSecret, code: 授权码, grantType: authorization_code }拿到access_token后调用用户信息接口curl -X GET https://api.dingtalk.com/v1.0/contact/users/me \ -H x-acs-dingtalk-access-token: 上一步拿到的token这个接口会返回用户的unionId、昵称、手机号等信息。你可以根据手机号去钉钉通讯录里匹配匹配上了就是内部员工匹配不上就当作访客。钉钉这套我曾经帮一个客户做过进阶版访客扫码后不是直接放行而是生成一条待审批消息推送给接待人的部门主管。主管在钉钉里点“同意”后端才调用网关API下发放行指令。这样访客上网也有了和门禁一样的审批留痕符合他们公司的信息安全制度。钉钉机器人在这里除了发通知还能顺手把无线AC的告警一同推到群里很多运维同事会联动zabbix这类监控系统统一在钉钉里收告警。4.3 三个平台的对接差异总结对比项企业微信飞书钉钉扫码入口URL的hostopen.weixin.qq.comaccounts.feishu.cnlogin.dingtalk.com换取用户身份方式code换access_token再换useridcode换user_access_token再取open_idcode换user_access_token再取unionId内部员工识别查通讯录UserID查通讯录open_id按手机号/unionId匹配访客授权扩展标签分组多维表格台账审批流机器人常见坑可信域名/可信IP权限申请不生效回调域名需要备案校验如果你只是想让“扫码就能上网”三家的代码结构是高度相似的都是“构造扫码URL → 接收回调code → 换用户身份 → 调网关放行”。如果你想做得更深入建议优先考虑公司主力办公平台对应的生态把访客台账、审批、告警融入进去比单独做一个WiFi认证系统更有价值。5. 访客授权的高级技巧从“能联网”到“可管控”5.1 访客分组、限速与网段隔离很多公司做完扫码连WiFi就收工了但我强烈建议别停在这。扫码连上只是第一关真正要命的是访客网络的安全边界。访客网络必须和办公内网彻底隔离否则来访的人通过WiFi扫描到公司打印机、文件服务器那就是重大安全事故。具体做法是给访客单独划分一个VLAN。如果你的AP支持多SSID建议直接开一个叫“Visitor”或者“Guest”的独立SSID并把它绑定到访客VLAN。这个VLAN只允许访问公网内网网段全部ACL禁止。我自己在AC上做的是访客VLAN的ACL规则里只放行目的地址为公网的流量内网网段统一deny。限速也一定要做不然“一个访客用迅雷全公司视频会议卡成狗”这种事还会发生。网关或AC上可以给访客SSID挂一个带宽模板单用户下行带宽5 Mbps单用户上行带宽2 Mbps总并发用户数自动有需要可限制连接数这个数值是我实测过比较合适的视频会议和普通网页浏览都没问题同时不至于拖垮整个出口带宽。如果公司出口带宽比较大可以适当调到下行10但我建议别超过10访客网络本来就是临时通道无需追求速度。5.2 临时访客码、黑白名单与自动回收扫码连WiFi解决了“身份确认”的问题但没有解决“谁可以访问”的问题。很多公司希望访客不仅要扫码还要有内部接待人录入的预约单才放行。这时候可以做一个“临时访客码”功能访客扫码后页面要求输入一个6位数字临时码这个临时码由接待人在企业微信/飞书/钉钉里申请生成有效期4小时过期作废。访客只有同时完成扫码和输入正确临时码后端才调用网关放行。这样做的好处是外部访客就算拿到你的二维码没有临时码还是上不了网。对于面试候选人、临时快递员这类没有提前预约的人还可以在页面单独展示一个“前台人工审批”入口由前台在后台手动通过。黑白名单也要用起来白名单内部员工的手机MAC地址可以自动放行不走访客流程。黑名单出现过恶意扫描、暴力破解行为的MAC地址直接拒绝接入。自动回收是很多人忽略的重要功能。访客授权了2小时但人可能半小时就走了他的手机还会一直连着访客WiFi。建议写一个定时任务每10分钟扫一次当前网关上的在线用户把已过期的授权记录强制下线并更新台账状态。这个脚本用Python或者Shell写都行核心逻辑就是调网关API查在线列表对比过期时间超过就调下线接口。5.3 审计留痕出了问题查得到人扫码连WiFi如果只做到“方便”不做审计那这个方案是不完整的。万一访客网络里有人发起攻击、访问违规网站后台得能回答“谁、在哪、什么时候、做了什么”这四个问题。我建议至少记录这些字段访客姓名/手机号或者内部员工工号认证渠道企业微信/飞书/钉钉手机MAC地址分配到的IP地址认证时间、到期时间当天上下行流量可选尽量记录关联的接待人或审批单号企业微信、飞书、钉钉都有对应的日志接口可以把用户身份数据拉下来但网络侧的MAC、IP、流量数据在网关日志里。最省事的方案是在后端回调服务里打一条结构化日志同时写一份到本地数据库再配合网关自身的会话日志两边都能对得上号。还有一个合规小提醒访客个人信息属于敏感数据能脱敏就脱敏台账里手机号中间4位打星号。别把访客信息当成普通Excel乱发出了问题大家都不好交代。6. 常见问题与排查实录6.1 扫码白屏、code失效、回调不通我把这段时间被问得最多的问题整理一下基本都是配置层面的坑。扫码后白屏九成是可信域名问题。企业微信和飞书都有域名校验校验文件必须能通过公网访问到且必须和你填的回调域名完全一致包括协议、域名、端口一个都不能差。我用飞书对接时一开始重定向URL里带了端口号飞书文档要求不能带端口改掉就通了。code失效大部分原因是代码被打过高并发或者调试时重复使用了一个code。三家的code都是“一次性”的拿一次以后就作废而且有效期只有几分钟。你如果在前端页面上刷新了一次后端的同一个code就会失效。解决办法很简单每次回调进来都生成新的code前端不要重复提交。回调不通先测网络层。后端服务器能不能访问到企业微信/飞书/钉钉的API域名中间有没有防火墙拦截如果后端在办公内网而公网请求转发不过来大概率是NAT或防火墙规则没放行。还有企业微信后台的可信IP务必把后端服务器公网出口IP加进去否则API会返回IP白名单校验失败。别问我怎么知道的问就是被坑过。6.2 平台版本与通知通道的坑有人问我公司电脑装的是麒麟系统企业微信客户端版本太旧扫码这个流程会不会受影响。这里可以放心扫码连WiFi的核心完全跑在浏览器和后端服务上访客拿来扫码的也是手机微信或企业微信App跟办公电脑上的客户端版本没关系。只要后端服务能正常对外提供回调接口PC端用什么系统都不影响。通知通道方面我的建议是别用“群文件”来通知访客状态。钉钉群里发文件会占钉盘容量我们之前有一段时间用机器人自动发访客Excel表到群里结果钉盘满了群文件发不出去大家还以为是网络问题。后来全改成机器人消息卡片纯文本或者图文卡片走webhook不占钉盘群成员也能在群里直接看到每天访客统计。飞书这边同理用多维表格卡片分享比发文件体验好太多。还有一个容易踩的坑是机器人自定义关键词。钉钉和飞书的自定义机器人都要求发送的消息里包含至少一个安全设置的关键词或者配置加签、IP白名单。否则机器人消息发不出去。对接的时候记得在机器人安全设置里加一个唯一关键词比如公司名缩写然后在消息内容里带上。最后提醒一句不要为了图省事去用非官方手段做自动化比如虚拟定位打卡、多开客户端、外挂脚本这类东西。正规的办公场景就用官方API稳定、合规、不给自己挖坑。6.3 一款只能靠踩坑换来的自查清单按照下面这个清单从上到下检查一遍能解决绝大部分部署问题检查项检查点常见问题域名与证书公网能否访问HTTPS证书是否有效白屏、浏览器拦截平台域名校验校验文件是否放在服务器根目录配置不可用回调地址是否与平台填写的redirect_uri完全一致code回调丢失后端服务器是否在平台配置了可信IPAPI报IP不在白名单网关对接网关API是否能从后端内网访问放行指令超时VLAN隔离访客是否能访问内网地址安全风险限速配置访客带宽是否存在超限办公网络被拖垮审计日志是否记录了MAC、IP、时间、用户出问题无法溯源我每到一个新项目现场都是先拿着一台测试手机完整走一遍“连SSID → 扫码 → 上网 → 断网”全流程再从后台日志核对每个环节的时间点。这样比翻十篇文档都管用。7. 写在最后一点个人实操心得做完这么多套扫码连WiFi之后我最大的感受是技术难点其实不在API对接而在需求梳理。你先想清楚“谁是访客”“访客能访问什么”“出了问题找谁”再去选平台、写代码、调网关整个流程会顺畅很多。我建议所有刚准备动手的人先别直接上生产环境。找一个会议室单独开一个访客SSID用测试账号跑通整个流程观察两天日志确认没有异常后再推广到全公司。推广的时候也别忘了行政和前台需要一套简单的后台操作入口你总不能让他们每次都来找你手动审批。另外如果你们公司已经有访客预约系统完全可以把这个扫码连WiFi做成它的一个子模块访客在预约时填写手机号到公司后扫码自动匹配预约单匹配上了就直接放行。这样访客从进大门到连上网全程不用人工干预行政也彻底从“我要WiFi密码”的噩梦里解放出来。我现在再听到“访客WiFi密码是多少”这句话已经可以很自然地回答“你扫一下前台那个二维码就行。”后台会自动告诉网关让他在这个下午的两小时里安静地上网。这个感觉挺值的。