Misago 0.39.6 配置参数详解

目标：系统讲解 Misago 0.39.6 的四层配置模型——环境变量层（config/misago.env）、settings 映射层（settings.py）、覆盖层（settings_override.py）、管理后台动态设置层（存库即时生效），逐项给出读取位置、默认值、修改方式、生效条件与实测验证，已在 Ubuntu 24.04.5 LTS + Docker 29.9.2 + Misago 0.39.6（Django 4.2.8 / PostgreSQL 15.19 / Redis 6）官方 misago_docker 部署包环境逐项实测通过。

一、环境信息

本篇实测环境（与部署篇同一套站点，所有参数可在此环境复现）：

• 操作系统：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/（宿主 80/443 被占用场景，IP 绑定 8128 发布）
• 管理员账号：admin / q1w2e3r4（演示口令）
• 配置文件：/opt/misago/config/misago.env

Misago 的配置分布在四个层面，先建立全局认知再逐层详解：

二、前置条件

本篇是配置专题篇，不重复部署步骤；开始前请确认站点已按官方 misago_docker 部署包上线（部署过程见站内《Misago 0.39.6 Docker Compose 部署指南》第四章），且满足以下两项，各给验证命令与实测回显。

./appctl 工具链可用（后续所有查看/修改/重建命令的入口，在部署目录内执行）：

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

实测回显：

System check identified no issues (0 silenced).

站点可访问（配置生效验证要用首页形态观察）：

curl -s http://192.168.1.172:8128/ | grep -oE '<title>[^<]*</title>'

实测回显：

<title>Misago</title>

三、参数查看与修改方式

3.1 环境变量层：查看与编辑

配置的唯一事实源是 config/misago.env（./appctl setup 向导生成，env_file 机制同时注入 misago 与 celery-worker 两个服务）。查看：

cat /opt/misago/config/misago.env

实测回显（本环境全量内容，密钥值以生成方法代替展示）：

MISAGO_DEBUG=no
MISAGO_DAILY_BACKUP=yes
MISAGO_SECRET_KEY=<python3 -c "import secrets; print(secrets.token_urlsafe(32))" 的输出>
MISAGO_ADDRESS=http://192.168.1.172:8128/
MISAGO_LANGUAGE_CODE=en-us
MISAGO_SEARCH_CONFIG=simple
MISAGO_TIME_ZONE=Asia/Shanghai
MISAGO_INDEX=categories
MISAGO_EMAIL_PROVIDER=console
MISAGO_DEFAULT_FROM_EMAIL=noreply@example.com

直接编辑该文件即可改参数；官方更推荐用 appctl 向导子命令改（自动校验取值并写回文件）：

./appctl forumindex   # 切换首页形态 threads/categories
./appctl hostname     # 改域名（重写 VIRTUAL_HOST/MISAGO_ADDRESS/LETSENCRYPT_*）
./appctl email        # 改邮件通道（smtp/gmail/mailjet/sendinblue/console 分支问答）
./appctl locale       # 改语言
./appctl timezone     # 改时区
./appctl debug        # 改调试模式
./appctl secret       # 重置 SECRET_KEY（会登出全部用户）
./appctl sentry       # 开关 Sentry 上报

无参执行 ./appctl 可看全量子命令分组，官方 intro 对这一组的原文提示：

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

即：这一层的所有改动都必须重建应用容器才生效（环境变量在容器创建时注入，settings.py 在进程启动时读取）：

./appctl rebuild

实测回显（末两行，构建层全部命中缓存，秒级完成）：

 Container misago_docker-misago-1 Started
 Container misago_docker-celery-worker-1 Started

3.2 settings 映射层：查看实际生效值

settings.py 把环境变量映射为 Django settings（映射关系见第五章）。查看最终生效值用 Django 原生 diffsettings（./appctl manage.py 透传进容器执行）：

./appctl manage.py diffsettings | grep -E '^ALLOWED_HOSTS|^MISAGO_THREADS_ON_INDEX|^TIME_ZONE'

实测回显：

