AI浏览器 Docker部署教程｜附配置文件

随着大模型能力的提升，“AI 浏览器”逐渐成为很多自动化场景中的基础工具。它并不是传统意义上的浏览器插件，而是一个可以被 AI Agent 调用的浏览器运行环境：AI 可以打开网页、点击按钮、填写表单、读取页面内容、截图分析，甚至完成一些多步骤任务。例如自动检索资料、登录后台查看数据、生成网页摘要、执行网页测试等。

本文将介绍一种适合个人开发者、团队测试环境使用的 AI 浏览器 Docker 部署方案。部署完成后，你可以获得一个隔离的浏览器运行环境，并通过 API 或控制台让 AI 调用浏览器执行任务。

本文内容包括：

• AI 浏览器部署思路
• Docker 环境准备
• 项目目录结构
• docker-compose.yml 配置文件
• 环境变量 .env 配置
• Playwright 浏览器服务配置
• 可视化远程浏览器访问方式
• 启动、停止、更新与排错
• 安全与生产环境建议

说明：本文以“AI Agent + Playwright Chromium 浏览器 + Docker 容器化部署”为示例。你可以将其作为自建 AI 浏览器环境的基础模板，也可以根据自己的业务接入不同的大模型 API。

一、什么是 AI 浏览器？

AI 浏览器可以理解为一个由 AI 控制的浏览器环境。传统浏览器需要用户手动点击、输入、浏览网页，而 AI 浏览器可以通过代码或 Agent 指令自动操作网页。

例如，你可以让 AI 完成如下任务：

打开指定网页，搜索“Docker 部署 Playwright”，阅读前 3 个结果，总结部署步骤。

AI 浏览器背后通常包括以下几个部分：

1. 浏览器内核
   一般使用 Chromium、Chrome、Firefox 或 WebKit。

2. 自动化控制框架
   常见的是 Playwright、Puppeteer、Selenium 等。

3. AI Agent 层
   负责理解用户任务，并将自然语言任务拆解成浏览器操作。

4. 大模型 API
   比如 OpenAI、Claude、通义千问、智谱、DeepSeek 等。

5. 可视化调试界面
   方便开发者查看 AI 当前打开的网页、点击位置、页面状态等。

本文的核心目标是：通过 Docker 快速部署一个可被 AI 调用的浏览器运行环境。

二、部署架构说明

本教程采用如下架构：

用户 / 调用方
    |
    | HTTP API / WebSocket
    |
AI Agent 服务
    |
    | Playwright
    |
Chromium 浏览器容器
    |
    | 可选：VNC / noVNC
    |
浏览器可视化界面

整体包含两个主要服务：

如果你只是开发调试，也可以把 AI Agent 和浏览器放在同一个容器里。但在更规范的部署中，建议拆分服务，方便维护、扩容和升级。

三、服务器环境要求

建议服务器配置如下：

如果你希望同时运行多个浏览器实例，建议至少 4 核 8GB 内存。Chromium 在无头模式下资源占用相对可控，但如果启用可视化桌面或多个并发页面，内存占用会明显增加。

四、安装 Docker 和 Docker Compose

如果你的服务器还没有安装 Docker，可以使用下面命令安装。

1. 更新系统软件包

sudo apt update
sudo apt upgrade -y

2. 安装依赖

sudo apt install -y ca-certificates curl gnupg lsb-release

3. 安装 Docker

curl -fsSL https://get.docker.com | bash

4. 设置 Docker 开机自启

sudo systemctl enable docker
sudo systemctl start docker

5. 验证 Docker 是否安装成功

docker version

6. 验证 Docker Compose

docker compose version

如果能看到版本号，说明环境准备完成。

五、创建项目目录

建议将所有配置文件统一放在 /opt/ai-browser 目录下：

sudo mkdir -p /opt/ai-browser
cd /opt/ai-browser

创建基础目录结构：

mkdir -p data logs config screenshots

最终目录结构如下：

/opt/ai-browser
├── docker-compose.yml
├── .env
├── config
│   └── browser.yml
├── data
├── logs
└── screenshots

各目录用途：

六、编写 docker-compose.yml

在 /opt/ai-browser 目录下创建 docker-compose.yml 文件：

nano docker-compose.yml

写入以下内容：

version: "3.9"

