主机资讯与使用指南

Umami 部署教程：Docker、网站统计与脚本接入

部署 Umami 与 PostgreSQL，完成管理员登录、网站登记、统计脚本接入和数据备份。

统计服务与网站分开运行

Umami 可以独立部署，再把脚本加到需要统计的网站。本文使用官方 Compose 所采用的镜像和 PostgreSQL 组合，网站本身无需迁移。

准备 stats.example.com 域名、Docker Compose 与宿主机 Caddy。数据库保存统计记录，保留时间和访问量会影响磁盘用量。

生成密码和密钥

mkdir -p "$HOME/umami"
cd "$HOME/umami"
umask 077
printf "DB_PASSWORD=%s\nAPP_SECRET=%s\nTWO_FACTOR_ENCRYPTION_KEY=%s\n" "$(openssl rand -hex 24)" "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > .env

将下面配置保存成 compose.yml。密码采用十六进制，便于放入数据库连接 URL；已有服务修改密钥前先查看对应文档，不能随意替换已经使用的加密密钥。

services:
  db:
    image: postgres:15-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: umami
      POSTGRES_USER: umami
      POSTGRES_PASSWORD: ${DB_PASSWORD:?set DB_PASSWORD}
    volumes:
      - ./postgres:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U umami -d umami"]
      interval: 10s
      timeout: 5s
      retries: 10
  umami:
    image: ghcr.io/umami-software/umami:latest
    restart: unless-stopped
    init: true
    ports:
      - "127.0.0.1:3002:3000"
    environment:
      DATABASE_URL: postgresql://umami:${DB_PASSWORD:?set DB_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

启动并登录

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

stats.example.com {
    reverse_proxy 127.0.0.1:3002
}

完成自己的域名解析和代理后访问登录页。官方初始账号为 admin，密码 umami，首次登录立即修改。应用密钥与管理员密码不是同一项。

添加网站并安装脚本

在后台添加网站名称和域名，复制该网站生成的跟踪代码。不同网站使用各自的 website-id，不把所有站点填成同一个标识。

将代码加入网站全局页头或对应模板。示例只展示结构，REPLACE_WITH_WEBSITE_ID 用实际生成值，脚本域名改成自己的。

<script defer src="https://stats.example.com/script.js" data-website-id="REPLACE_WITH_WEBSITE_ID"></script>

WordPress 可以通过主题支持的脚本入口或合适插件加入，升级主题时确认仍保留。

确认采集与保存数据

打开网站并查看浏览器网络请求，确认脚本及采集请求正常，再看 Umami 是否出现访问记录。浏览器扩展、内容安全策略或域名限制会影响采集，只有页面打开不代表脚本成功执行。

备份 PostgreSQL 数据、compose.yml 和 .env。软件更新前查看对应版本说明；升级 PostgreSQL 大版本时，另做数据迁移。