Plausible Analytics 开发环境搭建指南

项目概述

Plausible Analytics 是一个轻量级的网站分析工具，专注于隐私保护和简洁易用。本文将为开发者详细介绍如何搭建 Plausible Analytics 的开发环境，帮助开发者快速上手项目开发。

环境准备

基础软件要求

在开始之前，请确保你的开发机器上已安装以下软件：

1. Docker：用于运行数据库服务
2. Elixir：项目的后端语言
3. Erlang：Elixir 的运行环境
4. Node.js：前端资源构建所需

推荐使用版本管理工具如 asdf 来管理这些软件的版本，项目中的 .tool-versions 文件已经包含了所需的版本信息。

开发环境搭建

数据库服务启动

Plausible Analytics 使用两种数据库：

1. Postgres：存储用户和站点元数据
2. Clickhouse：存储分析事件数据

使用以下命令启动数据库容器：

make postgres
make clickhouse

项目初始化

完整的初始化过程可以通过单个命令完成：

make install

或者你也可以分步执行：

1. 获取 Elixir 依赖：

   mix deps.get
   

2. 创建数据库：

   mix ecto.create
   

3. 执行数据库迁移：

   mix ecto.migrate
   

4. 安装前端依赖：

   npm ci --prefix assets
   npm ci --prefix tracker
   

5. 设置前端构建工具：

   mix assets.setup
   

6. 构建追踪脚本：

   npm run deploy --prefix tracker
   

7. 下载地理位置数据库：

   mix download_country_database
   

启动开发服务器

完成初始化后，使用以下命令启动开发服务器：

make server
# 或者
mix phx.server

服务器启动后，可以通过 http://localhost:8000 访问本地开发环境。

数据库种子数据

为了便于开发测试，项目提供了种子数据功能：

1. 执行种子脚本：

   mix run priv/repo/seeds.exs
   

2. 使用以下凭证登录：

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

3. 你将获得一个名为 dummy.site 的测试站点，其中包含生成的统计数据。

或者你也可以手动创建账户：

1. 访问 http://localhost:8000/register 注册新账户
2. 使用 dummy.site 作为测试域名
3. 跳过 JS 代码片段步骤
4. 生成测试页面浏览事件：

   mix send_pageview
   

开发环境维护

停止数据库服务

make postgres-stop
make clickhouse-stop

注意：停止容器不会删除数据卷，下次启动时会保留之前的数据状态。如需完全清理，可以使用 docker volume prune 命令，但请谨慎操作，这会删除所有数据库数据。

代码提交前检查

项目配置了 pre-commit 钩子，用于在提交前自动检查代码格式和质量。安装方法：

pip install --user pre-commit
pre-commit install

如需禁用检查：

pre-commit uninstall

开发建议

1. 从现有问题开始：建议开发者先从已知问题入手，熟悉代码库
2. 新功能讨论：对于新功能开发，建议先在社区讨论获得共识
3. 代码风格：遵循项目已有的代码风格和约定
4. 测试覆盖：新增功能应包含相应的测试用例

通过本文的指导，你应该已经成功搭建了 Plausible Analytics 的开发环境，可以开始进行功能开发和问题修复了。如果在开发过程中遇到任何问题，可以参考项目的文档或向社区寻求帮助。