Plausible Docker Compose 部署指南

‍‍‌> 目标：在 Ubuntu 22.04 服务器上以 Docker Compose 完成隐私优先网站分析工具 Plausible CE（应用 + ClickHouse + PostgreSQL 三服务编排）的完整部署、初始化与埋点接入验证。本文全部命令与回显均在实测环境逐条执行并照抄，实测版本 Plausible CE v3.2.1（官方最新稳定版）；参数级调优见《Plausible 配置参数详解》，API 验证见《Plausible API 使用详解》。

一、环境信息

项目	值
操作系统	Ubuntu 22.04.4 LTS
Docker	Client/Server 29.8.1
Docker Compose	v5.5.1
部署目录	`/opt/data/plausible/`（数据）/ `~/plausible-lab/`（编排文件，示例中为 `/opt/data/quzuo/plausible-lab`）
服务端口	UI/API：`13910`（映射应用内 `8000`）
组件版本	`ghcr.io/plausible/community-edition:v3.2.1`、`clickhouse/clickhouse-server:24.12-alpine`（实测 24.12.6.70）、`postgres:16-alpine`（实测 16.15）
主机地址	`192.168.146.128`（下文 `BASE_URL` 均以此为例）
资源约束	ClickHouse 限内存 `512m`（实测常驻 217.3MiB）；三服务合计常驻约 710MiB（应用 399.3MiB + ClickHouse 217.3MiB + PostgreSQL 92.4MiB，`docker stats` 实测）
实测日期	2026-10-18

二、镜像选型说明

组件	镜像与 Tag	选型理由
应用	`ghcr.io/plausible/community-edition:v3.2.1`	官方唯一应用镜像；固定具体版本 tag，避免 `latest` 升级不可控；镜像内运行用户 uid=999
事件库	`clickhouse/clickhouse-server:24.12-alpine`	官方编排指定版本（`24.12-alpine`），与 v3.x 的表结构/协议兼容；alpine 变体体积小
元数据库	`postgres:16-alpine`	官方编排指定版本（PostgreSQL 16）；alpine 变体体积小

📌 官方 compose.yml（community-edition 仓库 master 分支）当前锁定的就是 clickhouse-server:24.12-alpine + postgres:16-alpine，本文照官方基线仅做三点适配：固定应用 tag 为 v3.2.1、UI 端口改 13910、数据改绑定挂载到 /opt/data/plausible/。

三、前置条件

服务器已安装 Docker（≥ 24.x，实测 29.8.1）与 Docker Compose 插件（实测 v5.5.1）；
防火墙/安全组放行 UI 端口（本文 13910/tcp）；
服务器可访问官方镜像仓库 ghcr.io 与 Docker Hub（离线环境需提前导入镜像）；
规划好外部访问地址 BASE_URL（协议 + 域名/IP + 端口），它决定注册确认链接、埋点脚本地址与邮件里的站点链接，部署后不建议再改；
内存建议 ≥ 2GB（实测三服务合计常驻约 710MiB，需预留系统与缓存余量）。

四、部署步骤

4.1 创建目录与获取官方编排文件

# 创建数据目录（应用进程 uid=999，稍后修正属主）
mkdir -p /opt/data/plausible/app /opt/data/plausible/postgres \
         /opt/data/plausible/clickhouse/data /opt/data/plausible/clickhouse/logs

# 编排文件目录
mkdir -p ~/plausible-lab/clickhouse && cd ~/plausible-lab

# 官方仓库文件（compose + ClickHouse 低资源配置，实测下载成功）
curl -sSL -o compose.yml \
  https://raw.githubusercontent.com/plausible/community-edition/master/compose.yml
curl -sSL -o clickhouse/logs.xml \
  https://raw.githubusercontent.com/plausible/community-edition/master/clickhouse/logs.xml
curl -sSL -o clickhouse/ipv4-only.xml \
  https://raw.githubusercontent.com/plausible/community-edition/master/clickhouse/ipv4-only.xml
curl -sSL -o clickhouse/low-resources.xml \
  https://raw.githubusercontent.com/plausible/community-edition/master/clickhouse/low-resources.xml
curl -sSL -o clickhouse/default-profile-low-resources-overrides.xml \
  https://raw.githubusercontent.com/plausible/community-edition/master/clickhouse/default-profile-low-resources-overrides.xml

