GlitchTip Docker Compose 部署实战

目标：在一台 Ubuntu 22.04 服务器上，用官方 Docker Compose 编排从 0 到 1 部署 GlitchTip 6.2.6 错误追踪平台：PostgreSQL 18 + Valkey 9 + GlitchTip 三服务编排、初始化管理员、创建组织/团队/项目、生成 DSN 并用 Sentry SDK（Python 2.73.0）发送真实错误事件，最终在 Issues 聚合页验证闭环。全部命令与回显均来自 2026-10-27 真实部署实测。

一、环境信息

本次部署实测的服务器与环境信息如下（命令均在该服务器上执行）：

操作系统：Ubuntu 22.04 LTS（x86_64）
Docker：Docker Compose v5.6.1（docker compose v2 插件语法）
GlitchTip：6.2.6（官方 Docker Hub 仓库 glitchtip/glitchtip，2026-10-27 查询为最新稳定版）
PostgreSQL：18（官方编排推荐版本）
Valkey：9（兼容 Redis 协议，承担任务队列与缓存）
Sentry Python SDK：sentry-sdk 2.73.0（用于发送验证事件）
宿主端口规划：8143 → GlitchTip web 8000
部署目录：/opt/glitchtip/（compose 项目目录）
网络与命名：编排项目名 glitchtip-6.2.6-stack，服务网络 glitchtip-6.2.6-net（10.89.69.0/24）

💡 说明：多台服务器共用 Docker 宿主时，自定义网络子网与宿主端口必须先查后占——本次实测中 10.89.67.0/24 与 8139 端口先后被同宿主其他编排占用，最终改用 10.89.69.0/24 与 8143（排障过程见第十章 FAQ）。

二、镜像选型说明

GlitchTip 官方在 Docker Hub 发布 glitchtip/glitchtip 仓库，tag 策略与选型依据（2026-10-27 实查 Docker Hub tags）：

tag	含义	适用建议
`6.2.6`	精确版本（2026-08-08 推送，当前 latest 指向）	生产固定版本，升级可控
`6`	6.x 大版本浮动 tag	官方编排样例默认；随小版本自动更新
`latest`	最新稳定版浮动 tag	试用环境，不建议生产
`6.2.6-amd64` / `6.2.6-arm64`	单架构精确 tag	有锁定架构诉求时使用

配套数据组件的版本由官方编排样例（compose.sample.yml，取自 glitchtip.com/assets，2026-10-27）直接给定：postgres:18 与 valkey/valkey:9。两点官方编排中的硬性要求必须在自建编排中保留：

PostgreSQL 需带启动参数 max_locks_per_transaction=512——GlitchTip 的事件分区表维护需要超出默认锁额度；
GlitchTip 服务通过 SERVER_ROLE: all_in_one 以单服务形态同时承担 Web 接入与后台任务（可拆分为 web/worker 双服务，见第八章）。

⚠️ 注意：官方样例为演示便捷使用了 POSTGRES_HOST_AUTH_METHOD: "trust"（无密码直连）。生产部署必须改为主密认证（本篇实测采用 POSTGRES_USER/POSTGRES_PASSWORD 方式），参见第四章。

三、前置条件

部署前确认服务器具备以下条件，逐项验证：

1. Docker 与 Compose 插件可用：

docker --version && docker compose version

实测回显：

Docker version 28.5.2, build 2dff8c0
Docker Compose version v5.6.1

2. 端口未被占用（本篇规划 8143；以实际探测结果为准）：

ss -ltn | grep 8143 || echo "8143 free"

实测回显：

8143 free

3. 自定义网络子网未被占用（多编排共存的服务器上必查）：

docker network ls --format '{{.Name}}'
for n in $(docker network ls --format '{{.Name}}'); do docker network inspect $n --format '{{.Name}}: {{range .IPAM.Config}}{{.Subnet}}{{end}}'; done 2>/dev/null

实测回显（节选）：

audiobookshelf-2.37.2-net: 10.89.60.0/24
bugzilla-5.2-net: 10.89.63.0/24
...

确认所选子网（本篇 10.89.69.0/24）不在输出列表中即可。

4. 磁盘余量：PostgreSQL 事件数据按官方粗估「每月 100 万事件约 30 GB」预留，实测起栈前检查：

df -h /opt

实测回显：

Filesystem      Size  Used Avail Use% Mounted on
/dev/vda1        98G   47G   47G  49% /opt

四、部署步骤

4.1 创建编排文件

创建项目目录并写入 compose.yml（在官方 compose.sample.yml 基础上做了三处生产化改造：数据库改主密认证、显式编排项目名与网络子网、开启 Django Admin 与 OpenAPI）：

mkdir -p /opt/glitchtip && cd /opt/glitchtip

name: glitchtip-6.2.6-stack

