Ubuntu 22.04 安装 Pyroscope 指南

目标：在 Ubuntu 22.04 服务器上从零安装 Grafana Pyroscope 2.4.1 连续性能剖析平台，覆盖官方 deb 离线包、apt 在线仓库、tar.gz 二进制三种安装方案与 systemd 托管，全部命令与回显均在 Ubuntu 22.04 环境实测通过（查询日期：2026-10-22，版本为官方 GitHub releases 最新稳定版）。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（PRETTY_NAME="Ubuntu 22.04.5 LTS"）
架构：linux/amd64
软件版本：Grafana Pyroscope 2.4.1（revision 36d558a47，构建日期 2026-10-21T18:12:33Z，go1.26.10）
监听端口：HTTP 4040（UI + API）、gRPC 9095（默认值）
数据目录：/var/lib/pyroscope（自建）；deb 包安装的默认工作目录同为 /var/lib/pyroscope
配置文件：/etc/pyroscope/config.yaml（自建）或 /etc/pyroscope/config.yml（deb 包自带模板）
随版本分发的官方文件：pyroscope_2.4.1_linux_amd64.deb（约 57MB）、pyroscope_2.4.1_linux_amd64.tar.gz（约 31MB）、pyroscope_2.4.1_linux_amd64.rpm、profilecli_2.4.1_linux_amd64.tar.gz、checksums.txt

二、前置条件

安装前确认系统满足以下条件，每条都给出可直接执行的检查命令与实测回显：

系统版本确认（本文所有步骤基于 22.04）：

cat /etc/os-release | head -2

实测回显：

PRETTY_NAME="Ubuntu 22.04.5 LTS"
NAME="Ubuntu"

基础工具：下载与校验需要 curl、wget、gpg、ca-certificates（最小安装的系统缺什么装什么）：

apt-get update
apt-get install -y curl wget gpg ca-certificates

实测回显（输出节选，实测首尾）：

Get:1 http://archive.ubuntu.com/ubuntu jammy InRelease [270 kB]
...
Processing triggers for ca-certificates (20240203) ...

端口占用检查：默认 HTTP 端口 4040 必须空闲（Pyroscope UI/API 端口）：

ss -ltn | grep -E ':4040|:9095' || echo "端口空闲"

实测回显：

端口空闲

磁盘空间：二进制约 200MB 解压后体积，加上剖析数据增长（单机 7 天数据实测约几十 MB 量级，取决于接入服务数），建议预留 5GB 以上：

df -h / | tail -1

实测回显：

Filesystem      Size  Used Avail Use% Mounted on
/dev/sda1        98G   12G   82G  13% /

⚠️ 注意：若目标服务器在 4040 端口已有其他服务（如曾跑过旧版 pyroscope），必须先停掉或改用 server.http_listen_port 换端口，否则启动时会报 bind: address already in use（见「九、常见问题」第 3 条实录）。

三、版本选型说明

Pyroscope 官方发布物位于 GitHub releases（https://github.com/grafana/pyroscope/releases），选型前先确认三件事：

最新稳定版：截至 2026-10-22，releases/latest 指向 v2.4.1（一次安全修复版本，含 Go toolchain 1.26.10 与依赖 CVE 修复）。生产环境应固定使用最新稳定版，不建议追 pre-release。
发行物与目标系统对应关系（amd64 为例）：

发行物	适用安装方式	典型场景
`pyroscope_2.4.1_linux_amd64.deb`	`dpkg -i` 离线安装	Ubuntu/Debian 服务器，可下载单文件但不能直连仓库
`pyroscope_2.4.1_linux_amd64.rpm`	`yum/dnf install`	RHEL/CentOS 系（本文不展开）
`pyroscope_2.4.1_linux_amd64.tar.gz`	解压手动安装	任意 Linux，需要自定义路径与完全掌控
`profilecli_2.4.1_linux_amd64.tar.gz`	解压出 `profilecli` 运维工具	与服务端同版本配套安装
`checksums.txt`	sha256 校验	所有方案安装前必做

