[[440208]]

本文轉載自微信公眾號「黑客下午茶」，作者為少 。轉載本文請聯系黑客下午茶公眾號。

自托管 Sentry

除了公開提供其源代碼外，Sentry 還提供并維護了一個最小的設置，可以為簡單的用例開箱即用。該存儲庫還可以作為各種 Sentry 服務如何連接以進行完整設置的藍圖，這對于愿意維護更大安裝的人很有用。為簡單起見，我們為此選擇使用 Docker 和 Docker Compose， 以及基于 bash 的安裝和升級腳本。

入門

我們的建議是下載自托管存儲庫的最新版本， 然后在此目錄中運行 ./install.sh。這個腳本會處理你開始需要的所有事情，包括一個 base-line 配置， 然后會告訴你運行 docker-compose up -d 來啟動 Sentry。 Sentry 默認綁定到端口 9000。您應該能夠訪問 http://127.0.0.1:9000 上的登錄頁面。

https://github.com/getsentry/self-hosted/releases/latest

配置

您很可能希望調整 Sentry 的默認配置。這些設施可用于此目的：

sentry/config.yml — 包含大多數(如果不是全部)要調整的配置選項。這個文件是在安裝時從 sentry/config.example.yml 生成的。該文件本身將最常見的配置選項記錄為代碼注釋。此文件中的一些常用設置包括：

• system.url-prefix(我們會在安裝后立即提示您在歡迎屏幕上進行設置)
• mail.*(雖然我們提供了一個基本的 SMTP 服務器)
• GitHub、Slack 等的集成。

sentry/sentry.conf.py—包含更高級的配置。這個文件是在安裝過程中從 sentry/sentry.conf.example.py 生成的。

• https://github.com/getsentry/self-hosted/blob/master/sentry/sentry.conf.example.py

環境變量—可用的 key 在 .env 中定義。如果您需要覆蓋任何環境變量，請使用一些與系統相關的方法來設置環境變量。為避免 Git 更改，只需創建一個名為 .env.custom 的文件并在其中插入與系統相關的環境變量。為了使用它，請使用 docker-compose --env-file /path/to/.env.custom up -d。

Geolocation 使用自定義配置文件來符合底層技術。

注意：更改配置后，您需要通過運行 docker-compose restart web worker cron sentry-cleanup(或僅 docker-compose restart 重新啟動所有內容)來重新啟動所有 Sentry 服務。

配置特定主題

以下是與自托管相關的特定配置主題的更多信息：

• 自定義 CA 根
• Email
• 地理位置
• 單點登錄 (SSO)

產品化

我們強烈建議在綁定到專用域或子域的 Sentry 設置前使用專用負載均衡器。一個執行 SSL/TLS 終止的專用負載平衡器也將客戶端 IP 地址轉發為 Docker Compose 內部網絡 (因為這幾乎不可能以其他方式獲得)將為您提供最佳的 Sentry 體驗。作為此設置的一部分，我們建議使用 HTTP 協議針對 /_health/ 端點配置負載均衡器運行狀況檢查。如果 Sentry 啟動，這將返回 200 或帶有問題列表的 500。

請記住，所有這些設置都對所有服務使用單節點，包括 Kafka。對于更大的負載，您需要一臺具有大量 RAM 和磁盤存儲空間的強大機器。為了進一步擴展，您很可能會使用帶有更復雜工具(例如 Kubernetes)的集群。由于自托管安裝的自定義性質，我們不提供任何有關擴展的建議或指導。

https://github.com/getsentry/self-hosted/issues/554

自托管發布和升級

Sentry 減少了自托管的定期發布，以使其盡可能接近 sentry.io。我們決定遵循使用 CalVer 版本控制方案的月度發布計劃。 每個月的 15 號發布一個新版本，并在必要時進行后續發布。您可以在我們自托管存儲庫的發布部分 找到最新版本。

• https://calver.org/#scheme
• https://github.com/getsentry/self-hosted/releases

為什么選擇 CalVer?

