Linux安装配置Umami统计工具详解

本文深入解析了在Linux环境下高效、稳定部署Umami开源网站统计工具的实战方案，强烈推荐采用docker-compose而非源码编译方式——它一举规避了Prisma引擎下载失败、MySQL 8.0认证插件兼容性问题、Node.js构建依赖繁杂及网络受限环境下的种种坑点；文章不仅提供开箱即用的最小化配置模板，还详解了APP_SECRET安全生成、容器健康检查机制、Nginx反向代理必备的Cookie安全头设置（Secure/HttpOnly/SameSite）等关键细节，并手把手指导排查“页面空白”“登录态丢失”“数据库连接拒绝”等高频故障，真正实现一次配置、稳定运行、安心监控。

直接用 Docker 装最稳，别碰源码编译——尤其在国产系统、网络受限或 MySQL 8.0+ 环境下，npm install 和 yarn build 极易卡在 Prisma 引擎下载或国外 registry 上。

为什么推荐 docker-compose 而不是 npm start

本地 Node.js 环境装 Umami 会触发 Prisma 客户端生成、数据库迁移、前端构建三重依赖，其中 prisma generate 默认从 GitHub 下载二进制引擎，在无代理/仅内网环境大概率失败；而 Docker 镜像已预编译好所有产物，启动即用。MySQL 8.0 的认证插件（caching_sha2_password）也常导致 Node.js 的 mysql2 驱动连接报错 ER_NOT_SUPPORTED_AUTH_MODE，但官方 Docker 镜像已适配。

使用 docker-compose 还能天然隔离数据库、Web 服务、健康检查，避免手动维护 pm2 进程或 nohup 日志轮转。

无序列表说明关键点：

• ghcr.io/umami-software/umami:mysql-latest 镜像内置 MySQL 8 兼容驱动，无需改用户密码插件
• 镜像中 APP_SECRET 和 HASH_SALT 已按安全要求自动生成，不用手搓随机字符串
• 健康检查（curl http://localhost:3000/api/heartbeat）确保服务真正就绪才对外提供流量

docker-compose.yaml 必须改的三项配置

复制粘贴官方模板容易漏掉三个实际运行必填项：数据库连接、端口映射、中文支持。下面是最小可用配置（MySQL 版）：

version: '3'
services:
  umami:
    image: ghcr.io/umami-software/umami:mysql-latest
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: mysql://umami:umami@db:3306/umami
      DATABASE_TYPE: mysql
      APP_SECRET: a-very-long-random-string-here
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped
db:
image: mysql:8.0
environment:
MYSQL_ROOT_PASSWORD: rootpass
MYSQL_DATABASE: umami
MYSQL_USER: umami
MYSQL_PASSWORD: umami
volumes:

• umami-db-data:/var/lib/mysql healthcheck: test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "root", "-prootpass"] interval: 30s timeout: 10s retries: 5 restart: unless-stopped

volumes: umami-db-data:

注意：

• DATABASE_URL 中的 @db:3306 是容器内 DNS 名，不能写成 localhost 或 IP
• APP_SECRET 至少 32 字符，可用 openssl rand -base64 32 生成，改完必须重启容器
• MySQL 8.0 容器默认启用 caching_sha2_password，但 Umami 镜像已指定兼容驱动，无需额外加 ?authPlugin=mysql_native_password

启动后打不开页面？先查这三处日志

容器跑起来不等于服务就绪。常见现象是浏览器访问 http://IP:3000 显示空白或 502，此时别急着重装，按顺序查：

• 执行 docker-compose logs -f umami，看是否卡在 PrismaClientInitializationError 或 connect ECONNREFUSED —— 前者说明数据库没通，后者说明 db 容器没起来或 DATABASE_URL 错了
• 执行 docker-compose logs -f db，确认 MySQL 是否完成初始化，有无 mysqld: ready for connections 日志行
• 执行 docker exec -it umami-container-name curl -v http://localhost:3000/api/heartbeat，验证应用进程是否真在监听 —— 如果返回 {"status":"ok"} 但浏览器打不开，大概率是反代或防火墙问题

特别提醒：docker-compose up -d 后立即访问常失败，因为 MySQL 初始化要 10–20 秒，depends_on 只等容器启动，不等服务就绪，所以首次务必等日志出现 umami listening on port 3000 再试。

Nginx 反向代理必须加的两个 header

用 Nginx 做域名反代时，如果只写 proxy_pass http://127.0.0.1:3000，登录后会反复跳回登录页，原因是 Session Cookie 缺少 Secure 和 SameSite 标志。正确配置如下：

location / {
  proxy_pass http://127.0.0.1:3000;
  proxy_set_header Host $host;
  proxy_set_header X-Real-IP $remote_addr;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_set_header X-Forwarded-Proto $scheme;
  proxy_cookie_path / "/; Secure; HttpOnly; SameSite=Lax";
}

关键点：

• X-Forwarded-Proto 必须传，否则 Umami 会误判为 HTTP 访问，拒绝设置 Secure Cookie
• proxy_cookie_path 中的 SameSite=Lax 是现代浏览器强制要求，缺失会导致登录态无法持久化
• 若用 HTTPS 域名访问但 Nginx 没配 SSL，或证书不被信任，浏览器也会静默丢弃带 Secure 标志的 Cookie

复杂点在于：Umami 的 Session 机制依赖于完整的请求链路头信息，漏一个 X-Forwarded-* 就可能让后端认为是不同客户端，反复重建 session。这点比多数 Web 应用更敏感。

理论要掌握，实操不能落！以上关于《Linux安装配置Umami统计工具详解》的详细介绍，大家都掌握了吧！如果想要继续提升自己的能力，那么就来关注golang学习网公众号吧！