Stockage

Les fichiers ObjectOS (pièces jointes, téléversements, documents générés) transitent par le service de stockage — une abstraction modulaire dotée de deux adaptateurs : le système de fichiers local (par défaut) et le mode compatible S3 (production).

Le service est fourni par @objectstack/service-storage et est activé par défaut lors des démarrages autonomes et de projet.

Comment les utilisateurs interagissent avec lui

Les fichiers sont suivis dans l'objet système sys_file — jamais sous forme de chemins bruts dans vos enregistrements. Cela découple votre modèle de données du backend de stockage.

Système de fichiers local (par défaut)

Adapté à : le développement, les déploiements mononœuds, les démos.

// objectstack.config.ts (or wherever you assemble plugins)
import { StorageServicePlugin } from '@objectstack/service-storage';

new StorageServicePlugin({
  adapter: 'local',
  local: {
    rootDir: './uploads',
    baseUrl: 'http://localhost:3000',  // for presigned URLs
    signingSecret: process.env.OS_STORAGE_SIGNING_SECRET, // optional; auto-generated if omitted
  },
  presignedTtl: 3600,   // seconds — TTL for presigned URLs
  sessionTtl: 86400,    // seconds — TTL for chunked upload sessions
});

En mode autonome (os start sans projet), le runtime configure automatiquement le stockage local sous .objectstack/data/uploads/. Remplacez le répertoire racine avec la variable d'environnement OS_STORAGE_ROOT.

L'adéquation à la production dépend de la forme du déploiement :

• ✅ Applications de bureau, outils internes mononœuds, équipements edge / on-premise — le stockage local convient, tant que le répertoire uploads/ est inclus dans la sauvegarde de votre système de fichiers (ou réside dans un dossier de synchronisation contrôlé par l'utilisateur pour les applications de bureau).
• ❌ Multinœuds, multi-AZ, ou tout ce qui nécessite une durabilité inter-régions — utilisez un stockage compatible S3.

Compatible S3 (production)

Adapté à : la production, le multinœuds, la durabilité + la gestion du cycle de vie.

pnpm add @aws-sdk/client-s3 @aws-sdk/s3-request-presigner

import { StorageServicePlugin } from '@objectstack/service-storage';

new StorageServicePlugin({
  adapter: 's3',
  s3: {
    bucket: 'my-bucket',
    region: 'us-east-1',
    // omit credentials to use the AWS SDK's default chain
    // (env, ~/.aws, IAM role)
  },
});

Le SDK AWS lit les identifiants depuis sa chaîne habituelle :

Cloudflare R2

new StorageServicePlugin({
  adapter: 's3',
  s3: {
    bucket: 'my-bucket',
    region: 'auto',
    endpoint: 'https://<account-id>.r2.cloudflarestorage.com',
    forcePathStyle: false,
  },
});

Identifiants : ID de clé d'accès R2 + secret, transmis via les variables d'environnement standard AWS_* ou votre gestionnaire de secrets.

MinIO (auto-hébergé)

new StorageServicePlugin({
  adapter: 's3',
  s3: {
    bucket: 'my-bucket',
    region: 'us-east-1',
    endpoint: 'http://minio.internal:9000',
    forcePathStyle: true,
  },
});

DigitalOcean Spaces

new StorageServicePlugin({
  adapter: 's3',
  s3: {
    bucket: 'my-bucket',
    region: 'nyc3',
    endpoint: 'https://nyc3.digitaloceanspaces.com',
    forcePathStyle: false,
  },
});

Politique de bucket S3

Le stockage utilise des URL présignées PUT/GET. Politique de bucket recommandée :

• Bloquer tout accès public.
• CORS : autoriser PUT/GET depuis le(s) nom(s) d'hôte de votre ObjectOS.
• Cycle de vie : expirer les téléversements multipart incomplets après 1 à 7 jours ; expirer les objets étiquetés temp=true après 24 heures.
• Versioning + Object Lock : optionnel, recommandé pour les déploiements soumis à des exigences de conformité.

Surface REST

@objectstack/client appelle ces points de terminaison — vous ne les sollicitez généralement pas directement :

L'autorisation par fichier est gérée par l'évaluateur de permissions du plugin de sécurité sur l'objet sys_file — vous n'avez pas besoin d'ACL distinctes au niveau de la couche de stockage.

Configuration en direct

Lorsque le service de paramètres est activé (c'est le cas par défaut), un administrateur peut changer d'adaptateur de stockage dans Console → Configuration → Storage sans redémarrer :

• choisir l'adaptateur, le bucket, la région, l'endpoint ;
• coller les identifiants (chiffrés au repos dans sys_setting) ;
• cliquer sur Test connection avant d'enregistrer.

Le changement s'applique à la requête suivante — aucun redémarrage requis.

Dimensionnement

Pour aller plus loin

• Paramètres système — configuration en direct et service de paramètres utilisé par les changements de stockage
• Préparation à la production — liste de contrôle incluant la durabilité et la sauvegarde du stockage d'objets
• @objectstack/service-storage sur GitHub — source et référence complète des options