GlitchTip：轻量级PHP错误监控，自托管也能用

你的生产环境又报错了，但用户只说"网站打不开"。你打开日志，几千行错误信息看得眼花缭乱，根本找不到关键信息。你需要一个错误监控平台——自动捕获异常、聚合分析、实时告警，让你在用户投诉前就解决问题。

Sentry 是行业标杆，但官方自托管最低要求 14GB 内存，很多机器跑不动。GlitchTip 是 Sentry 的轻量替代品：API 完全兼容 Sentry SDK，Docker 一键部署，最低 256MB 内存就能跑。

为什么选 GlitchTip

核心优势：轻量、自托管、兼容 Sentry SDK。对于不想把数据交给第三方、但又没有大服务器的团队来说，GlitchTip 是最实际的选择。

部署 GlitchTip

环境要求

• Docker + Docker Compose
• 512MB RAM（推荐），最低 256MB（all-in-one 模式）
• PostgreSQL 14+（Docker 自动拉取）

一键启动

下载 compose 文件：

GlitchTip 提供两种 compose 模板：

• compose.sample.yml — 生产模式（推荐，分离 web/worker）
• compose.minimal.yml — 精简模式（all-in-one，适合试用）

mkdir glitchtip && cd glitchtip

# 下载精简版模板（适合本地测试）
curl -sL https://glitchtip.com/assets/compose.minimal.yml -o docker-compose.yml

配置环境变量：

编辑 docker-compose.yml，修改以下几项：

版权声明：本文由phpreturn.com（PHP武器库官网）原创和首发，所有权利归phpreturn（PHP武器库）所有，本站允许任何形式的转载/引用文章，但必须同时注明出处。

x-environment: &default-environment
  DATABASE_URL: postgres://postgres:postgres@postgres:5432/postgres
  SECRET_KEY: # 改成随机字符串，下面有生成命令
  EMAIL_URL: consolemail:// # 测试时用这个，不发送邮件
  GLITCHTIP_DOMAIN: http://localhost:8000 # 改成你的域名
  DEFAULT_FROM_EMAIL: your@email.com

生成随机密钥：

openssl rand -hex 32
# 输出类似：27df5e89406889a37b52045ce8227da16bb6f667d932af34cb967a95a74301c8

启动：

docker compose up -d

第一次启动会自动：

1. 拉取 PostgreSQL 和 GlitchTip 镜像（约 160MB）
2. 初始化数据库（建表、迁移）
3. 启动 Web 服务

等待约 30 秒后访问 http://localhost:8000：

# 检查容器状态
docker compose ps
# 应该看到 2 个容器：glitchtip-deploy-postgres-1 和 glitchtip-deploy-web-1

# 检查日志确认启动完成
docker compose logs web | tail -5
# 看到 "Starting development server" 或 "Uvicorn running" 表示成功

启动后打开浏览器访问 http://localhost:8000，注册账号后进入组织页面：

版权声明：本文由phpreturn.com（PHP武器库官网）原创和首发，所有权利归phpreturn（PHP武器库）所有，本站允许任何形式的转载/引用文章，但必须同时注明出处。

创建项目和获取 DSN

1. 打开 http://localhost:8000，注册账号
2. 创建 Organization（组织）
3. 创建 Project（项目），选择平台为 PHP
4. 创建完成后进入项目 Settings > Client Keys (DSN)，复制 DSN 地址

DSN 格式类似：

http://xxxx@your-glitchtip-domain.com/project-id

重要：GlitchTip 的 API 与 Sentry 兼容，所以 PHP 项目使用 sentry/sdk 即可上报数据到 GlitchTip。

项目设置页展示了 DSN 地址、平台信息和环境配置：

快速开始：PHP SDK 接入

安装

composer require sentry/sdk:^4

