企业官网建设流程全解析

• 运维
• 云原生
• 可观测性

Sentry self-hosted（self-hosted仓库）将 Sentry 及其支撑服务打包为可自托管部署的形态，适合低流量部署与概念验证场景。本文基于仓库根目录的 CONTRIBUTING.md 整理成一份可直接落地的贡献指南：先讲清"什么改动属于这个仓库"的边界，再带你完成本地环境搭建与install.sh安装流程，随后深入单元测试与集成测试的写法与运行命令，最后介绍 PR 规范与月度发布流水线。读完本文，你将能够在自托管 Sentry 的打包与运维层面提交合规、可验证的贡献。

仓库定位：什么变更属于self-hosted仓库

self-hosted仓库打包的是Sentry 与其支撑服务的自托管部署形态，因此属于这里的改动集中在"打包与运维面"（packaging and operating surface）：

• Docker Compose 编排：如 docker-compose.yml；
• 安装与升级脚本：install.sh 及 install/ 目录下按阶段拆分的一系列子脚本；
• 默认配置模板：如 sentry/sentry.conf.example.py、sentry/config.example.yml、relay/config.example.yml、symbolicator/config.example.yml；
• 可选的 self-hosted 补丁：见 optional-modifications/；
• 上述工作流的测试：_unit-test/ 与 _integration-test/。

官方在文档中给出了明确的问题路由表——如果你的修复只改镜像内容而不涉及本仓库的打包逻辑，应提交到对应上游仓库，并在 issue/PR 中链接上下文：

从仓库目录结构可以印证这一分工：sentry/、relay/、symbolicator/、snuba/、clickhouse/、taskbroker/各自持有对应服务的镜像构建文件与配置模板，install/与scripts/持有运维脚本，改哪块就进哪个子目录，不要把镜像内的业务逻辑混入本仓库。

参与方式：贡献远不止写代码

贡献 self-hosted Sentry 有多种途径，文档明确列举了五类：

1. 在 GitHub issues 中回答问题：官方维护了 "Self-Hosted Sentry Projects" 面板，会过滤掉带 "Waiting For: Product Owner" 标签的 issue；当有至少 "Triage" 权限的人回复后标签会被移除，从而避免问题被遗忘。部分 issue 需要恢复上下文或深入调查，回复慢一些也正常。
2. 在 Discord 频道回答问题：实时消息频道，适合处理"自托管 Sentry 跑不起来"这类故障。
3. 编写 self-hosted 文档：将带 "Category: Docs" 标签的 issue 的解决方案整理后转移到sentry-docs仓库，这是最省力的文档贡献方式。
4. 升级第三方依赖：当 Postgres、Kafka、ClickHouse 等出现安全补丁时执行版本升级。注意：只有 SaaS（云版本）跟进某个大版本后，self-hosted 才会升级对应大版本。
5. 常规改进：保持sentry/sentry.conf.py中的功能开关（feature flags）有效、修复 Bash 脚本 bug、整体改善自托管体验。

文档最后强调：以上清单之外的任何贡献也同样欢迎。

本地环境搭建

官方警告：优先使用虚拟机而非个人电脑

[!WARNING] 除非你的机器非常大，否则官方不推荐在个人电脑（笔记本或 PC）上做本地搭建，强烈建议通过云厂商或受控虚拟环境（VirtualBox、Proxmox 等）创建 Linux 虚拟机。

自托管堆栈包含大量容器与服务，资源占用高、升级链路复杂，虚拟机能提供更干净的隔离与回滚能力。

必备工具清单

1. Docker Engine 与 Docker Compose（通过 Docker 插件系统提供）。推荐用发行版包管理器安装：Debian/Ubuntu 用apt，CentOS/Fedora/RHEL 用dnf或yum。
2. Python v3.11 或更高：与 pyproject.toml 中requires-python = ">=3.11"的要求一致。
3. uv包管理器：用于管理集成测试的 Python 依赖（uv.lock已随仓库提交）。
4. prek：用于 Git pre-commit 钩子。

安装流程：./install.sh

整个安装流程由 install.sh 驱动，职责包括：版本检查、复制示例配置文件、生成缺失的密钥、构建本地镜像、准备数据库。安装完成后，官方期望的下一步是：

docker compose up -d --wait

从 install.sh 的源码可以看出安装顺序的编排逻辑（source顺序即执行顺序）：

