实用指南：如何本地化部署 Sentry (Self-Hosted) 完整教程

前端市界2026-06-07 10:08

2026 级实用指南：如何本地化部署 Sentry (Self-Hosted) 完整教程

在日常的研发流程中，错误监控（Error Tracking）与可观测性（Observability）建设是保障线上稳定性的核心环。Sentry 作为行业内极其优秀的开源错误追踪工具，其本地化部署（官方称为 Self-Hosted）方案非常成熟。

官方提供了一整套基于 Docker 和 Docker Compose 的一键安装脚本，极大降低了搭建门槛。本文将带你从零开始，完整走一遍 Sentry 的本地化部署流程。

一、 硬件与环境准备（硬性指标）

Sentry 内部集成了非常庞大的组件生态（包括 Kafka、ClickHouse、Redis、PostgreSQL、Snuba 等），因此它是一个典型的**"内存大户"**。请务必确保机器配置达标，否则极易因内存不足导致容器崩溃。

1. 硬件配置要求

  • 最低配置： 4 核 CPU，16 GB RAM（官方强制建议，外加至少 16 GB Swap 虚拟内存），20 GB 硬盘空间。
  • 推荐配置： 32 GB RAM，搭配高性能固态硬盘（Sentry 对磁盘 I/O 要求极高）。

2. 基础软件环境

部署前，请确保你的服务器已安装好以下基础环境：

  • Docker 19.03.6+
  • Docker Compose 2.32.2+

二、 源码下载

Sentry 官方维护了一个专门用于本地化部署的开源蓝图仓库。我们直接通过 Git 将其克隆到本地服务器。