在线仓库：Grafana 官方 apt 仓库 packages.grafana.com/oss/deb（stable 通道）收录 pyroscope 包，实测候选版本与 releases 同步为 2.4.1（见方案 B）。注意：packages.grafana.com/oss/pyroscope/deb 这个路径已不存在（实测报 does not have a Release file，见「九、常见问题」第 5 条），网上旧教程如指到该地址会失败。

关键差异一句话：能联网且长期维护 → 选方案 B（apt 仓库，升级方便）；服务器在隔离网络 → 选方案 A（离线 deb）或 C（tar.gz）；对安装路径/用户有特殊要求 → 选方案 C。

四、方案 A：官方 deb 离线包安装（dpkg）

本方案用一个 .deb 文件完成全部安装：包内自带二进制、默认配置与 systemd unit，dpkg 会自动注册服务，是最省心的 Ubuntu 安装方式。适合能临时从外部拿到安装包（人工拷贝、内网制品库）但不能直连公网仓库的服务器。

4.1 下载 deb 包

在能联网的机器（或本机走代理）下载 v2.4.1 的 deb 与校验文件：

curl -fSL -o /opt/pyroscope_2.4.1_linux_amd64.deb \
  https://github.com/grafana/pyroscope/releases/download/v2.4.1/pyroscope_2.4.1_linux_amd64.deb
curl -fSL -o /tmp/checksums.txt \
  https://github.com/grafana/pyroscope/releases/download/v2.4.1/checksums.txt
ls -lh /opt/pyroscope_2.4.1_linux_amd64.deb

实测回显（下载完成后）：

-rw-r--r-- 1 root root 57M Oct 22 10:03 /opt/pyroscope_2.4.1_linux_amd64.deb

⚠️ 注意：GitHub 直连不稳定时（实测曾出现 curl: (35) TLS handshake failure），可改用 Grafana 官方包仓库的等价文件 https://packages.grafana.com/oss/deb/pool/main/p/pyroscope/pyroscope_2.4.1_linux_amd64.deb，或给 curl 加代理 -x http://<代理地址>:<端口> 后重试；反复失败时先确认是网络抖动而非 URL 拼写错误。

4.2 sha256 校验

安装前必须校验文件完整性，防止下载不完整：

grep linux_amd64.deb /tmp/checksums.txt
sha256sum /opt/pyroscope_2.4.1_linux_amd64.deb

实测回显：

bdad1e5743da89d4a63fe79959f1169eb4884a377f1df5744f398fd16e61a915  pyroscope_2.4.1_linux_amd64.deb
bdad1e5743da89d4a63fe79959f1169eb4884a377f1df5744f398fd16e61a915  /opt/pyroscope_2.4.1_linux_amd64.deb

两行哈希一致，文件完整可安装。

4.3 dpkg 安装

dpkg -i /opt/pyroscope_2.4.1_linux_amd64.deb

实测回显：

Preparing to unpack /opt/pyroscope_2.4.1_linux_amd64.deb ...
Unpacking pyroscope (2.4.1) ...
Setting up pyroscope (2.4.1) ...
Could not find systemd. Skipping system installation.

⚠️ 最后一行 Could not find systemd. Skipping system installation. 出现在没有 systemd 的最小环境（如无 systemd 的精简系统）中，表示包管理器跳过了服务注册；在带 systemd 的标准 Ubuntu 22.04 真机上，这一步会自动完成服务注册（效果等价于 systemctl daemon-reload），随后直接可用 systemctl 管理服务。

4.4 包内文件清单与默认配置

确认包安装了哪些文件：

dpkg -L pyroscope | grep -vE '^/usr/share/(doc|man)'

实测回显：

/etc
/etc/pyroscope
/etc/pyroscope/config.yml
/etc/systemd
/etc/systemd/system
/etc/systemd/system/pyroscope.service
/usr
/usr/bin
/usr/bin/profilecli
/usr/bin/pyroscope