ALLOWED_HOSTS = ['192.168.1.172']
MISAGO_THREADS_ON_INDEX = False  ###
TIME_ZONE = 'Asia/Shanghai'

读回显的两个要点（实测核对）：diffsettings 默认只列出与 Django 全局默认值不同的项与非标准自定义项（实测全量 54 行）——LANGUAGE_CODE='en-us' 与 Django 默认相同故不出现在列表里，其值以 settings.py 103 行的映射为准；行尾 ### 标记的是 Misago 自定义项（非 Django 标准 settings），如 MISAGO_THREADS_ON_INDEX。ALLOWED_HOSTS = ['192.168.1.172'] 即 VIRTUAL_HOST 经 strtolist 逗号拆分的结果。这一层只读不改——要越过环境变量直接设 Django 值，用下一节的覆盖层。

3.3 覆盖层：settings_override.py 实测

settings.py 末尾（483 行附近）有 from .settings_override import *，同目录还支持 urls_override.py（urls.py 28 行引入，override urlpatterns 先于默认检查，可覆盖既有 URL）。settings_override.py 默认不存在，需手工创建；注意它位于构建上下文内，随 Dockerfile COPY . /misago 烘焙进镜像，改完必须 rebuild：

cd /opt/misago
echo "MISAGO_THREADS_ON_INDEX = True" > misago/misagodocker/settings_override.py
./appctl rebuild 2>&1 | tail -2

验证生效——diffsettings 中该值变为 True 且带 ###（实测回显）：

./appctl manage.py diffsettings | grep MISAGO_THREADS_ON_INDEX

MISAGO_THREADS_ON_INDEX = True  ###

行为验证——首页从版块索引切换为帖子列表形态（MISAGO_INDEX=categories 被覆盖层压制，实测回显）：

curl -s http://192.168.1.172:8128/ | grep -oE 'list-group-category|page-threads-index' | sort -u

page-threads-index

删除覆盖文件并再次 rebuild，恢复 list-group-category（实测回显）：

list-group-category
MISAGO_THREADS_ON_INDEX = False  ###

优先级实证：settings_override.py > 环境变量 > settings.py 默认值。

3.4 动态设置层：/admincp/ 后台

论坛名称、描述、注册开关、帖子编辑时限、权限组等运营参数不在文件里，存数据库 misago_conf 迁移域，后台改动即时生效、免重建免重启。后台可用性实测：

curl -sI http://192.168.1.172:8128/admincp/ | head -2

HTTP/1.1 200 OK
Server: nginx/1.31.6

用 admin / q1w2e3r4 登录后可在 Settings 各页维护。划分原则：启动期参数（数据库、域名、密钥、索引形态）走环境变量层；运营参数走动态设置层——同一参数若两层都有（如站点地址），以动态设置层为准。

四、参数总览

环境变量层全部参数一览（读取位置实测核对自 misago/misagodocker/settings.py 与 docker-compose.yaml；「重建」= 需 ./appctl rebuild）：

nginx-proxy 侧参数（compose environment 注入，代理容器重建生效）：SSL_POLICY=Mozilla-Modern（TLS 套件策略）、VIRTUAL_PROTO=uwsgi（用 uwsgi_pass 而非 http_pass）、ENABLE_IPV6=true。

五、核心参数分类详解

5.1 身份与安全：SECRET_KEY 与 DEBUG

MISAGO_SECRET_KEY 是 Django 的签名根密钥：会话 Cookie、CSRF Token（CSRF_COOKIE_NAME='misagocsrftoken'，且 CSRF_COOKIE_SECURE=True）都由它派生。生成与更换：

python3 -c "import secrets; print(secrets.token_urlsafe(32))"

实测回显（示例输出，每次不同）：

ZuWKW5tLxKpmaCJgurK88C_7aa7HcO5s4lVNA6fdRGA

./appctl secret 向导会重置该值——更换密钥会立即使全部既有会话与 CSRF Token 失效（等同登出所有用户）。MISAGO_DEBUG 生产必须 no：yes 时 Django 输出详细错误页与堆栈（信息泄露面），且静态走 debug 加载器。

