Sentry 26.10.0 Ubuntu 22.04 安装指南

在 Ubuntu 22.04 上从零自托管部署 Sentry 26.10.0 错误追踪平台,覆盖 Docker 环境准备、self-hosted 仓库安装脚本、初始化启动、管理员创建与验证排障,全程命令实测。

SentrySentryUbuntuUbuntu 22.04LinuxDocker2026/10/17

Sentry 26.10.0 Ubuntu 22.04 安装指南

目标:在一台 Ubuntu 22.04 服务器上从零部署 Sentry 自托管(self-hosted)26.10.0,完成 Docker 环境准备、官方仓库获取、安装脚本执行、服务启动、管理员账号创建与登录验证,并在遇到安装故障时按本文排障章节处理。本文全部命令与输出均在 Ubuntu 22.04(x86_64)实测环境逐行采集。

一、环境信息

本文实测环境与关键组件版本如下,所有回显均来自该环境:

  • 操作系统:Ubuntu 22.04(x86_64,内核 6.8.0-138-generic)
  • Sentry self-hosted:26.10.0(仓库 tag 26.10.0,commit 5f84986,发布于 2026-10-16)
  • Docker Engine:29.8.1(实测安装流程);apt 官方源当前可装 29.9.1(见下文安装输出)
  • Docker Compose:v5.5.1(实测安装流程);apt 官方源当前可装 v5.6.0
  • 服务实例形态:Sentry self-hosted 官方 Docker Compose 全栈,共 53 个服务
  • 部署目录:/root/sentry(self-hosted 仓库检出目录,可自定)
  • 对外端口:9000(nginx 反代入口,由 .env 中 SENTRY_BIND 控制)
  • 管理员账号:admin@sentry.local / q1w2e3r4(本文演示账号,生产环境请更换为真实邮箱与强口令)

💡 说明:Sentry 是错误追踪(Error Tracking)与性能监控(APM)平台,官方只提供 Docker Compose 一种自托管方式,不像 MySQL 那样提供系统包安装。因此本文的「安装」= 安装 Docker 环境 + 获取 self-hosted 仓库 + 执行官方安装脚本,全部步骤均为官方推荐路径。

二、前置条件

2.1 硬件与软件最低要求

Sentry self-hosted 是一个包含 53 个服务的完整技术栈(Web、任务队列、Kafka、ClickHouse、PostgreSQL 等),官方在 install/_min-requirements.sh 中写死了最低要求,安装脚本会逐一校验,不满足直接退出:

项目全量安装(默认)仅错误监控(errors-only 模式)说明
内存14000 MB(约 14 GB)7000 MB(约 7 GB)安装脚本用 free -m 实测校验
CPU 核数4 核2 核安装脚本用 nproc --all 实测校验
Docker19.03.6 及以上同左MIN_DOCKER_VERSION
Docker Compose2.32.2 及以上同左MIN_COMPOSE_VERSION
磁盘建议 50 GB 以上可用空间20 GB 以上初装全栈数据卷约 110 MB + 全部组件镜像约 8 GB,随事件量增长
网络可访问 GitHub 与 ghcr.io同左拉取仓库与组件镜像
对比项全量安装errors-only
服务数量53 个约 20 个
内存下限14 GB7 GB
功能范围错误 + 性能 + 剖析 + 监控项 + Uptime仅错误监控
适用场景生产完整功能资源紧张或只需错误追踪

关键差异:errors-only 通过 .env 中 COMPOSE_PROFILES=errors-only 启用,会裁掉性能剖析、Uptime 拨测等非错误类服务,内存减半。本文按官方默认的全量安装主线书写。

本文实测宿主机资源:12 核 CPU、42 GB 内存(docker info 回显 CPUs=12),全栈启动后实测总内存占用 14.9 GiB,与官方 14 GB 下限吻合,余量适中。

2.2 安装 Docker Engine 与 Docker Compose

Ubuntu 22.04 官方仓库自带的 docker.io 版本较旧,推荐用 Docker 官方 apt 源安装。以下为 Ubuntu 22.04 上的完整实测过程:

