自托管

本指南可帮助您在自己的基础设施上自行托管measure.sh。

大规模自托管需要了解以下知识：

• 安全
• 联网
• 容器和编排
• 服务器管理
• 数据库管理、备份和扩展
• 分布式系统

不正确的配置可能会导致：

• 数据丢失
• 安全漏洞
• 停机时间

它对于无法选择云托管且经验丰富的基础设施工程师可以进行部署、监控和持续管理的严格监管环境最为有用。

我们的自主机安装脚本专为单机设置而设计。对于分布式、安全和可扩展的托管，我们推荐我们的托管云.

目标

• 单个 VM 实例上的自托管测量
• 安装和配置caddy作为反向代理
• 配置邮箱认证和平台账号审批
• 配置用于验证与密码重置邮件的 SMTP

先决条件

• 基本的终端/命令行技能
• 基本的文本编辑器技能
• 通过 SSH 访问云虚拟机实例
• 能够在您的主域上添加 DNS A 记录
• 能够运行命令sudo
• git在你的路径中
• 虚拟机的外部IP

系统要求

• x86-64/amd64 Linux 虚拟机
• 以下任一受支持的 Linux 发行版
  • Ubuntu 24.04 LTS
  • Debian 12（书呆子）
• 至少 4 个 vCPU
• 至少 16 GB RAM
• 至少 100 GB 的启动磁盘卷
• 港口80和443在防火墙设置中打开

在Linux虚拟机上部署

按照这些分步说明在单个 Linux VM 实例上部署measure.sh。

1. 通过 SSH 连接到您的虚拟机

在任何流行的云托管提供商（例如 Google Cloud Platform、AWS 或 DigitalOcean）上部署满足上述系统要求的 Linux VM。计算机启动并运行后，请按照云提供商的说明通过 SSH 连接到该计算机。

2. 克隆 Measure 仓库

让我们首先移动到您的主目录。

cd ~

选择一个 git tag。您可以在 Releases 页面找到最新稳定版本 tag。

使用 git 克隆存储库并更改为measure目录。代替GIT-TAG使用您选择的 git 标签。

git clone https://github.com/measure-sh/measure.git -b GIT-TAG && cd measure

3. 运行install.sh脚本

接下来，更改为self-host目录。所有后续命令都将从该目录运行。

cd self-host

运行安装脚本sudo.

sudo ./install.sh

sudo ./install.sh --podman

measure.sh 安装脚本将检查您的系统要求并开始安装。可能需要几分钟才能完成。

4. 配置并启动您的自托管测量实例

在安装过程中，您将看到 KMonitor 配置向导。

对于第一个提示，它会询问您的公司或团队的命名空间。这通常是您的公司或团队的名称。如果单独尝试，请随意设置任何名称。

对于下一个提示，系统会要求您输入 URL 以访问measure.sh 的网络仪表板。通常，这可能看起来像主域上的子域，例如，如果您的域是yourcompany.com， 进入https://measure.yourcompany.com.

接下来，系统会要求您输入 URL 以访问 Measure 的 REST API 和摄取端点。通常，这可能看起来像，https://measure-api.yourcompany.com & https://measure-ingest.yourcompany.com分别。

在本指南的后面部分，您将为您输入的上述子域设置 DNS A 记录。现在，让我们继续下一个提示。

接下来，将 PLATFORM_ADMIN_EMAILS 设置为以逗号分隔的管理员邮箱列表。管理员使用普通邮箱密码入口登录，验证邮箱后会自动审批，并可在“账号管理”中审核其他申请。系统不再使用 Google 或 GitHub OAuth 凭据。

接下来需要设置 SMTP 邮件服务。生产环境必须配置 SMTP，用于账号验证、密码重置、审批通知、团队邀请和告警。请通过以下链接获取 SMTP 凭据：

• 设置 SMTP 电子邮件提供商

设置提供商后，复制值并输入相关提示。

如果您想在 Slack 工作区中接收提醒通知，您可以选择设置 Slack 应用。请点击以下链接创建并配置 Slack 应用：

• 设置 Slack 集成

设置 slack 集成后，复制值并输入相关提示。如果您想忽略它，请输入空值并继续。

您也可以选择设置 KMonitor Agent，以便从编码代理或 Slack 调试您的应用。请点击以下链接进行配置：

• 设置 KMonitor Agent

设置完成后，复制 API 密钥和模型值，然后在相关提示中输入它们。如果您想忽略它，请输入空值并继续。

完成后，安装脚本将尝试启动所有 KMonitor docker compose 服务。

此时，所有服务都应该已启动，但无法通过互联网访问它们。为了确保这些服务可以提供流量，让我们进行设置：

• 反向代理使用球童
• 在您的域上设置 DNS A 记录

5. 设置反向代理服务器

虽然我们推荐球童用于将传入请求路由到正确的目的地。您可以设置您选择的任何其他反向代理服务器，例如nginx或者特拉菲克。我们选择 Caddy 是因为它的设置相对简单，并且具有很好的默认设置。

