最稳妥方式是直接用官方预编译二进制文件启动：下载对应架构的tar.gz包，解压后chmod +x，执行./listmonk --new-config生成配置，重点配置[db]、[smtp]和[app].address，初始化时需通过环境变量listmonk_admin_user与listmonk_admin_password同时传入，smtp配置注意嵌套结构与use_tls/use_ssl互斥，生产环境务必关闭debug模式并合理调高postgresql的max_connections。
直接用二进制文件启动最稳妥，别急着上 Docker
listmonk 官方提供预编译的 listmonk 二进制文件，对大多数 Linux 发行版（Ubuntu 22.04+/CentOS 8+/Debian 12+）开箱即用，比 Docker 更容易排查端口、数据库、权限问题。
- 下载对应架构的二进制（如
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"（监听所有网卡） - 若 PostgreSQL 不在本地，注意
ssl_mode：内网直连可设为"disable"；跨公网务必用"require"并配好证书
数据库初始化失败？检查 LISTMONK_admin 用户环境变量是否生效
执行 ./listmonk --install 报错 “failed to create admin user” 或 “pq: password authentication failed”，大概率是环境变量没传进去，而不是密码错了。
Zynq Linux Hardware Debug
下载
Zynq‑7000 / Zynq UltraScale+ 硬件调试技能。适用于 Xilinx Zynq（Cortex‑A9/A53 + FPGA）Linux 环境，调试 I2C、I2S、UART、GPIO 等外设。包括设备树配置、内核驱动、用户空间调试工具、交叉编译和常见问题排查，支持 PetaLinux 开发。
- 必须用
LISTMONK_ADMIN_USER和LISTMONK_ADMIN_PASSWORD同时设置，缺一不可 - 不要写成
LISTMONK_ADMIN_USER=admin LISTMONK_ADMIN_PASSWORD=123 ./listmonk --install（Bash 会认为这是两个独立命令） - 正确写法是：
LISTMONK_ADMIN_USER=admin LISTMONK_ADMIN_PASSWORD=your_strong_pass ./listmonk --install - 如果用 systemd 管理服务，记得在
.service文件里用Environment=显式声明，不能只靠 shell 环境
SMTP 配置不生效？优先验证配置项拼写和层级
listmonk 的 SMTP 设置在 TOML 中属于嵌套结构，[smtp] 下的字段名、缩进、布尔值大小写都敏感，错一个就静默回退到默认（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但没具体错误？加log_level = "debug"到[app]段再试
生产环境必须关掉 debug 模式，否则 API 密钥会泄露
listmonk 在 debug = true 且启用 API 时，会在 HTTP 响应头或日志中明文打印 LISTMONK_API_KEY 值——这不是 bug，是设计如此，方便开发调试。
- 上线前务必把
config.toml中的debug = true改成false，哪怕你用环境变量传了LISTMONK_API_KEY - API 密钥永远别硬编码进
config.toml；生产环境统一走LISTMONK_API_KEY=xxx ./listmonk启动 - 如果你用 nginx 反代 9000 端口，记得在
location /api/块里加proxy_set_header X-Forwarded-Proto $scheme;，否则 API 认证会因协议判断失败
max_connections。listmonk 默认连接池设 max_open = 25，但若你同时跑多个 worker 或开启大量并发订阅导入，PostgreSQL 本身默认只有 100 连接，很快会卡在 “sorry, too many clients already”。调这个值比调 listmonk 配置更关键。
