documenting-warehouse-sources

记录数据仓库来源

面向用户的来源文档位于 posthog.com 仓库（不是本仓库）中的 contents/docs/cdp/sources/<slug>.md，同时通过 /docs/cdp/sources/<slug> 和 /docs/data-warehouse/sources/<slug> 提供访问。本技能定义了每篇来源文档都必须遵循的统一结构。在发布新来源时，请搭配 /implementing-warehouse-sources 一起使用。

假设有一个同级的 posthog.com 检出（例如 ../posthog.com）。

网站为你渲染的两样东西

你不需要手写连接字段或表列表——二者都来自网站在构建时获取的 public_source_configs API，并通过 MDX 组件镜像到文档中：

• <SourceParameters /> 从 get_source_config.fields 渲染连接/配置表单字段。
• <SourceTables /> 从来源的 get_documented_tables() 渲染支持的表参考（表名、描述、同步方式、增量字段、主键）。

只有当来源在其来源类上设置 lists_tables_without_credentials = True 来选择启用时，<SourceTables /> 才有数据（仅当 get_schemas 遍历一个静态端点目录且没有 I/O 时才有效——参见 /implementing-warehouse-sources）。否则它会渲染一条通用的“从你的账户中发现”说明。如果某张表缺失或其描述过于单薄，请修复来源代码（settings.py 端点 + canonical_descriptions.py），而不是修复文档——文档只是渲染 API 返回的内容，因此代码始终是唯一事实来源。

Frontmatter

---
title: Linking <Source> as a source
sidebar: Docs
showTitle: true
availability: { free: full, selfServe: full, enterprise: full }
sourceId: <EnumValue> # MUST equal the ExternalDataSourceType value, e.g. ActiveCampaign, Stripe
beta: true # optional — only for beta sources
---

sourceId 是将文档链接到其 API 配置（图标、字段、表）的关键。如果弄错了，文档将无法渲染出 <SourceParameters /> / <SourceTables /> 数据。它必须是真实的 ExternalDataSourceType 值（PascalCase，例如 ActiveCampaign，而不是 Active Campaign）。

规范模板

---
title: Linking <Source> as a source
sidebar: Docs
showTitle: true
availability: { free: full, selfServe: full, enterprise: full }
sourceId: <EnumValue>
---

import SourceSetupIntro from "../_snippets/source-setup-intro.mdx"
import SyncModes from "../_snippets/sync-modes.mdx"
import TroubleshootingLink from "../_snippets/dw-troubleshooting-link.mdx"



One or two sentences: what this connector syncs and the typical use case.

## Prerequisites

Account tier / admin rights / API access the user needs before they can connect.

## Adding a data source

<SourceSetupIntro />

List the specific credentials this source needs and exactly where to get them (link to the provider's
dashboard). For sources with more than one auth method, use `###` subsections (mirror Stripe's
"Option 1 / Option 2").

## Sync modes

<SyncModes />

Add any source-specific recommendation here (e.g. "use webhooks for Stripe").

## Configuration

<SourceParameters />

## Supported tables

<SourceTables />

## Troubleshooting

Source-specific errors and fixes (optional but encouraged), then:

<TroubleshootingLink />

必需部分（每个来源）

状态提示（仅 alpha/beta）→ 简介 → 前置条件 → 添加数据来源 → 同步模式 → 配置 → 支持的表 → 故障排查。

可选部分（在适用时）

Webhook（实时同步）、CDC（数据库）、列选择、行过滤、入站 IP 地址 （<InboundIpAddresses />）、数据类型处理、已知限制、ERD/关系。仓库中已有的参考实现：Stripe（SaaS + webhook）、Postgres（数据库 + CDC）、 ClickHouse（数据库）。不要发明来源不需要的部分。

共享片段

复用这些片段，而不是重写相同的文字（它们位于 contents/docs/cdp/_snippets/）：

• source-setup-intro.mdx —— 标准的“添加数据来源”步骤。
• sync-modes.mdx —— 同步模式摘要，链接到规范说明。
• alpha-release.mdx / beta-release.mdx —— 状态提示（还要在 frontmatter 中设置 beta: true）。
• dw-troubleshooting-link.mdx —— 故障排查/支持页脚。
• inbound-ip-addresses.mdx —— 数据库来源的 IP 允许列表表格。
• feedback-questions.mdx —— 反馈/FAQ 页脚。

.md 来源文档支持 MDX import（例如 convex.md、mongodb.md），因此你无需重命名为 .mdx 即可使用片段——但 .mdx 也可以。CalloutBox、ProductScreenshot、SourceParameters 和 SourceTables 是全局组件——无需导入。

docsUrl / slug 规则（防止出现 404）

网站会从源数据的 docsUrl（其最后一段 /docs/cdp/sources/<slug>）推导出文档 slug，因此以下三者必须一致：

1. 文档文件名：<slug>.md。
2. get_source_config 中源数据的 docsUrl：https://posthog.com/docs/cdp/sources/<slug>。
3. （隐式地）列表链接 —— 现在从 docsUrl 推导，因此会自动跟随。

多词 slug 请使用 kebab-case（active-campaign，而非 activecampaign）。在编写或重命名 文档后，请从此（posthog）仓库运行审计：

python manage.py audit_source_docs --docs-dir ../posthog.com/contents/docs/cdp/sources

如果任何源数据的 docsUrl 指向缺失的文件，或任何文档的 sourceId 不是真实存在的源数据，它就会失败。 重命名已发布的文档还需要在 posthog.com/vercel.json 中为 /docs/cdp/sources/* 和 /docs/data-warehouse/sources/* 两者添加 301 重定向。

检查清单

• Frontmatter 中的 sourceId 与 ExternalDataSourceType 值完全一致
• 简介、先决条件、添加数据源、同步模式、配置、支持的表、故障排查
• 状态片段 + 若为 alpha/beta 则 beta: true
• 使用共享片段，而非定制化的文字描述
• 存在 <SourceParameters /> 和 <SourceTables />（不要手写字段或表列表）
• 如果渲染出的表列表为空或过少，且该源数据是固定 schema，则丰富其代码 （lists_tables_without_credentials、settings.py、canonical_descriptions.py）—— 参见 /implementing-warehouse-sources
• 文件名、docsUrl 和 slug 三者一致（kebab-case）
• audit_source_docs 通过