Twenty 应用怎么管理本地 Docker 服务器、版本固定与元数据同步恢复？

Twenty 应用怎么管理本地 Docker 服务器、版本固定与元数据同步恢复？

【免费下载链接】twentyThe open alternative to Salesforce, designed for AI.项目地址: https://gitcode.com/GitHub_Trending/tw/twenty

开发 Twenty 应用时，本地循环依赖三件事：一个可控的本地 Docker 服务器（yarn twenty docker:*管理）、与服务器版本匹配的固定策略（engines.twenty）、以及应用元数据同步出错后的恢复手段（apply/plan/ 恢复阶梯）。本文覆盖这条完整路径：启动并管理本地服务器、固定并升级服务器版本、读取同步输出、以及元数据漂移时按顺序恢复。

适用前提（来自官方 Quick Start 文档）：

• Node.js 24.5+（engines.node: ^24.5.0），用node -v检查
• Yarn 4，通过 Corepack 启用：corepack enable
• Docker 已安装并运行，本地服务器就是一个完整的 Twenty 实例（UI、GraphQL API、PostgreSQL），以 Docker 容器形式运行

启动和管理本地 Docker 服务器

在应用项目目录下，用yarn twenty docker:*控制本地容器：

数据通过两个 Docker 卷在重启间保留：twenty-app-dev-data存 PostgreSQL 数据，twenty-app-dev-storage存文件。只有docker:reset会清除全部内容，执行前确认本地数据已不再需要。

典型的首次运行流程：scaffolder（npx create-twenty-app@latest my-twenty-app）在 Docker 运行时会自动拉取twentycrm/twenty-app-dev镜像、在端口2020启动，并将 CLI 认证到预置的演示工作区（tim@apple.dev），无需登录。如果 Docker 未运行，scaffolder 会提示你正确的启动命令；Docker 就绪后可直接yarn twenty docker:start恢复，不必重新 scaffold。

可选：并行测试实例。给任意docker:*命令加--test，可以管理一个完全隔离的第二实例，用于集成测试或实验而不影响主开发数据：

yarn twenty docker:start --test # 默认端口 2021 yarn twenty docker:stop --test yarn twenty docker:status --test yarn twenty docker:logs --test yarn twenty docker:reset --test yarn twenty docker:upgrade --test

测试实例拥有独立的容器（twenty-app-dev-test）、卷（twenty-app-dev-test-data、twenty-app-dev-test-storage）和配置，可与主实例并行运行互不冲突。--test可与--port组合覆盖默认端口 2021。

可选：跳过 scaffolder 的手动接入。如果是在已有项目中引入 SDK：

yarn add twenty-sdk twenty-client-sdk

并在package.json添加脚本：

{ "scripts": { "twenty": "twenty" } }

之后yarn twenty dev、yarn twenty docker:start等命令即可使用。官方提醒：不要全局安装twenty-sdk，按项目固定版本，让每个应用使用自己的版本。

固定服务器版本

不传版本号时，docker:start从应用package.json的engines.twenty范围解析版本——这是服务器在安装应用时校验的同一个范围。它启动满足范围的最新已发布twenty-app-dev镜像；该字段缺失或没有已发布版本匹配时回退到latest：

{ "engines": { "twenty": ">=2.2.0" } }

范围是标准 semver range，常见写法（来自 Publishing 文档）：

单次运行时可用显式版本覆盖范围：yarn twenty docker:start 2.3.0。如果已有一个不同版本的容器存在，docker:start会就地升级它（重建容器但保留数据卷）。

engines.twenty同时也是发布路径上的硬约束：deploy（tarball 上传）或 install 时，若目标服务器版本不满足范围，会被拒绝并报SERVER_VERSION_INCOMPATIBLE错误，消息中会同时给出要求的范围和服务器实际版本；未设置该字段则任意服务器版本都接受；服务器没有配置APP_VERSION时跳过检查。

升级服务器镜像。yarn twenty docker:upgrade拉取新镜像、比较 digest，只有真正变化时才重建容器。卷被保留，只替换容器；如果拉取了新镜像且容器正在运行，升级会自动启动新容器，之后运行yarn twenty docker:start等待其变为健康状态。

yarn twenty docker:upgrade # 升级到最新 yarn twenty docker:upgrade 2.2.0 # 升级到指定版本

用yarn twenty docker:status验证实际运行版本——它显示的是容器内固化的APP_VERSION。

元数据同步：命令选择与输出解读

本地开发围绕syncing展开：CLI 重建 manifest，服务器只应用它与工作区中已有元数据之间的差异。

本地同步（yarn twenty dev）就地更新 manifest，不需要修改package.json的version。严格递增的版本规则（deploy 时的VERSION_ALREADY_EXISTS、install 时的APP_ALREADY_INSTALLED/CANNOT_DOWNGRADE_APPLICATION）只作用于app:publish/app:install这条发布路径。如果你发现自己要靠 bump 版本来测试本地变更，说明误用了发布路径而不是开发循环。

每次同步都会以 Terraform 风格打印它应用（或plan下将要应用）的元数据变更——每个实体一个块，最后是汇总行。文档示例输出：

# objectMetadata "rocket" will be created + icon = "IconRocket" + labelSingular = "Rocket" + ... # fieldMetadata "launchedAt" will be updated ~ isNullable = false -> true Plan: 2 to add, 1 to change, 1 to destroy. ✓ Synced My App (4 files)

