Umami 源代码安装-V3 版本 ​

本教程将详细指导您从源代码安装 Umami 网站统计工具，涵盖前期环境准备、源代码获取、配置、构建及启动全流程。

环境准备 ​

Umami 运行依赖 Node.js 和 PostgreSQL 数据库，需先确保这两款软件满足版本要求并正确安装。

• Node.js（v18.18 及以上）

• 安装 PostgreSQL（v12.14 及以上）

Umami 主要支持 PostgreSQL 数据库（需 12.14 及以上版本），目前官方V3版本对 MySQL 不在支持，本教程以官方推荐的 PostgreSQL 为例进行安装指导。

Windows 系统安装PostgreSQL 教程请参考PostgreSQL 安装】保姆级安装教程+特性详解

创建数据库和用户 ​

以下是 Windows 系统中创建 Umami 专用数据库和用户的完整步骤，需通过 PostgreSQL 自带的 SQL Shell 执行操作：

1. 打开 SQL Shell（psql）：通过开始菜单找到 PostgreSQL 对应的程序文件夹（如“PostgreSQL 18”），点击打开“SQL Shell (psql)”。

2. 依次输入连接参数：启动后会提示输入各项连接信息，按以下说明操作：

• Server [localhost]: 直接按 Enter（默认本地服务器）
• Database [postgres]: 直接按 Enter（默认系统数据库）
• Port [5432]: 直接按 Enter（默认端口）
• Username [postgres]: 直接按 Enter（默认超级用户）

密码参考PostgreSQL 安装】保姆级安装教程+特性详解 2.3 设置密码部分

• Password for user postgres: 输入安装 PostgreSQL 时设置的超级用户密码（输入时不显示字符，输完按 Enter） 若全部正确，会显示postgres =#提示符，表示已成功登录。

3. 创建 Umami 专用数据库：在“postgres =#”后输入命令（注意末尾必须加英文分号）： CREATE DATABASE umami_db; 按 Enter 执行，若显示“CREATE DATABASE”则表示数据库创建成功。

4. 创建 Umami 专用用户并设置密码：继续输入命令（将“umami_password”替换为你想设置的密码）： CREATE USER umami_user WITH ENCRYPTED PASSWORD 'umami_password'; 按 Enter 执行，显示“CREATE ROLE”则用户创建成功。

5. 授予用户数据库权限：输入命令授予 umami_user 对 umami_db 的全部操作权限： GRANT ALL PRIVILEGES ON DATABASE umami_db TO umami_user; 按 Enter 执行，显示“GRANT”则权限配置完成。

6. 退出 SQL Shell：输入命令 \q，按 Enter 即可关闭 SQL Shell。

#终端返回示例：
Server [localhost]:
Database [postgres]:
Port [5432]:
Username [postgres]: #数据库用户名
用户 postgres 的口令：
psql (18.1)
输入 "help" 来获取帮助信息.

#创建Umami专用数据库名：umami_db，注意后面的英文分号也需要复制执行！
postgres=# CREATE DATABASE umami_db;
CREATE DATABASE
#创建Umami专用数据库用户（用户名：umami_user，密码：123456，ENCRYPTED表示加密存储密码）
postgres=# CREATE USER umami_user WITH ENCRYPTED PASSWORD '123456';
CREATE ROLE
#给umami_user授权umami_db数据库的所有操作权限（包括查询、修改、创建表等，满足Umami应用需求）
postgres=# GRANT ALL PRIVILEGES ON DATABASE umami_db TO umami_user;
GRANT
#退出psql命令行工具（回到系统终端）
postgres=# \q

源码安装 ​

需先安装 Git 工具（用于克隆源代码）和 pnpm（用于依赖管理），再获取源代码并安装软件包。

安装 Git 和 pnpm ​

• Git 安装：访问 Git 官网（https://git-scm.com/downloads）下载对应系统安装包，按向导安装（Windows 需勾选 "Add Git to PATH"）。安装后终端执行 git --version 验证。

• pnpm 安装：终端执行 npm install -g pnpm（全局安装 pnpm），安装后执行 pnpm -v 验证版本（需 v7 及以上）。

克隆源代码并安装依赖 ​

1. 选择一个存放源代码的目录（如 Windows 的 D:\projects，Linux 的~/projects），终端进入该目录：cd /path/to/projects。

2. 克隆 Umami 源代码：git clone https://github.com/umami-software/umami.git。执行完成后，目录下会生成 umami 文件夹。

3. 进入 umami 目录：cd umami。

4. 安装依赖包：pnpm install。等待安装完成（可能需要几分钟，取决于网络速度），若未报错则依赖安装成功。

配置环境变量 ​

需创建.env 文件配置数据库连接信息，这是 Umami 与数据库通信的关键。

1. 进入 umami 目录（确保终端当前路径是 umami 文件夹）。

2. 创建.env 文件： Windows 系统：在 umami 文件夹空白处右键 → "新建" → "文本文档"，命名为 ".env"（注意：需先在文件夹选项中勾选 "显示文件扩展名"，否则会变成.env.txt）。

3. 编辑.env 文件，添加数据库连接 URL： DATABASE_URL=postgresql://username:mypassword@localhost:5432/mydb

   我的 env 配置：DATABASE_URL=postgresql://postgres:123456@localhost:5432/umami_db

• username：创建数据库和用户步骤中创建的数据库用户（如 postgres）

• mypassword：数据库用户密码（如 123456）

• localhost：数据库服务器地址（本地安装填 localhost）

• 5432：数据库端口（默认 5432）

• mydb：1.2.1 中创建的数据库名（如 umami_db）

构建 Umami ​

首次运行构建程序时，它会在您的数据库中创建所有必需的数据库表。它还会创建一个用户名为 admin、密码为 umami 的登录帐户。

启动应用程序 ​

默认情况下，应用程序将在 [此处应填写启动端口号] 上启动 http://localhost:3000。您需要 代理来自 Web 服务器的请求，或者更改端口以直接运行应用程序。

访问验证 ​

1. 打开浏览器，访问 http://localhost:3000

2. 输入默认账号密码：用户名 admin，密码 umami，点击登录