Rybbit 2.9.2 配置参数详解

目标：系统梳理 Rybbit v2.9.2 的四个配置层（环境变量层、ClickHouse 内嵌配置层、站点级配置层、Caddy 反代层）的全部参数：来源、默认值、生效方式与实测验证，并给出按内存分档的生产配置模板。除标注「官方文档溯源」的条目外，全部参数均在 192.168.1.200 服务器（Ubuntu 22.04）实测验证，实测日期 2026-10-30。

一、环境信息

二、前置条件

1. 已按 《Rybbit Docker Compose 部署指南》 完成部署并确认 docker compose ps 全部 healthy；
2. 已注册管理员并至少创建一个站点（站点级配置的验证依赖 site id）；
3. 理解本篇的「配置层」划分——Rybbit 的配置散在四个位置，改错层是新手最常见的无效修改根因：

三、参数查看与修改方式

3.1 环境变量层：.env 是唯一入口

# 查看：compose 会把 .env 与 compose 默认值合成最终配置
cd /opt/rybbit && docker compose config | grep -A3 'BASE_URL' | head -6

# 修改：编辑 .env 后重建（up -d 会自动只重建受影响容器）
docker compose up -d

注意：直接 docker exec 进容器 export 变量无效——compose 重建容器时会以 .env 为准覆盖。

3.2 站点级配置：API 即改即生效

# 查看当前站点全量配置（PUT 同地址回显 config 全字段，GET 亦可）
curl -s -b /opt/rybbit/cookies.txt \
  -X PUT http://127.0.0.1:8129/api/sites/2c0b9eb7c6a2/config \
  -H 'Content-Type: application/json' -H 'Origin: http://192.168.1.200:8129' \
  -d '{"blockBots":false}'

实测回显（节选，全字段即为站点级可配置全集）：

{"success":true,"message":"Site configuration updated successfully","config":{"id":"2c0b9eb7c6a2","siteId":1,"type":"web","public":false,"embedEnabled":false,"saltUserIds":false,"domain":"demo.example.com","blockBots":false,"firstPartyProxy":false,"excludedIPs":[],"excludedCountries":[],"excludedPaths":[],"excludedHostnames":[],"excludedUserAgents":[],"excludedASNs":[],...}}

3.3 ClickHouse 层：进容器核对生效值

# 实测核对异步插入与查询线程数是否按配置生效
docker exec clickhouse clickhouse-client --password frog \
  -q "SELECT name, value FROM system.settings WHERE name IN ('async_insert','wait_for_async_insert','max_threads','max_memory_usage')"

实测回显：

async_insert	1
wait_for_async_insert	1
max_threads	16
max_memory_usage	32000000000

四、参数总览

按配置层汇总 v2.9.2 全部可调参数（默认值实测/源码双确认）：

五、核心参数分类详解

5.1 环境变量层：安全与行为开关

BASE_URL（最高优先级，改错全站不可用） 作用有三：后端可信 Origin 白名单的唯一成员、前端构建期与运行期的 API 基址、tracker/邮件等外发链接的域名。实测验证：.env 设 BASE_URL=http://192.168.1.200:8129 时，带 Origin: http://192.168.1.200:8128 的注册请求被拒——实测回显 {"error":"Origin not allowed","code":"FORBIDDEN"}；改回一致的 8129 端口 Origin 后注册成功。该值必须与浏览器地址栏访问 Rybbit 的地址逐字符一致（协议、域名/IP、端口）。

BETTER_AUTH_SECRET Better Auth 框架的会话签名密钥。官方文档明确要求 32+ 随机字符并用 openssl rand -hex 32 生成。泄露等于全站会话可伪造，必须按密钥管理；轮换后所有用户需重新登录。

DISABLE_SIGNUP false 时注册页开放。生产建议先注册管理员、邀请完团队成员后置 true 并 docker compose up -d 重建——防止实例被陌生人注册占用（实例管理员可在看板邀请用户，官方组织功能见 API 篇）。

CLUSTER_WORKERS（默认 4） 后端 Node.js cluster 的 worker 数。compose 把该值原样注入 backend。事件写入走内存队列（每 worker 独立 1 秒 flush 批量写 ClickHouse），worker 数直接影响写入并发与内存；小内存机器（≤4GB 宿主）建议降为 2。

