Misago 0.39.6 常用 CLI 命令与工具详解

目标：系统整理 Misago 0.39.6 官方部署包（rafalp/misago_docker）的三套命令行工具链——主机侧 ./appctl（建站/升级/备份/运维全托管）、应用内 ./.run（初始化/备份原语）、Django manage.py（99 行全景命令与 40 余个 Misago 专属维护命令），逐条给出实测回显、参数语义与典型场景速查，已在 Ubuntu 24.04.5 LTS + Docker 29.9.2 + Compose v5.6.1 + Misago 0.39.6 环境逐条实测通过。

一、环境信息

本篇实测环境（与部署篇、配置篇同一套站点）：

• 操作系统：Ubuntu 24.04.5 LTS（x86_64）
• 部署包：rafalp/misago_docker HEAD 275343f Update to Misago 0.39.6（2026-06-19）
• Misago：0.39.6（容器内 pip show misago 实测），Django 4.2.8（manage.py --version 实测）
• 数据库：PostgreSQL 15.19；缓存/队列：Redis 6
• 部署目录：/opt/misago（./appctl 所在；本篇所有主机侧命令在此目录执行）
• 站点地址：http://192.168.1.172:8128/；管理员账号 admin / q1w2e3r4（演示口令）
• 五服务运行中：misago（uWSGI :3031）、celery-worker、nginx-proxy、postgres-15、redis-6

二、工具概览

Misago 官方部署链有三层命令入口，各司其职：

主机侧不直接敲 docker compose exec/run——appctl 已提供 manage.py/run/bash/psql 四个透传口（4.4 节），语义等价且自动带上 env_file 与卷上下文。

./appctl 无参执行即输出全量帮助（实测回显，原文照抄）：

./appctl

Usage: ./appctl [arg] ...
Arguments grouped by type:

Setup and upgrade:

    setup             Setup new Misago site.
    upgrade           Backup, rebuild, migrate and collect static.

Docker management:

    start             Start all containers.
    stop              Stop all containers.
    restart           Stop and start all docker containers.
    rebuild           Rebuild and restart Misago and celery container containers.
    rebuildall        Pull, rebuild and restart all containers.
    stats             See list and stats of running docker containers.

Change configuration:

    forumindex        Switch forum index between threads and categories.
    email             Change email setup.
    hostname          Change hostname setup.
    locale            Change locale setup.
    timezone          Change timezone setup.
    avatargallery     Load avatar gallery.
    sentry            Enable or disable Sentry (sentry.io) for logging.
    debug             Change debug mode.
    secret            Reset secret key.

    Note: you need to rebuild Misago container for changes made with those utils to take effect.

Backup:

    backup            Backup and archive database and media.
    restore BACKUP    Restore database and media from BACKUP archive.

Utilities:

    collectstatic     Collect static assets.
    manage.py         Runs "python manage.py" inside docker.
    bash              Starts bash session inside running Misago container.
    run               Runs "docker compose run --rm misago".
    psql              Runs psql connected to database.
    flushredis        Flush the redis cache.
    resetcron         Replace host's crontab with default one.

速查表（按用途索引，详解见第四章）：

三、前置条件

已按官方部署包完成建站（部署过程见站内《Misago 0.39.6 Docker Compose 部署指南》），并在部署目录内执行：

cd /opt/misago && ./appctl manage.py check

实测回显：

System check identified no issues (0 silenced).

⚠️ require_setup 门槛：除 setup 外的所有 appctl 子命令都会先检查 config/misago.env 是否存在（脚本 22-28 行），未建站直接执行会得到报错原文：

You need to setup your site using "./appctl setup" before you will be able to use this option.

子命令拼错时报错原文（脚本 103-107 行 invalid_argument）：

Invalid argument: <你输入的参数>
Please run this script without any arguments to see the list of available arguments.

四、各工具详解

4.1 appctl：建站与升级

