面向離線 K3s 場景的 Sentry 一鍵部署方案：sentry-off

前言

在企業(yè)內網、政務云、教育私有化、工業(yè)現(xiàn)場等環(huán)境里，Sentry 往往不是不能用，而是“不容易落地”。

難點并不只在于把一個 Web 服務跑起來，而在于它背后還帶著一整條依賴鏈：

  • 應用本體：Sentry
  • 隊列：Kafka
  • 元數(shù)據(jù)：PostgreSQL
  • 緩存：Redis
  • 事件存儲：ClickHouse
  • 輔助組件：Relay、Nginx、Vroom

如果目標環(huán)境還是 離線 + K3s + ARM64 單機，問題就會進一步放大：鏡像拉不下來、Chart 不能現(xiàn)場下載、手工改模板容易漏、升級和回放流程也難以標準化。

sentry-off 這個項目就是圍繞這個問題展開的。它的目標不是做一個“大而全”的 Sentry 發(fā)行版，而是提供一條清晰、可重復的離線路徑：

  • 在有網機器上完成打包
  • 在離線機器上完成安裝
  • 用同一份配置文件管理安裝、升級和后續(xù)調整

為什么離線部署 Sentry 容易踩坑

Sentry 自托管本身并不算輕量，離線場景下通常會遇到幾類典型問題。

1. 依賴鏈長

不是只部署一個應用鏡像就結束，而是需要同時處理多套組件、配置和持久化。

2. 網絡前提不同

很多在線文檔默認可以直接訪問公網倉庫，但離線現(xiàn)場往往根本不能拉鏡像、不能裝 Helm、不能臨時查資料。

3. 單機資源有限

離線環(huán)境常常不是“專門給 Sentry 一臺大機器”，而是要和其他業(yè)務共享 CPU、內存和磁盤，所以資源限制必須提前考慮。

4. 手工步驟太多

如果靠人工執(zhí)行“拉鏡像、導出鏡像、改 values、裝 ClickHouse、裝 Sentry、打補丁、做清理策略”，過程很容易失控。

sentry-off 的思路

這個項目把整個過程拆成兩段：

有網機器
  -> 下載 Chart
  -> 渲染模板
  -> 提取鏡像
  -> 拉取 linux/arm64 鏡像
  -> 打離線包

離線機器
  -> 導入鏡像到 k3s containerd
  -> 渲染當前配置
  -> 部署 ClickHouse
  -> Helm 安裝/升級 Sentry
  -> 健康檢查

它做的不是“隱藏復雜度”，而是把復雜度盡量固化到腳本里，避免每次都重復踩坑。

項目實際落地了哪些能力

結合倉庫腳本和模板來看，sentry-off 當前具備這些明確能力。

1. 在線打包完整離線安裝材料

scripts/prepare-online.sh 會自動完成：

  • 下載指定版本的 sentry-kubernetes Chart
  • 下載離線包附帶的 helm 二進制
  • 渲染 Sentry / ClickHouse / ClickHouse cleanup 模板
  • 用 helm template 輸出結果提取鏡像列表
  • 拉取全部 linux/arm64 鏡像
  • 生成鏡像 tar 包、校驗和和最終壓縮包

生成物不只是一個鏡像包，還會包含：

  • scripts/
  • templates/
  • bundle/
  • config/cluster.env
  • config/cluster.env.example

這意味著離線機拿到壓縮包以后，不需要再臨時拼裝腳本環(huán)境。

2. 離線機一鍵安裝

scripts/install-offline.sh 的核心流程是：

  1. 讀取當前環(huán)境變量文件
  2. 重新渲染模板
  3. 創(chuàng)建目標命名空間
  4. 把鏡像導入 sudo k3s ctr
  5. 創(chuàng)建 sentry-admin-password Secret
  6. 部署單機 ClickHouse
  7. 用 Helm 安裝 Sentry
  8. 對 nginx Service 再補一次 NodePort patch

這一步的好處是，離線側仍然保留了“按當前環(huán)境重新渲染”的能力，而不是死用打包時的靜態(tài) YAML。

3. 離線機支持升級

scripts/upgrade-offline.sh 和安裝流程保持一致，會重新導入鏡像、刷新管理員密碼 Secret、重新渲染模板，再執(zhí)行 Helm 升級。

這讓升級流程和首次安裝流程盡量保持同構，降低維護成本。

4. 內置 ClickHouse，而不是依賴現(xiàn)場補裝

項目沒有把 ClickHouse 完全交給上游 Chart 管理，而是單獨維護了一個 StatefulSet + PVC 模板，便于在單機環(huán)境下明確控制：

  • 服務名
  • 存儲大小
  • 資源請求
  • 探針行為

對于離線單機場景來說，這種“顯式建?！钡姆绞酵ǔ１扰R時拼接更穩(wěn)定。

5. 自帶 ClickHouse 物理清理任務

這是項目里一個很實用的點。

模板里顯式關閉了上游 snuba.cleanup，改為使用自己的 CronJob。它不會去掃所有 ClickHouse 表，而是只處理一組白名單事件表，并結合：

  • SENTRY_EVENT_RETENTION_DAYS
  • SENTRY_CH_CLEANUP_SCHEDULE
  • SENTRY_CH_CLEANUP_MAX_MEMORY_BYTES

來做更保守的物理清理。

對于單機離線環(huán)境，這種策略比“一股腦啟上游清理”更容易控制風險。

當前默認形態(tài)

