sentry自托管在linux上必须使用docker compose部署，跳过它将引发权限、版本、时区及表初始化等连环问题；需确保docker≥20.10、docker-compose≥1.29.2，克隆onpremise仓库后必须checkout稳定release tag（如23.10.0或24.3.0），并显式配置sentry_url_prefix，否则前端sdk上报会静默失败。
直接上结论：Sentry 自托管在 Linux 上，docker-compose 是唯一推荐路径；跳过它用源码或手动装 PostgreSQL/Redis 会陷入权限、版本、时区、表初始化失败等连环问题，90% 的失败都卡在这一步。
确认 Docker 和 docker-compose 版本是否达标
很多部署中断在 docker-compose up -d 启动阶段，根本原因不是配置错，而是版本不兼容。Sentry onpremise（21.x+）明确要求：
-
docker≥ 20.10（旧版如 19.03 在 Ubuntu 18.04 上常触发OCI runtime create failed） -
docker-compose≥ 1.29.2（低于此版本会报version '3.8' is invalid，因onpremise/docker-compose.yml使用了 3.8 schema） - 执行
docker --version和docker-compose --version验证，别信包管理器默认装的“最新”——CentOS Stream 或 Ubuntu 20.04 apt 源里的docker-compose往往是 1.25.x
克隆 onpremise 仓库后必须 checkout 稳定 release tag
直接 git clone 主干（main branch）大概率失败：依赖镜像未构建、install.sh 脚本调用的 Python 脚本路径已变更、PostgreSQL 初始化逻辑缺失。正确做法是锁定已验证的发布版本：
- 进入
onpremise目录后，运行：git fetch --tags && git checkout $(git describe --tags `git rev-list --tags --max-count=1`) - 截至 2026 年 4 月，稳定可用的是
23.10.0或24.3.0（检查 GitHub Releases 页面 最新 non-prerelease tag） - 别用
git checkout stable—— 这个分支早已废弃，指向空 commit
.env 文件里必须显式设置 SENTRY_URL_PREFIX
否则 Web 界面能打开，但所有前端 SDK 上报都会 403 或静默丢弃。这是因为 Sentry 后端校验 Referrer 和 Origin 头时，比对的是 SENTRY_URL_PREFIX 值，而非容器内网地址：
- 若你通过
http://your-domain.com:9000访问，.env中必须写：SENTRY_URL_PREFIX=http://your-domain.com:9000 - 若用反向代理（Nginx），且实际访问地址是
https://sentry.your-org.com，则必须设为https://sentry.your-org.com，不能带路径后缀（如/sentry） - 漏设或设成
http://localhost:9000会导致：项目 DSN 生成正常，但 JS SDKSentry.init()后上报 403，日志里只显示Failed to load resource，无具体错误提示
首次运行 install.sh 卡在 “Creating sentry user” 不是 bug，是等待交互输入
./install.sh 最后阶段会启动一个临时容器执行 sentry upgrade，并阻塞等待你输入管理员邮箱和密码 —— 它不会自动跳过，也不会输出明确提示“请输入”，容易误判为卡死：
- 保持终端挂着，直接键入邮箱（如
admin@your-org.com），回车 - 再键入密码（不显示明文，输完回车），重复一次确认
- 如果之前误按 Ctrl+C 中断，PostgreSQL 数据库已部分初始化，再次运行
./install.sh会报relation "sentry_organization" already exists；此时需先docker-compose down -v清除 volume，再重来
最易被忽略的一点：Sentry 的 nodestore_node 表会在几周内吃光磁盘空间，但它不会主动告警。等发现时，TRUNCATE public.nodestore_node 虽能清空，但必须在 docker exec -it sentry_onpremise_postgres_1 psql -U postgres 里执行，且确保没有其他容器正在写入该表——否则 truncate 会被挂起，psql 一直卡住不动。
