ファイルとメディア

アプリの再起動・再デプロイ後も残したいファイルは、Files SDK または Media SDK で保存します。SDK は、アプリのコードから保存・読み取りなどを行うためのライブラリです。

アプリ内部で読み書きするファイルには Files、画面に表示したり利用者が開いたりするファイルには Media を使います。 Media に保存すると、ブラウザから直接開ける URL を使えるため、画像表示や添付ファイルの閲覧に適しています。

用途で選ぶ

	Files SDK	Media SDK
主な用途	アプリ内部の処理に使うファイルを保存・更新する	利用者に画像を見せる、PDF や添付ファイルを開いてもらう
例	設定 JSON、処理済み URL の一覧、中間集計ファイル	商品写真、申請書 PDF、利用者向けのレポート
読み取り方	サーバー側のコードが SDK で読み取る。配信用 URL は付かない	サーバー側のコードで読み取れるほか、ブラウザから URL で開ける
更新方法	同じ名前（キー）で上書きできる。更新頻度の目安は 1 キーにつき 1 秒に 1 回程度	上書きせず、新しいファイルとして保存するたびに ID が付く
1 ファイルの上限	10 MiB	50 MiB

ファイル形式だけで決める必要はありません。たとえば CSV でも、アプリ内部で集計に使うなら Files、利用者に渡すレポートなら Media が適しています。

Media の URL は誰でも開ける公開 URL ではありません。そのアプリを閲覧できるメンバーだけが、Keelson にログインして開けます。 Files も Media も、利用には keelson.yaml への追加設定は不要です。

再起動後もファイルを残すには

アプリが動くサーバー内のファイルは、再起動・再デプロイで失われます。この性質を「揮発性」と呼びます。/tmp や /data に書くだけでは、後で使うファイルを残せません。

Files / Media SDK で保存が完了すると、ファイルはアプリの再起動後も残ります。後から同期処理を行う必要はありません。顧客情報や案件など、項目ごとに検索・更新するデータには Managed SQLite を使ってください。

インストール

必要な SDK をアプリの依存パッケージに追加します。以下のコード例はサーバー側で実行します。通常は AI エージェントに、保存したいファイルと用途を伝えて実装を依頼できます。

言語	パッケージ
Node.js	npm install @keelsonhq/files @keelsonhq/media
Python	pip install keelson-sdk（from keelson import files, media）
Go	go get github.com/keelsonhq/go-sdk（.../go-sdk/files、.../go-sdk/media）

Files SDK

Files は、アプリが名前を付けて保存し、必要に応じて同じ名前で更新するファイルに向いています。Web アプリと定期実行ジョブの間で、保存したファイルを共有できます。

保存先の名前を「キー」と呼びます。settings.json や reports/2026-08.csv のように指定します。主な操作は、保存する write、読み取る read、削除する delete、キーの一覧を取得する list です。read はファイルがなければ null / None を返します。

次は、設定を保存して読み取り、レポートの一覧取得と削除を行う例です。

import * as files from "@keelsonhq/files";

await files.write("settings.json", JSON.stringify({ theme: "dark" }));
const raw = await files.read("settings.json");            // Uint8Array | null
const settings = raw ? JSON.parse(new TextDecoder().decode(raw)) : {};
const keys = await files.list("reports/");                // ["reports/2026-08.csv", ...]
await files.delete("reports/2026-07.csv");

import json
from keelson import files

files.write("settings.json", json.dumps({"theme": "dark"}))
settings = json.loads(files.read("settings.json") or "{}")   # read() -> bytes | None
keys = files.list("reports/")
files.delete("reports/2026-07.csv")

ローカルファイルから移す場合は、書き込みと読み取りの両方を SDK に変更します。Files には配信用 URL がないため、保存したファイルを利用者に渡したい場合は、アプリ側にダウンロード処理を実装するか、Media を使ってください。

Media SDK

Media は、アプリの画面で見せる画像や、利用者が開く PDF・添付ファイルに向いています。保存したファイルを Keelson が URL で配信するため、アプリ側にファイル配信用の処理を書く必要はありません。

保存して画面に表示する流れ