• 簡而言之，這是為了讓自托管的 Sentry 與在 sentry.io 托管的實時版本接近。在我們宣布切換的博客文章中，有更多細節可供參考。
  
  • https://blog.sentry.io/2020/06/22/self-hosted-sentry-switching-to-calver
• CalVer 針對持續部署進行了優化，而非長期穩定性。我們建議您定期升級，就像我們在 SaaS 環境中所做的那樣。

升級

我們鼓勵每個人定期更新他們的 Sentry 安裝以獲得最佳和最新的 Sentry 體驗。

要升級，您需要做的就是下載或檢查您想要的自托管存儲庫的版本，用該版本替換現有文件夾的內容，然后運行 ./install.sh。

配置更新

我們可能有一些更新的配置，特別是對于新功能，因此請始終檢查 sentry 目錄下的示例配置文件，看看是否需要更新現有配置。我們盡最大努力自動化關鍵配置更新，但您應該始終在升級期間檢查您的配置。

在開始升級之前，我們關閉了所有服務，然后運行了一些數據遷移，因此預計會有一些停機時間。有一個實驗性的 --minimize-downtime 選項可以減少升級期間的停機時間。使用它的風險由您自己承擔，并查看它在其中實施的PR以獲取更多信息。

• https://github.com/getsentry/self-hosted/issues/607

從早期版本升級時，您需要經歷一些困難。請閱讀下面的 難點 部分以獲取列表。

難點

我們有三個難點，您需要通過這些步驟才能獲取重大的數據庫更改：

如果您來自 9.1.2 之前的版本，則首先需要升級到 9.1.2 并按照以下步驟操作：

<your.sentry.version> -> 9.1.2 -> 21.5.0 -> 21.6.3 -> latest 

如果您來自 9.1.2，首先需要升級到 21.5.0 并按照以下步驟操作：

<your.sentry.version> -> 21.5.0 -> 21.6.3 -> latest 

如果您來自 21.6.3 之前的版本，則首先需要升級到 21.6.3：

<your.sentry.version> -> 21.6.3 -> latest 

任何其他情況(21.6.3+)，你應該可以直接升級到最新版本。

每晚構建

我們為 Sentry 的每個新提交以及所有支持項目提供自托管存儲庫的 master 分支的每晚構建：

• Snuba

https://github.com/getsentry/snuba

• Relay

https://github.com/getsentry/relay

• Symbolicator

https://github.com/getsentry/symbolicator

注意：這些構建通常是穩定的，但您可能偶爾會遇到損壞的版本，因為這些版本不能保證首先部署到 sentry.io。也不能保證您能夠干凈地升級到更高版本而不會丟失任何數據。使用每晚構建的風險自負。

自托管備份和恢復

快速備份

如果您需要一種快速備份和恢復 Sentry 實例的方法，并且不需要歷史事件數據， 則可以使用內置的 export 和 import 命令。這些命令將保存和加載所有項目和用戶數據，但不包含任何事件數據。

備份

docker-compose run --rm -T -e SENTRY_LOG_LEVEL=CRITICAL web export > sentry/backup.json 

注意：如果您省略了 -T 或 -e SENTRY_LOG_LEVEL=CRITICAL 部分，您的備份文件將混入日志行，您必須以某種方式將其刪除。

恢復

使用 export 命令備份后，恢復它的最簡單方法是將其放在主 self-hosted 存儲庫中的 sentry 目錄下，在配置文件旁邊。這個目錄會自動掛載到 /etc/sentry，所以你可以運行以下命令來恢復你的備份：

docker-compose run --rm -T web import /etc/sentry/backup.json 

如果您沒有看到任何錯誤并且進程以代碼 0 退出，那么恭喜您，您剛剛恢復了備份。

注意：我們強烈建議您在全新安裝(空數據庫但運行遷移)時在 相同版本的 Sentry 上恢復備份。否則，您很可能會遇到錯誤并可能損壞您的數據庫。

完整備份

備份和恢復 Sentry 的理想方法是備份和恢復它使用的所有 Docker 卷。所有保存關鍵長期數據的卷在安裝時都已定義為全局卷，并以 sentry- 為前綴：

