Red Hat Summit 红帽全球峰会支持控制台（Console）开发人员开始试用联系人

跨资源共享(CORS)配置

Red Hat build of Quarkus 3.20

Red Hat Customer Content Services

摘要

本指南探索如何使用 Cross-Origin Resource Sharing (CORS)，通过使用红帽构建的 Quarkus 应用程序的服务器定义策略来安全地管理跨原始 HTTP 请求。它强调了安全策略实施、动态来源管理和详细的标头自定义，以控制跨原始 HTTP 请求。另外，它还为配置 CORS 过滤器提供了分步指导，使用正则表达式进行允许的原始卷，并确保在开发和生产环境中遵循安全最佳实践。

向红帽构建的 Quarkus 文档提供反馈

要报告错误或改进文档，请登录您的红帽 JIRA 帐户并提交问题。如果您没有红帽 JIRA 帐户，系统会提示您创建一个帐户。

流程

  1. 单击以下链接 来创建 ticket。
  2. 在 Summary 中输入有关此问题的简单描述。
  3. 在描述中提供问题或增强功能的详细描述。请包括有问题的文档 URL。
  4. 点 Submit 创建问题并将其路由到适当的文档团队。

第 1 章 跨资源共享(CORS)

在 Quarkus 中启用并配置 CORS，以指定允许的源、方法和标头，在安全处理跨原始请求时获取浏览器。

跨资源共享(CORS)使用 HTTP 标头来管理来自外部来源的资源的浏览器请求。通过指定允许的源、方法和标头，Quarkus 服务器可以使用 CORS 过滤器使浏览器在域间请求资源，同时保持受控访问。这种机制增强了安全性，并支持合法跨原始请求。有关原始定义的更多信息，请参阅 Web Origin Concept。

1.1. 启用 CORS 过滤器

要强制应用程序中 CORS 策略，请通过在 src/main/resources/application.properties 文件中添加以下行来启用 Quarkus CORS 过滤器： 

quarkus.http.cors.enabled=true
Copy to clipboard

过滤器截获所有传入的 HTTP 请求，以识别跨原始请求并应用配置的策略。然后，过滤器会将 CORS 标头添加到 HTTP 响应中，通知浏览器有关允许的源和访问参数。对于 preflight 请求，过滤器会立即返回 HTTP 响应。对于常规 CORS 请求，如果请求违反了配置策略，则过滤器会拒绝 HTTP 403 状态的访问；否则，如果策略允许，过滤器会将请求转发到目的地。

有关详细的配置选项，请查看以下配置属性部分。

lock 在构建时修复的配置属性 - 所有其他配置属性在运行时可覆盖

配置属性

类型

default

quarkus.http.cors.origins

CORS 允许的源。

以逗号分隔的有效 URL 列表，如 http://www.quarkus.io,http://localhost:3000。以正斜杠括起的 URL 解释为正则表达式。

环境变量： QUARKUS_HTTP_CORS_ORIGINS

字符串列表

 

quarkus.http.cors.methods

允许 CORS 请求的 HTTP 方法。

以逗号分隔的有效 HTTP 方法列表，如 GET、PUT、POST。如果没有设置，则过滤器默认允许任何 HTTP 方法。

默认：允许任何 HTTP 请求方法。

环境变量： QUARKUS_HTTP_CORS_METHODS

字符串列表

 

quarkus.http.cors.headers

CORS 请求允许的 HTTP 标头。

以逗号分隔的有效标头列表，如 X-Custom,Content-Disposition。如果没有设置，过滤器默认允许任何标头。

默认：允许任何 HTTP 请求标头。

环境变量： QUARKUS_HTTP_CORS_HEADERS

字符串列表

 

quarkus.http.cors.exposed-headers

CORS 响应中公开的 HTTP 标头。

要公开的标头的逗号分隔列表，如 X-Custom,Content-Disposition。

默认：不会公开标头。

环境变量： QUARKUS_HTTP_CORS_EXPOSED_HEADERS