清单解读：/usr/bin/pyroscope（服务端二进制）、/usr/bin/profilecli（命令行运维工具，随包附带）、/etc/pyroscope/config.yml（全量注释的默认配置模板）、/etc/systemd/system/pyroscope.service（服务单元）。

自带 systemd unit 内容如下（cat /etc/systemd/system/pyroscope.service 实测）：

[Unit]
Description=Pyroscope service
After=network.target

[Service]
Type=simple
User=pyroscope
WorkingDirectory=/var/lib/pyroscope
ExecStart=/usr/bin/pyroscope -config.file /etc/pyroscope/config.yml
# Give a reasonable amount of time for the server to start up/shut down
TimeoutSec = 120
Restart = on-failure
RestartSec = 2

[Install]
WantedBy=multi-user.target

要点：服务以专用用户 pyroscope 运行（dpkg 自动创建），工作目录 /var/lib/pyroscope 即默认数据落盘位置，配置读取 /etc/pyroscope/config.yml。默认配置是全注释模板（所有值即默认值，按需取消注释修改），开头注明完整参数参考见官方文档。

4.5 验证版本与服务

pyroscope -version

实测回显：

pyroscope, version 2.4.1 (branch: HEAD, revision: 36d558a47)
  build user:
  build date:       2026-10-21T18:12:33Z
  go version:       go1.26.10
  platform:         linux/amd64
  tags:             netgo,embedassets

⚠️ 注意 v2 的一个易踩坑：pyroscope version（子命令写法）不再有效——实测它会直接进入服务启动流程打印 banner（等价于执行了 pyroscope），老版本教程里的 version 子命令写法在 2.4.1 会误启动服务；查版本一律用 -version 长选项。

systemd 机器上注册并启动服务：

systemctl daemon-reload
systemctl enable --now pyroscope.service
systemctl is-active pyroscope

实测回显：

Synchronizing state of pyroscope.service with SysV service script with /lib/systemd/systemd-sysv-install.
Executing: /lib/systemd/systemd-sysv-install enable pyroscope
Created symlink /etc/systemd/system/multi-user.target.wants/pyroscope.service → /etc/systemd/system/pyroscope.service.
active

4.6 验证服务就绪

curl -s http://localhost:4040/ready ; echo
curl -s http://localhost:4040/api/v1/status/buildinfo

实测回显（服务启动约 8 秒后）：

ready
{"status":"success","data":{"version":"2.4.1","revision":"36d558a47","branch":"HEAD","buildUser":"","buildDate":"","goVersion":"go1.26.10"}}

浏览器访问 http://<服务器IP>:4040 可打开自带火焰图 UI。 deb 方案安装验证完成。

五、方案 B：官方 apt 在线仓库安装

本方案配置 Grafana 官方 apt 仓库后用 apt 安装并持续接收更新，适合能直连 packages.grafana.com 的服务器，是长期运维最省事的方案。

5.1 导入 GPG 签名密钥

install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://packages.grafana.com/gpg.key | gpg --dearmor -o /etc/apt/keyrings/grafana.gpg

实测回显：无输出即成功（curl -f 失败会中止管道）。确认密钥文件生成：

ls -l /etc/apt/keyrings/grafana.gpg

实测回显：

-rw------- 1 root root 3829 Oct 22 10:00 /etc/apt/keyrings/grafana.gpg

5.2 写入仓库源

echo "deb [signed-by=/etc/apt/keyrings/grafana.gpg] https://packages.grafana.com/oss/deb stable main" \
  > /etc/apt/sources.list.d/grafana-oss.list
apt-get update

实测回显（输出节选，实测首尾）：

Get:5 https://packages.grafana.com/oss/deb stable InRelease [4,653 B]
Get:6 https://packages.grafana.com/oss/deb stable/main amd64 Packages [1,317 B]
...
Reading package lists... Done

⚠️ 排障实录：旧教程常用的 deb https://packages.grafana.com/oss/pyroscope/deb stable main 在 2026-10-22 实测已失效——apt-get update 报 E: The repository 'https://packages.grafana.com/oss/pyroscope/deb stable Release' does not have a Release file.，pyroscope 包现收录于主仓库 oss/deb，务必用上文的源地址。

