> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# s3_allow_* 会话设置

> s3_allow_* 生成组中的 ClickHouse 会话设置。

export const SettingsInfoBlock = ({type, default_value, changeable_without_restart}) => {
  return <div className="not-prose" style={{
    display: "flex",
    flexWrap: "wrap",
    alignItems: "baseline",
    columnGap: "0.5rem",
    rowGap: "0.125rem",
    margin: "0.375rem 0",
    fontSize: "0.8125rem",
    lineHeight: "1.125rem"
  }}>
      <div style={{
    fontWeight: 600,
    opacity: 0.72
  }}>类型</div>
      <div style={{
    overflowWrap: "anywhere"
  }}>{type}</div>
      <div style={{
    fontWeight: 600,
    opacity: 0.72,
    marginInlineStart: "0.5rem"
  }}>默认值</div>
      <div style={{
    overflowWrap: "anywhere"
  }}>{default_value}</div>
      {changeable_without_restart && <div style={{
    fontWeight: 600,
    opacity: 0.72,
    marginInlineStart: "0.5rem"
  }}>
          无需重启即可更改
        </div>}
      {changeable_without_restart && <div style={{
    overflowWrap: "anywhere"
  }}>
          {changeable_without_restart}
        </div>}
    </div>;
};

这些设置可在 [system.settings](/docs/zh/reference/system-tables/settings) 中查看，并由 [源代码](https://github.com/ClickHouse/ClickHouse/blob/master/src/Core/Settings.cpp) 自动生成。

<div id="s3_allow_multipart_copy">
  ## s3\_allow\_multipart\_copy
</div>

<SettingsInfoBlock type="Bool" default_value="1" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "25.2"},{"label": "1"},{"label": "新增设置。"}]}]} />

允许在 S3 中使用多部分复制。

<div id="s3_allow_parallel_part_upload">
  ## s3\_allow\_parallel\_part\_upload
</div>

<SettingsInfoBlock type="Bool" default_value="1" />

使用多个线程执行 S3 分段上传。这可能会略微增加内存占用

<div id="s3_allow_server_credentials_in_user_queries">
  ## s3\_allow\_server\_credentials\_in\_user\_queries
</div>

<SettingsInfoBlock type="Bool" default_value="0" />

<VersionHistory rows={[{"id": "row-1","items": [{"label": "26.7"},{"label": "0"},{"label": "新增设置，用于阻止来自用户 SQL 的 S3 访问解析服务器自身的 ambient credentials（environment\/IMDS\/IRSA\/instance-profile\/AWS-config-file\/role_arn-STS\/GCP-OAuth-metadata）。可通过 compatibility 设置恢复此前的行为（允许）。"}]}]} />

允许源自用户 SQL 的 S3 访问使用服务器管理的凭证。

禁用时 (默认值) ，`s3`/`s3Cluster` 表函数、`S3`/`S3Queue` 引擎、S3 命名集合、动态 `disk(type=s3, ...)` 定义、`BACKUP`/`RESTORE TO S3`、DataLake 表数据读取，以及 `DataLakeCatalog` 数据库 (Glue、BigLake) 都不能从环境、实例元数据 (IMDS) 、IRSA、ECS、实例 profile、SSO、AWS config/credentials 文件、基于 `role_arn` 的 STS assume-role 或 GCP OAuth 元数据服务中解析凭证。如果某个请求要求使用这些服务器管理的来源之一 (例如 `use_environment_credentials = 1`、某个 `role_arn` 或 `http_client = gcp_oauth`) ，却没有提供可用的显式凭证，则会以 `ACCESS_DENIED` 拒绝。如果请求不要求其中任何一种，则会以未签名 (匿名) 方式发送，与提供 `NOSIGN` 时相同。

是否将无凭证请求视为请求环境凭证，由 `use_environment_credentials` 决定。命名集合默认将其设为 `0`，因此仅指定 URL 的集合会以匿名方式读取。`s3`/`s3Cluster` 表函数和 `S3`/`S3Queue` 引擎除非服务器的 `<s3>` config 另有设置，否则使用内置默认值 (`1`) ；将 `<s3><use_environment_credentials>0</use_environment_credentials></s3>` 设为使它们的无凭证读取默认也以匿名方式进行 (否则此类请求会被拒绝，并且必须使用 `NOSIGN`) 。在 server configuration 中定义的 disk 不受影响，默认仍使用环境凭证；而用户创建的动态 `disk(type = s3, ...)` 定义则受该限制约束 (见上文) ，当它们依赖默认值/环境凭证时会被拒绝。

这可防止已身份验证的用户让服务器使用其自身的 (ambient) 凭证访问 S3。显式提供的凭证不受影响：在查询中传入的 keys、命名集合中的静态 keys (通过 SQL 创建或在 config 中定义) ，以及服务器 `<s3>` config 中的 keys，都会继续正常工作。

