HyperDX 2.41.0 配置参数详解

目标：以实测栈（HyperDX 2.41.0 + ClickHouse 26.1.12 + Mongo 5.0.32，2026-10-23 实测）为基准，讲清 ClickStack 开源版三个配置面——app/collector 环境变量、OpAMP 动态配置、ClickHouse XML——的查看方法、逐项含义、修改方式与生效行为，并给出生产配置模板。部署过程见 B2 篇，本文全部命令与回显均为实测。

一、环境信息

• 实测对象：B2 篇部署的 hyperdx-2410-stack 四服务栈（app/otel-collector/ch-server/db 全部 healthy），配置基准版本 2.41.0
• 镜像内置默认值来源：hyperdx/hyperdx:2.41.0 与 clickhouse/clickstack-otel-collector:2.41.0 的容器环境与内置配置文件；collector 的运行时配置以 supervisor 生成的 /etc/otel/supervisor-data/effective.yaml 为准
• 官方配置文档：https://clickhouse.com/docs/clickstack/managing/config（查询日期 2026-10-23，注意 ClickStack 文档站需用 .md 后缀直出 Markdown）
• 实测环境：Docker 29.8.1 / Compose v5.5.1，Linux 服务器，编排与端口同 B2 篇（UI 8130 / API 8136 / OTLP 8137-8138）

二、前置条件

• 已按 B2 篇完成 4 服务栈部署且 docker compose ps 四容器运行中；
• 已注册首用户（本文示例 root@quzuo.net / Q1w2e3r4t5y6!）；
• 具备 docker exec 权限（查 Mongo/ClickHouse 内部状态用）。

三、参数查看与修改方式

ClickStack 的配置分散在三个配置面，查看与修改方式不同：

实测查看三个配置面的核心命令与回显：

$ docker inspect hyperdx-2410-stack-app-1 --format '{{range .Config.Env}}{{println .}}{{end}}' | grep -E 'HYPERDX|MONGO|OPAMP|SERVER|FRONTEND|USAGE|OTEL_|MINER' | sort
FRONTEND_URL=http://localhost:8130
HYPERDX_API_KEY=
HYPERDX_API_PORT=8136
HYPERDX_APP_PORT=8130
HYPERDX_APP_URL=http://localhost
HYPERDX_LOG_LEVEL=info
MINER_API_URL=http://miner:5123
MONGO_URI=mongodb://db:27017/hyperdx
OPAMP_PORT=4320
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
OTEL_RESOURCE_ATTRIBUTES=service.version=2.41.0
OTEL_SERVICE_NAME=hdx-oss-app
SERVER_URL=http://127.0.0.1:8136
USAGE_STATS_ENABLED=false

$ docker exec hyperdx-2410-stack-otel-collector-1 sh -c "grep -E 'ttl|timeout|database|endpoint' /etc/otel/supervisor-data/effective.yaml | head -8"
        database: ${env:HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE}
        endpoint: ${env:CLICKHOUSE_ENDPOINT}
        timeout: ${env:HYPERDX_OTEL_EXPORTER_TIMEOUT:-5s}
        ttl: ${env:HYPERDX_OTEL_EXPORTER_TABLES_TTL:-720h}
        database: ${env:HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE}
        endpoint: ${env:CLICKHOUSE_ENDPOINT}
        timeout: ${env:HYPERDX_OTEL_EXPORTER_TIMEOUT:-5s}
        ttl: ${env:HYPERDX_OTEL_EXPORTER_TABLES_TTL:-720h}

💡 注意 effective.yaml 中的 ${env:...} 是占位符引用——真实值取自容器环境变量，所以「改 collector 行为」的正确入口是 compose 的 environment 段，而不是去改 effective.yaml（它由 supervisor 重新生成，手改会被覆盖）。

四、参数总览

app 服务环境变量（hyperdx/hyperdx:2.41.0）：

collector 服务环境变量（clickstack-otel-collector:2.41.0）：

