Apache Pony Mail 0.11-incubating 配置参数详解

目标：详解 Apache Pony Mail 0.11-incubating 的三层配置——归档器/导入器配置 tools/ponymail.cfg、mod_lua 后端配置 site/api/lib/config.lua、前端配置 site/js/config.js，以及 ES 服务参数（JVM 堆 256-512MB）与 Apache vhost 参数，并给出可直接套用的生产模板。参数与默认值均基于真实环境实测。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS（x86_64）
• Apache Pony Mail：0.11-incubating（安装目录 /opt/ponymail）
• Elasticsearch：2.4.6（JVM 堆 -Xms256m -Xmx256m）
• 配置文件：
  • /opt/ponymail/tools/ponymail.cfg（setup.py 生成）
  • /opt/ponymail/site/api/lib/config.lua（setup.py 生成）
  • /opt/ponymail/site/js/config.js（由 config.js.sample 复制）
  • /opt/elasticsearch/config/elasticsearch.yml（ES 服务参数）
  • /etc/apache2/sites-available/ponymail.conf（web 前端参数）
• 默认端口：web 8080、ES 9200（本机）、LMTP 归档 8024

二、前置条件

• 已完成 Pony Mail 0.11-incubating 安装并跑通归档链路（ES 2.4.6 + Apache mod_lua web + lmtpd 网关）。
• 参数生效方式：
  • ponymail.cfg：归档器/导入器每次进程启动时读取，修改后需重启 lmtpd（systemctl restart ponymail-lmtpd）或重新调用 archiver.py；
  • config.lua：mod_lua 以 LuaCodeCache stat 运行，修改后 systemctl reload apache2 即可生效；
  • elasticsearch.yml 与 systemd 单元：需 systemctl restart elasticsearch；
  • 前端 config.js：浏览器刷新即生效。

三、参数查看与修改方式

# 查看当前生效配置
cat /opt/ponymail/tools/ponymail.cfg
cat /opt/ponymail/site/api/lib/config.lua
cat /opt/ponymail/site/js/config.js | head -60

修改一律直接编辑对应文件（配置为明文键值/Lua 表，无编译步骤），随后按上文方式重载。核对生效值：

# 核对 ES JVM 堆生效值
ps -ef | grep [e]lasticsearch
# 核对 web 后端连的 ES 索引
curl -s http://127.0.0.1:9200/_cat/indices?v

四、参数总览

五、核心参数分类详解

5.1 归档器/导入器配置（tools/ponymail.cfg）

5.1.1 [elasticsearch] 段

[elasticsearch]
hostname:               localhost
dbname:                 ponymail
port:                   9200
ssl:                    false

#uri:                   url_prefix
#user:                  username
#password:              password
#write:                 consistency level (default quorum)
#backup:                database name

• hostname / port：ES 引擎地址。与 config.lua 的 es_url 必须指向同一实例，否则「归档进库但 web 查不到」。
• dbname：邮件索引名，默认 ponymail。索引由 setup.py 创建（分片/副本见 --dbshards/--dbreplicas）。
• ssl：访问 ES 是否启用 TLS，默认 false。
• uri：ES 的 URL 前缀（如反向代理路径），一般留空。
• user / password：ES 需要认证时填写（明文）。
• write：写入一致性级别，默认 quorum（单节点下按 quorum 语义即为 1）。
• backup：备用 ES 库名，archiver 写入失败时降级写入备份库。

⚠️ 该文件由 setup.py --defaults 生成后即为可用默认值，归档器不依赖交互输入。

5.1.2 [archiver] 段

[archiver]
generator:              cluster

• generator：文档 ID（mid）生成器，可选 legacy、medium、cluster、full：
  • legacy：0.1-0.8 时代的旧生成器（不推荐）；
  • medium：0.9 时代的综合生成器（不推荐）；
  • cluster：近全文 digest、丢弃 MTA 轨迹（推荐多节点/集群部署，实测默认值）；
  • full：完整消息 digest 含 MTA 轨迹（推荐单节点）。
• 该值同时决定去重口径：同一 Message-ID 重复投递时，相同生成器产生的 mid 一致，ES 覆盖写不会产生重复文档（实测重复 LMTP 投递 count 不再增加）。生成器变更后重新导入会产生重复。

5.1.3 [debug] 段

