Sentry 26.10.0 配置参数详解

目标：逐项讲清自托管 Sentry 26.10.0 的三层配置体系——编排层 .env、应用层 sentry/config.yml、框架层 sentry/sentry.conf.py——每一层管什么、改了怎么生效，并用实测验证两个典型参数（system.url-prefix、SENTRY_BIND）的生效效果。全部回显来自实测环境真实采集。

一、环境信息

操作系统：Ubuntu 22.04（x86_64）
Sentry self-hosted：26.10.0（仓库 tag 26.10.0，commit 5f84986）
Docker Engine：29.8.1，Docker Compose：v5.5.1
配置文件位置：self-hosted 仓库目录（本文为 /root/sentry）下：.env、sentry/config.yml、sentry/sentry.conf.py
对外入口：http://127.0.0.1:9000（默认 SENTRY_BIND=9000）
管理员账号：admin@sentry.local / q1w2e3r4（本文演示账号）

二、前置条件

已完成部署并正常运行（53 服务全部 healthy）。
能在部署机执行 docker compose 命令。
了解修改配置的两种生效方式（见第三章），本文实测均在验证后还原。

三、配置体系总览

Sentry self-hosted 的配置分三层，各自职责与生效方式不同（这是排错前必须建立的心智模型）：

层	文件	语法	管什么	生效方式
编排层	`.env`	KEY=VALUE	端口、功能档位、镜像版本、保留天数等编排变量	`docker compose up -d`（重建受影响服务）
应用层	`sentry/config.yml`	YAML	邮件、URL 前缀、存储、缓存等 Sentry 选项	`docker compose restart web taskworker`（进程重载）
框架层	`sentry/sentry.conf.py`	Python	数据库连接、内部 IP、从 .env 派生的选项	同上，且修改前需懂 Django 配置

三者的加载关系：install.sh 安装时从样例（.env.example、sentry/config.example.yml、sentry/sentry.conf.example.py）生成正式配置；sentry.conf.py 会读取 .env 的部分变量派生配置（如 SENTRY_EVENT_RETENTION_DAYS → system.event-retention-days）；config.yml 与 sentry.conf.py 以只读方式挂载进相关服务。

cd /root/sentry
ls sentry/

实测回显（输出节选）：

config.example.yml  config.yml  sentry.conf.example.py  sentry.conf.py

四、.env 参数详解

安装脚本生成的 .env 全量内容（实测）：

COMPOSE_PROJECT_NAME=sentry-self-hosted
COMPOSE_PROFILES=feature-complete
SENTRY_EVENT_RETENTION_DAYS=90
LAUNCHPAD_RPC_SHARED_SECRET=supersecret
SENTRY_BIND=9000
SENTRY_TASKWORKER_CONCURRENCY=4
SENTRY_IMAGE=ghcr.io/getsentry/sentry:26.10.0
SNUBA_IMAGE=ghcr.io/getsentry/snuba:26.10.0
RELAY_IMAGE=ghcr.io/getsentry/relay:26.10.0
SYMBOLICATOR_IMAGE=ghcr.io/getsentry/symbolicator:26.10.0
TASKBROKER_IMAGE=ghcr.io/getsentry/taskbroker:26.10.0
VROOM_IMAGE=ghcr.io/getsentry/vroom:26.10.0
UPTIME_CHECKER_IMAGE=ghcr.io/getsentry/uptime-checker:26.10.0
LAUNCHPAD_IMAGE=ghcr.io/getsentry/launchpad:26.10.0
HEALTHCHECK_INTERVAL=60s
HEALTHCHECK_TIMEOUT=10s
HEALTHCHECK_RETRIES=10
HEALTHCHECK_START_PERIOD=40s
SENTRY_KAFKA_MAX_POLL_INTERVAL_MS=120000
SENTRY_MAIL_HOST=
STATSD_ADDR=

逐项说明：

