• 后端
• 数据分析
• 数据可视化
• 前端

导读：Umami 是一个以隐私为核心、简单快速、可作为 Google Analytics 替代品的开源网站分析平台。本文基于当前仓库（package.json 中版本为 2.12.1）的 README.md 展开，完整讲解两种主流部署路径——从源码编译安装与 Docker 容器化部署，并深入构建脚本、数据库迁移、环境变量与健康检查等源码级细节。读完本文，你将能够在一台服务器上独立完成 Umami 的初始化、配置、启动、代理与升级全流程。

一、部署前的环境要求

根据 README.md 的 Installing from Source 章节，从源码部署 Umami 需要满足两个前置条件：

• Node.js 16.13 或更新版本：用于执行安装、构建与启动命令；
• 数据库二选一：MySQL（最低 v8.0）或 PostgreSQL（最低 v12.14）。

仓库实际运行时对数据库版本的校验比 README 声明更宽松：启动检查脚本 scripts/check-db.js 会执行select version()读取数据库版本，并设置了兜底阈值——PostgreSQL 9.4.0、MySQL 5.7.0，低于该阈值的实例会直接报错退出。因此，官方 README 给出的 8.0 / 12.14 是推荐的稳妥下限，而脚本内阈值是最低的硬性门槛，两者并不冲突：建议按 README 要求选择较新的数据库版本。

此外，从源码结构看，Umami 的数据库抽象层（src/lib/db.ts）同时支持 PostgreSQL 与 MySQL（通过 Prisma 查询）以及 ClickHouse 大数据量方案，本文聚焦 README 主推的 PostgreSQL / MySQL 场景。

二、方式一：从源码安装

2.1 安装 Yarn

Umami 的依赖管理与构建脚本依赖 Yarn，先全局安装：

npm install -g yarn

2.2 获取源码并安装依赖

git clone https://github.com/umami-software/umami.git cd umami yarn install

yarn install会依据 yarn.lock 锁定依赖版本，确保构建环境与 CI 一致。

2.3 配置环境变量.env

在仓库根目录创建.env文件，核心变量只有一行：

DATABASE_URL=connection-url

连接串格式如下（PostgreSQL 与 MySQL 二选一）：

postgresql://username:mypassword@localhost:5432/mydb mysql://username:mypassword@localhost:3306/mydb

该连接串会被 Prisma Client 与运行脚本共同解析。底层解析逻辑可见 src/lib/db.ts：脚本通过url.split(':')[0]提取协议前缀来判断数据库类型，其中postgres会被归一化为postgresql。这一点与构建脚本 scripts/copy-db-files.js 中DATABASE_TYPE || url.split(':')[0]的取值方式一致——你也可以显式设置DATABASE_TYPE=postgresql或DATABASE_TYPE=mysql来覆盖推断结果。

环境变量缺失时的行为由 scripts/check-env.js 控制：当未设置SKIP_DB_CHECK且未设置DATABASE_TYPE时，必须提供DATABASE_URL，否则脚本会列出缺失项并process.exit(1)终止构建。

除DATABASE_URL外，还有一批可选环境变量（如APP_SECRET、BASE_PATH、TRACKER_SCRIPT_NAME等），详见本文第五节。

2.4 构建应用

yarn build

这一条命令背后是一整套流水线。查看 package.json 的 scripts 定义可知，yarn build实际等价于：

npm-run-all check-env build-db check-db build-tracker build-geo build-app

各阶段作用如下：

其中copy-db-files（scripts/copy-db-files.js）会根据数据库类型把 db/postgresql 或 db/mysql 目录下的schema.prisma与migrations整体复制到根目录prisma/供 Prisma 使用——这正是仓库同时维护db/mysql、db/postgresql、db/clickhouse三套数据库定义的原因。

首次安装时，构建过程会完成两件重要的事情（README 明确说明）：

1. 在数据库中自动创建全部数据表；
2. 创建一个登录用户，默认用户名admin、密码umami。

建表与迁移的实际执行者是 scripts/check-db.js 中的applyMigration，它内部调用prisma migrate deploy应用 db/postgresql/migrations（或 MySQL 对应目录）下的全部迁移文件。同一个脚本还会做 v1 旧版本检测：如果_prisma_migrations表中存在早于2023-04-17的迁移记录，说明数据库仍残留 Umami v1 表结构，构建会中止并提示先完成 v1 → v2 升级。

2.5 启动应用

yarn start

默认情况下应用监听在http://localhost:3000。README 强调：你需要通过 Web 服务器反向代理请求（如 Nginx），或修改监听端口后直接对外提供服务。

端口修改有两种途径：

• 直接改启动命令：yarn start --port 3001（基于 Next.js 生产模式 CLI）；
• 通过环境变量：查看 scripts/start-env.js 可知，yarn start-env会读取PORT（默认 3000）与HOSTNAME（默认0.0.0.0），例如：

PORT=8080 HOSTNAME=0.0.0.0 yarn start-env

生产服务器镜像（Dockerfile）正是采用start-docker入口并设置HOSTNAME 0.0.0.0、PORT 3000的方式启动的。

三、方式二：Docker 部署

3.1 一条命令启动：docker compose up -d

README 提供的最快捷方式是直接使用仓库自带的 docker-compose.yml：

docker compose up -d

该编排文件会同时启动两个容器：

• umami 服务：镜像为ghcr.io/umami-software/umami:postgresql-latest，将宿主机3000端口映射到容器3000；
• db 服务：镜像为postgres:15-alpine，通过POSTGRES_DB=umami、POSTGRES_USER=umami、POSTGRES_PASSWORD=umami初始化数据库，并将数据持久化到命名卷umami-db-data。

