block-proxy 0.1.11 → 0.1.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (62) hide show
  1. package/.agents/skills/commit/skill.md +40 -0
  2. package/.claude/settings.local.json +29 -1
  3. package/.claude/skills/build-client/skill.md +24 -0
  4. package/.claude/skills/commit/skill.md +34 -26
  5. package/.claude/skills/release-client/skill.md +68 -0
  6. package/CLAUDE.md +109 -47
  7. package/Dockerfile +1 -1
  8. package/README.md +69 -60
  9. package/build/asset-manifest.json +6 -6
  10. package/build/index.html +1 -1
  11. package/build/static/css/main.3f317ce6.css +2 -0
  12. package/build/static/css/main.3f317ce6.css.map +1 -0
  13. package/build/static/js/{main.2247fb80.js → main.68f66be0.js} +3 -3
  14. package/build/static/js/main.68f66be0.js.map +1 -0
  15. package/client/app.py +312 -0
  16. package/client/build.sh +84 -0
  17. package/client/config.py +49 -0
  18. package/client/config_window.py +155 -0
  19. package/client/icons/app.icns +0 -0
  20. package/client/icons/app_example.png +0 -0
  21. package/client/icons/app_icon.png +0 -0
  22. package/client/icons/backup/app_example.png +0 -0
  23. package/client/icons/backup/christmas-sock_dark.png +0 -0
  24. package/client/icons/backup/christmas-sock_light.png +0 -0
  25. package/client/icons/backup/socks_on_G.png +0 -0
  26. package/client/icons/backup/socks_on_M.png +0 -0
  27. package/client/icons/christmas-sock_dark.png +0 -0
  28. package/client/icons/christmas-sock_light.png +0 -0
  29. package/client/icons/christmas-sock_light_bar.png +0 -0
  30. package/client/icons/socks_on_G.png +0 -0
  31. package/client/icons/socks_on_G_bar.png +0 -0
  32. package/client/icons/socks_on_M.png +0 -0
  33. package/client/icons/socks_on_M_bar.png +0 -0
  34. package/client/main.py +28 -0
  35. package/client/proxy_core.py +475 -0
  36. package/client/requirements.txt +3 -0
  37. package/client/scripts/download_xray.sh +30 -0
  38. package/client/setup.py +30 -0
  39. package/client/system_proxy.py +94 -0
  40. package/client/tests/__init__.py +0 -0
  41. package/client/tests/test_config.py +72 -0
  42. package/client/tests/test_system_proxy.py +69 -0
  43. package/client/watch-icons.js +31 -0
  44. package/config.json +82 -5
  45. package/docs/superpowers/plans/2026-05-27-blockproxyclient.md +1274 -0
  46. package/docs/superpowers/specs/2026-05-27-blockproxyclient-design.md +264 -0
  47. package/package.json +11 -5
  48. package/proxy/proxy.js +70 -18
  49. package/server/express.js +17 -1
  50. package/skills-lock.json +11 -0
  51. package/socks5/server.js +2 -2
  52. package/src/App.css +596 -276
  53. package/src/App.js +25 -22
  54. package/src/index.css +3 -4
  55. package/test/lib/mock-server.js +133 -0
  56. package/test/proxy-tests.js +708 -0
  57. package/test/run.js +330 -0
  58. package/build/static/css/main.8bfa3d5f.css +0 -2
  59. package/build/static/css/main.8bfa3d5f.css.map +0 -1
  60. package/build/static/js/main.2247fb80.js.map +0 -1
  61. package/hack-of-anyproxy/lib/requestHandler.js +0 -1060
  62. /package/build/static/js/{main.2247fb80.js.LICENSE.txt → main.68f66be0.js.LICENSE.txt} +0 -0