• sentry-data
• sentry-postgres
• sentry-redis
• sentry-zookeeper
• sentry-kafka
• sentry-clickhouse
• sentry-symbolicator

注意：只有備份和恢復這些卷才能恢復所有持久化數據。如果您還需要備份運行中的數據，我們建議備份 docker-compose 自動創建的任何特定于項目的卷，通常使用 sentry_self_hosted_sentry- 前綴。

Docker 在他們的文檔中記錄了如何備份和恢復卷。只要可以毫無問題地讀回卷，您就可以使用不同的方法。

https://docs.docker.com/storage/volumes/#backup-restore-or-migrate-data-volumes

自托管的自定義 CA 根

從 Sentry 21.8.0 開始，如果您需要沒有來自公共信任 CA 根的 TLS 證書的 Sentry 訪問服務，現在可以輕松地將它們添加到容器中。只需將證書添加到 Sentry 安裝根目錄內的 certificates 文件夾中，然后重新啟動容器。除了公共信任的 CA 根之外，還將使用您的自定義 CA 根。

注意：雖然您可以在每個容器中運行 update-ca-certificates，但這將更新磁盤上系統的根包，但不會對內存中的任何副本執行任何操作。重新啟動容器將更新包并確保它被使用。

如果給定的證書有問題，容器的日志將在開始時具有 update-ca-certificates 的輸出。

• https://manpages.debian.org/buster/ca-certificates/update-ca-certificates.8.en.html

具有捆綁根的依賴項

一些依賴項選擇捆綁自己的 CA 根并忽略系統 CA 根。在已知的情況下，它們已被配置為使用系統根。如果某些東西似乎忽略了系統根，請創建一個 issue， 以便對其進行跟蹤和修復。

• https://github.com/getsentry/self-hosted/issues/new?template=problem-report.yml

覆蓋的捆綁根

• Python
  • requests
  • botocore
  • grpc

自托管 Email

注意：請記住，一旦更改設置，您就需要重新啟動所有 Sentry 服務。有關更多信息，請參閱配置部分。

出站 Email

自托管 Sentry 附帶一個由 exim4 提供支持的內置外發 SMTP server。默認配置設置為使用此服務器。您需要做的就是為 config.yml 中的 mail.from 設置設置一個有效地址， 并為 .env 中的 SENTRY_MAIL_HOST 設置 Sentry 實例的 FQDN。請記住，如果您開始向公共地址發送過多電子郵件，您的新服務器可能會被標記為垃圾郵件發送者并被禁止。

• https://hub.docker.com/r/tianon/exim4
• https://en.wikipedia.org/wiki/Fully_qualified_domain_name

如果您想使用外部 SMTP server，您可以在 config.yml 文件中設置相關的 mail.* 設置并忽略內置的 SMTP server。有關每個設置的含義和作用的所有詳細信息，請參閱我們的電子郵件服務文檔。

由于配置的分層方式，如果您通過 Web 界面更新 mail 設置，您還需要注釋掉 config.yml 中的 mail.host: 'smtp' 默認值，以便選擇所需的設置。

入站 Email

Sentry 通過 Mailgun 提供的入站 mail 支持非常有限。您可以在我們的入站 email 服務文檔中找到有關如何進行設置的所有信息。

https://documentation.mailgun.com/en/latest/quickstart-receiving.html

自托管地理定位

Sentry 可以使用 MaxMind 的免費 GeoLite2-City 數據庫來對 IP 地址進行地理定位， 為已知最終用戶 IP 地址的錯誤事件以及登錄 Sentry 安裝的用戶的會話歷史記錄提供額外的上下文。為此，我們捆綁了 MaxMind 的 geoipupdate 工具。

• https://dev.maxmind.com/geoip/geoip2/geolite2/
• https://hub.docker.com/r/maxmindinc/geoipupdate

為了利用服務器端 IP 地址地理定位，您必須首先將 IP 地址發送到 Sentry。 默認情況下，較新的 SDK 不會執行此操作。

• https://docs.sentry.io/platforms/python/data-management/sensitive-data/#personally-identifiable-information-pii

