Jinsi ya Kuendesha Paperless-ngx kwenye VPS

Unachojenga

Paperless-ngx kwenye VPS hubadilisha folda yenye karatasi zilizochanganuliwa kuwa hifadhi inayoweza kutafutwa. Unaweka PDF kwenye saraka inayofuatiliwa. Seva huendesha OCR (utambuzi wa herufi kwa macho), hutoa maandishi, hukisia tarehe na mwandishi, kisha huihifadhi. Usakinishaji unatumia faili moja ya Docker Compose yenye huduma nne. Kila kitu baada ya hapo ni usanidi. Mwongozo huu umetumia sehemu kubwa kueleza usanidi huo, kwa sababu ndipo usakinishaji unaposhindwa mara nyingi.

Paperless-ngx ni fork ya jamii inayodumishwa ya mradi wa awali wa Paperless. Ni programu isiyolipishwa na inayojihifadhiwa mwenyewe. Huhifadhi hati zako kama faili za kawaida kwenye diski, kwa hiyo huwezi kuzuiwa kufikia hifadhi yako mwenyewe. Kuiendesha kwenye VPS badala ya kompyuta ya nyumbani kunamaanisha kuwa unaweza kufikia michanganuo yako kutoka mahali popote bila kufungua port kwenye router ya nyumbani. Pia inafanya kazi vizuri pamoja na instance ya kibinafsi ya Nextcloud kwa faili zisizo za karatasi.

Kile ambacho stack huendesha hasa

Faili rasmi ya compose huanzisha kontena nne. Kujua kazi ya kila kontena hurahisisha kusoma kumbukumbu.

• webserver: image yenyewe ya paperless-ngx. Huendesha kiolesura cha wavuti, API, consumer inayofuatilia folda yako ya kuingiza, na wafanyakazi wa kazi wa Celery wanaofanya OCR.
• db: PostgreSQL. Huhifadhi metadata, lebo, waandishi, na majedwali ya faharasa ya utafutaji wa maandishi kamili. Haihifadhi PDF zako.
• broker: Valkey, hifadhi ya jozi za funguo na thamani inayooana na Redis. Ni foleni ya kazi kati ya mchakato wa wavuti na wafanyakazi.
• gotenberg na tika: za hiari, zinapatikana tu katika lahaja za compose za -tika. Hubadilisha hati za Office (.docx, .xlsx, .odt) kuwa PDF ili paperless iweze kuzifanyia faharasa.

Kufikia Julai 2026, faili ya compose ya postgres inaweka matoleo docker.io/library/postgres:18 na docker.io/valkey/valkey:9-alpine, na hupakua programu kutoka ghcr.io/paperless-ngx/paperless-ngx:latest.

Masharti ya awali

• VPS ya Ubuntu 24.04 KVM yenye ufikiaji wa sudo, pamoja na Docker iliyo na programu-jalizi ya Compose iliyosakinishwa tayari. Ikiwa sehemu hii ni mpya kwako, anza na misingi ya Docker Compose kwa VPS kisha urudi.
• Jina la kikoa lenye rekodi ya A inayoelekeza kwenye VPS. Paperless hukataa kutoa huduma kwenye hostname ambayo haijaelekezwa kuitumia, kwa hiyo jambo hili ni muhimu mapema kuliko unavyotarajia.
• Kumbukumbu ndiyo kizuizi halisi. PostgreSQL, Valkey, gunicorn na worker mmoja wa Tesseract OCR wanaweza kukaa kwa wakati mmoja ndani ya 2 GB kwa matumizi mepesi. Tumia 4 GB ikiwa unapanga kuingiza mkusanyiko wa mamia ya scan, kwa sababu OCR ya PDF kubwa yenye kurasa nyingi ndiyo inayoongeza matumizi ya kumbukumbu na kusababisha kernel kumuua worker kupitia out-of-memory killer.
• Diski: kumbukumbu yako huhifadhiwa mara mbili, yaani faili asili na PDF ya kumbukumbu iliyofanyiwa OCR, kwa hiyo tenga takribani mara mbili ya ukubwa wa scan zako.

Pata faili rasmi za compose

Kuna kisakinishi shirikishi:

bash -c "$(curl --location --silent --show-error https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/install-paperless-ngx.sh)"

Huuliza maswali na kukuandalia faili. Kuzifanya mwenyewe kunahitaji amri nne, na hukuwezesha kujua kila kitu kilipo. Hilo ndilo unalohitaji kwenye seva utakayoisimamia.

