Swetrix Docker Compose 部署指南

在一台 Ubuntu 服务器上用官方自托管编排（swetrix/selfhosting 仓库）从零部署 Swetrix 社区版 v5.4.1（前端 + API + nginx 统一入口 + ClickHouse + Redis 五服务），完成环境变量生成、服务启动、健康检查、首个账号注册、创建项目并验证事件上报出数的全流程。

SwetrixSwetrix产品分析2026/10/30

Swetrix Docker Compose 部署指南

目标：在一台 Ubuntu 服务器上用官方自托管编排（swetrix/selfhosting 仓库）从零部署 Swetrix 社区版 v5.4.1（前端 + API + nginx 统一入口 + ClickHouse + Redis 五服务），完成环境变量生成、服务启动、健康检查、首个账号注册、创建项目并验证事件上报出数的全流程。已在 Ubuntu 22.04 服务器（Docker 27 + Compose v2）上实测通过。

一、环境信息

  • 操作系统：Ubuntu 22.04 LTS（x86_64）
  • Docker：27.x，Docker Compose v2（docker compose 子命令形式）
  • Swetrix 版本：v5.4.1（官方最新稳定版，2026-08-04 发布；镜像 swetrix/swetrix-fe:v5.4.1 约 633MB、swetrix/swetrix-api:v5.4.1 约 1.1GB）
  • 依赖组件版本（官方编排锁定）：ClickHouse clickhouse/clickhouse-server:25.8-alpine、Redis redis:8.6-alpine、nginx nginx:1.31.1-alpine
  • 官方推荐资源：x86_64 / arm64 均可，内存至少 2GB（ClickHouse 为内存大头，官方附降内存配置，见第七章）
  • 服务端口：nginx 入口监听 80（本文映射为宿主机 8131 示例，读者按自身端口替换）；前端内部 3000、API 内部 5005、ClickHouse HTTP 8123、Redis 6379 均不直接对公网
  • 服务器 IP：192.168.1.200（下文访问地址以它为准，读者按自身服务器 IP 替换）
  • 部署目录：/opt/swetrix（编排仓库内容落在此处）

二、镜像选型说明

服务镜像选型依据
前端swetrix/swetrix-fe:v5.4.1官方 Docker Hub 镜像，与主仓库 Releases 版本号一一对应
APIswetrix/swetrix-api:v5.4.1官方 Docker Hub 镜像，同上；latest tag 同步指向最新稳定版
分析库clickhouse/clickhouse-server:25.8-alpine官方编排锁定；Swetrix 用 ClickHouse 同时存分析事件与业务事务数据
缓存redis:8.6-alpine官方编排锁定
入口nginx:1.31.1-alpine官方编排锁定，负责 / 与 /backend/ 路由

