教程:使用 Linux 上的 Azure 应用服务和 Azure Cosmos DB 生成 Java Spring Boot Web 应用
本教程介绍如何在 Azure 应用服务中生成、配置和部署安全 Spring Boot 应用程序,该应用程序连接到 Azure 中的 MongoDB 数据库(实际上是使用 MongoDB API 的 Cosmos DB 数据库)。 完成本教程后,Linux 上的 Azure 应用服务中将会运行 Java SE 应用。
本教程介绍如何执行下列操作:
- 使用 MongoDB API 为 Azure 应用服务和 Azure Cosmos DB 创建默认安全的体系结构。
- 使用托管标识和 Key Vault 引用来保护连接机密。
- 从 GitHub 存储库将 Spring Boot 示例应用部署到应用服务。
- 在应用程序代码中访问应用服务应用设置。
- 进行更新并重新部署应用程序代码。
- 从应用服务流式传输诊断日志。
- 在 Azure 门户中管理应用。
- 使用 Azure Developer CLI 预配同一体系结构并进行部署。
- 使用 GitHub Codespaces 和 GitHub Copilot 优化开发工作流。
- 具有活动订阅的 Azure 帐户。 如果没有 Azure 帐户,可创建一个帐户。
- 一个 GitHub 帐户。 你也可以免费获得一个。
- 通过 Spring Framework 开发了解 Java 知识。
- (可选)若要试用 GitHub Copilot,请创建一个 GitHub Copilot 帐户。 提供 30 天试用期。
- 具有活动订阅的 Azure 帐户。 如果没有 Azure 帐户,可以免费创建一个。
- 已安装 Azure 开发人员 CLI。 可以使用 Azure Cloud Shell 执行这些步骤,因为它已安装 Azure 开发人员 CLI。
- 通过 Spring Framework 开发了解 Java 知识。
- (可选)若要试用 GitHub Copilot,请创建一个 GitHub Copilot 帐户。 提供 30 天试用期。
可以快速部署本教程中的示例应用,并查看它是否在 Azure 中运行。 只需在 Azure Cli 中运行以下命令,然后按照提示操作:
mkdir msdocs-spring-boot-mongodb-sample-app
cd msdocs-spring-boot-mongodb-sample-app
azd init --template msdocs-spring-boot-mongodb-sample-app
azd up
首先,将示例数据驱动的应用设置为起点。 为方便起见,示例存储库包含一个开发容器配置。 开发容器包含开发应用程序所需的所有内容,包括示例应用程序所需的 MongoDB 数据库、缓存和所有环境变量。 开发容器可以在 GitHub codespace 中运行,这意味着可使用 Web 浏览器在任何计算机上运行示例。
步骤 1:在新浏览器窗口中:
- 登录到 GitHub 帐户。
- 导航到 https://github.com/Azure-Samples/msdocs-spring-boot-mongodb-sample-app/fork。
- 取消选择“仅复制主分支”。 需要所有分支。
- 选择“创建分支”。
步骤 2:在 GitHub 分支中:
- 为起始分支选择“主”>“starter-no-infra”。 此分支仅包含示例项目,不包含与 Azure 相关的文件或配置。
- 选择“代码”>“在 starter-no-infra 上创建 codespace”。 设置 codespace 需要几分钟时间。
步骤 3:在 codespace 终端中:
- 运行
mvn package spring-boot:run
。 - 看到通知
Your application running on port 8080 is available.
时,选择“在浏览器中打开”。 应在新的浏览器选项卡中看到该示例应用程序。若要停止 Jetty 服务器,请键入Ctrl
+C
。
提示
可以向 GitHub Copilot 询问有关此存储库的信息。 例如:
- @workspace 这个项目有什么用?
- @workspace 应用如何连接到数据库?
- @workspace .devcontainer 文件夹有什么用?
遇到问题? 检查故障排除部分。
首先,创建 Azure 资源。 本教程中使用的步骤创建一组默认安全的资源,其中包括应用服务和 Azure Cosmos DB。 对于创建过程,需要指定:
- Web 应用的名称。 它以
https://<app-name>-<hash>.<region>.chinacloudsites.cn
的形式用作应用的 DNS 名称的一部分。 - “区域”,在世界上以物理方式运行应用。 它还用作应用的 DNS 名称的一部分。
- 应用的运行时堆栈。 在此处选择要用于应用的 PHP 版本。
- 应用的托管计划。 它是定价层,包括应用的一组功能和缩放容量。
- 应用的资源组。 使用资源组可将应用程序所需的所有 Azure 资源分组到一个逻辑容器中。
登录到 Azure 门户并按照以下步骤创建 Azure 应用服务资源。
步骤 1:在 Azure 门户中:
- 在 Azure 门户顶部的搜索栏中,输入“Web 应用数据库”。
- 选择“市场”标题下标记为“Web 应用 + 数据库”的项目。 还可以直接导航到创建向导。
步骤 2:在“创建 Web 应用 + 数据库”页上,按下面所述填写表单。
- 资源组:选择“新建”,使用 msdocs-expressjs-mongodb-tutorial 的名称。
- 区域:你附近的任何 Azure 区域。
- 名称:msdocs-spring-cosmosdb-XYZ,其中 XYZ 是任意三个随机字符。 该名称在 Azure 中必须唯一。
- 运行时堆栈:Java 21。
- Java Web 服务器堆栈:Java SE(嵌入式 Web 服务器)。
- 引擎:适用于 MongoDB 的 Cosmos DB API。 Cosmos DB 是 Azure 上完全托管的 NoSQL 关系数据库和矢量数据库即服务。
- 托管计划:基本。 准备就绪后,可以纵向扩展到生产定价层。
- 选择“查看 + 创建”。
- 验证完成后,选择“创建”。
步骤 3:该部署需要数分钟才能完成。 部署完成后,选择“转到资源”按钮。 这将直接转到应用服务应用,但会创建以下资源:
- 资源组:所有已创建资源的容器。
- 应用服务计划:为应用服务定义计算资源。 将创建基本层中的 Linux 计划。
- 应用服务:表示应用并在应用服务计划中运行。
- 虚拟网络:与应用服务应用集成,并隔离后端网络流量。
- Azure Cosmos DB:只能从专用终结点后面访问。 将在数据库帐户上为你创建数据库。
- 专用终结点:虚拟网络中数据库服务器和 Redis 缓存的访问终结点。
- 专用 DNS 区域:在虚拟网络中启用数据库服务器和 Redis 缓存的 DNS 解析。
遇到问题? 检查故障排除部分。
创建向导已经为你生成了连接字符串作为应用设置。 但是,安全最佳做法是将机密完全保留在应用服务之外。 你需要借助服务连接器将机密移到密钥保管库,并将应用设置更改为密钥保管库引用。
步骤 1:在“应用服务”页中:
- 在左侧菜单中,选择“设置”>“环境变量”。
- 在 AZURE_COSMOS_CONNECTIONSTRING 旁边,选择“显示值”。 此连接字符串允许连接到受专用终结点保护的 Cosmos DB 数据库。 但是,机密直接保存在应用服务应用中,这不是最好的做法。 你将对此进行更改。
步骤 2:创建密钥保管库以安全管理机密。
- 在顶部搜索栏中,键入“密钥保管库”,然后选择“市场”>“密钥保管库”。
- 在“资源组”中,选择“msdocs-spring-cosmosdb-tutorial”。
- 在“密钥保管库名称”中,键入仅包含字母和数字的名称。
- 在“区域”中,将其设置为资源组的示例位置。
步骤 3:
- 选择“网络”选项卡。
- 取消选择“启用公共访问”。
- 选择“创建专用终结点”。
- 在“资源组”中,选择“msdocs-spring-cosmosdb-tutorial”。
- 在“密钥保管库名称”中,键入仅包含字母和数字的名称。
- 在“区域”中,将其设置为资源组的示例位置。
- 在对话框中,在“位置”中,选择与应用服务应用相同的位置。
- 在“资源组”中,选择“msdocs-spring-cosmosdb-tutorial”。
- 在“名称”中,键入 msdocs-spring-cosmosdb-XYZVaultEndpoint。
- 在“虚拟网络”中,选择 msdocs-spring-cosmosdb-XYZVnet。
- 在“子网”中,msdocs-spring-cosmosdb-XYZSubnet。
- 选择“确定”。
- 依次选择“查看 + 创建”、“创建”。 等待密钥保管库部署完成。 应会看到“部署已完成”。
步骤 4:
- 在顶部搜索栏中,键入“msdocs-spring-cosmosdb”,然后键入名为“msdocs-spring-cosmosdb-XYZ”的应用服务资源。
- 在应用服务页面的左侧菜单中,选择“设置”>“服务连接器”。 已经有一个连接器,该连接器是为你创建的应用创建向导。
- 选中连接器旁边的复选框,然后选择“编辑”。
- 在“基本信息”选项卡中,将“客户端类型”设置为“SpringBoot”。 此选项会为你创建特定于 Spring Boot 的环境变量。
- 选择“身份验证”选项卡。
- 选择“在密钥保管库中存储机密”。
- 在“密钥保管库连接”下,选择“创建新连接”。 在编辑对话框顶部打开“创建连接”对话框。
步骤 5:在密钥保管库连接的“创建连接”对话框中:
- 在“密钥保管库”中选择之前创建的密钥保管库。
- 选择“查看 + 创建” 。 应该会看到“系统分配的托管标识”设置为“已选中”。
- 验证完成后,选择“创建”。
步骤 6:返回“defaultConnector”的编辑对话框中。
- 在“身份验证”选项卡中,等待创建密钥保管库连接器。 完成后,“密钥保管库连接”下拉列表会自动选择相应选项。
- 选择“下一页:网络”。
- 选择“配置防火墙规则以启用对目标服务的访问权限”。 如果看到消息“目标服务上没有专用终结点”,请忽略它。 应用创建向导已使用专用终结点保护 Cosmos DB 数据库。
- 选择“保存”。 等待“更新成功”通知出现。
步骤 7:验证所做的更改:
- 在左侧菜单中,再次选择“环境变量”。
- 确保存在应用设置 spring.data.mongodb.uri。 默认连接器为你生成它,Spring Boot 应用程序已使用该变量。
- 在应用设置旁边,选择“显示值”。 该值应为
@Microsoft.KeyVault(...)
,这意味着它是 密钥保管库引用,因为密钥保管库中现在管理机密。
遇到问题? 检查故障排除部分。
在此步骤中,使用 GitHub Actions 配置 GitHub 部署。 这只是部署到应用服务的许多方法之一,也是一种在部署过程中持续集成的好方法。 默认情况下,进入 GitHub 存储库的每个 git push
都会启动生成和部署操作。
步骤 1:在左侧菜单中,选择“部署”>“部署中心”。
步骤 2:在“部署中心”页中:
- 在“源”中,选择“GitHub”。 默认情况下,选择 GitHub Actions 作为生成提供程序。
- 登录到 GitHub 帐户,并按照提示授权 Azure。
- 在“组织”中,选择你的帐户。
- 在“存储库”中,选择“msdocs-spring-boot-mongodb-sample-app”。
- 在“分支”中,选择“starter-no-infra”。 这是与示例应用一起使用的同一分支,不包含任何与 Azure 相关的文件或配置。
- 对于“身份验证类型”,请选择“用户分配的标识”。
- 在顶部菜单中,选择“保存”。 应用服务会将工作流文件提交到所选 GitHub 存储库中(在
.github/workflows
目录中)。 默认情况下,部署中心会为工作流创建用户分配的标识,以便使用 Microsoft Entra(OIDC 身份验证)进行身份验证。 有关身份验证选项的详细信息,请参阅使用 GitHub Actions 部署到应用服务。
步骤 3:
- 选择“日志”选项卡。查看新部署已运行,但状态为“失败”。
- 选择“生成/部署日志”。
浏览器选项卡打开为 GitHub 中分支存储库“操作”选项卡。 在“批注”中,会看到错误
The string 'java21' is not valid SeVer notation for a Java version
。 如果需要,请在页面中选择失败的“生成”步骤,以获取详细信息。
步骤 4:错误显示 GitHub 工作流期间出现问题。 若要解决此问题,请先将最新更改拉取到 codespace。 返回示例分支的 GitHub codespace,运行 git pull origin starter-no-infra
。
这会将新提交的工作流文件拉取到 codespace。
步骤 5(选项 1:使用 GitHub Copilot):
- 选择“聊天”视图,然后选择 +,即可开始新的聊天会话。
- 问:“@workspace 为什么我在 GitHub 操作中收到此错误:字符串 'java21' 对 Java 版本的 SemVer 表示法无效?”Copilot 可能会为你提供解释,甚至提供指向需要修复的工作流文件的链接。
- 在资源管理器中打开 .github/workflows/starter-no-infra_msdocs-spring-cosmosdb-123.yaml,并进行建议的修复。 GitHub Copilot 不会每次都给你相同的回复,你可能需要提出更多问题来优调其回复。 有关提示,请参阅我可以在 codespace 中使用 GitHub Copilot 做什么?。
步骤 5(选项 2:不使用 GitHub Copilot):
- 在资源管理器中打开 .github/workflows/starter-no-infra_msdocs-spring-cosmosdb-123.yaml,并找到
setup-java@v4
操作。 - 将
java-version
的值更改为'21'
。
步骤 6:
- 选择“源代码管理”扩展。
- 在文本框中,键入类似
Fix error in java-version
的提交消息。 或者,选择,让 GitHub Copilot 为你生成提交消息。
- 选择“提交”,然后使用“是”进行确认。
- 选择“同步更改 1”,然后使用“确定”进行确认。
步骤 7:返回到 Azure 门户中的“部署中心”页:
- 在“日志”选项卡下,选择“刷新”。 已从提交的更改开始新的部署运行。
- 在部署运行的日志项中,选择具有最新时间戳的“生成/部署日志”条目。
步骤 8:你已转到 GitHub 存储库,并看到 GitHub Action 正在运行。 工作流文件定义两个单独的阶段,即生成和部署阶段。 等待 GitHub 运行以显示“完成”状态。
遇到问题? 检查故障排除部分。
步骤 1:在“应用服务”页中:
- 从左侧菜单中选择“概述”。
- 选择应用的 URL。
步骤 2:将一些任务添加到列表。 恭喜,你已在 Azure 应用服务中运行了一个 Web 应用,并安全连接到了 Azure Cosmos DB。
遇到问题? 检查故障排除部分。
Azure 应用服务会捕获输出到控制台的所有消息,以帮助你诊断应用程序的问题。 示例应用程序包括标准 Log4j 日志记录语句,用于演示此功能,如以下代码片段所示:
private static Logger logger = LoggerFactory.getLogger(TodoListController.class);
@Autowired
private TodoItemRepository todoItemRepository;
public TodoListController() {
}
/**
* HTTP GET
*/
@GetMapping(path = "/api/todolist/{index}", produces = {MediaType.APPLICATION_JSON_VALUE})
public TodoItem getTodoItem(@PathVariable("index") String index) {
logger.info("GET request access '/api/todolist/{}' path.", index);
return todoItemRepository.findById(index).get();
}
步骤 1:在“应用服务”页中:
- 从左菜单中选择“应用服务日志”。
- 在“应用程序日志记录”下,选择“文件系统”。
- 在顶部菜单中,选择“保存”。
步骤 2:在左侧菜单中,选择“日志流”。 将显示应用的日志,包括平台日志和容器内部的日志。
在 为 .NET、Node.js、Python 和 Java 应用程序启用 Azure Monitor OpenTelemetry 系列中详细了解 Java 应用中的日志记录。
遇到问题? 检查故障排除部分。
完成后,可以通过删除资源组从 Azure 订阅中删除所有资源。
步骤 1:在 Azure 门户顶部的搜索栏中:
- 输入资源组名称。
- 选择前面创建的资源组。
步骤 2:在资源组页上,选择“删除资源组”。
步骤 3:
- 键入资源组名称以确认删除。
- 选择“删除”。
- 再次使用“删除”进行确认。
在此步骤中,将创建 Azure 资源并将示例应用部署到 Linux 上的应用服务。 本教程中使用的步骤创建一组默认安全的资源,其中包括应用服务和 Azure Cosmos DB。
开发容器已具有 Azure Developer CLI (AZD)。
从存储库根路径,运行
azd init
。azd init --template javase-app-service-cosmos-redis-infra
出现提示时,请提供以下答案:
问题 Answer 当前目录不为空。 是否要在此处初始化“<your-directory>”中的项目? Y 你希望对这些文件执行哪些操作? 使现有文件保持不变 输入新环境名称 键入唯一名称。 AZD 模板将此名称用作 Azure 中 Web 应用的 DNS 名称的一部分 ( <app-name>-<hash>.chinacloudsites.cn
)。 允许使用字母数字字符和下划线。通过运行
azd auth login
命令并按照提示登录到 Azure:azd auth login
使用
azd up
命令创建必要的 Azure 资源并部署应用代码。 按照提示为 Azure 资源选择所需的订阅和位置。azd up
azd up
命令需要大约 15 分钟来完成(Redis 缓存需要的时间最长)。 它还会编译和部署应用程序代码,但你稍后将修改代码以使用应用服务。 在运行时,该命令会提供有关预配和部署过程的消息,包括指向 Azure 中部署的链接。 完成后,命令还会显示指向部署应用程序的链接。此 AZD 模板包含使用以下 Azure 资源生成安全默认体系结构的文件(azure.yaml 和 infra 目录):
- 资源组:所有已创建资源的容器。
- 应用服务计划:为应用服务定义计算资源。 将创建 B1 层中的 Linux 计划。
- 应用服务:表示应用并在应用服务计划中运行。
- 虚拟网络:与应用服务应用集成,并隔离后端网络流量。
- 使用 MongoDB API 的 Azure Cosmos DB 账户:只能从其专用终结点后面访问。 将在服务器上为你创建数据库。
- Azure Cache for Redis:只能从虚拟网络中访问。
- 密钥保管库:只能从其专用终结点后面访问。 用于管理应用服务应用的机密。
- 专用终结点:虚拟网络中的密钥保管库、数据库服务器和 Redis 缓存的访问终结点。
- 专用 DNS 区域:启用虚拟网络中的 Cosmos DB 数据库、Redis 缓存和密钥保管库的 DNS 解析。
- Log Analytics 工作区:充当应用日志传送的目标容器,还可以在其中查询日志。
遇到问题? 检查故障排除部分。
你使用的 AZD 模板已为你生成了连接变量作为应用设置,并将它们输出到终端,以方便你使用。 使用应用设置可以将连接机密保留在代码存储库之外。
在 AZD 输出中,找到应用设置
spring.data.mongodb.uri
。 只显示设置名称。 它们在 AZD 输出中如下所示:App Service app has the following app settings: - spring.data.mongodb.uri - spring.data.mongodb.database - spring.redis.host - spring.redis.port - spring.redis.password - spring.redis.database - spring.redis.ssl - spring.cloud.azure.keyvault.secret.credential.managed_identity_enabled - spring.cloud.azure.keyvault.secret.endpoint - azure.keyvault.uri - azure.keyvault.scope
spring.data.mongodb.uri
包含 Azure 中 Cosmos DB 数据库的连接 URI。 它是一个标准 Spring Data 变量,应用程序已在 src/main/resources/application.properties 文件中使用。在资源管理器中,导航到 src/main/resources/application.properties,并查看 Spring Boot 应用已在使用
spring.data.mongodb.uri
变量访问数据。为方便起见,AZD 模板输出会显示应用的应用设置页的直接链接。 找到该链接并在新的浏览器选项卡中打开它。
如果查看
spring.data.mongodb.uri
的值,它应为@Microsoft.KeyVault(...)
,这意味着它是密钥保管库引用,因为密钥保管库中管理机密。
遇到问题? 检查故障排除部分。
在 AZD 输出中,找到应用的 URL 并在浏览器中导航到该 URL。 该 URL 在 AZD 输出中如下所示:
Deploying services (azd deploy) (✓) Done: Deploying service web - Endpoint: https://<app-name>-<hash>.chinacloudsites.cn/
将一些任务添加到列表。
恭喜,你已在 Azure 应用服务中运行了一个 Web 应用,并安全连接到了 Azure Cosmos DB。
遇到问题? 检查故障排除部分。
Azure 应用服务可以捕获控制台日志,以帮助你诊断应用程序的问题。 为方便起见,AZD 模板已启用对本地文件系统的日志记录以及将日志传送到 Log Analytics 工作区。
示例应用程序包括标准 Log4j 日志记录语句,用于演示此功能,如以下代码片段所示:
private static Logger logger = LoggerFactory.getLogger(TodoListController.class);
@Autowired
private TodoItemRepository todoItemRepository;
public TodoListController() {
}
/**
* HTTP GET
*/
@GetMapping(path = "/api/todolist/{index}", produces = {MediaType.APPLICATION_JSON_VALUE})
public TodoItem getTodoItem(@PathVariable("index") String index) {
logger.info("GET request access '/api/todolist/{}' path.", index);
return todoItemRepository.findById(index).get();
}
在 AZD 输出中,找到流式传输应用服务日志的链接,并在浏览器中导航到该链接。 该链接在 AZD 输出中如下所示:
Stream App Service logs at: https://portal.azure.cn/#@/resource/subscriptions/<subscription-guid>/resourceGroups/<group-name>/providers/Microsoft.Web/sites/<app-name>/logStream
在 为 .NET、Node.js、Python 和 Java 应用程序启用 Azure Monitor OpenTelemetry 系列中详细了解 Java 应用中的日志记录。
遇到问题? 检查故障排除部分。
若要删除当前部署环境中的所有 Azure 资源,请运行 azd down
并按照提示进行操作。
azd down
根据订阅和所选区域,你可能会看到 Azure SQL DB 的部署状态为 Conflict
,并且操作详细信息中显示以下消息:
Sorry, we are currently experiencing high demand in <region> region, and cannot fulfill your request at this time.
此错误很可能是由所选区域的订阅限制引起的。 请尝试为部署选择其他区域。
如果你看到 Hey, Java developers!
页,而不是任务列表应用,则应用服务很可能仍会从最近的代码部署加载更新的容器。 等待几分钟,然后刷新页面。
所创建资源的定价如下所示:
- 应用服务计划在基本层中创建,可以进行纵向扩展或缩减。 请参阅应用服务定价。
- Azure Cosmos DB 帐户是在“无服务器”层中创建的,并且此层的成本很小。 请参阅 Azure Cosmos DB 定价。
- Azure Cache for Redis 是在缓存大小最小的基本层中创建的。 此层的相关成本很低。 你可将其纵向扩展到更高的性能层,以实现更高的可用性、聚类分析和其他功能。 请查阅 Azure Cache for Redis 定价。
- 除非配置额外的功能(例如对等互连),否则虚拟网络不会产生费用。 请参阅 Azure 虚拟网络定价。
- 专用 DNS 区域会产生少量费用。 请参阅 Azure DNS 定价。
应用服务中的 Java SE 容器已与 Cosmos DB 建立网络连接,但不包含任何迁移工具或其他 MongoDB 工具。 有几个选择:
- 在应用启动时自动运行数据库迁移,例如使用 Hibernate 和/或 Flyway。
- 在应用的 SSH 会话中,安装迁移工具(如 Flyway CLI),然后运行迁移脚本。 请记住,除非它位于 /home 目录中,否则应用重启后,已安装的工具不会保留。
以应用服务中自动生成的工作流文件为例,每个 git push
都会启动新的生成和部署运行。 从 GitHub 存储库的本地克隆中,进行所需更新并推送到 GitHub。 例如:
git add .
git commit -m "<some-message>"
git push origin main
你可能注意到,创建 codespace 时,GitHub Copilot 聊天视图已经存在。 为了你的方便,我们在容器定义中包含了 GitHub Copilot 聊天扩展(参见 .devcontainer/devcontainer.json)。 但是,需要 GitHub Copilot 帐户(提供 30 天试用期)。
下面是与 GitHub Copilot 交谈时的一些提示:
- 在单次聊天会话中,问题和答案相互关联,你可以调整问题来微调所获得的答案。
- 默认情况下,GitHub Copilot 无法访问你存储库中的任何文件。 若要询问有关文件的问题,请首先在编辑器中打开该文件。
- 为了让 GitHub Copilot 在准备答案时有权访问存储库中的所有文件,请在问题开头加上
@workspace
。 有关详细信息,请参阅 Use the @workspace agent。 - 在聊天会话中,GitHub Copilot 可以建议更改,甚至可以(在使用
@workspace
时)建议在何处进行更改,但系统不允许它为你进行更改。 你可以自行添加建议的更改并对其进行测试。
在开发人员指南中详细了解在应用服务上运行 Java 应用。
了解如何使用自定义域和证书保护应用。