x-environment: &default-environment
  DATABASE_URL: postgres://glitchtip:q1w2e3r4@postgres:5432/glitchtip
  VALKEY_URL: redis://valkey:6379
  SECRET_KEY: 5f8db977c4ba2fd1e3a60c72d8ef41a9b06c25d3e7f84a2c9b1d0e6f3a5c8d27
  EMAIL_URL: consolemail://
  GLITCHTIP_DOMAIN: http://192.168.1.62:8143
  DEFAULT_FROM_EMAIL: admin@example.com
  ENABLE_ADMIN: "True"
  ENABLE_OPENAPI: "True"

services:
  postgres:
    image: postgres:18
    container_name: glitchtip-6.2.6-postgres
    command: -c max_locks_per_transaction=512
    environment:
      POSTGRES_DB: glitchtip
      POSTGRES_USER: glitchtip
      POSTGRES_PASSWORD: q1w2e3r4
    restart: unless-stopped
    volumes:
      - pg-data:/var/lib/postgresql
    networks:
      - glitchtip-net

  valkey:
    image: valkey/valkey:9
    container_name: glitchtip-6.2.6-valkey
    restart: unless-stopped
    networks:
      - glitchtip-net

  web:
    image: glitchtip/glitchtip:6.2.6
    container_name: glitchtip-6.2.6-web
    depends_on:
      - postgres
      - valkey
    ports:
      - "8143:8000"
    environment:
      <<: *default-environment
      SERVER_ROLE: all_in_one
    restart: unless-stopped
    volumes:
      - uploads:/code/uploads
    networks:
      - glitchtip-net

volumes:
  pg-data:
  uploads:

networks:
  glitchtip-net:
    name: glitchtip-6.2.6-net
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.69.0/24

配置要点逐项说明：

x-environment 锚点：三服务共享的环境变量集中定义，web 服务以 <<: *default-environment 合并注入，避免重复；
DATABASE_URL：PostgreSQL 连接串，账号 glitchtip、密码 q1w2e3r4，与下方 POSTGRES_* 三项保持一致；SECRET_KEY 官方建议用 openssl rand -hex 32 生成，此处为实测所用值，生产请重新生成；
EMAIL_URL: consolemail://：开发验证阶段把告警邮件输出到日志；生产替换为 smtp://用户:密码@smtp主机:端口（密码中的特殊字符需 URL 编码）；
GLITCHTIP_DOMAIN：实例对外访问地址（含协议），决定注册邮件中的链接与生成的 DSN 中事件上报地址；
ENABLE_ADMIN/ENABLE_OPENAPI：分别打开 Django Admin 后台（/admin/）与 OpenAPI 文档（/api/docs、/api/openapi.json）；
pg-data 卷：官方样例挂载到 /var/lib/postgresql（注意 PG18 官方编排不写到 /var/lib/postgresql/data 子路径，按官方写法即可）。

4.2 拉取镜像并启动

cd /opt/glitchtip && docker compose pull && docker compose up -d

实测回显（首启，网络与卷创建、三服务依序启动）：

[+] Running 5/5
 ✔ Network glitchtip-6.2.6-net   Created
 ✔ Volume "glitchtip-626-stack_pg-data"   Created
 ✔ Volume "glitchtip-626-stack_uploads"   Created
 ✔ Container glitchtip-6.2.6-postgres  Started
 ✔ Container glitchtip-6.2.6-valkey    Started
 ✔ Container glitchtip-6.2.6-web       Started

web 服务启动时自动执行数据库迁移，无需手工迁移。观察迁移日志（实测节选，全量迁移数十条）：

docker logs -f glitchtip-6.2.6-web

实测回显（节选）：

  Applying issue_events.0017_drop_issue_id_fk_on_partitioned_tables... OK
  Applying issue_events.0018_issue_assignment... OK
  Applying issue_events.0020_backfill_and_drop_search_gin... OK
  Applying logs.0001_initial...Created partitions for logs_logevent from 2026-10-27 00:00:00+00:00 to 2026-11-03 00:00:00+00:00
 OK
  Applying mfa.0001_initial... OK
  ...
Maintaining weekly partitions for projects_logprojecthourlystatistic...
Cleaning up old weekly partitions for projects_logprojecthourlystatistic...
Maintaining weekly partitions for uptime_uptimecheckhourlystatistic...
Partition maintenance complete.

迁移完成后每次启动还会自动执行分区维护（周分区创建与过期分区清理），这是事件表按时间分区的例行任务。

验证服务就绪：

docker compose ps
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8143/

实测回显：

NAME                    STATUS
glitchtip-6.2.6-web     Up
glitchtip-6.2.6-postgres  Up
glitchtip-6.2.6-valkey  Up
200

4.3 初始化管理员账号

