fix: cloud advanced usage for cn (#2946)

everpcpc · web-flow · commit 409a32e66277 · 2025-11-07T18:50:55.000+08:00
diff --git a/docs/cn/guides/20-cloud/10-using-databend-cloud/01-warehouses.md b/docs/cn/guides/20-cloud/10-using-databend-cloud/01-warehouses.md
@@ -208,4 +208,4 @@ GRANT ALL ON my_database.* TO warehouse_user1;
 
 ### 连接安全性
 
-默认情况下，所有到 Databend Cloud 计算集群的连接都使用 TLS 加密。对于需要额外安全性的企业用户，可以使用 [AWS PrivateLink](/guides/sql-clients/privatelink) 在您的 VPC 和 Databend Cloud 之间建立私有连接。
+默认情况下，所有到 Databend Cloud 计算集群的连接都使用 TLS 加密。对于需要额外安全性的企业用户，可以使用 [AWS PrivateLink](/guides/cloud/advanced/private-link) 在您的 VPC 和 Databend Cloud 之间建立私有连接。
diff --git a/docs/cn/guides/20-cloud/30-advanced/01-iam-role/01-aws.md b/docs/cn/guides/20-cloud/30-advanced/01-iam-role/01-aws.md
@@ -1,11 +1,8 @@
 ---
-title: "使用 AWS IAM 角色创建外部 Stage"
+title: "使用 AWS IAM 角色进行认证"
+sidebar_label: "AWS IAM 角色"
 ---
 
-# 为什么选择 IAM 角色
-
-通过 AWS IAM 角色，您可以在 Databend Cloud 中访问自己的 AWS S3 存储桶。这种方式无需管理 AWS 凭证即可安全访问数据并进行数据分析。
-
 # 如何使用 IAM 角色
 
 1. 提交工单获取您 Databend Cloud 组织的 IAM 角色 ARN：
@@ -57,6 +54,11 @@ title: "使用 AWS IAM 角色创建外部 Stage"
          "Principal": {
            "AWS": "arn:aws:iam::123456789012:role/xxxxxxx/tnabcdefg/xxxxxxx-tnabcdefg"
          },
+         "Condition": {
+           "StringEquals": {
+             "sts:ExternalId": "my-external-id-123"
+           }
+         },
          "Action": "sts:AssumeRole"
        }
      ]
