Linux上安装Umami最稳方式是docker-compose，因其预编译镜像规避Prisma引擎下载失败、MySQL 8.0认证插件兼容性等问题，且天然集成数据库、健康检查与服务隔离，启动即用。
Linux 上装 Umami 最稳的方式就是用 docker-compose，别折腾源码编译——尤其在国产系统、网络受限或 MySQL 8.0 环境下，yarn build 极易卡在 Prisma 引擎下载，npm install 也常因 registry 不可达失败。
为什么必须用 docker-compose 而不是 npm start
本地 Node.js 启动会触发三重构建：Prisma 客户端生成、数据库迁移、前端打包。其中 prisma generate 默认从 GitHub 下载二进制引擎，在无代理/内网环境几乎必挂；MySQL 8.0 的 caching_sha2_password 认证插件也会让 mysql2 驱动报 ER_NOT_SUPPORTED_AUTH_MODE。而官方 Docker 镜像已预编译全部产物，并内置适配逻辑，启动即用。
-
ghcr.io/umami-software/umami:mysql-latest镜像自带 MySQL 8 兼容驱动，不用手动改用户密码插件 -
APP_SECRET和HASH_SALT在镜像中已按安全要求自动生成，不需手搓 - 健康检查（如
curl http://localhost:3000/api/heartbeat）确保服务真正就绪才对外提供流量
DATABASE_URL 连不上？90% 是容器网络问题
错误现象：容器日志反复报 Connection refused 或 getaddrinfo EAI_AGAIN db。本质是容器间网络隔离导致服务名解析失败或端口不通。
-
DATABASE_URL必须写成postgresql://umami:umami@db:5432/umami或mysql://umami:umami@db:3306/umami——@db:5432中的db是docker-compose.yml里定义的服务名，不能写localhost或服务器真实 IP - PostgreSQL 镜像用
postgres:15-alpine时，healthcheck必须设为pg_isready -U umami -d umami，否则depends_on不生效，umami容器可能在 DB 没就绪时就启动 - 若换 MySQL，要同步改
image（如mysql:8.0）、DATABASE_TYPE=mysql和 URL 前缀为mysql://
国内拉镜像超时？改 registry + 配 daemon.json
直接拉 ghcr.io/umami-software/umami:postgresql-latest 在国内大概率超时或失败。
- 把镜像地址换成国内镜像源：
docker.umami.is/umami-software/umami:postgresql-latest（或mysql-latest） - 提前配置好
/etc/docker/daemon.json，加入主流 registry mirror，例如："https://docker.m.daocloud.io"、"https://mirror.ccs.tencentyun.com" - 改完执行
sudo systemctl daemon-reload && sudo systemctl restart docker
改完配置必须重启，环境变量不会热更新
哪怕只改了一个 APP_SECRET 或 TRACKER_SCRIPT_NAME，都必须彻底重启容器：
- 先执行
docker compose down（注意不是docker-compose down，新版本命令已去横线） - 再执行
docker compose up -d，否则新环境变量完全不生效 -
TRACKER_SCRIPT_NAME设成随机 JS 文件名（如z9x2k.js）后，Nginx 或 CDN 必须放行该路径，否则前端加载脚本 404
最易被忽略的是 depends_on 的 healthcheck 配置和 docker compose 命令的版本差异——旧脚本用 docker-compose，新环境默认只有 docker compose，少个横线就会报 command not found。
