Swetrix v5.4.1 配置参数详解

目标：系统梳理 Swetrix 社区版（CE）v5.4.1 全部部署级配置参数——前端、后端 API、Redis、ClickHouse 四个角色的环境变量逐项给出含义、默认值与改动影响，并附官方 ClickHouse 降内存配置逐文件解读与生产配置模板。参数清单以官方 Configuring 文档（swetrix.com/docs/selfhosting/configuring）为基准，并用 v5.4.1 源码（Swetrix/swetrix 仓库 backend 目录）交叉核对，检索/核对日期 2026-10-30。

一、环境信息

• 组件版本：Swetrix CE v5.4.1（官方最新稳定版，2026-08-04 发布；官方自托管编排同时使用 ClickHouse 25.8、Redis 8.6、nginx 1.31）。
• 参数基准来源：官方文档站 Configuring 页（docs/content/docs/selfhosting/configuring.mdx，与官网同源维护于主仓库）＋ 自托管编排仓库 swetrix/selfhosting 的 compose.yaml 与 configure.sh ＋ backend 源码 process.env.* 引用交叉核对。
• 核对日期：2026-10-30。
• 配置载体：Swetrix 全部配置经环境变量注入，官方编排统一从编排目录下的 .env 文件读取（configure.sh 自动生成骨架）。
• 部署形态：官方推荐 Docker Compose 单机编排（nginx 统一入口 → 前端 3000 / 后端 API 5005 → ClickHouse + Redis）。

💡 说明：v5.4.1 的自托管栈不含 MySQL——分析事件与业务事务数据均存于 ClickHouse（analytics 库），这正是官方编排只声明一个 swetrix-events-data 数据卷的原因。网上旧教程提到的 MySQL 属于 v5 之前版本的遗留依赖。

二、前置条件

• 已按 《Swetrix Docker Compose 部署指南》 完成基础部署，或至少已取得官方 selfhosting 编排仓库的文件。
• .env 文件位于编排目录根部（与 compose.yaml 同级），由 configure.sh 交互生成或手工创建。
• 后端对两类凭据有硬校验：SECRET_KEY_BASE（会话与鉴权签名密钥）与 CLICKHOUSE_PASSWORD（编排文件中写作 ${CLICKHOUSE_PASSWORD:?Set CLICKHOUSE_PASSWORD in .env}，缺失时 Compose 直接拒绝启动并原样报该提示）。
• 修改 .env 后需重建受影响服务（docker compose up -d --force-recreate swetrix-api swetrix，官方 Session replays 文档给出的标准做法）才能生效。

三、参数查看与修改方式

Swetrix 没有管理后台式的参数面板，全部部署参数走环境变量。查看与修改路径如下：

1. 查看当前生效值：编排目录内直接读 .env；运行中的值可进入后端进程环境核对（docker exec swetrix-api env | grep -E 'CLICKHOUSE|REDIS|SMTP'——其中 docker exec 仅为验证手段）。
2. 修改：编辑 .env 后重建对应服务。只改后端变量时重建 swetrix-api 即可；改 BASE_URL（前端渲染公共地址）需同时重建前端 swetrix。
3. 验证生效：重建后观察健康检查与 /ping 端点（前端 3000、后端 5005 均内置），或直接在浏览器确认站点行为变化（如注册开关）。

官方 configure.sh 生成的 .env 骨架如下（逐行实测自 v5.4.1 时期的编排仓库脚本逻辑）：

# Swetrix Frontend configuration
BASE_URL=https://analytics.example.com

# Swetrix API configuration
SECRET_KEY_BASE=<openssl rand -base64 48 自动生成>
DEBUG_MODE=false
IP_GEOLOCATION_DB_PATH=
DISABLE_REGISTRATION=true

# Database credentials
REDIS_PASSWORD=
CLICKHOUSE_PASSWORD=<openssl rand -hex 32 自动生成>

