Postorius 1.3.13 配置参数详解

目标：逐项讲透 Postorius 1.3.13 的配置体系——Django 主体 settings.py（重点是与 Mailman core 的 REST 集成参数）、uwsgi + nginx 服务承载、配置生效矩阵与验证序列。每个参数给出默认值、实测语义与生产建议，配置示例全部来自真实安装环境（Ubuntu 22.04 + Postorius 1.3.13，实测日期 2026-10-26）。安装过程见 《Ubuntu 22.04 安装 Postorius 1.3.13 指南》。

一、环境信息

• 软件版本：Postorius 1.3.13、mailman-web 0.0.9（Django 工程模板包）、django-mailman3 1.3.15、Mailman core 3.3.10、mailmanclient 3.3.5、Django 4.2.30、uwsgi 2.0.20、nginx 1.18.0、PostgreSQL 14.24
• 本篇涉及的配置文件清单（实测环境中的真实路径）：

• 配置装载机制（实测验证）：mailman-web 0.0.9 的 wsgi 与管理命令入口先执行 mailman_web.manage.setup()，读取环境变量 MAILMAN_WEB_CONFIG（缺省 /etc/mailman3/settings.py），将该文件所在目录加入 sys.path 并把 DJANGO_SETTINGS_MODULE 指向它——因此 uwsgi 与 systemd 单元里的 env = MAILMAN_WEB_CONFIG=/etc/mailman3/settings.py 是配置生效的总开关。
• 生效方式：settings.py 与 uwsgi.ini 改后 systemctl restart mailman-web；mailman.cfg 的 [webservice] 改后 systemctl restart mailman3 mailman-web（两端成对改）；nginx 站点改后 nginx -t && systemctl reload nginx。所有回显均实测采集。

二、配置体系总览

Postorius 是纯 REST 客户端形态的 Django 应用：它不收邮件、不直接读库里的列表数据，一切列表数据都经 MAILMAN_REST_API_* 指向的 core REST API 获取。理解这条数据通道是配置管理的核心：

浏览器/nginx
   │
   ▼
uwsgi（/etc/uwsgi/mailman-web.ini）
   │  env: MAILMAN_WEB_CONFIG=/etc/mailman3/settings.py
   ▼
Postorius Django 应用（/etc/mailman3/settings.py 覆盖 mailman_web.settings 默认值）
   │
   │ MAILMAN_REST_API_URL/USER/PASS ──▶ Mailman core REST（mailman.cfg [webservice]，127.0.0.1:8001）
   │                                        ▲ 列表/域/订阅者/Held Message 全部数据来自这里
   │ POSTORIUS_TEMPLATE_BASE_URL ──▶ 本机 uwsgi http-socket（127.0.0.1:8000，模板渲染回源）
   ▼
（同一 settings.py 还装载 HyperKitty——归档推送链路属 HyperKitty，见文末交叉引用）

优先级关系：settings.py 逐行 from mailman_web.settings.base import *、from mailman_web.settings.mailman import * 之后写覆盖项，后写的值生效。MAILMAN_REST_API_* 与 POSTORIUS_TEMPLATE_BASE_URL 的缺省值正来自 mailman.py 模块（实测源码：MAILMAN_REST_API_URL = 'http://localhost:8001'、POSTORIUS_TEMPLATE_BASE_URL = 'http://localhost:8000'）；Postorius 源码自带的 example_project/settings.py 展示了全部可覆盖项（POSTORIUS_API_DEBUG、LOGIN_REDIRECT_URL 等），生产环境以「mailman-web 基座 + 少量覆盖行」为标准形态。

三、settings.py 核心参数详解

3.1 实测配置全文

（来自实测环境 /etc/mailman3/settings.py，生产可直接套用后按 3.2 的表逐项核对）

from mailman_web.settings.base import *
from mailman_web.settings.mailman import *

SECRET_KEY = "pm3-prod-secret-key-change-me-0123456789abcdef"
DEBUG = False
ALLOWED_HOSTS = ["pm1.example.com", "localhost", "127.0.0.1"]

DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.postgresql",
        "NAME": "mailmanweb",
        "USER": "mailman",
        "PASSWORD": "q1w2e3r4",
        "HOST": "localhost",
        "PORT": "5432",
    }
}

TIME_ZONE = "Asia/Shanghai"
USE_TZ = True

STATIC_ROOT = "/opt/mailman/mm/static"
MEDIA_ROOT = "/opt/mailman/mm/media"
STATIC_URL = "/static/"
MEDIA_URL = "/media/"

