VPS 自建 Sentry 错误监控平台（2026）：Docker、HTTPS、SDK 接入、告警、备份与升级

可以，但要先接受两个现实：

• 官方把 Self-Hosted 定位为低流量部署和概念验证，不是 Sentry SaaS 的零运维替代品；
• 完整功能栈包含 PostgreSQL、ClickHouse、Kafka、Valkey、Relay、Snuba、Symbolicator、SeaweedFS 等多个组件，对内存、磁盘 I/O 和运维能力要求明显高于普通博客。

适合自建的场景包括：

• 错误事件不能发送到第三方 SaaS；
• 团队需要掌控数据保留期限和存储位置；
• 内网服务无法访问公有 Sentry；
• 已有专人维护 Docker、数据库、备份和告警；
• 事件量较低，但希望统一 JavaScript、Python、Java、移动端等项目的错误入口。

如果团队只有一个小项目、没有值班与恢复能力，托管版通常更省钱。自建节省的是订阅或数据外发成本，却增加了 VPS、备份、升级和故障处理成本。

合理组合是：Uptime Kuma 发现“网站打不开”，Sentry 告诉你“哪个 Release 的哪行代码报错”，日志平台补全前后请求。若还没有外部存活探测，可先部署 Uptime Kuma 监控面板。

26.8.0 源码中的安装检查给出了两组硬门槛：

官方文档当前推荐 4 核、16 GB RAM、20 GB 可用磁盘。20 GB 只是可用空间基线，不是长期容量规划；事件、附件、Replay、profile、ClickHouse 和 Kafka 都会增长。生产环境建议从 100–200 GB NVMe 起步，并按每日事件量与保留天数观察。

8 GB VPS 即使勉强通过 errors-only 边缘配置，也几乎没有给宿主机和 Docker 留余量。不要依赖大量 swap 把内存不足伪装成可用：ClickHouse 和 Kafka 在持续 swap 时，延迟和故障概率都会明显上升。

Sentry 的主要流量来自 SDK 上报，而不是用户打开后台。粗略估算：

月上行流量 ≈ 平均事件大小 × 每日事件数 × 30

例如平均事件 20 KB、每天 10 万条，原始上报约 60 GB/月；附件、Replay、Source Map 和协议开销会继续增加。VPS 至少需要稳定公网、低丢包和足够月流量。真正容易先耗尽的通常是磁盘和内存，而不是带宽。

SDK 必须设置采样率、过滤预期异常并避免上传敏感字段，否则一次错误循环可能在几分钟内制造大量重复事件。

本文使用官方 getsentry/self-hosted 仓库，不手写整套 Compose。流量路径如下：

应用 SDK
  ↓ HTTPS 443
Caddy（宿主机 TLS）
  ↓ 127.0.0.1:9000
官方 nginx / Relay
  ↓
Sentry Web + Worker + Snuba
  ↓
PostgreSQL / ClickHouse / Kafka / Valkey / SeaweedFS

只让 Caddy 暴露 80/443；Sentry 自带 nginx 绑定到 127.0.0.1:9000。数据库和消息队列均停留在 Docker 网络内。

准备独立域名，例如 sentry.example.com，将 A/AAAA 记录解析到 VPS。公网只开放：

• 22/tcp：SSH，限制管理 IP；
• 80/tcp：Caddy 申请证书和 HTTP 跳转；
• 443/tcp 与 443/udp：HTTPS/HTTP3；
• 9000/tcp：只监听 127.0.0.1，不开放防火墙；
• PostgreSQL、ClickHouse、Kafka、Valkey：不映射公网端口。

检查解析：

export SENTRY_DOMAIN="sentry.example.com"
getent ahosts "$SENTRY_DOMAIN"
curl -4 https://ifconfig.me

如果同时配置 AAAA，必须确保 IPv6 也能到达这台服务器；否则证书签发和客户端连接可能随机失败。

sudo apt-get update
sudo apt-get install -y ca-certificates curl git jq rsync
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list >/dev/null

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker
sudo docker version
sudo docker compose version

