Listmonk 6.2.0 Ubuntu 22.04 安装指南

目标：在 Ubuntu 22.04 服务器上从零安装并托管 Listmonk 6.2.0 邮件列表与营销系统，覆盖 PostgreSQL 数据库准备、官方二进制下载与校验、config.toml 配置、--install 数据库初始化、systemd 服务托管、服务验证、超级管理员与 API 用户创建、常见问题排障与卸载清理。本文所有命令与回显均在 Ubuntu 22.04.5 LTS（x86_64）环境逐条实测通过。

一、环境信息

本文所有命令与回显均在以下环境中实测：

操作系统：Ubuntu 22.04.5 LTS（x86_64）
Listmonk 版本：v6.2.0（构建标识 ef0a7587 2026-06-26T10:21:29Z, linux/amd64）
数据库：PostgreSQL 14（Ubuntu 22.04 官方仓库默认版本）
安装路径：/opt/listmonk
服务端口：9000（Listmonk Web 与 API 默认端口）
数据库名/账号：listmonk / listmonk（本文演示统一使用该账号口令）

二、版本选型与获取

2.1 版本选择

Listmonk 遵循语义化版本，发布件托管在 GitHub Releases。本文撰写时最新稳定版为 v6.2.0，可通过 GitHub API 确认：

curl -s https://api.github.com/repos/knadh/listmonk/releases/latest | grep -m1 '"tag_name"'

实测回显：

  "tag_name": "v6.2.0",

💡 技术拓展：Listmonk 是一款开源自托管的邮件列表与邮件营销系统（newsletter / mailing list manager），支持订阅者管理、邮件列表分组、Campaign 群发、模板变量渲染、退信（Bounce）处理等能力，数据存储依赖 PostgreSQL。它与 Mailman 等传统讨论组软件定位不同：Listmonk 面向「一对多广播式」的订阅推送场景，而不是成员互发讨论。

2.2 下载地址与校验值

v6.2.0 的 linux/amd64 发布件信息（实测下载后统计）：

项目	值
文件名	`listmonk_6.2.0_linux_amd64.tar.gz`
大小	9664556 字节
SHA256	`ce78c89d8aac0df3ffe0e110b008e7bb5dae13e6ad0c57b43aa7094971e8698e`
压缩包内容	`LICENSE`（34520 字节）、`README.md`（2138 字节）、`listmonk`（20153486 字节可执行文件）

三、安装 PostgreSQL 数据库

Listmonk 的全部数据（订阅者、列表、Campaign、设置等）都存放在 PostgreSQL 中，安装 Listmonk 前必须先准备好数据库。

3.1 安装 PostgreSQL 14

Ubuntu 22.04（jammy）官方仓库的 PostgreSQL 默认版本为 14（实测包版本 14+238）：

apt update && apt install -y postgresql

安装完成后确认集群状态：

pg_lsclusters

实测回显：

Ver Cluster Port Status Owner    Data directory              Log file
14  main    5432 online postgres /var/lib/postgresql/14/main /var/log/postgresql/postgresql-14-main.log

PostgreSQL 14 安装后以 systemd 单元 postgresql@14-main 托管，随系统自动启动，无需额外配置。

3.2 创建数据库与账号

Listmonk 需要一个专属数据库与账号。执行以下两条命令创建（口令 listmonk 为演示值，生产环境请替换为强口令）：

su - postgres -c "psql -c \"CREATE USER listmonk WITH PASSWORD 'listmonk';\""

实测回显：

CREATE ROLE

su - postgres -c "psql -c \"CREATE DATABASE listmonk OWNER listmonk;\""

实测回显：

CREATE DATABASE

核对数据库编码与属主：

su - postgres -c "psql -c '\l listmonk'"

实测回显（节选）：

                                   List of databases
   Name   |  Owner  | Encoding | Collate |  Ctype  | Access privileges