注意：不是 sentry/sentry（那是 2015 年的旧包），也不是 sentry/sentry-laravel（那是 Laravel 专用包）。通用项目用 sentry/sdk，它依赖底层的 sentry/sentry:^4.24。

最小示例

<?php
require_once __DIR__ . '/vendor/autoload.php';

\Sentry\init([
    'dsn' => 'http://xxxx@localhost:8000/1',  // 替换成你的 DSN
    'environment' => 'production',
]);

// 手动捕获异常
try {
    throw new Exception('数据库连接失败');
} catch (\Exception $e) {
    $eventId = \Sentry\captureException($e);
    echo "已上报，Event ID: $eventId\n";
}

运行后去 GlitchTip 的 Issues 页面，应该能看到这条错误。

核心功能实战

1. 错误追踪（Error Tracking）

自动捕获未处理异常：

版权声明：本文由phpreturn.com（PHP武器库官网）原创和首发，所有权利归phpreturn（PHP武器库）所有，本站允许任何形式的转载/引用文章，但必须同时注明出处。

\Sentry\init([
    'dsn' => 'http://xxxx@localhost:8000/1',
]);

// 这个异常会被自动上报（如果注册了异常处理器）
throw new RuntimeException('Unexpected error');

手动捕获并附加上下文：

\Sentry\init(['dsn' => 'http://xxxx@localhost:8000/1']);

try {
    $user = User::findOrFail($id);
} catch (\Exception $e) {
    // 设置用户信息（知道谁遇到了问题）
    \Sentry\configureScope(function (\Sentry\State\Scope $scope) {
        $scope->setUser([
            'id' => auth()->id(),
            'email' => auth()->user()->email,
            'username' => auth()->user()->name,
        ]);
    });

    // 添加标签（便于筛选和分组）
    \Sentry\configureScope(function (\Sentry\State\Scope $scope) {
        $scope->setTag('page', 'checkout');
        $scope->setTag('shop_id', session('shop_id'));
        $scope->setExtra('order_id', $orderId);
    });

    $eventId = \Sentry\captureException($e);

    return response()->json(['error' => '操作失败', 'event_id' => $eventId], 500);
}

不同级别的消息上报：

// 严重错误 — 立即处理
\Sentry\captureMessage('支付网关超时', \Sentry\Severity::error());

// 警告 — 关注但不紧急
\Sentry\captureMessage('API 响应变慢', \Sentry\Severity::warning());

// 信息 — 仅记录
\Sentry\captureMessage('用户登录', \Sentry\Severity::info());

注意：Severity::error() 是方法调用（带括号），返回一个对象。不要写成 Severity::error（那是一个字符串常量）。

面包屑（Breadcrumb）— 记录用户操作路径：

\Sentry\addBreadcrumb(new \Sentry\Breadcrumb(
    \Sentry\Severity::INFO,      // 级别
    'user_action',               // 类型
    'user_action',               // 分类
    '点击了购买按钮',             // 消息
    ['product_id' => 123, 'price' => 99.9],  // 数据
));

面包屑会在错误详情中展示用户的操作轨迹，帮助复现问题。

2. 性能监控（Performance Monitoring）

GlitchTip 支持事务追踪，可以监控每个请求的耗时分布。

\Sentry\init([
    'dsn' => 'http://xxxx@localhost:8000/1',
    'traces_sample_rate' => 0.2,  // 只采样 20% 的请求（生产环境建议）
]);

// 开始一个事务（通常对应一次 HTTP 请求）
use Sentry\Tracing\TransactionContext;
$transaction = \Sentry\startTransaction(TransactionContext::make([
    'name' => '/api/users',
    'op'   => 'http.server',
]));

// 子操作：数据库查询
use Sentry\Tracing\SpanContext;
$dbSpan = $transaction->startChild(SpanContext::make([
    'op'          => 'db.query',
    'description' => 'SELECT * FROM users WHERE id = 1',
]));
$result = $db->query('SELECT * FROM users WHERE id = 1');
$dbSpan->finish();

