Panduan

Oleh Matt Connor 2026-10-11

Cara Pasang Chaptarr untuk Buku Audio di VPS

Readarr telah ditamatkan sejak Jun 2025. Gunakan Chaptarr sebagai alternatif untuk mengurus buku audio dan e-buku melalui Docker Compose dengan konfigurasi PUID dan PGID.

Apakah Chaptarr dan sebab pengguna Readarr memerlukannya

Chaptarr ialah fork Readarr yang mengurus buku audio dan ebook daripada satu instance. Chaptarr memantau keluaran baharu, menghantarnya kepada klien muat turun anda, kemudian menamakan semula hasilnya dan menyusunnya ke dalam pustaka anda. Chaptarr tidak memainkan sebarang kandungan, jadi pasangkannya dengan pemain seperti Audiobookshelf.

Readarr dihentikan pada 27 June 2025. Notis pasukan Servarr sendiri menyatakan sebabnya: metadata projek itu sudah tidak boleh digunakan, manakala usaha komuniti untuk beralih ke Open Library terbantut. Repositori itu diarkibkan. Akibatnya, koleksi buku dan buku audio tidak lagi mempunyai pengurus yang diselenggara, lalu Chaptarr mengambil alih tugas tersebut. Chaptarr mengekalkan struktur yang biasa anda gunakan dalam Sonarr dan Radarr (pengindeks, klien muat turun, profil kualiti dan folder root), serta menambah pengendalian buku audio: penyusunan berdasarkan narator, berbilang edisi untuk satu judul, 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 August 2026. Setakat 11 October 2026, keluaran terbaharu ialah 0.9.965, yang diterbitkan pada 27 September 2026. Langkah di bawah hanya diuji pada 0.9.925, jadi fail tersebut mengekalkan tag itu; baca nota keluaran sebelum beralih kepada versi yang lebih baharu. Chaptarr menganggap dirinya sebagai perisian beta. Baca bahagian penyelenggaraan berhampiran penghujung panduan ini sebelum mengarahkannya kepada pustaka yang tidak boleh anda gantikan.

Perkara yang diperlukan sebelum anda bermula

VPS yang menjalankan Docker dan plugin Compose, serta ruang cakera yang mencukupi untuk pustaka. Buku audio menggunakan banyak ruang. Proses import yang tidak dapat menggunakan hardlink akan menyimpan dua salinan fail buat sementara waktu. Bahagian volume di bawah menerangkan keadaan ini. Jika Docker belum dipasang pada pelayan, mulakan dengan Docker telah dipasang dan sedang berjalan pada VPS, kemudian kembali ke sini.

Chaptarr buat masa ini hanya tersedia sebagai imej Docker. Sokongan natif masih dalam pembangunan. Binaan Windows percubaan dirancang, dan tiada pakej pengedaran disediakan. Secara lalai, kontena menyimpan pangkalan datanya dalam /config sebagai SQLite. Kontena juga boleh menggunakan pelayan PostgreSQL luaran melalui pemboleh ubah persekitaran Chaptarr__Postgres__* jika anda sudah menjalankan pelayan tersebut. SQLite ialah pilihan yang sesuai 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 Docker cipta sebagai root

Chaptarr menggunakan nilai lalai PUID=99 dan PGID=100 apabila anda tidak menetapkannya. Nilai tersebut ialah nilai unRAID. Pada VPS Ubuntu biasa, nilai itu tidak sepadan dengan pengguna yang boleh digunakan. Oleh itu, fail dicipta dengan pemilik yang akaun log masuk anda tidak boleh tulis. Baca nombor pengguna anda dengan id -u dan id -g, kemudian masukkan nilai tersebut ke dalam fail.

Setiap container yang mengakses fail yang sama memerlukan pasangan nilai yang sama. Klien muat turun menulis ke /srv/media/downloads, Chaptarr memindahkan fail ke /srv/media/audiobooks, dan pemain membaca fail itu di situ. Jika klien muat turun menulis sebagai 1000:1000 tetapi Chaptarr berjalan sebagai 99:100, proses import gagal. Pemilikan fail bukan penentu tunggal. Untuk mencipta, menamakan semula atau memadam fail, proses memerlukan permission tulis pada direktori yang menyimpan fail tersebut. Direktori yang dicipta oleh user 1000 dengan mode biasa 755 tidak memberikan 99:100 akses tulis. Oleh itu, Chaptarr tidak dapat memasukkan buku ke dalam pustaka atau memadamkannya daripada direktori muat turun. UMASK=002 menjadikan fail baharu boleh ditulis oleh group. Inilah yang diperlukan apabila beberapa container berkongsi satu media group. Pemetaan penuh diterangkan dalam cara PUID dan PGID memetakan pengguna container kepada fail pada host.

README memberikan amaran tentang satu perangkap khusus, dan perkara ini wajar diulangi. Jika ./config belum wujud apabila anda menjalankan docker compose up, Docker akan menciptanya secara automatik dengan pemilik root:root. Container itu kemudiannya berjalan sebagai UID 1000 dan tidak dapat menulis pangkalan datanya sendiri. Akibatnya, container berhenti dan dimulakan semula tanpa henti. Semak dengan ls -ln ./config, yang memaparkan pemilik dalam bentuk angka, bukan nama. Dua nilai sifar bermaksud root ialah pemiliknya. Betulkan dengan sudo chown -R 1000:1000 ./config, kemudian mulakan container itu semula.

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 berubah pantas

