Skip to content

Installation

Jump to bottom
HadesTop edited this page Aug 14, 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]"。

为什么没有 [all]

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

各组合的实际体积

命令 包数
pip install ipclick 17
+ [niquests] 22
+ [niquests,playwright] 27
+ [win]（DrissionPage） 20
+ [linux]（camoufox + patchright） 33

（不含浏览器本体，见下。）

浏览器引擎是两步安装

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 并告诉你该跑哪条命令。

为什么不让它自动下载？

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 例外——它必须用自己那份 打过补丁的 Firefox，指别的没有意义。

从源码安装

git clone https://github.com/yuanqimanong/IPClick.git
cd IPClick
uv sync --all-extras --all-groups      # 推荐，用 uv
# 或
pip install -e ".[niquests,playwright]"

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

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

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

系统要求

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

Docker

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

docker build -f docker/Dockerfile -t ipclick .
docker run -p 9527:9527 \
  -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 状态、每个机密来自哪里 （环境变量 / 配置文件 / 未配置）、限流设置、浏览器引擎与浏览器本体是否就绪、 链路记录状态。配错了的东西在这里一眼能看出来。

下一步：快速开始。

IPClick

开始

用法

能力

运维

参考

Clone this wiki locally