setup——交互式建站向导（wizard/setup.py）：问答收集域名、邮箱、语言、时区、首页形态、搜索配置、邮件通道并生成 MISAGO_SECRET_KEY，写入 config/misago.env 后自动串联 docker compose build --no-cache --force-rm --pull → collectstatic → ./.run initialize_default_database（建库迁移+头像库+创建超级用户）→ 启动容器 → 注册宿主 crontab。非交互等价流程见部署篇第四章。

upgrade——标准升级流程（备份→停服→git pull→重建→迁移→清版本缓存→起服→重注册 cron）。执行前的确认提示与回滚指引原文（脚本 172-183 行，实测源码核对）：

You are going to upgrade your Misago site to the new version.
All running docker containers will be stopped for the duration of the upgrade.
Your site's data will be backed up to the "backups" directory.
New version of misago-docker will be pulled from github.com

In case of any issues, run this command to return to the current version:

git reset --hard <8位commit> && docker compose build --no-cache --force-rm --pull

Note: remember to also restore your backup in case you are rolling back!

Start upgrade process? [Y/n]:

升级前自动 create_new_backup "upgrade" 落一份备份；输入 n 回显 Upgrade canceled. 并原样退出。completemajorupgrade 是 v0→v1 大版本迁移的收尾步骤（校验 backups/postgresql10.sql 后导入并完成升级），现役 v1 站点日常用不到。

生命周期命令实测：

./appctl stop

实测回显（节选，五容器逐个 Stopped）：

 Container misago_docker-celery-worker-1 Stopped
 Container misago_docker-misago-1 Stopped
 Container misago_docker-postgres-15-1 Stopped
 Container misago_docker-redis-6-1 Stopped

./appctl start && sleep 8 && curl -s -o /dev/null -w '%{http_code}\n' http://192.168.1.172:8128/

实测回显：

 Container misago_docker-nginx-proxy-1 Started
 Container misago_docker-misago-1 Started
 Container misago_docker-celery-worker-1 Started
200

restart = stop + start；rebuild 只重建并重启 misago 与 celery-worker 两个应用容器（配置层改动后的标准生效动作，实测无代码变更时构建层全命中缓存、秒级完成）；rebuildall 则 --pull 拉取基础镜像后全量重建。

stats——观察资源占用（内部为流式 docker stats，持续刷新，Ctrl+C 退出）。一次性采样可用 --no-stream 等价形态（实测回显，本栈五行）：

docker stats --no-stream --format 'table {{.Name}}\t{{.MemUsage}}' | grep misago_docker

misago_docker-misago-1          139.4MiB / 15.57GiB
misago_docker-celery-worker-1   355.3MiB / 15.57GiB
misago_docker-nginx-proxy-1     42.12MiB / 15.57GiB
misago_docker-postgres-15-1     21.39MiB / 15.57GiB
misago_docker-redis-6-1         2.945MiB / 15.57GiB

4.2 appctl：配置向导族

forumindex / email / hostname / locale / timezone / debug / secret / sentry / avatargallery 九个交互向导分别改写 config/misago.env 的对应键（MISAGO_INDEX、MISAGO_EMAIL_*、VIRTUAL_HOST+MISAGO_ADDRESS+LETSENCRYPT_*、MISAGO_LANGUAGE_CODE、MISAGO_TIME_ZONE、MISAGO_DEBUG、MISAGO_SECRET_KEY、SENTRY_DSN）；avatargallery 则直接执行 manage.py loadavatargallery。各键语义、默认值与生效机制详解见《Misago 0.39.6 配置参数详解》第五章；appctl 帮助对这一族的原文提示：改完必须 rebuild 才生效（"you need to rebuild Misago container for changes made with those utils to take effect"）。

avatargallery 实测回显（幂等复跑形态）：

./appctl avatargallery

New galleries have been loaded.

secret 向导会展示当前密钥并询问 Generate new secret key?——重置会使全部会话与 CSRF 失效（等同登出全员），低峰执行。

4.3 appctl：备份、恢复与定时任务