GlitchTip 的注册接口受 Django CSRF 保护，纯命令行部署推荐用管理命令创建超级管理员（也是 /admin/ 后台登录账号）。注意 6.x 的用户模型以 email 为唯一标识（已无 username 字段），--noinput 模式通过环境变量传入：

docker exec -e DJANGO_SUPERUSER_USERNAME=admin \
  -e DJANGO_SUPERUSER_EMAIL=admin@example.com \
  -e DJANGO_SUPERUSER_PASSWORD=q1w2e3r4 \
  glitchtip-6.2.6-web ./manage.py createsuperuser --noinput

实测回显：

/usr/local/lib/python3.14/importlib/__init__.py:88: RuntimeWarning: ALLOWED_HOSTS is the wildcard default. Restrict to known hostnames via the ALLOWED_HOSTS env var (comma-separated) in production deployments.
  return _bootstrap._gcd_import(name[level:], package, level)
Superuser created successfully.

首行的 RuntimeWarning 是因为 ALLOWED_HOSTS 未设置时默认 *，生产建议在编排中补 ALLOWED_HOSTS: "glitchtip.example.com"（见第十章 FAQ）。

验证账号已建（列用户清单）：

docker exec glitchtip-6.2.6-web ./manage.py shell -c "
from apps.users.models import User
for u in User.objects.all():
    print('email:', u.email, '| superuser:', u.is_superuser, '| active:', u.is_active)
"

实测回显：

email: admin@example.com | superuser: True | active: True

此时浏览器打开 http://192.168.1.62:8143/，用 admin@example.com / q1w2e3r4 登录即是平台管理员；http://192.168.1.62:8143/admin/ 为 Django Admin 后台。

4.4 为命令行操作签发 API Token

6.2.6 的 API 走 django-ninja，个人 API Token 模型为 APIToken（Sentry 风格 scope 位串）。命令行管理场景用管理命令直接签发一枚全权限 Token 并保存（后续所有 API 调用带 Authorization: Bearer <token>）：

docker exec glitchtip-6.2.6-web ./manage.py shell -c "
from apps.api_tokens.models import APIToken
from apps.users.models import User
u = User.objects.get(email='admin@example.com')
t = APIToken.objects.create(user=u, label='cli-admin')
for p in ['project:read','project:write','project:admin','team:read','team:write','team:admin','event:read','event:write','event:admin','org:read','org:write','org:admin','member:read','member:write','member:admin']:
    t.add_permission(p)
print(t.token)
"

实测回显（token 已脱敏展示，实测为 64 位字符串）：

394dbbdfec23...(64 位)

验证认证可用（列出组织，应返回空数组与 200）：

TOKEN=394dbbdfec23...   # 替换为上一步输出值
curl -s http://localhost:8143/api/0/organizations/ -H "Authorization: Bearer $TOKEN" -w '\nHTTP %{http_code}\n'

实测回显：

[]
HTTP 200

4.5 创建组织、团队与项目

GlitchTip 的资源层级是组织（Organization）→ 团队（Team）→ 项目（Project），且项目必须创建在团队路由下（组织路由下仅支持查询，直接对组织建项目会得到 405，排障见第十章 FAQ）。逐步执行：

创建组织：

curl -s -X POST http://localhost:8143/api/0/organizations/ \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"name":"Demo Org","slug":"demo-org"}' -w '\nHTTP %{http_code}\n'

实测回显（节选）：

{"name": "Demo Org", "id": "1", "dateCreated": "2026-10-27T13:06:36.707Z", "status": {"id": "active", "name": "active"}, "slug": "demo-org", "isAcceptingEvents": true, "access": ["org:integrations", "member:write", "team:read", "event:write", "event:read", "member:read", "project:write", "event:admin", "team:write", "project:read", "org:write", "member:admin", "project:admin", "project:releases", "org:admin", "team:admin", "org:read"], "openMembership": true}
HTTP 201

创建团队：

curl -s -X POST http://localhost:8143/api/0/organizations/demo-org/teams/ \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"name":"Platform Team","slug":"platform"}' -w '\nHTTP %{http_code}\n'

实测回显：

{"id": "1", "slug": "platform", "dateCreated": "2026-10-27T13:07:32.758Z", "isMember": true, "memberCount": 1, "projects": []}
HTTP 201

创建项目（注意路由在团队下）：

curl -s -X POST http://localhost:8143/api/0/teams/demo-org/platform/projects/ \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"name":"demo-app","platform":"python"}' -w '\nHTTP %{http_code}\n'

实测回显（节选）：

{"name": "demo-app", "slug": "demo-app", "id": "1", "platform": "python", "firstEvent": null, "eventThrottleRate": 0, "isMember": true, "hasAccess": true}
HTTP 201

4.6 获取 DSN 并接入 SDK

获取项目 DSN（事件上报地址）：

