一、当前服务器地址
页面会使用你当前访问的 IP 或域名，并读取 app.conf 的实际端口。手机不能使用 127.0.0.1，因为手机上的该地址代表手机自己。
服务器部署时通常需要放行 API 端口 正在读取 和人脸代理端口 正在读取。WebSocket 端口仅在需要实时消息时放行。
WeChatPad Pro · 使用文档返回接口首页
PAD LOGIN AND FACE VERIFICATION
从获取 Pad 二维码到完成人脸验证
本教程按真实操作顺序说明 Access Token、Pad 取码、扫码确认、人脸验证、iPhone 与 Android 证书安装和代理设置。主程序会自动启动同目录的人脸代理，不需要用户再启动第二个程序。
二、开始前准备
| 设备 | 负责的操作 | 注意事项 |
|---|---|---|
| 电脑或管理端 | 打开 Swagger、填写 Access Token、获取 Pad 二维码、持续检测登录状态 | 页面不要关闭或刷新 |
| 授权扫码手机 | 使用要登录的微信扫描 Pad 登录二维码并确认 | 出现“在新设备完成验证”后保持该页面，不要退出 |
| 人脸验证手机 | 安装服务器 CA、设置 Wi-Fi 代理、打开人脸验证地址并完成人脸动作 | 建议与扫码手机分开，避免扫码等待页被关闭 |
只有一台手机时，切换页面可能中断扫码确认流程。需要人脸验证时优先准备第二台 iPhone 或 Android 手机。
- 已从个人中心取得有效 Access Token
- 服务器主程序已启动，Swagger 首页可以打开
- 人脸代理状态正常，默认监听 18080
- 验证手机与服务器网络可互通；公网部署时安全组已放行对应端口
三、获取 Pad 登录二维码
1
在接口首页设置凭证
打开 Swagger 首页，点击“设置凭证”，把个人中心生成的 Access Token 填入 Access Token 输入框并保存。网页会通过 X-Access-Token 请求头提交，避免把长期凭证写入 URL。
2
选择正确的 Pad 取码接口
普通 iPad 协议登录使用 POST /api/Login/GetQR。/GetQRPad 表示 Android Pad 协议，不是指“人脸验证手机使用 Android”。人脸验证手机是 iPhone 还是 Android，不会改变取码接口。
3
填写请求体并执行{
"DeviceName": "我的 iPad",
"oversea": false
}
Proxy 是微信上游网络代理，可不填；它和后面手机 Wi-Fi 中填写的人脸代理不是同一个概念。
4
用授权扫码手机扫描二维码
在要登录的微信中打开扫一扫，扫描电脑页面显示的二维码并确认。扫码后保持微信等待页面开启。
5
持续检测登录状态
Swagger 弹窗会自动检测，也可以调用 POST /api/Login/CheckQR?uuid=取码返回的UUID。继续使用获取二维码时的同一个 Access Token。
6
等待出现验证地址
当返回 requires_face_verification=true 且 ready=true 时，复制最新的 verification_url。每次登录生成的 challenge_id 都不同，旧地址在服务重启或超时后不能再用。
先选择验证手机系统
苹果和安卓的证书安装入口不同。请选择做人脸验证的手机系统，页面只显示对应步骤。
四、iPhone / iPad 验证手机设置
1. 下载并安装 CA
- 使用 Safari 打开当前服务器证书：wechatpadpro-ca.cer。
- 出现“已下载描述文件”后，进入“设置”。
- 打开“已下载描述文件”；如果没有该入口，进入“通用 → VPN 与设备管理”。
- 选择 WeChatPadPro CA，点击“安装”，按系统要求输入锁屏密码。
2. 开启完全信任
- 进入“设置 → 通用 → 关于本机”。
- 滑到最下方，打开“证书信任设置”。
- 为 WeChatPadPro CA 开启完全信任并确认。
3. 设置 Wi-Fi 代理
- 进入“设置 → 无线局域网”，点击当前 Wi-Fi 右侧的信息按钮。
- 打开“配置代理 → 手动”。
- 服务器填写 正在读取，端口填写 正在读取。
- 关闭“鉴定”，保存后返回。
服务器一栏只填 IP 或域名，不要填写 http://，也不要把端口写进服务器一栏。
五、Android 验证手机设置
1. 下载并安装 CA
- 使用 Chrome 或系统浏览器打开当前服务器证书：wechatpadpro-ca.cer。服务器会输出 Android 可直接安装的 DER X.509 格式。
- 进入“设置 → 安全”或“安全与隐私”。
- 找到“更多安全设置 → 加密与凭据 → 安装证书 → CA 证书”；不要选“VPN 和应用”或“Wi-Fi 证书”。
- 选择下载的
wechatpadpro-ca.cer，按系统提示确认安装；系统要求设置锁屏密码时需先完成设置。 - 安装后在“受信任的凭据 → 用户”中确认证书已出现。
2. 设置 Wi-Fi 代理
- 长按当前 Wi-Fi，选择“修改网络”；部分机型需点击 Wi-Fi 右侧设置按钮。
- 展开“高级选项”，把“代理”改为“手动”。
- 代理主机名填写 正在读取，代理端口填写 正在读取。
- 保存并重新连接该 Wi-Fi。
Android 7 及以上即使 CA 安装成功，部分应用仍会按自身网络安全策略拒绝用户 CA。遇到这种情况时，请改用能正常信任该 CA 的验证设备；不建议修改系统安全机制。
小米、华为、荣耀、OPPO、vivo、三星和原生 Android 的菜单名称不同，可在系统设置中搜索“安装证书”或“代理”。
六、打开验证地址并完成人脸
1
先测试代理和证书
在人脸验证手机的浏览器中打开一个普通 HTTPS 网站。若立即出现证书不受信任或完全无法加载，先不要进行验证，返回检查 CA 与 Wi-Fi 代理。
2
打开最新 verification_url
把链接发送到人脸验证手机，在手机微信内点击链接打开。不要让授权扫码手机再去扫描 PadFacePage 二维码，也不要手工修改 challenge_id。
3
按页面提示完成人脸动作
页面会自动续接服务器保存的 Pad 会话。若要求姓名或证件信息，只在当前验证页面填写；若检测为滑块，则按页面弹出的腾讯滑块完成操作。
4
等待 Pad 登录完成
人脸页面显示通过后不要立刻关闭扫码手机上的等待页。电脑端继续检测 CheckQR，直到返回登录成功和账号信息。
5
恢复手机网络设置
登录完成后把 Wi-Fi 代理改回“关闭/无”。CA 可以保留给同一服务器下次使用；如果服务器重新生成证书，则需要删除旧证书并安装新证书。
同一台服务器可以让多个用户安装同一张 WeChatPadPro CA，不需要每个用户生成不同证书。只有服务器证书文件发生变化时，设备才需要重新安装。
七、验证状态含义
| status | 说明 | 应该做什么 |
|---|---|---|
preparing_pad_session | 服务器正在准备 Pad 验证会话 | 保持扫码手机等待，稍后继续检测 |
awaiting_open | 验证地址已经生成，等待手机打开 | 在已配置 CA 和代理的人脸手机打开最新地址 |
awaiting_face | 等待完成人脸验证 | 按手机页面提示操作 |
awaiting_slider | 本次要求滑块而非人脸 | 打开验证页完成腾讯滑块 |
resuming_login | 验证已通过，微信正在确认 Pad 登录 | 不要重新取码，继续等待 CheckQR |
completed | 验证与 Pad 登录完成 | 关闭手机代理并开始调用业务接口 |
failed / expired | 验证失败或 challenge 已过期 | 重新调用 GetQR 获取新二维码和新地址 |
八、常见问题
证书链接打不开
确认手机访问的是当前页面显示的 API 地址，并检查服务器安全组、防火墙和容器网络是否允许 API 端口。证书不在旧的 18081 端口。
设置代理后所有网页都打不开
检查人脸代理端口是否启动、手机填写的服务器 IP 是否可达、服务器是否放行该端口。手机不能填 127.0.0.1。
验证页面一直转圈
通常是 CA 未完全信任、仍在使用旧证书、代理端口填错、challenge 已过期，或者在错误的手机/浏览器中打开。按本页顺序重新检查。
证书已安装仍提示不信任
iPhone 还必须单独开启“证书信任设置”；Android 要按 CA 证书类型安装，不能只作为 VPN/应用证书安装。
公网 IP 是否自动生成
默认按当前请求 Host 自动生成。经过域名、反向代理或多层网关时，建议在 app.conf 设置 pad_face_public_base_url 为手机实际可访问的固定地址。
九、服务自检
正在读取当前服务器地址主程序启动日志应显示人脸验证服务已启动。无需手工运行 pad-face-verify-*。
WebSocket 授权
浏览器先用 X-Access-Token 请求短时票据，再连接 /ws/sync?ticket=...。服务端程序可在 WebSocket 握手中直接发送 Authorization: Bearer ACCESS_TOKEN。旧的 ?authcode= 仍兼容，但不建议把长期凭证放入 URL、历史记录或代理日志。