# 安装依赖工具
apt-get update
apt-get install -y ca-certificates curl gnupg

实测回显(apt-get install 段,输出节选):

Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
The following NEW packages will be installed:
  ca-certificates curl gnupg
0 upgraded, 3 newly installed, 0 to remove and 0 not upgraded.
Setting up curl (7.81.0-1ubuntu1.21) ...
# 添加 Docker 官方 GPG 密钥与 apt 源( jammy = Ubuntu 22.04 代号)
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu jammy stable" > /etc/apt/sources.list.d/docker.list
apt-get update
# 安装 Docker Engine、CLI、containerd、Buildx 与 Compose 插件
apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

实测回显(退出码与版本验证):

exit=0
Docker version 29.9.1, build dfc520d
Docker Compose version v5.6.0
# 启动并设置开机自启(真实服务器上有 systemd 托管,两条命令默认即可生效)
systemctl enable --now docker

⚠️ 注意:systemctl enable --now docker 依赖 systemd,请在真实 Ubuntu 22.04 服务器(或带 systemd 的虚拟机)上执行;云主机与物理机默认满足。

验证安装结果:

docker version --format 'Docker: {{.Server.Version}}'
docker compose version

实测回显:

Docker: 29.8.1
Docker Compose version v5.5.1

💡 说明:本文安装 Sentry 的实测环境使用 Docker 29.8.1 与 Compose v5.5.1;apt 官方源安装到的是 29.9.1 与 v5.6.0。两者都远高于 Sentry 安装脚本的最低线(19.03.6 / 2.32.2),均可正常完成安装。Sentry 安装脚本启动时会打印实际检测到的版本,见第四章实测回显。

三、版本选型说明

3.1 self-hosted 版本获取

Sentry self-hosted 仓库与 Sentry 主程序按月发版,tag 与官方镜像版本一一对应。查询最新 release(无需登录,直接访问 GitHub API):

curl -s https://api.github.com/repos/getsentry/self-hosted/releases/latest | grep -E '"tag_name"|"published_at"'

实测回显(2026-10-16 查询):

  "tag_name": "26.10.0",
  "published_at": "2026-10-16T01:17:30Z",

再查最近的版本序列:

curl -s "https://api.github.com/repos/getsentry/self-hosted/tags?per_page=8" | grep '"name"'

实测回显:

    "name": "26.10.0",
    "name": "26.9.0",
    "name": "26.8.0",
    "name": "26.7.2",
    "name": "26.7.1",
    "name": "26.7.0",
    "name": "26.6.0",
    "name": "26.5.2",

3.2 选型建议

版本发布节奏适用建议
最新 tag(本文 26.10.0)每月一个 minor新装环境直接采用,功能与修复最全
上月 tag(26.9.0 等)滞后一个月生产升级窗口期临时使用
master 分支实时仅限开发调试,安装脚本默认会警告并建议跳过(--skip-commit-check)
对比项选最新 tag锁定上月 tag跟 master
稳定性官方已回归测试更保守不可控
功能最新差一个月最新半成品
升级频率每月按需每天

关键差异:self-hosted 发版即打包了对应的数据库迁移与组件镜像版本,跨多月升级需经安装脚本内建的逐版本迁移流程,因此新装选最新 tag、存量按月跟进是官方推荐路径。本文选用最新 stable 26.10.0。

四、方案 A(推荐):官方仓库在线安装

4.1 方案说明

从 GitHub 官方仓库 getsentry/self-hosted 检出指定版本,执行官方安装脚本 install.sh。脚本会自动完成:组件镜像拉取、数据卷创建、配置文件从样例生成、密钥生成、本地镜像构建、数据库迁移、Snuba/ClickHouse 初始化、GeoIP 库下载等全部初始化工作。适合可访问外网的服务器。

4.2 获取 self-hosted 仓库并检出 26.10.0

apt-get install -y git
git clone --depth 1 --branch 26.10.0 https://github.com/getsentry/self-hosted.git sentry
cd sentry
git log -1 --oneline

实测回显:

