docs/deployment.md

Web2API 部署指南

本文档介绍如何将 Web2API 部署到本地 Ubuntu、远程 VPS 或 Render 平台。

---

目录

• 系统要求
• 方式一：Docker 部署（推荐）
• 方式二：Docker Compose 部署
• 方式三：Ubuntu 裸机部署
• 方式四：Render 部署
• 环境变量参考
• 部署后配置
• 常见问题

---

系统要求

项目	最低要求	推荐配置
CPU	1 核	2 核+
内存	1 GB	2 GB+
磁盘	2 GB	5 GB+
系统	Ubuntu 22.04+ / Debian 12+	Ubuntu 24.04
Python	3.12+	3.12
架构	amd64 / arm64	amd64

---

方式一：Docker 部署（推荐）

最简单的部署方式，适用于本地 Ubuntu 和远程 VPS。

1. 安装 Docker

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
# 重新登录使 docker 组生效

2. 构建镜像

git clone https://github.com/shenhao-stu/web2api.git
cd web2api
git checkout feat/huggingface-postgres-space

docker build -t web2api .

3. 运行容器

docker run -d \
  --name web2api \
  -p 9000:9000 \
  -v web2api-data:/data \
  -e WEB2API_AUTH_API_KEY="your-api-key-here" \
  -e WEB2API_AUTH_CONFIG_SECRET="your-admin-password" \
  -e WEB2API_BROWSER_NO_SANDBOX=true \
  -e WEB2API_BROWSER_DISABLE_GPU=true \
  -e WEB2API_BROWSER_DISABLE_GPU_SANDBOX=true \
  web2api

4. 验证

# 检查服务状态
curl http://localhost:9000/claude/v1/models \
  -H "Authorization: Bearer your-api-key-here"

# 测试对话
curl http://localhost:9000/claude/v1/chat/completions \
  -H "Authorization: Bearer your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-4.6","stream":false,"messages":[{"role":"user","content":"Hello"}]}'

---

方式二：Docker Compose 部署

适合需要 PostgreSQL 持久化配置的场景。

创建 docker-compose.yml：

services:
  web2api:
    build: .
    ports:
      - "9000:9000"
    volumes:
      - web2api-data:/data
    environment:
      - WEB2API_AUTH_API_KEY=your-api-key-here
      - WEB2API_AUTH_CONFIG_SECRET=your-admin-password
      - WEB2API_BROWSER_NO_SANDBOX=true
      - WEB2API_BROWSER_DISABLE_GPU=true
      - WEB2API_BROWSER_DISABLE_GPU_SANDBOX=true
      - WEB2API_DATABASE_URL=postgresql://web2api:web2api@db:5432/web2api
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: web2api
      POSTGRES_PASSWORD: web2api
      POSTGRES_DB: web2api
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U web2api"]
      interval: 5s
      timeout: 3s
      retries: 5
    restart: unless-stopped

volumes:
  web2api-data:
  pgdata:

docker compose up -d

---

方式三：Ubuntu 裸机部署

适合不想用 Docker 的场景，或需要更精细控制的 VPS。

1. 安装系统依赖

sudo apt-get update && sudo apt-get install -y \
  ca-certificates curl xz-utils xvfb xauth \
  python3 python3-pip python3-venv python-is-python3 \
  software-properties-common fonts-liberation \
  libasound2t64 libatk-bridge2.0-0t64 libatk1.0-0t64 \
  libcairo2 libcups2t64 libdbus-1-3 libdrm2 \
  libfontconfig1 libgbm1 libglib2.0-0t64 libgtk-3-0t64 \
  libnspr4 libnss3 libpango-1.0-0 libu2f-udev \
  libvulkan1 libx11-6 libx11-xcb1 libxcb1 \
  libxcomposite1 libxdamage1 libxext6 libxfixes3 \
  libxkbcommon0 libxrandr2 libxrender1 libxshmfence1

注意：Ubuntu 22.04 上部分包名不带 t64 后缀，如 libasound2、libcups2 等。

2. 安装 Fingerprint Chromium

# AMD64
sudo mkdir -p /opt/fingerprint-chromium
curl -L "https://github.com/adryfish/fingerprint-chromium/releases/download/142.0.7444.175/ungoogled-chromium-142.0.7444.175-1-x86_64_linux.tar.xz" \
  -o /tmp/fp-chromium.tar.xz
sudo tar -xf /tmp/fp-chromium.tar.xz -C /opt/fingerprint-chromium --strip-components=1
rm /tmp/fp-chromium.tar.xz

# 验证
/opt/fingerprint-chromium/chrome --version

3. 安装 Python 依赖

cd /opt
git clone https://github.com/shenhao-stu/web2api.git
cd web2api
git checkout feat/huggingface-postgres-space

python -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install curl-cffi fastapi playwright pyyaml python-dotenv pydantic pytz "uvicorn[standard]"

# 如需 PostgreSQL 支持
pip install "psycopg[binary]"

4. 创建配置文件

mkdir -p /data
cp docker/config.container.yaml /data/config.yaml

根据需要编辑 /data/config.yaml，或通过环境变量覆盖。

5. 创建 systemd 服务

