Cara Pasang Chaptarr untuk Buku Audio di VPS

Apakah itu Chaptarr, dan mengapa pengguna Readarr memerlukannya

Chaptarr ialah fork bagi Readarr yang mengurus buku audio dan e-buku daripada satu instans. Ia memantau keluaran baharu, menghantarnya ke klien muat turun anda, kemudian menamakan semula hasil tersebut dan menyimpannya ke dalam pustaka anda. Ia tidak memainkan sebarang fail, jadi anda perlu menggandingkannya dengan pemain seperti Audiobookshelf.

Readarr telah ditamatkan pada 27 Jun 2025. Notis daripada pasukan Servarr sendiri menyatakan sebabnya: metadata projek tersebut telah menjadi tidak boleh digunakan, dan usaha komuniti untuk beralih ke Open Library telah terhenti. Repositori tersebut kini diarkibkan. Keadaan ini menyebabkan koleksi buku dan buku audio tidak mempunyai pengurus yang diselenggara, dan Chaptarr mengambil alih tugas tersebut. Ia mengekalkan bentuk yang anda sudah kenali daripada Sonarr dan Radarr (indexer, klien muat turun, profil kualiti, folder root) serta menambah pengendalian buku audio: penyusunan berdasarkan pencerita, berbilang edisi bagi satu tajuk, sokongan M4B dan MP3 berbab, serta penukaran MP3 kepada M4B.

Panduan ini menggunakan tag imej chaptarr/chaptarr:0.9.925, yang merupakan keluaran terbaharu pada 9 Ogos 2026. Chaptarr melabelkan dirinya sebagai perisian beta. Baca bahagian penyelenggaraan di penghujung panduan sebelum anda menghalakannya ke pustaka yang anda tidak boleh ganti.

Keperluan sebelum bermula

Sebuah VPS yang menjalankan Docker dan pemalam Compose, serta ruang cakera yang mencukupi untuk pustaka anda. Buku audio bersaiz besar, dan proses import yang tidak dapat menggunakan hardlink akan menyimpan dua salinan fail untuk sementara waktu, seperti yang dijelaskan dalam bahagian volum di bawah. Jika Docker belum dipasang pada pelayan anda, mulakan dengan Docker dipasang dan berjalan pada VPS dan kembali ke sini.

Chaptarr kini hanya diedarkan sebagai imej Docker. Binaan asli untuk Windows disenaraikan sebagai dalam pembangunan, dan tiada pakej pengedaran disediakan. Bekas (container) ini menyimpan pangkalan datanya dalam /config sebagai SQLite secara lalai, dan ia boleh menggunakan pelayan PostgreSQL luaran melalui pemboleh ubah persekitaran Chaptarr__Postgres__* jika anda sudah menjalankannya. SQLite ialah pilihan yang tepat untuk seorang pengguna pada satu pelayan.

Servis Compose untuk Chaptarr

Servis ini disepadukan ke dalam stack sedia ada. Ia menetapkan tag keluaran, menerbitkan UI web pada loopback sahaja, dan menyertai rangkaian yang digunakan oleh klien muat turun anda.

services:
  chaptarr:
    image: chaptarr/chaptarr:0.9.925
    container_name: chaptarr
    environment:
      - PUID=1000
      - PGID=1000
      - UMASK=002
      - TZ=Europe/Berlin
    volumes:
      - ./config:/config
      - /srv/media/audiobooks:/audiobooks
      - /srv/media/ebooks:/ebooks
      - /srv/media/downloads:/downloads
    ports:
      - 127.0.0.1:8789:8789
    restart: unless-stopped
    networks:
      - arr

networks:
  arr:
    external: true

Baris external: true bermaksud "rangkaian ini sudah wujud, sambungkan kepadanya". Gunakan arahan ini apabila Prowlarr dan klien torrent anda berasal daripada projek Compose yang berbeza, kerana fail Compose kedua akan mencipta rangkaian terasingnya sendiri dan Chaptarr tidak akan dapat menyelesaikan qbittorrent mengikut nama. Dapatkan nama sebenar daripada docker network ls. Jika stack anda sudah berada dalam satu fail, tambahkan servis chaptarr: ke dalam fail tersebut dan padamkan keseluruhan blok networks:. Susun atur yang lebih luas diliputi dalam stack arr penuh di bawah Docker Compose, dan peraturan penamaan dalam cara rangkaian Compose dan nama servis diselesaikan.

