block-proxy 0.1.12 → 0.1.13

package/docs/superpowers/specs/2026-05-27-blockproxyclient-design.md

@@ -0,0 +1,264 @@
+# BlockProxyClient macOS 桌面客户端设计
+
+## 概述
+
+BlockProxyClient 是一个 macOS 状态栏应用，用于连接 block-proxy 服务端的 SOCKS5 over TLS 代理服务。通过 xray-core 作为本地转发核心，提供本地 SOCKS5 和 HTTP 代理端口，并可选自动设置系统全局代理。
+
+## 技术选型
+
+| 层次 | 技术 | 理由 |
+|------|------|------|
+| UI 框架 | Python + rumps | 极简 macOS 状态栏库，几十行代码即可实现菜单+窗口 |
+| 转发核心 | xray-core | 成熟稳定，原生支持 SOCKS5 over TLS、本地 SOCKS/HTTP inbound、UDP |
+| 系统代理 | networksetup CLI | macOS 原生命令，无需额外依赖 |
+| 配置窗口 | tkinter | 多字段表单需要完整窗口控件（rumps.Window 仅支持单行输入） |
+| 打包 | py2app | 打包为 .app，内嵌 xray-core 二进制 |
+
+## 目录结构
+
+```
+client/
+├── main.py              # 入口，启动 rumps 状态栏应用
+├── app.py               # BlockProxyClient 主类（rumps.App 子类）
+├── config.py            # 节点配置管理（读写 JSON）
+├── xray_manager.py      # xray-core 进程管理（启动/停止/生成配置）
+├── system_proxy.py      # macOS 系统代理设置（networksetup 封装）
+├── resources/
+│   ├── icon.png         # 状态栏图标（已连接）
+│   ├── icon_off.png     # 状态栏图标（未连接）
+│   └── xray-core        # 内嵌的 xray-core 二进制（开发阶段可从 PATH 获取）
+├── requirements.txt     # rumps, py2app
+└── setup.py             # py2app 打包配置
+```
+
+## UI 设计
+
+### 状态栏菜单
+
+```
+[图标] BlockProxyClient
+├── ● 开启代理  /  ○ 关闭代理    （点击切换状态）
+├── 节点配置...                   （打开配置窗口）
+├── ─────────────
+├── ◉ 全局代理                    （自动设置系统 SOCKS/HTTP 代理）
+├── ○ 手动模式                    （仅启动本地监听，不修改系统设置）
+├── ─────────────
+└── 退出
+```
+
+### 状态栏图标
+
+- 未连接：灰色图标
+- 已连接：黑色/彩色图标
+
+### 节点配置窗口
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| 地址 | 文本输入 | 空 | 服务器 IP 或域名 |
+| 端口 | 数字输入 | 8002 | 服务端 SOCKS5 over TLS 端口 |
+| 用户名 | 文本输入 | 空 | SOCKS5 认证用户名 |
+| 密码 | 密码输入 | 空 | SOCKS5 认证密码 |
+| 启用 TLS | 复选框 | 开启 | 是否使用 TLS 加密连接 |
+| allowInsecure | 下拉 | true | 是否允许不安全证书（自签证书需设为 true） |
+| 本地 SOCKS 监听端口 | 数字输入 | 1080 | 本地 SOCKS5 代理端口 |
+| 本地 HTTP 监听端口 | 数字输入 | 1087 | 本地 HTTP 代理端口 |
+| 启用 UDP | 复选框 | 开启 | 是否启用 UDP 转发 |
+
+## 核心模块设计
+
+### config.py - 配置管理
+
+配置文件位置：`~/Library/Application Support/BlockProxyClient/config.json`
+
+```json
+{
+  "server": {
+    "address": "",
+    "port": 8002,
+    "username": "",
+    "password": "",
+    "tls": true,
+    "allowInsecure": true
+  },
+  "local": {
+    "socks_port": 1080,
+    "http_port": 1087,
+    "udp": true
+  },
+  "mode": "global"
+}
+```
+
+功能：
+- 读取/保存配置到 JSON 文件
+- 配置变更后通知其他模块（用于重启 xray）
+- 首次运行创建默认配置
+
+### xray_manager.py - xray-core 进程管理
+
+职责：
+1. 根据用户配置生成 xray JSON 配置文件
+2. 启动/停止 xray-core 子进程
+3. 监控进程状态（意外退出时通知 UI）
+
+生成的 xray 配置结构：
+
+```json
+{
+  "inbounds": [
+    {
+      "tag": "socks-in",
+      "port": "<local.socks_port>",
+      "listen": "127.0.0.1",
+      "protocol": "socks",
+      "settings": { "udp": "<local.udp>" }
+    },
+    {
+      "tag": "http-in",
+      "port": "<local.http_port>",
+      "listen": "127.0.0.1",
+      "protocol": "http"
+    }
+  ],
+  "outbounds": [
+    {
+      "protocol": "socks",
+      "settings": {
+        "servers": [{
+          "address": "<server.address>",
+          "port": "<server.port>",
+          "users": [{ "user": "<server.username>", "pass": "<server.password>" }]
+        }]
+      },
+      "streamSettings": {
+        "network": "tcp",
+        "security": "<tls|none>",
+        "tlsSettings": {
+          "allowInsecure": "<server.allowInsecure>",
+          "serverName": "<server.address>"
+        }
+      }
+    }
+  ]
+}
+```
+
+进程管理：
+- 启动：`subprocess.Popen([xray_path, "run", "-c", config_path], stdout=PIPE, stderr=PIPE)`
+- 停止：`process.terminate()` → 等待 3 秒 → `process.kill()`
+- xray-core 路径：开发时从 PATH 查找，打包后从 .app bundle Resources 目录读取
+- 健康检查：后台线程定期 poll 进程状态
+
+### system_proxy.py - macOS 系统代理
+
+通过 `networksetup` 命令操作：
+
+开启全局代理：
+```bash
+# 自动检测活跃网络接口（Wi-Fi / Ethernet / etc.）
+networksetup -setsocksfirewallproxy "<interface>" 127.0.0.1 <socks_port>
+networksetup -setsocksfirewallproxystate "<interface>" on
+networksetup -setwebproxy "<interface>" 127.0.0.1 <http_port>
+networksetup -setwebproxystate "<interface>" on
+networksetup -setsecurewebproxy "<interface>" 127.0.0.1 <http_port>
+networksetup -setsecurewebproxystate "<interface>" on
+```
+
+关闭全局代理：
+```bash
+networksetup -setsocksfirewallproxystate "<interface>" off
+networksetup -setwebproxystate "<interface>" off
+networksetup -setsecurewebproxystate "<interface>" off
+```
+
+安全机制：
+- `atexit` 注册清除代理的回调，防止程序崩溃后代理残留
+- 信号处理（SIGTERM, SIGINT）也清除代理
+
+网络接口检测：
+- 通过 `networksetup -listallnetworkservices` 获取所有接口
+- 通过 `networksetup -getinfo <interface>` 判断哪些接口活跃
+- 对所有活跃接口设置代理
+
+### app.py - 主应用
+
+rumps.App 子类，负责：
+1. 状态栏菜单渲染和事件处理
+2. 协调 config / xray_manager / system_proxy 三个模块
+3. 维护全局状态（是否已连接、当前模式）
+
+状态机：
+```
+初始 → [用户点击开启] → 读取配置 → 生成 xray config → 启动 xray → (全局代理模式?) → 设置系统代理 → 已连接
+已连接 → [用户点击关闭] → 清除系统代理 → 停止 xray → 未连接
+已连接 → [切换模式] → 设置/清除系统代理（xray 不重启）
+已连接 → [xray 意外退出] → 清除系统代理 → 更新 UI 为未连接
+```
+
+## 打包与分发
+
+### py2app 配置
+
+```python
+# setup.py
+from setuptools import setup
+
+APP = ['main.py']
+DATA_FILES = [('resources', ['resources/xray-core', 'resources/icon.png', 'resources/icon_off.png'])]
+OPTIONS = {
+    'argv_emulation': False,
+    'iconfile': 'resources/app_icon.icns',
+    'plist': {
+        'LSUIElement': True,
+        'CFBundleName': 'BlockProxyClient',
+        'CFBundleIdentifier': 'com.jaylli.blockproxyclient',
+    },
+    'packages': ['rumps'],
+}
+
+setup(
+    app=APP,
+    data_files=DATA_FILES,
+    options={'py2app': OPTIONS},
+    setup_requires=['py2app'],
+)
+```
+
+- `LSUIElement: True`：无 Dock 图标，仅状态栏显示
+- xray-core 二进制内嵌在 .app/Contents/Resources/ 中
+- 构建命令：`python setup.py py2app`
+
+### xray-core 获取
+
+开发阶段：
+- 从 xray-core GitHub Releases 下载对应平台二进制
+- 放入 `client/resources/xray-core`
+- 确保有执行权限
+
+## 依赖清单
+
+```
+# requirements.txt
+rumps>=0.4.0
+py2app>=0.28
+```
+
+运行时无其他 Python 依赖（xray-core 是独立二进制）。
+
+## 与服务端的协议兼容性
+
+客户端通过 xray-core 的 SOCKS outbound + TLS streamSettings 连接服务端，协议流程：
+
+```
+本地应用 → 本地 SOCKS5/HTTP (xray inbound)
+         → xray outbound: TLS 握手 → SOCKS5 认证 (username/password)
+         → SOCKS5 CONNECT/UDP ASSOCIATE
+         → 服务端 (socks5/server.js) → 下游 HTTP 代理 → 目标
+```
+
+兼容性要点：
+- 服务端使用自签证书 → 客户端 `allowInsecure: true`
+- 服务端认证方式：SOCKS5 username/password (RFC 1929)
+- 服务端支持 TCP CONNECT 和 UDP ASSOCIATE
+- TLS 最低版本：TLSv1.2（服务端设定）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "block-proxy",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "description": "Small-scale network mitm proxy filter",
   "bin": {
     "block-proxy": "bin/start.js"
@@ -17,7 +17,7 @@
   },
   "scripts": {
     "cp": "echo '----- program start -----'",
-    "rm_bkconfig": "rm ./config_backup.json",
+    "rm_bkconfig": "rm -f ./config_backup.json",
     "craco": "craco start",
     "dev": "BLOCK_PROXY_DEV=1 npm run express",
     "start": "npm run express",
@@ -25,9 +25,15 @@
     "express": "npm run cp && node ./server/start.js",
     "proxy": "npm run cp && node ./proxy/start.js",
     "build": "npm run rm_bkconfig && react-scripts build",
-    "docker:build": "npm run build && docker build -t block-proxy .",
-    "docker:build_arm": "npm run build && docker buildx build --platform linux/arm64/v8 -t block-proxy .",
+    "docker:build": "npm run build && docker buildx build --platform linux/amd64 --load -t block-proxy:amd64 .",
+    "docker:build:arm": "npm run build && docker buildx build --platform linux/arm64 --load -t block-proxy:arm64 .",
+    "docker:push": "npm run build && docker buildx build --platform linux/amd64 --push -t crpi-x1zji86f6jpcd7t1.cn-hangzhou.personal.cr.aliyuncs.com/lijing00333/block-proxy:latest-amd64 . && docker buildx build --platform linux/arm64 --push -t crpi-x1zji86f6jpcd7t1.cn-hangzhou.personal.cr.aliyuncs.com/lijing00333/block-proxy:latest-arm64 . && docker manifest create crpi-x1zji86f6jpcd7t1.cn-hangzhou.personal.cr.aliyuncs.com/lijing00333/block-proxy:latest crpi-x1zji86f6jpcd7t1.cn-hangzhou.personal.cr.aliyuncs.com/lijing00333/block-proxy:latest-amd64 crpi-x1zji86f6jpcd7t1.cn-hangzhou.personal.cr.aliyuncs.com/lijing00333/block-proxy:latest-arm64 && docker manifest push crpi-x1zji86f6jpcd7t1.cn-hangzhou.personal.cr.aliyuncs.com/lijing00333/block-proxy:latest",
+    "docker:push:amd64": "npm run build && docker buildx build --platform linux/amd64 --push -t crpi-x1zji86f6jpcd7t1.cn-hangzhou.personal.cr.aliyuncs.com/lijing00333/block-proxy:latest-amd64 .",
+    "docker:push:arm64": "npm run build && docker buildx build --platform linux/arm64 --push -t crpi-x1zji86f6jpcd7t1.cn-hangzhou.personal.cr.aliyuncs.com/lijing00333/block-proxy:latest-arm64 .",
     "test": "react-scripts test",
+    "gen-icons": "node client/watch-icons.js",
+    "watch:icons": "node client/watch-icons.js --watch",
+    "test:proxy": "node test/run.js",
     "eject": "react-scripts eject"
   },
   "devDependencies": {

package/proxy/proxy.js

@@ -57,7 +57,8 @@ var is_running_in_docker = false;
 var docker_host_IP = '';
 var enable_express = "1"; // "0", "1"
 var enable_socks5 = "1";
-var enable_webinterface = "1"; // "0", "1"
+var enable_webinterface = "0"; // "0", "1"
+var enable_mitm = "1"; // "0", "1"，是否对 HTTPS 启用 MITM 解密（关闭后纯隧道转发，不拦截）
 // 域名判断，区分浏览器和 App
 var filtered_mitm_domains = [
   ...uaFilter.filtered_mitm_domains
@@ -279,6 +280,9 @@ async function loadConfig() {
       enable_webinterface = loadedConfig.enable_webinterface;
       config.enable_webinterface = enable_webinterface;
 
+      enable_mitm = loadedConfig.enable_mitm || "1"; // 默认开启，兼容旧配置文件缺少此字段
+      config.enable_mitm = enable_mitm;
+
       socks5Port = loadedConfig.socks5_port;
       config.socks5_port = socks5Port;
 
@@ -315,6 +319,7 @@ async function loadConfig() {
         socks5_port: socks5Port,
         enable_socks5: enable_socks5,
         enable_webinterface: enable_webinterface,
+        enable_mitm: enable_mitm,
         vpn_proxy: ""
       });
       // fs.writeFileSync(configPath, JSON.stringify({
@@ -1086,30 +1091,29 @@ function getAnyProxyOptions() {
           }
         }
 
-        // rewrite 规则判断
-        if (shouldMitm(host)) {
-          return true; // 强制 MITM
+        // rewrite 规则判断（YouTube 去广告、有道词典 VIP 等）
+        // 这些规则需要 MITM 解密 response body，仅在 enable_mitm 开启时生效
+        if (enable_mitm == "1" && shouldMitm(host)) {
+          return true; // MITM 解密，执行 rewrite 规则
         }
 
-        // HTTPS 这里只判断 ip 源和域名
-        // 域名不匹配的就直接转发
-        // 域名匹配的情况下，再去看 match_rule 的判断，放到 beforeSendRequest 中
-
         // 如果是裸IP请求，全部放行
         if (net.isIPv4(host) || net.isIPv6(host)) {
           return false;
         }
 
-        // 如果没有对应ip的匹配规则
-        let shouldBlock = shouldBlockHost(host, blockRules, "");
-        if (blockRules.length === 0) {
+        // enable_mitm 关闭时纯隧道转发，不做任何拦截
+        if (enable_mitm != "1") {
           return false;
-        } else if (shouldBlock) {
+        }
+
+        let shouldBlock = shouldBlockHost(host, blockRules, "");
+        if (blockRules.length > 0 && shouldBlock) {
+          // 有证书：走 MITM 解密后在 beforeSendRequest 中做完整 URL 路径级过滤
           console.log('https 拦截', host, '接下来判断是否根据 match_rule 进行拦截');
-          // 只对配置中的域名进行 HTTPS 拦截
-          return true; // 允许 HTTPS 拦截
+          return true;
         }
-        return false; // 不拦截 HTTPS
+        return false; // 不拦截 HTTPS，透明隧道转发
       },
 
       // 拦截 HTTP 请求以及 HTTPS 拆包的请求

package/server/express.js

@@ -11,7 +11,7 @@ const { exec, execSync } = require('child_process');
 const LocalProxy = require('../proxy/proxy');
 
 const app = express();
-const PORT = 8004;
+const PORT = 8003;
 const DEV = process.env.BLOCK_PROXY_DEV || 0;
 const configPath = path.join(__dirname, '../config.json');
 
@@ -199,6 +199,22 @@ app.use(/\/proxy\/*/, async (req, res) => {
   }
 });
 
+// 证书下载接口
+app.get('/fetchCrtFile', (req, res) => {
+  try {
+    const certPath = path.join(__dirname, '../cert/rootCA.crt');
+    if (fs.existsSync(certPath)) {
+      res.setHeader('Content-Type', 'application/x-x509-ca-cert');
+      res.setHeader('Content-Disposition', 'attachment; filename="rootCA.crt"');
+      res.sendFile(certPath);
+    } else {
+      res.status(404).json({ error: '证书文件不存在，请先生成根证书' });
+    }
+  } catch (error) {
+    res.status(500).json({ error: '证书下载失败: ' + error.message });
+  }
+});
+
 // 3. 所有其他请求都返回 index.html（支持 React Router 的前端路由）
 app.get((req, res) => {
   res.sendFile(path.join(__dirname, 'build', 'index.html'));