@@ -0,0 +1,40 @@
1
+ ---
2
+ name: "commit"
3
+ description: "Analyze git changes, stage as needed, generate a Conventional Commit message, and create a commit."
4
+ argument-hint: "[optional commit intent]"
5
+ user-invocable: true
6
+ ---
7
+
8
+ # Skill: Smart Git Commit
9
+
10
+ Use this skill when the user runs `/commit` or asks to commit changes.
11
+
12
+ ## Instructions
13
+
14
+ 1. **Analyze Context**:
15
+ - Run `git status` to identify modified, added, or deleted files.
16
+ - Run `git diff` to inspect changes in unstaged files.
17
+ - Run `git diff --cached` to inspect changes in staged files.
18
+
19
+ 2. **Stage Changes**:
20
+ - If there are unstaged changes, run `git add -A` to stage all changes unless the user explicitly requested a partial commit.
21
+
22
+ 3. **Generate Commit Message**:
23
+ - Analyze diffs to understand the intent of changes.
24
+ - Draft a message following **Conventional Commits**:
25
+ ```
26
+ <type>(<scope>): <description>
27
+
28
+ [optional body]
29
+ ```
30
+ - **Type 使用英文**: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`。
31
+ - Scope 为可选,应反映受影响的功能区域。
32
+ - **标题示例格式**: `feat(world): WorldStore/RegionCache 架构与 runtime chunk streaming`
33
+ - **正文尽量使用中文编写**,描述具体变更细节和原因。
34
+
35
+ 4. **Execute Commit**:
36
+ - Run `git commit -m "generated_message"`.
37
+ - If a body is needed, use multiple `-m` flags.
38
+
39
+ 5. **Report**:
40
+ - Inform the user of the commit message used and commit result.
@@ -1,8 +1,36 @@
1
1
  {
2
2
  "permissions": {
3
3
  "allow": [
4
+ "Bash(git commit:*)",
4
5
  "Bash(git add:*)",
5
- "Bash(git commit:*)"
6
+ "Bash(tshark:*)",
7
+ "Bash(python3:*)",
8
+ "Bash(gh issue create:*)",
9
+ "Bash(docker system *)",
10
+ "Bash(grep -rn --include=\"*.js\" --include=\"*.ts\" --include=\"*.json\" -l \"benchmark\\\\|speed.test\\\\|speed_test\\\\|performance\\\\|latency\\\\|perf_test\\\\|perfTest\" /Users/hfy/jayli/block-proxy/ ! -path \"*/node_modules/*\")",
11
+ "Bash(grep -rn \"ping\\\\|latency\\\\|speed\\\\|perf\\\\|benchmark\\\\|timeout\" /Users/hfy/jayli/block-proxy/ --include=\"*.js\" --include=\"*.ts\" --include=\"*.sh\" ! -path \"*/node_modules/*\" ! -path \"*/build/*\")",
12
+ "Bash(oha *)",
13
+ "Bash(ping *)",
14
+ "Bash(brew install *)",
15
+ "Bash(npm run *)",
16
+ "Bash(pnpm i *)",
17
+ "Bash(break)",
18
+ "Bash(pkill -f \"node ./proxy/start.js\")",
19
+ "Bash(pkill -f \"node ./socks5/start.js\")",
20
+ "Bash(pkill -f \"node proxy/start.js\")",
21
+ "Bash(pkill -f \"node socks5/start.js\")",
22
+ "Bash(gh release *)",
23
+ "Read(//Library/Frameworks/Python.framework/Versions/**)",
24
+ "Bash(/Library/Frameworks/Python.framework/Versions/3.13/bin/python3 -m nuitka --version)",
25
+ "Bash(ps *)",
26
+ "Bash(pkill -f nuitka)",
27
+ "Bash(sips *)",
28
+ "Bash(git *)",
29
+ "Bash(command -v fswatch)",
30
+ "Bash(npm view *)",
31
+ "Bash(npx react-scripts *)",
32
+ "Bash(npm config *)",
33
+ "Bash(npm whoami *)"
6
34
  ]
7
35
  }
8
36
  }
@@ -0,0 +1,24 @@
1
+ ---
2
+ name: "build-client"
3
+ description: "构建 macOS 客户端 SocksClient.app(仅本地构建,不升级版本号)"
4
+ user-invocable: true
5
+ ---
6
+
7
+ # Skill: Build Client
8
+
9
+ 仅本地构建 macOS 客户端,不修改版本号,不发布。自动检测当前机器架构并构建对应版本。
10
+
11
+ 每次构建都会从 `client/icons/app_icon.png` 重新生成 `app.icns`,确保图标始终与源文件一致。
12
+
13
+ ## Instructions
14
+
15
+ 1. 执行构建脚本:
16
+ ```bash
17
+ bash client/build.sh
18
+ ```
19
+
20
+ 2. 构建完成后,报告结果:
21
+ - 架构:当前机器架构(由 `uname -m` 自动检测)
22
+ - 输出路径:`client/dist/SocksClient.app`
23
+ - 打包文件:`client/dist/SocksClient-macos-{arch}.zip`
24
+ - 告知用户构建是否成功
@@ -1,32 +1,40 @@
1
+ ---
2
+ name: "commit"
3
+ description: "Analyze git changes, stage as needed, generate a Conventional Commit message, and create a commit."
4
+ argument-hint: "[optional commit intent]"
5
+ user-invocable: true
6
+ ---
7
+
1
8
  # Skill: Smart Git Commit
2
9
 
3
10
  Use this skill when the user runs `/commit` or asks to commit changes.
4
11
 
5
12
  ## Instructions
6
13
 
7
- 1. **Analyze Context**:
8
- - Run `git status` to identify modified, added, or deleted files.
9
- - Run `git diff` to inspect the actual code changes in unstaged files.
10
- - Run `git diff --cached` to inspect changes in staged files.
11
-
12
- 2. **Stage Changes**:
13
- - If there are unstaged changes, run `git add -A` to stage all changes (unless the user specifically asked to partial commit).
14
-
15
- 3. **Generate Commit Message**:
16
- - Analyze the diffs to understand the *intent* of the changes.
17
- - Draft a commit message following the **Conventional Commits** specification:
18
- ```
19
- <type>(<scope>): <description>
20
-
21
- [optional body]
22
- ```
23
- - **Types**: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`.
24
- - **Scope**: (Optional) The module or file affected (e.g., `proxy`, `ui`, `deps`).
25
- - **Description**: Concise summary in imperative mood (e.g., "add support for...", not "added").
26
-
27
- 4. **Execute Commit**:
28
- - Run `git commit -m "generated_message"`.
29
- - If the message has a body, use multiple `-m` flags or a heredoc.
30
-
31
- 5. **Report**:
32
- - Inform the user of the commit message used and the result.
14
+ 1. **Analyze Context**:
15
+ - Run `git status` to identify modified, added, or deleted files.
16
+ - Run `git diff` to inspect changes in unstaged files.
17
+ - Run `git diff --cached` to inspect changes in staged files.
18
+
19
+ 2. **Stage Changes**:
20
+ - If there are unstaged changes, run `git add -A` to stage all changes unless the user explicitly requested a partial commit.
21
+
22
+ 3. **Generate Commit Message**:
23
+ - Analyze diffs to understand the intent of changes.
24
+ - Draft a message following **Conventional Commits**:
25
+ ```
26
+ <type>(<scope>): <description>
27
+
28
+ [optional body]
29
+ ```
30
+ - **Type 使用英文**: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`。
31
+ - Scope 为可选,应反映受影响的功能区域。
32
+ - **标题示例格式**: `feat(world): WorldStore/RegionCache 架构与 runtime chunk streaming`
33
+ - **正文尽量使用中文编写**,描述具体变更细节和原因。
34
+
35
+ 4. **Execute Commit**:
36
+ - Run `git commit -m "generated_message"`.
37
+ - If a body is needed, use multiple `-m` flags.
38
+
39
+ 5. **Report**:
40
+ - Inform the user of the commit message used and commit result.
@@ -0,0 +1,68 @@
1
+ ---
2
+ name: "release-client"
3
+ description: "构建并发布 macOS 客户端到 GitHub Release(自动从最新 release 版本号 patch +1)"
4
+ user-invocable: true
5
+ ---
6
+
7
+ # Skill: Release Client
8
+
9
+ 构建并发布 macOS 客户端到 GitHub Release。支持多架构(arm64 / x86_64),当前机器编译当前架构。
10
+
11
+ ## Instructions
12
+
13
+ ### 1. 获取当前架构和版本信息
14
+
15
+ - **检测架构**:`uname -m`(x86_64 或 arm64)
16
+ - `x86_64` → zip 名 `SocksClient-macos-x86_64.zip`
17
+ - `arm64` → zip 名 `SocksClient-macos-arm64.zip`
18
+
19
+ - **获取最新版本号**:
20
+ ```bash
21
+ gh release list --repo jayli/block-proxy --limit 1 --json tagName --jq '.[0].tagName'
22
+ ```
23
+ - 如果没有任何 release,初始版本为 `v0.1.0`
24
+ - 如果有,取 tag(如 `v0.1.2`),将 patch 版本 +1(→ `v0.1.3`)
25
+
26
+ ### 2. 确认发布策略
27
+
28
+ 向用户展示并确认:
29
+ - 当前架构
30
+ - 新版本号(是否创建新 release,还是追加到已有 release)
31
+ - **默认行为**:patch +1 创建新 release。如果用户指定追加到已有 release(如「加到 v0.1.0 里」),则跳过版本号递增和 git 提交,直接编译并上传资产
32
+
33
+ ### 3. 版本号更新(仅新建 release 时)
34
+
35
+ 新版本号记为 `$VERSION`(不含 `v` 前缀):
36
+ - `client/VERSION` → 写入 `$VERSION`
37
+ - `client/build.sh` → 替换 `VERSION="..."` 为 `VERSION="$VERSION"`
38
+ - `client/app.py` → 替换所有 `版本:v...` 为 `版本:v$VERSION`
39
+
40
+ ### 4. 构建
41
+
42
+ ```bash
43
+ bash client/build.sh
44
+ ```
45
+
46
+ 构建脚本自动检测当前架构,输出对应的 zip 文件。
47
+
48
+ ### 5. 提交并推送(仅新建 release 时)
49
+
50
+ - `git add client/VERSION client/build.sh client/app.py`
51
+ - `git commit -m "release(client): v$VERSION"`
52
+ - `git push`
53
+
54
+ ### 6. 创建或更新 GitHub Release
55
+
56
+ **新建 release**:
57
+ ```bash
58
+ gh release create v$VERSION client/dist/SocksClient-macos-{arch}.zip --title "SocksClient v$VERSION" --notes "SocksClient v$VERSION (macOS {arch})"
59
+ ```
60
+
61
+ **追加资产到已有 release**(tag 记为 `$TAG`,如 `v0.1.0`):
62
+ ```bash
63
+ gh release upload $TAG client/dist/SocksClient-macos-{arch}.zip --repo jayli/block-proxy --clobber
64
+ ```
65
+
66
+ ### 7. 报告结果
67
+
68
+ 展示 release URL 给用户:`https://github.com/jayli/block-proxy/releases/tag/$VERSION`
package/CLAUDE.md CHANGED
@@ -1,25 +1,35 @@
1
1
  # CLAUDE.md