curl -s http://localhost:8143/api/0/projects/demo-org/demo-app/keys/ -H "Authorization: Bearer $TOKEN" | python3 -m json.tool

实测回显：

[
    {
        "name": "",
        "rateLimit": null,
        "dateCreated": "2026-10-27T13:07:32.838Z",
        "id": "c922bf01-7d78-4d37-8f25-cbeafc314fd6",
        "dsn": {
            "public": "http://c922bf017d784d378f25cbeafc314fd6@192.168.1.62:8143/1",
            "secret": "http://c922bf017d784d378f25cbeafc314fd6@192.168.1.62:8143/1",
            "security": "http://192.168.1.62:8143/api/1/security/?glitchtip_key=c922bf017d784d378f25cbeafc314fd6"
        },
        "label": "",
        "public": "c922bf01-7d78-4d37-8f25-cbeafc314fd6",
        "projectID": 1
    }
]

DSN 结构为 协议://公钥@主机:端口/项目ID，主机部分取自 GLITCHTIP_DOMAIN。应用侧使用的前提是「该地址从应用运行环境可达」——应用与平台同机时建议改写为 localhost，跨机时用服务器内网/公网地址。

应用侧接入（Python SDK 实测）。安装 SDK 后仅需三行初始化：

python3 -m venv /opt/glitchtip/sdk-venv
/opt/glitchtip/sdk-venv/bin/pip install sentry-sdk

实测回显（安装完成后验证版本）：

/opt/glitchtip/sdk-venv/bin/python -c "import sentry_sdk; print('sentry-sdk', sentry_sdk.VERSION)"

sentry-sdk 2.73.0

发送验证事件的脚本 /opt/glitchtip/send_event.py：

import sentry_sdk

DSN = "http://c922bf017d784d378f25cbeafc314fd6@localhost:8143/1"

sentry_sdk.init(
    dsn=DSN,
    release="demo-app@1.0.0",
    environment="production",
)

def risky_divide(a, b):
    return a / b

for i in range(2):
    try:
        risky_divide(7, 0)
    except ZeroDivisionError as e:
        sentry_sdk.capture_exception(e)

sentry_sdk.capture_message("Demo: payment gateway timeout", level="error")
sentry_sdk.flush(timeout=15)
print("events sent")

执行：

/opt/glitchtip/sdk-venv/bin/python /opt/glitchtip/send_event.py

实测回显：

events sent
Sentry is attempting to send 3 pending events
Waiting up to 2 seconds
Press Ctrl-C to quit

4.7 验证错误聚合闭环

等待数秒（事件入库与指纹分组在后台完成），查询 Issues 聚合列表：

curl -s 'http://localhost:8143/api/0/organizations/demo-org/issues/?project=1&query=' \
  -H "Authorization: Bearer $TOKEN" | python3 -m json.tool

实测回显（节选关键字段）：

[
    {
        "title": "ZeroDivisionError: division by zero",
        "level": "error",
        "type": "error",
        "status": "unresolved",
        "count": "3",
        "firstSeen": "2026-10-27T13:12:50.716000Z"
    },
    {
        "title": "Demo: payment gateway timeout",
        "level": "error",
        "type": "default",
        "status": "unresolved",
        "count": "1"
    }
]

闭环验证结论（实测）：同一函数栈帧触发的 3 次 ZeroDivisionError 被聚合为 1 个 Issue、3 个事件；capture_message 的 message 事件独立成条。浏览器打开 http://192.168.1.62:8143/organizations/demo-org/issues/ 可见同样的聚合列表与事件详情（堆栈、面包屑、release、environment）。至此「部署 → 建号 → 建项目 → DSN → SDK 上报 → 聚合呈现」全链路打通。

💡 技术拓展：错误聚合（grouping）的指纹策略不止一种。Sentry 系 SDK/平台常见的分组依据对比——异常类型 + 栈顶帧（默认，同类同位置的异常归并）、自定义 fingerprint（SDK 侧 scope.fingerprint 手工指定，如按业务实体聚合）、堆栈全帧哈希（更严格，同一异常不同调用路径会拆分）。GlitchTip 采用与 Sentry 一致的默认策略：本实测中「模块级 1/0」与「risky_divide 函数内除零」虽同为 ZeroDivisionError 却分成两个 Issue，即栈帧差异所致；重复抛出的同一函数异常则合并计数。接入方如需按业务维度聚合，可在 SDK 侧设置 fingerprint。

五、数据持久化说明

数据	落点	说明
事件与平台数据	卷 `pg-data` → `/var/lib/postgresql`	全部业务数据都在 PostgreSQL，备份即备份此卷
上传文件	卷 `uploads` → `/code/uploads`	sourcemap、调试符号文件等；量大或集群化时建议改 S3 兼容对象存储（`AWS_*` 环境变量）
Valkey 数据	不持久化	只承担队列/缓存/会话，重启丢失无影响

