Gnosis Docker

Gnosis Docker

Flask异步服务器，为MCP（模型上下文协议）与Claude Desktop和Claude Code的集成提供Docker管理端点。该服务器通过Docker套接字挂载与Docker守护进程通信，通过AI助手实现全面的容器管理。

特性

• 完整的Docker容器管理（列表、启动、停止、重启、删除）
• Docker镜像管理（列表、拉取、删除、构建）
• 容器日志流和统计数据监控
• 集装箱检查和健康检查
• Gnosis项目的Docker构建触发器
• 异步Flask服务器，具有适当的错误处理功能
• 仅用于本地访问的安全中间件
• 用于AI助手集成的MCP工具

先决条件和设置

带WSL2的Windows（推荐）

Gnosis Docker在Windows上使用WSL2和Docker Desktop效果最佳，因为它提供了本机Docker套接字访问：

1.安装WSL2

# Run as Administrator in PowerShell
wsl --install
# Restart your computer

2.安装Docker桌面

• 从下载Docker桌面https://www.docker.com/products/docker-desktop/
• 安装过程中，确保选择了“使用基于WSL 2的发动机”
• 启动Docker桌面

3.为WSL2配置Docker桌面

# Run the setup helper script
.\setup-docker-desktop.ps1

或手动配置：

1. 打开Docker桌面设置
2. 首选 将军 tab → 启用“使用基于WSL 2的引擎”
3. 首选 资源 → WSL集成 → 启用与WSL2发行版的集成
4. 开发可选：In 将军 tab → 启用“打开守护进程”tcp://localhost:2375无TLS”
5. 点击 应用并重新启动

4.验证Docker套接字访问

在WSL2中：

# Check if Docker socket is accessible
ls -la /var/run/docker.sock
# Should show: srw-rw---- 1 root docker 0 [date] /var/run/docker.sock

# Test Docker connection
docker version

不带WSL2的Windows（有限）

对于没有WSL2的开发，您可以使用Docker Desktop的TCP端点：

1. 在Docker桌面中启用TCP端点（设置→ 将军→ “打开守护进程tcp://localhost:2375")
2. 设置环境变量： $env:DOCKER_HOST = "tcp://localhost:2375"
3. 运行： .\setup-docker-desktop.ps1 验证设置

备注：此方法有局限性和安全考虑。强烈推荐WSL2。

Docker套接字通信

Gnosis Docker使用Docker套接字挂载与Docker守护进程通信：

• WSL2：使用Unix套接字 /var/run/docker.sock （装在容器中）
• 传输控制协议：用途 tcp://localhost:2375 （仅用于开发）
• 安全：服务器验证所有容器操作和装载

目录结构

gnosis-docker/
├── deploy.ps1              # Single deployment script for all environments
├── deploy-wsl2.sh          # WSL2 deployment script
├── requirements.txt        # Python dependencies
├── setup.ps1               # Initial setup script
├── setup-docker-desktop.ps1 # Docker Desktop configuration helper
├── Dockerfile             # Docker configuration
├── docker-compose.yml     # Local development with Redis
├── .env.example           # Environment variable template
├── .gitignore            # Git ignore file
├── README.md             # This file
├── WSL2_README.md        # WSL2-specific documentation
├── app.py                # Main Flask application
├── core/                 # Core application modules
│   ├── __init__.py
│   ├── docker_manager.py  # Docker operations handler
│   ├── auth.py           # Authentication middleware
│   ├── config.py         # Configuration management
│   ├── validation.py     # Container security validation
│   └── utils.py          # Utility functions
├── tests/                # Test suite
│   ├── __init__.py
│   └── test_docker_api.py
├── mcp/                  # MCP Tools Directory
│   ├── README.md         # MCP tools documentation
│   ├── requirements.txt  # MCP-specific dependencies
│   ├── setup.py          # MCP tools setup script
│   ├── gnosis_docker_mcp.py    # Docker management MCP tool
│   ├── file_manager_mcp.py     # File operations MCP tool
│   └── example_utilities_mcp.py # Example MCP tool
└── cleanup_*.py|ps1|sh   # Repository cleanup scripts

