Merge 24b5045a3e into 8e6d49df74

2026-09-10 22:41:02 +00:00 · 2026-04-10 11:40:15 +08:00 · 2026-04-10 11:40:15 +08:00 · 65f8f2d274
commit 65f8f2d274
parent 8e6d49df74 24b5045a3e
9 changed files with 833 additions and 3 deletions
--- a/.dockerignore
+++ b/.dockerignore
@ -0,0 +1,18 @@
+.git
+.github
+node_modules/
+frontend/node_modules/
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+env/
+venv/
+.venv/
+.env
+.openspace/
+frontend/dist/
+showcase/
+gdpval_bench/
+assets/
--- a/.env.example
+++ b/.env.example
@ -0,0 +1,50 @@
+# OpenSpace Docker Environment Configuration
+# Copy this file to .env and customize your settings
+
+# ==================== Required ====================
+# Generate a secure random key for your OpenSpace instance
+# You can generate one with: openssl rand -base64 32
+OPENSPACE_API_KEY=your_openpspace_api_key_here
+
+# ==================== LLM Providers ====================
+# Choose ONE provider configuration below
+
+# Option 1: OpenAI (GPT-4, GPT-3.5, etc.)
+# OPENAI_API_KEY=sk-...
+
+# Option 2: Anthropic (Claude)
+# ANTHROPIC_API_KEY=sk-ant-...
+
+# Option 3: StepFun (Step models via OpenRouter)
+# Note: Using OpenRouter as the API gateway
+OPENSPACE_MODEL=stepfun/step-3.5-flash:free
+OPENSPACE_LLM_API_KEY=sk-or-v1-...
+OPENSPACE_LLM_API_BASE=https://openrouter.ai/api/v1
+
+# Option 4: Custom provider (Local LLM, Together, etc.)
+# OPENSPACE_LLM_API_KEY=your_api_key
+# OPENSPACE_LLM_API_BASE=https://your-llm-provider.com/v1
+# OPENSPACE_MODEL=your-model-name
+
+# ==================== Optional ====================
+# Default model to use when not specified in queries
+# OPENSPACE_MODEL=claude-3-7-sonnet-latest
+
+# Enable debug logging (set to 1)
+# OPENSPACE_DEBUG=0
+
+# ==================== Docker Compose Configuration ====================
+# Override default host port (default: 9001)
+# HOST_PORT=9001
+
+# Volume type: "named" (Docker-managed) or "bind" (host directory)
+# VOLUME_TYPE=named
+
+# When VOLUME_TYPE=named, these named volumes are used:
+# VOLUME_DATA=openspace-data
+# VOLUME_SKILLS=openspace-skills
+
+# When VOLUME_TYPE=bind, create local directories:
+# (not set via env, edit docker-compose.yml directly)
+#   - ./data:/app/.openspace
+#   - ./skills:/app/skills
--- a/DOCKER.md
+++ b/DOCKER.md
@ -0,0 +1,283 @@
+# Docker Deployment for OpenSpace
+
+This guide provides instructions on how to run OpenSpace in a Docker container. Containerization ensures a consistent environment, making it easy to run the dashboard and backend API without dealing with local Python and Node.js dependencies.
+
+## Prerequisites
+
+- [Docker](https://docs.docker.com/get-docker/) (20.10+)
+- [Docker Compose](https://docs.docker.com/compose/install/) (v2.0+)
+
+## Quick Start (Docker Compose)
+
+The easiest way to get OpenSpace running is using `docker-compose`.
+
+### 1. Clone the Repository
+
+```bash
+git clone https://github.com/HKUDS/OpenSpace.git
+cd OpenSpace
+git checkout feat/docker-deployment
+```
+
+### 2. Configure Environment Variables
+
+```bash
+# Copy the example environment file
+cp .env.example .env
+
+# Edit .env with your configuration
+# Required at minimum:
+#   OPENSPACE_API_KEY=$(openssl rand -base64 32)
+#
+# Choose and configure ONE LLM provider:
+#   - OpenAI + OPENAI_API_KEY
+#   - Anthropic + ANTHROPIC_API_KEY
+#   - OpenRouter + OPENSPACE_LLM_API_KEY + OPENSPACE_LLM_API_BASE + OPENSPACE_MODEL
+```
+
+**Environment Variables Reference:**
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `OPENSPACE_API_KEY` | **Yes** | Secret API key for this OpenSpace instance. Generate with `openssl rand -base64 32` |
+| `OPENAI_API_KEY` | No | OpenAI API key (sk-...) |
+| `ANTHROPIC_API_KEY` | No | Anthropic API key (sk-ant-...) |
+| `OPENSPACE_MODEL` | No | Default model name (e.g., `claude-3-7-sonnet-latest`, `stepfun/step-3.5-flash:free`) |
+| `OPENSPACE_LLM_API_KEY` | No | API key for custom LLM provider |
+| `OPENSPACE_LLM_API_BASE` | No | Base URL for custom LLM provider (e.g., `https://openrouter.ai/api/v1`) |
+| `OPENSPACE_DEBUG` | No | Set to `1` to enable debug logging |
+| `HOST_PORT` | No | Host port to expose (default: `9001`) |
+| `VOLUME_TYPE` | No | `named` (default) or `bind` for local directories |
+
+### 3. Build and Run
+
+```bash
+# Standard docker-compose (uses docker-compose.yml)
+docker compose up -d --build
+
+# For production with stricter resource limits:
+# docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d --build
+
+# To stop:
+docker compose down
+
+# To view logs:
+docker compose logs -f openspace
+
+# To check health status:
+docker compose ps
+```
+
+### 4. Access the Dashboard
+
+Open your browser and navigate to:
+
+- **Dashboard:** http://localhost:${HOST_PORT:-9001}
+- Health endpoint: http://localhost:${HOST_PORT:-9001}/health
+
+The frontend and backend are served seamlessly from the same container.
+
+---
+
+## CLI Usage
+
+You can use the container to execute OpenSpace CLI commands.
+
+### Run a Query
+
+```bash
+docker exec -it openspace openspace --model "anthropic/claude-sonnet-4.5" --query "Analyze the local skills"
+```
+
+### Download/Upload Skills
+
+```bash
+docker exec -it openspace openspace-download-skill <skill_id>
+docker exec -it openspace openspace-upload-skill /app/skills/my-skill
+```
+
+### Enter Container Shell
+
+```bash
+docker exec -it openspace bash
+```
+
+---
+
+## Volume & Data Management
+
+### Volume Types
+
+1. **Named volumes** (default) - Managed by Docker, good for simple deployments
+   - `openspace-data`: Contains SQLite database (`openspace.db`) and skill history
+   - `openspace-skills`: Persists downloaded and custom skills
+
+2. **Bind mounts** - Direct host directory access, better for development
+   Edit `docker-compose.yml`:
+   ```yaml
+   volumes:
+     - ./data:/app/.openspace
+     - ./skills:/app/skills
+   ```
+
+### Backup & Restore
+
+**Backup:**
+```bash
+# Named volumes
+docker run --rm -v openspace-data:/data -v $(pwd):/backup alpine tar czf /backup/openspace-data-$(date +%Y%m%d).tar.gz -C /data .
+
+# Bind mounts (just copy the directories)
+cp -r data skills backup/
+```
+
+**Restore:**
+```bash
+# Named volumes
+docker run --rm -v openspace-data:/data -v $(pwd):/backup alpine sh -c "rm -rf /data/* && tar xzf /backup/openspace-data-YYYYMMDD.tar.gz -C /data"
+
+# Bind mounts
+cp -r backup/data backup/skills ./
+```
+
+---
+
+## Monitoring
+
+### Health Check
+
+OpenSpace container includes a health check that pings `/health` endpoint every 30 seconds. Check status:
+
+```bash
+docker compose ps
+# Look for "healthy" in the STATUS column
+```
+
+### Prometheus Metrics
+
+If you have a Prometheus instance, you can scrape metrics from OpenSpace. Add to your `docker-compose.yml`:
+
+```yaml
+services:
+  openspace:
+    # Add this label for service discovery
+    labels:
+      - "prometheus-job=openspace"
+```
+
+Then configure Prometheus to scrape `openspace:7788/metrics` (if endpoint is available).
+
+### Logs
+
+Logs are configured with rotation (10MB max, 3 files by default). View logs:
+
+```bash
+docker compose logs -f openspace
+# Or with timestamps
+docker compose logs -f --timestamp openspace
+```
+
+For centralized logging, consider using Loki/Promtail stack (not included by default).
+
+---
+
+## Troubleshooting
+
+### Container fails to start
+
+Check logs:
+```bash
+docker compose logs openspace
+```
+
+Common issues:
+- **Missing OPENSPACE_API_KEY**: Set it in `.env` file
+- **Port already in use**: Change `HOST_PORT` in `.env` or stop the conflicting service
+- **Insufficient memory**: Increase Docker memory limit (Settings → Resources)
+
+### Health check failing
+
+The health check endpoint `/health` might not be available in older versions. If using a development build, you may need to disable the health check by removing it from `docker-compose.yml`.
+
+### Permission denied on volumes
+
+If using bind mounts, ensure the host directories are readable/writable by the container user (UID 1000). Fix with:
+```bash
+sudo chown -R 1000:1000 data skills
+```
+
+---
+
+## Production Deployment Checklist
+
+- [ ] Generate a strong `OPENSPACE_API_KEY` and keep it secret
+- [ ] Configure SSL/TLS termination (use reverse proxy like nginx or Traefik)
+- [ ] Set appropriate resource limits (memory: 2-4G, CPU: 2-4 cores)
+- [ ] Enable log rotation and set up log aggregation
+- [ ] Configure regular backups of `openspace-data` volume
+- [ ] Set up monitoring (Prometheus + Grafana)
+- [ ] Use `docker-compose.prod.yml` for additional production settings
+- [ ] Restrict access to the API and dashboard via firewall/VPC
+- [ ] Keep Docker and base images updated regularly
+
+---
+
+## Advanced Configuration
+
+### Custom Network
+
+To integrate with other services on a custom network:
+
+```yaml
+networks:
+  app-network:
+    driver: bridge
+
+services:
+  openspace:
+    networks:
+      - app-network
+```
+
+### Multi-stage Deployment (with separate frontend/backend)
+
+For large-scale deployments, you might split frontend and backend services. See `docker-compose.multi.yml` (if available).
+
+### Environment-Specific Configs
+
+Use multiple compose files:
+
+```bash
+# Development (with hot-reload, less resource limits)
+docker compose -f docker-compose.yml -f docker-compose.override.yml up -d
+
+# Production (strict limits, optimized)
+docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
+```
+
+---
+
+## Security Notes
+
+- The Dockerfile creates and uses a non-root user `appuser` (UID 1000)
+- `OPENSPACE_API_KEY` should be treated as a secret; rotate periodically
+- Network access is limited to what the container needs; avoid `--network host`
+- Keep the host and Docker daemon updated to prevent vulnerabilities
+
+---
+
+## Contributing
+
+Found an issue or want to improve the Docker deployment? PRs welcome!
+
+Please update:
+- `docker-compose.yml` (core config)
+- `Dockerfile` (build instructions)
+- `DOCKER.md` (this documentation)
+- Add/maintain `.env.example`
+
+---
+
+## License
+
+MIT
--- a/65
+++ b/65
@ -0,0 +1,65 @@
+# Stage 1: Build the frontend
+FROM node:20-slim AS frontend-builder
+WORKDIR /app/frontend
+
+# Copy package files and install dependencies (cached layer)
+COPY frontend/package.json frontend/package-lock.json* ./
+RUN npm ci --only=production
+
+# Copy source and build
+COPY frontend/ ./
+RUN npm run build
+
+# Stage 2: Build the backend
+FROM python:3.12-slim
+
+# Create a non-root user for security
+RUN groupadd -r appuser && useradd -r -g appuser appuser
+
+WORKDIR /app
+
+# Install system dependencies required for python packages
+# Separate apt commands to leverage cache and clean up in same layer
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    gcc \
+    python3-dev \
+    libx11-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy backend source
+COPY --chown=appuser:appuser . /app/
+
+# Switch to non-root user for pip install (when possible)
+# Some packages may need system deps, but we installed them as root above
+USER appuser
+
+# Install Python package with minimal dependencies (linux extras require additional system deps)
+# Use --no-cache-dir to reduce image size
+RUN pip install --no-cache-dir -e .
+
+# Copy built frontend from Stage 1 (needs root to change ownership)
+USER root
+COPY --from=frontend-builder --chown=appuser:appuser /app/frontend/dist /app/frontend/dist
+
+# Switch back to non-root user
+USER appuser
+
+# Expose the dashboard port
+EXPOSE 7788
+
+# Set environment variables
+ENV HOST=0.0.0.0
+ENV PORT=7788
+ENV OPENSPACE_WORKSPACE=/app
+ENV PYTHONUNBUFFERED=1
+
+# Create necessary directories with proper permissions
+RUN mkdir -p /app/.openspace /app/skills && \
+    chmod 700 /app/.openspace /app/skills
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
+  CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:7788/health', timeout=5)" || exit 1
+
+# Run the dashboard server by default
+CMD ["openspace-dashboard", "--host", "0.0.0.0", "--port", "7788"]
--- a/README.md
+++ b/README.md
@ -139,6 +139,7 @@ On 50 professional tasks (**📈 [GDPVal Economic Benchmark](#-benchmark-gdpval)
  - [🤖 Path A: For Your Agent](#-path-a-for-your-agent)
  - [👤 Path B: As Your Co-Worker](#-path-b-as-your-co-worker)
  - [📊 Local Dashboard](#-local-dashboard)
+- [🐳 Docker Deployment](#-docker-deployment)
 - [📈 Benchmark: GDPVal](#-benchmark-gdpval)
 - [📊 Showcase: My Daily Monitor](#-showcase-my-daily-monitor)
 - [🏗️ Framework](#️-framework)
@ -310,6 +311,117 @@ npm run dev

 ---

+### 🐳 Docker Deployment
+
+To deploy OpenSpace without worrying about local Python and Node.js dependencies, you can use Docker containerization. We provide a `docker-compose.yml` for an easy, single-command setup with production-grade features.
+
+#### Quick Deploy (Development)
+
+This is the simplest way to get started:
+
+```bash
+# Clone the repository
+git clone https://github.com/HKUDS/OpenSpace.git
+cd OpenSpace
+
+# Configure environment variables
+cp .env.example .env
+# Edit .env to add your LLM API keys
+
+# Start containers
+docker-compose up -d --build
+
+# Verify status
+docker-compose ps
+```
+
+Once started, access:
+- **Dashboard**: http://localhost:7788
+- **API Service**: http://localhost:7777
+
+#### Production Deployment
+
+For production, use `docker-compose.prod.yml` overlay:
+
+```bash
+docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d --build
+docker-compose logs -f
+docker stats
+```
+
+Production features:
+- ✅ **Resource limits**: 4 CPU cores, 4GB memory
+- ✅ **Log management**: 50MB per file, 5 rotations
+- ✅ **Health checks**: Automatic container health detection
+- ✅ **Data persistence**: Named volumes or bind mounts
+
+#### Docker Configuration Details
+
+**🔒 Security:**
+- Non-root user `appuser` runs the container
+- Minimal image layers for reduced attack surface
+
+**📁 Data Volumes:**
+
+```yaml
+volumes:
+  - .openspace:/app/.openspace    # Skill database and embedding cache
+  - logs:/app/logs                # Log persistence
+```
+
+**🔌 Ports & Services:**
+
+| Service | Port | Description |
+|---------|------|-------------|
+| `openspace` (Dashboard) | 7788 | Web UI and API |
+| `openspace-cli` | - | CLI tool |
+
+#### Environment Variables
+
+See `.env.example` for all options. Key settings:
+
+```bash
+# Required
+OPENAI_API_KEY=sk-xxx
+OPENSPACE_MODEL=gpt-4o
+
+# Docker tuning
+HOST_PORT=7788                    # Frontend port
+OPENSPACE_WORKSPACE=/app          # Workspace inside container
+OPENSPACE_LOG_LEVEL=INFO          # Log level
+
+# Optional (cloud features)
+OPENSPACE_API_KEY=sk-xxx
+```
+
+#### Troubleshooting
+
+```bash
+# View logs
+docker-compose logs openspace
+
+# Check port conflicts
+docker-compose port openspace 7788
+
+# Enter container
+docker-compose exec openspace bash
+
+# Monitor resources
+docker stats openspace
+```
+
+- **Port conflicts:** Select unused port via `HOST_PORT` in `.env`. Run `docker ps` to see used ports.
+- **Backup/restore, custom networks, monitoring:** See **[DOCKER.md](./DOCKER.md)** for complete guide.
+- **Full configuration:** See **[openspace/config/README.md](./openspace/config/README.md)**
+- **Custom skills:** See **[openspace/skills/README.md](./openspace/skills/README.md)**
+# Start the container
+docker-compose up -d --build
+```
+
+The OpenSpace Dashboard is now available at [http://localhost:7788](http://localhost:7788).
+
+For detailed CLI and volume configurations, check out the [Docker Deployment Guide (DOCKER.md)](./DOCKER.md).
+
 ## 📈 Benchmark: GDPVal

 We evaluate OpenSpace on [GDPVal](https://huggingface.co/datasets/openai/gdpval) — 220 real-world professional tasks spanning 44 occupations — using the [ClawWork](https://github.com/HKUDS/ClawWork) evaluation protocol with identical productivity tools and LLM-based scoring. Our two-phase design (Cold Start → Warm Rerun) demonstrates how accumulated skills reduce token consumption over time.
--- a/README_CN.md
+++ b/README_CN.md
@ -139,6 +139,7 @@ Skill 能够自动学习并持续提升
  - [🤖 路径 A：为你的 Agent 接入](#-路径-a为你的-agent-接入)
  - [👤 路径 B：作为你的 AI 协作者](#-路径-b作为你的-ai-协作者)
  - [📊 本地仪表盘](#-本地仪表盘)
+- [🐳 Docker 容器化部署](#-docker-部署)
 - [📈 基准测试：GDPVal](#-基准测试gdpval)
 - [📊 案例展示：My Daily Monitor](#-案例展示my-daily-monitor)
 - [🏗️ 框架](#️-框架)
@ -310,11 +311,200 @@ npm run dev

 ---

-## 📈 基准测试：GDPVal
+### 🐳 Docker 容器化部署

-我们在 [GDPVal](https://huggingface.co/datasets/openai/gdpval) 上评估 OpenSpace——该数据集包含 220 项真实世界的专业任务，涵盖 44 个职业——采用 [ClawWork](https://github.com/HKUDS/ClawWork) 评测协议，使用相同的生产力工具和基于 LLM 的评分方式。我们的两阶段设计（Cold Start → Warm Rerun）展示了积累的 Skill 如何随时间降低 Token 消耗。
+为了避免配置本地 Python 和 Node.js 环境，你可以使用 Docker 容器化运行 OpenSpace。我们提供了完整的 docker-compose 配置，包含生产级监控、日志轮转、资源限制和健康检查。

-公平基准：OpenSpace 使用 Qwen 3.5-Plus 作为骨干 LLM——与 ClawWork 基线 Agent 完全相同——确保性能差异纯粹来源于 Skill 进化，而非模型能力差异。
+#### 快速部署（开发环境）
+
+这是最简单的启动方式，适合开发和快速测试：
+
+```bash
+# 1. 克隆仓库
+git clone https://github.com/HKUDS/OpenSpace.git
+cd OpenSpace
+
+# 2. 配置环境变量
+cp .env.example .env
+# 编辑 .env，填入你的 LLM API 密钥
+
+# 3. 启动容器
+docker-compose up -d --build
+
+# 4. 验证状态
+docker-compose ps
+```
+
+启动成功后，访问：
+- **Dashboard**: http://localhost:7788
+- **API 服务**: http://localhost:7777
+
+#### 生产部署
+
+生产环境建议使用 `docker-compose.prod.yml` 覆盖配置：
+
+```bash
+# 使用生产配置启动
+docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d --build
+
+# 查看日志（实时）
+docker-compose logs -f
+
+# 查看资源使用
+docker stats
+```
+
+生产配置特点：
+- ✅ **资源限制严格**：CPU 限制 4 核，内存限制 4G
+- ✅ **日志管理**：50MB 每文件，保留 5 个轮转文件
+- ✅ **健康检查**：自动检测容器健康状况
+- ✅ **数据持久化**：使用 Docker named volumes 或 bind mounts
+
+#### Docker 配置详解
+
+我们的 Docker 配置基于最佳实践，包含以下关键特性：
+
+**🔒 安全性增强：**
+- 非 root 用户 `appuser` 运行容器
+- 应用与系统目录分离
+- 最小化镜像层，减少攻击面
+
+**💡 资源管理：**
+- CPU 和内存限制（可配置）
+- 健康检查端点 `/health`
+- 合理的重启策略（on-failure）
+
+**📊 日志管理：**
+- JSON 格式日志，便于日志收集系统解析
+- 日志轮转配置，防止磁盘写满
+- 支持 stdout/stderr 分离
+
+**📁 数据卷：**
+
+```yaml
+volumes:
+  - .openspace:/app/.openspace    # 技能数据库和 embedding 缓存
+  - logs:/app/logs                # 日志持久化
+  - ./data:/app/data              # 可选：自定义数据目录（bind mount）
+```
+
+**🔌 服务与端口：**
+
+| 服务 | 端口 | 说明 |
+|------|------|------|
+| `openspace` (Dashboard) | 7788 | Web UI 和 API 服务 |
+| `openspace-cli` | - | CLI 命令行工具 |
+
+#### 环境变量配置（.env）
+
+所有配置项说明请参考 `.env.example`：
+
+```bash
+# --- 必填项 ---
+OPENAI_API_KEY=sk-xxx              # 或使用其他 LLM 提供商
+OPENSPACE_MODEL=gpt-4o             # 选择的模型
+# 或使用通用 litellm 格式：OPENSPACE_MODEL=anthropic/claude-3-7-sonnet
+
+# --- Docker 调优（可选）---
+HOST_PORT=7788                     # 前端访问端口，默认 7788
+OPENSPACE_WORKSPACE=/app          # 工作区路径（Docker 内）
+OPENSPACE_LOG_LEVEL=INFO          # 日志级别：DEBUG/INFO/WARNING
+
+# --- 云端功能（可选）---
+OPENSPACE_API_KEY=sk-xxx           # 用于云端技能社区
+```
+
+#### 端口管理
+
+为避免端口冲突，你可以：
+1. 在 `.env` 中修改 `HOST_PORT` 环境变量
+2. 或在 `docker-compose.override.yml` 中覆盖服务配置
+3. 使用 `docker-compose port` 查看实际映射的端口
+
+> ⚠️ **注意**：确保所选端口未被其他容器占用。运行 `docker ps` 查看已使用的端口。
+
+#### 自定义 Docker 网络（推荐生产使用）
+
+为提升安全性和隔离性，建议创建自定义网络：
+
+```bash
+# 创建 bridge 网络
+docker network create openspace-network
+
+# 编辑 docker-compose.yml，在每个服务中添加：
+# networks:
+#   - openspace-network
+#
+# networks:
+#   openspace-network:
+#     driver: bridge
+```
+
+#### 数据持久化与备份
+
+我们的配置使用 Docker volumes 自动持久化数据。备份方法：
+
+```bash
+# 备份技能数据库
+docker run --rm -v openspace_openspace_data:/data -v $(pwd):/backup \
+  alpine tar czf /backup/openspace-backup-$(date +%Y%m%d).tar.gz -C /data .
+
+# 恢复技能数据库
+docker run --rm -v openspace_openspace_data:/data -v $(pwd):/backup \
+  alpine sh -c "cd /data && tar xzf /backup/openspace-backup-*.tar.gz"
+```
+
+#### 监控集成
+
+默认配置已包含 Prometheus 监控标签。你可以：
+1. 确保 `PROMETHEUS_JOB=openspace` 环境变量已设置
+2. 将以下 job 配置添加到你的 `prometheus.yml`：
+
+```yaml
+scrape_configs:
+  - job_name: 'openspace'
+    static_configs:
+      - targets: ['openspace:7788']  # 使用 Docker 内部服务名
+```
+
+#### 故障排查
+
+**容器无法启动：**
+```bash
+# 查看容器日志
+docker-compose logs openspace
+
+# 检查端口冲突
+docker-compose port openspace 7788
+
+# 进入容器调试
+docker-compose exec openspace bash
+```
+
+**API 密钥问题：**
+```bash
+# 验证环境变量
+docker-compose exec openspace env | grep -i openai
+# 或验证 LLM 配置
+docker-compose exec openspace python -c "from openspace.llm import get_llm; print(get_llm())"
+```
+
+**性能问题：**
+```bash
+# 查看资源使用
+docker stats openspace
+
+# 检查数据库大小
+docker-compose exec openspace du -sh /app/.openspace/
+```
+
+**端口冲突：** 在 `.env` 中使用 `HOST_PORT` 指定未使用的端口。运行 `docker ps` 查看已占用端口。
+
+**完整备份/恢复、自定义网络、监控集成等详细信息**，请参阅 **[DOCKER.md](./DOCKER.md)**。
+
+**其他文档：**
+- **[环境变量参考](openspace/config/README.md)** — 所有配置选项
+- **[技能系统指南](openspace/skills/README.md)** — 自定义技能公平基准：OpenSpace 使用 Qwen 3.5-Plus 作为骨干 LLM——与 ClawWork 基线 Agent 完全相同——确保性能差异纯粹来源于 Skill 进化，而非模型能力差异。

 真实经济价值：任务涵盖构建工资计算器、准备纳税申报表、起草法律备忘录等——这些都是产生真实 GDP 的专业工作，同时从质量和成本效率两个维度进行评估。

--- a/docker-compose.override.yml
+++ b/docker-compose.override.yml
@ -0,0 +1,22 @@
+# Development overrides for OpenSpace
+# Automatically used by docker-compose up in development
+
+services:
+  openspace:
+    # Mount source code for live editing (requires rebuild on changes)
+    # volumes:
+    #   - ./openspace:/app/openspace:ro
+    #   - ./frontend:/app/frontend:ro
+    # Development-friendly resource limits
+    deploy:
+      resources:
+        limits:
+          memory: 4G  # More memory for dev
+        reservations:
+          memory: 1G
+    logging:
+      options:
+        max-size: "20m"
+        max-file: "3"
+    labels:
+      - "com.openspace.environment=development"
--- a/docker-compose.prod.yml
+++ b/docker-compose.prod.yml
@ -0,0 +1,22 @@
+# Production-specific overrides for OpenSpace
+# Usage: docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d
+
+services:
+  openspace:
+    # Production resource limits
+    deploy:
+      resources:
+        limits:
+          memory: 4G
+          cpus: '4.0'
+        reservations:
+          memory: 1G
+          cpus: '1.0'
+    # More aggressive log rotation for production
+    logging:
+      options:
+        max-size: "50m"
+        max-file: "5"
+    labels:
+      - "com.openspace.environment=production"
+      - "com.openspace.log-level=info"
--- a/docker-compose.yml
+++ b/docker-compose.yml
@ -0,0 +1,68 @@
+services:
+  openspace:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    container_name: openspace
+    ports:
+      - "${HOST_PORT:-9001}:7788"
+    volumes:
+      # Use bind mounts for easier access, or named volumes for persistence
+      - ${VOLUME_TYPE:-named}:${VOLUME_DATA:-openspace-data}:/app/.openspace
+      - ${VOLUME_TYPE:-named}:${VOLUME_SKILLS:-openspace-skills}:/app/skills
+      # For bind mounts, you would use:
+      # - ./data:/app/.openspace
+      # - ./skills:/app/skills
+    environment:
+      # Required: Generate a secure API key for this instance
+      - OPENSPACE_API_KEY=${OPENSPACE_API_KEY:-}
+      # Optional: OpenAI API key (if using OpenAI models)
+      - OPENAI_API_KEY=${OPENAI_API_KEY:-}
+      # Optional: Anthropic API key (if using Claude)
+      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY:-}
+      # Optional: Default model to use (e.g., "claude-3-7-sonnet-latest")
+      - OPENSPACE_MODEL=${OPENSPACE_MODEL:-}
+      # Optional: Custom LLM provider (like OpenRouter, local LLM)
+      - OPENSPACE_LLM_API_KEY=${OPENSPACE_LLM_API_KEY:-}
+      - OPENSPACE_LLM_API_BASE=${OPENSPACE_LLM_API_BASE:-}
+      # Optional: Set to "1" to enable debug logging
+      - OPENSPACE_DEBUG=${OPENSPACE_DEBUG:-0}
+      # Internal config
+      - HOST=0.0.0.0
+      - PORT=7788
+      - OPENSPACE_WORKSPACE=/app
+    restart: unless-stopped
+    # Health check to ensure the service is ready
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:7788/health || exit 1"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 40s
+    # Resource limits (adjust based on your needs)
+    deploy:
+      resources:
+        limits:
+          memory: 2G
+          cpus: '2.0'
+        reservations:
+          memory: 512M
+          cpus: '0.5'
+    # Logging configuration to prevent disk fill
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "10m"
+        max-file: "3"
+    # Labels for monitoring and identification
+    labels:
+      - "com.openspace.service=true"
+      - "com.openspace.component=api"
+      - "com.openspace.version=${OPENSPACE_VERSION:-latest}"
+
+# Named volumes for data persistence (used when VOLUME_TYPE=named)
+volumes:
+  openspace-data:
+    driver: local
+  openspace-skills:
+    driver: local