逐行说明：BASE_URL 是唯一必填的交互项（脚本会循环追问直到非空，并自动去掉尾部斜杠）；SECRET_KEY_BASE 回车即自动生成；DEBUG_MODE 被脚本固定写为 false；DISABLE_REGISTRATION 固定写 true（只允许首个注册用户）；REDIS_PASSWORD 默认留空；CLICKHOUSE_PASSWORD 强制自动生成 64 位十六进制串。

四、参数总览

按角色分组的完整参数清单（默认值取自官方 Configuring 文档与编排文件）：

💡 说明：CLICKHOUSE_DATABASE（API 侧读写哪个库）与 CLICKHOUSE_DB（ClickHouse 镜像启动时初始化建哪个库）必须一致，官方编排里都指向 analytics，自行改造编排时切勿只改其一。

五、核心参数分类详解

5.1 前端与公共地址：BASE_URL

BASE_URL 是唯一一个前后端都出现的参数，两侧含义不同：

• 前端侧：页面渲染与资源引用的公共地址，默认值 http://localhost:8080/。官方特别警告必须是用户浏览器可达的公网地址，不能填编排内部主机名（如 http://swetrix-api:5005 这类），否则页面会把内部地址输出给浏览器。
• 后端侧：用于拼装 OAuth 回调地址——Google Search Console 集成使用 ${BASE_URL}/gsc-connected，GA4 导入使用 ${BASE_URL}/ga4-import-connected，OIDC 使用 ${BASE_URL}/socialised。这三项集成不配 BASE_URL 时分别表现为「not configured 提示」或「not configured 报错」。

改动影响：BASE_URL 变更后前端必须重建；若已配置 Google/OIDC 集成，回调 URI 与第三方平台登记值必须同步更新，否则回调 401/redirect_uri mismatch。

5.2 鉴权与会话：SECRET_KEY_BASE

SECRET_KEY_BASE 无默认值、必须设置，官方 Configuring 文档描述其为「用于鉴权密钥与登录会话的种子」。configure.sh 用 openssl rand -base64 48 生成 64 字符随机串。

改动影响：更换该值会使全部已有登录会话失效（签名对不上），用户需重新登录；属于安全事件后的标准轮换手段，但不要在日常运维中随意更换。

5.3 访客 IP 识别：CLIENT_IP_HEADER 与 TRUSTED_PROXY_IPS

• CLIENT_IP_HEADER（默认空，等效使用 x-forwarded-for）：指定从哪个请求头取访客真实 IP。官方给的两条口径——实例前有 Cloudflare 时设为 cf-connecting-ip；自建 Traefik/其他反代时通常 x-forwarded-for 即可。
• TRUSTED_PROXY_IPS：官方 Configuring 文档未列出、但 v5.4.1 后端源码中存在的信任代理网段变量（源码 process.env.TRUSTED_PROXY_IPS，两处引用），用于决定哪些上游代理的 X-Forwarded-For 可以被采信。多级代理部署时可显式指定，单机官方编排无需设置。

IP 头配置错误的影响链：访客 IP 取错 → 独立访客/实时访客计数失真 → 地理位置报表全部归到反代/机房位置；若项目开启了 Strict 级反机器人防护（Shields），机房 IP 的事件会被整体丢弃（API 仍返回成功但数据不入库，需到「Project settings → Shields → Blocked traffic」核对）。

5.4 注册与多实例：DISABLE_REGISTRATION、IS_PRIMARY_NODE

• DISABLE_REGISTRATION（默认 true）：关闭除首个注册用户之外的新用户注册。官方脚本固定写 true，是「单管理员自用」的安全默认；团队场景改为 false 开放注册，或保持 true 由首个账号在后台邀请成员。
• IS_PRIMARY_NODE（默认 true）：多 API 实例横向扩展时的主节点开关。官方文档原话：除主节点外其余实例应设为 false，否则定时任务管理器（cron task manager）会在每个实例上重复运行。单实例部署保持默认即可。

