从本地 Git 部署到 Azure 应用服务Local Git Deployment to Azure App Service

本操作方法指南说明如何将代码从本地计算机上的 Git 存储库部署到 Azure 应用服务This how-to guide shows you how to deploy your code to Azure App Service from a Git repository on your local computer.

如果没有 Azure 订阅,可在开始前创建一个试用帐户If you don't have an Azure subscription, create a trial account before you begin.

先决条件Prerequisites

按照本操作方法指南中的步骤操作:To follow the steps in this how-to guide:

  • 安装 GitInstall Git.
  • 使用想要部署的代码维护本地 Git 存储库。Maintain a local Git repository with code you want to deploy.

要遵循示例存储库操作,请在本地终端窗口运行以下命令:To use a sample repository to follow along, run the following command in your local terminal window:

git clone https://github.com/Azure-Samples/nodejs-docs-hello-world.git

准备存储库Prepare your repository

若要从 Azure 应用服务 Kudu 生成服务器获取自动生成,请确保项目中存储库根路径具有正确的文件。To get automatic builds from the Azure App Service Kudu build server, make sure that your repository root has the correct files in your project.

运行时Runtime 根目录文件Root directory files
ASP.NET(仅限 Windows)ASP.NET (Windows only) *.sln*.csprojdefault.aspx*.sln, *.csproj, or default.aspx
ASP.NET CoreASP.NET Core *.sln*.csproj*.sln or *.csproj
PHPPHP index.phpindex.php
Ruby(仅限 Linux)Ruby (Linux only) GemfileGemfile
Node.jsNode.js server.js、app.js 或具有启动脚本的 package.jsonserver.js, app.js, or package.json with a start script
Python(仅限 Windows)Python (Windows only) *.pyrequirements.txtruntime.txt*.py, requirements.txt, or runtime.txt
HTMLHTML default.htm、default.html、default.asp、index.htm、index.html 或 iisstart.htmdefault.htm, default.html, default.asp, index.htm, index.html, or iisstart.htm
Web 作业WebJobs App_Data/jobs/continuous(适用于连续的 WebJobs)或 App_Data/jobs/triggered(适用于触发的 WebJobs)下的 <job_name>/run.<extension>。<job_name>/run.<extension> under App_Data/jobs/continuous (for continuous WebJobs) or App_Data/jobs/triggered (for triggered WebJobs). 有关详细信息,请参阅 Kudu WebJobs 文档For more information, see Kudu WebJobs documentation.
函数Functions 请参阅 Azure Functions 的连续部署See Continuous deployment for Azure Functions.

要自定义部署,可以在存储库根路径中添加 .deployment 文件。To customize your deployment, include a .deployment file in the repository root. 有关详细信息,请参阅自定义部署自定义部署脚本For more information, see Customize deployments and Custom deployment script.

Note

如果在 Visual Studio 中进行开发,让 Visual Studio 创建存储库If you develop in Visual Studio, let Visual Studio create a repository for you. 该项目可立即通过 Git 进行部署。The project is immediately ready to be deployed by using Git.

通过 Kudu 生成从本地 Git 部署Deploy from local Git with Kudu builds

使用 Kudu 生成服务器为应用启用本地 Git 部署的最简单方法是使用命令外壳。The easiest way to enable local Git deployment for your app with the Kudu build server is to use command shell.

配置部署用户Configure a deployment user

使用 az webapp deployment user set 命令配置部署凭据。Configure deployment credentials with the az webapp deployment user set command. 对 Web 应用进行 FTP 和本地 Git 部署时需要此部署用户。This deployment user is required for FTP and local Git deployment to a web app. 用户名和密码都为帐户级别。The user name and password are account level. 它们与 Azure 订阅凭据不同。They are different from your Azure subscription credentials.

在以下示例中,将 <username><password>(包括括号)替换为新的用户名和密码。In the following example, replace <username> and <password> (including brackets) with a new user name and password. 用户名在 Azure 中必须唯一。The user name must be unique within Azure. 密码长度必须至少为 8 个字符,其中包含以下 3 种元素中的两种:字母、数字、符号。The password must be at least eight characters long, with two of the following three elements: letters, numbers, symbols.

az webapp deployment user set --user-name <username> --password <password>

命令执行完成后你会获得一个 JSON 输出,密码显示为 nullYou should get a JSON output, with the password shown as null. 如果收到 'Conflict'. Details: 409 错误,请更改用户名。If you get a 'Conflict'. Details: 409 error, change the username. 如果收到 'Bad Request'. Details: 400 错误,请使用更强的密码。If you get a 'Bad Request'. Details: 400 error, use a stronger password.

只需配置此部署用户一次;之后可对所有 Azure 部署使用此用户。You need to configure this deployment user only once; you can use it for all your Azure deployments.

Note

记录用户名和密码。Record the user name and password. 稍后需要使用它们来部署 Web 应用。You need them to deploy the web app later.

使用 Kudu 启用本地 GitEnable local Git with Kudu

若要使用 Kudu 生成服务器为应用启用本地 Git 部署,请运行 az webapp deployment source config-local-gitTo enable local Git deployment for your app with the Kudu build server, run az webapp deployment source config-local-git.