backup——数据库 + 用户上传媒体打包归档（实测完整回显）：

./appctl backup

Initializing backup manual-20261102152126
Preparing database...
Preparing media files...
Archiving...
Cleaning up...
New backup: manual-20261102152126.tar.gz

命名恒为 manual-YYYYMMDDHHMMSS.tar.gz（create_new_backup 固定前缀，daily_backup 子命令同走此函数）。归档结构实测：

tar -tzf backups/manual-20261102152126.tar.gz | head -4

manual-20261102152126/
manual-20261102152126/media/
manual-20261102152126/media/avatars/
manual-20261102152126/database.sql

database.sql 由容器内 pg_dump -Oxc 生成（无 owner、无权限语句、纯 CREATE 语句，跨环境可导入）。

restore——按归档名恢复（参数必填，先校验 backups/<归档> 存在）：解包到 backups/tmp-<时间戳> → 校验含 database.sql 与 media/ → ./.run psql < database.sql 导入数据库 → 清空并替换 ./misago/media/* → 清理临时目录。完成提示原文（脚本 387 行）：

Restore completed! Remember to run "./appctl rebuild" to rebuild and restart your site!

⚠️ 两个必知：① restore 会覆盖现库与现媒体，执行前先 ./appctl backup 留一份还原点；② 归档名必须精确匹配 backups/ 下文件名，先 ls backups/ 确认（实测目录回显）：

manual-20261102145738.tar.gz
manual-20261102145750.tar.gz
manual-20261102152126.tar.gz

crontab 三行——setup/upgrade/resetcron 都会调用 set_crontab 向宿主当前用户注册定时任务（实测脚本 154-165 行生成的三行）：

30 1 * * * cd <部署目录> && docker compose run --rm misago ./cron
0 1 * * * cd <部署目录> && docker compose run --rm misago ./.run backup "auto-$(date +%Y%m%d%H%M%S)"
0 1 * * * find <部署目录>/backups/ -name auto-* -type f -mtime +10 -delete

即每日 01:00 自动备份（auto-* 前缀，保留 10 天后自动清理）、01:30 跑维护脚本 ./cron（见 4.6）。resetcron 重新生成这三行——注意它用 crontab cron_tmp 整体替换宿主当前用户 crontab，若该用户有其他定时任务，先 crontab -l 备份合并。

4.4 appctl：透传工具族

manage.py——把 Django 管理命令透传进 misago 容器执行（docker compose run --rm misago python manage.py <参数>），实测：

./appctl manage.py invalidateversionedcaches

Invalidated all versioned caches.

run——通用 docker compose run --rm misago <命令> 透传口（跑 .run、psql 等任意一次性命令）。bash——docker compose exec misago bash 进入运行中容器的交互 shell（排障时看日志、试命令用；非交互场景用 exec -T 直跑单命令）。

psql——带全连接参数直连业务库（stdin 管道可用，实测回显）：

echo "SELECT version();" | ./appctl psql

----------------------------------------------------------------------------------------------------------------------
 PostgreSQL 15.19 (Debian 15.19-1.pgdg13+2) on x86_64-pc-linux-gnu, compiled by gcc (Debian 14.2.0-19) 14.2.0, 64-bit
(1 row)

collectstatic——重建后或换主题后收集静态资产（实测回显）：

./appctl collectstatic

348 static files copied to '/misago/static', 1 unmodified, 349 post-processed.

flushredis——清空 Redis（缓存 + 会话）。交互确认文案与取消路径实测回显：

echo n | ./appctl flushredis

  - Remove all cached information
  - Close all user sessions (log all users out)

Cache flush canceled.

输 y 则执行并回显 OK（实测）——因 SESSION_ENGINE 绑定 Redis cache，清缓存即登出全部在线用户，务必低峰执行。

4.5 .run：容器内脚本家族

/misago/.run 是镜像内的 bash 分发器（主机侧经 ./appctl run ./.run <命令> 触达），无参静默退出，非法参数回显（实测）：

./appctl run ./.run badcommand

Invalid argument: badcommand

子命令全集（源码分发段核对）：

⚠️ 已知设计坑：wait_for_db/psql/backup 一律用 -d $POSTGRES_USER 连库（库名=用户名），POSTGRES_DB 与 POSTGRES_USER 不同值时这三个动作全部失败，详见配置篇 5.3。

4.6 manage.py：Django 命令与 Misago 维护命令

全量命令清单（./appctl manage.py help 实测回显，按 app 分组照抄）：

Type 'manage.py help <subcommand>' for help on a specific subcommand.

Available subcommands:

[auth]
    changepassword

[cache]
    invalidateversionedcaches

[categories]
    fixcategoriestree
    prunecategories
    synchronizecategories

[contenttypes]
    remove_stale_contenttypes

[debug_toolbar]
    debugsqlshell

[django]
    check
    compilemessages
    createcachetable
    dbshell
    diffsettings
    dumpdata
    flush
    inspectdb
    loaddata
    makemessages
    makemigrations
    migrate
    optimizemigration
    sendtestemail
    shell
    showmigrations
    sqlflush
    sqlmigrate
    sqlsequencereset
    squashmigrations
    startapp
    startproject
    test
    testserver

[faker]
    createfakebans
    createfakecategories
    createfakefollowers
    createfakehistory
    createfakenotifications
    createfakeposts
    createfakethreads
    createfakeusers
    createfakewatchedthreads

[notifications]
    clearnotifications

[readtracker]
    clearreadtracker

[rest_framework]
    generateschema

[sessions]
    clearsessions

[social_django]
    clearsocial

[staticfiles]
    collectstatic
    findstatic
    runserver

[threads]
    clearattachments
    rebuildpostssearch
    synchronizethreads
    updatepostschecksums

[users]
    buildactivepostersranking
    createsuperuser
    deleteinactiveusers
    deletemarkedusers
    deleteprofilefield
    expireuserdatadownloads
    invalidatebans
    listusedprofilefields
    loadavatargallery
    populateonlinetracker
    prepareuserdatadownloads
    removeoldips
    synchronizeusers

Misago 专属维护命令逐条实测回显（本站为初始化后空数据稳态，回显即稳态形态；有数据时命令会输出实际处理量）：

常用 Django 标准命令实测：

./appctl manage.py check
./appctl manage.py showmigrations misago_threads | tail -3

System check identified no issues (0 silenced).
 [X] 0012_set_dj_partial_indexes
 [X] 0013_rename_pollvote_poll_voter_name_misago_thre_poll_id_c3e8fe_idx_and_more
 [X] 0014_plugin_data

createsuperuser 特别提示（本批次实测坑）：Misago 用 users 应用覆盖了 Django 原版命令，新增原生 --password 参数且不读 DJANGO_SUPERUSER_PASSWORD 环境变量；--noinput 缺密码时静默 exit 0 不建用户。帮助原文（实测回显节选）：

usage: manage.py createsuperuser [-h] [--username USERNAME] [--email EMAIL]
                                 [--password PASSWORD] [--noinput]
                                 [--database DATABASE] ...
  --password PASSWORD   Specifies the password for the superuser.
  --noinput, --no-input
                        Tells Misago to NOT prompt the user for input of any
                        kind. ...

正确用法与回显见部署篇 4.5 节。

*faker 组（9 个 createfake 命令）**：生成假版块/用户/帖子/通知等测试数据（misago.faker 应用），仅用于开发/压测环境填充——生产站点禁用，假数据会进计数、排行与搜索索引，清理成本高。

cron 维护脚本：misago/cron（容器内 /misago/cron）串起 ./.run wait_for_db → find /misago/logs/ -mtime +60 -delete（清 60 天前日志）→ 上表 13 条维护命令（deletemarkedusers → prunecategories → buildactivepostersranking → clearattachments → clearnotifications → clearreadtracker → clearsessions → clearsocial → invalidatebans → removeoldips → deleteinactiveusers → expireuserdatadownloads → prepareuserdatadownloads），由 4.3 节 crontab 每日 01:30 执行。脚本头注释明示可自行编辑追加 manage.py 调用——顺序执行、单任务内存占用可控是其设计要点。

五、注意事项

5.1 命令速查与组合场景

5.2 run 与 exec 的差异

./appctl manage.py/run 走 docker compose run --rm（每次新建一次性容器，慢但隔离）；./appctl bash 走 exec（进现运行容器，快）。脚本化非交互执行务必加 -T（docker compose exec -T misago python manage.py <cmd>），否则 TTY 分配会干扰管道与退出码。

5.3 宿主变量不透传

VAR=x docker compose run --rm misago ... 容器内读不到 VAR——compose 只注入编排声明过的变量；需要透传时在 compose/override 的 environment: 声明或 run -e VAR=x（排障实录见部署篇 11.6）。

5.4 stats 与 flushredis 的行为边界

stats 是流式输出（不会自行退出，脚本化采样用 docker stats --no-stream）；flushredis 清的是缓存+会话（SESSION_ENGINE=cache），非仅缓存——执行即全员登出，确认提示不可跳过。

六、常见问题（FAQ）

Q1：./appctl backup 报 You need to setup your site using "./appctl setup"？ require_setup 检查的是 config/misago.env 存在性（脚本 22-28 行）。非交互建站时该文件需手工就位（内容模板见部署篇 4.2），或先跑一次 ./appctl setup。

Q2：createsuperuser --noinput 退出码 0 但用户没建成？ Misago 版命令不读 DJANGO_SUPERUSER_PASSWORD，必须显式 --password（4.6 节帮助原文可证）；建成与否以 Superuser #1 has been created successfully. 回显或后台查询为准。

Q3：./appctl psql 或 backup 连不上数据库？ 先核对「库名=用户名」约束（.run 用 -d $POSTGRES_USER 连库，配置篇 5.3）；再 docker compose ps 确认 postgres-15 在跑；最后核对 MISAGO_POSTGRES_PASSWORD 与 postgres 容器初始化口令一致。

Q4：restore 报 Specified archive is missing database backup.？ 归档不完整（backup 中途被打断）或传的不是 manual-*/auto-* 系列归档；用 tar -tzf backups/<归档> 确认含 database.sql 与 media/ 再恢复。