@@ -72,7 +74,7 @@ title: "使用 AWS IAM 角色创建外部 Stage"
 4. 在 Databend Cloud 工作区或 `BendSQL` 中执行以下 SQL 语句：
 
    ```sql
-   CREATE CONNECTION databend_test STORAGE_TYPE = 's3' ROLE_ARN = 'arn:aws:iam::987654321987:role/databend-test';
+   CREATE CONNECTION databend_test STORAGE_TYPE = 's3' ROLE_ARN = 'arn:aws:iam::987654321987:role/databend-test' EXTERNAL_ID = 'my-external-id-123';
 
    CREATE STAGE databend_test URL = 's3://test-bucket-123' CONNECTION = (CONNECTION_NAME = 'databend_test');
 
@@ -81,4 +83,4 @@ title: "使用 AWS IAM 角色创建外部 Stage"
 
 :::info
 恭喜！您现在可以通过 IAM 角色在 Databend Cloud 中访问自己的 AWS S3 存储桶了。
-:::
+:::
diff --git a/docs/cn/guides/20-cloud/30-advanced/01-iam-role/_category_.json b/docs/cn/guides/20-cloud/30-advanced/01-iam-role/_category_.json
@@ -0,0 +1,3 @@
+{
+  "label": "IAM 角色"
+}
diff --git a/docs/cn/guides/20-cloud/30-advanced/01-iam-role/index.md b/docs/cn/guides/20-cloud/30-advanced/01-iam-role/index.md
@@ -0,0 +1,22 @@
+---
+title: IAM 角色
+---
+
+import IndexOverviewList from '@site/src/components/IndexOverviewList';
+
+# 为什么选择 IAM 角色
+
+云原生的身份委托能力（如 AWS IAM Role、Azure Managed Identity、Google Service Account Federation 等）可以让 Databend Cloud 获取短期凭证，而无需接触长期 Access Key。这样既能把数据平面访问留在您的云账户内，又能让您始终掌控权限。
+
+## 优势
+
+- 无需长期密钥：短期凭证消除了泄露或轮换长期密钥的风险。
+- 最小权限：精细化策略可确保 Databend Cloud 只访问您授权的桶和操作。
+- 集中治理：继续通过既有 IAM 工作流进行审计、吊销和审批。
+- 自动轮换：云厂商负责刷新令牌，团队变动也不会中断访问。
+
+## 工作原理
+
+当 Databend Cloud 支持团队提供您组织的受信主体信息后，您需要在自己的云账户中创建 IAM 角色或身份，授予访问对象存储所需的最小权限，并在信任策略中指定只允许 Databend Cloud 使用唯一的 External ID 来扮演该角色。此后 Databend Cloud 会按需假设该角色，使用短期凭证访问存储，并在会话结束后自动退出。
+
+<IndexOverviewList />
diff --git a/docs/cn/guides/20-cloud/30-advanced/02-private-link/01-aws.md b/docs/cn/guides/20-cloud/30-advanced/02-private-link/01-aws.md
@@ -3,32 +3,21 @@ title: "通过 AWS PrivateLink 连接到 Databend Cloud"
 sidebar_label: "AWS PrivateLink"
 ---
 
-# 为什么选择 PrivateLink
-
-通过 AWS PrivateLink 连接到 Databend Cloud 提供了一种安全且私密的方式来访问 Databend Cloud 服务，而无需经过公共互联网。
-
-通过利用 AWS PrivateLink，您可以在您的 Virtual Private Cloud (VPC) 和 Databend Cloud 之间建立私有连接，确保您的数据保留在您的 VPC 边界内，并且不会暴露于互联网。此设置增强了数据的安全性，并最大限度地降低了未经授权访问的风险。
-
-要使用 AWS PrivateLink 连接到 Databend Cloud，您需要在 VPC 中配置一个 VPC 终端节点。此终端节点充当代理，允许流量在您的 VPC 和 Databend Cloud 之间安全地流动。VPC 终端节点在您的 VPC 中具有私有 IP 地址，并有助于与 Databend Cloud 服务进行直接通信。
-
-建立 VPC 终端节点后，您可以使用私有 IP 地址安全地访问 Databend Cloud 服务，例如数据存储、数据处理和分析工具。这确保了您的数据保留在 VPC 的安全边界内，从而提供额外的保护层。
-
 # 如何设置 AWS PrivateLink
 
 1. 提供您计划连接到 Databend Cloud 的 AWS 账户 ID：
 
-   例如：`952853449216`
+   例如：`123456789012`
 
 2. 验证您的 VPC 设置
 
    ![VPC 设置](/img/cloud/privatelink/vpc-settings.png)
 
    确保选中 `启用 DNS 解析` 和 `启用 DNS 主机名`。
 
-3. 等待云管理员将您的帐户添加到白名单，并获取要连接的集群的服务名称：
+3. 等待云管理员将您的账户添加到白名单，并获取要连接的集群服务名称：
 
-   - `com.amazonaws.vpce.us-east-2.vpce-svc-0e494364a37d35445` (aws, us-east-2, white)
-   - `com.amazonaws.vpce.us-east-1.vpce-svc-0d9cd5a4a7c19796f` (aws, us-east-1, ivory)
+   例如：`com.amazonaws.vpce.us-east-2.vpce-svc-0123456789abcdef0`
 
 4. 准备一个打开 tcp 443 端口的安全组：
 
diff --git a/docs/cn/guides/20-cloud/30-advanced/02-private-link/_category_.json b/docs/cn/guides/20-cloud/30-advanced/02-private-link/_category_.json
@@ -0,0 +1,3 @@
+{
+  "label": "Private Link"
+}
diff --git a/docs/cn/guides/20-cloud/30-advanced/02-private-link/index.md b/docs/cn/guides/20-cloud/30-advanced/02-private-link/index.md
@@ -0,0 +1,22 @@
+---
+title: Private Link
+---
+
+import IndexOverviewList from '@site/src/components/IndexOverviewList';
+
+# 为什么选择 PrivateLink
+
+各大云厂商提供的 PrivateLink/Private Endpoint（AWS PrivateLink、Azure Private Link、Google Private Service Connect 等）允许您在自己的网络边界内通过私有 IP 访问 Databend Cloud，整个链路无需穿越公网。这能让数据集、凭据和管理操作都留在云厂商骨干网上，并遵循您现有的网络策略。
+
+## 优势
+
+- 网络隔离：流量始终停留在 VPC/VPN 内，避免暴露到公网上。
+- 合规友好：更容易满足禁止公网出口的内审或行业规范。
+- 性能稳定：走云厂商骨干而不是不可控的互联网线路。
+- 简化管控：沿用既有的安全组、路由表和监控手段。
+
+## 工作原理
+
+当 Databend Cloud 审批了您计划接入的云账户或项目后，您即可创建指向所在区域 Databend 服务的私有终端节点。启用私有 DNS 后，Databend Cloud 域名会解析到这些私有 IP，所有会话都会自动通过安全的私有链路传输。
+
+<IndexOverviewList />
diff --git a/docs/cn/guides/20-cloud/30-advanced/_category_.json b/docs/cn/guides/20-cloud/30-advanced/_category_.json
@@ -0,0 +1,3 @@
+{
+  "label": "高级用法"
+}
diff --git a/docs/cn/guides/20-cloud/30-advanced/index.md b/docs/cn/guides/20-cloud/30-advanced/index.md
@@ -0,0 +1,7 @@
+---
+title: 高级用法
+---
+
+import IndexOverviewList from '@site/src/components/IndexOverviewList';
+
+<IndexOverviewList />
diff --git a/docs/cn/guides/30-sql-clients/index.md b/docs/cn/guides/30-sql-clients/index.md
@@ -27,10 +27,3 @@ Databend 支持多种连接方式以适应不同的使用场景。以下所有 S
 | **Node.js** | JavaScript 驱动 | Web 应用程序 | [Node.js 指南](/guides/sql-clients/developers/nodejs) |
 | **Java** | JDBC 驱动 | 企业应用程序 | [JDBC 指南](/guides/sql-clients/developers/jdbc) |
 | **Rust** | 原生驱动 | 系统编程 | [Rust 指南](/guides/sql-clients/developers/rust) |
-
-## 连接方式
-
-| 方式 | 安全级别 | 使用场景 | 设置复杂度 |
-|--------|----------------|----------|------------------|
-| **直接连接** | 标准 | 开发、测试 | ⭐ 简单 |
-| **[AWS PrivateLink](/guides/sql-clients/privatelink)** | 高 | 生产、企业 | ⭐⭐⭐ 高级 |
diff --git a/docs/cn/sql-reference/10-sql-commands/00-ddl/01-table/91-alter-table-connection.md b/docs/cn/sql-reference/10-sql-commands/00-ddl/01-table/91-alter-table-connection.md
@@ -32,7 +32,7 @@ ALTER TABLE [ <database_name>. ]<table_name> CONNECTION = ( connection_name = '<
 - **自动轮换**：自动处理凭据轮换
 - **细粒度控制**：支持更精确的访问控制
 
-要在 Databend Cloud 中使用 IAM 角色，请参阅[使用 AWS IAM 角色创建外部暂存区（Stage）](/guides/load-data/stage/aws-iam-role)获取指南。
+要在 Databend Cloud 中使用 IAM 角色，请参阅[使用 AWS IAM 角色进行认证](/guides/cloud/advanced/iam-role)获取指南。
 
 ## 示例
 
@@ -57,8 +57,8 @@ CREATE OR REPLACE TABLE external_table_test (
     id INT,
     name VARCHAR,
     age INT
-) 
-'s3://testbucket/13_fuse_external_table/' 
+)
+'s3://testbucket/13_fuse_external_table/'
 CONNECTION=(connection_name = 'external_table_conn');
 
 -- 更新表以使用包含轮换凭据的新连接
@@ -80,8 +80,8 @@ CREATE TABLE sales_data (
     order_id INT,
     product_name VARCHAR,
     quantity INT
-) 
-'s3://sales-bucket/data/' 
+)
+'s3://sales-bucket/data/'
 CONNECTION=(connection_name = 's3_access_key_conn');
 
 -- 稍后，使用 IAM 角色身份验证创建新连接
@@ -91,4 +91,4 @@ CREATE CONNECTION s3_role_conn
 
 -- 更新表以使用 IAM 角色连接
 ALTER TABLE sales_data CONNECTION=( connection_name = 's3_role_conn' );
-```
+```
diff --git a/docs/cn/sql-reference/10-sql-commands/00-ddl/13-connection/create-connection.md b/docs/cn/sql-reference/10-sql-commands/00-ddl/13-connection/create-connection.md
@@ -17,8 +17,8 @@ import TabItem from '@theme/TabItem';
 ## 语法
 
 ```sql
