缓存证书设置

选择缓存模式下的TLS选项#

密码中没有_cache-后缀？无需更改任何设置。普通代理模式保持端到端TLS，对于明文的http://代理端点，无需安装证书，也无需更改客户端TLS设置。https://代理端点是唯一的例外：其节点证书的证书链指向同一个根证书，因此需要按照HTTP与HTTPS代理端点中的说明，为该代理连接信任该根证书。仅有这一信任，绝不会启用缓存模式。

启用缓存模式后，选择其中一项：

跳过验证意味着客户端无法对目标证书进行认证。切勿将该选项用于登录、支付、私有API、cookie或敏感流量。

代理URL可以以http://开头，因为它标识的是HTTP代理端点。目标仍然是https://example.com/...；代理端点的协议和目标的协议是两回事。

在隔离的公开数据自动化中跳过验证#

仅在获取公开静态数据的专用缓存客户端中使用此选项。它会关闭客户端对目标证书的认证；并不会使私密流量可以安全地被拦截。将代理凭证保存在机密存储中，并在隔离的工作负载结束时移除缓存后缀。

curl#

curl --insecure --proxy 'http://hub-us-7.litport.net:PORT' \
  --proxy-user 'USER:PASSWORD_cache-scripts' \
  'https://cdn.jsdelivr.net/npm/[email protected]/lodash.min.js'

Python Requests#

import requests

requests.get(
    'https://cdn.jsdelivr.net/npm/[email protected]/lodash.min.js',
    proxies={'https': 'http://USER:[email protected]:PORT'},
    verify=False,
    timeout=30,
)

Node#

NODE_TLS_REJECT_UNAUTHORIZED=0 node scraper.mjs

在该隔离的Node进程中配置HTTP代理。此环境变量设置会关闭该进程的证书验证；不要将其用于通用服务。

浏览器自动化#

import { chromium } from 'playwright'

const browser = await chromium.launch({ proxy: {
  server: 'http://hub-us-7.litport.net:PORT',
  username: 'USER',
  password: 'PASSWORD_cache-scripts',
}})
const context = await browser.newContext({ ignoreHTTPSErrors: true })
await (await context.newPage()).goto('https://cdn.jsdelivr.net/npm/[email protected]/lodash.min.js')

为此工作负载使用专用的浏览器配置文件。不要用它访问已登录的网站或敏感网站。

Go#

proxyURL, err := url.Parse("http://USER:[email protected]:PORT")
if err != nil { log.Fatal(err) }
client := &http.Client{Transport: &http.Transport{
  Proxy: http.ProxyURL(proxyURL),
  TLSClientConfig: &tls.Config{InsecureSkipVerify: true}, // public-data-only isolated client
}}
response, err := client.Get("https://cdn.jsdelivr.net/npm/[email protected]/lodash.min.js")

信任Litport根证书（推荐）#

两段经过验证的TLS链路#

缓存模式会在所选Litport节点上终止面向客户端的TLS连接，以便读取符合条件的响应，并在之后提供本地副本。客户端会依据Litport缓存根证书验证所签发的目标证书。另外，节点在读取源站响应之前，会验证真实的源站证书和主机名。在两个信任边界上都要保持验证开启。

HTTP目标没有经过认证的源站身份，会保持在普通代理路径上。缓存模式应使用HTTPS目标。

已发布的根证书标识#

下载：https://litport.net/certificates/litport-cache-root.crt

机器可读标识（可选）：litport-cache-root.json

指纹是对证书DER表示形式计算的哈希。文件校验和是对已下载的PEM字节（包括文本编码和换行符）计算的哈希，因此这两个SHA-256值不同。

curl --fail --remote-name https://litport.net/certificates/litport-cache-root.crt
openssl x509 -in litport-cache-root.crt -noout -subject -issuer -dates -fingerprint -sha256
sha256sum litport-cache-root.crt

下载文件只包含公开的证书内容，绝不含私钥。一个根证书适用于所有被选中的节点。切换节点可能导致缓存未命中，因为条目仅存在于各自的节点上；这并不需要新的根证书。

安装根证书后会允许什么#

