docker run 启动 Lightpanda 验证 CDP

执行 docker run 后，容器已经出现在 Docker 列表中，Puppeteer、Playwright 或 chromedp 却仍然无法连接 127.0.0.1:9222，这是 Lightpanda AI 自动化接入时容易混淆的一类故障。结论：先确认容器是否仍在运行，再确认 9222 是否发布到宿主机，最后检查 CDP 发现端点和客户端封装；“容器在运行”不等于“CDP 已就绪”。

这里只讨论 GitHub 趋势《browser》项目的 docker run 启动、CDP 子集接入与能力边界验证；“能连接 CDP”不能直接解释成“完整兼容浏览器”。

Lightpanda 官方 Docker 文档提供的基线命令如下。官方镜像覆盖 Linux amd64 和 arm64，CDP 服务使用容器的 9222 端口。

docker run -d --name lightpanda -p 127.0.0.1:9222:9222 lightpanda/browser:nightly

容器创建后，先执行下面三条命令，而不是立刻修改客户端：

docker ps -a --filter name=lightpanda
docker logs --tail 100 lightpanda
docker port lightpanda

按以下顺序判断：容器不存在或已经退出，先查镜像拉取和启动日志；容器仍在运行但没有端口映射，先查启动参数；映射存在但发现端点失败，再查当前版本的 CDP 地址；握手成功之后，才进入导航、DOM、JavaScript 和 Web API 的功能验证。

官方命令里的几个参数各自承担不同职责，排障时需要分别核对。

参数或现象	实际作用	排查意义
-d	容器在后台运行	只表示 Docker 已启动容器，不表示 CDP 已经可以接受连接
--name lightpanda	为容器指定稳定名称	方便查看状态和日志；同名容器已存在时，先处理旧容器
-p 127.0.0.1:9222:9222	把宿主机回环地址的 9222 映射到容器 9222	同一宿主机上的客户端可以访问；其他主机不能直接使用这个地址
lightpanda/browser:nightly	使用官方 nightly 镜像	标签可能随上游更新而变化，生产环境应记录并固定实际摘要

镜像没有拉下来、Docker daemon 权限不足和 Lightpanda 自身启动失败，看起来都可能像“容器不可用”。先把它们分开：

docker pull lightpanda/browser:nightly
docker info

如果命令在连接 Docker daemon 时就出现权限错误，应按所在机器的权限策略使用授权的提权方式或 Docker 用户组。不要把开放 Docker socket 当成通用修复，也不要用 --privileged 掩盖权限问题；这些做法改变的是安全边界，不是 CDP 配置。

如果旧容器占用了名称，先确认它是否仍有用途，再选择重命名或删除：

docker ps -a --filter name=lightpanda
docker rename lightpanda lightpanda-old

只有确认旧容器可以丢弃时，才执行：

docker rm -f lightpanda

宿主机 9222 已被其他进程占用时，Lightpanda 容器即使正常启动，客户端仍会连接失败。先查占用者：

ss -ltnp | grep ':9222'

如果不能释放这个端口，可以只改宿主机侧端口：

docker run -d --name lightpanda-9223 -p 127.0.0.1:9223:9222 lightpanda/browser:nightly

此时客户端地址也要同步改成 9223，容器内部的 CDP 端口仍然是 9222：

export LIGHTPANDA_BROWSER_URL='http://127.0.0.1:9223'

CPU 架构不匹配属于镜像和平台问题，不属于 CDP 子集问题。宿主机架构与镜像架构可以分别检查：

uname -m
docker image inspect lightpanda/browser:nightly --format '{{.Architecture}}'

在 Linux 环境中，常见的 x86_64 对应 Docker 的 amd64，aarch64 对应 arm64；官方镜像提供的是 Linux amd64 和 arm64 版本。 在 Docker Desktop 或 WSL2 中，应以实际运行容器的 Linux 环境为准，不要只看 macOS 或 Windows 主机表面的架构名称。出现架构不匹配时，应改用匹配的平台或当前环境明确支持的模拟方式，不要从客户端连接参数上绕。

容器立即退出时，优先看状态、退出码、日志和镜像默认入口：

docker inspect lightpanda --format '{{.State.Status}} {{.State.ExitCode}} {{.State.Error}} {{.Image}}'
docker logs --tail 100 lightpanda
docker image inspect lightpanda/browser:nightly --format '{{json .Config.Entrypoint}} {{json .Config.Cmd}}'

