Sentry是当前主流的开源错误追踪系统，能够在应用发生异常时自动收集堆栈、上下文与用户行为，帮助团队快速定位问题。将Sentry部署到云服务器，可以让前端网页与后端服务共用同一套报警和日志面板，避免多平台切换带来的信息碎片化。
一、云服务器环境准备
在正式部署Sentry之前，需要先准备一台配置合理的云服务器。官方推荐至少4GB内存和2核CPU，因为Sentry依赖多个容器组件，包括Web、Worker、PostgreSQL、Redis等，资源不足会导致启动失败或运行缓慢。系统建议选择Ubuntu 20.04或22.04，社区资料丰富且兼容性好。
除了机器本身，还要在云厂商的安全组里放行所需端口。默认情况下，Sentry的Web服务使用9000端口，如果打算用Nginx反代到80或443，则只需对外暴露代理端口。同时应配置好域名解析，方便后续为前端和后端分配统一的接入地址，也利于HTTPS证书部署。
二、使用Docker部署Sentry服务端
最简便的方式是采用官方维护的senttry-self-hosted仓库，它已经写好了docker-compose配置。先在云服务器上安装Docker与Docker Compose，然后克隆仓库并执行./install.sh，脚本会自动拉取镜像、初始化数据库并创建管理员账号。整个过程可能持续十几分钟，取决于带宽和磁盘性能。
部署完成后，通过docker compose up -d启动所有服务。此时访问 http://服务器IP:9000 即可进入登录页。首次进入后建议立刻修改默认密码，并在设置中配置邮件发信，否则后续异常报警无法主动推送。若使用域名，可在Nginx中做反向代理，将请求转发到本地9000端口，并配置SSL证书提升安全性。
2.1 获取项目Dsn
Dsn是Sentry用来标识上报目标的字符串，格式类似 https://xxxx@域名/项目ID。在Web后台新建一个项目时，系统会生成专属Dsn。前端和后端必须使用同一个或不同项目的Dsn，但都指向这台云服务器，这样才能在统一面板中查看。注意Dsn中的密钥不要提交到公开代码库，避免被他人冒用上报。
三、前端异常上报配置
前端接入通常使用@sentry/browser或框架专用包，例如@sentry/react、@sentry/vue。安装依赖后，在应用入口文件中初始化，填入云服务器对应的Dsn和release版本号。SDK会自动捕获未处理的Promise异常、资源加载错误以及控制台错误，并附带当前页面路由和用户ID等上下文。
为了提升排查效率，可以手动添加面包屑和用户标签。例如在用户登录后调用Sentry.setUser写入账号信息，或在关键操作前使用Sentry.addBreadcrumb记录步骤。当页面发生白屏或接口报错时，后台就能看到完整操作轨迹。此外，利用source map上传功能，可将压缩后的代码映射回源码行号，显著降低阅读堆栈的门槛。
3.1 常见前端上报问题
有些团队发现Sentry收不到错误，多半是因为云服务器跨域策略限制。需在Sentry后台将前端域名加入可信来源，或调整Nginx允许相关请求头。另一个常见问题是SDK初始化太晚，导致首屏异常遗漏，因此初始化代码应尽量置于入口最前方，并避免被异步分包延迟加载。
四、后端异常上报配置
后端根据语言选择对应SDK，如Python用sentry-sdk，Java用sentry-logback，Node.js用@sentry/node。以Python为例，安装后在程序启动时调用sentry_sdk.init，设置dsn和traces_sample_rate。此后未被捕获的异常会自动上报，已捕获的异常也可通过sentry_sdk.capture_exception手动发送。
在Web框架中还可结合中间件统一拦截错误。例如Django或Flask在返回500时，SDK会附带请求体、Headers和SQL耗时，帮助还原现场。对于定时任务或消息队列消费者，同样要在进程入口初始化，否则子线程中的异常将无法被收集。若涉及敏感数据，应通过before_send钩子过滤掉密码、令牌等字段再上报。
4.1 后端性能监控补充
除了报错，Sentry也支持性能追踪。开启traces_sample_rate后，后端接口耗时、数据库查询次数都会以事务形式展示。在云服务器资源有限的情况下，建议采样率设为0.1到0.2，既保留足够样本又不至于让PostgreSQL写入压力过大。配合前端的事务串联，还能看到一次页面请求从浏览器到服务器的全链路耗时。
五、自建与托管方案对比
很多团队会犹豫是自建还是直接用Sentry官方SaaS。核心差异体现在运维成本和数据合规。下表列出主要维度供参考：
| 对比项 | 云服务器自建 | 官方托管SaaS |
|---|---|---|
| 初期费用 | 仅云主机租金 | 按事件量阶梯收费 |
| 运维投入 | 需自己升级、备份、监控 | 平台负责可用性 |
| 数据存放 | 全在自有服务器 | 存于第三方机房 |
| 定制能力 | 可改源码、加插件 | 仅用官方功能 |
如果业务涉及隐私或内网系统，自建在云服务器上是更稳妥的选择；若是初创项目且事件量小，先试用SaaS能省去运维麻烦。无论哪种方式，前端与后端接入逻辑基本一致，后续迁移成本不高。
六、日常维护建议
Sentry运行一段时间后，PostgreSQL会累积大量事件数据。云服务器磁盘有限，应定期在后台清理旧事件或调整保留天数，例如只存最近30天。也可单独挂载云盘给数据目录，避免系统盘被写满导致服务崩溃。Redis若使用默认配置，重启可能丢部分队列，但对错误追踪影响较小，可接受。
另外，Sentry版本升级较为频繁，建议订阅官方更新日志。升级时先在测试机拉新镜像验证，再上生产，防止compose字段变动引发启动异常。配合云厂商的监控告警，当容器退出或9000端口不通时及时感知，才能保证异常上报链路长期稳定。