26.8.0 源码要求 Docker 至少 19.03.6、Compose 至少 2.32.2、Bash 至少 4.4。新装 Ubuntu 使用当前 Docker 官方仓库通常能满足，但仍应以命令输出为准。

如果要系统理解 healthcheck、日志和资源限制，可参考 Docker Compose 生产环境配置。

nproc
free -h
df -h /
df -i /
uname -a
sysctl vm.max_map_count

为 ClickHouse 设置 vm.max_map_count：

echo 'vm.max_map_count=262144' | sudo tee /etc/sysctl.d/90-sentry.conf
sudo sysctl --system
sysctl vm.max_map_count

确保 Docker 数据目录位于空间足够的 NVMe 分区。若需要迁移 /var/lib/docker，应先停机并验证备份，不要在已有 Sentry 数据后直接修改 daemon 配置。

sudo install -d -o "$USER" -g "$USER" -m 0750 /opt/sentry
cd /opt/sentry

git clone https://github.com/getsentry/self-hosted.git
cd self-hosted
git fetch --tags
git checkout 26.8.0
git status --short
git describe --tags --exact-match

最后一个命令应输出 26.8.0。生产服务器不要运行 master/nightly，因为配置和镜像可能在没有升级说明的情况下变化。

如果只需要异常、Issue、Release 和基础告警，优先使用 errors-only，可以减少容器数量和资源占用。需要完整性能、Replay、profile、uptime 等能力时再选 feature-complete。

用 .env.custom 保存少量覆盖项，不要复制整个 .env；完整复制会把旧版本镜像 tag 一并固定，之后升级容易继续引用旧默认值。

cd /opt/sentry/self-hosted

LAUNCHPAD_SECRET="$(openssl rand -hex 32)"
umask 077
cat >.env.custom <<EOF
COMPOSE_PROFILES=errors-only
SENTRY_BIND=127.0.0.1:9000
SENTRY_EVENT_RETENTION_DAYS=30
SENTRY_MAIL_HOST=example.com
SENTRY_TASKWORKER_CONCURRENCY=2
LAUNCHPAD_RPC_SHARED_SECRET=${LAUNCHPAD_SECRET}
EOF
unset LAUNCHPAD_SECRET
chmod 600 .env.custom

完整功能 VPS 把 COMPOSE_PROFILES 改为 feature-complete，并根据内存压力调整 taskworker 并发。并发越高内存占用越多，不要照抄高配机器参数。

先查看改动与固定 tag，再运行安装器：

cd /opt/sentry/self-hosted
git status --short
sudo ./install.sh --no-report-self-hosted-issues

安装器会检查资源与版本、创建持久化 volume、生成配置与密钥、构建本地镜像、初始化 PostgreSQL/ClickHouse/Kafka/SeaweedFS，并运行数据库迁移。首次安装耗时可能超过十分钟。

启动时同时加载默认和自定义环境文件：

cd /opt/sentry/self-hosted
sudo docker compose --env-file .env --env-file .env.custom up --wait
sudo docker compose --env-file .env --env-file .env.custom ps
sudo docker compose --env-file .env --env-file .env.custom logs --tail=200 web relay nginx

不要因为某个容器处于 starting 就连续重启整套栈。先看 healthcheck 和对应依赖的日志。

安装器首次运行后会从 sentry/config.example.yml 生成 sentry/config.yml。编辑实际文件，至少配置公网 URL 和可用邮件服务器：

mail.backend: "smtp"
mail.host: "smtp.example.com"
mail.port: 587
mail.username: "[email protected]"
mail.password: "replace-with-app-password"
mail.use-tls: true

system.url-prefix: "https://sentry.example.com"
system.internal-url-prefix: "http://web:9000"

mail.use-tls 与 mail.use-ssl 只能选一个。配置文件包含 SMTP 密码，应设置权限并排除在外部代码仓库之外：