快速开始

部署Docker API服务器

Windows WSL2（推荐）

# From WSL2 terminal
cd /mnt/c/Users/kord/Code/gnosis/gnosis-docker

# Make scripts executable
chmod +x deploy-wsl2.sh

# Deploy locally
./deploy-wsl2.sh

Windows PowerShell

# Initial setup (run once)
.\setup.ps1

# Windows - Deploy locally
.\deploy.ps1 -Target local

# Windows - Deploy to staging
.\deploy.ps1 -Target staging

# Windows - Deploy to production
.\deploy.ps1 -Target production

# Windows - Rebuild from scratch
.\deploy.ps1 -Target local -Rebuild

# Windows - Dry run (see what would happen)
.\deploy.ps1 -Target production -WhatIf

将MCP工具与AI助手结合使用

这 /mcp 目录包含与Claude Code和Claude Desktop集成的即用型MCP工具：

# Navigate to MCP tools
cd mcp

# Install dependencies
pip install -r requirements.txt

# Run setup and validation
python setup.py

# Configure with Claude Code
claude mcp add gnosis-docker python3 gnosis_docker_mcp.py

# Test the integration
claude
# Then try: "list docker containers", "check docker health"

看 mcp/README.md 了解完整的MCP设置说明。

API终点

容器管理

• GET /health -健康检查
• GET /api/containers -列出所有容器
• GET /api/containers/ -获取容器详细信息
• POST /api/containers//start -启动容器
• POST /api/containers//stop -停止集装箱
• POST /api/containers//restart -重新启动容器
• DELETE /api/containers/ -移除容器
• GET /api/containers//logs -获取容器日志
• GET /api/containers//stats -获取容器统计信息

图像管理

• GET /api/images -列出所有图像
• POST /api/images/pull -拉取图像
• DELETE /api/images/ -删除图像

项目运营

• POST /api/build -构建一个Gnosis项目
• POST /api/projects//deploy -部署项目

MCP集成

该服务器通过MCP工具为AI助手提供Docker管理功能：

可用的MCP工具

1. Gnosis Docker MCP (mcp/gnosis_docker_mcp.py)

- 通过克劳德代码/桌面完成Docker管理 - 列出、启动、停止、重新启动容器 - 获取容器日志和统计信息 - 管理Docker镜像 - 构建和部署Gnosis项目

1. 文件管理器MCP (mcp/file_manager_mcp.py)

- 跨平台文件操作 - 创建、复制、移动、删除文件和目录 - 安全操作的备份支持

1. 示例实用程序MCP (mcp/example_utilities_mcp.py)

- 演示MCP开发模式 - 基本实用程序（回声、时间戳、计算） - 文本分析和系统信息

配置方法

克劳德代码（推荐）：

claude mcp add gnosis-docker python3 /path/to/gnosis-docker/mcp/gnosis_docker_mcp.py

克劳德桌面： 增添 claude_desktop_config.json:

{
  "mcpServers": {
    "gnosis-docker-mcp": {
      "command": "python",
      "args": ["C:\\path\\to\\gnosis-docker\\mcp\\gnosis_docker_mcp.py"]
    }
  }
}

存储库维护

清理版本控制目录

此存储库包括用于删除不需要的版本控制目录和Python缓存文件的清理脚本：

# Python script (cross-platform)
python cleanup_comprehensive.py

# PowerShell script (Windows)
.\cleanup_comprehensive.ps1

# Bash script (Linux/WSL2)
./cleanup_quick.sh

这些脚本将删除：

• *_versions/ 目录
• __pycache__/ 目录
• *.pyc 文件
• 更新 .gitignore 有适当的图案

环境变量

• FLASK_ENV -环境（开发/分期/生产）