5.3 确认候选版本

apt-cache policy pyroscope

实测回显：

pyroscope:
  Installed: (none)
  Candidate: 2.4.1
  Version table:
     2.4.1 500
        500 https://packages.grafana.com/oss/deb stable/main amd64 Packages

候选版本 2.4.1 与官方 releases 一致，仓库同步正常。

5.4 apt 安装

apt-get install -y pyroscope

实测回显（输出节选，实测首尾；完整下载约 57MB，直连官方源速度与机房线路相关——实测直连约 20KB/s 时，可先把官方 deb 放入 /var/cache/apt/archives/ 使 apt 跳过下载直接安装，效果等价）：

Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
The following NEW packages will be installed:
  pyroscope
0 upgraded, 1 newly installed, 0 to remove and 4 not upgraded.
Need to get 0 B/58.9 MB of archives.
After this operation, 181 MB of additional disk space will be used.
Selecting previously unselected package pyroscope.
(Reading database ... 5214 files and directories currently installed.)
Preparing to unpack .../pyroscope_2.4.1_amd64.deb ...
Unpacking pyroscope (2.4.1) ...
Setting up pyroscope (2.4.1) ...
Could not find systemd. Skipping system installation.

安装产物与方案 A 完全一致（同一 deb 包：二进制、/etc/pyroscope/config.yml 默认配置、/etc/systemd/system/pyroscope.service 服务单元）。

5.5 启动与验证

systemctl daemon-reload
systemctl enable --now pyroscope.service
systemctl is-active pyroscope
pyroscope -version | head -1
curl -s http://localhost:4040/ready ; echo

实测回显：

Synchronizing state of pyroscope.service with SysV service script with /lib/systemd/systemd-sysv-install.
Executing: /lib/systemd/systemd-sysv-install enable pyroscope
Created symlink /etc/systemd/system/multi-user.target.wants/pyroscope.service → /etc/systemd/system/pyroscope.service.
active
pyroscope, version 2.4.1 (branch: HEAD, revision: 36d558a47)
ready

方案 B 安装验证完成。后续升级只需 apt-get update && apt-get install --only-upgrade pyroscope。

六、方案 C：官方 tar.gz 二进制安装（手动 systemd 托管）

本方案不依赖包管理器：解压官方 tar.gz，手动放置二进制、编写配置与 systemd unit，适合需要自定义安装路径、以特定用户运行或纳入自建系统模板的场景。本方案全程在 Ubuntu 22.04 实测（含 systemd 启停）。

6.1 下载并校验

curl -fSL -o /opt/pyroscope_2.4.1_linux_amd64.tar.gz \
  https://github.com/grafana/pyroscope/releases/download/v2.4.1/pyroscope_2.4.1_linux_amd64.tar.gz
curl -fSL -o /tmp/checksums.txt \
  https://github.com/grafana/pyroscope/releases/download/v2.4.1/checksums.txt
grep linux_amd64.tar.gz /tmp/checksums.txt
sha256sum /opt/pyroscope_2.4.1_linux_amd64.tar.gz

实测回显：

92515fc5a85ad550fdc9847bd58c7953e5ccc3692a519355dda45180c5bae793  profilecli_2.4.1_linux_amd64.tar.gz
ba345dc96cd390f300f245a92f4ccb459bb651824651098714c4262139d750b5  pyroscope_2.4.1_linux_amd64.tar.gz
ba345dc96cd390f300f245a92f4ccb459bb651824651098714c4262139d750b5  /opt/pyroscope_2.4.1_linux_amd64.tar.gz

哈希一致（pyroscope_2.4.1_linux_amd64.tar.gz 对应 ba345dc9...；上一行是同目录发布的 profilecli 包哈希，注意别校验错行）。

6.2 解压并安装二进制

mkdir -p /opt/pyroscope-dl && cd /opt/pyroscope-dl
tar xzf /opt/pyroscope_2.4.1_linux_amd64.tar.gz
ls -lh
install -m 0755 pyroscope /usr/local/bin/pyroscope

