企业官网建设流程全解析

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 本身就要吃掉几个 G，ClickHouse 在内存里做列式聚合又很吃资源，再加上 Web 和 Worker 各需要 1-2G，4G 内存连部署过程都撑不过去。

磁盘方面，官方建议 30GB 起步，这个数我建议直接再加一倍。因为 ClickHouse 一张原始事件表一天就能长几百 MB，如果保留周期设成 90 天，几个月之后磁盘会非常紧张。我的建议是：

对了，如果你的机器物理内存不够，一定记得先准备 Swap 分区。我在 4G 机器上就是因为没设 Swap，安装期间进程直接被 OOM Killer 干掉，报错信息只有一堆"退出状态码 137"，当时差点以为是镜像拉坏了。

2.2 端口规划与反向代理预留

Sentry 的 Web 服务默认监听9000端口，这也是安装完成后唯一需要对外暴露的入口。我遇到的实际问题是，服务器上之前有一个旧的监控面板占着 9000，导致安装脚本启动sentry-web时容器反复重启。排查了一大圈才发现是端口冲突——所以部署前务必先查一次：

ss -lntp | grep -E ':9000|:9001'

9001 是 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。它内部按顺序做了这几件关键事：

1. 生成了.env配置文件，里面有大量SENTRY_开头的环境变量。
2. 拉取所有 Docker 镜像，此时 Docker Hub 的网络压力会很大。
3. 启动依赖的底层服务（Postgres、Redis、ClickHouse、Kafka 等）。
4. 执行 Sentry 自身的数据库迁移（类似 Django framework 的 migrate）。
5. 初始化 Snuba 的 schema，这一步失败率极高，尤其在内存不够时。

我后来回过头看，install.sh之所以容易显得"卡死"，其实是两个原因：一是镜像体积大，一个完整的镜像包可能超过 10GB；二是在初始化底层库时 CPU 占用特别高，日志输出也不一定实时刷新。所以看到脚本长时间没反应，别急着 Ctrl+C，先docker stats看下 CPU 和内存是否还在跳动。

3.3 我踩过的三个安装期错误

第一个错误我已经提过了：内存不足导致容器 OOM，现象是一堆服务反复重启，install.sh最后报错失败。解决办法不是降低配置，而是老老实实加 Swap：

fallocate -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 100

3.4 建立第一个管理员账号

安装成功后，你可能会疑惑从哪里登录。直接在浏览器访问http://服务器IP:9000就能看到 Sentry 的登录页。如果你在安装时选择了跳过超级管理员创建，那就需要手动用命令创建：

docker compose run --rm sentry createuser \ --email admin@example.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_HOST=sentry.example.com SENTRY_EVENT_RETENTION_DAYS=30 SENTRY_BEACON=False SENTRY_SINGLE_ORGANIZATION=false

这里有个容易忽略的细节：改.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 项目，接入过程其实非常轻量。安装 SDK：

pip install sentry-sdk

然后在项目的初始化配置里加两行：

import sentry_sdk from sentry_sdk.integrations.django import DjangoIntegration sentry_sdk.init( dsn="http://<public_key>@sentry.example.com:9000/<project_id>", integrations=[DjangoIntegration()], traces_sample_rate=0.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_EMAIL=no-reply@sentry.example.com SENTRY_MAIL_HOST=smtp.example.com SENTRY_MAIL_PORT=465 SENTRY_MAIL_USER=mailuser@example.com SENTRY_MAIL_PASSWORD=mailpassword SENTRY_MAIL_USE_TLS=true

这里面有几个很容易被忽略的点：

• 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 --tail=100 sentry-web

docker 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).sql

ClickHouse 里是原始错误事件和性能数据，数据量大且是典型的时间序列数据。备份它的成本很高，我个人的建议是：如果保留周期只设 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和容器重建为准，不要靠手动改容器内部文件；第三，备份永远在升级之前。把这三点记住，你大概率能比我少熬夜几晚。