📌 low-resources.xml 已在事件数据库中预建用户 plausible，应用默认就是用它连接 ClickHouse，无需手动建库建用户；如需给 ClickHouse 更高内存可去掉 low-resources.xml 的挂载。

4.2 编写 `.env`（BASE_URL 与 SECRET_KEY_BASE）

# 生成应用密钥（官方推荐 openssl 生成，>=64 字节）
openssl rand -base64 48
# 实测输出（示例，请勿照抄使用）：
# S3jOczEZi7NlB4U1LcjpR5rPFdCNl8pcOTLC9Oc9VJkrO4Uy1VNlo0BlC1/H9EZIYhCcvRKApAswUwWKoMFfcg==

cat > .env <<'EOF'
BASE_URL=http://192.168.146.128:13910
SECRET_KEY_BASE=S3jOczEZi7NlB4U1LcjpR5rPFdCNl8pcOTLC9Oc9VJkrO4Uy1VNlo0BlC1/H9EZIYhCcvRKApAswUwWKoMFfcg==
EOF

BASE_URL：外部访问地址（决定埋点脚本域名、注册/邮件链接），部署后不要随意变更；
SECRET_KEY_BASE：会话签名/加密密钥，泄露等同接管全部账号，必须保存好；实测验证变更它会导致全体登录态立即失效（见 4.6）。

4.3 编写 `compose.yml`（三服务逐段说明）

官方 compose.yml 逐段结构如下（与本文实测部署一致，仅端口/挂载/限内存为本地适配，注释为逐段说明）：

name: plausible

services:
  # ── ① 元数据库：用户/站点/API Key 等业务数据 ──
  plausible_db:
    image: postgres:16-alpine            # 官方锁定版本
    restart: always
    volumes:                             # 官方为 named volume，此处改绑定挂载便于备份
      - /opt/data/plausible/postgres:/var/lib/postgresql/data
    environment:
      - POSTGRES_PASSWORD=postgres       # 内网编排内通信；如暴露端口请改强密码
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      start_period: 1m

  # ── ② 事件数据库：页面浏览/事件明细，列式存储 ──
  plausible_events_db:
    image: clickhouse/clickhouse-server:24.12-alpine
    restart: always
    mem_limit: 512m                      # 本地适配：限制 ClickHouse 内存（实测常驻 217.3MiB）
    volumes:
      - /opt/data/plausible/clickhouse/data:/var/lib/clickhouse
      - /opt/data/plausible/clickhouse/logs:/var/log/clickhouse-server
      - ./clickhouse/logs.xml:/etc/clickhouse-server/config.d/logs.xml:ro
      - ./clickhouse/ipv4-only.xml:/etc/clickhouse-server/config.d/ipv4-only.xml:ro
      - ./clickhouse/low-resources.xml:/etc/clickhouse-server/config.d/low-resources.xml:ro
      - ./clickhouse/default-profile-low-resources-overrides.xml:/etc/clickhouse-server/users.d/default-profile-low-resources-overrides.xml:ro
    ulimits:
      nofile:
        soft: 262144                     # 官方要求，ClickHouse 打开文件数
        hard: 262144
    healthcheck:
      test: ["CMD-SHELL", "wget --no-verbose --tries=1 -O - http://127.0.0.1:8123/ping || exit 1"]
      start_period: 1m

  # ── ③ 应用：Web 仪表盘 + API + 采集 ──
  plausible:
    image: ghcr.io/plausible/community-edition:v3.2.1
    restart: always
    # 官方启动命令：先建库、再迁移、最后启动应用
    command: sh -c "/entrypoint.sh db createdb && /entrypoint.sh db migrate && /entrypoint.sh run"
    depends_on:                          # 等两个数据库健康后再启动应用
      plausible_db:
        condition: service_healthy
      plausible_events_db:
        condition: service_healthy
    ports:
      - "13910:8000"                     # 本地适配：UI 端口 13910 → 容器内 8000
    volumes:
      - /opt/data/plausible/app:/var/lib/plausible   # 下载缓存/tzdata 副本等
    ulimits:
      nofile:
        soft: 65535
        hard: 65535
    environment:                         # 变量透传：在 .env 里按需增删
      - TMPDIR=/var/lib/plausible/tmp
      - BASE_URL=${BASE_URL}
      - SECRET_KEY_BASE=${SECRET_KEY_BASE}
      - TOTP_VAULT_KEY                   # 可选：双因素密钥加密
      - DISABLE_REGISTRATION
      - ENABLE_EMAIL_VERIFICATION
      - HTTP_PORT
      - HTTPS_PORT
      - DATABASE_URL
      - CLICKHOUSE_DATABASE_URL
      - GOOGLE_CLIENT_ID
      - GOOGLE_CLIENT_SECRET
      - IP_GEOLOCATION_DB
      - GEONAMES_SOURCE_FILE
      - MAXMIND_LICENSE_KEY
      - MAXMIND_EDITION
      - MAILER_ADAPTER
      - MAILER_EMAIL
      - MAILER_NAME
      - SMTP_HOST_ADDR
      - SMTP_HOST_PORT
      - SMTP_USER_NAME
      - SMTP_USER_PWD
      - SMTP_HOST_SSL_ENABLED
      - POSTMARK_API_KEY
      - MAILGUN_API_KEY
      - MAILGUN_DOMAIN
      - MAILGUN_BASE_URI
      - MANDRILL_API_KEY
      - SENDGRID_API_KEY

