docker 部署

.dockerignore

@@ -0,0 +1,59 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info/
+dist/
+build/
+
+# Virtual environments
+venv/
+.venv/
+env/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+.claude/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Misc
+.DS_Store
+.env
+*.log
+
+# Cache and output
+.cache/
+.trace/
+.trace_test/
+output/
+examples/**/output*/
+
+# Frontend
+node_modules/
+frontend/react-template/dist/
+frontend/react-template/node_modules/
+yarn.lock
+
+# Database
+*.db
+*.db-shm
+*.db-wal
+knowhub/milvus_data/
+
+# Git
+.git/
+.gitignore
+
+# Deploy
+deploy/
+DEPLOY.md

.env.example

@@ -0,0 +1,10 @@
+# Docker Compose 环境变量配置
+# 用于 content-finder 服务
+
+# LLM 配置（必填）
+OPEN_ROUTER_API_KEY=your-api-key-here
+
+# 模型配置（可选，有默认值）
+MODEL=anthropic/claude-sonnet-4.6
+TEMPERATURE=0.3
+MAX_ITERATIONS=30

DEPLOY.md

@@ -0,0 +1,305 @@
+# Docker 一键部署文档
+
+## 快速开始
+
+### 1. 配置环境变量
+
+```bash
+cp .env.example .env
+vim .env  # 填写 OPEN_ROUTER_API_KEY
+```
+
+`.env` 文件内容：
+```bash
+OPEN_ROUTER_API_KEY=your-api-key-here
+MODEL=anthropic/claude-sonnet-4.6
+TEMPERATURE=0.3
+MAX_ITERATIONS=30
+MAX_CONCURRENT_TASKS=3
+```
+
+### 2. 一键启动
+
+```bash
+docker-compose up -d
+```
+
+首次启动会自动构建镜像（需要几分钟），后续启动秒级完成。
+
+### 3. 查看状态
+
+```bash
+docker-compose ps
+```
+
+---
+
+## 服务访问
+
+| 服务 | 地址 | 说明 |
+|------|------|------|
+| 前端 | http://localhost:3000 | 可视化界面 |
+| API 服务 | http://localhost:8000 | 可视化 API |
+| Agent 服务 | http://localhost:8080 | 内容寻找 API |
+
+---
+
+## 常用命令
+
+### 启动服务
+
+```bash
+docker-compose up -d
+```
+
+### 停止服务
+
+```bash
+docker-compose down
+```
+
+### 重启服务
+
+```bash
+# 重启所有服务
+docker-compose restart
+
+# 重启指定服务
+docker-compose restart content-finder
+```
+
+### 查看日志
+
+```bash
+# 所有服务
+docker-compose logs -f
+
+# 指定服务
+docker-compose logs -f content-finder
+docker-compose logs -f api-server
+docker-compose logs -f frontend
+
+# 查看最近 100 行
+docker-compose logs --tail 100 content-finder
+```
+
+### 重新构建
+
+```bash
+# 代码更新后重新构建
+docker-compose build
+
+# 构建并启动
+docker-compose up -d --build
+```
+
+### 更新镜像
+
+```bash
+# 拉取最新基础镜像
+docker-compose pull
+
+# 重新构建
+docker-compose build --no-cache
+docker-compose up -d
+```
+
+---
+
+## 数据持久化
+
+`.trace` 数据存储在 `./data/traces` 目录，容器重启不会丢失。
+
+### 备份数据
+
+```bash
+tar -czf traces-backup-$(date +%Y%m%d).tar.gz ./data/traces
+```
+
+### 恢复数据
+
+```bash
+tar -xzf traces-backup-20260317.tar.gz
+```
+
+---
+
+## 生产环境部署
+
+### ALB 配置
+
+#### 监听器
+
+| 端口 | 协议 | 目标 | 说明 |
+|------|------|------|------|
+| 80 | HTTP | 宿主机:3000 | 前端（可重定向到 HTTPS） |
+| 443 | HTTPS | 宿主机:3000 | 前端（SSL 终止） |
+| 8000 | HTTP/HTTPS | 宿主机:8000 | API 服务 |
+
+**重要**：前端代码会访问 `window.location.hostname:8000`，所以 ALB 必须暴露 8000 端口。
+
+#### 健康检查
+
+| 服务 | 路径 | 端口 | 间隔 | 超时 |
+|------|------|------|------|------|
+| frontend | `/` | 3000 | 5s | 3s |
+| api-server | `/health` | 8000 | 5s | 3s |
+| content-finder | `/health` | 8080 | 5s | 3s |
+
+### 服务器准备
+
+```bash
+# 1. 安装 Docker 和 Docker Compose
+curl -fsSL https://get.docker.com | sh
+sudo usermod -aG docker $USER
+
+# 2. 克隆代码
+git clone <your-repo>
+cd Agent
+
+# 3. 配置环境变量
+cp .env.example .env
+vim .env
+
+# 4. 启动服务
+docker-compose up -d
+```
+
+---
+
+## 故障排查
+
+### 服务无法启动
+
+```bash
+# 查看日志
+docker-compose logs content-finder
+
+# 检查环境变量
+cat .env
+
+# 检查容器状态
+docker-compose ps
+```
+
+### 前端无法访问 API
+
+**问题**：前端访问 `yourdomain.com:8000` 失败
+
+**原因**：ALB 没有暴露 8000 端口
+
+**解决**：在 ALB 配置中添加 8000 端口监听器
+
+### 端口冲突
+
+```bash
+# 检查端口占用
+netstat -tlnp | grep 3000
+netstat -tlnp | grep 8000
+netstat -tlnp | grep 8080
+
+# 停止占用端口的进程
+sudo kill -9 <PID>
+```
+
+### 构建失败
+
+```bash
+# 清理缓存重新构建
+docker-compose build --no-cache
+
+# 查看构建日志
+docker-compose build --progress=plain
+```
+
+### 磁盘空间不足
+
+```bash
+# 清理未使用的镜像和容器
+docker system prune -a
+
+# 查看磁盘使用
+docker system df
+```
+
+---
+
+## 性能优化
+
+### 资源限制
+
+编辑 `docker-compose.yml` 添加资源限制：
+
+```yaml
+services:
+  content-finder:
+    deploy:
+      resources:
+        limits:
+          cpus: '2'
+          memory: 4G
+        reservations:
+          cpus: '1'
+          memory: 2G
+```
+
+### 日志轮转
+
+```bash
+# 限制日志大小
+docker-compose logs --tail 1000 > logs.txt
+docker-compose logs --since 1h > recent-logs.txt
+```
+
+---
+
+## 监控
+
+### 查看资源使用
+
+```bash
+docker stats agent-content-finder agent-api-server agent-frontend
+```
+
+### 健康检查
+
+```bash
+# content-finder
+curl http://localhost:8080/health
+
+# api-server
+curl http://localhost:8000/health
+
+# frontend
+curl http://localhost:3000
+```
+
+---
+
+## 架构说明
+
+```
+[用户浏览器]
+    ↓
+[ALB - 80/443/8000]
+    ↓
+[宿主机]
+    ├─ :3000 → agent-frontend (nginx)
+    ├─ :8000 → agent-api-server (FastAPI)
+    └─ :8080 → agent-content-finder (FastAPI)
+         ↓
+    [./data/traces] (持久化存储)
+```
+
+### 服务说明
+
+- **frontend**：React 应用，nginx 托管静态文件
+- **api-server**：可视化 API，读取 `.trace` 数据
+- **content-finder**：内容寻找 Agent，写入 `.trace` 数据
+
+### 数据流
+
+1. 用户访问前端 (port 3000)
+2. 前端调用 API (port 8000)
+3. API 读取 `.trace` 数据
+4. content-finder 执行任务，写入 `.trace`