该公开根证书使客户端能够验证由Litport缓存CA层级签发的目标证书。同一个根证书还用于验证节点在其https://代理端点上出示的证书；参见HTTP与HTTPS代理端点。Litport将根证书私钥离线保存，不会部署到节点上。每个节点都会获得各自的中间证书和私钥，因此即使某个节点被攻破，根证书私钥也不会暴露。

对于启用缓存的连接，所选节点可以读取HTTPS请求和响应。在系统范围内安装根证书，还会使使用该系统证书存储的每个应用都接受由Litport缓存层级签发的证书。将信任范围限定在缓存客户端或其专用容器内，仅对公开静态数据使用缓存模式，并在工作负载不再需要时移除根证书。没有有效的_cache-后缀时，即使根证书仍已安装，Litport也会保持HTTPS隧道不透明。

客户端设置#

优先采用按进程、按配置文件或专用容器的信任方式。系统级信任的范围很广：使用该证书存储的所有应用都可能信任由此根证书签发的证书。替换USER、PASSWORD和PORT；对URL保留字符进行百分号编码，切勿提交代理凭证。

curl --proxy 'http://hub-us-7.litport.net:PORT' \
  --proxy-user 'USER:PASSWORD_cache-scripts' \
  --cacert ./litport-cache-root.crt \
  'https://cdn.jsdelivr.net/npm/[email protected]/lodash.min.js'

import requests

requests.get(
    "https://cdn.jsdelivr.net/npm/[email protected]/lodash.min.js",
    proxies={"https": "http://USER:[email protected]:PORT"},
    verify="litport-cache-root.crt",
    timeout=30,
)

NODE_EXTRA_CA_CERTS=./litport-cache-root.crt node scraper.js

// Configure the Litport HTTP proxy in your Node client.
// Keep rejectUnauthorized at its default true.

// Trust litport-cache-root.crt in the isolated browser/profile
// trust store actually used by the automation browser.
// Keep ignoreHTTPSErrors: false.
// Do not use --ignore-certificate-errors.

pool, _ := x509.SystemCertPool()
pem, _ := os.ReadFile("litport-cache-root.crt")
pool.AppendCertsFromPEM(pem)
transport := &http.Transport{
    Proxy: http.ProxyURL(proxyURL),
    TLSClientConfig: &tls.Config{RootCAs: pool, MinVersion: tls.VersionTLS12},
}

keytool -importcert -alias litport-cache \
  -file litport-cache-root.crt \
  -keystore ./litport-cache-truststore.p12 \
  -storetype PKCS12

java -Djavax.net.ssl.trustStore=./litport-cache-truststore.p12 App

<network-security-config>
  <base-config>
    <trust-anchors><certificates src="system" /></trust-anchors>
  </base-config>
  <debug-overrides>
    <trust-anchors>
      <certificates src="@raw/litport_cache_root" />
    </trust-anchors>
  </debug-overrides>
</network-security-config>

1. 安装Litport根证书描述文件。
2. 打开“设置” → “通用” → “关于本机” → “证书信任设置”。
3. 为Litport根证书启用完全信任。
4. 缓存模式测试结束后，移除该描述文件。

curl#

--cacert会为本次请求替换curl默认的CA证书包。如果目标需要另一个私有CA，应将所需的根证书合并到一个专用证书包中。

curl --proxy 'http://hub-us-7.litport.net:PORT' --proxy-user 'USER:PASSWORD_cache-scripts' \
  --cacert ./litport-cache-root.crt --verbose \
  'https://cdn.jsdelivr.net/npm/[email protected]/lodash.min.js'

Python Requests、httpx和aiohttp#

Requests的verify文件会替换其默认证书包。对于httpx和aiohttp，先创建默认上下文，再调用load_verify_locations()，把此根证书追加到系统根证书中。

import asyncio, ssl
import aiohttp, httpx, requests
proxy = 'http://USER:[email protected]:PORT'
url = 'https://cdn.jsdelivr.net/npm/[email protected]/lodash.min.js'
requests.get(url, proxies={'https': proxy}, verify='litport-cache-root.crt', timeout=30)
context = ssl.create_default_context()
context.load_verify_locations(cafile='litport-cache-root.crt')
httpx.get(url, proxy=proxy, verify=context, timeout=30)
async def fetch():
    async with aiohttp.ClientSession(connector=aiohttp.TCPConnector(ssl=context)) as session:
        async with session.get(url, proxy=proxy) as response: return await response.read()