az webapp deployment source config-local-git --name <app_name> --resource-group <group_name>

要创建启用 Git 的应用,请结合 --deployment-local-git 参数运行 az webapp createTo create a Git-enabled app instead, run az webapp create with the --deployment-local-git parameter.

az webapp create --name <app_name> --resource-group <group_name> --plan <plan_name> --deployment-local-git

az webapp create 命令的输出应如下所示:The az webapp create command should give you something similar to the following output:

Local git is configured with url of 'https://<username>@<app_name>.scm.chinacloudsites.cn/<app_name>.git'
{
  "availabilityState": "Normal",
  "clientAffinityEnabled": true,
  "clientCertEnabled": false,
  "cloningInfo": null,
  "containerSize": 0,
  "dailyMemoryTimeQuota": 0,
  "defaultHostName": "<app_name>.chinacloudsites.cn",
  "deploymentLocalGitUrl": "https://<username>@<app_name>.scm.chinacloudsites.cn/<app_name>.git",
  "enabled": true,
  < JSON data removed for brevity. >
}

部署项目Deploy your project

回到本地终端窗口,将 Azure 远程功能添加到本地 Git 存储库。Back in the local terminal window, add an Azure remote to your local Git repository. 使用从启用应用的 Git中获取的 Git 远程 URL 替换 <url>。Replace <url> with the URL of the Git remote that you got from Enable Git for your app.

git remote add azure <url>

使用以下命令推送到 Azure 远程功能以部署应用。Push to the Azure remote to deploy your app with the following command. 提示输入密码时,请确保输入在配置部署用户中创建的密码,而不是用于登录到 Azure 门户的密码。When prompted for a password, make sure that you enter the password you created in Configure a deployment user, not the password you use to log in to the Azure portal.

git push azure master

在输出中可能会看到特定于运行时的自动化,如 MSBuild for ASP.NET、npm install for Node.js 和 pip install for Python。You may see runtime-specific automation in the output, such as MSBuild for ASP.NET, npm install for Node.js, and pip install for Python.

浏览到应用以验证内容已部署。Browse to your app to verify that the content is deployed.

使用 Azure DevOps Services 内部版本从本地 Git 进行部署Deploy from local Git with Azure DevOps Services builds

Note

要让应用服务在 Azure DevOps Services 组织中创建必要的 Azure 管道,Azure 帐户必须在 Azure 订阅中具有“所有者”角色。For App Service to create the necessary Azure Pipelines in your Azure DevOps Services organization, your Azure account must have the role of Owner in your Azure subscription.

若要使用 Kudu 生成服务器为应用启用本地 Git 部署,请在 Azure 门户中导航至应用。To enable local Git deployment for your app with the Kudu build server, navigate to your app in the Azure portal.

在应用页的左侧导航栏中,单击“部署中心” > “本地 Git” > “继续”。In the left navigation of your app page, click Deployment Center > Local Git > Continue.

单击“Azure DevOps Services 持续交付” > “继续”。Click Azure DevOps Services Continuous Delivery > Continue.

在“配置”页中,配置新的 Azure DevOps Services 组织,或指定现有组织。In the Configure page, configure a new Azure DevOps Services organization, or specify an existing organization. 完成后,单击“继续”。When finished, click Continue.

Note

如果要使用未列出的现有 Azure DevOps Services 组织,则需要将 Azure DevOps Services 组织链接到 Azure 订阅If you want to use an existing Azure DevOps Services organization that is not listed, you need to link the Azure DevOps Services organization to your Azure subscription.

在“测试”页面中,选择是否要启用负载测试,然后单击“继续”。In the Test page, choose whether to enable load tests, then click Continue.

根据应用服务计划的定价层,可能还会看到“部署到过渡环境”页。Depending on the pricing tier of your App Service plan, you may also see a Deploy to staging page. 选择是否要启用部署槽位,然后单击“继续”。Choose whether to enable deployment slots, then click Continue.

在“摘要”页中,确认选项,然后单击“完成”。In the Summary page, verify your options and click Finish.

Azure DevOps Services 组织需要几分钟才能准备就绪。It takes a few minutes for the Azure DevOps Services organization to be ready. 准备就绪后,在部署中心复制 Git 存储库 URL。When it's ready, copy the Git repository URL in the deployment center.

回到本地终端窗口,将 Azure 远程功能添加到本地 Git 存储库。Back in the local terminal window, add an Azure remote to your local Git repository. <url> 替换为从上一步获得的 URL。Replace <url> with the URL you got from the last step.

git remote add vsts <url>

使用以下命令推送到 Azure 远程功能以部署应用。Push to the Azure remote to deploy your app with the following command. 当 Git 凭据管理器提示时,请使用 visualstudio.com 用户登录。When prompted by Git Credential Manager, sign in with your visualstudio.com user. 有关其他身份验证方法,请参阅 Azure DevOps Services 身份验证概述For additional authentication methods, see Azure DevOps Services authentication overview.

git push vsts master