----------+---------+----------+---------+---------+-------------------
 listmonk | listmonk | UTF8     | C.UTF-8 | C.UTF-8 |

💡 技术拓展：Listmonk 对数据库的要求是 PostgreSQL 9.4 及以上，但新版本（含 v6.x）建议使用较新的 PostgreSQL 以获得更好的 JSON 与索引性能；Ubuntu 22.04 仓库自带的 14 完全满足。编码保持 UTF8 即可正常存储中文订阅者姓名与邮件内容。

四、安装 Listmonk 主程序

4.1 下载与校验

创建安装目录并下载官方发布件：

mkdir -p /opt/listmonk && cd /opt/listmonk
wget https://github.com/knadh/listmonk/releases/download/v6.2.0/listmonk_6.2.0_linux_amd64.tar.gz

实测下载过程返回 302 Found 重定向至对象存储后开始传输，文件 9664556 字节。下载完成后校验 SHA256：

sha256sum listmonk_6.2.0_linux_amd64.tar.gz

实测回显：

ce78c89d8aac0df3ffe0e110b008e7bb5dae13e6ad0c57b43aa7094971e8698e  listmonk_6.2.0_linux_amd64.tar.gz

与 2.2 节表格中的校验值一致，文件完整可信。若服务器访问 GitHub 缓慢，可为 wget 指定 HTTPS 代理后重试（wget -e "https_proxy=http://<代理地址>:<端口>" ...）。

4.2 解压部署

tar -xzf listmonk_6.2.0_linux_amd64.tar.gz
ls -lh /opt/listmonk

实测回显：

-rw-r--r-- 1 root root    34520 Jun 26 10:23 LICENSE
-rw-r--r-- 1 root root     2138 Jun 26 10:23 README.md
-rwxr-xr-x 1 root root 20153486 Jun 26 10:23 listmonk

确认二进制可用与版本：

./listmonk --version

实测回显：

v6.2.0 (ef0a7587 2026-06-26T10:21:29Z, linux/amd64)

4.3 生成配置文件

Listmonk 提供 --new-config 在 --config 指定的路径生成样例配置（未指定时默认 config.toml）：

./listmonk --new-config

实测回显：

2026/10/17 00:14:22.116222 main.go:106: v6.2.0 (ef0a7587 2026-06-26T10:21:29Z, linux/amd64)
2026/10/17 00:14:22.158594 main.go:115: generated config.toml. Edit and run --install

4.4 修改配置

生成的 config.toml 内容如下（实测文件原文，关键处已可对号入座）：

[app]
# Interface and port where the app will run its webserver.  The default value
# of localhost will only listen to connections from the current machine. To
# listen on all interfaces use '0.0.0.0'. To listen on the default web address
# port, use port 80 (this will require running with elevated permissions).
address = "localhost:9000"

# Database.
[db]
host = "localhost"
port = 5432
user = "listmonk"
password = "listmonk"

# Ensure that this database has been created in Postgres.
database = "listmonk"

ssl_mode = "disable"
max_open = 25
max_idle = 25
max_lifetime = "300s"

# Optional space separated Postgres DSN params. eg: "application_name=listmonk gssencmode=disable"
params = ""

需要按 3.2 节实际创建的账号修改 [db] 段。本文演示账号口令与样例一致（listmonk/listmonk），无需改动。[app] 段的 address = "localhost:9000" 表示仅监听本机回环；如需对外提供服务，可改为 0.0.0.0:9000 并配合反向代理使用。

4.5 初始化数据库

首次运行 --install 会在目标数据库中创建 Listmonk 的全部表结构。安装程序会交互式要求确认（该操作会清空库中已有的 listmonk 表），实测通过管道输入 y 完成：

printf "y\n" | ./listmonk --install

实测回显：

2026/10/17 00:14:44.293935 main.go:106: v6.2.0 (ef0a7587 2026-06-26T10:21:29Z, linux/amd64)
2026/10/17 00:14:44.294012 init.go:191: reading config: config.toml
2026/10/17 00:14:44.294111 init.go:331: connecting to db: localhost:5432/listmonk