Cipta direktori konfigurasi sendiri, kemudian mulakannya.

mkdir -p ./config
sudo chown 1000:1000 ./config
docker compose up -d
docker compose ps
docker compose logs -f chaptarr

docker compose ps sepatutnya menunjukkan kontena sebagai Up. Kontena yang disenaraikan sebagai Restarting telah gagal bermula dan sedang dicuba semula, dan puncanya hampir selalu disebabkan oleh direktori konfigurasi. Log akan berhenti menatal sebaik sahaja aplikasi mendengar pada port 8789.

PUID, PGID, dan direktori yang dicipta oleh Docker sebagai root

Chaptarr menggunakan PUID=99 dan PGID=100 secara lalai apabila anda membiarkannya tidak ditetapkan. Nilai tersebut adalah nilai untuk unRAID, dan pada VPS Ubuntu biasa, nilai tersebut tidak merujuk kepada pengguna yang berguna, jadi fail akan disimpan dengan pemilik yang tidak boleh ditulis oleh akaun log masuk anda. Baca nombor anda sendiri dengan id -u dan id -g dan masukkan nilai tersebut ke dalam fail.

Setiap kontena yang mengakses fail yang sama memerlukan pasangan nilai yang sama. Pelanggan muat turun menulis ke dalam /srv/media/downloads, Chaptarr memindahkan fail tersebut ke /srv/media/audiobooks, dan pemain media membacanya di sana. Jika pelanggan muat turun menulis sebagai 1000:1000 dan Chaptarr berjalan sebagai 99:100, proses import akan gagal kerana Chaptarr tidak boleh memadam atau memindahkan fail yang bukan miliknya. UMASK=002 menjadikan fail baharu boleh ditulis oleh kumpulan, iaitu perkara yang anda perlukan apabila beberapa kontena berkongsi satu kumpulan media. Pemetaan penuh terdapat dalam bagaimana PUID dan PGID memetakan pengguna kontena kepada fail hos.

README memberi amaran tentang satu perangkap khusus, dan ia perlu diulangi. Jika ./config tidak wujud apabila anda menjalankan docker compose up, Docker akan menciptakannya untuk anda, dengan pemilikan oleh root:root. Kontena tersebut kemudian berjalan sebagai UID 1000 dan tidak boleh menulis pangkalan datanya sendiri, jadi ia akan berhenti dan dimulakan semula selama-lamanya. Semak dengan ls -ln ./config, yang memaparkan pemilik dalam bentuk angka dan bukannya nama. Dua sifar bermakna root adalah pemiliknya. Betulkan dengan sudo chown -R 1000:1000 ./config dan mulakan semula kontena tersebut.

Mengapa volum buku audio dan e-buku yang diasingkan menyebabkan masalah hardlink

Susun atur di atas melekapkan /audiobooks, /ebooks dan /downloads sebagai bind yang berasingan, selaras dengan arahan jalankan projek itu sendiri. Ia mudah dibaca, namun mempunyai satu kos sebenar: hardlink tidak lagi berfungsi.

Hardlink ialah nama kedua bagi data yang sama pada cakera. Ia tidak menggunakan ruang tambahan dan berlaku serta-merta, itulah sebabnya keluarga arr lebih mengutamakannya berbanding penyalinan. Hardlink hanya berfungsi di dalam satu sistem fail. Di dalam kontena, ini adalah tiga titik lekap (mount point) yang berasingan, jadi kernel menolak pautan tersebut walaupun laluan hos berada pada cakera yang sama. Uji sendiri.

docker exec chaptarr sh -c 'touch /downloads/linktest && ln /downloads/linktest /audiobooks/linktest'

