本文介绍如何使用仅限前端的体系结构在 Azure 中托管 Fabric Extensibility Toolkit 工作负载。 Extensibility Toolkit 将云原生部署方法与针对静态 Web 应用程序优化的 Azure 服务配合使用。
体系结构概述
Fabric 扩展性工具包使用一个侧重于前端部署的体系结构和 Azure 服务：
扩展性工具包体系结构
Extensibility Toolkit 体系结构包括以下特征：
- 仅限前端的部署：工作负荷完全在浏览器中运行，无需单独的后端
- 静态网站托管：使用 Azure 存储静态网站进行托管
- Azure Front Door：提供全局 CDN、SSL 终止和路由
- 托管服务：利用 Entra ID、Key Vault 和托管标识实现安全性
- 单一部署过程：使用提供的 PowerShell 脚本进行部署
使用的 Azure 服务
Azure Front Door
Azure Front Door 充当工作负荷的全局入口点。 它提供：
- 全局负载均衡：将用户路由到最近的边缘位置
- SSL 终止：自动处理 HTTPS 证书
- Web 应用程序防火墙（WAF）：防范常见 Web 漏洞
- 缓存：通过在边缘位置缓存静态资产来提高性能
对于扩展性工具包，Front Door 将流量路由到托管在 Azure 存储上的静态网站，确保全球范围内的高可用性和低延迟。
Azure 存储帐户（静态网站）
一个包含静态网站托管的 Azure 存储帐户用于托管您的已构建的工作负载应用程序。 这提供：
- 经济高效的托管：仅支付使用的存储和带宽费用
- 自动缩放：在不配置的情况下处理流量高峰
- 全局可用性：从 Azure 的全局存储基础结构提供内容
- 基于文件的部署：上传文件以部署版本
Extensibility Toolkit 将 React 应用程序构建为静态的 HTML、JavaScript、CSS 和资源，这些资源将直接部署到存储帐户。
Azure Key Vault
Azure Key Vault 管理敏感配置和机密：
- 客户端机密：安全地存储 Entra ID 应用程序机密
- API 密钥：管理外部服务 API 密钥
- 配置：存储特定于环境的设置
- 证书：根据需要管理 SSL 证书
工作负载通过托管标识访问 Key Vault，进行安全且无需凭据的身份验证。
Azure Entra ID （Azure Active Directory）
Azure Entra ID 提供身份验证和授权：
- 应用注册：将工作负荷注册为 Entra 应用程序
- OAuth 2.0 流：使用 Fabric 处理用户身份验证
- API 权限：管理对 Fabric 和 Microsoft 图形 API 的访问权限
- 令牌管理：为 API 调用提供安全访问令牌
托管身份
托管标识 提供安全的服务间认证：
- 无凭据管理：无需在代码中存储机密
- 令牌处理：Azure 处理令牌获取和续订
- 安全访问：安全地连接到 Key Vault 和其他 Azure 服务
- 标识生命周期：关联至 Azure 资源以便清理
部署过程
先决条件
在部署到 Azure 之前，请确保具备：
- 具有适当权限的 Azure 订阅
- 已安装并经过身份验证的 Azure CLI
- 在本地克隆的 Fabric 扩展性工具包存储库
- 使用
.\scripts\Build\BuildRelease.ps1构建的工作负载
使用部署脚本
Extensibility Toolkit 包括一个 PowerShell 部署脚本 scripts\Deploy\DeployToAzureWebApp.ps1 ，用于自动执行部署过程。
基本部署
# Deploy to an existing Azure Web App
.\scripts\Deploy\DeployToAzureWebApp.ps1 -WebAppName "my-fabric-workload" -ResourceGroupName "fabric-workload-rg"
其他部署选项
# Deploy to staging slot with custom settings
.\scripts\Deploy\DeployToAzureWebApp.ps1 `
-WebAppName "my-fabric-workload" `
-ResourceGroupName "fabric-workload-rg" `
-SlotName "staging" `
-Force $true `
-CreateBackup $true `
-RestartAfterDeploy $true
部署脚本参数
| 参数 | Description | 必选 | 违约 |
|---|---|---|---|
WebAppName |
要部署到的 Azure Web 应用的名称 | 是的 | - |
ResourceGroupName |
包含 Web 应用的资源组 | 是的 | - |
ReleasePath |
生成应用程序文件的路径 | 否 | ..\..\release\app |
DeploymentMethod |
部署方法（ZipDeploy、FTP、LocalGit） | 否 | ZipDeploy |
SlotName |
过渡的部署槽位 | 否 | - |
Force |
跳过确认提示 | 否 | $false |
CreateBackup |
在部署之前创建备份 | 否 | $true |
RestartAfterDeploy |
部署后重启应用 | 否 | $true |
部署脚本功能
部署脚本提供全面的部署功能：
验证和安全
- 先决条件检查：验证 Azure CLI 安装和身份验证
- 资源验证：确认目标 Web 应用存在且可访问
- 生成验证：确保发布目录包含所需的文件
- 备份创建：为回滚功能创建部署备份
部署工作流
- ZIP 包创建：将内置应用程序压缩到部署包中
- 大小报告：显示用于验证的部署包大小
- 进度监视：提供实时部署状态更新
- 错误处理：包含故障排除指南的详细错误消息
后期部署
- 运行状况检查：验证部署的应用程序是否正确响应
- URL 报告：提供指向已部署应用程序的直接链接
- 清单指南：显示清单上传到 Fabric 的后续步骤
- 计时指标：报告总部署持续时间
手动部署
还可以使用 Azure PowerShell 命令手动部署前端应用程序：
生成应用程序
首先，为测试环境生成前端应用程序：
npm run build:test
创建部署包
- 导航到项目中的
build\Frontend文件夹 - 选择生成目录下的所有文件以及
assets文件夹 - 创建一个包含所有选定文件的
.zip文件
使用 Azure PowerShell 进行部署
# Connect to Azure
Connect-AzAccount
# Set your subscription context
Set-AzContext -Subscription "<subscription_id>"
# Deploy the zip file to your web app
Publish-AzWebApp -ResourceGroupName <resource_group_name> -Name <web_app_name> -ArchivePath <zip_file_path>
手动部署参数
| 参数 | Description | Example |
|---|---|---|
<subscription_id> |
Azure 订阅 ID | 12345678-1234-1234-1234-123456789012 |
<resource_group_name> |
包含 Web 应用的资源组 | fabric-workload-rg |
<web_app_name> |
Azure Web 应用的名称 | my-fabric-workload |
<zip_file_path> |
部署 zip 文件的完整路径 | C:\path\to\deployment.zip |
注释
手动部署要求你拥有相应的 Azure 权限和计算机上安装的 Azure PowerShell 模块 。
安全注意事项
身份验证流
工作负载使用标准 OAuth 2.0 流程向 Fabric 进行身份验证：
- 用户通过 Fabric 访问工作负荷
- Fabric 重定向到 Azure 托管的应用程序
- 应用重定向到 Entra ID 进行身份验证
- Entra ID 返回身份验证令牌
- 应用使用令牌访问 Fabric API
安全配置
- 环境变量：在 Azure 应用设置中存储配置，而不是在代码中存储配置
- Key Vault 集成：通过托管标识访问机密
- 仅限 HTTPS：对所有通信强制实施 HTTPS
- CORS 配置：为 Fabric 域配置适当的 CORS 策略
最佳做法
- 最低权限：向托管标识授予最低所需权限
- 机密轮换：定期轮换存储在 Key Vault 中的机密
- 网络安全：尽可能使用专用终结点
- 监视：启用 Application Insights 以实现安全监视
部署后的配置
Azure 应用服务配置
部署后，配置 Azure 应用服务：
# Set environment variables for your workload
az webapp config appsettings set --name "my-fabric-workload" --resource-group "fabric-workload-rg" --settings \
"FABRIC_CLIENT_ID=your-client-id" \
"FABRIC_TENANT_ID=your-tenant-id" \
"KEY_VAULT_URL=https://your-keyvault.vault.azure.net/"
Key Vault 设置
在 Key Vault 中存储敏感配置：
# Store client secret
az keyvault secret set --vault-name "your-keyvault" --name "FabricClientSecret" --value "your-client-secret"
# Store API keys
az keyvault secret set --vault-name "your-keyvault" --name "ExternalApiKey" --value "your-api-key"
托管身份配置
为 Key Vault 访问配置托管标识：
# Enable system-assigned managed identity
az webapp identity assign --name "my-fabric-workload" --resource-group "fabric-workload-rg"
# Grant access to Key Vault
az keyvault set-policy --name "your-keyvault" \
--object-id "managed-identity-principal-id" \
--secret-permissions get list
清单部署
将应用程序部署到 Azure 后，必须将清单包上传到 Fabric：
生成清单包
首先，生成清单包：
.\scripts\Build\BuildManifestPackage.ps1
这会创建一个包含工作负荷清单的release\ManifestPackage.1.0.0.nupkg。
上传到 Fabric 管理门户
- 打开 Microsoft Fabric 管理门户
- 导航到 工作负荷管理>上传工作负荷
- 上传您的
ManifestPackage.1.0.0.nupkg文件 - 配置工作负荷设置和权限
- 激活租户的工作负荷
更新 Azure 部署的清单文件
确保您的 Product.json 清单引用您在 Azure 部署的应用程序。
{
"name": "Product",
"displayName": "Your_Workload_Name",
"frontend": {
"path": "https://your-workload.azurewebsites.net"
}
}
监视和故障排除
Application Insights
启用 Application Insights 进行监视：
- 性能监视：跟踪页面加载时间和用户交互
- 错误跟踪：监视 JavaScript 错误和失败的请求
- 使用情况分析：了解用户如何与工作负荷交互
- 自定义遥测：为业务逻辑添加自定义指标
常见问题和解决方案
部署失败
-
身份验证错误：验证 Azure CLI 登录
az account show - 找不到资源：确认 Web 应用名称和资源组正确
- 权限被拒绝：确保帐户对资源组具有“贡献者”角色
运行时问题
- 白屏：检查浏览器控制台是否存在 JavaScript 错误
- 身份验证失败：验证 Entra ID 应用注册和重定向 URI
- API 调用失败：检查 CORS 配置和 API 权限
性能优化
- 加载速度缓慢：启用压缩并优化捆绑包大小
- 缓存问题：在 Front Door 中配置正确的缓存标头
- 地理延迟：确保为全局路由正确配置 Front Door
相关指南
- 如何发布和管理工作负荷 - 将清单上传到 Fabric
- 设置指南 - 初始开发环境设置
- 教程：入门 - 扩展性工具包入门