services:
  ai-browser:
    image: node:20-bookworm
    container_name: ai-browser
    working_dir: /app
    restart: unless-stopped
    env_file:
      - .env
    volumes:
      - ./data:/app/data
      - ./logs:/app/logs
      - ./config:/app/config
      - ./screenshots:/app/screenshots
    ports:
      - "${AI_BROWSER_PORT}:3000"
    command: >
      sh -c "
      npm install -g pnpm &&
      if [ ! -f package.json ]; then
        echo '请将你的 AI Browser 项目代码放到 /app，或替换 compose 中的启动命令';
        tail -f /dev/null;
      else
        pnpm install &&
        pnpm start
      fi
      "
    networks:
      - ai-browser-net
    depends_on:
      - browser

  browser:
    image: mcr.microsoft.com/playwright:v1.48.2-jammy
    container_name: ai-browser-playwright
    restart: unless-stopped
    ipc: host
    shm_size: "2gb"
    environment:
      - TZ=Asia/Shanghai
      - PLAYWRIGHT_BROWSERS_PATH=/ms-playwright
    volumes:
      - ./data:/data
      - ./screenshots:/screenshots
    ports:
      - "${PLAYWRIGHT_DEBUG_PORT}:9222"
    command: >
      bash -c "
      chromium
      --headless=new
      --no-sandbox
      --disable-dev-shm-usage
      --disable-gpu
      --remote-debugging-address=0.0.0.0
      --remote-debugging-port=9222
      about:blank
      "
    networks:
      - ai-browser-net

networks:
  ai-browser-net:
    driver: bridge

这个配置中需要注意几个关键点：

1. shm_size: "2gb"

Chromium 对共享内存比较敏感。如果不设置，可能会出现浏览器崩溃、页面加载异常等问题。

2. --no-sandbox

在 Docker 容器中运行 Chromium 时，经常需要关闭沙箱。生产环境建议通过更严格的容器隔离、非 root 用户、网络访问控制等方式增强安全性。

3. --remote-debugging-port=9222

开启远程调试端口后，AI Agent 或调试工具可以通过 Chrome DevTools Protocol 连接到浏览器。

4. browser 服务独立运行

将浏览器单独放在一个容器里，有利于后续横向扩展。例如你可以运行多个 browser 实例，供不同 Agent 使用。

七、编写 .env 配置文件

继续在 /opt/ai-browser 目录下创建 .env 文件：

nano .env

写入以下内容：

# ======================
# 基础服务配置
# ======================

AI_BROWSER_PORT=3000
PLAYWRIGHT_DEBUG_PORT=9222

NODE_ENV=production
TZ=Asia/Shanghai

# ======================
# 大模型配置
# ======================

LLM_PROVIDER=openai
OPENAI_API_KEY=sk-your-openai-api-key
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4o-mini

# 如果你使用 DeepSeek，可以参考：
# LLM_PROVIDER=deepseek
# OPENAI_API_KEY=sk-your-deepseek-api-key
# OPENAI_BASE_URL=https://api.deepseek.com
# OPENAI_MODEL=deepseek-chat

# 如果你使用通义千问兼容 OpenAI 接口：
# LLM_PROVIDER=qwen
# OPENAI_API_KEY=sk-your-qwen-api-key
# OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
# OPENAI_MODEL=qwen-plus

# ======================
# 浏览器连接配置
# ======================

BROWSER_WS_ENDPOINT=ws://browser:9222/devtools/browser
BROWSER_HOST=browser
BROWSER_PORT=9222

# ======================
# 任务配置
# ======================

MAX_STEPS=20
STEP_TIMEOUT=30000
PAGE_LOAD_TIMEOUT=60000

# 是否保存截图
SAVE_SCREENSHOT=true
SCREENSHOT_DIR=/app/screenshots

# 是否启用详细日志
DEBUG=false
LOG_LEVEL=info

配置说明：

注意：不要将 .env 文件提交到公开 Git 仓库，因为里面通常包含 API Key 等敏感信息。

八、编写浏览器配置文件

创建 config/browser.yml：

nano config/browser.yml

写入以下配置：

browser:
  type: chromium
  headless: true
  viewport:
    width: 1440
    height: 900
  locale: zh-CN
  timezone: Asia/Shanghai
  user_agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 Chrome/120 Safari/537.36

page:
  default_timeout: 30000
  navigation_timeout: 60000
  wait_until: networkidle

screenshot:
  enabled: true
  path: /app/screenshots
  full_page: true

download:
  enabled: true
  path: /app/data/downloads

security:
  allow_private_ip: false
  allow_file_protocol: false
  block_ads: false
  block_trackers: false

