Umami：从Cloud迁移到服务器

相信我，dockeZ 会比直接裸装数据库要好，因为很大可能你的 Umami build 不动，除非本地构建再上传；就是那样的话本地还得装环境，况且 Umami 官方是支持 docker 部署的

一、安装 Docker 和 Docker Compose#

1.添加 Docker 官方仓库(镜像)

1
sudo apt-get update
2
sudo apt-get install -y ca-certificates curl gnupg

2.添加 Docker GPG key 下载，换为阿里云的镜像

Docker 官方要求把 GPG key 存在这个目录，属于新的安全规范（避免污染系统 key）。

1
sudo mkdir -p /etc/apt/keyrings
2

3
curl -fsSL https://mirrors.aliyun.com/docker-ce/linux/ubuntu/gpg \
4
| sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

https://download.docker.com -> https://mirrors.aliyun.com

3.添加 Docker apt 源

把 Docker 下载地址从官方改成镜像
以后 apt install docker-ce 就走国内源

1
echo \
2
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
3
https://mirrors.aliyun.com/docker-ce/linux/ubuntu \
4
$(lsb_release -cs) stable" \
5
| sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

4.安装 Docker 和 Docker Compse

刚刚添加了新源，必须更新，否则 apt 不知道这个源存在

1
sudo apt-get update
2
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

5.验证安装完成

1
docker -v
2
docker compose version

6.允许普通用户使用 Docker，避免每一步 sudo

1
sudo usermod -aG docker $USER
2
newgrp docker

Umami 推荐用 Docker Compose 部署，这样 Umami 应用和 PostgreSQL 数据库可以统一管理。

7.创建 Umami 部署目录

1
sudo mkdir -p /opt/umami
2
sudo chown -R $USER:$USER /opt/umami
3
cd /opt/umami

把 Umami 的配置文件和数据库挂载数据统一放在 /opt/umami，后期维护、备份、迁移更方便。

二、编写 docker-compose.yml#

切换目录为：

1
cd /opt/umami
2
nano docker-compose.yml

写入内容如下（：APP_SECRET、POSTGRES_DB、POSTGRES_USER: umami

1
  `POSTGRES_PASSWORD`可自行更改

1
services:
2
  umami:
3
    image: ghcr.io/umami-software/umami:latest
4
    container_name: umami
5
    ports:
6
      - "127.0.0.1:3000:3000"
7
    environment:
8
      DATABASE_URL: postgresql://umami:umami_password@db:5432/umami
9
      APP_SECRET: your_random_app_secret
10
    depends_on:
11
      db:
12
        condition: service_healthy
13
    restart: always
14

15
  db:
16
    image: postgres:15-alpine
17
    container_name: umami-db
18
    environment:
19
      POSTGRES_DB: umami
20
      POSTGRES_USER: umami
21
      POSTGRES_PASSWORD: umami_password
22
    volumes:
23
      - ./postgres-data:/var/lib/postgresql/data
24
    restart: always
25
    healthcheck:
26
      test: ["CMD-SHELL", "pg_isready -U umami -d umami"]
27
      interval: 5s
28
      timeout: 5s
29
      retries: 5

生成 APP_SECRET：

1
openssl rand -base64 32

DATABASE_URL 是 Umami 连接 PostgreSQL 的地址。
APP_SECRET 用于加密会话，不能随便写固定弱字符串。
127.0.0.1:3000:3000 表示 Umami 只允许本机访问，外部访问交给 Nginx 反代，更安全。

三、启动 Umami#

**1. 以下命令是在/opt/umami 下执行，否则会找不到 docker-compose.yml **

1
cd /opt/umami
2
sudo docker compose up -d

2. 查看容器：

1
sudo docker compose ps

3. 查看日志：

1
sudo docker compose logs -f umami

确认 Umami 和 PostgreSQL 是否正常运行，尤其是数据库，像图片中就是正常运行了

4.测试本地访问

1
curl -I https://127.0.0.1:3000

正常是可以得到 HTTP/1.1 200 OK此类回显；

我们的顺序是先确认 Umami 本身在服务器内部可访问，再配置域名和 HTTPS

四、配置 Nginx 反向代理#

1.创建配置：

1
sudo nano /etc/nginx/sites-available/umami

写入：

以下内容要**注意更改证书路径**

