2026-08-31 21:25:30 commit

Author: ZEROLINGG

README.md

@@ -1,90 +1,89 @@
-# free-proxy — 零成本私人独享代理
+# free-proxy — 零成本私人专属代理
 
-> 不用买 VPS、不用买域名、不用备案，只用 **Cloudflare 免费的 Worker**，就能部署一个私人且几乎无限流量的代理节点。
+> 无需购买 VPS，无需注册域名，无需备案，仅借助 **Cloudflare 免费 Worker** 服务，即可部署一个专属于个人使用、流量几乎不受限的代理节点。
 
 ---
 
-## 一、这是什么？
+## 一、项目简介
 
-`free-proxy` 是一个「客户端 + 免费中转服务」组成的私人代理方案：
+`free-proxy` 是一套由「客户端 + 免费中转服务」构成的私人代理方案：
 
-- **服务端**跑在 Cloudflare Worker 上——这是 Cloudflare 的**免费**服务，按免费额度提供日常请求量，个人上网绰绰有余；
-- **客户端**是桌面 / 手机上的一个小应用，负责加密、压缩、加速，并把流量交给你的 Worker 转发。
+- **服务端**部署于 Cloudflare Worker 之上——该服务为 Cloudflare 提供的**免费**产品，其免费额度足以满足个人日常使用需求；
+- **客户端**为运行于桌面或移动设备上的应用程序，负责数据的加密、压缩与加速处理，并通过 Worker 完成流量转发。
 
 <div><img alt="" src="./image/screenshot-20260821-194431.png"></div>
 <div><img alt="" src="./image/screenshot-20260818-164913.png"></div>
 
-### 它能给你带来什么
+### 核心特性
 
-- **免费**：全部依赖 Cloudflare 免费额度，零月租、零维护成本；
-- **独享**：节点只属于你，认证密钥只在你和设备两端；
-- **省流量**：内置压缩（zstd / lz4），相同内容传得少、跑得快；
-- **更安全**：多种加密算法可选（ChaCha20-Poly1305 / Ascon-AEAD128 等），传输内容被加密；
-- **自动挑最快的路**：内置「优选 IP」测速工具，帮你找到与 Worker 之间最快的网络路径；
-- **全家桶通用**：客户端可一键导出订阅链接，Clash / sing-box / v2rayN 等工具都能用；
-- **WebSocket支持**：内置 WebSocket 隧道，聊天 / 推送 / 在线协作等基于 `ws://` / `wss://` 的应用同样走加密代理；
-- **跨平台**：桌面（Windows / macOS / Linux）+ 手机（Android和iOS 实验性支持）。
+- **零成本**：全部功能依托 Cloudflare 免费额度实现，无需支付月租或维护费用；
+- **专属独享**：节点仅供个人使用，认证密钥仅存在于用户本人与设备之间；
+- **流量优化**：内置 zstd / lz4 压缩算法，有效降低传输数据量，提升访问速度；
+- **传输加密**：支持多种加密算法（ChaCha20-Poly1305、Ascon-AEAD128 等），保障传输内容的安全性；
+- **智能选路**：内置「优选 IP」测速工具，自动探测与 Worker 之间延迟最低的网络路径；
+- **广泛兼容**：客户端支持导出订阅链接，可直接用于 Clash、sing-box、v2rayN 等主流代理工具；
+- **WebSocket 支持**：内置 WebSocket 隧道，`ws://` / `wss://` 协议下的即时通信、消息推送、协同办公等应用均可正常经由加密代理访问；
+- **跨平台适配**：支持桌面端（Windows / macOS / Linux）及移动端（实验性支持）。
 
 ---
 
-## 二、你需要准备什么
-
-1. 一个 **Cloudflare 账号**（免费注册）；
-2. 一台**电脑**。
-3. 电脑上装好：**Node.js**、**Rust 工具链**、**pnpm**。
+## 二、前置条件
 
+1. 一个 **Cloudflare 账号**；
+2. 一台可用于操作的**计算机**；
+3. 该计算机需预先安装 **Node.js**、**Rust 工具链**及 **pnpm**。
 
 ---
 
-## 三、快速上手
+## 三、快速部署指南
 
-### 第 1 步：部署你的免费 Worker
+### 第一步：部署 Worker 服务端
 
 ```bash
-# 安装构建工具（只需一次）
+# 安装构建工具（仅需执行一次）
 cargo install -q "worker-build@^0.8"
 
-# 部署到 Cloudflare（首次会让你登录并选择账号）
+# 部署至 Cloudflare（首次执行时需登录并选择目标账号）
 cd server-rs
 wrangler deploy
 ```
 
