ストレージ

ObjectOS のファイル（添付ファイル、アップロード、生成されたドキュメント）は ストレージサービス を経由します。これは 2 つのアダプターを備えた プラガブルな抽象化レイヤーです。ローカルファイルシステム（デフォルト）と S3 互換（本番環境）です。

このサービスは @objectstack/service-storage によって提供され、 スタンドアロンおよびプロジェクトの起動時にデフォルトで有効になります。

ユーザーはどのように操作するか

ファイルは sys_file システムオブジェクトで追跡されます。レコード内に 生のパスとして保存されることはありません。これにより、データモデルが ストレージバックエンドから切り離されます。

ローカルファイルシステム（デフォルト）

適した用途: 開発、シングルノードのデプロイ、デモ。

// 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
});

スタンドアロンモード（プロジェクトなしの os start）では、ランタイムが .objectstack/data/uploads/ 配下にローカルストレージを自動的に構成します。 ルートディレクトリは OS_STORAGE_ROOT 環境変数で上書きできます。

本番環境での適合性はデプロイの形態によって決まります:

• ✅ デスクトップアプリ、シングルノードの社内ツール、エッジ / オンプレミスの アプライアンス — uploads/ ディレクトリがファイルシステムのバックアップに 含まれている（またはデスクトップアプリの場合はユーザー管理の同期フォルダー上に 存在する）限り、ローカルストレージで問題ありません。
• ❌ マルチノード、マルチ AZ、またはクロスリージョンの耐久性を必要とするもの — S3 互換ストレージを使用してください。

S3 互換（本番環境）

適した用途: 本番環境、マルチノード、耐久性 + ライフサイクル管理。

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)
  },
});

AWS SDK は通常のチェーンから認証情報を読み取ります:

Cloudflare R2

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

認証情報: R2 のアクセスキー ID + シークレットを、標準の AWS_* 環境変数 またはシークレットマネージャー経由で渡します。

MinIO（セルフホスト）

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,
  },
});

S3 バケットポリシー

ストレージは署名付きの PUT/GET URL を使用します。推奨されるバケットポリシー:

• すべてのパブリックアクセスをブロックする。
• CORS: ObjectOS のホスト名から PUT/GET を許可する。
• ライフサイクル: 未完了のマルチパートアップロードを 1〜7 日後に期限切れにする。 temp=true のタグが付いたオブジェクトを 24 時間後に期限切れにする。
• バージョニング + Object Lock: 任意。コンプライアンス対応のデプロイでは推奨。

REST インターフェイス

@objectstack/client がこれらを呼び出します。通常は直接アクセスする必要はありません:

ファイルごとの認可は、sys_file オブジェクトに対するセキュリティプラグインの 権限エバリュエーターによって処理されます。ストレージ層に個別の ACL を 用意する必要はありません。

ライブ構成

設定サービスが有効になっている場合（デフォルトで有効です）、管理者は Console → Configuration → Storage からストレージアダプターを再起動せずに 切り替えることができます:

• アダプター、バケット、リージョン、エンドポイントを選択する。
• 認証情報を貼り付ける（sys_setting 内で保存時に暗号化される）。
• 保存する前に Test connection をクリックする。

変更は次のリクエストから適用されます。再起動は不要です。

サイジング

次に読むべきもの

• システム設定 — ライブ構成と、 ストレージの切り替えで使用される設定サービス
• 本番環境への準備 — オブジェクトストレージの 耐久性とバックアップを含むチェックリスト
• GitHub 上の @objectstack/service-storage — ソースとすべてのオプションのリファレンス