5.2 网络与域名：VIRTUAL_HOST 与 MISAGO_ADDRESS

VIRTUAL_HOST 一变量两用：① settings.py 44 行拆成 ALLOWED_HOSTS（不匹配的主机名请求返回 400）；② nginx-proxy 的 docker-gen 据此生成 server_name 与 upstream（实测生成配置见部署篇 FAQ 11.5）。多域名逗号分隔：VIRTUAL_HOST=www.example.com,example.com，ALLOWED_HOSTS 同步获得两项。

⚠️ 本批次实测坑：VIRTUAL_HOST 若写进 config/misago.env，会连同 env_file 注入 celery-worker，docker-gen 把 celery 也注册进 upstream（celery 不监听 3031）造成间歇 502。正确做法是只写在 override 的 misago 服务 environment: 下，完整排障实录见《Misago 0.39.6 Docker Compose 部署指南》 11.3/11.5 节。

MISAGO_ADDRESS 与 LETSENCRYPT_EMAIL/LETSENCRYPT_HOST 由 ./appctl hostname 向导成组维护（写入 env 文件），Django 进程不读取它们——前者供工具链与站内展示，后者供证书容器。

5.3 数据库连接与「库名=用户名」坑

DATABASES 直读 POSTGRES_DB/USER/PASSWORD/HOST 四变量，端口硬编码 5432（settings.py 58 行）。这四个变量在 compose 里由宿主插值变量 MISAGO_POSTGRES_* 提供（默认全 misagodb/misagodbpassword）。

⚠️ 改数据库名/用户前必读：容器内辅助脚本 ./.run 的 wait_for_db、psql、backup 均以 psql -d $POSTGRES_USER 连接——库名被当作用户名使用，POSTGRES_DB 与 POSTGRES_USER 必须同值，否则 appctl backup/psql/setup 初始化全部连不上库。实测验证（默认同值形态）：

echo "SELECT current_database(), current_user;" | ./appctl psql

实测回显（两值相同，即默认配置的自洽性验证）：

 current_database | current_user
------------------+--------------
 misagodb         | misagodb
(1 row)

5.4 缓存、会话与队列（Redis 双库分工）

会话即缓存的直接后果：./appctl flushredis 清缓存 = 登出全部用户，该命令交互确认文案原文（实测回显节选）：

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

5.5 首页形态：MISAGO_INDEX 与索引切换实验

settings.py 478 行：MISAGO_THREADS_ON_INDEX = os.environ.get('MISAGO_INDEX', "threads") == "threads"。threads（默认）首页为全站帖子列表，categories 首页为版块索引。实测两形态的切换闭环（env 层与 override 层各验一次）：

# 当前 env：MISAGO_INDEX=categories
curl -s http://192.168.1.172:8128/ | grep -oE 'list-group-category|page-threads-index' | sort -u

list-group-category

# 覆盖层强制 threads 形态（3.3 节实验）
echo "MISAGO_THREADS_ON_INDEX = True" > misago/misagodocker/settings_override.py && ./appctl rebuild >/dev/null 2>&1
curl -s http://192.168.1.172:8128/ | grep -oE 'list-group-category|page-threads-index' | sort -u

page-threads-index

生产建议：版块层级清晰的社区用 categories（本实测站点即此形态），信息流式社区用 threads。./appctl forumindex 向导改 env 后同样需 rebuild。

5.6 全文检索：MISAGO_SEARCH_CONFIG

settings.py 432 行将 MISAGO_SEARCH_CONFIG（默认 simple）注入 PostgreSQL 全文检索管道——Misago 不依赖 Elasticsearch，检索由数据库 to_tsvector/tsquery 完成。

💡 技术拓展：PostgreSQL 文本搜索配置（text search configuration）决定分词与词干化处理，常见选项对比——

