面向离线 K3s 场景的 Sentry 一键部署方案：sentry-off

前言

在企业内网、政务云、教育私有化、工业现场等环境里，Sentry 往往不是不能用，而是“不容易落地”。

难点并不只在于把一个 Web 服务跑起来，而在于它背后还带着一整条依赖链：

应用本体：Sentry
队列：Kafka
元数据：PostgreSQL
缓存：Redis
事件存储：ClickHouse
辅助组件：Relay、Nginx、Vroom

如果目标环境还是 离线 + K3s + ARM64 单机，问题就会进一步放大：镜像拉不下来、Chart 不能现场下载、手工改模板容易漏、升级和回放流程也难以标准化。

sentry-off 这个项目就是围绕这个问题展开的。它的目标不是做一个“大而全”的 Sentry 发行版，而是提供一条清晰、可重复的离线路径：

在有网机器上完成打包
在离线机器上完成安装
用同一份配置文件管理安装、升级和后续调整

为什么离线部署 Sentry 容易踩坑

Sentry 自托管本身并不算轻量，离线场景下通常会遇到几类典型问题。

1. 依赖链长

不是只部署一个应用镜像就结束，而是需要同时处理多套组件、配置和持久化。

2. 网络前提不同

很多在线文档默认可以直接访问公网仓库，但离线现场往往根本不能拉镜像、不能装 Helm、不能临时查资料。

3. 单机资源有限

离线环境常常不是“专门给 Sentry 一台大机器”，而是要和其他业务共享 CPU、内存和磁盘，所以资源限制必须提前考虑。

4. 手工步骤太多

如果靠人工执行“拉镜像、导出镜像、改 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

这意味着离线机拿到压缩包以后，不需要再临时拼装脚本环境。

2. 离线机一键安装

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

读取当前环境变量文件
重新渲染模板
创建目标命名空间
把镜像导入 sudo k3s ctr
创建 sentry-admin-password Secret
部署单机 ClickHouse
用 Helm 安装 Sentry
对 nginx Service 再补一次 NodePort patch

这一步的好处是，离线侧仍然保留了“按当前环境重新渲染”的能力，而不是死用打包时的静态 YAML。

3. 离线机支持升级

scripts/upgrade-offline.sh 和安装流程保持一致，会重新导入镜像、刷新管理员密码 Secret、重新渲染模板，再执行 Helm 升级。

这让升级流程和首次安装流程尽量保持同构，降低维护成本。

4. 内置 ClickHouse，而不是依赖现场补装

项目没有把 ClickHouse 完全交给上游 Chart 管理，而是单独维护了一个 StatefulSet + PVC 模板，便于在单机环境下明确控制：

服务名
存储大小
资源请求
探针行为

对于离线单机场景来说，这种“显式建模”的方式通常比临时拼接更稳定。

5. 自带 ClickHouse 物理清理任务

这是项目里一个很实用的点。

模板里显式关闭了上游 snuba.cleanup，改为使用自己的 CronJob。它不会去扫所有 ClickHouse 表，而是只处理一组白名单事件表，并结合：

SENTRY_EVENT_RETENTION_DAYS
SENTRY_CH_CLEANUP_SCHEDULE
SENTRY_CH_CLEANUP_MAX_MEMORY_BYTES

来做更保守的物理清理。

对于单机离线环境，这种策略比“一股脑启上游清理”更容易控制风险。

当前默认形态

从 cluster.env.example 和模板可以看出，这个项目当前的默认定位非常明确。

目标架构：linux-arm64
默认档位：errors-only
默认入口：NodePort 31080
默认保留天数：30
symbolicator：默认关闭
mail.backend：dummy
sourcemaps：默认关闭

一句话总结就是：先保证单机离线能稳定落地，再谈更完整功能。

5 步上手

Step 1：准备配置文件

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

至少修改这几个关键参数：

SENTRY_BASE_URL=http://<离线主机IP>:31080
SENTRY_ADMIN_EMAIL=admin@example.com
SENTRY_ADMIN_PASSWORD=<强密码>

Step 2：在有网机器打包

bash scripts/prepare-online.sh

脚本执行完成后，会生成 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：访问系统

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

如果机器资源有限，建议优先坚持默认值。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，这对单机部署很重要。

和常见做法相比，它解决了什么

如果按传统方式做离线部署，通常要自己手工完成下面这些事情：

识别需要哪些镜像
一个个拉取并导出
在离线机导入 containerd
自己准备 Helm
自己维护 values 文件
自己处理 ClickHouse
自己再补一套清理策略

sentry-off 并不是把这些步骤“变没了”，而是把它们标准化成了一套工程流程。这对团队协作最大的价值在于：

可重复
可交接
可升级
配置集中
风险边界更清楚

使用边界也要说清楚

这个项目当前不是一个“放到任何环境都能直接通吃”的方案，至少有这些边界：

当前只面向 linux-arm64
默认假设离线目标是 k3s
Sentry 的 Kubernetes 安装依赖社区 sentry-kubernetes Chart
离线包会携带 config/cluster.env，里面可能包含敏感信息，需要自行保护
如果你要切到更复杂的生产级高可用方案，还需要在此基础上继续扩展

换句话说，它更像一个“单机离线部署基线工程”，而不是大规模生产多节点发行版。

适合谁用

如果你面临的是下面这些场景，这个项目会比较对路：

政务云或专网环境
校园网或教育私有化平台
工厂内网或工业边缘环境
无法直接访问公网的 K3s / ARM64 机器
需要快速搭一套可维护的 Sentry 基线环境

结语

离线环境部署 Sentry 的难点，从来都不是某一个 YAML 文件，而是整条链路是否足够标准化。

sentry-off 做的事情很朴素：把在线准备、离线安装、后续升级、清理和健康检查这些步骤统一起来，让“能部署一次”变成“能持续维护”。

如果你也在做 离线 K3s 单机 + ARM64 场景下的 Sentry 落地，这个仓库可以直接拿来试，也可以作为你们内部方案的起点。

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

面向离线 K3s 场景的 Sentry 一键部署方案：sentry-off