Dockerfile.api-server

@@ -0,0 +1,28 @@
+FROM registry.cn-hangzhou.aliyuncs.com/stuuudy/python:3.13-slim
+
+WORKDIR /app
+
+# 安装系统依赖
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    gcc \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# 复制依赖文件
+COPY requirements.txt .
+
+# 安装 Python 依赖
+RUN pip install --no-cache-dir -r requirements.txt
+
+# 复制项目代码
+COPY agent/ ./agent/
+COPY api_server.py .
+
+# 创建 .trace 目录
+RUN mkdir -p /app/.trace
+
+# 暴露端口
+EXPOSE 8000
+
+# 启动命令（生产模式，不使用 reload）
+CMD ["uvicorn", "api_server:app", "--host", "0.0.0.0", "--port", "8000"]

Dockerfile.content-finder

@@ -0,0 +1,28 @@
+FROM registry.cn-hangzhou.aliyuncs.com/stuuudy/python:3.13-slim
+
+WORKDIR /app
+
+# 安装系统依赖
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    gcc \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# 复制依赖文件
+COPY requirements.txt .
+
+# 安装 Python 依赖
+RUN pip install --no-cache-dir -r requirements.txt
+
+# 复制项目代码
+COPY agent/ ./agent/
+COPY examples/content_finder/ ./examples/content_finder/
+
+# 设置工作目录
+WORKDIR /app/examples/content_finder
+
+# 暴露端口
+EXPOSE 8080
+
+# 启动命令
+CMD ["python", "server.py"]