** first time installation **
** IMPORTANT: This will wipe existing listmonk tables and types in the DB 'listmonk' **
continue (y/N)?  2026/10/17 00:14:44.449105 install.go:96: no superadmin user created. Visit webpage to create user.
2026/10/17 00:14:44.449133 install.go:116: setup complete
2026/10/17 00:14:44.449139 install.go:117: run the program and access the dashboard at localhost:9000

三个关键信息：

setup complete：表结构初始化完成；
no superadmin user created. Visit webpage to create user.：命令行初始化不创建管理员，首次访问网页时会进入创建超级管理员流程（见 6.2 节）；
回显中的 wipe existing listmonk tables 警告说明 --install 具有破坏性，对已初始化的库重复执行会清空数据。若担心误操作，可加 --idempotent：仅在库未初始化时才执行安装。

💡 技术拓展：--install、--upgrade、--idempotent 三个参数分工明确——--install 负责「从零建表」，会重置已有表；--upgrade 负责「把已建好的表结构迁移到当前二进制对应的版本」，幂等且增量；--idempotent 只能配合 --install 使用，让安装命令可以安全地重复执行（常用于脚本化部署）。版本升级场景应使用 --upgrade 而不是重跑 --install。

五、systemd 服务托管

5.1 编写服务单元

创建 /etc/systemd/system/listmonk.service：

cat > /etc/systemd/system/listmonk.service <<'EOF'
[Unit]
Description=listmonk mailing list manager
After=network.target postgresql.service

[Service]
Type=simple
WorkingDirectory=/opt/listmonk
ExecStart=/opt/listmonk/listmonk --config /opt/listmonk/config.toml
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

说明：

After=network.target postgresql.service：确保网络与 PostgreSQL 就绪后再拉起 Listmonk；
WorkingDirectory=/opt/listmonk：Listmonk 默认在该目录下读写上传媒体等文件；
Restart=on-failure + RestartSec=5：进程异常退出后 5 秒自动拉起。

5.2 启动与开机自启

重新加载单元定义、设置开机自启并启动服务（每条命令针对一个单元）：

systemctl daemon-reload
systemctl enable listmonk

实测回显：

Created symlink /etc/systemd/system/multi-user.target.wants/listmonk.service → /etc/systemd/system/listmonk.service.

systemctl start listmonk
systemctl status listmonk

实测回显（节选）：

● listmonk.service - listmonk mailing list manager
     Loaded: loaded (/etc/systemd/system/listmonk.service; enabled; vendor preset: enabled)
     Active: active (running)
   Main PID: 3691 (listmonk)
      Tasks: 9 (limit: 4537)
     Memory: 29.8M
        CPU: 1.212s
     CGroup: /system.slice/listmonk.service
             └─3691 /opt/listmonk/listmonk --config /opt/listmonk/config.toml

服务 active (running)，常驻内存约 30 MB，非常轻量。

六、部署验证与管理员创建

6.1 服务健康验证

curl -s -o /dev/null -w "%{http_code}\n" http://localhost:9000/

实测回显：

curl -s http://localhost:9000/ | grep -o '<title>[^<]*</title>'

实测回显：

<title>Login - Mailing list</title>

返回 200 且页面标题为 Login - Mailing list，说明服务已正常响应。由于尚未创建任何用户，根路径直接呈现登录页。

6.2 创建超级管理员

在没有任何用户时，访问管理后台 /admin 会被重定向到「创建超级管理员」页面。验证重定向行为：

curl -sI http://localhost:9000/admin

实测回显（节选）：

HTTP/1.1 307 Temporary Redirect
Location: /admin/login?next=%2Fadmin

