آموزش نصب Chaptarr برای مدیریت کتاب صوتی روی VPS

Chaptarr چیست و چرا کاربران Readarr به آن نیاز دارند

Chaptarr یک انشعاب (fork) از Readarr است که کتاب‌های صوتی و الکترونیکی را از یک نمونه واحد مدیریت می‌کند. این برنامه انتشار نسخه‌های جدید را پایش کرده، آن‌ها را به کلاینت دانلود شما می‌فرستد و سپس نتایج را تغییر نام داده و در کتابخانه شما دسته‌بندی می‌کند. این برنامه قابلیت پخش فایل ندارد، بنابراین باید آن را با یک پخش‌کننده مانند Audiobookshelf جفت کنید.

پروژه Readarr در تاریخ 27 June 2025 بازنشسته شد. اطلاعیه رسمی تیم Servarr دلیل این امر را این‌گونه بیان می‌کند: متادیتای پروژه غیرقابل استفاده شده بود و تلاش جامعه کاربری برای انتقال به Open Library متوقف شد. مخزن این پروژه اکنون آرشیو شده است. این وضعیت باعث شد مجموعه‌های کتاب و کتاب صوتی بدون یک مدیر نگهداری‌شده باقی بمانند و Chaptarr این وظیفه را بر عهده گرفت. این برنامه ساختاری که از Sonarr و Radarr می‌شناسید (ایندکسرها، کلاینت‌های دانلود، پروفایل‌های کیفیت، پوشه‌های ریشه) را حفظ کرده و قابلیت‌های مدیریت کتاب صوتی را به آن می‌افزاید: سازمان‌دهی بر اساس گوینده، مدیریت نسخه‌های متعدد از یک عنوان، پشتیبانی از M4B و MP3های فصل‌بندی‌شده، و تبدیل MP3 به M4B.

این راهنما از تگ ایمیج chaptarr/chaptarr:0.9.925 استفاده کرده است که جدیدترین نسخه در تاریخ 9 August 2026 بود. تا تاریخ 11 October 2026، جدیدترین نسخه 0.9.965 است که در 27 September 2026 منتشر شده است. مراحل زیر فقط روی نسخه 0.9.925 تست شده‌اند، بنابراین فایل‌ها همان تگ را حفظ می‌کنند؛ پیش از ارتقا به نسخه‌های جدیدتر، یادداشت‌های انتشار (release notes) را مطالعه کنید. Chaptarr خود را نرم‌افزار بتا معرفی می‌کند. پیش از آنکه آن را به کتابخانه‌ای که امکان جایگزینی آن را ندارید متصل کنید، بخش نگهداری (maintenance) در انتهای این متن را بخوانید.

پیش‌نیازهای شروع کار

یک VPS که Docker و افزونه Compose روی آن نصب باشد، و فضای دیسک کافی برای کتابخانه. کتاب‌های صوتی حجم زیادی دارند و فرآیندی که نتواند از hardlink استفاده کند، برای مدتی دو نسخه از یک فایل را نگه می‌دارد که در بخش volume در ادامه توضیح داده شده است. اگر Docker هنوز روی سرور شما نصب نیست، با نصب و اجرای Docker روی VPS شروع کنید و سپس به اینجا بازگردید.

Chaptarr در حال حاضر فقط به صورت Docker image عرضه می‌شود. پشتیبانی بومی (Native) در حال توسعه است، یک نسخه آزمایشی برای Windows در برنامه قرار دارد و هیچ بسته توزیعی (distribution package) برای آن وجود ندارد. این کانتینر به‌طور پیش‌فرض پایگاه‌داده خود را در /config به صورت SQLite ذخیره می‌کند و اگر از قبل یک سرور PostgreSQL دارید، می‌تواند از طریق متغیرهای محیطی Chaptarr__Postgres__* از آن استفاده کند. برای یک کاربر روی یک سرور، SQLite انتخاب مناسبی است.

