Pasang Listmonk di Ubuntu 24.04 pada VPS

Keperluan surat berita dihos sendiri pada Listmonk

Listmonk ialah pengurus surat berita dan senarai mel yang dihos sendiri: satu binari Go, satu pangkalan data PostgreSQL, satu fail konfigurasi dan satu unit systemd. VPS kecil boleh menjalankannya tanpa masalah kerana Listmonk menyimpan pelanggan dan membuat giliran kempen, tetapi tidak pernah menghantar mel itu sendiri. Listmonk menyerahkan setiap mesej kepada pelayan SMTP (protokol pemindahan mel mudah), jadi kadar penghantaran anda ditentukan oleh reputasi pelayan itu, bukan oleh perisian ini.

Panduan ini memasang Listmonk v6.2.0, keluaran semasa pada Julai 2026, pada Ubuntu 24.04. Anda memerlukan VPS dengan alamat IP awam, nama domain yang anda kawal dan PostgreSQL 12 atau lebih baharu. Pemasangan mengambil masa kira-kira sejam. Reputasi penghantaran mengambil masa beberapa minggu, dan bahagian itu diterangkan menjelang akhir.

Pasang PostgreSQL dan cipta pangkalan data

Ubuntu 24.04 menyediakan PostgreSQL 16 dalam repositorinya sendiri, jauh lebih baharu daripada keperluan Listmonk.

sudo apt update
sudo apt install -y postgresql curl
sudo systemctl enable --now postgresql

Cipta peranan dan pangkalan data dalam satu sesi psql. -v ON_ERROR_STOP=1 menyebabkan psql keluar apabila pernyataan pertama gagal, supaya kesilapan taip tidak meninggalkan persediaan separa yang kelihatan siap.

sudo -u postgres psql -v ON_ERROR_STOP=1 <<'SQL'
CREATE USER listmonk WITH PASSWORD 'pick-a-long-random-password';
CREATE DATABASE listmonk OWNER listmonk;
SQL

OWNER listmonk bukan hiasan. Pemasangan skema mencipta jadual, jenis, indeks dan fungsi, jadi peranan tersebut mesti memiliki pangkalan data. Jika anda menetapkan Listmonk kepada pangkalan data yang dimiliki oleh peranan lain, pemasangan akan berhenti dengan permission denied, walaupun anda telah menjalankan GRANT CONNECT.

Sahkan bahawa pangkalan data wujud sebelum meneruskan.

sudo -u postgres psql -tAc "SELECT datname FROM pg_database WHERE datname='listmonk';"

Perintah itu mencetak listmonk. Baris kosong bermaksud pernyataan CREATE tidak pernah dijalankan, jadi semak semula output psql.

Pasang binari Listmonk

Listmonk mengeluarkan binari statik untuk setiap seni bina. Semak seni bina anda terlebih dahulu kerana binari amd64 pada VPS ARM ialah fail yang tidak dapat dilaksanakan oleh kernel.

dpkg --print-architecture
cd /tmp
curl -fsSLO https://github.com/knadh/listmonk/releases/download/v6.2.0/listmonk_6.2.0_linux_amd64.tar.gz
tar -xzf listmonk_6.2.0_linux_amd64.tar.gz
sudo install -m 755 listmonk /usr/bin/listmonk
listmonk --version

Pada VPS ARM, gantikan amd64 dengan arm64 dalam nama fail. listmonk --version yang mencetak rentetan versi ialah bukti pertama bahawa binari itu sepadan dengan mesin.

Jana config.toml dan hadkan aksesnya

--new-config menulis config.toml ke direktori kerja semasa. Oleh itu, cd berada di dalam sh -c, bukan sebelum sudo.

sudo install -d -m 750 /etc/listmonk
sudo sh -c 'cd /etc/listmonk && listmonk --new-config'

Fail yang dijana itu ringkas. Di bawah [app], address = "localhost:9000" mengikat pelayan HTTP kepada loopback sahaja. Oleh itu, panel pentadbir tidak boleh dicapai dari internet sehingga anda meletakkan proksi terbalik di hadapannya. Jangan ubah baris itu. Di bawah [db], anda mendapat host = "localhost", port = 5432, user = "listmonk", database = "listmonk" dan ssl_mode = "disable". Nilai lalai tersebut sudah sepadan dengan pangkalan data yang anda cipta. Jadi, satu-satunya baris yang perlu diubah ialah kata laluan.

