跳到主要内容
跳到主要内容

Docker Compose

所有 ClickStack 组件都以独立的 Docker 镜像单独分发：

  • ClickHouse
  • HyperDX
  • OpenTelemetry (OTel) collector
  • MongoDB

这些镜像可以通过 Docker Compose 组合并在本地部署。

基于默认的 otel-collector 配置，Docker Compose 会暴露用于可观测性和摄取的额外端口：

  • 13133：health_check 扩展的健康检查端点
  • 24225：用于日志摄取的 Fluentd 接收器
  • 4317：OTLP gRPC 接收器（用于 traces、logs 和 metrics 的标准端口）
  • 4318：OTLP HTTP 接收器（gRPC 的替代方案）
  • 8888：用于监控收集器自身的 Prometheus metrics 端点

这些端口支持与多种遥测源集成，使 OpenTelemetry collector 能够在生产环境中满足多样化的摄取需求。

适用场景​

  • 本地测试
  • 概念验证
  • 对容错性无要求、单台服务器即可承载全部 ClickHouse 数据的生产环境部署
  • 部署 ClickStack，但将 ClickHouse 独立托管（例如通过 ClickHouse Cloud）

部署步骤​


克隆仓库​

要使用 Docker Compose 进行部署，先克隆 HyperDX 仓库，进入该目录并运行 docker-compose up：

git clone [email protected]:hyperdxio/hyperdx.git
docker compose up

访问 http://localhost:8080 以打开 HyperDX UI。

创建一个用户，并提供满足要求的用户名和密码。

点击 Create 后，会为通过 Helm 图表部署的 ClickHouse 实例自动创建数据源。

覆盖默认连接

您可以替换到集成 ClickHouse 实例的默认连接。有关详细信息，请参阅 "Using ClickHouse Cloud"。

HyperDX UI

有关使用其他 ClickHouse 实例的示例，请参阅 "Create a ClickHouse Cloud connection"。

完成连接配置​

要连接到已部署的 ClickHouse 实例，只需点击 Create 并接受默认设置。

如果您更倾向于连接自己的外部 ClickHouse 集群（例如 ClickHouse Cloud），可以手动输入连接凭据。

如果系统提示您创建数据源，请保留所有默认值，并将 Table 字段设置为 otel_logs。其他所有设置应会自动检测，此时即可点击 Save New Source。

创建日志数据源

修改 compose 设置​

用户可以通过环境变量文件来修改该栈的设置，例如使用的版本。

user@example-host hyperdx % cat .env
# 供 docker-compose.yml 使用 \{#used-by-docker-composeyml}
# 供 docker-compose.yml 使用 \{#used-by-docker-composeyml}
HDX_IMAGE_REPO=docker.hyperdx.io
IMAGE_NAME=ghcr.io/hyperdxio/hyperdx
IMAGE_NAME_DOCKERHUB=hyperdx/hyperdx
LOCAL_IMAGE_NAME=ghcr.io/hyperdxio/hyperdx-local
LOCAL_IMAGE_NAME_DOCKERHUB=hyperdx/hyperdx-local
ALL_IN_ONE_IMAGE_NAME=ghcr.io/hyperdxio/hyperdx-all-in-one
ALL_IN_ONE_IMAGE_NAME_DOCKERHUB=hyperdx/hyperdx-all-in-one
OTEL_COLLECTOR_IMAGE_NAME=ghcr.io/hyperdxio/hyperdx-otel-collector
OTEL_COLLECTOR_IMAGE_NAME_DOCKERHUB=hyperdx/hyperdx-otel-collector
CODE_VERSION=2.0.0-beta.16
IMAGE_VERSION_SUB_TAG=.16
IMAGE_VERSION=2-beta
IMAGE_NIGHTLY_TAG=2-nightly

# 配置域名 URL \{#set-up-domain-urls}
HYPERDX_API_PORT=8000 # 可选（不应被其他服务占用）
HYPERDX_APP_PORT=8080
HYPERDX_APP_URL=http://localhost
HYPERDX_LOG_LEVEL=debug
HYPERDX_OPAMP_PORT=4320

# OTel/ClickHouse 配置 \{#otelclickhouse-config}
HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE=default

配置 OpenTelemetry collector​

如有需要，可以修改 OTel collector 的配置——请参阅“修改配置”。