-部署完成后，给 Worker 配置两个密钥（在 Cloudflare 控制台对应 Worker 的「设置 → 变量」里添加，或命令行执行）：
+部署完成后，需为 Worker 配置以下两项密钥（可在 Cloudflare 控制台对应 Worker 的「设置 → 变量」中添加，或通过命令行完成）：
 
-| 密钥       | 填什么          | 说明                                            |
-|----------|--------------|-----------------------------------------------|
-| `key`    | 你自己随便编一串字符   | 认证密钥，**请记好**，客户端要用同一个                         |
-| `domain` | 你的 Worker 域名 | 形如 `free-proxy.xxxx.workers.dev`，**注意不要带端口号** |
+| 密钥       | 填写内容        | 说明                                           |
+|----------|--------------|----------------------------------------------|
+| `key`    | 自定义字符串       | 认证密钥，**请妥善保存**，客户端需使用同一密钥                     |
+| `domain` | Worker 的域名   | 格式类似 `free-proxy.xxxx.workers.dev`，**注意不含端口号** |
 
-### 第 2 步：启动客户端
+### 第二步：启动客户端
 
 ```bash
 cd client_tauri
-pnpm tauri build   # 桌面端（Windows / macOS / Linux）
-# 然后安装运行构建的程序
+pnpm tauri build   # 编译桌面端应用（支持 Windows / macOS / Linux）
+# 编译完成后，安装并运行生成的应用程序
 ```
 
-打开应用后，进入「代理」页填写：
+打开应用程序后，进入「代理设置」页面并填写以下信息：
 
-- **域名**：和上面 `domain` 一致（如 `free-proxy.xxxx.workers.dev`）；
-- **认证密钥**：和上面 `key` 一致；
-- **协议**：默认 HTTP 即可（走 HTTPS 一般没必要）；
-- **本地端口**：默认 `8081`；
-- **算法**：一般默认即可。
+- **域名**：与上述配置的 `domain` 保持一致（如 `free-proxy.xxxx.workers.dev`）；
+- **认证密钥**：与上述配置的 `key` 保持一致；
+- **协议**：默认使用 HTTP 即可，通常无需启用 HTTPS；
+- **本地端口**：默认为 `8081`；
+- **算法**：一般保持默认设置即可。
 
-回到「仪表盘」，点击**启动代理**，等待「链路正常」+ 显示出口 IP
+返回「仪表盘」页面，点击**启动代理**，等待显示「链路正常」及当前出口 IP 即表示配置成功。
 
+### 第三步：导入订阅或设置代理
 
-### 第 3 步：导入订阅或设置代理
-- 复制仪表板中的订阅链接，使用你你的代理客户端（如clash,v2rayN）导入。
-- 或者在系统或浏览器（通过FoxyProxy或类似插件）直接设置http代理。
+- 复制仪表盘中提供的订阅链接，通过代理客户端（如 Clash、v2rayN）导入使用；
+- 或直接在操作系统或浏览器（借助 FoxyProxy 等插件）中配置 HTTP 代理。
 
-### 第 4 步：信任 CA 证书（访问 HTTPS 网站必需）
+### 第四步：安装信任 CA 证书（访问 HTTPS 站点必需）
 
-客户端要能解密 HTTPS，需要把应用生成的本地证书信任为系统根证书：
+若需通过客户端解密 HTTPS 流量，须将应用生成的本地证书添加至系统受信任的根证书列表：
 
-- 打开客户端的「CA 证书安装」页，点击**一键安装**；
-- **Linux 用户**需要先安装 `certutil`，各发行版命令：
+- 打开客户端「CA 证书安装」页面，点击**一键安装**；
+- **Linux 用户**需预先安装 `certutil` 工具，各发行版对应命令如下：
 
 ```bash
 # Debian / Ubuntu
@@ -95,79 +94,78 @@ sudo dnf install nss-tools
 sudo pacman -S nss
 ```
 
-> 该证书由你的设备本地生成并加密保存，只影响你自己的设备；换设备需重新导入。
+> 该证书由本地设备生成并加密存储，仅对当前设备生效；更换设备后需重新导入。
 
 ---
 
-## 四、优选 IP
-
+## 四、优选 IP 使用说明
 
-在「IP 优选测速」页点击开始，应用会自动对一批候选 IP 做两轮测速（连通性 + Worker 健康检查），并给出最优结果。把最优 IP 填进「代理」页的**优选 IP** 栏（或直接一键应用），下次启动即生效——网络不好时这一步往往立竿见影。
+在「IP 优选测速」页面点击开始测速，应用将对一批候选 IP 地址依次执行两轮测试（连通性检测与 Worker 健康检查），并给出最优结果。将测速得出的最优 IP 填入「代理设置」页面的**优选 IP** 一栏（或直接应用测速结果），重新启动即可生效。在网络状况不佳的情况下，该操作通常能显著改善连接质量。
 