سرویس Compose برای Chaptarr

این سرویس در یک stack موجود قرار می‌گیرد. این پیکربندی یک تگ منتشرشده را ثابت (pin) می‌کند، رابط کاربری وب را فقط روی loopback منتشر می‌کند و به شبکه‌ای که کلاینت دانلود شما هم‌اکنون از آن استفاده می‌کند، متصل می‌شود.

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

خط external: true به این معناست که «این شبکه از قبل وجود دارد، به آن متصل شو». زمانی از این گزینه استفاده کنید که Prowlarr و کلاینت تورنت شما از یک پروژه Compose متفاوت آمده باشند؛ زیرا در غیر این صورت، فایل Compose دوم شبکه ایزولهٔ خودش را می‌سازد و Chaptarr هرگز نمی‌تواند qbittorrent را از طریق نام پیدا کند. نام واقعی را از docker network ls به دست آورید. اگر stack شما هم‌اکنون در یک فایل واحد قرار دارد، سرویس chaptarr: را به همان فایل اضافه کرده و کل بلوک networks: را حذف کنید. طرح کلی‌تر در یک stack کامل arr تحت Docker Compose و قوانین نام‌گذاری در نحوه حل نام‌های سرویس و شبکه‌های Compose پوشش داده شده است.

دایرکتوری پیکربندی را خودتان ایجاد کنید و سپس آن را استارت بزنید.

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

docker compose ps باید کانتینر را به صورت Up نشان دهد. کانتینری که به صورت Restarting لیست شده باشد، در شروع کار شکست خورده و در حال تلاش مجدد است؛ لاگ‌های آن را بخوانید تا علت را بیابید. پس از آنکه برنامه روی پورت 8789 شروع به گوش دادن کرد، لاگ از اسکرول کردن باز می‌ایستد.

PUID، PGID و دایرکتوری‌هایی که Docker با دسترسی root ایجاد می‌کند

اگر مقادیر PUID=99 و PGID=100 را تنظیم نکنید، Chaptarr به‌صورت پیش‌فرض از آن‌ها استفاده می‌کند. این مقادیر مربوط به unRAID هستند و در یک VPS معمولی با سیستم‌عامل Ubuntu به کاربری معتبر اشاره نمی‌کنند؛ در نتیجه فایل‌ها با مالکی ایجاد می‌شوند که حساب کاربری شما اجازه نوشتن در آن‌ها را ندارد. شماره‌های کاربری خود را با دستورات id -u و id -g مشاهده کرده و در فایل وارد کنید.

هر کانتینری که با این فایل‌ها سروکار دارد، باید از همان جفت UID و GID استفاده کند. کلاینت دانلود در /srv/media/downloads می‌نویسد، Chaptarr فایل را به /srv/media/audiobooks منتقل می‌کند و پخش‌کننده آن را از آنجا می‌خواند. اگر کلاینت دانلود با 1000:1000 بنویسد و Chaptarr با 99:100 اجرا شود، عملیات import با شکست مواجه می‌شود. مالکیت فایل تعیین‌کننده نیست؛ ایجاد، تغییر نام یا حذف فایل نیازمند دسترسی نوشتن در دایرکتوری والد است. دایرکتوری‌هایی که توسط کاربر 1000 و با حالت معمول 755 ایجاد می‌شوند، به 99:100 اجازه نوشتن نمی‌دهند؛ بنابراین Chaptarr نمی‌تواند کتاب را در کتابخانه ثبت کند یا آن را از پوشه دانلودها پاک کند. تنظیم UMASK=002 باعث می‌شود فایل‌های جدید توسط گروه قابل‌نوشتن باشند؛ این دقیقاً همان چیزی است که هنگام اشتراک‌گذاری یک گروه رسانه‌ای بین چندین کانتینر به آن نیاز دارید. نگاشت کامل در نحوه نگاشت PUID و PGID کانتینر به فایل‌های میزبان توضیح داده شده است.