MAILMAN_REST_API_URL = "http://localhost:8001"
MAILMAN_REST_API_USER = "restadmin"
MAILMAN_REST_API_PASS = "restpass"
MAILMAN_ARCHIVER_KEY = "SecretArchiverAPIKey"
MAILMAN_ARCHIVER_FROM = ("127.0.0.1", "::1")

POSTORIUS_TEMPLATE_BASE_URL = "http://localhost:8000"
DEFAULT_FROM_EMAIL = "postorius@example.com"
SERVER_EMAIL = "postorius@example.com"
EMAIL_BACKEND = "django.core.mail.backends.console.EmailBackend"
ACCOUNT_DEFAULT_HTTP_PROTOCOL = "http"

HAYSTACK_CONNECTIONS = {
    "default": {
        "ENGINE": "haystack.backends.whoosh_backend.WhooshEngine",
        "PATH": "/opt/mailman/mm/fulltext_index",
    }
}

3.2 参数逐项详解

与 Mailman core 集成类（本组是 Postorius 配置的灵魂）

安全类

数据库类

账号与跳转类（Postorius 的登录体验）

路径与静态资源类

邮件类

四、core 侧对端配置与 REST 集成验证

Postorius 的 REST 凭据在 core 侧的落点是 mailman.cfg 的 [webservice] 段（属 Mailman core 配置体系，完整解析见 《Mailman 3.3.10 配置参数详解》，此处列与 Postorius 相关的四行）：

[webservice]
host: 127.0.0.1
port: 8001
admin_user: restadmin
admin_pass: restpass

• host/port：REST 监听地址，Postorius 的 MAILMAN_REST_API_URL 必须可达这里；只绑 127.0.0.1 即不对公网暴露管理 API；
• admin_user/admin_pass：与 settings.py 的 MAILMAN_REST_API_USER/PASS 成对，改必须两端同时改。

验证集成链路是否就绪（实测回显——用 Postorius 同款客户端库 mailmanclient 走一遍真实调用）：