• 前置阶段（无副作用）：install/_logging.sh、install/_lib.sh（环境变量与公共函数）、install/parse-cli.sh（命令行解析）、install/detect-platform.sh、install/dc-detect-version.sh、install/error-handling.sh（错误处理与 trap 注册）、install/check-latest-commit.sh、install/check-minimum-requirements.sh；
• 实际变更阶段：先升级 ClickHouse（upgrade-clickhouse.sh需要旧镜像来判断是否需要升级，因此必须先于关停执行）→cleanup-clickhouse.sh→update-docker-images.sh→turn-things-off.sh→create-docker-volumes.sh→ensure-files-from-examples.sh（从示例复制配置）→check-memcached-backend.sh→ensure-relay-credentials.sh→generate-secret-key.sh→ 构建镜像 →migrate-seaweedfs-kek.sh→upgrade-postgres.sh→ S3 nodestore 引导 →bootstrap-snuba.sh→ profiles 目录权限与 S3 profiles 引导 →set-up-and-migrate-database.sh→migrate-pgbouncer.sh→geoip.sh→setup-js-sdk-assets.sh→setup-custom-ca-certificate.sh→wrap-up.sh。

该脚本透传 install/parse-cli.sh 定义的参数，常用选项如下：

同时保留了若干弃用别名：--no-user-prompt/--skip-user-prompt建议改用--skip-user-creation；环境变量SKIP_USER_PROMPT建议改用SKIP_USER_CREATION。

生成的配置文件：先当作安装输出，再手动编辑

安装会在工作树中生成并管理以下文件：

官方立场是：把这些生成文件当作"安装输出"优先、手动编辑其次。如果你在修改生成逻辑，必须同时验证示例文件与安装脚本的行为。

生成机制位于 install/_lib.sh 的ensure_file_from_example函数：目标文件已存在则跳过，不存在则按"去掉最后一个扩展名再加.example"的规则定位模板并执行cp -n复制，模板缺失会直接报错退出。_lib.sh还实现了一个容易被忽略的细节：如果存在.env.custom文件，其值会与.env合并且优先于.env，这一机制被ensure-files-from-examples.sh等脚本使用；_unit-test/merge-env-file-test.sh 专门验证了它：在.env.custom中写入SENTRY_EVENT_RETENTION_DAYS=10后，断言该值生效，同时.env中的SENTRY_BIND=9000、COMPOSE_PROJECT_NAME=sentry-self-hosted保持默认。此外_lib.sh还导出STOP_TIMEOUT=60，将默认 10 秒的 SIGTERM 超时提高到 60 秒，确保升级时任务队列能充分排空。

测试体系

仓库有两类测试，改动任何安装脚本或配置模板后都应按对应层级验证。

1. 单元测试：Bash 断言

