listmonk 安装部署完全指南二进制、Docker Compose 与源码编译实战【免费下载链接】listmonkHigh performance, self-hosted, newsletter and mailing list manager with a modern dashboard. Single binary app.项目地址: https://gitcode.com/GitHub_Trending/li/listmonklistmonk 是一款高性能、自托管的开源新闻邮件与邮件列表管理器核心是一个依赖 Postgres 数据库的单一二进制应用。本文基于官方安装文档结合仓库源码逐条拆解二进制直装、Docker Compose 容器化、自定义config.toml挂载、nightly 尝鲜、源码编译及 Kubernetes Helm 部署等全路径安装方案读完你即可根据生产环境规模选择最合适的部署方式并理解每一步背后的实现原理。安装前置认知单一二进制 Postgreslistmonk 的部署模型非常简单一个可执行文件 一个 Postgres≥ 12实例。官方安装文档开篇即点明这一点——二进制可以直接手动下载运行也可以放进容器里用 Docker Compose 编排。从仓库源码看这种单二进制设计并非把静态资源丢掉而是反向做了资源内嵌stuffing在 Makefile 的dist目标中通过 stuffbin 把config.toml.sample、schema.sql、queries/下的全部 SQL 查询、permissions.json、static/public、static/email-templates、前端构建产物frontend/dist映射为/admin以及i18n/语言包一并打包进可执行文件见 Makefile 的STATIC变量与pack-bin目标。而 cmd/init.go 的initFS()在运行时优先从内嵌文件系统读取资源读取失败时才回退到本地磁盘目录。这意味着下载单个二进制后不需要单独部署前端或静态文件服务器管理后台、公开订阅页、邮件模板全部随二进制提供生产环境唯一必须准备的外部依赖是 Postgres 数据库。方式一二进制直接安装这是最轻量的部署方式适合单机 VPS 或内网服务器官方推荐步骤如下下载最新 release并解压出listmonk二进制。amd64是主力构建产物兼容 Intel 与 x86 架构 CPU。运行./listmonk --new-config生成config.toml然后按需编辑。运行./listmonk --install在 Postgres≥ 12中创建全部数据表。运行./listmonk浏览器访问http://localhost:9000创建 Super Admin 用户并登录。关键命令行参数解析从 cmd/init.go 的initFlags()可以看到上述命令对应的真实 flag 定义理解它们能帮你避免踩坑Flag说明--config path配置文件路径可传多个按顺序合并默认config.toml--install首次初始化数据库建表、写 schema、插入示例数据--idempotent让--install仅在数据库尚未初始化时执行重复运行安全--upgrade将数据库升级到当前版本执行增量迁移--new-config在--config指定路径生成示例配置文件--version打印当前构建版本--yes在--install/--upgrade交互提示时自动回答 yes--passive被动模式不处理任何 campaign--static-dir/--i18n-dir可选指定磁盘上的静态资源 / 语言包目录用于覆盖内嵌资源结合 cmd/install.go 的实现可以还原--install的完整动作执行schema.sql建表 → 记录当前迁移版本 → 创建 Default list单重确认、私有与 Opt-in list双重确认、公开两个示例列表 → 插入 John/Anon 两个示例订阅者 → 创建默认 campaign 模板、存档模板、示例事务模板与可视化模板 → 创建一条 Test campaign 示例邮件 → 可选创建超级管理员。这也是为什么安装完成后你能立刻在后台看到一堆可操作的示例数据。安装期预置管理员账号官方文档给出了一个实用技巧安装时通过环境变量直接预置 Super Admin 的用户名和密码省去首次访问网页时的交互创建LISTMONK_ADMIN_USERmyuser LISTMONK_ADMIN_PASSWORDxxxxx ./listmonk --install源码中的校验逻辑见 cmd/install.go为用户名最少 3 个字符、密码最少 8 个字符否则直接Fatal退出。另外还支持LISTMONK_ADMIN_API_USER环境变量创建一个 API 用户生成 32 位随机 API token 并打印到 stderr形如export LISTMONK_ADMIN_API_TOKEN...见 cmd/install.go但 API 用户必须与管理员账号同时设置才有效。建议同时生成连接池参数--new-config生成的配置来自仓库根目录的 config.toml.sample最小可用配置如下[app] # 服务监听地址。默认 localhost:9000 只接受本机连接 # 对外提供服务需改为 0.0.0.0使用 80 端口需要 root 权限。 address localhost:9000 # 数据库连接。 [db] host localhost port 5432 user listmonk password listmonk database listmonk # 需提前在 Postgres 中创建该库 ssl_mode disable max_open 25 max_idle 25 max_lifetime 300s # 可选额外空格分隔的 Postgres DSN 参数。 # 例如 application_namelistmonk gssencmodedisable params cmd/init.go 的initDB()展示了这些字段如何被组装成 Postgres DSNhost/port/user/password/dbname/sslmode按非空值拼接params原样附加随后用db.SetMaxOpenConns/SetMaxIdleConns/SetConnMaxLifetime应用连接池上限。注意database字段不会自动建库你需要先用createdb listmonk或等价命令把数据库建好。方式二Docker Compose 容器化部署官方推荐的常规部署方式是 Docker Compose。最新镜像位于 DockerHub镜像名为listmonk/listmonk:latest。# 下载 compose 文件到当前目录 curl -LO https://github.com/knadh/listmonk/raw/master/docker-compose.yml # 后台运行全部服务 docker compose up -d启动完成后访问http://localhost:9000创建 Super Admin 并登录。同样地首次启动时可以用环境变量预置管理员仅首次有效LISTMONK_ADMIN_USERmyuser LISTMONK_ADMIN_PASSWORDxxxxx docker compose up -d理解仓库自带的 compose 编排仓库根目录的 docker-compose.yml 就是官方文档所指的模板值得逐段读懂app 服务image: listmonk/listmonk:latest端口映射9000:9000restart: unless-stopped通过 YAML 锚点*db-credentials复用数据库凭据Postgres 连接指向 compose 内部服务名db启动命令command: [sh, -c, ./listmonk --install --idempotent --yes --config ./listmonk --upgrade --yes --config ./listmonk --config ]——--config 表示完全不用配置文件只依赖环境变量--install --idempotent保证只在空库上执行一次初始化--upgrade在拉取新镜像后自动跑数据库迁移配置方式所有配置以LISTMONK_*环境变量传入嵌套键用双下划线分隔。例如LISTMONK_app__address0.0.0.0:9000对应app.addressLISTMONK_db__hostdb对应db.host持久化Postgres 数据存入命名卷listmonk-data挂载到/var/lib/postgresql/data可选把宿主机./uploads挂载到容器/listmonk/uploads:rw并在后台 设置 → 媒体 中将上传目录改为/listmonk/uploads数据库健康检查pg_isready -U listmonk间隔 10s、超时 5s、重试 6 次安全细节db 端口仅绑定127.0.0.1:5432避免 Postgres 暴露到公网。环境变量的_FILE模式Docker Secrets / Podmancompose 文件开头有一行容易被忽略的注释透露了一个重要能力所有LISTMONK_*环境变量都支持对应的LISTMONK_*_FILE变体用于从文件中加载密钥兼容 Docker secrets 与 Podman。实现位于 docker-entrypoint.sh容器启动时扫描所有^LISTMONK_.*_FILE形式的环境变量若指向的文件存在就把文件内容赋给去掉_FILE后缀的变量例如LISTMONK_DB_USER_FILE/run/secrets/user→LISTMONK_DB_USER文件内容。生产环境把数据库口令放进 secret 文件、而不是直接写进 compose是更安全的做法。挂载自定义 config.toml 的完整三步如果你不想用环境变量而想沿用传统config.toml文件管理配置官方文档给出了标准三步流程第 1 步在宿主机保存 config.toml[app] address 0.0.0.0:9000 # 数据库。 [db] host listmonk_db # compose 文件中 Postgres 容器名 port 5432 user listmonk password listmonk database listmonk ssl_mode disable max_open 25 max_idle 25 max_lifetime 300s第 2 步在 docker-compose.yml 中挂载配置文件app: ... volumes: - /path/on/your/host/config.toml:/listmonk/config.toml第 3 步把command:段中的--config 改为指向该路径command: [sh, -c, ./listmonk --install --idempotent --yes --config /listmonk/config.toml ./listmonk --upgrade --yes --config /listmonk/config.toml ./listmonk --config /listmonk/config.toml]这里值得说明--config 与显式路径的区别从 cmd/main.go 的启动流程看listmonk 先加载 TOML 配置再把LISTMONK_*环境变量合并覆盖到配置树中db.host这类嵌套键由环境变量LISTMONK_db__host转换而来。因此同时设置 config.toml 与环境变量时环境变量优先级更高——这也是为什么自定义 config 挂载时必须把默认的--config 和LISTMONK_*环境变量都让位给真实文件否则两者会产生预期外的覆盖。镜像内部结构Dockerfile 揭示了镜像的构建方式基于alpine:latest安装ca-certificates tzdata shadow su-exec将listmonk二进制与config.toml.sample拷贝进/listmonk暴露 9000 端口入口为docker-entrypoint.sh。入口脚本还支持通过PUID/PGID环境变量以非 root 用户运行容器默认 0/0即 root并在需要时用su-exec降权。方式三Nightly 尝鲜构建如果你希望第一时间体验尚未进入正式版本的最新代码官方持续发布 nightly 构建使用方式与正式版完全一致Docker把 compose 文件中的镜像名改为listmonk/listmonk:nightly二进制从 nightly release 下载。务必注意官方警告nightly 未经过测试、可能存在缺陷使用风险自负升级前一定要备份 Postgres 数据库。源码层面也有对应的特殊处理在 cmd/main.go 中当构建版本号包含nightly字样时listmonk 会在每次启动时自动执行全部待迁移upgrade(db, fs, false, false)且不向数据库记录迁移版本——因为 nightly 之间的迁移可能反复变化这样设计可以保证启动即迁移、迁移幂等。方式四从源码编译master 分支需要编译尚未发布的最新代码master分支时按官方步骤确保系统已安装go、nodejs和yarngit clone gitgithub.com:knadh/listmonk.gitcd listmonk make dist生成listmonk二进制。make dist是一条完整流水线见 Makefile先go build出二进制再yarn build分别构建 Vue 管理前端frontend/dist与 email-builderfrontend/public/static/email-builder最后用 stuffbin 把前端、SQL、模板、i18n 等资源全部塞进二进制。因此编译产物是自包含的可直接拷贝到任意同架构机器运行。如果只想跑后端开发模式可执行make run前端资源从磁盘frontend/dist加载仓库还提供了一套本地开发用的 Docker 编排见 dev/docker-compose.yml通过make dev-docker一键拉起后端 前端 Postgres 的完整开发环境。方式五Kubernetes Helm Chart社区在 HelmForge charts 仓库维护了 listmonk 的官方 Helm chart适合已经运行 Kubernetes 集群的团队。按需配置values.yaml后执行$ helm upgrade \ --create-namespace \ --install listmonk listmonk \ --namespace listmonk \ --repo https://repo.helmforge.dev \ --values values.yaml该命令会创建如不存在listmonk命名空间从 HelmForge 仓库拉取 chart 并按values.yaml覆盖默认值完成安装。方式六第三方托管平台免运维对于不想自己维护服务器的场景官方文档列出了一系列一键部署选项包括 Elestio、PikaPod、Northflank、Railway、RepoCloud、Sealos、Zeabur、Cloudron 等平台的一键部署按钮。这类平台通常会在部署向导中要求填好 Postgres 连接串后直接拉起实例适合快速验证或小规模使用。需要提醒的是各平台的具体配置界面与版本跟随情况以平台为准正式投入生产前建议核对镜像/构建版本与数据备份策略。进阶把二进制装成 systemd 服务虽然不在安装文档正文中仓库根目录提供了两个可直接使用的 systemd unit 模板对二进制部署的生产化很有价值listmonk-simple.service兼容性更广的简单模板。启动前通过ExecStartPre自动执行--upgrade --yes完成迁移ExecStart指定--config /etc/listmonk/config.toml内置NoNewPrivileges、ProtectHome、UMask0027、RestrictAddressFamilies等安全加固项还注释了启用静态目录、日志持久化、非 root 用户运行的扩展写法listmonk.service模板化实例单元可在同一主机上通过listmonk实例名管理多套配置。复制 unit 文件后把配置放到/etc/listmonk/config.toml、二进制放到/usr/bin/listmonk即可用systemctl enable --now listmonk-simple管理。安装后验证与升级路径无论采用哪种方式安装完成后的标准动作是访问http://localhost:9000或你配置的app.address若安装时未设置LISTMONK_ADMIN_USER/LISTMONK_ADMIN_PASSWORD此时网页会引导创建 Super Admin 账号登录后在后台检查示例列表、模板与测试 campaign确认数据库初始化成功。后续升级时二进制部署替换二进制后运行./listmonk --upgrade --yes执行数据库迁移容器部署直接docker compose pull docker compose up -d即可因为 compose 的启动命令已内置--upgrade见 docker-compose.yml。正式环境升级前务必先备份 Postgres 数据库——这也是官方对 nightly 构建反复强调的前提。小结部署方式适用场景关键命令/文件二进制直装单机 VPS、最小依赖--new-config、--install、config.toml.sampleDocker Compose官方推荐、生产常用docker-compose.yml、LISTMONK_*环境变量自定义 config 挂载偏好文件式配置管理三步挂载流程 --config /listmonk/config.tomlNightly尝鲜最新功能有风险listmonk/listmonk:nightly或 nightly release源码编译二次开发、验证 mastermake dist见 MakefileHelm / 托管平台Kubernetes 集群 / 免运维helm upgrade ...或平台一键部署安装只是起点装好之后下一步通常会配置 SMTP 发信smtp配置段、媒体上传存储upload段与反弹邮件处理bounce段这些配置项的默认值与含义可以继续参考 config.toml.sample 及 cmd/init.go 中对应的初始化逻辑。无论选择哪条路径牢记 listmonk 的部署哲学——单一二进制 Postgres资源内嵌、配置分层TOML 环境变量覆盖就能在任何环境里快速复现一套可用的邮件列表系统。【免费下载链接】listmonkHigh performance, self-hosted, newsletter and mailing list manager with a modern dashboard. Single binary app.项目地址: https://gitcode.com/GitHub_Trending/li/listmonk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