5.5 地理定位：IP_GEOLOCATION_DB_PATH

默认空，使用内置的 DB-IP「IP to City Lite」库，仅提供国家/地区/城市三档。把该变量指向一个 .mmdb 文件路径（容器内路径）可换用更全的数据库：官方指明要点亮 Network intelligence 面板（ISP、组织、使用类型——住宅/商用/机房/蜂窝、连接类型） 需要付费的 MaxMind GeoIP2 ISP/Insights 或含这些字段的付费 DB-IP 库。该变量属于后端变量，换库后重建 swetrix-api 生效。

5.6 事务邮件：SMTP_* 六件套与 SMTP_MOCK

用途边界：Swetrix 只发事务邮件（密码重置、项目邀请等），不发营销邮件。测试与演示环境强烈建议 SMTP_MOCK=true——注册、找回密码的验证码/链接会直接落在 swetrix-api 日志里，无需真实邮箱即可完成全流程。SMTP_HELO_NAME（源码级变量，文档未列）可自定义 SMTP 握手 HELO 名，默认跟随主机名。

5.7 OIDC 单点登录：OIDC_* 六参数

启用顺序：OIDC_ENABLED=true → 填 OIDC_DISCOVERY_URL（形如 https://idp.example.com/.well-known/openid-configuration）与 OIDC_CLIENT_ID/OIDC_CLIENT_SECRET → 在身份提供方登记回调 URI 为 ${BASE_URL}/socialised → 重建后端。

• OIDC_ONLY_AUTH=true 时表单登录/注册入口关闭，只剩 OIDC 一条认证通道（企业内网统一身份的典型用法）。
• OIDC_PROMPT 默认 select_account，透传给身份提供方，控制是否每次弹账号选择。

5.8 Google 双集成：GSC 与 GA4

两组变量各自对应一个 OAuth 客户端（需在 Google Cloud Console 自建）：GOOGLE_GSC_* 供项目设置里连接 Search Console（数据进 SEO 标签页）；GOOGLE_GA4_* 供 GA4 历史数据导入。两者都依赖后端 BASE_URL 拼回调（见 5.1）。未配置时：GSC 表现为集成卡片显示「not configured」提示（无 Connect 按钮），GA4 导入请求直接报「not configured」错误。

5.9 Redis 连接参数

REDIS_HOST（编排固定 redis）、REDIS_PORT（6379）、REDIS_USER（default）、REDIS_PASSWORD。官方文档默认值为 password，但 configure.sh 生成的骨架留空——官方编排镜像以空密码运行（.env 里 REDIS_PASSWORD= 且 Redis 服务未设密码变量之外的保护）。Redis 仅作缓存层，不落持久数据；生产建议补一个强密码并同步到 .env（Redis 服务与 API 服务共用同名变量，Compose 会同时注入两侧）。

5.10 ClickHouse 连接参数

CLICKHOUSE_HOST（http://clickhouse，注意带协议前缀的 HTTP 8123 接口）、CLICKHOUSE_PORT（8123）、CLICKHOUSE_USER（default）、CLICKHOUSE_DATABASE（analytics）、CLICKHOUSE_PASSWORD（必填，强校验）。官方编排里 ClickHouse 服务端镜像侧还设了 CLICKHOUSE_DB=analytics 与同名密码变量，两端一致性由 Compose 的 ${CLICKHOUSE_PASSWORD} 同源引用保证。

5.11 源码级扩展变量（文档未列、v5.4.1 后端实际读取）

以下变量从 v5.4.1 backend 源码 process.env.* 引用中核对得出，官方 Configuring 文档未收录，属高级调优项，默认不设置即可：

⚠️ 注意：上表「云服务域」变量在社区版设置后多数不会生效（对应功能本身是 Cloud 特性），列出的目的是防止误配；TRUSTED_PROXY_IPS、PUBLIC_PROJECT_CACHE_TTL、SMTP_HELO_NAME 三项在 CE 中真实生效。