Arahan tersebut gagal dengan ralat yang berakhir dengan Invalid cross-device link. Itu adalah tindakan kernel yang menolak untuk memaut merentasi titik lekap, dan itulah sebab tepat mengapa Chaptarr kembali kepada penyalinan fail. Salinan tersebut adalah betul tetapi lebih perlahan, dan buku audio tersebut kemudian wujud dua kali sehingga anda membuang torrent tersebut, yang mana anda tidak akan lakukannya semasa anda masih melakukan seeding. Padam /srv/media/downloads/linktest selepas itu.

Untuk mengekalkan hardlink, lekapkan satu direktori induk sebaliknya:

    volumes:
      - ./config:/config
      - /srv/media:/data

Kemudian tetapkan folder root di dalam Chaptarr kepada /data/audiobooks dan /data/ebooks, dan berikan klien muat turun titik lekap /srv/media:/data yang sama supaya kedua-dua kontena melihat satu laluan yang serupa. Sahkan dahulu bahawa bahagian hos adalah satu sistem fail tunggal: df -h /srv/media/downloads /srv/media/audiobooks mesti mencetak nilai yang sama dalam lajur Filesystem untuk kedua-duanya. Nilai yang berbeza bermakna cakera yang berbeza, dan tiada susun atur lekap yang boleh melakukan hardlink merentasinya. Pertukaran antara ini dan storan bernama dibincangkan dalam bind mounts against named volumes for media.

Mencapai UI web tanpa mendedahkannya

Baris port diterbitkan pada 127.0.0.1 atas sebab tertentu. ufw deny 8789 tidak melindungi port Docker yang diterbitkan, kerana Docker menulis peraturan NAT (network address translation) miliknya sendiri ke dalam rantaian yang dicapai oleh kernel sebelum rantaian ufw, jadi trafik akan diteruskan sebelum peraturan anda sempat dirujuk. Gelagat ini sering memerangkap pengguna, dan ia dijelaskan dalam mengapa port Docker yang diterbitkan mengabaikan peraturan ufw anda. Melakukan binding pada loopback akan memintas perkara ini sepenuhnya.

Capai UI tersebut melalui terowong SSH daripada mesin anda sendiri:

ssh -N -L 8789:127.0.0.1:8789 you@your-server

Biarkan ia berjalan dan buka http://127.0.0.1:8789 dalam pelayar anda. Sediakan pengesahan pada kali pertama ia dijalankan. Hanya selepas itu anda patut mempertimbangkan reverse proxy dengan TLS (transport layer security) di hadapannya. Apabila anda sudah melakukan tunneling ke dalam tiga atau empat alat ini dengan kata laluan berasingan bagi setiap satu, jawapan yang lebih kemas adalah dengan meletakkan proksi di belakang pelayan daftar masuk tunggal (single sign-on) yang dihoskan sendiri seperti Authentik, supaya satu log masuk merangkumi setiap aplikasi dan satu pembatalan akan menutup kesemuanya.

Menyambungkan pengindeks dan klien muat turun

Chaptarr menggunakan protokol pengindeks dan klien muat turun standard arr, jadi Prowlarr menolak pengindeks ke dalamnya dengan cara yang sama seperti Sonarr, dan klien torrent serta usenet biasa boleh disambungkan tanpa pengendalian khas.

Satu tetapan sering memerangkap hampir semua pengguna. Apabila Chaptarr meminta hos klien muat turun, jangan taip localhost atau 127.0.0.1. Di dalam kontena, alamat tersebut merujuk kepada kontena itu sendiri, jadi Chaptarr akan cuba berhubung dengan port 8080 miliknya sendiri dan melaporkan bahawa ia tidak dapat bersambung. Gunakan nama kontena, qbittorrent, dengan port 8080. Sahkan kedua-dua kontena berada pada rangkaian yang sama dengan docker network inspect arr, yang menyenaraikan setiap kontena yang disambungkan mengikut nama.

