CoPaw Docker 镜像完整构建教程 - 从零到生产环境部署

AI人工智能 6 小时前 0 1

前言

CoPaw 是一款强大的 AI 智能助手，支持多种大模型接入和丰富的技能扩展。本文详细介绍如何基于 CoPaw 官方安装脚本构建 Docker 镜像，并提供完整的生产环境部署方案。

官方安装脚本：https://copaw.agentscope.io/install.sh

一、项目文件结构

copaw-docker/
├── Dockerfile           # Docker 镜像构建文件
├── docker-compose.yml   # Docker Compose 配置
├── .env.example         # 环境变量示例
├── .env                 # 实际环境变量（需自行创建）
├── build.sh             # 构建和测试脚本
├── README_DOCKER.md     # 详细文档
├── data/                # 数据目录
├── logs/                # 日志目录
├── config/              # 配置目录
└── skills/              # 技能目录

二、Dockerfile 详解

2.1 基础镜像选择

# 使用 Python 3.12 slim 版本（与官方安装脚本一致）
FROM python:3.12-slim

2.2 环境变量配置

ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1 \
    PIP_NO_CACHE_DIR=1 \
    COPAW_HOME="/root/.copaw" \
    COPAW_VENV="/root/.copaw/venv" \
    COPAW_BIN="/root/.copaw/bin" \
    PATH="/root/.copaw/bin:$PATH"

2.3 系统依赖安装

