免责声明
⚠️ 人工智能实验项目 该项目是在人工智能（Claude Sonnet 4.5和Claude Opus 4.5）的帮助下生成的，并作为实现web应用程序的实验基础堆栈。该代码按“原样”提供，不提供任何明示或暗示的保证，包括但不限于适销性、特定用途适用性和不侵权保证。在任何情况下，作者或版权持有人均不对因软件或软件的使用或其他交易而产生、产生或与之相关的任何索赔、损害赔偿或其他责任承担责任，无论是在合同、侵权或其他诉讼中。 使用风险自负。 在部署到生产环境之前，请检查所有代码。
Python WebApp基础
一个使用FastAPI、HTMX、Alpine.js和Tailwind CSS构建的现代、生产就绪的Python web应用程序入门模板。该基础提供了快速构建交互式web应用程序所需的一切，包括服务器端渲染、可选的AI驱动开发监控（MCP）和遵循最佳实践的干净架构。
包含内容
- FastAPI后端：带有自动OpenAPI文档的现代Python web框架
- 交互式前端：HTMX+Alpine.js+顺风CSS（无需构建步骤）
- 本地依赖关系：所有前端库都在本地提供服务（没有CDN依赖关系）
- 服务器端渲染：Jinja2模板用于快速页面加载
- MCP服务器：可选的AI驱动开发监控和调试
- 代码质量：自动格式化、linting、类型检查、安全扫描
- 测试：具有覆盖率报告的全面pytest设置
- Docker就绪：针对生产优化的多阶段构建
- 最佳实践：符合PEP 8标准，架构简洁，基于环境的配置
入门指南
将其用作您自己的web应用程序的基础。只需克隆、定制并在此基础上构建即可。
快速开始
# Clone and setup
git clone my-project
cd my-project
./setup.sh
# Activate environment
source venv/bin/activate
# Run the application
./run.sh访问 查看您的应用程序是否正在运行。
技术栈
- 后端：使用FastAPI的Python 3.13+
- 前端：HTMX 1.9.10+Alpine.js 3.13.3+顺风CSS 3.4.1（本地）
- 模板：Jinja2（服务器端渲染）
- API文档：OpenAPI v3（Swagger用户界面）
- AI监控：用于开发的MCP服务器（可选）
- 代码质量：黑色，伊索特，高射炮，我的，土匪
- 测试：带覆盖率的pytest
- 部署：Docker具有多阶段构建，Gunicorn具有1个worker
先决条件
- Python 3.13+（推荐）或Python 3.11+
- Docker和Docker Compose（用于容器化部署）
- Git
设置
本地开发
开发使用Python虚拟环境（venv），不需要Docker。
1.克隆和导航
git clone my-project-name
cd my-project-name2.运行安装脚本
安装脚本将：
- 检测最新Python版本（3.11+）
- 创建虚拟环境
- 安装所有依赖项
- 设置预提交挂钩
- 从模板创建.env文件
./setup.sh3.激活虚拟环境
source venv/bin/activate4.配置环境变量
编辑 .env 使用您的本地配置（已由安装脚本创建）：
# Update these values
SECRET_KEY=your-secure-secret-key-here5.访问应用程序
打开浏览器：
- 主要应用:
- API文档: （Swagger用户界面）
- 备选文档: （ReDoc）
- 健康检查:
人工智能发展监测（MCP）
该项目包括 可选MCP（模型上下文协议）服务器 用于AI驱动的开发监控。启用后，GitHub Copilot可以主动监控您的应用程序并帮助检测问题。
MCP快速入门
- 编辑
.env并设置：
ENABLE_MCP_DEV_MODE=true- 重新启动应用程序：
./run.sh- 向GitHub Copilot提出以下问题：
- “目前的健康状况如何？” - “显示最近的错误” - “最慢的端点是什么？”
MCP工具可用
- 健康监测:
health_status,app_uptime - 日志访问:
recent_logs,search_logs,error_logs - 误差分析:
last_errors,error_summary - 演出:
request_metrics,endpoint_performance - 控制:
restart_app,reload_config - 公用事业:
list_routes,api_docs,get_config - 监控:
recent_alerts,alert_summary
后台监视器
监视器自动启动 启用MCP模式时：
# In .env
ENABLE_MCP_DEV_MODE=true
# Start app - monitors start automatically
./run.sh这将开始：
- 健康民调：每30秒检查一次应用程序运行状况，如果应用程序出现故障，则发出警报
- 性能监视器：跟踪CPU、内存、延迟-降级警报
- 日志监视器：实时日志监控，错误/关键条目警报
当检测到问题时，监视器会发送主动警报。问我：“显示最近的提醒”
MCP演示面板
主页上提供了一个演示面板，用于测试MCP监控：
- 反应迟钝：触发3秒延迟（测试延迟监测）
- 生成错误：创建500错误（测试错误检测和日志监视）
- CPU负荷：运行5秒CPU密集型操作（测试性能监控）
- 演示状态：显示演示系统状态和触发器计数
访问地址： 当 ENABLE_MCP_DEV_MODE=true.
演示API端点 （仅在MCP开发模式下可用）：
POST /api/v1/demo/slow?delay_seconds=3-模拟缓慢响应POST /api/v1/demo/error?status_code=500-生成错误POST /api/v1/demo/load?duration_seconds=5&intensity=0.8-CPU负载模拟GET /api/v1/demo/status-获取演示状态
📚 全部文件：参见 mcp_server/README.md 了解完整的MCP设置和使用。
⚠️ 安全生产：MCP服务器仅在以下情况下运行 ENABLE_MCP_DEV_MODE=true 并自动从Docker构建中排除。
生产部署（Docker）
生产使用Docker而不使用虚拟环境来获得最佳性能。
1.构建Docker镜像
docker build -t python-webapp-base:latest .2.配置环境
cp .env.docker .env
# Edit .env with production values3.启动应用程序
docker-compose up -d4.查看日志
docker-compose logs -f app发展
运行测试
测试在开发过程中是可选的，可以使用pytest运行：
# Run all tests
pytest
# Run with coverage
pytest --cov=app --cov-report=html
# Run specific test file
pytest tests/test_health.py
# Run tests verbosely
pytest -v看 TODO.md 包括MCP服务器测试在内的计划改进。
代码质量
预提交挂钩由以下方式自动安装 setup.sh。手动运行它们：
# Run all pre-commit hooks
pre-commit run --all-files
# Format code
black app tests
isort app tests
# Lint
flake8 app tests
# Type check
mypy app项目结构
.
├── app/ # Application code
│ ├── __init__.py
│ ├── main.py # FastAPI app entry point
│ ├── config.py # Configuration
│ ├── api/ # API endpoints
│ │ └── demo.py # MCP demo endpoints
│ └── middleware/ # Custom middleware
├── tests/ # Test suite
│ ├── conftest.py # Shared pytest fixtures
│ ├── test_health.py # Health endpoint tests
│ ├── test_api.py # API endpoint tests
│ ├── test_demo.py # MCP demo endpoint tests
│ ├── test_views.py # Frontend view tests
│ └── test_static.py # Static file tests
├── mcp_server/ # MCP development server (optional)
│ ├── server.py # MCP server entry point
│ ├── tools/ # MCP tool implementations
│ ├── monitors/ # Background monitors
│ └── utils/ # Utility functions
├── templates/ # Jinja2 HTML templates
│ └── index.html # Main frontend page
├── static/ # Static assets
│ ├── css/main.css # Custom CSS
│ ├── js/main.js # Custom JavaScript
│ └── vendor/ # Local frontend libraries
├── scripts/ # Utility scripts
├── .env.example # Environment variables template
├── .pre-commit-config.yaml
├── pyproject.toml # Python project configuration
├── requirements.txt # Production dependencies
├── requirements-dev.txt # Development dependencies
├── Dockerfile # Production container
└── docker-compose.yml # Container orchestrationAPI文档
API遵循OpenAPI v3标准，并提供了全面的文档：
- 所有端点都有描述和示例记录
- 请求/响应模式是用Pydantic模型定义的
- 错误响应遵循标准格式
- 身份验证要求已明确标记
访问交互式文档 /api/v1/docs 运行服务器时。
错误处理
API使用标准化的错误代码和响应格式：
{
"error_code": "RESOURCE_NOT_FOUND",
"message": "User with identifier 123 not found",
"details": {"resource": "User", "identifier": "123"},
"timestamp": "2025-11-20T10:30:00Z",
"path": "/api/v1/users/123"
}看 .github/copilot-instructions.md 了解完整的错误代码约定。
为您的项目进行自定义
这是一个入门模板-根据您的需求进行定制：
- 重命名项目:
- 更新 PROJECT_NAME 在 .env - 更新FastAPI description 在 app/main.py - 在构建命令中更新Docker镜像名称 - 更新 container_name 在 docker-compose.yml
- 添加您的功能:
- 在中添加新路线 app/main.py 或创建 app/api/ 对于大型项目 - 在中添加中间件 app/middleware/ - 创建用于请求/响应验证的Pydantic模式
- 自定义前端:
- 修改 templates/index.html 对于您的UI - 在中添加自定义CSS static/css/ - 在中添加自定义JavaScript static/js/
- 更新文档:
- 将此README替换为您的项目文档 - 更新路线文档字符串中的API文档
贡献
我们欢迎捐款！如果你改进了这个模板，请考虑回馈：
- 复刻仓库
- 创建要素分支(
git checkout -b feature/amazing-improvement) - 进行更改
- 确保测试通过，代码质量检查通过(
pre-commit run --all-files && pytest) - 提交您的更改(
git commit -m 'Add amazing improvement') - 推到分支(
git push origin feature/amazing-improvement) - 打开拉取请求
贡献方式
- 🐛 报告错误和问题
- 💡 建议新功能或改进
- 📖 改进文档
- 🔧 提交带有修复或增强功能的拉取请求
- ⭐ 如果你觉得这个项目有用，就给它标上星号
许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
回馈
虽然MIT许可证允许您自由使用此代码而不承担任何义务，但我们鼓励您为社区做出改进。如果你在这个模板的基础上构建了一些有用的东西，请考虑：
- 将错误修复和改进作为pull请求提交
- 分享您的扩展程序，使他人受益
- 报告您遇到的问题
您的贡献有助于使这个模板对每个人都更好！ 🙏