su -s /bin/bash mailman -c 'echo "
from mailmanclient import Client
c = Client(\"http://localhost:8001/3.0\", \"restadmin\", \"restpass\")
print(\"REST lists:\", [l.fqdn_listname for l in c.lists])
print(\"REST domains:\", [d.mail_host for d in c.domains])
" | /opt/mailman/venv/bin/mailman-web shell'

REST lists: ['testlist@example.com']
REST domains: ['example.com']

（能列出域与列表即 URL+凭据双通过——这正是 Postorius 列表页背后发生的事。）

模板回源地址与 REST 地址的连通性（实测回显）：

curl -s -o /dev/null -w 'POSTORIUS_TEMPLATE_BASE_URL: %{http_code}\n' http://localhost:8000/
curl -s -o /dev/null -w 'REST from web host: %{http_code}\n' -u restadmin:restpass http://localhost:8001/3.0/system/versions

POSTORIUS_TEMPLATE_BASE_URL: 301
REST from web host: 200

（301 是根路径到列表页的正常重定向；200 即 REST 凭据有效。）

📌 同一 settings.py 还承载同栈部署的 HyperKitty：MAILMAN_ARCHIVER_KEY/MAILMAN_ARCHIVER_FROM 归档令牌与来源白名单、以及 core 侧 mailman-hyperkitty.cfg 推送配置的逐项详解见 《HyperKitty 1.3.12 配置参数详解》第四章——Postorius 本身不参与归档链路，但在 mailman-web 一体化部署中共用这套配置。

五、uwsgi 承载配置详解

/etc/uwsgi/mailman-web.ini（实测全文）：

[uwsgi]
plugins = python3
socket = /opt/mailman/mm/uwsgi.sock
chmod-socket = 666
http-socket = 127.0.0.1:8000
chdir = /opt/mailman/web
virtualenv = /opt/mailman/venv
module = mailman_web.wsgi:application
env = MAILMAN_WEB_CONFIG=/etc/mailman3/settings.py
master = true
processes = 4
threads = 2
harakiri = 60
max-requests = 500
vacuum = true
uid = mailman
gid = mailman
logto = /opt/mailman/mm/var/log/uwsgi.log

逐项详解：

六、nginx 反代配置详解

/etc/nginx/sites-available/mailman-web（实测全文）：

server {
    listen 80;
    server_name pm1.example.com;

    access_log /var/log/nginx/mailman-web.access.log;
    error_log  /var/log/nginx/mailman-web.error.log;

    client_max_body_size 20m;

    location /static/ {
        alias /opt/mailman/mm/static/;
        expires 30d;
    }

    location /media/ {
        alias /opt/mailman/mm/media/;
        expires 7d;
    }

    location / {
        include uwsgi_params;
        uwsgi_pass unix:/opt/mailman/mm/uwsgi.sock;
        uwsgi_read_timeout 300;
    }
}

逐项详解：

Postorius URL 挂载地图（mailman-web 0.0.9 实测行为，配置 nginx 后自检用）：

改后生效与验证：

nginx -t && systemctl reload nginx
curl -sI http://127.0.0.1/ | grep -iE 'HTTP|Location'

HTTP/1.1 301 Moved Permanently
Location: /mailman3/lists/

（301 落到 Postorius 列表索引即入口正常。）

七、配置变更生效矩阵与验证

变更后的标准验证序列（全部实测通过）：① systemctl is-active mailman3 mailman-web nginx postgresql postfix 五服务全 active；② mailmanclient 实测 REST 列表/域可读（第四章回显）；③ POSTORIUS_TEMPLATE_BASE_URL 回源 301（第四章回显）；④ curl -o /dev/null -w '%{http_code}' http://127.0.0.1/postorius/lists/ 得 200；⑤ 浏览器登录 admin 后列表详情页可开（/postorius/lists/testlist.example.com/ 200）。

八、常见问题（FAQ）

Q1：Postorius 页面打开报「Mailman REST API is not available / 暂不可用」，但网站其他页正常？ 这是 Postorius 最典型的故障：MAILMAN_REST_API_URL/USER/PASS 与 core 侧 [webservice] 不匹配（改过一端口令、或 URL 端口写错）。先用第四章的 mailmanclient 一行验证（列出列表即通）；不通时核对两端四行配置，成对修改后 systemctl restart mailman3 mailman-web。另外确认 core 在跑：systemctl is-active mailman3。

Q2：列表索引页 500，uwsgi 日志见模板渲染异常？ POSTORIUS_TEMPLATE_BASE_URL 指向了无 HTTP 应答的地址（典型：误指 nginx 80 之外的端口、或误删 uwsgi.ini 的 http-socket 行——该地址必须是纯 HTTP 端点）。用第四章的 curl 自检恢复 301/200 后 restart mailman-web。

Q3：换了 SECRET_KEY 之后发生什么？ 所有已签发会话立即失效，用户需重新登录；密码重置链接作废。账号与已做的列表配置不受影响。生产建议在首次上线前就定好强随机值并纳入配置备份。

Q4：页面报 400（Bad Request）？ 请求 Host 头不在 ALLOWED_HOSTS 白名单。补上真实访问域名（nginx server_name 同步核对）后 restart mailman-web。

Q5：nginx 全站 502，sock 文件也在？ uwsgi.ini 缺 socket = 行（只写了 http-socket）。nginx 的 uwsgi_pass 需要uwsgi 二进制协议，socket 与 http-socket 必须并存（第五章）。同时核对 chmod-socket 666 是否被改过——权限收窄后 www-data 打不开 sock 同样 502。

Q6：登录成功后跳回登录页或落错页面？ 登录落点由 LOGIN_REDIRECT_URL 控制（默认 'list_index' 落列表索引）；跳回登录页一般是会话问题：SECRET_KEY 刚换过（Q3）或多 worker 间时区/时钟不一致。检查 uwsgi 所在机器时间同步即可。

Q7：想统计/调试 Postorius 对 core 发出的 REST 调用？ 源码预留了调试开关：settings.py 里 DEBUG = True 且 POSTORIUS_API_DEBUG = True 时启用 APICountingMiddleware（见 example_project 源码）。仅限开发环境临时用，排障后立即关回 False。

Q8：想把 Postorius 挂到 / 前缀以外的子路径？ 需要同时改：nginx location 加路径前缀、settings.py 的 STATIC_URL/MEDIA_URL 前缀；POSTORIUS_TEMPLATE_BASE_URL 若含路径需一并核对。官方不建议子路径部署，优先用独立子域名。

九、参考链接

• Postorius 官方配置文档：https://postorius.readthedocs.io/en/latest/
• Postorius example_project/settings.py（全部可覆盖项的官方示例）：https://gitlab.com/mailman/postorius/-/blob/master/example_project/settings.py
• mailman-web 包 settings 基座（base/mailman 模块源码）：https://gitlab.com/mailman/mailman-web
• Django Settings 官方手册：https://docs.djangoproject.com/en/stable/ref/settings/
• uwsgi 官方文档（socket 与 http-socket）：https://uwsgi-docs.readthedocs.io/en/latest/
• 站内参考：《Postorius 1.3.13 介绍与选型指南》、《Ubuntu 22.04 安装 Postorius 1.3.13 指南》、《Mailman 3.3.10 配置参数详解》、《HyperKitty 1.3.12 配置参数详解》

（实测环境：Ubuntu 22.04 + Postorius 1.3.13，配置文件与全部回显采集日期 2026-10-26）