Plausible Analytics 贡献指南：本地开发环境搭建、种子数据与提交 Pull Request 全流程

• 后端
• 数据分析
• 数据可视化

Plausible Analytics 是一个开源、隐私优先的轻量级网站分析工具（无需 Cookie、可自托管），技术栈以 Elixir/Phoenix 为后端、ClickHouse 存储事件数据、Postgres 存储业务数据、Node.js 构建前端与跟踪脚本。本文以仓库根目录的 CONTRIBUTING.md 为主线，完整还原从零搭建开发环境、启动 Phoenix 服务、填充演示数据到通过 pre-commit 检查并提交 Pull Request 的全过程，并结合 Makefile、.tool-versions、mix.exs、priv/repo/seeds.exs 等源码文件进行深度解读。读完本文，你将能够独立在本机跑起 Plausible 开发环境，生成带统计数据的演示站点，并理解整个贡献流程背后的实现细节。

一、开发环境概览：依赖三件套

在开始搭建之前，先明确 Plausible 开发环境需要哪些组件，以及为什么需要它们：

仓库根目录的 .tool-versions 明确记录了当前推荐的版本组合，可与 asdf 之类的版本管理工具配合使用：

erlang 28.5.0.5 elixir 1.20.4-otp-28 nodejs 24.17.0

从 mix.exs 可以看到，项目声明了elixir: "~> 1.18"，即 Elixir 1.18 及以上版本均可；同时mix.exs中列出的核心依赖包括 Phoenix（~> 1.8.2）、Phoenix LiveView（~> 1.1.17）、Ecto（~> 3.13.5）、ecto_ch（ClickHouse 适配器）、postgrex、ua_inspector（UA 解析）、ref_inspector（来源识别）等，这些会在mix deps.get时统一拉取。

二、启动数据库容器：make postgres 与 make clickhouse

Plausible 采用双数据库架构：Postgres 存放用户、站点、订阅等业务数据，ClickHouse 存放海量事件/会话统计数据。CONTRIBUTING.md 推荐直接用 Docker 运行两者，最省事的方式就是使用仓库根目录 Makefile 中预置的 target。

make postgres # 启动 Postgres 容器 make clickhouse # 启动 ClickHouse 容器

查看 Makefile 可以看到这两个命令的实际行为：

• Postgres：docker run --detach -e POSTGRES_PASSWORD="postgres" -p 5432:5432 --name plausible_db --volume=plausible_db:/var/lib/postgresql/docker postgres:latest，容器名为plausible_db，密码为postgres，数据卷名为plausible_db，监听宿主机 5432 端口。
• ClickHouse：docker run --detach -p 8123:8123 -p 9000:9000 --ulimit nofile=262144:262144 --name plausible_clickhouse --env CLICKHOUSE_SKIP_USER_SETUP=1 --network host --volume=$PWD/.clickhouse_db_vol:/var/lib/clickhouse ...，容器名为plausible_clickhouse，HTTP 端口 8123、原生协议端口 9000，使用--network host与本地数据卷。

Makefile 还提供了两个常用的运维 target：

make clickhouse-client # 进入 ClickHouse 客户端：docker exec -it plausible_clickhouse clickhouse-client -d plausible_events_db make postgres-client # 进入 Postgres 客户端：docker exec -it plausible_db psql -U postgres -d plausible_dev

另外，若需要与生产环境完全一致的数据库版本，可运行make postgres-prod（Postgres 18）与make clickhouse-prod（ClickHouse 25.11.5.8-alpine），这在你排查生产复现问题时非常有用。

三、一键安装：make install 或逐步执行

数据库容器就绪后，接下来安装 Elixir 依赖、创建数据库、构建前端资源。CONTRIBUTING.md 提供了两种方式：

方式一：一键完成

make install

查看 Makefile，make install实际按顺序执行了以下命令（等价于方式二的组合）：

mix deps.get mix ecto.create mix ecto.migrate mix download_country_database npm install --prefix assets npm install --prefix tracker npm run deploy --prefix tracker

方式二：逐步执行（便于理解每一步的作用）