1
server {
2
    listen 80;
3
    server_name umami.sirens007.cn;
4

5
    return 301 https://$host$request_uri;
6
}
7

8
server {
9
    listen 443 ssl http2;
10
    server_name umami.sirens007.cn;
11

12
    ssl_certificate /path/to/your.crt;
13
    ssl_certificate_key /path/to/your.key;
14

15
    ssl_protocols TLSv1.2 TLSv1.3;
16
    ssl_ciphers HIGH:!aNULL:!MD5;
17

18
    location / {
19
        proxy_pass http://127.0.0.1:3000;
20

21
        proxy_set_header Host $host;
22
        proxy_set_header X-Real-IP $remote_addr;
23
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
24
        proxy_set_header X-Forwarded-Proto $scheme;
25
    }
26
}

启用：

1
sudo ln -s /etc/nginx/sites-available/umami /etc/nginx/sites-enabled/umami
2
sudo nginx -t
3
sudo systemctl reload nginx

是因为 Docker 里的 Umami 不直接暴露公网，而是通过 Nginx 提供 HTTPS 访问，后期方便配置证书、缓存…

注意，在访问并登录 Umami 前，先申请 SSL 证书以便支持 https 协议，如果是阿里云用户可

以在阿里云中申请个人测试证书，要记得三个月一换

申请后可以在阿里云的工作台一键上传证书和私钥，记得上传

随后便可以登录 Umami：

直接在浏览器访问https://umami.sirens007.cn，改为你的域名即可

默认账号密码为：

用户名：admin

密码：umami

登录后立刻修改密码，否则你的账号可能被别人登录并改密

五、导入 Umami 访问数据#

1. 在 Umami 后台添加你的网站，比如blog.sirens007.cn

创建一条 website，随后就可以得到 shareId，并且获取统计脚本，例如

1
<script
2
  defer
3
  src="https://umami.sirens007.cn/script.js"
4
  data-website-id="新的 website_id">
5
</script>

为什么导入放在后面，因为可以让你的网站能拿到最新的访问数据…

开个玩笑，其实就是为了在能够拿到 website_id 后，才需要对导出的数据文件操作

2.访问 Umami Cloud Data | Settings ，选择导出数据

随后会在你注册的邮箱中收到一个 zip 压缩包，其中只有 website_event.csv 这个文件有数据，其他两个只有表头

不知道你是一位喜欢 CLI 界面还是 GUI 界面的爱好者，如果是喜欢命令行的话在服务器用查询语句就可以查到 umami 这个仓库下的所有字段；如果喜欢图形化，那么 Navicat 可能是你需要的，或者 pgAdmin - PostgreSQL Tools。类似下图中可以看到各个字段的顺序，同时也可以修改

此时你可能还需要一个能够修改 csv 文件的一个软件，不推荐 wps 和 excel，首先 excel 可能是 CRLF 文件类型问题，wps 在你编辑后需要转为 xlsx 文件，所以还是奉劝下一个CSV编辑软件： SmoothCSV - The ultimate CSV editor for macOS & Windows

在我在的版本 Umami3.1 中，website_event.csv 文件中有 41 行数据，而 PostgreSQL 数据库中的 website_event 这个表中只有 31 条，因此如果要导入该文件需要删除 10 条数据库中不存在的字段的数据，但是要先备份该文件，因为后 10 条数据实际上是放在数据库中的 session 这个表中的，因此将备份的文件删掉 event 表中的 31 列数据后并排好序就可导入

website_event.csv 该文件中的 event_id 需要修改为服务器部署的 Umami 增设的 website 新获得的 websiteId，只有此处有修改，剩下的只需要排序即可

3. 随后使用 scp 命令上传至服务器即可

1
scp website_event.csv session.csv root@服务器IP:/home/sirens/

4. 然后复制进 PostgreSQL 容器：

1
sudo docker cp /home/root/website_event.csv umami-db:/tmp/website_event.csv
2
sudo docker cp /home/root/session.csv umami-db:/tmp/session.csv

主要是因为psql \copy 在容器里执行时，读取的是容器内部路径，所以要先把 CSV 放进容器的 /tmp

5. 随后进入 PostgreSQL：

1
sudo docker compose exec db psql -U umami -d umami

-U 代表用户 Users，-d 代表 database