要啟用服務器端 IP 地址地理定位，請注冊一個免費的 MaxMind 帳戶， 然后通過將您的 MaxMind 配置文件放在 geoip/GeoIP.conf 來告訴 Sentry 您的憑據。

• https://www.maxmind.com/en/geolite2/signup

AccountID 012345 
 
LicenseKey foobarbazbuz 
 
EditionIDs GeoLite2-City 

有了這個配置文件，Sentry 的 install.sh 的后續運行將刷新 IP 地址地理定位數據庫。下次您重新啟動自托管的 Sentry 實例(特別是 relay 和 web 服務)時，您應該會看到最新的數據。以下是確認它是否正常工作的方法：

• 對于 relay 服務：Dashboards > Errors by Country 上應該有一些紫色。
• 對于 web 服務：User Settings > Security > Session History 應在表中的 IP 地址下方顯示國家代碼和地區(例如，"US (CA)")。

啟動后不久看到 sentry_self_hosted_geoipupdate_1 容器退出是正常的，因為更新地理定位數據庫是一次性的批處理過程，而不是長時間運行的 job。

升級

使用 GeoLite2-City.mmdb 文件的服務需要知道在哪里可以找到它。新安裝將自動設置此設置，但如果您要升級，則需要在重新啟動 Sentry 之前手動設置以下內容。

在 relay/config.yml 中(示例):

• https://github.com/getsentry/self-hosted/blob/master/relay/config.example.yml

processing: 
  geoip_path: "/geoip/GeoLite2-City.mmdb" 

在 sentry/sentry.conf.py 中(示例):

• https://github.com/getsentry/self-hosted/blob/master/sentry/sentry.conf.example.py

GEOIP_PATH_MMDB = '/geoip/GeoLite2-City.mmdb' 

自托管單點登錄 (SSO)

Sentry 中的 SSO 以兩種方式之一處理：

• 通過處理上游代理的中間件來指示經過身份驗證的用戶
• 通過實現身份驗證管道的第三方服務

使用中間件代理 (SAML2)

從 Sentry 20.6.0 開始，自托管 Sentry 內置了對 SAML2 和某些身份驗證提供程序的支持。對于舊版本，您需要在運行 ./install.sh 之前將以下行添加到 sentry/requirements.txt：

• https://github.com/getsentry/self-hosted/blob/10.0.1/sentry/requirements.example.txt

sentry-auth-saml2@https://github.com/getsentry/sentry-auth-saml2/archive/master.zip#egg=sentry-auth-saml2 

您可以設置它的方式與 sentry.io 相同，除了您需要為文檔中提到的 URL 使用自己實例的 url-prefix。

• https://develop.sentry.dev/config/#general

有關所有詳細信息，請參閱我們的主要 SAML 文檔。

• https://docs.sentry.io/accounts/sso/#saml2-identity-provider

使用 OAuth 的單點登錄

注意：啟用 SSO 后，這將是登錄到自托管實例的唯一方法。如果您需要與 SSO 一起免費注冊，您可以在 GitHub PR 上對此發表評論。

• https://github.com/getsentry/sentry/pull/16247

Google Auth

從 Sentry 9.1 開始，自托管的 Sentry 帶有內置的 Google Auth 支持。要啟用，您需要為您的 Google App 創建一個 client ID 和 secret， 然后將這些值分別輸入到您的 sentry/config.yaml 文件中：

auth-google.client-id: '<client id>' 
auth-google.client-secret: '<client secret>' 

注意：請記住，一旦更改設置，您就需要重新啟動所有 Sentry 服務。有關更多信息，請參閱配置部分。

• https://developers.google.com/identity/sign-in/web/server-side-flow#step_1_create_a_client_id_and_client_secret
• https://github.com/getsentry/self-hosted/blob/master/sentry/config.example.yml

GitHub Auth

從 Sentry 10 開始， 自托管 Sentry 帶有內置的 GitHub Auth 支持。要啟用，您需要在您的組織下創建一個新的 GitHub App 并安裝它。

為 SSO & integration 創建 GitHub App

GitHub App 名稱不得包含任何空格。

如果上面的表單對您不起作用，您需要為您的 GitHub 應用程序進行以下設置：