فایل README توصیه می‌کند ابتدا دایرکتوری config را ایجاد کنید و از override کردن user: در Compose خودداری کنید. اگر هنگام اجرای docker compose up، دایرکتوری ./config وجود نداشته باشد، Docker آن را با مالکیت root:root برای شما ایجاد می‌کند. در image نسخه 0.9.925، نقطه ورود (entrypoint) ابتدا با دسترسی root اجرا می‌شود و پیش از تغییر سطح دسترسی به UID و GID تنظیم‌شده، مالکیت /config و فایل‌های دیتابیس آن را اصلاح می‌کند؛ بنابراین دایرکتوری جدیدی که توسط root ایجاد شده، معمولاً باعث ایجاد حلقه راه‌اندازی مجدد (restart loop) نمی‌شود. استفاده از override برای user: این تنظیمات را دور می‌زند و یک mount فقط‌خواندنی یا فایل‌سیستمی که اجازه تغییر مالکیت را نمی‌دهد، همچنان می‌تواند مانع نوشتن دیتابیس شود. با استفاده از ls -ln ./config وضعیت را بررسی کنید؛ این دستور مالکیت عددی را به‌جای نام نمایش می‌دهد. دو صفر به این معنی است که مالک آن root است. اگر لاگ‌ها خطای دسترسی (permissions failure) در یک دایرکتوری محلی قابل‌نوشتن را تأیید کردند، آن را با sudo chown -R 1000:1000 ./config اصلاح کرده و کانتینر را دوباره اجرا کنید.

چرا جدا کردن حجم‌های کتاب صوتی و کتاب الکترونیکی باعث از دست رفتن hardlinkها می‌شود

ساختار بالا، /audiobooks، /ebooks و /downloads را به عنوان bind mountهای جداگانه متصل می‌کند که با دستور اجرای خود پروژه مطابقت دارد. این ساختار خوانایی بالایی دارد، اما یک هزینهٔ واقعی به همراه دارد: hardlinkها از کار می‌افتند.

یک hardlink در واقع نام دومی برای همان داده‌های موجود روی دیسک است. این قابلیت فضای اضافی اشغال نمی‌کند و بلافاصله انجام می‌شود؛ به همین دلیل است که خانوادهٔ arr آن را به کپی کردن ترجیح می‌دهند. یک hardlink فقط در داخل یک فایل‌سیستم کار می‌کند. در داخل کانتینر، این‌ها سه نقطهٔ اتصال (mount point) مجزا هستند، بنابراین هستهٔ سیستم‌عامل حتی زمانی که مسیرهای میزبان روی یک دیسک قرار دارند، از ایجاد لینک خودداری می‌کند. خودتان تست کنید.

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

این دستور با خطایی که به Invalid cross-device link ختم می‌شود، شکست می‌خورد. این همان واکنش هسته برای جلوگیری از لینک کردن بین نقاط اتصال مختلف است و دقیقاً به همین دلیل است که Chaptarr به کپی کردن فایل روی می‌آورد. کپی کردن صحیح است اما کندتر انجام می‌شود و کتاب صوتی تا زمانی که تورنت را حذف نکنید، دو بار روی دیسک وجود خواهد داشت؛ کاری که تا زمانی که در حال seeding هستید، انجام نخواهید داد. پس از آن /srv/media/downloads/linktest را حذف کنید.

برای حفظ hardlinkها، به جای آن یک دایرکتوری والد را mount کنید:

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

سپس پوشه‌های root را در داخل Chaptarr روی /data/audiobooks و /data/ebooks تنظیم کنید و به کلاینت دانلود نیز همان mount مربوط به /srv/media:/data را بدهید تا هر دو کانتینر یک مسیر یکسان را ببینند. ابتدا تأیید کنید که سمت میزبان یک فایل‌سیستم واحد است: df -h /srv/media/downloads /srv/media/audiobooks باید برای هر دو، مقدار یکسانی را در ستون Filesystem چاپ کند. مقادیر متفاوت به معنای دیسک‌های متفاوت است و هیچ ساختار mountای نمی‌تواند بین آن‌ها hardlink ایجاد کند. تفاوت بین این روش و استفاده از named storage در bind mountها در مقابل named volumeها برای رسانه بررسی شده است.