Note: switching to '5f84986651b3c4af1910e1af731d0132f5c7043d'.

You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by switching back to a branch.

5f84986 release: 26.10.0

检出后目录内容:

ls

实测回显:

AGENTS.md       codecov.yml  geoip      optional-modifications  sentry           symbolicator
CHANGELOG.md    cron         healthcheck  redis.conf           sentry-admin.sh  taskbroker
CONTRIBUTING.md docker-compose.yml  install   relay          scripts          unit-test.sh
LICENSE.md      get-compose-action  nginx.conf  sentry.conf.example.py  uv.lock      workstation
README.md       _integration-test   install.sh  pyproject.toml          sentry/

💡 说明:--depth 1 --branch 26.10.0 只拉取该 tag 的快照(数百 KB 级),比全量 clone 快得多。detached HEAD 提示属正常现象,升级时再 git fetch --tags && git checkout <新tag> 即可。

4.3 执行安装脚本

./install.sh --skip-user-creation --no-report-self-hosted-issues

参数说明:

  • --skip-user-creation:跳过交互式创建管理员,改为安装完成后用命令行创建(适合脚本化安装;不加此参数则脚本结束前会交互式询问邮箱/密码/是否超级用户)。
  • --no-report-self-hosted-issues:不向 sentry.io 上报本实例的运行错误(自托管实例默认不上报,显式声明更安心)。
  • 其余可用参数可用 ./install.sh --help 查看,实测帮助输出(输出节选):
Usage: ./install.sh [options]

Install Sentry with `docker|podman compose`.

Options:
 -h, --help             Show this message and exit.
 --minimize-downtime    EXPERIMENTAL: try to keep accepting events for as long
                          as possible while upgrading.
 --skip-commit-check    Skip the check for the latest commit when on the master
                          branch of a `self-hosted` Git working copy.
 --skip-user-creation   Skip the initial user creation prompt (ideal for non-
                                interactive installs).

脚本启动阶段实测回显(逐阶段进行,中间为镜像拉取与迁移耗时,全流程实测约 25 分钟):

▶ Parsing command line ...

▶ Detecting container engine ...
Detected container engine: docker

▶ Detecting Docker platform
Detected Docker platform is linux/amd64

▶ Initializing Docker|Podman Compose ...
docker compose --ansi never --env-file .env run --pull=never --rm

▶ Setting up error handling ...

▶ Checking for latest commit ...
skipped

▶ Checking minimum requirements ...
Found docker version 29.8.1
Found docker Compose version 5.5.1

后续阶段(grep -E "^▶" 安装日志 实测输出):

▶ Fetching and updating docker images ...
▶ Turning things off ...
▶ Creating volumes for persistent storage ...
▶ Ensuring files from examples ...
▶ Checking memcached backend ...
▶ Ensuring Relay credentials ...
▶ Generating secret key ...
▶ Building and tagging Docker images ...
▶ Migrating the SeaweedFS encryption key ...
▶ Ensuring proper PostgreSQL version ...
▶ Bootstrapping seaweedfs (node store)...
▶ Bootstrapping and migrating Snuba ...
▶ Bootstrapping seaweedfs (profiles)...
▶ Setting up / migrating database ...
▶ Migrating Postgres config to PGBouncer...
▶ Setting up GeoIP integration ...

安装成功收尾输出:

-----------------------------------------------------------------

You're all done! Run the following command to get Sentry running:

  docker compose up --wait

-----------------------------------------------------------------

⚠️ 排障实录:本文首次执行 install.sh 在 ▶ Building and tagging Docker images ... 阶段失败,报错关键行:

failed to solve: failed to fetch anonymous token: Get "https://auth.docker.io/token?scope=repository%3Aaltinity%2Fclickhouse-server%3Apull&service=registry.docker.io": dial tcp 45.77.186.255:443: connect: connection refused

原因:构建 ClickHouse 本地组件镜像时需要基于 altinity/clickhouse-server:25.8.28.10001.altinitystable 基础镜像,该基础镜像默认未被脚本预拉取,构建过程直连 Docker Hub 被网络策略拒绝。解决方法:先手动拉取缺失的基础镜像再重跑安装脚本(本文实测有效):