Jika klien muat turun anda berjalan melalui kontena VPN dengan network_mode: "service:gluetun", ia tidak mempunyai nama sendiri pada rangkaian kerana ia berkongsi ruang nama rangkaian Gluetun. Alamatnya sebagai gluetun pada port yang didedahkan oleh Gluetun. Susunan tersebut, serta penghalaan yang berkaitan dengannya, terdapat dalam penghalaan klien muat turun melalui Gluetun.

Peralihan Readarr: kos sebenar migrasi

Chaptarr tidak serasi dengan sumber metadata Readarr. Ia menyelesaikan tajuk, penulis dan edisi melalui talian paipnya sendiri merentasi beberapa penyedia, jadi pengecam yang disimpan oleh Readarr tidak membawa makna di sini. Tiada import pangkalan data dan tiada laluan naik taraf terus (drop-in).

Bagi pustaka sedia ada, ini bermakna fail anda selamat tetapi tetapan tidak. Tiada apa-apa dalam proses ini yang menyentuh perkara yang sudah ada pada cakera. Anda menambah folder akar, menjalankan import pustaka, dan Chaptarr memadankan fail yang ditemuinya dengan metadata miliknya sendiri. Perkara yang perlu anda bina semula secara manual: profil kualiti, format penamaan, tetapan indexer dan klien, serta setiap padanan yang salah diteka oleh Chaptarr. Pustaka yang besar akan memerlukan satu pusingan pembetulan manual, jadi peruntukkan masa satu malam dan bukannya sepuluh minit.

Lakukan mengikut urutan ini. Hentikan kontena Readarr tetapi kekalkan volum konfigurasinya, supaya anda masih boleh membaca tetapan lama anda semasa anda menaipnya semula. Halakan Chaptarr ke satu folder kecil dahulu dan semak padanan sebelum anda mengimport semuanya. Hanya buang kontena lama setelah anda berpuas hati.

Satu perincian privasi yang perlu diketahui sebelum anda mengimbas keseluruhan pustaka: carian metadata pergi ke api2.chaptarr.com. README menyatakan bahawa permintaan tersebut boleh membawa ID penyedia, teks carian, jenis media, tag dan nama fail, serta ia mengecualikan laluan penuh, identiti pengguna dan kelayakan. Nama fail akan meninggalkan pelayan anda. Itu adalah perkara biasa bagi perkhidmatan metadata, dan anda tetap perlu memutuskannya secara sengaja.

Serahkan buku audio kepada pemain

Chaptarr menyusun fail. Memainkan fail tersebut adalah tugas program lain, dan Audiobookshelf merupakan rakan yang biasa digunakan kerana ia menjejaki kedudukan pendengaran anda merentas peranti serta mempunyai aplikasi telefon. Imej rasminya ialah ghcr.io/advplyr/audiobookshelf:latest, dan contoh Compose yang didokumentasikan menerbitkan port hos 13378 ke port kontena 80.

  audiobookshelf:
    image: ghcr.io/advplyr/audiobookshelf:latest
    container_name: audiobookshelf
    ports:
      - 127.0.0.1:13378:80
    volumes:
      - ./abs/config:/config
      - ./abs/metadata:/metadata
      - /srv/media/audiobooks:/audiobooks
    environment:
      - TZ=Europe/Berlin
    restart: unless-stopped

Lekapkan laluan hos yang sama tempat Chaptarr menulis, kemudian tambah /audiobooks sebagai pustaka di dalam UI web. Import baharu akan muncul selepas imbasan seterusnya.

Jika anda sudah menjalankan Jellyfin, anda boleh menambah folder tersebut sebagai pustaka di sana dan ia akan memainkan fail tersebut, walaupun tingkah laku sambung semula pada satu fail buku audio yang panjang adalah kurang berkesan berbanding pelayan buku audio khusus. Penyediaan bahagian tersebut diliputi dalam menjalankan Jellyfin sebagai pelayan media pada VPS. Bagi bahagian e-buku, serahkan /srv/media/ebooks kepada aplikasi pembaca; tugas Chaptarr berakhir sebaik sahaja fail dinamakan dan difailkan.

Risiko penyelenggaraan: lesen, runtime, dan tag yang pantas berubah

