Azure Functions 的基于包的部署

创建部署包

大多数情况下，你不需要自己创建部署包。 这些基于工具的部署方法将软件包作为发布过程的一部分创建：

• Azure Functions Core Tools func azure functionapp publish 命令。
• Visual Studio Code 发布功能。
• Visual Studio 发布。
• GitHub Actions 部署，它将配置好的项目路径打包。

当你需要直接使用可直接运行的部署包时，使用 func pack 创建该部署包。 例如，部署时使用 外部包 URL 自行创建包。

你也可以手动创建 .zip 档案。 手动创建归档时，请遵循这些包结构要求。

部署包需求

部署的 zip 存档必须包含运行函数应用所需的所有文件。 可以使用内置 .zip 压缩功能或非Microsoft工具从 Functions 项目文件夹的内容手动创建 zip 存档。

存档必须在提取文件夹的根目录中包含 host.json 文件。 函数应用的所选语言堆栈会创建其他要求：

• .NET（独立工作者模型）
• .NET（进程内模型）
• 爪哇岛
• JavaScript
• TypeScript
• PowerShell
• Python

Zip 部署过程会在 wwwroot 目录中提取 .zip 压缩包中的文件和文件夹。 如果你在创建归档时包含父目录，系统就找不到它期望看到的文件。wwwroot

部署程序包

高级、专用和消费套餐应用都使用zip部署API。 部署服务执行以下操作：

• 删除之前部署中剩余的文件。
• 运行部署脚本和其他部署自定义。
• 写部署日志。
• 同步功能触发。

使用 Azure CLI 进行部署

使用 Azure CLI 来触发推送部署。 使用 az functionapp deployment source config-zip 命令将 .zip 文件推送部署到函数应用。 要使用此命令，必须使用 Azure CLI 版本 2.0.21 或更高版本。 若要查看正在使用的 Azure CLI 版本，请使用 az --version 该命令。

以下命令将 <zip_file_path> 占位符替换为 .zip 文件的位置路径。 此外，请将 <app_name> 替换为函数应用的唯一名称，并将 <resource_group> 替换为资源组的名称。

az functionapp deployment source config-zip -g <resource_group> -n \
<app_name> --src <zip_file_path>

这个命令会把项目文件从 .zip 文件部署到你的函数应用Azure然后重启应用。

在本地计算机上使用 Azure CLI 时，<zip_file_path> 是计算机中 .zip 文件的路径。

使用 REST API 部署 ZIP 文件

可以使用部署服务 REST API 将 .zip 文件部署到 Azure 中的应用。 若要部署，请将 POST 请求发送到 https://<app_name>.scm.chinacloudsites.cn/api/zipdeploy。 POST 请求必须在消息正文中包含此 .zip 文件。 应用的部署凭据是通过使用 HTTP BASIC 身份验证在请求中提供的。 有关详细信息，请参阅 .zip 推送部署参考。

对于 HTTP 基本身份验证，需使用应用服务部署凭据。 若要了解如何设置部署凭据，请参阅设置和重置用户级别凭据。

使用 cURL

以下示例使用 cURL 工具部署 .zip 文件。 替换占位符 <deployment_user>、<zip_file_path> 和 <app_name>。 出现 cURL 提示时，键入密码。

curl -X POST -u <deployment_user> --data-binary "@<zip_file_path>" https://<app_name>.scm.chinacloudsites.cn/api/zipdeploy

此请求从已上传的 .zip 文件触发推送部署。 可以使用 https://<app_name>.scm.chinacloudsites.cn/api/deployments 终结点查看当前和之前的部署，如以下 cURL 示例所示。 再次，将 <app_name> 替换为您的应用名称，并将 <deployment_user> 替换为您的部署凭据用户名。

curl -u <deployment_user> https://<app_name>.scm.chinacloudsites.cn/api/deployments

异步 Zip 文件部署

同步部署时，可能会收到与连接超时相关的错误。 将 ?isAsync=true 添加到 URL 能够以异步方式进行部署。 一旦 zip 文件上传，就会收到 Location 响应，其中包含指向可轮询部署状态 URL 的标头。 轮询 Location 标头中提供的 URL 时，您会在过程进行中收到 HTTP 202（已接受）响应，而在归档展开且部署成功完成后收到 HTTP 200（正常）响应。

Microsoft Entra 身份验证

对 zip 部署使用 HTTP BASIC 身份验证的替代方法是使用 Microsoft Entra 标识。 如果 SCM 站点禁用 HTTP BASIC 身份验证，则可能需要Microsoft Entra 标识。

需要为执行部署的用户或服务主体提供有效的Microsoft Entra 访问令牌。 可以使用 Azure CLI 的 az account get-access-token 命令检索访问令牌。 访问令牌在 HTTP POST 请求的身份验证标头中使用。