asyncio.run(fetch())

Node HTTPS客户端#

NODE_EXTRA_CA_CERTS会向Node追加根证书。流量由真正的HTTPS代理agent转发；让rejectUnauthorized保持默认值true。

npm install https-proxy-agent
NODE_EXTRA_CA_CERTS=./litport-cache-root.crt node scraper.mjs

import https from 'node:https'
import { HttpsProxyAgent } from 'https-proxy-agent'
const agent = new HttpsProxyAgent('http://USER:[email protected]:PORT')
https.get('https://cdn.jsdelivr.net/npm/[email protected]/lodash.min.js', { agent }, response => response.resume())

此设置不会影响Chromium、Playwright或Puppeteer的流量。

浏览器自动化#

将根证书安装到隔离浏览器配置文件所使用的操作系统或NSS证书存储中。保持ignoreHTTPSErrors: false，不要使用--ignore-certificate-errors。

import { chromium } from 'playwright'
const browser = await chromium.launch({ proxy: {
  server: 'http://hub-us-7.litport.net:PORT', username: 'USER', password: 'PASSWORD_cache-scripts',
}})
const context = await browser.newContext({ ignoreHTTPSErrors: false })
await (await context.newPage()).goto('https://cdn.jsdelivr.net/npm/[email protected]/lodash.min.js')

Go#

pool, err := x509.SystemCertPool()
if err != nil || pool == nil { pool = x509.NewCertPool() }
pem, err := os.ReadFile("litport-cache-root.crt")
if err != nil || !pool.AppendCertsFromPEM(pem) { log.Fatal("could not add Litport root") }
proxyURL, err := url.Parse("http://USER:[email protected]:PORT")
if err != nil { log.Fatal(err) }
client := &http.Client{Transport: &http.Transport{
  Proxy: http.ProxyURL(proxyURL),
  TLSClientConfig: &tls.Config{RootCAs: pool, MinVersion: tls.VersionTLS12},
}}
response, err := client.Get("https://cdn.jsdelivr.net/npm/[email protected]/lodash.min.js")

SystemCertPool加AppendCertsFromPEM可保留系统根证书，并追加此根证书。

Java#

专用信任库作用于单个进程，但会替换Java的默认证书包。将其他所需的根证书导入该专用存储中。

keytool -importcert -noprompt -alias litport-cache -file litport-cache-root.crt \
  -keystore ./litport-cache-truststore.p12 -storetype PKCS12 -storepass changeit
java -Djavax.net.ssl.trustStore=./litport-cache-truststore.p12 \
  -Djavax.net.ssl.trustStoreType=PKCS12 -Djavax.net.ssl.trustStorePassword=changeit App

在范围较广的信任库中安装和移除#

仅在无法使用进程或配置文件级信任时才使用这些方式；它们也会影响其他应用。

Debian和Ubuntu#

sudo install -m 0644 litport-cache-root.crt /usr/local/share/ca-certificates/litport-cache-root.crt
sudo update-ca-certificates
# Remove: sudo rm /usr/local/share/ca-certificates/litport-cache-root.crt && sudo update-ca-certificates

RHEL和Fedora#

sudo install -m 0644 litport-cache-root.crt /etc/pki/ca-trust/source/anchors/litport-cache-root.crt
sudo update-ca-trust extract
# Remove: sudo rm /etc/pki/ca-trust/source/anchors/litport-cache-root.crt && sudo update-ca-trust extract

macOS#

sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain litport-cache-root.crt
# Remove: sudo security delete-certificate -c 'Litport cache root CA' /Library/Keychains/System.keychain

Windows#

在以管理员身份运行的PowerShell中执行：

certutil -addstore -f Root .\litport-cache-root.crt
# Remove: certutil -delstore Root "Litport cache root CA"

Firefox和NSS#

将FIREFOX_PROFILE设置为包含cert9.db的配置文件目录；在Debian/Ubuntu上先安装libnss3-tools。

certutil -A -n 'Litport cache root' -t 'C,,' -i litport-cache-root.crt -d "sql:$FIREFOX_PROFILE"
# Remove: certutil -D -n 'Litport cache root' -d "sql:$FIREFOX_PROFILE"

