diff --git a/.github/scripts/check-locale-surface.mjs b/.github/scripts/check-locale-surface.mjs index 8f789c5..7f7e02d 100644 --- a/.github/scripts/check-locale-surface.mjs +++ b/.github/scripts/check-locale-surface.mjs @@ -226,8 +226,12 @@ const SITE_URL = 'https://docs.objectos.ai'; * outcome, not a maintenance tax: unlike the docs counts, it does not move on * every content PR. * - * The site root is separate: it exists in every locale because it is a - * language dispatch page that redirects to that locale's `/docs`. + * The site root is deliberately NOT here, and not expected anywhere below. It + * is a language dispatch page that redirects to that locale's `/docs` — a URL + * that serves no content — and `sitemap.ts` stopped submitting it under + * objectos#171, following www.objectos.ai's `noindex` dispatch page excluded + * from its sitemap. A root URL in the artifact is therefore `unexpected-url`, + * which is what keeps the redirect from creeping back in at `priority: 1`. */ const STATIC_PAGES = [ { path: 'privacy', locales: ['en', 'zh-Hans'] }, @@ -382,16 +386,14 @@ function localeUrl(lang, path, defaultLanguage) { } /** - * The full expected sitemap URL set: the root in every locale, the two legal - * pages in the locales they are written in, and every docs page in the locales - * that really have it. + * The full expected sitemap URL set: the two legal pages in the locales they + * are written in, and every docs page in the locales that really have it. + * Not the root — see `STATIC_PAGES`. */ function expectedSitemapUrls(surface) { const { languages, defaultLanguage, pages } = surface; const urls = new Set(); - for (const lang of languages) urls.add(localeUrl(lang, '', defaultLanguage)); - for (const { path, locales } of STATIC_PAGES) { for (const lang of locales) { if (languages.includes(lang)) urls.add(localeUrl(lang, path, defaultLanguage)); @@ -1051,8 +1053,9 @@ function evaluate({ surface, artifacts, bodies }) { // An oracle that expects nothing cannot contradict anything, so a green // over it is a claim and not a measurement — the same reason `artifact-empty` // above is a failure rather than a skip. It is reachable only for a - // vocabulary with a `universe`: the sitemap's expected set always holds at - // least the site root in each of the locales `readI18n` guarantees. + // vocabulary with a `universe` in practice: the sitemap's expected set + // holds the legal pages in every locale `STATIC_PAGES` names, so it is + // empty only for a locale list that declares none of them. if (expected.size === 0) { findings.push({ rule: 'nothing-expected', @@ -1290,14 +1293,11 @@ const BASE_CONTENT = { const BASE_TITLES = ['Home', 'Guide', 'Deep']; /** - * The sitemap the base fixture SHOULD produce: root in all three locales, the - * two legal pages in their two, `docs` and `docs/deep` in English only, and - * `docs/guide` in English and Japanese. + * The sitemap the base fixture SHOULD produce: the two legal pages in their + * two locales, `docs` and `docs/deep` in English only, and `docs/guide` in + * English and Japanese. No root in any locale — see `STATIC_PAGES`. */ const BASE_URLS = [ - 'https://docs.objectos.ai', - 'https://docs.objectos.ai/zh-Hans', - 'https://docs.objectos.ai/ja', 'https://docs.objectos.ai/privacy', 'https://docs.objectos.ai/zh-Hans/privacy', 'https://docs.objectos.ai/terms', @@ -1347,6 +1347,14 @@ const CASES = [ name: 'clean baseline', expect: [], }, + { + // objectos#171, reading 1: the redirecting root used to be submitted in + // every locale at `priority: 1`. It is excluded now, and a sitemap that + // advertises it again is the regression this case keeps red. + name: 'the redirecting root creeps back into the sitemap', + urls: ['https://docs.objectos.ai', 'https://docs.objectos.ai/ja', ...BASE_URLS], + expect: ['unexpected-url'], + }, { // The #169 defect, in miniature: every page advertised in every locale. name: 'every page in every locale (the #169 shape)', @@ -1499,9 +1507,6 @@ const CASES = [ name: 'no title is exclusive to any locale', content: { 'index.mdx': mdx('Shared'), 'index.ja.mdx': mdx('Shared') }, urls: [ - 'https://docs.objectos.ai', - 'https://docs.objectos.ai/zh-Hans', - 'https://docs.objectos.ai/ja', 'https://docs.objectos.ai/privacy', 'https://docs.objectos.ai/zh-Hans/privacy', 'https://docs.objectos.ai/terms', diff --git a/.github/scripts/check-positioning.mjs b/.github/scripts/check-positioning.mjs new file mode 100644 index 0000000..3ddefc6 --- /dev/null +++ b/.github/scripts/check-positioning.mjs @@ -0,0 +1,173 @@ +#!/usr/bin/env node +/** + * The positioning gate for objectos#171. Three rules: + * + * (a) Each copy of the positioning equals `apps/docs/lib/positioning.ts` (its + * literals, joined as its own `POSITIONING = [...].join(...)` says): the + * `content/docs/index.mdx` frontmatter `description` (MDX cannot import), the + * site-wide meta description on the built `_not-found.html` (that route sets + * only a title), and the built `/llms.txt` `> ` summary line. + * (b) The brand is spelled ObjectOS in every built HTML page and both `llms` + * bodies. It reads the build, not the sources: `lib/i18n.ts` keeps + * "ObjectStack Documentation" in a comment that ships nowhere, as #171 allowed. + * (c) The stale sentences #171 removed stay out of the English `content/docs/` + * sources, outside code fences and MDX comments. + * + * Run it after `pnpm turbo run build`; a missing build fails. `--self-test` runs the fixtures. + */ +import { existsSync, readFileSync, readdirSync } from 'node:fs'; +import { dirname, join, resolve } from 'node:path'; +import { fileURLToPath } from 'node:url'; + +const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '../..'); +const CONSTANT = 'apps/docs/lib/positioning.ts'; +const INDEX = 'content/docs/index.mdx'; +const GLOSSARY = 'content/docs/resources/glossary.mdx'; +const BUILD = 'apps/docs/.next/server/app'; +const LOCALE_SIBLING = /\.[a-z]{2}(?:-[A-Z][a-z]{3})?\.mdx$/; + +const MISSPELT = /\b(?:ObjectStack Protocol|ObjectStack Documentation|Object OS|objectOS|ObjectOs)\b/; +const STALE = [ + /ObjectOS\s+is\s+a\s+self-hosted\s+runtime/, + /[Nn]ever\s+phones\s+home/, + /[Dd]oes\s+not\s+call\s+home/, + /[Nn]ever\s+calls\s+home/, + /No\s+licen[cs]e\s+server/, // capital N: "no seats, ..., no license server" is the open runtime and stays + /[Ff]ully\s+self-contained/, + /[Ii]nside\s+your\s+firewall/, +]; +const OPEN_SOURCE = /Open[\s-]+source,\s+Apache-2\.0/i; // checked inside the glossary's ObjectOS entry only + +/** POSITIONING as the constant's file composes it, or undefined when it cannot be read. */ +function composed(ts) { + const literal = {}; + for (const m of ts.matchAll(/export const (\w+) =\s*(['"])((?:\\.|(?!\2).)*)\2;/g)) { + literal[m[1]] = m[3].replace(/\\(.)/g, '$1'); + } + const join = /export const POSITIONING = \[([^\]]*)\]\.join\((['"])(.*?)\2\)/.exec(ts.replace(/\s*\n\s*/g, ' ')); + const parts = join?.[1].split(',').map((s) => s.trim()).filter(Boolean) ?? []; + if (!parts.length || parts.some((p) => literal[p] === undefined)) return undefined; + return parts.map((p) => literal[p]).join(join[3]); +} + +function frontmatterDescription(mdx) { + const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---/.exec(mdx)?.[1] ?? ''; + const v = /^description:[ \t]*(.*)$/m.exec(frontmatter)?.[1].trim(); + if (v?.startsWith("'")) return v.slice(1, -1).replace(/''/g, "'"); + try { + return v?.startsWith('"') ? JSON.parse(v) : v; + } catch { + return v; // malformed quoting is returned raw, so it differs and is reported + } +} + +const ENTITY = { amp: '&', quot: '"', lt: '<', gt: '>', apos: "'" }; +const decode = (s) => + s?.replace(/&(?:#x([0-9a-f]+)|#(\d+)|(\w+));/gi, (m, hex, dec, name) => + hex ? String.fromCodePoint(parseInt(hex, 16)) : dec ? String.fromCodePoint(+dec) : (ENTITY[name] ?? m), + ); +const metaDescription = (html) => decode(/ l.startsWith('> '))?.slice(2), + }; + return Object.entries(copies) + .filter(([, got]) => got !== want) + .map(([what, got]) => `(a) ${what} is not POSITIONING\n got: ${JSON.stringify(got)}\n want: ${JSON.stringify(want)}`); +} + +/** (b) No shipped file spells the brand another way. A missing file is a finding: it was not measured. */ +const ruleB = (files) => + files.flatMap(([path, text]) => { + if (text === undefined) return [`(b) ${path} does not exist, so it was not measured`]; + const m = MISSPELT.exec(text); + return m ? [`(b) ${path} spells the brand ${JSON.stringify(m[0])}; it is ObjectOS`] : []; + }); + +/** (c) No English source brings a stale sentence back. Fences and comments are blanked, lines kept. */ +function ruleC(files) { + const out = []; + const blank = (m) => m.replace(/[^\n]/g, ' '); + for (const [path, text] of files) { + const prose = text.replace(/\{\/\*[\s\S]*?\*\/\}|^ {0,3}(`{3,}|~{3,})[\s\S]*?^ {0,3}\1/gm, blank); + for (const re of STALE) { + const m = re.exec(prose); + const line = m && prose.slice(0, m.index).split('\n').length; + if (m) out.push(`(c) ${path}:${line} brings back ${JSON.stringify(m[0].replace(/\s+/g, ' '))}`); + } + } + const glossary = files.find(([path]) => path === GLOSSARY)?.[1]; + const entry = glossary?.split(/\n(?=#)/).find((s) => s.startsWith('### ObjectOS\n')); + if (entry === undefined) out.push(`(c) ${GLOSSARY} has no "### ObjectOS" entry; the open-source check measured nothing`); + else if (OPEN_SOURCE.test(entry)) out.push(`(c) ${GLOSSARY} calls ObjectOS "Open source, Apache-2.0" again`); + return out; +} + +function gate() { + const at = (p) => join(ROOT, p); + const read = (p) => (existsSync(at(p)) ? readFileSync(at(p), 'utf8') : undefined); + const list = (dir) => readdirSync(at(dir), { recursive: true }).map((f) => join(dir, f)); + if (!existsSync(at(BUILD))) { + console.error(`✗ positioning: ${BUILD} does not exist. Run pnpm turbo run build first.`); + return 1; + } + const pages = list(BUILD).filter((f) => f.endsWith('.html')); + const shipped = [...pages, `${BUILD}/llms.txt.body`, `${BUILD}/llms-full.txt.body`]; + const sources = list('content/docs').filter((f) => f.endsWith('.mdx') && !LOCALE_SIBLING.test(f)); + const findings = [ + ...ruleA({ ts: read(CONSTANT), index: read(INDEX), notFound: read(`${BUILD}/_not-found.html`), llms: read(`${BUILD}/llms.txt.body`) }), + ...ruleB(shipped.map((p) => [p, read(p)])), + ...ruleC(sources.map((p) => [p, read(p)])), + ]; + for (const f of findings) console.error(` ${f}`); + if (findings.length) { + console.error(`\n✗ positioning: ${findings.length} finding(s). The rules are in this script's header.`); + return 1; + } + console.log(`✓ positioning: 3 copies equal the constant; the brand is right in ${pages.length} pages and 2 llms bodies; no stale sentence in ${sources.length} English sources`); + return 0; +} + +/* Self-test: per rule, a good fixture that must give 0 findings and a bad one that must give exactly N. */ +const A_OK = { + ts: "export const A = 'One ontology.';\nexport const B =\n \"It's yours.\";\nexport const POSITIONING = [\n A,\n B,\n].join(' ');\n", + index: `---\ntitle: Introduction\ndescription: "One ontology. It's yours."\n---\n\nBody.\n`, + notFound: '404', + llms: "# ObjectOS\n\n> One ontology. It's yours.\n", +}; +const A_BAD = { + index: '---\ndescription: One ontology, yours.\n---\n', + notFound: '', + llms: "> One ontology.\nIt's yours.\n", +}; +const B_BAD = ['ObjectStack Protocol', 'ObjectStack Documentation', 'Object OS', 'objectOS', 'ObjectOs']; +const C_OK = 'No seats, no license server. Does ObjectOS phone home?\n\n```\nObjectOS is a self-hosted runtime\n```\n\n{/* was: never phones home */}\n'; +const C_BAD = 'ObjectOS is a self-hosted\nruntime. It never phones home, does not call home, never calls home.\n\nNo license server. Fully\nself-contained, inside your firewall.\n'; +const glossary = (entry) => [GLOSSARY, `### ObjectOS\n\n${entry}\n\n### ObjectStack\n\nOpen source, Apache-2.0.\n`]; +const CASES = [ + ['(a) the three copies equal the constant', () => ruleA(A_OK), 0], + ['(a) index paraphrased, site meta stale, llms line split', () => ruleA({ ...A_OK, ...A_BAD }), 3], + ['(b) ObjectOS, the host and the package scope', () => ruleB([['a.html', 'Intro | ObjectOS, docs.objectos.ai, @objectos/docs']]), 0], + ['(b) the five wrong spellings, one file each', () => ruleB(B_BAD.map((s, i) => [`${i}.html`, `

${s} boots.

`])), 5], + ['(c) list form, a question, a fenced quote, a comment', () => ruleC([glossary('Commercial. Not open source.'), ['a.mdx', C_OK]]), 0], + ['(c) the eight stale sentences, three wrapped', () => ruleC([glossary('The runtime. Open\nsource, Apache-2.0.'), ['a.mdx', C_BAD]]), 8], +]; + +function selfTest() { + const wrong = CASES.filter(([name, run, want]) => { + const findings = run(); + console.log(`${findings.length === want ? '✓' : '✗'} ${name}: ${findings.length} finding(s), expected ${want}`); + if (findings.length !== want) for (const f of findings) console.error(` ${f}`); + return findings.length !== want; + }); + console.log(wrong.length ? `\n✗ self-test: ${wrong.length} case(s) wrong` : '\n✓ self-test: every rule fails its bad fixture and passes its good one'); + return wrong.length ? 1 : 0; +} + +process.exitCode = process.argv.includes('--self-test') ? selfTest() : gate(); diff --git a/.github/scripts/smoke-docs.mjs b/.github/scripts/smoke-docs.mjs index 4535942..dd9e57d 100644 --- a/.github/scripts/smoke-docs.mjs +++ b/.github/scripts/smoke-docs.mjs @@ -146,10 +146,16 @@ const TARGET_DEFAULTS = { * table, so it exercises the part of the route tree a shallow check misses. * Both content pages predate the version currently serving (added 2026-05-24 * and earlier), so this list is runnable against the pinned live version. + * + * The index H1 is `Introduction` since #171 gave `content/docs/index.mdx` a + * real title instead of the bare brand. A version from before that change + * renders `ObjectOS` there and reads as `h1-mismatch` against this list — + * which is what a rollback to such a version would show, and is correct: the + * list describes the site this tree ships, not every version ever served. */ const TARGETS = [ - { path: '/', finalPath: '/docs', h1: /^ObjectOS$/i }, - { path: '/en/docs', finalPath: '/docs', h1: /^ObjectOS$/i }, + { path: '/', finalPath: '/docs', h1: /^Introduction$/i }, + { path: '/en/docs', finalPath: '/docs', h1: /^Introduction$/i }, { path: '/docs/quickstart', finalPath: '/docs/quickstart', h1: /^Quickstart$/i }, { path: '/docs/build/interface/views', @@ -428,7 +434,7 @@ function goodPage({ title = 'Quickstart | ObjectOS', h1 = 'Quickstart', links = 20, - prose = 'ObjectOS is a self-hosted runtime for building internal tools. '.repeat(20), + prose = 'The ontology is the software, and this fixture carries enough prose to clear the floor. '.repeat(20), } = {}) { const nav = Array.from({ length: links }, (_, i) => `Page ${i}`).join(''); return ( diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 66174c4..e00f0c1 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -146,6 +146,20 @@ jobs: shell: bash run: node .github/scripts/check-locale-surface.mjs | tee -a "$GITHUB_STEP_SUMMARY" + # #171: one positioning constant (`apps/docs/lib/positioning.ts`, quoting + # the objectstack README), one brand spelling, and no stale sentence + # coming back. The brand and the positioning copies are read off the + # BUILT pages and `llms` bodies — the 2026-09-08 mandate is about shipped + # output, and a source scan would flag the code comment in `lib/i18n.ts` + # that the ruling on #171 accepted — so this sits after `build`, on the + # same footing as `Locale surface` above: not a turbo task, its + # `--self-test` under `pnpm turbo run test` below, `shell: bash` for the + # same pipefail reason. The stale-sentence rules read the English sources + # under `content/docs/`, so a finding names the `path:line` to open. + - name: Positioning + shell: bash + run: node .github/scripts/check-positioning.mjs | tee -a "$GITHUB_STEP_SUMMARY" + - run: pnpm turbo run test # Defect 2 of #269: the deploy used to run its own `pnpm install` and its diff --git a/README.md b/README.md index 8b8b898..849e6db 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ > ## Build & ask online. Keep the data you own. > -> ObjectOS is the **commercial runtime environment for +> **The ontology is the software.** ObjectOS is the **commercial runtime environment for > [ObjectStack](https://github.com/objectstack-ai/objectstack) apps — built > and operated entirely in the browser**: tell the built-in AI Builder what > your business needs — a helpdesk, an approval flow, a CRM — and it's running diff --git a/apps/docs/app/layout.tsx b/apps/docs/app/layout.tsx index 14cc545..ed5a0a5 100644 --- a/apps/docs/app/layout.tsx +++ b/apps/docs/app/layout.tsx @@ -2,6 +2,7 @@ import './global.css'; import type { ReactNode } from 'react'; import type { Metadata } from 'next'; import { SITE_URL } from '@/lib/seo'; +import { POSITIONING } from '@/lib/positioning'; export const metadata: Metadata = { metadataBase: new URL(SITE_URL), @@ -9,7 +10,12 @@ export const metadata: Metadata = { template: '%s | ObjectOS', default: 'ObjectOS', }, - description: 'Customer-hosted runtime for ObjectStack applications. Private, compliant, yours.', + // The site-wide description is the positioning paragraph, one constant + // quoted from the objectstack README (objectos#171, Q4). It used to be a + // literal here that contradicted the index page and the glossary; now + // `check-positioning.mjs` asserts this field reads the constant and that the + // other copies agree with it. + description: POSITIONING, icons: { icon: '/logo.svg', }, diff --git a/apps/docs/app/llms.txt/route.ts b/apps/docs/app/llms.txt/route.ts index 297880e..6286a92 100644 --- a/apps/docs/app/llms.txt/route.ts +++ b/apps/docs/app/llms.txt/route.ts @@ -1,28 +1,28 @@ import type { Folder, Item, Node } from 'fumadocs-core/page-tree'; import { llms } from 'fumadocs-core/source/llms'; import { i18n } from '@/lib/i18n'; +import { POSITIONING } from '@/lib/positioning'; import { SITE_URL, localeUrl } from '@/lib/seo'; -import { source } from '@/lib/source'; +import { SITE_NAME, source } from '@/lib/source'; export const revalidate = false; /** - * The one place this site states what ObjectOS is. - * - * Taken verbatim from the marketing site's own `/llms.txt` - * (`www.objectos.ai`, `src/pages/llms.txt.ts`) — the current authoritative - * positioning string for the two products. It is deliberately NOT re-derived - * from `content/docs/index.mdx`: that page's framing is itself under review, - * and `llms.txt` must not become the place a second version of it appears. - * - * If the positioning changes, change this constant. Nothing else in this file - * encodes it. + * The summary line is the positioning paragraph in `lib/positioning.ts` — the + * one constant this site states ObjectOS in, quoted from the objectstack + * README (objectos#171, Q4). This file used to carry its own literal, taken + * from the marketing site's `/llms.txt`, which was a second version of the + * positioning by construction; both sites now quote the README, and + * `check-positioning.mjs` compares the BUILT summary line against the + * constant, so a literal reintroduced here goes red in CI. */ -const SUMMARY = - 'ObjectStack is the open target format and runtime for AI-written enterprise software; ObjectOS is the commercial production platform where teams build, review, deploy, and operate ObjectStack applications.'; +const SUMMARY = POSITIONING; -/** Title line: the product this documentation is for. */ -const TITLE = 'ObjectOS'; +/** + * Title line: the product this documentation is for, spelled the one way + * `SITE_NAME` spells it. + */ +const TITLE = SITE_NAME; /** Heading for the pages that sit at the tree root rather than in a section. */ const ROOT_HEADING = 'Overview'; diff --git a/apps/docs/app/sitemap.ts b/apps/docs/app/sitemap.ts index 429c04b..028e903 100644 --- a/apps/docs/app/sitemap.ts +++ b/apps/docs/app/sitemap.ts @@ -12,9 +12,14 @@ export default function sitemap(): MetadataRoute.Sitemap { // Top-level static pages (paths are locale-independent slugs). const staticPaths: Array<{ path: string; priority: number; locales: readonly string[] }> = [ - // The root exists in every locale: it is a language dispatch page that - // redirects to that locale's /docs. - { path: '', priority: 1, locales: i18n.languages }, + // The root is deliberately absent. `app/page.tsx` and `app/[lang]/page.tsx` + // are language-dispatch redirects to that locale's `/docs` — a URL that + // serves no content — and this file used to submit it in every locale at + // `priority: 1`, the highest entry in the sitemap (objectos#171, reading + // 1). www.objectos.ai is the precedent: its root is a `noindex` dispatch + // page filtered out of its sitemap. `check-locale-surface.mjs` expects the + // same absence, so a root entry creeping back is an `unexpected-url`. + // // `privacy` and `terms` carry their copy in a `content` record inside their // own route component, and render `content[lang] ?? content.en` for every // other locale — the same fallback shape the docs pages had. So the locales diff --git a/apps/docs/lib/positioning.ts b/apps/docs/lib/positioning.ts new file mode 100644 index 0000000..9d1fbf3 --- /dev/null +++ b/apps/docs/lib/positioning.ts @@ -0,0 +1,70 @@ +/** + * The one place this site states what ObjectOS is. + * + * ## Source of truth + * + * `objectstack-ai/objectstack` `README.md` at `main`: lines 7-16 carry the + * headline and the four promises, lines 26-30 the sentence that defines ObjectOS. + * The maintainer's ruling of 2026-10-05 (objectos#171, Q4) makes that README the + * single source of the positioning. This repository and www.objectos.ai both + * quote it, and neither paraphrases it: when the positioning changes, the README + * changes first and the new words are copied here, byte for byte. + * + * ## Who reads it + * + * Three machine-facing surfaces carry `POSITIONING`: the site-wide meta + * description (`app/layout.tsx`), the `/llms.txt` summary line + * (`app/llms.txt/route.ts`) and the `description` frontmatter of + * `content/docs/index.mdx`. MDX frontmatter cannot import, so that third copy is + * a literal, and `.github/scripts/check-positioning.mjs` compares it to this + * constant on every pull request — a copy that differs fails CI. The same gate + * reads the four literals below, so keep each one on the shape it parses: one + * `export const NAME =` followed by a single quoted string. + * + * ## The one departure from the README's bytes + * + * `OBJECTOS_DEFINITION` reads "built on ObjectStack" where the README reads + * "built on this stack". Inside the README the phrase has a referent; on this + * site it has none, so the referent is spelled out. That is the only + * substitution, and it is declared here so nobody corrects it back. + * + * ## No imports + * + * A leaf module on purpose. `app/layout.tsx` imports it and sits on every + * route's tree, so anything imported here ships in every bundle — `lib/site.ts` + * measures what one careless import costs at that position. Never add an + * `import` to this file. + */ + +/** README line 7: the headline. */ +export const ONTOLOGY_HEADLINE = 'The ontology is the software.'; + +/** README lines 9-10: the four promises as one sentence. */ +export const ONTOLOGY_PROMISE = + 'One executable business ontology. AI writes it, the runtime runs it, agents operate it, you own it.'; + +/** README lines 27-30: what ObjectOS is, with "this stack" spelled out (see above). */ +export const OBJECTOS_DEFINITION = + "Want the same loop hosted, in the browser, nothing to install? That's ObjectOS, the commercial runtime environment built on ObjectStack."; + +/** + * The edition clause. Not in the README: fixed by the maintainer's rulings on + * objectos#171 — Q1, ObjectOS still ships a self-managed edition, and Q2, a + * Cloud tenant can export its ontology and run it on the open runtime — and + * quoted verbatim by www.objectos.ai as well. + */ +export const OBJECTOS_EDITIONS = + 'ObjectOS runs hosted in the browser with nothing to install (ObjectOS Cloud) or self-managed on your own infrastructure (ObjectOS Enterprise), and on either edition you can export your ontology and run it on the open-source ObjectStack runtime.'; + +/** + * The positioning paragraph every machine-facing surface carries, in this order + * and joined by single spaces. `check-positioning.mjs` composes the same four + * literals the same way and compares the shipped `/llms.txt` summary against the + * result, so the composition cannot drift from the parts without a red build. + */ +export const POSITIONING = [ + ONTOLOGY_HEADLINE, + ONTOLOGY_PROMISE, + OBJECTOS_DEFINITION, + OBJECTOS_EDITIONS, +].join(' '); diff --git a/content/docs/architecture.mdx b/content/docs/architecture.mdx index c728be0..4eae96f 100644 --- a/content/docs/architecture.mdx +++ b/content/docs/architecture.mdx @@ -3,8 +3,9 @@ title: Architecture description: What you're actually running — for the engineer evaluating whether to bring this in. --- -A practical view of what runs on your machines when you deploy -ObjectOS, what data leaves your network, and what doesn't. +A practical view of what runs when you deploy ObjectOS — on your own +machines with **ObjectOS Enterprise**, or operated for you on **ObjectOS +Cloud** — what data leaves your network, and what doesn't. The mental model is two thin layers: @@ -22,7 +23,9 @@ metadata after a HITL approval. ## What you deploy -One Node.js process, serving one app. That's it. +One Node.js process, serving one app. That's it. On ObjectOS Cloud we run +that process for you; on ObjectOS Enterprise you deploy it, from the +licensed runtime image described under [Deployment](/docs/deploy). ```text ┌─────────────────────────────────────────────────────┐ @@ -58,6 +61,12 @@ one; see [Docker](/docs/deploy/docker). ## Where your data lives +On **ObjectOS Enterprise** — the self-managed edition this table describes — +nothing below leaves your network. On **ObjectOS Cloud** the same process +runs in our infrastructure instead, and on either edition the ontology +itself is yours: export it and run it on the open-source ObjectStack +runtime. + | Data | Lives in | Leaves your network? | |---|---|---| | Business records | Your database | **No** | @@ -67,9 +76,10 @@ one; see [Docker](/docs/deploy/docker). | Uploaded files | Your disk or your S3/R2 bucket | **No** | | The compiled app definition (`objectstack.json`) | A file on disk or fetched from your control plane | Optional | -ObjectOS does not call home. No telemetry. No license check. If you cut -internet access entirely, it keeps running indefinitely. See -[Air-gapped](/docs/deploy/air-gapped). +Self-managed ObjectOS validates its licence online; Enterprise air-gapped +licences validate offline, so a deployment with no internet access at all +keeps running. See [Air-gapped](/docs/deploy/air-gapped) for the supported +licence and cloud-posture pairs. ## How a request is served @@ -92,14 +102,14 @@ authentication, the permission checks, and one compiled query. ## The three layers (only matters if you're integrating) -Most customers deploy only **ObjectOS**. The other two layers exist if -you want to know where the artifact comes from: +Most customers run only **ObjectOS**. The other two layers exist if you +want to know where the artifact comes from: | Layer | What it is | Where it runs | |---|---|---| | **Framework** (`@objectstack/*`) | Open-source kernel, ObjectQL, plugins, drivers | npm — pulled in at build time | | **Control plane** (optional) | Publishes compiled `objectstack.json` artifacts; you can use the hosted ObjectOS Cloud, run your own, or skip it entirely | Your CI, our cloud, or your laptop | -| **ObjectOS** | The runtime you operate | **Your infrastructure** | +| **ObjectOS** | The commercial runtime environment built on the framework | **ObjectOS Cloud** (we operate it) or **your infrastructure** (ObjectOS Enterprise) | If you're shipping a single app, you don't need a control plane — compile `objectstack.config.ts → dist/objectstack.json` in your CI and @@ -122,7 +132,7 @@ carries the exact contract for each. 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 +any of the modes above. A self-managed 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). diff --git a/content/docs/build/ai-skills.mdx b/content/docs/build/ai-skills.mdx index 2fff9a5..19820ab 100644 --- a/content/docs/build/ai-skills.mdx +++ b/content/docs/build/ai-skills.mdx @@ -1,6 +1,6 @@ --- title: IDE Skills (Claude Code / Cursor / Copilot) -description: Install ObjectOS skills into your coding agent so Claude Code, Cursor, Copilot, Codex and friends know how to author ObjectOS metadata correctly. +description: Install the ObjectStack skills into your coding agent so Claude Code, Cursor, Copilot, Codex and friends know how to author ObjectStack metadata — the ontology ObjectOS runs — correctly. --- The [AI Builder](./ai-builder) lives inside ObjectOS and talks to your @@ -8,8 +8,9 @@ tenant's database. But sometimes you want the same domain knowledge inside your IDE — when you're hand-editing `*.object.ts`, designing a flow, or asking Cursor to write a CEL predicate. -ObjectOS ships **9 first-party agent skills** that teach coding -assistants how to author every kind of ObjectOS metadata. They are +ObjectStack ships **9 first-party agent skills** that teach coding +assistants how to author every kind of ObjectStack metadata — the ontology +ObjectOS runs. They are distributed through the open [`skills`](https://www.npmjs.com/package/skills) ecosystem (Vercel Labs) and work with **Claude Code, Cursor, Copilot, Codex, Gemini CLI, Windsurf, Cline, Continue, Roo, Goose, Kiro, diff --git a/content/docs/extend-existing-systems.mdx b/content/docs/extend-existing-systems.mdx index 442446b..cc80b81 100644 --- a/content/docs/extend-existing-systems.mdx +++ b/content/docs/extend-existing-systems.mdx @@ -1,18 +1,24 @@ --- title: Extend Existing Systems -description: Connect ObjectOS to the business systems you already run, then add AI-native query, analysis, and automation — without a migration. +description: Federate a database you already run into ObjectOS as an external datasource — read-only by default, and early — and model the tables you care about as objects, without a migration. --- Most teams evaluating ObjectOS already have a system of record — a CRM, an ERP, a ticketing tool, a homegrown back office sitting on a production SQL or MongoDB database. The question is rarely "should we throw it away -and rebuild?" It's "can we make the thing we already have **AI-native**, -without a risky migration?" - -That's exactly the path this page describes: **connect ObjectOS to your -existing database, model the tables you care about as objects, and let AI -agents query, analyze, and act on that data** — under your permissions, -on your infrastructure, with the original system untouched. +and rebuild?" It's "can we work with the thing we already have, without a +risky migration?" + +One boundary first, because it decides what this page can promise. The +ontology ObjectOS runs is **not a semantic layer over your existing +systems**: it is the system — the database, API, UI and agent tools are +derived from it. What it offers for a system you already run is narrower, +and stated the way the +[ObjectStack](https://github.com/objectstack-ai/objectstack) README states +it: **federating an external datasource is read-only by default and +early.** You connect the database as a datasource, model the tables you +care about as objects, and ObjectOS reads them through the same permission +model as everything else. The system of record stays the system of record. ## The shape of the move @@ -20,27 +26,29 @@ You don't replace your business system. You put ObjectOS *next to* it and point it at the same database: 1. **Connect** the existing database as a [datasource](/docs/configure/data-sources). - Credentials come from your environment; the connection can be - read-only if you only want to analyze. + Credentials come from your environment. Start read-only — a `readOnly` + datasource, or a read-only database user — and enable writes + deliberately. 2. **Model** the tables as objects — by hand, or by letting a coding agent scan the schema and generate source-level object files for you. 3. **Bind** each object to the datasource (per object, or with a routing rule for a whole namespace). -4. **Use AI** — the moment a table is an object, every agent, tool, flow, - and dashboard works on it, routed automatically to the right database. +4. **Read** — the moment a table is an object, every view, dashboard, flow + and agent tool can read it, routed automatically to the right database + and gated by the same permissions. Nothing about the legacy application changes. The rows stay where they -are. ObjectOS becomes the AI-native, permission-aware surface on top. +are, and the legacy application keeps writing them. ## Why this works without a rewrite | Concern | How ObjectOS handles it | |---|---| | "We can't move the data" | The data never moves. ObjectOS connects to your database in place. | -| "We can't risk writes to production" | Bind objects to a **read-only** datasource (or a read-only DB user). Analyze safely first; enable writes deliberately. | +| "We can't risk writes to production" | Start read-only — the `readOnly` capability, or a read-only database user — and enable writes deliberately, per object, once you trust the model. | | "Modeling every table is weeks of work" | A coding agent scans the schema and generates one object file per table — you review and refine, you don't hand-type. | | "AI can't be trusted with our data" | Agents run as the **signed-in user** and obey object-, record-, and field-level permissions. They never see more than the person behind them. | -| "Our data can't leave our network" | ObjectOS runs in your environment. Business data and prompts stay inside your perimeter. | +| "Our data can't leave our network" | On ObjectOS Enterprise, ObjectOS runs in your environment: business data and prompts stay inside your perimeter. | ## Generating objects with a coding agent @@ -67,16 +75,25 @@ Once the tables are modeled as objects bound to your existing database: - **Natural-language analysis.** Users ask questions about the real records — "which deals slipped this quarter and who owns them?" — and the answer is computed against live data through ObjectQL. -- **Governed automation.** Flows and actions can read and (where allowed) - write the same data, with every step audited. +- **Governed automation.** Flows and actions read the same data and — + where you have enabled writes — write it, with every step audited. - **A generated API and UI.** REST endpoints and admin screens come - from the same metadata — no extra integration layer. + from the same metadata. - **One permission model.** The boundary that applies to humans applies identically to AI traffic. +## What it is not, yet + +Federation is early. Expect the read path to be the mature one, and check +[Data Sources](/docs/configure/data-sources) and the framework's own +[External Datasources](https://docs.objectstack.ai/docs/data-modeling/external-datasources) +guide for what each datasource protocol supports today. If what you need +is a semantic layer that *describes* many systems without running any of +them, that is a different kind of product. + ## Start here - [Data Sources](/docs/configure/data-sources) — connect a database, bind objects, route queries - [AI Agents](/docs/build/agents) — declarative agents over your objects - [Permissions](/docs/configure/permissions) — the model AI inherits -- [Quickstart](/docs/quickstart) — stand up a runtime in minutes +- [Quickstart](/docs/quickstart) — stand up the open runtime in minutes diff --git a/content/docs/index.de.mdx b/content/docs/index.de.mdx deleted file mode 100644 index 7eaddc5..0000000 --- a/content/docs/index.de.mdx +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: ObjectOS -description: Die Laufzeitumgebung für interne Tools, die in Ihrem Netzwerk bleibt. Ein Befehl zum Starten, Ihre Datenbank, Ihre Authentifizierung, Ihre Daten — niemals unsere. -translation: - source_sha: d8f6522ae3a04825e07a12e003ff4eb1247902133cc0bde24e2640d9e7259fd0 - guide_rev: 1 - mode: auto ---- - -**ObjectOS ist eine selbst gehostete Laufzeitumgebung zum Erstellen -interner Tools, Admin-Panels und Back-Office-Anwendungen, ohne die -Kontrolle über Ihre Daten aufzugeben.** Beschreiben Sie dem -in der Console integrierten AI Builder, was Sie benötigen — oder forken Sie -eine Vorlage — und erhalten Sie REST-APIs, eine generierte Admin-UI, -Authentifizierung, RBAC, Audit-Logs, Dateispeicher, Hintergrundjobs, -Webhooks und KI-Integration. Alles läuft in Ihrem Netzwerk, auf Ihrer -Datenbank. - -Es ist das, was herauskäme, wenn Retool, Supabase und Salesforce ein Kind -bekämen, das innerhalb Ihrer Firewall läuft — mit einer KI, die die Apps für -Sie erstellt. - -## In 60 Sekunden einsatzbereit - -```bash -npm i -g @objectstack/cli -os start -``` - -Öffnen Sie **http://localhost:3000** und Sie haben ein funktionierendes -ObjectOS mit Console und Account, einem Audit-Log und einer -SQLite-Datenbank — ohne Konfiguration, ohne Scaffolding. - -Dann entweder: - -- **Sprechen Sie mit dem AI Builder** — *"Ich muss Support-Tickets mit - Priorität und zugewiesener Person verfolgen"* — und beobachten Sie, wie die - Metadaten generiert werden. Siehe - [Build → AI Builder](/docs/build/ai-builder). -- **Installieren Sie eine Vorlage** aus dem in der Console integrierten - marketplace (Todo, Contracts, Helpdesk, …) und erhalten Sie mit einem Klick - eine echte App. -- **Forken Sie eine [Vorlage](/docs/build/templates)**, wenn Sie - TypeScript-Quellcode unter Ihrer Kontrolle haben möchten. - -## Warum ObjectOS statt … - -| Sie verwenden | Schmerzpunkt | Was ObjectOS Ihnen bietet | -|---|---|---| -| **Retool / Appsmith** | Der UI-Builder ist großartig, aber Ihre Daten liegen in deren Cloud und die Preise skalieren mit der Nutzerzahl | Ihre Daten verlassen niemals Ihr Netzwerk; Apache-2.0, keine Lizenzgebühr pro Sitzplatz | -| **Supabase / Firebase** | Backend-as-a-Service ist schnell, aber an einen Anbieter gebunden; mandantenfähiges SaaS von Grund auf | Gleiche DX (automatische APIs, Authentifizierung, Speicher), aber Sie besitzen die Laufzeitumgebung und die Datenbank | -| **Salesforce / NetSuite** | Leistungsstarke Plattform, mühsame Anpassung, schwindelerregende Kosten pro Sitzplatz | Gleiches metadatengesteuertes Modell (Objekte, Felder, Rollen, Freigaberegeln), selbst gehostet, keine Gebühr pro Sitzplatz | -| **Selbstentwicklung (Next + Prisma + NextAuth)** | Sie bauen jedes Mal RBAC, Audit, Datei-Uploads, Einstellungen, Webhooks und Jobs neu auf | Liefern Sie die eigentliche Geschäftslogik aus; die Plattform-Infrastruktur ist bereits vorhanden | - -## Was Sie sofort erhalten - -| Bereich | Was es ist | -|---|---| -| **Automatische REST-API** | Jedes Objekt, das Sie deklarieren, erhält `/api/v1/data/` mit Filtern/Sortieren/Paginierung | -| **Console** (`/_console/`) | Generierte Admin-UI: Datensätze durchsuchen und bearbeiten, Benutzer/Rollen/Berechtigungssätze verwalten, Audit-Log, Sitzungen, API-Schlüssel und Einstellungen anzeigen | -| **Account** (`/_account/`) | Anmeldung, Registrierung, Passwort-Zurücksetzung, OAuth, OIDC/SSO, Passkeys, 2FA | -| **20+ Plugins** | RBAC + Sicherheit auf Zeilenebene, Audit, Dateispeicher, Queues, Jobs, E-Mail, KI, Webhooks — deklarativ, bei Bedarf | - -## Worüber Sie die Kontrolle behalten - -| Asset | Wo es liegt | -|---|---| -| Geschäftsdaten | **Ihre** Datenbank (Postgres, SQLite, MySQL, MongoDB) | -| Benutzeridentitäten & Sitzungen | **Ihre** Datenbank | -| Audit-Log | **Ihre** Datenbank | -| Dateien | **Ihr** Speicher (lokale Festplatte, S3 oder S3-kompatibel wie R2/MinIO) | -| Secrets | **Ihr** Secret Manager | -| Die Laufzeitumgebung selbst | **Ihre** Server, Container oder Ihr Laptop | - -ObjectOS funkt niemals nach Hause. Keine Telemetrie. Kein Lizenzserver. -Air-Gapped-Netzwerke sind ein erstklassiges Deployment-Ziel — siehe -[Air-gapped](/docs/deploy/air-gapped). - -## Wohin als Nächstes - -| Wenn Sie … möchten | Lesen Sie | -|---|---| -| Sehen, wie es tatsächlich funktioniert | [Quickstart](/docs/quickstart) | -| Verstehen, was drinsteckt | [Architecture](/docs/architecture) | -| Es in Docker ausführen | [Docker](/docs/deploy/docker) | -| Auf Kubernetes deployen | [Kubernetes](/docs/deploy/kubernetes) | -| Es mit Postgres / Ihrer DB verbinden | [Runtime Configuration](/docs/configure/runtime) | -| SSO einrichten | [Authentication](/docs/configure/authentication) | -| Festlegen, wer was sieht | [Permissions](/docs/configure/permissions) | -| Es von einem anderen Dienst aus aufrufen | [API Access](/docs/configure/api-access) | -| Ereignisse an andere Systeme senden | [Webhooks](/docs/configure/webhooks) | -| In Produktion gehen | [Production Readiness](/docs/operate/production) | - -## Lizenz & Preise - -Die ObjectOS-Laufzeitumgebung ist **Apache-2.0** — die freizügigste -weit verbreitete OSS-Lizenz. Verwenden Sie sie in kommerziellen Produkten, -betten Sie sie ein, verteilen Sie sie weiter, behalten Sie Ihre Änderungen -privat. Keine Gebühr pro Sitzplatz, kein Lizenzserver, kein -"ab 50.000 $/Jahr". Optionaler kommerzieller Support und Managed Hosting -sind separat verfügbar — siehe [License](/docs/resources/license). diff --git a/content/docs/index.es.mdx b/content/docs/index.es.mdx deleted file mode 100644 index b316daa..0000000 --- a/content/docs/index.es.mdx +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: ObjectOS -description: El runtime para herramientas internas que permanece en tu red. Un solo comando para empezar; tu base de datos, tu autenticación, tus datos — nunca los nuestros. -translation: - source_sha: d8f6522ae3a04825e07a12e003ff4eb1247902133cc0bde24e2640d9e7259fd0 - guide_rev: 1 - mode: auto ---- - -**ObjectOS es un runtime autoalojado para crear herramientas internas, -paneles de administración y aplicaciones de back-office sin renunciar a -tus datos.** Describe lo que necesitas al AI Builder integrado en la -Console — o haz un fork de una plantilla — y obtén APIs REST, una UI de -administración generada, autenticación, RBAC, registros de auditoría, -almacenamiento de archivos, trabajos en segundo plano, webhooks e -integración con IA. Todo ejecutándose en tu red, sobre tu base de datos. - -Es lo que obtendrías si Retool, Supabase y Salesforce tuvieran un hijo -que se ejecutara dentro de tu firewall — con una IA que crea las -aplicaciones por ti. - -## Ponlo en marcha en 60 segundos - -```bash -npm i -g @objectstack/cli -os start -``` - -Abre **http://localhost:3000** y tendrás un ObjectOS funcional con -Console y Account, un registro de auditoría y una base de datos SQLite — -sin configuración, sin scaffolding. - -Luego, puedes: - -- **Hablar con el AI Builder** — *"Necesito hacer seguimiento de tickets - de soporte con prioridad y responsable asignado"* — y ver cómo se - generan los metadatos. Consulta - [Build → AI Builder](/docs/build/ai-builder). -- **Instalar una plantilla** desde el marketplace integrado en la Console - (Todo, Contracts, Helpdesk, …) y tener una aplicación real con un solo - clic. -- **Hacer un fork de una [plantilla](/docs/build/templates)** si quieres - el código fuente en TypeScript bajo tu control. - -## Por qué ObjectOS en lugar de … - -| Lo que usas | Punto de dolor | Lo que te ofrece ObjectOS | -|---|---|---| -| **Retool / Appsmith** | El constructor de UI es excelente, pero tus datos viven en su nube y sus precios escalan con los usuarios | Tus datos nunca salen de tu red; Apache-2.0, sin coste por asiento | -| **Supabase / Firebase** | El backend-as-a-service es rápido pero genera dependencia del proveedor; SaaS multitenant por diseño | La misma DX (APIs automáticas, autenticación, almacenamiento), pero tú eres dueño del runtime y la base de datos | -| **Salesforce / NetSuite** | Plataforma potente, personalización dolorosa, coste por asiento exorbitante | El mismo modelo orientado a metadatos (objetos, campos, roles, reglas de compartición), autoalojado, sin coste por asiento | -| **Construirlo tú mismo (Next + Prisma + NextAuth)** | Reconstruyes RBAC, auditoría, subida de archivos, ajustes, webhooks y trabajos cada vez | Despliega la lógica de negocio real; la infraestructura de la plataforma ya está lista | - -## Lo que obtienes de fábrica - -| Superficie | Qué es | -|---|---| -| **API REST automática** | Cada objeto que declaras obtiene `/api/v1/data/` con filtrado/ordenación/paginación | -| **Console** (`/_console/`) | UI de administración generada: explora y edita registros, gestiona usuarios/roles/conjuntos de permisos, consulta el registro de auditoría, sesiones, claves de API y ajustes | -| **Account** (`/_account/`) | Inicio de sesión, registro, restablecimiento de contraseña, OAuth, OIDC/SSO, passkeys, 2FA | -| **Más de 20 plugins** | RBAC + seguridad a nivel de fila, auditoría, almacenamiento de archivos, colas, trabajos, correo, IA, webhooks — declarativos y bajo demanda | - -## Sobre lo que mantienes el control - -| Activo | Dónde reside | -|---|---| -| Datos de negocio | **Tu** base de datos (Postgres, SQLite, MySQL, MongoDB) | -| Identidades de usuario y sesiones | **Tu** base de datos | -| Registro de auditoría | **Tu** base de datos | -| Archivos | **Tu** almacenamiento (disco local, S3 o compatible con S3 como R2/MinIO) | -| Secretos | **Tu** gestor de secretos | -| El runtime en sí | **Tus** servidores, contenedores o portátil | - -ObjectOS nunca se comunica con el exterior. Sin telemetría. Sin servidor -de licencias. Las redes aisladas (air-gapped) son un objetivo de -despliegue de primera clase — consulta -[Air-gapped](/docs/deploy/air-gapped). - -## A dónde ir a continuación - -| Si quieres … | Lee | -|---|---| -| Verlo funcionar de verdad | [Quickstart](/docs/quickstart) | -| Entender qué hay dentro | [Architecture](/docs/architecture) | -| Ejecutarlo en Docker | [Docker](/docs/deploy/docker) | -| Desplegarlo en Kubernetes | [Kubernetes](/docs/deploy/kubernetes) | -| Conectarlo a Postgres / tu BD | [Runtime Configuration](/docs/configure/runtime) | -| Configurar SSO | [Authentication](/docs/configure/authentication) | -| Restringir quién ve qué | [Permissions](/docs/configure/permissions) | -| Llamarlo desde otro servicio | [API Access](/docs/configure/api-access) | -| Enviar eventos a otros sistemas | [Webhooks](/docs/configure/webhooks) | -| Pasar a producción | [Production Readiness](/docs/operate/production) | - -## Licencia y precios - -El runtime de ObjectOS es **Apache-2.0** — la licencia OSS de uso -extendido más permisiva. Úsalo en productos comerciales, incrústalo, -redistribúyelo, mantén tus modificaciones privadas. Sin tarifa por -asiento, sin servidor de licencias, sin "desde 50.000 $/año". Hay -soporte comercial y alojamiento gestionado opcionales disponibles por -separado — consulta [License](/docs/resources/license). diff --git a/content/docs/index.fr.mdx b/content/docs/index.fr.mdx deleted file mode 100644 index d752132..0000000 --- a/content/docs/index.fr.mdx +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: ObjectOS -description: Le runtime des outils internes qui reste dans votre réseau. Une seule commande pour démarrer, votre base de données, votre authentification, vos données — jamais les nôtres. -translation: - source_sha: d8f6522ae3a04825e07a12e003ff4eb1247902133cc0bde24e2640d9e7259fd0 - guide_rev: 1 - mode: auto ---- - -**ObjectOS est un runtime auto-hébergé pour créer des outils internes, des -panneaux d'administration et des applications de back-office sans renoncer -à vos données.** Décrivez ce dont vous avez besoin à l'AI Builder intégré à -la Console — ou forkez un template — et obtenez des API REST, une interface -d'administration générée, l'authentification, le RBAC, des journaux d'audit, -le stockage de fichiers, des tâches en arrière-plan, des webhooks et -l'intégration de l'IA. Le tout s'exécutant dans votre réseau, sur votre base -de données. - -C'est ce que vous obtiendriez si Retool, Supabase et Salesforce avaient un -enfant qui s'exécutait à l'intérieur de votre pare-feu — avec une IA qui -construit les applications pour vous. - -## Opérationnel en 60 secondes - -```bash -npm i -g @objectstack/cli -os start -``` - -Ouvrez **http://localhost:3000** et vous disposez d'un ObjectOS fonctionnel -avec la Console et l'Account, un journal d'audit et une base de données -SQLite — zéro configuration, zéro échafaudage. - -Ensuite, au choix : - -- **Parlez à l'AI Builder** — *« J'ai besoin de suivre des tickets de support - avec une priorité et un destinataire assigné »* — et observez la génération - des métadonnées. Voir [Build → AI Builder](/docs/build/ai-builder). -- **Installez un template** depuis le marketplace intégré à la Console (Todo, - Contracts, Helpdesk, …) et obtenez une vraie application en un clic. -- **Forkez un [template](/docs/build/templates)** si vous voulez du code source - TypeScript sous votre contrôle. - -## Pourquoi ObjectOS plutôt que … - -| Vous utilisez | Point de friction | Ce qu'ObjectOS vous apporte | -|---|---|---| -| **Retool / Appsmith** | Le générateur d'interface est excellent, mais vos données résident dans leur cloud et leur tarification augmente avec le nombre d'utilisateurs | Vos données ne quittent jamais votre réseau ; Apache-2.0, sans taxe par siège | -| **Supabase / Firebase** | Le backend-as-a-service est rapide mais soumis au verrouillage fournisseur ; SaaS multi-tenant par conception | Même expérience développeur (API automatiques, authentification, stockage), mais vous possédez le runtime et la base de données | -| **Salesforce / NetSuite** | Plateforme puissante, personnalisation pénible, coût par siège exorbitant | Même modèle piloté par métadonnées (objets, champs, rôles, règles de partage), auto-hébergé, sans taxe par siège | -| **Tout reconstruire soi-même (Next + Prisma + NextAuth)** | Vous reconstruisez le RBAC, l'audit, le téléversement de fichiers, les paramètres, les webhooks et les tâches à chaque fois | Livrez la véritable logique métier ; la plomberie de la plateforme est déjà là | - -## Ce que vous obtenez d'emblée - -| Surface | De quoi il s'agit | -|---|---| -| **API REST automatique** | Chaque objet que vous déclarez obtient `/api/v1/data/` avec filtrage/tri/pagination | -| **Console** (`/_console/`) | Interface d'administration générée : parcourir et modifier les enregistrements, gérer les utilisateurs/rôles/ensembles de permissions, consulter le journal d'audit, les sessions, les clés API, les paramètres | -| **Account** (`/_account/`) | Connexion, inscription, réinitialisation du mot de passe, OAuth, OIDC/SSO, passkeys, 2FA | -| **Plus de 20 plugins** | RBAC + sécurité au niveau des lignes, audit, stockage de fichiers, files d'attente, tâches, e-mail, IA, webhooks — déclaratifs, à la demande | - -## Ce dont vous gardez le contrôle - -| Ressource | Où elle réside | -|---|---| -| Données métier | **Votre** base de données (Postgres, SQLite, MySQL, MongoDB) | -| Identités et sessions des utilisateurs | **Votre** base de données | -| Journal d'audit | **Votre** base de données | -| Fichiers | **Votre** stockage (disque local, S3 ou compatible S3 comme R2/MinIO) | -| Secrets | **Votre** gestionnaire de secrets | -| Le runtime lui-même | **Vos** serveurs, conteneurs ou ordinateur portable | - -ObjectOS ne communique jamais avec l'extérieur. Aucune télémétrie. Aucun -serveur de licence. Les réseaux isolés (air-gapped) sont une cible de -déploiement de premier ordre — voir [Air-gapped](/docs/deploy/air-gapped). - -## Où aller ensuite - -| Si vous voulez … | Lire | -|---|---| -| Le voir fonctionner concrètement | [Quickstart](/docs/quickstart) | -| Comprendre ce qu'il y a dans la boîte | [Architecture](/docs/architecture) | -| L'exécuter dans Docker | [Docker](/docs/deploy/docker) | -| Le déployer sur Kubernetes | [Kubernetes](/docs/deploy/kubernetes) | -| Le connecter à Postgres / votre base de données | [Runtime Configuration](/docs/configure/runtime) | -| Configurer le SSO | [Authentication](/docs/configure/authentication) | -| Verrouiller qui voit quoi | [Permissions](/docs/configure/permissions) | -| L'appeler depuis un autre service | [API Access](/docs/configure/api-access) | -| Envoyer des événements vers d'autres systèmes | [Webhooks](/docs/configure/webhooks) | -| Passer en production | [Production Readiness](/docs/operate/production) | - -## Licence et tarification - -Le runtime ObjectOS est sous **Apache-2.0** — la licence open source la plus -permissive et la plus largement utilisée. Utilisez-le dans des produits -commerciaux, intégrez-le, redistribuez-le, gardez vos modifications privées. -Aucun frais par siège, aucun serveur de licence, aucun « à partir de -50 000 $/an ». Un support commercial et un hébergement managé optionnels sont -disponibles séparément — voir [License](/docs/resources/license). diff --git a/content/docs/index.ja.mdx b/content/docs/index.ja.mdx deleted file mode 100644 index 5b68e67..0000000 --- a/content/docs/index.ja.mdx +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: ObjectOS -description: ネットワーク内にとどまる社内ツール向けランタイム。1つのコマンドで起動でき、データベースも認証もデータもすべてあなたのもの——決して私たちのものにはなりません。 -translation: - source_sha: d8f6522ae3a04825e07a12e003ff4eb1247902133cc0bde24e2640d9e7259fd0 - guide_rev: 1 - mode: auto ---- - -**ObjectOS は、データを手放すことなく社内ツール、管理パネル、バックオフィスアプリを構築するためのセルフホスト型ランタイムです。** 必要なものを Console 内の AI Builder に説明する——あるいはテンプレートをフォークする——だけで、REST API、生成された管理 UI、認証、RBAC、監査ログ、ファイルストレージ、バックグラウンドジョブ、Webhook、AI 連携が手に入ります。すべてはあなたのネットワーク内で、あなたのデータベース上で動作します。 - -これは、Retool と Supabase と Salesforce の子どもがあなたのファイアウォールの内側で動くようなもの——しかもアプリをあなたの代わりに構築する AI 付きです。 - -## 60 秒で起動 - -```bash -npm i -g @objectstack/cli -os start -``` - -**http://localhost:3000** を開けば、Console と Account、監査ログ、SQLite データベースを備えた稼働中の ObjectOS が手に入ります——設定不要、スキャフォールディング不要です。 - -そのうえで、次のいずれかを行えます。 - -- **AI Builder に話しかける**——*「優先度と担当者付きでサポートチケットを管理したい」*——と、メタデータが生成される様子を見られます。[Build → AI Builder](/docs/build/ai-builder) を参照してください。 -- Console 内の marketplace から **テンプレートをインストール**する（Todo、Contracts、Helpdesk、…）と、ワンクリックで実際のアプリが動きます。 -- 自分の管理下に TypeScript ソースを置きたい場合は、**[テンプレート](/docs/build/templates)をフォーク**します。 - -## なぜ … ではなく ObjectOS なのか - -| 利用中のもの | 課題 | ObjectOS が提供するもの | -|---|---|---| -| **Retool / Appsmith** | UI ビルダーは優れているが、データは彼らのクラウドに置かれ、料金はユーザー数に応じて増加する | データがネットワークから出ることはなく、Apache-2.0、シート課金もなし | -| **Supabase / Firebase** | Backend-as-a-Service は高速だがベンダーロックインされる。設計上マルチテナント SaaS である | 同等の DX（自動 API、認証、ストレージ）でありながら、ランタイムとデータベースはあなたが所有する | -| **Salesforce / NetSuite** | 強力なプラットフォームだが、カスタマイズが苦痛で、シート単価が目を見張るほど高い | 同じメタデータ駆動モデル（オブジェクト、フィールド、ロール、共有ルール）をセルフホストで、シート課金なし | -| **自前構築（Next + Prisma + NextAuth）** | RBAC、監査、ファイルアップロード、設定、Webhook、ジョブを毎回作り直す | 実際のビジネスロジックを出荷できる。プラットフォームの配管はすでに整っている | - -## すぐに使える機能 - -| 機能領域 | 概要 | -|---|---| -| **自動 REST API** | 宣言したすべてのオブジェクトに、フィルター/ソート/ページネーション付きの `/api/v1/data/` が用意される | -| **Console** (`/_console/`) | 生成された管理 UI：レコードの閲覧と編集、ユーザー/ロール/権限セットの管理、監査ログ・セッション・API キー・設定の表示 | -| **Account** (`/_account/`) | ログイン、登録、パスワードリセット、OAuth、OIDC/SSO、パスキー、2FA | -| **20 以上のプラグイン** | RBAC + 行レベルセキュリティ、監査、ファイルストレージ、キュー、ジョブ、メール、AI、Webhook——宣言的に、必要に応じて | - -## あなたが制御し続けるもの - -| 資産 | 保管場所 | -|---|---| -| 業務データ | **あなたの**データベース（Postgres、SQLite、MySQL、MongoDB） | -| ユーザー ID とセッション | **あなたの**データベース | -| 監査ログ | **あなたの**データベース | -| ファイル | **あなたの**ストレージ（ローカルディスク、S3、または R2/MinIO のような S3 互換ストレージ） | -| シークレット | **あなたの**シークレットマネージャー | -| ランタイムそのもの | **あなたの**サーバー、コンテナ、またはノート PC | - -ObjectOS が外部に通信することはありません。テレメトリーなし。ライセンスサーバーなし。エアギャップネットワークは第一級のデプロイ対象です——[エアギャップ](/docs/deploy/air-gapped)を参照してください。 - -## 次に読むべきもの - -| やりたいこと | 読むべきもの | -|---|---| -| 実際の動作を見る | [クイックスタート](/docs/quickstart) | -| 中身を理解する | [アーキテクチャ](/docs/architecture) | -| Docker で実行する | [Docker](/docs/deploy/docker) | -| Kubernetes にデプロイする | [Kubernetes](/docs/deploy/kubernetes) | -| Postgres / 自分の DB に接続する | [ランタイム構成](/docs/configure/runtime) | -| SSO を設定する | [認証](/docs/configure/authentication) | -| 誰が何を見られるかを制限する | [権限](/docs/configure/permissions) | -| 別のサービスから呼び出す | [API アクセス](/docs/configure/api-access) | -| 他システムへイベントを送信する | [Webhook](/docs/configure/webhooks) | -| 本番環境へ移行する | [本番運用への準備](/docs/operate/production) | - -## ライセンスと料金 - -ObjectOS ランタイムは **Apache-2.0**——広く使われている OSS ライセンスの中で最も寛容なものです。商用製品で利用する、組み込む、再配布する、変更内容を非公開にしておく——いずれも可能です。シート単価なし、ライセンスサーバーなし、「年間 5 万ドルから」もありません。オプションの商用サポートとマネージドホスティングは別途提供しています——[ライセンス](/docs/resources/license)を参照してください。 diff --git a/content/docs/index.ko.mdx b/content/docs/index.ko.mdx deleted file mode 100644 index 9867b03..0000000 --- a/content/docs/index.ko.mdx +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: ObjectOS -description: 네트워크 안에 머무는 내부 도구용 런타임. 한 번의 명령으로 시작하며, 데이터베이스도, 인증도, 데이터도 모두 당신의 것 — 결코 우리의 것이 아닙니다. -translation: - source_sha: d8f6522ae3a04825e07a12e003ff4eb1247902133cc0bde24e2640d9e7259fd0 - guide_rev: 1 - mode: auto ---- - -**ObjectOS는 데이터를 포기하지 않고 내부 도구, 관리자 패널, 백오피스 앱을 -구축할 수 있는 셀프 호스팅 런타임입니다.** Console 내장 AI Builder에 -필요한 것을 설명하거나 템플릿을 포크하면, REST API, 자동 생성된 관리자 -UI, 인증, RBAC, 감사 로그, 파일 저장소, 백그라운드 작업, 웹훅, AI 통합을 -얻을 수 있습니다. 이 모든 것이 당신의 네트워크에서, 당신의 데이터베이스 -위에서 실행됩니다. - -이는 Retool, Supabase, Salesforce가 자녀를 낳아 그 자녀가 당신의 방화벽 -안에서 실행되는 것과 같습니다 — 게다가 앱을 대신 만들어 주는 AI까지 -딸려 있습니다. - -## 60초 만에 실행하기 - -```bash -npm i -g @objectstack/cli -os start -``` - -**http://localhost:3000** 을 열면 Console와 Account, 감사 로그, 그리고 -SQLite 데이터베이스를 갖춘 작동하는 ObjectOS가 준비됩니다 — 구성도, -스캐폴딩도 전혀 필요 없습니다. - -그런 다음 다음 중 하나를 하면 됩니다. - -- **AI Builder와 대화하세요** — *"우선순위와 담당자가 있는 지원 - 티켓을 추적해야 합니다"* — 그러면 메타데이터가 생성되는 것을 지켜볼 - 수 있습니다. [Build → AI Builder](/docs/build/ai-builder)를 참고하세요. -- Console 내장 marketplace에서 **템플릿을 설치하세요**(Todo, - Contracts, Helpdesk 등). 한 번의 클릭으로 실제 앱을 갖출 수 있습니다. -- TypeScript 소스를 직접 관리하고 싶다면 - **[템플릿](/docs/build/templates)을 포크하세요**. - -## 왜 다른 것이 아니라 ObjectOS인가 … - -| 현재 사용 중인 것 | 불편한 점 | ObjectOS가 제공하는 것 | -|---|---|---| -| **Retool / Appsmith** | UI 빌더는 훌륭하지만 데이터가 그들의 클라우드에 있고 가격이 사용자 수에 따라 늘어납니다 | 데이터가 네트워크를 절대 벗어나지 않습니다. Apache-2.0이며 좌석당 과금이 없습니다 | -| **Supabase / Firebase** | 백엔드 서비스(BaaS)는 빠르지만 벤더에 종속되며 설계상 멀티테넌트 SaaS입니다 | 동일한 개발자 경험(자동 API, 인증, 저장소)을 제공하지만 런타임과 데이터베이스를 당신이 소유합니다 | -| **Salesforce / NetSuite** | 강력한 플랫폼이지만 커스터마이징이 고통스럽고 좌석당 비용이 눈물이 날 정도입니다 | 동일한 메타데이터 기반 모델(객체, 필드, 역할, 공유 규칙)을 셀프 호스팅으로 제공하며 좌석당 과금이 없습니다 | -| **직접 구축(Next + Prisma + NextAuth)** | 매번 RBAC, 감사, 파일 업로드, 설정, 웹훅, 작업을 다시 만들어야 합니다 | 실제 비즈니스 로직만 출시하면 됩니다. 플랫폼 기반 작업은 이미 마련되어 있습니다 | - -## 기본으로 제공되는 것 - -| 영역 | 무엇인가 | -|---|---| -| **자동 REST API** | 선언하는 모든 객체에 필터/정렬/페이지네이션이 가능한 `/api/v1/data/`가 생깁니다 | -| **Console** (`/_console/`) | 자동 생성된 관리자 UI: 레코드 조회 및 편집, 사용자/역할/권한 집합 관리, 감사 로그·세션·API 키·설정 보기 | -| **Account** (`/_account/`) | 로그인, 회원가입, 비밀번호 재설정, OAuth, OIDC/SSO, 패스키, 2FA | -| **20개 이상의 플러그인** | RBAC + 행 수준 보안, 감사, 파일 저장소, 큐, 작업, 이메일, AI, 웹훅 — 선언적이며 필요에 따라 사용 | - -## 당신이 계속 통제하는 것 - -| 자산 | 어디에 있는가 | -|---|---| -| 비즈니스 데이터 | **당신의** 데이터베이스(Postgres, SQLite, MySQL, MongoDB) | -| 사용자 신원 및 세션 | **당신의** 데이터베이스 | -| 감사 로그 | **당신의** 데이터베이스 | -| 파일 | **당신의** 저장소(로컬 디스크, S3, 또는 R2/MinIO 같은 S3 호환 저장소) | -| 비밀 값 | **당신의** 시크릿 매니저 | -| 런타임 자체 | **당신의** 서버, 컨테이너, 또는 노트북 | - -ObjectOS는 절대 외부로 연결을 시도하지 않습니다. 텔레메트리도, 라이선스 -서버도 없습니다. 에어갭(air-gapped) 네트워크는 일급 배포 대상입니다 — -[Air-gapped](/docs/deploy/air-gapped)를 참고하세요. - -## 다음으로 갈 곳 - -| 하고 싶은 것 … | 읽을 문서 | -|---|---| -| 실제로 작동하는 모습 보기 | [Quickstart](/docs/quickstart) | -| 내부에 무엇이 있는지 이해하기 | [Architecture](/docs/architecture) | -| Docker로 실행하기 | [Docker](/docs/deploy/docker) | -| Kubernetes에 배포하기 | [Kubernetes](/docs/deploy/kubernetes) | -| Postgres / 당신의 DB에 연결하기 | [Runtime Configuration](/docs/configure/runtime) | -| SSO 설정하기 | [Authentication](/docs/configure/authentication) | -| 누가 무엇을 볼지 잠그기 | [Permissions](/docs/configure/permissions) | -| 다른 서비스에서 호출하기 | [API Access](/docs/configure/api-access) | -| 다른 시스템으로 이벤트 보내기 | [Webhooks](/docs/configure/webhooks) | -| 프로덕션으로 가기 | [Production Readiness](/docs/operate/production) | - -## 라이선스 및 가격 - -ObjectOS 런타임은 **Apache-2.0**입니다 — 가장 널리 쓰이는 관대한 OSS -라이선스입니다. 상업용 제품에 사용하고, 임베드하고, 재배포하고, 수정 -사항을 비공개로 유지할 수 있습니다. 좌석당 요금도, 라이선스 서버도, "연 -$50K부터 시작" 같은 것도 없습니다. 선택적 상업 지원 및 관리형 호스팅은 -별도로 제공됩니다 — [License](/docs/resources/license)를 참고하세요. diff --git a/content/docs/index.mdx b/content/docs/index.mdx index 114b308..26b9c65 100644 --- a/content/docs/index.mdx +++ b/content/docs/index.mdx @@ -1,30 +1,32 @@ --- -title: ObjectOS -description: The runtime for internal tools that stays in your network. One command to start, your database, your auth, your data — never ours. +title: Introduction +description: "The ontology is the software. One executable business ontology. AI writes it, the runtime runs it, agents operate it, you own it. Want the same loop hosted, in the browser, nothing to install? That's ObjectOS, the commercial runtime environment built on ObjectStack. ObjectOS runs hosted in the browser with nothing to install (ObjectOS Cloud) or self-managed on your own infrastructure (ObjectOS Enterprise), and on either edition you can export your ontology and run it on the open-source ObjectStack runtime." --- -**ObjectOS is a self-hosted runtime for building internal tools, admin -panels, and back-office apps without giving up your data.** Describe -what you need to the built-in AI Builder — or fork a template — and -get REST APIs, a generated admin UI, authentication, RBAC, audit logs, -file storage, background jobs, webhooks, and AI integration. All -running in your network, on your database. +Describe what the business needs to the built-in +[AI Builder](/docs/build/ai-builder) — a helpdesk, an approval flow, a CRM +— or install a template, and the ontology it writes is live at once: REST +APIs, generated screens, authentication, RBAC, audit logs, file storage, +background jobs, webhooks, and every object exposed as an MCP tool your +agents can call. Each change is a small, readable diff that a person +approves before it runs. -It's what you'd get if Retool, Supabase, and Salesforce had a child -that ran inside your firewall — with an AI that builds the apps for you. +The open-source (Apache-2.0) +[ObjectStack](https://github.com/objectstack-ai/objectstack) stack — +protocol, kernel, CLI and production runtime — is what executes the +ontology and what ObjectOS is built on. Everything you build on ObjectOS is +ordinary ObjectStack metadata, so it is portable to that runtime by +construction. -## Get running in 60 seconds +## Start -```bash -npm i -g @objectstack/cli -os start -``` - -Open **http://localhost:3000** and you have a working ObjectOS with -its UI and Account portal, an audit log, and a SQLite database — zero -configuration, zero scaffolding. +| You want … | Do this | +|---|---| +| ObjectOS, nothing to install | Sign in to **[ObjectOS Cloud](https://www.objectos.ai)** — the Free plan is enough to build your first app | +| ObjectOS on your own infrastructure | **ObjectOS Enterprise** (or Business Self-Managed) runs the licensed runtime image on your servers — see [License & Pricing](/docs/resources/license) and [Deployment](/docs/deploy) | +| The open runtime, locally, free | That is ObjectStack, not ObjectOS: `npm i -g @objectstack/cli && os start` boots it with a SQLite database and no configuration — see [Quickstart](/docs/quickstart) | -Then either: +Either ObjectOS edition then takes you to the same place — sign in, and: - **Talk to the AI Builder** — *"I need to track support tickets with priority and assignee"* — and watch the metadata get generated. See @@ -32,15 +34,16 @@ Then either: - **Install a template** from the built-in marketplace (Todo, Contracts, Helpdesk, …) and have a real app in one click. - **Fork a [template](/docs/build/templates)** if you want TypeScript - source under your control. + source under your control — the same metadata, authored in your repo + with your coding agent. ## Why ObjectOS instead of … | You're using | Pain point | What ObjectOS gives you | |---|---|---| -| **Retool / Appsmith** | UI builder is great, but your data sits in their cloud and their pricing scales with users | Your data never leaves your network; open-source foundation (ObjectStack, Apache-2.0), no seat tax | -| **Supabase / Firebase** | Backend-as-a-service is fast but vendor-locked; multi-tenant SaaS by design | Same DX (auto APIs, auth, storage), but you own the runtime and database | -| **Salesforce / NetSuite** | Powerful platform, painful customization, eye-watering per-seat cost | Same metadata-driven model (objects, fields, roles, sharing rules), self-hosted, no seat tax | +| **Retool / Appsmith** | UI builder is great, but your data sits in their cloud and their pricing scales with users | Hosted (ObjectOS Cloud) or inside your network (ObjectOS Enterprise); built on open-source ObjectStack (Apache-2.0), so the ontology is yours to export; no seat tax — AI seats only | +| **Supabase / Firebase** | Backend-as-a-service is fast but vendor-locked; multi-tenant SaaS by design | Same DX (auto APIs, auth, storage), but the definition is yours: export it and run it on the open ObjectStack runtime, or run ObjectOS Enterprise on your own database | +| **Salesforce / NetSuite** | Powerful platform, painful customization, eye-watering per-seat cost | Same metadata-driven model (objects, fields, roles, sharing rules), hosted or self-managed, no seat tax — viewers and non-AI users are free | | **Rolling your own (Next + Prisma + NextAuth)** | You rebuild RBAC, audit, file uploads, settings, webhooks, jobs every time | Ship the actual business logic; the platform plumbing is already there | ## What you get out of the box @@ -52,7 +55,12 @@ Then either: | **Account** ([inside the UI](/docs/resources/glossary#surface)) | Login, register, password reset, OAuth, OIDC/SSO, passkeys, 2FA | | **20+ plugins** | RBAC + row-level security, audit, file storage, queues, jobs, email, AI, webhooks — declarative, on demand | -## What you keep control of +## What stays yours + +On either edition, the ontology: your objects, fields, relations, actions, +permissions, flows and agent definitions are ordinary ObjectStack metadata, +and you can export them and run them on the open-source ObjectStack +runtime. On **ObjectOS Enterprise**, everything else stays with you too: | Asset | Where it lives | |---|---| @@ -61,10 +69,11 @@ Then either: | Audit log | **Your** database | | Files | **Your** storage (local disk, S3, or S3-compatible like R2/MinIO) | | Secrets | **Your** secret manager | -| The runtime itself | **Your** servers, containers, or laptop | +| The runtime itself | **Your** servers or containers | -ObjectOS never phones home. No telemetry. No license server. Air-gapped -networks are a first-class deployment target — see +Self-managed ObjectOS validates its licence online; Enterprise air-gapped +licences validate offline, so a network with no internet access is a +first-class Enterprise deployment target — see [Air-gapped](/docs/deploy/air-gapped). ## Find your docs @@ -82,6 +91,7 @@ matches how you use ObjectOS: | If you want to … | Read | |---|---| +| Start without installing anything | [ObjectOS Cloud](https://www.objectos.ai) | | See it actually work | [Quickstart](/docs/quickstart) | | Understand what's inside the box | [Architecture](/docs/architecture) | | Run it in Docker | [Docker](/docs/deploy/docker) | diff --git a/content/docs/index.zh-Hans.mdx b/content/docs/index.zh-Hans.mdx deleted file mode 100644 index c7f1dad..0000000 --- a/content/docs/index.zh-Hans.mdx +++ /dev/null @@ -1,87 +0,0 @@ ---- -title: ObjectOS -description: 留在你网络内的内部工具运行时。一条命令启动，你的数据库、你的认证、你的数据 —— 永远不归我们所有。 -translation: - source_sha: efeebee6085cb07619dc92dcba84bc59eb43037c3dd7ebfab29006dc0a4903e1 - guide_rev: 1 - mode: auto ---- - -**ObjectOS 是一个自托管运行时，用于构建内部工具、管理后台和后办公应用，且不必交出你的数据。** 向 Console 内置的 AI Builder 描述你要的东西 —— 或者 fork 一个模板 —— 你就能得到 REST API、生成的管理 UI、认证、RBAC、审计日志、文件存储、后台任务、Webhook 和 AI 集成。所有这些都运行在你的网络中，使用你的数据库。 - -如果 Retool、Supabase 和 Salesforce 生了一个孩子并让它运行在你的防火墙内 —— 由 AI 替你构建应用 —— 那大概就是它的样子。 - -## 60 秒内启动 - -```bash -npm i -g @objectstack/cli -os start -``` - -打开 **http://localhost:3000**，你就拥有了一个可工作的 ObjectOS，包含 Console、Account、审计日志和一个 SQLite 数据库 —— 零配置、零脚手架。 - -然后你可以： - -- **与 AI Builder 对话** —— *"我需要追踪支持工单，包含优先级和负责人"* —— 看着元数据被生成。参见 [Build → AI Builder](/docs/build/ai-builder)。 -- 从 Console 内置市场**安装模板**（Todo、Contracts、Helpdesk……），一键就能拥有一个真实可用的应用。 -- 如果你想要 TypeScript 源码归你控制，可以 **fork 一个 [模板](/docs/build/templates)**。 - -## 为什么选 ObjectOS 而不是 …… - -| 你在用 | 痛点 | ObjectOS 给你的 | -|---|---|---| -| **Retool / Appsmith** | UI 构建器很好，但你的数据在他们的云上，价格随用户数膨胀 | 数据从不离开你的网络；Apache-2.0，无人头税 | -| **Supabase / Firebase** | BaaS 很快但被供应商锁定；本质上是多租户 SaaS | 同样的 DX（自动 API、认证、存储），但你拥有运行时和数据库 | -| **Salesforce / NetSuite** | 平台强大，定制痛苦，每席位成本惊人 | 同样的元数据驱动模型（对象、字段、角色、共享规则），自托管，无人头税 | -| **自己造轮子（Next + Prisma + NextAuth）** | 你每次都在重新实现 RBAC、审计、文件上传、设置、Webhook、任务 | 直接写业务逻辑；平台底座已就绪 | - -## 开箱即用 - -| 入口 | 是什么 | -|---|---| -| **自动 REST API** | 你声明的每个对象都自动获得 `/api/v1/data/`，支持过滤/排序/分页 | -| **Console** (`/_console/`) | 生成的管理 UI:浏览/编辑记录,管理用户/角色/权限集,查看审计日志、会话、API Key、设置 | -| **Account** (`/_account/`) | 登录、注册、密码重置、OAuth、OIDC/SSO、Passkey、2FA | -| **23 个插件** | RBAC + 行级安全、审计、文件存储、队列、任务、邮件、AI、Webhook —— 声明式、按需启用 | - -## 你保留控制的部分 - -| 资产 | 存放位置 | -|---|---| -| 业务数据 | **你的**数据库（Postgres、SQLite、MySQL、Turso、MongoDB） | -| 用户身份与会话 | **你的**数据库 | -| 审计日志 | **你的**数据库 | -| 文件 | **你的**存储（本地磁盘、S3、R2） | -| 密钥 | **你的**密钥管理器 | -| 运行时本身 | **你的**服务器、容器或笔记本 | - -ObjectOS 从不回传数据。无遥测。无授权服务器。气隙网络是头等部署目标 —— 参见 [Air-gapped](/docs/deploy/air-gapped)。 - -## 按角色找文档 - -本文档服务三类人群 —— 从与你使用 ObjectOS 的方式匹配的部分开始： - -| 你是… | 你想… | 从这里开始 | -|---|---|---| -| **普通用户** | 在应用中工作：记录、视图、仪表盘、审批 | [使用](/docs/use) | -| **构建者** | 创建应用：数据模型、界面、自动化、AI Agent | [构建](/docs/build) | -| **管理员** | 运行平台：用户、权限、设置、部署 | [管理](/docs/configure)、[部署](/docs/deploy)、[运维](/docs/operate/production) | - -## 下一步去哪里 - -| 如果你想…… | 阅读 | -|---|---| -| 看它真正运行起来 | [Quickstart](/docs/quickstart) | -| 理解盒子里有什么 | [Architecture](/docs/architecture) | -| 用 Docker 运行 | [Docker](/docs/deploy/docker) | -| 部署到 Kubernetes | [Kubernetes](/docs/deploy/kubernetes) | -| 接到 Postgres / 你的数据库 | [Runtime Configuration](/docs/configure/runtime) | -| 配置 SSO | [Authentication](/docs/configure/authentication) | -| 锁定谁能看到什么 | [Permissions](/docs/configure/permissions) | -| 从另一个服务调用它 | [API Access](/docs/configure/api-access) | -| 向其他系统发送事件 | [Webhooks](/docs/configure/webhooks) | -| 上线生产 | [Production Readiness](/docs/operate/production) | - -## 许可与定价 - -ObjectOS 是构建在开源（Apache-2.0）**[ObjectStack 框架](https://github.com/objectstack-ai/objectstack)** 之上的**商业产品** —— 框架可免费用于商业产品、可嵌入、可自托管，没有按席位收费，也没有许可证服务器。ObjectOS 在其上增加内嵌的界面内 AI、治理与官方运维，**仅按 AI 席位**计价（只读用户与不使用 AI 的用户免费）—— 没有 "起价 5 万美元/年"。参见 [许可与定价](/docs/resources/license)。 diff --git a/content/docs/index.zh-Hant.mdx b/content/docs/index.zh-Hant.mdx deleted file mode 100644 index 4af78fc..0000000 --- a/content/docs/index.zh-Hant.mdx +++ /dev/null @@ -1,88 +0,0 @@ ---- -# @generated zh-Hant from zh-Hans -- do not edit. Edit the English source, then regenerate: pnpm --filter @objectos/docs gen:zh-hant -title: ObjectOS -description: 留在你網路內的內部工具執行時。一條命令啟動，你的資料庫、你的認證、你的資料 —— 永遠不歸我們所有。 -translation: - source_sha: efeebee6085cb07619dc92dcba84bc59eb43037c3dd7ebfab29006dc0a4903e1 - guide_rev: 1 - mode: auto ---- - -**ObjectOS 是一個自託管執行時，用於構建內部工具、管理後臺和後辦公應用，且不必交出你的資料。** 向 Console 內建的 AI Builder 描述你要的東西 —— 或者 fork 一個模板 —— 你就能得到 REST API、生成的管理 UI、認證、RBAC、審計日誌、檔案儲存、後臺任務、Webhook 和 AI 整合。所有這些都執行在你的網路中，使用你的資料庫。 - -如果 Retool、Supabase 和 Salesforce 生了一個孩子並讓它執行在你的防火牆內 —— 由 AI 替你構建應用 —— 那大概就是它的樣子。 - -## 60 秒內啟動 - -```bash -npm i -g @objectstack/cli -os start -``` - -開啟 **http://localhost:3000**，你就擁有了一個可工作的 ObjectOS，包含 Console、Account、審計日誌和一個 SQLite 資料庫 —— 零配置、零腳手架。 - -然後你可以： - -- **與 AI Builder 對話** —— *"我需要追蹤支援工單，包含優先順序和負責人"* —— 看著後設資料被生成。參見 [Build → AI Builder](/docs/build/ai-builder)。 -- 從 Console 內建市場**安裝模板**（Todo、Contracts、Helpdesk……），一鍵就能擁有一個真實可用的應用。 -- 如果你想要 TypeScript 原始碼歸你控制，可以 **fork 一個 [模板](/docs/build/templates)**。 - -## 為什麼選 ObjectOS 而不是 …… - -| 你在用 | 痛點 | ObjectOS 給你的 | -|---|---|---| -| **Retool / Appsmith** | UI 構建器很好，但你的資料在他們的雲上，價格隨使用者數膨脹 | 資料從不離開你的網路；Apache-2.0，無人頭稅 | -| **Supabase / Firebase** | BaaS 很快但被供應商鎖定；本質上是多租戶 SaaS | 同樣的 DX（自動 API、認證、儲存），但你擁有執行時和資料庫 | -| **Salesforce / NetSuite** | 平臺強大，定製痛苦，每席位成本驚人 | 同樣的後設資料驅動模型（物件、欄位、角色、共享規則），自託管，無人頭稅 | -| **自己造輪子（Next + Prisma + NextAuth）** | 你每次都在重新實現 RBAC、審計、檔案上傳、設定、Webhook、任務 | 直接寫業務邏輯；平臺底座已就緒 | - -## 開箱即用 - -| 入口 | 是什麼 | -|---|---| -| **自動 REST API** | 你宣告的每個物件都自動獲得 `/api/v1/data/`，支援過濾/排序/分頁 | -| **Console** (`/_console/`) | 生成的管理 UI:瀏覽/編輯記錄,管理使用者/角色/許可權集,檢視審計日誌、會話、API Key、設定 | -| **Account** (`/_account/`) | 登入、註冊、密碼重置、OAuth、OIDC/SSO、Passkey、2FA | -| **23 個外掛** | RBAC + 行級安全、審計、檔案儲存、佇列、任務、郵件、AI、Webhook —— 宣告式、按需啟用 | - -## 你保留控制的部分 - -| 資產 | 存放位置 | -|---|---| -| 業務資料 | **你的**資料庫（Postgres、SQLite、MySQL、Turso、MongoDB） | -| 使用者身份與會話 | **你的**資料庫 | -| 審計日誌 | **你的**資料庫 | -| 檔案 | **你的**儲存（本地磁碟、S3、R2） | -| 金鑰 | **你的**金鑰管理器 | -| 執行時本身 | **你的**伺服器、容器或筆記本 | - -ObjectOS 從不回傳資料。無遙測。無授權伺服器。氣隙網路是頭等部署目標 —— 參見 [Air-gapped](/docs/deploy/air-gapped)。 - -## 按角色找文件 - -本文件服務三類人群 —— 從與你使用 ObjectOS 的方式匹配的部分開始： - -| 你是… | 你想… | 從這裡開始 | -|---|---|---| -| **普通使用者** | 在應用中工作：記錄、檢視、儀表盤、審批 | [使用](/docs/use) | -| **構建者** | 建立應用：資料模型、介面、自動化、AI Agent | [構建](/docs/build) | -| **管理員** | 執行平臺：使用者、許可權、設定、部署 | [管理](/docs/configure)、[部署](/docs/deploy)、[運維](/docs/operate/production) | - -## 下一步去哪裡 - -| 如果你想…… | 閱讀 | -|---|---| -| 看它真正執行起來 | [Quickstart](/docs/quickstart) | -| 理解盒子裡有什麼 | [Architecture](/docs/architecture) | -| 用 Docker 執行 | [Docker](/docs/deploy/docker) | -| 部署到 Kubernetes | [Kubernetes](/docs/deploy/kubernetes) | -| 接到 Postgres / 你的資料庫 | [Runtime Configuration](/docs/configure/runtime) | -| 配置 SSO | [Authentication](/docs/configure/authentication) | -| 鎖定誰能看到什麼 | [Permissions](/docs/configure/permissions) | -| 從另一個服務呼叫它 | [API Access](/docs/configure/api-access) | -| 向其他系統傳送事件 | [Webhooks](/docs/configure/webhooks) | -| 上線生產 | [Production Readiness](/docs/operate/production) | - -## 許可與定價 - -ObjectOS 是構建在開源（Apache-2.0）**[ObjectStack 框架](https://github.com/objectstack-ai/objectstack)** 之上的**商業產品** —— 框架可免費用於商業產品、可嵌入、可自託管，沒有按席位收費，也沒有許可證伺服器。ObjectOS 在其上增加內嵌的介面內 AI、治理與官方運維，**僅按 AI 席位**計價（只讀使用者與不使用 AI 的使用者免費）—— 沒有 "起價 5 萬美元/年"。參見 [許可與定價](/docs/resources/license)。 diff --git a/content/docs/quickstart.de.mdx b/content/docs/quickstart.de.mdx deleted file mode 100644 index 7993701..0000000 --- a/content/docs/quickstart.de.mdx +++ /dev/null @@ -1,235 +0,0 @@ ---- -title: Schnellstart -description: Von null zu einem laufenden ObjectOS — eine CLI installieren, einen Befehl ausführen, schon haben Sie eine App. -translation: - source_sha: a9f996909d21e0b4b2f159dbe4a631f1c74b49fc9aa6ede2fa2866df598fe4bc - guide_rev: 1 - mode: auto ---- - -Es gibt zwei Möglichkeiten zu starten, je nachdem, was Sie vorhaben. - -| Sie sind … | Hier starten | -|---|---| -| Sie testen ObjectOS zum ersten Mal oder betreiben es in der Produktion | [Pfad A — `os start`](#path-a--os-start-operator-first-time-evaluator) | -| Sie entwickeln oder passen eine App im Code an | [Pfad B — `os init`](#path-b--os-init-developer) | - -Beide erzeugen einen laufenden Server mit Console + Account. Der -Unterschied besteht darin, ob Sie Quelldateien als Gerüst erstellen. - -## Voraussetzungen - -- **Node.js 20 oder neuer** — `node --version` -- Ein Terminal - -Das war's. Kein Docker. Keine Datenbank. Keine Kontoregistrierung. - ---- - -## Pfad A — `os start` (Operator / erstmaliger Tester) - -Installieren Sie die CLI global und führen Sie sie dann aus: - -```bash -npm i -g @objectstack/cli -os start -``` - -Sie sehen: - -```text -◆ ObjectStack -──────────────────────────────────────── -🏠 Home: ~/.objectstack -📦 Artifact: none (empty kernel — install apps via Console marketplace) -🗄️ Database: file:~/.objectstack/data/objectstack.db - - ✓ Server is ready - - ➜ API: http://localhost:3000/ - ➜ Console: http://localhost:3000/_console/ - ➜ Account: http://localhost:3000/_account/ - ➜ Console: http://localhost:3000/_console/ - - Plugins: 23 loaded -``` - -Das war's. Sie betreiben jetzt ObjectOS. - -### Was läuft - -| URL | Was es ist | -|---|---| -| http://localhost:3000/_account/register | Erstellen Sie Ihr erstes Konto | -| http://localhost:3000/_console/ | Die Admin-Oberfläche — und der **App-marketplace** | -| http://localhost:3000/_console/ | Benutzer, Rollen, Audit-Log, Einstellungen | -| http://localhost:3000/health | Liveness-Probe | - -Die Laufzeitumgebung startet in einem **leeren Kernel** — keine Objekte, keine Apps — -und stellt den marketplace bereit, sodass Sie fertige Apps in -Sekunden installieren können. - -### Per Chat erstellen — der AI Builder - -Sobald Sie angemeldet sind, öffnen Sie den KI-Assistenten in der Console (Funkel-Symbol -oben rechts) und beschreiben Sie, was Sie benötigen: - -> *„Ich muss Kundensupport-Tickets verfolgen. Jedes hat einen Betreff, -> eine Beschreibung, eine Priorität (niedrig/mittel/hoch/dringend), einen Status und -> einen Bearbeiter. Füge eine Kanban-Ansicht hinzu, gruppiert nach Status."* - -Die KI schlägt einen Plan vor, Sie genehmigen ihn, und die Metadaten sind aktiv — -REST-Endpunkte, Console-Ansichten, Audit-Log-Einträge, Berechtigungsschranken. -Keine Datei bearbeitet, kein Neustart. Siehe [Build → AI Builder](/docs/build/ai-builder) -für das vollständige Vokabular. - -> **Handcodierung in Ihrer IDE?** Führen Sie `npx skills add objectstack-ai/objectstack/skills` aus, -> um Claude Code / Cursor / Copilot / Codex beizubringen, wie man -> ObjectOS-Metadaten gegen die echten Zod-Schemas verfasst. Siehe -> [Build → IDE Skills](/docs/build/ai-skills). - -### Eine App aus dem marketplace installieren - -Öffnen Sie **http://localhost:3000/_console/**, melden Sie sich an und wählen Sie eine App aus: - -| App | Was sie Ihnen bietet | -|---|---| -| Todo | Universeller Aufgaben- und Projekt-Tracker | -| Contracts | Vertragslebenszyklus mit KI-Extraktion | -| Procurement | Lieferanten, Bestellungen, 3-Wege-Abgleich | -| Compliance | SOC 2 / ISO 27001 Kontrollen + Nachweise | -| Helpdesk | KI-zentrierter Kundensupport | -| Content | Redaktionskalender + Kanal-ROI | -| HR | Verzeichnis, Organigramm, Abwesenheiten | - -Installieren → neu laden → schon ist sie da, mit ihren Objekten, Ansichten, Berechtigungen -und Beispieldaten. Kein Neustart erforderlich. - -### Häufige Flags - -```bash -os start --port 3200 # different port -os start --database postgres://... # external database -os start --auth-secret "$(openssl rand -hex 32)" # enable auth in /api/v1/auth/* -os start --home /var/lib/objectos # persistent home (production) -``` - -Siehe [Runtime Configuration](/docs/configure/runtime) für jede Option -und [Docker](/docs/deploy/docker) für den produktionsnahen Weg. - ---- - -## Pfad B — `os init` (Entwickler) - -Verwenden Sie dies, wenn Sie TypeScript schreiben, um Ihr eigenes Datenmodell, -Ihre Ansichten und Flows zu definieren. - -```bash -npx @objectstack/cli init my-app -t app --install -cd my-app -pnpm dev -``` - -Sie sehen: - -```text -✓ Project initialized! - -◆ Compile - ✓ Build complete (462ms) - Data: 1 Objects 3 Fields - -◆ Development Mode - ✓ Server is ready - - ➜ API: http://localhost:3002/ - ➜ Console: http://localhost:3002/_console/ - ➜ Account: http://localhost:3002/_account/ - ➜ Console: http://localhost:3002/_console/ -``` - -Beachten Sie, dass der Dev-Server Port **3002** verwendet, um eine Kollision mit einem -laufenden `os start` auf Port 3000 zu vermeiden. - -### Fügen Sie Ihr eigenes Objekt hinzu - -Bearbeiten Sie `src/objects/task.ts`: - -```ts -// src/objects/task.ts -import { ObjectSchema, Field } from '@objectstack/spec/data'; - -export const Task = ObjectSchema.create({ - name: 'task', - label: 'Task', - fields: { - subject: Field.text({ label: 'Subject', required: true, maxLength: 200 }), - done: Field.boolean({ label: 'Done', defaultValue: false }), - due: Field.date({ label: 'Due' }), - assignee: Field.lookup({ label: 'Assignee', reference: 'sys_user' }), - }, -}); -``` - -Speichern. Der Dev-Server kompiliert neu, und Sie haben sofort: - -- **`/api/v1/data/task`** — vollständiges CRUD mit Filtern/Sortieren/Paginieren -- **Eine „Task"-Ansicht in der Console** — Liste, Formular, Detailansicht, alles generiert -- **Berechtigungszeilen in der Console** — gewähren Sie Lese-/Schreibzugriff pro Rolle -- **Audit-Log-Einträge** — jedes Anlegen/Aktualisieren/Löschen wird erfasst - -Keine Migrationen. Keine Codegenerierung. Kein Neustart. - -### Projektaufbau - -```text -my-app/ -├── objectstack.config.ts # Stack definition (manifest + objects) -├── src/ -│ └── objects/ # Your data model — add files here -├── dist/ -│ └── objectstack.json # Compiled artifact (regenerated on save) -├── package.json -└── tsconfig.json -``` - -`dist/objectstack.json` ist das, was Sie in die Produktion ausliefern — binden Sie es in einen -laufenden ObjectOS-Container ein, und das wird zu Ihrer App. - -### Oder starten Sie von einer Vorlage - -Produktionsnahe Starter befinden sich unter -[github.com/objectstack-ai/templates](https://github.com/objectstack-ai/templates): - -```bash -git clone https://github.com/objectstack-ai/templates.git -cd templates/packages/todo -pnpm install -pnpm dev # http://localhost:4002 -``` - -Jede Vorlage umfasst weniger als 2500 LOC, ist in einer Sitzung lesbar und läuft eigenständig. - ---- - -## Was standardmäßig geladen wird - -Beide Pfade geben Ihnen diese 23 Plugins automatisch: - -> Auth, Security (RBAC + RLS + FLS), Audit, REST API, Console UI, -> Account UI, Console UI, AI Service, Queue, Jobs, Cache, Settings, -> Email, Storage, Marketplace, Metadata, ObjectQL, plus dem SQL-Treiber. - -Sie importieren oder verdrahten keines davon — sie werden aktiviert, wenn etwas -deklariert, dass es sie benötigt. - -## Nächste Schritte - -| Was nun | Lesen | -|---|---| -| In Docker ausführen (produktionsnah) | [Docker](/docs/deploy/docker) | -| Postgres statt SQLite verwenden | [Runtime Configuration](/docs/configure/runtime) | -| Google / Okta / Entra Login hinzufügen | [Authentication](/docs/configure/authentication) | -| Festlegen, wer was tun darf | [Permissions](/docs/configure/permissions) | -| Ereignisse an Slack / Zapier / Ihren Dienst senden | [Webhooks](/docs/configure/webhooks) | -| In die Produktion deployen | [Production Readiness](/docs/operate/production) | diff --git a/content/docs/quickstart.es.mdx b/content/docs/quickstart.es.mdx deleted file mode 100644 index 831e224..0000000 --- a/content/docs/quickstart.es.mdx +++ /dev/null @@ -1,235 +0,0 @@ ---- -title: Inicio rápido -description: "De cero a un ObjectOS en marcha: instala una CLI, ejecuta un comando y tienes una aplicación." -translation: - source_sha: a9f996909d21e0b4b2f159dbe4a631f1c74b49fc9aa6ede2fa2866df598fe4bc - guide_rev: 1 - mode: auto ---- - -Hay dos formas de empezar, según lo que vayas a hacer. - -| Tú eres … | Empieza aquí | -|---|---| -| Probando ObjectOS por primera vez, o ejecutándolo en producción | [Ruta A — `os start`](#path-a--os-start-operator-first-time-evaluator) | -| Creando o personalizando una aplicación con código | [Ruta B — `os init`](#path-b--os-init-developer) | - -Ambas generan un servidor en marcha con Console + Account. La -diferencia está en si generas archivos de código fuente. - -## Requisitos previos - -- **Node.js 20 o más reciente** — `node --version` -- Una terminal - -Eso es todo. Sin Docker. Sin base de datos. Sin registro de cuenta. - ---- - -## Ruta A — `os start` (operador / evaluador por primera vez) - -Instala la CLI de forma global y luego ejecútala: - -```bash -npm i -g @objectstack/cli -os start -``` - -Verás: - -```text -◆ ObjectStack -──────────────────────────────────────── -🏠 Home: ~/.objectstack -📦 Artifact: none (empty kernel — install apps via Console marketplace) -🗄️ Database: file:~/.objectstack/data/objectstack.db - - ✓ Server is ready - - ➜ API: http://localhost:3000/ - ➜ Console: http://localhost:3000/_console/ - ➜ Account: http://localhost:3000/_account/ - ➜ Console: http://localhost:3000/_console/ - - Plugins: 23 loaded -``` - -Eso es todo. Ya tienes ObjectOS en marcha. - -### Qué está en ejecución - -| URL | Qué es | -|---|---| -| http://localhost:3000/_account/register | Crea tu primera cuenta | -| http://localhost:3000/_console/ | La interfaz de administración — y el **marketplace de aplicaciones** | -| http://localhost:3000/_console/ | Usuarios, roles, registro de auditoría, ajustes | -| http://localhost:3000/health | Sonda de actividad | - -El runtime arranca en un **kernel vacío** — sin objetos, sin aplicaciones — -y expone el marketplace para que puedas instalar aplicaciones listas para usar en -segundos. - -### Crea conversando — el AI Builder - -Una vez que hayas iniciado sesión, abre el asistente de IA en Console (el icono de -destello en la esquina superior derecha) y describe lo que necesitas: - -> *"Necesito hacer seguimiento de tickets de soporte al cliente. Cada uno tiene un asunto, -> una descripción, una prioridad (baja/media/alta/urgente), un estado y un -> responsable. Añade una vista kanban agrupada por estado."* - -La IA propone un plan, tú lo apruebas y los metadatos quedan activos — -endpoints REST, vistas de Console, entradas de registro de auditoría, controles de permisos. -Sin editar archivos, sin reiniciar. Consulta [Build → AI Builder](/docs/build/ai-builder) -para conocer todo el vocabulario. - -> **¿Programando a mano en tu IDE?** Ejecuta `npx skills add objectstack-ai/objectstack/skills` -> para enseñar a Claude Code / Cursor / Copilot / Codex a crear -> metadatos de ObjectOS con los esquemas reales de Zod. Consulta -> [Build → IDE Skills](/docs/build/ai-skills). - -### Instala una aplicación desde el marketplace - -Abre **http://localhost:3000/_console/**, inicia sesión y elige una aplicación: - -| Aplicación | Qué te ofrece | -|---|---| -| Todo | Gestor universal de tareas y proyectos | -| Contracts | Ciclo de vida de contratos con extracción por IA | -| Procurement | Proveedores, órdenes de compra, conciliación a 3 vías | -| Compliance | Controles de SOC 2 / ISO 27001 + evidencias | -| Helpdesk | Soporte al cliente con IA primero | -| Content | Calendario editorial + ROI por canal | -| HR | Directorio, organigrama, ausencias | - -Instala → recarga → ahí está, con sus objetos, vistas, permisos -y datos iniciales. Sin necesidad de reiniciar. - -### Opciones habituales - -```bash -os start --port 3200 # different port -os start --database postgres://... # external database -os start --auth-secret "$(openssl rand -hex 32)" # enable auth in /api/v1/auth/* -os start --home /var/lib/objectos # persistent home (production) -``` - -Consulta [Runtime Configuration](/docs/configure/runtime) para todas las opciones, -y [Docker](/docs/deploy/docker) para la ruta orientada a producción. - ---- - -## Ruta B — `os init` (desarrollador) - -Usa esto cuando escribas TypeScript para definir tu propio modelo de datos, -vistas y flujos. - -```bash -npx @objectstack/cli init my-app -t app --install -cd my-app -pnpm dev -``` - -Verás: - -```text -✓ Project initialized! - -◆ Compile - ✓ Build complete (462ms) - Data: 1 Objects 3 Fields - -◆ Development Mode - ✓ Server is ready - - ➜ API: http://localhost:3002/ - ➜ Console: http://localhost:3002/_console/ - ➜ Account: http://localhost:3002/_account/ - ➜ Console: http://localhost:3002/_console/ -``` - -Ten en cuenta que el servidor de desarrollo usa el puerto **3002** para evitar -colisionar con un `os start` en marcha en el 3000. - -### Añade tu propio objeto - -Edita `src/objects/task.ts`: - -```ts -// src/objects/task.ts -import { ObjectSchema, Field } from '@objectstack/spec/data'; - -export const Task = ObjectSchema.create({ - name: 'task', - label: 'Task', - fields: { - subject: Field.text({ label: 'Subject', required: true, maxLength: 200 }), - done: Field.boolean({ label: 'Done', defaultValue: false }), - due: Field.date({ label: 'Due' }), - assignee: Field.lookup({ label: 'Assignee', reference: 'sys_user' }), - }, -}); -``` - -Guarda. El servidor de desarrollo recompila e inmediatamente tienes: - -- **`/api/v1/data/task`** — CRUD completo con filtrado/ordenación/paginación -- **Una vista "Task" en Console** — lista, formulario, detalle, todo generado -- **Filas de permisos en Console** — concede lectura/escritura por rol -- **Entradas de registro de auditoría** — cada creación/actualización/eliminación queda registrada - -Sin migraciones. Sin generación de código. Sin reinicios. - -### Estructura del proyecto - -```text -my-app/ -├── objectstack.config.ts # Stack definition (manifest + objects) -├── src/ -│ └── objects/ # Your data model — add files here -├── dist/ -│ └── objectstack.json # Compiled artifact (regenerated on save) -├── package.json -└── tsconfig.json -``` - -`dist/objectstack.json` es lo que envías a producción — móntalo en un -contenedor de ObjectOS en marcha y eso se convierte en tu aplicación. - -### O empieza desde una plantilla - -Las plantillas iniciales orientadas a producción están en -[github.com/objectstack-ai/templates](https://github.com/objectstack-ai/templates): - -```bash -git clone https://github.com/objectstack-ai/templates.git -cd templates/packages/todo -pnpm install -pnpm dev # http://localhost:4002 -``` - -Cada plantilla tiene menos de 2500 líneas de código, se lee de una sentada y se ejecuta de forma independiente. - ---- - -## Qué viene cargado de fábrica - -Cualquiera de las dos rutas te ofrece estos 23 plugins automáticamente: - -> Auth, Security (RBAC + RLS + FLS), Audit, REST API, Console UI, -> Account UI, Console UI, AI Service, Queue, Jobs, Cache, Settings, -> Email, Storage, Marketplace, Metadata, ObjectQL, además del controlador SQL. - -No importas ni conectas ninguno de ellos — se activan cuando algo -declara que los necesita. - -## Próximos pasos - -| Qué hacer ahora | Lee | -|---|---| -| Ejecutarlo en Docker (orientado a producción) | [Docker](/docs/deploy/docker) | -| Usar Postgres en lugar de SQLite | [Runtime Configuration](/docs/configure/runtime) | -| Añadir inicio de sesión con Google / Okta / Entra | [Authentication](/docs/configure/authentication) | -| Restringir quién puede hacer qué | [Permissions](/docs/configure/permissions) | -| Enviar eventos a Slack / Zapier / tu servicio | [Webhooks](/docs/configure/webhooks) | -| Desplegar en producción | [Production Readiness](/docs/operate/production) | diff --git a/content/docs/quickstart.fr.mdx b/content/docs/quickstart.fr.mdx deleted file mode 100644 index c835c1a..0000000 --- a/content/docs/quickstart.fr.mdx +++ /dev/null @@ -1,236 +0,0 @@ ---- -title: Démarrage rapide -description: De zéro à un ObjectOS opérationnel — installez une CLI, exécutez une commande, vous avez une application. -translation: - source_sha: a9f996909d21e0b4b2f159dbe4a631f1c74b49fc9aa6ede2fa2866df598fe4bc - guide_rev: 1 - mode: auto ---- - -Il existe deux façons de commencer, selon ce que vous faites. - -| Vous êtes … | Commencez ici | -|---|---| -| Vous essayez ObjectOS pour la première fois, ou vous l'exécutez en production | [Parcours A — `os start`](#path-a--os-start-operator-first-time-evaluator) | -| Vous créez ou personnalisez une application dans le code | [Parcours B — `os init`](#path-b--os-init-developer) | - -Les deux produisent un serveur opérationnel avec Console + Account. La -différence réside dans le fait que vous générez ou non des fichiers source. - -## Prérequis - -- **Node.js 20 ou plus récent** — `node --version` -- Un terminal - -C'est tout. Pas de Docker. Pas de base de données. Pas d'inscription de compte. - ---- - -## Parcours A — `os start` (opérateur / premier évaluateur) - -Installez la CLI globalement, puis exécutez-la : - -```bash -npm i -g @objectstack/cli -os start -``` - -Vous verrez : - -```text -◆ ObjectStack -──────────────────────────────────────── -🏠 Home: ~/.objectstack -📦 Artifact: none (empty kernel — install apps via Console marketplace) -🗄️ Database: file:~/.objectstack/data/objectstack.db - - ✓ Server is ready - - ➜ API: http://localhost:3000/ - ➜ Console: http://localhost:3000/_console/ - ➜ Account: http://localhost:3000/_account/ - ➜ Console: http://localhost:3000/_console/ - - Plugins: 23 loaded -``` - -C'est tout. ObjectOS est en cours d'exécution. - -### Ce qui est en cours d'exécution - -| URL | Ce que c'est | -|---|---| -| http://localhost:3000/_account/register | Créez votre premier compte | -| http://localhost:3000/_console/ | L'interface d'administration — et le **marketplace d'applications** | -| http://localhost:3000/_console/ | Utilisateurs, rôles, journal d'audit, paramètres | -| http://localhost:3000/health | Sonde de disponibilité | - -Le runtime démarre sur un **kernel vide** — aucun objet, aucune application — -et expose le marketplace pour que vous puissiez installer des applications -prêtes à l'emploi en quelques secondes. - -### Construire par conversation — l'AI Builder - -Une fois connecté, ouvrez l'assistant IA dans Console (icône étincelle en -haut à droite) et décrivez ce dont vous avez besoin : - -> *« J'ai besoin de suivre les tickets de support client. Chacun a un sujet, -> une description, une priorité (basse/moyenne/haute/urgente), un statut et -> un assigné. Ajoutez une vue kanban regroupée par statut. »* - -L'IA propose un plan, vous l'approuvez, et les métadonnées sont actives — -points de terminaison REST, vues Console, entrées du journal d'audit, contrôles -de permissions. Aucun fichier modifié, aucun redémarrage. Consultez -[Build → AI Builder](/docs/build/ai-builder) pour le vocabulaire complet. - -> **Vous codez à la main dans votre IDE ?** Exécutez `npx skills add objectstack-ai/objectstack/skills` -> pour apprendre à Claude Code / Cursor / Copilot / Codex comment rédiger -> des métadonnées ObjectOS conformes aux véritables schémas Zod. Consultez -> [Build → IDE Skills](/docs/build/ai-skills). - -### Installer une application depuis le marketplace - -Ouvrez **http://localhost:3000/_console/**, connectez-vous et choisissez une application : - -| Application | Ce qu'elle vous apporte | -|---|---| -| Todo | Suivi universel des tâches et des projets | -| Contracts | Cycle de vie des contrats avec extraction par IA | -| Procurement | Fournisseurs, bons de commande, rapprochement à 3 voies | -| Compliance | Contrôles SOC 2 / ISO 27001 + preuves | -| Helpdesk | Support client centré sur l'IA | -| Content | Calendrier éditorial + ROI par canal | -| HR | Annuaire, organigramme, congés | - -Installer → recharger → c'est là, avec ses objets, ses vues, ses permissions -et ses données initiales. Aucun redémarrage requis. - -### Options courantes - -```bash -os start --port 3200 # different port -os start --database postgres://... # external database -os start --auth-secret "$(openssl rand -hex 32)" # enable auth in /api/v1/auth/* -os start --home /var/lib/objectos # persistent home (production) -``` - -Consultez [Runtime Configuration](/docs/configure/runtime) pour toutes les options, -et [Docker](/docs/deploy/docker) pour le parcours orienté production. - ---- - -## Parcours B — `os init` (développeur) - -Utilisez ceci lorsque vous écrivez du TypeScript pour définir votre propre -modèle de données, vos vues et vos flux. - -```bash -npx @objectstack/cli init my-app -t app --install -cd my-app -pnpm dev -``` - -Vous verrez : - -```text -✓ Project initialized! - -◆ Compile - ✓ Build complete (462ms) - Data: 1 Objects 3 Fields - -◆ Development Mode - ✓ Server is ready - - ➜ API: http://localhost:3002/ - ➜ Console: http://localhost:3002/_console/ - ➜ Account: http://localhost:3002/_account/ - ➜ Console: http://localhost:3002/_console/ -``` - -Notez que le serveur de développement utilise le port **3002** pour éviter -tout conflit avec un `os start` en cours d'exécution sur le port 3000. - -### Ajouter votre propre objet - -Modifiez `src/objects/task.ts` : - -```ts -// src/objects/task.ts -import { ObjectSchema, Field } from '@objectstack/spec/data'; - -export const Task = ObjectSchema.create({ - name: 'task', - label: 'Task', - fields: { - subject: Field.text({ label: 'Subject', required: true, maxLength: 200 }), - done: Field.boolean({ label: 'Done', defaultValue: false }), - due: Field.date({ label: 'Due' }), - assignee: Field.lookup({ label: 'Assignee', reference: 'sys_user' }), - }, -}); -``` - -Enregistrez. Le serveur de développement recompile et vous disposez immédiatement de : - -- **`/api/v1/data/task`** — CRUD complet avec filtrage/tri/pagination -- **Une vue « Task » dans Console** — liste, formulaire, détail, tout généré -- **Des lignes de permissions dans Console** — accordez lecture/écriture par rôle -- **Des entrées de journal d'audit** — chaque création/mise à jour/suppression enregistrée - -Aucune migration. Aucune génération de code. Aucun redémarrage. - -### Structure du projet - -```text -my-app/ -├── objectstack.config.ts # Stack definition (manifest + objects) -├── src/ -│ └── objects/ # Your data model — add files here -├── dist/ -│ └── objectstack.json # Compiled artifact (regenerated on save) -├── package.json -└── tsconfig.json -``` - -`dist/objectstack.json` est ce que vous livrez en production — montez-le sur -un conteneur ObjectOS en cours d'exécution et cela devient votre application. - -### Ou partez d'un modèle - -Des modèles de démarrage orientés production sont disponibles sur -[github.com/objectstack-ai/templates](https://github.com/objectstack-ai/templates) : - -```bash -git clone https://github.com/objectstack-ai/templates.git -cd templates/packages/todo -pnpm install -pnpm dev # http://localhost:4002 -``` - -Chaque modèle fait moins de 2500 lignes de code, se lit en une seule séance -et s'exécute de manière autonome. - ---- - -## Ce qui est chargé par défaut - -Les deux parcours vous fournissent automatiquement ces 23 plugins : - -> Auth, Security (RBAC + RLS + FLS), Audit, REST API, Console UI, -> Account UI, Console UI, AI Service, Queue, Jobs, Cache, Settings, -> Email, Storage, Marketplace, Metadata, ObjectQL, ainsi que le pilote SQL. - -Vous n'en importez ni n'en câblez aucun — ils s'activent lorsqu'un élément -déclare en avoir besoin. - -## Étapes suivantes - -| Et maintenant | À lire | -|---|---| -| L'exécuter dans Docker (orienté production) | [Docker](/docs/deploy/docker) | -| Utiliser Postgres au lieu de SQLite | [Runtime Configuration](/docs/configure/runtime) | -| Ajouter la connexion Google / Okta / Entra | [Authentication](/docs/configure/authentication) | -| Verrouiller qui peut faire quoi | [Permissions](/docs/configure/permissions) | -| Envoyer des événements vers Slack / Zapier / votre service | [Webhooks](/docs/configure/webhooks) | -| Déployer en production | [Production Readiness](/docs/operate/production) | diff --git a/content/docs/quickstart.ja.mdx b/content/docs/quickstart.ja.mdx deleted file mode 100644 index 7f5b08b..0000000 --- a/content/docs/quickstart.ja.mdx +++ /dev/null @@ -1,214 +0,0 @@ ---- -title: クイックスタート -description: ゼロから動作する ObjectOS まで — CLI を 1 つインストールし、コマンドを 1 つ実行すれば、アプリの完成です。 -translation: - source_sha: a9f996909d21e0b4b2f159dbe4a631f1c74b49fc9aa6ede2fa2866df598fe4bc - guide_rev: 1 - mode: auto ---- - -何をしたいかに応じて、2 つの始め方があります。 - -| あなたは … | ここから始める | -|---|---| -| ObjectOS を初めて試す、または本番環境で実行する | [パス A — `os start`](#path-a--os-start-operator-first-time-evaluator) | -| コードでアプリを構築・カスタマイズする | [パス B — `os init`](#path-b--os-init-developer) | - -どちらも Console + Account を備えた動作するサーバーを生成します。違いは、ソースファイルをスキャフォールドするかどうかです。 - -## 前提条件 - -- **Node.js 20 以降** — `node --version` -- ターミナル - -これだけです。Docker も不要。データベースも不要。アカウント登録も不要です。 - ---- - -## パス A — `os start`（オペレーター / 初回評価者） - -CLI をグローバルにインストールして実行します。 - -```bash -npm i -g @objectstack/cli -os start -``` - -次のように表示されます。 - -```text -◆ ObjectStack -──────────────────────────────────────── -🏠 Home: ~/.objectstack -📦 Artifact: none (empty kernel — install apps via Console marketplace) -🗄️ Database: file:~/.objectstack/data/objectstack.db - - ✓ Server is ready - - ➜ API: http://localhost:3000/ - ➜ Console: http://localhost:3000/_console/ - ➜ Account: http://localhost:3000/_account/ - ➜ Console: http://localhost:3000/_console/ - - Plugins: 23 loaded -``` - -これだけです。ObjectOS が動作しています。 - -### 動作しているもの - -| URL | 内容 | -|---|---| -| http://localhost:3000/_account/register | 最初のアカウントを作成 | -| http://localhost:3000/_console/ | 管理 UI — そして **アプリ marketplace** | -| http://localhost:3000/_console/ | ユーザー、ロール、監査ログ、設定 | -| http://localhost:3000/health | 死活監視プローブ | - -ランタイムは **空のカーネル** で起動します — オブジェクトもアプリもありません — そして marketplace を公開するので、既製のアプリを数秒でインストールできます。 - -### チャットで構築する — AI Builder - -サインインしたら、Console の AI アシスタント（右上のキラキラアイコン）を開き、必要なものを記述します。 - -> *「カスタマーサポートのチケットを追跡したい。各チケットには件名、説明、優先度（低 / 中 / 高 / 緊急）、ステータス、担当者がある。ステータスでグループ化したかんばんビューを追加して。」* - -AI がプランを提案し、あなたが承認すると、メタデータが即座に有効になります — REST エンドポイント、Console ビュー、監査ログのエントリ、権限ゲート。ファイルの編集も再起動も不要です。完全な語彙については [Build → AI Builder](/docs/build/ai-builder) を参照してください。 - -> **IDE で手書きコーディングしますか？** `npx skills add objectstack-ai/objectstack/skills` を実行すると、Claude Code / Cursor / Copilot / Codex に、本物の Zod スキーマに対して ObjectOS メタデータを記述する方法を教えられます。[Build → IDE Skills](/docs/build/ai-skills) を参照してください。 - -### marketplace からアプリをインストールする - -**http://localhost:3000/_console/** を開き、サインインしてアプリを選びます。 - -| アプリ | 提供される機能 | -|---|---| -| Todo | 汎用的なタスク & プロジェクトトラッカー | -| Contracts | AI 抽出付きの契約ライフサイクル | -| Procurement | ベンダー、発注書、3-way マッチ | -| Compliance | SOC 2 / ISO 27001 のコントロール + エビデンス | -| Helpdesk | AI ファーストなカスタマーサポート | -| Content | 編集カレンダー + チャネル ROI | -| HR | ディレクトリ、組織図、休暇管理 | - -インストール → 再読み込み → オブジェクト、ビュー、権限、シードデータとともにそこに表示されます。再起動は不要です。 - -### よく使うフラグ - -```bash -os start --port 3200 # different port -os start --database postgres://... # external database -os start --auth-secret "$(openssl rand -hex 32)" # enable auth in /api/v1/auth/* -os start --home /var/lib/objectos # persistent home (production) -``` - -すべてのオプションについては [Runtime Configuration](/docs/configure/runtime) を、本番環境向けのパスについては [Docker](/docs/deploy/docker) を参照してください。 - ---- - -## パス B — `os init`（開発者） - -TypeScript を書いて独自のデータモデル、ビュー、フローを定義する場合は、こちらを使います。 - -```bash -npx @objectstack/cli init my-app -t app --install -cd my-app -pnpm dev -``` - -次のように表示されます。 - -```text -✓ Project initialized! - -◆ Compile - ✓ Build complete (462ms) - Data: 1 Objects 3 Fields - -◆ Development Mode - ✓ Server is ready - - ➜ API: http://localhost:3002/ - ➜ Console: http://localhost:3002/_console/ - ➜ Account: http://localhost:3002/_account/ - ➜ Console: http://localhost:3002/_console/ -``` - -dev サーバーは、3000 で実行中の `os start` と衝突しないように、ポート **3002** を使用する点に注意してください。 - -### 独自のオブジェクトを追加する - -`src/objects/task.ts` を編集します。 - -```ts -// src/objects/task.ts -import { ObjectSchema, Field } from '@objectstack/spec/data'; - -export const Task = ObjectSchema.create({ - name: 'task', - label: 'Task', - fields: { - subject: Field.text({ label: 'Subject', required: true, maxLength: 200 }), - done: Field.boolean({ label: 'Done', defaultValue: false }), - due: Field.date({ label: 'Due' }), - assignee: Field.lookup({ label: 'Assignee', reference: 'sys_user' }), - }, -}); -``` - -保存します。dev サーバーが再コンパイルし、すぐに次のものが手に入ります。 - -- **`/api/v1/data/task`** — フィルター / ソート / ページネーション付きの完全な CRUD -- **Console の「Task」ビュー** — リスト、フォーム、詳細、すべて自動生成 -- **Console の権限行** — ロールごとに読み取り / 書き込みを付与 -- **監査ログのエントリ** — すべての作成 / 更新 / 削除を記録 - -マイグレーション不要。コード生成不要。再起動不要です。 - -### プロジェクト構成 - -```text -my-app/ -├── objectstack.config.ts # Stack definition (manifest + objects) -├── src/ -│ └── objects/ # Your data model — add files here -├── dist/ -│ └── objectstack.json # Compiled artifact (regenerated on save) -├── package.json -└── tsconfig.json -``` - -`dist/objectstack.json` が本番環境に出荷するものです — 動作中の ObjectOS コンテナにマウントすれば、それがあなたのアプリになります。 - -### またはテンプレートから始める - -本番環境向けのスターターは [github.com/objectstack-ai/templates](https://github.com/objectstack-ai/templates) にあります。 - -```bash -git clone https://github.com/objectstack-ai/templates.git -cd templates/packages/todo -pnpm install -pnpm dev # http://localhost:4002 -``` - -各テンプレートは 2500 行未満で、一度に読み切れる量で、単独で動作します。 - ---- - -## 標準で読み込まれるもの - -どちらのパスでも、これら 23 のプラグインが自動的に手に入ります。 - -> Auth、Security（RBAC + RLS + FLS）、Audit、REST API、Console UI、Account UI、Console UI、AI Service、Queue、Jobs、Cache、Settings、Email、Storage、Marketplace、Metadata、ObjectQL、そして SQL ドライバー。 - -これらをインポートしたり配線したりする必要はありません — 何かがそれらを必要とすると宣言したときに有効になります。 - -## 次のステップ - -| 次にやること | 読む | -|---|---| -| Docker で実行する（本番環境向け） | [Docker](/docs/deploy/docker) | -| SQLite の代わりに Postgres を使う | [Runtime Configuration](/docs/configure/runtime) | -| Google / Okta / Entra ログインを追加する | [Authentication](/docs/configure/authentication) | -| 誰が何をできるかを制限する | [Permissions](/docs/configure/permissions) | -| Slack / Zapier / 自社サービスにイベントを送信する | [Webhooks](/docs/configure/webhooks) | -| 本番環境にデプロイする | [Production Readiness](/docs/operate/production) | diff --git a/content/docs/quickstart.ko.mdx b/content/docs/quickstart.ko.mdx deleted file mode 100644 index 8636a2f..0000000 --- a/content/docs/quickstart.ko.mdx +++ /dev/null @@ -1,234 +0,0 @@ ---- -title: 빠른 시작 -description: 처음부터 실행 중인 ObjectOS까지 — CLI 하나를 설치하고 명령 하나를 실행하면 앱이 완성됩니다. -translation: - source_sha: a9f996909d21e0b4b2f159dbe4a631f1c74b49fc9aa6ede2fa2866df598fe4bc - guide_rev: 1 - mode: auto ---- - -무엇을 하려는지에 따라 시작하는 방법이 두 가지 있습니다. - -| 당신은 … | 여기서 시작하세요 | -|---|---| -| ObjectOS를 처음 사용해 보거나 프로덕션에서 실행하는 경우 | [경로 A — `os start`](#path-a--os-start-operator-first-time-evaluator) | -| 코드로 앱을 빌드하거나 커스터마이징하는 경우 | [경로 B — `os init`](#path-b--os-init-developer) | - -두 경로 모두 Console + Account가 포함된 실행 중인 서버를 생성합니다. -차이점은 소스 파일을 스캐폴딩하는지 여부입니다. - -## 사전 요구 사항 - -- **Node.js 20 이상** — `node --version` -- 터미널 - -이것이 전부입니다. Docker 불필요. 데이터베이스 불필요. 계정 가입 불필요. - ---- - -## 경로 A — `os start` (운영자 / 처음 평가하는 사용자) - -CLI를 전역으로 설치한 다음 실행합니다: - -```bash -npm i -g @objectstack/cli -os start -``` - -다음과 같은 화면이 표시됩니다: - -```text -◆ ObjectStack -──────────────────────────────────────── -🏠 Home: ~/.objectstack -📦 Artifact: none (empty kernel — install apps via Console marketplace) -🗄️ Database: file:~/.objectstack/data/objectstack.db - - ✓ Server is ready - - ➜ API: http://localhost:3000/ - ➜ Console: http://localhost:3000/_console/ - ➜ Account: http://localhost:3000/_account/ - ➜ Console: http://localhost:3000/_console/ - - Plugins: 23 loaded -``` - -이것이 전부입니다. ObjectOS가 실행되고 있습니다. - -### 실행 중인 항목 - -| URL | 무엇인지 | -|---|---| -| http://localhost:3000/_account/register | 첫 번째 계정 생성 | -| http://localhost:3000/_console/ | 관리자 UI — 그리고 **앱 marketplace** | -| http://localhost:3000/_console/ | 사용자, 역할, 감사 로그, 설정 | -| http://localhost:3000/health | 활성 상태 프로브 | - -런타임은 **빈 커널**로 부팅되며 — 오브젝트도 앱도 없습니다 — -marketplace를 노출하여 몇 초 만에 완성된 앱을 설치할 수 있게 합니다. - -### 채팅으로 빌드 — AI Builder - -로그인한 후, Console에서 AI 어시스턴트(오른쪽 상단의 -반짝이 아이콘)를 열고 필요한 것을 설명하세요: - -> *"고객 지원 티켓을 추적해야 합니다. 각 티켓에는 제목, -> 설명, 우선순위(낮음/중간/높음/긴급), 상태, 담당자가 -> 있습니다. 상태별로 그룹화된 칸반 뷰를 추가하세요."* - -AI가 계획을 제안하고, 당신이 승인하면, 메타데이터가 바로 적용됩니다 — -REST 엔드포인트, Console 뷰, 감사 로그 항목, 권한 게이트까지. -파일 편집도, 재시작도 필요 없습니다. 전체 어휘는 [Build → AI Builder](/docs/build/ai-builder)를 -참고하세요. - -> **IDE에서 직접 코딩하시나요?** `npx skills add objectstack-ai/objectstack/skills`를 -> 실행하여 Claude Code / Cursor / Copilot / Codex가 실제 Zod 스키마에 맞춰 -> ObjectOS 메타데이터를 작성하는 방법을 익히도록 하세요. -> [Build → IDE Skills](/docs/build/ai-skills)를 참고하세요. - -### marketplace에서 앱 설치 - -**http://localhost:3000/_console/**를 열고, 로그인한 후, 앱을 선택하세요: - -| 앱 | 제공하는 기능 | -|---|---| -| Todo | 범용 작업 및 프로젝트 추적기 | -| Contracts | AI 추출이 포함된 계약 라이프사이클 | -| Procurement | 공급업체, 발주서, 3자 매칭 | -| Compliance | SOC 2 / ISO 27001 통제 항목 + 증빙 | -| Helpdesk | AI 우선 고객 지원 | -| Content | 편집 캘린더 + 채널 ROI | -| HR | 디렉터리, 조직도, 휴가 | - -설치 → 새로고침 → 오브젝트, 뷰, 권한, 시드 데이터와 함께 -바로 사용할 수 있습니다. 재시작이 필요 없습니다. - -### 자주 쓰는 플래그 - -```bash -os start --port 3200 # different port -os start --database postgres://... # external database -os start --auth-secret "$(openssl rand -hex 32)" # enable auth in /api/v1/auth/* -os start --home /var/lib/objectos # persistent home (production) -``` - -모든 옵션은 [Runtime Configuration](/docs/configure/runtime)을, -프로덕션 형태의 경로는 [Docker](/docs/deploy/docker)를 참고하세요. - ---- - -## 경로 B — `os init` (개발자) - -직접 데이터 모델, 뷰, 플로우를 정의하기 위해 TypeScript를 작성할 때 -이 경로를 사용하세요. - -```bash -npx @objectstack/cli init my-app -t app --install -cd my-app -pnpm dev -``` - -다음과 같은 화면이 표시됩니다: - -```text -✓ Project initialized! - -◆ Compile - ✓ Build complete (462ms) - Data: 1 Objects 3 Fields - -◆ Development Mode - ✓ Server is ready - - ➜ API: http://localhost:3002/ - ➜ Console: http://localhost:3002/_console/ - ➜ Account: http://localhost:3002/_account/ - ➜ Console: http://localhost:3002/_console/ -``` - -dev 서버는 3000에서 실행 중인 `os start`와 충돌을 피하기 위해 -**3002** 포트를 사용한다는 점에 유의하세요. - -### 직접 오브젝트 추가하기 - -`src/objects/task.ts`를 편집하세요: - -```ts -// src/objects/task.ts -import { ObjectSchema, Field } from '@objectstack/spec/data'; - -export const Task = ObjectSchema.create({ - name: 'task', - label: 'Task', - fields: { - subject: Field.text({ label: 'Subject', required: true, maxLength: 200 }), - done: Field.boolean({ label: 'Done', defaultValue: false }), - due: Field.date({ label: 'Due' }), - assignee: Field.lookup({ label: 'Assignee', reference: 'sys_user' }), - }, -}); -``` - -저장하세요. dev 서버가 다시 컴파일되고 즉시 다음을 사용할 수 있습니다: - -- **`/api/v1/data/task`** — 필터/정렬/페이지네이션이 포함된 전체 CRUD -- **Console의 "Task" 뷰** — 목록, 폼, 상세가 모두 생성됨 -- **Console의 권한 행** — 역할별로 읽기/쓰기 권한 부여 -- **감사 로그 항목** — 모든 생성/수정/삭제가 기록됨 - -마이그레이션 없음. 코드 생성 없음. 재시작 없음. - -### 프로젝트 레이아웃 - -```text -my-app/ -├── objectstack.config.ts # Stack definition (manifest + objects) -├── src/ -│ └── objects/ # Your data model — add files here -├── dist/ -│ └── objectstack.json # Compiled artifact (regenerated on save) -├── package.json -└── tsconfig.json -``` - -`dist/objectstack.json`은 프로덕션에 배포하는 파일입니다 — 실행 중인 -ObjectOS 컨테이너에 마운트하면 그것이 당신의 앱이 됩니다. - -### 또는 템플릿에서 시작하기 - -프로덕션 형태의 스타터는 -[github.com/objectstack-ai/templates](https://github.com/objectstack-ai/templates)에 있습니다: - -```bash -git clone https://github.com/objectstack-ai/templates.git -cd templates/packages/todo -pnpm install -pnpm dev # http://localhost:4002 -``` - -각 템플릿은 2500 LOC 미만으로, 한 번에 읽을 수 있으며, 독립적으로 실행됩니다. - ---- - -## 기본으로 로드되는 항목 - -어느 경로든 다음 23개의 플러그인을 자동으로 제공합니다: - -> Auth, Security (RBAC + RLS + FLS), Audit, REST API, Console UI, -> Account UI, Console UI, AI Service, Queue, Jobs, Cache, Settings, -> Email, Storage, Marketplace, Metadata, ObjectQL, 그리고 SQL 드라이버. - -이들 중 어느 것도 직접 import하거나 연결할 필요가 없습니다 — -무언가가 필요하다고 선언하면 자동으로 활성화됩니다. - -## 다음 단계 - -| 이제 무엇을 | 읽어보기 | -|---|---| -| Docker에서 실행 (프로덕션 형태) | [Docker](/docs/deploy/docker) | -| SQLite 대신 Postgres 사용 | [Runtime Configuration](/docs/configure/runtime) | -| Google / Okta / Entra 로그인 추가 | [Authentication](/docs/configure/authentication) | -| 누가 무엇을 할 수 있는지 제한 | [Permissions](/docs/configure/permissions) | -| Slack / Zapier / 내 서비스로 이벤트 전송 | [Webhooks](/docs/configure/webhooks) | -| 프로덕션에 배포 | [Production Readiness](/docs/operate/production) | diff --git a/content/docs/quickstart.mdx b/content/docs/quickstart.mdx index 10c599d..d88784a 100644 --- a/content/docs/quickstart.mdx +++ b/content/docs/quickstart.mdx @@ -1,13 +1,23 @@ --- title: Quickstart -description: From zero to a running ObjectOS — install one CLI, run one command, you have an app. +description: From zero to a running app on the open-source ObjectStack runtime — install one CLI, run one command. ObjectOS Cloud needs none of it, sign in and build in the browser. --- -There are two ways to start, depending on what you're doing. +This page boots the **open-source ObjectStack runtime** on your own +machine — the stack ObjectOS is built on. ObjectOS itself needs none of +it: **ObjectOS Cloud** is hosted in the browser with nothing to install +(sign in at [www.objectos.ai](https://www.objectos.ai)), and **ObjectOS +Enterprise** is the same runtime environment self-managed on your +infrastructure, deployed from the licensed image described under +[Deployment](/docs/deploy). What you build here is ordinary ObjectStack +metadata, so it runs on either. + +There are two ways to start the open runtime, depending on what you're +doing. | You are … | Start here | |---|---| -| Trying ObjectOS for the first time, or running it in production | [Path A — `os start`](#path-a--os-start-operator-first-time-evaluator) | +| Trying the open runtime for the first time, or running it in production | [Path A — `os start`](#path-a--os-start-operator-first-time-evaluator) | | Building or customizing an app in code | [Path B — `os init`](#path-b--os-init-developer) | Both produce a running server with the UI — account sign-in, registration @@ -58,7 +68,10 @@ You'll see: Press Ctrl+C to stop ``` -That's it. You're running ObjectOS. +That's it. You're running the open-source ObjectStack runtime — the stack +ObjectOS is built on, not ObjectOS itself. See +[License & Pricing](/docs/resources/license) for what the ObjectOS editions +add on top of it. That block is transcribed from `@objectstack/cli` 17.5.0 booting an empty kernel. Home paths show as `~/…` — the CLI prints yours expanded. Your own boot @@ -93,8 +106,12 @@ show which probe goes where. ### Build by chat — the AI Builder -Once you're signed in, open the AI assistant (top-right -sparkle icon) and describe what you need: +The in-product AI Builder is ObjectOS's: it ships in ObjectOS Cloud and +ObjectOS Enterprise, not in the open runtime you just started, whose AI +path is the MCP endpoint printed in the banner +(`http://localhost:3000/api/v1/mcp` — point Claude Code or any MCP client +at it). On ObjectOS, once you're signed in, open the AI assistant +(top-right sparkle icon) and describe what you need: > *"I need to track customer support tickets. Each has a subject, > description, priority (low/medium/high/urgent), status, and @@ -107,8 +124,8 @@ for the full vocabulary. > **Hand-coding in your IDE?** Run `npx skills add objectstack-ai/objectstack/skills` > to teach Claude Code / Cursor / Copilot / Codex how to author -> ObjectOS metadata against the real Zod schemas. See -> [Build → IDE Skills](/docs/build/ai-skills). +> ObjectStack metadata — the ontology ObjectOS runs — against the real Zod +> schemas. See [Build → IDE Skills](/docs/build/ai-skills). ### Install an app from the marketplace @@ -258,8 +275,9 @@ my-app/ └── tsconfig.json ``` -`dist/objectstack.json` is what you ship to production — mount it on a -running ObjectOS container and that becomes your app. +`dist/objectstack.json` is what you ship to production — mount it on the +runtime, the open ObjectStack image or an ObjectOS Enterprise deployment, +and that becomes your app. ### Or start from a template diff --git a/content/docs/quickstart.zh-Hans.mdx b/content/docs/quickstart.zh-Hans.mdx deleted file mode 100644 index b6a6df3..0000000 --- a/content/docs/quickstart.zh-Hans.mdx +++ /dev/null @@ -1,214 +0,0 @@ ---- -title: 快速开始 -description: 从零到一个运行中的 ObjectOS —— 安装一个 CLI，运行一条命令，你就有了一个应用。 -translation: - source_sha: a9f996909d21e0b4b2f159dbe4a631f1c74b49fc9aa6ede2fa2866df598fe4bc - guide_rev: 1 - mode: auto ---- - -根据你正在做的事情，有两种启动方式。 - -| 你是…… | 从这里开始 | -|---|---| -| 第一次试用 ObjectOS，或在生产环境运行它 | [路径 A —— `os start`](#path-a--os-start-operator-first-time-evaluator) | -| 用代码构建或定制应用 | [路径 B —— `os init`](#path-b--os-init-developer) | - -两者都会得到一个运行中的服务器，包含 Console + Account。区别在于是否生成源码文件。 - -## 先决条件 - -- **Node.js 20 或更新** —— `node --version` -- 一个终端 - -仅此而已。无需 Docker。无需数据库。无需注册账号。 - ---- - -## 路径 A —— `os start`（运维 / 首次评估者）[#path-a--os-start-operator-first-time-evaluator] - -全局安装 CLI，然后运行： - -```bash -npm i -g @objectstack/cli -os start -``` - -你会看到： - -```text -◆ ObjectStack -──────────────────────────────────────── -🏠 Home: ~/.objectstack -📦 Artifact: none (empty kernel — install apps via Console marketplace) -🗄️ Database: file:~/.objectstack/data/objectstack.db - - ✓ Server is ready - - ➜ API: http://localhost:3000/ - ➜ Console: http://localhost:3000/_console/ - ➜ Account: http://localhost:3000/_account/ - ➜ Console: http://localhost:3000/_console/ - - Plugins: 23 loaded -``` - -就这样。你已经在运行 ObjectOS 了。 - -### 都在运行什么 - -| URL | 是什么 | -|---|---| -| http://localhost:3000/_account/register | 创建你的第一个账号 | -| http://localhost:3000/_console/ | 管理 UI —— 以及**应用市场** | -| http://localhost:3000/_console/ | 用户、角色、审计日志、设置 | -| http://localhost:3000/health | 存活探针 | - -运行时以**空内核**启动 —— 没有对象，没有应用 —— 并暴露市场，让你能在几秒内安装现成应用。 - -### 用对话构建 —— AI Builder - -登录后，打开 Console 中的 AI 助手（右上角闪光图标），描述你要的东西： - -> *"我需要追踪客户支持工单。每张工单都有主题、描述、优先级（低/中/高/紧急）、状态和负责人。再加一个按状态分组的看板视图。"* - -AI 提出一份计划，你批准，元数据就立刻生效 —— REST 端点、Console 视图、审计日志、权限闸门。无需编辑文件，无需重启。完整词汇请见 [Build → AI Builder](/docs/build/ai-builder)。 - -> **在 IDE 中手写代码？** 运行 `npx skills add objectstack-ai/objectstack/skills`，让 Claude Code / Cursor / Copilot / Codex 学会根据真实的 Zod schema 编写 ObjectOS 元数据。参见 [Build → IDE Skills](/docs/build/ai-skills)。 - -### 从市场安装应用 - -打开 **http://localhost:3000/_console/**，登录，选一个应用： - -| 应用 | 你能得到什么 | -|---|---| -| Todo | 通用任务与项目追踪 | -| Contracts | 合同生命周期 + AI 信息抽取 | -| Procurement | 供应商、采购单、三向匹配 | -| Compliance | SOC 2 / ISO 27001 控制项与证据 | -| Helpdesk | AI 优先的客户支持 | -| Content | 编辑日历 + 渠道 ROI | -| HR | 通讯录、组织架构、休假 | - -安装 → 刷新 → 它就在那里了，带着对象、视图、权限和种子数据。无需重启。 - -### 常用参数 - -```bash -os start --port 3200 # 不同端口 -os start --database postgres://... # 外部数据库 -os start --auth-secret "$(openssl rand -hex 32)" # 启用 /api/v1/auth/* 认证 -os start --home /var/lib/objectos # 持久化主目录（生产环境） -``` - -完整选项见 [Runtime Configuration](/docs/configure/runtime)；生产形态请见 [Docker](/docs/deploy/docker)。 - ---- - -## 路径 B —— `os init`（开发者）[#path-b--os-init-developer] - -当你要用 TypeScript 定义自己的数据模型、视图和流程时使用。 - -```bash -npx @objectstack/cli init my-app -t app --install -cd my-app -pnpm dev -``` - -你会看到： - -```text -✓ Project initialized! - -◆ Compile - ✓ Build complete (462ms) - Data: 1 Objects 3 Fields - -◆ Development Mode - ✓ Server is ready - - ➜ API: http://localhost:3002/ - ➜ Console: http://localhost:3002/_console/ - ➜ Account: http://localhost:3002/_account/ - ➜ Console: http://localhost:3002/_console/ -``` - -注意 dev 服务器使用 **3002** 端口，避免与运行在 3000 的 `os start` 冲突。 - -### 添加你自己的对象 - -编辑 `src/objects/task.ts`： - -```ts -// src/objects/task.ts -import { ObjectSchema, Field } from '@objectstack/spec/data'; - -export const Task = ObjectSchema.create({ - name: 'task', - label: 'Task', - fields: { - subject: Field.text({ label: 'Subject', required: true, maxLength: 200 }), - done: Field.boolean({ label: 'Done', defaultValue: false }), - due: Field.date({ label: 'Due' }), - assignee: Field.lookup({ label: 'Assignee', reference: 'sys_user' }), - }, -}); -``` - -保存。dev 服务器重新编译，你立刻就有了： - -- **`/api/v1/data/task`** —— 支持过滤/排序/分页的完整 CRUD -- **Console 中的 "Task" 视图** —— 列表、表单、详情，全部生成 -- **Console 中的权限行** —— 按角色授予读/写 -- **审计日志条目** —— 每次创建/更新/删除都被记录 - -无需迁移。无需代码生成。无需重启。 - -### 项目布局 - -```text -my-app/ -├── objectstack.config.ts # Stack 定义（清单 + 对象） -├── src/ -│ └── objects/ # 你的数据模型 —— 在这里加文件 -├── dist/ -│ └── objectstack.json # 编译产物（保存时重新生成） -├── package.json -└── tsconfig.json -``` - -`dist/objectstack.json` 就是你部署到生产的产物 —— 把它挂到运行中的 ObjectOS 容器上，它就成为你的应用。 - -### 或者从模板开始 - -生产形态的模板位于 [github.com/objectstack-ai/templates](https://github.com/objectstack-ai/templates)： - -```bash -git clone https://github.com/objectstack-ai/templates.git -cd templates/packages/todo -pnpm install -pnpm dev # http://localhost:4002 -``` - -每个模板小于 2500 行代码，一次能读完，可独立运行。 - ---- - -## 开箱启用的能力 - -无论哪条路径，都自动启用这 23 个插件： - -> Auth、Security（RBAC + RLS + FLS）、Audit、REST API、Console UI、Account UI、AI Service、Queue、Jobs、Cache、Settings、Email、Storage、Marketplace、Metadata、ObjectQL，外加 SQL 驱动。 - -你无需 import 或接线任何一个 —— 当某处声明需要时它们就会激活。 - -## 接下来 - -| 想要…… | 阅读 | -|---|---| -| 在 Docker 中运行（生产形态） | [Docker](/docs/deploy/docker) | -| 用 Postgres 替代 SQLite | [Runtime Configuration](/docs/configure/runtime) | -| 加入 Google / Okta / Entra 登录 | [Authentication](/docs/configure/authentication) | -| 锁定谁能做什么 | [Permissions](/docs/configure/permissions) | -| 把事件发送到 Slack / Zapier / 你的服务 | [Webhooks](/docs/configure/webhooks) | -| 部署到生产 | [Production Readiness](/docs/operate/production) | diff --git a/content/docs/quickstart.zh-Hant.mdx b/content/docs/quickstart.zh-Hant.mdx deleted file mode 100644 index 20f9c00..0000000 --- a/content/docs/quickstart.zh-Hant.mdx +++ /dev/null @@ -1,215 +0,0 @@ ---- -# @generated zh-Hant from zh-Hans -- do not edit. Edit the English source, then regenerate: pnpm --filter @objectos/docs gen:zh-hant -title: 快速開始 -description: 從零到一個執行中的 ObjectOS —— 安裝一個 CLI，執行一條命令，你就有了一個應用。 -translation: - source_sha: a9f996909d21e0b4b2f159dbe4a631f1c74b49fc9aa6ede2fa2866df598fe4bc - guide_rev: 1 - mode: auto ---- - -根據你正在做的事情，有兩種啟動方式。 - -| 你是…… | 從這裡開始 | -|---|---| -| 第一次試用 ObjectOS，或在生產環境執行它 | [路徑 A —— `os start`](#path-a--os-start-operator-first-time-evaluator) | -| 用程式碼構建或定製應用 | [路徑 B —— `os init`](#path-b--os-init-developer) | - -兩者都會得到一個執行中的伺服器，包含 Console + Account。區別在於是否生成原始碼檔案。 - -## 先決條件 - -- **Node.js 20 或更新** —— `node --version` -- 一個終端 - -僅此而已。無需 Docker。無需資料庫。無需註冊賬號。 - ---- - -## 路徑 A —— `os start`（運維 / 首次評估者）[#path-a--os-start-operator-first-time-evaluator] - -全域性安裝 CLI，然後執行： - -```bash -npm i -g @objectstack/cli -os start -``` - -你會看到： - -```text -◆ ObjectStack -──────────────────────────────────────── -🏠 Home: ~/.objectstack -📦 Artifact: none (empty kernel — install apps via Console marketplace) -🗄️ Database: file:~/.objectstack/data/objectstack.db - - ✓ Server is ready - - ➜ API: http://localhost:3000/ - ➜ Console: http://localhost:3000/_console/ - ➜ Account: http://localhost:3000/_account/ - ➜ Console: http://localhost:3000/_console/ - - Plugins: 23 loaded -``` - -就這樣。你已經在執行 ObjectOS 了。 - -### 都在執行什麼 - -| URL | 是什麼 | -|---|---| -| http://localhost:3000/_account/register | 建立你的第一個賬號 | -| http://localhost:3000/_console/ | 管理 UI —— 以及**應用市場** | -| http://localhost:3000/_console/ | 使用者、角色、審計日誌、設定 | -| http://localhost:3000/health | 存活探針 | - -執行時以**空核心**啟動 —— 沒有物件，沒有應用 —— 並暴露市場，讓你能在幾秒內安裝現成應用。 - -### 用對話構建 —— AI Builder - -登入後，開啟 Console 中的 AI 助手（右上角閃光圖示），描述你要的東西： - -> *"我需要追蹤客戶支援工單。每張工單都有主題、描述、優先順序（低/中/高/緊急）、狀態和負責人。再加一個按狀態分組的看板檢視。"* - -AI 提出一份計劃，你批准，後設資料就立刻生效 —— REST 端點、Console 檢視、審計日誌、許可權閘門。無需編輯檔案，無需重啟。完整詞彙請見 [Build → AI Builder](/docs/build/ai-builder)。 - -> **在 IDE 中手寫程式碼？** 執行 `npx skills add objectstack-ai/objectstack/skills`，讓 Claude Code / Cursor / Copilot / Codex 學會根據真實的 Zod schema 編寫 ObjectOS 後設資料。參見 [Build → IDE Skills](/docs/build/ai-skills)。 - -### 從市場安裝應用 - -開啟 **http://localhost:3000/_console/**，登入，選一個應用： - -| 應用 | 你能得到什麼 | -|---|---| -| Todo | 通用任務與專案追蹤 | -| Contracts | 合同生命週期 + AI 資訊抽取 | -| Procurement | 供應商、採購單、三向匹配 | -| Compliance | SOC 2 / ISO 27001 控制項與證據 | -| Helpdesk | AI 優先的客戶支援 | -| Content | 編輯日曆 + 渠道 ROI | -| HR | 通訊錄、組織架構、休假 | - -安裝 → 重新整理 → 它就在那裡了，帶著物件、檢視、許可權和種子資料。無需重啟。 - -### 常用引數 - -```bash -os start --port 3200 # 不同端口 -os start --database postgres://... # 外部数据库 -os start --auth-secret "$(openssl rand -hex 32)" # 启用 /api/v1/auth/* 认证 -os start --home /var/lib/objectos # 持久化主目录（生产环境） -``` - -完整選項見 [Runtime Configuration](/docs/configure/runtime)；生產形態請見 [Docker](/docs/deploy/docker)。 - ---- - -## 路徑 B —— `os init`（開發者）[#path-b--os-init-developer] - -當你要用 TypeScript 定義自己的資料模型、檢視和流程時使用。 - -```bash -npx @objectstack/cli init my-app -t app --install -cd my-app -pnpm dev -``` - -你會看到： - -```text -✓ Project initialized! - -◆ Compile - ✓ Build complete (462ms) - Data: 1 Objects 3 Fields - -◆ Development Mode - ✓ Server is ready - - ➜ API: http://localhost:3002/ - ➜ Console: http://localhost:3002/_console/ - ➜ Account: http://localhost:3002/_account/ - ➜ Console: http://localhost:3002/_console/ -``` - -注意 dev 伺服器使用 **3002** 埠，避免與執行在 3000 的 `os start` 衝突。 - -### 新增你自己的物件 - -編輯 `src/objects/task.ts`： - -```ts -// src/objects/task.ts -import { ObjectSchema, Field } from '@objectstack/spec/data'; - -export const Task = ObjectSchema.create({ - name: 'task', - label: 'Task', - fields: { - subject: Field.text({ label: 'Subject', required: true, maxLength: 200 }), - done: Field.boolean({ label: 'Done', defaultValue: false }), - due: Field.date({ label: 'Due' }), - assignee: Field.lookup({ label: 'Assignee', reference: 'sys_user' }), - }, -}); -``` - -儲存。dev 伺服器重新編譯，你立刻就有了： - -- **`/api/v1/data/task`** —— 支援過濾/排序/分頁的完整 CRUD -- **Console 中的 "Task" 檢視** —— 列表、表單、詳情，全部生成 -- **Console 中的許可權行** —— 按角色授予讀/寫 -- **審計日誌條目** —— 每次建立/更新/刪除都被記錄 - -無需遷移。無需程式碼生成。無需重啟。 - -### 專案佈局 - -```text -my-app/ -├── objectstack.config.ts # Stack 定义（清单 + 对象） -├── src/ -│ └── objects/ # 你的数据模型 —— 在这里加文件 -├── dist/ -│ └── objectstack.json # 编译产物（保存时重新生成） -├── package.json -└── tsconfig.json -``` - -`dist/objectstack.json` 就是你部署到生產的產物 —— 把它掛到執行中的 ObjectOS 容器上，它就成為你的應用。 - -### 或者從模板開始 - -生產形態的模板位於 [github.com/objectstack-ai/templates](https://github.com/objectstack-ai/templates)： - -```bash -git clone https://github.com/objectstack-ai/templates.git -cd templates/packages/todo -pnpm install -pnpm dev # http://localhost:4002 -``` - -每個模板小於 2500 行程式碼，一次能讀完，可獨立執行。 - ---- - -## 開箱啟用的能力 - -無論哪條路徑，都自動啟用這 23 個外掛： - -> Auth、Security（RBAC + RLS + FLS）、Audit、REST API、Console UI、Account UI、AI Service、Queue、Jobs、Cache、Settings、Email、Storage、Marketplace、Metadata、ObjectQL，外加 SQL 驅動。 - -你無需 import 或接線任何一個 —— 當某處宣告需要時它們就會啟用。 - -## 接下來 - -| 想要…… | 閱讀 | -|---|---| -| 在 Docker 中執行（生產形態） | [Docker](/docs/deploy/docker) | -| 用 Postgres 替代 SQLite | [Runtime Configuration](/docs/configure/runtime) | -| 加入 Google / Okta / Entra 登入 | [Authentication](/docs/configure/authentication) | -| 鎖定誰能做什麼 | [Permissions](/docs/configure/permissions) | -| 把事件傳送到 Slack / Zapier / 你的服務 | [Webhooks](/docs/configure/webhooks) | -| 部署到生產 | [Production Readiness](/docs/operate/production) | diff --git a/content/docs/reference/security.es.mdx b/content/docs/reference/security.es.mdx deleted file mode 100644 index 9893ac1..0000000 --- a/content/docs/reference/security.es.mdx +++ /dev/null @@ -1,279 +0,0 @@ ---- -title: Seguridad y Cumplimiento -description: Qué se protege, cómo y quién es responsable — para revisión de seguridad. -translation: - source_sha: 8ef4efaee0f913098534126f549f5d34559d1b3f39a8a4e5fd76e49c9a2d41ff - guide_rev: 1 - mode: auto ---- - -Esta página está dirigida a revisores de seguridad, administradores de TI y -cualquier persona que tenga que responder "¿es seguro adoptar esto?" - -## El modelo de amenazas en una frase - -ObjectOS se ejecuta como un único proceso de Node.js dentro de **tu** red, -se comunica con **tu** base de datos y nunca se conecta a casa. El radio de -impacto de un compromiso es la información de la base de datos a la que se -conecta — nada más. - -## Residencia de los datos - -| Clase de datos | Reside en | ¿Sale 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** | -| Configuración, claves de API | Tu base de datos / tu gestor de secretos | **No** | -| Archivos subidos | Tu disco o bucket compatible con S3 | **No** | -| Telemetría / datos de uso | — | **No se recopila nada** | - -ObjectOS realiza **cero llamadas salientes** a menos que las configures -explícitamente (descubrimiento OIDC, proveedor de correo, proveedor de IA, -destinos de webhook, almacenamiento externo). No se conecta a casa, no -consulta un servidor de licencias, no hace ping en busca de actualizaciones. - -## Cifrado - -| Capa | Mecanismo | Responsabilidad | -|---|---|---| -| En tránsito (navegador ↔ ObjectOS) | TLS, terminado en tu edge / ingress | Tú | -| En tránsito (ObjectOS ↔ base de datos) | TLS a nivel de driver (Postgres `sslmode=require`, MongoDB `tls=true`, …) | Tú — define la cadena de conexión | -| En reposo (datos de negocio) | Nativo de la base de datos (p. ej. Postgres TDE, cifrado de RDS) | Tú | -| En reposo (archivos subidos) | Nativo del almacenamiento (S3 SSE, R2 por defecto, FDE a nivel de disco) | Tú | -| Secretos en la BD (configuración, secreto de cliente OIDC) | Cifrados por el servicio de configuración | ObjectOS | -| Cookies de sesión / tokens | Firmados con HMAC mediante `OS_AUTH_SECRET` | ObjectOS | -| Valores de claves de API | **Hasheados** en la BD — una fila de BD filtrada no puede reconstruir la clave | ObjectOS | - -## Autenticación - -Integrada (mediante `@objectstack/plugin-auth`, impulsada por Better Auth): - -- correo/contraseña con verificación + restablecimiento -- gestión de sesiones con revocación -- OAuth social (Google, GitHub, Microsoft, Apple, …) -- OIDC/SSO empresarial (Okta, Entra ID, Keycloak, Ping) -- doble factor (TOTP) -- passkeys / WebAuthn -- enlaces mágicos -- flujo de dispositivo CLI/navegador -- claves de API (hasheadas, con caducidad, revocables, vinculadas a un usuario) - -Consulta [Authentication](/docs/configure/authentication). - -## Autorización - -Aplicación por capas (mediante `@objectstack/plugin-security`): - -1. **Permisos de objeto** — CRUD por objeto y por conjunto de permisos -2. **Seguridad a nivel de fila** — expresiones de política declarativas inyectadas en - las consultas; no es opcional -3. **Seguridad a nivel de campo** — campos eliminados de las respuestas / - rechazados en escritura -4. **Alcance por organización** — aislamiento multiinquilino; omitirlo requiere - `viewAllRecords` explícito - -Las operaciones en contexto de sistema omiten las comprobaciones para que los trabajos -internos / migraciones puedan ejecutarse — estas rutas son auditables. - -Consulta [Permissions](/docs/configure/permissions). - -## Auditoría y evidencias - -Cuando la capacidad de auditoría está cargada (`@objectstack/plugin-audit`): - -- Cada operación CRUD sobre cada objeto → una fila de auditoría. -- Valores anteriores/posteriores de los cambios de campo. -- Eventos de autenticación, concesión de permisos, revocación de sesiones. -- Las filas de auditoría son **inmutables**: no pueden modificarse, solo archivarse. -- La retención es configurable; combínala con la política de archivado de tu BD. - -Esta es la base de evidencias para SOC 2 CC6/CC7, ISO 27001 A.12.4, HIPAA -§164.312(b) y el Artículo 30 del RGPD. - -## Marcos de cumplimiento - -ObjectOS proporciona las **primitivas técnicas** que pide cada marco común. -La certificación es una propiedad del despliegue, no del software — pero los -controles se mapean con claridad: - -| Marco | Qué te aporta ObjectOS | -|---|---| -| **SOC 2** | Control de acceso (CC6), gestión de cambios (registro de auditoría), cifrado (despliegue), monitorización (observabilidad), copias de seguridad (operate/backup) | -| **ISO 27001** | A.5 políticas (RBAC), A.8 gestión de activos (catálogo de objetos), A.9 control de acceso, A.12 operaciones, A.18 cumplimiento | -| **HIPAA** | Controles de acceso (§164.312(a)), controles de auditoría (§164.312(b)), integridad (auditoría inmutable), seguridad en la transmisión (TLS) | -| **RGPD** | Artículo 30 registros de actividades de tratamiento (auditoría), Artículo 32 seguridad del tratamiento, Artículo 17 derecho de supresión (se admite borrado lógico + físico), residencia de datos (tú eliges la región) | -| **CCPA / China DSL / Russia 152-FZ** | El autoalojamiento en la región adecuada satisface la residencia; los controles de acceso + auditoría cubren la mayoría de las obligaciones de reporte | - -ObjectOS en sí **no está certificado** porque la certificación corresponde a un -despliegue en ejecución, no a un binario. Tu despliegue sí puede certificarse — -muchos ya lo están. - -## Manejo de secretos - -| Secreto | Dónde colocarlo | -|---|---| -| `OS_AUTH_SECRET` | Tu gestor de secretos (Vault, AWS Secrets Manager, k8s Secret); inyéctalo como variable de entorno | -| URL de base de datos con credenciales | Igual | -| Secreto de cliente OIDC | Igual | -| Secretos de proveedores OAuth | Igual | -| Claves de proveedores de API (correo, almacenamiento, IA) | Igual | -| Configuración almacenada en la BD | Cifrada en reposo por el servicio de configuración | - -**Nunca** incorpores secretos en el artefacto (`objectstack.json`), la -imagen de Docker, el archivo compose ni en Git. La interfaz de configuración en Console -muestra los valores gestionados por entorno como bloqueados, de modo que los operadores no puedan -sobrescribirlos accidentalmente. - -## Modelo de red - -Entrada requerida: -- HTTPS desde tu ingress / balanceador de carga hacia ObjectOS en `:3000` (por defecto). - -Salida requerida (solo si configuras estas funciones): -- Tu base de datos (Postgres / Mongo / Turso / …). -- Almacenamiento compatible con S3 (si la capacidad `storage` está habilitada con el adaptador de S3). -- URL de descubrimiento OIDC (si SSO está habilitado). -- API del proveedor de correo (Resend / Postmark). -- API del proveedor de IA (OpenAI / Anthropic / Google / …). -- Destinos de webhook. - -Esa es toda la superficie de salida. Consulta [Air-gapped](/docs/deploy/air-gapped) -para despliegues que reducen aún más. - -## IA: herramientas, aprobaciones, aislamiento - -El AI Builder es la superficie más sensible a la seguridad que vas a exponer, -por lo que cuenta con su propia capa de aplicación además de todo lo anterior. - -### Cómo puede la IA modificar el estado - -El modelo **no puede escribir directamente** en tu base de datos. La única manera -de que cambie el estado es emitiendo una llamada estructurada a una herramienta que el servicio -de IA recibe, valida y encola. La cadena: - -```text -user prompt - → model emits tool call (e.g. add_field { object: 'ticket', name: 'severity', type: 'select' }) - → AI service validates payload against the tool's Zod schema - → if the tool is "mutating": queue as pending action (no state change yet) - → human reviewer approves → mutation applied → audit row written - → if the tool is "read-only": run immediately, response returned to model -``` - -Hay 11 herramientas de metadatos de primera parte -([consulta Build → AI Builder](/docs/build/ai-builder)) más una herramienta -`action_` por cada acción declarada. Cada herramienta — de primera parte o -personalizada — tiene el mismo ciclo de vida. - -### Claves de permiso - -| Clave | Concede | -|:--|:--| -| `ai:chat` | Mantener una conversación; consumir modelos; permitir que el agente llame a herramientas de solo lectura | -| `ai:complete` | Endpoint de completado en bruto (sin bucle de agente) | -| `ai:conversations` | Listar / inspeccionar / eliminar conversaciones (propias o todas, según el alcance de RBAC) | -| `ai:agents` | Gestionar metadatos de agentes (junto con `ai:chat` para invocarlos) | -| `ai:tools` | Listar el catálogo de herramientas | -| `ai:execute` | Invocar una herramienta directamente vía REST (avanzado — normalmente solo los agentes ambientales lo necesitan) | -| `ai:read` | Leer la cola de acciones pendientes y la lista de modelos | -| `ai:approve` | Aprobar / rechazar mutaciones encoladas | -| `ai:admin` | Administración completa del servicio de IA | - -La división crítica es **`ai:chat` ≠ `ai:approve`**. Otorga a la mayoría de los usuarios -`ai:chat` para que el asistente funcione; reserva `ai:approve` para los -administradores / propietarios de la aplicación que deban revisar cambios estructurales. Los usuarios -finales pueden, por tanto, "construir al vuelo" de forma segura — lo peor que pueden hacer es -encolar un cambio incorrecto que otra persona debe aceptar. - -### Aislamiento de inquilinos - -- Los agentes, conversaciones, bases de conocimiento y acciones pendientes están - acotados a un único **Environment** (inquilino). El inquilino A no puede ver las - conversaciones del inquilino B, las herramientas que la IA propuso ni los corpus de conocimiento — - incluso si se instaló la misma definición de agente desde el mismo - paquete del marketplace. -- Las herramientas de metadatos (`create_object`, `add_field`, …) operan sobre - el **paquete activo** en el inquilino del llamante. No pueden salir - de él. -- Las entradas de las herramientas se validan con CEL y el motor rechaza referencias a - paquetes de sistema reservados (`sys.*`) o a nombres de objeto de otros inquilinos. - -### Eventos de auditoría - -Cuando la capacidad de auditoría está cargada: - -- `ai.chat.message` — cada mensaje de usuario / asistente, con modelo + recuento de tokens -- `ai.tool.call` — nombre de herramienta, entrada validada, salida completa (o error) -- `ai.pending_action.queued` — mutación propuesta, diff completo -- `ai.pending_action.approved` / `.rejected` — quién decidió, cuándo, por qué -- `ai.metadata.applied` — escritura real en el almacén de metadatos, con diff - -Estas filas son inmutables y pueden exportarse para revisión de seguridad o -imputación de costes. Los recuentos de tokens por (proveedor, modelo, usuario) alimentan la -atribución de costes. - -### Postura frente a la inyección de prompts - -La inyección indirecta de prompts (p. ej. contenido malicioso en un documento que -el agente recupera) es un riesgo real; ObjectOS reduce el radio de impacto por -construcción: - -- La IA **no puede eludir la validación de herramientas** — incluso si se la convence de - emitir una carga maliciosa, el esquema de Zod rechaza las entradas malformadas - antes de que lleguen al motor. -- Las herramientas mutadoras siempre se encolan. Un prompt inyectado no puede escribir - silenciosamente en la base de datos. -- Las llamadas a herramientas heredan los **permisos del usuario final**, no los permisos - de la cuenta de servicio del modelo. Un usuario nunca puede usar la IA para hacer - algo que no pudiera hacer por sí mismo a través de Console o REST. -- Las skills cargadas en los agentes están versionadas y son explícitas — consulta - [Build → IDE Skills](/docs/build/ai-skills) y - [Build → AI Builder](/docs/build/ai-builder). - -### Flujo de datos hacia proveedores de IA externos - -Cuando configuras un proveedor (OpenAI, Anthropic, …), solo lo -siguiente sale de tu red: - -- El historial de conversación que el modelo necesita (sujeto a la configuración - `redact` de tu servicio de IA — consulta [Configure → AI](/docs/configure/ai)) -- Definiciones de herramientas (nombres, esquemas JSON — sin datos de registros) -- Salidas de herramientas que el modelo necesita para continuar (p. ej. el resultado de una consulta - que el usuario solicitó explícitamente) - -Para despliegues air-gapped, apunta el servicio de IA a un endpoint local de Ollama / -vLLM / TGI y el mismo flujo permanece dentro de tu perímetro. - -## Divulgación de vulnerabilidades - -Reporta los problemas de seguridad de forma privada a -**security@objectstack.ai**. Respondemos en un plazo de 1 día hábil. No -abras issues públicas en GitHub para problemas de seguridad. - -## Cadena de suministro - -- Imágenes precompiladas publicadas desde [github.com/objectstack-ai/objectos](https://github.com/objectstack-ai/objectos) - con procedencia de compilación reproducible. -- Todos los paquetes `@objectstack/*` tienen el código fuente publicado en GitHub — - Apache-2.0, sin ofuscación. -- Usa etiquetas de imagen ancladas a SHA (`sha-`) en producción para evitar - desviaciones; consulta [Docker](/docs/deploy/docker). - -## Lista de verificación de endurecimiento sugerida - -- [ ] TLS terminado en el edge con un certificado real. -- [ ] `OS_AUTH_SECRET` tiene 32+ bytes aleatorios, en un gestor de secretos. -- [ ] La conexión a la base de datos usa TLS. -- [ ] HSTS habilitado tras validar TLS. -- [ ] Orígenes CORS explícitos (nunca `*` con credenciales). -- [ ] Límites de tasa en los endpoints de autenticación (`10/min/IP` recomendado). -- [ ] La retención de auditoría coincide con la política. -- [ ] OIDC para cuentas humanas; claves de API para cuentas de máquina. -- [ ] Simulacro de copia de seguridad + restauración ejecutado y cronometrado. -- [ ] Pruebas negativas: acceso entre organizaciones denegado, la seguridad de campo se mantiene, la sesión expirada se rechaza. -- [ ] Imagen anclada a una etiqueta `sha-` o semver. -- [ ] `os doctor` limpio en CI antes de cada release. - -Consulta [Production Readiness](/docs/operate/production) para la lista de -verificación completa de puesta en marcha. diff --git a/content/docs/reference/security.fr.mdx b/content/docs/reference/security.fr.mdx deleted file mode 100644 index d0c11b2..0000000 --- a/content/docs/reference/security.fr.mdx +++ /dev/null @@ -1,278 +0,0 @@ ---- -title: Sécurité et conformité -description: Ce qui est protégé, comment, qui est responsable — pour la revue de sécurité. -translation: - source_sha: 8ef4efaee0f913098534126f549f5d34559d1b3f39a8a4e5fd76e49c9a2d41ff - guide_rev: 1 - mode: auto ---- - -Cette page s'adresse aux examinateurs de sécurité, aux administrateurs IT et à toute personne qui doit -répondre à la question « est-il sûr de l'adopter ? » - -## Le modèle de menace en une phrase - -ObjectOS s'exécute comme un unique processus Node.js à l'intérieur de **votre** réseau, -communique avec **votre** base de données et ne rappelle jamais sa base. Le rayon d'impact d'une -compromission se limite aux données de la base de données à laquelle il se connecte — rien de -plus. - -## Résidence des données - -| Classe de données | Réside dans | Quitte votre réseau ? | -|---|---|---| -| Enregistrements métier | Votre base de données | **Non** | -| Comptes utilisateurs, sessions, jetons OAuth | Votre base de données | **Non** | -| Journal d'audit | Votre base de données | **Non** | -| Paramètres, clés API | Votre base de données / votre gestionnaire de secrets | **Non** | -| Fichiers téléversés | Votre disque ou bucket compatible S3 | **Non** | -| Télémétrie / données d'usage | — | **Aucune collecte** | - -ObjectOS effectue **zéro appel sortant** sauf si vous les configurez explicitement -(découverte OIDC, fournisseur d'e-mail, fournisseur d'IA, cibles de webhook, -stockage externe). Il ne rappelle pas sa base, ne contacte pas un serveur de -licence, ne sonde pas pour des mises à jour. - -## Chiffrement - -| Couche | Mécanisme | Responsabilité | -|---|---|---| -| En transit (navigateur ↔ ObjectOS) | TLS, terminé au niveau de votre edge / ingress | Vous | -| En transit (ObjectOS ↔ base de données) | TLS au niveau du pilote (Postgres `sslmode=require`, MongoDB `tls=true`, …) | Vous — définissez la chaîne de connexion | -| Au repos (données métier) | Natif à la base de données (par ex. Postgres TDE, chiffrement RDS) | Vous | -| Au repos (fichiers téléversés) | Natif au stockage (S3 SSE, R2 par défaut, FDE au niveau du disque) | Vous | -| Secrets en base (paramètres, secret client OIDC) | Chiffrés par le service de paramètres | ObjectOS | -| Cookies / jetons de session | Signés par HMAC avec `OS_AUTH_SECRET` | ObjectOS | -| Valeurs des clés API | **Hachées** en base — une ligne de base fuitée ne permet pas de reconstruire la clé | ObjectOS | - -## Authentification - -Intégrée (via `@objectstack/plugin-auth`, propulsée par Better Auth) : - -- e-mail/mot de passe avec vérification + réinitialisation -- gestion des sessions avec révocation -- OAuth social (Google, GitHub, Microsoft, Apple, …) -- OIDC/SSO d'entreprise (Okta, Entra ID, Keycloak, Ping) -- double authentification (TOTP) -- passkeys / WebAuthn -- liens magiques -- flux d'appareil CLI/navigateur -- clés API (hachées, expirables, révocables, liées à un utilisateur) - -Voir [Authentication](/docs/configure/authentication). - -## Autorisation - -Application en couches (via `@objectstack/plugin-security`) : - -1. **Permissions sur les objets** — CRUD par objet par jeu de permissions -2. **Sécurité au niveau des lignes** — expressions de politique déclaratives injectées dans - les requêtes ; non optionnelle -3. **Sécurité au niveau des champs** — champs retirés des réponses / - rejetés en écriture -4. **Cloisonnement par organisation** — isolation multi-locataire ; le contournement requiert - un `viewAllRecords` explicite - -Les opérations en contexte système contournent les vérifications afin que les tâches internes / migrations -puissent s'exécuter — ces chemins sont auditables. - -Voir [Permissions](/docs/configure/permissions). - -## Audit et preuves - -Lorsque la capacité d'audit est chargée (`@objectstack/plugin-audit`) : - -- Chaque opération CRUD sur chaque objet → ligne d'audit. -- Valeurs avant/après pour les modifications de champs. -- Événements d'authentification, d'attribution de permissions, de révocation de session. -- Les lignes d'audit sont **immuables** : elles ne peuvent être modifiées, seulement archivées. -- La rétention est configurable ; à coupler avec la politique d'archivage de votre base de données. - -C'est la base de preuves pour SOC 2 CC6/CC7, ISO 27001 A.12.4, HIPAA -§164.312(b) et l'article 30 du RGPD. - -## Cadres de conformité - -ObjectOS fournit les **primitives techniques** que chaque cadre courant -demande. La certification est une propriété du déploiement, pas du -logiciel — mais les contrôles s'y rattachent proprement : - -| Cadre | Ce qu'ObjectOS vous apporte | -|---|---| -| **SOC 2** | Contrôle d'accès (CC6), gestion des changements (journal d'audit), chiffrement (déploiement), surveillance (observabilité), sauvegarde (operate/backup) | -| **ISO 27001** | A.5 politiques (RBAC), A.8 gestion des actifs (catalogue d'objets), A.9 contrôle d'accès, A.12 exploitation, A.18 conformité | -| **HIPAA** | Contrôles d'accès (§164.312(a)), contrôles d'audit (§164.312(b)), intégrité (audit immuable), sécurité de la transmission (TLS) | -| **RGPD** | Article 30 registres de traitement (audit), Article 32 sécurité du traitement, Article 17 droit à l'effacement (suppression douce + définitive prises en charge), résidence des données (vous choisissez la région) | -| **CCPA / China DSL / Russia 152-FZ** | L'auto-hébergement dans la bonne région satisfait la résidence ; les contrôles d'accès + l'audit couvrent la plupart des obligations de déclaration | - -ObjectOS lui-même n'est **pas certifié** car la certification porte sur un -déploiement en exécution, et non sur un binaire. Votre déploiement peut être certifié — -beaucoup le sont déjà. - -## Gestion des secrets - -| Secret | Où le placer | -|---|---| -| `OS_AUTH_SECRET` | Votre gestionnaire de secrets (Vault, AWS Secrets Manager, k8s Secret) ; injecté comme variable d'environnement | -| URL de base de données avec identifiants | Idem | -| Secret client OIDC | Idem | -| Secrets de fournisseur OAuth | Idem | -| Clés de fournisseur API (e-mail, stockage, IA) | Idem | -| Paramètres stockés en base | Chiffrés au repos par le service de paramètres | - -**N'intégrez jamais** de secrets dans l'artefact (`objectstack.json`), l' -image Docker, le fichier compose ou Git. L'interface de paramètres dans Console -affiche les valeurs gérées par variables d'environnement comme verrouillées, de sorte que les opérateurs ne puissent pas accidentellement -les remplacer. - -## Modèle réseau - -Entrant requis : -- HTTPS depuis votre ingress / répartiteur de charge vers ObjectOS sur `:3000` (par défaut). - -Sortant requis (uniquement si vous configurez ces fonctionnalités) : -- Votre base de données (Postgres / Mongo / Turso / …). -- Stockage compatible S3 (si la capacité `storage` est activée avec l'adaptateur S3). -- URL de découverte OIDC (si le SSO est activé). -- API de fournisseur d'e-mail (Resend / Postmark). -- API de fournisseur d'IA (OpenAI / Anthropic / Google / …). -- Cibles de webhook. - -Voilà toute la surface de sortie. Voir [Air-gapped](/docs/deploy/air-gapped) -pour des déploiements qui en retranchent encore davantage. - -## IA : outils, approbations, isolation - -L'AI Builder est la surface la plus sensible en matière de sécurité que vous exposerez, -il dispose donc de sa propre couche d'application en plus de tout ce qui précède. - -### Comment l'IA peut modifier l'état - -Le modèle **ne peut pas écrire directement** dans votre base de données. La seule façon dont -l'état change est en émettant un appel d'outil structuré que le service d'IA -reçoit, valide et met en file d'attente. La chaîne : - -```text -user prompt - → model emits tool call (e.g. add_field { object: 'ticket', name: 'severity', type: 'select' }) - → AI service validates payload against the tool's Zod schema - → if the tool is "mutating": queue as pending action (no state change yet) - → human reviewer approves → mutation applied → audit row written - → if the tool is "read-only": run immediately, response returned to model -``` - -Il existe 11 outils de métadonnées de première partie -([voir Build → AI Builder](/docs/build/ai-builder)) plus un -outil `action_` par action déclarée. Chaque outil — de première partie ou -personnalisé — suit le même cycle de vie. - -### Clés de permission - -| Clé | Octroie | -|:--|:--| -| `ai:chat` | Tenir une conversation ; consommer des modèles ; laisser l'agent appeler des outils en lecture seule | -| `ai:complete` | Point de terminaison de complétion brute (sans boucle d'agent) | -| `ai:conversations` | Lister / inspecter / supprimer des conversations (les siennes ou toutes, selon la portée RBAC) | -| `ai:agents` | Gérer les métadonnées d'agent (avec `ai:chat` pour les invoquer) | -| `ai:tools` | Lister le catalogue d'outils | -| `ai:execute` | Invoquer un outil directement via REST (avancé — normalement, seuls les agents ambiants en ont besoin) | -| `ai:read` | Lire la file des actions en attente et la liste des modèles | -| `ai:approve` | Approuver / rejeter les mutations en file d'attente | -| `ai:admin` | Administration complète du service d'IA | - -La distinction critique est **`ai:chat` ≠ `ai:approve`**. Accordez `ai:chat` à la -plupart des utilisateurs pour que l'assistant fonctionne ; réservez `ai:approve` aux -administrateurs / propriétaires d'applications qui doivent examiner les changements structurels. Les utilisateurs -finaux peuvent ainsi « construire à l'instinct » en toute sécurité — au pire, ils peuvent -mettre en file d'attente un mauvais changement que quelqu'un d'autre doit accepter. - -### Isolation des locataires - -- Les agents, conversations, bases de connaissances et actions en attente sont - cloisonnés à un seul **Environment** (locataire). Le locataire A ne peut pas voir les - conversations, les outils proposés par l'IA ou les corpus de connaissances du locataire B — - même si la même définition d'agent a été installée depuis le même - package du marketplace. -- Les outils de métadonnées (`create_object`, `add_field`, …) opèrent sur le - **package actif** dans le locataire de l'appelant. Ils ne peuvent pas en sortir. -- Les entrées d'outils sont validées par CEL et le moteur refuse les références aux - packages système réservés (`sys.*`) ou aux noms d'objets d'autres locataires. - -### Événements d'audit - -Lorsque la capacité d'audit est chargée : - -- `ai.chat.message` — chaque message utilisateur / assistant, avec le modèle + le décompte de jetons -- `ai.tool.call` — nom de l'outil, entrée validée, sortie complète (ou erreur) -- `ai.pending_action.queued` — mutation proposée, diff complet -- `ai.pending_action.approved` / `.rejected` — qui a décidé, quand, pourquoi -- `ai.metadata.applied` — écriture effective dans le magasin de métadonnées, avec diff - -Ces lignes sont immuables et peuvent être exportées pour une revue de sécurité ou -une refacturation. Les décomptes de jetons par (fournisseur, modèle, utilisateur) alimentent l'attribution -des coûts. - -### Posture face à l'injection de prompt - -L'injection de prompt indirecte (par ex. un contenu malveillant dans un document que -l'agent récupère) est un risque réel ; ObjectOS réduit le rayon d'impact par -conception : - -- L'IA **ne peut pas contourner la validation des outils** — même si on la convainc d' - émettre une charge utile malveillante, le schéma Zod rejette les entrées mal formées - avant qu'elles n'atteignent le moteur. -- Les outils mutants sont toujours mis en file d'attente. Un prompt injecté ne peut pas écrire - silencieusement dans la base de données. -- Les appels d'outils héritent des **permissions de l'utilisateur final**, et non des - permissions de compte de service du modèle. Un utilisateur ne peut jamais utiliser l'IA pour faire - quelque chose qu'il ne pourrait pas faire lui-même via Console ou REST. -- Les AI Skills chargées dans les agents sont versionnées et explicites — voir - [Build → IDE Skills](/docs/build/ai-skills) et - [Build → AI Builder](/docs/build/ai-builder). - -### Flux de données vers un fournisseur d'IA externe - -Lorsque vous configurez un fournisseur (OpenAI, Anthropic, …), seuls les -éléments suivants quittent votre réseau : - -- L'historique de conversation dont le modèle a besoin (sous réserve de la configuration `redact` - de votre service d'IA — voir [Configure → AI](/docs/configure/ai)) -- Les définitions d'outils (noms, schémas JSON — aucune donnée d'enregistrement) -- Les sorties d'outils dont le modèle a besoin pour continuer (par ex. un résultat de requête - que l'utilisateur a explicitement demandé) - -Pour les déploiements isolés (air-gapped), pointez le service d'IA vers un point de terminaison local Ollama / -vLLM / TGI et le même flux reste à l'intérieur de votre périmètre. - -## Divulgation des vulnérabilités - -Signalez les problèmes de sécurité de manière privée à -**security@objectstack.ai**. Nous répondons sous 1 jour ouvré. Ne -créez pas d'issues GitHub publiques pour les problèmes de sécurité. - -## Chaîne d'approvisionnement - -- Images préconstruites publiées depuis [github.com/objectstack-ai/objectos](https://github.com/objectstack-ai/objectos) - avec une provenance de build reproductible. -- Tous les packages `@objectstack/*` ont leur source publiée sur GitHub — - Apache-2.0, sans obfuscation. -- Utilisez des tags d'image épinglés par SHA (`sha-`) en production pour éviter la - dérive ; voir [Docker](/docs/deploy/docker). - -## Liste de durcissement suggérée - -- [ ] TLS terminé en périphérie avec un certificat réel. -- [ ] `OS_AUTH_SECRET` fait 32 octets aléatoires ou plus, dans un gestionnaire de secrets. -- [ ] La connexion à la base de données utilise TLS. -- [ ] HSTS activé après validation du TLS. -- [ ] Origines CORS explicites (jamais `*` avec des identifiants). -- [ ] Limitation de débit sur les points de terminaison d'authentification (`10/min/IP` recommandé). -- [ ] La rétention d'audit correspond à la politique. -- [ ] OIDC pour les comptes humains ; clés API pour les comptes machines. -- [ ] Exercice de sauvegarde + restauration exécuté et chronométré. -- [ ] Tests négatifs : accès inter-organisations refusé, sécurité des champs tenue, session expirée rejetée. -- [ ] Image épinglée à un tag `sha-` ou semver. -- [ ] `os doctor` propre en CI avant chaque release. - -Voir [Production Readiness](/docs/operate/production) pour la liste complète -de mise en production. diff --git a/content/docs/reference/security.ja.mdx b/content/docs/reference/security.ja.mdx deleted file mode 100644 index edb9aa5..0000000 --- a/content/docs/reference/security.ja.mdx +++ /dev/null @@ -1,221 +0,0 @@ ---- -title: セキュリティとコンプライアンス -description: 何が、どのように保護され、誰が責任を負うのか — セキュリティレビュー向け。 -translation: - source_sha: 8ef4efaee0f913098534126f549f5d34559d1b3f39a8a4e5fd76e49c9a2d41ff - guide_rev: 1 - mode: auto ---- - -このページは、セキュリティレビュー担当者、IT 管理者、そして「これを導入しても安全か?」に答えなければならないすべての人のためのものです。 - -## ひとことで言う脅威モデル - -ObjectOS は **あなた自身の** ネットワーク内で単一の Node.js プロセスとして動作し、**あなた自身の** データベースと通信し、決して外部へ通信を行いません。侵害が及ぶ影響範囲は、接続先のデータベース上のデータに限られ、それ以上ではありません。 - -## データレジデンシー - -| データ分類 | 保存場所 | ネットワーク外へ出るか? | -|---|---|---| -| 業務レコード | あなたのデータベース | **いいえ** | -| ユーザーアカウント、セッション、OAuth トークン | あなたのデータベース | **いいえ** | -| 監査ログ | あなたのデータベース | **いいえ** | -| 設定、API キー | あなたのデータベース / あなたのシークレットマネージャー | **いいえ** | -| アップロードされたファイル | あなたのディスク、または S3 互換バケット | **いいえ** | -| テレメトリ / 使用状況データ | — | **収集しない** | - -ObjectOS は、明示的に構成しない限り **外部への通信を一切行いません**(OIDC ディスカバリ、メールプロバイダー、AI プロバイダー、Webhook ターゲット、外部ストレージ)。外部へのフォンホームも、ライセンスサーバーの確認も、アップデートの確認も行いません。 - -## 暗号化 - -| レイヤー | メカニズム | 責任者 | -|---|---|---| -| 転送中(ブラウザ ↔ ObjectOS) | TLS、あなたのエッジ / イングレスで終端 | あなた | -| 転送中(ObjectOS ↔ データベース) | ドライバーレベルの TLS(Postgres `sslmode=require`、MongoDB `tls=true`、…) | あなた — 接続文字列を設定 | -| 保存時(業務データ) | データベースネイティブ(例: Postgres TDE、RDS 暗号化) | あなた | -| 保存時(アップロードされたファイル) | ストレージネイティブ(S3 SSE、R2 デフォルト、ディスクレベルの FDE) | あなた | -| DB 内のシークレット(設定、OIDC クライアントシークレット) | 設定サービスによって暗号化 | ObjectOS | -| セッションクッキー / トークン | `OS_AUTH_SECRET` による HMAC 署名 | ObjectOS | -| API キーの値 | DB 内で **ハッシュ化** — DB の行が漏洩してもキーは復元できない | ObjectOS | - -## 認証 - -組み込み機能(`@objectstack/plugin-auth` 経由、Better Auth による): - -- 検証 + リセット付きのメール / パスワード認証 -- 失効機能を備えたセッション管理 -- ソーシャル OAuth(Google、GitHub、Microsoft、Apple、…) -- エンタープライズ OIDC/SSO(Okta、Entra ID、Keycloak、Ping) -- 二要素認証(TOTP) -- パスキー / WebAuthn -- マジックリンク -- CLI / ブラウザのデバイスフロー -- API キー(ハッシュ化、有効期限設定可、失効可、ユーザーに紐付け) - -[認証](/docs/configure/authentication) を参照してください。 - -## 認可 - -階層的な強制(`@objectstack/plugin-security` 経由): - -1. **オブジェクト権限** — パーミッションセットごと、オブジェクトごとの CRUD -2. **行レベルセキュリティ** — クエリに注入される宣言的なポリシー式。省略不可 -3. **フィールドレベルセキュリティ** — レスポンスから除去 / 書き込み時に拒否されるフィールド -4. **組織スコープ** — マルチテナント分離。バイパスには明示的な `viewAllRecords` が必要 - -システムコンテキストの操作はチェックをバイパスするため、内部ジョブ / マイグレーションを実行できます。これらの経路は監査可能です。 - -[権限](/docs/configure/permissions) を参照してください。 - -## 監査とエビデンス - -監査機能がロードされている場合(`@objectstack/plugin-audit`): - -- すべてのオブジェクトにわたるすべての CRUD 操作 → 監査行。 -- フィールド変更の前後の値。 -- 認証、権限付与、セッション失効イベント。 -- 監査行は **イミュータブル** です。変更はできず、アーカイブのみ可能です。 -- 保持期間は構成可能です。DB のアーカイブポリシーと組み合わせてください。 - -これは SOC 2 CC6/CC7、ISO 27001 A.12.4、HIPAA §164.312(b)、GDPR 第 30 条のエビデンス基盤となります。 - -## コンプライアンスフレームワーク - -ObjectOS は、一般的なフレームワークが求める **技術的なプリミティブ** を提供します。認証はデプロイメントの属性であってソフトウェアの属性ではありませんが、コントロールはきれいにマッピングできます。 - -| フレームワーク | ObjectOS が提供するもの | -|---|---| -| **SOC 2** | アクセス制御(CC6)、変更管理(監査ログ)、暗号化(デプロイメント)、モニタリング(可観測性)、バックアップ(operate/backup) | -| **ISO 27001** | A.5 ポリシー(RBAC)、A.8 資産管理(オブジェクトカタログ)、A.9 アクセス制御、A.12 運用、A.18 コンプライアンス | -| **HIPAA** | アクセス制御(§164.312(a))、監査制御(§164.312(b))、完全性(イミュータブルな監査)、伝送セキュリティ(TLS) | -| **GDPR** | 第 30 条 処理活動の記録(監査)、第 32 条 処理のセキュリティ、第 17 条 消去権(ソフト削除 + ハード削除に対応)、データレジデンシー(リージョンを自分で選択) | -| **CCPA / 中国 DSL / ロシア 152-FZ** | 適切なリージョンでのセルフホスティングがレジデンシーを満たす。アクセス制御 + 監査がほとんどの報告義務をカバー | - -ObjectOS そのものは **認証を取得していません**。認証は実行中のデプロイメントに対するものであって、バイナリに対するものではないためです。あなたのデプロイメントは認証を取得でき、すでに多くが取得しています。 - -## シークレットの取り扱い - -| シークレット | 配置場所 | -|---|---| -| `OS_AUTH_SECRET` | あなたのシークレットマネージャー(Vault、AWS Secrets Manager、k8s Secret)。環境変数として注入 | -| 認証情報を含むデータベース URL | 同上 | -| OIDC クライアントシークレット | 同上 | -| OAuth プロバイダーシークレット | 同上 | -| API プロバイダーキー(メール、ストレージ、AI) | 同上 | -| DB に保存される設定 | 設定サービスによって保存時に暗号化 | - -シークレットをアーティファクト(`objectstack.json`)、Docker イメージ、compose ファイル、Git に **決して** 焼き込まないでください。Console の設定 UI は環境変数で管理される値をロックして表示するため、オペレーターが誤って上書きすることはありません。 - -## ネットワークモデル - -必須のインバウンド: -- あなたのイングレス / ロードバランサーから ObjectOS への HTTPS、ポート `:3000`(デフォルト)。 - -必須のアウトバウンド(これらの機能を構成する場合のみ): -- あなたのデータベース(Postgres / Mongo / Turso / …)。 -- S3 互換ストレージ(S3 アダプターで `storage` 機能を有効にした場合)。 -- OIDC ディスカバリ URL(SSO を有効にした場合)。 -- メールプロバイダー API(Resend / Postmark)。 -- AI プロバイダー API(OpenAI / Anthropic / Google / …)。 -- Webhook ターゲット。 - -これがエグレスサーフェスのすべてです。さらに削減するデプロイメントについては [エアギャップ](/docs/deploy/air-gapped) を参照してください。 - -## AI: ツール、承認、分離 - -AI Builder は、あなたが公開する最もセキュリティに敏感なサーフェスであるため、上記すべてに加えて独自の強制レイヤーを備えています。 - -### AI が状態を変更する仕組み - -モデルはあなたのデータベースに **直接書き込むことはできません**。状態が変化する唯一の方法は、AI サービスが受信、検証、キューイングする構造化されたツールコールを発行することです。その連鎖は次のとおりです。 - -```text -user prompt - → model emits tool call (e.g. add_field { object: 'ticket', name: 'severity', type: 'select' }) - → AI service validates payload against the tool's Zod schema - → if the tool is "mutating": queue as pending action (no state change yet) - → human reviewer approves → mutation applied → audit row written - → if the tool is "read-only": run immediately, response returned to model -``` - -11 個のファーストパーティのメタデータツール([Build → AI Builder を参照](/docs/build/ai-builder))に加え、宣言された各アクションごとに 1 つの `action_` ツールがあります。すべてのツール — ファーストパーティであれカスタムであれ — は同じライフサイクルを持ちます。 - -### パーミッションキー - -| キー | 付与する権限 | -|:--|:--| -| `ai:chat` | 会話を保持する。モデルを消費する。エージェントに読み取り専用ツールを呼び出させる | -| `ai:complete` | 生の補完エンドポイント(エージェントループなし) | -| `ai:conversations` | 会話の一覧 / 検査 / 削除(RBAC スコープに応じて自分のものまたはすべて) | -| `ai:agents` | エージェントメタデータの管理(呼び出すには `ai:chat` と併用) | -| `ai:tools` | ツールカタログの一覧表示 | -| `ai:execute` | REST 経由でツールを直接呼び出す(上級者向け — 通常はアンビエントエージェントのみが必要) | -| `ai:read` | 保留中アクションのキューとモデル一覧の読み取り | -| `ai:approve` | キューイングされたミューテーションの承認 / 却下 | -| `ai:admin` | AI サービスの完全な管理 | - -重要な区別は **`ai:chat` ≠ `ai:approve`** です。アシスタントが機能するように、ほとんどのユーザーには `ai:chat` を付与してください。`ai:approve` は、構造的な変更をレビューすべき管理者 / アプリ所有者のために確保してください。これにより、エンドユーザーは安全に「バイブビルド」できます。最悪の場合でも、他の誰かが受け入れなければならない不適切な変更をキューに入れるだけです。 - -### テナント分離 - -- エージェント、会話、ナレッジベース、保留中アクションは、1 つの **Environment**(テナント)にスコープされます。同じ marketplace パッケージから同じエージェント定義がインストールされていたとしても、テナント A はテナント B の会話、AI が提案したツール、ナレッジコーパスを見ることはできません。 -- メタデータツール(`create_object`、`add_field`、…)は、呼び出し元のテナント内の **アクティブパッケージ** に対して動作します。その外には到達できません。 -- ツール入力は CEL で検証され、エンジンは予約済みのシステムパッケージ(`sys.*`)や他テナントのオブジェクト名への参照を拒否します。 - -### 監査イベント - -監査機能がロードされている場合: - -- `ai.chat.message` — すべてのユーザー / アシスタントメッセージ、モデル + トークン数付き -- `ai.tool.call` — ツール名、検証済み入力、完全な出力(またはエラー) -- `ai.pending_action.queued` — 提案されたミューテーション、完全な差分 -- `ai.pending_action.approved` / `.rejected` — 誰が、いつ、なぜ決定したか -- `ai.metadata.applied` — メタデータストアへの実際の書き込み、差分付き - -これらの行はイミュータブルであり、セキュリティレビューやチャージバックのためにエクスポートできます。(プロバイダー、モデル、ユーザー)ごとのトークン数はコスト配賦に利用されます。 - -### プロンプトインジェクションへの姿勢 - -間接プロンプトインジェクション(例: エージェントが取得するドキュメント内の悪意あるコンテンツ)は現実的なリスクです。ObjectOS は構造上、影響範囲を低減します。 - -- AI は **ツール検証をバイパスできません**。悪意あるペイロードを発行するよう仕向けられたとしても、Zod スキーマが不正な入力をエンジンに到達する前に拒否します。 -- ミューテーションを行うツールは常にキューイングされます。注入されたプロンプトが密かにデータベースへ書き込むことはできません。 -- ツールコールは、モデルのサービスアカウントの権限ではなく、**エンドユーザーの権限** を継承します。ユーザーは、Console や REST で自分ができないことを AI を使って行うことは決してできません。 -- エージェントにロードされる Skills はバージョン管理され、明示的です。[Build → IDE Skills](/docs/build/ai-skills) および [Build → AI Builder](/docs/build/ai-builder) を参照してください。 - -### 外部 AI プロバイダーのデータフロー - -プロバイダー(OpenAI、Anthropic、…)を構成した場合、ネットワークから出るのは次のものだけです。 - -- モデルが必要とする会話履歴(AI サービスの `redact` 設定に従う — [Configure → AI](/docs/configure/ai) を参照) -- ツール定義(名前、JSON スキーマ — レコードデータは含まない) -- モデルが続行するために必要なツール出力(例: ユーザーが明示的に要求したクエリ結果) - -エアギャップデプロイメントの場合、AI サービスをローカルの Ollama / vLLM / TGI エンドポイントに向ければ、同じフローがあなたの境界内に留まります。 - -## 脆弱性の開示 - -セキュリティ問題は **security@objectstack.ai** へ非公開で報告してください。営業日 1 日以内に対応します。セキュリティ上の問題について、公開された GitHub issue を作成しないでください。 - -## サプライチェーン - -- 事前ビルドされたイメージは [github.com/objectstack-ai/objectos](https://github.com/objectstack-ai/objectos) から、再現可能なビルドプロビナンス付きで公開されています。 -- すべての `@objectstack/*` パッケージは GitHub 上でソースが公開されています — Apache-2.0、難読化なし。 -- 本番環境では SHA 固定のイメージタグ(`sha-`)を使用してドリフトを回避してください。[Docker](/docs/deploy/docker) を参照してください。 - -## 推奨ハードニングチェックリスト - -- [ ] エッジで TLS を本物の証明書で終端している。 -- [ ] `OS_AUTH_SECRET` は 32 バイト以上のランダム値で、シークレットマネージャーに保管されている。 -- [ ] データベース接続が TLS を使用している。 -- [ ] TLS 検証後に HSTS を有効化している。 -- [ ] CORS オリジンが明示的である(認証情報付きで `*` を使用していない)。 -- [ ] 認証エンドポイントにレート制限がかかっている(`10/min/IP` を推奨)。 -- [ ] 監査の保持期間がポリシーに合致している。 -- [ ] 人間のアカウントには OIDC、マシンアカウントには API キーを使用している。 -- [ ] バックアップ + リストアの訓練を実施し、所要時間を計測している。 -- [ ] ネガティブテスト: クロス組織アクセスが拒否される、フィールドセキュリティが維持される、期限切れセッションが拒否される。 -- [ ] イメージが `sha-` または semver タグに固定されている。 -- [ ] 各リリース前に CI で `os doctor` がクリーンである。 - -本番稼働の完全なチェックリストについては [本番準備](/docs/operate/production) を参照してください。 diff --git a/content/docs/reference/security.ko.mdx b/content/docs/reference/security.ko.mdx deleted file mode 100644 index 977f45b..0000000 --- a/content/docs/reference/security.ko.mdx +++ /dev/null @@ -1,273 +0,0 @@ ---- -title: 보안 및 규정 준수 -description: 무엇이, 어떻게, 누구의 책임 하에 보호되는지 — 보안 검토를 위한 안내입니다. -translation: - source_sha: 8ef4efaee0f913098534126f549f5d34559d1b3f39a8a4e5fd76e49c9a2d41ff - guide_rev: 1 - mode: auto ---- - -이 페이지는 보안 검토 담당자, IT 관리자, 그리고 "이것을 도입해도 안전한가?"에 -답해야 하는 모든 사람을 위한 것입니다. - -## 한 문장으로 보는 위협 모델 - -ObjectOS는 **당신의** 네트워크 내부에서 단일 Node.js 프로세스로 실행되며, -**당신의** 데이터베이스와 통신하고, 절대 외부로 연락(call home)하지 않습니다. -침해가 발생했을 때의 피해 범위(blast radius)는 연결된 데이터베이스의 -데이터에 한정됩니다 — 그 이상은 없습니다. - -## 데이터 레지던시 - -| 데이터 분류 | 저장 위치 | 네트워크를 벗어나는가? | -|---|---|---| -| 비즈니스 레코드 | 당신의 데이터베이스 | **아니요** | -| 사용자 계정, 세션, OAuth 토큰 | 당신의 데이터베이스 | **아니요** | -| 감사 로그 | 당신의 데이터베이스 | **아니요** | -| 설정, API 키 | 당신의 데이터베이스 / 당신의 시크릿 매니저 | **아니요** | -| 업로드된 파일 | 당신의 디스크 또는 S3 호환 버킷 | **아니요** | -| 텔레메트리 / 사용 데이터 | — | **수집하지 않음** | - -ObjectOS는 명시적으로 구성하지 않는 한 **외부로의 호출을 전혀 하지 -않습니다**(OIDC 디스커버리, 이메일 공급자, AI 공급자, 웹훅 대상, -외부 스토리지). 외부로 연락하지 않고, 라이선스 서버를 확인하지 않으며, -업데이트를 위해 핑을 보내지도 않습니다. - -## 암호화 - -| 계층 | 메커니즘 | 책임 주체 | -|---|---|---| -| 전송 중 (브라우저 ↔ ObjectOS) | TLS, 당신의 엣지 / 인그레스에서 종료 | 당신 | -| 전송 중 (ObjectOS ↔ 데이터베이스) | 드라이버 수준 TLS (Postgres `sslmode=require`, MongoDB `tls=true`, …) | 당신 — 연결 문자열을 설정 | -| 저장 시 (비즈니스 데이터) | 데이터베이스 네이티브 (예: Postgres TDE, RDS 암호화) | 당신 | -| 저장 시 (업로드된 파일) | 스토리지 네이티브 (S3 SSE, R2 기본값, 디스크 수준 FDE) | 당신 | -| DB 내 시크릿 (설정, OIDC 클라이언트 시크릿) | 설정 서비스에 의해 암호화됨 | ObjectOS | -| 세션 쿠키 / 토큰 | `OS_AUTH_SECRET`로 HMAC 서명됨 | ObjectOS | -| API 키 값 | DB에 **해시 처리됨** — 유출된 DB 행으로는 키를 복원할 수 없음 | ObjectOS | - -## 인증 - -기본 제공 (`@objectstack/plugin-auth`를 통해, Better Auth 기반): - -- 검증 + 재설정이 포함된 이메일/비밀번호 -- 취소(revocation) 기능이 있는 세션 관리 -- 소셜 OAuth (Google, GitHub, Microsoft, Apple, …) -- 엔터프라이즈 OIDC/SSO (Okta, Entra ID, Keycloak, Ping) -- 2단계 인증 (TOTP) -- 패스키 / WebAuthn -- 매직 링크 -- CLI/브라우저 디바이스 플로우 -- API 키 (해시 처리됨, 만료 가능, 취소 가능, 사용자에 바인딩됨) - -[Authentication](/docs/configure/authentication)을 참조하세요. - -## 권한 부여 - -계층화된 적용 (`@objectstack/plugin-security`를 통해): - -1. **오브젝트 권한** — 권한 집합별, 오브젝트별 CRUD -2. **행 수준 보안** — 쿼리에 주입되는 선언적 정책 표현식이며, - 선택 사항이 아닙니다 -3. **필드 수준 보안** — 응답에서 제거되거나 쓰기 시 거부되는 필드 -4. **조직 범위 지정** — 멀티 테넌트 격리; 우회하려면 명시적인 - `viewAllRecords`가 필요함 - -시스템 컨텍스트 작업은 내부 작업 / 마이그레이션이 실행될 수 있도록 -검사를 우회합니다 — 이러한 경로는 감사 가능합니다. - -[Permissions](/docs/configure/permissions)을 참조하세요. - -## 감사 및 증거 - -감사 기능이 로드되면 (`@objectstack/plugin-audit`): - -- 모든 오브젝트에 걸친 모든 CRUD 작업 → 감사 행. -- 필드 변경에 대한 변경 전/후 값. -- 인증, 권한 부여, 세션 취소 이벤트. -- 감사 행은 **불변(immutable)**입니다: 수정할 수 없으며 아카이브만 가능합니다. -- 보존 기간은 구성 가능하며, DB의 아카이브 정책과 함께 사용하세요. - -이것은 SOC 2 CC6/CC7, ISO 27001 A.12.4, HIPAA §164.312(b), GDPR 제30조에 -대한 증거 기반이 됩니다. - -## 규정 준수 프레임워크 - -ObjectOS는 모든 일반적인 프레임워크가 요구하는 **기술적 기본 요소(primitives)**를 -제공합니다. 인증(certification)은 소프트웨어가 아닌 배포의 속성이지만, -컨트롤은 깔끔하게 매핑됩니다: - -| 프레임워크 | ObjectOS가 제공하는 것 | -|---|---| -| **SOC 2** | 접근 제어 (CC6), 변경 관리 (감사 로그), 암호화 (배포), 모니터링 (옵저버빌리티), 백업 (운영/백업) | -| **ISO 27001** | A.5 정책 (RBAC), A.8 자산 관리 (오브젝트 카탈로그), A.9 접근 제어, A.12 운영, A.18 준수 | -| **HIPAA** | 접근 제어 (§164.312(a)), 감사 제어 (§164.312(b)), 무결성 (불변 감사), 전송 보안 (TLS) | -| **GDPR** | 제30조 처리 기록 (감사), 제32조 처리의 보안, 제17조 삭제권 (소프트 + 하드 삭제 지원), 데이터 레지던시 (리전을 선택) | -| **CCPA / 중국 DSL / 러시아 152-FZ** | 올바른 리전에서의 셀프 호스팅이 레지던시 요건을 충족하며, 접근 제어 + 감사가 대부분의 보고 의무를 커버합니다 | - -ObjectOS 자체는 **인증되지 않았습니다**. 인증은 바이너리가 아닌 실행 중인 -배포에 대한 것이기 때문입니다. 당신의 배포는 인증받을 수 있으며 — -이미 인증받은 곳도 많습니다. - -## 시크릿 처리 - -| 시크릿 | 보관 위치 | -|---|---| -| `OS_AUTH_SECRET` | 당신의 시크릿 매니저 (Vault, AWS Secrets Manager, k8s Secret); 환경 변수로 주입 | -| 자격 증명이 포함된 데이터베이스 URL | 위와 동일 | -| OIDC 클라이언트 시크릿 | 위와 동일 | -| OAuth 공급자 시크릿 | 위와 동일 | -| API 공급자 키 (이메일, 스토리지, AI) | 위와 동일 | -| DB에 저장된 설정 | 설정 서비스에 의해 저장 시 암호화됨 | - -시크릿을 아티팩트(`objectstack.json`), Docker 이미지, compose 파일, 또는 -Git에 절대 **포함하지 마세요**. Console의 설정 UI는 환경 변수로 관리되는 -값을 잠금 상태로 표시하므로, 운영자가 실수로 이를 재정의할 수 없습니다. - -## 네트워크 모델 - -필수 인바운드: -- 당신의 인그레스 / 로드 밸런서에서 ObjectOS의 `:3000`(기본값)으로의 HTTPS. - -필수 아웃바운드 (다음 기능을 구성하는 경우에만): -- 당신의 데이터베이스 (Postgres / Mongo / Turso / …). -- S3 호환 스토리지 (`storage` 기능이 S3 어댑터와 함께 활성화된 경우). -- OIDC 디스커버리 URL (SSO가 활성화된 경우). -- 이메일 공급자 API (Resend / Postmark). -- AI 공급자 API (OpenAI / Anthropic / Google / …). -- 웹훅 대상. - -이것이 전체 이그레스(egress) 표면입니다. 이보다 더 많은 것을 차단하는 -배포에 대해서는 [Air-gapped](/docs/deploy/air-gapped)를 참조하세요. - -## AI: 도구, 승인, 격리 - -AI Builder는 당신이 노출하게 될 가장 보안에 민감한 표면이므로, 위의 -모든 것에 더해 자체적인 적용 계층을 가지고 있습니다. - -### AI가 상태를 변경하는 방법 - -모델은 당신의 데이터베이스에 **직접 쓸 수 없습니다**. 상태가 변경되는 -유일한 방법은 구조화된 도구 호출을 발행하는 것이며, AI 서비스가 이를 -수신하고, 검증하고, 큐에 넣습니다. 그 연쇄 과정은 다음과 같습니다: - -```text -user prompt - → model emits tool call (e.g. add_field { object: 'ticket', name: 'severity', type: 'select' }) - → AI service validates payload against the tool's Zod schema - → if the tool is "mutating": queue as pending action (no state change yet) - → human reviewer approves → mutation applied → audit row written - → if the tool is "read-only": run immediately, response returned to model -``` - -11개의 기본(first-party) 메타데이터 도구 -([Build → AI Builder 참조](/docs/build/ai-builder))와 더불어, 선언된 -액션당 하나의 `action_` 도구가 있습니다. 모든 도구 — 기본이든 -커스텀이든 — 는 동일한 생명 주기를 갖습니다. - -### 권한 키 - -| 키 | 부여 내용 | -|:--|:--| -| `ai:chat` | 대화 진행; 모델 소비; 에이전트가 읽기 전용 도구를 호출하도록 허용 | -| `ai:complete` | 원시 컴플리션 엔드포인트 (에이전트 루프 없음) | -| `ai:conversations` | 대화 목록 조회 / 검사 / 삭제 (RBAC 범위에 따라 본인 또는 전체) | -| `ai:agents` | 에이전트 메타데이터 관리 (호출하려면 `ai:chat`과 함께) | -| `ai:tools` | 도구 카탈로그 목록 조회 | -| `ai:execute` | REST를 통해 도구를 직접 호출 (고급 — 보통 앰비언트 에이전트만 필요) | -| `ai:read` | 대기 중 액션 큐 및 모델 목록 읽기 | -| `ai:approve` | 큐에 들어간 변경 승인 / 거부 | -| `ai:admin` | 전체 AI 서비스 관리 | - -핵심적인 구분은 **`ai:chat` ≠ `ai:approve`**입니다. 어시스턴트가 작동하도록 -대부분의 사용자에게 `ai:chat`을 부여하고, 구조적 변경을 검토해야 하는 -관리자 / 앱 소유자에게는 `ai:approve`를 따로 두세요. 따라서 최종 사용자는 -안전하게 "바이브 빌드(vibe-build)"할 수 있습니다 — 그들이 할 수 있는 최악의 -일은 다른 누군가가 수락해야 하는 잘못된 변경을 큐에 넣는 것뿐입니다. - -### 테넌트 격리 - -- 에이전트, 대화, 지식 베이스, 대기 중 액션은 하나의 **Environment**(테넌트)로 - 범위가 지정됩니다. 테넌트 A는 테넌트 B의 대화, AI가 제안한 도구, 또는 - 지식 코퍼스를 볼 수 없습니다 — 동일한 marketplace 패키지에서 동일한 - 에이전트 정의가 설치되었더라도 마찬가지입니다. -- 메타데이터 도구(`create_object`, `add_field`, …)는 호출자의 테넌트 내 - **활성 패키지**에 대해 작동합니다. 그 외부에는 도달할 수 없습니다. -- 도구 입력은 CEL로 검증되며, 엔진은 예약된 시스템 패키지(`sys.*`) 또는 - 다른 테넌트의 오브젝트 이름에 대한 참조를 거부합니다. - -### 감사 이벤트 - -감사 기능이 로드되면: - -- `ai.chat.message` — 모든 사용자 / 어시스턴트 메시지, 모델 + 토큰 수 포함 -- `ai.tool.call` — 도구 이름, 검증된 입력, 전체 출력 (또는 오류) -- `ai.pending_action.queued` — 제안된 변경, 전체 diff -- `ai.pending_action.approved` / `.rejected` — 누가, 언제, 왜 결정했는지 -- `ai.metadata.applied` — 메타데이터 스토어에 대한 실제 쓰기, diff 포함 - -이 행들은 불변이며 보안 검토나 차지백(chargeback)을 위해 내보낼 수 -있습니다. (공급자, 모델, 사용자)별 토큰 수는 비용 귀속(cost attribution)에 -활용됩니다. - -### 프롬프트 인젝션 대응 태세 - -간접 프롬프트 인젝션(예: 에이전트가 검색하는 문서 내의 악성 콘텐츠)은 -실제 위험입니다. ObjectOS는 구조적으로 피해 범위를 줄입니다: - -- AI는 **도구 검증을 우회할 수 없습니다** — 악성 페이로드를 발행하도록 - 설득당하더라도, Zod 스키마가 엔진에 도달하기 전에 잘못된 입력을 - 거부합니다. -- 변경(mutating) 도구는 항상 큐에 들어갑니다. 주입된 프롬프트는 - 조용히 데이터베이스에 쓸 수 없습니다. -- 도구 호출은 모델의 서비스 계정 권한이 아닌 **최종 사용자의 권한**을 - 상속합니다. 사용자는 Console이나 REST를 통해 스스로 할 수 없는 일을 - AI를 사용해 결코 할 수 없습니다. -- 에이전트에 로드된 스킬은 버전 관리되고 명시적입니다 — - [Build → IDE Skills](/docs/build/ai-skills)와 - [Build → AI Builder](/docs/build/ai-builder)를 참조하세요. - -### 외부 AI 공급자 데이터 흐름 - -공급자(OpenAI, Anthropic, …)를 구성하면, 다음 항목만 당신의 네트워크를 -벗어납니다: - -- 모델이 필요로 하는 대화 기록 (당신의 AI 서비스 `redact` 구성에 따름 — - [Configure → AI](/docs/configure/ai) 참조) -- 도구 정의 (이름, JSON 스키마 — 레코드 데이터 없음) -- 모델이 계속 진행하는 데 필요한 도구 출력 (예: 사용자가 명시적으로 - 요청한 쿼리 결과) - -에어갭 배포의 경우, AI 서비스를 로컬 Ollama / vLLM / TGI 엔드포인트로 -지정하면 동일한 흐름이 당신의 경계 내부에 머무릅니다. - -## 취약점 공개 - -보안 문제는 **security@objectstack.ai**로 비공개로 신고하세요. 영업일 기준 -1일 이내에 응답합니다. 보안 문제에 대해 공개 GitHub 이슈를 작성하지 마세요. - -## 공급망 - -- [github.com/objectstack-ai/objectos](https://github.com/objectstack-ai/objectos)에서 - 재현 가능한 빌드 출처(provenance)와 함께 게시된 사전 빌드 이미지. -- 모든 `@objectstack/*` 패키지는 GitHub에 소스가 공개되어 있습니다 — - Apache-2.0, 난독화 없음. -- 드리프트를 방지하기 위해 프로덕션에서는 SHA로 고정된 이미지 태그 - (`sha-`)를 사용하세요. [Docker](/docs/deploy/docker)를 참조하세요. - -## 권장 하드닝 체크리스트 - -- [ ] 실제 인증서로 엣지에서 TLS 종료. -- [ ] `OS_AUTH_SECRET`은 32바이트 이상의 랜덤 값이며, 시크릿 매니저에 보관됨. -- [ ] 데이터베이스 연결이 TLS를 사용함. -- [ ] TLS 검증 후 HSTS 활성화됨. -- [ ] CORS 오리진이 명시적임 (자격 증명과 함께 `*`를 절대 사용하지 않음). -- [ ] 인증 엔드포인트에 속도 제한 적용 (`10/min/IP` 권장). -- [ ] 감사 보존 기간이 정책과 일치함. -- [ ] 사람 계정에는 OIDC; 머신 계정에는 API 키. -- [ ] 백업 + 복원 훈련을 실행하고 시간을 측정함. -- [ ] 네거티브 테스트: 조직 간 접근 거부, 필드 보안 유지, 만료된 세션 거부. -- [ ] 이미지가 `sha-` 또는 semver 태그로 고정됨. -- [ ] 각 릴리스 전 CI에서 `os doctor`가 깨끗함. - -전체 출시 체크리스트는 [Production Readiness](/docs/operate/production)를 -참조하세요. diff --git a/content/docs/reference/security.mdx b/content/docs/reference/security.mdx index 1ed62fe..e5fc364 100644 --- a/content/docs/reference/security.mdx +++ b/content/docs/reference/security.mdx @@ -8,13 +8,20 @@ answer "is it safe to bring this in?" ## Threat model in one sentence -ObjectOS runs as a single Node.js process inside **your** network, -talks to **your** database, and never calls home. The blast radius of -a compromise is the data on the database it connects to — nothing -more. +ObjectOS runs as a single Node.js process that talks to one database — +inside **your** network on **ObjectOS Enterprise**, in ours on **ObjectOS +Cloud**. Self-managed, its only outbound call of its own is licence +validation, and Enterprise air-gapped licences validate offline. The blast +radius of a compromise is the data on the database it connects to — +nothing more. ## Data residency +This table describes **ObjectOS Enterprise**, the self-managed edition. On +**ObjectOS Cloud** the same classes of data live in the infrastructure we +operate for you, and on either edition your ontology is exportable to the +open-source ObjectStack runtime. + | Data class | Lives in | Leaves your network? | |---|---|---| | Business records | Your database | **No** | @@ -24,10 +31,11 @@ more. | Uploaded files | Your disk or S3-compatible bucket | **No** | | Telemetry / usage data | — | **None collected** | -ObjectOS makes **zero outbound calls** unless you explicitly configure -them (OIDC discovery, email provider, AI provider, webhook targets, -external storage). It does not phone home, does not check a license -server, does not ping for updates. +Beyond the integrations you explicitly configure (OIDC discovery, email +provider, AI provider, webhook targets, external storage), the one outbound +call self-managed ObjectOS makes on its own is **licence validation** — +Enterprise air-gapped licences validate offline, so an air-gapped +deployment makes none. See [License & Pricing](/docs/resources/license#faq). ## Encryption @@ -129,7 +137,7 @@ software — but the controls map cleanly: | **ISO 27001** | A.5 policies (RBAC), A.8 asset management (object catalog), A.9 access control, A.12 operations, A.18 compliance | | **HIPAA** | Access controls (§164.312(a)), audit controls (§164.312(b)), integrity (immutable audit), transmission security (TLS) | | **GDPR** | Article 30 records of processing (audit), Article 32 security of processing, Article 17 right to erasure (soft + hard delete supported), data residency (you choose the region) | -| **CCPA / China DSL / Russia 152-FZ** | Self-hosting in the right region satisfies residency; access controls + audit cover most reporting obligations | +| **CCPA / China DSL / Russia 152-FZ** | ObjectOS Enterprise in the right region satisfies residency; access controls + audit cover most reporting obligations | ObjectOS itself is **not certified** because the certification is of a running deployment, not a binary. Your deployment can be certified — @@ -156,7 +164,11 @@ override them. Required inbound: - HTTPS from your ingress / load balancer to ObjectOS on `:3000` (default). -Required outbound (only if you configure these features): +Required outbound: +- Licence validation, for self-managed ObjectOS — Enterprise air-gapped + licences validate offline and need no egress for it. + +Required outbound only if you configure these features: - Your database (Postgres / Mongo / Turso / …). - S3-compatible storage (if `storage` capability enabled with S3 adapter). - OIDC discovery URL (if SSO enabled). diff --git a/content/docs/reference/security.zh-Hans.mdx b/content/docs/reference/security.zh-Hans.mdx deleted file mode 100644 index e8082b0..0000000 --- a/content/docs/reference/security.zh-Hans.mdx +++ /dev/null @@ -1,233 +0,0 @@ ---- -title: 安全与合规 -description: 保护什么、如何保护、谁负责 —— 供安全评审。 -translation: - source_sha: 8ef4efaee0f913098534126f549f5d34559d1b3f39a8a4e5fd76e49c9a2d41ff - guide_rev: 1 - mode: auto ---- - -本页面面向安全评审者、IT 管理员,以及需要回答"引入它安全吗?"的任何人。 - -## 一句话威胁模型 - -ObjectOS 作为单个 Node.js 进程运行在**你**的网络内,与**你**的数据库通信,从不回传。被攻破的爆炸半径即其连接的数据库上的数据 —— 仅此而已。 - -## 数据驻留 - -| 数据类别 | 存放在 | 是否离开你的网络? | -|---|---|---| -| 业务记录 | 你的数据库 | **否** | -| 用户账户、会话、OAuth token | 你的数据库 | **否** | -| 审计日志 | 你的数据库 | **否** | -| 设置、API key | 你的数据库 / 你的密钥管理器 | **否** | -| 上传文件 | 你的磁盘或 S3 兼容存储桶 | **否** | -| 遥测/使用数据 | — | **不收集** | - -ObjectOS **零外发调用**,除非你显式配置（OIDC discovery、邮件提供商、AI 提供商、webhook 目标、外部存储）。它不回传、不查 license server、不轮询更新。 - -## 加密 - -| 层 | 机制 | 责任方 | -|---|---|---| -| 传输中（浏览器 ↔ ObjectOS） | TLS,在你的 edge / ingress 终结 | 你 | -| 传输中（ObjectOS ↔ 数据库） | 驱动级 TLS（Postgres `sslmode=require`、MongoDB `tls=true`……） | 你 —— 设置连接字符串 | -| 静态（业务数据） | 数据库原生（如 Postgres TDE、RDS encryption） | 你 | -| 静态（上传文件） | 存储原生（S3 SSE、R2 默认、磁盘级 FDE） | 你 | -| DB 中密钥（settings、OIDC client secret） | 由 settings 服务加密 | ObjectOS | -| 会话 cookie / token | 用 `OS_AUTH_SECRET` 进行 HMAC 签名 | ObjectOS | -| API key 值 | DB 中**哈希存储** —— 泄露的 DB 行无法重建 key | ObjectOS | - -## 认证 - -内置（通过 `@objectstack/plugin-auth`,基于 Better Auth）： - -- 带验证 + 重置的邮箱/密码 -- 带撤销的会话管理 -- Social OAuth（Google、GitHub、Microsoft、Apple……） -- 企业 OIDC/SSO（Okta、Entra ID、Keycloak、Ping） -- 双因素（TOTP） -- Passkey / WebAuthn -- 魔法链接 -- 手机号 + 短信 OTP 登录与密码重置（通过 `auth.plugins.phoneNumber` 显式开启;支持阿里云 / Twilio 通道,自带限流） -- CLI/浏览器设备流 -- API key（哈希、可过期、可撤销、绑定到用户） -- 面向 MCP 客户端的自助 OAuth 2.1（授权码 + PKCE、动态客户端注册、按 scope 推导权限上限） -- 管理员直接创建用户与批量导入（一次性密码 + `must_change_password` 强制轮换） - -见[认证](/docs/configure/authentication)。 - -## 授权 - -分层强制（通过 `@objectstack/plugin-security`）,遵循权限模型 v2（ObjectStack 13,ADR-0090）： - -1. **对象权限** —— 每个权限集对每个对象的 CRUD,直接分配给用户或通过扁平的**岗位**分发 -2. **组织级默认值（OWD）** —— 带所有者的自定义对象默认 `private` 共享模型;匿名数据访问默认拒绝 -3. **行级安全** —— 注入查询的声明式策略表达式;不可选 -4. **字段级安全** —— 响应中剥离字段 / 写入时拒绝（键带对象限定,由校验规则强制） -5. **组织作用域** —— 多租户隔离;绕过需要显式 `viewAllRecords` - -系统上下文操作绕过检查以便内部作业 / 迁移可运行 —— 这些路径可审计。 - -配套机制： - -- **解释引擎** —— `explain(principal, object, operation)` 按层报告判定结果并逐层归因,与强制执行使用相同的求值器（构造上不漂移）。 -- **编写期校验** —— `os compile` 以安全态势闸门构建（`security-owd-unset`、`security-anchor-high-privilege`、`security-fls-unqualified-key` 等）;可选提交 `access-matrix.json` 快照,任何能力漂移都会让 CI 失败,直到显式重新批准。 -- **委托管理** —— 权限集可携带 `adminScope`,子管理员只能在其业务单元子树内、按白名单管理分配,且记录 `granted_by` 审计。 -- **MCP 权限上限** —— 通过 OAuth 接入的 AI 代理在 `effective_permission = scope_ceiling ∩ user_grants` 下运行（`data:read` / `data:write` / `actions:execute`）,失败即关闭。 - -见[权限](/docs/configure/permissions)。 - -## 审计与证据 - -当审计能力被加载时（`@objectstack/plugin-audit`）： - -- 每个对象上的每次 CRUD 操作 → 审计行。 -- 字段变更的前后值。 -- 认证、权限授予、会话撤销事件。 -- 审计行**不可变**：不能修改,只能归档。 -- 保留期在对象的 `lifecycle` 块上声明（`sys_audit_log` 出厂为热存 90 天后归档）,可通过 `lifecycle.retention_overrides` 按环境调整;与你的 DB 归档策略配合。 - -这是 SOC 2 CC6/CC7、ISO 27001 A.12.4、HIPAA §164.312(b) 和 GDPR Article 30 的证据基础。 - -## 合规框架 - -ObjectOS 提供每个常见框架所要求的**技术原语**。认证是部署的属性,而非软件的属性 —— 但控制项映射清晰： - -| 框架 | ObjectOS 提供 | -|---|---| -| **SOC 2** | 访问控制（CC6）、变更管理（审计日志）、加密（部署）、监控（可观测性）、备份（operate/backup） | -| **ISO 27001** | A.5 政策（RBAC）、A.8 资产管理（对象目录）、A.9 访问控制、A.12 运营、A.18 合规 | -| **HIPAA** | 访问控制（§164.312(a)）、审计控制（§164.312(b)）、完整性（不可变审计）、传输安全（TLS） | -| **GDPR** | Article 30 处理记录（审计）、Article 32 处理安全、Article 17 删除权（支持软删 + 硬删）、数据驻留（你选择区域） | -| **CCPA / 中国 DSL / 俄罗斯 152-FZ** | 在正确区域自托管即满足驻留;访问控制 + 审计覆盖大部分报告义务 | - -ObjectOS 本身**未认证**,因为认证针对运行中的部署,而非二进制。你的部署可以被认证 —— 已有许多达成。 - -## 密钥处理 - -| 密钥 | 放置位置 | -|---|---| -| `OS_AUTH_SECRET` | 你的密钥管理器（Vault、AWS Secrets Manager、k8s Secret）;注入为环境变量 | -| 带凭据的数据库 URL | 同 | -| OIDC client secret | 同 | -| OAuth provider secret | 同 | -| API provider key（邮件、存储、AI） | 同 | -| DB 中存储的 settings | 由 settings 服务静态加密 | - -**绝不要**将密钥烘焙到 artifact（`objectstack.json`）、Docker 镜像、compose 文件或 Git 中。Console 中的 settings UI 将 env 管理的值显示为锁定状态,运维不会意外覆盖。 - -## 网络模型 - -必需入站： -- 从你的 ingress / 负载均衡器到 ObjectOS `:3000`（默认）的 HTTPS。 - -必需出站（仅当你配置这些功能时）： -- 你的数据库（Postgres / Mongo / Turso / ……）。 -- S3 兼容存储（若启用 `storage` 能力且使用 S3 适配器）。 -- OIDC discovery URL（若启用 SSO）。 -- 邮件提供商 API（Resend / Postmark）。 -- AI 提供商 API（OpenAI / Anthropic / Google / ……）。 -- Webhook 目标。 - -这就是全部出站表面。见[气隙](/docs/deploy/air-gapped)了解切断更多的部署。 - -## AI：工具、审批、隔离 - -AI Builder 是你将暴露的最敏感安全表面,因此除上述一切之外还有自己的强制层。 - -### AI 如何变更状态 - -模型**无法直接写入**你的数据库。状态变更的唯一方式是发出结构化的工具调用,由 AI 服务接收、校验和入队。链条： - -```text -user prompt - → model emits tool call (e.g. add_field { object: 'ticket', name: 'severity', type: 'select' }) - → AI service validates payload against the tool's Zod schema - → if the tool is "mutating": queue as pending action (no state change yet) - → human reviewer approves → mutation applied → audit row written - → if the tool is "read-only": run immediately, response returned to model -``` - -有 11 个第一方元数据工具（[见 Build → AI Builder](/docs/build/ai-builder)）加每个已声明 Action 对应的一个 `action_` 工具。每个工具 —— 第一方或自定义 —— 都遵循相同的生命周期。 - -### 权限键 - -| 键 | 授予 | -|:--|:--| -| `ai:chat` | 进行对话;消费模型;让 Agent 调用只读工具 | -| `ai:complete` | 原始补全端点（无 Agent 循环） | -| `ai:conversations` | 列出/检查/删除对话（取决于 RBAC 作用域,自己或全部） | -| `ai:agents` | 管理 Agent 元数据（与 `ai:chat` 一同用于调用） | -| `ai:tools` | 列出工具目录 | -| `ai:execute` | 通过 REST 直接调用工具（高级 —— 通常仅 ambient agent 需要） | -| `ai:read` | 读取 pending-actions 队列与模型列表 | -| `ai:approve` | 批准/拒绝排队中的变更 | -| `ai:admin` | 完全的 AI 服务管理 | - -关键拆分是 **`ai:chat` ≠ `ai:approve`**。给大多数用户 `ai:chat` 使助手可用;为应审查结构性变更的管理员 / 应用所有者保留 `ai:approve`。最终用户因此可以安全地"vibe-build" —— 他们最坏只能将糟糕的变更入队,需别人接受。 - -### 租户隔离 - -- Agent、对话、知识库和 pending action 作用于一个**环境**（租户）。租户 A 不能看到租户 B 的对话、AI 提议的工具或知识语料 —— 即使从同一 marketplace 包安装的同一 Agent 定义也不行。 -- 元数据工具（`create_object`、`add_field`……）针对调用方租户中的**激活包**操作。它们无法触及包外。 -- 工具输入经 CEL 校验,引擎拒绝对保留系统包（`sys.*`）或其他租户对象名的引用。 - -### 审计事件 - -当审计能力被加载时： - -- `ai.chat.message` —— 每条用户/助手消息,带模型 + token 计数 -- `ai.tool.call` —— 工具名、已校验输入、完整输出（或错误） -- `ai.pending_action.queued` —— 提议的变更,完整 diff -- `ai.pending_action.approved` / `.rejected` —— 谁、何时、为何决定 -- `ai.metadata.applied` —— 对元数据存储的实际写入,带 diff - -这些行不可变,可导出用于安全审查或费用分摊。按（提供商、模型、用户）的 token 计数供成本归因。 - -### 提示注入态势 - -间接提示注入（如 Agent 检索的文档中含恶意内容）是真实风险;ObjectOS 通过构造减少爆炸半径： - -- AI **无法绕过工具校验** —— 即使被说服发出恶意载荷,Zod schema 也会在到达引擎前拒绝畸形输入。 -- 变更性工具始终入队。注入的提示无法静默写入数据库。 -- 工具调用继承**最终用户的权限**,而非模型的服务账户权限。用户永远无法通过 AI 做他们自己在 Console 或 REST 中也做不到的事。 -- 加载到 Agent 中的 Skill 是版本化且显式的 —— 见 [Build → IDE Skills](/docs/build/ai-skills) 和 [Build → AI Builder](/docs/build/ai-builder)。 - -### 外部 AI 提供商数据流 - -当你配置一个提供商（OpenAI、Anthropic……）时,仅以下内容离开你的网络： - -- 模型所需的对话历史（受你的 AI 服务 `redact` 配置约束 —— 见 [Configure → AI](/docs/configure/ai)） -- 工具定义（名称、JSON schema —— 无记录数据） -- 模型继续所需的工具输出（如用户明确请求的查询结果） - -对气隙部署,将 AI 服务指向本地 Ollama / vLLM / TGI 端点,同样的流程仍在你的边界内。 - -## 漏洞披露 - -请私下报告安全问题至 -**security@objectstack.ai**。我们将在 1 个工作日内响应。请勿就安全问题提交公开 GitHub issue。 - -## 供应链 - -- 预构建镜像由 [github.com/objectstack-ai/objectos](https://github.com/objectstack-ai/objectos) 发布,带可复现构建溯源。 -- 所有 `@objectstack/*` 包在 GitHub 上有发布源码 —— Apache-2.0,无混淆。 -- 生产中使用 SHA 钉死的镜像 tag（`sha-`）以避免漂移;见 [Docker](/docs/deploy/docker)。 - -## 推荐加固清单 - -- [ ] 在 edge 用真实证书终结 TLS。 -- [ ] `OS_AUTH_SECRET` 为 32+ 字节随机,放在密钥管理器。 -- [ ] 数据库连接使用 TLS。 -- [ ] TLS 校验后启用 HSTS。 -- [ ] CORS origin 显式（带凭据时永不 `*`）。 -- [ ] auth 端点限速（推荐 `10/min/IP`）。 -- [ ] 审计保留期匹配策略。 -- [ ] 人类账户用 OIDC;机器账户用 API key。 -- [ ] 备份 + 恢复演练已执行并计时。 -- [ ] 反向测试：跨组织访问被拒、字段安全有效、过期会话被拒。 -- [ ] 镜像固定到 `sha-` 或语义版本 tag。 -- [ ] 每次发布前在 CI 中 `os doctor` 干净。 - -完整上线清单见[生产就绪](/docs/operate/production)。 diff --git a/content/docs/reference/security.zh-Hant.mdx b/content/docs/reference/security.zh-Hant.mdx deleted file mode 100644 index 2a520b4..0000000 --- a/content/docs/reference/security.zh-Hant.mdx +++ /dev/null @@ -1,234 +0,0 @@ ---- -# @generated zh-Hant from zh-Hans -- do not edit. Edit the English source, then regenerate: pnpm --filter @objectos/docs gen:zh-hant -title: 安全與合規 -description: 保護什麼、如何保護、誰負責 —— 供安全評審。 -translation: - source_sha: 8ef4efaee0f913098534126f549f5d34559d1b3f39a8a4e5fd76e49c9a2d41ff - guide_rev: 1 - mode: auto ---- - -本頁面面向安全評審者、IT 管理員,以及需要回答"引入它安全嗎?"的任何人。 - -## 一句話威脅模型 - -ObjectOS 作為單個 Node.js 程序執行在**你**的網路內,與**你**的資料庫通訊,從不回傳。被攻破的爆炸半徑即其連線的資料庫上的資料 —— 僅此而已。 - -## 資料駐留 - -| 資料類別 | 存放在 | 是否離開你的網路? | -|---|---|---| -| 業務記錄 | 你的資料庫 | **否** | -| 使用者賬戶、會話、OAuth token | 你的資料庫 | **否** | -| 審計日誌 | 你的資料庫 | **否** | -| 設定、API key | 你的資料庫 / 你的金鑰管理器 | **否** | -| 上傳檔案 | 你的磁碟或 S3 相容儲存桶 | **否** | -| 遙測/使用資料 | — | **不收集** | - -ObjectOS **零外發呼叫**,除非你顯式配置（OIDC discovery、郵件提供商、AI 提供商、webhook 目標、外部儲存）。它不回傳、不查 license server、不輪詢更新。 - -## 加密 - -| 層 | 機制 | 責任方 | -|---|---|---| -| 傳輸中（瀏覽器 ↔ ObjectOS） | TLS,在你的 edge / ingress 終結 | 你 | -| 傳輸中（ObjectOS ↔ 資料庫） | 驅動級 TLS（Postgres `sslmode=require`、MongoDB `tls=true`……） | 你 —— 設定連線字串 | -| 靜態（業務資料） | 資料庫原生（如 Postgres TDE、RDS encryption） | 你 | -| 靜態（上傳檔案） | 儲存原生（S3 SSE、R2 預設、磁碟級 FDE） | 你 | -| DB 中金鑰（settings、OIDC client secret） | 由 settings 服務加密 | ObjectOS | -| 會話 cookie / token | 用 `OS_AUTH_SECRET` 進行 HMAC 簽名 | ObjectOS | -| API key 值 | DB 中**雜湊儲存** —— 洩露的 DB 行無法重建 key | ObjectOS | - -## 認證 - -內建（通過 `@objectstack/plugin-auth`,基於 Better Auth）： - -- 帶驗證 + 重置的郵箱/密碼 -- 帶撤銷的會話管理 -- Social OAuth（Google、GitHub、Microsoft、Apple……） -- 企業 OIDC/SSO（Okta、Entra ID、Keycloak、Ping） -- 雙因素（TOTP） -- Passkey / WebAuthn -- 魔法連結 -- 手機號 + 簡訊 OTP 登入與密碼重置（通過 `auth.plugins.phoneNumber` 顯式開啟;支援阿里雲 / Twilio 通道,自帶限流） -- CLI/瀏覽器裝置流 -- API key（雜湊、可過期、可撤銷、繫結到使用者） -- 面向 MCP 客戶端的自助 OAuth 2.1（授權碼 + PKCE、動態客戶端註冊、按 scope 推導許可權上限） -- 管理員直接建立使用者與批次匯入（一次性密碼 + `must_change_password` 強制輪換） - -見[認證](/docs/configure/authentication)。 - -## 授權 - -分層強制（通過 `@objectstack/plugin-security`）,遵循許可權模型 v2（ObjectStack 13,ADR-0090）： - -1. **物件許可權** —— 每個許可權集對每個物件的 CRUD,直接分配給使用者或通過扁平的**崗位**分發 -2. **組織級預設值（OWD）** —— 帶所有者的自定義物件預設 `private` 共享模型;匿名資料訪問預設拒絕 -3. **行級安全** —— 注入查詢的宣告式策略表示式;不可選 -4. **欄位級安全** —— 響應中剝離欄位 / 寫入時拒絕（鍵帶物件限定,由校驗規則強制） -5. **組織作用域** —— 多租戶隔離;繞過需要顯式 `viewAllRecords` - -系統上下文操作繞過檢查以便內部作業 / 遷移可執行 —— 這些路徑可審計。 - -配套機制： - -- **解釋引擎** —— `explain(principal, object, operation)` 按層報告判定結果並逐層歸因,與強制執行使用相同的求值器（構造上不漂移）。 -- **編寫期校驗** —— `os compile` 以安全態勢閘門構建（`security-owd-unset`、`security-anchor-high-privilege`、`security-fls-unqualified-key` 等）;可選提交 `access-matrix.json` 快照,任何能力漂移都會讓 CI 失敗,直到顯式重新批准。 -- **委託管理** —— 許可權集可攜帶 `adminScope`,子管理員只能在其業務單元子樹內、按白名單管理分配,且記錄 `granted_by` 審計。 -- **MCP 許可權上限** —— 通過 OAuth 接入的 AI 代理在 `effective_permission = scope_ceiling ∩ user_grants` 下執行（`data:read` / `data:write` / `actions:execute`）,失敗即關閉。 - -見[許可權](/docs/configure/permissions)。 - -## 審計與證據 - -當審計能力被載入時（`@objectstack/plugin-audit`）： - -- 每個物件上的每次 CRUD 操作 → 審計行。 -- 欄位變更的前後值。 -- 認證、許可權授予、會話撤銷事件。 -- 審計行**不可變**：不能修改,只能歸檔。 -- 保留期在物件的 `lifecycle` 塊上宣告（`sys_audit_log` 出廠為熱存 90 天后歸檔）,可通過 `lifecycle.retention_overrides` 按環境調整;與你的 DB 歸檔策略配合。 - -這是 SOC 2 CC6/CC7、ISO 27001 A.12.4、HIPAA §164.312(b) 和 GDPR Article 30 的證據基礎。 - -## 合規框架 - -ObjectOS 提供每個常見框架所要求的**技術原語**。認證是部署的屬性,而非軟體的屬性 —— 但控制項對映清晰： - -| 框架 | ObjectOS 提供 | -|---|---| -| **SOC 2** | 訪問控制（CC6）、變更管理（審計日誌）、加密（部署）、監控（可觀測性）、備份（operate/backup） | -| **ISO 27001** | A.5 政策（RBAC）、A.8 資產管理（物件目錄）、A.9 訪問控制、A.12 運營、A.18 合規 | -| **HIPAA** | 訪問控制（§164.312(a)）、審計控制（§164.312(b)）、完整性（不可變審計）、傳輸安全（TLS） | -| **GDPR** | Article 30 處理記錄（審計）、Article 32 處理安全、Article 17 刪除權（支援軟刪 + 硬刪）、資料駐留（你選擇區域） | -| **CCPA / 中國 DSL / 俄羅斯 152-FZ** | 在正確區域自託管即滿足駐留;訪問控制 + 審計覆蓋大部分報告義務 | - -ObjectOS 本身**未認證**,因為認證針對執行中的部署,而非二進位制。你的部署可以被認證 —— 已有許多達成。 - -## 金鑰處理 - -| 金鑰 | 放置位置 | -|---|---| -| `OS_AUTH_SECRET` | 你的金鑰管理器（Vault、AWS Secrets Manager、k8s Secret）;注入為環境變數 | -| 帶憑據的資料庫 URL | 同 | -| OIDC client secret | 同 | -| OAuth provider secret | 同 | -| API provider key（郵件、儲存、AI） | 同 | -| DB 中儲存的 settings | 由 settings 服務靜態加密 | - -**絕不要**將金鑰烘焙到 artifact（`objectstack.json`）、Docker 映象、compose 檔案或 Git 中。Console 中的 settings UI 將 env 管理的值顯示為鎖定狀態,運維不會意外覆蓋。 - -## 網路模型 - -必需入站： -- 從你的 ingress / 負載均衡器到 ObjectOS `:3000`（預設）的 HTTPS。 - -必需出站（僅當你配置這些功能時）： -- 你的資料庫（Postgres / Mongo / Turso / ……）。 -- S3 相容儲存（若啟用 `storage` 能力且使用 S3 介面卡）。 -- OIDC discovery URL（若啟用 SSO）。 -- 郵件提供商 API（Resend / Postmark）。 -- AI 提供商 API（OpenAI / Anthropic / Google / ……）。 -- Webhook 目標。 - -這就是全部出站表面。見[氣隙](/docs/deploy/air-gapped)瞭解切斷更多的部署。 - -## AI：工具、審批、隔離 - -AI Builder 是你將暴露的最敏感安全表面,因此除上述一切之外還有自己的強制層。 - -### AI 如何變更狀態 - -模型**無法直接寫入**你的資料庫。狀態變更的唯一方式是發出結構化的工具呼叫,由 AI 服務接收、校驗和入隊。鏈條： - -```text -user prompt - → model emits tool call (e.g. add_field { object: 'ticket', name: 'severity', type: 'select' }) - → AI service validates payload against the tool's Zod schema - → if the tool is "mutating": queue as pending action (no state change yet) - → human reviewer approves → mutation applied → audit row written - → if the tool is "read-only": run immediately, response returned to model -``` - -有 11 個第一方後設資料工具（[見 Build → AI Builder](/docs/build/ai-builder)）加每個已宣告 Action 對應的一個 `action_` 工具。每個工具 —— 第一方或自定義 —— 都遵循相同的生命週期。 - -### 許可權鍵 - -| 鍵 | 授予 | -|:--|:--| -| `ai:chat` | 進行對話;消費模型;讓 Agent 呼叫只讀工具 | -| `ai:complete` | 原始補全端點（無 Agent 迴圈） | -| `ai:conversations` | 列出/檢查/刪除對話（取決於 RBAC 作用域,自己或全部） | -| `ai:agents` | 管理 Agent 後設資料（與 `ai:chat` 一同用於呼叫） | -| `ai:tools` | 列出工具目錄 | -| `ai:execute` | 通過 REST 直接呼叫工具（高階 —— 通常僅 ambient agent 需要） | -| `ai:read` | 讀取 pending-actions 佇列與模型列表 | -| `ai:approve` | 批准/拒絕排隊中的變更 | -| `ai:admin` | 完全的 AI 服務管理 | - -關鍵拆分是 **`ai:chat` ≠ `ai:approve`**。給大多數使用者 `ai:chat` 使助手可用;為應審查結構性變更的管理員 / 應用所有者保留 `ai:approve`。終端使用者因此可以安全地"vibe-build" —— 他們最壞只能將糟糕的變更入隊,需別人接受。 - -### 租戶隔離 - -- Agent、對話、知識庫和 pending action 作用於一個**環境**（租戶）。租戶 A 不能看到租戶 B 的對話、AI 提議的工具或知識語料 —— 即使從同一 marketplace 包安裝的同一 Agent 定義也不行。 -- 後設資料工具（`create_object`、`add_field`……）針對呼叫方租戶中的**啟用包**操作。它們無法觸及包外。 -- 工具輸入經 CEL 校驗,引擎拒絕對保留系統包（`sys.*`）或其他租戶物件名的引用。 - -### 審計事件 - -當審計能力被載入時： - -- `ai.chat.message` —— 每條使用者/助手訊息,帶模型 + token 計數 -- `ai.tool.call` —— 工具名、已校驗輸入、完整輸出（或錯誤） -- `ai.pending_action.queued` —— 提議的變更,完整 diff -- `ai.pending_action.approved` / `.rejected` —— 誰、何時、為何決定 -- `ai.metadata.applied` —— 對後設資料儲存的實際寫入,帶 diff - -這些行不可變,可匯出用於安全審查或費用分攤。按（提供商、模型、使用者）的 token 計數供成本歸因。 - -### 提示注入態勢 - -間接提示注入（如 Agent 檢索的文件中含惡意內容）是真實風險;ObjectOS 通過構造減少爆炸半徑： - -- AI **無法繞過工具校驗** —— 即使被說服發出惡意載荷,Zod schema 也會在到達引擎前拒絕畸形輸入。 -- 變更性工具始終入隊。注入的提示無法靜默寫入資料庫。 -- 工具呼叫繼承**終端使用者的許可權**,而非模型的服務賬戶許可權。使用者永遠無法通過 AI 做他們自己在 Console 或 REST 中也做不到的事。 -- 載入到 Agent 中的 Skill 是版本化且顯式的 —— 見 [Build → IDE Skills](/docs/build/ai-skills) 和 [Build → AI Builder](/docs/build/ai-builder)。 - -### 外部 AI 提供商資料流 - -當你配置一個提供商（OpenAI、Anthropic……）時,僅以下內容離開你的網路： - -- 模型所需的對話歷史（受你的 AI 服務 `redact` 配置約束 —— 見 [Configure → AI](/docs/configure/ai)） -- 工具定義（名稱、JSON schema —— 無記錄資料） -- 模型繼續所需的工具輸出（如使用者明確請求的查詢結果） - -對氣隙部署,將 AI 服務指向本地 Ollama / vLLM / TGI 端點,同樣的流程仍在你的邊界內。 - -## 漏洞披露 - -請私下報告安全問題至 -**security@objectstack.ai**。我們將在 1 個工作日內響應。請勿就安全問題提交公開 GitHub issue。 - -## 供應鏈 - -- 預構建映象由 [github.com/objectstack-ai/objectos](https://github.com/objectstack-ai/objectos) 釋出,帶可復現構建溯源。 -- 所有 `@objectstack/*` 包在 GitHub 上有釋出原始碼 —— Apache-2.0,無混淆。 -- 生產中使用 SHA 釘死的映象 tag（`sha-`）以避免漂移;見 [Docker](/docs/deploy/docker)。 - -## 推薦加固清單 - -- [ ] 在 edge 用真實證書終結 TLS。 -- [ ] `OS_AUTH_SECRET` 為 32+ 位元組隨機,放在金鑰管理器。 -- [ ] 資料庫連線使用 TLS。 -- [ ] TLS 校驗後啟用 HSTS。 -- [ ] CORS origin 顯式（帶憑據時永不 `*`）。 -- [ ] auth 端點限速（推薦 `10/min/IP`）。 -- [ ] 審計保留期匹配策略。 -- [ ] 人類賬戶用 OIDC;機器賬戶用 API key。 -- [ ] 備份 + 恢復演練已執行並計時。 -- [ ] 反向測試：跨組織訪問被拒、欄位安全有效、過期會話被拒。 -- [ ] 映象固定到 `sha-` 或語義版本 tag。 -- [ ] 每次釋出前在 CI 中 `os doctor` 乾淨。 - -完整上線清單見[生產就緒](/docs/operate/production)。 diff --git a/content/docs/resources/faq.de.mdx b/content/docs/resources/faq.de.mdx deleted file mode 100644 index 0ab68d4..0000000 --- a/content/docs/resources/faq.de.mdx +++ /dev/null @@ -1,209 +0,0 @@ ---- -title: FAQ -description: Antworten auf die Fragen, die uns am häufigsten gestellt werden. -translation: - source_sha: 8267da8b9943789c7cae4d84724c9fb36d3a48ec09f8a6665652bc8dec94138d - guide_rev: 1 - mode: auto ---- - -## Erste Schritte - -**F: Was ist der absolut schnellste Weg, ObjectOS auszuprobieren?** -A: `npm i -g @objectstack/cli && os start` — und dann -http://localhost:3000 öffnen. Siehe [Quickstart](/docs/quickstart). - -**F: Brauche ich Docker?** -A: Nein. Node 20+ und die CLI reichen aus. Docker ist die empfohlene -Form für das Produktiv-Deployment. - -**F: Brauche ich eine Datenbank?** -A: Nein, nicht für den Anfang — ObjectOS verwendet standardmäßig lokales -SQLite. Wechseln Sie zu Postgres / MySQL / Turso / Mongo, wenn Sie in -die Produktion gehen. - -**F: Brauche ich ein Konto / einen Cloud-Dienst?** -A: Nein. ObjectOS ist vollständig eigenständig. ObjectStack Cloud ist -optional für Deployments über mehrere Umgebungen / mehrere Apps mit -einer Control Plane. - -## Architektur - -**F: Kann ich Postgres / MySQL / MongoDB verwenden?** -A: Ja — Postgres, MySQL, SQLite, Turso/libSQL und MongoDB sind -unterstützte Treiber. Siehe [Runtime Configuration](/docs/configure/runtime). - -**F: Kann ich Console / Account deaktivieren und nur die REST-API nutzen?** -A: Ja. Führen Sie `os start --no-ui` aus oder setzen Sie die -entsprechenden Flags. Die REST-API ist dieselbe, egal ob die UIs -eingebunden sind oder nicht. - -**F: Kann ich mein eigenes Frontend anstelle von Console verwenden?** -A: Ja. Console verwendet dieselben `/api/v1/*`-Endpunkte, die Sie aus -Ihrem eigenen Code aufrufen würden. Verwenden Sie das -`@objectstack/client` SDK oder einen beliebigen HTTP-Client. - -**F: Unterstützt ObjectOS GraphQL?** -A: REST ist die primäre Schnittstelle. GraphQL ist auf der Roadmap — bis -dahin deckt die Abfragesprache ObjectQL (über REST `?filter=`/`?sort=`) -dasselbe Terrain ab. - -**F: Wie wird Mandantenfähigkeit (Multi-Tenancy) gehandhabt?** -A: Ein ObjectOS-Prozess kann viele Environments (Mandanten) bedienen. -Die Auflösung Hostname → Environment wird in einem LRU zwischengespeichert; -jedes Environment hat seine eigene Datenbank, Identität und sein eigenes -Audit-Log. Cookies sind pro Hostname gescoped, sodass Sessions nicht -zwischen Mandanten durchsickern können. - -**F: Kann ObjectOS in einer Serverless-/Lambda-Umgebung laufen?** -A: Die Laufzeit ist ein langlebiger Node-Prozess — ausgelegt für -Container oder VMs, nicht für zustandslose Funktionen. Sowohl der -Kernel-Cache als auch das Better-Auth-Session-Modell hängen von warmem -prozessinternem Zustand ab. - -**F: Skaliert es horizontal?** -A: Ja. Führen Sie mehrere Instanzen hinter einem Load Balancer aus. -Sessions liegen in der Datenbank (nicht im Speicher), sodass jede -Instanz jede Anfrage bedienen kann. Verwenden Sie Redis für gemeinsames -Rate-Limiting und Queueing, wenn Sie diese Funktionen aktivieren. - -## Daten & Migrationen - -**F: Wie werden Schema-Migrationen gehandhabt?** -A: Der Treiber synchronisiert das Datenbankschema beim Hochfahren mit -Ihren deklarierten Objekten. Für Postgres sind das `CREATE TABLE` / -`ALTER TABLE`-Anweisungen. Für kontrollierte Migrationen in regulierten -Umgebungen setzen Sie `OS_SKIP_SCHEMA_SYNC=1` und verwalten das DDL -selbst. - -**F: Was passiert mit Daten, wenn ich ein Feld umbenenne?** -A: Eine Umbenennung ist auf der Datenebene eine destruktive Änderung -(sie sieht aus wie „alte Spalte löschen, neue Spalte hinzufügen"). -Verwenden Sie `os diff`, um dies zu erkennen, und fügen Sie einen -Migrationsschritt hinzu (Spalte in der DB umbenennen, bevor das neue -Artefakt deployt wird). - -**F: Kann ich Daten aus CSV / Excel / Salesforce importieren?** -A: CSV: ja, per `os data create` in einer Schleife oder über den -Bulk-Upload in der Console. Salesforce: Der beste Weg heute ist der -Export nach CSV und der anschließende Import. Native Konnektoren sind -auf der Roadmap. - -**F: Gehen beim Upgrade von ObjectOS meine Daten verloren?** -A: Nein. Patch- und Minor-Upgrades sind nicht-destruktiv. Major-Upgrades -(z. B. 4 → 5) dokumentieren erforderliche Migrationen ausdrücklich. -Erstellen Sie zuerst ein Backup — [Backup & DR](/docs/operate/backup). - -## Berechtigungen & Mandantenfähigkeit - -**F: Wie realisiere ich Sicherheit auf Zeilenebene (Row-Level Security)?** -A: Deklarieren Sie eine Sharing-Regel (deklarativ, wie bei Salesforce) -oder ein CEL-Prädikat in der `recordAccess`-Konfiguration eines Objekts. -Das Security-Plugin fügt bei jeder Abfrage den entsprechenden Filter -ein. Siehe [Permissions](/docs/configure/permissions). - -**F: Kann ich bestimmte Felder für bestimmte Benutzer unsichtbar machen?** -A: Ja — Sicherheit auf Feldebene in Permission Sets. Verbergen oder -schreibgeschützt, pro Feld pro Permission Set. Wird einheitlich über -REST, ObjectQL und Console durchgesetzt. Siehe -[Permission Sets](/docs/configure/permissions/permission-sets). - -**F: Wie integriere ich Okta / Entra / Keycloak?** -A: OIDC. Konfigurieren Sie die Discovery-URL + Client-ID/-Secret unter -**Console → Authentication** (oder per Env). Die Callback-URL des -Providers ist `/api/v1/auth/oauth2/callback/`. Siehe -[Authentication](/docs/configure/authentication). - -## Integrationen - -**F: Kann ich Webhooks senden?** -A: Ja — aktivieren Sie `webhooks` in `requires`. ObjectOS verwendet -eine persistente Outbox mit HMAC-SHA256-Signierung. Siehe -[Webhooks](/docs/configure/webhooks). - -**F: Kann ich mit Zapier / Make / n8n integrieren?** -A: Ja — Webhooks für ausgehende und die REST-API + API-Keys für -eingehende Kommunikation. Native Konnektoren für gängige iPaaS-Tools -sind auf der Roadmap. - -**F: Können KI-Agenten mein ObjectOS aufrufen?** -A: Ja, über MCP (`@objectstack/mcp`) — stellt Objekte -und Aktionen als MCP-Tools bereit, die Claude Desktop, IDEs oder andere -MCP-Clients verwenden können. Siehe [AI Service](/docs/configure/ai). - -## Anpassung - -**F: Kann ich eigene Plugins schreiben?** -A: Ja — Plugins folgen einem einfachen DI- + Lifecycle-Muster -(`init → start → destroy`). Beispiele finden Sie in den -`@objectstack/plugin-*`-Paketen auf GitHub. - -**F: Kann ich das Erscheinungsbild von Console anpassen?** -A: Branding (Logo, Akzentfarbe, Standard-Theme) befindet sich unter -**Console → System Settings**. Tiefgreifende UI-Anpassung bedeutet, das -`@objectstack/client-react` zu forken oder Ihr eigenes Frontend gegen -die REST-API zu bauen. - -**F: Kann ich andere Sprachen als Englisch hinzufügen?** -A: Ja — i18n ist erstklassig integriert. Verwenden Sie -`os i18n extract` / `os i18n check` und liefern Sie ein -Übersetzungs-Bundle aus. - -## Betrieb - -**F: Was ist das empfohlene Produktiv-Deployment?** -A: Docker (oder Kubernetes für mehrere Pods) + verwaltetes Postgres + S3 -oder R2 für Dateien + Ihr Secret-Manager für `OS_AUTH_SECRET`. Siehe -[Production Readiness](/docs/operate/production). - -**F: Hat ObjectOS eine Statusseite?** -A: Für Ihr selbst gehostetes Deployment ist der Status Ihre Angelegenheit -— verbinden Sie `/health` mit Ihrem Monitor. Für gehostete Dienste siehe -[status.objectstack.ai](https://status.objectstack.ai). - -**F: Welche Metriken sollte ich überwachen?** -A: 5xx-Rate, p95-Latenz, Auth-Fehlerrate, Kernel-Cache-Miss-Rate, -Queue-Tiefe. Ein minimales Prometheus-Beispiel finden Sie in -[Observability](/docs/operate/observability). - -**F: Wie erstelle ich ein Backup?** -A: Sichern Sie die **Datenbank** und den **Storage-Bucket** — diese -enthalten alle Kundendaten. ObjectOS selbst ist zustandslos. Siehe -[Backup](/docs/operate/backup). - -## Preise & Rechtliches - -**F: Ist ObjectOS wirklich kostenlos?** -A: Ja. Apache-2.0. Keine Sitze, keine Nutzungsstufe, kein Lizenzserver. - -**F: Kann ich ObjectOS in einem kommerziellen Produkt verwenden, das ich verkaufe?** -A: Ja. Apache-2.0 erlaubt die kommerzielle Nutzung. Siehe -[License](/docs/resources/license). - -**F: Erfassen Sie Telemetrie?** -A: Nein. Null ausgehende Aufrufe, sofern Sie sie nicht konfigurieren -(OIDC, E-Mail, AI, Webhooks). Siehe -[Security & Compliance](/docs/reference/security#data-residency). - -**F: Ist ObjectOS SOC 2 / ISO 27001 / HIPAA / GDPR-konform?** -A: ObjectOS stellt die **Primitive** bereit, die jedes Framework -benötigt (RBAC, Audit, verschlüsselungsbereit, Residenz). Eine -Zertifizierung ist eine Eigenschaft Ihres **Deployments**, nicht der -Binärdatei. Viele ObjectOS-Deployments sind zertifiziert. Siehe -[Security & Compliance](/docs/reference/security#compliance-frameworks). - -## Wenn Sie nicht weiterkommen - -**F: Etwas ist kaputt — wo fange ich an?** -A: `os doctor`. Das erkennt 80 % der Fehlkonfigurationen von selbst. -Danach [Troubleshooting](/docs/operate/troubleshooting). - -**F: Wo melde ich einen Fehler?** -A: [GitHub Issues](https://github.com/objectstack-ai/objectos/issues). -Fügen Sie die Ausgabe von `os doctor` bei. Sicherheitsprobleme: -**security@objectstack.ai**. - -**F: Wo bekomme ich Hilfe von echten Menschen?** -A: [GitHub Discussions](https://github.com/objectstack-ai/objectos/discussions), -der Community-Discord oder **sales@objectstack.ai** für kommerziellen -Support. diff --git a/content/docs/resources/faq.es.mdx b/content/docs/resources/faq.es.mdx deleted file mode 100644 index fcea97c..0000000 --- a/content/docs/resources/faq.es.mdx +++ /dev/null @@ -1,203 +0,0 @@ ---- -title: Preguntas frecuentes -description: Respuestas a las preguntas que más nos hacen. -translation: - source_sha: 8267da8b9943789c7cae4d84724c9fb36d3a48ec09f8a6665652bc8dec94138d - guide_rev: 1 - mode: auto ---- - -## Primeros pasos - -**P: ¿Cuál es la forma más rápida de probar ObjectOS?** -R: `npm i -g @objectstack/cli && os start` — luego abre -http://localhost:3000. Consulta [Quickstart](/docs/quickstart). - -**P: ¿Necesito Docker?** -R: No. Node 20+ y la CLI son suficientes. Docker es la forma de -despliegue de producción recomendada. - -**P: ¿Necesito una base de datos?** -R: No, no para empezar — ObjectOS usa SQLite local de forma predeterminada. -Cámbiala por Postgres / MySQL / Turso / Mongo cuando pases a producción. - -**P: ¿Necesito una cuenta / servicio en la nube?** -R: No. ObjectOS es totalmente autónomo. ObjectStack Cloud es opcional -para despliegues multientorno / multiaplicación con un plano de control. - -## Arquitectura - -**P: ¿Puedo usar Postgres / MySQL / MongoDB?** -R: Sí — Postgres, MySQL, SQLite, Turso/libSQL y MongoDB son -controladores compatibles. Consulta [Runtime Configuration](/docs/configure/runtime). - -**P: ¿Puedo desactivar Console / Account y usar solo la API REST?** -R: Sí. Ejecuta `os start --no-ui` o establece los indicadores -correspondientes. La API REST es la misma tanto si las interfaces de -usuario están montadas como si no. - -**P: ¿Puedo usar mi propio front-end en lugar de Console?** -R: Sí. Console usa los mismos endpoints `/api/v1/*` que llamarías desde -tu propio código. Usa el SDK `@objectstack/client` o cualquier cliente HTTP. - -**P: ¿ObjectOS admite GraphQL?** -R: REST es la superficie principal. GraphQL está en la hoja de ruta — -hasta entonces, el lenguaje de consulta ObjectQL (sobre REST -`?filter=`/`?sort=`) cubre el mismo terreno. - -**P: ¿Cómo se gestiona la multitenencia?** -R: Un proceso de ObjectOS puede servir a muchos Environments (tenants). -La resolución de hostname → Environment se almacena en caché en una LRU; -cada Environment tiene su propia base de datos, identidad y registro de -auditoría. Las cookies tienen un alcance por hostname para que las -sesiones no puedan filtrarse entre tenants. - -**P: ¿Puede ObjectOS ejecutarse en un entorno serverless / Lambda?** -R: El runtime es un proceso Node de larga duración — diseñado para -contenedores o VMs, no para funciones sin estado. Tanto la caché del -kernel como el modelo de sesión de Better Auth dependen de un estado -en proceso "caliente". - -**P: ¿Escala horizontalmente?** -R: Sí. Ejecuta varias instancias detrás de un balanceador de carga. Las -sesiones viven en la base de datos (no en memoria), por lo que cualquier -instancia puede atender cualquier solicitud. Usa Redis para la limitación -de tasa y la cola compartidas si habilitas esas capacidades. - -## Datos y migraciones - -**P: ¿Cómo se gestionan las migraciones de esquema?** -R: El controlador sincroniza el esquema de la base de datos con los -objetos que declaras durante el arranque. Para Postgres, eso son -sentencias `CREATE TABLE` / `ALTER TABLE`. Para migraciones controladas -en entornos regulados, establece `OS_SKIP_SCHEMA_SYNC=1` y gestiona el -DDL tú mismo. - -**P: ¿Qué ocurre con los datos cuando renombro un campo?** -R: Un cambio de nombre es un cambio destructivo en la capa de datos -(parece "eliminar la columna antigua, añadir la columna nueva"). Usa -`os diff` para detectarlo y añade un paso de migración (renombra la -columna en la BD antes de desplegar el nuevo artefacto). - -**P: ¿Puedo importar datos desde CSV / Excel / Salesforce?** -R: CSV: sí, mediante `os data create` en bucle o la carga masiva de -Console. Salesforce: el mejor camino hoy es exportar a CSV e importar. -Los conectores nativos están en la hoja de ruta. - -**P: ¿Actualizar ObjectOS hará que pierda mis datos?** -R: No. Las actualizaciones de parche y menores no son destructivas. Las -actualizaciones mayores (p. ej. 4 → 5) documentan explícitamente las -migraciones necesarias. Haz una copia de seguridad primero — -[Backup & DR](/docs/operate/backup). - -## Permisos y multitenencia - -**P: ¿Cómo implemento la seguridad a nivel de fila?** -R: Declara una regla de uso compartido (declarativa, como Salesforce) o -un predicado CEL en la configuración `recordAccess` de un objeto. El -plugin de seguridad inyecta el filtro correspondiente en cada consulta. -Consulta [Permissions](/docs/configure/permissions). - -**P: ¿Puedo hacer que algunos campos sean invisibles para ciertos usuarios?** -R: Sí — seguridad a nivel de campo en los conjuntos de permisos. Oculto -o de solo lectura, por campo y por conjunto de permisos. Se aplica de -manera uniforme en REST, ObjectQL y Console. Consulta -[Permission Sets](/docs/configure/permissions/permission-sets). - -**P: ¿Cómo integro Okta / Entra / Keycloak?** -R: OIDC. Configura la URL de descubrimiento + el id/secreto de cliente -en **Console → Authentication** (o mediante env). La URL de callback del -proveedor es `/api/v1/auth/oauth2/callback/`. Consulta -[Authentication](/docs/configure/authentication). - -## Integraciones - -**P: ¿Puedo enviar webhooks?** -R: Sí — habilita `webhooks` en `requires`. ObjectOS usa una bandeja de -salida persistente con firma HMAC-SHA256. Consulta [Webhooks](/docs/configure/webhooks). - -**P: ¿Puedo integrarme con Zapier / Make / n8n?** -R: Sí — webhooks para la salida y la API REST + claves de API para la -entrada. Los conectores nativos para herramientas iPaaS populares están -en la hoja de ruta. - -**P: ¿Pueden los agentes de IA llamar a mi ObjectOS?** -R: Sí, mediante MCP (`@objectstack/mcp`) — expone objetos -y acciones como herramientas MCP que Claude Desktop, los IDE u otros -clientes MCP pueden usar. Consulta [AI Service](/docs/configure/ai). - -## Personalización - -**P: ¿Puedo escribir plugins personalizados?** -R: Sí — los plugins siguen un patrón sencillo de DI + ciclo de vida -(`init → start → destroy`). Consulta los paquetes `@objectstack/plugin-*` -en GitHub para ver ejemplos. - -**P: ¿Puedo personalizar el aspecto de Console?** -R: La personalización de marca (logo, color de acento, tema -predeterminado) está en **Console → System Settings**. La personalización -profunda de la interfaz implica hacer un fork de -`@objectstack/client-react` o construir tu propio front-end contra la -API REST. - -**P: ¿Puedo añadir idiomas distintos del inglés?** -R: Sí — i18n es de primera clase. Usa `os i18n extract` / `os i18n check` -y entrega un paquete de traducción. - -## Operaciones - -**P: ¿Cuál es el despliegue de producción recomendado?** -R: Docker (o Kubernetes para multipod) + Postgres gestionado + S3 o R2 -para archivos + tu gestor de secretos para `OS_AUTH_SECRET`. Consulta -[Production Readiness](/docs/operate/production). - -**P: ¿ObjectOS tiene una página de estado?** -R: Para tu despliegue autoalojado, el estado es asunto tuyo — conecta -`/health` a tu monitor. Para servicios alojados, consulta -[status.objectstack.ai](https://status.objectstack.ai). - -**P: ¿Qué métricas debo monitorizar?** -R: tasa de 5xx, latencia p95, tasa de fallos de autenticación, tasa de -fallos de caché del kernel, profundidad de la cola. Ejemplo mínimo de -Prometheus en [Observability](/docs/operate/observability). - -**P: ¿Cómo hago una copia de seguridad?** -R: Haz una copia de seguridad de la **base de datos** y del **bucket de -almacenamiento** — esos contienen todos los datos de clientes. ObjectOS -en sí no tiene estado. Consulta [Backup](/docs/operate/backup). - -## Precios y aspectos legales - -**P: ¿ObjectOS es realmente gratis?** -R: Sí. Apache-2.0. Sin asientos, sin nivel de uso, sin servidor de -licencias. - -**P: ¿Puedo usar ObjectOS en un producto comercial que vendo?** -R: Sí. Apache-2.0 permite el uso comercial. Consulta [License](/docs/resources/license). - -**P: ¿Recopilan telemetría?** -R: No. Cero llamadas salientes a menos que las configures (OIDC, email, -IA, webhooks). Consulta [Security & Compliance](/docs/reference/security#data-residency). - -**P: ¿ObjectOS cumple con SOC 2 / ISO 27001 / HIPAA / GDPR?** -R: ObjectOS proporciona las **primitivas** que requiere todo framework -(RBAC, auditoría, listo para cifrado, residencia). La certificación es -una propiedad de tu **despliegue**, no del binario. Muchos despliegues -de ObjectOS están certificados. Consulta -[Security & Compliance](/docs/reference/security#compliance-frameworks). - -## Resolver bloqueos - -**P: Algo está roto — ¿por dónde empiezo?** -R: `os doctor`. Detecta por sí solo el 80% de las configuraciones -incorrectas. Después de eso, [Troubleshooting](/docs/operate/troubleshooting). - -**P: ¿Dónde reporto un error?** -R: [GitHub Issues](https://github.com/objectstack-ai/objectos/issues). -Incluye la salida de `os doctor`. Problemas de seguridad: -**security@objectstack.ai**. - -**P: ¿Dónde obtengo ayuda de personas reales?** -R: [GitHub Discussions](https://github.com/objectstack-ai/objectos/discussions), -el Discord de la comunidad o **sales@objectstack.ai** para soporte -comercial. diff --git a/content/docs/resources/faq.fr.mdx b/content/docs/resources/faq.fr.mdx deleted file mode 100644 index dc7b11e..0000000 --- a/content/docs/resources/faq.fr.mdx +++ /dev/null @@ -1,207 +0,0 @@ ---- -title: FAQ -description: Réponses aux questions qu'on nous pose le plus souvent. -translation: - source_sha: 8267da8b9943789c7cae4d84724c9fb36d3a48ec09f8a6665652bc8dec94138d - guide_rev: 1 - mode: auto ---- - -## Premiers pas - -**Q : Quel est le moyen le plus rapide d'essayer ObjectOS ?** -R : `npm i -g @objectstack/cli && os start` — puis ouvrez -http://localhost:3000. Voir [Démarrage rapide](/docs/quickstart). - -**Q : Ai-je besoin de Docker ?** -R : Non. Node 20+ et le CLI suffisent. Docker est la forme de -déploiement recommandée pour la production. - -**Q : Ai-je besoin d'une base de données ?** -R : Non, pas pour démarrer — ObjectOS utilise SQLite en local par défaut. -Remplacez-le par Postgres / MySQL / Turso / Mongo lorsque vous passez en -production. - -**Q : Ai-je besoin d'un compte / d'un service cloud ?** -R : Non. ObjectOS est entièrement autonome. ObjectStack Cloud est -optionnel pour les déploiements multi-environnements / multi-applications -avec un plan de contrôle. - -## Architecture - -**Q : Puis-je utiliser Postgres / MySQL / MongoDB ?** -R : Oui — Postgres, MySQL, SQLite, Turso/libSQL et MongoDB sont des -pilotes pris en charge. Voir [Configuration du runtime](/docs/configure/runtime). - -**Q : Puis-je désactiver Console / Account et n'utiliser que l'API REST ?** -R : Oui. Exécutez `os start --no-ui` ou définissez les indicateurs -correspondants. L'API REST est la même que les interfaces soient montées -ou non. - -**Q : Puis-je utiliser mon propre front-end à la place de Console ?** -R : Oui. Console utilise les mêmes points de terminaison `/api/v1/*` que -vous appelleriez depuis votre propre code. Utilisez le SDK -`@objectstack/client` ou n'importe quel client HTTP. - -**Q : ObjectOS prend-il en charge GraphQL ?** -R : REST est la surface principale. GraphQL est dans la feuille de route — -en attendant, le langage de requête ObjectQL (par-dessus REST -`?filter=`/`?sort=`) couvre le même périmètre. - -**Q : Comment la multilocation est-elle gérée ?** -R : Un seul processus ObjectOS peut servir de nombreux Environments -(locataires). La résolution nom d'hôte → Environment est mise en cache -dans un LRU ; chaque Environment a sa propre base de données, son identité -et son journal d'audit. Les cookies sont délimités par nom d'hôte afin que -les sessions ne puissent pas fuiter entre locataires. - -**Q : ObjectOS peut-il s'exécuter dans un environnement serverless / Lambda ?** -R : Le runtime est un processus Node de longue durée — conçu pour des -conteneurs ou des VM, pas pour des fonctions sans état. Le cache du noyau -et le modèle de session Better Auth dépendent tous deux d'un état chaud -en cours de processus. - -**Q : Est-ce que ça monte en charge horizontalement ?** -R : Oui. Exécutez plusieurs instances derrière un répartiteur de charge. -Les sessions résident dans la base de données (et non en mémoire), de -sorte que n'importe quelle instance peut servir n'importe quelle requête. -Utilisez Redis pour la limitation de débit partagée et la file d'attente -si vous activez ces capacités. - -## Données & migrations - -**Q : Comment les migrations de schéma sont-elles gérées ?** -R : Le pilote synchronise le schéma de la base de données avec vos objets -déclarés au démarrage. Pour Postgres, ce sont des instructions -`CREATE TABLE` / `ALTER TABLE`. Pour des migrations contrôlées dans des -environnements réglementés, définissez `OS_SKIP_SCHEMA_SYNC=1` et gérez le -DDL vous-même. - -**Q : Qu'advient-il des données lorsque je renomme un champ ?** -R : Un renommage est une modification destructrice au niveau de la couche -de données (cela ressemble à « supprimer l'ancienne colonne, ajouter une -nouvelle colonne »). Utilisez `os diff` pour le détecter et ajoutez une -étape de migration (renommez la colonne dans la base de données avant de -déployer le nouvel artefact). - -**Q : Puis-je importer des données depuis CSV / Excel / Salesforce ?** -R : CSV : oui, via `os data create` dans une boucle ou via le téléversement -en masse de Console. Salesforce : la meilleure voie aujourd'hui consiste à -exporter vers CSV puis à importer. Des connecteurs natifs sont dans la -feuille de route. - -**Q : La mise à niveau d'ObjectOS fera-t-elle perdre mes données ?** -R : Non. Les mises à niveau de correctif et mineures ne sont pas -destructrices. Les mises à niveau majeures (par ex. 4 → 5) documentent -explicitement les migrations requises. Faites d'abord une sauvegarde — -[Sauvegarde & DR](/docs/operate/backup). - -## Permissions & multilocation - -**Q : Comment mettre en place une sécurité au niveau des lignes ?** -R : Déclarez une règle de partage (déclarative, comme Salesforce) ou un -prédicat CEL sur la configuration `recordAccess` d'un objet. Le plugin de -sécurité injecte le filtre correspondant à chaque requête. Voir -[Permissions](/docs/configure/permissions). - -**Q : Puis-je rendre certains champs invisibles pour certains utilisateurs ?** -R : Oui — sécurité au niveau des champs dans les ensembles de permissions. -Masqué ou en lecture seule, par champ et par ensemble de permissions. -Appliqué uniformément sur REST, ObjectQL et Console. Voir -[Ensembles de permissions](/docs/configure/permissions/permission-sets). - -**Q : Comment intégrer Okta / Entra / Keycloak ?** -R : OIDC. Configurez l'URL de découverte + le client id/secret dans -**Console → Authentication** (ou via les variables d'environnement). L'URL -de rappel du fournisseur est -`/api/v1/auth/oauth2/callback/`. Voir [Authentification](/docs/configure/authentication). - -## Intégrations - -**Q : Puis-je envoyer des webhooks ?** -R : Oui — activez `webhooks` dans `requires`. ObjectOS utilise une boîte -d'envoi persistante avec signature HMAC-SHA256. Voir [Webhooks](/docs/configure/webhooks). - -**Q : Puis-je intégrer Zapier / Make / n8n ?** -R : Oui — des webhooks pour le sortant et l'API REST + des clés d'API pour -l'entrant. Des connecteurs natifs pour les outils iPaaS populaires sont -dans la feuille de route. - -**Q : Les agents IA peuvent-ils appeler mon ObjectOS ?** -R : Oui, via MCP (`@objectstack/mcp`) — il expose les objets -et les actions comme des outils MCP que Claude Desktop, les IDE ou d'autres -clients MCP peuvent utiliser. Voir [Service IA](/docs/configure/ai). - -## Personnalisation - -**Q : Puis-je écrire des plugins personnalisés ?** -R : Oui — les plugins suivent un modèle simple d'injection de dépendances -et de cycle de vie (`init → start → destroy`). Voir les paquets -`@objectstack/plugin-*` sur GitHub pour des exemples. - -**Q : Puis-je personnaliser l'apparence de Console ?** -R : L'image de marque (logo, couleur d'accentuation, thème par défaut) se -trouve dans **Console → System Settings**. Une personnalisation poussée de -l'UI implique de forker `@objectstack/client-react` ou de créer votre -propre front-end basé sur l'API REST. - -**Q : Puis-je ajouter d'autres langues que l'anglais ?** -R : Oui — l'i18n est de première classe. Utilisez `os i18n extract` / -`os i18n check` et livrez un bundle de traduction. - -## Exploitation - -**Q : Quel est le déploiement de production recommandé ?** -R : Docker (ou Kubernetes pour le multi-pod) + Postgres managé + S3 ou R2 -pour les fichiers + votre gestionnaire de secrets pour `OS_AUTH_SECRET`. -Voir [Préparation à la production](/docs/operate/production). - -**Q : ObjectOS dispose-t-il d'une page de statut ?** -R : Pour votre déploiement auto-hébergé, le statut est de votre ressort — -branchez `/health` à votre moniteur. Pour les services hébergés, voir -[status.objectstack.ai](https://status.objectstack.ai). - -**Q : Quelles métriques dois-je surveiller ?** -R : Taux de 5xx, latence p95, taux d'échec d'authentification, taux d'échec -de cache du noyau, profondeur de la file d'attente. Exemple Prometheus -minimal dans [Observabilité](/docs/operate/observability). - -**Q : Comment effectuer une sauvegarde ?** -R : Sauvegardez la **base de données** et le **bucket de stockage** — ce -sont eux qui contiennent toutes les données client. ObjectOS lui-même est -sans état. Voir [Sauvegarde](/docs/operate/backup). - -## Tarification & aspects juridiques - -**Q : ObjectOS est-il vraiment gratuit ?** -R : Oui. Apache-2.0. Pas de sièges, pas de palier d'utilisation, pas de -serveur de licences. - -**Q : Puis-je utiliser ObjectOS dans un produit commercial que je vends ?** -R : Oui. Apache-2.0 autorise un usage commercial. Voir [Licence](/docs/resources/license). - -**Q : Collectez-vous de la télémétrie ?** -R : Non. Zéro appel sortant sauf si vous les configurez (OIDC, e-mail, IA, -webhooks). Voir [Sécurité & conformité](/docs/reference/security#data-residency). - -**Q : ObjectOS est-il conforme à SOC 2 / ISO 27001 / HIPAA / RGPD ?** -R : ObjectOS fournit les **primitives** que tout framework requiert (RBAC, -audit, prêt pour le chiffrement, résidence). La certification est une -propriété de votre **déploiement**, pas du binaire. De nombreux -déploiements ObjectOS sont certifiés. Voir [Sécurité & conformité](/docs/reference/security#compliance-frameworks). - -## Se débloquer - -**Q : Quelque chose ne fonctionne pas — par où commencer ?** -R : `os doctor`. Il détecte à lui seul 80 % des erreurs de configuration. -Ensuite, [Dépannage](/docs/operate/troubleshooting). - -**Q : Où signaler un bug ?** -R : [GitHub Issues](https://github.com/objectstack-ai/objectos/issues). -Incluez la sortie de `os doctor`. Problèmes de sécurité : -**security@objectstack.ai**. - -**Q : Où obtenir de l'aide auprès d'humains ?** -R : [GitHub Discussions](https://github.com/objectstack-ai/objectos/discussions), -le Discord communautaire, ou **sales@objectstack.ai** pour le support -commercial. diff --git a/content/docs/resources/faq.ja.mdx b/content/docs/resources/faq.ja.mdx deleted file mode 100644 index 5c88356..0000000 --- a/content/docs/resources/faq.ja.mdx +++ /dev/null @@ -1,203 +0,0 @@ ---- -title: FAQ -description: よく寄せられる質問への回答。 -translation: - source_sha: 8267da8b9943789c7cae4d84724c9fb36d3a48ec09f8a6665652bc8dec94138d - guide_rev: 1 - mode: auto ---- - -## はじめに - -**Q: ObjectOS を最速で試す方法は?** -A: `npm i -g @objectstack/cli && os start` を実行し、 -http://localhost:3000 を開いてください。[クイックスタート](/docs/quickstart)を参照してください。 - -**Q: Docker は必要ですか?** -A: いいえ。Node 20+ と CLI があれば十分です。Docker は本番環境への -推奨デプロイ構成です。 - -**Q: データベースは必要ですか?** -A: いいえ、開始時には不要です。ObjectOS はデフォルトでローカルの SQLite を -使用します。本番環境に移行する際は Postgres / MySQL / Turso / Mongo に -切り替えてください。 - -**Q: アカウントやクラウドサービスは必要ですか?** -A: いいえ。ObjectOS は完全に自己完結しています。ObjectStack Cloud は、 -コントロールプレーンを備えたマルチ環境・マルチアプリのデプロイにおいて -任意で利用できます。 - -## アーキテクチャ - -**Q: Postgres / MySQL / MongoDB を使えますか?** -A: はい。Postgres、MySQL、SQLite、Turso/libSQL、MongoDB が -サポートされるドライバです。[ランタイム設定](/docs/configure/runtime)を参照してください。 - -**Q: Console / Account を無効化して REST API のみを使えますか?** -A: はい。`os start --no-ui` を実行するか、対応するフラグを設定してください。 -REST API は UI がマウントされているかどうかに関わらず同一です。 - -**Q: Console の代わりに独自のフロントエンドを使えますか?** -A: はい。Console は、独自のコードから呼び出すのと同じ `/api/v1/*` -エンドポイントを使用します。`@objectstack/client` SDK または任意の HTTP -クライアントを使用してください。 - -**Q: ObjectOS は GraphQL をサポートしていますか?** -A: REST が主要なインターフェースです。GraphQL はロードマップにあります。 -それまでは、ObjectQL クエリ言語(REST の `?filter=`/`?sort=` 上)が -同等の範囲をカバーします。 - -**Q: マルチテナンシーはどのように扱われますか?** -A: 1 つの ObjectOS プロセスが多数の Environment(テナント)を提供できます。 -ホスト名 → Environment の解決は LRU にキャッシュされ、各 Environment は -独自のデータベース、アイデンティティ、監査ログを持ちます。Cookie は -ホスト名ごとにスコープされるため、セッションがテナント間で漏れることは -ありません。 - -**Q: ObjectOS はサーバーレス / Lambda 環境で実行できますか?** -A: ランタイムは長時間稼働する Node プロセスであり、ステートレスな関数では -なくコンテナや VM 向けに設計されています。カーネルキャッシュと Better Auth -のセッションモデルはいずれも、プロセス内のウォームな状態に依存します。 - -**Q: 水平方向にスケールしますか?** -A: はい。複数のインスタンスをロードバランサーの背後で実行してください。 -セッションはデータベース(インメモリではない)に保存されるため、どの -インスタンスでも任意のリクエストを処理できます。共有のレート制限やキューを -有効にする場合は Redis を使用してください。 - -## データとマイグレーション - -**Q: スキーマのマイグレーションはどのように扱われますか?** -A: ドライバは起動時に、宣言したオブジェクトに合わせてデータベース -スキーマを同期します。Postgres の場合、`CREATE TABLE` / `ALTER TABLE` -ステートメントになります。規制された環境で制御されたマイグレーションを -行う場合は、`OS_SKIP_SCHEMA_SYNC=1` を設定し、DDL を自分で管理してください。 - -**Q: フィールド名を変更するとデータはどうなりますか?** -A: 名前の変更はデータ層では破壊的な変更です(「古い列を削除し、新しい列を -追加する」ように見えます)。`os diff` でこれを検出し、マイグレーションの -ステップを追加してください(新しいアーティファクトをデプロイする前に DB で -列名を変更します)。 - -**Q: CSV / Excel / Salesforce からデータをインポートできますか?** -A: CSV: はい、ループ内での `os data create` または Console の一括アップロードで -可能です。Salesforce: 現時点で最善の方法は CSV にエクスポートしてから -インポートすることです。ネイティブコネクタはロードマップにあります。 - -**Q: ObjectOS をアップグレードするとデータが失われますか?** -A: いいえ。パッチおよびマイナーアップグレードは非破壊的です。メジャー -アップグレード(例: 4 → 5)では必要なマイグレーションが明示的に文書化されます。 -まずバックアップを取得してください。[バックアップと DR](/docs/operate/backup)。 - -## 権限とマルチテナンシー - -**Q: 行レベルのセキュリティはどう実装しますか?** -A: 共有ルール(Salesforce のような宣言的なもの)、またはオブジェクトの -`recordAccess` 設定における CEL の述語を宣言してください。セキュリティ -プラグインがすべてのクエリに対応するフィルタを注入します。 -[権限](/docs/configure/permissions)を参照してください。 - -**Q: 特定のユーザーには一部のフィールドを非表示にできますか?** -A: はい。権限セットでのフィールドレベルセキュリティです。権限セットごと、 -フィールドごとに非表示または読み取り専用にできます。REST、ObjectQL、 -Console 全体で一様に適用されます。 -[権限セット](/docs/configure/permissions/permission-sets)を参照してください。 - -**Q: Okta / Entra / Keycloak とどう統合しますか?** -A: OIDC です。**Console → Authentication**(または env 経由)で -ディスカバリ URL とクライアント id / secret を設定してください。プロバイダの -コールバック URL は `/api/v1/auth/oauth2/callback/` です。 -[認証](/docs/configure/authentication)を参照してください。 - -## 連携 - -**Q: Webhook を送信できますか?** -A: はい。`requires` で `webhooks` を有効にしてください。ObjectOS は -HMAC-SHA256 署名付きの永続的な outbox を使用します。 -[Webhooks](/docs/configure/webhooks)を参照してください。 - -**Q: Zapier / Make / n8n と統合できますか?** -A: はい。アウトバウンドには Webhook、インバウンドには REST API + API キーを -使用します。人気の iPaaS ツール向けのネイティブコネクタはロードマップに -あります。 - -**Q: AI エージェントは私の ObjectOS を呼び出せますか?** -A: はい、MCP(`@objectstack/mcp`)経由で可能です。オブジェクトや -アクションを MCP ツールとして公開し、Claude Desktop、IDE、その他の MCP -クライアントが利用できます。[AI Service](/docs/configure/ai)を参照してください。 - -## カスタマイズ - -**Q: カスタムプラグインを書けますか?** -A: はい。プラグインはシンプルな DI + ライフサイクルパターン -(`init → start → destroy`)に従います。例については GitHub 上の -`@objectstack/plugin-*` パッケージを参照してください。 - -**Q: Console の見た目をカスタマイズできますか?** -A: ブランディング(ロゴ、アクセントカラー、デフォルトテーマ)は -**Console → System Settings** にあります。より高度な UI カスタマイズには、 -`@objectstack/client-react` をフォークするか、REST API に対して独自の -フロントエンドを構築する必要があります。 - -**Q: 英語以外の言語を追加できますか?** -A: はい。i18n はファーストクラスでサポートされています。`os i18n extract` / -`os i18n check` を使用し、翻訳バンドルを同梱してください。 - -## 運用 - -**Q: 推奨される本番デプロイ構成は?** -A: Docker(マルチポッドの場合は Kubernetes)+ マネージド Postgres + -ファイル用の S3 または R2 + `OS_AUTH_SECRET` 用のシークレットマネージャです。 -[本番環境への準備](/docs/operate/production)を参照してください。 - -**Q: ObjectOS にステータスページはありますか?** -A: セルフホスト型のデプロイでは、ステータスはあなたの責任です。`/health` を -監視ツールに接続してください。ホスト型サービスについては -[status.objectstack.ai](https://status.objectstack.ai) を参照してください。 - -**Q: どのメトリクスを監視すべきですか?** -A: 5xx 率、p95 レイテンシ、認証失敗率、カーネルキャッシュのミス率、 -キューの深さです。最小限の Prometheus の例は -[Observability](/docs/operate/observability)にあります。 - -**Q: バックアップはどう取得しますか?** -A: **データベース**と**ストレージバケット**をバックアップしてください。 -それらにすべての顧客データが保持されています。ObjectOS 自体はステートレスです。 -[バックアップ](/docs/operate/backup)を参照してください。 - -## 料金と法務 - -**Q: ObjectOS は本当に無料ですか?** -A: はい。Apache-2.0 です。シート課金も使用量ティアもライセンスサーバーも -ありません。 - -**Q: 販売する商用製品に ObjectOS を使えますか?** -A: はい。Apache-2.0 は商用利用を許可しています。 -[ライセンス](/docs/resources/license)を参照してください。 - -**Q: テレメトリを収集しますか?** -A: いいえ。あなたが設定しない限り、アウトバウンド通信は一切ありません -(OIDC、メール、AI、Webhook)。 -[セキュリティとコンプライアンス](/docs/reference/security#data-residency)を参照してください。 - -**Q: ObjectOS は SOC 2 / ISO 27001 / HIPAA / GDPR に準拠していますか?** -A: ObjectOS は、あらゆるフレームワークが必要とする**プリミティブ**(RBAC、 -監査、暗号化対応、データレジデンシー)を提供します。認証はバイナリではなく -あなたの**デプロイ**の属性です。多くの ObjectOS デプロイが認証を取得しています。 -[セキュリティとコンプライアンス](/docs/reference/security#compliance-frameworks)を参照してください。 - -## 行き詰まったときは - -**Q: 何かが壊れている、まず何をすべき?** -A: `os doctor` です。これだけで設定ミスの 80% を捕捉します。その後は -[トラブルシューティング](/docs/operate/troubleshooting)へ。 - -**Q: バグはどこに報告しますか?** -A: [GitHub Issues](https://github.com/objectstack-ai/objectos/issues) です。 -`os doctor` の出力を含めてください。セキュリティの問題は -**security@objectstack.ai** へ。 - -**Q: 人によるサポートはどこで受けられますか?** -A: [GitHub Discussions](https://github.com/objectstack-ai/objectos/discussions)、 -コミュニティの Discord、または商用サポートについては **sales@objectstack.ai** -へ。 diff --git a/content/docs/resources/faq.ko.mdx b/content/docs/resources/faq.ko.mdx deleted file mode 100644 index de20ada..0000000 --- a/content/docs/resources/faq.ko.mdx +++ /dev/null @@ -1,189 +0,0 @@ ---- -title: 자주 묻는 질문 -description: 가장 많이 받는 질문에 대한 답변입니다. -translation: - source_sha: 8267da8b9943789c7cae4d84724c9fb36d3a48ec09f8a6665652bc8dec94138d - guide_rev: 1 - mode: auto ---- - -## 시작하기 - -**Q: ObjectOS를 가장 빠르게 사용해 볼 수 있는 방법은 무엇인가요?** -A: `npm i -g @objectstack/cli && os start` — 그런 다음 -http://localhost:3000 을 엽니다. [Quickstart](/docs/quickstart)를 참고하세요. - -**Q: Docker가 필요한가요?** -A: 아니요. Node 20+ 와 CLI만 있으면 충분합니다. Docker는 권장되는 -프로덕션 배포 형태입니다. - -**Q: 데이터베이스가 필요한가요?** -A: 아니요, 시작하는 데는 필요하지 않습니다 — ObjectOS는 기본적으로 로컬 SQLite를 사용합니다. -프로덕션으로 전환할 때 Postgres / MySQL / Turso / Mongo로 교체하세요. - -**Q: 계정 / 클라우드 서비스가 필요한가요?** -A: 아니요. ObjectOS는 완전히 독립적입니다. ObjectStack Cloud는 컨트롤 플레인을 갖춘 -다중 환경 / 다중 앱 배포를 위한 선택 사항입니다. - -## 아키텍처 - -**Q: Postgres / MySQL / MongoDB를 사용할 수 있나요?** -A: 예 — Postgres, MySQL, SQLite, Turso/libSQL, MongoDB가 -지원되는 드라이버입니다. [Runtime Configuration](/docs/configure/runtime)를 참고하세요. - -**Q: Console / Account를 비활성화하고 REST API만 사용할 수 있나요?** -A: 예. `os start --no-ui`를 실행하거나 해당 플래그를 설정하세요. UI가 마운트되어 있든 -아니든 REST API는 동일합니다. - -**Q: Console 대신 제 자체 프런트엔드를 사용할 수 있나요?** -A: 예. Console은 여러분이 자체 코드에서 호출하는 것과 동일한 `/api/v1/*` 엔드포인트를 -사용합니다. `@objectstack/client` SDK 또는 임의의 HTTP 클라이언트를 사용하세요. - -**Q: ObjectOS는 GraphQL을 지원하나요?** -A: REST가 기본 인터페이스입니다. GraphQL은 로드맵에 있습니다 — 그때까지는 -ObjectQL 쿼리 언어(REST `?filter=`/`?sort=` 기반)가 동일한 영역을 -다룹니다. - -**Q: 멀티테넌시는 어떻게 처리되나요?** -A: 하나의 ObjectOS 프로세스는 여러 Environment(테넌트)를 제공할 수 있습니다. 호스트명 -→ Environment 해석은 LRU에 캐시됩니다. 각 Environment는 자체 -데이터베이스, 신원, 감사 로그를 갖습니다. 쿠키는 호스트명별로 스코프가 지정되므로 -세션이 테넌트 간에 누출될 수 없습니다. - -**Q: ObjectOS를 서버리스 / Lambda 환경에서 실행할 수 있나요?** -A: 런타임은 장기 실행되는 Node 프로세스입니다 — 상태 비저장 함수가 아니라 컨테이너나 -VM을 위해 설계되었습니다. 커널 캐시와 Better Auth -세션 모델은 모두 워밍된 인프로세스 상태에 의존합니다. - -**Q: 수평적으로 확장되나요?** -A: 예. 로드 밸런서 뒤에서 여러 인스턴스를 실행하세요. 세션은 -데이터베이스에 저장되므로(메모리가 아님) 어떤 인스턴스든 어떤 요청이든 처리할 수 있습니다. -해당 기능을 활성화하는 경우 공유 속도 제한 및 큐를 위해 Redis를 -사용하세요. - -## 데이터 및 마이그레이션 - -**Q: 스키마 마이그레이션은 어떻게 처리되나요?** -A: 드라이버는 부팅 시 선언된 객체에 맞게 데이터베이스 스키마를 -동기화합니다. Postgres의 경우 `CREATE TABLE` / `ALTER TABLE` 문입니다. -규제 환경에서 통제된 마이그레이션을 수행하려면 -`OS_SKIP_SCHEMA_SYNC=1`을 설정하고 DDL을 직접 관리하세요. - -**Q: 필드 이름을 변경하면 데이터는 어떻게 되나요?** -A: 이름 변경은 데이터 계층에서 파괴적인 변경입니다("기존 열 삭제, -새 열 추가"처럼 보입니다). `os diff`를 사용해 이를 감지하고 마이그레이션 -단계를 추가하세요(새 아티팩트를 배포하기 전에 DB에서 열 이름 -변경). - -**Q: CSV / Excel / Salesforce에서 데이터를 가져올 수 있나요?** -A: CSV: 예, 반복 루프 내에서 `os data create`를 사용하거나 Console 일괄 업로드를 통해 가능합니다. -Salesforce: 현재 가장 좋은 경로는 CSV로 내보낸 후 가져오는 것입니다. 네이티브 -커넥터는 로드맵에 있습니다. - -**Q: ObjectOS를 업그레이드하면 데이터가 손실되나요?** -A: 아니요. 패치 및 마이너 업그레이드는 비파괴적입니다. 메이저 업그레이드 -(예: 4 → 5)는 필요한 마이그레이션을 명시적으로 문서화합니다. 먼저 백업하세요 — -[Backup & DR](/docs/operate/backup). - -## 권한 및 멀티테넌시 - -**Q: 행 수준 보안은 어떻게 하나요?** -A: 공유 규칙(선언적, Salesforce와 유사)을 선언하거나 객체의 `recordAccess` -구성에 CEL 술어를 선언하세요. 보안 플러그인은 -모든 쿼리에 해당 필터를 주입합니다. -[Permissions](/docs/configure/permissions)를 참고하세요. - -**Q: 특정 사용자에게 일부 필드를 보이지 않게 할 수 있나요?** -A: 예 — 권한 집합의 필드 수준 보안입니다. 권한 집합별로 필드별로 -숨김 또는 읽기 전용으로 설정합니다. REST, ObjectQL, -Console 전반에 걸쳐 일관되게 적용됩니다. [Permission Sets](/docs/configure/permissions/permission-sets)를 참고하세요. - -**Q: Okta / Entra / Keycloak를 어떻게 통합하나요?** -A: OIDC. **Console → -Authentication**에서(또는 환경 변수를 통해) 디스커버리 URL + 클라이언트 ID/시크릿을 구성하세요. 제공자 콜백 URL은 -`/api/v1/auth/oauth2/callback/`입니다. [Authentication](/docs/configure/authentication)를 참고하세요. - -## 통합 - -**Q: 웹훅을 보낼 수 있나요?** -A: 예 — `requires`에서 `webhooks`를 활성화하세요. ObjectOS는 HMAC-SHA256 -서명이 적용된 영구 아웃박스를 사용합니다. [Webhooks](/docs/configure/webhooks)를 참고하세요. - -**Q: Zapier / Make / n8n과 통합할 수 있나요?** -A: 예 — 아웃바운드는 웹훅으로, 인바운드는 REST API + API 키로 가능합니다. -인기 있는 iPaaS 도구를 위한 네이티브 커넥터는 로드맵에 있습니다. - -**Q: AI 에이전트가 제 ObjectOS를 호출할 수 있나요?** -A: 예, MCP(`@objectstack/mcp`)를 통해 가능합니다 — 객체와 -액션을 Claude Desktop, IDE 또는 기타 MCP -클라이언트가 사용할 수 있는 MCP 도구로 노출합니다. [AI Service](/docs/configure/ai)를 참고하세요. - -## 커스터마이징 - -**Q: 사용자 정의 플러그인을 작성할 수 있나요?** -A: 예 — 플러그인은 간단한 DI + 라이프사이클 패턴 -(`init → start → destroy`)을 따릅니다. 예제는 GitHub의 `@objectstack/plugin-*` -패키지를 참고하세요. - -**Q: Console의 외관을 커스터마이즈할 수 있나요?** -A: 브랜딩(로고, 강조 색상, 기본 테마)은 **Console → -System Settings**에 있습니다. 심도 있는 UI 커스터마이징은 -`@objectstack/client-react`를 포크하거나 REST API에 맞춰 자체 프런트엔드를 -구축하는 것을 의미합니다. - -**Q: 영어 외의 언어를 추가할 수 있나요?** -A: 예 — i18n은 일급 기능입니다. `os i18n extract` / `os i18n check`를 -사용하고 번역 번들을 배포하세요. - -## 운영 - -**Q: 권장되는 프로덕션 배포는 무엇인가요?** -A: Docker(또는 다중 파드용 Kubernetes) + 관리형 Postgres + 파일용 S3 또는 R2 -+ `OS_AUTH_SECRET`을 위한 시크릿 관리자입니다. -[Production Readiness](/docs/operate/production)를 참고하세요. - -**Q: ObjectOS에 상태 페이지가 있나요?** -A: 셀프 호스팅 배포의 경우 상태는 여러분의 책임입니다 — -`/health`를 모니터에 연결하세요. 호스팅 서비스의 경우 -[status.objectstack.ai](https://status.objectstack.ai)를 참고하세요. - -**Q: 어떤 메트릭을 모니터링해야 하나요?** -A: 5xx 비율, p95 지연 시간, 인증 실패율, 커널 캐시 미스율, -큐 깊이입니다. 최소한의 Prometheus 예제는 [Observability](/docs/operate/observability)에 있습니다. - -**Q: 백업은 어떻게 하나요?** -A: **데이터베이스**와 **스토리지 버킷**을 백업하세요 — 그것들이 -모든 고객 데이터를 담고 있습니다. ObjectOS 자체는 상태 비저장입니다. [Backup](/docs/operate/backup)을 참고하세요. - -## 가격 및 법적 사항 - -**Q: ObjectOS는 정말 무료인가요?** -A: 예. Apache-2.0. 좌석 수, 사용 등급, 라이선스 서버가 없습니다. - -**Q: 제가 판매하는 상용 제품에 ObjectOS를 사용할 수 있나요?** -A: 예. Apache-2.0은 상업적 사용을 허용합니다. [License](/docs/resources/license)를 참고하세요. - -**Q: 텔레메트리를 수집하나요?** -A: 아니요. 여러분이 구성하지 않는 한 아웃바운드 호출은 전혀 없습니다(OIDC, 이메일, AI, -웹훅). [Security & Compliance](/docs/reference/security#data-residency)를 참고하세요. - -**Q: ObjectOS는 SOC 2 / ISO 27001 / HIPAA / GDPR를 준수하나요?** -A: ObjectOS는 모든 프레임워크가 요구하는 **기본 요소**(RBAC, -감사, 암호화 준비, 데이터 위치)를 제공합니다. 인증은 바이너리가 아니라 -여러분의 **배포**의 속성입니다. 많은 ObjectOS 배포가 -인증을 받았습니다. [Security & Compliance](/docs/reference/security#compliance-frameworks)를 참고하세요. - -## 막혔을 때 해결하기 - -**Q: 무언가 망가졌어요 — 어디서부터 시작해야 하나요?** -A: `os doctor`. 이것은 잘못된 구성의 80%를 자체적으로 잡아냅니다. 그 후에는 -[Troubleshooting](/docs/operate/troubleshooting)을 참고하세요. - -**Q: 버그는 어디에 보고하나요?** -A: [GitHub Issues](https://github.com/objectstack-ai/objectos/issues). -`os doctor` 출력을 포함해 주세요. 보안 문제는 -**security@objectstack.ai**로 알려주세요. - -**Q: 사람에게 도움을 받으려면 어디로 가야 하나요?** -A: [GitHub Discussions](https://github.com/objectstack-ai/objectos/discussions), -커뮤니티 Discord, 또는 상업적 지원을 위한 **sales@objectstack.ai**입니다. diff --git a/content/docs/resources/faq.mdx b/content/docs/resources/faq.mdx index 15536ff..83d67d2 100644 --- a/content/docs/resources/faq.mdx +++ b/content/docs/resources/faq.mdx @@ -6,20 +6,26 @@ description: Answers to questions we get asked the most. ## Getting started **Q: What's the absolute fastest way to try ObjectOS?** -A: `npm i -g @objectstack/cli && os start` — then open +A: Sign in to [ObjectOS Cloud](https://www.objectos.ai) — hosted in the +browser, nothing to install. To run the open-source ObjectStack runtime on +your own machine instead, `npm i -g @objectstack/cli && os start` and open http://localhost:3000. See [Quickstart](/docs/quickstart). **Q: Do I need Docker?** -A: No. Node 22+ and the CLI are enough. Docker is the recommended -production deployment shape. +A: No. ObjectOS Cloud needs nothing installed. For the open runtime, Node +22+ and the CLI are enough; Docker is the recommended shape for a +self-managed production deployment. **Q: Do I need a database?** -A: No, not to start — ObjectOS uses local SQLite by default. Swap for -Postgres / MySQL / Turso / Mongo when you go to production. +A: No, not to start — ObjectOS Cloud is managed for you, and the open +runtime uses local SQLite by default. A self-managed deployment swaps in +Postgres / MySQL / Turso / Mongo when it goes to production. **Q: Do I need an account / cloud service?** -A: No. ObjectOS is fully self-contained. ObjectOS Cloud is optional -for multi-environment / multi-app deployments with a control plane. +A: ObjectOS Cloud *is* the account: sign in and build. ObjectOS Enterprise +is self-managed and needs no cloud service to run — connecting it to a +control plane is optional. The open-source ObjectStack runtime needs no +account at all. ## Architecture @@ -154,8 +160,8 @@ for files + your secret manager for `OS_AUTH_SECRET`. See [Production Readiness](/docs/operate/production). **Q: Does ObjectOS have a status page?** -A: For your self-hosted deployment, status is your concern — point your -monitor at `/api/v1/health` for liveness and `/api/v1/ready` for readiness, +A: For a self-managed (Enterprise) deployment, status is your concern — point +your monitor at `/api/v1/health` for liveness and `/api/v1/ready` for readiness, the pair [Docker](/docs/deploy/docker) and [Kubernetes](/docs/deploy/kubernetes) wire up. For hosted services, see [status.objectstack.ai](https://status.objectstack.ai). diff --git a/content/docs/resources/faq.zh-Hans.mdx b/content/docs/resources/faq.zh-Hans.mdx deleted file mode 100644 index acb1e6b..0000000 --- a/content/docs/resources/faq.zh-Hans.mdx +++ /dev/null @@ -1,181 +0,0 @@ ---- -title: FAQ -description: 我们最常被问到的问题及答案。 -translation: - source_sha: 8267da8b9943789c7cae4d84724c9fb36d3a48ec09f8a6665652bc8dec94138d - guide_rev: 1 - mode: auto ---- - -## 起步 - -**Q：试用 ObjectOS 最快的方法是什么？** -A：`npm i -g @objectstack/cli && os start` —— 然后打开 -http://localhost:3000。见 [快速开始](/docs/quickstart)。 - -**Q：需要 Docker 吗？** -A：不需要。Node 20+ 和 CLI 就够了。Docker 是推荐的生产部署形态。 - -**Q：需要数据库吗？** -A：起步时不需要 —— ObjectOS 默认使用本地 SQLite。生产时可换成 -Postgres / MySQL / Turso / Mongo。 - -**Q：需要账号 / 云服务吗？** -A：不需要。ObjectOS 完全自包含。ObjectStack Cloud 是可选的，用于 -带控制面的多环境 / 多应用部署。 - -## 架构 - -**Q：可以使用 Postgres / MySQL / MongoDB 吗？** -A：可以 —— 支持的驱动包括 Postgres、MySQL、SQLite、Turso/libSQL -与 MongoDB。见 [运行时配置](/docs/configure/runtime)。 - -**Q：可以关闭 Console / Account，只使用 REST API 吗？** -A：可以。运行 `os start --no-ui` 或设置相应开关。无论是否挂载 UI， -REST API 都一致。 - -**Q：可以用自己的前端代替 Console 吗？** -A：可以。Console 调用的是与你自己代码相同的 `/api/v1/*` 接口。使用 -`@objectstack/client` SDK 或任意 HTTP 客户端即可。 - -**Q：ObjectOS 支持 GraphQL 吗？** -A：REST 是主要接口形态。GraphQL 在路线图中 —— 在此之前，ObjectQL -查询语言（通过 REST 的 `?filter=`/`?sort=`）能覆盖同样的能力。 - -**Q：多租户是如何处理的？** -A：单个 ObjectOS 进程可以服务多个 Environment（租户）。主机名 → -Environment 的解析使用 LRU 缓存;每个 Environment 拥有自己的 -数据库、身份与审计日志。Cookie 按主机名作用域，会话不会在租户 -之间泄露。 - -**Q：ObjectOS 能跑在 serverless / Lambda 环境里吗？** -A：运行时是长驻 Node 进程 —— 面向容器或 VM 设计，不面向无状态 -函数。内核缓存与 Better Auth 的会话模型都依赖进程内的热状态。 - -**Q：能水平扩展吗？** -A：可以。把多个实例放在负载均衡器后面。会话存于数据库（不在内存 -中），任意实例都能处理任意请求。如果启用相关能力，请用 Redis 做 -共享限流与队列。 - -## 数据与迁移 - -**Q：schema 迁移如何处理？** -A：驱动在启动时把数据库 schema 同步到你声明的对象。对 Postgres -来说就是 `CREATE TABLE` / `ALTER TABLE`。受监管环境需要受控迁移 -时，设置 `OS_SKIP_SCHEMA_SYNC=1`，自行管理 DDL。 - -**Q：重命名字段时数据怎么办？** -A：在数据层上重命名是破坏性变更（看起来像"删旧列、加新列"）。用 -`os diff` 检测出来，并加一步迁移（在部署新产物前，先在 DB 中重命名 -列）。 - -**Q：能从 CSV / Excel / Salesforce 导入数据吗？** -A：CSV：可以，通过 `os data create` 循环或 Console 批量上传。 -Salesforce：目前最好的路径是导出 CSV 再导入。原生连接器在路线图中。 - -**Q：升级 ObjectOS 会丢数据吗？** -A：不会。Patch 与 minor 升级是非破坏性的。Major 升级（如 4 → 5） -会显式列出所需迁移。请先备份 —— 见 -[备份与灾难恢复](/docs/operate/backup)。 - -## 权限与多租户 - -**Q：怎么做行级安全？** -A：声明一条共享规则（声明式，类似 Salesforce），或在对象的 -`recordAccess` 配置中声明一个 CEL 谓词。安全插件会在每次查询时注入 -对应的过滤条件。见 [权限](/docs/configure/permissions)。 - -**Q：能让某些字段对特定用户不可见吗？** -A：可以 —— 权限集中提供字段级安全。可按字段、按权限集设置为隐藏 -或只读。在 REST、ObjectQL 与 Console 中统一生效。见 -[权限集](/docs/configure/permissions/permission-sets)。 - -**Q：如何对接 Okta / Entra / Keycloak？** -A：OIDC。在 **Console → Authentication** 中（或通过环境变量） -配置发现 URL 与 client id/secret。Provider 回调 URL 为 -`/api/v1/auth/oauth2/callback/`。见 -[认证](/docs/configure/authentication)。 - -## 集成 - -**Q：可以发送 webhook 吗？** -A：可以 —— 在 `requires` 中启用 `webhooks`。ObjectOS 使用持久化 -outbox + HMAC-SHA256 签名。见 [Webhooks](/docs/configure/webhooks)。 - -**Q：可以集成 Zapier / Make / n8n 吗？** -A：可以 —— 出站走 webhook，入站走 REST API + API key。主流 iPaaS -的原生连接器在路线图中。 - -**Q：AI 智能体能调用我的 ObjectOS 吗？** -A：可以，通过 MCP（`@objectstack/mcp`） —— 把对象与 -action 暴露为 MCP 工具，供 Claude Desktop、IDE 或其他 MCP 客户端 -使用。见 [AI 服务](/docs/configure/ai)。 - -## 自定义 - -**Q：能写自定义插件吗？** -A：可以 —— 插件遵循简洁的 DI + 生命周期模式 -（`init → start → destroy`）。在 GitHub 上的 `@objectstack/plugin-*` -包是参考样例。 - -**Q：能定制 Console 的外观吗？** -A：品牌化（Logo、强调色、默认主题）在 **Console → System Settings** -中调整。深度 UI 定制意味着 fork `@objectstack/client-react` 或基于 -REST API 构建自己的前端。 - -**Q：可以添加英文以外的语言吗？** -A：可以 —— i18n 是一等公民。使用 `os i18n extract` / `os i18n check` -并发布一份翻译包。 - -## 运维 - -**Q：推荐的生产部署是什么？** -A：Docker（多 Pod 场景用 Kubernetes）+ 托管 Postgres + 用 S3 或 -R2 存文件 + 用密钥管理器存 `OS_AUTH_SECRET`。见 -[生产就绪](/docs/operate/production)。 - -**Q：ObjectOS 有状态页吗？** -A：自托管部署的状态由你自己负责 —— 把 `/health` 接到监控上。 -托管服务请见 -[status.objectstack.ai](https://status.objectstack.ai)。 - -**Q：应该监控哪些指标？** -A：5xx 率、p95 时延、认证失败率、内核缓存未命中率、队列深度。 -最小化 Prometheus 示例见 [可观测性](/docs/operate/observability)。 - -**Q：怎么做备份？** -A：备份 **数据库** 与 **存储 bucket** —— 它们承载所有客户数据。 -ObjectOS 自身是无状态的。见 [备份](/docs/operate/backup)。 - -## 计费与法务 - -**Q：ObjectOS 真的免费吗？** -A：是的。Apache-2.0。没有席位计费、没有用量层级、没有许可证服务器。 - -**Q：可以在我对外销售的商业产品里使用 ObjectOS 吗？** -A：可以。Apache-2.0 允许商用。见 [许可证](/docs/resources/license)。 - -**Q：你们收集遥测吗？** -A：不收集。除非你自己配置（OIDC、邮件、AI、webhook），否则无任何 -出站调用。见 [安全与合规](/docs/reference/security#data-residency)。 - -**Q：ObjectOS 是否符合 SOC 2 / ISO 27001 / HIPAA / GDPR？** -A：ObjectOS 提供所有框架都需要的**原语**（RBAC、审计、加密就绪、 -数据驻留）。认证属于你的**部署**，而不是这个二进制本身。许多 -ObjectOS 部署都已获得认证。见 -[安全与合规](/docs/reference/security#compliance-frameworks)。 - -## 卡住了怎么办 - -**Q：出问题了，从哪儿入手？** -A：`os doctor`。它能独立处理 80% 的错误配置。之后再看 -[排错](/docs/operate/troubleshooting)。 - -**Q：在哪里报 bug？** -A：[GitHub Issues](https://github.com/objectstack-ai/objectos/issues)。 -附上 `os doctor` 的输出。安全问题： -**security@objectstack.ai**。 - -**Q：在哪里能获得真人帮助？** -A：[GitHub Discussions](https://github.com/objectstack-ai/objectos/discussions)、 -社区 Discord，或商业支持联系 **sales@objectstack.ai**。 diff --git a/content/docs/resources/faq.zh-Hant.mdx b/content/docs/resources/faq.zh-Hant.mdx deleted file mode 100644 index e9950c4..0000000 --- a/content/docs/resources/faq.zh-Hant.mdx +++ /dev/null @@ -1,182 +0,0 @@ ---- -# @generated zh-Hant from zh-Hans -- do not edit. Edit the English source, then regenerate: pnpm --filter @objectos/docs gen:zh-hant -title: FAQ -description: 我們最常被問到的問題及答案。 -translation: - source_sha: 8267da8b9943789c7cae4d84724c9fb36d3a48ec09f8a6665652bc8dec94138d - guide_rev: 1 - mode: auto ---- - -## 起步 - -**Q：試用 ObjectOS 最快的方法是什麼？** -A：`npm i -g @objectstack/cli && os start` —— 然後開啟 -http://localhost:3000。見 [快速開始](/docs/quickstart)。 - -**Q：需要 Docker 嗎？** -A：不需要。Node 20+ 和 CLI 就夠了。Docker 是推薦的生產部署形態。 - -**Q：需要資料庫嗎？** -A：起步時不需要 —— ObjectOS 預設使用本地 SQLite。生產時可換成 -Postgres / MySQL / Turso / Mongo。 - -**Q：需要賬號 / 雲服務嗎？** -A：不需要。ObjectOS 完全自包含。ObjectStack Cloud 是可選的，用於 -帶控制面的多環境 / 多應用部署。 - -## 架構 - -**Q：可以使用 Postgres / MySQL / MongoDB 嗎？** -A：可以 —— 支援的驅動包括 Postgres、MySQL、SQLite、Turso/libSQL -與 MongoDB。見 [執行時配置](/docs/configure/runtime)。 - -**Q：可以關閉 Console / Account，只使用 REST API 嗎？** -A：可以。執行 `os start --no-ui` 或設定相應開關。無論是否掛載 UI， -REST API 都一致。 - -**Q：可以用自己的前端代替 Console 嗎？** -A：可以。Console 呼叫的是與你自己程式碼相同的 `/api/v1/*` 介面。使用 -`@objectstack/client` SDK 或任意 HTTP 客戶端即可。 - -**Q：ObjectOS 支援 GraphQL 嗎？** -A：REST 是主要介面形態。GraphQL 在路線圖中 —— 在此之前，ObjectQL -查詢語言（通過 REST 的 `?filter=`/`?sort=`）能覆蓋同樣的能力。 - -**Q：多租戶是如何處理的？** -A：單個 ObjectOS 程序可以服務多個 Environment（租戶）。主機名 → -Environment 的解析使用 LRU 快取;每個 Environment 擁有自己的 -資料庫、身份與審計日誌。Cookie 按主機名作用域，會話不會在租戶 -之間洩露。 - -**Q：ObjectOS 能跑在 serverless / Lambda 環境裡嗎？** -A：執行時是長駐 Node 程序 —— 面向容器或 VM 設計，不面向無狀態 -函式。核心快取與 Better Auth 的會話模型都依賴程序內的熱狀態。 - -**Q：能水平擴充套件嗎？** -A：可以。把多個例項放在負載均衡器後面。會話存於資料庫（不在記憶體 -中），任意例項都能處理任意請求。如果啟用相關能力，請用 Redis 做 -共享限流與佇列。 - -## 資料與遷移 - -**Q：schema 遷移如何處理？** -A：驅動在啟動時把資料庫 schema 同步到你宣告的物件。對 Postgres -來說就是 `CREATE TABLE` / `ALTER TABLE`。受監管環境需要受控遷移 -時，設定 `OS_SKIP_SCHEMA_SYNC=1`，自行管理 DDL。 - -**Q：重新命名欄位時資料怎麼辦？** -A：在資料層上重新命名是破壞性變更（看起來像"刪舊列、加新列"）。用 -`os diff` 檢測出來，並加一步遷移（在部署新產物前，先在 DB 中重新命名 -列）。 - -**Q：能從 CSV / Excel / Salesforce 匯入資料嗎？** -A：CSV：可以，通過 `os data create` 迴圈或 Console 批次上傳。 -Salesforce：目前最好的路徑是匯出 CSV 再匯入。原生聯結器在路線圖中。 - -**Q：升級 ObjectOS 會丟資料嗎？** -A：不會。Patch 與 minor 升級是非破壞性的。Major 升級（如 4 → 5） -會顯式列出所需遷移。請先備份 —— 見 -[備份與災難恢復](/docs/operate/backup)。 - -## 許可權與多租戶 - -**Q：怎麼做行級安全？** -A：宣告一條共享規則（宣告式，類似 Salesforce），或在物件的 -`recordAccess` 配置中宣告一個 CEL 謂詞。安全外掛會在每次查詢時注入 -對應的過濾條件。見 [許可權](/docs/configure/permissions)。 - -**Q：能讓某些欄位對特定使用者不可見嗎？** -A：可以 —— 許可權集中提供欄位級安全。可按欄位、按許可權集設定為隱藏 -或只讀。在 REST、ObjectQL 與 Console 中統一生效。見 -[許可權集](/docs/configure/permissions/permission-sets)。 - -**Q：如何對接 Okta / Entra / Keycloak？** -A：OIDC。在 **Console → Authentication** 中（或通過環境變數） -配置發現 URL 與 client id/secret。Provider 回撥 URL 為 -`/api/v1/auth/oauth2/callback/`。見 -[認證](/docs/configure/authentication)。 - -## 整合 - -**Q：可以傳送 webhook 嗎？** -A：可以 —— 在 `requires` 中啟用 `webhooks`。ObjectOS 使用持久化 -outbox + HMAC-SHA256 簽名。見 [Webhooks](/docs/configure/webhooks)。 - -**Q：可以整合 Zapier / Make / n8n 嗎？** -A：可以 —— 出站走 webhook，入站走 REST API + API key。主流 iPaaS -的原生聯結器在路線圖中。 - -**Q：AI 智慧體能呼叫我的 ObjectOS 嗎？** -A：可以，通過 MCP（`@objectstack/mcp`） —— 把物件與 -action 暴露為 MCP 工具，供 Claude Desktop、IDE 或其他 MCP 客戶端 -使用。見 [AI 服務](/docs/configure/ai)。 - -## 自定義 - -**Q：能寫自定義外掛嗎？** -A：可以 —— 外掛遵循簡潔的 DI + 生命週期模式 -（`init → start → destroy`）。在 GitHub 上的 `@objectstack/plugin-*` -包是參考樣例。 - -**Q：能定製 Console 的外觀嗎？** -A：品牌化（Logo、強調色、預設主題）在 **Console → System Settings** -中調整。深度 UI 定製意味著 fork `@objectstack/client-react` 或基於 -REST API 構建自己的前端。 - -**Q：可以新增英文以外的語言嗎？** -A：可以 —— i18n 是一等公民。使用 `os i18n extract` / `os i18n check` -併發布一份翻譯包。 - -## 運維 - -**Q：推薦的生產部署是什麼？** -A：Docker（多 Pod 場景用 Kubernetes）+ 託管 Postgres + 用 S3 或 -R2 存檔案 + 用金鑰管理器存 `OS_AUTH_SECRET`。見 -[生產就緒](/docs/operate/production)。 - -**Q：ObjectOS 有狀態頁嗎？** -A：自託管部署的狀態由你自己負責 —— 把 `/health` 接到監控上。 -託管服務請見 -[status.objectstack.ai](https://status.objectstack.ai)。 - -**Q：應該監控哪些指標？** -A：5xx 率、p95 時延、認證失敗率、核心快取未命中率、佇列深度。 -最小化 Prometheus 示例見 [可觀測性](/docs/operate/observability)。 - -**Q：怎麼做備份？** -A：備份 **資料庫** 與 **儲存 bucket** —— 它們承載所有客戶資料。 -ObjectOS 自身是無狀態的。見 [備份](/docs/operate/backup)。 - -## 計費與法務 - -**Q：ObjectOS 真的免費嗎？** -A：是的。Apache-2.0。沒有席位計費、沒有用量層級、沒有許可證伺服器。 - -**Q：可以在我對外銷售的商業產品裡使用 ObjectOS 嗎？** -A：可以。Apache-2.0 允許商用。見 [許可證](/docs/resources/license)。 - -**Q：你們收集遙測嗎？** -A：不收集。除非你自己配置（OIDC、郵件、AI、webhook），否則無任何 -出站呼叫。見 [安全與合規](/docs/reference/security#data-residency)。 - -**Q：ObjectOS 是否符合 SOC 2 / ISO 27001 / HIPAA / GDPR？** -A：ObjectOS 提供所有框架都需要的**原語**（RBAC、審計、加密就緒、 -資料駐留）。認證屬於你的**部署**，而不是這個二進位制本身。許多 -ObjectOS 部署都已獲得認證。見 -[安全與合規](/docs/reference/security#compliance-frameworks)。 - -## 卡住了怎麼辦 - -**Q：出問題了，從哪兒入手？** -A：`os doctor`。它能獨立處理 80% 的錯誤配置。之後再看 -[排錯](/docs/operate/troubleshooting)。 - -**Q：在哪裡報 bug？** -A：[GitHub Issues](https://github.com/objectstack-ai/objectos/issues)。 -附上 `os doctor` 的輸出。安全問題： -**security@objectstack.ai**。 - -**Q：在哪裡能獲得真人幫助？** -A：[GitHub Discussions](https://github.com/objectstack-ai/objectos/discussions)、 -社群 Discord，或商業支援聯絡 **sales@objectstack.ai**。 diff --git a/content/docs/resources/glossary.de.mdx b/content/docs/resources/glossary.de.mdx deleted file mode 100644 index 9ef3a81..0000000 --- a/content/docs/resources/glossary.de.mdx +++ /dev/null @@ -1,232 +0,0 @@ ---- -title: Glossar -description: Das in ObjectOS und ObjectStack verwendete Vokabular — jeweils eine Definition. -translation: - source_sha: b7904d8f61e8f9b0bea68a073206f0af8bd20228a7c8fe8da68e6cc3ac4550e6 - guide_rev: 1 - mode: auto ---- - -Eine einzige kanonische Definition für jeden in dieser Dokumentation verwendeten Begriff. - -### Artifact - -Eine kompilierte `objectstack.json`-Datei. Eine in sich geschlossene, unveränderliche -Beschreibung einer App — Manifest, Objekte, Views, Apps, Flows, -Berechtigungen, Übersetzungen. Erzeugt durch `os compile`. Das, was -ObjectOS tatsächlich ausführt. - -### Action - -Ein in den Metadaten deklarierter, benannter Vorgang, der über REST -(`/api/v1/data//actions/`), Console-Schaltflächen oder Flow-Schritte -aufgerufen werden kann. Erbt die Berechtigungen des Aufrufers. - -### Adapter - -Ein Framework-Paket, das ObjectStack mit einer Host-Laufzeitumgebung integriert — -Express, Fastify, Hono, Next.js, Nuxt, SvelteKit, NestJS. Die meisten -ObjectOS-Deployments benötigen keinen; ObjectOS bringt seinen eigenen HTTP- -Server mit. - -### App - -Ein Bündel aus Objekten + Views + Berechtigungen, das als eine einzige -navigierbare Anwendung in der Console dargestellt wird. Mehrere Apps können in einer -Laufzeitumgebung koexistieren (z. B. CRM + Helpdesk + Setup). - -### Better Auth - -Die Auth-Bibliothek, die `@objectstack/plugin-auth` antreibt. Du konfigurierst -Better Auth nicht direkt; das Plugin kapselt es. - -### Capability - -Ein optionales Laufzeit-Feature, das ein Artifact in seiner `requires`-Liste -deklariert. Wird einem Paket zugeordnet — z. B. `audit` → `@objectstack/plugin-audit`. -Bei Bedarf von ObjectOS geladen. Siehe -[Runtime Capabilities](/docs/reference/runtime-capabilities). - -### CEL - -[Common Expression Language](https://github.com/google/cel-spec) — -Googles sichere, isolierte Ausdruckssyntax. Wird in Formeln, -Validierungsregeln, Berechtigungsprädikaten, Sharing-Regeln und Flow- -Bedingungen verwendet. - -### Console - -Die System-UI unter `/_console/` — verwaltet Benutzer, Rollen, Permission Sets, -Audit-Log, Sessions, API-Schlüssel, Systemeinstellungen. Unterscheidet sich von der Console -(Business-UI). - -### Control Plane - -Ein optionaler Dienst, der versionierte Artifacts an ObjectOS-Instanzen -veröffentlicht. Wird als ObjectStack Cloud gehostet oder selbst betrieben. Die meisten -Deployments benötigen keine — der dateibasierte Modus funktioniert für die -produktive Bereitstellung einer einzelnen App. - -### Driver - -Eine Implementierung eines Daten-Backends: `driver-sql` (Postgres, MySQL, SQLite, -Turso/libSQL), `driver-mongodb`, `driver-memory`. Wird beim Start anhand -der Datenbank-URL ausgewählt. - -### Embedder - -Der Dienst, der Text für RAG / semantische Suche in Vektoren umwandelt. -Über verschiedene Anbieter hinweg austauschbar (OpenAI, Azure, 硅基流动, Ollama, …). -Siehe [AI Service](/docs/configure/ai). - -### Environment - -Eine mandantenspezifische Laufzeitinstanz, die von ihrer eigenen Datenbank und Identität -gestützt wird. In v4.x manchmal *Project* genannt (Alias beibehalten). v5.0 standardisiert auf -*Environment* in CLI, HTTP, Umgebungsvariablen und Schemas. - -### Field - -Eine typisierte Eigenschaft eines Objects. ~48 eingebaute Typen: `text`, `select`, -`lookup`, `markdown`, `file`, `formula`, `summary` usw. Siehe -[Data Model](/docs/build/data). - -### Flow - -Deklarative Geschäftslogik — automatisch gestartet (Datensatz-Trigger), geplant -(Cron) oder manuell (Schaltfläche / API). Wird als DAG mit -Bedingungs-/Schleifen-/Wiederholungs-/Parallel-Primitiven ausgeführt. Siehe -[Flows & Automation](/docs/build/automation/flows). - -### Formula field - -Ein berechnetes Feld, dessen Wert ein CEL-Ausdruck ist, der beim Lesen -ausgewertet wird. Nicht gespeichert. - -### Hook - -Eine Funktion, die in den Objektlebenszyklus eingefügt wird (`beforeInsert`, -`afterUpdate`, …). In TypeScript geschrieben. Anders als ein Flow: -Hooks sind erstklassiger Code; Flows sind Metadaten. - -### Kernel - -Der Mikrokernel innerhalb von ObjectOS, der Plugins lädt, den DI- -Container hält, Events verteilt und die Metadaten eines einzelnen Environments -bereitstellt. Ein Prozess kann viele zwischengespeicherte Kernels (einen pro -Environment) in einem LRU halten. - -### Manifest - -Die Metadaten auf oberster Ebene am Kopf eines Artifacts: `id`, `namespace`, -`version`, `type` (`app` / `plugin` / `service`), `name`, -`description`, `requires`-Liste. - -### Marketplace - -Der in der Console integrierte Katalog installierbarer Apps. Gestützt durch eine konfigurierbare -Paket-Registry. Siehe [Marketplace](/docs/build/marketplace). - -### MCP (Model Context Protocol) - -Ein offenes Protokoll, mit dem KI-Agenten Werkzeuge entdecken und aufrufen können. -ObjectOS kann seine Objekte + Actions über -`@objectstack/mcp` als MCP bereitstellen. - -### Object - -Eine typisierte Geschäftsentität — `task`, `account`, `invoice`. Wird als -TypeScript-Schema deklariert; erzeugt automatisch REST-APIs, Console-Views, Audit-Einträge, -RBAC-Prüfpunkte. Siehe [Data Model](/docs/build/data). - -### ObjectOS - -Die Laufzeitumgebung — ein einzelner Node.js-Prozess, der deine Apps bereitstellt. Open -Source, Apache-2.0. **Diese Dokumentationsseite ist für ObjectOS.** - -### ObjectQL - -Das Datenschicht-Protokoll und die Query-Engine. Kompiliert deklarative Abfragen -in native SQL-/Mongo-Abfragen. Wird von REST-Endpunkten, Console, -Flows verwendet — alles dieselbe Engine. - -### ObjectStack - -Das übergeordnete Projekt: das Framework (`@objectstack/*` npm-Pakete), -die Laufzeitumgebung (ObjectOS), der optionale Cloud-Dienst und der -marketplace. Manchmal auch „die Plattform“ genannt. - -### ObjectUI - -Das View-Schicht-Protokoll — Apps, Views, Seiten, Dashboards, Actions, -Diagramme, Navigation. Die Console rendert ObjectUI-Deklarationen. - -### Permission Set - -Ein Bündel aus Berechtigungen — Objektberechtigungen, Feldberechtigungen, Systemberechtigungen. -Wird Benutzern direkt oder über Rollen zugewiesen. Die primäre -Autorisierungseinheit. Siehe [Permissions](/docs/configure/permissions). - -### Plugin - -Ein Framework-Paket, das die Laufzeitumgebung um eine Capability erweitert — -`plugin-auth`, `plugin-security`, `plugin-audit`, `plugin-webhooks`, -`mcp` usw. Wird über DI + Lifecycle-Hooks aktiviert -(`init → start → destroy`). - -### Project - -Alter Name für **Environment**. Wird in v4.x noch in CLI/Umgebung verwendet (als Alias). -In v5.0 entfernt. - -### Record Share - -Eine direkte Zugriffsgewährung auf einen bestimmten Datensatz für einen bestimmten Benutzer / -eine bestimmte Rolle / Gruppe. Gespeichert als `sys_record_share`-Zeilen. Unterscheidet sich von -Sharing-Regeln (deklarative Kriterien). - -### Sharing Rule - -Eine deklarative Regel, die den Datensatzzugriff anhand von Kriterien gewährt -(„regionale Manager können Datensätze in ihrer Region sehen“). Wird zur -Abfragezeit ausgewertet und in Zeilenebene-Filter kompiliert. - -### Console - -Die Business-UI unter `/_console/` — Datensätze durchsuchen, erstellen, bearbeiten, -Views konfigurieren, Apps aus dem marketplace installieren. Unterscheidet sich von der Console (System-UI). - -### Surface - -Einer der vier HTTP-Einstiegspunkte, die ein laufendes ObjectOS bereitstellt: -`/` (REST API), `/_console/`, `/_account/`, `/_console/`. - -### System Context - -Der interne Ausführungsmodus, der von Plugins, Hooks und Seed-Skripten -verwendet wird, die Sicherheitsprüfungen umgehen müssen. Auditierbar; nicht für -Benutzercode zugänglich. - -### Tenant - -Eine logische Isolationsgrenze in Multi-Tenant-Deployments. Ein Tenant -entspricht typischerweise einem Environment. Cookies und Sessions sind pro -Hostname gescoped; Daten sind pro Environment gescoped. - -### Trigger - -Die Bedingung, die einen Flow auslöst — Datensatzereignis (`after_insert`), -Zeitplan (Cron) oder manueller Aufruf. - -### View - -Eine deklarative UI-Konfiguration — Liste, Formular, Kanban, Kalender, Gantt — -die an ein Object angehängt ist. Die Console rendert sie; du schreibst die -Komponente nicht. - -### Zod schema - -Das Laufzeit- und Compile-Zeit-Typsystem, das von `@objectstack/spec` verwendet wird. -Jedes Objekt, Feld, jede View, App und jeder Flow wird durch ein Zod- -Schema geparst und validiert. JSON Schema, TypeScript-Typen und REST-Request-Validatoren -werden alle aus denselben Zod-Definitionen abgeleitet. diff --git a/content/docs/resources/glossary.es.mdx b/content/docs/resources/glossary.es.mdx deleted file mode 100644 index 2751a7a..0000000 --- a/content/docs/resources/glossary.es.mdx +++ /dev/null @@ -1,235 +0,0 @@ ---- -title: Glosario -description: El vocabulario utilizado en ObjectOS y ObjectStack — una definición para cada término. -translation: - source_sha: b7904d8f61e8f9b0bea68a073206f0af8bd20228a7c8fe8da68e6cc3ac4550e6 - guide_rev: 1 - mode: auto ---- - -Una única definición canónica para cada término utilizado en esta documentación. - -### Artifact - -Un archivo `objectstack.json` compilado. Una descripción autónoma e -inmutable de una aplicación — manifiesto, objetos, vistas, apps, flujos, -permisos, traducciones. Producido por `os compile`. Lo que ObjectOS -realmente ejecuta. - -### Action - -Una operación con nombre declarada en los metadatos, invocable mediante REST -(`/api/v1/data//actions/`), botones de Console o pasos de -flujo. Hereda los permisos de quien la invoca. - -### Adapter - -Un paquete del framework que integra ObjectStack con un runtime anfitrión — -Express, Fastify, Hono, Next.js, Nuxt, SvelteKit, NestJS. La mayoría de los -despliegues de ObjectOS no necesitan uno; ObjectOS incluye su propio -servidor HTTP. - -### App - -Un conjunto de objetos + vistas + permisos presentado como una única -aplicación navegable en Console. Múltiples apps pueden coexistir en un mismo -runtime (p. ej. CRM + Helpdesk + Setup). - -### Better Auth - -La biblioteca de autenticación que impulsa `@objectstack/plugin-auth`. No -configuras Better Auth directamente; el plugin lo encapsula. - -### Capability - -Una funcionalidad opcional del runtime declarada por un artifact en su lista -`requires`. Se corresponde con un paquete — p. ej. `audit` → -`@objectstack/plugin-audit`. ObjectOS la carga bajo demanda. Consulta -[Runtime Capabilities](/docs/reference/runtime-capabilities). - -### CEL - -[Common Expression Language](https://github.com/google/cel-spec) — -la sintaxis de expresiones segura y aislada de Google. Se usa en fórmulas, -reglas de validación, predicados de permisos, reglas de compartición y -condiciones de flujo. - -### Console - -La interfaz del sistema en `/_console/` — gestiona usuarios, roles, conjuntos -de permisos, registro de auditoría, sesiones, claves de API y ajustes del -sistema. Distinta de Console (interfaz de negocio). - -### Control Plane - -Un servicio opcional que publica artifacts versionados en instancias de -ObjectOS. Alojado como ObjectStack Cloud o autohospedado. La mayoría de los -despliegues no necesitan uno — el modo basado en archivos funciona para -producción de una sola app. - -### Driver - -Una implementación de backend de datos: `driver-sql` (Postgres, MySQL, -SQLite, Turso/libSQL), `driver-mongodb`, `driver-memory`. Se elige al -arrancar mediante la URL de la base de datos. - -### Embedder - -El servicio que convierte texto en vectores para RAG / búsqueda semántica. -Conectable entre proveedores (OpenAI, Azure, 硅基流动, Ollama, …). -Consulta [AI Service](/docs/configure/ai). - -### Environment - -Una instancia de runtime por tenant respaldada por su propia base de datos e -identidad. En la v4.x a veces se le llamaba *Project* (se mantiene el alias). -La v5.0 estandariza *Environment* en CLI, HTTP, variables de entorno y -esquemas. - -### Field - -Una propiedad tipada en un Object. ~48 tipos integrados: `text`, `select`, -`lookup`, `markdown`, `file`, `formula`, `summary`, etc. Consulta -[Data Model](/docs/build/data). - -### Flow - -Lógica de negocio declarativa — autolanzada (disparador de registro), -programada (cron) o manual (botón / API). Se ejecuta como un DAG con -primitivas de condición/bucle/reintento/paralelismo. Consulta -[Flows & Automation](/docs/build/automation/flows). - -### Formula field - -Un campo calculado cuyo valor es una expresión CEL evaluada en el momento de -la lectura. No se almacena. - -### Hook - -Una función inyectada en el ciclo de vida del objeto (`beforeInsert`, -`afterUpdate`, …). Escrita en TypeScript. Diferente de un flujo: los hooks -son código de primera clase; los flujos son metadatos. - -### Kernel - -El microkernel dentro de ObjectOS que carga plugins, mantiene el contenedor -de DI, despacha eventos y sirve los metadatos de un único Environment. Un -proceso puede mantener muchos kernels en caché (uno por Environment) en una -LRU. - -### Manifest - -Los metadatos de nivel superior al inicio de un artifact: `id`, `namespace`, -`version`, `type` (`app` / `plugin` / `service`), `name`, -`description`, lista `requires`. - -### Marketplace - -El catálogo dentro de Console de apps instalables. Respaldado por un registro -de paquetes configurable. Consulta [Marketplace](/docs/build/marketplace). - -### MCP (Model Context Protocol) - -Un protocolo abierto para que los agentes de IA descubran e invoquen -herramientas. ObjectOS puede exponer sus objetos + acciones como MCP mediante -`@objectstack/mcp`. - -### Object - -Una entidad de negocio tipada — `task`, `account`, `invoice`. Declarada como -un esquema de TypeScript; genera APIs REST, vistas de Console, entradas de -auditoría y puntos de control de RBAC automáticamente. Consulta [Data Model](/docs/build/data). - -### ObjectOS - -El runtime — un único proceso de Node.js que sirve tus apps. De código -abierto, Apache-2.0. **Este sitio de documentación es para ObjectOS.** - -### ObjectQL - -El protocolo de la capa de datos y el motor de consultas. Compila consultas -declarativas a consultas nativas de SQL / Mongo. Usado por los endpoints -REST, Console y flujos — todos el mismo motor. - -### ObjectStack - -El proyecto paraguas: el framework (paquetes npm `@objectstack/*`), el -runtime (ObjectOS), el servicio en la nube opcional y el marketplace. A veces -llamado "la plataforma". - -### ObjectUI - -El protocolo de la capa de vistas — apps, vistas, páginas, paneles, acciones, -gráficos, navegación. Console renderiza las declaraciones de ObjectUI. - -### Permission Set - -Un conjunto de concesiones — permisos de objeto, permisos de campo, permisos -del sistema. Se asocia a los usuarios directamente o mediante roles. La -unidad principal de autorización. Consulta [Permissions](/docs/configure/permissions). - -### Plugin - -Un paquete del framework que extiende el runtime con una capability — -`plugin-auth`, `plugin-security`, `plugin-audit`, `plugin-webhooks`, -`mcp`, etc. Activado mediante DI + hooks de ciclo de vida -(`init → start → destroy`). - -### Project - -Antiguo nombre de **Environment**. Todavía se usa en la CLI/entorno de la -v4.x (con alias). Eliminado en la v5.0. - -### Record Share - -Una concesión directa de acceso a un registro específico para un usuario / -rol / grupo específico. Almacenada como filas `sys_record_share`. Diferente -de las reglas de compartición (criterios declarativos). - -### Sharing Rule - -Una regla declarativa que concede acceso a registros según criterios ("los -gerentes regionales pueden ver los registros de su región"). Evaluada en el -momento de la consulta, compilada en filtros a nivel de fila. - -### Console - -La interfaz de negocio en `/_console/` — explora, crea y edita registros, -configura vistas e instala apps desde el marketplace. Distinta de Console -(interfaz del sistema). - -### Surface - -Uno de los cuatro puntos de entrada HTTP que expone un ObjectOS en ejecución: -`/` (REST API), `/_console/`, `/_account/`, `/_console/`. - -### System Context - -El modo de ejecución interno usado por plugins, hooks y scripts de inicialización -que necesitan omitir las comprobaciones de seguridad. Auditable; no expuesto -al código de usuario. - -### Tenant - -Un límite de aislamiento lógico en despliegues multi-tenant. Un tenant -normalmente se corresponde con un Environment. Las cookies y sesiones tienen -alcance por nombre de host; los datos tienen alcance por Environment. - -### Trigger - -La condición que dispara un flujo — evento de registro (`after_insert`), -programación (cron) o invocación manual. - -### View - -Una configuración de UI declarativa — lista, formulario, kanban, calendario, -gantt — asociada a un Object. Console la renderiza; tú no escribes el -componente. - -### Zod schema - -El sistema de tipos en runtime + tiempo de compilación usado por -`@objectstack/spec`. Cada objeto, campo, vista, app y flujo es analizado y -validado por un esquema de Zod. JSON Schema, los tipos de TypeScript y los -validadores de peticiones REST se derivan todos de las mismas definiciones de -Zod. diff --git a/content/docs/resources/glossary.fr.mdx b/content/docs/resources/glossary.fr.mdx deleted file mode 100644 index 116885a..0000000 --- a/content/docs/resources/glossary.fr.mdx +++ /dev/null @@ -1,233 +0,0 @@ ---- -title: Glossaire -description: Le vocabulaire utilisé dans ObjectOS et ObjectStack — une définition pour chaque terme. -translation: - source_sha: b7904d8f61e8f9b0bea68a073206f0af8bd20228a7c8fe8da68e6cc3ac4550e6 - guide_rev: 1 - mode: auto ---- - -Une définition canonique unique pour chaque terme utilisé dans cette documentation. - -### Artifact - -Un fichier `objectstack.json` compilé. Description autonome et immuable -d'une application — manifeste, objets, vues, applications, flux, -permissions, traductions. Produit par `os compile`. C'est ce -qu'ObjectOS exécute réellement. - -### Action - -Une opération nommée déclarée dans les métadonnées, invocable via REST -(`/api/v1/data//actions/`), des boutons de Console ou des étapes -de flux. Hérite des permissions de l'appelant. - -### Adapter - -Un package du framework qui intègre ObjectStack à un runtime hôte — -Express, Fastify, Hono, Next.js, Nuxt, SvelteKit, NestJS. La plupart -des déploiements ObjectOS n'en ont pas besoin ; ObjectOS embarque son propre -serveur HTTP. - -### App - -Un ensemble d'objets + vues + permissions présenté comme une application -unique navigable dans Console. Plusieurs applications peuvent coexister dans un -même runtime (par exemple CRM + Helpdesk + Setup). - -### Better Auth - -La bibliothèque d'authentification qui alimente `@objectstack/plugin-auth`. Vous ne -configurez pas Better Auth directement ; le plugin l'encapsule. - -### Capability - -Une fonctionnalité runtime optionnelle déclarée par un artifact dans sa liste -`requires`. Correspond à un package — par exemple `audit` → `@objectstack/plugin-audit`. -Chargée à la demande par ObjectOS. Voir -[Runtime Capabilities](/docs/reference/runtime-capabilities). - -### CEL - -[Common Expression Language](https://github.com/google/cel-spec) — -la syntaxe d'expression sûre et sandboxée de Google. Utilisée dans les formules, -les règles de validation, les prédicats de permission, les règles de partage et les -conditions de flux. - -### Console - -L'interface système accessible à `/_console/` — gère les utilisateurs, les rôles, les ensembles de permissions, -le journal d'audit, les sessions, les clés API et les paramètres système. Distincte de Console -(interface métier). - -### Control Plane - -Un service optionnel qui publie des artifacts versionnés vers des instances -ObjectOS. Hébergé en tant qu'ObjectStack Cloud ou auto-hébergé. La plupart des -déploiements n'en ont pas besoin — le mode basé sur fichiers fonctionne pour une -production mono-application. - -### Driver - -Une implémentation de backend de données : `driver-sql` (Postgres, MySQL, SQLite, -Turso/libSQL), `driver-mongodb`, `driver-memory`. Choisi au démarrage via -l'URL de la base de données. - -### Embedder - -Le service qui convertit le texte en vecteurs pour le RAG / la recherche sémantique. -Interchangeable entre fournisseurs (OpenAI, Azure, 硅基流动, Ollama, …). -Voir [AI Service](/docs/configure/ai). - -### Environment - -Une instance runtime par tenant, adossée à sa propre base de données et identité. -Sur la v4.x, parfois appelée *Project* (alias conservé). La v5.0 standardise sur -*Environment* dans la CLI, le HTTP, les variables d'environnement et les schémas. - -### Field - -Une propriété typée sur un Object. ~48 types intégrés : `text`, `select`, -`lookup`, `markdown`, `file`, `formula`, `summary`, etc. Voir -[Data Model](/docs/build/data). - -### Flow - -Logique métier déclarative — déclenchée automatiquement (déclencheur d'enregistrement), planifiée -(cron) ou manuelle (bouton / API). S'exécute sous forme de DAG avec des -primitives condition/boucle/réessai/parallèle. Voir -[Flows & Automation](/docs/build/automation/flows). - -### Formula field - -Un champ calculé dont la valeur est une expression CEL évaluée au moment de -la lecture. Non stockée. - -### Hook - -Une fonction injectée dans le cycle de vie de l'objet (`beforeInsert`, -`afterUpdate`, …). Écrite en TypeScript. Différent d'un flux : -les hooks sont du code de première classe ; les flux sont des métadonnées. - -### Kernel - -Le micronoyau au cœur d'ObjectOS qui charge les plugins, contient le conteneur -DI, distribue les événements et sert les métadonnées d'un unique Environment. -Un processus peut contenir de nombreux kernels en cache (un par -Environment) dans un LRU. - -### Manifest - -Les métadonnées de plus haut niveau en tête d'un artifact : `id`, `namespace`, -`version`, `type` (`app` / `plugin` / `service`), `name`, -`description`, liste `requires`. - -### Marketplace - -Le catalogue dans Console des applications installables. Adossé à un registre de -packages configurable. Voir [Marketplace](/docs/build/marketplace). - -### MCP (Model Context Protocol) - -Un protocole ouvert permettant aux agents IA de découvrir et d'appeler des outils. -ObjectOS peut exposer ses objets + actions en tant que MCP via -`@objectstack/mcp`. - -### Object - -Une entité métier typée — `task`, `account`, `invoice`. Déclarée sous forme de -schéma TypeScript ; génère automatiquement les API REST, les vues de Console, les entrées -d'audit et les points de contrôle RBAC. Voir [Data Model](/docs/build/data). - -### ObjectOS - -Le runtime — un processus Node.js unique qui sert vos applications. Open -source, Apache-2.0. **Ce site de documentation est dédié à ObjectOS.** - -### ObjectQL - -Le protocole de la couche de données et le moteur de requêtes. Compile les requêtes -déclaratives en requêtes SQL / Mongo natives. Utilisé par les endpoints REST, Console, -les flux — tous le même moteur. - -### ObjectStack - -Le projet parapluie : le framework (packages npm `@objectstack/*`), -le runtime (ObjectOS), le service cloud optionnel et le -marketplace. Parfois appelé « la plateforme ». - -### ObjectUI - -Le protocole de la couche de présentation — applications, vues, pages, tableaux de bord, actions, -graphiques, navigation. Console rend les déclarations ObjectUI. - -### Permission Set - -Un ensemble d'attributions — permissions d'objet, permissions de champ, permissions -système. Rattaché directement aux utilisateurs ou via des rôles. L'unité d'autorisation -principale. Voir [Permissions](/docs/configure/permissions). - -### Plugin - -Un package du framework qui étend le runtime avec une capability — -`plugin-auth`, `plugin-security`, `plugin-audit`, `plugin-webhooks`, -`mcp`, etc. Activé via DI + hooks de cycle de vie -(`init → start → destroy`). - -### Project - -Ancien nom d'**Environment**. Toujours utilisé dans la CLI/env de la v4.x (alias). -Supprimé en v5.0. - -### Record Share - -Une attribution directe d'accès à un enregistrement spécifique pour un utilisateur / -rôle / groupe spécifique. Stockée sous forme de lignes `sys_record_share`. Différente des -règles de partage (critères déclaratifs). - -### Sharing Rule - -Une règle déclarative qui accorde l'accès aux enregistrements selon des critères -(« les responsables régionaux peuvent voir les enregistrements de leur région »). Évaluée au -moment de la requête, compilée en filtres au niveau des lignes. - -### Console - -L'interface métier accessible à `/_console/` — parcourir, créer, modifier des enregistrements, -configurer des vues, installer des applications depuis le marketplace. Distincte de Console -(interface système). - -### Surface - -L'un des quatre points d'entrée HTTP qu'expose un ObjectOS en cours d'exécution : -`/` (API REST), `/_console/`, `/_account/`, `/_console/`. - -### System Context - -Le mode d'exécution interne utilisé par les plugins, les hooks et les scripts de seed -qui doivent contourner les contrôles de sécurité. Auditable ; non exposé au code -utilisateur. - -### Tenant - -Une frontière d'isolation logique dans les déploiements multi-tenant. Un tenant -correspond généralement à un Environment. Les cookies et les sessions sont délimités par -nom d'hôte ; les données sont délimitées par Environment. - -### Trigger - -La condition qui déclenche un flux — événement d'enregistrement (`after_insert`), -planification (cron) ou invocation manuelle. - -### View - -Une configuration d'interface déclarative — liste, formulaire, kanban, calendrier, gantt — -rattachée à un Object. Console la rend ; vous n'écrivez pas le -composant. - -### Zod schema - -Le système de types runtime + compile-time utilisé par `@objectstack/spec`. -Chaque objet, champ, vue, application et flux est analysé et validé par un schéma -Zod. Les schémas JSON, les types TypeScript et les validateurs de requêtes REST sont -tous dérivés des mêmes définitions Zod. diff --git a/content/docs/resources/glossary.ja.mdx b/content/docs/resources/glossary.ja.mdx deleted file mode 100644 index 1b8a128..0000000 --- a/content/docs/resources/glossary.ja.mdx +++ /dev/null @@ -1,158 +0,0 @@ ---- -title: 用語集 -description: ObjectOS と ObjectStack 全体で使われる用語 — 各用語につき定義は1つ。 -translation: - source_sha: b7904d8f61e8f9b0bea68a073206f0af8bd20228a7c8fe8da68e6cc3ac4550e6 - guide_rev: 1 - mode: auto ---- - -このドキュメントで使われる各用語について、唯一の正式な定義を示します。 - -### Artifact - -コンパイル済みの `objectstack.json` ファイル。アプリの自己完結型かつ不変な記述で、マニフェスト、オブジェクト、ビュー、アプリ、フロー、権限、翻訳を含みます。`os compile` によって生成されます。ObjectOS が実際に実行する対象です。 - -### Action - -メタデータで宣言される名前付き操作で、REST（`/api/v1/data//actions/`）、Console のボタン、またはフローのステップから呼び出せます。呼び出し元の権限を継承します。 - -### Adapter - -ObjectStack をホストランタイムと統合するフレームワークパッケージ — Express、Fastify、Hono、Next.js、Nuxt、SvelteKit、NestJS。ほとんどの ObjectOS デプロイメントでは不要です。ObjectOS は独自の HTTP サーバーを内蔵しています。 - -### App - -オブジェクト + ビュー + 権限をまとめたもので、Console 上で単一のナビゲート可能なアプリケーションとして提供されます。複数のアプリを1つのランタイムに共存させることができます（例: CRM + Helpdesk + Setup）。 - -### Better Auth - -`@objectstack/plugin-auth` を支える認証ライブラリ。Better Auth を直接設定することはありません。プラグインがそれをラップします。 - -### Capability - -Artifact が `requires` リスト内で宣言する、オプションのランタイム機能。パッケージにマッピングされます — 例: `audit` → `@objectstack/plugin-audit`。ObjectOS によってオンデマンドで読み込まれます。[Runtime Capabilities](/docs/reference/runtime-capabilities) を参照してください。 - -### CEL - -[Common Expression Language](https://github.com/google/cel-spec) — Google による安全でサンドボックス化された式構文。数式、検証ルール、権限述語、共有ルール、フロー条件で使われます。 - -### Console - -`/_console/` にあるシステム UI — ユーザー、ロール、権限セット、監査ログ、セッション、API キー、システム設定を管理します。Console（ビジネス UI）とは区別されます。 - -### Control Plane - -バージョン管理された Artifact を ObjectOS インスタンスに公開するオプションのサービス。ObjectStack Cloud としてホストするか、セルフホストします。ほとんどのデプロイメントでは不要です — ファイルベースモードは単一アプリの本番環境で機能します。 - -### Driver - -データバックエンドの実装: `driver-sql`（Postgres、MySQL、SQLite、Turso/libSQL）、`driver-mongodb`、`driver-memory`。データベース URL を介して起動時に選択されます。 - -### Embedder - -RAG / セマンティック検索のためにテキストをベクトルに変換するサービス。プロバイダー間で差し替え可能です（OpenAI、Azure、硅基流动、Ollama、…）。[AI Service](/docs/configure/ai) を参照してください。 - -### Environment - -独自のデータベースとアイデンティティに裏付けられた、テナントごとのランタイムインスタンス。v4.x では *Project* と呼ばれることがあります（エイリアスは維持）。v5.0 では CLI、HTTP、環境変数、スキーマ全体で *Environment* に標準化されています。 - -### Field - -Object 上の型付きプロパティ。約48種類の組み込み型: `text`、`select`、`lookup`、`markdown`、`file`、`formula`、`summary` など。[Data Model](/docs/build/data) を参照してください。 - -### Flow - -宣言的なビジネスロジック — 自動起動（レコードトリガー）、スケジュール（cron）、または手動（ボタン / API）。condition/loop/retry/parallel プリミティブを備えた DAG として実行されます。[Flows & Automation](/docs/build/automation/flows) を参照してください。 - -### Formula field - -値が CEL 式で、読み取り時に評価される計算フィールド。保存されません。 - -### Hook - -オブジェクトのライフサイクル（`beforeInsert`、`afterUpdate`、…）に注入される関数。TypeScript で記述されます。フローとは異なります: フックはファーストクラスのコードで、フローはメタデータです。 - -### Kernel - -ObjectOS 内部のマイクロカーネルで、プラグインを読み込み、DI コンテナを保持し、イベントをディスパッチし、単一の Environment のメタデータを提供します。1つのプロセスは多数のキャッシュされたカーネル（Environment ごとに1つ）を LRU で保持できます。 - -### Manifest - -Artifact の先頭にあるトップレベルのメタデータ: `id`、`namespace`、`version`、`type`（`app` / `plugin` / `service`）、`name`、`description`、`requires` リスト。 - -### Marketplace - -インストール可能なアプリの Console 内カタログ。設定可能なパッケージレジストリに裏付けられています。[Marketplace](/docs/build/marketplace) を参照してください。 - -### MCP (Model Context Protocol) - -AI エージェントがツールを検出して呼び出すためのオープンプロトコル。ObjectOS は `@objectstack/mcp` を介して、オブジェクト + アクションを MCP として公開できます。 - -### Object - -型付きのビジネスエンティティ — `task`、`account`、`invoice`。TypeScript スキーマとして宣言され、REST API、Console ビュー、監査エントリ、RBAC チェックポイントを自動的に生成します。[Data Model](/docs/build/data) を参照してください。 - -### ObjectOS - -ランタイム — アプリを提供する単一の Node.js プロセス。オープンソース、Apache-2.0。**このドキュメントサイトは ObjectOS 向けです。** - -### ObjectQL - -データレイヤープロトコルおよびクエリエンジン。宣言的クエリをネイティブの SQL / Mongo クエリにコンパイルします。REST エンドポイント、Console、フローで使われます — すべて同じエンジンです。 - -### ObjectStack - -全体を包括するプロジェクト: フレームワーク（`@objectstack/*` npm パッケージ）、ランタイム（ObjectOS）、オプションのクラウドサービス、そして marketplace。「プラットフォーム」と呼ばれることもあります。 - -### ObjectUI - -ビューレイヤープロトコル — アプリ、ビュー、ページ、ダッシュボード、アクション、チャート、ナビゲーション。Console は ObjectUI 宣言をレンダリングします。 - -### Permission Set - -付与のまとまり — オブジェクト権限、フィールド権限、システム権限。ユーザーに直接、またはロールを介してアタッチされます。主要な認可単位です。[Permissions](/docs/configure/permissions) を参照してください。 - -### Plugin - -ランタイムをある機能で拡張するフレームワークパッケージ — `plugin-auth`、`plugin-security`、`plugin-audit`、`plugin-webhooks`、`mcp` など。DI + ライフサイクルフック（`init → start → destroy`）を介して有効化されます。 - -### Project - -**Environment** の旧名称。v4.x の CLI/環境変数では今も使われています（エイリアス）。v5.0 で削除されました。 - -### Record Share - -特定のユーザー / ロール / グループに対して、特定のレコードへのアクセスを直接付与するもの。`sys_record_share` の行として保存されます。共有ルール（宣言的な条件）とは異なります。 - -### Sharing Rule - -条件に基づいてレコードアクセスを付与する宣言的なルール（「地域マネージャーは自分の地域のレコードを参照できる」）。クエリ時に評価され、行レベルのフィルターにコンパイルされます。 - -### Console - -`/_console/` にあるビジネス UI — レコードの参照、作成、編集、ビューの設定、marketplace からのアプリのインストール。Console（システム UI）とは区別されます。 - -### Surface - -実行中の ObjectOS が公開する4つの HTTP エントリポイントの1つ: `/`（REST API）、`/_console/`、`/_account/`、`/_console/`。 - -### System Context - -セキュリティチェックをバイパスする必要があるプラグイン、フック、シードスクリプトが使う内部実行モード。監査可能で、ユーザーコードには公開されません。 - -### Tenant - -マルチテナントデプロイメントにおける論理的な分離境界。1つのテナントは通常1つの Environment にマッピングされます。Cookie とセッションはホスト名ごとにスコープされ、データは Environment ごとにスコープされます。 - -### Trigger - -フローを起動する条件 — レコードイベント（`after_insert`）、スケジュール（cron）、または手動呼び出し。 - -### View - -Object にアタッチされる宣言的な UI 設定 — リスト、フォーム、カンバン、カレンダー、ガント。Console がレンダリングし、コンポーネントを記述する必要はありません。 - -### Zod schema - -`@objectstack/spec` が使うランタイム + コンパイル時の型システム。すべてのオブジェクト、フィールド、ビュー、アプリ、フローは Zod スキーマによってパースおよび検証されます。JSON Schema、TypeScript 型、REST リクエストバリデーターはすべて同じ Zod 定義から派生します。 diff --git a/content/docs/resources/glossary.ko.mdx b/content/docs/resources/glossary.ko.mdx deleted file mode 100644 index df6fdc8..0000000 --- a/content/docs/resources/glossary.ko.mdx +++ /dev/null @@ -1,230 +0,0 @@ ---- -title: 용어집 -description: ObjectOS와 ObjectStack 전반에서 사용되는 용어 — 각 용어마다 하나의 정의. -translation: - source_sha: b7904d8f61e8f9b0bea68a073206f0af8bd20228a7c8fe8da68e6cc3ac4550e6 - guide_rev: 1 - mode: auto ---- - -이 문서에서 사용되는 각 용어에 대한 단일 표준 정의입니다. - -### Artifact - -컴파일된 `objectstack.json` 파일. 앱에 대한 자체 완결형이며 변경 불가능한 -설명 — 매니페스트, 객체, 뷰, 앱, 플로우, -권한, 번역. `os compile`로 생성됩니다. ObjectOS가 -실제로 실행하는 대상입니다. - -### Action - -메타데이터에 선언된 이름 있는 작업으로, REST -(`/api/v1/data//actions/`), Console 버튼, 또는 플로우 -단계를 통해 호출할 수 있습니다. 호출자의 권한을 상속합니다. - -### Adapter - -ObjectStack를 호스트 런타임과 통합하는 프레임워크 패키지 — -Express, Fastify, Hono, Next.js, Nuxt, SvelteKit, NestJS. 대부분의 -ObjectOS 배포에는 어댑터가 필요하지 않습니다. ObjectOS는 자체 HTTP -서버를 번들로 제공합니다. - -### App - -Console에서 하나의 탐색 가능한 애플리케이션으로 표현되는 객체 + 뷰 + 권한의 -묶음입니다. 하나의 런타임에 여러 앱이 공존할 수 있습니다 -(예: CRM + Helpdesk + Setup). - -### Better Auth - -`@objectstack/plugin-auth`를 구동하는 인증 라이브러리입니다. Better Auth를 -직접 구성하지 않으며, 플러그인이 이를 감쌉니다. - -### Capability - -아티팩트가 자신의 `requires` 목록에 선언하는 선택적 런타임 기능입니다. -패키지에 매핑됩니다 — 예: `audit` → `@objectstack/plugin-audit`. -ObjectOS가 필요에 따라 로드합니다. 다음을 참조하세요: -[Runtime Capabilities](/docs/reference/runtime-capabilities). - -### CEL - -[Common Expression Language](https://github.com/google/cel-spec) — -Google의 안전하고 샌드박스화된 표현식 구문입니다. 수식, -유효성 검사 규칙, 권한 술어, 공유 규칙, 플로우 조건에서 사용됩니다. - -### Console - -`/_console/`의 시스템 UI — 사용자, 역할, 권한 집합, -감사 로그, 세션, API 키, 시스템 설정을 관리합니다. Console -(비즈니스 UI)와 구별됩니다. - -### Control Plane - -버전 관리된 아티팩트를 ObjectOS 인스턴스에 게시하는 선택적 서비스입니다. -ObjectStack Cloud로 호스팅되거나 자체 호스팅됩니다. 대부분의 -배포에는 필요하지 않으며, 파일 기반 모드로 단일 앱 -프로덕션을 운영할 수 있습니다. - -### Driver - -데이터 백엔드 구현체입니다: `driver-sql` (Postgres, MySQL, SQLite, -Turso/libSQL), `driver-mongodb`, `driver-memory`. 부팅 시 데이터베이스 -URL을 통해 선택됩니다. - -### Embedder - -RAG / 시맨틱 검색을 위해 텍스트를 벡터로 변환하는 서비스입니다. -여러 공급자에 걸쳐 교체 가능합니다 (OpenAI, Azure, 硅基流动, Ollama, …). -다음을 참조하세요: [AI Service](/docs/configure/ai). - -### Environment - -자체 데이터베이스와 ID로 뒷받침되는 테넌트별 런타임 인스턴스입니다. -v4.x에서는 때때로 *Project*라고 불렸습니다 (별칭 유지). v5.0은 -CLI, HTTP, 환경 변수, 스키마 전반에서 *Environment*로 표준화합니다. - -### Field - -Object의 형식 지정 속성입니다. 약 48개의 기본 제공 타입: `text`, `select`, -`lookup`, `markdown`, `file`, `formula`, `summary` 등. 다음을 참조하세요: -[Data Model](/docs/build/data). - -### Flow - -선언적 비즈니스 로직 — 자동 실행(레코드 트리거), 예약 실행 -(cron), 또는 수동 실행(버튼 / API). 조건/루프/재시도/병렬 -프리미티브를 갖춘 DAG로 실행됩니다. 다음을 참조하세요: -[Flows & Automation](/docs/build/automation/flows). - -### Formula field - -값이 읽기 시점에 평가되는 CEL 표현식인 계산 필드입니다. -저장되지 않습니다. - -### Hook - -객체 수명 주기(`beforeInsert`, `afterUpdate`, …)에 삽입되는 -함수입니다. TypeScript로 작성됩니다. 플로우와는 다릅니다: -훅은 일급 코드이고, 플로우는 메타데이터입니다. - -### Kernel - -플러그인을 로드하고, DI 컨테이너를 보유하며, 이벤트를 디스패치하고, -단일 Environment의 메타데이터를 제공하는 ObjectOS 내부의 마이크로커널입니다. -하나의 프로세스는 LRU 방식으로 여러 캐시된 커널(Environment당 하나)을 -보유할 수 있습니다. - -### Manifest - -아티팩트의 맨 앞에 있는 최상위 메타데이터입니다: `id`, `namespace`, -`version`, `type` (`app` / `plugin` / `service`), `name`, -`description`, `requires` 목록. - -### Marketplace - -설치 가능한 앱의 Console 내 카탈로그입니다. 구성 가능한 -패키지 레지스트리로 뒷받침됩니다. 다음을 참조하세요: [Marketplace](/docs/build/marketplace). - -### MCP (Model Context Protocol) - -AI 에이전트가 도구를 검색하고 호출하기 위한 개방형 프로토콜입니다. -ObjectOS는 `@objectstack/mcp`를 통해 자신의 객체 + 액션을 -MCP로 노출할 수 있습니다. - -### Object - -형식 지정된 비즈니스 엔터티입니다 — `task`, `account`, `invoice`. -TypeScript 스키마로 선언되며, REST API, Console 뷰, 감사 항목, -RBAC 체크포인트를 자동으로 생성합니다. 다음을 참조하세요: [Data Model](/docs/build/data). - -### ObjectOS - -런타임 — 앱을 제공하는 단일 Node.js 프로세스입니다. 오픈 -소스, Apache-2.0. **이 문서 사이트는 ObjectOS를 위한 것입니다.** - -### ObjectQL - -데이터 계층 프로토콜 및 쿼리 엔진입니다. 선언적 쿼리를 -네이티브 SQL / Mongo 쿼리로 컴파일합니다. REST 엔드포인트, Console, -플로우에서 사용되며 — 모두 동일한 엔진입니다. - -### ObjectStack - -상위 프로젝트입니다: 프레임워크(`@objectstack/*` npm 패키지), -런타임(ObjectOS), 선택적 클라우드 서비스, 그리고 -marketplace. 때때로 "플랫폼"이라고 불립니다. - -### ObjectUI - -뷰 계층 프로토콜입니다 — 앱, 뷰, 페이지, 대시보드, 액션, -차트, 내비게이션. Console은 ObjectUI 선언을 렌더링합니다. - -### Permission Set - -권한 부여의 묶음입니다 — 객체 권한, 필드 권한, 시스템 -권한. 사용자에게 직접 또는 역할을 통해 연결됩니다. 기본 -권한 부여 단위입니다. 다음을 참조하세요: [Permissions](/docs/configure/permissions). - -### Plugin - -런타임을 하나의 기능으로 확장하는 프레임워크 패키지입니다 — -`plugin-auth`, `plugin-security`, `plugin-audit`, `plugin-webhooks`, -`mcp` 등. DI + 수명 주기 훅 -(`init → start → destroy`)을 통해 활성화됩니다. - -### Project - -**Environment**의 이전 이름입니다. v4.x CLI/환경에서 여전히 사용됩니다(별칭 처리). -v5.0에서 제거되었습니다. - -### Record Share - -특정 사용자 / 역할 / 그룹에 대해 특정 레코드에 대한 접근 권한을 -직접 부여하는 것입니다. `sys_record_share` 행으로 저장됩니다. 공유 -규칙(선언적 기준)과는 다릅니다. - -### Sharing Rule - -기준에 따라 레코드 접근 권한을 부여하는 선언적 규칙입니다 -("지역 관리자는 자신의 지역에 있는 레코드를 볼 수 있다"). 쿼리 -시점에 평가되어 행 수준 필터로 컴파일됩니다. - -### Console - -`/_console/`의 비즈니스 UI — 레코드를 탐색, 생성, 편집하고, -뷰를 구성하며, marketplace에서 앱을 설치합니다. Console(시스템 UI)과 -구별됩니다. - -### Surface - -실행 중인 ObjectOS가 노출하는 네 가지 HTTP 진입점 중 하나입니다: -`/` (REST API), `/_console/`, `/_account/`, `/_console/`. - -### System Context - -보안 검사를 우회해야 하는 플러그인, 훅, 시드 스크립트가 사용하는 -내부 실행 모드입니다. 감사 가능하며, 사용자 코드에는 노출되지 않습니다. - -### Tenant - -멀티테넌트 배포에서의 논리적 격리 경계입니다. 하나의 테넌트는 -일반적으로 하나의 Environment에 매핑됩니다. 쿠키와 세션은 호스트명별로 -범위가 지정되고, 데이터는 Environment별로 범위가 지정됩니다. - -### Trigger - -플로우를 실행하는 조건입니다 — 레코드 이벤트(`after_insert`), -예약(cron), 또는 수동 호출. - -### View - -Object에 연결된 선언적 UI 구성입니다 — 목록, 폼, 칸반, 캘린더, 간트. -Console이 이를 렌더링하며, 컴포넌트를 직접 작성하지 않습니다. - -### Zod schema - -`@objectstack/spec`이 사용하는 런타임 + 컴파일 타임 타입 시스템입니다. -모든 객체, 필드, 뷰, 앱, 플로우는 Zod 스키마로 파싱되고 검증됩니다. -JSON Schema, TypeScript 타입, REST 요청 검증기는 모두 -동일한 Zod 정의에서 파생됩니다. diff --git a/content/docs/resources/glossary.mdx b/content/docs/resources/glossary.mdx index 7cd37e5..b4f612e 100644 --- a/content/docs/resources/glossary.mdx +++ b/content/docs/resources/glossary.mdx @@ -36,6 +36,19 @@ runtime (e.g. CRM + Helpdesk + Setup). The auth library powering `@objectstack/plugin-auth`. You don't configure Better Auth directly; the plugin wraps it. +### Business ontology + +Your app's definition — objects and fields, relations, actions, +permissions, flows, and agent and tool definitions — as one executable, +versioned whole: authored as typed ObjectStack metadata, validated rather +than reasoned over, and run by the runtime, which derives the database, +REST API, UI and MCP tools from it. Views, dashboards, apps and +translations are projections of it, not part of it. It is yours on either +ObjectOS edition: export it and run it on the open-source ObjectStack +runtime. The full account is +[Business Ontology](https://objectstack.ai/docs/concepts/ontology) in the +ObjectStack docs. + ### Capability An optional runtime feature declared by an artifact in its `requires` @@ -72,7 +85,7 @@ See [AI Service](/docs/configure/ai). ### Environment A deployment's own identity — the id it reports as `OS_ENVIRONMENT_ID`, -persisted once a cloud binding completes. A self-hosted ObjectOS is a +persisted once a cloud binding completes. A self-managed ObjectOS is a **single-environment** runtime: one process, one environment, one app. Holding many environments, and publishing an artifact for each, is what a control plane does. See @@ -135,8 +148,12 @@ RBAC checkpoints automatically. See [Data Model](/docs/build/data). ### ObjectOS -The runtime — a single Node.js process that serves your apps. Open -source, Apache-2.0. **This documentation site is for ObjectOS.** +The commercial runtime environment built on ObjectStack: hosted in the +browser with nothing to install (**ObjectOS Cloud**) or self-managed on +your own infrastructure (**ObjectOS Enterprise**), licensed per AI seat. +Not open source — the stack it runs is, and on either edition you can +export your ontology and run it on that open runtime. **This +documentation site is for ObjectOS.** ### ObjectQL @@ -146,9 +163,11 @@ flows — all the same engine. ### ObjectStack -The umbrella project: the framework (`@objectstack/*` npm packages), -the runtime (ObjectOS), the optional cloud service, and the -marketplace. Sometimes called "the platform." +The open stack, Apache-2.0: the protocol, microkernel, SDK, CLI and +production runtime that execute a business ontology — the `@objectstack/*` +npm packages and the runtime image. ObjectOS is the commercial runtime +environment built on it; the two are different products under different +licences. ### ObjectUI diff --git a/content/docs/resources/glossary.zh-Hans.mdx b/content/docs/resources/glossary.zh-Hans.mdx deleted file mode 100644 index a3f306f..0000000 --- a/content/docs/resources/glossary.zh-Hans.mdx +++ /dev/null @@ -1,211 +0,0 @@ ---- -title: 术语表 -description: ObjectOS 与 ObjectStack 通用词汇 —— 每个一条定义。 -translation: - source_sha: b7904d8f61e8f9b0bea68a073206f0af8bd20228a7c8fe8da68e6cc3ac4550e6 - guide_rev: 1 - mode: auto ---- - -本文档使用的每个术语都给出一个权威定义。 - -### Artifact（产物） - -编译后的 `objectstack.json` 文件。对一个应用的自包含、不可变描述 —— -manifest、对象、视图、应用、流程、权限、翻译。由 `os compile` 产生。 -ObjectOS 实际执行的就是它。 - -### Action - -在元数据中声明的命名操作，可通过 REST -（`/api/v1/data//actions/`）、Console 按钮或流程 -步骤调用。继承调用者的权限。 - -### Adapter - -把 ObjectStack 集成到宿主运行时的框架包 —— Express、Fastify、Hono、 -Next.js、Nuxt、SvelteKit、NestJS。大多数 ObjectOS 部署不需要 adapter; -ObjectOS 自带 HTTP 服务器。 - -### App - -把对象 + 视图 + 权限打包成一个在 Console 中可导航的应用。同一个 -运行时中可以共存多个 App（如 CRM + Helpdesk + Setup）。 - -### Better Auth - -为 `@objectstack/plugin-auth` 提供动力的认证库。你不直接配置 -Better Auth;插件会做封装。 - -### Capability（能力） - -产物在其 `requires` 列表中声明的可选运行时特性。对应一个包 —— 例如 -`audit` → `@objectstack/plugin-audit`。由 ObjectOS 按需加载。见 -[运行时能力](/docs/reference/runtime-capabilities)。 - -### CEL - -[Common Expression Language](https://github.com/google/cel-spec) —— -Google 的安全沙箱表达式语法。用于公式、校验规则、权限谓词、共享 -规则与流程条件。 - -### Console - -位于 `/_console/` 的系统 UI —— 管理用户、角色、权限集、审计日志、 -会话、API key、系统设置。与 Console（业务 UI）有区别。 - -### Control Plane（控制面） - -可选服务，将版本化的产物分发给 ObjectOS 实例。可用 ObjectStack -Cloud 托管或自行部署。大多数部署不需要它 —— 单应用生产场景下， -文件挂载模式即可。 - -### Driver（驱动） - -数据后端实现：`driver-sql`（Postgres、MySQL、SQLite、Turso/libSQL）、 -`driver-mongodb`、`driver-memory`。启动时按数据库 URL 选择。 - -### Embedder - -把文本转成向量供 RAG / 语义检索使用的服务。跨 provider 可插拔 -（OpenAI、Azure、硅基流动、Ollama……）。见 -[AI 服务](/docs/configure/ai)。 - -### Environment - -按租户隔离的运行时实例，背后有各自的数据库与身份。在 v4.x 中 -有时仍称 *Project*（保留别名）。v5.0 在 CLI、HTTP、环境变量、 -schema 中统一为 *Environment*。 - -### Field（字段） - -对象上的有类型属性。约 48 种内置类型：`text`、`select`、`lookup`、 -`markdown`、`file`、`formula`、`summary` 等。见 -[数据模型](/docs/build/data)。 - -### Flow（流程） - -声明式业务逻辑 —— 自动触发（记录触发器）、定时（cron）或手动 -（按钮 / API）。以 DAG 执行，支持 condition/loop/retry/parallel -等原语。见 [流程与自动化](/docs/build/automation/flows)。 - -### Formula field（公式字段） - -值为 CEL 表达式、读取时计算的字段，不存储。 - -### Hook - -注入到对象生命周期的函数（`beforeInsert`、`afterUpdate`……）。 -用 TypeScript 编写。与流程不同：Hook 是一等代码，流程是元数据。 - -### Kernel（内核） - -ObjectOS 内部的微内核，负责加载插件、持有 DI 容器、分发事件， -并为单个 Environment 提供元数据服务。一个进程可在 LRU 中缓存 -多个内核（每个 Environment 一个）。 - -### Manifest - -产物头部的顶层元数据：`id`、`namespace`、`version`、`type` -（`app` / `plugin` / `service`）、`name`、`description`、 -`requires` 列表。 - -### Marketplace（应用市场） - -Console 内可安装应用的目录。背后由可配置的包注册中心支持。见 -[应用市场](/docs/build/marketplace)。 - -### MCP（Model Context Protocol） - -一个开放协议，让 AI 智能体发现并调用工具。ObjectOS 可以通过 -`@objectstack/mcp` 把对象 + action 暴露为 MCP。 - -### Object（对象） - -有类型的业务实体 —— `task`、`account`、`invoice`。以 TypeScript -schema 声明;自动生成 REST API、Console 视图、审计条目与 RBAC 检查 -点。见 [数据模型](/docs/build/data)。 - -### ObjectOS - -运行时 —— 一个对外服务你应用的 Node.js 进程。开源，Apache-2.0。 -**本文档站点就是 ObjectOS 的文档。** - -### ObjectQL - -数据层协议与查询引擎。把声明式查询编译成原生 SQL / Mongo 查询。 -REST 端点、Console、流程都用同一套引擎。 - -### ObjectStack - -总称项目：框架（`@objectstack/*` npm 包）、运行时（ObjectOS）、 -可选云服务，以及应用市场。有时也称 "平台"。 - -### ObjectUI - -视图层协议 —— App、View、Page、Dashboard、Action、Chart、导航。 -Console 渲染 ObjectUI 声明。 - -### Permission Set（权限集） - -一组授权的捆绑 —— 对象权限、字段权限、系统权限。可直接挂到用户 -上，也可经由角色挂载。授权的主单元。见 -[权限](/docs/configure/permissions)。 - -### Plugin（插件） - -为运行时扩展能力的框架包 —— `plugin-auth`、`plugin-security`、 -`plugin-audit`、`plugin-webhooks`、`mcp` 等。通过 -DI + 生命周期 Hook（`init → start → destroy`）激活。 - -### Project - -**Environment** 的旧名。在 v4.x 的 CLI/环境变量中仍可用（已别名化）。 -v5.0 中移除。 - -### Record Share（记录共享） - -把对某条记录的访问直接授予某个用户 / 角色 / 用户组。以 -`sys_record_share` 行存储。与共享规则（声明式条件）不同。 - -### Sharing Rule（共享规则） - -基于条件授予记录访问的声明式规则（"区域经理可以看到本区域的 -记录"）。查询时求值，编译为行级过滤条件。 - -### Console - -位于 `/_console/` 的业务 UI —— 浏览、创建、编辑记录，配置视图， -从应用市场安装应用。与 Console（系统 UI）有区别。 - -### Surface（表面） - -运行中的 ObjectOS 暴露的四类 HTTP 入口之一：`/`（REST API）、 -`/_console/`、`/_account/`、`/_console/`。 - -### System Context（系统上下文） - -供插件、Hook 与种子脚本绕过安全检查所用的内部执行模式。可审计; -不暴露给用户代码。 - -### Tenant（租户） - -多租户部署中的逻辑隔离边界。一个租户通常映射为一个 Environment。 -Cookie 与会话按主机名作用域;数据按 Environment 作用域。 - -### Trigger（触发器） - -触发流程的条件 —— 记录事件（`after_insert`）、调度（cron）或手动 -调用。 - -### View（视图） - -绑定到对象上的声明式 UI 配置 —— list、form、kanban、calendar、 -gantt。由 Console 渲染，你不需要写组件。 - -### Zod schema - -`@objectstack/spec` 使用的运行时 + 编译期类型系统。每一个对象、 -字段、视图、应用、流程都会被一个 Zod schema 解析与校验。JSON -Schema、TypeScript 类型与 REST 请求校验器都从同一份 Zod 定义 -派生。 diff --git a/content/docs/resources/glossary.zh-Hant.mdx b/content/docs/resources/glossary.zh-Hant.mdx deleted file mode 100644 index c4458b5..0000000 --- a/content/docs/resources/glossary.zh-Hant.mdx +++ /dev/null @@ -1,212 +0,0 @@ ---- -# @generated zh-Hant from zh-Hans -- do not edit. Edit the English source, then regenerate: pnpm --filter @objectos/docs gen:zh-hant -title: 術語表 -description: ObjectOS 與 ObjectStack 通用詞彙 —— 每個一條定義。 -translation: - source_sha: b7904d8f61e8f9b0bea68a073206f0af8bd20228a7c8fe8da68e6cc3ac4550e6 - guide_rev: 1 - mode: auto ---- - -本文件使用的每個術語都給出一個權威定義。 - -### Artifact（產物） - -編譯後的 `objectstack.json` 檔案。對一個應用的自包含、不可變描述 —— -manifest、物件、檢視、應用、流程、許可權、翻譯。由 `os compile` 產生。 -ObjectOS 實際執行的就是它。 - -### Action - -在後設資料中宣告的命名操作，可通過 REST -（`/api/v1/data//actions/`）、Console 按鈕或流程 -步驟呼叫。繼承呼叫者的許可權。 - -### Adapter - -把 ObjectStack 整合到宿主執行時的框架包 —— Express、Fastify、Hono、 -Next.js、Nuxt、SvelteKit、NestJS。大多數 ObjectOS 部署不需要 adapter; -ObjectOS 自帶 HTTP 伺服器。 - -### App - -把物件 + 檢視 + 許可權打包成一個在 Console 中可導航的應用。同一個 -執行時中可以共存多個 App（如 CRM + Helpdesk + Setup）。 - -### Better Auth - -為 `@objectstack/plugin-auth` 提供動力的認證庫。你不直接配置 -Better Auth;外掛會做封裝。 - -### Capability（能力） - -產物在其 `requires` 列表中宣告的可選執行時特性。對應一個包 —— 例如 -`audit` → `@objectstack/plugin-audit`。由 ObjectOS 按需載入。見 -[執行時能力](/docs/reference/runtime-capabilities)。 - -### CEL - -[Common Expression Language](https://github.com/google/cel-spec) —— -Google 的安全沙箱表示式語法。用於公式、校驗規則、許可權謂詞、共享 -規則與流程條件。 - -### Console - -位於 `/_console/` 的系統 UI —— 管理使用者、角色、許可權集、審計日誌、 -會話、API key、系統設定。與 Console（業務 UI）有區別。 - -### Control Plane（控制面） - -可選服務，將版本化的產物分發給 ObjectOS 例項。可用 ObjectStack -Cloud 託管或自行部署。大多數部署不需要它 —— 單應用生產場景下， -檔案掛載模式即可。 - -### Driver（驅動） - -資料後端實現：`driver-sql`（Postgres、MySQL、SQLite、Turso/libSQL）、 -`driver-mongodb`、`driver-memory`。啟動時按資料庫 URL 選擇。 - -### Embedder - -把文本轉成向量供 RAG / 語義檢索使用的服務。跨 provider 可插拔 -（OpenAI、Azure、矽基流動、Ollama……）。見 -[AI 服務](/docs/configure/ai)。 - -### Environment - -按租戶隔離的執行時例項，背後有各自的資料庫與身份。在 v4.x 中 -有時仍稱 *Project*（保留別名）。v5.0 在 CLI、HTTP、環境變數、 -schema 中統一為 *Environment*。 - -### Field（欄位） - -物件上的有型別屬性。約 48 種內建型別：`text`、`select`、`lookup`、 -`markdown`、`file`、`formula`、`summary` 等。見 -[資料模型](/docs/build/data)。 - -### Flow（流程） - -宣告式業務邏輯 —— 自動觸發（記錄觸發器）、定時（cron）或手動 -（按鈕 / API）。以 DAG 執行，支援 condition/loop/retry/parallel -等原語。見 [流程與自動化](/docs/build/automation/flows)。 - -### Formula field（公式欄位） - -值為 CEL 表示式、讀取時計算的欄位，不儲存。 - -### Hook - -注入到物件生命週期的函式（`beforeInsert`、`afterUpdate`……）。 -用 TypeScript 編寫。與流程不同：Hook 是一等程式碼，流程是後設資料。 - -### Kernel（核心） - -ObjectOS 內部的微核心，負責載入外掛、持有 DI 容器、分發事件， -併為單個 Environment 提供後設資料服務。一個程序可在 LRU 中快取 -多個核心（每個 Environment 一個）。 - -### Manifest - -產物頭部的頂層後設資料：`id`、`namespace`、`version`、`type` -（`app` / `plugin` / `service`）、`name`、`description`、 -`requires` 列表。 - -### Marketplace（應用市場） - -Console 內可安裝應用的目錄。背後由可配置的包註冊中心支援。見 -[應用市場](/docs/build/marketplace)。 - -### MCP（Model Context Protocol） - -一個開放協議，讓 AI 智慧體發現並呼叫工具。ObjectOS 可以通過 -`@objectstack/mcp` 把物件 + action 暴露為 MCP。 - -### Object（物件） - -有型別的業務實體 —— `task`、`account`、`invoice`。以 TypeScript -schema 宣告;自動生成 REST API、Console 檢視、審計條目與 RBAC 檢查 -點。見 [資料模型](/docs/build/data)。 - -### ObjectOS - -執行時 —— 一個對外服務你應用的 Node.js 程序。開源，Apache-2.0。 -**本文件站點就是 ObjectOS 的文件。** - -### ObjectQL - -資料層協議與查詢引擎。把宣告式查詢編譯成原生 SQL / Mongo 查詢。 -REST 端點、Console、流程都用同一套引擎。 - -### ObjectStack - -總稱專案：框架（`@objectstack/*` npm 包）、執行時（ObjectOS）、 -可選雲服務，以及應用市場。有時也稱 "平臺"。 - -### ObjectUI - -檢視層協議 —— App、View、Page、Dashboard、Action、Chart、導航。 -Console 渲染 ObjectUI 宣告。 - -### Permission Set（許可權集） - -一組授權的捆綁 —— 物件許可權、欄位許可權、系統許可權。可直接掛到使用者 -上，也可經由角色掛載。授權的主單元。見 -[許可權](/docs/configure/permissions)。 - -### Plugin（外掛） - -為執行時擴充套件能力的框架包 —— `plugin-auth`、`plugin-security`、 -`plugin-audit`、`plugin-webhooks`、`mcp` 等。通過 -DI + 生命週期 Hook（`init → start → destroy`）啟用。 - -### Project - -**Environment** 的舊名。在 v4.x 的 CLI/環境變數中仍可用（已別名化）。 -v5.0 中移除。 - -### Record Share（記錄共享） - -把對某條記錄的訪問直接授予某個使用者 / 角色 / 使用者組。以 -`sys_record_share` 行儲存。與共享規則（宣告式條件）不同。 - -### Sharing Rule（共享規則） - -基於條件授予記錄訪問的宣告式規則（"區域經理可以看到本區域的 -記錄"）。查詢時求值，編譯為行級過濾條件。 - -### Console - -位於 `/_console/` 的業務 UI —— 瀏覽、建立、編輯記錄，配置檢視， -從應用市場安裝應用。與 Console（系統 UI）有區別。 - -### Surface（表面） - -執行中的 ObjectOS 暴露的四類 HTTP 入口之一：`/`（REST API）、 -`/_console/`、`/_account/`、`/_console/`。 - -### System Context（系統上下文） - -供外掛、Hook 與種子指令碼繞過安全檢查所用的內部執行模式。可審計; -不暴露給使用者程式碼。 - -### Tenant（租戶） - -多租戶部署中的邏輯隔離邊界。一個租戶通常對映為一個 Environment。 -Cookie 與會話按主機名作用域;資料按 Environment 作用域。 - -### Trigger（觸發器） - -觸發流程的條件 —— 記錄事件（`after_insert`）、排程（cron）或手動 -呼叫。 - -### View（檢視） - -繫結到物件上的宣告式 UI 配置 —— list、form、kanban、calendar、 -gantt。由 Console 渲染，你不需要寫元件。 - -### Zod schema - -`@objectstack/spec` 使用的執行時 + 編譯期型別系統。每一個物件、 -欄位、檢視、應用、流程都會被一個 Zod schema 解析與校驗。JSON -Schema、TypeScript 型別與 REST 請求校驗器都從同一份 Zod 定義 -派生。 diff --git a/content/docs/why.de.mdx b/content/docs/why.de.mdx deleted file mode 100644 index c7736ed..0000000 --- a/content/docs/why.de.mdx +++ /dev/null @@ -1,150 +0,0 @@ ---- -title: Warum ObjectOS -description: Der ehrliche Pitch — wann du es einsetzen solltest, wann nicht und was es anders macht. -translation: - source_sha: ff0ca5df2635d1d00748f9f434d140c5713792157c936a7a639a6bfce552444c - guide_rev: 1 - mode: auto ---- - -Diese Seite gibt es, damit du nicht in jedem anderen Dokument zwischen -den Zeilen lesen musst, um herauszufinden, ob ObjectOS das Richtige für -dich ist. - -## Die Form der Wette - -ObjectOS geht eine klare Wette ein: **KI schreibt die Metadaten deiner -Anwendung, dir gehört die Runtime, die sie ausführt.** - -Du schreibst Objekte, Felder, Ansichten, Flows und Berechtigungen nicht -Datei für Datei von Hand. Deine Nutzer beschreiben in natürlicher -Sprache im Console-internen [AI Builder](/docs/build/ai-builder), was -sie brauchen; er ruft eine kleine Menge geprüfter Tools auf, stellt jede -Änderung zur menschlichen Freigabe in eine Warteschlange, und das -Ergebnis ist live — REST-Endpunkte, Console-Bildschirme, RBAC, -Audit-Log, alles aus denselben Metadaten generiert. - -Die Runtime liegt in **deiner** VPC, auf **deiner** Datenbank, unter -**deinem** Apache-2.0-Fork. Das Modell kommuniziert mit einer -gesandboxten Metadaten-API, nicht mit deinem Data Warehouse. - -Das ist der ganze Pitch. Der Rest dieser Seite handelt davon, zu wem das -passt und zu wem nicht. - -## Setze ObjectOS ein, wenn du … - -- ein internes Tool, ein Admin-Panel oder eine Back-Office-App brauchst, - **und** -- möchtest, dass die Menschen, die es nutzen (oder die KI-Agenten, die - für sie handeln), es *erweitern* können, ohne ein Ticket einzureichen, - **und** -- die Daten nicht in der Cloud eines anderen ablegen kannst (oder - willst), **und** -- nicht zum zehnten Mal Auth + RBAC + Audit + Datei-Uploads + Jobs + - Webhooks neu bauen willst. - -Typische Szenarien, in denen es passt: - -| Szenario | Warum es funktioniert | -|---|---| -| Ablösung einer Retool-/Appsmith-App, weil im Security Review Datenhoheit zum Thema wurde | ObjectOS läuft in deiner VPC; Daten verlassen sie nie | -| Aufbau eines Compliance-/Risiko-/Vendor-Management-Tools für ein reguliertes Unternehmen | Audit-Log, RBAC, Feldsicherheit und Zeilenisolation sind erstklassig — und jede KI-getriebene Änderung ist selbst ein Audit-Eintrag | -| Bereitstellung einer internen Verwaltung für ein SaaS-Produkt | Ein einziger Node-Prozess, reiht sich neben deinen bestehenden Diensten ein | -| Air-Gapped- oder On-Prem-Deployment für einen Enterprise-Kunden | Erstklassiges Deployment-Ziel, kein Internet-Egress erforderlich (BYO lokales Modell) | -| Mandantenfähiges internes Portal (eine Runtime, viele kleine Apps) | Kernel pro Projekt + LRU-Cache genau dafür entworfen | -| Du möchtest, dass deine Nutzer ihre eigenen Erweiterungen sicher „vibe-coden" | Der AI Builder + die HITL-Freigabe-Warteschlange + das Audit-Log sind der ganze Sinn | - -## Setze ObjectOS nicht ein, wenn du … - -- ein Consumer-Produkt mit hohem Traffic baust → nutze ein - klassisches Web-Framework, du hast mehr Kontrolle. -- eine pixelgenaue, maßgeschneiderte UI für Endnutzer brauchst → die - Console von ObjectOS ist für den Admin-/internen Gebrauch; kombiniere - sie über REST mit deinem eigenen Front-End. -- einen No-Code-Drag-and-Drop-Builder für Nicht-Entwickler und eine - gehostete Cloud willst → nutze Retool, Bubble oder Airtable. ObjectOS - ist code-first, KI-getrieben und self-hosted. -- Echtzeit-Kollaboration beim Editieren (im Figma-Stil) brauchst → das - löst das Realtime-Plugin nicht. - -## Im Vergleich zu dem, was du wahrscheinlich nutzt - -### vs. Retool / Appsmith / Internal - -| | Retool | ObjectOS | -|---|---|---| -| Datenstandort | Ihre Cloud (oder self-hosted in höheren Tarifen) | Dein Netzwerk, immer | -| UI-Builder | Drag-and-drop, sehr ausgefeilt | Metadatengetrieben, generiert; weniger individuell | -| Preismodell | Pro Nutzer, skaliert schmerzhaft | Self-hosted, Apache-2.0 | -| Workflow / Trigger | Ihre Workflow-Engine | Deklarative Flows + Plugins | -| Backend-Logik | Auf ihren Query-Editor beschränkt | Vollständiges TypeScript, gesamtes Node-Ökosystem | -| Am besten für | Schnelle Dashboards auf bestehenden APIs | Apps, denen ihre Daten *gehören* | - -### vs. Supabase / Firebase - -| | Supabase | ObjectOS | -|---|---|---| -| Einrichtungszeit | ~30 Sekunden | ~30 Sekunden | -| Datenbank | Postgres, ihres (Self-Hosting möglich) | Beliebige Postgres / MySQL / SQLite / Turso / Mongo, **deine** | -| Auth | Eingebaut | Eingebaut | -| Generierte APIs | PostgREST | ObjectQL-generiertes REST | -| Admin-UI | Console (einfach) | Console + Account | -| RBAC | Zeilenebene via Postgres RLS | RBAC + Zeilenebene + Feldebene, deklarativ | -| Audit-Log | Selbstgebaut | Erstklassig | -| Vendor-Lock-in | Ihre Auth + ihr Storage + ihr Realtime | Keiner — jede Schicht ist ein Plugin | -| Am besten für | Neue Apps, die ein BaaS wollen | Apps, die die Runtime besitzen müssen | - -### vs. Salesforce / NetSuite / ServiceNow - -| | Salesforce | ObjectOS | -|---|---|---| -| Datenmodell | Objekte + Felder + Beziehungen | Dasselbe | -| Berechtigungen | Profile + Permission Sets + Sharing Rules + FLS | **Dasselbe Vokabular**, deklaratives TypeScript | -| Kosten pro Nutzer | 150–300 $/Nutzer/Monat | 0 $ | -| Anpassung | Apex + Lightning + Flows | TypeScript + Flows | -| Wo es läuft | Ihre Cloud, Punkt | Deine Infrastruktur | -| Zeit bis „es gehört uns" | Monate an Beratungsarbeit | Ein Nachmittag | -| Am besten für | Vertriebsgetriebene Unternehmen, die für das Ökosystem zahlen | Teams, die das Modell ohne die Steuer wollen | - -### vs. selbst bauen (Next.js + Prisma + NextAuth) - -| | DIY | ObjectOS | -|---|---|---| -| Erster REST-Endpunkt | Ein paar Stunden | 60 Sekunden | -| Auth (E-Mail + OAuth + OIDC + Passkey + 2FA) | Wochen | Inbegriffen | -| Admin-UI für jedes Objekt | Pro Objekt bauen | Generiert | -| Audit-Log | Selbstgebaut | Plugin, deklarativ | -| Datei-Upload zu S3 mit Berechtigungen | Selbstgebaut | Plugin | -| Hintergrundjobs + Retries + Dead Letter | Selbstgebaut | Plugin | -| Mandantenfähigkeit | Selbstgebaut (und du machst es zweimal falsch) | Eingebaut | -| Am besten für | Öffentliche App mit maßgeschneiderter UX | Internes Tooling, bei dem Tempo zählt | - -## Die ehrlichen Kompromisse - -- **Weniger UI-Freiheit als Retool.** Die Console wird aus deinen - Metadaten generiert. Du kannst sie mit einem eigenen Front-End - kombinieren (die REST-API ist dieselbe, die die Console nutzt), aber - wenn du eine handgefertigte, pixelgenaue UI brauchst, baue sie selbst - und nutze ObjectOS als Backend. -- **TypeScript-first.** Nicht-Entwickler erstellen Objekte nicht direkt. - Salesforce-Admins sind es gewohnt, sich durch einen UI-Builder zu - klicken; hier ist es `git`. -- **Neuer als Salesforce.** Salesforce hat 25 Jahre dokumentierter - Sonderfälle. Wir haben ein paar hundert. Das Protokoll ist stabil; das - Ökosystem wächst. -- **Apache-2.0.** Nutze es in kommerziellen Produkten, bette es ein, - modifiziere es privat. Keine Copyleft-Überraschungen. Optionaler - kommerzieller Support separat erhältlich. - -## Realitätscheck - -Das kleinste lauffähige ObjectOS-Deployment ist ein einzelnes -`pnpm dev` oder ein einzelner Docker-Container mit SQLite. Das größte -heute im Produktivbetrieb bedient Zehntausende interne Nutzer über -mehrere Regionen hinweg mit Postgres + S3 + Redis. Beide sind dieselbe -Software. - -Beginne mit `npx @objectstack/cli init my-app` und entscheide in 5 -Minuten. Wenn es nichts für dich ist, hast du 5 Minuten verbrannt. - -[**Probiere den Quickstart →**](/docs/quickstart) diff --git a/content/docs/why.es.mdx b/content/docs/why.es.mdx deleted file mode 100644 index e9b3942..0000000 --- a/content/docs/why.es.mdx +++ /dev/null @@ -1,142 +0,0 @@ ---- -title: Por qué ObjectOS -description: La propuesta honesta — cuándo deberías usarlo, cuándo no, y qué lo hace diferente. -translation: - source_sha: ff0ca5df2635d1d00748f9f434d140c5713792157c936a7a639a6bfce552444c - guide_rev: 1 - mode: auto ---- - -Esta página existe para que no tengas que leer entre líneas de cada -otro documento para averiguar si ObjectOS es adecuado para ti. - -## La forma de la apuesta - -ObjectOS hace una apuesta con una opinión clara: **la IA escribe los -metadatos de tu aplicación, tú eres dueño del runtime que los ejecuta.** - -No escribes a mano objetos, campos, vistas, flujos y permisos -archivo por archivo. Tus usuarios describen lo que necesitan en lenguaje -natural al [AI Builder](/docs/build/ai-builder) integrado en la Console; -este invoca un pequeño conjunto de herramientas auditadas, pone en cola -cada cambio para su aprobación humana, y el resultado está en vivo — -endpoints REST, pantallas de Console, RBAC, registro de auditoría, -todo generado a partir de los mismos metadatos. - -El runtime reside en **tu** VPC, en **tu** base de datos, bajo -**tu** fork con licencia Apache-2.0. El modelo se comunica con una API -de metadatos en sandbox, no con tu data warehouse. - -Esa es toda la propuesta. El resto de esta página trata sobre a quién -le encaja y a quién no. - -## Usa ObjectOS si … - -- necesitas una herramienta interna, panel de administración o aplicación de back-office, **y** -- quieres que las personas que la usan (o los agentes de IA que actúan en su nombre) puedan - *extenderla* sin abrir un ticket, **y** -- no puedes (o no quieres) poner los datos en la nube de otra persona, **y** -- no quieres reconstruir auth + RBAC + auditoría + cargas de archivos + trabajos + - webhooks por décima vez. - -Escenarios comunes donde encaja: - -| Escenario | Por qué funciona | -|---|---| -| Reemplazar una app de Retool / Appsmith porque la soberanía de datos surgió en una revisión de seguridad | ObjectOS se ejecuta en tu VPC; los datos nunca salen | -| Construir una herramienta de cumplimiento / riesgo / gestión de proveedores para un negocio regulado | El registro de auditoría, RBAC, seguridad a nivel de campo y aislamiento a nivel de fila son de primera clase — y cada cambio impulsado por IA es en sí mismo una entrada de auditoría | -| Levantar un administrador interno para un producto SaaS | Un único proceso de Node, encaja junto a tus servicios existentes | -| Despliegue air-gapped u on-premise para un cliente empresarial | Destino de despliegue de primera clase, sin necesidad de salida a internet (BYO modelo local) | -| Portal interno multi-inquilino (un runtime, muchas apps pequeñas) | Kernel por proyecto + caché LRU diseñados para esto | -| Quieres que tus usuarios "vibe-codeen" sus propias extensiones de forma segura | El AI Builder + la cola de aprobación HITL + el registro de auditoría son justamente el punto | - -## No uses ObjectOS si … - -- estás construyendo un producto de consumo de alto tráfico → usa un framework - web tradicional, tendrás más control. -- necesitas una interfaz a medida y perfecta al píxel para usuarios finales → la Console de ObjectOS es - para uso administrativo/interno; combínala con tu propio front-end vía REST. -- quieres un constructor no-code de arrastrar y soltar para no ingenieros y una nube - alojada → usa Retool, Bubble o Airtable. ObjectOS es code-first, impulsado por IA y autoalojado. -- necesitas edición colaborativa en tiempo real (estilo Figma) → no es lo que resuelve el - plugin de realtime. - -## Comparado con lo que probablemente estás usando - -### vs. Retool / Appsmith / Internal - -| | Retool | ObjectOS | -|---|---|---| -| Ubicación de los datos | Su nube (o autoalojado en un nivel superior) | Tu red, siempre | -| Constructor de UI | Arrastrar y soltar, muy pulido | Impulsado por metadatos, generado; menos personalizado | -| Precios | Por usuario, escala de forma dolorosa | Autoalojado, Apache-2.0 | -| Flujo de trabajo / disparadores | Su motor de flujos de trabajo | Flujos declarativos + plugins | -| Lógica de backend | Limitada a su editor de consultas | TypeScript completo, ecosistema completo de Node | -| Mejor para | Dashboards rápidos sobre APIs existentes | Apps que *son dueñas* de sus datos | - -### vs. Supabase / Firebase - -| | Supabase | ObjectOS | -|---|---|---| -| Tiempo de configuración | ~30 segundos | ~30 segundos | -| Base de datos | Postgres, suya (autoalojado posible) | Cualquier Postgres / MySQL / SQLite / Turso / Mongo, **tuya** | -| Auth | Incorporado | Incorporado | -| APIs generadas | PostgREST | REST generado por ObjectQL | -| UI de administración | Console (básica) | Console + Account | -| RBAC | A nivel de fila vía Postgres RLS | RBAC + a nivel de fila + a nivel de campo, declarativo | -| Registro de auditoría | Hazlo tú mismo | De primera clase | -| Dependencia del proveedor | Su auth + su almacenamiento + su realtime | Ninguna — cada capa es un plugin | -| Mejor para | Apps nuevas que quieren un BaaS | Apps que necesitan ser dueñas del runtime | - -### vs. Salesforce / NetSuite / ServiceNow - -| | Salesforce | ObjectOS | -|---|---|---| -| Modelo de datos | Objetos + campos + relaciones | Igual | -| Permisos | Perfil + conjuntos de permisos + reglas de compartición + FLS | **El mismo vocabulario**, TypeScript declarativo | -| Costo por usuario | $150-300/usuario/mes | $0 | -| Personalización | Apex + Lightning + flujos | TypeScript + flujos | -| Dónde se ejecuta | Su nube, punto | Tu infraestructura | -| Tiempo hasta "es nuestro" | Meses de trabajo de consultoría | Una tarde | -| Mejor para | Empresas lideradas por ventas que pagarán por el ecosistema | Equipos que quieren el modelo sin el impuesto | - -### vs. construir lo tuyo propio (Next.js + Prisma + NextAuth) - -| | DIY | ObjectOS | -|---|---|---| -| Primer endpoint REST | Unas horas | 60 segundos | -| Auth (email + OAuth + OIDC + passkey + 2FA) | Semanas | Incluido | -| UI de administración para cada objeto | Construir por objeto | Generada | -| Registro de auditoría | Hazlo tú mismo | Plugin, declarativo | -| Carga de archivos a S3 con permisos | Hazlo tú mismo | Plugin | -| Trabajos en segundo plano + reintentos + dead letter | Hazlo tú mismo | Plugin | -| Multi-inquilino | Hazlo tú mismo (y lo harás mal dos veces) | Incorporado | -| Mejor para | App pública con UX a medida | Tooling interno donde gana la velocidad | - -## Las concesiones honestas - -- **Menos libertad de UI que Retool.** La Console se genera a partir de tus - metadatos. Puedes combinarla con un front-end personalizado (la API REST es - la misma que usa la Console), pero si necesitas una interfaz hecha a mano y - perfecta al píxel, constrúyela tú mismo y usa ObjectOS como backend. -- **TypeScript primero.** Los no ingenieros no escribirán objetos directamente. - Los administradores de Salesforce están acostumbrados a hacer clic en un constructor de UI; aquí, - es `git`. -- **Más nuevo que Salesforce.** Salesforce tiene 25 años de casos límite - documentados. Nosotros tenemos unos cientos. El protocolo es estable; el - ecosistema está creciendo. -- **Apache-2.0.** Úsalo en productos comerciales, incorpóralo, modifícalo - de forma privada. Sin sorpresas de copyleft. Soporte comercial opcional - disponible por separado. - -## Verificación de la realidad - -El despliegue de ObjectOS viable más pequeño es un único `pnpm dev` o un -único contenedor Docker con SQLite. El más grande en producción hoy en día -sirve a decenas de miles de usuarios internos en múltiples regiones con -Postgres + S3 + Redis. Ambos son el mismo software. - -Comienza con `npx @objectstack/cli init my-app` y decide en 5 minutos. -Si no es para ti, habrás gastado 5 minutos. - -[**Prueba el Quickstart →**](/docs/quickstart) diff --git a/content/docs/why.fr.mdx b/content/docs/why.fr.mdx deleted file mode 100644 index 385ac47..0000000 --- a/content/docs/why.fr.mdx +++ /dev/null @@ -1,150 +0,0 @@ ---- -title: Pourquoi ObjectOS -description: L'argumentaire honnête — quand l'utiliser, quand ne pas l'utiliser, et ce qui le rend différent. -translation: - source_sha: ff0ca5df2635d1d00748f9f434d140c5713792157c936a7a639a6bfce552444c - guide_rev: 1 - mode: auto ---- - -Cette page existe pour que vous n'ayez pas à lire entre les lignes de -chaque autre page de documentation pour déterminer si ObjectOS vous -convient. - -## La nature du pari - -ObjectOS fait un pari assumé : **l'IA écrit les métadonnées de votre -application, vous possédez le runtime qui les exécute.** - -Vous n'écrivez pas à la main les objets, les champs, les vues, les flux -et les permissions fichier par fichier. Vos utilisateurs décrivent ce -dont ils ont besoin en langage naturel à l'[AI Builder](/docs/build/ai-builder) -intégré à la Console ; celui-ci appelle un petit ensemble d'outils -audités, met chaque changement en file d'attente pour approbation -humaine, et le résultat est en production — points de terminaison REST, -écrans de la Console, RBAC, journal d'audit, le tout généré à partir des -mêmes métadonnées. - -Le runtime se trouve dans **votre** VPC, sur **votre** base de données, -sous **votre** fork Apache-2.0. Le modèle dialogue avec une API de -métadonnées en bac à sable, pas avec votre entrepôt de données. - -C'est tout l'argumentaire. Le reste de cette page indique à qui cela -convient et à qui cela ne convient pas. - -## Utilisez ObjectOS si vous … - -- avez besoin d'un outil interne, d'un panneau d'administration ou d'une - application back-office, **et** -- voulez que les personnes qui l'utilisent (ou les agents IA agissant - pour elles) puissent l'*étendre* sans ouvrir de ticket, **et** -- ne pouvez (ou ne voulez) pas placer les données dans le cloud de - quelqu'un d'autre, **et** -- ne voulez pas reconstruire l'authentification + RBAC + audit + envois - de fichiers + jobs + webhooks pour la dixième fois. - -Scénarios courants où cela convient : - -| Scénario | Pourquoi cela fonctionne | -|---|---| -| Remplacer une application Retool / Appsmith parce que la souveraineté des données a été soulevée lors d'une revue de sécurité | ObjectOS s'exécute dans votre VPC ; les données ne sortent jamais | -| Construire un outil de conformité / risque / gestion des fournisseurs pour une entreprise réglementée | Le journal d'audit, le RBAC, la sécurité des champs et l'isolation au niveau des lignes sont natifs — et chaque changement piloté par l'IA est lui-même une entrée d'audit | -| Mettre en place une administration interne pour un produit SaaS | Un seul processus Node, qui s'insère à côté de vos services existants | -| Déploiement air-gapped ou on-prem pour un client grand compte | Cible de déploiement de premier ordre, aucune sortie internet requise (modèle local en BYO) | -| Portail interne multi-locataire (un runtime, plusieurs petites applications) | Kernel par projet + cache LRU conçus pour cela | -| Vous voulez que vos utilisateurs « vibe-codent » leurs propres extensions en toute sécurité | L'AI Builder + la file d'approbation HITL + le journal d'audit en sont tout l'intérêt | - -## N'utilisez pas ObjectOS si vous … - -- construisez un produit grand public à fort trafic → utilisez un - framework web traditionnel, vous aurez plus de contrôle. -- avez besoin d'une interface sur mesure au pixel près pour les - utilisateurs finaux → la Console d'ObjectOS est destinée à un usage - administratif/interne ; associez-la à votre propre front-end via REST. -- voulez un constructeur no-code en glisser-déposer pour les - non-ingénieurs et un cloud hébergé → utilisez Retool, Bubble ou - Airtable. ObjectOS est code-first, piloté par l'IA, auto-hébergé. -- avez besoin d'une édition collaborative en temps réel (à la Figma) → - ce n'est pas ce que résout le plugin temps réel. - -## Comparé à ce que vous utilisez probablement - -### vs. Retool / Appsmith / Internal - -| | Retool | ObjectOS | -|---|---|---| -| Emplacement des données | Leur cloud (ou auto-hébergé sur une offre supérieure) | Votre réseau, toujours | -| Constructeur d'UI | Glisser-déposer, très soigné | Piloté par métadonnées, généré ; moins personnalisable | -| Tarification | Par utilisateur, montée en charge douloureuse | Auto-hébergé, Apache-2.0 | -| Workflow / déclencheurs | Leur moteur de workflow | Flux déclaratifs + plugins | -| Logique back-end | Limitée à leur éditeur de requêtes | TypeScript complet, tout l'écosystème Node | -| Idéal pour | Tableaux de bord rapides au-dessus d'API existantes | Applications qui *possèdent* leurs données | - -### vs. Supabase / Firebase - -| | Supabase | ObjectOS | -|---|---|---| -| Temps de configuration | ~30 secondes | ~30 secondes | -| Base de données | Postgres, la leur (auto-hébergement possible) | N'importe quel Postgres / MySQL / SQLite / Turso / Mongo, **la vôtre** | -| Authentification | Intégrée | Intégrée | -| API générées | PostgREST | REST généré par ObjectQL | -| Interface d'administration | Console (basique) | Console + Account | -| RBAC | Au niveau des lignes via le RLS de Postgres | RBAC + niveau des lignes + niveau des champs, déclaratif | -| Journal d'audit | À faire soi-même | Natif | -| Verrouillage fournisseur | Leur authentification + leur stockage + leur temps réel | Aucun — chaque couche est un plugin | -| Idéal pour | Nouvelles applications voulant un BaaS | Applications qui doivent posséder le runtime | - -### vs. Salesforce / NetSuite / ServiceNow - -| | Salesforce | ObjectOS | -|---|---|---| -| Modèle de données | Objets + champs + relations | Identique | -| Permissions | Profil + jeux de permissions + règles de partage + FLS | **Même vocabulaire**, TypeScript déclaratif | -| Coût par utilisateur | 150-300 $/utilisateur/mois | 0 $ | -| Personnalisation | Apex + Lightning + flux | TypeScript + flux | -| Où il s'exécute | Leur cloud, un point c'est tout | Votre infrastructure | -| Temps avant « on le possède » | Des mois de travail de consultants | Un après-midi | -| Idéal pour | Entreprises orientées ventes prêtes à payer pour l'écosystème | Équipes qui veulent le modèle sans la taxe | - -### vs. tout faire soi-même (Next.js + Prisma + NextAuth) - -| | DIY | ObjectOS | -|---|---|---| -| Premier point de terminaison REST | Quelques heures | 60 secondes | -| Authentification (e-mail + OAuth + OIDC + passkey + 2FA) | Des semaines | Incluse | -| Interface d'administration pour chaque objet | À construire par objet | Générée | -| Journal d'audit | À faire soi-même | Plugin, déclaratif | -| Envoi de fichiers vers S3 avec permissions | À faire soi-même | Plugin | -| Jobs en arrière-plan + relances + dead letter | À faire soi-même | Plugin | -| Multi-location | À faire soi-même (et vous vous tromperez deux fois) | Intégrée | -| Idéal pour | Application destinée au public avec une UX sur mesure | Outillage interne où la vitesse prime | - -## Les compromis honnêtes - -- **Moins de liberté d'UI que Retool.** La Console est générée à partir - de vos métadonnées. Vous pouvez l'associer à un front-end personnalisé - (l'API REST est la même que celle utilisée par la Console), mais si - vous avez besoin d'une interface au pixel près faite à la main, - construisez-la vous-même et utilisez ObjectOS comme back-end. -- **TypeScript d'abord.** Les non-ingénieurs n'écriront pas directement - les objets. Les administrateurs Salesforce ont l'habitude de cliquer - dans un constructeur d'UI ; ici, c'est `git`. -- **Plus récent que Salesforce.** Salesforce documente 25 ans de cas - limites. Nous en avons quelques centaines. Le protocole est stable ; - l'écosystème grandit. -- **Apache-2.0.** Utilisez-le dans des produits commerciaux, intégrez-le, - modifiez-le en privé. Aucune mauvaise surprise de copyleft. Un support - commercial optionnel est disponible séparément. - -## Mise au point - -Le plus petit déploiement viable d'ObjectOS est un simple `pnpm dev` ou -un seul conteneur Docker avec SQLite. Le plus grand en production -aujourd'hui sert des dizaines de milliers d'utilisateurs internes à -travers plusieurs régions avec Postgres + S3 + Redis. Les deux sont le -même logiciel. - -Commencez avec `npx @objectstack/cli init my-app` et décidez en 5 -minutes. Si ce n'est pas pour vous, vous aurez perdu 5 minutes. - -[**Essayer le Quickstart →**](/docs/quickstart) diff --git a/content/docs/why.ja.mdx b/content/docs/why.ja.mdx deleted file mode 100644 index bb1c061..0000000 --- a/content/docs/why.ja.mdx +++ /dev/null @@ -1,139 +0,0 @@ ---- -title: なぜ ObjectOS なのか -description: 率直な提案 — いつ使うべきか、いつ使うべきでないか、そして何が違うのか。 -translation: - source_sha: ff0ca5df2635d1d00748f9f434d140c5713792157c936a7a639a6bfce552444c - guide_rev: 1 - mode: auto ---- - -このページは、ObjectOS が自分に合っているかどうかを判断するために、 -他のすべてのドキュメントの行間を読まなくて済むように存在しています。 - -## この賭けのかたち - -ObjectOS はひとつの明確な賭けに出ています。**AI があなたのアプリケーションの -メタデータを記述し、あなたはそれを実行するランタイムを所有する。** - -オブジェクト、フィールド、ビュー、フロー、権限をファイルごとに手で書く必要は -ありません。ユーザーは必要なものを Console 内の [AI Builder](/docs/build/ai-builder) に -平易な言葉で説明します。AI Builder は監査済みの小さなツール群を呼び出し、 -すべての変更を人による承認のためにキューに入れ、その結果がそのまま稼働します。 -REST エンドポイント、Console 画面、RBAC、監査ログ — すべてが同じメタデータから -生成されます。 - -ランタイムは **あなたの** VPC 内、**あなたの** データベース上、**あなたの** -Apache-2.0 フォークのもとに置かれます。モデルが対話するのはサンドボックス化された -メタデータ API であり、あなたのデータウェアハウスではありません。 - -これが提案のすべてです。このページの残りは、これが誰に合い、誰に合わないかの話です。 - -## ObjectOS を使うべきなのは、あなたが … - -- 社内ツール、管理パネル、またはバックオフィスアプリを必要としていて、**かつ** -- それを使う人々（またはその人々の代わりに動く AI エージェント）が、チケットを - 起票することなく *拡張* できるようにしたい、**かつ** -- データを他社のクラウドに置けない（または置きたくない）、**かつ** -- 認証 + RBAC + 監査 + ファイルアップロード + ジョブ + Webhook を 10 回目も - 作り直したくない、という場合です。 - -合致する一般的なシナリオ: - -| シナリオ | なぜ機能するのか | -|---|---| -| セキュリティレビューでデータ主権が問題になったため Retool / Appsmith アプリを置き換える | ObjectOS はあなたの VPC 内で動作し、データが外に出ることはない | -| 規制対象ビジネス向けのコンプライアンス / リスク / ベンダー管理ツールを構築する | 監査ログ、RBAC、フィールドセキュリティ、行レベルの分離が標準機能 — しかも AI 主導の変更そのものが監査エントリになる | -| SaaS 製品の社内管理画面を立ち上げる | 単一の Node プロセスで、既存サービスの隣にそのまま組み込める | -| エンタープライズ顧客向けのエアギャップまたはオンプレミス展開 | 第一級の展開ターゲットで、インターネット送信は不要（ローカルモデルを持ち込み） | -| マルチテナント社内ポータル（ひとつのランタイム、多数の小規模アプリ） | プロジェクトごとのカーネル + LRU キャッシュがこのために設計されている | -| ユーザーに自分自身の拡張を安全に「バイブコーディング」させたい | AI Builder + HITL 承認キュー + 監査ログこそが核心 | - -## ObjectOS を使うべきでないのは、あなたが … - -- 高トラフィックのコンシューマー向け製品を構築している場合 → 従来の Web - フレームワークを使ってください。より多くの制御が得られます。 -- エンドユーザー向けにピクセル単位で作り込んだ専用 UI が必要な場合 → ObjectOS の - Console は管理 / 社内用途向けです。REST 経由で独自のフロントエンドと組み合わせてください。 -- 非エンジニア向けのノーコードのドラッグ&ドロップビルダーとホスティングされた - クラウドが欲しい場合 → Retool、Bubble、または Airtable を使ってください。ObjectOS は - コードファーストで AI 主導、セルフホストです。 -- リアルタイムの共同編集（Figma スタイル）が必要な場合 → これは realtime プラグインが - 解決する問題ではありません。 - -## あなたがおそらく使っているものとの比較 - -### vs. Retool / Appsmith / 社内ツール - -| | Retool | ObjectOS | -|---|---|---| -| データの所在 | 同社のクラウド（または上位プランでセルフホスト） | 常にあなたのネットワーク | -| UI ビルダー | ドラッグ&ドロップ、非常に洗練されている | メタデータ駆動で生成、カスタマイズ性は低め | -| 価格 | ユーザー単位で、スケールするほど苦しい | セルフホスト、Apache-2.0 | -| ワークフロー / トリガー | 同社のワークフローエンジン | 宣言的なフロー + プラグイン | -| バックエンドロジック | 同社のクエリエディタに限定 | フル TypeScript、フル Node エコシステム | -| 最適な用途 | 既存 API の上に素早くダッシュボードを作る | データを *所有* するアプリ | - -### vs. Supabase / Firebase - -| | Supabase | ObjectOS | -|---|---|---| -| セットアップ時間 | 約 30 秒 | 約 30 秒 | -| データベース | Postgres、同社のもの（セルフホストも可能） | 任意の Postgres / MySQL / SQLite / Turso / Mongo、**あなたのもの** | -| 認証 | 組み込み | 組み込み | -| 生成される API | PostgREST | ObjectQL が生成する REST | -| 管理 UI | Console（基本的） | Console + Account | -| RBAC | Postgres RLS による行レベル | RBAC + 行レベル + フィールドレベル、宣言的 | -| 監査ログ | 自前で実装 | 第一級機能 | -| ベンダーロックイン | 同社の認証 + 同社のストレージ + 同社のリアルタイム | なし — すべての層がプラグイン | -| 最適な用途 | BaaS を求める新規アプリ | ランタイムを所有する必要があるアプリ | - -### vs. Salesforce / NetSuite / ServiceNow - -| | Salesforce | ObjectOS | -|---|---|---| -| データモデル | オブジェクト + フィールド + リレーション | 同じ | -| 権限 | プロファイル + 権限セット + 共有ルール + FLS | **同じ語彙**、宣言的な TypeScript | -| ユーザー単位コスト | 1 ユーザーあたり月 $150〜300 | $0 | -| カスタマイズ | Apex + Lightning + フロー | TypeScript + フロー | -| 実行場所 | 同社のクラウドのみ | あなたのインフラ | -| 「所有できる」までの時間 | コンサルタントによる数か月の作業 | 一日の午後 | -| 最適な用途 | エコシステムに費用を払うセールス主導の企業 | 税金なしでモデルだけが欲しいチーム | - -### vs. 自前で構築する（Next.js + Prisma + NextAuth） - -| | 自前 (DIY) | ObjectOS | -|---|---|---| -| 最初の REST エンドポイント | 数時間 | 60 秒 | -| 認証（email + OAuth + OIDC + パスキー + 2FA） | 数週間 | 同梱 | -| 全オブジェクトの管理 UI | オブジェクトごとに構築 | 生成される | -| 監査ログ | 自前で実装 | プラグイン、宣言的 | -| 権限付きの S3 へのファイルアップロード | 自前で実装 | プラグイン | -| バックグラウンドジョブ + リトライ + デッドレター | 自前で実装 | プラグイン | -| マルチテナント | 自前で実装（そして 2 回は間違える） | 組み込み | -| 最適な用途 | 専用 UX を持つ一般公開アプリ | スピードが勝負の社内ツール | - -## 率直なトレードオフ - -- **Retool より UI の自由度は低い。** Console はあなたのメタデータから生成されます。 - カスタムフロントエンドと組み合わせることはできますが（REST API は Console が使うものと - 同じです）、手作りでピクセル単位に作り込んだ UI が必要なら、自分で構築し、ObjectOS は - バックエンドとして使ってください。 -- **TypeScript ファースト。** 非エンジニアがオブジェクトを直接記述することはありません。 - Salesforce の管理者は UI ビルダーをクリックして進めることに慣れていますが、ここでは - `git` です。 -- **Salesforce より新しい。** Salesforce には 25 年分のエッジケースが文書化されています。 - 私たちには数百件です。プロトコルは安定しており、エコシステムは成長中です。 -- **Apache-2.0。** 商用製品での利用、組み込み、非公開での改変が可能です。コピーレフトの - 不意打ちはありません。任意の商用サポートは別途利用できます。 - -## 現実的なチェック - -実用可能な最小の ObjectOS 構成は、単一の `pnpm dev`、または SQLite を伴う単一の -Docker コンテナです。現在の本番環境で最大のものは、Postgres + S3 + Redis を用いて、 -複数のリージョンにわたり数万人の社内ユーザーにサービスを提供しています。どちらも -同じソフトウェアです。 - -`npx @objectstack/cli init my-app` から始めて、5 分で判断してください。 -合わなければ、5 分を費やしただけです。 - -[**クイックスタートを試す →**](/docs/quickstart) diff --git a/content/docs/why.ko.mdx b/content/docs/why.ko.mdx deleted file mode 100644 index e013e41..0000000 --- a/content/docs/why.ko.mdx +++ /dev/null @@ -1,143 +0,0 @@ ---- -title: 왜 ObjectOS인가 -description: 솔직한 제안 — 언제 사용해야 하고, 언제 사용하지 말아야 하며, 무엇이 다른지. -translation: - source_sha: ff0ca5df2635d1d00748f9f434d140c5713792157c936a7a639a6bfce552444c - guide_rev: 1 - mode: auto ---- - -이 페이지는 ObjectOS가 여러분에게 적합한지 알아내기 위해 다른 모든 문서의 -행간을 읽을 필요가 없도록 존재합니다. - -## 이 베팅의 형태 - -ObjectOS는 하나의 확고한 베팅을 합니다. **AI가 애플리케이션의 메타데이터를 -작성하고, 여러분은 그것을 실행하는 런타임을 소유합니다.** - -여러분은 객체, 필드, 뷰, 플로우, 권한을 파일 하나하나 직접 손으로 작성하지 -않습니다. 사용자(또는 그들을 대신해 작동하는 AI 에이전트)가 필요한 것을 -Console 내장 [AI Builder](/docs/build/ai-builder)에게 평이한 언어로 -설명합니다. 그러면 AI Builder는 감사된 소규모 도구 집합을 호출하고, 모든 -변경 사항을 사람의 승인을 위해 대기열에 넣으며, 그 결과는 곧바로 작동합니다 — -REST 엔드포인트, Console 화면, RBAC, 감사 로그, 이 모든 것이 동일한 -메타데이터에서 생성됩니다. - -런타임은 **여러분의** VPC, **여러분의** 데이터베이스, **여러분의** -Apache-2.0 포크 위에 자리합니다. 모델은 여러분의 데이터 웨어하우스가 아니라 -샌드박스화된 메타데이터 API와 대화합니다. - -이것이 제안의 전부입니다. 이 페이지의 나머지는 누구에게 맞고 누구에게 -맞지 않는지에 관한 것입니다. - -## 다음과 같다면 ObjectOS를 사용하세요 … - -- 내부 도구, 관리자 패널 또는 백오피스 앱이 필요하고, **또한** -- 그것을 사용하는 사람들(또는 그들을 대신해 작동하는 AI 에이전트)이 티켓을 - 발행하지 않고도 그것을 *확장*할 수 있기를 원하며, **또한** -- 데이터를 다른 사람의 클라우드에 둘 수 없거나 두고 싶지 않고, **또한** -- 인증 + RBAC + 감사 + 파일 업로드 + 작업 + 웹훅을 열 번째로 다시 만들고 - 싶지 않다면. - -적합한 일반적인 시나리오: - -| 시나리오 | 왜 효과적인가 | -|---|---| -| 보안 검토에서 데이터 주권이 거론되어 Retool / Appsmith 앱을 대체할 때 | ObjectOS는 여러분의 VPC에서 실행되며, 데이터는 절대 외부로 나가지 않습니다 | -| 규제 대상 비즈니스를 위한 컴플라이언스 / 리스크 / 벤더 관리 도구를 구축할 때 | 감사 로그, RBAC, 필드 보안, 행 수준 격리가 기본 기능이며 — 모든 AI 주도 변경 자체가 하나의 감사 항목입니다 | -| SaaS 제품을 위한 내부 관리자를 구축할 때 | 단일 Node 프로세스로, 기존 서비스 옆에 그대로 들어맞습니다 | -| 엔터프라이즈 고객을 위한 에어갭 또는 온프레미스 배포 | 기본 배포 대상이며, 인터넷 송신이 필요 없습니다(로컬 모델 직접 준비) | -| 멀티 테넌트 내부 포털(하나의 런타임, 여러 개의 작은 앱) | 프로젝트별 커널 + LRU 캐시가 이를 위해 설계되었습니다 | -| 사용자가 자신만의 확장을 안전하게 "바이브 코딩"하기를 원할 때 | AI Builder + HITL 승인 대기열 + 감사 로그가 바로 그 핵심입니다 | - -## 다음과 같다면 ObjectOS를 사용하지 마세요 … - -- 트래픽이 많은 소비자 제품을 구축하고 있다면 → 전통적인 웹 프레임워크를 - 사용하세요, 더 많은 제어권을 갖게 됩니다. -- 최종 사용자를 위한 픽셀 단위로 완벽한 맞춤형 UI가 필요하다면 → ObjectOS의 - Console은 관리자/내부용입니다. REST를 통해 여러분만의 프런트엔드와 함께 - 사용하세요. -- 비엔지니어를 위한 노코드 드래그 앤 드롭 빌더와 호스팅된 클라우드를 - 원한다면 → Retool, Bubble 또는 Airtable을 사용하세요. ObjectOS는 - 코드 우선, AI 주도, 자체 호스팅 방식입니다. -- 실시간 협업 편집(Figma 스타일)이 필요하다면 → 그것은 realtime 플러그인이 - 해결하는 문제가 아닙니다. - -## 여러분이 아마 사용 중인 것과의 비교 - -### vs. Retool / Appsmith / Internal - -| | Retool | ObjectOS | -|---|---|---| -| 데이터 위치 | 그들의 클라우드(또는 상위 등급에서 자체 호스팅) | 항상 여러분의 네트워크 | -| UI 빌더 | 드래그 앤 드롭, 매우 세련됨 | 메타데이터 기반, 생성됨; 덜 맞춤화됨 | -| 가격 | 사용자당, 고통스럽게 증가 | 자체 호스팅, Apache-2.0 | -| 워크플로우 / 트리거 | 그들의 워크플로우 엔진 | 선언적 플로우 + 플러그인 | -| 백엔드 로직 | 그들의 쿼리 편집기로 제한됨 | 전체 TypeScript, 전체 Node 생태계 | -| 가장 적합한 용도 | 기존 API 위에 빠른 대시보드 | 데이터를 *소유*하는 앱 | - -### vs. Supabase / Firebase - -| | Supabase | ObjectOS | -|---|---|---| -| 설정 시간 | 약 30초 | 약 30초 | -| 데이터베이스 | Postgres, 그들의 것(자체 호스팅 가능) | 모든 Postgres / MySQL / SQLite / Turso / Mongo, **여러분의 것** | -| 인증 | 내장 | 내장 | -| 생성된 API | PostgREST | ObjectQL 생성 REST | -| 관리자 UI | Console(기본) | Console + Account | -| RBAC | Postgres RLS를 통한 행 수준 | RBAC + 행 수준 + 필드 수준, 선언적 | -| 감사 로그 | 직접 구현 | 기본 기능 | -| 벤더 종속 | 그들의 인증 + 그들의 스토리지 + 그들의 realtime | 없음 — 모든 계층이 플러그인 | -| 가장 적합한 용도 | BaaS를 원하는 신규 앱 | 런타임을 소유해야 하는 앱 | - -### vs. Salesforce / NetSuite / ServiceNow - -| | Salesforce | ObjectOS | -|---|---|---| -| 데이터 모델 | 객체 + 필드 + 관계 | 동일 | -| 권한 | 프로필 + 권한 집합 + 공유 규칙 + FLS | **동일한 어휘**, 선언적 TypeScript | -| 사용자당 비용 | 사용자당 월 $150-300 | $0 | -| 커스터마이징 | Apex + Lightning + 플로우 | TypeScript + 플로우 | -| 실행 위치 | 오직 그들의 클라우드 | 여러분의 인프라 | -| "우리가 소유"하기까지의 시간 | 수개월의 컨설턴트 작업 | 하루 오후 | -| 가장 적합한 용도 | 생태계에 비용을 지불할 영업 주도 기업 | 세금 없이 모델을 원하는 팀 | - -### vs. 직접 구축(Next.js + Prisma + NextAuth) - -| | DIY | ObjectOS | -|---|---|---| -| 첫 REST 엔드포인트 | 몇 시간 | 60초 | -| 인증(이메일 + OAuth + OIDC + 패스키 + 2FA) | 수 주 | 포함됨 | -| 모든 객체를 위한 관리자 UI | 객체마다 구축 | 생성됨 | -| 감사 로그 | 직접 구현 | 플러그인, 선언적 | -| 권한이 적용된 S3 파일 업로드 | 직접 구현 | 플러그인 | -| 백그라운드 작업 + 재시도 + 데드 레터 | 직접 구현 | 플러그인 | -| 멀티 테넌시 | 직접 구현(그리고 두 번은 잘못 만들 것입니다) | 내장 | -| 가장 적합한 용도 | 맞춤형 UX를 가진 공개 앱 | 속도가 우선인 내부 도구 | - -## 솔직한 트레이드오프 - -- **Retool보다 UI 자유도가 낮습니다.** Console은 여러분의 메타데이터에서 - 생성됩니다. 맞춤형 프런트엔드와 함께 사용할 수 있지만(REST API는 Console이 - 사용하는 것과 동일합니다), 손수 만든 픽셀 단위로 완벽한 UI가 필요하다면 - 직접 구축하고 ObjectOS를 백엔드로 사용하세요. -- **TypeScript 우선.** 비엔지니어가 객체를 직접 작성하지는 않습니다. - Salesforce 관리자는 UI 빌더를 클릭하는 데 익숙하지만, 여기서는 `git`입니다. -- **Salesforce보다 신생.** Salesforce는 25년간 문서화된 엣지 케이스를 - 가지고 있습니다. 우리는 수백 개를 가지고 있습니다. 프로토콜은 안정적이며, - 생태계는 성장 중입니다. -- **Apache-2.0.** 상업용 제품에 사용하고, 임베드하고, 비공개로 수정하세요. - 카피레프트의 깜짝 놀랄 일은 없습니다. 선택적 상업 지원은 별도로 - 제공됩니다. - -## 현실 점검 - -가장 작은 실용적인 ObjectOS 배포는 단일 `pnpm dev` 또는 SQLite를 사용하는 -단일 Docker 컨테이너입니다. 오늘날 프로덕션에서 가장 큰 배포는 Postgres + -S3 + Redis로 여러 지역에 걸쳐 수만 명의 내부 사용자를 서비스합니다. 둘 다 -동일한 소프트웨어입니다. - -`npx @objectstack/cli init my-app`으로 시작해서 5분 안에 결정하세요. 여러분에게 -맞지 않는다면 5분을 쓴 것뿐입니다. - -[**Quickstart 사용해보기 →**](/docs/quickstart) diff --git a/content/docs/why.mdx b/content/docs/why.mdx index d120c23..1f87e85 100644 --- a/content/docs/why.mdx +++ b/content/docs/why.mdx @@ -8,19 +8,31 @@ other doc to figure out whether ObjectOS is right for you. ## The shape of the bet -ObjectOS makes one opinionated bet: **AI writes your application's -metadata, you own the runtime that runs it.** - -You don't hand-write objects, fields, views, flows, and permissions -file-by-file. Your users describe what they need in plain language to -the built-in [AI Builder](/docs/build/ai-builder); it calls a small -set of audited tools, queues every change for human approval, and the -result is live — REST endpoints, generated screens, RBAC, audit log, -everything generated from the same metadata. - -The runtime sits in **your** VPC, on **your** database — the underlying -**ObjectStack runtime is Apache-2.0**, yours to fork. The model talks to a -sandboxed metadata API, not your data warehouse. +**The ontology is the software.** One executable business ontology. AI +writes it, the runtime runs it, agents operate it, you own it. Four +promises — and ObjectOS keeps them hosted in the browser with nothing to +install (**ObjectOS Cloud**) or self-managed on your own infrastructure +(**ObjectOS Enterprise**): + +- **Executable.** Your objects, fields, relations, actions, permissions, + flows and agent definitions are one typed, versioned definition that the + runtime runs. REST endpoints, generated screens, RBAC, the audit log and + the MCP tools are all derived from it — no code generation step, no + deploy pipeline between "described" and "live". +- **AI-writable.** You don't hand-write that definition file by file. + Describe what the business needs to the built-in + [AI Builder](/docs/build/ai-builder); it calls a small set of audited + tools, every mutation queues for human approval, and the result is a + small diff you can actually read. +- **Agent-operable.** Every object and every exposed action doubles as an + MCP tool, so agents operate the running app under the same permissions, + row-level security and audit as a person — never raw SQL, never a scraped + UI. +- **You own it.** The ontology is ordinary + [ObjectStack](https://github.com/objectstack-ai/objectstack) metadata, + Apache-2.0, and on either edition you can export it and run it on that + open-source runtime. ObjectOS Enterprise also keeps the runtime and the + database on your infrastructure. That's the whole pitch. The rest of this page is who that fits and who it doesn't. @@ -30,7 +42,8 @@ who it doesn't. - need an internal tool, admin panel, or back-office app, **and** - want the people who use it (or the AI agents acting for them) to be able to *extend* it without filing a ticket, **and** -- can't (or won't) put the data in someone else's cloud, **and** +- want it hosted and operated for you (ObjectOS Cloud) — or must run it + inside your own perimeter (ObjectOS Enterprise), **and** - don't want to rebuild auth + RBAC + audit + file uploads + jobs + webhooks for the tenth time. @@ -38,10 +51,10 @@ Common scenarios where it's a fit: | Scenario | Why it works | |---|---| -| Replacing a Retool / Appsmith app because data sovereignty came up in security review | ObjectOS runs in your VPC; data never leaves | +| Replacing a Retool / Appsmith app because data sovereignty came up in security review | ObjectOS Enterprise runs in your VPC; data never leaves | | Building a compliance / risk / vendor management tool for a regulated business | Audit log, RBAC, field security, row-level isolation are first-class — and every AI-driven change is itself an audit entry | -| Standing up an internal admin for a SaaS product | One Node process, slots in next to your existing services | -| Air-gapped or on-prem deployment for an enterprise customer | First-class deployment target, no internet egress required (BYO local model) | +| Standing up an internal admin for a SaaS product | One Node process, slots in next to your existing services — or a Cloud tenant with nothing to run | +| Air-gapped or on-prem deployment for an enterprise customer | A first-class ObjectOS Enterprise target: air-gapped licences validate offline, and the AI service can point at a local model | | Multi-tenant internal portal (several organizations, one deployment) | A walled tenancy posture puts up the per-organization isolation wall, enforced inside the runtime — an Enterprise capability, see [License & Pricing](/docs/resources/license). It separates the organizations' data and memberships, not their schema: they share one database and one metadata set | | You want your users to "vibe-code" their own extensions safely | The AI Builder + HITL approval queue + audit log are the whole point | @@ -51,8 +64,9 @@ Common scenarios where it's a fit: framework, you'll have more control. - need a pixel-perfect bespoke UI for end users → the generated UI is for admin/internal use; pair it with your own front-end via REST. -- want a no-code drag-and-drop builder for non-engineers and a hosted - cloud → use Retool, Bubble, or Airtable. ObjectOS is code-first AI-driven, self-hosted. +- want a drag-and-drop canvas for non-engineers → use Retool, Bubble, or + Airtable. ObjectOS generates its UI from the ontology; the builder is + the AI and the diff it proposes, not a canvas. - need real-time collaborative editing (Figma-style) → not what the realtime plugin solves. @@ -62,26 +76,26 @@ Common scenarios where it's a fit: | | Retool | ObjectOS | |---|---|---| -| Data location | Their cloud (or self-hosted at higher tier) | Your network, always | +| Data location | Their cloud (or self-hosted at higher tier) | ObjectOS Cloud, or your network on ObjectOS Enterprise | | UI builder | Drag-and-drop, very polished | Metadata-driven, generated; less custom | -| Pricing | Per-user, scales painfully | Self-hostable (open-source ObjectStack); ObjectOS bills AI seats only | +| Pricing | Per-user, scales painfully | AI seats only; viewers free. Free self-hosting is the open-source ObjectStack runtime | | Workflow / triggers | Their workflow engine | Declarative flows + plugins | | Backend logic | Limited to their query editor | Full TypeScript, full Node ecosystem | -| Best for | Quick dashboards on top of existing APIs | Apps that *own* their data | +| Best for | Quick dashboards on top of existing APIs | Apps whose definition you own | ### vs. Supabase / Firebase | | Supabase | ObjectOS | |---|---|---| | Setup time | ~30 seconds | ~30 seconds | -| Database | Postgres, theirs (self-host possible) | Any Postgres / MySQL / SQLite / Turso / Mongo, **yours** | +| Database | Postgres, theirs (self-host possible) | Managed on ObjectOS Cloud; any Postgres / MySQL / SQLite / Turso / Mongo, **yours**, on ObjectOS Enterprise | | Auth | Built in | Built in | | Generated APIs | PostgREST | ObjectQL-generated REST | | Admin UI | Console (basic) | Setup + Account | | RBAC | Row-level via Postgres RLS | RBAC + row-level + field-level, declarative | | Audit log | DIY | First-class | -| Vendor lock-in | Their auth + their storage + their realtime | None — every layer is a plugin | -| Best for | New apps that want a BaaS | Apps that need to own the runtime | +| Vendor lock-in | Their auth + their storage + their realtime | The ontology exports to the open-source ObjectStack runtime; every layer is a plugin | +| Best for | New apps that want a BaaS | Apps that need to own their definition — and, on Enterprise, their runtime | ### vs. Salesforce / NetSuite / ServiceNow @@ -89,9 +103,9 @@ Common scenarios where it's a fit: |---|---|---| | Data model | Objects + fields + relationships | Same | | Permissions | Profile + permission sets + sharing rules + FLS | **Same vocabulary**, declarative TypeScript | -| Per-user cost | $150-300/user/month | $0 | +| Per-user cost | $150-300/user/month | Viewers and non-AI users free; you pay for AI seats only | | Customization | Apex + Lightning + flows | TypeScript + flows | -| Where it runs | Their cloud, period | Your infrastructure | +| Where it runs | Their cloud, period | ObjectOS Cloud, or your infrastructure (ObjectOS Enterprise) | | Time to "we own it" | Months of consultant work | One afternoon | | Best for | Sales-led companies who'll pay for the ecosystem | Teams who want the model without the tax | @@ -114,25 +128,28 @@ Common scenarios where it's a fit: metadata. You can pair it with a custom front-end (the REST API is the same one the UI uses), but if you need a hand-crafted pixel- perfect UI, build it yourself and use ObjectOS as the backend. -- **TypeScript-first.** Non-engineers won't author objects directly. - Salesforce admins are used to clicking through a UI builder; here, - it's `git`. +- **TypeScript-first.** Non-engineers won't author objects directly in a + repo. Salesforce admins are used to clicking through a UI builder; here, + it's the AI Builder's diff or `git`. - **Newer than Salesforce.** Salesforce has 25 years of edge cases documented. We have a few hundred. The protocol is stable; the ecosystem is growing. -- **Open-source foundation.** The underlying ObjectStack framework is - Apache-2.0 — use it in commercial products, embed it, modify it - privately, no copyleft surprises. ObjectOS (the commercial layer) and - support subscriptions are available separately. +- **Open-source foundation, commercial product.** The underlying + ObjectStack stack is Apache-2.0 — use it in commercial products, embed + it, modify it privately, no copyleft surprises. ObjectOS itself is + commercial, in two editions, Cloud and Enterprise; there is no + open-source edition of ObjectOS. ## Reality check -The smallest viable ObjectOS deployment is a single `pnpm dev` or a -single Docker container with SQLite. The largest in production today -serves tens of thousands of internal users across multiple regions with -Postgres + S3 + Redis. Both are the same software. +The smallest ObjectOS is a Free tenant on ObjectOS Cloud; the smallest +self-managed one is a single-node container with SQLite. The largest in +production today serves tens of thousands of internal users across +multiple regions with Postgres + S3 + Redis. All of them run the same +software. -Start with `npx @objectstack/cli init my-app` and decide in 5 minutes. -If it's not for you, you've burned 5 minutes. +Start on [ObjectOS Cloud](https://www.objectos.ai), or boot the open +ObjectStack runtime with `npx @objectstack/cli init my-app`, and decide in +5 minutes. If it's not for you, you've burned 5 minutes. [**Try the Quickstart →**](/docs/quickstart) diff --git a/content/docs/why.zh-Hans.mdx b/content/docs/why.zh-Hans.mdx deleted file mode 100644 index 9b1527c..0000000 --- a/content/docs/why.zh-Hans.mdx +++ /dev/null @@ -1,112 +0,0 @@ ---- -title: 为什么选 ObjectOS -description: 老实话 —— 什么时候应该用它，什么时候不应该，以及它的不同之处。 -translation: - source_sha: ff0ca5df2635d1d00748f9f434d140c5713792157c936a7a639a6bfce552444c - guide_rev: 1 - mode: auto ---- - -这一页存在的意义是：让你不必在其他文档之间反复揣摩，就能判断 ObjectOS 是否适合你。 - -## 这个赌注的形状 - -ObjectOS 押下了一个观点鲜明的赌注：**AI 编写你应用的元数据，你拥有运行它的运行时。** - -你不再一个文件一个文件地手写对象、字段、视图、流程和权限。用户用自然语言向 Console 内置的 [AI Builder](/docs/build/ai-builder) 描述需求；它调用一小组受审计的工具，将每次变更排队等待人工审批，结果立刻上线 —— REST 端点、Console 界面、RBAC、审计日志，全部由同一份元数据生成。 - -运行时位于**你的** VPC、**你的**数据库、**你的** Apache-2.0 fork。模型只与沙箱化的元数据 API 对话，不接触你的数据仓库。 - -这就是全部主张。本页其余部分是关于谁适合、谁不适合。 - -## 如果你…… 就用 ObjectOS - -- 需要一个内部工具、管理后台或后办公应用，**且** -- 希望使用它的人（或代表他们的 AI Agent）能在不开工单的情况下*扩展*它，**且** -- 不能（或不愿）把数据放到别人的云上，**且** -- 不想第十次重建认证 + RBAC + 审计 + 文件上传 + 任务 + Webhook。 - -常见的适用场景： - -| 场景 | 为什么合适 | -|---|---| -| 因为安全评审提到数据主权而要替换 Retool / Appsmith 应用 | ObjectOS 跑在你的 VPC 里；数据从不离开 | -| 为受监管业务构建合规 / 风险 / 供应商管理工具 | 审计日志、RBAC、字段安全、行级隔离都是头等公民 —— 每次 AI 驱动的变更本身也是一条审计 | -| 为 SaaS 产品建立内部管理后台 | 一个 Node 进程，与你现有服务并列 | -| 为企业客户做气隙或本地部署 | 头等部署目标，无需出网（自带本地模型） | -| 多租户内部门户（一个运行时，多个小应用） | 按项目内核 + LRU 缓存正是为此设计 | -| 你希望用户安全地 "vibe-code" 自己的扩展 | AI Builder + HITL 审批队列 + 审计日志就是核心 | - -## 如果你…… 别用 ObjectOS - -- 在构建高流量的消费级产品 → 用传统 Web 框架，你能掌控更多。 -- 需要为终端用户打造像素级定制 UI → ObjectOS 的 Console 面向管理/内部用途；把它和你自己的前端通过 REST 配对使用。 -- 想要给非工程师用的无代码拖拽生成器 + 托管云 → 用 Retool、Bubble 或 Airtable。ObjectOS 是代码优先、AI 驱动、自托管的。 -- 需要 Figma 风格的实时协作编辑 → 不是 realtime 插件要解决的问题。 - -## 与你现在大概率在用的东西对比 - -### vs. Retool / Appsmith / Internal - -| | Retool | ObjectOS | -|---|---|---| -| 数据位置 | 他们的云（高阶可自托管） | 始终在你的网络中 | -| UI 构建器 | 拖拽，非常打磨 | 元数据驱动、自动生成；定制空间更小 | -| 价格 | 按用户计费，扩张痛苦 | 自托管，Apache-2.0 | -| 工作流 / 触发器 | 他们的工作流引擎 | 声明式流程 + 插件 | -| 后端逻辑 | 限于他们的查询编辑器 | 完整 TypeScript，完整 Node 生态 | -| 最适合 | 在现有 API 上做快速仪表盘 | *拥有自己数据*的应用 | - -### vs. Supabase / Firebase - -| | Supabase | ObjectOS | -|---|---|---| -| 启动时间 | ~30 秒 | ~30 秒 | -| 数据库 | Postgres，他们的（可自托管） | 任意 Postgres / MySQL / SQLite / Turso / Mongo，**你的** | -| 认证 | 内置 | 内置 | -| 生成的 API | PostgREST | ObjectQL 生成的 REST | -| 管理 UI | Console（基础） | Console + Account | -| RBAC | 基于 Postgres RLS 的行级 | RBAC + 行级 + 字段级，声明式 | -| 审计日志 | DIY | 头等支持 | -| 厂商锁定 | 他们的认证 + 存储 + realtime | 无 —— 每一层都是插件 | -| 最适合 | 想要 BaaS 的新应用 | 需要拥有运行时的应用 | - -### vs. Salesforce / NetSuite / ServiceNow - -| | Salesforce | ObjectOS | -|---|---|---| -| 数据模型 | 对象 + 字段 + 关系 | 一致 | -| 权限 | Profile + permission sets + sharing rules + FLS | **同样的词汇**，声明式 TypeScript | -| 每用户成本 | 150-300 美元/用户/月 | 0 美元 | -| 定制 | Apex + Lightning + flows | TypeScript + flows | -| 运行位置 | 他们的云，没得选 | 你的基础设施 | -| 到达 "归我所有" 的时间 | 几个月的咨询工作 | 一个下午 | -| 最适合 | 愿意为生态付费的销售导向公司 | 想要模型但不想交税的团队 | - -### vs. 自己拼（Next.js + Prisma + NextAuth） - -| | DIY | ObjectOS | -|---|---|---| -| 第一个 REST 端点 | 几个小时 | 60 秒 | -| 认证（邮箱 + OAuth + OIDC + Passkey + 2FA） | 数周 | 已包含 | -| 每个对象的管理 UI | 逐个构建 | 自动生成 | -| 审计日志 | DIY | 插件，声明式 | -| 带权限的 S3 文件上传 | DIY | 插件 | -| 后台任务 + 重试 + 死信 | DIY | 插件 | -| 多租户 | DIY（你会做错两次） | 内置 | -| 最适合 | 有定制 UX 的对外应用 | 速度优先的内部工具 | - -## 老实说的权衡 - -- **比 Retool 的 UI 自由度低。** Console 是从元数据生成的。你可以把它与定制前端配对（REST API 就是 Console 在用的那一个），但如果你需要手工打磨像素级 UI，那就自己写前端，把 ObjectOS 当作后端。 -- **TypeScript 优先。** 非工程师不会直接编写对象。Salesforce 管理员习惯了通过 UI 构建器点击；这里靠 `git`。 -- **比 Salesforce 年轻。** Salesforce 有 25 年的边缘案例文档。我们只有几百条。协议稳定；生态在成长。 -- **Apache-2.0。** 可用于商业产品、可嵌入、可私自修改。无 copyleft 惊喜。可选商业支持单独提供。 - -## 现实检验 - -最小可用的 ObjectOS 部署是一个 `pnpm dev` 或一个 SQLite Docker 容器。目前生产中最大的部署使用 Postgres + S3 + Redis，在多个区域为数万名内部用户提供服务。两者是同一份软件。 - -用 `npx @objectstack/cli init my-app` 启动，五分钟内做决定。如果不合适，你只花了五分钟。 - -[**试试 Quickstart →**](/docs/quickstart) diff --git a/content/docs/why.zh-Hant.mdx b/content/docs/why.zh-Hant.mdx deleted file mode 100644 index fd60824..0000000 --- a/content/docs/why.zh-Hant.mdx +++ /dev/null @@ -1,113 +0,0 @@ ---- -# @generated zh-Hant from zh-Hans -- do not edit. Edit the English source, then regenerate: pnpm --filter @objectos/docs gen:zh-hant -title: 為什麼選 ObjectOS -description: 老實話 —— 什麼時候應該用它，什麼時候不應該，以及它的不同之處。 -translation: - source_sha: ff0ca5df2635d1d00748f9f434d140c5713792157c936a7a639a6bfce552444c - guide_rev: 1 - mode: auto ---- - -這一頁存在的意義是：讓你不必在其他文件之間反覆揣摩，就能判斷 ObjectOS 是否適合你。 - -## 這個賭注的形狀 - -ObjectOS 押下了一個觀點鮮明的賭注：**AI 編寫你應用的後設資料，你擁有執行它的執行時。** - -你不再一個檔案一個檔案地手寫物件、欄位、檢視、流程和許可權。使用者用自然語言向 Console 內建的 [AI Builder](/docs/build/ai-builder) 描述需求；它呼叫一小組受審計的工具，將每次變更排隊等待人工審批，結果立刻上線 —— REST 端點、Console 介面、RBAC、審計日誌，全部由同一份後設資料生成。 - -執行時位於**你的** VPC、**你的**資料庫、**你的** Apache-2.0 fork。模型只與沙箱化的後設資料 API 對話，不接觸你的資料倉儲。 - -這就是全部主張。本頁其餘部分是關於誰適合、誰不適合。 - -## 如果你…… 就用 ObjectOS - -- 需要一個內部工具、管理後臺或後辦公應用，**且** -- 希望使用它的人（或代表他們的 AI Agent）能在不開工單的情況下*擴充套件*它，**且** -- 不能（或不願）把資料放到別人的雲上，**且** -- 不想第十次重建認證 + RBAC + 審計 + 檔案上傳 + 任務 + Webhook。 - -常見的適用場景： - -| 場景 | 為什麼合適 | -|---|---| -| 因為安全評審提到資料主權而要替換 Retool / Appsmith 應用 | ObjectOS 跑在你的 VPC 裡；資料從不離開 | -| 為受監管業務構建合規 / 風險 / 供應商管理工具 | 審計日誌、RBAC、欄位安全、行級隔離都是頭等公民 —— 每次 AI 驅動的變更本身也是一條審計 | -| 為 SaaS 產品建立內部管理後臺 | 一個 Node 程序，與你現有服務並列 | -| 為企業客戶做氣隙或本地部署 | 頭等部署目標，無需出網（自帶本地模型） | -| 多租戶內部門戶（一個執行時，多個小應用） | 按專案核心 + LRU 快取正是為此設計 | -| 你希望使用者安全地 "vibe-code" 自己的擴充套件 | AI Builder + HITL 審批佇列 + 審計日誌就是核心 | - -## 如果你…… 別用 ObjectOS - -- 在構建高流量的消費級產品 → 用傳統 Web 框架，你能掌控更多。 -- 需要為終端使用者打造畫素級定製 UI → ObjectOS 的 Console 面向管理/內部用途；把它和你自己的前端通過 REST 配對使用。 -- 想要給非工程師用的無程式碼拖拽生成器 + 託管雲 → 用 Retool、Bubble 或 Airtable。ObjectOS 是程式碼優先、AI 驅動、自託管的。 -- 需要 Figma 風格的即時協作編輯 → 不是 realtime 外掛要解決的問題。 - -## 與你現在大機率在用的東西對比 - -### vs. Retool / Appsmith / Internal - -| | Retool | ObjectOS | -|---|---|---| -| 資料位置 | 他們的雲（高階可自託管） | 始終在你的網路中 | -| UI 構建器 | 拖拽，非常打磨 | 後設資料驅動、自動生成；定製空間更小 | -| 價格 | 按使用者計費，擴張痛苦 | 自託管，Apache-2.0 | -| 工作流 / 觸發器 | 他們的工作流引擎 | 宣告式流程 + 外掛 | -| 後端邏輯 | 限於他們的查詢編輯器 | 完整 TypeScript，完整 Node 生態 | -| 最適合 | 在現有 API 上做快速儀表盤 | *擁有自己資料*的應用 | - -### vs. Supabase / Firebase - -| | Supabase | ObjectOS | -|---|---|---| -| 啟動時間 | ~30 秒 | ~30 秒 | -| 資料庫 | Postgres，他們的（可自託管） | 任意 Postgres / MySQL / SQLite / Turso / Mongo，**你的** | -| 認證 | 內建 | 內建 | -| 生成的 API | PostgREST | ObjectQL 生成的 REST | -| 管理 UI | Console（基礎） | Console + Account | -| RBAC | 基於 Postgres RLS 的行級 | RBAC + 行級 + 欄位級，宣告式 | -| 審計日誌 | DIY | 頭等支援 | -| 廠商鎖定 | 他們的認證 + 儲存 + realtime | 無 —— 每一層都是外掛 | -| 最適合 | 想要 BaaS 的新應用 | 需要擁有執行時的應用 | - -### vs. Salesforce / NetSuite / ServiceNow - -| | Salesforce | ObjectOS | -|---|---|---| -| 資料模型 | 物件 + 欄位 + 關係 | 一致 | -| 許可權 | Profile + permission sets + sharing rules + FLS | **同樣的詞彙**，宣告式 TypeScript | -| 每使用者成本 | 150-300 美元/使用者/月 | 0 美元 | -| 定製 | Apex + Lightning + flows | TypeScript + flows | -| 執行位置 | 他們的雲，沒得選 | 你的基礎設施 | -| 到達 "歸我所有" 的時間 | 幾個月的諮詢工作 | 一個下午 | -| 最適合 | 願意為生態付費的銷售導向公司 | 想要模型但不想交稅的團隊 | - -### vs. 自己拼（Next.js + Prisma + NextAuth） - -| | DIY | ObjectOS | -|---|---|---| -| 第一個 REST 端點 | 幾個小時 | 60 秒 | -| 認證（郵箱 + OAuth + OIDC + Passkey + 2FA） | 數週 | 已包含 | -| 每個物件的管理 UI | 逐個構建 | 自動生成 | -| 審計日誌 | DIY | 外掛，宣告式 | -| 帶許可權的 S3 檔案上傳 | DIY | 外掛 | -| 後臺任務 + 重試 + 死信 | DIY | 外掛 | -| 多租戶 | DIY（你會做錯兩次） | 內建 | -| 最適合 | 有定製 UX 的對外應用 | 速度優先的內部工具 | - -## 老實說的權衡 - -- **比 Retool 的 UI 自由度低。** Console 是從後設資料生成的。你可以把它與定製前端配對（REST API 就是 Console 在用的那一個），但如果你需要手工打磨畫素級 UI，那就自己寫前端，把 ObjectOS 當作後端。 -- **TypeScript 優先。** 非工程師不會直接編寫物件。Salesforce 管理員習慣了通過 UI 構建器點選；這裡靠 `git`。 -- **比 Salesforce 年輕。** Salesforce 有 25 年的邊緣案例文件。我們只有幾百條。協議穩定；生態在成長。 -- **Apache-2.0。** 可用於商業產品、可嵌入、可私自修改。無 copyleft 驚喜。可選商業支援單獨提供。 - -## 現實檢驗 - -最小可用的 ObjectOS 部署是一個 `pnpm dev` 或一個 SQLite Docker 容器。目前生產中最大的部署使用 Postgres + S3 + Redis，在多個區域為數萬名內部使用者提供服務。兩者是同一份軟體。 - -用 `npx @objectstack/cli init my-app` 啟動，五分鐘內做決定。如果不合適，你只花了五分鐘。 - -[**試試 Quickstart →**](/docs/quickstart) diff --git a/package.json b/package.json index 5fc3667..5279584 100644 --- a/package.json +++ b/package.json @@ -15,7 +15,8 @@ "clean": "turbo run clean && rm -rf node_modules", "docs:dev": "turbo run dev --filter=@objectos/docs", "docs:build": "turbo run build --filter=@objectos/docs", - "check:locale-surface": "node .github/scripts/check-locale-surface.mjs" + "check:locale-surface": "node .github/scripts/check-locale-surface.mjs", + "check:positioning": "node .github/scripts/check-positioning.mjs" }, "devDependencies": { "turbo": "^2.5.0", diff --git a/tools/ci-scripts/run-self-tests.mjs b/tools/ci-scripts/run-self-tests.mjs index a840835..c0d9679 100644 --- a/tools/ci-scripts/run-self-tests.mjs +++ b/tools/ci-scripts/run-self-tests.mjs @@ -82,6 +82,14 @@ * still refuse a bundle whose prerender cache is incomplete — the bundle shape * that publishes a Worker returning 404 for every page while the deploy step * exits 0. + * + * `check-positioning.mjs` is listed for its `--self-test` only (#171). Its gate + * mode reads `apps/docs/.next/` the way `check-locale-surface.mjs` does and is + * a `ci.yml` step after the build for the same reason. Its fixtures are inline + * strings, one good and one bad per rule; they prove that each of its three + * rules — the copies of the positioning constant agreeing with it, the one + * brand spelling in shipped output, the stale sentences staying gone — can + * still go red, and stays silent on the shapes the rulings on #171 accepted. */ import { readFileSync, readdirSync, existsSync } from 'node:fs'; @@ -103,6 +111,7 @@ const SELF_TESTED = [ 'smoke-docs.mjs', 'check-prerender-cache.mjs', 'check-translation-ownership.mjs', + 'check-positioning.mjs', ]; /**