配置	特点	适用
simple	只按空白/标点切词，不做词干化与停用词	多语言混排、行为可预期（Misago 默认）
english 等 pg_catalog.*	语言词干化（running→run）+ 停用词表	单一英语社区，召回更准
自定义配置（CREATE TEXT SEARCH CONFIGURATION）	组合解析器/词典，如接 zhparser/pg_jieba 扩展	中文分词需求

中文社区注意：PG 原生解析器不切中文词，simple/english 下中文检索近似整句匹配；需中文全文检索要装分词扩展并自定义配置名填入本参数。

改此参数后必须重建帖子搜索索引才对新旧数据一致（实测回显，本站无帖子）：

./appctl manage.py rebuildpostssearch

No posts were found

5.7 邮件：MISAGO_EMAIL_PROVIDER 分支

settings.py 157-184 行按 MISAGO_EMAIL_PROVIDER 的值四选一分支，其余值落入 console（邮件打到进程日志，开发/内网兜底）：

MISAGO_DEFAULT_FROM_EMAIL 为默认发件人（空串时 Django 用 webmaster@localhost 兜底，注册确认邮件会异常，生产必设）。推荐用 ./appctl email 向导配置（按分支问答并写回 env）。

5.8 插件与主题扩展点

MISAGO_PLUGINS（默认 /misago/plugins，由 Dockerfile ENV 设定）指向 discover_plugins() 扫描目录（settings.py 205-207 行），插件包挂载进该目录即被装入 INSTALLED_APPS 首位。外观定制两条路：./misago/theme 只读挂载（静态/模板覆盖，compose 实测挂载 /misago/theme:ro）与后台 misago_themes 主题系统。urls_override.py（同覆盖层机制）可改写路由。

5.9 日志与监控

settings.py 366-393 行定义 logging：应用错误日志 /misago/logs/misago.log、Celery 日志 /misago/logs/celery.log，均按周轮转（when='W0'）；uWSGI 访问日志 /misago/logs/uwsgi.log（uwsgi.ini logger file: 实测行）。三个目录经 bind 落宿主 ./logs/，cron 任务每日清理 60 天前日志（find /misago/logs/ -mtime +60 -delete）。SENTRY_DSN 非空即接入 sentry-sdk 上报（411-416 行），./appctl sentry 向导开关。

六、生产配置模板

以域名 www.example.com + HTTPS + SMTP 为例，config/misago.env 生产形态（密钥与口令用生成方法/注入方式表达，不落明文）：

MISAGO_DEBUG=no
MISAGO_DAILY_BACKUP=yes
MISAGO_SECRET_KEY=<python3 -c "import secrets; print(secrets.token_urlsafe(32))" 的输出>
MISAGO_ADDRESS=https://www.example.com/
MISAGO_LANGUAGE_CODE=en-us
MISAGO_TIME_ZONE=Asia/Shanghai
MISAGO_SEARCH_CONFIG=simple
MISAGO_INDEX=categories
MISAGO_EMAIL_PROVIDER=smtp
MISAGO_EMAIL_HOST=smtp.example.com
MISAGO_EMAIL_PORT=465
MISAGO_EMAIL_USE_SSL=yes
MISAGO_EMAIL_USE_TLS=no
MISAGO_EMAIL_USER=noreply@example.com
MISAGO_EMAIL_PASSWORD=<SMTP 口令，建议由部署平台密钥管理注入>
MISAGO_DEFAULT_FROM_EMAIL=noreply@example.com

compose 宿主层同步设置（数据库强口令 + 域名，写入宿主 shell 或 .env）：

MISAGO_POSTGRES_DB=misagodb
MISAGO_POSTGRES_USER=misagodb
MISAGO_POSTGRES_PASSWORD=<强随机口令；注意库名必须等于用户名，见 5.3>
MISAGO_POSTGRES_HOST=postgres-15

config/misago.env 中不设 VIRTUAL_HOST（5.2 坑），改在 docker-compose.override.yml 仅对 misago 服务注入域名并让证书容器接管 TLS：

