Firefox FPN Local Proxy (Go)

基于Firefox 免费内置 VPN（FPN / Private Network）本地 SOCKS5 代理。

用 Firefox 账户登录后，向 Mozilla Guardian 申请 proxy-pass，再通过上游 FPN 节点建立 单条 HTTP/2 CONNECT 隧道，在本地提供 SOCKS5 代理。

这是 浏览器内置免费 FPN 路线，不是付费 Mozilla VPN 购买/订阅产品流。

功能

浏览器弹窗完成 Firefox Account OAuth（PKCE）
可选邮箱密码登录
自动/手动选择上游节点：
- -country 指定国家
- -fastest TCP 测速选最快
- -proxy 手动指定节点
本地 SOCKS5（默认 127.0.0.1:1080）
上游单连接 HTTP/2 + Proxy-Authorization: Bearer <proxy-pass>
会话与 proxy-pass 本地缓存：
- tokens.json：OAuth / session
- proxy_pass.json：proxy-pass JWT（过期前可复用）
支持 -api-proxy：仅用于 Guardian/FxA API 出口（解决 HTTP 451 unavailable_in_region）

目录结构

VPN/
├── main.go                 # CLI、SOCKS5、HTTP/2 上游、续期
├── vpnclient/
│   ├── auth_browser.go     # 浏览器 OAuth + PKCE
│   ├── fxa.go              # 邮箱密码 / refresh（兼容旧逻辑）
│   ├── guardian.go         # /api/v1/fpn/token、status
│   ├── httpclient.go       # 共享 HTTP 客户端与 -api-proxy
│   ├── serverlist.go       # Remote Settings 节点列表
│   ├── serverpick.go       # 国家过滤 / 延迟探测
│   ├── tokens.go           # tokens.json
│   └── proxypass_store.go  # proxy_pass.json
├── tokens.json             # 运行后生成
├── proxy_pass.json         # 运行后生成
└── firefox-vpn-proxy.exe

编译

cd C:\Users\admin\GolandProjects\VPN
go mod tidy
go build -o firefox-vpn-proxy.exe .

快速开始

1. 首次登录（若本机被地区限制）

# 用本机已有代理作为 Guardian API 出口（示例端口按你的代理改）
.\firefox-vpn-proxy.exe -login -api-proxy http://127.0.0.1:7890 -country us -fastest

2. 之后日常启动（复用缓存，通常不再需要 api-proxy）

.\firefox-vpn-proxy.exe -country us -fastest
# 或全球测速
.\firefox-vpn-proxy.exe -fastest

3. 配置系统/浏览器代理

SOCKS5 127.0.0.1:1080

浏览器授权步骤

运行 -login 后自动打开 Firefox Accounts 登录页
登录成功后进入 accounts.firefox.com/oauth/success/...
复制页面上的 authorization code，或复制完整成功 URL
粘贴到本地 helper 页面，或直接粘贴到终端

说明：

使用合法 https redirect + PKCE（public client 要求）
不会打开付费入口：https://vpn.mozilla.org/api/v2/vpn/login/...

如果浏览器流异常，可用旧方式：

.\firefox-vpn-proxy.exe -password-login

节点选择

列出国家

.\firefox-vpn-proxy.exe -list-countries

指定国家

.\firefox-vpn-proxy.exe -country us
.\firefox-vpn-proxy.exe -country de
.\firefox-vpn-proxy.exe -country Japan

测速选最快

# 全部节点测速
.\firefox-vpn-proxy.exe -fastest

# 某国家内测速
.\firefox-vpn-proxy.exe -country sg -fastest

手动指定上游

.\firefox-vpn-proxy.exe -proxy de0.vpn.mozilla.org:443

优先级：

-proxy（最高）
-country + 可选 -fastest
默认：服务器列表中随机

proxy-pass 缓存

成功获取后会保存到：

proxy_pass.json

行为：

默认优先读缓存
仅当 token 距离过期仍大于 -pass-lead（默认 2 分钟）时复用
复用缓存时，连接 FPN 节点不需要 -api-proxy
后台续期成功后也会更新缓存

强制重新获取：

.\firefox-vpn-proxy.exe -force-pass -api-proxy http://127.0.0.1:7890

同时还会保存：

tokens.json   # OAuth access/refresh 或 session

地区限制（HTTP 451）

若出现：

guardian returned HTTP 451: {"error":"unavailable_in_region"}

说明当前公网 IP 不能向 Guardian 申请 FPN proxy-pass。

处理：

用 -api-proxy 走允许地区出口，先把 pass 拉下来并写入 proxy_pass.json
之后日常运行直接复用缓存，不再依赖该 API 出口

.\firefox-vpn-proxy.exe -login -api-proxy http://127.0.0.1:7890 -fastest
.\firefox-vpn-proxy.exe -fastest

注意区分两个代理：

参数	用途
`-api-proxy`	仅访问 Guardian / Firefox Accounts API
`-proxy`	FPN 上游业务节点（真正代理流量）

全部参数