curl -X POST \
    --data-binary "@<zip_file_path>" \
    -H "Authorization: Bearer <access_token>" \
    "https://<app_name>.scm.chinacloudsites.cn/api/zipdeploy"

使用 PowerShell

下面的示例使用 Publish-AzWebapp 上传 .zip 文件。 替换占位符 <group-name>、<app-name> 和 <zip-file-path>。

Publish-AzWebapp -ResourceGroupName <group-name> -Name <app-name> -ArchivePath <zip-file-path>

此请求从已上传的 .zip 文件触发推送部署。

若要查看当前和之前的部署，请运行以下命令。 再次替换 <deployment-user>、<deployment-password> 和 <app-name> 占位符。

$username = "<deployment-user>"
$password = "<deployment-password>"
$apiUrl = "https://<app-name>.scm.chinacloudsites.cn/api/deployments"
$base64AuthInfo = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(("{0}:{1}" -f $username, $password)))
$userAgent = "powershell/1.0"
Invoke-RestMethod -Uri $apiUrl -Headers @{Authorization=("Basic {0}" -f $base64AuthInfo)} -UserAgent $userAgent -Method GET

使用 Azure 资源管理器模板进行部署

你可以用Azure 资源管理器（ARM）模板的ZipDeploy扩展来推送你的 .zip 文件到函数应用。

示例 ZipDeploy ARM 模板

此模板包括生产槽和过渡槽，并部署到一个或另一个槽。 通常，你使用此模板将应用部署到预发布槽位，然后通过交换槽位，使新的 ZIP 包在生产槽位上运行。

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "appServiceName": {
      "type": "string"
    },
    "deployToProduction": {
      "type": "bool",
      "defaultValue": false
    },
    "slot": {
      "type": "string",
      "defaultValue": "staging"
    },
    "packageUri": {
      "type": "secureString"
    }
  },
  "resources": [
    {
      "condition": "[parameters('deployToProduction')]",
      "type": "Microsoft.Web/sites/extensions",
      "apiVersion": "2021-02-01",
      "name": "[format('{0}/ZipDeploy', parameters('appServiceName'))]",
      "properties": {
        "packageUri": "[parameters('packageUri')]",
        "appOffline": true
      }
    },
    {
      "condition": "[not(parameters('deployToProduction'))]",
      "type": "Microsoft.Web/sites/slots/extensions",
      "apiVersion": "2021-02-01",
      "name": "[format('{0}/{1}/ZipDeploy', parameters('appServiceName'), parameters('slot'))]",
      "properties": {
        "packageUri": "[parameters('packageUri')]",
        "appOffline": true
      }
    }
  ]
}

首次部署时，你将直接部署到生产槽位。 有关详细信息，请参阅槽部署。

从部署包中运行函数

直接从部署包运行时，可以跳过将文件复制到目录中的 wwwroot 过程。 相反，Functions 运行时将该包挂载为只读的 wwwroot 目录。 此方法：

• 减少文件复制锁的问题。
• 验证在应用中运行的文件。
• 提升 Azure 资源管理器 部署性能。
• 可以减少冷启动时间，尤其是对于拥有大型 npm 包树的 JavaScript 应用。

高级和专用套餐配置

将 WEBSITE_RUN_FROM_PACKAGE 设置为 1，以直接从本地部署的包运行。 运行时在 Windows 上将该软件包存储在文件夹中，在 /home/data/SitePackages Linux 上则存储在c:\home\data\SitePackages文件夹中。

消费包配置

支持 WEBSITE_RUN_FROM_PACKAGE 的值取决于操作系统：

包部署注意事项

使用包部署和运行函数应用时，请牢记以下要求和限制：

• 该软件包必须使用 .zip 格式。 不支持 TAR 和 GZIP 格式。
• 最大包装容量为1GB。 部署在解压项目文件时会使用临时存储，因此应用也必须有足够的临时存储。 消耗计划为每个计划提供 500 MB 的临时存储空间。
• 当你从包运行时，wwwroot 中的文件均为只读，包括在 Azure 门户中也是如此。
• 你不能在从包里运行时使用本地缓存。
• 请求远程构建时，不要设置 WEBSITE_RUN_FROM_PACKAGE。 而是设置 SCM_DO_BUILD_DURING_DEPLOYMENT=true。 在Linux上，同样设置为 ENABLE_ORYX_BUILD=true。
• WEBSITE_RUN_FROM_PACKAGE 无法与 MSDeploy 配合使用。 改用压缩包部署。

添加 WEBSITE_RUN_FROM_PACKAGE 设置

可以通过以下几种方法添加、更新和删除函数应用设置：

• 在 Azure 门户中
• 使用 Azure CLI
• 使用 Azure PowerShell

如果更改函数应用设置，则需要重启函数应用。

