SimpleLogin 4.83.1 配置参数详解

目标：讲清 SimpleLogin 4.83.1 自托管的配置体系——.env 配置文件与 app/config.py 的加载关系、查看与修改参数的正确流程，并按站点域名、事务邮件、认证安全、别名扩展、邮件链路、存储管理六大类逐项解析核心参数，其中关键开关均给出「修改 → 重启 → 验证」的实测闭环。已在 Ubuntu 22.04 + SimpleLogin 4.83.1 环境实测。

一、环境信息

• SimpleLogin：4.83.1（2026-10-21 发布，app/config.py 共 201 个参数定义，grep -cE "^[A-Z_]+ ?=" app/config.py 实查）
• 配置文件：simplelogin.env（部署篇路径 /opt/simplelogin/sl/simplelogin.env，挂载为应用内 /code/.env）
• 实测部署形态：PostgreSQL 12.1 + Postfix 中继 + SimpleLogin 三角色（api/email/jobrunner），见站内部署指南
• 实测演示域：sltest.dev（别名域）、mailtest.dev（真实收件域）、customtest.dev（自定义域）
• 演示账号：admin@mailtest.dev / q1w2e3r4

二、前置条件

1. 已按部署指南完成 SimpleLogin 4.83.1 的部署与迁移（alembic current 输出 b7e2d4a9c1f3 (head)）；
2. 三个应用角色（api/email/jobrunner）共用同一份 .env，修改参数前先备份：

cd /opt/simplelogin/sl
cp simplelogin.env simplelogin.env.bak.$(date +%F)
head -3 simplelogin.env

# SimpleLogin v4.83.1 自托管配置（闭环实验：sltest.dev / mailtest.dev / customtest.dev）
# WebApp URL
URL=http://sltest.dev:8135

三、参数查看与修改方式

3.1 加载机制

SimpleLogin 在进程启动时通过 python-dotenv 读取 /code/.env，随后 app/config.py 按三种方式消费环境变量（源码实查）：

• 必需项：os.environ["URL"] 写法，缺失即启动失败（URL、EMAIL_DOMAIN、SUPPORT_EMAIL、DB_URI、FLASK_SECRET 等）；
• 开关项："DISABLE_REGISTRATION" in os.environ 写法，出现即生效、无需值（DISABLE_REGISTRATION、DISABLE_ALIAS_SUFFIX、LOCAL_FILE_UPLOAD、DISABLE_ONBOARDING、ENFORCE_SPF、RSPAMD_SIGN_DKIM 等）；
• 带默认值项：os.environ.get("SUPPORT_NAME", "Son from SimpleLogin") 写法（SUPPORT_NAME、ADMIN_EMAIL、FIRST_ALIAS_DOMAIN、NOREPLY 等）。

因此改配置 = 改 .env + 重启所有应用角色；仅重启 api 而不重启 email/jobrunner 会导致三个角色读到不同配置，产生「注册页行为与收信行为不一致」这类疑难杂症。

3.2 查看当前生效值

应用内直接导入 config 即可打印实际生效值（实测输出）：

cd /opt/simplelogin/sl
docker compose exec api python -c "
from app.config import URL, EMAIL_DOMAIN, SUPPORT_EMAIL, SUPPORT_NAME, NAMESERVERS, DISABLE_ALIAS_SUFFIX, DISABLE_ONBOARDING, LOCAL_FILE_UPLOAD
print('URL =', URL)
print('EMAIL_DOMAIN =', EMAIL_DOMAIN)
print('SUPPORT_EMAIL =', SUPPORT_EMAIL)
print('SUPPORT_NAME =', SUPPORT_NAME)
print('NAMESERVERS =', NAMESERVERS)
print('DISABLE_ALIAS_SUFFIX =', DISABLE_ALIAS_SUFFIX)
print('DISABLE_ONBOARDING =', DISABLE_ONBOARDING)
print('LOCAL_FILE_UPLOAD =', LOCAL_FILE_UPLOAD)
"

URL = http://sltest.dev:8135
EMAIL_DOMAIN = sltest.dev
SUPPORT_EMAIL = support@sltest.dev
SUPPORT_NAME = SimpleLogin Support
NAMESERVERS = ['10.89.63.53']
DISABLE_ALIAS_SUFFIX = True
DISABLE_ONBOARDING = True
LOCAL_FILE_UPLOAD = True