容器与Kubernetes#

使用专用的工作负载镜像或只读的运行时挂载，而不是主机级信任。对于Node：

COPY litport-cache-root.crt /opt/litport/litport-cache-root.crt
ENV NODE_EXTRA_CA_CERTS=/opt/litport/litport-cache-root.crt

更新发行版的系统证书存储，会使容器中的每个进程都信任该证书。对于Kubernetes，用已下载的公开PEM创建ConfigMap，然后仅将其挂载到需要缓存模式的工作负载中：

kubectl create configmap litport-cache-root --from-file=litport-cache-root.crt

# Pod template fragment
spec:
  containers:
    - name: client
      env:
        - name: NODE_EXTRA_CA_CERTS
          value: /var/run/litport-ca/litport-cache-root.crt
      volumeMounts:
        - { name: litport-cache-root, mountPath: /var/run/litport-ca, readOnly: true }
  volumes:
    - name: litport-cache-root
      configMap: { name: litport-cache-root }

Android#

Android 7.0+的应用通常不信任用户添加的CA。内置CA的范围较窄：把此PEM包含在调试构建中，并且只信任它。src="user"会信任所有用户安装的CA，其范围比大多数生产环境应用应当接受的更宽。Android在网络安全配置中记录了这些信任来源和调试覆盖项。

<!-- AndroidManifest.xml -->
<application android:networkSecurityConfig="@xml/network_security_config" />

发布构建保留其正常的系统根证书：

<!-- src/main/res/xml/network_security_config.xml -->
<network-security-config><base-config><trust-anchors><certificates src="system" /></trust-anchors></base-config></network-security-config>

调试构建会追加内置的Litport根证书：

<!-- src/debug/res/xml/network_security_config.xml -->
<network-security-config>
  <base-config><trust-anchors><certificates src="system" /></trust-anchors></base-config>
  <debug-overrides><trust-anchors><certificates src="@raw/litport_cache_root" /></trust-anchors></debug-overrides>
</network-security-config>

将PEM文件放在src/debug/res/raw/litport_cache_root.pem。信任策略无法更改的第三方应用与开启证书验证的缓存模式不兼容；应移除_cache-后缀。

iPhone和iPad#

安装已下载的根证书描述文件，然后在设置 → 通用 → VPN与设备管理中完成安装。在设置 → 通用 → 关于本机 → 证书信任设置中，为Litport根证书启用完全信任。通过VPN与设备管理 → 描述文件 → 移除描述文件将其移除。受管设备应通过MDM安装和移除同一载荷。具有自身策略或证书固定的应用仍可能拒绝该连接。Apple在信任手动安装的证书描述文件中记录了单独的完全信任步骤。

验证配置#

1. 发出一个不带后缀的对照请求：它不需要根证书，使用普通代理行为。
2. 使用有效的启用缓存的密码并开启验证，发出相同的HTTPS请求。
3. 向同一节点重复发出该相同请求。在缓存统计中查看先未命中、后命中；不要假定存在专有的缓存响应头。
4. 在已开启验证的curl请求中加上--verbose，确认证书验证成功，且显示的颁发者属于Litport缓存层级。
5. 切换节点可能未命中，因为条目仅存在于各自的节点上；这并不需要新的根证书。

curl --proxy 'http://hub-us-7.litport.net:PORT' --proxy-user 'USER:PASSWORD_cache-scripts' \
  --cacert ./litport-cache-root.crt --verbose --output /dev/null \
  'https://cdn.jsdelivr.net/npm/[email protected]/lodash.min.js'

常见证书问题#

轮换与凭证安全#

轮换期间，核对新PEM已发布的指纹和文件校验和，在所述的重叠期内同时信任两个根证书，测试缓存模式，然后在重叠期结束后，从每个专用证书包、浏览器配置文件、镜像和受管设备载荷中移除旧的根证书。使用带引号的代理URL，并在可用时使用--proxy-user；使用机密存储或注入的环境变量，对URL保留字符进行百分号编码，切勿提交代理凭证或包含密码的命令历史记录。

返回缓存快速入门或选项与故障排查。