参数	默认值	说明
COMPOSE_PROJECT_NAME	sentry-self-hosted	编排项目名；决定全部服务名、网络名、数据卷前缀。改名等于新建一套栈，不建议改
COMPOSE_PROFILES	feature-complete	功能档位。`errors-only` 仅启用错误监控（官方内存下限从 14 GB 降至 7 GB），其余档位为 `feature-complete`
SENTRY_EVENT_RETENTION_DAYS	90	事件保留天数。传递给清理任务与 Snuba 清理，设小可显著省磁盘；90 天为官方默认
LAUNCHPAD_RPC_SHARED_SECRET	安装时生成	Launchpad 接入服务内部 RPC 密钥，保持默认即可
SENTRY_BIND	9000	对外端口。nginx 的端口映射写成官方配置 `"${SENTRY_BIND}:80"`，改后需 `docker compose up -d` 重建
SENTRY_TASKWORKER_CONCURRENCY	4	后台任务执行并发。低配机器可降为 2，内存实测可从约 1.3 GB 明显回落
SENTRY_IMAGE / SNUBA_IMAGE / RELAY_IMAGE / SYMBOLICATOR_IMAGE / TASKBROKER_IMAGE / VROOM_IMAGE / UPTIME_CHECKER_IMAGE / LAUNCHPAD_IMAGE	对应 26.10.0 tag	组件镜像版本锁定。升级由官方发版统一更新，保持与 `docker-compose.yml` 的引用一致
HEALTHCHECK_INTERVAL / TIMEOUT / RETRIES / START_PERIOD	60s / 10s / 10 / 40s	全部服务健康检查节奏。低配机器启动慢时可加大 START_PERIOD 与 RETRIES
SENTRY_KAFKA_MAX_POLL_INTERVAL_MS	120000	Kafka 消费者单轮处理的最大间隔，消费积压报警时可适当调大
SENTRY_MAIL_HOST	空	出站邮件域名（HELO/发件域）。为空时 `sentry.conf.py` 派生 `mail.list-namespace=localhost`，发件人变 `sentry@localhost`，会被邮件中继拒收（实测见《进阶实战与运维》）
STATSD_ADDR	空	统计指标上报地址（如 `127.0.0.1:8125`），空则关闭指标外发

💡 技术拓展：.env 只被 Docker Compose 读取（变量替换进 docker-compose.yml），Sentry 应用进程本身不读它；应用能感知的是 sentry.conf.py 里从环境变量再读一遍的那几个键（SENTRY_EVENT_RETENTION_DAYS、SENTRY_SYSTEM_SECRET_KEY、SENTRY_MAIL_HOST）。自定义变量建议追加到 .env.custom，安装脚本会自动合并，避免升级时被覆盖。

4.1 实测：修改 SENTRY_BIND 端口

cd /root/sentry
sed -i 's/^SENTRY_BIND=9000/SENTRY_BIND=9001/' .env
docker compose up -d
docker port sentry-self-hosted-nginx-1
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:9001/auth/login/

实测回显：

 Container sentry-self-hosted-nginx-1  Recreate
 Container sentry-self-hosted-nginx-1  Started
80/tcp -> 0.0.0.0:9001
80/tcp -> [::]:9001
200

还原（改回 9000 后再次 docker compose up -d，实测仅重建 nginx，其余 52 服务不动）：

80/tcp -> 0.0.0.0:9000
80/tcp -> [::]:9000

结论：.env 修改的生效路径是「重建受影响的服务」，端口变量只影响 nginx，因此其余服务无需重启。

五、config.yml 参数详解

install.sh 生成的 sentry/config.yml 有效配置项（实测，去除注释与空行）：

mail.host: 'smtp'
system.internal-url-prefix: 'http://web:9000'
system.secret-key: 'vo;]s*[E%6hL[=i\=m7#<X^(m4Btude2+*I*k#XnkSorkksA+g'
filestore.backend: 'filesystem'
filestore.options:
  location: '/data/files'
dsym.cache-path: '/data/dsym-cache'
releasefile.cache-path: '/data/releasefile-cache'
filestore.profiles-backend: 's3'
filestore.profiles-options:
  bucket_acl: "private"
  default_acl: "private"

