分离内容仓库

介绍

TinaCloud 允许你将一个项目分成两个 GitHub 仓库：一个包含你的 Tina 架构和应用代码的 生成器仓库，以及一个包含你的编辑文件（markdown / MDX 内容和媒体）的 内容仓库。这两个仓库属于 同一个 TinaCloud 项目；你不需要创建两个项目并链接它们。

在本指南中：

• 生成器仓库 - 包含你的 tina/config.tsx、你的 Next.js / Astro / Remix / 等应用代码，以及在 tina/__generated__/ 下生成的工件。
• 内容仓库 - 包含你的 .md / .mdx 文件和媒体。这里没有 Tina 配置。

为什么？

你可能想要进行这种分离的几个原因：

• 解耦提交历史。 编辑者每天提交几十个小的内容编辑；工程师提交一到两次。将它们保存在不同的仓库中可以保持每个仓库的历史记录可读。
• 权限管理。 编辑者获得内容仓库的写入权限，而无需接触应用代码。
• 多站点复用。 单个内容仓库可以为多个生成器提供支持（区域站点、面向合作伙伴的变体、文档 + 营销）。

要求

• 一个 TinaCloud 账户。
• 你控制的两个 GitHub 仓库，一个用于生成器，一个用于内容。
• 在 两个 仓库的组织中安装 TinaCloud GitHub 应用（这些可能不同）。

工作原理

设置完成后，你的 TinaCloud 项目绑定到两个仓库。从编辑者的角度来看，仪表板没有任何变化；他们以往的方式编辑、保存和提交审核。在幕后：

• 架构 从生成器仓库的索引架构中加载。它从不从内容仓库读取。
• 编辑分支和拉取请求 通过 Tina 的编辑工作流在 内容仓库 上创建。
• 媒体上传 到 内容仓库。
• 搜索索引重建 在每次内容仓库推送时进行。
• CLI 在本地开发和 CI 构建期间通过 localContentPath 从兄弟内容目录读取内容。

设置一个新的 TinaCloud 项目

TinaCloud 仪表板在创建项目流程中直接显示多仓库选项。

1. 在 TinaCloud 仪表板中，点击 创建项目。
2. 像往常一样选择你的 生成器仓库。
3. 项目配置 | 打开 使用单独的内容仓库。
4. 从列表中选择 内容仓库。（如果你的内容仓库位于不同的 GitHub 组织中，先在那里安装 TinaCloud GitHub 应用；选择器只会列出应用有访问权限的仓库。）
5. 点击创建。

TinaCloud 会自动在两个仓库上安装必要的 GitHub webhook。

内容仓库 不需要 包含 tina/ 文件夹。仪表板将从头开始索引它。

设置一个现有的 TinaCloud 项目

如果你已经有一个单仓库的 TinaCloud 项目并想将其转换为多仓库：

1. 打开项目的 配置 页面。
2. 找到 内容仓库 部分。
3. 打开 使用单独的内容仓库。
4. 选择内容仓库。
5. 确认。

TinaCloud 将从头开始索引内容仓库的默认分支，并将后续的编辑工作流操作重新路由到它。你可以稍后关闭该开关以恢复到单仓库，尽管内容仓库的编辑分支将保留在内容仓库中，直到手动清理。

配置你的生成器仓库

在你的生成器仓库的 tina/config.tsx 中，添加 localContentPath 以便 CLI 在本地开发和 CI 构建期间找到你的内容文件：

import { defineConfig } from 'tinacms';

export default defineConfig({
  // ...你的现有配置
  localContentPath: '../my-content-repo',
});

路径是相对于 tina/ 文件夹解析的。最常见的布局是 在共享父目录下的兄弟仓库，两个仓库克隆到同一个文件夹中。

localContentPath 仅用于本地开发。TinaCloud 生产运行时通过 GitHub 从内容仓库读取内容，无论此设置如何；该字段由 tinacms dev 和 tinacms build 使用，以便 CLI 在内容文件未与生成器代码一起检出时定位它们。

本地开发

将两个仓库作为磁盘上的兄弟仓库检出：

parent/
├── my-generator-repo/
│   └── tina/
│       └── config.tsx
└── my-content-repo/
    └── content/
        └── posts/
            └── hello.mdx

从生成器仓库运行你的常规开发命令：

pnpm dev   # 或 npm run dev / yarn dev

Tina 的开发服务器将监视内容仓库的文件以及生成器的架构。在 my-content-repo/content/posts/hello.mdx 中编辑内容文件将热重载管理 UI；在 my-generator-repo/tina/config.tsx 中编辑将重新生成架构。生成的工件只会出现在 my-generator-repo/tina/__generated__/ 中。

什么内容存放在哪里

从旧的“两 TinaCloud 项目”模式迁移