docker pull altinity/clickhouse-server:25.8.28.10001.altinitystable

实测回显:

docker.io/altinity/clickhouse-server:25.8.28.10001.altinitystable

然后重新执行 ./install.sh --skip-user-creation --no-report-self-hosted-issues,脚本会跳过已完成的阶段直接继续。若还有其他基础镜像拉取失败,同样先 docker pull <报错中的镜像名:tag> 再重跑即可。受限网络环境下,为 Docker 守护进程配置 HTTP 代理(/etc/systemd/system/docker.service.d/http-proxy.conf 中设置 HTTP_PROXY/HTTPS_PROXY 后 systemctl daemon-reload && systemctl restart docker)可一并解决。

⚠️ 注意:安装完成时若见到 Error setting up IP address geolocation. 提示,属 GeoIP 离线库下载失败,不影响核心功能(仅 IP 地理位置展示缺失),官方指引见 https://develop.sentry.dev/self-hosted/geolocation/ 。本文实测即出现该提示并确认栈正常启动,处理方式见第八章常见问题。

4.4 启动全栈服务

docker compose up --wait

该命令等待全部 53 个服务达到健康状态后退出。实测启动日志尾部(输出节选):

 Container sentry-self-hosted-post-process-forwarder-transactions-1 Healthy
 Container sentry-self-hosted-nginx-1 Healthy
 Container sentry-self-hosted-post-process-forwarder-issue-platform-1 Healthy
 Container sentry-self-hosted-snuba-api-1 Healthy

确认服务状态:

docker compose ps --format '{{.Service}}\t{{.Status}}' | head -12

实测回显(输出节选,共 53 行):

attachments-consumer    Up About a minute (healthy)
clickhouse      Up About a minute (healthy)
events-consumer Up About a minute (healthy)
ingest-feedback-events  Up About a minute (healthy)
ingest-monitors Up About a minute (healthy)
ingest-occurrences      Up About a minute (healthy)
kafka   Up About a minute (healthy)
launchpad-taskworker    Up 52 seconds (healthy)
memcached       Up About a minute (healthy)
metrics-consumer        Up About a minute (healthy)
nginx   Up 51 seconds (healthy)
pgbouncer       Up About a minute (healthy)

统计服务总数:

docker compose ps --format '{{.Service}}' | wc -l

实测回显:

53

4.5 创建管理员账号

docker compose run --rm -T web createuser --email admin@sentry.local --password q1w2e3r4 --superuser

实测回显(输出节选,前几行为正常的配置提示):

* Unknown config option found: 'spans.buffer.process-segments-task-rollout-rate'
* Unknown config option found: 'transaction-events.force-disable-internal-project'
Added to organization: sentry
User created: admin@sentry.local

💡 说明:--superuser 赋予管理员全部组织权限;安装脚本若未加 --skip-user-creation,此处会在交互式向导中完成同样的事情。账号已被自动加入初始化时创建的默认组织 sentry。

4.6 登录验证

浏览器访问 http://<服务器IP>:9000(端口由 .env 的 SENTRY_BIND 决定,默认 9000),用 admin@sentry.local / q1w2e3r4 登录即可进入仪表盘。命令行验证 Web 入口:

curl -I http://127.0.0.1:9000/auth/login/

实测回显:

HTTP/1.1 200 OK
Server: nginx
Date: Fri, 16 Oct 2026 15:42:10 GMT
Content-Type: text/html
Content-Length: 19578
Connection: keep-alive

API 层验证(未带凭证时应返回匿名 JSON):

curl -s http://127.0.0.1:9000/api/0/

实测回显:

{"version":"0","auth":null,"user":null}

创建项目(用于后续 SDK 接入验证,详见《Sentry 26.10.0 快速入门与集成示例》):

docker compose run --rm -T web createproject --name python-demo --platform python --organization sentry

实测回显(输出节选):

Created project:
  ID: 2
  Slug: python-demo

至此安装与验证全部完成。端口映射最终确认:

