ackify-ce/docs/fr/features/storage.md

Stockage de Documents

Uploadez et stockez des documents directement dans Ackify.

Vue d'Ensemble

Ackify supporte optionnellement le stockage de documents, permettant aux utilisateurs d'uploader des fichiers directement au lieu de fournir des URLs externes. Les documents sont stockés de manière sécurisée et servis via des endpoints API authentifiés.

Options de stockage :

• Désactivé (par défaut) - Les utilisateurs fournissent des URLs de documents
• Système de fichiers local - Documents stockés sur le serveur
• Compatible S3 - AWS S3, MinIO, Wasabi, DigitalOcean Spaces, etc.

Types de Fichiers Supportés

Type	Extensions	Types MIME
PDF	.pdf	application/pdf
Images	.png, .jpg, .jpeg, .gif, .webp	image/*
Office	.doc, .docx	application/msword, application/vnd.openxmlformats-*
Texte	.txt	text/plain
HTML	.html, .htm	text/html

Configuration

Stockage Local

Stockez les documents sur le système de fichiers du serveur via un volume Docker.

ACKIFY_STORAGE_TYPE=local
ACKIFY_STORAGE_LOCAL_PATH=/data/documents
ACKIFY_STORAGE_MAX_SIZE_MB=50

Volume Docker Compose :

services:
  ackify-ce:
    volumes:
      - ackify_storage:/data/documents

volumes:
  ackify_storage:

Stockage Compatible S3

Fonctionne avec tout fournisseur de stockage compatible S3.

ACKIFY_STORAGE_TYPE=s3
ACKIFY_STORAGE_MAX_SIZE_MB=50
ACKIFY_STORAGE_S3_ENDPOINT=https://s3.amazonaws.com
ACKIFY_STORAGE_S3_BUCKET=ackify-documents
ACKIFY_STORAGE_S3_ACCESS_KEY=votre_access_key
ACKIFY_STORAGE_S3_SECRET_KEY=votre_secret_key
ACKIFY_STORAGE_S3_REGION=us-east-1
ACKIFY_STORAGE_S3_USE_SSL=true

MinIO (S3 Auto-hébergé)

MinIO est une solution de stockage compatible S3 open-source populaire.

ACKIFY_STORAGE_TYPE=s3
ACKIFY_STORAGE_S3_ENDPOINT=http://minio:9000
ACKIFY_STORAGE_S3_BUCKET=ackify-documents
ACKIFY_STORAGE_S3_ACCESS_KEY=minioadmin
ACKIFY_STORAGE_S3_SECRET_KEY=minioadmin
ACKIFY_STORAGE_S3_REGION=us-east-1
ACKIFY_STORAGE_S3_USE_SSL=false

Docker Compose avec MinIO :

services:
  minio:
    image: minio/minio:latest
    environment:
      MINIO_ROOT_USER: minioadmin
      MINIO_ROOT_PASSWORD: minioadmin
    volumes:
      - minio_data:/data
    ports:
      - "9000:9000"
      - "9001:9001"
    command: server /data --console-address ":9001"
    healthcheck:
      test: ["CMD", "mc", "ready", "local"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  minio_data:

Utilisation

Interface Utilisateur

Quand le stockage est activé, un bouton d'upload apparaît à côté du champ URL :

1. Cliquez sur le bouton upload (ou glissez-déposez)
2. Sélectionnez un fichier depuis votre ordinateur
3. Le nom et la taille du fichier sont affichés
4. Cliquez sur "Upload" pour soumettre

Fonctionnalités :

• Barre de progression pendant l'upload
• Titre automatique depuis le nom de fichier
• Validation du type de fichier
• Respect de la limite de taille

Endpoints API

Upload de Document

POST /api/v1/documents/upload
Content-Type: multipart/form-data
X-CSRF-Token: abc123

file: (binaire)
title: Titre optionnel du document

Réponse :

{
  "success": true,
  "data": {
    "doc_id": "abc123",
    "title": "document.pdf",
    "storage_key": "abc123/document.pdf",
    "storage_provider": "local",
    "file_size": 1048576,
    "mime_type": "application/pdf",
    "checksum": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "checksum_algorithm": "SHA-256",
    "created_at": "2025-01-07T12:00:00Z",
    "is_new": true
  }
}

Obtenir le Contenu du Document

GET /api/v1/storage/{docId}/content

Retourne le fichier document avec l'en-tête Content-Type approprié.

Note : Nécessite une session authentifiée.

Sécurité

Authentification

• Tous les endpoints de stockage nécessitent une authentification
• Les documents ne sont accessibles qu'aux utilisateurs authentifiés
• Protection CSRF sur l'endpoint d'upload

Vérification de Checksum

• Checksum SHA-256 calculé automatiquement à l'upload
• Stocké dans les métadonnées du document
• Garantit l'intégrité du fichier

Validation des Fichiers

• Type de fichier vérifié contre les types MIME autorisés
• Taille du fichier validée contre ACKIFY_STORAGE_MAX_SIZE_MB
• Nom de fichier assaini pour éviter les traversées de chemin

Schéma de Base de Données

Les documents uploadés ajoutent des champs à la table documents :

ALTER TABLE documents ADD COLUMN storage_key TEXT;
ALTER TABLE documents ADD COLUMN storage_provider TEXT;
ALTER TABLE documents ADD COLUMN file_size BIGINT;
ALTER TABLE documents ADD COLUMN mime_type TEXT;

Bonnes Pratiques

Choix du Stockage

Scénario	Stockage Recommandé
Déploiement serveur unique	Local
Plusieurs serveurs / scaling	S3
Environnement isolé	Local
Déploiement cloud-native	S3
Développement / tests	Local ou MinIO

Sauvegarde

Stockage local :

• Inclure le volume ackify_storage dans la stratégie de backup
• Utiliser docker-volume-backup ou outils similaires

Stockage S3 :

• Configurer le versioning du bucket
• Activer la réplication cross-région si nécessaire
• Utiliser les politiques de cycle de vie pour la rétention

Performance

• Activer SSL S3 en production (ACKIFY_STORAGE_S3_USE_SSL=true)
• Utiliser des endpoints S3 régionaux pour une latence réduite
• Considérer un CDN pour les documents fréquemment accédés

Limitations

• Taille maximum de fichier : configurable, 50MB par défaut
• Pas de scan antivirus (à implémenter au niveau infrastructure)
• Pas de génération d'aperçu de document
• Pas de compression automatique

Dépannage

L'upload échoue avec "Storage not configured"

Assurez-vous que ACKIFY_STORAGE_TYPE est défini à local ou s3.

Erreurs de connexion S3

1. Vérifiez le format de l'URL endpoint (inclure http:// ou https://)
2. Vérifiez l'access key et la secret key
3. Vérifiez que le bucket existe et est accessible
4. Vérifiez que le paramètre SSL correspond à l'endpoint

Erreur fichier trop volumineux

Augmentez ACKIFY_STORAGE_MAX_SIZE_MB ou réduisez la taille du fichier.

Permission refusée (stockage local)

Assurez-vous que le conteneur a accès en écriture au chemin de stockage :

docker exec ackify-ce ls -la /data/documents