vfs_plugin_deep_dive.md 23 KB

插件系统深度走读:以 vfs_plugin 为例

配套文档:docs/HANDOVER.md(系统全景)。本文聚焦"插件系统是怎么设计出来的",用 vfs 插件作为解剖样本。 行号引用:plugins/vfs_plugin.py(1466 行),框架侧引用 vs_plg.py / vs_plg_factory.py / sentinel.py / booker.py / standalone.py。


第一部分:插件系统是什么——三个文件、三个概念

整个插件系统只有三个核心文件,对应三个概念:契约(Interface)、工厂(Factory)、宿主(Host)。

vs_plg.py           契约:IVSPlg 抽象基类 —— 定义"一个签证插件长什么样"
vs_plg_factory.py   工厂:VSPlgFactory —— 定义"怎么把一个 .py 文件变成插件实例"
sentinel/booker/standalone.py   宿主:GCO —— 定义"什么时候调用插件的哪个方法"

1.1 契约:IVSPlg(vs_plg.py,94 行)

插件必须实现 8 个抽象方法,不多不少:

方法 语义 宿主什么时候调用
set_config(cfg) 注入配置(账号/代理/业务参数) 创建后立即
set_log(logger) 注入日志函数 创建后立即
create_session() 登录建会话;抛异常=失败 实例化时一次
query(apt_type) 查档期,返回 VSQueryResult 宿主循环反复调用
book(slot_info, user_inputs) 抢号,返回 VSBookResult 收到信号/命中档期时
keep_alive() 保活;不允许抛异常 周期调用
health_check() 健康探活,返回 bool;不允许抛异常 周期调用
cleanup() 释放资源(关浏览器/删文件) 任务销毁/组停止时

外加两个约定:

  • 类属性 name / version / description —— 这是插件的"身份证",utils/plugin_updater.py 用 AST 静态扫描(不 import、不执行代码)就能读到版本号做升级判断(plugin_updater.py:30-65)。
  • 可选方法 get_plugin_status() —— 返回运行状态快照,供状态上报。

为什么是这 8 个方法? 这是把"成千上万个具体签证网站"抽象成通用模式后的最小集合。观察所有签证预约网站:都要登录(会话)、都要查日期(查询)、都要填表提交(预订)、都要防掉线(保活)、都要判断登录是否过期(健康)、都要关浏览器(清理)。变化的(每个网站的协议细节)留给插件,不变的(生命周期节奏、配额、退避、信号、订单流转)留在宿主。 这就是框架开发的"抽象能力"——区分什么是变的、什么是不变的。

1.2 工厂:VSPlgFactory(vs_plg_factory.py,63 行)

register_plugin(plugin_name, module_path, class_name)  # 注册:名字 → 文件路径 + 类名
create(group_id, plugin_name) -> IVSPlg               # 动态加载并实例化

关键实现:importlib.util.spec_from_file_location 按文件路径加载,而不是普通 import(vs_plg_factory.py:41-48)。

为什么按路径加载而不是 import? 因为插件要支持热升级:

  1. 云端下发新版本 → 下载到 plugins/xxx.py(SHA256 校验 + py_compile 语法预检 + 原子替换,plugin_updater.py:117-170)
  2. 宿主把正在用旧代码的实例停掉,sys.modules.pop(plugin_name) 清掉模块缓存(main.py:90)
  3. 下次 create() 再加载时,读到的是磁盘上的新文件

如果插件是普通 import 的模块,sys.modules 缓存会让"升级"永远加载旧代码。按路径加载 + 显式清缓存,是热升级闭环的地基。

create() 里还有一个防御:实例化后强制 isinstance(instance, IVSPlg) 校验(vs_plg_factory.py:54-56),防止有人写了个"长得像插件但不是插件"的文件。

1.3 宿主:GCO 怎么驱动插件

以 Sentinel 为例,创建实例的完整链路(sentinel.py:246-298):