样例文件中其余可选项（sentry/config.example.yml，默认注释）按节整理：

5.1 mail.*（邮件）

参数	默认	说明
mail.backend	smtp	邮件后端。`smtp` 走 SMTP 服务器；`dummy` 完全禁用邮件发送
mail.use-tls	false	是否使用 TLS（465 端口直连）；另有一个独立的 `mail.use-ssl` 选项，二选一
mail.host	smtp	SMTP 服务器地址。默认 `smtp` 指向内置邮件中继；企业场景改为内部 Exchange/邮件网关地址
mail.port	25	SMTP 端口。use-tls 一般配 465，明文带 STARTTLS 用 587
mail.username / mail.password	空	SMTP 认证凭证
mail.from	sentry@localhost	发件人地址。生产必须改为真实域名（也受 `SENTRY_MAIL_HOST` 派生影响）
mail.list-namespace	localhost	邮件列表命名空间，影响回复地址
mail.subject-prefix	[Sentry]	邮件主题前缀

5.2 system.*（系统）

参数	默认	说明
system.url-prefix	（注释，无）	实例对外地址，如 `https://sentry.example.com`。影响：事件详情链接、邮件链接、界面展示的 DSN 前缀。生产必配
system.internal-url-prefix	http://web:9000	编排内部地址，用于服务间改写
system.secret-key	安装时生成	全局加密密钥：登录会话、CSRF、Relay 注册。更换后所有会话失效，且影响已注册 Relay

5.3 filestore.*（文件存储）

参数	默认	说明
filestore.backend	filesystem	事件附件等文件存储后端。`filesystem` 用本地数据卷；多节点部署必须改 `s3`（亦支持 GCS/OSS 兼容接口）
filestore.options.location	/data/files	filesystem 模式的存储路径（挂载自 sentry-data 数据卷）
filestore.options	—	s3 模式下配 access_key/secret_key/bucket_name/endpoint_url 等
filestore.profiles-backend / profiles-options	s3 / —	Profiling 数据的独立存储（默认走 s3 指向 SeaweedFS）

5.4 缓存与符号化

参数	默认	说明
dsym.cache-path	/data/dsym-cache	调试符号缓存目录
releasefile.cache-path	/data/releasefile-cache	发行版文件缓存目录
symbolicator.enabled	（注释）	是否启用独立符号化服务（26.10.0 编排已内置 symbolicator 服务，保持默认）

5.5 redis.clusters（缓存集群）

样例中为注释状态，默认由 sentry.conf.py 提供 redis:6379 单节点：

redis.clusters:
  default:
    hosts:
      0:
        host: redis
        port: 6379

外置 Redis/哨兵集群时在此改写。

5.6 其他

参数	说明
transaction-events.force-disable-internal-project	置 true 可关闭内部项目的事件上报（省资源）
beacon.artificial-latency	向 sentry.io 版本检查请求加延迟（隔离网络排查用）
github-app.*	GitHub 应用集成配置（私有部署 GitHub 场景）

5.7 实测：修改 system.url-prefix 并验证 DSN 变化

cd /root/sentry
sed -i 's|^# system.url-prefix: https://example.sentry.com|system.url-prefix: "http://sentry.example.com:9000"|' sentry/config.yml
grep -n '^system.url-prefix' sentry/config.yml
docker compose run --rm -T web shell -c "
from sentry.models.projectkey import ProjectKey
k = ProjectKey.objects.get(project_id=2)
print('dsn_public:', k.dsn_public)
"

实测回显：

1:system.url-prefix: "http://sentry.example.com:9000"
dsn_public: http://739eaf5acad60fa61c7700b1ea7afc29@sentry.example.com:9000/2

对比修改前（未配置 url-prefix 时，DSN 主机段直接取入口地址）：

http://739eaf5acad60fa61c7700b1ea7afc29@127.0.0.1:9000/2

