Litlyx v0.0.19 配置参数详解

目标：逐项讲清 Litlyx 自托管版 0.0.19 全部配置参数——三个应用服务的环境变量全集（dashboard 的 NUXT_ 前缀变量、producer/consumer 的裸变量）、MongoDB/Redis 依赖组件配置、修改方式与生产推荐配置。参数生效值全部来自运行中实例的容器环境实查与源码 runtimeConfig/requireEnv 取证。

一、环境信息

• 操作系统：Ubuntu（x86_64，arm64 官方镜像经 binfmt 模拟运行）
• Docker：27.x + Compose v2，编排项目 litlyx-v0.0.19-stack（部署过程见 《Litlyx Docker Compose 部署指南》）
• Litlyx 版本：0.0.19（litlyx/litlyx-{dashboard,producer,consumer}:latest，2025-11-26 构建）
• 取证方式：
  • 运行实例实查：docker inspect <服务> --format '{{range .Config.Env}}{{println .}}{{end}}'；
  • 源码取证：dashboard/nuxt.config.ts 的 runtimeConfig 声明、producer/consumer 的 requireEnv 启动检查；
  • 启动日志：consumer 启动时逐个打印 requireEnv <变量> <值>。

二、前置条件

1. 已有按部署篇运行中的五服务栈（dashboard/producer/consumer/MongoDB/Redis）；
2. 理解 Litlyx 配置的两个命名约定：
   • dashboard 变量带 NUXT_ 前缀：Nuxt runtimeConfig 将 NUXT_MONGO_CONNECTION_STRING 映射为代码内 MONGO_CONNECTION_STRING，NUXT_PUBLIC_* 前缀映射到 public 命名空间并暴露给浏览器；
   • producer/consumer 用裸变量名，不带前缀；
3. 改动环境变量的生效路径统一为：编辑 docker-compose.yml → docker compose up -d <服务名> 重建对应容器 → 核对启动日志。

三、参数查看与修改方式

查看运行值（实测命令与回显）：

$ docker inspect litlyx-v0.0.19-producer --format '{{range .Config.Env}}{{println .}}{{end}}' | grep -vE '^(PATH|NODE_VERSION|YARN_VERSION|HOME|HOSTNAME|TERM|LANG|GPG_KEY|NODE_ICU_DATA|npm_config)'
MONGO_CONNECTION_STRING=mongodb://root:q1w2E3r4T!@mongo:27017/Litlyx?authSource=admin
REDIS_PASSWORD=q1w2E3r4T!
PORT=3001
EMAIL_TRPC_URL=none
STREAM_NAME=LITLYX_STREAM
REDIS_URL=redis://redis:6379
REDIS_USERNAME=default
DEV_MODE=false

consumer 启动日志自带参数核对信息（实测回显）：

$ docker logs litlyx-v0.0.19-consumer | head -8
requireEnv EMAIL_SECRET none
requireEnv MONGO_CONNECTION_STRING mongodb://root:q1w2E3r4T!@mongo:27017/Litlyx?authSource=admin
Consumer started
Listening on port undefined
requireEnv STREAM_NAME LITLYX_STREAM
requireEnv GROUP_NAME DATABASE
Start reading loop
Group DATABASE already exist

修改流程（实测验证过）：

cd /opt/litlyx
vi docker-compose.yml                       # 修改目标服务的 environment 段
docker compose up -d dashboard              # 只重建受影响服务
docker logs litlyx-v0.0.19-dashboard | tail # 核对启动日志

四、参数总览

三个应用服务合计 24 个源码声明变量（自托管常用 18 个），按服务分：

OAuth 与云版专属变量的存在依据为源码 dashboard/nuxt.config.ts runtimeConfig 声明（含 oauth.google.clientId/clientSecret/redirectURL），自托管默认未启用。

五、核心参数分类详解

5.1 数据库连接类

NUXT_MONGO_CONNECTION_STRING / MONGO_CONNECTION_STRING（三处）

• 格式：mongodb://<用户>:<密码>@mongo:27017/Litlyx?authSource=admin；
• 三处（dashboard/producer/consumer）必须指向同一 MongoDB 实例、同一 Litlyx 库名——数据库名固定为 Litlyx（源码写死口径，改名会导致 consumer 落库与 dashboard 查询不在同一库）；
• authSource=admin 不可省略：mongo 镜像以 root 建号时凭据在 admin 库；
• 值内含 @、: 的密码需 URL 编码。