数据卷由编排创建（glitchtip-626-stack_pg-data / glitchtip-626-stack_uploads，命名带编排项目名前缀）。验证与备份示例：

docker volume ls | grep glitchtip

实测回显：

local     glitchtip-626-stack_pg-data
local     glitchtip-626-stack_uploads

docker exec glitchtip-6.2.6-postgres pg_dump -U glitchtip -d glitchtip | gzip > /opt/glitchtip/backup-$(date +%F).sql.gz

实测回显（执行后核对文件）：

ls -lh /opt/glitchtip/backup-*.sql.gz

-rw-r--r-- 1 root root 108K Oct 27 21:20 /opt/glitchtip/backup-2026-10-27.sql.gz

恢复场景：以空数据卷重建 postgres 服务后 gunzip -c backup-xxx.sql.gz | docker exec -i glitchtip-6.2.6-postgres psql -U glitchtip -d glitchtip。

六、环境变量表

GlitchTip 6.2.6 全量环境变量以官方安装文档为准（2026-10-27 查询），按必需/常用/高级分组列出，默认值均为官方文档口径：

必需项：

变量	默认值	说明
`SECRET_KEY`	无（必填）	Django 会话签名密钥，`openssl rand -hex 32` 生成
`DATABASE_URL`	无（必填）	PostgreSQL 连接串，支持 14+；形如 `postgres://user:pass@host:5432/db`
`GLITCHTIP_DOMAIN`	无（必填）	实例对外地址含协议，影响邮件链接与 DSN 生成
`DEFAULT_FROM_EMAIL`	无（生产必填）	告警邮件发件人
`EMAIL_URL`	无	SMTP 连接串 `smtp://user:pass@host:port`；无邮件需求可 `consolemail://` 输出到日志

服务角色与基础设施：

变量	默认值	说明
`SERVER_ROLE`	`web`	`all_in_one` 全合一 / `web` 仅接入 / `worker` 仅后台任务
`VALKEY_URL`	空	`redis://host:6379`；置空则队列/缓存/会话回退 PostgreSQL
`GLITCHTIP_EMBED_WORKER`	`False`	等价 `SERVER_ROLE=all_in_one` 的开关形式
`SKIP_INIT`	`False`	跳过启动时自动迁移与分区维护（K8s migrationJob 场景用）
`PORT`	`8000`	监听端口，与编排端口映射保持一致
`BASE_PATH`	空	子路径部署（如 `/glitchtip`）时设置
`LOG_LEVEL`	`WARNING`	排障时可调 `INFO`/`DEBUG`

安全与访问控制：

变量	默认值	说明
`ALLOWED_HOSTS`	`*`	逗号分隔主机名白名单，生产必须收敛
`CSRF_TRUSTED_ORIGINS`	空	反代域名与实例域名不一致时必填，如 `https://glitchtip.example.com`
`ENABLE_ADMIN`	`False`	Django Admin 后台（`/admin/`）开关
`ENABLE_OPENAPI`	`False`	OpenAPI 文档（`/api/docs`）开关
`ENABLE_USER_REGISTRATION`	`True`	自注册开关；`False` 时首用户之后仅管理员建号
`ENABLE_SOCIAL_APPS_USER_REGISTRATION`	同上	社会化登录注册开关
`ENABLE_ORGANIZATION_CREATION`	`False`	普通用户能否自建组织
`PROXY_ENV`	`False`	是否信任 `HTTP_PROXY`/`HTTPS_PROXY`/`NO_PROXY`

功能开关（6.x 新增能力）：

变量	默认值	说明
`GLITCHTIP_ENABLE_LOGS`	`True`	OTLP 日志接入与界面
`GLITCHTIP_ENABLE_UPTIME`	`True`	Uptime 拨测功能
`GLITCHTIP_UPTIME_ALLOW_PRIVATE_IPS`	`False`	允许拨测内网地址（默认关闭防 SSRF）
`GLITCHTIP_ENABLE_MCP`	`False`	内置 MCP 服务端（AI 辅助排障）
`GLITCHTIP_ENABLE_DUCKDB`	`False`	DuckDB 冷存储归档
`ENABLE_OBSERVABILITY_API`	`False`	Prometheus 指标端点
`GLITCHTIP_INSTANCE_NAME`	空	界面实例名（支持 Markdown）

数据保留：

变量	默认值	说明
`GLITCHTIP_RETENTION_DAYS`	`90`	保留天数总开关
`GLITCHTIP_EVENT_HOT_DAYS`	`30`	事件在 PostgreSQL 热存天数，之后归档
`GLITCHTIP_EVENT_RETENTION_DAYS`	同总开关	事件保留（热+冷）
`GLITCHTIP_TRANSACTION_RETENTION_DAYS`	同总开关	事务（性能监控）保留
`GLITCHTIP_LOG_RETENTION_DAYS`	同总开关	日志保留

