Apache James 配置参数详解

目标：详解 Apache James 3.9.1（james-server-jpa-guice 单机版）conf/ 目录下全部配置文件与参数，给出默认值、修改方式、生效条件与生产建议。文中命令与回显来自 Ubuntu 22.04.5 真实服务器实测。

一、环境信息

• 版本：Apache James 3.9.1（james-server-jpa-guice.zip，JPA+Guice 单机版）
• 配置目录：/opt/data/james/james-server-jpa-guice/conf/
• 数据目录：/opt/data/james/james-server-jpa-guice/var/
• 配置文件清单（实测 conf/ 目录）：smtpserver.xml、imapserver.xml、pop3server.xml、lmtpserver.xml、mailetcontainer.xml、domainlist.xml、usersrepository.xml、james-database.properties、james-database-mariadb.properties、jvm.properties、webadmin.properties、jmx.properties、logback.xml、dnsservice.xml、recipientrewritetable.xml、mailrepositorystore.xml、managesieveserver.xml、healthcheck.properties、extensions.properties、listeners.xml、jwt_publickey、droplists.properties
• 配置文件均为 XML/properties 文本，修改后需重启 James 生效

二、前置条件

• 已按《Ubuntu 22.04 安装 Apache James 3.9.1 指南》完成部署（JDK 21、发行包解压、keystore）。
• 拥有 conf/ 目录写权限（root 或文件属主）。
• 修改端口/监听类参数时确认对应端口未被占用。

三、参数查看与修改方式

3.1 查看当前配置

cd /opt/data/james/james-server-jpa-guice
cat conf/smtpserver.xml          # SMTP 配置
cat conf/imapserver.xml          # IMAP 配置
cat conf/webadmin.properties     # WebAdmin 配置
cat conf/james-database.properties

3.2 修改与生效流程

1. 用编辑器或 sed 修改对应文件。
2. 重启 James（以下命令按 JVM 进程精确停止）：

$JAVA_HOME/bin/jps -l | grep "james-server-jpa-app.jar" | awk '{print $1}' | xargs -r kill
sleep 5
cd /opt/data/james/james-server-jpa-guice
nohup $JAVA_HOME/bin/java -Xms256m -Xmx512m \
  -javaagent:james-server-jpa-app.lib/openjpa-4.1.1.jar \
  -Dworking.directory=. \
  -Djdk.tls.ephemeralDHKeySize=2048 \
  -Dlogback.configurationFile=conf/logback.xml \
  -jar james-server-jpa-app.jar > /var/log/james.log 2>&1 &

3. 通过日志与端口验证是否生效：

grep -E "Service bound|disabled by configuration" /var/log/james.log

⚠️ 注意：James 启动时会做配置校验（StartUpChecksPerformer - StartUpChecks all succeeded），配置非法会导致启动失败并回滚，因此修改后务必看日志确认。

四、参数总览

五、核心参数分类详解

5.1 协议服务段：smtpserver.xml

SMTP 服务段默认有 3 个 <smtpserver>：明文 25、SMTPS 465、STARTTLS 587。实测默认片段：

<smtpservers>
    <smtpserver enabled="true">
        <jmxName>smtpserver-global</jmxName>
        <bind>0.0.0.0:25</bind>
        <connectionBacklog>200</connectionBacklog>
        <tls socketTLS="false" startTLS="false">
            <keystore>file://conf/keystore</keystore>
            <keystoreType>PKCS12</keystoreType>
            <secret>james72laBalle</secret>
            <provider>org.bouncycastle.jce.provider.BouncyCastleProvider</provider>
            <algorithm>SunX509</algorithm>
        </tls>
        <connectiontimeout>360</connectiontimeout>
        <connectionLimit>0</connectionLimit>
        <connectionLimitPerIP>0</connectionLimitPerIP>
        <auth>
            <announce>never</announce>
            <requireSSL>false</requireSSL>
            <required>false</required>
            <plainAuthEnabled>true</plainAuthEnabled>
        </auth>
        <authorizedAddresses>127.0.0.0/8</authorizedAddresses>
        <verifyIdentity>true</verifyIdentity>
        <maxmessagesize>0</maxmessagesize>
        <smtpGreeting>Apache JAMES awesome SMTP Server</smtpGreeting>
        <handlerchain coreHandlersPackage="org.apache.james.smtpserver.NoAuthCmdHandlerLoader">
            <handler class="org.apache.james.smtpserver.fastfail.ValidRcptHandler"/>
        </handlerchain>
    </smtpserver>
    <!-- 另有 465（socketTLS=true）与 587（startTLS=true）两个 smtpserver 段，结构与上段一致 -->
