FAQ

起步

Q：试用 ObjectOS 最快的方法是什么？ A：npm i -g @objectstack/cli && os start —— 然后打开 http://localhost:3000。见 快速开始。

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。见 运行时配置。

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） 会显式列出所需迁移。请先备份 —— 见 备份与灾难恢复。

权限与多租户

Q：怎么做行级安全？ A：声明一条共享规则（声明式，类似 Salesforce），或在对象的 recordAccess 配置中声明一个 CEL 谓词。安全插件会在每次查询时注入 对应的过滤条件。见 权限。

Q：能让某些字段对特定用户不可见吗？ A：可以 —— 权限集中提供字段级安全。可按字段、按权限集设置为隐藏 或只读。在 REST、ObjectQL 与 Console 中统一生效。见 权限集。

Q：如何对接 Okta / Entra / Keycloak？ A：OIDC。在 Console → Authentication 中（或通过环境变量） 配置发现 URL 与 client id/secret。Provider 回调 URL 为 /api/v1/auth/oauth2/callback/<provider-id>。见 认证。

集成

Q：可以发送 webhook 吗？ A：可以 —— 在 requires 中启用 webhooks。ObjectOS 使用持久化 outbox + HMAC-SHA256 签名。见 Webhooks。

Q：可以集成 Zapier / Make / n8n 吗？ A：可以 —— 出站走 webhook，入站走 REST API + API key。主流 iPaaS 的原生连接器在路线图中。

Q：AI 智能体能调用我的 ObjectOS 吗？ A：可以，通过 MCP（@objectstack/plugin-mcp-server） —— 把对象与 action 暴露为 MCP 工具，供 Claude Desktop、IDE 或其他 MCP 客户端 使用。见 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。见 生产就绪。

Q：ObjectOS 有状态页吗？ A：自托管部署的状态由你自己负责 —— 把 /health 接到监控上。 托管服务请见 status.objectstack.ai。

Q：应该监控哪些指标？ A：5xx 率、p95 时延、认证失败率、内核缓存未命中率、队列深度。 最小化 Prometheus 示例见 可观测性。

Q：怎么做备份？ A：备份 数据库 与 存储 bucket —— 它们承载所有客户数据。 ObjectOS 自身是无状态的。见 备份。

计费与法务

Q：ObjectOS 真的免费吗？ A：是的。Apache-2.0。没有席位计费、没有用量层级、没有许可证服务器。

Q：可以在我对外销售的商业产品里使用 ObjectOS 吗？ A：可以。Apache-2.0 允许商用。见 许可证。

Q：你们收集遥测吗？ A：不收集。除非你自己配置（OIDC、邮件、AI、webhook），否则无任何 出站调用。见 安全与合规。

Q：ObjectOS 是否符合 SOC 2 / ISO 27001 / HIPAA / GDPR？ A：ObjectOS 提供所有框架都需要的原语（RBAC、审计、加密就绪、 数据驻留）。认证属于你的部署，而不是这个二进制本身。许多 ObjectOS 部署都已获得认证。见 安全与合规。

卡住了怎么办

Q：出问题了，从哪儿入手？ A：os doctor。它能独立处理 80% 的错误配置。之后再看 排错。

Q：在哪里报 bug？ A：GitHub Issues。 附上 os doctor 的输出。安全问题： security@objectstack.ai。

Q：在哪里能获得真人帮助？ A：GitHub Discussions、 社区 Discord，或商业支持联系 sales@objectstack.ai。