GlitchTip 6.2.6 常用 CLI 命令与运维实战

目标：覆盖 GlitchTip 6.2.6 日常运维的命令行能力：manage.py 管理命令体系（用户、迁移、维护、样例数据）、API Token 签发与管理、组织/项目/DSN 的 API 运维动作、队列与后台任务、定时维护方案，并沉淀实测排障结论。全部命令与回显来自 2026-10-27 部署实例实测（部署过程见《GlitchTip 6.2.6 Docker Compose 部署实战》）。

一、环境信息

操作系统：Ubuntu 22.04 LTS（x86_64），Docker Compose v5.6.1 编排
GlitchTip：6.2.6（SERVER_ROLE=all_in_one），PostgreSQL 18，Valkey 9
服务实例名：glitchtip-6.2.6-web（所有管理命令经 docker exec glitchtip-6.2.6-web ./manage.py … 执行）
已有数据：管理员 admin@example.com、组织 demo-org、项目 demo-app（id=1）、API Token 一枚
实测日期：2026-10-27

二、CLI 体系总览

GlitchTip 的命令行入口是 Django 的 manage.py，在服务实例内执行。三种等价调用方式：

docker exec glitchtip-6.2.6-web ./manage.py <命令> [参数]        # 一次性执行（推荐）
docker exec -it glitchtip-6.2.6-web ./manage.py shell            # 进入交互式 Django shell
docker exec -it glitchtip-6.2.6-web bash                          # 进入实例后 ./manage.py …

./manage.py help 列出全部可用命令。6.2.6 的命令来自四个层级（实测 help 输出归纳）：

层级	来源	代表命令
Django 内建	django.core	`createsuperuser`、`migrate`、`shell`、`check`、`dbshell`、`dumpdata`、`sendtestemail`
django_extensions 扩展	第三方	`shell_plus`、`print_settings`、`show_urls`、`generate_secret_key`、`clear_cache`、`mail_debug`
GlitchTip 自有	glitchtip/issues_events/logs/performance/uptime/ninja/vtasks 等应用	`maintain_partitions`、`make_sample_issues`、`export_openapi_schema`、`clear_queue`
静态/内容	staticfiles 等	`collectstatic`、`findstatic`

⚠️ 注意：GlitchTip 6.x 的 API 框架已从 Django REST Framework 迁移到 django-ninja，早期资料中的 drf_create_token 命令在 6.2.6 中不存在（实测 CommandError: Unknown command），Token 改由 APIToken 模型签发，见第四章。

三、用户与账号命令

创建超级管理员（部署后的第一个命令，--noinput 模式经环境变量传参；注意 6.x 用户模型以 email 为唯一标识）：

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

实测回显：

Superuser created successfully.

修改用户密码（交互式；忘记管理员密码时的标准恢复路径）：

docker exec -it glitchtip-6.2.6-web ./manage.py changepassword admin@example.com

列用户/重置邮箱等账号操作经 shell 完成：

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

实测回显：

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

四、数据库与迁移命令

迁移状态——6.2.6 首启自动迁移后的实测状态：

docker exec glitchtip-6.2.6-web ./manage.py showmigrations

实测回显（统计与节选）：

（统计：123 个迁移全部为 [X] 已应用状态）
[ ] glitchtip
 [X] 0001_initial
...

正常情况下无需手动执行 migrate：全合一模式启动时自动迁移（部署篇日志可见 Applying … OK 序列）。手动 ./manage.py migrate 仅在恢复备份后状态异常、或用 SKIP_INIT=true 跳过自动迁移的部署形态（K8s migrationJob）中需要。

进入数据库命令行——dbshell 在 6.2.6 精简服务实例中不可用（实测报 CommandError: You appear not to have the 'psql' program installed or on your path.），替代路径是直接进数据库服务执行 psql：

docker exec -it glitchtip-6.2.6-postgres psql -U glitchtip -d glitchtip

实测回显（提示符与烟囱测试）：

glitchtip=# SELECT 1 AS smoke;
 smoke
-------
     1
(1 row)

数据导出：

# Django 层导出（JSON，适合跨版本搬运核心配置数据）
docker exec glitchtip-6.2.6-web ./manage.py dumpdata --exclude=contenttypes --exclude=auth > data.json
# 数据库层全量备份（推荐，事件数据在分区表中）
docker exec glitchtip-6.2.6-postgres pg_dump -U glitchtip -d glitchtip | gzip > backup-$(date +%F).sql.gz

实测回显（备份文件核对）：

ls -lh backup-*.sql.gz

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

五、应用生命周期与维护命令

check——部署后健康自检（配置/模型一致性）：

docker exec glitchtip-6.2.6-web ./manage.py check

实测回显：

System check identified no issues (0 silenced).

maintain_partitions——事件/日志/拨测分区表的创建与清理（启动时自动跑，也可 cron 定期跑）：

docker exec glitchtip-6.2.6-web ./manage.py maintain_partitions

实测回显：