</smtpservers>

关键参数说明：

• bind：监听地址与端口。端口受限时改高端口（如 <bind>0.0.0.0:2525</bind>）。
• tls socketTLS/startTLS：socketTLS="true" 为 465 隐式 TLS；startTLS="true" 为 587 STARTTLS。
• keystore/secret：TLS 密钥库路径与口令，必须与 keytool -storepass 一致（默认 james72laBalle）。
• auth.required/announce/plainAuthEnabled：SMTP 认证要求、宣告时机与是否允许明文认证（plain 默认 true）。
• authorizedAddresses：免认证中继白名单（默认 127.0.0.0/8 本机）。
• verifyIdentity：身份一致性校验（发件人与登录身份）。
• maxmessagesize：单封最大字节数，0 为不限（实测日志 No maximum message size is enforced）。

⚠️ 注意：开 SMTP 认证时，verifyIdentity=true 配合 auth.required=true 可防止开放中继（open relay）。

5.2 协议服务段：imapserver.xml 与 pop3server.xml

IMAP 默认两个服务（143 明文、993 TLS）。POP3 默认禁用（enabled="false"，监听 110），启用方法：

sed -i 's/<pop3server enabled="false">/<pop3server enabled="true">/' conf/pop3server.xml

POP3 默认片段关键项：

<pop3server enabled="true">
    <jmxName>pop3server</jmxName>
    <bind>0.0.0.0:110</bind>
    <connectiontimeout>1200</connectiontimeout>
    <connectionLimit>0</connectionLimit>
    <tls socketTLS="false" startTLS="false">
        <keystore>file://conf/keystore</keystore>
        <keystoreType>PKCS12</keystoreType>
        <secret>james72laBalle</secret>
    </tls>
</pop3server>

💡 说明：IMAP/POP3 的 TLS 参数与 SMTP 一致（keystore/keystoreType/secret）。IMAP 明文登录默认被禁用（LOGINDISABLED 能力），客户端需先 STARTTLS 再登录，可执行示例：python3 -c "import imaplib; c=imaplib.IMAP4('127.0.0.1',143); c.starttls(); print(c.login('root@example.com','q1w2e3r4'))"。

5.3 mailetcontainer.xml（邮件处理管道）

控制邮件从接收、校验、本地投递到远程转发的整条处理链。实测默认管道：

• context：<postmaster>postmaster</postmaster>（缺域时自动补默认域）。
• spooler：<threads>20</threads>、<errorRepository>file://var/mail/error/</errorRepository>。
• root 处理器：PostmasterAlias → RelayLimit=30 的 ToRepository → 转 transport。
• transport 处理器（核心）：
  • RecipientRewriteTable（地址重写表）
  • RecipientIsLocal → Sieve（Sieve 过滤脚本）
  • RecipientIsLocal → AddDeliveredToHeader
  • RecipientIsLocal → LocalDelivery（本地投递到收件人 INBOX）
  • HostIsLocal → local-address-error（不存在用户退信）
  • relay-allowed（SMTPAuthSuccessful/SMTPIsAuthNetwork/SentByMailet）→ relay
• relay 处理器：RemoteDelivery，<delayTime>5000, 100000, 500000</delayTime>、<maxRetries>3</maxRetries>、<deliveryThreads>10</deliveryThreads>、<sendpartial>true</sendpartial>。
• 错误处理：error 处理器（Bounce + 入库 var/mail/error/）、relay-denied、local-address-error、bounces。

💡 说明：RecipientIsLocal 与 LocalDelivery 是"域名本地投递"的关键 mailet；开放中继防护靠 relay-allowed 匹配器（需 SMTP 认证成功或来自认证网络）。实测本地投递日志：

SimpleMailStore - Local delivered mail Mail1791717294496-dTMuVcrXJWe2Y7zutpeg with messageId null successfully from root@example.com to <root@example.com> in folder [INBOX] with composedMessageId ComposedMessageId{mailboxId=1, messageId=DefaultMessageId{}, uid=MessageUid{uid=1}}