cd /opt/sentry/self-hosted
sudo chmod 600 sentry/config.yml
sudo docker compose --env-file .env --env-file .env.custom up -d

26.6.0 起自托管版要求新增邮箱先完成验证，因此生产环境不应继续使用 dummy mail backend。先发送测试邮件，再邀请团队成员。

如果已经安装 Caddy，可直接创建站点配置。否则按照 Caddy 官方仓库安装：

sudo apt-get install -y debian-keyring debian-archive-keyring apt-transport-https curl gnupg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list >/dev/null
sudo apt-get update
sudo apt-get install -y caddy

创建 /etc/caddy/Caddyfile：

sentry.example.com {
    encode zstd gzip

    reverse_proxy 127.0.0.1:9000 {
        header_up Host {host}
        header_up X-Real-IP {remote_host}
        header_up X-Forwarded-For {remote_host}
        header_up X-Forwarded-Proto {scheme}

        transport http {
            read_timeout 90s
            write_timeout 90s
        }
    }

    log {
        output file /var/log/caddy/sentry-access.log
        format json
    }
}

校验并加载：

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
sudo systemctl status caddy --no-pager
curl -fsSI https://sentry.example.com/

反向代理和自动证书的完整排查方法见 Caddy HTTPS 教程。

cd /opt/sentry/self-hosted
sudo ./sentry-admin.sh createuser

按提示输入邮箱、密码并创建 superuser。完成后访问 https://sentry.example.com，创建 Organization 与 Project。管理员账号启用强密码和双因素认证，不要让应用 SDK 或 CI 使用管理员 token。

set -euo pipefail
cd /opt/sentry/self-hosted

curl -fsS http://127.0.0.1:9000/_health/
curl -fsSI https://sentry.example.com/
sudo docker compose --env-file .env --env-file .env.custom ps
sudo docker compose --env-file .env --env-file .env.custom logs --since=10m --tail=300 web relay snuba-api

本地健康接口应返回 ok。若页面能打开但事件始终不出现，重点检查 Relay、Kafka consumer、Snuba 与 ClickHouse，而不是只看 web 容器。

在 Sentry 项目 Settings → Client Keys (DSN) 复制当前项目 DSN。前端安装 SDK：

npm install @sentry/browser

import * as Sentry from "@sentry/browser";

Sentry.init({
  dsn: "https://[email protected]/PROJECT_ID",
  environment: "production",
  release: "[email protected]",
  tracesSampleRate: 0.1,
  beforeSend(event) {
    if (event.request?.headers) {
      delete event.request.headers.Authorization;
      delete event.request.headers.Cookie;
    }
    return event;
  },
});

用测试异常验证：

try {
  throw new Error("sentry-self-hosted-test");
} catch (error) {
  Sentry.captureException(error);
}

生产环境不要使用 tracesSampleRate: 1.0 作为默认值。采样比例应根据请求量、VPS 容量和排障价值设定。

python3 -m pip install --upgrade sentry-sdk

import os
import sentry_sdk

sentry_sdk.init(
    dsn=os.environ["SENTRY_DSN"],
    environment=os.getenv("APP_ENV", "production"),
    release=os.getenv("APP_RELEASE", "[email protected]"),
    traces_sample_rate=0.1,
    send_default_pii=False,
)

def divide(a: int, b: int) -> float:
    return a / b

divide(1, 0)

运行后确认 Issue 中显示正确 environment、release 和堆栈。DSN 不是管理员密码，但仍应按项目管理；真正的 Auth Token 必须放在 Secret Manager。

如果压缩后的前端代码没有 Source Map，Sentry 只会显示难以定位的 bundle 行列。发布时必须让 SDK 的 release 与上传 Source Map 的 release 完全一致。

GitHub Actions 示例：

name: build-and-upload-sourcemaps

on:
  push:
    tags:
      - "v*"