services:
  misago:
    environment:
      - VIRTUAL_HOST=www.example.com
      - LETSENCRYPT_HOST=www.example.com
      - LETSENCRYPT_EMAIL=admin@example.com

应用清单：① 域名/证书参数由 ./appctl hostname 向导成组维护更省事；② 改任何 env 参数后 ./appctl rebuild；③ MISAGO_DEBUG=no 常闭；④ 每日备份已由 appctl 注册的 crontab 自动执行（备份保留 10 天，见命令篇 4.3），异地容灾需自行同步 ./backups/ 与 misago-postgres-15 卷；⑤ flushredis 前先评估登出影响（5.4）。

七、常见问题（FAQ）

Q1：改了 config/misago.env 但参数不生效？ 环境变量在容器创建时注入、settings.py 在进程启动时读取，且 settings_override.py 随镜像烘焙——任何 env/override 改动都要 ./appctl rebuild（appctl intro 原文即提示 "you need to rebuild Misago container"）。用 ./appctl manage.py diffsettings | grep <参数名> 核对最终值，带 ### 且值正确才算生效。

Q2：访问站点返回 400 Bad Request？ 请求的 Host 头不在 ALLOWED_HOSTS 里。核对 VIRTUAL_HOST 值（逗号分隔多域名）与 rebuild 是否已做；./appctl manage.py diffsettings | grep ALLOWED_HOSTS 应包含你访问用的主机名/IP。

Q3：./appctl backup 或 ./appctl psql 报连不上数据库？ 优先核对 5.3 的「库名=用户名」约束：.run 脚本用 psql -d $POSTGRES_USER 连库，MISAGO_POSTGRES_DB 与 MISAGO_POSTGRES_USER 不同值时必失败。其次核对 MISAGO_POSTGRES_PASSWORD 三处一致（postgres 容器初始化值、misago 连接值、备份脚本值）——改口令需同时重建 postgres 卷数据目录里的 pg_hba 授权，建议新装时一次定好。

Q4：清空 Redis 后所有用户被登出？ 预期行为：SESSION_ENGINE 绑定 cache 后端（5.4），会话即缓存。运维动作前先 ./appctl flushredis 的确认提示就是为此设计；确需保留会话的缓存清理目前无单清命令，建议仅在维护窗口执行。

Q5：改了 MISAGO_SEARCH_CONFIG 后搜索结果异常？ 索引向量仍按旧配置生成，必须 ./appctl manage.py rebuildpostssearch 全量重建（大站耗时较长，低峰执行；回显形态见 5.6）。

Q6：注册收不到确认邮件？ 依次核对：① MISAGO_EMAIL_PROVIDER 是否落在 console 分支（内网测试环境属预期，邮件在 docker compose logs misago 可见）；② smtp 分支六个伴随参数是否齐全（5.7 表）；③ MISAGO_DEFAULT_FROM_EMAIL 是否为空。用 ./appctl manage.py sendtestemail <你的邮箱> 直接验证通道。

Q7：首页想从版块索引换成帖子列表，改了参数没变化？ MISAGO_INDEX 需 rebuild（Q1）；若你曾创建过 settings_override.py 并写了 MISAGO_THREADS_ON_INDEX，覆盖层优先级更高（3.3 实验），删掉对应行再 rebuild。

八、参考链接

• Misago 官方文档（含 Docker 部署配置说明）：https://misago.gitbook.io/docs/setup
• 官方部署包仓库（settings.py/appctl/wizard 源码）：https://github.com/rafalp/misago_docker
• Misago GitHub 仓库：https://github.com/rafalp/Misago
• Django diffsettings 文档：https://docs.djangoproject.com/en/4.2/ref/django-admin/#diffsettings
• PostgreSQL 全文检索文档：https://www.postgresql.org/docs/15/textsearch.html
• 官方支持论坛（Docker 版块）：https://misago-project.org/c/docker/27/
• 站内配套阅读：《Misago 0.39.6 介绍与选型指南》、《Misago 0.39.6 Docker Compose 部署指南》、《Misago 0.39.6 常用 CLI 命令与工具详解》