plg_cfg = VSPlgConfig()                    # 组装插件配置
plg_cfg.account = ...(从云端账号池取,带冷却)   # sentinel.py:261-262
plg_cfg.proxy = ...(从云端代理池取,带冷却)     # sentinel.py:264-266
instance = self.m_factory.create(group_id, plugin_name)  # 动态加载
instance.set_log(logger)
instance.set_config(plg_cfg)
instance.create_session()                  # 登录
task = Task(instance=instance, ...)        # 包进任务对象

之后 monitor 循环只做一件事:task.instance.query(apt_type)(sentinel.py:202)。发现档期 → 写 Redis 信号,插件对"信号/Redis/云端"一无所知。

Booker 侧多了 book():收到信号 → task.instance.book(query_result, user_inputs)(booker.py:388)。

设计亮点:宿主把插件当"黑盒工人",插件把宿主当"调度器"。 插件代码里你找不到任何 Redis 操作、找不到订单队列逻辑——这些全是宿主的事。职责边界清晰到可以各自独立演进:新增一种签证网站 = 新增一个插件文件,框架一行不改;宿主加新能力(比如心跳) = 所有插件自动受益。


第二部分:vfs_plugin 解剖——一个真实插件做了什么

VFS Global 是全球最大的签证外包商,它的预约系统是典型的 SPA(Angular 前端)+ 独立 API 域(lift-api.vfsglobal.com)+ Cloudflare 防护。这个插件就是和这套系统对抗的完整产物。

2.0 模块级工具(vfs_plugin.py:1-114)

工具 作用 为什么需要
VFS_PUBLIC_KEY_PEM VFS 的公钥(RSA) VFS 登录密码必须 RSA-OAEP 加密后传输(2.3 详述)
COUNTRY_MAP 国家名 → ISO3 代码 申请人 payload 里 nationalityCode 要 ISO3,用户输入的是英文名
get_alias_email() xxx@gmail.com → xxx@text.skin VFS 邮箱字段校验域名(防虚假邮箱),用别名规避
to_yyyymmdd() 日期格式转换 VFS 不同接口返回 MM/DD/YYYY / %m/%d/%Y %H:%M:%S 等多种格式,统一成 YYYY-MM-DD
BrowserResponse 模拟 requests.Response JS fetch 结果是个 dict,包装成类 Response 让上层代码像写普通 HTTP 客户端

2.1 init:每实例完全隔离

self.instance_id = uuid.uuid4().hex[:8]
self.root_workspace = "data/temp_browser_data/{group_id}.{instance_id}"
self.user_data_path = .../user_data

每个实例有独立的浏览器用户数据目录 + 独立 instance_id。 这是多实例并发的安全地基:Sentinel 一个组可以 spawn 多个 worker(target_instances),Booker 可能同时有 5 个实例,如果共享浏览器目录会互相踩 Cookie/锁文件。

set_config 里有个细节(vfs_plugin.py:155-159):free_config.country_code == 'chn' 时把 API 域名切到 lift-apicn.vfsglobal.com——中国区有独立 API 域名。业务配置(free_config)驱动行为差异,而不是写死在代码里,这是插件"一文件多场景"的关键。

2.2 create_session:四步建会话(vfs_plugin.py:201-373)

第 1 步:拉起浏览器(201-265)

  • 随机空闲 debug port(get_free_port()):DrissionPage 走 CDP(Chrome DevTools Protocol),多实例必须端口隔离。
  • 代理接入两种模式:
    • 账号密码代理 → 起 mihomo 隧道(MihomoTunnel):本地起一个 Clash Meta 实例,配置 exit_node=目标代理、可选随机 relay_node=中继节点(configure.MIHOMO_RELAY_NODES 随机选),浏览器只连本地 --proxy-server=127.0.0.1:随机端口。为什么这么绕? 直连代理容易被检测,mihomo 可以做链式路由(出口伪装 + 中继混淆),且每个实例独立隧道进程、独立端口,互不干扰(toolkit/mihomo_tunnel.py)。
    • 无密码代理 → 直接 --proxy-server={proto}://{ip}:{port}。
  • 反自动化参数:--disable-blink-features=AutomationControlled(去掉 navigator.webdriver 标志)、--no-sandbox、--disable-dev-shm-usage(容器内 /dev/shm 太小)、固定 1920x1080 视口。

