Umami 网站分析工具 Docker Compose 部署指南

Umami 是一个开源的、注重隐私保护的网站分析工具，它提供了简洁直观的界面来跟踪网站访问数据。本文将详细介绍如何使用 Docker Compose 部署 Umami 及其 PostgreSQL 数据库。

架构概述

该 Docker Compose 文件定义了一个由两个服务组成的系统架构：

1. Umami 应用服务：基于 Node.js 构建的网站分析应用
2. PostgreSQL 数据库服务：用于持久化存储分析数据

服务配置详解

Umami 应用服务配置

umami:
  image: ghcr.io/umami-software/umami:postgresql-latest
  ports:
    - "3000:3000"
  environment:
    DATABASE_URL: postgresql://umami:umami@db:5432/umami
    DATABASE_TYPE: postgresql
    APP_SECRET: replace-me-with-a-random-string
  depends_on:
    db:
      condition: service_healthy
  restart: always
  healthcheck:
    test: ["CMD-SHELL", "curl http://localhost:3000/api/heartbeat"]
    interval: 5s
    timeout: 5s
    retries: 5

关键配置说明：

1. 镜像选择：使用了官方提供的 PostgreSQL 兼容版本镜像
2. 端口映射：将容器内的 3000 端口映射到主机的 3000 端口
3. 环境变量：
   • DATABASE_URL：定义了连接 PostgreSQL 的 URL
   • DATABASE_TYPE：明确指定使用 PostgreSQL 数据库
   • APP_SECRET：用于加密会话的安全密钥，部署时必须替换为随机字符串
4. 健康检查：定期检查应用是否正常运行
5. 依赖管理：确保数据库服务健康后才启动应用

PostgreSQL 数据库服务配置

db:
  image: postgres:15-alpine
  environment:
    POSTGRES_DB: umami
    POSTGRES_USER: umami
    POSTGRES_PASSWORD: umami
  volumes:
    - umami-db-data:/var/lib/postgresql/data
  restart: always
  healthcheck:
    test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
    interval: 5s
    timeout: 5s
    retries: 5

关键配置说明：

1. 轻量级镜像：使用 Alpine Linux 基础的 PostgreSQL 15 镜像，体积更小
2. 认证配置：预设了数据库名称、用户名和密码（均为 umami）
3. 数据持久化：通过命名卷 umami-db-data 持久化存储数据
4. 健康检查：确保数据库服务已准备好接受连接

部署实践建议

1. 安全加固：

   • 务必修改 APP_SECRET 为强随机字符串
   • 考虑修改默认的数据库凭据（用户名/密码）

2. 网络配置：

   • 生产环境中建议添加自定义网络而非使用默认网络
   • 考虑使用反向代理（如 Nginx）暴露服务

3. 性能调优：

   • 可根据访问量调整 PostgreSQL 的内存参数
   • 对于高流量网站，考虑分离应用和数据库到不同主机

4. 备份策略：

   • 定期备份 umami-db-data 卷中的数据
   • 考虑设置自动备份机制

部署步骤

1. 创建 docker-compose.yml 文件并填入上述内容
2. 修改 APP_SECRET 和其他安全相关配置
3. 运行 docker-compose up -d 启动服务
4. 访问 http://localhost:3000 验证部署

常见问题排查

1. 应用无法启动：

   • 检查数据库服务是否健康
   • 查看容器日志：docker-compose logs umami

2. 数据库连接问题：

   • 确认环境变量中的连接字符串正确
   • 验证数据库服务健康状态

3. 性能问题：

   • 检查主机资源使用情况
   • 考虑增加 PostgreSQL 的资源限制

通过以上配置和说明，您可以轻松部署一个功能完整的 Umami 网站分析系统。这种容器化部署方式不仅简化了安装过程，还便于后续的维护和扩展。