mkdir -p ~/paperless && cd ~/paperless
curl -fsSL -o docker-compose.yml https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/docker-compose.postgres.yml
curl -fsSL -o docker-compose.env https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/docker-compose.env
curl -fsSL -o .env https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/.env

Aina mbalimbali ziko katika saraka hiyo hiyo: docker-compose.sqlite.yml, docker-compose.mariadb.yml, na toleo la -tika la kila aina. Chagua postgres kwa usakinishaji mpya. SQLite inafaa kwa hati mia kadhaa, lakini faharasa ya utafutaji wa maandishi kamili huwa polepole kabla PostgreSQL haijawa hivyo.

Faili ya .env ina mstari mmoja, COMPOSE_PROJECT_NAME=paperless. Jina hilo huwa kiambishi awali cha kila container na volume. Kwa hiyo usilifute kisha ushangae kwa nini docker compose down -v haiwezi kupata data yako.

Sanidi docker-compose.env kabla ya kuanzisha mara ya kwanza

Mipangilio miwili si ya hiari. Tengeneza ufunguo wa siri kwa amri iliyoandikwa kwenye nyaraka za mradi:

python3 -c "import secrets; print(secrets.token_urlsafe(64))"

Kisha hariri docker-compose.env:

PAPERLESS_SECRET_KEY=<the long string you just generated>
PAPERLESS_URL=https://paperless.example.com
PAPERLESS_TIME_ZONE=Europe/Berlin
PAPERLESS_OCR_LANGUAGE=deu+eng
USERMAP_UID=1000
USERMAP_GID=1000

PAPERLESS_SECRET_KEY hutolewa ikiwa na thamani halisi change-me. Hutia sahihi vidakuzi vya kipindi, kwa hiyo kuiacha hivyo kunamaanisha mtu yeyote anayejua thamani chaguo-msingi anaweza kutengeneza kipindi bandia. Iweke kabla ya kuanzisha mara ya kwanza, kwa sababu kuibadilisha baadaye huwaondoa watumiaji wote kwenye akaunti zao.

PAPERLESS_URL ndiyo inayokuokoa saa moja ya kazi. Paperless ni programu ya Django, na Django huthibitisha kichwa cha Host cha kila ombi. Weka PAPERLESS_URL, nayo itajaza ALLOWED_HOSTS, CORS_ALLOWED_HOSTS na CSRF_TRUSTED_ORIGINS kwa ajili yako. Ukiiacha tupu na kuelekeza domain kwenye seva, kila ukurasa hurudisha Bad Request (400), huku DisallowedHost ikionekana kwenye logi ya container. Iandike bila alama ya slash mwishoni na bila path.

USERMAP_UID na USERMAP_GID huweka mtumiaji ambaye container huendesha kama. Zilinganishe na akaunti yako mwenyewe, iliyoangaliwa kwa id -u na id -g. Zisipolingana, faili unazonakili kwenye folda ya consume hazitasomeka na consumer, na logi itaonyesha hitilafu ya ruhusa badala ya kuonyesha uagizaji.

Anzisha stack na uunde mtumiaji wa kwanza

docker compose pull
docker compose up -d
docker compose run --rm webserver createsuperuser
docker compose logs -f webserver

createsuperuser huomba jina la mtumiaji, barua pepe na nenosiri. Hakuna kuingia kwa chaguo-msingi, kwa hiyo kuruka hatua hii kutakuacha kwenye ukurasa wa kuingia ambao hautakubali taarifa yoyote. Subiri mstari wa logi unaoripoti kuwa seva inasikiliza kwenye port 8000 kabla ya kujaribu kivinjari. Mwanzo wa kwanza pia huendesha uhamishaji wa hifadhidata, unaochukua dakika moja au mbili.

Ihakikishe kwenye mfumo wa ndani kabla ya kutumia domain:

curl -I http://127.0.0.1:8000

302 redirect kwenda /accounts/login/ inamaanisha kuwa stack iko katika hali nzuri.

Weka HTTPS mbele yake

Faili ya kawaida ya compose huchapisha 8000:8000, ambayo hufungamana na kila kiolesura. Kwenye VPS ya umma, hii huweka kumbukumbu yako yote ya hati wazi kupitia HTTP isiyo na usimbaji kwa mtu yeyote anayepata anwani hiyo. Badilisha mstari wa port ili ufungamane na loopback pekee:

    ports:
      - "127.0.0.1:8000:8000"

