ai-agent-book 精选快照（<2MB 代码与文档，来自 github.com/bojieli/ai-agent-book）

chapter4/DOCKER_DEPLOYMENT.md

@@ -0,0 +1,337 @@
+# Docker Deployment Guide for MCP Servers
+
+This guide explains how to deploy the three MCP servers (execution-tools, perception-tools, collaboration-tools) using Docker.
+
+## Overview
+
+All three MCP servers are containerized with Docker support, making them:
+- **Portable**: Run anywhere Docker is available
+- **Isolated**: Each server runs in its own environment
+- **Reproducible**: Consistent behavior across different machines
+- **Easy to deploy**: Simple setup with docker-compose
+
+## Prerequisites
+
+1. **Docker** (version 20.10 or later)
+2. **Docker Compose** (version 2.0 or later)
+3. **API Keys** for external services (OpenAI, Google, etc.)
+
+## Quick Start
+
+### 1. Set Up Environment Variables
+
+Copy the example environment file and configure your API keys:
+
+```bash
+cd /Users/boj/ai-agent-book/projects/week4
+cp .env.example .env
+```
+
+Edit `.env` and add your API keys:
+
+```env
+OPENAI_API_KEY=your-openai-api-key
+GOOGLE_API_KEY=your-google-key
+# ... other keys
+```
+
+### 2. Build and Run All Services
+
+Use the provided script:
+
+```bash
+./build_and_run.sh
+```
+
+Or manually:
+
+```bash
+# Build all images
+docker-compose build
+
+# Start all services
+docker-compose up -d
+
+# View logs
+docker-compose logs -f
+```
+
+### 3. Build Individual Services
+
+To build/run a single service:
+
+```bash
+# Build execution-tools only
+docker-compose build execution-tools
+
+# Run execution-tools only
+docker-compose up -d execution-tools
+```
+
+## Service Details
+
+### Execution Tools
+
+**Purpose**: Multi-language code execution with scientific computing support
+
+**Languages Supported**:
+- Python 3.11 (with NumPy, Pandas, Scikit-learn, etc.)
+- JavaScript/Node.js 20.x
+- TypeScript (with tsx/ts-node)
+- Go 1.21
+- Java 17 (OpenJDK)
+- C++ (GCC)
+- Rust
+- PHP
+- Bash
+
+**Volume Mounts**:
+- `execution-workspace:/workspace` - Code execution workspace
+
+**Key Environment Variables**:
+- `WORKSPACE_DIR`: Working directory for code execution
+- `AUTO_VERIFY_CODE`: Automatically verify code before execution
+- `AUTO_SUMMARIZE_COMPLEX_OUTPUT`: Summarize long outputs
+
+### Perception Tools
+
+**Purpose**: Document processing, web search, and data retrieval
+
+**Features**:
+- PDF/document processing
+- Web search (Google, Arxiv)
+- Data extraction and analysis
+- OCR support (Tesseract)
+
+**Volume Mounts**:
+- `perception-data:/data` - Processed document storage
+
+**Key Environment Variables**:
+- `DATA_DIR`: Data storage directory
+- `GOOGLE_API_KEY`: Google search API key
+- `GOOGLE_CSE_ID`: Custom Search Engine ID
+
+### Collaboration Tools
+
+**Purpose**: Browser automation, Excel processing, HITL interactions
+
+**Features**:
+- Headless browser automation (Chromium)
+- Excel file processing
+- Human-in-the-loop interactions
+- Chess game analysis
+- Timer and notification tools
+
+**Volume Mounts**:
+- `collaboration-workspace:/workspace` - Working directory
+
+**Key Environment Variables**:
+- `WORKSPACE_DIR`: Working directory
+- `DISPLAY`: X11 display (for headless browser)
+
+## Local Development
+
+For local development without Docker:
+
+### Execution Tools
+
+```bash
+cd execution-tools
+python3 -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+cp .env.example .env
+# Edit .env with your settings
+python server.py
+```
+
+### Perception Tools
+
+```bash
+cd perception-tools
+python3 -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+cp env.example .env
+# Edit .env with your settings
+python src/main.py
+```
+
+### Collaboration Tools
+
+```bash
+cd collaboration-tools
+python3 -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+cp env.example .env
+# Edit .env with your settings
+python src/main.py
+```
+
+## Testing Multi-Language Code Execution
+
+Once the execution-tools service is running, you can test different languages:
+
+### Python Example
+```python
+code = """
+import numpy as np
+import pandas as pd
+
+data = pd.DataFrame({'A': [1, 2, 3], 'B': [4, 5, 6]})
+print(data.describe())
+"""
+# Execute via MCP: code_interpreter(code=code, language="python")
+```
+
+### JavaScript Example
+```javascript
+code = """
+console.log('Hello from Node.js!');
+const numbers = [1, 2, 3, 4, 5];
+const sum = numbers.reduce((a, b) => a + b, 0);
+console.log('Sum:', sum);
+"""
+# Execute via MCP: code_interpreter(code=code, language="javascript")
+```
+
+### Go Example
+```go
+code = """
+package main
+import "fmt"
+
+func main() {
+    fmt.Println("Hello from Go!")
+    sum := 0
+    for i := 1; i <= 10; i++ {
+        sum += i
+    }
+    fmt.Printf("Sum: %d\\n", sum)
+}
+"""
+# Execute via MCP: code_interpreter(code=code, language="go")
+```
+
+## Docker Commands Reference
+
+```bash
+# Build all services
+docker-compose build
+
+# Start all services
+docker-compose up -d
+
+# Stop all services
+docker-compose down
+
+# View logs
+docker-compose logs -f [service-name]
+
+# Restart a service
+docker-compose restart [service-name]
+
+# View running containers
+docker-compose ps
+
+# Execute command in container
+docker-compose exec execution-tools bash
+
+# Remove all containers and volumes
+docker-compose down -v
+
+# Rebuild a service
+docker-compose up -d --build [service-name]
+```
+
+## Troubleshooting
+
+### Issue: Service won't start
+
+Check logs:
+```bash
+docker-compose logs [service-name]
+```
+
+### Issue: Permission denied
+
+Ensure volumes have correct permissions:
+```bash
+docker-compose down -v
+docker-compose up -d
+```
+
+### Issue: Out of memory
+
+Increase Docker memory limit in Docker Desktop settings or add to docker-compose.yml:
+```yaml
+services:
+  execution-tools:
+    mem_limit: 4g
+```
+
+### Issue: Python packages missing
+
+Rebuild the image:
+```bash
+docker-compose build --no-cache execution-tools
+```
+
+## Security Considerations
+
+1. **Never commit .env files** with real API keys
+2. **Use non-root users** in containers (already configured)
+3. **Limit resource usage** with Docker resource constraints
+4. **Keep images updated** regularly rebuild with latest security patches
+5. **Use secrets management** for production deployments (Docker Swarm secrets, Kubernetes secrets)
+
+## Production Deployment
+
+For production deployments, consider:
+
+1. **Orchestration**: Use Kubernetes or Docker Swarm
+2. **Secrets Management**: Use external secret stores (Vault, AWS Secrets Manager)
+3. **Monitoring**: Add Prometheus/Grafana for metrics
+4. **Logging**: Centralized logging with ELK or Loki
+5. **Resource Limits**: Set proper CPU/memory limits
+6. **Health Checks**: Already configured in docker-compose.yml
+7. **Auto-restart**: Already configured with `restart: unless-stopped`
+
+## Architecture Diagram
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                   MCP Client (Claude)                    │
+└────────────┬────────────┬────────────┬──────────────────┘
+             │            │            │
+             │ stdio      │ stdio      │ stdio
+             │            │            │
+   ┌─────────▼───────┐ ┌─▼──────────┐ ┌▼────────────────┐
+   │ execution-tools │ │ perception-│ │ collaboration-  │
+   │   Container     │ │   tools    │ │   tools         │
+   │                 │ │ Container  │ │   Container     │
+   │ • Python 3.11   │ │ • Doc Proc │ │ • Browser       │
+   │ • Node.js 20    │ │ • Search   │ │ • Excel         │
+   │ • Go 1.21       │ │ • OCR      │ │ • HITL          │
+   │ • Java 17       │ │ • APIs     │ │ • Timers        │
+   │ • C++/Rust/PHP  │ │            │ │                 │
+   └────────┬────────┘ └─┬──────────┘ └┬────────────────┘
+            │            │             │
+            ▼            ▼             ▼
+      /workspace      /data       /workspace
+       (volume)      (volume)      (volume)
+```
+
+## Additional Resources
+
+- [Docker Documentation](https://docs.docker.com/)
+- [Docker Compose Reference](https://docs.docker.com/compose/)
+- [MCP Protocol Specification](https://modelcontextprotocol.io/)
+
+## Support
+
+For issues or questions:
+1. Check the logs: `docker-compose logs -f`
+2. Review this documentation
+3. Check the individual README files in each service directory