ClickHouse（XML/在线 DDL）：监听地址与端口、max_memory_usage、用户与密码、各表 TTL（可在线 ALTER ... MODIFY TTL，实测见 5.3）。

五、核心参数分类详解

5.1 端口与进程参数

HYPERDX_API_PORT / HYPERDX_APP_PORT / OPAMP_PORT 三个端口参数中，改 API 端口有一个必踩的坑：镜像内置 healthcheck 硬编码探测 http://localhost:8000/health（docker inspect hyperdx/hyperdx:2.41.0 --format '{{json .Config.Healthcheck}}' 实测可见），改端口后探针永远失败、容器显示 unhealthy 但服务正常。解法是 compose 里覆盖 healthcheck（B2 篇编排已含）：

    healthcheck:
      test: ["CMD-SHELL", "node -e \"require('http').get('http://localhost:' + (process.env.HYPERDX_API_PORT || 8000) + '/health',r=>r.statusCode===200?process.exit(0):process.exit(1)).on('error',()=>process.exit(1))\""]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 60s

覆盖并重建后实测 Up About a minute (healthy)。前端端口/UI 相关的 CORS：FRONTEND_URL 必须与浏览器实际访问地址一致，实测注册/登录接口响应头会按它回 Access-Control-Allow-Origin: http://localhost:8130。

5.2 连接与依赖参数

MONGO_URI、CLICKHOUSE_ENDPOINT、OPAMP_SERVER_URL 三条链路串起全栈，实测可用性判据：

• Mongo：app 启动日志打印 Connection established to MongoDB；
• ClickHouse：collector 能建表（B2 篇表清单）、app 的 DEFAULT_CONNECTIONS 能通过 http://ch-server:8123 HTTP 探活；
• OpAMP：collector 日志出现 Connected to the OpAMP server.。

对接外部 ClickHouse：把 collector 的 CLICKHOUSE_ENDPOINT 改为 tcp://<外部CH>:9000，app 的 DEFAULT_CONNECTIONS 改为外部实例的 HTTP 地址与账号即可；注意外部账号需要建表权限（collector 首次写入会 CREATE TABLE）。

5.3 数据留存参数（TTL）

保留期由 collector exporter 的 HYPERDX_OTEL_EXPORTER_TABLES_TTL（默认 720h=30 天）在建表时写入 TTL；已建的表改环境变量不会回改 TTL（该值只在 CREATE TABLE 时消费），在线修改用 DDL，实测全程可逆：

$ docker exec hyperdx-2410-stack-ch-server-1 clickhouse-client --query "ALTER TABLE default.otel_logs MODIFY TTL toDateTime(Timestamp) + toIntervalDay(90)"
$ docker exec hyperdx-2410-stack-ch-server-1 clickhouse-client --query "SELECT engine_full FROM system.tables WHERE database='default' AND table='otel_logs' FORMAT TSV"
MergeTree PARTITION BY toDate(Timestamp) ORDER BY (toStartOfFiveMinutes(Timestamp), ServiceName, Timestamp) TTL toDateTime(Timestamp) + toIntervalDay(90) SETTINGS index_granularity = 8192, ttl_only_drop_parts = 1, enable_block_number_column = 1, enable_block_offset_column = 1

# 还原 30 天
$ ... --query "ALTER TABLE default.otel_logs MODIFY TTL toDateTime(Timestamp) + toIntervalDay(30)"
TTL toDateTime(Timestamp) + toIntervalDay(30)

注意三点：① ttl_only_drop_parts = 1 意味着过期按整分区删除，分区粒度是天，实际删除有滞后属正常；② 留存改长前先核对磁盘（每 30 天一个分位）；③ 追溯期内的查询不受 TTL 修改影响。

5.4 Schema 开关参数

HYPERDX_OTEL_EXPORTER_CREATE_LEGACY_SCHEMA 的语义与直觉相反，实测结论（2.41.0，对 otel_logs/otel_traces/hyperdx_sessions 三表核对列名）：

