# 插件系统深度走读:以 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 行) ```python 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`): ```python 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__:每实例完全隔离 ```python 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 就登录不了。 ```python 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)——本插件最核心的逆向成果 ```python 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`。 ```js 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) ```python 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) ```python 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. 上传到云端插件仓库 → 下发 → 节点秒级热升级,框架零改动。