[debug]
#cropout:               string to crop from list-id

• cropout：对收到的 List-ID 做裁剪/正则替换，常用于把 foo.bar.incubator.apache.org 归并到 foo.bar.apache.org：

  [debug]
  cropout:  (\w+\.\w+)\.incubator\.apache\.org \1.apache.org
  

5.2 mod_lua 后端配置（site/api/lib/config.lua）

5.2.1 es_url

web 后端（各 site/api/*.lua）访问 ES 的完整前缀：

es_url = "http://localhost:9200/ponymail/",

格式为 http://<host>:<port>/<dbname>/。改库名或迁移 ES 时同步改这里。

5.2.2 mailserver 与 mailport

web 界面「回复邮件」功能的外发服务器：

mailserver = "localhost",
--  mailport = 1025, -- override the default port (25)

默认端口 25；测试环境可用 mailport = 1025 覆盖。

5.2.3 accepted_domains

允许通过 web 界面回复投递的域名白名单：

accepted_domains = "example.org",

• "*"：允许发到任意地址（不推荐）；
• "foo.org"：仅 *@foo.org；
• "*.foo.org"：仅子域（不含根域）；
• { "foo.org", "*.foo.org" }：根域与子域都允许。

5.2.4 wordcloud 与统计参数

wordcloud = true,
--  stats_maxBody = 200,     -- 正文统计片段最大长度
--  stats_wordExclude = ".|..|...",  -- 词云排除模式

• wordcloud：词云功能开关（实测默认 true）。内存紧张的机器可关掉。
• stats_maxBody：stats API 返回的正文片段最大长度，默认 200。
• stats_wordExclude：词云剔除的词模式（按 | 分隔）。

5.2.5 full_headers 与 maxResults

full_headers = false,
maxResults = 5000,

• full_headers：设为 true 时邮件视图显示 to/cc 等完整头（默认隐藏）。
• maxResults：单次 API 最多返回的邮件数，默认 5000；超大列表可上调。

5.2.6 认证与反垃圾

admin_oauth = {},
oauth_fields = { },
antispam = true

• admin_oauth：允许「管理级 OAuth」（可访问私有列表）的域名数组，如 { 'myoauth.foo.tld', '*.oauthprovider.com' }。
• oauth_fields：各 OAuth 提供方参数（如 GitHub 的 client_secret/client_id/oauth_token）。
• antispam：对匿名用户加反垃圾措施，默认 true。
• allow_insecure_cookie：测试环境可设为 true（默认 false，生产不要开）。
• email_footer：web 回复邮件页脚模板，支持 $list、$hostname、$port、$msgid 变量。

5.3 前端配置（site/js/config.js）

前端全局对象 pm_config（默认值 debug: false）：

var pm_config = {
    debug: false, // set to true for some debug output
    oauth: {
        // 默认注释掉的 apache/google/github 等 OAuth 提供方示例
    }
};

• debug：设为 true 输出前端调试信息。
• oauth：各 OAuth 提供方（name/oauth_portal/oauth_url/fullname_key/email_key/client_id 等）。启用时需与 config.lua 的 oauth_fields 配合。

5.4 Elasticsearch 服务参数

5.4.1 elasticsearch.yml

cluster.name: ponymail
node.name: ponymail-node-1
network.host: 127.0.0.1
http.port: 9200

• cluster.name：ES 集群名（Pony Mail 单集群部署建议固定）。
• node.name：节点名。
• network.host：监听地址。单机演示用 127.0.0.1；若 web/archiver 与 ES 分机部署则改为对外地址。
• http.port：REST 端口。

5.4.2 JVM 堆内存（256-512MB）

ES 2.4.6 通过 ES_HEAP_SIZE 同时设定 -Xms/-Xmx，在 systemd 单元中配置：

Environment=ES_HEAP_SIZE=256m

修改后重启并核对生效值：

systemctl restart elasticsearch
ps -ef | grep [e]lasticsearch

回显（节选）应包含：

-Xms256m -Xmx256m

💡 需要更大堆可改 ES_HEAP_SIZE=512m（仍落在 256-512MB 规范区间）。不要超过物理内存的一半，ES 还需留内存给 Lucene 页缓存。

5.5 Apache vhost 参数（/etc/apache2/sites-available/ponymail.conf）

Listen 8080
<VirtualHost *:8080>
    ServerName ponymail.localhost
    DocumentRoot /opt/ponymail/site
    LuaPackageCPath /usr/lib/x86_64-linux-gnu/lua/5.3/?.so
    LuaPackagePath  /usr/share/lua/5.3/?.lua
    AddHandler      lua-script .lua
    LuaScope        thread
    LuaCodeCache    stat
    AcceptPathInfo  On
    AddOutputFilterByType DEFLATE application/json
    <Directory /opt/ponymail/site>
        Require all granted
    </Directory>
</VirtualHost>

• Listen 8080：web 端口（默认 80 也可，本指南用 8080）。
• LuaPackageCPath / LuaPackagePath：Lua 5.3 模块搜索路径（cjson/socket 等 C 模块在 ?.so，纯 Lua 在 ?.lua）。
• AddHandler lua-script .lua：把 .lua 交给 mod_lua。
• LuaScope thread：Lua 虚拟机作用域（thread 级别，可换 server 加速）。
• LuaCodeCache stat：lua 文件按 stat 检测变化（改 config.lua 后 reload 即生效）。
• AcceptPathInfo On：支持带路径信息的 API 调用。
• <Directory>：DocumentRoot 不在 /var/www 时必须显式授权，否则 403。

六、生产配置模板

适用场景：16GB 内存、SSD 磁盘、单台服务器承载中小型组织邮件归档（数十个列表、日归档数百封），ES 与 Pony Mail 同机部署。

/opt/ponymail/tools/ponymail.cfg：

[elasticsearch]
hostname:               localhost
dbname:                 ponymail
port:                   9200
ssl:                    false
#user:                  esuser
#password:              q1w2e3r4

[archiver]
generator:              cluster

[debug]
#cropout:               (\w+\.\w+)\.incubator\.apache\.org \1.apache.org

/opt/ponymail/site/api/lib/config.lua：

local config = {
    es_url = "http://localhost:9200/ponymail/",
    mailserver = "localhost",
    accepted_domains = "example.org",
    wordcloud = true,
    email_footer = nil,
    full_headers = false,
    maxResults = 5000,
    admin_oauth = {},
    oauth_fields = {},
    antispam = true
}
return config

systemd 单元（ES）追加堆与副本建议：单机用 ES_HEAP_SIZE=256m；若列表量大可调 512m，并建议在 setup.py 初始化时用 --dbreplicas 1 增加副本（需 ≥2 个数据节点）。

💡 内存说明：ES 堆 256-512MB 足够支撑单机演示与中小规模归档；归档/查询压力大时优先横向扩展 ES 数据节点而非调大堆内存。

七、常见问题

7.1 改了 ponymail.cfg 不生效

解决：ponymail.cfg 在 archiver 进程启动时读取，需 systemctl restart ponymail-lmtpd（或让 MTA 重新调用 archiver.py）后生效。

7.2 改了 config.lua 不生效

解决：systemctl reload apache2（LuaCodeCache stat 下 reload 即感知文件变化）；若仍不生效检查文件是否有 Lua 语法错误（reload 后 curl /api/pminfo.lua 是否 200）。

7.3 web 查不到已归档邮件

解决：核对 config.lua 的 es_url 与 ponymail.cfg 的 hostname/port/dbname 是否指向同一 ES 索引；再用 curl http://127.0.0.1:9200/ponymail/mbox/_count 确认数据确实在库里。

7.4 词云接口慢/内存高

解决：wordcloud = false 关闭，或调小 stats_maxBody、调整 stats_wordExclude 过滤高频词。

7.5 私有列表看不到邮件

解决：私有列表由归档时 --private 标记（private: true）；web 端访问需配置 admin_oauth 并把域名加入，或自建 site/api/lib/aaa.lua 的权限判定。

八、参考链接

• Apache Pony Mail GitHub：https://github.com/apache/incubator-ponymail
• Apache Pony Mail 官方安装文档（docs/INSTALLING.md）：https://github.com/apache/incubator-ponymail/blob/master/docs/INSTALLING.md
• Apache Pony Mail 归档说明（docs/ARCHIVING.md）：https://github.com/apache/incubator-ponymail/blob/master/docs/ARCHIVING.md
• Elasticsearch 2.x 配置参考：https://www.elastic.co/guide/en/elasticsearch/reference/2.4/index.html