1. サーバー側のコードで put を呼び、ファイルを保存します。
2. 返されたファイル ID を、案件や商品などのデータと一緒に DB に記録します。
3. url(id) で URL を取得し、画面の画像やリンクに設定します。ブラウザがその URL にアクセスすると、Keelson が認証を確認してファイルを返します。

画像を保存するサーバー側の関数の例です。引数には、アップロードで受け取った画像データを渡します。

import * as media from "@keelsonhq/media";

async function savePhoto(imageBytes) {
  const id = await media.put(imageBytes, {
    contentType: "image/png",
    filename: "photo.png",
  });
  // id を DB に記録し、url を画面に返します。
  return { id, url: media.url(id) };
}

from keelson import media


def save_photo(image_bytes):
    file_id = media.put(
        image_bytes,
        content_type="image/png",
        filename="photo.png",
    )
    # file_id を DB に記録し、url を画面に返します。
    return {"id": file_id, "url": media.url(file_id)}

Keelson 上での URL は /__keelson/media/<ファイルID> という形式です。たとえば、画像の URL を <img> の src に、PDF の URL をリンクの href に設定します。

<!-- 保存したファイルの URL を設定する例 -->
<img src="/__keelson/media/画像のファイルID" alt="商品の写真" />
<a href="/__keelson/media/PDFのファイルID">申請書を開く</a>

ファイルの読み取りは Keelson が処理します。URL を知っているだけでは開けず、そのアプリの閲覧権限が必要です。

更新・削除とその他の操作

保存済みのファイルは上書きできません。差し替える場合は新しいファイルを保存し、DB に記録した ID を更新します。不要になった古いファイルは別途削除してください。

• サーバー側で中身を読み取るには get(id)、種類（Content-Type）とサイズを調べるには stat(id) を使います。
• 存在確認は exists(id)、削除は Node.js では del(id)、Python では delete(id) です。
• Content-Type を省略すると、ファイル名の拡張子から決まります。

ローカル開発

手元で開発するときは、Keelson の接続設定がなければ、どちらの SDK もローカルのフォルダにファイルを保存します。手元のファイルが、デプロイ時に Keelson の Files / Media に自動で移されるわけではありません。

• Files: ./.keelson/files/ 配下に実ファイルとして書きます。.keelson/ を .gitignore に入れてください
• Media: ./media/ 配下に書きます（MEDIA_DIR で変更可）

Keelson 上では、必要な環境変数を Keelson が設定します。

Media のローカルモードでは、URL の既定値は /media/<ファイルID> です。ブラウザで表示を確認するには、開発用サーバーにファイルを返す処理を用意してください。media.url() は URL を返す関数で、ローカルの HTTP 配信を開始するものではありません。

Files SDK のローカルモードは OS によって条件が違います。確実に動くのは Linux（WSL2 や Linux の devcontainer を含む）です。

SDK	Linux	macOS	Windows
Node.js	動く	標準では動かない。KEELSON_FILES_ALLOW_BESTEFFORT_LOCAL=1 で試験的に有効化できるが、環境によっては書き込みに失敗する	動かない
Python	動く	動く	動かない（POSIX 専用の API を使うため）
Go	動く	動く	動く

Node.js を macOS / Windows で使う場合や、Python を Windows で使う場合は、Linux の開発環境（devcontainer や WSL2）を利用してください。Media SDK のローカルモードにこの OS 制限はありません。

ファイルの管理と容量

• コンソールや CLI には、アプリのファイルを一覧表示・ダウンロード・差し替える機能はありません。利用者向けのファイル一覧はアプリに用意します。Media は保存した ID から閲覧用リンクを作り、Files は必要に応じてダウンロード処理を実装してください。
• 上限を超える大容量ファイルは、S3 互換などの外部オブジェクトストレージにアプリから直接保存してください（外部通信に制限はありません）

Files / Media のファイルはワークスペースのストレージ容量（プランと制限）に含まれます。

Managed SQLite のバックアップには、Files / Media のファイル本体は含まれません。DB を復元しても、削除したファイルは戻りません。

関連ページ

• データベース（Managed SQLite）
• 定期実行ジョブ — cron から Files SDK を使う