第 2 步:过 Cloudflare 盾(278-325)

这是全插件最"硬核"的部分。VFS 登录页挂了 Cloudflare Turnstile(无感验证码),拿不到它的 token 就登录不了。

for i in range(40):                     # 最多等 40 秒
    time.sleep(1)
    ele = self.page.ele('@name=cf-turnstile-response', timeout=1)
    if ele and ele.value:               # 隐藏 input 里出现 token = 过盾成功
        cf_token = ele.value
        break
    if i > 2:
        cf_bypasser.click_verification_button(False)  # 主动点验证按钮

配套 CloudflareBypasser(utils/cloudflare_bypass_for_scraping.py)做两件事:

  • 递归钻 shadow DOM + iframe(search_recursively_shadow_root_with_iframe):Turnstile 组件是"shadow root 套 iframe 再套 shadow root"的俄罗斯套娃,必须一层层钻进去才能找到真正的验证按钮/输入框。
  • handle_waiting_room:VFS 高峰有"waiting room"排队页,检测到 file d'attente / waitting room 就每 10s 轮询,最多等 1 小时。

过盾后从隐藏 input 的 value 里提取 cf_token——Turnstile token 是登录请求的必填参数(captcha_api_key)。

第 3 步:JS fetch 登录(327-367)——本插件最核心的逆向成果

enc_password = self._encrypt_password(password)   # RSA-OAEP(SHA256) 加密
client_src = self._get_client_source()            # RSA("GA;{UTC时间戳}Z")
orange_src = self._get_orange_source(email)       # RSA("{email};{UTC时间戳}")
data = {
    "username": email,
    "password": enc_password,
    "captcha_version": "cloudflare-v1",
    "captcha_api_key": cf_token,                  # Turnstile token
    ...
}
resp = self._perform_request("POST", url, headers=headers, json_data=data)

三个逆向点:

  1. 密码 RSA-OAEP 加密(_encrypt_password,604-613):VFS 前端用公钥加密密码再 POST,cryptography 库复刻。
  2. 请求签名:clientsource = RSA 加密 "GA;{时间戳}Z",orangex = RSA 加密 "{email};{时间戳}"——这是 VFS 的反爬签名(防脚本调用 API),插件把签名算法逆向出来了。
  3. 登录走浏览器内 fetch 而非 requests(_perform_request,2.4 详述)——复用浏览器的 Cookie、TLS 指纹、UA、Origin。

OTP 分支(361-364 + 705-781):若账号开了二次验证,登录响应返回 enableOTPAuthentication:

  • 用云端邮件抓取 API(VSCloudApi.fetch_mail_content)读 VFS 发来的 OTP 邮件——不依赖本地邮箱客户端;
  • 先正则找 6 位数字;找不到(VFS 有时把 OTP 做成图片)→ base64 图片丢给 Qwen-VL 多模态大模型识别(toolkit/captcha_breaker.py:46-77,prompt 甚至知道"OTP 箭头指向的才是真验证码");
  • 重新过盾拿新 Turnstile token(_refresh_turnstile_token,783-822:清空 input → window.turnstile.reset() → 轮询新 token),带 otp 字段重新提交登录。

第 4 步:会话建立后(369-373)

  • 记录 session_create_time(供 health_check 判定会话寿命);
  • 开新标签页查 api.ipify.org 拿出口 IP(_get_realnetwork_ip,555-583)。为什么开新标签页而不是 fetch? 注释写得很清楚:Top-Level Navigation 不带 Origin 头也不带 credentials,符合 ipify 的 CORS 规则。这个 IP 后面会作为申请人 payload 的 ipAddress 字段——VFS 的风控会校验"填表 IP"和"实际 IP"是否一致,提前拿到可以防误杀。