# 安装基础工具
RUN apt-get update && apt-get install -y --no-install-recommends \
    curl \
    git \
    build-essential \
    libpq-dev \
    # 图像处理支持
    ffmpeg \
    libsm6 \
    libxext6 \
    # Playwright 浏览器依赖
    libnss3 \
    libnspr4 \
    libatk1.0-0 \
    libatk-bridge2.0-0 \
    libcups2 \
    libdrm2 \
    libdbus-1-3 \
    libxkbcommon0 \
    libxcomposite1 \
    libxdamage1 \
    libxfixes3 \
    libxrandr2 \
    libgbm1 \
    libasound2 \
    ca-certificates \
    && rm -rf /var/lib/apt/lists/*

2.4 安装 uv 包管理器

# uv 是 CoPaw 使用的 Python 包管理器
RUN curl -LsSf https://astral.sh/uv/install.sh | sh
ENV PATH="/root/.local/bin:$PATH"

2.5 安装 CoPaw

# 方式一：从源码安装（推荐，获取最新版本）
RUN curl -fsSL https://copaw.agentscope.io/install.sh | bash -s -- --from-source

# 方式二：从 PyPI 安装（稳定版本）
# RUN uv pip install copaw --python /root/.copaw/venv/bin/python --prerelease=allow

2.6 安装 Playwright 浏览器

# 安装 Chromium 浏览器（用于 browser_use 技能）
RUN /root/.copaw/venv/bin/python -m playwright install chromium

2.7 健康检查和端口

# 健康检查
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
    CMD /healthcheck.sh || exit 1

# 暴露端口
EXPOSE 8080

# 数据持久化
VOLUME ["/root/.copaw/data", "/root/.copaw/logs", "/root/.copaw/config", "/root/.copaw/skills"]

# 启动命令
CMD ["copaw", "app", "--host", "0.0.0.0", "--port", "8080"]

三、Docker Compose 配置

3.1 完整配置

version: '3.8'

services:
  copaw:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: copaw
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./data:/root/.copaw/data
      - ./logs:/root/.copaw/logs
      - ./config:/root/.copaw/config
      - ./skills:/root/.copaw/skills
    environment:
      - COPAW_PORT=8080
      - COPAW_HOST=0.0.0.0
      - COPAW_ENV=production
      - TZ=Asia/Shanghai
    env_file:
      - .env
    networks:
      - copaw-network
    healthcheck:
      test: ["CMD", "test", "-f", "/root/.copaw/venv/bin/copaw"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s
    deploy:
      resources:
        limits:
          cpus: '4.0'
          memory: 4G

  # Redis 缓存（可选）
  redis:
    image: redis:7-alpine
    container_name: copaw-redis
    restart: unless-stopped
    command: redis-server --requirepass copaw123
    volumes:
      - ./redis/data:/data
    networks:
      - copaw-network

  # PostgreSQL 数据库（可选）
  postgres:
    image: postgres:15-alpine
    container_name: copaw-postgres
    restart: unless-stopped
    volumes:
      - ./postgres/data:/var/lib/postgresql/data
    environment:
      - POSTGRES_USER=copaw
      - POSTGRES_PASSWORD=copaw123
      - POSTGRES_DB=copaw
    networks:
      - copaw-network

networks:
  copaw-network:
    driver: bridge

四、环境配置

4.1 创建 .env 文件

# 复制示例文件
cp .env.example .env

# 编辑配置文件
vi .env

4.2 配置 AI 模型 API 密钥

# 至少配置一个 AI 模型的 API Key

# OpenAI（GPT-4、GPT-3.5）
OPENAI_API_KEY=sk-your-openai-api-key-here

# Anthropic（Claude）
ANTHROPIC_API_KEY=sk-ant-your-anthropic-key-here

# 阿里云（通义千问）
DASHSCOPE_API_KEY=sk-your-dashscope-key-here

# DeepSeek
DEEPSEEK_API_KEY=sk-your-deepseek-key-here

五、快速开始

5.1 一键部署

# 创建项目目录
mkdir -p ~/copaw-docker && cd ~/copaw-docker

# 复制配置文件（假设文件在 /root/.copaw）
cp /root/.copaw/Dockerfile .
cp /root/.copaw/docker-compose.yml .
cp /root/.copaw/.env.example .env
cp /root/.copaw/build.sh .

# 配置 API 密钥
vi .env

# 一键构建和启动
chmod +x build.sh
./build.sh all

5.2 分步部署

# 1. 准备环境
./build.sh prepare

# 2. 构建镜像
./build.sh build

# 3. 启动服务
./build.sh start

# 4. 初始化 CoPaw
./build.sh init

# 5. 查看日志
./build.sh logs

5.3 手动部署

# 构建镜像
docker-compose build

# 启动服务
docker-compose up -d

# 查看状态
docker-compose ps

# 初始化
docker exec -it copaw copaw init

# 查看日志
docker-compose logs -f copaw

六、使用指南

6.1 访问 CoPaw

# Web 控制台（如果支持）
http://localhost:8080

# 或者使用 CLI
docker exec -it copaw copaw app

6.2 常用命令

# 进入容器
docker exec -it copaw bash

# 查看 CoPaw 版本
docker exec copaw copaw --version

# 查看帮助
docker exec copaw copaw --help

# 重新初始化
docker exec -it copaw copaw init --force

6.3 技能配置

在 config/config.yaml 中配置启用的技能：

skills:
  enabled:
    - browser_use
    - execute_shell_command
    - read_file
    - write_file
    - edit_file
    - memory_search

七、数据持久化

7.1 目录结构

copaw-docker/
├── data/           # 数据文件（持久化）
│   ├── memory/     # 记忆数据
│   └── cache/      # 缓存数据
├── logs/           # 日志文件（持久化）
│   └── copaw.log
├── config/         # 配置文件（持久化）
│   └── config.yaml
├── skills/         # 自定义技能（持久化）
├── redis/          # Redis 数据（可选）
│   └── data/
└── postgres/       # PostgreSQL 数据（可选）
    └── data/

7.2 备份数据

# 创建备份脚本
cat > backup.sh << 'EOF'
#!/bin/bash
BACKUP_DIR=~/copaw-backup/$(date +%Y%m%d)
mkdir -p $BACKUP_DIR

# 备份 CoPaw 数据
cp -r data $BACKUP_DIR/
cp -r config $BACKUP_DIR/
cp -r logs $BACKUP_DIR/

# 备份数据库
docker exec copaw-postgres pg_dump -U copaw copaw > $BACKUP_DIR/db.sql

# 备份 Redis
docker exec copaw-redis redis-cli --pass copaw123 SAVE
cp redis/data/dump.rdb $BACKUP_DIR/ 2>/dev/null || true

echo "Backup completed: $BACKUP_DIR"
EOF

chmod +x backup.sh

# 执行备份
./backup.sh

7.3 定时备份

# 添加到 crontab（每天凌晨 2 点备份）
crontab -e

# 添加以下内容
0 2 * * * /path/to/backup.sh >> /var/log/copaw-backup.log 2>&1

八、生产环境部署

8.1 Nginx 反向代理

server {
    listen 80;
    server_name copaw.example.com;
    
    location / {
        proxy_pass http://localhost:8080;
        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;
        
        # WebSocket 支持
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

8.2 HTTPS 配置

# 使用 Certbot 申请 Let's Encrypt 证书
apt install certbot python3-certbot-nginx -y
certbot --nginx -d copaw.example.com

8.3 监控配置

# Prometheus 配置
global:
  scrape_interval: 15s

scrape_configs:
  - job_name: 'copaw'
    static_configs:
      - targets: ['copaw:8080']
    metrics_path: /metrics

九、故障排查

9.1 容器无法启动

# 查看详细日志
docker-compose logs copaw

# 检查配置
docker-compose config

# 测试构建
docker-compose build --no-cache

9.2 API 密钥问题

# 检查环境变量
docker exec copaw env | grep API_KEY

# 测试 API 连接
docker exec copaw curl -I https://api.openai.com/v1

9.3 内存不足

# 查看资源使用
docker stats copaw

# 调整限制（编辑 docker-compose.yml）
deploy:
  resources:
    limits:
      memory: 8G  # 增加到 8GB

9.4 Playwright 问题

# 重新安装浏览器
docker exec -it copaw python -m playwright install chromium

# 安装依赖
docker exec -it copaw playwright install-deps chromium

十、性能优化

10.1 镜像优化

# 使用多阶段构建减少镜像大小
FROM python:3.12-slim as builder
# ... 构建步骤 ...

FROM python:3.12-slim
COPY --from=builder /root/.copaw /root/.copaw
# ... 运行配置 ...

10.2 启动优化

# 使用 docker-compose 并行启动
docker-compose up -d --build --force-recreate

# 设置启动依赖
depends_on:
  redis:
    condition: service_healthy
  postgres:
    condition: service_healthy

总结

本文介绍了基于 CoPaw 官方安装脚本构建 Docker 镜像的完整流程：

Dockerfile 编写：基于 Python 3.12，使用 uv 包管理器
Docker Compose 配置：包含 Redis 和 PostgreSQL 的完整方案
环境配置：AI 模型 API 密钥、服务参数
快速部署：一键构建脚本和分步指南
数据持久化：Volume 挂载和定时备份
生产部署：Nginx 反向代理、HTTPS、监控
故障排查：常见问题解决方案
性能优化：镜像优化和启动优化

通过 Docker 部署 CoPaw，你可以：

✅ 环境隔离，不影响宿主机
✅ 快速部署，一键启动
✅ 易于备份，数据持久化
✅ 方便迁移，跨平台运行
✅ 资源可控，限制 CPU/内存

现在就开始部署你的 CoPaw AI 助手吧！🚀

相关链接：

CoPaw 官网：https://copaw.agentscope.io
GitHub：https://github.com/agentscope-ai/CoPaw
安装脚本：https://copaw.agentscope.io/install.sh

声明：本站所有文章，如无特殊说明或标注，均为本站原创发布。任何个人或组织，在未征得本站同意时，禁止复制、盗用、采集、发布本站内容到任何网站、书籍等各类媒体平台。如若本站内容侵犯了原著者的合法权益，可联系我们进行处理。

前言