【实用的开源工具】Plausible Analytics：自托管的轻量网站统计

「实用的开源工具」系列：我只收集值得用的开源项目，写清楚它能做什么、怎么部署、有哪些坑，并在文末标明出处。内容整理自官方文档，核对日期 2026-10-31，具体版本以官方为准。文中的命令来自官方 README、Wiki 和仓库里的 Compose 文件，我没有在本文里逐条实际运行过，上线前请先在测试环境走一遍。

项目信息卡

安全提醒： v3.2.1 的发布说明写明，它修复了一个编号为 CVE-2026-8467 的漏洞：旧版本暴露的 /storybook 端点在一定条件下可被远程执行代码。官方列出的受影响版本是 v3.0.0 到 v3.2.0（含对应的 v3、v3.2 等浮动标签），建议升级到 v3.2.1，临时办法是在反向代理上屏蔽该路径。

云版和 CE 的区别（来自官方 README）

• 基础设施：云版由官方运维；CE 要自己负责安装、升级、容量、备份和安全。
• 发布节奏：README 说 CE 是“长期版本”，每年发布两次，所以最新功能不会马上出现在 CE 里。
• 功能：README 写明营销漏斗（funnels）、电商收入目标、SSO、站点 API 这几项高级功能在 CE 里不提供。
• 机器人过滤：CE 只有基于 User-Agent 和垃圾来源域名的基础过滤，云版的更全面。
• 支持：CE 只有社区支持，没有官方付费支持。
• 数据：自托管可以直接从 ClickHouse 取原始数据；Looker Studio（Data Studio）连接器 CE 不提供。

它能做什么

• 一个页面看完：流量、来源、页面、国家、设备等放在同一个仪表盘里。
• 单页应用：README 称支持 SPA，包括 pushState 和哈希路由。
• 目标与自定义事件：可以设置目标，追踪出站链接点击、文件下载、表单提交等（在站点设置里开关）。
• 事件 API：不想用 JavaScript 时，可以从服务端发事件。
• 邮件报告：每周或每月报告需要配置邮件发送（见下文踩坑）。
• IP 地理位置：镜像里自带 db-ip 的国家库，国家数据自动收集；想要城市级可以另配 MaxMind。

不太适合的场景：服务器内存很小；或者你需要漏斗、电商收入、SSO 这类 CE 不提供的功能。

和同类项目怎么选

下面只列我在各项目官方文档里核对过的事实，不涉及性能和“谁更好”的比较：

怎么选，看你已有什么：已经有 PostgreSQL 想少维护组件，可以看 Umami（见 Umami 那篇）；习惯 PHP 加 MySQL、需要功能更全，可以看 Matomo（见 Matomo 那篇）；不介意多一个 ClickHouse、内存够 2 GB，Plausible 的部署流程很简洁。至于是否需要弹同意提示，取决于你所在地区的法规和你用的其他服务，请自己判断，官方说“无 cookie”也不等于不用考虑合规。

部署

准备

• 一台装好 Docker 和 Docker Compose 的服务器，内存按官方建议至少 2 GB。
• 一个域名（下文用 plausible.example.com），DNS 指向服务器。

第 1 步：取得官方部署仓库

官方推荐直接克隆指定版本的分支（版本号请以官方最新为准，克隆前可以去仓库看分支是否存在）：

git clone -b v3.2.1 --single-branch https://github.com/plausible/community-edition plausible-ce
cd plausible-ce

目录里有 clickhouse/、compose.yml、LICENSE、README.md。compose.yml 里的镜像已经固定为 ghcr.io/plausible/community-edition:v3.2.1。

第 2 步：写 .env

touch .env
echo "BASE_URL=https://plausible.example.com" >> .env
echo "SECRET_KEY_BASE=$(openssl rand -base64 48)" >> .env

• BASE_URL：必填，没有默认值。用于生成链接和 Cross-Site WebSocket Hijacking（CSWSH）检查，必须填你实际对外访问的地址。
• SECRET_KEY_BASE：必填，没有默认值，用于仪表盘会话，也用来派生 TOTP Vault Key 等其他密钥。官方要求至少 64 字节，并给了 openssl rand -base64 48 这个生成方法。每个实例都要用自己生成的值。

本机体验的话，官方说可以把 BASE_URL 设成 http://localhost:8000。

第 3 步：让 Plausible 对外可访问

compose.yml 本身不发布任何端口，需要用官方推荐的 compose.override.yml 来加。官方有两种做法。

做法 A：用自带的 Let's Encrypt（官方 README 的快速开始）

echo "HTTP_PORT=80" >> .env
echo "HTTPS_PORT=443" >> .env

