Obscura 生产部署：Docker、Systemd、多 Worker 与资源调优

从开发到生产

本地使用 obscura fetch 很简单，但正式环境需要进程管理、资源隔离、监控和扩展能力。本文介绍 Obscura 的生产部署方案。

Docker 部署

官方 Docker 镜像基于 distroless/cc（不含 shell 和包管理器），压缩后约 57 MB。

# 基础运行
docker run -d \
  --name obscura \
  --restart unless-stopped \
  -p 127.0.0.1:9222:9222 \
  -v /srv/obscura/data:/data \
  h4ckf0r0day/obscura \
  serve --host 0.0.0.0 --storage-dir /data --stealth
 
# 查看日志
docker logs -f obscura

默认命令是 serve，可以通过镜像名后的参数覆盖。

资源限制：

docker run -d \
  --name obscura \
  --memory=4g \
  --cpus=2 \
  -p 127.0.0.1:9222:9222 \
  h4ckf0r0day/obscura

Systemd 服务

对于直接部署在服务器上的场景，Systemd 是推荐的方式。

# /etc/systemd/system/obscura.service
[Unit]
Description=Obscura headless browser
After=network.target
 
[Service]
ExecStart=/usr/local/bin/obscura serve \
  --port 9222 \
  --stealth \
  --storage-dir /var/lib/obscura
Restart=always
RestartSec=5
User=obscura
Group=obscura
LimitNOFILE=65536
MemoryMax=4G
MemoryHigh=3G
 
[Install]
WantedBy=multi-user.target

启用并启动：

sudo systemctl daemon-reload
sudo systemctl enable --now obscura
sudo journalctl -fu obscura

MemoryMax 和 MemoryHigh 使用 cgroups 限制内存，防止单个实例吃光服务器内存。

多 Worker 扩展

obscura serve --workers N 启动 N 个 Worker 进程。这是多进程模式，不是多线程。

# 4 Worker，适合 4 核 CPU
obscura serve --workers 4

Workers 实现原理

每个 Worker 是一个独立进程，端口从指定端口 + 1 开始依次分配：

主进程 (port 9222) → 负载均衡
  │
  ├── Worker 1 (port 9223)
  ├── Worker 2 (port 9224)
  ├── Worker 3 (port 9225)
  └── Worker 4 (port 9226)

主进程运行一个负载均衡器，将入站连接按轮询转发给各个 Worker。Session 对 Worker 是粘性的——同一个浏览器上下文始终连接到同一个 Worker。

建议：Worker 数 = CPU 核心数。

# 8 核机器
obscura serve --workers 8

V8 堆调优

V8 默认堆大小因架构而异：

架构	默认 `max-old-space-size`	其他默认参数
64-bit	4096 MB	`--max-semi-space-size=4 --optimize-for-size`
非 64-bit	1024 MB	`--max-semi-space-size=4 --optimize-for-size`

--optimize-for-size 让 V8 偏向内存效率而非极致性能，有助于降低 RSS。

通过 --v8-flags 覆盖：

# 降低内存上限，适合内存受限环境
obscura serve --v8-flags "--max-old-space-size=2048"
 
# 提高内存上限，适合重型 SPA
obscura serve --v8-flags "--max-old-space-size=8192 --max-semi-space-size=8"

传递的参数追加在默认参数之后，V8 使用最后一个值，因此你的覆盖生效而其他默认参数保持不变。

反向代理与 WebSocket

CDP 需要使用 WebSocket，因此反向代理必须支持 WebSocket 升级。

Nginx 配置

location /obscura/ {
  proxy_pass http://127.0.0.1:9222/;
  proxy_http_version 1.1;
  proxy_set_header Upgrade $http_upgrade;
  proxy_set_header Connection "upgrade";
  proxy_read_timeout 86400;
}
 
# MCP HTTP 传输
location /mcp/ {
  proxy_pass http://127.0.0.1:3000/;
  proxy_read_timeout 86400;
}

CDP 连接可能长时间保持（Puppeteer/Playwright 会话），proxy_read_timeout 需要设置一个很大的值（单位秒，86400 = 24 小时）。

推荐使用 Caddy 自动管理 TLS：

obscura.example.16yun.cn {
  reverse_proxy /obscura/* 127.0.0.1:9222 {
    header_up Upgrade {http.request.header.Upgrade}
    header_up Connection {http.request.header.Connection}
  }
}

安全配置

Obscura 自身没有内置认证机制，谁能访问端口谁就能驱动浏览器。

基本原则

默认绑定 127.0.0.1：只在本地可访问
Docker 端口映射：-p 127.0.0.1:9222:9222 避免暴露到外网
反向代理认证：在反向代理层增加 Basic Auth 或 OAuth
网络隔离：使用 Docker network 限制访问来源

禁止事项

# 否 不要将 CDP 端口直接暴露到公网
obscura serve --host 0.0.0.0 --port 9222   # 危险！
 
# 是 使用反向代理 + 认证
obscura serve --host 127.0.0.1 --port 9222

MCP HTTP 安全

OBSCURA_MCP_ALLOWED_ORIGINS="https://app.16yun.cn" \
  obscura mcp --http --host 0.0.0.0 --port 3000

超时调优

通过环境变量调整各项超时：

export OBSCURA_NAV_TIMEOUT_MS=60000      # 导航超时（默认 30s）
export OBSCURA_CDP_COMMAND_TIMEOUT_MS=30000  # CDP 命令超时（默认 60s）
export OBSCURA_FETCH_TIMEOUT_MS=20000    # fetch/XHR 超时（默认 30s）
obscura serve

监控与日志

# 详细日志
obscura serve --verbose
 
# 调试日志
RUST_LOG=obscura=debug obscura serve
 
# CDP 层调试
RUST_LOG=obscura_cdp=trace,obscura_browser=debug obscura serve
 
# 日志输出到文件
RUST_LOG=obscura=info obscura serve 2>> /var/log/obscura.log

生产 Checklist

上线前逐项确认：

Docker/Systemd 服务能在服务器重启后自动启动
资源限制已配置（MemoryMax、LimitNOFILE）
V8 堆大小根据页面类型调整
反向代理支持 WebSocket 和长超时
端口只暴露给受信网络
启用 Stealth 模式（除非明确不需要）
配置存储目录持久化 Cookie 和 localStorage
日志轮转已配置
为预期并发压力测试 Worker 数量

总结

Obscura 的生产部署和标准 Web 服务类似，关键差异点在于：WebSocket 长连接需要反向代理的特殊配置、多进程 Worker 扩展与资源隔离、以及 V8 堆大小需要根据页面负载调整。

Obscura 生产部署——Docker、Systemd、多 Worker 与资源调优