Linux怎么安装和配置Umami Linux开源隐私友好统计详解-LINUX-PHP中文网

推荐使用 docker-compose 部署 umami，因其预编译镜像规避了 prisma 引擎下载失败、mysql 8.0 认证插件兼容性及 node.js 构建依赖等问题，且天然集成数据库、健康检查与服务隔离，启动即用。

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

直接用 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
<p>db:
image: mysql:8.0
environment:
MYSQL_ROOT_PASSWORD: rootpass
MYSQL_DATABASE: umami
MYSQL_USER: umami
MYSQL_PASSWORD: umami
volumes:</p>

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:

注意：

Obsidian (Linux)

操作 Obsidian 库（纯 Markdown 笔记），并通过 notesmd-cli 实现自动化。

下载

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";
}

关键点：