cat > compose.override.yml << EOF
services:
    plausible:
        ports:
            - 80:80
            - 443:443
EOF

官方说明：HTTP_PORT=80 加 HTTPS_PORT=443 会让 Plausible 自动申请并续期 Let's Encrypt 证书，前提是域名 DNS 已经指向服务器。

做法 B：放在自己的反向代理后面（本文推荐，如果你的服务器上已有 Nginx 或 Caddy）

echo "HTTP_PORT=8000" >> .env

cat > compose.override.yml << EOF
services:
  plausible:
    ports:
      - 127.0.0.1:8000:\${HTTP_PORT}
EOF

这一段改自官方 Wiki 的 Reverse Proxy 页面，那里就是绑定在 127.0.0.1:8000，只让本机的反向代理访问。注意这里 heredoc 里的 \$ 是我为了让 ${HTTP_PORT} 原样写进文件加的转义；你也可以直接用编辑器创建这个文件，内容写 - 127.0.0.1:8000:${HTTP_PORT}。Docker Compose 会自动合并 compose.yml 和 compose.override.yml，后者优先。

第 4 步：启动

docker compose up -d

plausible 容器启动时会依次执行 db createdb、db migrate、run（见 compose.yml 的 command），第一次启动会花一点时间。然后访问 BASE_URL，按官方说明创建第一个用户。

反向代理

官方 Wiki 说明：从 2.1.2 版本起，Plausible CE 自己就能处理 HTTPS 和自动证书，反向代理不再是必需的。Wiki 里的 Caddy、Nginx、Apache 配置是社区贡献的，维护者没有测试过。

Caddy（Wiki 示例）：

plausible.example.com {
    reverse_proxy localhost:8000
}

Nginx（Wiki 示例，原样照抄）：

server {
    server_name plausible.example.com;

    listen 80;
    listen [::]:80;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    location /live/websocket {
        proxy_pass http://127.0.0.1:8000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
    }
}

要点：/live/websocket 这一段不能少，需要 Upgrade 和 Connection 头。Wiki 的 Nginx 示例只监听 80 端口，HTTPS 证书这一部分需要你自己加（比如用证书工具签发后补上 listen 443 ssl 和证书路径，这是通用做法，Wiki 没有写）。server_name 要和 BASE_URL 的域名一致。

第一次使用 / 把统计代码装到网站

1. 打开 BASE_URL，创建第一个用户（官方快速开始的第 5 步）。
2. 添加你的网站。官方文档说，添加站点的过程中会显示跟踪代码片段；以后也可以在站点列表里点站点右边的菜单进入 Settings，在 General 里的 Tracking 区域，点 Site installation 旁边的 Review 查看。
3. 把这段片段放进网站页面的 <head> … </head> 里。我这里不手写片段，因为官方文档没有给出固定的文本，请直接复制你实例页面上显示的那一份。
4. 在同一个 Tracking 区域，可以打开出站链接、文件下载、表单提交这几项“默认跟踪”，官方说这些改动不用重新改页面上的片段。
5. 官方提供测试工具来检查片段是否装对，没数据时先用它，再看官方的排错指南。常见原因是片段没加、缓存没清、广告拦截器或性能优化插件干扰了脚本。
6. 用 WordPress 的话，官方建议使用官方插件而不是手动贴代码；想让脚本以你自己的域名的形式加载，官方有代理说明（见出处里的文档）。

更新与卸载

更新

官方 Wiki 的要点：

• 每个 release 都写有从上一版本升级的具体说明，升级前先读。
• 镜像标签支持大版本、小版本、补丁版本三种固定方式（例如 v3、v3.2、v3.2.1），官方推荐固定到补丁版本。
• 官方说安全补丁和 bug 修复不会向旧版本回移植，所以需要自己跟着升级。

一般步骤（Wiki 的写法，版本号换成你要升到的那一个，先确认仓库里有这个分支）：

cd plausible-ce
git pull origin v3.2.1    # 换成目标版本
docker compose up -d

升级前先备份，是通用建议：官方文档没有给出 CE 的备份命令，我也没有核对，请自己给 PostgreSQL 和 ClickHouse 的数据卷做备份（卷名见 compose.yml：db-data、event-data、event-logs、plausible-data）。

PostgreSQL 的大版本升级不能只改镜像标签，官方 Wiki 有单独的 “Upgrade PostgreSQL” 页面，基于 pg_dump 和 psql 导出再导入。

卸载

官方文档没有专门的卸载章节。下面是通用做法：

cd plausible-ce
docker compose down        # 停止并删除容器，数据卷保留
# docker compose down -v   # 连同数据卷一起删除，统计数据会永久丢失，确认不要了再用

别忘了把网站里的统计代码去掉。