六、ClickHouse 服务端降内存配置（官方编排附带）

官方编排为 ClickHouse 挂载了 4 个配置覆盖文件，目标把分析库内存压到 250–500MB 量级（官方 README 口径：适合总量 <100 万事件的小站点）。逐文件解读：

preserve-ram-config.xml（服务端全局设置）：

<clickhouse>
  <mark_cache_size>536870912</mark_cache_size>
  <concurrent_threads_soft_limit_num>1</concurrent_threads_soft_limit_num>
</clickhouse>

• mark_cache_size：标记缓存上限 512MB（小实例主内存消耗点之一，显式封顶）。
• concurrent_threads_soft_limit_num：并发查询线程软上限设为 1，牺牲并发换内存。

preserve-ram-user.xml（default 用户 profile）：

<clickhouse>
  <profiles>
    <default>
      <max_block_size>2048</max_block_size>
      <max_download_threads>1</max_download_threads>
      <input_format_parallel_parsing>0</input_format_parallel_parsing>
      <output_format_parallel_formatting>0</output_format_parallel_formatting>
    </default>
  </profiles>
</clickhouse>

四个键都在压单查询的块大小与并行度：块 2048 行、下载/解析/格式化单线程。数据量过 100 万事件后若查询变慢，优先回调 concurrent_threads_soft_limit_num 与 max_block_size。

disable-user-logging.xml（关闭查询日志）与 reduce-logs.xml（日志降噪）：

<clickhouse>
  <profiles>
    <default>
      <log_queries>0</log_queries>
      <log_query_threads>0</log_query_threads>
    </default>
  </profiles>
</clickhouse>

<clickhouse>
  <logger>
    <level>warning</level>
    <console>true</console>
  </logger>
  <query_thread_log remove="remove"/>
  <query_log remove="remove"/>
  <text_log remove="remove"/>
  <trace_log remove="remove"/>
  <metric_log remove="remove"/>
  <asynchronous_metric_log remove="remove"/>
  <session_log remove="remove"/>
  <part_log remove="remove"/>
  <processors_profile_log remove="remove"/>
  <asynchronous_insert_log remove="remove"/>
  <query_metric_log remove="remove"/>
  <opentelemetry_span_log remove="remove"/>
</clickhouse>

前者关掉 system.query_log 类用户级查询日志（ClickHouse 默认会记录每条查询，磁盘增长快），后者把服务端日志级别压到 warning 并移除 12 类系统日志表——两者共同消除 ClickHouse 「日志写爆磁盘」的经典问题。排障时可临时摘掉 reduce-logs.xml 挂载恢复详细日志。

七、生产配置模板

模板一：小站点（日均 <1 万访问、4GB 内存服务器）——官方编排默认形态：

# Swetrix Frontend configuration
BASE_URL=https://analytics.example.com

# Swetrix API configuration
SECRET_KEY_BASE=<openssl rand -base64 48 生成>
DEBUG_MODE=false
IP_GEOLOCATION_DB_PATH=
DISABLE_REGISTRATION=true

# Database credentials
REDIS_PASSWORD=<自定强口令>
CLICKHOUSE_PASSWORD=<openssl rand -hex 32 生成>

# SMTP（建议初期 MOCK，验证流程后再换真实发件）
SMTP_MOCK=true

配套：官方 compose.yaml 原样使用（ClickHouse 四个降内存 XML 全挂载），单机 4GB 内存即可稳定运行；适用磁盘 20GB 起（ClickHouse 数据 + 系统日志已按上文配置压制）。

模板二：团队/中型站点（日均 10 万级访问、8GB+ 内存）：

