如何在 Azure 中托管工作负荷

本文介绍如何使用仅限前端的体系结构在 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

部署脚本参数

部署脚本功能

部署脚本提供全面的部署功能：

验证和安全

• 先决条件检查：验证 Azure CLI 安装和身份验证
• 资源验证：确认目标 Web 应用存在且可访问
• 生成验证：确保发布目录包含所需的文件
• 备份创建：为回滚功能创建部署备份

部署工作流

• ZIP 包创建：将内置应用程序压缩到部署包中
• 大小报告：显示用于验证的部署包大小
• 进度监视：提供实时部署状态更新
• 错误处理：包含故障排除指南的详细错误消息

后期部署

• 运行状况检查：验证部署的应用程序是否正确响应
• URL 报告：提供指向已部署应用程序的直接链接
• 清单指南：显示清单上传到 Fabric 的后续步骤
• 计时指标：报告总部署持续时间

手动部署

还可以使用 Azure PowerShell 命令手动部署前端应用程序：

生成应用程序

首先，为测试环境生成前端应用程序：

npm run build:test

创建部署包

1. 导航到项目中的 build\Frontend 文件夹
2. 选择生成目录下的所有文件以及assets文件夹
3. 创建一个包含所有选定文件的.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>

手动部署参数

安全注意事项

身份验证流

工作负载使用标准 OAuth 2.0 流程向 Fabric 进行身份验证：

1. 用户通过 Fabric 访问工作负荷
2. Fabric 重定向到 Azure 托管的应用程序
3. 应用重定向到 Entra ID 进行身份验证
4. Entra ID 返回身份验证令牌
5. 应用使用令牌访问 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 管理门户

1. 打开 Microsoft Fabric 管理门户
2. 导航到 工作负荷管理>上传工作负荷
3. 上传您的ManifestPackage.1.0.0.nupkg文件
4. 配置工作负荷设置和权限
5. 激活租户的工作负荷

更新 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
• 设置指南 - 初始开发环境设置
• 教程：入门 - 扩展性工具包入门