部署完成后,可以在 https://<vsts_account>.visualstudio.com/<project_name>/_build 中找到构建进度,并在 https://<vsts_account>.visualstudio.com/<project_name>/_release 中找到部署进度。Once deployment is finished, you can find the build progress at https://<vsts_account>.visualstudio.com/<project_name>/_build and the deployment progress at https://<vsts_account>.visualstudio.com/<project_name>/_release.

浏览到应用以验证内容已部署。Browse to your app to verify that the content is deployed.

部署期间我的应用会发生什么情况?What happens to my app during deployment?

所有官方支持的部署方法均具有一个共同点:它们会更改应用的 /home/site/wwwroot 文件夹中的文件。All the officially supported deployment methods have one thing in common: they make changes to the files in the /home/site/wwwroot folder of your app. 这些文件与生产中运行的文件相同。These are the same files that are run in production. 因此,部署可能由于存在锁定文件而失败,或者由于并非所有文件同时更新,生产中的应用在部署期间可能出现不可预测的行为。Therefore, the deployment can fail due to locked files, or the app in production may have unpredictable behavior during deployment because not all the files are updated simultaneously. 可通过多种不同方式避免这些问题:There are a few different ways to avoid these issues:

排查 Kudu 部署问题Troubleshooting Kudu deployment

以下是使用 Git 发布到 Azure 中的应用服务应用时遇到的常见错误或问题:The following are common errors or problems when using Git to publish to an App Service app in Azure:


症状Unable to access '[siteURL]': Failed to connect to [scmAddress]Symptom: Unable to access '[siteURL]': Failed to connect to [scmAddress]

原因:如果应用无法启动和运行,则会发生该错误。Cause: This error can happen if the app isn't up and running.

解决方法:在 Azure 门户中启动应用。Resolution: Start the app in the Azure portal. 如果 Web 应用停止时,Git 部署将不可用。Git deployment is unavailable when the Web App is stopped.


症状Couldn't resolve host 'hostname'Symptom: Couldn't resolve host 'hostname'

原因:如果创建“azure”远程网站时输入的地址信息不正确,则会发生该错误。Cause: This error can happen if the address information entered when creating the 'azure' remote was incorrect.

解决方法:使用 git remote -v 命令列出所有远程网站以及关联的 URL。Resolution: Use the git remote -v command to list all remotes, along with the associated URL. 确认“azure”远程网站的 URL 正确。Verify that the URL for the 'azure' remote is correct. 如果需要,请删除此远程网站并使用正确的 URL 重新创建它。If needed, remove and recreate this remote using the correct URL.


症状No refs in common and none specified; doing nothing. Perhaps you should specify a branch such as 'master'.Symptom: No refs in common and none specified; doing nothing. Perhaps you should specify a branch such as 'master'.

原因:如果在 git push 期间未指定分支,或者未在 .gitconfig 中设置 push.default 值,则会出现此错误。Cause: This error can happen if you don't specify a branch during git push, or if you haven't set the push.default value in .gitconfig.

解决方法:再次运行 git push,并指定主分支。Resolution: Run git push again, specifying the master branch. 例如:For example:

git push azure master

症状src refspec [branchname] does not match any.Symptom: src refspec [branchname] does not match any.

原因:如果尝试推送到“azure”远程网站上主分支之外的分支,则会发生该错误。Cause: This error can happen if you try to push to a branch other than master on the 'azure' remote.

解决方法:再次运行 git push,并指定主分支。Resolution: Run git push again, specifying the master branch. 例如:For example:

git push azure master

症状RPC failed; result=22, HTTP code = 5xx.Symptom: RPC failed; result=22, HTTP code = 5xx.

原因:如果尝试通过 HTTPS 推送大型 Git 存储库,则可能出现此错误。Cause: This error can happen if you try to push a large git repository over HTTPS.

解决方法:在本地计算机上更改 Git 配置,以增大 postBufferResolution: Change the git configuration on the local machine to make the postBuffer bigger

git config --global http.postBuffer 524288000

症状Error - Changes committed to remote repository but your web app not updated.Symptom: Error - Changes committed to remote repository but your web app not updated.

原因:如果部署 Node.js 应用时使用的 package.json 文件指定了其他所需模块,则会发生该错误。Cause: This error can happen if you deploy a Node.js app with a package.json file that specifies additional required modules.

解决方法:应在发生此错误之前记录包含“npm ERR!”Resolution: Additional messages with 'npm ERR!' 的其他消息,这些消息可提供有关失败的其他上下文。should be logged before this error, and can provide additional context on the failure. 以下是该错误的已知原因和相应的“npm ERR!”The following are known causes of this error and the corresponding 'npm ERR!' 消息:message:

  • package.json 文件格式不正确:npm ERR!Malformed package.json file: npm ERR! 无法读取依赖项。Couldn't read dependencies.

  • 没有 Windows 的二进制分发的本机模块Native module that doesn't have a binary distribution for Windows:

    • npm ERR! \cmd "/c" "node-gyp rebuild"\ failed with 1

      OROR

    • npm ERR! [modulename@version] preinstall: \make || gmake\

其他资源Additional Resources