4.4 启动

cd ~/plausible-lab
docker compose up -d

实测回显（首次执行会先拉取镜像；以下为 docker compose up -d 的启动输出，取自实测 down → up 完整循环）：

Network plausible_default Creating
Network plausible_default Created
Container plausible-v3.2.1-clickhouse Creating
Container plausible-v3.2.1-postgres Creating
Container plausible-v3.2.1-postgres Created
Container plausible-v3.2.1-clickhouse Created
Container plausible-v3.2.1-app Creating
Container plausible-v3.2.1-app Created
Container plausible-v3.2.1-postgres Starting
Container plausible-v3.2.1-clickhouse Starting
Container plausible-v3.2.1-postgres Started
Container plausible-v3.2.1-clickhouse Started
Container plausible-v3.2.1-clickhouse Waiting
Container plausible-v3.2.1-postgres Waiting
Container plausible-v3.2.1-postgres Healthy
Container plausible-v3.2.1-clickhouse Healthy
Container plausible-v3.2.1-app Starting
Container plausible-v3.2.1-app Started

等待约 30~60 秒（应用需完成建库与迁移），验证健康检查：

curl -s http://127.0.0.1:13910/api/health

实测回显：

{"sessions":"ok","postgres":"ok","clickhouse":"ok","sites_cache":"ok"}

# 浏览器访问（或本机 curl 验证跳转）
curl -s -o /dev/null -w '%{http_code} -> %{redirect_url}\n' http://127.0.0.1:13910/

实测回显（全新实例，首页跳注册页）：

302 -> http://127.0.0.1:13910/register

⚠️ 若 plausible 服务反复重启，十有八九是「数据目录属主」问题，直接看第十章排障 Q1。

4.5 初始化注册（首个账号）

浏览器打开 BASE_URL（本文 http://192.168.146.128:13910），自动跳转 /register；
填写姓名/邮箱/密码。实测确认密码策略：至少 12 位，且通过内置强度检测——q1w2e3r4（8 位）会被拒绝，q1w2e3r4-plausible（16 位带符号）可注册成功；
提交后默认还需添加团队（全新个人实例默认创建 My personal sites），随后进入站点添加页。

📌 注册策略：CE 默认 DISABLE_REGISTRATION=invite_only。实测三态行为一致——

配置实测 GET /register 行为
不设置（默认） 302 → /login（仅受邀注册）
DISABLE_REGISTRATION=false 200，开放自助注册
DISABLE_REGISTRATION=true 302 → /login（完全关闭）

默认值下首个账号通过「首次启动放行」创建；之后新账号需管理员邀请。开放自助注册请显式设 DISABLE_REGISTRATION=false（实测见《Plausible 配置参数详解》）。

配置	实测 `GET /register` 行为
不设置（默认）	302 → `/login`（仅受邀注册）
`DISABLE_REGISTRATION=false`	200，开放自助注册
`DISABLE_REGISTRATION=true`	302 → `/login`（完全关闭）

4.6 重启后登录态验证（可选，验证 SECRET_KEY_BASE 的作用）

# 保持登录会话 cookie 不变，变更 SECRET_KEY_BASE 并重建服务后再次访问
curl -s -b cookies.txt -o /dev/null -w '%{http_code} -> %{redirect_url}\n' \
  http://127.0.0.1:13910/sites