Maintaining weekly partitions for issue_events_issueevent...
Cleaning up old weekly partitions for issue_events_issueevent...
Maintaining weekly partitions for logs_logevent...
Cleaning up old weekly partitions for logs_logevent...
Maintaining weekly partitions for projects_logprojecthourlystatistic...
Cleaning up old weekly partitions for projects_logprojecthourlystatistic...
Maintaining weekly partitions for uptime_uptimecheckhourlystatistic...
Cleaning up old weekly partitions for uptime_uptimecheckhourlystatistic...
Partition maintenance complete.

sendtestemail——邮件链路验证（配合 EMAIL_URL 配置）：

docker exec glitchtip-6.2.6-web ./manage.py sendtestemail admin@example.com

实测回显（consolemail 模式下邮件原文直接打到标准输出，节选头尾）：

Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: [Django] Test e-mail from ...
From: root@localhost
To: admin@example.com
Date: ...
Message-ID: ...
-------------------------------------------------------------------------------

collectstatic——6.2.6 镜像不需要也不支持运行期收集（实测报错）：

docker exec glitchtip-6.2.6-web ./manage.py collectstatic --noinput

实测回显（失败）：

PermissionError: [Errno 13] Permission denied: '/code/static/admin/js/vendor/select2/i18n/fi.614ec42aa9ba.js'

结论：静态文件在镜像构建期已就位，运行实例对 /code/static 无写权限属预期设计——裸机部署（官方「Installing Without Docker」路径）才需要手动 collectstatic，编排部署请忽略该命令。

六、API Token 管理命令

6.2.6 的个人 Token 由 APIToken 模型承载（Sentry 风格 scope 位串）。签发一枚全权限 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)
"

实测回显（64 位 token，展示脱敏）：

394dbbdfec23...(64 位)

使用方式（HTTP 头 Authorization: Bearer <token>）与撤销（删除模型记录即可失效）：

curl -s http://192.168.1.62:8143/api/0/organizations/ -H "Authorization: Bearer $TOKEN" -w '\nHTTP %{http_code}\n'

[{"name": "Demo Org", "id": "1", ...}]
HTTP 200

docker exec glitchtip-6.2.6-web ./manage.py shell -c "
from apps.api_tokens.models import APIToken
APIToken.objects.filter(label='cli-admin').delete()
print('revoked')
"

七、组织/项目/DSN 运维动作（API 实测）

以下为运维常用的 API 动作矩阵（BASE=http://192.168.1.62:8143，AUTH="Authorization: Bearer $TOKEN"，全部实测）：

建团队与项目（项目必须建在团队路由下，组织路由仅查询）：

curl -s -X POST $BASE/api/0/organizations/demo-org/teams/ -H "$AUTH" -H 'Content-Type: application/json' -d '{"name":"Platform Team","slug":"platform"}'
curl -s -X POST $BASE/api/0/teams/demo-org/platform/projects/ -H "$AUTH" -H 'Content-Type: application/json' -d '{"name":"demo-app","platform":"python"}'

查看与轮换 DSN——项目密钥（keys）即 DSN，支持创建/删除/轮换（rotate 让旧 DSN 失效）：

curl -s $BASE/api/0/projects/demo-org/demo-app/keys/ -H "$AUTH"   # 列出
curl -s -X POST $BASE/api/0/projects/demo-org/demo-app/keys/ -H "$AUTH" -H 'Content-Type: application/json' -d '{"name":"new-key"}'   # 新建一枚 key
curl -s -X PUT $BASE/api/0/projects/demo-org/demo-app/keys/<key_id>/rotate/ -H "$AUTH"   # 轮换（作废旧公钥）

实测回显（keys 列表节选，DSN 主机取自 GLITCHTIP_DOMAIN）：

{
    "id": "c922bf01-7d78-4d37-8f25-cbeafc314fd6",
    "dsn": {"public": "http://c922bf017d784d378f25cbeafc314fd6@192.168.1.62:8143/1"},
    "projectID": 1
}

Issue 运维动作——解决、忽略、指派（action 参数实测可用值）：

curl -s -X PUT "$BASE/api/0/organizations/demo-org/issues/?project=1&id=<issue_id>" \
  -H "$AUTH" -H 'Content-Type: application/json' -d '{"status":"resolved"}'
curl -s -X PUT "$BASE/api/0/organizations/demo-org/issues/?project=1&id=<issue_id>" \
  -H "$AUTH" -H 'Content-Type: application/json' -d '{"status":"ignored"}'

事件查询——按 issue 拉取最新事件详情（堆栈/面包屑）：

curl -s "$BASE/api/0/organizations/demo-org/issues/?project=1&query=" -H "$AUTH" | python3 -m json.tool
curl -s "$BASE/api/0/organizations/demo-org/issues/<issue_id>/events/latest/" -H "$AUTH" | python3 -m json.tool

实测回显（Issues 列表节选，验证聚合生效）：

