知识.docker
项目介绍
Gnosis Docker
这是一个异步Flask服务器，通过暴露Docker管理端点来实现与Claude Desktop和Claude Code的MCP（模型上下文协议）集成。该服务器通过挂载Docker套接字与Docker守护进程通信，从而通过AI助手实现全面的容器管理。
功能
- 完整的Docker容器管理（列出、启动、停止、重启、删除）
- Docker镜像管理（列出、拉取、删除、构建）
- 容器日志流和状态监控
- 容器检查和健康检查
- Gnosis项目的Docker构建触发
- 异步Flask服务器，具有正确的错误处理
- 仅本地访问的安全中间件
- 用于AI助手集成的MCP工具
预备条件和设置
Windows与WSL2（推荐）
在Windows上使用WSL2和Docker Desktop运行Gnosis Docker效果最佳，因为它提供了原生的Docker套接字访问：
1. 安装WSL2
# 在PowerShell中以管理员身份运行
wsl --install
# 重新启动计算机
2. 安装Docker Desktop
- 从https://www.docker.com/products/docker-desktop/下载Docker Desktop
- 在安装过程中，请确保选择了“使用基于WSL 2的引擎”
- 启动Docker Desktop
3. 配置Docker Desktop以支持WSL2
# 运行设置辅助脚本
.\setup-docker-desktop.ps1
或者手动配置：
- 打开Docker Desktop设置
- 转到常规选项卡 → 启用“使用基于WSL 2的引擎”
- 转到资源 → WSL集成 → 启用与您的WSL2发行版的集成
- 开发可选：在常规选项卡 → 启用“在tcp://localhost:2375上暴露守护进程，不使用TLS”
- 点击应用并重启
4. 验证Docker套接字访问
在WSL2中：
# 检查Docker套接字是否可访问
ls -la /var/run/docker.sock
# 应显示：srw-rw---- 1 root docker 0 [日期] /var/run/docker.sock
# 测试Docker连接
docker version
Windows无WSL2（有限）
对于没有WSL2的开发，可以使用Docker Desktop的TCP端点：
- 在Docker Desktop中启用TCP端点（设置 → 通用 → “在tcp://localhost:2375上暴露守护进程”）
- 设置环境变量：
$env:DOCKER_HOST = "tcp://localhost:2375" - 运行：
.\setup-docker-desktop.ps1以验证设置
注意：此方法存在限制和安全考虑。强烈推荐使用WSL2。
Docker套接字通信
Gnosis Docker通过挂载Docker套接字与Docker守护进程通信：
- WSL2：使用Unix套接字
/var/run/docker.sock（挂载到容器中） - TCP：使用
tcp://localhost:2375（仅用于开发） - 安全性：服务器验证所有容器操作并进行挂载
目录结构
gnosis-docker/
├── deploy.ps1 # 适用于所有环境的单个部署脚本
├── deploy-wsl2.sh # WSL2部署脚本
├── requirements.txt # Python依赖项
├── setup.ps1 # 初始设置脚本
├── setup-docker-desktop.ps1 # Docker Desktop配置辅助脚本
├── Dockerfile # Docker配置
├── docker-compose.yml # 使用Redis的本地开发
├── .env.example # 环境变量模板
├── .gitignore # Git忽略文件
├── README.md # 本文件
├── WSL2_README.md # WSL2特定文档
├── app.py # 主Flask应用程序
├── core/ # 核心应用程序模块
│ ├── __init__.py
│ ├── docker_manager.py # Docker操作处理器
│ ├── auth.py # 认证中间件
│ ├── config.py # 配置管理
│ ├── validation.py # 容器安全验证
│ └── utils.py # 工具函数
├── tests/ # 测试套件
│ ├── __init__.py
│ └── test_docker_api.py
├── mcp/ # MCP工具目录
│ ├── README.md # MCP工具文档
│ ├── requirements.txt # MCP特定依赖项
│ ├── setup.py # MCP工具设置脚本
│ ├── gnosis_docker_mcp.py # Docker管理MCP工具
│ ├── file_manager_mcp.py # 文件操作MCP工具
│ └── example_utilities_mcp.py # 示例MCP工具
└── cleanup_*.py|ps1|sh # 仓库清理脚本
快速开始
部署Docker API服务器
Windows WSL2（推荐）
# 从WSL2终端
cd /mnt/c/Users/kord/Code/gnosis/gnosis-docker
# 使脚本可执行
chmod +x deploy-wsl2.sh
# 本地部署
./deploy-wsl2.sh
Windows PowerShell
# 初始设置（只需运行一次）
.\setup.ps1
# Windows - 本地部署
.\deploy.ps1 -Target local
# Windows - 部署到预发布环境
.\deploy.ps1 -Target staging
# Windows - 部署到生产环境
.\deploy.ps1 -Target production
# Windows - 从头开始重建
.\deploy.ps1 -Target local -Rebuild
# Windows - 干运行（查看会发生什么）
.\deploy.ps1 -Target production -WhatIf
使用AI助手的MCP工具
/mcp目录包含可用于与Claude Code和Claude Desktop集成的MCP工具：
# 导航到MCP工具
cd mcp
# 安装依赖项
pip install -r requirements.txt
# 运行设置和验证
python setup.py
# 与Claude Code配置
claude mcp add gnosis-docker python3 gnosis_docker_mcp.py
# 测试集成
claude
# 然后尝试："列出Docker容器"，"检查Docker健康"
请参阅mcp/README.md获取完整的MCP设置说明。
API端点
容器管理
GET /health- 健康检查GET /api/containers- 列出所有容器GET /api/containers/<id>- 获取容器详情POST /api/containers/<id>/start- 启动容器POST /api/containers/<id>/stop- 停止容器POST /api/containers/<id>/restart- 重启容器DELETE /api/containers/<id>- 删除容器GET /api/containers/<id>/logs- 获取容器日志GET /api/containers/<id>/stats- 获取容器状态
镜像管理
GET /api/images- 列出所有镜像POST /api/images/pull- 拉取一个镜像DELETE /api/images/<id>- 删除一个镜像
项目操作
POST /api/build- 构建一个Gnosis项目POST /api/projects/<name>/deploy- 部署一个项目
MCP集成
此服务器通过MCP工具提供Docker管理功能给AI助手：
可用的MCP工具
-
Gnosis Docker MCP (
mcp/gnosis_docker_mcp.py)- 通过Claude Code/Desktop完成完整的Docker管理
- 列出、启动、停止、重启容器
- 获取容器日志和状态
- 管理Docker镜像
- 构建和部署Gnosis项目
-
文件管理MCP (
mcp/file_manager_mcp.py)- 跨平台文件操作
- 创建、复制、移动、删除文件和目录
- 支持备份以保证安全操作
-
示例实用程序MCP (
mcp/example_utilities_mcp.py)- 展示MCP开发模式
- 基本实用程序（回显、时间戳、计算）
- 文本分析和系统信息
配置方法
Claude Code（推荐）：
claude mcp add gnosis-docker python3 /path/to/gnosis-docker/mcp/gnosis_d
ocker_mcp.py
Claude Desktop：
添加到claude_desktop_config.json：
{
"mcpServers": {
"gnosis-docker-mcp": {
"command": "python",
"args": ["C:\\path\\to\\gnosis-docker\\mcp\\gnosis_docker_mcp.py"]
}
}
}
仓库维护
清理版本控制目录
此仓库包括清理脚本以移除不需要的版本控制目录和Python缓存文件：
# Python脚本（跨平台）
python cleanup_comprehensive.py
# PowerShell脚本（Windows）
.\cleanup_comprehensive.ps1
# Bash脚本（Linux/WSL2）
./cleanup_quick.sh
这些脚本将移除：
*_versions/目录__pycache__/目录*.pyc文件- 更新
.gitignore以包含正确模式
环境变量
-
FLASK_ENV- 环境（开发/预发布/生产） -
DOCKER_HOST- Docker守护进程URL（默认：unix:///var/run/docker.sock，或Windows上的tcp://localhost:2375） -
API_KEY- 生产认证密钥 -
REDIS_URL- 缓存的Redis URL（可选） -
GNOSIS_DOCKER_URL- API端点URL（默认：http://localhost:5680）
安全性
- 默认仅本地访问（绑定到127.0.0.1）
- 生产部署的API密钥认证
- 请求验证和净化
- 具有适当权限和验证的Docker套接字安全性
- 网页界面的CORS保护
- 容器参数验证防止危险操作
- 限制文件系统访问的卷挂载限制
开发
本地运行
# 安装依赖项
pip install -r requirements.txt
# 或使用设置脚本
.\setup.ps1
# 在开发模式下运行
python app.py
# 运行测试
python -m pytest tests/
# 测试API端点
python test_api.py
Docker开发
# 构建容器
docker build -t gnosis-docker .
# 或使用部署脚本
.\deploy.ps1 -Target local
# 使用Docker Compose运行
docker-compose up -d
# 查看日志
docker-compose logs -f gnosis-docker
与Gnosis生态系统集成
此Docker控制器设计用于与其他Gnosis组件协同工作：
- Gnosis Wraith - 网络爬虫和数据提取
- Gnosis Mystic - 函数拦截和分析
- Gnosis Stream - 数据处理和流传输
- Gnosis Evolve - 开发工具和实用程序
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"}'
故障排除
常见问题
-
在WSL2中无法访问Docker守护进程
- 检查Docker Desktop是否正在运行
- 验证Docker Desktop中的WSL2集成是否已启用
- 检查Docker套接字是否存在：
ls -la /var/run/docker.sock - 重新启动Docker Desktop并再次尝试
-
在Windows中无法访问Docker守护进程
- 确保Docker Desktop正在运行
- 检查是否启用了TCP端点（设置 → 通用）
- 验证
DOCKER_HOST环境变量 - 尝试运行：
.\setup-docker-desktop.ps1
-
“无法连接到Docker守护进程”的错误
- WSL2：检查Docker套接字是否已挂载：
docker version - Windows：验证TCP端点：
curl http://localhost:2375/version - 检查防火墙设置
- 确保Docker Desktop已完全启动
- WSL2：检查Docker套接字是否已挂载：
-
容器无法启动
- 检查Docker日志：
docker-compose logs gnosis-docker - 验证端口5680未被占用：
netstat -an | findstr 5680 - 检查docker-compose.yml中的卷挂载
- 检查Docker日志：
-
端口5680已被占用
- 停止现有实例
- 更改部署脚本中的端口
- 检查是否有冲突的服务
-
MCP工具无法连接
- 验证API服务器是否在localhost:5680上运行
- 检查防火墙设置
- 确保已安装MCP依赖项
-
路径问题双斜杠
- 在Windows路径中使用单反斜杠
- WSL2路径应使用
/mnt/c/前缀 - Docker-compose在容器内部使用Linux风格路径
- 检查docker-compose.yml中的卷映射
日志和调试
# 检查API服务器日志
docker-compose logs gnosis-docker
# 启用调试日志
export FLASK_ENV=development # WSL2
$env:FLASK_ENV = "development" # PowerShell
python app.py
# 测试API健康状况
curl http://localhost:5680/health
# 测试Docker套接字访问（WSL2）
docker version
ls -la /var/run/docker.sock
贡献
- 分叉仓库
- 创建功能分支
- 进行更改
- 为新功能添加测试
- 更新文档
- 提交合并请求
许可
此项目是Gnosis生态系统的一部分，并遵循相同的许可条款。