listmonk 如何用 LISTMONK_ 环境变量代替 config.toml 启动（含 --config=““ 用法）-编程实验室

listmonk 如何用 LISTMONK_ 环境变量代替 config.toml 启动（含 --config="" 用法）

【免费下载链接】listmonkHigh performance, self-hosted, newsletter and mailing list manager with a modern dashboard. Single binary app.项目地址: https://gitcode.com/GitHub_Trending/li/listmonk

listmonk 默认通过--config config.toml读取 TOML 配置文件，但它也支持完全不用配置文件启动：把 config.toml 中定义的配置项改写为带LISTMONK_前缀的环境变量，并给--config传空值。官方docker-compose.yml就是按这种方式工作的。本文以二进制 + Postgres 数据库为例，说明如何用环境变量启动 listmonk，以及--config=""的确切用法、验证方式和LISTMONK_*_FILE变体。

前提条件

按安装文档的要求，环境需要满足：

已下载 listmonk 二进制（amd64版本适用于 Intel 和 x86 CPU），或准备使用 Docker 镜像listmonk/listmonk:latest；
一个 Postgres 数据库实例（文档要求版本 ⩾ 12），数据库listmonk已创建；
首次启动时需要完成数据库安装（--install）和管理员用户创建。

环境变量命名规则

配置文档的规则是：

变量名加LISTMONK_前缀；
TOML 中的点（.）替换为双下划线__，表示嵌套配置。

config.toml.sample 与对应环境变量的对照：

TOML 配置项	环境变量	示例值
`app.address`	`LISTMONK_app__address`	`0.0.0.0:9000`
`db.host`	`LISTMONK_db__host`	`db`
`db.port`	`LISTMONK_db__port`	`5432`
`db.user`	`LISTMONK_db__user`	`listmonk`
`db.password`	`LISTMONK_db__password`	`listmonk`
`db.database`	`LISTMONK_db__database`	`listmonk`
`db.ssl_mode`	`LISTMONK_db__ssl_mode`	`disable`
`db.max_open`/`db.max_idle`/`db.max_lifetime`	`LISTMONK_db__max_open`/`LISTMONK_db__max_idle`/`LISTMONK_db__max_lifetime`	`25`/`25`/`300s`

此外还有两个不带__的专用变量：LISTMONK_ADMIN_USER和LISTMONK_ADMIN_PASSWORD。在安装文档的 Tip 中说明：安装时设置这两个变量会自动创建 Super Admin 用户；否则在首次访问http://localhost:9000后通过 Web 界面创建。cmd/install.go 中有对应的长度校验：LISTMONK_ADMIN_USER至少 3 个字符，LISTMONK_ADMIN_PASSWORD至少 8 个字符。

用环境变量启动（--config=""）

配置加载逻辑在 cmd/main.go：先读取--config指定的文件（可传多个，按顺序合并），再加载环境变量并合并进已加载的配置。cmd/init.go 中--config的默认值是config.toml，如果文件不存在会直接报错退出并提示先用--new-config生成——所以纯环境变量启动必须显式给--config传空字符串，否则进程会去找当前目录下的config.toml而失败。

配置文档给出的原话是：

To start listmonk purely with environment variables without a configuration file, set the environment variables and pass the config flag as--config="".

二进制方式

数据库连接配置全部通过环境变量传入，--config=""表示不读任何配置文件：

LISTMONK_app__address="0.0.0.0:9000" \ LISTMONK_db__host=localhost \ LISTMONK_db__port=5432 \ LISTMONK_db__user=listmonk \ LISTMONK_db__password=listmonk \ LISTMONK_db__database=listmonk \ LISTMONK_db__ssl_mode=disable \ LISTMONK_ADMIN_USER=myuser \ LISTMONK_ADMIN_PASSWORD=xxxxx \ ./listmonk --install --config=""

--install用于在空数据库上安装表结构（安装文档步骤 3）。确认数据库安装成功后，用同样的环境变量运行不带--install的启动命令：

