Skip to content

Installation

Jump to bottom
HadesTop edited this page Aug 21, 2026 · 4 revisions

安装

最小安装

pip install ipclick

装完是 17 个包，只带默认适配器 curl_cffi。这是刻意的：绝大多数用途只需要发 HTTP 请求，不该为此拖进四个浏览器内核和上 G 的浏览器本体。

核心依赖 10 项：grpcio、grpcio-health-checking、protobuf、curl-cffi、click、 fake-useragent、loguru、python-box、uuid-utils、typing-extensions。

可选组件（extras）

pip install "ipclick[niquests]"       # HTTP/2 + HTTP/3 适配器
pip install "ipclick[camoufox]"       # 浏览器渲染：Firefox 反检测（Linux/macOS 默认）
pip install "ipclick[drissionpage]"   # 浏览器渲染：CDP 直连（Windows 默认）
pip install "ipclick[patchright]"     # 浏览器渲染：Chromium 反检测
pip install "ipclick[playwright]"     # 浏览器渲染：原版，最稳

按平台打包好的组合：

pip install "ipclick[win]"     # curl_cffi + DrissionPage
pip install "ipclick[linux]"   # curl_cffi + camoufox + patchright

多个可以一起装：pip install "ipclick[niquests,camoufox]"。

zsh 用户注意：方括号会被当成 glob，必须加引号 —— pip install "ipclick[niquests]"。

也可以在 Web 管理端点按钮装：/components 页列出全部五个组件的两级安装 状态，就地装 / 卸、下载浏览器本体，装完不用重启进程。见 Web 管理端 · 组件。

版本区间

各 extra 的版本区间写在 pyproject.toml 里。有一条约束值得单独知道：

camoufox 钉着 playwright<1.61，所以 [camoufox] 和 [playwright] 真的互斥。 这一点在 pyproject.toml 的 [tool.uv].conflicts 里显式声明了出来，uv 会为两者 各解一份依赖——于是 [playwright] 能跟上上游（当前 >=1.62.0），同时 [camoufox] 仍然装得上它自己那份 playwright<1.61。

实际声明了两组互斥：[camoufox] × [playwright]，以及 [linux] × [playwright] ——后者是因为 [linux] 本身聚合了 camoufox，所以 ipclick[linux,playwright] 同样解不出来。

代价是 --all-extras 用不了（它会同时点亮互斥的 extra 而直接失败）， 装可选适配器时要逐个 --extra 列出。

只装 [playwright] 不装 camoufox 的话，区间上限 <2.0.0 允许你拿到最新版。

为什么没有 [all]

四个浏览器内核全装是 60 多个包和上 G 的浏览器本体，而一台机器只会用其中一个。 提供 [all] 只会让人不假思索地装上，然后抱怨包太大。

各组合的实际体积

命令 包数
pip install ipclick 17
+ [niquests] 24
+ [niquests,playwright] 约 30
+ [win]（DrissionPage） 33
+ [linux]（camoufox + patchright） 约 50

（数字取自仓库 uv.lock 的 Linux / CPython 解析，不含浏览器本体；随上游依赖会有出入， 看量级就好。）

[win] 比 [niquests] 重得多，容易反直觉——DrissionPage 拉进来 lxml、psutil、 requests、tldextract、openpyxl 一长串传递依赖。

浏览器引擎是两步安装

pip install 只装 Python 包（几 MB）。浏览器本体要单独准备：

python -m camoufox fetch        # camoufox：下载它自己那份 Firefox，约 1 GB → ~/.cache/camoufox
patchright install chromium     # patchright
playwright install chromium     # playwright
# DrissionPage 用本机已装的 Chrome/Chromium，不用额外下载

只做第一步的话，ipclick config-info 与 Web 管理端会明确显示 「包已装，浏览器本体未就绪」，请求会直接报 FAILED_PRECONDITION 并告诉你该跑哪条命令。

Web 管理端的 /components 页也能直接点「下载浏览器本体」——camoufox fetch 要下约 1 GB，跑在后台并实时显示输出，不会把页面卡住。