Setting	Value
Homepage URL	${urlPrefix}
User authorization callback URL	${urlPrefix}/auth/sso/
Setup URL (optional)	${urlPrefix}/extensions/github/setup/
Webhook URL	${urlPrefix}/extensions/github/webhook/

不要忘記將所有出現的 {'${urlPrefix}'} 替換為您自己的 url 前綴。

當提示輸入權限時，請選擇以下選項：

Permission	Setting
Organization permissions / members	Read-only
User permissions / Email addresses	Read-only
Repository administration	Read-only
Repository contents	Read-only
Issues	Read & write
Pull requests	Read & write
Repository webhooks	Read & write

使用您的 GitHub App 信息更新您的配置

然后，您需要設置以下配置值：

在 sentry/sentry.conf.py 中

GITHUB_APP_ID="<App ID>" 
GITHUB_API_SECRET="<Client secret>" 
GITHUB_REQUIRE_VERIFIED_EMAIL = True  # Optional but recommended 
 
# Only if you are using GitHub Enterprise 
#GITHUB_BASE_DOMAIN = "git.example.com" 
#GITHUB_API_DOMAIN = "api.git.example.com" 

在 sentry/config.yaml 中

# github-app.id: <App ID> 
# github-app.name: '<GitHub App name>' 
# github-app.webhook-secret: '<Webhook secret>' # Use only if configured in GitHub 
# github-app.client-id: '<Client ID>' 
# github-app.client-secret: '<Client secret>' 
# github-app.private-key: | 
#   -----BEGIN RSA PRIVATE KEY----- 
#   privatekeyprivatekeyprivatekeyprivatekey 
#   privatekeyprivatekeyprivatekeyprivatekey 
#   privatekeyprivatekeyprivatekeyprivatekey 
#   privatekeyprivatekeyprivatekeyprivatekey 
#   privatekeyprivatekeyprivatekeyprivatekey 
#   -----END RSA PRIVATE KEY----- 

這還將為您的實例啟用 GitHub Integration。

注意：請記住，一旦更改設置，您就需要重新啟動所有 Sentry 服務。有關更多信息，請參閱配置部分。

自定義 Provider

目前，API 被認為是不穩定的，可能會發生變化。事情可能不會有太大變化，但有一些地方需要清理。

考慮到這一點，如果您想構建自己的，請查看上面的參考實現之一。

• https://github.com/getsentry/sentry/tree/master/src/sentry/auth/providers

自托管故障排除

請記住，自托管存儲庫面向中低負載，并考慮到了簡單性。需要更大設置或有事件高峰的人們可以根據他們的特定需求和環境從這里擴展。

• https://github.com/getsentry/self-hosted

常見

您可以通過運行 docker-compose logs 來查看每個服務的日志。您可以使用 -f 標志來 "follow" 進入的日志，并使用 -t 標志作為時間戳。如果您不傳遞任何服務名稱，您將獲得所有正在運行的服務的日志。有關詳細信息，請參閱 logs 命令的參考。

• https://docs.docker.com/compose/reference/logs/

Kafka

最有可能導致問題的事情之一是 Kafka。最常報告的錯誤是

Exception: KafkaError{code=OFFSET_OUT_OF_RANGE,val=1,str="Broker: Offset out of range"} 

這發生在 Kafka 和 consumer 不同步的地方。可能的原因有：

• 磁盤空間或內存不足
• 持續的事件峰值會導致很長的處理時間，導致 Kafka 在超過保留時間時丟棄消息
• 由于重新啟動或 suspend/resume(暫停/恢復) 循環導致的 Date/time(日期/時間) 不同步問題

恢復

正確的解決方案

正確 的解決方案如下 (reported by @rmisyurev)：

接收消費者列表：

docker-compose run --rm kafka kafka-consumer-groups --bootstrap-server kafka:9092 --list 

獲取群組信息：

docker-compose run --rm kafka kafka-consumer-groups --bootstrap-server kafka:9092 --group snuba-consumers -describe 

使用試運行(可選)觀察 offset 會發生什么：