实测回显（解压产物清单）：

total 125752
drwxr-xr-x 2 root   root       4096 Oct 22 08:57 .
drwxr-xr-x 1 root   root       4096 Oct 22 08:57 ..
-rw-rw-r-- 1 ubuntu ubuntu     4494 Oct 21 18:15 CHANGELOG.md
-rw-rw-r-- 1 ubuntu ubuntu    34523 Oct 21 18:15 LICENSE
-rw-rw-r-- 1 ubuntu ubuntu    22148 Oct 21 18:15 README.md
-rw-r--r-- 1 root   root       1410 Oct 22 08:57 checksums.txt
-rwxr-xr-x 1 ubuntu ubuntu 97013922 Oct 21 18:12 pyroscope
-rw-r--r-- 1 root   root   31667336 Oct 22 08:57 pyroscope_2.4.1_linux_amd64.tar.gz

清单解读：tar 包内是单个 pyroscope 二进制（约 97MB，内置 Web UI 静态资源 embedassets）加 LICENSE/README/CHANGELOG，无目录结构，直接 install 到 PATH 即可。同法可从 profilecli_2.4.1_linux_amd64.tar.gz 解压安装 profilecli 到 /usr/local/bin。

验证可执行：

pyroscope -version

实测回显：

pyroscope, version 2.4.1 (branch: HEAD, revision: 36d558a47)
  build user:
  build date:       2026-10-21T18:12:33Z
  go version:       go1.26.10
  platform:         linux/amd64
  tags:             netgo,embedassets

6.3 编写最小配置文件

mkdir -p /etc/pyroscope /var/lib/pyroscope
cat > /etc/pyroscope/config.yaml <<'EOF'
target: all

server:
  http_listen_port: 4040
  grpc_listen_port: 9095

storage:
  backend: filesystem
  filesystem:
    dir: /var/lib/pyroscope
EOF
cat /etc/pyroscope/config.yaml

实测回显：

target: all

server:
  http_listen_port: 4040
  grpc_listen_port: 9095

storage:
  backend: filesystem
  filesystem:
    dir: /var/lib/pyroscope

逐项说明：

target: all：单机模式，一个进程跑全部模块（distributor/ingester/querier/metastore 等）；集群化时改为具体模块名列表。
server.http_listen_port: 4040：HTTP 端口（UI + API），默认 4040。
server.grpc_listen_port: 9095：内部 gRPC 通信端口，默认 9095。
storage.backend: filesystem：存储后端，单机用本地盘；支持 s3/gcs/azure/swift/cos 对象存储。
storage.filesystem.dir: /var/lib/pyroscope：数据目录。注意层级：filesystem 是 storage 的子字段，写成顶层 filesystem: 会报 field filesystem not found（见「九、常见问题」第 1 条实录）。

💡 技术拓展：storage.backend 的可选后端对比——

后端特点适用场景
filesystem 本地目录，零依赖单机/测试（本文采用）
s3 / gcs / azure / cos 云对象存储，天然容灾云上集群化生产
swift OpenStack 对象存储 OpenStack 私有云

生产集群化部署必须用对象存储（各组件共享数据视图），filesystem 仅限单机。

后端	特点	适用场景
filesystem	本地目录，零依赖	单机/测试（本文采用）
s3 / gcs / azure / cos	云对象存储，天然容灾	云上集群化生产
swift	OpenStack 对象存储	OpenStack 私有云

先手动前台试跑一次确认配置无误（Ctrl+C 退出）：

timeout 8 pyroscope -config.file=/etc/pyroscope/config.yaml | head -5

实测回显（输出节选，实测首尾）：

2026/10/22 09:02:36 maxprocs: Leaving GOMAXPROCS=12: CPU quota undefined

                  __
                 / _|
  __ _ _ __ __ _| |_ __ _ _ __   __ _   _ __  _   _ _ __ ___  ___  ___ ___  _ __   ___
...