دسترسی به رابط کاربری وب بدون در معرض قرار دادن آن

خط پورت به دلیلی روی 127.0.0.1 منتشر می‌شود. ufw deny 8789 از پورت منتشرشدهٔ Docker محافظت نمی‌کند، زیرا Docker قوانین NAT (ترجمه آدرس شبکه) خود را در زنجیره‌ای می‌نویسد که هسته پیش از ufw به آن می‌رسد، بنابراین ترافیک پیش از آنکه قانون شما بررسی شود، هدایت (forward) می‌شود. این رفتار همواره کاربران را غافلگیر می‌کند و در دلیل نادیده گرفته شدن قوانین ufw توسط پورت منتشرشده Docker توضیح داده شده است. اتصال به loopback این مشکل را به‌طور کامل دور می‌زند.

از طریق یک تونل SSH از دستگاه خود به رابط کاربری دسترسی پیدا کنید:

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

آن را در حال اجرا بگذارید و http://127.0.0.1:8789 را در مرورگر خود باز کنید. در اولین اجرا، احراز هویت را تنظیم کنید. تنها پس از آن است که باید به فکر استفاده از یک reverse proxy با TLS (امنیت لایه انتقال) در مقابل آن باشید. هنگامی که با استفاده از تونل به سه یا چهار مورد از این ابزارها با رمز عبور جداگانه برای هر کدام متصل شدید، راهکار تمیزتر این است که پروکسی را پشت یک سرور ورود یکپارچه (SSO) خودمیزبان مانند Authentik قرار دهید تا یک ورود، تمام برنامه‌ها را پوشش دهد و یک ابطال دسترسی، همه آن‌ها را ببندد.

اتصال ایندکسرها و کلاینت دانلود

نرم‌افزار Chaptarr از پروتکل‌های استاندارد ایندکسر و کلاینت دانلود در مجموعه arr پشتیبانی می‌کند؛ بنابراین Prowlarr ایندکسرها را همان‌طور که برای Sonarr ارسال می‌کند، به Chaptarr نیز می‌فرستد و کلاینت‌های معمول torrent و usenet بدون نیاز به تنظیمات خاصی به آن متصل می‌شوند.

یک تنظیم وجود دارد که تقریباً همه را دچار مشکل می‌کند. هنگامی که Chaptarr آدرس میزبان (host) کلاینت دانلود را می‌پرسد، localhost یا 127.0.0.1 را وارد نکنید. در داخل یک کانتینر، این آدرس به خودِ کانتینر اشاره دارد؛ بنابراین Chaptarr سعی می‌کند با پورت 8080 خودش ارتباط برقرار کند و گزارش می‌دهد که قادر به اتصال نیست. از نام کانتینر، یعنی qbittorrent، به همراه پورت 8080 استفاده کنید. با دستور docker network inspect arr که نام تمام کانتینرهای متصل را فهرست می‌کند، تأیید کنید که هر دو کانتینر در یک شبکه قرار دارند.

اگر کلاینت دانلود شما از طریق یک کانتینر VPN با network_mode: "service:gluetun" اجرا می‌شود، به دلیل اشتراک فضای نام شبکه (network namespace) با Gluetun، نام مستقلی در شبکه ندارد. در این حالت، از آدرس gluetun روی پورتی که Gluetun در معرض دید قرار داده است، استفاده کنید. این پیکربندی و مسیریابی‌های مربوط به آن، در مسیریابی کلاینت دانلود از طریق Gluetun توضیح داده شده است.

