Vite+React项目Sentry本地部署全攻略

1. 项目概述

作为一名长期奋战在一线的前端开发者，我深知错误监控对于项目稳定性的重要性。最近在为一个Vite+React项目搭建本地Sentry监控系统时，经历了从环境准备到问题排查的全过程。本文将详细记录这次部署的完整历程，特别是那些官方文档没有提及的"坑"和解决方案。

Sentry作为一款开源的错误监控工具，能够帮助我们实时捕获前端运行时错误、记录完整的堆栈信息，并与具体用户、版本和环境关联。与SaaS版本相比，本地部署的Sentry更适合企业级应用，既能满足数据隐私要求，又能根据业务需求进行深度定制。

2. 环境准备与基础配置

2.1 系统要求检查

在开始部署前，必须确保系统满足以下最低要求：

• Docker版本：20.10.0+
• Docker Compose：1.29.0+
• 可用内存：14GB以上
• 磁盘空间：至少50GB可用空间

提示：内存不足是新手最常见的失败原因。在Mac上，可以通过Docker Desktop的Preferences → Resources调整内存分配。

2.2 获取Sentry自托管代码库

官方推荐的self-hosted仓库包含了完整的部署配置：

bash复制git clone https://github.com/getsentry/self-hosted.git
cd self-hosted

这个仓库实际上是一个Docker Compose项目的模板，包含了Sentry及其所有依赖服务（PostgreSQL、Redis、Kafka、ClickHouse等）的配置。

2.3 初始化安装脚本

运行安装脚本将自动完成以下操作：

bash复制./install.sh

这个脚本会：

1. 检查系统环境是否符合要求
2. 拉取所有必要的Docker镜像
3. 初始化数据库和配置文件
4. 启动所有服务容器

3. 常见安装问题与解决方案

3.1 Docker镜像拉取失败

问题现象：

bash复制#3 ERROR: failed to authorize: DeadlineExceeded: failed to fetch oauth token

解决方案（国内用户特别有用）：

1. 配置Docker镜像加速器：

bash复制# 创建或修改daemon.json
vim ~/.docker/daemon.json

# 添加以下内容
{
  "registry-mirrors": [
    "https://docker.mirrors.ustc.edu.cn",
    "https://mirror.ccs.tencentyun.com"
  ]
}

2. 重启Docker服务后重试安装。

3.2 内存不足错误

错误信息：

bash复制FAIL: Required minimum RAM available to Docker is 14000 MB, found 7837 MB

解决方法：

1. 在Docker Desktop中调整内存分配至16GB
2. 确保没有其他内存密集型应用在运行
3. 对于Linux系统，可能需要调整swappiness参数：

bash复制sudo sysctl vm.swappiness=10

3.3 Bash版本过低（Mac特有）

错误信息：

bash复制FAIL: Expected minimum bash version to be 4.4.0 but found 3.2.57(1)-release

完整解决方案：

bash复制# 安装新版Bash
brew install bash

# 验证版本
/opt/homebrew/bin/bash --version

# 设置为默认shell
sudo sh -c 'echo /opt/homebrew/bin/bash >> /etc/shells'
chsh -s /opt/homebrew/bin/bash

# 重新登录后验证
bash --version

4. 核心服务依赖解析

4.1 Sentry架构组成

Sentry self-hosted实际上是一个微服务架构，包含以下核心组件：

4.2 服务启动顺序的重要性

正确的启动顺序应该是：

1. 基础存储服务：PostgreSQL、Redis
2. 消息系统：Zookeeper → Kafka
3. 分析数据库：ClickHouse
4. 上层服务：Snuba → Web/Worker

错误示例（会导致Web unhealthy）：

bash复制# 错误：一次性启动所有服务
docker compose up -d

正确做法：

bash复制# 分阶段启动
docker compose up -d postgres redis zookeeper
docker compose up -d kafka clickhouse
docker compose up -d snuba-api
docker compose run --rm web upgrade
docker compose up -d

5. Web Unhealthy问题深度解析

5.1 现象描述

即使所有容器都显示为"running"，Web服务仍可能处于unhealthy状态。这是因为Docker的健康检查不仅检查进程是否存在，还会检查API端点是否响应。

5.2 根本原因

Web服务健康检查依赖多个底层服务：

1. 数据库迁移是否完成
2. Kafka主题是否创建
3. Snuba是否初始化完成
4. ClickHouse连接是否正常

5.3 解决方案

完整恢复流程：

bash复制# 1. 停止所有服务
docker compose stop