日志为空也不能据此判断 Lightpanda 已正常启动，因为有些启动失败会在默认入口执行前就结束。没有核对当前镜像入口前，不要随意追加 --entrypoint、浏览器参数或其他启动命令；这些参数可能改变镜像原本的启动方式。

容器显示运行中、端口映射也存在，但 9222 仍然没有响应，可以继续区分“服务没有监听”和“发现端点不存在”：

docker port lightpanda
docker top lightpanda
curl -i --max-time 5 http://127.0.0.1:9222/json/version

docker port 没有显示映射，说明容器创建时就没有发布端口，需要按正确参数重建；映射存在但连接没有响应，再检查容器进程、宿主机防火墙和网络路径。若 /json/version 返回路由不存在，也不应立即把它等同于容器损坏，因为后文的版本差异会解释这一点。

宿主机、容器和远程客户端看到的地址不同。客户端运行在宿主机上时，官方示例中的 127.0.0.1:9222 指向宿主机回环地址；客户端运行在另一个容器里时，它的 127.0.0.1 指向自己，而不是宿主机或 Lightpanda 容器，此时应使用同一 Docker 网络中的服务名或经过验证的宿主机网关地址。

跨主机访问时，官方命令只绑定宿主机回环地址，不能直接接受远端连接。需要监听指定私网接口时，应明确修改宿主机绑定地址，并同时限制防火墙来源；现有资料没有说明 CDP 服务的鉴权机制，因此不能假定它自带身份认证，也不应把 9222 暴露到公网。需要跨主机使用时，应先核对当前版本文档，并优先通过受控私网、VPN 或明确的防火墙规则限制访问范围。

WSL2 是另一个容易产生地址误判的环境。资料明确提到 Lightpanda 可以在 WSL2 中运行，并建议将 Puppeteer 等客户端放在 Windows 主机上。 因此可以在 WSL2 中执行官方 Docker 命令，让 Windows 客户端先尝试 http://127.0.0.1:9222；如果本机转发没有生效，再确认 WSL2 可达地址、端口发布方式和监听接口，不能把 WSL2 内部的回环地址直接当作跨环境地址。

客户端能够连接 CDP，也不代表 Lightpanda 能够访问目标站点。容器内的 DNS、代理环境和证书信任链可能与宿主机不同。导航失败时，应把目标站点因素与 CDP 方法缺失分开：先用受控内网固定页面验证导航，再检查目标域名解析、容器代理配置和证书链。不要因为外部页面打不开，就直接修改 Puppeteer 的连接地址；同样也不要通过关闭证书校验来掩盖容器 CA 配置问题。

容器和端口都正常后，才进入 CDP 子集接入。官方 Docker 文档确认 CDP 服务运行在 9222 上，但没有保证每个版本都提供标准的 /json/version 发现端点。 因此 /json/version 可以作为探针，但不能作为唯一的健康判断：

curl -i --max-time 5 http://127.0.0.1:9222/json/version

如果响应中包含浏览器信息和 webSocketDebuggerUrl，应优先使用返回的完整 WebSocket 地址，不要自行改写路径。如果当前版本不提供这个 HTTP 端点，而只给出了 WebSocket 地址，就使用该版本官方示例或启动输出中的实际地址；这是版本敏感步骤，HTTP 404 不能直接证明 Lightpanda 容器已经损坏。

使用发现端点时，配置 HTTP 基地址：

export LIGHTPANDA_BROWSER_URL='http://127.0.0.1:9222'

只有 WebSocket 地址时，配置实际端点并替换占位内容：

export LIGHTPANDA_WS_ENDPOINT='ws://ACTUAL_WS_ENDPOINT'

Puppeteer 应使用 connect，不要误用会自行启动浏览器的 launch。安装不带浏览器内核的客户端即可：

npm i puppeteer-core

发现端点可用时，连接方式是：

import puppeteer from "puppeteer-core";

const browser = await puppeteer.connect({
  browserURL: process.env.LIGHTPANDA_BROWSER_URL,
});

只有 WebSocket 地址时，改为：

import puppeteer from "puppeteer-core";

const browser = await puppeteer.connect({
  browserWSEndpoint: process.env.LIGHTPANDA_WS_ENDPOINT,
});

browserURL 依赖客户端自行发现浏览器端点，browserWSEndpoint 则直接连接已经确定的 WebSocket 地址。两者不是同一个入口，也不应该同时填写。

现有资料列出的 CDP 兼容对象包括 Playwright 1、Puppeteer 和 chromedp，同时把 Web API 标为 partial、WIP。 客户端能够发起连接，不代表它们调用的所有方法都受支持。