bash 复制代码 
# 1. 克隆官方本地化部署仓库
git clone [https://github.com/getsentry/self-hosted.git](https://github.com/getsentry/self-hosted.git)
cd self-hosted

# 2. 【可选】切换到特定稳定版本
# 默认主分支是 nightly/master。如需生产稳定版，可去 Releases 中找一个 Tag 切换
# git checkout 24.1.0

三、 标准本地化部署全流程

Step 1: 执行自动化安装脚本

在 self-hosted 目录下，运行官方提供的一键集成安装脚本。该脚本会自动拉取镜像、创建 Docker 数据卷、并完成复杂的数据库表结构初始化与数据迁移。

Bash

bash 复制代码 
./install.sh

⚠️ 注意 ：由于涉及拉取数十个基础组件镜像及 ClickHouse 初始化，根据您的网络带宽与机器性能，此步骤通常需要 10 ~ 30 分钟。

Step 2: 交互式创建管理员账号

在 ./install.sh 脚本执行到尾声时，控制台会弹出一个关键的交互提示：

Would you like to create a user account now? [Y/n]

此时请及时输入 Y ，并根据提示输入您的 管理员邮箱（Username） 和 强密码（Password） 。该账号将作为首次登录 Sentry Web 后台的超级管理员凭证。

Step 3: 一键启动容器集群

当脚本提示安装完成后，执行以下命令，在后台一键拉起 Sentry 全家桶服务：

Bash

复制代码 
docker compose up -d

Step 4: 检查服务健康状态

服务完全拉起需要 1~2 分钟，随后可通过以下命令检查所有容器是否均处于正常的 Up 或 Healthy 状态：

Bash

复制代码 
docker compose ps

四、 生产环境适配与核心踩坑点（防脱发指南）

1. 解决登录后的 CSRF 跨域报错 🛑

很多同学在好不容易搭建完、高高兴兴登录时，会遭遇 "CSRF Verification Failed" 的安全报错。这是因为新版 Sentry 增强了对安全域名的限制。

解决方案 ： 进入 sentry 子目录，修改 sentry.conf.py 配置文件，搜索或手动追加 CSRF_TRUSTED_ORIGINS，将你的实际访问域名或 IP + 端口加进去：

Python

ini 复制代码 
# sentry/sentry.conf.py
CSRF_TRUSTED_ORIGINS = ["[https://sentry.yourdomain.com](https://sentry.yourdomain.com)", "http://<服务器外网IP>:9000"]

修改后，在根目录下重启容器使配置生效：

Bash

复制代码 
docker compose restart

2. 配置 Nginx 反向代理与 HTTPS（生产标准）

在企业实际落地中，强烈建议不要将 9000 端口直接裸露在外网。最规范的做法是在前端架设一台 Nginx 负责 SSL 证书卸载（HTTPS），再将流量安全转发至内部的 127.0.0.1:9000。

配置完 Nginx 后，记得修改项目根目录下的 config.yml 文件：

YAML

less 复制代码 
# config.yml
system.url-prefix: '[https://sentry.yourdomain.com](https://sentry.yourdomain.com)'

3. 数据留存周期（Event Retention）调优

默认情况下，Sentry 会在本地保留 90 天的错误事件数据。如果公司业务体量大、报错频发，磁盘很容易被撑爆。 可以通过修改隐藏的环境变量 SENTRY_EVENT_RETENTION_DAYS（例如缩短至 30 天）来释放宝贵的 SSD 空间。

五、 进阶：如何配置 Nginx 反向代理与 HTTPS（最规范的生产实践）

在生产环境中，最标准的做法是不暴露 Sentry 的 9000 端口给外网，而是通过 Nginx 在前端作为统一入口，负责 SSL 证书卸载（HTTPS 解密），再通过内网转发。

以下是完整的实现步骤和 Nginx 核心配置：

1. 完整的 Nginx 配置文件

在你的 Nginx 服务器上（可以是独立服务器，也可以是宿主机），创建或修改站点配置。请将 sentry.yourdomain.com 替换为您自己的真实域名。

nginx 复制代码 
# 1. 强制将所有 HTTP 请求重定向到 HTTPS
server {
    listen 80;
    listen [::]:80;
    server_name sentry.yourdomain.com;

    # 允许 Let's Encrypt 等证书自动化校验
    location /.well-known/acme-challenge/ {
        root /var/www/html;
    }

    location / {
        return 301 https://$host$request_uri;
    }
}

# 2. HTTPS 正式配置
server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name sentry.yourdomain.com;

    # ----------------------------------------
    # SSL 证书路径配置（请根据实际路径修改）
    # ----------------------------------------
    ssl_certificate /etc/nginx/ssl/sentry.yourdomain.com.crt;
    ssl_certificate_key /etc/nginx/ssl/sentry.yourdomain.com.key;

    # 安全优化配置
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 1d;

    # ----------------------------------------
    # 核心反向代理配置
    # ----------------------------------------
    location / {
        # 转发到 Sentry 默认绑定的本地 9000 端口
        proxy_pass [http://127.0.0.1:9000](http://127.0.0.1:9000);

        # 传递真实客户端 IP（Sentry 识别错误来源和地域的关键）
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        
        # 【极其重要】告诉 Sentry 前端使用的是 HTTPS 协议，防止 CSRF 报错和无限重定向
        proxy_set_header X-Forwarded-Proto https;

        # 优化长连接
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        # 缓存与超时调优
        proxy_redirect off;
        proxy_buffering off;
        proxy_read_timeout 3600s;
        proxy_send_timeout 3600s;
    }

    # 针对 Sentry 附件/大日志上传，调大允许的最大 Body 大小
    client_max_body_size 100m;
}

2. 必须同步修改的 Sentry 配置文件

光配置 Nginx 还不够，如果不修改 Sentry 内部的域名策略，登录时依旧会触发浏览器的跨域和安全阻断。

请前往你的 self-hosted 目录，修改以下两个配置文件：

① 修改 config.yml

找到 system.url-prefix，将其修改为你带 https:// 的完整域名 （注意：结尾不要加斜杠 /）：

YAML

less 复制代码 
# config.yml
system.url-prefix: '[https://sentry.yourdomain.com](https://sentry.yourdomain.com)'
② 修改 sentry/sentry.conf.py

在文件末尾追加以下内容，显式信任该 HTTPS 域名的请求：

Python

ini 复制代码 
# sentry/sentry.conf.py
SECURE_PROXY_SSL_HEADER = ('HTTP_X_FORWARDED_PROTO', 'https')
CSRF_TRUSTED_ORIGINS = ["[https://sentry.yourdomain.com](https://sentry.yourdomain.com)"]

3. 重启服务生效

  1. 测试并重启 Nginx：

    Bash

    复制代码 
    nginx -t && systemctl restart nginx

  2. 在 self-hosted 根目录下重启 Sentry 容器集群：

    Bash

    复制代码 
    docker compose restart

此时，你就可以安全地通过 https://sentry.yourdomain.com 访问你的专属错误追踪平台了！

六、 集成Sentry SDK

第一步：在 Sentry 后台获取 DSN (Data Source Name)

DSN 是 Sentry 给每个项目分配的唯一密钥（类似于 https://public@sentry.yourdomain.com/1），SDK 需要通过这个地址将错误日志上报到你的私有服务器。

  1. 登录你的 Sentry 后台（例如 http://<服务器IP>:9000）。

  2. 点击左侧导航栏的 Projects（项目） -> Create Project（创建项目） 。

  3. 选择你的前端开发语言或框架（如 Vue、React、JavaScript、HTML 等）。

  4. 给项目起个名字，点击 Create Project。

  5. 创建成功后，Sentry 会自动显示引导页面，复制里面生成的 DSN 字符串。

    • 注：如果以后找不到，可以在 项目设置 (Project Settings) -> Client Keys (DSN) 中重新找到它。

第二步：在网站代码中嵌入 Sentry SDK

根据你网站的构建方式，选择以下对应的方法进行嵌入：

方案 A：传统 HTML 网站（直接通过 <script> 标签引入）

如果你的网站是没有使用 Webpack/Vite 的传统网页，直接在页面的 <head> 标签中加入以下代码（确保尽可能靠前，以便捕获最开始的错误）：

HTML

xml 复制代码 
<head>
  <script
    src="https://browser.sentry-cdn.com/8.0.0/bundle.min.js"
    integrity="sha384-XXXXX" 
    crossorigin="anonymous"
  ></script>

  <script>
    Sentry.init({
      // 替换为你自己在本地 Sentry 后台获取的真实 DSN
      dsn: "http://xxx@你的服务器IP或域名:9000/项目ID",
      
      // 性能监控采样率（1.0 代表 100% 收集，生产环境建议调低如 0.1）
      tracesSampleRate: 1.0,
    });
  </script>
</head>

方案 B：现代前端框架（Vue / React / Next.js / Vite 等）

如果你使用的是现代前端工程化项目，推荐通过包管理器安装。以 Vue 3 为例：

1. 安装 SDK

Bash

bash 复制代码 
npm install @sentry/vue
# 或者使用 yarn / pnpm
pnpm add @sentry/vue
2. 在 main.js 或 main.ts 中初始化

JavaScript

javascript 复制代码 
import { createApp } from "vue";
import App from "./App.vue";
import * as Sentry from "@sentry/vue";

const app = createApp(App);

Sentry.init({
  app,
  // 填入你的本地 Sentry DSN
  dsn: "http://xxx@你的服务器IP或域名:9000/项目ID",
  
  integrations: [
    // 自动追踪路由性能（如果你使用了 vue-router）
    Sentry.browserTracingIntegration(),
    // 自动重现用户错误发生时的屏幕录像（可选，非常强大但耗费流量）
    Sentry.replayIntegration(),
  ],
  
  // 性能采样率
  tracesSampleRate: 1.0,
  // 录像采样率
  replaysSessionSampleRate: 0.1, 
  replaysOnErrorSampleRate: 1.0,
});

app.mount("#app");

第三步：测试是否嵌入成功

部署并运行你的网站，在浏览器的开发者工具（F12）控制台（Console）中，故意手动制造一个错误：

JavaScript

javascript 复制代码 
// 在控制台直接回车执行
setTimeout(() => {
  throw new Error("Sentry 本地集成测试错误！");
}, 500);

执行后，查看浏览器的 Network（网络） 标签页，如果发现有一个指向你的 Sentry 服务器域名/IP 的 envelope 或 store 请求，且状态码为 200，说明上报成功！

此时回到你的本地 Sentry 后台 Issues 页面，刷新即可看到刚刚触发的错误详情和调用栈。

七、 总结

通过官方提供的 self-hosted 方案，我们可以在极短时间内为企业内部搭建起一套完全免费、功能无阉割、且符合数据合规要求的企业级错误监控平台。

如果在部署中遇到 ClickHouse 或 Kafka 容器无故退出，请优先去检查机器内存和 Swap 分区，通常 95% 的搭建失败都是由于硬件资源被榨干引起的。祝大家部署顺利，线上稳如泰山！

欢迎在评论区分享你在部署 Sentry 时遇到的坑，我们一起交流解决！如果本篇教程帮到了你，欢迎点赞、收藏、关注三连支持！

相关推荐
颂love1 小时前
TypeScript速学
前端·javascript·typescript
IT策士1 小时前
第 46 篇 k8s之CI/CD 集成：GitOps 理念与 ArgoCD
前端·容器·kubernetes
Dalydai1 小时前
AI 辅助大屏开发：怎么让 AI 干活，但别让它干砸
前端
凌涘1 小时前
深入理解 JavaScript 执行机制：从执行上下文到调用栈全解析
前端·javascript
utmhikari1 小时前
【AI原生】用Vibe Coding写产品前端原型的一些经验
前端·ai·产品经理·web·web开发·ai-native·qoder
li星野1 小时前
从零搭建文件上传系统：FastAPI 后端 + Streamlit 前端
前端·状态模式·fastapi
YAwu111 小时前
手写一个符合 Promise/A+ 规范的 Promise（附完整代码）
前端·javascript
暗不需求1 小时前
从路虎汽车小程序看微信小程序开发的最佳实践
前端·javascript·微信小程序
用户059540174461 小时前
我把RAG对话记忆测试从手工用例改成ChromaDB自动化评估，Bug发现率翻了4倍
前端·css
热门推荐
01GitHub 镜像站点02【AI】2026 年具身智能模型和世界模型总结032026 年 AI 编程工具终极横评：Cursor vs Claude Code vs Copilot vs Windsurf04Codex 下载安装指南：Windows 和 macOS 官方版下载05Codex 桌面端更新后 Chrome 插件和 Computer Use 不可用，怎么排查和修复06CC-Switch 下载、安装与使用配置指南【2026.5.29】07【踩坑记录 | 第一篇】微软商店无法使用时，如何手动安装 OpenAI Codex？附`.msix`文件系统错误解决方法08CC-Switch & Claude 基于 Linux 服务器安装使用指南09Codex 接入 DeepSeek API 完整配置文档10裂开！ChatGPT 居然开始要手机号验证，附详细解决方法