推荐直接使用官方预编译二进制安装listmonk，因其不依赖系统go环境、无需拉取镜像、跳过postgresql健康检查，错误日志即时可见，便于快速排查端口、权限及数据库连接问题。
listmonk 在 Linux 上安装不难，但卡住的地方往往不是编译或下载，而是**数据库初始化失败、环境变量没生效、或 Docker 网络配置错填 localhost**。直接用官方预编译二进制最稳，Docker 次之，别碰源码编译或 phpenv 这类无关工具。
二进制方式启动：为什么推荐？
它不依赖系统 Go 环境、不拉镜像、不等 PostgreSQL 健康检查，出问题能立刻看到错误日志，排查端口、权限、数据库连接都更直接。
- 下载对应架构的包（如
listmonk_3.1.0_linux_amd64.tar.gz），解压后执行chmod +x listmonk - 首次必须生成配置：
./listmonk --new-config→ 生成config.toml - 编辑
config.toml，重点改三块：[db]（PostgreSQL 连接）、[smtp]（发信）、[app].address（监听地址，建议填"0.0.0.0:9000"） - 初始化数据库时，
LISTMONK_ADMIN_USER和LISTMONK_ADMIN_PASSWORD必须同时设置且生效，否则报"failed to create admin user"—— 不是密码错，是变量根本没传进去 - 正确写法：
LISTMONK_ADMIN_USER=admin LISTMONK_ADMIN_PASSWORD=your_strong_pass ./listmonk --install
Docker Compose 部署：常见失败点在哪？
官方 docker-compose.yml 开箱可用，但很多人自己改崩了，核心就一条：db_host 必须填服务名 db，不是 localhost，也不是 127.0.0.1。
-
config.toml中的[db].host = "db"—— 这是容器间通信的 DNS 名，localhost在 listmonk 容器里指向自己，不是 PostgreSQL - 环境变量必须写进
docker-compose.yml的environment:块里，shell 里export没用，因为--install是容器启动脚本自动触发的 - 宿主机目录
./data和./uploads权限要对：属主得是运行docker compose up的用户，且至少755 - PostgreSQL 启动慢？加
restart: on-failure让 listmonk 容器自动重试，别只靠depends_on
SMTP 配置总不生效？先看 TOML 结构
listmonk 的 SMTP 设置是嵌套 TOML，拼写、缩进、布尔值大小写全敏感，错一个就静默回退到默认 localhost:25，日志还不报错。
- 必填字段只有三个：
host、port、username；password和from_email强建议填 -
use_tls和use_ssl互斥：Gmail/Outlook 用use_tls = true（端口 587）；老企业邮件服务器可能要用use_ssl = true（端口 465） - 测试前先确认网络层通：
telnet smtp.gmail.com 587或openssl s_client -connect smtp.gmail.com:587 -starttls smtp - 日志里出现
failed to send test email却没具体错误？大概率是from_email格式不对（比如缺 @ 符号）或 SMTP 密码含特殊字符没转义
别踩这些坑：phpenv、源码编译、SSL mode
listmonk 是 Go 写的单二进制，和 PHP 零关系 —— phpenv 对它完全无效，装了也白装，还可能污染环境变量。
- 不要尝试用
make build编译源码，除非你真要改 Go 代码；官方二进制已针对各平台优化过 -
ssl_mode别乱设：内网直连 PostgreSQL 可设"disable"；跨公网必须用"require"并配好证书，否则连接被拒 - 生产环境务必关掉
debug = true，否则日志泄露 SQL 查询和用户数据 - PostgreSQL 的
max_connections要调高（建议 ≥200），listmonk 发信并发高，连接池不够会卡住
pg_hba.conf，或是 SMTP 测试失败后翻遍日志却漏看了 TOML 缩进。把 host、use_tls、LISTMONK_ADMIN_USER 这三处盯死，八成问题当场解决。