Redis 连接三件套 REDIS_URL / REDIS_USERNAME / REDIS_PASSWORD

• REDIS_URL 格式 redis://redis:6379（密码走独立变量，不拼在 URL 里）；
• dashboard 带 NUXT_ 前缀，producer/consumer 不带，两侧密码必须一致；
• Redis 密码由 redis 服务启动参数 --requirepass q1w2E3r4T! 设定，修改时两侧同步改（redis 启动命令 + 三个应用变量），否则应用报认证失败、采集断链。

STREAM_NAME（producer/consumer 各一处）

• 默认 LITLYX_STREAM；Redis Stream 的键名，producer 向其写入 visit/event/keep_alive 三类消息，consumer 从其消费；
• 两侧不一致是最典型的静默断链：producer 写入成功（返回 200）但 consumer 消费的是另一个 Stream，看板永远无数据且无报错。

GROUP_NAME（仅 consumer）

• 默认 DATABASE；Redis Stream 消费组名。多 consumer 实例共用同一消费组可水平扩展消费能力；首次启动自动创建（日志 Group DATABASE already exist 为正常回显）。

5.2 认证与会话类

NUXT_SESSION_PASSWORD

• 会话 Cookie（nuxt-session）的加密密钥，实测要求 ≥32 字符（不足时启动报错）；
• 实测会话行为：登录返回 set-cookie: nuxt-session=Fe26.2**…; HttpOnly; SameSite=Lax，有效期 7 天（maxAge: 60*60*24*7）；
• 该密钥改动后所有既有会话立即失效（旧 Cookie 解密失败，需重新登录）。

NUXT_ADMIN_EMAIL / NUXT_ADMIN_PASSWORD

• 自托管管理员引导账号：dashboard 每次启动执行 UserModel.updateOne(... upsert) 覆盖式重建该账号（密码以 scrypt 哈希落库）；
• 含义是「重启后管理员密码恢复为该变量值」——看板内改过密码、容器重启后失效属预期行为；
• 生产建议设为强密码且不在变更后删除。

NUXT_LICENSE_KEY

• 自托管固定值 FREE_SELFHOST；dashboard 启动时调用 https://license.litlyx.com/license/<KEY> 校验（首次启动需外网），校验通过写入本地 premium 记录（premium_type=9999）；
• 断网部署的坑：license 请求失败会中断启动插件，管理员账号不创建，登录一直报 Email or Password wrong。

NUXT_RESET_PASSWORD_SECRET

• 「忘记密码」链接的签名密钥；自托管未配置邮件服务时该功能不可用，可不设。

Google OAuth 三件套 NUXT_OAUTH_GOOGLE_CLIENT_ID / NUXT_OAUTH_GOOGLE_CLIENT_SECRET / NUXT_OAUTH_GOOGLE_REDIRECT_URI

• 源码含 /api/auth/google 路由；配置后登录页出现 Google 登录入口。自托管内网环境通常不适用，可不设。

5.3 服务端口与运行类

PORT（producer）

• 采集服务监听端口，容器内默认 3001；对外暴露靠 compose 端口映射（实测 8135:3001），容器外端口随意改，容器内 3001 与官方镜像 EXPOSE 对应。

NUXT_BASE_URL

• dashboard 自身可达地址，用于拼接邮件确认链接等；自托管未配邮件时基本不生效，建议设为实际访问地址（如 http://<服务器IP>:8134）。

DEV_MODE（producer/consumer）

• 开发调试开关，生产固定 false。

5.4 功能开关类

NUXT_PUBLIC_SELFHOSTED

• true 开启自托管模式（启用管理员引导、隐藏云版计费入口），并作为浏览器端可见的运行模式标识。

NUXT_PUBLIC_AI_ENABLED + NUXT_AI_ORG/PROJECT/KEY

• AI 数据助手开关；自托管置 false（浏览器端标识 + 服务端双重判断）。开启需提供云版 AI 凭据，自托管无官方凭据来源。

NUXT_EMAIL_TRPC_URL / NUXT_EMAIL_SECRET（三服务）

