From e4efd5c38b9b4d0764c6b3342c376a0d3501ab2e Mon Sep 17 00:00:00 2001 From: os-zhuang Date: Tue, 18 Aug 2026 05:34:35 +0000 Subject: [PATCH] docs: replace the retired runtime env contract outside Deploy (#60) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Nine pages outside `deploy/` still documented environment variables the shipped runtime does not read. `reference/environment-variables.mdx` was the worst of them, because a reference page is the one a reader treats as the contract — and since the Deploy rewrite landed it also *contradicted* a page shipping beside it, describing the cloud-posture variable as a switch for marketplace features while the deployment page states it is coupled to the licence mode with unsupported pairings refused at startup. Every variable in the rewrite was checked against the deployment bundle that ships with the release, and against the runtime and CLI source that reads it. What the evidence showed: - `OS_ARTIFACT_FILE`, `OS_BUSINESS_DB_URL`, `OS_CACHE_DIR` and `OS_PROJECT_ID` are read by nothing at all. A reader who sets one gets the boot they would have got with nothing set, and no error naming the mistake. - `OS_ARTIFACT_PATH` is retired on the runtime image and *refuses* a boot that carries a non-default value, naming its replacement. It was documented as a supported alternative on two pages. - `OS_CLOUD_API_KEY` is not a variable a self-hosted deployment sets. It is the service credential the hosted cloud injects into runtimes it operates, and the CLI's publishing bearer token. A self-hosted deployment authenticates with a token minted when it was bound. Three pages presented it as the deployment's cloud credential; the publishing page, which had it right, gains a note about the collision. - `OS_DATABASE_DRIVER` is NOT retired — it is the live driver override — so it is documented rather than removed. The reference page is rebuilt around the decisions a deployment actually makes: licence and cloud posture as a coupled pair, the walled-posture decisions that refuse to default, multi-node, and artifact selection. It carries a retired-name table so an inherited configuration file can be read and corrected. Variable names stay — they are the contract — but the values a customer copies stay in the release's deploy bundle, where they can be pinned to a version. Rows that could not be confirmed against any shipped artifact are not carried forward on a guess; they are reported for triage rather than restated. Stale translations of every rewritten page are deleted in six locales. Fumadocs falls back to English, measured here rather than assumed: the deleted siblings serve the new English body with localized chrome, while a page whose translation was kept still renders in its own language. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_0137TnZzVmkSjXxoSVgPFS6S --- content/docs/architecture.de.mdx | 137 -------- content/docs/architecture.es.mdx | 140 -------- content/docs/architecture.fr.mdx | 139 -------- content/docs/architecture.ja.mdx | 118 ------- content/docs/architecture.ko.mdx | 137 -------- content/docs/architecture.mdx | 23 +- content/docs/architecture.zh-Hans.mdx | 114 ------- content/docs/build/packages.de.mdx | 169 --------- content/docs/build/packages.es.mdx | 171 ---------- content/docs/build/packages.fr.mdx | 169 --------- content/docs/build/packages.ja.mdx | 134 -------- content/docs/build/packages.ko.mdx | 134 -------- content/docs/build/packages.mdx | 19 +- content/docs/build/packages.zh-Hans.mdx | 154 --------- content/docs/configure/runtime.de.mdx | 123 ------- content/docs/configure/runtime.es.mdx | 124 ------- content/docs/configure/runtime.fr.mdx | 123 ------- content/docs/configure/runtime.ja.mdx | 120 ------- content/docs/configure/runtime.ko.mdx | 124 ------- content/docs/configure/runtime.mdx | 215 ++++++------ content/docs/configure/runtime.zh-Hans.mdx | 102 ------ content/docs/operate/backup.de.mdx | 165 --------- content/docs/operate/backup.es.mdx | 165 --------- content/docs/operate/backup.fr.mdx | 168 --------- content/docs/operate/backup.ja.mdx | 154 --------- content/docs/operate/backup.ko.mdx | 153 --------- content/docs/operate/backup.mdx | 4 +- content/docs/operate/backup.zh-Hans.mdx | 137 -------- content/docs/operate/production.de.mdx | 80 ----- content/docs/operate/production.es.mdx | 80 ----- content/docs/operate/production.fr.mdx | 81 ----- content/docs/operate/production.ja.mdx | 77 ----- content/docs/operate/production.ko.mdx | 80 ----- content/docs/operate/production.mdx | 10 +- content/docs/operate/production.zh-Hans.mdx | 79 ----- content/docs/operate/troubleshooting.de.mdx | 92 ----- content/docs/operate/troubleshooting.es.mdx | 92 ----- content/docs/operate/troubleshooting.fr.mdx | 92 ----- content/docs/operate/troubleshooting.ja.mdx | 90 ----- content/docs/operate/troubleshooting.ko.mdx | 92 ----- content/docs/operate/troubleshooting.mdx | 76 +++-- .../docs/operate/troubleshooting.zh-Hans.mdx | 90 ----- content/docs/reference/cli.de.mdx | 205 ----------- content/docs/reference/cli.es.mdx | 206 ----------- content/docs/reference/cli.fr.mdx | 206 ----------- content/docs/reference/cli.ja.mdx | 206 ----------- content/docs/reference/cli.ko.mdx | 205 ----------- content/docs/reference/cli.mdx | 12 +- content/docs/reference/cli.zh-Hans.mdx | 197 ----------- .../reference/environment-variables.de.mdx | 119 ------- .../reference/environment-variables.es.mdx | 120 ------- .../reference/environment-variables.fr.mdx | 118 ------- .../reference/environment-variables.ja.mdx | 116 ------- .../reference/environment-variables.ko.mdx | 116 ------- .../docs/reference/environment-variables.mdx | 238 ++++++++----- .../environment-variables.zh-Hans.mdx | 106 ------ content/docs/resources/changelog.de.mdx | 210 ------------ content/docs/resources/changelog.es.mdx | 218 ------------ content/docs/resources/changelog.fr.mdx | 221 ------------ content/docs/resources/changelog.ja.mdx | 185 ---------- content/docs/resources/changelog.ko.mdx | 194 ----------- content/docs/resources/changelog.mdx | 9 +- content/docs/resources/changelog.zh-Hans.mdx | 323 ------------------ 63 files changed, 354 insertions(+), 7922 deletions(-) delete mode 100644 content/docs/architecture.de.mdx delete mode 100644 content/docs/architecture.es.mdx delete mode 100644 content/docs/architecture.fr.mdx delete mode 100644 content/docs/architecture.ja.mdx delete mode 100644 content/docs/architecture.ko.mdx delete mode 100644 content/docs/architecture.zh-Hans.mdx delete mode 100644 content/docs/build/packages.de.mdx delete mode 100644 content/docs/build/packages.es.mdx delete mode 100644 content/docs/build/packages.fr.mdx delete mode 100644 content/docs/build/packages.ja.mdx delete mode 100644 content/docs/build/packages.ko.mdx delete mode 100644 content/docs/build/packages.zh-Hans.mdx delete mode 100644 content/docs/configure/runtime.de.mdx delete mode 100644 content/docs/configure/runtime.es.mdx delete mode 100644 content/docs/configure/runtime.fr.mdx delete mode 100644 content/docs/configure/runtime.ja.mdx delete mode 100644 content/docs/configure/runtime.ko.mdx delete mode 100644 content/docs/configure/runtime.zh-Hans.mdx delete mode 100644 content/docs/operate/backup.de.mdx delete mode 100644 content/docs/operate/backup.es.mdx delete mode 100644 content/docs/operate/backup.fr.mdx delete mode 100644 content/docs/operate/backup.ja.mdx delete mode 100644 content/docs/operate/backup.ko.mdx delete mode 100644 content/docs/operate/backup.zh-Hans.mdx delete mode 100644 content/docs/operate/production.de.mdx delete mode 100644 content/docs/operate/production.es.mdx delete mode 100644 content/docs/operate/production.fr.mdx delete mode 100644 content/docs/operate/production.ja.mdx delete mode 100644 content/docs/operate/production.ko.mdx delete mode 100644 content/docs/operate/production.zh-Hans.mdx delete mode 100644 content/docs/operate/troubleshooting.de.mdx delete mode 100644 content/docs/operate/troubleshooting.es.mdx delete mode 100644 content/docs/operate/troubleshooting.fr.mdx delete mode 100644 content/docs/operate/troubleshooting.ja.mdx delete mode 100644 content/docs/operate/troubleshooting.ko.mdx delete mode 100644 content/docs/operate/troubleshooting.zh-Hans.mdx delete mode 100644 content/docs/reference/cli.de.mdx delete mode 100644 content/docs/reference/cli.es.mdx delete mode 100644 content/docs/reference/cli.fr.mdx delete mode 100644 content/docs/reference/cli.ja.mdx delete mode 100644 content/docs/reference/cli.ko.mdx delete mode 100644 content/docs/reference/cli.zh-Hans.mdx delete mode 100644 content/docs/reference/environment-variables.de.mdx delete mode 100644 content/docs/reference/environment-variables.es.mdx delete mode 100644 content/docs/reference/environment-variables.fr.mdx delete mode 100644 content/docs/reference/environment-variables.ja.mdx delete mode 100644 content/docs/reference/environment-variables.ko.mdx delete mode 100644 content/docs/reference/environment-variables.zh-Hans.mdx delete mode 100644 content/docs/resources/changelog.de.mdx delete mode 100644 content/docs/resources/changelog.es.mdx delete mode 100644 content/docs/resources/changelog.fr.mdx delete mode 100644 content/docs/resources/changelog.ja.mdx delete mode 100644 content/docs/resources/changelog.ko.mdx delete mode 100644 content/docs/resources/changelog.zh-Hans.mdx diff --git a/content/docs/architecture.de.mdx b/content/docs/architecture.de.mdx deleted file mode 100644 index 6ed04c3..0000000 --- a/content/docs/architecture.de.mdx +++ /dev/null @@ -1,137 +0,0 @@ ---- -title: Architektur -description: Was tatsächlich auf Ihren Systemen läuft — für die Engineers, die abwägen, ob sie dies einführen sollen. ---- - -Eine praxisnahe Sicht darauf, was auf Ihren Maschinen läuft, wenn Sie -ObjectOS bereitstellen, welche Daten Ihr Netzwerk verlassen und welche nicht. - -Das mentale Modell besteht aus zwei dünnen Schichten: - -1. **Metadaten** — Pakete aus Objekten / Views / Actions / Flows / - Agents. Größtenteils vom [AI Builder](/docs/build/ai-builder) - gegen eine sandboxed Tool-API geschrieben; teils von Hand bearbeitet, stets - versionskontrolliert und auditiert. -2. **Eine einzige Node.js-Laufzeit**, die diese Metadaten in eine - funktionierende Anwendung interpretiert — REST-API, Console-UI, Berechtigungen, Jobs, AI-Tools — alles in einem Prozess, der mit Ihrer Datenbank kommuniziert. - -Kein Codegenerierungsschritt, keine Deploy-Pipeline zwischen „Benutzer hat -beschrieben, was er möchte" und „es ist live". Die Laufzeit lädt die neuen -Metadaten nach einer HITL-Freigabe per Hot-Reload. - -## Was Sie bereitstellen - -Ein Node.js-Prozess pro ObjectOS-Instanz. Das ist alles. - -```text -┌─────────────────────────────────────────────────────┐ -│ ObjectOS process │ -│ ┌───────────────────────────────────────────────┐ │ -│ │ HTTP dispatcher (/ · /api · /_console …) │ │ -│ ├───────────────────────────────────────────────┤ │ -│ │ Per-project ObjectKernel (LRU cached) │ │ -│ │ ├─ Auth (Better Auth) │ │ -│ │ ├─ Security (RBAC + row-level + field) │ │ -│ │ ├─ ObjectQL (data engine, generates SQL) │ │ -│ │ ├─ REST API generator │ │ -│ │ └─ Capabilities loaded per artifact │ │ -│ │ (audit, storage, jobs, queue, AI …) │ │ -│ └───────────────────────────────────────────────┘ │ -└──────────┬──────────────────────────────────────────┘ - │ - ▼ - Your business database - (Postgres / MySQL / SQLite / Turso / MongoDB) -``` - -Es hat die Komplexität einer einzigen statisch gelinkten Binärdatei. Kein -Sidecar, kein Kafka, keine separate Cache-Schicht erforderlich. Fügen Sie diese hinzu, wenn Sie -sie brauchen; zahlen Sie nicht am ersten Tag dafür. - -## Wo Ihre Daten liegen - -| Daten | Liegen in | Verlassen Ihr Netzwerk? | -|---|---|---| -| Geschäftsdatensätze | Ihrer Datenbank | **Nein** | -| Benutzerkonten, Sitzungen, OAuth-Tokens | Ihrer Datenbank | **Nein** | -| Audit-Log | Ihrer Datenbank | **Nein** | -| Einstellungen, API-Schlüssel, Secrets | Ihrer Datenbank / Secret-Manager | **Nein** | -| Hochgeladene Dateien | Ihrer Festplatte oder Ihrem S3/R2-Bucket | **Nein** | -| Die kompilierte App-Definition (`objectstack.json`) | Einer Datei auf der Festplatte oder abgerufen von Ihrer Control Plane | Optional | - -ObjectOS telefoniert nicht nach Hause. Keine Telemetrie. Keine Lizenzprüfung. Wenn Sie den -Internetzugang vollständig kappen, läuft es unbegrenzt weiter. Siehe -[Air-gapped](/docs/deploy/air-gapped). - -## Wie eine Anfrage bedient wird - -```text -1. Ingress / TLS termination (your load balancer) -2. HTTP dispatcher (security headers, request id) -3. Hostname → project resolution (cached, TTL configurable) -4. Get or build per-project kernel from LRU -5. AuthPlugin — session cookie, bearer token, or API key -6. SecurityPlugin — RBAC + row-level + field-level checks -7. Route handler — generated REST, declarative action, or custom -8. Data driver — ObjectQL compiles to SQL / Mongo query -9. Response with X-Request-Id propagated -``` - -Die Schritte 4–8 werden typischerweise in < 5 ms ausgeführt, sobald der Kernel warm ist. - -## Die drei Schichten (nur relevant, wenn Sie integrieren) - -Die meisten Kunden stellen nur **ObjectOS** bereit. Die anderen beiden Schichten existieren, falls -Sie wissen möchten, woher das Artefakt stammt: - -| Schicht | Was es ist | Wo es läuft | -|---|---|---| -| **Framework** (`@objectstack/*`) | Open-Source-Kernel, ObjectQL, Plugins, Treiber | npm — zur Build-Zeit eingebunden | -| **Control Plane** (optional) | Veröffentlicht kompilierte `objectstack.json`-Artefakte; Sie können die gehostete ObjectStack Cloud nutzen, eine eigene betreiben oder sie ganz weglassen | Ihre CI, unsere Cloud oder Ihr Laptop | -| **ObjectOS** | Die Laufzeit, die Sie betreiben | **Ihre Infrastruktur** | - -Wenn Sie eine einzelne App ausliefern, benötigen Sie keine Control Plane — -kompilieren Sie `objectstack.config.ts → dist/objectstack.json` in Ihrer CI und -liefern Sie das JSON im Image aus. Wenn Sie einen internen App-Marketplace -mit vielen Tenants und Apps betreiben, ist die Control Plane der Ort, an dem der -Katalog liegt. - -## Boot-Modi - -| Modus | Wann | Wie | -|---|---|---| -| **Standalone** | Einzelne App, Entwicklung, Evaluierung, Air-gapped, die meisten Produktionsbereitstellungen | `pnpm dev` oder `dist/objectstack.json` von der Festplatte ausführen | -| **File-backed** | Produktion mit extern verwalteten Artefakten | `OS_ARTIFACT_PATH=/path/to/objectstack.json` setzen | -| **Cloud-connected** | Multi-Tenant- / Multi-App-Bereitstellungen, gespeist von einer Control Plane | `OS_CLOUD_URL` + `OS_CLOUD_API_KEY` setzen | - -Der Modus wird automatisch anhand von Umgebungsvariablen erkannt. - -## Performance-Eigenschaften - -| Metrik | Wert | -|---|---| -| Kaltstart (Prozess hochgefahren, bereit für Traffic) | ~1 Sekunde | -| Kernel-Warmup (erste Anfrage an ein Projekt) | 50–300 ms je nach Capabilities | -| Latenz bei warmer Anfrage (CRUD via REST) | typischerweise < 10 ms + Datenbanklatenz | -| Speicherbedarf | ~150 MB Basis; ~10–30 MB pro aktivem Projekt-Kernel | -| Gleichzeitige Projekte pro Instanz | Begrenzt durch `OS_KERNEL_CACHE_SIZE` (Standard 32) | - -## Warum diese Form - -- **Ein Node-Prozess, keine Sidecars** → passt in ein `docker run`, passt in eine - systemd-Unit, passt in eine Lambda-ähnliche Umgebung. -- **Per-Projekt-Kernel, LRU-gecacht** → eine Instanz kann viele - kleine Apps bedienen, ohne bei jeder Anfrage die Warmup-Kosten zu tragen. -- **Generierte APIs auf Basis deklarierter Metadaten** → es gibt keinen Codegen- - Schritt in Ihrer CI, kein Client-SDK zum Veröffentlichen; die API entspricht Ihrem Datenmodell konstruktionsbedingt. -- **Alle Capabilities sind optionale Plugins** → die Image-Größe skaliert mit dem, - was Sie tatsächlich nutzen. - -## Wie es weitergeht - -- [Production Readiness](/docs/operate/production) — Checkliste, bevor - Sie es echtem Traffic aussetzen. -- [Runtime Configuration](/docs/configure/runtime) — Verdrahtung von Datenbanken, - Caches und Secrets. -- [Runtime Capabilities](/docs/reference/runtime-capabilities) — - welche optionalen Pakete existieren und was sie ermöglichen. diff --git a/content/docs/architecture.es.mdx b/content/docs/architecture.es.mdx deleted file mode 100644 index 3b03172..0000000 --- a/content/docs/architecture.es.mdx +++ /dev/null @@ -1,140 +0,0 @@ ---- -title: Arquitectura -description: Lo que realmente estás ejecutando — para el ingeniero que evalúa si vale la pena adoptar esto. ---- - -Una visión práctica de lo que se ejecuta en tus máquinas cuando despliegas -ObjectOS, qué datos salen de tu red y cuáles no. - -El modelo mental son dos capas delgadas: - -1. **Metadatos** — paquetes de objetos / vistas / acciones / flujos / - agentes. En su mayoría escritos por el [AI Builder](/docs/build/ai-builder) - contra una API de herramientas en un entorno aislado (sandbox); a veces - editados a mano, siempre con control de versiones y auditados. -2. **Un único runtime de Node.js** que interpreta esos metadatos en una - aplicación funcional — REST API, Console UI, permisos, trabajos, herramientas - de IA — todo en un solo proceso, comunicándose con tu base de datos. - -Sin paso de generación de código, sin pipeline de despliegue entre "el usuario -describió lo que quería" y "está en producción". El runtime carga en caliente los -nuevos metadatos tras una aprobación HITL. - -## Lo que despliegas - -Un proceso de Node.js por instancia de ObjectOS. Eso es todo. - -```text -┌─────────────────────────────────────────────────────┐ -│ ObjectOS process │ -│ ┌───────────────────────────────────────────────┐ │ -│ │ HTTP dispatcher (/ · /api · /_console …) │ │ -│ ├───────────────────────────────────────────────┤ │ -│ │ Per-project ObjectKernel (LRU cached) │ │ -│ │ ├─ Auth (Better Auth) │ │ -│ │ ├─ Security (RBAC + row-level + field) │ │ -│ │ ├─ ObjectQL (data engine, generates SQL) │ │ -│ │ ├─ REST API generator │ │ -│ │ └─ Capabilities loaded per artifact │ │ -│ │ (audit, storage, jobs, queue, AI …) │ │ -│ └───────────────────────────────────────────────┘ │ -└──────────┬──────────────────────────────────────────┘ - │ - ▼ - Your business database - (Postgres / MySQL / SQLite / Turso / MongoDB) -``` - -Equivale a la complejidad de un único binario enlazado estáticamente. Sin -sidecar, sin Kafka, sin necesidad de una capa de caché separada. Añade esas -cosas cuando las necesites; no pagues por ellas desde el primer día. - -## Dónde viven tus datos - -| Datos | Viven en | ¿Salen de tu red? | -|---|---|---| -| Registros de negocio | Tu base de datos | **No** | -| Cuentas de usuario, sesiones, tokens OAuth | Tu base de datos | **No** | -| Registro de auditoría | Tu base de datos | **No** | -| Configuraciones, claves API, secretos | Tu base de datos / gestor de secretos | **No** | -| Archivos subidos | Tu disco o tu bucket S3/R2 | **No** | -| La definición compilada de la app (`objectstack.json`) | Un archivo en disco u obtenido desde tu plano de control | Opcional | - -ObjectOS no se comunica con el exterior. Sin telemetría. Sin verificación de -licencia. Si cortas el acceso a internet por completo, sigue funcionando -indefinidamente. Consulta [Air-gapped](/docs/deploy/air-gapped). - -## Cómo se atiende una solicitud - -```text -1. Ingress / TLS termination (your load balancer) -2. HTTP dispatcher (security headers, request id) -3. Hostname → project resolution (cached, TTL configurable) -4. Get or build per-project kernel from LRU -5. AuthPlugin — session cookie, bearer token, or API key -6. SecurityPlugin — RBAC + row-level + field-level checks -7. Route handler — generated REST, declarative action, or custom -8. Data driver — ObjectQL compiles to SQL / Mongo query -9. Response with X-Request-Id propagated -``` - -Los pasos 4-8 normalmente se ejecutan en < 5ms una vez que el kernel está -caliente. - -## Las tres capas (solo importa si estás integrando) - -La mayoría de los clientes despliegan únicamente **ObjectOS**. Las otras dos -capas existen por si quieres saber de dónde viene el artefacto: - -| Capa | Qué es | Dónde se ejecuta | -|---|---|---| -| **Framework** (`@objectstack/*`) | Kernel de código abierto, ObjectQL, plugins, drivers | npm — incorporado en tiempo de compilación | -| **Plano de control** (opcional) | Publica artefactos `objectstack.json` compilados; puedes usar el ObjectStack Cloud alojado, ejecutar el tuyo propio u omitirlo por completo | Tu CI, nuestra nube o tu portátil | -| **ObjectOS** | El runtime que operas | **Tu infraestructura** | - -Si estás distribuyendo una sola app, no necesitas un plano de control — -compila `objectstack.config.ts → dist/objectstack.json` en tu CI y -distribuye el JSON en la imagen. Si estás ejecutando un marketplace interno de -apps con muchos inquilinos y aplicaciones, el plano de control es donde reside -el catálogo. - -## Modos de arranque - -| Modo | Cuándo | Cómo | -|---|---|---| -| **Standalone** | App única, desarrollo, evaluación, air-gapped, la mayoría de despliegues de producción | `pnpm dev` o ejecuta `dist/objectstack.json` desde disco | -| **File-backed** | Producción con artefactos gestionados externamente | Define `OS_ARTIFACT_PATH=/path/to/objectstack.json` | -| **Cloud-connected** | Despliegues multi-inquilino / multi-app alimentados por un plano de control | Define `OS_CLOUD_URL` + `OS_CLOUD_API_KEY` | - -El modo se detecta automáticamente a partir de las variables de entorno. - -## Características de rendimiento - -| Métrica | Número | -|---|---| -| Arranque en frío (proceso activo, listo para tráfico) | ~1 segundo | -| Calentamiento por kernel (primera solicitud a un proyecto) | 50-300ms según las capacidades | -| Latencia de solicitud en caliente (CRUD vía REST) | normalmente < 10ms + latencia de base de datos | -| Huella de memoria | ~150MB base; ~10-30MB por kernel de proyecto activo | -| Proyectos concurrentes por instancia | Limitado por `OS_KERNEL_CACHE_SIZE` (32 por defecto) | - -## Por qué esta forma - -- **Un proceso de Node, sin sidecars** → cabe en un `docker run`, cabe en una - unidad systemd, cabe en un entorno tipo Lambda. -- **Kernel por proyecto, con caché LRU** → una instancia puede atender muchas - apps pequeñas sin pagar el coste de calentamiento en cada solicitud. -- **APIs generadas sobre metadatos declarados** → no hay paso de codegen - en tu CI, ni SDK de cliente que publicar; la API coincide con tu modelo de - datos por construcción. -- **Todas las capacidades son plugins opcionales** → el tamaño de la imagen - escala con lo que realmente usas. - -## A dónde ir después - -- [Production Readiness](/docs/operate/production) — checklist antes de - exponerlo a tráfico real. -- [Runtime Configuration](/docs/configure/runtime) — conexión de bases de - datos, cachés y secretos. -- [Runtime Capabilities](/docs/reference/runtime-capabilities) — - qué paquetes opcionales existen y qué habilitan. diff --git a/content/docs/architecture.fr.mdx b/content/docs/architecture.fr.mdx deleted file mode 100644 index 47bbafd..0000000 --- a/content/docs/architecture.fr.mdx +++ /dev/null @@ -1,139 +0,0 @@ ---- -title: Architecture -description: Ce que vous exécutez réellement — pour l'ingénieur qui évalue s'il faut adopter cette solution. ---- - -Une vision pratique de ce qui s'exécute sur vos machines lorsque vous déployez -ObjectOS, des données qui quittent votre réseau et de celles qui n'en sortent pas. - -Le modèle mental repose sur deux couches légères : - -1. **Métadonnées** — des packages d'objets / vues / actions / flows / - agents. Écrits pour l'essentiel par l'[AI Builder](/docs/build/ai-builder) - via une API d'outils en bac à sable ; parfois édités à la main, toujours - versionnés et audités. -2. **Un unique runtime Node.js** qui interprète ces métadonnées pour en faire une - application fonctionnelle — API REST, interface Console, permissions, jobs, outils - d'IA — le tout dans un seul processus, communiquant avec votre base de données. - -Aucune étape de génération de code, aucun pipeline de déploiement entre « l'utilisateur a décrit -ce qu'il voulait » et « c'est en ligne ». Le runtime charge à chaud les nouvelles -métadonnées après une approbation HITL. - -## Ce que vous déployez - -Un seul processus Node.js par instance ObjectOS. C'est tout. - -```text -┌─────────────────────────────────────────────────────┐ -│ ObjectOS process │ -│ ┌───────────────────────────────────────────────┐ │ -│ │ HTTP dispatcher (/ · /api · /_console …) │ │ -│ ├───────────────────────────────────────────────┤ │ -│ │ Per-project ObjectKernel (LRU cached) │ │ -│ │ ├─ Auth (Better Auth) │ │ -│ │ ├─ Security (RBAC + row-level + field) │ │ -│ │ ├─ ObjectQL (data engine, generates SQL) │ │ -│ │ ├─ REST API generator │ │ -│ │ └─ Capabilities loaded per artifact │ │ -│ │ (audit, storage, jobs, queue, AI …) │ │ -│ └───────────────────────────────────────────────┘ │ -└──────────┬──────────────────────────────────────────┘ - │ - ▼ - Your business database - (Postgres / MySQL / SQLite / Turso / MongoDB) -``` - -Cela représente la complexité d'un unique binaire lié statiquement. Aucun -sidecar, aucun Kafka, aucune couche de cache distincte requise. Ajoutez-les quand vous en -avez besoin ; ne les payez pas dès le premier jour. - -## Où résident vos données - -| Données | Résident dans | Quittent votre réseau ? | -|---|---|---| -| Enregistrements métier | Votre base de données | **Non** | -| Comptes utilisateurs, sessions, tokens OAuth | Votre base de données | **Non** | -| Journal d'audit | Votre base de données | **Non** | -| Paramètres, clés API, secrets | Votre base de données / gestionnaire de secrets | **Non** | -| Fichiers téléversés | Votre disque ou votre bucket S3/R2 | **Non** | -| La définition compilée de l'application (`objectstack.json`) | Un fichier sur disque ou récupéré depuis votre control plane | Optionnel | - -ObjectOS ne « rappelle pas la maison ». Aucune télémétrie. Aucune vérification de licence. Si vous coupez -totalement l'accès à Internet, il continue de fonctionner indéfiniment. Voir -[Air-gapped](/docs/deploy/air-gapped). - -## Comment une requête est traitée - -```text -1. Ingress / TLS termination (your load balancer) -2. HTTP dispatcher (security headers, request id) -3. Hostname → project resolution (cached, TTL configurable) -4. Get or build per-project kernel from LRU -5. AuthPlugin — session cookie, bearer token, or API key -6. SecurityPlugin — RBAC + row-level + field-level checks -7. Route handler — generated REST, declarative action, or custom -8. Data driver — ObjectQL compiles to SQL / Mongo query -9. Response with X-Request-Id propagated -``` - -Les étapes 4 à 8 s'exécutent généralement en moins de 5 ms une fois le kernel à chaud. - -## Les trois couches (utile uniquement si vous intégrez) - -La plupart des clients ne déploient que **ObjectOS**. Les deux autres couches existent si -vous voulez savoir d'où provient l'artefact : - -| Couche | Ce que c'est | Où elle s'exécute | -|---|---|---| -| **Framework** (`@objectstack/*`) | Kernel open-source, ObjectQL, plugins, drivers | npm — récupéré au moment du build | -| **Control plane** (optionnel) | Publie des artefacts `objectstack.json` compilés ; vous pouvez utiliser le service hébergé ObjectStack Cloud, exécuter le vôtre ou vous en passer entièrement | Votre CI, notre cloud ou votre ordinateur portable | -| **ObjectOS** | Le runtime que vous exploitez | **Votre infrastructure** | - -Si vous livrez une application unique, vous n'avez pas besoin d'un control plane — -compilez `objectstack.config.ts → dist/objectstack.json` dans votre CI et -livrez le JSON dans l'image. Si vous exploitez un marketplace d'applications -internes avec de nombreux tenants et applications, le control plane est l'endroit où réside le -catalogue. - -## Modes de démarrage - -| Mode | Quand | Comment | -|---|---|---| -| **Standalone** | Application unique, dev, évaluation, air-gapped, la plupart des déploiements en production | `pnpm dev` ou exécuter `dist/objectstack.json` depuis le disque | -| **File-backed** | Production avec des artefacts gérés en externe | Définir `OS_ARTIFACT_PATH=/path/to/objectstack.json` | -| **Cloud-connected** | Déploiements multi-tenant / multi-app alimentés par un control plane | Définir `OS_CLOUD_URL` + `OS_CLOUD_API_KEY` | - -Le mode est détecté automatiquement à partir des variables d'environnement. - -## Caractéristiques de performance - -| Métrique | Valeur | -|---|---| -| Démarrage à froid (processus lancé, prêt à recevoir du trafic) | ~1 seconde | -| Préchauffage par kernel (première requête vers un projet) | 50-300 ms selon les capabilities | -| Latence des requêtes à chaud (CRUD via REST) | typiquement < 10 ms + latence de la base de données | -| Empreinte mémoire | ~150 Mo de base ; ~10-30 Mo par kernel de projet actif | -| Projets concurrents par instance | Limité par `OS_KERNEL_CACHE_SIZE` (32 par défaut) | - -## Pourquoi cette forme - -- **Un seul processus Node, sans sidecars** → tient dans un `docker run`, tient dans une - unité systemd, tient dans un environnement de type Lambda. -- **Kernel par projet, mis en cache LRU** → une instance peut servir de nombreuses - petites applications sans payer le coût de préchauffage à chaque requête. -- **APIs générées au-dessus de métadonnées déclarées** → il n'y a pas d'étape de codegen - dans votre CI, pas de SDK client à publier ; l'API correspond à votre modèle de - données par construction. -- **Toutes les capabilities sont des plugins optionnels** → la taille de l'image évolue selon - ce que vous utilisez réellement. - -## Pour aller plus loin - -- [Production Readiness](/docs/operate/production) — checklist avant - d'exposer le tout à du trafic réel. -- [Runtime Configuration](/docs/configure/runtime) — câblage des bases de données, - des caches et des secrets. -- [Runtime Capabilities](/docs/reference/runtime-capabilities) — - quels packages optionnels existent et ce qu'ils activent. diff --git a/content/docs/architecture.ja.mdx b/content/docs/architecture.ja.mdx deleted file mode 100644 index a9e8912..0000000 --- a/content/docs/architecture.ja.mdx +++ /dev/null @@ -1,118 +0,0 @@ ---- -title: アーキテクチャ -description: 実際に何が動いているのか — 導入を検討しているエンジニアのために。 ---- - -ObjectOS をデプロイしたときにマシン上で何が動くのか、どのデータがネットワークの外へ出て、どのデータが出ないのかを実践的な視点で解説します。 - -メンタルモデルは、薄い 2 つのレイヤーです。 - -1. **メタデータ** — objects / views / actions / flows / - agents のパッケージ。多くは [AI Builder](/docs/build/ai-builder) - がサンドボックス化されたツール API に対して記述します。手作業で編集される場合もありますが、常にバージョン管理され監査されます。 -2. **単一の Node.js ランタイム** が、そのメタデータを解釈して動作するアプリケーション - — REST API、Console UI、権限、ジョブ、AI - ツール — に変換します。これらはすべて 1 つのプロセス内で、あなたのデータベースと通信しながら動作します。 - -コード生成のステップはなく、「ユーザーが望むものを記述した」状態と「それが稼働している」状態の間にデプロイパイプラインはありません。ランタイムは HITL の承認後に新しいメタデータをホットロードします。 - -## デプロイするもの - -ObjectOS インスタンスごとに 1 つの Node.js プロセス。それだけです。 - -```text -┌─────────────────────────────────────────────────────┐ -│ ObjectOS process │ -│ ┌───────────────────────────────────────────────┐ │ -│ │ HTTP dispatcher (/ · /api · /_console …) │ │ -│ ├───────────────────────────────────────────────┤ │ -│ │ Per-project ObjectKernel (LRU cached) │ │ -│ │ ├─ Auth (Better Auth) │ │ -│ │ ├─ Security (RBAC + row-level + field) │ │ -│ │ ├─ ObjectQL (data engine, generates SQL) │ │ -│ │ ├─ REST API generator │ │ -│ │ └─ Capabilities loaded per artifact │ │ -│ │ (audit, storage, jobs, queue, AI …) │ │ -│ └───────────────────────────────────────────────┘ │ -└──────────┬──────────────────────────────────────────┘ - │ - ▼ - Your business database - (Postgres / MySQL / SQLite / Turso / MongoDB) -``` - -複雑さの度合いは、静的リンクされた単一バイナリ程度です。サイドカーも、Kafka も、別途のキャッシュレイヤーも必要ありません。必要になったときに追加すればよく、初日からそのコストを払う必要はありません。 - -## データはどこにあるのか - -| データ | 保管場所 | ネットワークの外へ出るか？ | -|---|---|---| -| 業務レコード | あなたのデータベース | **いいえ** | -| ユーザーアカウント、セッション、OAuth トークン | あなたのデータベース | **いいえ** | -| 監査ログ | あなたのデータベース | **いいえ** | -| 設定、API キー、シークレット | あなたのデータベース / シークレットマネージャー | **いいえ** | -| アップロードされたファイル | あなたのディスク、または S3/R2 バケット | **いいえ** | -| コンパイル済みアプリ定義（`objectstack.json`） | ディスク上のファイル、またはコントロールプレーンから取得 | 任意 | - -ObjectOS はホームへ通信しません。テレメトリーもライセンスチェックもありません。インターネットアクセスを完全に遮断しても、無期限に動作し続けます。[Air-gapped](/docs/deploy/air-gapped) を参照してください。 - -## リクエストはどのように処理されるか - -```text -1. Ingress / TLS termination (your load balancer) -2. HTTP dispatcher (security headers, request id) -3. Hostname → project resolution (cached, TTL configurable) -4. Get or build per-project kernel from LRU -5. AuthPlugin — session cookie, bearer token, or API key -6. SecurityPlugin — RBAC + row-level + field-level checks -7. Route handler — generated REST, declarative action, or custom -8. Data driver — ObjectQL compiles to SQL / Mongo query -9. Response with X-Request-Id propagated -``` - -ステップ 4〜8 は、カーネルがウォームな状態であれば通常 5ms 未満で実行されます。 - -## 3 つのレイヤー（統合する場合のみ重要） - -ほとんどの顧客は **ObjectOS** のみをデプロイします。残りの 2 つのレイヤーは、アーティファクトがどこから来るのかを知りたい場合に存在します。 - -| レイヤー | 内容 | 実行される場所 | -|---|---|---| -| **Framework**（`@objectstack/*`） | オープンソースのカーネル、ObjectQL、プラグイン、ドライバー | npm — ビルド時に取り込まれる | -| **Control plane**（任意） | コンパイル済み `objectstack.json` アーティファクトを公開する。ホスティングされた ObjectStack Cloud を利用するか、自前で運用するか、まったく使わないかを選べる | あなたの CI、当社のクラウド、またはあなたのノート PC | -| **ObjectOS** | あなたが運用するランタイム | **あなたのインフラ** | - -単一のアプリを出荷するだけなら、コントロールプレーンは不要です。CI で `objectstack.config.ts → dist/objectstack.json` をコンパイルし、その JSON をイメージに含めて出荷します。多数のテナントやアプリを抱える社内アプリ marketplace を運用する場合は、コントロールプレーンがカタログの置き場所になります。 - -## ブートモード - -| モード | 利用シーン | 方法 | -|---|---|---| -| **Standalone** | 単一アプリ、開発、評価、エアギャップ環境、ほとんどの本番デプロイ | `pnpm dev`、またはディスク上の `dist/objectstack.json` を実行 | -| **File-backed** | 外部管理のアーティファクトを使う本番環境 | `OS_ARTIFACT_PATH=/path/to/objectstack.json` を設定 | -| **Cloud-connected** | コントロールプレーンから供給されるマルチテナント / マルチアプリのデプロイ | `OS_CLOUD_URL` + `OS_CLOUD_API_KEY` を設定 | - -モードは環境変数から自動検出されます。 - -## パフォーマンス特性 - -| 指標 | 数値 | -|---|---| -| コールドスタート（プロセス起動からトラフィック受付可能まで） | 約 1 秒 | -| カーネルごとのウォームアップ（プロジェクトへの最初のリクエスト） | capabilities に応じて 50〜300ms | -| ウォームリクエストのレイテンシ（REST 経由の CRUD） | 通常 10ms 未満 + データベースのレイテンシ | -| メモリフットプリント | ベース約 150MB、アクティブなプロジェクトカーネルごとに約 10〜30MB | -| インスタンスあたりの同時プロジェクト数 | `OS_KERNEL_CACHE_SIZE`（デフォルト 32）によって制限される | - -## なぜこの形なのか - -- **サイドカーなしの単一 Node プロセス** → `docker run` に収まり、systemd ユニットに収まり、Lambda のような環境に収まる。 -- **プロジェクトごとのカーネル、LRU キャッシュ** → 1 つのインスタンスで多数の小さなアプリを、リクエストごとにウォームアップコストを払うことなく処理できる。 -- **宣言されたメタデータの上に生成される API** → CI にコード生成のステップはなく、公開すべきクライアント SDK もない。API は構造的にあなたのデータモデルと一致する。 -- **すべての capabilities は任意のプラグイン** → イメージサイズは実際に使うものに応じてスケールする。 - -## 次に読むもの - -- [Production Readiness](/docs/operate/production) — 実トラフィックにさらす前のチェックリスト。 -- [Runtime Configuration](/docs/configure/runtime) — データベース、キャッシュ、シークレットの接続。 -- [Runtime Capabilities](/docs/reference/runtime-capabilities) — どの任意パッケージが存在し、何を有効にするか。 diff --git a/content/docs/architecture.ko.mdx b/content/docs/architecture.ko.mdx deleted file mode 100644 index d9f70b2..0000000 --- a/content/docs/architecture.ko.mdx +++ /dev/null @@ -1,137 +0,0 @@ ---- -title: 아키텍처 -description: 실제로 무엇이 실행되는가 — 이 제품을 도입할지 평가하는 엔지니어를 위한 안내. ---- - -ObjectOS를 배포할 때 여러분의 머신에서 무엇이 실행되는지, 어떤 데이터가 -네트워크 밖으로 나가고 어떤 데이터가 나가지 않는지에 대한 실용적인 관점입니다. - -핵심 개념은 두 개의 얇은 계층입니다. - -1. **메타데이터** — 객체 / 뷰 / 액션 / 플로우 / 에이전트의 패키지입니다. - 대부분은 샌드박스화된 도구 API를 대상으로 [AI Builder](/docs/build/ai-builder)가 - 작성하며, 때때로 직접 편집되기도 하지만 항상 버전 관리되고 감사됩니다. -2. **단일 Node.js 런타임** — 이 메타데이터를 동작하는 애플리케이션으로 - 해석합니다. REST API, Console UI, 권한, 작업, AI 도구가 모두 하나의 - 프로세스 안에서 여러분의 데이터베이스와 통신합니다. - -코드 생성 단계도, "사용자가 원하는 것을 설명함"과 "그것이 라이브로 동작함" -사이의 배포 파이프라인도 없습니다. 런타임은 HITL 승인 이후 새 메타데이터를 -핫 로드합니다. - -## 무엇을 배포하는가 - -ObjectOS 인스턴스당 하나의 Node.js 프로세스. 그것이 전부입니다. - -```text -┌─────────────────────────────────────────────────────┐ -│ ObjectOS process │ -│ ┌───────────────────────────────────────────────┐ │ -│ │ HTTP dispatcher (/ · /api · /_console …) │ │ -│ ├───────────────────────────────────────────────┤ │ -│ │ Per-project ObjectKernel (LRU cached) │ │ -│ │ ├─ Auth (Better Auth) │ │ -│ │ ├─ Security (RBAC + row-level + field) │ │ -│ │ ├─ ObjectQL (data engine, generates SQL) │ │ -│ │ ├─ REST API generator │ │ -│ │ └─ Capabilities loaded per artifact │ │ -│ │ (audit, storage, jobs, queue, AI …) │ │ -│ └───────────────────────────────────────────────┘ │ -└──────────┬──────────────────────────────────────────┘ - │ - ▼ - Your business database - (Postgres / MySQL / SQLite / Turso / MongoDB) -``` - -정적으로 링크된 단일 바이너리 수준의 복잡도입니다. 사이드카도, Kafka도, -별도의 캐시 계층도 필요하지 않습니다. 필요할 때 추가하세요. 첫날부터 그 -비용을 치를 필요는 없습니다. - -## 데이터는 어디에 있는가 - -| 데이터 | 저장 위치 | 네트워크 밖으로 나가는가? | -|---|---|---| -| 비즈니스 레코드 | 여러분의 데이터베이스 | **아니오** | -| 사용자 계정, 세션, OAuth 토큰 | 여러분의 데이터베이스 | **아니오** | -| 감사 로그 | 여러분의 데이터베이스 | **아니오** | -| 설정, API 키, 시크릿 | 여러분의 데이터베이스 / 시크릿 매니저 | **아니오** | -| 업로드된 파일 | 여러분의 디스크 또는 S3/R2 버킷 | **아니오** | -| 컴파일된 앱 정의(`objectstack.json`) | 디스크의 파일 또는 컨트롤 플레인에서 가져옴 | 선택적 | - -ObjectOS는 외부로 연결을 시도하지 않습니다. 텔레메트리도, 라이선스 검사도 -없습니다. 인터넷 접속을 완전히 차단해도 무기한 계속 실행됩니다. -[에어갭](/docs/deploy/air-gapped)을 참고하세요. - -## 요청이 처리되는 방식 - -```text -1. Ingress / TLS termination (your load balancer) -2. HTTP dispatcher (security headers, request id) -3. Hostname → project resolution (cached, TTL configurable) -4. Get or build per-project kernel from LRU -5. AuthPlugin — session cookie, bearer token, or API key -6. SecurityPlugin — RBAC + row-level + field-level checks -7. Route handler — generated REST, declarative action, or custom -8. Data driver — ObjectQL compiles to SQL / Mongo query -9. Response with X-Request-Id propagated -``` - -커널이 워밍업된 상태에서는 4~8단계가 일반적으로 5ms 미만으로 실행됩니다. - -## 세 개의 계층 (통합할 때만 중요함) - -대부분의 고객은 **ObjectOS**만 배포합니다. 나머지 두 계층은 아티팩트가 -어디에서 오는지 알고 싶을 때를 위해 존재합니다. - -| 계층 | 무엇인가 | 어디에서 실행되는가 | -|---|---|---| -| **Framework**(`@objectstack/*`) | 오픈소스 커널, ObjectQL, 플러그인, 드라이버 | npm — 빌드 시점에 포함됨 | -| **Control plane**(선택적) | 컴파일된 `objectstack.json` 아티팩트를 게시함. 호스팅되는 ObjectStack Cloud를 사용하거나, 직접 운영하거나, 완전히 생략할 수 있음 | 여러분의 CI, 우리 클라우드, 또는 여러분의 노트북 | -| **ObjectOS** | 여러분이 운영하는 런타임 | **여러분의 인프라** | - -단일 앱을 출시한다면 컨트롤 플레인이 필요하지 않습니다. CI에서 -`objectstack.config.ts → dist/objectstack.json`을 컴파일하고 그 JSON을 -이미지에 담아 출시하세요. 다수의 테넌트와 앱을 가진 내부 앱 마켓플레이스를 -운영한다면, 컨트롤 플레인이 카탈로그가 머무는 곳입니다. - -## 부팅 모드 - -| 모드 | 언제 | 어떻게 | -|---|---|---| -| **Standalone** | 단일 앱, 개발, 평가, 에어갭, 대부분의 프로덕션 배포 | `pnpm dev` 또는 디스크에서 `dist/objectstack.json` 실행 | -| **File-backed** | 외부에서 관리되는 아티팩트를 사용하는 프로덕션 | `OS_ARTIFACT_PATH=/path/to/objectstack.json` 설정 | -| **Cloud-connected** | 컨트롤 플레인이 공급하는 멀티 테넌트 / 멀티 앱 배포 | `OS_CLOUD_URL` + `OS_CLOUD_API_KEY` 설정 | - -모드는 환경 변수로부터 자동 감지됩니다. - -## 성능 특성 - -| 지표 | 수치 | -|---|---| -| 콜드 스타트(프로세스 기동, 트래픽 수신 준비) | 약 1초 | -| 커널당 워밍업(프로젝트로의 첫 요청) | 기능에 따라 50~300ms | -| 워밍업된 요청 지연(REST를 통한 CRUD) | 일반적으로 10ms 미만 + 데이터베이스 지연 | -| 메모리 사용량 | 기본 약 150MB, 활성 프로젝트 커널당 약 10~30MB | -| 인스턴스당 동시 프로젝트 수 | `OS_KERNEL_CACHE_SIZE`로 제한됨(기본값 32) | - -## 왜 이런 형태인가 - -- **사이드카 없는 단일 Node 프로세스** → `docker run`에 들어맞고, systemd - 유닛에 들어맞고, Lambda 같은 환경에 들어맞습니다. -- **프로젝트당 커널, LRU 캐시** → 하나의 인스턴스가 매 요청마다 워밍업 - 비용을 치르지 않고도 많은 소규모 앱을 처리할 수 있습니다. -- **선언된 메타데이터 위에 생성되는 API** → CI에 코드 생성 단계가 없고, - 게시할 클라이언트 SDK도 없습니다. API는 구조적으로 여러분의 데이터 - 모델과 일치합니다. -- **모든 기능은 선택적 플러그인** → 이미지 크기가 실제로 사용하는 것에 - 맞춰 조정됩니다. - -## 다음으로 갈 곳 - -- [프로덕션 준비성](/docs/operate/production) — 실제 트래픽에 노출하기 전의 - 체크리스트. -- [런타임 구성](/docs/configure/runtime) — 데이터베이스, 캐시, 시크릿 - 연결하기. -- [런타임 기능](/docs/reference/runtime-capabilities) — 어떤 선택적 - 패키지가 존재하고 무엇을 활성화하는지. diff --git a/content/docs/architecture.mdx b/content/docs/architecture.mdx index f47bb1a..8c5bdb6 100644 --- a/content/docs/architecture.mdx +++ b/content/docs/architecture.mdx @@ -99,13 +99,24 @@ catalog lives. ## Boot modes -| Mode | When | How | +Where the running app comes from is one decision, and the deployment declares +it. The shipped default needs no configuration; each of the other modes is +selected by naming a published artifact, and the +[Environment Variables](/docs/reference/environment-variables) reference +carries the exact contract for each. + +| Mode | When | How the app arrives | |---|---|---| -| **Standalone** | Single app, dev, evaluation, air-gapped, most production deployments | `pnpm dev` or run `dist/objectstack.json` from disk | -| **File-backed** | Production with externally-managed artifacts | Set `OS_ARTIFACT_PATH=/path/to/objectstack.json` | -| **Cloud-connected** | Multi-tenant / multi-app deployments fed by a control plane | Set `OS_CLOUD_URL` + `OS_CLOUD_API_KEY` | +| **Config-authored** | The shipped shape. Single app, evaluation, air-gapped, most production deployments | The runtime boots the metadata authored in the image, plus anything installed into it | +| **Artifact-pinned** | The app is released on its own cadence, separately from the runtime image | One variable names a published artifact by URL, with an optional integrity pin. Upgrading the app is a change to that variable plus a restart | +| **Composed** | Several organizations behind the isolation wall, sharing one database, running a published app | The same artifact reference, consumed from the deployment's own configuration so the enterprise plugins load alongside it. Air-gap licensed only | -Mode is auto-detected from environment variables. +Whether the deployment also talks to a **control plane** is a separate +decision, made by the cloud-posture variable — a connected deployment can be +any of the modes above. A self-hosted runtime authenticates to a control plane +with a token minted when the deployment was **bound** to it, not with a key +pasted into a file, and pairing the wrong licence mode with the wrong cloud +posture is [refused at startup](/docs/deploy/air-gapped). ## Performance characteristics @@ -115,7 +126,7 @@ Mode is auto-detected from environment variables. | Per-kernel warmup (first request to a project) | 50-300ms depending on capabilities | | Warm request latency (CRUD via REST) | typically < 10ms + database latency | | Memory footprint | ~150MB base; ~10-30MB per active project kernel | -| Concurrent projects per instance | Limited by `OS_KERNEL_CACHE_SIZE` (default 32) | +| Concurrent app kernels per instance | Bounded by the runtime's kernel cache | ## Why this shape diff --git a/content/docs/architecture.zh-Hans.mdx b/content/docs/architecture.zh-Hans.mdx deleted file mode 100644 index aee723d..0000000 --- a/content/docs/architecture.zh-Hans.mdx +++ /dev/null @@ -1,114 +0,0 @@ ---- -title: 架构 -description: 你实际运行的是什么 —— 写给评估是否引入它的工程师。 ---- - -一个实用视角，帮你看清部署 ObjectOS 后你的机器上跑了什么、什么数据离开了你的网络、什么数据没有。 - -心智模型是两层薄薄的东西： - -1. **元数据** —— 对象 / 视图 / Action / 流程 / Agent 的打包。大部分由 [AI Builder](/docs/build/ai-builder) 通过沙箱工具 API 编写；偶尔人工编辑，始终版本化并被审计。 -2. **单一 Node.js 运行时**，将元数据解释为一个可工作的应用 —— REST API、Console UI、权限、任务、AI 工具 —— 全部在同一个进程内，与你的数据库对话。 - -没有代码生成步骤，没有从 "用户描述需求" 到 "已上线" 之间的部署流水线。运行时在 HITL 审批后热加载新元数据。 - -## 你部署的是什么 - -每个 ObjectOS 实例对应一个 Node.js 进程。就这些。 - -```text -┌─────────────────────────────────────────────────────┐ -│ ObjectOS 进程 │ -│ ┌───────────────────────────────────────────────┐ │ -│ │ HTTP 分发器 (/ · /api · /_console …) │ │ -│ ├───────────────────────────────────────────────┤ │ -│ │ 每项目 ObjectKernel（LRU 缓存） │ │ -│ │ ├─ Auth (Better Auth) │ │ -│ │ ├─ Security（RBAC + 行级 + 字段级） │ │ -│ │ ├─ ObjectQL（数据引擎，生成 SQL） │ │ -│ │ ├─ REST API 生成器 │ │ -│ │ └─ 按产物加载的能力 │ │ -│ │ （审计、存储、任务、队列、AI……） │ │ -│ └───────────────────────────────────────────────┘ │ -└──────────┬──────────────────────────────────────────┘ - │ - ▼ - 你的业务数据库 - (Postgres / MySQL / SQLite / Turso / MongoDB) -``` - -复杂度相当于一个静态链接的二进制。没有 sidecar、没有 Kafka、不需要独立缓存层。需要时再加；第一天别为它们付费。 - -## 你的数据存放在哪里 - -| 数据 | 存放在 | 是否离开你的网络？ | -|---|---|---| -| 业务记录 | 你的数据库 | **否** | -| 用户账号、会话、OAuth Token | 你的数据库 | **否** | -| 审计日志 | 你的数据库 | **否** | -| 设置、API Key、密钥 | 你的数据库 / 密钥管理器 | **否** | -| 上传的文件 | 你的磁盘或 S3/R2 桶 | **否** | -| 编译后的应用定义（`objectstack.json`） | 磁盘上的一个文件，或从你的控制面拉取 | 可选 | - -ObjectOS 不会回拨电话。无遥测。无授权检查。如果你完全切断互联网，它会持续运行。参见 [Air-gapped](/docs/deploy/air-gapped)。 - -## 一个请求如何被服务 - -```text -1. 入口 / TLS 终结 （你的负载均衡器） -2. HTTP 分发器 （安全头、请求 ID） -3. 主机名 → 项目解析 （带缓存，TTL 可配） -4. 从 LRU 中获取或构建对应项目的内核 -5. AuthPlugin —— 会话 Cookie、Bearer Token 或 API Key -6. SecurityPlugin —— RBAC + 行级 + 字段级检查 -7. 路由处理 —— 自动生成的 REST、声明式 Action 或自定义 -8. 数据驱动 —— ObjectQL 编译为 SQL / Mongo 查询 -9. 响应携带 X-Request-Id -``` - -内核热起来后，步骤 4-8 通常在 5ms 内执行完。 - -## 三个层级（只在你做集成时才重要） - -大多数客户只部署 **ObjectOS**。如果你想知道产物从哪里来，另外两层就在这里： - -| 层级 | 是什么 | 运行在哪 | -|---|---|---| -| **框架** (`@objectstack/*`) | 开源内核、ObjectQL、插件、驱动 | npm —— 构建时引入 | -| **控制面**（可选） | 发布编译后的 `objectstack.json` 产物；可使用托管的 ObjectStack Cloud、自建，或完全不要 | 你的 CI、我们的云，或你的笔记本 | -| **ObjectOS** | 你运维的运行时 | **你的基础设施** | - -如果你只发布单个应用，根本不需要控制面 —— 在 CI 里把 `objectstack.config.ts → dist/objectstack.json` 编译出来打进镜像即可。如果你要运营一个面向多租户多应用的内部应用市场，目录就放在控制面。 - -## 启动模式 - -| 模式 | 何时 | 如何 | -|---|---|---| -| **Standalone** | 单应用、开发、评估、气隙、大多数生产部署 | `pnpm dev` 或从磁盘运行 `dist/objectstack.json` | -| **File-backed** | 由外部管理产物的生产环境 | 设置 `OS_ARTIFACT_FILE=/path/to/objectstack.json` | -| **Cloud-connected** | 由控制面驱动的多租户/多应用部署 | 设置 `OS_CLOUD_URL` + `OS_CLOUD_API_KEY` | - -模式由环境变量自动检测。 - -## 性能特征 - -| 指标 | 数值 | -|---|---| -| 冷启动（进程起来、可接流量） | ~1 秒 | -| 每个内核预热（首次请求该项目） | 50-300ms，视能力而定 | -| 热请求延迟（REST 走 CRUD） | 通常 < 10ms + 数据库延迟 | -| 内存占用 | 基础 ~150MB；每个活跃项目内核 ~10-30MB | -| 单实例并发项目数 | 受 `OS_KERNEL_CACHE_SIZE` 限制（默认 32） | - -## 为什么是这种形态 - -- **一个 Node 进程，无 sidecar** → 适合 `docker run`、适合 systemd 单元、适合 Lambda 类环境。 -- **每项目内核，LRU 缓存** → 一个实例可以服务多个小应用，且不必为每次请求付预热成本。 -- **基于声明元数据生成 API** → CI 中没有 codegen 步骤，无需发布客户端 SDK；API 按构造与你的数据模型一致。 -- **所有能力都是可选插件** → 镜像大小随你实际用到的部分而扩张。 - -## 下一步 - -- [Production Readiness](/docs/operate/production) —— 上真实流量前的清单。 -- [Runtime Configuration](/docs/configure/runtime) —— 数据库、缓存、密钥接线。 -- [Runtime Capabilities](/docs/reference/runtime-capabilities) —— 有哪些可选包以及它们启用什么。 diff --git a/content/docs/build/packages.de.mdx b/content/docs/build/packages.de.mdx deleted file mode 100644 index f79d5b6..0000000 --- a/content/docs/build/packages.de.mdx +++ /dev/null @@ -1,169 +0,0 @@ ---- -title: Pakete -description: Die Organisationseinheit in ObjectOS — versioniert, installierbar, teilbar. ---- - -Alles, was Sie in ObjectOS erstellen, lebt in einem **Paket**: einem -versionierten, in sich geschlossenen Bündel von Metadaten. Pakete sind die -Einheit, an der der AI Builder arbeitet, die Einheit, die der marketplace -ausliefert, und die Einheit, gegen die ObjectOS Updates verfolgt. - -## Was in einem Paket steckt - -```text -com.acme.crm@1.2.0 -├── manifest id, version, namespace, dependencies -├── objects/ *.object.ts, *.state.ts, *.hook.ts -├── views/ *.view.ts, *.page.ts, *.form.ts -├── actions/ *.action.ts -├── flows/ *.flow.ts, *.approval.ts -├── agents/ *.agent.ts, *.skill.ts -├── permissions/ *.permission.ts -├── sharing/ *.sharing.ts -├── translations/ en.ts, zh-CN.ts, ... -├── apps/ *.app.ts (navigation) -└── data/ defineDataset(...) seed -``` - -Jedes Metadaten-Artefakt (Objekt, Aktion, Flow, …) gehört zu genau einem -Paket. Die Paket-id ist **reverse-DNS** (`com.acme.crm`, -`org.mycompany.helpdesk`), und das Namespace-Präfix (`crm_`, `hd_`) verhindert, -dass Tabellen- / Objektnamen über mehrere im selben Tenant installierte Pakete -hinweg kollidieren. - -## Ein Paket erstellen - -### Über den AI Builder - -> *"Starte ein neues Paket für unser internes CRM, namespace `crm`."* - -Die KI ruft `create_package` und `set_active_package` auf. Von da an landet -jedes Objekt / Feld / jede Aktion, die Sie beschreiben, in `crm`. - -### Über die CLI - -```bash -os init my-crm -t app -cd my-crm -# manifest lives in the `manifest:` block of ./objectstack.config.ts -pnpm dev -``` - -### Über die Console - -**Console → Packages → New Package** — Name, id, Version, namespace. - -## Aktives Paket - -Im AI Builder trägt eine Konversation ein **aktives Paket** — den Standard- -Container für neue Metadaten. Die KI setzt es mit dem Tool -`set_active_package`, wenn Sie etwas sagen wie *"Wechsle zu -`com.acme.helpdesk`."* Über die CLI ist das aktive Paket einfach dasjenige, -das in der `objectstack.config.ts` des Projekts deklariert ist (der -`manifest:`-Block). - -## Versionierung - -Pakete verwenden **semver**. Dieselben Regeln wie die Runtime — siehe -[Changelog & Versioning](/docs/resources/changelog). - -Das Anheben einer Version ändert nichts, bis Sie veröffentlichen. Die Runtime -verfolgt `installed_version` pro Tenant pro Paket, und der marketplace zeigt -ein *"Update available"*-Badge an, wenn der Katalog eine neuere Version hat. - -## Abhängigkeiten - -Pakete können von anderen Paketen abhängen: - -```json -{ - "id": "com.acme.helpdesk", - "version": "0.3.0", - "dependencies": { - "com.acme.crm": "^1.0.0", - "sys.feeds": "*" - } -} -``` - -Die Runtime löst Abhängigkeiten bei der Installation auf. Wenn -`com.acme.crm` nicht installiert ist, schlägt die Helpdesk-Installation mit -einem klaren Fehler fehl. - -Systempakete (`sys.*`) sind immer vorhanden — feeds, attachments, audit, -identity usw. - -## Veröffentlichen - -```bash -os compile # → dist/objectstack.json -os package publish # → ObjectStack cloud catalog -``` - -`os package publish` lädt das kompilierte manifest in die Cloud-Control-Plane -hoch, die durch `OS_CLOUD_URL` konfiguriert und mit `OS_CLOUD_API_KEY` -authentifiziert wird. Für private / luftgekapselte Distribution überspringen -Sie das Veröffentlichen und übergeben das kompilierte `dist/objectstack.json` -direkt an die Zielinstallation (siehe Installieren weiter unten). Siehe -[Marketplace](/docs/build/marketplace). - -## Installieren - -| Pfad | Wie | -|---|---| -| Console | Marketplace-Tab → Paket auswählen → Install | -| REST | `POST /api/v1/marketplace/install-local` (Body: `{ packageId, versionId? }`) | -| Luftgekapselt | Das kompilierte `dist/objectstack.json`-Artefakt einhängen (siehe [Air-gapped](/docs/deploy/air-gapped)) | - -Die Installation führt die Metadaten des Pakets in den laufenden Kernel -zusammen, registriert seine Objekte bei ObjectQL und sät bei der ersten -Installation initiale Daten — kein Neustart nötig. Zwischengespeicherte -Installationen werden beim nächsten Boot erneut registriert und überstehen so -Prozess-Neustarts. - -## Deinstallieren - -Beim Deinstallieren wird das zwischengespeicherte manifest des Pakets -entfernt, sodass es beim nächsten Boot nicht mehr erneut registriert wird. Da -die Objektregistrierung additiv ist, ist ein **Kernel-Neustart** erforderlich, -um die Objekte eines bereits laufenden Pakets vollständig zu entladen. Daten -werden standardmäßig **behalten**, sodass Sie erneut installieren und -fortfahren können. - -## Paketübergreifende Konventionen - -Um Kollisionen zu vermeiden, wenn viele Pakete koexistieren: - -| Artefakt | Konvention | -|---|---| -| Objektnamen | Immer mit Präfix: `crm_account`, `hd_ticket` | -| Aktionsnamen | Mit Präfix: `crm_assign_owner`, `hd_close_ticket` | -| Flow-Namen | Mit Präfix: `hd_overdue_alert` | -| Übersetzungsschlüssel | Unter dem namespace eingeordnet: `crm.account.label` | -| Seed-`externalId` | `:`, z. B. `crm:demo-account-1` | -| Systemnamen | Reserviert: `sys_*` (niemals in benutzerdefinierten Paketen verwenden) | - -Sowohl die CLI als auch der AI Builder erzwingen dies bei der Erstellung. - -## Systempakete - -Die Runtime liefert eine kleine Reihe stets vorhandener Pakete mit, die -polymorphe Dienste bereitstellen: - -| Paket | Stellt bereit | -|---|---| -| `sys.identity` | `sys_user`, `sys_organization`, `sys_member`, Sessions, API-Keys | -| `sys.feeds` | `sys_comment`, `sys_activity`, `sys_attachment` | -| `sys.audit` | `sys_audit_log` | -| `sys.files` | `sys_file` | -| `sys.ai` | `ai_conversations`, `ai_pending_actions` | -| `sys.settings` | `sys_setting` | - -Sie aktivieren sie über `enable: { feeds: true, trackHistory: true, … }` an -Ihren Objekten — siehe [Data Model](/docs/build/data). - -## Wie es weitergeht - -- [Marketplace](/docs/build/marketplace) — Pakete an andere Tenants verteilen -- [Data Model](/docs/build/data) — was in ein Paket gehört -- [`os package` commands](/docs/reference/cli) — vollständige CLI-Referenz diff --git a/content/docs/build/packages.es.mdx b/content/docs/build/packages.es.mdx deleted file mode 100644 index bb8c550..0000000 --- a/content/docs/build/packages.es.mdx +++ /dev/null @@ -1,171 +0,0 @@ ---- -title: Paquetes -description: "La unidad de organización en ObjectOS: versionada, instalable y compartible." ---- - -Todo lo que construyes en ObjectOS reside en un **paquete**: un conjunto -de metadatos versionado y autocontenido. Los paquetes son la unidad -sobre la que trabaja el AI Builder, la unidad que distribuye el -marketplace y la unidad respecto a la que ObjectOS rastrea las -actualizaciones. - -## Qué contiene un paquete - -```text -com.acme.crm@1.2.0 -├── manifest id, version, namespace, dependencies -├── objects/ *.object.ts, *.state.ts, *.hook.ts -├── views/ *.view.ts, *.page.ts, *.form.ts -├── actions/ *.action.ts -├── flows/ *.flow.ts, *.approval.ts -├── agents/ *.agent.ts, *.skill.ts -├── permissions/ *.permission.ts -├── sharing/ *.sharing.ts -├── translations/ en.ts, zh-CN.ts, ... -├── apps/ *.app.ts (navigation) -└── data/ defineDataset(...) seed -``` - -Cada artefacto de metadatos (objeto, acción, flujo, …) pertenece a -exactamente un paquete. El id del paquete sigue el formato **DNS -inverso** (`com.acme.crm`, `org.mycompany.helpdesk`) y el prefijo del -namespace (`crm_`, `hd_`) evita que los nombres de tablas / objetos -colisionen entre paquetes instalados en el mismo tenant. - -## Crear un paquete - -### Desde el AI Builder - -> *"Inicia un nuevo paquete para nuestro CRM interno, con el namespace `crm`."* - -La IA invoca `create_package` y `set_active_package`. A partir de ese -momento, cada objeto / campo / acción que describas se ubica en `crm`. - -### Desde la CLI - -```bash -os init my-crm -t app -cd my-crm -# manifest lives in the `manifest:` block of ./objectstack.config.ts -pnpm dev -``` - -### Desde Console - -**Console → Packages → New Package** — nombre, id, versión, namespace. - -## Paquete activo - -En el AI Builder, una conversación lleva asociado un **paquete activo**: -el contenedor predeterminado para los nuevos metadatos. La IA lo -establece con la herramienta `set_active_package` cuando dices algo como -*"Cambia a `com.acme.helpdesk`."* Desde la CLI, el paquete activo es -simplemente el declarado en el `objectstack.config.ts` del proyecto (el -bloque `manifest:`). - -## Versionado - -Los paquetes usan **semver**. Las mismas reglas que el runtime — consulta -[Changelog & Versioning](/docs/resources/changelog). - -Incrementar una versión no cambia nada hasta que publicas. El runtime -rastrea `installed_version` por tenant y por paquete, y el marketplace -muestra una insignia de *"Update available"* cuando el catálogo tiene una -versión más reciente. - -## Dependencias - -Los paquetes pueden depender de otros paquetes: - -```json -{ - "id": "com.acme.helpdesk", - "version": "0.3.0", - "dependencies": { - "com.acme.crm": "^1.0.0", - "sys.feeds": "*" - } -} -``` - -El runtime resuelve las dependencias durante la instalación. Si -`com.acme.crm` no está instalado, la instalación del helpdesk falla con -un error claro. - -Los paquetes de sistema (`sys.*`) siempre están presentes — feeds, -adjuntos, auditoría, identidad, etc. - -## Publicar - -```bash -os compile # → dist/objectstack.json -os package publish # → ObjectStack cloud catalog -``` - -`os package publish` sube el manifiesto compilado al plano de control en -la nube configurado por `OS_CLOUD_URL`, autenticado con -`OS_CLOUD_API_KEY`. Para distribución privada / sin conexión (air-gapped), -omite la publicación y entrega el `dist/objectstack.json` compilado -directamente a la instalación de destino (consulta Instalación más -abajo). Consulta [Marketplace](/docs/build/marketplace). - -## Instalar - -| Ruta | Cómo | -|---|---| -| Console | Pestaña Marketplace → elige el paquete → Install | -| REST | `POST /api/v1/marketplace/install-local` (body: `{ packageId, versionId? }`) | -| Air-gapped | Monta el artefacto compilado `dist/objectstack.json` (consulta [Air-gapped](/docs/deploy/air-gapped)) | - -La instalación fusiona los metadatos del paquete en el kernel en vivo, -registra sus objetos con ObjectQL y carga los datos iniciales en la -primera instalación — sin necesidad de reiniciar. Las instalaciones en -caché se vuelven a registrar en el siguiente arranque, por lo que -sobreviven a los reinicios del proceso. - -## Desinstalar - -Desinstalar elimina el manifiesto en caché del paquete para que ya no se -vuelva a registrar en el siguiente arranque. Como el registro de objetos -es aditivo, se requiere un **reinicio del kernel** para descargar por -completo los objetos de un paquete ya en ejecución. Los datos se -**conservan** de forma predeterminada, por lo que puedes reinstalar y -continuar. - -## Convenciones entre paquetes - -Para evitar colisiones cuando coexisten muchos paquetes: - -| Artefacto | Convención | -|---|---| -| Nombres de objetos | Siempre con prefijo: `crm_account`, `hd_ticket` | -| Nombres de acciones | Con prefijo: `crm_assign_owner`, `hd_close_ticket` | -| Nombres de flujos | Con prefijo: `hd_overdue_alert` | -| Claves de traducción | Acotadas bajo el namespace: `crm.account.label` | -| `externalId` de seed | `:`, p. ej. `crm:demo-account-1` | -| Nombres de sistema | Reservados: `sys_*` (nunca los uses en paquetes personalizados) | - -Tanto la CLI como el AI Builder aplican esto al momento de la creación. - -## Paquetes de sistema - -El runtime incluye un pequeño conjunto de paquetes siempre presentes que -proporcionan servicios polimórficos: - -| Paquete | Proporciona | -|---|---| -| `sys.identity` | `sys_user`, `sys_organization`, `sys_member`, sesiones, claves de API | -| `sys.feeds` | `sys_comment`, `sys_activity`, `sys_attachment` | -| `sys.audit` | `sys_audit_log` | -| `sys.files` | `sys_file` | -| `sys.ai` | `ai_conversations`, `ai_pending_actions` | -| `sys.settings` | `sys_setting` | - -Los habilitas mediante `enable: { feeds: true, trackHistory: true, … }` -en tus objetos — consulta [Data Model](/docs/build/data). - -## A dónde ir después - -- [Marketplace](/docs/build/marketplace) — distribuye paquetes a otros tenants -- [Data Model](/docs/build/data) — qué va dentro de un paquete -- [`os package` commands](/docs/reference/cli) — referencia completa de la CLI diff --git a/content/docs/build/packages.fr.mdx b/content/docs/build/packages.fr.mdx deleted file mode 100644 index 90ca692..0000000 --- a/content/docs/build/packages.fr.mdx +++ /dev/null @@ -1,169 +0,0 @@ ---- -title: Packages -description: L'unité d'organisation dans ObjectOS — versionnée, installable, partageable. ---- - -Tout ce que vous construisez dans ObjectOS réside dans un **package** : -un ensemble de métadonnées autonome et versionné. Le package est l'unité -sur laquelle travaille l'AI Builder, l'unité que distribue le marketplace, -et l'unité dont ObjectOS suit les mises à jour. - -## Contenu d'un package - -```text -com.acme.crm@1.2.0 -├── manifest id, version, namespace, dependencies -├── objects/ *.object.ts, *.state.ts, *.hook.ts -├── views/ *.view.ts, *.page.ts, *.form.ts -├── actions/ *.action.ts -├── flows/ *.flow.ts, *.approval.ts -├── agents/ *.agent.ts, *.skill.ts -├── permissions/ *.permission.ts -├── sharing/ *.sharing.ts -├── translations/ en.ts, zh-CN.ts, ... -├── apps/ *.app.ts (navigation) -└── data/ defineDataset(...) seed -``` - -Chaque artefact de métadonnées (object, action, flow, …) appartient à -exactement un package. L'id du package est en **reverse-DNS** (`com.acme.crm`, -`org.mycompany.helpdesk`) et le préfixe de namespace (`crm_`, `hd_`) -empêche les noms de tables / d'objets d'entrer en collision entre les -packages installés dans le même tenant. - -## Créer un package - -### Depuis l'AI Builder - -> *« Démarre un nouveau package pour notre CRM interne, namespace `crm`. »* - -L'IA appelle `create_package` et `set_active_package`. À partir de là, -chaque object / champ / action que vous décrivez est placé dans `crm`. - -### Depuis la CLI - -```bash -os init my-crm -t app -cd my-crm -# manifest lives in the `manifest:` block of ./objectstack.config.ts -pnpm dev -``` - -### Depuis la Console - -**Console → Packages → New Package** — nom, id, version, namespace. - -## Package actif - -Dans l'AI Builder, une conversation porte un **package actif** — le -conteneur par défaut pour les nouvelles métadonnées. L'IA le définit avec -l'outil `set_active_package` lorsque vous dites par exemple *« Bascule vers -`com.acme.helpdesk`. »* Depuis la CLI, le package actif est simplement -celui déclaré dans le fichier `objectstack.config.ts` du projet (le bloc -`manifest:`). - -## Versionnement - -Les packages utilisent le **semver**. Mêmes règles que le runtime — voir -[Changelog & Versioning](/docs/resources/changelog). - -Incrémenter une version ne change rien tant que vous ne publiez pas. Le -runtime suit `installed_version` par tenant et par package, et le -marketplace affiche un badge *« Update available »* lorsque le catalogue -contient une version plus récente. - -## Dépendances - -Les packages peuvent dépendre d'autres packages : - -```json -{ - "id": "com.acme.helpdesk", - "version": "0.3.0", - "dependencies": { - "com.acme.crm": "^1.0.0", - "sys.feeds": "*" - } -} -``` - -Le runtime résout les dépendances à l'installation. Si `com.acme.crm` -n'est pas installé, l'installation du helpdesk échoue avec une erreur -explicite. - -Les packages système (`sys.*`) sont toujours présents — feeds, pièces -jointes, audit, identité, etc. - -## Publication - -```bash -os compile # → dist/objectstack.json -os package publish # → ObjectStack cloud catalog -``` - -`os package publish` téléverse le manifeste compilé vers le plan de -contrôle cloud configuré par `OS_CLOUD_URL`, authentifié avec -`OS_CLOUD_API_KEY`. Pour une distribution privée / air-gapped, ignorez la -publication et transmettez directement le `dist/objectstack.json` compilé -à l'installation cible (voir Installation ci-dessous). Voir [Marketplace](/docs/build/marketplace). - -## Installation - -| Méthode | Comment | -|---|---| -| Console | Onglet Marketplace → choisir le package → Install | -| REST | `POST /api/v1/marketplace/install-local` (corps : `{ packageId, versionId? }`) | -| Air-gapped | Monter l'artefact `dist/objectstack.json` compilé (voir [Air-gapped](/docs/deploy/air-gapped)) | - -L'installation fusionne les métadonnées du package dans le kernel en -service, enregistre ses objects auprès d'ObjectQL et amorce les données -initiales lors de la première installation — aucun redémarrage requis. Les -installations en cache sont réenregistrées au prochain démarrage, ce qui -leur permet de survivre aux redémarrages de processus. - -## Désinstallation - -La désinstallation supprime le manifeste mis en cache du package afin qu'il -ne soit plus réenregistré au prochain démarrage. Comme l'enregistrement des -objects est additif, un **redémarrage du kernel** est nécessaire pour -décharger complètement les objects d'un package déjà en cours d'exécution. -Les données sont **conservées** par défaut, ce qui vous permet de -réinstaller et de reprendre. - -## Conventions inter-packages - -Pour éviter les collisions lorsque de nombreux packages coexistent : - -| Artefact | Convention | -|---|---| -| Noms d'objects | Toujours préfixés : `crm_account`, `hd_ticket` | -| Noms d'actions | Préfixés : `crm_assign_owner`, `hd_close_ticket` | -| Noms de flows | Préfixés : `hd_overdue_alert` | -| Clés de traduction | Cadrées sous le namespace : `crm.account.label` | -| `externalId` des seeds | `:`, ex. `crm:demo-account-1` | -| Noms système | Réservés : `sys_*` (à ne jamais utiliser dans les packages personnalisés) | - -La CLI et l'AI Builder appliquent tous deux ces règles à la création. - -## Packages système - -Le runtime fournit un petit ensemble de packages toujours présents qui -offrent des services polymorphes : - -| Package | Fournit | -|---|---| -| `sys.identity` | `sys_user`, `sys_organization`, `sys_member`, sessions, clés API | -| `sys.feeds` | `sys_comment`, `sys_activity`, `sys_attachment` | -| `sys.audit` | `sys_audit_log` | -| `sys.files` | `sys_file` | -| `sys.ai` | `ai_conversations`, `ai_pending_actions` | -| `sys.settings` | `sys_setting` | - -Vous les activez via `enable: { feeds: true, trackHistory: true, … }` -sur vos objects — voir [Data Model](/docs/build/data). - -## Pour aller plus loin - -- [Marketplace](/docs/build/marketplace) — distribuer des packages à d'autres tenants -- [Data Model](/docs/build/data) — ce qui réside à l'intérieur d'un package -- [Commandes `os package`](/docs/reference/cli) — référence CLI complète diff --git a/content/docs/build/packages.ja.mdx b/content/docs/build/packages.ja.mdx deleted file mode 100644 index 540313f..0000000 --- a/content/docs/build/packages.ja.mdx +++ /dev/null @@ -1,134 +0,0 @@ ---- -title: パッケージ -description: ObjectOS における組織化の単位 — バージョン管理され、インストール可能で、共有可能。 ---- - -ObjectOS で構築するものはすべて **パッケージ** の中に存在します。パッケージとは、バージョン管理された、自己完結型のメタデータのまとまりです。パッケージは AI Builder が作業する単位であり、marketplace が配布する単位であり、ObjectOS が更新を追跡する単位でもあります。 - -## パッケージの中身 - -```text -com.acme.crm@1.2.0 -├── manifest id, version, namespace, dependencies -├── objects/ *.object.ts, *.state.ts, *.hook.ts -├── views/ *.view.ts, *.page.ts, *.form.ts -├── actions/ *.action.ts -├── flows/ *.flow.ts, *.approval.ts -├── agents/ *.agent.ts, *.skill.ts -├── permissions/ *.permission.ts -├── sharing/ *.sharing.ts -├── translations/ en.ts, zh-CN.ts, ... -├── apps/ *.app.ts (navigation) -└── data/ defineDataset(...) seed -``` - -すべてのメタデータ成果物（object、action、flow、…）は、ちょうど 1 つのパッケージに属します。パッケージ id は **逆 DNS** 形式（`com.acme.crm`、`org.mycompany.helpdesk`）であり、namespace のプレフィックス（`crm_`、`hd_`）によって、同一テナントにインストールされたパッケージ間でテーブル名 / object 名が衝突しないようにします。 - -## パッケージの作成 - -### AI Builder から - -> *「社内 CRM 用の新しいパッケージを namespace `crm` で開始して。」* - -AI は `create_package` と `set_active_package` を呼び出します。それ以降、記述したすべての object / field / action は `crm` に格納されます。 - -### CLI から - -```bash -os init my-crm -t app -cd my-crm -# manifest lives in the `manifest:` block of ./objectstack.config.ts -pnpm dev -``` - -### Console から - -**Console → Packages → New Package** — name、id、version、namespace を指定します。 - -## アクティブパッケージ - -AI Builder では、会話は **アクティブパッケージ**（新しいメタデータのデフォルトのコンテナ）を保持します。*「`com.acme.helpdesk` に切り替えて。」* のように指示すると、AI は `set_active_package` ツールでこれを設定します。CLI では、アクティブパッケージは単にプロジェクトの `objectstack.config.ts`（`manifest:` ブロック）で宣言されているものになります。 - -## バージョニング - -パッケージは **semver** に従います。ランタイムと同じルールです。詳しくは [Changelog & Versioning](/docs/resources/changelog) を参照してください。 - -バージョンを上げても、公開するまでは何も変わりません。ランタイムはテナントごと・パッケージごとに `installed_version` を追跡し、カタログにより新しいバージョンがある場合、marketplace には *「Update available」* バッジが表示されます。 - -## 依存関係 - -パッケージは他のパッケージに依存できます。 - -```json -{ - "id": "com.acme.helpdesk", - "version": "0.3.0", - "dependencies": { - "com.acme.crm": "^1.0.0", - "sys.feeds": "*" - } -} -``` - -ランタイムはインストール時に依存関係を解決します。`com.acme.crm` がインストールされていない場合、helpdesk のインストールは明確なエラーとともに失敗します。 - -システムパッケージ（`sys.*`）は常に存在します。feeds、attachments、audit、identity などです。 - -## 公開 - -```bash -os compile # → dist/objectstack.json -os package publish # → ObjectStack cloud catalog -``` - -`os package publish` は、コンパイル済みの manifest を、`OS_CLOUD_URL` で設定されたクラウドコントロールプレーンにアップロードし、`OS_CLOUD_API_KEY` で認証します。プライベートな / エアギャップ環境での配布の場合は、公開をスキップし、コンパイル済みの `dist/objectstack.json` を直接インストール先に渡します（後述の「インストール」を参照）。[Marketplace](/docs/build/marketplace) も参照してください。 - -## インストール - -| 経路 | 方法 | -|---|---| -| Console | Marketplace タブ → パッケージを選択 → Install | -| REST | `POST /api/v1/marketplace/install-local`（body: `{ packageId, versionId? }`） | -| エアギャップ | コンパイル済みの `dist/objectstack.json` 成果物をマウント（[Air-gapped](/docs/deploy/air-gapped) を参照） | - -インストールは、パッケージのメタデータを稼働中のカーネルにマージし、その object を ObjectQL に登録し、初回インストール時には初期データをシードします。再起動は不要です。キャッシュされたインストールは次回のブート時に再登録されるため、プロセスの再起動後も維持されます。 - -## アンインストール - -アンインストールはパッケージのキャッシュされた manifest を削除するため、次回のブート時に再登録されなくなります。object の登録は追加的に行われるため、すでに稼働中のパッケージの object を完全にアンロードするには **カーネルの再起動** が必要です。データはデフォルトで **保持** されるため、再インストールして再開できます。 - -## パッケージ横断の規約 - -多数のパッケージが共存する際の衝突を防ぐために： - -| 成果物 | 規約 | -|---|---| -| Object 名 | 常にプレフィックス付き: `crm_account`、`hd_ticket` | -| Action 名 | プレフィックス付き: `crm_assign_owner`、`hd_close_ticket` | -| Flow 名 | プレフィックス付き: `hd_overdue_alert` | -| 翻訳キー | namespace 配下にスコープ: `crm.account.label` | -| シードの `externalId` | `:`、例: `crm:demo-account-1` | -| システム名 | 予約済み: `sys_*`（カスタムパッケージでは使用しない） | - -CLI と AI Builder はどちらも、作成時にこの規約を強制します。 - -## システムパッケージ - -ランタイムには、ポリモーフィックなサービスを提供する、常に存在する小さなパッケージ群が同梱されています。 - -| パッケージ | 提供するもの | -|---|---| -| `sys.identity` | `sys_user`、`sys_organization`、`sys_member`、セッション、API キー | -| `sys.feeds` | `sys_comment`、`sys_activity`、`sys_attachment` | -| `sys.audit` | `sys_audit_log` | -| `sys.files` | `sys_file` | -| `sys.ai` | `ai_conversations`、`ai_pending_actions` | -| `sys.settings` | `sys_setting` | - -これらは object 上で `enable: { feeds: true, trackHistory: true, … }` を指定することで有効化します。[Data Model](/docs/build/data) を参照してください。 - -## 次に読むべきもの - -- [Marketplace](/docs/build/marketplace) — パッケージを他のテナントに配布する -- [Data Model](/docs/build/data) — パッケージの中に入るもの -- [`os package` commands](/docs/reference/cli) — CLI の完全なリファレンス diff --git a/content/docs/build/packages.ko.mdx b/content/docs/build/packages.ko.mdx deleted file mode 100644 index a9824be..0000000 --- a/content/docs/build/packages.ko.mdx +++ /dev/null @@ -1,134 +0,0 @@ ---- -title: 패키지 -description: ObjectOS의 조직 단위 — 버전 관리되고, 설치 가능하며, 공유할 수 있습니다. ---- - -ObjectOS에서 만드는 모든 것은 **패키지** 안에 존재합니다. 패키지는 버전이 관리되고 자체적으로 완결된 메타데이터 번들입니다. 패키지는 AI Builder가 작업하는 단위이자, marketplace가 배포하는 단위이며, ObjectOS가 업데이트를 추적하는 단위입니다. - -## 패키지의 구성 요소 - -```text -com.acme.crm@1.2.0 -├── manifest id, version, namespace, dependencies -├── objects/ *.object.ts, *.state.ts, *.hook.ts -├── views/ *.view.ts, *.page.ts, *.form.ts -├── actions/ *.action.ts -├── flows/ *.flow.ts, *.approval.ts -├── agents/ *.agent.ts, *.skill.ts -├── permissions/ *.permission.ts -├── sharing/ *.sharing.ts -├── translations/ en.ts, zh-CN.ts, ... -├── apps/ *.app.ts (navigation) -└── data/ defineDataset(...) seed -``` - -모든 메타데이터 아티팩트(object, action, flow 등)는 정확히 하나의 패키지에 속합니다. 패키지 id는 **reverse-DNS**(`com.acme.crm`, `org.mycompany.helpdesk`) 형식이며, 네임스페이스 접두사(`crm_`, `hd_`)는 같은 테넌트에 설치된 여러 패키지 간에 테이블/object 이름이 충돌하지 않도록 합니다. - -## 패키지 생성하기 - -### AI Builder에서 - -> *"우리 내부 CRM용 새 패키지를 시작하고, 네임스페이스는 `crm`으로 해줘."* - -AI는 `create_package`와 `set_active_package`를 호출합니다. 그 이후로 당신이 설명하는 모든 object / field / action은 `crm`에 들어갑니다. - -### CLI에서 - -```bash -os init my-crm -t app -cd my-crm -# manifest lives in the `manifest:` block of ./objectstack.config.ts -pnpm dev -``` - -### Console에서 - -**Console → Packages → New Package** — 이름, id, 버전, 네임스페이스. - -## 활성 패키지 - -AI Builder에서는 대화가 **활성 패키지(active package)**를 가지고 있습니다. 이는 새 메타데이터의 기본 컨테이너입니다. 당신이 *"`com.acme.helpdesk`로 전환해줘."*와 같이 말하면 AI가 `set_active_package` 도구로 이를 설정합니다. CLI에서 활성 패키지는 단순히 프로젝트의 `objectstack.config.ts`(`manifest:` 블록)에 선언된 패키지입니다. - -## 버전 관리 - -패키지는 **semver**를 따릅니다. 런타임과 동일한 규칙입니다 — [Changelog & Versioning](/docs/resources/changelog)을 참고하세요. - -버전을 올리더라도 게시(publish)하기 전까지는 아무것도 바뀌지 않습니다. 런타임은 테넌트별, 패키지별로 `installed_version`을 추적하며, 카탈로그에 더 최신 버전이 있으면 marketplace에 *"Update available"* 배지가 표시됩니다. - -## 의존성 - -패키지는 다른 패키지에 의존할 수 있습니다: - -```json -{ - "id": "com.acme.helpdesk", - "version": "0.3.0", - "dependencies": { - "com.acme.crm": "^1.0.0", - "sys.feeds": "*" - } -} -``` - -런타임은 설치 시 의존성을 해석합니다. `com.acme.crm`이 설치되어 있지 않으면 helpdesk 설치는 명확한 오류와 함께 실패합니다. - -시스템 패키지(`sys.*`)는 항상 존재합니다 — feeds, attachments, audit, identity 등. - -## 게시하기 - -```bash -os compile # → dist/objectstack.json -os package publish # → ObjectStack cloud catalog -``` - -`os package publish`는 컴파일된 manifest를 `OS_CLOUD_URL`로 구성된 클라우드 컨트롤 플레인에 업로드하며, `OS_CLOUD_API_KEY`로 인증합니다. 비공개/에어갭(air-gapped) 배포의 경우 게시를 건너뛰고 컴파일된 `dist/objectstack.json`을 대상 설치 환경에 직접 전달하세요(아래 설치 섹션 참조). [Marketplace](/docs/build/marketplace)를 참고하세요. - -## 설치하기 - -| 경로 | 방법 | -|---|---| -| Console | Marketplace 탭 → 패키지 선택 → Install | -| REST | `POST /api/v1/marketplace/install-local` (본문: `{ packageId, versionId? }`) | -| 에어갭 | 컴파일된 `dist/objectstack.json` 아티팩트를 마운트 (참고: [Air-gapped](/docs/deploy/air-gapped)) | - -설치는 패키지의 메타데이터를 실행 중인 커널에 병합하고, 해당 object들을 ObjectQL에 등록하며, 최초 설치 시 초기 데이터를 시드합니다 — 재시작이 필요 없습니다. 캐시된 설치는 다음 부팅 시 다시 등록되므로 프로세스 재시작에도 유지됩니다. - -## 제거하기 - -제거는 패키지의 캐시된 manifest를 삭제하여 다음 부팅 시 더 이상 재등록되지 않도록 합니다. object 등록은 누적 방식이므로, 이미 실행 중인 패키지의 object를 완전히 언로드하려면 **커널 재시작**이 필요합니다. 데이터는 기본적으로 **유지**되므로, 다시 설치하여 이어서 사용할 수 있습니다. - -## 패키지 간 규약 - -여러 패키지가 공존할 때 충돌을 방지하기 위해: - -| 아티팩트 | 규약 | -|---|---| -| Object 이름 | 항상 접두사 사용: `crm_account`, `hd_ticket` | -| Action 이름 | 접두사 사용: `crm_assign_owner`, `hd_close_ticket` | -| Flow 이름 | 접두사 사용: `hd_overdue_alert` | -| 번역 키 | 네임스페이스 하위로 스코프 지정: `crm.account.label` | -| 시드 `externalId` | `:`, 예: `crm:demo-account-1` | -| 시스템 이름 | 예약됨: `sys_*` (커스텀 패키지에서 절대 사용 금지) | - -CLI와 AI Builder 모두 생성 시 이 규약을 강제합니다. - -## 시스템 패키지 - -런타임은 항상 존재하면서 다형적(polymorphic) 서비스를 제공하는 소수의 패키지를 함께 제공합니다: - -| 패키지 | 제공 항목 | -|---|---| -| `sys.identity` | `sys_user`, `sys_organization`, `sys_member`, 세션, API 키 | -| `sys.feeds` | `sys_comment`, `sys_activity`, `sys_attachment` | -| `sys.audit` | `sys_audit_log` | -| `sys.files` | `sys_file` | -| `sys.ai` | `ai_conversations`, `ai_pending_actions` | -| `sys.settings` | `sys_setting` | - -object에서 `enable: { feeds: true, trackHistory: true, … }`를 통해 활성화할 수 있습니다 — [Data Model](/docs/build/data)을 참고하세요. - -## 다음으로 볼 곳 - -- [Marketplace](/docs/build/marketplace) — 다른 테넌트에 패키지 배포 -- [Data Model](/docs/build/data) — 패키지 안에 들어가는 것 -- [`os package` commands](/docs/reference/cli) — 전체 CLI 레퍼런스 diff --git a/content/docs/build/packages.mdx b/content/docs/build/packages.mdx index 2cbbef0..40b5a09 100644 --- a/content/docs/build/packages.mdx +++ b/content/docs/build/packages.mdx @@ -101,12 +101,19 @@ os compile # → dist/objectstack.json os package publish # → ObjectStack cloud catalog ``` -`os package publish` uploads the compiled manifest to the cloud -control plane configured by `OS_CLOUD_URL`. Authentication comes from -`os cloud login` (interactive) or, for CI, an `OS_CLOUD_API_KEY` bearer -token. For private / air-gapped distribution, skip publishing and hand -the compiled `dist/objectstack.json` directly to the target install -(see Installing below). See [Marketplace](/docs/build/marketplace). +`os package publish` uploads the compiled manifest to the catalog named +by `OS_CLOUD_URL`. Authentication comes from `os cloud login` +(interactive) or, for CI, an `OS_CLOUD_API_KEY` bearer token. For +private / air-gapped distribution, skip publishing and hand the +compiled `dist/objectstack.json` directly to the target install (see +Installing below). See [Marketplace](/docs/build/marketplace). + +> **These two variables configure the publishing identity of your build +> machine** — the CLI's credential for a package catalog. They are not how a +> *deployment* connects to a control plane: a running deployment authenticates +> with a token minted when it was bound, and has no API key to configure. Check +> [Environment Variables](/docs/reference/environment-variables) before copying +> either name into a deployment's configuration. ## Installing diff --git a/content/docs/build/packages.zh-Hans.mdx b/content/docs/build/packages.zh-Hans.mdx deleted file mode 100644 index c8b8dde..0000000 --- a/content/docs/build/packages.zh-Hans.mdx +++ /dev/null @@ -1,154 +0,0 @@ ---- -title: Packages -description: ObjectOS 中的组织单元 —— 可版本化、可安装、可共享。 ---- - -你在 ObjectOS 中构建的一切都存放于一个**包（package）**中：一个可版本化、 -自包含的元数据捆绑体。包是 AI Builder 操作的单元，是 marketplace 分发的单元， -也是 ObjectOS 追踪更新所依据的单元。 - -## 包里有什么 - -```text -com.acme.crm@1.2.0 -├── manifest id, version, namespace, dependencies -├── objects/ *.object.ts, *.state.ts, *.hook.ts -├── views/ *.view.ts, *.page.ts, *.form.ts -├── actions/ *.action.ts -├── flows/ *.flow.ts, *.approval.ts -├── agents/ *.agent.ts, *.skill.ts -├── permissions/ *.permission.ts -├── sharing/ *.sharing.ts -├── translations/ en.ts, zh-CN.ts, ... -├── apps/ *.app.ts (navigation) -└── data/ defineDataset(...) seed -``` - -每一个元数据制品（对象、操作、流程……）都恰好归属于一个包。包 id 采用 -**反向 DNS**（`com.acme.crm`、`org.mycompany.helpdesk`），而命名空间前缀 -（`crm_`、`hd_`）能避免在同一租户中安装的不同包之间，表名 / 对象名发生冲突。 - -## 创建一个包 - -### 从 AI Builder 创建 - -> *"为我们的内部 CRM 新建一个包，命名空间为 `crm`。"* - -AI 会调用 `create_package` 和 `set_active_package`。从此之后， -你所描述的每一个对象 / 字段 / 操作都会落入 `crm`。 - -### 从 CLI 创建 - -```bash -os init my-crm -t app -cd my-crm -# manifest lives in the `manifest:` block of ./objectstack.config.ts -pnpm dev -``` - -### 从 Console 创建 - -**Console → Packages → New Package** —— 填写名称、id、版本、命名空间。 - -## 活动包（Active package） - -在 AI Builder 中，一段对话会携带一个**活动包**—— 即新元数据的默认容器。 -当你说类似 *"切换到 `com.acme.helpdesk`。"* 这样的话时，AI 会通过 -`set_active_package` 工具来设置它。从 CLI 来看，活动包就是项目的 -`objectstack.config.ts` 中声明的那个包（即 `manifest:` 块）。 - -## 版本管理 - -包采用 **semver**。规则与运行时相同 —— 参见 -[Changelog & Versioning](/docs/resources/changelog)。 - -在你发布之前，提升版本号不会改变任何东西。运行时会按租户、按包追踪 -`installed_version`，当目录中存在更新版本时，marketplace 会显示一个 -*"Update available"* 徽标。 - -## 依赖 - -包可以依赖其他包： - -```json -{ - "id": "com.acme.helpdesk", - "version": "0.3.0", - "dependencies": { - "com.acme.crm": "^1.0.0", - "sys.feeds": "*" - } -} -``` - -运行时会在安装时解析依赖。如果 `com.acme.crm` 未安装，helpdesk 的安装会 -带着清晰的错误信息失败。 - -系统包（`sys.*`）始终存在 —— feeds、附件、审计、身份等。 - -## 发布 - -```bash -os compile # → dist/objectstack.json -os package publish # → ObjectStack cloud catalog -``` - -`os package publish` 会将编译后的 manifest 上传到由 `OS_CLOUD_URL` 配置的 -云端控制平面，并使用 `OS_CLOUD_API_KEY` 进行认证。对于私有 / 隔离网络 -（air-gapped）分发，可跳过发布，直接将编译好的 `dist/objectstack.json` -交给目标安装方（参见下方的「安装」）。参见 [Marketplace](/docs/build/marketplace)。 - -## 安装 - -| 路径 | 方式 | -|---|---| -| Console | Marketplace 标签页 → 选择包 → Install | -| REST | `POST /api/v1/marketplace/install-local`（请求体：`{ packageId, versionId? }`） | -| 隔离网络（Air-gapped） | 挂载编译后的 `dist/objectstack.json` 制品（参见 [Air-gapped](/docs/deploy/air-gapped)） | - -安装会将包的元数据合并进运行中的内核，将其对象注册到 ObjectQL，并在首次安装时 -注入初始数据 —— 无需重启。已缓存的安装会在下次启动时重新注册，因此能够在进程 -重启后依然保留。 - -## 卸载 - -卸载会移除包已缓存的 manifest，使其不再在下次启动时被重新注册。由于对象注册是 -增量式的，要彻底卸载一个已在运行中的包的对象，需要进行一次**内核重启**。 -数据默认会被**保留**，因此你可以重新安装并继续使用。 - -## 跨包约定 - -为防止多个包共存时发生冲突： - -| 制品 | 约定 | -|---|---| -| 对象名 | 始终带前缀：`crm_account`、`hd_ticket` | -| 操作名 | 带前缀：`crm_assign_owner`、`hd_close_ticket` | -| 流程名 | 带前缀：`hd_overdue_alert` | -| 翻译键 | 限定在命名空间下：`crm.account.label` | -| 种子数据 `externalId` | `:`，例如 `crm:demo-account-1` | -| 系统名 | 保留：`sys_*`（切勿在自定义包中使用） | - -CLI 和 AI Builder 在创建时都会强制执行这些约定。 - -## 系统包 - -运行时自带一小组始终存在的包，提供多态服务： - -| 包 | 提供内容 | -|---|---| -| `sys.identity` | `sys_user`、`sys_organization`、`sys_member`、会话、API keys | -| `sys.feeds` | `sys_comment`、`sys_activity`、`sys_attachment` | -| `sys.audit` | `sys_audit_log` | -| `sys.files` | `sys_file` | -| `sys.ai` | `ai_conversations`、`ai_pending_actions` | -| `sys.settings` | `sys_setting` | - -你可以在对象上通过 `enable: { feeds: true, trackHistory: true, … }` 来启用它们 —— -参见 [Data Model](/docs/build/data)。 - -## 下一步去哪 - -- [Marketplace](/docs/build/marketplace) —— 将包分发到其他租户 -- [Data Model](/docs/build/data) —— 包里都放些什么 -- [`os package` 命令](/docs/reference/cli) —— 完整 CLI 参考 diff --git a/content/docs/configure/runtime.de.mdx b/content/docs/configure/runtime.de.mdx deleted file mode 100644 index 01e55e8..0000000 --- a/content/docs/configure/runtime.de.mdx +++ /dev/null @@ -1,123 +0,0 @@ ---- -title: Laufzeitkonfiguration -description: Konfigurieren Sie das Laden von Artefakten, die Projektauflösung, die Datenbank, den Cache und Laufzeit-Secrets. ---- - -Die ObjectOS-Laufzeitkonfiguration beantwortet drei Fragen: - -1. Welches Projekt soll diese Anfrage bedienen? -2. Wo befindet sich das kompilierte Artefakt? -3. Welche Datenbank und welche Laufzeitdienste soll das Projekt verwenden? - -## Boot-Modi - -| Modus | Verwenden, wenn | Wichtige Konfiguration | -|---|---|---| -| Standalone | `os start` ohne Konfiguration — schnelle Demo, leerer Kernel, ~23 Plugins, lokales SQLite unter `~/.objectstack/data/standalone.db` | _keine_ (Standardwerte) | -| File-backed | Einzelnes Projekt, Demo, Offline-Bundle für Kunden, Air-Gapped-Bereitstellung | `OS_ARTIFACT_FILE` | -| Cloud-connected | Eine gehostete oder private Control Plane veröffentlicht Projektartefakte | `OS_CLOUD_URL`, `OS_PROJECT_ID` oder Hostnamen-Auflösung | - -### Standalone-Modus - -Der Standard, wenn Sie `os start` ohne Konfiguration oder Artefakt ausführen. -ObjectOS startet einen leeren Kernel mit geladenen Plattform-Plugins -(`auth`, `security`, `audit`, `storage`, `webhooks`, `mcp-server`, -`marketplace-proxy`, `marketplace-install-local`, …), öffnet lokales -SQLite unter `~/.objectstack/data/standalone.db` und stellt die Console- -und Account-UIs bereit. - -Installieren Sie Apps über den marketplace-Tab in der Console, um den Kernel -mit Objekten, Ansichten und Flows zu füllen — kein Rebuild, kein Neustart. Am besten geeignet für -Demos, Evaluierung und die Erkundung im Sinne von "Zeig mir, was das Ding kann". - -`os start` eskaliert automatisch: - -| Erkannt | Verhalten | -|---|---| -| Nichts | Standalone-Modus (siehe oben) | -| `objectstack.config.ts` im cwd | Projektmodus — automatische Kompilierung, `HOME=/.objectstack` | -| Kompiliertes Artefakt im cwd | Artefaktmodus — dieses Artefakt laden | -| Explizites `--artifact ` oder `OS_CLOUD_URL` | File-backed- / Cloud-connected-Modus | - -## File-backed-Modus - -Festlegen: - -```bash -OS_ARTIFACT_FILE=/artifacts/objectstack.json -``` - -ObjectOS verwendet einen lokalen Artifact-API-Client. Jeder Hostname wird auf -dasselbe Projekt aufgelöst. Die Laufzeitkonfiguration wird aus dem Artefakt gelesen, sofern vorhanden, -oder fällt für die Evaluierung auf einen lokalen Laufzeit-Standard zurück. - -`OS_ARTIFACT_FILE` ist die Konvention des ObjectOS-App-Wrappers. Die zugrunde liegende -Laufzeit akzeptiert auch `OS_ARTIFACT_PATH` direkt (verwendet von den -Befehlen `dev` und `start` der `@objectstack/cli` und vom Standalone-Stack des -Frameworks). Legen Sie eines von beiden fest — nicht beide. - -Optional: - -```bash -OS_ENVIRONMENT_ID=env_prod # or the legacy alias OS_PROJECT_ID -OS_WATCH_ARTIFACT=1 -``` - -Verwenden Sie den Watch-Modus nur für die Entwicklung oder für Smoke-Tests. - -## Cloud-connected-Modus - -Festlegen: - -```bash -OS_CLOUD_URL=https://cloud.example.com -OS_CLOUD_API_KEY=replace-with-deployment-token -``` - -ObjectOS fordert die Control Plane auf: - -- den Hostnamen zu Projekt/Umgebung aufzulösen; -- das aktuelle Artefakt abzurufen; -- die Laufzeit-Datenbankkonfiguration für dieses Projekt zu empfangen. - -ObjectOS sollte sich nicht direkt mit der Datenbank der Control Plane verbinden. - -## Authentifizierungs-Secret - -Legen Sie ein starkes Basis-Secret fest: - -```bash -OS_AUTH_SECRET=replace-with-a-strong-random-secret -``` - -ObjectOS leitet projektspezifische Auth-Secrets aus diesem Wert ab. Das hält -die Sitzungssignierung pro Projekt isoliert und ermöglicht gleichzeitig deterministische -Neustarts. Das Rotieren dieses Werts macht bestehende Sitzungen ungültig. - -## Kernel- und Artefakt-Caches - -ObjectOS cacht aufgelöste Umgebungen und Projekt-Kernel, um zu vermeiden, -dass für jede Anfrage ein Kernel neu erstellt wird. - -| Variable | Standard | Zweck | -|---|---:|---| -| `OS_KERNEL_CACHE_SIZE` | `32` | Maximale Anzahl zwischengespeicherter Projekt-Kernel | -| `OS_KERNEL_TTL_MS` | `900000` | Leerlauf-TTL für zwischengespeicherte Kernel | -| `OS_ENV_CACHE_TTL_MS` | `300000` | Cache für Hostnamen-/Umgebungsauflösung | -| `OS_ARTIFACT_CACHE_TTL_MS` | `300000` | Cache für Artefaktantworten | - -Niedrigere TTLs machen Änderungen schneller sichtbar. Höhere TTLs reduzieren den Datenverkehr -zur Control Plane und Kaltstarts. - -## Datenbankkonfiguration - -Im Cloud-connected-Modus gibt die Control Plane die projektspezifische -Laufzeit-Datenbankkonfiguration mit der Artefaktantwort zurück. - -Im File-backed-Modus kann ObjectOS die Datenbankeinstellungen aus den -Datasource-Deklarationen des Artefakts ableiten. Zu den unterstützten Framework-Treibern gehören -SQLite, PostgreSQL, MySQL, MongoDB und speicherbasierte Evaluierungstreiber. - -Verwenden Sie für die Produktion eine kundenverwaltete Datenbank. Verlassen Sie sich für -Geschäftsdaten nicht auf containerlokalen Speicher, es sei denn, die Bereitstellung ist -ausdrücklich eine Single-Node-Evaluierung. diff --git a/content/docs/configure/runtime.es.mdx b/content/docs/configure/runtime.es.mdx deleted file mode 100644 index e397305..0000000 --- a/content/docs/configure/runtime.es.mdx +++ /dev/null @@ -1,124 +0,0 @@ ---- -title: Configuración del entorno de ejecución -description: Configura la carga de artefactos, la resolución de proyectos, la base de datos, la caché y los secretos del entorno de ejecución. ---- - -La configuración del entorno de ejecución de ObjectOS responde a tres preguntas: - -1. ¿Qué proyecto debe atender esta solicitud? -2. ¿Dónde está el artefacto compilado? -3. ¿Qué base de datos y servicios de ejecución debe usar el proyecto? - -## Modos de arranque - -| Modo | Úsalo cuando | Configuración clave | -|---|---|---| -| Standalone | `os start` sin configuración — demo rápida, kernel vacío, ~23 plugins, SQLite local en `~/.objectstack/data/standalone.db` | _ninguna_ (valores por defecto) | -| File-backed | Proyecto único, demo, paquete offline del cliente, despliegue aislado de la red | `OS_ARTIFACT_FILE` | -| Cloud-connected | Un plano de control alojado o privado publica los artefactos del proyecto | `OS_CLOUD_URL`, `OS_PROJECT_ID` o resolución por nombre de host | - -### Modo standalone - -El modo por defecto cuando ejecutas `os start` sin configuración ni artefacto. -ObjectOS arranca un kernel vacío con los plugins de plataforma cargados -(`auth`, `security`, `audit`, `storage`, `webhooks`, `mcp-server`, -`marketplace-proxy`, `marketplace-install-local`, …), abre SQLite local -en `~/.objectstack/data/standalone.db` y sirve las interfaces de Console -y Account. - -Instala apps desde la pestaña del marketplace en Console para poblar el kernel -con objetos, vistas y flujos — sin recompilar ni reiniciar. Ideal para -demos, evaluación y exploraciones del tipo "muéstrame qué hace esto". - -`os start` escala automáticamente: - -| Detectado | Comportamiento | -|---|---| -| Nada | Modo standalone (arriba) | -| `objectstack.config.ts` en el cwd | Modo proyecto — compilación automática, `HOME=/.objectstack` | -| Artefacto compilado en el cwd | Modo artefacto — carga ese artefacto | -| `--artifact ` explícito u `OS_CLOUD_URL` | Modos file-backed / cloud-connected | - -## Modo file-backed - -Configura: - -```bash -OS_ARTIFACT_FILE=/artifacts/objectstack.json -``` - -ObjectOS usa un cliente local de la Artifact API. Cada nombre de host se resuelve -al mismo proyecto. La configuración del entorno de ejecución se lee del artefacto cuando está presente, -o recurre a un valor por defecto de ejecución local para evaluación. - -`OS_ARTIFACT_FILE` es la convención del app-wrapper de ObjectOS. El entorno de -ejecución subyacente también acepta `OS_ARTIFACT_PATH` directamente (usado por los -comandos `dev` y `start` de `@objectstack/cli` y por el stack standalone del -framework). Configura uno u otro — no ambos. - -Opcional: - -```bash -OS_ENVIRONMENT_ID=env_prod # o el alias heredado OS_PROJECT_ID -OS_WATCH_ARTIFACT=1 -``` - -Usa el modo watch solo para desarrollo o pruebas de humo. - -## Modo cloud-connected - -Configura: - -```bash -OS_CLOUD_URL=https://cloud.example.com -OS_CLOUD_API_KEY=replace-with-deployment-token -``` - -ObjectOS le pide al plano de control que: - -- resuelva el nombre de host a proyecto/entorno; -- obtenga el artefacto actual; -- reciba la configuración de la base de datos de ejecución para ese proyecto. - -ObjectOS no debe conectarse directamente a la base de datos del plano de control. - -## Secreto de autenticación - -Configura un secreto base robusto: - -```bash -OS_AUTH_SECRET=replace-with-a-strong-random-secret -``` - -ObjectOS deriva secretos de autenticación por proyecto a partir de este valor. Esto mantiene -la firma de sesiones aislada por proyecto, sin dejar de permitir reinicios -deterministas. Rotar este valor invalida las sesiones existentes. - -## Cachés de kernel y artefactos - -ObjectOS almacena en caché los entornos resueltos y los kernels de proyecto para evitar -reconstruir un kernel en cada solicitud. - -| Variable | Por defecto | Propósito | -|---|---:|---| -| `OS_KERNEL_CACHE_SIZE` | `32` | Número máximo de kernels de proyecto en caché | -| `OS_KERNEL_TTL_MS` | `900000` | TTL de inactividad para los kernels en caché | -| `OS_ENV_CACHE_TTL_MS` | `300000` | Caché de resolución de nombre de host/entorno | -| `OS_ARTIFACT_CACHE_TTL_MS` | `300000` | Caché de respuestas de artefactos | - -Los TTL más bajos hacen que los cambios sean visibles más rápido. Los TTL más altos reducen el -tráfico al plano de control y los arranques en frío. - -## Configuración de la base de datos - -En el modo cloud-connected, el plano de control devuelve la configuración de la base de datos -de ejecución por proyecto junto con la respuesta del artefacto. - -En el modo file-backed, ObjectOS puede derivar la configuración de la base de datos a partir de las -declaraciones de datasource del artefacto. Los drivers del framework compatibles incluyen -SQLite, PostgreSQL, MySQL, MongoDB y drivers de evaluación respaldados por -memoria. - -Para producción, usa una base de datos gestionada por el cliente. No dependas del -almacenamiento local del contenedor para los datos de negocio, a menos que el despliegue sea -explícitamente una evaluación de un solo nodo. diff --git a/content/docs/configure/runtime.fr.mdx b/content/docs/configure/runtime.fr.mdx deleted file mode 100644 index 9c449b4..0000000 --- a/content/docs/configure/runtime.fr.mdx +++ /dev/null @@ -1,123 +0,0 @@ ---- -title: Configuration de l'environnement d'exécution -description: Configurez le chargement des artefacts, la résolution des projets, la base de données, le cache et les secrets d'exécution. ---- - -La configuration de l'environnement d'exécution d'ObjectOS répond à trois questions : - -1. Quel projet cette requête doit-elle servir ? -2. Où se trouve l'artefact compilé ? -3. Quelle base de données et quels services d'exécution le projet doit-il utiliser ? - -## Modes de démarrage - -| Mode | À utiliser quand | Configuration clé | -|---|---|---| -| Standalone | `os start` sans configuration — démo rapide, kernel vide, environ 23 plugins, SQLite local à `~/.objectstack/data/standalone.db` | _aucune_ (valeurs par défaut) | -| Adossé à un fichier | Projet unique, démo, offre hors ligne client, déploiement isolé du réseau | `OS_ARTIFACT_FILE` | -| Connecté au cloud | Un plan de contrôle hébergé ou privé publie les artefacts du projet | `OS_CLOUD_URL`, `OS_PROJECT_ID` ou résolution par nom d'hôte | - -### Mode Standalone - -Mode par défaut lorsque vous exécutez `os start` sans configuration ni artefact. -ObjectOS démarre un kernel vide avec les plugins de la plateforme chargés -(`auth`, `security`, `audit`, `storage`, `webhooks`, `mcp-server`, -`marketplace-proxy`, `marketplace-install-local`, …), ouvre une base -SQLite locale à `~/.objectstack/data/standalone.db`, et sert les interfaces -Console et Account. - -Installez des applications depuis l'onglet marketplace dans Console pour peupler le kernel -avec des objets, des vues et des flux — sans recompilation, sans redémarrage. Idéal pour -les démos, l'évaluation et l'exploration de type « montre-moi ce que fait cette chose ». - -`os start` monte automatiquement en puissance : - -| Détecté | Comportement | -|---|---| -| Rien | Mode Standalone (ci-dessus) | -| `objectstack.config.ts` dans le répertoire courant | Mode projet — compilation automatique, `HOME=/.objectstack` | -| Artefact compilé dans le répertoire courant | Mode artefact — charge cet artefact | -| `--artifact ` explicite ou `OS_CLOUD_URL` | Modes adossé à un fichier / connecté au cloud | - -## Mode adossé à un fichier - -Définissez : - -```bash -OS_ARTIFACT_FILE=/artifacts/objectstack.json -``` - -ObjectOS utilise un client local de l'API Artifact. Chaque nom d'hôte se résout vers le -même projet. La configuration d'exécution est lue depuis l'artefact lorsqu'elle est présente, -ou repli sur une valeur d'exécution locale par défaut pour l'évaluation. - -`OS_ARTIFACT_FILE` est la convention de l'enveloppe applicative d'ObjectOS. L'environnement -d'exécution sous-jacent accepte aussi directement `OS_ARTIFACT_PATH` (utilisé par les -commandes `dev` et `start` de `@objectstack/cli` ainsi que par la stack -standalone du framework). Définissez l'une ou l'autre — pas les deux. - -Optionnel : - -```bash -OS_ENVIRONMENT_ID=env_prod # or the legacy alias OS_PROJECT_ID -OS_WATCH_ARTIFACT=1 -``` - -N'utilisez le mode surveillance que pour le développement ou les tests de fumée. - -## Mode connecté au cloud - -Définissez : - -```bash -OS_CLOUD_URL=https://cloud.example.com -OS_CLOUD_API_KEY=replace-with-deployment-token -``` - -ObjectOS demande au plan de contrôle de : - -- résoudre le nom d'hôte vers un projet/environnement ; -- récupérer l'artefact courant ; -- recevoir la configuration de la base de données d'exécution pour ce projet. - -ObjectOS ne doit pas se connecter directement à la base de données du plan de contrôle. - -## Secret d'authentification - -Définissez un secret de base robuste : - -```bash -OS_AUTH_SECRET=replace-with-a-strong-random-secret -``` - -ObjectOS dérive de cette valeur les secrets d'authentification propres à chaque projet. Cela -maintient la signature des sessions isolée par projet tout en permettant des redémarrages -déterministes. Faire pivoter cette valeur invalide les sessions existantes. - -## Caches du kernel et des artefacts - -ObjectOS met en cache les environnements résolus et les kernels de projet afin d'éviter -de reconstruire un kernel à chaque requête. - -| Variable | Valeur par défaut | Objet | -|---|---:|---| -| `OS_KERNEL_CACHE_SIZE` | `32` | Nombre maximum de kernels de projet mis en cache | -| `OS_KERNEL_TTL_MS` | `900000` | TTL d'inactivité pour les kernels mis en cache | -| `OS_ENV_CACHE_TTL_MS` | `300000` | Cache de résolution nom d'hôte/environnement | -| `OS_ARTIFACT_CACHE_TTL_MS` | `300000` | Cache des réponses d'artefacts | - -Des TTL plus faibles rendent les changements visibles plus rapidement. Des TTL plus élevés réduisent le -trafic vers le plan de contrôle et les démarrages à froid. - -## Configuration de la base de données - -En mode connecté au cloud, le plan de contrôle renvoie la configuration de la base de données -d'exécution propre au projet avec la réponse d'artefact. - -En mode adossé à un fichier, ObjectOS peut dériver les paramètres de la base de données à partir des -déclarations de sources de données de l'artefact. Les pilotes du framework pris en charge incluent -SQLite, PostgreSQL, MySQL, MongoDB et des pilotes d'évaluation en mémoire. - -Pour la production, utilisez une base de données gérée par le client. Ne vous appuyez pas sur le -stockage local du conteneur pour les données métier, sauf si le déploiement est -explicitement une évaluation mononœud. diff --git a/content/docs/configure/runtime.ja.mdx b/content/docs/configure/runtime.ja.mdx deleted file mode 100644 index d8eb3c0..0000000 --- a/content/docs/configure/runtime.ja.mdx +++ /dev/null @@ -1,120 +0,0 @@ ---- -title: ランタイム構成 -description: アーティファクトの読み込み、プロジェクトの解決、データベース、キャッシュ、ランタイムシークレットを構成します。 ---- - -ObjectOS のランタイム構成は、次の 3 つの問いに答えます。 - -1. このリクエストはどのプロジェクトを処理すべきか? -2. コンパイル済みアーティファクトはどこにあるか? -3. プロジェクトはどのデータベースとランタイムサービスを使用すべきか? - -## ブートモード - -| モード | 使用する場面 | 主な構成 | -|---|---|---| -| Standalone | 設定なしの `os start` — クイックデモ、空のカーネル、約 23 個のプラグイン、`~/.objectstack/data/standalone.db` のローカル SQLite | _なし_（デフォルト） | -| File-backed | 単一プロジェクト、デモ、顧客向けオフラインバンドル、エアギャップ環境へのデプロイ | `OS_ARTIFACT_FILE` | -| Cloud-connected | ホスト型またはプライベートのコントロールプレーンがプロジェクトアーティファクトを公開 | `OS_CLOUD_URL`、`OS_PROJECT_ID` またはホスト名解決 | - -### Standalone モード - -設定やアーティファクトなしで `os start` を実行したときのデフォルトです。 -ObjectOS はプラットフォームプラグイン（`auth`、`security`、`audit`、`storage`、`webhooks`、`mcp-server`、 -`marketplace-proxy`、`marketplace-install-local` など）を読み込んだ空のカーネルをブートし、 -`~/.objectstack/data/standalone.db` のローカル SQLite を開いて、Console と Account の UI を提供します。 - -Console の marketplace タブからアプリをインストールして、オブジェクト、ビュー、フローでカーネルを -構築できます。リビルドも再起動も不要です。デモ、評価、そして「これが何をするものか見せて」という -探索に最適です。 - -`os start` は自動的にエスカレートします。 - -| 検出された内容 | 動作 | -|---|---| -| なし | Standalone モード（上記） | -| cwd に `objectstack.config.ts` | プロジェクトモード — 自動コンパイル、`HOME=/.objectstack` | -| cwd にコンパイル済みアーティファクト | アーティファクトモード — そのアーティファクトを読み込む | -| 明示的な `--artifact ` または `OS_CLOUD_URL` | File-backed / cloud-connected モード | - -## File-backed モード - -設定します。 - -```bash -OS_ARTIFACT_FILE=/artifacts/objectstack.json -``` - -ObjectOS はローカルの Artifact API クライアントを使用します。すべてのホスト名が同じプロジェクトに -解決されます。ランタイム構成はアーティファクトが存在する場合はそこから読み込まれ、存在しない場合は -評価用のローカルランタイムデフォルトにフォールバックします。 - -`OS_ARTIFACT_FILE` は ObjectOS アプリラッパーの慣例です。基盤となるランタイムは -`OS_ARTIFACT_PATH` を直接受け付けることもできます（`@objectstack/cli` の `dev` および `start` -コマンド、ならびにフレームワークの standalone スタックで使用されます）。どちらか一方を設定します — -両方ではありません。 - -オプション: - -```bash -OS_ENVIRONMENT_ID=env_prod # or the legacy alias OS_PROJECT_ID -OS_WATCH_ARTIFACT=1 -``` - -ウォッチモードは開発またはスモークテストでのみ使用してください。 - -## Cloud-connected モード - -設定します。 - -```bash -OS_CLOUD_URL=https://cloud.example.com -OS_CLOUD_API_KEY=replace-with-deployment-token -``` - -ObjectOS はコントロールプレーンに次のことを要求します。 - -- ホスト名をプロジェクト/環境に解決する。 -- 現在のアーティファクトを取得する。 -- そのプロジェクトのランタイムデータベース構成を受け取る。 - -ObjectOS はコントロールプレーンのデータベースに直接接続すべきではありません。 - -## 認証シークレット - -強力なベースシークレットを設定します。 - -```bash -OS_AUTH_SECRET=replace-with-a-strong-random-secret -``` - -ObjectOS はこの値からプロジェクトごとの認証シークレットを導出します。これにより、セッション署名が -プロジェクトごとに分離されつつ、決定論的な再起動も可能になります。この値をローテーションすると、 -既存のセッションは無効になります。 - -## カーネルとアーティファクトのキャッシュ - -ObjectOS は、リクエストごとにカーネルを再構築するのを避けるため、解決済みの環境とプロジェクト -カーネルをキャッシュします。 - -| 変数 | デフォルト | 目的 | -|---|---:|---| -| `OS_KERNEL_CACHE_SIZE` | `32` | キャッシュするプロジェクトカーネルの最大数 | -| `OS_KERNEL_TTL_MS` | `900000` | キャッシュ済みカーネルのアイドル TTL | -| `OS_ENV_CACHE_TTL_MS` | `300000` | ホスト名/環境の解決キャッシュ | -| `OS_ARTIFACT_CACHE_TTL_MS` | `300000` | アーティファクトレスポンスのキャッシュ | - -TTL を低くすると変更がより速く反映されます。TTL を高くするとコントロールプレーンへのトラフィックと -コールドスタートが減少します。 - -## データベース構成 - -cloud-connected モードでは、コントロールプレーンがアーティファクトレスポンスとともにプロジェクト -ごとのランタイムデータベース構成を返します。 - -file-backed モードでは、ObjectOS はアーティファクトのデータソース宣言からデータベース設定を導出 -できます。サポートされるフレームワークドライバには、SQLite、PostgreSQL、MySQL、MongoDB、および -メモリベースの評価用ドライバが含まれます。 - -本番環境では、顧客が管理するデータベースを使用してください。デプロイが明示的に単一ノードの評価用で -ない限り、業務データをコンテナローカルのストレージに依存させないでください。 diff --git a/content/docs/configure/runtime.ko.mdx b/content/docs/configure/runtime.ko.mdx deleted file mode 100644 index 581af1f..0000000 --- a/content/docs/configure/runtime.ko.mdx +++ /dev/null @@ -1,124 +0,0 @@ ---- -title: 런타임 구성 -description: 아티팩트 로딩, 프로젝트 해석, 데이터베이스, 캐시, 런타임 시크릿을 구성합니다. ---- - -ObjectOS 런타임 구성은 세 가지 질문에 답합니다. - -1. 이 요청은 어떤 프로젝트를 처리해야 하는가? -2. 컴파일된 아티팩트는 어디에 있는가? -3. 프로젝트는 어떤 데이터베이스와 런타임 서비스를 사용해야 하는가? - -## 부팅 모드 - -| 모드 | 사용 시점 | 주요 구성 | -|---|---|---| -| Standalone | 구성 없이 `os start` — 빠른 데모, 빈 커널, 약 23개의 플러그인, `~/.objectstack/data/standalone.db`의 로컬 SQLite | _없음_ (기본값) | -| File-backed | 단일 프로젝트, 데모, 고객 오프라인 번들, 망분리 배포 | `OS_ARTIFACT_FILE` | -| Cloud-connected | 호스팅 또는 프라이빗 컨트롤 플레인이 프로젝트 아티팩트를 게시 | `OS_CLOUD_URL`, `OS_PROJECT_ID` 또는 호스트명 해석 | - -### Standalone 모드 - -구성이나 아티팩트 없이 `os start`를 실행할 때의 기본값입니다. -ObjectOS는 플랫폼 플러그인(`auth`, `security`, `audit`, `storage`, -`webhooks`, `mcp-server`, `marketplace-proxy`, -`marketplace-install-local`, …)이 로드된 빈 커널을 부팅하고, -`~/.objectstack/data/standalone.db`의 로컬 SQLite를 열며, Console과 -Account UI를 제공합니다. - -Console의 marketplace 탭에서 앱을 설치하여 커널을 객체, 뷰, 플로우로 -채우세요 — 재빌드나 재시작이 필요 없습니다. 데모, 평가, 그리고 "이게 무엇을 -하는지 보여줘" 식의 탐색에 가장 적합합니다. - -`os start`는 자동으로 단계를 격상합니다. - -| 감지된 것 | 동작 | -|---|---| -| 없음 | Standalone 모드 (위 참조) | -| cwd의 `objectstack.config.ts` | Project 모드 — 자동 컴파일, `HOME=/.objectstack` | -| cwd의 컴파일된 아티팩트 | Artifact 모드 — 해당 아티팩트 로드 | -| 명시적 `--artifact ` 또는 `OS_CLOUD_URL` | File-backed / cloud-connected 모드 | - -## File-backed 모드 - -설정: - -```bash -OS_ARTIFACT_FILE=/artifacts/objectstack.json -``` - -ObjectOS는 로컬 Artifact API 클라이언트를 사용합니다. 모든 호스트명은 동일한 -프로젝트로 해석됩니다. 런타임 구성은 아티팩트에 존재하면 그곳에서 읽으며, -없으면 평가용 로컬 런타임 기본값으로 폴백합니다. - -`OS_ARTIFACT_FILE`은 ObjectOS 앱 래퍼 규칙입니다. 기반 런타임은 -`OS_ARTIFACT_PATH`도 직접 허용합니다(`@objectstack/cli`의 `dev` 및 `start` -명령과 프레임워크의 standalone 스택에서 사용). 둘 중 하나만 설정하세요 — -둘 다 설정하지 마세요. - -선택 사항: - -```bash -OS_ENVIRONMENT_ID=env_prod # or the legacy alias OS_PROJECT_ID -OS_WATCH_ARTIFACT=1 -``` - -watch 모드는 개발이나 스모크 테스트에만 사용하세요. - -## Cloud-connected 모드 - -설정: - -```bash -OS_CLOUD_URL=https://cloud.example.com -OS_CLOUD_API_KEY=replace-with-deployment-token -``` - -ObjectOS는 컨트롤 플레인에 다음을 요청합니다. - -- 호스트명을 프로젝트/환경으로 해석; -- 현재 아티팩트를 가져오기; -- 해당 프로젝트의 런타임 데이터베이스 구성을 수신. - -ObjectOS는 컨트롤 플레인 데이터베이스에 직접 연결해서는 안 됩니다. - -## 인증 시크릿 - -강력한 베이스 시크릿을 설정하세요: - -```bash -OS_AUTH_SECRET=replace-with-a-strong-random-secret -``` - -ObjectOS는 이 값으로부터 프로젝트별 인증 시크릿을 파생합니다. 이를 통해 -세션 서명을 프로젝트별로 격리하면서도 결정론적 재시작을 허용합니다. 이 값을 -교체하면 기존 세션이 무효화됩니다. - -## 커널 및 아티팩트 캐시 - -ObjectOS는 모든 요청마다 커널을 재빌드하지 않도록 해석된 환경과 프로젝트 -커널을 캐시합니다. - -| 변수 | 기본값 | 용도 | -|---|---:|---| -| `OS_KERNEL_CACHE_SIZE` | `32` | 캐시되는 프로젝트 커널의 최대 개수 | -| `OS_KERNEL_TTL_MS` | `900000` | 캐시된 커널의 유휴 TTL | -| `OS_ENV_CACHE_TTL_MS` | `300000` | 호스트명/환경 해석 캐시 | -| `OS_ARTIFACT_CACHE_TTL_MS` | `300000` | 아티팩트 응답 캐시 | - -TTL을 낮추면 변경 사항이 더 빠르게 반영됩니다. TTL을 높이면 컨트롤 플레인 -트래픽과 콜드 스타트가 줄어듭니다. - -## 데이터베이스 구성 - -cloud-connected 모드에서는 컨트롤 플레인이 아티팩트 응답과 함께 프로젝트별 -런타임 데이터베이스 구성을 반환합니다. - -file-backed 모드에서는 ObjectOS가 아티팩트의 데이터소스 선언으로부터 -데이터베이스 설정을 파생할 수 있습니다. 지원되는 프레임워크 드라이버에는 -SQLite, PostgreSQL, MySQL, MongoDB, 그리고 메모리 기반 평가 드라이버가 -포함됩니다. - -프로덕션에서는 고객이 관리하는 데이터베이스를 사용하세요. 배포가 명시적으로 -단일 노드 평가인 경우가 아니라면 비즈니스 데이터를 컨테이너 로컬 스토리지에 -의존하지 마세요. diff --git a/content/docs/configure/runtime.mdx b/content/docs/configure/runtime.mdx index e349a46..00945dd 100644 --- a/content/docs/configure/runtime.mdx +++ b/content/docs/configure/runtime.mdx @@ -1,124 +1,115 @@ --- title: Runtime Configuration -description: Configure artifact loading, project resolution, database, cache, and runtime secrets. +description: Where the running app comes from, which database it uses, and the startup decisions a deployment has to declare. --- -ObjectOS runtime configuration answers three questions: +Runtime configuration answers three questions: -1. Which project should this request serve? -2. Where is the compiled artifact? -3. Which database and runtime services should the project use? +1. **Where does the running app come from?** +2. **Which database does it use?** +3. **What is this deployment entitled to be** — connected or disconnected, + one organization or many? -## Boot modes +This page is about the shape of those decisions. The variable names and their +exact contracts are in +[Environment Variables](/docs/reference/environment-variables); the values you +copy are in the deploy bundle that ships with your release. -| Mode | Use when | Key configuration | -|---|---|---| -| Standalone | `os start` with no config — quick demo, empty kernel, ~23 plugins, local SQLite at `~/.objectstack/data/standalone.db` | _none_ (defaults) | -| File-backed | Single project, demo, customer offline bundle, air-gapped deployment | `OS_ARTIFACT_FILE` | -| Cloud-connected | Hosted or private control plane publishes project artifacts | `OS_CLOUD_URL`, `OS_PROJECT_ID` or hostname resolution | - -### Standalone mode - -The default when you run `os start` without a config or artifact. -ObjectOS boots an empty kernel with the platform plugins loaded -(`auth`, `security`, `audit`, `storage`, `webhooks`, `mcp-server`, -`marketplace-proxy`, `marketplace-install-local`, …), opens local -SQLite at `~/.objectstack/data/standalone.db`, and serves the Console -and Account UIs. - -Install apps from the marketplace tab in Console to populate the kernel -with objects, views, and flows — no rebuild, no restart. Best for -demos, evaluation, and "show me what this thing does" exploration. - -`os start` escalates automatically: - -| Detected | Behavior | -|---|---| -| Nothing | Standalone mode (above) | -| `objectstack.config.ts` in cwd | Project mode — auto-compile, `HOME=/.objectstack` | -| Compiled artifact in cwd | Artifact mode — load that artifact | -| Explicit `--artifact ` or `OS_CLOUD_URL` | File-backed / cloud-connected modes | - -## File-backed mode - -Set: - -```bash -OS_ARTIFACT_FILE=/artifacts/objectstack.json -``` - -ObjectOS uses a local Artifact API client. Every hostname resolves to the -same project. The runtime config is read from the artifact when present, -or falls back to a local runtime default for evaluation. - -`OS_ARTIFACT_FILE` is the ObjectOS app-wrapper convention. The underlying -runtime also accepts `OS_ARTIFACT_PATH` directly (used by the -`@objectstack/cli` `dev` and `start` commands and by the framework's -standalone stack). Set either one — not both. - -Optional: - -```bash -OS_ENVIRONMENT_ID=env_prod # or the legacy alias OS_PROJECT_ID -OS_WATCH_ARTIFACT=1 -``` - -Use watch mode only for development or smoke tests. - -## Cloud-connected mode +## Where the app comes from -Set: +Exactly one source is in effect, and the deployment declares which. -```bash -OS_CLOUD_URL=https://cloud.example.com -OS_CLOUD_API_KEY=replace-with-deployment-token -``` - -ObjectOS asks the control plane to: - -- resolve hostname to project/environment; -- fetch the current artifact; -- receive the runtime database configuration for that project. - -ObjectOS should not connect directly to the control-plane database. +| Mode | Use when | How the app arrives | +|---|---|---| +| **Config-authored** | The shipped shape: one app, evaluation, air-gapped, most production deployments | The runtime serves the metadata authored in the image, plus whatever has been installed into it | +| **Artifact-pinned** | The app is released on its own cadence, independently of the runtime image | One variable names a published artifact by URL. The image's own configuration is not loaded on this path | +| **Composed** | Several organizations behind the isolation wall, sharing one database, running a published app | The same artifact reference, consumed from the deployment's own configuration so the enterprise plugins load with it | + +Upgrading a published app is a change to the artifact reference plus a restart +— no image rebuild. Rollback is the same operation with the previous URL, which +only works if the previous object still exists with the same bytes. That is a +property of how you publish, not of the runtime, so three rules go with the +mode: + +- **Publish immutable, version-named objects.** Never overwrite a published + artifact and never publish to a moving name. A mutable name means the running + app can change with no deployment event, makes rollback impossible, and + destroys the audit answer to "what was running at 14:05". +- **Give write access to the publishing pipeline only.** An artifact store + humans can write to is a production deploy path with no review on it. +- **Pin the digest in production.** The reference carries an optional + integrity pin; with one, a mismatch **refuses the boot** and names the + expected and the actual digest. Without one, the runtime boots whatever the + host returned and cannot tell a republished artifact from a substituted one. + +A `file://` reference exercises the same path with no artifact host, which +makes it the right way to rehearse a deployment — the production command then +differs from the rehearsed one in exactly one place. + +### Migrations on the artifact path + +"Upgrade the app" on this path is an environment change and a restart, with +nobody at a terminal at the moment schema and metadata can first disagree. So +this path — and only this one — applies safe schema changes automatically and +**refuses the boot on a destructive one**, naming every change and the command +that resolves it. Every other boot keeps the standing production policy, under +which the schema is never altered automatically. + +## Startup decisions the runtime will not guess + +Some configurations are checked when configuration is loaded and **refused** +rather than degraded. A refusal prints a fatal error naming the settings that +disagree, and exits. + +- **Licence mode and cloud posture are coupled.** An ordinary licence is + validated online against a control plane; an air-gap licence is verified + locally with no network traffic. Pairing an ordinary licence with "no control + plane" is impossible, not degraded, and is refused before any validation is + attempted. [Air-gapped](/docs/deploy/air-gapped) carries the full matrix. +- **Leaving the cloud posture unset is not "no cloud".** Unset resolves to the + *public* control plane. A deployment meant to talk to nobody has to say so + explicitly. +- **A multi-organization posture requires a licence**, and makes two further + decisions mandatory: what a new sign-up joins, and which AI agents are + mounted. Declaring either available value is accepted; not deciding is not. A + single-organization deployment sees neither check. +- **A cluster driver makes one shared secret key mandatory** on every replica. + Without a cluster driver each replica mints its own; across replicas those + would silently diverge, so the runtime refuses to start instead. + +## Connecting to a control plane + +A control plane is what serves the marketplace catalog and validates an +ordinary licence. Connecting is a **binding**, not a pasted credential: the +deployment is bound to the control plane once, and the runtime persists the +token it was issued and presents that on every later call. There is no +deployment API key to distribute or rotate by hand. + +A bound, cloud-connected deployment is still a single-environment deployment. +Connecting to a control plane does not turn one deployment into many. + +## Database + +In production, point the deployment at a **managed** database and remove the +bundled database service from the stack. The bundled one exists so that a first +run works; it is not a production posture, and container-local storage is not +where business data belongs. + +The driver is inferred from the connection URL's scheme. Override it explicitly +only when the scheme cannot carry that information — an unsupported value fails +rather than falling back to a guess. + +The shipped stack runs schema migration as a **one-shot step that completes +before any application replica starts**, so concurrent replicas never run +schema changes against each other. Any other orchestrator has to reproduce that +ordering. See [Data Sources](/docs/configure/data-sources) for declaring +additional datasources, and [Backup](/docs/operate/backup) for the restore +side. ## Authentication secret -Set a strong base secret: - -```bash -OS_AUTH_SECRET=replace-with-a-strong-random-secret -``` - -ObjectOS derives per-project auth secrets from this value. That keeps -session signing isolated per project while still allowing deterministic -restarts. Rotating this value invalidates existing sessions. - -## Kernel and artifact caches - -ObjectOS caches resolved environments and project kernels to avoid -rebuilding a kernel for every request. - -| Variable | Default | Purpose | -|---|---:|---| -| `OS_KERNEL_CACHE_SIZE` | `32` | Maximum number of cached project kernels | -| `OS_KERNEL_TTL_MS` | `900000` | Idle TTL for cached kernels | -| `OS_ENV_CACHE_TTL_MS` | `300000` | Hostname/environment resolution cache | -| `OS_ARTIFACT_CACHE_TTL_MS` | `300000` | Artifact response cache | - -Lower TTLs make changes visible faster. Higher TTLs reduce control-plane -traffic and cold starts. - -## Database configuration - -In cloud-connected mode, the control plane returns the per-project -runtime database configuration with the artifact response. - -In file-backed mode, ObjectOS can derive database settings from the -artifact's datasource declarations. Supported framework drivers include -SQLite, PostgreSQL, MySQL, MongoDB, and memory-backed evaluation -drivers. - -For production, use a customer-managed database. Do not rely on -container-local storage for business data unless the deployment is -explicitly a single-node evaluation. +Sessions are signed from a base secret, and it must be **identical on every +replica**. Rotating it invalidates every existing session, and it also orphans +the stored signing key — so a rotation is a planned operation, not a +configuration tweak — the deploy bundle's template states the one extra step a +rotation needs. Keep the secret in a secret manager, never in an image. diff --git a/content/docs/configure/runtime.zh-Hans.mdx b/content/docs/configure/runtime.zh-Hans.mdx deleted file mode 100644 index d494830..0000000 --- a/content/docs/configure/runtime.zh-Hans.mdx +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: 运行时配置 -description: 配置 artifact 加载、项目解析、数据库、缓存以及运行时 secret。 ---- - -ObjectOS 的运行时配置回答三个问题： - -1. 该请求应服务于哪个项目？ -2. 已编译的 artifact 在哪里？ -3. 该项目应使用哪个数据库与哪些运行时服务？ - -## 启动模式 - -| 模式 | 适用场景 | 关键配置 | -|---|---|---| -| Standalone | 无配置直接执行 `os start` —— 快速演示、空 kernel、约 23 个插件、本地 SQLite 位于 `~/.objectstack/data/standalone.db` | _无_（使用默认） | -| File-backed | 单项目、演示、客户离线包、内网/离线部署 | `OS_ARTIFACT_FILE` | -| Cloud-connected | 托管或私有控制面发布项目 artifact | `OS_CLOUD_URL`、`OS_PROJECT_ID` 或主机名解析 | - -### Standalone 模式 - -在无配置或 artifact 的情况下执行 `os start` 时的默认行为。ObjectOS 启动一个空 kernel，加载平台插件（`auth`、`security`、`audit`、`storage`、`webhooks`、`mcp-server`、`marketplace-proxy`、`marketplace-install-local` ……），打开 `~/.objectstack/data/standalone.db` 的本地 SQLite，并提供 Console 与 Account。 - -从 Console 的 marketplace 标签页安装应用即可在 kernel 中填充对象、视图和流程 —— 无需重建、无需重启。适合演示、评估以及"看看这玩意能干啥"的探索。 - -`os start` 会自动升级： - -| 检测到 | 行为 | -|---|---| -| 什么都没有 | Standalone 模式（如上） | -| 当前目录有 `objectstack.config.ts` | Project 模式 —— 自动编译，`HOME=/.objectstack` | -| 当前目录有已编译 artifact | Artifact 模式 —— 加载该 artifact | -| 显式 `--artifact ` 或 `OS_CLOUD_URL` | File-backed / cloud-connected 模式 | - -## File-backed 模式 - -设置： - -```bash -OS_ARTIFACT_FILE=/artifacts/objectstack.json -``` - -ObjectOS 使用本地 Artifact API 客户端。所有主机名都解析到同一个项目。运行时配置在 artifact 中存在时从其中读取，否则回退到本地默认值用于评估。 - -`OS_ARTIFACT_FILE` 是 ObjectOS app-wrapper 的约定。底层运行时也直接接受 `OS_ARTIFACT_PATH`（被 `@objectstack/cli` 的 `dev` 和 `start` 命令以及框架的 standalone stack 使用）。两者设置其一即可——不要同时设置。 - -可选： - -```bash -OS_ENVIRONMENT_ID=env_prod # 或旧别名 OS_PROJECT_ID -OS_WATCH_ARTIFACT=1 -``` - -watch 模式仅用于开发或冒烟测试。 - -## Cloud-connected 模式 - -设置： - -```bash -OS_CLOUD_URL=https://cloud.example.com -OS_CLOUD_API_KEY=replace-with-deployment-token -``` - -ObjectOS 请求控制面： - -- 把主机名解析为项目/环境； -- 拉取当前 artifact； -- 接收该项目的运行时数据库配置。 - -ObjectOS 不应直接连接控制面数据库。 - -## 认证 secret - -设置一个强随机基础 secret： - -```bash -OS_AUTH_SECRET=replace-with-a-strong-random-secret -``` - -ObjectOS 由此派生每个项目的认证 secret。这样会话签名按项目隔离，同时仍可在重启后保持。轮换该值会使现有会话失效。 - -## Kernel 与 artifact 缓存 - -ObjectOS 缓存已解析的环境和项目 kernel，避免每次请求都重建 kernel。 - -| 变量 | 默认值 | 用途 | -|---|---:|---| -| `OS_KERNEL_CACHE_SIZE` | `32` | 缓存的项目 kernel 最大数 | -| `OS_KERNEL_TTL_MS` | `900000` | 缓存 kernel 的空闲 TTL | -| `OS_ENV_CACHE_TTL_MS` | `300000` | 主机名/环境解析缓存 | -| `OS_ARTIFACT_CACHE_TTL_MS` | `300000` | Artifact 响应缓存 | - -更低的 TTL 让变更更快可见；更高的 TTL 降低控制面流量和冷启动。 - -## 数据库配置 - -在 cloud-connected 模式下，控制面把每个项目的运行时数据库配置随 artifact 响应一起返回。 - -在 file-backed 模式下，ObjectOS 可以根据 artifact 的数据源声明派生数据库设置。支持的框架驱动包括 SQLite、PostgreSQL、MySQL、MongoDB 以及内存评估驱动。 - -生产环境请使用客户托管的数据库。不要把业务数据放在容器本地存储中，除非该部署明确是单节点评估。 diff --git a/content/docs/operate/backup.de.mdx b/content/docs/operate/backup.de.mdx deleted file mode 100644 index dbdd44e..0000000 --- a/content/docs/operate/backup.de.mdx +++ /dev/null @@ -1,165 +0,0 @@ ---- -title: Backup und Disaster Recovery -description: Was gesichert werden muss, wie wiederhergestellt wird und wie man für den Ausfall plant. ---- - -ObjectOS selbst ist zustandslos — die Laufzeitumgebung kann aus dem -Container-Image neu aufgebaut werden. **Bei Backups geht es um die Daten, -von denen ObjectOS abhängt, nicht um ObjectOS selbst.** Planen Sie die -Wiederherstellung rund um diese Datensätze. - -## Was gesichert werden muss - -| Asset | Verantwortlich | Backup-Strategie | -|---|---|---| -| Geschäftsdatenbank | Kunde | Datenbank-native Sicherung (PITR für Managed Services); Wiederherstellung vierteljährlich testen | -| Kompiliertes Artefakt (`objectstack.json`) | Anwendungs-/Release-Team | Jedes veröffentlichte Artefakt in unveränderlichem Speicher ablegen; niemals überschreiben | -| Secrets-Baseline | Secret-Manager des Kunden | Anbieter-native Sicherung; Rotationsintervall gemäß Richtlinie | -| Objekt-/Dateispeicher (wenn die `storage`-Capability aktiviert ist) | Kunde | Bucket-Versionierung + bei Bedarf regionsübergreifende Replikation | -| Vom Kunden verwalteter Identitätsanbieter | IdP-Anbieter | Anbieter-native | - -ObjectOS benötigt **kein** separates Backup seines Container-Dateisystems. -Cache-Verzeichnisse (`OS_CACHE_DIR`) sind neu aufbaubar. - -## Datenbank-Backups - -Passen Sie die Strategie an den Treiber an: - -| Treiber | Empfohlener Ansatz | -|---|---| -| PostgreSQL | Kontinuierliches WAL-Archiving + Base-Backup; Point-in-Time-Wiederherstellung | -| MySQL | Binärlog-Archiving + vollständiger Dump; Point-in-Time-Wiederherstellung | -| MongoDB | Replica-Set-Snapshots; Oplog für PITR | -| SQLite (Single-Node / Desktop) | WAL-Modus + Hot-Snapshots über `VACUUM INTO` oder die Online Backup API; optional Litestream für kontinuierliche Replikation — siehe [SQLite-Deployments](#sqlite-deployments) unten | - -Validieren Sie unabhängig vom Treiber, dass: - -- Backups innerhalb des RPO des Kunden abgeschlossen werden; -- eine frische Datenbank ObjectOS aus demselben Artefakt starten und - Traffic bedienen kann; -- Wiederherstellungstests mindestens einmal pro Quartal durchgängig - durchgeführt werden. - -## SQLite-Deployments - -SQLite ist der Standardtreiber und eine legitime Produktionswahl für -**Single-Node**-ObjectOS — Desktop-Apps, interne Tools für ein kleines -Team, Edge-/On-Prem-Appliances, Evaluierungsumgebungen. Der Kompromiss -ist struktureller Natur: SQLite ist ein Single-Writer und eignet sich -daher nicht für Multi-Node-ObjectOS, hohen gleichzeitigen Schreibdurchsatz -oder Deployments mit gemeinsam genutzter Datenbank. Verwenden Sie dafür -PostgreSQL. - -Wenn Sie SQLite in der Produktion betreiben, gehören die Konfiguration, -die es sicher macht, und das Backup-Rezept zusammen: - -**Laufzeitkonfiguration** - -- WAL aktivieren: `PRAGMA journal_mode=WAL` (Leser blockieren den - Schreiber nicht; absturzsicher). -- `PRAGMA synchronous=NORMAL` ist der übliche Desktop-/Single-Node-Standard - — sicher mit WAL, deutlich schneller als `FULL`. -- Halten Sie die Datenbankdatei auf **lokalem Datenträger**. Legen Sie sie - **nicht** auf NFS, SMB oder in einen von Dropbox / OneDrive / iCloud - synchronisierten Ordner, während die Laufzeitumgebung läuft — die - Sperrmechanismen von SQLite sind dort unzuverlässig, und dies ist die - häufigste Ursache für die Beschädigung von SQLite-Deployments. - -**Hot-Snapshot (ohne Ausfallzeit)** - -Die Laufzeitumgebung bedient weiterhin Traffic, während Sie mit der -Online Backup API von SQLite oder `VACUUM INTO` einen Snapshot erstellen: - -```sql -VACUUM INTO '/var/backups/objectos/db-2026-05-27T13-00Z.sqlite'; -``` - -Planen Sie ihn (cron, systemd-Timer oder der In-Process-Scheduler) in -einem Intervall, das Ihrem RPO entspricht. Versehen Sie jeden Snapshot mit -der Artefaktversion, die ihn erzeugt hat, damit Sie Datenbank + Artefakt -gemeinsam zurückrollen können (siehe [Artefakt-Versionierung](#artifact-versioning) -unten). - -**Externe Kopie** - -Ein lokaler Snapshot übersteht keinen Datenträgerverlust. Übertragen Sie -jeden Snapshot in dauerhaften Speicher: - -- Server / VM: in S3 oder einen beliebigen S3-kompatiblen Bucket übertragen - (Sie haben wahrscheinlich bereits einen für die `storage`-Capability - konfiguriert). -- Desktop-App: den Snapshot in einen vom Benutzer kontrollierten - Sync-Ordner schreiben (OneDrive / iCloud / Google Drive) — hier - akzeptabel, weil die Snapshot-Datei **geschlossen und unveränderlich** - ist, anders als die Live-Datenbank. - -**Kontinuierliche Replikation (niedrigeres RPO)** - -Für ein RPO im Sekundenbereich, ohne SQLite aufzugeben, betreiben Sie -[Litestream](https://litestream.io) neben dem ObjectOS-Prozess. Es streamt -das WAL in S3-kompatiblen Speicher und unterstützt -Point-in-Time-Wiederherstellung. Dies ist der empfohlene Weg, wenn ein -Single-Node-SQLite-Deployment einen nahezu verlustfreien Betrieb benötigt. - -**Wiederherstellung** - -Stoppen Sie die Laufzeitumgebung, ersetzen Sie die Datenbankdatei durch -den gewählten Snapshot (oder führen Sie `litestream restore` aus) und -starten Sie die Laufzeitumgebung gegen dieselbe Artefaktversion, die den -Snapshot erzeugt hat. - -## Artefakt-Versionierung - -Behandeln Sie veröffentlichte Artefakte als unveränderlich. Versehen Sie -jedes Artefakt mit der Release-ID, die zum Kompilieren verwendet wurde -(z. B. `objectstack-2026-05-24.json`). Eine Wiederherstellung in einen -bekannten guten Geschäftszustand bedeutet in der Regel: - -1. Stellen Sie die Datenbank auf den gewählten Zeitpunkt wieder her. -2. Verweisen Sie ObjectOS erneut auf die Artefaktversion, die zu diesem - Zeitpunkt aktiv war. -3. Starten Sie die Laufzeitumgebung neu. - -Wenn Sie Artefakte direkt überschreiben, verlieren Sie die Möglichkeit, -sauber zurückzurollen — selbst wenn das Datenbank-Backup einwandfrei ist. - -## RPO-/RTO-Planung - -Ein praktikables Ausgangsziel für Kunden-Deployments: - -| Klasse | RPO | RTO | Hinweise | -|---|---|---|---| -| Evaluierung / Demo | nach bestem Bemühen | nach bestem Bemühen | SQLite-Snapshot ist ausreichend | -| Desktop-App / Single-Node für kleines Team | ≤ 1 Stunde (Snapshots) oder ≤ Sekunden (Litestream) | Minuten | SQLite + WAL + geplantes `VACUUM INTO` + externe Kopie | -| Single-Tenant-Produktion | ≤ 15 Min | ≤ 1 Stunde | Managed PostgreSQL mit PITR + Warm-Image | -| Multi-Tenant / reguliert | ≤ 5 Min | ≤ 30 Min | HA-Datenbank + Multi-AZ-ObjectOS + getestetes Runbook | - -Engere Ziele erfordern Plattformänderungen außerhalb des -ObjectOS-Containers selbst (HA-Datenbank, Multi-AZ-Ingress, -Warm-Replicas). - -## Ausfallszenarien, die das Üben wert sind - -- **Datenbank über einen langen Zeitraum nicht verfügbar.** Stellen Sie - sicher, dass die Laufzeitumgebung einen klaren 503 ausgibt und dass - Probes Pods korrekt als ungesund markieren. -- **Artefakt-Regression.** Rollen Sie den Artefakt-Zeiger zurück; die - Daten sind nicht betroffen. -- **Secret-Rotation.** Die Rotation von `AUTH_SECRET` macht jede Session - ungültig. Führen Sie sie während eines Wartungsfensters durch oder - staffeln Sie sie über die Replicas. -- **Regionsausfall.** Wenn der Kunde ein regionsübergreifendes Failover - benötigt, müssen die Geschäftsdatenbank, der Secret-Manager und der - Ingress alle regionsübergreifend ausgelegt sein. ObjectOS selbst kann - überall dort laufen, wo das Image verfügbar ist. - -## Was im Runbook festgehalten werden sollte - -- Backup-Zeitplan, Aufbewahrung und On-Call-Kontakt für jeden Datensatz. -- Schritt-für-Schritt-Wiederherstellungsprozedur (zuerst Datenbank, dann - Artefakt, dann ObjectOS starten). -- Verifizierungsabfragen, um zu bestätigen, dass die wiederhergestellte - Datenbank konsistent ist. -- Rollback-Plan für ObjectOS-Image und Artefaktversion (siehe - [Upgrade und Rollback](/docs/operate/upgrade)). -- Kommunikationsvorlage für kundensichtbare Vorfälle. diff --git a/content/docs/operate/backup.es.mdx b/content/docs/operate/backup.es.mdx deleted file mode 100644 index 0c4a53b..0000000 --- a/content/docs/operate/backup.es.mdx +++ /dev/null @@ -1,165 +0,0 @@ ---- -title: Copias de seguridad y recuperación ante desastres -description: Qué respaldar, cómo restaurar y cómo planificar ante fallos. ---- - -ObjectOS en sí mismo es stateless: el runtime puede reconstruirse a partir -de la imagen del contenedor. **Las copias de seguridad tratan sobre los -datos de los que ObjectOS depende, no sobre ObjectOS en sí.** Planifica la -recuperación en torno a esos conjuntos de datos. - -## Qué respaldar - -| Activo | Propiedad de | Estrategia de copia de seguridad | -|---|---|---| -| Base de datos de negocio | Cliente | Copia de seguridad nativa de la base de datos (PITR para servicios gestionados); prueba la restauración trimestralmente | -| Artefacto compilado (`objectstack.json`) | Equipo de aplicación/release | Almacena cada artefacto publicado en almacenamiento inmutable; nunca lo sobrescribas | -| Línea base de secretos | Gestor de secretos del cliente | Copia de seguridad nativa del proveedor; cadencia de rotación según la política | -| Almacenamiento de objetos/archivos (cuando la capacidad `storage` está habilitada) | Cliente | Versionado de buckets + replicación entre regiones si es necesario | -| Proveedor de identidad gestionado por el cliente | Proveedor del IdP | Nativo del proveedor | - -ObjectOS **no** requiere una copia de seguridad separada del sistema de -archivos de su contenedor. Los directorios de caché (`OS_CACHE_DIR`) se -pueden reconstruir. - -## Copias de seguridad de la base de datos - -Adapta la estrategia al driver: - -| Driver | Enfoque recomendado | -|---|---| -| PostgreSQL | Archivado continuo de WAL + base backup; restauración point-in-time | -| MySQL | Archivado de binary-log + volcado completo; restauración point-in-time | -| MongoDB | Snapshots del replica-set; oplog para PITR | -| SQLite (nodo único / escritorio) | Modo WAL + snapshots en caliente mediante `VACUUM INTO` o la Online Backup API; opcionalmente Litestream para replicación continua — consulta [Despliegues de SQLite](#sqlite-deployments) más abajo | - -Sea cual sea el driver, valida que: - -- las copias de seguridad se completen dentro del RPO del cliente; -- una base de datos nueva pueda arrancar ObjectOS desde el mismo artefacto - y atender tráfico; -- las pruebas de restauración se ejerciten de extremo a extremo al menos - una vez por trimestre. - -## Despliegues de SQLite - -SQLite es el driver por defecto y es una elección de producción legítima -para ObjectOS de **nodo único**: aplicaciones de escritorio, herramientas -internas para un equipo pequeño, dispositivos edge / on-prem, entornos de -evaluación. La contrapartida es estructural: SQLite es de un único escritor, -por lo que no encaja con ObjectOS multinodo, alto rendimiento de escritura -concurrente ni despliegues de base de datos compartida. Para esos casos, -usa PostgreSQL. - -Cuando ejecutes SQLite en producción, la configuración que lo hace seguro y -la receta de copia de seguridad van de la mano: - -**Configuración del runtime** - -- Habilita WAL: `PRAGMA journal_mode=WAL` (los lectores no bloquean al - escritor; resistente a fallos). -- `PRAGMA synchronous=NORMAL` es el valor por defecto habitual en - escritorio/nodo único: seguro con WAL, mucho más rápido que `FULL`. -- Mantén el archivo de la base de datos en **disco local**. **No** lo - pongas en NFS, SMB ni dentro de una carpeta sincronizada por Dropbox / - OneDrive / iCloud mientras el runtime está en ejecución: el bloqueo de - SQLite es poco fiable en esos casos y esta es la forma más común en que - los despliegues de SQLite se corrompen. - -**Snapshot en caliente (sin tiempo de inactividad)** - -El runtime sigue atendiendo tráfico mientras tomas un snapshot usando la -Online Backup API de SQLite o `VACUUM INTO`: - -```sql -VACUUM INTO '/var/backups/objectos/db-2026-05-27T13-00Z.sqlite'; -``` - -Prográmalo (cron, systemd timer o el planificador in-process) a una -cadencia acorde con tu RPO. Etiqueta cada snapshot con la versión del -artefacto que lo produjo para poder revertir la base de datos + el -artefacto juntos (consulta [Versionado de artefactos](#artifact-versioning) -más abajo). - -**Copia externa** - -Un snapshot local no sobrevive a la pérdida del disco. Envía cada snapshot -a almacenamiento duradero: - -- Servidor / VM: envíalo a S3 o a cualquier bucket compatible con S3 - (probablemente ya tengas uno configurado para la capacidad `storage`). -- Aplicación de escritorio: escribe el snapshot en una carpeta de - sincronización controlada por el usuario (OneDrive / iCloud / Google - Drive) — aceptable aquí porque el archivo de snapshot está **cerrado e - inmutable**, a diferencia de la base de datos en vivo. - -**Replicación continua (RPO más bajo)** - -Para un RPO inferior al minuto sin renunciar a SQLite, ejecuta -[Litestream](https://litestream.io) junto al proceso de ObjectOS. Transmite -el WAL a almacenamiento compatible con S3 y admite restauración -point-in-time. Esta es la vía recomendada cuando un despliegue de SQLite de -nodo único necesita una pérdida de datos casi nula. - -**Restauración** - -Detén el runtime, reemplaza el archivo de la base de datos por el snapshot -elegido (o ejecuta `litestream restore`), e inicia el runtime contra la -misma versión de artefacto que produjo el snapshot. - -## Versionado de artefactos - -Trata los artefactos publicados como inmutables. Etiqueta cada artefacto -con el id de release usado para compilarlo (p. ej. -`objectstack-2026-05-24.json`). Recuperar un estado de negocio conocido y -correcto suele implicar: - -1. Restaurar la base de datos al punto en el tiempo elegido. -2. Reapuntar ObjectOS al artefacto que estaba en vivo en ese momento. -3. Reiniciar el runtime. - -Si sobrescribes los artefactos en su sitio, pierdes la capacidad de revertir -limpiamente incluso cuando la copia de seguridad de la base de datos es -perfecta. - -## Planificación de RPO/RTO - -Un objetivo de partida viable para los despliegues de clientes: - -| Clase | RPO | RTO | Notas | -|---|---|---|---| -| Evaluación / demo | mejor esfuerzo | mejor esfuerzo | Un snapshot de SQLite es suficiente | -| Aplicación de escritorio / nodo único de equipo pequeño | ≤ 1 hora (snapshots) o ≤ segundos (Litestream) | minutos | SQLite + WAL + `VACUUM INTO` programado + copia externa | -| Producción de un solo inquilino | ≤ 15 min | ≤ 1 hora | PostgreSQL gestionado con PITR + imagen en caliente | -| Multiinquilino / regulado | ≤ 5 min | ≤ 30 min | Base de datos HA + ObjectOS multi-AZ + runbook probado | - -Objetivos más estrictos requieren cambios de plataforma que están fuera del -propio contenedor de ObjectOS (base de datos HA, ingress multi-AZ, réplicas -en caliente). - -## Modos de fallo que vale la pena ensayar - -- **Base de datos no disponible durante una ventana prolongada.** Confirma - que el runtime expone un 503 claro y que las probes marcan correctamente - los pods como no saludables. -- **Regresión del artefacto.** Revierte el puntero del artefacto; los datos - no se ven afectados. -- **Rotación de secretos.** Rotar `AUTH_SECRET` invalida todas las - sesiones. Hazlo durante una ventana de mantenimiento o escalónalo entre - réplicas. -- **Caída de región.** Si el cliente requiere failover de región, la base - de datos de negocio, el gestor de secretos y el ingress deben ser todos - multirregión. ObjectOS en sí puede ejecutarse en cualquier lugar donde la - imagen esté disponible. - -## Qué documentar en el runbook - -- Calendario de copias de seguridad, retención y contacto de guardia para - cada conjunto de datos. -- Procedimiento de restauración paso a paso (primero la base de datos, - luego el artefacto, luego iniciar ObjectOS). -- Consultas de verificación para confirmar que la base de datos restaurada - es consistente. -- Plan de reversión tanto para la imagen de ObjectOS como para la versión - del artefacto (consulta [Actualización y reversión](/docs/operate/upgrade)). -- Plantilla de comunicación para incidentes visibles al cliente. diff --git a/content/docs/operate/backup.fr.mdx b/content/docs/operate/backup.fr.mdx deleted file mode 100644 index 7049c70..0000000 --- a/content/docs/operate/backup.fr.mdx +++ /dev/null @@ -1,168 +0,0 @@ ---- -title: Sauvegarde et reprise après sinistre -description: Quoi sauvegarder, comment restaurer et comment planifier les pannes. ---- - -ObjectOS est lui-même sans état — le runtime peut être reconstruit à -partir de l'image de conteneur. **Les sauvegardes concernent les données -dont dépend ObjectOS, et non ObjectOS lui-même.** Planifiez la reprise -autour de ces jeux de données. - -## Quoi sauvegarder - -| Actif | Détenu par | Stratégie de sauvegarde | -|---|---|---| -| Base de données métier | Client | Sauvegarde native de la base de données (PITR pour les services managés) ; tester la restauration chaque trimestre | -| Artefact compilé (`objectstack.json`) | Équipe applicative / de release | Stocker chaque artefact publié dans un stockage immuable ; ne jamais écraser | -| Référentiel des secrets | Gestionnaire de secrets du client | Sauvegarde native du fournisseur ; rotation selon la politique en vigueur | -| Stockage d'objets / de fichiers (lorsque la capacité `storage` est activée) | Client | Versionnage des buckets + réplication inter-régions si nécessaire | -| Fournisseur d'identité géré par le client | Fournisseur IdP | Native au fournisseur | - -ObjectOS **ne nécessite pas** de sauvegarde distincte de son système de -fichiers de conteneur. Les répertoires de cache (`OS_CACHE_DIR`) sont -reconstructibles. - -## Sauvegardes de base de données - -Adaptez la stratégie au driver : - -| Driver | Approche recommandée | -|---|---| -| PostgreSQL | Archivage continu du WAL + sauvegarde de base ; restauration à un instant précis | -| MySQL | Archivage du journal binaire + dump complet ; restauration à un instant précis | -| MongoDB | Snapshots du replica set ; oplog pour le PITR | -| SQLite (mononœud / poste de travail) | Mode WAL + snapshots à chaud via `VACUUM INTO` ou l'Online Backup API ; éventuellement Litestream pour une réplication continue — voir [Déploiements SQLite](#sqlite-deployments) ci-dessous | - -Quel que soit le driver, vérifiez que : - -- les sauvegardes s'achèvent dans le RPO du client ; -- une base de données neuve peut démarrer ObjectOS à partir du même - artefact et traiter le trafic ; -- les tests de restauration sont exécutés de bout en bout au moins une - fois par trimestre. - -## Déploiements SQLite - -SQLite est le driver par défaut et constitue un choix de production -légitime pour un ObjectOS **mononœud** — applications de bureau, outils -internes pour une petite équipe, appliances edge / on-prem, -environnements d'évaluation. Le compromis est structurel : SQLite -n'autorise qu'un seul rédacteur, il ne convient donc pas à un ObjectOS -multinœud, à un débit d'écriture concurrent élevé ou aux déploiements à -base de données partagée. Pour ces cas, utilisez PostgreSQL. - -Lorsque vous exécutez SQLite en production, la configuration qui le rend -sûr et la recette de sauvegarde vont de pair : - -**Configuration du runtime** - -- Activez le WAL : `PRAGMA journal_mode=WAL` (les lecteurs ne bloquent - pas le rédacteur ; résistant aux pannes). -- `PRAGMA synchronous=NORMAL` est la valeur par défaut habituelle pour - les postes de travail / mononœuds — sûre avec le WAL, bien plus rapide - que `FULL`. -- Conservez le fichier de base de données sur un **disque local**. Ne le - placez **pas** sur NFS, SMB, ni dans un dossier synchronisé par - Dropbox / OneDrive / iCloud pendant que le runtime est en cours - d'exécution — le verrouillage de SQLite n'est pas fiable dans ces cas, - et c'est la cause la plus fréquente de corruption des déploiements - SQLite. - -**Snapshot à chaud (sans interruption)** - -Le runtime continue de traiter le trafic pendant que vous prenez un -snapshot à l'aide de l'Online Backup API de SQLite ou de `VACUUM INTO` : - -```sql -VACUUM INTO '/var/backups/objectos/db-2026-05-27T13-00Z.sqlite'; -``` - -Planifiez-le (cron, timer systemd ou le planificateur in-process) à une -cadence correspondant à votre RPO. Étiquetez chaque snapshot avec la -version d'artefact qui l'a produit, afin de pouvoir restaurer ensemble -la base de données et l'artefact (voir [Versionnage des -artefacts](#artifact-versioning) ci-dessous). - -**Copie hors site** - -Un snapshot local ne survit pas à la perte du disque. Poussez chaque -snapshot vers un stockage durable : - -- Serveur / VM : poussez vers S3 ou tout bucket compatible S3 (vous en - avez probablement déjà un configuré pour la capacité `storage`). -- Application de bureau : écrivez le snapshot dans un dossier de - synchronisation contrôlé par l'utilisateur (OneDrive / iCloud / Google - Drive) — acceptable ici car le fichier de snapshot est **fermé et - immuable**, contrairement à la base de données active. - -**Réplication continue (RPO réduit)** - -Pour un RPO inférieur à la minute sans renoncer à SQLite, exécutez -[Litestream](https://litestream.io) aux côtés du processus ObjectOS. Il -diffuse le WAL vers un stockage compatible S3 et prend en charge la -restauration à un instant précis. C'est la voie recommandée lorsqu'un -déploiement SQLite mononœud exige une perte de données quasi nulle. - -**Restauration** - -Arrêtez le runtime, remplacez le fichier de base de données par le -snapshot choisi (ou exécutez `litestream restore`), démarrez le runtime -avec la même version d'artefact que celle ayant produit le snapshot. - -## Versionnage des artefacts - -Considérez les artefacts publiés comme immuables. Étiquetez chaque -artefact avec l'identifiant de release utilisé pour le compiler (par -exemple `objectstack-2026-05-24.json`). La reprise vers un état métier -sain implique généralement de : - -1. Restaurer la base de données à l'instant choisi. -2. Re-pointer ObjectOS vers la version d'artefact qui était active à ce - moment-là. -3. Redémarrer le runtime. - -Si vous écrasez les artefacts sur place, vous perdez la possibilité de -revenir en arrière proprement, même lorsque la sauvegarde de la base de -données est parfaite. - -## Planification RPO/RTO - -Un objectif de départ réaliste pour les déploiements clients : - -| Classe | RPO | RTO | Notes | -|---|---|---|---| -| Évaluation / démo | au mieux | au mieux | Un snapshot SQLite suffit | -| Application de bureau / mononœud petite équipe | ≤ 1 heure (snapshots) ou ≤ quelques secondes (Litestream) | minutes | SQLite + WAL + `VACUUM INTO` planifié + copie hors site | -| Production mono-locataire | ≤ 15 min | ≤ 1 heure | PostgreSQL managé avec PITR + image préchauffée | -| Multi-locataire / réglementé | ≤ 5 min | ≤ 30 min | Base de données HA + ObjectOS multi-AZ + runbook testé | - -Des objectifs plus stricts nécessitent des changements de plateforme -extérieurs au conteneur ObjectOS lui-même (base de données HA, ingress -multi-AZ, réplicas préchauffés). - -## Modes de défaillance à répéter - -- **Base de données indisponible sur une longue période.** Confirmez que - le runtime renvoie un 503 clair et que les sondes marquent - correctement les pods comme défaillants. -- **Régression d'artefact.** Revenez au pointeur d'artefact précédent ; - les données ne sont pas affectées. -- **Rotation de secret.** La rotation de `AUTH_SECRET` invalide toutes - les sessions. Effectuez-la pendant une fenêtre de maintenance ou - échelonnez-la entre les réplicas. -- **Panne de région.** Si le client exige un basculement de région, la - base de données métier, le gestionnaire de secrets et l'ingress - doivent tous être inter-régions. ObjectOS lui-même peut s'exécuter - partout où l'image est disponible. - -## Que consigner dans le runbook - -- Calendrier de sauvegarde, rétention et contact d'astreinte pour chaque - jeu de données. -- Procédure de restauration étape par étape (base de données d'abord, - puis artefact, puis démarrage d'ObjectOS). -- Requêtes de vérification pour confirmer que la base de données - restaurée est cohérente. -- Plan de rollback à la fois pour l'image ObjectOS et la version - d'artefact (voir [Mise à niveau et rollback](/docs/operate/upgrade)). -- Modèle de communication pour les incidents visibles par les clients. diff --git a/content/docs/operate/backup.ja.mdx b/content/docs/operate/backup.ja.mdx deleted file mode 100644 index a0af361..0000000 --- a/content/docs/operate/backup.ja.mdx +++ /dev/null @@ -1,154 +0,0 @@ ---- -title: バックアップと災害復旧 -description: 何をバックアップし、どう復元し、障害にどう備えるか。 ---- - -ObjectOS 自体はステートレスであり、ランタイムはコンテナイメージから -再構築できます。**バックアップの対象は ObjectOS が依存するデータであり、 -ObjectOS 自体ではありません。** 復旧計画はそれらのデータセットを中心に -立てましょう。 - -## 何をバックアップするか - -| アセット | 所有者 | バックアップ戦略 | -|---|---|---| -| 業務データベース | 顧客 | データベースネイティブのバックアップ（マネージドサービスでは PITR）。四半期ごとに復元をテストする | -| コンパイル成果物（`objectstack.json`） | アプリケーション/リリースチーム | 公開した成果物はすべてイミュータブルストレージに保存し、決して上書きしない | -| シークレットのベースライン | 顧客のシークレットマネージャー | ベンダーネイティブのバックアップ。ポリシーに従ってローテーション頻度を設定する | -| オブジェクト/ファイルストレージ（`storage` 機能が有効な場合） | 顧客 | バケットのバージョニング + 必要に応じてクロスリージョンレプリケーション | -| 顧客管理の ID プロバイダー | IdP ベンダー | ベンダーネイティブ | - -ObjectOS はコンテナファイルシステムの個別バックアップを**必要としません**。 -キャッシュディレクトリ（`OS_CACHE_DIR`）は再構築可能です。 - -## データベースのバックアップ - -戦略はドライバーに合わせます。 - -| ドライバー | 推奨アプローチ | -|---|---| -| PostgreSQL | 継続的な WAL アーカイブ + ベースバックアップ。ポイントインタイムリストア | -| MySQL | バイナリログのアーカイブ + フルダンプ。ポイントインタイムリストア | -| MongoDB | レプリカセットのスナップショット。PITR 用に oplog | -| SQLite（単一ノード / デスクトップ） | WAL モード + `VACUUM INTO` または Online Backup API によるホットスナップショット。必要に応じて継続的レプリケーションには Litestream を使用 — 後述の [SQLite デプロイ](#sqlite-deployments) を参照 | - -どのドライバーであっても、次の点を検証してください。 - -- バックアップが顧客の RPO 内に完了すること。 -- 新しいデータベースが同じ成果物から ObjectOS を起動し、 - トラフィックを処理できること。 -- 復元テストが少なくとも四半期に一度はエンドツーエンドで実施されること。 - -## SQLite デプロイ - -SQLite はデフォルトのドライバーであり、**単一ノード**の ObjectOS にとって -正当な本番選択肢です — デスクトップアプリ、小規模チーム向けの社内ツール、 -エッジ / オンプレミスのアプライアンス、評価環境などです。トレードオフは -構造的なもので、SQLite は単一ライターであるため、マルチノードの ObjectOS、 -高い同時書き込みスループット、共有データベースのデプロイには適しません。 -そうしたケースでは PostgreSQL を使用してください。 - -本番で SQLite を実行する場合、安全性を確保する構成とバックアップの -レシピは一体です。 - -**ランタイム構成** - -- WAL を有効にする: `PRAGMA journal_mode=WAL`（リーダーがライターを - ブロックせず、クラッシュセーフ）。 -- `PRAGMA synchronous=NORMAL` は通常のデスクトップ/単一ノードの - デフォルトです — WAL と組み合わせれば安全で、`FULL` よりはるかに高速です。 -- データベースファイルは**ローカルディスク**に置いてください。ランタイムの - 実行中に、NFS、SMB、または Dropbox / OneDrive / iCloud で同期される - フォルダの内部には置か**ないでください** — SQLite のロックはそれらでは - 信頼できず、これが SQLite デプロイで最もよく見られる破損の原因です。 - -**ホットスナップショット（ダウンタイムなし）** - -ランタイムはトラフィックを処理し続けながら、SQLite の Online Backup API -または `VACUUM INTO` を使ってスナップショットを取得します。 - -```sql -VACUUM INTO '/var/backups/objectos/db-2026-05-27T13-00Z.sqlite'; -``` - -RPO に合わせた頻度でスケジュールします（cron、systemd タイマー、または -プロセス内スケジューラ）。各スナップショットには、それを生成した成果物 -バージョンのタグを付け、データベースと成果物をまとめてロールバックできる -ようにします（後述の [成果物のバージョニング](#artifact-versioning) を参照）。 - -**オフサイトコピー** - -ローカルスナップショットはディスク喪失に耐えられません。各スナップショットを -耐久性のあるストレージにプッシュしてください。 - -- サーバー / VM: S3 または任意の S3 互換バケットにプッシュ（おそらく - `storage` 機能用にすでに 1 つ構成済みでしょう）。 -- デスクトップアプリ: スナップショットをユーザーが管理する同期フォルダ - （OneDrive / iCloud / Google Drive）に書き込みます — スナップショット - ファイルは**クローズされたイミュータブル**なもので、稼働中のデータベースとは - 異なるため、ここでは許容されます。 - -**継続的レプリケーション（より低い RPO）** - -SQLite を手放さずにサブ分の RPO を実現するには、ObjectOS プロセスと並行して -[Litestream](https://litestream.io) を実行します。WAL を S3 互換ストレージに -ストリーミングし、ポイントインタイムリストアをサポートします。単一ノードの -SQLite デプロイでほぼゼロのデータ損失が必要な場合の推奨パスです。 - -**復元** - -ランタイムを停止し、データベースファイルを選択したスナップショットで -置き換え（または `litestream restore` を実行）、そのスナップショットを -生成したのと同じ成果物バージョンに対してランタイムを起動します。 - -## 成果物のバージョニング - -公開した成果物はイミュータブルとして扱います。各成果物には、それを -コンパイルするために使用したリリース ID のタグを付けます -（例: `objectstack-2026-05-24.json`）。既知の正常な業務状態への復旧は、 -通常次のことを意味します。 - -1. データベースを選択した時点まで復元する。 -2. その時点で稼働していた成果物バージョンに ObjectOS を再び向ける。 -3. ランタイムを再起動する。 - -成果物をその場で上書きすると、データベースのバックアップが完璧であっても、 -きれいにロールバックする能力を失います。 - -## RPO/RTO の計画 - -顧客デプロイで実現可能な出発点としての目標値: - -| クラス | RPO | RTO | 備考 | -|---|---|---|---| -| 評価 / デモ | ベストエフォート | ベストエフォート | SQLite スナップショットで十分 | -| デスクトップアプリ / 小規模チームの単一ノード | ≤ 1 時間（スナップショット）または ≤ 数秒（Litestream） | 数分 | SQLite + WAL + スケジュールされた `VACUUM INTO` + オフサイトコピー | -| シングルテナント本番 | ≤ 15 分 | ≤ 1 時間 | PITR を備えたマネージド PostgreSQL + ウォームイメージ | -| マルチテナント / 規制対象 | ≤ 5 分 | ≤ 30 分 | HA データベース + マルチ AZ の ObjectOS + テスト済みランブック | - -より厳しい目標値には、ObjectOS コンテナ自体の外側にあるプラットフォーム -変更（HA データベース、マルチ AZ イングレス、ウォームレプリカ）が必要です。 - -## リハーサルする価値のある障害モード - -- **データベースが長時間利用不能。** ランタイムが明確な 503 を返し、 - プローブが Pod を正しく不健全とマークすることを確認します。 -- **成果物のリグレッション。** 成果物ポインタをロールバックします。 - データは影響を受けません。 -- **シークレットのローテーション。** `AUTH_SECRET` をローテーションすると、 - すべてのセッションが無効になります。メンテナンスウィンドウ中に実行するか、 - レプリカ間でずらして行います。 -- **リージョン障害。** 顧客がリージョンフェイルオーバーを必要とする場合、 - 業務データベース、シークレットマネージャー、イングレスのすべてが - クロスリージョンである必要があります。ObjectOS 自体はイメージが利用可能な - 場所であればどこでも実行できます。 - -## ランブックに記載すべき内容 - -- 各データセットのバックアップスケジュール、保持期間、オンコール連絡先。 -- ステップバイステップの復元手順（最初にデータベース、次に成果物、 - 最後に ObjectOS の起動）。 -- 復元したデータベースの整合性を確認する検証クエリ。 -- ObjectOS イメージと成果物バージョンの両方のロールバック計画 - （[アップグレードとロールバック](/docs/operate/upgrade) を参照）。 -- 顧客に見える障害のためのコミュニケーションテンプレート。 diff --git a/content/docs/operate/backup.ko.mdx b/content/docs/operate/backup.ko.mdx deleted file mode 100644 index 2e5dce4..0000000 --- a/content/docs/operate/backup.ko.mdx +++ /dev/null @@ -1,153 +0,0 @@ ---- -title: 백업 및 재해 복구 -description: 무엇을 백업하고, 어떻게 복원하며, 장애에 어떻게 대비할 것인가. ---- - -ObjectOS 자체는 상태를 저장하지 않습니다(stateless). 런타임은 컨테이너 -이미지로부터 재구축할 수 있습니다. **백업은 ObjectOS 자체가 아니라 -ObjectOS가 의존하는 데이터에 관한 것입니다.** 복구는 이러한 데이터셋을 -중심으로 계획하세요. - -## 무엇을 백업할 것인가 - -| 자산 | 소유 주체 | 백업 전략 | -|---|---|---| -| 비즈니스 데이터베이스 | 고객 | 데이터베이스 네이티브 백업(관리형 서비스의 경우 PITR), 분기마다 복원 테스트 수행 | -| 컴파일된 아티팩트(`objectstack.json`) | 애플리케이션/릴리스 팀 | 게시된 모든 아티팩트를 변경 불가능한 스토리지에 저장, 절대 덮어쓰지 않음 | -| 시크릿 기준선 | 고객의 시크릿 관리자 | 벤더 네이티브 백업, 정책에 따른 교체 주기 | -| 객체/파일 스토리지(`storage` 기능이 활성화된 경우) | 고객 | 버킷 버전 관리 + 필요 시 리전 간 복제 | -| 고객이 관리하는 ID 공급자 | IdP 벤더 | 벤더 네이티브 | - -ObjectOS는 컨테이너 파일시스템에 대한 별도의 백업을 **요구하지 -않습니다**. 캐시 디렉터리(`OS_CACHE_DIR`)는 재구축이 가능합니다. - -## 데이터베이스 백업 - -전략을 드라이버에 맞추세요: - -| 드라이버 | 권장 접근 방식 | -|---|---| -| PostgreSQL | 지속적인 WAL 아카이빙 + 베이스 백업, 시점 복원(point-in-time restore) | -| MySQL | 바이너리 로그 아카이빙 + 전체 덤프, 시점 복원 | -| MongoDB | 레플리카 세트 스냅샷, PITR를 위한 oplog | -| SQLite(단일 노드 / 데스크톱) | WAL 모드 + `VACUUM INTO` 또는 Online Backup API를 통한 핫 스냅샷, 필요 시 Litestream으로 지속적 복제 — 아래 [SQLite 배포](#sqlite-deployments) 참조 | - -드라이버와 관계없이 다음을 검증하세요: - -- 백업이 고객의 RPO 내에 완료되는지, -- 동일한 아티팩트로 새 데이터베이스에서 ObjectOS를 부팅하여 트래픽을 - 처리할 수 있는지, -- 복원 테스트가 적어도 분기에 한 번 엔드 투 엔드로 수행되는지. - -## SQLite 배포 - -SQLite는 기본 드라이버이며 **단일 노드** ObjectOS — 데스크톱 앱, -소규모 팀용 내부 도구, 엣지 / 온프레미스 어플라이언스, 평가 환경 — 에서 -정당한 프로덕션 선택지입니다. 트레이드오프는 구조적입니다. SQLite는 -단일 쓰기(single-writer)이므로 멀티 노드 ObjectOS, 높은 동시 쓰기 -처리량, 또는 공유 데이터베이스 배포에는 적합하지 않습니다. 그러한 -경우에는 PostgreSQL을 사용하세요. - -SQLite를 프로덕션에서 실행할 때는, 안전하게 만드는 구성과 백업 -레시피가 함께 갑니다: - -**런타임 구성** - -- WAL 활성화: `PRAGMA journal_mode=WAL`(리더가 라이터를 차단하지 않으며, - 크래시에 안전함). -- `PRAGMA synchronous=NORMAL`은 일반적인 데스크톱/단일 노드 기본값입니다 — - WAL과 함께 사용하면 안전하고 `FULL`보다 훨씬 빠릅니다. -- 데이터베이스 파일은 **로컬 디스크**에 두세요. 런타임이 실행 중인 동안에는 - NFS, SMB, 또는 Dropbox / OneDrive / iCloud로 동기화되는 폴더 안에 - **두지 마세요** — 이러한 환경에서는 SQLite의 잠금이 불안정하며, 이것이 - SQLite 배포가 손상되는 가장 흔한 원인입니다. - -**핫 스냅샷(다운타임 없음)** - -런타임은 SQLite의 Online Backup API 또는 `VACUUM INTO`를 사용하여 -스냅샷을 찍는 동안에도 트래픽을 계속 처리합니다: - -```sql -VACUUM INTO '/var/backups/objectos/db-2026-05-27T13-00Z.sqlite'; -``` - -RPO에 맞는 주기로(cron, systemd 타이머, 또는 인프로세스 스케줄러) -이를 예약하세요. 각 스냅샷에 이를 생성한 아티팩트 버전을 태그하여 -데이터베이스와 아티팩트를 함께 롤백할 수 있도록 하세요 -(아래 [아티팩트 버전 관리](#artifact-versioning) 참조). - -**오프사이트 복사본** - -로컬 스냅샷은 디스크 손실에서 살아남지 못합니다. 각 스냅샷을 내구성 -있는 스토리지로 푸시하세요: - -- 서버 / VM: S3 또는 S3 호환 버킷으로 푸시하세요(이미 `storage` 기능을 - 위해 하나 구성되어 있을 가능성이 높습니다). -- 데스크톱 앱: 스냅샷을 사용자가 제어하는 동기화 폴더(OneDrive / - iCloud / Google Drive)에 기록하세요 — 스냅샷 파일은 라이브 - 데이터베이스와 달리 **닫혀 있고 변경 불가능**하므로 여기서는 - 허용됩니다. - -**지속적 복제(낮은 RPO)** - -SQLite를 포기하지 않으면서 1분 미만의 RPO를 원한다면, ObjectOS 프로세스와 -함께 [Litestream](https://litestream.io)을 실행하세요. WAL을 S3 호환 -스토리지로 스트리밍하고 시점 복원을 지원합니다. 단일 노드 SQLite 배포가 -거의 제로에 가까운 데이터 손실을 필요로 할 때 권장되는 방법입니다. - -**복원** - -런타임을 중지하고, 데이터베이스 파일을 선택한 스냅샷으로 교체한 뒤 -(또는 `litestream restore` 실행), 해당 스냅샷을 생성한 동일한 아티팩트 -버전으로 런타임을 시작하세요. - -## 아티팩트 버전 관리 - -게시된 아티팩트는 변경 불가능한 것으로 취급하세요. 각 아티팩트에 이를 -컴파일하는 데 사용된 릴리스 id를 태그하세요(예: `objectstack-2026-05-24.json`). -알려진 정상 비즈니스 상태로의 복구는 보통 다음을 의미합니다: - -1. 데이터베이스를 선택한 시점으로 복원합니다. -2. ObjectOS를 그 시점에 활성화되어 있던 아티팩트 버전으로 다시 - 가리킵니다. -3. 런타임을 다시 시작합니다. - -아티팩트를 제자리에서 덮어쓰면, 데이터베이스 백업이 완벽하더라도 -깔끔하게 롤백할 수 있는 능력을 잃게 됩니다. - -## RPO/RTO 계획 - -고객 배포를 위한 실용적인 시작 목표: - -| 등급 | RPO | RTO | 비고 | -|---|---|---|---| -| 평가 / 데모 | 최선의 노력 | 최선의 노력 | SQLite 스냅샷으로 충분 | -| 데스크톱 앱 / 소규모 팀 단일 노드 | ≤ 1시간(스냅샷) 또는 ≤ 수 초(Litestream) | 수 분 | SQLite + WAL + 예약된 `VACUUM INTO` + 오프사이트 복사본 | -| 단일 테넌트 프로덕션 | ≤ 15분 | ≤ 1시간 | PITR가 있는 관리형 PostgreSQL + 웜 이미지 | -| 멀티 테넌트 / 규제 대상 | ≤ 5분 | ≤ 30분 | HA 데이터베이스 + 멀티 AZ ObjectOS + 테스트된 런북 | - -더 엄격한 목표를 달성하려면 ObjectOS 컨테이너 자체 외부의 플랫폼 -변경(HA 데이터베이스, 멀티 AZ 인그레스, 웜 레플리카)이 필요합니다. - -## 연습해 볼 만한 장애 모드 - -- **데이터베이스가 장시간 사용 불가.** 런타임이 명확한 503을 표출하고 - 프로브가 파드를 올바르게 비정상으로 표시하는지 확인하세요. -- **아티팩트 회귀.** 아티팩트 포인터를 롤백하세요. 데이터는 영향을 - 받지 않습니다. -- **시크릿 교체.** `AUTH_SECRET`을 교체하면 모든 세션이 무효화됩니다. - 유지보수 시간대에 실행하거나 레플리카 간에 시차를 두고 진행하세요. -- **리전 장애.** 고객이 리전 페일오버를 요구하는 경우, 비즈니스 - 데이터베이스, 시크릿 관리자, 인그레스가 모두 리전 간으로 구성되어야 - 합니다. ObjectOS 자체는 이미지를 사용할 수 있는 곳이라면 어디서든 - 실행할 수 있습니다. - -## 런북에 담아야 할 것 - -- 각 데이터셋에 대한 백업 일정, 보존 기간, 온콜 담당자. -- 단계별 복원 절차(데이터베이스 먼저, 그다음 아티팩트, 그다음 ObjectOS - 시작). -- 복원된 데이터베이스가 일관적인지 확인하기 위한 검증 쿼리. -- ObjectOS 이미지와 아티팩트 버전 모두에 대한 롤백 계획(자세한 내용은 - [업그레이드 및 롤백](/docs/operate/upgrade) 참조). -- 고객에게 노출되는 인시던트를 위한 커뮤니케이션 템플릿. diff --git a/content/docs/operate/backup.mdx b/content/docs/operate/backup.mdx index 8032263..08b5add 100644 --- a/content/docs/operate/backup.mdx +++ b/content/docs/operate/backup.mdx @@ -18,7 +18,9 @@ ObjectOS itself.** Plan recovery around those datasets. | Customer-managed identity provider | IdP vendor | Vendor-native | ObjectOS does **not** require a separate backup of its container -filesystem. Cache directories (`OS_CACHE_DIR`) are rebuildable. +filesystem. Its runtime state lives on a declared volume and its caches are +rebuildable — a cached artifact is re-verified against its integrity pin on +every read, so losing the cache costs a fetch, never correctness. ## Database backups diff --git a/content/docs/operate/backup.zh-Hans.mdx b/content/docs/operate/backup.zh-Hans.mdx deleted file mode 100644 index 162e41a..0000000 --- a/content/docs/operate/backup.zh-Hans.mdx +++ /dev/null @@ -1,137 +0,0 @@ ---- -title: 备份与灾难恢复 -description: 备份什么、如何恢复，以及如何为故障做规划。 ---- - -ObjectOS 本身是无状态的 —— 运行时可从容器镜像重建。**备份关心的是 -ObjectOS 所依赖的数据，而不是 ObjectOS 本身。** 围绕这些数据集来规划 -恢复。 - -## 备份什么 - -| 资产 | 归属方 | 备份策略 | -|---|---|---| -| 业务数据库 | 客户 | 数据库原生备份（托管服务使用 PITR）;每季度测试恢复一次 | -| 编译产物（`objectstack.json`） | 应用/发布团队 | 每个发布的产物保存在不可变存储中;切勿覆盖 | -| Secret 基线 | 客户的密钥管理器 | 厂商原生备份;按策略轮换 | -| 对象/文件存储（启用 `storage` 能力时） | 客户 | Bucket 版本化 + 如需可跨区域复制 | -| 客户自管的身份提供方 | IdP 厂商 | 厂商原生 | - -ObjectOS **不**需要对其容器文件系统做单独备份。缓存目录 -（`OS_CACHE_DIR`）可以重建。 - -## 数据库备份 - -按驱动匹配策略： - -| 驱动 | 推荐方式 | -|---|---| -| PostgreSQL | 持续 WAL 归档 + 基础备份;支持时间点恢复 | -| MySQL | 二进制日志归档 + 完整转储;支持时间点恢复 | -| MongoDB | 副本集快照;通过 oplog 实现 PITR | -| SQLite（单节点 / 桌面） | 启用 WAL 模式 + 用 `VACUUM INTO` 或 Online Backup API 做热快照;如需更低 RPO 可叠加 Litestream 持续复制 —— 见下方 [SQLite 部署](#sqlite-deployments) | - -无论使用哪种驱动，都需验证： - -- 备份能在客户的 RPO 内完成; -- 一个全新数据库能基于同一份产物启动 ObjectOS 并对外服务; -- 至少每季度执行一次端到端的恢复演练。 - -## SQLite 部署 - -SQLite 是默认驱动，对于**单节点**形态的 ObjectOS 完全可以用于生产 -—— 桌面端应用、小团队内部工具、边缘 / 本地一体机、评估环境。它的 -取舍是结构性的：SQLite 是单写者，因此不适合多节点 ObjectOS、高并发 -写入或共享数据库的部署。这些场景请使用 PostgreSQL。 - -当你确实在生产中使用 SQLite 时，让它稳定运行的配置和备份方案是配套的： - -**运行时配置** - -- 启用 WAL：`PRAGMA journal_mode=WAL`（读不阻塞写;崩溃安全）。 -- `PRAGMA synchronous=NORMAL` 是桌面 / 单机生产的常用默认值 —— 在 - WAL 下安全，且比 `FULL` 快得多。 -- 数据库文件放在**本地磁盘**上。**不要**放在 NFS、SMB，或者在运行时 - 正在使用的情况下放在被 Dropbox / OneDrive / iCloud 同步的目录里 - —— SQLite 的文件锁在这些位置不可靠，这是 SQLite 部署最常见的损坏 - 原因。 - -**热快照（无需停机）** - -运行时继续对外服务的同时，可以用 SQLite 的 Online Backup API 或 -`VACUUM INTO` 生成一致性快照： - -```sql -VACUUM INTO '/var/backups/objectos/db-2026-05-27T13-00Z.sqlite'; -``` - -按照你的 RPO 节奏用 cron、systemd timer 或运行时内置 scheduler 触发。 -给每份快照打上当时所用的产物版本标签，以便将数据库和产物作为一组 -回滚（见下方 [产物版本化](#artifact-versioning)）。 - -**异地副本** - -本地快照扛不住磁盘故障。把每份快照推送到可持续存储： - -- 服务器 / VM：推到 S3 或任何 S3 兼容 bucket（你大概率已经为 - `storage` 能力配过一个了）。 -- 桌面端应用：把快照写入用户控制的同步目录（OneDrive / iCloud / - Google Drive）—— 这里可以接受，因为快照文件是**关闭且不可变**的， - 和活动数据库不同。 - -**持续复制（更低 RPO）** - -在不放弃 SQLite 的前提下要拿到分钟级以下的 RPO，把 -[Litestream](https://litestream.io) 与 ObjectOS 进程一起跑。它把 WAL -流式复制到 S3 兼容存储，并支持时间点恢复。当单节点 SQLite 部署需要 -近零数据丢失时，这是推荐路径。 - -**恢复** - -停掉运行时，用选定的快照替换数据库文件（或执行 `litestream -restore`），用产生该快照时所对应的产物版本重新启动运行时。 - -## 产物版本化 - -把发布的产物视为不可变。给每份产物打上其编译所用的发布 id 标签 -（例如 `objectstack-2026-05-24.json`）。恢复到已知正常的业务状态通常意味着： - -1. 将数据库恢复到所选时间点。 -2. 将 ObjectOS 指回当时在线的那个产物版本。 -3. 重启运行时。 - -如果就地覆盖产物，即便数据库备份完美无缺，也会失去干净回滚的能力。 - -## RPO/RTO 规划 - -客户部署可行的起点目标： - -| 等级 | RPO | RTO | 备注 | -|---|---|---|---| -| 评估 / 演示 | 尽力而为 | 尽力而为 | SQLite 快照即可 | -| 桌面端应用 / 小团队单节点 | ≤ 1 小时（快照）或 ≤ 秒级（Litestream） | 分钟级 | SQLite + WAL + 定时 `VACUUM INTO` + 异地副本 | -| 单租户生产 | ≤ 15 分钟 | ≤ 1 小时 | 托管 PostgreSQL + PITR + 热镜像 | -| 多租户 / 受监管 | ≤ 5 分钟 | ≤ 30 分钟 | 高可用数据库 + 多可用区 ObjectOS + 经过演练的 runbook | - -更严苛的目标需要在 ObjectOS 容器之外做平台层改造（HA 数据库、多 -可用区入口、热副本）。 - -## 值得演练的故障模式 - -- **数据库长时间不可用。** 确认运行时返回明确的 503，并且探针正确 - 地把 Pod 标记为不健康。 -- **产物回归。** 回滚产物指针;数据不受影响。 -- **Secret 轮换。** 轮换 `AUTH_SECRET` 会使所有会话失效。请在维护 - 窗口执行，或在副本之间分批进行。 -- **区域故障。** 如果客户要求区域级故障切换，业务数据库、密钥 - 管理器和入口都需要跨区域。ObjectOS 本身可以运行在任何能拉到 - 镜像的地方。 - -## runbook 中应记录的内容 - -- 每个数据集的备份计划、保留策略和值班联系人。 -- 分步恢复流程（先恢复数据库，再切换产物，最后启动 ObjectOS）。 -- 用于确认已恢复数据库一致性的校验查询。 -- ObjectOS 镜像和产物版本各自的回滚方案（见 - [升级与回滚](/docs/operate/upgrade)）。 -- 面向客户的事件沟通模板。 diff --git a/content/docs/operate/production.de.mdx b/content/docs/operate/production.de.mdx deleted file mode 100644 index 125b6d3..0000000 --- a/content/docs/operate/production.de.mdx +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: Produktionsreife -description: Checkliste für den sicheren Betrieb von ObjectOS in der Produktion. ---- - -Verwenden Sie diese Checkliste, bevor Sie ObjectOS dem Produktionsverkehr aussetzen. - -## HTTP-Härtung - -Die ObjectStack-Laufzeitumgebung stellt konservative Sicherheits-Header für -Dispatcher-Routen bereit. Produktionsbereitstellungen sollten Folgendes überprüfen: - -- `Content-Security-Policy`; -- `X-Content-Type-Options`; -- `X-Frame-Options`; -- `Referrer-Policy`; -- `Permissions-Policy`; -- `Cross-Origin-Resource-Policy`; -- HSTS, nachdem TLS bestätigt wurde. - -Wenn ein Reverse-Proxy die Header verwaltet, überprüfen Sie die endgültige Antwort mit: - -```bash -curl -I https://app.example.com -``` - -## Geheimnisse - -Speichern Sie diese in einem Secret Manager: - -| Geheimnis | Zweck | -|---|---| -| `OS_AUTH_SECRET` | Basis-Geheimnis zur Signierung von Sitzungen | -| `OS_CLOUD_API_KEY` | Zugriff auf die Artifact-API der Control-Plane | -| Datenbank-Anmeldedaten | Zugriff auf die Geschäftsdatenbank | -| OIDC-Client-Secret | Enterprise-SSO | -| Provider-API-Schlüssel | E-Mail, Speicher, KI, Integrationen | - -Betten Sie Geheimnisse niemals in Artefakte oder Images ein. - -## Rate Limiting - -Das Framework stellt einen Token-Bucket-Rate-Limiter bereit. Richten Sie das Rate -Limiting auf der Adapter-, Ingress- oder Gateway-Ebene ein, wo die Aufrufer-IP und -die authentifizierte Identität vertrauenswürdig sind. - -Empfohlene Buckets: - -| Verkehr | Beispiel-Limit | -|---|---:| -| Auth-Endpunkte | 10/Min/IP | -| Schreibanfragen | 60/Min/IP | -| Leseanfragen | 600/Min/IP | - -Verwenden Sie ein gemeinsames Backend wie Redis für Bereitstellungen mit mehreren Pods. - -## CORS - -Konfigurieren Sie explizite Ursprünge: - -```text -https://app.example.com -https://admin.example.com -``` - -Verwenden Sie keine Wildcard-Ursprünge bei Anfragen mit Anmeldedaten. - -## Go-Live-Checkliste - -- [ ] TLS wird am Edge oder Ingress terminiert. -- [ ] Sicherheits-Header sind vorhanden. -- [ ] HSTS ist nach der TLS-Validierung aktiviert. -- [ ] CORS-Ursprünge sind explizit. -- [ ] Rate-Limits schützen Auth- und Schreib-Endpunkte. -- [ ] `OS_AUTH_SECRET` ist stark und wird als Geheimnis gespeichert. -- [ ] OIDC-Callback-URLs stimmen mit der öffentlichen Domain überein. -- [ ] Backup und Wiederherstellung der Geschäftsdatenbank sind getestet. -- [ ] Audit-Logs werden gemäß der Kundenrichtlinie aufbewahrt. -- [ ] Negative Zugriffstests über Organisationsgrenzen hinweg bestehen. -- [ ] Der Rollback-Plan deckt sowohl das ObjectOS-Image als auch die Artefaktversion ab. diff --git a/content/docs/operate/production.es.mdx b/content/docs/operate/production.es.mdx deleted file mode 100644 index 3e2ec8b..0000000 --- a/content/docs/operate/production.es.mdx +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: Preparación para producción -description: Lista de verificación para ejecutar ObjectOS de forma segura en producción. ---- - -Usa esta lista de verificación antes de exponer ObjectOS al tráfico de producción. - -## Endurecimiento de HTTP - -El runtime de ObjectStack proporciona cabeceras de seguridad conservadoras para las -rutas del dispatcher. Los despliegues de producción deben verificar: - -- `Content-Security-Policy`; -- `X-Content-Type-Options`; -- `X-Frame-Options`; -- `Referrer-Policy`; -- `Permissions-Policy`; -- `Cross-Origin-Resource-Policy`; -- HSTS una vez confirmado el TLS. - -Si un proxy inverso gestiona las cabeceras, verifica la respuesta final con: - -```bash -curl -I https://app.example.com -``` - -## Secretos - -Almacena estos valores en un gestor de secretos: - -| Secreto | Propósito | -|---|---| -| `OS_AUTH_SECRET` | Secreto base para la firma de sesiones | -| `OS_CLOUD_API_KEY` | Acceso a la Artifact API del plano de control | -| Credenciales de base de datos | Acceso a la base de datos de negocio | -| Secreto de cliente OIDC | SSO empresarial | -| Claves de API de proveedores | Correo electrónico, almacenamiento, IA, integraciones | - -Nunca incrustes secretos en artefactos ni en imágenes. - -## Limitación de tasa - -El framework expone un limitador de tasa de tipo token-bucket. Configura la limitación -de tasa en la capa de adaptador, ingress o gateway, donde la IP del llamante y la -identidad autenticada sean fiables. - -Buckets recomendados: - -| Tráfico | Límite de ejemplo | -|---|---:| -| Endpoints de autenticación | 10/min/IP | -| Solicitudes de escritura | 60/min/IP | -| Solicitudes de lectura | 600/min/IP | - -Usa un backend compartido como Redis para despliegues con múltiples pods. - -## CORS - -Configura orígenes explícitos: - -```text -https://app.example.com -https://admin.example.com -``` - -No uses orígenes comodín con solicitudes que incluyan credenciales. - -## Lista de verificación para la puesta en marcha - -- [ ] El TLS se termina en el edge o en el ingress. -- [ ] Las cabeceras de seguridad están presentes. -- [ ] HSTS está habilitado tras la validación del TLS. -- [ ] Los orígenes de CORS son explícitos. -- [ ] Los límites de tasa protegen los endpoints de autenticación y escritura. -- [ ] `OS_AUTH_SECRET` es robusto y se almacena como secreto. -- [ ] Las URL de callback de OIDC coinciden con el dominio público. -- [ ] La copia de seguridad y la restauración de la base de datos de negocio están probadas. -- [ ] Los registros de auditoría se conservan según la política del cliente. -- [ ] Las pruebas negativas de acceso entre organizaciones pasan. -- [ ] El plan de reversión cubre tanto la imagen de ObjectOS como la versión del artefacto. diff --git a/content/docs/operate/production.fr.mdx b/content/docs/operate/production.fr.mdx deleted file mode 100644 index 213bd5e..0000000 --- a/content/docs/operate/production.fr.mdx +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: Préparation à la production -description: Liste de contrôle pour exécuter ObjectOS en toute sécurité en production. ---- - -Utilisez cette liste de contrôle avant d'exposer ObjectOS au trafic de production. - -## Renforcement HTTP - -Le runtime ObjectStack fournit des en-têtes de sécurité prudents pour les -routes du dispatcher. Les déploiements en production doivent vérifier : - -- `Content-Security-Policy` ; -- `X-Content-Type-Options` ; -- `X-Frame-Options` ; -- `Referrer-Policy` ; -- `Permissions-Policy` ; -- `Cross-Origin-Resource-Policy` ; -- HSTS une fois le TLS confirmé. - -Si un reverse proxy gère les en-têtes, vérifiez la réponse finale avec : - -```bash -curl -I https://app.example.com -``` - -## Secrets - -Stockez ces éléments dans un gestionnaire de secrets : - -| Secret | Objet | -|---|---| -| `OS_AUTH_SECRET` | Secret de base pour la signature des sessions | -| `OS_CLOUD_API_KEY` | Accès à l'Artifact API du plan de contrôle | -| Identifiants de base de données | Accès à la base de données métier | -| Secret client OIDC | SSO d'entreprise | -| Clés API de fournisseurs | E-mail, stockage, IA, intégrations | - -N'intégrez jamais de secrets dans les artefacts ou les images. - -## Limitation de débit - -Le framework expose un limiteur de débit de type token-bucket. Mettez en place -la limitation de débit au niveau de l'adaptateur, de l'ingress ou de la -passerelle, là où l'IP de l'appelant et l'identité authentifiée sont fiables. - -Buckets recommandés : - -| Trafic | Limite exemple | -|---|---:| -| Points de terminaison d'authentification | 10/min/IP | -| Requêtes d'écriture | 60/min/IP | -| Requêtes de lecture | 600/min/IP | - -Utilisez un backend partagé tel que Redis pour les déploiements multi-pods. - -## CORS - -Configurez des origines explicites : - -```text -https://app.example.com -https://admin.example.com -``` - -N'utilisez pas d'origines avec caractère générique pour les requêtes -authentifiées. - -## Liste de contrôle de mise en production - -- [ ] Le TLS est terminé au niveau de l'edge ou de l'ingress. -- [ ] Les en-têtes de sécurité sont présents. -- [ ] HSTS est activé après validation du TLS. -- [ ] Les origines CORS sont explicites. -- [ ] Les limites de débit protègent les points de terminaison d'authentification et d'écriture. -- [ ] `OS_AUTH_SECRET` est robuste et stocké comme un secret. -- [ ] Les URL de callback OIDC correspondent au domaine public. -- [ ] La sauvegarde et la restauration de la base de données métier sont testées. -- [ ] Les journaux d'audit sont conservés conformément à la politique du client. -- [ ] Les tests d'accès négatifs inter-organisations réussissent. -- [ ] Le plan de rollback couvre à la fois l'image ObjectOS et la version de l'artefact. diff --git a/content/docs/operate/production.ja.mdx b/content/docs/operate/production.ja.mdx deleted file mode 100644 index 6e90dcd..0000000 --- a/content/docs/operate/production.ja.mdx +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: 本番運用の準備 -description: ObjectOS を本番環境で安全に運用するためのチェックリスト。 ---- - -ObjectOS を本番トラフィックに公開する前に、このチェックリストを使用してください。 - -## HTTP のハードニング - -ObjectStack ランタイムは、ディスパッチャールートに対して保守的なセキュリティヘッダーを提供します。本番デプロイでは、以下を確認してください。 - -- `Content-Security-Policy` -- `X-Content-Type-Options` -- `X-Frame-Options` -- `Referrer-Policy` -- `Permissions-Policy` -- `Cross-Origin-Resource-Policy` -- TLS が確認できたら HSTS - -リバースプロキシがヘッダーを管理している場合は、次のコマンドで最終的なレスポンスを確認してください。 - -```bash -curl -I https://app.example.com -``` - -## シークレット - -以下はシークレットマネージャーに保管してください。 - -| シークレット | 用途 | -|---|---| -| `OS_AUTH_SECRET` | セッション署名のベースシークレット | -| `OS_CLOUD_API_KEY` | コントロールプレーンの Artifact API アクセス | -| データベース認証情報 | 業務データベースへのアクセス | -| OIDC クライアントシークレット | エンタープライズ SSO | -| プロバイダーの API キー | メール、ストレージ、AI、連携 | - -シークレットをアーティファクトやイメージに埋め込まないでください。 - -## レート制限 - -フレームワークはトークンバケット方式のレートリミッターを提供します。呼び出し元の IP と認証済みアイデンティティが信頼できる、アダプター、イングレス、またはゲートウェイの層でレート制限を組み込んでください。 - -推奨バケット: - -| トラフィック | 制限の例 | -|---|---:| -| 認証エンドポイント | 10/分/IP | -| 書き込みリクエスト | 60/分/IP | -| 読み取りリクエスト | 600/分/IP | - -複数ポッドのデプロイでは、Redis などの共有バックエンドを使用してください。 - -## CORS - -許可するオリジンを明示的に設定してください。 - -```text -https://app.example.com -https://admin.example.com -``` - -認証情報付きリクエストでワイルドカードのオリジンを使用しないでください。 - -## 本番公開チェックリスト - -- [ ] TLS がエッジまたはイングレスで終端されている。 -- [ ] セキュリティヘッダーが存在する。 -- [ ] TLS の検証後に HSTS が有効になっている。 -- [ ] CORS のオリジンが明示的に指定されている。 -- [ ] レート制限が認証エンドポイントと書き込みエンドポイントを保護している。 -- [ ] `OS_AUTH_SECRET` が強力で、シークレットとして保管されている。 -- [ ] OIDC のコールバック URL が公開ドメインと一致している。 -- [ ] 業務データベースのバックアップとリストアがテスト済みである。 -- [ ] 監査ログが顧客のポリシーに従って保持されている。 -- [ ] 組織をまたいだネガティブアクセステストに合格している。 -- [ ] ロールバック計画が ObjectOS イメージとアーティファクトバージョンの両方をカバーしている。 diff --git a/content/docs/operate/production.ko.mdx b/content/docs/operate/production.ko.mdx deleted file mode 100644 index 6ac1f10..0000000 --- a/content/docs/operate/production.ko.mdx +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: 프로덕션 준비 -description: ObjectOS를 프로덕션에서 안전하게 운영하기 위한 체크리스트. ---- - -ObjectOS를 프로덕션 트래픽에 노출하기 전에 이 체크리스트를 사용하세요. - -## HTTP 강화 - -ObjectStack 런타임은 디스패처 라우트에 대해 보수적인 보안 헤더를 제공합니다. -프로덕션 배포 시 다음을 확인해야 합니다. - -- `Content-Security-Policy`; -- `X-Content-Type-Options`; -- `X-Frame-Options`; -- `Referrer-Policy`; -- `Permissions-Policy`; -- `Cross-Origin-Resource-Policy`; -- TLS가 확인된 후의 HSTS. - -리버스 프록시가 헤더를 소유하는 경우 다음으로 최종 응답을 확인하세요. - -```bash -curl -I https://app.example.com -``` - -## 시크릿 - -다음 항목은 시크릿 관리자에 저장하세요. - -| 시크릿 | 용도 | -|---|---| -| `OS_AUTH_SECRET` | 세션 서명 기본 시크릿 | -| `OS_CLOUD_API_KEY` | 컨트롤 플레인 Artifact API 접근 | -| 데이터베이스 자격 증명 | 비즈니스 데이터베이스 접근 | -| OIDC 클라이언트 시크릿 | 엔터프라이즈 SSO | -| 프로바이더 API 키 | 이메일, 스토리지, AI, 통합 | - -시크릿을 아티팩트나 이미지에 절대 포함하지 마세요. - -## 속도 제한 - -프레임워크는 토큰 버킷 속도 제한기를 제공합니다. 호출자 IP와 인증된 -신원을 신뢰할 수 있는 어댑터, 인그레스 또는 게이트웨이 계층에서 속도 제한을 -구성하세요. - -권장 버킷: - -| 트래픽 | 예시 제한 | -|---|---:| -| 인증 엔드포인트 | 10/min/IP | -| 쓰기 요청 | 60/min/IP | -| 읽기 요청 | 600/min/IP | - -다중 파드 배포에는 Redis와 같은 공유 백엔드를 사용하세요. - -## CORS - -명시적인 오리진을 구성하세요. - -```text -https://app.example.com -https://admin.example.com -``` - -자격 증명이 포함된 요청에는 와일드카드 오리진을 사용하지 마세요. - -## 출시 체크리스트 - -- [ ] TLS가 엣지 또는 인그레스에서 종료됩니다. -- [ ] 보안 헤더가 존재합니다. -- [ ] TLS 검증 후 HSTS가 활성화되어 있습니다. -- [ ] CORS 오리진이 명시적입니다. -- [ ] 속도 제한이 인증 및 쓰기 엔드포인트를 보호합니다. -- [ ] `OS_AUTH_SECRET`이 강력하며 시크릿으로 저장되어 있습니다. -- [ ] OIDC 콜백 URL이 공개 도메인과 일치합니다. -- [ ] 비즈니스 데이터베이스 백업 및 복원이 테스트되었습니다. -- [ ] 감사 로그가 고객 정책에 따라 보존됩니다. -- [ ] 조직 간 부정 접근 테스트가 통과합니다. -- [ ] 롤백 계획이 ObjectOS 이미지와 아티팩트 버전을 모두 포함합니다. diff --git a/content/docs/operate/production.mdx b/content/docs/operate/production.mdx index cf63d57..e5d0066 100644 --- a/content/docs/operate/production.mdx +++ b/content/docs/operate/production.mdx @@ -30,14 +30,20 @@ Store these in a secret manager: | Secret | Purpose | |---|---| -| `OS_AUTH_SECRET` | Session signing base secret | -| `OS_CLOUD_API_KEY` | Control-plane Artifact API access | +| `OS_AUTH_SECRET` | Session signing base secret. **Identical on every replica** — replicas with different values reject each other's sessions. | +| `OS_SECRET_KEY` | Required once you run more than one replica, and likewise identical across all of them. | +| `OS_LICENSE_KEY` | The deployment's entitlement. | | Database credentials | Business database access | | OIDC client secret | Enterprise SSO | | Provider API keys | Email, storage, AI, integrations | Never bake secrets into artifacts or images. +A deployment **bound** to a control plane holds a runtime token as well, but +that one is not a secret you configure: it is minted during the binding and +persisted by the runtime. There is no deployment-level API key to distribute +for it. + ## Rate limiting The framework exposes a token-bucket rate limiter. Wire rate limiting at diff --git a/content/docs/operate/production.zh-Hans.mdx b/content/docs/operate/production.zh-Hans.mdx deleted file mode 100644 index e5cfb06..0000000 --- a/content/docs/operate/production.zh-Hans.mdx +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: 生产就绪 -description: 安全地在生产环境运行 ObjectOS 的检查清单。 ---- - -在让 ObjectOS 承接生产流量之前，请使用这份清单。 - -## HTTP 加固 - -ObjectStack 运行时为分发路由提供了保守的安全响应头。生产部署应当 -确认： - -- `Content-Security-Policy`; -- `X-Content-Type-Options`; -- `X-Frame-Options`; -- `Referrer-Policy`; -- `Permissions-Policy`; -- `Cross-Origin-Resource-Policy`; -- 在确认 TLS 后启用 HSTS。 - -如果响应头由反向代理控制，请用以下命令验证最终响应： - -```bash -curl -I https://app.example.com -``` - -## Secrets - -以下内容应存放在密钥管理器中： - -| Secret | 用途 | -|---|---| -| `OS_AUTH_SECRET` | 会话签名的基础密钥 | -| `OS_CLOUD_API_KEY` | 控制面 Artifact API 访问 | -| 数据库凭据 | 业务数据库访问 | -| OIDC client secret | 企业 SSO | -| 各类 Provider API key | 邮件、存储、AI、集成 | - -切勿将 secret 写入产物或镜像。 - -## 限流 - -框架暴露了一个令牌桶限流器。请在调用方 IP 与已认证身份可信的位置 -（适配器、入口或网关层）接入限流。 - -推荐的桶配置： - -| 流量 | 示例上限 | -|---|---:| -| 认证端点 | 10/分钟/IP | -| 写请求 | 60/分钟/IP | -| 读请求 | 600/分钟/IP | - -多 Pod 部署应使用共享后端，如 Redis。 - -## CORS - -显式配置来源： - -```text -https://app.example.com -https://admin.example.com -``` - -不要在携带凭据的请求中使用通配符来源。 - -## 上线检查清单 - -- [ ] TLS 在边缘或入口处终止。 -- [ ] 安全响应头已就位。 -- [ ] 验证 TLS 后启用 HSTS。 -- [ ] CORS 来源是显式的。 -- [ ] 对认证与写端点做了限流保护。 -- [ ] `OS_AUTH_SECRET` 足够强并作为 secret 存储。 -- [ ] OIDC 回调 URL 与公开域名一致。 -- [ ] 业务数据库的备份与恢复已测试。 -- [ ] 审计日志按客户策略保留。 -- [ ] 跨组织的反向访问测试通过。 -- [ ] 回滚方案覆盖 ObjectOS 镜像与产物版本。 diff --git a/content/docs/operate/troubleshooting.de.mdx b/content/docs/operate/troubleshooting.de.mdx deleted file mode 100644 index 7565531..0000000 --- a/content/docs/operate/troubleshooting.de.mdx +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: Fehlerbehebung -description: Diagnostizieren Sie Probleme bei Start, Artefakten, Authentifizierung, Berechtigungen und Deployment. ---- - -Beginnen Sie mit dem Symptom und prüfen Sie dann zuerst die kleinste Abgrenzung. - -## ObjectOS startet nicht - -Prüfen Sie: - -1. Container-Logs. -2. Node-Version und Paketinstallation. -3. `PORT`-Konflikt. -4. Fehlendes Artefakt. -5. Fehlendes `OS_AUTH_SECRET`, wenn Auth-Endpunkte erwartet werden. - -Für Docker: - -```bash -docker compose -f docker/docker-compose.yml logs objectos -``` - -## Artefakt kann nicht geladen werden - -Prüfen Sie: - -- `OS_ARTIFACT_FILE` zeigt auf die eingehängte Datei; -- die Datei existiert innerhalb des Containers; -- die Datei ist gültiges JSON; -- das Artefakt ist ein kompiliertes ObjectStack-Artefakt, keine Quell-Metadaten; -- die Dateiberechtigungen erlauben Lesezugriff. - -Innerhalb eines Containers: - -```bash -ls -l /artifacts/objectstack.json -``` - -## Anmeldung schlägt fehl - -Prüfen Sie: - -- `OS_AUTH_SECRET` ist konfiguriert; -- öffentliche URL und Callback-URL stimmen überein; -- die OIDC-Discovery-URL ist von ObjectOS aus erreichbar; -- die vertrauenswürdigen Origins enthalten die öffentliche Domain; -- Cookies sind auf den korrekten Projekt-Hostnamen begrenzt; -- der Projekt-Kernel hat die Authentifizierung aktiviert. - -## Benutzer kann keine Datensätze sehen - -Prüfen Sie: - -1. Korrekter Projekt-Hostname. -2. Der Benutzer gehört zur erwarteten Organisation. -3. Objekt-Berechtigung `read`. -4. Sicherheit auf Zeilenebene. -5. Freigaberegeln oder Datensatzfreigaben. -6. Feldsicherheit, wenn nur einige Felder fehlen. - -## Einstellungen sind nicht bearbeitbar - -Eine Einstellung kann durch eine Umgebungsüberschreibung gesperrt sein. Effektive Einstellungen -werden in dieser Reihenfolge aufgelöst: - -```text -Environment -> Tenant -> User -> Default -``` - -Wenn die Umgebung einen Wert bereitstellt, sollten Laufzeitänderungen abgelehnt werden, -anstatt ihn stillschweigend zu überschreiben. - -## Webhooks oder Jobs werden nicht ausgeführt - -Prüfen Sie: - -- die `requires`-Liste des Artefakts enthält die benötigte Capability; -- das ObjectOS-Image enthält das optionale Service-Paket; -- die Konfiguration des Queue-/Job-Service ist verfügbar; -- ausgehender Netzwerkzugriff auf das Ziel ist erlaubt; -- Zustelllogs oder Job-Läufe sind in der Console-Diagnose sichtbar. - -## Datenbankfehler - -Prüfen Sie: - -- Datenbank-URL und Treibertyp; -- Netzwerkzugriff von ObjectOS auf die Datenbank; -- Anmeldedaten und TLS-Optionen; -- Logs zur Schema-Synchronisierung/-Migration; -- Speicherpersistenz bei Verwendung von lokalem SQLite. diff --git a/content/docs/operate/troubleshooting.es.mdx b/content/docs/operate/troubleshooting.es.mdx deleted file mode 100644 index 510dab6..0000000 --- a/content/docs/operate/troubleshooting.es.mdx +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: Resolución de problemas -description: Diagnostica problemas de arranque, artefactos, autenticación, permisos e implementación. ---- - -Comienza por el síntoma y luego revisa primero el límite más pequeño. - -## ObjectOS no arranca - -Revisa: - -1. Los registros del contenedor. -2. La versión de Node y la instalación de paquetes. -3. Conflictos en `PORT`. -4. Artefacto faltante. -5. Falta de `OS_AUTH_SECRET` cuando se esperan endpoints de autenticación. - -Para Docker: - -```bash -docker compose -f docker/docker-compose.yml logs objectos -``` - -## No se puede cargar el artefacto - -Revisa: - -- que `OS_ARTIFACT_FILE` apunte al archivo montado; -- que el archivo exista dentro del contenedor; -- que el archivo sea un JSON válido; -- que el artefacto sea un artefacto compilado de ObjectStack, no metadatos de origen; -- que los permisos del archivo permitan el acceso de lectura. - -Dentro de un contenedor: - -```bash -ls -l /artifacts/objectstack.json -``` - -## El inicio de sesión falla - -Revisa: - -- que `OS_AUTH_SECRET` esté configurado; -- que la URL pública y la URL de callback coincidan; -- que la URL de descubrimiento de OIDC sea accesible desde ObjectOS; -- que los orígenes de confianza incluyan el dominio público; -- que las cookies estén delimitadas al nombre de host correcto del proyecto; -- que el kernel del proyecto tenga la autenticación habilitada. - -## El usuario no puede ver registros - -Revisa: - -1. El nombre de host correcto del proyecto. -2. Que el usuario pertenezca a la organización esperada. -3. El permiso `read` del objeto. -4. La seguridad a nivel de fila. -5. Las reglas de compartición o los registros compartidos. -6. La seguridad de campo si solo faltan algunos campos. - -## Los ajustes no se pueden editar - -Un ajuste puede estar bloqueado por una anulación de entorno. Los ajustes efectivos -se resuelven en este orden: - -```text -Environment -> Tenant -> User -> Default -``` - -Si el entorno proporciona un valor, las ediciones en tiempo de ejecución deberían rechazarse -en lugar de sobrescribirlo de forma silenciosa. - -## Los webhooks o trabajos no se ejecutan - -Revisa: - -- que la lista `requires` del artefacto incluya la capacidad necesaria; -- que la imagen de ObjectOS incluya el paquete de servicio opcional; -- que la configuración del servicio de cola/trabajos esté disponible; -- que se permita el acceso de red saliente hacia el destino; -- que los registros de entrega o las ejecuciones de trabajos sean visibles en los diagnósticos de Console. - -## Errores de base de datos - -Revisa: - -- la URL de la base de datos y el tipo de controlador; -- el acceso de red desde ObjectOS hacia la base de datos; -- las credenciales y las opciones de TLS; -- los registros de sincronización/migración de esquema; -- la persistencia del almacenamiento si usas SQLite local. diff --git a/content/docs/operate/troubleshooting.fr.mdx b/content/docs/operate/troubleshooting.fr.mdx deleted file mode 100644 index 46668ed..0000000 --- a/content/docs/operate/troubleshooting.fr.mdx +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: Dépannage -description: Diagnostiquer les problèmes de démarrage, d'artefact, d'authentification, de permission et de déploiement. ---- - -Commencez par le symptôme, puis vérifiez d'abord la plus petite limite. - -## ObjectOS ne démarre pas - -Vérifiez : - -1. Les journaux du conteneur. -2. La version de Node et l'installation des paquets. -3. Un conflit de `PORT`. -4. Un artefact manquant. -5. L'absence de `OS_AUTH_SECRET` lorsque des points de terminaison d'authentification sont attendus. - -Pour Docker : - -```bash -docker compose -f docker/docker-compose.yml logs objectos -``` - -## L'artefact ne peut pas être chargé - -Vérifiez : - -- que `OS_ARTIFACT_FILE` pointe vers le fichier monté ; -- que le fichier existe à l'intérieur du conteneur ; -- que le fichier est un JSON valide ; -- que l'artefact est un artefact ObjectStack compilé, et non des métadonnées source ; -- que les permissions du fichier autorisent l'accès en lecture. - -À l'intérieur d'un conteneur : - -```bash -ls -l /artifacts/objectstack.json -``` - -## La connexion échoue - -Vérifiez : - -- que `OS_AUTH_SECRET` est configuré ; -- que l'URL publique et l'URL de rappel correspondent ; -- que l'URL de découverte OIDC est joignable depuis ObjectOS ; -- que les origines de confiance incluent le domaine public ; -- que les cookies sont limités au nom d'hôte de projet correct ; -- que le kernel du projet a l'authentification activée. - -## Un utilisateur ne voit pas les enregistrements - -Vérifiez : - -1. Le nom d'hôte de projet correct. -2. Que l'utilisateur appartient à l'organisation attendue. -3. La permission `read` sur l'objet. -4. La sécurité au niveau des lignes. -5. Les règles de partage ou les partages d'enregistrements. -6. La sécurité des champs si seuls certains champs sont manquants. - -## Les paramètres ne sont pas modifiables - -Un paramètre peut être verrouillé par une surcharge d'environnement. Les paramètres -effectifs sont résolus dans cet ordre : - -```text -Environment -> Tenant -> User -> Default -``` - -Si l'environnement fournit une valeur, les modifications à l'exécution doivent être rejetées -au lieu de l'écraser silencieusement. - -## Les webhooks ou les tâches ne s'exécutent pas - -Vérifiez : - -- que la liste `requires` de l'artefact inclut la capacité nécessaire ; -- que l'image ObjectOS inclut le paquet de service optionnel ; -- que la configuration du service de file d'attente/de tâches est disponible ; -- que l'accès réseau sortant vers la cible est autorisé ; -- que les journaux de livraison ou les exécutions de tâches sont visibles dans les diagnostics de la Console. - -## Erreurs de base de données - -Vérifiez : - -- l'URL de la base de données et le type de pilote ; -- l'accès réseau depuis ObjectOS vers la base de données ; -- les identifiants et les options TLS ; -- les journaux de synchronisation/migration du schéma ; -- la persistance du stockage si vous utilisez SQLite en local. diff --git a/content/docs/operate/troubleshooting.ja.mdx b/content/docs/operate/troubleshooting.ja.mdx deleted file mode 100644 index 30a2682..0000000 --- a/content/docs/operate/troubleshooting.ja.mdx +++ /dev/null @@ -1,90 +0,0 @@ ---- -title: トラブルシューティング -description: 起動、アーティファクト、認証、権限、デプロイに関する問題を診断します。 ---- - -まず症状から始め、最も小さな境界から確認しましょう。 - -## ObjectOS が起動しない - -確認事項: - -1. コンテナのログ。 -2. Node のバージョンとパッケージのインストール。 -3. `PORT` の競合。 -4. アーティファクトの欠落。 -5. 認証エンドポイントが必要な場合の `OS_AUTH_SECRET` の欠落。 - -Docker の場合: - -```bash -docker compose -f docker/docker-compose.yml logs objectos -``` - -## アーティファクトを読み込めない - -確認事項: - -- `OS_ARTIFACT_FILE` がマウントされたファイルを指していること。 -- そのファイルがコンテナ内に存在すること。 -- そのファイルが有効な JSON であること。 -- アーティファクトがソースのメタデータではなく、コンパイル済みの ObjectStack アーティファクトであること。 -- ファイルの権限が読み取りアクセスを許可していること。 - -コンテナ内で: - -```bash -ls -l /artifacts/objectstack.json -``` - -## ログインに失敗する - -確認事項: - -- `OS_AUTH_SECRET` が設定されていること。 -- 公開 URL とコールバック URL が一致していること。 -- OIDC ディスカバリ URL に ObjectOS から到達できること。 -- 信頼されたオリジンに公開ドメインが含まれていること。 -- Cookie が正しいプロジェクトのホスト名にスコープされていること。 -- プロジェクトカーネルで認証が有効になっていること。 - -## ユーザーがレコードを表示できない - -確認事項: - -1. 正しいプロジェクトのホスト名。 -2. ユーザーが想定される組織に属していること。 -3. オブジェクトの `read` 権限。 -4. 行レベルセキュリティ。 -5. 共有ルールまたはレコード共有。 -6. 一部のフィールドのみが表示されない場合はフィールドセキュリティ。 - -## 設定を編集できない - -設定が環境のオーバーライドによってロックされている場合があります。有効な設定は次の順序で解決されます: - -```text -Environment -> Tenant -> User -> Default -``` - -環境が値を提供している場合、ランタイムでの編集は、暗黙的に上書きするのではなく拒否されるべきです。 - -## Webhook やジョブが実行されない - -確認事項: - -- アーティファクトの `requires` リストに必要な機能が含まれていること。 -- ObjectOS イメージにオプションのサービスパッケージが含まれていること。 -- キュー/ジョブサービスの構成が利用可能であること。 -- ターゲットへのアウトバウンドネットワークアクセスが許可されていること。 -- 配信ログまたはジョブ実行が Console の診断機能で確認できること。 - -## データベースエラー - -確認事項: - -- データベース URL とドライバの種類。 -- ObjectOS からデータベースへのネットワークアクセス。 -- 認証情報と TLS オプション。 -- スキーマの同期/マイグレーションのログ。 -- ローカル SQLite を使用している場合のストレージの永続化。 diff --git a/content/docs/operate/troubleshooting.ko.mdx b/content/docs/operate/troubleshooting.ko.mdx deleted file mode 100644 index 1ce0cf9..0000000 --- a/content/docs/operate/troubleshooting.ko.mdx +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: 문제 해결 -description: 시작, 아티팩트, 인증, 권한, 배포 문제를 진단합니다. ---- - -증상에서 시작한 다음, 가장 작은 경계부터 먼저 확인하세요. - -## ObjectOS가 시작되지 않음 - -확인 사항: - -1. 컨테이너 로그. -2. Node 버전 및 패키지 설치. -3. `PORT` 충돌. -4. 누락된 아티팩트. -5. 인증 엔드포인트가 필요할 때 누락된 `OS_AUTH_SECRET`. - -Docker의 경우: - -```bash -docker compose -f docker/docker-compose.yml logs objectos -``` - -## 아티팩트를 로드할 수 없음 - -확인 사항: - -- `OS_ARTIFACT_FILE`이 마운트된 파일을 가리키는지; -- 파일이 컨테이너 내부에 존재하는지; -- 파일이 유효한 JSON인지; -- 아티팩트가 소스 메타데이터가 아니라 컴파일된 ObjectStack 아티팩트인지; -- 파일 권한이 읽기 액세스를 허용하는지. - -컨테이너 내부에서: - -```bash -ls -l /artifacts/objectstack.json -``` - -## 로그인 실패 - -확인 사항: - -- `OS_AUTH_SECRET`이 구성되어 있는지; -- 공개 URL과 콜백 URL이 일치하는지; -- OIDC 디스커버리 URL에 ObjectOS에서 접근할 수 있는지; -- 신뢰할 수 있는 오리진에 공개 도메인이 포함되어 있는지; -- 쿠키가 올바른 프로젝트 호스트 이름으로 범위가 지정되어 있는지; -- 프로젝트 커널에서 인증이 활성화되어 있는지. - -## 사용자가 레코드를 볼 수 없음 - -확인 사항: - -1. 올바른 프로젝트 호스트 이름. -2. 사용자가 예상된 조직에 속해 있음. -3. 객체 `read` 권한. -4. 행 수준 보안. -5. 공유 규칙 또는 레코드 공유. -6. 일부 필드만 누락된 경우 필드 보안. - -## 설정을 편집할 수 없음 - -설정이 환경 재정의에 의해 잠겨 있을 수 있습니다. 유효 설정은 -다음 순서로 해석됩니다: - -```text -Environment -> Tenant -> User -> Default -``` - -환경에서 값을 제공하면, 런타임 편집은 값을 자동으로 덮어쓰는 대신 -거부되어야 합니다. - -## 웹훅 또는 작업이 실행되지 않음 - -확인 사항: - -- 아티팩트의 `requires` 목록에 필요한 기능이 포함되어 있는지; -- ObjectOS 이미지에 선택적 서비스 패키지가 포함되어 있는지; -- 큐/작업 서비스 구성을 사용할 수 있는지; -- 대상으로의 아웃바운드 네트워크 액세스가 허용되는지; -- 전달 로그 또는 작업 실행이 Console 진단에서 표시되는지. - -## 데이터베이스 오류 - -확인 사항: - -- 데이터베이스 URL 및 드라이버 유형; -- ObjectOS에서 데이터베이스로의 네트워크 액세스; -- 자격 증명 및 TLS 옵션; -- 스키마 동기화/마이그레이션 로그; -- 로컬 SQLite를 사용하는 경우 스토리지 지속성. diff --git a/content/docs/operate/troubleshooting.mdx b/content/docs/operate/troubleshooting.mdx index 55dc914..490caee 100644 --- a/content/docs/operate/troubleshooting.mdx +++ b/content/docs/operate/troubleshooting.mdx @@ -7,35 +7,53 @@ Start with the symptom, then check the smallest boundary first. ## ObjectOS does not start -Check: - -1. Container logs. -2. Node version and package install. -3. `PORT` conflict. -4. Missing artifact. -5. Missing `OS_AUTH_SECRET` when auth endpoints are expected. - -For Docker: - -```bash -docker compose -f docker/docker-compose.yml logs objectos -``` - -## Artifact cannot be loaded - -Check: - -- `OS_ARTIFACT_FILE` points to the mounted file; -- the file exists inside the container; -- the file is valid JSON; -- the artifact is a compiled ObjectStack artifact, not source metadata; -- file permissions allow read access. - -Inside a container: - -```bash -ls -l /artifacts/objectstack.json -``` +**Read the last lines of the log before anything else.** A large class of +startup failures here is a *deliberate refusal*, not a crash: the runtime +checks the configuration it was given, prints a fatal error naming the +variables that disagree, and exits. Those messages name the problem exactly, +and no amount of restarting will change the outcome. + +The refusals you are most likely to meet: + +| The log says | What it means | +|---|---| +| Two settings are named together as an unsupported pairing | A licence mode and a cloud posture that cannot work together — most often an ordinary, online-validated licence on a deployment configured with no control plane. [Air-gapped](/docs/deploy/air-gapped) has the supported matrix. | +| A walled deployment requires a licence | A multi-organization tenancy posture was asked for without a licence. Isolation is a licensed capability; the runtime will not serve traffic while pretending to have it. | +| A decision was not made | On a multi-organization posture, the new-sign-up membership policy and the set of mounted AI agents have no safe default. Declaring either available value is accepted; leaving it unset is not. | +| A retired variable is set | An old artifact-selection variable refuses the boot and names its replacement. See [retired names](/docs/reference/environment-variables#retired-names). | +| The cluster secret is missing | Turning on a cluster driver makes one shared secret key mandatory across every replica. | + +If the log shows no fatal error, check the ordinary causes: container logs for +the failing service, a port conflict, and a missing auth secret when +authentication endpoints are expected. + +## The app is not the one you expected + +The app a deployment serves comes from exactly one place, and which place is a +decision the deployment declares — see +[Boot modes](/docs/architecture#boot-modes). When the running app is not the +one you published: + +- **Confirm which mode this deployment is in.** If no artifact reference is + set, the runtime is serving the metadata authored in the image plus whatever + was installed into it — publishing a new artifact changes nothing until the + deployment names it. +- **Check the boot banner**, which names the app that was actually loaded. +- **An integrity pin that does not match refuses the boot** and prints both the + expected and the actual digest. Those two being printed together is the + point: it distinguishes a republished artifact from a substituted one. +- **Unpinned, with the artifact host unreachable, the boot fails loudly.** + There is no cache fallback on the unpinned path — nothing could authenticate + a cached copy. Orchestration retries; the runtime never invents a different + app. +- **Pinned, with the host unreachable, a locally cached copy may serve** — but + only one whose bytes still hash to the pin, and it says so with a warning. + The cache is re-hashed on every read; a filename is never the authority. +- **Setting a retired artifact variable does not select an app.** One of them + refuses the boot outright; the others are read by nothing at all, so the + deployment boots as if you had set nothing. [Retired + names](/docs/reference/environment-variables#retired-names) lists them + against their replacements. ## Login fails diff --git a/content/docs/operate/troubleshooting.zh-Hans.mdx b/content/docs/operate/troubleshooting.zh-Hans.mdx deleted file mode 100644 index c3604f9..0000000 --- a/content/docs/operate/troubleshooting.zh-Hans.mdx +++ /dev/null @@ -1,90 +0,0 @@ ---- -title: 排错 -description: 诊断启动、产物、认证、权限与部署问题。 ---- - -从症状入手，再从最小的边界开始检查。 - -## ObjectOS 启动失败 - -检查： - -1. 容器日志。 -2. Node 版本与依赖安装。 -3. `PORT` 冲突。 -4. 缺失产物。 -5. 期望使用认证端点时缺失 `OS_AUTH_SECRET`。 - -Docker： - -```bash -docker compose -f docker/docker-compose.yml logs objectos -``` - -## 产物无法加载 - -检查： - -- `OS_ARTIFACT_FILE` 指向已挂载的文件; -- 文件在容器内确实存在; -- 文件是合法的 JSON; -- 该产物是编译后的 ObjectStack 产物，而非源元数据; -- 文件权限允许读取。 - -容器内： - -```bash -ls -l /artifacts/objectstack.json -``` - -## 登录失败 - -检查： - -- 已配置 `OS_AUTH_SECRET`; -- 公开 URL 与回调 URL 匹配; -- ObjectOS 能访问 OIDC 发现 URL; -- 受信任来源包含公开域名; -- Cookie 作用域是正确的项目主机名; -- 项目内核已启用认证。 - -## 用户看不到记录 - -检查： - -1. 主机名对应的项目是否正确。 -2. 用户是否归属于预期的组织。 -3. 对象的 `read` 权限。 -4. 行级安全。 -5. 共享规则或记录共享。 -6. 如果只缺少部分字段，检查字段级安全。 - -## 设置不可编辑 - -设置可能被环境层覆盖锁定。生效顺序如下： - -```text -Environment -> Tenant -> User -> Default -``` - -如果环境提供了值，运行时的编辑应当被拒绝，而不是静默覆盖。 - -## webhook 或任务不运行 - -检查： - -- 产物的 `requires` 列表包含所需能力; -- ObjectOS 镜像包含相应的可选服务包; -- 队列/任务服务配置可用; -- 允许出站访问目标地址; -- 在 Console 诊断中能看到投递日志或任务运行。 - -## 数据库错误 - -检查： - -- 数据库 URL 与驱动类型; -- 从 ObjectOS 到数据库的网络可达性; -- 凭据与 TLS 选项; -- schema 同步/迁移日志; -- 若使用本地 SQLite，检查存储持久化。 diff --git a/content/docs/reference/cli.de.mdx b/content/docs/reference/cli.de.mdx deleted file mode 100644 index ed8747c..0000000 --- a/content/docs/reference/cli.de.mdx +++ /dev/null @@ -1,205 +0,0 @@ ---- -title: CLI-Referenz -description: Jeder `os`-Befehl, was er tut und die nützlichsten Flags. ---- - -Das Paket `@objectstack/cli` installiert eine einzelne Binärdatei, `os` (auch -verfügbar als `objectstack`). Alle Beispiele unten verwenden das kürzere `os`. - -```bash -npm i -g @objectstack/cli -os --help -``` - -## Server-Befehle - -### `os start` — Boot ohne Konfiguration - -Erkennt automatisch 4 eskalierende Modi: - -1. **Leerer Boot** — kein Artefakt, keine Konfiguration im cwd → bootet einen - minimalen Kernel mit Console + marketplace. -2. **Projekt-Boot** — `objectstack.config.ts` im cwd → kompiliert automatisch - zu `./dist/objectstack.json` und bootet daraus. -3. **Artefakt-Boot** — `dist/objectstack.json` erreichbar → bootet direkt - daraus. -4. **Explizite Überschreibungen** — `--artifact`, `--database`, `--port` gewinnen. - -```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 Console/Account) -``` - -Standardwert des HOME-Verzeichnisses: -- mit einer Projektkonfiguration im cwd → `/.objectstack` (projektlokal) -- ohne → `~/.objectstack` (global, über Aufrufe hinweg gemeinsam genutzt) - -### `os serve` — Produktionsserver - -Liest `objectstack.config.ts`, falls vorhanden, andernfalls greift es auf -`dist/objectstack.json` zurück (oder `OS_ARTIFACT_PATH`, einschließlich `http(s)://`-URLs). -Verwenden Sie dies in Produktionscontainern, wenn Sie striktes Verhalten wünschen. - -```bash -os serve # port 3000 -os serve --port 4000 --no-ui -``` - -### `os dev` — Entwicklung mit Hot-Reload - -Überwacht `objectstack.config.ts` und `src/`. Rekompiliert + lädt beim -Speichern neu. Wird in gerüsteten Projekten als npm-`dev`-Skript verwendet. - -```bash -os dev # port 3002 by default -os dev -p 4002 -``` - -### `os studio` — Console mit Dev-Server - -Wie `os dev`, aber mit explizit aktivierter Console. - -## Projekt-Befehle - -### `os init` — ein neues Projekt aufsetzen - -```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 -``` - -Vorlagen: -| Vorlage | Was sie Ihnen bietet | -|---|---| -| `app` | Vollständige App — Objekte, Views, Aktionen, bereit zum Erweitern | -| `plugin` | Plugin-Gerüst zum Verteilen wiederverwendbarer Funktionen | -| `empty` | Nur Manifest + tsconfig | - -### `os create` — ein Paket, Plugin oder Beispiel aus einer Vorlage erstellen - -```bash -os create plugin my-plugin -os create example my-example -``` - -## Build- / Validierungs-Befehle - -| Befehl | Zweck | -|---|---| -| `os compile` (`os build`) | `objectstack.config.ts` → `dist/objectstack.json` kompilieren | -| `os validate` | Konfiguration gegen das Protokollschema validieren | -| `os lint` | Stil- und Konventionsprüfungen (empfohlen in CI) | -| `os diff ` | Zwei Konfigurationen vergleichen, Breaking Changes erkennen | -| `os info` | Metadaten-Zusammenfassung einer Konfiguration oder eines Artefakts ausgeben | -| `os explain ` | Menschenlesbare Erklärung eines Objektschemas | -| `os doctor` | Health-Check: erkennt zirkuläre Abhängigkeiten, defekte Referenzen, Umgebungsprobleme | -| `os generate` (`os g`) | TypeScript-Typen / Metadatendateien generieren | - -`os doctor` ist das **Erste, das man ausführen sollte, wenn etwas nicht stimmt** — es -fängt Fehlkonfigurationen ab, die die Laufzeit nur als Laufzeitwarnung melden würde. - -## Daten-Befehle - -Arbeiten Sie mit Datensätzen vom Terminal aus — nützlich für Seeding, Migrationen -und CI-Smoke-Tests. - -```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 -``` - -## Metadaten-Befehle - -Metadaten-Datensätze (Objekte, Views, Berechtigungssätze, …) zur Laufzeit -lesen/schreiben. - -```bash -os meta list -os meta get -os meta register -os meta delete -``` - -## i18n-Befehle - -```bash -os i18n extract # extract translation keys from source -os i18n check # find missing keys across configured locales -``` - -## Cloud-Befehle - -Für Benutzer von ObjectStack Cloud (der optionalen gehosteten Control-Plane). - -```bash -os login # interactive -os logout -os whoami -os register # create an account -os cloud login | logout | whoami -``` - -## Publish- / Package-Befehle - -```bash -os package publish # publish artifact as a versioned package -``` - -## Umgebungs-Befehle - -Für Deployments mit mehreren Umgebungen pro Projekt (dev, staging, -prod), die von einer Control-Plane unterstützt werden. - -```bash -os environments list -os environments show -os environments create -os environments switch -os environments bind # bind local artifact to an environment -``` - -## Test-Befehl - -```bash -os test # run Quality Protocol scenarios against a running server -``` - -## Gängige Flag-Konventionen - -| Flag | Bedeutung | -|---|---| -| `-p, --port` | HTTP-Port | -| `-a, --artifact` | Pfad oder URL zum kompilierten Artefakt | -| `-d, --database` | Datenbank-URL | -| `--home` | Verzeichnis für persistenten Zustand | -| `-v, --verbose` | Ausführliche Ausgabe | -| `--no-ui` | Console-/Account-Portale deaktivieren | - -Führen Sie einen beliebigen Befehl mit `--help` aus, um die vollständige Flag-Liste zu erhalten: - -```bash -os start --help -os data query --help -``` - -## Wo die CLI hineinpasst - -- **Operator / erster Start** → `os start` -- **Entwickler, der eine App baut** → `os init` → `os dev` → `os compile` -- **CI / Release-Pipeline** → `os lint && os validate && os compile && os test` -- **Produktions-Laufzeit** → `os serve` (typischerweise im `CMD` des Docker-Images) -- **Diagnose** → `os doctor`, `os info`, `os explain` diff --git a/content/docs/reference/cli.es.mdx b/content/docs/reference/cli.es.mdx deleted file mode 100644 index df527c7..0000000 --- a/content/docs/reference/cli.es.mdx +++ /dev/null @@ -1,206 +0,0 @@ ---- -title: Referencia de la CLI -description: Cada comando `os`, qué hace y los flags más útiles. ---- - -El paquete `@objectstack/cli` instala un único binario, `os` (también -disponible como `objectstack`). Todos los ejemplos a continuación usan el `os` más corto. - -```bash -npm i -g @objectstack/cli -os --help -``` - -## Comandos del servidor - -### `os start` — arranque sin configuración - -Detecta automáticamente 4 modos escalonados: - -1. **Arranque vacío** — sin artefacto ni configuración en el cwd → arranca un - kernel básico con Console + marketplace. -2. **Arranque de proyecto** — `objectstack.config.ts` en el cwd → compila - automáticamente a `./dist/objectstack.json` y arranca desde ahí. -3. **Arranque de artefacto** — `dist/objectstack.json` accesible → arranca desde - él directamente. -4. **Sobrescrituras explícitas** — `--artifact`, `--database`, `--port` tienen prioridad. - -```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 Console/Account) -``` - -Directorio HOME por defecto: -- con una configuración de proyecto en el cwd → `/.objectstack` (local al proyecto) -- sin ella → `~/.objectstack` (global, compartido entre invocaciones) - -### `os serve` — servidor de producción - -Lee `objectstack.config.ts` si está presente; de lo contrario recurre a -`dist/objectstack.json` (o `OS_ARTIFACT_PATH`, incluyendo URLs `http(s)://`). -Usa esto en contenedores de producción cuando quieras un comportamiento estricto. - -```bash -os serve # port 3000 -os serve --port 4000 --no-ui -``` - -### `os dev` — desarrollo con recarga en caliente - -Observa `objectstack.config.ts` y `src/`. Recompila + recarga al -guardar. Se usa como el script npm `dev` en los proyectos generados. - -```bash -os dev # port 3002 by default -os dev -p 4002 -``` - -### `os studio` — Console con servidor de desarrollo - -Igual que `os dev` pero con Console habilitada explícitamente. - -## Comandos de proyecto - -### `os init` — genera un nuevo proyecto - -```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 -``` - -Plantillas: -| Plantilla | Qué te ofrece | -|---|---| -| `app` | App completa — objetos, vistas, acciones, lista para ampliar | -| `plugin` | Andamiaje de plugin para distribuir capacidades reutilizables | -| `empty` | Solo manifiesto + tsconfig | - -### `os create` — crea un paquete, plugin o ejemplo desde una plantilla - -```bash -os create plugin my-plugin -os create example my-example -``` - -## Comandos de compilación / validación - -| Comando | Propósito | -|---|---| -| `os compile` (`os build`) | Compila `objectstack.config.ts` → `dist/objectstack.json` | -| `os validate` | Valida la configuración contra el esquema del protocolo | -| `os lint` | Comprobaciones de estilo y convenciones (recomendado en CI) | -| `os diff ` | Compara dos configuraciones, detecta cambios incompatibles | -| `os info` | Imprime un resumen de metadatos de una configuración o artefacto | -| `os explain ` | Explicación legible del esquema de un objeto | -| `os doctor` | Chequeo de salud: detecta dependencias circulares, referencias rotas, problemas de entorno | -| `os generate` (`os g`) | Genera tipos de TypeScript / archivos de metadatos | - -`os doctor` es **lo primero que debes ejecutar cuando algo parece ir mal** — detecta -configuraciones erróneas que el runtime solo mostraría como una advertencia en tiempo -de ejecución. - -## Comandos de datos - -Operan sobre registros desde la terminal — útiles para sembrar datos, migraciones -y pruebas de humo en 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 -``` - -## Comandos de metadatos - -Lee/escribe registros de metadatos (objetos, vistas, conjuntos de permisos, …) en -tiempo de ejecución. - -```bash -os meta list -os meta get -os meta register -os meta delete -``` - -## Comandos de i18n - -```bash -os i18n extract # extract translation keys from source -os i18n check # find missing keys across configured locales -``` - -## Comandos de la nube - -Para usuarios de ObjectStack Cloud (el plano de control alojado opcional). - -```bash -os login # interactive -os logout -os whoami -os register # create an account -os cloud login | logout | whoami -``` - -## Comandos de publicación / empaquetado - -```bash -os package publish # publish artifact as a versioned package -``` - -## Comandos de entorno - -Para despliegues que usan múltiples entornos por proyecto (dev, staging, -prod) respaldados por un plano de control. - -```bash -os environments list -os environments show -os environments create -os environments switch -os environments bind # bind local artifact to an environment -``` - -## Comando de prueba - -```bash -os test # run Quality Protocol scenarios against a running server -``` - -## Convenciones comunes de flags - -| Flag | Significado | -|---|---| -| `-p, --port` | Puerto HTTP | -| `-a, --artifact` | Ruta o URL al artefacto compilado | -| `-d, --database` | URL de la base de datos | -| `--home` | Directorio de estado persistente | -| `-v, --verbose` | Salida detallada | -| `--no-ui` | Deshabilita los portales Console / Account | - -Ejecuta cualquier comando con `--help` para ver la lista completa de flags: - -```bash -os start --help -os data query --help -``` - -## Dónde encaja la CLI - -- **Operador / primer arranque** → `os start` -- **Desarrollador que construye una app** → `os init` → `os dev` → `os compile` -- **Pipeline de CI / release** → `os lint && os validate && os compile && os test` -- **Runtime de producción** → `os serve` (normalmente dentro del `CMD` de la imagen Docker) -- **Diagnóstico** → `os doctor`, `os info`, `os explain` diff --git a/content/docs/reference/cli.fr.mdx b/content/docs/reference/cli.fr.mdx deleted file mode 100644 index 65b0ffb..0000000 --- a/content/docs/reference/cli.fr.mdx +++ /dev/null @@ -1,206 +0,0 @@ ---- -title: Référence de la CLI -description: Chaque commande `os`, ce qu'elle fait, et les options les plus utiles. ---- - -Le paquet `@objectstack/cli` installe un binaire unique, `os` (également -disponible sous le nom `objectstack`). Tous les exemples ci-dessous utilisent la forme plus courte `os`. - -```bash -npm i -g @objectstack/cli -os --help -``` - -## Commandes du serveur - -### `os start` — démarrage sans configuration - -Détecte automatiquement 4 modes croissants : - -1. **Démarrage vide** — aucun artefact, aucune configuration dans le répertoire courant → démarre un - kernel minimal avec Console + marketplace. -2. **Démarrage de projet** — `objectstack.config.ts` dans le répertoire courant → compile automatiquement - vers `./dist/objectstack.json` et démarre à partir de celui-ci. -3. **Démarrage d'artefact** — `dist/objectstack.json` accessible → démarre directement - à partir de celui-ci. -4. **Surcharges explicites** — `--artifact`, `--database`, `--port` l'emportent. - -```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 Console/Account) -``` - -Répertoire HOME par défaut : -- avec une configuration de projet dans le répertoire courant → `/.objectstack` (local au projet) -- sans → `~/.objectstack` (global, partagé entre les invocations) - -### `os serve` — serveur de production - -Lit `objectstack.config.ts` s'il est présent, sinon se rabat sur -`dist/objectstack.json` (ou `OS_ARTIFACT_PATH`, y compris les URL `http(s)://`). -Utilisez cette commande dans les conteneurs de production lorsque vous voulez un comportement strict. - -```bash -os serve # port 3000 -os serve --port 4000 --no-ui -``` - -### `os dev` — développement avec rechargement à chaud - -Surveille `objectstack.config.ts` et `src/`. Recompile + recharge à chaque -enregistrement. Utilisé comme script npm `dev` dans les projets générés. - -```bash -os dev # port 3002 by default -os dev -p 4002 -``` - -### `os studio` — Console avec serveur de développement - -Identique à `os dev` mais avec la Console explicitement activée. - -## Commandes de projet - -### `os init` — générer un nouveau projet - -```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 -``` - -Modèles : -| Modèle | Ce qu'il vous fournit | -|---|---| -| `app` | Application complète — objets, vues, actions, prête à étendre | -| `plugin` | Squelette de plugin pour distribuer des capacités réutilisables | -| `empty` | Manifeste + tsconfig uniquement | - -### `os create` — créer un package, un plugin ou un exemple à partir d'un modèle - -```bash -os create plugin my-plugin -os create example my-example -``` - -## Commandes de build / validation - -| Commande | Objectif | -|---|---| -| `os compile` (`os build`) | Compile `objectstack.config.ts` → `dist/objectstack.json` | -| `os validate` | Valide la configuration par rapport au schéma du protocole | -| `os lint` | Vérifications de style et de conventions (recommandé en CI) | -| `os diff ` | Compare deux configurations, détecte les changements incompatibles | -| `os info` | Affiche un résumé des métadonnées d'une configuration ou d'un artefact | -| `os explain ` | Explication lisible du schéma d'un objet | -| `os doctor` | Bilan de santé : détecte les dépendances circulaires, les références cassées, les problèmes d'environnement | -| `os generate` (`os g`) | Génère les types TypeScript / fichiers de métadonnées | - -`os doctor` est la **première chose à exécuter lorsque quelque chose semble anormal** — elle -détecte les mauvaises configurations que le runtime ne ferait remonter que sous forme d'avertissement -à l'exécution. - -## Commandes de données - -Opèrent sur les enregistrements depuis le terminal — utiles pour l'initialisation, les migrations -et les tests de fumée en 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 -``` - -## Commandes de métadonnées - -Lecture/écriture des enregistrements de métadonnées (objets, vues, ensembles de permissions, …) à -l'exécution. - -```bash -os meta list -os meta get -os meta register -os meta delete -``` - -## Commandes i18n - -```bash -os i18n extract # extract translation keys from source -os i18n check # find missing keys across configured locales -``` - -## Commandes Cloud - -Pour les utilisateurs d'ObjectStack Cloud (le plan de contrôle hébergé optionnel). - -```bash -os login # interactive -os logout -os whoami -os register # create an account -os cloud login | logout | whoami -``` - -## Commandes de publication / packaging - -```bash -os package publish # publish artifact as a versioned package -``` - -## Commandes d'environnement - -Pour les déploiements utilisant plusieurs environnements par projet (dev, staging, -prod) adossés à un plan de contrôle. - -```bash -os environments list -os environments show -os environments create -os environments switch -os environments bind # bind local artifact to an environment -``` - -## Commande de test - -```bash -os test # run Quality Protocol scenarios against a running server -``` - -## Conventions courantes des options - -| Option | Signification | -|---|---| -| `-p, --port` | Port HTTP | -| `-a, --artifact` | Chemin ou URL vers l'artefact compilé | -| `-d, --database` | URL de la base de données | -| `--home` | Répertoire d'état persistant | -| `-v, --verbose` | Sortie détaillée | -| `--no-ui` | Désactive les portails Console / Account | - -Exécutez n'importe quelle commande avec `--help` pour la liste complète des options : - -```bash -os start --help -os data query --help -``` - -## Où la CLI s'inscrit - -- **Opérateur / premier lancement** → `os start` -- **Développeur construisant une application** → `os init` → `os dev` → `os compile` -- **Pipeline CI / de release** → `os lint && os validate && os compile && os test` -- **Runtime de production** → `os serve` (généralement à l'intérieur du `CMD` de l'image Docker) -- **Diagnostics** → `os doctor`, `os info`, `os explain` diff --git a/content/docs/reference/cli.ja.mdx b/content/docs/reference/cli.ja.mdx deleted file mode 100644 index 7550762..0000000 --- a/content/docs/reference/cli.ja.mdx +++ /dev/null @@ -1,206 +0,0 @@ ---- -title: CLI リファレンス -description: すべての `os` コマンド、その機能、そして最も役立つフラグ。 ---- - -`@objectstack/cli` パッケージは単一のバイナリ `os`（`objectstack` としても -利用可能）をインストールします。以下の例ではすべて短い `os` を使用します。 - -```bash -npm i -g @objectstack/cli -os --help -``` - -## サーバーコマンド - -### `os start` — ゼロコンフィグ起動 - -段階的にエスカレートする 4 つのモードを自動検出します。 - -1. **空起動** — アーティファクトなし、cwd に設定なし → Console と marketplace - を備えた最小限のカーネルを起動します。 -2. **プロジェクト起動** — cwd に `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 Console/Account) -``` - -HOME ディレクトリのデフォルト: -- cwd にプロジェクト設定がある場合 → `/.objectstack`（プロジェクトローカル） -- ない場合 → `~/.objectstack`（グローバル、呼び出し間で共有） - -### `os serve` — 本番サーバー - -`objectstack.config.ts` が存在すればそれを読み込み、なければ -`dist/objectstack.json`（または `OS_ARTIFACT_PATH`、`http(s)://` URL を含む）に -フォールバックします。厳格な動作が必要な本番コンテナで使用してください。 - -```bash -os serve # port 3000 -os serve --port 4000 --no-ui -``` - -### `os dev` — ホットリロード付き開発 - -`objectstack.config.ts` と `src/` を監視します。保存時に再コンパイルして -リロードします。スキャフォールドされたプロジェクトで npm の `dev` スクリプトとして -使用されます。 - -```bash -os dev # port 3002 by default -os dev -p 4002 -``` - -### `os studio` — 開発サーバー付き Console - -`os dev` と同じですが、Console が明示的に有効化されています。 - -## プロジェクトコマンド - -### `os init` — 新しいプロジェクトのスキャフォールド - -```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` — テンプレートからパッケージ、プラグイン、または例を作成 - -```bash -os create plugin my-plugin -os create example my-example -``` - -## ビルド / 検証コマンド - -| コマンド | 目的 | -|---|---| -| `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 doctor` は **何かおかしいと感じたときに最初に実行すべきもの** です。 -ランタイムが警告としてのみ表面化させるような設定ミスを捕捉します。 - -## データコマンド - -ターミナルからレコードを操作します — シーディング、マイグレーション、 -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 -``` - -## メタデータコマンド - -ランタイムでメタデータレコード（オブジェクト、ビュー、パーミッションセットなど）を -読み書きします。 - -```bash -os meta list -os meta get -os meta register -os meta delete -``` - -## i18n コマンド - -```bash -os i18n extract # extract translation keys from source -os i18n check # find missing keys across configured locales -``` - -## クラウドコマンド - -ObjectStack Cloud（オプションのホスト型コントロールプレーン）のユーザー向けです。 - -```bash -os login # interactive -os logout -os whoami -os register # create an account -os cloud login | logout | whoami -``` - -## パブリッシュ / パッケージコマンド - -```bash -os package publish # publish artifact as a versioned package -``` - -## 環境コマンド - -コントロールプレーンに支えられた、プロジェクトごとに複数の環境（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 -``` - -## テストコマンド - -```bash -os test # run Quality Protocol scenarios against a running server -``` - -## 共通のフラグ規約 - -| フラグ | 意味 | -|---|---| -| `-p, --port` | HTTP ポート | -| `-a, --artifact` | コンパイル済みアーティファクトへのパスまたは URL | -| `-d, --database` | データベース URL | -| `--home` | 永続的な状態ディレクトリ | -| `-v, --verbose` | 詳細な出力 | -| `--no-ui` | Console / Account ポータルを無効化 | - -完全なフラグ一覧を表示するには、任意のコマンドを `--help` 付きで実行します。 - -```bash -os start --help -os data query --help -``` - -## CLI の位置づけ - -- **オペレーター / 初回実行** → `os start` -- **アプリを構築する開発者** → `os init` → `os dev` → `os compile` -- **CI / リリースパイプライン** → `os lint && os validate && os compile && os test` -- **本番ランタイム** → `os serve`（通常は Docker イメージの `CMD` 内） -- **診断** → `os doctor`、`os info`、`os explain` diff --git a/content/docs/reference/cli.ko.mdx b/content/docs/reference/cli.ko.mdx deleted file mode 100644 index 6106c1a..0000000 --- a/content/docs/reference/cli.ko.mdx +++ /dev/null @@ -1,205 +0,0 @@ ---- -title: CLI 레퍼런스 -description: 모든 `os` 명령어와 그 기능, 그리고 가장 유용한 플래그. ---- - -`@objectstack/cli` 패키지는 단일 바이너리 `os`(별칭 `objectstack`로도 -사용 가능)를 설치합니다. 아래의 모든 예제는 더 짧은 `os`를 사용합니다. - -```bash -npm i -g @objectstack/cli -os --help -``` - -## 서버 명령어 - -### `os start` — 설정 없는 부팅 - -4가지 단계적 모드를 자동으로 감지합니다: - -1. **빈 부팅(Empty boot)** — cwd에 아티팩트도 설정도 없음 → Console과 - marketplace가 포함된 최소한의 커널을 부팅합니다. -2. **프로젝트 부팅(Project boot)** — cwd에 `objectstack.config.ts`가 있음 → - `./dist/objectstack.json`으로 자동 컴파일한 뒤 그것으로 부팅합니다. -3. **아티팩트 부팅(Artifact boot)** — `dist/objectstack.json`에 접근 가능 → - 그것으로 직접 부팅합니다. -4. **명시적 재정의(Explicit overrides)** — `--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 Console/Account) -``` - -HOME 디렉터리 기본값: -- cwd에 프로젝트 설정이 있을 때 → `/.objectstack` (프로젝트 로컬) -- 없을 때 → `~/.objectstack` (전역, 호출 간 공유) - -### `os serve` — 프로덕션 서버 - -`objectstack.config.ts`가 있으면 이를 읽고, 없으면 `dist/objectstack.json` -(또는 `http(s)://` URL을 포함한 `OS_ARTIFACT_PATH`)으로 대체합니다. -엄격한 동작을 원하는 프로덕션 컨테이너에서 사용하세요. - -```bash -os serve # port 3000 -os serve --port 4000 --no-ui -``` - -### `os dev` — 핫 리로드를 지원하는 개발 - -`objectstack.config.ts`와 `src/`를 감시합니다. 저장 시 재컴파일 및 -리로드합니다. 스캐폴딩된 프로젝트에서 npm `dev` 스크립트로 사용됩니다. - -```bash -os dev # port 3002 by default -os dev -p 4002 -``` - -### `os studio` — 개발 서버가 포함된 Console - -`os dev`와 동일하지만 Console이 명시적으로 활성화됩니다. - -## 프로젝트 명령어 - -### `os init` — 새 프로젝트 스캐폴딩 - -```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` — 템플릿에서 패키지, 플러그인 또는 예제 생성 - -```bash -os create plugin my-plugin -os create example my-example -``` - -## 빌드 / 검증 명령어 - -| 명령어 | 목적 | -|---|---| -| `os compile` (`os build`) | `objectstack.config.ts` → `dist/objectstack.json` 컴파일 | -| `os validate` | 프로토콜 스키마에 대해 설정을 검증 | -| `os lint` | 스타일 및 규칙 검사 (CI에서 권장) | -| `os diff ` | 두 설정을 비교하여 호환성 깨짐(breaking changes) 감지 | -| `os info` | 설정 또는 아티팩트의 메타데이터 요약 출력 | -| `os explain ` | 오브젝트 스키마에 대한 사람이 읽기 쉬운 설명 | -| `os doctor` | 상태 점검: 순환 의존성, 깨진 참조, 환경 문제 감지 | -| `os generate` (`os g`) | TypeScript 타입 / 메타데이터 파일 생성 | - -`os doctor`는 **무언가 이상하다고 느껴질 때 가장 먼저 실행해야 할 명령어**입니다. -런타임이 런타임 경고로만 드러낼 잘못된 설정을 잡아냅니다. - -## 데이터 명령어 - -터미널에서 레코드를 조작합니다 — 시딩, 마이그레이션, 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 -``` - -## 메타데이터 명령어 - -런타임에 메타데이터 레코드(오브젝트, 뷰, 권한 세트 등)를 읽고 씁니다. - -```bash -os meta list -os meta get -os meta register -os meta delete -``` - -## i18n 명령어 - -```bash -os i18n extract # extract translation keys from source -os i18n check # find missing keys across configured locales -``` - -## 클라우드 명령어 - -ObjectStack Cloud(선택적 호스팅 컨트롤 플레인) 사용자를 위한 명령어입니다. - -```bash -os login # interactive -os logout -os whoami -os register # create an account -os cloud login | logout | whoami -``` - -## 게시 / 패키지 명령어 - -```bash -os package publish # publish artifact as a versioned package -``` - -## 환경 명령어 - -컨트롤 플레인을 기반으로 프로젝트당 여러 환경(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 -``` - -## 테스트 명령어 - -```bash -os test # run Quality Protocol scenarios against a running server -``` - -## 공통 플래그 규칙 - -| 플래그 | 의미 | -|---|---| -| `-p, --port` | HTTP 포트 | -| `-a, --artifact` | 컴파일된 아티팩트의 경로 또는 URL | -| `-d, --database` | 데이터베이스 URL | -| `--home` | 영구 상태 디렉터리 | -| `-v, --verbose` | 상세 출력 | -| `--no-ui` | Console / Account 포털 비활성화 | - -전체 플래그 목록을 보려면 어떤 명령어든 `--help`와 함께 실행하세요: - -```bash -os start --help -os data query --help -``` - -## CLI의 위치 - -- **운영자 / 첫 실행** → `os start` -- **앱을 개발하는 개발자** → `os init` → `os dev` → `os compile` -- **CI / 릴리스 파이프라인** → `os lint && os validate && os compile && os test` -- **프로덕션 런타임** → `os serve` (일반적으로 Docker 이미지의 `CMD` 내부) -- **진단** → `os doctor`, `os info`, `os explain` diff --git a/content/docs/reference/cli.mdx b/content/docs/reference/cli.mdx index 0c256d9..b5d44ff 100644 --- a/content/docs/reference/cli.mdx +++ b/content/docs/reference/cli.mdx @@ -45,8 +45,16 @@ HOME directory default: ### `os serve` — production server Reads `objectstack.config.ts` if present, otherwise falls back to -`dist/objectstack.json` (or `OS_ARTIFACT_PATH`, including `http(s)://` URLs). -Use this in production containers when you want strict behavior. +`dist/objectstack.json`. Use this in production containers when you want +strict behavior. + +To boot a **published** artifact instead, name it with `OS_ARTIFACT_URL` — an +absolute `https://`, `http://` or `file://` URL, with an optional `#sha256=` +integrity pin in the fragment. It is resolved before any configuration is +read. The older `OS_ARTIFACT_PATH` spelling is retired: on the ObjectOS +runtime image a non-default value **refuses the boot** and names the +replacement. See +[Environment Variables](/docs/reference/environment-variables#retired-names). ```bash os serve # port 3000 diff --git a/content/docs/reference/cli.zh-Hans.mdx b/content/docs/reference/cli.zh-Hans.mdx deleted file mode 100644 index 08b0b26..0000000 --- a/content/docs/reference/cli.zh-Hans.mdx +++ /dev/null @@ -1,197 +0,0 @@ ---- -title: CLI 参考 -description: 每个 `os` 命令的作用以及最有用的 flag。 ---- - -`@objectstack/cli` 包安装单个二进制文件 `os`（也可作为 `objectstack`）。下面所有示例使用更短的 `os`。 - -```bash -npm i -g @objectstack/cli -os --help -``` - -## Server 命令 - -### `os start` —— 零配置启动 - -自动检测 4 种递进模式： - -1. **空启动** —— 当前目录无 artifact、无 config → 启动一个带 Console + marketplace 的裸内核。 -2. **项目启动** —— 当前目录有 `objectstack.config.ts` → 自动编译到 `./dist/objectstack.json` 并从中启动。 -3. **Artifact 启动** —— 可访问 `dist/objectstack.json` → 直接从中启动。 -4. **显式覆盖** —— `--artifact`、`--database`、`--port` 优先。 - -```bash -os start # 默认端口 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 # 持久化 home 目录 -os start --no-ui # 仅 API（无 Console/Account） -``` - -HOME 目录默认值： -- 当前目录有项目 config → `/.objectstack`（项目本地） -- 无 → `~/.objectstack`（全局,跨调用共享） - -### `os serve` —— 生产服务器 - -如果存在则读取 `objectstack.config.ts`,否则回退到 `dist/objectstack.json`（或 `OS_ARTIFACT_PATH`,包括 `http(s)://` URL）。在希望严格行为的生产容器中使用此命令。 - -```bash -os serve # 端口 3000 -os serve --port 4000 --no-ui -``` - -### `os dev` —— 带热重载的开发模式 - -监听 `objectstack.config.ts` 和 `src/`。保存时重新编译并重载。脚手架项目中作为 npm `dev` 脚本使用。 - -```bash -os dev # 默认端口 3002 -os dev -p 4002 -``` - -### `os studio` —— 带开发服务器的 Console - -与 `os dev` 相同,但显式启用 Console。 - -## 项目命令 - -### `os init` —— 脚手架新项目 - -```bash -os init my-app # 交互式 -os init my-app -t app --install # 默认 pnpm 自动安装 -os init my-app -t app --install -p npm -os init my-app -t plugin # 插件脚手架 -os init my-app -t empty # 最小骨架 -``` - -模板： -| 模板 | 提供内容 | -|---|---| -| `app` | 完整应用 —— 对象、视图、Action,可扩展 | -| `plugin` | 用于分发可复用能力的插件脚手架 | -| `empty` | 仅 manifest + tsconfig | - -### `os create` —— 从模板创建包、插件或示例 - -```bash -os create plugin my-plugin -os create example my-example -``` - -## 构建/校验命令 - -| 命令 | 用途 | -|---|---| -| `os compile` (`os build`) | 编译 `objectstack.config.ts` → `dist/objectstack.json` | -| `os validate` | 根据协议 schema 校验 config | -| `os lint` | 风格和约定检查（推荐在 CI 中使用） | -| `os diff ` | 比较两个 config,检测破坏性变更 | -| `os info` | 打印 config 或 artifact 的元数据摘要 | -| `os explain ` | 对象 schema 的可读说明 | -| `os doctor` | 健康检查：检测循环依赖、断裂引用、环境问题 | -| `os generate` (`os g`) | 生成 TypeScript 类型/元数据文件 | -| `os db clean` | 一次性 SQLite `VACUUM` + 开启增量 auto-vacuum；报告回收字节数（14.5+） | - -`os doctor` 是**感觉不对劲时首先要运行的命令** —— 它能捕获运行时只会以警告呈现的配置错误。 - -自 ObjectStack 13 起，`os compile` 还会以**安全态势**闸门构建：`validateSecurityPosture` 错误（未设置/使用别名的共享模型、高权限锚点绑定、遗留角色词汇、未带对象限定的字段权限键等）会导致构建失败，`os lint` 则在更早阶段报告它们。如果提交了 `access-matrix.json` 快照，任何权限能力漂移都会让 `os compile` 失败，直到用 `--update-access-matrix` 重新生成快照——每次能力变更都变得可审查。 - -## 数据命令 - -从终端操作记录 —— 用于种子数据、迁移和 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 -``` - -## 元数据命令 - -在运行时读写元数据记录（对象、视图、权限集……）。 - -```bash -os meta list -os meta get -os meta register -os meta delete -``` - -## i18n 命令 - -```bash -os i18n extract # 从源码提取翻译键 -os i18n check # 查找已配置 locale 间缺失的键 -``` - -## Cloud 命令 - -供 ObjectStack Cloud（可选托管控制平面）用户使用。 - -```bash -os login # 交互式 -os logout -os whoami -os register # 创建账户 -os cloud login | logout | whoami -``` - -## 发布/打包命令 - -```bash -os package publish # 将 artifact 作为版本化包发布 -``` - -## 环境命令 - -适用于每个项目使用多环境（dev、staging、prod）并由控制平面支持的部署。 - -```bash -os environments list -os environments show -os environments create -os environments switch -os environments bind # 将本地 artifact 绑定到一个环境 -``` - -## 测试命令 - -```bash -os test # 针对运行中的服务器执行 Quality Protocol 场景 -``` - -## 常用 flag 约定 - -| Flag | 含义 | -|---|---| -| `-p, --port` | HTTP 端口 | -| `-a, --artifact` | 已编译 artifact 的路径或 URL | -| `-d, --database` | 数据库 URL | -| `--home` | 持久化状态目录 | -| `-v, --verbose` | 详细输出 | -| `--no-ui` | 禁用 Console / Account 门户 | - -任意命令带 `--help` 查看完整 flag 列表： - -```bash -os start --help -os data query --help -``` - -## CLI 的角色定位 - -- **运维/首次运行** → `os start` -- **构建应用的开发者** → `os init` → `os dev` → `os compile` -- **CI/发布管道** → `os lint && os validate && os compile && os test` -- **生产运行时** → `os serve`（通常位于 Docker 镜像的 `CMD` 内） -- **诊断** → `os doctor`、`os info`、`os explain` diff --git a/content/docs/reference/environment-variables.de.mdx b/content/docs/reference/environment-variables.de.mdx deleted file mode 100644 index 244009d..0000000 --- a/content/docs/reference/environment-variables.de.mdx +++ /dev/null @@ -1,119 +0,0 @@ ---- -title: Umgebungsvariablen -description: Referenz der ObjectOS-Laufzeitumgebungsvariablen. ---- - -Verwenden Sie Umgebungsvariablen für Konfiguration und Geheimnisse auf Deployment-Ebene. -Verwenden Sie Systemeinstellungen für anwendungsbezogene Konfiguration, die von Mandanten/Benutzern bearbeitet werden kann. - -> **Benennung.** Alle ObjectStack-eigenen Variablen verwenden das Präfix `OS_`. -> Unpräfixierte Pre-1.0-Namen (`PORT`, `AUTH_SECRET`, `OS_MULTI_TENANT`, …) -> funktionieren weiterhin, geben aber eine einmalige Verwarnung zur Veralterung aus. -> Bevorzugen Sie die kanonischen `OS_*`-Namen in neuen Deployments; siehe -> [Veraltete Aliasse](#legacy-aliases). - -## Kern - -| Variable | Erforderlich | Beschreibung | -|---|---:|---| -| `OS_PORT` | Nein | HTTP-Port, auf dem die Laufzeit lauscht. Standardwert ist `3000`. Veralteter Alias: `PORT`. | -| `OS_AUTH_SECRET` | Ja für Auth | Basisgeheimnis, aus dem projektspezifische Auth-Geheimnisse abgeleitet werden. Veralteter Alias: `AUTH_SECRET`. | - -## Artefakt- und Projektauflösung - -| Variable | Erforderlich | Beschreibung | -|---|---:|---| -| `OS_ARTIFACT_FILE` | Dateimodus | Pfad oder `http(s)://`-URL zu einer kompilierten `objectstack.json`. Wird von der ObjectOS-Konfiguration gelesen und als `artifactPath` an `createStandaloneStack` übergeben. Für cloud-verbundene Deployments auf eine veröffentlichte Artifact-URL zeigen lassen. | -| `OS_ARTIFACT_PATH` | Alternative | Framework-Name für denselben Pfad oder dieselbe URL, direkt von `@objectstack/runtime` berücksichtigt (CLI `dev`/`start`). Standard: `/dist/objectstack.json`. | -| `OS_PROJECT_ID` | Optional | Veralteter Alias für `OS_ENVIRONMENT_ID`, der von der ObjectOS-Konfiguration aus Gründen der Abwärtskompatibilität akzeptiert wird. Bevorzugen Sie `OS_ENVIRONMENT_ID` in neuen Deployments. | -| `OS_ENVIRONMENT_ID` | Optional | Umgebungs-ID für den Standalone-Stack (Standard `proj_local`). Wird auch zur Ableitung des projektspezifischen Auth-Geheimnisses verwendet. Die ObjectOS-Konfiguration akzeptiert außerdem den veralteten Alias `OS_PROJECT_ID`. | -| `OS_ORGANIZATION_ID` | Optional | Standard-Organisations-ID für den dateibasierten Modus (Standard `org_local`). | -| `OS_MCP_SERVER_ENABLED` | Nein | Steuert den Model-Context-Protocol-Server über Streamable HTTP unter `/api/v1/mcp` — und nur diese HTTP-Oberfläche. **Standardmäßig an** (16.0+): ungesetzt wird der Endpunkt bereitgestellt; ein explizit falscher Wert (`false`/`0`/`off`/`no`) deaktiviert ihn. Erfordert einen authentifizierten Principal. Legacy: `OS_MCP_SERVER_ENABLED=true` startet für ein weiteres Release zusätzlich den stdio-Transport (mit Deprecation-Warnung) — stattdessen `OS_MCP_STDIO_ENABLED` verwenden. | -| `OS_MCP_STDIO_ENABLED` | Nein | Auf einen wahren Wert (`true`/`1`/`on`/`yes`) setzen, um den langlebigen **stdio**-MCP-Transport automatisch zu starten. Standardmäßig aus und getrennt von `OS_MCP_SERVER_ENABLED` (das nur die HTTP-Oberfläche steuert). Erfordert `OS_MCP_STDIO_API_KEY`. | -| `OS_MCP_STDIO_API_KEY` | Wenn stdio aktiviert ist | API-Schlüssel (`osk_...`), an dessen Principal der stdio-Transport gebunden wird. Wird über dieselbe Verify-/Autorisierungskette wie HTTP-MCP aufgelöst, RLS/FLS und Tenant-Scoping gelten. Fail-closed: Ist stdio-Autostart aktiv und kein auflösbarer Schlüssel vorhanden, verweigert der Server den Start des stdio-Transports. | -| `OS_CLOUD_URL` | Optional | Basis-URL der Steuerungsebene für den Marketplace-Proxy und die lokale Paketinstallation. Auf `off` oder `local` setzen, um Marketplace-Funktionen zu deaktivieren. Wird in der Standalone-Distribution nicht mehr für das Hostname-Routing des Host-Stacks verwendet. | -| `OS_MULTI_ORG_ENABLED` | Nein | Auf `true` setzen, um Multi-Mandanten-Routing / Organisationswechsel zu aktivieren (Standard `false`). Veralteter Alias: `OS_MULTI_TENANT`. | -| `OS_RUNTIME_PORT` | Nur Dev | Localhost-Port, der zum Aufbau von Plattform-SSO-Callback-URLs bei der Entwicklung auf `http://localhost:` verwendet wird. | - -> **Artefakt-Hot-Reload.** Der Standalone-Stack lädt das lokale Artefakt außerhalb -> der Produktion automatisch neu (gesteuert durch `NODE_ENV`); das explizite -> `OS_WATCH_ARTIFACT=1`-Flag aus 7.x ist nicht mehr erforderlich. - -## Cache - -| Variable | Standard | Beschreibung | -|---|---:|---| -| `OS_KERNEL_CACHE_SIZE` | `32` | Maximale Anzahl zwischengespeicherter Projektkernel. | -| `OS_KERNEL_TTL_MS` | `900000` | Leerlauf-TTL für Projektkernel. | -| `OS_ENV_CACHE_TTL_MS` | `300000` | TTL des Umgebungs-/Hostnamen-Caches. | -| `OS_ARTIFACT_CACHE_TTL_MS` | `300000` | TTL des Artefakt-Antwort-Caches. | - -## Auth und vertrauenswürdige Ursprünge - -| Variable | Beschreibung | -|---|---| -| `AUTH_SECRET` | Veralteter Alias für `OS_AUTH_SECRET`. Wird in diesem Release noch berücksichtigt; bevorzugen Sie `OS_AUTH_SECRET`. | -| `OS_TRUSTED_ORIGINS` | Kommagetrennte zusätzliche vertrauenswürdige Ursprünge. | -| `OS_ROOT_DOMAIN` | Root-Domain, die zum Vertrauen von Projekt-Subdomains in Plattform-SSO-Deployments verwendet wird. | -| `OS_PLATFORM_SSO` | Auf `false` setzen, um die Plattform-SSO-Verdrahtung zu deaktivieren. | -| `OS_RUNTIME_PORT` | Hilfe für die lokale Entwicklung von localhost-Projekt-Hostnamen. | - -## Datenbank - -Im cloud-verbundenen Modus gibt die Steuerungsebene die projektspezifische -Laufzeit-Datenbankkonfiguration mit der Artefaktantwort zurück. Im -dateibasierten Modus liest ObjectOS Datenquellendeklarationen aus dem -Artefakt. Als letzten Ausweg berücksichtigt das Framework außerdem: - -| Variable | Beschreibung | -|---|---| -| `OS_DATABASE_URL` | Verbindungs-URL (`file:./db.sqlite`, `libsql://…`, `postgres://…`, `mongodb://…`, `memory://`). Wird vom Standalone-Modus und der CLI `dev` verwendet. | -| `OS_DATABASE_DRIVER` | Überschreibt den aus der URL automatisch erkannten Treiber. | -| `OS_DATABASE_AUTH_TOKEN` | Auth-Token für verwaltete Treiber wie Turso/libSQL. | -| `OS_BUSINESS_DB_URL` | ObjectOS-Wrapper-Konvention für die projektspezifische Geschäftsdatenbank-URL. Lösen Sie sie in Ihrem Deployment zu `OS_DATABASE_URL` oder einer Laufzeit-Datenquellen-Überschreibung auf. | -| `OS_CACHE_DIR` | Lokales Verzeichnis für Artefakt- und Laufzeit-Cache (Standard `/var/cache/objectos`). | -| `OS_SKIP_SCHEMA_SYNC` | Auf `1` setzen, um die ObjectQL-DDL-Synchronisierung beim Start zu überspringen. Verwenden, wenn das Schema außerhalb verwaltet wird. | - -Bevorzugen Sie für ObjectOS-Kundendeployments eine explizite Laufzeitkonfiguration der -Steuerungsebene oder eine Artefakt-Datenquellenkonfiguration, anstatt sich auf -container-lokale Standardwerte zu verlassen. - -## Observability - -Der Export von Traces und Metriken ist opt-in. Der Exporter ist standardmäßig -`noop`, sodass ein Deployment nichts ausgibt, bis Sie einen auswählen — allein -einen Endpunkt zu setzen, bewirkt nichts. - -| Variable | Standard | Beschreibung | -|---|---:|---| -| `OS_OBS_EXPORTER` | `noop` | Telemetrie-Exporter: `noop` \| `console` \| `json` \| `otlp`. Verwenden Sie `console`/`json` für lokales Debugging, `otlp` für einen Collector. | -| `OS_OTLP_ENDPOINT` | — | OTLP/HTTP-Root-URL (z. B. `https://otlp.grafana.net/otlp`). Erforderlich, wenn `OS_OBS_EXPORTER=otlp`; ist sie leer, warnt die Laufzeit und fällt auf `noop` zurück. | -| `OS_OTLP_HEADERS` | — | Zusätzliche OTLP-Header (z. B. Auth) als kommagetrennte `key=value`-Paare. | -| `OS_OBS_SERVICE_NAME` | — | Ressourcenattribut `service.name` auf ausgegebenen Spans/Metriken. | -| `OS_OBS_DEPLOYMENT_ENV` | `production` | Ressourcenattribut `deployment.environment`. | -| `OS_OTLP_FLUSH_MS` | — | Flush-Intervall für den OTLP-Exporter, in Millisekunden. | - -## Überschreibungen von Einstellungs-Namespaces - -Systemeinstellungen (die von Mandanten/Benutzern bearbeitbaren Namespaces `ai`, -`email`, `feature_flags`, …) können auf Deployment-Ebene mit einer -Umgebungsvariablen namens `OS__` festgelegt werden — in -Großbuchstaben, wobei `.` und `-` durch `_` ersetzt werden. Zum Beispiel -`ai.openai_base_url` → `OS_AI_OPENAI_BASE_URL` und `feature_flags.ai_enabled` → -`OS_FEATURE_FLAGS_AI_ENABLED`. Ab 9.0 wurden die unpräfixierten Aliasse -entfernt — die `OS_`-präfixierte Form ist die einzige, die gelesen wird. - -Die Google-Anmeldung (konfigurierbar unter **Setup → Authentication**) liest -außerdem `GOOGLE_CLIENT_ID` und `GOOGLE_CLIENT_SECRET` auf Deployment-Ebene. - -## Veraltete Aliasse - -Diese Pre-1.0-Namen funktionieren in diesem Release noch, geben aber eine einmalige -Verwarnung zur Veralterung aus. Sie werden in einer zukünftigen Hauptversion entfernt. Bevorzugen Sie den kanonischen Namen. - -| Kanonisch | Veraltet | -|---|---| -| `OS_PORT` | `PORT` | -| `OS_AUTH_SECRET` | `AUTH_SECRET` | -| `OS_MULTI_ORG_ENABLED` | `OS_MULTI_TENANT` | -| `OS_ENVIRONMENT_ID` | `OS_PROJECT_ID` | diff --git a/content/docs/reference/environment-variables.es.mdx b/content/docs/reference/environment-variables.es.mdx deleted file mode 100644 index 56b7fc3..0000000 --- a/content/docs/reference/environment-variables.es.mdx +++ /dev/null @@ -1,120 +0,0 @@ ---- -title: Variables de entorno -description: Referencia de variables de entorno del entorno de ejecución de ObjectOS. ---- - -Use variables de entorno para la configuración a nivel de despliegue y los secretos. -Use la configuración del sistema para la configuración de la aplicación editable por inquilino/usuario. - -> **Nomenclatura.** Todas las variables propiedad de ObjectStack usan el prefijo -> `OS_`. Los nombres sin prefijo anteriores a 1.0 (`PORT`, `AUTH_SECRET`, -> `OS_MULTI_TENANT`, …) siguen funcionando, pero emiten una advertencia de -> obsolescencia de una sola vez. Prefiera los nombres canónicos `OS_*` en los -> nuevos despliegues; consulte [Alias heredados](#legacy-aliases). - -## Núcleo - -| Variable | Obligatoria | Descripción | -|---|---:|---| -| `OS_PORT` | No | Puerto HTTP en el que escucha el entorno de ejecución. Por defecto es `3000`. Alias heredado: `PORT`. | -| `OS_AUTH_SECRET` | Sí para auth | Secreto base utilizado para derivar los secretos de autenticación por proyecto. Alias heredado: `AUTH_SECRET`. | - -## Resolución de artefactos y proyectos - -| Variable | Obligatoria | Descripción | -|---|---:|---| -| `OS_ARTIFACT_FILE` | Modo archivo | Ruta o URL `http(s)://` a un `objectstack.json` compilado. Leído por la configuración de ObjectOS y pasado como `artifactPath` a `createStandaloneStack`. Apúntelo a una URL de artefacto publicada en la nube para despliegues conectados a la nube. | -| `OS_ARTIFACT_PATH` | Alternativa | Nombre a nivel de framework para la misma ruta o URL, reconocido directamente por `@objectstack/runtime` (CLI `dev`/`start`). Por defecto `/dist/objectstack.json`. | -| `OS_PROJECT_ID` | Opcional | Alias heredado de `OS_ENVIRONMENT_ID`, aceptado por la configuración de ObjectOS por compatibilidad con versiones anteriores. Prefiera `OS_ENVIRONMENT_ID` en los nuevos despliegues. | -| `OS_ENVIRONMENT_ID` | Opcional | Id de entorno para el stack independiente (por defecto `proj_local`). También se usa para derivar el secreto de autenticación por proyecto. La configuración de ObjectOS también acepta el alias heredado `OS_PROJECT_ID`. | -| `OS_ORGANIZATION_ID` | Opcional | Id de organización por defecto para el modo respaldado por archivo (por defecto `org_local`). | -| `OS_MCP_SERVER_ENABLED` | No | Gobierna el servidor Model Context Protocol sobre Streamable HTTP en `/api/v1/mcp` — y solo esa superficie HTTP. **Activado por defecto** (16.0+): sin definir, el endpoint se sirve; establezca un valor falso explícito (`false`/`0`/`off`/`no`) para desactivarlo. Requiere un principal autenticado. Legado: `OS_MCP_SERVER_ENABLED=true` también arranca el transporte stdio durante una versión más (con aviso de obsolescencia) — use `OS_MCP_STDIO_ENABLED` en su lugar. | -| `OS_MCP_STDIO_ENABLED` | No | Establézcalo en un valor verdadero (`true`/`1`/`on`/`yes`) para arrancar automáticamente el transporte MCP **stdio** de larga duración. Desactivado por defecto y separado de `OS_MCP_SERVER_ENABLED` (que gobierna solo la superficie HTTP). Requiere `OS_MCP_STDIO_API_KEY`. | -| `OS_MCP_STDIO_API_KEY` | Cuando stdio está habilitado | Clave de API (`osk_...`) a cuyo principal se vincula el transporte stdio. Se resuelve por la misma cadena de verificación y autorización que HTTP MCP, por lo que se aplican RLS/FLS y el alcance de tenant. Falla cerrado: con el autoarranque de stdio habilitado y sin una clave resoluble, el servidor se niega a iniciar el transporte stdio. | -| `OS_CLOUD_URL` | Opcional | URL base del plano de control para el proxy del marketplace y la instalación local de paquetes. Establézcalo en `off` o `local` para deshabilitar las funciones del marketplace. Ya no se usa para el enrutamiento por nombre de host del host-stack en la distribución independiente. | -| `OS_MULTI_ORG_ENABLED` | No | Establézcalo en `true` para habilitar el enrutamiento multiinquilino / cambio de organización (por defecto `false`). Alias heredado: `OS_MULTI_TENANT`. | -| `OS_RUNTIME_PORT` | Solo desarrollo | Puerto de localhost utilizado para construir las URL de callback de SSO de plataforma al desarrollar en `http://localhost:`. | - -> **Recarga en caliente del artefacto.** El stack independiente recarga el artefacto -> local automáticamente fuera de producción (controlado por `NODE_ENV`); el indicador -> explícito `OS_WATCH_ARTIFACT=1` de 7.x ya no es necesario. - -## Caché - -| Variable | Por defecto | Descripción | -|---|---:|---| -| `OS_KERNEL_CACHE_SIZE` | `32` | Máximo de kernels de proyecto en caché. | -| `OS_KERNEL_TTL_MS` | `900000` | TTL de inactividad para los kernels de proyecto. | -| `OS_ENV_CACHE_TTL_MS` | `300000` | TTL de la caché de entorno/nombre de host. | -| `OS_ARTIFACT_CACHE_TTL_MS` | `300000` | TTL de la caché de respuestas de artefactos. | - -## Autenticación y orígenes de confianza - -| Variable | Descripción | -|---|---| -| `AUTH_SECRET` | Alias heredado de `OS_AUTH_SECRET`. Aún reconocido en esta versión; prefiera `OS_AUTH_SECRET`. | -| `OS_TRUSTED_ORIGINS` | Orígenes de confianza adicionales separados por comas. | -| `OS_ROOT_DOMAIN` | Dominio raíz utilizado para confiar en los subdominios de proyecto en despliegues de SSO de plataforma. | -| `OS_PLATFORM_SSO` | Establézcalo en `false` para desactivar el cableado del SSO de plataforma. | -| `OS_RUNTIME_PORT` | Ayudante de desarrollo local para los nombres de host de proyecto en localhost. | - -## Base de datos - -En el modo conectado a la nube, el plano de control devuelve la configuración de la base de datos -del entorno de ejecución por proyecto junto con la respuesta del artefacto. En -el modo respaldado por archivo, ObjectOS lee las declaraciones de origen de datos del -artefacto. Como último recurso, el framework también reconoce: - -| Variable | Descripción | -|---|---| -| `OS_DATABASE_URL` | URL de conexión (`file:./db.sqlite`, `libsql://…`, `postgres://…`, `mongodb://…`, `memory://`). Utilizada por el modo independiente y la CLI `dev`. | -| `OS_DATABASE_DRIVER` | Anula el controlador detectado automáticamente a partir de la URL. | -| `OS_DATABASE_AUTH_TOKEN` | Token de autenticación para controladores gestionados como Turso/libSQL. | -| `OS_BUSINESS_DB_URL` | Convención del envoltorio de ObjectOS para la URL de la base de datos de negocio por proyecto. Resuélvala a `OS_DATABASE_URL` o a una anulación de origen de datos del entorno de ejecución en su despliegue. | -| `OS_CACHE_DIR` | Directorio local de caché de artefactos y del entorno de ejecución (por defecto `/var/cache/objectos`). | -| `OS_SKIP_SCHEMA_SYNC` | Establézcalo en `1` para omitir la sincronización de DDL de ObjectQL en el arranque. Úselo cuando el esquema se gestiona de forma externa. | - -Para los despliegues de clientes de ObjectOS, prefiera la configuración explícita del entorno de ejecución -del plano de control o la configuración de origen de datos del artefacto en lugar de depender de los valores -por defecto locales del contenedor. - -## Observabilidad - -La exportación de trazas y métricas es opcional. El exportador es `noop` por -defecto, por lo que un despliegue no emite nada hasta que seleccione uno: -establecer únicamente un endpoint no hace nada. - -| Variable | Por defecto | Descripción | -|---|---:|---| -| `OS_OBS_EXPORTER` | `noop` | Exportador de telemetría: `noop` \| `console` \| `json` \| `otlp`. Use `console`/`json` para depuración local y `otlp` para un collector. | -| `OS_OTLP_ENDPOINT` | — | URL raíz de OTLP/HTTP (p. ej. `https://otlp.grafana.net/otlp`). Obligatoria cuando `OS_OBS_EXPORTER=otlp`; si está vacía, el entorno de ejecución advierte y vuelve a `noop`. | -| `OS_OTLP_HEADERS` | — | Cabeceras OTLP adicionales (p. ej. autenticación) como pares `key=value` separados por comas. | -| `OS_OBS_SERVICE_NAME` | — | Atributo de recurso `service.name` en las trazas/métricas emitidas. | -| `OS_OBS_DEPLOYMENT_ENV` | `production` | Atributo de recurso `deployment.environment`. | -| `OS_OTLP_FLUSH_MS` | — | Intervalo de vaciado del exportador OTLP, en milisegundos. | - -## Anulaciones de espacios de nombres de configuración - -La configuración del sistema (los espacios de nombres `ai`, `email`, -`feature_flags`, … editables por inquilino/usuario) puede fijarse a nivel de -despliegue con una variable de entorno llamada `OS__` —en -mayúsculas, con `.` y `-` reemplazados por `_`. Por ejemplo, -`ai.openai_base_url` → `OS_AI_OPENAI_BASE_URL`, y -`feature_flags.ai_enabled` → `OS_FEATURE_FLAGS_AI_ENABLED`. A partir de 9.0 se -eliminaron los alias sin prefijo: la forma con prefijo `OS_` es la única que se -lee. - -El inicio de sesión con Google (configurable en **Setup → Authentication**) -también lee `GOOGLE_CLIENT_ID` y `GOOGLE_CLIENT_SECRET` a nivel de despliegue. - -## Alias heredados - -Estos nombres anteriores a 1.0 siguen funcionando en esta versión, pero emiten una advertencia de obsolescencia -de una sola vez. Se eliminarán en una versión mayor futura. Prefiera el nombre canónico. - -| Canónico | Heredado | -|---|---| -| `OS_PORT` | `PORT` | -| `OS_AUTH_SECRET` | `AUTH_SECRET` | -| `OS_MULTI_ORG_ENABLED` | `OS_MULTI_TENANT` | -| `OS_ENVIRONMENT_ID` | `OS_PROJECT_ID` | diff --git a/content/docs/reference/environment-variables.fr.mdx b/content/docs/reference/environment-variables.fr.mdx deleted file mode 100644 index e0bd001..0000000 --- a/content/docs/reference/environment-variables.fr.mdx +++ /dev/null @@ -1,118 +0,0 @@ ---- -title: Variables d'environnement -description: Référence des variables d'environnement d'exécution d'ObjectOS. ---- - -Utilisez les variables d'environnement pour la configuration au niveau du déploiement et les secrets. -Utilisez les paramètres système pour la configuration applicative modifiable par le locataire ou l'utilisateur. - -> **Nommage.** Toutes les variables appartenant à ObjectStack utilisent le -> préfixe `OS_`. Les noms sans préfixe antérieurs à la version 1.0 (`PORT`, `AUTH_SECRET`, `OS_MULTI_TENANT`, -> …) fonctionnent toujours mais émettent un avertissement de dépréciation unique. Préférez les noms canoniques -> `OS_*` dans les nouveaux déploiements ; voir [Alias hérités](#legacy-aliases). - -## Cœur - -| Variable | Requis | Description | -|---|---:|---| -| `OS_PORT` | Non | Port HTTP sur lequel le runtime écoute. Par défaut `3000`. Alias hérité : `PORT`. | -| `OS_AUTH_SECRET` | Oui pour l'authentification | Secret de base utilisé pour dériver les secrets d'authentification par projet. Alias hérité : `AUTH_SECRET`. | - -## Résolution des artefacts et des projets - -| Variable | Requis | Description | -|---|---:|---| -| `OS_ARTIFACT_FILE` | Mode fichier | Chemin ou URL `http(s)://` vers un `objectstack.json` compilé. Lu par la configuration ObjectOS et transmis en tant que `artifactPath` à `createStandaloneStack`. Pointez-le vers une URL d'artefact publiée pour les déploiements connectés au cloud. | -| `OS_ARTIFACT_PATH` | Alternative | Nom au niveau du framework pour le même chemin ou la même URL, pris en charge directement par `@objectstack/runtime` (CLI `dev`/`start`). Par défaut `/dist/objectstack.json`. | -| `OS_PROJECT_ID` | Optionnel | Alias hérité pour `OS_ENVIRONMENT_ID`, accepté par la configuration ObjectOS pour des raisons de rétrocompatibilité. Préférez `OS_ENVIRONMENT_ID` dans les nouveaux déploiements. | -| `OS_ENVIRONMENT_ID` | Optionnel | Identifiant d'environnement pour le stack autonome (par défaut `proj_local`). Également utilisé pour dériver le secret d'authentification par projet. La configuration ObjectOS accepte aussi l'alias hérité `OS_PROJECT_ID`. | -| `OS_ORGANIZATION_ID` | Optionnel | Identifiant d'organisation par défaut pour le mode adossé à un fichier (par défaut `org_local`). | -| `OS_MCP_SERVER_ENABLED` | Non | Gouverne le serveur Model Context Protocol via Streamable HTTP sur `/api/v1/mcp` — et uniquement cette surface HTTP. **Activé par défaut** (16.0+) : non défini, l'endpoint est servi ; définissez une valeur explicitement fausse (`false`/`0`/`off`/`no`) pour le désactiver. Requiert un principal authentifié. Héritage : `OS_MCP_SERVER_ENABLED=true` démarre aussi le transport stdio pendant encore une version (avec avertissement de dépréciation) — utilisez plutôt `OS_MCP_STDIO_ENABLED`. | -| `OS_MCP_STDIO_ENABLED` | Non | Définissez une valeur vraie (`true`/`1`/`on`/`yes`) pour démarrer automatiquement le transport MCP **stdio** de longue durée. Désactivé par défaut et distinct de `OS_MCP_SERVER_ENABLED` (qui ne gouverne que la surface HTTP). Requiert `OS_MCP_STDIO_API_KEY`. | -| `OS_MCP_STDIO_API_KEY` | Quand stdio est activé | Clé d'API (`osk_...`) au principal de laquelle le transport stdio est lié. Résolue via la même chaîne de vérification et d'autorisation que MCP HTTP : RLS/FLS et le périmètre de tenant s'appliquent. Fail-closed : si le démarrage automatique stdio est activé sans clé résoluble, le serveur refuse de démarrer le transport stdio. | -| `OS_CLOUD_URL` | Optionnel | URL de base du plan de contrôle pour le proxy du marketplace et l'installation locale de paquets. Définissez-le à `off` ou `local` pour désactiver les fonctionnalités du marketplace. N'est plus utilisé pour le routage par nom d'hôte du host-stack dans la distribution autonome. | -| `OS_MULTI_ORG_ENABLED` | Non | Définissez-le à `true` pour activer le routage multi-locataire / le changement d'organisation (par défaut `false`). Alias hérité : `OS_MULTI_TENANT`. | -| `OS_RUNTIME_PORT` | Dev uniquement | Port localhost utilisé pour construire les URL de rappel SSO de la plateforme lors du développement sur `http://localhost:`. | - -> **Rechargement à chaud de l'artefact.** Le stack autonome recharge automatiquement -> l'artefact local hors production (piloté par `NODE_ENV`) ; le drapeau explicite -> `OS_WATCH_ARTIFACT=1` de 7.x n'est plus requis. - -## Cache - -| Variable | Par défaut | Description | -|---|---:|---| -| `OS_KERNEL_CACHE_SIZE` | `32` | Nombre maximal de kernels de projet en cache. | -| `OS_KERNEL_TTL_MS` | `900000` | TTL d'inactivité pour les kernels de projet. | -| `OS_ENV_CACHE_TTL_MS` | `300000` | TTL du cache d'environnement/de noms d'hôte. | -| `OS_ARTIFACT_CACHE_TTL_MS` | `300000` | TTL du cache des réponses d'artefacts. | - -## Authentification et origines de confiance - -| Variable | Description | -|---|---| -| `AUTH_SECRET` | Alias hérité pour `OS_AUTH_SECRET`. Toujours pris en charge dans cette version ; préférez `OS_AUTH_SECRET`. | -| `OS_TRUSTED_ORIGINS` | Origines de confiance supplémentaires, séparées par des virgules. | -| `OS_ROOT_DOMAIN` | Domaine racine utilisé pour faire confiance aux sous-domaines de projet dans les déploiements SSO de la plateforme. | -| `OS_PLATFORM_SSO` | Définissez-le à `false` pour désactiver le câblage SSO de la plateforme. | -| `OS_RUNTIME_PORT` | Aide au développement local pour les noms d'hôte de projet en localhost. | - -## Base de données - -En mode connecté au cloud, le plan de contrôle renvoie la configuration de la -base de données d'exécution par projet avec la réponse d'artefact. En -mode adossé à un fichier, ObjectOS lit les déclarations de source de données depuis -l'artefact. En dernier recours, le framework prend également en charge : - -| Variable | Description | -|---|---| -| `OS_DATABASE_URL` | URL de connexion (`file:./db.sqlite`, `libsql://…`, `postgres://…`, `mongodb://…`, `memory://`). Utilisée par le mode autonome et la CLI `dev`. | -| `OS_DATABASE_DRIVER` | Remplace le pilote auto-détecté à partir de l'URL. | -| `OS_DATABASE_AUTH_TOKEN` | Jeton d'authentification pour les pilotes managés tels que Turso/libSQL. | -| `OS_BUSINESS_DB_URL` | Convention du wrapper ObjectOS pour l'URL de la base de données métier par projet. Résolvez-la vers `OS_DATABASE_URL` ou un remplacement de source de données d'exécution dans votre déploiement. | -| `OS_CACHE_DIR` | Répertoire de cache local des artefacts et de l'exécution (par défaut `/var/cache/objectos`). | -| `OS_SKIP_SCHEMA_SYNC` | Définissez-le à `1` pour ignorer la synchronisation DDL ObjectQL au démarrage. À utiliser lorsque le schéma est géré hors bande. | - -Pour les déploiements clients ObjectOS, préférez une configuration d'exécution -explicite du plan de contrôle ou une configuration de source de données d'artefact -plutôt que de vous appuyer sur les valeurs par défaut locales au conteneur. - -## Observabilité - -L'export des traces et des métriques est opt-in. L'exporteur a pour valeur par -défaut `noop`, de sorte qu'un déploiement n'émet rien tant que vous n'en -sélectionnez pas un — définir un endpoint seul ne fait rien. - -| Variable | Par défaut | Description | -|---|---:|---| -| `OS_OBS_EXPORTER` | `noop` | Exporteur de télémétrie : `noop` \| `console` \| `json` \| `otlp`. Utilisez `console`/`json` pour le débogage local, `otlp` pour un collecteur. | -| `OS_OTLP_ENDPOINT` | — | URL racine OTLP/HTTP (par ex. `https://otlp.grafana.net/otlp`). Requise lorsque `OS_OBS_EXPORTER=otlp` ; si vide, le runtime avertit et retombe sur `noop`. | -| `OS_OTLP_HEADERS` | — | En-têtes OTLP supplémentaires (par ex. authentification) sous forme de paires `key=value` séparées par des virgules. | -| `OS_OBS_SERVICE_NAME` | — | Attribut de ressource `service.name` sur les spans/métriques émis. | -| `OS_OBS_DEPLOYMENT_ENV` | `production` | Attribut de ressource `deployment.environment`. | -| `OS_OTLP_FLUSH_MS` | — | Intervalle de vidage de l'exporteur OTLP, en millisecondes. | - -## Remplacements d'espace de noms des paramètres - -Les paramètres système (les espaces de noms `ai`, `email`, `feature_flags`, … -modifiables par le locataire ou l'utilisateur) peuvent être épinglés au niveau du -déploiement avec une variable d'environnement nommée `OS__` — en -majuscules, avec `.` et `-` remplacés par `_`. Par exemple `ai.openai_base_url` -→ `OS_AI_OPENAI_BASE_URL`, et `feature_flags.ai_enabled` -→ `OS_FEATURE_FLAGS_AI_ENABLED`. À partir de la 9.0, les alias sans préfixe ont -été supprimés — la forme préfixée par `OS_` est la seule lue. - -La connexion Google (configurable dans **Setup → Authentication**) lit également -`GOOGLE_CLIENT_ID` et `GOOGLE_CLIENT_SECRET` au niveau du déploiement. - -## Alias hérités - -Ces noms antérieurs à la version 1.0 fonctionnent toujours dans cette version mais émettent un avertissement -de dépréciation unique. Ils seront supprimés dans une future version majeure. Préférez le nom canonique. - -| Canonique | Hérité | -|---|---| -| `OS_PORT` | `PORT` | -| `OS_AUTH_SECRET` | `AUTH_SECRET` | -| `OS_MULTI_ORG_ENABLED` | `OS_MULTI_TENANT` | -| `OS_ENVIRONMENT_ID` | `OS_PROJECT_ID` | diff --git a/content/docs/reference/environment-variables.ja.mdx b/content/docs/reference/environment-variables.ja.mdx deleted file mode 100644 index 977e1af..0000000 --- a/content/docs/reference/environment-variables.ja.mdx +++ /dev/null @@ -1,116 +0,0 @@ ---- -title: 環境変数 -description: ObjectOS ランタイムの環境変数リファレンス。 ---- - -デプロイメントレベルの設定とシークレットには環境変数を使用します。 -テナント／ユーザーが編集可能なアプリケーション設定にはシステム設定を使用します。 - -> **命名規則。** ObjectStack が所有するすべての変数は `OS_` プレフィックスを使用します。 -> 1.0 以前のプレフィックスなしの名前（`PORT`、`AUTH_SECRET`、`OS_MULTI_TENANT`、…）も引き続き -> 動作しますが、一度限りの非推奨警告を出力します。新しいデプロイメントでは正規の -> `OS_*` 名を優先してください。[レガシーエイリアス](#legacy-aliases)を参照してください。 - -## コア - -| 変数 | 必須 | 説明 | -|---|---:|---| -| `OS_PORT` | いいえ | ランタイムがリッスンする HTTP ポート。デフォルトは `3000`。レガシーエイリアス: `PORT`。 | -| `OS_AUTH_SECRET` | 認証には必須 | プロジェクトごとの認証シークレットを導出するために使用する基本シークレット。レガシーエイリアス: `AUTH_SECRET`。 | - -## アーティファクトとプロジェクトの解決 - -| 変数 | 必須 | 説明 | -|---|---:|---| -| `OS_ARTIFACT_FILE` | ファイルモード | コンパイル済み `objectstack.json` へのパスまたは `http(s)://` URL。ObjectOS の設定によって読み取られ、`artifactPath` として `createStandaloneStack` に渡されます。クラウド接続デプロイでは公開済みのクラウド artifact URL を指定します。 | -| `OS_ARTIFACT_PATH` | 代替 | 同じパスまたは URL に対するフレームワークレベルの名前。`@objectstack/runtime` によって直接処理されます（CLI `dev`/`start`）。デフォルトは `/dist/objectstack.json`。 | -| `OS_PROJECT_ID` | 任意 | `OS_ENVIRONMENT_ID` のレガシーエイリアスで、後方互換性のために ObjectOS の設定が受け付けます。新しいデプロイメントでは `OS_ENVIRONMENT_ID` を優先してください。 | -| `OS_ENVIRONMENT_ID` | 任意 | standalone stack の環境 id（デフォルト `proj_local`）。プロジェクトごとの認証シークレットの導出にも使用されます。ObjectOS の設定はレガシーエイリアス `OS_PROJECT_ID` も受け付けます。 | -| `OS_ORGANIZATION_ID` | 任意 | ファイルバックモードのデフォルト組織 id（デフォルト `org_local`）。 | -| `OS_MCP_SERVER_ENABLED` | いいえ | Streamable HTTP の `/api/v1/mcp` で提供される Model Context Protocol サーバー——この HTTP サーフェスのみ——を制御します。**デフォルトはオン**（16.0+）：未設定ならエンドポイントは提供され、明示的な偽値（`false`/`0`/`off`/`no`）で無効化します。認証済みプリンシパルが必要です。レガシー：`OS_MCP_SERVER_ENABLED=true` はあと 1 リリースの間、非推奨警告付きで stdio トランスポートも自動起動します——代わりに `OS_MCP_STDIO_ENABLED` を使用してください。 | -| `OS_MCP_STDIO_ENABLED` | いいえ | 真値（`true`/`1`/`on`/`yes`）に設定すると、長寿命の **stdio** MCP トランスポートを自動起動します。デフォルトはオフで、`OS_MCP_SERVER_ENABLED`（HTTP サーフェスのみを制御）とは別のスイッチです。`OS_MCP_STDIO_API_KEY` が必要です。 | -| `OS_MCP_STDIO_API_KEY` | stdio 有効時 | stdio トランスポートをプリンシパルに束縛する API キー（`osk_...`）。HTTP MCP と同じ検証・認可チェーンで解決されるため、RLS/FLS とテナントスコープが適用されます。フェイルクローズド：stdio 自動起動が有効で解決可能なキーがない場合、サーバーは stdio トランスポートの起動を拒否します。 | -| `OS_CLOUD_URL` | 任意 | marketplace プロキシとローカルパッケージインストールのためのコントロールプレーンのベース URL。`off` または `local` に設定すると marketplace 機能を無効化できます。standalone ディストリビューションでは host stack のホスト名ルーティングには使用されなくなりました。 | -| `OS_MULTI_ORG_ENABLED` | いいえ | マルチテナントルーティング／組織切り替えを有効にするには `true` に設定します（デフォルト `false`）。レガシーエイリアス: `OS_MULTI_TENANT`。 | -| `OS_RUNTIME_PORT` | 開発のみ | `http://localhost:` で開発する際にプラットフォーム SSO のコールバック URL を構築するために使用するローカルホストポート。 | - -> **Artifact のホットリロード。** standalone stack は本番以外（`NODE_ENV` で制御）で -> ローカル artifact を自動的に再読み込みします。7.x の明示的な -> `OS_WATCH_ARTIFACT=1` フラグは不要になりました。 - -## キャッシュ - -| 変数 | デフォルト | 説明 | -|---|---:|---| -| `OS_KERNEL_CACHE_SIZE` | `32` | キャッシュするプロジェクトカーネルの最大数。 | -| `OS_KERNEL_TTL_MS` | `900000` | プロジェクトカーネルのアイドル TTL。 | -| `OS_ENV_CACHE_TTL_MS` | `300000` | 環境／ホスト名のキャッシュ TTL。 | -| `OS_ARTIFACT_CACHE_TTL_MS` | `300000` | アーティファクトレスポンスのキャッシュ TTL。 | - -## 認証と信頼できるオリジン - -| 変数 | 説明 | -|---|---| -| `AUTH_SECRET` | `OS_AUTH_SECRET` のレガシーエイリアス。このリリースでは引き続き処理されますが、`OS_AUTH_SECRET` を優先してください。 | -| `OS_TRUSTED_ORIGINS` | カンマ区切りの追加の信頼できるオリジン。 | -| `OS_ROOT_DOMAIN` | プラットフォーム SSO デプロイメントでプロジェクトのサブドメインを信頼するために使用するルートドメイン。 | -| `OS_PLATFORM_SSO` | プラットフォーム SSO の接続を無効にするには `false` に設定します。 | -| `OS_RUNTIME_PORT` | localhost プロジェクトのホスト名向けのローカル開発ヘルパー。 | - -## データベース - -クラウド接続モードでは、コントロールプレーンがアーティファクトレスポンスとともに -プロジェクトごとのランタイムデータベース設定を返します。ファイルバックモードでは、 -ObjectOS はアーティファクトからデータソース宣言を読み取ります。最終手段として、 -フレームワークは次のものも処理します。 - -| 変数 | 説明 | -|---|---| -| `OS_DATABASE_URL` | 接続 URL（`file:./db.sqlite`、`libsql://…`、`postgres://…`、`mongodb://…`、`memory://`）。スタンドアロンモードと CLI `dev` で使用されます。 | -| `OS_DATABASE_DRIVER` | URL から自動検出されるドライバーを上書きします。 | -| `OS_DATABASE_AUTH_TOKEN` | Turso/libSQL などのマネージドドライバー用の認証トークン。 | -| `OS_BUSINESS_DB_URL` | プロジェクトごとのビジネスデータベース URL に対する ObjectOS ラッパーの規約。デプロイメントでは `OS_DATABASE_URL` またはランタイムデータソースの上書きに解決してください。 | -| `OS_CACHE_DIR` | ローカルアーティファクトおよびランタイムキャッシュのディレクトリ（デフォルト `/var/cache/objectos`）。 | -| `OS_SKIP_SCHEMA_SYNC` | 起動時の ObjectQL DDL 同期をスキップするには `1` に設定します。スキーマを別途管理する場合に使用します。 | - -ObjectOS の顧客デプロイメントでは、コンテナローカルのデフォルトに依存するよりも、 -明示的なコントロールプレーンのランタイム設定またはアーティファクトのデータソース設定を -優先してください。 - -## オブザーバビリティ - -トレースとメトリクスのエクスポートはオプトインです。エクスポーターのデフォルトは `noop` のため、 -いずれかを選択するまでデプロイメントは何も出力しません——エンドポイントを設定するだけでは -何も起こりません。 - -| 変数 | デフォルト | 説明 | -|---|---:|---| -| `OS_OBS_EXPORTER` | `noop` | テレメトリエクスポーター: `noop` \| `console` \| `json` \| `otlp`。ローカルデバッグには `console`/`json`、コレクターには `otlp` を使用します。 | -| `OS_OTLP_ENDPOINT` | — | OTLP/HTTP のルート URL（例: `https://otlp.grafana.net/otlp`）。`OS_OBS_EXPORTER=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 エクスポーターのフラッシュ間隔（ミリ秒）。 | - -## 設定ネームスペースの上書き - -システム設定（テナント/ユーザーが編集可能な `ai`、`email`、`feature_flags`、… の各ネームスペース）は、 -`OS__` という名前の環境変数でデプロイメントレベルに固定できます——大文字化し、 -`.` と `-` を `_` に置き換えます。たとえば `ai.openai_base_url` → `OS_AI_OPENAI_BASE_URL`、 -`feature_flags.ai_enabled` → `OS_FEATURE_FLAGS_AI_ENABLED` です。9.0 以降、プレフィックスなしの -エイリアスは削除され、`OS_` プレフィックス付きの形式のみが読み取られます。 - -Google サインイン（**Setup → Authentication** で設定可能）も、デプロイメントレベルで -`GOOGLE_CLIENT_ID` と `GOOGLE_CLIENT_SECRET` を読み取ります。 - -## レガシーエイリアス - -これらの 1.0 以前の名前はこのリリースでは引き続き動作しますが、一度限りの非推奨 -警告を出力します。これらは将来のメジャーバージョンで削除されます。正規の名前を優先してください。 - -| 正規 | レガシー | -|---|---| -| `OS_PORT` | `PORT` | -| `OS_AUTH_SECRET` | `AUTH_SECRET` | -| `OS_MULTI_ORG_ENABLED` | `OS_MULTI_TENANT` | -| `OS_ENVIRONMENT_ID` | `OS_PROJECT_ID` | diff --git a/content/docs/reference/environment-variables.ko.mdx b/content/docs/reference/environment-variables.ko.mdx deleted file mode 100644 index 779b39c..0000000 --- a/content/docs/reference/environment-variables.ko.mdx +++ /dev/null @@ -1,116 +0,0 @@ ---- -title: 환경 변수 -description: ObjectOS 런타임 환경 변수 참조. ---- - -배포 수준 구성 및 시크릿에는 환경 변수를 사용하세요. -테넌트/사용자가 편집 가능한 애플리케이션 구성에는 시스템 설정을 사용하세요. - -> **명명 규칙.** 모든 ObjectStack 소유 변수는 `OS_` 접두사를 사용합니다. 1.0 이전의 -> 접두사 없는 이름(`PORT`, `AUTH_SECRET`, `OS_MULTI_TENANT`, …)도 여전히 동작하지만 -> 일회성 사용 중단 경고를 출력합니다. 새 배포에서는 표준 `OS_*` 이름을 사용하는 것이 -> 좋습니다. [레거시 별칭](#legacy-aliases)을 참조하세요. - -## 핵심 - -| 변수 | 필수 | 설명 | -|---|---:|---| -| `OS_PORT` | 아니오 | 런타임이 수신 대기하는 HTTP 포트. 기본값은 `3000`. 레거시 별칭: `PORT`. | -| `OS_AUTH_SECRET` | 인증 시 필수 | 프로젝트별 인증 시크릿을 파생하는 데 사용되는 기본 시크릿. 레거시 별칭: `AUTH_SECRET`. | - -## 아티팩트 및 프로젝트 확인 - -| 변수 | 필수 | 설명 | -|---|---:|---| -| `OS_ARTIFACT_FILE` | 파일 모드 | 컴파일된 `objectstack.json`의 경로 또는 `http(s)://` URL. ObjectOS 구성이 읽어 `artifactPath`로 `createStandaloneStack`에 전달합니다. 클라우드 연결 배포에서는 게시된 클라우드 artifact URL을 가리키게 하세요. | -| `OS_ARTIFACT_PATH` | 대안 | 동일한 경로 또는 URL에 대한 프레임워크 수준의 이름으로, `@objectstack/runtime`이 직접 처리합니다(CLI `dev`/`start`). 기본값 `/dist/objectstack.json`. | -| `OS_PROJECT_ID` | 선택 | `OS_ENVIRONMENT_ID`의 레거시 별칭으로, 하위 호환성을 위해 ObjectOS 구성에서 허용됩니다. 새 배포에서는 `OS_ENVIRONMENT_ID`를 사용하는 것이 좋습니다. | -| `OS_ENVIRONMENT_ID` | 선택 | standalone stack의 환경 id(기본값 `proj_local`). 프로젝트별 인증 시크릿을 파생하는 데에도 사용됩니다. ObjectOS 구성은 레거시 별칭 `OS_PROJECT_ID`도 허용합니다. | -| `OS_ORGANIZATION_ID` | 선택 | 파일 기반 모드의 기본 조직 id(기본값 `org_local`). | -| `OS_MCP_SERVER_ENABLED` | 아니오 | Streamable HTTP의 `/api/v1/mcp`로 제공되는 Model Context Protocol 서버 — 오직 이 HTTP 표면만 — 를 제어합니다. **기본값은 켜짐**(16.0+): 설정하지 않으면 엔드포인트가 제공되며, 명시적인 거짓 값(`false`/`0`/`off`/`no`)으로 비활성화합니다. 인증된 주체가 필요합니다. 레거시: `OS_MCP_SERVER_ENABLED=true`는 한 릴리스 동안 사용 중단 경고와 함께 stdio 전송도 자동 시작합니다 — 대신 `OS_MCP_STDIO_ENABLED`를 사용하세요. | -| `OS_MCP_STDIO_ENABLED` | 아니오 | 참 값(`true`/`1`/`on`/`yes`)으로 설정하면 장수명 **stdio** MCP 전송을 자동 시작합니다. 기본값은 꺼짐이며 `OS_MCP_SERVER_ENABLED`(HTTP 표면만 제어)와는 별개의 스위치입니다. `OS_MCP_STDIO_API_KEY`가 필요합니다. | -| `OS_MCP_STDIO_API_KEY` | stdio 활성화 시 | stdio 전송이 주체에 바인딩되는 API 키(`osk_...`). HTTP MCP와 동일한 검증·인가 체인으로 해석되므로 RLS/FLS와 테넌트 범위가 적용됩니다. 실패 시 닫힘(fail-closed): stdio 자동 시작이 활성화되었는데 해석 가능한 키가 없으면 서버는 stdio 전송 시작을 거부합니다. | -| `OS_CLOUD_URL` | 선택 | marketplace 프록시 및 로컬 패키지 설치를 위한 컨트롤 플레인 기본 URL. `off` 또는 `local`로 설정하면 marketplace 기능을 비활성화합니다. standalone 배포판에서는 더 이상 host stack의 호스트명 라우팅에 사용되지 않습니다. | -| `OS_MULTI_ORG_ENABLED` | 아니오 | 멀티 테넌트 라우팅/조직 전환을 활성화하려면 `true`로 설정합니다(기본값 `false`). 레거시 별칭: `OS_MULTI_TENANT`. | -| `OS_RUNTIME_PORT` | 개발 전용 | `http://localhost:`에서 개발할 때 플랫폼 SSO 콜백 URL을 구성하는 데 사용되는 localhost 포트. | - -> **Artifact 핫 리로드.** standalone stack은 프로덕션이 아닌 환경에서(`NODE_ENV`로 제어) -> 로컬 artifact를 자동으로 다시 로드합니다. 7.x의 명시적 `OS_WATCH_ARTIFACT=1` -> 플래그는 더 이상 필요하지 않습니다. - -## 캐시 - -| 변수 | 기본값 | 설명 | -|---|---:|---| -| `OS_KERNEL_CACHE_SIZE` | `32` | 캐시된 프로젝트 커널의 최대 개수. | -| `OS_KERNEL_TTL_MS` | `900000` | 프로젝트 커널의 유휴 TTL. | -| `OS_ENV_CACHE_TTL_MS` | `300000` | 환경/호스트명 캐시 TTL. | -| `OS_ARTIFACT_CACHE_TTL_MS` | `300000` | 아티팩트 응답 캐시 TTL. | - -## 인증 및 신뢰할 수 있는 출처 - -| 변수 | 설명 | -|---|---| -| `AUTH_SECRET` | `OS_AUTH_SECRET`의 레거시 별칭. 이번 릴리스에서도 여전히 처리되지만 `OS_AUTH_SECRET`을 사용하는 것이 좋습니다. | -| `OS_TRUSTED_ORIGINS` | 쉼표로 구분된 추가 신뢰 출처. | -| `OS_ROOT_DOMAIN` | 플랫폼 SSO 배포에서 프로젝트 하위 도메인을 신뢰하는 데 사용되는 루트 도메인. | -| `OS_PLATFORM_SSO` | 플랫폼 SSO 연결을 비활성화하려면 `false`로 설정합니다. | -| `OS_RUNTIME_PORT` | localhost 프로젝트 호스트명을 위한 로컬 개발 도우미. | - -## 데이터베이스 - -클라우드 연결 모드에서는 컨트롤 플레인이 아티팩트 응답과 함께 -프로젝트별 런타임 데이터베이스 구성을 반환합니다. 파일 기반 -모드에서 ObjectOS는 아티팩트에서 데이터소스 선언을 읽습니다. -최후의 수단으로 프레임워크는 다음도 처리합니다: - -| 변수 | 설명 | -|---|---| -| `OS_DATABASE_URL` | 연결 URL(`file:./db.sqlite`, `libsql://…`, `postgres://…`, `mongodb://…`, `memory://`). 독립 실행형 모드 및 CLI `dev`에서 사용됩니다. | -| `OS_DATABASE_DRIVER` | URL에서 자동 감지된 드라이버를 재정의합니다. | -| `OS_DATABASE_AUTH_TOKEN` | Turso/libSQL과 같은 관리형 드라이버를 위한 인증 토큰. | -| `OS_BUSINESS_DB_URL` | 프로젝트별 비즈니스 데이터베이스 URL에 대한 ObjectOS 래퍼 규칙. 배포에서 이를 `OS_DATABASE_URL` 또는 런타임 데이터소스 재정의로 확인하세요. | -| `OS_CACHE_DIR` | 로컬 아티팩트 및 런타임 캐시 디렉터리(기본값 `/var/cache/objectos`). | -| `OS_SKIP_SCHEMA_SYNC` | 부팅 시 ObjectQL DDL 동기화를 건너뛰려면 `1`로 설정합니다. 스키마를 별도로 관리할 때 사용하세요. | - -ObjectOS 고객 배포의 경우 컨테이너 로컬 기본값에 의존하기보다는 -명시적인 컨트롤 플레인 런타임 구성 또는 아티팩트 데이터소스 구성을 -사용하는 것이 좋습니다. - -## Observability - -추적 및 메트릭 내보내기는 옵트인입니다. 익스포터의 기본값은 `noop`이므로 배포는 -하나를 선택하기 전까지 아무것도 내보내지 않습니다 — 엔드포인트만 설정해서는 -아무 일도 일어나지 않습니다. - -| 변수 | 기본값 | 설명 | -|---|---:|---| -| `OS_OBS_EXPORTER` | `noop` | 텔레메트리 익스포터: `noop` \| `console` \| `json` \| `otlp`. 로컬 디버깅에는 `console`/`json`을, 컬렉터에는 `otlp`를 사용하세요. | -| `OS_OTLP_ENDPOINT` | — | OTLP/HTTP 루트 URL(예: `https://otlp.grafana.net/otlp`). `OS_OBS_EXPORTER=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 익스포터의 플러시 간격(밀리초). | - -## Settings 네임스페이스 재정의 - -시스템 설정(테넌트/사용자 편집 가능한 `ai`, `email`, `feature_flags`, … 네임스페이스)은 -`OS__` 형식의 환경 변수로 배포 수준에서 고정할 수 있습니다 — 대문자로 -바꾸고 `.`과 `-`를 `_`로 치환합니다. 예를 들어 `ai.openai_base_url` → -`OS_AI_OPENAI_BASE_URL`, `feature_flags.ai_enabled` → `OS_FEATURE_FLAGS_AI_ENABLED`. -9.0부터 접두사 없는 별칭은 제거되었습니다 — `OS_` 접두사 형식만 읽습니다. - -Google 로그인(**Setup → Authentication**에서 구성)도 배포 수준에서 `GOOGLE_CLIENT_ID`와 -`GOOGLE_CLIENT_SECRET`을 읽습니다. - -## 레거시 별칭 - -이 1.0 이전 이름들은 이번 릴리스에서도 여전히 동작하지만 일회성 사용 중단 -경고를 출력합니다. 향후 메이저 버전에서 제거될 예정입니다. 표준 이름을 사용하는 것이 좋습니다. - -| 표준 | 레거시 | -|---|---| -| `OS_PORT` | `PORT` | -| `OS_AUTH_SECRET` | `AUTH_SECRET` | -| `OS_MULTI_ORG_ENABLED` | `OS_MULTI_TENANT` | -| `OS_ENVIRONMENT_ID` | `OS_PROJECT_ID` | diff --git a/content/docs/reference/environment-variables.mdx b/content/docs/reference/environment-variables.mdx index f0a3b57..e5eb336 100644 --- a/content/docs/reference/environment-variables.mdx +++ b/content/docs/reference/environment-variables.mdx @@ -1,124 +1,180 @@ --- title: Environment Variables -description: ObjectOS runtime environment variable reference. +description: The environment contract of a self-hosted ObjectOS deployment — what each variable decides, which combinations are refused at startup, and the names that no longer do anything. --- -Use environment variables for deployment-level configuration and secrets. -Use system settings for tenant/user-editable application configuration. +Environment variables carry **deployment-level** decisions: which image is +running, where the data lives, and what this deployment is entitled to be. +Anything a tenant or an administrator should be able to change while the +deployment is running belongs in system settings instead. -> **Naming.** All ObjectStack-owned variables use the `OS_` prefix. Pre-1.0 -> unprefixed names (`PORT`, `AUTH_SECRET`, `OS_MULTI_TENANT`, …) still work but -> emit a one-shot deprecation warning. Prefer the canonical `OS_*` names in new -> deployments; see [Legacy aliases](#legacy-aliases). +This page is the **contract** — what each variable decides, and what happens +when two of them disagree. The **values you copy** live in the deploy bundle +that ships with your release: an annotated template you copy to `.env` and +edit. That template is pinned to your release; this page is not. Where the two +differ, the template shipped with your image wins. -## Core +> **Naming.** ObjectOS-owned variables use the `OS_` prefix. A few pre-1.0 +> unprefixed names still work and emit a one-shot deprecation warning — see +> [Legacy names](#legacy-names). Two other groups are worth knowing before you +> reach for a name you remember: [retired names](#retired-names), which are +> read by nothing or refuse the boot outright, and legacy names that still +> resolve. -| Variable | Required | Description | -|---|---:|---| -| `OS_PORT` | No | HTTP port the runtime listens on. Defaults to `3000`. Legacy alias: `PORT`. | -| `OS_AUTH_SECRET` | Yes for auth | Base secret used to derive per-project auth secrets. Legacy alias: `AUTH_SECRET`. | +## The decisions every deployment makes -## Artifact and project resolution +| Variable | Decides | +|---|---| +| `OS_EE_IMAGE` | Which image runs. Read by the bundled Compose stack, not by the runtime. Pin the **digest**, never a tag — see [Docker](/docs/deploy/docker). | +| `OS_AUTH_SECRET` | The base secret sessions are signed from. Must be **identical on every replica**. Rotating it invalidates every existing session. | +| `OS_DATABASE_URL` | The database the deployment runs on. In production, point this at your managed PostgreSQL and remove the bundled database service. | +| `OS_DB_USER`, `OS_DB_PASSWORD`, `OS_DB_NAME` | Provision the **bundled** database service in the shipped Compose stack. The credentials inside `OS_DATABASE_URL` must match them. Irrelevant once you use a managed database. | +| `AI_GATEWAY_API_KEY` | The AI provider credential behind the "ask your data" agent. | -| Variable | Required | Description | -|---|---:|---| -| `OS_ARTIFACT_FILE` | File mode | Path or `http(s)://` URL to a compiled `objectstack.json`. Read by the ObjectOS config and passed as `artifactPath` to `createStandaloneStack`. Point this at a published cloud artifact URL for cloud-connected deployments. | -| `OS_ARTIFACT_PATH` | Alternative | Framework-level name for the same path or URL, honoured by `@objectstack/runtime` directly (CLI `dev`/`start`). Defaults to `/dist/objectstack.json`. | -| `OS_PROJECT_ID` | Optional | Legacy alias for `OS_ENVIRONMENT_ID`, accepted by the ObjectOS config for backward compatibility. Prefer `OS_ENVIRONMENT_ID` in new deployments. | -| `OS_ENVIRONMENT_ID` | Optional | Environment id for the standalone stack (default `proj_local`). Also used to derive the per-project auth secret. The ObjectOS config also accepts the legacy alias `OS_PROJECT_ID`. | -| `OS_ORGANIZATION_ID` | Optional | Default organization id for file-backed mode (default `org_local`). | -| `OS_MCP_SERVER_ENABLED` | No | Governs the Model Context Protocol server over Streamable HTTP at `/api/v1/mcp` — and only that HTTP surface. **On by default** (16.0+): unset means the endpoint is served; set an explicit falsy value (`false`/`0`/`off`/`no`) to disable it. Requires an authenticated principal. Legacy: `OS_MCP_SERVER_ENABLED=true` also auto-starts the stdio transport for one more release with a deprecation warning — use `OS_MCP_STDIO_ENABLED` instead. | -| `OS_MCP_STDIO_ENABLED` | No | Set to a truthy value (`true`/`1`/`on`/`yes`) to auto-start the long-lived **stdio** MCP transport. Off by default and separate from `OS_MCP_SERVER_ENABLED` (which governs only the HTTP surface). Requires `OS_MCP_STDIO_API_KEY`. | -| `OS_MCP_STDIO_API_KEY` | When stdio is enabled | API key (`osk_...`) the stdio transport is principal-bound to. Resolved through the same verify + authorization chain as HTTP MCP, so RLS/FLS and tenant scoping apply. Fails closed: with stdio auto-start enabled and no resolvable key, the server refuses to start the stdio transport. | -| `OS_CLOUD_URL` | Optional | Control-plane base URL for the marketplace proxy and local package install. Set to `off` or `local` to disable marketplace features. No longer used for host-stack hostname routing in the standalone distribution. | -| `OS_MULTI_ORG_ENABLED` | No | Set to `true` to enable multi-tenant routing / organization switching (default `false`). Legacy alias: `OS_MULTI_TENANT`. | -| `OS_RUNTIME_PORT` | Dev only | Localhost port used to build platform-SSO callback URLs when developing on `http://localhost:`. | - -> **Artifact hot-reload.** The standalone stack reloads the local artifact -> automatically outside production (gated by `NODE_ENV`); the explicit -> `OS_WATCH_ARTIFACT=1` flag from 7.x is no longer required. - -## Cache - -| Variable | Default | Description | -|---|---:|---| -| `OS_KERNEL_CACHE_SIZE` | `32` | Maximum cached project kernels. | -| `OS_KERNEL_TTL_MS` | `900000` | Idle TTL for project kernels. | -| `OS_ENV_CACHE_TTL_MS` | `300000` | Environment/hostname cache TTL. | -| `OS_ARTIFACT_CACHE_TTL_MS` | `300000` | Artifact response cache TTL. | +## Licence and cloud posture -## Auth and trusted origins +These two are a pair. Setting one without reading the other is the most +expensive mistake on this page, because unsupported pairings are **refused at +startup** rather than degraded. -| Variable | Description | +| Variable | Decides | |---|---| -| `AUTH_SECRET` | Legacy alias for `OS_AUTH_SECRET`. Still honoured this release; prefer `OS_AUTH_SECRET`. | -| `OS_TRUSTED_ORIGINS` | Comma-separated additional trusted origins. | -| `OS_ROOT_DOMAIN` | Root domain used to trust project subdomains in platform SSO deployments. | -| `OS_PLATFORM_SSO` | Set to `false` to disable platform SSO wiring. | -| `OS_RUNTIME_PORT` | Local development helper for localhost project hostnames. | +| `OS_LICENSE_KEY` | The deployment's entitlement. A licence also has a **mode** — ordinary licences are validated online against a control plane; air-gap licences are verified locally with no network traffic at all. The mode is a property of the licence you were issued, not something you configure here. | +| `OS_CLOUD_URL` | Whether this deployment has a control plane, and which one. `off` (and its aliases `none`, `local`, `disabled`) means **no control plane**: no marketplace, and no licence validation either. | + +Two consequences follow, and both surprise people: -## Database +- **Unset is not "off".** An unset `OS_CLOUD_URL` resolves to the *public* + control plane. It was never a neutral value — it selects the connected + behaviour. A deployment meant to talk to nobody must say `off` out loud. +- **An ordinary licence with `off` is refused at startup**, naming both + variables. It is not a degraded state but an impossible one: an online + licence is validated by an exchange that needs a control plane, so with none + configured the exchange is never made — not on this boot and not on a later + one — and the grace window never starts, because grace runs from the last + *successful* validation. -In cloud-connected mode the control plane returns the per-project -runtime database configuration with the artifact response. In -file-backed mode ObjectOS reads datasource declarations from the -artifact. As a last resort the framework also honours: +[Air-gapped Deployment](/docs/deploy/air-gapped) carries the full matrix of +supported combinations and the reasoning behind the refusal. -| Variable | Description | +## Multi-organization deployments + +A **walled** tenancy posture puts up the per-organization isolation wall. It is +a licensed capability, and it makes two further decisions mandatory: the +runtime refuses to start until each is declared. Declaring either available +value is accepted; not deciding is not. + +| Variable | Decides | |---|---| -| `OS_DATABASE_URL` | Connection URL (`file:./db.sqlite`, `libsql://…`, `postgres://…`, `mongodb://…`, `memory://`). Used by standalone mode and CLI `dev`. | -| `OS_DATABASE_DRIVER` | Override the driver auto-detected from the URL. | -| `OS_DATABASE_AUTH_TOKEN` | Auth token for managed drivers such as Turso/libSQL. | -| `OS_BUSINESS_DB_URL` | ObjectOS wrapper convention for the per-project business database URL. Resolve it to `OS_DATABASE_URL` or a runtime datasource override in your deployment. | -| `OS_CACHE_DIR` | Local artifact and runtime cache directory (default `/var/cache/objectos`). | -| `OS_SKIP_SCHEMA_SYNC` | Set to `1` to skip ObjectQL DDL sync at boot. Use when schema is managed out-of-band. | -| `OS_TELEMETRY_DB` | Dedicated datasource for lifecycle-classed system data (14.5+). `objectstack dev` auto-provisions `.telemetry.db`; set to `0` to opt out, or to a path/URL to opt in anywhere. | +| `OS_TENANCY_POSTURE` | Whether organizations are isolated from one another. The walled values are `isolated` and `group`. A walled posture **requires a licence**: without one the runtime exits at startup rather than serve traffic while pretending to be isolated. | +| `OS_AUTH_MEMBERSHIP_POLICY` | What a fresh sign-up joins. `auto` binds every new user to the deployment's default organization — right for a single-organization box, wrong where a membership *is* the tenant boundary. `invite-only` grants membership only by an explicit act: creating a workspace, accepting an invitation, an admin, or SSO provisioning. Also settable in **Setup → Authentication → Membership**; setting it here pins it and makes the Setup field read-only. | +| `OS_AI_STUDIO_AGENTS` | Which AI agents are mounted, as a comma-separated subset of `ask` and `build`. Unset mounts **both**. `ask` reads; `build` **authors metadata** — and metadata is scoped to the deployment, not to an organization, so on a shared database one customer's `build` turn rewrites the schema every other customer runs on. The AI seat does not cover this: it is one flag for both agents. A misspelled value fails the boot rather than quietly falling back to mounting both. | -## Data lifecycle +A single-organization deployment sees neither of the last two checks and may +leave both unset. -| Variable | Default | Description | -|---|---:|---| -| `OS_LIFECYCLE_DISABLED` | unset (service on) | Set to `1` to disable the LifecycleService (retention reaper, table rotation, audit archiver — 14.4+). Retention windows themselves are tuned via the `lifecycle.retention_overrides` setting, not env vars. | +## Multi-node -For ObjectOS customer deployments, prefer explicit control-plane runtime -configuration or artifact datasource configuration over relying on -container-local defaults. +Scaling past one replica changes what is mandatory. + +| Variable | Decides | +|---|---| +| `OS_CLUSTER_DRIVER` | Turns on the shared coordinator. Unset means one replica on the built-in in-memory coordinator. | +| `OS_REDIS_URL` | Where that coordinator lives. | +| `OS_SECRET_KEY` | **Becomes required** once a cluster driver is set, and must be the *same* value on every replica. With no cluster driver each replica mints and persists its own key; across replicas those keys would silently diverge, so the runtime refuses to boot instead of serving with inconsistent crypto. | +| `OS_CLUSTER_REPLICAS` | How many application replicas the bundled stack starts. | + +## Running a published app + +The runtime image and the app it serves are independent release axes: one +variable names a published artifact, and upgrading the app is a change to that +variable plus a restart — no image rebuild. + +| Variable | Decides | +|---|---| +| `OS_ARTIFACT_URL` | **The one variable that selects the app.** An absolute `https://`, `http://` or `file://` URL naming a built `objectstack.json`, with an optional SRI-style integrity pin in the URL fragment (`#sha256=` followed by 64 hex characters). A pinned artifact whose bytes do not match **refuses the boot**, naming the expected and the actual digest. Resolved before any configuration is read, so the image's own enterprise wiring is not loaded on this path. | +| `OS_COMPOSED_ARTIFACT_URL` | Selects the app for the **composed** shape — a published app booted together with the image's enterprise plugins, several organizations sharing one database. That shape has its own template in the deploy bundle, is air-gap-licensed only, and requires `OS_CLOUD_URL=off`; both are enforced at startup. Setting both this and `OS_ARTIFACT_URL` refuses the boot. | + +There is deliberately no companion variable for the integrity hash. The pin +lives in the URL fragment, so there is one value to copy and one to rotate, and +"URL updated, hash not" is not a state you can spell. + +Publish to **immutable, version-named** objects, give the artifact host's write +credential to your publishing pipeline only, and pin the digest in production. +Those three rules are what make rollback — the same operation as upgrade, with +the older URL — actually work. + +## Runtime services + +| Variable | Decides | +|---|---| +| `OS_PORT` | The HTTP port the runtime listens on. Legacy alias: `PORT`. | +| `OS_ENVIRONMENT_ID` | The environment id a single-environment runtime reports as its own. A completed cloud binding persists this, after which a self-hosted runtime does not need it set. | +| `OS_TRUSTED_ORIGINS` | Additional trusted origins, comma-separated. | +| `OS_ROOT_DOMAIN` | Root domain used to trust subdomains in platform-SSO deployments. | +| `OS_DATABASE_DRIVER` | Overrides the driver otherwise inferred from the `OS_DATABASE_URL` scheme. Set it only when the scheme cannot be inferred; an unsupported value fails rather than falling back. | +| `OS_DATABASE_AUTH_TOKEN` | Auth token for managed drivers that use one. | +| `OS_SKIP_SCHEMA_SYNC` | Set to `1` to skip the boot-time schema sync. Use when schema is managed out of band — the shipped stack already runs migrations as a separate one-shot step before any replica starts. | +| `OS_TELEMETRY_DB` | A dedicated datasource for lifecycle-classed system data. Set to `0` to opt out, or to a path or URL to opt in. | +| `OS_LIFECYCLE_DISABLED` | Set to `1` to disable the lifecycle service (retention reaper, table rotation, audit archiver). Retention windows themselves are tuned through the `lifecycle.retention_overrides` setting, not through environment variables. | +| `OS_MCP_SERVER_ENABLED` | Governs the Model Context Protocol server over HTTP at `/api/v1/mcp`, and only that surface. **On by default**: set an explicit falsy value (`false`, `0`, `off`, `no`) to disable it. An authenticated principal is always required. | +| `OS_MCP_STDIO_ENABLED` | Set to a truthy value to auto-start the long-lived **stdio** MCP transport. Off by default, and independent of the HTTP surface above. | +| `OS_MCP_STDIO_API_KEY` | The API key that stdio transport is principal-bound to, resolved through the same authorization chain as HTTP MCP, so record- and field-level security still apply. Fails closed: with stdio enabled and no resolvable key, the transport does not start. | ## Observability -Tracing and metrics export is opt-in. The exporter defaults to `noop`, so a -deployment emits nothing until you select one — setting an endpoint alone does -nothing. +Export is opt-in. The exporter defaults to `noop`, so a deployment emits +nothing until you select one — **setting an endpoint alone does nothing.** -| Variable | Default | Description | +| Variable | Default | Decides | |---|---:|---| -| `OS_OBS_EXPORTER` | `noop` | Telemetry exporter: `noop` \| `console` \| `json` \| `otlp`. Use `console`/`json` for local debugging, `otlp` for a collector. | -| `OS_OTLP_ENDPOINT` | — | OTLP/HTTP root URL (e.g. `https://otlp.grafana.net/otlp`). Required when `OS_OBS_EXPORTER=otlp`; if empty the runtime warns and falls back to `noop`. | -| `OS_OTLP_HEADERS` | — | Extra OTLP headers (e.g. auth) as comma-separated `key=value` pairs. | -| `OS_OBS_SERVICE_NAME` | — | `service.name` resource attribute on emitted spans/metrics. | -| `OS_OBS_DEPLOYMENT_ENV` | `production` | `deployment.environment` resource attribute. | +| `OS_OBS_EXPORTER` | `noop` | `noop`, `console`, `json` or `otlp`. Use `console` or `json` for local debugging and `otlp` for a collector. | +| `OS_OTLP_ENDPOINT` | — | OTLP/HTTP root URL. Required when the exporter is `otlp`; if it is empty the runtime warns and falls back to `noop`. | +| `OS_OTLP_HEADERS` | — | Extra OTLP headers, as comma-separated `key=value` pairs. | +| `OS_OBS_SERVICE_NAME` | — | The `service.name` resource attribute on emitted spans and metrics. | +| `OS_OBS_DEPLOYMENT_ENV` | `production` | The `deployment.environment` resource attribute. | | `OS_OTLP_FLUSH_MS` | — | Flush interval for the OTLP exporter, in milliseconds. | -## Settings namespace overrides +## Pinning a system setting -System settings (the tenant/user-editable `ai`, `email`, `feature_flags`, … -namespaces) can be pinned at the deployment level with an environment variable -named `OS__` — uppercased, with `.` and `-` replaced by `_`. -For example `ai.openai_base_url` → `OS_AI_OPENAI_BASE_URL`, and -`feature_flags.ai_enabled` → `OS_FEATURE_FLAGS_AI_ENABLED`. As of 9.0 the -unprefixed aliases were removed — the `OS_`-prefixed form is the only one read. +System settings — the tenant- and administrator-editable `ai`, `email`, +`feature_flags` and similar namespaces — can be pinned at the deployment level +with a variable named `OS_` plus the namespace plus the key, uppercased, with +`.` and `-` replaced by `_`. For example `ai.openai_base_url` becomes +`OS_AI_OPENAI_BASE_URL`, and `feature_flags.ai_enabled` becomes +`OS_FEATURE_FLAGS_AI_ENABLED`. A pinned setting is read-only in Setup. -Google sign-in (configurable in **Setup → Authentication**) also reads +Google sign-in, configurable in **Setup → Authentication**, also reads `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` at the deployment level. -## Legacy aliases +## Retired names -These pre-1.0 names still work this release but emit a one-shot deprecation -warning. They will be removed in a future major. Prefer the canonical name. +These names appeared in earlier ObjectOS documentation. They are listed here so +that a configuration file you inherited can be read and corrected — **not** so +they can be used. -| Canonical | Legacy | +| Retired name | What to use instead | |---|---| -| `OS_PORT` | `PORT` | -| `OS_AUTH_SECRET` | `AUTH_SECRET` | -| `OS_MULTI_ORG_ENABLED` | `OS_MULTI_TENANT` | -| `OS_ENVIRONMENT_ID` | `OS_PROJECT_ID` | +| `OS_ARTIFACT_FILE` | `OS_ARTIFACT_URL`. Nothing in the shipped runtime reads `OS_ARTIFACT_FILE`; a deployment that sets it gets the boot it would have got with nothing set, and no error naming the mistake. A local file is `file://` on the replacement, and the replacement carries the integrity pin. | +| `OS_ARTIFACT_PATH` | `OS_ARTIFACT_URL`. **The runtime image refuses a boot that carries a non-default `OS_ARTIFACT_PATH`**, naming the replacement. Two spellings for "which artifact do I boot" is one dialect too many, and the retired one never carried an integrity pin. | +| `OS_BUSINESS_DB_URL` | `OS_DATABASE_URL`, or a datasource declared in the artifact. Nothing reads `OS_BUSINESS_DB_URL`; a deployment that sets it and nothing else has no database configured at all. | + +`OS_CLOUD_API_KEY` is **not** a variable a self-hosted deployment sets. It is +the service credential the hosted cloud injects into runtimes it operates +itself, and — separately — the bearer token `os package publish` uses to +authenticate against a package catalog from CI (see +[Packages](/docs/build/packages)). A self-hosted deployment that connects to a +control plane presents a runtime token minted when the deployment was **bound** +to that control plane, not a key you paste into a file. + +## Legacy names + +These still resolve, but the canonical name is preferred and the legacy one may +be removed in a future major version. + +| Canonical | Legacy | Note | +|---|---|---| +| `OS_PORT` | `PORT` | Emits a one-shot deprecation warning. | +| `OS_AUTH_SECRET` | `AUTH_SECRET` | Emits a one-shot deprecation warning. | +| `OS_TENANCY_POSTURE` | `OS_MULTI_ORG_ENABLED` | The posture derives from the legacy boolean only when `OS_TENANCY_POSTURE` is unset: `true` there means isolated. Declare the posture directly — it is the variable the licence and startup checks are written against. | +| `OS_MULTI_ORG_ENABLED` | `OS_MULTI_TENANT` | | diff --git a/content/docs/reference/environment-variables.zh-Hans.mdx b/content/docs/reference/environment-variables.zh-Hans.mdx deleted file mode 100644 index 705c84f..0000000 --- a/content/docs/reference/environment-variables.zh-Hans.mdx +++ /dev/null @@ -1,106 +0,0 @@ ---- -title: 环境变量 -description: ObjectOS 运行时环境变量参考。 ---- - -使用环境变量进行部署级配置和密钥管理。 -使用系统设置进行租户/用户可编辑的应用配置。 - -> **命名。** 所有 ObjectStack 自有变量统一使用 `OS_` 前缀。1.0 之前的无前缀名称（`PORT`、`AUTH_SECRET`、`OS_MULTI_TENANT` 等）仍可使用,但会触发一次性弃用警告。新部署请优先使用规范的 `OS_*` 名称,参见[旧别名](#legacy-aliases)。 - -## 核心 - -| 变量 | 是否必需 | 说明 | -|---|---:|---| -| `OS_PORT` | 否 | 运行时监听的 HTTP 端口。默认 `3000`。旧别名:`PORT`。 | -| `OS_AUTH_SECRET` | 启用 auth 时必需 | 用于派生各项目 auth 密钥的基础密钥。旧别名:`AUTH_SECRET`。 | - -## Artifact 与项目解析 - -| 变量 | 是否必需 | 说明 | -|---|---:|---| -| `OS_ARTIFACT_FILE` | 文件模式 | 已编译 `objectstack.json` 的路径或 `http(s)://` URL。由 ObjectOS 配置读取,并作为 `artifactPath` 传给 `createStandaloneStack`。云连接部署可将其指向已发布的云端 artifact URL。 | -| `OS_ARTIFACT_PATH` | 备选 | 同一路径或 URL 的框架级名称,由 `@objectstack/runtime` 直接识别（CLI `dev`/`start`）。默认 `/dist/objectstack.json`。 | -| `OS_PROJECT_ID` | 可选 | `OS_ENVIRONMENT_ID` 的旧别名,ObjectOS 配置为向后兼容接受。新部署中优先使用 `OS_ENVIRONMENT_ID`。 | -| `OS_ENVIRONMENT_ID` | 可选 | standalone stack 的环境 id（默认 `proj_local`）。也用于派生项目级 auth 密钥。ObjectOS 配置也接受旧别名 `OS_PROJECT_ID`。 | -| `OS_ORGANIZATION_ID` | 可选 | 文件支持模式下的默认组织 id（默认 `org_local`）。 | -| `OS_MCP_SERVER_ENABLED` | 否 | 控制通过 Streamable HTTP 在 `/api/v1/mcp` 提供的 Model Context Protocol 服务器——且仅控制该 HTTP 表面。**默认开启**（16.0+）：未设置时端点即被提供；设置显式假值（`false`/`0`/`off`/`no`）可将其关闭。需要已认证的主体。遗留行为：`OS_MCP_SERVER_ENABLED=true` 在接下来一个版本内仍会附带弃用警告地自动启动 stdio 传输——请改用 `OS_MCP_STDIO_ENABLED`。 | -| `OS_MCP_STDIO_ENABLED` | 否 | 设为真值（`true`/`1`/`on`/`yes`）以自动启动长驻的 **stdio** MCP 传输。默认关闭，且与 `OS_MCP_SERVER_ENABLED`（仅控制 HTTP 表面）相互独立。需要 `OS_MCP_STDIO_API_KEY`。 | -| `OS_MCP_STDIO_API_KEY` | 启用 stdio 时必需 | stdio 传输绑定到的 API 密钥（`osk_...`）对应的主体。通过与 HTTP MCP 相同的校验 + 授权链解析，因此 RLS/FLS 与租户隔离同样生效。失败即关闭（fail-closed）：启用 stdio 自动启动但没有可解析的密钥时，服务器会拒绝启动 stdio 传输。 | -| `OS_CLOUD_URL` | 可选 | marketplace 代理与本地 package 安装的控制平面基础 URL。设为 `off` 或 `local` 可禁用 marketplace 功能。在 standalone 分发中不再用于 host stack 的主机名路由。 | -| `OS_MULTI_ORG_ENABLED` | 否 | 设为 `true` 以启用多租户路由/组织切换（默认 `false`）。旧别名:`OS_MULTI_TENANT`。 | -| `OS_RUNTIME_PORT` | 仅开发 | 当在 `http://localhost:` 开发时,用于构建平台 SSO 回调 URL 的本地端口。 | - -> **Artifact 热重载。** standalone stack 在非生产环境下（由 `NODE_ENV` 控制） -> 自动重载本地 artifact;不再需要 7.x 的显式 `OS_WATCH_ARTIFACT=1` 标志。 - -## 缓存 - -| 变量 | 默认值 | 说明 | -|---|---:|---| -| `OS_KERNEL_CACHE_SIZE` | `32` | 缓存项目内核的最大数量。 | -| `OS_KERNEL_TTL_MS` | `900000` | 项目内核的空闲 TTL。 | -| `OS_ENV_CACHE_TTL_MS` | `300000` | 环境/主机名缓存 TTL。 | -| `OS_ARTIFACT_CACHE_TTL_MS` | `300000` | Artifact 响应缓存 TTL。 | - -## Auth 与可信来源 - -| 变量 | 说明 | -|---|---| -| `AUTH_SECRET` | `OS_AUTH_SECRET` 的旧别名。本版本仍可使用;请优先使用 `OS_AUTH_SECRET`。 | -| `OS_TRUSTED_ORIGINS` | 逗号分隔的额外可信来源。 | -| `OS_ROOT_DOMAIN` | 平台 SSO 部署中信任项目子域的根域。 | -| `OS_PLATFORM_SSO` | 设为 `false` 以禁用平台 SSO 装配。 | -| `OS_RUNTIME_PORT` | 用于 localhost 项目主机名的本地开发辅助。 | - -## 数据库 - -云端联动模式下,控制平面在 artifact 响应中返回每个项目的运行时数据库配置。文件支持模式下,ObjectOS 从 artifact 读取数据源声明。作为最后回退,框架还识别以下变量： - -| 变量 | 说明 | -|---|---| -| `OS_DATABASE_URL` | 连接 URL（`file:./db.sqlite`、`libsql://…`、`postgres://…`、`mongodb://…`、`memory://`）。独立模式与 CLI `dev` 使用。 | -| `OS_DATABASE_DRIVER` | 覆盖根据 URL 自动检测的驱动。 | -| `OS_DATABASE_AUTH_TOKEN` | 用于 Turso/libSQL 等托管驱动的 auth token。 | -| `OS_BUSINESS_DB_URL` | ObjectOS wrapper 对每个项目业务数据库 URL 的约定。在部署中将其解析到 `OS_DATABASE_URL` 或运行时数据源覆盖。 | -| `OS_CACHE_DIR` | 本地 artifact 与运行时缓存目录（默认 `/var/cache/objectos`）。 | -| `OS_SKIP_SCHEMA_SYNC` | 设为 `1` 时在启动时跳过 ObjectQL DDL 同步。schema 由外部管理时使用。 | -| `OS_TELEMETRY_DB` | 生命周期类系统数据的专用数据源（14.5+）。`objectstack dev` 自动预置 `.telemetry.db`；设为 `0` 可关闭，设为路径/URL 可在任意环境开启。 | - -## 数据生命周期 - -| 变量 | 默认 | 说明 | -|---|---:|---| -| `OS_LIFECYCLE_DISABLED` | 未设置（服务开启） | 设为 `1` 可禁用 LifecycleService（保留期回收器、表轮换、审计归档器——14.4+）。保留期窗口本身通过 `lifecycle.retention_overrides` 设置调整，而非环境变量。 | - -对 ObjectOS 客户部署,优先使用显式控制平面运行时配置或 artifact 数据源配置,而非依赖容器本地默认值。 - -## 可观测性 - -追踪与指标导出为按需启用。导出器默认为 `noop`,因此在你选择之前部署不会发出任何数据 —— 仅设置端点不起作用。 - -| 变量 | 默认值 | 说明 | -|---|---:|---| -| `OS_OBS_EXPORTER` | `noop` | 遥测导出器:`noop` \| `console` \| `json` \| `otlp`。本地调试用 `console`/`json`,接入采集器用 `otlp`。 | -| `OS_OTLP_ENDPOINT` | — | OTLP/HTTP 根 URL（例如 `https://otlp.grafana.net/otlp`）。当 `OS_OBS_EXPORTER=otlp` 时必需;若为空,运行时会告警并回退到 `noop`。 | -| `OS_OTLP_HEADERS` | — | 额外的 OTLP 头（例如鉴权）,以逗号分隔的 `key=value` 对表示。 | -| `OS_OBS_SERVICE_NAME` | — | 发出的 span/指标上的 `service.name` 资源属性。 | -| `OS_OBS_DEPLOYMENT_ENV` | `production` | `deployment.environment` 资源属性。 | -| `OS_OTLP_FLUSH_MS` | — | OTLP 导出器的刷新间隔,单位毫秒。 | - -## 设置命名空间覆盖 - -系统设置（租户/用户可编辑的 `ai`、`email`、`feature_flags` 等命名空间）可在部署级用一个名为 `OS__` 的环境变量固定 —— 全部大写,并将 `.` 与 `-` 替换为 `_`。例如 `ai.openai_base_url` → `OS_AI_OPENAI_BASE_URL`,`feature_flags.ai_enabled` → `OS_FEATURE_FLAGS_AI_ENABLED`。自 9.0 起,无前缀的别名已被移除 —— 只读取带 `OS_` 前缀的形式。 - -Google 登录（在 **Setup → Authentication** 中配置）也在部署级读取 `GOOGLE_CLIENT_ID` 与 `GOOGLE_CLIENT_SECRET`。 - -## 旧别名 [#legacy-aliases] - -以下 1.0 之前的名称在本版本仍可使用,但会触发一次性弃用警告,并将在未来的主版本中移除。请优先使用规范名称。 - -| 规范名称 | 旧别名 | -|---|---| -| `OS_PORT` | `PORT` | -| `OS_AUTH_SECRET` | `AUTH_SECRET` | -| `OS_MULTI_ORG_ENABLED` | `OS_MULTI_TENANT` | -| `OS_ENVIRONMENT_ID` | `OS_PROJECT_ID` | diff --git a/content/docs/resources/changelog.de.mdx b/content/docs/resources/changelog.de.mdx deleted file mode 100644 index ebdfd74..0000000 --- a/content/docs/resources/changelog.de.mdx +++ /dev/null @@ -1,210 +0,0 @@ ---- -title: Changelog & Versionierung -description: Wie ObjectOS versioniert wird, was sich zwischen Releases ändert und was unterstützt wird. ---- - -## Versionierungsrichtlinie - -ObjectOS folgt **[Semantic Versioning](https://semver.org/)**: `MAJOR.MINOR.PATCH`. - -| Versionssprung | Was es bedeutet | Was zu tun ist | -|---|---|---| -| **Patch** (`10.0.0 → 10.0.1`) | Fehlerbehebungen, keine Verhaltensänderung | Aktualisieren, keine App-Änderungen nötig | -| **Minor** (`10.0 → 10.1`) | Neue Funktionen, abwärtskompatibel | Aktualisieren, optional neue Funktionen übernehmen | -| **Major** (`9 → 10`) | Breaking Changes, in den Release Notes dokumentiert | Lesen Sie den Migrationsleitfaden vor dem Upgrade | - -Alle `@objectstack/*`-Pakete werden gemeinsam mit einer synchronisierten -Versionsnummer veröffentlicht — sie werden als Matrix getestet, nicht einzeln. - -## Kompatibilitätsmatrix - -| Komponente | Kompatibilitätsregel | -|---|---| -| ObjectOS-Image ↔ kompiliertes Artefakt | Gleiche Minor-Version. Ein 10.2.x-Image führt ein 10.2.x-Artefakt aus; ein 10.2-Artefakt kann Funktionen nutzen, die in einem 10.0-Image nicht verfügbar sind. | -| ObjectOS ↔ CLI | Gleiche Minor-Version empfohlen. Die per `npm i -g` installierte CLI erzeugt Scaffolds, die auf ihre eigene Version gepinnt sind. | -| ObjectOS ↔ Datenbanktreiber | Treiber durch den Image-Build gepinnt; prüfen Sie Postgres ≥ 13 / MongoDB ≥ 5 / Turso (jede aktuelle Version). | -| Node.js | **20 LTS oder neuer**. 22 LTS empfohlen für neue Deployments. | - -## Support-Zeiträume - -| Branch | Status | Bis | -|---|---|---| -| **10.x** (aktuell) | Aktive Entwicklung; neue Funktionen und Fixes | Mindestens 12 Monate nach dem Erscheinen von 11.0 | -| **9.x** | Nur Sicherheitsfixes | EOL mit dem Release von 11.0 | -| **≤ 8.x** | Nicht unterstützt | Bereits EOL | - -Kritische Sicherheitsfixes werden auf den aktuellen und den vorherigen -Major-Branch zurückportiert. Alles andere landet auf `main`. - -## Release Notes - -Veröffentlichte ObjectOS-Versionen und ihre CHANGELOG-Einträge werden hier publiziert: - -- **npm**: [`@objectstack/runtime`](https://www.npmjs.com/package/@objectstack/runtime) -- **GitHub**: [github.com/objectstack-ai/objectos/releases](https://github.com/objectstack-ai/objectos/releases) -- **Quell-CHANGELOG**: [`CHANGELOG.md`](https://github.com/objectstack-ai/objectstack/blob/main/CHANGELOG.md) -- **Ausführliche Release Notes**: [`RELEASE_NOTES.md`](https://github.com/objectstack-ai/objectstack/blob/main/RELEASE_NOTES.md) - -Abonnieren Sie Releases auf GitHub, um benachrichtigt zu werden. - -## Aktuelle Highlights - -### 10.x — aktueller Release-Zug - -ObjectOS One und der gebündelte Server laufen jetzt auf `@objectstack` **10.2.0**. -Trotz des Major-Sprungs ist der Runtime-Boot-Vertrag unverändert — -`createStandaloneStack` nimmt weiterhin dieselben Artefakt-, Umgebungs- und -Datenbankeinstellungen entgegen — und jeder Breaking Change landet in der -Multi-Org-Mandantenschicht, sodass ein **single-tenant ObjectOS-Deployment (der -Standard) ohne Konfigurationsänderungen von 9.x weiterrollt**. Was sich bewegt hat: - -- **Zeilenbezogenes Org-Scoping in ein eigenes Plugin ausgelagert** (10.0, Breaking) — - das automatische Stempeln von `organization_id`, das Pro-Org-Seed-Replay und der - Default-Org-Bootstrap wurden aus `@objectstack/plugin-security` in das optionale - [`@objectstack/plugin-org-scoping`](https://www.npmjs.com/package/@objectstack/plugin-org-scoping) - verschoben. Single-Org-Deployments sind schlanker (kein Wildcard-RLS, das bei jeder - Abfrage entfernt werden muss), und `OS_MULTI_TENANT=true` registriert das Plugin - weiterhin automatisch vor `plugin-security`, sodass per CLI gesteuerte Projekte keine - Codeänderungen benötigen. Laut ADR-0002 ist ein *Tenant* physische Isolation (eine - Umgebung = eine Datenbank); `organization_id` ist *logisches* Scoping innerhalb einer - DB und verdient daher sein eigenes Plugin. -- **Keine automatischen persönlichen Workspaces mehr** (10.0, Breaking) — - `plugin-security` erstellt nicht mehr für jeden neuen Benutzer eine - „`'s Workspace`"-Org. Benutzer nehmen jetzt eine Einladung an oder erstellen - explizit ihre erste Organisation (das Slack-/Linear-/GitHub-Orgs-Modell). Der erste - registrierte Benutzer — automatisch zum Plattform-Admin befördert — erhält im - Multi-Tenant-Modus weiterhin eine einzige `Default Organization`, damit seine Session - RLS auflöst; single-tenant Deployments erstellen keine Orgs. -- **`record`-Formularfeldtyp** (ADR-0014) — `Record`-Eigenschaften (etwa - die `fields`-Map eines Objekts) sind jetzt als vollwertige Formularfelder in Studio - editierbar, statt als rohes JSON durchzusickern, und der Objektvorschau-Bereich - bindet den echten `ObjectGrid`-Renderer ein — was Sie in der Vorschau sehen, ist das, - was ausgeliefert wird. -- **Steckbare Embeddings über `IEmbedder`** — ein neues Embedder-Protokoll plus - [`@objectstack/embedder-openai`](https://www.npmjs.com/package/@objectstack/embedder-openai); - die Knowledge-/RAG-Adapter nutzen jetzt `IEmbedder` und wurden umbenannt, um das - `plugin-`-Präfix abzulegen. -- **Public Forms** — anonyme Web-to-Lead-/Web-to-Case-Formulare, bereitgestellt unter - `/f/:slug`, eine einheitliche FormPage (öffentlich `/f/:slug` + intern - `/forms/:name`), eine `type: 'form'`-Aktionsvariante und `defaultDetailForm` auf - `ObjectSchema`. -- **Cloud-Identitätstrennung** — `os cloud login` ist jetzt von `os login` getrennt, - die Cloud-Control-Plane wurde in ein privates Repo verschoben (eine schlankere - OSS-Runtime), und `objectstack init` scaffoldet wieder ein Projekt, das baut und - bootet. - -### 9.x - -Der 9.x-Zug lief auf `@objectstack` **9.0 – 9.11** vor dem 10.0-Umstieg. -Der Runtime-Boot-Vertrag ist gegenüber 8.0 unverändert — `createStandaloneStack` -nimmt weiterhin dieselben Artefakt-, Umgebungs- und Datenbankeinstellungen entgegen —, -sodass ein 8.0-Deployment ohne Konfigurationsänderungen weiterrollt. Was sich -bewegt hat, ist die autorenseitige Oberfläche: - -- **Analytics-Datasets sind die einzige Autorenoberfläche** (9.0, Breaking) — - Dashboard-Widgets, Berichte und Listen-Charts binden jetzt ein semantisches - `dataset` (`defineDataset(...)`) und wählen Dimensionen/Maße **per Name**. Die - alten Inline-Abfragefelder (`object`/`valueField`/`aggregate` an Widgets, - `objectName`/`columns`/`groupingsDown` an Berichten, `xAxisField`/`yAxisFields` - an Listen-Charts) wurden entfernt. Migration: Verschieben Sie die Inline-Abfrage - in ein `defineDataset` und referenzieren Sie es per Name. `ChartTypeSchema` hat - außerdem 8 Varianttypen verworfen, die nur als ihr Basistyp gerendert wurden - (`stacked-bar`→`bar`, `spline`→`line`, `bubble`→`scatter`, …). -- **Strengere Validierung zur Build-Zeit** (9.6–9.7) — `os compile` **scheitert** - jetzt an blanken Feldreferenzen (`amount` statt `record.amount`), unbekannten - CEL-Funktionen und falscher Interpolationssyntax für Flow-Werte, jeweils mit - einem „Meinten Sie"-Hinweis. Ein Stack, der zuvor „baute, aber stillschweigend - falsch war", scheitert jetzt lautstark — führen Sie `os compile` nach dem Upgrade - erneut aus und beheben Sie, was es bemängelt. -- **Zahlenfeld-Formeln berechnen gemischte Arithmetik** (9.7) — `record.amount / 100` - und `record.price * 2` werten jetzt aus, statt stillschweigend `null` zu liefern; - der `/ 100.0`-Float-Literal-Workaround ist nicht mehr nötig. -- **REST-Gating auf Objektebene, jetzt durchgesetzt** (ADR-0049) — `apiEnabled: false` - eines Objekts entfernt es aus der REST-Oberfläche, und eine `apiMethods`-Whitelist - schränkt ein, welche Operationen erreichbar sind. Zuvor geparst, aber nicht - durchgesetzt. -- **Paketdokumentation als Metadaten + `book`-Navigation** (9.3–9.6) — - `src/docs/*.md` registrieren sich als `doc`-Metadaten; das `book`-Element - (ADR-0046) deklariert eine Navigationsachse mit abgeleiteter Mitgliedschaft, - bereitgestellt unter `GET /api/v1/meta/book/:name/tree` mit Audience-Gating. -- **`os package install`** (9.3) — installiert ein Paket in eine laufende Runtime - aus einer Katalog-ID oder einem Inline-Artefakt für Air-Gap-Umgebungen, - authentifiziert mit `--email` / `--password`. -- **Genehmigungen** (9.3) — Zurücksenden zur Überarbeitung (`maxRevisions`, - Standard 3), jobs-gestützte SLA-Auto-Eskalation, Listensuche/Paginierung und - sitzungsfreie zweisprachige Bestätigungslinks zum Genehmigen/Ablehnen. -- **Eingehende Webhook-Flow-Trigger** (9.3) — ein `type: 'api'`-Flow stellt einen - HMAC-verifizierten `POST /api/v1/automation/hooks/:flowName/:hookId`-Endpunkt mit - idempotenter, queue-gestützter Aufnahme bereit. -- **Aufbewahrung von Benachrichtigungen standardmäßig aktiv** (9.5) — der - Benachrichtigungsverlauf wird automatisch nach **90 Tagen** bereinigt; setzen Sie - die Messaging-Einstellung `retentionDays: 0`, um den Verlauf dauerhaft zu behalten. -- **CLI bündelt AI-Provider-SDKs** (9.0) — OpenAI-kompatible Provider (DeepSeek, - DashScope, SiliconFlow, OpenRouter, Cloudflare) funktionieren auf einer global - installierten CLI sofort. - -Eine zu beachtende Verhaltensänderung beim Flow-Authoring: Der `outputVariable` -eines `create_record`-Knotens hält jetzt das **erstellte Datensatzobjekt** (zuvor -die blanke ID), aktualisieren Sie also `{var}`-Referenzen, die eine ID erwarteten, -auf `{var.id}`. - -### 8.0.x - -ObjectOS One und der gebündelte Server liefen auf `@objectstack` **8.0.1**. - -- **MCP über Streamable HTTP** — jede Bereitstellung kann als netzwerkerreichbarer - [Model-Context-Protocol](https://modelcontextprotocol.io)-Server fungieren. - Aktivierung über `OS_MCP_SERVER_ENABLED=true`; der Endpunkt liegt unter - `/api/v1/mcp` mit fail-closed-Authentifizierung (anonyme Anfragen werden - abgelehnt). Das Plugin wurde von `@objectstack/plugin-mcp-server` zu - `@objectstack/mcp` umbenannt. -- **Self-Service-API-Keys** — `POST /api/v1/keys` erzeugt einen nur einmal - angezeigten `sys_api_key`. Die REST-Daten- und Metadaten-APIs (`/api/v1/data`, - `/api/v1/meta`) authentifizieren API-Keys jetzt über denselben Verifier wie MCP - und laufen mit den Berechtigungen und der Datensatz-Sicherheit des - Key-Inhabers. -- **Feldbezogene Bedingungsregeln** — `visibleWhen`, `readonlyWhen` und - `requiredWhen` werden serverseitig von ObjectQL durchgesetzt, nicht nur in der - Formular-UI. -- **Wiederverwendbarer RLS-Lesefilter** — `security.getReadFilter(object, context)` - stellt den Datensatzzugriffs-Lesebereich bereit; Analytics-Datasets, Dashboards - und Berichte greifen darauf zu und schließen fail-closed, wenn der Bereich nicht - sicher angewendet werden kann. -- **Standalone-Host-Stack** — die Runtime liefert einen single-tenant - `createStandaloneStack`-Host; der cloud-verbundene, hostname-geroutete - `createObjectOSStack`-Wrapper aus 7.x wurde entfernt. Eine Cloud-Bereitstellung - verweist `OS_ARTIFACT_FILE` jetzt auf eine veröffentlichte Artifact-URL. - -### 5.0 — Umbenennung `project` → `environment` (veröffentlicht) - -Das Runtime-Konzept, das früher *Project* hieß, wurde durchgängig in *Environment* -umbenannt. Betroffen waren: - -- CLI-Flags: `--environment` / `-e` -- HTTP-Pfade: `/api/v1/environments/:environmentId/...` -- Header: `X-Environment-Id` -- Umgebungsvariablen: `OS_ENVIRONMENT_ID` (`OS_PROJECT_ID` bleibt als veralteter Alias erhalten) -- DB-Spalten: `environment_id` -- JSON-Schemas: `EnvironmentArtifact` - -## Upgrade - -Siehe [Upgrade und Rollback](/docs/operate/upgrade) für die konkreten -Schritte. Vorab-Prüfung: - -1. Lesen Sie den CHANGELOG-Eintrag für jede Minor-Version zwischen Ihrer - aktuellen und der Zielversion. -2. Führen Sie `os diff ` aus, um Breaking - Schema-Änderungen aufzudecken. -3. Führen Sie `os doctor` gegen die Zielversion aus. -4. Bringen Sie eine Canary-Instanz hoch, bevor Sie die gesamte Flotte ausrollen. -5. Halten Sie einen Rollback-Plan sowohl für das Image-Tag als auch für die - Artefakt-Version bereit (sie werden unabhängig voneinander ausgerollt). - -## Regressionen melden - -Wenn ein Patch oder eine Minor-Version etwas zuvor Funktionierendes bricht, melden Sie -einen Bug unter -[github.com/objectstack-ai/objectos/issues](https://github.com/objectstack-ai/objectos/issues) -mit der Version, von der / auf die Sie aktualisiert haben. Wir behandeln Regressionen als -die höchstpriorisierte Fehlerklasse. diff --git a/content/docs/resources/changelog.es.mdx b/content/docs/resources/changelog.es.mdx deleted file mode 100644 index a0f6565..0000000 --- a/content/docs/resources/changelog.es.mdx +++ /dev/null @@ -1,218 +0,0 @@ ---- -title: Registro de cambios y versionado -description: Cómo se versiona ObjectOS, qué cambia entre versiones y qué tiene soporte. ---- - -## Política de versionado - -ObjectOS sigue el **[Versionado semántico](https://semver.org/)**: `MAJOR.MINOR.PATCH`. - -| Incremento de versión | Qué significa | Qué hacer | -|---|---|---| -| **Parche** (`10.0.0 → 10.0.1`) | Corrección de errores, sin cambios de comportamiento | Actualiza, no se requieren cambios en la aplicación | -| **Menor** (`10.0 → 10.1`) | Nuevas funciones, compatible con versiones anteriores | Actualiza y, opcionalmente, adopta las nuevas funciones | -| **Mayor** (`9 → 10`) | Cambios incompatibles documentados en las notas de versión | Lee la guía de migración antes de actualizar | - -Todos los paquetes `@objectstack/*` se publican juntos con un número de -versión sincronizado: se prueban como una matriz, no de forma independiente. - -## Matriz de compatibilidad - -| Componente | Regla de compatibilidad | -|---|---| -| Imagen de ObjectOS ↔ artefacto compilado | Misma versión menor. Una imagen 10.2.x ejecuta un artefacto 10.2.x; un artefacto 10.2 puede usar funciones no disponibles en una imagen 10.0. | -| ObjectOS ↔ CLI | Se recomienda la misma versión menor. La CLI en `npm i -g` genera andamiajes fijados a su propia versión. | -| ObjectOS ↔ controlador de base de datos | El controlador queda fijado por la compilación de la imagen; verifica Postgres ≥ 13 / MongoDB ≥ 5 / Turso (cualquiera actual). | -| Node.js | **20 LTS o posterior**. Se recomienda 22 LTS para nuevos despliegues. | - -## Ventanas de soporte - -| Rama | Estado | Hasta | -|---|---|---| -| **10.x** (actual) | Desarrollo activo; nuevas funciones y correcciones | Al menos 12 meses después del lanzamiento de 11.0 | -| **9.x** | Solo correcciones de seguridad | EOL en el lanzamiento de 11.0 | -| **≤ 8.x** | Sin soporte | Ya en EOL | - -Las correcciones de seguridad críticas se retroportan a la versión mayor -actual y a la anterior. Todo lo demás se incorpora en `main`. - -## Notas de versión - -Las versiones publicadas de ObjectOS y sus entradas de CHANGELOG se publican en: - -- **npm**: [`@objectstack/runtime`](https://www.npmjs.com/package/@objectstack/runtime) -- **GitHub**: [github.com/objectstack-ai/objectos/releases](https://github.com/objectstack-ai/objectos/releases) -- **CHANGELOG de origen**: [`CHANGELOG.md`](https://github.com/objectstack-ai/objectstack/blob/main/CHANGELOG.md) -- **Notas de versión extensas**: [`RELEASE_NOTES.md`](https://github.com/objectstack-ai/objectstack/blob/main/RELEASE_NOTES.md) - -Suscríbete a las versiones en GitHub para recibir notificaciones. - -## Aspectos destacados recientes - -### 10.x — tren de versiones actual - -ObjectOS One y el servidor incluido ahora se ejecutan sobre `@objectstack` **10.2.0**. -A pesar del salto de versión mayor, el contrato de arranque del runtime no cambia -—`createStandaloneStack` sigue tomando el mismo artefacto, entorno y ajustes de -base de datos— y todos los cambios incompatibles caen en la capa de tenencia -multi-organización, por lo que un **despliegue de ObjectOS de inquilino único -(el predeterminado) actualiza desde 9.x sin cambios de configuración**. Lo que se -movió: - -- **El alcance por organización a nivel de fila se separó en su propio plugin** - (10.0, cambio incompatible): el autosellado de `organization_id`, la repetición - de seeds por organización y el arranque de la organización predeterminada se - movieron de `@objectstack/plugin-security` al plugin opcional - [`@objectstack/plugin-org-scoping`](https://www.npmjs.com/package/@objectstack/plugin-org-scoping). - Los despliegues de una sola organización son más ligeros (no hay RLS comodín que - eliminar en cada consulta), y `OS_MULTI_TENANT=true` sigue registrando - automáticamente el plugin por delante de `plugin-security`, por lo que los - proyectos gestionados por la CLI no necesitan cambios de código. Según el - ADR-0002, un *tenant* es aislamiento físico (un Environment = una base de datos); - `organization_id` es alcance *lógico* dentro de una misma BD, así que merece su - propio plugin. -- **Se acabaron los espacios de trabajo personales automáticos** (10.0, cambio - incompatible): `plugin-security` ya no crea una organización «`'s - Workspace`» para cada nuevo usuario. Ahora los usuarios aceptan una invitación o - crean explícitamente su primera organización (el modelo de Slack / Linear / - GitHub-Orgs). El primer usuario registrado —autopromovido a administrador de la - plataforma— sigue obteniendo una única `Default Organization` en modo - multi-inquilino para que su sesión resuelva el RLS; los despliegues de inquilino - único no crean ninguna organización. -- **Tipo de campo de formulario `record`** (ADR-0014): las propiedades - `Record` (como el mapa `fields` de un objeto) ahora son editables como - campos de formulario de primera clase en Studio, en lugar de filtrarse como JSON - en bruto, y el panel de previsualización del objeto monta el renderizador real - `ObjectGrid`: lo que previsualizas es lo que se publica. -- **Embeddings conectables mediante `IEmbedder`**: un nuevo protocolo de embedder - junto con - [`@objectstack/embedder-openai`](https://www.npmjs.com/package/@objectstack/embedder-openai); - los adaptadores de conocimiento / RAG ahora consumen `IEmbedder` y se - renombraron para eliminar el prefijo `plugin-`. -- **Formularios públicos**: formularios anónimos de Web-to-Lead / Web-to-Case - servidos en `/f/:slug`, una FormPage unificada (`/f/:slug` público + `/forms/:name` - interno), una variante de acción `type: 'form'` y `defaultDetailForm` en - `ObjectSchema`. -- **Separación de la identidad en la nube**: `os cloud login` ahora es independiente - de `os login`, el plano de control de la nube se movió a un repositorio privado - (un runtime OSS más ligero), y `objectstack init` vuelve a generar un proyecto que - compila y arranca. - -### 9.x - -El tren 9.x se ejecutó sobre `@objectstack` **9.0 – 9.11** antes del cambio a 10.0. -El contrato de arranque del runtime no cambia respecto a 8.0 — -`createStandaloneStack` sigue tomando el mismo artefacto, entorno y ajustes de -base de datos—, por lo que un despliegue 8.0 actualiza sin cambios de -configuración. Lo que se movió es la superficie orientada al autor: - -- **Los datasets de analítica son la única superficie de autor** (9.0, cambio - incompatible): los widgets de panel, los informes y los gráficos de lista - ahora vinculan un `dataset` semántico (`defineDataset(...)`) y seleccionan - dimensiones/medidas **por nombre**. Se eliminaron los antiguos campos de - consulta en línea (`object`/`valueField`/`aggregate` en widgets, - `objectName`/`columns`/`groupingsDown` en informes, `xAxisField`/`yAxisFields` - en gráficos de lista). Migración: mueve la consulta en línea a un - `defineDataset` y refiérete a él por nombre. `ChartTypeSchema` también eliminó - 8 tipos de variante que solo se renderizaban como su base (`stacked-bar`→`bar`, - `spline`→`line`, `bubble`→`scatter`, …). -- **Validación más estricta en tiempo de compilación** (9.6–9.7): `os compile` - ahora **falla** ante referencias de campo sin prefijo (`amount` en lugar de - `record.amount`), funciones CEL desconocidas y sintaxis de interpolación de - valores de flujo incorrecta, cada una con una sugerencia «quizás quisiste - decir». Un stack que antes «compilaba pero estaba silenciosamente mal» ahora - falla de forma visible: vuelve a ejecutar `os compile` tras actualizar y - corrige lo que señale. -- **Las fórmulas de campos numéricos calculan aritmética mixta** (9.7): - `record.amount / 100` y `record.price * 2` ahora se evalúan en lugar de - producir silenciosamente `null`; ya no se necesita el truco del literal flotante - `/ 100.0`. -- **Control de REST a nivel de objeto, ahora aplicado** (ADR-0049): el - `apiEnabled: false` de un objeto lo retira de la superficie REST, y una lista - blanca `apiMethods` restringe qué operaciones son accesibles. Antes se - analizaba pero no se aplicaba. -- **Documentación de paquetes como metadatos + navegación `book`** (9.3–9.6): - los `src/docs/*.md` se registran como metadatos `doc`; el elemento `book` - (ADR-0046) declara una espina de navegación de pertenencia derivada, servida en - `GET /api/v1/meta/book/:name/tree` con control por audiencia. -- **`os package install`** (9.3): instala un paquete en un runtime en ejecución - desde un id de catálogo o un artefacto en línea aislado de la red, - autenticándose con `--email` / `--password`. -- **Aprobaciones** (9.3): devolución para revisión (`maxRevisions`, predeterminado - 3), autoescalada de SLA respaldada por jobs, búsqueda/paginación de listas y - enlaces de confirmación de aprobar/rechazar bilingües y sin sesión. -- **Disparadores de flujo por webhook entrante** (9.3): un flujo `type: 'api'` - monta un endpoint `POST /api/v1/automation/hooks/:flowName/:hookId` verificado - con HMAC, con ingesta idempotente y respaldada por cola. -- **Retención de notificaciones activada por defecto** (9.5): el historial de - notificaciones se poda automáticamente a los **90 días**; pon - `retentionDays: 0` en la mensajería para conservar el historial para siempre. -- **La CLI incluye los SDK de proveedores de IA** (9.0): los proveedores - compatibles con OpenAI (DeepSeek, DashScope, SiliconFlow, OpenRouter, - Cloudflare) funcionan de inmediato en una CLI instalada globalmente. - -Un cambio de comportamiento en la autoría de flujos a tener en cuenta: el -`outputVariable` de un nodo `create_record` ahora contiene el **objeto de -registro creado** (antes era el id sin más), así que actualiza las referencias -`{var}` que esperaban un id a `{var.id}`. - -### 8.0.x - -ObjectOS One y el servidor incluido se ejecutaban sobre `@objectstack` **8.0.1**. - -- **MCP sobre Streamable HTTP**: cada despliegue puede actuar como un servidor - [Model Context Protocol](https://modelcontextprotocol.io) accesible por red. - Actívalo con `OS_MCP_SERVER_ENABLED=true`; el endpoint se sirve en `/api/v1/mcp` - con autenticación fail-closed (las solicitudes anónimas se rechazan). El plugin - pasó a llamarse de `@objectstack/plugin-mcp-server` a `@objectstack/mcp`. -- **Claves de API autoservicio**: `POST /api/v1/keys` genera una `sys_api_key` - que se muestra una sola vez. Las API REST de datos y metadatos (`/api/v1/data`, - `/api/v1/meta`) ahora autentican las claves de API con el mismo verificador que - MCP, ejecutándose bajo los permisos y la seguridad a nivel de registro del - propietario de la clave. -- **Reglas condicionales por campo**: `visibleWhen`, `readonlyWhen` y - `requiredWhen` se aplican en el servidor mediante ObjectQL, no solo en la UI del - formulario. -- **Filtro de lectura RLS reutilizable**: `security.getReadFilter(object, context)` - expone el alcance de lectura del acceso a registros; los datasets de analítica, - los paneles y los informes se conectan a él y fallan en cerrado cuando el alcance - no puede aplicarse de forma segura. -- **Stack de host autónomo**: el runtime incluye un host - `createStandaloneStack` de inquilino único; se eliminó el wrapper - `createObjectOSStack` de 7.x, conectado a la nube y enrutado por hostname. Un - despliegue en la nube ahora apunta `OS_ARTIFACT_FILE` a una URL de artefacto - publicada. - -### 5.0 — cambio de nombre de `project` a `environment` (publicado) - -El concepto de runtime antes llamado *Project* pasó a llamarse *Environment* -en todo el sistema. Afectó a: - -- Indicadores de CLI: `--environment` / `-e` -- Rutas HTTP: `/api/v1/environments/:environmentId/...` -- Cabeceras: `X-Environment-Id` -- Variables de entorno: `OS_ENVIRONMENT_ID` (`OS_PROJECT_ID` se mantiene como alias obsoleto) -- Columnas de BD: `environment_id` -- Esquemas JSON: `EnvironmentArtifact` - -## Actualización - -Consulta [Actualización y reversión](/docs/operate/upgrade) para los pasos -mecánicos. Comprobaciones previas: - -1. Lee la entrada del CHANGELOG de cada versión menor entre tu versión - actual y la de destino. -2. Ejecuta `os diff ` para detectar cambios - de esquema incompatibles. -3. Ejecuta `os doctor` contra la versión de destino. -4. Pon en marcha una instancia canary antes de desplegar en toda la flota. -5. Ten un plan de reversión tanto para la etiqueta de la imagen como para - la versión del artefacto (se revierten de forma independiente). - -## Informar regresiones - -Si un parche o una versión menor rompe algo que antes funcionaba, abre un -informe de error en -[github.com/objectstack-ai/objectos/issues](https://github.com/objectstack-ai/objectos/issues) -indicando la versión desde la que actualizaste y a la que actualizaste. -Tratamos las regresiones como la clase de error de máxima prioridad. diff --git a/content/docs/resources/changelog.fr.mdx b/content/docs/resources/changelog.fr.mdx deleted file mode 100644 index 9a8eb63..0000000 --- a/content/docs/resources/changelog.fr.mdx +++ /dev/null @@ -1,221 +0,0 @@ ---- -title: Journal des modifications et versionnage -description: Comment ObjectOS est versionné, ce qui change entre les versions et ce qui est pris en charge. ---- - -## Politique de versionnage - -ObjectOS suit le **[versionnage sémantique](https://semver.org/)** : `MAJOR.MINOR.PATCH`. - -| Incrément de version | Signification | Que faire | -|---|---|---| -| **Patch** (`10.0.0 → 10.0.1`) | Corrections de bogues, aucun changement de comportement | Mettre à jour, aucune modification de l'application nécessaire | -| **Mineur** (`10.0 → 10.1`) | Nouvelles fonctionnalités, rétrocompatibles | Mettre à jour, adopter éventuellement les nouvelles fonctionnalités | -| **Majeur** (`9 → 10`) | Changements incompatibles documentés dans les notes de version | Lire le guide de migration avant de mettre à niveau | - -Tous les paquets `@objectstack/*` sont publiés ensemble avec un numéro de -version synchronisé — ils sont testés en tant que matrice, et non -indépendamment. - -## Matrice de compatibilité - -| Composant | Règle de compatibilité | -|---|---| -| Image ObjectOS ↔ artefact compilé | Même version mineure. Une image 10.2.x exécute un artefact 10.2.x ; un artefact 10.2 peut utiliser des fonctionnalités indisponibles dans une image 10.0. | -| ObjectOS ↔ CLI | Même version mineure recommandée. Le CLI dans `npm i -g` écrit des squelettes épinglés à sa propre version. | -| ObjectOS ↔ pilote de base de données | Pilote épinglé par la construction de l'image ; vérifier Postgres ≥ 13 / MongoDB ≥ 5 / Turso (toute version actuelle). | -| Node.js | **20 LTS ou plus récent**. 22 LTS recommandé pour les nouveaux déploiements. | - -## Fenêtres de support - -| Branche | Statut | Jusqu'à | -|---|---|---| -| **10.x** (actuelle) | Développement actif ; nouvelles fonctionnalités et corrections | Au moins 12 mois après la sortie de la 11.0 | -| **9.x** | Corrections de sécurité uniquement | Fin de vie à la sortie de la 11.0 | -| **≤ 8.x** | Non prise en charge | Déjà en fin de vie | - -Les correctifs de sécurité critiques sont rétroportés vers la version -majeure actuelle et la précédente. Tout le reste atterrit sur `main`. - -## Notes de version - -Les versions publiées d'ObjectOS et leurs entrées de CHANGELOG sont publiées à : - -- **npm** : [`@objectstack/runtime`](https://www.npmjs.com/package/@objectstack/runtime) -- **GitHub** : [github.com/objectstack-ai/objectos/releases](https://github.com/objectstack-ai/objectos/releases) -- **CHANGELOG source** : [`CHANGELOG.md`](https://github.com/objectstack-ai/objectstack/blob/main/CHANGELOG.md) -- **Notes de version détaillées** : [`RELEASE_NOTES.md`](https://github.com/objectstack-ai/objectstack/blob/main/RELEASE_NOTES.md) - -Abonnez-vous aux versions sur GitHub pour être notifié. - -## Points marquants récents - -### 10.x — train de versions actuel - -ObjectOS One et le serveur intégré tournent désormais sur `@objectstack` **10.2.0**. -Malgré le bond de version majeure, le contrat de démarrage du runtime est inchangé — -`createStandaloneStack` prend toujours le même artefact, le même environnement et -les mêmes paramètres de base de données — et chaque changement incompatible se -situe dans la couche de multilocation multi-organisations, de sorte qu'un -**déploiement ObjectOS mono-locataire (le cas par défaut) se met à jour depuis la -9.x sans aucun changement de configuration**. Ce qui a bougé : - -- **Le périmètre d'organisation au niveau des lignes est extrait dans son propre - plugin** (10.0, incompatible) — l'auto-marquage `organization_id`, la réexécution - des seeds par organisation et l'amorçage de l'organisation par défaut ont été - sortis de `@objectstack/plugin-security` vers le plugin optionnel - [`@objectstack/plugin-org-scoping`](https://www.npmjs.com/package/@objectstack/plugin-org-scoping). - Les déploiements mono-organisation sont plus légers (plus de RLS générique à - retirer à chaque requête), et `OS_MULTI_TENANT=true` enregistre toujours - automatiquement le plugin avant `plugin-security`, de sorte que les projets - pilotés par le CLI n'ont besoin d'aucun changement de code. Selon l'ADR-0002, un - *locataire* est une isolation physique (un Environment = une base de données) ; - `organization_id` est un périmètre *logique* à l'intérieur d'une seule base, il - mérite donc son propre plugin. -- **Plus d'espaces de travail personnels automatiques** (10.0, incompatible) — - `plugin-security` ne crée plus d'organisation « `'s Workspace` » pour chaque - nouvel utilisateur. Les utilisateurs acceptent désormais une invitation ou créent - explicitement leur première organisation (le modèle Slack / Linear / GitHub-Orgs). - Le premier utilisateur enregistré — auto-promu administrateur de la plateforme — - obtient toujours une unique `Default Organization` en mode multilocataire pour que - sa session résolve la RLS ; les déploiements mono-locataire ne créent aucune - organisation. -- **Type de champ de formulaire `record`** (ADR-0014) — les propriétés - `Record` (telles que la map `fields` d'un objet) sont désormais - éditables comme des champs de formulaire de première classe dans Studio au lieu de - transparaître en JSON brut, et le volet d'aperçu d'objet monte le véritable - moteur de rendu `ObjectGrid` — ce que vous prévisualisez correspond à ce qui est - livré. -- **Embeddings enfichables via `IEmbedder`** — un nouveau protocole d'embedder ainsi - que [`@objectstack/embedder-openai`](https://www.npmjs.com/package/@objectstack/embedder-openai) ; - les adaptateurs de connaissances / RAG consomment désormais `IEmbedder` et ont été - renommés pour abandonner le préfixe `plugin-`. -- **Formulaires publics** — des formulaires Web-to-Lead / Web-to-Case anonymes - servis sur `/f/:slug`, une FormPage unifiée (`/f/:slug` public + `/forms/:name` - interne), une variante d'action `type: 'form'` et `defaultDetailForm` sur - `ObjectSchema`. -- **Séparation de l'identité cloud** — `os cloud login` est désormais distinct de - `os login`, le plan de contrôle cloud a été déplacé vers un dépôt privé (un - runtime OSS plus léger), et `objectstack init` génère de nouveau un projet qui se - construit et démarre. - -### 9.x - -Le train 9.x a tourné sur `@objectstack` **9.0 – 9.11** avant la bascule vers la 10.0. -Le contrat de démarrage du runtime est inchangé depuis la 8.0 — -`createStandaloneStack` prend toujours les mêmes paramètres d'artefact, -d'environnement et de base de données — de sorte qu'un déploiement 8.0 se met à -jour sans changement de configuration. C'est la surface destinée aux auteurs qui -a évolué : - -- **Les datasets d'analytique sont l'unique surface d'auteur** (9.0, incompatible) — - les widgets de tableau de bord, les rapports et les list-charts lient désormais - un `dataset` sémantique (`defineDataset(...)`) et sélectionnent les - dimensions/mesures **par nom**. Les anciens champs de requête en ligne - (`object`/`valueField`/`aggregate` sur les widgets, - `objectName`/`columns`/`groupingsDown` sur les rapports, `xAxisField`/`yAxisFields` - sur les list-charts) ont été supprimés. Migration : déplacez la requête en ligne - dans un `defineDataset` et référencez-le par nom. `ChartTypeSchema` a également - abandonné 8 types de variantes qui ne faisaient que rendre comme leur type de base - (`stacked-bar`→`bar`, `spline`→`line`, `bubble`→`scatter`, …). -- **Validation plus stricte au moment du build** (9.6–9.7) — `os compile` - **échoue** désormais sur les références de champ nues (`amount` au lieu de - `record.amount`), les fonctions CEL inconnues et la mauvaise syntaxe - d'interpolation de valeurs de flux, chacune avec une suggestion - « vouliez-vous dire ». Une stack qui auparavant « se construisait mais était - silencieusement erronée » échoue désormais bruyamment — relancez `os compile` - après la mise à niveau et corrigez ce qu'il signale. -- **Les formules de champ numérique calculent l'arithmétique mixte** (9.7) — - `record.amount / 100` et `record.price * 2` s'évaluent désormais au lieu de - produire silencieusement `null` ; le contournement par littéral flottant - `/ 100.0` n'est plus nécessaire. -- **Contrôle REST au niveau de l'objet, désormais appliqué** (ADR-0049) — un - `apiEnabled: false` sur un objet le retire de la surface REST, et une liste - blanche `apiMethods` restreint les opérations accessibles. Auparavant analysé - mais non appliqué. -- **Documentation de paquet sous forme de métadonnées + navigation `book`** (9.3–9.6) — - les `src/docs/*.md` s'enregistrent comme métadonnées `doc` ; l'élément `book` - (ADR-0046) déclare une colonne vertébrale de navigation à appartenance dérivée, - servie sur `GET /api/v1/meta/book/:name/tree` avec un contrôle par audience. -- **`os package install`** (9.3) — installe un paquet dans un runtime en cours - d'exécution à partir d'un identifiant de catalogue ou d'un artefact en ligne - isolé (air-gapped), en s'authentifiant avec `--email` / `--password`. -- **Approbations** (9.3) — renvoi pour révision (`maxRevisions`, par défaut 3), - auto-escalade de SLA adossée aux jobs, recherche/pagination de listes, et liens - de confirmation d'approbation/rejet bilingues et sans session. -- **Déclencheurs de flux par webhook entrant** (9.3) — un flux `type: 'api'` monte - un endpoint `POST /api/v1/automation/hooks/:flowName/:hookId` vérifié par HMAC, - avec une ingestion idempotente et adossée à une file d'attente. -- **Rétention des notifications activée par défaut** (9.5) — l'historique des - notifications est auto-purgé à **90 jours** ; définissez `retentionDays: 0` dans - la messagerie pour conserver l'historique indéfiniment. -- **Le CLI embarque les SDK des fournisseurs d'IA** (9.0) — les fournisseurs - compatibles OpenAI (DeepSeek, DashScope, SiliconFlow, OpenRouter, Cloudflare) - fonctionnent immédiatement sur un CLI installé globalement. - -Un changement de comportement à noter côté création de flux : l'`outputVariable` -d'un nœud `create_record` contient désormais l'**objet enregistrement créé** (et -non plus l'id nu), donc mettez à jour les références `{var}` qui attendaient un id -en `{var.id}`. - -### 8.0.x - -ObjectOS One et le serveur intégré tournaient sur `@objectstack` **8.0.1**. - -- **MCP via Streamable HTTP** — chaque déploiement peut agir comme un serveur - [Model Context Protocol](https://modelcontextprotocol.io) accessible via le - réseau. Activez-le avec `OS_MCP_SERVER_ENABLED=true` ; l'endpoint est servi sur - `/api/v1/mcp` avec une authentification fail-closed (les requêtes anonymes sont - rejetées). Le plugin a été renommé de `@objectstack/plugin-mcp-server` en - `@objectstack/mcp`. -- **Clés d'API en libre-service** — `POST /api/v1/keys` génère une `sys_api_key` - affichée une seule fois. Les API REST de données et de métadonnées - (`/api/v1/data`, `/api/v1/meta`) authentifient désormais les clés d'API via le - même vérificateur que MCP, en s'exécutant sous les permissions et la sécurité au - niveau des enregistrements du propriétaire de la clé. -- **Règles conditionnelles au niveau des champs** — `visibleWhen`, `readonlyWhen` - et `requiredWhen` sont appliquées côté serveur par ObjectQL, et pas seulement - dans l'UI du formulaire. -- **Filtre de lecture RLS réutilisable** — `security.getReadFilter(object, context)` - expose la portée de lecture de l'accès aux enregistrements ; les datasets - d'analytique, les tableaux de bord et les rapports s'y connectent et échouent en - mode fermé lorsque la portée ne peut pas être appliquée en toute sécurité. -- **Stack hôte autonome** — le runtime fournit un hôte `createStandaloneStack` - mono-locataire ; le wrapper `createObjectOSStack` de 7.x, connecté au cloud et - routé par hostname, a été supprimé. Un déploiement cloud pointe désormais - `OS_ARTIFACT_FILE` vers une URL d'artefact publiée. - -### 5.0 — renommage de `project` → `environment` (publié) - -Le concept de runtime autrefois appelé *Project* a été renommé en -*Environment* partout. Cela a affecté : - -- Drapeaux CLI : `--environment` / `-e` -- Chemins HTTP : `/api/v1/environments/:environmentId/...` -- En-têtes : `X-Environment-Id` -- Variables d'environnement : `OS_ENVIRONMENT_ID` (`OS_PROJECT_ID` conservé comme alias déprécié) -- Colonnes de base de données : `environment_id` -- Schémas JSON : `EnvironmentArtifact` - -## Mise à niveau - -Voir [Mise à niveau et restauration](/docs/operate/upgrade) pour les -étapes mécaniques. Avant le décollage : - -1. Lire l'entrée du CHANGELOG pour chaque version mineure entre votre - version actuelle et la version cible. -2. Exécuter `os diff ` pour faire apparaître - les changements de schéma incompatibles. -3. Exécuter `os doctor` sur la version cible. -4. Démarrer une instance canari avant de déployer sur l'ensemble du parc. -5. Avoir un plan de restauration à la fois pour le tag d'image et la - version d'artefact (ils sont restaurés indépendamment). - -## Signaler des régressions - -Si un correctif ou une version mineure casse quelque chose qui -fonctionnait auparavant, signalez un bogue sur -[github.com/objectstack-ai/objectos/issues](https://github.com/objectstack-ai/objectos/issues) -en indiquant la version depuis / vers laquelle vous avez effectué la mise -à niveau. Nous traitons les régressions comme la catégorie de bogues la -plus prioritaire. diff --git a/content/docs/resources/changelog.ja.mdx b/content/docs/resources/changelog.ja.mdx deleted file mode 100644 index cd1e1fb..0000000 --- a/content/docs/resources/changelog.ja.mdx +++ /dev/null @@ -1,185 +0,0 @@ ---- -title: 変更履歴とバージョニング -description: ObjectOS のバージョン管理方法、リリース間の変更点、サポート対象について。 ---- - -## バージョニングポリシー - -ObjectOS は **[セマンティックバージョニング](https://semver.org/)** に従います: `MAJOR.MINOR.PATCH`。 - -| バージョンの更新 | 意味 | 対応 | -|---|---|---| -| **パッチ** (`10.0.0 → 10.0.1`) | バグ修正、動作の変更なし | そのまま更新でき、アプリの変更は不要 | -| **マイナー** (`10.0 → 10.1`) | 新機能、後方互換あり | そのまま更新でき、必要に応じて新機能を採用 | -| **メジャー** (`9 → 10`) | リリースノートに記載された破壊的変更 | アップグレード前に移行ガイドを必読 | - -すべての `@objectstack/*` パッケージは、同期されたバージョン番号で一緒にリリースされます。これらは個別ではなく、マトリックスとしてテストされます。 - -## 互換性マトリックス - -| コンポーネント | 互換性ルール | -|---|---| -| ObjectOS イメージ ↔ コンパイル済みアーティファクト | 同一のマイナーバージョン。10.2.x のイメージは 10.2.x のアーティファクトを実行します。10.2 のアーティファクトは 10.0 のイメージで利用できない機能を使用している場合があります。 | -| ObjectOS ↔ CLI | 同一のマイナーバージョンを推奨。`npm i -g` の CLI は、自身のバージョンに固定されたスキャフォールドを書き出します。 | -| ObjectOS ↔ データベースドライバー | ドライバーはイメージビルドで固定されます。Postgres ≥ 13 / MongoDB ≥ 5 / Turso(現行いずれか)を確認してください。 | -| Node.js | **20 LTS 以降**。新規デプロイには 22 LTS を推奨。 | - -## サポート期間 - -| ブランチ | ステータス | 期限 | -|---|---|---| -| **10.x**(現行) | 活発に開発中。新機能と修正 | 11.0 リリース後、少なくとも 12 か月 | -| **9.x** | セキュリティ修正のみ | 11.0 リリースで EOL | -| **≤ 8.x** | サポート対象外 | すでに EOL | - -重大なセキュリティ修正は、現行および 1 つ前のメジャーバージョンにバックポートされます。それ以外はすべて `main` に取り込まれます。 - -## リリースノート - -リリース済みの ObjectOS バージョンとその CHANGELOG エントリは、次の場所で公開されています: - -- **npm**: [`@objectstack/runtime`](https://www.npmjs.com/package/@objectstack/runtime) -- **GitHub**: [github.com/objectstack-ai/objectos/releases](https://github.com/objectstack-ai/objectos/releases) -- **ソース CHANGELOG**: [`CHANGELOG.md`](https://github.com/objectstack-ai/objectstack/blob/main/CHANGELOG.md) -- **詳細リリースノート**: [`RELEASE_NOTES.md`](https://github.com/objectstack-ai/objectstack/blob/main/RELEASE_NOTES.md) - -GitHub でリリースを購読すると、通知を受け取れます。 - -## 最近のハイライト - -### 10.x — 現行リリーストレイン - -ObjectOS One とバンドル版サーバーは現在 `@objectstack` **10.2.0** 上で動作します。 -メジャーバージョンの更新にもかかわらず、ランタイムの起動コントラクトは変更ありません。 -`createStandaloneStack` は引き続き同じアーティファクト・環境・データベース設定を受け取り、 -すべての破壊的変更はマルチ組織テナンシー層に集約されているため、**シングルテナントの -ObjectOS デプロイ(デフォルト)は設定変更なしで 9.x からそのまま更新できます**。 -変わった点は次のとおりです: - -- **行レベルの組織スコーピングを独立したプラグインに分離**(10.0、破壊的)— - `organization_id` の自動スタンプ、組織ごとのシード再生、デフォルト組織のブートストラップが、 - `@objectstack/plugin-security` から、オプトインの - [`@objectstack/plugin-org-scoping`](https://www.npmjs.com/package/@objectstack/plugin-org-scoping) - に移されました。シングル組織のデプロイはより軽量になり(クエリごとにワイルドカード RLS を - 剥がす必要がなくなり)、`OS_MULTI_TENANT=true` は引き続き `plugin-security` の前にプラグインを - 自動登録するため、CLI で駆動されるプロジェクトはコード変更不要です。ADR-0002 に従い、 - *テナント*は物理的な分離(1 つの Environment = 1 つのデータベース)であり、 - `organization_id` は 1 つの DB 内での*論理的な*スコーピングなので、独自のプラグインを持つに値します。 -- **自動的な個人ワークスペースを廃止**(10.0、破壊的)— `plugin-security` は、 - 新規ユーザーごとに「`'s Workspace`」組織を作成しなくなりました。ユーザーは招待を受諾するか、 - 最初の組織を明示的に作成します(Slack / Linear / GitHub Orgs のモデル)。 - 最初に登録されたユーザー(プラットフォーム管理者に自動昇格)は、マルチテナントモードでは - 引き続き単一の `Default Organization` を取得し、セッションが RLS を解決できるようにします。 - シングルテナントのデプロイでは組織は作成されません。 -- **`record` フォームフィールドタイプ**(ADR-0014)— `Record` プロパティ - (オブジェクトの `fields` マップなど)は、生の JSON として漏れ出るのではなく、Studio で - ファーストクラスのフォームフィールドとして編集できるようになりました。また、オブジェクトの - プレビューペインは実際の `ObjectGrid` レンダラーをマウントします。プレビューしたものが - そのまま出荷されます。 -- **`IEmbedder` によるプラガブルな埋め込み** — 新しい埋め込みプロトコルと - [`@objectstack/embedder-openai`](https://www.npmjs.com/package/@objectstack/embedder-openai)。 - ナレッジ / RAG アダプターは `IEmbedder` を利用するようになり、`plugin-` プレフィックスを - 落とすように名称変更されました。 -- **Public Forms** — `/f/:slug` で提供される匿名の Web-to-Lead / Web-to-Case フォーム、 - 統合された FormPage(公開 `/f/:slug` + 内部 `/forms/:name`)、`type: 'form'` のアクションバリアント、 - `ObjectSchema` の `defaultDetailForm`。 -- **クラウド ID の分離** — `os cloud login` は `os login` とは別になり、 - クラウドコントロールプレーンはプライベートリポジトリに移され(より軽量な OSS ランタイム)、 - `objectstack init` は再びビルドして起動するプロジェクトをスキャフォールドします。 - -### 9.x - -9.x トレインは、10.0 への切り替え前は `@objectstack` **9.0 – 9.11** 上で動作していました。 -ランタイムの起動コントラクトは 8.0 から変更ありません。`createStandaloneStack` -は引き続き同じアーティファクト・環境・データベース設定を受け取るため、8.0 のデプロイは -設定変更なしでそのまま更新できます。変わったのはオーサリング向けの表面です: - -- **分析データセットが唯一のオーサリング表面に**(9.0、破壊的)— - ダッシュボードのウィジェット、レポート、リストチャートは、セマンティックな `dataset` - (`defineDataset(...)`)をバインドし、ディメンション/メジャーを**名前で**選択するようになりました。 - 従来のインラインクエリフィールド(ウィジェットの `object`/`valueField`/`aggregate`、 - レポートの `objectName`/`columns`/`groupingsDown`、リストチャートの - `xAxisField`/`yAxisFields`)は削除されました。移行方法: インラインクエリを - `defineDataset` に移し、名前で参照します。`ChartTypeSchema` も、ベースとしてしか - 描画されなかった 8 つのバリアントタイプを廃止しました(`stacked-bar`→`bar`、 - `spline`→`line`、`bubble`→`scatter`、…)。 -- **ビルド時の検証が厳格化**(9.6–9.7)— `os compile` は、裸のフィールド参照 - (`record.amount` ではなく `amount`)、未知の CEL 関数、誤ったフロー値の補間構文に対して、 - それぞれ did-you-mean ヒント付きで**失敗する**ようになりました。以前は「ビルドは通るが - 暗黙的に誤っていた」スタックが、明示的に失敗するようになります。アップグレード後に - `os compile` を再実行し、指摘された箇所を修正してください。 -- **数値フィールドの数式が混合演算を計算**(9.7)— `record.amount / 100` や - `record.price * 2` が、暗黙的に `null` を返すのではなく評価されるようになりました。 - `/ 100.0` という浮動小数点リテラルの回避策はもう不要です。 -- **オブジェクト単位の REST ゲーティングを強制適用**(ADR-0049)— オブジェクトの - `apiEnabled: false` は REST 表面からそのオブジェクトを除外し、`apiMethods` - ホワイトリストは到達可能な操作を制限します。以前はパースされるだけで強制されていませんでした。 -- **パッケージドキュメントをメタデータ化 + `book` ナビゲーション**(9.3–9.6)— - `src/docs/*.md` は `doc` メタデータとして登録されます。`book` 要素(ADR-0046)は - 派生メンバーシップのナビゲーション軸を宣言し、対象者ゲーティング付きで - `GET /api/v1/meta/book/:name/tree` から提供されます。 -- **`os package install`**(9.3)— カタログ ID またはインラインのエアギャップ用アーティファクトから、 - 稼働中のランタイムにパッケージをインストールします。`--email` / `--password` で認証します。 -- **承認(Approvals)**(9.3)— 差し戻し再提出(`maxRevisions`、デフォルト 3)、 - ジョブベースの SLA 自動エスカレーション、一覧の検索/ページネーション、 - セッションレスのバイリンガル承認/却下確認リンク。 -- **インバウンド Webhook のフロートリガー**(9.3)— `type: 'api'` のフローは、 - HMAC 検証付きの `POST /api/v1/automation/hooks/:flowName/:hookId` エンドポイントをマウントし、 - 冪等かつキューベースの取り込みを行います。 -- **通知の保持期間がデフォルトで有効に**(9.5)— 通知履歴は **90 日**で自動的に剪定されます。 - 履歴を永久に保持するには、メッセージングの `retentionDays: 0` を設定します。 -- **CLI が AI プロバイダーの SDK をバンドル**(9.0)— OpenAI 互換プロバイダー - (DeepSeek、DashScope、SiliconFlow、OpenRouter、Cloudflare)が、 - グローバルインストールした CLI でそのまま動作します。 - -フロー作成での動作変更として 1 点注意: `create_record` ノードの `outputVariable` は、 -裸の ID ではなく**作成されたレコードオブジェクト**を保持するようになりました。ID を期待していた -`{var}` 参照は `{var.id}` に更新してください。 - -### 8.0.x - -ObjectOS One とバンドル版サーバーは `@objectstack` **8.0.1** 上で動作していました。 - -- **MCP over Streamable HTTP** — すべてのデプロイがネットワーク到達可能な - [Model Context Protocol](https://modelcontextprotocol.io) サーバーとして機能できます。 - `OS_MCP_SERVER_ENABLED=true` で有効化すると、エンドポイントは `/api/v1/mcp` で提供され、 - fail-closed 認証(匿名リクエストは拒否)が適用されます。プラグインは - `@objectstack/plugin-mcp-server` から `@objectstack/mcp` に名称変更されました。 -- **セルフサービス API キー** — `POST /api/v1/keys` は一度だけ表示される - `sys_api_key` を発行します。REST のデータ/メタデータ API(`/api/v1/data`、 - `/api/v1/meta`)は MCP と同じ検証器で API キーを認証し、キー所有者の権限と - レコードレベルセキュリティの下で実行されます。 -- **フィールド単位の条件ルール** — `visibleWhen`、`readonlyWhen`、`requiredWhen` は - フォーム UI だけでなく、ObjectQL によってサーバー側で強制されます。 -- **再利用可能な RLS 読み取りフィルター** — `security.getReadFilter(object, context)` が - レコードアクセスの読み取り範囲を公開します。分析データセット、ダッシュボード、レポートは - これにブリッジし、範囲を安全に適用できない場合は fail closed になります。 -- **スタンドアロン host スタック** — ランタイムはシングルテナントの - `createStandaloneStack` host を提供します。7.x のクラウド接続・ホスト名ルーティング型の - `createObjectOSStack` ラッパーは削除されました。クラウドデプロイでは - `OS_ARTIFACT_FILE` を公開済みの artifact URL に向けます。 - -### 5.0 — `project` → `environment` への名称変更(リリース済み) - -これまで *Project* と呼ばれていたランタイムの概念が、全体を通して *Environment* に名称変更されました。影響範囲: - -- CLI フラグ: `--environment` / `-e` -- HTTP パス: `/api/v1/environments/:environmentId/...` -- ヘッダー: `X-Environment-Id` -- 環境変数: `OS_ENVIRONMENT_ID`(`OS_PROJECT_ID` は非推奨のエイリアスとして維持) -- DB カラム: `environment_id` -- JSON スキーマ: `EnvironmentArtifact` - -## アップグレード - -具体的な手順については [アップグレードとロールバック](/docs/operate/upgrade) を参照してください。事前チェック: - -1. 現行バージョンとターゲットバージョンの間にあるすべてのマイナーについて、CHANGELOG エントリを読みます。 -2. `os diff ` を実行して、破壊的なスキーマ変更を洗い出します。 -3. ターゲットバージョンに対して `os doctor` を実行します。 -4. フリート全体に展開する前に、カナリアインスタンスを 1 台立ち上げます。 -5. イメージタグとアーティファクトバージョンの両方についてロールバック計画を用意します(これらは独立してロールします)。 - -## リグレッションの報告 - -パッチまたはマイナーによって、以前は動作していたものが壊れた場合は、[github.com/objectstack-ai/objectos/issues](https://github.com/objectstack-ai/objectos/issues) で、アップグレード元/先のバージョンを添えてバグを報告してください。リグレッションは最優先で対応すべきバグとして扱います。 diff --git a/content/docs/resources/changelog.ko.mdx b/content/docs/resources/changelog.ko.mdx deleted file mode 100644 index dfc66f2..0000000 --- a/content/docs/resources/changelog.ko.mdx +++ /dev/null @@ -1,194 +0,0 @@ ---- -title: 변경 로그 및 버전 관리 -description: ObjectOS의 버전 관리 방식, 릴리스 간 변경 사항, 그리고 지원 범위. ---- - -## 버전 관리 정책 - -ObjectOS는 **[유의적 버전(Semantic Versioning)](https://semver.org/)**을 따릅니다: `MAJOR.MINOR.PATCH`. - -| 버전 증가 | 의미 | 해야 할 일 | -|---|---|---| -| **패치** (`10.0.0 → 10.0.1`) | 버그 수정, 동작 변경 없음 | 그대로 업데이트, 앱 변경 불필요 | -| **마이너** (`10.0 → 10.1`) | 새 기능, 하위 호환 | 그대로 업데이트, 필요 시 새 기능 도입 | -| **메이저** (`9 → 10`) | 릴리스 노트에 문서화된 호환성 깨짐 변경 | 업그레이드 전에 마이그레이션 가이드를 읽으세요 | - -모든 `@objectstack/*` 패키지는 동기화된 버전 번호로 함께 릴리스됩니다 — -개별적으로가 아니라 매트릭스로 테스트됩니다. - -## 호환성 매트릭스 - -| 구성 요소 | 호환성 규칙 | -|---|---| -| ObjectOS 이미지 ↔ 컴파일된 아티팩트 | 동일한 마이너 버전. 10.2.x 이미지는 10.2.x 아티팩트를 실행하며, 10.2 아티팩트는 10.0 이미지에서 사용할 수 없는 기능을 사용할 수 있습니다. | -| ObjectOS ↔ CLI | 동일한 마이너 버전 권장. `npm i -g`로 설치한 CLI는 자체 버전에 고정된 스캐폴드를 작성합니다. | -| ObjectOS ↔ 데이터베이스 드라이버 | 드라이버는 이미지 빌드에 고정됨; Postgres ≥ 13 / MongoDB ≥ 5 / Turso(현재 버전) 확인. | -| Node.js | **20 LTS 이상**. 새 배포에는 22 LTS 권장. | - -## 지원 기간 - -| 브랜치 | 상태 | 종료 시점 | -|---|---|---| -| **10.x** (현재) | 활발한 개발; 새 기능 및 수정 | 11.0 출시 후 최소 12개월 | -| **9.x** | 보안 수정만 | 11.0 릴리스 시 EOL | -| **≤ 8.x** | 지원 종료 | 이미 EOL | - -중대한 보안 수정은 현재 및 이전 메이저 버전에 백포트됩니다. 그 외 모든 것은 -`main`에 반영됩니다. - -## 릴리스 노트 - -릴리스된 ObjectOS 버전과 해당 CHANGELOG 항목은 다음에서 게시됩니다: - -- **npm**: [`@objectstack/runtime`](https://www.npmjs.com/package/@objectstack/runtime) -- **GitHub**: [github.com/objectstack-ai/objectos/releases](https://github.com/objectstack-ai/objectos/releases) -- **소스 CHANGELOG**: [`CHANGELOG.md`](https://github.com/objectstack-ai/objectstack/blob/main/CHANGELOG.md) -- **상세 릴리스 노트**: [`RELEASE_NOTES.md`](https://github.com/objectstack-ai/objectstack/blob/main/RELEASE_NOTES.md) - -알림을 받으려면 GitHub에서 릴리스를 구독하세요. - -## 주요 변경 사항 - -### 10.x — 현재 릴리스 트레인 - -ObjectOS One과 번들 서버는 이제 `@objectstack` **10.2.0** 기반으로 동작합니다. -메이저 버전 증가에도 불구하고 런타임 부트 계약은 변경되지 않았습니다 — -`createStandaloneStack`은 여전히 동일한 아티팩트, 환경, 데이터베이스 설정을 -받으며, 모든 호환성 깨짐 변경은 멀티 조직 테넌시 계층에서 발생하므로 **단일 -테넌트 ObjectOS 배포(기본값)는 구성 변경 없이 9.x에서 그대로 업데이트됩니다**. -바뀐 것은 다음과 같습니다: - -- **행 단위 조직 스코핑이 자체 플러그인으로 분리되었습니다** (10.0, 호환성 깨짐) — - `organization_id` 자동 스탬프, 조직별 시드 재생, 기본 조직 부트스트랩이 - `@objectstack/plugin-security`에서 빠져나와 옵트인 방식의 - [`@objectstack/plugin-org-scoping`](https://www.npmjs.com/package/@objectstack/plugin-org-scoping)으로 - 이동했습니다. 단일 조직 배포는 더 가벼워지며(모든 쿼리에서 제거할 와일드카드 RLS가 - 없음), `OS_MULTI_TENANT=true`는 여전히 `plugin-security`보다 먼저 플러그인을 자동 - 등록하므로 CLI로 구동되는 프로젝트는 코드 변경이 필요 없습니다. ADR-0002에 따르면 - *테넌트*는 물리적 격리(하나의 Environment = 하나의 데이터베이스)이고, - `organization_id`는 하나의 DB 내에서의 *논리적* 스코핑이므로 자체 플러그인을 - 가질 자격이 있습니다. -- **자동 개인 워크스페이스가 더 이상 없습니다** (10.0, 호환성 깨짐) — - `plugin-security`는 더 이상 모든 신규 사용자에 대해 "`'s Workspace`" 조직을 - 생성하지 않습니다. 사용자는 이제 초대를 수락하거나 명시적으로 첫 조직을 생성합니다 - (Slack / Linear / GitHub-Orgs 모델). 첫 등록 사용자 — 플랫폼 관리자로 자동 승격됨 — - 는 멀티 테넌트 모드에서 세션이 RLS를 해석할 수 있도록 여전히 단일 - `Default Organization`을 받습니다. 단일 테넌트 배포는 조직을 생성하지 않습니다. -- **`record` 폼 필드 타입** (ADR-0014) — `Record` 속성(예: 객체의 `fields` - 맵)이 이제 Studio에서 원시 JSON으로 새어 나가는 대신 일급 폼 필드로 편집 가능하며, - 객체 미리보기 창은 실제 `ObjectGrid` 렌더러를 마운트합니다 — 미리 보는 것이 곧 - 출시되는 것입니다. -- **`IEmbedder`를 통한 플러그형 임베딩** — 새로운 임베더 프로토콜과 - [`@objectstack/embedder-openai`](https://www.npmjs.com/package/@objectstack/embedder-openai); - 지식 / RAG 어댑터는 이제 `IEmbedder`를 사용하며 `plugin-` 접두사를 떼도록 - 이름이 변경되었습니다. -- **Public Forms** — `/f/:slug`에서 제공되는 익명 Web-to-Lead / Web-to-Case 폼, - 통합 FormPage(공개 `/f/:slug` + 내부 `/forms/:name`), `type: 'form'` 액션 변형, - 그리고 `ObjectSchema`의 `defaultDetailForm`. -- **클라우드 아이덴티티 분리** — `os cloud login`이 이제 `os login`과 분리되었고, - 클라우드 컨트롤 플레인은 비공개 저장소로 이동했으며(더 가벼운 OSS 런타임), - `objectstack init`은 다시 빌드되고 부팅되는 프로젝트를 스캐폴드합니다. - -### 9.x - -9.x 트레인은 10.0 전환 전까지 `@objectstack` **9.0 – 9.11** 기반으로 동작했습니다. -런타임 부트 계약은 8.0과 동일합니다 — `createStandaloneStack`은 여전히 동일한 -아티팩트, 환경, 데이터베이스 설정을 받으므로 8.0 배포는 구성 변경 없이 그대로 -업데이트됩니다. 바뀐 것은 작성자(author)가 마주하는 표면입니다: - -- **분석 데이터셋이 유일한 작성자 표면이 되었습니다** (9.0, 호환성 깨짐) — - 대시보드 위젯, 보고서, 리스트 차트는 이제 의미 기반 `dataset` - (`defineDataset(...)`)에 바인딩하고 차원/측정값을 **이름으로** 선택합니다. 기존의 - 인라인 쿼리 필드(위젯의 `object`/`valueField`/`aggregate`, 보고서의 - `objectName`/`columns`/`groupingsDown`, 리스트 차트의 `xAxisField`/`yAxisFields`)는 - 제거되었습니다. 마이그레이션: 인라인 쿼리를 `defineDataset`으로 옮기고 이름으로 - 참조하세요. `ChartTypeSchema`도 기본형으로만 렌더링되던 8개의 변형 타입을 - 삭제했습니다(`stacked-bar`→`bar`, `spline`→`line`, `bubble`→`scatter`, …). -- **더 엄격한 빌드 타임 검증** (9.6–9.7) — `os compile`은 이제 단독 필드 참조 - (`record.amount` 대신 `amount`), 알 수 없는 CEL 함수, 잘못된 플로우 값 보간 구문에 - 대해 각각 did-you-mean 힌트와 함께 **실패**합니다. 이전에는 "빌드는 되지만 조용히 - 잘못되던" 스택이 이제 큰 소리로 실패합니다 — 업그레이드 후 `os compile`을 다시 - 실행하고 플래그된 항목을 수정하세요. -- **숫자 필드 수식이 혼합 산술을 계산합니다** (9.7) — `record.amount / 100`과 - `record.price * 2`가 이제 조용히 `null`을 내놓는 대신 평가됩니다. `/ 100.0` 부동 - 소수점 리터럴 우회법은 더 이상 필요하지 않습니다. -- **객체 단위 REST 게이팅, 이제 강제됨** (ADR-0049) — 객체의 `apiEnabled: false`는 - 해당 객체를 REST 표면에서 제거하고, `apiMethods` 화이트리스트는 어떤 작업에 - 도달할 수 있는지를 제한합니다. 이전에는 파싱은 되었지만 강제되지 않았습니다. -- **패키지 문서를 메타데이터로 + `book` 내비게이션** (9.3–9.6) — `src/docs/*.md`가 - `doc` 메타데이터로 등록됩니다. `book` 요소(ADR-0046)는 파생 멤버십 내비게이션 - 척추를 선언하며, 청중 게이팅과 함께 `GET /api/v1/meta/book/:name/tree`에서 - 제공됩니다. -- **`os package install`** (9.3) — 카탈로그 id 또는 인라인 에어갭 아티팩트로부터 - 실행 중인 런타임에 패키지를 설치하며, `--email` / `--password`로 인증합니다. -- **승인(Approvals)** (9.3) — 수정 요청 반려(`maxRevisions`, 기본값 3), 잡 기반 SLA - 자동 에스컬레이션, 리스트 검색/페이지네이션, 세션 없는 이중 언어 승인/거부 확인 - 링크. -- **인바운드 웹훅 플로우 트리거** (9.3) — `type: 'api'` 플로우는 HMAC 검증된 - `POST /api/v1/automation/hooks/:flowName/:hookId` 엔드포인트를 멱등적이고 큐 - 기반인 수집과 함께 마운트합니다. -- **알림 보존 기본값 켜짐** (9.5) — 알림 기록이 **90일**에 자동으로 정리됩니다. - 기록을 영구 보관하려면 메시징 `retentionDays: 0`을 설정하세요. -- **CLI가 AI 제공자 SDK를 번들합니다** (9.0) — OpenAI 호환 제공자(DeepSeek, - DashScope, SiliconFlow, OpenRouter, Cloudflare)가 전역 설치된 CLI에서 별도 설정 - 없이 동작합니다. - -주목할 플로우 작성 동작 변경 하나: `create_record` 노드의 `outputVariable`는 이제 -(단순 id가 아니라) **생성된 레코드 객체**를 담으므로, id를 기대하던 `{var}` 참조를 -`{var.id}`로 업데이트하세요. - -### 8.0.x - -ObjectOS One과 번들 서버는 `@objectstack` **8.0.1** 기반으로 동작했습니다. - -- **MCP over Streamable HTTP** — 모든 배포가 네트워크로 접근 가능한 - [Model Context Protocol](https://modelcontextprotocol.io) 서버로 동작할 수 있습니다. - `OS_MCP_SERVER_ENABLED=true`로 활성화하면 엔드포인트가 `/api/v1/mcp`에서 제공되며 - fail-closed 인증(익명 요청 거부)이 적용됩니다. 플러그인은 - `@objectstack/plugin-mcp-server`에서 `@objectstack/mcp`로 이름이 변경되었습니다. -- **셀프 서비스 API 키** — `POST /api/v1/keys`는 한 번만 표시되는 `sys_api_key`를 - 발급합니다. REST 데이터 및 메타데이터 API(`/api/v1/data`, `/api/v1/meta`)는 이제 - MCP와 동일한 검증기로 API 키를 인증하며, 키 소유자의 권한과 레코드 수준 보안 아래에서 - 실행됩니다. -- **필드 단위 조건 규칙** — `visibleWhen`, `readonlyWhen`, `requiredWhen`이 폼 UI뿐 - 아니라 ObjectQL에 의해 서버 측에서 강제됩니다. -- **재사용 가능한 RLS 읽기 필터** — `security.getReadFilter(object, context)`가 레코드 - 접근의 읽기 범위를 노출합니다. 분석 데이터셋, 대시보드, 보고서가 여기에 브리지되며 - 범위를 안전하게 적용할 수 없으면 fail closed 됩니다. -- **독립형 host 스택** — 런타임은 단일 테넌트 `createStandaloneStack` host를 - 제공합니다. 7.x의 클라우드 연결·호스트명 라우팅 방식 `createObjectOSStack` 래퍼는 - 제거되었습니다. 클라우드 배포는 이제 `OS_ARTIFACT_FILE`을 게시된 artifact URL로 - 지정합니다. - -### 5.0 — `project` → `environment` 이름 변경 (출시됨) - -이전에 *Project*라고 불리던 런타임 개념이 전반에 걸쳐 *Environment*로 -이름이 변경되었습니다. 영향 범위: - -- CLI 플래그: `--environment` / `-e` -- HTTP 경로: `/api/v1/environments/:environmentId/...` -- 헤더: `X-Environment-Id` -- 환경 변수: `OS_ENVIRONMENT_ID` (`OS_PROJECT_ID`는 사용 중단된 별칭으로 유지됨) -- DB 컬럼: `environment_id` -- JSON 스키마: `EnvironmentArtifact` - -## 업그레이드 - -실제 작업 단계는 [업그레이드 및 롤백](/docs/operate/upgrade)을 참고하세요. -사전 점검: - -1. 현재 버전과 대상 버전 사이의 모든 마이너에 대한 CHANGELOG 항목을 - 읽으세요. -2. `os diff `를 실행하여 호환성을 깨는 스키마 - 변경을 드러내세요. -3. 대상 버전에 대해 `os doctor`를 실행하세요. -4. 전체 플릿에 적용하기 전에 카나리 인스턴스 하나를 먼저 띄우세요. -5. 이미지 태그와 아티팩트 버전 모두에 대한 롤백 계획을 마련하세요(둘은 - 독립적으로 롤백됩니다). - -## 회귀 보고 - -패치 또는 마이너 버전이 이전에 정상 작동하던 것을 망가뜨린 경우, -업그레이드 전/후 버전과 함께 -[github.com/objectstack-ai/objectos/issues](https://github.com/objectstack-ai/objectos/issues)에 -버그를 등록하세요. 회귀는 가장 높은 우선순위의 버그로 처리합니다. diff --git a/content/docs/resources/changelog.mdx b/content/docs/resources/changelog.mdx index 2c6b381..148c6be 100644 --- a/content/docs/resources/changelog.mdx +++ b/content/docs/resources/changelog.mdx @@ -328,8 +328,10 @@ ObjectOS One and the bundled server shipped on `@objectstack` **8.0.1**. reports bridge to it and fail closed when the scope cannot be applied. - **Standalone host stack** — the runtime ships a single-tenant `createStandaloneStack` host; the 7.x cloud-connected, hostname-routed - `createObjectOSStack` wrapper was removed. A cloud deployment now points - `OS_ARTIFACT_FILE` at a published artifact URL. + `createObjectOSStack` wrapper was removed. A deployment that runs a + separately published app names that artifact by **URL** from then on. For the + variable that does this today, and the retired spellings that do not, see + [Environment Variables](/docs/reference/environment-variables#retired-names). ### 5.0 — `project` → `environment` rename (shipped) @@ -339,7 +341,8 @@ throughout. Affected: - CLI flags: `--environment` / `-e` - HTTP paths: `/api/v1/environments/:environmentId/...` - Headers: `X-Environment-Id` -- Env vars: `OS_ENVIRONMENT_ID` (`OS_PROJECT_ID` kept as a deprecated alias) +- Env vars: `OS_ENVIRONMENT_ID` (`OS_PROJECT_ID` was kept as a deprecated + alias at the time; it is no longer read) - DB columns: `environment_id` - JSON schemas: `EnvironmentArtifact` diff --git a/content/docs/resources/changelog.zh-Hans.mdx b/content/docs/resources/changelog.zh-Hans.mdx deleted file mode 100644 index 26f4c5a..0000000 --- a/content/docs/resources/changelog.zh-Hans.mdx +++ /dev/null @@ -1,323 +0,0 @@ ---- -title: 变更日志与版本策略 -description: ObjectOS 的版本规则、各版本间的变化及支持范围。 ---- - -## 版本策略 - -ObjectOS 遵循 **[语义化版本](https://semver.org/)**：`MAJOR.MINOR.PATCH`。 - -| 版本号变化 | 含义 | 应对方式 | -|---|---|---| -| **Patch**（`14.7.0 → 14.7.1`） | 修 bug，不改变行为 | 直接升级，无需改动应用 | -| **Minor**（`14.6 → 14.7`） | 新增功能，向后兼容 | 直接升级，可选采用新功能 | -| **Major**（`13 → 14`） | 破坏性变更，发版说明会列出 | 升级前阅读迁移指南 | - -所有 `@objectstack/*` 包按同步的版本号一起发布 —— 作为矩阵一同测试， -而不是各自独立。 - -## 兼容性矩阵 - -| 组件 | 兼容性规则 | -|---|---| -| ObjectOS 镜像 ↔ 编译产物 | 同一 minor 版本。14.7.x 镜像运行 14.7.x 产物;14.7 产物可能使用 14.0 镜像不具备的功能。协议握手（`PROTOCOL_VERSION`，12.0+）会在安装时拒绝不兼容的软件包。 | -| ObjectOS ↔ CLI | 建议使用同一 minor 版本。`npm i -g` 安装的 CLI 生成的脚手架会固定为其自身版本。 | -| ObjectOS ↔ 数据库驱动 | 驱动版本由镜像构建固定;请确认 Postgres ≥ 13 / MongoDB ≥ 5 / Turso（当前版本）。 | -| Node.js | **20 LTS 或更新**。新部署推荐 22 LTS。 | - -## 支持窗口 - -| 分支 | 状态 | 截止 | -|---|---|---| -| **14.x**（当前） | 活跃开发;新功能与修复 | 至少到 15.0 发布后 12 个月 | -| **13.x** | 仅安全修复 | 15.0 发布时 EOL | -| **≤ 12.x** | 不再支持 | 已 EOL | - -关键安全修复会反向移植到当前 major 与上一个 major;其他变更只进 -`main`。 - -## 发版说明 - -发布的 ObjectOS 版本与其 CHANGELOG 在以下位置发布： - -- **npm**：[`@objectstack/runtime`](https://www.npmjs.com/package/@objectstack/runtime) -- **GitHub**：[github.com/objectstack-ai/objectos/releases](https://github.com/objectstack-ai/objectos/releases) -- **源码 CHANGELOG**：[`CHANGELOG.md`](https://github.com/objectstack-ai/objectstack/blob/main/CHANGELOG.md) -- **长文版发版说明**：[`RELEASE_NOTES.md`](https://github.com/objectstack-ai/objectstack/blob/main/RELEASE_NOTES.md) - -在 GitHub 上订阅 Releases 即可收到通知。 - -## 近期亮点 - -### 16.0 - -`@objectstack` **16.0.0** 收敛了开发者面，并让已声明的元数据变得诚实：调用者组织只有一个受祝福的名字、审批获得真正的多审批人治理、时间相对自动化真正会触发，以及一次平台级清理，把被静默忽略的元数据在创作时就变成响亮的错误。完整说明见 -[docs.objectstack.ai/docs/releases](https://docs.objectstack.ai/docs/releases)。 -16.0 的变动： - -- **hook/action `ctx` 移除 `tenantId` 别名**（16.0，破坏性）—— 在所有 - `*.hook.ts` / `*.action.ts` 代码体中，改用 `ctx.user.organizationId` / - `ctx.session.organizationId` 读取调用者组织（值不变；system 写入时 - `ctx.user` 为 `undefined`）。驱动层的租户轴（`ExecutionContext.tenantId`） - 是另一个概念，刻意保持不动。 -- **审批：法定人数、会签，以及元数据驱动的收件箱**——审批步骤支持 - M-of-N 法定人数（`minApprovals`）和每组一人的会签，基于开启时刻的快照 - 统计并支持 OOO 替补；单次拒绝仍是一票否决，阈值会自动收紧，错误配置 - 永远不会造成死锁。决策可附带文件附件，进度（"2 of 3 · finance - pending"）由服务端计算，approve / reject / reassign / send-back / - request-info / remind / recall / resubmit 都作为 `sys_approval_request` - 上声明的 `type:'api'` action —— Console 通过通用 action 运行时渲染它们， - 而不是手写按钮。 -- **时间相对自动化**——流程开始节点可以声明 `timeRelative` - （`offsetDays: [60, 30, 7]` 或 `withinDays`）；每日扫描对每条匹配记录 - 启动一次流程，"合同到期前 60 天提醒我"终于开箱即用——不再依赖只有 - 恰好在正确的那天有人编辑记录才会触发的日期相等条件。 -- **带过滤的汇总字段**——`summaryOperations.filter` 让父级合计只聚合 - 匹配的子行，并在子行进出谓词范围时重新聚合。 -- **严格的仪表盘 widget**（16.0，破坏性）——`DashboardWidgetSchema` 改为 - `.strict()`：未声明的键（拼写错误或已移除的内联分析键）会成为解析 - 错误，指名该键并指向数据集形态（`dataset` + `dimensions` + `values`）， - 而不是静默渲染出一片空白。 -- **MCP：stdio 获得身份，Agent 获得校验器**——stdio 自动启动改由独立的 - `OS_MCP_STDIO_ENABLED` 开关控制（默认关闭），并要求 - `OS_MCP_STDIO_API_KEY=osk_...` 身份主体，fail-closed，通过与 HTTP 相同 - 的授权链解析（RLS/FLS/租户隔离全部生效；没有 `system` 旁路）。新增 - `validate_expression` 工具，让 Agent 在保存前对照真实对象 schema 校验 - 公式。 -- **enforce-or-remove 清理**（16.0，破坏性）——声明了却从不强制执行的 - 元数据现在会大声报错：无效的字段/对象/agent 属性被移除或以带指引的 - tombstone 报错，hook 事件从 18 收敛到 8，验证规则移除从不求值的 - `'delete'` 事件，webhook 的 `undelete` / `api` 触发器被移除，未知的 - `requires` 能力 token 在创作时即被拒绝（`aiStudio` / `aiSeat` 别名已 - 移除——使用 kebab-case 的 `ai-studio` / `ai-seat`）。 -- **引擎自有的系统行通过通用数据 API 只读**（ADR-0103）——作业、通知、 - 审批运行时行、共享行、审计日志、密钥等被锁定为 `get`/`list`， - fail-closed 守卫会拒绝经 `/data` 的用户上下文写入。确实需要接受用户 - 写入的第三方 `system` 对象必须声明 `userActions`。 -- **日期逻辑不再说谎**——`record.due_date == today()` 现在能匹配了 - （时间相等比较会被重写以强制转换字段操作数）；而公式中的日期*算术* - （`end - start + 1`、`today() + 30`）改为构建期错误，并指向 - `daysBetween` / `daysFromNow` / `addDays` / `addMonths` ——这些表达式 - 在运行时本来就总是得到 `null`。 -- **批量用户导入默认 `passwordPolicy: 'auto'`**——具有可送达通道的行 - （真实邮箱 + 已接通的邮件服务，或手机号 + 短信邀请通道）会被邀请； - 只有无法触达的行才得到一次性临时密码（`must_change_password`）。 - 想要旧的仅建身份行为，请显式传入 `passwordPolicy: 'none'`；每行结果 - 在 `rows[].delivery` 上。 - -### 14.x - -ObjectOS One 与捆绑的 server 基于 `@objectstack` **14.7.0** 发布。运行时的启动 -契约并未变化 —— `createStandaloneStack` 仍然接收同样的 artifact、环境与数据库 -设置 —— 但 13.0 与 14.0 均在授权词汇上有破坏性变更，因此**从 ≤ 12.x 升级前请 -先审查权限元数据**。完整说明见 -[docs.objectstack.ai/docs/releases](https://docs.objectstack.ai/docs/releases)。 -14.x 的变动： - -- **ADR-0090 词汇收敛完成**（14.0，破坏性）—— `book.audience` 改用 - `{ permissionSet }` 门控（原为 `{ profile }`），`PortalSchema.profiles` → - `positions`，`RLSUserContextSchema.role` → `positions`（字符串数组）， - `sys_record_share.recipient_type: 'role'` → `'position'`。 -- **对象能力开关强制执行**（14.0，准破坏性）—— `enable.*` 开关从"解析但不生效" - 变为真实闸门。`activities` 与 `feeds` 为默认开启、可显式关闭（`feeds: false` - 会以 403 `FEEDS_DISABLED` 拒绝评论）；`trackHistory` 控制 History 选项卡； - `files` 需显式开启（否则 403 `FILES_DISABLED`）。 -- **成员基线移除删除权**（14.2，破坏性）—— `member_default` 不再授予记录删除； - 需按对象通过岗位分发的权限集重新授予。 -- **管理员用户管理与手机号认证**（14.3）—— 直接创建用户 - （`POST /api/v1/auth/admin/create-user`，一次性密码 + 强制轮换）、批量导入 - （行/CSV/XLSX、dry-run、upsert）、通过 `@objectstack/plugin-sms` 的可选手机号 - 登录与短信 OTP（阿里云 / Twilio），以及 `sms` 通知通道。 -- **数据生命周期契约**（14.4，ADR-0057）—— 对象声明 `lifecycle` - （class、retention、rotation、archive）；默认开启的 LifecycleService 负责 - 回收、轮换与归档平台数据（`sys_activity` 14 天，`sys_audit_log` 热存 90 天）。 - 可用 `OS_LIFECYCLE_DISABLED=1` 关闭，通过 `lifecycle.retention_overrides` - 调整。14.5 移除了插件级 `retentionDays` / `retentionSweepMs` 选项 - （`JobRunRetention`、`NotificationRetention`），改由生命周期声明接管，并将 - 生命周期类系统数据拆分到专用 telemetry 数据源（`OS_TELEMETRY_DB`）； - `os db clean` 可回收 SQLite 空间。 -- **带生效期的授权与委托**（14.4，ADR-0091）—— 岗位与权限集分配支持 - `valid_from` / `valid_until` 时间窗口（失败即关闭，无需后台任务）； - `delegatable` 岗位允许持有者在有限窗口内自助委托（≤ 30 天、必须填写原因、 - 管理范围永不可委托）。 -- **MCP 权限上限**（14.5，ADR-0090 D10）—— 通过 OAuth 接入的代理在 - `effective_permission = scope_ceiling ∩ user_grants` 下运行 - （`data:read` / `data:write` / `actions:execute`），失败即关闭。 -- **安全修复**（14.4–14.5）—— 字段权限键必须带对象限定（裸键会静默匹配不到 - 任何字段；现在由校验规则拒绝并支持自动修复）；settings 与共享链接路由不再 - 信任可伪造的 `x-user-id` 类请求头；分析查询按调用者的读取过滤器限定范围。 - -### 13.x —— 权限模型 v2 - -`@objectstack` **13.0** 重构了授权模型（ADR-0090）。破坏性变更： - -- **角色与简档合并为岗位** —— `sys_role*` 表、`RoleSchema` / `defineRole`、 - 元数据类型 `role` / `profile`、`ExecutionContext.roles[]` 均已移除；岗位是 - 扁平的，层级迁移到业务单元树。共享接收者重命名（`role` → `position`、 - `role_and_subordinates` → `unit_and_subordinates`）。 -- **自定义对象默认私有** —— 带所有者但未显式声明 `sharingModel` 的对象现在 - 默认私有；OWD 别名 `read` / `read_write` / `full` 已移除。声明 - `sharingModel: 'public_read_write'` 可恢复原行为。 -- **RBAC 关联表写入受门控** —— 写入 `sys_user_position`、 - `sys_position_permission_set`、`sys_user_permission_set`、`sys_permission_set` - 需要租户管理员或委托管理范围。 - -新增能力：`everyone` / `guest` 受众锚点、委托管理 -（`PermissionSet.adminScope`）、带逐层归因的 `explain()` 解释引擎、 -`os compile` 的访问矩阵快照闸门、面向 MCP 客户端的自助 OAuth 2.1、 -编写期安全校验（`validateSecurityPosture`）、按操作粒度的 -`Object.requiredPermissions` 映射，以及软件包命名空间前缀强制。从未生效的 -schema（合规 / 脱敏 / 全局 RLS 配置）被直接移除。 - -### 12.x - -`@objectstack` **12.0** 收紧了 API 默认安全态势： - -- **匿名数据访问默认拒绝**（破坏性）—— `api.requireAuth` 现在默认 `true`； - 匿名 `/data/*` 请求返回 401。公开数据的部署必须显式退出： - `api: { requireAuth: false }`（启动时告警）。共享链接、公开表单、`/auth`、 - `/health` 不受影响。 -- **强制协议握手** —— `PROTOCOL_VERSION` + `checkProtocolCompat()` 在安装时 - 拒绝不兼容的软件包。 -- **自适应记录表面** —— 记录根据字段复杂度推导页面 vs 模态/抽屉展示； - `FormField.span` 改为响应式（`'auto'` / `'full'`）；关联列表支持 `'primary'` - 选项卡提升。 -- **软件包自带权限** —— 软件包可声明默认权限集，启动时自动物化并跟踪来源。 -- **构建期校验** —— `lint-view-refs`、`validateListViewMode`、 - `validateFormLayout` 及破坏性操作的 RBAC 映射成为编译闸门。 - -### 10.x - -10.x 列车运行于 `@objectstack` **10.0 – 10.2**。所有破坏性变更都落在多组织 -（multi-org）租户层，因此单租户的 ObjectOS 部署可从 9.x 无配置改动直接升级。 -变动内容如下： - -- **行级组织作用域拆分为独立插件**（10.0，破坏性）—— `organization_id` - 自动标记、按组织的 seed 重放,以及默认组织的 bootstrap,已从 - `@objectstack/plugin-security` 移出,改到可选启用的 - [`@objectstack/plugin-org-scoping`](https://www.npmjs.com/package/@objectstack/plugin-org-scoping)。 - 单组织部署因此更精简(无需在每次查询时剥离通配的 RLS),而 - `OS_MULTI_TENANT=true` 仍会在 `plugin-security` 之前自动注册该插件,因此由 - CLI 驱动的项目无需任何代码改动。按 ADR-0002,*tenant*(租户)是物理隔离 - (一个 Environment = 一个数据库);`organization_id` 则是同一数据库内的*逻辑* - 作用域,因此它单独成为一个插件。 -- **不再自动创建个人工作区**（10.0，破坏性）—— `plugin-security` 不再为每位 - 新用户创建「`'s Workspace`」组织。用户现在需要接受邀请,或显式创建 - 自己的第一个组织(Slack / Linear / GitHub-Orgs 的模式)。第一位注册用户 - —— 会被自动提升为平台管理员 —— 在多租户模式下仍会获得一个 - `Default Organization`,以便其会话能解析 RLS;单租户部署则不创建任何组织。 -- **`record` 表单字段类型**（ADR-0014）—— `Record` 属性(例如对象的 - `fields` 映射)现在可在 Studio 中作为一等公民的表单字段编辑,而不再以原始 - JSON 的形式泄露出来;对象预览面板也挂载了真正的 `ObjectGrid` 渲染器 —— - 你预览到的就是最终交付的。 -- **通过 `IEmbedder` 实现可插拔嵌入**（embeddings）—— 新增一套 embedder 协议, - 外加 [`@objectstack/embedder-openai`](https://www.npmjs.com/package/@objectstack/embedder-openai); - 知识 / RAG 适配器现在消费 `IEmbedder`,并已重命名以去掉 `plugin-` 前缀。 -- **Public Forms（公开表单）** —— 服务于 `/f/:slug` 的匿名 Web-to-Lead / - Web-to-Case 表单、一个统一的 FormPage(公开的 `/f/:slug` + 内部的 - `/forms/:name`)、一个 `type: 'form'` 的 action 变体,以及 `ObjectSchema` 上的 - `defaultDetailForm`。 -- **云身份拆分** —— `os cloud login` 现在与 `os login` 分离,云控制平面已迁至 - 私有仓库(让 OSS 运行时更精简),而 `objectstack init` 再次能脚手架出一个 - 可构建、可启动的项目。 - -### 9.x - -9.x 列车在切换到 10.0 之前运行于 `@objectstack` **9.0 – 9.11**。运行时的 -启动契约相较 8.0 没有变化 —— `createStandaloneStack` 仍然接收同样的 -artifact、环境与数据库设置 —— 因此 8.0 部署可无配置改动直接升级。变动 -集中在面向作者的层面： - -- **分析数据集成为唯一的作者层面入口**（9.0，破坏性）—— 仪表盘组件、 - 报表与列表图表现在绑定一个语义化的 `dataset`（`defineDataset(...)`）， - 并**按名称**选择维度/度量。旧的内联查询字段（组件上的 - `object`/`valueField`/`aggregate`、报表上的 - `objectName`/`columns`/`groupingsDown`、列表图表上的 - `xAxisField`/`yAxisFields`）已被移除。迁移方式：把内联查询移入一个 - `defineDataset` 并按名称引用它。`ChartTypeSchema` 也去掉了 8 个仅以其 - 基础类型渲染的变体类型（`stacked-bar`→`bar`、`spline`→`line`、 - `bubble`→`scatter`、…）。 -- **更严格的构建期校验**（9.6–9.7）—— `os compile` 现在会在遇到裸字段 - 引用（用 `amount` 而非 `record.amount`）、未知的 CEL 函数、以及错误的 - flow-value 插值语法时**失败**，并各自给出 did-you-mean 提示。一个以往 - 「能构建但默默出错」的栈现在会显式报错 —— 升级后请重新运行 - `os compile` 并修复它指出的问题。 -- **数字字段公式可计算混合算术**（9.7）—— `record.amount / 100` 和 - `record.price * 2` 现在会求值,而不再默默地得到 `null`;不再需要 - `/ 100.0` 这种浮点字面量的变通写法。 -- **对象级 REST 门控,现已强制执行**（ADR-0049）—— 对象的 - `apiEnabled: false` 会将其从 REST 面移除,`apiMethods` 白名单则限制 - 哪些操作可达。此前只解析而不强制执行。 -- **包文档作为元数据 + `book` 导航**（9.3–9.6）—— `src/docs/*.md` 注册为 - `doc` 元数据;`book` 元素（ADR-0046）声明一条派生成员关系的导航主线, - 通过 `GET /api/v1/meta/book/:name/tree` 提供,并带受众门控。 -- **`os package install`**（9.3）—— 从目录 id 或内联的隔离网（air-gapped） - artifact 将一个包安装进运行中的 runtime,使用 `--email` / `--password` - 进行认证。 -- **审批**（9.3）—— 退回修订（`maxRevisions`,默认 3）、由 jobs 支撑的 - SLA 自动升级、列表搜索/分页,以及无会话的双语批准/拒绝确认链接。 -- **入站 webhook 流程触发器**（9.3）—— 一个 `type: 'api'` 流程会挂载一个 - 经 HMAC 校验的 `POST /api/v1/automation/hooks/:flowName/:hookId` 端点, - 采用幂等、队列支撑的摄入。 -- **通知保留默认开启**（9.5）—— 通知历史在 **90 天**自动清理;将消息设置 - 的 `retentionDays: 0` 设为该值可永久保留历史。 -- **CLI 捆绑 AI 提供方 SDK**（9.0）—— 兼容 OpenAI 的提供方（DeepSeek、 - DashScope、SiliconFlow、OpenRouter、Cloudflare）在全局安装的 CLI 上 - 开箱即用。 - -有一项流程编写行为变化需要注意:`create_record` 节点的 `outputVariable` -现在保存**创建出的记录对象**(此前是裸 id),因此把原本期望得到 id 的 -`{var}` 引用改为 `{var.id}`。 - -### 8.0.x - -ObjectOS One 与捆绑的 server 此前基于 `@objectstack` **8.0.1**。 - -- **MCP over Streamable HTTP** —— 每个部署都可作为网络可达的 - [Model Context Protocol](https://modelcontextprotocol.io) 服务器。 - 通过 `OS_MCP_SERVER_ENABLED=true` 开启；端点位于 `/api/v1/mcp`，采用 - fail-closed 鉴权（匿名请求被拒绝）。插件已从 - `@objectstack/plugin-mcp-server` 重命名为 `@objectstack/mcp`。 -- **自助 API key** —— `POST /api/v1/keys` 生成只显示一次的 - `sys_api_key`。REST 数据与元数据 API（`/api/v1/data`、`/api/v1/meta`） - 现在通过与 MCP 相同的校验器认证 API key，并以 key 所有者的权限与 - 记录级安全运行。 -- **字段级条件规则** —— `visibleWhen`、`readonlyWhen`、`requiredWhen` - 由 ObjectQL 在服务端强制执行，而不仅在表单 UI 中生效。 -- **可复用的 RLS 读取过滤器** —— `security.getReadFilter(object, context)` - 暴露记录访问的读取范围；分析数据集、仪表盘与报表均桥接到它，无法安全 - 应用范围时 fail closed。 -- **Standalone host stack** —— 运行时改为单租户的 - `createStandaloneStack` host;7.x 那种按 hostname 路由的云连接 - `createObjectOSStack` 封装已移除。云部署改为让 `OS_ARTIFACT_FILE` - 指向已发布的 artifact URL。 - -### 5.0 —— `project` → `environment` 重命名（已发布） - -运行时中原称 *Project* 的概念已在全栈范围内重命名为 *Environment*。 -影响范围： - -- CLI 参数：`--environment` / `-e` -- HTTP 路径：`/api/v1/environments/:environmentId/...` -- 请求头：`X-Environment-Id` -- 环境变量：`OS_ENVIRONMENT_ID`（`OS_PROJECT_ID` 保留为已弃用的别名） -- 数据库列名：`environment_id` -- JSON schema：`EnvironmentArtifact` - -## 升级 - -机械式的步骤见 [升级与回滚](/docs/operate/upgrade)。升级前检查： - -1. 阅读从当前版本到目标版本之间每个 minor 的 CHANGELOG 条目。 -2. 运行 `os diff ` 找出破坏性的 - schema 变更。 -3. 针对目标版本运行 `os doctor`。 -4. 在全量滚动前先跑一个金丝雀实例。 -5. 准备好镜像 tag 与产物版本两条独立的回滚方案。 - -## 上报回归 - -如果某个 patch 或 minor 升级使原本可用的功能失效，请到 -[github.com/objectstack-ai/objectos/issues](https://github.com/objectstack-ai/objectos/issues) -提单，并写明你从哪个版本升级到哪个版本。我们把回归视为最高优先级 -的缺陷。