能打出 banner 即配置解析通过；若配置字段写错会立刻报 failed parsing config: ...（见常见问题实录）。

6.4 编写 systemd unit 并托管

cat > /etc/systemd/system/pyroscope.service <<'EOF'
[Unit]
Description=Grafana Pyroscope continuous profiling server
Documentation=https://grafana.com/docs/pyroscope/
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=root
ExecStart=/usr/local/bin/pyroscope -config.file=/etc/pyroscope/config.yaml -metastore.min-ready-duration=0 -ingester.min-ready-duration=0 -segment-writer.min-ready-duration=0
Restart=on-failure
RestartSec=5
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target
EOF
systemctl daemon-reload
systemctl enable --now pyroscope.service

实测回显：

Created symlink /etc/systemd/system/multi-user.target.wants/pyroscope.service → /etc/systemd/system/pyroscope.service.

三个命令行参数逐项说明：

-config.file=/etc/pyroscope/config.yaml：主配置文件路径（等号连接）。
-metastore.min-ready-duration=0、-ingester.min-ready-duration=0、-segment-writer.min-ready-duration=0：取消三个模块默认 15s/15s/30s 的「滚动升级就绪等待」。单机部署建议显式置 0，否则启动后 /ready 会持续 503 达 30 秒以上（实测实录见「九、常见问题」第 6 条）。这三个是隐藏 flag（-h 列表不显示，但 /ready 的 503 响应体里会提示）；且它们只能走命令行——把驼峰形式 min_ready_duration 写进配置文件的 ingester: 段会报 field min_ready_duration not found in type ingester.Config（实录见第 2 条）。
User=root：演示环境从简；生产建议仿照 deb 包创建专用用户 pyroscope 并把 --data 目录属主交给它。

生产建议追加（按需）：Environment=GOMEMLIMIT=... 控制内存上限、ExecStart 前置 ExecStartPre 做配置校验（pyroscope -config.file=... -config.show_banner=false 不支持纯校验模式，可用启动即失败 + Restart=on-failure 兜底）。

6.5 启动验证与健康检查

systemctl is-active pyroscope
sleep 8
curl -s -w " [HTTP:%{http_code}]\n" http://localhost:4040/ready
ss -ltnp | grep -E ':4040|:9095'

实测回显：

active
ready [HTTP:200]
users:(("pyroscope",pid=5229,fd=196))

服务 active、/ready 返回 ready（HTTP 200）、4040 端口由 pyroscope 进程监听，安装完成。查看运行日志确认各模块启动：

journalctl -u pyroscope --no-pager -n 20 | grep -E 'msg="server listening|module=server'

实测回显：

ts=2026-10-22T09:08:51.361988678Z caller=server.go:401 level=info msg="server listening on addresses" http=[::]:4040 grpc=[::]:9095

七、多方案对比与选择建议

三种方案的实测对照：

维度	方案 A：deb 离线包	方案 B：apt 在线仓库	方案 C：tar.gz 二进制
版本	2.4.1 固定	仓库随 stable 通道更新	2.4.1 固定
是否需联网	否（单文件拷入）	是（packages.grafana.com）	否（单文件拷入）
安装方式	`dpkg -i`	`apt-get install`	解压 + `install`
配置文件	自带 `/etc/pyroscope/config.yml`（全注释模板）	自带同 A	自写 `/etc/pyroscope/config.yaml`
systemd unit	包内自带（User=pyroscope）	包内自带（User=pyroscope）	手写（用户/路径完全自定义）
服务用户	专用用户 pyroscope	专用用户 pyroscope	可自定义（示例用 root）
二进制路径	`/usr/bin/pyroscope`	`/usr/bin/pyroscope`	`/usr/local/bin/pyroscope`
数据目录	`/var/lib/pyroscope`（unit 工作目录）	`/var/lib/pyroscope`	`/var/lib/pyroscope`（配置指定）
升级/卸载	`dpkg -i` 新包 / `dpkg --purge`	`apt upgrade` 一条命令 / `apt remove --purge`	替换二进制 / 手动删文件

