GlitchTip 6.2.6 配置参数详解
GlitchTip 6.2.6 配置参数体系全解：加载机制、必配项、基础设施、安全访问、功能开关、数据保留、邮件与 SSO、对象存储与调优项，官方默认值与实测生效值对照（2026-10-27 实测）。
GlitchTip 6.2.6 配置参数详解
目标：系统梳理 GlitchTip 6.2.6 的全部配置参数体系：配置加载机制、必配项、基础设施、安全访问、功能开关、数据保留、邮件、SSO、对象存储与调优项，每类参数给出官方口径默认值与实测生效值对照。所有「实测生效值」来自 2026-10-27 部署实例（详见《GlitchTip 6.2.6 Docker Compose 部署实战》）中
manage.py shell对 Django settings 的真实导出。
一、环境信息
本篇参数验证基于以下实测环境（参数实测均在部署实例上执行）：
- 操作系统：Ubuntu 22.04 LTS（x86_64）
- GlitchTip：6.2.6（SERVER_ROLE=all_in_one，
docker exec进入服务执行 Django 管理命令验证） - PostgreSQL：18（DATABASE_URL 接入）；Valkey：9（VALKEY_URL 接入）
- 验证方法：
./manage.py shell -c "from django.conf import settings; ..."导出生效配置值 - 编排注入：Docker Compose
environment段（x-environment 锚点合并注入） - 查询日期：2026-10-27（官方口径值取自官方安装文档同日版本）
二、配置体系总览
GlitchTip 没有配置文件——全部配置通过环境变量注入，由 Django 启动时读取（django-environ 机制）转为内部 settings 属性。这决定了它的三条配置铁律：
- 改配置 = 改环境变量 + 重启服务：Compose 场景改
environment后docker compose up -d（重建实例使新变量生效）；没有 reload 类热加载； - 环境变量名 ≠ settings 属性名：两者大致对应但存在映射关系，例如环境变量
GLITCHTIP_DOMAIN对应的生效属性是GLITCHTIP_URL（一个 URL 解析对象）。验证生效值时应查 settings 属性而非环境变量本身； - 少数配置在数据库不在环境：组织级设置（告警规则、成员角色）、社会化登录应用（Social Applications）的密钥等存于数据库，经 Web 界面或 API 管理，环境变量只负责实例级默认与开关。
配置项按功能域分为七族，本篇结构与其对应：
| 配置族 | 代表变量 | 本章 |
|---|---|---|
| 核心必配 | SECRET_KEY、DATABASE_URL、GLITCHTIP_DOMAIN | 三 |
| 基础设施 | SERVER_ROLE、VALKEY_URL、PORT、SKIP_INIT | 四 |
| 安全访问 | ALLOWED_HOSTS、CSRF_TRUSTED_ORIGINS、注册与管理开关 | 五 |
| 功能开关 | GLITCHTIP_ENABLE_LOGS / _UPTIME / _MCP / _DUCKDB | 六 |
| 数据保留 | GLITCHTIP_RETENTION_DAYS 及分域保留组 | 七 |
| 邮件与身份源 | EMAIL_URL、EMAIL_*、Social Auth | 八 |
| 存储与调优 | AWS_*、payload 限制、性能项 | 九 |
三、核心必配参数
1. SECRET_KEY — Django 会话与签名密钥。
- 官方默认：无（不设置无法启动）；
- 生成方式：
openssl rand -hex 32（官方建议）； - 实测：编排注入 64 位十六进制串，settings 导出
SECRET_KEY = <64 chars>，实例正常运行。另有配套SECRET_KEY_FALLBACKS（轮换期间的旧密钥列表，默认空）。
2. DATABASE_URL — PostgreSQL 连接串。
- 格式：
postgres://用户:密码@主机:5432/库名（官方要求 PostgreSQL 14+，实测 18）； - 实测生效：
DATABASES['default']引擎为 Django PostgreSQL 后端、主机postgres（服务网络别名解析）； - 分区表特殊要求：数据库侧需
max_locks_per_transaction=512（官方编排通过启动参数提供；使用外部数据库时必须自行调整，这是官方文档唯一指名的数据库调优点）； - Helm/K8s 场景另有
MAINTENANCE_DATABASE_URL、READ_ONLY_DATABASE_URL（分离权限的迁移/只读连接串，官方 chart 支持项）。
3. GLITCHTIP_DOMAIN — 实例对外地址。
- 格式：含协议的完整 URL（如
https://glitchtip.example.com）； - 作用：注册/告警邮件中的链接、项目 DSN 的主机部分（实测生成的 DSN 主机即取自该值）、CSRF 域判断；
- 实测生效：注入
GLITCHTIP_DOMAIN: http://192.168.1.62:8143后，settings 中出现GLITCHTIP_URL = ParseResult(scheme='http', netloc='192.168.1.62:8143', ...)——确认映射关系为GLITCHTIP_DOMAIN（环境变量）→GLITCHTIP_URL（生效属性）。
4. DEFAULT_FROM_EMAIL — 告警/邀请邮件的发件人地址。
- 实测生效：
DEFAULT_FROM_EMAIL = admin@example.com； - 与
EMAIL_URL配合构成邮件最低可用组合；不配邮件时它仍是注册展示的默认来源，建议总是设置。
四、基础设施参数
| 变量 | 默认值 | 说明与实测 |
|---|---|---|
SERVER_ROLE | web | 服务角色：all_in_one（单服务全包）/ web（只接入）/ worker（只后台任务）。实测 all_in_one 模式下事件入库与后台分组正常 |
GLITCHTIP_EMBED_WORKER | False | all_in_one 的等价开关写法，两者取一即可 |
VALKEY_URL | 空 | 队列/缓存/会话地址，redis://host:6379。实测注入 redis://valkey:6379 后 settings 导出 CACHE_IS_VALKEY = True。置空时回退 PostgreSQL 承载队列/缓存（官方低内存建议），代价是上报吞吐 |
SKIP_INIT | False | 跳过启动时的自动迁移与分区维护（K8s 由独立 Job 跑迁移时置 true，Compose 单机保持默认） |
PORT | 8000 | 服务监听端口；编排端口映射的目标端口需与其一致 |
BASE_PATH | 空 | 子路径反代部署（如域名下 /glitchtip/）时设置 |
LOG_LEVEL | WARNING | 服务日志等级，排障时临时调 INFO/DEBUG |
PROXY_ENV | False | 是否信任 HTTP_PROXY/HTTPS_PROXY/NO_PROXY 环境变量（出站请求走代理场景） |
UPTIME_CHECK_INTERVAL | 1 | 拨测调度间隔（分钟） |
五、安全与访问控制参数
网络层防护：
| 变量 | 默认值 | 说明与实测 |
|---|---|---|
ALLOWED_HOSTS | * | HTTP Host 白名单（逗号分隔）。实测未设置时导出 ALLOWED_HOSTS = ['*']，同时启动日志出现「Restrict to known hostnames via the ALLOWED_HOSTS env var」的 RuntimeWarning——生产必须收敛为具体域名 |
CSRF_TRUSTED_ORIGINS | 空 | CSRF 来源白名单。反代域名与 GLITCHTIP_DOMAIN 不一致时必填（实测中纯 IP 直连场景未配也能跑通 API，但上反代换域名后缺失此项会导致登录/表单 403） |
SOCIAL_AUTH_BLOCK_PRIVATE_IPS | False | 禁止社会化登录流程访问内网地址（SSRF 防护） |
GLITCHTIP_ALLOW_PRIVATE_IPS / GLITCHTIP_UPTIME_ALLOW_PRIVATE_IPS | False | 分别放开 webhook 与拨测对内网地址的限制，默认关闭防 SSRF，内网联动场景按需开启 |
后台与 API 开关：
| 变量 | 默认值 | 说明与实测 |
|---|---|---|
ENABLE_ADMIN | False | Django Admin 后台（/admin/）。实测置 True 后导出 ENABLE_ADMIN = True 且后台可登录 |
ENABLE_OPENAPI | False | OpenAPI 文档端点（/api/docs 与 /api/openapi.json）。实测开启后可下载 6.2.6 的全量接口规范（114 条路径） |
ENABLE_USER_REGISTRATION | True | 邮箱自注册开关。实测默认 True；收敛为管理员建号模式时置 False |
ENABLE_SOCIAL_APPS_USER_REGISTRATION | True | 经社会化登录的注册开关（与上项独立） |
ENABLE_ORGANIZATION_CREATION | False | 普通用户自建组织开关。实测默认 False——组织由管理员创建是推荐治理姿势 |
认证细节（settings 实测导出）：登录标识为邮箱（ACCOUNT_LOGIN_METHODS = {'email'}，6.x 用户模型以 email 为唯一标识）；账号邮箱验证策略 ACCOUNT_EMAIL_VERIFICATION = optional；passkey 登录默认开启（MFA_PASSKEY_LOGIN_ENABLED = True）；I_PAID_FOR_GLITCHTIP = False（自托管捐助致谢标记，不解锁任何功能）。
六、功能开关参数
| 变量 | 默认值 | 说明与实测 |
|---|---|---|
GLITCHTIP_ENABLE_LOGS | True | OTLP 日志接入与界面。实测导出 GLITCHTIP_ENABLE_LOGS = True |
GLITCHTIP_ENABLE_UPTIME | True | Uptime 拨测。实测 True；禁用可省后台任务开销 |
GLITCHTIP_ENABLE_MCP | False | 内置 MCP 服务端（供 AI 工具查询错误/监控数据）。实测 False，启用后提供 MCP 端点 |
GLITCHTIP_ENABLE_DUCKDB | False | DuckDB 冷存储归档。实测导出 GLITCHTIP_ENABLE_DUCKDB = None（未显式设置即关闭态），配套生效参数：DUCKDB_MEMORY_LIMIT = 256MB、DUCKDB_THREADS = 4、DUCKDB_TEMP_DIRECTORY = /tmp、DUCKDB_EXTENSION_DIRECTORY = /opt/duckdb/extensions |
ENABLE_OBSERVABILITY_API | False | Prometheus 指标端点（监控 GlitchTip 自身） |
GLITCHTIP_INSTANCE_NAME | 空 | 界面展示的自定义实例名（支持 Markdown），实测 None |
GLITCHTIP_RUST_INGEST | False | Rust 摄入路径开关（6.x 实验特性，导出值 False） |
SENTRY_ENABLE_LOGS | False | SDK 兼容层的日志开关（独立于 GLITCHTIP_ENABLE_LOGS） |
GLITCHTIP_CHUNK_UPLOAD_USE_RELATIVE_URL | False | 分块上传使用相对 URL（特殊反代场景） |
七、数据保留参数
保留体系是「总开关 + 分域覆盖」结构：GLITCHTIP_RETENTION_DAYS（默认 90）为总开关，事件/事务/日志/拨测/文件/release 各域可单独覆盖，事件在 PostgreSQL 的热存天数另由 GLITCHTIP_EVENT_HOT_DAYS 控制（到期转入冷存档）。实测生效值全景：
| 变量 | 官方默认 | 实测生效值 | 说明 |
|---|---|---|---|
GLITCHTIP_RETENTION_DAYS | 90 | 90 | 保留总开关 |
GLITCHTIP_EVENT_HOT_DAYS | 30 | 30 | 事件热存（PostgreSQL）天数 |
GLITCHTIP_EVENT_RETENTION_DAYS | =总开关 | 90 | 事件保留（热+冷） |
GLITCHTIP_TRANSACTION_RETENTION_DAYS | =总开关 | 90 | 事务（性能监控）保留 |
GLITCHTIP_LOG_RETENTION_DAYS | =总开关 | 90 | 日志保留 |
GLITCHTIP_LOG_HOT_DAYS | 7 | 7 | 日志热存天数（比事件更短） |
GLITCHTIP_UPTIME_RETENTION_DAYS | =总开关 | 90 | 拨测数据保留 |
GLITCHTIP_SPAN_RAW_RETENTION_DAYS | 30 | 30 | 原始 span 数据保留 |
GLITCHTIP_RELEASE_RETENTION_DAYS | 365 | 365 | release 元数据保留 |
GLITCHTIP_FILE_RETENTION_DAYS | 90 | 90 | 上传文件（sourcemap 等）保留 |
配套清理行为：GLITCHTIP_COLD_STORAGE_CLEANUP_ENABLED = True（冷存档过期自动清理）；GLITCHTIP_COLD_STORAGE_DIR / GLITCHTIP_COLD_STORAGE_BUCKET（冷存档落本地目录或 S3 兼容桶，默认 None 即未启用）。
💡 技术拓展：热/冷分层与分区表的关系——事件按时间分区写入 PostgreSQL，超过
GLITCHTIP_EVENT_HOT_DAYS的分区数据转入冷存储后从热表清理，周分区维护任务在启动与运行期自动执行（部署篇日志可见「Maintaining weekly partitions」）。只配总开关不配分域时，各域一律 90 天；要让日志只留 14 天，仅需追加GLITCHTIP_LOG_RETENTION_DAYS: "14"一行。
八、邮件与身份源参数
*邮件（EMAIL_ 全组，实测生效）**：
| 变量 | 默认值 | 说明与实测 |
|---|---|---|
EMAIL_URL | 空 | 连接串总入口。实测 consolemail:// → 导出 EMAIL_BACKEND = django.core.mail.backends.console.EmailBackend（邮件打到日志），印证映射链路 |
EMAIL_HOST / EMAIL_PORT / EMAIL_HOST_USER / EMAIL_HOST_PASSWORD | None | SMTP 分项写法（与 EMAIL_URL 二选一） |
EMAIL_USE_TLS / EMAIL_USE_SSL | False | SMTP 加密开关（587 端口一般 TLS、465 一般 SSL） |
EMAIL_TIMEOUT | None | SMTP 超时秒数 |
EMAIL_FILE_PATH | 空 | filemail:// 落盘模式的目标目录 |
EMAIL_ENABLED | True | 邮件功能总开关（导出值 True） |
EMAIL_SUBJECT_PREFIX | [Django] | 邮件主题前缀 |
EMAIL_INVITE_REQUIRE_VERIFICATION | False | 受邀成员需邮箱验证 |
EMAIL_INVITE_THROTTLE_COUNT / _INTERVAL | 50 / 300 | 邀请邮件限流（次数/秒窗） |
SMTP 生产配法示例（URL 中特殊字符需百分号编码）：EMAIL_URL: smtp://alert%40example.com:AppPassword@smtp.example.com:587。
社会化登录与 SSO：GlitchTip 的 Social Auth 体系支持 GitHub、GitLab、Google、Azure AD、OIDC、SAML 等身份源。配置采取「后台为主、环境变量为辅」：提供方应用（client_id/client_secret）在 Django Admin 的 Social Applications 中录入（数据库存储）；环境变量用于实例级引导（如 SOCIAL_AUTH_GITLAB_KEY/SOCIAL_AUTH_GITLAB_SECRET 等官方文档列出的键值写法）。实测 6.2.6 settings 导出中直接可见的仅有 SOCIAL_AUTH_BLOCK_PRIVATE_IPS，其余提供方配置经 social_django 模型机制加载——因此升级或迁移实例时，SSO 配置随数据库走，无需在环境变量中重复维护。另外注意访问内网 IdP 时需同步放开 SOCIAL_AUTH_BLOCK_PRIVATE_IPS。
九、存储与调优参数
对象存储（上传文件，S3 兼容）：
| 变量 | 默认值 | 说明 |
|---|---|---|
AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY | None | S3 兼容存储凭据（实测导出 SECRET 为 None 即未启用，默认落本地 uploads 卷） |
AWS_STORAGE_BUCKET_NAME | — | 目标桶名 |
AWS_S3_ENDPOINT_URL | — | 自建 S3（MinIO 等）的 endpoint |
AWS_S3_REGION_NAME | — | 区域（部分实现必需） |
事件量大的实例建议把 sourcemap/调试符号文件外移对象存储，本地卷只留数据库。
上传与解析限额（实测导出值）：
| 变量 | 实测值 | 说明 |
|---|---|---|
GLITCHTIP_MAX_UNZIPPED_PAYLOAD_SIZE | 5242880（5 MB） | 单事件载荷解压上限 |
GLITCHTIP_MAX_UNZIPPED_ARCHIVE_SIZE | 536870912（512 MB） | 压缩包（sourcemap 包）解压上限 |
GLITCHTIP_MAX_ARCHIVE_MEMBERS | 10000 | 压缩包内文件数上限 |
性能与调度（实测导出值）：
| 变量 | 实测值 | 说明 |
|---|---|---|
GLITCHTIP_MALLOC_TRIM_INTERVAL | 3600 | glibc malloc trim 周期（秒），控制长驻内存回收 |
GLITCHTIP_THROTTLE_CHECK_INTERVAL | 5000 | 限流检查间隔（毫秒） |
GLITCHTIP_TRANSACTION_FUTURE_SKEW | 1 小时 | 事务时间戳的未来偏移容忍 |
GLITCHTIP_PII_SCRUB_DEFAULT | {} | 默认 PII 洗刷规则（空即不洗刷） |
托管版计费参数（自托管无效应，仅识别用）：GLITCHTIP_FREE_TIER_EVENTS = 1000、GLITCHTIP_LICENSE_KEY = None、GLITCHTIP_OVERAGE_TIERS（超额阶梯单价）——这些是 SaaS 运营参数，自托管实例保持默认即可。
十、配置生效方式与验证
修改与生效流程（Compose 场景）：
- 编辑
/opt/glitchtip/compose.yml的 environment 段； docker compose up -d（配置变化会触发 web/postgres 实例重建）；- 验证注入：
docker exec glitchtip-6.2.6-web env | grep GLITCHTIP（环境层）； - 验证生效：
./manage.py shell导出对应 settings 属性（应用层，注意变量名→属性名的映射，如 GLITCHTIP_DOMAIN→GLITCHTIP_URL）。
两类常见配置错误（实测来源）：
- 变量名拼错静默失效：Django 对未知环境变量不报错，settings 中查无该属性即为拼错或未生效；
- 只改环境未重启：
docker compose restart不会应用新的 environment（restart 不重建实例定义），必须docker compose up -d。
十一、参考链接
- 官方安装文档·环境变量清单：https://glitchtip.com/documentation/install
- 官方 compose 样例（变量默认口径）：https://glitchtip.com/assets/compose.sample.yml
- GitLab 主仓库：https://gitlab.com/glitchtip/glitchtip
- 部署实测（本篇参数的验证环境）：同专栏《GlitchTip 6.2.6 Docker Compose 部署实战》
- CLI 与运维（参数相关的管理命令）：同专栏《GlitchTip 6.2.6 常用 CLI 命令与运维实战》
- 项目定位与选型（同专栏）：《GlitchTip 介绍与选型指南》