Bookshelf: o'z kitoblaringiz uchun o'rnatiladigan, bulutga tayyor kutubxona

Ko'plab odamlar yillar davomida yig'gan elektron kutubxonalar — Project Gutenberg dan ozod klassiklar, Humble Bundle to'plamlari, o'zbek tilidagi tarjimalar yoki o'zlari skanerlagan kitoblar — odatda diskda yoki bulut sinxronizatorlarida "arxiv" holatida yotib turadi. Ularni qulay o'qish, qidirish va qurilmalar o'rtasida sinxronlash alohida muammo. Bookshelf bu bo'shliqni to'ldirish uchun yaratilgan: bu sizga tegishli kitoblardan to'liq funktsiyali, brauzerda ishlaydigan kutubxona qurish imkonini beradi — hech qanday ro'yxatdan o'tish, obuna yoki tashqi xizmatga majburiy ulanish shart emas.

Nima uchun bu oddiy "fayl menejeri" emas?

Avval ko'rinishi oddiy: bitta sahifa, qidiruv maydoni, kitoblar ro'yxati. Lekin ichida ikki alohida o'qish vositasi yashirin — EPUB uchun glava-bo'lim navigatsiyasi, shrift sozlamalari va quyidagi matnni o'zlashtiruvchi o'quvchi; PDF uchun sahifa-bosahifa ko'rinish, zoom va aylantirish. Ikkalasi ham serverdan HTML/JS sifatida yetib boradi, ma'nosi — mobil brauzer, planshet yoki e-ink qurilma (masalan, KOReader orqali) qo'shimcha ilovasiz o'qiya oladi. Yuklab olish tugmasi original faylni beradi, shuningda DRM-siz kitoblaringiz butunlay sizda qoladi.

Ikkita ish rejimi: bulut yoki server

Loyiha ikki storage provider (saqlash provayderi) bilan yetib boradi, ularning har biri o'z vazifasiga mos:

git clone https://github.com/murerkinn/bookshelf.git
cd bookshelf
npm install

• Cloudflare R2 — obyekt saqlash (S3-mos) ustida. wrangler orqali deploy qilinadi, npm run deploy bitta buyruq. Bu yerda server yo'q — Cloudflare Worker har bir so'rovni ushlab, R2 dan faylni streamilab beradi. Narxi: faqat R2 operatsiyalari (o'qish so'rovlari bepul, yozish — miqdoriy).
• Fayl tizimi (fs) — oddiy Node.js serveri. VPS, Raspberry Pi, NAS yoki lokal dasturiy ta'minot (Docker konteyner) sifatida ishga tushiriladi. Barcha ma'lumotlar bitta library nomli Docker volumeida — bu vafaqolikka yagona nusxa ko'chirish yetarli.

Arxitektura ports and adapters (portlar va adapterlar) prinsipi ustida qurilgan: yangi saqlash provayderi (masalan, Backblaze B2, MinIO, hatto IPFS) alohida npm paketi sifatida yozilib, bookshelf.config.json da ko'rsatilishi kifoya.

