rwadurian/backend/infrastructure/sentry/README.md

Sentry Self-Hosted - 崩溃收集与错误追踪

100% 自主可控的崩溃收集与错误追踪系统。

功能特性

• 崩溃收集: 自动捕获 Flutter + Android/iOS 原生层崩溃
• 符号化: 自动解析混淆后的堆栈，定位到源代码
• 设备信息: 收集设备型号、系统版本、内存等兼容性信息
• 性能监控: 页面加载、API 响应时间等性能指标
• Session Replay: 重放用户操作轨迹（可选）
• 告警通知: 崩溃告警推送到邮件/钉钉等

系统要求

• Docker 20.10+
• Docker Compose v2+
• 最低 4GB 内存，推荐 8GB+
• 约 20GB 磁盘空间

快速开始

1. 首次安装

cd backend/infrastructure/sentry

# 初始化 (会创建管理员账号)
./deploy.sh init

按提示输入管理员邮箱和密码。

2. 启动服务

./deploy.sh up

3. 访问 Web UI

打开浏览器访问: http://localhost:9000

使用初始化时创建的管理员账号登录。

4. 创建项目

1. 登录后点击 "Create Project"
2. 选择平台: Flutter
3. 记录生成的 DSN (Data Source Name)

DSN 格式示例:

http://your_public_key@localhost:9000/project_id

目录结构

sentry/
├── docker-compose.yml      # Docker 编排
├── deploy.sh               # 部署脚本
├── .env.example            # 环境变量模板
├── sentry.conf.py          # Sentry 配置
├── README.md               # 本文档
│
├── clickhouse/
│   └── config.xml          # ClickHouse 配置
│
├── relay/
│   ├── config.yml          # Relay 配置
│   └── credentials.json    # Relay 凭证
│
└── symbolicator/
    └── config.yml          # Symbolicator 配置

常用命令

# 启动
./deploy.sh up

# 停止
./deploy.sh down

# 查看状态
./deploy.sh status

# 查看日志
./deploy.sh logs
./deploy.sh logs sentry-web

# 升级
./deploy.sh upgrade

架构说明

                                    ┌─────────────────┐
                                    │   Flutter App   │
                                    │  sentry_flutter │
                                    └────────┬────────┘
                                             │
                                             ▼
┌─────────────────────────────────────────────────────────────────────┐
│                            Sentry Relay                              │
│                         (事件接收网关 :3000)                          │
└────────────────────────────────┬────────────────────────────────────┘
                                 │
         ┌───────────────────────┼───────────────────────┐
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐   ┌─────────────────┐   ┌─────────────────┐
│      Kafka      │   │   Sentry Web    │   │  Symbolicator   │
│   (事件队列)     │   │  (Web UI :9000) │   │   (符号化服务)   │
└────────┬────────┘   └────────┬────────┘   └─────────────────┘
         │                     │
         │            ┌────────┴────────┐
         │            │                 │
         ▼            ▼                 ▼
┌─────────────────┐   ┌─────────────────┐
│    ClickHouse   │   │   PostgreSQL    │
│   (事件存储)     │   │   (元数据)       │
└─────────────────┘   └─────────────────┘

生产环境配置

1. 修改密钥

编辑 .env 文件:

# 生成强密钥
SENTRY_SECRET_KEY=$(openssl rand -hex 32)
SENTRY_DB_PASSWORD=$(openssl rand -hex 16)

2. 配置域名

如果需要公网访问，配置反向代理:

# /etc/nginx/conf.d/sentry.conf
server {
    listen 443 ssl;
    server_name sentry.your-domain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:9000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

# Relay 端口 (SDK 上报)
server {
    listen 443 ssl;
    server_name sentry-relay.your-domain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

3. 配置邮件告警

编辑 .env 文件:

SENTRY_EMAIL_HOST=smtp.example.com
SENTRY_EMAIL_PORT=587
SENTRY_EMAIL_USER=your-email@example.com
SENTRY_EMAIL_PASSWORD=your-password
SENTRY_EMAIL_USE_TLS=true
SENTRY_SERVER_EMAIL=sentry@your-domain.com

4. 数据保留策略

编辑 sentry.conf.py:

# 事件保留天数 (默认 90 天)
SENTRY_OPTIONS["system.event-retention-days"] = 30

Flutter 端集成

详见 frontend/mobile-app 目录下的集成代码。

简要步骤:

1. 添加依赖:

dependencies:
  sentry_flutter: ^8.0.0

2. 初始化:

await SentryFlutter.init(
  (options) {
    options.dsn = 'http://your_key@your-server:9000/project_id';
  },
  appRunner: () => runApp(MyApp()),
);

故障排查

服务无法启动

检查内存是否足够:

free -h
docker stats

事件未上报

1. 检查 DSN 是否正确
2. 检查网络连通性
3. 查看 Relay 日志: ./deploy.sh logs sentry-relay

符号化失败

1. 确保上传了符号文件 (Android: mapping.txt, iOS: dSYM)
2. 检查 Symbolicator 日志: ./deploy.sh logs sentry-symbolicator

参考链接

• Sentry 官方文档
• Self-Hosted 安装指南
• sentry_flutter SDK