From 247c4991b5907de55acdaee9841b697af96bb658 Mon Sep 17 00:00:00 2001 From: Cheese Date: Sat, 18 Jul 2026 01:41:33 +0800 Subject: [PATCH 1/4] docs: add Chinese tdc preview documentation --- TOC-ai.md | 26 ++ ai/_index.md | 41 +++ .../concepts/tdc-concepts-and-architecture.md | 129 ++++++++ ai/tdc/examples/tdc-agent-sandbox-example.md | 106 ++++++ ai/tdc/examples/tdc-daily-workflow-example.md | 112 +++++++ .../tdc-git-workspace-for-agents-example.md | 83 +++++ .../tdc-journal-agent-workflow-example.md | 84 +++++ .../tdc-query-sql-with-roles-example.md | 103 ++++++ ...hare-filesystem-across-machines-example.md | 100 ++++++ .../tdc-vault-agent-secrets-example.md | 97 ++++++ ai/tdc/guides/tdc-filesystem-git.md | 98 ++++++ ai/tdc/guides/tdc-filesystem-journal.md | 82 +++++ ai/tdc/guides/tdc-filesystem-vault.md | 141 ++++++++ ai/tdc/guides/tdc-filesystem.md | 301 ++++++++++++++++++ ai/tdc/guides/tdc-install-configure-update.md | 148 +++++++++ ai/tdc/guides/tdc-organization.md | 65 ++++ ai/tdc/guides/tdc-starter-database.md | 204 ++++++++++++ ai/tdc/reference/tdc-cli-reference.md | 158 +++++++++ .../tdc-configuration-and-credentials.md | 195 ++++++++++++ .../tdc-regions-security-and-limitations.md | 94 ++++++ ai/tdc/reference/tdc-troubleshooting.md | 190 +++++++++++ ai/tdc/tdc-overview.md | 72 +++++ ai/tdc/tdc-quick-start.md | 130 ++++++++ 23 files changed, 2759 insertions(+) create mode 100644 ai/tdc/concepts/tdc-concepts-and-architecture.md create mode 100644 ai/tdc/examples/tdc-agent-sandbox-example.md create mode 100644 ai/tdc/examples/tdc-daily-workflow-example.md create mode 100644 ai/tdc/examples/tdc-git-workspace-for-agents-example.md create mode 100644 ai/tdc/examples/tdc-journal-agent-workflow-example.md create mode 100644 ai/tdc/examples/tdc-query-sql-with-roles-example.md create mode 100644 ai/tdc/examples/tdc-share-filesystem-across-machines-example.md create mode 100644 ai/tdc/examples/tdc-vault-agent-secrets-example.md create mode 100644 ai/tdc/guides/tdc-filesystem-git.md create mode 100644 ai/tdc/guides/tdc-filesystem-journal.md create mode 100644 ai/tdc/guides/tdc-filesystem-vault.md create mode 100644 ai/tdc/guides/tdc-filesystem.md create mode 100644 ai/tdc/guides/tdc-install-configure-update.md create mode 100644 ai/tdc/guides/tdc-organization.md create mode 100644 ai/tdc/guides/tdc-starter-database.md create mode 100644 ai/tdc/reference/tdc-cli-reference.md create mode 100644 ai/tdc/reference/tdc-configuration-and-credentials.md create mode 100644 ai/tdc/reference/tdc-regions-security-and-limitations.md create mode 100644 ai/tdc/reference/tdc-troubleshooting.md create mode 100644 ai/tdc/tdc-overview.md create mode 100644 ai/tdc/tdc-quick-start.md diff --git a/TOC-ai.md b/TOC-ai.md index 098447fd04fd..a10c4142f61e 100644 --- a/TOC-ai.md +++ b/TOC-ai.md @@ -7,10 +7,15 @@ - [使用 Python 快速上手](/ai/quickstart-via-python.md) - [使用 SQL 快速上手](/ai/quickstart-via-sql.md) +- TiDB Cloud CLI (tdc) (Preview) + - [概览](/ai/tdc/tdc-overview.md) + - [快速开始](/ai/tdc/tdc-quick-start.md) ## 基础概念 - [向量搜索](/ai/concepts/vector-search-overview.md) +- TiDB Cloud CLI (tdc) (Preview) + - [概念与架构](/ai/tdc/concepts/tdc-concepts-and-architecture.md) ## 使用指南 @@ -30,6 +35,14 @@ - [Join 查询](/ai/guides/join-queries.md) - [Raw SQL 查询](/ai/guides/raw-queries.md) - [事务](/ai/guides/transactions.md) +- TiDB Cloud CLI (tdc) (Preview) + - [安装、配置和更新 tdc](/ai/tdc/guides/tdc-install-configure-update.md) + - [组织](/ai/tdc/guides/tdc-organization.md) + - [Starter 数据库](/ai/tdc/guides/tdc-starter-database.md) + - [文件系统](/ai/tdc/guides/tdc-filesystem.md) + - [文件系统 Git](/ai/tdc/guides/tdc-filesystem-git.md) + - [文件系统 Journal](/ai/tdc/guides/tdc-filesystem-journal.md) + - [文件系统 Vault](/ai/tdc/guides/tdc-filesystem-vault.md) ## 代码示例 @@ -44,6 +57,14 @@ - [RAG 应用](/ai/examples/rag-with-pytidb.md) - [对话记忆](/ai/examples/memory-with-pytidb.md) - [文本转 SQL](/ai/examples/text2sql-with-pytidb.md) +- TiDB Cloud CLI (tdc) (Preview) + - [Agent 沙箱](/ai/tdc/examples/tdc-agent-sandbox-example.md) + - [日常工作流](/ai/tdc/examples/tdc-daily-workflow-example.md) + - [使用不同角色查询 SQL](/ai/tdc/examples/tdc-query-sql-with-roles-example.md) + - [在多台机器间共享文件系统](/ai/tdc/examples/tdc-share-filesystem-across-machines-example.md) + - [为 Agent 准备 Git 工作区](/ai/tdc/examples/tdc-git-workspace-for-agents-example.md) + - [记录 Agent 工作流](/ai/tdc/examples/tdc-journal-agent-workflow-example.md) + - [向 Agent 委派 Vault 密钥](/ai/tdc/examples/tdc-vault-agent-secrets-example.md) ## 集成指南 @@ -84,3 +105,8 @@ - [性能调优](/ai/reference/vector-search-improve-performance.md) - [限制](/ai/reference/vector-search-limitations.md) - [更新记录](/ai/reference/vector-search-changelogs.md) +- TiDB Cloud CLI (tdc) (Preview) + - [CLI 参考](/ai/tdc/reference/tdc-cli-reference.md) + - [配置与凭证](/ai/tdc/reference/tdc-configuration-and-credentials.md) + - [区域、安全与限制](/ai/tdc/reference/tdc-regions-security-and-limitations.md) + - [故障排查](/ai/tdc/reference/tdc-troubleshooting.md) diff --git a/ai/_index.md b/ai/_index.md index 2650fae9956b..a85d05c3c546 100644 --- a/ai/_index.md +++ b/ai/_index.md @@ -16,6 +16,13 @@ TiDB 是面向 AI 应用的分布式 SQL 数据库，支持向量搜索、全文 | [使用 Python 快速上手](/ai/quickstart-via-python.md) | 使用 Python 在几分钟内构建你的第一个基于 TiDB 的 AI 应用。 | | [使用 SQL 快速上手](/ai/quickstart-via-sql.md) | 使用 SQL 快速开始向量搜索。 | +### TiDB Cloud CLI (tdc) (Preview) + +| 文档 | 描述 | +| --- | --- | +| [tdc 概览](/ai/tdc/tdc-overview.md) | 了解 tdc 管理的资源，以及它如何使用随附的文件系统 companion。 | +| [快速开始使用 tdc](/ai/tdc/tdc-quick-start.md) | 安装并配置 tdc，然后完成第一次数据库或文件系统操作。 | + ## 基础概念 了解 TiDB AI 搜索的基础概念。 @@ -23,6 +30,7 @@ TiDB 是面向 AI 应用的分布式 SQL 数据库，支持向量搜索、全文 | 文档 | 描述 | | --- | --- | | [向量搜索](/ai/concepts/vector-search-overview.md) | 向量搜索的全面概述，包括概念、工作原理和应用场景。 | +| [tdc 概念与架构 (Preview)](/ai/tdc/concepts/tdc-concepts-and-architecture.md) | 了解 profile、地域、凭证、SQL 角色、文件系统以及 Drive9 companion 边界。 | ## 使用指南 @@ -39,6 +47,18 @@ TiDB 是面向 AI 应用的分布式 SQL 数据库，支持向量搜索、全文 | [Auto Embedding（自动生成向量）](/ai/guides/auto-embedding.md) | 数据插入时自动生成嵌入向量。 | | [过滤](/ai/guides/filtering.md) | 通过元信息条件过滤搜索结果。 | +### TiDB Cloud CLI (tdc) (Preview) + +| 文档 | 描述 | +| --- | --- | +| [安装、配置和更新 tdc](/ai/tdc/guides/tdc-install-configure-update.md) | 安装发布版二进制文件、配置 profile、更新和卸载 tdc。 | +| [组织](/ai/tdc/guides/tdc-organization.md) | 列出项目并了解虚拟项目的选择方式。 | +| [Starter 数据库](/ai/tdc/guides/tdc-starter-database.md) | 管理集群、分支、SQL 用户、连接字符串以及 SQL 执行。 | +| [文件系统](/ai/tdc/guides/tdc-filesystem.md) | 管理文件系统资源、数据、layer、打包以及 FUSE 或 WebDAV 挂载。 | +| [文件系统 Git](/ai/tdc/guides/tdc-filesystem-git.md) | 克隆、hydrate 并管理关联的 Git worktree。 | +| [文件系统 Journal](/ai/tdc/guides/tdc-filesystem-journal.md) | 记录、搜索并验证仅追加的工作流事件。 | +| [文件系统 Vault](/ai/tdc/guides/tdc-filesystem-vault.md) | 存储密钥、委派访问、审计、注入并挂载只读 Vault。 | + ## 代码示例 完整代码示例和演示，展示 TiDB 的 AI 能力。 @@ -52,6 +72,18 @@ TiDB 是面向 AI 应用的分布式 SQL 数据库，支持向量搜索、全文 | [对话记忆](/ai/examples/memory-with-pytidb.md) | 为 AI agent 和聊天机器人提供持久 memory。 | | [文本转 SQL](/ai/examples/text2sql-with-pytidb.md) | 将自然语言转换为 SQL 查询。 | +### TiDB Cloud CLI (tdc) (Preview) + +| 文档 | 描述 | +| --- | --- | +| [Agent 沙箱](/ai/tdc/examples/tdc-agent-sandbox-example.md) | 在不提供 TiDB Cloud API 密钥的情况下，让干净的沙箱访问文件系统。 | +| [日常工作流](/ai/tdc/examples/tdc-daily-workflow-example.md) | 按常规运维流程管理一个 Starter 集群和文件系统。 | +| [使用不同角色查询 SQL](/ai/tdc/examples/tdc-query-sql-with-roles-example.md) | 显式使用只读、读写和管理员 SQL 角色。 | +| [在多台机器间共享文件系统](/ai/tdc/examples/tdc-share-filesystem-across-machines-example.md) | 安全传递 owner token，并验证多台机器间的数据可见性。 | +| [为 Agent 准备 Git 工作区](/ai/tdc/examples/tdc-git-workspace-for-agents-example.md) | 准备已挂载的 Git 工作区和隔离的关联 worktree。 | +| [记录 Agent 工作流](/ai/tdc/examples/tdc-journal-agent-workflow-example.md) | 记录结构化事件并验证其哈希链。 | +| [向 Agent 委派 Vault 密钥](/ai/tdc/examples/tdc-vault-agent-secrets-example.md) | 向 Agent 临时授予一个密钥字段的访问权限。 | + ## 集成指南 将 TiDB 集成到主流 AI framework、嵌入提供商和开发工具中。 @@ -75,3 +107,12 @@ TiDB AI 与向量搜索特性的技术参考文档。 | [向量搜索索引](/ai/reference/vector-search-index.md) | 创建和管理向量索引以提升性能。 | | [性能调优](/ai/reference/vector-search-improve-performance.md) | 优化向量搜索性能。 | | [限制](/ai/reference/vector-search-limitations.md) | 当前的限制与约束。 | + +### TiDB Cloud CLI (tdc) (Preview) + +| 文档 | 描述 | +| --- | --- | +| [CLI 参考](/ai/tdc/reference/tdc-cli-reference.md) | 全局参数、输出、查询、dry run、帮助、错误和别名。 | +| [配置与凭证](/ai/tdc/reference/tdc-configuration-and-credentials.md) | Profile、优先级、本地状态、凭证、挂载定位文件和日志。 | +| [区域、安全与限制](/ai/tdc/reference/tdc-regions-security-and-limitations.md) | 部署区域、认证边界、平台、持久性和预览阶段限制。 | +| [故障排查](/ai/tdc/reference/tdc-troubleshooting.md) | 排查认证、配额、SQL、companion、文件系统选择和挂载故障。 | diff --git a/ai/tdc/concepts/tdc-concepts-and-architecture.md b/ai/tdc/concepts/tdc-concepts-and-architecture.md new file mode 100644 index 000000000000..4490aebc4956 --- /dev/null +++ b/ai/tdc/concepts/tdc-concepts-and-architecture.md @@ -0,0 +1,129 @@ +--- +title: tdc 概念与架构 +summary: 了解 tdc profile、region、凭证、SQL 角色、文件系统资源、本地状态和内置的 Drive9 companion。 +--- + +# tdc 概念与架构 + +本文介绍使用 tdc 管理 TiDB Cloud Starter 和 TiDB Cloud 文件系统所需的核心概念。 + +> **注意：** +> +> tdc 当前处于预览（Preview）阶段，其功能和命令行界面可能会发生变更，恕不另行通知。 + +## 命令模型 + +tdc 使用 service 名词和显式 operation 名称： + +```text +tdc db create-db-cluster +tdc fs copy-file +tdc fs-git clone-git-workspace +``` + +命令树最多两级。完整且清晰的命令与参数名称，让日志和 Agent 生成的命令更容易理解。除 `tdc configure` 外，其他命令均不交互。 + +结构化命令默认返回 JSON。使用 `--output text` 获得面向终端的输出，使用 `--query` 进行 JMESPath 投影。 + +## Profile 与 region + +Profile 是包含 TiDB Cloud 部署区域、默认 virtual project 和凭证的本地命名空间。默认 profile 名为 `default`，使用 `--profile` 选择其他 profile。 + +tdc 使用一个 canonical region code 表示 placement： + +```text +aws-us-east-1 +aws-ap-southeast-1 +ali-ap-southeast-1 +``` + +前缀表示云服务提供商。全局 `--region` 可为单次命令覆盖 `TDC_REGION_CODE` 和 profile 中的 region，但不会修改已保存的配置。 + +执行 `tdc configure` 时，tdc 会调用 organization API，并要求 API key 恰好能访问一个 `type = "tidbx_virtual"` 的 project。该 project ID 会成为创建 Starter 集群时的默认值。 + +## 凭证边界 + +tdc 为不同安全边界使用不同凭证： + +| 凭证 | 用途 | 存储位置 | +| --- | --- | --- | +| TiDB Cloud API public/private key | Organization、Starter control plane、文件系统创建与删除 | `~/.tdc/credentials` | +| DB SQL 用户名/密码 | 访问一个 Starter 集群的 SQL | `~/.tdc/db_users//credentials` | +| 文件系统 owner token | 文件系统数据面、挂载、Git、Journal 和 owner Vault 操作 | `~/.tdc/fs_resources/` 下的每资源凭证或 `TDC_FS_TOKEN` | +| 委派 Vault token | 对指定 secret 字段的有限访问 | `TDC_VAULT_TOKEN` 或显式命令输入 | + +TiDB Cloud API key 不会被复用为 SQL 密码或文件系统 token。 + +## SQL 角色 + +`tdc db create-db-sql-users` 为集群创建或修复三个稳定用户： + +- `read_only`：不能修改数据的查询； +- `read_write`：常规应用与 Agent 工作； +- `admin`：DDL 和权限管理。 + +使用 `--read-only`、`--read-write` 或 `--admin` 显式选择角色。不提供角色 flag 时，默认使用 read-write。 + +## 一个 profile 管理多个文件系统 + +一个 profile 可以注册多个文件系统资源。每个资源拥有独立的配置和凭证文件。选择顺序如下： + +1. `--file-system-name`； +2. `TDC_FS_FILE_SYSTEM_NAME`； +3. profile 的默认文件系统； +4. 只有一个已注册文件系统时，选择该资源。 + +如果存在多个资源但没有选择，tdc 会报错而不是猜测。使用 `tdc fs set-default-file-system` 设置默认资源。 + +## 无配置 sandbox 访问 + +全新的 Agent 沙箱不需要运行 `tdc configure`，也不需要 TiDB Cloud API key。只需提供： + +```bash +export TDC_FS_TOKEN="" +export TDC_REGION_CODE="aws-us-east-1" +export TDC_FS_FILE_SYSTEM_NAME="workspace" +``` + +tdc 会在内存中将这些值解析为 profile 命名空间，不会写入 `[env]` profile，也不会持久化 token。 + +## 本地状态 + +tdc 管理的所有状态都位于 `~/.tdc/`： + +| 路径 | 内容 | +| --- | --- | +| `config` | 非敏感 profile、默认 project 和日志设置 | +| `credentials` | TiDB Cloud API key | +| `fs_resources/` | 按 profile 和文件系统隔离的元数据与 owner 凭证 | +| `db_users/` | 集群级 SQL 凭证 | +| `mounts/` | 后台挂载的非敏感定位信息 | +| `logs/tdc.jsonl` | 已脱敏的本地 operation log | +| `bin/` | 已安装的 `tdc` 和 `tdc-drive9` | + +Operation logging 是本地日志，不是 telemetry。设置 `TDC_LOGGING=off` 可为单个进程关闭。 + +## tdc 与 Drive9 companion + +tdc 将 [Drive9](https://github.com/mem9-ai/drive9) 安装为内部名称 `tdc-drive9`。 + +tdc 负责： + +- profile、凭证、region 和文件系统选择； +- TiDB Cloud control-plane 调用； +- JSON/text 输出、查询、错误和本地日志； +- 将 tdc 命令转换为 companion 调用。 + +Companion 负责： + +- 文件系统读写、元数据、链接、搜索和 layer； +- FUSE/WebDAV 挂载进程、缓存、drain 和 unmount； +- pack/unpack、Git workspace、Journal 和 Vault 语义。 + +后台挂载会留下长期运行的 `tdc-drive9 mount --foreground` 进程。`tdc fs drain-file-system` 要求该进程刷出待处理的 FUSE 工作，`tdc fs unmount-file-system` 停止挂载。不要在仍有未刷出的写入或需要保留的本地 overlay 数据时终止机器。 + +## 后续步骤 + +- [安装、配置和更新 tdc](/ai/tdc/guides/tdc-install-configure-update.md) +- [tdc 配置与凭证](/ai/tdc/reference/tdc-configuration-and-credentials.md) +- [tdc 区域、安全与限制](/ai/tdc/reference/tdc-regions-security-and-limitations.md) diff --git a/ai/tdc/examples/tdc-agent-sandbox-example.md b/ai/tdc/examples/tdc-agent-sandbox-example.md new file mode 100644 index 000000000000..e0ae48a8a58e --- /dev/null +++ b/ai/tdc/examples/tdc-agent-sandbox-example.md @@ -0,0 +1,106 @@ +--- +title: 在 Agent Sandbox 中使用 TiDB Cloud 文件系统 +summary: 在可信机器上创建文件系统，并让全新的 Agent 沙箱在没有 TiDB Cloud API key 的情况下访问。 +--- + +# 在 Agent Sandbox 中使用 TiDB Cloud 文件系统 + +本示例在可信机器上创建文件系统，将最小环境变量传入全新的沙箱，并在不复制 `~/.tdc/` 的情况下使用 tdc。 + +> **注意：** +> +> tdc 当前处于预览（Preview）阶段，其功能和命令行界面可能会发生变更，恕不另行通知。 + +## 前置条件 + +- 在可信机器上安装并配置 tdc。 +- 在 sandbox 中安装 tdc。Release installer 包含 `tdc-drive9`。 +- 使用 secret manager 或加密的 sandbox input 传递 token。 + +## 第 1 步：在可信机器上创建文件系统 + +```bash +export TDC_FS_TOKEN="$(tdc fs create-file-system \ + --file-system-name agent-sandbox \ + --query fs_token \ + --output text)" +``` + +记录该 profile 使用的 canonical region code，例如 `aws-us-east-1`。不要输出 token。 + +## 第 2 步：注入最小 sandbox 环境 + +通过 sandbox secret/environment 机制配置： + +```bash +TDC_FS_TOKEN= +TDC_REGION_CODE=aws-us-east-1 +TDC_FS_FILE_SYSTEM_NAME=agent-sandbox +``` + +Sandbox 不需要 `TDC_PUBLIC_KEY`、`TDC_PRIVATE_KEY`、`tdc configure`，也不需要从 `~/.tdc/` 复制文件。 + +## 第 3 步：验证直接访问 + +在 sandbox 中： + +```bash +printf 'sandbox ready\n' | tdc fs copy-file \ + --from-stdin \ + --to-remote /sandbox/status.txt + +tdc fs read-file --path /sandbox/status.txt +``` + +预期输出： + +```text +sandbox ready +``` + +## 第 4 步：可选挂载文件系统 + +在 Linux FUSE 环境中： + +```bash +mkdir -p /workspace +tdc fs mount-file-system \ + --file-system-name agent-sandbox \ + --mount-path /workspace \ + --driver fuse + +cat /workspace/sandbox/status.txt +``` + +在 macOS 上省略 `--driver fuse`，使用默认 WebDAV。只有安装 macFUSE 后才使用 FUSE。 + +挂载后，可以使用同一 FS 环境运行 `tdc fs-git`、`tdc fs-journal` 和 owner 授权的 `tdc fs-vault`。Agent 只需要指定 secret field 时，应提供 delegated `TDC_VAULT_TOKEN`，而不是 owner token。 + +## 清理 + +停止 writer。对于 FUSE： + +```bash +tdc fs drain-file-system --mount-path /workspace +tdc fs unmount-file-system --mount-path /workspace +``` + +对于 WebDAV，关闭文件并只运行 unmount。回到可信机器： + +```bash +tdc fs delete-file-system \ + --file-system-name agent-sandbox \ + --confirm-file-system-name agent-sandbox +``` + +## 安全说明 + +- 将 `TDC_FS_TOKEN` 视为 owner credential。 +- 不要将其写入镜像、代码仓库、命令行参数或操作日志。 +- 删除 sandbox 不会删除远端文件系统。 +- 如果 pending write 必须持久化，请在删除 FUSE sandbox 前执行 drain。 + +## 后续步骤 + +- [使用 tdc 管理 TiDB Cloud 文件系统](/ai/tdc/guides/tdc-filesystem.md) +- [tdc 配置与凭证](/ai/tdc/reference/tdc-configuration-and-credentials.md) diff --git a/ai/tdc/examples/tdc-daily-workflow-example.md b/ai/tdc/examples/tdc-daily-workflow-example.md new file mode 100644 index 000000000000..6ef867605def --- /dev/null +++ b/ai/tdc/examples/tdc-daily-workflow-example.md @@ -0,0 +1,112 @@ +--- +title: 执行日常 tdc Workflow +summary: 查看 project、管理 Starter 集群和文件系统、检查 tdc 更新并清理资源。 +--- + +# 执行日常 tdc Workflow + +本示例展示跨 TiDB Cloud Starter 和 TiDB Cloud 文件系统的典型 operator workflow。 + +> **注意：** +> +> tdc 当前处于预览（Preview）阶段，其功能和命令行界面可能会发生变更，恕不另行通知。 + +## 前置条件 + +- 安装 tdc 并运行 `tdc configure`。 +- 确保 organization 有一个 Starter 集群和一个文件系统的可用 quota。 + +## 第 1 步：查看 active account + +```bash +tdc organization list-projects --output text +tdc db list-db-clusters --output text +tdc fs list-file-systems --output text +``` + +## 第 2 步：创建 Starter 集群 + +```bash +tdc db create-db-cluster \ + --db-cluster-name daily-demo \ + --db-cluster-type starter \ + --dry-run + +tdc db create-db-cluster \ + --db-cluster-name daily-demo \ + --db-cluster-type starter +``` + +记录返回的 cluster ID，并等待集群 active： + +```bash +tdc db describe-db-cluster \ + --db-cluster-id "" \ + --output text +``` + +## 第 3 步：验证 SQL 访问 + +```bash +tdc db create-db-sql-users --db-cluster-id "" +tdc db execute-sql-statement \ + --db-cluster-id "" \ + --read-only \ + --sql "SELECT CURRENT_TIMESTAMP AS checked_at" \ + --output text +``` + +## 第 4 步：创建并使用文件系统 + +```bash +tdc fs create-file-system \ + --file-system-name daily-workspace \ + --set-default + +printf 'daily workflow\n' | tdc fs copy-file \ + --from-stdin \ + --to-remote /notes/today.txt + +tdc fs list-files --path /notes --output text +``` + +`/notes/today.txt` 验证所选默认资源可用。 + +## 第 5 步：检查更新 + +应用更新前 unmount active filesystem。Check 始终不修改文件： + +```bash +tdc update --check +``` + +在合适时应用更新： + +```bash +tdc update --dry-run +tdc update +``` + +## 清理 + +```bash +tdc fs delete-file-system \ + --file-system-name daily-workspace \ + --confirm-file-system-name daily-workspace + +tdc db delete-db-cluster \ + --db-cluster-id "" +``` + +删除本地 tdc 配置不能替代删除远端资源。 + +## 安全说明 + +- 不要 echo FS token 或格式化后的数据库连接字符串。 +- 自动化使用唯一 prefix，只删除本次运行创建的资源。 +- 使用 `--dry-run` 预览 destructive operation。 + +## 后续步骤 + +- [管理 TiDB Cloud Starter 数据库](/ai/tdc/guides/tdc-starter-database.md) +- [使用 tdc 管理 TiDB Cloud 文件系统](/ai/tdc/guides/tdc-filesystem.md) diff --git a/ai/tdc/examples/tdc-git-workspace-for-agents-example.md b/ai/tdc/examples/tdc-git-workspace-for-agents-example.md new file mode 100644 index 000000000000..45b117383ce7 --- /dev/null +++ b/ai/tdc/examples/tdc-git-workspace-for-agents-example.md @@ -0,0 +1,83 @@ +--- +title: 在 TiDB Cloud 文件系统中为 Agent 准备 Git Workspace +summary: 挂载文件系统、创建快速 Git workspace 与 linked worktree、正常使用 Git 并安全清理。 +--- + +# 在 TiDB Cloud 文件系统中为 Agent 准备 Git Workspace + +本示例为 agent 准备 repository 和隔离的 linked worktree。 + +> **注意：** +> +> tdc 当前处于预览（Preview）阶段，其功能和命令行界面可能会发生变更，恕不另行通知。 + +## 前置条件 + +- 选择一个文件系统。 +- 使用 Linux FUSE，或者在 macOS 安装 macFUSE 并显式使用 `--driver fuse`。 +- 安装 Git 并配置 repository authentication。 + +## 第 1 步：挂载 workspace + +```bash +mkdir -p /path/to/workspace +tdc fs mount-file-system \ + --mount-path /path/to/workspace \ + --driver fuse +``` + +## 第 2 步：Clone 并 hydrate + +```bash +tdc fs-git clone-git-workspace \ + --repo-url https://github.com/pingcap/tidb.git \ + --target-path /path/to/workspace/tidb \ + --blobless \ + --hydrate sync +``` + +验证： + +```bash +git -C /path/to/workspace/tidb status +``` + +## 第 3 步：创建 agent worktree + +```bash +tdc fs-git add-git-worktree \ + --base-path /path/to/workspace/tidb \ + --worktree-path /path/to/workspace/tidb-agent-task \ + --branch-name agent-task +``` + +Agent 可以使用普通工具： + +```bash +git -C /path/to/workspace/tidb-agent-task status +``` + +删除 worktree 前 commit 或 push 需要保留的变更。 + +## 清理 + +```bash +tdc fs-git remove-git-worktree \ + --worktree-path /path/to/workspace/tidb-agent-task + +tdc fs drain-file-system --mount-path /path/to/workspace +tdc fs unmount-file-system --mount-path /path/to/workspace +``` + +只有可以丢弃未提交变更时，才为 worktree removal 使用 `--force`。 + +## 安全与 durability 说明 + +- Repository credentials 由 Git 管理，不属于 tdc。 +- Coding-agent profile 为提高性能，将 `.git` 和 ignored generated file 保存在本地。 +- 删除临时机器前，对无法重建的本地 overlay 状态执行保留或 pack。 + +## 后续步骤 + +- [在 TiDB Cloud 文件系统中使用 Git Workspace](/ai/tdc/guides/tdc-filesystem-git.md) +- [使用 tdc 管理 TiDB Cloud 文件系统](/ai/tdc/guides/tdc-filesystem.md) diff --git a/ai/tdc/examples/tdc-journal-agent-workflow-example.md b/ai/tdc/examples/tdc-journal-agent-workflow-example.md new file mode 100644 index 000000000000..1ba70eaff133 --- /dev/null +++ b/ai/tdc/examples/tdc-journal-agent-workflow-example.md @@ -0,0 +1,84 @@ +--- +title: 使用文件系统 Journal 记录 Agent Workflow +summary: 创建 journal、追加结构化 agent event、搜索 workflow 并验证 journal hash chain。 +--- + +# 使用文件系统 Journal 记录 Agent Workflow + +本示例使用结构化、有序 event 记录 agent task，而不是向可修改文件追加未验证文本。 + +> **注意：** +> +> tdc 当前处于预览（Preview）阶段，其功能和命令行界面可能会发生变更，恕不另行通知。 + +## 前置条件 + +通过已配置 profile 或 FS token 环境选择文件系统。 + +## 第 1 步：创建 journal + +```bash +tdc fs-journal create-journal \ + --journal-id jrn-agent-demo \ + --journal-kind agent \ + --title "dependency update" \ + --actor agent:dependency-bot \ + --label repository=demo \ + --label environment=test +``` + +## 第 2 步：追加 workflow event + +```bash +tdc fs-journal append-journal-entries \ + --journal-id jrn-agent-demo \ + --idempotency-key dependency-update-start \ + --entry-json '{"type":"task.started","status":"running"}' + +tdc fs-journal append-journal-entries \ + --journal-id jrn-agent-demo \ + --entry-json '{"type":"test.finished","status":"passed","suite":"unit"}' \ + --entry-json '{"type":"task.finished","status":"completed"}' +``` + +## 第 3 步：读取和搜索 + +```bash +tdc fs-journal read-journal-entries \ + --journal-id jrn-agent-demo \ + --after-seq 0 \ + --limit 100 \ + --output text + +tdc fs-journal search-journal-entries \ + --entry-type task.finished \ + --status completed \ + --label repository=demo \ + --include-entries +``` + +有序结果应包含 start、test 和 completion event。 + +## 第 4 步：验证完整性 + +```bash +tdc fs-journal verify-journal \ + --journal-id jrn-agent-demo \ + --output text +``` + +成功结果表示已保存 sequence 和 hash chain 保持一致。 + +## 清理 + +Journal 仅追加，当前 tdc public surface 没有 delete command。请使用合成 journal ID，并将其作为 workflow evidence 保留。只有整个文件系统内容不再需要时才删除对应文件系统。 + +## 安全说明 + +- 不要在 journal payload 中放入 API key、password、包含 secret 的 SQL 或原始 file content。 +- Hash-chain verification 检测已存储 chain 的不一致，不能证明原始 event 真实。 + +## 后续步骤 + +- [使用 TiDB Cloud 文件系统 Journal](/ai/tdc/guides/tdc-filesystem-journal.md) +- [向 Agent 委派 Vault 密钥](/ai/tdc/examples/tdc-vault-agent-secrets-example.md) diff --git a/ai/tdc/examples/tdc-query-sql-with-roles-example.md b/ai/tdc/examples/tdc-query-sql-with-roles-example.md new file mode 100644 index 000000000000..80fd0f5f07e2 --- /dev/null +++ b/ai/tdc/examples/tdc-query-sql-with-roles-example.md @@ -0,0 +1,103 @@ +--- +title: 使用显式 SQL 角色查询 TiDB Cloud Starter +summary: 准备 tdc 管理的 SQL 用户，并以明确权限意图运行只读、读写和管理员 statement。 +--- + +# 使用显式 SQL 角色查询 TiDB Cloud Starter + +本示例使用全部三个 tdc 管理的 SQL 角色，同时不暴露生成的密码。 + +> **注意：** +> +> tdc 当前处于预览（Preview）阶段，其功能和命令行界面可能会发生变更，恕不另行通知。 + +## 前置条件 + +- 配置 tdc。 +- 选择一个 active Starter cluster ID。 + +## 第 1 步：准备用户 + +```bash +tdc db create-db-sql-users \ + --db-cluster-id "" +``` + +该命令可重入，会创建或修复 `read_only`、`read_write` 和 `admin` 凭证。 + +## 第 2 步：使用 admin 修改 schema + +```bash +tdc db execute-sql-statement \ + --db-cluster-id "" \ + --admin \ + --sql "CREATE DATABASE IF NOT EXISTS role_demo" + +tdc db execute-sql-statement \ + --db-cluster-id "" \ + --admin \ + --database role_demo \ + --sql "CREATE TABLE IF NOT EXISTS messages (id BIGINT PRIMARY KEY, body VARCHAR(255))" +``` + +## 第 3 步：使用 read-write 修改数据 + +```bash +tdc db execute-sql-statement \ + --db-cluster-id "" \ + --read-write \ + --database role_demo \ + --sql "INSERT INTO messages(id, body) VALUES (1, 'hello') ON DUPLICATE KEY UPDATE body = VALUES(body)" +``` + +## 第 4 步：使用 read-only 验证 + +```bash +tdc db execute-sql-statement \ + --db-cluster-id "" \ + --read-only \ + --database role_demo \ + --sql "SELECT id, body FROM messages ORDER BY id" \ + --output text +``` + +预期结果包含 ID `1` 和 body `hello`。 + +## 第 5 步：格式化连接环境 + +将输出直接写入受保护的本地文件，而不是显示： + +```bash +umask 077 +tdc db format-db-connection-string \ + --db-cluster-id "" \ + --read-only \ + --database role_demo \ + --format env \ + --env-include-database-url > .env.tidb +``` + +不要提交 `.env.tidb`。 + +## 清理 + +```bash +tdc db execute-sql-statement \ + --db-cluster-id "" \ + --admin \ + --sql "DROP DATABASE role_demo" + +rm -f .env.tidb +``` + +## 安全说明 + +- 每条 statement 使用权限最低的显式角色。 +- 每次 tdc 调用只接受一条 SQL statement。 +- 默认 transport 为 HTTPS；`--transport mysql` 是显式回退。 +- 连接字符串和环境变量输出包含凭证。 + +## 后续步骤 + +- [管理 TiDB Cloud Starter 数据库](/ai/tdc/guides/tdc-starter-database.md) +- [tdc 配置与凭证](/ai/tdc/reference/tdc-configuration-and-credentials.md) diff --git a/ai/tdc/examples/tdc-share-filesystem-across-machines-example.md b/ai/tdc/examples/tdc-share-filesystem-across-machines-example.md new file mode 100644 index 000000000000..45a96f675d9e --- /dev/null +++ b/ai/tdc/examples/tdc-share-filesystem-across-machines-example.md @@ -0,0 +1,100 @@ +--- +title: 在不同机器间共享 TiDB Cloud 文件系统 +summary: 创建一个文件系统，通过安全方式从第二台机器访问，并验证 data plane 与 mount 的可见性。 +--- + +# 在不同机器间共享 TiDB Cloud 文件系统 + +本示例在机器 A 上创建文件系统，并在不复制 tdc profile 的情况下让机器 B 访问相同数据。 + +> **注意：** +> +> tdc 当前处于预览（Preview）阶段，其功能和命令行界面可能会发生变更，恕不另行通知。 + +## 前置条件 + +- 机器 A 已配置 tdc。 +- 两台机器均已安装 tdc。 +- 你可以使用安全的 secret-transfer channel。 + +## 第 1 步：在机器 A 创建文件系统 + +```bash +export TDC_FS_TOKEN="$(tdc fs create-file-system \ + --file-system-name shared-workspace \ + --query fs_token \ + --output text)" + +printf 'from machine A\n' | tdc fs copy-file \ + --file-system-name shared-workspace \ + --from-stdin \ + --to-remote /shared/origin.txt +``` + +通过 secret manager 传输 token，同时传达 canonical region code 和文件系统名称。 + +## 第 2 步：在机器 B 以内存方式配置 + +```bash +export TDC_FS_TOKEN="" +export TDC_REGION_CODE="aws-us-east-1" +export TDC_FS_FILE_SYSTEM_NAME="shared-workspace" +``` + +无需运行 `tdc configure`。 + +## 第 3 步：验证机器 B 的直接可见性 + +```bash +tdc fs read-file --path /shared/origin.txt +printf 'from machine B\n' | tdc fs copy-file --from-stdin --to-remote /shared/second.txt +``` + +## 第 4 步：验证 mount 与 data-plane 可见性 + +```bash +mkdir -p /path/to/shared-workspace +tdc fs mount-file-system \ + --file-system-name shared-workspace \ + --mount-path /path/to/shared-workspace + +cat /path/to/shared-workspace/shared/origin.txt +printf 'written through mount\n' > /path/to/shared-workspace/shared/mounted.txt +tdc fs read-file --path /shared/mounted.txt +``` + +第一次读取证明 data-plane write 对 mount 可见；最后一次读取证明 mount write 刷出后对 data plane 可见。 + +## 清理 + +停止 writer。如果 mount 是 FUSE： + +```bash +tdc fs drain-file-system --mount-path /path/to/shared-workspace +``` + +Unmount 任一 driver： + +```bash +tdc fs unmount-file-system --mount-path /path/to/shared-workspace +unset TDC_FS_TOKEN TDC_REGION_CODE TDC_FS_FILE_SYSTEM_NAME +``` + +在机器 A 上： + +```bash +tdc fs delete-file-system \ + --file-system-name shared-workspace \ + --confirm-file-system-name shared-workspace +``` + +## 安全说明 + +- FS token 授予 owner access，应作为 secret 传输，不能放入聊天或 command history。 +- 并发 writer 可以覆盖相同路径，请在 workflow 层协调 ownership。 +- Pending FUSE write 未 drain 前不要终止机器。 + +## 后续步骤 + +- [使用 tdc 管理 TiDB Cloud 文件系统](/ai/tdc/guides/tdc-filesystem.md) +- [在 Agent Sandbox 中使用文件系统](/ai/tdc/examples/tdc-agent-sandbox-example.md) diff --git a/ai/tdc/examples/tdc-vault-agent-secrets-example.md b/ai/tdc/examples/tdc-vault-agent-secrets-example.md new file mode 100644 index 000000000000..84772f17d8ac --- /dev/null +++ b/ai/tdc/examples/tdc-vault-agent-secrets-example.md @@ -0,0 +1,97 @@ +--- +title: 向 Agent 委派文件系统 Vault Secret +summary: 保存 secret、将一个 field 委派给 agent、注入进程、审计访问并撤销 grant。 +--- + +# 向 Agent 委派文件系统 Vault Secret + +本示例在不共享文件系统 owner token 的情况下，向 agent 临时开放一个 field。 + +> **注意：** +> +> tdc 当前处于预览（Preview）阶段，其功能和命令行界面可能会发生变更，恕不另行通知。 + +## 前置条件 + +- 以 owner access 选择一个文件系统。 +- 将源 secret value 保存在受保护文件中。 + +## 第 1 步：创建 secret + +```bash +tdc fs-vault create-secret \ + --secret-name service-demo \ + --field ENDPOINT=https://service.example \ + --field API_TOKEN=@./api-token.txt +``` + +## 第 2 步：创建最小 grant + +```bash +export TDC_VAULT_TOKEN="$(tdc fs-vault create-grant \ + --agent-id example-agent \ + --scope service-demo/ENDPOINT \ + --permission read \ + --ttl 10m \ + --label-hint example \ + --token-only)" +``` + +实际 workflow 应从结构化 create result 记录返回的 grant ID。Token 被捕获而不会显示。 + +## 第 3 步：使用 delegated field + +```bash +tdc fs-vault read-secret \ + --secret-name service-demo \ + --field ENDPOINT \ + --format raw +``` + +将允许的 field 注入命令： + +```bash +tdc fs-vault run-with-secret \ + --secret-path /n/vault/service-demo \ + -- sh -c 'test -n "$ENDPOINT"' +``` + +允许的 field 存在时进程成功退出。不要使用会打印全部 environment value 的命令。 + +## 第 4 步：审计和撤销 + +```bash +tdc fs-vault list-audit-events \ + --secret-name service-demo \ + --agent-id example-agent \ + --limit 20 + +tdc fs-vault delete-grant \ + --grant-id "" \ + --revoked-by operator \ + --reason task-complete +``` + +清除本地 token： + +```bash +unset TDC_VAULT_TOKEN +``` + +## 清理 + +```bash +tdc fs-vault delete-secret --secret-name service-demo +rm -f ./api-token.txt +``` + +## 安全说明 + +- 将 grant 限制到最小 field 集合和最短实用 TTL。 +- 撤销的 token 无法授权新的读取，但不能清除进程已经读取的 value。 +- 避免使用 secret flag，因为进程列表和 shell history 可能保留它们。 + +## 后续步骤 + +- [使用 TiDB Cloud 文件系统 Vault](/ai/tdc/guides/tdc-filesystem-vault.md) +- [tdc 区域、安全与限制](/ai/tdc/reference/tdc-regions-security-and-limitations.md) diff --git a/ai/tdc/guides/tdc-filesystem-git.md b/ai/tdc/guides/tdc-filesystem-git.md new file mode 100644 index 000000000000..d987e2dcf801 --- /dev/null +++ b/ai/tdc/guides/tdc-filesystem-git.md @@ -0,0 +1,98 @@ +--- +title: 在 TiDB Cloud 文件系统中使用 Git Workspace +summary: 在已挂载的 TiDB Cloud 文件系统中 clone、hydrate 并管理 linked Git worktree。 +--- + +# 在 TiDB Cloud 文件系统中使用 Git Workspace + +`tdc fs-git` 用于加速已挂载 TiDB Cloud 文件系统路径中的 Git workspace 初始化。它增强而不是替代 Git；status、edit、add、commit、fetch 和 push 仍使用普通 `git` 命令。 + +> **注意：** +> +> tdc 当前处于预览（Preview）阶段，其功能和命令行界面可能会发生变更，恕不另行通知。 + +## 前置条件 + +- 通过 FUSE 挂载文件系统。Git workspace 加速依赖已挂载的文件系统 runtime。 +- 安装 `git`，并独立配置 repository credentials。 +- 确保 FS owner token 或所选 profile 能访问文件系统。 + +## Clone workspace + +```bash +tdc fs-git clone-git-workspace \ + --repo-url https://github.com/pingcap/tidb.git \ + --target-path /path/to/workspace/tidb +``` + +对于大型 repository，创建 blobless workspace 并同步 hydrate： + +```bash +tdc fs-git clone-git-workspace \ + --repo-url https://github.com/pingcap/tidb.git \ + --target-path /path/to/workspace/tidb \ + --blobless \ + --hydrate sync +``` + +`--hydrate` 接受 `auto`、`background`、`sync` 或 `off`。 + +## Hydrate 已有 workspace + +```bash +tdc fs-git hydrate-git-workspace \ + --target-path /path/to/workspace/tidb \ + --timeout 30m +``` + +Hydrate 为 fast 或 blobless workspace materialize clean Git object，不会丢弃 working-tree change。 + +## 添加 linked worktree + +```bash +tdc fs-git add-git-worktree \ + --base-path /path/to/workspace/tidb \ + --worktree-path /path/to/workspace/tidb-feature \ + --branch-name feature-x +``` + +使用 `--detach` 创建 detached worktree，使用 `--commit-ish` 选择起始 revision；base workspace 使用 blobless mode 时，配合 `--blobless` 和 `--hydrate`。 + +正常使用 Git： + +```bash +git -C /path/to/workspace/tidb-feature status +git -C /path/to/workspace/tidb-feature add . +git -C /path/to/workspace/tidb-feature commit -m "Implement feature x" +``` + +## 删除 worktree + +```bash +tdc fs-git remove-git-worktree \ + --worktree-path /path/to/workspace/tidb-feature +``` + +默认拒绝删除 dirty worktree。只有确定可以丢弃本地变更时才使用 `--force`： + +```bash +tdc fs-git remove-git-worktree \ + --worktree-path /path/to/workspace/tidb-feature \ + --force +``` + +## Lifecycle 建议 + +终止临时机器前： + +1. Commit 或以其他方式保留必要的 working-tree change。 +2. 删除不再需要的 linked worktree。 +3. Drain 文件系统 mount。 +4. Unmount。 + +默认 coding-agent mount profile 将 `.git` 和可重建的 generated file 保存在本地 overlay。必须跨机器保留时，请保存或 pack 本地状态。 + +## 后续步骤 + +- [为 Agent 准备 Git Workspace](/ai/tdc/examples/tdc-git-workspace-for-agents-example.md) +- [使用 tdc 管理 TiDB Cloud 文件系统](/ai/tdc/guides/tdc-filesystem.md) diff --git a/ai/tdc/guides/tdc-filesystem-journal.md b/ai/tdc/guides/tdc-filesystem-journal.md new file mode 100644 index 000000000000..3a07e38300c2 --- /dev/null +++ b/ai/tdc/guides/tdc-filesystem-journal.md @@ -0,0 +1,82 @@ +--- +title: 使用 TiDB Cloud 文件系统 Journal +summary: 创建仅追加 workflow journal，追加和搜索结构化事件，并验证 hash chain。 +--- + +# 使用 TiDB Cloud 文件系统 Journal + +`tdc fs-journal` 为 agent 和 workflow 事件提供仅追加、可验证的 ledger。与可修改文本文件不同，journal 会分配有序 sequence number、支持结构化搜索，并维护可检测篡改的 hash chain。 + +> **注意：** +> +> tdc 当前处于预览（Preview）阶段，其功能和命令行界面可能会发生变更，恕不另行通知。 + +## 前置条件 + +通过 profile 选择文件系统，或者提供 `TDC_FS_TOKEN`、`TDC_REGION_CODE` 和 `TDC_FS_FILE_SYSTEM_NAME`。 + +## 创建 journal + +```bash +tdc fs-journal create-journal \ + --journal-id jrn-demo \ + --journal-kind agent \ + --title "demo task" \ + --actor agent:tdc \ + --label env=dev +``` + +`--journal-id` 可省略，由系统生成。Label 可重复。 + +## 追加 entry + +追加一个或多个 JSON object： + +```bash +tdc fs-journal append-journal-entries \ + --journal-id jrn-demo \ + --entry-json '{"type":"task.started","status":"running"}' \ + --entry-json '{"type":"tool.called","tool":"tdc"}' +``` + +使用 `--entry-type` 为缺少 `type` 的 entry 提供默认值，并通过 `--source` 或可重复 `--subject` 添加 metadata。`--idempotency-key` 使重试行为确定；省略时由 tdc 生成。 + +Pipeline 可以从 stdin 发送 JSON Lines，或使用 `--json-array` 读取 JSON array。 + +## 读取和搜索 + +读取某个 sequence 后的 entry： + +```bash +tdc fs-journal read-journal-entries \ + --journal-id jrn-demo \ + --after-seq 0 \ + --limit 100 +``` + +跨 journal 搜索： + +```bash +tdc fs-journal search-journal-entries \ + --entry-type task.started \ + --journal-kind agent \ + --label env=dev \ + --include-entries +``` + +搜索还支持 status、actor、subject、`--since`、`--until`、`--limit` 和 pagination cursor。 + +## 验证完整性 + +```bash +tdc fs-journal verify-journal \ + --journal-id jrn-demo \ + --output text +``` + +验证会重新计算有序 hash chain，并报告 entry 是否保持内部一致。它不能证明 event payload 在最初追加时是真实的。 + +## 后续步骤 + +- [使用 Journal 记录 Agent Workflow](/ai/tdc/examples/tdc-journal-agent-workflow-example.md) +- [tdc 配置与凭证](/ai/tdc/reference/tdc-configuration-and-credentials.md) diff --git a/ai/tdc/guides/tdc-filesystem-vault.md b/ai/tdc/guides/tdc-filesystem-vault.md new file mode 100644 index 000000000000..43d077c94866 --- /dev/null +++ b/ai/tdc/guides/tdc-filesystem-vault.md @@ -0,0 +1,141 @@ +--- +title: 使用 TiDB Cloud 文件系统 Vault +summary: 保存文件系统 secret、委派有限访问、向进程注入 secret、审计访问并挂载只读 vault。 +--- + +# 使用 TiDB Cloud 文件系统 Vault + +`tdc fs-vault` 保存结构化 secret，并向 agent 委派有限、带过期时间的访问。Owner 操作使用文件系统 owner credential；委派读取使用 scope 限定到指定 secret 或 field 的 vault token。 + +> **注意：** +> +> tdc 当前处于预览（Preview）阶段，其功能和命令行界面可能会发生变更，恕不另行通知。 + +## 前置条件 + +通过 profile 或无配置 FS 环境变量选择文件系统。不要输出、记录或提交 owner token 和 delegated token。 + +## 创建和替换 secret + +使用可重复 field 创建 secret： + +```bash +tdc fs-vault create-secret \ + --secret-name db-prod \ + --field DB_URL=mysql://example \ + --field PASSWORD=@./password.txt +``` + +`key=value` 使用 literal value，`key=@file` 读取文件，`key=-` 从 stdin 读取。 + +用目录中的文件替换全部 field： + +```bash +tdc fs-vault replace-secret \ + --secret-path /n/vault/db-prod \ + --from-directory ./secret-fields +``` + +## 读取、列出和删除 + +```bash +tdc fs-vault list-secrets +tdc fs-vault read-secret --secret-name db-prod +tdc fs-vault read-secret --secret-name db-prod --field DB_URL --format raw +tdc fs-vault read-secret --secret-name db-prod --field DB_URL --format env +``` + +删除 owner 可见的 secret： + +```bash +tdc fs-vault delete-secret --secret-name db-prod +``` + +Raw 和 environment 输出包含 plaintext，只能发送给目标进程。 + +## 委派有限访问 + +创建短期 read grant 并获取 token： + +```bash +export TDC_VAULT_TOKEN="$(tdc fs-vault create-grant \ + --agent-id deploy-agent \ + --scope db-prod/DB_URL \ + --permission read \ + --ttl 10m \ + --token-only)" +``` + +Scope 可重复。`--label-hint` 可以添加非敏感 operator context。 + +使用 delegated token： + +```bash +tdc fs-vault read-secret \ + --secret-name db-prod \ + --field DB_URL \ + --format raw +``` + +优先使用 `TDC_VAULT_TOKEN`，而不是 `--vault-token`，因为命令行值可能保留在进程列表或 shell history 中。 + +## 向进程注入 secret + +```bash +tdc fs-vault run-with-secret \ + --secret-path /n/vault/db-prod \ + -- env +``` + +子进程会将 secret field 作为环境变量接收。生产环境不要使用打印完整 environment 的命令；此处使用 `env` 仅用于展示接口。 + +## 审计和撤销 + +```bash +tdc fs-vault list-audit-events \ + --secret-name db-prod \ + --agent-id deploy-agent \ + --since 24h \ + --limit 20 + +tdc fs-vault delete-grant \ + --grant-id "" \ + --revoked-by operator \ + --reason rotated +``` + +撤销会阻止新的授权操作，但无法清除进程已经读取的 secret value。 + +## 挂载只读 vault + +在支持 FUSE 的 macOS 或 Linux 上： + +```bash +mkdir -p /path/to/vault +tdc fs-vault mount-vault \ + --mount-path /path/to/vault \ + --vault-token "$TDC_VAULT_TOKEN" +``` + +Mount 是只读的。`--foreground` 使其附着在终端，`--ready-timeout` 修改后台 readiness 等待时间。 + +Unmount： + +```bash +tdc fs-vault unmount-vault --mount-path /path/to/vault +``` + +Unmount 还支持 `--timeout`、`--force` 和 `--ignore-absent`。Windows 不支持 vault mount，vault mount 需要 FUSE；直接 `read-secret` 和 `run-with-secret` 不需要 mount。 + +## 安全建议 + +- 为 agent 提供最小 field scope 和尽可能短的 TTL。 +- 优先使用 `run-with-secret`，而不是将 plaintext 写入磁盘。 +- 不要将委派 token 写入 tdc 配置或操作日志。 +- Unmount 前停止正在使用 vault mount 的进程。 +- 任务结束后撤销 grant。 + +## 后续步骤 + +- [向 Agent 委派 Vault Secret](/ai/tdc/examples/tdc-vault-agent-secrets-example.md) +- [tdc 区域、安全与限制](/ai/tdc/reference/tdc-regions-security-and-limitations.md) diff --git a/ai/tdc/guides/tdc-filesystem.md b/ai/tdc/guides/tdc-filesystem.md new file mode 100644 index 000000000000..293cba88a381 --- /dev/null +++ b/ai/tdc/guides/tdc-filesystem.md @@ -0,0 +1,301 @@ +--- +title: 使用 tdc 管理 TiDB Cloud 文件系统 +summary: 管理文件系统资源、操作文件、使用 layer 和 pack，并通过内置 Drive9 companion 挂载文件系统。 +--- + +# 使用 tdc 管理 TiDB Cloud 文件系统 + +使用 `tdc fs` 创建 TiDB Cloud 文件系统资源，并通过命令或本地挂载访问数据。 + +> **注意：** +> +> tdc 当前处于预览（Preview）阶段，其功能和命令行界面可能会发生变更，恕不另行通知。 + +## 前置条件 + +- Provision 或删除文件系统前运行 `tdc configure`。 +- 使用 release installer 安装 tdc，确保 `tdc-drive9` companion 位于 `tdc` 二进制旁。 +- 将返回的 FS owner token 作为 secret 处理。 + +Data-plane 命令也可以通过 `TDC_FS_TOKEN`、`TDC_REGION_CODE` 和 `TDC_FS_FILE_SYSTEM_NAME` 使用已有文件系统，无需 TiDB Cloud API key。 + +## 管理文件系统资源 + +创建资源并将其设为 profile 默认值： + +```bash +tdc fs create-file-system \ + --file-system-name workspace \ + --set-default +``` + +JSON 响应包含 `fs_token`。在不显示完整结果的情况下获取： + +```bash +export TDC_FS_TOKEN="$(tdc fs create-file-system \ + --file-system-name sandbox \ + --query fs_token \ + --output text)" +``` + +列出和查看本地已注册资源： + +```bash +tdc fs list-file-systems +tdc fs describe-file-system --file-system-name workspace +``` + +设置或清除 profile 默认值： + +```bash +tdc fs set-default-file-system --file-system-name workspace +tdc fs unset-default-file-system +``` + +检查所选资源和 companion： + +```bash +tdc fs check-file-system --file-system-name workspace +``` + +删除资源前，先移除或保留需要的数据： + +```bash +tdc fs delete-file-system \ + --file-system-name workspace \ + --confirm-file-system-name workspace +``` + +Create 和 delete 支持 `--dry-run`。删除需要 TiDB Cloud API key 和本地已注册资源；仅有 FS token 不能删除资源。 + +## 在多个文件系统中选择 + +一个 profile 可以拥有多个资源。选择优先级为： + +1. `--file-system-name`； +2. `TDC_FS_FILE_SYSTEM_NAME`； +3. profile 默认值； +4. 唯一的已注册资源。 + +选择存在歧义时，tdc 会失败，绝不会随机选择文件系统。 + +## 复制和读取数据 + +上传、下载和远端复制： + +```bash +tdc fs copy-file --from-local ./README.md --to-remote /workspace/README.md +tdc fs copy-file --from-remote /workspace/README.md --to-local ./README.copy.md --create-parents +tdc fs copy-file --from-remote /workspace/README.md --to-remote /archive/README.md +``` + +使用 `--overwrite` 替换已有 target，使用 `--resume` 恢复受支持的中断上传或下载，使用 `--recursive` 复制目录： + +```bash +tdc fs copy-file --from-local ./src --to-remote /workspace/src --recursive +tdc fs copy-file --from-local ./large.bin --to-remote /workspace/large.bin --resume +``` + +追加和 stream： + +```bash +tdc fs copy-file --from-local ./tail.log --to-remote /logs/app.log --append +printf 'hello\n' | tdc fs copy-file --from-stdin --to-remote /workspace/stdin.txt +tdc fs copy-file --from-remote /workspace/stdin.txt --to-stdout +``` + +上传时添加 metadata： + +```bash +tdc fs copy-file \ + --from-local ./report.md \ + --to-remote /workspace/report.md \ + --tag owner=agent \ + --tag stage=review \ + --description "agent review report" +``` + +读取完整文件或 byte range： + +```bash +tdc fs read-file --path /workspace/report.md +tdc fs read-file --path /workspace/large.bin --offset 1024 --length 4096 +``` + +## 查看和修改 namespace + +```bash +tdc fs list-files --path /workspace +tdc fs describe-file --path /workspace/report.md +tdc fs create-directory --path /workspace/archive --mode 0755 +tdc fs move-file --from-remote /workspace/report.md --to-remote /workspace/archive/report.md +tdc fs chmod-file --path /workspace/archive/report.md --mode 0600 +tdc fs create-symlink --target archive/report.md --link-path /workspace/report.link +tdc fs create-hardlink --source-path /workspace/archive/report.md --link-path /workspace/report.hard +tdc fs delete-file --path /workspace/report.link +tdc fs delete-file --path /workspace/archive --recursive +``` + +修改 namespace 的命令支持 `--dry-run`。 + +搜索内容和 metadata： + +```bash +tdc fs search-file-content --path /workspace --pattern "TODO" --limit 50 +tdc fs find-files --path /workspace --file-name-pattern "*.md" --tag stage=review +``` + +`find-files` 还支持 resource type、时间、大小和结果数量筛选。两个 search 命令均接受 `--layer-id`。 + +## 使用 layer 和 checkpoint + +Layer 在提交或丢弃之前记录 base root 上的变更： + +```bash +tdc fs create-layer \ + --base-root-path /workspace \ + --layer-name agent-task \ + --durability-mode restore-safe \ + --tag task=review +``` + +使用返回的 layer ID： + +```bash +tdc fs copy-file \ + --from-local ./proposal.md \ + --to-remote /workspace/proposal.md \ + --layer-id "" + +tdc fs list-layers +tdc fs describe-layer --layer-id "" +tdc fs diff-layer --layer-id "" +tdc fs create-layer-checkpoint \ + --layer-id "" \ + --checkpoint-id before-review \ + --label "before review" +``` + +通过 rollback 或 commit 完成 layer： + +```bash +tdc fs rollback-layer --layer-id "" +tdc fs commit-layer --layer-id "" +``` + +这两个命令表示同一任务的两种结果，实际 workflow 中不要依次执行两者。 + +## Pack 本地 overlay 状态 + +FUSE mount profile 可以将选定路径路由到本地 overlay storage。迁移到其他机器前，将这些路径 pack 到远端 archive： + +```bash +tdc fs pack-file-system --mount-path /path/to/workspace +tdc fs unpack-file-system --mount-path /path/to/workspace +``` + +没有活跃 mount 时，提供 `--local-root`、`--remote-root` 和 `--mount-profile`。`--archive-path` 选择远端 archive，可重复的 `--path` 限制 pack 内容，`--no-replace` 让 unpack 进行 merge，而不是替换 manifest path。 + +## 挂载文件系统 + +创建本地 mount path，并在后台挂载： + +```bash +mkdir -p /path/to/workspace +tdc fs mount-file-system \ + --file-system-name workspace \ + --mount-path /path/to/workspace +``` + +默认 `--driver auto` 行为取决于平台。`--remote-path` 暴露子树，`--read-only` 禁止写入，`--foreground` 让 runtime 保持附着在终端。 + +### 平台行为 + +| 平台 | `--driver auto` | 可选或必要依赖 | 说明 | +| --- | --- | --- | --- | +| macOS | WebDAV | WebDAV 无需额外依赖 | 安装 macFUSE 并选择 `--driver fuse`，获得完整 FUSE 体验 | +| Linux | FUSE | FUSE3 和 `/dev/fuse` 访问权限；显式 WebDAV 需要 `davfs2` | FUSE 支持 drain 和 cache 控制 | +| Windows | WebDAV | Windows WebClient service | Mount path 必须是 `X:` 之类的 drive letter；不支持 FUSE 和 vault mount | + +即使安装了 macFUSE，macOS 的自动选择也始终是 WebDAV。如需使用 FUSE，请从 [macFUSE 官网](https://macfuse.github.io/)安装受支持版本，完成 installer 要求的批准或重启，然后执行： + +```bash +tdc fs mount-file-system \ + --file-system-name workspace \ + --mount-path /path/to/workspace \ + --driver fuse +``` + +显式 FUSE 支持 cache 控制： + +```bash +tdc fs mount-file-system \ + --file-system-name workspace \ + --mount-path /path/to/workspace \ + --driver fuse \ + --cache-dir "$HOME/.tdc/cache/workspace" \ + --read-cache-size-mb 256 \ + --read-cache-max-file-mb 16 \ + --read-cache-ttl 30s +``` + +默认 mount profile 是 `coding-agent`，会将 dependency、cache、generated output 和 Git 内部状态等常见开发数据保留在本地 overlay。这些 local-only 文件不会在机器删除后保留，除非执行 pack 或保留本地 volume。需要自动 portable pack 行为时使用 `--mount-profile portable`；不需要 coding-agent overlay policy 时使用 `none`。 + +## Drain 和 unmount + +清理前停止 writer 并关闭打开的文件。对于 FUSE： + +```bash +tdc fs drain-file-system \ + --mount-path /path/to/workspace \ + --timeout 30s + +tdc fs unmount-file-system \ + --mount-path /path/to/workspace +``` + +Drain 等待 dirty handle 和 pending write，不支持 WebDAV。`unmount-file-system` 还支持 `--timeout`、`--force`、`--ignore-absent`、`--pack-archive-path` 和 `--no-auto-pack`。 + +后台 mount 成功后，会在 `~/.tdc/mounts/` 写入非敏感 locator。同一个 `HOME` 下的 drain 和 unmount 可以使用该 locator，无需再次提供 `TDC_FS_TOKEN` 或 `TDC_REGION_CODE`。 + +> **警告：** +> +> 不要在仍有 pending write 时终止 sandbox 或虚拟机。已提交到远端的数据可以保留，但内存写入、位于已删除本地磁盘上的 write-back 数据，以及 coding-agent local-only 文件可能丢失。 + +## Unix 风格 alias + +Alias 只修改命令名称。所有 flag 保持长名称，并与 canonical command 一致。 + +| Alias | Canonical command | +| --- | --- | +| `tdc fs cp` | `tdc fs copy-file` | +| `tdc fs cat` | `tdc fs read-file` | +| `tdc fs ls` | `tdc fs list-files` | +| `tdc fs stat` | `tdc fs describe-file` | +| `tdc fs mv` | `tdc fs move-file` | +| `tdc fs rm` | `tdc fs delete-file` | +| `tdc fs mkdir` | `tdc fs create-directory` | +| `tdc fs chmod` | `tdc fs chmod-file` | +| `tdc fs symlink` | `tdc fs create-symlink` | +| `tdc fs hardlink` | `tdc fs create-hardlink` | +| `tdc fs grep` | `tdc fs search-file-content` | +| `tdc fs find` | `tdc fs find-files` | +| `tdc fs mount` | `tdc fs mount-file-system` | +| `tdc fs drain` | `tdc fs drain-file-system` | +| `tdc fs umount` | `tdc fs unmount-file-system` | + +## 命令汇总 + +| 范围 | 命令 | +| --- | --- | +| 资源 | `create-file-system`、`list-file-systems`、`describe-file-system`、`set-default-file-system`、`unset-default-file-system`、`check-file-system`、`delete-file-system` | +| 数据 | `copy-file`、`read-file`、`list-files`、`describe-file`、`move-file`、`delete-file`、`create-directory`、`chmod-file`、`create-symlink`、`create-hardlink`、`search-file-content`、`find-files` | +| Layer | `create-layer`、`list-layers`、`describe-layer`、`diff-layer`、`create-layer-checkpoint`、`rollback-layer`、`commit-layer` | +| 可移植性 | `pack-file-system`、`unpack-file-system` | +| Mount | `mount-file-system`、`drain-file-system`、`unmount-file-system` | + +## 后续步骤 + +- [在 Agent Sandbox 中使用文件系统](/ai/tdc/examples/tdc-agent-sandbox-example.md) +- [在不同机器间共享文件系统](/ai/tdc/examples/tdc-share-filesystem-across-machines-example.md) +- [在 TiDB Cloud 文件系统中使用 Git Workspace](/ai/tdc/guides/tdc-filesystem-git.md) diff --git a/ai/tdc/guides/tdc-install-configure-update.md b/ai/tdc/guides/tdc-install-configure-update.md new file mode 100644 index 000000000000..b3080acb33df --- /dev/null +++ b/ai/tdc/guides/tdc-install-configure-update.md @@ -0,0 +1,148 @@ +--- +title: 安装、配置和更新 tdc +summary: 安装 tdc release 二进制、以交互或自动化方式配置 profile、安全更新并卸载 CLI。 +--- + +# 安装、配置和更新 tdc + +本文介绍受支持的 release installer、profile 配置、帮助与版本行为、更新和卸载。 + +> **注意：** +> +> tdc 当前处于预览（Preview）阶段，其功能和命令行界面可能会发生变更，恕不另行通知。 + +## 安装 tdc + +### macOS 和 Linux + +```bash +curl -fsSL https://github.com/tidbcloud/tdc/releases/latest/download/install.sh | sh -s -- --yes +export PATH="$HOME/.tdc/bin:$PATH" +tdc --version +``` + +Installer 会将 `tdc` 和 `tdc-drive9` companion 放入 `~/.tdc/bin`。请将 PATH 设置加入 shell profile。安装过程不需要 `sudo`，也不会写入凭证。 + +### Windows + +```powershell +$script = "$env:TEMP\install-tdc.ps1" +iwr https://github.com/tidbcloud/tdc/releases/latest/download/install.ps1 -OutFile $script +powershell -ExecutionPolicy Bypass -File $script -Yes +$env:Path = "$HOME\.tdc\bin;$env:Path" +tdc --version +``` + +将 `$HOME\.tdc\bin` 加入用户 `PATH`，使新 PowerShell session 也能找到 tdc。 + +## 配置 profile + +交互式配置是唯一会提示输入的 tdc workflow： + +```bash +tdc configure +``` + +tdc 会请求 TiDB Cloud API public key、private key 和 canonical region code。它通过列出 project 验证 key，并将唯一的 `tidbx_virtual` project 记录为 profile 的默认 project。 + +配置命名 profile： + +```bash +tdc configure --profile staging +``` + +在 CI 或其他非交互环境中，优先使用环境变量： + +```bash +TDC_PUBLIC_KEY="" \ +TDC_PRIVATE_KEY="" \ +TDC_REGION_CODE="aws-us-east-1" \ +tdc configure --profile ci --non-interactive +``` + +也可以使用 `--tdc-public-key`、`--tdc-private-key` 和 `--region-code`，但 secret flag 可能保留在 shell history 或进程列表中。 + +配置优先级为命令参数、环境变量、已保存 profile。全局 `--region` 只覆盖当前命令的 region： + +```bash +tdc db list-db-clusters --profile staging --region aws-us-west-2 +``` + +## 获取帮助与版本信息 + +所有命令层级都支持 `help`、`--help` 和 `--version`： + +```bash +tdc help +tdc fs help +tdc db create-db-cluster help +tdc --version +tdc fs --version +``` + +生成的 usage 会先显示必需参数，再显示带方括号的可选参数。tdc 仅支持长参数。 + +## 更新 tdc + +只检查而不修改文件： + +```bash +tdc update --check +``` + +在自动化中，有更新时返回失败： + +```bash +tdc update --check --fail-if-update-available +``` + +预览并执行更新： + +```bash +tdc update --dry-run +tdc update +``` + +安装指定 tdc release： + +```bash +tdc update --target-version v0.1.2 +``` + +更新命令会替换用户安装目录中的两个二进制。活跃的文件系统挂载会继续运行已经加载的 companion 进程。为避免旧挂载运行时与新 CLI 命令混用，请在更新前停止写入、drain FUSE 挂载并 unmount： + +```bash +tdc fs drain-file-system --mount-path /path/to/workspace +tdc fs unmount-file-system --mount-path /path/to/workspace +tdc update +``` + +WebDAV 应关闭写入进程并 unmount；drain 仅支持 FUSE。tdc 不会修改受保护位置或 package manager 管理的安装。较早安装在 `/usr/local/bin` 的版本需要重新运行 installer，一次性迁移到 `~/.tdc/bin`。 + +## 卸载 tdc + +仅删除二进制： + +```bash +rm -f "$HOME/.tdc/bin/tdc" "$HOME/.tdc/bin/tdc-drive9" +``` + +在 Windows 上： + +```powershell +Remove-Item "$HOME\.tdc\bin\tdc.exe", "$HOME\.tdc\bin\tdc-drive9.exe" +``` + +删除二进制会保留 profile、凭证、文件系统注册、DB SQL 凭证、日志和挂载定位文件。只有在确定要删除全部本地 tdc 状态时，才删除 `~/.tdc/`： + +```bash +rm -rf "$HOME/.tdc" +``` + +删除本地状态不会删除远端 Starter 集群或文件系统资源。 + +## 后续步骤 + +- [tdc 配置与凭证](/ai/tdc/reference/tdc-configuration-and-credentials.md) +- [管理 TiDB Cloud Starter 数据库](/ai/tdc/guides/tdc-starter-database.md) +- [管理 TiDB Cloud 文件系统](/ai/tdc/guides/tdc-filesystem.md) diff --git a/ai/tdc/guides/tdc-organization.md b/ai/tdc/guides/tdc-organization.md new file mode 100644 index 000000000000..6305973b4b9d --- /dev/null +++ b/ai/tdc/guides/tdc-organization.md @@ -0,0 +1,65 @@ +--- +title: 使用 tdc 管理 TiDB Cloud Organization +summary: 列出可访问的 TiDB Cloud project，并了解 tdc 使用的普通 project 与 virtual project 类型。 +--- + +# 使用 tdc 管理 TiDB Cloud Organization + +使用 `tdc organization` 查看已配置 TiDB Cloud API key 能访问的 project。 + +> **注意：** +> +> tdc 当前处于预览（Preview）阶段，其功能和命令行界面可能会发生变更，恕不另行通知。 + +## 前置条件 + +使用能够列出 organization project 的 TiDB Cloud API key 运行 `tdc configure`。 + +## 列出 project + +```bash +tdc organization list-projects +``` + +JSON 响应包含 project ID、名称和 `type`： + +- `tidbx` 表示普通 project； +- `tidbx_virtual` 表示作为 Starter 默认 project 的 virtual project。 + +指定 page size，或者使用返回的 page token 继续： + +```bash +tdc organization list-projects --page-size 50 +tdc organization list-projects --page-size 50 --page-token "" +``` + +输出终端表格或选择字段： + +```bash +tdc organization list-projects --output text +tdc organization list-projects --query 'projects[].{id:id,name:name,type:type}' +``` + +## 默认 virtual project + +`tdc configure` 会调用同一 project-listing API。只有找到恰好一个可访问的 `tidbx_virtual` project 时配置才会成功，并将其 ID 保存到所选 profile： + +```toml +[default] +region_code = "aws-us-east-1" +project_id = "..." +``` + +省略 `--project-id` 时，`tdc db create-db-cluster` 会使用该 project。为单个集群覆盖它： + +```bash +tdc db create-db-cluster \ + --db-cluster-name project-specific-cluster \ + --db-cluster-type starter \ + --project-id "" +``` + +## 后续步骤 + +- [管理 TiDB Cloud Starter 数据库](/ai/tdc/guides/tdc-starter-database.md) +- [tdc 配置与凭证](/ai/tdc/reference/tdc-configuration-and-credentials.md) diff --git a/ai/tdc/guides/tdc-starter-database.md b/ai/tdc/guides/tdc-starter-database.md new file mode 100644 index 000000000000..b73de231a0e6 --- /dev/null +++ b/ai/tdc/guides/tdc-starter-database.md @@ -0,0 +1,204 @@ +--- +title: 使用 tdc 管理 TiDB Cloud Starter 数据库 +summary: 管理 Starter 集群和分支、创建 SQL 用户、格式化连接字符串，并使用显式角色执行 SQL。 +--- + +# 使用 tdc 管理 TiDB Cloud Starter 数据库 + +使用 `tdc db` 管理 TiDB Cloud Starter 集群、分支和 SQL 访问。 + +> **注意：** +> +> tdc 当前处于预览（Preview）阶段，其功能和命令行界面可能会发生变更，恕不另行通知。 + +## 前置条件 + +- 使用 `tdc configure` 配置 tdc。 +- 确保 API key 能管理所选 project 中的 Starter 集群。 +- 自动化使用合成且唯一的名称，使清理过程只识别本次运行创建的资源。 + +## 管理集群 + +预览并创建 Starter 集群： + +```bash +tdc db create-db-cluster \ + --db-cluster-name demo-cluster \ + --db-cluster-type starter \ + --dry-run + +tdc db create-db-cluster \ + --db-cluster-name demo-cluster \ + --db-cluster-type starter +``` + +除非提供 `--project-id`，否则使用已配置的 virtual project。`--monthly-spending-limit-usd-cents` 是可选项；设置该值可能要求配置 payment method。 + +列出和筛选集群： + +```bash +tdc db list-db-clusters +tdc db list-db-clusters --page-size 20 --order-by "createTime desc" +tdc db list-db-clusters --query 'clusters[].{id:id,name:display_name,state:state}' +``` + +List 命令还支持 `--page-token`、`--filter` 和 `--skip`。 + +查看和更新集群： + +```bash +tdc db describe-db-cluster \ + --db-cluster-id "" \ + --view FULL + +tdc db update-db-cluster \ + --db-cluster-id "" \ + --db-cluster-name demo-cluster-renamed +``` + +Update 必须包含新名称或 spending limit。使用 `--dry-run` 预览 mutating command。 + +删除集群： + +```bash +tdc db delete-db-cluster \ + --db-cluster-id "" \ + --dry-run + +tdc db delete-db-cluster \ + --db-cluster-id "" +``` + +tdc 会在内部解析集群名称，无需名称确认 flag。 + +## 管理分支 + +创建并列出分支： + +```bash +tdc db create-db-cluster-branch \ + --db-cluster-id "" \ + --db-cluster-branch-name development + +tdc db list-db-cluster-branches \ + --db-cluster-id "" \ + --page-size 20 +``` + +使用 `--page-token` 继续读取分页 branch list。 + +查看并删除分支： + +```bash +tdc db describe-db-cluster-branch \ + --db-cluster-id "" \ + --db-cluster-branch-id "" \ + --view FULL + +tdc db delete-db-cluster-branch \ + --db-cluster-id "" \ + --db-cluster-branch-id "" +``` + +Create 和 delete 支持 `--dry-run`。 + +## 创建 SQL 用户 + +创建或修复三个 tdc 管理的 SQL 角色： + +```bash +tdc db create-db-sql-users \ + --db-cluster-id "" +``` + +该操作可重入。它复用稳定的角色名，并将生成的凭证保存到 `~/.tdc/db_users//credentials`： + +- `read_only`； +- `read_write`； +- `admin`。 + +不修改用户地预览操作： + +```bash +tdc db create-db-sql-users \ + --db-cluster-id "" \ + --dry-run +``` + +## 格式化连接字符串 + +默认角色是 read-write，但建议显式选择： + +```bash +tdc db format-db-connection-string \ + --db-cluster-id "" \ + --read-write \ + --database app \ + --format mysql-uri + +tdc db format-db-connection-string \ + --db-cluster-id "" \ + --read-only \ + --format env \ + --env-prefix TIDB_ + +tdc db format-db-connection-string \ + --db-cluster-id "" \ + --admin \ + --format jdbc +``` + +支持 `mysql-uri`、`jdbc`、`go-sql-driver`、`sqlalchemy` 和 `env` 格式。对于 `env`，`--env-include-database-url` 添加 URL 变量，`--env-database-url-name` 修改变量名。 + +> **警告：** +> +> 连接字符串包含凭证。不要将其写入日志、ticket 或 source control。 + +## 执行 SQL + +每次调用只接受一条 SQL statement。请使用显式角色： + +```bash +tdc db execute-sql-statement \ + --db-cluster-id "" \ + --read-only \ + --database app \ + --sql "SELECT COUNT(*) AS row_count FROM messages" \ + --output text + +tdc db execute-sql-statement \ + --db-cluster-id "" \ + --read-write \ + --database app \ + --sql "INSERT INTO messages(id, body) VALUES (1, 'hello')" + +tdc db execute-sql-statement \ + --db-cluster-id "" \ + --admin \ + --sql "CREATE DATABASE IF NOT EXISTS app" +``` + +默认 `--transport https` 通过 HTTPS 发送 SQL 请求，不保留数据库连接。`--transport mysql` 是显式兼容回退；它会为当前命令建立连接并在完成后关闭。 + +## 命令汇总 + +| 命令 | 用途 | +| --- | --- | +| `create-db-cluster` | 创建 Starter 集群 | +| `list-db-clusters` | 列出 Starter 集群 | +| `describe-db-cluster` | 读取单个集群 | +| `update-db-cluster` | 修改集群名称或 spending limit | +| `delete-db-cluster` | 删除集群 | +| `create-db-cluster-branch` | 创建分支 | +| `list-db-cluster-branches` | 列出分支 | +| `describe-db-cluster-branch` | 读取单个分支 | +| `delete-db-cluster-branch` | 删除分支 | +| `create-db-sql-users` | 创建或修复三个 SQL 角色 | +| `format-db-connection-string` | 格式化已准备的凭证 | +| `execute-sql-statement` | 执行一条 SQL statement | + +## 后续步骤 + +- [使用显式角色查询 SQL](/ai/tdc/examples/tdc-query-sql-with-roles-example.md) +- [tdc CLI 参考](/ai/tdc/reference/tdc-cli-reference.md) +- [tdc 故障排查](/ai/tdc/reference/tdc-troubleshooting.md) diff --git a/ai/tdc/reference/tdc-cli-reference.md b/ai/tdc/reference/tdc-cli-reference.md new file mode 100644 index 000000000000..2afca8390e95 --- /dev/null +++ b/ai/tdc/reference/tdc-cli-reference.md @@ -0,0 +1,158 @@ +--- +title: tdc CLI 参考 +summary: 参考 tdc 全局参数、输出与查询行为、dry-run 规则、help 形式、错误、命令 family 和文件系统 alias。 +--- + +# tdc CLI 参考 + +本文说明 tdc 命令 surface 共享的行为。 + +> **注意：** +> +> tdc 当前处于预览（Preview）阶段，其功能和命令行界面可能会发生变更，恕不另行通知。 + +## 语法 + +```text +tdc [subcommand] [required flags] [optional flags] [global flags] +``` + +tdc 仅接受长 flag，`-p` 之类的单字母 flag 会被拒绝。 + +生成的 usage 中，required flag 位于 optional flag 之前，optional flag 使用方括号： + +```text +tdc db describe-db-cluster + --db-cluster-id + [--output ] + [--view ] +``` + +## 全局 flag + +| Flag | 说明 | +| --- | --- | +| `--profile ` | 选择本地 profile，默认为 `default` | +| `--region ` | 为当前命令覆盖 canonical region | +| `--output ` | 输出 `json` 或 `text`，默认为 `json` | +| `--query ` | 在输出前应用 JMESPath expression | +| `--debug` | 输出已脱敏 debug diagnostic | +| `--help` | 显示帮助 | +| `--version` | 显示 tdc 版本信息 | + +## 输出 + +结构化 control-plane 命令默认返回 JSON： + +```bash +tdc db list-db-clusters +``` + +使用 text 输出进行终端查看： + +```bash +tdc db list-db-clusters --output text +``` + +`tdc fs read-file` 和 `tdc fs copy-file --to-stdout` 等 raw byte 命令会直接写出文件内容。 + +## JMESPath query + +`--query` 在命令成功后、输出渲染前执行： + +```bash +tdc db list-db-clusters \ + --query 'clusters[].{id:id,name:display_name,state:state}' + +tdc organization list-projects \ + --query 'projects[?type == `tidbx_virtual`].id' \ + --output text +``` + +无效 expression 会失败，不会用 partial output 替换命令结果。 + +## Dry-run + +会修改资源的 control-plane 命令会显式声明 `--dry-run`。命令先验证本地参数、profile、凭证、region 和请求结构，然后输出执行计划，但不修改远端资源。 + +```bash +tdc db delete-db-cluster \ + --db-cluster-id "" \ + --dry-run +``` + +只读命令拒绝 `--dry-run`。Dry run 不是通用的全局模拟参数，只在命令帮助明确显示时可用。 + +## Help 与 version 形式 + +```bash +tdc help +tdc db help +tdc db create-db-cluster help +tdc --help +tdc db --help +tdc db create-db-cluster --help +tdc --version +tdc fs --version +``` + +`help` 是导航命令树的 command，`--help` 是每个命令上的惯例 flag，两者有意共存。 + +## 错误与退出行为 + +人类可读错误使用稳定 prefix： + +```text +tdc [ERROR]: +``` + +错误写入 stderr，成功结果写入 stdout。用法和配置错误会在修改远端资源前以非零状态码退出；运行时和远端 API 错误同样返回非零状态码。交互式配置被中断时返回退出码 `130`。 + +`--debug` 可以显示已脱敏 request 和 resolution context，但不得显示 API key、FS token、DB password、SQL text、file content 或 connection string。 + +## 命令 family + +| 命令 | 用途 | +| --- | --- | +| `tdc configure` | 配置本地 profile | +| `tdc update` | 检查或应用 release update | +| `tdc organization` | 查看 project | +| `tdc db` | 管理 Starter cluster、branch 和 SQL | +| `tdc fs` | 管理文件系统、file、layer、pack 和 mount | +| `tdc fs-git` | 管理 mounted filesystem 上的 Git workspace | +| `tdc fs-journal` | 管理可验证 journal | +| `tdc fs-vault` | 管理 secret 和 delegated access | + +查看完整命令和 flag： + +```bash +tdc help +tdc help +``` + +## 文件系统 alias mapping + +| Alias | Canonical command | +| --- | --- | +| `cp` | `copy-file` | +| `cat` | `read-file` | +| `ls` | `list-files` | +| `stat` | `describe-file` | +| `mv` | `move-file` | +| `rm` | `delete-file` | +| `mkdir` | `create-directory` | +| `chmod` | `chmod-file` | +| `symlink` | `create-symlink` | +| `hardlink` | `create-hardlink` | +| `grep` | `search-file-content` | +| `find` | `find-files` | +| `mount` | `mount-file-system` | +| `drain` | `drain-file-system` | +| `umount` | `unmount-file-system` | + +Alias 与 canonical command 使用相同的长参数、认证、输出、查询和错误行为。 + +## 相关文档 + +- [安装、配置和更新 tdc](/ai/tdc/guides/tdc-install-configure-update.md) +- [tdc 配置与凭证](/ai/tdc/reference/tdc-configuration-and-credentials.md) diff --git a/ai/tdc/reference/tdc-configuration-and-credentials.md b/ai/tdc/reference/tdc-configuration-and-credentials.md new file mode 100644 index 000000000000..e8d827250eee --- /dev/null +++ b/ai/tdc/reference/tdc-configuration-and-credentials.md @@ -0,0 +1,195 @@ +--- +title: tdc 配置与凭证 +summary: 参考 tdc profile、环境变量和参数优先级、本地状态路径、文件系统 registry、SQL 凭证、挂载定位信息和操作日志。 +--- + +# tdc 配置与凭证 + +tdc 将所有产品管理的本地状态保存在 `~/.tdc/`，并分离非敏感配置与凭证。 + +> **注意：** +> +> tdc 当前处于预览（Preview）阶段，其功能和命令行界面可能会发生变更，恕不另行通知。 + +## 主文件 + +```toml +# ~/.tdc/config +[default] +region_code = "aws-us-east-1" +project_id = "..." +fs_default_file_system_name = "workspace" + +[logging] +enabled = true +max_file_mb = 10 +max_files = 5 +``` + +```toml +# ~/.tdc/credentials +[default] +tdc_public_key = "..." +tdc_private_key = "..." +``` + +平台支持 POSIX mode 时，凭证文件仅允许所有者访问。 + +## Profile 选择 + +Profile 命名空间的选择顺序如下： + +1. 显式 `--profile`； +2. `TDC_PROFILE`； +3. `default`。 + +显式空 profile 无效。环境凭证不会创建 `[env]` profile，也不会修改所选命名空间。 + +## TiDB Cloud API 凭证 + +凭证选择顺序如下： + +1. 设置了任意一项时，使用 `TDC_PUBLIC_KEY` 和 `TDC_PRIVATE_KEY`； +2. 使用 `~/.tdc/credentials` 中所选 profile section。 + +两个环境值必须同时存在。tdc 不会混用一半环境变量和一半文件值。 + +部署区域的选择顺序如下： + +1. 显式全局 `--region`； +2. `TDC_REGION_CODE`； +3. profile `region_code`。 + +命令参数、环境输入、已保存配置和命令默认值会按字段分别解析。因此，除 API key pair 这类必须成对提供的字段外，不同字段可以来自不同层级。 + +## 默认 Starter project + +创建 Starter 集群时，project 的选择顺序如下： + +1. 显式非空 `--project-id`； +2. `tdc configure` 发现的 profile `project_id`； +3. 否则在发送创建请求前失败。 + +其他 DB 命令通过集群或分支 ID 定位资源，不使用 `project_id`。文件系统命令不使用 DB 默认 project。 + +## 文件系统资源 registry + +一个 profile 可以注册多个文件系统。主配置仅保存可选的默认名称，各资源状态彼此隔离： + +```text +~/.tdc/fs_resources///config +~/.tdc/fs_resources///credentials +``` + +资源配置包含文件系统名称、tenant ID、云服务提供商、region code 和创建时间。凭证文件只包含 owner `api_key`，且只允许所有者访问。 + +资源选择顺序如下： + +1. 显式 `--file-system-name`； +2. `TDC_FS_FILE_SYSTEM_NAME`； +3. profile `fs_default_file_system_name`； +4. 唯一已注册资源； +5. 否则以资源缺失或选择不明确的错误失败。 + +远端 `fs`、`fs-git`、`fs-journal` 和 owner `fs-vault` 操作的 FS owner 凭证选择顺序如下： + +1. 显式 `--fs-token`； +2. `TDC_FS_TOKEN`； +3. 所选资源的凭证。 + +优先使用 `TDC_FS_TOKEN`，因为命令行参数可能保留在 shell history 或进程列表中。 + +## 无配置访问文件系统 + +全新的沙箱可以使用： + +```bash +export TDC_FS_TOKEN="" +export TDC_REGION_CODE="aws-us-east-1" +export TDC_FS_FILE_SYSTEM_NAME="workspace" +``` + +这些值只构成内存中的命名空间，tdc 不会写入 `~/.tdc/`。创建和删除文件系统仍需要 TiDB Cloud API 凭证；删除还需要本地资源注册信息。 + +## DB SQL 凭证 + +生成的 SQL 凭证以集群为作用域： + +```text +~/.tdc/db_users//credentials +``` + +```toml +[read_only] +username = "..." +password = "..." + +[read_write] +username = "..." +password = "..." + +[admin] +username = "..." +password = "..." +``` + +`tdc db create-db-sql-users` 创建或修复这些稳定用户。它们不存储在主凭证文件中。 + +## Companion 状态与挂载定位信息 + +每个已注册文件系统都有隔离的 companion home： + +```text +~/.tdc/drive9-home/// +``` + +不要为 tdc 工作流编辑该状态或独立的 `~/.drive9` 配置。 + +后台 FS 或 Vault 挂载成功后会写入非敏感的定位文件： + +```text +~/.tdc/mounts/.locator.json +``` + +定位文件包含足以确定部署区域和 companion home 的信息，使同一个 `HOME` 中的 drain 和 unmount 无需再次提供 token。定位文件不包含 FS token，并会在 unmount 成功后删除。 + +## 操作日志 + +tdc 将已脱敏的本地 JSON Lines 事件写入： + +```text +~/.tdc/logs/tdc.jsonl +``` + +这是本地审计和调试数据，不是 telemetry。它可以包含命令名、参数名、profile、region、耗时、退出状态、稳定错误码、HTTP method/status、操作与 request ID；不包含参数值、SQL、文件路径或内容、payload、连接字符串或凭证。 + +为单个进程关闭： + +```bash +TDC_LOGGING=off tdc db list-db-clusters +``` + +或者配置： + +```toml +[logging] +enabled = false +``` + +环境值 `off`、`false`、`0`、`no` 用于关闭，`on`、`true`、`1`、`yes` 用于开启。环境变量优先于配置文件。 + +## 敏感值 + +以下值均应视为密钥： + +- TiDB Cloud API private key 和 public-key pair； +- FS owner token； +- DB SQL 用户名、密码和连接字符串； +- 委派的 Vault token 和 secret 值。 + +不要将其写入版本控制、工单、日志、命令示例或不受保护的 shell history。 + +## 相关文档 + +- [tdc 区域、安全与限制](/ai/tdc/reference/tdc-regions-security-and-limitations.md) +- [tdc 故障排查](/ai/tdc/reference/tdc-troubleshooting.md) diff --git a/ai/tdc/reference/tdc-regions-security-and-limitations.md b/ai/tdc/reference/tdc-regions-security-and-limitations.md new file mode 100644 index 000000000000..aba56e958f65 --- /dev/null +++ b/ai/tdc/reference/tdc-regions-security-and-limitations.md @@ -0,0 +1,94 @@ +--- +title: tdc 区域、安全与限制 +summary: 参考 tdc 支持的 region、认证边界、平台依赖、Preview 限制和文件系统 companion 行为。 +--- + +# tdc 区域、安全与限制 + +本文说明当前部署区域、认证、平台和 Preview 边界。 + +> **注意：** +> +> tdc 当前处于预览（Preview）阶段，其功能和命令行界面可能会发生变更，恕不另行通知。 + +## TiDB Cloud region + +tdc 接受一个 canonical region code： + +| Canonical code | Provider | Location | +| --- | --- | --- | +| `aws-us-east-1` | AWS | N. Virginia | +| `aws-us-west-2` | AWS | Oregon | +| `aws-eu-central-1` | AWS | Frankfurt | +| `aws-ap-northeast-1` | AWS | Tokyo | +| `aws-ap-southeast-1` | AWS | Singapore | +| `ali-ap-southeast-1` | Alibaba Cloud | Singapore | + +Alibaba Cloud 当前在 tdc 中只支持 Singapore。用户不能配置原始 service URL。 + +## 文件系统 region + +文件系统 endpoint 的可用性由托管的 Drive9 region manifest 解析。本文发布时，TiDB Cloud native Filesystem mode 支持： + +- `aws-us-east-1`； +- `aws-ap-southeast-1`。 + +托管的 manifest 是权威来源，在 Preview 阶段可能变化。位于其他 TiDB Cloud region 的 profile 仍可以管理 Starter 数据库，但在 manifest 支持该部署区域之前，文件系统命令会返回 endpoint 不受支持的错误。 + +## 凭证要求 + +| 操作 | 所需凭证 | +| --- | --- | +| `tdc configure`、`tdc organization`、所有 `tdc db` control-plane 操作 | TiDB Cloud API public/private key | +| `tdc fs create-file-system` | TiDB Cloud API key | +| `tdc fs delete-file-system` | TiDB Cloud API key、本地资源注册信息和 owner 资源凭证 | +| 远端文件、layer、pack、挂载、Git、Journal 和 owner Vault 操作 | FS owner token 或已注册的资源凭证 | +| 委派的 Vault 读取、列出、运行或挂载操作 | Scope 合适的委派 Vault token | +| 后台挂载成功后的 drain 和 unmount | 同一 `HOME` 中的非敏感挂载定位信息 | + +TiDB Cloud API 调用使用 Digest 认证。SQL HTTPS 执行使用生成的 SQL 用户名和密码，并通过 TLS 上的 Basic 认证传递。这些凭证不能互换。 + +## 安全建议 + +- 密钥优先使用环境变量或受保护的凭证文件。 +- SQL 使用显式 read-only、read-write 或 admin 角色。 +- Agent 仅需访问密钥时，应提供委派的 Vault grant，而不是 FS owner token。 +- 执行破坏性 control-plane 操作前使用 `--dry-run`。 +- 确保 `~/.tdc/credentials`、资源凭证和 DB SQL 凭证仅所有者可读。 +- 即使 tdc 会对已知密钥类型进行脱敏，共享诊断信息前仍应检查本地操作日志。 + +## 挂载平台限制 + +| 平台 | 默认 | 限制 | +| --- | --- | --- | +| macOS | WebDAV | 安装 macFUSE 并显式使用 `--driver fuse`，获得 FUSE cache、drain 和更完整的 POSIX 行为 | +| Linux | FUSE | 需要 FUSE3 和 `/dev/fuse`；显式 WebDAV 需要 `davfs2` | +| Windows | WebDAV | 需要 WebClient 服务和盘符形式的挂载路径；不支持 FUSE 和 Vault 挂载 | + +FUSE 和 WebDAV 由内置 [Drive9](https://github.com/mem9-ai/drive9) companion 实现。tdc 不会回退到另一套原生挂载实现。 + +## 持久性限制 + +- companion 支持时，默认 FUSE 行为会使用本地缓冲和异步远端操作。 +- `drain-file-system` 仅支持 FUSE。 +- 突然终止挂载进程或删除机器，可能丢失尚未提交的内存或 write-back 状态。 +- 默认 `coding-agent` 挂载 profile 会在本地保存依赖树、生成输出、缓存和 Git 内部状态。除非执行 pack 或以其他方式保留，否则这些本地数据会随磁盘删除而消失。 +- 运行中的挂载会继续使用挂载时加载的 companion 版本。更新 tdc 后需要卸载并重新挂载。 +- 已提交到远端的文件系统数据不受客户端或沙箱删除影响；删除机器不会删除远端资源。 + +## 产品限制 + +- tdc 处于 Preview，命令契约可能变化。 +- 数据库管理面向 TiDB Cloud Starter，不覆盖所有 TiDB Cloud 集群规格。 +- 每次 SQL 执行只接受一条 statement。 +- 默认 SQL 角色为 read-write；安全敏感的自动化应显式指定角色参数。 +- Journal 仅支持追加，当前公开命令面没有删除 Journal 的命令。 +- 文件系统资源的 list 和 describe 针对本地 registry，不是 organization 级的发现 API。 +- Telemetry 命令、Serverless Function 部署、Homebrew 和 Scoop 分发尚未实现。 +- 所有公开的文件系统运行时行为都依赖已安装的 `tdc-drive9` companion。 + +## 相关文档 + +- [使用 tdc 管理 TiDB Cloud 文件系统](/ai/tdc/guides/tdc-filesystem.md) +- [tdc 配置与凭证](/ai/tdc/reference/tdc-configuration-and-credentials.md) +- [tdc 故障排查](/ai/tdc/reference/tdc-troubleshooting.md) diff --git a/ai/tdc/reference/tdc-troubleshooting.md b/ai/tdc/reference/tdc-troubleshooting.md new file mode 100644 index 000000000000..bcc55f7fd42c --- /dev/null +++ b/ai/tdc/reference/tdc-troubleshooting.md @@ -0,0 +1,190 @@ +--- +title: tdc 故障排查 +summary: 排查 tdc 认证、project、文件系统选择、companion、配额、SQL 用户、挂载和中断清理问题。 +--- + +# tdc 故障排查 + +使用本文排查当前常见的 tdc 故障。只在需要时添加 `--debug`；调试输出已经脱敏，但共享前仍需检查。 + +> **注意：** +> +> tdc 当前处于预览（Preview）阶段，其功能和命令行界面可能会发生变更，恕不另行通知。 + +## API 认证失败 + +常见症状包括凭证缺失、Digest 认证失败或权限不足。 + +检查两个环境值是否同时设置： + +```bash +test -n "$TDC_PUBLIC_KEY" +test -n "$TDC_PRIVATE_KEY" +``` + +如果要使用已保存的凭证，请清除这两个变量并验证 profile： + +```bash +unset TDC_PUBLIC_KEY TDC_PRIVATE_KEY +tdc organization list-projects --profile default +``` + +API key 即使认证成功，也可能缺少命令所需的权限。请使用对相应 organization 或 project 具备访问权限的 key。 + +## Configure 找不到 virtual project + +`tdc configure` 要求恰好一个可访问 project 的 `type` 为 `tidbx_virtual`。 + +```bash +tdc organization list-projects \ + --query 'projects[].{id:id,name:name,type:type}' +``` + +如果没有 virtual project，请检查 API key 对 organization 和 project 的访问权限。如果出现多个，请通过 [tdc issue tracker](https://github.com/tidbcloud/tdc/issues)报告无法确定默认项目的问题。 + +## 文件系统 token 缺失 + +干净 sandbox 需要提供三个值： + +```bash +export TDC_FS_TOKEN="" +export TDC_REGION_CODE="aws-us-east-1" +export TDC_FS_FILE_SYSTEM_NAME="workspace" +tdc fs check-file-system +``` + +FS token 不是 TiDB Cloud API private key。 + +## 文件系统选择存在歧义 + +列出已注册资源并显式选择： + +```bash +tdc fs list-file-systems --output text +tdc fs list-files --file-system-name workspace --path / +``` + +或者设置默认值： + +```bash +tdc fs set-default-file-system --file-system-name workspace +``` + +tdc 不会在多个资源中猜测。 + +## 文件系统 region 不受支持 + +已配置的 TiDB Cloud region 可能没有 `tidb_cloud_native` 文件系统 endpoint。请与[当前文件系统 region](/ai/tdc/reference/tdc-regions-security-and-limitations.md#文件系统-region)比较。使用有效的 profile 或命令级 `--region` 修改部署区域，不要配置原始 server URL。 + +## Companion 缺失或不兼容 + +Release installer 会将 `tdc-drive9` 放在 `tdc` 旁。tdc 报告 companion 缺失时，请重新运行当前 installer： + +```bash +curl -fsSL https://github.com/tidbcloud/tdc/releases/latest/download/install.sh | sh -s -- --yes +``` + +验证 `PATH` 解析到预期 tdc： + +```bash +command -v tdc +tdc --version +``` + +不要复制任意 standalone Drive9 二进制。 + +## Starter 或文件系统创建达到 quota + +Quota 和 capacity error 可能表示 organization 达到 free Starter limit。创建前列出已有资源： + +```bash +tdc db list-db-clusters --output text +tdc fs list-file-systems --output text +``` + +不要为了让自动化通过而删除无关资源。Starter spending limit 可能要求配置 billing。 + +## SQL 凭证缺失 + +为准确 cluster 准备或修复用户： + +```bash +tdc db create-db-sql-users --db-cluster-id "" +``` + +然后以显式角色重试： + +```bash +tdc db execute-sql-statement \ + --db-cluster-id "" \ + --read-only \ + --sql "SELECT 1" +``` + +删除 `~/.tdc/db_users//credentials` 会删除本地密码。请运行创建或修复命令，不要自行构造凭证。 + +## Mount 未能 ready + +查看 timeout error 输出的 log path，并确认： + +- Mount path 存在且可写； +- 没有其他挂载覆盖该路径； +- FS token 和 region 有效； +- 已安装 FUSE prerequisite 或 WebDAV helper； +- 远端 region 可达。 + +macOS 默认使用 WebDAV。安装 macFUSE 后请求 FUSE： + +```bash +tdc fs mount-file-system \ + --mount-path /path/to/workspace \ + --driver fuse +``` + +Linux 需要 FUSE3，并且当前用户需要访问 `/dev/fuse`。Windows WebDAV 需要 WebClient 服务和 `X:` 之类的盘符。 + +## 进程崩溃后 mount stale + +如果 companion 未正常卸载就被终止，FUSE 访问可能返回 `EIO` 或 `Transport endpoint is not connected`。请先停止仍在打开文件的进程，然后尝试： + +```bash +tdc fs unmount-file-system \ + --mount-path /path/to/workspace \ + --force +``` + +没有 locator 时，如果清理应成功，使用 `--ignore-absent`。突然清理无法保证恢复已删除本地磁盘上的 pending write。 + +## Unmount 报告 busy + +关闭编辑器、工作目录位于挂载点内的 shell，以及其他持有已打开文件的进程。对于 FUSE，请在 drain 后重试： + +```bash +tdc fs drain-file-system --mount-path /path/to/workspace --timeout 30s +tdc fs unmount-file-system --mount-path /path/to/workspace +``` + +不要对 WebDAV 使用 drain。 + +## 中断命令留下资源 + +列出资源，并且只处理本次工作流创建的对象。删除前先查看详情： + +```bash +tdc db describe-db-cluster --db-cluster-id "" +tdc fs describe-file-system --file-system-name "" +``` + +预览受支持的清理： + +```bash +tdc db delete-db-cluster --db-cluster-id "" --dry-run +tdc fs delete-file-system \ + --file-system-name "" \ + --confirm-file-system-name "" \ + --dry-run +``` + +## 报告问题 + +请提供 tdc 版本、操作系统与架构、命令名称、稳定错误码和已脱敏日志。不要提供 API key、FS/Vault token、DB 密码、包含私有数据的 SQL 或文件内容。请在 [github.com/tidbcloud/tdc/issues](https://github.com/tidbcloud/tdc/issues) 报告问题。 diff --git a/ai/tdc/tdc-overview.md b/ai/tdc/tdc-overview.md new file mode 100644 index 000000000000..bf293417fb66 --- /dev/null +++ b/ai/tdc/tdc-overview.md @@ -0,0 +1,72 @@ +--- +title: TiDB Cloud CLI（tdc）概览 +summary: 了解预览版 tdc 命令行如何为用户、脚本和 AI Agent 管理 TiDB Cloud Starter 数据库与 TiDB Cloud 文件系统。 +--- + +# TiDB Cloud CLI（tdc）概览 + +tdc 是用于管理 TiDB Cloud Starter 数据库和 TiDB Cloud 文件系统的命令行工具。它提供确定性的 JSON 输出、显式权限、可脚本化配置，以及同时面向用户与 AI Agent 的命令设计。 + +> **注意：** +> +> tdc 当前处于预览（Preview）阶段，其功能和命令行界面可能会发生变更，恕不另行通知。 + +## tdc 能做什么 + +你可以使用 tdc： + +- 创建、查看、更新和删除 TiDB Cloud Starter 集群； +- 创建和管理 Starter 分支； +- 创建只读、读写和管理员 SQL 用户，格式化连接字符串并执行 SQL； +- 在一个 profile 中创建和选择多个 TiDB Cloud 文件系统资源； +- 直接访问文件系统数据，或者通过 FUSE、WebDAV 挂载； +- 使用文件系统 layer、pack、Git workspace、仅追加 journal 和委派密钥； +- 在脚本和 Agent 工作流中使用 JSON 输出与 JMESPath 查询。 + +tdc 使用两级命令模型： + +```text +tdc +``` + +例如 `tdc db list-db-clusters`、`tdc fs copy-file` 和 `tdc fs-journal verify-journal`。顶层的 `tdc configure` 和 `tdc update` 分别用于配置和维护 CLI。 + +## tdc 与 Drive9 + +tdc 会安装名为 `tdc-drive9` 的内置 [Drive9](https://github.com/mem9-ai/drive9) companion。tdc 负责 profile 选择、TiDB Cloud 凭证、region 与文件系统选择、输出格式和错误处理；companion 负责文件系统数据面语义、FUSE/WebDAV 挂载、layer、pack/unpack、Git workspace 加速、Journal 和 Vault。 + +在常规 tdc 工作流中，你不需要单独安装、配置或调用 Drive9。 + +## 开始使用 tdc + +- [快速上手](/ai/tdc/tdc-quick-start.md) +- [概念与架构](/ai/tdc/concepts/tdc-concepts-and-architecture.md) + +### 使用指南 + +- [安装、配置和更新 tdc](/ai/tdc/guides/tdc-install-configure-update.md) +- [管理 TiDB Cloud Organization](/ai/tdc/guides/tdc-organization.md) +- [管理 TiDB Cloud Starter 数据库](/ai/tdc/guides/tdc-starter-database.md) +- [管理 TiDB Cloud 文件系统](/ai/tdc/guides/tdc-filesystem.md) +- [在 TiDB Cloud 文件系统中使用 Git Workspace](/ai/tdc/guides/tdc-filesystem-git.md) +- [使用文件系统 Journal](/ai/tdc/guides/tdc-filesystem-journal.md) +- [使用文件系统 Vault](/ai/tdc/guides/tdc-filesystem-vault.md) + +### 场景示例 + +- [在 Agent Sandbox 中使用文件系统](/ai/tdc/examples/tdc-agent-sandbox-example.md) +- [执行日常 tdc 工作流](/ai/tdc/examples/tdc-daily-workflow-example.md) +- [使用显式角色查询 SQL](/ai/tdc/examples/tdc-query-sql-with-roles-example.md) +- [在不同机器间共享文件系统](/ai/tdc/examples/tdc-share-filesystem-across-machines-example.md) +- [为 Agent 准备 Git Workspace](/ai/tdc/examples/tdc-git-workspace-for-agents-example.md) +- [使用 Journal 记录 Agent 工作流](/ai/tdc/examples/tdc-journal-agent-workflow-example.md) +- [向 Agent 委派 Vault 密钥](/ai/tdc/examples/tdc-vault-agent-secrets-example.md) + +### 参考 + +- [tdc CLI 参考](/ai/tdc/reference/tdc-cli-reference.md) +- [tdc 配置与凭证](/ai/tdc/reference/tdc-configuration-and-credentials.md) +- [tdc 区域、安全与限制](/ai/tdc/reference/tdc-regions-security-and-limitations.md) +- [tdc 故障排查](/ai/tdc/reference/tdc-troubleshooting.md) + +如需报告问题或提出改进建议，请在 [tdc GitHub 仓库](https://github.com/tidbcloud/tdc/issues)创建 issue。 diff --git a/ai/tdc/tdc-quick-start.md b/ai/tdc/tdc-quick-start.md new file mode 100644 index 000000000000..ab1f8169e178 --- /dev/null +++ b/ai/tdc/tdc-quick-start.md @@ -0,0 +1,130 @@ +--- +title: 快速上手 TiDB Cloud CLI（tdc） +summary: 安装和配置 tdc，并完成第一个 TiDB Cloud Starter 数据库或文件系统操作。 +--- + +# 快速上手 TiDB Cloud CLI（tdc） + +本快速上手将帮助你安装 tdc、配置一个 profile，并通过 TiDB Cloud Starter 或 TiDB Cloud 文件系统获得第一个成功结果。 + +> **注意：** +> +> tdc 当前处于预览（Preview）阶段，其功能和命令行界面可能会发生变更，恕不另行通知。 + +## 前置条件 + +开始前，请从 [TiDB Cloud API Keys](https://tidbcloud.com/org-settings/api-keys) 页面获取 API public key 和 private key。该 key 必须能够访问一个 `tidbx_virtual` project。 + +## 第 1 步：安装 tdc + +在 macOS 或 Linux 上： + +```bash +curl -fsSL https://github.com/tidbcloud/tdc/releases/latest/download/install.sh | sh -s -- --yes +export PATH="$HOME/.tdc/bin:$PATH" +tdc --version +``` + +将 `export PATH="$HOME/.tdc/bin:$PATH"` 加入 shell profile，使新终端也能找到 tdc。 + +在 Windows PowerShell 上： + +```powershell +$script = "$env:TEMP\install-tdc.ps1" +iwr https://github.com/tidbcloud/tdc/releases/latest/download/install.ps1 -OutFile $script +powershell -ExecutionPolicy Bypass -File $script -Yes +$env:Path = "$HOME\.tdc\bin;$env:Path" +tdc --version +``` + +## 第 2 步：配置 tdc + +运行交互式配置： + +```bash +tdc configure +``` + +输入 API public key、private key，以及 `aws-us-east-1` 之类的 canonical region code。tdc 会验证 key、发现 `tidbx_virtual` project，并将其保存为默认 project。 + +验证配置： + +```bash +tdc organization list-projects --output text +``` + +## 第 3 步：选择第一个 workflow + +选择完成文件系统或 Starter 数据库 workflow。 + +### 选项 A：写入并读取文件 + +创建文件系统，并在不显示完整结果的情况下获取 owner token： + +```bash +export TDC_FS_TOKEN="$(tdc fs create-file-system \ + --file-system-name quickstart-fs \ + --query fs_token \ + --output text)" +``` + +通过 data plane 写入并读取文件： + +```bash +printf 'hello from tdc\n' | tdc fs copy-file \ + --file-system-name quickstart-fs \ + --from-stdin \ + --to-remote /hello.txt + +tdc fs read-file \ + --file-system-name quickstart-fs \ + --path /hello.txt +``` + +预期输出： + +```text +hello from tdc +``` + +清理： + +```bash +tdc fs delete-file-system \ + --file-system-name quickstart-fs \ + --confirm-file-system-name quickstart-fs +unset TDC_FS_TOKEN +``` + +### 选项 B：查询 Starter 数据库 + +列出集群并选择一个 active cluster ID： + +```bash +tdc db list-db-clusters --output text +export TDC_DB_CLUSTER_ID="" +``` + +如果该集群还没有 tdc 管理的 SQL 用户，则创建这些用户： + +```bash +tdc db create-db-sql-users --db-cluster-id "$TDC_DB_CLUSTER_ID" +``` + +运行只读验证查询： + +```bash +tdc db execute-sql-statement \ + --db-cluster-id "$TDC_DB_CLUSTER_ID" \ + --read-only \ + --sql "SELECT 1 AS ready" \ + --output text +``` + +该命令通过 HTTPS SQL API 执行一条 statement，并返回包含 `ready = 1` 的结果。 + +## 后续步骤 + +- [管理 TiDB Cloud Starter 数据库](/ai/tdc/guides/tdc-starter-database.md) +- [管理 TiDB Cloud 文件系统](/ai/tdc/guides/tdc-filesystem.md) +- [tdc 配置与凭证](/ai/tdc/reference/tdc-configuration-and-credentials.md) From cd88bf5a7b24b4d6752346b37a40dba12747d5f7 Mon Sep 17 00:00:00 2001 From: Cheese Date: Sat, 18 Jul 2026 02:33:14 +0800 Subject: [PATCH 2/4] docs: improve Chinese tdc onboarding and examples --- ai/tdc/examples/tdc-agent-sandbox-example.md | 14 +++- .../tdc-git-workspace-for-agents-example.md | 31 +++++++-- .../tdc-journal-agent-workflow-example.md | 14 +++- .../tdc-query-sql-with-roles-example.md | 14 +++- ...hare-filesystem-across-machines-example.md | 14 +++- .../tdc-vault-agent-secrets-example.md | 14 +++- ai/tdc/guides/tdc-filesystem-git.md | 8 ++- ai/tdc/guides/tdc-install-configure-update.md | 14 ++++ .../tdc-configuration-and-credentials.md | 2 +- .../tdc-regions-security-and-limitations.md | 10 ++- ai/tdc/tdc-quick-start.md | 66 +++++++++++++------ 11 files changed, 164 insertions(+), 37 deletions(-) diff --git a/ai/tdc/examples/tdc-agent-sandbox-example.md b/ai/tdc/examples/tdc-agent-sandbox-example.md index e0ae48a8a58e..cf9e0fae8cef 100644 --- a/ai/tdc/examples/tdc-agent-sandbox-example.md +++ b/ai/tdc/examples/tdc-agent-sandbox-example.md @@ -5,12 +5,24 @@ summary: 在可信机器上创建文件系统，并让全新的 Agent 沙箱在 # 在 Agent Sandbox 中使用 TiDB Cloud 文件系统 -本示例在可信机器上创建文件系统，将最小环境变量传入全新的沙箱，并在不复制 `~/.tdc/` 的情况下使用 tdc。 +本示例让临时 Coding Agent 获得持久工作区，而不需要将用户完整的 tdc 配置复制到沙箱中。 > **注意：** > > tdc 当前处于预览（Preview）阶段，其功能和命令行界面可能会发生变更，恕不另行通知。 +## Agent 面临的问题 + +Coding Agent 通常运行在全新、短生命周期的沙箱中。沙箱被替换后，本地磁盘随之消失，但 Agent 仍然需要之前生成的产物、仓库状态以及其他 worker 写入的文件。重复构建这些状态会浪费任务时间，而复制 `~/.tdc/` 或注入 TiDB Cloud API key，又会让沙箱获得并不需要的控制面权限。 + +## 本地存储和完整云凭证为什么不够 + +沙箱本地目录速度快，但既不持久也不能共享。通用对象存储 API 需要应用自行实现上传和下载逻辑，无法直接支持普通文件操作。给每个沙箱提供用户的完整云凭证虽然能够访问资源，却扩大了安全边界。 + +## tdc 如何改变工作流 + +可信机器只需创建一次文件系统。沙箱仅接收文件系统 owner token、region code 和文件系统名称，无需运行 `tdc configure`，即可使用 data plane、挂载、Git、Journal 和 Vault。Agent 只需要访问特定 secret 时，应使用委派的 Vault token，而不是 owner token。 + ## 前置条件 - 在可信机器上安装并配置 tdc。 diff --git a/ai/tdc/examples/tdc-git-workspace-for-agents-example.md b/ai/tdc/examples/tdc-git-workspace-for-agents-example.md index 45b117383ce7..ecc119da94e0 100644 --- a/ai/tdc/examples/tdc-git-workspace-for-agents-example.md +++ b/ai/tdc/examples/tdc-git-workspace-for-agents-example.md @@ -1,16 +1,28 @@ --- title: 在 TiDB Cloud 文件系统中为 Agent 准备 Git Workspace -summary: 挂载文件系统、创建快速 Git workspace 与 linked worktree、正常使用 Git 并安全清理。 +summary: 快速显示大型 Git workspace，在后台 hydrate clean object，并让 Agent 在完整下载结束前开始工作。 --- # 在 TiDB Cloud 文件系统中为 Agent 准备 Git Workspace -本示例为 agent 准备 repository 和隔离的 linked worktree。 +本示例将大型仓库 clone 从 Agent 启动任务的关键路径中移除。 > **注意：** > > tdc 当前处于预览（Preview）阶段，其功能和命令行界面可能会发生变更，恕不另行通知。 +## Agent 面临的问题 + +临时 Agent 通常需要等待 `git clone` 和 checkout 下载完整仓库，才能查看文件树并开始工作。对于大型 monorepo，每次替换沙箱都要重新承受这段启动延迟，即使 Agent 的第一个任务只需要仓库中的少量文件，它仍然只能等待。 + +## 普通 clone 和 partial clone 为什么不够 + +普通 clone 会一直阻塞到初始 object transfer 和 checkout 完成。原生 blobless partial clone 可以减少首次传输，但后续 Git 命令和文件读取仍可能在 Agent 的关键路径上触发大量按需 fetch。这两种方式本身也不提供可在不同 Agent runtime 之间恢复的共享文件系统 workspace。 + +## tdc 如何改变工作流 + +`tdc fs-git clone-git-workspace --blobless --hydrate background` 会注册 Git workspace，并在所有 clean blob 下载完成前先显示文件树。命令返回后，Agent 可以立即查看路径并开始工作，同时 tdc 在后台 hydrate clean tree 和本地 Git object database。Hydration 尚未完成时发生的读取会回退到 Git lazy fetch，以保证正确性。编辑、commit、fetch 和 push 仍然使用普通 Git。 + ## 前置条件 - 选择一个文件系统。 @@ -26,22 +38,31 @@ tdc fs mount-file-system \ --driver fuse ``` -## 第 2 步：Clone 并 hydrate +## 第 2 步：创建 workspace 并在后台 hydrate ```bash tdc fs-git clone-git-workspace \ --repo-url https://github.com/pingcap/tidb.git \ --target-path /path/to/workspace/tidb \ --blobless \ - --hydrate sync + --hydrate background ``` -验证： +此时 workspace 文件树已经可见，hydration 会继续在后台运行。Agent 可以立即执行普通命令： ```bash +find /path/to/workspace/tidb -maxdepth 2 -type f | head git -C /path/to/workspace/tidb status ``` +在运行确定性 benchmark 或 drain 挂载之前，可以显式等待 hydration 完成： + +```bash +tdc fs-git hydrate-git-workspace \ + --target-path /path/to/workspace/tidb \ + --timeout 30m +``` + ## 第 3 步：创建 agent worktree ```bash diff --git a/ai/tdc/examples/tdc-journal-agent-workflow-example.md b/ai/tdc/examples/tdc-journal-agent-workflow-example.md index 1ba70eaff133..44475889c8cc 100644 --- a/ai/tdc/examples/tdc-journal-agent-workflow-example.md +++ b/ai/tdc/examples/tdc-journal-agent-workflow-example.md @@ -5,12 +5,24 @@ summary: 创建 journal、追加结构化 agent event、搜索 workflow 并验 # 使用文件系统 Journal 记录 Agent Workflow -本示例使用结构化、有序 event 记录 agent task，而不是向可修改文件追加未验证文本。 +本示例使用结构化、有序且可验证的事件历史记录 Agent 任务。 > **注意：** > > tdc 当前处于预览（Preview）阶段，其功能和命令行界面可能会发生变更，恕不另行通知。 +## Agent 面临的问题 + +一个 Agent 任务可能经历规划、工具调用、测试、重试以及多个 worker 之间的交接。任务失败时，运维人员需要知道发生了哪些事件以及准确顺序。普通控制台输出往往分散在多个进程中，而可修改的状态文件通常只保留最后状态。 + +## 向普通文件追加内容为什么不够 + +文本文件写入后仍然可以被修改或截断，没有内置 sequence 和 hash chain，也要求每个 producer 自行设计解析与并发规则。追加操作发生重试时，如果应用没有额外实现幂等逻辑，还可能生成重复事件。 + +## tdc 如何改变工作流 + +文件系统 Journal 保存带 sequence、可搜索字段、可选 idempotency key 和 hash-chain verification 的结构化只追加 entry。Agent 可以追加 `task.started`、`test.finished` 等语义事件；运维人员能够查询工作流并验证已保存的 chain，而不需要将可修改日志文件当作审计证据。 + ## 前置条件 通过已配置 profile 或 FS token 环境选择文件系统。 diff --git a/ai/tdc/examples/tdc-query-sql-with-roles-example.md b/ai/tdc/examples/tdc-query-sql-with-roles-example.md index 80fd0f5f07e2..f48f80e3aea0 100644 --- a/ai/tdc/examples/tdc-query-sql-with-roles-example.md +++ b/ai/tdc/examples/tdc-query-sql-with-roles-example.md @@ -5,12 +5,24 @@ summary: 准备 tdc 管理的 SQL 用户，并以明确权限意图运行只读 # 使用显式 SQL 角色查询 TiDB Cloud Starter -本示例使用全部三个 tdc 管理的 SQL 角色，同时不暴露生成的密码。 +本示例让 Agent 完成 schema、数据写入和结果验证，同时为每条 SQL 明确指定所需权限。 > **注意：** > > tdc 当前处于预览（Preview）阶段，其功能和命令行界面可能会发生变更，恕不另行通知。 +## Agent 面临的问题 + +能够读取数据的 Agent，有时还需要执行 migration 或更新数据。让整个任务共用一个管理员连接最为方便，但 Agent 在检查数据时一旦生成错误 SQL，也会拥有修改或删除数据的权限。只提供只读连接又无法完成合理的写入和 schema 变更。 + +## 单一原生数据库连接为什么不够 + +TiDB 本身支持 SQL 权限，但传统客户端 session 只使用当前连接凭证对应的权限。用户需要自行创建、保存和切换多组凭证，Agent 也可能在任务阶段变化后继续使用权限过高的连接。 + +## tdc 如何改变工作流 + +`tdc db create-db-sql-users` 创建稳定的 read-only、read-write 和 admin 身份，并在本地保存对应凭证。每次执行 `execute-sql-statement` 时都显式选择一个角色，并且一次只执行一条 SQL。Agent 可以使用 admin 修改 schema、使用 read-write 修改数据，再使用 read-only 验证结果，全程无需直接处理密码。 + ## 前置条件 - 配置 tdc。 diff --git a/ai/tdc/examples/tdc-share-filesystem-across-machines-example.md b/ai/tdc/examples/tdc-share-filesystem-across-machines-example.md index 45a96f675d9e..d55df7f8be29 100644 --- a/ai/tdc/examples/tdc-share-filesystem-across-machines-example.md +++ b/ai/tdc/examples/tdc-share-filesystem-across-machines-example.md @@ -5,12 +5,24 @@ summary: 创建一个文件系统，通过安全方式从第二台机器访问 # 在不同机器间共享 TiDB Cloud 文件系统 -本示例在机器 A 上创建文件系统，并在不复制 tdc profile 的情况下让机器 B 访问相同数据。 +本示例让两台机器上的用户或 Agent 共享同一个工作区，无需在机器本地磁盘之间反复复制文件。 > **注意：** > > tdc 当前处于预览（Preview）阶段，其功能和命令行界面可能会发生变更，恕不另行通知。 +## Agent 面临的问题 + +Agent 可能在机器 A 上生成源码或构建产物，然后在机器 B 上继续任务，但每台机器通常只能看到自己的磁盘。每次交接前复制快照会增加延迟，复制后的新变更也不会自动出现在另一台机器上。多个 Agent 同时交接时，还可能产生多个冲突副本，难以判断哪一份才是最新状态。 + +## 本地磁盘和手动同步为什么不够 + +本地磁盘不提供共享命名空间。`scp` 和压缩包上传只能传输某一时刻的副本，而对象存储本身也不是编辑器、构建工具和 Agent 所期待的挂载目录。 + +## tdc 如何改变工作流 + +两台机器选择同一个 TiDB Cloud 文件系统。Data-plane 命令和挂载路径访问同一个远端命名空间，因此任一接口写入并刷出后，另一接口都可以看到结果。机器 B 只需要文件系统 token、region code 和名称，不需要 TiDB Cloud API key，也不需要复制 profile。 + ## 前置条件 - 机器 A 已配置 tdc。 diff --git a/ai/tdc/examples/tdc-vault-agent-secrets-example.md b/ai/tdc/examples/tdc-vault-agent-secrets-example.md index 84772f17d8ac..a171b7419780 100644 --- a/ai/tdc/examples/tdc-vault-agent-secrets-example.md +++ b/ai/tdc/examples/tdc-vault-agent-secrets-example.md @@ -5,12 +5,24 @@ summary: 保存 secret、将一个 field 委派给 agent、注入进程、审计 # 向 Agent 委派文件系统 Vault Secret -本示例在不共享文件系统 owner token 的情况下，向 agent 临时开放一个 field。 +本示例在不共享文件系统 owner token 或完整 secret 的情况下，向 Agent 临时开放一个 secret field。 > **注意：** > > tdc 当前处于预览（Preview）阶段，其功能和命令行界面可能会发生变更，恕不另行通知。 +## Agent 面临的问题 + +Agent 可能只需要一个 API endpoint 或 token 来完成短期任务。把完整 secret 放进 prompt、`.env` 文件或沙箱镜像，会让 secret 暴露给超出所需范围和生命周期的环境。共享文件系统 owner token 同样会授予远多于一个 secret field 的权限。 + +## 普通环境变量和文件为什么不够 + +环境变量和文件可以传递 secret，但不能形成限定 scope、自动过期的委派，也不提供访问审计。独立的云 secret manager 可以提供这些控制，但每个沙箱都需要额外配置一套身份、策略和集成路径。 + +## tdc 如何改变工作流 + +文件系统 owner 只需保存一次 secret，并创建一个仅覆盖所需 field 的短期 grant。Agent 只接收委派的 Vault token，并将允许访问的值注入子进程。Owner 可以检查 audit event 并撤销 grant，而无需轮换或暴露文件系统 owner credential。 + ## 前置条件 - 以 owner access 选择一个文件系统。 diff --git a/ai/tdc/guides/tdc-filesystem-git.md b/ai/tdc/guides/tdc-filesystem-git.md index d987e2dcf801..1c5b53398be8 100644 --- a/ai/tdc/guides/tdc-filesystem-git.md +++ b/ai/tdc/guides/tdc-filesystem-git.md @@ -25,17 +25,19 @@ tdc fs-git clone-git-workspace \ --target-path /path/to/workspace/tidb ``` -对于大型 repository，创建 blobless workspace 并同步 hydrate： +对于大型 repository，创建 blobless workspace 并在后台 hydrate： ```bash tdc fs-git clone-git-workspace \ --repo-url https://github.com/pingcap/tidb.git \ --target-path /path/to/workspace/tidb \ --blobless \ - --hydrate sync + --hydrate background ``` -`--hydrate` 接受 `auto`、`background`、`sync` 或 `off`。 +命令注册 workspace 后便会返回，因此文件树可以立即使用，而 clean content 和 Git object 会继续在后台 hydrate。Hydration 完成前的读取会使用 Git lazy fetch 保证正确性。这样可以将大部分仓库下载工作移出 Agent 启动的关键路径。 + +`--hydrate` 接受 `auto`、`background`、`sync` 或 `off`。调用方必须等待 hydration 完成后再继续时（例如执行确定性 benchmark），使用 `sync`。 ## Hydrate 已有 workspace diff --git a/ai/tdc/guides/tdc-install-configure-update.md b/ai/tdc/guides/tdc-install-configure-update.md index b3080acb33df..da013a5e7387 100644 --- a/ai/tdc/guides/tdc-install-configure-update.md +++ b/ai/tdc/guides/tdc-install-configure-update.md @@ -15,8 +15,15 @@ summary: 安装 tdc release 二进制、以交互或自动化方式配置 profil ### macOS 和 Linux +运行安装程序： + ```bash curl -fsSL https://github.com/tidbcloud/tdc/releases/latest/download/install.sh | sh -s -- --yes +``` + +安装完成后，将 tdc 加入当前 shell 并验证安装： + +```bash export PATH="$HOME/.tdc/bin:$PATH" tdc --version ``` @@ -25,10 +32,17 @@ Installer 会将 `tdc` 和 `tdc-drive9` companion 放入 `~/.tdc/bin`。请将 P ### Windows +运行安装程序： + ```powershell $script = "$env:TEMP\install-tdc.ps1" iwr https://github.com/tidbcloud/tdc/releases/latest/download/install.ps1 -OutFile $script powershell -ExecutionPolicy Bypass -File $script -Yes +``` + +安装完成后，将 tdc 加入当前 PowerShell session 并验证安装： + +```powershell $env:Path = "$HOME\.tdc\bin;$env:Path" tdc --version ``` diff --git a/ai/tdc/reference/tdc-configuration-and-credentials.md b/ai/tdc/reference/tdc-configuration-and-credentials.md index e8d827250eee..77ad32c9a125 100644 --- a/ai/tdc/reference/tdc-configuration-and-credentials.md +++ b/ai/tdc/reference/tdc-configuration-and-credentials.md @@ -43,7 +43,7 @@ Profile 命名空间的选择顺序如下： 2. `TDC_PROFILE`； 3. `default`。 -显式空 profile 无效。环境凭证不会创建 `[env]` profile，也不会修改所选命名空间。 +显式空 profile 无效。 ## TiDB Cloud API 凭证 diff --git a/ai/tdc/reference/tdc-regions-security-and-limitations.md b/ai/tdc/reference/tdc-regions-security-and-limitations.md index aba56e958f65..358afacda846 100644 --- a/ai/tdc/reference/tdc-regions-security-and-limitations.md +++ b/ai/tdc/reference/tdc-regions-security-and-limitations.md @@ -28,10 +28,14 @@ Alibaba Cloud 当前在 tdc 中只支持 Singapore。用户不能配置原始 se ## 文件系统 region -文件系统 endpoint 的可用性由托管的 Drive9 region manifest 解析。本文发布时，TiDB Cloud native Filesystem mode 支持： +文件系统 endpoint 的可用性由托管的 Drive9 region manifest 解析。本文发布时，TiDB Cloud native Filesystem mode 支持以下区域： -- `aws-us-east-1`； -- `aws-ap-southeast-1`。 +| 云服务提供商 | Canonical region code | +| --- | --- | +| AWS | `aws-ap-southeast-1` | +| AWS | `aws-us-east-1` | +| AWS | `aws-us-west-2` | +| Alibaba Cloud | `ali-ap-southeast-1` | 托管的 manifest 是权威来源，在 Preview 阶段可能变化。位于其他 TiDB Cloud region 的 profile 仍可以管理 Starter 数据库，但在 manifest 支持该部署区域之前，文件系统命令会返回 endpoint 不受支持的错误。 diff --git a/ai/tdc/tdc-quick-start.md b/ai/tdc/tdc-quick-start.md index ab1f8169e178..83c101c2fe83 100644 --- a/ai/tdc/tdc-quick-start.md +++ b/ai/tdc/tdc-quick-start.md @@ -13,30 +13,42 @@ summary: 安装和配置 tdc，并完成第一个 TiDB Cloud Starter 数据库 ## 前置条件 -开始前，请从 [TiDB Cloud API Keys](https://tidbcloud.com/org-settings/api-keys) 页面获取 API public key 和 private key。该 key 必须能够访问一个 `tidbx_virtual` project。 +开始前，请从 [TiDB Cloud API Keys](https://tidbcloud.com/org-settings/api-keys) 页面获取 API public key 和 private key。 ## 第 1 步：安装 tdc -在 macOS 或 Linux 上： +在 macOS 或 Linux 上运行安装程序： ```bash curl -fsSL https://github.com/tidbcloud/tdc/releases/latest/download/install.sh | sh -s -- --yes +``` + +安装完成后，将 tdc 加入当前 shell 并验证安装： + +```bash export PATH="$HOME/.tdc/bin:$PATH" tdc --version ``` 将 `export PATH="$HOME/.tdc/bin:$PATH"` 加入 shell profile，使新终端也能找到 tdc。 -在 Windows PowerShell 上： +在 Windows PowerShell 上运行安装程序： ```powershell $script = "$env:TEMP\install-tdc.ps1" iwr https://github.com/tidbcloud/tdc/releases/latest/download/install.ps1 -OutFile $script powershell -ExecutionPolicy Bypass -File $script -Yes +``` + +安装完成后，将 tdc 加入当前 PowerShell session 并验证安装： + +```powershell $env:Path = "$HOME\.tdc\bin;$env:Path" tdc --version ``` +将 `$HOME\.tdc\bin` 加入用户 `PATH`，使新 PowerShell session 也能找到 tdc。 + ## 第 2 步：配置 tdc 运行交互式配置： @@ -45,7 +57,7 @@ tdc --version tdc configure ``` -输入 API public key、private key，以及 `aws-us-east-1` 之类的 canonical region code。tdc 会验证 key、发现 `tidbx_virtual` project，并将其保存为默认 project。 +输入 API public key、private key，以及 `aws-us-east-1` 之类的 canonical region code。 验证配置： @@ -59,26 +71,23 @@ tdc organization list-projects --output text ### 选项 A：写入并读取文件 -创建文件系统，并在不显示完整结果的情况下获取 owner token： +创建文件系统并将其设为默认文件系统： ```bash -export TDC_FS_TOKEN="$(tdc fs create-file-system \ +tdc fs create-file-system \ --file-system-name quickstart-fs \ - --query fs_token \ - --output text)" + --set-default \ + --output text ``` -通过 data plane 写入并读取文件： +tdc 会在本地保存文件系统凭证。接下来可以直接写入并读取文件： ```bash printf 'hello from tdc\n' | tdc fs copy-file \ - --file-system-name quickstart-fs \ --from-stdin \ --to-remote /hello.txt -tdc fs read-file \ - --file-system-name quickstart-fs \ - --path /hello.txt +tdc fs read-file --path /hello.txt ``` 预期输出： @@ -93,27 +102,37 @@ hello from tdc tdc fs delete-file-system \ --file-system-name quickstart-fs \ --confirm-file-system-name quickstart-fs -unset TDC_FS_TOKEN ``` ### 选项 B：查询 Starter 数据库 -列出集群并选择一个 active cluster ID： +创建 Starter 集群并保存其 ID： ```bash -tdc db list-db-clusters --output text -export TDC_DB_CLUSTER_ID="" +export TDC_DB_CLUSTER_ID="$(tdc db create-db-cluster \ + --db-cluster-name quickstart-db \ + --db-cluster-type starter \ + --query id \ + --output text)" ``` -如果该集群还没有 tdc 管理的 SQL 用户，则创建这些用户： +等待集群进入 active 状态： ```bash -tdc db create-db-sql-users --db-cluster-id "$TDC_DB_CLUSTER_ID" +until [ "$(tdc db describe-db-cluster \ + --db-cluster-id "$TDC_DB_CLUSTER_ID" \ + --query state \ + --output text)" = "ACTIVE" ]; do + sleep 5 +done ``` -运行只读验证查询： +创建 SQL 用户并运行只读验证查询： ```bash +tdc db create-db-sql-users \ + --db-cluster-id "$TDC_DB_CLUSTER_ID" + tdc db execute-sql-statement \ --db-cluster-id "$TDC_DB_CLUSTER_ID" \ --read-only \ @@ -123,6 +142,13 @@ tdc db execute-sql-statement \ 该命令通过 HTTPS SQL API 执行一条 statement，并返回包含 `ready = 1` 的结果。 +清理资源： + +```bash +tdc db delete-db-cluster --db-cluster-id "$TDC_DB_CLUSTER_ID" +unset TDC_DB_CLUSTER_ID +``` + ## 后续步骤 - [管理 TiDB Cloud Starter 数据库](/ai/tdc/guides/tdc-starter-database.md) From 090b8bba9ca134cf94380df7a5a4a3bbe51e7b50 Mon Sep 17 00:00:00 2001 From: Cheese Date: Sat, 18 Jul 2026 22:33:24 +0800 Subject: [PATCH 3/4] docs: document unified wait behavior --- ai/tdc/examples/tdc-agent-sandbox-example.md | 1 + ...-share-filesystem-across-machines-example.md | 1 + ai/tdc/guides/tdc-filesystem.md | 8 ++++++-- ai/tdc/guides/tdc-starter-database.md | 10 ++++++---- ai/tdc/tdc-quick-start.md | 17 +++++------------ 5 files changed, 19 insertions(+), 18 deletions(-) diff --git a/ai/tdc/examples/tdc-agent-sandbox-example.md b/ai/tdc/examples/tdc-agent-sandbox-example.md index cf9e0fae8cef..33fa2a7efed9 100644 --- a/ai/tdc/examples/tdc-agent-sandbox-example.md +++ b/ai/tdc/examples/tdc-agent-sandbox-example.md @@ -34,6 +34,7 @@ Coding Agent 通常运行在全新、短生命周期的沙箱中。沙箱被替 ```bash export TDC_FS_TOKEN="$(tdc fs create-file-system \ --file-system-name agent-sandbox \ + --wait \ --query fs_token \ --output text)" ``` diff --git a/ai/tdc/examples/tdc-share-filesystem-across-machines-example.md b/ai/tdc/examples/tdc-share-filesystem-across-machines-example.md index d55df7f8be29..c469e1777d3b 100644 --- a/ai/tdc/examples/tdc-share-filesystem-across-machines-example.md +++ b/ai/tdc/examples/tdc-share-filesystem-across-machines-example.md @@ -34,6 +34,7 @@ Agent 可能在机器 A 上生成源码或构建产物，然后在机器 B 上 ```bash export TDC_FS_TOKEN="$(tdc fs create-file-system \ --file-system-name shared-workspace \ + --wait \ --query fs_token \ --output text)" diff --git a/ai/tdc/guides/tdc-filesystem.md b/ai/tdc/guides/tdc-filesystem.md index 293cba88a381..b503b30f718d 100644 --- a/ai/tdc/guides/tdc-filesystem.md +++ b/ai/tdc/guides/tdc-filesystem.md @@ -26,14 +26,18 @@ Data-plane 命令也可以通过 `TDC_FS_TOKEN`、`TDC_REGION_CODE` 和 `TDC_FS_ ```bash tdc fs create-file-system \ --file-system-name workspace \ - --set-default + --set-default \ + --wait ``` +不指定 `--wait` 时，Drive9 接受异步创建请求后 tdc 立即返回。指定该 flag 后，tdc 最多等待 10 分钟，直到可以通过公开的 Drive9 data-plane CLI 读取根目录。等待失败不会删除资源或本地保存的凭证。 + JSON 响应包含 `fs_token`。在不显示完整结果的情况下获取： ```bash export TDC_FS_TOKEN="$(tdc fs create-file-system \ --file-system-name sandbox \ + --wait \ --query fs_token \ --output text)" ``` @@ -66,7 +70,7 @@ tdc fs delete-file-system \ --confirm-file-system-name workspace ``` -Create 和 delete 支持 `--dry-run`。删除需要 TiDB Cloud API key 和本地已注册资源；仅有 FS token 不能删除资源。 +Create 和 delete 支持 `--dry-run`。删除需要 TiDB Cloud API key 和本地已注册资源；仅有 FS token 不能删除资源。Drive9 的删除是异步操作，请求成功被接受时返回 `status: "deleting"`，同时 tdc 会移除所选资源的本地 registry entry 和凭证。 ## 在多个文件系统中选择 diff --git a/ai/tdc/guides/tdc-starter-database.md b/ai/tdc/guides/tdc-starter-database.md index b73de231a0e6..2c88fed55367 100644 --- a/ai/tdc/guides/tdc-starter-database.md +++ b/ai/tdc/guides/tdc-starter-database.md @@ -66,10 +66,11 @@ tdc db delete-db-cluster \ --dry-run tdc db delete-db-cluster \ - --db-cluster-id "" + --db-cluster-id "" \ + --wait ``` -tdc 会在内部解析集群名称，无需名称确认 flag。 +tdc 会在内部解析集群名称，无需名称确认 flag。不指定 `--wait` 时，TiDB Cloud 接受异步删除请求后命令立即返回。指定该 flag 后，tdc 最多等待 12 分钟，直到集群状态为 `DELETED` 或无法再访问。 ## 管理分支 @@ -78,14 +79,15 @@ tdc 会在内部解析集群名称，无需名称确认 flag。 ```bash tdc db create-db-cluster-branch \ --db-cluster-id "" \ - --db-cluster-branch-name development + --db-cluster-branch-name development \ + --wait tdc db list-db-cluster-branches \ --db-cluster-id "" \ --page-size 20 ``` -使用 `--page-token` 继续读取分页 branch list。 +使用 `--page-token` 继续读取分页 branch list。不指定 `--wait` 时，创建请求被接受后命令立即返回；指定该 flag 后，tdc 最多等待五分钟，直到分支状态为 `ACTIVE`。 查看并删除分支： diff --git a/ai/tdc/tdc-quick-start.md b/ai/tdc/tdc-quick-start.md index 83c101c2fe83..93742aba69a4 100644 --- a/ai/tdc/tdc-quick-start.md +++ b/ai/tdc/tdc-quick-start.md @@ -77,6 +77,7 @@ tdc organization list-projects --output text tdc fs create-file-system \ --file-system-name quickstart-fs \ --set-default \ + --wait \ --output text ``` @@ -112,21 +113,11 @@ tdc fs delete-file-system \ export TDC_DB_CLUSTER_ID="$(tdc db create-db-cluster \ --db-cluster-name quickstart-db \ --db-cluster-type starter \ + --wait \ --query id \ --output text)" ``` -等待集群进入 active 状态： - -```bash -until [ "$(tdc db describe-db-cluster \ - --db-cluster-id "$TDC_DB_CLUSTER_ID" \ - --query state \ - --output text)" = "ACTIVE" ]; do - sleep 5 -done -``` - 创建 SQL 用户并运行只读验证查询： ```bash @@ -145,7 +136,9 @@ tdc db execute-sql-statement \ 清理资源： ```bash -tdc db delete-db-cluster --db-cluster-id "$TDC_DB_CLUSTER_ID" +tdc db delete-db-cluster \ + --db-cluster-id "$TDC_DB_CLUSTER_ID" \ + --wait unset TDC_DB_CLUSTER_ID ``` From be1832f027ac98f02bc6e3d7c41d59ffabb8722a Mon Sep 17 00:00:00 2001 From: Cheese Date: Sun, 19 Jul 2026 02:56:57 +0800 Subject: [PATCH 4/4] docs: add Docker FUSE mount guidance --- ai/tdc/guides/tdc-filesystem.md | 82 +++++++++++++++++++++++++++++++++ 1 file changed, 82 insertions(+) diff --git a/ai/tdc/guides/tdc-filesystem.md b/ai/tdc/guides/tdc-filesystem.md index b503b30f718d..dcec1e5e5e94 100644 --- a/ai/tdc/guides/tdc-filesystem.md +++ b/ai/tdc/guides/tdc-filesystem.md @@ -221,6 +221,88 @@ tdc fs mount-file-system \ | Linux | FUSE | FUSE3 和 `/dev/fuse` 访问权限；显式 WebDAV 需要 `davfs2` | FUSE 支持 drain 和 cache 控制 | | Windows | WebDAV | Windows WebClient service | Mount path 必须是 `X:` 之类的 drive letter；不支持 FUSE 和 vault mount | +### 在 Docker 和 Docker Compose 中挂载 + +只在镜像内安装 FUSE3 并不足以完成挂载。Docker host 必须提供 `/dev/fuse`，并授予容器执行 mount 的权限。以下 Dockerfile 安装 Ubuntu 所需软件包和 tdc，但不会把任何 cloud 或 Filesystem 凭证写入镜像： + +```dockerfile +FROM ubuntu:24.04 + +ARG TDC_VERSION=latest + +RUN apt-get update \ + && apt-get install -y --no-install-recommends ca-certificates curl fuse3 \ + && rm -rf /var/lib/apt/lists/* + +RUN curl -fsSL https://github.com/tidbcloud/tdc/releases/latest/download/install.sh \ + | sh -s -- --yes --version "${TDC_VERSION}" + +ENV PATH="/root/.tdc/bin:${PATH}" + +RUN mkdir -p /workspace + +CMD ["bash"] +``` + +构建镜像，然后在运行时传入 Filesystem owner token、canonical region code 和 Filesystem name： + +```bash +docker build -t tdc-fuse . + +docker run --rm -it \ + --device /dev/fuse \ + --cap-add SYS_ADMIN \ + --security-opt apparmor=unconfined \ + --env TDC_FS_TOKEN \ + --env TDC_REGION_CODE \ + --env TDC_FS_FILE_SYSTEM_NAME \ + tdc-fuse +``` + +这三个环境变量必须已经存在于 host shell。进入容器后，按照普通文件系统方式进行挂载和使用： + +```bash +tdc fs mount --mount-path /workspace +printf 'hello from Docker\n' > /workspace/hello.txt +tdc fs drain --mount-path /workspace +tdc fs umount --mount-path /workspace +``` + +在 `compose.yaml` 中配置等价的运行时设置： + +```yaml +services: + agent: + build: + context: . + args: + TDC_VERSION: latest + devices: + - /dev/fuse:/dev/fuse + cap_add: + - SYS_ADMIN + security_opt: + - apparmor=unconfined + environment: + TDC_FS_TOKEN: ${TDC_FS_TOKEN} + TDC_REGION_CODE: ${TDC_REGION_CODE} + TDC_FS_FILE_SYSTEM_NAME: ${TDC_FS_FILE_SYSTEM_NAME} + stdin_open: true + tty: true +``` + +启动交互式容器： + +```bash +docker compose run --rm agent +``` + +`fuse3` 会提供 `/usr/bin/fusermount3`。如果挂载返回 `fusermount3: mount failed: Permission denied`，请确认 host 存在 `/dev/fuse`，并确认所有必要的 `devices`、`cap_add` 和 AppArmor 设置均已传入容器。`apparmor=unconfined` 适用于 Ubuntu 等启用了 AppArmor 的 host；未启用 AppArmor 时可以省略。 + +> **警告：** +> +> `SYS_ADMIN` 和不受限制的 AppArmor profile 会削弱容器隔离。仅在专用且可信的 agent container 中使用。Rootless Docker 和 managed container platform 可能禁止这些设置；无法授予 FUSE 权限时，请改用无需 mount 的 tdc fs data-plane 命令。Mount 位于容器的 mount namespace，容器停止后就会消失，因此在停止可能仍有 pending write 的容器前执行 drain 和 unmount。 + 即使安装了 macFUSE，macOS 的自动选择也始终是 WebDAV。如需使用 FUSE，请从 [macFUSE 官网](https://macfuse.github.io/)安装受支持版本，完成 installer 要求的批准或重启，然后执行： ```bash