从通过 ZIP 部署上传的包中运行

在部署该包之前，将 WEBSITE_RUN_FROM_PACKAGE 设置为 1。 ZIP 部署 API 会将包复制到 SitePackages 文件夹，而不是将其内容解压到 wwwroot。 部署还会创建一个 packagename.txt 文件，用于识别要挂载的包。 应用重启后，包会被挂载为只读 wwwroot 目录。 Linux Consumption 应用程序不支持此设置值，必须改为 从外部包 URL 运行。

当部署重启应用时，当前正在运行的函数执行会终止。 关于如何编写能够安全处理重启的函数，请参见 “写函数为无状态”。

从外部包URL运行

当您需要自行管理软件包存储时，请使用外部软件包 URL。 你需要这个选项才能在 Linux Consumption 应用上运行本地开发的包。 Flex Consumption 不支持此功能。

使用私有的 Blob 存储 容器，并赋予函数应用对包的管理身份访问权。 使用托管身份，因为SAS令牌会过期并需要维护。 每当你发布更新包时，必须 手动同步触发器。 如果你直接更新该包而不更改其 URL，请先重启函数应用，再同步触发器。

手动上传一个包到 Azure Blob 存储

1. 创建一个 .zip 部署包。

2. 在 Azure 门户中，转到您的存储帐户。

3. 在 数据存储中，选择 容器，然后创建或选择一个私有容器。

4. 把包裹上传到集装箱。

5. 选择上传的blob并复制其URL。 如果你不使用托管身份，可以生成一个 SAS URL。

6. 在你的功能应用中，展开设置，选择环境变量，然后在应用设置标签页选择添加。

7. 添加一个名为 WEBSITE_RUN_FROM_PACKAGE 的设置，并将包 URL 作为其值。

8. 应用这些更改，重启应用，然后手动同步触发器。

使用托管标识从 Azure Blob 存储获取包

可以将 Azure Blob 存储 配置为使用 Microsoft Entra ID 授权请求。 此配置意味着可以依赖应用程序的托管标识，而不是生成会过期的 SAS 密钥。 默认情况下，将使用应用的系统分配的标识。 如果要指定用户分配的身份，可以将应用设置WEBSITE_RUN_FROM_PACKAGE_BLOB_MI_RESOURCE_ID设为该身份的资源ID。 该设置还可以接受 SystemAssigned 作为值，该值等效于将该设置省略。

要启用通过标识获取包的功能，请运行以下操作：

1. 确保 Blob 已配置为私有访问。

2. 向标识授予存储 Blob 数据读取器角色，其范围为包 blob。 有关创建角色分配的详细信息，请参阅 分配 Azure 角色以访问 Blob 数据。

3. 将WEBSITE_RUN_FROM_PACKAGE的程序设置设为包的blob URL。 此 URL 通常采用 https://{storage-account-name}.blob.core.chinacloudapi.cn/{container-name}/{path-to-package} 或类似形式。

4. 如果要指定用户分配的身份，可以将应用设置WEBSITE_RUN_FROM_PACKAGE_BLOB_MI_RESOURCE_ID设为该身份的资源ID。 该设置还可以接受“SystemAssigned”作为值，尽管这与完全省略该设置是一样的。 资源 ID 是 Azure 中资源的标准表示形式。 对于用户分配的托管标识，这将是 /subscriptions/subid/resourcegroups/rg-name/providers/Microsoft.ManagedIdentity/userAssignedIdentities/identity-name。 可以在“设置”-“属性”->“用户分配的托管标识的 ID”中获取用户分配的托管标识的资源 ID>。

部署定制化

部署过程假设推送的 .zip 文件包含随时可运行的应用。 默认情况下，不会运行自定义。 若要启用通过持续集成获取的同一生成进程，请将以下内容添加到应用程序设置：

SCM_DO_BUILD_DURING_DEPLOYMENT=true

使用 .zip 推送部署时，此设置默认为“false”。 持续集成部署的设置默认为“true”。 当设置为“true”时，将使用您的部署相关设置进行部署。 可以将这些设置配置为应用设置或在位于 .zip 文件根目录中的 .deployment 配置文件中进行配置。 有关详细信息，请参阅部署参考中的 Repository and deployment-related settings（存储库和与部署相关的设置）。

下载您的函数应用文件

如果使用 Azure 门户中的编辑器创建了函数，则可以通过以下方式之一将现有函数应用项目下载为 .zip 文件：

https://<FUNCTION_APP>.scm.chinacloudsites.cn/api/zip/site/wwwroot/

对于通过CI/CD部署的应用，应将源项目保留在源代码管理中，并根据你的发布保留策略保留现成的构建工件。 从仓库下载的源代码归档不是部署包。 使用你的部署工作流程来构建和部署项目。