Docker 使用指南

本指南将帮助您在 Docker 环境中使用 Trae，包括容器化部署和开发环境配置。

概述

Trae 支持在 Docker 容器中运行，这为开发和部署提供了一致的环境。您可以：

• 在容器中运行 Trae 服务
• 使用 Docker 进行开发环境隔离
• 部署 Trae 到容器化的生产环境

前置要求

• Docker Engine 20.10 或更高版本
• Docker Compose 2.0 或更高版本
• 至少 4GB 可用内存
• 至少 10GB 可用磁盘空间

快速开始

使用官方镜像

# 拉取最新的 Trae 镜像
docker pull trae/trae:latest

# 运行 Trae 容器
docker run -d \
  --name trae-server \
  -p 8080:8080 \
  -v trae-data:/data \
  trae/trae:latest

使用 Docker Compose

创建 docker-compose.yml 文件：

version: '3.8'

services:
  trae:
    image: trae/trae:latest
    container_name: trae-server
    ports:
      - "8080:8080"
    volumes:
      - trae-data:/data
      - ./config:/config
    environment:
      - TRAE_PORT=8080
      - TRAE_DATA_DIR=/data
      - TRAE_CONFIG_FILE=/config/trae.yml
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    container_name: trae-redis
    volumes:
      - redis-data:/data
    restart: unless-stopped

  postgres:
    image: postgres:15-alpine
    container_name: trae-postgres
    environment:
      - POSTGRES_DB=trae
      - POSTGRES_USER=trae
      - POSTGRES_PASSWORD=your-password
    volumes:
      - postgres-data:/var/lib/postgresql/data
    restart: unless-stopped

volumes:
  trae-data:
  redis-data:
  postgres-data:

启动服务：

docker-compose up -d

配置

环境变量

变量名	描述	默认值
TRAE_PORT	服务端口	8080
TRAE_DATA_DIR	数据目录	/data
TRAE_CONFIG_FILE	配置文件路径	/config/trae.yml
TRAE_LOG_LEVEL	日志级别	info
TRAE_DB_URL	数据库连接	sqlite:///data/trae.db
TRAE_REDIS_URL	Redis 连接	redis://localhost:6379

配置文件

创建 config/trae.yml：

server:
  port: 8080
  host: "0.0.0.0"

database:
  url: "postgresql://trae:your-password@postgres:5432/trae"

redis:
  url: "redis://redis:6379"

ai:
  providers:
    openai:
      api_key: "${OPENAI_API_KEY}"
    anthropic:
      api_key: "${ANTHROPIC_API_KEY}"

security:
  jwt_secret: "${JWT_SECRET}"
  cors_origins:
    - "http://localhost:3000"
    - "https://your-domain.com"

logging:
  level: "info"
  format: "json"

开发环境

本地开发

创建开发环境的 docker-compose.dev.yml：

version: '3.8'

services:
  trae-dev:
    build:
      context: .
      dockerfile: Dockerfile.dev
    container_name: trae-dev
    ports:
      - "8080:8080"
      - "9229:9229"  # 调试端口
    volumes:
      - .:/app
      - /app/node_modules
    environment:
      - NODE_ENV=development
      - TRAE_LOG_LEVEL=debug
    command: npm run dev
    restart: unless-stopped

  postgres-dev:
    image: postgres:15-alpine
    container_name: trae-postgres-dev
    environment:
      - POSTGRES_DB=trae_dev
      - POSTGRES_USER=trae
      - POSTGRES_PASSWORD=dev-password
    ports:
      - "5432:5432"
    volumes:
      - postgres-dev-data:/var/lib/postgresql/data

volumes:
  postgres-dev-data:

开发用 Dockerfile

创建 Dockerfile.dev：

FROM node:18-alpine

WORKDIR /app

# 安装依赖
COPY package*.json ./
RUN npm ci

# 复制源代码
COPY . .

# 暴露端口
EXPOSE 8080 9229

# 启动开发服务器
CMD ["npm", "run", "dev"]

生产部署

生产用 Dockerfile

FROM node:18-alpine AS builder

WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

COPY . .
RUN npm run build

FROM node:18-alpine AS runtime