LITE_DASHBOARD 置 true 后前端走 lite 系列接口（overview-lite、metric-lite 等，v2.9.2 路由实测存在），看板去掉重型组件。低配 VPS 或只看基础指标的场景建议开启，可显著降低 ClickHouse 查询压力。

DISABLE_TELEMETRY Rybbit 默认向上报自身运行指标（产品遥测）。隐私敏感部署置 true，实测置 true 后 compose 传入 backend/client 两容器。

5.2 环境变量层：数据层凭据

三套凭据的默认值全部是演示值，生产必须改（改法一致：.env 修改后重建）：

💡 技术拓展：CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT=1 是这套自动开通机制的前提——它让 default 用户具备建用户/授权的 SQL 权限，backend 启动时才能自建只读查询用户。ClickHouse 的访问控制有两代体系：XML users.xml 静态配置与 SQL 驱动的动态授权（Access Management），Rybbit 选择后者以实现「启动即自愈」的零手工初始化，这是值得借鉴的容器化数据库交付模式。

5.3 ClickHouse 内嵌配置层

官方在 compose configs: 段内嵌 4 份 XML（v2.9.2 源码全文核对），生产调优主要动这份：

<!-- resource_limits.xml 核心：为宿主留出余量，防 ClickHouse 吃光内存 -->
<clickhouse>
  <max_server_memory_usage_to_ram_ratio>0.80</max_server_memory_usage_to_ram_ratio>
  <concurrent_threads_soft_limit_ratio_to_cores>1</concurrent_threads_soft_limit_ratio_to_cores>
  <merges_mutations_memory_usage_to_ram_ratio>0.25</merges_mutations_memory_usage_to_ram_ratio>
</clickhouse>

<!-- user_settings.xml 核心：写入异步化 + 查询资源上限 -->
<clickhouse>
  <profiles>
    <default>
      <enable_json_type>1</enable_json_type>
      <async_insert>1</async_insert>
      <wait_for_async_insert>1</wait_for_async_insert>
      <log_queries>0</log_queries>
      <log_query_threads>0</log_query_threads>
      <log_processors_profiles>0</log_processors_profiles>
      <max_memory_usage>32000000000</max_memory_usage>
      <max_threads>16</max_threads>
    </default>
  </profiles>
</clickhouse>

参数解读（含实测依据）：

1. async_insert=1 + wait_for_async_insert=1：track 接口返回 success 时事件已由服务端确认落库（等待 flush 完成），但看板聚合仍有秒级延迟——实测从发事件到 overview 数字变化约 6 秒（1 秒应用层队列 flush + ClickHouse 异步合并），属预期行为而非故障。
2. max_memory_usage=32GB：单查询内存上限。16GB 宿主必须下调（否则单查询可申请超过物理内存的值，靠 ratio 兜底），建议设为宿主内存的 60%；32GB+ 宿主可保持默认。
3. logging_rules.xml 把 16 类系统日志表全部 remove：官方刻意裁剪（这些表在写入密集场景吃磁盘），排障时若需 query_log 临时去掉对应 remove 行即可，实测该文件位于容器 /etc/clickhouse-server/config.d/logging_rules.xml。
4. 小内存机器额外加 mem_limit: 2560m（本次实测配置）：容器级硬限与 ratio 软限双保险。注意 ratio 0.80 按容器可见内存计算，加 mem_limit 后 ClickHouse 会按 2.56GB 的 80% 自限，实际更省。

5.4 站点级配置层

每个站点一行配置（存 PostgreSQL），全部通过看板「Site Settings」或 PUT /api/sites/<siteId>/config 修改，即时生效。实测字段逐个说明：

站点排除的判定顺序在 v2.9.2 源码 ingestEvent.ts 有明确注释：站点排除最先执行（先于限额与 bot 检测），被排除的访客不会留下任何痕迹也不计 bot 计数。

5.5 Caddy 反代层

启用内置 Caddy 时（docker compose --profile with-webserver up -d）涉及两处配置：

1. .env 的 DOMAIN_NAME：Caddyfile 用 {$DOMAIN} 占位符引用，决定 ACME 签发域名与站点地址；
2. Caddyfile 全局段 email：Let's Encrypt 通知邮箱。

同时必须把 BASE_URL 改为 https://<域名>——三层配置（Caddy 域名、BASE_URL、DNS 解析）必须指向同一地址，这同时根治部署篇记录的 Origin 跨端口 403 问题。Caddy 数据卷 caddy_data（证书）与 caddy_config（配置缓存）已在官方 compose 预定义，重建容器证书不丢。

