使用说明
DSL到PNG MCP服务器
🎨 一个强大的模型上下文协议（MCP）服务器，使用Playwright浏览器自动化将领域特定语言（DSL）定义转换为高质量的PNG图像。
🚀 快速开始
开发环境
# 1. Clone the repository
git clone <repository-url>
cd dslToPngMCP
# 2. Setup development environment
make setup-dev
# 3. Start all services
make dev
# 4. Access the application
open http://localhost
生产部署
# 1. Configure production environment
cp .env.production .env
# Edit .env with your production settings
# 2. Generate production secrets
./scripts/generate-secrets.sh
# 3. Deploy to production
make deploy-prod
📋 目录
✨ 特性
核心功能
- DSL到PNG转换：将JSON/YAML DSL定义转换为高质量的PNG图像
- MCP协议支持：全面实施AI集成的模型上下文协议
- 异步处理：使用Celery进行后台任务处理，以应对繁重的渲染工作负载
- 浏览器池：管理Playwright浏览器实例以获得最佳性能
- 智能缓存：基于Redis的缓存可缩短响应时间
生产就绪
- 多容器架构：具有适当隔离的6服务架构
- 负载平衡：具有轮转负载平衡的Nginx反向代理
- 自动缩放：对高需求场景的横向扩展支持
- 健康监测：全面的健康检查和监测
- 零停机部署：蓝绿色部署战略
- SSL/TLS支持：具有Let’s Encrypt集成的生产就绪HTTPS
开发者体验
- 热重新加载：具有实时代码重新加载功能的开发环境
- 交互式API文档：内置Swagger/OpenAPI文档
- 综合录井：跨所有服务的结构化日志记录
- 发出命令：所有操作的简单make命令
- 健康检查：内置健康监测和诊断
🏗️ 建筑
服务体系结构
graph TB
Client[Client] --> Nginx[Nginx Proxy]
Nginx --> FastAPI1[FastAPI Server 1]
Nginx --> FastAPI2[FastAPI Server 2]
FastAPI1 --> MCP[MCP Server]
FastAPI2 --> MCP
FastAPI1 --> Redis[(Redis)]
FastAPI2 --> Redis
Redis --> Celery1[Celery Worker 1]
Redis --> Celery2[Celery Worker 2]
Redis --> Celery3[Celery Worker 3]
Redis --> Celery4[Celery Worker 4]
Celery1 --> Playwright[Playwright Browsers]
Celery2 --> Playwright
Celery3 --> Playwright
Celery4 --> Playwright
Playwright --> Storage[(PNG Storage)]
网络体系结构
- 前端网络：Nginx代理和外部访问
- 后端网络：内部API通信（隔离）
- 浏览器网络：剧作家浏览器池（隔离）
资源分配
| 服务 | CPU限制 | 内存限制 | 副本 | 用途 |
|---|---|---|---|---|
| Nginx代理 | 0.1 CPU | 128MB | 1 | 负载均衡器和SSL终止 |
| MCP服务器 | 0.5 CPU | 512MB | 1 | MCP协议处理 |
| FastAPI服务器 | 0.5 CPU | 512MB | 2 | REST API端点 |
| Celery Workers | 1.0 CPU | 1GB | 4 | 后台渲染任务 |
| 剧作家浏览器 | 2.0 CPU | 2GB | 1 | 用于渲染的浏览器池 |
| Redis | 0.2 CPU | 256MB | 1 | 缓存和消息队列 |
📋 需求
系统要求
- 码头工人：版本20.10或更高版本
- Docker Compose：2.0或更高版本
- 系统记忆体：最低8GB RAM（建议生产使用16GB）
- 磁盘空间：最小10GB可用空间
- 操作系统：Linux（Ubuntu 20.04+）、macOS（10.15+）或带WSL2的Windows
开发要求
- Git：用于版本控制
- 制造：便于执行命令
- 卷曲：用于API测试
- Node.js：版本18+（用于开发工具）
🔧 安装
开发设置
-
克隆存储库
git clone <repository-url> cd dslToPngMCP -
运行开发设置
make setup-dev这将：
- 创建必要的目录
- 生成开发秘密
- 构建Docker镜像
- 设置SSL证书
- 配置环境文件
-
启动开发环境
make dev -
验证安装
make health
生产设置
-
准备生产环境
# Copy production environment template cp .env.production .env # Edit configuration (IMPORTANT!) nano .env # Update DOMAIN_NAME, passwords, etc. -
生成生产秘密
# Generate strong passwords and keys openssl rand -base64 32 > secrets/app_secret_key.txt openssl rand -base64 16 > secrets/redis_password.txt openssl rand -base64 16 > secrets/grafana_password.txt chmod 600 secrets/* -
部署到生产
make deploy-prod
⚙️ 配置
环境变量
核心应用程序设置
DSL_PNG_ENVIRONMENT=production # Environment: development|production
DSL_PNG_DEBUG=false # Debug mode
DSL_PNG_LOG_LEVEL=INFO # Logging level
DSL_PNG_DOMAIN_NAME=yourdomain.com # Your domain
数据库和缓存
DSL_PNG_REDIS_URL=redis://redis:6379/0 # Redis connection
DSL_PNG_CELERY_BROKER_URL=redis://redis:6379/1 # Celery broker
安全
DSL_PNG_SECRET_KEY_FILE=/run/secrets/app_secret_key # App secret
DSL_PNG_ALLOWED_HOSTS=["yourdomain.com"] # Allowed hosts
DSL_PNG_CORS_ORIGINS=["https://yourdomain.com"] # CORS origins
演出
DSL_PNG_WORKERS=4 # FastAPI workers
DSL_PNG_BROWSER_POOL_SIZE=5 # Browser instances
DSL_PNG_RATE_LIMIT_REQUESTS=50 # Rate limit
卷配置
永久存储
- PNG存储:
/opt/dsl-png/storage/png-生成的PNG文件 - Redis数据:
/opt/dsl-png/data/redis-Redis持久性 - 日志:
/opt/dsl-png/logs-应用程序日志
临时存储
- HTML临时文件：浏览器生成的HTML文件
- 浏览器缓存：Playwright浏览器缓存
🎯 用法
REST API
同步渲染
curl -X POST "http://localhost/render" \
-H "Content-Type: application/json" \
-d '{
"dsl_content": "{\"width\": 400, \"height\": 300, \"elements\": [{\"type\": \"button\", \"layout\": {\"x\": 100, \"y\": 100, \"width\": 200, \"height\": 50}, \"label\": \"Click Me\", \"style\": {\"background\": \"#007bff\", \"color\": \"white\"}}]}",
"options": {
"width": 800,
"height": 600
}
}'
异步渲染
# Submit rendering task
curl -X POST "http://localhost/render/async" \
-H "Content-Type: application/json" \
-d '{
"dsl_content": "...",
"options": {"width": 800, "height": 600}
}'
# Check task status
curl "http://localhost/status/{task_id}"
DSL验证
curl -X POST "http://localhost/validate" \
-H "Content-Type: application/json" \
-d '{
"dsl_content": "{\"width\": 400, \"height\": 300, \"elements\": []}"
}'
MCP协议
服务器实现了三个核心MCP工具：
- 渲染_实物模型：将DSL转换为PNG
- validate_dsl：验证DSL语法
- get_nder_status：检查异步任务状态
可用端点
| 端点 | 方法 | 描述 |
|---|---|---|
/ |
GET | 欢迎页面 |
/health |
GET | 健康检查 |
/docs |
获取 | API文档 |
/render |
POST | 同步渲染 |
/render/async |
POST | 异步渲染 |
/validate |
POST | DSL验证 |
/status/{task_id} |
GET | 任务状态 |
/static/png/ |
GET | PNG文件访问 |
📚 文档
完整的文档套件
该项目包括全面的生产准备文件：
核心文件
- 📖 用户指南 -完整的用户指南，包括教程和最佳实践
- 🔧 安装指南 -开发和生产的详细安装
- 🎯 DSL参考 -完整的DSL语法和元素参考
- 🏗️ 架构指南 -系统架构和设计决策
- 📋 API文档 -完整的REST API和MCP协议参考
运营与维护
示例和教程
交互式文档
- Swagger用户界面:
http://localhost/docs-交互式API测试 - ReDoc:
http://localhost/redoc-API综合参考
性能指标和能力
渲染性能
- 吞吐量：100+并发渲染操作
- 响应时间：典型UI模型<2秒
- 图像质量：高分辨率PNG输出（最高4K）
- 浏览器池：5个并发剧作家实例
- 缓存命中率：85%以上使用Redis缓存
系统能力
- 并发用户：支持1000+个并发用户
- 每日效果图：每天100000多次渲染操作
- 运行时间：99.9%的可用性，具有健康监测功能
- 可扩展性：横向扩展与负载平衡
- 安全：生产级SSL/TLS和速率限制
DSL支持
- 元素类型：支持15+个UI元素
- 布局系统：绝对灵敏的定位
- 样式：完整的CSS样式支持
- 验证：实时DSL语法验证
- 格式支持：JSON和YAML输入格式
快速DSL示例
{
"width": 800,
"height": 600,
"elements": [
{
"type": "button",
"layout": {
"x": 100,
"y": 100,
"width": 200,
"height": 50
},
"label": "Click Me",
"style": {
"background": "#007bff",
"color": "white",
"border_radius": "5px"
}
}
]
}
📖 有关完整的DSL语法和示例，请参阅 DSL参考
🛠️ 发展
可用命令
# Development
make setup-dev # Setup development environment
make dev # Start development environment
make dev-logs # Show development logs
make dev-stop # Stop development environment
# Production
make deploy-prod # Deploy to production
make prod # Start production environment
make prod-logs # Show production logs
# Testing
make test # Run all tests
make test-unit # Run unit tests
make health # Run health checks
# Utilities
make shell-fastapi # Access FastAPI container
make redis-cli # Access Redis CLI
make logs # Show all logs
make clean # Clean Docker resources
开发工作流程
-
启动开发环境
make dev -
进行代码更改
- 代码更改会自动重新加载
- 访问日志：
make dev-logs
-
运行测试
make test -
检查健康状况
make health -
停止环境
make dev-stop
添加新功能
-
创建特征分支
git checkout -b feature/new-feature -
开发和测试
make dev # Make changes make test make health -
更新文档
- 更新API文档
- 添加配置选项
- 必要时更新README
🚀 部署
生产部署检查表
- []更新
DOMAIN_NAME在……里面.env.production - []在中生成强烈的秘密
secrets/目录 - []配置SSL证书（Let's Encrypt）
- []设置监控和警报
- []配置备份过程
- []检查安全设置
- []在暂存环境中进行测试部署
部署程序
-
预部署
# Backup current system make backup # Validate configuration make validate -
部署
# Zero-downtime deployment make deploy-prod -
部署后
# Verify deployment make health-prod # Monitor logs make prod-logs
回滚程序
如果部署失败：
# Automatic rollback during deployment failure
# Or manual rollback:
./scripts/rollback.sh
📊 监控
健康检查
# Check all services
make health
# Check production
make health-prod
# Service status
make status
度量和监控
- 普罗米修斯指标:
http://localhost:9090（如果启用） - Grafana仪表板:
http://localhost:3000（如果启用） - Nginx状态:
http://localhost/nginx-status - 应用程序指标:
http://localhost/metrics
日志管理
# View all logs
make logs
# Follow logs
make logs-follow
# Service-specific logs
make logs-service SERVICE=nginx-proxy
🔧 故障排除
常见问题
服务无法启动
# Check Docker daemon
docker info
# Check compose file
make validate
# View error logs
make logs
内存使用率高
# Check resource usage
make status
# Monitor containers
docker stats
SSL证书问题
# Regenerate development certificates
rm -rf docker/nginx/ssl/*
make setup-dev
# For production, check Let's Encrypt
docker compose -f docker compose.prod.yaml logs nginx-proxy
Redis连接问题
# Check Redis health
make redis-info
# Access Redis CLI
make redis-cli
调试模式
启用开发调试模式：
# In .env file
DSL_PNG_DEBUG=true
DSL_PNG_LOG_LEVEL=DEBUG
性能问题
-
检查资源使用情况
docker stats -
规模服务
docker compose up -d --scale celery-worker=6 -
监控瓶颈
make health
🤝 贡献
开发设置
- 分叉存储库
- 创建特征分支
- 设置开发环境：
make setup-dev - 进行更改和测试：
make test - 提交拉取请求
代码的风格
- Python代码遵循PEP 8
- 使用类型提示
- 为函数添加文档字符串
- 为新功能编写测试
提交变化
-
测试您的更改
make test make health -
更新文档
- API文档
- 配置更改
- README更新
-
创建pull请求
- 清晰的描述
- 问题链接
- 包括测试结果
📄 许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
🆘 支持
- 文档：参见
docs/目录 - 问题：GitHub问题
- 讨论：GitHub讨论
🔗 链接
由以下材料制成❤️ 对于MCP社区