Chaptarr dilesenkan di bawah GPL-3.0, hak cipta milik penyumbang Chaptarr dengan bahagian tertentu daripada pasukan Servarr, jadi kodnya kekal terbuka dan sesiapa sahaja boleh melakukan fork semula jika penyelenggara ini berhenti. Ia dibina menggunakan .NET 10, iaitu keluaran sokongan jangka panjang (LTS) semasa bagi runtime tersebut setakat Ogos 2026, yang bermaksud asasnya disokong untuk tempoh bertahun-tahun dan bukannya berbulan-bulan. Kedua-dua fakta ini penting jika anda menilai sama ada projek ini masih akan wujud pada tahun hadapan.

Nombor versi berubah dengan pantas. Keluaran diterbitkan sebagai pra-keluaran, dan 0.9.925 dilancarkan pada hari yang sama dengan panduan ini. Tetapkan tag yang tepat. Menggunakan latest bermakna docker compose pull tanpa pengawasan boleh menyebabkan anda beralih beberapa versi dalam seminggu, dan fork yang masih baharu ini boleh mengubah API-nya antara keluaran, yang akan merosakkan sebarang skrip atau papan pemuka yang anda tulis untuknya.

Lakukan sandaran sebelum setiap naik taraf, kemudian lakukan naik taraf secara sengaja.

docker compose stop chaptarr
sudo tar czf chaptarr-config-backup.tgz ./config
docker compose start chaptarr

docker compose pull chaptarr
docker compose up -d chaptarr

Projek ini melaporkan tiada kejadian kehilangan data sepanjang kira-kira enam bulan dan melibatkan lebih daripada sebelas ribu pengguna. Namun, projek ini tetap menyarankan supaya sandaran disimpan dan aplikasi tidak diarahkan kepada pustaka yang tidak mampu anda kehilangan. Ambil serius kedua-dua perkara tersebut. Salin arkib konfigurasi keluar dari pelayan. Sandaran yang disimpan pada cakera yang sama dengan data yang dilindunginya bukanlah sandaran. Satu fail tarball itu mencukupi hanya kerana Chaptarr menyimpan keadaannya dalam satu fail SQLite di bawah /config. Sebarang data yang berada pada pelayan pangkalan data berasingan juga memerlukan pembuangan pangkalan data. Itulah bentuk langkah sandaran apabila mengehos sendiri Chatwoot pada VPS bersama data Postgres dan fail yang dimuat naik.

Mod kegagalan, berserta rentetan yang akan anda lihat

Kontena dimulakan semula dalam gelung. docker compose ps menunjukkan Restarting. Jalankan ls -ln ./config. Dua sifar dalam lajur pemilik bermakna Docker mencipta direktori sebagai root dan pengguna kontena tidak boleh menulis ke dalam pangkalan datanya. Jalankan sudo chown -R 1000:1000 ./config.

Import tidak pernah selesai dan fail kekal dalam muat turun. Chaptarr boleh membaca muat turun tetapi tidak boleh menulis ke dalam pustaka. Bandingkan ls -ln /srv/media/audiobooks dengan PUID dan PGID anda. Direktori yang dimiliki oleh UID berbeza, atau dimiliki oleh kumpulan anda tanpa kebenaran tulis kumpulan, akan menghalang pemindahan tersebut. UMASK=002 menghalang kes kedua bagi fail baharu.

Penggunaan cakera berganda selepas setiap import. Tiada hardlink dibuat, jadi fail tersebut telah disalin. Jalankan ujian ln daripada bahagian volum. Ralat yang berakhir dengan Invalid cross-device link mengesahkannya, dan pelekap induk tunggal (single-parent mount) adalah penyelesaiannya.

Klien muat turun tidak mahu bersambung. Anda memasukkan localhost sebagai hos. Di dalam kontena, itu adalah Chaptarr itu sendiri. Gunakan nama kontena dan semak sama ada docker network inspect arr menyenaraikan kedua-dua kontena.