选型结论：五个镜像全部来自官方渠道且版本组合由官方编排文件锁定，直接照抄官方组合即可；升级 Swetrix 版本时只改两个 swetrix/* 镜像 tag，依赖库版本不建议自行大幅变更。Swetrix 不提供非 Docker 的官方分发（无裸机安装包、无系统包），Compose 是唯一官方自托管路径。

三、前置条件

  1. 服务器已安装 Docker 27+ 与 Docker Compose v2，当前用户在 docker 组；
  2. 宿主机入口端口空闲（本文用 8131，可用 ss -ltn | grep 8131 自查）；
  3. 服务器可访问外网拉取镜像（官方镜像在 Docker Hub，国内网络缓慢时配置镜像加速或代理）；
  4. openssl 命令可用（configure.sh 生成随机凭据用）；
  5. 浏览器可访问服务器入口端口（注册账号与仪表盘操作用）。

四、部署步骤

4.1 获取官方自托管编排

Swetrix 的编排文件单独维护在 swetrix/selfhosting 仓库（主仓库 README 的 Self-hosting guide 指向它），结构如下：

selfhosting/
├── compose.yaml         # 五服务编排
├── configure.sh         # 交互式 .env 生成脚本
├── nginx/
│   └── config           # nginx 反代配置（/ → 前端，/backend/ → API）
└── clickhouse/
    ├── README.md
    ├── reduce-logs.xml
    ├── disable-user-logging.xml
    ├── preserve-ram-config.xml
    └── preserve-ram-user.xml

在服务器上获取编排文件（官方文档用 git clone，亦可直接下载压缩包）：

sudo mkdir -p /opt/swetrix && sudo chown $USER /opt/swetrix && cd /opt/swetrix
git clone https://github.com/swetrix/selfhosting .
# 无法访问 GitHub 时可下载主干压缩包解压：
# curl -L https://codeload.github.com/swetrix/selfhosting/tar.gz/refs/heads/main -o sh.tgz && tar xzf sh.tgz --strip-components=1 && rm sh.tgz

4.2 生成环境变量（configure.sh）

运行官方配置脚本，交互生成 .env：

./configure.sh

脚本行为实录（实测要点）：先做 preflight 检查并打印 Docker/Compose 版本，随后要求输入实例公共 URL（必填，自动去尾部斜杠），SECRET_KEY_BASE 直接回车自动生成，其余项脚本自动写入。最终生成的 .env 结构：

# Swetrix Frontend configuration
BASE_URL=http://192.168.1.200:8131

# Swetrix API configuration
SECRET_KEY_BASE=<自动生成的 64 字符随机串>
DEBUG_MODE=false
IP_GEOLOCATION_DB_PATH=
DISABLE_REGISTRATION=true

# Database credentials
REDIS_PASSWORD=
CLICKHOUSE_PASSWORD=<自动生成的 64 位十六进制串>

逐行说明：BASE_URL 必须是浏览器可达的地址（本例 http://192.168.1.200:8131，公网部署换域名）；DISABLE_REGISTRATION=true 是官方默认的安全姿态——只放行首个注册用户；SMTP_MOCK 脚本不生成，需要控制台邮件模拟时手工追加 SMTP_MOCK=true（本文实验加此项，验证注册流程无需真实邮箱）；参数逐项含义见 《Swetrix v5.4.1 配置参数详解》。

4.3 调整入口端口（可选）

官方编排把入口 nginx 的 80 端口直接映射到宿主机。若 80 已被占用或想用高位端口，编辑 compose.yaml 中 nginx-proxy 服务的端口映射（本文实验映射为 8131）：

    ports:
      - "8131:80"

同时把 .env 的 BASE_URL 同步改为带新端口的地址，避免前端拼出错误链接。

4.4 启动编排

docker compose up -d

首次启动会按依赖顺序拉起：redis、clickhouse（带健康检查）→ swetrix-api（等待上述两者 healthy）→ swetrix 前端 → nginx-proxy（等待前后端 healthy）。全链路健康后（实测首启约 1–3 分钟，含 ClickHouse 初始化建库建表）查看状态：

docker compose ps

实测回显（五服务全部就绪，healthy 状态由各自内置健康检查驱动）：

NAME                        STATUS                    PORTS
swetrix-v5.4.1-api          Up 20 seconds (healthy)   5005/tcp
swetrix-v5.4.1-clickhouse   Up 27 seconds (healthy)   8123/tcp, 9000/tcp, 9009/tcp
swetrix-v5.4.1-fe           Up 20 seconds (healthy)
swetrix-v5.4.1-nginx        Up 9 seconds              0.0.0.0:8131->80/tcp, [::]:8131->80/tcp
swetrix-v5.4.1-redis        Up 26 seconds (healthy)   6379/tcp

4.5 健康检查与首次访问

官方两个应用镜像内置 wget --spider /ping 健康检查，可直接复现验证：

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8131/          # 前端入口
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8131/backend/  # API 经 nginx 转发

实测回显：

302
200

第一行 302 是预期行为：未登录访问前端根路径会被重定向到登录页（浏览器访问时自动跟随）；第二行 200 说明 nginx → API 的 /backend/ 转发链路健康。浏览器打开 http://192.168.1.200:8131 进入 Swetrix 界面。

4.6 注册首个账号

入口页面右上角进入登录页，切换到注册（DISABLE_REGISTRATION=true 时仅首个用户可注册，注册入口在首个用户产生后自动关闭）。本文实验账号：

  • 邮箱：admin@example.com
  • 密码：q1w2E3r4（实测服务端密码策略仅校验长度 8–72 位，无强度要求；出于安全习惯建议生产改用强口令）

注册也可以直接调 API 验证（端点 POST /backend/v1/auth/register）。注意请求体必须携带 checkIfLeaked 布尔字段（是否对照泄露密码库检查），缺失时直接 400：

curl -s -X POST http://192.168.1.200:8131/backend/v1/auth/register \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@example.com","password":"q1w2E3r4"}'

实测回显（缺字段被校验拦截）：

{"message":"Bad Request Exception","error":"Bad Request","statusCode":400}

补上字段重试：

curl -s -X POST http://192.168.1.200:8131/backend/v1/auth/register \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@example.com","password":"q1w2E3r4","checkIfLeaked":false}'

实测回显（注册成功，直接签发 JWT 令牌对与用户信息，输出节选）：

{"accessToken":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJkODdjN2VjMS01NTNiLTRlNWQtYTQ1NC00ZjUxMDU1MzdmY2Qi…","refreshToken":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJkODdjN2VjMS01NTNiLTRlNWQtYTQ1NC00ZjUxMDU1MzdmY2Qi…","user":{"id":"d87c7ec1-553b-4e5d-a454-4f5105537fcd","email":"admin@example.com", …}}

⚠️ 注意：注册响应即含 accessToken（约 30 分钟有效）与 refreshToken，无需邮箱验证环节——自托管默认 SMTP_MOCK 未配置也无妨；后续 API 调用把 accessToken 放在 Authorization: Bearer 头中即可。

4.7 创建项目并验证事件上报

登录后创建项目（名称任意，如 demo），项目创建后得到 Project ID（本文实测为 SojpySDiPDTp 形态的 12 位串）。用管理 API 创建项目的实测：

curl -s -X POST http://192.168.1.200:8131/backend/v1/project \
  -H "Authorization: Bearer <accessToken>" \
  -H 'Content-Type: application/json' \
  -d '{"name":"demo"}'

实测回显：

{
    "id": "SojpySDiPDTp",
    "name": "demo",
    "websiteUrl": null
}

拿到 Project ID 后先用 Events API 直接验证数据链路（官方文档要求：User-Agent 与访客 X-Forwarded-For 必须携带，否则独立访客与实时访客统计失真）：

curl -i -X POST http://192.168.1.200:8131/backend/log \
  -H 'Content-Type: application/json' \
  -H 'User-Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 Chrome/126 Safari/537.36' \
  -H 'X-Forwarded-For: 89.160.20.112' \
  -d '{"pid":"SojpySDiPDTp","pg":"/home","tz":"Europe/Berlin","lc":"en-US","ref":"https://www.google.com/"}'

实测回显（响应头节选）：

HTTP/1.1 201 Created
Server: nginx/1.31.1
Content-Type: application/json; charset=utf-8

再补一条自定义事件（转化类上报）：

curl -s -o /dev/null -w '%{http_code}\n' -X POST http://192.168.1.200:8131/backend/log/custom \
  -H 'Content-Type: application/json' \
  -H 'User-Agent: Mozilla/5.0 (X11; Linux x86_64) Chrome/126' \
  -H 'X-Forwarded-For: 89.160.20.112' \
  -d '{"pid":"SojpySDiPDTp","ev":"signup","pg":"/home","meta":{"plan":"pro"}}'

实测回显：

201

刷新项目仪表盘，pageview、来源（Google）、国家维度（内置 GeoIP 库把 89.160.20.112 识别为瑞典 SE）与 signup 事件计数应即时可见；统计查询 API 的出数核对见 《Swetrix API 使用详解》。

五、数据持久化说明

数据载体说明
分析事件与业务数据命名卷 swetrix-events-data（挂载 ClickHouse /var/lib/clickhouse）全部用户/项目/事件数据都在这一个卷里，备份即备份此卷
nginx 路由配置bind mount ./nginx/config只读挂载，改路由规则后 docker compose restart nginx-proxy
ClickHouse 调优bind mount ./clickhouse/*.xml只读挂载四个 XML（见第七章）

命名卷实体位于宿主机 /var/lib/docker/volumes/swetrix-v54x-stack_swetrix-events-data/_data（卷名前缀随 compose 项目名）。官方文档明确提醒：升级新版本通常附带数据库迁移，升级前必须备份该卷并按 Releases changelog 逐条执行。

六、环境变量表

.env 全量参数（默认值、逐项说明与源码级扩展变量）在配置篇逐条详解，此处给部署视角速查：

变量必填默认/生成方式说明
BASE_URL✅configure.sh 交互输入浏览器可达的实例地址
SECRET_KEY_BASE✅回车自动生成会话与鉴权签名密钥，更换会使全部会话失效
CLICKHOUSE_PASSWORD✅自动生成编排强校验，缺失拒绝启动
DISABLE_REGISTRATION建议true只放行首个注册用户
DEBUG_MODE-false保持关闭
IP_GEOLOCATION_DB_PATH-空内置 DB-IP Lite；付费库换这里
REDIS_PASSWORD-空建议生产补强口令
SMTP_* / FROM_EMAIL-空事务邮件；SMTP_MOCK=true 时打印到日志
OIDC_*-false/空企业 SSO；回调 ${BASE_URL}/socialised
GOOGLE_GSC_* / GOOGLE_GA4_*-空Google 集成 OAuth 客户端
CLIENT_IP_HEADER-空（=x-forwarded-for）反代/CDN 后必配，Cloudflare 用 cf-connecting-ip

七、配置文件挂载（ClickHouse 降内存配置）

官方编排默认给 ClickHouse 挂载 4 个 XML，小站点（总量 <100 万事件）照单全收即可把分析库内存压在 250–500MB；逐文件解读与回调参数见 《Swetrix v5.4.1 配置参数详解》第六章。

八、等价 docker run

Compose 编排等价于以下逐条启动命令（示意理解用，实际部署请用编排文件——依赖健康检查与配置挂载手写极易出错）。内部网络先行，随后按依赖顺序启动：

docker network create swetrix-net
docker run -d --name redis --network swetrix-net redis:8.6-alpine
docker run -d --name clickhouse --network swetrix-net \
  -e CLICKHOUSE_DB=analytics -e CLICKHOUSE_USER=default \
  -e CLICKHOUSE_PASSWORD=q1w2E3r4 \
  clickhouse/clickhouse-server:25.8-alpine
docker run -d --name swetrix-api --network swetrix-net \
  -e SECRET_KEY_BASE=... -e CLICKHOUSE_HOST=http://clickhouse \
  -e CLICKHOUSE_DATABASE=analytics -e CLICKHOUSE_PASSWORD=q1w2E3r4 \
  -e REDIS_HOST=redis swetrix/swetrix-api:v5.4.1
docker run -d --name swetrix --network swetrix-net \
  -e BASE_URL=http://192.168.1.200:8131 swetrix/swetrix-fe:v5.4.1
docker run -d --name nginx-proxy --network swetrix-net \
  -p 8131:80 -v /opt/swetrix/nginx/config:/etc/nginx/conf.d/default.conf:ro \
  nginx:1.31.1-alpine

九、常用运维命令

docker compose ps                          # 五服务健康状态
docker compose logs -f swetrix-api         # API 日志（含 SMTP_MOCK 邮件）
docker compose restart nginx-proxy         # 改 nginx 路由后重启
docker compose up -d --force-recreate swetrix-api   # 改 .env 后重建后端使其生效
docker compose pull swetrix swetrix-api    # 拉取新版本镜像
docker compose up -d                       # 滚动替换到新镜像（升级前先备份数据卷并读 changelog）
docker compose down                        # 停止并删除容器（保留数据卷）
docker compose down -v                     # 连同数据卷一并删除（数据将丢失，慎用）

十、常见问题

Q1：docker compose up 直接报 Set CLICKHOUSE_PASSWORD in .env？ 编排对 CLICKHOUSE_PASSWORD 做了强校验（${CLICKHOUSE_PASSWORD:?...}），.env 缺失该变量时拒绝启动。跑一遍 ./configure.sh 或手工补上即可。

Q2：前端能打开但登录/注册一直转圈？ nginx 把 /backend/ 转发给 API：确认 docker compose ps 里 swetrix-api 为 healthy；若 API 反复重启，查 docker compose logs swetrix-api，常见原因是 ClickHouse 未就绪或 SECRET_KEY_BASE 缺失。

Q3：独立访客数与实际不符、地图全标在服务器位置？ 事件里的访客 IP 被取成了反代地址。在反代与 Swetrix 之间校准 CLIENT_IP_HEADER（Cloudflare 设 cf-connecting-ip，常规反代 x-forwarded-for），改完 --force-recreate 重建后端。

Q4：注册提示已关闭？ DISABLE_REGISTRATION=true 是官方默认，只放行首个用户；要开放注册改 false 后重建 swetrix-api。

Q5：升级版本要注意什么？ 官方 how-to 明确：Releases 通常带数据库迁移，升级前备份数据卷、按 changelog 逐条执行迁移说明，再换镜像 tag 重建。

十一、参考链接