用浏览器打开 http://<服务器IP>:9000/admin，页面即「创建超级管理员」表单，字段包括姓名（name）、邮箱（email）、登录用户名（username）、密码（password）与确认密码（password2）。填写后提交，服务端校验规则为：邮箱格式合法、用户名不少于 3 个字符、密码不少于 8 位且两次输入一致。

本文演示创建的账号为：

字段	值
姓名	Admin
邮箱	admin@listmonk.local
用户名	admin
密码	q1w2e3r4

也可以用 curl 模拟表单提交完成创建（-w 输出状态码与跳转地址）：

curl -s -o /dev/null -w "%{http_code} %{redirect_url}\n" \
  --data-urlencode "name=Admin" \
  --data-urlencode "email=admin@listmonk.local" \
  --data-urlencode "username=admin" \
  --data-urlencode "password=q1w2e3r4" \
  --data-urlencode "password2=q1w2e3r4" \
  http://localhost:9000/admin/login

实测回显：

302 http://localhost:9000/admin

返回 302 并跳转到 /admin，说明超级管理员创建成功、已可登录后台。

6.3 创建 API 用户并验证 API

Listmonk 的 REST API 认证方式是 Basic 认证：API 用户名 + API Token（不是网页登录密码）。API 用户需在已登录的后台创建：进入管理后台 Admin → Users 页面新建用户，类型选择 API；也可以携带管理员登录会话 Cookie 调用 POST /api/users，请求体：

{
  "username": "apibot",
  "name": "API Bot",
  "type": "api",
  "status": "enabled",
  "user_role_id": 1
}

实测响应（节选，data.password 即 48 位 API Token）：

{"data":{"id":3,"username":"apibot","password":"p2KZBp1b25vfJfau1RSUJMhKT0J5CRxZdVcBK7fWTgM6Hpzk","name":"API Bot","type":"api","status":"enabled","user_role":{"id":1,"name":"Super Admin","permissions":["bounces:get","subscribers:import","campaigns:manage_all","media:get","templates:manage","users:manage","roles:manage","settings:manage","lists:manage_all","subscribers:get_all","campaigns:get_analytics","webhooks:post_bounce","users:get","roles:get","settings:maintain","lists:get_all","campaigns:get_all","bounces:manage","media:manage","templates:get","settings:get","subscribers:get","subscribers:manage","subscribers:sql_query","tx:send","campaigns:get","campaigns:manage","campaigns:send"]}}}

用该 API 用户验证接口连通性：

curl -s -u "apibot:p2KZBp1b25vfJfau1RSUJMhKT0J5CRxZdVcBK7fWTgM6Hpzk" http://localhost:9000/api/lists

实测回显（节选）：

{"data":{"results":[{"id":1,"uuid":"2bf2b879-4979-4665-8c7b-2c2799fd41f3","name":"Default list","type":"private","optin":"single","status":"active","tags":["test"],"subscriber_count":1},{"id":2,"uuid":"8d6d30e4-27f8-43e2-ab15-a872f019c84e","name":"Opt-in list","type":"public","optin":"double","status":"active","tags":["test"],"subscriber_count":1}],"total":2,"per_page":20,"page":1}}

返回 200 且列出两个默认列表，API 认证链路验证通过。

💡 技术拓展：user_role_id: 1 是 Super Admin 角色，拥有全部 28 项细粒度权限（如 subscribers:import、campaigns:send、webhooks:post_bounce 等）。生产环境建议按需创建权限更小的 API 用户，只授予实际需要的权限（例如只发事务邮件的集成仅需 tx:send）。

6.4 默认数据说明

--install 初始化后自带两份演示数据：

id	名称	type	optin	说明
1	Default list	private	single	私有列表，单步确认
2	Opt-in list	public	double	公开列表，双步确认

另有 1 名状态为 unconfirmed 的示例订阅者。

💡 技术拓展：type（private/public）控制列表是否对外可见；optin（single/double）控制订阅确认流程——single 为订阅即生效，double 需要订阅者点击确认邮件中的链接后才正式加入（double opt-in 是欧美邮件合规的主流实践，可有效降低垃圾邮件投诉率）。