-CREATE [ OR REPLACE ] CONNECTION [ IF NOT EXISTS ] <connection_name> 
-    STORAGE_TYPE = '<type>' 
+CREATE [ OR REPLACE ] CONNECTION [ IF NOT EXISTS ] <connection_name>
+    STORAGE_TYPE = '<type>'
     [ <storage_params> ]
 ```
 
@@ -51,9 +51,9 @@ Amazon S3 及兼容服务支持以下两种认证方式：
 <TabItem value="access-keys" label="Access Keys">
 
 ```sql
-CREATE CONNECTION <connection_name> 
-    STORAGE_TYPE = 's3' 
-    ACCESS_KEY_ID = '<your-access-key-id>' 
+CREATE CONNECTION <connection_name>
+    STORAGE_TYPE = 's3'
+    ACCESS_KEY_ID = '<your-access-key-id>'
     SECRET_ACCESS_KEY = '<your-secret-access-key>';
 ```
 
@@ -66,8 +66,8 @@ CREATE CONNECTION <connection_name>
 <TabItem value="iam-role" label="IAM Role">
 
 ```sql
-CREATE CONNECTION <connection_name> 
-    STORAGE_TYPE = 's3' 
+CREATE CONNECTION <connection_name>
+    STORAGE_TYPE = 's3'
     ROLE_ARN = '<your-role-arn>';
 ```
 
@@ -155,13 +155,13 @@ CREATE CONNECTION <connection_name>
 示例：创建名为 toronto 的 Amazon S3 连接，并建立外部 Stage `my_s3_stage` 指向 `s3://databend-toronto`。更多与连接相关的示例请参阅 [使用示例](index.md#usage-examples)。
 
 ```sql
-CREATE CONNECTION toronto 
-    STORAGE_TYPE = 's3' 
+CREATE CONNECTION toronto
+    STORAGE_TYPE = 's3'
     ACCESS_KEY_ID = '<your-access-key-id>'
     SECRET_ACCESS_KEY = '<your-secret-access-key>';
 
-CREATE STAGE my_s3_stage 
-    URL = 's3://databend-toronto' 
+CREATE STAGE my_s3_stage
+    URL = 's3://databend-toronto'
     CONNECTION = (CONNECTION_NAME = 'toronto');
 ```
 