使用 ClickHouse Cloud​

此发行版可以与 ClickHouse Cloud 一起使用。用户应当：

  • 从 docker-compose.yaml 文件中移除 ClickHouse 服务。如果只是测试，这一步是可选的，因为已部署的 ClickHouse 实例只是会被忽略——不过仍会占用本地资源。如果移除该服务，请确保同时移除对该服务的所有引用，例如 depends_on。

  • 通过在 Compose 文件中设置环境变量 CLICKHOUSE_ENDPOINT、CLICKHOUSE_USER 和 CLICKHOUSE_PASSWORD，修改 OTel collector 以使用 ClickHouse Cloud 实例。具体来说，将这些环境变量添加到 OTel collector 服务中：

    otel-collector:
    image: ${OTEL_COLLECTOR_IMAGE_NAME}:${IMAGE_VERSION}
    environment:
      CLICKHOUSE_ENDPOINT: '<CLICKHOUSE_ENDPOINT>' # https endpoint here
      CLICKHOUSE_USER: '<CLICKHOUSE_USER>'
      CLICKHOUSE_PASSWORD: '<CLICKHOUSE_PASSWORD>'
      HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE: ${HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE}
      HYPERDX_LOG_LEVEL: ${HYPERDX_LOG_LEVEL}
      OPAMP_SERVER_URL: 'http://app:${HYPERDX_OPAMP_PORT}'
    ports:
      - '13133:13133' # health_check extension
      - '24225:24225' # fluentd receiver
      - '4317:4317' # OTLP gRPC receiver
      - '4318:4318' # OTLP http receiver
      - '8888:8888' # metrics extension
    restart: always
    networks:
      - internal

    CLICKHOUSE_ENDPOINT 应设置为 ClickHouse Cloud 的 HTTPS endpoint，并包含端口 8443，例如 https://mxl4k3ul6a.us-east-2.aws.clickhouse.com:8443。

  • 在连接到 HyperDX UI 并创建到 ClickHouse 的连接时，使用你的 Cloud 凭证。

JSON 类型支持​

Beta feature. Learn more.
Beta 功能 - 尚未准备好用于生产环境

ClickStack 中的 JSON 类型支持目前为 Beta 功能。虽然 JSON 类型本身在 ClickHouse 25.3+ 中已经可以用于生产环境，但其在 ClickStack 中的集成仍在积极开发中，可能存在功能限制、未来变更或缺陷。

从 2.0.4 版本开始，ClickStack 对 JSON 类型 提供 Beta 支持。

关于此类型的优势，请参见 JSON 类型的优势。

要启用对 JSON 类型的支持，用户必须设置以下环境变量：

  • OTEL_AGENT_FEATURE_GATE_ARG='--feature-gates=clickhouse.json' - 在 OTel collector 中启用支持，确保使用 JSON 类型创建模式（schema）。
  • BETA_CH_OTEL_JSON_SCHEMA_ENABLED=true - 在 HyperDX 应用中启用支持，允许查询 JSON 数据。

要进行这些设置，请修改 docker-compose.yaml 中相关的服务：

  app:
    image: ${HDX_IMAGE_REPO}/${IMAGE_NAME_DOCKERHUB}:${IMAGE_VERSION}
    ports:
      - ${HYPERDX_API_PORT}:${HYPERDX_API_PORT}
      - ${HYPERDX_APP_PORT}:${HYPERDX_APP_PORT}
    environment:
      BETA_CH_OTEL_JSON_SCHEMA_ENABLED: true # 启用 JSON
      FRONTEND_URL: ${HYPERDX_APP_URL}:${HYPERDX_APP_PORT}
      HYPERDX_API_KEY: ${HYPERDX_API_KEY}
      HYPERDX_API_PORT: ${HYPERDX_API_PORT}
    # 为简洁起见省略部分内容

  otel-collector:
    image: ${HDX_IMAGE_REPO}/${OTEL_COLLECTOR_IMAGE_NAME_DOCKERHUB}:${IMAGE_VERSION}
    environment:
      OTEL_AGENT_FEATURE_GATE_ARG: '--feature-gates=clickhouse.json' # 启用 JSON
      CLICKHOUSE_ENDPOINT: 'tcp://ch-server:9000?dial_timeout=10s' 
      # 为简洁起见省略部分内容