docker port sentry-self-hosted-nginx-1

实测回显:

80/tcp -> 0.0.0.0:9000
80/tcp -> [::]:9000

五、方案 B:受限网络/离线安装

5.1 方案说明

无法直连 GitHub / ghcr.io 的服务器,采用「能联网的中转机上准备全部物料 → 内网服务器还原」的方式:仓库用离线包传递,组件镜像用 docker save / docker load 传递,配置文件由安装脚本从样例生成(无需联网)。适合内网隔离的生产环境。

5.2 中转机准备物料

# 中转机:检出仓库并导出离线包
git clone --depth 1 --branch 26.10.0 https://github.com/getsentry/self-hosted.git sentry
cd sentry
# 先完整跑一遍 install.sh 令其拉齐全部组件镜像,然后导出镜像清单
docker compose --env-file .env config | grep "image:" | awk '{print $2}' | sort -u > /tmp/images.txt
cat /tmp/images.txt

实测回显(cat /tmp/images.txt,本文实测环境采集):

clickhouse-self-hosted-local
confluentinc/cp-kafka:7.6.14
edoburu/pgbouncer:v1.26.0-p0
ghcr.io/getsentry/launchpad:26.10.0
ghcr.io/getsentry/relay:26.10.0
ghcr.io/getsentry/sentry:26.10.0
ghcr.io/getsentry/snuba:26.10.0
ghcr.io/getsentry/symbolicator:26.10.0
ghcr.io/getsentry/taskbroker:26.10.0
ghcr.io/getsentry/uptime-checker:26.10.0
ghcr.io/getsentry/vroom:26.10.0
memcached:1.6.45-alpine
nginx:1.31.6-alpine
postgres:18.6-trixie
registry.gitlab.com/egos-tech/smtp
sentry-cleanup-self-hosted-local
sentry-self-hosted-local
valkey/valkey:8.1.10-alpine
# 逐个保存镜像为 tar(也可用一条循环脚本批量处理 /tmp/images.txt 清单)
while read -r img; do docker save "$img" -o "/tmp/imgs/$(echo "$img" | tr '/:' '__').tar"; done < /tmp/images.txt

将 sentry 目录(可先 tar czf sentry-26.10.0.tgz sentry)与全部镜像 tar 拷贝至内网服务器。

5.3 内网服务器还原安装

# 还原仓库与镜像
tar xzf sentry-26.10.0.tgz && cd sentry
while read -r img; do docker load -i "/tmp/imgs/$(echo "$img" | tr '/:' '__').tar"; done < /tmp/images.txt

# 预生成配置(脚本会从样例生成 .env / sentry/config.yml / sentry/sentry.conf.py,并完成迁移与初始化)
./install.sh --skip-user-creation --no-report-self-hosted-issues
docker compose up --wait

⚠️ 注意:install.sh 会按 .env 中的镜像版本变量(SENTRY_IMAGE、SNUBA_IMAGE 等)逐个核对本地镜像,缺失才会联网拉取。离线环境务必保证镜像清单导出与安装版本完全一致(同一 tag),否则脚本仍会尝试联网。若初始化阶段确需联网(如 GeoIP 库),可忽略其失败提示,不影响核心功能。

5.4 方案对比与选择建议

维度方案 A 在线安装方案 B 离线安装
版本拉取即最新 tag中转机锁定版本
网络要求需访问 GitHub、ghcr.io、Docker Hub内网服务器零外联
安装耗时约 25 分钟(含镜像拉取)传输耗时为主,安装约 10 分钟
适用云主机/有外网出口金融、政企内网

关键差异:两方案最终都收敛到同一套配置文件与同一组本地镜像,区别只在物料传输方式。可联网优先方案 A;内网隔离必须方案 B,且要在中转机上用同一版本完整跑一遍安装,确保镜像清单完整。

六、配置说明

安装脚本已从样例生成三份核心配置文件,安装后通常只需确认以下几项(逐项详解见《Sentry 26.10.0 配置参数详解》):

cat .env | grep -vE '^#|^$' | head -8