-> 优选ip时请关闭tun或其他代理，否则将导致优选失败
+> 执行优选 IP 测速期间，请关闭 TUN 模式或其他代理工具，否则可能导致测速失败。
 
 ---
 
-## 五、常见问题（FAQ）
+## 五、常见问题
 
-**为什么连不上 / 无法上网？**
-按顺序排查：① 域名和密钥是否与 Worker 一致；② 本地端口是否被占用；③ HTTPS 站点是否已信任 CA 证书；④ 「验证 Worker」是否提示连接正常。
+**无法连接或无法正常上网？**
+请按以下顺序逐项排查：① 域名与密钥是否与 Worker 端配置一致；② 本地端口是否被其他程序占用；③ 是否已完成 HTTPS 站点所需的 CA 证书信任设置；④ 「验证 Worker」是否提示连接正常。
 
-**免费额度够用吗？**
-Cloudflare Workers 免费版每天提供约 10 万次请求额度，个人日常浏览、看网页、刷社交足够。大流量下载请留意用量，超限会暂停当天服务，次日自动恢复。
+**免费额度是否足够使用？**
+Cloudflare Workers 免费版每日提供约 10 万次请求额度，可满足日常浏览、网页访问及社交媒体使用需求。若进行大流量下载，请留意用量情况，超出限额将导致当日服务暂停，次日额度自动恢复。
 
-**为什么有的网站打不开？**
-部分站点对代理访问有限制，属正常现象；另外可尝试切换「优选 IP」或更换算法组合。
+**部分网站无法访问？**
+个别站点可能对代理访问设有限制，属正常现象。可尝试更换「优选 IP」或调整算法组合以改善访问情况。
 
-**大文件上传总是失败 / 很慢？**
-本地客户端与 Worker 对请求体做流式加解密，Cloudflare 免费版每个请求的 CPU 时间有限，超大请求体的累计解密/解压开销可能触顶导致传输中断。建议先压缩文件再上传，或升级 Workers Paid 提升上限。
+**大文件上传经常失败或速度较慢？**
+本地客户端与 Worker 之间对请求体采用流式加解密处理，而 Cloudflare 免费版对每次请求的 CPU 时间存在限制，超大文件累计的加解密开销可能触及该限制，导致传输中断。建议在上传前先对文件进行压缩，或升级至 Workers 付费版以提升处理上限。
 
-**为什么首次启动链路异常？**
-需要去「IP 优选测速」页点测速选择一个ip，否则无优选ip会回退到DNS解析，将导致获得受DNS污染的ip或tls握手时受到sni阻断。
+**首次启动时链路状态异常？**
+请前往「IP 优选测速」页面执行测速并选择合适的 IP。若未设置优选 IP，程序将回退至默认 DNS 解析方式，可能获取到受 DNS 污染影响的 IP 地址，或在 TLS 握手阶段遭遇基于 SNI 的连接阻断。
 
-**在哪里看日志 / 怎么开启 debug 日志？**
-客户端统一使用 `lib/log` 日志（`RUST_LOG` 控制等级与过滤，如 `RUST_LOG=debug`）。GUI 日志写入应用数据目录的 `logs/freeproxy.log`（1MB 轮转，ANSI 关闭）；命令行客户端输出到终端 stderr（带颜色）。Worker 端日志打印到控制台。
+**如何查看日志或开启调试日志？**
+客户端统一使用 `lib/log` 模块进行日志记录（可通过环境变量 `RUST_LOG` 控制日志级别及过滤条件，如 `RUST_LOG=debug`）。图形界面版本的日志写入应用数据目录下的 `logs/freeproxy.log` 文件（单文件上限 1MB，超出后自动轮转，不含 ANSI 颜色代码）；命令行版本的日志直接输出至终端标准错误流（带颜色标注）。Worker 端日志则输出至控制台。
 
 ---
 
 ## 六、工作原理
 
-### 普通Http请求
+### 普通 HTTP 请求
 
-普通 HTTP 请求走 `/api/{version}/{target}` 转发。
+普通 HTTP 请求经由 `/api/{version}/{target}` 路径完成转发：
 
 ```
 浏览器
-  │  （HTTP/HTTPS 明文交给本地客户端）
+  │  （以 HTTP/HTTPS 明文形式交付本地客户端）
   ▼
 本地客户端 ── 压缩 + 加密 ──▶ 免费 Worker ──▶ 目标网站
   ▲                                    │
   └────────── 加密返回 ────────────────┘
 ```
 
-- 浏览器把流量交给本地客户端；
-- 客户端**压缩 + 加密**后，通过Worker转发到目标网站；
-- Worker 拿到网站响应，再加密传回客户端解密，写回浏览器；
-- 通过http2请求worker。
+- 浏览器将流量转交给本地客户端处理；
+- 客户端对数据进行**压缩与加密**后，经由 Worker 转发至目标网站；
+- Worker 获取网站响应结果后，加密回传至客户端，客户端解密后写回浏览器；
+- 客户端与 Worker 之间的通信基于 HTTP/2 协议。
 
 ### WebSocket 隧道
 