2.3 _perform_request:插件的灵魂(397-526)

所有 API 调用(登录/查询/预订/保活)都走这一个方法,它干的事是:把 HTTP 请求翻译成一段 JS,注入浏览器执行 fetch,再把结果翻译回 BrowserResponse。

return fetch(url, options)          // credentials: "include" —— 自动带浏览器 Cookie
    .then(async response => { ... 把 status/body/headers 打包返回 ... })

为什么坚持用浏览器 fetch 而不是 requests? 三层原因:

  1. Cookie 自动携带:credentials: include,浏览器自动带上登录后的会话 Cookie/JWT 相关状态;
  2. 环境指纹一致:TLS 指纹、UA、Sec-CH-UA、Origin 全部是真实浏览器值——requests 的 TLS 指纹一眼假;
  3. CF 盾的延续:lift-api 域也受 Cloudflare 保护,用浏览器上下文发请求天然"过盾"。

代价是性能(每次请求一次 JS 注入 + 网络往返),但正确性优先。

错误处理是这套系统的精华——它把"反爬对抗"抽象成了标准 HTTP 语义:

状态码 插件动作 宿主动作(框架层)
401 is_healthy=False + 抛 SessionExpiredOrInvalidError 宿主销毁实例、重新 spawn(booker.py:498-502)
403 检测到 "Just a moment"(CF 盾)→ 自动重新过盾拿新 token → 递归重试(最多 3 次);否则抛 PermissionDeniedError 宿主退避
429 is_healthy=False + 抛 RateLimiteddError 宿主 30s 退避 + 云端锁账号(sentinel.py:281-289)
0(fetch 网络错误) 抛 BizLogicError 宿主重试

亮点:403 自动过盾重试(498-511)。请求打到一半被 CF 拦了,插件不慌:重置 Turnstile → 等新 token → 更新请求里的 captcha_api_key → 递归重发。这在抢号场景是生死攸关的——CF 盾可能随时插入,能自动恢复的抢号机才能活下来。

另外注意 debug 模式(435-489):完整打印每个请求的 Headers/Body 和响应,这是"逆向调参"时期的可观测性设计,生产关掉避免刷屏(这也是最近 commit 在清理的"verbose logs")。

2.4 query:查询链路(375-395 + 625-703)

apt_config = self.free_config["apt_configs"][routing_key]  # 业务配置:这个 routing_key 对应哪个中心/类别
self._fetch_configurations(apt_config)                     # 懒加载 master 数据
result = self._query_earliest_slot(apt_config)             # 查最早档期
  • _query_earliest_slot(625-646):POST CheckIsSlotAvailable → 响应含 "WaitList" 或 earliestSlotLists[0].date;
  • 结果归一化成 VSQueryResult(availability_status = Available / Waitlist / NoneAvailable 三态)——插件内部千奇百怪的响应,出插件必须是统一三态,这样宿主/信号/云端才能无脑消费。

_fetch_configurations(648-703)是性能设计:VFS 的 master 数据(中心列表 → 签证类别 → 子类别)要三级 API 才能拿到,但一个会话内基本不变,所以惰性加载 + 内存缓存(center_conf / category_conf / subcategory_conf),只查一次。_query_center 用的是 GET 无鉴权接口(678-684),连登录都不需要。

2.5 book:预订链路(824-992)——全插件最长的单方法