$ docker exec hyperdx-2410-stack-ch-server-1 clickhouse-client --query "SELECT table, countIf(name='TimestampTime') AS tt, countIf(name='Timestamp') AS ts FROM system.columns WHERE database='default' AND table IN ('otel_logs','otel_traces','hyperdx_sessions') GROUP BY table FORMAT TSV"
hyperdx_sessions        1       1
otel_logs       0       1
otel_traces     0       1

• 该变量置 true（官方 compose 默认值）时，otel_logs/otel_traces 仍是新 schema（仅 Timestamp 列 + <table>_kv_rollup_15m 元数据物化视图），只有 hyperdx_sessions 保留 TimestampTime 列；
• 因此 Source 表达式必须按真实列名写：Logs/Traces 用 Timestamp，Sessions 用 TimestampTime（或 Timestamp，该列两表都有）；
• 官方仓库模板把 Traces 源写成 TimestampTime 是 2.41.0 时点的模板滞后（B2 篇常见问题 2 有完整报错与修复）；
• HYPERDX_OTEL_EXPORTER_CLICKHOUSE_JSON_ENABLE=true 可切 JSON schema（beta），官方明示不建议默认启用——切换需 DROP 全部表重建，成本高，评估期用独立库测试。

5.5 密钥与会话参数

两套密钥分工实测明确：

ingest key 实测读取（B2 篇同款）：

$ docker exec hyperdx-2410-stack-db-1 mongosh --quiet hyperdx --eval 'JSON.stringify(db.teams.find({},{apiKey:1}).toArray())'
[{"_id":"6adaae2ed640de28d174c2ad","apiKey":"cca923a9-201f-4aa6-9d2d-98d016261d61"}]

会话与令牌安全参数（不设时的实测启动告警，建议生产都补上）：

[API] {"level":50,..."msg":"EXPRESS_SESSION_SECRET is missing or uses the public legacy value: generated a random secret for this process. Users are signed out whenever it restarts, and replicas do not share sessions. Configure a random secret shared by all replicas to keep sessions."}
[API] {"level":40,..."msg":"Token encryption is disabled: third-party tokens will be stored in plain text (set TOKEN_ENCRYPTION_KEY to enable)"}

5.6 自观测与统计参数

app 自身也是一台"被观测服务"：OTEL_EXPORTER_OTLP_ENDPOINT 指向栈内 collector、OTEL_SERVICE_NAME=hdx-oss-app，因此 otel_logs 里能看到 app 的自观测日志。USAGE_STATS_ENABLED=false 关闭的是向上游匿名统计（内网/合规场景建议关闭，实测关闭后不影响任何功能）。

5.7 日志级别参数

app 与 collector 各有 HYPERDX_LOG_LEVEL，默认 info。排查接入问题时建议临时把 collector 调到 debug（docker compose 改环境变量后 up -d otel-collector 重建），配合 docker compose logs -f otel-collector 观察 OTLP 接收与批量导出；确认后改回 info，避免日志量膨胀。

5.8 DEFAULT_CONNECTIONS / DEFAULT_SOURCES

两者只在首次初始化（Mongo 中尚无连接/Source）时消费，实测两点：

• 表达式与表结构对齐规则见 5.4；defaultTableSelectExpression 决定搜索页默认列，可按团队习惯裁剪；
• 已运行栈的修改走 UI（Team Settings → Sources）或直接改 Mongo 集合（connections/sources），改 compose 环境变量对已初始化的栈无效——这是"改了不生效"的高频误区。

5.9 ClickHouse XML 参数

官方模板 users.xml 的关键项（本栈实测生效值）：

<profiles>
    <default>
        <max_memory_usage>10000000000</max_memory_usage>
        <use_uncompressed_cache>0</use_uncompressed_cache>
        <load_balancing>in_order</load_balancing>