全量参数定义可在应用运行环境内直接检索：

docker compose exec api grep -nE "^[A-Z_]+ ?=" /code/app/config.py | head -8

20:URL = os.environ["URL"]
22:SUPPORT_EMAIL = os.environ["SUPPORT_EMAIL"]
23:SUPPORT_NAME = os.environ.get("SUPPORT_NAME", "Son from SimpleLogin")
25:USE_PROXY_PROTOCOL = "USE_PROXY_PROTOCOL" in os.environ
27:NOT_SEND_EMAIL = "NOT_SEND_EMAIL" in os.environ
29:EMAIL_DOMAIN = os.environ["EMAIL_DOMAIN"].lower()
30:SUPPORT_NAME = os.environ.get("SUPPORT_NAME", "Son from SimpleLogin")
31:EMAIL_SERVERS_WITH_PRIORITY = sl_getenv("EMAIL_SERVERS_WITH_PRIORITY")

💡 说明：行号与条目以 4.83.1 源码为准，升级版本后建议先重跑该命令核对参数名变化。

3.3 修改流程（标准三步）

1. 编辑 .env 修改参数；
2. 重启全部应用角色：docker compose restart api email jobrunner；
3. 按 3.2 节命令核对生效值，再对该参数做一次业务级验证（本文第五章给出各项的验证命令）。

四、参数总览

SimpleLogin 4.83.1 自托管常用参数一览（默认值列标注「开关」者出现即生效）：

五、核心参数分类详解

5.1 站点与域名（URL / EMAIL_DOMAIN / FIRST_ALIAS_DOMAIN）

URL 决定激活链接、密码重置链接的域名与端口。实测 URL=http://sltest.dev:8135 时，注册激活邮件中的链接为 http://sltest.dev:8135/auth/activate?code=bmpyiuvmqwbnxzympdgwaqoldyhavf（激活邮件实测留存）；生产若前面有反向代理，URL 要写成公网协议+域名+端口三元组，错一个端口链接就不可点。

EMAIL_DOMAIN 是别名后缀域，同时被三处引用：随机/自定义别名的后缀、DKIM 签名域（d=sltest.dev）、事务邮件 noreply 域。修改它等于换整个别名体系，已有别名全部失效，务必一次性定好。

FIRST_ALIAS_DOMAIN 用于注册后默认选中的别名域；配置了多个别名域（配合 ALIAS_DOMAINS）时把最常用域设为首选。

验证命令（别名域应出现在仪表盘与 API 的可创建列表中）：

docker compose exec api python -c "
from app.config import ALIAS_DOMAINS, FIRST_ALIAS_DOMAIN
print('ALIAS_DOMAINS =', ALIAS_DOMAINS)
print('FIRST_ALIAS_DOMAIN =', FIRST_ALIAS_DOMAIN)
"

ALIAS_DOMAINS = ['sltest.dev']
FIRST_ALIAS_DOMAIN = sltest.dev

5.2 事务邮件与发件人（SUPPORT_EMAIL / SUPPORT_NAME / NOREPLY）

一个易混淆点（实测澄清）：SUPPORT_EMAIL 不是事务邮件的发件人。4.83.1 的事务邮件发件人由 NOREPLY 控制，默认按 EMAIL_DOMAIN 拼接（源码 app/email_utils.py:466 实查）：

NOREPLY = os.environ.get("NOREPLY", f'"SimpleLogin (noreply)" <noreply@{EMAIL_DOMAIN}>')

实测注册激活邮件的真实抬头：

Subject: Just one more step to join SimpleLogin
From: "SimpleLogin (noreply)" <noreply@sltest.dev>
To: admin@mailtest.dev

SUPPORT_EMAIL 的实际用途是站点界面上的支持/联系邮箱展示。若想让事务邮件以支持身份发出，显式配置 NOREPLY="SimpleLogin Support" <support@sltest.dev> 即可（该地址域必须已配 SPF/DKIM，否则退信率升高）。

5.3 认证与安全（FLASK_SECRET / DISABLE_REGISTRATION / ADMIN_EMAIL / GNUPGHOME）