Kisha tekeleza TLS (usalama wa safu ya usafirishaji) katika reverse proxy na usambaze maombi kwa 127.0.0.1:8000. Ikiwa hii ndiyo programu pekee kwenye seva, proxy yoyote yenye mteja wa ACME (mazingira ya usimamizi wa vyeti otomatiki) itatosha. Ikiwa unaendesha kontena kadhaa nyuma ya usanidi mmoja wa cheti, fuata muundo wa Traefik reverse proxy kwa programu nyingi za Docker Compose na uunganishe huduma ya webserver kwenye mtandao wa proxy bila port iliyochapishwa kabisa.

Bila kujali proxy unayotumia, lazima itume X-Forwarded-Proto: https. Bila kichwa hiki, Django huamini kuwa ombi lilifika kupitia HTTP, ukaguzi wa asili kwenye fomu ya kuingia hushindwa, na unapata CSRF verification failed. Request aborted. kwenye ukurasa unaoonekana kuwa sahihi. Nusu nyingine ya marekebisho hayo ni kuweka PAPERLESS_URL kuwa anwani halisi ya https:// unayoandika kwenye kivinjari.

Pia ongeza kikomo cha ukubwa wa upakiaji cha proxy. Skani ya 40 MB inayopitia proxy inayoweka kikomo cha miili ya maombi kuwa 1 MB hukataliwa kabla paperless haijaiona, na kivinjari huripoti hitilafu ya jumla ya upakiaji.

Jinsi saraka ya consume inavyofanya kazi

Faili ya compose huweka ./consume kama bind mount kutoka saraka ya compose kwenda kwenye container. Kitu chochote unachoweka hapo huingizwa kisha kufutwa kutoka kwenye saraka hiyo, kwa sababu faili hiyo sasa huhifadhiwa kwenye media volume inayosimamiwa na paperless.

cp ~/scan-2026-07-14.pdf ~/paperless/consume/
docker compose logs -f webserver

Unapaswa kuona consumer ikichukua jina la faili, ikiendesha OCR, na kumaliza kwa mstari unaoripoti kuwa hati imeongezwa. Mzunguko wote huchukua sekunde chache kwa skani ya ukurasa mmoja, na unaweza kuchukua dakika moja au zaidi kwa hati ndefu.

Mipangilio miwili hubadilisha jinsi faili zinavyopatikana. PAPERLESS_CONSUMER_RECURSIVE=true huifanya paperless kutafuta kwenye saraka ndogo, na PAPERLESS_CONSUMER_SUBDIRS_AS_TAGS=true hugeuza jina la kila saraka ndogo kuwa tag, kwa hiyo kuweka faili kwenye consume/invoices/2026/ huipa tag invoices na 2026. Huu ndio mfumo rahisi zaidi wa kupanga faili utakaowahi kuunda.

Utambuzi wa faili ni sehemu nyingine muhimu. Kwa chaguo-msingi, PAPERLESS_CONSUMER_POLLING_INTERVAL ni 0, kumaanisha kuwa paperless hutumia arifa za mfumo wa faili za kernel, ambazo hutokea mara moja. Arifa hizo hazipitishwi kupitia mfumo wa faili wa mtandao. Ikiwa saraka yako ya consume ni share ya NFS au SMB ili scanner ya mtandao iweze kuandikia, hakuna faili itakayotambuliwa. Suluhisho ni kuweka interval kuwa idadi chanya ya sekunde ili paperless ichanganue saraka hiyo badala yake.

Lugha za OCR, na gharama zake

PAPERLESS_OCR_LANGUAGE inahitaji msimbo wa Tesseract wenye herufi tatu, eng kwa chaguo-msingi. Unganisha lugha kwa kutumia alama ya jumlisha, kama ilivyo kwenye deu+eng. Tesseract hujaribu kila lugha kisha huhifadhi matokeo bora zaidi. Kwa hiyo, kila lugha ya ziada huongeza mara nyingi muda wa CPU unaotumika kwenye kila ukurasa. Kwenye VPS yenye vCPU inayoshirikiwa, hiyo inaweza kufanya uchanganuzi ukamilike baada ya sekunde kumi badala ya dakika moja. Orodhesha tu lugha ambazo hati zako zimeandikwa nazo.

Picha hii inajumuisha Kiingereza, Kijerumani, Kiitalia, Kihispania na Kifaransa. Kwa lugha nyingine yoyote, ongeza lugha hiyo kwenye PAPERLESS_OCR_LANGUAGES kama orodha iliyotenganishwa kwa nafasi, kwa mfano PAPERLESS_OCR_LANGUAGES=tur ces, kisha uanze upya. Kontena hupakua vifurushi vya data vya Tesseract wakati wa kuanza. Kwa hiyo, uanzishaji wa kwanza baada ya mabadiliko hayo utachukua muda zaidi.