2
2
 
3
- This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
3
+ This file provides guidance to Claude Code (claude.ai/code) when working with this repository.
4
4
 
5
5
  ## Common Commands
6
6
 
7
7
  ### Development
8
+ - `pnpm i` – Install dependencies (pnpm is the preferred package manager)
8
9
  - `npm run dev` – Start development mode with BLOCK_PROXY_DEV=1 (starts all services)
9
10
  - `npm run craco` – Start React development server with CRACO (port 3000)
10
11
  - `npm run start` / `npm run express` – Start backend + proxy server for production
11
12
  - `npm run proxy` – Start proxy only (no admin interface)
12
13
  - `npm run socks5` – Start SOCKS5 server only
14
+ - `npm run cp` – Print start banner (used internally by other scripts)
15
+
16
+ ### Testing
17
+ - `npm run test:proxy` – 一键代理连通性/性能/吞吐量测试(需先启动代理服务)
18
+ - `npm test` – Run React tests (currently limited, based on CRA defaults)
19
+
20
+ ### Utilities
21
+ - `npm run rm_bkconfig` – Remove backup config file
13
22
 
14
23
  ### Build & Deployment
15
24
  - `npm run build` – Build React frontend
16
- - `npm run docker:build` – Build Docker image for current architecture
17
- - `npm run docker:build_arm` – Build ARM64 Docker image
18
- - `npm test` – Run React tests
25
+ - `npm run docker:build` – Build Docker image (amd64)
26
+ - `npm run docker:build:arm` – Build ARM64 Docker image
27
+ - `npm run docker:push` – Build and push amd64 + arm64 dual-arch to ACR (needs `docker login` first)
28
+ - `npm run docker:push:amd64` / `npm run docker:push:arm64` – Push single architecture
19
29
  - `npm run eject` – Eject from Create React App (irreversible)
