a76yyyy/pycurl repository overview

⁠pycurl Docker 镜像（Alpine）

pycurl 的 musllinux wheel 分发，另附装好的可运行镜像。两条线：latest 用自编 curl + OpenSSL， ja3-latest 用 curl-impersonate + BoringSSL，提供浏览器 TLS 指纹。

• Docker Hub：https://hub.docker.com/r/a76yyyy/pycurl⁠
• 源码：qd-today/pycurl-docker⁠

⁠快速开始

docker pull a76yyyy/pycurl:latest        # 或 ja3-latest

import pycurl

body = bytearray()
c = pycurl.Curl()
c.setopt(pycurl.URL, "https://example.com")
c.setopt(pycurl.WRITEFUNCTION, body.extend)
c.perform()
print(c.getinfo(pycurl.RESPONSE_CODE), len(body))

以 wheelhouse 作为依赖来源：

# syntax=docker/dockerfile:1.7
FROM alpine:3.24
RUN --mount=type=bind,from=a76yyyy/pycurl:wheelhouse,source=/wheels,target=/w1 \
    apk add --no-cache $(cat /w1/system-packages.txt) uv && \
    uv pip install --system --break-system-packages --no-cache \
        --index-url https://pypi.org/simple \
        --extra-index-url file:///w1/simple \
        "pycurl==7.49.0"

/w1/simple 是 PEP 503 索引，链接为相对路径，可与 wheel 目录一起挂到任意位置。

RUN --mount 需要 BuildKit（首行 # syntax=docker/dockerfile:1）；Kaniko 等不支持时用 COPY --from=<wheelhouse> /wheels /wheels，代价是 /wheels 会进镜像层，且 rm 删不掉。

⁠镜像内容

两条线的 import pycurl 都只依赖解释器与 wheel 自带的库；pycurl.libs/ 里是 libcurl、libssl/libcrypto（或 libcurl-impersonate、libstdc++）、ngtcp2、nghttp3、 nghttp2、libidn2、libpsl、libbrotli、libzstd、c-ares 与 GSSAPI 链。

⁠支持的平台

ja3 线的平台范围由 BoringSSL 决定：include/openssl/target.h 的官方架构清单只有 x86 / x86_64 / aarch64 / arm / mips64 / riscv64 等，因此 ppc64le 没有对应移植、s390x 是大端、loong64 无 loongarch 条目。

loong64 构建需 --build-arg BASE_IMAGE=ghcr.io/loong64/alpine:3.24（官方 alpine 无此架构，CI 会自动注入）。

⁠标签

lite 只是 latest 的别名：两个标签由一次 imagetools create 挂到同一个 manifest，digest 相同。 <ver> 只在 tag 推送时产出；workflow_dispatch 只更新滚动标签。

⁠构建

wheel 的构建与镜像的组装分两步：第一步产出 wheel 与 curl 命令行，第二步用这份产物组装镜像。 两步之间可以用不同的架构环境（CI 里 arm 系列在原生 arm64 上编，组装统一在 x86_64）。

# ① 编译产物：/wheels 与 /opt/curl-cli
docker buildx build --platform linux/arm64 --target artifacts \
    --output type=local,dest=./dist .

# ② 可运行镜像
docker buildx build --platform linux/arm64 --target runtime \
    --build-context wheelsrc=./dist -t pycurl:latest .

# ③ wheelhouse 镜像（供上层 COPY --from / bind mount）
docker buildx build --platform linux/arm64 --target wheel-from-artifacts \
    --build-context wheelsrc=./dist -t pycurl:wheelhouse .

# 指纹伪装那条线把 -f Dockerfile.ja3 加上，三步相同

--target runtime 不传 --build-context wheelsrc 会失败：镜像里必须有 pycurl，宁可报错也不要 静默产出一个没有它的基座。

国内构建三个镜像参数一起给：apk 与 pip 走镜像，源码 clone 走 GIT_DOMAIN。只给前两个时构建仍会 卡在从 GitHub 拉源码。

⁠产物

/wheels/
  pycurl-<ver>-cpXXX-cpXXX-musllinux_1_2_<arch>.whl
  SHA256SUMS
  system-packages.txt
  simple/
    index.html
    pycurl/index.html        # href="../../<wheel>#sha256=<hex>"

system-packages.txt 是需要 apk add 的运行时包，一行一个：

判定依据是 wheel 里 ELF 的 DT_NEEDED 闭包：除 musl 的 libc 与 libz.so.1 外全部被 auditwheel 收进 pycurl.libs/（可以用 unzip -l pycurl-*.whl | grep libs/ 核对）。

⁠TLS 指纹（ja3 线）

pycurl.IMPERSONATE 由 patches/pycurl-impersonate.patch 提供（选项号 10999），一行开启完整 浏览器指纹；补丁同时清掉 pycurl 构造时强设的默认 User-Agent，使指纹自带的 UA 生效。

import pycurl

c = pycurl.Curl()
c.setopt(pycurl.URL, "https://example.com")
c.setopt(pycurl.IMPERSONATE, "chrome152")
c.perform()

指纹目标覆盖 Chrome 151/152、Safari 27、Firefox 153–155（含 ECH、ZSTD、PQC 与 HTTP/3 指纹）， 由 curl-impersonate 的 target 配置决定 TLS 套件、曲线、扩展、ALPN 与 HTTP/2 settings。要自定义 UA， 在其后 setopt(pycurl.USERAGENT, ...) 覆盖。

⁠已知限制

• 镜像带 curl 命令行（build 阶段编好的那份，与 pycurl 扩展同源），二进制与它的私有库放在 /opt/curl-cli，由 /usr/local/bin/curl 包装脚本限定 LD_LIBRARY_PATH 的作用域。ja3 线的 CLI 是 curl-impersonate（curl 8.23.0-IMPERSONATE，BoringSSL），与 pycurl 扩展同一套补丁； main 线的 CLI 是普通 curl（OpenSSL）。
• wheel 的 cp314 与 alpine:3.24 的 Python 3.14 绑定；换 Python 小版本需要重新构建。
• BoringSSL 未提供 SSL_CTX_set_ciphersuites()，ja3 线的 pycurl.TLS13_CIPHERS 恒返回 CURLE_NOT_BUILT_IN——TLS 1.3 套件由 impersonate target 内部配置。若不能用打过补丁的 pycurl， 可 curl_easy_setopt(handle, 10999, b"chrome152")（10999 即 CURLOPT_IMPERSONATE）。
• chrome152 等 target 启用 tls_permute_extensions，TLS 扩展顺序逐连接随机置换，ja3_hash 每次 请求都不同；比对指纹请用扩展排序归一化后的 ja3n。
• wheel 里只有 ca-certificates 提供的信任链，没有额外 CA；需要自定义 CA 时自行挂载并设 pycurl.CAINFO。
• wheel 的 zip 条目带 mtime，构建不可逐字节复现；内容一致，sha256 每次不同。

⁠维护者