// 子操作：HTTP 请求
$httpSpan = $transaction->startChild(SpanContext::make([
    'op'          => 'http.client',
    'description' => 'POST https://payment-api.com/charge',
]));
$response = Http::post('https://payment-api.com/charge', [...]);
$httpSpan->finish();

// 结束事务
$transaction->finish();

在 GlitchTip 的 Performance 页面可以看到：

版权声明：本文由phpreturn.com（PHP武器库官网）原创和首发，所有权利归phpreturn（PHP武器库）所有，本站允许任何形式的转载/引用文章，但必须同时注明出处。

• 慢请求排行（Web Vitals）
• 每个请求的 Span 分布（数据库查询、HTTP调用各占多少时间）
• 错误与性能的关联

3. Release 版本追踪

\Sentry\init([
    'dsn'     => 'http://xxxx@localhost:8000/1',
    'release' => '1.0.0',       // 版本号
]);

设置后，GlitchTip 会按版本统计错误数量。发布新版本后可以快速判断是否引入了新 Bug。

错误详情页能看到什么

这是 GlitchTip 最有价值的地方——每条错误都包含完整的上下文信息。点击任意一条 Issue 进入详情页：

从上图中可以看到：

有了这些信息，大部分问题不需要复现就能定位原因。

框架集成

Laravel

composer require sentry/sentry-laravel

# .env
SENTRY_LARAVEL_DSN=http://xxxx@localhost:8000/1

Laravel 包会自动：

版权声明：本文由phpreturn.com（PHP武器库官网）原创和首发，所有权利归phpreturn（PHP武器库）所有，本站允许任何形式的转载/引用文章，但必须同时注明出处。

• 监听 Exception Handler 自动上报
• 记录 SQL 查询作为 Span
• 集合队列任务错误

ThinkPHP

ThinkPHP 没有官方 SDK 包，但通用 SDK 完全可用。推荐在异常处理类中集成：

// app/ExceptionHandle.php
<?php
namespace app;

use Sentry\State\Scope;
use Sentry\Severity;

class ExceptionHandle extends Handle
{
    public function render(\Throwable $e)
    {
        // 上报到 GlitchTip
        if (env('GLITCHTIP_DSN')) {
            \Sentry\captureException($e);
        }

        // 开发环境显示详细错误
        if (app()->isDebug()) {
            return parent::render($e);
        }

        // 生产环境返回友好页面
        return json(['error' => '服务器内部错误']);
    }
}

入口文件初始化：

// public/index.php
require __DIR__ . '/../vendor/autoload.php';

if (env('GLITCHTIP_DSN')) {
    \Sentry\init([
        'dsn' => env('GLITCHTIP_DSN'),
        'environment' => env('APP_ENV', 'production'),
        'release' => app()->version,
    ]);
}

// ... 后续框架启动代码

通用框架（原生 PHP）

任何 PHP 项目都可以用，只需要：

1. composer require sentry/sdk
2. 在入口文件 \Sentry\init()
3. 在 catch 块中 \Sentry\captureException()

部署建议

本地开发 / 测试

用 compose.minimal.yml（all-in-one 模式），256MB 内存就够：

# docker-compose.yml 关键配置
services:
  web:
    image: glitchtip/glitchtip:6
    environment:
      SERVER_ROLE: all_in_one  # 关键：合并 web + worker
    ports:
      - "8000:8000"

生产环境

用 compose.sample.yml（分离模式），推荐配置：

• PostgreSQL 用外部托管的服务（如 RDS）
• Valkey（Redis 替代）启用缓存加速
• Nginx 反向代理 + SSL
• 定期备份数据库

# 升级
docker compose pull
docker compose up -d
# 数据库迁移自动执行

最佳实践

1. 采样率节省资源

