基于Alpine Linux 构建的轻量、高性能的 Headless 浏览器 API 容器
1.4K
高性能无头浏览器渲染服务，基于 Fastify、puppeteer-core、generic-pool 构建，支持动态页面渲染、截图、接口监听和文件抓取。
BrowserContext 隔离每次请求的 Cookie、缓存和本地存储puppeteer-extra-plugin-stealth 降低基础自动化特征暴露cp .env.example .env
# 修改 .env 中的 API_KEY
docker-compose up -d
npm install
cp .env.example .env
# 修改 .env 中的 API_KEY 与 Chromium 路径
npm start
| 变量名 | 默认值 | 说明 |
|---|---|---|
API_KEY | 空 | 接口鉴权密钥。生产环境必须设置 |
PORT | 3000 | 服务端口 |
HOST | 0.0.0.0 | 监听地址 |
MIN_BROWSERS | 2 | 浏览器池最小实例数 |
MAX_BROWSERS | 10 | 浏览器池最大实例数 |
PUPPETEER_EXECUTABLE_PATH | /usr/bin/chromium | Chromium 可执行文件路径 |
ALLOW_PRIVATE_NETWORK | false | 是否允许访问本地或内网地址。默认关闭以避免 SSRF 风险 |
API_KEYhttp / https 目标ALLOW_PRIVATE_NETWORK=false 时，会拒绝本地地址、回环地址和常见内网地址/fetch-file 会同时校验页面地址和文件地址x-api-key: your-secret-keyapplication/jsonok: trueok: false 和 error渲染页面并返回完整 HTML。
curl -X POST http://localhost:3000/render \
-H "Content-Type: application/json" \
-H "x-api-key: your-secret-key" \
-d '{
"url": "https://www.douyin.com",
"waitFor": "networkidle2",
"timeout": 15000
}'
| 参数 | 类型 | 说明 |
|---|---|---|
url | string | 目标页面 URL，必填 |
waitFor | string | 等待时机：load / domcontentloaded / networkidle0 / networkidle2 |
timeout | number | 超时毫秒数，默认 15000 |
headers | object | 附加请求头 |
cookies | string | object[] | Cookie 字符串或 Cookie 对象数组 |
{
"ok": true,
"html": "<html>...</html>",
"title": "页面标题",
"finalUrl": "https://www.douyin.com/"
}
对目标页面截图，返回图片二进制流。
curl -X POST http://localhost:3000/screenshot \
-H "Content-Type: application/json" \
-H "x-api-key: your-secret-key" \
--output screenshot.png \
-d '{
"url": "https://example.com",
"waitFor": "networkidle2",
"format": "png",
"fullPage": true,
"viewport": {
"width": 1440,
"height": 900,
"deviceScaleFactor": 1
}
}'
| 参数 | 类型 | 说明 |
|---|---|---|
url | string | 目标页面 URL，必填 |
waitFor | string | 等待时机：load / domcontentloaded / networkidle0 / networkidle2 |
timeout | number | 超时毫秒数，默认 20000 |
headers | object | 附加请求头 |
cookies | string | object[] | Cookie 字符串或 Cookie 对象数组 |
format | string | 图片格式：png / jpeg / webp，默认 png |
fullPage | boolean | 是否截全页，默认 true |
quality | number | jpeg / webp 质量，范围 0-100 |
clip | object | 指定截图区域，传入后会忽略 fullPage |
viewport | object | 视口设置，支持 width、height、deviceScaleFactor |
Content-Type 会根据 format 自动设置Content-Disposition 为 inline; filename="screenshot.xxx"打开页面时同时监听接口响应和目标资源类型。
curl -X POST http://localhost:3000/intercept \
-H "Content-Type: application/json" \
-H "x-api-key: your-secret-key" \
-d '{
"url": "https://example.com",
"listenUrls": ["/api/feed", "/graphql"],
"fileTypes": ["image", "video"],
"timeout": 20000
}'
| 参数 | 类型 | 说明 |
|---|---|---|
url | string | 目标页面 URL，必填 |
listenUrls | string[] | 需要监听的接口 URL 关键字 |
fileTypes | string[] | 需要记录的资源类型：image / video / audio / pdf / json / css / js / font |
timeout | number | 超时毫秒数，默认 20000 |
headers | object | 附加请求头 |
cookies | string | object[] | Cookie 字符串或 Cookie 对象数组 |
{
"ok": true,
"finalUrl": "https://example.com/",
"captured": [
{
"url": "https://api.example.com/feed",
"status": 200,
"contentType": "application/json",
"body": {
"items": []
}
}
],
"files": [
{
"url": "https://cdn.example.com/video.mp4",
"contentType": "video/mp4",
"status": 200
}
]
}
下载页面加载过程中命中的单个文件，返回文件二进制流。
curl -X POST http://localhost:3000/fetch-file \
-H "Content-Type: application/json" \
-H "x-api-key: your-secret-key" \
--output video.mp4 \
-d '{
"url": "https://example.com/page",
"fileUrl": "https://cdn.example.com/video.mp4"
}'
| 参数 | 类型 | 说明 |
|---|---|---|
url | string | 触发下载的页面 URL，必填 |
fileUrl | string | 目标文件 URL，必填 |
timeout | number | 超时毫秒数，默认 20000 |
cookies | string | object[] | Cookie 字符串或 Cookie 对象数组 |
404健康检查接口。
curl http://localhost:3000/health
{
"ok": true,
"pool": {
"size": 5,
"available": 3,
"borrowed": 2
}
}
支持两种写法：
{
"cookies": "session=abc; token=xyz"
}
{
"cookies": [
{
"name": "session",
"value": "abc",
"httpOnly": true,
"secure": true
}
]
}
当前版本已接入以下策略：
puppeteer-extra + puppeteer-extra-plugin-stealthuser-agent-override，统一处理 UA、语言和平台信息User-AgentBrowserContext说明：
stealth 只能降低被简单规则识别的概率，不能保证绕过所有反爬策略npm test
当前测试覆盖以下关键行为：
MAX_BROWSERS=10 以下MAX_BROWSERS=15 起评估shm_sizePUPPETEER_EXECUTABLE_PATH 一致Content type
Image
Digest
sha256:f34b9fa48…
Size
432.5 MB
Last updated
29 days ago
docker pull zhuhanxin/brower_headless