11 个步骤,按业务顺序:

  1. 日期偏好预检(837-842):expected_start/end 是订单用户填的期望区间,earliest_date 不在区间内直接放弃——避免无谓地消耗账号和触发风控。
  2. master 配置懒加载(849)。
  3. OCR 分支(854-860):如果该子类别 isOCREnable,先把护照照片上传(_upload_applicant_documents,1006-1044:支持 URL 下载或本地文件,base64 上传),拿到 GUID 等凭证,后面 payload 要用。
  4. 20 秒"冷静期"(867-870):booking_wait_applied 标志位保证每个插件实例只等一次——VFS 风控会抓"刚登录就抢号"的行为,先装一会儿人。硬编码 20s,见"风险"。
  5. 提交主申请人(875,_add_primary_applicant,1046-1165):构造一个 60+ 字段的 applicant payload——姓名全大写、生日转 DD/MM/YYYY、国家名转 ISO3、ipAddress 用真实出口 IP、referenceNumber 按子类别开关……全是逆向出来的"VFS 想要的格式"。成功后拿到 URN(预约单号)。失败重试 2 次,但 "Capping has exceeded"(当日预约上限)不重试(880-881)——识别"不可恢复错误"并立刻止损。
  6. 申请人 OTP(889-899):isApplicantOTPEnabled 子类别 → 发 OTP → 云邮件读 → 验证。注意 _applicant_otp_verify 给 header 加了 datacenter: GERMANY(1187)——逆向出的又一个隐藏要求。
  7. Waitlist 分流(901-908):如果查到的档期是 Waitlist,走 ConfirmWaitlist 接口直接确认,流程结束——不用选日期,因为日期不可选。
  8. 按月扫日历选日期(910-958):从 expected_start 到 expected_end 生成月份列表(_get_filtered_covered_months)→ 逐月 _query_slot_calendar 拿可预约日期 → 累积去重 → _filter_dates 过滤出区间内日期并 random.shuffle 打乱(防"每次都选同一天"的机器人特征)→ 对每个候选日期先 _saveuseractionaudit(VFS 要求的"用户操作审计"步骤,不调这个接口就选不了时间)→ _query_slot_time 拿时间段 → random.choice 随机选一个。
  9. 跳过增值服务 + 查费用(967-968):_submit_no_addition_service(/vas/mapvas,不选任何 VAS)→ _query_fee 拿金额和币种。
  10. 提交预订(971-976):/appointment/schedule,带 allocationId(选中时间段的 ID)和支付信息 → IsAppointmentBooked 判定成败。
  11. 支付链接解析(984-991):如需在线支付,_pay_request(1324-1348)开新标签页访问 VFS 支付组件,等 URL 跳转后把最终支付链接抓回来——返回给订单用户去付款,机器人不替用户付钱。

2.6 keep_alive / health_check(170-199)

def keep_alive(self):
    keep_alive_funcs = [self._get_application, self._query_center]
    random.choice(keep_alive_funcs)()   # 随机挑一个真实 API 打一下

亮点:保活不是发心跳包,而是随机执行一个真实业务 API。 既维持了会话活性,又模拟了真实用户行为(对风控更友好)。失败则 is_healthy=False。

health_check 三重判定:is_healthy 标志 + 页面 run_js("return 1;") 探活 + session_max_life 超时(超时返回 False,宿主重建会话)。两个方法都"不允许抛异常"——契约里写死的,因为宿主循环里任何异常都会打乱调度节奏。

2.7 cleanup / get_plugin_status(1407-1460)

  • cleanup:关浏览器 → 删临时目录(3 次重试) → 停 mihomo 隧道。抢号机跑久了会产生大量浏览器 profile(每个实例几十 MB),不删干净磁盘会爆;
  • get_plugin_status:把内部状态翻译成 PluginStatus(instance_id / account / proxy / current_url / session_age / state:running / logging_in / unhealthy)——宿主聚合后上报云端做监控大屏;
  • __del__ 兜底:对象被 GC 时也尝试清理(防异常路径泄漏)。