mkdir books && cp ~/Downloads/*.epub books/
docker compose run --rm sync --create
docker compose up -d

Kutubxona qanday shakllanadi: sync vositasi

Kitoblar books/ papkasiga qo'yiladi (EPUB yoki PDF). Keyin npm run sync -- --create ishga tushirilganda:

chown -R 1000:1000 /srv/bookshelf

• Har bir fayl tahlil qilinadi: metadata (muallif, sarlavha, ISBN, chop yili) ajratib olinadi.
• Muqova rasmlari yaratiladi — cwebp (WebP formatida siqilgan) va pdftoppm (PDF dan birinch sahifa) yordamida. Docker imagede ular tayyor o'rnatilgan keladi.
• Natija — library/ direktoriyasida tayyor statik "katalog" drevosini hosil qiladi: JSON indekslar, muqova fayllari, o'qish uchun bo'laklarga ajratilgan EPUB/PDF.
• Bu drevo tanlangan provayderga (R2 bucket yoki shelf-data/ papka) yuklanadi.

Muhim nuans: library/ — bu paydo bo'lishi mumkin bo'lgan (regenerable) artefakt. Asl manba — books/ papkasidagi original fayllar. Bu demak, agar provayder buzsa yoki o'chirilsa, sync ni qayta ishga tushirish kutubxonani to'liq tiklaydi.

// bookshelf.config.json
{ "storage": { "provider": "fs", "directory": "shelf-data" } }

Profillar: xavfsizlik emas, qulaylik

Bookshelfda autentifikatsiya yo'q. Har kim URL ga kirsa, barcha kitoblarni ko'ra oladi, yuklab oladi va har qanday profilni tanlashi mumkin. Profillar — bu "kim o'qiyapti" ni ajratish uchun: uyda uchta odam bo'lsa, har birining o'qish pozitsiyasi (glava, scroll, shrift o'lchami) alohida saqlanadi. Ma'lumotlar provayderda (R2 yoki disk) profil fayli sifatida yoziladi. Agar provayder yozish huquqini bermasa (masalan, BOOKSHELF_READ_ONLY=1 o'rnatilgan bo'lsa), profillar brauzer cookiesida yashirib qoladi — bu graceful degradation (muvofiq pasayish) misoli.

npm run sync -- --create   # builds library/, then publishes it to shelf-data/
npm run build
npm start -w @bookshelf/app

Eslatma: ikki qurilma bitta profil bilan bir vaqtda o'qisa, last-write-wins (oxirgi yozuv g'alaba qozonadi) prinsipi ishlaydi — bu oddiy, lekin sinxronlash talab qilinadigan holat uchun cheklov.

npm run sync -- --create   # creates the bucket, then uploads to it
npm run deploy

O'rnatish: Docker eng qisqa yo'l

Windowsda to'g'ridan-to'g'ri Node 24 bilan ishlamasligi (UNIX vositalariga bog'liqlik) sababli, Docker — universal yechim. cwebp va pdftoppm imageda bor, shuningda muqovalar darhol to'g'ri chiqadi. Minimal buyruqlar ketma-ketligi:

npm run demo                 # writes them into books/

git clone https://github.com/murerkinn/bookshelf.git
cd bookshelf
mkdir books && cp ~/Downloads/*.epub books/
docker compose run --rm sync --create
docker compose up -d

Kutubxona http://localhost:3000 da. Agar host papkasini bind-mount qilmoqchi bo'lsangiz, chown -R 1000:1000 /srv/bookshelf ni unutmang — konteyner ichidagi foydalanuvchi UID 1000.

Cloudflare R2 marshruti: serverlarsiz kutubxona

Bu yo'l serverless faylashtirishni tanlovchilariga mo'ljallangan. Talablar: Cloudflare hisob, npx wrangler login, va loyihada tekshirilgan wrangler.jsonc va bookshelf.config.json — ular bir-biriga mos kelishi shart (bucket nomi va Worker nomi). npm run sync -- --create bucketni yaratadi va yuklaydi, npm run deploy Worker ni joylashtiradi. Natija — global CDN ustida, har qanday joydan tez ishlaydigan, doimiy server to'lovsiz kutubxona.

Cheklovlar va ochiq savollar

• Autentifikatsiya yo'qligi — bu xususiyat, emas kamchilik deb e'lon qilingan, lekin ommaviy IP manziliga qo'yilgan kutubxona hamma uchun ochiq bo'ladi. Tarmoq darajasida (VPN, Tailscale, Cloudflare Access, Basic Auth proxy) himoya kerak.
• Windows qo'llab-quvvatlanmaydi (Node 24 + UNIX vositalari). Docker — yechim, lekin Windowsda Docker Desktop resurs talab qiladi.
• O'qish pozitsiyalari sinxi — profillar provayderda saqlanadi, lekin real-time sinxronizatsiya yo'q. Ikki qurilma bir vaqtda o'qisa, birining pozitsiyasi yo'qoladi.
• DRM-li kitoblar — o'qilmaydi. Faqat DRM-siz EPUB/PDF.
• Mobil ilova yo'q — brauzer versiyasi responsive, lekin native ilova (iOS/Android) va OPDS qo'llab-quvvatlanishi yo'q (hali).

Kimga va nima uchun foydali?

Shaxsiy kutubxonachi uchun — Calibre + Calibre-Web yoki Kavita o'rniga yengil, konteynerga mos, bulutga tayyor alternatava. Dasturchi uchun — ochiq manbali, TypeScript, Turborepo, Worker/Fayl tizimi abstraktsiyasi misoli sifatida o'rganish manbai. Kichik jamoa/oila uchun — bitta VPS yoki R2 bucket ustida alohida profillar bilan umumiy kutubxona.

Loyiha MIT litsenziyasi ostida, extension point (kengaytirish nuqtasi) sifatida saqlash provayderlari tashqi paketlar sifatida yozilishi mumkin. Bu demak, ekotizim o'sishi kutilmoqda — masalan, immutable saqlash (Arweave, Filecoin) yoki shifrlangan konteynerlar uchun adapterlar paydo bo'lishi mumkin.

Xulosa: o'z kitoblaringiz, o'z qoidalariz

Bookshelf hech nima yashirmaydi: bu sizning fayllaringiz, sizning serveringiz (yoki siz tanlagan R2 bucket), sizning brauzeringiz. Hech qanday hisob, obuna, telemetriya yoki majburiy yangilanish. Bu — local-first (avval mahalliy) falsafasining to'g'ri amaliyoti: texnologiya xizmatchi bo'lib, egasi emas. Agar sizda yig'ilgan EPUB/PDF to'plami bor va ularni har qayerdan, har qanday qurilmadan, o'z nazariyagingizda o'qimoqchi bo'lsangiz — Bookshelf bugungi kunda eng toza va eng kam talab qiluvchi yechimlardan biri.

Asl manba: github.com