Q5：./appctl resetcron 之后其他业务的定时任务消失了？ 预期行为——它用三行官方模板整体替换宿主当前用户 crontab（4.3 节警告）。恢复方法：替换前 crontab -l 留存，事后把其他行合并回去再 crontab 写入。

Q6：升级后页面样式错乱/静态 404？ ./appctl upgrade 已含 collectstatic，若仍异常多为版本化缓存：./appctl manage.py invalidateversionedcaches 后强刷浏览器；再不行 ./appctl collectstatic 手动补收一次（回显形态见 4.4）。

Q7：维护命令想加自己的任务？ 直接编辑部署包 misago/cron 脚本追加 python manage.py <cmd> 行（脚本头注释明示允许），随每日 01:30 的 crontab 生效，无需改 appctl。

七、参考链接

• 官方部署包仓库（appctl/.run/cron/wizard 源码）：https://github.com/rafalp/misago_docker
• 部署包 README（setup 向导与备份说明）：https://github.com/rafalp/misago_docker#readme
• Misago 官方文档：https://misago.gitbook.io/docs/setup
• Misago GitHub 仓库：https://github.com/rafalp/Misago
• Django manage.py 文档：https://docs.djangoproject.com/en/4.2/ref/django-admin/
• 官方支持论坛（Docker 版块）：https://misago-project.org/c/docker/27/
• 站内配套阅读：《Misago 0.39.6 介绍与选型指南》、《Misago 0.39.6 Docker Compose 部署指南》、《Misago 0.39.6 配置参数详解》