七、命令行参数速查

./listmonk --help 实测输出全文如下：

      --config strings      path to one or more config files (will be merged in order) (default [config.toml])
      --i18n-dir string     (optional) path to directory with i18n language files
      --idempotent          make --install run only if the database isn't already setup
      --install             setup database (first time)
      --new-config          generate sample config file (at path given in --config)
      --passive             run in passive mode where campaigns are not processed
      --static-dir string   (optional) path to directory with static files
      --upgrade             upgrade database to the current version
      --version             show current version of the build
      --yes                 assume 'yes' to prompts during --install/upgrade

参数	说明
`--config`	配置文件路径，可传多个按顺序合并，默认 `[config.toml]`
`--i18n-dir`	可选，i18n 语言文件目录
`--idempotent`	配合 `--install`，仅在数据库未初始化时执行安装
`--install`	首次安装，初始化数据库表结构（重复执行会清空已有表）
`--new-config`	在 `--config` 指定路径生成样例配置
`--passive`	被动模式运行，不处理 Campaign 投递
`--static-dir`	可选，静态文件目录
`--upgrade`	将数据库结构升级到当前二进制对应版本
`--version`	显示构建版本
`--yes`	对 `--install`/`--upgrade` 的交互确认自动回答 yes

八、常见问题与排障

8.1 API 返回 403 invalid API credentials

现象：用 Basic 认证调用 API 时返回：

{"message":"invalid API credentials"}

原因：把网页登录密码当成了 API Token。Listmonk 的 API 认证凭据是「API 用户名 + 创建 API 用户时返回的 48 位 Token」，两者不同。解决：到后台 Admin → Users 查看或重建 API 用户，使用响应中的 password 字段值作为 Token（该值仅在创建时完整返回一次）。

8.2 创建 API 用户报 pq: invalid input value for enum user_status

现象：POST /api/users 返回：

pq: invalid input value for enum user_status

原因：请求体缺少 status 字段。解决：补上 "status": "enabled"。

8.3 创建 API 用户报 null value in column user_role_id

现象：POST /api/users 返回：

null value in column user_role_id violates not-null constraint

原因：角色字段名写成了 roles。v6 API 的正确字段名是 user_role_id（值为角色 ID 数字，Super Admin 为 1）。

8.4 重复执行 --install 的数据风险

--install 启动即提示 This will wipe existing listmonk tables and types in the DB 'listmonk'，确认后清空重建。日常不要把它写进启动脚本；脚本化部署请使用 --install --idempotent --yes 组合（首次空库安装，之后自动跳过）。

九、卸载清理

按「停服务 → 摘自启 → 删单元 → 删库删账号 → 删程序目录」的顺序完整卸载：

systemctl stop listmonk

systemctl disable listmonk

实测回显：

Removed /etc/systemd/system/multi-user.target.wants/listmonk.service.

删除服务单元并重载：

rm -f /etc/systemd/system/listmonk.service
systemctl daemon-reload

删除数据库与账号：

su - postgres -c "psql -c \"DROP DATABASE listmonk;\""

实测回显：

DROP DATABASE

su - postgres -c "psql -c \"DROP USER listmonk;\""

实测回显：

DROP ROLE

删除程序目录并验证卸载结果：

rm -rf /opt/listmonk
systemctl is-active listmonk

实测回显：

inactive

su - postgres -c "psql -lt" | grep listmonk

实测回显为空（数据库列表中已无 listmonk），卸载完成。

十、参考链接

Listmonk 官网：https://listmonk.app/
安装文档：https://listmonk.app/docs/installation/
GitHub 仓库：https://github.com/knadh/listmonk
GitHub Releases（v6.2.0）：https://github.com/knadh/listmonk/releases/tag/v6.2.0
Listmonk 官方 Docker Compose 示例：https://github.com/knadh/listmonk/blob/master/docker-compose.yml