可以先用一个不依赖外部网络的固定页面做冒烟测试：

<!doctype html>
<title>lp-check</title>
<p id="ok">ok</p>
<script>
  window.lpResult = 40 + 2;
</script>

下面的脚本依次覆盖版本握手、导航、DOM、页面内 JavaScript、Promise 和定时任务。把脚本保存为 smoke.mjs 后运行：

import puppeteer from "puppeteer-core";

const browser = await puppeteer.connect({
  browserURL: process.env.LIGHTPANDA_BROWSER_URL,
});

try {
  console.log(await browser.version());

  const page = await browser.newPage();
  const response = await page.goto(
    "data:text/html,%3Ctitle%3Elp-check%3C%2Ftitle%3E%3Cp%20id%3Dok%3Eok%3C%2Fp%3E%3Cscript%3Ewindow.lpResult%3D40%2B2%3B%3C%2Fscript%3E"
  );

  console.log(response ? response.status() : "no-response");
  console.log(await page.title());
  console.log(
    await page.evaluate(() => document.querySelector("#ok")?.textContent)
  );
  console.log(await page.evaluate(() => window.lpResult));
  console.log(await page.evaluate(() => Promise.resolve("promise-ok")));
  console.log(
    await page.evaluate(
      () => new Promise((resolve) => setTimeout(() => resolve("timer-ok"), 0))
    )
  );
} finally {
  await browser.disconnect();
}

如果使用 browserWSEndpoint，只需替换连接对象，后面的验证逻辑不变。验收记录应写入实际返回值、异常原文和所用客户端版本，不以预期结果代替。若当前版本不接受 data: URL 导航，就把同一份 HTML 放到受控内网 HTTP 服务上继续测试，不要把 URL scheme 不受支持误判成 DOM 或 JavaScript 全部不可用。

点击、输入和事件监听需要单独验证，因为这些调用可能经过客户端封装，而不是直接对应一个 CDP 方法。可以使用这样的受控页面：

<!doctype html>
<title>lp-interaction</title>
<button id="go" type="button">go</button>
<input id="name">
<script>
  window.clickCount = 0;
  window.inputCount = 0;

  document.querySelector("#go").addEventListener("click", () => {
    window.clickCount += 1;
  });

  document.querySelector("#name").addEventListener("input", () => {
    window.inputCount += 1;
  });
</script>

可先用以下客户端调用：

await page.click("#go");
console.log(await page.evaluate(() => window.clickCount));

await page.type("#name", "abc");
console.log(await page.$eval("#name", (element) => element.value));
console.log(await page.evaluate(() => window.inputCount));

如果高层客户端方法失败，而原始 CDP 调用成功，通常说明问题落在客户端封装、等待条件或客户端版本假设上。Puppeteer 暴露 CDP session 时，可以做一次对照：

const session = await page.createCDPSession();
const result = await session.send("DOM.getDocument", { depth: -1 });

console.log(Boolean(result?.root));

原始 DOM.getDocument 成功而 page.$eval、page.title 或等待方法失败，应记录客户端封装差异；原始方法本身失败，则要核对当前 CDP 子集、目标是否正确附着以及页面是否真的完成加载。

Playwright 的连接入口是 connectOverCDP，而不是自行启动 Chromium：

npm i playwright-core

import { chromium } from "playwright-core";

const browser = await chromium.connectOverCDP(
  process.env.LIGHTPANDA_CDP_URL
);

chromedp 则使用 NewRemote 一类的远程连接入口。兼容性记录应固定实际依赖版本，例如：

npm list puppeteer-core --depth=0
npm list playwright-core --depth=0
go list -m -f '{{.Path}} {{.Version}}' github.com/chromedp/chromedp

三个客户端应执行同一份固定用例。记录应写明连接入口、客户端版本、第一个失败方法和完整错误原文，不能只记录“连接成功”。

失败位置	优先判断	下一层检查
客户端无法连接	容器状态、端口映射、端点地址	Docker 映射、WebSocket 路径、地址绑定
能连接但导航失败	导航方法、目标地址、容器网络	DNS、代理、TLS、页面等待条件
导航成功但 DOM 为空	HTML 解析和目标附着状态	页面是否真的加载、固定标记是否存在
DOM 正常但 JavaScript 失败	JavaScript 执行、Promise、定时器	区分语言能力和具体 Web API
点击或输入失败	事件分发、输入方法、客户端封装	用原始 CDP 方法做对照
原始 CDP 成功但高级方法失败	Puppeteer、Playwright 或 chromedp 封装	客户端版本、首个失败方法
不同客户端结果不一致	测试页面与客户端版本差异	固定环境后逐项比较，不下笼统结论