两个服务之间通过depends_on: db (condition: service_healthy)建立依赖，db 容器通过pg_isready探活，umami 容器则通过curl http://localhost:3000/api/heartbeat做健康检查——也就是说，Umami 暴露了一个心跳 API/api/heartbeat，可用于负载均衡器的存活探测。umami 服务本身还设置了restart: always，崩溃后会自动重启。

compose 文件中 umami 服务的环境变量示例：

DATABASE_URL: postgresql://umami:umami@db:5432/umami DATABASE_TYPE: postgresql APP_SECRET: replace-me-with-a-random-string

注意其中的APP_SECRET是用于会话加密的密钥，README 未展开，但 compose 模板中明确要求替换为随机字符串，生产环境务必生成强随机值，切勿沿用模板值。

3.2 只拉取镜像：按数据库类型选择标签

如果不想使用本地编排文件，也可以只拉取官方镜像。README 给出了两个标签，按数据库支持区分：

# PostgreSQL 支持 docker pull docker.umami.is/umami-software/umami:postgresql-latest # MySQL 支持 docker pull docker.umami.is/umami-software/umami:mysql-latest

拉取后按需自行docker run并注入DATABASE_URL、DATABASE_TYPE、APP_SECRET环境变量即可。

3.3 镜像内部：多阶段构建解析

Dockerfile 采用经典的三阶段构建，理解它对排查镜像问题很有帮助：

1. deps 阶段：基于node:18-alpine，仅安装依赖（yarn install --frozen-lockfile，并设置network-timeout 300000应对慢网络）；
2. builder 阶段：复制源码并执行yarn build-docker（即build-db+build-tracker+build-geo+build-app，跳过环境变量检查），同时会把 docker/middleware.js 复制到src/作为 Next.js 中间件；
3. runner 阶段：以非 root 用户nextjs运行，利用 Next.js 的output: 'standalone'（见 next.config.js 的output: 'standalone'配置）只拷贝运行时产物，显著减小镜像体积，最终以yarn start-docker启动。

值得留意的是 docker/middleware.js 承担的两个运行时重写职责：COLLECT_API_ENDPOINT会把自定义采集端点重写到/api/send，TRACKER_SCRIPT_NAME则把自定义脚本名重写到/script.js，这是源码部署时配置「隐藏埋点端点与脚本名」的底层机制（详见第五节）。

四、升级与更新

4.1 源码部署的更新

README 给出的更新流程为「拉取 → 装依赖 → 重建」三步：

git pull yarn install yarn build

由于数据库迁移是幂等部署式的（prisma migrate deploy只应用未执行的迁移），yarn build过程中的check-db阶段会自动完成表结构演进，无需手动执行迁移命令。

4.2 Docker 部署的更新

docker compose pull docker compose up --force-recreate

pull拉取新镜像，--force-recreate强制重建容器，同时保留命名卷umami-db-data中的数据。如果你的环境需要手动执行迁移，仓库也提供了独立命令：yarn update-db（即prisma migrate deploy）。

五、常用环境变量速查（源码级扩展）

README 只显式给出DATABASE_URL，但仓库源码中实际支持的环境变量远不止于此。以下变量均可在 next.config.js 与 scripts/check-env.js 中找到读取证据，部署时可按需配置：

需要强调的是：以上均为可选高级配置，标准自托管场景只需DATABASE_URL即可跑通。

六、初始化登录与密码管理

无论源码还是 Docker 方式，首次构建/启动完成后，使用以下凭据登录：

• 用户名：admin
• 密码：umami

出于安全考虑，登录后应立即修改默认密码。除了在界面中修改，仓库还提供了命令行工具 scripts/change-password.js，可直接执行yarn change-password重置指定用户密码，适合忘记密码或脚本化初始化场景。

登录后即可在界面上创建网站、获取埋点脚本。埋点脚本的前端实现位于 src/tracker/index.js，配套类型声明在 src/tracker/index.d.ts，如需定制或二次开发可参考。

七、部署后的常规检查清单

结合本文涉及的源码证据，给出部署完成后的自检要点：

1. 环境变量是否完整：运行yarn build时若提示 "The following environment variables are not defined"，按 scripts/check-env.js 列出的缺失项补齐；
2. 数据库是否可达：若构建报 "Unable to connect to the database"，检查DATABASE_URL的账号、密码与网络连通性（对应 scripts/check-db.js 的$connect探测）；
3. 版本是否兼容：数据库版本低于脚本阈值会报 "Database version is not compatible"；
4. 反向代理：源码方式默认监听3000，通过 Nginx 等代理/路径，并建议将FORCE_SSL设为true以获得 HSTS 头；
5. 健康检查：Docker 部署时可轮询http://localhost:3000/api/heartbeat判断服务存活（与 docker-compose.yml 内置探活一致）；
6. 安全加固：替换APP_SECRET为随机串、修改默认登录密码、生产环境不要使用弱口令数据库账号。

结语

Umami 的部署并不复杂：一条DATABASE_URL驱动整个构建与运行时，源码安装与 Docker 安装殊途同归——最终都是「Prisma 建表 + Next.js 起服务」。本文以 README.md 为骨架，结合 package.json、Dockerfile、docker-compose.yml 与 scripts 目录下的构建/检查脚本，把每一步命令背后的真实机制拆解清楚。无论是追求最小依赖的源码部署，还是追求开箱即用的容器化部署，按本文流程操作即可完成一个可投入使用的隐私优先分析平台。

• 后端
• 数据分析
• 数据可视化
• 前端