گسست Readarr: هزینه واقعی مهاجرت

نرم‌افزار Chaptarr با منابع متادیتای Readarr سازگار نیست. این برنامه عناوین، نویسندگان و نسخه‌ها را از طریق خط لوله اختصاصی خود و در میان چندین ارائه‌دهنده مختلف شناسایی می‌کند، بنابراین شناسه‌هایی که Readarr ذخیره کرده است در اینجا کاربردی ندارند. هیچ قابلیت وارد کردن دیتابیس (database import) یا مسیر ارتقای مستقیم (drop-in upgrade) وجود ندارد.

برای یک کتابخانه موجود، این بدان معناست که فایل‌ها ایمن هستند اما تنظیمات خیر. هیچ بخشی از این فرآیند، داده‌های موجود روی دیسک را تغییر نمی‌دهد. شما یک پوشه ریشه (root folder) اضافه می‌کنید، عملیات وارد کردن کتابخانه را اجرا می‌کنید و Chaptarr فایل‌های یافت‌شده را با متادیتای خود تطبیق می‌دهد. آنچه باید به‌صورت دستی بازسازی کنید عبارت است از: پروفایل‌های کیفیت، فرمت نام‌گذاری، تنظیمات ایندکسر و کلاینت، و هر تطبیقی که Chaptarr به‌اشتباه انجام داده است. یک کتابخانه بزرگ به یک دور اصلاحات دستی نیاز دارد، بنابراین به‌جای 10 دقیقه، یک عصر کامل را برای آن در نظر بگیرید.

این کار را به ترتیب زیر انجام دهید. کانتینر Readarr را متوقف کنید اما volume تنظیمات آن را نگه دارید تا بتوانید هنگام بازنویسی تنظیمات، همچنان به تنظیمات قدیمی خود دسترسی داشته باشید. ابتدا Chaptarr را به یک پوشه کوچک اشاره دهید و پیش از وارد کردن کل کتابخانه، تطبیق‌ها را بررسی کنید. تنها زمانی کانتینر قدیمی را حذف کنید که از نتیجه کار راضی باشید.

یک نکته حریم خصوصی که پیش از اسکن کل کتابخانه باید بدانید: جستجوهای متادیتا به api2.chaptarr.com ارسال می‌شوند. در فایل README ذکر شده است که این درخواست‌ها ممکن است شامل شناسه‌های ارائه‌دهنده، متن جستجو، نوع رسانه، برچسب‌ها و نام فایل‌ها باشند، و این درخواست‌ها مسیرهای کامل، هویت کاربر و اعتبارنامه‌ها را شامل نمی‌شوند. نام فایل‌ها از سرور شما خارج می‌شوند. این موضوع برای یک سرویس متادیتا عادی است، با این حال شما باید آگاهانه در مورد آن تصمیم بگیرید.

تحویل کتاب‌های صوتی به یک پخش‌کننده

برنامه Chaptarr فایل‌ها را سازماندهی می‌کند. پخش آن‌ها وظیفهٔ یک برنامه دیگر است و Audiobookshelf معمول‌ترین گزینه برای این کار است، زیرا موقعیت گوش دادن شما را در دستگاه‌های مختلف همگام‌سازی می‌کند و اپلیکیشن‌های موبایل نیز دارد. ایمیج رسمی آن ghcr.io/advplyr/audiobookshelf:latest است و نمونه فایل Compose مستندشدهٔ آن، پورت 13378 میزبان را به پورت 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

همان مسیر میزبانی که Chaptarr در آن می‌نویسد را mount کنید، سپس /audiobooks را به عنوان یک کتابخانه در رابط کاربری وب اضافه کنید. پس از اسکن بعدی، یک import جدید ظاهر می‌شود.