20
30
 
21
31
  ### Global CLI
22
- - `block-proxy` – Start the proxy system (auto-restart on failure)
32
+ - `block-proxy` – Start the proxy system (auto-restart on failure, max 10000 times)
23
33
  - `block-proxy -c rule.js` – Start with external MITM rule configuration
24
34
 
25
35
  ## Architecture Overview
@@ -28,36 +38,28 @@ Block-Proxy is a MITM-based proxy filtering tool designed for parental control a
28
38
 
29
39
  ### Core Components
30
40
 
31
- 1. **Proxy Engine** (`/proxy/`)
32
- - `proxy.js` – Main AnyProxy integration with MITM logic
33
- - `mitm/` – MITM rule implementations (YouTube ads, dictionary, etc.)
34
- - `scan.js` – Network scanning for device discovery (every 2 hours)
35
- - `fs.js` Configuration file management
41
+ 1. **Proxy Engine** (`/proxy/`) – 核心入口 `proxy.js`,集成 AnyProxy 实现 MITM 请求/响应过滤。`attacker.js` 执行拦截判断,`domain.js` 做 host 匹配,`fs.js` 管理 config.json 读写备份,`scan.js` 每 2 小时 ARP 扫描发现设备。`mitm/` 子目录包含规则定义(`rule.js`)和具体的响应修改器(YouTube 去广告、有道词典 VIP)
42
+
43
+ 2. **SOCKS5 Proxy** (`/socks5/`)SOCKS5 over TLS 实现(端口 8002),TLS 握手认证后通过 CONNECT 隧道转发至 AnyProxy
44
+
45
+ 3. **Backend Server** (`/server/`) – Express API 服务器(端口 8003)。`start.js` 根据 config 决定启动完整栈还是仅代理模式
36
46
 