实测回显（变更后）：

401 -> http://127.0.0.1:13910/login

结论：变更 SECRET_KEY_BASE 会使全部既有登录态立即失效（旧会话签名无法通过校验），用户需重新登录。

4.7 埋点接入与数据验证

① 添加站点：登录后进入「添加网站」，域名填目标站（本文 mysite.dev，本地测试无需真实解析），时区按需选择（本文 Asia/Shanghai）。

② 获取并安装脚本：站点创建后跳转安装页，实测页面给出的脚本片段为：

<script defer src="http://192.168.146.128:13910/js/pa-IhP1_HJykpkMhQKcTIukr.js" data-domain="mysite.dev"></script>
<script>window.plausible = window.plausible || function() { (window.plausible.q = window.plausible.q || []).push(arguments) }</script>

放入目标网站 <head>...</head>；pa-<随机串>.js 按站点生成；
无 Cookie、无跨站追踪，无需同意横幅。

③ 模拟页面浏览验证（不装脚本也能验证链路，Events API 等价于脚本上报）：

curl -s -w '\nHTTP %{http_code}\n' -X POST http://192.168.146.128:13910/api/event \
  -H 'Content-Type: application/json' \
  -H 'User-Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36' \
  -d '{"name":"pageview","domain":"mysite.dev","url":"http://mysite.dev/"}'

实测回显（202 Accepted，body 为 ok）：

ok
HTTP 202

📌 事件先写入应用内存缓冲，默认每 5 秒批量刷入 ClickHouse（CLICKHOUSE_FLUSH_INTERVAL_MS=5000），因此发送后需等几秒仪表盘才出现数据。

④ 仪表盘确认：打开 http://192.168.146.128:13910/mysite.dev，顶部实时访客出现计数；实测发送 3 条不同页面/UA 的浏览事件（/、/pricing、/blog/hello-world）后，实时访客显示 3，「热门页面」出现这三个路径，浏览器维度出现 Chrome/Safari。

⑤ 直查事件库确认落库（可选）：

docker exec plausible-v3.2.1-clickhouse clickhouse-client --query \
  "SELECT name, count() AS c FROM plausible_events_db.events_v2 GROUP BY name ORDER BY c DESC"

实测回显（3 条 pageview 后）：

pageview	3

4.8 验证部署完成

curl http://<服务器>:13910/api/health 返回四项 ok（见 4.4）；
仪表盘能打开且有实时数据（见 4.7）；
docker compose ps 三服务均为 Up，实测：

NAME                          IMAGE                                        COMMAND                   SERVICE               CREATED          STATUS                    PORTS
plausible-v3.2.1-app          ghcr.io/plausible/community-edition:v3.2.1   "/entrypoint.sh sh -…"   plausible             51 seconds ago   Up 45 seconds             0.0.0.0:13910->8000/tcp, [::]:13910->8000/tcp
plausible-v3.2.1-clickhouse   clickhouse/clickhouse-server:24.12-alpine    "/entrypoint.sh"          plausible_events_db   51 seconds ago   Up 50 seconds (healthy)   8123/tcp, 9000/tcp, 9009/tcp
plausible-v3.2.1-postgres     postgres:16-alpine                           "docker-entrypoint.s…"   plausible_db          51 seconds ago   Up 50 seconds (healthy)   5432/tcp

五、数据持久化说明

挂载点（宿主）	容器内	内容
`/opt/data/plausible/postgres`	`/var/lib/postgresql/data`	用户/站点/API Key 等元数据
`/opt/data/plausible/clickhouse/data`	`/var/lib/clickhouse`	事件与会话明细（`events_v2`/`sessions_v2`）
`/opt/data/plausible/clickhouse/logs`	`/var/log/clickhouse-server`	ClickHouse 日志
`/opt/data/plausible/app`	`/var/lib/plausible`	应用下载缓存（IP 库/tzdata 副本）等

实测验证：docker compose down → up -d 完整循环后，站点、账号、事件数据全部保留；循环后发送 1 条新 pageview，实时接口返回 1，历史事件仍在库中（实测 events_v2 事件行数在循环前后不变）。

⚠️ 属主注意：应用镜像以 uid 999 运行，其内嵌 tzdata 组件需要向 /var/lib/plausible/tzdata_data 写文件。若宿主目录属主是 root（uid 0），首次启动会直接崩溃，必须先执行 chown -R 999:999 /opt/data/plausible/app（详见第十章 Q1）。