'traces_sample_rate' => env('SENTRY_TRACES_SAMPLE_RATE', 0.1),  // 性能监控只采 10%
'sample_rate'       => 1.0,  // 错误监控 100%（关键错误不能漏）

2. 错误分级

// 致命错误 — 立即通知
\Sentry\captureMessage('支付失败', Severity::error());

// 降级功能 — 记录即可
\Sentry\captureMessage('推荐服务降级', Severity::warning());

// 业务事件 — 信息级别
\Sentry\captureMessage('VIP用户注册', Severity::info());

3. 忽略不需要的错误

\Sentry\init([
    'dsn'           => 'http://xxxx@localhost:8000/1',
    'ignore_errors' => [
        E_NOTICE,
        E_WARNING,
        E_USER_NOTICE,
        // 第三方库的预期内错误
        '^Symfony\\\\Component\\\\Http\\\\Exception\\\\NotFoundHttpException$',
    ],
]);

4. Before Send 过滤敏感信息

\Sentry\init([
    'dsn' => 'http://xxxx@localhost:8000/1',
    'before_send' => function (\Sentry\Event $event): ?\Sentry\Event {
        // 移除密码字段
        if ($event->getRequest()) {
            $event->getRequest()->headers->delete('Authorization');
        }
        return $event;
    },
]);

常见问题

Q: GlitchTip 和 Sentry 的 SDK 互通吗？

完全互通。 GlitchTip 兼容 Sentry 的协议和 API，所以 sentry/sdk 上报的数据两个平台都能接收。你可以随时在两者之间切换，代码不用改。

版权声明：本文由phpreturn.com（PHP武器库官网）原创和首发，所有权利归phpreturn（PHP武器库）所有，本站允许任何形式的转载/引用文章，但必须同时注明出处。

Q: 内存真的只要 512MB 吗？

是的。GlitchTip 官方推荐配置是 512MB RAM，all-in-one 模式最低 256MB。对比 Sentry 需要 7-14GB，差距很大。当然，流量大的实例建议给更多内存。

Q: 数据存哪里？

默认存在 Docker volume（PostgreSQL 数据目录）。你可以：

• 备份整个 volume
• 配置冷存储（GlitchTip 支持 DuckDB + Parquet 归档到 S3 或本地磁盘）
• 设置保留天数（默认 90 天）

Q: 可以用 MySQL 吗？

不行，GlitchTip 只支持 PostgreSQL 14+。但 Docker 会自动拉取并运行 PostgreSQL，你不需要单独安装。

Q: 如何升级？

docker compose pull     # 拉取新镜像
docker compose up -d    # 重启（数据库迁移自动执行）

总结

GlitchTip 让自托管错误监控变得触手可及：

• 轻量：512MB 内存，Docker 一键启动
• 兼容：直接用 Sentry PHP SDK，代码无需特殊适配
• 功能完整：错误追踪、性能监控、Release 追踪、面包屑
• 自主可控：数据在你自己的服务器上

部署清单：

1. docker compose up -d 启动 GlitchTip（5 分钟）
2. composer require sentry/sdk:^4 安装 PHP SDK（1 分钟）
3. 三行代码接入（\Sentry\init + captureException）（1 分钟）
4. 收到第一个错误，打开 Dashboard 查看

本文基于 GlitchTip v6 + sentry/sdk v4.24 实测编写，所有代码均在 PHP 8.4 环境下验证通过。

版权声明：本文由phpreturn.com（PHP武器库官网）原创和首发，所有权利归phpreturn（PHP武器库）所有，本站允许任何形式的转载/引用文章，但必须同时注明出处。

原文标题： GlitchTip：轻量级PHP错误监控，自托管也能用

原文地址： https://phpreturn.com/index/a6a16868c17cff.html

原文平台： PHP武器库

版权声明： 本文由phpreturn.com（PHP武器库官网）原创和首发，所有权利归phpreturn（PHP武器库）所有，本站允许任何形式的转载/引用文章，但必须同时注明出处。