Chaptarr dilesenkan di bawah GPL-3.0, dengan hak cipta oleh penyumbang Chaptarr serta sebahagian kod daripada pasukan Servarr. Oleh itu, kodnya kekal terbuka dan sesiapa sahaja boleh membuat fork baharu jika penyelenggara ini berhenti. Chaptarr dibina pada .NET 10, iaitu keluaran sokongan jangka panjang semasa bagi runtime tersebut pada Ogos 2026. Ini bermakna asasnya disokong selama bertahun-tahun, bukan berbulan-bulan. Kedua-dua perkara ini penting apabila anda menilai sama ada projek ini masih akan wujud pada tahun hadapan.

Nombor versinya berubah dengan pantas. 0.9.925 diterbitkan pada 9 Ogos 2026, dan lima keluaran lagi menyusul dalam tempoh tujuh minggu berikutnya. Setiap keluaran sehingga 0.9.958 diterbitkan sebagai prapelancaran; 0.9.965 pada 27 September 2026 ialah keluaran pertama yang ditandai sebagai keluaran penuh. Tetapkan tag yang tepat. Menggunakan latest bermakna docker compose pull tanpa pengawasan boleh mengemas kini anda merentasi beberapa versi dalam seminggu. Fork yang masih baharu juga boleh mengubah API antara keluaran, lalu memecahkan mana-mana skrip atau papan pemuka yang anda bina berasaskannya. Menetapkan versi khusus ialah amalan yang wajar digunakan untuk setiap projek baharu yang anda hos sendiri. Atas sebab yang sama, panduan menjalankan openGym sebagai penjejak senaman yang dihoskan sendiri menggunakan deployment daripada tag git tetap.

Buat sandaran sebelum setiap naik taraf, kemudian jalankan naik taraf dengan 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 masih menasihatkan supaya sandaran disimpan dan supaya ia tidak diarahkan kepada pustaka yang anda tidak mampu kehilangan. Ambil serius kedua-dua perkara tersebut. Salin arkib konfigurasi keluar dari pelayan, kerana sandaran yang berada pada cakera yang sama dengan data yang dilindunginya bukanlah sandaran yang sebenar. Satu tarball itu mencukupi hanya kerana Chaptarr menyimpan keadaannya dalam satu fail SQLite di bawah /config. Apa-apa data pada pelayan pangkalan data berasingan juga perlu dieksport daripada pangkalan data tersebut. Inilah 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 pipeline penyedia sendiri. Oleh itu, pengecam yang disimpan oleh Readarr tidak mempunyai makna dan tiada penukaran pangkalan data. Fail pada cakera tidak diubah. Tambahkan path yang sama sebagai folder root, jalankan import pustaka dan biarkan Chaptarr memadankan fail itu sendiri. Profil kualiti, format penamaan, tetapan pengindeks dan sebarang padanan yang salah perlu dikendalikan secara manual. Jadi, mulakan dengan satu folder kecil sebelum mengimport semuanya.

Mengapakah Chaptarr tidak boleh menulis ke folder buku audio saya?

Pengguna dalam container tidak mempunyai kebenaran menulis ke direktori itu. Biasanya, container berjalan dengan UID yang berbeza daripada UID pemilik direktori tersebut. Chaptarr menggunakan PUID=99 dan PGID=100 apabila pemboleh ubah itu tidak ditetapkan. Nilai tersebut ialah nilai unRAID dan salah pada VPS Ubuntu biasa. Tetapkan pemboleh ubah itu kepada id -u dan id -g anda sendiri. Gunakan pasangan yang sama pada klien muat turun. Tetapkan UMASK=002 supaya fail baharu kekal boleh ditulis oleh kumpulan. Semak pemilikan dengan ls -ln pada direktori pustaka. Perintah itu memaparkan nombor, bukan nama, supaya anda boleh membuat perbandingan.

Mengapakah penggunaan cakera saya berganda selepas import?

Chaptarr menyalin fail kerana tidak dapat membuat hard link. Melekapkan /downloads dan /audiobooks sebagai bind berasingan menjadikannya titik lekapan berasingan dalam container. Kernel menolak hard link merentasi titik lekapan dengan Invalid cross-device link. Lekapkan satu direktori induk seperti /srv/media:/data dan gunakan /data/downloads serta /data/audiobooks dalam aplikasi. Kedua-dua path itu juga mesti berada pada satu sistem fail hos. df -h mengesahkan perkara ini.

Adakah Chaptarr memainkan buku audio saya?

Tidak. Chaptarr mencari, memuat turun, menamakan semula dan menyusun fail tersebut. Playback dilakukan oleh program berasingan. Audiobookshelf ialah gandingan yang biasa digunakan kerana ia mengingati kedudukan anda merentas peranti. Gunakan imej rasmi ghcr.io/advplyr/audiobookshelf:latest dan lekapkan path buku audio hos yang sama. Jellyfin juga boleh memainkan fail tersebut jika anda menambahkan folder itu sebagai pustaka. Namun, fungsi menyambung playback lebih lemah untuk buku audio panjang yang disimpan sebagai satu fail.

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

Chaptarr ialah perisian beta daripada fork yang masih baharu. Projek itu sendiri menyatakan perkara ini, sambil melaporkan tiada kejadian kehilangan data selama kira-kira enam bulan dan melibatkan lebih daripada sebelas ribu pengguna. Faktor yang meyakinkan termasuk lesen GPL-3.0, yang membolehkan kod terus difork, serta asas .NET 10, iaitu runtime sokongan jangka panjang pada Ogos 2026. Tetapkan tag imej yang tepat seperti 0.9.925, bukan latest. Sandarkan /config sebelum setiap upgrade dan simpan arkib tersebut di luar pelayan.

#chaptarr#audiobooks#arr-stack #docker-compose #self-hosting