Compose enggan memulakan servis. Bind for 127.0.0.1:8789 failed: port is already allocated bermakna sesuatu yang lain memegang port tersebut. Cari puncanya dengan sudo ss -lntp | grep 8789.

Pelayar tidak menunjukkan apa-apa langsung. Dengan port diikat pada 127.0.0.1, tiada apa-apa untuk komputer riba anda bersambung melalui internet. Itu adalah tingkah laku yang dijangkakan. Buka terowong SSH terlebih dahulu.

FAQ

Bolehkah saya memindahkan pustaka Readarr saya ke Chaptarr?

Bukan sebagai import. Chaptarr tidak serasi dengan sumber metadata Readarr dan menggunakan saluran pembekal (provider pipeline) tersendiri, jadi pengecam yang disimpan oleh Readarr tidak membawa makna dan tiada penukaran pangkalan data. Fail anda pada cakera tidak disentuh. Anda perlu menambah laluan yang sama sebagai root folders, jalankan import pustaka, dan biarkan Chaptarr memadankan fail tersebut sendiri. Profil kualiti, format penamaan, tetapan indexer dan sebarang padanan yang salah perlu dilakukan secara manual, jadi mulakan dengan satu folder kecil sebelum mengimport semuanya.

Mengapa Chaptarr tidak boleh menulis ke folder buku audio saya?

Pengguna kontena tidak memiliki fail tersebut. Chaptarr akan kembali kepada PUID=99 dan PGID=100 apabila pemboleh ubah tersebut tidak ditetapkan, yang merupakan nilai unRAID dan salah pada VPS Ubuntu biasa. Tetapkan nilai tersebut kepada id -u dan id -g anda sendiri, gunakan pasangan yang sama pada klien muat turun, dan tetapkan UMASK=002 supaya fail baharu kekal boleh ditulis oleh kumpulan (group-writable). Semak pemilikan dengan ls -ln pada direktori pustaka, kerana ia mencetak nombor dan bukannya nama, jadi anda tidak boleh membandingkannya secara terus.

Mengapa penggunaan cakera saya meningkat dua kali ganda selepas import?

Chaptarr menyalin fail tersebut kerana ia tidak dapat melakukan hardlink. Melekapkan /downloads dan /audiobooks sebagai bind yang berasingan menjadikannya titik lekap (mount point) yang berbeza di dalam kontena, dan kernel menolak hardlink merentasi titik lekap dengan ralat Invalid cross-device link. Lekapkan satu direktori induk seperti /srv/media:/data dan gunakan /data/downloads serta /data/audiobooks di dalam aplikasi. Kedua-dua laluan juga mesti berada pada satu sistem fail hos yang sama, yang disahkan oleh df -h.

Adakah Chaptarr memainkan buku audio saya?

Tidak. Ia mencari, memuat turun, menamakan semula dan menyusun fail tersebut, manakala main balik adalah program yang berasingan. Audiobookshelf ialah pasangan yang biasa digunakan kerana ia mengingati kedudukan anda merentasi peranti, menggunakan imej rasmi ghcr.io/advplyr/audiobookshelf:latest dengan laluan buku audio hos yang sama dilekapkan. Jellyfin juga akan memainkan fail tersebut jika anda menambah folder itu sebagai pustaka, dengan prestasi penyambungan semula (resume) yang lebih lemah pada buku audio fail tunggal yang panjang.

Adakah Chaptarr selamat untuk dijalankan pada pustaka yang penting bagi saya?

Ia merupakan perisian beta daripada fork yang baharu, dan projek itu sendiri menyatakan perkara tersebut walaupun tiada kejadian kehilangan data dilaporkan sepanjang kira-kira enam bulan dengan lebih sebelas ribu pengguna. Bahagian yang meyakinkan ialah lesen GPL-3.0, yang membolehkan kod tersebut di-fork, dan asas .NET 10, iaitu runtime sokongan jangka panjang (LTS) setakat Ogos 2026. Pin tag imej yang tepat seperti 0.9.925 dan bukannya latest, sandarkan /config sebelum setiap naik taraf, dan simpan arkib tersebut di luar pelayan.