现在，让我们设置球童。

更改为您的主目录。

cd ~

运行以下命令安装 caddy。

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl && \
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg && \
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list && \
sudo apt update && \
sudo apt install caddy

如果您不是在 Ubuntu 或 Debian 上安装，请按照 Caddy 上的指南进行操作安装页面安装 Caddy 后返回此处。

创建一个基本的~/Caddyfile通过运行以下命令进行配置。

cat <<EOF > ~/Caddyfile
measure.yourcompany.com {
	reverse_proxy http://localhost:3000
}

measure-api.yourcompany.com {
	reverse_proxy http://localhost:8080
}

measure-ingest.yourcompany.com {
	reverse_proxy http://localhost:8085
}
EOF

接下来，重新加载 caddy 以确保 caddy 获取我们新生成的配置。

caddy reload

6. 设置 DNS A 记录

对于最后一步，我们将设置 2 个 DNS A 记录并使这些子域发挥作用。首先，获取虚拟机的外部 IP 地址。假设外部 IP 是101.102.103.104.

转到您的域名托管提供商并为以下子域添加 A 记录。

measure.yourcompany.com           IN A        101.102.103.104
measure-api.yourcompany.com       IN A        101.102.103.104
measure-ingest.yourcompany.com    IN A        101.102.103.104

根据您的域名提供商的不同，上述 DNS 记录可能需要几分钟到几个小时才能生效。

7. 访问您的measure.sh仪表板

访问https://measure.yourcompany.com访问您的仪表板并登录以继续。代替yourcompany.com与您的域名。

升级自托管安装

升级到邮箱账号版本前，请先配置 PLATFORM_ADMIN_EMAILS 和 SMTP，检查仅大小写不同的重复邮箱，并备份 PostgreSQL。迁移会统一邮箱大小写，并在发现冲突时中止；同时会撤销全部 Dashboard 会话和 MCP Token。现有用户会迁移为已验证、已审批，但需要通过“忘记密码”建立新密码，并重新授权 MCP。

要升级到measure.sh 的特定或最新版本，请首先通过SSH 连接到您的VM 实例并运行这些命令。

对于某些目标版本，您将需要运行额外的迁移脚本。看看我们的迁移指南.

# change to the directory you
# had cloned to.
cd ~/measure

从以下位置找到合适的版本发布标签列表. 我们建议坚持使用最新的稳定版本。

跑步git fetch --tags获取所有标签。

git reset --hard # reset local modifications, if any
git fetch --tags

签出特定的 git 标签。

# replace `v1.2.3` with the suitable git tag
git checkout v1.2.3

更改为self-host目录并运行sudo ./install.sh执行升级。

# change to `self-host` directory
cd self-host

# run the `install.sh` script
sudo ./install.sh

升级需要几分钟才能完成。

在 macOS 上本地运行

您可以在 macOS 上本地运行measure.sh 以便快速试用，但请记住，并非所有功能都可以在 macOS 上按预期工作。

系统要求

在继续之前，请确保满足以下要求。

1. 克隆 Measure 仓库

选择要使用的 git tag。您可以在 Releases 页面找到最新稳定版本 tag。

使用 git 克隆存储库并更改为measure目录。代替GIT-TAG使用您选择的 git 标签。

git clone https://github.com/measure-sh/measure.git -b GIT-TAG && cd measure/self-host

2. 跑步config.sh要配置的脚本

运行config.sh自动配置大多数设置的脚本。

./config.sh

./config.sh --production

将 PLATFORM_ADMIN_EMAILS 设置为以逗号分隔的管理员邮箱列表。不再需要 Google 或 GitHub OAuth 凭据。

接下来设置 SMTP 邮件服务。邮箱注册、验证和密码重置必须使用 SMTP，团队邀请与告警也会复用该配置。请通过以下链接获取 SMTP 凭据：

• 设置 SMTP 电子邮件提供商

设置提供商后，复制这些值并将其输入到相关提示中。

3. 启动容器

要在生产模式下启动容器，请运行。

docker compose -f compose.yml -f compose.prod.yml \
  --profile migrate \
  up --build

容器需要几秒钟才能恢复正常。

4. 访问您的 KMonitor 信息中心

访问仪表板访问您的仪表板并登录以继续。

常见问题解答

其他自助托管者提出的典型问题。

问：我可以使用 podman 代替 docker 吗？

是的，你可以。使用--podman运行安装脚本时标记。

sudo ./install.sh --podman

您可以使用 docker 和 docker compose 命令管理实例，就像使用 docker 一样。

问：我犯了一些错误并想重新开始安装？

如果您想从头开始安装，请执行以下操作。

1. 从以下位置运行以下命令self-host目录

   sudo docker compose down --rmi all --remove-orphans --volumes

2. 删除克隆的measure目录

   rm -rf ~/measure

3. 从头开始重复安装过程

问：如何对KMonitor服务进行健康检查？

要对 API 服务执行运行状况检查，请使用：