ssl_mode = "disable" adalah betul apabila Postgres mendengar pada loopback di mesin yang sama, kerana trafik itu tidak pernah meninggalkan mesin. Jika anda memindahkan pangkalan data ke hos lain, tetapkan nilainya kepada require. Jika tidak, kata laluan akan merentasi rangkaian dalam teks jelas.

Edit baris kata laluan di bawah [db] supaya sepadan dengan peranan tersebut. Kemudian, cipta akaun perkhidmatan dan halang semua log masuk lain daripada mengakses fail itu.

sudo useradd --system --home-dir /var/lib/listmonk --create-home --shell /usr/sbin/nologin listmonk
sudo chown -R root:listmonk /etc/listmonk
sudo chmod 640 /etc/listmonk/config.toml

Kini akaun perkhidmatan boleh membaca fail tersebut dan tiada pengguna lain boleh membacanya.

sudo -u listmonk cat /etc/listmonk/config.toml > /dev/null && echo readable
stat -c '%U:%G %a' /etc/listmonk/config.toml

Perintah pertama mencetak readable. Perintah kedua mencetak root:listmonk 640. Mana-mana akaun tanpa keistimewaan lain yang cuba menjalankan cat yang sama akan mendapat Permission denied. Itulah tujuannya: fail ini mengandungi kata laluan pangkalan data dalam teks jelas, dan pelayan biasanya mempunyai lebih daripada satu akaun log masuk. Prinsip yang sama terpakai pada setiap perkhidmatan yang anda jalankan. Oleh itu, baca pengguna perkhidmatan dengan keistimewaan minimum sekali dan gunakannya di semua tempat.

Cipta skema dengan --install

--install mencipta jadual dan mengisi tetapan lalai. Tetapkan log masuk pentadbir pertama dengan pemboleh ubah persekitaran supaya akaun itu wujud sebelum panel boleh dicapai.

sudo -u listmonk env LISTMONK_ADMIN_USER=admin \
  LISTMONK_ADMIN_PASSWORD='another-long-random-password' \
  listmonk --config /etc/listmonk/config.toml --install --yes

--yes menjawab gesaan pengesahan. Baca gesaan itu sekali sebelum mengautomasikannya kerana --install ialah pemasangan pertama dan akan memadam skema Listmonk yang sedia ada. Menjalankannya kali kedua pada pangkalan data langsung akan memusnahkan pelanggan anda. Dalam mana-mana skrip yang mungkin dijalankan dua kali, gunakan --install --idempotent --yes, yang tidak melakukan apa-apa apabila jadual sudah tersedia. Perubahan skema yang disertakan dalam keluaran baharu digunakan dengan --upgrade, bukan dengan --install.

Semak hasilnya dari sisi pangkalan data, bukan melalui pelayar.

sudo -u postgres psql -d listmonk -c '\dt'
sudo -u postgres psql -d listmonk -tAc "SELECT username FROM users;"

Perintah pertama menyenaraikan jadual Listmonk, termasuk subscribers, lists, campaigns, templates dan bounces. Perintah kedua mencetak admin. Hasil kosong daripada perintah kedua bermaksud pemboleh ubah persekitaran tidak pernah sampai kepada proses tersebut, jadi panel akan meminta anda mencipta pengguna pertama dalam pelayar.

Jalankan Listmonk dengan systemd

Tulis /etc/systemd/system/listmonk.service.

[Unit]
Description=Listmonk newsletter and mailing list manager
After=network-online.target postgresql.service
Wants=network-online.target

[Service]
Type=simple
User=listmonk
Group=listmonk
WorkingDirectory=/var/lib/listmonk
ExecStart=/usr/bin/listmonk --config /etc/listmonk/config.toml
Restart=on-failure
RestartSec=5
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=full
ProtectHome=true

[Install]
WantedBy=multi-user.target

