基本コンセプト

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

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

基本の用語

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

「閲覧」は、アプリにアクセスして利用するための権限です。アプリ内でデータを登録・編集できるかどうかは、アプリ側の実装で決まります。

新しいアプリには、初期設定で次の権限が割り当てられます。

グループ	含まれるメンバー	アプリの権限
`everyone`	ワークスペースの全メンバー	閲覧
`developers`	Owner / Admin / Developer ロールのメンバー	管理（閲覧も含む）

特定のチームだけが利用できるようにする場合は、チームにアプリを共有するを参照してください。

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

アプリと Keelson の役割分担

データの保存には、Keelson が管理するアプリ専用のデータベース「Managed SQLite」と、ファイルや画像・動画を保存・取得するためのライブラリ「Files / Media SDK」を利用できます。これらを含め、Keelson が提供する機能とアプリ側で実装する処理は、次のように分かれます。

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

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

利用できる共通機能

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

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

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

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

keelson.yaml に次のように設定すると、アプリ専用の Managed SQLite が用意されます。

db:
  mode: libsql

接続情報は Keelson が渡します。接続してデータを読み書きするコードは、アプリ側で実装します。

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

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

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

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

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

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

アクセスがない状態が続くと、Web アプリは停止します。 次のアクセスで起動するため、停止後の最初の応答には通常より時間がかかることがあります。アクセス元に応答を返したあとも続ける処理は、完了まで実行される保証がありません。
アプリが動くサーバー内のファイルは、一時的な保存先です。 再起動や再デプロイで失われるため、残したいデータは Managed SQLite や Files / Media SDK を使って保存してください。

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