@succsoft/pageweave

v0.1.2

Published

6 days ago

Request-scoped web rendering service powered by Playwright

0High
0Medium
0Low

succsoft

PageWeave

PageWeave 是基于 Playwright 的网页渲染服务。通过一次 POST /v1/render 请求，可以完成页面导航、等待、执行页面脚本、截图或导出 PDF。

安装

要求 Node.js 22.19 或更高版本。在服务目录中安装 PageWeave 及 Chromium：

npm install --omit=dev @succsoft/pageweave
npx playwright install chromium

启动和停止

启动 PageWeave 后，默认监听 127.0.0.1:3200：

npx pageweave start --profile-id succapp
npx pageweave status --profile-id succapp
npx pageweave stop --profile-id succapp

使用 doctor 检查 Chromium 和基础渲染能力：

npx pageweave doctor

PageWeave 的工作目录可通过 PAGEWEAVE_WORK_DIR 或 --work-dir 指定，默认是 ~/.pageweave。例如：

npx pageweave start \
  --profile-id succapp \
  --work-dir /data/pageweave \
  --host 127.0.0.1 \
  --port 3200 \
  --log-level info \
  --log-max-bytes 10485760 \
  --log-retention 5

也可以使用环境变量配置服务：

安全要求

PageWeave 面向受信任的内网环境，不提供服务级鉴权或目标主机白名单。请通过监听地址、防火墙或容器网络限制可访问服务的调用方。只有在确认网络隔离和访问控制已经配置完成后，才应使用 --host 0.0.0.0 监听其他主机。

请求中的 script 会在目标页面上下文执行 JavaScript，因此调用方必须信任请求内容和目标页面。

日志

PageWeave 使用结构化 JSON 日志。前台 serve 模式输出到终端，后台 start 模式追加到 <workDir>/<profileId>/pageweave.log。日志文件超过 PAGEWEAVE_LOG_MAX_BYTES 后会按 pageweave.log.1、pageweave.log.2 的形式轮转，并保留 PAGEWEAVE_LOG_RETENTION 份历史文件。启动时可以通过 --log-level、PAGEWEAVE_LOG_LEVEL 或 JSON 配置文件中的 logLevel 设置初始级别，通过 --log-max-bytes、PAGEWEAVE_LOG_MAX_BYTES、logMaxBytes 设置大小上限，通过 --log-retention、PAGEWEAVE_LOG_RETENTION、logRetention 设置保留份数；优先级均为命令行参数、环境变量、配置文件、默认值。

运行中的实例也可以通过管理页面首页的日志设置区域调整级别，或调用：

GET /settings/logging
PUT /settings/logging
Content-Type: application/json

{"level":"debug"}

Web 调整立即影响当前进程，但不会写回启动配置；服务重启后恢复启动时的日志级别。日志会记录请求 ID、渲染阶段、耗时、错误码、队列和 Chromium 生命周期，不记录请求体、页面脚本、Cookie、Authorization 或完整目标 URL。

HTTP 接口

`POST /v1/render`

请求头：

Content-Type: application/json

请求示例：

{
  "version": "1",
  "url": "http://127.0.0.1:8080/page",
  "viewport": { "width": 1366, "height": 768 },
  "waitForLoad": "load",
  "script": "document.fonts.ready",
  "outputs": [
    { "id": "page", "type": "screenshot", "format": "png" },
    { "id": "data", "type": "script", "script": "document.title" }
  ]
}

顶层 script 和 output 脚本支持普通值或 Promise。服务会等待顶层脚本完成后，再按 outputs 数组顺序执行各项输出。

成功响应使用 multipart/mixed：第一段是 JSON 元数据，后续分段按输出顺序返回截图或 PDF 文件。JSON 中的 part 字段表示对应的二进制分段：

{
  "version": "1",
  "requestId": "92efeb3c-700e-4d75-a8f5-2cba093ece5b",
  "success": true,
  "outputs": [
    { "id": "page", "type": "screenshot", "contentType": "image/png", "part": 2 },
    { "id": "data", "type": "script", "value": "Page title" }
  ],
  "diagnostics": { "finalUrl": "http://127.0.0.1:8080/page" }
}

每个请求使用独立的页面。页面关闭后 Cookie 会被清理，但浏览器缓存及部分站点存储可能在后续请求之间保留；需要完全隔离不同用户或租户时，请使用独立 PageWeave 实例或独立工作目录。

常用入口

GET /：打开服务帮助页。
GET /playground：在浏览器中交互测试页面渲染、截图、PDF 和脚本结果。
GET /status：查看服务队列和运行状态。
GET /settings/logging：查看当前日志级别和启动级别。
PUT /settings/logging：调整当前进程的日志级别。
POST /cache/clear：清理当前空闲的浏览器上下文缓存，不会中断正在执行的任务。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme