配套文档:
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 —— 定义"什么时候调用插件的哪个方法"
插件必须实现 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 个方法? 这是把"成千上万个具体签证网站"抽象成通用模式后的最小集合。观察所有签证预约网站:都要登录(会话)、都要查日期(查询)、都要填表提交(预订)、都要防掉线(保活)、都要判断登录是否过期(健康)、都要关浏览器(清理)。变化的(每个网站的协议细节)留给插件,不变的(生命周期节奏、配额、退避、信号、订单流转)留在宿主。 这就是框架开发的"抽象能力"——区分什么是变的、什么是不变的。
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? 因为插件要支持热升级:
plugins/xxx.py(SHA256 校验 + py_compile 语法预检 + 原子替换,plugin_updater.py:117-170)sys.modules.pop(plugin_name) 清掉模块缓存(main.py:90)create() 再加载时,读到的是磁盘上的新文件如果插件是普通 import 的模块,sys.modules 缓存会让"升级"永远加载旧代码。按路径加载 + 显式清缓存,是热升级闭环的地基。
create() 里还有一个防御:实例化后强制 isinstance(instance, IVSPlg) 校验(vs_plg_factory.py:54-56),防止有人写了个"长得像插件但不是插件"的文件。
以 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 Global 是全球最大的签证外包商,它的预约系统是典型的 SPA(Angular 前端)+ 独立 API 域(lift-api.vfsglobal.com)+ Cloudflare 防护。这个插件就是和这套系统对抗的完整产物。
| 工具 | 作用 | 为什么需要 |
|---|---|---|
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 客户端 |
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)驱动行为差异,而不是写死在代码里,这是插件"一文件多场景"的关键。
get_free_port()):DrissionPage 走 CDP(Chrome DevTools Protocol),多实例必须端口隔离。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 视口。这是全插件最"硬核"的部分。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)做两件事:
search_recursively_shadow_root_with_iframe):Turnstile 组件是"shadow root 套 iframe 再套 shadow root"的俄罗斯套娃,必须一层层钻进去才能找到真正的验证按钮/输入框。file d'attente / waitting room 就每 10s 轮询,最多等 1 小时。过盾后从隐藏 input 的 value 里提取 cf_token——Turnstile token 是登录请求的必填参数(captcha_api_key)。
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)
三个逆向点:
_encrypt_password,604-613):VFS 前端用公钥加密密码再 POST,cryptography 库复刻。clientsource = RSA 加密 "GA;{时间戳}Z",orangex = RSA 加密 "{email};{时间戳}"——这是 VFS 的反爬签名(防脚本调用 API),插件把签名算法逆向出来了。_perform_request,2.4 详述)——复用浏览器的 Cookie、TLS 指纹、UA、Origin。OTP 分支(361-364 + 705-781):若账号开了二次验证,登录响应返回 enableOTPAuthentication:
VSCloudApi.fetch_mail_content)读 VFS 发来的 OTP 邮件——不依赖本地邮箱客户端;toolkit/captcha_breaker.py:46-77,prompt 甚至知道"OTP 箭头指向的才是真验证码");_refresh_turnstile_token,783-822:清空 input → window.turnstile.reset() → 轮询新 token),带 otp 字段重新提交登录。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"是否一致,提前拿到可以防误杀。所有 API 调用(登录/查询/预订/保活)都走这一个方法,它干的事是:把 HTTP 请求翻译成一段 JS,注入浏览器执行 fetch,再把结果翻译回 BrowserResponse。
return fetch(url, options) // credentials: "include" —— 自动带浏览器 Cookie
.then(async response => { ... 把 status/body/headers 打包返回 ... })
为什么坚持用浏览器 fetch 而不是 requests? 三层原因:
credentials: include,浏览器自动带上登录后的会话 Cookie/JWT 相关状态;Sec-CH-UA、Origin 全部是真实浏览器值——requests 的 TLS 指纹一眼假;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")。
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),连登录都不需要。
11 个步骤,按业务顺序:
expected_start/end 是订单用户填的期望区间,earliest_date 不在区间内直接放弃——避免无谓地消耗账号和触发风控。isOCREnable,先把护照照片上传(_upload_applicant_documents,1006-1044:支持 URL 下载或本地文件,base64 上传),拿到 GUID 等凭证,后面 payload 要用。booking_wait_applied 标志位保证每个插件实例只等一次——VFS 风控会抓"刚登录就抢号"的行为,先装一会儿人。硬编码 20s,见"风险"。_add_primary_applicant,1046-1165):构造一个 60+ 字段的 applicant payload——姓名全大写、生日转 DD/MM/YYYY、国家名转 ISO3、ipAddress 用真实出口 IP、referenceNumber 按子类别开关……全是逆向出来的"VFS 想要的格式"。成功后拿到 URN(预约单号)。失败重试 2 次,但 "Capping has exceeded"(当日预约上限)不重试(880-881)——识别"不可恢复错误"并立刻止损。isApplicantOTPEnabled 子类别 → 发 OTP → 云邮件读 → 验证。注意 _applicant_otp_verify 给 header 加了 datacenter: GERMANY(1187)——逆向出的又一个隐藏要求。ConfirmWaitlist 接口直接确认,流程结束——不用选日期,因为日期不可选。expected_start 到 expected_end 生成月份列表(_get_filtered_covered_months)→ 逐月 _query_slot_calendar 拿可预约日期 → 累积去重 → _filter_dates 过滤出区间内日期并 random.shuffle 打乱(防"每次都选同一天"的机器人特征)→ 对每个候选日期先 _saveuseractionaudit(VFS 要求的"用户操作审计"步骤,不调这个接口就选不了时间)→ _query_slot_time 拿时间段 → random.choice 随机选一个。_submit_no_addition_service(/vas/mapvas,不选任何 VAS)→ _query_fee 拿金额和币种。/appointment/schedule,带 allocationId(选中时间段的 ID)和支付信息 → IsAppointmentBooked 判定成败。_pay_request(1324-1348)开新标签页访问 VFS 支付组件,等 URL 跳转后把最终支付链接抓回来——返回给订单用户去付款,机器人不替用户付钱。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,宿主重建会话)。两个方法都"不允许抛异常"——契约里写死的,因为宿主循环里任何异常都会打乱调度节奏。
cleanup:关浏览器 → 删临时目录(3 次重试) → 停 mihomo 隧道。抢号机跑久了会产生大量浏览器 profile(每个实例几十 MB),不删干净磁盘会爆;get_plugin_status:把内部状态翻译成 PluginStatus(instance_id / account / proxy / current_url / session_age / state:running / logging_in / unhealthy)——宿主聚合后上报云端做监控大屏;__del__ 兜底:对象被 GC 时也尝试清理(防异常路径泄漏)。契约是"最小共识":8 个方法恰好覆盖"任何签证网站都要做的事",多一个侵入、少一个残缺。插件作者只需要看 vs_plg.py 一个文件就能写插件——低门槛;而宿主通过异常体系(401/403/429)获得"通用决策能力"——高天花板。这就是"Low Floor, High Ceiling"。
控制反转:不是插件调用框架("我要查档期了"),而是框架调用插件("该你查了")。插件不知道 Redis、不知道订单队列、不知道信号,它只对 query/book 的入参出参负责。替换插件 = 替换工人,不换工厂。
对抗性设计内聚在插件里:反爬对抗(CF 过盾、RSA 签名、浏览器 fetch、拟人化等待)全部在插件内部消化,框架层的调度逻辑保持纯净、可测试。框架只依赖"插件会按契约工作"这个信念。
归一化接口:VFS 的三种档期状态(有/无/waitlist)→ 统一 AvailabilityStatus;千奇百怪的日期格式 → 统一 YYYY-MM-DD;浏览器 fetch 结果 → 统一 BrowserResponse。接口的稳定性就是插件的可替换性。
生产级资源管理:实例隔离(独立端口/独立目录)、原子清理、__del__ 兜底、内存缓存、失败重试带"不可恢复错误识别"——这些是"能长期跑"和"演示能跑"的分界线。
| # | 亮点 | 位置 |
|---|---|---|
| 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 |
time.sleep(20) 硬编码(869):冷静期不可配置,改时长要改代码。建议进 free_config。master_email = "hujiarui8@gmail.com" 硬编码(707):读 OTP 邮件的"主邮箱"写死在代码里,换运营人就要改代码。建议进配置。_query_center 是 GET 全量中心列表(较重的响应),高频随机到它浪费带宽。可换成更轻的接口。real_ip 获取失败 fallback 到代理 IP(373):代理 IP 与风控记录可能不符,极端情况会误伤账号。值得观察线上日志。_perform_request 每次全量打印响应体(debug 模式):响应 1KB 截断打印,已比早期好,仍建议加开关。prt_plugin.py(最小骨架)或参考 vfs_plugin.py 结构;keep_alive/health_check 不抛异常;create_session 失败抛异常;free_config(用 apt_configs 按 routing_key 给配置),不要写死任何中心/类别代码;_perform_request 式浏览器 fetch(如果网站有反爬)或 requests(如果网站裸奔),但响应必须归一化成 VSQueryResult 三态;