5.4 domainlist.xml 与 usersrepository.xml（域与用户）

domainlist.xml：

<domainlist>
    <autodetect>false</autodetect>
    <autodetectIP>false</autodetectIP>
    <defaultDomain>localhost</defaultDomain>
</domainlist>

• autodetect/autodetectIP：是否自动探测主机名/IP 加入域名表（默认 false）。
• defaultDomain：默认域（实测 localhost；WebAdmin 建域后为 example.com, localhost）。
• 域管理走 WebAdmin REST：PUT /domains/example.com 建域、GET /domains 列表、DELETE /domains/<name> 删除。

usersrepository.xml：

<usersrepository name="LocalUsers">
    <algorithm>PBKDF2-SHA512</algorithm>
    <enableVirtualHosting>true</enableVirtualHosting>
    <enableForwarding>true</enableForwarding>
</usersrepository>

• algorithm：口令哈希算法（默认 PBKDF2-SHA512）。
• enableVirtualHosting：是否启用多域名虚拟主机（true 时用户名带域，如 root@example.com）。
• enableForwarding：允许转发地址配置。

💡 说明：enableVirtualHosting=true 意味着登录名必须完整（root@example.com），这也是 POP3/IMAP 登录需要带域名的原因。

5.5 james-database.properties（数据库）

database.driverClassName=org.apache.derby.jdbc.EmbeddedDriver
database.url=jdbc:derby:../var/store/derby;create=true
database.username=app
database.password=app

• 默认内置 Derby 嵌入式数据库，库文件位于 var/store/derby。
• 发行包另带 james-database-mariadb.properties 模板（MariaDB/MySQL 场景），切换数据库需替换本文件并将驱动 jar 放入 classpath（官方 README 提供了 -cp "james-server-jpa-app.jar:james-server-jpa-app.lib/*:jdbc-driver.jar" 方式）。

⚠️ 注意：database.url 是相对 -Dworking.directory=. 的路径（../var/store/derby），不要随意改动目录结构，否则 Derby 找不到库会重建空库导致"用户消失"。

5.6 webadmin.properties（WebAdmin REST API）

实测关键项：

enabled=true
port=8000
host=localhost
https.enabled=false
password.generate=true   # 实测修改后为 false
password=q1w2e3r4        # 固定密码（示例）

• port/host：WebAdmin 监听地址（默认 localhost:8000；对外暴露建议改 0.0.0.0 并启用 HTTPS）。
• https.enabled/keystore：HTTPS 开关与密钥库。
• password.generate：true 时每次启动生成随机密码并写日志；false 时用 password 固定值。
• 认证方式：REST 请求带 Password 请求头，而非 Basic Auth。

5.7 jmx.properties（JMX，CLI 依赖）

jmx.enabled=true
jmx.address=127.0.0.1
jmx.port=9999

• jmx.port=9999：JMX RMI 端口，命令行工具 james-cli 通过它执行管理命令。
• 凭据：用户名 james-admin，密码每次启动自动生成（写入 conf/jmxremote.password，文件权限 600）。
• 安全项（jvm.properties 相关）：jmx.remote.x.mlet.allow.getMBeansFromURL=false 禁用 JMX 远程代码执行。

5.8 jvm.properties（JVM 系统属性与行为开关）

该文件在启动时以 -D 系统属性形式注入 JVM（不是堆内存参数）。实测默认关键项：

sun.rmi.dgc.server.gcInterval=3600000000
sun.rmi.dgc.client.gcInterval=3600000000
james.jmx.credential.generation=true
jmx.remote.x.mlet.allow.getMBeansFromURL=false
openjpa.Multithreaded=true

常用可选（注释态）：

5.9 JVM 堆内存参数（重点）

James 为 Java 进程，堆内存由启动命令行 -Xms/-Xmx 控制（不在 jvm.properties 中）。推荐限制在 256–512MB：

java -Xms256m -Xmx512m \
  -javaagent:james-server-jpa-app.lib/openjpa-4.1.1.jar \
  -Dworking.directory=. \
  -Djdk.tls.ephemeralDHKeySize=2048 \
  -Dlogback.configurationFile=conf/logback.xml \
  -jar james-server-jpa-app.jar

• -Xms256m：初始堆 256MB；-Xmx512m：最大堆 512MB（也可 -Xms256m -Xmx256m 固定）。
• 修改方式：直接编辑启动脚本/启动命令行中对应参数后重启。
• 生效验证：