参数	默认	说明
`-listen`	`127.0.0.1:1080`	本地 SOCKS5 监听地址
`-login`	false	强制浏览器重新授权
`-password-login`	false	邮箱密码登录
`-session-token`		直接使用已有 token
`-api-proxy`		Guardian/FxA API 出口代理
`-country`		国家代码/名称过滤
`-fastest`	false	TCP 测速选最快节点
`-list-countries`	false	列出国家后退出
`-proxy`		手动指定上游 host:port
`-force-pass`	false	忽略 `proxy_pass.json`
`-pass-lead`	`2m`	缓存至少剩余多久才复用
`-print-info`	false	打印用户/额度/节点信息
`-guardian`	`https://vpn.mozilla.org`	Guardian API
`-timeout`	`20s`	上游握手超时
`-4` / `-6`	IPv4	强制地址族

工作原理（简图）

浏览器/应用
    │  SOCKS5
    ▼
firefox-vpn-proxy (本机)
    │  HTTP/2 CONNECT + Bearer proxy-pass
    ▼
Mozilla FPN 节点
    │
    ▼
目标网站

鉴权：

Firefox Account OAuth (PKCE)
        │
        ▼
access token  ──►  Guardian /api/v1/fpn/token
        │
        ▼
proxy-pass JWT  ──►  缓存 proxy_pass.json
        │
        ▼
连接上游节点并提供本地 SOCKS5

GitHub Release（多平台）

仓库已配置 GitHub Actions：推送版本标签后自动交叉编译并发布 Release。

触发方式

方式 A：打 tag 发布

git tag v0.1.0
git push origin v0.1.0

方式 B：Actions 手动运行

GitHub → Actions → Release
Run workflow
填写 tag，例如 v0.1.0，并勾选 publish

产物平台

平台	架构
Windows	amd64, arm64
Linux	amd64, arm64, 386
macOS	amd64, arm64
FreeBSD	amd64

产物命名示例：

firefox-vpn-proxy_v0.1.0_windows_amd64.exe
firefox-vpn-proxy_v0.1.0_linux_amd64
firefox-vpn-proxy_v0.1.0_darwin_arm64
SHA256SUMS.txt

常见问题

1) 登录后跳到购买页？

当前实现已避开付费 /api/v2/vpn/login 产品流。若仍看到异常页面，把完整 Auth URL 发出来排查。

2) `Public clients require PKCE`？

已支持 PKCE（code_challenge + code_verifier）。请使用最新编译的 firefox-vpn-proxy.exe。

3) `unavailable_in_region` / HTTP 451？

本机出口被 Guardian 限制。用 -api-proxy 先拿并缓存 pass，后续可离线复用。

4) 如何只换节点、不重新登录？

.\firefox-vpn-proxy.exe -country de -fastest

只要 tokens.json / proxy_pass.json 仍有效即可。

5) 额度在哪看？

.\firefox-vpn-proxy.exe -print-info

安全提示

tokens.json、proxy_pass.json 含登录凭证与通行令牌，权限已尽量设为仅当前用户可读写
不要把这两个文件分享或提交到 Git
建议将它们加入 .gitignore

参考

https://ntc.party/t/firefox-149-%D0%BF%D0%BE%D1%81%D1%82%D0%B0%D0%B2%D0%BB%D1%8F%D0%B5%D1%82%D1%81%D1%8F-%D1%81-%D0%B1%D0%B5%D1%81%D0%BF%D0%BB%D0%B0%D1%82%D0%BD%D1%8B%D0%BC-vpn/22946/199
Mozilla Guardian FPN API：/api/v1/fpn/token、/api/v1/fpn/status
Firefox Remote Settings 节点列表：vpn-serverlist

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
.github/workflows		.github/workflows
vpnclient		vpnclient
.gitignore		.gitignore
README.md		README.md
go.mod		go.mod
go.sum		go.sum
main.go		main.go

Navigation Menu

Repository files navigation

Firefox FPN Local Proxy (Go)

功能

目录结构

编译

快速开始

1. 首次登录（若本机被地区限制）

2. 之后日常启动（复用缓存，通常不再需要 api-proxy）

3. 配置系统/浏览器代理

浏览器授权步骤

节点选择

列出国家

指定国家

测速选最快

手动指定上游

proxy-pass 缓存

地区限制（HTTP 451）

全部参数

工作原理（简图）

GitHub Release（多平台）

触发方式

产物平台

常见问题

1) 登录后跳到购买页？

2) `Public clients require PKCE`？

3) `unavailable_in_region` / HTTP 451？

4) 如何只换节点、不重新登录？

5) 额度在哪看？

安全提示

参考

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

Firefox FPN Local Proxy (Go)

功能

目录结构

编译

快速开始

1. 首次登录（若本机被地区限制）

2. 之后日常启动（复用缓存，通常不再需要 api-proxy）

3. 配置系统/浏览器代理

浏览器授权步骤

节点选择

列出国家

指定国家

测速选最快

手动指定上游

proxy-pass 缓存

地区限制（HTTP 451）

全部参数

工作原理（简图）

GitHub Release（多平台）

触发方式

产物平台

常见问题

1) 登录后跳到购买页？

2) Public clients require PKCE？

3) unavailable_in_region / HTTP 451？

4) 如何只换节点、不重新登录？

5) 额度在哪看？

安全提示

参考

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

2) `Public clients require PKCE`？

3) `unavailable_in_region` / HTTP 451？