sudo tee /etc/systemd/system/web2api.service > /dev/null << 'EOF'
[Unit]
Description=Web2API Service
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/web2api
Environment=DISPLAY=:99
Environment=WEB2API_DATA_DIR=/data
Environment=WEB2API_CONFIG_PATH=/data/config.yaml
Environment=WEB2API_AUTH_API_KEY=your-api-key-here
Environment=WEB2API_AUTH_CONFIG_SECRET=your-admin-password
Environment=WEB2API_BROWSER_NO_SANDBOX=true
Environment=WEB2API_BROWSER_DISABLE_GPU=true
Environment=WEB2API_BROWSER_DISABLE_GPU_SANDBOX=true
Environment=HOME=/data
Environment=PYTHONUNBUFFERED=1
ExecStartPre=/bin/bash -c 'rm -rf /data/fp-data && mkdir -p /data/fp-data /tmp/.X11-unix'
ExecStartPre=/bin/bash -c 'rm -f /tmp/.X99-lock; Xvfb :99 -screen 0 1600x900x24 -nolisten tcp -ac &'
ExecStartPre=/bin/sleep 1
ExecStart=/opt/web2api/.venv/bin/python -u /opt/web2api/main.py
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now web2api

6. 查看日志

sudo journalctl -u web2api -f

---

方式四：Render 部署

Render 支持 Docker 部署，流程与 VPS 类似。

1. 创建 Render Web Service

1. 登录 Render Dashboard
2. New → Web Service → 连接 GitHub 仓库 shenhao-stu/web2api
3. 选择分支 feat/huggingface-postgres-space
4. 配置：
   • Environment: Docker
   • Instance Type: Starter ($7/月) 或更高
   • Disk: 添加 1 GB 持久化磁盘，挂载到 /data

2. 设置环境变量

在 Render Dashboard → Environment 中添加：

Key	Value
WEB2API_AUTH_API_KEY	你的 API 密钥
WEB2API_AUTH_CONFIG_SECRET	管理后台密码
WEB2API_BROWSER_NO_SANDBOX	true
WEB2API_BROWSER_DISABLE_GPU	true
WEB2API_BROWSER_DISABLE_GPU_SANDBOX	true
PORT	9000

3. （可选）添加 PostgreSQL

1. Render Dashboard → New → PostgreSQL
2. 创建后复制 Internal Database URL
3. 添加环境变量 WEB2API_DATABASE_URL = 复制的 URL

4. 部署

Render 会自动构建 Docker 镜像并部署。部署完成后通过 https://your-service.onrender.com 访问。

---

环境变量参考

必需

变量	说明	示例
WEB2API_AUTH_API_KEY	API 认证密钥	sk-your-key
WEB2API_AUTH_CONFIG_SECRET	管理后台密码	admin123

浏览器

变量	说明	默认值
WEB2API_BROWSER_NO_SANDBOX	禁用沙箱（容器必须）	false
WEB2API_BROWSER_DISABLE_GPU	禁用 GPU	false
WEB2API_BROWSER_DISABLE_GPU_SANDBOX	禁用 GPU 沙箱	false
WEB2API_BROWSER_HEADLESS	无头模式	false（使用 Xvfb）
WEB2API_BROWSER_CDP_PORT_START	CDP 起始端口	9222
WEB2API_BROWSER_CDP_PORT_COUNT	CDP 端口数量	20

服务器

变量	说明	默认值
HOST / WEB2API_SERVER_HOST	监听地址	0.0.0.0
PORT / WEB2API_SERVER_PORT	监听端口	9000
WEB2API_DATABASE_URL	PostgreSQL 连接串	空（使用 SQLite）

调度器

变量	说明	默认值
WEB2API_SCHEDULER_TAB_MAX_CONCURRENT	单 tab 最大并发	1
WEB2API_SCHEDULER_RESIDENT_BROWSER_COUNT	预热浏览器数	1

覆盖规则

所有 config.yaml 中的配置项都可以通过环境变量覆盖：

config.yaml 中的 section.key → WEB2API_SECTION_KEY

例如：claude.api_base → WEB2API_CLAUDE_API_BASE

---

部署后配置

1. 访问 http://your-host:9000/login，输入 WEB2API_AUTH_CONFIG_SECRET 设置的密码
2. 进入 /config 管理页面
3. 添加代理组（Proxy Group）：
   • 如不需要代理，取消勾选 use_proxy，fingerprint_id 填任意唯一标识
4. 添加 Claude 账号：
   • name：任意名称
   • type：claude
   • auth：{"sessionKey": "你的 Claude sessionKey"}
5. 点击 Save config
6. （可选）开启 Pro models 开关以使用 Haiku / Opus 模型

获取 sessionKey

1. 登录 claude.ai
2. 打开浏览器开发者工具 → Application → Cookies
3. 复制 sessionKey 的值

---

常见问题

Page crashed / OOM

浏览器内存不足导致页面崩溃。解决方案：

• 升级服务器内存到 2 GB+
• 减少 WEB2API_SCHEDULER_TAB_MAX_CONCURRENT 为 1
• 减少 WEB2API_BROWSER_CDP_PORT_COUNT 为 3
• 设置 WEB2API_SCHEDULER_RESIDENT_BROWSER_COUNT=0 禁用预热

D-Bus / XKEYBOARD 警告

容器环境中的正常噪音，不影响功能和性能，可忽略。

Page.goto: Timeout

浏览器导航超时，通常是网络问题或 Claude 服务暂时不可用。服务会自动重试（最多 3 次）。如果持续出现：

• 检查服务器到 claude.ai 的网络连通性
• 检查代理配置是否正确
• 检查 sessionKey 是否过期

端口冲突

默认使用 9000 端口和 9222-9241 的 CDP 端口。如有冲突：

-e PORT=8080 \
-e WEB2API_BROWSER_CDP_PORT_START=19222 \
-e WEB2API_BROWSER_CDP_PORT_COUNT=6