permissions:
  contents: read

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      SENTRY_URL: "https://sentry.example.com/"
      SENTRY_ORG: "example-org"
      SENTRY_PROJECT: "web"
      SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "22"
          cache: npm
      - run: npm ci
      - run: npm run build
      - name: Upload source maps
        run: |
          set -euo pipefail
          VERSION="web@${GITHUB_REF_NAME}"
          npx --yes @sentry/cli releases new "$VERSION"
          npx --yes @sentry/cli sourcemaps inject ./dist
          npx --yes @sentry/cli sourcemaps upload --release "$VERSION" ./dist
          npx --yes @sentry/cli releases finalize "$VERSION"

第三方 Action 和 npm 工具应按供应链策略固定版本或 commit SHA。Auth Token 只授予发布所需权限，不能复用管理员 token，也不要在日志里打印。

如果构建在 Jenkins，流程与 GitHub Actions 相同：构建产物、Release 名和 Source Map 上传必须在同一流水线中完成。

pipeline {
  agent any
  environment {
    SENTRY_URL = 'https://sentry.example.com/'
    SENTRY_ORG = 'example-org'
    SENTRY_PROJECT = 'web'
  }
  stages {
    stage('Build and upload source maps') {
      steps {
        withCredentials([string(credentialsId: 'sentry-auth-token', variable: 'SENTRY_AUTH_TOKEN')]) {
          sh '''
            set -euo pipefail
            npm ci
            npm run build
            VERSION="web@${GIT_COMMIT}"
            npx --yes @sentry/cli releases new "$VERSION"
            npx --yes @sentry/cli sourcemaps inject ./dist
            npx --yes @sentry/cli sourcemaps upload --release "$VERSION" ./dist
            npx --yes @sentry/cli releases finalize "$VERSION"
          '''
        }
      }
    }
  }
}

自建 Jenkins 的凭据隔离与 Agent 配置可参考 Jenkins CI/CD 教程。

建议先建立三层规则：

• P1：生产环境首次出现、影响用户多或错误率突增，立即通知；
• P2：已知 Issue 回归、连续触发或影响关键交易，5–15 分钟聚合；
• P3：开发/测试环境或低频错误，仅进入每日摘要。

每条 Issue 都应有 owner、environment、release 和响应动作。不要把所有新 Issue 都发到一个群；告警风暴会让真正故障被忽略。

在 SDK 端过滤浏览器插件噪声、爬虫、主动取消和预期业务异常；在服务端使用 inbound filters 与采样控制。过滤规则上线前先观察命中，不要一刀切丢掉真正故障。

统一命名有助于判断“新版本引入了什么错误”：

[email protected]+abc1234
[email protected]+def5678

至少使用 production、staging 两个 environment，不要让本地开发事件污染生产告警。部署成功后标记 Release，回滚时也上传正确版本，否则回归分析会失真。

代码质量门禁可以与 SonarQube 配合：SonarQube 在合并前发现静态问题，Sentry 在运行时发现真实异常，两者覆盖阶段不同。

错误事件可能携带 URL、用户名、IP、请求头、表单字段和 Breadcrumb。上线前必须定义：

• 哪些字段允许上传；
• Cookie、Authorization、手机号、邮箱如何脱敏；
• 谁能访问生产 Organization；
• 事件保留多少天；
• 离职账号和 Auth Token 如何吊销；
• 数据跨境与监管要求是否允许自建节点所在区域。

SDK 默认配置不等于符合你的隐私要求。使用 beforeSend、send_default_pii=False、服务端 scrubber 和最小权限共同控制。

.env.custom 中的 SENTRY_EVENT_RETENTION_DAYS=30 会被定时 cleanup 使用。短保留期能降低 ClickHouse、对象存储和附件增长，但不会自动解决所有日志与 volume 空间问题。

每周检查：

cd /opt/sentry/self-hosted
sudo docker system df -v
sudo docker volume ls
df -h /var/lib/docker
df -i /var/lib/docker
sudo docker compose --env-file .env --env-file .env.custom logs --since=24h --tail=1000 sentry-cleanup

