Docker 部署维护 Umami 一站式教程 - 自建轻量级网站统计

前言

在数据驱动的时代，了解访客如何与你的网站互动至关重要。然而，传统的网站分析工具，如 Google Analytics，正变得越来越臃肿复杂，并且伴随着严峻的数据隐私和所有权问题。你的用户数据真的属于你自己吗？庞大的脚本是否会拖慢你的网站速度？

现在，有一种更优雅、更轻便、更尊重隐私的选择。Umami 是一款开源的现代化网站分析工具，它不仅界面简洁美观，而且部署简单，资源占用极低。通过 Docker，我们可以在短短几分钟内就搭建一个完全属于自己、百分百掌控数据的分析平台。

本教程将手把手引导你，使用最流行的 Docker 技术，从零开始完成 Umami 的部署、配置到最终上线。无论你是个人站长、开发者还是隐私倡导者，这份指南都将帮你轻松迈出第一步。

如果您并不只满足于查看 UV PV 跳出率这种基础信息，而是想要进行详细、深度的营销分析，可以看一看功能更加强大且同样免费开源自部署的站内统计程序 Matomo，使用教程可以参考我这篇文章：https://www.pyrzo.com/posts/matomo/

本文使用 Docker 部署 Umami。并介绍更新维护方法，提供疑难解答。

部署 Umami

环境介绍

本文使用 Docker 部署。请确保你的机器已经安装了 Docker。

如果您还没有安装 Dcoker 可以使用一键脚本：

sudo curl -sSL https://get.daocloud.io/docker | sh

如果您使用宝塔面板，也可以进入 Docker - 安装 Docker 服务（安装方式默认）

构建容器

我们新建一个 docker-compose.yaml，这个文件可以在 /opt/umami 目录下，也可以在你反代站点目录的跟目录里，总之你喜欢的任何位置都可以，只需记住不要创建在系统根目录即可。然后在文件中填入如下内容：

version: '3'
services:
  umami:
    container_name: umami
    image: umamisoftware/umami:postgresql-latest
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgresql://umami:umami@db:5432/umami
      DATABASE_TYPE: postgresql
      HASH_SALT: replace-me-with-a-random-string
    depends_on:
      - db
    restart: always
  db:
    container_name: umami-db
    image: postgres:12-alpine
    environment:
      POSTGRES_DB: umami
      POSTGRES_USER: umami
      POSTGRES_PASSWORD: umami
    volumes:
      - ./sql/schema.postgresql.sql:/docker-entrypoint-initdb.d/schema.postgresql.sql:ro
      - ./umami-db-data:/var/lib/postgresql/data
    restart: always

随后我们进入该文件所在目录。例如我这里使用的是 /opt/umami，那么就在 SSH 终端中执行 cd /opt/umami。

然后执行 docker-compose up -d 等待镜像拉取及容器运行成功即完成安装。

容器启动后即可在浏览器中访问 IP : 3000 来进入后台。

默认账户 admin，密码 umami，登陆后请第一时间修改默认密码！

创建反代

目前你的服务只能在 3000 端口被访问，如果想让它能在 HTTP 标准端口（80/443）提供服务则需要进行反向代理。即 Nginx（或其他 Web Server）| 80/443 => Umami 容器 | 3000。

我们创建一个站点，然后添加一条反向代理，目标 url 填写 127.0.0.1:3000，证书按需选配（例如前面套层 CDN 就可以直接 80(http) 回源）

至此，你可以通过你的域名访问你的 Umami 了。

设置你的第一个站点

我们进入 Umami 后台后，第一件事便是添加站点。我们输入站点名称与域名后，会得到一个跟踪代码，我们将其添加在网站每个页面的 <head> 部分中即可。

如果你使用 Wordpres 程序，可以直接搜索插件 Simple Custom CSS and JS，添加一个 JS Code，然后填入给你的追踪代码并发布。

如果您有使用 CDN 并缓存了 HTML 页面，建议清空 CDN 缓存。

如何更新 Umami

Docker

对于 Docker，只需拉取最新的数据库配置镜像。

PostgreSQL：

docker pull docker.umami.is/umami-software/umami:postgresql-latest

或者 MySQL：（Umami 默认使用的是 PostgreSQL）

docker pull docker.umami.is/umami-software/umami:mysql-latest

常见问题

无法访问 Umami 管理界面（连接被拒绝）

可能原因：

容器未成功启动
防火墙/安全组阻止端口
端口被其他程序占用

解决方法：

运行 docker ps 检查 umami 和 postgres（或 db）容器状态是否为 Up。如果不是，运行 docker logs umami-app 查看具体错误日志。
检查服务器防火墙及云服务商（如阿里云、腾讯云）的安全组设置，确保 3000 端口（或你映射的其他端口，如 8080）已放行。

网站跟踪代码已安装，但后台无数据

可能原因：

跟踪代码错误
网站未正确配置
广告拦截器插件屏蔽

解决方法：

在Umami后台的“网站设置”中，重新复制完整的跟踪脚本，确保网站中安装的代码完全一致，特别是 data-website-id 属性。
在Umami后台点击网站名称，确保“域名”一栏填写正确，例如 yourwebsite.com（不要带https://）。可以暂时设置为 * 以接收所有来源的数据进行测试。
尝试在浏览器中禁用广告拦截器（如 uBlock Origin）后访问你的网站，看是否能统计到。

如何更新 Umami

参考本文中“如何更新 Umami”章节。

忘记了登陆密码

首先，确保你的 docker-compose.yml 中设置了 HASH_SALT 环境变量，且值是一个复杂的随机字符串。
进入 PostgreSQL 数据库容器：docker exec -it umami-db psql -d umami -U postgres
执行以下SQL命令（将 'your_new_password' 替换为你的新密码）：
UPDATE account SET password = encode(sha256('your_new_password'), 'hex') WHERE username = 'admin';