LISTMONK_app__address="0.0.0.0:9000" \ LISTMONK_db__host=localhost \ LISTMONK_db__port=5432 \ LISTMONK_db__user=listmonk \ LISTMONK_db__password=listmonk \ LISTMONK_db__database=listmonk \ LISTMONK_db__ssl_mode=disable \ ./listmonk --config=""

上面的myuser/xxxxx是安装文档示例中的占位值，替换为你自己的管理员账号密码，且满足最小长度要求。

Docker 方式

仓库自带的 docker-compose.yml 就是"纯环境变量"启动的完整参考实现，关键片段：

command: [sh, -c, "./listmonk --install --idempotent --yes --config '' && ./listmonk --upgrade --yes --config '' && ./listmonk --config ''"] # --config (file) param is set to empty so that listmonk only uses the env vars (below) for config.

注释解释了三个要点：

--config设为空，listmonk 只使用下面environment:中的环境变量；
--install --idempotent保证--install只在首次启动（空数据库）时真正执行；
--upgrade在拉取新镜像后自动运行数据库迁移。

环境变量部分（省略 YAML 锚点，完整版本见仓库文件）：

environment: LISTMONK_app__address: 0.0.0.0:9000 LISTMONK_db__user: *db-user LISTMONK_db__password: *db-password LISTMONK_db__database: *db-name LISTMONK_db__host: db LISTMONK_db__port: 5432 LISTMONK_db__ssl_mode: disable LISTMONK_db__max_open: 25 LISTMONK_db__max_idle: 25 LISTMONK_db__max_lifetime: 300s TZ: Etc/UTC LISTMONK_ADMIN_USER: ${LISTMONK_ADMIN_USER:-} LISTMONK_ADMIN_PASSWORD: ${LISTMONK_ADMIN_PASSWORD:-}

按安装文档执行：

curl -LO https://github.com/knadh/listmonk/raw/master/docker-compose.yml docker compose up -d

如需在安装时直接创建 Super Admin，可在首次docker compose up前设置LISTMONK_ADMIN_USER和LISTMONK_ADMIN_PASSWORD。

验证启动是否成功

访问http://localhost:9000：能看到登录页即表示 Web 服务已按LISTMONK_app__address指定的地址监听；尚未创建管理员时，进入界面创建 Super Admin 用户即可登录。
查看容器日志确认安装、升级和启动三步都完成：

sudo docker logs -f sudo docker logs listmonk_app -t

以上docker logs命令来自 configuration.md 的 Logs 章节。如果日志中出现config file not found类错误，通常说明--config没有传空、进程去找了不存在的config.toml。

可选：用 LISTMONK_*_FILE 从文件加载密钥

Dockerfile 的入口脚本支持一种扩展形式：所有LISTMONK_*变量都可以换成LISTMONK_*_FILE指向一个文件，容器启动时读取文件内容并赋值给去掉_FILE后缀的变量。例如：

# LISTMONK_DB_USER_FILE=/run/secrets/user -> LISTMONK_DB_USER=（/run/secrets/user 文件的内容）

docker-compose.yml头部注释给出同样的示例：LISTMONK_ADMIN_USER->LISTMONK_ADMIN_USER_FILE=/path/to/file_with_value。该机制用于配合 Docker secrets 和 Podman 管理敏感值，仅在容器入口脚本会执行load_secret_files的路径下生效。

边界与限制

不是所有配置都能走环境变量：配置文档说明"少数底层配置变量和数据库配置"除外，其余设置都可以在管理后台的Settings面板中管理，也就是说数据库连接（db.*）恰恰是启动前必须通过文件或环境变量给定的部分。
--config默认值是config.toml（cmd/init.go），多个文件可重复传--config按顺序合并；--config=""传空串后则完全不读文件，此时LISTMONK_环境变量成为数据库配置的唯一来源。
环境变量与 TOML 的键名转换是固定的：__变.；文档示例中LISTMONK_app__address的值带引号写法"0.0.0.0:9000"，Docker compose 中则直接写0.0.0.0:9000，两种形式来自文档本身，按你的启动方式选用。
安装、升级、启动三段命令都需要相同的数据库环境变量，遗漏任何一步的--config ''都会使该步尝试读取config.toml并在文件缺失时退出。