不要运行未经审计的 docker system prune --volumes。Sentry 使用多个持久化卷，错误清理可能直接删除事件、附件或数据库。

最低监控项：

• https://sentry.example.com 与本地 /_health/；
• 所有关键容器的 health、重启次数和 OOM；
• VPS CPU、内存、load、磁盘、inode、I/O wait；
• PostgreSQL、ClickHouse、Kafka、Valkey 容量；
• Relay 接收事件与 consumer lag；
• Caddy 证书、5xx 和延迟；
• 离线备份是否完成、是否复制异地。

可把公网 HTTPS 交给 Uptime Kuma；但还要增加一条测试事件或健康事件链路，避免“页面正常、事件管道已堵塞”。

官方 scripts/backup.sh 调用 Sentry 的 export 命令生成 sentry/backup.json，适合导出全局配置等逻辑数据。它不是完整事件备份，不能替代 PostgreSQL、ClickHouse、SeaweedFS 与其他 volume 的一致性快照。

可靠备份至少包括：

• 固定 tag 对应的仓库配置文件；
• sentry-data、sentry-postgres、sentry-clickhouse、sentry-kafka、sentry-redis、sentry-seaweedfs；
• profile、taskbroker 等仍需保留的 Compose volume；
• Caddy 配置和恢复说明；
• 校验和、加密和异地副本。

下面先导出逻辑配置，再记录所有正在挂载的 Docker volume，停止整套 Sentry 后逐卷打包。维护窗口内没有写入，能减少跨组件时间点不一致。

#!/usr/bin/env bash
set -euo pipefail

cd /opt/sentry/self-hosted
STAMP="$(date -u +%Y%m%dT%H%M%SZ)"
BACKUP_DIR="/srv/backups/sentry/${STAMP}"
COMPOSE=(sudo docker compose --env-file .env --env-file .env.custom)

sudo install -d -m 0700 "$BACKUP_DIR/volumes"

sudo ./scripts/backup.sh --no-report-self-hosted-issues
sudo cp sentry/backup.json "$BACKUP_DIR/backup.json"

mapfile -t CONTAINERS < <("${COMPOSE[@]}" ps -q)
test "${#CONTAINERS[@]}" -gt 0

mapfile -t VOLUMES < <(
  sudo docker inspect "${CONTAINERS[@]}" \
    --format '{{range .Mounts}}{{if eq .Type "volume"}}{{println .Name}}{{end}}{{end}}' |
    sort -u
)
test "${#VOLUMES[@]}" -gt 0
printf '%s\n' "${VOLUMES[@]}" | sudo tee "$BACKUP_DIR/volumes.list" >/dev/null

"${COMPOSE[@]}" down

sudo tar -C /opt/sentry -czf "$BACKUP_DIR/self-hosted-config.tar.gz" \
  --exclude='self-hosted/.git' \
  self-hosted

for volume in "${VOLUMES[@]}"; do
  safe_name="${volume//\//_}"
  sudo docker run --rm \
    -v "${volume}:/source:ro" \
    -v "$BACKUP_DIR/volumes:/backup" \
    alpine:3.22 \
    tar -C /source -czf "/backup/${safe_name}.tar.gz" .
done

sudo find "$BACKUP_DIR" -type f ! -name SHA256SUMS -print0 |
  sort -z |
  sudo xargs -0 sha256sum |
  sudo tee "$BACKUP_DIR/SHA256SUMS" >/dev/null

"${COMPOSE[@]}" up --wait
echo "Backup complete: $BACKUP_DIR"

将脚本保存为 /opt/sentry/backup-offline.sh，先在非生产环境验证。脚本不能保证 VPS 在磁盘故障时仍能读取备份，因此完成后还要加密复制到另一台机器或对象存储。

如果要建立 restic/rclone、保留策略和恢复抽查，可参考 VPS 备份恢复演练。

至少每月在隔离 VPS 验证一次：