• 邮件微服务地址与密钥（tRPC 协议）；自托管统一置 none（实测值），注册确认/忘记密码邮件功能随之停用——自托管管理员账号不走邮件确认，不受影响。

NUXT_PAYMENT_TRPC_URL / NUXT_PAYMENT_SECRET / NUXT_MODE

• 云版计费微服务与运行模式变量，自托管不配置（源码 runtimeConfig 声明，实测容器内未注入）。

5.5 MongoDB 与 Redis 自身配置

mongo 服务

• MONGO_INITDB_ROOT_USERNAME / MONGO_INITDB_ROOT_PASSWORD：仅数据目录为空时执行初始化生效；已有数据后修改这两个变量不会改密码（需进 mongo shell 改），同步改连接串时注意；
• 数据库名 Litlyx 不在环境变量中，由连接串路径段指定。

redis 服务

• 实测以 command: ["redis-server", "--requirepass", "q1w2E3r4T!"] 启动；Stream 消息持久化依赖默认 RDB 快照（实测日志有周期性 Background saving 回显）。

六、生产配置模板

适用场景：日均 10 万 PV 以内的站点分析，2 vCPU / 4GB 内存 / 20GB SSD 单机。实测五服务常驻内存合计约 775MiB（空载数据量下），4GB 内存余量充足：

推荐增量配置（在部署篇编排基础上追加）：

  mongo:
    command: ["mongod", "--wiredTigerCacheSizeGB", "1"]   # 限制 WiredTiger 缓存，防内存膨胀
  dashboard:
    environment:
      - NUXT_BASE_URL=https://analytics.example.com        # 换成实际对外地址
      - NUXT_SESSION_PASSWORD=<openssl rand -base64 36 生成>
      - NUXT_ADMIN_PASSWORD=<强密码>

要点：

1. NUXT_SESSION_PASSWORD 与 NUXT_ADMIN_PASSWORD 上生产前必须换掉本文示例值；
2. 对外暴露只保留 dashboard 端口；producer 采集端口（8135）建议经反代以 /event、/visit 路径收敛后发布，并转发 X-Forwarded-For（Litlyx 靠它识别访客 IP，直连代理端口则访客 IP 全部失真）；
3. MongoDB 定期 mongodump 备份（命令见部署篇运维章节）；
4. 需要邮件功能（注册确认/忘记密码）的团队，自托管需自建并指向 EMAIL_TRPC_URL——官方未开源该邮件微服务的独立部署文档，属自托管功能边界。

七、常见问题

一、改了环境变量不生效

必须 docker compose up -d <服务> 重建容器（仅 restart 不会应用新 environment）。重建后核对启动日志（consumer 的 requireEnv 打印、dashboard 的 { selfhosted: ..., aiEnabled: ... } 回显）。

二、上报 200 但看板始终无数据

按顺序排查：STREAM_NAME 两侧是否一致 → GROUP_NAME 是否被改动 → consumer 日志有无 validation 错误 → Mongo visits 集合是否有新文档。全套链路与错误现象见 《Litlyx API 使用详解》。

三、启动报 ADMIN_EMAIL is not defined in env

自托管模式（NUXT_PUBLIC_SELFHOSTED=true）下管理员变量必填，漏配即启动插件抛错。补齐 NUXT_ADMIN_EMAIL/NUXT_ADMIN_PASSWORD 后重建。

四、修改 mongo 密码后连不上

MONGO_INITDB_ROOT_* 只在空数据目录时生效。改密码的正确路径：mongo shell db.changeUserPassword → 同步改三处连接串 → 重建三个应用服务。

五、忘记 NUXT_SESSION_PASSWORD 要求

密钥长度不足 32 字符时会话加密启动失败，报错信息不含原因，用 openssl rand -base64 36 生成即可。

八、参考链接

1. 源码配置声明：https://github.com/litlyx/litlyx（`dashboard/nuxt.config.ts`、`producer/src`、`consumer/src` 的 requireEnv）
2. 官方文档站：https://docs.litlyx.com
3. 部署过程与编排全量文件：本专栏 《Litlyx Docker Compose 部署指南》
4. 产品认知与版本背景：本专栏 《Litlyx 介绍与选型指南》
5. 采集端点与数据接口参数：本专栏《Litlyx API 使用详解》
6. 同类平台配置参照：《Swetrix v5.4.1 配置参数详解》