Fathom项目配置指南：从基础到高级设置

Fathom项目配置指南：从基础到高级设置

fathom Fathom Lite. Simple, privacy-focused website analytics. Built with Golang & Preact. 项目地址: https://gitcode.com/gh_mirrors/fa/fathom

项目概述

Fathom是一个轻量级的网站分析工具，专注于提供简单、隐私友好的网站访问统计。与传统的分析工具不同，Fathom不依赖JavaScript追踪，而是通过服务器日志分析来获取访问数据，这使其成为注重用户隐私的开发者的理想选择。

基础配置

Fathom的设计哲学强调"约定优于配置"，这意味着即使完全不进行任何配置，Fathom也能使用默认设置运行。默认情况下，Fathom会使用当前工作目录下的SQLite数据库（fathom.db）。

对于大多数开发者而言，最简单的启动方式就是直接运行Fathom，无需任何额外配置。这种零配置的设计使得Fathom特别适合快速部署和测试环境使用。

配置文件详解

当需要更复杂的配置时，Fathom提供了两种配置方式：

1. 在当前工作目录创建.env文件
2. 通过--config参数指定配置文件路径

配置文件采用标准的键值对格式，支持以下主要配置项：

核心配置项

• FATHOM_DEBUG：调试模式开关，默认为false。开启后会输出更多日志信息，适合开发环境使用
• FATHOM_SERVER_ADDR：服务监听地址，默认为:8080，表示监听所有网络接口的8080端口
• FATHOM_GZIP：是否启用HTTP内容压缩，默认为false。开启后可减少网络传输量
• FATHOM_SECRET：用于会话签名的随机字符串，生产环境必须设置

数据库配置

Fathom支持三种数据库后端：

1. SQLite3（默认）：轻量级文件数据库，无需额外服务
2. MySQL：适合高负载生产环境
3. PostgreSQL：功能丰富的关系型数据库

相关配置项包括：

• FATHOM_DATABASE_DRIVER：数据库驱动类型
• FATHOM_DATABASE_NAME：数据库名称（SQLite为文件路径）
• FATHOM_DATABASE_USER：数据库用户名
• FATHOM_DATABASE_PASSWORD：数据库密码
• FATHOM_DATABASE_HOST：数据库主机地址
• FATHOM_DATABASE_SSLMODE：SSL连接模式
• FATHOM_DATABASE_URL：完整的数据库连接字符串（替代上述各项）

数据库连接最佳实践

MySQL连接配置

使用MySQL时，建议在连接字符串中包含parseTime=true&loc=Local参数，确保时间字段能正确解析为Go的时间类型。示例配置：

FATHOM_DATABASE_DRIVER=mysql
FATHOM_DATABASE_URL=username:password@tcp(hostname:3306)/dbname?parseTime=true&loc=Local

PostgreSQL连接配置

PostgreSQL对SSL连接有严格要求。如果服务器未启用SSL，需要显式禁用：

FATHOM_DATABASE_SSLMODE=disable

PostgreSQL支持的SSL模式包括：

• disable：不使用SSL
• require：必须使用SSL
• verify-ca：验证CA证书
• verify-full：完全验证

SQLite连接配置

SQLite配置最为简单，只需指定数据库文件路径。建议添加_loc=auto参数确保时区处理正确：

FATHOM_DATABASE_DRIVER=sqlite3
FATHOM_DATABASE_NAME=/path/to/fathom.db?_loc=auto

常见问题解决方案

PostgreSQL SSL错误

错误信息pq: SSL is not enabled on the server表明PostgreSQL服务器未启用SSL，而客户端默认要求SSL连接。解决方案：

1. 在服务器启用SSL（推荐生产环境使用）
2. 临时解决方案：设置FATHOM_DATABASE_SSLMODE=disable

连接字符串格式问题

使用FATHOM_DATABASE_URL时，常见的格式错误包括：

• 缺少必要的参数（如MySQL的parseTime）
• 特殊字符未正确转义
• 协议前缀缺失（如mysql://或postgres://）

建议先使用分项配置测试连接，确认无误后再转换为连接字符串格式。

生产环境配置建议

1. 禁用调试模式：设置FATHOM_DEBUG=false减少日志输出
2. 启用GZIP：设置FATHOM_GZIP=true提升传输效率
3. 使用强密钥：FATHOM_SECRET应使用足够长度的随机字符串
4. 数据库选择：生产环境推荐使用MySQL或PostgreSQL
5. SSL加密：数据库连接应启用SSL加密（特别是远程连接）

通过合理配置，Fathom可以轻松适应从开发测试到高负载生产环境的各种场景，为用户提供稳定可靠的网站分析服务。

fathom Fathom Lite. Simple, privacy-focused website analytics. Built with Golang & Preact. 项目地址: https://gitcode.com/gh_mirrors/fa/fathom