agent:
  max_steps: 20
  retry_times: 2
  observe_with_screenshot: true
  observe_with_html: true

这份配置可以作为 AI Agent 读取的统一参数。不同项目的字段名称可能不同，但配置思路基本一致。

九、接入你的 AI Browser 项目代码

上面的 docker-compose.yml 中，ai-browser 服务使用的是 node:20-bookworm 镜像，并假设你的应用代码在容器 /app 目录中。

如果你已经有自己的 AI Browser 项目，可以将代码放到 /opt/ai-browser/app，然后修改挂载配置。例如：

mkdir -p app

然后修改 docker-compose.yml 中 ai-browser 的 volumes：

volumes:
  - ./app:/app
  - ./data:/app/data
  - ./logs:/app/logs
  - ./config:/app/config
  - ./screenshots:/app/screenshots

如果你的项目启动命令是：

npm run start

则可以将 command 改为：

command: >
  sh -c "
  npm install &&
  npm run start
  "

如果你使用 Python 项目，例如基于 FastAPI、browser-use 或 LangChain，可以将 ai-browser 服务改为 Python 镜像：

ai-browser:
  image: python:3.11-slim
  container_name: ai-browser
  working_dir: /app
  restart: unless-stopped
  env_file:
    - .env
  volumes:
    - ./app:/app
    - ./data:/app/data
    - ./logs:/app/logs
    - ./config:/app/config
    - ./screenshots:/app/screenshots
  ports:
    - "${AI_BROWSER_PORT}:8000"
  command: >
    sh -c "
    pip install -r requirements.txt &&
    uvicorn main:app --host 0.0.0.0 --port 8000
    "
  networks:
    - ai-browser-net
  depends_on:
    - browser

十、启动服务

在 /opt/ai-browser 目录下执行：

docker compose up -d

查看容器状态：

docker compose ps

如果看到类似输出，说明服务已经启动：

NAME                    IMAGE                                      STATUS
ai-browser              node:20-bookworm                           Up
ai-browser-playwright   mcr.microsoft.com/playwright:v1.48.2-jammy  Up

查看日志：

docker compose logs -f

查看浏览器容器日志：

docker logs -f ai-browser-playwright

十一、测试浏览器远程调试端口

在服务器上执行：

curl http://127.0.0.1:9222/json/version

如果返回类似内容，说明 Chromium 远程调试端口正常：

{
  "Browser": "Chrome/120.0.0.0",
  "Protocol-Version": "1.3",
  "User-Agent": "Mozilla/5.0 ...",
  "webSocketDebuggerUrl": "ws://127.0.0.1:9222/devtools/browser/xxxx"
}

在 Docker 网络内部，AI Agent 应该通过以下地址访问浏览器：

http://browser:9222

或者使用 WebSocket 地址：

ws://browser:9222/devtools/browser/xxxx

需要注意，/devtools/browser/xxxx 后面的 ID 每次启动可能会变化。因此实际项目中通常先访问：

http://browser:9222/json/version

再从返回值中读取 webSocketDebuggerUrl。

十二、可选：增加 noVNC 可视化浏览器

如果你希望在网页中实时看到 AI 操作浏览器，可以增加一个带 VNC/noVNC 的浏览器容器。下面是一个可选配置。

在 docker-compose.yml 中新增服务：

  browser-vnc:
    image: browserless/chrome:latest
    container_name: ai-browser-vnc
    restart: unless-stopped
    shm_size: "2gb"
    environment:
      - CONNECTION_TIMEOUT=600000
      - MAX_CONCURRENT_SESSIONS=3
      - DEFAULT_LAUNCH_ARGS=["--no-sandbox","--disable-dev-shm-usage"]
    ports:
      - "3001:3000"
    networks:
      - ai-browser-net

启动后访问：

http://服务器IP:3001

不过需要注意，browserless/chrome 更偏向浏览器服务化和调试场景，不同版本的配置方式可能会变化。如果你需要稳定的可视化桌面，也可以使用 selenium/standalone-chrome 镜像。

示例配置如下：

  selenium-chrome:
    image: selenium/standalone-chrome:latest
    container_name: ai-browser-selenium
    restart: unless-stopped
    shm_size: "2gb"
    ports:
      - "4444:4444"
      - "7900:7900"
    environment:
      - SE_NODE_MAX_SESSIONS=2
      - SE_NODE_OVERRIDE_MAX_SESSIONS=true
      - VNC_NO_PASSWORD=1
    networks:
      - ai-browser-net

访问 noVNC：

