Umami 在 Linux 上最稳、最省事的安装方式是 Docker + docker-compose；需确保容器网络互通、DATABASE_URL 用服务名 db 而非 localhost、正确配置 healthcheck 和 registry 镜像源、生成安全的 APP_SECRET 和 TRACKER_SCRIPT_NAME、重启生效环境变量、Nginx 透传关键请求头并匹配 BASE_PATH。
直接说结论：Umami 在 Linux 上最稳、最省事的安装方式是 Docker + docker-compose，不是源码编译，也不是宝塔一键插件——后者常因环境耦合导致 npm run build 失败或 prisma generate 卡死。
docker-compose 启动时 DATABASE_URL 连不上数据库？
这是部署失败最常见原因，本质是容器网络隔离导致的「服务名解析失败」或「端口不通」。
-
db是docker-compose.yml里定义的服务名，umami容器内必须用它访问数据库，不能写localhost或服务器真实 IP -
DATABASE_URL=postgresql://umami:umami@db:5432/umami中的@db:5432必须和db服务的image、environment严格匹配；若改用 MySQL，要同步改image（如mysql:8.0）、DATABASE_TYPE=mysql和 URL 前缀为mysql:// - PostgreSQL 镜像用
postgres:15-alpine时，healthcheck必须用pg_isready，否则depends_on不生效，umami容器可能在 DB 没就绪时就启动并报Connection refused - 国内拉取镜像超时？把
ghcr.io/umami-software/umami:postgresql-latest改成docker.umami.is/umami-software/umami:postgresql-latest，再配好/etc/docker/daemon.json的国内 registry-mirrors
APP_SECRET 和 TRACKER_SCRIPT_NAME 怎么生成才安全？
这两个值直接影响后台登录和前端脚本防篡改能力，不能留默认值或用简单字符串。
-
APP_SECRET要至少 32 位随机字符，推荐用openssl rand -base64 32生成，不要手敲或复用其他项目密钥 -
TRACKER_SCRIPT_NAME是前端加载的 JS 文件名（如umami.js），设成随机名可增加爬虫识别难度；但一旦设了，就必须确保 Nginx 反代或 CDN 缓存规则放行该路径，否则页面会 404 加载不到统计脚本 - 改完
.env或docker-compose.yml后，必须docker compose down && docker compose up -d重启，环境变量不会热更新
Nginx 反向代理后登录 401 或仪表盘空白？
这不是 Umami 本身的问题，而是反代配置漏掉了关键头信息或路径重写。
- 必须透传
Host、X-Forwarded-For、X-Forwarded-Proto，否则 Umami 认为请求不合法，返回 401；Nginx 配置里要加：proxy_set_header Host $host;<br>proxy_set_header X-Forwarded-For $remote_addr;<br>proxy_set_header X-Forwarded-Proto $scheme;
- 如果用了子路径反代（如
https://stat.example.com/umami/），需在docker-compose.yml里加BASE_PATH=/umami环境变量，并确保 Nginx 的location /umami/块末尾有proxy_pass http://127.0.0.1:3000/;（注意结尾斜杠） - 静态资源 404？检查
docker-compose.yml是否挂载了./public:/app/public，或确认npm run build后的.next目录已生成——Docker 镜像里已内置构建结果，源码方式才需要手动 build
真正麻烦的点不在安装步骤，而在于 Docker 网络、反代头透传、以及环境变量生效时机这三者的咬合。哪怕只错一个字母，比如 DB 写成 Db，或漏掉 proxy_set_header，都会让整个后台卡在登录页或白屏，且日志里未必报明确错误。