字符串列表

 

quarkus.http.cors.access-control-max-age

Access-Control-Max-Age 响应标头值，格式为 java.time.Duration。

告知浏览器可以缓存 preflight 请求结果的时长。

环境变量： QUARKUS_HTTP_CORS_ACCESS_CONTROL_MAX_AGE

duration  question circle

 

quarkus.http.cors.access-control-allow-credentials

Access-Control-Allow-Credentials 响应标头。

当请求的凭据模式 Request.credentials 被设置为 include 时，告诉浏览器，如果允许前端 JavaScript 访问凭证。

default: true 如果设置了 quarkus.http.cors.origins 属性，并且与 precise Origin 标头值匹配。

环境变量： QUARKUS_HTTP_CORS_ACCESS_CONTROL_ALLOW_CREDENTIALS

布尔值

 
关于 Duration 格式

要写入持续时间值，请使用标准 java.time.Duration 格式。如需更多信息，请参阅 Duration#parse （）Java API 文档。

您还可以使用简化的格式，从数字开始：

  • 如果值只是一个数字，它代表时间（以秒为单位）。
  • 如果值为数字，后跟 ms，代表时间（毫秒）。

在其他情况下，简化的格式被转换为 java.time.Duration 格式以进行解析：

  • 如果该值是一个数字，后跟 h、m 或 s，则前缀为 PT。
  • 如果值为数字，后跟 d，则会以 P 为前缀。

1.2. CORS 配置示例

以下示例显示了完整的 CORS 过滤器配置，包括定义一个原始表达式的正则表达式。 

quarkus.http.cors.enabled=true 1
quarkus.http.cors.origins=http://example.com,http://www.example.io,/https://([a-z0-9\\-_]+)\\\\.app\\\\.mydomain\\\\.com/ 2
quarkus.http.cors.methods=GET,PUT,POST 3
quarkus.http.cors.headers=X-Custom 4
quarkus.http.cors.exposed-headers=Content-Disposition 5
quarkus.http.cors.access-control-max-age=24H 6
quarkus.http.cors.access-control-allow-credentials=true 7
Copy to clipboard
1
启用 CORS 过滤器。
2
指定允许的原始卷，包括正则表达式。
3
列出跨原始请求允许的 HTTP 方法。
4
声明客户端可在请求中包含的自定义标头。
5
标识客户端可访问的响应标头。
6
设置 preflight 请求结果的缓存时长。
7
允许跨原始请求中的 Cookie 或凭证。

在 application.properties 文件中使用正则表达式时，请使用四个反向斜杠(\\\\)转义特殊字符，以确保行为正确。例如：

  • \\\\. 匹配字面上的 . 字符。
  • \\. 将任何单个字符匹配为正则表达式元数据字符。
重要

转义模式不正确可能会导致意外的行为或安全漏洞。在部署之前，始终验证正则表达式语法。

1.3. 在 dev 模式中允许所有源

在开发过程中配置起源可能具有挑战性。要简化开发，请考虑只允许开发模式中的所有源： 

quarkus.http.cors.enabled=true
%dev.quarkus.http.cors.origins=/.*/
Copy to clipboard
警告

只允许 development 配置集中的所有源(%dev)。在生产环境中允许不受限制的源会带来严重的安全风险，如未授权的数据访问或资源滥用。对于生产环境，在 quarkus.http.cors.origins 属性中定义显式原始卷。

1.4. 参考

法律通告

Copyright © 2025 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.
返回顶部
Red Hat logoGithubredditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

通过我们的产品和服务，以及可以信赖的内容，帮助红帽用户创新并实现他们的目标。 了解我们当前的更新.

让开源更具包容性

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。欲了解更多详情，请参阅红帽博客.

關於紅帽

我们提供强化的解决方案，使企业能够更轻松地跨平台和环境（从核心数据中心到网络边缘）工作。

Theme

© 2025 Red Hat, Inc.