RUN addgroup -g 1001 -S trae && \
    adduser -S trae -u 1001

WORKDIR /app

COPY --from=builder --chown=trae:trae /app/dist ./dist
COPY --from=builder --chown=trae:trae /app/node_modules ./node_modules
COPY --from=builder --chown=trae:trae /app/package.json ./

USER trae

EXPOSE 8080

HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD curl -f http://localhost:8080/health || exit 1

CMD ["node", "dist/server.js"]

生产环境配置

version: '3.8'

services:
  trae:
    image: trae/trae:latest
    container_name: trae-prod
    ports:
      - "8080:8080"
    volumes:
      - trae-data:/data
      - ./config:/config:ro
    environment:
      - NODE_ENV=production
      - TRAE_CONFIG_FILE=/config/trae.yml
    secrets:
      - jwt_secret
      - openai_api_key
    deploy:
      resources:
        limits:
          memory: 2G
          cpus: '1.0'
        reservations:
          memory: 1G
          cpus: '0.5'
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3

  nginx:
    image: nginx:alpine
    container_name: trae-nginx
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./ssl:/etc/ssl:ro
    depends_on:
      - trae
    restart: unless-stopped

secrets:
  jwt_secret:
    file: ./secrets/jwt_secret.txt
  openai_api_key:
    file: ./secrets/openai_api_key.txt

volumes:
  trae-data:

网络配置

Nginx 反向代理

创建 nginx.conf：

events {
    worker_connections 1024;
}

http {
    upstream trae {
        server trae:8080;
    }

    server {
        listen 80;
        server_name your-domain.com;
        return 301 https://$server_name$request_uri;
    }

    server {
        listen 443 ssl http2;
        server_name your-domain.com;

        ssl_certificate /etc/ssl/cert.pem;
        ssl_certificate_key /etc/ssl/key.pem;

        location / {
            proxy_pass http://trae;
            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;
        }

        location /ws {
            proxy_pass http://trae;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection "upgrade";
            proxy_set_header Host $host;
        }
    }
}

监控和日志

日志配置

services:
  trae:
    # ... 其他配置
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

  fluentd:
    image: fluent/fluentd:v1.16-debian-1
    container_name: trae-fluentd
    volumes:
      - ./fluentd.conf:/fluentd/etc/fluent.conf
      - /var/log:/var/log
    ports:
      - "24224:24224"

健康检查

# 检查容器状态
docker ps

# 查看容器日志
docker logs trae-server

# 检查健康状态
docker inspect --format='{{.State.Health.Status}}' trae-server

备份和恢复

数据备份

# 备份数据卷
docker run --rm \
  -v trae-data:/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/trae-backup-$(date +%Y%m%d).tar.gz -C /data .

# 备份数据库
docker exec trae-postgres pg_dump -U trae trae > backup-$(date +%Y%m%d).sql

数据恢复

# 恢复数据卷
docker run --rm \
  -v trae-data:/data \
  -v $(pwd):/backup \
  alpine tar xzf /backup/trae-backup-20240115.tar.gz -C /data

# 恢复数据库
docker exec -i trae-postgres psql -U trae trae < backup-20240115.sql

故障排除

常见问题

1. 容器启动失败

   # 检查日志
   docker logs trae-server
   
   # 检查配置
   docker exec trae-server cat /config/trae.yml

2. 端口冲突

   # 检查端口占用
   netstat -tulpn | grep 8080
   
   # 修改端口映射
   docker run -p 8081:8080 trae/trae:latest

3. 内存不足

   # 检查资源使用
   docker stats
   
   # 增加内存限制
   docker run --memory=4g trae/trae:latest

性能优化

1. 资源限制

   deploy:
     resources:
       limits:
         memory: 2G
         cpus: '1.0'

2. 卷挂载优化

   volumes:
     - type: bind
       source: ./data
       target: /data
       bind:
         propagation: cached

安全最佳实践

1. 使用非 root 用户
2. 限制容器权限
3. 定期更新镜像
4. 使用密钥管理
5. 网络隔离

相关资源

• Docker 官方文档
• Docker Compose 文档
• Trae 安装指南
• Trae 配置指南