Litlyx Docker Compose 部署指南

在 Ubuntu 服务器上用官方 Docker 镜像部署 Litlyx 0.0.19 五服务自托管栈(dashboard+producer+consumer+MongoDB+Redis):编排编写、启动验证、管理员登录、事件上报出数全流程与排障实录,全部实测。

LitlyxLitlyx网站分析产品分析2026/10/30

Litlyx Docker Compose 部署指南

目标：在一台 Ubuntu 服务器上用官方 Docker 镜像（dashboard + producer + consumer + MongoDB + Redis 五服务）从零部署 Litlyx 自托管版 0.0.19，完成编排编写、服务启动、健康检查、管理员登录、创建项目与事件上报验证的全流程。已在 Ubuntu x86_64 服务器（Docker 27 + Compose v2）上实测通过。

一、环境信息

  • 操作系统：Ubuntu（x86_64）
  • Docker：27.x，Docker Compose v2（docker compose 子命令形式）
  • Litlyx 版本：0.0.19（官方 Docker Hub litlyx/*:latest，构建时间 2025-11-26）
  • 依赖组件：MongoDB 7（官方推荐）、Redis 7
  • 服务端口：dashboard 内部 3000（本文映射宿主机 8134）、producer 内部 3001（映射宿主机 8135）；consumer、MongoDB、Redis 不对宿主机暴露
  • 部署目录：/opt/litlyx（示例，读者按自身目录替换）
  • Compose 项目名：litlyx-v0.0.19-stack（name: 显式指定，防止与他栈同名互删）
  • 自定义网络：litlyx-v0.0.19-net，显式网段 10.89.57.0/24（选槽前先 docker network ls 核对 10.89.x.0/24 已占网段，取空闲槽位）

二、镜像选型说明

服务镜像实测大小选型依据
看板litlyx/litlyx-dashboard:latest282MB官方 Docker Hub 镜像（Nuxt 3 全栈）
采集litlyx/litlyx-producer:latest363MB官方镜像（Express 采集入口）
消费litlyx/litlyx-consumer:latest468MB官方镜像（Stream 消费聚合）
数据库mongo:71.18GB源码 MONGO_CONNECTION_STRING 与官方 README 口径
缓存/队列redis:7170MBRedis Stream 消息队列 + 缓存

架构说明（重要）：实测拉取的三枚 litlyx/*:latest 镜像均为 linux/arm64 架构（docker image inspect 显示 arch=arm64），官方当前构建以 arm64 形态发布。在 x86_64 宿主机上运行依赖 Docker 的跨架构模拟（binfmt_misc/QEMU），本文五服务在 amd64 宿主机上已连续运行验证。若宿主机未启用模拟，执行 docker run --privileged --rm tonistiigi/binfmt --install arm64 一次性安装后重试；纯 arm64 宿主机（Apple Silicon、部分国产化服务器）则天然匹配。编排在三个 litlyx 服务上显式写 platform: linux/arm64 与实际拉取架构保持一致。

选型结论：五个镜像全部来自官方渠道，版本组合照抄本文即可；Litlyx 不提供非 Docker 的官方自托管分发，Compose 是唯一官方自托管路径。

三、前置条件

  1. 服务器已安装 Docker 27+ 与 Docker Compose v2，当前用户在 docker 组；
  2. 宿主机端口 8134、8135 空闲（可用 ss -ltn | grep -E '8134|8135' 自查）；
  3. 服务器可访问外网拉取镜像（国内网络缓慢时配置镜像加速或代理）；
  4. 首次启动期间服务器需能访问 https://license.litlyx.com——dashboard 启动时会校验 NUXT_LICENSE_KEY 并写入本地授权记录，外网不通会导致管理员账号初始化失败（见第十章常见问题一）；
  5. x86_64 宿主机需已启用 arm64 模拟（见第二章架构说明）。

四、部署步骤

4.1 编写编排文件

创建目录与 docker-compose.yml：

mkdir -p /opt/litlyx && cd /opt/litlyx

写入以下编排（本实测栈逐字复现口径，密码按需替换）：

name: litlyx-v0.0.19-stack
services:
  mongo:
    image: mongo:7
    container_name: litlyx-v0.0.19-mongo
    restart: unless-stopped
    environment:
      MONGO_INITDB_ROOT_USERNAME: root
      MONGO_INITDB_ROOT_PASSWORD: q1w2E3r4T!
    volumes:
      - mongo_data:/data/db
    networks: [litlyx-net]

  redis:
    image: redis:7
    container_name: litlyx-v0.0.19-redis
    restart: unless-stopped
    command: ["redis-server", "--requirepass", "q1w2E3r4T!"]
    volumes:
      - redis_data:/data
    networks: [litlyx-net]

  producer:
    image: litlyx/litlyx-producer:latest
    platform: linux/arm64
    container_name: litlyx-v0.0.19-producer
    restart: unless-stopped
    ports:
      - "8135:3001"
    environment:
      - PORT=3001
      - DEV_MODE=false
      - EMAIL_TRPC_URL=none
      - MONGO_CONNECTION_STRING=mongodb://root:q1w2E3r4T!@mongo:27017/Litlyx?authSource=admin
      - STREAM_NAME=LITLYX_STREAM
      - REDIS_URL=redis://redis:6379
      - REDIS_USERNAME=default
      - REDIS_PASSWORD=q1w2E3r4T!
    depends_on:
      - mongo
      - redis
    networks: [litlyx-net]

  consumer:
    image: litlyx/litlyx-consumer:latest
    platform: linux/arm64
    container_name: litlyx-v0.0.19-consumer
    restart: unless-stopped
    environment:
      - DEV_MODE=false
      - EMAIL_TRPC_URL=none
      - EMAIL_SECRET=none
      - MONGO_CONNECTION_STRING=mongodb://root:q1w2E3r4T!@mongo:27017/Litlyx?authSource=admin
      - STREAM_NAME=LITLYX_STREAM
      - REDIS_URL=redis://redis:6379
      - REDIS_USERNAME=default
      - REDIS_PASSWORD=q1w2E3r4T!
      - GROUP_NAME=DATABASE
    depends_on:
      - mongo
      - redis
    networks: [litlyx-net]

  dashboard:
    image: litlyx/litlyx-dashboard:latest
    platform: linux/arm64
    container_name: litlyx-v0.0.19-dashboard
    restart: unless-stopped
    ports:
      - "8134:3000"
    environment:
      - NUXT_LICENSE_KEY=FREE_SELFHOST
      - NUXT_MONGO_CONNECTION_STRING=mongodb://root:q1w2E3r4T!@mongo:27017/Litlyx?authSource=admin
      - NUXT_REDIS_URL=redis://redis:6379
      - NUXT_REDIS_USERNAME=default
      - NUXT_REDIS_PASSWORD=q1w2E3r4T!
      - NUXT_BASE_URL=http://127.0.0.1:3000
      - NUXT_SESSION_PASSWORD=q1w2e3r4q1w2e3r4q1w2e3r4q1w2e3r4
      - NUXT_ADMIN_EMAIL=admin@litlyx.local
      - NUXT_ADMIN_PASSWORD=Q1w2E3r4T!
      - NUXT_PUBLIC_SELFHOSTED=true
      - NUXT_PUBLIC_AI_ENABLED=false
    depends_on:
      - mongo
      - redis
      - producer
      - consumer
    networks: [litlyx-net]

volumes:
  mongo_data:
  redis_data:

networks:
  litlyx-net:
    name: litlyx-v0.0.19-net
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.57.0/24

4.2 启动服务

docker compose up -d

验证运行状态（实测回显）：

$ docker compose ps
NAME                       IMAGE                             COMMAND                  SERVICE     CREATED       STATUS       PORTS
litlyx-v0.0.19-consumer    litlyx/litlyx-consumer:latest     "docker-entrypoint.s…"   consumer    2 hours ago   Up 2 hours
litlyx-v0.0.19-dashboard   litlyx/litlyx-dashboard:latest    "docker-entrypoint.s…"   dashboard   2 hours ago   Up 2 hours   0.0.0.0:8134->3000/tcp, [::]:8134->3000/tcp
litlyx-v0.0.19-mongo       mongo:7                           "docker-entrypoint.s…"   mongo       2 hours ago   Up 2 hours   27017/tcp
litlyx-v0.0.19-producer    litlyx/litlyx-producer:latest     "docker-entrypoint.s…"   producer    2 hours ago   Up 2 hours   0.0.0.0:8135->3001/tcp, [::]:8135->3001/tcp
litlyx-v0.0.19-redis       redis:7                           "docker-entrypoint.s…"   redis       2 hours ago   Up 2 hours   6379/tcp

4.3 健康检查与首次登录

dashboard 启动日志（实测回显，看到 Admin account OK 即初始化完成）：

$ docker logs litlyx-v0.0.19-dashboard
PRIMARY CLUSTER
{ selfhosted: true, aiEnabled: false }
[SELFHOSTED] Admin account Creation
Listening on http://[::]:3000
Cache connected
Database connected
[SELFHOSTED] Admin account OK

consumer 日志（实测回显，消费组就绪标志）：

$ docker logs litlyx-v0.0.19-consumer
Consumer started
Listening on port undefined
requireEnv STREAM_NAME LITLYX_STREAM
requireEnv GROUP_NAME DATABASE
Start reading loop
Group DATABASE already exist

浏览器访问 http://<服务器IP>:8134，使用 NUXT_ADMIN_EMAIL / NUXT_ADMIN_PASSWORD 登录（本文示例 admin@litlyx.local / Q1w2E3r4T!）。命令行验证登录（实测回显）：

$ curl -s -D - -o /dev/null -X POST http://localhost:8134/api/auth/login \
    -H 'Content-Type: application/json' \
    -d '{"email":"admin@litlyx.local","password":"Q1w2E3r4T!"}'
HTTP/1.1 204 No Content
set-cookie: nuxt-session=Fe26.2**8b3bf6ff…; Path=/; Expires=Fri, 06 Nov 2026 06:43:45 GMT; HttpOnly; Secure; SameSite=Lax

返回 204 并下发 nuxt-session Cookie 即登录成功（会话有效期 7 天）。

4.4 验证数据链路（上报出数）

登录后进入项目（Workspace）详情页，取得项目 ID（MongoDB projects 集合 _id，实测值形如 6ae4267da0064c0b9a6c9546）。向 producer 采集端口上报一条测试访问与一条自定义事件（注意所有值必须为字符串，原因见第十章常见问题五）：

$ curl -s -o /dev/null -w 'visit:%{http_code}\n' -X POST http://localhost:8135/visit \
    -H 'Content-Type: application/json' \
    -d '{"pid":"6ae4267da0064c0b9a6c9546","website":"doc-demo.example.com","userAgent":"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 Chrome/126.0 Safari/537.36","browser":"Chrome","os":"Linux","device":"Desktop","page":"/docs/getting-started","referrer":"https://www.google.com/","screenWidth":"1920","screenHeight":"1080","language":"zh-CN"}'
visit:200

$ curl -s -o /dev/null -w 'event:%{http_code}\n' -X POST http://localhost:8135/event \
    -H 'Content-Type: application/json' \
    -d '{"pid":"6ae4267da0064c0b9a6c9546","website":"doc-demo.example.com","userAgent":"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 Chrome/126.0 Safari/537.36","name":"click_download","metadata":"{}"}'
event:200

数秒后在看板该项目中即可看到访问记录与事件 click_download；用带会话 Cookie 的 API 查询也可确认（实测回显）：

$ curl -s -b cookies.txt 'http://localhost:8134/api/project/stats?pid=6ae4267da0064c0b9a6c9546'
{"chart":{"labels":[null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null],"data":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,4,0,1]}}

上报端点字段、认证机制与更多数据接口详见 《Litlyx API 使用详解》。

五、数据持久化说明

持久化由两个命名卷承担：

卷名挂载点内容
mongo_data/data/db全部业务数据（用户、项目、访问、事件、聚合）
redis_data/dataStream 积压消息与指标缓存（消费后即短生命周期）

实测卷清单：

$ docker volume ls | grep litlyx
local     litlyx-v0.0.19-stack_mongo_data
local     litlyx-v0.0.19-stack_redis_data

核心数据都在 MongoDB：docker compose down 不带 -v 时卷保留，重新 up 数据完好；down -v 会连卷一起删除，执行前务必确认（本篇收尾清理即用 down -v）。MongoDB 备份用 mongodump：

docker exec litlyx-v0.0.19-mongo mongodump -u root -p 'q1w2E3r4T!' --authenticationDatabase admin --db Litlyx --archive --gzip > litlyx-$(date +%F).archive.gz

六、环境变量表

按服务分组（实测生效值；变量全集详解见 《Litlyx v0.0.19 配置参数详解》，此处列部署必填项）：

dashboard

变量实测值必填说明
NUXT_LICENSE_KEYFREE_SELFHOST✅自托管许可键，官方默认值
NUXT_MONGO_CONNECTION_STRINGmongodb://root:q1w2E3r4T!@mongo:27017/Litlyx?authSource=admin✅MongoDB 连接串
NUXT_REDIS_URL / NUXT_REDIS_USERNAME / NUXT_REDIS_PASSWORDredis://redis:6379 / default / q1w2E3r4T!✅Redis 连接三件套
NUXT_BASE_URLhttp://127.0.0.1:3000✅站点自身地址（邮件确认链接等使用）
NUXT_SESSION_PASSWORD≥32 字符随机串✅会话 Cookie 加密密钥
NUXT_ADMIN_EMAIL / NUXT_ADMIN_PASSWORDadmin@litlyx.local / Q1w2E3r4T!✅自托管管理员账号（首启创建，每次重启重置）
NUXT_PUBLIC_SELFHOSTEDtrue✅开启自托管模式
NUXT_PUBLIC_AI_ENABLEDfalse可选关闭 AI 助手

producer

变量实测值必填说明
PORT3001✅监听端口
MONGO_CONNECTION_STRING同上✅连接库（防护规则读取用）
REDIS_URL / REDIS_USERNAME / REDIS_PASSWORD同上✅Stream 写入用
STREAM_NAMELITLYX_STREAM✅与 consumer 一致
DEV_MODEfalse可选开发模式开关
EMAIL_TRPC_URLnone可选邮件服务地址（自托管置 none）

consumer

producer 基础上增加 EMAIL_SECRET=none、GROUP_NAME=DATABASE（Redis Stream 消费组名，保持默认）。

mongo / redis

MONGO_INITDB_ROOT_USERNAME/MONGO_INITDB_ROOT_PASSWORD 建库凭据；Redis 通过 --requirepass 设密码。

七、配置参数说明

Litlyx 的全部配置通过环境变量注入，无配置文件：

  1. dashboard 的变量带 NUXT_ 前缀（Nuxt runtimeConfig 约定），producer/consumer 为裸变量名；
  2. NUXT_PUBLIC_* 前缀的变量会暴露到浏览器端（SELFHOSTED、AI_ENABLED），改后需强刷浏览器；
  3. 三处 MONGO_CONNECTION_STRING（dashboard/producer/consumer）与两处 Redis 连接组必须指向同一实例，STREAM_NAME 两侧必须一致，否则上报与出数会静默断链；
  4. 会话密钥 NUXT_SESSION_PASSWORD 改动会使所有已登录会话失效（Cookie 解密失败）。

八、配置文件挂载

无配置文件挂载项。可选的挂载增强：

    volumes:
      - ./mongodump:/backup        # 备份产物落盘
    # - ./ssl:/etc/nginx/ssl:ro   # 如外置 nginx 做 TLS 终结，证书挂载示例

生产建议在 Litlyx 前置 nginx/Caddy 做 HTTPS 与路径收敛（8134/8135 不直接对公网），反向代理转发时须携带 X-Forwarded-For 头（Litlyx 按该头识别访客 IP，裸露直连则全部记为代理 IP）。

九、等价 docker run

五服务组合强依赖网络互访与环境变量全集，仅给出 dashboard 单容器等价命令供理解（实际部署请用 Compose）：

docker run -d --name litlyx-v0.0.19-dashboard \
  -p 8134:3000 \
  -e NUXT_LICENSE_KEY=FREE_SELFHOST \
  -e NUXT_MONGO_CONNECTION_STRING='mongodb://root:q1w2E3r4T!@mongo:27017/Litlyx?authSource=admin' \
  -e NUXT_REDIS_URL=redis://redis:6379 \
  -e NUXT_REDIS_USERNAME=default \
  -e NUXT_REDIS_PASSWORD='q1w2E3r4T!' \
  -e NUXT_BASE_URL=http://127.0.0.1:3000 \
  -e NUXT_SESSION_PASSWORD=q1w2e3r4q1w2e3r4q1w2e3r4q1w2e3r4 \
  -e NUXT_ADMIN_EMAIL=admin@litlyx.local \
  -e NUXT_ADMIN_PASSWORD='Q1w2E3r4T!' \
  -e NUXT_PUBLIC_SELFHOSTED=true \
  -e NUXT_PUBLIC_AI_ENABLED=false \
  --network litlyx-v0.0.19-net \
  litlyx/litlyx-dashboard:latest

十、常用运维命令

# 服务状态 / 日志跟踪
docker compose ps
docker compose logs -f dashboard

# 重启单个服务（改环境变量后）
docker compose up -d dashboard

# 停止（保留数据卷）
docker compose down

# 彻底清除（含数据卷，慎用）
docker compose down -v

# MongoDB 数据备份
docker exec litlyx-v0.0.19-mongo mongodump -u root -p 'q1w2E3r4T!' --authenticationDatabase admin --db Litlyx --archive --gzip > litlyx-backup.archive.gz

# MongoDB 数据恢复
cat litlyx-backup.archive.gz | docker exec -i litlyx-v0.0.19-mongo mongorestore -u root -p 'q1w2E3r4T!' --authenticationDatabase admin --archive --gzip --drop

十一、常见问题

一、dashboard 日志报 Admin account Creation 后无 Admin account OK 或重启循环

dashboard 首次启动会调用 https://license.litlyx.com/license/<NUXT_LICENSE_KEY> 校验许可（源码 server/plugins/selfhost.ts），外网不通时该步骤抛错、管理员账号不落库，登录报 Email or Password wrong。解决：确认服务器可出网到该域名后 docker compose restart dashboard；FREE_SELFHOST 为官方默认许可键，无需购买。

二、管理员密码每次重启被重置

自托管模式下 dashboard 每次启动都会用 NUXT_ADMIN_EMAIL/PASSWORD 覆盖式重建管理员（upsert）。看板里改过密码、重启后失效即此机制，属预期行为。固定密码做法：编排里设好 NUXT_ADMIN_PASSWORD 不再变动。

三、x86_64 服务器启动 litlyx 服务报 exec format error

官方镜像为 arm64 架构，宿主机未启用跨架构模拟。执行 docker run --privileged --rm tonistiigi/binfmt --install arm64 后 docker compose up -d 重试。

四、端口 8134/8135 冲突

用 ss -ltnp | grep 8134 找占用进程，或改编排左侧宿主端口（右侧 3000/3001 为容器内约定不可改）。

五、上报返回 500 {"error":"Invalid argument type"}

producer 将请求体原样写入 Redis Stream，Redis Stream 只接受字符串键值。请求体里出现数字类型（如 "screenWidth":1920）即触发该错误，改为字符串 "1920" 即恢复 200。自托管脚本上报不受影响（官方 litlyx.js 已按字符串发送），手工 curl/cURL 集成时需注意。

六、上报返回 200 但看板无数据

检查 STREAM_NAME 两侧是否一致、consumer 是否在跑（docker logs litlyx-consumer 应有 Start reading loop）；若 consumer 日志出现 events validation failed，说明自定义事件用了错误字段名——事件名字段是 name（不是 eventName），见 《Litlyx API 使用详解》 的错误码章节。

十二、参考链接

  1. 官方仓库自托管说明：https://github.com/litlyx/litlyx（README "Self-hosting with docker"）
  2. 官方文档站：https://docs.litlyx.com
  3. Docker Hub 镜像：https://hub.docker.com/u/litlyx
  4. 产品认知与同类平台对比：本专栏 《Litlyx 介绍与选型指南》
  5. 环境变量全集逐项详解：本专栏《Litlyx v0.0.19 配置参数详解》
  6. 同类平台部署参照：《Swetrix Docker Compose 部署指南》、《Rybbit Docker Compose 部署指南》