本指南的早期版本要求你创建 两个独立的 TinaCloud 项目 并通过 tina/meta.json 文件中的 upstreamClientId 连接它们。该模式不再是推荐的设置；一个具有两个仓库绑定的单一 TinaCloud 项目取代了它。

如果你有一个遵循旧模式的现有设置，请按以下步骤迁移：

1. 选择指向你的 生成器仓库 的项目。这是你将保留的项目。
2. 打开该项目的设置，打开 使用单独的内容仓库，并选择你一直在使用的内容仓库。
3. 更新生成器仓库中的 .env，使 NEXT_PUBLIC_TINA_CLIENT_ID 和 TINA_TOKEN 引用 生成器项目 的凭据（你可能已经在这样做）。
4. 删除 内容仓库 的 TinaCloud 项目；它不再使用。
5. 可选清理：从内容仓库中删除 tina/meta.json 文件；没有东西再读取它。你还可以从内容仓库中删除 tina/__generated__/ 文件夹，如果你的先前设置将其提交在那里；这些工件现在只存在于生成器中。

路径配置注意事项

在你的 tina/config.(ts/js) 中定义集合路径时，避免设置 path: ''。Tina 期望一个相对于文件夹的路径；空字符串可能导致在创建新文档时出现错误，因为 Tina 在保存时会添加一个 /，这可能会产生无效的 GitHub 路径。

静态网站生成器兼容性

如果你使用的是 Next.js 以外的静态网站生成器（如 Astro），请确保你的内容管道忽略 生成器仓库 内的 tina/ 目录；Tina 的配置和生成文件不是内容文件，可能会在被内容集合拾取时导致解析错误。

export default defineCollection({
  schema: mySchema,
  exclude: ['tina/**/*'],
});

如果你在最新的 tinacms 版本之前设置了多仓库，你的 内容仓库 可能还有一个陈旧的 tina/ 文件夹，这是从前生成的工件写入的地方。可以安全删除；没有东西再读取它。

从内容仓库触发网站构建（可选）

使用单独的内容仓库时，你可能希望内容更新（例如来自 Tina UI）自动触发网站的构建。TinaCloud 支持通过 webhooks 开箱即用地实现这一点。

使用 TinaCloud Webhooks（推荐）

TinaCloud 可以配置为在提交内容更改时向 webhook 端点发送 POST 请求。这是触发网站重建的推荐方式。

👉 查看 webhook 功能 以获取更多详细信息。

使用 GitHub Actions 触发构建

作为使用 webhooks 的替代方案，你可以使用 GitHub Actions 触发网站构建。如果你的平台不支持构建 webhooks，或者你希望对构建过程有更多控制，这将非常有用。

示例工作流

在你的内容仓库中创建一个工作流文件（例如 .github/workflows/trigger-website-build.yml）：

name: Trigger Website Build

on:
  workflow_dispatch:
  push:
    branches:
      - '**'

jobs:
  trigger-deploy:
    runs-on: ubuntu-latest
    if: github.repository_owner == 'your-org'

    steps:
      - name: Generate a token
        id: generate-token
        uses: actions/create-github-app-token@v2
        with:
          app-id: ${{ vars.MY_APP_ID }}
          private-key: ${{ secrets.MY_APP_PRIVATE_KEY }}
          owner: your-org
          repositories: your-website-repo

      - name: Trigger website deploy
        run: |
          gh workflow run build-and-deploy.yml \
            --repo your-org/your-website-repo \
            --ref main \
            --field run_id="$GITHUB_RUN_ID" \
            --field branch_name="${GITHUB_REF#refs/heads/}"
        env:
          GH_TOKEN: ${{ steps.generate-token.outputs.token }}

先决条件

此设置需要：

• 一个具有两个仓库访问权限的 GitHub 应用。
• 在 GitHub 仓库设置中保存的令牌和应用密钥。

故障排除

• 在选择内容仓库时出现“GitHub 应用未安装在此仓库的组织上”。TinaCloud GitHub 应用必须安装在拥有仓库的 组织（或用户账户）上。如果你的生成器和内容仓库位于不同的 GitHub 组织下，请分别在每个组织上安装应用。
• 内容仓库的选择器缺少你期望看到的仓库。 GitHub 应用授予每个仓库的访问权限。打开相关组织上的 GitHub 应用设置，并授予你想使用的特定仓库的访问权限，然后刷新仪表板。
• 升级后内容仓库中存在陈旧的 tina/ 文件夹。 升级前的构建将 tina/__generated__/* 和 tina/tina-lock.json 提交到内容仓库。新模型中没有东西更新或读取这些文件。建议在单次清理提交中从内容仓库中删除。
• 内容仓库中的旧 tina/meta.json 文件。 这是旧的两项目模式的连接器。不再使用；删除它。
• 内容编辑未出现在构建中。 确认生成器仓库的 tina/config.tsx 设置了 localContentPath，并且你已将内容仓库作为磁盘上的兄弟仓库检出。