# 1. 下载 Elixir 依赖 mix deps.get # 2. 在 Postgres 与 ClickHouse 中创建所需数据库 mix ecto.create # 3. 构建数据库 schema mix ecto.migrate # 4. 填充种子数据（可选，详见下文 Seeds 章节） mix run priv/repo/seeds.exs # 5. 安装前端（dashboard）依赖 npm ci --prefix assets # 6. 安装 tracker（跟踪脚本）依赖 npm ci --prefix tracker # 7. 安装 Tailwind 与 Esbuild mix assets.setup # 8. 生成 tracker 文件到 priv/tracker/js npm run deploy --prefix tracker # 9. 下载地理定位数据库 mix download_country_database

其中几个关键步骤值得展开说明：

• mix ecto.create/mix ecto.migrate：从 config/config.exs 可以看到项目同时注册了两个 Ecto Repo：Plausible.Repo（Postgres）与Plausible.IngestRepo（ClickHouse），因此这条命令会同时作用于两个数据库。mix ecto.migrate会执行 priv/repo/migrations（Postgres 侧）下的全部迁移文件。
• mix assets.setup：等价于mix tailwind.install --if-missing与mix esbuild.install --if-missing（见 mix.exs 中定义的 alias）。
• mix download_country_database：从源码 lib/mix/tasks/download_country_database.ex 看，该任务会从 DB-IP 下载当月（若 404 则回退到上月）的dbip-country-lite-YYYY-MM.mmdb.gz并保存到priv/geodb/dbip-country.mmdb.gz，用于访问来源国家/地区的地理定位解析。
• npm ci --prefix tracker+npm run deploy --prefix tracker：tracker 是随站点嵌入的 JavaScript 统计脚本（源码位于 tracker/src），需要先安装依赖再编译输出到 priv/tracker/js。

小提示：若你想一次性完成「创建数据库 + 迁移 + 种子」的整套初始化，mix ecto.setupalias（见 mix.exs）会依次执行ecto.create、ecto.migrate和run priv/repo/seeds.exs。

四、启动服务器：make server

安装完成后，启动 Phoenix 服务器：

make server # 等价于 mix phx.server

系统随即运行在http://localhost:8000。

在开发模式下，config/dev.exs 配置了一组 watchers，会在启动时自动执行：

• esbuild：编译assets/js/app.js、assets/js/dashboard.tsx等前端入口，支持--sourcemap=inline --watch热更新；
• tailwind：监听 assets/css/app.css 输出priv/static/css/app.css；
• npm --prefix assets run typecheck：对 TypeScript 前端代码做类型检查；
• npm run deploy（tracker 目录）：持续编译跟踪脚本。

同时开发环境开启了code_reloader、debug_errors与 LiveView 调试选项，方便调试 lib/plausible_web/controllers 与 lib/plausible_web/live 下的代码。

五、Seeds：一键获得带统计数据的演示账号

CONTRIBUTING.md 推荐通过种子脚本自动创建账号和站点，这是快速体验完整功能（Dashboard、目标、漏斗、导入数据等）的最佳路径。

mix run priv/repo/seeds.exs make server # 打开 http://localhost:8000/login

登录凭证为：

• 邮箱：user@plausible.test
• 密码：plausible

登录后你会看到一个dummy.site站点，它自带生成好的统计数据。

5.1 种子脚本内部做了什么

阅读 priv/repo/seeds.exs 可以发现它远比"创建一个账号"复杂，值得了解以便更好地调试：

• 主用户与站点：创建user@plausible.test用户，以及两个站点：dummy.site（原生统计覆盖过去约 720 天，另有约 180 天的导入统计区间）与another.site（约 320 天原生统计）。
• 多种角色示例：通过add_guest添加了Arnold Wallaby（viewer 角色）与Lois Lane（editor 角色）；还创建了Mary Jane、Harvey Dent（订阅了 Business 计划）、Bruce Wayne等示例用户，覆盖邀请、转让站点、团队成员等团队功能场景。
• 目标（Goals）与漏斗：为dummy.site创建了/、/register、/login等页面路径目标、Purchase收入目标、Outbound Link: Click事件目标，以及带自定义属性（logged_in）的目标；在企业版（EE）环境下还会创建多个漏斗（如"From homepage to login"）。
• 统计生成逻辑：脚本用Plausible.TestUtils.populate_stats()按天批量生成随机的 pageview/engagement 事件，包含随机浏览器、操作系统、来源、UTM 参数、地理位置等字段，最终写入 ClickHouse。
• 其他开发便利设施：为dummy.site插入 IP 规则与国家规则（PL、EE），绑定 Google 搜索控制台授权，并生成一个 Plugins API 开发用 Token（plausible-plugin-dev-seed-token，见脚本中Plausible.Plugins.API.Token.generate("seed-token")一段）。