表格解读：最小可跑集合是 SECRET_KEY + DATABASE_URL（Valkey 可省、邮件可 consolemail）；对外域名部署再加 GLITCHTIP_DOMAIN + CSRF_TRUSTED_ORIGINS + ALLOWED_HOSTS 三件套；单机 512 MB 以内的资源受限场景优先关 GLITCHTIP_ENABLE_LOGS、GLITCHTIP_ENABLE_UPTIME 并置空 VALKEY_URL（官方样例注释同款建议）。

七、配置文件挂载说明

GlitchTip 与传统 nginx/MySQL 类服务不同：它没有主配置文件，全部配置经环境变量注入（完整清单见第六章与《GlitchTip 6.2.6 配置参数详解》），因此编排中无需挂载配置文件。需要关注的数据类挂载只有两处（均为官方样例自带）：

pg-data 卷 → postgres 服务 /var/lib/postgresql：数据库文件；
uploads 卷 → web 服务 /code/uploads：sourcemap/调试符号等上传文件。

若需为 PostgreSQL 追加自定义调优参数，直接扩展 command 行（已带官方要求的 max_locks_per_transaction=512），例如：

    command: -c max_locks_per_transaction=512 -c shared_buffers=256MB

八、等价 docker run 部署方式

不使用 Compose 时，可用 docker run 逐条等价启动（与第四章编排逐项对应）。关键差异在于：Compose 会自动把服务名注册为网络别名，docker run 必须显式加 --network-alias，否则 web 解析 postgres/valkey 主机名失败（实测排障过程见 Q8）。三条启动命令：

docker network create --subnet 10.89.69.0/24 glitchtip-6.2.6-net

docker run -d --name glitchtip-6.2.6-postgres \
  --network glitchtip-6.2.6-net --network-alias postgres \
  -e POSTGRES_DB=glitchtip -e POSTGRES_USER=glitchtip -e POSTGRES_PASSWORD=q1w2e3r4 \
  -v glitchtip-626-stack_pg-data:/var/lib/postgresql \
  --restart unless-stopped \
  postgres:18 -c max_locks_per_transaction=512

docker run -d --name glitchtip-6.2.6-valkey \
  --network glitchtip-6.2.6-net --network-alias valkey \
  --restart unless-stopped \
  valkey/valkey:9

docker run -d --name glitchtip-6.2.6-web \
  --network glitchtip-6.2.6-net \
  -p 8143:8000 \
  -e DATABASE_URL=postgres://glitchtip:q1w2e3r4@postgres:5432/glitchtip \
  -e VALKEY_URL=redis://valkey:6379 \
  -e SECRET_KEY=5f8db977c4ba2fd1e3a60c72d8ef41a9b06c25d3e7f84a2c9b1d0e6f3a5c8d27 \
  -e EMAIL_URL=consolemail:// \
  -e GLITCHTIP_DOMAIN=http://192.168.1.62:8143 \
  -e DEFAULT_FROM_EMAIL=admin@example.com \
  -e ENABLE_ADMIN=True -e ENABLE_OPENAPI=True \
  -e SERVER_ROLE=all_in_one \
  -v glitchtip-626-stack_uploads:/code/uploads \
  --restart unless-stopped \
  glitchtip/glitchtip:6.2.6

实测回显（三服务启动后验证）：

curl -s -o /dev/null -w 'HTTP %{http_code}\n' http://localhost:8143/
docker ps --format '{{.Names}}  {{.Status}}' | grep glitchtip

HTTP 200
glitchtip-6.2.6-web  Up 13 seconds
glitchtip-6.2.6-valkey  Up 13 seconds
glitchtip-6.2.6-postgres  Up 13 seconds

两条路径共用同一组数据卷，可互相接管：实测中先用 Compose 起栈写入组织数据，down 后改用 docker run 以同名卷启动，GET /api/0/organizations/ 仍返回原有 Demo Org——持久化与双路径兼容同时得到验证。生产日常管理仍推荐 Compose（环境变量锚点复用、依赖顺序与迁移自动化由官方样例保证）。

九、常用运维命令

日常运维的 compose 命令矩阵（均在 /opt/glitchtip/ 目录执行）：

状态与日志：

docker compose ps

实测回显：

NAME                    STATUS
glitchtip-6.2.6-web     Up
glitchtip-6.2.6-postgres  Up
glitchtip-6.2.6-valkey  Up

docker compose logs -f web        # 跟踪 web 日志（上报/迁移/告警邮件输出）
docker compose logs --tail 100 web  # 最近 100 行

重启与更新：

docker compose restart web   # 仅重启 web（配置变更后）