WorkingDirectory penting kerana Listmonk menyelesaikan laluan relatif, termasuk laluan muat naik media dalam sistem fail, berdasarkan laluan ini. After=postgresql.service hanya mengarahkan proses untuk bermula. Ia tidak menunggu Postgres menerima sambungan. Oleh itu, Restart=on-failure menangani keadaan apabila Listmonk bermula terlalu awal dan tidak dapat bersambung.

sudo systemctl daemon-reload
sudo systemctl enable --now listmonk
ss -ltnp | grep 9000
curl -sI http://127.0.0.1:9000/

ss sepatutnya menunjukkan 127.0.0.1:9000 dalam keadaan LISTEN. curl yang mengembalikan apa-apa baris status HTTP bermaksud pelayan sedang memberikan respons. curl yang gagal dengan Connection refused bermaksud proses terhenti semasa permulaan, dan journalctl -u listmonk -n 50 --no-pager akan menyatakan sebabnya. Perhatikan bahawa enable --now ialah bahagian yang terus berfungsi selepas but semula. Proses yang dimulakan secara manual akan terhenti selepas peningkatan kernel yang seterusnya.

Pasang nginx dan TLS di hadapan

Listmonk menggunakan HTTP biasa pada loopback. Oleh itu, nginx menamatkan TLS (keselamatan lapisan pengangkutan) dan memajukan permintaan.