37
- 2. **SOCKS5 Proxy** (`/socks5/`)
38
- - `server.js` – SOCKS5 over TLS implementation (port 8002)
39
- - `start.js` – SOCKS5 server entry point
47
+ 4. **React Frontend** (`/src/`) – CRA + CRACO 构建的管理界面,`App.js` 为主组件
40
48
 
41
- 3. **Backend Server** (`/server/`)
42
- - `express.js` – Express.js API server for admin interface (port 8004)
43
- - `start.js` – Main server entry point (decides whether to start admin UI)
49
+ 5. **Test Suite** (`/test/`) – `run.js` 一键测试入口(自动启动 Mock Server),`proxy-tests.js` 覆盖 HTTP/SOCKS5 连通性、延迟、并发、吞吐量
44
50
 
45
- 4. **React Frontend** (`/src/`)
46
- - `App.js` – Admin interface for managing blocking rules
47
- - Built with Create React App, configured via CRACO
51
+ 6. **CLI** (`/bin/start.js`) – 全局命令入口,失败自动重启(max 10000 次),退出时清理全局配置
48
52
 
49
- 5. **CLI Interface** (`/bin/`)
50
- - `start.js` – Global CLI entry point with auto-restart capabilities and config cleanup
53
+ 7. **AnyProxy Fork** (`node_modules/@bachi/anyproxy/`) – 核心 MITM 代理引擎,fork 自 AnyProxy 的私有 npm 包(v0.1.5)。关键源码:`proxy.js`(入口)、`lib/requestHandler.js`(HTTP/HTTPS 请求处理与转发)、`lib/httpsServerMgr.js`(HTTPS MITM 服务管理、动态证书生成)、`lib/certMgr.js`(根证书与域名证书管理)。所有底层连接处理、TLS 拦截、请求转发的实现分析都应从此包查找
51
54
 