踩坑清单

1. 安全修复版本：v3.0.0 到 v3.2.0 有 /storybook 远程代码执行漏洞。 来自 v3.2.1 的发布说明。如果你用的是旧版本，升级到 v3.2.1 或更新的版本；暂时升不了，就在反向代理上屏蔽 /storybook。
2. BASE_URL 和 SECRET_KEY_BASE 都没有默认值。 少了就起不来或者行为不对。BASE_URL 要写你真实访问的完整地址（含 https://），SECRET_KEY_BASE 至少 64 字节。
3. SECRET_KEY_BASE 不要随便换。 它用于会话，也用来生成 TOTP Vault Key。文档写明 TOTP_VAULT_KEY 默认从 SECRET_KEY_BASE 派生，所以换掉前者而没有单独设置 TOTP_VAULT_KEY，已启用双因素的用户可能会受影响（这是我根据文档的推断，没有实测）。要用双因素，可以单独生成并固定 TOTP_VAULT_KEY。
4. 默认的注册策略是 invite_only。 文档里 DISABLE_REGISTRATION 的取值是 true（完全限制）、false（不限制）、invite_only（仅受邀用户可注册），默认 invite_only。个人使用建议建好自己的账号后改成 true，再执行 docker compose up -d。先建号后收紧是我的建议，文档没有说明首个用户在 true 下能否注册。
5. 内存别太小。 官方建议至少 2 GB。Compose 里已经挂了 ClickHouse 的低资源配置文件（low-resources.xml 等），但这不等于 1 GB 机器能稳定运行。
6. compose.yml 不发布端口。 不加 compose.override.yml，外面访问不到。用反向代理时只绑定 127.0.0.1；Docker 发布的端口会绕过 ufw 之类的防火墙（通用经验），所以别随手写成 8000:8000。
7. 自动证书和反向代理二选一。 自带 Let's Encrypt 需要 HTTP_PORT=80、HTTPS_PORT=443 并且 80/443 能被外网访问；已经用 Nginx 或 Caddy 终结 HTTPS 的话，用做法 B，不要把两者叠在一起。
8. Nginx 缺少 WebSocket 头，仪表盘实时部分会出问题。 /live/websocket 要带 Upgrade 和 Connection。Wiki 提醒 Nginx 和 Apache 示例是社区贡献、未经维护者测试。
9. 邮件默认不会替你配好。 SMTP_HOST_ADDR 不设时，SMTP 客户端会尝试直接发信，这要求服务器能出站连接 25 端口，且发件域名配置了 SPF、DKIM，否则容易进垃圾箱。周报、月报、密码重置都靠邮件。要稳定发信，请配置 SMTP 中继。
10. ENABLE_EMAIL_VERIFICATION 要谨慎开启。 默认是 false。邮件没配好就开启，新用户会收不到验证链接。文档给了一条批量标记已验证的 SQL 命令：docker compose exec plausible_db psql -U postgres -h localhost -d plausible_db -c "UPDATE users SET email_verified = true;"，它会把所有用户标为已验证，用前想清楚。
11. CE 没有的功能别当成有。 漏斗、电商收入目标、SSO、站点 API 在 CE 里不提供；官方文档站同时描述云版和 CE，看到某个功能不代表你的 CE 里有。
12. Wiki 有些链接停在旧版本。 比如指向 v2.1.3 的快速开始链接。以你克隆下来的那个版本的 README.md 为准。
13. 数据库默认口令是公开的。 compose.yml 里的 PostgreSQL 密码是 postgres，数据库没有对外发布端口。不要给 plausible_db 和 plausible_events_db 加 ports；确实需要改口令的话，要同时改容器环境变量和 DATABASE_URL，且口令只在数据目录第一次初始化时生效（通用经验，没有专门核对）。
14. 广告拦截器会挡住统计脚本。 官方排错文档提到这是漏数据的常见原因，可以接受少量损失，也可以按官方的代理方案让脚本从你自己的域名提供。

出处

• Plausible Analytics 主仓库 README（CE 与云版区别、技术栈、许可证）
• 主仓库 LICENSE（AGPL-3.0）
• Plausible CE 部署仓库 README（要求、快速开始、Compose 文件）
• CE 仓库 compose.yml
• CE Wiki：Configuration（BASE_URL、SECRET_KEY_BASE、DISABLE_REGISTRATION 等）
• CE Wiki：Reverse Proxy
• CE Wiki：Compose Override
• CE Wiki：Upgrade
• CE Wiki：Upgrade PostgreSQL
• Plausible v3.2.1 发布说明（安全修复）
• 官方文档：添加跟踪脚本
• 官方文档：可选的测量项
• 官方文档：排错