基本コンセプト

Keelson では、同じワークスペースに社内アプリとメンバーをまとめて管理します。アプリを増やすたびに、ログインやメンバー管理の仕組みを作り直す必要はありません。

このページでは、基本的な用語と、Keelson が用意する機能・アプリ側で実装する機能の違いを説明します。

基本の用語

用語	意味
ワークスペース	メンバーやアプリをまとめて管理する単位
アプリ	デプロイして利用する業務ツール。案件管理や日報など
メンバー	ワークスペースに参加している人
グループ	部署やチームなど、アクセス権をまとめて設定するためのメンバーの集まり
デプロイ	アプリのコードと設定を送り、Keelson 上で使える状態にすること

たとえば、同じワークスペースに「営業日報」と「経費申請」を作り、営業チームには営業日報、全社員には経費申請を共有できます。

アプリを開くときの仕組み

Web アプリや静的サイトをデプロイすると、HTTPS で保護された専用 URL が発行されます。証明書の取得や更新は Keelson が行います。

https://<ワークスペース>--<アプリ>.keelson.run

通常のアプリ画面は、URL を知っているだけでは開けません。Keelson がログインとアプリの閲覧権限を確認し、許可されたアクセスだけをアプリに渡します。

ブラウザ
   ↓
Keelson：ログイン・アプリの閲覧権限・IP 制御の条件を確認
   ↓
アプリ：画面を表示し、業務の処理を実行

アプリ側でログイン画面や Keelson のログインセッションを実装する必要はありません。誰がアクセスしているかは、Keelson が渡すユーザー情報で確認できます。

外部サービスからの Webhook など、ブラウザのログインを使わない呼び出しには別の設定を行います。詳しくは外部システムとの連携を参照してください。

メンバーとアクセス権をまとめて管理する

同じワークスペースのアプリでログインを共有する

ユーザーは 1 回ログインすれば、同じワークスペース内で閲覧権限のあるアプリを開けます。Keelson のログインをアプリごとにやり直す必要はありません。アプリが独自の外部認証も使っている場合は、そのログインが別途必要になることがあります。

グループにアプリごとの権限を設定する

メンバーとグループはワークスペースで管理し、アプリごとにグループへ権限を割り当てます。

権限	できること
閲覧（`view`）	アプリを開いて利用する
管理（`manage`）	アプリをデプロイし、設定やシークレットを変更する

新しいアプリには、既定で「全員に閲覧、開発者に管理」が割り当てられます。特定のチームだけに絞る場合はチームにアプリを共有するを参照してください。

管理権限は、業務上の承認権限とは別です。 「上司だけが申請を承認できる」「担当者だけが案件を編集できる」といったルールは、ユーザーやグループの情報を使ってアプリ側で実装します。

アプリと Keelson の役割分担

機能	Keelson が用意すること	アプリで実装すること
画面と業務処理	アプリの URL と実行環境	入力画面、集計、申請などの機能
ログインと権限	ログイン、メンバー管理、アプリを開ける人の確認	本人のデータだけ表示するなど、業務に応じた制御
データの保存	Managed SQLite、Files / Media SDK	保存先を使った読み書き
API キーなどの秘密情報	シークレットの保管とアプリへの受け渡し	受け取った情報を使う外部サービスへの接続
定期実行	設定した時刻・間隔で処理を起動	1 回分の処理を行って終了するコード
運用	ログ、アプリ一覧、Managed SQLite のバックアップと復元	業務上の処理結果やエラーをログに記録すること

通常は、AI エージェントに作りたい機能を伝え、アプリのコードと Keelson の設定を作成してもらいます。

利用できる共通機能

API キーなどをシークレットとして管理する

共通の API キーはワークスペースに設定し、アプリへ環境変数として渡せます。アプリごとに別の値を設定して上書きすることもできます。秘密の値をコードや keelson.yaml に直接書く必要はありません。

詳しくは環境変数とシークレットを参照してください。

アプリ専用のデータベースを用意できる

keelson.yaml に db.mode: libsql と書くと、アプリ専用の Managed SQLite が用意されます。接続情報は Keelson が渡しますが、接続してデータを読み書きするコードはアプリ側に必要です。

Managed SQLite にはバックアップと復元が付きます。Files / Media のファイルは、このバックアップの対象外です。保存先の選び方はデータベースとファイルとメディアを参照してください。

決まった時刻・間隔で処理を実行できる

毎朝の集計や定期的なデータ同期は、keelson.yaml の crons に設定します。Web アプリへのアクセスがなくても実行できます。設定方法は定期実行ジョブを参照してください。

アプリの一覧から運用状況を確認できる

コンソールでは、各アプリを誰が作ったか、誰が使えるか、最後にいつ利用・デプロイされたかを確認できます。作成者以外も、アプリの管理状況を把握できます。

起動とデータ保存について知っておくこと

アクセスがない状態が続くと、Web アプリは停止します。 次のアクセスで起動するため、停止後の最初の応答には通常より時間がかかることがあります。レスポンスを返した後の処理は、最後まで実行されることが保証されません。
サーバー内のローカルファイルは、再起動・再デプロイで失われます。 この性質を「揮発性」と呼びます。残したいデータは Managed SQLite、Files SDK、Media SDK などに保存してください。

実装時の注意点はアプリが動くタイミングと対応アプリと制約を参照してください。