带有Azure存储的Python Aspire代理工作台
一个用以下代码构建的现代Python代理工作台 Aspire 13 用于Azure容器应用程序部署,具有Azure存储集成(块、队列、表)和MCP(模型上下文协议)支持。
> 🤖 GitHub复制品就绪:此存储库包括全面的 GitHub副本说明 帮助您充分利用人工智能辅助开发。看 贡献.md 关于贡献指南。
概述
该项目演示了一个尖端的云原生Python应用程序,使用:
- Aspire 13 (最新)用于编排和云部署
- .NET 10 SDK 用于Aspire工具
- Azure容器应用 用于无服务器托管
- Azure存储 (块、队列、表)用于数据持久化
- 快速API 用于高性能REST API
- React+Vite 使用TypeScript的前端
- 开放遥测 可观察性
- 主控程序 用于代理通信
> 📚 架构文档:参见 存储_建筑.md 有关基础存储架构的详细信息,包括多租户数据模型、分区策略和查询模式。
项目结构```
.
├── PythonAspireSample/
│ ├── apphost.cs # Aspire 13 single-file AppHost
│ ├── apphost.run.json # Run configuration
│ ├── app/ # Python FastAPI application
│ │ ├── main.py # Main API with Azure Storage endpoints
│ │ ├── telemetry.py # OpenTelemetry configuration
│ │ ├── pyproject.toml # Python dependencies
│ │ ├── .python-version # Python version (3.13)
│ │ └── .dockerignore # Docker ignore patterns
│ └── frontend/ # React + Vite frontend
│ ├── src/ # TypeScript source files
│ ├── public/ # Static assets
│ ├── vite.config.ts # Vite configuration
│ └── package.json # Node dependencies
├── azure.yaml # Azure Developer CLI config
└── README.md # This file
## 先决条件
### 必需
- **.NET SDK 10.0.100或更高版本** (Aspire 13需要)
- **Python 3.13** 或以后
- **Node.js 18+** (前端)
- **Docker 桌面版** 或波德曼(用于当地发展)
### 用于Azure部署
- **Azure开发者命令行界面(azd)** - 安装azd
- **Azure订阅**
## 入门指南
### 1.安装。净10 SDK
**Linux/macOS:**```bash
curl -sSL https://dot.net/v1/dotnet-install.sh | bash /dev/stdin --channel 10.0
export PATH="$HOME/.dotnet:$PATH"
export DOTNET_ROOT="$HOME/.dotnet"
Windows(PowerShell):```powershell
Invoke-WebRequest -Uri https://dot.net/v1/dotnet-install.ps1 -OutFile dotnet-install.ps1
./dotnet-install.ps1 -Channel 10.0
验证安装:```bash
dotnet --version # Should show 10.0.100 or later
2.安装Aspire CLI 13
将Aspire CLI安装为。NET全局工具:```bash
dotnet tool install -g Aspire.Cli --prerelease
验证安装:```bash
aspire --version # Should show 13.0.0
3.在本地运行应用程序
导航到项目目录并运行:```bash
cd PythonAspireSample
aspire run
这将:
- 启动Aspire仪表板(通常在https://localhost:19888)
- 启动Python FastAPI应用程序
- 启动React前端
- 为本地开发设置Azure存储模拟(Azurite)
- 自动配置所有服务连接
- 启用OpenTetry跟踪和指标
### 4.访问应用程序
运行后,访问:
- **Aspire仪表板**: https://localhost:19888
- **Python API**: http://localhost:PORT(检查仪表板上的实际端口)
- **前端**: http://localhost:PORT(检查仪表板上的实际端口)
仪表板提供:
- 实时服务健康监测
- 分布式跟踪可视化
- 日志聚合
- 指标和绩效数据
- 资源拓扑
## API终点
Python FastAPI应用程序提供以下端点:
### 核心终点
- `GET /` -服务信息和可用端点
- `GET /health` -健康检查端点
- `GET /api/weatherforecast` -天气预报数据示例
### Azure存储集成端点
- `GET /api/storage/test` -测试所有Azure存储连接
- `GET /api/blob/upload` -将测试blob上载到Azure blob存储
- `GET /api/queue/send` -向Azure队列存储发送测试消息
- `GET /api/table/insert` -将测试实体插入Azure表存储
## Azure存储集成
该应用程序演示了与三个Azure存储服务的集成:
### Blob存储
- 上传和下载文件
- 集装箱管理
- 通过集成 `azure-storage-blob` Python 软件开发工具包
- 连接字符串: `ConnectionStrings__blobs` (由Aspire设定)
### 队列存储
- 发送和接收消息
- 队列管理
- 通过集成 `azure-storage-queue` Python 软件开发工具包
- 连接字符串: `ConnectionStrings__queues` (由Aspire设定)
### 表存储
- NoSQL实体存储
- CRUD操作
- 通过集成 `azure-data-tables` Python 软件开发工具包
- 连接字符串: `ConnectionStrings__tables` (由Aspire设定)
## Aspire CLI命令
### 创建新项目```bash
# Create a new Python Aspire project
aspire new aspire-py-starter --name MyProject --output ./MyProject
# Create just an AppHost
aspire new aspire-apphost-singlefile --name MyAppHost --output ./apphost
添加集成```bash
Add PostgreSQL
aspire add postgresql
Add Redis
aspire add redis
Add Azure Service Bus
aspire add azure-servicebus
### 运行和管理```bash
# Run in development mode
aspire run
# Run with debug output
aspire run --debug
# Initialize Aspire in existing solution
aspire init
发布(预览)```bash
Generate deployment artifacts
aspire publish
Deploy to Azure Container Apps (Preview)
aspire deploy
## Azure容器应用部署
### 使用Aspire CLI(推荐)
1. **使用Aspire CLI进行部署** (如果可用):```bash
cd PythonAspireSample
aspire deploy
使用Azure开发者命令行界面(azd)
- 初始化项目:```bash
azd init
1. **配置Azure资源:**```bash
azd provision
这将创建:
- Azure容器应用程序环境
- Azure容器注册表
- Azure存储帐户(带块、队列、表)
- 应用洞察
- 日志分析工作区
- 部署应用程序:```bash
azd deploy
1. **查看部署:**```bash
azd show
- 监控日志:```bash
azd monitor --logs
## 配置
### 环境变量
Python应用程序从Aspire自动配置的环境变量中读取Azure存储连接字符串:
- `ConnectionStrings__blobs` -Blob存储连接
- `ConnectionStrings__queues` -队列存储连接
- `ConnectionStrings__tables` -表存储连接
### Azurite的地方发展
对于没有Aspire的本地测试,您可以使用Azurite(Azure存储模拟器):```bash
# Install Azurite
npm install -g azurite
# Start Azurite
azurite --silent --location /tmp/azurite
# Connection strings for local emulator
export ConnectionStrings__blobs="UseDevelopmentStorage=true"
export ConnectionStrings__queues="UseDevelopmentStorage=true"
export ConnectionStrings__tables="UseDevelopmentStorage=true"
发展
安装Python依赖项```bash
cd PythonAspireSample/app
Using uv (recommended by Aspire)
uv pip install -e .
Or using pip
pip install -e .
### 安装前端依赖项```bash
cd PythonAspireSample/frontend
npm install
生产大楼```bash
Frontend
cd PythonAspireSample/frontend
npm run build
The build output will be served by the Python app in production
### Docker构建
手动构建容器:```bash
# Python app
cd PythonAspireSample/app
docker build -t python-aspire-app .
# Frontend (if needed separately)
cd PythonAspireSample/frontend
docker build -t python-aspire-frontend .
监测和可观察性
该项目包括综合可观测性:
- 开放遥测 分布式跟踪集成
- 结构化日志记录 转到Aspire仪表板
- 健康检查 用于服务监控
- 指标收集 用于性能分析
- Aspire仪表板 获取当地发展见解
- Azure应用洞察 (部署到Azure时)
- Azure监视器 整合
查看遥测数据
在Aspire仪表板中,您可以:
- 查看跨服务的请求跟踪
- 监控服务依赖关系
- 分析性能瓶颈
- 跟踪错误和异常
- 实时查看日志
故障排除
常见问题
- Aspire CLI需要。净值10:确保你有。NET SDK 10.0.100或更高版本已安装```bash
dotnet --version
1. **端口冲突**:Aspire动态分配端口。检查仪表板上的实际端口。
1. **存储连接错误**:
- 对于本地开发人员,确保Azurite正在运行
- 对于Azure,验证存储帐户连接字符串
1. **Python版本**:确保安装了Python 3.13+```bash
python --version
- Node.js版本:确保前端安装了Node 18+```bash
node --version
### 查看日志
**地方发展:**
- 使用Aspire仪表板在一个地方查看所有服务日志
- 访问地址:https://localhost:19888
**Azure部署:**
- Azure门户>容器应用>日志流
- `azd monitor --logs`
- 应用洞察>交易搜索
### 调试模式
使用调试输出运行:```bash
aspire run --debug
高级功能
单文件AppHost
此项目使用Aspire 13的新单文件AppHost格式(apphost.cs),它提供:
- 简化项目结构
- 不需要单独的.csproj文件
- 使用内联包引用
#:package指令 - 更易于理解和维护
UV包装管理器
Python应用程序使用 uv 为了实现快速的包管理:
- 明显快于pip
- 更好的依赖关系解决方案
- 与Aspire集成
容器文件发布
前端通过以下方式发布到Python应用程序的静态目录中:csharp
app.PublishWithContainerFiles(frontend, "./static");
这将创建一个包含前端和后端的单一容器。
贡献
欢迎投稿!此存储库是 GitHub复制品就绪 提供全面的指导,帮助您有效地做出贡献。
GitHub Copilot入门
此存储库包括:
- .github/copilot-instructions.md -项目特定副驾驶说明
- 贡献.md -详细的捐款指南
- .vcode/settings.json -针对Copilot优化的VS代码配置
- .编辑权 -跨编辑器的一致代码风格
GitHub Copilot将自动使用这些说明,根据此项目的模式和惯例提供更好的建议。
贡献步骤
- 分叉存储库
- 创建要素分支
- 进行更改(Copilot将帮助您提供上下文感知建议)
- 提交拉取请求
看 贡献.md 详细指南。
资源
文档
- 存储体系结构 -使用Azure存储服务的多租户存储设计
- 部署指导 -Azure容器应用部署
- 快速开始 -5分钟设置指南
- 贡献 -贡献指南
外部资源
- Aspire 13文档
- Aspire CLI概述
- Azure容器应用
- Azure存储Python SDK
- FastAPI文档
- Azure开发者命令行界面
许可证
这个项目是开源的,可以在MIT许可证下使用。