FLASK_SECRET 是 Flask 会话签名密钥，更换后所有已登录会话失效。生产必须用独立随机串：openssl rand -hex 32。

DISABLE_REGISTRATION 为开关项，配置后注册页直接跳转登录页。实测闭环：

echo 'DISABLE_REGISTRATION=1' >> simplelogin.env
docker compose restart api email jobrunner
curl -s -o /dev/null -w 'redirect: %{redirect_url}\n' http://127.0.0.1:8135/auth/register
curl -s -L http://127.0.0.1:8135/auth/register | grep -o -E 'closed[^<"]{0,20}' | head -1

redirect: http://127.0.0.1:8135/auth/login
closed

/auth/register 返回 302 指向登录页，页面出现 "closed" 提示，开关生效。移除该行并再次重启后实测恢复：

sed -i '/^DISABLE_REGISTRATION=1$/d' simplelogin.env
docker compose restart api email jobrunner
curl -s -o /dev/null -w 'register-after-restore: %{http_code}\n' http://127.0.0.1:8135/auth/register

register-after-restore: 200

ADMIN_EMAIL 指定可访问 /admin 管理面板的账号；注意该邮箱必须是已注册用户，先注册该邮箱账号再配置才生效。

GNUPGHOME 指向 PGP 密钥环目录，目录必须预先存在（迁移与运行都依赖，详见第七章 FAQ 3）。

5.4 别名行为（DISABLE_ALIAS_SUFFIX / ALIAS_DOMAINS）

DISABLE_ALIAS_SUFFIX 开启后随机别名不再追加 .{随机词} 后缀（官方默认形如 xxx.random_word@域）。实测开启后通过 API 创建的随机别名为 aversion_raffle827@sltest.dev（无附加后缀段）。

ALIAS_DOMAINS 扩充可用别名域（逗号分隔多个域），所有域都需把 MX 指向本栈中继。验证方式同 5.1 节命令。

5.5 邮件链路与 DNS（DKIM_PRIVATE_KEY_PATH / POSTFIX_SERVER / NAMESERVERS / ENFORCE_SPF / RSPAMD_SIGN_DKIM）

DKIM_PRIVATE_KEY_PATH 指向应用侧签名私钥，必须是 PKCS#1 格式（-----BEGIN RSA PRIVATE KEY-----）。生成命令（OpenSSL 3.x 必须加 -traditional）：

openssl genrsa -out dkim.key 1024
openssl rsa -in dkim.key -out dkim.key -traditional
openssl rsa -in dkim.key -pubout -out dkim.pub.key
head -1 dkim.key

-----BEGIN RSA PRIVATE KEY-----

若误用默认 PKCS#8 输出，外发邮件会全部因 UnparsableKeyError 被阻断（原因与修复见第七章 FAQ 2）。

POSTFIX_SERVER 是外发中继主机名（本栈为 mail）。验证应用能连上中继并发信的最小回路：注册新用户触发激活邮件，观察 Postfix 日志出现 status=sent (delivered to maildir) 即链路通畅（实测已验证）。

NAMESERVERS 决定域名校验流量走哪台 DNS（所有权 TXT/MX/SPF/DKIM CNAME 四项校验都用它）。实测指向栈内 CoreDNS 10.89.63.53 时，四项校验全部通过；生产环境建议指向公共解析器或本机递归服务。

ENFORCE_SPF 开启后收信阶段强制校验发件域 SPF，不达标拒收；自托管面向公网时建议开启，实验环境因内网闭环未开启。

RSPAMD_SIGN_DKIM 开启后签名责任移交 Rspamd milter，应用不再自带签名；与默认方案二选一，同时开启会双重签名。

5.6 存储与管理（LOCAL_FILE_UPLOAD / DB_URI）

LOCAL_FILE_UPLOAD 开启后用户上传附件存本地 /code/static/upload；未开启则需配置 S3 系列参数（S3_ENDPOINT 等），小规模自托管建议开启并纳入备份。

DB_URI 是唯一数据持久化入口，格式 postgresql://用户:密码@主机:端口/库名；主机名在 Compose 内为服务名 db。修改后必须重启三角色，且建议先验证连通：

docker compose exec db psql -U sluser -d simplelogin -tAc 'SELECT count(*) FROM information_schema.tables WHERE table_schema='"'"'public'"'"';'