Hifadhi nakala ya hifadhidata na midia

Kunakili volumes za Docker wakati PostgreSQL inaendelea kutoa nakala ambayo huenda isirejeshwe. Paperless ina exporter yake, ambayo huandika hati pamoja na manifest ya JSON ya metadata yote kwenye bind mount ya ./export:

docker compose exec webserver document_exporter ../export --delete --no-progress-bar

--delete huondoa faili zilizohamishwa ambazo hazilingani tena na hati ya sasa, hivyo folda inabaki kuwa kioo badala ya kuendelea kukua bila mwisho. --no-progress-bar huweka matokeo katika hali safi wakati mchakato huu unaendeshwa na cron.

Kurejesha ni document_importer dhidi ya folda hiyo hiyo kwenye stack mpya, hivyo saraka ya export ndiyo kitu pekee unachopaswa kulinda. Itume nje ya eneo kwa ratiba ukitumia restic backups zilizofichwa na kupunguzwa marudio kutoka kwenye VPS, na endesha export kwanza ili restic isiwahi kunasa archive iliyoandikwa kwa nusu.

Thibitisha nakala kwa kuangalia kuwa export/manifest.json ipo na kwamba idadi ya faili inalingana na idadi ya hati katika kiolesura. Nakala ambayo hujawahi kuorodhesha si nakala.

FAQ

Kwa nini kila ukurasa unarudisha "Bad Request (400)" baada ya kuelekeza domain yangu hapo?

Django ilikataa kichwa cha Host kwa sababu domain yako haipo katika ALLOWED_HOSTS. Weka PAPERLESS_URL=https://paperless.example.com katika docker-compose.env bila slash ya mwisho, kisha endesha docker compose up -d ili kuunda upya container. Kuhariri faili ya env pekee hakutoshi, kwa sababu container inayoendesha inaendelea kutumia mazingira iliyotumia wakati ilipoanzishwa.

Niliweka PDF katika folda ya consume lakini hakuna kilichotokea. Tatizo ni nini?

Kwanza, angalia docker compose logs webserver. Kosa la ruhusa linamaanisha kuwa USERMAP_UID na USERMAP_GID havilingani na akaunti inayomiliki faili hiyo. Rekebisha thamani hizo, kisha uunde upya container. Kutokuwepo kabisa kwa mstari wa logi kunamaanisha kuwa tukio la faili halikufika. Hili hutokea kwenye network shares kwa sababu arifa za kernel hazivuki humo. Weka PAPERLESS_CONSUMER_POLLING_INTERVAL kuwa kitu kama 30, na paperless itachanganua folda kila baada ya sekunde 30 badala yake.

Je, ninaweza kuendesha paperless-ngx kwa SQLite badala ya PostgreSQL?

Ndiyo, docker-compose.sqlite.yml inatumika na hutumia kumbukumbu kidogo, hivyo inafaa kwa VPS ndogo. Hasara huonekana archive yako inapokua: utafutaji wa maandishi kamili na uhariri wa tag kwa mafungu hupungua kasi kwa kiasi kinachoonekana unapokuwa na maelfu ya hati. Kuhama baadaye kunahitaji export na import, kwa hiyo chagua PostgreSQL sasa ikiwa unatarajia archive itaendelea kukua.

Archive ya scan inahitaji nafasi kiasi gani ya diski?

Kwa kawaida, takribani mara mbili ya ukubwa wa faili zako chanzo. Paperless huhifadhi ya awali bila kuibadilisha na huhifadhi PDF ya pili iliyofanyiwa OCR yenye tabaka la maandishi linaloweza kutafutwa, pamoja na thumbnails ndogo. Scan ya maandishi pekee yenye ukubwa wa 200 KB hubaki ndogo. Scan ya rangi yenye ukubwa wa 30 MB ya mkataba mrefu huhifadhi takribani 60 MB. Ongeza folda ya export ikiwa unaendelea kuihifadhi kwenye diski hiyo hiyo, na archive hiyo hiyo itatumia nafasi mara tatu kwenye diski.

Je, ninahitaji containers za Tika na Gotenberg?

Ni lazima tu ikiwa unataka faili za Word, Excel au OpenDocument ziwekwe kwenye faharasa pamoja na PDF zako. Hubadilisha miundo hiyo kuwa PDF ili paperless iweze kufanya OCR na kuzitafuta. Pia huongeza containers nyingine mbili zinazoendesha na megabaiti mia kadhaa za kumbukumbu. Kwa hiyo, ziruke kwenye mashine ndogo ikiwa kila kitu unachohifadhi tayari ni PDF au picha.