Obscura 环境变量完全指南：从运行时安全到浏览器指纹的逐项配置详解

网页爬虫后端MCP 服务浏览器控制【免费下载链接】obscuraThe headless browser for AI agents and web scraping项目地址https://gitcode.com/gh_mirrors/ob/obscura点击查看免费下载Obscura 是一个面向 AI Agent 与网页抓取场景的无头浏览器它的行为高度可配置而环境变量正是它最核心的旋钮面板。本文基于仓库官方文档 docs/Environment-variables.md逐项讲解 Obscura 全部环境变量的语义、默认值、取值规则与适用场景并结合源码网络层、页面层、CDP 服务层、MCP 服务层说明每个变量底层是如何生效的。读完本文你将能够精确地为本地调试、生产抓取、隐身防检测、MCP 服务加固等场景挑选并组合正确的环境变量而不必靠猜测反复试错。环境变量分类总览Obscura 的环境变量按职能分为六组覆盖了从网络请求安全、导航与脚本执行预算、隐身身份一致性到 MCP 服务加固、日志与构建、V8 引擎调优的全部生命周期分组变量默认值核心作用RuntimeOBSCURA_ALLOW_PRIVATE_NETWORK关闭放行私网/回环地址默认封禁防 SSRFRuntimeOBSCURA_NAV_TIMEOUT_MS30000单次导航硬性上限RuntimeOBSCURA_NAV_CHAIN_LIMIT10导航链最多加载文档数RuntimeOBSCURA_SCRIPT_DEADLINE_MS30000整页脚本执行阶段软上限兼 V8 看门狗预算RuntimeOBSCURA_MODULE_BUDGET_MS3000增强型模块的图加载与求值预算RuntimeOBSCURA_CDP_COMMAND_TIMEOUT_MS60000CDP 单命令超时0关闭RuntimeOBSCURA_FETCH_TIMEOUT_MS30000fetch()/XHR/ES 模块请求超时RuntimeOBSCURA_PROXY未设置obscura-worker的默认代理 URLStealthOBSCURA_TIMEZONEEurope/Berlin进程时区保持Date/Intl一致StealthOBSCURA_GEOLOCATION固定默认navigator.geolocation的经纬度覆盖StealthOBSCURA_PROFILE稳定单档案按索引固定内置浏览器档案StealthOBSCURA_ROTATE_PROFILE关闭每个浏览器上下文随机选择档案MCPOBSCURA_MCP_ALLOWED_ORIGINS未设置宽松HTTP MCP 传输的Origin白名单LoggingRUST_LOG由命令决定tracing过滤器BuildOPENSSL_NO_VENDOR未设置改用系统 OpenSSL 编译V8--v8-flagsCLI 参数见下文追加 V8 引擎标志下面按分组逐项深入。Runtime 组网络、导航与脚本执行的资源边界Runtime 组的环境变量控制 Obscura 的运行护栏哪些地址允许访问、一次导航能走多远、脚本能执行多久、单个 CDP 命令能占锁多久。这一组直接决定了引擎在恶意页面与故障页面前是安全、可控还是被拖垮。OBSCURA_ALLOW_PRIVATE_NETWORKSSRF 防护的总开关该变量默认关闭这是 Obscura 默认的 SSRF 防护策略。关闭时引擎拒绝访问回环地址127.0.0.0/8RFC1918 私网段10.0.0.0/8、172.16.0.0/12、192.168.0.0/16链路本地169.254.0.0/16其中包含云厂商元数据端点169.254.169.254——这是 SSRF 攻击最经典的靶点未指定地址0.0.0.0/::IPv6 唯一本地地址fc00::/7以上地址的任何 IPv4-mapped 形式如::ffff:127.0.0.1值得强调的是该防护不仅在字面 IP 上生效还在 DNS 解析时刻校验。仓库的 SSRF 防护实现在 crates/obscura-net/src/client.rs 中env_allows_private_network()读取环境变量见client.rs第 582 行附近而网络客户端通过自定义的SsrfGuardResolver对每个解析结果做任意解析地址落入 deny-set 即拒绝的判定注释明确写道这closes the DNS-rebinding attack。也就是说一个解析到内网地址的公网域名会在连接建立前就被拒绝而不是只拦截那些把 IP 直接写进 URL 的请求。取值方面只有1、true、yes、on被视为真值大小写不敏感源码中的env_enabled会先trim再转小写匹配见 crates/obscura-browser/src/profiles.rs。典型用法是配合本地开发服务OBSCURA_ALLOW_PRIVATE_NETWORK1 obscura fetch http://localhost:8080每个子命令都有等价进程级开关--allow-private-network。从源码看CLI 在启动时会把该开关镜像回环境变量主入口crates/obscura-cli/src/main.rs中若传入--allow-private-network则设置OBSCURA_ALLOW_PRIVATE_NETWORK1注释说明这样做的原因——JS 侧的fetch()路径op_fetch_url会直接读该环境变量做 SSRF 门禁镜像后 iframe 加载与脚本内fetch()就能与http_client层看到同一份策略避免CLI 放行但 JS 仍拦截的不一致issue #33。OBSCURA_NAV_TIMEOUT_MS单次导航的硬性上限一次导航含页面触发的后续跳转链路的总时间预算默认30000毫秒30 秒。它同时约束Page.navigateCDP 页面导航和 CLI 的fetch命令。默认值常量定义在 crates/obscura-browser/src/page.rsDEFAULT_NAVIGATION_TIMEOUT_MS 30_000环境变量解析函数navigation_timeout_from_env_value无法解析成数字时回退默认值。超时后页面层会以navigation exceeded {ms}ms deadline报错。OBSCURA_NAV_TIMEOUT_MS60000 obscura serve对于需要更长时间首屏加载的重型站点把它调大即可注意它与导航链上限配合时的预算归属见下节。OBSCURA_NAV_CHAIN_LIMIT导航链深度上限与防死循环该变量限制一条导航链最多加载多少个文档含第一次导航默认10即请求的文档 页面自己通过location赋值或表单提交触发的 9 次后续导航。源码中默认常量DEFAULT_NAVIGATION_CHAIN_LIMIT: usize 10page.rs解析函数会先把值parse::usize()解析失败回退默认成功则limit.max(1)——这正是文档所述0 会被提升为 1的落地实现page.rs。这个低默认值正是用来阻止那种每次加载都把location重置、从而无限重载的恶意/故障页面的。但有些合法场景需要更长链路——例如跨多个身份提供商接力跳转的 SSO 流程。此时按需调大OBSCURA_NAV_CHAIN_LIMIT20 obscura serve边界行为要留意两点设为0会被提升为1只加载请求的文档本身如果页面之后还想继续跳转调用会像到达任何其他上限一样报错。引擎无法读取为数字的值包括负数、带尾随空格的值一律替换为默认值10。时间预算与链长上限是相互独立的OBSCURA_NAV_TIMEOUT_MS的 30 秒默认是作用于整条链而非单个文档所以链变长后通常需要同步调高导航超时否则链路还没走完就被超时掐断。OBSCURA_SCRIPT_DEADLINE_MS整页脚本执行阶段的软截止时间脚本执行阶段含 classic scripts 与 ES modules的软上限默认30000毫秒。实现位于 page.rs软截止只在脚本之间检查适用于那些会越过截止时间继续跑的页面正常快速页面远早于预算结束因此调大预算对快页面零成本。同时引擎把该值加 1 秒宽限期作为硬 V8 看门狗预算arm_watchdog(script_deadline_ms 1000)确保一段同步死循环脚本无法永远占住引擎——注释里明确提到这是针对真实世界 SPA / 反爬 busy-loop 挂起的兜底。适用场景初始模块负责挂载原本空白文档的重型 SPA源码注释点名 GitHub、Linear、CodeSandbox 这类 50 脚本的站点。此时把预算调高OBSCURA_SCRIPT_DEADLINE_MS60000 obscura serveOBSCURA_MODULE_BUDGET_MS增强型模块的独立短预算默认3000毫秒3 秒针对增强已渲染页面的模块——即文档 body 已包含超过 50 个后代节点时模块通常只是渐进增强不应无限期推迟导航因此给出更短的预算。典型例子是 Vite HMR 客户端这类合法但需要更久求值的模块OBSCURA_MODULE_BUDGET_MS10000 obscura serve分支规则当页面是未挂载的 SPA 壳body 节点数未超阈值时Obscura 反过来给每个模块完整的OBSCURA_SCRIPT_DEADLINE_MS预算让应用有足够时间完成挂载。此外模块的网络请求仍由OBSCURA_FETCH_TIMEOUT_MS独立兜底。OBSCURA_CDP_COMMAND_TIMEOUT_MSCDP 单命令预算防止坏会话独占 V8 锁CDP 服务器对单条命令的执行截止时间默认60000毫秒设为0则禁用。设计动机非常关键挂死的页面失控的Runtime.evaluate、同步 DOM 操作超过该预算后会被终止从而避免一个坏会话长期占用共享的 V8 锁、拖慢其他所有会话。实现见 crates/obscura-cdp/src/dispatch.rs。导航自身会被OBSCURA_NAV_TIMEOUT_MS限制在远低于此预算的范围之内所以两者职责不重叠。OBSCURA_CDP_COMMAND_TIMEOUT_MS30000 obscura serveOBSCURA_FETCH_TIMEOUT_MS脚本网络请求超时针对脚本发起的fetch()、XMLHttpRequest以及 ES 模块加载的请求超时默认30000毫秒。没有它时一个接受了连接但永不响应的服务端包括 CORS preflight会让 XHR 永远挂起且收不到任何完成事件。解析位置在 crates/obscura-js/src/ops.rs注释提到该环境变量用于在更紧的云环境限制下覆盖工作区默认值。OBSCURA_FETCH_TIMEOUT_MS15000 obscura serveOBSCURA_PROXY并行 scrape 的默认代理为obscura-worker的并行scrape命令提供默认代理 URL当没有--proxy标志时生效。它的定位是把代理凭据放进环境变量而非命令行——obscura-cli主进程在serve分支中回退读取该变量见 crates/obscura-cli/src/main.rs并把它以环境变量方式传给 worker源码注释强调该变量仅属主用户可读避免命令行参数被同机用户窥探。用法OBSCURA_PROXYhttp://proxy.example.com:8080 obscura scrape - urls.txtStealth 组让浏览器身份保持内部一致隐身组的核心思想不是假装成一个浏览器而是全身各处自洽得像一个真实设备。详见仓库文档 Configure stealth and proxies。OBSCURA_TIMEZONE在 V8/ICU 读取前钉住进程时区固定进程时区使DategetTimezoneOffset、toString与Intl.DateTimeFormat报告一致的时区默认Europe/Berlin。实现位于 CLI 主入口的启动早期主函数在创建任何 V8 isolate 或 worker 线程之前设置TZ环境变量源码注释强调此时环境仍是单线程的所以set_var是安全的若宿主已有TZ则尊重宿主值main.rs。源码注释解释了必要性若TZ未设置V8 对Date默认用 UTC而页面层却会对外宣告另一套时区这种跨表面不一致正是指纹脚本会抓的破绽。OBSCURA_TIMEZONEAmerica/New_York obscura serve最佳实践让时区与出口 IP 所在区域一致。OBSCURA_GEOLOCATION覆盖navigator.geolocation的坐标以lat,lon格式覆盖navigator.geolocationshim 上报的坐标不设置时 shim 上报固定的默认值。解析函数位于 crates/obscura-browser/src/page.rs从OBSCURA_GEOLOCATION读取lat,lon。实践上应与OBSCURA_TIMEZONE及代理区域保持一致OBSCURA_GEOLOCATION40.7128,-74.0060 obscura serveOBSCURA_PROFILE与OBSCURA_ROTATE_PROFILE浏览器档案的固定与轮换OBSCURA_PROFILE按索引0 基从内置档案池中固定一个档案OBSCURA_ROTATE_PROFILE1则让每个浏览器上下文随机挑选一个档案。档案池定义在 crates/obscura-browser/src/profiles.rs共 8 个档案Windows 平台 Chrome 143/144/145/146macOS 平台 Chrome 143/144/145/146。每个档案把navigator.platform、userAgentData、UA 字符串与 GPU renderer 保持一致。选择逻辑select_profile见 profiles.rs先看OBSCURA_PROFILE是否解析为有效索引超出池长的索引会被忽略再看OBSCURA_ROTATE_PROFILE是否启用最后回退到PROFILES[0]这个稳定档案。默认单一稳定档案是刻意的源码注释指出从一个地址轮换不同浏览器身份本身就是机器人信号真实地址对应稳定设备且轮换档案尚未携带匹配的 TLS 或时区指纹所以轮换必须显式开启。# 固定使用第 3 个档案0 基索引 OBSCURA_PROFILE2 obscura serve # 随机轮换 OBSCURA_ROTATE_PROFILE1 obscura serve关键约束当你钉死了 TLS 指纹、代理区域或时区时应保持轮换关闭否则轮换出的档案将与这些固定指纹不再匹配反而暴露矛盾。MCP 组HTTP 传输的 Origin 白名单OBSCURA_MCP_ALLOWED_ORIGINS逗号分隔的Origin白名单作用于 HTTP MCP 传输obscura mcp --http。默认未设置保持宽松行为对应 CORSAccess-Control-Allow-Origin: *。设置后浏览器发来的请求若Origin不在名单中会在能驱动服务器之前就被403拒绝而原生非浏览器MCP 客户端不发送Origin永远放行。实现见 crates/obscura-mcp/src/http.rsorigin_allowed对无Origin请求放行对有Origin的请求做大小写不敏感的逗号列表匹配白名单开启时响应还会回显请求方Origin并附加Vary: Origin而非广告*。OBSCURA_MCP_ALLOWED_ORIGINShttps://app.example.com obscura mcp --http --host 0.0.0.0核心用途当 MCP 服务监听在0.0.0.0时防止任意跨域网页驱动回环 MCP 端口DNS rebinding / 恶意本地页面攻击。如果把服务绑定在 loopback 上且仅限本机工具使用维持默认即可。Logging 组tracing 日志过滤RUST_LOG标准的tracing过滤器可精确控制各 crate 的日志级别。CLI 在main.rs中通过EnvFilter::try_from_default_env()读取该变量未设置时使用命令级默认过滤器select_log_filter会考虑--verbose与--quiet。常用设置RUST_LOGobscurainfo obscura serve RUST_LOGobscuradebug obscura serve RUST_LOGobscura_cdptrace,obscura_browserdebug obscura serve注意CLI 的--verbose等价于RUST_LOGobscurainfo二者并存时以更细的显式RUST_LOG为准。需要排查具体模块如 CDP 分发、页面生命周期时obscura_cdptrace,obscura_browserdebug这类定向过滤比全局debug噪音小得多。Build 组编译期行为OPENSSL_NO_VENDOR强制cargo build使用系统 OpenSSL 而非编译 vendored 副本。设为1适用于 vendored OpenSSL 编译失败的宿主机——文档特别点名带有 AVX-512 问题的老 VPSOPENSSL_NO_VENDOR1 cargo build --release --features render仅影响构建不影响运行时。V8 组通过--v8-flags而非环境变量调优V8 引擎标志不通过环境变量传递而是通过 CLI 全局参数--v8-flagsobscura serve --v8-flags --max-old-space-size2048 --expose-gc默认标志在 64 位系统上为--max-old-space-size4096 --max-semi-space-size4 --optimize-for-size常量定义见 crates/obscura-cli/src/main.rs非 64 位平台 old-space 上限降为 1024。含义是4 GB old-space 上限、受限的年轻代semi-space 4 MB防止解析/分配突发膨胀 RSS、以及面向更小内存占用的代码生成优化。源码注释给出的实测参照这套组合在重页面ycombinator.com上把 RSS 从约 173 MB 压到约 140 MB而速度无可测损失。你通过--v8-flags传入的参数会追加在这些默认值之后V8 对重复标志取最后一个值所以你传入的标志生效其余默认值保持。effective_v8_flags的拼接逻辑证实了这一点main.rs。HTTP 代理环境变量明确的不支持清单Obscura不理会HTTP_PROXY/HTTPS_PROXY/NO_PROXY这三个通用代理环境变量。配置代理只有两条路CLI 的--proxy标志或OBSCURA_PROXY环境变量。这避免了很多抓取工具莫名走了系统代理的坑——在 Obscura 中代理行为完全显式可控。综合实践建议基于以上语义给出几组典型组合按场景套用即可# 本地开发访问 localhost 上的服务放宽导航预算 OBSCURA_ALLOW_PRIVATE_NETWORK1 OBSCURA_NAV_TIMEOUT_MS60000 obscura fetch http://localhost:8080 # 重型 SPA给挂载脚本更长预算同时放宽模块求值 OBSCURA_SCRIPT_DEADLINE_MS60000 OBSCURA_MODULE_BUDGET_MS10000 obscura serve # 隐身抓取时区、地理、档案与出口 IP 区域一致 OBSCURA_TIMEZONEAmerica/New_York OBSCURA_GEOLOCATION40.7128,-74.0060 OBSCURA_PROFILE0 obscura serve # 生产加固CDP 命令预算收紧 MCP 白名单 收敛日志 OBSCURA_CDP_COMMAND_TIMEOUT_MS30000 OBSCURA_MCP_ALLOWED_ORIGINShttps://app.example.com RUST_LOGobscurainfo obscura mcp --http --host 0.0.0.0最后提醒几个容易踩的细节布尔变量只认1/true/yes/on其余值一律视为关闭数值解析失败一律回退默认值OBSCURA_NAV_CHAIN_LIMIT0会被提升为1导航超时针对整条链调长链长时务必同步调大OBSCURA_NAV_TIMEOUT_MS轮换档案与固定指纹互斥轮换开启时不要同时钉死 TLS 指纹/时区/代理区域CLI--allow-private-network会自动镜像回环境变量保证页面层与 JSfetch()策略一致不需要手动双写。如需完整的 CLI 参数与子命令说明可继续阅读 CLI reference隐身机制的整体设计见 Configure stealth and proxies。赞分享网页爬虫后端MCP 服务浏览器控制【免费下载链接】obscuraThe headless browser for AI agents and web scraping项目地址https://gitcode.com/gh_mirrors/ob/obscura点击查看免费下载相关推荐Poketwo-Autocatcher免费开源的Pokétwo自动捕捉工具终结付费开发者的垄断Poketwo Autocatcher免费开源的Pokétwo自动捕捉工具终结付费开发者的垄断 Poketwo Autocatcher是一款功能强大的免费后端Web框架SSRPolygraphy 全局配置完全指南从 polygraphy.config 到环境变量驱动的运行时开关Polygraphy 全局配置完全指南从 polygraphy.config 到环境变量驱动的运行时开关 Polygraphy 是 NVIDIA Tensor人工智能深度学习推理引擎模型优化模型编译ZenML 环境变量配置完全指南从 Step 运行时注入到 Secrets 管理ZenML 环境变量配置完全指南从 Step 运行时注入到 Secrets 管理 ZenML 提供了一套分层、可继承的环境变量与 Secrets 配置体系让MLOps机器学习后端工作流自动化AI Agent上一篇Nextcloud AIO客户关系管理CRM系统集成下一篇MiniChain扩展开发打造专属后端工具与智能代理的完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考