docker-compose run --rm kafka kafka-consumer-groups --bootstrap-server kafka:9092 --group snuba-consumers --topic events --reset-offsets --to-latest --dry-run 

將 offset 設置為最新并執行：

docker-compose run --rm kafka kafka-consumer-groups --bootstrap-server kafka:9092 --group snuba-consumers --topic events --reset-offsets --to-latest --execute 

您可以在需要時將 snuba-consumers 替換為其他 consumer groups 或其他 topics 的 events。

• https://github.com/getsentry/self-hosted/issues/478#issuecomment-666254392

硬核選項

硬核選項 是刪除所有與 Kafka 相關的卷并重新創建它們，這將導致數據丟失。刪除這些卷后，任何掛起的數據都_將_消失。

停止實例：

docker-compose down --volumes 

刪除 Kafka & Zookeeper 相關卷：

docker volume rm sentry-kafka 
docker volume rm sentry-zookeeper 

再次運行安裝腳本：

./install.sh 

啟動實例：

docker-compose up -d 

減少磁盤使用

如果你想減少 Kafka 使用的磁盤空間，你需要仔細計算你攝取的數據量，你可以容忍的數據丟失量， 然后按照這個很棒的 StackOverflow 帖子或 我們社區論壇上的帖子中的建議進行操作。

• https://stackoverflow.com/a/52970982/90297
• https://forum.sentry.io/t/sentry-disk-cleanup-kafka/11337/2?u=byk

Redis

在自托管設置中，Redis 既用作事務數據存儲又用作 Celery 的工作隊列。出于這個原因，它可能會在事件高峰期間不堪重負。從版本 20.10.1 開始，我們對此進行了一些重大改進。如果您仍然遇到問題，您可以考慮擴展 Redis 本身或切換到不同的 Celery broker，例如 RabbitMQ。

Workers

如果您看到錯誤，例如

Background workers haven’t checked in recently. It seems that you have a backlog of 200 tasks. Either your workers aren’t running or you need more capacity. 

您可能會從使用額外的專職工作人員中受益。這是通過在 docker-compose.override.yml 中創建新的 worker 服務并使用 -Q queue_name 參數將它們綁定到特定隊列來實現的。一個例子是：

worker1: 
    << : *sentry_defaults 
    command: run worker -Q events.process_event 

要查看更完整的示例，請參閱我們社區論壇上的示例解決方案。

• https://forum.sentry.io/t/how-to-clear-backlog-and-monitor-it/10715/14?u=byk

Postgres

Postgres 用于主數據存儲，以及用于存儲 key/value 數據的 nodestore。 node_nodestore 表可以快速增長，尤其是在大量使用性能監控功能時，因為跟蹤數據存儲在該表中。

• https://develop.sentry.dev/services/nodestore/

node_nodestore 表作為 cleanup 任務的一部分被清理， 但是 Postgres 可能沒有機會清理表(尤其是在重載情況下)，所以即使行可能被刪除，它們仍然會占用磁盤空間。

您可以使用 pg-repack，它通過創建一個新表并在刪除舊表之前復制數據來重新打包一個表。您需要在清理腳本之后運行它，并注意它在創建表時，磁盤使用量會在回落之前激增。

下面是一個腳本示例：

# Only keep the last 7 days of nodestore data. We heavily use performance monitoring. 
docker-compose run -T web cleanup --days 7 -m nodestore -l debug 
# This ensures pg-repack exists before running as the container gets recreated on upgrades 
docker-compose run -T postgres bash -c "apt update && apt install -y --no-install-recommends postgresql-9.6-repack && su postgres -c 'pg_repack -E info -t nodestore_node'" 

其他

如果您仍然遇到問題，您可以隨時訪問我們的社區論壇以搜索現有主題或創建新主題并尋求幫助。請記住，我們希望社區能夠幫助自己，并且 Sentry 員工也會在有時間時嘗試監控和回答論壇問題。

• https://forum.sentry.io/

在報告問題或在論壇上提問時共享您的安裝日志、服務日志和 Sentry 版本將為您和試圖幫助您的人節省時間和精力。

• https://github.com/getsentry/self-hosted/issues/new/choose