推荐使用 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
<p>db:
image: mysql:8.0
environment:
MYSQL_ROOT_PASSWORD: rootpass
MYSQL_DATABASE: umami
MYSQL_USER: umami
MYSQL_PASSWORD: umami
volumes:</p><ul><li>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</li></ul><p>volumes:
umami-db-data:
注意：
Linux AI 服务器 — 将 Linux 服务器转换为本地 AI 推理集群。使用 systemd、NVIDIA CUDA 实现无头 Linux AI，零 GUI 开销。
-
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 访问，拒绝设置SecureCookie -
proxy_cookie_path中的SameSite=Lax是现代浏览器强制要求，缺失会导致登录态无法持久化 - 若用 HTTPS 域名访问但 Nginx 没配 SSL，或证书不被信任，浏览器也会静默丢弃带
Secure标志的 Cookie
复杂点在于：Umami 的 Session 机制依赖于完整的请求链路头信息，漏一个 X-Forwarded-* 就可能让后端认为是不同客户端，反复重建 session。这点比多数 Web 应用更敏感。