http://服务器IP:7900

如果设置了密码，请根据容器镜像文档查看默认密码或自定义环境变量。

十三、Nginx 反向代理配置

如果你希望通过域名访问 AI Browser API，可以使用 Nginx 进行反向代理。

假设域名为：

ai-browser.example.com

创建 Nginx 配置：

sudo nano /etc/nginx/sites-available/ai-browser.conf

写入：

server {
    listen 80;
    server_name ai-browser.example.com;

    client_max_body_size 50m;

    location / {
        proxy_pass http://127.0.0.1:3000;

        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        proxy_read_timeout 600s;
        proxy_send_timeout 600s;
    }
}

启用配置：

sudo ln -s /etc/nginx/sites-available/ai-browser.conf /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

申请 HTTPS 证书：

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d ai-browser.example.com

十四、安全配置建议

AI 浏览器具备访问网页、提交表单、执行自动化操作的能力，因此安全问题必须重视。

1. 不要直接暴露调试端口

9222 是 Chromium DevTools 调试端口，一旦暴露到公网，攻击者可能直接控制浏览器。因此生产环境建议不要映射该端口到公网。

可以将：

ports:
  - "${PLAYWRIGHT_DEBUG_PORT}:9222"

改为仅本地监听：

ports:
  - "127.0.0.1:${PLAYWRIGHT_DEBUG_PORT}:9222"

或者完全删除 ports，只允许 Docker 内部网络访问。

2. 为 API 增加鉴权

建议在 AI Browser 服务中增加 API Token，例如：

API_TOKEN=your-strong-random-token

调用接口时必须携带：

Authorization: Bearer your-strong-random-token

3. 限制访问范围

如果 AI 浏览器只需要访问特定网站，建议在应用层做域名白名单，例如：

ALLOWED_DOMAINS=example.com,docs.example.com

避免 AI 被提示词诱导访问恶意站点。

4. 禁止访问内网敏感地址

务必防止 AI 浏览器访问：

127.0.0.1
localhost
169.254.169.254
10.0.0.0/8
172.16.0.0/12
192.168.0.0/16

尤其是云服务器环境中，169.254.169.254 可能暴露实例元数据。

5. 控制任务执行时长

建议设置最大步骤数、超时时间、最大页面数，避免任务失控：

MAX_STEPS=20
STEP_TIMEOUT=30000
PAGE_LOAD_TIMEOUT=60000

十五、常见问题与解决方法

1. 浏览器容器启动后立刻退出

查看日志：

docker logs ai-browser-playwright

常见原因包括 Chromium 启动参数不兼容、共享内存不足等。可以确认是否配置：

shm_size: "2gb"
ipc: host

也可以尝试增加参数：

--disable-dev-shm-usage
--no-sandbox

2. AI Agent 无法连接浏览器

先进入 AI Agent 容器：

docker exec -it ai-browser bash

测试连接：

curl http://browser:9222/json/version

如果无法访问，检查两个服务是否在同一个 Docker 网络中：

docker network ls
docker network inspect ai-browser_ai-browser-net

3. 页面加载很慢

可能原因包括：

• 服务器网络较慢
• 目标网站有反爬策略
• DNS 解析慢
• 页面资源过大
• 容器内存不足

可以尝试：

dns:
  - 8.8.8.8
  - 1.1.1.1

或者提高超时时间：

PAGE_LOAD_TIMEOUT=120000

4. 中文字体显示异常

部分基础镜像缺少中文字体。可以自定义 Dockerfile 安装字体：

FROM mcr.microsoft.com/playwright:v1.48.2-jammy