实测回显：

[+] Restarting 1/1
 ✔ Container glitchtip-6.2.6-web  Started

重启后验证（实测 HTTP 200）：

curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8143/

docker compose pull && docker compose stop && docker compose up -d   # 官方升级三步

单服务操作与数据操作：

docker stop glitchtip-6.2.6-valkey && docker start glitchtip-6.2.6-valkey   # 单服务维护
docker exec glitchtip-6.2.6-web ./manage.py <管理命令>                       # 进入管理命令（见[《GlitchTip 6.2.6 常用 CLI 命令与运维实战》](https://www.quzuo.net/document/VlSITyRAMb2K)）
docker exec glitchtip-6.2.6-postgres pg_dump -U glitchtip -d glitchtip > backup.sql   # 逻辑备份

停栈（保数据）与彻底清理：

docker compose down              # 停栈并删网络/实例，保留数据卷
docker compose down -v           # ⚠️ 连同数据卷一并删除（含全部事件数据），仅测试环境使用

实测回显（docker compose down，可见卷被保留）：

 Container glitchtip-6.2.6-web  Removed
 Container glitchtip-6.2.6-valkey  Removed
 Container glitchtip-6.2.6-postgres  Removed
 Network glitchtip-6.2.6-net  Removed

docker volume ls | grep glitchtip

local     glitchtip-626-stack_pg-data
local     glitchtip-626-stack_uploads

十、常见问题（FAQ）

以下均为本次实测过程中真实发生并解决的问题（Q8 为 docker run 等价部署新增实测项）：

Q1：docker compose up 报 invalid pool request: Pool overlaps with other one on this address space？

现象与定位：创建网络时失败。同宿主上其他编排已占用所选子网（实测中 10.89.67.0/24 被另一编排占用）。解决：

for n in $(docker network ls --format '{{.Name}}'); do docker network inspect $n --format '{{range .IPAM.Config}}{{.Subnet}}{{end}}'; done 2>/dev/null | sort -u

换一个未被列出的子网（如 10.89.69.0/24）写入 compose.yml 的 ipam.config 后重新 docker compose up -d。

Q2：web 启动报 Bind for 0.0.0.0:8143 failed: port is already allocated？

宿主端口已被其他服务占用（实测中 8139 被占后换 8143，随后 8143 也曾被占）。排查与解决：

ss -ltn | grep -E ':(8139|8143)\s'
docker ps --format '{{.Names}} {{.Ports}}'

修改 compose.yml 端口映射为未占用端口，同时同步修改 GLITCHTIP_DOMAIN（否则 DSN 与邮件链接中的端口与实际不符）。

Q3：curl -X POST http://…:8143/auth/users/（注册）与 /auth/token/login/ 均返回 403 CSRF？

定位：GlitchTip 的认证类接口沿用 Django CSRF 保护，纯 curl 无浏览器 Cookie 无法通过。解决路径二选一：命令行场景改用 createsuperuser --noinput + APIToken（见 4.3/4.4，本篇实测采用）；浏览器场景正常走 Web 注册流程。另注意：反代域名与 GLITCHTIP_DOMAIN 不一致也会引发 CSRF 拦截，需配 CSRF_TRUSTED_ORIGINS。

Q4：createsuperuser 后登录不上 / 查无此用户？

6.x 用户模型已无 username 字段、以 email 为唯一标识（实测 User.objects.get(username='admin') 报 Cannot resolve keyword 'username' into field）。--noinput 模式实际生效的是 DJANGO_SUPERUSER_EMAIL + DJANGO_SUPERUSER_PASSWORD，登录时用 admin@example.com / q1w2e3r4。

Q5：对组织路由 POST 建项目返回 405 Method not allowed？

6.2.6 的项目创建在团队路由下：POST /api/0/teams/{org_slug}/{team_slug}/projects/；组织路由 /api/0/organizations/{org_slug}/projects/ 仅支持 GET。需先建团队（POST /api/0/organizations/{org}/teams/）再建项目。全部路由可开 ENABLE_OPENAPI=true 后访问 http://<主机>:8143/api/openapi.json 自查（6.2.6 共 114 条路径）。

Q6：SDK 上报不报错但 Issues 页始终为空？

排查顺序（本实测全部遇到）：① DSN 主机从应用侧不可达——实测中用服务器内网 IP 组装的 DSN 在本机发送未达，改 localhost 立即成功；跨机部署务必用应用可达地址；② 未等待后台分组完成——事件入库后数秒才出现在 Issues 列表；③ 项目过滤参数错误——API 查询需带 ?project=<项目ID>。

Q7：如何升级版本？

官方流程：改 compose.yml 中 image tag（如 6.2.6 → 新版本）→ docker compose pull → docker compose stop → docker compose up -d。迁移在启动时自动执行，无需手工操作。大版本（6→7）升级前先阅读官方博客发布说明（可能含 PostgreSQL 版本要求变化）。