数据导入、查看表结构、删除约束、恢复约束都要在 PostgreSQL 里完成或者在 Navicat 中完成；在导入前，最后检查一遍是否与数据库中的字段顺序对应上

6. 查看 website_event：

1
SELECT ordinal_position, column_name, data_type
2
FROM information_schema.columns
3
WHERE table_name = 'website_event'
4
ORDER BY ordinal_position;

6. 查看 session：

1
SELECT ordinal_position, column_name, data_type
2
FROM information_schema.columns
3
WHERE table_name = 'session'
4
ORDER BY ordinal_position;

注意可能输出的字段按页折叠，记得检查完全

重要步骤！！！

7. 迁移前先备份数据库

1
sudo docker compose exec db pg_dump -U umami -d umami > /opt/umami/backup_before_import.sql

8.再检查一下本地 session 和 website_event 字段顺序

检查 website_event：

1
SELECT ordinal_position, column_name, data_type
2
FROM information_schema.columns
3
WHERE table_name = 'website_event'
4
ORDER BY ordinal_position;

然后根据实际字段写导入语句，例如常见结构可能类似：

1
\copy website_event (
2
  event_id,
3
  website_id,
4
  session_id,
5
  created_at,
6
  url_path,
7
  url_query,
8
  referrer_path,
9
  referrer_query,
10
  referrer_domain,
11
  page_title,
12
  event_type,
13
  event_name,
14
  visit_id
15
)
16
FROM '/tmp/website_event.csv'
17
WITH (FORMAT csv, HEADER true, NULL '\N', QUOTE '"');

1
# 建议执行单条命令，如上条报错
2
sudo docker compose exec db psql -U umami -d umami -c "\copy session (session_id, website_id, browser, os, device, screen, language, country, region, city, created_at, distinct_id) FROM '/tmp/session.csv' WITH (FORMAT csv, HEADER true, NULL '\N', QUOTE '\"');"

注意：
这条不能直接照抄，必须以你本地 information_schema.columns 查到的字段为准；

原因：
Umami Cloud 导出的 CSV 字段和本地 v3.x 表结构可能不同。多字段、少字段、顺序不一致都会导入失败；

检查 session 本地字段：

1
SELECT column_name
2
FROM information_schema.columns
3
WHERE table_name = 'session'
4
ORDER BY ordinal_position;

然后导入时必须这样写成一整条命令，不要在 psql 交互里分开敲：

1
\copy session (
2
  session_id,
3
  website_id,
4
  browser,
5
  os,
6
  device,
7
  screen,
8
  language,
9
  country,
10
  region,
11
  city,
12
  created_at,
13
  distinct_id
14
)
15
FROM '/tmp/session.csv'
16
WITH (FORMAT csv, HEADER true, NULL '\N', QUOTE '"');

如果你是在 shell 里执行，推荐：

1
sudo docker compose exec db psql -U umami -d umami -c "\copy session (session_id, website_id, browser, os, device, screen, language, country, region, city, created_at, distinct_id) FROM '/tmp/session.csv' WITH (FORMAT csv, HEADER true, NULL '\N', QUOTE '\"');"

原因：

就是我之前有报错syntax error at or near "session_id"

9.重启 Umami

1
sudo docker compose restart umami

最后访问后台 umami.example.com 登录检查数据是否对应即可

总流程顺序：

1
1. 安装 Docker
2
2. 创建 /opt/umami
3
3. 写 docker-compose.yml
4
4. 启动 Umami + PostgreSQL
5
5. 配置 Nginx + HTTPS
6
6. 登录后台并修改密码
7
7. 创建网站
8
8. 导出 Umami Cloud 数据
9
9. 上传 CSV 到服务器
10
10. 备份本地数据库
11
11. 查看本地表结构
12
12. 修正 CSV 字段和 website_id
13
13. 导入 session
14
14. 导入 website_event
15
15. 检查数据关联
16
16. 恢复约束
17
17. 重启 Umami
18
18. 修改博客统计脚本
19
19. 后台验证统计结果

参考文章：

Umami Cloud迁移到本地踩坑记录

Installation

美好將發生

一、安装 Docker 和 Docker Compose#

二、编写 docker-compose.yml#

三、启动 Umami#

四、配置 Nginx 反向代理#

五、导入 Umami 访问数据#

目录