52
- 6. **Configuration** (`config.json`)
53
- - Runtime configuration: ports, blocked hosts, authentication
54
- - Auto-saved from admin interface
55
+ 8. **TLS Certificates** (`/cert/`) – `rootCA.key` + `rootCA.crt`,Docker 构建时复制到容器的 `~/.anyproxy/certificates/`,客户端需安装此证书才能 HTTPS MITM
56
+
57
+ 9. **Configuration** (`config.json`) 运行时配置(非源码),由 `proxy/fs.js` 管理。关键字段:`block_hosts[]`, `proxy_port`, `socks5_port`, `enable_express`, `enable_socks5`, `devices[]`, `auth_username`, `auth_password`
55
58
 
56
59
  ### Port Configuration
57
- - `8001` – HTTP proxy port (mandatory)
60
+ - `8001` – HTTP proxy port (mandatory, AnyProxy)
58
61
  - `8002` – SOCKS5 over TLS port (optional)
59
- - `8003` – AnyProxy monitoring interface (optional)
60
- - `8004` – Admin configuration interface (optional)
62
+ - `8003` – Admin configuration interface (Express,原 AnyProxy 监控端口已永久关闭)
61
63
  - `3000` – React development server (dev only)
62
64
 
63
65
  ### Entry Points
@@ -65,50 +67,110 @@ Block-Proxy is a MITM-based proxy filtering tool designed for parental control a
65
67
  - **Proxy-only**: `proxy/start.js` → `proxy/proxy.js`
66
68
  - **Development**: `npm run dev` → starts everything with dev flag
67
69
 
70
+ ### Request Flow
71
+ ```
72
+ Client → HTTP Proxy (8001) → AnyProxy → MITM Rules → Target Server
73
+ → SOCKS5 (8002) → TLS → SOCKS5 Server → HTTP Proxy (8001) → Target Server
74
+ ```
75
+ SOCKS5 先做 TLS 握手和认证,然后通过 CONNECT 命令建立隧道,将 TCP 流量转发至下游 HTTP 代理。
76
+
68
77
  ## Key Patterns
69
78
 
70
79
  ### MITM Rule System
71
80
  - Host-based blocking with regex pattern matching
72
81
  - Time-based restrictions (start/end times, weekdays)
73
- - MAC address targeting for device-specific rules
82
+ - MAC address targeting for device-specific rules (HTTP proxy only)
74
83
  - YouTube ad blocking with predefined regex patterns
75
84
  - Custom rule injection via external `rule.js` configuration
85
+ - Two rule types: `beforeSendRequest` and `beforeSendResponse`
86
+ - Built-in rules: YouTube ad removal, Youdao Dictionary VIP unlock
87
+
88
+ **Adding Custom MITM Rules:**
89
+ 1. Edit `proxy/mitm/rule.js` for built-in rules, or
90
+ 2. Create external rule file and start with `block-proxy -c rule.js`
91
+ 3. Rule structure: `{ type, host, regexp, callback }` where callback receives `(url, request, response)`
92
+ 4. See `example/rule.js` for reference
76
93
 
77
94
  ### Configuration Management
78
95
  - Configuration stored in `config.json` at runtime
79
- - Supports external rule files via `-c` flag
80
- - Network device scanning every 2 hours (stored in `config.json`)
96
+ - Supports external rule files via `-c` flag (global config via `_fs.setGlobalConfigFile()`)
97
+ - Network device scanning every 2 hours (stored in `config.json` as `devices[]`)
81
98
  - Auto-clears global config file on exit/restart
