249 lines
6.7 KiB
Markdown
249 lines
6.7 KiB
Markdown
# Sentry Self-Hosted - 崩溃收集与错误追踪
|
|
|
|
100% 自主可控的崩溃收集与错误追踪系统。
|
|
|
|
## 功能特性
|
|
|
|
- **崩溃收集**: 自动捕获 Flutter + Android/iOS 原生层崩溃
|
|
- **符号化**: 自动解析混淆后的堆栈，定位到源代码
|
|
- **设备信息**: 收集设备型号、系统版本、内存等兼容性信息
|
|
- **性能监控**: 页面加载、API 响应时间等性能指标
|
|
- **Session Replay**: 重放用户操作轨迹（可选）
|
|
- **告警通知**: 崩溃告警推送到邮件/钉钉等
|
|
|
|
## 系统要求
|
|
|
|
- Docker 20.10+
|
|
- Docker Compose v2+
|
|
- **最低 4GB 内存，推荐 8GB+**
|
|
- 约 20GB 磁盘空间
|
|
|
|
## 快速开始
|
|
|
|
### 1. 首次安装
|
|
|
|
```bash
|
|
cd backend/infrastructure/sentry
|
|
|
|
# 初始化 (会创建管理员账号)
|
|
./deploy.sh init
|
|
```
|
|
|
|
按提示输入管理员邮箱和密码。
|
|
|
|
### 2. 启动服务
|
|
|
|
```bash
|
|
./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 配置
|
|
```
|
|
|
|
## 常用命令
|
|
|
|
```bash
|
|
# 启动
|
|
./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` 文件:
|
|
|
|
```bash
|
|
# 生成强密钥
|
|
SENTRY_SECRET_KEY=$(openssl rand -hex 32)
|
|
SENTRY_DB_PASSWORD=$(openssl rand -hex 16)
|
|
```
|
|
|
|
### 2. 配置域名
|
|
|
|
如果需要公网访问，配置反向代理:
|
|
|
|
```nginx
|
|
# /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` 文件:
|
|
|
|
```bash
|
|
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`:
|
|
|
|
```python
|
|
# 事件保留天数 (默认 90 天)
|
|
SENTRY_OPTIONS["system.event-retention-days"] = 30
|
|
```
|
|
|
|
## Flutter 端集成
|
|
|
|
详见 `frontend/mobile-app` 目录下的集成代码。
|
|
|
|
简要步骤:
|
|
|
|
1. 添加依赖:
|
|
```yaml
|
|
dependencies:
|
|
sentry_flutter: ^8.0.0
|
|
```
|
|
|
|
2. 初始化:
|
|
```dart
|
|
await SentryFlutter.init(
|
|
(options) {
|
|
options.dsn = 'http://your_key@your-server:9000/project_id';
|
|
},
|
|
appRunner: () => runApp(MyApp()),
|
|
);
|
|
```
|
|
|
|
## 故障排查
|
|
|
|
### 服务无法启动
|
|
|
|
检查内存是否足够:
|
|
```bash
|
|
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 官方文档](https://docs.sentry.io/)
|
|
- [Self-Hosted 安装指南](https://develop.sentry.dev/self-hosted/)
|
|
- [sentry_flutter SDK](https://pub.dev/packages/sentry_flutter)
|