Q8：docker run 方式启动后 web 反复重启，日志报 failed to lookup address information: Temporary failure in name resolution？

现象：web 以 Compose 同款 DATABASE_URL（主机名为 postgres）启动后 crash-loop，docker logs 呈现连接池报错，docker ps 中 web 状态为 Restarting (1)。定位：Compose 会把服务名注册为该网络的 DNS 别名（服务名 postgres 可直接解析），而 docker run 创建的实例网络别名默认是实例名（glitchtip-6.2.6-postgres），解析 postgres 失败。解决：docker run 启动 postgres/valkey 时显式加 --network-alias postgres 与 --network-alias valkey（见第八章），web 随即正常。

十一、web/worker 分离与水平扩展

全合一模式适合起步；事件量增长后官方支持把接入与后台任务拆分。改造要点（官方文档口径 + 本篇环境变量实测依据）：

web 服务设 SERVER_ROLE: web，worker 服务设 SERVER_ROLE: worker，共用同一镜像与环境变量；
worker 不映射宿主端口，仅参与内部网络；
两服务均可多副本（docker compose up -d --scale worker=2），共享 PostgreSQL 与 Valkey；
反向代理侧只需指向 web。

nginx 参考片段（官方安装文档同款结构，client_max_body_size 40M 用于大体积上报）：

server {
    server_name glitchtip.example.com;
    client_max_body_size 40M;
    location / {
        proxy_pass http://127.0.0.1:8143;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

反代后需在 compose 环境中追加 CSRF_TRUSTED_ORIGINS: "https://glitchtip.example.com"、ALLOWED_HOSTS: "glitchtip.example.com"，并把 GLITCHTIP_DOMAIN 改为对外域名。

十二、Kubernetes 部署形态（附）

除 Compose 外，GlitchTip 官方提供 Helm Chart（仓库 gitlab.com/glitchtip/glitchtip-helm-chart，本节内容实查于 2026-10-27 的官方安装文档与 chart values.yaml，未做集群实测）。适合已有 K8s 平台与高吞吐场景：

helm repo add glitchtip https://gitlab.com/api/v4/projects/16325141/packages/helm/stable
helm install glitchtip glitchtip/glitchtip -f your-values.yaml

chart 关键形态（values.yaml 实查）：

镜像：glitchtip/glitchtip，tag 缺省取 chart AppVersion；
默认副本数：replicaCount: 2，支持 autoscaling 开关（HPA）与 PodDisruptionBudget；
迁移方式：migrationJob.enabled: true——迁移以独立 Job 执行，Web 应用以 SKIP_INIT 跳过启动时自动迁移（与 Compose 形态的关键差异）；
密钥管理：SECRET_KEY/DATABASE_URL 支持引用既有 Secret（existingSecret + existingSecretKey），chart 亦支持 MAINTENANCE_DATABASE_URL、READ_ONLY_DATABASE_URL 等分离权限连接串；
上传存储：支持挂载卷或 S3 兼容对象存储，另有 symbolicationCache（符号化缓存）节点本地空目录优化；
数据库建议：官方推荐外接托管 PostgreSQL，仅提供 DATABASE_URL，不在集群内自建数据库。

十三、参考链接

官方安装文档（Compose/系统要求/环境变量）：https://glitchtip.com/documentation/install
官方 compose 样例：https://glitchtip.com/assets/compose.sample.yml
Docker Hub 官方仓库：https://hub.docker.com/r/glitchtip/glitchtip
GitLab 主仓库：https://gitlab.com/glitchtip/glitchtip
官方 Helm Chart 仓库：https://gitlab.com/glitchtip/glitchtip-helm-chart
配置参数体系详解（同专栏）：《GlitchTip 6.2.6 配置参数详解》
CLI 命令与运维实战（同专栏）：《GlitchTip 6.2.6 常用 CLI 命令与运维实战》
项目定位与选型（同专栏）：《GlitchTip 介绍与选型指南》

GlitchTip 6.2.6 Docker Compose 部署实战

GlitchTip Docker Compose 部署实战

一、环境信息

二、镜像选型说明

三、前置条件

四、部署步骤

4.1 创建编排文件

4.2 拉取镜像并启动

4.3 初始化管理员账号

4.4 为命令行操作签发 API Token

4.5 创建组织、团队与项目

4.6 获取 DSN 并接入 SDK

4.7 验证错误聚合闭环

五、数据持久化说明

六、环境变量表

七、配置文件挂载说明

八、等价 docker run 部署方式

九、常用运维命令

十、常见问题（FAQ）

十一、web/worker 分离与水平扩展

十二、Kubernetes 部署形态（附）

十三、参考链接