# 浏览器扩展：导览

扩展是浏览器里的 URnetwork，ur.io 的 Web 应用是它的控制面：一件产品，两个半边。这一页是深度导览：各浏览器里的代理机制、各控制项及其出厂默认值、断网保护承诺什么和不承诺什么，以及出问题时查什么。它背后的网络、提供者是谁、各方能看到什么，读[概览](/docs/overview)。商店链接、登录和首次连接，从[浏览器入门](/docs/getting-started-browser)开始。

始终要拿稳的框架：**这是浏览器代理，不是 VPN。** 代理是替浏览器取回网站的中间人，所以网站看到的是它的地址而不是你的。扩展配置的是浏览器自己的代理设置，所以它治理的恰好是这个浏览器发出的东西，不多不少。覆盖：这个浏览器的每个标签页和窗口，无痕窗口也算，Chromium 上始终如此，Firefox 上在你允许隐私窗口后如此。不覆盖：其他浏览器、你的邮件应用、系统更新、其余一切——不受保护，也不受干扰。按浏览器安装；整机覆盖是 URnetwork 应用的工作（Android、iOS、macOS、Windows、Linux）：同一个账户、同样的断网保护、往下一层。

![扩展弹窗](/docs-assets/connect-extension.png)

## 设置一览

扩展有意保持小的表面。两个控制项，都在弹窗里：

| 设置 | 默认 | 效果 | 主要代价 |
|---|---|---|---|
| 断网保护（Kill switch） | 开 | 代理断开时阻止浏览器流量，而不是回落到你的直接连接 | 故障期间标签页报错 |
| 地理位置覆盖（Geolocation override） | 关 | 浏览器的地理位置 API 报告你的出口城市，而不是你的真实位置 | 想让站点看到真实位置时得关掉；保持最新需要开着一个 ur.io 标签页 |

随表附送的注意事项：

- 有两个应用里的开关在浏览器里没有对应物，这是设计使然。这里没有**后量子加密**（Post Quantum Encryption），因为扩展没有可密封的客户端到提供者会话；完整的适用范围说明在下文"数据收集"。也没有**强匿名化**（Strong Anonymization）开关，因为扩展所依托的托管代理设备上直连模式被强制关闭：任何提供者都永远拿不到你的真实地址。
- 断网保护跨浏览器重启保持，所以故障期间你保持被阻断而不是被暴露，直到你断开或路径恢复。

## 工作原理

扩展在每个浏览器上都是 Manifest V3，但代理管线不同，因为浏览器的 API 不同：

- **Chrome 和 Edge**（以及 Chromium 系浏览器）使用代理设置 API。扩展安装一个生成的 PAC 脚本——浏览器用来决定每个请求去哪的小规则文件——把浏览器流量送到为你配置好的 URnetwork 代理端点。设置它就占据了浏览器的代理配置，这也是两个代理扩展无法共存的原因（见疑难解答）。它从不碰操作系统设置，撤销得干干净净：断开就恢复直连，卸载就移除占据。
- **Firefox** 没有对应的设置交接机制，所以它用 `proxy.onRequest`：每个请求都询问扩展，扩展应答完整的已配置代理列表，所以一个不可达的代理不会让请求搁浅。只有当你关掉断网保护时，`direct` 才会被附加到那个列表末尾；开着时，列表止于最后一个代理，全面故障就是失败。

没有 Safari 版本，因为 Safari 缺这些 API。在 Apple 设备上，应用覆盖一切，包括 Safari。