• 目录：_unit-test/；
• 方式：运行指定 Bash 脚本并用 Bash 做断言；
• 入口：unit-test.sh 遍历_unit-test/*-test.sh依次执行，支持传入单个测试文件名进行过滤；注意它仅在CI=true时运行（脚本开头会拒绝非 CI 环境），运行前会以FORCE_CLEAN=1调用scripts/reset.sh重置环境。

_unit-test/_test_setup.sh 提供了沙箱机制：把当前仓库用git clone --depth=1 file://$ORIGIN克隆到临时目录，再把工作副本中的本地改动以符号链接方式传播进沙箱，实现"边改边测"的开发体验——用DEBUG=1 some-test.sh运行可保留沙箱供交互调试。

仓库内现有的单元测试覆盖了安装的关键环节，例如：check-memcached-backend-test.sh（Memcached 后端检查）、geoip-test.sh、js-sdk-assets-test.sh、migrate-pgbouncer-test.sh、multiple-seaweedfs-bucket-test.sh、setup-custom-ca-certificate-test.sh、ensure-relay-credentials-test.sh、merge-env-file-test.sh等。

2. 集成测试：完整堆栈 + pytest

• 目录：_integration-test/；
• 方式：使用特定COMPOSE_PROFILES运行./install.sh与docker compose up --wait启动完整自托管堆栈，再执行登录、验证事件被摄入并可被查询等场景；
• 断言语言：Python，使用pytest测试框架。

集成测试的依赖通过uv管理，先同步环境并安装测试依赖：

uv sync --frozen

然后运行集成测试：

uv run pytest -x --cov --junitxml=junit.xml _integration-test/

参数含义：-x遇错即停，--cov输出覆盖率，--junitxml生成 JUnit 格式报告。dev 依赖清单见 pyproject.toml，包含httpx、pytest、pytest-cov、beautifulsoup4、cryptography、sentry-sdk等。

_integration-test/conftest.py 的会话级 fixture 展示了测试骨架：自动执行docker compose --ansi never up --wait拉起堆栈，再通过docker compose exec -T web sentry createuser --force-update --superuser创建测试用户（默认test@example.com，测试主机默认http://localhost:9000，可用SENTRY_TEST_HOST覆盖）。_integration-test/test_01_basics.py 实现了 120 秒超时的轮询辅助函数，并通过调用/api/0/projects/sentry/internal/keys/获取公开 DSN，用于端到端验证事件摄入链路；测试场景还包括备份恢复（test_02_backup.py）、SeaweedFS 加密密钥（test_seaweedfs_kek.py）与自定义 CA 根证书等。

PR 期望与规范

官方要求 PR 保持足够小，让评审者一次就能理解完整的用户影响。在本仓库中，通常意味着一个 PR 只解决一个打包问题：一次安装修复、一次配置迁移、一个测试新增，或一个可选修改。

提交时的硬性期望：

• 写清楚问题陈述，而不只是修复本身；
• 说明 bug 是在全新安装、升级，还是两者上复现；
• 明确指出涉及的生成文件、配置迁移或运维可见的行为变更；
• 附上你在本地运行的确切验证过程；
• 若根因在仓库之外，链接上游 issue 或 PR提供上下文；
• 保持提交历史可读：少量聚焦的提交优于一长串 fixup。

如果开 issue 或 PR，请提供足够让陌生人在自己机器上复现的上下文：宿主操作系统、Docker 与 Compose 版本、是否使用了.env.custom、相关COMPOSE_PROFILES，以及失败的命令或日志片段。

关于 AI 辅助的 PR

你必须理解你自己的 PR。如果你无法解释改动做了什么、以及它如何与系统其他部分交互，PR 可能会被关闭。

官方态度明确：用 AI 来开 PR 是可以的，但提交自己都不理解的 AI 生成内容（"AI slop"）是不被接受的。结合本仓库特点，AI 辅助贡献最稳妥的做法是：让 AI 生成初稿，然后人工核对install.sh的脚本执行顺序、ensure_file_from_example的模板复制逻辑、.env.custom的合并优先级，并实际跑一遍对应层级的测试。

月度发布流程

该章节对普通公众不相关，仅说明发布流水线全貌（官方员工可参考内部文档）。一次 self-hosted 发布按顺序执行以下步骤：

1. 发布所有组件：sentry、snuba、relay 等各自仓库通过 GitHub Actions 发布工作流触发，每月 15 日自动执行，也可手动 "workflow dispatch"。
2. 在publish仓库审批：组件发布会触发 issue 创建，需为每个 issue 添加 "accepted" 标签；若 CI 检查变红，重试失败任务后重新加标签；CI 全绿后发布创建成功。
3. 发布self-hosted本身：所有组件发布完成后，用本仓库的发布工作流发布self-hosted，并在publish仓库审批。
4. （可选）更新发布说明：在self-hosted仓库更新 release notes，告知用户变更。

对普通贡献者而言，理解这套流程的关键意义在于：大版本依赖升级不会由社区擅自发起，需等待 SaaS 跟进，因此涉及依赖 bump 的 PR 应先确认当前版本基线。

获取帮助

• 贡献相关问题：Sentry 官方 Discord 的#self-hosted频道；
• Sentry 员工：Slack 的#discuss-self-hosted频道。

另外值得一提的是，install/error-handling.sh 为安装过程内置了故障上报设施：安装失败时默认提示是否将错误与性能数据上报到官方自托管的 Sentry 实例（而非 SaaS），收集内容包括 OS 用户名、IP 地址、安装日志、运行时错误与性能数据，30 天保留期；可用--report-self-hosted-issues/--no-report-self-hosted-issues或环境变量REPORT_SELF_HOSTED_ISSUES跳过交互提示。启用上报后，脚本会通过sentry-cli发送 envelope（含异常、breadcrumbs 与 Docker/Compose/各镜像版本等 tags）到SENTRY_DSN，并根据是否设置--minimize-downtime决定出错后是否执行docker compose stop清理——这是贡献者排查安装脚本问题时自带的、可观测的排错入口。

• 运维
• 云原生
• 可观测性