-浏览器发起 `ws://` / `wss://` 升级请求时，会自动切换到独立的 WebSocket 隧道（`/ws/{version}/{target}`）：
+当浏览器发起 `ws://` / `wss://` 协议升级请求时，系统将自动切换至独立的 WebSocket 隧道（路径为 `/ws/{version}/{target}`）：
 
 ```
 浏览器 ── ws/wss 升级请求 + RFC 6455 帧 ──▶ 本地客户端 ── 加密隧道消息 ──▶ Worker ──▶ 上游 WS 服务器
    ▲                                                                                   │
    └────────── 原始 WS 帧（101 响应头 / 数据帧 / close 帧）零解析回写 ───────────────┘
 ```
 
-- **本地客户端**负责 RFC 6455 协议细节：帧解析、掩码解掩码、分片重组；浏览器的 Ping 帧本地直接回 Pong，不占用隧道带宽；
-- **Worker 端**与上游完成真正的 WebSocket 握手（含按客户端 key 计算 `Sec-WebSocket-Accept`），之后全双工转发，浏览器收到的仍是原始 WS 帧，text / binary / close 语义完整保留；
-- **保活**：隧道侧每 60 秒发一次 Ping（低于 Cloudflare 约 100 秒的空闲断开阈值），避免长连接被空闲回收；
-- 升级请求必须走 HTTP/1.1（HTTP/2 不支持 Upgrade 语义），客户端连接 Worker 的隧道通道已强制 HTTP/1.1。
+- **本地客户端**负责处理 RFC 6455 协议相关细节，包括帧解析、掩码处理及分片重组；浏览器发出的 Ping 帧由本地直接回复 Pong，不占用隧道带宽资源；
+- **Worker 端**与上游服务器完成实际的 WebSocket 握手过程（包括依据客户端密钥计算 `Sec-WebSocket-Accept`），随后执行全双工数据转发，浏览器所接收到的仍为原始 WS 帧，text / binary / close 等语义完整保留；
+- **连接保活机制**：隧道每隔 60 秒发送一次 Ping 帧（低于 Cloudflare 约 100 秒的空闲断开阈值），以避免长连接因空闲而被中断回收；
+- 由于协议升级请求必须基于 HTTP/1.1（HTTP/2 不支持 Upgrade 语义），客户端与 Worker 之间的隧道通信通道已强制采用 HTTP/1.1 协议。
 
-### 请求核心
-通过worker::Fetch 接口发送请求，而不是worker::Socket，不受限制，可以连接使用了cf服务的站点，能够解锁更多内容。
+### 核心请求机制
 
+系统通过 `worker::Fetch` 接口发送请求，而非 `worker::Socket`，因此不受相关限制，可正常连接使用 Cloudflare 服务的站点，从而实现更广泛的内容访问支持。
 
 ---
 
@@ -256,12 +254,9 @@ npm run test-e2e
 
 ### 安全模型
 
-- 密钥由 `auth_key + domain` 经 Sha256 哈希 + HKDF 派生，客户端与 Worker 两端独立推导出同一组密钥，无需网络传输密钥；
-- 每次请求的快速认证令牌由Ascon128 + 时间戳 + nonce 组成，服务端仅接受 ±30 秒内的令牌；
-- 本地 CA 私钥使用设备唯一标识 + 随机盐派生密钥加密存储，换设备需重新导入证书。
-
-
-
+- 密钥经由 `auth_key + domain` 依次执行 SHA-256 哈希与 HKDF 派生，客户端与 Worker 各自独立推导出相同的密钥组，全程无需通过网络传输密钥本身；
+- 每次请求所使用的快速认证令牌由 Ascon128、时间戳及随机数（nonce）共同构成，服务端仅接受时间窗口在 ±30 秒以内的有效令牌；
+- 本地 CA 私钥采用设备唯一标识与随机盐值派生出的密钥进行加密存储，更换设备后需重新导入证书。
 
 ### 客户端界面
 
@@ -270,12 +265,9 @@ npm run test-e2e
 
 ---
 
-## 许可
+## 许可协议
 
-本项目采用 **MIT OR Apache-2.0** 双许可。
+本项目采用 **MIT OR Apache-2.0** 双重许可协议。
 
 - [MIT License](LICENSE-MIT) — Copyright (c) 2026 ZEROLINGG
-- [Apache License 2.0](LICENSE-APACHE) — Copyright 2026 ZEROLINGG
-
-贡献即视为同意以相同双许可分发。
-
+- [Apache License 2.0](LICENSE-APACHE) — Copyright 2026 ZEROLINGG