早在半年前我就动了本地部署 Sentry 的念头但每次都被它那套庞大的服务编排吓得退回去。后来项目里线上报错越来越多团队天天在群里发截图终于让我下定决心把 Sentry 完整跑起来。这篇踩坑实录就是记录我从零到能正常上报错误的全过程。如果你正准备本地部署 Sentry或者已经被各种奇奇怪怪的错误折腾得想掀桌子这篇文章应该能帮你省下不少周末。先说结论Sentry 的本地部署没有想象中那么难但坑很多尤其是对资源规划不熟、不读官方文档默认配置的人基本都要交一遍学费。文章里我会把每一步的背景和原因讲清楚包括为什么选 Docker Compose、内存到底要多少、邮件服务怎么接、升级时为什么老失败这些都有实际经历支撑不是纸上谈兵。1. 部署前必须想明白的几件事1.1 本地部署 Sentry 到底是要解决什么问题很多团队接触 Sentry第一反应是“这不就是个错误监控平台吗直接用官方 SaaS 版不就行了”但实际上自托管 Sentry 的价值远不止省钱。就拿我们项目来说服务器环境偏内网业务数据的敏感级别较高用户上报的某些日志信息又不适合放到第三方平台这时候本地部署就成了几乎唯一的选择。另一个场景是研发团队有定制需求比如想把异常数据和企业内部工单系统打通或者要对接私有化权限体系这些在 SaaS 版里做起来限制非常多而自托管版本能直接改代码、改配置。所以你在动手之前必须想清楚你是为了数据私密性、合规要求、定制能力还是单纯为了省钱这个决定会影响你后续所有配置。如果是图省钱我劝你先算一笔账自托管 Sentry 需要的服务器、维护时间、升级成本加上偶尔出问题抢救的一次性人力成本未必比官方免费额度或低档套餐划算。但如果是为了数据主权和定制空间那自托管就是正路值得投入。我个人建议如果只是个人学习、小项目试用不要急着上完整集群先跑单机 Docker Compose 模式就好。Sentry 的完整部署会拉起十几个服务包括 ClickHouse、Kafka、PostgreSQL、Redis、Zookeeper、Snuba 等等第一次看到docker compose ps刷出满满一屏时确实有点吓人。但别慌底层逻辑并不复杂它就是用这些组件来支撑事件存储、搜索分析、队列处理和缓存理解了大方向后面的排障就不会迷路。1.2 硬件要求与操作系统的选择官方文档其实写得比较保守告诉你推荐配置是 4 核 8G 起步但我的实际体验是8G 内存只够勉强跑起来一旦开始有流量、有查询就会频繁触发 OOM尤其是 Kafka 和 Snuba 这两个家伙吃内存毫不客气。我自己第一次部署在一台 4 核 16G 的 Linux 服务器上跑了两周还算稳定之后有一次升级时 ClickHouse 和 Kafka 同时重启内存直接被打满整个 Docker 都卡死在那了。你要是条件允许直接上 16G 内存硬盘建议 SSD至少留出 100G 空间。磁盘空间这个事很容易被忽略。Sentry 的日志、事件原始数据、ClickHouse 的数据都占用空间尤其 ClickHouse 的存储路径默认会不断膨胀。我见过有人硬盘被写满后整个 Sentry 处于半死不活状态登录页面能打开但新事件根本不进来。所以部署前就要规划好数据目录最好用独立数据盘顺便把日志轮转和保留策略配好。操作系统我偏向 Ubuntu 22.04 LTS 或 Debian 12原因是 Docker 支持最稳遇到问题搜索时能找到大量现成解决方案。不建议用带桌面版的系统跑生产环境如果你是个人学习就无所谓但团队的服务器还是越干净越好。另外如果是 CentOS 7 这种老系统会遇到内核版本和 Docker 版本兼容性问题Sentry 容器启动时也是一堆诡异报错我劝你趁早放弃。内核版本建议 5.10 以上能避免很多 cgroup 和网络问题。1.3 域名、HTTPS 与访问方式的提前规划本地部署完成后总要访问 Web 界面。在真正动手前你还要想清楚通过什么地址访问。如果只是内网自己用可以直接用http://IP:9000这种方式但现代浏览器的安全策略会越来越严格而且很多特性比如 clipboard 写入、摄像头权限、Service Worker 这些在非 HTTPS 环境下会有莫名其妙的问题。个人学习阶段无所谓但要让团队正式用起来我强烈建议配一个域名并启用 HTTPS。我当时就是图省事先用 IP 地址跑了两周结果同事反馈说某些浏览器里登录状态总失效上传 Source Map 也会失败查了半天发现都是因为页面不是安全上下文导致的。后来加了 Nginx 反代和 Let‘s Encrypt 证书整个世界清净了。如果你们公司有内部 CA也可以用内部证书但记得在每台客户端安装信任链不然浏览器拦截也很麻烦。反向代理这块最常用的方案就是 Nginx。Sentry 默认监听 9000 端口你只需要在 Nginx 里做一个location /的转发把 WebSocket 也代理过去就行。注意 WebSocket 支持Sentry 的 Web 界面有实时推送功能不配置 WebSocket 的话页面能开但某些操作会感觉很迟钝或者报错。Nginx 配置里添加Upgrade和Connection头即可我后面会给出具体示例。2. 安装前的准备工作镜像、配置与网络2.1 用官方 install.sh 还是手动 Docker Compose这是新手最容易纠结的问题。Sentry 官方仓库getsentry/self-hosted提供了一键安装脚本./install.sh实际上它做的工作也不复杂检查环境、生成默认配置、创建 docker volume、构建镜像、初始化数据库。你会发现如果用脚本安装整条链路走下来会顺滑很多因为它的默认版本组合是经过验证的不太会出现镜像间版本不匹配的问题。我的建议是第一次部署就用官方 install.sh不要自己手工去改镜像 tag。Sentry 的组件之间版本耦合度很高比如 Snuba 和 Sentry 前端版本不一致会出现界面能打开但事件详情页 API 报 500 的情况。你可能会觉得手工指定每个镜像的最新版更酷实际上这只是给自己挖坑。install.sh 用到的docker-compose.yml里已经固定了镜像版本组合你最多就是改环境变量不要动镜像 tag。同时install.sh 还会生成.env文件里面包含了大量配置项例如SENTRY_SECRET_KEY、POSTGRES_PASSWORD、SENTRY_EVENT_RETENTION_DAYS等。它要求你必须设置一个复杂的SENTRY_SECRET_KEY这是用来给 Django 做签名和加密的不能丢失否则数据库里的部分数据将无法读取。生成后记得保存好别随手删了。2.2 Docker 环境检查与 Compose 插件在运行 install.sh 之前先把 Docker 环境整利索。你需要安装 Docker Engine 和 Docker Compose 插件。注意如果你用的是docker-compose这个旧版命令和插件版的docker compose在某些解析行为上有差异。Sentry 官方脚本会检测 compose 是否可用建议直接装官方插件。另外一个容易踩坑的点是 Docker 的存储驱动。如果你之前配置过 devicemapper 或别的存储驱动可能会导致容器层构建异常。现在主流环境都建议使用 overlay2可通过docker info查看 Storage Driver 字段。如果发现不是 overlay2我建议你重新安装 Docker别在这个上面将就。Docker 版本也不能太老。Sentry 的编排文件用到了不少较新的语法老版本可能直接报解析错误。官方要求 Docker 20.10 以上最好是 24 及以上。在准备阶段执行docker version检查一下 Client 和 Server 版本顺便看看权限问题确保当前用户能直接操作 Docker。我在第一次部署时就是忘了加用户组结果./install.sh里所有 docker 命令都被权限拒绝浪费了不少时间。2.3 反向代理与 WebSocket 配置前面说到要提前规划域名和 HTTPS这里直接给出一份 Nginx 示例配置方便你对照修改。注意我这个配置只负责转发不包含证书申请逻辑。server { listen 80; server_name sentry.example.com; return 301 https://$host$request_uri; } server { listen 443 ssl http2; server_name sentry.example.com; ssl_certificate /etc/nginx/ssl/sentry.example.com.crt; ssl_certificate_key /etc/nginx/ssl/sentry.example.com.key; client_max_body_size 50m; location / { proxy_pass http://127.0.0.1:9000; proxy_set_header Host $host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Real-IP $remote_addr; } location /ws/ { proxy_pass http://127.0.0.1:9000; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_set_header Host $host; proxy_read_timeout 86400; } }这里最关键的是client_max_body_size如果项目里要上传不少 Source Map 文件默认 1m 肯定不够。我在实际使用中碰到过上传 sourcemap 时 413 Request Entity Too Large调大这个值就解决了。WebSocket 的/ws/路径是 Sentry 内部功能用的包括实时事件流和看板刷新漏掉这一段会导致页面一直转圈。另外如果你之前只用过 Caddy那更简单Caddy 会自动申请证书并支持 WebSocket 代理配置量比 Nginx 小很多。我这里贴 Nginx 是因为团队服务器上普遍都装了 Nginx你按自己的实际情况选就好。3. 完整安装过程实录3.1 拉取仓库与执行安装脚本我以 Ubuntu 22.04 为例完整安装命令如下sudo apt update sudo apt install -y git vim curl git clone https://github.com/getsentry/self-hosted.git cd self-hosted注意默认分支通常是最新的稳定发布版。既然要做本地部署最好固定版本不要一更新就跟着最新走否则哪天官方改了编排格式你可能连升级路径都没有。可以用git tag查看当前发布版本比如24.4.1这种格式然后git checkout 24.4.1。我这次踩坑就是没固定版本中途官方调整了镜像名称我拉下来一堆新旧混合最后只能重来。接着运行sudo ./install.sh安装脚本会做几件事首先检查环境依赖然后交互式询问是否要创建初始用户。它会让你输入邮箱和密码这步别跳过因为 Sentry 初始化页面虽然也可以注册但因为默认开启了注册限制很多情况下会因配置问题无法成功注册直接创建管理员账户最省事。整个过程耗时取决于网络和机器性能一般在 10 到 30 分钟之间。因为脚本要编译部分前端资源等待时压力很大。不要频繁中断如果中途断了理论上可以重新运行但部分步骤可能不幂等我建议断了几次后干脆把~/.sentry缓存清掉再来不要硬着头皮续跑。3.2 环境变量与关键参数解读安装完以后仓库目录下会生成一个.env文件。这个文件是自托管 Sentry 的核心配置你需要重点理解以下几个参数。SENTRY_SECRET_KEY是 Django 密钥必须保持稳定一改掉所有 session 失效严重时数据都解不开。SENTRY_EVENT_RETENTION_DAYS控制事件数据保留天数我这里设置成 30 天因为磁盘空间不是无限大默认 90 天对于个人或者中小团队来说太长还会拖慢查询性能。邮件相关配置在后续会单独讲这里更需要注意的是SENTRY_SINGLE_ORGANIZATION。如果设置为trueSentry 会强制你不能创建多个组织适合小团队的单实例使用如果希望以后有多业务线接入就保留默认或设为 false。我一开始没仔细看默认是 true后来想加一个新组织一直找不到入口查了一圈才明白是这个开关的问题。还有一个参数是SKIP_USER_CREATION如果设成1新用户注册功能会被禁用只能由管理员邀请。内网环境建议开启避免任何人都能注册。3.3 启动服务与健康检查安装完成后用以下命令启动所有服务docker compose up -d docker compose ps第一次启动时上面这一串服务会按照依赖顺序启动。如果安装脚本执行顺利启动一般问题不大但你还是得学会怎么判断服务是否健康。使用docker compose ps查看状态Sentry 的状态字段会显示running或者healthy。Sentry 正常工作时sentry-web、sentry-worker、sentry-cron这几个核心容器必须长期运行。因为容器数量多日志排查时要学会只盯着出问题的容器看不要用docker logs -f一把梭地看全部信息量太大会淹没真正的报错。常用的排障命令是docker compose logs sentry-web -f docker compose logs sentry-worker -f docker compose logs snuba -f如果sentry-web的日志里持续出现数据库连接失败那就说明 PostgreSQL 容器还没正常起来先docker compose ps看数据库状态再去查对应日志。内存不足时很多容器会反复重启状态里出现Restarting这时候最有效的办法是增加内存或减少同时运行的组件而不是在报错里找答案。4. 我在实际操作中踩到的那些坑4.1 内存不足导致的构建失败我最初部署时用的是 8G 内存的机器前 20 分钟还很顺利结果到编译前端静态资源时直接 OOM。症状表现是 install.sh 卡在某个地方不动终端没有任何动静过一会儿容器自动退出日志里能看到Killed或者We did not find any downloads。这个阶段最吃内存的是sentry-web的前端构建任务用到了 webpack本身就是一个内存大户。我的建议是内存不足的机器不要硬扛升级到 16G 最省事。如果实在不方便升级可以临时增加 swap比如sudo fallocate -l 8G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile但 swap 只能缓解生产环境别指望靠 swap 长期顶着。4.2 升级时常见错误及恢复方法自托管 Sentry 每过一阵子官方就会发布新版本升级本来是一次git pull ./install.sh就能搞定的操作但是我在升级过程中遇到的最经典问题是升级脚本因为数据库迁移失败而中断。 第一次升级时我从非常老的版本跳到比较新的版本结果 ClickHouse 的 schema 迁移跑挂报错信息大段大段地输出根本无从看起。后来我学会了备份先行在升级前先备份 PostgreSQL 和 ClickHouse 的数据目录或者直接打 Docker volume 的 tar 包。备份命令也许是这样docker run --rm -v sentry_postgres:/data -v $(pwd):/backup alpine tar czf /backup/postgres.tar.gz -C /data .ClickHouse 的数据量通常更大备份起来更久但也必须做。升级失败的时候第一件事不是去查报错而是先确认网络和磁盘空间然后看是否有未完成的迁移锁。部分迁移锁可以通过重启对应容器解除但有些需要手动连接数据库去清理表这对新手来说难度陡增。我这边的经验是小版本升级不用太怕大版本升迁前一定要先跑一个docker compose down然后用完整备份留出回滚路径再执行git pull。另外不要跨太多版本跳跃升级官方有时只保证相邻版本可升级跨了太多版本中间缺了迁移步骤谁都救不了你。4.3 邮件服务不生效的排查自托管 Sentry 的邮件服务是我折腾最久的一个功能。本地部署后如果不对 SMTP 做配置你会发现用户无法收到注册确认邮件、密码重置邮件问题反馈也无法转到邮箱。即使你填对了 SMTP 参数发送也可能失败因为 Sentry 对邮件发送的配置层级比较绕人。最关键的配置项在.env里SENTRY_MAIL_HOSTsmtp.example.com SENTRY_MAIL_PORT465 SENTRY_MAIL_USERNAMEyournameexample.com SENTRY_MAIL_PASSWORDyourpassword SENTRY_MAIL_USE_TLStrue SENTRY_MAIL_FROMno-replyexample.com要注意的是如果端口是 465则使用 SSL对应的变量名可能是SENTRY_MAIL_USE_SSL而不是 TLS如果是 587 端口则用 STARTTLS。我一开始填反了页面提示发送成功实际邮箱里什么都没有查 worker 日志才发现握手失败。如果使用了阿里云、腾讯云这类厂商的邮件推送服务一般会要求验证发件域名还要配置 SPF/DKIM 记录。这些在本地部署时同样生效别以为在配置里填了账号密码就万事大吉。排查邮件问题时一条最快的命令是docker compose exec sentry-web python manage.py shell -c from django.core.mail import send_mail; send_mail(test subject, message, no-replyexample.com, [targetexample.com], fail_silentlyFalse) 通过这条命令可以直接测试 Sentry 进程能不能发信排除不少转发层和配置层的干扰因素。4.4 构建失败与镜像拉取超时国内网络环境下拉取 Docker Hub 镜像时还会经常出现超时、连接重置的情况。我第一次部署就卡在了拉取ghcr.io和docker.io镜像的环节install.sh 反复提示某个镜像 pull 失败。最有效的解决方案是配置你的 Docker daemon 使用可用的镜像加速器这个需要在/etc/docker/daemon.json里写入 registry-mirrors。但因为镜像源属于外部环境问题不同地区和不同网络情况效果差异很大如果你的部署环境比较特殊要么耐心多拉几次要么提前把需要的镜像手动 pull 下来导出成 tar再在离线环境导入。这个步骤容易被忽略所以建议你在规划部署时就把网络因素考虑进去。如果你所在团队有内网镜像仓库建议把所有需要的镜像 tag 推送到内网仓库然后把.env里的镜像地址替换成内网地址这样后续升级也稳定很多不会再因为外网波动中断安装。5. 部署完成后的关键配置与日常维护建议5.1 创建项目、获取 DSN 并与后端集成Sentry 部署完成后第一步是登录管理员账号创建一个项目。项目类型可以选择你实际使用的技术栈比如 Django、Flask、Node.js 或前端 JavaScript。Sentry 会根据项目类型展示对应的接入代码。其实它真正需要的东西只有一个DSN 字符串。DSN 的格式一般是这样的http://public_key:secret_keysentry.example.com/project_id在新版本中secret_key 这个字段已经不太用了但在 SDK 中它仍然出现在 DSN 里。你在后端代码里初始化 Sentry 时只需要填这一个 DSN 即可。以 Python 项目为例安装sentry-sdk后在初始化代码中写入import sentry_sdk sentry_sdk.init( dsnhttp://public_keylocalhost:9000/2, traces_sample_rate1.0, )然后故意制造一个异常Sentry 就能收到并展示错误详情、堆栈、上下文信息。要注意的是上报的请求是会走 Web 服务所在的 9000 端口如果项目代码和 Sentry 不在同一台机器DSN 里的主机名要写成能访问到的服务器地址不能写localhost否则线上环境会全部上报失败。5.2 SDK 配置中容易忽略的细节很多人在本地部署 Sentry 后接入 SDK 时想当然地用默认配置结果上报的数据量忽大忽小或者性能监控完全没数据。实际上有几个参数非常关键。traces_sample_rate是性能监控的采样率我建议不要直接设成 1.0。高流量场景下设成 1.0 会让事件量和性能数据暴涨存储和查询压力马上就上来了。更合理的方式是动态采样比如根据 用户是否登录决定采样率。同样send_default_pii这个开关要谨慎开启它会在事件中附带用户 IP、Cookies 等个人信息本地部署虽然数据不出网但也要考虑合规和隐私问题。如果把 SDK 集成到大型项目里建议给 SDK 增加环境标签方便区分开发、测试和生产环境。Sentry 内部的看板支持按环境筛选这是做故障分级很重要的能力。不然开发环境报的错误和生产环境混在一起排查效率非常低。5.3 日常维护备份、清理与安全检查自托管 Sentry 一旦稳定跑起来日常维护其实没有想象中复杂但有几件事必须养成习惯。第一是定期备份数据库和配置文件。Sentry 的业务配置、用户账号、项目设置都存在 PostgreSQL 里事件数据则在 ClickHouse 里。如果你关心的是配置和用户数据PostgreSQL 备份优先级最高如果担心丢失大量历史事件ClickHouse 也要纳入备份策略。第二是磁盘空间和容器日志体积的管理。长期运行的 Docker 容器会产生大量日志文件尤其是sentry-worker和snuba它们的日志轮转如果不配置很容易克隆到几十 GB。可以在/etc/docker/daemon.json里设置 log rotation{ log-driver: json-file, log-opts: { max-size: 10m, max-file: 3 } }重启 Docker 后新容器才生效。旧容器日志的那个体积问题只能手动清或者等你下一次重新部署时再解决。第三是安全更新。Sentry 的很多组件是用 Docker 镜像方式发布的镜像本身的漏洞需要官方发布新版本才会修复所以定期关注 GitHub Releases 很重要。对于生产环境我建议至少每季度检查一次是否需要升级。当然升级前别忘了我前面说的备份和固定版本那条铁律。最后再说一个小技巧如果你发现某天 Sentry 异常变慢不要急着重启所有容器。先看docker stats分析哪个容器内存和 CPU 占用异常多数情况下是 ClickHouse 在做合并或者 Kafka 堆积了大量消息。用docker compose logs定位针对性处理比无脑重启靠谱得多。自托管 Sentry 这条路走通之后你会获得一个完全受自己控制的错误监控系统也理解了事件处理链路里的那些组件分工。虽然第一次部署花了我几乎两个完整周末但把所有坑记录下来之后后续升级和迁移都变得非常顺。如果你正准备部署按照前面的步骤一步一步来遇到问题不要焦虑大部分故障都能通过在docker compose ps、docker compose logs和.env文件里找到线索。希望这篇实录能帮你少走几段弯路。