$JAVA_HOME/bin/jps -v | grep james-server

实测回显（可见 -Xms256m -Xmx512m 生效）：

7577 james-server-jpa-app.jar -Xms256m -Xmx512m -javaagent:james-server-jpa-app.lib/openjpa-4.1.1.jar -Dworking.directory=. -Djdk.tls.ephemeralDHKeySize=2048 -Dlogback.configurationFile=conf/logback.xml

⚠️ 注意：若以 systemd 托管，用 Environment=JAVA_TOOL_OPTIONS=-Xms256m -Xmx512m 注入（每行仅一个单元）；Docker Compose 用 environment: JAVA_TOOL_OPTIONS: "-Xms256m -Xmx512m"。极端场景（如启用了 -XX:+UseContainerSupport）可用 jcmd <pid> VM.flags 复核实际生效堆上限。

5.10 logback.xml（日志）

• 默认输出到标准输出 + 滚动文件（var/log/ 或 -Dlogback.configurationFile=conf/logback.xml 指定）。
• 可调 level（DEBUG/INFO/WARN/ERROR）。实测启动时大量 DEBUG org.eclipse.jetty.jndi.* 输出来自 CLI 客户端侧，服务端日志级别默认 INFO。

六、生产配置模板

适用场景：16GB 内存、SSD 磁盘、单机中小型邮件服务器（≤2000 用户）。

# jvm.properties（取消注释并按需调整）
james.message.memory.threshold=12K
james.exit.on.startup.error=true
james.fail.on.missing.configuration=true

# webadmin.properties（内网管理）
enabled=true
port=8000
host=0.0.0.0
password.generate=false
password=q1w2e3r4

# jmx.properties
jmx.enabled=true
jmx.address=127.0.0.1
jmx.port=9999

<!-- smtpserver.xml 关键调整：开认证、限制邮件大小、启 STARTTLS -->
<auth>
    <announce>always</announce>
    <requireSSL>false</requireSSL>
    <required>true</required>
    <plainAuthEnabled>true</plainAuthEnabled>
</auth>
<maxmessagesize>26214400</maxmessagesize>   <!-- 25MB -->

# 启动命令（堆 256-512MB）
java -Xms256m -Xmx512m \
  -javaagent:james-server-jpa-app.lib/openjpa-4.1.1.jar \
  -Dworking.directory=. \
  -Djdk.tls.ephemeralDHKeySize=2048 \
  -Dlogback.configurationFile=conf/logback.xml \
  -jar james-server-jpa-app.jar

💡 说明：低内存服务器（4GB）建议 -Xms256m -Xmx256m；同时将 james.message.memory.threshold 调低以控制堆内驻留邮件内容。

七、常见问题（FAQ）

Q1：改了端口为什么不生效？ 修改 smtpserver.xml/imapserver.xml/pop3server.xml 后必须重启 James；确认新端口无占用，且 <bind> 语法为 0.0.0.0:PORT。

Q2：POP3 110 端口没监听？ pop3server.xml 默认 enabled="false"，改为 true 后重启（见 5.2）。

Q3：jvm.properties 里写 -Xmx512m 不生效？ jvm.properties 只注入 -D 系统属性，堆参数须在启动命令/环境变量里设置（见 5.9）。

Q4：重启后用户/域名全没了？ database.url 指向 ../var/store/derby，若删除或移动了 var/ 目录则重建空库；保持 var/ 持久化并在固定目录启动。

Q5：WebAdmin 登录一直 401？ 确认 password.generate=false 且 password= 已固定（见 5.6），请求带 Password 头；或从启动日志取随机密码。

Q6：IMAP 明文登录被拒？ 安全默认 LOGINDISABLED，客户端先 STARTTLS（可执行示例见 5.2 说明）；确需明文需调整 IMAP TLS 与认证策略。

八、参考链接

• James 配置总览：https://james.apache.org/server/config.html
• SMTP/LMTP 配置：https://james.apache.org/server/config-smtp-lmtp.html
• mailetcontainer 配置：https://james.apache.org/server/config-mailetcontainer.html
• WebAdmin 配置：https://james.apache.org/server/config-webadmin.html
• 系统/JMX 配置：https://james.apache.org/server/config-system.html