اگر در حال حاضر از Jellyfin استفاده می‌کنید، می‌توانید پوشه را به عنوان یک کتابخانه در آن اضافه کنید تا فایل‌ها پخش شوند. تنظیمات مربوط به آن در اجرای Jellyfin به عنوان مدیا سرور روی یک VPS پوشش داده شده است. برای بخش کتاب‌های الکترونیکی، /srv/media/ebooks را به یک برنامه کتاب‌خوان بسپارید؛ وظیفه Chaptarr پس از نام‌گذاری و دسته‌بندی فایل به پایان می‌رسد.

ریسک نگهداری: مجوز، محیط اجرا و تگ‌های با تغییرات سریع

نرم‌افزار Chaptarr تحت مجوز GPL-3.0 منتشر شده و حق نشر آن متعلق به مشارکت‌کنندگان Chaptarr است؛ بخش‌هایی از آن نیز از تیم Servarr گرفته شده است. بنابراین کد منبع باز باقی می‌ماند و اگر این نگهدارنده فعالیت خود را متوقف کند، هر کسی می‌تواند دوباره آن را فورک کند. این پروژه بر پایه .NET 10 ساخته شده که تا اوت 2026 نسخه پشتیبانی بلندمدت (LTS) محیط اجرا محسوب می‌شود؛ این یعنی پایه نرم‌افزار به جای ماه‌ها، برای سال‌ها پشتیبانی می‌شود. هر دو مورد برای قضاوت درباره اینکه آیا این پروژه سال آینده همچنان وجود خواهد داشت یا خیر، اهمیت دارند.

شماره نسخه‌ها به‌سرعت تغییر می‌کنند. نسخه 0.9.925 در 9 اوت 2026 منتشر شد و پنج نسخه دیگر در هفت هفته پس از آن عرضه شدند. تمام نسخه‌ها تا 0.9.958 به‌عنوان پیش‌انتشار (pre-release) منتشر شدند؛ نسخه 0.9.965 که در 27 سپتامبر 2026 عرضه شد، اولین نسخه‌ای است که به‌عنوان انتشار کامل (full release) علامت‌گذاری شده است. یک تگ دقیق را ثابت (Pin) کنید. استفاده از latest به این معنی است که یک docker compose pull بدون نظارت می‌تواند شما را در یک هفته چندین نسخه جلو ببرد، و یک فورک به این جوانی ممکن است API خود را بین نسخه‌ها تغییر دهد که باعث خرابی هر اسکریپت یا داشبوردی می‌شود که برای آن نوشته‌اید. ثابت‌سازی (Pinning) عادتی است که ارزش دارد برای هر پروژه جوانی که خودتان میزبانی می‌کنید به کار ببرید؛ به همین دلیل است که راهنمای اجرای openGym به‌عنوان یک ردیاب تمرین ورزشی self-hosted به همان دلیل از یک تگ git ثابت برای استقرار استفاده می‌کند.

پیش از هر ارتقا، نسخه پشتیبان تهیه کنید و سپس ارتقا را به‌صورت آگاهانه انجام دهید.

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

این پروژه در طول حدود شش ماه و با بیش از یازده هزار کاربر، هیچ رویداد از دست رفتن داده‌ای گزارش نکرده است، با این حال همچنان توصیه می‌کند که پشتیبان‌گیری را حفظ کنید و آن را به کتابخانه‌ای که تحمل از دست دادنش را ندارید، متصل نکنید. هر دو بخش این توصیه را جدی بگیرید. آرشیو پیکربندی را از سرور کپی کنید، زیرا نسخه‌ پشتیبانی که روی همان دیسکِ داده‌های اصلی قرار دارد، پشتیبان محسوب نمی‌شود. آن فایل tarball واحد، وضعیت محلی برنامه را پوشش می‌دهد زیرا شامل پایگاه‌داده‌های SQLite و پیکربندی‌های موجود در /config است؛ هر چیزی که روی یک سرور پایگاه‌داده مجزا قرار دارد، نیاز به dump گرفتن از پایگاه‌داده نیز دارد؛ این همان شکلی است که مرحله پشتیبان‌گیری هنگام میزبانی Chatwoot روی یک VPS به همراه داده‌های Postgres و فایل‌های آپلود شده به خود می‌گیرد.

