Sentry 26.10.0 Docker Compose 部署指南

目标：读懂并掌握 Sentry self-hosted 26.10.0 官方 Docker Compose 编排的结构——53 个服务分别承担什么职责、暴露哪些端口、数据落在哪些数据卷、实际消耗多少资源，以及如何用环境变量控制这套编排。本文所有数字（服务数、端口、卷、内存、磁盘）均来自 26.10.0 实测环境的真实采集。

一、环境信息

• 操作系统：Ubuntu 22.04（x86_64）
• Sentry self-hosted：26.10.0（仓库 tag 26.10.0，commit 5f84986）
• Docker Engine：29.8.1，Docker Compose：v5.5.1
• 编排文件：self-hosted 仓库根目录 docker-compose.yml（单文件定义全部 53 个服务）
• 项目名：sentry-self-hosted（.env 中 COMPOSE_PROJECT_NAME，所有服务、数据卷、网络以此为前缀）
• 实测运行状态：53 个服务全部 healthy（docker compose ps 统计）
• 管理员账号：admin@sentry.local / q1w2e3r4（本文演示账号）

💡 说明：Sentry 的 Docker Compose 不是「单机玩具」，它本身就是官方唯一的生产部署形态。理解这份编排文件，等于理解 Sentry 的完整运行架构：数据从 nginx/relay 接入，经 Kafka 消费链落进 ClickHouse（事件库）与 PostgreSQL（元数据库），后台由 taskbroker/各消费器异步处理。

二、镜像选型说明

self-hosted 26.10.0 编排引用的组件镜像全部为固定版本（.env 中以变量声明），初装实测拉取的镜像清单如下（docker images 输出）：

关键差异：.env 中每个镜像都有独立版本变量（SENTRY_IMAGE、SNUBA_IMAGE 等），官方发版时会同步更新全部变量保持组合兼容，自行改动需自行承担联调验证。

三、前置条件

• 已按《Sentry 26.10.0 Ubuntu 22.04 安装指南》安装 Docker Engine 与 Docker Compose。
• 硬件满足：14 GB 内存 / 4 核（errors-only 模式 7 GB / 2 核，见第十章）。
• 磁盘可用空间 50 GB 以上（初装组件镜像约 8 GB + 数据卷约 110 MB，随事件量增长）。
• 服务器可访问 GitHub 与 ghcr.io（或按安装指南方案 B 先备齐镜像）。

四、部署步骤

部署入口与安装指南一致，这里给出面向编排管理的最小序列（详细安装排障见安装指南第四章）：

git clone --depth 1 --branch 26.10.0 https://github.com/getsentry/self-hosted.git sentry
cd sentry
./install.sh --skip-user-creation --no-report-self-hosted-issues
docker compose up --wait

实测启动完成状态：

docker compose ps --format '{{.Service}}' | wc -l
docker compose ps | grep -c "Up"

实测回显：

53
53

五、服务组成详解

26.10.0 的 docker-compose.yml 共定义 53 个服务，全部为「只暴露内部网络、仅 nginx 对外」的结构。按职责分类如下（实测 docker compose config --services 全量清单）：

5.1 接入层（用户流量与事件入口）

5.2 存储层（基础设施）

5.3 Snuba 数据流系列（14 个）

5.4 事件摄取消费器（7 个）

5.5 后台处理链（5 个）

5.6 任务与调度（3 个）

5.7 辅助与维护（5 个）

5.8 清理任务（3 个）

💡 说明：以上分类合计即 53 个服务。docker compose config --services | sort 输出（实测）： attachments-consumer clickhouse events-consumer ingest-feedback-events ingest-monitors ingest-occurrences kafka launchpad-taskworker memcached metrics-consumer monitors-clock-tasks monitors-clock-tick nginx pgbouncer post-process-forwarder-errors post-process-forwarder-issue-platform post-process-forwarder-transactions postgres process-spans redis relay seaweedfs sentry-cleanup smtp snuba-api snuba-eap-items-consumer snuba-errors-consumer snuba-group-attributes-consumer snuba-issue-occurrence-consumer snuba-metrics-consumer snuba-outcomes-accepted-consumer snuba-outcomes-billing-consumer snuba-outcomes-consumer snuba-profiling-functions-consumer snuba-profiling-profile-chunks-consumer snuba-profiling-profiles-consumer snuba-replacer snuba-replays-consumer snuba-subscription-consumer-eap-items snuba-subscription-consumer-events snuba-subscription-consumer-metrics snuba-subscription-consumer-transactions snuba-transactions-consumer symbolicator symbolicator-cleanup taskbroker taskscheduler taskworker transactions-consumer uptime-checker uptime-results vroom web

⚠️ 注意：26.10.0 已没有名为 worker 的服务（旧版后台任务服务）。重启后台任务要用 taskworker/taskbroker/taskscheduler，写惯老版本运维脚本的同学需要更新命令（实测 docker compose restart worker 报错 no such service: worker）。