{
    "title": "ZeroDivisionError: division by zero",
    "level": "error",
    "count": "3",
    "status": "unresolved"
}

八、GlitchTip 自有命令矩阵

./manage.py help 中 GlitchTip 自有命令全集（6.2.6 实测列出，用途按官方模块名归纳）：

应用	命令	用途
glitchtip	`import_legacy_events`	从旧版事件存储导入历史事件
glitchtip	`maintain_partitions`	分区表创建/清理（见第五章实测）
issue_events	`issue_generator` / `make_sample_issues`	生成样例 Issue（演示/验收环境造数）
logs	`make_sample_logs` / `perf_test_logs`	生成样例日志 / 日志性能压测数据
performance	`make_sample_transactions`	生成样例性能事务数据
uptime	`make_sample_checks` / `resync_monitor_cache`	生成样例拨测项 / 重同步拨测缓存
projects	`bootstrap_dev`	开发环境引导数据
ninja	`export_openapi_schema`	导出 API 的 OpenAPI 规范文件
django_vtasks	`runworker` / `clear_queue` / `benchmark_vtasks`	运行后台任务 worker / 清空任务队列 / 任务基准测试

造数命令适合验收演示（例如快速填充一个带数据的看板）：

docker exec glitchtip-6.2.6-web ./manage.py make_sample_issues --help

实测回显（参数帮助节选）：

usage: manage.py make_sample_issues [-h] [--project PROJECT] [--n N] [--issue Issue] [--event Event]

九、队列与后台任务运维

全合一模式内置后台任务处理（队列在 Valkey）。运维关注三点（实测命令帮助）：

docker exec glitchtip-6.2.6-web ./manage.py clear_queue --help

实测回显（节选）：

usage: manage.py clear_queue [-h] [--backend-alias BACKEND_ALIAS] [--queue QUEUE]
                             [--all-queues] [--force] ...

队列积压清理：./manage.py clear_queue --all-queues --force（清空待处理任务，事件数据不受影响）；
worker 状态：all_in_one 下 worker 内嵌运行，实例日志出现任务处理记录；独立 worker 形态由 SERVER_ROLE=worker 的实例经 runworker/启动脚本承担；
缓存清理：django_extensions 提供 ./manage.py clear_cache（界面缓存异常时的软恢复手段）。

十、定时维护与自动化

推荐的 cron 维护组合（宿主机 crontab，实测各命令均可无交互执行）：

# 每日 02:30 数据库全量备份（保留 14 天）
30 2 * * * docker exec glitchtip-6.2.6-postgres pg_dump -U glitchtip -d glitchtip | gzip > /opt/glitchtip/backup-$(date +\%F).sql.gz && find /opt/glitchtip -name 'backup-*.sql.gz' -mtime +14 -delete
# 每小时分区维护（官方默认随启动执行，长驻实例可显式加保）
0 * * * * docker exec glitchtip-6.2.6-web ./manage.py maintain_partitions

版本升级三步（部署篇 Q7 同款，命令视角）：

cd /opt/glitchtip && docker compose pull && docker compose stop && docker compose up -d
docker exec glitchtip-6.2.6-web ./manage.py check          # 升级后自检
docker exec glitchtip-6.2.6-web ./manage.py showmigrations | grep -c '\[X\]'   # 迁移计数核对

十一、常见问题（FAQ）

Q1：drf_create_token 命令报 Unknown command？ 6.x 已从 DRF 迁移到 django-ninja，该命令随 DRF 移除。用第四章的 APIToken 模型签发流程替代。

Q2：dbshell 报 You appear not to have the 'psql' program installed？ 6.2.6 精简服务实例未内置 psql 客户端，属预期。到数据库服务侧执行：docker exec -it glitchtip-6.2.6-postgres psql -U glitchtip -d glitchtip。

Q3：collectstatic 报 PermissionError？ 编排部署的静态文件在构建期已就位、运行期目录只读，不需要手动收集。仅裸机部署（官方 Without Docker 路径）需要手动 collectstatic。

Q4：shell -c "…" 里的引号嵌套报错？ Django shell 的 -c 参数是 Python 代码，外层双引号时内部字符串用单引号，多层嵌套时改为 heredoc 写入临时脚本再 ./manage.py shell < /tmp/script.py 执行。

Q5：样例数据命令跑完在界面看不到？ make_sample_* 系列默认写入当前时间分区，界面需选择对应项目与时间范围；确认命令输出中的 project 参数与界面一致。

十二、参考链接

官方安装文档（Without Docker 的 CLI 依赖路径）：https://glitchtip.com/documentation/install
GitLab 主仓库：https://gitlab.com/glitchtip/glitchtip
API 文档端点（实例内）：<http://<实例地址>/api/docs>
部署过程与编排细节：同专栏《GlitchTip 6.2.6 Docker Compose 部署实战》
参数含义与生效验证：同专栏《GlitchTip 6.2.6 配置参数详解》
项目定位与选型：同专栏《GlitchTip 介绍与选型指南》