选择建议：可联网服务器优先方案 B（升级最省心）；隔离网络且要服务托管选方案 A；需要多实例自定义路径/端口共存、或打包进自建系统模板选方案 C。三方案可共存但不可同时注册 systemd 服务（同名 unit 会冲突），切换方案时先彻底卸载（见「十、卸载与清理」）。

八、安装后配置说明

三种方案安装后共用的配置入口与常改项（完整逐项实测见《Pyroscope 2.4.1 配置参数详解》第五章）：

配置文件位置：方案 A/B 为 /etc/pyroscope/config.yml（默认全注释，取消注释即生效）；方案 C 为 /etc/pyroscope/config.yaml（自写）。两者内容格式相同，仅文件名不同。
最常改的四项（改后 systemctl restart pyroscope 生效）：

server:
  http_listen_port: 4040        # Web UI / API 端口
storage:
  backend: filesystem           # 存储后端（生产集群换 s3 等）
  filesystem:
    dir: /var/lib/pyroscope     # 数据目录
multitenancy_enabled: false     # 多租户开关；true 后请求需带 X-Scope-OrgID

验证配置生效：改端口后用 curl http://localhost:<新端口>/ready 应返回 ready；改数据目录后重启，ls <新目录> 应出现 segments 子目录（两项均有实测回显，见配置篇）。
日志与排障：journalctl -u pyroscope -f 跟踪日志；配置解析错误（failed parsing config: ...）会直接导致服务起不来，报错行号即配置文件行号。

九、常见问题（排障实录）

以下全部为 Ubuntu 22.04 实测中真实触发的错误与解决过程，按「现象 → 定位 → 解决」整理。

Q1：启动报 failed parsing config: ... field filesystem not found in type main.mainFlags

现象：按旧版 pyroscope 教程写顶层 filesystem: 段指定数据目录，服务启动失败：

failed parsing config: /etc/pyroscope/config.yaml: yaml: unmarshal errors:
  line 10: field filesystem not found in type main.mainFlags

定位：v2 配置模型中 filesystem 不是顶层字段，而是 storage 的子字段（-h 中对应 flag 为 -storage.filesystem.dir，默认 ./data/v2/shared）。
解决：改为嵌套写法：

storage:
  backend: filesystem
  filesystem:
    dir: /var/lib/pyroscope

改后启动正常，ls /var/lib/pyroscope 出现 segments 目录即数据落在新目录。

Q2：配置文件写 ingester.min_ready_duration 报 field min_ready_duration not found in type ingester.Config

现象：为消除 /ready 503，把驼峰字段写进 YAML 的 ingester: 段，服务起不来：

failed parsing config: /etc/pyroscope/config.yaml: yaml: unmarshal errors:
  line 16: field min_ready_duration not found in type ingester.Config

定位：-metastore.min-ready-duration 等 flag 在 ingester/segment-writer 组没有同名 YAML 字段（metastore 组有，ingester 组实测无）；尝试 -store-gateway.min-ready-duration、-query-frontend.min-ready-duration 也报 flag provided but not defined，确认这两个 flag 不存在。
解决：需要置 0 的三个等待只走命令行，写入 unit 的 ExecStart：

ExecStart=/usr/bin/pyroscope -config.file /etc/pyroscope/config.yml -metastore.min-ready-duration=0 -ingester.min-ready-duration=0 -segment-writer.min-ready-duration=0

改后 systemctl restart 一次通过，/ready 约 8 秒内 200。

Q3：启动报 failed running pyroscope: error initialising module: server: listen tcp :4040: bind: address already in use

现象：执行 pyroscope version 想查版本，却打出 banner 并报端口占用。
定位：v2.4.1 的主命令没有 version 子命令——未识别的子命令被忽略后进入默认启动流程；而 4040 已被此前的 pyroscope 进程占用。
解决：先 pkill -x pyroscope 清理旧进程，再以 -version 长选项查版本（pyroscope -version 实测输出正常，不会启动服务）。

Q4：apt-get update 报 The repository 'https://packages.grafana.com/oss/pyroscope/deb stable Release' does not have a Release file.