⚠️ 注意与还原：url-prefix 指向的域名必须真实可解析，否则 Web 进程内部回调会持续报 Failed to resolve <域名>（实测 docker compose logs web 出现 NameResolutionError）。测试完成后本文已将该项还原为注释并 docker compose restart web。生产环境配置该参数前，先确保 DNS/hosts 解析就绪。

5.8 实测：重新生成 system.secret-key

docker compose run --rm -T web config generate-secret-key

实测回显：

dz^x+u8i3#&0mm5m%u44v=6@ja1cc_0&!lxcs_pl5oegu7k7&+

把输出替换进 config.yml 的 system.secret-key 后重启 web/taskworker 即完成换钥（全员会被登出，Relay 需重新注册）。本文实测后保持原密钥未替换。

六、sentry.conf.py 参数详解

该文件以 from sentry.conf.server import * 开头继承默认 Django 配置，自托管主要用它管理「数据库连接 + 内部网络 + 从 .env 派生的选项」。关键块（生成文件实测）：

6.1 DATABASES（数据库连接）

DATABASES = {
    "default": {
        "ENGINE": "sentry.db.postgres",
        "NAME": "postgres",
        "USER": "postgres",
        "PASSWORD": "",
        "HOST": "pgbouncer",
        "PORT": "",
    }
}

库名固定为 postgres（不是 sentry！备份命令直接用该名，实测见《进阶实战与运维》）。
HOST: pgbouncer 表示所有应用连接走连接池服务，postgres 服务仅对 pgbouncer 可见。
外置 PostgreSQL 时改 HOST/NAME/USER/PASSWORD，并同步调整编排文件。

6.2 SENTRY_OPTIONS 派生项

SENTRY_OPTIONS["system.event-retention-days"] = int(
    env("SENTRY_EVENT_RETENTION_DAYS", "90")
)

if env("SENTRY_SYSTEM_SECRET_KEY"):
    SENTRY_OPTIONS["system.secret-key"] = env("SENTRY_SYSTEM_SECRET_KEY", "")

SENTRY_OPTIONS["mail.list-namespace"] = env("SENTRY_MAIL_HOST", "localhost")
SENTRY_OPTIONS["mail.from"] = f"sentry@{SENTRY_OPTIONS['mail.list-namespace']}"

含义：system.event-retention-days 与 system.secret-key 也可以用环境变量覆盖（优先级：环境变量 > config.yml）；发件人地址由 SENTRY_MAIL_HOST 派生，这解释了 5.1 节 mail.from 为空时为何变成 sentry@localhost。

6.3 INTERNAL_SYSTEM_IPS（内部网段）

INTERNAL_SYSTEM_IPS = (get_internal_network(),)

脚本自动探测内网网段，用于「内部接口白名单」（如健康检查路径、内部 API 鉴权豁免）。跨网段编排或有双网卡环境时手工补充。

6.4 GITHUB_APP 块

样例提供了 GitHub 应用集成的环境变量化配置（GITHUB_APP_ID/GITHUB_APP_CLIENT_ID 等），未集成时保持空即可。

七、生产配置模板

按规模给出关键差异项的最小修改集（其余保持安装默认）：

配置项	单机小团队	中型生产	大型/多节点
COMPOSE_PROFILES	feature-complete	feature-complete	feature-complete（拆分存储需自行改编排）
SENTRY_EVENT_RETENTION_DAYS	90	30~90（按磁盘）	30
SENTRY_BIND	9000	9000（反代后）	9000
system.url-prefix	http://IP:9000	https://sentry.example.com	https://sentry.example.com
mail.*	内置 smtp 即可	企业 SMTP/网关	企业 SMTP + SENTRY_MAIL_HOST
filestore.backend	filesystem	filesystem（定时备份卷）	s3（对象存储）
SENTRY_TASKWORKER_CONCURRENCY	4	8	按流量扩展
STATSD_ADDR	空	可接入	必配（Prometheus/StatsD）