六、环境变量表

变量	默认值	说明
`BASE_URL`	无（必填）	外部访问地址，影响埋点脚本与邮件链接
`SECRET_KEY_BASE`	无（必填）	会话签名/加密密钥，`openssl rand -base64 48` 生成
`TOTP_VAULT_KEY`	可选	双因素恢复码加密 key，需 32 字节 Base64；未启用 2FA 时可不设
`DISABLE_REGISTRATION`	`invite_only`	`false` 开放注册；`true` 完全关闭
`ENABLE_EMAIL_VERIFICATION`	`false`	开启后注册需邮箱验证码激活
`HTTP_PORT` / `HTTPS_PORT`	`80` / `443`	生成链接用的对外端口（不影响监听端口）
`DATABASE_URL`	`postgres://postgres:postgres@plausible_db:5432/plausible_db`	元数据库连接
`CLICKHOUSE_DATABASE_URL`	`http://plausible_events_db:8123/plausible_events_db`	事件库 HTTP 连接
`CLICKHOUSE_FLUSH_INTERVAL_MS`	`5000`	事件缓冲刷盘间隔（毫秒）
`CLICKHOUSE_INGEST_POOL_SIZE`	`5`	采集写入连接池大小
`MAILER_EMAIL`	按 `BASE_URL` 主机拼接（如 `plausible@<host>`）	发件人地址；用 IP 做 BASE_URL 时会拼出非法地址
`SMTP_HOST_ADDR`	`localhost`	SMTP 服务器
`SMTP_HOST_PORT`	`25`	SMTP 端口
`SMTP_HOST_SSL_ENABLED`	`false`	是否 STARTTLS/SSL
`SMTP_USER_NAME` / `SMTP_USER_PWD`	空	SMTP 认证
`IP_GEOLOCATION_DB`	`Purchased MaxMindDB`	地理库类型（可改 `ep offline` 离线库）
`MAXMIND_LICENSE_KEY` / `MAXMIND_EDITION`	空	MaxMind 商业库凭据
`GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET`	空	Search Console 集成

完整逐参数实测（改值 → 重启 → 行为对比）见《Plausible 配置参数详解》。

七、配置文件挂载说明

文件	挂载点	作用
`clickhouse/logs.xml`	`/etc/clickhouse-server/config.d/logs.xml`	日志输出策略
`clickhouse/ipv4-only.xml`	`/etc/clickhouse-server/config.d/ipv4-only.xml`	仅监听 IPv4
`clickhouse/low-resources.xml`	`/etc/clickhouse-server/config.d/low-resources.xml`	低资源配置（后台池收缩等）
`clickhouse/default-profile-low-resources-overrides.xml`	`/etc/clickhouse-server/users.d/default-profile-low-resources-overrides.xml`	默认 profile 约束（内存/并发上限），并预建 `plausible` 用户

八、等价 `docker run` 部署

不用 Compose 时的等价命令（同一自定义网络，参数与编排一致；逐条实测可用）：

docker network create plausible_net

docker run -d --name plausible-v3.2.1-postgres --network plausible_net \
  -e POSTGRES_PASSWORD=postgres \
  -v /opt/data/plausible/postgres:/var/lib/postgresql/data \
  --restart always postgres:16-alpine

docker run -d --name plausible-v3.2.1-clickhouse --network plausible_net \
  --memory 512m --ulimit nofile=262144:262144 \
  -v /opt/data/plausible/clickhouse/data:/var/lib/clickhouse \
  -v /opt/data/plausible/clickhouse/logs:/var/log/clickhouse-server \
  -v ~/plausible-lab/clickhouse/logs.xml:/etc/clickhouse-server/config.d/logs.xml:ro \
  -v ~/plausible-lab/clickhouse/ipv4-only.xml:/etc/clickhouse-server/config.d/ipv4-only.xml:ro \
  -v ~/plausible-lab/clickhouse/low-resources.xml:/etc/clickhouse-server/config.d/low-resources.xml:ro \
  -v ~/plausible-lab/clickhouse/default-profile-low-resources-overrides.xml:/etc/clickhouse-server/users.d/default-profile-low-resources-overrides.xml:ro \
  --restart always clickhouse/clickhouse-server:24.12-alpine

