> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8c05c8a2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> 使用 Vector 为 ClickStack 摄取数据 - ClickHouse 可观测性技术栈

# 使用 Vector 摄取数据

export const Image = ({img, alt, size}) => {
  return <Frame>
      <img src={img} alt={alt} />
    </Frame>;
};

[Vector](https://vector.dev) 是一个高性能、厂商中立的可观测性数据管道。它通常用于从各种来源收集、转换和路由日志与指标，并因其灵活性高、资源占用低而被广泛采用，尤其常用于日志摄取。

将 Vector 与 ClickStack 结合使用时，用户需要自行定义 schema。这些 schema 可以遵循 OpenTelemetry 约定，也可以完全自定义，用来表示用户定义的事件结构。在实际使用中，Vector 摄取最常见的用途是处理**日志**，因为用户希望在数据写入 ClickHouse 之前，能够完全掌控解析和富集过程。

本指南重点介绍如何使用 Vector 将数据导入 ClickStack，适用于 ClickStack Open Source 和托管 ClickStack。为便于说明，本文不会深入展开介绍 Vector source 或管道配置，而是重点说明如何配置将数据写入 ClickHouse 的 **sink**，并确保最终生成的 schema 与 ClickStack 兼容。

对于 ClickStack，无论使用开源部署还是托管部署，唯一的硬性要求是数据中必须包含一个**timestamp 列** (或等效的时间字段) ；该列可在 ClickStack UI 中配置数据源时声明。

<div id="sending-data-with-vector">
  ## 通过 Vector 发送数据
</div>

<br />

<Tabs>
  <Tab title="托管 ClickStack">
    以下指南假设您已创建托管 ClickStack 服务并记录了相应的服务凭据。如果尚未完成，请先参阅托管 ClickStack 的 [Getting Started](/zh/clickstack/getting-started/managed) 指南，按步骤操作至提示配置 Vector 为止。

    <Steps>
      <Step>
        ### 创建数据库和表

        Vector 要求在摄取数据之前预先定义好表和 schema。

        首先创建一个数据库。可以通过 [ClickHouse Cloud 控制台](/zh/products/cloud/features/sql-console-features/sql-console) 完成。

        在下面的示例中，我们使用 `logs`：

        ```sql theme={null}
        CREATE DATABASE IF NOT EXISTS logs
        ```

        为您的数据创建一个表。该表应与数据的输出 schema 相匹配。下面的示例假设采用经典的 Nginx 结构。请根据您的数据进行相应调整，并遵循 [schema 最佳实践](/zh/concepts/best-practices/select-data-type)。我们**强烈建议**您先了解[主键的概念](/zh/concepts/core-concepts/primary-indexes)，并根据[此处](/zh/clickstack/managing/performance-tuning#choosing-a-primary-key)列出的指南选择主键。

        ```sql theme={null}
        CREATE TABLE logs.nginx_logs
        (
            `time_local` DateTime,
            `remote_addr` IPv4,
            `remote_user` LowCardinality(String),
            `request` String,
            `status` UInt16,
            `body_bytes_sent` UInt64,
            `http_referer` String,
            `http_user_agent` String,
            `http_x_forwarded_for` LowCardinality(String),
            `request_time` Float32,
            `upstream_response_time` Float32,
            `http_host` String
        )
        ENGINE = MergeTree
        ORDER BY (toStartOfMinute(time_local), status, remote_addr)
        ```

        <Info>
          **Nginx 主键**

          上述主键是基于 ClickStack UI 中 Nginx 日志的常见访问模式设定的，但在生产环境中可能需要根据你的工作负载进行调整。
        </Info>
      </Step>

      <Step>
        ### 在 Vector 配置中添加 ClickHouse sink

        修改 Vector 配置，加入 ClickHouse sink，并更新 `inputs` 字段，使其从现有管道接收事件。

        此配置假定你的上游 Vector 管道已经**将数据处理为符合目标 ClickHouse schema 的格式**，也就是说，各字段都已完成解析、正确命名，并设置为适合插入的类型。有关如何将原始日志行解析并规范化为适用于 ClickStack 的 schema 的完整示例，请参见[**下方的 Nginx 示例**](#example-dataset-with-vector)。

        ```yaml theme={null}
        sinks:
          clickhouse:
            type: clickhouse
            inputs:
              - your_input
            endpoint: "<CLICKHOUSE_ENDPOINT>"
            database: logs
            format: json_each_row
            table: nginx_logs
            skip_unknown_fields: true
            auth:
              strategy: "basic"
              user: "default"
              password: "<CLICKHOUSE_PASSWORD>"
        ```

        默认情况下，我们建议使用 **`json_each_row`** 格式，它会将每个事件编码为每行一个 JSON 对象。这是 ClickStack 摄取 JSON 数据时默认且推荐使用的格式，应优先于其他替代格式，例如将 JSON 对象编码为字符串的格式。

        ClickHouse sink 也支持 **Arrow stream encoding** (目前处于 Beta 阶段) 。这种方式可以提供更高的吞吐量，但也有一些重要约束：数据库和表必须是静态的，因为 schema 只会在启动时拉取一次，并且不支持动态路由。因此，Arrow 编码最适合固定且定义明确的摄取管道。

        我们建议查阅 [Vector documentation](https://vector.dev/docs/reference/configuration/sinks/clickhouse) 中可用的 sink 配置选项：

        <Note>
          上面的示例使用的是托管 ClickStack 的默认用户。对于生产部署，我们建议[创建专用的摄取用户](/zh/clickstack/ingesting-data/collector#creating-an-ingestion-user)，并为其分配适当的权限和限制。
        </Note>
      </Step>

      <Step>
        ### 前往 ClickStack UI

        前往你的托管 ClickStack 服务，并从左侧菜单中选择 "ClickStack"。如果你已经完成引导流程，这将在新标签页中打开 ClickStack UI，并自动完成身份验证。如果尚未完成，你可以继续完成引导流程，并在选择 Vector 作为输入源后点击“Launch ClickStack”。

        <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/mGB-7MnBG_6npuhw/images/clickstack/launch-clickstack-vector.png?fit=max&auto=format&n=mGB-7MnBG_6npuhw&q=85&s=17ddb1720ed82d5007b4bd747f26480d" alt="为 Vector 启动 ClickStack" size="lg" width="1920" height="918" data-path="images/clickstack/launch-clickstack-vector.png" />
      </Step>

      <Step>
        ### 创建数据源

        创建一个日志数据源。如果当前还没有数据源，首次登录时系统会提示你创建一个。否则，请前往 Team Settings，添加一个新的数据源。

        <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/GaEHa-fd8w_5w7tQ/images/clickstack/create-vector-datasource.png?fit=max&auto=format&n=GaEHa-fd8w_5w7tQ&q=85&s=bcf6923c4843a0a9ba198628ea3cfd87" alt="创建数据源 - vector" size="lg" width="3600" height="1938" data-path="images/clickstack/create-vector-datasource.png" />

        上述配置假定采用 Nginx 风格的 schema，并将 `time_local` 列用作时间戳。应尽可能使用在主键中声明的时间戳列。此列为必填项。

        我们还建议更新 `Default SELECT`，明确指定日志视图中返回哪些列。如果还有其他可用字段，例如服务名称、日志级别或 body 列，也可以一并配置。如果时间戳显示列与表主键中使用且在上方配置的列不同，也可以单独覆盖。

        在上面的示例中，数据里并不存在 `Body` 列。相反，它是通过一个 SQL 表达式定义的，用于根据现有字段重建一条 Nginx 日志行。

        有关其他可选项，请参阅[配置参考](/zh/clickstack/managing/config)。
      </Step>

      <Step>
        ### 探查数据

        前往日志视图探查数据，并开始使用 ClickStack。

        <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/mGB-7MnBG_6npuhw/images/clickstack/nginx-logs-vector-search.png?fit=max&auto=format&n=mGB-7MnBG_6npuhw&q=85&s=62db4cb133326072330b5ec95d12f349" alt="ClickStack 中的 Nginx 日志" size="lg" width="3600" height="1906" data-path="images/clickstack/nginx-logs-vector-search.png" />
      </Step>
    </Steps>
  </Tab>

  <Tab title="开源 ClickStack">
    <Steps>
      <Step>
        ### 创建数据库和表

        Vector 要求在摄取数据之前预先定义好表和 schema。

        首先创建一个数据库。可通过 [ClickHouse Web 用户界面](/zh/concepts/features/interfaces/http#web-ui) 访问 [http://localhost:8123/play](http://localhost:8123/play) 来完成。使用默认用户名和密码 `api:api`。

        <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/mGB-7MnBG_6npuhw/images/clickstack/play-ui-clickstack.png?fit=max&auto=format&n=mGB-7MnBG_6npuhw&q=85&s=1bac3511fb24ff4669f04db8998f310f" alt="ClickStack Play UI" size="lg" width="3600" height="1918" data-path="images/clickstack/play-ui-clickstack.png" />

        在下面的示例中，我们使用 `logs`：

        ```sql theme={null}
        CREATE DATABASE IF NOT EXISTS logs
        ```

        为您的数据创建一个表。该表应与数据的输出 schema 相匹配。下面的示例假设采用经典的 Nginx 结构。请根据您的数据相应调整，并遵循 [schema 最佳实践](/zh/concepts/best-practices/select-data-type)。我们**强烈建议**您先熟悉[主键的概念](/zh/concepts/core-concepts/primary-indexes)，并根据[此处](/zh/clickstack/managing/performance-tuning#choosing-a-primary-key)所述指南选择主键。

        ```sql theme={null}
        CREATE TABLE logs.nginx_logs
        (
            `time_local` DateTime,
            `remote_addr` IPv4,
            `remote_user` LowCardinality(String),
            `request` String,
            `status` UInt16,
            `body_bytes_sent` UInt64,
            `http_referer` String,
            `http_user_agent` String,
            `http_x_forwarded_for` LowCardinality(String),
            `request_time` Float32,
            `upstream_response_time` Float32,
            `http_host` String
        )
        ENGINE = MergeTree
        ORDER BY (toStartOfMinute(time_local), status, remote_addr)
        ```

        <Info>
          **Nginx 主键**

          上述主键是基于 ClickStack UI 中 Nginx 日志的常见访问模式设定的，但在生产环境中，可能需要根据实际工作负载进行调整。
        </Info>
      </Step>

      <Step>
        ### 将 ClickHouse sink 添加到 Vector 配置中

        对于 Vector，向 ClickStack 摄取数据时应直接发送到 ClickHouse，绕过 collector 暴露的 OTLP 端点。

        修改 Vector 配置以加入 ClickHouse sink，并更新 `inputs` 字段，使其从现有管道接收事件。

        此配置假定你的上游 Vector 管道已经**将数据处理为与目标 ClickHouse schema 匹配**，也就是说，各个字段都已完成解析、命名正确，并设置了适合插入的类型。有关如何将原始日志行解析并规范化为适用于 ClickStack 的 schema，请参见[**下面的 Nginx 示例**](#example-dataset-with-vector)。

        ```yaml theme={null}
        sinks:
          clickhouse:
            type: clickhouse
            inputs:
              - your_input
            endpoint: "http://localhost:8123"
            database: logs
            format: json_each_row
            table: nginx_logs
            skip_unknown_fields: true
            auth:
              strategy: "basic"
              user: "api"
              password: "api"
        ```

        默认情况下，我们建议使用 **`json_each_row`** 格式，它会将每个事件编码为每行一个 JSON object。这是 ClickStack 在摄取 JSON 数据时默认且推荐使用的格式，应优先于其他替代格式，例如将 JSON objects 编码为字符串的方式。

        ClickHouse sink 还支持 **Arrow stream encoding** (目前处于 Beta 阶段) 。这种方式可以提供更高的吞吐量，但也有一些重要约束：数据库和表必须是静态的，因为 schema 只会在启动时拉取一次，并且不支持动态路由。因此，Arrow encoding 最适合固定且定义明确的摄取管道。

        我们建议在 [Vector documentation](https://vector.dev/docs/reference/configuration/sinks/clickhouse) 中查看可用的 sink 配置选项：

        <Note>
          上面的示例在 ClickStack Open Source 中使用的是 `api` 用户。对于生产部署，我们建议[创建专用的摄取用户](/zh/clickstack/ingesting-data/collector#creating-an-ingestion-user)，并为其设置适当的权限和限制。上述配置还假设 Vector 与 ClickStack 运行在同一台主机上。在生产部署中，通常并非如此。我们建议通过安全的 HTTPS 端口 8443 发送数据。
        </Note>
      </Step>

      <Step>
        ### 访问 ClickStack UI

        访问 [http://localhost:8080](http://localhost:8080) 打开 ClickStack UI。如果你尚未完成引导设置，请先创建一个用户。

        <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/RhEK5rhPj_7m6pWY/images/use-cases/observability/hyperdx-login.png?fit=max&auto=format&n=RhEK5rhPj_7m6pWY&q=85&s=eec6e42744553cd8881cf9c9ada74166" alt="ClickStack 登录" size="lg" width="3600" height="1900" data-path="images/use-cases/observability/hyperdx-login.png" />
      </Step>

      <Step>
        ### 创建数据源

        前往 Team Settings，然后添加一个新的数据源。

        <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/GaEHa-fd8w_5w7tQ/images/clickstack/create-vector-datasource-oss.png?fit=max&auto=format&n=GaEHa-fd8w_5w7tQ&q=85&s=d9917d00228e1219bbacd2a2759eb938" alt="创建数据源 - vector" size="lg" width="3600" height="1940" data-path="images/clickstack/create-vector-datasource-oss.png" />

        上述配置假定使用 Nginx 风格的 schema，并将 `time_local` 列用作 timestamp。在可能的情况下，这一列应当是在主键中声明的 timestamp 列。此列为必填项。

        我们还建议更新 `Default SELECT`，明确指定日志视图中返回哪些列。如果还有其他可用字段，例如 service name、日志级别或 body 列，也可以一并配置。如果 timestamp 显示列不同于表主键中使用且在上方配置的列，也可以单独覆盖。

        在上面的示例中，数据中不存在 `Body` 列。相反，它是通过一个 SQL expression 定义的，用于根据现有字段重建一条 Nginx 日志行。

        如需了解其他可用选项，请参阅[配置参考](/zh/clickstack/managing/config)。
      </Step>

      <Step>
        ### 查看数据

        前往日志视图查看数据，并开始使用 ClickStack。

        <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/mGB-7MnBG_6npuhw/images/clickstack/nginx-logs-vector-search.png?fit=max&auto=format&n=mGB-7MnBG_6npuhw&q=85&s=62db4cb133326072330b5ec95d12f349" alt="ClickStack 中的 Nginx 日志" size="lg" width="3600" height="1906" data-path="images/clickstack/nginx-logs-vector-search.png" />
      </Step>
    </Steps>
  </Tab>
</Tabs>

<div id="example-dataset-with-vector">
  ## 使用 Vector 的示例数据集
</div>

下面我们使用一个 **Nginx 日志文件** 作为更完整的示例。

<Tabs>
  <Tab title="托管 ClickStack">
    以下指南假设您已创建托管 ClickStack 服务并记录了相应的服务凭据。如果尚未完成，请先参阅托管 ClickStack 的 [Getting Started](/zh/clickstack/getting-started/managed) 指南，按步骤操作直至出现配置 Vector 的提示。

    <Steps>
      <Step>
        ### 安装 Vector

        继续之前，请确保在计划运行摄取管道的系统上**已安装 Vector**。请按照 [Vector 官方安装指南](https://vector.dev/docs/setup/installation/) 安装适合您环境的预构建二进制文件或软件包：

        安装完成后，在继续执行下面的配置步骤之前，请确认 `vector` 可执行文件已在您的路径中。

        它也可以安装在与 ClickStack OTel collector 相同的实例上。

        在[将 Vector 部署到生产环境](https://vector.dev/docs/setup/going-to-prod/)时，请遵循架构和安全方面的最佳实践。
      </Step>

      <Step>
        ### 下载示例数据

        如果你想用示例数据集进行试验，请下载下面的 nginx 示例。

        ```bash theme={null}
        curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/access.log
        ```

        <Note>
          这些数据采集自一个 Nginx 实例；该实例已配置为以 JSON 格式输出日志，以便于解析。有关这些日志的 Nginx 配置，请参阅["使用 ClickStack 监控 Nginx 日志"](/zh/clickstack/integration-examples/nginx-logs#configure-nginx)。
        </Note>
      </Step>

      <Step>
        ### 创建数据库和表

        在开始摄取数据之前，Vector 需要预先定义好表和 schema。

        首先创建一个数据库。可以通过 [ClickHouse Cloud 控制台](/zh/products/cloud/features/sql-console-features/sql-console) 完成。

        创建一个名为 `logs` 的数据库：

        ```sql theme={null}
        CREATE DATABASE IF NOT EXISTS logs
        ```

        创建一个用于存储数据的表。

        ```sql theme={null}
        CREATE TABLE logs.nginx_logs
        (
            `time_local` DateTime,
            `remote_addr` IPv4,
            `remote_user` LowCardinality(String),
            `request` String,
            `status` UInt16,
            `body_bytes_sent` UInt64,
            `http_referer` String,
            `http_user_agent` String,
            `http_x_forwarded_for` LowCardinality(String),
            `request_time` Float32,
            `upstream_response_time` Float32,
            `http_host` String
        )
        ENGINE = MergeTree
        ORDER BY (toStartOfMinute(time_local), status, remote_addr)
        ```

        <Info>
          **Nginx 主键**

          上述主键是根据 ClickStack UI 中 Nginx 日志的常见访问模式设定的，但在生产环境中可能需要根据实际工作负载进行调整。
        </Info>
      </Step>

      <Step>
        ### 复制 Vector 配置

        复制 Vector 配置，并创建一个 `nginx.yaml` 文件，设置 `CLICKHOUSE_ENDPOINT` 和 `CLICKHOUSE_PASSWORD`。

        ```yaml theme={null}
        data_dir: ./.vector-data
        sources:
          nginx_logs:
            type: file
            include:
              - access.log
            read_from: beginning

        transforms:
          decode_json:
            type: remap
            inputs:
              - nginx_logs
            source: |
              . = parse_json!(to_string!(.message))
              ts = parse_timestamp!(.time_local, format: "%d/%b/%Y:%H:%M:%S %z")
              # ClickHouse 兼容的 DateTime 格式
              .time_local = format_timestamp!(ts, format: "%F %T")

        sinks:
          clickhouse:
            type: clickhouse
            inputs:
              - decode_json
            endpoint: "<CLICKHOUSE_ENDPOINT>"
            database: logs
            format: json_each_row
            table: nginx_logs
            skip_unknown_fields: true
            auth:
              strategy: "basic"
              user: "default"
              password: "<CLICKHOUSE_PASSWORD>"
        ```

        <Note>
          上述示例使用了托管 ClickStack 的默认用户。对于生产环境中的部署，我们建议[创建专用的摄取用户](/zh/clickstack/ingesting-data/collector#creating-an-ingestion-user)，并为其设置适当的权限和限制。
        </Note>
      </Step>

      <Step>
        ### 启动 Vector

        使用以下命令启动 Vector，并先创建数据目录，用于记录文件偏移量。

        ```bash theme={null}
        mkdir ./.vector-data
        vector --config nginx.yaml
        ```
      </Step>

      <Step>
        ### 前往 ClickStack UI

        前往你的托管 ClickStack 服务，并在左侧菜单中选择 "ClickStack"。如果你已经完成引导流程，系统会在新标签页中打开 ClickStack UI，并自动完成身份验证。如果还没有，请继续完成引导流程，并在选择 Vector 作为输入源后，选择“启动 ClickStack”。

        <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/mGB-7MnBG_6npuhw/images/clickstack/launch-clickstack-vector.png?fit=max&auto=format&n=mGB-7MnBG_6npuhw&q=85&s=17ddb1720ed82d5007b4bd747f26480d" alt="为 Vector 启动 ClickStack" size="lg" width="1920" height="918" data-path="images/clickstack/launch-clickstack-vector.png" />
      </Step>

      <Step>
        ### 创建数据源

        创建一个日志数据源。如果还没有任何数据源，首次登录时系统会提示你创建一个。否则，请前往 Team Settings 并添加新的数据源。

        <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/GaEHa-fd8w_5w7tQ/images/clickstack/create-vector-datasource.png?fit=max&auto=format&n=GaEHa-fd8w_5w7tQ&q=85&s=bcf6923c4843a0a9ba198628ea3cfd87" alt="创建数据源 - vector" size="lg" width="3600" height="1938" data-path="images/clickstack/create-vector-datasource.png" />

        该配置假定使用 Nginx schema，并将 `time_local` 列作为 timestamp。这是在主键中声明的 timestamp 列。此列是必填项。

        我们还将默认 select 指定为 `time_local, remote_addr, status, request`，用于定义日志视图中会返回哪些列。

        在上面的示例中，数据中并不存在 `Body` 列。相反，它被定义为以下 SQL expression：

        ```sql theme={null}
        concat(
          remote_addr, ' ',
          remote_user, ' ',
          '[', formatDateTime(time_local, '%d/%b/%Y:%H:%M:%S %z'), '] ',
          '"', request, '" ',
          toString(status), ' ',
          toString(body_bytes_sent), ' ',
          '"', http_referer, '" ',
          '"', http_user_agent, '" ',
          '"', http_x_forwarded_for, '" ',
          toString(request_time), ' ',
          toString(upstream_response_time), ' ',
          '"', http_host, '"'
        )
        ```

        这会根据结构化字段还原日志行。

        有关其他可用选项，请参阅[配置参考](/zh/clickstack/managing/config)。
      </Step>

      <Step>
        ### 查看数据

        前往 `2025 年 10 月 20 日` 的搜索视图，查看数据并开始使用 ClickStack。

        <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/mGB-7MnBG_6npuhw/images/clickstack/nginx-logs-vector-search.png?fit=max&auto=format&n=mGB-7MnBG_6npuhw&q=85&s=62db4cb133326072330b5ec95d12f349" alt="HyperDX UI" size="lg" width="3600" height="1906" data-path="images/clickstack/nginx-logs-vector-search.png" />
      </Step>
    </Steps>
  </Tab>

  <Tab title="开源 ClickStack">
    以下指南假设您已参照[入门指南](/zh/clickstack/getting-started/oss)完成了 ClickStack Open Source 的部署。

    <Steps>
      <Step>
        ### 安装 Vector

        继续之前，请确保在计划运行摄取管道的系统上**已安装 Vector**。请按照 [Vector 官方安装指南](https://vector.dev/docs/setup/installation/) 安装适合您环境的预构建二进制文件或软件包：

        安装完成后，在继续执行下面的配置步骤之前，请确认 `vector` 可执行文件已在您的路径中。

        它也可以安装在与 ClickStack OTel collector 相同的实例上。

        在[将 Vector 部署到生产环境](https://vector.dev/docs/setup/going-to-prod/)时，请遵循架构和安全方面的最佳实践。
      </Step>

      <Step>
        ### 下载样本数据

        如果你想用示例数据集进行试验，请下载下面的 nginx 示例。

        ```bash theme={null}
        curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/access.log
        ```

        <Note>
          这些数据采集自一个 Nginx 实例；该实例已配置为以 JSON 格式输出日志，以便于解析。有关这些日志的 Nginx 配置，请参阅["使用 ClickStack 监控 Nginx 日志"](/zh/clickstack/integration-examples/nginx-logs#configure-nginx)。
        </Note>
      </Step>

      <Step>
        ### 创建数据库和表

        Vector 要求在摄取数据之前预先定义好表和 schema。

        首先创建一个数据库。可通过 [ClickHouse Web 用户界面](/zh/concepts/features/interfaces/http#web-ui) 在 [http://localhost:8123/play](http://localhost:8123/play) 中完成。使用默认用户名和密码 `api:api`。

        <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/mGB-7MnBG_6npuhw/images/clickstack/play-ui-clickstack.png?fit=max&auto=format&n=mGB-7MnBG_6npuhw&q=85&s=1bac3511fb24ff4669f04db8998f310f" alt="Play UI ClickStack" size="lg" width="3600" height="1918" data-path="images/clickstack/play-ui-clickstack.png" />

        创建数据库 `logs`：

        ```sql theme={null}
        CREATE DATABASE IF NOT EXISTS logs
        ```

        创建一个用于存储数据的表。

        ```sql theme={null}
        CREATE TABLE logs.nginx_logs
        (
            `time_local` DateTime,
            `remote_addr` IPv4,
            `remote_user` LowCardinality(String),
            `request` String,
            `status` UInt16,
            `body_bytes_sent` UInt64,
            `http_referer` String,
            `http_user_agent` String,
            `http_x_forwarded_for` LowCardinality(String),
            `request_time` Float32,
            `upstream_response_time` Float32,
            `http_host` String
        )
        ENGINE = MergeTree
        ORDER BY (toStartOfMinute(time_local), status, remote_addr)
        ```

        <Info>
          **Nginx 主键**

          上述主键是根据 ClickStack UI 中 Nginx 日志的典型访问模式设计的，但在生产环境中可能需要根据你的工作负载进行调整。
        </Info>
      </Step>

      <Step>
        ### 复制 Vector 配置

        对于 Vector，向 ClickStack 的摄取应直接写入 ClickHouse，绕过 collector 暴露的 OTLP 端点。

        复制 Vector 配置并创建文件 `nginx.yaml`。

        ```yaml theme={null}
        data_dir: ./.vector-data
        sources:
          nginx_logs:
            type: file
            include:
              - access.log
            read_from: beginning

        transforms:
          decode_json:
            type: remap
            inputs:
              - nginx_logs
            source: |
              . = parse_json!(to_string!(.message))
              ts = parse_timestamp!(.time_local, format: "%d/%b/%Y:%H:%M:%S %z")
              # 适合 ClickHouse 的 DateTime 格式
              .time_local = format_timestamp!(ts, format: "%F %T")

        sinks:
          clickhouse:
            type: clickhouse
            inputs:
              - decode_json
            endpoint: "http://localhost:8123"
            database: logs
            format: json_each_row
            table: nginx_logs
            skip_unknown_fields: true
            auth:
              strategy: "basic"
              user: "api"
              password: "api"
        ```

        <Note>
          上面的示例在 ClickStack Open Source 中使用的是 `api` 用户。对于生产环境部署，我们建议[创建专用的摄取用户](/zh/clickstack/ingesting-data/collector#creating-an-ingestion-user)，并为其设置适当的权限和限制。上述配置还假定 Vector 与 ClickStack 运行在同一台主机上，但在生产环境中通常并非如此。我们建议通过安全的 HTTPS 8443 端口发送数据。
        </Note>
      </Step>

      <Step>
        ### 启动 Vector

        运行以下命令启动 Vector。

        ```bash theme={null}
        mkdir ./.vector-data
        vector --config nginx-local.yaml
        ```
      </Step>

      <Step>
        ### 创建数据源

        通过 `Team -> Sources` 创建一个日志数据源

        <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/GaEHa-fd8w_5w7tQ/images/clickstack/create-vector-datasource-oss.png?fit=max&auto=format&n=GaEHa-fd8w_5w7tQ&q=85&s=d9917d00228e1219bbacd2a2759eb938" alt="创建数据源 - vector" size="lg" width="3600" height="1940" data-path="images/clickstack/create-vector-datasource-oss.png" />

        该配置假定使用 Nginx schema，并将 `time_local` 列作为 timestamp 使用。这是主键中声明的 timestamp 列。该列是必填项。

        我们还将默认选择字段指定为 `time_local, remote_addr, status, request`，用于定义日志视图中返回哪些列。

        在上面的示例中，数据中并不存在 `Body` 列。相反，它被定义为以下 SQL 表达式：

        ```sql theme={null}
        concat(
          remote_addr, ' ',
          remote_user, ' ',
          '[', formatDateTime(time_local, '%d/%b/%Y:%H:%M:%S %z'), '] ',
          '"', request, '" ',
          toString(status), ' ',
          toString(body_bytes_sent), ' ',
          '"', http_referer, '" ',
          '"', http_user_agent, '" ',
          '"', http_x_forwarded_for, '" ',
          toString(request_time), ' ',
          toString(upstream_response_time), ' ',
          '"', http_host, '"'
        )
        ```

        这会根据结构化字段重新构建日志行。

        有关其他选项，请参阅[配置参考](/zh/clickstack/managing/config)。
      </Step>

      <Step>
        ### 访问 ClickStack UI

        访问 [http://localhost:8080](http://localhost:8080) 上的 ClickStack UI。如果你尚未完成引导配置，请先创建用户。

        <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/RhEK5rhPj_7m6pWY/images/use-cases/observability/hyperdx-login.png?fit=max&auto=format&n=RhEK5rhPj_7m6pWY&q=85&s=eec6e42744553cd8881cf9c9ada74166" alt="ClickStack 登录" size="lg" width="3600" height="1900" data-path="images/use-cases/observability/hyperdx-login.png" />
      </Step>

      <Step>
        ### 浏览数据

        前往 `October 20th, 2025` 的搜索视图，浏览数据并开始使用 ClickStack。

        <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/mGB-7MnBG_6npuhw/images/clickstack/nginx-logs-vector-search.png?fit=max&auto=format&n=mGB-7MnBG_6npuhw&q=85&s=62db4cb133326072330b5ec95d12f349" alt="HyperDX UI" size="lg" width="3600" height="1906" data-path="images/clickstack/nginx-logs-vector-search.png" />
      </Step>
    </Steps>
  </Tab>
</Tabs>