從 cluster.env.example 和模板可以看出，這個項目當前的默認定位非常明確。

  • 目標架構：linux-arm64
  • 默認檔位：errors-only
  • 默認入口：NodePort 31080
  • 默認保留天數(shù)：30
  • symbolicator：默認關閉
  • mail.backend：dummy
  • sourcemaps：默認關閉

一句話總結就是：先保證單機離線能穩(wěn)定落地，再談更完整功能。

5 步上手

Step 1：準備配置文件

cp config/cluster.env.example config/cluster.env

至少修改這幾個關鍵參數(shù)：

SENTRY_BASE_URL=http://<離線主機IP>:31080
SENTRY_ADMIN_EMAIL=admin@example.com
SENTRY_ADMIN_PASSWORD=<強密碼>

Step 2：在有網機器打包

bash scripts/prepare-online.sh

腳本執(zhí)行完成后，會生成 bundle/ 和 dist/sentry-offline-<version>-linux-arm64.tar.gz。

Step 3：拷貝到離線機器

scp dist/sentry-offline-*.tar.gz <user>@<offline-host>:/opt/

Step 4：解壓并安裝

tar -xzf sentry-offline-*.tar.gz
cd sentry-off
sudo bash scripts/install-offline.sh

Step 5：訪問系統(tǒng)

http://<離線主機IP>:31080

配置上有哪些值得關注的點

這個項目把絕大部分可調項都集中到了 config/cluster.env，這點對離線維護非常友好。

1. 入口與管理員

SENTRY_BASE_URL=http://<離線主機IP>:31080
SENTRY_NGINX_NODE_PORT=31080
SENTRY_ADMIN_EMAIL=admin@example.com
SENTRY_ADMIN_PASSWORD=<強密碼>

2. 功能檔位

SENTRY_PROFILE=errors-only

如果機器資源有限，建議優(yōu)先堅持默認值。feature-complete 更適合資源更充足、對完整能力有明確訴求的場景。

3. 保留與清理

SENTRY_EVENT_RETENTION_DAYS=30
SENTRY_CH_CLEANUP_ENABLED=true
SENTRY_CH_CLEANUP_SCHEDULE=30 3 * * *

4. 存儲大小

CLICKHOUSE_STORAGE_SIZE=50Gi
POSTGRES_STORAGE_SIZE=20Gi
REDIS_STORAGE_SIZE=8Gi
KAFKA_STORAGE_SIZE=20Gi
FILESTORE_STORAGE_SIZE=20Gi

5. 組件資源限制

模板里已經為 web、worker、snuba、kafka、postgres、redis、relay、nginx 等組件預置了 CPU 和內存 request/limit，這對單機部署很重要。

和常見做法相比，它解決了什么

如果按傳統(tǒng)方式做離線部署，通常要自己手工完成下面這些事情：

  • 識別需要哪些鏡像
  • 一個個拉取并導出
  • 在離線機導入 containerd
  • 自己準備 Helm
  • 自己維護 values 文件
  • 自己處理 ClickHouse
  • 自己再補一套清理策略

sentry-off 并不是把這些步驟“變沒了”，而是把它們標準化成了一套工程流程。這對團隊協(xié)作最大的價值在于：

  • 可重復
  • 可交接
  • 可升級
  • 配置集中
  • 風險邊界更清楚

使用邊界也要說清楚

這個項目當前不是一個“放到任何環(huán)境都能直接通吃”的方案，至少有這些邊界：

  • 當前只面向 linux-arm64
  • 默認假設離線目標是 k3s
  • Sentry 的 Kubernetes 安裝依賴社區(qū) sentry-kubernetes Chart
  • 離線包會攜帶 config/cluster.env，里面可能包含敏感信息，需要自行保護
  • 如果你要切到更復雜的生產級高可用方案，還需要在此基礎上繼續(xù)擴展

換句話說，它更像一個“單機離線部署基線工程”，而不是大規(guī)模生產多節(jié)點發(fā)行版。

適合誰用

如果你面臨的是下面這些場景，這個項目會比較對路：

  • 政務云或專網環(huán)境
  • 校園網或教育私有化平臺
  • 工廠內網或工業(yè)邊緣環(huán)境
  • 無法直接訪問公網的 K3s / ARM64 機器
  • 需要快速搭一套可維護的 Sentry 基線環(huán)境

結語

離線環(huán)境部署 Sentry 的難點，從來都不是某一個 YAML 文件，而是整條鏈路是否足夠標準化。

sentry-off 做的事情很樸素：把在線準備、離線安裝、后續(xù)升級、清理和健康檢查這些步驟統(tǒng)一起來，讓“能部署一次”變成“能持續(xù)維護”。

如果你也在做 離線 K3s 單機 + ARM64 場景下的 Sentry 落地，這個倉庫可以直接拿來試，也可以作為你們內部方案的起點。

項目地址：https://gitee.com/zhaojiale1016/sentry-off

最后編輯于 ：
?著作權歸作者所有,轉載或內容合作請聯(lián)系作者
【社區(qū)內容提示】社區(qū)部分內容疑似由AI輔助生成，瀏覽時請結合常識與多方信息審慎甄別。
平臺聲明：文章內容（如有圖片或視頻亦包括在內）由作者上傳并發(fā)布，文章內容僅代表作者本人觀點，簡書系信息發(fā)布平臺，僅提供信息存儲服務。

相關閱讀更多精彩內容

友情鏈接更多精彩內容