• DOCKER_HOST -Docker守护进程URL（默认值：unix:///var/run/docker.sock，或tcp://localhost:2375适用于Windows）

• API_KEY -生产认证密钥

• REDIS_URL -缓存Redis URL（可选）

• GNOSIS_DOCKER_URL -API端点URL（默认值：http://localhost:5680)

安全

• 仅限本地访问 默认情况下（绑定到127.0.0.1）
• API密钥验证 用于生产部署
• 请求验证 和消毒
• Docker套接字安全 具有适当的权限和验证
• CORS保护 用于web界面
• 容器参数验证 防止危险操作
• 卷装载限制 限制文件系统访问

发展

本地运行

# Install dependencies
pip install -r requirements.txt

# Or use setup script
.\setup.ps1

# Run in development mode
python app.py

# Run tests
python -m pytest tests/

# Test API endpoints
python test_api.py

Docker开发

# Build container
docker build -t gnosis-docker .

# Or use deployment script
.\deploy.ps1 -Target local

# Run with Docker Compose
docker-compose up -d

# View logs
docker-compose logs -f gnosis-docker

与Gnosis生态系统集成

此Docker控制器旨在与其他Gnosis组件配合使用：

• 灵知幽灵 -Web爬行和数据提取
• 神秘灵知 -功能拦截与分析
• Gnosis流 -数据处理和流媒体
• Gnosis进化 -开发工具和实用程序

MCP工具为AI助手提供了一个统一的接口，通过Docker容器管理整个Gnosis生态系统。

API使用示例

列出正在运行的容器

curl http://localhost:5680/api/containers

启动容器

curl -X POST http://localhost:5680/api/containers/mycontainer/start

获取容器日志

curl http://localhost:5680/api/containers/mycontainer/logs?tail=100

构建Gnosis项目

curl -X POST http://localhost:5680/api/build \
  -H "Content-Type: application/json" \
  -d '{"project": "gnosis-wraith", "tag": "latest"}'

故障排除

常见问题

1. Docker守护进程在WSL2中不可访问

- 检查Docker桌面是否正在运行 - 验证Docker桌面中是否启用了WSL2集成 - 检查Docker套接字是否存在： ls -la /var/run/docker.sock - 重新启动Docker桌面并重试

1. Docker守护进程在Windows上无法访问

- 确保Docker桌面正在运行 - 检查TCP端点是否已启用（设置→ 一般） - 验证 DOCKER_HOST 环境变量 - 尝试跑步： .\setup-docker-desktop.ps1

1. “无法连接到Docker守护进程”错误

- WSL2：检查Docker套接字是否已挂载： docker version - Windows：验证TCP终结点： curl http://localhost:2375/version - 检查防火墙设置 - 确保Docker桌面已完全启动

1. 容器无法启动

- 检查Docker日志： docker-compose logs gnosis-docker - 验证端口5680是否未使用： netstat -an | findstr 5680 - 检查docker-compose.yml中的卷装载量

1. 端口5680已在使用中

- 停止现有实例 - 更改部署脚本中的端口 - 检查是否存在冲突的服务

1. MCP工具未连接

- 验证API服务器是否在localhost:5680上运行 - 检查防火墙设置 - 确保安装了MCP依赖项

1. 双斜线路径问题

- 在Windows路径中使用单个反斜杠 - WSL2路径应使用 /mnt/c/ 前缀 - Docker compose在容器内使用Linux风格的路径 - 检查docker-compose.yml卷映射

日志和调试

# Check API server logs
docker-compose logs gnosis-docker

# Enable debug logging
export FLASK_ENV=development  # WSL2
$env:FLASK_ENV = "development"  # PowerShell
python app.py

# Test API health
curl http://localhost:5680/health

# Test Docker socket access (WSL2)
docker version
ls -la /var/run/docker.sock

贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 添加新功能的测试
5. 更新文档
6. 提交拉取请求

许可证

该项目是Gnosis生态系统的一部分，遵循相同的许可条款。