ipclick 0.3.0__tar.gz → 0.4.0__tar.gz

ipclick-0.3.0/README.md → ipclick-0.4.0/PKG-INFO

@@ -1,3 +1,48 @@
+Metadata-Version: 2.4
+Name: ipclick
+Version: 0.4.0
+Summary: IPClick Tool
+License: MIT
+License-File: LICENSE
+Author: 元气码农少女酱
+Author-email: 1276162429@qq.com
+Requires-Python: >=3.11
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Provides-Extra: camoufox
+Provides-Extra: drissionpage
+Provides-Extra: linux
+Provides-Extra: niquests
+Provides-Extra: patchright
+Provides-Extra: playwright
+Provides-Extra: win
+Requires-Dist: camoufox (>=0.5.4,<1.0.0) ; extra == "camoufox"
+Requires-Dist: camoufox (>=0.5.4,<1.0.0) ; extra == "linux"
+Requires-Dist: click (>=8.4.2,<9.0.0)
+Requires-Dist: curl-cffi (>=0.16.0,<0.17.0)
+Requires-Dist: drissionpage (>=4.1.1,<5.0.0) ; extra == "drissionpage"
+Requires-Dist: drissionpage (>=4.1.1,<5.0.0) ; extra == "win"
+Requires-Dist: fake-useragent (>=2.2.0,<3.0.0)
+Requires-Dist: grpcio (>=1.83.0,<2.0.0)
+Requires-Dist: grpcio-health-checking (>=1.83.0,<2.0.0)
+Requires-Dist: loguru (>=0.7.3,<0.8.0)
+Requires-Dist: niquests (>=3.21.0,<4.0.0) ; extra == "niquests"
+Requires-Dist: patchright (>=1.61.2,<2.0.0) ; extra == "linux"
+Requires-Dist: patchright (>=1.61.2,<2.0.0) ; extra == "patchright"
+Requires-Dist: playwright (>=1.60.0,<2.0.0) ; extra == "playwright"
+Requires-Dist: protobuf (>=6.33.2,<8.0.0)
+Requires-Dist: python-box[all] (>=7.4.1,<8.0.0)
+Requires-Dist: typing-extensions (>=4.16.0,<5.0.0)
+Requires-Dist: uuid-utils (>=0.17.0,<0.18.0)
+Project-URL: Bug Tracker, https://github.com/yuanqimanong/IPClick/issues
+Project-URL: Homepage, https://github.com/yuanqimanong/IPClick
+Project-URL: Repository, https://github.com/yuanqimanong/IPClick
+Description-Content-Type: text/markdown
+
 # IPClick
 
 ![IPClick Logo](https://raw.githubusercontent.com/yuanqimanong/IPClick/master/docs/logo.png)
@@ -40,7 +85,9 @@ IPClick 是一个轻量级、高性能的分布式 HTTP 请求代理工具，基
 - **链路记录**：每个请求记一条（谁执行的、重试几次、排队多久），内存环形缓冲 + 可选 SQLite，零第三方依赖
 - **SSRF 防护**：服务端对目标 URL 做协议白名单与内网/元数据地址拦截
 - **Web 管理端**：`ipclick run --web` 起一个带登录的界面——总览看板、实时请求流、
-  「试一试」就地发请求看源码、配置改完写回 `ipclick.toml`、集群节点增删
+  「试一试」就地发请求看源码（支持粘贴 curl、可点名目标节点）、配置改完写回
+  `ipclick.toml`、集群节点增删（保存即生效）与就地测连通性 / 鉴权、可选组件的
+  装卸。左中右三栏布局 + 明暗主题切换，前端零构建链路
 - **命令行工具**：提供便捷的 CLI 工具，支持快速启动服务和查看配置
 - **Docker 支持**：多阶段构建、非 root 运行的镜像
 - **完整类型标注**：随包提供 `py.typed`，下游可直接享受类型检查
@@ -83,6 +130,9 @@ playwright install chromium     # playwright
 只做第一步的话，`ipclick config-info` 与 Web 端会明确显示 **「包已装，浏览器本体未就绪」**，
 请求会直接报 `FAILED_PRECONDITION` 并告诉你该跑哪条命令。
 
+上面这些也可以**直接在 Web 端点按钮完成**（0.4 起）：`/components` 页列出全部五个
+可选组件的两级安装状态，就地装 / 卸、下载浏览器本体，装完不用重启进程。
+
 > **刻意不让它在请求里自动下载。** camoufox 的 API 默认行为是"缺本体就当场下"
 > （`camoufox_path(download_if_missing=True)`），而那一刻已经在 gRPC 的请求处理线程上：
 > 第一个请求会卡着下 1 GB 然后超时，超时返回后下载还在后台跑，并发的多个首请求
@@ -142,6 +192,9 @@ ipclick run --config /path/to/ipclick.toml
 
 # 显示详细日志
 ipclick run --verbose
+
+# 同一目录起第二个实例：gRPC 与 Web 两个端口都要岔开
+ipclick run --port 9528 --web-port 9531 -w
 ```
 
 初始化配置（推荐）：
@@ -220,20 +273,41 @@ IPCLICK_WEB_USER=ops IPCLICK_WEB_PASSWORD=... ipclick run -w
 
 或写进 `.env`，或配 `[WEB].username` / `password`。
 
-#### 五个页面
+#### 六个页面
+
+0.4 布局大改版：**左侧导航 + 主内容 + 右侧状态栏**的 CSS Grid，右上角有
+**跟随系统 / 亮 / 暗** 三态主题切换（记在 `localStorage`，刷新不丢）。
 
 | 页面 | 干什么 |
 |---|---|
-| **总览** `/` | 吞吐、成功率、在途与峰值、各适配器耗时与流量、状态码分布、引擎安装状态、集群拓扑、最近 12 条请求 |
-| **请求流** `/trace` | **实时**（3 秒刷新）看请求打进来。按状态 / 适配器 / URL 过滤，看目标站点排行与按天趋势 |
-| **试一试** `/test` | 填一个网址就地发一次请求，看链路信息与返回的**源码** |
-| **配置** `/config` | 白名单内的行为配置可改，**写回 `ipclick.toml`** |
-| **节点** `/nodes` | 集群节点的增删改，同样写回 `ipclick.toml` |
+| **总览** `/` | 吞吐、成功率、在途与峰值、状态码分布、各适配器耗时与流量、集群拓扑、最近请求；右栏常驻服务端 / 安全 / 链路 / 限流 / 组件状态 |
+| **请求流** `/trace` | **实时**看请求打进来。按状态 / 适配器 / URL 过滤，看目标站点排行与按天趋势 |
+| **试一试** `/test` | 填一个网址（或直接**粘一条 curl**）就地发一次请求，看链路信息与返回的**源码**；可**点名**打到某个节点 |
+| **组件** `/components` | 五个可选 extras 的两级安装状态，可以就地**安装 / 卸载 / 下载浏览器本体** |
+| **配置** `/config` | 白名单内的行为配置可改，**写回 `ipclick.toml`**；可一键**生成凭据** |
+| **节点** `/nodes` | 集群节点的增删改（**保存即生效**，不用重启）+ 就地**测试连接** |
 
 「试一试」走的是本进程 `TaskService` 的**同一条**代码路径——SSRF 准入、限流、
 以及开了转发时的分发全都照常生效，请求也会像真实请求一样出现在请求流里。
 另写一条只在页面上成立的路径毫无意义：那验证的就不是线上行为了。
 
+**从 curl 导入**：浏览器 DevTools 里对着请求「复制为 cURL」，粘进输入框就能自动
+填好 URL / 方法 / 请求头 / 请求体。认不出的参数会**明确列出来**——静默丢掉一个
+`-F` 比不支持它更糟。
+
+**指定目标节点**：开了服务端转发时，「试一试」多一个"目标节点"下拉，选中后跳过
+负载均衡强制打到那一台。验证新加的机器配对没有，不用再反复点、靠轮询碰运气。
+
+**测试连接**：`/nodes` 每行一个按钮，只验**连通性**与**集群内部鉴权**，不发业务
+请求。失败时区分"连不上"（查进程和网络）和"鉴权不通过"（核对各节点 `.env` 里的
+`IPCLICK_CLUSTER_SECRET`）——这两种的排查方向完全相反。底层是 0.4 新增的
+`Ping` RPC；对着 0.3 的节点调会收到 `UNIMPLEMENTED`，那恰恰说明鉴权是通的，
+页面会如实这么说，不会误报成鉴权失败。
+
+**生成凭据**：`/config` 可以为鉴权令牌、Web 密码、集群共享密钥各生成一个随机值，
+**只显示一次**（服务端不保存、不写进任何文件，取完即弃），并明确区分"本机独有"
+和"必须复制到所有其他节点的 `.env`"——集群共享密钥每台各自生成一个就全对不上了。
+
 #### 能改什么、不能改什么
 
 - **能改**（写回 toml，保留注释与格式，改动前留 `.bak`）：超时、重试、按 host
@@ -241,20 +315,33 @@ IPCLICK_WEB_USER=ops IPCLICK_WEB_PASSWORD=... ipclick run -w
 - **不能改**：`[SECURITY]` 全部（令牌、TLS、SSRF 三个开关）、Web 自己的登录凭据、
   集群共享密钥与各节点 token、`[BROWSER].allow_scripts`。这些只展示，要改请编辑
   文件 / `.env` 后重启。
-- **不装东西**：引擎的安装状态只**展示**，附上安装命令让人自己去那台机器上跑。
-  让网页能执行安装命令等于给它一个任意命令执行的入口。
+- **能装依赖**（0.4 放开，此前刻意不给）：`/components` 可以装 / 卸 IPClick 自己
+  声明的那五个 extras，以及下载浏览器本体。包名走**白名单常量**（表单里传来的
+  extra 必须能在清单里查到），命令以列表形式交给 `subprocess`（`shell=False`），
+  并**绑定当前解释器**——不依赖 PATH 上的 `pip`，装到别的环境去比装不上更糟。
+  `pip` 和 `uv pip` 两条路自动探测（uv 建的 venv 默认不装 pip），两者都没有时
+  明确报错并给出手动命令。长任务（`camoufox fetch` 要下约 1 GB）跑在后台，
+  页面轮询状态。**卸载只卸 Python 包**，浏览器本体不动——界面会把它的路径和
+  体积摆出来，让人自己决定，从网页递归删一个 GB 级目录风险和收益不成比例。
 
 这条线是刻意划的：这个服务能代任意 URL 发请求，一个能从网页关掉内网拦截、改掉
-令牌的管理端，等于给自己装了个跳板。而调超时、加节点这类操作改错了也只是性能
-或可用性问题，可逆、可见。
+令牌的管理端，等于给自己装了个跳板。而调超时、加节点、装一个自己声明过的可选
+依赖，这类操作改错了也只是性能或可用性问题，可逆、可见。
 
 写回是**定点文本替换**而不是"读成 dict 再整体 dump"：那份配置里几乎每一项都带着
 解释（为什么默认是这个值、配错了什么症状），整体 dump 会把它们全抹掉。所以只换
 被改动那一行等号右边的值，行尾注释都保留。写入用临时文件 + `os.replace`，
 断电不会留下半个配置文件。
 
-页面里**一行 JavaScript 都没有**，自动刷新用 `<meta refresh>`，CSP 收到
-`default-src 'none'`。
+前端**没有构建链路**：没有模板引擎、框架、打包工具，也没有任何外部资源。
+布局是纯 CSS Grid，交互是几十行原生 JS——0.3 时页面里一行 JS 都没有，0.4 加了
+三件没有 JS 就做不好的事：手动切主题、装依赖的状态轮询、请求流的**局部刷新**
+（`<meta refresh>` 每 3 秒重载整页，滚动位置丢失、正在填的过滤条件被冲掉、
+页面白闪；现在只换那一块的 HTML，而且仍然由服务端渲染，不在 JS 里复制一份逻辑）。
+
+CSP 里 `script-src` 用的是那两段内联脚本的 **sha256 哈希**，不是
+`'unsafe-inline'`——脚本是源码里的常量，哈希能精确放行它们，同时让任何注入进来的
+`<script>` 执行不了。
 
 安全措施：会话 cookie 带 `HttpOnly` + `SameSite=Strict`，所有写操作校验 CSRF
 token，登录失败按来源 IP 限速（5 次后锁定 5 分钟，锁定期间正确密码也不放行），
@@ -842,6 +929,7 @@ IPClick/
 │       ├── health.py            # grpc.health.v1 健康检查
 │       ├── trace.py             # 链路记录（内存环形缓冲 + 可选 SQLite）
 │       ├── compression.py       # 请求压缩策略（自动化脚本压缩收益最大）
+│       ├── components.py        # 五个可选 extras 的清单、两级安装状态、分类
 │       ├── limiter.py           # 按 host 的并发与 QPS 闸门
 │       ├── exceptions.py        # 异常层次
 │       ├── py.typed             # 类型标注标记
@@ -863,17 +951,22 @@ IPClick/
 │       │   ├── forwarder.py     # ForwardingTaskService（服务端转发）
 │       │   ├── tokens.py        # 由共享密钥派生每节点独立令牌
 │       │   ├── discovery.py     # static / dns 节点发现
+│       │   ├── probe.py         # 节点探测：连得上吗、鉴权配对吗
 │       │   └── status_page.py   # 只读状态页
-│       ├── web/                 # Web 管理端（仅标准库，页面里没有 JS）
-│       │   ├── server.py        # HTTP 服务、会话、CSRF、路由
+│       ├── web/                 # Web 管理端（仅标准库，无前端构建链路）
+│       │   ├── server.py        # HTTP 服务、会话、CSRF、路由、CSP
 │       │   ├── pages.py         # 各页面的数据与操作
 │       │   ├── templates.py     # HTML 渲染（每处插值都要过 esc）
+│       │   ├── assets.py        # CSS 与 JS（CSP 用脚本哈希放行）
+│       │   ├── installer.py     # 装 / 卸可选组件（白名单 + 后台任务）
+│       │   ├── curl_parser.py   # 把 curl 命令解析成「试一试」表单
 │       │   ├── editable.py      # 可编辑配置项白名单
 │       │   └── auth.py          # 凭据、会话、登录限速
 │       ├── cli/                 # 命令行工具
 │       ├── config_loader/       # 配置加载
 │       │   ├── loader.py        # 优先级与环境变量覆盖
 │       │   ├── dotenv.py        # .env 解析
+│       │   ├── placeholders.py  # 路径里的 {port} 占位符
 │       │   └── writer.py        # 写回 toml（定点替换，保留注释）
 │       ├── configs/             # 默认配置文件
 │       ├── dto/                 # 数据传输对象
@@ -882,6 +975,7 @@ IPClick/
 │       │   └── proto/           # Protobuf 定义与生成脚本
 │       ├── services/            # gRPC 服务实现
 │       └── utils/               # 工具模块（日志、配置、URL 安全校验等）
+│           └── module_probe.py  # 不执行模块代码的"装没装"探测（find_spec）
 ├── docker/                      # Docker 相关文件
 ├── examples/                    # 示例代码
 ├── tests/                       # 测试代码
@@ -987,7 +1081,7 @@ healthy, status = check_health("10.0.0.1:9527", timeout=3)
 [TRACE]
 memory_size = 500          # 内存环形缓冲，始终开启，零磁盘
 sqlite_enabled = false     # 落盘（默认关）。开了 Web 端才能查历史与跨天统计
-sqlite_path = "ipclick-trace.db"
+sqlite_path = "ipclick-trace.{port}.db"   # {port} = 运行时实际监听端口
 retention_days = 30        # 超期的每小时清一次；0 = 永久
 only_errors = false        # 只记失败请求（成功量极大时省磁盘）
 record_url = true          # 关掉后只记 host
@@ -1022,6 +1116,45 @@ print(resp.raw.trace.queued_ms)  # 在限流闸门里排了多久
 > 爆炸），所以回答不了"我刚才那个请求为什么 403"。而这个库的使用场景恰恰是后者。
 > 聚合数字这边也有——进程内计数器实时累加，代价只是重启归零。
 
+#### 同一目录起多个实例：`{port}` 占位符
+
+`sqlite_path` 与 `[LOG].output` 的路径值支持 `{port}` 占位符，替换成**运行时实际
+生效**的监听端口（`--port` 覆盖之后的那个，不是配置文件里的原始值）：
+
+```toml
+[TRACE]
+sqlite_path = "ipclick-trace.{port}.db"   # -> ipclick-trace.9528.db
+
+[LOG]
+output = "logs/{port}/app.log"            # 占位符在路径中间也行
+```
+
+不这么做的话，同一目录用 `--port` 起的多个实例会**静默**写同一个库、抢同一个日志
+文件：不报错、不提示，用户以为在看单个实例的数据，实际是多进程合并的结果。
+（真撞上了也会打一条明确的告警，但那是兜底，不是解法。）
+
+用占位符而不是在代码里"自动加端口后缀"是刻意的：新用户从模板拿到的默认值就带
+`{port}`，天然按端口分离；已有部署里自己写死的路径**一个字符都不会被改**，否则
+旧日志和 trace 数据看起来就像丢了。而且这条规则写在 toml 里是**看得见的**。
+
+Web 端口也有了对应的命令行覆盖（gRPC 端口一直有 `--port`，Web 端此前没有）：
+
+```bash
+ipclick run --port 9528 --web-port 9531 -w
+```
+
+#### `[LOG].output` 的两种写法
+
+```toml
+[LOG]
+output = "stdout"           # 只打控制台（默认）
+output = "logs/app.log"     # 写这个文件（没有扩展名时自动补 .log）
+output = "logs/"            # 以斜杠结尾 = 写进这个**目录**，文件名用 ipclick.log
+```
+
+最后一种在 0.3 会被静默改写成同级的 `logs.log`（目录名被当成缺扩展名的文件名），
+0.4 修了。
+
 ### 安全配置
 
 服务端会代替调用方请求任意 URL。**若监听在公网或不可信网络，请开启内网拦截**，
@@ -1238,3 +1371,4 @@ uv run python src/ipclick/dto/proto/generate.py
 本项目采用 [MIT License](https://github.com/yuanqimanong/IPClick/blob/master/LICENSE) 开源许可证。
 
 Copyright (c) 2025 元气码农少女酱
+

ipclick-0.3.0/PKG-INFO → ipclick-0.4.0/README.md

@@ -1,48 +1,3 @@
-Metadata-Version: 2.4
-Name: ipclick
-Version: 0.3.0
-Summary: IPClick Tool
-License: MIT
-License-File: LICENSE
-Author: 元气码农少女酱
-Author-email: 1276162429@qq.com
-Requires-Python: >=3.11
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Provides-Extra: camoufox
-Provides-Extra: drissionpage
-Provides-Extra: linux
-Provides-Extra: niquests
-Provides-Extra: patchright
-Provides-Extra: playwright
-Provides-Extra: win
-Requires-Dist: camoufox (>=0.5.0,<1.0.0) ; extra == "camoufox"
-Requires-Dist: camoufox (>=0.5.0,<1.0.0) ; extra == "linux"
-Requires-Dist: click (>=8.4.2,<9.0.0)
-Requires-Dist: curl-cffi (>=0.16.0,<0.17.0)
-Requires-Dist: drissionpage (>=4.1.0,<5.0.0) ; extra == "drissionpage"
-Requires-Dist: drissionpage (>=4.1.0,<5.0.0) ; extra == "win"
-Requires-Dist: fake-useragent (>=2.2.0,<3.0.0)
-Requires-Dist: grpcio (>=1.83.0,<2.0.0)
-Requires-Dist: grpcio-health-checking (>=1.83.0,<2.0.0)
-Requires-Dist: loguru (>=0.7.3,<0.8.0)
-Requires-Dist: niquests (>=3.14.0,<4.0.0) ; extra == "niquests"
-Requires-Dist: patchright (>=1.52.0,<2.0.0) ; extra == "linux"
-Requires-Dist: patchright (>=1.52.0,<2.0.0) ; extra == "patchright"
-Requires-Dist: playwright (>=1.49.0,<2.0.0) ; extra == "playwright"
-Requires-Dist: protobuf (>=6.33.2,<8.0.0)
-Requires-Dist: python-box[all] (>=7.4.1,<8.0.0)
-Requires-Dist: typing-extensions (>=4.15.0,<5.0.0)
-Requires-Dist: uuid-utils (>=0.17.0,<0.18.0)
-Project-URL: Bug Tracker, https://github.com/yuanqimanong/IPClick/issues
-Project-URL: Homepage, https://github.com/yuanqimanong/IPClick
-Project-URL: Repository, https://github.com/yuanqimanong/IPClick
-Description-Content-Type: text/markdown
-
 # IPClick
 
 ![IPClick Logo](https://raw.githubusercontent.com/yuanqimanong/IPClick/master/docs/logo.png)
@@ -85,7 +40,9 @@ IPClick 是一个轻量级、高性能的分布式 HTTP 请求代理工具，基
 - **链路记录**：每个请求记一条（谁执行的、重试几次、排队多久），内存环形缓冲 + 可选 SQLite，零第三方依赖
 - **SSRF 防护**：服务端对目标 URL 做协议白名单与内网/元数据地址拦截
 - **Web 管理端**：`ipclick run --web` 起一个带登录的界面——总览看板、实时请求流、
-  「试一试」就地发请求看源码、配置改完写回 `ipclick.toml`、集群节点增删
+  「试一试」就地发请求看源码（支持粘贴 curl、可点名目标节点）、配置改完写回
+  `ipclick.toml`、集群节点增删（保存即生效）与就地测连通性 / 鉴权、可选组件的
+  装卸。左中右三栏布局 + 明暗主题切换，前端零构建链路
 - **命令行工具**：提供便捷的 CLI 工具，支持快速启动服务和查看配置
 - **Docker 支持**：多阶段构建、非 root 运行的镜像
 - **完整类型标注**：随包提供 `py.typed`，下游可直接享受类型检查
@@ -128,6 +85,9 @@ playwright install chromium     # playwright
 只做第一步的话，`ipclick config-info` 与 Web 端会明确显示 **「包已装，浏览器本体未就绪」**，
 请求会直接报 `FAILED_PRECONDITION` 并告诉你该跑哪条命令。
 
+上面这些也可以**直接在 Web 端点按钮完成**（0.4 起）：`/components` 页列出全部五个
+可选组件的两级安装状态，就地装 / 卸、下载浏览器本体，装完不用重启进程。
+
 > **刻意不让它在请求里自动下载。** camoufox 的 API 默认行为是"缺本体就当场下"
 > （`camoufox_path(download_if_missing=True)`），而那一刻已经在 gRPC 的请求处理线程上：
 > 第一个请求会卡着下 1 GB 然后超时，超时返回后下载还在后台跑，并发的多个首请求
@@ -187,6 +147,9 @@ ipclick run --config /path/to/ipclick.toml
 
 # 显示详细日志
 ipclick run --verbose
+
+# 同一目录起第二个实例：gRPC 与 Web 两个端口都要岔开
+ipclick run --port 9528 --web-port 9531 -w
 ```
 
 初始化配置（推荐）：
@@ -265,20 +228,41 @@ IPCLICK_WEB_USER=ops IPCLICK_WEB_PASSWORD=... ipclick run -w
 
 或写进 `.env`，或配 `[WEB].username` / `password`。
 
-#### 五个页面
+#### 六个页面
+
+0.4 布局大改版：**左侧导航 + 主内容 + 右侧状态栏**的 CSS Grid，右上角有
+**跟随系统 / 亮 / 暗** 三态主题切换（记在 `localStorage`，刷新不丢）。
 
 | 页面 | 干什么 |
 |---|---|
-| **总览** `/` | 吞吐、成功率、在途与峰值、各适配器耗时与流量、状态码分布、引擎安装状态、集群拓扑、最近 12 条请求 |
-| **请求流** `/trace` | **实时**（3 秒刷新）看请求打进来。按状态 / 适配器 / URL 过滤，看目标站点排行与按天趋势 |
-| **试一试** `/test` | 填一个网址就地发一次请求，看链路信息与返回的**源码** |
-| **配置** `/config` | 白名单内的行为配置可改，**写回 `ipclick.toml`** |
-| **节点** `/nodes` | 集群节点的增删改，同样写回 `ipclick.toml` |
+| **总览** `/` | 吞吐、成功率、在途与峰值、状态码分布、各适配器耗时与流量、集群拓扑、最近请求；右栏常驻服务端 / 安全 / 链路 / 限流 / 组件状态 |
+| **请求流** `/trace` | **实时**看请求打进来。按状态 / 适配器 / URL 过滤，看目标站点排行与按天趋势 |
+| **试一试** `/test` | 填一个网址（或直接**粘一条 curl**）就地发一次请求，看链路信息与返回的**源码**；可**点名**打到某个节点 |
+| **组件** `/components` | 五个可选 extras 的两级安装状态，可以就地**安装 / 卸载 / 下载浏览器本体** |
+| **配置** `/config` | 白名单内的行为配置可改，**写回 `ipclick.toml`**；可一键**生成凭据** |
+| **节点** `/nodes` | 集群节点的增删改（**保存即生效**，不用重启）+ 就地**测试连接** |
 
 「试一试」走的是本进程 `TaskService` 的**同一条**代码路径——SSRF 准入、限流、
 以及开了转发时的分发全都照常生效，请求也会像真实请求一样出现在请求流里。
 另写一条只在页面上成立的路径毫无意义：那验证的就不是线上行为了。
 
+**从 curl 导入**：浏览器 DevTools 里对着请求「复制为 cURL」，粘进输入框就能自动
+填好 URL / 方法 / 请求头 / 请求体。认不出的参数会**明确列出来**——静默丢掉一个
+`-F` 比不支持它更糟。
+
+**指定目标节点**：开了服务端转发时，「试一试」多一个"目标节点"下拉，选中后跳过
+负载均衡强制打到那一台。验证新加的机器配对没有，不用再反复点、靠轮询碰运气。
+
+**测试连接**：`/nodes` 每行一个按钮，只验**连通性**与**集群内部鉴权**，不发业务
+请求。失败时区分"连不上"（查进程和网络）和"鉴权不通过"（核对各节点 `.env` 里的
+`IPCLICK_CLUSTER_SECRET`）——这两种的排查方向完全相反。底层是 0.4 新增的
+`Ping` RPC；对着 0.3 的节点调会收到 `UNIMPLEMENTED`，那恰恰说明鉴权是通的，
+页面会如实这么说，不会误报成鉴权失败。
+
+**生成凭据**：`/config` 可以为鉴权令牌、Web 密码、集群共享密钥各生成一个随机值，
+**只显示一次**（服务端不保存、不写进任何文件，取完即弃），并明确区分"本机独有"
+和"必须复制到所有其他节点的 `.env`"——集群共享密钥每台各自生成一个就全对不上了。
+
 #### 能改什么、不能改什么
 
 - **能改**（写回 toml，保留注释与格式，改动前留 `.bak`）：超时、重试、按 host
@@ -286,20 +270,33 @@ IPCLICK_WEB_USER=ops IPCLICK_WEB_PASSWORD=... ipclick run -w
 - **不能改**：`[SECURITY]` 全部（令牌、TLS、SSRF 三个开关）、Web 自己的登录凭据、
   集群共享密钥与各节点 token、`[BROWSER].allow_scripts`。这些只展示，要改请编辑
   文件 / `.env` 后重启。
-- **不装东西**：引擎的安装状态只**展示**，附上安装命令让人自己去那台机器上跑。
-  让网页能执行安装命令等于给它一个任意命令执行的入口。
+- **能装依赖**（0.4 放开，此前刻意不给）：`/components` 可以装 / 卸 IPClick 自己
+  声明的那五个 extras，以及下载浏览器本体。包名走**白名单常量**（表单里传来的
+  extra 必须能在清单里查到），命令以列表形式交给 `subprocess`（`shell=False`），
+  并**绑定当前解释器**——不依赖 PATH 上的 `pip`，装到别的环境去比装不上更糟。
+  `pip` 和 `uv pip` 两条路自动探测（uv 建的 venv 默认不装 pip），两者都没有时
+  明确报错并给出手动命令。长任务（`camoufox fetch` 要下约 1 GB）跑在后台，
+  页面轮询状态。**卸载只卸 Python 包**，浏览器本体不动——界面会把它的路径和
+  体积摆出来，让人自己决定，从网页递归删一个 GB 级目录风险和收益不成比例。
 
 这条线是刻意划的：这个服务能代任意 URL 发请求，一个能从网页关掉内网拦截、改掉
-令牌的管理端，等于给自己装了个跳板。而调超时、加节点这类操作改错了也只是性能
-或可用性问题，可逆、可见。
+令牌的管理端，等于给自己装了个跳板。而调超时、加节点、装一个自己声明过的可选
+依赖，这类操作改错了也只是性能或可用性问题，可逆、可见。
 
 写回是**定点文本替换**而不是"读成 dict 再整体 dump"：那份配置里几乎每一项都带着
 解释（为什么默认是这个值、配错了什么症状），整体 dump 会把它们全抹掉。所以只换
 被改动那一行等号右边的值，行尾注释都保留。写入用临时文件 + `os.replace`，
 断电不会留下半个配置文件。
 
-页面里**一行 JavaScript 都没有**，自动刷新用 `<meta refresh>`，CSP 收到
-`default-src 'none'`。
+前端**没有构建链路**：没有模板引擎、框架、打包工具，也没有任何外部资源。
+布局是纯 CSS Grid，交互是几十行原生 JS——0.3 时页面里一行 JS 都没有，0.4 加了
+三件没有 JS 就做不好的事：手动切主题、装依赖的状态轮询、请求流的**局部刷新**
+（`<meta refresh>` 每 3 秒重载整页，滚动位置丢失、正在填的过滤条件被冲掉、
+页面白闪；现在只换那一块的 HTML，而且仍然由服务端渲染，不在 JS 里复制一份逻辑）。
+
+CSP 里 `script-src` 用的是那两段内联脚本的 **sha256 哈希**，不是
+`'unsafe-inline'`——脚本是源码里的常量，哈希能精确放行它们，同时让任何注入进来的
+`<script>` 执行不了。
 
 安全措施：会话 cookie 带 `HttpOnly` + `SameSite=Strict`，所有写操作校验 CSRF
 token，登录失败按来源 IP 限速（5 次后锁定 5 分钟，锁定期间正确密码也不放行），
@@ -887,6 +884,7 @@ IPClick/
 │       ├── health.py            # grpc.health.v1 健康检查
 │       ├── trace.py             # 链路记录（内存环形缓冲 + 可选 SQLite）
 │       ├── compression.py       # 请求压缩策略（自动化脚本压缩收益最大）
+│       ├── components.py        # 五个可选 extras 的清单、两级安装状态、分类
 │       ├── limiter.py           # 按 host 的并发与 QPS 闸门
 │       ├── exceptions.py        # 异常层次
 │       ├── py.typed             # 类型标注标记
@@ -908,17 +906,22 @@ IPClick/
 │       │   ├── forwarder.py     # ForwardingTaskService（服务端转发）
 │       │   ├── tokens.py        # 由共享密钥派生每节点独立令牌
 │       │   ├── discovery.py     # static / dns 节点发现
+│       │   ├── probe.py         # 节点探测：连得上吗、鉴权配对吗
 │       │   └── status_page.py   # 只读状态页
-│       ├── web/                 # Web 管理端（仅标准库，页面里没有 JS）
-│       │   ├── server.py        # HTTP 服务、会话、CSRF、路由
+│       ├── web/                 # Web 管理端（仅标准库，无前端构建链路）
+│       │   ├── server.py        # HTTP 服务、会话、CSRF、路由、CSP
 │       │   ├── pages.py         # 各页面的数据与操作
 │       │   ├── templates.py     # HTML 渲染（每处插值都要过 esc）
+│       │   ├── assets.py        # CSS 与 JS（CSP 用脚本哈希放行）
+│       │   ├── installer.py     # 装 / 卸可选组件（白名单 + 后台任务）
+│       │   ├── curl_parser.py   # 把 curl 命令解析成「试一试」表单
 │       │   ├── editable.py      # 可编辑配置项白名单
 │       │   └── auth.py          # 凭据、会话、登录限速
 │       ├── cli/                 # 命令行工具
 │       ├── config_loader/       # 配置加载
 │       │   ├── loader.py        # 优先级与环境变量覆盖
 │       │   ├── dotenv.py        # .env 解析
+│       │   ├── placeholders.py  # 路径里的 {port} 占位符
 │       │   └── writer.py        # 写回 toml（定点替换，保留注释）
 │       ├── configs/             # 默认配置文件
 │       ├── dto/                 # 数据传输对象
@@ -927,6 +930,7 @@ IPClick/
 │       │   └── proto/           # Protobuf 定义与生成脚本
 │       ├── services/            # gRPC 服务实现
 │       └── utils/               # 工具模块（日志、配置、URL 安全校验等）
+│           └── module_probe.py  # 不执行模块代码的"装没装"探测（find_spec）
 ├── docker/                      # Docker 相关文件
 ├── examples/                    # 示例代码
 ├── tests/                       # 测试代码
@@ -1032,7 +1036,7 @@ healthy, status = check_health("10.0.0.1:9527", timeout=3)
 [TRACE]
 memory_size = 500          # 内存环形缓冲，始终开启，零磁盘
 sqlite_enabled = false     # 落盘（默认关）。开了 Web 端才能查历史与跨天统计
-sqlite_path = "ipclick-trace.db"
+sqlite_path = "ipclick-trace.{port}.db"   # {port} = 运行时实际监听端口
 retention_days = 30        # 超期的每小时清一次；0 = 永久
 only_errors = false        # 只记失败请求（成功量极大时省磁盘）
 record_url = true          # 关掉后只记 host
@@ -1067,6 +1071,45 @@ print(resp.raw.trace.queued_ms)  # 在限流闸门里排了多久
 > 爆炸），所以回答不了"我刚才那个请求为什么 403"。而这个库的使用场景恰恰是后者。
 > 聚合数字这边也有——进程内计数器实时累加，代价只是重启归零。
 
+#### 同一目录起多个实例：`{port}` 占位符
+
+`sqlite_path` 与 `[LOG].output` 的路径值支持 `{port}` 占位符，替换成**运行时实际
+生效**的监听端口（`--port` 覆盖之后的那个，不是配置文件里的原始值）：
+
+```toml
+[TRACE]
+sqlite_path = "ipclick-trace.{port}.db"   # -> ipclick-trace.9528.db
+
+[LOG]
+output = "logs/{port}/app.log"            # 占位符在路径中间也行
+```
+
+不这么做的话，同一目录用 `--port` 起的多个实例会**静默**写同一个库、抢同一个日志
+文件：不报错、不提示，用户以为在看单个实例的数据，实际是多进程合并的结果。
+（真撞上了也会打一条明确的告警，但那是兜底，不是解法。）
+
+用占位符而不是在代码里"自动加端口后缀"是刻意的：新用户从模板拿到的默认值就带
+`{port}`，天然按端口分离；已有部署里自己写死的路径**一个字符都不会被改**，否则
+旧日志和 trace 数据看起来就像丢了。而且这条规则写在 toml 里是**看得见的**。
+
+Web 端口也有了对应的命令行覆盖（gRPC 端口一直有 `--port`，Web 端此前没有）：
+
+```bash
+ipclick run --port 9528 --web-port 9531 -w
+```
+
+#### `[LOG].output` 的两种写法
+
+```toml
+[LOG]
+output = "stdout"           # 只打控制台（默认）
+output = "logs/app.log"     # 写这个文件（没有扩展名时自动补 .log）
+output = "logs/"            # 以斜杠结尾 = 写进这个**目录**，文件名用 ipclick.log
+```
+
+最后一种在 0.3 会被静默改写成同级的 `logs.log`（目录名被当成缺扩展名的文件名），
+0.4 修了。
+
 ### 安全配置
 
 服务端会代替调用方请求任意 URL。**若监听在公网或不可信网络，请开启内网拦截**，
@@ -1283,4 +1326,3 @@ uv run python src/ipclick/dto/proto/generate.py
 本项目采用 [MIT License](https://github.com/yuanqimanong/IPClick/blob/master/LICENSE) 开源许可证。
 
 Copyright (c) 2025 元气码农少女酱
-

{ipclick-0.3.0 → ipclick-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ipclick"
-version = "0.3.0"
+version = "0.4.0"
 description = "IPClick Tool"
 authors = [
     { name = "元气码农少女酱", email = "1276162429@qq.com" }
@@ -18,7 +18,7 @@ dependencies = [
     "loguru>=0.7.3,<0.8.0",
     "python-box[all]>=7.4.1,<8.0.0",
     "uuid-utils>=0.17.0,<0.18.0",
-    "typing-extensions>=4.15.0,<5.0.0",
+    "typing-extensions>=4.16.0,<5.0.0",
 ]
 
 [project.optional-dependencies]
@@ -26,25 +26,29 @@ dependencies = [
 # 另一个可选的是 niquests —— requests 的 drop-in 替代，额外支持 HTTP/2 与 HTTP/3。
 # （httpx 曾经也在这里，0.3.0 移除：它和 niquests 能力重叠，
 #   而 niquests 还多支持 HTTP/3，维护两套等价的 HTTP 适配器不划算。）
-niquests = ["niquests>=3.14.0,<4.0.0"]
+niquests = ["niquests>=3.21.0,<4.0.0"]
 
 # 浏览器渲染引擎。装完还要各自准备浏览器本体：
 #   camoufox     python -m camoufox fetch
 #   patchright   patchright install chromium
 #   playwright   playwright install chromium
 #   drissionpage 用本机已装的 Chrome/Chromium，无需下载
-camoufox = ["camoufox>=0.5.0,<1.0.0"]
-patchright = ["patchright>=1.52.0,<2.0.0"]
-drissionpage = ["drissionpage>=4.1.0,<5.0.0"]
-playwright = ["playwright>=1.49.0,<2.0.0"]
+camoufox = ["camoufox>=0.5.4,<1.0.0"]
+patchright = ["patchright>=1.61.2,<2.0.0"]
+drissionpage = ["drissionpage>=4.1.1,<5.0.0"]
+# ⚠️ 上限**必须**留在 camoufox 能接受的范围内：camoufox 0.5.4 自己钉着
+# playwright<1.61，把这里的下限提到 1.62 会让 [camoufox] 和 [playwright]
+# 直接互斥（uv 会报 unsatisfiable）。而 camoufox 是 Linux 上的默认引擎，
+# 为了追一个更新的 playwright 把它挤掉不划算。
+playwright = ["playwright>=1.60.0,<2.0.0"]
 
 # 按平台打包好的组合。刻意不提供 [all]——把四个浏览器内核全装上去
 # 有 70+ 个包和上 G 的浏览器本体，而一台机器只会用其中一个。
 # curl_cffi 是核心依赖，不在这里重复声明（重复写还会引入版本区间打架的风险）。
 #   win   : DrissionPage 直接驱动本机已装的 Chrome，Windows 上最省事
 #   linux : Camoufox / Patchright 自带无头浏览器，适合服务器
-win = ["drissionpage>=4.1.0,<5.0.0"]
-linux = ["camoufox>=0.5.0,<1.0.0", "patchright>=1.52.0,<2.0.0"]
+win = ["drissionpage>=4.1.1,<5.0.0"]
+linux = ["camoufox>=0.5.4,<1.0.0", "patchright>=1.61.2,<2.0.0"]
 
 [project.urls]
 "Homepage" = "https://github.com/yuanqimanong/IPClick"

{ipclick-0.3.0 → ipclick-0.4.0}/src/ipclick/__init__.py

@@ -29,7 +29,7 @@ try:
     __version__ = importlib.metadata.version("ipclick")
     __author__ = importlib.metadata.metadata("ipclick")["Author"]
 except importlib.metadata.PackageNotFoundError:  # pragma: no cover - 仅在未安装时走到
-    __version__ = "0.3.0"
+    __version__ = "0.4.0"
     __author__ = "元气码农少女酱"