Xata 是一个开源、云原生的 Postgres 平台，基于 Kubernetes 构建，提供写时复制（CoW）分支、缩容至零、自动扩缩容、高可用、PITR 备份以及无服务器 SQL 驱动。它构建在 CloudNativePG 与 OpenEBS 之上。
架构概览
平台由多个组件构成：CLI 通过 REST API（clusters/projects 服务）交互；SQL Gateway 负责连接路由与缩容至零唤醒；Branch Operator 管理每个分支对应的 Kubernetes 资源；Auth Service 基于 Keycloak，提供 RBAC API 密钥。底层依赖 CloudNativePG（高可用、故障转移、备份、连接池）与 OpenEBS（本地 NVMe 或 Mayastor 复制存储）。
前置条件
需要 Docker、Kind、Tilt、kubectl。
本地开发环境搭建
第一步：创建 Kind 集群，执行 kind create cluster --wait 10m。
第二步：使用 Tilt 部署，执行 tilt up，等待所有资源就绪。首次运行需下载镜像，耗时较长；后续运行较快。
第三步：安装并认证 CLI。安装命令为 curl -fsSL https://xata.io/install.sh | bash。认证到本地 profile 使用默认凭据 email=dev@xata.tech、password=Xata1234!，命令为 xata auth login --profile local --env local --force，然后切换 profile：xata auth switch local。
第四步：创建项目与分支。创建项目：xata project create --name my-project；创建子分支（父分支的 CoW 副本）：xata branch create。
CLI 参考
认证：登录 Xata Cloud 使用 xata auth login；登录自托管本地实例使用 xata auth login --profile local --env local --force；切换 profile 使用 xata auth switch local 或 xata auth switch default；列出 profile 使用 xata auth list。
项目：创建 xata project create --name my-project；列出 xata project list；获取详情 xata project get <project-id>；删除 xata project delete <project-id>。
分支：创建分支（父分支的 CoW 快照，即使 TB 级数据也能在数秒内完成）使用 xata branch create；从指定父分支创建命名分支使用 xata branch create --name feature-xyz --from main；列出 xata branch list；获取详情 xata branch get <branch-id>；删除 xata branch delete <branch-id>。
连接分支：获取连接字符串 xata branch connection-string <branch-id>；通过 psql 连接 psql "$(xata branch connection-string <branch-id>)"。
配置
环境变量：XATA_API_URL（自托管 API 端点，如 http://localhost:8080）、XATA_API_KEY（认证密钥）、XATA_PROJECT_ID（默认项目 ID）。
API 密钥管理（RBAC）：创建带特定权限的密钥 xata apikey create --name ci-key --role branch:read,branch:write；列出 xata apikey list；撤销 xata apikey delete <key-id>。
无服务器 SQL 驱动（通过 HTTP/WebSockets 执行 SQL）
Xata 提供无服务器驱动，可通过 HTTP 或 WebSockets 执行 SQL，适用于边缘函数及无持久 TCP 连接的环境。资料中给出了 Go 语言通过 HTTP 执行 SQL 查询的示例代码，以及使用 pgx 直接连接 Postgres 的 Go 示例代码。
常见模式
预览环境工作流（CI/CD）：为每个 PR 创建独立分支用于隔离测试，合并后销毁。资料提供了 create-preview.sh 与 cleanup-preview.sh 脚本示例，以及 GitHub Actions 集成配置示例。
编程式分支管理（Go）：资料提供了使用 Go 通过 REST API 创建与删除分支的客户端示例代码。
缩容至零
分支在闲置后自动休眠，并在下次连接时唤醒。SQL Gateway 透明处理唤醒过程，客户端在休眠后首次连接时可能经历短暂延迟（约数秒）。手动休眠：xata branch hibernate <branch-id>；唤醒：xata branch wake <branch-id>；检查分支状态（running、hibernated、starting）：xata branch get <branch-id> --output json | jq '.state'。
故障排查
Tilt/Kind 问题：检查所有 pod 运行状态 kubectl get pods -A；检查 Xata 相关 pod kubectl get pods -n xata；查看特定组件日志 kubectl logs -n xata -l app=sql-gateway --tail=100 等；资源卡住时重启 tilt down && tilt up。
分支卡在 Provisioning：检查 branch operator 日志、CloudNativePG 集群状态、OpenEBS 存储。
SQL Gateway 连接被拒：验证服务运行 kubectl get svc -n xata sql-gateway；本地测试端口转发 kubectl port-forward -n xata svc/sql-gateway 5432:5432；测试连接 psql。
CLI 认证失败：重新认证、验证当前 profile、检查 API 密钥有效性。
检查缩容至零插件：验证 CNPG 插件安装、检查集群休眠注解。
关键组件参考
SQL Gateway：连接路由、缩容至零唤醒、HTTP/WS 无服务器驱动。Branch Operator：每个分支的 Kubernetes 资源生命周期。clusters 服务：集群管理 REST API。projects 服务：项目管理 REST API。Auth 服务：基于 Keycloak 的认证、RBAC API 密钥。CloudNativePG：高可用 Postgres、故障转移、备份、连接池。OpenEBS：云原生存储（本地 NVMe 或 Mayastor 复制）。
使用场景决策指南
内部 Postgres-as-a-Service：适合使用 Xata OSS。带 CoW 的预览/测试/开发环境：适合使用。单一 Postgres 实例：建议使用普通 Postgres 或托管服务。面向终端客户的公共 PGaaS：建议联系 Xata 了解 BYOC 方案。