Dockerfile.frontend

@@ -0,0 +1,34 @@
+# Stage 1: 构建前端
+FROM node:20-alpine AS builder
+
+WORKDIR /app
+
+# 复制依赖文件
+COPY frontend/react-template/package.json frontend/react-template/yarn.lock* ./
+
+# 安装依赖
+RUN yarn install --frozen-lockfile
+
+# 复制源码
+COPY frontend/react-template/ .
+
+# 构建生产版本
+RUN yarn build
+
+# Stage 2: nginx 托管
+FROM nginx:alpine
+
+# 安装 curl（用于健康检查）
+RUN apk add --no-cache curl
+
+# 复制 nginx 配置
+COPY nginx.conf /etc/nginx/conf.d/default.conf
+
+# 复制构建产物
+COPY --from=builder /app/dist /usr/share/nginx/html
+
+# 暴露端口
+EXPOSE 3000
+
+# 启动 nginx
+CMD ["nginx", "-g", "daemon off;"]

docker-compose.yml

@@ -0,0 +1,62 @@
+version: '3.8'
+
+services:
+  # 内容寻找 Agent 服务
+  content-finder:
+    build:
+      context: .
+      dockerfile: Dockerfile.content-finder
+    container_name: agent-content-finder
+    restart: unless-stopped
+    ports:
+      - "8080:8080"
+    volumes:
+      - ./data/traces:/app/.trace
+    environment:
+      - OPEN_ROUTER_API_KEY=${OPEN_ROUTER_API_KEY}
+      - MODEL=${MODEL:-anthropic/claude-sonnet-4.6}
+      - TEMPERATURE=${TEMPERATURE:-0.3}
+      - MAX_ITERATIONS=${MAX_ITERATIONS:-30}
+      - TRACE_DIR=/app/.trace
+      - PORT=8080
+      - MAX_CONCURRENT_TASKS=${MAX_CONCURRENT_TASKS:-3}
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 40s
+
+  # 可视化 API 服务
+  api-server:
+    build:
+      context: .
+      dockerfile: Dockerfile.api-server
+    container_name: agent-api-server
+    restart: unless-stopped
+    ports:
+      - "8000:8000"
+    volumes:
+      - ./data/traces:/app/.trace
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 40s
+
+  # 前端服务
+  frontend:
+    build:
+      context: .
+      dockerfile: Dockerfile.frontend
+    container_name: agent-frontend
+    restart: unless-stopped
+    ports:
+      - "3000:3000"
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:3000"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 10s

nginx.conf

@@ -0,0 +1,18 @@
+server {
+    listen 3000;
+    server_name _;
+
+    root /usr/share/nginx/html;
+    index index.html;
+
+    # 前端静态文件
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+
+    # gzip 压缩
+    gzip on;
+    gzip_vary on;
+    gzip_min_length 1024;
+    gzip_types text/plain text/css text/xml text/javascript application/x-javascript application/xml+rss application/json application/javascript;
+}