用 Docker 部署 Umami 网站统计

自建 Umami 不需要迁移原网站。把它和数据库部署好，再给网站加跟踪脚本即可。统计数据、访问权限和备份都由自己维护。

先按官方 Compose 准备数据库

从官方仓库当前的 Compose 配置开始，核对镜像、PostgreSQL 版本和环境变量。生成独立数据库密码与应用密钥，保存到权限受限的环境文件，不照抄别人的真实连接 URL。

应用与 PostgreSQL 在同一 Compose 网络时，数据库地址使用服务名和内部端口。统计服务的后端端口可以绑定宿主机回环地址，再由现有代理提供 HTTPS；数据库无需对公网开放。

下面给新部署准备一份完整配置。它使用官方预构建镜像，沿用应用与 PostgreSQL 分开的服务布局，端口改为只监听宿主机回环地址。需要 Linux VPS、Docker Engine、Compose 插件与 OpenSSL；已有 Umami 实例按原配置维护，不覆盖旧数据卷或环境文件。

先新建项目目录，生成数据库密码和两项应用密钥。在 Bash 中执行下面的命令；它仅用于首次部署，目录必须尚不存在，任何一步失败就停止：

set -eu
mkdir -m 700 ~/umami-new
cd ~/umami-new
umask 077
postgres_password=$(openssl rand -hex 32)
app_secret=$(openssl rand -hex 32)
two_factor_key=$(openssl rand -hex 32)
for secret_value in "$postgres_password" "$app_secret" "$two_factor_key"; do
  [[ $secret_value =~ ^[0-9a-f]{64}$ ]] || exit 1
done
printf 'POSTGRES_PASSWORD=%s\nAPP_SECRET=%s\nTWO_FACTOR_ENCRYPTION_KEY=%s\n' \
  "$postgres_password" "$app_secret" "$two_factor_key" > .env
unset postgres_password app_secret two_factor_key secret_value

数据库密码使用十六进制，放进下面的连接 URL 时无需再处理特殊字符。把以下内容保存为 compose.yaml：

services:
  umami:
    image: ghcr.io/umami-software/umami:latest
    ports:
      - "127.0.0.1:3000:3000"
    environment:
      DATABASE_URL: postgresql://umami:${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}@db:5432/umami
      APP_SECRET: ${APP_SECRET:?set APP_SECRET}
      TWO_FACTOR_ENCRYPTION_KEY: ${TWO_FACTOR_ENCRYPTION_KEY:?set TWO_FACTOR_ENCRYPTION_KEY}
    depends_on:
      db:
        condition: service_healthy
    init: true
    restart: unless-stopped
  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: umami
      POSTGRES_USER: umami
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}
    volumes:
      - umami-db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -h 127.0.0.1 -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 5s
      timeout: 5s
      retries: 5
    restart: unless-stopped
volumes:
  umami-db-data:

latest 与 15-alpine 都是可变标签。正式使用时记录实际镜像摘要，升级前备份；这里没有要求把已有数据库切换到 PostgreSQL 15。TWO_FACTOR_ENCRYPTION_KEY 是启用双因素认证前需要的 64 位十六进制密钥，设置它以后仍要在账号中启用双因素认证。数据库卷第一次初始化后，更改 .env 的数据库密码不会自动修改库内账号。

docker compose config --quiet
docker compose up -d
docker compose ps
docker compose logs --tail=100

当前官方 Compose 用到的密钥按文档保留。已经运行的实例不能为了“重新生成”随意更换加密密钥，升级数据库大版本也需要单独迁移。

初始登录后立即设置账号

端口绑定回环地址后，从自己的电脑通过 SSH 转发访问，your-vps 替换成实际主机名：

ssh -N -L 3000:127.0.0.1:3000 your-vps

保持连接，打开本机 http://127.0.0.1:3000。如果本机 3000 已占用，修改 -L 的第一个端口。新建数据库的初始账号为 admin，密码为 umami，首次登录后立即修改。之后需要公开统计脚本，再按宿主机 Caddy 配置 HTTPS接入自己的域名，确认页面使用正确的统计域名。管理员密码与应用密钥不同，不能改其中一个就当作另一个也已替换。控制面板仅让需要查看统计的人访问。

为每个网站建立对应记录，复制它生成的跟踪代码。website-id 用该站实际值，不把所有网站填成同一个 ID。

打开一篇文章，检查采集请求

将脚本放进实际页面模板，打开一页普通内容，在浏览器网络面板检查脚本和采集请求。CSP、可能阻止统计脚本的内容拦截工具、域名范围与代理路径都可能影响数据；页面能打开不代表脚本已执行。

再到后台确认这次访问记录。只有首页有数据时，查其他页面是否使用同一模板；更新主题或部署新版本以后，也复查脚本是否仍在。

备份保留网站标识与历史记录

统计数据主要在 PostgreSQL 中，数据库、配置和环境密钥一起备份。保存数据时考虑访问者相关信息和保留期限，备份不放在公开目录。

迁移时恢复原网站标识，确认旧脚本仍指向正确服务，并验证一次新访问。统计变化用于观察页面表现，访问或点击不代表购买订单，购买结果仍以对应平台的实际记录为准。

VPS 要同时跑得动 Umami 和数据库

已有服务器可以先按独立库、账号与端口部署。需要单独运行或现有内存不足时，按Docker 应用选购计算应用与 PostgreSQL 一起运行的资源，再预留数据增长和备份空间。上线验证真实事件请求，才能开始观察页面表现。

Umami 与 PostgreSQL 共用实例时，可以从 2 核、4 GB 内存开始测试，把历史事件增长、数据库备份和其他应用的余量计入。独立私人部署可比较雨云 RCS 的应用与云盘配置；已有同平台云数据库和网络资源时，可查看 ECS 的地域与实例组合。选配置要看查询负载和数据增长，不能只按采集脚本很小就选最小机器。

先按官方 Compose 准备数据库

初始登录后立即设置账号

打开一篇文章，检查采集请求

备份保留网站标识与历史记录

VPS 要同时跑得动 Umami 和数据库

接着读