实测回显:

COMPOSE_PROJECT_NAME=sentry-self-hosted
COMPOSE_PROFILES=feature-complete
SENTRY_EVENT_RETENTION_DAYS=90
LAUNCHPAD_RPC_SHARED_SECRET=supersecret
SENTRY_BIND=9000
SENTRY_TASKWORKER_CONCURRENCY=4
SENTRY_IMAGE=ghcr.io/getsentry/sentry:26.10.0
SNUBA_IMAGE=ghcr.io/getsentry/snuba:26.10.0
  • SENTRY_BIND:对外端口,默认 9000。改为其他端口后需 docker compose up -d 重建接入层服务生效。
  • system.secret-key:位于 sentry/config.yml,安装时已自动生成为随机串(可用 docker compose run --rm -T web config generate-secret-key 重新生成,实测输出形如 dz^x+u8i3#&0mm5m%u44v=6@ja1cc_0&!lxcs_pl5oegu7k7&+),更换会使所有登录会话失效。
  • system.url-prefix:sentry/config.yml 中默认注释,配置后 Sentry 生成的事件链接、邮件链接将使用该地址,影响 DSN 展示形态。

任何配置修改后统一用以下命令滚动生效并验证:

docker compose up -d
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:9000/auth/login/

实测回显:

200

七、常见问题(FAQ)

Q1:安装脚本提示内存或 CPU 不达标怎么办? 安装脚本按 14000 MB 内存 / 4 核(全量)实测校验,不满足直接退出。解决办法:按第二章表格扩容;资源确实紧张时在 .env 中设 COMPOSE_PROFILES=errors-only 走仅错误监控模式(下限 7000 MB / 2 核),再重跑安装。

Q2:install.sh 在 Building and tagging Docker images 阶段报 failed to fetch anonymous token 或镜像拉取失败? 见 4.3 排障实录:先 docker pull <报错镜像>(本文实测为 altinity/clickhouse-server:25.8.28.10001.altinitystable),受限网络为 Docker 守护进程配置代理后 systemctl restart docker,再重跑安装脚本。脚本支持断点续跑,已完成阶段自动跳过。

Q3:安装完成提示 Error setting up IP address geolocation.? GeoIP 离线库(MaxMind GeoLite2)下载失败所致,仅影响事件中的 IP 地理位置展示,不影响错误收集。按官方指引(https://develop.sentry.dev/self-hosted/geolocation/ )手动放置 GeoLite2-City.mmdb 到 geoip/ 目录后重跑 ./install.sh 即可。

Q4:9000 端口被占用? 修改 .env 中 SENTRY_BIND=9000 为空闲端口(本文实测改为 9001 后 docker port 确认映射变为 80/tcp -> 0.0.0.0:9001,curl http://127.0.0.1:9001/auth/login/ 返回 200),再 docker compose up -d 生效。

Q5:docker compose up --wait 卡在某个服务不健康? 先 docker compose ps 找到非 healthy 服务,再 docker compose logs --tail=50 <服务名> 看具体报错。常见原因是内存不足导致 ClickHouse / Kafka 被内核 OOM 杀掉(dmesg | grep -i oom 可确认),扩容后 docker compose up -d 恢复。

Q6:升级后配置文件被覆盖怎么办? install.sh 自动更新配置时默认会保留手工修改;如使用 --apply-automatic-config-updates,建议将自定义改动放在 .env.custom 或用 git diff sentry/config.yml 自查后再确认。

八、卸载与清理

完全卸载(删除全部服务、网络与数据卷,数据不可恢复,务必先备份,备份方法见《Sentry 26.10.0 进阶实战与运维》):

cd /root/sentry
docker compose down --volumes --remove-orphans

仅停止服务、保留数据卷(便于下次恢复,实测重启后事件与项目数据完整保留):

docker compose down
docker compose up -d

实测(down 后重新 up,等待约 1 分钟恢复健康,登录页与历史数据均可访问):

web-after-restart HTTP 200

删除镜像与残留:

docker image prune -af
rm -rf /root/sentry

九、参考链接