@@ -170,18 +170,18 @@ CREATE STAGE my_s3_stage
 示例：使用 IAM Role 创建 Amazon S3 连接，并让 Stage 复用该连接，无需在 Databend 中存储访问密钥。
 
 ```sql
-CREATE CONNECTION databend_test 
-    STORAGE_TYPE = 's3' 
+CREATE CONNECTION databend_test
+    STORAGE_TYPE = 's3'
     ROLE_ARN = 'arn:aws:iam::987654321987:role/databend-test';
 
-CREATE STAGE databend_test 
-    URL = 's3://test-bucket-123' 
+CREATE STAGE databend_test
+    URL = 's3://test-bucket-123'
     CONNECTION = (CONNECTION_NAME = 'databend_test');
 
 -- 现在可直接查询 S3 桶中的数据
 SELECT * FROM @databend_test/test.parquet LIMIT 1;
 ```
 
 :::info
-在 Databend Cloud 中使用 IAM 角色，需要在 AWS 账户与 Databend Cloud 之间建立信任关系。详见 [使用 AWS IAM 角色创建外部 Stage](/guides/load-data/stage/aws-iam-role)。
+在 Databend Cloud 中使用 IAM 角色，需要在 AWS 账户与 Databend Cloud 之间建立信任关系。详见 [使用 AWS IAM 角色进行认证](/guides/cloud/advanced/iam-role)。
 :::

Original file line number	Diff line number	Diff line change
`@@ -208,4 +208,4 @@ GRANT ALL ON my_database.* TO warehouse_user1;`
`208`	`208`
`209`	`209`	`### 连接安全性`
`210`	`210`
`211`		`-默认情况下，所有到 Databend Cloud 计算集群的连接都使用 TLS 加密。对于需要额外安全性的企业用户，可以使用 [AWS PrivateLink](/guides/sql-clients/privatelink) 在您的 VPC 和 Databend Cloud 之间建立私有连接。`
	`211`	`+默认情况下，所有到 Databend Cloud 计算集群的连接都使用 TLS 加密。对于需要额外安全性的企业用户，可以使用 [AWS PrivateLink](/guides/cloud/advanced/private-link) 在您的 VPC 和 Databend Cloud 之间建立私有连接。`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+{`
	`2`	`+ "label": "Private Link"`
	`3`	`+}`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+{`
	`2`	`+ "label": "高级用法"`
	`3`	`+}`