卸载的语义：pip uninstall camoufox 不会删掉 ~/.cache/camoufox 里那 1 GB 浏览器本体。Web 端的「卸载」同样只卸 Python 包，但会把本体的路径和体积摆出来告诉你 ——不说的话容易以为空间已经释放了。真要回收就自己删那个目录。

为什么不让它自动下载？

camoufox 的 API 默认行为就是「缺本体就当场下」（camoufox_path(download_if_missing=True)）。 而那一刻已经在 gRPC 的请求处理线程上：第一个请求会卡着下 1 GB 然后超时，超时返回后 下载还在后台跑，并发的多个首请求还可能各自触发一次。所以 IPClick 自己解析路径并显式 传给它，缺了就报错。

连「查一下装没装」也不能走它的接口——launch_path() 内部同样会触发下载， 光渲染一次 Web 管理端总览页就够了。

复用系统已装的浏览器

playwright / patchright / DrissionPage 都可以用系统浏览器，省掉 150 MB 下载：

[BROWSER]
engine = "playwright"
executable_path = "/usr/bin/chromium"   # 容器里常见

设了 executable_path 之后，安装状态检测与启动都以它为准——camoufox 也不例外。

这恰恰是个配置陷阱：camoufox 的全部反检测能力来自它自己那份打过补丁的 Firefox， 把 executable_path 指向普通 Firefox 会静默丢掉这些补丁，不报错、也不回落。 engine = "camoufox" 时请把这一项留空。

从源码安装

git clone https://github.com/yuanqimanong/IPClick.git
cd IPClick
uv sync --all-groups                   # 推荐，用 uv（含开发依赖，不含可选适配器）
# 要可选适配器就逐个列出，不能用 --all-extras（见上文「版本区间」的互斥说明）
uv sync --all-groups --extra niquests --extra camoufox --extra patchright
# 或
pip install -e ".[niquests,playwright]"

改了 .proto 之后要重新生成：

uv run python src/ipclick/dto/proto/generate.py

（这个脚本会调 protoc 并把生成代码里的顶层导入改成包内相对导入。）

系统要求

  • Python ≥ 3.11（用到了 tomllib、StrEnum 等）
  • 内存：纯 HTTP 用途几十 MB 足够；开浏览器渲染时 Chromium 系每个实例约 600 MB， camoufox 更高（Firefox 加一整套扩展）。集群里每个会执行渲染的节点各占一份， 见性能与容量
  • 操作系统：Linux / macOS / Windows 都支持。浏览器引擎的默认选择按平台不同： Windows → DrissionPage，其余 → camoufox

Docker

仓库里有多阶段构建、非 root 运行的 Dockerfile：

docker build -f docker/Dockerfile -t ipclick .
docker run -p 9528:9528 \
  -v "$PWD/ipclick.toml:/app/ipclick.toml:ro" \
  --env-file .env \
  ipclick

容器里跑浏览器渲染要注意两点：

  • --disable-dev-shm-usage：容器默认 /dev/shm 只有 64 MB，Chromium 会崩。 配置里设 no_sandbox = true 会自动带上这个参数。
  • 沙箱：容器里通常没有 user namespace，需要 no_sandbox = true， 或者给容器 --cap-add=SYS_ADMIN。

验证装好了

ipclick --version
ipclick config-info      # 逐项显示"什么真生效了"

config-info 会告诉你：绑定地址、鉴权与 TLS 状态、每个机密来自哪里 （环境变量 / 配置文件 / 未配置）、限流设置、浏览器引擎与浏览器本体是否就绪、 链路记录状态。配错了的东西在这里一眼能看出来。

"装没装"是探测出来的（走 importlib.util.find_spec，不执行模块代码）， 结果缓存在进程内直到显式刷新。所以在终端里装完 / 卸完，Web 管理端点一下 「刷新状态」就能看到，不用重启进程。 换成模块级 try: import 的话，结论会固化在进程启动那一刻，卸载更是完全探测不出来。

下一步

IPClick

开始

用法

能力

运维

参考

Clone this wiki locally