Docker Compose

所有 ClickStack 开源组件都以单独的 Docker 镜像形式发布：

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

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

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

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

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

适用场景

• 本地测试
• 概念验证
• 不需要容错能力且单台服务器足以承载全部 ClickHouse 数据的生产部署
• 部署 ClickStack，但将 ClickHouse 独立托管（例如使用 ClickHouse Cloud）时

部署步骤

克隆代码仓库

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

git clone https://github.com/ClickHouse/ClickStack.git
docker compose up

访问 HyperDX UI

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

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

点击 Create 后，将为通过 Docker Compose 部署的 ClickHouse 实例创建数据源。

覆盖默认连接

可以覆盖与集成 ClickHouse 实例的默认连接配置。详情请参阅 "Using ClickHouse Cloud"。

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

完成连接配置

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

如果希望连接到自己的外部 ClickHouse 集群（例如 ClickHouse Cloud），可以手动输入连接凭证。

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

修改 compose 设置

你可以通过环境变量文件来修改该栈的配置，例如所使用的版本：

user@example-host clickstack % cat .env

# Used by docker-compose.yml
IMAGE_NAME_DOCKERHUB=clickhouse/clickstack-all-in-one
LOCAL_IMAGE_NAME_DOCKERHUB=clickhouse/clickstack-local
ALL_IN_ONE_IMAGE_NAME_DOCKERHUB=clickhouse/clickstack-all-in-one
OTEL_COLLECTOR_IMAGE_NAME_DOCKERHUB=clickhouse/clickstack-otel-collector
CODE_VERSION=2.8.0
IMAGE_VERSION_SUB_TAG=.8.0
IMAGE_VERSION=2
IMAGE_NIGHTLY_TAG=2-nightly
IMAGE_LATEST_TAG=latest

# Set up domain URLs
HYPERDX_API_PORT=8000 #optional (should not be taken by other services)
HYPERDX_APP_PORT=8080
HYPERDX_APP_URL=http://localhost
HYPERDX_LOG_LEVEL=debug
HYPERDX_OPAMP_PORT=4320

# Otel/Clickhouse config
HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE=default

配置 OpenTelemetry collector

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

使用 ClickHouse Cloud

此发行版可以与 ClickHouse Cloud 一起使用，但它与托管 ClickStack不同。在此部署场景下，你自行管理 ClickStack UI，而 ClickHouse Cloud 仅用于计算和存储。除非你有特定原因需要独立运行 UI，否则我们推荐使用托管 ClickStack，它集成了身份认证和其他企业级功能，并且无需你自行管理 ClickStack UI。

你需要：

• 从 docker-compose.yml 文件中移除 ClickHouse 服务。如果只是测试，这是可选的，因为已部署的 ClickHouse 实例虽然会被忽略，但会浪费本地资源。如果移除该服务，请确保同时删除所有对该服务的引用，例如 depends_on。

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

  otel-collector:
      image: ${OTEL_COLLECTOR_IMAGE_NAME_DOCKERHUB}:${IMAGE_VERSION}
      environment:
        CLICKHOUSE_ENDPOINT: '<CLICKHOUSE_ENDPOINT>' # 此处填写 HTTPS endpoint
        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 扩展
        - '24225:24225' # fluentd 接收器
        - '4317:4317' # OTLP gRPC 接收器
        - '4318:4318' # OTLP http 接收器
        - '8888:8888' # 指标扩展
      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（仅适用于 ClickStack 开源版）- 在 ClickStack UI 应用中启用支持，允许查询 JSON 数据。

要完成上述设置，请修改 docker-compose.yml 中相关的服务：

  app:
    image: ${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 # enable JSON
      FRONTEND_URL: ${HYPERDX_APP_URL}:${HYPERDX_APP_PORT}
      HYPERDX_API_KEY: ${HYPERDX_API_KEY}
      HYPERDX_API_PORT: ${HYPERDX_API_PORT}
    # truncated for brevity

  otel-collector:
    image: ${OTEL_COLLECTOR_IMAGE_NAME_DOCKERHUB}:${IMAGE_VERSION}
    environment:
      OTEL_AGENT_FEATURE_GATE_ARG: '--feature-gates=clickhouse.json' # enable JSON
      CLICKHOUSE_ENDPOINT: 'tcp://ch-server:9000?dial_timeout=10s' 
      # truncated for brevity