RUN apt-get update && apt-get install -y \
    fonts-noto-cjk \
    fonts-wqy-zenhei \
    && rm -rf /var/lib/apt/lists/*

然后修改 Compose：

browser:
  build:
    context: .
    dockerfile: Dockerfile.browser

5. 截图为空白

可能是页面还没加载完成就截图。建议在代码中等待：

await page.waitForLoadState('networkidle')
await page.screenshot({ path: 'screenshots/page.png', fullPage: true })

或者增加配置：

page:
  wait_until: networkidle

十六、更新与维护

1. 停止服务

docker compose down

2. 重启服务

docker compose restart

3. 查看实时日志

docker compose logs -f --tail=200

4. 更新镜像

docker compose pull
docker compose up -d

5. 清理无用镜像

docker system prune -f

如果你要清理未使用的数据卷，需要谨慎执行：

docker system prune -a --volumes

该命令可能删除重要数据，不建议在生产环境随意使用。

十七、生产环境部署建议

如果你打算把 AI 浏览器部署到生产环境，建议进一步优化：

1. 使用自定义镜像
   不要每次容器启动都执行 npm install 或 pip install，而是提前构建镜像。

2. 增加队列系统
   对于耗时任务，可以使用 Redis、RabbitMQ、Kafka 等队列系统。

3. 任务隔离
   每个任务使用独立浏览器上下文，避免 Cookie、缓存、登录态互相污染。

4. 日志审计
   保存任务 ID、访问 URL、执行步骤、截图、错误信息，便于追踪问题。

5. 资源限制
   使用 Docker 的 CPU 和内存限制，防止单个任务耗尽服务器资源。

示例：

deploy:
  resources:
    limits:
      cpus: "2"
      memory: 2G

需要注意，deploy.resources 在普通 docker compose 模式下支持有限，完整资源编排建议使用 Docker Swarm 或 Kubernetes。

6. 敏感信息脱敏
   日志中不要输出 API Key、Cookie、Authorization Header、表单密码等内容。

7. 权限最小化
   容器尽量不要使用 root 用户，避免挂载宿主机敏感目录。

十八、完整配置文件汇总

下面给出一份相对完整的 docker-compose.yml，适合直接作为基础模板使用。

version: "3.9"

services:
  ai-browser:
    image: node:20-bookworm
    container_name: ai-browser
    working_dir: /app
    restart: unless-stopped
    env_file:
      - .env
    volumes:
      - ./app:/app
      - ./data:/app/data
      - ./logs:/app/logs
      - ./config:/app/config
      - ./screenshots:/app/screenshots
    ports:
      - "${AI_BROWSER_PORT}:3000"
    command: >
      sh -c "
      npm install -g pnpm &&
      pnpm install &&
      pnpm start
      "
    networks:
      - ai-browser-net
    depends_on:
      - browser

  browser:
    image: mcr.microsoft.com/playwright:v1.48.2-jammy
    container_name: ai-browser-playwright
    restart: unless-stopped
    ipc: host
    shm_size: "2gb"
    environment:
      - TZ=Asia/Shanghai
      - PLAYWRIGHT_BROWSERS_PATH=/ms-playwright
    volumes:
      - ./data:/data
      - ./screenshots:/screenshots
    ports:
      - "127.0.0.1:${PLAYWRIGHT_DEBUG_PORT}:9222"
    command: >
      bash -c "
      chromium
      --headless=new
      --no-sandbox
      --disable-dev-shm-usage
      --disable-gpu
      --remote-debugging-address=0.0.0.0
      --remote-debugging-port=9222
      about:blank
      "
    networks:
      - ai-browser-net

networks:
  ai-browser-net:
    driver: bridge

完整 .env 示例：

AI_BROWSER_PORT=3000
PLAYWRIGHT_DEBUG_PORT=9222

NODE_ENV=production
TZ=Asia/Shanghai

LLM_PROVIDER=openai
OPENAI_API_KEY=sk-your-api-key
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4o-mini

BROWSER_HOST=browser
BROWSER_PORT=9222

MAX_STEPS=20
STEP_TIMEOUT=30000
PAGE_LOAD_TIMEOUT=60000

SAVE_SCREENSHOT=true
SCREENSHOT_DIR=/app/screenshots

DEBUG=false
LOG_LEVEL=info

API_TOKEN=change-this-token

十九、总结

通过 Docker 部署 AI 浏览器，可以让浏览器运行环境更加稳定、隔离和可复现。本文提供的方案使用 Docker Compose 管理 AI Agent 服务与 Playwright Chromium 浏览器服务，适合开发测试、自建自动化浏览器、网页摘要、网页数据采集、后台自动化操作等场景。

部署时需要重点关注三点：

1. 浏览器容器稳定性
   建议配置 shm_size、--no-sandbox、--disable-dev-shm-usage 等参数。

2. 大模型与浏览器连接配置
   AI Agent 需要能正确访问 browser:9222，并读取 DevTools WebSocket 地址。

3. 安全控制
   不要将调试端口直接暴露到公网，API 必须增加鉴权，并限制 AI 浏览器访问内网敏感地址。

如果只是个人测试，可以使用本文的配置快速启动；如果是团队或生产环境，建议进一步封装自定义镜像、加入任务队列、权限隔离和日志审计。这样不仅能提升稳定性，也能降低 AI 自动化浏览器带来的安全风险。