server {
    listen 443 ssl;
    server_name lists.example.com;

    client_max_body_size 25m;

    location / {
        proxy_pass http://127.0.0.1:9000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

client_max_body_size perlu dinaikkan kerana import pelanggan dan muat naik media ialah kiriman fail. nginx menolak apa-apa yang melebihi 1 MB secara lalai dengan 413 Request Entity Too Large. Keluarkan sijil menggunakan certbot. certbot juga menulis baris listen 443 ssl dan ubah hala daripada port 80 untuk anda. Langkah-langkahnya terdapat dalam panduan sijil Let's Encrypt untuk nginx. Buka port 80 dan 443. Pastikan port 9000 ditutup kerana proksi mengaksesnya melalui loopback. Jika tembok api masih belum dikonfigurasikan, mulakan dengan asas tembok api ufw.

Kemudian buka panel pentadbir dan tetapkan URL akar di bawah Settings kepada https://lists.example.com. Pemasangan baharu mengandungi http://localhost:9000. Listmonk menulis nilai itu ke dalam setiap pautan nyahlanggan dan URL media yang dimasukkannya dalam e-mel. Jika anda menghantar kempen sebelum mengubahnya, setiap penerima akan mendapat pautan yang menghala ke mesin mereka sendiri. Pautan itu gagal dibuka oleh penerima. Bagi penapis spam, keadaan ini kelihatan seperti pengirim yang tidak dapat mengkonfigurasikan domain sendiri.

Sambungkan SMTP, yang tiada dalam config.toml

Cari bahagian SMTP dalam config.toml dan anda tidak akan menemuinya. Tetapan mel disimpan dalam pangkalan data, dalam jadual settings, dan anda mengeditnya dalam panel pentadbir di bawah Settings dan SMTP. Sebab itu fail yang dijana kekal begitu ringkas. Sebab itu juga perubahan SMTP tidak memerlukan mula semula.

Terdapat dua pilihan yang munasabah untuk pelayan SMTP itu sendiri. Jalankan pelayan sendiri. Ini meletakkan reputasi sepenuhnya dalam kawalan anda dan merupakan projek tersendiri: menjalankan pelayan mel sendiri dengan Mailcow menerangkan perkara yang terlibat. Atau halakan Listmonk kepada relay transaksi dan biarkan pihak lain mengurus reputasi IP.

Dalam kedua-dua keadaan, gunakan port 587 dengan STARTTLS, atau port 465 dengan TLS tersirat. Jangan merancang untuk menggunakan port keluar 25. Kebanyakan penyedia VPS menyekatnya secara lalai pada akaun baharu. Port 25 yang disekat kelihatan sama seperti sambungan yang tergantung kerana paket digugurkan dan bukannya ditolak. Oleh itu, klien menunggu tamat masa dan bukannya gagal dengan segera.

Uji dahulu sebelum mempercayainya. Cipta senarai, tambah alamat anda sendiri sebagai pelanggan, dan hantar kempen kepada seorang penerima. Buka mesej yang diterima dan baca pengepala penuh. Pengepala Authentication-Results yang ditambahkan oleh pihak penerima memberitahu anda sama ada SPF dan DKIM lulus.

Kebolehsampaian ialah keseluruhan tugas

Listmonk membina mesej, menjejaki senarai dan menyerahkan mel untuk dihantar. Semua keputusan tentang sama ada mel itu sampai ke peti masuk dibuat oleh penyedia penerima, berdasarkan alamat IP penghantar dan domain penghantar. IP VPS baharu langsung tiada sejarah, dan semua penyedia peti mel utama menganggap ketiadaan sejarah sebagai sedikit mencurigakan.

Empat perkara berikut adalah wajib:

• Rekod TXT SPF (sender policy framework) yang menamakan hos yang dibenarkan menghantar untuk domain anda.
• Kunci DKIM (domainkeys identified mail) yang diterbitkan sebagai rekod TXT, dengan proses penandatanganan dilakukan oleh pelayan mel, bukan oleh Listmonk.
• Rekod DMARC (domain based message authentication, reporting and conformance), yang memberitahu penerima tindakan yang perlu diambil apabila dua perkara pertama gagal.
• Peti mel lantunan yang dibaca oleh Listmonk, supaya alamat yang menolak mel dikeluarkan daripada senarai dan tidak dicuba semula tanpa henti.

Kemudian, hantar mel secara perlahan pada peringkat awal. Domain yang tidak pernah menghantar mel dan tiba-tiba menghantar sepuluh ribu mesej dalam masa sejam mempunyai ciri yang sama seperti akaun yang telah diceroboh, lalu ditapis sedemikian. Mulakan dengan pelanggan yang paling aktif dan tingkatkan jumlah penghantaran secara berperingkat selama beberapa hari.

Setiap templat juga memerlukan pautan berhenti melanggan yang berfungsi. Dalam templat Listmonk, pautan itu ialah {{ UnsubscribeURL }}, dan kandungan kempen diletakkan di tempat {{ template "content" . }} berada. Penanda itu mesti muncul tepat sekali dalam setiap templat. Kempen tanpa pautan berhenti melanggan akan menerima aduan spam, bukan permintaan berhenti melanggan. Aduan ialah cara terpantas untuk kehilangan reputasi penghantaran yang anda bina selama berminggu-minggu.

Sandaran dan perkara yang benar-benar diperlukan untuk pemulihan

Dua perkara mesti dikeluarkan dari pelayan: dump pangkalan data dan config.toml. Tambahkan direktori media jika anda memuat naik imej ke dalam kempen.

sudo -u postgres pg_dump -Fc listmonk > listmonk-$(date +%F).dump

Dump itu mengandungi pelanggan, kempen, templat dan semua tetapan, termasuk kelayakan SMTP. Oleh itu, sulitkan dump tersebut dan simpan di luar pelayan ini. Penjadualan proses ini sudah tersedia: lihat sandaran restic yang disulitkan ke storan jauh. config.toml hanya terdiri daripada beberapa baris, tetapi mengandungi kata laluan pangkalan data. Oleh itu, kendalikannya dengan cara yang sama.

Ikut satu turutan untuk naik taraf. Hentikan perkhidmatan, buat dump, gantikan binari dalam /usr/bin, jalankan listmonk --config /etc/listmonk/config.toml --upgrade, kemudian mulakan perkhidmatan. Migrasi skema hanya berjalan ke hadapan. Oleh itu, dump itu ialah satu-satunya cara untuk kembali ke keadaan sebelumnya.

Mengapakah Listmonk gagal dimulakan?

Baca jurnal terlebih dahulu dengan journalctl -u listmonk -n 50 --no-pager. Hampir semua kegagalan permulaan muncul sebagai satu baris dalam blok [db].

pq: password authentication failed for user "listmonk" bermaksud kata laluan dalam [db] tidak sepadan dengan peranan Postgres. Awalan pq menunjukkan pemacu Postgres melaporkan penolakan daripada pelayan. Ini bermakna konfigurasi telah dibaca dengan betul, tetapi kelayakan tidak betul. Tetapkan semula peranan dengan sudo -u postgres psql -c "ALTER USER listmonk WITH PASSWORD 'new-password';" dan masukkan rentetan yang sama dalam fail tersebut.

pq: database "listmonk" does not exist bermaksud nilai database dalam [db] tidak merujuk kepada pangkalan data yang sebenar. sudo -u postgres psql -l menyenaraikan pangkalan data yang tersedia pada pelayan, termasuk ejaan yang tersilap digunakan.

permission denied semasa --install bermaksud peranan tersebut boleh bersambung tetapi bukan pemilik pangkalan data. Oleh itu, peranan itu tidak boleh mencipta jadual dalam pangkalan data tersebut. Betulkan dengan sudo -u postgres psql -c "ALTER DATABASE listmonk OWNER TO listmonk;" dan jalankan pemasangan sekali lagi.

Perkhidmatan tidak pernah bermula dan jurnal menamakan fail konfigurasi. Proses yang berjalan sebagai listmonk tidak boleh membuka config.toml yang ditetapkan sebagai root:root dengan mod 600. stat -c '%U:%G %a' /etc/listmonk/config.toml sepatutnya mencetak root:listmonk 640, dan direktori di atasnya sepatutnya ialah root:listmonk 750.

Panel berfungsi tetapi tiada mel diterima. Ini bukan masalah permulaan. Semak Settings dan SMTP terlebih dahulu. Kemudian semak log kempen itu sendiri dalam panel pentadbir. Log tersebut merekodkan ralat yang dikembalikan oleh pelayan mel bagi setiap percubaan.

FAQ

Adakah saya memerlukan pelayan mel sendiri untuk menggunakan Listmonk?

Tidak. Listmonk bukan pelayan mel. Ia memerlukan kelayakan SMTP untuk pelayan yang menerima dan menghantar mel anda. Pelayan itu boleh berupa geganti transaksi atau pelayan mel yang anda kendalikan sendiri. Tetapkan kelayakan tersebut di bawah Settings dan SMTP dalam panel pentadbir, bukan dalam config.toml, kerana tetapan mel disimpan dalam pangkalan data. Gunakan port 587 dengan STARTTLS atau port 465 dengan TLS implisit, kerana kebanyakan penyedia VPS menyekat port keluar 25 untuk akaun baharu.

Mengapakah pautan dalam kempen saya menghala ke localhost:9000?

Tetapan URL akar masih menggunakan nilai lalai pemasangan, iaitu http://localhost:9000. Listmonk menulis nilai tersebut ke dalam pautan nyahlanggan dan URL media apabila kempen dihantar. Buka Settings dalam panel pentadbir, tetapkan URL akar kepada alamat HTTPS sebenar anda, kemudian simpan. Mesej yang telah dihantar tidak boleh dibetulkan. Oleh itu, hantar kempen ujian kepada diri sendiri dan klik pautan nyahlanggan di dalamnya sebelum menghantar mel kepada senarai sebenar.

Adakah menjalankan --install sekali lagi akan memadamkan pelanggan saya?

Ya. --install ialah pemasang kali pertama dan ia menggugurkan skema Listmonk sedia ada. --yes mengalih keluar gesaan yang sepatutnya memberi amaran kepada anda. Dalam mana-mana skrip yang mungkin dijalankan dua kali, gunakan --install --idempotent --yes, yang tidak melakukan apa-apa jika jadual tersebut sudah wujud. Untuk menggunakan perubahan skema dalam keluaran baharu, hentikan perkhidmatan, buat pg_dump, kemudian jalankan --upgrade.

Mengapakah Listmonk memaparkan mesej password authentication failed for user listmonk?

Kata laluan dalam blok [db] dalam /etc/listmonk/config.toml tidak sepadan dengan peranan Postgres yang mempunyai nama yang sama. Baris jurnal ialah pq: password authentication failed for user "listmonk", manakala pq ialah pemacu Postgres yang menyampaikan penolakan daripada pelayan. Ini bermakna fail konfigurasi telah ditemui dan dibaca. Tetapkan semula kata laluan peranan tersebut dengan sudo -u postgres psql -c "ALTER USER listmonk WITH PASSWORD 'new-password';", tulis rentetan yang sama ke dalam fail konfigurasi, kemudian jalankan sudo systemctl restart listmonk.