Linux怎么安装和配置Umami Linux开源隐私友好统计详解

苏承栈

2026-09-24 • 👁 0人浏览过

推荐使用 docker-compose 部署 Umami，因其预编译镜像规避了 Prisma 引擎下载失败、MySQL 8.0 认证插件兼容性及 Node.js 构建依赖等问题，且天然集成数据库、健康检查与服务隔离，启动即用。直接用 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:

注意： CentOS Linux 7.9.2009 CentOS Linux 7.9.2009是传统CentOS Linux 7的最后主要版本，也是很多企业历史服务器中仍可能遇到的系统版本。它以稳定、兼容RHEL 7生态、文档丰富和软件支持广泛著称，曾长期用于Web服务、数据库、虚拟化节点和企业内部业务系统。不过CentOS Linux 7已于2024年6月30日停止维护，现在继续使用会面临安全补丁缺失风险。该版本更适合旧业务迁移、历史环境恢复或离线兼容性测试。下载

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

proxy_cookie_path

中的

SameSite=Lax

是现代浏览器强制要求，缺失会导致登录态无法持久化若用 HTTPS 域名访问但 Nginx 没配 SSL，或证书不被信任，浏览器也会静默丢弃带

Secure

标志的 Cookie 复杂点在于：Umami 的 Session 机制依赖于完整的请求链路头信息，漏一个

X-Forwarded-*

就可能让后端认为是不同客户端，反复重建 session。这点比多数 Web 应用更敏感。

相关文章