diff --git a/content/docs/architecture.ja.mdx b/content/docs/architecture.ja.mdx new file mode 100644 index 00000000..0b2b36f8 --- /dev/null +++ b/content/docs/architecture.ja.mdx @@ -0,0 +1,137 @@ +--- +title: アーキテクチャ +seoTitle: "アーキテクチャ：何が動き、データがどこにあるか" +description: 実際に何を動かすことになるのか。導入するかどうかを評価しているエンジニアのために。 +editions: [community, cloud, enterprise] +translation: + source_sha: 9292459ed8a30885f3b5c660fb772187d5d1edb8ead66c12839ab7900dcbef3f + guide_rev: 1 + mode: auto +--- + +ObjectOS をデプロイしたときに何が動くのか（**ObjectOS Enterprise** で自社のマシン上で動かす場合も、**ObjectOS Cloud** で私たちが運用する場合も）、どのデータがネットワークの外に出て、どのデータが出ないのかを、実践的な視点から説明します。 + +メンタルモデルは、ひとつの定義と、それを実行するひとつのランタイムです。 + +1. **あなたの[オントロジー](/docs/ontology)**：ビジネスの定義です。オブジェクトとフィールド、リレーション、アクション、権限、フロー、そしてエージェントとツールの定義。ビュー、ダッシュボード、アプリ、翻訳は、そのプロジェクションとして横で作成されます。ほとんどはサンドボックス化されたツール API を通じて [AI Builder](/docs/build/ai-builder) が書き、ときには手で編集されます。実行される前に必ず検証され、バージョン管理され、監査されます。 +2. **単一の Node.js ランタイム**：そこから動作するアプリケーション（データベーススキーマ、REST API、Console の UI、エージェントが呼び出す MCP サーバー）を**導出**し、すべての呼び出しでそれを**強制**します。RBAC、行レベルとフィールドレベルのセキュリティ、共有、監査は、REST のリクエストにも、Console でのクリックにも、エージェントのツール呼び出しにも同じように適用されます。すべてがひとつのプロセスの中で、あなたのデータベースと通信します。 + +```text +your ontology + objects · relations · actions + permissions · flows · agents + + projections: views · dashboards + apps · translations + │ + ▼ +ObjectOS runtime + derives the app, enforces it + │ + ├──▶ database its schema + ├──▶ REST API /api/v1/* + ├──▶ Console /_console/ + └──▶ MCP server /api/v1/mcp +``` + +「ユーザーが望むものを説明した」と「それが稼働している」の間に、コード生成の手順もデプロイのパイプラインもありません。ランタイムは、ヒューマンインザループ（HITL）の承認の後に新しいメタデータをホットロードします。 + +## デプロイするもの [#what-you-deploy] + +ひとつのアプリを提供する、ひとつの Node.js プロセス。それだけです。ObjectOS Community では、オープンソースのイメージからそのプロセスを自分で実行します（`os start`）。ObjectOS Cloud では私たちが実行します。ObjectOS Enterprise では、[デプロイ](/docs/deploy)で説明しているライセンスされた Enterprise イメージからデプロイします。 + +```text +┌─────────────────────────────────────────────────────┐ +│ ObjectOS process │ +│ ┌───────────────────────────────────────────────┐ │ +│ │ HTTP dispatcher (/ · /api · /_console …) │ │ +│ ├───────────────────────────────────────────────┤ │ +│ │ ObjectKernel — this deployment's app │ │ +│ │ ├─ Auth (Better Auth) │ │ +│ │ ├─ Security (RBAC + row-level + field) │ │ +│ │ ├─ ObjectQL (data engine, generates SQL) │ │ +│ │ ├─ REST API generator │ │ +│ │ ├─ MCP server (/api/v1/mcp, on by default) │ │ +│ │ └─ Capabilities loaded per artifact │ │ +│ │ (audit, storage, jobs, queue, AI …) │ │ +│ └───────────────────────────────────────────────┘ │ +└──────────┬──────────────────────────────────────────┘ + │ + ▼ + Your business database + (Postgres / MySQL / SQLite / Turso / MongoDB) +``` + +複雑さは、静的にリンクされた単一のバイナリ程度です。サイドカーも、Kafka も、別のキャッシュレイヤーも必要ありません。必要になったときに追加すればよく、初日からそのコストを払う必要はありません。 + +**デプロイメントはひとつのアプリを提供します。** どのアプリかはデプロイメントレベルの判断であり（[起動モード](#boot-modes)を参照）、デプロイメントが提供するすべての人にとって同じアプリです。複数の組織が共有する、壁で区切られたデプロイメントでも同様です。デプロイメントを拡張するには、ひとつのプロセスに多くのアプリを詰め込むのではなく、同じプロセスの同一のレプリカを増やします。[Docker](/docs/deploy/docker) を参照してください。 + +## データの置き場所 [#where-your-data-lives] + +**ObjectOS Enterprise**（この表が記述するセルフマネージドのエディション）では、以下のものはどれもネットワークの外に出ません。**ObjectOS Cloud** では、同じプロセスが代わりに私たちのインフラストラクチャで動作します。どちらのエディションでも、オントロジー自体はあなたのものです。エクスポートして、オープンソースの ObjectStack ランタイムで実行できます。[データレジデンシー](/docs/reference/security#data-residency)には、データの各分類について、どこに保存され、ネットワークの外に出るかどうかが記載されています。 + +セルフマネージドの ObjectOS はライセンスをオンラインで検証します。Enterprise のエアギャップライセンスはオフラインで検証します。したがって、インターネットにまったくアクセスできないデプロイメントも動作し続けます。サポートされるライセンスとクラウドの姿勢の組み合わせについては、[エアギャップ](/docs/deploy/air-gapped)を参照してください。 + +## リクエストの処理 [#how-a-request-is-served] + +```text +1. Ingress / TLS termination (your load balancer) +2. HTTP dispatcher (security headers, request id) +3. AuthPlugin — session cookie, bearer token, or API key +4. SecurityPlugin — RBAC + row-level + field-level checks +5. Route handler — generated REST, MCP tool call, declarative action, + or custom +6. Data driver — ObjectQL compiles to SQL / Mongo query +7. Response with X-Request-Id propagated +``` + +エージェントの呼び出しも同じ経路をたどります。MCP クライアントは OAuth または API キーでユーザーとして認証し、同じ権限のチェックが、そのツール呼び出しが読み書きできる範囲を制限します。[AI ツールを接続する（MCP）](/docs/configure/mcp)を参照してください。 + +アプリは最初のリクエストが届く前にすでに解決されています。カーネルは起動時に構築され、それが終わるまでプロセスは[準備完了](/docs/deploy/docker)を報告しません。そのため、提供されるリクエストには、それが*どの*アプリに属するかを決める手順がなく、読み手が考慮すべきアプリごとのウォームアップもありません。リクエストのコストは、認証、権限のチェック、そしてコンパイル済みのクエリ 1 つです。 + +## 3 つの層（連携する場合にのみ重要） [#the-three-layers-only-matters-if-youre-integrating] + +ほとんどの顧客は **ObjectOS** だけを実行します。他の 2 つの層は、アーティファクトがどこから来るのかを知りたい場合のためにあります。 + +| 層 | 内容 | 動作する場所 | +|---|---|---| +| **フレームワーク**（`@objectstack/*`） | オープンソースのカーネル、ObjectQL、プラグイン、ドライバー | npm。ビルド時に取り込まれます | +| **コントロールプレーン**（任意） | コンパイル済みの `objectstack.json` アーティファクトを公開します。ホスト型の ObjectOS Cloud を使うことも、自前で運用することも、まったく使わないこともできます | あなたの CI、私たちのクラウド、またはあなたのノートパソコン | +| **ObjectOS** | フレームワーク上に構築された商用ランタイム環境 | **ObjectOS Cloud**（私たちが運用）または**あなたのインフラストラクチャ**（ObjectOS Enterprise） | + +単一のアプリを出荷するなら、コントロールプレーンは不要です。CI で `objectstack.config.ts → dist/objectstack.json` をコンパイルし、その JSON をイメージに入れて出荷します。複数のデプロイメントがインストールするアプリを公開する場合は、コントロールプレーンがそのカタログの置き場所になります。 + +## 起動モード [#boot-modes] + +実行中のアプリがどこから来るかはひとつの判断であり、デプロイメントがそれを宣言します。提供されるデフォルトは設定が不要です。その他の各モードは公開済みのアーティファクトを指定することで選択され、それぞれの正確な契約は[環境変数](/docs/reference/environment-variables)のリファレンスにあります。 + +| モード | 使う場面 | アプリの届き方 | +|---|---|---| +| **Config-authored** | 提供される形態。単一のアプリ、評価、エアギャップ、ほとんどの本番デプロイメント | ランタイムは、イメージ内で作成されたメタデータと、そこにインストールされたものを起動します | +| **Artifact-pinned** | アプリが、ランタイムのイメージとは別に、独自のペースでリリースされる | 1 つの変数が、公開済みのアーティファクトを URL で指定します。完全性の固定は任意です。アプリのアップグレードは、その変数の変更と再起動で済みます | +| **Composed** | 分離の壁の背後にある複数の組織が 1 つのデータベースを共有し、公開済みのアプリを実行する。ホスト型の単一アプリ SaaS の形態です | 同じアーティファクトの参照を、デプロイメント自身の設定から読み込むため、Enterprise プラグインが一緒に読み込まれます。エアギャップライセンスのみで、それ以外は[起動時に拒否されます](/docs/deploy/air-gapped) | + +デプロイメントが**コントロールプレーン**とも通信するかどうかは別の判断であり、クラウドの姿勢の変数で決まります。接続されたデプロイメントは、上記のどのモードでもかまいません。セルフマネージドのランタイムは、ファイルに貼り付けたキーではなく、デプロイメントがコントロールプレーンに**バインド**されたときに発行されたトークンで認証します。間違ったライセンスモードと間違ったクラウドの姿勢の組み合わせは、[起動時に拒否されます](/docs/deploy/air-gapped)。 + +## 性能の特性 [#performance-characteristics] + +**このページはレイテンシやメモリの数値を掲載しません。** 実行するのは、*あなたの*データベースに対して*あなたの*アプリを提供する、ダイジェストで固定したイメージであり、デプロイメントのサイジングに使う価値のある数値は、それを実際に計測したものだけです。このページが示せるのはその形です。各コストがどこから来るか、そしてそれを何として計測すべきかです。 + +| 特性 | どこから来るか、どう計測するか | +|---|---| +| **起動** | プロセスが起動し、このデプロイメントのアプリのためにカーネルを構築し、その後で初めて準備完了を報告します。自分のイメージとアーティファクトで、`/api/v1/ready` が 200 を返すまでの時間として計測します。アプリが大きく、読み込む機能が多いほど、処理は増えます。 | +| **リクエストのレイテンシ** | 認証、権限のチェック、そして ObjectQL がコンパイルしたクエリ 1 つ。リクエストごとにどのアプリを提供するかを解決する処理はないため、通常変動するのはデータベースとの往復です。自分のデータ量に対して、自分のパーセンタイルで計測してください。 | +| **メモリ** | このデプロイメントのメタデータの常駐コピー 1 つ、アプリが読み込む機能（オプションのプラグインなので、読み込みが少ないデプロイメントほど保持するものも少なくなります）、そして同時実行中の処理。アイドル時ではなく、自分の負荷のもとでコンテナの RSS を計測してください。 | +| **1 つのプロセスを超えて拡張する** | 同じプロセスのレプリカで、それぞれが同じアプリを提供します。レプリカが 2 つ以上になると、クラスタードライバーと同一の共有シークレットが必須になります。[Docker](/docs/deploy/docker) を参照してください。 | + +## なぜこの形なのか [#why-this-shape] + +- **ひとつの Node プロセス、サイドカーなし** → `docker run` に収まり、systemd のユニットに収まり、長時間動作するコンテナや VM に収まります。 +- **デプロイメントごとにひとつのアプリ** → メタデータはリクエストごとではなく起動時に一度だけ解決されるため、正しく設定すべきキャッシュのサイズがありません。複数の組織がデプロイメントを共有する場合も、組織はそのアプリを共有し、組織間の分離の壁はランタイムの内部で強制されます。 +- **宣言されたメタデータの上に生成される API** → CI にコード生成の手順はなく、公開すべきクライアント SDK もありません。API は構造上、データモデルと一致します。 +- **すべての機能はオプションのプラグイン** → イメージのサイズは、実際に使うものに応じて増減します。 + +## 次に進む [#where-to-go-next] + +- [本番環境への準備](/docs/operate/production)：実際のトラフィックに公開する前のチェックリスト。 +- [ランタイム設定](/docs/configure/runtime)：データベース、キャッシュ、シークレットの接続。 +- [ランタイムの機能](/docs/reference/runtime-capabilities)：どのオプションのパッケージがあり、何を有効にするか。 diff --git a/content/docs/ontology.ja.mdx b/content/docs/ontology.ja.mdx new file mode 100644 index 00000000..ebcec30c --- /dev/null +++ b/content/docs/ontology.ja.mdx @@ -0,0 +1,62 @@ +--- +title: ObjectOS におけるあなたのオントロジー +seoTitle: "ObjectOS におけるあなたのオントロジー：コア、プロジェクション、置き場所" +description: ObjectOS におけるあなたのオントロジーとは何か。ランタイムが実行するコア、その横で作成されるプロジェクション、置き場所、そしてオントロジーでないものを説明します。 +editions: [community, cloud, enterprise] +translation: + source_sha: 89b7e2e2e35db3cfc1e321a759eade603c86bbf958670a2c0abd7952bb51a8ab + guide_rev: 1 + mode: auto +--- + +**オントロジーこそがソフトウェアです。** ObjectOS において、*あなたのオントロジー*とは、ランタイムが実行するビジネスの定義です。型付けされ、バージョン管理されたひとまとまりの ObjectStack メタデータです。ランタイムはそこからデータベーススキーマ、REST API、Console、MCP ツールを導出し、すべての呼び出しでそれを強制します。このページはこの言葉をこのサイトに対応付けます。完全な説明は、ObjectStack ドキュメントの [Business Ontology](https://objectstack.ai/docs/concepts/ontology) にあります。 + +## コア [#the-core] + +オントロジーそのものは 6 種類のものから成ります。 + +| コア | 宣言するもの | このサイトでは | +|---|---|---| +| **オブジェクトとフィールド** | ビジネスのエンティティと、その型付きの属性 | [データモデル](/docs/build/data)、[フィールドタイプ](/docs/reference/field-types) | +| **リレーション** | オブジェクト間のルックアップと主従関係のリンク | [リレーションシップ](/docs/build/data/relationships) | +| **アクション** | ユーザー（または、作成者が公開した場合はエージェント）がレコードに対して呼び出せる操作 | [アクション](/docs/build/interface/actions) | +| **権限** | 誰が何を読み、作成し、編集し、削除できるか：権限セット、レコードアクセス、フィールドレベルのセキュリティ | [権限](/docs/configure/permissions) | +| **フロー** | ビジネスプロセス：フロー、レコードトリガー、スケジュール、承認、ワークフロー | [自動化](/docs/build/automation) | +| **エージェントとツールの定義** | アプリに付属する AI エージェント、そのスキル、エージェントが呼び出せるツール | [エージェント](/docs/build/agents) | + +## プロジェクション [#the-projections] + +ビュー、ダッシュボード、アプリ、翻訳もメタデータとして作成され、同じ検証ゲートを通過しますが、これらはオントロジーの一部ではなく、オントロジーの**プロジェクション**です。コアを変更すればそれらは追従し、1 つを削除しても、それが表示していたビジネスは変わりません。 + +| プロジェクション | 投影するもの | このサイトでは | +|---|---|---| +| **ビュー** | オブジェクトのフィールドと権限を、リスト、フォーム、カンバン、カレンダーに | [ビュー](/docs/build/interface/views)、[フォーム](/docs/build/interface/forms) | +| **ダッシュボード** | オブジェクトに対するクエリをグラフに | [ダッシュボード](/docs/build/interface/dashboards) | +| **アプリ** | オブジェクト、ビュー、アクションを、ナビゲーションできる製品にまとめたもの | [アプリ](/docs/build/interface/apps) | +| **翻訳** | すべてのラベルを、あるロケールに | [ローカライズ](/docs/configure/localization) | + +## ObjectOS での置き場所 [#where-it-lives-on-objectos] + +ひとつの定義が、3 つの形で存在します。 + +| 形 | 内容 | +|---|---| +| **テナントのメタデータ** | [AI Builder](/docs/build/ai-builder) と Studio が書き込むもの：デプロイメント内の稼働中のメタデータ。AI Builder による変更は、適用される前に人の承認待ちのキューに入ります | +| **リポジトリのソース** | 開発者とそのコーディングエージェントが [AI スキル](/docs/build/ai-skills)を使って書くもの：`objectstack.config.ts` とそのメタデータファイル。プルリクエストとしてレビューされます | +| **コンパイル済みアーティファクト** | `os compile` が生成するもの：デプロイメントが起動に使う `objectstack.json`。[起動モード](/docs/architecture#boot-modes)を参照してください。公開したものはすべて保管してください（[バックアップ](/docs/operate/backup)） | + +どの形で作成しても、メタデータは実行される前に同じ[検証ゲート](/docs/resources/glossary#validation-gate)を通過します。どちらのエディションでも、オントロジーはあなたのものです。通常の ObjectStack メタデータであり、エクスポートしてオープンソースの ObjectStack ランタイムで実行できます。 + +## オントロジーでないもの [#what-it-is-not] + +- **知識オントロジーではありません。** クラスの継承も、公理も、推論器もありません。定義は検証され、そして実行されます。 +- **既存システムの上のセマンティックレイヤーではありません。** セマンティックレイヤーは、自らが実行しないビジネスを記述します。あなたのオントロジーはシステムそのものです。データベース、API、UI、エージェントのツールはそこから導出されます。すでに運用しているデータベースを接続することは可能ですが、デフォルトでは読み取り専用で、まだ初期段階です。[既存システムの拡張](/docs/build/extend-existing-systems)を参照してください。 + +## さらに読む [#read-further] + +このサイトはランタイムを説明しています。概念は ObjectStack のサイトが扱います。 + +- [Business Ontology](https://objectstack.ai/docs/concepts/ontology)：この言葉の意味と、ランタイムがそれをどう実行するか +- [How ObjectStack compares](https://objectstack.ai/docs/concepts/compare)：知識オントロジー、セマンティックレイヤー、メタデータプラットフォーム、AI によるコード生成との比較 +- [When to use ObjectStack](https://objectstack.ai/docs/concepts/when-to-use)：現時点で適している場面と、適していない場面 +- [The Ontology Is the Software](https://objectstack.ai/blog/the-ontology-is-the-software)：長文の解説 diff --git a/content/docs/reference/cel.ja.mdx b/content/docs/reference/cel.ja.mdx new file mode 100644 index 00000000..435a67d9 --- /dev/null +++ b/content/docs/reference/cel.ja.mdx @@ -0,0 +1,92 @@ +--- +title: CEL 式 +seoTitle: "CEL 式：数式、述語、テンプレート" +description: 数式フィールド、検証ルール、表示条件、共有、フローの条件を支える式言語です。ObjectOS での使いどころ、いくつかの例、そして objectstack.ai にある言語の完全な説明を紹介します。 +editions: [community, cloud, enterprise] +translation: + source_sha: ba57e518fc6626502da8e3012659d4218d65c7703dcb70c1834432e11a711d17 + guide_rev: 1 + mode: auto +--- + +**完全な仕様：** [objectstack.ai の Expressions (CEL)](https://objectstack.ai/docs/data-modeling/formulas)。このページはその要約です。ObjectOS での使いどころと、いくつかの例を示します。 + +ObjectOS は、定義に小さく安全な式が必要な場所で [CEL](https://github.com/google/cel-spec)（Common Expression Language）を使います。CEL には副作用も I/O もなく、サーバー上で評価されます。式からは、評価対象のレコードが `record`（その以前の状態が `previous`）として見え、実行ユーザーがいる場合はそのユーザーが `current_user` として見えます。 + +## ObjectOS での使いどころ [#where-objectos-uses-it] + +| 場所 | 式が決めること | +|:--|:--| +| 数式フィールド | レコードから導出されるフィールドの値 | +| フィールドの `requiredWhen`、`visibleWhen`、`readonlyWhen` | このレコードでフィールドが必須か、表示されるか、編集できるか | +| 検証ルール | 書き込みが拒否されるかどうか（[検証ルール](/docs/build/data/validation-rules)） | +| 共有ルール | ユーザーのグループにどのレコードが付与されるか（[レコードアクセス](/docs/configure/permissions/record-access)） | +| アクションの `visible` / `disabled` | ボタンが表示されるかどうか | +| フローの開始条件とその分岐 | フローが実行されるかどうか、どちらに進むか（[フローと自動化](/docs/build/automation/flows)） | +| フィールドの `defaultValue` | 新しいレコードの初期値 | + +## 例 [#examples] + +**数式フィールド**：明細行の合計： + +```ts +subtotal: Field.formula({ + label: 'Subtotal', + expression: F`record.quantity * record.unit_price`, +}), +``` + +**検証**：完了日は未来でなければならない。`script` ルールの `condition` は*無効な*レコードを記述します。これが true のとき、書き込みは拒否されます。 + +```ts +// One validation rule, an entry of the object's `validations` +{ + type: 'script', + name: 'close_date_in_future', + message: 'Close date must be in the future', + condition: P`record.close_date <= today()`, +} +``` + +**表示条件**：商談が成立してから初めてフィールドを表示する： + +```ts +close_reason: Field.textarea({ + label: 'Close reason', + visibleWhen: P`record.stage == 'closed_won'`, +}), +``` + +**フローの条件**：金額が大きい場合だけ、レコード変更フローを開始する： + +```ts +// The `config` of a `start` node; the rest of the flow is omitted (see Flows). +config: { + objectName: 'opportunity', + triggerType: 'record-after-update', + condition: P`record.amount >= 1000`, +} +``` + +## 権限のチェック [#permission-checks] + +ObjectStack 17.5 以降、`current_user.can(object, verb)` は、実行ユーザーがオブジェクト権限を持っているかを尋ね、そのユーザーの実効的な権限に基づいて答えます。 + +```ts +discount: Field.percent({ + label: 'Discount', + defaultValue: cel`current_user.can('crm_quote', 'edit') ? 10 : 0`, +}), +``` + +サーバーは、選択肢の `visibleWhen`（ユーザーが選べない選択肢は `invalid_option` で拒否されます）、数式フィールド、CEL の `defaultValue` でこれに答えます。評価に権限のデータが伴わない場所（検証ルールがその一例です）では、`can()` は推測されるのではなく拒否され、式は失敗します。 + +## 式が間違っているとき [#when-an-expression-is-wrong] + +黙って失敗することはありません。形式が不正な式や、オブジェクトにないフィールドを指定する式は、場所と「もしかして」のヒントを示して `os compile` で失敗します。実行時には、不正な式は `null` や `false` に評価されるのではなく、原因を特定したエラーを投げます。そのため、数式の値やガードの判断を黙って壊すのではなく、ログと監査証跡に失敗が表れます。 + +## 関連項目 [#see-also] + +- [数式](/docs/build/data/formulas)：アプリにおける数式フィールド +- [検証ルール](/docs/build/data/validation-rules)：書き込みを拒否する述語 +- [フィールドタイプ](./field-types)：数式フィールドと条件付きのプロパティ diff --git a/content/docs/reference/cli.ja.mdx b/content/docs/reference/cli.ja.mdx new file mode 100644 index 00000000..3ff61271 --- /dev/null +++ b/content/docs/reference/cli.ja.mdx @@ -0,0 +1,259 @@ +--- +title: CLI リファレンス +seoTitle: "CLI リファレンス：すべての os コマンドとそのフラグ" +description: すべての `os` コマンド、その動作、最も役立つフラグ。 +editions: [community, cloud, enterprise] +translation: + source_sha: 3a77aa68e28e880be0de253974a5977e4412d168b16c73e544224ce1bdd82412 + guide_rev: 1 + mode: auto +--- + +`@objectstack/cli` パッケージは、`os` という 1 つのバイナリ（`objectstack` としても利用可能）をインストールします。以下の例はすべて短い `os` を使います。 + +```bash +npm i -g @objectstack/cli +os --help +``` + +## サーバーのコマンド [#server-commands] + +### `os start`：設定不要の起動 [#os-start--zero-config-boot] + +段階的な 4 つのモードを自動検出します。 + +1. **空の起動**：カレントディレクトリにアーティファクトも設定もない → UI とマーケットプレイスを備えた素のカーネルで起動します。 +2. **プロジェクトの起動**：カレントディレクトリに `objectstack.config.ts` がある → `./dist/objectstack.json` に自動コンパイルし、そこから起動します。 +3. **アーティファクトの起動**：`dist/objectstack.json` に到達できる → そこから直接起動します。 +4. **明示的な上書き**：`--artifact`、`--database`、`--port` が優先されます。 + +```bash +os start # default port 3000 +os start --port 8080 +os start --artifact ./build/myapp.json +os start --artifact https://cdn.example.com/app.json +os start --database file:./data/prod.db +os start --database postgres://user:pass@host:5432/mydb +os start --database libsql://my-db.turso.io --database-auth-token $TURSO +os start --auth-secret "$(openssl rand -hex 32)" +os start --home /var/lib/objectos # persistent home dir +os start --no-ui # API only (no UI/Account portals) +``` + +HOME ディレクトリのデフォルト： +- カレントディレクトリにプロジェクトの設定がある場合 → `/.objectstack`（プロジェクトローカル） +- ない場合 → `~/.objectstack`（グローバル。実行間で共有） + +### `os serve`：本番サーバー [#os-serve--production-server] + +`objectstack.config.ts` があればそれを読み、なければ `dist/objectstack.json` にフォールバックします。厳格な動作が必要な本番のコンテナで使います。 + +代わりに**公開済み**のアーティファクトで起動するには、`OS_ARTIFACT_URL` で指定します。絶対的な `https://`、`http://`、`file://` の URL で、フラグメントに `#sha256=` による完全性の固定を任意で付けられます。設定が読み込まれる前に解決されます。古い綴りの `OS_ARTIFACT_PATH` は廃止されています。ObjectOS のランタイムイメージでは、デフォルト以外の値は代替の変数を示して**起動を拒否**します。[環境変数](/docs/reference/environment-variables#retired-names)を参照してください。 + +```bash +os serve # port 3000 +os serve --port 4000 --no-ui +``` + +### `os dev`：ホットリロード付きの開発 [#os-dev--development-with-hot-reload] + +`objectstack.config.ts` と `src/` を監視し、保存時に再コンパイルと再読み込みを行います。雛形から作成したプロジェクトでは、npm の `dev` スクリプトとして使われます。 + +```bash +os dev # port 3000 by default +os dev -p 4000 +``` + +`os dev` は `os start` と同じポート（3000）を要求します。そのポートが使用中の場合は次の空きポートにバインドし、`↪ server bound to port 3001 (requested 3000)` のようにその旨を表示します。 + +## プロジェクトのコマンド [#project-commands] + +### `os init`：新しいプロジェクトの雛形を作る [#os-init--scaffold-a-new-project] + +```bash +os init my-app # interactive +os init my-app -t app --install # auto-install with default pnpm +os init my-app -t app --install -p npm +os init my-app -t plugin # plugin scaffold +os init my-app -t empty # bare minimum +``` + +テンプレート： +| テンプレート | 得られるもの | +|---|---| +| `app` | 完全なアプリ。オブジェクト、ビュー、アクションがあり、すぐに拡張できます | +| `plugin` | 再利用可能な機能を配布するためのプラグインの雛形 | +| `empty` | マニフェストと tsconfig のみ | + +### `os create`：カーネルのコードプラグインの雛形を作る [#os-create--scaffold-a-kernel-code-plugin] + +```bash +os create plugin my-plugin +``` + +`os create plugin` は、カーネルの `Plugin` 契約を実装する TypeScript パッケージを書き出します。これは `os init` にはできないことです。`os create example` は ObjectStack 17.4 で廃止されました。`os init` が書き出すものの一部を書き出すだけだったため、現在は `os init` を示すエラーで終了します。 + +## ビルド / 検証のコマンド [#build--validate-commands] + +| コマンド | 目的 | +|---|---| +| `os compile`（`os build`） | `objectstack.config.ts` を `dist/objectstack.json` にコンパイルする | +| `os validate` | プロトコルのスキーマに照らして設定を検証する | +| `os lint` | スタイルと規約のチェック（CI で推奨） | +| `os diff ` | 2 つの設定を比較し、破壊的変更を検出する | +| `os info` | 設定またはアーティファクトのメタデータの概要を表示する | +| `os explain ` | オブジェクトのスキーマを人が読める形で説明する | +| `os doctor` | ヘルスチェック：循環依存、壊れた参照、環境の問題を検出する | +| `os generate`（`os g`） | TypeScript の型 / メタデータファイルを生成する | +| `os db clean` | 1 回限りの SQLite の `VACUUM` と、増分の自動バキュームの有効化。回収したバイト数を報告します（14.5 以降） | + +`os doctor` は、**何かおかしいと感じたときに最初に実行するもの**です。ランタイムでは実行時の警告としてしか表れない設定の誤りを捉えます。 + +ObjectStack 13 以降、`os compile` は**セキュリティの姿勢**によってもビルドを制限します。`validateSecurityPosture` のエラー（未設定や別名の共有モデル、高い権限を持つアンカーのバインディング、残っているロールの語彙、修飾されていないフィールド権限のキーなど）はビルドを失敗させ、`os lint` はそれらをループのより早い段階で報告します。`access-matrix.json` のスナップショットをコミットしている場合、権限の機能にずれがあると、`--update-access-matrix` で再スナップショットするまで `os compile` が失敗します。すべての機能の変更がレビュー可能になります。 + +## データのコマンド [#data-commands] + +ターミナルからレコードを操作します。シードデータの投入、マイグレーション、CI のスモークテストに便利です。 + +```bash +os data create --data '{"subject": "Hello"}' +os data get +os data query --filter 'status:active' --limit 10 +os data update --data '{"done": true}' +os data delete +``` + +## メタデータのコマンド [#metadata-commands] + +実行時にメタデータのレコード（オブジェクト、ビュー、権限セットなど）を読み書きします。 + +```bash +os meta list +os meta get +os meta register +os meta delete +``` + +## データベースのマイグレーション：`os migrate` [#database-migrations--os-migrate] + +`os migrate` は、デプロイメントのデータベースをメタデータと一致させ、リリースが求める 1 回限りのデータマイグレーションを実行します。すべてのサブコマンドは `--database-url` で指定したデータベースに対して動作します。デフォルトは `$OS_DATABASE_URL`、次にプロジェクト自身のデータベースなので、デプロイメントのデータベースを明示的に指定してください。いずれもメタデータを読むためにアプリを起動します。先にデータベースをバックアップしてください。各アップグレードで必要なコマンドは[アップグレードとロールバック](/docs/operate/upgrade#version-specific-steps)にあります。 + +### スキーマ [#schema] + +| コマンド | 動作 | +|---|---| +| `os migrate plan` | データベースがメタデータからどのようにずれているかを、安全、確認が必要、破壊的の変更として表示します。何も書き込みません | +| `os migrate apply` | 確認のプロンプトの後（`--yes` で省略）、破壊的でない変更を適用します。`--allow-destructive` を付けると、孤立した列の削除、`NOT NULL` の厳格化、型の縮小も行います | +| `os migrate multi-value-columns` | フィールドが `multiple: true` を宣言している場所で、古いテキスト列を JSON に移します。`apply` が決して行わない唯一の型変更です。`--apply` を付けるまではドライランです | +| `os migrate unmapped-columns --object NAME` | 廃止されたフィールドの列に残る値を、レコード id をキーとして読み取ります。読み取り専用です。17.7 以降、ランタイムのどの入り口もそれらの列を返さないため、`apply --allow-destructive` が列を削除する前に、変換処理はこの方法で値を読み取ります | +| `os migrate duplicates` | すでに 2 回発行された識別子と、一意インデックスを妨げる行を JSON で報告します。読み取り専用です | + +```bash +os migrate plan # what would change; writes nothing +os migrate apply --allow-destructive --yes # also drop and tighten (CI / scripts) +os migrate unmapped-columns --object contact --json > contact-unmapped.json +``` + +### データマイグレーション [#data-migrations] + +これらはいずれもスキーマではなく行を書き換えるもので、インストールしたバージョンではなく、データベースについての事実に関わります。ランタイムがこれらを代わりに実行することはありません。行に別の記載がない限り、`--apply` を渡すまではドライランです。 + +| コマンド | 動作 | +|---|---| +| `os migrate files-to-references` | （17.0）インラインで保存されたファイルフィールドの値を `sys_file` の参照に変換します。`--apply` は、このデプロイメントでメディアの値の厳格なチェックを有効にするフラグを記録します | +| `os migrate value-shapes` | （17.0）参照と構造化 JSON の値を、その契約に照らしてスキャンします。スキャンで何も見つからなくなると、`--apply` がフラグを記録します | +| `os migrate meta --from 17` | アプリの**ソース**に対してメタデータの変換チェーンを再実行し、行う編集を一覧表示します。`--out FILE` は変換後のスタックを書き出します。作成時の手順であり、データベースには触れません | +| `os migrate meta --stored` | 同じ変換を、このデプロイメントに**保存された**メタデータに対して行います。`--apply` で行を書き換えます | +| `os migrate account-issuer` | （17.5）`sys_account.issuer` 列を削除できるかを確認します。読み取り専用です。2 つのアカウントが衝突する間はゼロ以外で終了します | +| `os migrate audit-metadata-bodies` | （17.6）監査証跡とアクティビティストリームが保持するメタデータ本体のコピーを書き換え、認証情報と保存されたコンテンツハッシュを削除します | +| `os migrate summary-nulls` | 古い親の行で、まだ `NULL` として保存されているロールアップの `count` / `sum` の列を埋めます | +| `os migrate recorded-by` | メタデータの履歴にあるレガシーな `'system'` マーカーを `NULL` に書き換えます | +| `os migrate resume` | 中断されたマイグレーションの実行を一覧表示します。`--run ID` を付けるまでは読み取り専用で、付けるとその実行を再開または巻き戻します | + +```bash +os migrate account-issuer # read-only pre-flight +os migrate audit-metadata-bodies # dry run: what it would rewrite +os migrate audit-metadata-bodies --apply # rewrite +``` + +### シークレットと保存されたファイル [#secrets-and-stored-files] + +| コマンド | 動作 | +|---|---| +| `os secret rewrap` | 古い `sys_secret` の暗号文を 17.7 の形式で再封印します。`--apply` を付けるまではドライランです。ホストがコードでデータソースを宣言しているかどうかを指定する必要があります（`--declared-datasources FILE` または `--no-declared-datasources`）。⚠️ 17.7 より前のリリースは、これが書き込んだものを開けません | +| `os secret orphans` | もう何からも参照されていない `sys_secret` の行を報告します。削除するのは `--delete` を付けた場合だけです | +| `os storage orphans` | 何も保持しておらず、どの保持ポリシーも回収することのない保存ファイルを報告します。何も書き込みません | + +## i18n のコマンド [#i18n-commands] + +```bash +os i18n extract # extract translation keys from source +os i18n check # find missing keys across configured locales +``` + +## クラウドのコマンド [#cloud-commands] + +ObjectOS Cloud（オプションのホスト型コントロールプレーン）のユーザー向けです。 + +```bash +os login # interactive +os logout +os whoami +os register # create an account +os cloud login | logout | whoami +``` + +## 公開 / パッケージのコマンド [#publish--package-commands] + +```bash +os package publish # publish artifact as a versioned package +os package install # install into a RUNNING runtime: catalog id + # (com.acme.crm) or a compiled artifact JSON + # (air-gapped, inline). --runtime / --email / + # --password identify the runtime to install into +``` + +## 環境のコマンド [#environment-commands] + +コントロールプレーンに支えられた、プロジェクトごとに複数の環境（dev、staging、prod）を使うデプロイメント向けです。 + +```bash +os environments list +os environments show +os environments create +os environments switch +os environments bind # bind local artifact to an environment +``` + +## テストのコマンド [#test-command] + +```bash +os test # run Quality Protocol scenarios against a running server +``` + +## 共通のフラグの規則 [#common-flag-conventions] + +| フラグ | 意味 | +|---|---| +| `-p, --port` | HTTP ポート | +| `-a, --artifact` | コンパイル済みアーティファクトのパスまたは URL | +| `-d, --database` | データベース URL | +| `--home` | 永続的な状態のディレクトリ | +| `-v, --verbose` | 詳細な出力 | +| `--no-ui` | UI と Account ポータルを無効にする | + +完全なフラグの一覧は、任意のコマンドに `--help` を付けて実行すると表示されます。 + +```bash +os start --help +os data query --help +``` + +## CLI の位置づけ [#where-the-cli-fits] + +- **オペレーター / 初回実行** → `os start` +- **アプリを構築する開発者** → `os init` → `os dev` → `os compile` +- **CI / リリースパイプライン** → `os lint && os validate && os compile && os test` +- **本番のランタイム** → `os serve`（通常は Docker イメージの `CMD` の中） +- **デプロイメントのアップグレード** → [アップグレードのページ](/docs/operate/upgrade#version-specific-steps)が、お使いのバージョンについて挙げている `os migrate` の手順 +- **診断** → `os doctor`、`os info`、`os explain` diff --git a/content/docs/reference/environment-variables.ja.mdx b/content/docs/reference/environment-variables.ja.mdx new file mode 100644 index 00000000..029f1197 --- /dev/null +++ b/content/docs/reference/environment-variables.ja.mdx @@ -0,0 +1,162 @@ +--- +title: 環境変数 +seoTitle: "セルフホストのデプロイメントの環境変数" +description: セルフマネージドの ObjectOS デプロイメント（Community または Enterprise）の環境の契約です。各変数が何を決めるか、どのエディションがそれを読むか、どの組み合わせが起動時に失敗するか、どの名前が廃止されたかを説明します。 +editions: [community, enterprise] +translation: + source_sha: 470c8ef488571d10b3f0c678d447ccf97b2f06c6c29ef0f48515b291169ecb2c + guide_rev: 1 + mode: auto +--- + +環境変数は**デプロイメントレベル**の判断を担います。どのイメージが動いているか、データがどこにあるか、このデプロイメントが何であることを認められているか。デプロイメントの稼働中にテナントや管理者が変更できるべきものは、代わりにシステム設定に置きます。 + +このページは**契約**です。各変数が何を決めるか、そして 2 つの変数が食い違ったときに何が起きるかを示します。**エディション**の列は、どのイメージがそれを読むかを示します。 + +- **両方**：オープンな Community イメージ `ghcr.io/objectstack-ai/objectstack` と、ライセンスされた Enterprise イメージの両方。 +- **Enterprise**：Enterprise イメージ、またはそれに付属するデプロイバンドルのみ。 + +Community では、設定する値は [Docker](/docs/deploy/docker) に示しています。Enterprise では、**コピーする値**はリリースに付属するデプロイバンドルにあります。`.env` にコピーして編集する、注釈付きのテンプレートです。そのテンプレートはリリースに固定されていますが、このページはそうではありません。両者が異なる場合は、イメージとともに提供されたテンプレートが優先されます。 + +> **命名。** ObjectOS が所有する変数は `OS_` の接頭辞を使います。1.0 より前の接頭辞のない名前のいくつかは引き続き機能し、一度だけ非推奨の警告を出します。[レガシーな名前](#legacy-names)を参照してください。覚えている名前を使う前に知っておくべきグループが他に 2 つあります。何にも読まれないか起動をその場で拒否する[廃止された名前](#retired-names)と、まだ解決されるレガシーな名前です。 + +## すべてのデプロイメントが下す判断 [#the-decisions-every-deployment-makes] + +| 変数 | エディション | 決めること | +|---|---|---| +| `OS_EE_IMAGE` | Enterprise | どのイメージを実行するか。ランタイムではなく、バンドルの Compose スタックが読みます。タグではなく、必ず**ダイジェスト**を固定してください。[Docker](/docs/deploy/docker) を参照してください。 | +| `OS_AUTH_SECRET` | 両方 | セッションの署名に使う基本シークレット。未設定の場合、サインインエンドポイントはスキップされ、サーバーは認証なしで実行されます。**すべてのレプリカで同一**でなければなりません。ローテーションすると既存のすべてのセッションが無効になります。 | +| `OS_DATABASE_URL` | 両方 | デプロイメントが動作するデータベース。未設定の場合、ランタイムはホームディレクトリの下に SQLite ファイルを書き込み、コンテナではファイルシステムとともに失われます。本番ではマネージド PostgreSQL に向けてください。Enterprise では、バンドルのデータベースサービスを削除します。 | +| `OS_SECRET_KEY` | 両方 | 保存されたすべてのシークレット（暗号化された設定、`secret` フィールド、データソースの認証情報）を暗号化するキー。未設定の場合、ランタイムはキーを生成して自身のファイルシステムに保持し、コンテナでは再起動で失われます。32 バイトの値（`openssl rand -hex 32`）を設定し、シークレットマネージャーに保管し、データベースと一緒にバックアップしてください。複数のレプリカでは**必須**であり、すべてのレプリカで*同じ*値でなければなりません。[マルチノード](#multi-node)を参照してください。 | +| `OS_DB_USER`、`OS_DB_PASSWORD`、`OS_DB_NAME` | Enterprise | 提供される Compose スタックの**バンドルの**データベースサービスをプロビジョニングします。`OS_DATABASE_URL` の中の認証情報はこれらと一致していなければなりません。マネージドデータベースを使う場合は関係ありません。 | +| `AI_GATEWAY_API_KEY` | Enterprise | 「データに質問する」エージェントの背後にある AI プロバイダーの認証情報。 | + +## ライセンスとクラウドの姿勢 [#license-and-cloud-posture] + +この 2 つはペアです。片方を設定するときにもう片方を読まないのは、このページで最も高くつく間違いです。サポートされない組み合わせは、劣化するのではなく**起動時に拒否される**からです。 + +| 変数 | エディション | 決めること | +|---|---|---| +| `OS_LICENSE_KEY` | Enterprise | デプロイメントのエンタイトルメント。ライセンスには**モード**もあります。通常のライセンスはコントロールプレーンに対してオンラインで検証され、エアギャップライセンスはネットワークトラフィックを一切伴わずにローカルで検証されます。モードは発行されたライセンスの性質であり、ここで設定するものではありません。 | +| `OS_CLOUD_URL` | 両方 | このデプロイメントにコントロールプレーンがあるかどうか、あるならどれか。`off`（および別名の `none`、`local`、`disabled`）は**コントロールプレーンなし**を意味します。マーケットプレイスもライセンスの検証もありません。 | + +Community にはライセンスがないため、`OS_CLOUD_URL` が決めるのは、デプロイメントがコントロールプレーンに接続するかどうかだけです。Enterprise では 2 つの変数はペアであり、次の 2 つの帰結があります。どちらも人を驚かせます。 + +- **未設定は「off」ではありません**。どちらのエディションでもです。未設定の `OS_CLOUD_URL` は*公開*コントロールプレーンに解決されます。中立な値だったことは一度もなく、接続された動作を選びます。誰とも通信しないはずのデプロイメントは、`off` をはっきりと書かなければなりません。 +- **通常のライセンスと `off` の組み合わせは起動時に拒否され**、両方の変数が名指しされます。これは劣化した状態ではなく不可能な状態です。オンラインライセンスはコントロールプレーンを必要とする交換によって検証されるため、コントロールプレーンが設定されていなければ交換は行われず（今回の起動でも以降の起動でも）、猶予期間も始まりません。猶予は最後に*成功した*検証から計測されるからです。 + +サポートされる組み合わせの完全な表と、拒否の理由は[エアギャップデプロイメント](/docs/deploy/air-gapped)にあります。 + +## マルチ組織のデプロイメント [#multi-organization-deployments] + +**壁で区切られた**テナンシーの姿勢は、組織ごとの分離の壁を立てます。これはライセンスされた機能であり、さらに 3 つの判断を必須にします。それぞれが宣言されるまで、ランタイムは起動を拒否します。どの値を宣言しても受け入れられますが、決めないことは受け入れられません。 + +| 変数 | エディション | 決めること | +|---|---|---| +| `OS_TENANCY_POSTURE` | 両方。壁で区切られた値は Enterprise | 組織を互いに分離するかどうか。未設定または `single` は 1 つの組織です。壁で区切られた値は `isolated` と `group` です。壁で区切られた姿勢には**ライセンスが必要**です。ライセンスがない場合、ランタイムは分離されているふりをしてトラフィックを提供するのではなく、起動時に終了します。 | +| `OS_AUTH_MEMBERSHIP_POLICY` | 両方 | 新しいサインアップが何に参加するか。`auto` はすべての新規ユーザーをデプロイメントのデフォルトの組織に紐づけます。単一組織の環境には適切ですが、メンバーシップそのものがテナントの境界である場所では不適切です。`invite-only` は、明示的な行為（ワークスペースの作成、招待の承諾、管理者、SSO プロビジョニング）によってのみメンバーシップを付与します。**Setup → Authentication → Membership** でも設定できます。ここで設定するとその値に固定され、Setup のフィールドは読み取り専用になります。 | +| `OS_AI_STUDIO_AGENTS` | Enterprise | どの AI エージェントをマウントするか。`ask` と `build` のカンマ区切りの部分集合です。未設定では**両方**がマウントされます。`ask` は読み取ります。`build` は**メタデータを作成**します。そしてメタデータの範囲は組織ではなくデプロイメントなので、共有データベースでは、ある顧客の `build` のターンが、他のすべての顧客が使うスキーマを書き換えます。AI シートはこれをカバーしません。両方のエージェントに対する 1 つのフラグです。スペルの誤った値は、黙って両方のマウントにフォールバックするのではなく、起動を失敗させます。 | +| `OS_PLATFORM_OWNER_EMAIL` | 両方 | デプロイメントのプラットフォーム管理者が誰か。1 つのメールアドレス、またはカンマ区切りのリストです。壁で区切られた姿勢では、プラットフォーム管理者の地位の**唯一の**根拠です（ObjectStack 17.5 以降、そこでは `admin_full_access` の付与はその地位を与えません）。未設定または空の場合、ランタイムは起動を拒否します。列挙されたアカウントは、アドレスが**確認**されて初めてその地位を持つため、デプロイメントには確認の手段（メールの送信手段、または信頼できるフェデレーションによるサインイン）が必要です。解析できないエントリが 1 つでもあると、リスト全体が無効になります。変更は再起動で反映されます。 | + +単一組織のデプロイメントでは、これらのチェックは一切行われません。後の 3 つは未設定のままでかまいません。`OS_PLATFORM_OWNER_EMAIL` で指定されていない限り、最初に登録したアカウントがプラットフォーム管理者になります。指定されている場合は、その確認済みのアカウントがなります。 + +## マルチノード [#multi-node] + +マルチノードは Enterprise の機能です。Community のデプロイメントはレプリカ 1 つで実行され、それ以上を宣言すると（`OS_CLUSTER_REPLICAS` が 1 より大きい）、プロセスごとのロックでレプリカを実行するのではなく、起動を拒否します。レプリカを 2 つ以上にスケールすると、必須となるものが変わります。クラスタードライバー、そしてすべてのレプリカで同じ `OS_SECRET_KEY` と `OS_AUTH_SECRET` です。 + +| 変数 | エディション | 決めること | +|---|---|---| +| `OS_CLUSTER_DRIVER` | Enterprise | 共有のコーディネーターを有効にします。未設定は、組み込みのインメモリのコーディネーターでレプリカ 1 つを意味します。 | +| `OS_REDIS_URL` | Enterprise | そのコーディネーターの場所。 | +| `OS_CLUSTER_REPLICAS` | Enterprise | バンドルのスタックが起動するアプリケーションのレプリカ数。ランタイムも、宣言されたトポロジーとしてこれを読みます。マルチノードのライセンスなしで 1 より大きい場合、起動は拒否されます。 | + +クラスタードライバーが設定されると、`OS_SECRET_KEY` は**必須になります**。クラスタードライバーがない場合、各レプリカは独自のキーを生成して永続化します。レプリカ間ではそれらのキーが黙って食い違うことになるため、ランタイムは一貫しない暗号で提供する代わりに起動を拒否します。 + +## 公開済みアプリを実行する [#running-a-published-app] + +ランタイムのイメージと、それが提供するアプリは、独立したリリースの軸です。1 つの変数が公開済みアーティファクトを指定し、アプリのアップグレードはその変数の変更と再起動で済みます。イメージの再ビルドは不要です。 + +| 変数 | エディション | 決めること | +|---|---|---| +| `OS_ARTIFACT_URL` | 両方 | **アプリを選択する唯一の変数。** ビルド済みの `objectstack.json` を指す、絶対的な `https://`、`http://`、`file://` の URL で、URL フラグメントに SRI 形式の完全性の固定（`#sha256=` に続けて 16 進数 64 文字）を任意で付けられます。固定されたアーティファクトのバイトが一致しない場合、期待するダイジェストと実際のダイジェストを示して**起動を拒否**します。Community イメージが `/srv/app/objectstack.json` で探すアーティファクトを上書きします。Enterprise イメージでは、設定が読み込まれる前に解決されるため、この経路ではイメージ自身の Enterprise の配線は読み込まれません。 | +| `OS_COMPOSED_ARTIFACT_URL` | Enterprise | **composed** 形態（公開済みアプリをイメージの Enterprise プラグインと一緒に起動し、複数の組織が 1 つのデータベースを共有する）のアプリを選択します。この形態にはデプロイバンドル内に専用のテンプレートがあり、エアギャップライセンスのみで、`OS_CLOUD_URL=off` が必須です。どちらも起動時に強制されます。これと `OS_ARTIFACT_URL` の両方を設定すると、起動は拒否されます。 | + +完全性のハッシュ用の対となる変数は、意図的に用意していません。固定は URL フラグメントにあるため、コピーする値もローテーションする値も 1 つだけで、「URL は更新したがハッシュは更新していない」という状態は表現できません。 + +アーティファクトは**不変でバージョン名の付いた**オブジェクトとして公開し、アーティファクトのホストへの書き込み認証情報は公開パイプラインだけに与え、本番ではダイジェストを固定してください。この 3 つのルールがあるからこそ、ロールバック（古い URL を使った、アップグレードと同じ操作）が実際に機能します。 + +## ランタイムのサービス [#runtime-services] + +| 変数 | エディション | 決めること | +|---|---|---| +| `OS_PORT` | 両方 | ランタイムが待ち受ける HTTP ポート。Community イメージは `8080` を設定します。`os start` は別のポートに移ることはなく、使用中のポートでは起動に失敗します。レガシーな別名：`PORT`。 | +| `OS_AUTH_URL` | 両方 | サインインサーバーの公開ベース URL：コールバックと Cookie のオリジン。プロキシの背後と本番では必須です。 | +| `OS_CORS_ORIGIN` | 両方 | クロスオリジンのリクエストを受け入れるオリジン（カンマ区切り）。未設定では何も受け入れません。Console と API が同じ公開オリジンを共有している間は、何も受け入れる必要はありません。認証情報が有効な間、`*` は起動時に拒否されます。 | +| `OS_ENVIRONMENT_ID` | 両方 | 単一環境のランタイムが自身のものとして報告する環境 id。クラウドへのバインディングが完了するとこれが永続化され、その後のセルフホストのランタイムでは設定する必要がありません。 | +| `OS_TRUSTED_ORIGINS` | 両方 | 追加の信頼されたオリジン（カンマ区切り）。 | +| `OS_ROOT_DOMAIN` | 両方 | プラットフォーム SSO のデプロイメントで、サブドメインを信頼するために使うルートドメイン。 | +| `OS_DATABASE_DRIVER` | 両方 | `OS_DATABASE_URL` のスキームから推測されるドライバーを上書きします。スキームから推測できない場合にだけ設定してください。サポートされない値はフォールバックせずに失敗します。ObjectStack 17.7 以降、インメモリのエンジンは、ここで指定した場合（`memory`）も `memory://` の URL で指定した場合も、起動用のストアとして拒否されます。 | +| `OS_DATABASE_AUTH_TOKEN` | 両方 | 認証トークンを使うマネージドドライバー向けのトークン。 | +| `OS_SKIP_SCHEMA_SYNC` | 両方 | `1` に設定すると、起動時のスキーマ同期をスキップします。スキーマを帯域外で管理する場合に使います。Enterprise のデプロイバンドルのスタックは、どのレプリカよりも先に、別の 1 回限りの手順としてすでにマイグレーションを実行しています。 | +| `OS_TELEMETRY_DB` | 両方 | ライフサイクルで分類されるシステムデータ専用のデータソース。オプトアウトするには `0`、オプトインするにはパスまたは URL を設定します。 | +| `OS_STORAGE_LOCAL_ROOT` | 両方 | ローカルのファイルストレージアダプターがアップロードを保存する場所。作業ディレクトリからの相対パスです（デフォルトは `./.objectstack/data/uploads`）。データベースと一緒にバックアップしてください。設定すると **Setup → Settings → File Storage → Root directory** が固定されます。 | +| `OS_LIFECYCLE_DISABLED` | 両方 | `1` に設定すると、ライフサイクルサービス（保持期間による削除、テーブルのローテーション、監査のアーカイブ）を無効にします。保持期間自体は、環境変数ではなく `lifecycle.retention_overrides` 設定で調整します。 | +| `OS_AUTOMATION_SCHEDULED_WORK_ENABLED` | 両方 | アプリやパッケージが宣言するスケジュールされた処理を、デプロイメントが実行するかどうか。時間で起動する[フロー](/docs/build/automation/flows#scheduled-run-on-a-clock)（スケジュール、または相対時間のスイープ）と、パッケージ化された `defineJob` の cron ジョブです。オンになるのは `true`、`1`、`on`、`yes` だけです。**未設定はオフ**で、これは 17.5 以降、すべてのテナンシーの姿勢における ObjectStack ランタイムのデフォルトです。オフの間は時間で動くものは何も有効にならず、そのようなフローはそれぞれデプロイメントのポリシーにより無効と報告されます。プラットフォーム自身のスケジュール処理（承認のエスカレーション、保持期間、メッセージの配信）には影響しません。`isolated` では、スケジュールフローやジョブは実行時の組織も宣言しなければなりません。⚠️ お使いの ObjectOS イメージやデプロイバンドルのテンプレートがこれを設定してくれるかどうかは、このページでは約束できません。アプリがスケジュールフローに依存する場合は明示的に設定し、実効値を `os doctor` で確認してください。 | +| `OS_MCP_SERVER_ENABLED` | 両方 | `/api/v1/mcp` における HTTP 経由の Model Context Protocol サーバーを制御します。対象はそのサーフェスだけです。**デフォルトでオン**です。無効にするには、明示的に偽の値（`false`、`0`、`off`、`no`）を設定します。認証済みのプリンシパルが常に必要です。 | +| `OS_MCP_STDIO_ENABLED` | 両方 | 真の値に設定すると、長時間動作する **stdio** の MCP トランスポートを自動起動します。デフォルトはオフで、上記の HTTP サーフェスとは独立しています。 | +| `OS_MCP_STDIO_API_KEY` | 両方 | stdio トランスポートがプリンシパルとして紐づく API キー。HTTP の MCP と同じ認可チェーンで解決されるため、レコードとフィールドのレベルのセキュリティは引き続き適用されます。フェイルクローズです。stdio が有効で解決できるキーがない場合、トランスポートは起動しません。 | + +## オブザーバビリティ [#observability] + +エクスポートはオプトインです。エクスポーターのデフォルトは `noop` なので、選択するまでデプロイメントは何も出力しません。**エンドポイントを設定するだけでは何も起きません。** + +| 変数 | エディション | デフォルト | 決めること | +|---|---|---:|---| +| `OS_OBS_EXPORTER` | 両方 | `noop` | `noop`、`console`、`json`、`otlp`。ローカルのデバッグには `console` または `json` を、コレクターには `otlp` を使います。 | +| `OS_OTLP_ENDPOINT` | 両方 | — | OTLP/HTTP のルート URL。エクスポーターが `otlp` のときは必須です。空の場合、ランタイムは警告を出して `noop` にフォールバックします。 | +| `OS_OTLP_HEADERS` | 両方 | — | 追加の OTLP ヘッダー。カンマ区切りの `key=value` のペアです。 | +| `OS_OBS_SERVICE_NAME` | 両方 | — | 出力されるメトリクスの `service.name` リソース属性。 | +| `OS_OBS_DEPLOYMENT_ENV` | 両方 | `production` | `deployment.environment` リソース属性。 | +| `OS_OTLP_FLUSH_MS` | 両方 | — | OTLP エクスポーターのフラッシュ間隔（ミリ秒）。 | + +## データ契約の抜け道 [#data-contract-escape-hatches] + +ObjectStack 17.0 で、プラットフォームは宣言された契約に反する値を、以前のように警告して受け入れるのではなく、拒否するようになりました。これらの変数は、今すぐには修正できない連携のために、古い動作を**一時的に**再び有効にします。それぞれ `1` だけを受け付け、それ以外では厳格な動作のままです。違反は引き続きログに記録されるため、ずれは見えたままです。 + +| 変数 | エディション | 再び有効にするもの | +|---|---|---| +| `OS_ALLOW_LAX_ACTION_PARAMS` | 両方 | `params` が必須パラメーターを欠く、`options` / `multiple` / `reference` の宣言に反する、または宣言されていないキーを含むアクションの呼び出し。これがない場合、そのような呼び出しは `400 VALIDATION_FAILED` を返します。 | +| `OS_ALLOW_LAX_MEDIA_VALUES` | 両方 | 厳格にチェックされる場所での、不正な形式の `file` / `image` / `avatar` / `video` / `audio` の値。 | +| `OS_ALLOW_LAX_VALUE_SHAPES` | 両方 | 厳格にチェックされる場所での、不正な形式の参照（`lookup`、`master_detail`、`user`、`tree`）または構造化 JSON の値（`location`、`address` など）。 | + +メディアと値の形は、17.x のランタイムが作成したデータベースでは厳格にチェックされます。以前のメジャーバージョンからアップグレードしたデータベースは、対応するマイグレーションがフラグを記録して初めて厳格にチェックされます。[CLI → データマイグレーション](/docs/reference/cli#data-migrations)を参照してください。そこへ早く到達するために `OS_DATA_VALUE_SHAPE_STRICT_ENABLED=1` を使わないでください。これは、このデプロイメントのデータが実際に何を含んでいるかにかかわらず、すべての値の種類の厳格なチェックを一度にオンにします。 + +## システム設定を固定する [#pinning-a-system-setting] + +システム設定（テナントと管理者が編集できる `ai`、`email`、`feature_flags` などの名前空間）は、`OS_` に名前空間とキーを続け、大文字にして `.` と `-` を `_` に置き換えた名前の変数で、デプロイメントレベルで固定できます。たとえば `ai.openai_base_url` は `OS_AI_OPENAI_BASE_URL` に、`feature_flags.ai_enabled` は `OS_FEATURE_FLAGS_AI_ENABLED` になります。固定された設定は Setup では読み取り専用です。 + +**Setup → Authentication** で設定できる Google サインインも、デプロイメントレベルで `GOOGLE_CLIENT_ID` と `GOOGLE_CLIENT_SECRET` を読み取ります。 + +## 廃止された名前 [#retired-names] + +これらの名前は以前の ObjectOS のドキュメントに登場していました。ここに挙げるのは、引き継いだ設定ファイルを読んで修正できるようにするためであり、使えるようにするためでは**ありません**。行に別の記載がある場合を除き、いずれも両方のエディションで廃止されています。 + +| 廃止された名前 | 代わりに使うもの | +|---|---| +| `OS_ARTIFACT_FILE` | `OS_ARTIFACT_URL`。提供されるランタイムで `OS_ARTIFACT_FILE` を読むものはありません。これを設定したデプロイメントは何も設定しなかった場合と同じように起動し、間違いを指摘するエラーも出ません。ローカルファイルは代替の変数で `file://` として指定し、完全性の固定も代替の変数が担います。 | +| `OS_ARTIFACT_PATH` | `OS_ARTIFACT_URL`。**Enterprise イメージは、デフォルト以外の `OS_ARTIFACT_PATH` を持つ起動を拒否し**、代替の変数を示します。「どのアーティファクトで起動するか」を表す綴りが 2 つあるのは 1 つ多すぎますし、廃止された方は完全性の固定を持ったことがありません。Community イメージは、自身が探すパスである `/srv/app/objectstack.json` を今もこれに設定しています。そのままにしてアーティファクトをそこにマウントし、それ以外のアーティファクトは `OS_ARTIFACT_URL` で指定してください。 | +| `OS_BUSINESS_DB_URL` | `OS_DATABASE_URL`、またはアーティファクトで宣言したデータソース。`OS_BUSINESS_DB_URL` を読むものはありません。これだけを設定したデプロイメントには、データベースが一切設定されていません。 | +| `OS_LOCALIZATION_DATE_FORMAT`、`OS_LOCALIZATION_TIME_FORMAT`、`OS_LOCALIZATION_NUMBER_FORMAT`、`OS_LOCALIZATION_FIRST_DAY_OF_WEEK` | なし。ObjectStack 17.7 で、これらが固定していた設定は廃止され、日付、時刻、数値、週の始まりは言語に従うようになりました。[ローカライズ](/docs/configure/localization#dates-times-and-numbers-follow-the-language)を参照してください。 | + +`OS_CLOUD_API_KEY` は、セルフホストのデプロイメントが設定する変数では**ありません**。ホスト型のクラウドが自ら運用するランタイムに注入するサービスの認証情報であり、それとは別に、`os package publish` が CI からパッケージカタログに対して認証するために使うベアラートークンでもあります（[パッケージ](/docs/build/packages)を参照）。コントロールプレーンに接続するセルフホストのデプロイメントは、ファイルに貼り付けるキーではなく、デプロイメントがそのコントロールプレーンに**バインド**されたときに発行されたランタイムトークンを提示します。 + +## レガシーな名前 [#legacy-names] + +これらは両方のエディションで引き続き解決されますが、正式な名前が推奨され、レガシーな名前は将来のメジャーバージョンで削除される可能性があります。 + +| 正式な名前 | レガシー | 備考 | +|---|---|---| +| `OS_PORT` | `PORT` | 一度だけ非推奨の警告を出します。 | +| `OS_AUTH_SECRET` | `AUTH_SECRET` | 一度だけ非推奨の警告を出します。 | +| `OS_TENANCY_POSTURE` | `OS_MULTI_ORG_ENABLED` | 姿勢がレガシーなブール値から導出されるのは、`OS_TENANCY_POSTURE` が未設定の場合だけです。そこでの `true` は isolated を意味します。姿勢は直接宣言してください。ライセンスと起動時のチェックは、その変数に対して書かれています。 | +| `OS_MULTI_ORG_ENABLED` | `OS_MULTI_TENANT` | | diff --git a/content/docs/reference/field-types.ja.mdx b/content/docs/reference/field-types.ja.mdx new file mode 100644 index 00000000..1c9ffaee --- /dev/null +++ b/content/docs/reference/field-types.ja.mdx @@ -0,0 +1,96 @@ +--- +title: フィールドタイプ +seoTitle: "フィールドタイプ：各フィールドが保存し、表示するもの" +description: ObjectOS でフィールドタイプが決めるもの（列、API、フォームのウィジェット、AI Builder が尋ねる内容）を、いくつかの例と、objectstack.ai にある完全な一覧とともに紹介します。 +editions: [community, cloud, enterprise] +translation: + source_sha: d8cf773f496622e8a3d84f80d1e3e96dbcc89f6f2892ef7cf6847d049db4a2ca + guide_rev: 1 + mode: auto +--- + +**完全な仕様：** [objectstack.ai のフィールドタイプ](https://objectstack.ai/docs/data-modeling/field-types)。このページはその要約です。ObjectOS での使いどころと、いくつかの例を示します。 + +フィールドのタイプは、何を保存し、すべてのサーフェスがそれをどう扱うかを決めます。組み込みのタイプは 48 種類あります。テキスト、数値、日付、選択肢、リレーション、計算値、メディア、構造化データ、そして住所、評価、署名のようなより豊かな入力です。また、すべてのオブジェクトには、宣言しなくてもシステムフィールド（`id`、`created_at`、`updated_at`、`created_by`、`updated_by`）があります。 + +## ObjectOS での使いどころ [#where-objectos-uses-it] + +ひとつのフィールド定義が、これらすべてを動かします。 + +``` +*.object.ts (field spec) + │ + ├─► Postgres / MySQL / SQLite column + index + constraint + ├─► REST: validated on POST/PATCH, exposed on GET + ├─► UI: form widget + list column + ├─► AI Builder: tool argument schema (so the AI knows what to ask) + └─► Audit: change-tracked if `trackHistory: true` +``` + +- **データベース**には、列、そのインデックス、制約が作られます。 +- **REST API** は、書き込みのたびにフィールドを検証し、読み取りでそれを返します（[REST API](./rest-api)）。 +- **UI** は、タイプからフォームのウィジェットとリストの列を選びます。 +- **AI Builder** は、タイプがそのツールの引数スキーマなので、何を尋ねればよいかがわかります。 +- **監査**は、`trackHistory` がオンのとき、フィールドの変更を記録します。 + +## 例 [#examples] + +**選択肢**：`select` フィールドの選択肢： + +```ts +// Keys of a `select` field; its other keys are omitted. +options: [ + { value: 'low', label: 'Low' }, + { value: 'high', label: 'High', color: '#e02' }, + { value: 'urgent', label: 'Urgent', color: '#c00' } +] +``` + +**リレーション**：アカウントへのルックアップ。選択画面を有効なものに絞り込みます。 + +```ts +// One field. +{ + type: 'lookup', + reference: 'account', // target object name + lookupFilters: [ // narrow the lookup picker + { field: 'status', operator: 'eq', value: 'active' } + ], + deleteBehavior: 'set_null' // 'set_null' | 'cascade' | 'restrict' +} +``` + +**計算値**：[CEL](./cel) で書かれた数式フィールド： + +```ts +// One field. +{ + name: 'profit_margin', + type: 'formula', + expression: F`(record.revenue - record.cost) / record.revenue * 100` +} +``` + +**添付ファイル**：サーバーでチェックされるファイル： + +```ts +// One field. +{ + type: 'file', + multiple: true, // store an array of attachments + accept: ['image/png', 'image/jpeg'], // MIME types / extensions + maxSize: 10_000_000 // bytes +} +``` + +## メディア [#media] + +メディアフィールドは**不透明な `sys_file` id** を保存します。URL でも、インラインのメタデータの塊でもありません。レコードを読んだときに見える `{ url, name, size, mimeType, … }` オブジェクトは展開された形であり、所有する `sys_file` レコードから導出されます。`url` は `/files/:fileId` リゾルバーから来ます。 + +バイトはプラットフォームが所有するため、`accept` と `maxSize` はブラウザのファイル選択画面へのヒントにとどまりません。サーバーはすべてのレコードの書き込みをそれらに照らして再チェックするため、API を直接呼び出す呼び出し元もそれらを回避できません。ダウンロードには実際のファイル名とコンテンツタイプが付き、読み取りアクセスは所有するオブジェクトに委ねられます。既存のデプロイメントは `os migrate files-to-references` で変換します。バイトの置き場所は[ストレージ](/docs/configure/storage)を、マイグレーションについては [17.0 のリリースノート](https://objectstack.ai/docs/releases/v17)を参照してください。 + +## 関連項目 [#see-also] + +- [構築 → データモデル](/docs/build/data)：フィールドを組み合わせてオブジェクトにする +- [リレーションシップ](/docs/build/data/relationships)：ルックアップと主従関係 +- [ObjectQL](./objectql)：これらのフィールドのクエリ diff --git a/content/docs/reference/objectql.ja.mdx b/content/docs/reference/objectql.ja.mdx new file mode 100644 index 00000000..8e59d02d --- /dev/null +++ b/content/docs/reference/objectql.ja.mdx @@ -0,0 +1,77 @@ +--- +title: ObjectQL +seoTitle: "ObjectQL：JSON のクエリ形式、フィルター、結合" +description: データ API、ビュー、レポート、AI ツールを支える構造化クエリ形式です。ObjectOS での使いどころ、いくつかの例、そして objectstack.ai にある完全な構文を紹介します。 +editions: [community, cloud, enterprise] +translation: + source_sha: 694b3e7d0f7ea2228656bfed5c5c5b145b9a592f05c3dfea1c8efb55640a8505 + guide_rev: 1 + mode: auto +--- + +**完全な仕様：** [objectstack.ai の ObjectQL クエリ構文](https://objectstack.ai/docs/data-modeling/queries)。このページはその要約です。ObjectOS での使いどころと、いくつかの例を示します。 + +ObjectQL は、データエンジンが受け取る JSON のクエリ形式です。クエリはオブジェクトを指定し、どのレコードを返すかを記述します。`where` フィルター、`orderBy`、ページ（`limit`、`offset`）、`expand` するリレーション、そして任意で `aggregations` 付きの `groupBy` です。すべてのクエリは要求したユーザーとして実行されるため、そのユーザーが読めるレコードとフィールドしか返しません。 + +## ObjectOS での使いどころ [#where-objectos-uses-it] + +- **データ API**：`GET /api/v1/data/:object` はクエリ文字列のパラメーターとしてクエリを受け取ります。`POST /api/v1/data/:object/query` は完全な本文を受け取り、`groupBy` と `aggregations` を受け付けるのはこちらです（[REST API](./rest-api)）。 +- **ビュー**：ビューの `filter` と `sort` は ObjectQL にコンパイルされます（[ビュー](/docs/build/interface/views)）。 +- **レポート**：レポートは ObjectQL にシリアライズされます。 +- **AI**：`query_data` ツールは ObjectQL の本文を生成します。 + +## 例 [#examples] + +**緊急または期限切れの未解決チケット。** フィールドの演算子は `$` で始まります。`$and`、`$or`、`$not` がそれらを組み合わせ、`{ "$cel": "…" }` はサーバーがクエリ時に評価する [CEL](./cel) 式を埋め込みます。 + +```jsonc +{ + "$and": [ + { "status": { "$eq": "open" } }, + { + "$or": [ + { "priority": { "$in": ["high", "urgent"] } }, + { "due_at": { "$lt": { "$cel": "now()" } } } + ] + } + ] +} +``` + +**担当者と顧客アカウント付きのチケット。** 行ごとに 1 回リクエストするのではなく、1 回のバッチで解決されます。 + +```jsonc +{ + "object": "support_ticket", + "expand": ["assignee", "customer.account"], + "limit": 20 +} +``` + +**顧客ごとの月次売上で、10,000 を超えるもの。** `POST /data/order/query` を使います。 + +```jsonc +{ + "object": "order", + "where": { "status": { "$ne": "cancelled" } }, + "groupBy": [ + "customer_id", + { "field": "created_at", "dateGranularity": "month" } + ], + "aggregations": [ + { "function": "sum", "field": "amount", "alias": "total_sales" }, + { "function": "count", "alias": "order_count" } + ], + "having": { "total_sales": { "$gt": 10000 } }, + "orderBy": [{ "field": "total_sales", "order": "desc" }], + "limit": 25 +} +``` + +**クエリ文字列での並べ替え：** `?orderBy=-priority,created_at`。優先度の降順、次に古い順です。 + +## 関連項目 [#see-also] + +- [REST API](./rest-api)：ObjectQL を受け付けるエンドポイント +- [フィールドタイプ](./field-types)：各フィールドが何を保存し、したがって何で絞り込めるか +- [CEL](./cel)：`$cel` の中の式言語 diff --git a/content/docs/reference/rest-api.ja.mdx b/content/docs/reference/rest-api.ja.mdx new file mode 100644 index 00000000..f2043777 --- /dev/null +++ b/content/docs/reference/rest-api.ja.mdx @@ -0,0 +1,122 @@ +--- +title: REST API +seoTitle: "REST API：生成されるエンドポイント、認証、OpenAPI" +description: ObjectOS がメタデータから生成する HTTP サーフェスです。製品での使いどころ、いくつかの例、そして objectstack.ai にある完全な仕様を紹介します。 +editions: [community, cloud, enterprise] +translation: + source_sha: 9fa13b663d57b4d063262824875deb8a379c76338ec7272227af4e273972d0b1 + guide_rev: 1 + mode: auto +--- + +**完全な仕様：** [objectstack.ai の REST and GraphQL APIs](https://objectstack.ai/docs/api)。このページはその要約です。ObjectOS での使いどころと、いくつかの例を示します。 + +宣言したすべてのオブジェクトに REST エンドポイントが用意され、すべてのアクションは `POST` になり、すべてのフローは HTTP から開始できます。書いたりデプロイしたりする別の API レイヤーはありません。ベース URL は `https:///api/v1` で、実行中のランタイムは `/api/v1/openapi.json`（OpenAPI 3.0）と `/api/v1`（サービスディスカバリー）で自身を記述します。 + +[公開フォーム](#public-forms)や[共有リンク](#share-links)のように、宣言によって匿名の呼び出し元に開放されている場合を除き、`/api/v1` の下のすべてのルートには、サインイン済みのセッションまたはベアラートークンが必要です。権限はルートごと、レコードごとにチェックされます。オブジェクト、レコード、フィールドのレベルのセキュリティは、UI とまったく同じように API の呼び出し元にも適用されます。キーとトークンについては [API アクセス](/docs/configure/api-access)を参照してください。 + +## ObjectOS での使いどころ [#where-objectos-uses-it] + +| サーフェス | ルート | 利用者 | +|:--|:--|:--| +| データ | `/data/:object`、`/data/:object/:id`、`/data/:object/query` | 生成された UI、連携、インポートとエクスポート。クエリは [ObjectQL](./objectql) です | +| アクション | `/actions/:object/:action` | UI のボタン、そしてアクションが AI に公開されている場合はエージェント（[アクション](/docs/build/interface/actions)） | +| 自動化 | `/automation/:name/trigger`、`/automation/:name/runs` | 別のシステムからのフローの開始と、その実行の読み取り（[フローと自動化](/docs/build/automation/flows)） | +| メタデータ | `/meta/:type/:name` | これを通じて保存する Studio と、実行中のメタデータを読むツール | +| AI | `/ai/chat`、`/ai/pending-actions` | [AI Builder](/docs/build/ai-builder) とその承認キュー | +| 公開フォーム | `/forms/:slug` | 匿名の回答者向けに公開されたフォームビュー | + +## 例 [#examples] + +**未解決のチケットを新しい順に一覧表示する：** + +```http +GET /api/v1/data/support_ticket?where={"status":{"$eq":"open"}}&orderBy=-created_at&limit=20 +Authorization: Bearer +``` + +```json +{ + "object": "support_ticket", + "records": [ { "id": "...", "subject": "...", "status": "open" } ], + "total": 137, + "hasMore": true +} +``` + +**オブジェクトを API から外す、または読み取り専用にする。** `enable` ブロックで指定します。 + +```ts +import { ObjectSchema, Field } from '@objectstack/spec/data'; + +// A read-only reference object, never writable over the API: +ObjectSchema.create({ + name: 'exchange_rate', + enable: { apiMethods: ['get', 'list'] }, + fields: { + rate: Field.number({ label: 'Rate', scale: 6 }), + // ...more fields + }, +}) + +// An internal object that the API never exposes: +ObjectSchema.create({ + name: 'sync_cursor', + enable: { apiEnabled: false }, + fields: { + cursor: Field.text({ label: 'Cursor' }), + // ...more fields + }, +}) +``` + +**メッセージではなく、エラーコードで分岐する：** + +```json +{ + "error": { + "code": "PERMISSION_DENIED", + "message": "Missing ai:approve on conversation 01H…", + "httpStatus": 403, + "details": { "permission": "ai:approve", "subject": "01H…" } + } +} +``` + +## API サーフェスを制限する [#restricting-the-api-surface] + +オブジェクトの `enable` ブロックは、生成されるエンドポイントを制御します。`apiEnabled: false` はオブジェクトを REST サーフェスから完全に除外するため、そのルートは `404` を返します。`apiMethods` は `get`、`list`、`create`、`update`、`delete`、`bulk` の許可リストで、それ以外の操作は REST レイヤーで拒否されます。どちらも強制されます（ADR-0049）。以前のバージョンは、これらを解析するだけで適用していませんでした。 + +## 公開フォーム [#public-forms] + +セッションなしで応答します。フォームビューは `sharing` でオプトインし、3 つのキーすべてが必要です：`enabled: true`、`allowAnonymous: true`、そして `publicLink` のスラッグ。ObjectStack 17.7 以降、後の 2 つだけを設定したフォームは `404 FORM_NOT_FOUND` を返します。[ビュー → 公開フォーム](/docs/build/interface/views#public-forms)を参照してください。`GET /forms/:slug` はフォームを返し、`POST /forms/:slug/submit` はそれを送信します。 + +## 共有リンク [#share-links] + +これもセッションなしで応答します。リンクに含まれるトークンが認可です。`GET /share-links/:token/resolve` は、リンクが隠すフィールドを除いて、リンクが共有する 1 つのレコードを返します。サインイン済みのユーザーに限定されたリンクは、セッションのない呼び出し元に `401 SIGN_IN_REQUIRED` を返し、パスワードで保護されたリンクは、パスワードが送信されるまで `401 NEEDS_PASSWORD` を返します。リンクの作成、一覧表示、取り消し（`POST /share-links`、`GET /share-links`、`DELETE /share-links/:idOrToken`）にはセッションが必要です。[共有リンク：リンクを知っている全員](/docs/use/collaboration#share-links-anyone-with-the-link)を参照してください。 + +## フローのステータス表 [#flow-status-table] + +トリガーのルート、タイプ `flow` のアクション、宣言された `type: 'flow'` のエンドポイントは、すべて同じステータスを返します。本文の中の `success` フラグではなく、HTTP ステータスで分岐してください。 + +| ステータス | コード | 意味 | +|:--|:--|:--| +| `200` | — | 実行がディスパッチされました。その `status` は `completed`、`paused`（画面、承認、タイマーを待機中）、または `refused`（`outcome: 'refused'` の `end` ノードに到達。テキストは `refusalMessage` にあります）です | +| `404` | `RESOURCE_NOT_FOUND` | その名前のフローがありません | +| `409` | `FLOW_DISABLED` | フローがオフになっています | +| `422` | `FLOW_NO_START_NODE` | 保存された定義に開始ノードがなく、実行できません | +| `400` | `FLOW_FAILED` | 実行はディスパッチされましたが失敗しました。詳細にはフローの `errorMessage` が含まれます | + +## メタデータ：`/api/v1/meta/*` [#metadata--apiv1meta] + +`/meta/:type/:name` はメタデータ項目の唯一のアドレスです。スラッシュを含む名前はパーセントエンコードします（`GET /api/v1/meta/lead/views%2Fall_leads`）。セクション分けされた `/meta/:type/:section/:name` のルートは ObjectStack 17.3 で廃止され、`404 ROUTE_NOT_FOUND` を返します。保存には作成の機能が必要で、`datasource` のメタデータの読み取りや保存には `manage_platform_settings` が必要です。 + +## レポート [#reports] + +保存済みレポートの API はありません。ObjectStack 17.5 で `/reports`、`/reports/:id/run`、`/reports/:id/schedule` が削除され、現在は `404` を返します。レポートはメタデータであり、`/meta/report/:name` で読み取ります。その数値は分析（`POST /analytics/query`）から得られます。 + +## 関連項目 [#see-also] + +- [API アクセス](/docs/configure/api-access)：キー、トークン、誰が何を呼び出せるか +- [ObjectQL](./objectql)：`/data/*` が受け付けるクエリ形式 +- [セキュリティ](./security)：すべてのルートが実行前にチェックするもの diff --git a/content/docs/reference/runtime-capabilities.ja.mdx b/content/docs/reference/runtime-capabilities.ja.mdx new file mode 100644 index 00000000..2bba23cf --- /dev/null +++ b/content/docs/reference/runtime-capabilities.ja.mdx @@ -0,0 +1,66 @@ +--- +title: ランタイムの機能 +seoTitle: "ランタイムの機能：ベースとオプションのパッケージ" +description: ObjectOS が ObjectStack フレームワークのパッケージから読み込める機能。 +editions: [community, cloud, enterprise] +translation: + source_sha: 3beb96f0a63636343e3b8750462e6b3051b331b4addc65c3e2c18c93c9ec4d4e + guide_rev: 1 + mode: auto +--- + +ObjectOS はすべてのプロジェクトでベースのランタイムを読み込み、その後、アプリケーションのアーティファクトが宣言したオプションの機能をインストールします。 + +## ベースのランタイム [#base-runtime] + +ベースのプロジェクトカーネルには次のものが含まれます。 + +- ObjectKernel のライフサイクルとサービスレジストリ +- ObjectQL データエンジン +- 設定されたデータドライバー +- メタデータサービス +- アプリケーションのアーティファクトの登録 +- `OS_AUTH_SECRET` が設定されている場合の認証 +- RBAC、行レベルセキュリティ、フィールドのセキュリティのためのセキュリティプラグイン +- i18n サービス + +## オプションの機能 [#optional-capabilities] + +アーティファクトは `requires` リストで機能を宣言できます。ObjectOS は、イメージに存在する場合、一致するフレームワークのパッケージを読み込みます。 + +| 機能 | パッケージ | 目的 | +|---|---|---| +| `automation` | `@objectstack/service-automation` | フロー/DAG の実行と自動化ノード | +| `ai` | フレームワークのパッケージではありません。AI ランタイムは ObjectOS に付属します（[AI サービス](/docs/configure/ai)） | LLM アダプター、会話、ツール、SSE ルート | +| `analytics` | `@objectstack/service-analytics` | キューブ、分析クエリ、レポートのデータ | +| `audit` | `@objectstack/plugin-audit` | 監査ログのオブジェクトと監査証跡 | +| `cache` | `@objectstack/service-cache` | キャッシュの抽象化とアダプター | +| `storage` | `@objectstack/service-storage` | ファイル/オブジェクトストレージのサービス | +| `queue` | `@objectstack/service-queue` | キューの抽象化とワーカー | +| `job` | `@objectstack/service-job` | スケジュール/バックグラウンドのジョブ | +| `realtime` | `@objectstack/service-realtime` | WebSocket と pub/sub のリアルタイム | +| `settings` | `@objectstack/service-settings` | 設定のマニフェストと K/V リゾルバー | + +機能が要求されているのにイメージにそのパッケージが含まれていない場合、**ObjectOS は警告をログに出力し、その機能を無効にしたまま実行を続けます。** これは意図的な動作です。開発中にオプションのパッケージが欠けていてもランタイムが起動できるようにするためです。しかし**本番では現実のリスク**になります。 + +- 監査を必要とするアプリを `@objectstack/plugin-audit` のないイメージに読み込むと、問題なく起動し、**監査ログを一切書き込みません**。コンプライアンスの証拠が、エラーもなく欠落します。 +- ジョブで動くアプリを `@objectstack/service-job` のないイメージに読み込むと、問題なく起動し、**スケジュールされた処理を黙って一切実行しません**。 + +**本番のチェックリスト：** + +1. 機能の警告はデプロイの失敗として扱います。起動ログを `capability not loaded`（またはそれに相当するもの）で検索し、1 つでもあれば readiness プローブ / ロールアウトを失敗させます。 +2. ObjectOS ランタイムのイメージは、アーティファクトが `requires` で宣言するすべてのパッケージを含むものに固定します。 +3. アーティファクトを公開するときは、その `requires` リストを一緒に記載し、オペレーターが対応するイメージを確認できるようにします。 + +## API サーフェス [#api-surface] + +ObjectOS が一般的に公開するもの： + +- 生成された REST API +- `/api/v1/auth/*` の下の認証エンドポイント +- メタデータと i18n のエンドポイント +- 有効な機能のサービスエンドポイント + +OData はフレームワークレベルの機能であり、デプロイされたランタイムのパッケージに含まれ、かつ有効になっている場合にだけ、サポートされていると記載すべきものです。 + +**GraphQL はそれらに含まれません。** GraphQL のサーフェスは ObjectStack 17.0 で削除されました。このルートの背後にエンドポイントが実装されたことは一度もなく、現在 `/graphql` は 404 を返します。どのランタイムパッケージについても、利用可能またはオプションの機能として記載しないでください。（`graphql` は**外部データソース**のプロトコルとしては引き続き有効です。それは ObjectOS がクエリするシステムであり、ObjectOS が提供するサーフェスではありません。） diff --git a/content/docs/reference/security.ja.mdx b/content/docs/reference/security.ja.mdx new file mode 100644 index 00000000..7f6e2c51 --- /dev/null +++ b/content/docs/reference/security.ja.mdx @@ -0,0 +1,241 @@ +--- +title: セキュリティとコンプライアンス +description: 何が、どのように保護され、誰が責任を負うのか。セキュリティレビューのために。 +editions: [community, cloud, enterprise] +translation: + source_sha: f4b8cc8aeeb89ea330e8e0c536e84ad3f27d8bb2ae336f839e9321ab0da0c9a7 + guide_rev: 1 + mode: auto +--- + +このページは、セキュリティレビューの担当者、IT 管理者、そして「これを導入しても安全か」に答えなければならないすべての人のためのものです。 + +## 一文で表す脅威モデル [#threat-model-in-one-sentence] + +ObjectOS は、1 つのデータベースと通信する単一の Node.js プロセスとして動作します。**ObjectOS Enterprise** では**あなたの**ネットワークの中で、**ObjectOS Cloud** では私たちのネットワークの中で動作します。セルフマネージドの場合、ObjectOS が自ら行う唯一のアウトバウンドの呼び出しはライセンスの検証であり、Enterprise のエアギャップライセンスはオフラインで検証されます。侵害の影響範囲は、接続先のデータベース上のデータであり、それ以上ではありません。 + +## データレジデンシー [#data-residency] + +この表は、セルフマネージドのエディションである **ObjectOS Enterprise** について記述しています。**ObjectOS Cloud** では、同じ種類のデータが私たちがあなたのために運用するインフラストラクチャに置かれます。どちらのエディションでも、オントロジーはオープンソースの ObjectStack ランタイムへエクスポートできます。 + +| データの種類 | 置き場所 | ネットワークの外に出るか | +|---|---|---| +| 業務レコード | あなたのデータベース | **いいえ** | +| ユーザーアカウント、セッション、OAuth トークン | あなたのデータベース | **いいえ** | +| 監査ログ | あなたのデータベース | **いいえ** | +| 設定、API キー、シークレット | あなたのデータベース / あなたのシークレットマネージャー | **いいえ** | +| アップロードされたファイル | あなたのディスク、または S3 互換のバケット（S3、R2、MinIO） | **いいえ** | +| コンパイル済みのアプリ定義（`objectstack.json`） | ディスク上のファイル、またはあなたのコントロールプレーンから取得 | 任意 | +| ランタイム自体 | あなたのサーバーまたはコンテナ | **いいえ** | +| テレメトリ / 利用データ | — | **一切収集しません** | + +明示的に設定した連携（OIDC ディスカバリー、メールプロバイダー、AI プロバイダー、Webhook の送信先、外部ストレージ）以外で、セルフマネージドの ObjectOS が自ら行う唯一のアウトバウンドの呼び出しは**ライセンスの検証**です。Enterprise のエアギャップライセンスはオフラインで検証されるため、エアギャップのデプロイメントは何も呼び出しません。[ライセンスと料金](/docs/editions/license#faq)を参照してください。 + +## 暗号化 [#encryption] + +| 層 | 仕組み | 責任 | +|---|---|---| +| 通信中（ブラウザ ↔ ObjectOS） | TLS。あなたのエッジ / イングレスで終端 | あなた | +| 通信中（ObjectOS ↔ データベース） | ドライバーレベルの TLS（Postgres の `sslmode=require`、MongoDB の `tls=true` など） | あなた（接続文字列で設定） | +| 保存時（業務データ） | データベースネイティブ（例：Postgres TDE、RDS の暗号化） | あなた | +| 保存時（アップロードされたファイル） | ストレージネイティブ（S3 SSE、R2 のデフォルト、ディスクレベルの FDE） | あなた | +| DB 内のシークレット（設定、OIDC クライアントシークレット） | 設定サービスによって暗号化 | ObjectOS | +| セッション Cookie / トークン | `OS_AUTH_SECRET` で HMAC 署名 | ObjectOS | +| API キーの値 | DB では**ハッシュ化**。DB の行が漏洩してもキーは復元できません | ObjectOS | + +## 認証 [#authentication] + +組み込み（Better Auth を基盤とする `@objectstack/plugin-auth` による）： + +- 確認とリセット付きのメール/パスワード +- 取り消しが可能なセッション管理 +- ソーシャル OAuth（Google、GitHub、Microsoft、Apple など） +- エンタープライズの OIDC/SSO（Okta、Entra ID、Keycloak、Ping） +- 二要素認証（TOTP） +- パスキー / WebAuthn +- マジックリンク +- 電話番号と SMS の OTP によるサインインとパスワードリセット（`auth.plugins.phoneNumber` でオプトイン。Aliyun / Twilio のトランスポート、レート制限付き） +- CLI/ブラウザのデバイスフロー +- API キー（ハッシュ化、有効期限付き、取り消し可能、ユーザーに紐づく） +- MCP クライアント向けのセルフサービスの OAuth 2.1（認可コード + PKCE、動的クライアント登録、スコープから導出される権限の上限） +- 管理者主導のユーザー作成と一括インポート（`must_change_password` による強制変更付きのワンタイムパスワード） + +[認証](/docs/configure/authentication)を参照してください。 + +## 認可 [#authorization] + +Permission Model v2（ObjectStack 13、ADR-0090）に従った、層状の強制（`@objectstack/plugin-security` による）： + +1. **オブジェクト権限**：権限セットごと、オブジェクトごとの CRUD。ユーザーに直接、またはフラットな**ポジション**を通じて配布されます +2. **組織全体のデフォルト**：所有者を持つカスタムオブジェクトは、デフォルトで `private` の共有モデルになります。オブジェクトのデータへの匿名アクセスは無条件に拒否され、それを開くスイッチはありません（ObjectStack 17.0）。公開アクセスはサーフェスごとに宣言します（公開フォームまたは共有リンク）。`guest` アンカーは何も付与しません +3. **行レベルセキュリティ**：クエリに注入される宣言的なポリシー式。省略はできず、ランタイムが強制できないポリシーは範囲を広げるのではなく拒否します（ObjectStack 17.5） +4. **フィールドレベルのセキュリティ**：フィールドはレスポンスから除去されるか、部分的にマスクされるか（`maskingRule`、ObjectStack 17.1）、書き込み時に拒否されます（キーはオブジェクトで修飾され、lint で強制されます）。非表示またはマスクされたフィールドでは、絞り込み、並べ替え、グループ化、集計ができません。ObjectStack 17.6 以降、すべてのクエリの入り口で `403` になります +5. **組織のスコープ**：マルチテナントの分離。回避には明示的な `viewAllRecords` が必要です + +システムコンテキストの操作は、内部のジョブやマイグレーションが実行できるようにチェックを回避します。これらの経路は監査可能です。 + +それを支える仕組み： + +- **説明エンジン**：`explain(principal, object, operation)` は、強制と同じ評価器を使って、各層の判定を層ごとの根拠とともに報告します（構造上ずれは生じません）。 +- **作成時の lint**：`os compile` はセキュリティの姿勢（`security-owd-unset`、`security-anchor-high-privilege`、`security-fls-unqualified-key` など）によってビルドを制限します。また、任意でコミットする `access-matrix.json` のスナップショットにより、機能のずれがあると明示的に再承認されるまで CI が失敗します。 +- **委任された管理**：権限セットに `adminScope` を持たせると、サブ管理者は自分のビジネスユニットのサブツリー内でのみ、許可リストから、`granted_by` の監査付きで割り当てを管理できます。 +- **MCP のスコープの上限**：OAuth で接続した AI エージェントは `effective_permission = scope_ceiling ∩ user_grants`（`data:read` / `data:write` / `actions:execute`）のもとで実行され、フェイルクローズです。 + +[権限](/docs/configure/permissions)を参照してください。 + +## 監査と証拠 [#audit--evidence] + +監査機能（`@objectstack/plugin-audit`）が読み込まれている場合： + +- すべてのオブジェクトにおけるすべての CRUD 操作 → 監査の行。 +- フィールドの変更の変更前と変更後の値。 +- 認証、権限の付与、セッションの取り消しのイベント。 +- 監査の行は**改ざんできません**。変更はできず、アーカイブのみ可能です。 +- 保持期間はオブジェクトの `lifecycle` ブロックで宣言され（`sys_audit_log` は 90 日間ホット、その後アーカイブとして提供されます）、`lifecycle.retention_overrides` で環境ごとに調整できます。データベースのアーカイブポリシーと組み合わせてください。 + +これが、SOC 2 CC6/CC7、ISO 27001 A.12.4、HIPAA §164.312(b)、GDPR 第 30 条の証拠の基盤になります。 + +## コンプライアンスのフレームワーク [#compliance-frameworks] + +ObjectOS は、一般的なフレームワークのすべてが求める**技術的なプリミティブ**を提供します。認証はソフトウェアではなくデプロイメントの性質ですが、統制はきれいに対応します。 + +| フレームワーク | ObjectOS が提供するもの | +|---|---| +| **SOC 2** | アクセス制御（CC6）、変更管理（監査ログ）、暗号化（デプロイメント）、監視（オブザーバビリティ）、バックアップ（operate/backup） | +| **ISO 27001** | A.5 ポリシー（RBAC）、A.8 資産管理（オブジェクトのカタログ）、A.9 アクセス制御、A.12 運用、A.18 コンプライアンス | +| **HIPAA** | アクセス制御（§164.312(a)）、監査制御（§164.312(b)）、完全性（改ざんできない監査）、伝送のセキュリティ（TLS） | +| **GDPR** | 第 30 条 処理の記録（監査）、第 32 条 処理のセキュリティ、第 17 条 消去権（論理削除と物理削除をサポート）、データレジデンシー（リージョンを選択可能） | +| **CCPA / 中国データセキュリティ法 / ロシア 152-FZ** | 適切なリージョンの ObjectOS Enterprise でレジデンシーを満たします。アクセス制御と監査で、報告義務のほとんどをカバーします | + +認証の対象はバイナリではなく稼働中のデプロイメントであるため、ObjectOS 自体は**認証を受けていません**。あなたのデプロイメントは認証を受けることができ、すでに多くが受けています。 + +## シークレットの取り扱い [#secrets-handling] + +| シークレット | 置き場所 | +|---|---| +| `OS_AUTH_SECRET` | あなたのシークレットマネージャー（Vault、AWS Secrets Manager、k8s Secret）。環境変数として注入します | +| 認証情報を含むデータベース URL | 同上 | +| OIDC クライアントシークレット | 同上 | +| OAuth プロバイダーのシークレット | 同上 | +| API プロバイダーのキー（メール、ストレージ、AI） | 同上 | +| DB に保存された設定 | 保存時に設定サービスによって暗号化 | + +シークレットをアーティファクト（`objectstack.json`）、Docker イメージ、compose ファイル、Git に**決して**焼き込まないでください。Setup の設定 UI は、環境で管理された値をロックされた状態で表示するため、オペレーターが誤って上書きすることはありません。 + +## ネットワークモデル [#network-model] + +必須のインバウンド： +- イングレス / ロードバランサーから ObjectOS の `:3000`（デフォルト）への HTTPS。 + +必須のアウトバウンド： +- セルフマネージドの ObjectOS のライセンスの検証。Enterprise のエアギャップライセンスはオフラインで検証されるため、そのための送信は不要です。 + +次の機能を設定した場合にのみ必要なアウトバウンド： +- データベース（Postgres / Mongo / Turso など）。 +- S3 互換のストレージ（`storage` 機能を S3 アダプターで有効にした場合）。 +- OIDC のディスカバリー URL（SSO を有効にした場合）。 +- メールプロバイダーの API（Resend / Postmark）。 +- AI プロバイダーの API（OpenAI / Anthropic / Google など）。 +- Webhook の送信先。 + +送信のサーフェスはこれですべてです。さらに削減するデプロイメントについては[エアギャップ](/docs/deploy/air-gapped)を参照してください。 + +## AI：ツール、承認、分離 [#ai-tools-approvals-isolation] + +AI Builder は、公開するものの中で最もセキュリティに敏感なサーフェスです。そのため、上記のすべてに加えて独自の強制の層を持っています。 + +### AI が状態を変更する仕組み [#how-ai-can-mutate-state] + +モデルはデータベースに**直接書き込むことはできません**。状態が変わる唯一の方法は、構造化されたツール呼び出しを出力し、AI サービスがそれを受け取り、検証し、キューに入れることです。その流れは次のとおりです。 + +```text +user prompt + → model emits tool call (e.g. add_field { object: 'ticket', name: 'severity', type: 'select' }) + → AI service validates payload against the tool's Zod schema + → if the tool is "mutating": queue as pending action (no state change yet) + → human reviewer approves → mutation applied → audit row written + → if the tool is "read-only": run immediately, response returned to model +``` + +ファーストパーティのメタデータツールが 11 個あり（[構築 → AI Builder](/docs/build/ai-builder) を参照）、加えて、作成者が [AI に公開した](/docs/build/interface/actions#from-an-ai-agent)アクションごとに `action_` ツールが 1 つあります。公開とは、UI なしで実行されるタイプ（`script`、`flow`、`api`）で、40 文字以上の `ai.description` とともに `ai: { exposed: true }` を指定することです。公開されていないアクションはエージェントからは見えず、呼び出されても拒否されます。ファーストパーティでもカスタムでも、すべてのツールは同じライフサイクルを持ちます。 + +### 権限のキー [#permission-keys] + +| キー | 付与するもの | +|:--|:--| +| `ai:chat` | 会話を行う、モデルを使う、エージェントに読み取り専用のツールを呼び出させる | +| `ai:complete` | 生の補完エンドポイント（エージェントループなし） | +| `ai:conversations` | 会話の一覧表示 / 確認 / 削除（RBAC のスコープに応じて自分のものまたはすべて） | +| `ai:agents` | エージェントのメタデータの管理（呼び出すには `ai:chat` も必要） | +| `ai:tools` | ツールのカタログの一覧表示 | +| `ai:execute` | REST でツールを直接呼び出す（上級者向け。通常は常駐エージェントだけが必要とします） | +| `ai:read` | 保留中のアクションのキューとモデルの一覧の読み取り | +| `ai:approve` | キューに入った変更の承認 / 却下 | +| `ai:admin` | AI サービスの完全な管理 | + +重要な分離は **`ai:chat` ≠ `ai:approve`** です。アシスタントが機能するように、ほとんどのユーザーには `ai:chat` を付与し、`ai:approve` は構造的な変更をレビューすべき管理者 / アプリのオーナーに限定します。そうすれば、エンドユーザーは安全に「バイブビルド」できます。最悪の場合でも、他の誰かが承認しなければならない悪い変更をキューに入れるだけです。 + +### テナントの分離 [#tenant-isolation] + +- エージェント、会話、ナレッジベース、保留中のアクションは、1 つの **Environment**（テナント）にスコープされます。テナント A は、同じマーケットプレイスのパッケージから同じエージェント定義をインストールしていても、テナント B の会話、AI が提案したツール、ナレッジのコーパスを見ることはできません。 +- メタデータツール（`create_object`、`add_field` など）は、呼び出し元のテナントの**アクティブなパッケージ**に対して動作します。その外には届きません。 +- ツールの入力は CEL で検証され、エンジンは予約されたシステムパッケージ（`sys.*`）や他のテナントのオブジェクト名への参照を拒否します。 + +### 監査イベント [#audit-events] + +監査機能が読み込まれている場合： + +- `ai.chat.message`：ユーザー / アシスタントのすべてのメッセージ。モデルとトークン数付き +- `ai.tool.call`：ツール名、検証済みの入力、完全な出力（またはエラー） +- `ai.pending_action.queued`：提案された変更と、その完全な差分 +- `ai.pending_action.approved` / `.rejected`：誰が、いつ、なぜ決めたか +- `ai.metadata.applied`：メタデータストアへの実際の書き込みと、その差分 + +これらの行は改ざんできず、セキュリティレビューやチャージバックのためにエクスポートできます。（プロバイダー、モデル、ユーザー）ごとのトークン数が、コストの配分に使われます。 + +### プロンプトインジェクションへの姿勢 [#prompt-injection-posture] + +間接的なプロンプトインジェクション（エージェントが取得したドキュメント内の悪意あるコンテンツなど）は現実のリスクです。ObjectOS は構造的に影響範囲を縮小します。 + +- AI は**ツールの検証を回避できません**。悪意のあるペイロードを出力するよう説得されたとしても、Zod スキーマが不正な形式の入力をエンジンに届く前に拒否します。 +- 変更を行うツールは常にキューに入ります。注入されたプロンプトが黙ってデータベースに書き込むことはできません。 +- ツールの呼び出しは、モデルのサービスアカウントの権限ではなく、**エンドユーザーの権限**を継承します。ユーザーが UI や REST で自分ではできないことを、AI を使って行うことは決してできません。 +- エージェントに読み込まれるスキルは、バージョン管理された明示的なものです。[構築 → IDE スキル](/docs/build/ai-skills)と[構築 → AI Builder](/docs/build/ai-builder) を参照してください。 + +### 外部の AI プロバイダーへのデータの流れ [#external-ai-provider-data-flow] + +プロバイダー（OpenAI、Anthropic など）を設定した場合、ネットワークの外に出るのは次のものだけです。 + +- モデルが必要とする会話の履歴 +- ツールの定義（名前、JSON スキーマ。レコードのデータは含みません） +- モデルが続行するために必要なツールの出力（ユーザーが明示的に求めたクエリの結果など） + +エアギャップのデプロイメントでは、AI サービスをローカルの Ollama / vLLM / TGI のエンドポイントに向ければ、同じ流れが境界の内側にとどまります。 + +## 脆弱性の開示 [#vulnerability-disclosure] + +セキュリティの問題は **security@objectstack.ai** に非公開で報告してください。1 営業日以内に回答します。セキュリティの問題について、公開の GitHub issue を作成しないでください。 + +## サプライチェーン [#supply-chain] + +- **Community** イメージ `ghcr.io/objectstack-ai/objectstack` は公開されています。ObjectStack のリリースごとに、オープンソースの [objectstack-ai/objectstack](https://github.com/objectstack-ai/objectstack) リポジトリからビルドされて公開され、タグは内部の ObjectStack CLI のバージョンを反映しています。 +- **Enterprise** イメージはライセンスされたイメージで、プライベートレジストリから取得します。レジストリの認証情報はライセンスとともに提供されます。[デプロイ](/docs/deploy#the-two-images)を参照し、[Docker](/docs/deploy/docker#verify-the-image-before-production) の説明に従って本番の前にイメージを検証してください。 +- すべての `@objectstack/*` パッケージは、ソースが GitHub で公開されています。Apache-2.0 で、難読化はありません。 +- 本番では正確なイメージをひとつに固定し、ダイジェストで固定してください。決して動かないのはダイジェストだけです。Community では、正確なバージョンタグ（`X.Y.Z`）を実行し、そのダイジェストを固定します。`latest` のような移動するタグはリリースのたびに付け替えられ、公開済みのバージョンの再ビルドは、その `X.Y.Z` タグを新しいバイトに再プッシュします。Enterprise では、リリースノートに記載されたダイジェストを固定します。[Docker](/docs/deploy/docker#pin-the-image) を参照してください。 + +## 推奨される堅牢化のチェックリスト [#suggested-hardening-checklist] + +- [ ] 本物の証明書で、エッジで TLS が終端されている。 +- [ ] `OS_AUTH_SECRET` が 32 バイト以上のランダムな値で、シークレットマネージャーにある。 +- [ ] データベースの接続が TLS を使っている。 +- [ ] TLS の検証後に HSTS が有効になっている。 +- [ ] CORS のオリジンが明示されている（認証情報と `*` を決して組み合わせない）。 +- [ ] 認証エンドポイントにレート制限がある（`10/min/IP` を推奨）。 +- [ ] 監査の保持期間がポリシーと一致している。 +- [ ] 人のアカウントには OIDC、マシンのアカウントには API キー。 +- [ ] バックアップと復元の予行演習を実施し、所要時間を計測した。 +- [ ] 否定テスト：組織をまたぐアクセスが拒否される、フィールドのセキュリティが保たれる、期限切れのセッションが拒否される。 +- [ ] イメージが移動するタグではなく、ダイジェストで固定されている（Community では、正確なバージョンタグ `X.Y.Z` のダイジェスト）。 +- [ ] 各リリースの前に、CI で `os doctor` がクリーンである。 + +本番稼働の完全なチェックリストは[本番環境への準備](/docs/operate/production)を参照してください。 diff --git a/content/docs/reference/skills-cli.ja.mdx b/content/docs/reference/skills-cli.ja.mdx new file mode 100644 index 00000000..dbdf59e0 --- /dev/null +++ b/content/docs/reference/skills-cli.ja.mdx @@ -0,0 +1,48 @@ +--- +title: skills CLI +seoTitle: "skills CLI：コーディングエージェントにスキルをインストールする" +description: ObjectStack のスキルをコーディングエージェントにインストールする npx コマンドです。ObjectOS での使いどころ、いくつかの例、そして objectstack.ai にある完全なスキルリファレンスを紹介します。 +editions: [community, cloud, enterprise] +translation: + source_sha: 26df3bfe697fc1dcc37dc143c85b53c43d842b6b8a5801ad85e00738000a6399 + guide_rev: 1 + mode: auto +--- + +**完全な仕様：** [objectstack.ai の AI スキルリファレンス](https://objectstack.ai/docs/ai/skills-reference)。このページはその要約です。ObjectOS での使いどころと、いくつかの例を示します。 + +[`skills`](https://www.npmjs.com/package/skills) CLI（[vercel-labs/skills](https://github.com/vercel-labs/skills) 製）は、ドメインごとの指示を AI コーディングエージェントにインストールします。ObjectStack のスキルは、Claude Code、Cursor、Copilot、Codex などに、ObjectOS が実行するメタデータ（オブジェクト、ビュー、フロー、権限、クエリ、CEL）を実際のスキーマに沿って書く方法を教えるため、エージェントが書いたものはコンパイルが通ります。 + +## ObjectOS での使いどころ [#where-objectos-uses-it] + +- **IDE でアプリを手作業で作成する。** ブラウザ内の [AI Builder](/docs/build/ai-builder) は ObjectOS の中でメタデータを書いてくれます。リポジトリで作業する場合は、スキルが自分のコーディングエージェントに同じ語彙を与えます。[構築 → IDE スキル](/docs/build/ai-skills)を参照してください。 +- **エージェントを最新に保つ。** スキルは、それが説明するスキーマと並んで [objectstack リポジトリ](https://github.com/objectstack-ai/objectstack/tree/main/skills)にあるため、アップグレード後に再インストールすればエージェントが最新の状態になります。 + +## 例 [#examples] + +現在のプロジェクトにスキルを**インストール**します。CLI はプロジェクトが使っているエージェントを検出し、それぞれのネイティブ形式（`.claude/skills/`、`.cursor/rules/`、`AGENTS.md` など）で書き込みます。 + +```bash +npx skills add objectstack-ai/objectstack/skills +``` + +再現可能な CI のために**バージョンを固定**します。 + +```bash +npx skills add https://github.com/objectstack-ai/objectstack/tree//skills +``` + +インストールされているものを**確認・管理**します。 + +```bash +npx skills detect # show which agents the CLI will write to +npx skills list # list installed skills +npx skills remove # remove a skill +``` + +**出力をコミットします。** スキルは、チーム全体（CI のエージェントを含む）で共有すべき Markdown であり、CLI が書き込むパスはいずれにせよチェックインするものです。 + +## 関連項目 [#see-also] + +- [構築 → IDE スキル](/docs/build/ai-skills)：AI Builder と並ぶスキル +- [vercel-labs/skills](https://github.com/vercel-labs/skills)：アップストリームの CLI