5.2 手动注册 + 生成伪造事件

如果你不想用种子脚本，也可以完全手动创建：

1. 打开http://localhost:8000/register填写注册表单；
2. 后续表单中的域名使用dummy.site；
3. 跳过 JS 代码片段，直接点击开始收集数据；
4. 在终端运行mix send_pageview生成一条伪造的 pageview 事件。

mix send_pageview是一个位于 lib/mix/tasks/send_pageview.ex 的 Mix Task，它通过 HTTP 向/api/event发送事件（类似 tracker 的真实行为），默认参数如下：

例如生成一条带收入信息的自定义事件：

mix send_pageview --event Purchase --revenue_currency USD --revenue_amount 19.99

六、停止 Docker 容器与数据保留

开发结束后，可以用以下命令停止并移除容器：

make postgres-stop # docker stop plausible_db && docker rm plausible_db make clickhouse-stop # docker stop plausible_clickhouse && docker rm plausible_clickhouse

需要注意（这也是 CONTRIBUTING.md 特别提醒的）：数据卷会被保留。重新执行make postgres/make clickhouse后，之前的注册账号、站点与统计状态都会原样恢复，无需重新注册。正因容器被删除而卷仍存在，执行docker volume prune前务必谨慎——它可能连同数据库卷一起清掉，导致你不得不重新走一遍注册流程。

七、Pre-commit 钩子：提交前的自动检查

Plausible 使用 pre-commit 框架在提交前自动检查代码质量，覆盖 Elixir、JavaScript 与 CSS。安装方式：

pip install --user pre-commit # 安装框架（需要本机有 Python） pre-commit install # 在仓库中启用钩子

如果这些提示过于频繁、影响你的提交节奏，可以直接卸载：

pre-commit uninstall

仓库根目录的 .pre-commit-config.yaml 定义了实际生效的检查项：

• Elixir 格式检查：mix-format（来自elixir-pre-commit-hooks仓库），确保.ex/.exs文件符合mix format规范；
• 通用文件检查（来自pre-commit-hooks）：
  • check-case-conflict：防止大小写冲突的文件名；
  • check-symlinks/destroyed-symlinks：检查失效符号链接；
  • check-yaml：校验 YAML 语法；
  • end-of-file-fixer：确保文件以换行结尾（priv/tracker/js下生成的文件被排除）；
  • mixed-line-ending：统一行尾符；
  • trailing-whitespace：去除行尾空白。

八、寻找任务与提交 Pull Request 的建议

CONTRIBUTING.md 对贡献流程给出三点核心建议：

1. Bug 类任务：项目 issue 跟踪器中通常能找到"可认领"的 bug，这类任务一般直接认领即可，无需提前讨论。
2. 新功能必须先讨论：任何新功能都需要先与核心团队和社区沟通确认方向。建议在 Discussions 讨论区提出方案，再动手实现并提交 Pull Request。贡献者被明确要求：在开 PR 之前，先在讨论区用评论的形式提出解决方案。
3. 无关联 PR 的处理策略：没有对应 issue 或 discussion 的 Pull Request 仍可能被合并，但维护者会优先处理那些已经充分讨论过的变更。

对于想快速上手了解项目的贡献者，仓库本身还提供了非常丰富的探索入口：端到端测试位于 e2e/tests/dashboard（覆盖注解、行为、细分、过滤、主图、分段、验证等场景，基于 Playwright），单元/集成测试位于 test/plausible 与 test/plausible_web。阅读这些测试不仅能理解现有功能的行为约定，也是为新功能编写配套测试的最佳参照——Plausible 的 CI 体系（见 mix.exs 中定义的test、test.e2e等 alias）会统一执行它们。

九、常见问题速查

按照上述流程，你就能在本地完整跑起 Plausible 的开发环境：双数据库容器就绪 → 依赖与资源构建完成 → Phoenix 服务运行在 8000 端口 → 种子数据提供带统计的演示站点。在此基础上，无论是修复 bug 还是实现新功能，你都可以依照本文第八节提到的讨论与 PR 流程，安全、合规地参与这个开源项目。

• 后端
• 数据分析
• 数据可视化