Коригиране на грешката „CSRF проверка неуспешна“ в Paperless-ngx

Ако се показва Paperless-ngx 403 Забранено: CSRF проверката е неуспешна al iniciar sesión, la aplicación ha rechazado una comprobación de seguridad de la petición. Es habitual encontrarlo después de cambiar el dominio, activar HTTPS o configurar un proxy inverso, pero también puede estar relacionado con las cookies o con un formulario antiguo.

La solución consiste en identificar el motivo concreto, comprobar la URL pública y asegurarse de que la configuración llega realmente a Paperless. No necesitas desactivar la protección CSRF ni modificar los permisos de los documentos.

Идентифицирайте какво причинява CSRF грешката в Paperless-ngx

Django utiliza cookies y tokens, además de comprobaciones del origen de la petición, para dificultar que otra web envíe acciones aprovechando la sesión del usuario.

Comprueba que el aviso menciona expresamente CSRF проверката не беше успешна. Un 403 generado por Cloudflare, una regla del proxy o un sistema de acceso externo puede tener otra causa.

Si utilizas Docker Compose, reproduce el fallo y consulta los registros:

docker compose logs --tail=100 webserver

В примерите, които използвахме webserver като име на услугата. Заменете го с името на вашето внедряване. Потърсете препратки към django.security.csrf и причината за отказа.

• Проверката на произхода не бе успешна: Проверете източника, който се показва в известието, и публичните настройки.
• CSRF бисквитката не е зададена: проверете дали браузърът получава и запазва „бисквитката“.
• Липсващ или неправилен токен: Презаредете формуляра, преди да го изпратите.
• Проверката на референта не бе успешна: Проверете заглавките и достъпете чрез HTTPS.

Конфигурирайте PAPERLESS_URL с правилния публичен адрес

За уникален публичен адрес, конфигурирайте БЕЗХАРТИЕН_URLВключете протокола и порта, ако не е по подразбиране, но не добавяйте наклонена черта или пътища като /accounts/login/.

Например:

PAPERLESS_URL=https://documentos.example.com

Тази променлива съвместно конфигурира настройките за разрешени хостове, CORS и надеждни CSRF източници. Не преобразува автоматично всички адреси в еквиваленти desde las que puedas abrir la instancia.

Si publicas Paperless bajo una subruta, como https://example.com/paperlessНе въвеждайте този път в PAPERLESS_URL. Това внедряване изисква конфигуриране на префикса и проксито поотделно.

Уверете се, че Docker получава променливата

Файл .env puede servir para sustituir valores en Compose, pero sus variables no se incorporan automáticamente al entorno de todos los servicios.

Puedes añadir este fragmento al servicio existente de Paperless:

services:
  webserver:
    environment:
      PAPERLESS_URL: "https://documentos.example.com"

Интегрирайте корекцията, без да замествате останалата част от вашия Compose. Conserva la imagen, los volúmenes, las dependencias y las demás variables que ya utilizabas.

Si prefieres guardar la configuración en un archivo, decláralo expresamente:

services:
  webserver:
    env_file:
      - paperless.env

И вътре paperless.env:

PAPERLESS_URL=https://documentos.example.com

Проверете за евентуални дубликати: ако дадена променлива се появява и в environment, тази стойност има предимство пред тази, дефинирана в env_file.

Приложете промените, като пресъздадете услугата.

След като промените променливите, изпълнете командата от съответния проект Compose:

docker compose up -d --no-deps --force-recreate webserver

Този пример предполага, че зависимите услуги вече работят. Той пресъздава Paperless без умишлено спиране на базата данни и останалата част от стека.

Едно просто рестартиране на Docker Compose не актуализира средата на контейнера. Tampoco necesitas eliminar volúmenes para aplicar estos ajustes.

Comprueba el valor recibido:

docker compose exec webserver printenv PAPERLESS_URL

Ако очакваният адрес не се появи, проверете редактирания файл, услугата и всички дублиращи се променливи. Ако използвате опции като -f или конкретно име на проект, той запазва същите опции в командите.

Кога да използвате PAPERLESS_CSRF_TRUSTED_ORIGINS

PAPERLESS_CSRF_TRUSTED_ORIGINS не е остаряла променлива. Permite declarar orígenes adicionales para peticiones protegidas por CSRF.

Por ejemplo, para dos direcciones de confianza:

PAPERLESS_CSRF_TRUSTED_ORIGINS=https://documentos.example.com,https://archivo.example.com

Използвайте конкретни източници, с протокол и порт, където е приложимо. Не бъркайте този списък с PAPERLESS_ALLOWED_HOSTS, donde se configuran nombres de host sin protocolo.

Autorizar un origen no sustituye la configuración del dominio, del certificado o del proxy. Añade únicamente las direcciones que realmente utilizas y controlas.

Проверете HTTPS и обратните прокси заглавки

El proxy debe transmitir correctamente el host y el esquema externo. No es obligatorio que cambie el host por utilizar Nginx Proxy Manager, Traefik o Cloudflare Tunnel: depende de cómo estén configurados.

Si el navegador usa HTTPS y el proxy se comunica por HTTP con Paperless, puede ser necesario indicar cómo reconocer la conexión externa segura:

PAPERLESS_PROXY_SSL_HEADER='["HTTP_X_FORWARDED_PROTO", "https"]'

Този формат съответства на променлив файл. Не го активирайте без да проверите проксито: debe establecer o sobrescribir esa cabecera de manera fiable, evitando aceptar valores arbitrarios enviados por clientes externos.

En cadenas con varios proxies, comprueba el esquema que llega al último salto. Las opciones de confianza en cabeceras reenviadas no deben habilitarse todas como receta universal.

Si el registro muestra un origen null или проблем с препращащия; прегледайте също така политиката за препращане, приложена към формуляра. Уикито на проекта документира проблеми с достъпа, свързани с Referrer-Policy: no-referrerКоригирането на разрешените URL адреси може да не е достатъчно в този случай.

Изхвърлете стари бисквитки и остарели формуляри

Una vez corregida la configuración del servidor, abre de nuevo la dirección definitiva y vuelve a cargar el formulario de acceso. Evita enviarlo desde una pestaña antigua o alternar entre HTTP, HTTPS, IP y dominio durante la prueba.

Si el motivo apunta a cookies o tokens, prueba con una ventana privada o elimina únicamente los datos del sitio de Paperless. Comprueba también si alguna extensión está bloqueando cookies o modificando las peticiones.

El objetivo es que navegador, proxy y aplicación coincidan en la dirección y el contexto de acceso. Деактивирането на CSRF, безразборното разширяване на източниците или изтриването на данни за внедряване не отстранява причината..