• max_memory_usage 10 GB：单查询内存上限，小内存服务器需按 (总内存 - 栈基础占用 ~1 GB) × 0.7 下调；
• config.xml 中 listen_host 0.0.0.0 + 8123/9000 端口仅暴露在 compose 内部网络（编排未映射宿主端口），外部访问需显式加映射并配密码；
• 修改 XML 后 docker compose restart ch-server 生效；用户密码改在 users.xml 的 default 段，同步更新 app 的 DEFAULT_CONNECTIONS。

六、生产配置模板

场景：50200 人研发团队，日志为主、日均 50100 GB，单机 32 GB 内存起步。在 B2 篇编排基础上叠加：

services:
  app:
    environment:
      EXPRESS_SESSION_SECRET: "<openssl rand -hex 32 生成>"
      TOKEN_ENCRYPTION_KEY: "<openssl rand -hex 32 生成>"
      USAGE_STATS_ENABLED: "false"
      HYPERDX_LOG_LEVEL: warn
      FRONTEND_URL: "https://hdx.example.com"     # 与对外域名一致
      HYPERDX_APP_URL: "https://hdx.example.com"
  otel-collector:
    environment:
      HYPERDX_OTEL_EXPORTER_TABLES_TTL: "2160h"   # 90 天留存（新建表生效）
      HYPERDX_LOG_LEVEL: warn
  ch-server:
    volumes:
      - ./clickhouse/users-prod.xml:/etc/clickhouse-server/users.xml  # default 设强密码

配套动作（逐项对应上文小节）：① 存量表 TTL 用 5.3 的 DDL 改到 90 天；② DEFAULT_CONNECTIONS 同步 ClickHouse 新密码；③ Mongo 加认证后改 MONGO_URI；④ API/UI 挂反代 HTTPS，8136/8137/8138 不直接暴露公网（OTLP 入口加网关鉴权或 IP 白名单）。

七、常见问题

1. 改了 compose 环境变量但行为没变。 两类原因：① 改的是 DEFAULT_CONNECTIONS/DEFAULT_SOURCES——仅首次初始化消费，已建栈走 UI 或 Mongo；② 改的是 collector 的 TTL——只影响新建表，存量表用 DDL（5.3）。

2. 改 API 端口后容器 unhealthy。 镜像 healthcheck 硬编码 8000 端口，覆盖 healthcheck 即可（5.1）。

3. 搜索/时间列报 UNKNOWN_IDENTIFIER。 Source 表达式与 2.41.0 实际表结构不符：Logs/Traces 只认 Timestamp，官方模板的 TimestampTime 是滞后的（5.4 有实测列名分布）。

4. 重启后所有人被登出。 未设 EXPRESS_SESSION_SECRET，每次重启随机生成会话密钥（5.5 有实测告警原文）。生产设固定值。

5. collector 重启后 OTLP 端口不监听。 OpAMP 配置未下发：确认 app 先 healthy（4320 就绪）、两镜像版本一致，再看 collector 日志是否出现 Connected to the OpAMP server.（B2 篇常见问题 3 有完整排查链）。

6. 单查询报内存超限。 max_memory_usage 默认 10 GB 超过机器可用内存，按 5.9 的公式下调 users.xml 后重启 ch-server。

八、参考链接

• 官方配置选项文档：https://clickhouse.com/docs/clickstack/managing/config
• 官方 .env 模板：https://github.com/hyperdxio/hyperdx/blob/main/.env
• 官方编排文件：https://github.com/hyperdxio/hyperdx/blob/main/docker-compose.yml
• ClickHouse TTL 文档：https://clickhouse.com/docs/engines/table-engines/mergetree/mergetree#table_engine-mergetree-ttl
• 站内系列：《HyperDX 2.41.0 介绍与选型指南》、《HyperDX 2.41.0 Docker Compose 部署指南》、《HyperDX 2.41.0 常用 CLI 命令详解》
• 站内同类：《SigNoz v0.146.0 配置参数详解》