第三部分:为什么这么设计——设计哲学总结

  1. 契约是"最小共识":8 个方法恰好覆盖"任何签证网站都要做的事",多一个侵入、少一个残缺。插件作者只需要看 vs_plg.py 一个文件就能写插件——低门槛;而宿主通过异常体系(401/403/429)获得"通用决策能力"——高天花板。这就是"Low Floor, High Ceiling"。

  2. 控制反转:不是插件调用框架("我要查档期了"),而是框架调用插件("该你查了")。插件不知道 Redis、不知道订单队列、不知道信号,它只对 query/book 的入参出参负责。替换插件 = 替换工人,不换工厂。

  3. 对抗性设计内聚在插件里:反爬对抗(CF 过盾、RSA 签名、浏览器 fetch、拟人化等待)全部在插件内部消化,框架层的调度逻辑保持纯净、可测试。框架只依赖"插件会按契约工作"这个信念。

  4. 归一化接口:VFS 的三种档期状态(有/无/waitlist)→ 统一 AvailabilityStatus;千奇百怪的日期格式 → 统一 YYYY-MM-DD;浏览器 fetch 结果 → 统一 BrowserResponse。接口的稳定性就是插件的可替换性。

  5. 生产级资源管理:实例隔离(独立端口/独立目录)、原子清理、__del__ 兜底、内存缓存、失败重试带"不可恢复错误识别"——这些是"能长期跑"和"演示能跑"的分界线。


第四部分:亮点清单(vfs 插件值得抄作业的地方)

# 亮点 位置
1 403 自动过盾重试:请求被 CF 拦截后自动重置 Turnstile、换 token、递归重发,抢号机在盾前能自愈 498-511
2 逆向 VFS 请求签名:RSA-OAEP 加密的 clientsource/orangex 头 + 密码加密 604-623
3 保活 = 随机真实业务 API:既是心跳又是行为仿真 170-180
4 OTP 双通道读取:云邮件正文正则 → 失败再上 Qwen-VL 识图 705-737
5 master 配置惰性缓存:三级元数据只拉一次,会话内复用 648-703
6 风控前置:20s 冷静期(仅一次)、日期随机化、真实 IP 预取、审计步骤补齐 867/1376/555/1249
7 不可恢复错误识别:Capping has exceeded 不重试,止损 880-881
8 可观测性:debug 模式完整 TRAFFIC 日志 435-489
9 多态适配:Waitlist / OTP / OCR / 参考号,全部由子类别配置开关驱动,一个插件覆盖全球几十个中心 854/889/1136
10 实例级隔离 + 彻底清理:独立 profile、独立隧道、删除重试 144-150 / 1407-1434

第五部分:客观风险与可改进点(不做改动,仅记录)

  1. time.sleep(20) 硬编码(869):冷静期不可配置,改时长要改代码。建议进 free_config。
  2. master_email = "hujiarui8@gmail.com" 硬编码(707):读 OTP 邮件的"主邮箱"写死在代码里,换运营人就要改代码。建议进配置。
  3. 保活调用随机二选一(172-175):_query_center 是 GET 全量中心列表(较重的响应),高频随机到它浪费带宽。可换成更轻的接口。
  4. real_ip 获取失败 fallback 到代理 IP(373):代理 IP 与风控记录可能不符,极端情况会误伤账号。值得观察线上日志。
  5. OTP 图片识别依赖具体邮件模板:prompt 里写死"OTP 箭头指向的验证码"(captcha_breaker.py:53),VFS 改模板就失效——属"对抗的宿命",但要知道这个脆弱点。
  6. _perform_request 每次全量打印响应体(debug 模式):响应 1KB 截断打印,已比早期好,仍建议加开关。

附:如果你要新写一个插件(比如接一个新签证网站)

  1. 复制 prt_plugin.py(最小骨架)或参考 vfs_plugin.py 结构;
  2. 只实现 8 个契约方法,遵守两条铁律:keep_alive/health_check 不抛异常;create_session 失败抛异常;
  3. 业务差异全放 free_config(用 apt_configs 按 routing_key 给配置),不要写死任何中心/类别代码;
  4. 所有 HTTP 走 _perform_request 式浏览器 fetch(如果网站有反爬)或 requests(如果网站裸奔),但响应必须归一化成 VSQueryResult 三态;
  5. 上传到云端插件仓库 → 下发 → 节点秒级热升级,框架零改动。