六、端口说明

6.1 对外端口

整个编排只发布一个对外端口（nginx），其余 52 个服务全部仅在内网互通：

docker port sentry-self-hosted-nginx-1

实测回显：

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

nginx 把宿主机 9000 端口映射到其 80 端口，映射规则写在 docker-compose.yml："${SENTRY_BIND}:80"。

6.2 内部端口速查（实测 compose 配置）

6.3 修改对外端口实测

sed -i 's/^SENTRY_BIND=9000/SENTRY_BIND=9001/' .env
docker compose up -d
docker port sentry-self-hosted-nginx-1
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:9001/auth/login/

实测回显：

 Container sentry-self-hosted-nginx-1  Recreate
 Container sentry-self-hosted-nginx-1  Started
80/tcp -> 0.0.0.0:9001
80/tcp -> [::]:9001
200

改回 SENTRY_BIND=9000 再执行 docker compose up -d 即还原（实测同样只重建 nginx，秒级完成）。

七、数据卷说明

7.1 数据卷清单

编排共声明 16 个数据卷（实测 docker volume ls），前缀均为项目名 sentry-self-hosted_：

7.2 初装磁盘占用实测

du -sh /var/lib/docker/volumes/sentry-self-hosted_* | sort -rh | head -8

实测回显（初装完成后约 15 分钟，已写入少量测试事件）：

104.2M  /var/lib/docker/volumes/sentry-self-hosted_postgres
5.2M    /var/lib/docker/volumes/sentry-self-hosted_clickhouse
2.9M    /var/lib/docker/volumes/sentry-self-hosted_taskbroker
2.2M    /var/lib/docker/volumes/sentry-self-hosted_kafka
276.4M  /var/lib/docker/volumes/sentry-self-hosted_vroom
1.5M    /var/lib/docker/volumes/sentry-self-hosted_symbolicator
1.4M    /var/lib/docker/volumes/sentry-self-hosted_seaweedfs
1.1M    /var/lib/docker/volumes/sentry-self-hosted_sentry-data

初装总体很小（约 400 MB 级），磁盘大头在组件镜像（约 8 GB）与后续事件增长量（ClickHouse/Kafka/SeaweedFS）。

7.3 备份视角

• 必备份卷：sentry-postgres（全部元数据）、sentry-clickhouse、sentry-kafka、sentry-seaweedfs（原始事件）。
• PostgreSQL 建议用 pg_dump 逻辑备份而非直接拷贝卷（实例运行中拷贝数据目录有崩溃风险），方法见《Sentry 26.10.0 进阶实战与运维》。

八、资源要求与实测占用

8.1 官方资源校验线

install.sh 实测校验（不达标直接退出）：

8.2 实测内存占用

12 核 / 42 GB 内存宿主机，全栈稳定运行后 docker stats --no-stream 实测（内存占用前 15 名）：

sentry-self-hosted-taskworker-1         1.337GiB / 31.42GiB   1.51%
sentry-self-hosted-web-1                927.6MiB / 31.42GiB   0.75%
sentry-self-hosted-kafka-1              606.1MiB / 31.42GiB   0.62%
sentry-self-hosted-clickhouse-1         272.4MiB / 31.42GiB   0.68%
sentry-self-hosted-postgres-1           162.1MiB / 31.42GiB   0.00%
sentry-self-hosted-vroom-1              134.9MiB / 31.42GiB   0.75%
sentry-self-hosted-snuba-transactions-consumer-1  87.2MiB / 31.42GiB  0.14%
sentry-self-hosted-snuba-api-1          82.5MiB / 31.42GiB    0.11%
sentry-self-hosted-relay-1              62.9MiB / 31.42GiB    0.05%
sentry-self-hosted-snuba-subscription-consumer-transactions-1  54.6MiB  0.14%
sentry-self-hosted-uptime-checker-1     53.9MiB / 31.42GiB    0.10%
sentry-self-hosted-snuba-subscription-consumer-eap-items-1  49.8MiB  0.13%
sentry-self-hosted-ingest-monitors-1    49.1MiB / 31.42GiB    0.13%
sentry-self-hosted-snuba-errors-consumer-1  48.7MiB / 31.42GiB  0.16%
sentry-self-hosted-taskbroker-1         46.6MiB / 31.42GiB    0.04%

53 个服务合计实测 14.9 GiB——与官方 14 GB 下限吻合，即官方要求是按实际占用反推的。规划生产资源时建议至少 16 GB 内存留出增长空间。

8.3 各档资源配置建议

九、环境变量（.env）逐项说明