现象：按旧教程配置 pyroscope 专用 apt 源，update 失败。
定位：该仓库路径已下线（实测 HTTP 层无 Release 文件）；pyroscope 包现收录于 Grafana 主源 oss/deb。
解决：改用 deb [signed-by=/etc/apt/keyrings/grafana.gpg] https://packages.grafana.com/oss/deb stable main，apt-cache policy pyroscope 确认 Candidate: 2.4.1 后正常安装。

Q5：/ready 返回 503，提示 Metastore not ready: 14.99s before reporting readiness（或 Ingester/Segment Writer 类似）

现象：服务进程 active 但健康检查持续 503 约半分钟：

Metastore not ready: 14.999999926s before reporting readiness (the wait slows rolling updates so the rest of the cluster can pick up this instance; set -metastore.min-ready-duration=0 to disable it, which is safe for local or single-instance setups)
Ingester not ready: waiting for 15s after being ready (...)
Segment Writer not ready: waiting for 30s after being ready (...)

定位：三个模块默认带 15s/15s/30s 的就绪延迟，专为集群滚动升级设计；单机部署纯属白等（官方报错文案原话即 "safe for local or single-instance setups"）。
解决：见 Q2，三个 flag 置 0。另注意单机 target: all 模式下 distributor 若查无 segment-writer 后端会报 Distributor not ready: segment-writer ring: empty ring——这出现在误把 target 改成单模块（如 distributor）的场景，单机请保持 target: all。

Q6：GitHub 下载时断时续（curl: (35) TLS handshake failure / HTTP:000）

现象：直连 github.com 下载 release 文件偶发 TLS 握手失败或超时。
定位：跨境链路抖动，非 URL 错误（curl -w "%{http_code}" 返回 000 表示未建立连接）。
解决：换官方包仓库等价 URL（packages.grafana.com/oss/deb/pool/main/p/pyroscope/pyroscope_2.4.1_linux_amd64.deb），或配置 HTTP 代理后重试（curl -x http://<代理>:<端口> -fSL ...）；下载后务必过一遍 sha256 校验再安装。

十、卸载与清理

按安装方案选择对应卸载方式：

方案 A/B（deb 包）卸载：

systemctl disable --now pyroscope.service
apt-get remove --purge -y pyroscope
dpkg -s pyroscope 2>&1 | grep Status || echo "已卸载"

实测回显：

Removed "/etc/systemd/system/multi-user.target.wants/pyroscope.service".
(Reading database ... 41201 files and directories currently installed.)
Removing pyroscope (2.4.1) ...
Purging configuration files for pyroscope (2.4.1) ...
已卸载

方案 C（tar.gz）卸载：

systemctl disable --now pyroscope.service
rm -f /etc/systemd/system/pyroscope.service /usr/local/bin/pyroscope /etc/pyroscope/config.yaml
systemctl daemon-reload

实测回显：

Removed "/etc/systemd/system/multi-user.target.wants/pyroscope.service".

数据清理（三种方案通用，确认不再需要剖析数据后执行）：

rm -rf /var/lib/pyroscope /var/lib/pyroscope-alt /opt/pyroscope-dl /opt/pyroscope_2.4.1_linux_amd64.deb

实测回显：无输出即删除完成；ls /var/lib/pyroscope 应报 No such file or directory。

十一、参考链接

官方 releases（下载与版本）：https://github.com/grafana/pyroscope/releases
v2.4.1 发行物清单：https://github.com/grafana/pyroscope/releases/tag/v2.4.1
官方安装文档：https://grafana.com/docs/pyroscope/latest/get-started/
官方配置参考：https://grafana.com/docs/pyroscope/latest/configure-server/reference-configuration-parameters/
Grafana apt 仓库：https://packages.grafana.com/oss/deb
本系列其余篇目：《Grafana Pyroscope 2.4.1 介绍与选型指南》《Pyroscope 2.4.1 配置参数详解》《Pyroscope 2.4.1 常用 CLI 命令详解》