99
+ - Backup config: `config_backup.json` (removed on build)
100
+
101
+ ### Block Host Rule Structure
102
+ ```javascript
103
+ {
104
+ "filter_host": "example.com", // Host pattern
105
+ "filter_match_rule": "^https?://...", // URL regex (optional)
106
+ "filter_start_time": "00:00", // Start time
107
+ "filter_end_time": "23:59", // End time
108
+ "filter_weekday": [1,2,3,4,5,6,7], // 1=Monday, 7=Sunday
109
+ "filter_mac": "AA:BB:CC:DD:EE:FF" // Target device (optional)
110
+ }
111
+ ```
82
112
 
83
113
  ### Deployment Patterns
84
114
  - Designed for OpenWRT router deployment with host networking (`--network=host`)
85
115
  - Docker container with volume mounting for configuration
86
116
  - Multi-architecture support (ARM/X86)
87
- - Auto-restart on failure with config cleanup
117
+ - Auto-restart on failure with config cleanup (3 second delay, max 10000 restarts)
88
118
  - Production vs. development modes controlled by `BLOCK_PROXY_DEV` env var
89
119
 
90
120
  ### Development Workflow
91
121
  1. **Development**: `npm run dev` starts proxy + admin UI + SOCKS5 (if enabled)
92
- 2. **Testing**: Proxy-only mode with `npm run proxy`
93
- 3. **Building**: `npm run build` compiles React frontend to `/build/`
94
- 4. **Docker**: Separate commands for x86 and ARM architectures
122
+ 2. **Frontend Development**: `npm run craco` starts React dev server (port 3000),CRACO 将 `/api` 请求代理到 Express 后端端口 8003
123
+ 3. **Testing**: Proxy-only mode with `npm run proxy`
124
+ 4. **Building**: `npm run build` compiles React frontend to `/build/`
125
+ 5. **Docker**: Dockerfile 基于 Node 18 Alpine(多阶段构建),本地开发可用更高版本 Node
95
126
 
96
127
  ### Dependencies
97
- - `@bachi/anyproxy` Modified AnyProxy fork for MITM
98
- - `express` – Backend API server
99
- - `react`, `react-dom` Frontend framework
100
- - `commander` CLI argument parsing
101
- - `axios` HTTP client for API calls
102
- - `qrcode` Certificate QR code generation for MITM setup
128
+ **Note:** `@bachi/anyproxy` 与较新 Node.js 版本不完全兼容,因此连同大多数运行时依赖一起放在 `devDependencies` 中(查看 package.json 了解完整列表)
129
+
130
+ **核心依赖 `@bachi/anyproxy`(v0.1.5):** fork 自开源 AnyProxy 的私有 npm 包,是整个代理系统的底层引擎。分析连接处理、TLS 拦截、请求转发等底层逻辑时,应直接阅读 `node_modules/@bachi/anyproxy/` 的源码(而非项目根目录下的其他备份)。关键文件:
131
+ - `proxy.js` 包入口,创建代理服务器实例
132
+ - `lib/requestHandler.js` HTTP/HTTPS 请求处理与转发核心
133
+ - `lib/httpsServerMgr.js` HTTPS MITM 服务管理、动态伪造证书
134
+ - `lib/certMgr.js` — 根证书与域名证书的生成和管理
135
+
136
+ ## macOS Client (`/client/`)
137
+
138
+ macOS 状态栏代理客户端,纯 Python 实现,连接远端 SOCKS5 over TLS 服务。
139
+
140
+ ### Commands
141
+ - `python main.py` – 直接运行客户端(开发模式)
142
+ - `bash build.sh` – Nuitka 一键构建 macOS .app(输出到 `dist/SocksClient.app`)
143
+ - `cd client && pytest tests/` – 运行客户端单元测试
144
+ - 删除 `icons/app.icns` 后再 `bash build.sh` 可强制重新生成应用图标
145
+
146
+ ### Architecture
147
+ ```
148
+ main.py (入口, 文件锁单实例) → app.py (rumps 状态栏 App)
149
+ ├── proxy_core.py (asyncio SOCKS5/HTTP 代理核心)
150
+ ├── config.py (配置读写, ~/Library/Application Support/SocksClient/)
151
+ ├── config_window.py (tkinter 配置窗口, 独立进程启动)
152
+ └── system_proxy.py (macOS 系统代理 networksetup)
153
+ ```
154
+
155
+ ### Key Design Decisions
156
+ - **纯 Python 替代 xray-core**:公司安全软件(云壳)按二进制特征码拦截 xray-core、py2app、PyInstaller,因此用 asyncio + ssl 模块纯 Python 实现 SOCKS5 over TLS 协议,用 Nuitka 编译为原生二进制
157
+ - **代理协议流程**:本地应用 → 本地 SOCKS5(1080)/HTTP(1087) → TLS 连接远端 → SOCKS5 握手(用户名密码认证) → CONNECT → 双向 relay
158
+ - **私有地址直连**:127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 等私有地址段不走代理,直接连接(可通过配置项关闭)
159
+ - **UI 线程安全**:代理启动/停止在后台线程执行,UI 更新通过 `AppHelper.callAfter()` 调度回主线程
160
+ - **config_window.py 作为独立进程**:tkinter 窗口通过 `subprocess.Popen` 用系统 Python 启动(Nuitka 编译后 `sys.executable` 不是 Python 解释器),关闭后自动检测配置变化并重启代理
161
+ - **Nuitka 构建后处理**:`build.sh` 自动重命名可执行文件、修正 Info.plist(CFBundleExecutable、LSUIElement 等)
103
162
 