حالت‌های شکست و پیام‌های مرتبط

کانتینر در یک حلقه (loop) مدام راه‌اندازی مجدد می‌شود. docker compose ps مقدار Restarting را نشان می‌دهد. ابتدا docker compose logs chaptarr را بخوانید. مالکیت root روی ./config به‌تنهایی علت حلقه نیست: entrypoint معمولاً پیش از اجرای برنامه، مالکیت را اصلاح می‌کند. اگر لاگ‌ها گزارش می‌دهند که دایرکتوری داده قابل‌نوشتن نیست، یک override در user:، یک mount با دسترسی فقط‌خواندنی (read-only) یا یک سیستم‌فایل که اجازه تغییر مالکیت نمی‌دهد را بررسی کنید. override را حذف کنید تا entrypoint بتواند تنظیمات خود را انجام دهد؛ برای مالکیت نادرست در یک دایرکتوری محلی قابل‌نوشتن، دستور sudo chown -R 1000:1000 ./config را اجرا کنید.

فرایند وارد کردن (import) هرگز کامل نمی‌شود و فایل‌ها در پوشه دانلود باقی می‌مانند. Chaptarr می‌تواند فایل دانلودشده را بخواند اما نمی‌تواند در کتابخانه بنویسد. ls -ln /srv/media/audiobooks را با PUID و PGID خود مقایسه کنید. دایرکتوری که مالک آن UID متفاوتی است، یا متعلق به گروه شماست اما دسترسی نوشتن گروهی ندارد، مانع از انتقال فایل می‌شود. UMASK=002 از بروز حالت دوم برای فایل‌های جدید جلوگیری می‌کند.

مصرف دیسک پس از هر بار وارد کردن دو برابر می‌شود. هیچ hardlink ایجاد نشده است، بنابراین فایل کپی شده است. تست ln را از بخش volumes اجرا کنید. خطایی که به Invalid cross-device link ختم می‌شود این موضوع را تأیید می‌کند و راه‌حل آن، استفاده از یک mount با والد واحد (single-parent) است.

کلاینت دانلود متصل نمی‌شود. شما localhost را به‌عنوان میزبان وارد کرده‌اید. در داخل کانتینر، این آدرس به خود Chaptarr اشاره دارد. از نام کانتینر استفاده کنید و بررسی کنید که docker network inspect arr هر دو کانتینر را لیست می‌کند.

Compose از شروع سرویس خودداری می‌کند. Bind for 127.0.0.1:8789 failed: port is already allocated به این معنی است که سرویس دیگری پورت را اشغال کرده است. آن را با sudo ss -lntp | grep 8789 پیدا کنید.

مرورگر هیچ چیزی نشان نمی‌دهد. با اتصال پورت به 127.0.0.1، هیچ مقصدی برای اتصال لپ‌تاپ شما از طریق اینترنت وجود ندارد. این رفتار مورد انتظار است. ابتدا SSH tunnel را باز کنید.

FAQ

آیا می‌توانم کتابخانه Readarr خود را به Chaptarr منتقل کنم؟

به‌عنوان یک import مستقیم، خیر. Chaptarr با منابع متادیتای Readarr سازگار نیست و از خط لوله (pipeline) تأمین‌کننده اختصاصی خود استفاده می‌کند؛ بنابراین شناسه‌های ذخیره‌شده در Readarr فاقد اعتبار هستند و هیچ ابزاری برای تبدیل دیتابیس وجود ندارد. فایل‌های شما روی دیسک دست‌نخورده باقی می‌مانند. شما باید همان مسیرها را به‌عنوان root folders اضافه کنید، یک library import انجام دهید و اجازه دهید Chaptarr خودش فایل‌ها را تطبیق دهد. پروفایل‌های کیفیت، فرمت نام‌گذاری، تنظیمات indexer و اصلاح تطبیق‌های اشتباه، همگی نیازمند کار دستی هستند؛ بنابراین پیش از وارد کردن کل کتابخانه، ابتدا با یک پوشه کوچک شروع کنید.