浏览同时从一小窗提供者出网：主人主动开启共享、参与 [UR protocol](https://ur.xyz) 的成员设备。"你的出口 IP"是复数的，按站点固定让每个站点停留在一个出口上，所以你的银行看到一个一致的地址。

URnetwork SDK 以 WebAssembly 形式装在扩展包里。配置、位置列表和 API 调用都在本地运行。运行时不下载任何可执行的东西；商店审核的是什么，跑的就是什么。

**Web 应用是扩展的控制面；它们是一件产品。** 在 [ur.io](https://ur.io) 登录一次，页面和扩展就经一座有文档的桥对话：一套简短的动词协议（`SETUP`、`CONNECT`、`DISCONNECT`、`SET_LOCATION`、断网保护、地理同步），由 `window.postMessage` 承载，这是在 Chrome、Edge、Brave 和 Firefox 上都通的唯一通道。`SETUP` 把已登录的会话直接递过去，这就是从应用设置扩展从不向你要授权码的原因。分工是真实的：扩展铸出代理会话并安装浏览器代理，应用持有活的设备。在应用里换位置会直接重路由，浏览器无需重连，而且每个半边都显示你在另一边做了什么。

**这座桥刻意做窄。** 它只在 `ur.io` 和 `app.ur.network` 页面上运行；其他任何站点都无法与扩展对话。另有一个脚本确实加载在每个页面上，即地理位置覆盖，但在你打开它之前（见下文），它保持不活动，原生接口原封不动。

登录需要账户，因为用量按账户计量：邮箱或手机验证码、ur.io 的某个 SSO 选项、钱包签名，或在已登录设备上生成的授权码。这里的免邮箱路线是钱包和授权码；一键免邮箱的即时账户在手机和桌面应用里创建，扩展像接任何账户一样接上它。免费是每日流量额度；Pro 是大额月度额度（每月 $5 或每年 $40；当前数字在 ur.io/products）。

## 断网保护的语义

它做什么：断网保护开着时如果代理连接断了，扩展会阻止浏览器的流量，而不是让浏览器悄悄回落到你的直接连接、在会话中途暴露你的真实地址。

- 它**默认开启**，是唯一一个出厂即上膛的 URnetwork 界面。
- 执行靠的是浏览器自己的代理规则：上膛后，它没有"不行就直连"的后门，所以请求失败而不是回落。它跨浏览器重启保持。你回来时是被阻断的，不是被暴露的。
- 如果它触发，只有这个浏览器停下（标签页报错；弹窗说明原因）。你电脑的其余部分从来就没走过它。
- 关掉它意味着放行失败：连接断掉会把你还原成直连浏览，弹窗里看得见，标签页里悄无声息。只有当泄漏只是不便而非伤害时才可接受。
- 范围局限：它阻止的是*浏览器*流量，这是扩展所能治理的全部；它不是系统防火墙。本地地址（localhost、打印机）有意绕过，而 WebRTC（浏览器内的语音/视频）可能打开无视代理设置的连接，这是每个代理扩展都有的缺口；浏览器可以限制它。

## 地理位置覆盖

两个信号：你的 IP 地址现在说阿姆斯特丹，但浏览器的地理位置 API 由附近 Wi-Fi 等系统信号应答，仍然报告你身体所在。比对这两者的站点会看到矛盾。覆盖修正第二个信号，让两个故事一致：

- **默认关闭。** 在弹窗里启用之前什么都不变。
- 启用后，它在 `document_start` 时**在所有 frame 里**应答，所以地理位置 API 在任何页面脚本来得及问之前就给出你的出口位置，包括试图抢跑的 iframe。坐标是你连接最久的提供者所在城市，经应用桥到达扩展：扩展自己不持有设备，所以保持位置最新靠的是一个开着的 ur.io 标签页。
- 停用时，它一言不发：页面保留原生地理位置，也没有站点会收到一个"你装了扩展"的新信号。当你*想让*站点看到真实位置时（地图、外卖），把它关掉。

## 健康检测与降级状态

连接期间，扩展每五分钟经代理抓取一个轻量端点（URnetwork API 上的 `my-ip-info`），即使对免费额度也可以忽略不计。这证明的是路径端到端可用，而不只是设置生效了：

- **连续两次失败**：状态变为**降级**（degraded）。你仍是已配置状态，但流量未被确认在流动。弹窗显示不稳定指示。
- **连续三次失败**：自动重连，带退避（2 秒翻倍至 30 秒，五次尝试），按需重新配置代理。
- 任何时刻的一次成功都把状态弹回已连接。连接后有一段宽限期，避免首次连接还没坐稳就来回摆动。

降级不是泄漏。你仍然指向代理，而且上膛状态下，死路是阻断而不是暴露。它不是一个要修的错误；它是扩展在提早告诉你——通常是你和代理之间的网络不稳。

## 数据收集：没有

- Firefox 上架条目在 manifest 里以机器可读的方式声明：`data_collection_permissions` 是 **none**。那是商店强制执行的陈述，不是隐私页上的承诺。
- 扩展只与 URnetwork API 对话来配置你的代理，和任何客户端相同的调用。没有分析、没有遥测、任何地方都没有浏览历史收集。
- **主机权限按浏览器不同，有其原因。** 在 Chrome 上，扩展只请求访问 URnetwork API 主机（`api.bringyour.com`、`api-v4.bringyour.com`）；基于 PAC 的代理 API 不需要看见你的请求。在 Firefox 上扩展需要 `<all_urls>`：`proxy.onRequest` 会为每个可能路由的请求询问扩展，而 Firefox 要求有主机访问权它才能工作。那里更宽的权限是 Firefox 代理 API 的代价，不是抓数据。
- **没有第三方评估过这个扩展。** URnetwork 的 Android 应用在 2025 年 5 月通过了 Leviathan Security Group 的 MASA AL2 评估（Google 为移动应用定的固定安全清单），同年 4 月一家独立公司渗透测试了 Web 应用和 API；两者都不覆盖扩展，而且尚无独立审计覆盖协议或运营方的服务器代码。这一页给出的替代是可证伪的：那些权限在你自己安装的副本里就能读到，运行时不下载任何东西，源码是公开的。是你能核查的说法，不是一纸证书。

服务保留什么：你的账户和一份按设备的字节数账本（也就是额度和提供者计量），从不含目的地或 URL；一个以你 IP 地址块的带密钥单向哈希形式保存的客户端地址，而不是地址本身；以及地理查询得出的一个粗略城市。提供者在不知道你真实地址的情况下出网，只看到 ISP 级的元数据（站点名，从不是页面或密码，那些仍被 HTTPS 密封）；网站只看到出口。

不过，对中间那一方要说得精确。网络有三种模式，浏览器永远只占其中一种：

| 模式 | 运营方看到 | 提供者看到 | 此处可用 |
|---|---|---|---|
| **中继标准** | 你的账户和来源连接、你在用哪些提供者，以及里面的目的地和数据包字节 | 它出网的目的地和一个设备/合同 id，**不含**你的真实 IP | **可用：唯一的浏览器模式** |
| **中继密封** | 同上，但目的地换成密文及其时序和数据量 | 同上 | 不可用：应用那种加密到提供者的会话（在应用里默认开启）在浏览器没有对应物 |
| **直连** | 更少的中继参与 | **你的真实 IP**及它出网的目的地 | 不可用：在扩展所依托的托管代理设备上被强制关闭 |

第一行就是浏览器的位置，与应用的对比是锋利的而不是含糊的：应用默认密封客户端↔提供者会话，而浏览器在那里没有可密封的会话。它不可能有。浏览器说的是自己的代理协议，跑不了网络的引擎，所以你的客户端设备远程运行在运营方内部，由运营方在两种协议之间转换 — 从那台设备发起的密封会始于运营方，而密封的存在恰恰是为了让运营方失明。这个实现用密封换来了对浏览器的支持。这里的保证是存储层面的，不是加密层面的。任何浏览器代理都会把每个目的地递给它拨号的端点，所以你的目的地在途中经运营方之手；站在这背后的，是一条什么日志都不写、被开源代码里的回归测试钉住的代理数据路径，和一本没有任何字段能放目的地的账本。应用的**强匿名化**开关同样缺席、同样不需要：直连模式被强制关闭后，任何提供者都永远拿不到你的真实地址。

你的流量流动起来之后网络本身能看到什么、不能看到什么，读[概览](/docs/overview)。[威胁模型](/docs/threat-model)走得更远，把浏览器路径缺失的密封列为它自己的失败之一。

## 疑难解答

### "Failed to provision any proxy connections. Check your account."

（未能配置任何代理连接。请检查你的账户。）扩展向 API 请求代理凭证，一个都没批下来。几乎总是账户状况：

1. 确认你能在 [ur.io](https://ur.io) 登录，查看你的套餐。用尽的免费每日额度是最常见的原因（它每天刷新）。
2. 检查套餐的并发客户端上限是否被其他设备占满；断开一台。
3. 登出扩展再登录，刷新凭证。

### "Connection lost. Please reconnect."

（连接已断开。请重新连接。）健康检查连续失败，自动重连用完了尝试次数。多半是你的底层网络变了（换了网络、笔记本睡眠、不友好的 Wi-Fi）。从弹窗重连；如果在某一个网络上反复出现，那个网络可能在封锁代理端口。

### 另一个扩展在抢代理

同一时间只有一个扩展能控制浏览器的代理设置（Chrome 上最近安装的那个赢）。再跑一个 VPN 或代理扩展，两者就会把设置抢来抢去，看起来都坏了。失去控制时弹窗会说明，`chrome://settings` 会写明当前持有者；停用另一个。在 Firefox 上，检查其他装了代理权限的附加组件。

### 强制登录门户

酒店和机场 Wi-Fi 要你先经门户页登录，互联网才通，而代理开着时（尤其是上膛状态），门户加载不出来。你不会被卡死：断开是本地动作，不需要网络。断开扩展，完成门户登录，再重连。这是每个代理和 VPN 的固有情况，不是扩展的 bug。

### 读懂状态

弹窗的状态指示是最快的诊断：

- **空闲**（Idle）：已登录，未连接。浏览走直连。
- **连接中**（Connecting，转圈）：正在配置代理并应用设置。
- **已连接**（Connected）：已配置，且最近健康检查通过。
- **降级**（Degraded，不稳定图标）：已配置，但健康检测在失败；持续下去就等着重连。
- **重连中**（Reconnecting）：自动恢复进行中；别动它。
- **错误**（Error）：上面那些消息之一，修法就列在本节。

## 接下来去哪里

- [浏览器入门](/docs/getting-started-browser)：商店链接、登录和首次连接，包括隐私窗口那条说明。
- [URnetwork 的工作原理](/docs/overview)：弹窗背后的网络，以及提供者从哪里来。
- [FAQ](/docs/faq)：套餐、额度和账户问题。