104
163
  ## Important Notes
105
- - SOCKS5 proxy does not support MAC address targeting (only HTTP proxy does)
106
- - Clients must install AnyProxy certificate for HTTPS MITM inspection
107
- - Service needs network scanning permissions (best deployed on OpenWRT gateway)
108
- - Admin interface allows real-time rule management with proxy restart
109
- - Docker builds use Chinese npm registry (registry.npmmirror.com) by default
164
+ - **Testing 陷阱**: 通过代理请求 `127.0.0.1` 会被 AnyProxy 拦截返回管理页面。Mock Server 需绑定 `0.0.0.0` 并通过 LAN IP 访问
165
+ - SOCKS5 不支持 MAC 地址定向拦截(仅 HTTP 代理支持)
166
+ - 客户端必须安装 `cert/` 目录下的 AnyProxy 证书才能启用 HTTPS MITM(URL 路径过滤、广告重写)。未安装证书时,将 `enable_mitm` 设为 `"0"` 可切换为纯隧道转发模式,关闭所有 MITM 解密和拦截,零证书错误
167
+ - Docker 构建默认使用 npmmirror.com 镜像源
168
+ - iOS Safari 安全限制:带认证的代理不能和网关 IP 相同
169
+ - 路由表每 2 小时刷新;新设备可能需要手动刷新
170
+ - ACR 推送前需先 `docker login --username=hi50078584@aliyun.com crpi-x1zji86f6jpcd7t1.cn-hangzhou.personal.cr.aliyuncs.com`
110
171
 
111
172
  # Project Rules & Skills
112
173
 
113
- - **Import Skill**: 实时遵循 `.claude/skills/*/skill.md` 中的指令。
114
-
174
+ - **Local Skills**: 实时遵循 `.claude/skills/*/skill.md` 中的指令。可用技能: `commit`, `pcap-analyse`
175
+ - **CLI入口**: 全局命令 `block-proxy` 注册在 `bin/start.js`,通过 `npm i -g` 安装后可直接调用
176
+ - **config.json** 是运行时配置文件(非源码),由 `proxy/fs.js` 管理读写和备份,不在 git 中追踪变更
package/Dockerfile CHANGED
@@ -45,7 +45,7 @@ COPY cert/rootCA.crt /root/.anyproxy/certificates/
45
45
 
46
46
  USER nodeuser
47
47
 
48
- EXPOSE 8001 8002 8003
48
+ EXPOSE 8001 8002
49
49
 
50
50
  # 使用 node 启动脚本作为 CMD
51
51
  CMD ["npm", "run", "start"]