向用户查询授予 S3 访问权限的推荐方式，是使用带有显式凭证的命名集合 (公共存储桶则使用 `NOSIGN`) ：这样 keys 不会出现在查询文本中，并且每个集合的使用都通过 RBAC 控制 (`GRANT NAMED COLLECTION ON <name> TO <user>`) ，因此你可以向特定用户授予特定 bucket 的访问权限，而不是暴露服务器自身的身份。

适用范围 (有意不包含的范围) ：此设置仅阻止上面列出的服务器 ambient credential 来源。它不会阻止来自服务器 `<s3>` config 或 config 中定义的命名集合的、由 operator provisioned 的静态 `access_key_id`/`secret_access_key`：这些被视为显式凭证，并会继续生效。不过请注意，诸如 `access_header` 或 server-side-encryption keys 之类的 config 请求材料，在这里本身并不被视为凭证：如果某个请求仅携带此类材料而没有显式 key pair (且默认 `use_environment_credentials = 1`) ，仍然会被拒绝，因为否则它会回退到服务器的 ambient credentials。此类 endpoint 还必须提供显式 keys、`NOSIGN`、`use_environment_credentials = 0`，或使用下面的例外通道。

受信任的管理客户端可能出于合法操作需要服务器管理的凭证 (例如，通过 SQL 在 `s3_plain_rewritable` disk 上附加系统表) 。在该客户端的会话或 settings profile 中启用此设置即可允许这样做。

对于 `BACKUP`/`RESTORE ... ON CLUSTER`，此设置在 initiator 上的值会传播到其他 hosts，并在这些主机上原样使用。这些 hosts 通过 distributed DDL queue 运行操作在各主机上的后续部分，默认情况下不带 initiator 的用户，因此否则它们会根据自身的 default profile 来评估该限制；这里会保留 initiator 的值，因为它已经在自身受限的 settings 下打开了同一个 backup destination。对 initiator 的 `readonly` 约束仍然适用 (不受信任的 initiator 不能为其自身的 on-cluster backup 启用该设置) ，因此这不会削弱该限制。

对于持久化的 `S3` 和 `S3Queue` 表：如果只在 session 或 profile 中启用此项，重启后不会持续生效。当 server 根据已存储的定义重新加载这类表时 (在启动时或执行 `RESTORE` 时) ，它会重建 S3 client，并使用启动 Context 重新应用该限制。因此，那些依赖服务器管理的凭证、且仅在 session/profile `s3_allow_server_credentials_in_user_queries = 1` 下创建的表，虽然可以成功创建，但在重启后会变得无法访问 (表本身仍会保留；对其执行的查询会失败，直到其凭据再次解析到允许的来源) 。不过，server 本身仍然可以启动。要让这类表获得持久访问能力，请为其提供显式凭证；或者，也可以在整个 server 范围内启用该 setting，这样它们在重启后仍可被加载，但代价是对所有重新加载都放宽了这一限制。

为了让不受信任的用户始终保持禁用状态，请在其 profile 中固定该项：显式将其值设为 `0`，并将其标记为 `readonly`：

```xml theme={null}
<profiles>
    <untrusted>
        <!-- The explicit value is required: a `readonly` constraint alone only blocks direct changes,
             but `compatibility` with a version before this setting was introduced would otherwise
             restore the old (allowing) default. Setting the value explicitly defeats `compatibility`. -->
        <s3_allow_server_credentials_in_user_queries>0</s3_allow_server_credentials_in_user_queries>
        <constraints>
            <s3_allow_server_credentials_in_user_queries>
                <readonly/>
            </s3_allow_server_credentials_in_user_queries>
        </constraints>
    </untrusted>
</profiles>
```

此设置在 `clickhouse-local` 中不生效，因为用户就是 operator。

`DataLakeCatalog` 数据库 (Glue、BigLake) 也适用，但有一点不同。catalog 对象只创建一次，并由该数据库的所有用户共享，因此无法按查询读取其值；它会从执行 `CREATE DATABASE` (或用户执行 `ATTACH DATABASE`) 的 session 中捕获。在启用此设置时创建的数据库 (例如在受信任的 session 或 profile 中) 可能会让其 catalog 使用 server 的 ambient credentials，而之后所有能够查询该数据库的用户都会共享这些 credentials；如果在默认设置下创建，则无论由谁查询，该 catalog 都会对所有人受限。当 server 从自身的 metadata 中加载一个已创建的数据库 (启动时、`RESTORE`) 时，会使用启动 context 重新施加这一限制，这与持久化 `S3`/`S3Queue` 表相同：如果某个 catalog 解析到服务器管理的凭证，它就会保持不可用，并且该数据库会在重启后变得不可访问 (server 仍会启动；该数据库会按照 `s3_load_table_anonymously_if_credentials_restricted` 以 catalog 不可用的状态加载，并且查询会报告该限制) 。而提供了显式凭证的 catalog (Glue：`aws_access_key_id` 和 `aws_secret_access_key`；BigLake：完整的 Google ADC 三元组) 则始终可用，并且在重启后仍然有效。