Sentry自托管部署实战：从资源规划到告警运维的完整指南

1. 为什么要把 Sentry 搬回自己服务器1.1 数据合规和成本这笔账越算越明白先说结论如果你还在犹豫直接用官网云服务不香吗那这篇文章大概率不适合你。真正让人下定决心自托管的原因通常是这几类情况叠加数据不出内网公司的业务日志里可能带用户手机号、订单号、内部系统 IP。用 SaaS 方案意味着这些数据默认要过一遍第三方平台的链路。本地部署后所有事件数据只落在我自己的服务器上审计和合规这边基本没啥可解释的。事件量大的成本账Sentry 云版按 event错误事件和 performance性能采样单位计费。项目多、请求量大之后一个月几千上万块的费用是常态。自托管版本免费代价是你得自己养这套基础设施。二次定制空间云版只能调开关自托管可以改上报协议、接内部登录体系、甚至改告警聚合逻辑能做的事情完全不是一个量级。如果你要建的是团队内部统一错误监控并且团队里至少有一两个人愿意折腾 Docker 和 Linux那自托管确实是值得投入的方向。官方为此准备了一个专门的仓库getsentry/self-hosted里面是一套完整的 Docker Compose 编排我这次踩坑的主体就是它。1.2 官方自托管方案的总体面貌别看 Sentry 核心功能只是收集异常聚合展示它的工程化程度相当夸张。用官方编排方案启动之后你会看到一堆服务在跑Web 前端、Worker 异步任务、Cron 定时任务、Relay 边缘网关、Kafka 消息队列、ClickHouse 分析数据库、PostgreSQL 主库、Redis 缓存、Zookeeper 协调器、Snuba 查询层、Symbolicator 符号化服务……我数了下正常启动后容器大概在 20 个左右。这一整套其实跟一套大型分布式系统没什么区别。好处是官方帮你编排好了依赖install.sh脚本会自动执行数据库迁移和初始化坏处是一旦某个底层服务不稳定排查链路就会变得很酸爽。接下来分享的踩坑记录基本就是在这 20 个容器之间来回折腾攒下来的。2. 部署前的准备资源和版本这两个坑基本决定了成败2.1 机器配置红线到底要开多高我最初想省成本用了一台 2 核 4G 的旧服务器结果安装脚本跑到一半Kafka 和 ClickHouse 直接 OOM 被杀容器重启成死循环。后来换了 4 核 16G 的机器才顺畅跑起来。按照官方文档最小推荐是 8GB 内存、4 核 CPU但我实际体验下来16G 内存才是舒服的起点。理由很简单JVM 系的 Kafka 和 Zookeeper 本身就要吃掉几个 GClickHouse 在内存里做列式聚合又很吃资源再加上 Web 和 Worker 各需要 1-2G4G 内存连部署过程都撑不过去。磁盘方面官方建议 30GB 起步这个数我建议直接再加一倍。因为 ClickHouse 一张原始事件表一天就能长几百 MB如果保留周期设成 90 天几个月之后磁盘会非常紧张。我的建议是资源项最低要求推荐配置内存8GB16GB 以上CPU4 核4-8 核磁盘30GB SSD100GB SSD网络内网即可千兆内网对了如果你的机器物理内存不够一定记得先准备 Swap 分区。我在 4G 机器上就是因为没设 Swap安装期间进程直接被 OOM Killer 干掉报错信息只有一堆退出状态码 137当时差点以为是镜像拉坏了。2.2 端口规划与反向代理预留Sentry 的 Web 服务默认监听9000端口这也是安装完成后唯一需要对外暴露的入口。我遇到的实际问题是服务器上之前有一个旧的监控面板占着 9000导致安装脚本启动sentry-web时容器反复重启。排查了一大圈才发现是端口冲突——所以部署前务必先查一次ss -lntp | grep -E :9000|:90019001 是 Relay 的默认端口如果计划以后用外部 Relay 实例也需要留出来。另外如果你和我一样用 Nginx 做反向代理建议在部署前就把域名和服务器的关联想好。Sentry 对自定义域名处理比较敏感这个后面会在环境变量部分细说。2.3 时间同步和 Docker 版本这两个小点最容易被忽略Kafka、ClickHouse、Snuba 全部强依赖主机时钟一致性。我测试环境一开始主机时间漂了十几秒导致事件写入后时间轴错乱、告警触发时间对不上。后来给宿主机配了自动时间同步NTP 客户端才彻底解决。这不是官方文档里会高亮强调的内容但分布式系统的同学应该秒懂。Docker 方面官方编排已经迁移到了Docker Compose v2语法所以机器上的docker compose命令必须是新版。检查方式很简单docker compose version如果提示找不到命令或者版本太低先升级 Docker 本体和 Compose Plugin再去拉 Sentry 的仓库。我在旧机器上直接踩了docker-compose和docker compose命令混用的坑导致install.sh里解析命令时直接报错退出。3. 安装脚本执行的每一步和我遇到的第一轮报错3.1 拉代码与执行 install.sh整体流程非常简单git clone https://github.com/getsentry/self-hosted.git cd self-hosted sudo ./install.sh但我强烈建议不要直接用master分支跑生产而是 checkout 到官方发布的最新稳定 tag。我实际操作时用了当时的24.x系列 release tag这样镜像和脚本之间的兼容性最有保证。install.sh跑起来之后交互式提问会比想象中多。我记得安装过程中至少要确认三件事是否创建超级管理员账号我看文档说可以跳过但实际建议直接创建反正就填一次邮箱和密码是否需要启用新的 LLM 相关功能对大部分团队没用直接关闭是否允许访问 Beacon 上报安装实例信息这是回传给 Sentry 官方的匿名统计内网环境建议关掉拿到问题清单之后先说结论这个脚本表面上在装容器背后其实是把整个系统初始化了。3.2 install.sh 后台到底在做什么这个脚本不是简单地拉镜像然后docker compose up。它内部按顺序做了这几件关键事生成了.env配置文件里面有大量SENTRY_开头的环境变量。拉取所有 Docker 镜像此时 Docker Hub 的网络压力会很大。启动依赖的底层服务Postgres、Redis、ClickHouse、Kafka 等。执行 Sentry 自身的数据库迁移类似 Django framework 的 migrate。初始化 Snuba 的 schema这一步失败率极高尤其在内存不够时。我后来回过头看install.sh之所以容易显得卡死其实是两个原因一是镜像体积大一个完整的镜像包可能超过 10GB二是在初始化底层库时 CPU 占用特别高日志输出也不一定实时刷新。所以看到脚本长时间没反应别急着 CtrlC先docker stats看下 CPU 和内存是否还在跳动。3.3 我踩过的三个安装期错误第一个错误我已经提过了内存不足导致容器 OOM现象是一堆服务反复重启install.sh最后报错失败。解决办法不是降低配置而是老老实实加 Swapfallocate -l 8G /swapfile chmod 600 /swapfile mkswap /swapfile swapon /swapfile第二个错误是 Docker 版本问题install.sh内部用的是docker compose up -d这种新语法而我之前安装的docker-compose是独立的 Python 工具版本在 1.29根本不认识新的配置文件。升级完 Docker Compose Plugin 之后重新执行问题消失。第三个错误发生在初始化期间报错信息类似clickhouse server not ready。这个其实不是 ClickHouse 真挂了而是检查脚本太激进在 ClickHouse 还没完成启动时就去探测端口。这类假性失败重跑一次通常能过如果多次失败就去查对应容器的真实日志docker compose logs clickhouse | tail -n 1003.4 建立第一个管理员账号安装成功后你可能会疑惑从哪里登录。直接在浏览器访问http://服务器IP:9000就能看到 Sentry 的登录页。如果你在安装时选择了跳过超级管理员创建那就需要手动用命令创建docker compose run --rm sentry createuser \ --email adminexample.com \ --password 强密码 \ --superuser这里的坑在于docker compose run会临时启动一个容器如果数据库还没完全初始化命令会直接连接失败。所以稳妥的顺序是先docker compose ps确认核心服务都 healthy再操作账号。4. 服务全启动之后的健康检查与细节修正4.1 哪些容器才是真的健康的登录之前先别急着狂欢。我是用下面这条命令把所有容器状态拉出来看的docker compose ps正常状态下sentry-web、sentry-worker、sentry-cron、sentry-relay、snuba-consumer等核心服务都应该显示Up同时Health字段是healthy。如果有个别服务显示unhealthy或者Restarting建议按这个顺序排查先看该容器日志docker compose logs 服务名 --tail 200再确认依赖服务是否健康比如snuba依赖clickhouse和redis最后检查系统资源free -h看内存是否又不够了我最常被坑的是sentry-worker。这个服务负责处理异步任务比如事件预处理、告警发送、网页截图等。它短暂不健康时前端页面照样能打开但新的错误事件可能一直处于待处理状态不会出现在 issue 列表里。所以判断 Sentry 是否真能用了一定要确认 worker 容器处于健康状态。4.2 用环境变量把多余功能收紧官方.env文件默认了很多配置但其中几个我强烈建议调整。最核心的是SENTRY_HOST它决定了页面链接、邮件链接里显示的主机名。如果保持默认值收到的告警邮件里点开的链接会是一个乱七八糟的无效地址。我的.env关键配置长这样SENTRY_HOSTsentry.example.com SENTRY_EVENT_RETENTION_DAYS30 SENTRY_BEACONFalse SENTRY_SINGLE_ORGANIZATIONfalse这里有个容易忽略的细节改.env之后必须执行docker compose down再docker compose up -d重新创建容器不能指望docker compose restart自动加载新环境变量。我第一次就因为只 restart 了 web 容器导致配置半天没生效白查了一堆日志。关于SENTRY_SINGLE_ORGANIZATION默认是true意思是整个实例只有一个组织。如果你的团队以后要拆多个部门、多个项目建议提前设成false否则后面在界面上新增组织会很别扭。4.3 创建项目与获取 DSN登录之后的操作在 Web 界面上就能完成逻辑也很清晰先创建项目选择对应的语言/框架模板然后在项目的设置页面拿到 DSN 字符串。DSN 长这样http://public_key主机名:9000/项目ID这个 DSN 就是应用上报事件的地址。我之前用 SaaS 版的时候DSN 总是带着一段看起来很神秘的 key到了自托管才发现它其实就是明文的基础认证。需要强调的是DSN 里的 public key 是敏感信息把前端页面的 DSN 写死在 JS 里虽然问题不大但后端项目的 DSN 建议放到环境变量和密钥管理里别直接提交到仓库。5. 接入 Python 项目的 SDK 实录5.1 最小植入两行代码团队里有一个 Django 项目接入过程其实非常轻量。安装 SDKpip install sentry-sdk然后在项目的初始化配置里加两行import sentry_sdk from sentry_sdk.integrations.django import DjangoIntegration sentry_sdk.init( dsnhttp://public_keysentry.example.com:9000/project_id, integrations[DjangoIntegration()], traces_sample_rate0.2, )注意traces_sample_rate是性能监控的采样率。对内部系统来说0.2 已经足够看出来整体性能趋势如果业务低峰期想看得更细也可以临时调到 1.0但注意这会明显增加事件量和存储开销。我第一次接入后总觉得没反应后来才发现是端口问题。Django 服务在容器内访问 Sentry 时不能用宿主机 IP 加 9000而要用内网域名或者直接把 Sentry 服务加入同一个 Docker 网络。这个网络问题如果没想明白很容易以为是 SDK 配错了。5.2 验证事件与速率限制SDK 配好之后最直接的验证方式是故意触发一个异常try: 1 / 0 except ZeroDivisionError as e: sentry_sdk.capture_exception(e)我通常还会再跑一次sentry_sdk.capture_message(test message from local)因为 message 类型的事件可以绕过部分异常过滤逻辑能更干净地验证网络链路是否通。验证完事件上报后强烈建议去项目设置里看一眼速率限制Rate Limiting。自托管默认不限制事件量这既是个好消息也是个坏消息——某个高并发接口一旦出问题短时间内可能刷出几万条重复事件把 ClickHouse 写入打爆。我给关键项目设置的策略是默认项目允许每分钟 500 个事件然后在告警规则里按条件单独放行更高频的错误。5.3 发布号与源代码映射如果是纯后端项目异常堆栈一般来说已经很可读了但前端项目就必须考虑源码映射Source Map的问题。我在接入一个 Vite 构建的前端项目时遇到的核心痛点是错误定位精确到源码行和隐藏真实源码之间的取舍。方案是配合发布号release把 Source Map 上传到 Sentry。本地我的做法是构建时生成带 hash 的 Source Map 文件安装sentry/cli在 CI 脚本里用下面命令上传sentry-cli releases new v1.0.0 sentry-cli releases files v1.0.0 upload-sourcemaps ./dist \ --url-prefix ~/assets/js这一步最容易踩的坑是 URL prefix 不匹配。Vite 默认生成的资源路径带/assets/如果你上传时写的 prefix 和线上实际加载路径不一致Sentry 拿到 Source Map 也匹配不上界面上会出现 No matching source map 的提示。建议先开浏览器 DevTools 看线上资源的绝对路径再决定--url-prefix怎么填。6. 告警链路的折腾从 SMTP 到 IM 机器人6.1 服务器邮件配置的细节Sentry 自托管的邮件配置都在.env里。我配置的参考值如下SENTRY_SYSTEM_EMAILno-replysentry.example.com SENTRY_MAIL_HOSTsmtp.example.com SENTRY_MAIL_PORT465 SENTRY_MAIL_USERmailuserexample.com SENTRY_MAIL_PASSWORDmailpassword SENTRY_MAIL_USE_TLStrue这里面有几个很容易被忽略的点SENTRY_SYSTEM_EMAIL和前面说的SENTRY_HOST是配合使用的。邮件里所有链接都会组装成https://SENTRY_HOST/...如果主机名不对收件人点开链接就是 404。端口和是否启用 TLS 要跟你的邮件服务商对齐。很多公司的内部 SMTP 走的是 25 端口且不带认证这种时候就不要强上 TLS。配置改完同样要重新创建容器才生效。我测试时还发现即使邮件配置正确Sentry 默认的告警邮件也可能因为收件人邮箱域名校验被拒。如果收件人是其他邮件系统建议在项目管理里给成员绑定真实邮箱后再测。6.2 告警规则和通知渠道别被默认规则骗了Sentry 项目默认会创建几条告警规则但真正生产环境根本不够用。我在项目设置里新增的规则比较实用新问题创建后 5 分钟内没有分配处理人触发未分配提醒同一个 issue 在 1 小时内连续出现超过 10 次触发高频率提醒特定错误级别如 FATAL出现时立即通知通知渠道方面邮件只是底线。比较实际的做法是走 Webhook 把告警推到团队内部沟通软件。Sentry 自带一个通用的 Webhook 集成Webhook 官网叫 Plugin 或者 Webhooks Integration我配置了一个简单的 handler 把告警消息 POST 到内部机器人地址效果很稳定。这里有个小坑Sentry 的 Webhook POST 请求带的是签名后的 JSON如果你的接收端没有校验请求来源很容易收到一堆伪造告警。建议自定义 Webhook 接收脚本时至少校验一下来源 IP 和固定的 Header。7. 上线一周后的运维与升级笔记7.1 日常体检看日志、看容器、看资源自托管 Sentry 不是装完就一劳永逸我上线后第一周基本每天会花几分钟做三件事docker compose ps docker compose stats docker compose logs --tail100 sentry-webdocker compose ps用来确认有没有容器异常重启stats可以直观看到哪些服务在吃资源logs则适合发现一些不影响服务但值得注意的警告。另外我习惯用一个简单的定时任务把sentry-web、sentry-worker、snuba-consumer的关键日志片段归档到本地文件万一后面出问题需要复盘不至于翻 Docker 的滚动日志翻到怀疑人生。7.2 数据保留与清理前面提到我把SENTRY_EVENT_RETENTION_DAYS设成了 30 天但实际上已经写入 ClickHouse 的历史数据不会因为这个变量自动清除。要真正回收磁盘空间需要手动跑sentry cleanup。我执行的命令是docker compose run --rm sentry cleanup --days 30这条命令这次实测跑了几十分钟期间会影响一部分后台查询建议放在低峰期执行。如果你完全不在乎历史数据更粗暴的方式是直接清空 ClickHouse 里的事件表但我不推荐因为那样会把告警历史、性能监控记录也一起抹掉。7.3 温和的升级路径Sentry 的迭代速度非常快官方推荐升级方式很简单在self-hosted仓库目录里git pull拉最新代码然后重新执行install.sh。但我个人建议加两个参数git pull ./install.sh --skip-user-create --minimize-downtime--skip-user-create避免升级过程中反复创建管理员账号--minimize-downtime则会让升级过程尽量不中断已有服务。即使这样升级前我也强烈建议先把当前环境完整快照或备份做好。有一次我直接跟着 master 走结果升级到一半报数据库迁移冲突查下来是某个中间版本遗留下来的 schema 问题。从那以后我就记住了升级前先看官方仓库的 Release Notes跨大版本升级前先查是否有特殊的迁移说明而不是无脑git pull。如果可能优先切到官方推荐的稳定 tag而不是追赶最新的 master。7.4 备份事件数据和应用数据的差异备份备份策略要区分两大类数据。PostgreSQL 里放的是组织、项目、用户、告警规则等结构化数据这类数据量小但很关键直接用 Postgres 的 dump 工具备份即可docker compose exec postgres pg_dump -U postgres sentry sentry_pg_$(date %F).sqlClickHouse 里是原始错误事件和性能数据数据量大且是典型的时间序列数据。备份它的成本很高我个人的建议是如果保留周期只设 30 天其实没必要做完整的 ClickHouse 冷备只需保证磁盘不爆即可真正需要长期留存的异常样本可以靠告警规则的 Webhook 在事件发生时同步到内部知识库或者对象存储里。这样既控制了成本又留住了有价值的异常样本。8. 一些只有跑过一段时间才知道的经验8.1 入口地址别用裸 IP如果只能给一条部署建议我会说哪怕只是内部系统也尽量给它一个正式的域名或者长期固定的内网别名。裸 IP 加端口作为入口短时间用没问题但后面你一定会遇到这些情况换成 HTTPS、接公司统一登录、发给外部协作方演示每个场景都会让你重新改一遍SENTRY_HOST和相关配置。与其反复折腾不如一开始就把内部域名解析好。同理反向代理上的 WebSocket 支持也是必选项因为前端的实时刷新和部分交互依赖它。8.2 重装是最快的试错方式这套系统组件的状态太多如果某一次升级或改动后出现了诡异的全局故障与其花几个小时追踪某一条依赖链不如在保留数据卷的前提下做个干净的重装docker compose down sudo ./install.sh我不是鼓励出问题就无脑重装而是想表达self-hosted仓库的设计本身就倾向于幂等修复很多问题的修复方式就是让install.sh重新跑一遍。我后来调整配置、排查故障时已经把这一步当成了常规手段前提是环境变量和数据卷都还在。8.3 资源监控一定要提前做Sentry 本身是干监控的但它对自己消耗的资源一无所知。我自己就把 Sentry 服务器加进了另一套基础监控里重点盯四项指标ClickHouse 所在分区的磁盘使用率Kafka 所在进程的内存占用各容器的重启次数Docker 网卡流量为什么盯这四项因为它们分别对应了最常出现的三件事磁盘写满、JVM OOM、以及异常事件突然暴增导致的网络带宽打满。如果你没有另外一套监控体系也可以用cron配合脚本每天把关键指标记录到文件里总比事后抓瞎强。8.4 关掉不需要的采样功能自托管初装后所有功能默认是开着的包括性能监控、Session Replay、Activity Feed 等。这些功能都有成本尤其是 Session Replay它会把整个浏览器会话的录屏数据传上来存储量增长得飞快。我的做法是性能监控保留 20% 采样率Session Replay 直接全局关闭只在排查特定线上问题时临时对单个项目开启。宁可功能少一点也别让存储压力反过来成了新的生产问题。最后再分享一点自己的体会吧。第一次部署 Sentry 时我觉得它不过是一个开源版错误日志工具但折腾完整套流程后最大的感受是它其实是一套完整的中型分布式系统所有软件工程里的经典问题——资源规划、服务编排、数据生命周期、升级兼容性、备份策略——在这里都能亲手遇到一遍。如果你正在自托管 Sentry 的路上我的建议是第一按照先最小化跑通、再逐步加功能的顺序走不要在第一天就贪多求全第二任何配置改动都以.env和容器重建为准不要靠手动改容器内部文件第三备份永远在升级之前。把这三点记住你大概率能比我少熬夜几晚。