docker run -d --name plausible-v3.2.1-app --network plausible_net \
  -p 13910:8000 \
  -e BASE_URL=http://192.168.146.128:13910 \
  -e SECRET_KEY_BASE=<同上生成的密钥> \
  -e DATABASE_URL=postgres://postgres:postgres@plausible-v3.2.1-postgres:5432/plausible_db \
  -e CLICKHOUSE_DATABASE_URL=http://plausible-v3.2.1-clickhouse:8123/plausible_events_db \
  -v /opt/data/plausible/app:/var/lib/plausible \
  --restart always ghcr.io/plausible/community-edition:v3.2.1 \
  sh -c "/entrypoint.sh db createdb && /entrypoint.sh db migrate && /entrypoint.sh run"

📌 docker run 方式需自行保证三服务启动顺序与数据库就绪等待；Compose 的 depends_on + healthcheck 已封装该逻辑，推荐优先使用 Compose。

九、常用运维命令

docker compose ps                 # 三服务状态（healthy）
docker compose logs -f plausible  # 跟踪应用日志
docker compose restart plausible  # 仅重启应用进程（不改环境变量时使用）
docker compose down               # 停止并移除三服务（数据在宿主目录，不丢失）
docker compose up -d              # 启动/应用 .env 改动（触发容器重建）

# 升级版本：修改 compose.yml 中 tag（如 v3.2.1 → 更高版本）后
docker compose pull && docker compose up -d

# 备份（停机一致性备份最稳妥）
docker compose down
tar czf plausible-backup-$(date +%F).tar.gz /opt/data/plausible
docker compose up -d

# 事件库行数速查
docker exec plausible-v3.2.1-clickhouse clickhouse-client --query \
  "SELECT count() FROM plausible_events_db.events_v2"

实测 down → up 完整循环回显（照抄）：

### docker compose down
 Container plausible-v3.2.1-app Stopping
 Container plausible-v3.2.1-app Stopped
 Container plausible-v3.2.1-app Removing
 Container plausible-v3.2.1-app Removed
 Container plausible-v3.2.1-clickhouse Stopping
 Container plausible-v3.2.1-postgres Stopping
 Container plausible-v3.2.1-postgres Stopped
 Container plausible-v3.2.1-postgres Removing
 Container plausible-v3.2.1-postgres Removed
 Container plausible-v3.2.1-clickhouse Stopped
 Container plausible-v3.2.1-clickhouse Removing
 Container plausible-v3.2.1-clickhouse Removed
 Network plausible_default Removing
 Network plausible_default Removed
### docker compose up -d
 Network plausible_default Creating
 Network plausible_default Created
 Container plausible-v3.2.1-clickhouse Creating
 Container plausible-v3.2.1-postgres Creating
 Container plausible-v3.2.1-postgres Created
 Container plausible-v3.2.1-clickhouse Created
 Container plausible-v3.2.1-app Creating
 Container plausible-v3.2.1-app Created
 Container plausible-v3.2.1-postgres Starting
 Container plausible-v3.2.1-clickhouse Starting
 Container plausible-v3.2.1-postgres Started
 Container plausible-v3.2.1-clickhouse Started
 Container plausible-v3.2.1-clickhouse Waiting
 Container plausible-v3.2.1-postgres Waiting
 Container plausible-v3.2.1-postgres Healthy
 Container plausible-v3.2.1-clickhouse Healthy
 Container plausible-v3.2.1-app Starting
 Container plausible-v3.2.1-app Started
### 等待 45 秒后健康检查
{"sessions":"ok","postgres":"ok","clickhouse":"ok","sites_cache":"ok"}

十、常见问题（FAQ）

Q1：应用启动即崩溃（Kernel pid terminated），日志报 tzdata 相关 File.Error，不断重启？

实测崩溃日志（/var/lib/plausible 挂载目录属主为 root、tzdata 目录缺失/不可写时，docker logs plausible-v3.2.1-app）：

23:22:48.790 [notice] Application tzdata exited: exited in: Tzdata.App.start(:normal, [])
    ** (EXIT) an exception was raised:
        ** (MatchError) no match of right hand side value:
    {:error,
     {:shutdown,
      {:failed_to_start_child, Tzdata.EtsHolder,
       {%File.Error{
          reason: :enoent,
          path: "/var/lib/plausible/tzdata_data/release_ets",
          action: "list directory"
        }, [...]}}}}