💡 技术拓展：Sentry 自托管默认把数据落在单机数据卷（PostgreSQL/ClickHouse/Kafka/SeaweedFS 各一）。所谓「大型配置」并非改几个参数就能水平扩展，而是要把有状态服务（尤其 ClickHouse 与 Kafka）迁出编排为集群，再让 Sentry 指向集群地址——属于架构级改造，超出了配置参数范畴，此处仅给出边界说明。

八、参数修改与生效验证

标准修改流程（以生产环境最常见三项为例）：

cd /root/sentry

# 1) 改 .env（编排层）
sed -i 's/^SENTRY_EVENT_RETENTION_DAYS=90/SENTRY_EVENT_RETENTION_DAYS=30/' .env

# 2) 改 config.yml（应用层）：配置 url-prefix 与邮件
#    编辑 system.url-prefix 与 mail.* 各项后：

# 3) 应用编排层变更（重建受影响服务）
docker compose up -d

# 4) 重载应用层变更（进程内配置）
docker compose restart web taskworker

# 5) 验证
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:9000/auth/login/

实测回显：

 Container sentry-self-hosted-web-1  Restarting
 Container sentry-self-hosted-web-1  Started
 Container sentry-self-hosted-nginx-1  Restarting
 Container sentry-self-hosted-nginx-1  Started
200

验证事件保留天数已生效（应用进程内读取）：

docker compose run --rm -T web shell -c "
from sentry.conf.server import SENTRY_OPTIONS
print('retention-days:', SENTRY_OPTIONS.get('system.event-retention-days'))
"

实测回显：

retention-days: 30

九、常见问题（FAQ）

Q1：改了 config.yml 没生效？ config.yml 是挂载进服务进程的文件，必须重启读取它的进程：docker compose restart web taskworker（涉及查询还要重启 snuba-api 对应选项的场景较少）。.env 则要用 docker compose up -d 重建。两类文件生效方式不同，别混用。

Q2：system.secret-key 能随意换吗？ 能，但有代价：所有登录会话失效、Relay 注册失效。换钥后 docker compose restart web taskworker，并在界面重新登录；有独立 Relay 部署的需重新注册。

Q3：url-prefix 用 http 还是 https？ 取决于入口实际协议。编排默认 http（nginx 直连）；生产在前置负载均衡终结 TLS 时填 https，并确保 X-Forwarded-Proto 被传递，否则生成的链接与 Cookie 安全属性会错。

Q4：多个配置来源的优先级？ 环境变量（sentry.conf.py 中 env() 读取）> sentry/config.yml > sentry.conf.server 内置默认。排查「改了没生效」时，先确认没有被更高优先级来源覆盖。

Q5：mail.from 与 SENTRY_MAIL_HOST 的关系？ sentry.conf.py 固定用 SENTRY_MAIL_HOST 派生 mail.from = sentry@<SENTRY_MAIL_HOST>，因此在 config.yml 里手工改 mail.from 会被启动时覆盖；正确做法是设置 .env 的 SENTRY_MAIL_HOST=<真实域名>。

Q6：如何确认某配置项当前运行值？ 用管理命令行直接读选项存储：

cd /root/sentry
docker compose run --rm -T web shell -c "
from sentry.options import get
print('url-prefix:', get('system.url-prefix'))
print('mail.host:', get('mail.host'))
"

实测回显（本文还原 url-prefix 后的状态）：

url-prefix: None
mail.host: smtp

十、参考链接

Sentry 官网：https://sentry.io
self-hosted 配置文档（on-premise configuration）：https://develop.sentry.dev/self-hosted/
config.yml 样例（官方仓库）：https://github.com/getsentry/self-hosted/blob/master/sentry/config.example.yml
sentry.conf.py 样例（官方仓库）：https://github.com/getsentry/self-hosted/blob/master/sentry/sentry.conf.example.py
选项系统说明（options）：https://develop.sentry.dev/config/options/
errors-only 模式：https://develop.sentry.dev/self-hosted/optional-features/errors-only/