BASE_URL=https://analytics.example.com
SECRET_KEY_BASE=<openssl rand -base64 48 生成>
DEBUG_MODE=false
DISABLE_REGISTRATION=false
IP_GEOLOCATION_DB_PATH=/data/GeoLite2-City.mmdb
REDIS_PASSWORD=<自定强口令>
CLICKHOUSE_PASSWORD=<openssl rand -hex 32 生成>
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=analytics@example.com
SMTP_PASSWORD=${SMTP_PASSWORD}
FROM_EMAIL=analytics@example.com
SMTP_MOCK=false
OIDC_ENABLED=true
OIDC_DISCOVERY_URL=https://idp.example.com/.well-known/openid-configuration
OIDC_CLIENT_ID=${OIDC_CLIENT_ID}
OIDC_CLIENT_SECRET=${OIDC_CLIENT_SECRET}

配套调整：ClickHouse 摘掉 preserve-ram 组（或仅保留 reduce-logs），给足并发线程；DISABLE_REGISTRATION=false 或走邀请制；IP_GEOLOCATION_DB_PATH 指向自购数据库提升地理与网络维度精度。适用场景：多项目、多成员、需要事务邮件与统一登录的生产部署。

⚠️ 注意：${SMTP_PASSWORD}、${OIDC_CLIENT_ID} 等第三方凭据以环境变量注入方式提供（export SMTP_PASSWORD=... 后再启动编排），避免把真实凭据写进受版本管理的 .env 之外；SECRET_KEY_BASE 与 CLICKHOUSE_PASSWORD 属实例自生成凭据，写入 .env 属正常做法但需保证该文件权限 600。

八、常见问题

Q1：后端启动即退出，日志出现 Set CLICKHOUSE_PASSWORD in .env？ 编排文件的 ${CLICKHOUSE_PASSWORD:?...} 硬校验触发，.env 缺该变量。补上后 docker compose up -d --force-recreate swetrix-api 重建。

Q2：改了 .env 但行为没变化？ 环境变量只在进程启动时读取。改完必须 --force-recreate 重建对应服务；BASE_URL 这类前后端共用变量要同时重建 swetrix 与 swetrix-api 两个服务。

Q3：独立访客数明显偏低/地理位置全是服务器所在地？ 典型的访客 IP 取错：实例前有反代/CDN 而未设 CLIENT_IP_HEADER，或多级代理下 X-Forwarded-For 链路被中间层重写。按 5.3 节校准，必要时配 TRUSTED_PROXY_IPS。

Q4：注册页面提示已关闭注册？ DISABLE_REGISTRATION=true（官方默认）只放行首个注册用户。需要开放注册改 false 并重建后端；团队协作也可以保持关闭、由已有账号在项目内邀请成员。

Q5：忘记密码邮件收不到？ 先确认 SMTP_* 是否配置；未配置 SMTP 时把 SMTP_MOCK=true 打开重建，验证码/重置链接会打印在 swetrix-api 日志中，直接从日志取用即可完成登录。

Q6：ClickHouse 内存占用过高或磁盘增长异常？ 小站点确认 preserve-ram 两个 XML 与 reduce-logs/disable-user-logging 是否按官方编排挂载（第六章）；数据量过百万事件后按 5.x 说明回调并发参数。

九、参考链接

• 官方 Configuring 文档（本文参数基准）：https://swetrix.com/docs/selfhosting/configuring
• 自托管指南：https://swetrix.com/docs/selfhosting/how-to
• 编排仓库（compose.yaml / configure.sh / ClickHouse XML）：https://github.com/swetrix/selfhosting
• 主仓库（backend 源码，源码级变量核对）：https://github.com/Swetrix/swetrix
• Session replays 自托管说明（--force-recreate 出处）：https://swetrix.com/docs/selfhosting/session-replays
• 本站部署篇：《Swetrix Docker Compose 部署指南》
• 本站 API 篇：《Swetrix API 使用详解》

参数核对日期：2026-10-30（官方文档 v5.4.1 时期版本 + 主仓库 tag 源码交叉验证）。