# 2. 启动基础服务
docker compose up -d postgres redis kafka clickhouse

# 3. 初始化Snuba
docker compose run --rm snuba-api bootstrap --force

# 4. 执行数据库迁移
docker compose run --rm web upgrade

# 5. 启动全部服务
docker compose up -d

5.4 关键命令：web upgrade

这个命令实际上执行了以下操作：

python复制# 伪代码表示实际执行流程
def upgrade():
    apply_database_migrations()
    create_kafka_topics()
    initialize_snuba()
    create_default_users()
    setup_initial_projects()

6. 日常运维最佳实践

6.1 正确的启停方式

推荐方案（保持状态）：

bash复制# 暂停服务
docker compose stop

# 恢复服务
docker compose start

替代方案（需要重新初始化）：

bash复制# 完整重启流程
docker compose down
docker compose up -d postgres redis kafka clickhouse
docker compose run --rm snuba-api bootstrap --force
docker compose run --rm web upgrade
docker compose up -d

6.2 数据备份策略

由于Sentry使用多种存储后端，备份需要覆盖：

bash复制# PostgreSQL备份
docker compose exec postgres pg_dump -U postgres sentry > sentry_db.sql

# Redis备份
docker compose exec redis redis-cli SAVE
cp ./data/redis/dump.rdb ./backup/

# ClickHouse备份
docker compose exec clickhouse clickhouse-client --query="BACKUP DATABASE sentry TO Disk('backup', 'sentry_backup')"

6.3 日志收集与分析

建议配置日志聚合：

bash复制# 查看实时日志
docker compose logs -f --tail=100 web

# 导出日志到文件
docker compose logs --no-color > sentry_logs.txt

7. 前端项目接入指南

7.1 Vite+React项目配置

安装必要的包：

bash复制npm install --save @sentry/react @sentry/tracing

创建sentry.client.config.js：

javascript复制import * as Sentry from '@sentry/react';
import { BrowserTracing } from '@sentry/tracing';

Sentry.init({
  dsn: 'http://your-local-sentry-dsn',
  integrations: [new BrowserTracing()],
  tracesSampleRate: 0.2,
  environment: 'development',
  release: 'your-project@1.0.0'
});

7.2 SourceMap上传配置

在vite.config.js中添加：

javascript复制import { sentryVitePlugin } from "@sentry/vite-plugin";

export default {
  plugins: [
    sentryVitePlugin({
      org: "your-org",
      project: "your-project",
      authToken: process.env.SENTRY_AUTH_TOKEN,
      sourcemaps: {
        assets: "./dist/**"
      }
    })
  ]
}

8. 性能优化与调优

8.1 资源分配建议

对于开发环境，推荐的最小资源配置：

8.2 关键参数调整

在.env文件中可以配置：

ini复制# Kafka内存调整
KAFKA_HEAP_OPTS=-Xmx4g -Xms4g

# ClickHouse配置
CLICKHOUSE_MAX_MEMORY_USAGE=8G
CLICKHOUSE_MAX_CONCURRENT_QUERIES=20

9. 监控与告警配置

9.1 内置健康检查端点

bash复制# Web健康检查
curl http://localhost:9000/_health/

# 服务状态API
curl -H "Authorization: Bearer YOUR_TOKEN" \
  http://localhost:9000/api/0/relays/status/

9.2 自定义告警规则

在sentry.conf.py中添加：

python复制SENTRY_FEATURES['projects:alert-rules'] = True

# 示例规则：5分钟内相同错误超过10次触发告警
{
  "conditions": [
    ["count()", ">", 10]
  ],
  "actionMatch": "all",
  "actions": [
    {
      "type": "email",
      "targetType": "team",
      "targetIdentifier": "dev-team"
    }
  ],
  "frequency": 5
}

10. 故障排查手册

10.1 常见问题速查表

10.2 高级诊断命令

检查Kafka主题：

bash复制docker compose exec kafka kafka-topics --list --bootstrap-server localhost:9092

测试ClickHouse连接：

bash复制docker compose exec clickhouse clickhouse-client --query="SHOW DATABASES"

验证Snuba：

bash复制curl http://localhost:1218/health

经过这次完整的部署实践，我深刻体会到Sentry作为一个企业级监控系统的复杂性。关键在于理解其微服务架构的依赖关系，掌握正确的服务启停顺序，并建立完善的监控机制来确保系统稳定运行。对于前端开发者而言，能够自主搭建和维护这样一套系统，无疑会大大提升项目的可观测性和稳定性保障能力。