...
Kernel pid terminated (application_controller) ("{application_start_failure,tzdata,{bad_return,...}}")
Crash dump is being written to: erl_crash.dump...

根因：应用以 uid 999 运行，而宿主挂载目录 /opt/data/plausible/app 属主为 root（uid 0），tzdata 组件无法在该目录创建/读取时区文件。修复：

chown -R 999:999 /opt/data/plausible/app
docker compose restart plausible

实测修复后：健康检查恢复 4 项 ok，应用稳定运行。

Q2：改了 .env 里的变量不生效？

docker compose restart 不会重新读取 .env（变量在容器创建时注入）。必须：

docker compose up -d

实测：改 BASE_URL/SECRET_KEY_BASE 后 up -d（触发重建）才生效；仅 restart 无效。

Q3：改了 SECRET_KEY_BASE 后所有人掉线？

是预期行为。会话 cookie 用该 key 签名/加密，key 变更后旧会话校验失败，实测访问 /sites 返回 401 -> /login（见 4.6）。重新登录即可；该 key 一经使用请勿随意变更。

Q4：打开首页跳到 /login，没有注册入口，新用户怎么进？

CE 默认 DISABLE_REGISTRATION=invite_only（仅邀请）。自助注册需在 .env 设 DISABLE_REGISTRATION=false 后 docker compose up -d；实测三态行为见 4.5 表格。

Q5：发不出邮件（注册验证/密码重置）？

默认邮件适配器 Bamboo.Mua 直投 SMTP_HOST_ADDR（默认 localhost:25），且未设 MAILER_EMAIL 时按 BASE_URL 主机名拼发件人——用 IP 形式 BASE_URL 会拼出非法地址（实测报 Expected "at" at position...）。生产务必配置外部 SMTP（SMTP_* 系列 + 显式 MAILER_EMAIL）。邮件验证流程还需 ENABLE_EMAIL_VERIFICATION=true（实测见《Plausible 配置参数详解》）。

Q6：ClickHouse 内存被限 512M 会不会影响使用？

本实测约束场景：mem_limit: 512m 下 ClickHouse 常驻内存 217.3MiB（docker stats 实测），中小流量足够；官方通过 low-resources.xml 已限制后台任务内存。大流量站点建议解除 mem_limit 或调大限制。

Q7：埋点脚本被广告拦截插件拦截？

官方脚本以 /js/pa-<随机串>.js 形式按站点提供，通用规则较少命中；也可自建反代路径。实测脚本直连可用（GET /js/pa-IhP1_HJykpkMhQKcTIukr.js 返回 200）。

Q8：发了几条 pageview，仪表盘实时没变化？

两处延迟：① 事件先入内存缓冲，默认 5 秒批量落库（CLICKHOUSE_FLUSH_INTERVAL_MS）；② 仪表盘查询走聚合缓存，新窗口才刷新。实测发送后 5~30 秒内实时访客与热门页面均出现数据。

十一、参考链接

官方自托管文档：https://plausible.io/docs/self-hosting（2026-10-18 抓取）
官方编排仓库：https://github.com/plausible/community-edition（compose.yml 与 clickhouse 配置均取自 master 分支，2026-10-18 下载）
配置参数 Wiki：https://github.com/plausible/community-edition/wiki/configuration
镜像发布页：https://github.com/plausible/analytics/pkgs/container/community-edition
本系列：《Plausible 介绍与选型指南》《Plausible 配置参数详解》《Plausible API 使用详解》

Plausible Docker Compose 部署指南

Plausible Docker Compose 部署指南

一、环境信息

二、镜像选型说明

三、前置条件

四、部署步骤

4.1 创建目录与获取官方编排文件

4.2 编写 .env（BASE_URL 与 SECRET_KEY_BASE）

4.3 编写 compose.yml（三服务逐段说明）

4.4 启动

4.5 初始化注册（首个账号）

4.6 重启后登录态验证（可选，验证 SECRET_KEY_BASE 的作用）

4.7 埋点接入与数据验证

4.8 验证部署完成

五、数据持久化说明

六、环境变量表

七、配置文件挂载说明

八、等价 docker run 部署

九、常用运维命令

十、常见问题（FAQ）

十一、参考链接

4.2 编写 `.env`（BASE_URL 与 SECRET_KEY_BASE）

4.3 编写 `compose.yml`（三服务逐段说明）

八、等价 `docker run` 部署