HyperKitty 1.3.12 配置参数详解

目标：逐项讲透 HyperKitty 1.3.12 的三层配置——Django 主体 settings.py、core 侧归档插件 mailman-hyperkitty.cfg、uwsgi + nginx 服务承载，每个参数给出默认值、实测语义与生产建议，配置示例全部来自真实安装环境（Debian 12 + HyperKitty 1.3.12，实测日期 2026-10-26）。安装过程见 《Debian 12 安装 HyperKitty 1.3.12 指南》。

一、环境信息

• 软件版本：HyperKitty 1.3.12、mailman-web 0.0.9（Django 工程模板包）、postorius 1.3.13、django-mailman3 1.3.15、Mailman core 3.3.10、uwsgi 2.0.21、nginx 1.22.1、PostgreSQL 15.19
• 本篇涉及的配置文件清单（实测环境中的真实路径）：

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

二、配置体系总览

HyperKitty 的配置分散在三个层次，理解「谁加载谁、改哪层、怎么生效」是配置管理的核心：

浏览器/nginx
   │
   ▼
uwsgi（/etc/uwsgi/mailman-web.ini）
   │  env: MAILMAN_WEB_CONFIG=/etc/mailman3/settings.py
   ▼
HyperKitty Django 应用（/etc/mailman3/settings.py 覆盖 mailman_web.settings.base 默认值）
   │                                    ▲
   │ MAILMAN_REST_API_* 读 core         │ MAILMAN_ARCHIVER_KEY 校验推送
   ▼                                    │
Mailman core（REST 8001）── 归档插件 mailman_hyperkitty
   （[archiver.hyperkitty] 开关 ──▶ /etc/mailman3/mailman-hyperkitty.cfg：推送地址+令牌）

优先级关系：settings.py 逐行 from mailman_web.settings.base import * 之后写覆盖项，后写的值生效；mailman.cfg 的 [archiver.hyperkitty] 只管「插件装不装、配置在哪」，推送行为细节全在 mailman-hyperkitty.cfg。

三、settings.py 核心参数详解

3.1 实测配置全文

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

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

SECRET_KEY = "hk3-prod-secret-key-change-me-0123456789abcdef"
DEBUG = False
ALLOWED_HOSTS = ["hk1.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 = "hyperkitty@example.com"
SERVER_EMAIL = "hyperkitty@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 集成类（本组是 HyperKitty 配置的灵魂）

路径与静态资源类

邮件类

四、归档插件配置 mailman-hyperkitty.cfg 详解

core 侧插件负责把每封过信邮件 HTTP POST 给 HyperKitty，它的配置极简但责任重大：

# /etc/mailman3/mailman-hyperkitty.cfg
[general]
base_url: http://localhost:8000/hyperkitty/
api_key: SecretArchiverAPIKey

它的启用开关在 core 主配置 /etc/mailman3/mailman.cfg（属 Mailman core 配置体系，此处仅列出与 HyperKitty 相关的三行）：

[archiver.hyperkitty]
class: mailman_hyperkitty.Archiver
enable: yes
configuration: /etc/mailman3/mailman-hyperkitty.cfg

• class：插件 Archiver 类的 Python 路径，来自 mailman-hyperkitty 1.2.1 包；
• enable: yes：总开关，改 no 后 core 不再推信（只影响新邮件，历史归档不受影响）；
• configuration：指向本章的插件配置文件。

验证推送链路是否就绪（实测回显——用插件同款调用方式直查归档 API，200 即令牌与白名单双通过）：

curl -s -o /dev/null -w '%{http_code}\n' \
  'http://127.0.0.1:8000/hyperkitty/api/mailman/urls?mlist=testlist@example.com' \
  -H 'Authorization: Token SecretArchiverAPIKey'

200

五、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 hk1.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;
    }
}

逐项详解：

改后生效与验证：

nginx -t && systemctl reload nginx
curl -sI http://127.0.0.1/ | head -3

HTTP/1.1 301 Moved Permanently
Server: nginx/1.22.1
Date: Mon, 26 Oct 2026 04:09:40 GMT

（根路径 301 到 HyperKitty/Postorius 默认列表页；curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1/hyperkitty/ 返回 200 即入口正常。）

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

变更后的标准验证序列（全部实测通过）：① systemctl is-active mailman3 mailman-web nginx postgresql postfix 五服务全 active；② mailman info 打印 db url 与 REST 地址；③ 归档 API Token 查询 200（4.4 节命令）；④ curl -o /dev/null -w '%{http_code}' http://127.0.0.1/hyperkitty/ 得 200；⑤ core 归档日志出现 HyperKitty archived message <msgid> to … 且 spool 目录为空。

八、常见问题（FAQ）

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

Q2：归档推送报 403 或邮件堆在 spool？ 三处逐一核对：mailman-hyperkitty.cfg 的 api_key 与 settings.py 的 MAILMAN_ARCHIVER_KEY 是否逐字符一致；base_url 指向的端口是否有 HTTP 服务应答（uwsgi 必须有 http-socket 行）；来源 IP 是否在 MAILMAN_ARCHIVER_FROM 白名单内。修复后无需手工清 spool——core 自动重试补推（实测两封积压邮件修复后 1 秒内归档成功）。

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

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

Q5：页面样式全丢，静态资源 404？ collectstatic 没跑或 STATIC_ROOT 变更后 nginx 未同步。执行 mailman-web collectstatic --noinput（实测回显 0 static files copied … 387 unmodified. 属复检正常态，首启为 387 copied），确认 nginx alias 指向新路径后 reload。

Q6：搜索一直无结果？ Whoosh 索引目录为空或权限不可写。mailman-web update_index 全量重建（实测归档两封邮件后重建立即可搜）；确认 settings.py 的 HAYSTACK PATH 目录属主与 uwsgi 运行用户一致。

Q7：归档邮件时间显示不对？ 核对 settings.py 的 TIME_ZONE 与 USE_TZ；USE_TZ 必须为 True（存 UTC、显示按时区），只改 TIME_ZONE 不改 USE_TZ 会出现历史时间整体偏移。

Q8：想把 HyperKitty 挂到 / 前缀以外的子路径？ 需要同时改：nginx location 加路径前缀、settings.py 的 STATIC_URL/MEDIA_URL 前缀、uwsgi 无需动；HyperKitty 官方不建议子路径部署，优先用独立子域名。

九、参考链接

• HyperKitty 官方配置文档：https://hyperkitty.readthedocs.io/en/latest/
• 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/
• 站内参考：《HyperKitty 1.3.12 介绍与选型指南》、《Debian 12 安装 HyperKitty 1.3.12 指南》、《HyperKitty 1.3.12 Docker Compose 部署指南》、《Mailman 3.3.10 配置参数详解》

（实测环境：Debian 12 + HyperKitty 1.3.12，配置文件与全部回显采集日期 2026-10-26）