WebJobs 如何在 Azure 应用服务中运行

2025-08-29

Azure WebJobs 允许在应用服务应用中运行后台任务，而无需单独的基础结构。这些任务由 Kudu 引擎、内置应用服务部署和运行时管理服务发现和管理。 Kudu 在后台处理 WebJob 执行、文件系统访问、诊断和日志收集。

本文介绍如何发现 WebJobs、运行时如何决定执行什么，以及如何使用可选 settings.job 文件配置行为。

特定于平台的注释

WebJobs 支持各种脚本和可执行格式，具体取决于应用服务托管环境。可以运行的文件类型和可用的运行时因使用的是 Windows 代码、Linux 代码还是自定义容器而略有不同。通常，内置运行时可用于常见脚本语言，并且当它们与应用或容器的语言运行时匹配时，支持其他文件类型。

支持的脚本或程序文件类型

重要

基于 Alpine Linux 的自定义 Linux 容器不支持 WebJobs，包括使用 Java 8 和 Java 11 运行时堆栈的 Linux 应用。从 Java 17 Linux 应用开始，Azure 应用服务使用与 WebJobs 兼容的非 Alpine 映像。

支持以下文件类型：

使用 Windows cmd： .cmd、 .bat、 .exe
使用 PowerShell：.ps1
使用 Bash：.sh
使用 Node.js：.js
使用 Java：.jar

运行这些文件类型所需的运行时已安装在 Web 应用实例上。

重要

如果托管它们的 Web 应用处于空闲状态，则连续、计划或事件驱动的 WebJobs 可能会停止运行。 Web 应用可在进入非活动状态 20 分钟后超时，只有‌直接向应用发起的请求才会重置此空闲计时器。查看门户或访问 Kudu 工具等操作不会使应用保持活跃状态。若要确保 WebJobs 可靠运行，请在应用服务的“配置”窗格中启用 Always on 设置。此设置仅在基本、标准和高级定价层中可用。

作业发现和文件夹结构

WebJobs 存储在 site/wwwroot/App_Data/jobs/ 应用服务应用的文件夹中。有两个子文件夹：

continuous/：用于自动启动并连续运行的长时间运行任务。
triggered/：用于按需或按计划运行的作业。

每个作业在相应的类型下都有自己的子文件夹，以 WebJob 命名。例如：

App_Data/jobs/triggered/myjob/
App_Data/jobs/continuous/myjob/

在作业文件夹中，Kudu 引擎查找要执行的文件。此文件可以是脚本或可执行文件。

入口点检测

WebJobs 运行时使用名为 run.* （例如 run.py， run.sh或 run.js）的文件作为作业的显式入口点。此文件告知平台要首先执行哪个脚本或二进制文件，确保跨环境的行为一致且可预测的行为。

文件名必须精确为run.*才能自动检测。除非手动触发，否则类似 start.sh 或 job.py 的文件将被忽略。 run.*如果未找到文件，则平台会尝试根据 WebJob 的语言平台选择第一个受支持的文件来检测回退入口点。例如：

包含多个 .py 文件的 Python WebJob（例如，file1.py，file2.py）将执行它在存档中找到的第一个 .py 文件。
Node.js WebJob 查找第一个 .js 文件。
基于 Bash 的 WebJob 查找第一个 .sh 脚本。

当存在多个脚本文件（尤其是在多文件项目中）时，这种回退行为可能会导致不可预知的执行，因此建议包含一个 run.* 文件来显式定义入口点。

在基于 Linux 的 WebJobs 上，.sh 脚本必须包含 shebang (#!)，并且必须标记为可执行文件。

使用“settings.job”进行的 WebJob 配置

可以使用放置在作业根文件夹中的可选 settings.job 文件（JSON 格式）自定义 WebJob 行为。此文件支持多个属性：

资产	DESCRIPTION
`schedule`	（字符串）用于计划触发的作业的 CRON 表达式。示例：`"0 /15 * * *"`。仅适用于触发的作业。
`is_singleton`	（布尔）确保只有一个作业实例在所有横向扩展实例上运行。默认值： `true` 对于连续作业， `false` 对于触发/按需作业。
`stopping_wait_time`	（数字，秒）在 WebJob 停止时（如网站切换或重启期间），系统将在终止脚本之前给予一个宽限期（默认为 5秒）。
`shutdownGraceTimeLimit`	（数字，秒）为整个 WebJob 进程关闭（包括 `stopping_wait_time`强制终止之前）提供的最大时间（默认值 0，即没有限制）。
`run_mode`	（字符串）值：`continuous`、、`scheduledon_demand`. 基于文件夹替代作业类型检测。

注释

stopping_wait_time 适用于运行脚本的宽限期，而 shutdownGraceTimeLimit 定义了整个进程关闭的超时时间。有关详细行为，请参阅 Kudu 文档。

示例：

{
  "schedule": "0 0 * * * *", // Run once at the top of every hour
  "is_singleton": true,
  "stopping_wait_time": 60,
  "shutdownGraceTimeLimit": 120
}

日志记录和诊断

WebJob 日志由 Kudu 引擎处理，并可在 App_Data/jobs/<type>/<jobname> 文件夹下找到。此外，可以在 Azure 门户中查看日志，也可以通过 SCM （Kudu）终结点进行访问：

https://<your-app>.scm.chinacloudsites.cn/api/triggeredwebjobs/<job>/history

有关更高级的监视和查询功能，请考虑与 Application Insights 集成。

触发的 WebJobs 包含完整的执行历史记录。持续型 WebJobs‌ 会‌实时流式传输日志。

故障排除提示

WebJob 未启动： 检查是否存在缺失或未命名 run.* 的文件。确保它位于正确的作业文件夹中（triggered 或 continuous）。
权限错误 (Linux)：确保脚本具有执行权限 (chmod +x run.sh) 并包括有效的 shebang（例如：#!/bin/bash）。
作业未正常停止：使用 settings.job 来定义 stopping_wait_time，并可能 shutdownGraceTimeLimit。
计划作业未运行： 验证 CRON 表达式 settings.job 是否正确，并在需要时启用应用服务计划的“Always On”功能。
检查 Kudu 日志：在“工具 https://<your-app>.scm.chinacloudsites.cn/ Web 作业”下检查 Kudu 控制台（>）中可用的详细执行日志和部署日志，并检查潜在的日志流。

通过