چرا Chaptarr نمی‌تواند در پوشه کتاب‌های صوتی من بنویسد؟

کاربر کانتینر دسترسی نوشتن (write permission) روی آن دایرکتوری ندارد؛ معمولاً به این دلیل که کانتینر با UID متفاوتی نسبت به مالک فایل‌ها اجرا می‌شود. اگر متغیرهای PUID=99 و PGID=100 تنظیم نشده باشند، Chaptarr به مقادیر پیش‌فرض برمی‌گردد که مربوط به unRAID هستند و در یک VPS معمولی با سیستم‌عامل Ubuntu اشتباه عمل می‌کنند. آن‌ها را روی id -u و id -g خود تنظیم کنید، از همین جفت در کلاینت دانلود استفاده کنید و UMASK=002 را مقداردهی کنید تا فایل‌های جدید برای گروه قابل‌نوشتن باقی بمانند. مالکیت دایرکتوری کتابخانه را با ls -ln بررسی کنید؛ چون این دستور اعداد را نمایش می‌دهد (نه نام‌ها)، می‌توانید مقایسه دقیقی انجام دهید.

چرا پس از import، فضای مصرفی دیسک من دو برابر شد؟

Chaptarr فایل را کپی کرده است چون امکان ایجاد hardlink وجود نداشته است. Mount کردن /downloads و /audiobooks به‌عنوان bindهای جداگانه باعث می‌شود آن‌ها در داخل کانتینر به نقاط mount مجزا تبدیل شوند و هسته سیستم‌عامل با خطای Invalid cross-device link از ایجاد hardlink بین نقاط mount مختلف خودداری می‌کند. یک دایرکتوری والد مانند /srv/media:/data را mount کنید و از /data/downloads و /data/audiobooks در داخل برنامه استفاده کنید. هر دو مسیر باید روی یک فایل‌سیستم میزبان قرار داشته باشند که با df -h قابل تأیید است.

آیا Chaptarr کتاب‌های صوتی من را پخش می‌کند؟

خیر. این برنامه وظیفه یافتن، دانلود، تغییر نام و سازماندهی فایل‌ها را بر عهده دارد و پخش فایل‌ها توسط برنامه دیگری انجام می‌شود. Audiobookshelf معمولاً در کنار آن استفاده می‌شود، زیرا موقعیت پخش شما را در دستگاه‌های مختلف ذخیره می‌کند؛ برای این کار از ایمیج رسمی ghcr.io/advplyr/audiobookshelf:latest با همان مسیر mount شده کتاب‌های صوتی استفاده کنید. اگر پوشه را به‌عنوان یک کتابخانه اضافه کنید، Jellyfin نیز فایل‌ها را پخش خواهد کرد.

آیا اجرای Chaptarr روی کتابخانه‌ای که برایم مهم است ایمن است؟

این نرم‌افزار در مرحله بتا و از یک fork نوپا است؛ خود پروژه نیز به این موضوع اذعان دارد، هرچند در حدود شش ماه گذشته و با بیش از یازده هزار کاربر، گزارشی از حذف داده‌ها ثبت نشده است. نکات اطمینان‌بخش شامل مجوز GPL-3.0 است که امکان fork کردن کد را فراهم می‌کند و همچنین پایه .NET 10 که از اوت 2026 یک runtime با پشتیبانی بلندمدت (LTS) محسوب می‌شود. از یک تگ ایمیج دقیق مانند 0.9.925 به‌جای latest استفاده کنید، پیش از هر ارتقا از /config نسخه پشتیبان تهیه کنید و آن آرشیو را خارج از سرور نگهداری کنید.