这是第一层诊断：它精确告诉你哪些对象、字段、布局发生了变化，可以在看 UI 之前确认同步做了预期中的事。破坏性变更（to destroy）会列出将删除什么（例如objectMetadata "auditNote" — drops the table and all its rows），并要求交互确认，脚本中可用--force。

单次实体同步失败时，错误信息会点名出问题的实体及其universalIdentifier，例如：

Migration action 'create' for 'fieldMetadata' (universalIdentifier: 2020...4337) failed

用这个标识符在 manifest（必要时在工作区）中定位实体，而不是猜测哪个实体冲突。

预览（plan）。yarn twenty plan构建 manifest、向服务器请求迁移计划并打印——不应用任何东西。它不写入任何内容（无元数据迁移、无应用记录更新、无默认角色/标签页变更、无 API client 生成），且返回真实同步会应用的同一份 diff，适合在高风险变更、审查 AI 生成的变更、或"出现意外变更就应失败的脚本"之前使用。注意 plan 只预览元数据变更；对从未同步过应用也有效——服务器会针对空应用评估 manifest，因此 plan 会列出源码将要创建的一切。

元数据漂移时的恢复阶梯

本地元数据看起来不对时，按以下顺序升级，解除阻塞即停。每一步比上一步破坏性更大：

1. 重新同步。再跑一次yarn twenty apply。同步是幂等的——干净 manifest 重跑安全，常能解决瞬时故障。
2. 预览 plan。跑yarn twenty plan，在不应用的前提下看到下一次同步打算改什么。
3. 读懂点名错误。记下同步失败消息中的元数据类型和universalIdentifier，在 manifest 中定位该实体。冲突通常指向重复或复用的标识符。
4. 卸载再装。yarn twenty app:uninstall，然后重新同步（yarn twenty dev）。这从干净状态重建应用元数据，同时保持工作区其余部分完整。
5. 完整重置（最后手段）。yarn twenty docker:reset，然后重新灌数据并重新同步。

docker:reset会删除本地实例的所有数据——每个工作区、记录和应用。只有前面步骤都失败后才用它。

避免对同一工作区并发同步。同步应用的是元数据迁移。对同一工作区同时跑多个 sync、deploy 或 install（例如多个终端或并行迭代的 AI agent）可能交错这些迁移，把元数据留在部分应用的状态。服务器已按工作区串行化同步以防此问题，但敏感元数据操作仍应通过单一进程走，多 agent 编排时应把 sync/deploy/install 调用排进一个队列，保证同时只有一个在跑。

区分故障类型与验证

元数据 diff 和点名错误能帮你定位故障属于哪一类（来自 Syncing & recovery 文档）：

• Manifest build error— CLI 在同步前就失败（MANIFEST_BUILD_FAILED、TYPECHECK_FAILED）；修应用源码。
• Registration ownership error— 同步被拒绝，因为应用的universalIdentifier属于另一个工作区、或不属于任何工作区；详见 Registration ownership。从 marketplace 目录导入的应用初始无主，需要先 claim。
• Sync / migration error— build 成功但应用 diff 失败，消息中点名实体和universalIdentifier；修冲突的元数据。
• Dependencies size error— 同步或安装因应用生产dependencies过大而失败（LOGIC_FUNCTION_DEPENDENCIES_SIZE_EXCEEDED）；把逻辑函数运行时不导入的包（UI 库、开发工具）移到devDependencies。
• App code runtime error— 同步成功但逻辑函数或组件运行时行为异常；查看函数日志（CLI 文档中的yarn twenty dev:function:logs）。
• Local instance state— 以上都不是但工作区仍看起来不对；走恢复阶梯。

首跑阶段的常见问题（来自 Troubleshooting）：Docker 未运行时docker:start的报错会给出你操作系统的正确启动命令；Node 版本错误用node -v检查；twenty-sdk在 v2.8.0 起从dependencies移到了devDependencies，升级后报错属正常变更；twenty dev:build警告twenty-client-sdk位于dependencies下时，应把它移到devDependencies（运行时由 Twenty 提供）。

验证方式汇总：

• 服务器状态：yarn twenty docker:status显示 URL、APP_VERSION和登录凭据，是确认版本固定与升级结果的直接依据。
• 同步结果：以同步输出的Plan: N to add, N to change, N to destroy.汇总行和逐实体 diff 为准；UI 侧打开http://localhost:2020/settings/applications#developer，应用应出现在Your Apps下。
• 恢复是否成功：阶梯中任意一步之后，yarn twenty apply重新干净退出（退出码 0）且 plan 输出符合预期。

边界与下一步

• yarn twenty pull仍是实验性：只覆盖应用的一部分，输出格式可能随版本变化，且会覆盖它拉取的实体对应的文件，暂不恢复翻译；运行前提交你的工作，并审查 diff。
• 遇到元数据错误仍无法解决时，官方建议提交 issue，附上失败的迁移消息（含元数据类型和universalIdentifier）、同步的Metadata changes输出和运行过的命令。
• 服务器管理之外的完整 CLI 参考（exec、logs、remotes 等）见 CLI；发布路径（tarball 部署、npm 发布、CI 中的TWENTY_VERSION固定）见 Publishing。

【免费下载链接】twentyThe open alternative to Salesforce, designed for AI.项目地址: https://gitcode.com/GitHub_Trending/tw/twenty