安装脚本从样例生成的 .env（实测内容）：

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
RELAY_IMAGE=ghcr.io/getsentry/relay:26.10.0
SYMBOLICATOR_IMAGE=ghcr.io/getsentry/symbolicator:26.10.0
TASKBROKER_IMAGE=ghcr.io/getsentry/taskbroker:26.10.0
VROOM_IMAGE=ghcr.io/getsentry/vroom:26.10.0
UPTIME_CHECKER_IMAGE=ghcr.io/getsentry/uptime-checker:26.10.0
LAUNCHPAD_IMAGE=ghcr.io/getsentry/launchpad:26.10.0
HEALTHCHECK_INTERVAL=60s
HEALTHCHECK_TIMEOUT=10s
HEALTHCHECK_RETRIES=10
HEALTHCHECK_START_PERIOD=40s
SENTRY_KAFKA_MAX_POLL_INTERVAL_MS=120000
SENTRY_MAIL_HOST=
STATSD_ADDR=

逐项说明：

十、配置文件挂载与功能档位

10.1 挂载进服务的数据

docker-compose.yml 为 web/taskworker 等服务挂载了仓库内 5 个目录/文件，编排与配置解耦：

10.2 errors-only 功能档位

资源受限或只需要错误追踪时，编辑 .env：

COMPOSE_PROFILES=errors-only

然后重新拉起编排。效果（官方设计 + 实测校验脚本数据）：裁掉 profiling（vroom）、Uptime（uptime-checker/uptime-results）、monitors 时钟等非错误链路服务，服务数量大幅减少，内存下限从 14 GB 降到 7 GB。与全量模式的对比见第二章与第八章。

十一、常用编排命令

cd /root/sentry
docker compose ps                     # 查看全部服务状态
docker compose logs --tail=50 web     # 看某个服务最近日志
docker compose logs -f taskworker     # 实时跟踪后台任务日志
docker compose restart web            # 重启单服务（依赖 nginx 会一并重启）
docker compose stop                   # 全部停止（保留数据卷）
docker compose up -d                  # 全部启动/应用配置变更
docker compose down                   # 停止并删除网络（数据卷保留）
docker compose down --volumes         # 彻底删除（含数据卷，不可恢复！）

实测 docker compose restart web 回显（输出节选）：

 Container sentry-self-hosted-web-1  Restarting
 Container sentry-self-hosted-web-1  Started
 Container sentry-self-hosted-nginx-1  Restarting
 Container sentry-self-hosted-nginx-1  Started

实测 down 后 up -d 重启（输出节选）：

===DOWN===
 Container sentry-self-hosted-symbolicator-1 Removed
 Network sentry-self-hosted_default Removing
 Network sentry-self-hosted_default Removed
===UP===
 Container sentry-self-hosted-nginx-1 Starting
 Container sentry-self-hosted-nginx-1 Started

重启后验证数据完好（实测）：

web-after-restart HTTP 200
groups-still: 4

十二、常见问题（FAQ）

Q1：docker compose restart worker 报 no such service: worker？ 26.10.0 后台任务架构改为 taskbroker/taskworker/taskscheduler，老版 worker 服务已移除。按职责分别重启 taskworker、taskbroker、taskscheduler 或各 ingest-*/post-process-forwarder-* 服务。

Q2：为什么只有 9000 一个对外端口？需要暴露 Kafka/ClickHouse 给外部吗？ 不需要，也不建议。事件上报与 UI 都走 nginx 入口；Kafka/ClickHouse 是内部数据管道，直接暴露有安全风险。如果要做集群化拆分，官方部署形态仍以单 compose 为基线，多节点需自行拆分网络规划。

Q3：内存不够，能不能只跑一部分服务？ 可以，用 errors-only 档位（COMPOSE_PROFILES=errors-only），下限 7 GB。不建议手工注释服务——会导致事件管线断链且升级时合并困难。

Q4：某服务一直 unhealthy 怎么定位？

docker compose ps | grep -v healthy
docker compose logs --tail=100 <服务名>

常见原因：内存不足被 OOM（dmesg | grep -i oom）、Kafka 未就绪导致消费器反复重连（启动初期属正常，等健康检查通过即可）。

Q5：改了 .env / config.yml 后没生效？ .env 改动需 docker compose up -d（部分变量如镜像 tag 会触发重建）；sentry/config.yml 与 sentry/sentry.conf.py 是挂载进服务进程的，需 docker compose restart web taskworker（或涉及到的服务）重载进程才生效。

十三、参考链接

• Sentry 官网：https://sentry.io
• self-hosted 官方仓库：https://github.com/getsentry/self-hosted
• 编排文件（docker-compose.yml）：https://github.com/getsentry/self-hosted/blob/master/docker-compose.yml
• 官方部署文档：https://develop.sentry.dev/self-hosted/
• errors-only 模式说明：https://develop.sentry.dev/self-hosted/optional-features/errors-only/
• Relay 文档：https://docs.sentry.io/product/relay/