1. 安装相同 Docker/Compose；
2. checkout 备份时的 Sentry tag；
3. 校验 SHA256SUMS；
4. 按 volumes.list 创建同名 volume；
5. 解压对应 tar 到空 volume；
6. 恢复 self-hosted 配置；
7. 启动整套服务；
8. 登录、打开历史 Issue、发送新测试事件；
9. 验证 SMTP、告警和 Source Map；
10. 记录 RTO、RPO 与失败步骤。

恢复必须在隔离网络开始，避免旧实例和恢复实例同时接收同一个 DSN 的生产事件。

Sentry Self-Hosted 使用 CalVer，升级不能只把 tag 从旧版跳到最新版。Release notes 会标记 hard stop；例如 26.5.0 和 26.7.0 都是 2026 年升级链路中的必经点。跨越 hard stop 会跳过必要迁移或配置变更。

升级前：

set -euo pipefail
cd /opt/sentry/self-hosted

git fetch --tags
git status --short
git tag --sort=-version:refname | head -n 20
sudo /opt/sentry/backup-offline.sh

如果当前版本低于 26.5.0，先 checkout 26.5.0，阅读 release notes、合并配置、执行安装器并验证；之后再经过 26.7.0，最后到 26.8.0。

cd /opt/sentry/self-hosted
git checkout 26.8.0
git diff HEAD@{1} -- .env docker-compose.yml sentry/config.example.yml sentry/sentry.conf.example.py
sudo ./install.sh --no-report-self-hosted-issues --minimize-downtime
sudo docker compose --env-file .env --env-file .env.custom ps
curl -fsS http://127.0.0.1:9000/_health/

26.8.0 移除了 7 个旧 metrics 容器；如果维护了 docker-compose.override.yml，升级前必须删除或修改对这些旧服务的引用。升级还把 Redis 服务镜像切换到 Valkey，脚本和监控不应只按镜像名判断可用性。

升级过程可能改变 PostgreSQL、ClickHouse 和其他持久化数据。失败后直接 git checkout 旧 tag 并启动，可能让旧代码读取新 schema。

可靠回滚流程是：

1. 停止失败的新版本；
2. 隔离当前 volume，保留排障证据；
3. 恢复升级前同一时间点的全部 volume 与配置；
4. checkout 原固定 tag；
5. 启动并检查事件接收链路；
6. 确认没有 SDK 同时向两套实例写入。

没有做过恢复演练，就不要把“有 VPS 快照”当成可回滚方案。

• 使用正式 tag 26.8.0，不是 master/nightly；
• 根据功能选择 errors-only 或 feature-complete；
• VPS 资源高于安装器门槛并保留宿主机余量；
• SENTRY_BIND 只监听 127.0.0.1:9000；
• 仅 Caddy 暴露 80/443，公网 HTTPS 正常；
• system.url-prefix 与外部域名一致；
• SMTP、邮箱验证和告警通知已经实测；
• JavaScript/Python 测试异常能进入正确项目；
• Release、Environment 和 Source Map 一致；
• SDK 已过滤敏感字段并设置合理采样；
• 磁盘、容器、consumer lag 与证书都有告警；
• 离线备份覆盖全部持久化 volume 和配置；
• 隔离环境完成过真实恢复；
• 升级路径包含所有 hard stop。

在 VPS 上自建 Sentry 的关键不是运行一次 install.sh，而是正确选择 errors-only 或完整模式、固定正式 tag、只通过 HTTPS 暴露服务、让 Release 与 Source Map 对齐，并持续控制事件量、隐私和磁盘增长。

上线后先完成两个验证：从真实应用发送一个带唯一 Release 的测试异常；在隔离环境恢复一次离线全量备份。只有事件链路和恢复链路都通过，这套 Sentry 才算可维护的生产监控，而不是一组暂时健康的容器。

• Sentry Self-Hosted 官方仓库
• Sentry Self-Hosted 26.8.0 Release
• Self-Hosted 安装与系统要求
• Sentry SDK 官方文档
• Sentry Self-Hosted LICENSE