连接握手完成后，仍不能据此认定 Lightpanda 具备完整浏览器能力。现有资料明确将 Web API 标为 partial、WIP。 验收时应把每个 API、每个高级 CDP 域拆成独立用例。

能力组	最小验证	结论写法
CDP 握手	连接、读取版本、断开并重连	通过或失败，同时记录客户端版本
导航与资源访问	受控内网页面、固定内容标记、一个固定子资源	通过、失败或等待条件不一致
DOM	标题、文本、节点数量、属性读取	按具体 DOM 操作记录
JavaScript	同步表达式、Promise、定时任务	分开记录语言执行与 Web API 缺失
事件与交互	点击、输入、监听器触发	记录首个失败的高层封装方法
Web API	每个实际依赖的 API 单独建立用例	通过、部分支持、不支持或未测试
视觉能力	截图、PDF、布局尺寸、像素比较	单独列为待验证项，必要时回退完整浏览器
高级 CDP	网络拦截、存储、下载、Tracing、Target/Session 管理	按方法逐项记录，不接受“基本支持”
自动化框架	Puppeteer、Playwright、chromedp 执行同一用例	记录版本、连接入口和实际结果

Web API 的验收单位应该是单个 API，而不是“支持 Web API”这个笼统结论。同步 JavaScript 能执行，不代表定时器、存储、网络或浏览器接口都可用；某个 API 在一种参数形式下工作，也不足以把它标成完整支持。

视觉能力要单独处理。项目介绍把 Lightpanda 描述为不包含传统图形渲染层，而保留 HTML 解析、JavaScript 执行和 CDP。 即使按这一描述，也只能说明截图、PDF、布局尺寸和像素级断言需要额外验证，不能据此直接推定所有视觉功能都不支持。对像素比较、截图基线或 PDF 验收有硬要求的任务，保留 Chromium 回退路径更稳妥。

网络拦截、存储、下载、Tracing、Target 和 Session 管理同样不能由“兼容 CDP”直接推出。它们可能涉及额外的目标附着、事件订阅和生命周期管理，而且不同客户端的封装方式并不相同。某个客户端连接阶段就失败，也可能是因为它自动调用了当前子集尚未提供的方法，而不是页面导航本身有问题。

验收状态建议固定为四种：通过 表示固定用例满足预期；部分支持 表示基础路径可用，但任务需要的另一方法或参数形式失败；不支持 表示在固定环境中能够稳定复现失败，并保存了具体方法；未测试 表示没有足够证据。一次高层调用失败还不能自动把某个能力记成“不支持”。

进入生产链路前，应同时固定镜像摘要和客户端版本。容器实际使用的镜像 ID，以及本地镜像可见的仓库摘要，可以这样记录：

docker inspect lightpanda --format '{{.Image}}'
docker image inspect lightpanda/browser:nightly --format '{{json .RepoDigests}}'

.Image 是当前容器引用的镜像 ID，RepoDigests 则取决于镜像是否带有仓库摘要。部署时使用已经验收过的摘要，而不是继续依赖可移动的 nightly 标签。以下命令只演示参数结构；512m 和 1 不是 Lightpanda 的最低配置要求，应按实际负载调整：

docker run -d --name lightpanda --restart unless-stopped --memory 512m --cpus 1 -p 127.0.0.1:9222:9222 lightpanda/browser@sha256:REPLACE_WITH_APPROVED_DIGEST

--restart 只能处理进程退出后的重启，不能保证 CDP 握手已经就绪；监控也应分为两层：一层检查容器状态，另一层执行真实 CDP 握手。当前版本是否提供 /json/version 尚未确认时，不要把探测这个端点直接设成唯一健康检查，应使用已经确认可用的 WebSocket 端点。

每条生产验收记录至少应包含以下字段：

case
lightpanda_image_digest
client_name
client_version
expected
actual
status
error
fallback

其中 error 保留原始异常文本，fallback 记录失败后是否切换到 Chromium。镜像摘要、客户端版本或测试页面发生变化后，应重跑同一套用例；只验证新镜像能够启动，不足以证明能力没有回退。

我的判断是，应把 Lightpanda 视作需要按任务验收的轻量 CDP 执行端，不能未经测试就等同于完整 Chromium。只有导航、DOM、JavaScript 以及任务真正依赖的 API 和高级能力全部通过后，才适合进入生产链路；否则，保留完整浏览器回退比强行统一执行端更稳妥。