运维云原生可观测性【免费下载链接】self-hostedSentry, feature-complete and packaged up for low-volume deployments and proofs-of-concept项目地址https://gitcode.com/gh_mirrors/se/self-hosted点击查看免费下载Sentry self-hostedself-hosted仓库将 Sentry 及其支撑服务打包为可自托管部署的形态适合低流量部署与概念验证场景。本文基于仓库根目录的 CONTRIBUTING.md 整理成一份可直接落地的贡献指南先讲清什么改动属于这个仓库的边界再带你完成本地环境搭建与install.sh安装流程随后深入单元测试与集成测试的写法与运行命令最后介绍 PR 规范与月度发布流水线。读完本文你将能够在自托管 Sentry 的打包与运维层面提交合规、可验证的贡献。仓库定位什么变更属于self-hosted仓库self-hosted仓库打包的是Sentry 与其支撑服务的自托管部署形态因此属于这里的改动集中在打包与运维面packaging and operating surfaceDocker 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 应用镜像内的产品行为尤其是前端改动Sentry事件摄取与轻量处理如 PII 脱敏等Relay长期事件存储对 ClickHouse 的查询与写入Snuba原生符号的符号化Java、.NET、C、C 等Symbolicator可用性监控检查Uptime Checker任务路由已用 Taskbroker 替代 CeleryTaskbrokerEmerge Tools 相关代码移动端构建分发、体积分析、快照Launchpad文件/对象存储代理与管理Objectstore从仓库目录结构可以印证这一分工sentry/、relay/、symbolicator/、snuba/、clickhouse/、taskbroker/各自持有对应服务的镜像构建文件与配置模板install/与scripts/持有运维脚本改哪块就进哪个子目录不要把镜像内的业务逻辑混入本仓库。参与方式贡献远不止写代码贡献 self-hosted Sentry 有多种途径文档明确列举了五类在 GitHub issues 中回答问题官方维护了 Self-Hosted Sentry Projects 面板会过滤掉带 Waiting For: Product Owner 标签的 issue当有至少 Triage 权限的人回复后标签会被移除从而避免问题被遗忘。部分 issue 需要恢复上下文或深入调查回复慢一些也正常。在 Discord 频道回答问题实时消息频道适合处理自托管 Sentry 跑不起来这类故障。编写 self-hosted 文档将带 Category: Docs 标签的 issue 的解决方案整理后转移到sentry-docs仓库这是最省力的文档贡献方式。升级第三方依赖当 Postgres、Kafka、ClickHouse 等出现安全补丁时执行版本升级。注意只有 SaaS云版本跟进某个大版本后self-hosted 才会升级对应大版本。常规改进保持sentry/sentry.conf.py中的功能开关feature flags有效、修复 Bash 脚本 bug、整体改善自托管体验。文档最后强调以上清单之外的任何贡献也同样欢迎。本地环境搭建官方警告优先使用虚拟机而非个人电脑[!WARNING] 除非你的机器非常大否则官方不推荐在个人电脑笔记本或 PC上做本地搭建强烈建议通过云厂商或受控虚拟环境VirtualBox、Proxmox 等创建 Linux 虚拟机。自托管堆栈包含大量容器与服务资源占用高、升级链路复杂虚拟机能提供更干净的隔离与回滚能力。必备工具清单Docker Engine 与 Docker Compose通过 Docker 插件系统提供。推荐用发行版包管理器安装Debian/Ubuntu 用aptCentOS/Fedora/RHEL 用dnf或yum。Python v3.11 或更高与 pyproject.toml 中requires-python 3.11的要求一致。uv包管理器用于管理集成测试的 Python 依赖uv.lock已随仓库提交。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实际变更阶段先升级 ClickHouseupgrade-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 定义的参数常用选项如下参数作用-h, --help显示帮助并退出--minimize-downtime实验性升级时尽可能久地保持接收事件会禁用出错时的清理可能留下部分升级状态仅用于原地升级--skip-commit-check在self-hostedGit 工作副本的 master 分支上跳过最新提交检查--skip-user-creation跳过初始用户创建提示适合非交互安装--skip-sse42-requirements跳过环境 SSE42 要求检查仅在明确知情时使用--report-self-hosted-issues/--no-report-self-hosted-issues是否向 Sentry 上报本实例的错误与性能数据--container-engine-podman使用 podman 作为容器引擎--apply-automatic-config-updates/--no-apply-automatic-config-updates是否自动应用配置文件更新同时保留了若干弃用别名--no-user-prompt/--skip-user-prompt建议改用--skip-user-creation环境变量SKIP_USER_PROMPT建议改用SKIP_USER_CREATION。生成的配置文件先当作安装输出再手动编辑安装会在工作树中生成并管理以下文件生成文件来源模板.env默认环境文件sentry/sentry.conf.pysentry/sentry.conf.example.pysentry/config.ymlsentry/config.example.ymlrelay/config.ymlrelay/config.example.ymlsymbolicator/config.ymlsymbolicator/config.example.yml官方立场是把这些生成文件当作安装输出优先、手动编辑其次。如果你在修改生成逻辑必须同时验证示例文件与安装脚本的行为。生成机制位于 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_DAYS10后断言该值生效同时.env中的SENTRY_BIND9000、COMPOSE_PROJECT_NAMEsentry-self-hosted保持默认。此外_lib.sh还导出STOP_TIMEOUT60将默认 10 秒的 SIGTERM 超时提高到 60 秒确保升级时任务队列能充分排空。测试体系仓库有两类测试改动任何安装脚本或配置模板后都应按对应层级验证。1. 单元测试Bash 断言目录_unit-test/方式运行指定 Bash 脚本并用 Bash 做断言入口unit-test.sh 遍历_unit-test/*-test.sh依次执行支持传入单个测试文件名进行过滤注意它仅在CItrue时运行脚本开头会拒绝非 CI 环境运行前会以FORCE_CLEAN1调用scripts/reset.sh重置环境。_unit-test/_test_setup.sh 提供了沙箱机制把当前仓库用git clone --depth1 file://$ORIGIN克隆到临时目录再把工作副本中的本地改动以符号链接方式传播进沙箱实现边改边测的开发体验——用DEBUG1 some-test.sh运行可保留沙箱供交互调试。仓库内现有的单元测试覆盖了安装的关键环节例如check-memcached-backend-test.shMemcached 后端检查、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 --junitxmljunit.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创建测试用户默认testexample.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 发布按顺序执行以下步骤发布所有组件sentry、snuba、relay 等各自仓库通过 GitHub Actions 发布工作流触发每月 15 日自动执行也可手动 workflow dispatch。在publish仓库审批组件发布会触发 issue 创建需为每个 issue 添加 accepted 标签若 CI 检查变红重试失败任务后重新加标签CI 全绿后发布创建成功。发布self-hosted本身所有组件发布完成后用本仓库的发布工作流发布self-hosted并在publish仓库审批。可选更新发布说明在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清理——这是贡献者排查安装脚本问题时自带的、可观测的排错入口。赞分享运维云原生可观测性【免费下载链接】self-hostedSentry, feature-complete and packaged up for low-volume deployments and proofs-of-concept项目地址https://gitcode.com/gh_mirrors/se/self-hosted点击查看免费下载相关推荐Self-hosted LiveSync 贡献指南从环境搭建、代码验证到翻译与发布的全流程实战Self hosted LiveSync 贡献指南从环境搭建、代码验证到翻译与发布的全流程实战 本篇指南基于 obsidian livesync 仓库的 CO数据同步Next.js 仓库贡献指南本地开发、构建、测试与发布的全流程实践Next.js 仓库贡献指南本地开发、构建、测试与发布的全流程实践 本文以 Next.js 官方仓库的贡献指南 contributing.md https:/前端后端Web框架SSR前端构建ice.js 参与贡献指南Monorepo 环境搭建、本地调试、vitest 测试与发布全流程ice.js 参与贡献指南Monorepo 环境搭建、本地调试、vitest 测试与发布全流程 本篇指南面向希望为 ice.js基于 React 的渐进式应前端Web框架SSR前端构建插件系统微前端跨平台上一篇从阻塞到毫秒级响应cim系统离线消息表的高性能设计实践下一篇终极指南基于YOLOv5的12种中文车牌检测识别完整解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考