hf400159 commented on code in PR #7398: URL: https://github.com/apache/apisix/pull/7398#discussion_r915425235
########## docs/zh/latest/plugins/cors.md: ########## @@ -71,10 +79,15 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13 ## 测试插件 -请求下接口，发现接口已经返回了 `CORS` 相关的 header，代表插件生效 +启用插件后，使用 curl 命令向服务器请求接口： ```shell curl http://127.0.0.1:9080/hello -v +``` + +如果发现接口已经返回了 CORS 相关的 header，则代表插件生效： Review Comment: ```suggestion 如果返回结果中出现 CORS 相关的 header，则代表插件生效： ``` ########## docs/zh/latest/plugins/cors.md: ########## @@ -23,35 +28,38 @@ title: cors ## 描述 -`cors` 插件可以让你为服务端启用 [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) 的返回头。 +`cors` 插件可以让你轻松地为服务端启用 [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)（Cross-Origin Resource Sharing，跨域资源共享）的返回头。 ## 属性 -| 名称 | 类型 | 可选项 | 默认值 | 有效值 | 描述 | -| ---------------- | ------- | ------ | ------ | ------ | ------------------------------------------------------------ | -| allow_origins | string | 可选 | "*" | | 允许跨域访问的 Origin，格式如：`scheme`://`host`:`port`，比如: https://somehost.com:8081 。多个值使用 `,` 分割，`allow_credential` 为 `false` 时可以使用 `*` 来表示所有 Origin 均允许通过。你也可以在启用了 `allow_credential` 后使用 `**` 强制允许所有 Origin 都通过，但请注意这样存在安全隐患。 | -| allow_methods | string | 可选 | "*" | | 允许跨域访问的 Method，比如: `GET`，`POST`等。多个值使用 `,` 分割，`allow_credential` 为 `false` 时可以使用 `*` 来表示所有 Origin 均允许通过。你也可以在启用了 `allow_credential` 后使用 `**` 强制允许所有 Method 都通过，但请注意这样存在安全隐患。 | -| allow_headers | string | 可选 | "*" | | 允许跨域访问时请求方携带哪些非 `CORS 规范` 以外的 Header， 多个值使用 `,` 分割，`allow_credential` 为 `false` 时可以使用 `*` 来表示所有 Header 均允许通过。你也可以在启用了 `allow_credential` 后使用 `**` 强制允许所有 Header 都通过，但请注意这样存在安全隐患。 | -| expose_headers | string | 可选 | "*" | | 允许跨域访问时响应方携带哪些非 `CORS 规范` 以外的 Header， 多个值使用 `,` 分割，`allow_credential` 为 `false` 时可以使用 `*` 来表示允许任意 Header 。你也可以在启用了 `allow_credential` 后使用 `**` 强制允许任意 Header，但请注意这样存在安全隐患。 | -| max_age | integer | 可选 | 5 | | 浏览器缓存 CORS 结果的最大时间，单位为秒，在这个时间范围内浏览器会复用上一次的检查结果，`-1` 表示不缓存。请注意各个浏览器允许的最大时间不同，详情请参考 [MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Max-Age#Directives)。 | -| allow_credential | boolean | 可选 | false | | 是否允许跨域访问的请求方携带凭据（如 Cookie 等）。根据 CORS 规范，如果设置该选项为 `true`，那么将不能在其他选项中使用 `*`。 | -| allow_origins_by_regex | array | 可选 | nil | | 使用正则表达式数组来匹配允许跨域访问的 Origin，如 [".*\.test.com"] 可以匹配任何 test.com 的子域名`*`。 | -| allow_origins_by_metadata | array | 可选 | nil | | 通过引用插件元数据的 `allow_origins` 配置允许跨域访问的 Origin。比如当元数据为 `"allow_origins": {"EXAMPLE": "https://example.com"}` 时，配置 `["EXAMPLE"]` 将允许 Origin `https://example.com` 的访问 | - -> **提示** -> -> 请注意 `allow_credential` 是一个很敏感的选项，谨慎选择开启。开启之后，其他参数默认的 `*` 将失效，你必须显式指定它们的值。 -> 使用 `**` 时要充分理解它引入了一些安全隐患，比如 CSRF，所以确保这样的安全等级符合自己预期再使用。 +| 名称 | 类型 | 必选项 | 默认值 | 描述 | +| ---------------- | ------- | ------ | ------ | ------------------------------------------------------------ | +| allow_origins | string | 否 | "*" | 允许跨域访问的 Origin，格式如：`scheme://host:port`，比如：`https://somedomain.com:8081`。多个值使用 `,` 分隔。 `allow_credential` 为 `false` 可以使用 `*` 来表示所有 Origin 均允许通过。你也可以在启用了 `allow_credential` 后使用 `**` 强制允许所有 Origin 均通过，但请注意这样存在安全隐患。 | +| allow_methods | string | 否 | "*" | 允许跨域访问的 Method，比如：`GET`，`POST` 等。多个值使用 `,` 分割，`allow_credential` 为 `false` 时可以使用 `*` 来表示所有 Method 均允许通过。你也可以在启用了 `allow_credential` 后使用 `**` 强制允许所有 Method 都通过，但请注意这样存在安全隐患。 | +| allow_headers | string | 否 | "*" | 允许跨域访问时请求方携带哪些非 `CORS 规范` 以外的 Header，多个值使用 `,` 分割，`allow_credential` 为 `false` 时可以使用 `*` 来表示所有 Header 均允许通过。你也可以在启用了 `allow_credential` 后使用 `**` 强制允许所有 Header 都通过，但请注意这样存在安全隐患。 | +| expose_headers | string | 否 | "*" | 允许跨域访问时响应方携带哪些非 `CORS 规范` 以外的 Header，多个值使用 `,` 分割，`allow_credential` 为 `false` 时可以使用 `*` 来表示允许任意 Header 。你也可以在启用了 `allow_credential` 后使用 `**` 强制允许任意 Header，但请注意这样存在安全隐患。 | +| max_age | integer | 否 | 5 | 浏览器缓存 CORS 结果的最大时间，单位为秒。在这个时间范围内，浏览器会复用上一次的检查结果，`-1` 表示不缓存。请注意各个浏览器允许的最大时间不同，详情请参考 [Access-Control-Max-Age - MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Max-Age#directives)。 | +| allow_credential | boolean | 否 | false | 是否允许跨域访问的请求方携带凭据（如 Cookie 等）。根据 CORS 规范，如果设置该选项为 `true`，那么将不能在其他属性中使用 `*`。 | +| allow_origins_by_regex | array | 否 | nil | 使用正则表达式数组来匹配允许跨域访问的 Origin，如 `[".*\.test.com"]` 可以匹配任何 `test.com` 的子域名 `*`。 | +| allow_origins_by_metadata | array | 否 | nil | 通过引用插件元数据的 `allow_origins` 配置允许跨域访问的 Origin。比如当插件元数据为 `"allow_origins": {"EXAMPLE": "https://example.com"}` 时，配置 `["EXAMPLE"]` 将允许 Origin `https://example.com` 的访问。 | + +:::info IMPORTANT + +请注意， `allow_credential` 是一个很敏感的选项，谨慎选择开启。开启之后，其他参数默认的 `*` 将失效，你必须显式指定它们的值。使用 `**` 时要充分理解它引入的一些安全隐患，比如 CSRF，并确保这样的安全等级符合自己预期。 + +::: ## 元数据 -| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 | -| ----------- | ------ | ------ | ----- | ----- | ------------------ | -| allow_origins | object | 可选 | | | 定义允许跨域访问的 Origin；它的键为 `allow_origins_by_metadata` 使用的引用键， 值则为允许跨域访问的 Origin，其语义与 `allow_origins` 相同 | +| 名称 | 类型 | 必选项 | 描述 | +| ----------- | ------ | ------ | ------------------ | +| allow_origins | object | 否 | 定义允许跨域访问的 Origin；它的键为 `allow_origins_by_metadata` 使用的引用键，值则为允许跨域访问的 Origin，其语义与 `allow_origins` 相同。 | Review Comment: ```suggestion | allow_origins | object | 否 | 定义允许跨域访问的 Origin；它的键为 `allow_origins_by_metadata` 使用的引用键，值则为允许跨域访问的 Origin，其语义与属性中的 `allow_origins` 相同。 | ``` ########## docs/zh/latest/plugins/cors.md: ########## @@ -23,35 +28,38 @@ title: cors ## 描述 -`cors` 插件可以让你为服务端启用 [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) 的返回头。 +`cors` 插件可以让你轻松地为服务端启用 [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)（Cross-Origin Resource Sharing，跨域资源共享）的返回头。 ## 属性 -| 名称 | 类型 | 可选项 | 默认值 | 有效值 | 描述 | -| ---------------- | ------- | ------ | ------ | ------ | ------------------------------------------------------------ | -| allow_origins | string | 可选 | "*" | | 允许跨域访问的 Origin，格式如：`scheme`://`host`:`port`，比如: https://somehost.com:8081 。多个值使用 `,` 分割，`allow_credential` 为 `false` 时可以使用 `*` 来表示所有 Origin 均允许通过。你也可以在启用了 `allow_credential` 后使用 `**` 强制允许所有 Origin 都通过，但请注意这样存在安全隐患。 | -| allow_methods | string | 可选 | "*" | | 允许跨域访问的 Method，比如: `GET`，`POST`等。多个值使用 `,` 分割，`allow_credential` 为 `false` 时可以使用 `*` 来表示所有 Origin 均允许通过。你也可以在启用了 `allow_credential` 后使用 `**` 强制允许所有 Method 都通过，但请注意这样存在安全隐患。 | -| allow_headers | string | 可选 | "*" | | 允许跨域访问时请求方携带哪些非 `CORS 规范` 以外的 Header， 多个值使用 `,` 分割，`allow_credential` 为 `false` 时可以使用 `*` 来表示所有 Header 均允许通过。你也可以在启用了 `allow_credential` 后使用 `**` 强制允许所有 Header 都通过，但请注意这样存在安全隐患。 | -| expose_headers | string | 可选 | "*" | | 允许跨域访问时响应方携带哪些非 `CORS 规范` 以外的 Header， 多个值使用 `,` 分割，`allow_credential` 为 `false` 时可以使用 `*` 来表示允许任意 Header 。你也可以在启用了 `allow_credential` 后使用 `**` 强制允许任意 Header，但请注意这样存在安全隐患。 | -| max_age | integer | 可选 | 5 | | 浏览器缓存 CORS 结果的最大时间，单位为秒，在这个时间范围内浏览器会复用上一次的检查结果，`-1` 表示不缓存。请注意各个浏览器允许的最大时间不同，详情请参考 [MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Max-Age#Directives)。 | -| allow_credential | boolean | 可选 | false | | 是否允许跨域访问的请求方携带凭据（如 Cookie 等）。根据 CORS 规范，如果设置该选项为 `true`，那么将不能在其他选项中使用 `*`。 | -| allow_origins_by_regex | array | 可选 | nil | | 使用正则表达式数组来匹配允许跨域访问的 Origin，如 [".*\.test.com"] 可以匹配任何 test.com 的子域名`*`。 | -| allow_origins_by_metadata | array | 可选 | nil | | 通过引用插件元数据的 `allow_origins` 配置允许跨域访问的 Origin。比如当元数据为 `"allow_origins": {"EXAMPLE": "https://example.com"}` 时，配置 `["EXAMPLE"]` 将允许 Origin `https://example.com` 的访问 | - -> **提示** -> -> 请注意 `allow_credential` 是一个很敏感的选项，谨慎选择开启。开启之后，其他参数默认的 `*` 将失效，你必须显式指定它们的值。 -> 使用 `**` 时要充分理解它引入了一些安全隐患，比如 CSRF，所以确保这样的安全等级符合自己预期再使用。 +| 名称 | 类型 | 必选项 | 默认值 | 描述 | +| ---------------- | ------- | ------ | ------ | ------------------------------------------------------------ | +| allow_origins | string | 否 | "*" | 允许跨域访问的 Origin，格式如：`scheme://host:port`，比如：`https://somedomain.com:8081`。多个值使用 `,` 分隔。 `allow_credential` 为 `false` 可以使用 `*` 来表示所有 Origin 均允许通过。你也可以在启用了 `allow_credential` 后使用 `**` 强制允许所有 Origin 均通过，但请注意这样存在安全隐患。 | +| allow_methods | string | 否 | "*" | 允许跨域访问的 Method，比如：`GET`，`POST` 等。多个值使用 `,` 分割，`allow_credential` 为 `false` 时可以使用 `*` 来表示所有 Method 均允许通过。你也可以在启用了 `allow_credential` 后使用 `**` 强制允许所有 Method 都通过，但请注意这样存在安全隐患。 | +| allow_headers | string | 否 | "*" | 允许跨域访问时请求方携带哪些非 `CORS 规范` 以外的 Header，多个值使用 `,` 分割，`allow_credential` 为 `false` 时可以使用 `*` 来表示所有 Header 均允许通过。你也可以在启用了 `allow_credential` 后使用 `**` 强制允许所有 Header 都通过，但请注意这样存在安全隐患。 | +| expose_headers | string | 否 | "*" | 允许跨域访问时响应方携带哪些非 `CORS 规范` 以外的 Header，多个值使用 `,` 分割，`allow_credential` 为 `false` 时可以使用 `*` 来表示允许任意 Header 。你也可以在启用了 `allow_credential` 后使用 `**` 强制允许任意 Header，但请注意这样存在安全隐患。 | +| max_age | integer | 否 | 5 | 浏览器缓存 CORS 结果的最大时间，单位为秒。在这个时间范围内，浏览器会复用上一次的检查结果，`-1` 表示不缓存。请注意各个浏览器允许的最大时间不同，详情请参考 [Access-Control-Max-Age - MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Max-Age#directives)。 | +| allow_credential | boolean | 否 | false | 是否允许跨域访问的请求方携带凭据（如 Cookie 等）。根据 CORS 规范，如果设置该选项为 `true`，那么将不能在其他属性中使用 `*`。 | +| allow_origins_by_regex | array | 否 | nil | 使用正则表达式数组来匹配允许跨域访问的 Origin，如 `[".*\.test.com"]` 可以匹配任何 `test.com` 的子域名 `*`。 | +| allow_origins_by_metadata | array | 否 | nil | 通过引用插件元数据的 `allow_origins` 配置允许跨域访问的 Origin。比如当插件元数据为 `"allow_origins": {"EXAMPLE": "https://example.com"}` 时，配置 `["EXAMPLE"]` 将允许 Origin `https://example.com` 的访问。 | + +:::info IMPORTANT + +请注意， `allow_credential` 是一个很敏感的选项，谨慎选择开启。开启之后，其他参数默认的 `*` 将失效，你必须显式指定它们的值。使用 `**` 时要充分理解它引入的一些安全隐患，比如 CSRF，并确保这样的安全等级符合自己预期。 + +::: ## 元数据 -| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 | -| ----------- | ------ | ------ | ----- | ----- | ------------------ | -| allow_origins | object | 可选 | | | 定义允许跨域访问的 Origin；它的键为 `allow_origins_by_metadata` 使用的引用键， 值则为允许跨域访问的 Origin，其语义与 `allow_origins` 相同 | +| 名称 | 类型 | 必选项 | 描述 | +| ----------- | ------ | ------ | ------------------ | +| allow_origins | object | 否 | 定义允许跨域访问的 Origin；它的键为 `allow_origins_by_metadata` 使用的引用键，值则为允许跨域访问的 Origin，其语义与 `allow_origins` 相同。 | -## 如何启用 +## 启用插件 -创建 `Route` 或 `Service` 对象，并配置 `cors` 插件。 +你可以在一个特定路由或服务上启用 `cors` 插件。 Review Comment: ```suggestion 你可以在路由或服务上启用 `cors` 插件。 ``` ########## docs/zh/latest/plugins/cors.md: ########## @@ -23,35 +28,38 @@ title: cors ## 描述 -`cors` 插件可以让你为服务端启用 [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) 的返回头。 +`cors` 插件可以让你轻松地为服务端启用 [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)（Cross-Origin Resource Sharing，跨域资源共享）的返回头。 ## 属性 -| 名称 | 类型 | 可选项 | 默认值 | 有效值 | 描述 | -| ---------------- | ------- | ------ | ------ | ------ | ------------------------------------------------------------ | -| allow_origins | string | 可选 | "*" | | 允许跨域访问的 Origin，格式如：`scheme`://`host`:`port`，比如: https://somehost.com:8081 。多个值使用 `,` 分割，`allow_credential` 为 `false` 时可以使用 `*` 来表示所有 Origin 均允许通过。你也可以在启用了 `allow_credential` 后使用 `**` 强制允许所有 Origin 都通过，但请注意这样存在安全隐患。 | -| allow_methods | string | 可选 | "*" | | 允许跨域访问的 Method，比如: `GET`，`POST`等。多个值使用 `,` 分割，`allow_credential` 为 `false` 时可以使用 `*` 来表示所有 Origin 均允许通过。你也可以在启用了 `allow_credential` 后使用 `**` 强制允许所有 Method 都通过，但请注意这样存在安全隐患。 | -| allow_headers | string | 可选 | "*" | | 允许跨域访问时请求方携带哪些非 `CORS 规范` 以外的 Header， 多个值使用 `,` 分割，`allow_credential` 为 `false` 时可以使用 `*` 来表示所有 Header 均允许通过。你也可以在启用了 `allow_credential` 后使用 `**` 强制允许所有 Header 都通过，但请注意这样存在安全隐患。 | -| expose_headers | string | 可选 | "*" | | 允许跨域访问时响应方携带哪些非 `CORS 规范` 以外的 Header， 多个值使用 `,` 分割，`allow_credential` 为 `false` 时可以使用 `*` 来表示允许任意 Header 。你也可以在启用了 `allow_credential` 后使用 `**` 强制允许任意 Header，但请注意这样存在安全隐患。 | -| max_age | integer | 可选 | 5 | | 浏览器缓存 CORS 结果的最大时间，单位为秒，在这个时间范围内浏览器会复用上一次的检查结果，`-1` 表示不缓存。请注意各个浏览器允许的最大时间不同，详情请参考 [MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Max-Age#Directives)。 | -| allow_credential | boolean | 可选 | false | | 是否允许跨域访问的请求方携带凭据（如 Cookie 等）。根据 CORS 规范，如果设置该选项为 `true`，那么将不能在其他选项中使用 `*`。 | -| allow_origins_by_regex | array | 可选 | nil | | 使用正则表达式数组来匹配允许跨域访问的 Origin，如 [".*\.test.com"] 可以匹配任何 test.com 的子域名`*`。 | -| allow_origins_by_metadata | array | 可选 | nil | | 通过引用插件元数据的 `allow_origins` 配置允许跨域访问的 Origin。比如当元数据为 `"allow_origins": {"EXAMPLE": "https://example.com"}` 时，配置 `["EXAMPLE"]` 将允许 Origin `https://example.com` 的访问 | - -> **提示** -> -> 请注意 `allow_credential` 是一个很敏感的选项，谨慎选择开启。开启之后，其他参数默认的 `*` 将失效，你必须显式指定它们的值。 -> 使用 `**` 时要充分理解它引入了一些安全隐患，比如 CSRF，所以确保这样的安全等级符合自己预期再使用。 +| 名称 | 类型 | 必选项 | 默认值 | 描述 | +| ---------------- | ------- | ------ | ------ | ------------------------------------------------------------ | +| allow_origins | string | 否 | "*" | 允许跨域访问的 Origin，格式如：`scheme://host:port`，比如：`https://somedomain.com:8081`。多个值使用 `,` 分隔。 `allow_credential` 为 `false` 可以使用 `*` 来表示所有 Origin 均允许通过。你也可以在启用了 `allow_credential` 后使用 `**` 强制允许所有 Origin 均通过，但请注意这样存在安全隐患。 | Review Comment: ```suggestion | allow_origins | string | 否 | "*" | 允许跨域访问的 Origin，格式为 `scheme://host:port`，示例如 `https://somedomain.com:8081`。如果你有多个 Origin，请使用 `,` 分隔。当 `allow_credential` 为 `false` 可以使用 `*` 来表示所有 Origin 均允许通过。你也可以在启用了 `allow_credential` 后使用 `**` 强制允许所有 Origin 均通过，但请注意这样存在安全隐患。 | ``` ########## docs/zh/latest/plugins/cors.md: ########## @@ -23,35 +28,38 @@ title: cors ## 描述 -`cors` 插件可以让你为服务端启用 [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) 的返回头。 +`cors` 插件可以让你轻松地为服务端启用 [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)（Cross-Origin Resource Sharing，跨域资源共享）的返回头。 ## 属性 -| 名称 | 类型 | 可选项 | 默认值 | 有效值 | 描述 | -| ---------------- | ------- | ------ | ------ | ------ | ------------------------------------------------------------ | -| allow_origins | string | 可选 | "*" | | 允许跨域访问的 Origin，格式如：`scheme`://`host`:`port`，比如: https://somehost.com:8081 。多个值使用 `,` 分割，`allow_credential` 为 `false` 时可以使用 `*` 来表示所有 Origin 均允许通过。你也可以在启用了 `allow_credential` 后使用 `**` 强制允许所有 Origin 都通过，但请注意这样存在安全隐患。 | -| allow_methods | string | 可选 | "*" | | 允许跨域访问的 Method，比如: `GET`，`POST`等。多个值使用 `,` 分割，`allow_credential` 为 `false` 时可以使用 `*` 来表示所有 Origin 均允许通过。你也可以在启用了 `allow_credential` 后使用 `**` 强制允许所有 Method 都通过，但请注意这样存在安全隐患。 | -| allow_headers | string | 可选 | "*" | | 允许跨域访问时请求方携带哪些非 `CORS 规范` 以外的 Header， 多个值使用 `,` 分割，`allow_credential` 为 `false` 时可以使用 `*` 来表示所有 Header 均允许通过。你也可以在启用了 `allow_credential` 后使用 `**` 强制允许所有 Header 都通过，但请注意这样存在安全隐患。 | -| expose_headers | string | 可选 | "*" | | 允许跨域访问时响应方携带哪些非 `CORS 规范` 以外的 Header， 多个值使用 `,` 分割，`allow_credential` 为 `false` 时可以使用 `*` 来表示允许任意 Header 。你也可以在启用了 `allow_credential` 后使用 `**` 强制允许任意 Header，但请注意这样存在安全隐患。 | -| max_age | integer | 可选 | 5 | | 浏览器缓存 CORS 结果的最大时间，单位为秒，在这个时间范围内浏览器会复用上一次的检查结果，`-1` 表示不缓存。请注意各个浏览器允许的最大时间不同，详情请参考 [MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Max-Age#Directives)。 | -| allow_credential | boolean | 可选 | false | | 是否允许跨域访问的请求方携带凭据（如 Cookie 等）。根据 CORS 规范，如果设置该选项为 `true`，那么将不能在其他选项中使用 `*`。 | -| allow_origins_by_regex | array | 可选 | nil | | 使用正则表达式数组来匹配允许跨域访问的 Origin，如 [".*\.test.com"] 可以匹配任何 test.com 的子域名`*`。 | -| allow_origins_by_metadata | array | 可选 | nil | | 通过引用插件元数据的 `allow_origins` 配置允许跨域访问的 Origin。比如当元数据为 `"allow_origins": {"EXAMPLE": "https://example.com"}` 时，配置 `["EXAMPLE"]` 将允许 Origin `https://example.com` 的访问 | - -> **提示** -> -> 请注意 `allow_credential` 是一个很敏感的选项，谨慎选择开启。开启之后，其他参数默认的 `*` 将失效，你必须显式指定它们的值。 -> 使用 `**` 时要充分理解它引入了一些安全隐患，比如 CSRF，所以确保这样的安全等级符合自己预期再使用。 +| 名称 | 类型 | 必选项 | 默认值 | 描述 | +| ---------------- | ------- | ------ | ------ | ------------------------------------------------------------ | +| allow_origins | string | 否 | "*" | 允许跨域访问的 Origin，格式如：`scheme://host:port`，比如：`https://somedomain.com:8081`。多个值使用 `,` 分隔。 `allow_credential` 为 `false` 可以使用 `*` 来表示所有 Origin 均允许通过。你也可以在启用了 `allow_credential` 后使用 `**` 强制允许所有 Origin 均通过，但请注意这样存在安全隐患。 | +| allow_methods | string | 否 | "*" | 允许跨域访问的 Method，比如：`GET`，`POST` 等。多个值使用 `,` 分割，`allow_credential` 为 `false` 时可以使用 `*` 来表示所有 Method 均允许通过。你也可以在启用了 `allow_credential` 后使用 `**` 强制允许所有 Method 都通过，但请注意这样存在安全隐患。 | +| allow_headers | string | 否 | "*" | 允许跨域访问时请求方携带哪些非 `CORS 规范` 以外的 Header，多个值使用 `,` 分割，`allow_credential` 为 `false` 时可以使用 `*` 来表示所有 Header 均允许通过。你也可以在启用了 `allow_credential` 后使用 `**` 强制允许所有 Header 都通过，但请注意这样存在安全隐患。 | +| expose_headers | string | 否 | "*" | 允许跨域访问时响应方携带哪些非 `CORS 规范` 以外的 Header，多个值使用 `,` 分割，`allow_credential` 为 `false` 时可以使用 `*` 来表示允许任意 Header 。你也可以在启用了 `allow_credential` 后使用 `**` 强制允许任意 Header，但请注意这样存在安全隐患。 | +| max_age | integer | 否 | 5 | 浏览器缓存 CORS 结果的最大时间，单位为秒。在这个时间范围内，浏览器会复用上一次的检查结果，`-1` 表示不缓存。请注意各个浏览器允许的最大时间不同，详情请参考 [Access-Control-Max-Age - MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Max-Age#directives)。 | +| allow_credential | boolean | 否 | false | 是否允许跨域访问的请求方携带凭据（如 Cookie 等）。根据 CORS 规范，如果设置该选项为 `true`，那么将不能在其他属性中使用 `*`。 | +| allow_origins_by_regex | array | 否 | nil | 使用正则表达式数组来匹配允许跨域访问的 Origin，如 `[".*\.test.com"]` 可以匹配任何 `test.com` 的子域名 `*`。 | +| allow_origins_by_metadata | array | 否 | nil | 通过引用插件元数据的 `allow_origins` 配置允许跨域访问的 Origin。比如当插件元数据为 `"allow_origins": {"EXAMPLE": "https://example.com"}` 时，配置 `["EXAMPLE"]` 将允许 Origin `https://example.com` 的访问。 | + +:::info IMPORTANT + +请注意， `allow_credential` 是一个很敏感的选项，谨慎选择开启。开启之后，其他参数默认的 `*` 将失效，你必须显式指定它们的值。使用 `**` 时要充分理解它引入的一些安全隐患，比如 CSRF，并确保这样的安全等级符合自己预期。 Review Comment: ```suggestion `allow_credential` 是一个很敏感的选项，请谨慎开启。开启之后，其他参数默认的 `*` 将失效，你必须显式指定它们的值。 在使用 `**` 时，需要清楚该参数引入的一些安全隐患，比如 CSRF，并确保这样的安全等级符合自己预期。 ``` ########## docs/zh/latest/plugins/cors.md: ########## @@ -23,35 +28,38 @@ title: cors ## 描述 -`cors` 插件可以让你为服务端启用 [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) 的返回头。 +`cors` 插件可以让你轻松地为服务端启用 [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)（Cross-Origin Resource Sharing，跨域资源共享）的返回头。 ## 属性 -| 名称 | 类型 | 可选项 | 默认值 | 有效值 | 描述 | -| ---------------- | ------- | ------ | ------ | ------ | ------------------------------------------------------------ | -| allow_origins | string | 可选 | "*" | | 允许跨域访问的 Origin，格式如：`scheme`://`host`:`port`，比如: https://somehost.com:8081 。多个值使用 `,` 分割，`allow_credential` 为 `false` 时可以使用 `*` 来表示所有 Origin 均允许通过。你也可以在启用了 `allow_credential` 后使用 `**` 强制允许所有 Origin 都通过，但请注意这样存在安全隐患。 | -| allow_methods | string | 可选 | "*" | | 允许跨域访问的 Method，比如: `GET`，`POST`等。多个值使用 `,` 分割，`allow_credential` 为 `false` 时可以使用 `*` 来表示所有 Origin 均允许通过。你也可以在启用了 `allow_credential` 后使用 `**` 强制允许所有 Method 都通过，但请注意这样存在安全隐患。 | -| allow_headers | string | 可选 | "*" | | 允许跨域访问时请求方携带哪些非 `CORS 规范` 以外的 Header， 多个值使用 `,` 分割，`allow_credential` 为 `false` 时可以使用 `*` 来表示所有 Header 均允许通过。你也可以在启用了 `allow_credential` 后使用 `**` 强制允许所有 Header 都通过，但请注意这样存在安全隐患。 | -| expose_headers | string | 可选 | "*" | | 允许跨域访问时响应方携带哪些非 `CORS 规范` 以外的 Header， 多个值使用 `,` 分割，`allow_credential` 为 `false` 时可以使用 `*` 来表示允许任意 Header 。你也可以在启用了 `allow_credential` 后使用 `**` 强制允许任意 Header，但请注意这样存在安全隐患。 | -| max_age | integer | 可选 | 5 | | 浏览器缓存 CORS 结果的最大时间，单位为秒，在这个时间范围内浏览器会复用上一次的检查结果，`-1` 表示不缓存。请注意各个浏览器允许的最大时间不同，详情请参考 [MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Max-Age#Directives)。 | -| allow_credential | boolean | 可选 | false | | 是否允许跨域访问的请求方携带凭据（如 Cookie 等）。根据 CORS 规范，如果设置该选项为 `true`，那么将不能在其他选项中使用 `*`。 | -| allow_origins_by_regex | array | 可选 | nil | | 使用正则表达式数组来匹配允许跨域访问的 Origin，如 [".*\.test.com"] 可以匹配任何 test.com 的子域名`*`。 | -| allow_origins_by_metadata | array | 可选 | nil | | 通过引用插件元数据的 `allow_origins` 配置允许跨域访问的 Origin。比如当元数据为 `"allow_origins": {"EXAMPLE": "https://example.com"}` 时，配置 `["EXAMPLE"]` 将允许 Origin `https://example.com` 的访问 | - -> **提示** -> -> 请注意 `allow_credential` 是一个很敏感的选项，谨慎选择开启。开启之后，其他参数默认的 `*` 将失效，你必须显式指定它们的值。 -> 使用 `**` 时要充分理解它引入了一些安全隐患，比如 CSRF，所以确保这样的安全等级符合自己预期再使用。 +| 名称 | 类型 | 必选项 | 默认值 | 描述 | +| ---------------- | ------- | ------ | ------ | ------------------------------------------------------------ | +| allow_origins | string | 否 | "*" | 允许跨域访问的 Origin，格式如：`scheme://host:port`，比如：`https://somedomain.com:8081`。多个值使用 `,` 分隔。 `allow_credential` 为 `false` 可以使用 `*` 来表示所有 Origin 均允许通过。你也可以在启用了 `allow_credential` 后使用 `**` 强制允许所有 Origin 均通过，但请注意这样存在安全隐患。 | +| allow_methods | string | 否 | "*" | 允许跨域访问的 Method，比如：`GET`，`POST` 等。多个值使用 `,` 分割，`allow_credential` 为 `false` 时可以使用 `*` 来表示所有 Method 均允许通过。你也可以在启用了 `allow_credential` 后使用 `**` 强制允许所有 Method 都通过，但请注意这样存在安全隐患。 | +| allow_headers | string | 否 | "*" | 允许跨域访问时请求方携带哪些非 `CORS 规范` 以外的 Header，多个值使用 `,` 分割，`allow_credential` 为 `false` 时可以使用 `*` 来表示所有 Header 均允许通过。你也可以在启用了 `allow_credential` 后使用 `**` 强制允许所有 Header 都通过，但请注意这样存在安全隐患。 | +| expose_headers | string | 否 | "*" | 允许跨域访问时响应方携带哪些非 `CORS 规范` 以外的 Header，多个值使用 `,` 分割，`allow_credential` 为 `false` 时可以使用 `*` 来表示允许任意 Header 。你也可以在启用了 `allow_credential` 后使用 `**` 强制允许任意 Header，但请注意这样存在安全隐患。 | +| max_age | integer | 否 | 5 | 浏览器缓存 CORS 结果的最大时间，单位为秒。在这个时间范围内，浏览器会复用上一次的检查结果，`-1` 表示不缓存。请注意各个浏览器允许的最大时间不同，详情请参考 [Access-Control-Max-Age - MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Max-Age#directives)。 | +| allow_credential | boolean | 否 | false | 是否允许跨域访问的请求方携带凭据（如 Cookie 等）。根据 CORS 规范，如果设置该选项为 `true`，那么将不能在其他属性中使用 `*`。 | +| allow_origins_by_regex | array | 否 | nil | 使用正则表达式数组来匹配允许跨域访问的 Origin，如 `[".*\.test.com"]` 可以匹配任何 `test.com` 的子域名 `*`。 | +| allow_origins_by_metadata | array | 否 | nil | 通过引用插件元数据的 `allow_origins` 配置允许跨域访问的 Origin。比如当插件元数据为 `"allow_origins": {"EXAMPLE": "https://example.com"}` 时，配置 `["EXAMPLE"]` 将允许 Origin `https://example.com` 的访问。 | + +:::info IMPORTANT + +请注意， `allow_credential` 是一个很敏感的选项，谨慎选择开启。开启之后，其他参数默认的 `*` 将失效，你必须显式指定它们的值。使用 `**` 时要充分理解它引入的一些安全隐患，比如 CSRF，并确保这样的安全等级符合自己预期。 + +::: ## 元数据 -| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 | -| ----------- | ------ | ------ | ----- | ----- | ------------------ | -| allow_origins | object | 可选 | | | 定义允许跨域访问的 Origin；它的键为 `allow_origins_by_metadata` 使用的引用键， 值则为允许跨域访问的 Origin，其语义与 `allow_origins` 相同 | +| 名称 | 类型 | 必选项 | 描述 | +| ----------- | ------ | ------ | ------------------ | +| allow_origins | object | 否 | 定义允许跨域访问的 Origin；它的键为 `allow_origins_by_metadata` 使用的引用键，值则为允许跨域访问的 Origin，其语义与 `allow_origins` 相同。 | -## 如何启用 +## 启用插件 -创建 `Route` 或 `Service` 对象，并配置 `cors` 插件。 +你可以在一个特定路由或服务上启用 `cors` 插件。 + +以下示例展示了如何创建 `Route` 对象，并在其上配置 `cors` 插件： Review Comment: ```suggestion 你可以通过如下命令在指定路由上启用 `cors` 插件： ``` ########## docs/zh/latest/plugins/cors.md: ########## @@ -71,10 +79,15 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13 ## 测试插件 -请求下接口，发现接口已经返回了 `CORS` 相关的 header，代表插件生效 +启用插件后，使用 curl 命令向服务器请求接口： Review Comment: ```suggestion 通过上述命令启用插件后，可以使用如下命令测试插件是否启用成功： ``` -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