curl -s https://measure.yourcompany.com | grep measure

# local environment
curl -s http://localhost:3000 | grep measure

要对 Dashboard 服务执行运行状况检查，请使用：

curl -s https://measure-api.yourcompany.com/ping | grep pong

# local environment
curl -s http://localhost:8080/ping | grep pong

要对 Ingest 服务执行健康检查，请使用：

curl -s https://measure-ingest.yourcompany.com/ping | grep pong

# local environment
curl -s http://localhost:8085/ping | grep pong

相应地替换域名。将 KMonitor 服务定义为负载均衡器或代理的后端时，这些运行状况检查端点非常有用。

问：我可以在 VPN 后面托管 KMonitor 吗？

绝对地！在 VPN 后面托管 KMonitor 是屏蔽公共互联网的好方法。不过，请记住以下几点。

1. Measure API 服务必须可通过公共互联网访问。这允许您的移动应用中的 Measure SDK 与 KMonitor 后端进行通信。

2. KMonitor 仪表板服务必须绑定到私有地址。通常，代理服务器将侦听所有网络接口。当托管在 VPN 之后时，请确保仅将仪表板服务绑定到专用 IP 上。这对于实现网络级隔离至关重要。例如，Caddy 配置如下所示：

   measure.yourcompany.com {
     # listen only on private IP
     # change the IP accordingly
     bind 10.0.0.1
     reverse_proxy http://localhost:3000
   }
   
   measure-api.yourcompany.com {
     reverse_proxy http://localhost:8080
   }
   
   measure-ingest.yourcompany.com {
     reverse_proxy http://localhost:8085
   }

阅读更多内容bind.

在上述设置中，只有授权的 VPN 用户才能访问 KMonitor 仪表板，而不会中断来自 Measure SDK 的事件提取。

问：我使用 nginx 作为反向代理。我应该更改哪些配置？

使用 nginx 时，配置以下指令。

• client_max_body_size。将其设置为足够大，例如1024M(1 GiB) 以确保大型调试映射文件（例如 proguard 和 dSYM 文件上传）能够成功。

• ignore_invalid_headers。将其设置为off，否则上传构建或映射文件（例如 proguard 和 dSYM 文件）可能会失败。

server {
  # other configuration

  client_max_body_size 1024M;
  ignore_invalid_headers off;

  # other configuration
}

Q. 如何添加或更新环境变量？

所有配置变量都定义在self-host/.env文件。为了使更新的配置生效，请关闭并启动撰写服务。

为此，请从内部运行self-host目录。

sudo docker compose -f compose.yml -f compose.prod.yml \
  --profile migrate \
  down

然后运行./install.sh脚本。

sudo ./install.sh

问：如何为 iOS 设置完整的符号？

要为系统框架符号化 iOS 框架，您需要获取 Google Drive API 密钥并执行以下操作：

1. 更新并保存DRIVE_API_KEY环境变量在self-host/.env
2. 重新启动symboloader通过运行服务

docker compose down symboloader
docker compose up -d symboloader

3. 运行symboloader的sync命令，像这样

docker compose exec symboloader symboloader \
  sync \
  --versions "last 5 versions"

有几点需要注意：

• iOS 系统符号文件可能会占用大量磁盘空间。确保您至少有 500 GB 的额外磁盘空间容量。
• 如果您收到 403 错误，您可能受到 Google 云端硬盘的速率限制：很抱歉...但您的计算机或网络可能正在发送自动查询。发生这种情况时，请在 24 小时后重试。

了解符号加载器 CLI 命令

问：为什么 ClickHouse 会消耗大量的 CPU 或内存？

ClickHouse 旨在最大限度地提高硬件利用率，通常会导致较高的 CPU 和内存消耗。在空闲状态下，当 KMonitor 未提取会话或执行查询时，您可能会观察到 25-30% 的 CPU 消耗。在较高负载下，CPU 消耗可能高达 90-100%。这是完全正常且预期的行为。

有几个因素导致了这种行为。

1. 查询执行和并行性：ClickHouse 使用多线程执行查询以提高性能。默认情况下，它使用的线程数等于可用的 CPU 核心数。

2. 背景合并和突变：ClickHouse在后台不断合并数据部分，以优化存储和查询性能。这些合并操作和数据突变可能会导致资源消耗增加。

3. 压缩与解压：ClickHouse 采用压缩算法来最小化存储空间。在摄取和查询期间压缩和解压缩数据是 CPU 密集型操作。

4. 硬件注意事项：ClickHouse 配置为有效利用可用资源，并需要足够的 RAM（建议 32 GB 或更多）。我们的默认配置旨在为大多数用户在成本和性能之间取得平衡。如果您的预算允许，请随意分配额外的系统资源。

话虽如此，我们将随着时间的推移继续优化我们的配置和建议，以尽可能适应轻量级和重量级的使用模式。

参考

1. ClickHouse 高 CPU 使用率
2. 讨论突变的 GitHub 问题
3. ClickHouse使用建议