六、生产配置模板

6.1 4GB 小内存 VPS（个人博客/小站，日均 <10 万 PV）

# .env 关键差异项
BASE_URL=https://analytics.example.com
BETTER_AUTH_SECRET=<openssl rand -hex 32 生成>
DISABLE_SIGNUP=true
CLUSTER_WORKERS=2
LITE_DASHBOARD=true
DISABLE_TELEMETRY=true
CLICKHOUSE_PASSWORD=<强密码>
POSTGRES_PASSWORD=<强密码>
REDIS_PASSWORD=<强密码>

compose 附加：clickhouse mem_limit: 1500m，并把 user_settings.xml 的 max_memory_usage 下调到 2000000000（2GB）。磁盘 SSD 40GB 起。适用：单站点或少数几个站点、开启 LITE_DASHBOARD、CLUSTER_WORKERS=2。

6.2 16GB 中型服务器（多站点/SaaS 产品，日均 <500 万 PV）

本次实测的配置即此档：clickhouse mem_limit: 2560m、其余默认、CLUSTER_WORKERS=4、全功能看板。实测 5 容器稳定运行后宿主内存余量约 7GB。磁盘按 events 表增速预留（ClickHouse 列存压缩后每百万 pageview 约 0.5–2GB，含回放数据需另计）。

6.3 32GB+ 高流量（日均 500 万 PV 以上）

保持官方默认 ratio（0.80）但去掉 mem_limit 让 ClickHouse 用满预算；max_memory_usage 维持 32GB；CLUSTER_WORKERS 提升到 CPU 核数；开启 firstPartyProxy 与 saltUserIds。此档建议把 ClickHouse 迁出 compose 单机形态独立部署（Rybbit 后端通过 CLICKHOUSE_HOST 指向外部集群即可，v2.9.2 环境变量原生支持）。

七、常见问题

1. 改了 .env 不生效？ 环境变量在容器创建时注入，docker compose restart 不会重建环境，必须 docker compose up -d（compose 检测到 env 变化会自动重建对应容器）。实测用 docker compose config 核对合成结果。

2. 看板数据延迟多久正常？ 应用层队列 1 秒 flush（PAGEVIEW_BATCH_SIZE=5000、PAGEVIEW_FLUSH_INTERVAL_MS=1000，v2.9.2 源码常量）+ ClickHouse 异步插入等待，实测端到端约 6 秒。实时访客（live-user-count）走独立计数路径，秒级更新。

3. ClickHouse 内存占用为什么远超预期？ 检查三点：是否保留官方 0.80 ratio（改小会先杀查询后杀进程）；是否未加 mem_limit 而 ratio 按宿主全内存计算；filesystem cache（页缓存）在 free 输出里算 buff/cache 不算进程占用，docker stats clickhouse 才是进程真实值。

4. 多套 Rybbit 栈能跑在同一宿主吗？ 可以，但必须改三处：compose 顶层 name（防 down 互删）、显式子网、全部宿主端口映射。本次实测项目名 rybbit-2.9.2-stack + 子网 10.89.58.0/24 的写法可直接复制。

5. 遥测关了之后有功能损失吗？ 没有。DISABLE_TELEMETRY 只关闭产品运行指标上报（官方用于了解自托管使用情况），分析功能与升级检查完全独立。

6. 站点配置改错了如何回滚？ PUT /api/sites/<siteId>/config 是全字段覆盖式更新，回滚就是再 PUT 一次旧值；config 回显会带回修改后的全量字段，实测可直接作为回滚载荷。

八、参考链接

1. v2.9.2 源码包（.env.example、docker-compose.yml、Caddyfile）：https://github.com/rybbit-io/rybbit/releases/tag/v2.9.2
2. 官方自托管进阶指南（v2.9.2 源码包内 docs/content/docs/(docs)/self-hosting-guides/self-hosting-advanced.mdx）
3. ClickHouse settings 文档：https://clickhouse.com/docs/operations/settings
4. 本专栏部署篇：《Rybbit Docker Compose 部署指南》
5. 本专栏选型篇：《Rybbit 介绍与选型指南》
6. 本专栏 API 篇：《Rybbit 2.9.2 API 使用详解》
7. 同类方案配置参考：《Umami 3.4 配置参数详解》、《Plausible 配置参数详解》