81

六、生产配置模板

以下为生产环境推荐的 .env 模板（标注每个与实验环境的差异点），域名以 sl.example.com 为例：

# 站点：公网 HTTPS 入口（差异点：实验用 8135 明文端口，生产走反向代理 443）
URL=https://sl.example.com

# 别名域：生产可配置多个（差异点：ALIAS_DOMAINS 扩充，实验仅单域）
EMAIL_DOMAIN=sl.example.com
ALIAS_DOMAINS=sl.example.com

# 事务邮件发件人与支持联系人（差异点：显式 NOREPLY，避免 noreply@ 域未配 SPF）
SUPPORT_EMAIL=support@sl.example.com
SUPPORT_NAME=IT Support
NOREPLY="IT Support" <noreply@sl.example.com>

# 自定义域校验基准 MX（差异点：真实公网 MX）
EMAIL_SERVERS_WITH_PRIORITY=[(10, "mail.sl.example.com.")]

# 别名行为
DISABLE_ALIAS_SUFFIX=1

# DKIM：私钥必须 PKCS#1 格式
DKIM_PRIVATE_KEY_PATH=/dkim.key

# 数据库与密钥（差异点：强密码 + 独立随机 FLASK_SECRET）
DB_URI=postgresql://sluser:<strong-password>@db:5432/simplelogin
FLASK_SECRET=<openssl rand -hex 32 生成>
GNUPGHOME=/sl/pgp

# 存储
LOCAL_FILE_UPLOAD=1

# 外发中继与 DNS（差异点：NAMESERVERS 指向公共递归，实验指向栈内 CoreDNS）
POSTFIX_SERVER=mail
NAMESERVERS=1.1.1.1

# 运营开关
DISABLE_ONBOARDING=true
ADMIN_EMAIL=admin@sl.example.com
# DISABLE_REGISTRATION=1   # 如需关闭自助注册再打开

💡 说明：模板中 <strong-password>、<openssl rand -hex 32 生成> 为取值方法占位——分别用强口令生成器与 openssl rand -hex 32 的实际输出替换，其余参数可直接使用。

七、常见问题（FAQ）

Q1：修改了 .env 但行为没变化。 三个应用角色只在启动时读一次 .env。执行 docker compose restart api email jobrunner 全量重启后再验证；只重启 api 会导致 email/jobrunner 仍用旧值。

Q2：事务邮件发不出去，日志报 dkim.crypto.UnparsableKeyError: Unparsable private key: Unexpected tag (got 30, expecting 02)。 DKIM 私钥是 OpenSSL 3.x 默认的 PKCS#8 格式，签名库只认 PKCS#1。执行 openssl rsa -in dkim.key -out dkim.key -traditional 转换（首行应变为 BEGIN RSA PRIVATE KEY），重启 api/email 后生效。注意签名失败会阻断全部外发邮件，包括激活邮件。

Q3：alembic upgrade head 报 FileNotFoundError: [Errno 2] No such file or directory: '/sl/pgp'。 GNUPGHOME 目录不存在。先 mkdir -p /opt/simplelogin/sl/pgp 再执行迁移或启动。

Q4：配置了 ADMIN_EMAIL 但 /admin 提示无权限。 ADMIN_EMAIL 对应的邮箱必须已经是注册用户。先注册该邮箱（或由已有管理员在面板创建），重启 api 后生效。

Q5：自定义域校验一直失败，但 DNS 记录看似正确。 按顺序排查三点：NAMESERVERS 是否指向能解析该域的服务器（校验流量走它）；MX 记录是否与 EMAIL_SERVERS_WITH_PRIORITY 的主机名完全一致（优先级数字可以不同）；DKIM 是否按要求配置了 dkim/dkim02/dkim03 三条 CNAME 而非 TXT（详见部署指南 FAQ）。

八、参考链接

• 官方配置源码：https://github.com/simple-login/app/blob/master/app/config.py
• 官方示例配置：https://github.com/simple-login/app/blob/master/example.env
• 官方仓库与自托管文档：https://github.com/simple-login/app
• 站内部署指南（配置文件如何挂载与生效）：https://www.quzuo.net/document/tORMRsffUIa3