self-hosted-funnel-launch

自托管漏斗上线

使用 Autonnel（Apache-2.0），在由运营者掌控的基础设施上，从零开始构建并发布漏斗。此技能是构建步骤；请先使用 sales-funnel-blueprint 设计漏斗，如果尚未确定是否适合自托管，再使用 funnel-platform-picker 做出确认。

第 1 步：选择运行方式

方案	低流量时的成本	运维负担	适用场景
Cloudflare Workers	几乎为 $0，另加 Postgres 费用	无需服务器，无需打补丁	生产环境的默认选择。 漏斗页面大多是静态资源，Workers 可免费且不限量地提供这些资源
Docker	一台 VPS 或容器主机的费用	由你负责：升级、备份、正常运行时间	两分钟内进行本地评估，或用于你已在运行且希望数据存储在其上的服务器
源代码检出（Node）	一台 VPS 或容器主机的费用	由你负责	修改 Autonnel 本身，或直接运行 Node 构建

除非运营者有具体原因不选 Workers，否则建议使用 Workers：其定价模式几乎完全契合漏斗需求，并且省去了让人们不愿自托管的整类工作。

无论如何，都可以先用 Docker 了解产品。这是最快的体验方式，而且你在本地构建的内容都不会白费：两种方案使用相同的架构和管理 UI。

第 2a 步：Cloudflare Workers（近乎免费的生产方案）

为什么成本接近于零

漏斗流量绝大部分是对页面、图片和脚本的请求。在 Workers 上，这些都是静态资源请求，免费且不限量，也不收取存储费用——只有会调用 Worker 的请求（服务端渲染页面、结账、API）才会计费。漏斗的动态部分很少：订单表单、追加销售接受操作、回传队列。

已核实的 Cloudflare 免费套餐限制（于 2026-08 检查；依赖这些数据前请确认当前数值）：

资源	Workers 免费套餐
静态资源请求	免费且不限量，不收取存储费用
Worker 调用次数	每天 100,000 次请求
Hyperdrive（Postgres 连接池）	免费套餐可用，每天 100,000 次数据库查询
Workers KV（页面缓存）	每天 100,000 次读取、1,000 次写入、1 GB 存储空间
Cron Triggers	支持（仓库提供了一个 scheduled 处理程序）

不免费的项目：Postgres。Hyperdrive 会为你提供的数据库建立连接池，因此你仍需要 Postgres 服务提供商。托管服务提供商各有其免费套餐和限制，这是唯一需要纳入预算的项目。

你真正先遇到的上限会是 KV 写入次数，而非请求数。 每天 1,000 次写入足以应付页面服务，但发布时可能不够，因为发布会使缓存条目失效并刷新条目。繁忙的一天可能会耗尽写入次数，而流量仍远未触及任何限制。如果发布开始失败，而流量没有问题，那就是这个限制所致，不是程序错误。

部署

此仓库包含完整的 Workers 工具链：Worker 入口及 cron scheduled 处理程序（src/cf-worker.ts）、wrangler.toml 生成、KV 缓存接线，以及用于 Postgres 的 Hyperdrive。

npx wrangler login
npx wrangler kv namespace create CACHE_KV
# $DATABASE_URL is the operator's own Postgres connection string, exported in their
# shell - do not write the credentials into this command or into wrangler.toml.
npx wrangler hyperdrive create autonnel-db --connection-string="$DATABASE_URL"

每条命令都会输出一个 ID。将它们放入项目旁的 .env 文件中：

CF_WORKER_NAME=my-funnels
CF_KV_NAMESPACE_ID=<id from kv namespace create>
CF_HYPERDRIVE_CONFIG_ID=<id from hyperdrive create>

然后设置密钥并部署：

npx wrangler secret put DATABASE_URL
npx wrangler secret put AUTH_SESSION_SECRET            # openssl rand -hex 32
npx wrangler secret put CREDENTIALS_ENCRYPTION_KEY     # openssl rand -base64 32
npm run deploy:cf

deploy:cf 会先构建并根据模板生成 wrangler.toml，因此无需单独执行生成步骤。Cron 表达式从应用的 cron 注册表读取，而不是手动写入配置——请勿手动编辑生成的 wrangler.toml，因为每次构建都会覆盖它。

如果缺少某个 CF_* 变量，生成过程会失败并指出该变量。这是预期行为；这些变量没有静默默认值。

首次访问前，请在同一个 Postgres 上应用一次数据库架构，然后打开 Worker URL 并完成 /setup 向导来创建管理员账户。

还提供了：npm run dev:cf（在 Workers 运行时上启动开发服务器）和 npm run preview:cf（通过 wrangler dev 进行本地预览）。如果目标是 Workers，请优先使用这些命令，而不是直接运行 astro dev，因为运行时有所不同。

后续运行

以下 CLI 命令需要访问数据库，而不是容器。在 DATABASE_URL 指向同一个 Postgres 的代码检出目录中运行：

npx autonnel admin:create [email protected] 'a-strong-password'
npx autonnel password:reset [email protected]

第 2b 步：Docker（本地评估或自有服务器）

从 https://github.com/autonnel/autonnel（Apache-2.0）获取仓库，检出一个发布标签，并阅读其 docker-compose.yml——其中声明了将要运行的镜像和端口。在该检出目录中运行：

docker compose up

打开 http://localhost:4321 并完成 /setup。Compose 文件会启动 Postgres、应用架构并运行应用。启动无需其他操作：存储、支付、媒体存储、电子邮件和 AI 都可稍后在管理界面中配置，并且仅在实际使用相关功能时才需要配置。

在将其公开到公网主机之前，请将真实密钥放入 docker-compose.yml 旁的 .env 文件中——随附的默认值是不安全的开发用值，仅用于让首次本地运行无需任何配置：

AUTH_SESSION_SECRET=$(openssl rand -hex 32)
CREDENTIALS_ENCRYPTION_KEY=$(openssl rand -base64 32)
ADMIN_DOMAIN=admin.example.com

每个值只生成一次并保持稳定。轮换 AUTH_SESSION_SECRET 会使会话失效；轮换 CREDENTIALS_ENCRYPTION_KEY 会导致已存储的服务提供商凭据无法读取，这意味着必须重新输入所有支付和平台凭据。

GHCR 上发布了多架构镜像，可通过普通的 docker run 命令连接现有数据库：

# DATABASE_URL, AUTH_SESSION_SECRET and CREDENTIALS_ENCRYPTION_KEY come from the
# operator's own environment - never write their values into a command or a file.
docker run -p 4321:4321 \
  -e DATABASE_URL \
  -e AUTH_SESSION_SECRET \
  -e CREDENTIALS_ENCRYPTION_KEY \
  -e ADMIN_DOMAIN="admin.example.com" \
  ghcr.io/autonnel/autonnel:v1.5.0

请固定使用确切的标签，而不是 :latest，并在拉取更新的标签后重新应用架构——Compose 文件中的一次性架构服务会在每次 docker compose up 时重新运行。编排器的健康检查端点：/api/health（涵盖数据库和缓存的连接情况）。

容器内的管理员 CLI：

docker compose exec app node dist/cli/index.js admin:create [email protected] 'a-strong-password'

第 2c 步：检出源码（Node）

用于修改 Autonnel 本身，或在你已有的主机上运行 Node 构建。需要 Node 22+ 和一个 Postgres：

npm create autonnel@latest my-funnel
cd my-funnel
cp .env.example .env   # set DATABASE_URL and ADMIN_DOMAIN
pnpm install           # pnpm 10+; the repo pins overrides npm would ignore
npm run db:push
npm run dev            # or: npm run build && npm run start

此操作会克隆仓库并移除其 Git 历史记录。架构位于检出目录中的 prisma/schema.prisma；db:push 会同步该架构。管理员 CLI：在项目目录中运行 npx autonnel admin:create [email protected] 'a-strong-password'。

第 3 步：只配置转化漏斗所需的内容

在管理界面的 Settings 中：

设置	用途	选项
Ecommerce	产品和订单数据	Shopify、WooCommerce、Picocart
Payments	收款	Stripe、PayPal
Storage	图片/视频上传	任意兼容 S3 的存储桶（R2、S3、MinIO）
Email	收据、召回活动	SMTP、Resend、AWS SES
LLM	AI 页面生成	任意兼容 OpenAI 的端点
Ad platforms	服务端转化（全部四个平台）；广告级支出/点击报告（仅 Facebook、Google Ads、TikTok）	Facebook、TikTok、Google Ads、Bing

按此顺序操作可避免返工：先配置目录（它会限制结账可以销售的内容），再配置支付，然后是存储、电子邮件，最后配置广告平台——追踪需要对照真实订单进行验证，因此必须先确保其他部分正常运行。连接广告平台以查看支出报告，与将其绑定到转化漏斗以进行回传是两个独立步骤（参见 server-side-conversion-tracking）；如果两者都需要，请都完成。

在 Workers 上，R2 是显而易见的存储选择：它兼容 S3，且媒体流出流量留在 Cloudflare 内部。

第 4 步：构建页面

转化漏斗中的角色直接对应转化漏斗规范：

转化漏斗中的角色	用途	每个转化漏斗可有多个？
LANDING	入口页面（每种流量角度一个）	可以
CHECKOUT	订单表单	不可以——每个转化漏斗只能有一个
UPSELL	购买后的加购优惠，按顺序组成链	可以
THANKYOU	确认页面	不可以
ERROR	支付失败/备用页面	不可以

这些是页面在转化漏斗内部承担的角色。通过 API 查询时，页面自身的类型为 CHECKOUT | THANKYOU | ERROR | UPSELL | CUSTOM——落地页会以 CUSTOM 类型创建，并通过绑定到转化漏斗中的 LANDING 角色成为落地页。

有两种编辑器可用：基于组件的可视化编辑器（其输出为可比较差异的 JSON），以及用于导入页面的原始 HTML。对于任何计划进行 A/B 测试或之后由 Agent 编辑的页面，优先使用组件编辑器——JSON 差异易于审查，HTML 代码块则不然。

先构建结账页面，再构建落地页。结账页面决定了实际可以销售什么以及售价多少；如果先编写落地页，就可能承诺结账页面无法提供的内容。

第 5 步：连接转化漏斗

• 创建转化漏斗，然后按角色和顺序添加页面。
• 同一页面可以被多个转化漏斗引用。域模型强制执行的唯一性规则是：stepSlug 在一个转化漏斗中必须唯一（且同一页面在每个转化漏斗中最多出现一次）——系统不会拒绝跨转化漏斗引用，因此无需为此进行特殊设计。只有当你希望两个转化漏斗有所不同时，才克隆落地页，因为编辑共享页面会影响引用它的所有转化漏斗。
• 创建时，如果已有 THANKYOU 和 ERROR 页面，系统会自动绑定；如果租户没有这些页面，请在上线前创建。如果转化漏斗没有错误页面，支付被拒时将不会有任何提示。
• 广告活动中使用的 URL 是店面域名上落地页自身的 slug——https://shop.example.com/{page.slug}——绝不能使用 /n/ 步骤 URL。/n/{funnelId}/{stepSlug} 会向前跳转到下一步骤，因此应将其用作页面的 CTA 链接，而不是广告链接。这样编写 CTA，即使将某个步骤替换为另一个页面，买家的路径也能保持稳定。
• 发布操作是显式的，并按页面和转化漏斗分别进行版本管理——发布页面并不会发布转化漏斗绑定。

步骤 6：发送流量前做好监控

发布前必须完成的检查：

1. 完成一次真实的端到端购买，使用真实的支付服务提供商，包括：基础订单、一次已接受的追加销售、一次已拒绝的追加销售、感谢页面、收据邮件，以及订单出现在已连接的商店中。
2. 对该订单进行一次退款，确认每笔收费的退款流程正常。
3. 覆盖点击 ID——确认 fbclid / ttclid / gclid / msclkid 已写入订单记录。参见 server-side-conversion-tracking。
4. 服务器端转化事件已到达每个平台的广告事件调试器，其中附有点击 ID，且不会与浏览器事件重复。
5. 可以访问错误页面：通过强制使用一张被拒绝的银行卡来验证。

在 Workers 上，还要多做一项：确认 cron 的 scheduled 处理程序正在触发（排队的回传和召回活动都依赖它）。部署若悄悄丢失了 cron 触发器，表面上看起来一切正常，后台任务却会悄然停止。

只有完成这些检查后，才增加投放预算。未经真实交易验证的漏斗，其故障率是未知的，而不是低。

步骤 7：通过 MCP 使用 Agent 操作实例

该实例通过 /api/mcp 将管理 API 作为 MCP 工具提供，因此 Agent 无需使用 UI 也能创建和修改漏斗。

{
  "mcpServers": {
    "autonnel": {
      "type": "http",
      "url": "https://<your-autonnel-host>/api/mcp",
      "headers": { "Authorization": "Bearer <your-api-key>" }
    }
  }
}

使用原始 HTTP 调用 /api/mcp，而不是使用 MCP 客户端时，有两项传输要求通常会被 SDK 隐藏。此端点使用 Streamable HTTP：请求必须携带 Accept: application/json, text/event-stream——否则会在到达工具层之前被以 406 拒绝；成功响应则以 SSE 帧（event: message / data: {...}）返回，因此解析前必须先从 data: 中提取 JSON-RPC 信封。

整个应用之前还有一个容易踩的坑：如果实例位于 Cloudflare 后方，且启用了默认的托管机器人规则，Python 标准库的 user agent 会被拒绝。urllib 客户端会发送 Python-urllib/3.x，并在每个路径上收到状态为 403、正文为纯文本 error code: 1010 的响应，包括 /api/health。这看起来完全像是身份验证或权限错误，而且响应不是 JSON，因此解析正文的客户端会在看到状态码前就抛出异常。只有该 Agent 字符串会被拦截——curl、python-requests、httpx、axios、node 和空 UA 均可通过。如果用 Python 编写脚本，请设置明确的 User-Agent，或使用 requests / httpx；如果所有调用（包括未授权调用）都返回 403，原因就在这里，API 密钥也无法解决。

以下是 Claude Code 的 .mcp.json 格式（必须使用 type: "http"；没有该字段的条目会被跳过）。Claude Desktop 不会从 claude_desktop_config.json 读取远程服务：请使用 URL 和 Request headers 下的 Authorization 条目添加自定义连接器；请注意，该连接器从 Anthropic 的云端连接，因此无法访问 localhost 实例。Codex、Cursor 和 Windsurf 的配置：https://autonnel.com/docs/api/agent-page-editing。在管理后台 → Settings → API Keys 中生成密钥。每次调用的权限范围均限定为该密钥所属的租户。读取工具可使用任何密钥；修改工具则需要启用 writeAccess。请将写入密钥视为生产环境凭据：每个 Agent 使用独立密钥，报表使用只读密钥，并在需要时撤销密钥，而不是共享。

工具会自我描述——客户端连接时会读取名称、说明和输入架构，因此本指南不会重复这些内容。下文只介绍通过自省无法获知的信息。

失败的调用仍会返回 HTTP 200

这是最容易让客户端把失败误判为成功的情况。

条件	实际返回内容
在 CDN 边缘被拦截（参见上面的 Python-urllib 说明）	HTTP 403，正文为纯文本 error code: 1010，完全没有 JSON——请求根本没有到达应用
缺少 Accept 标头或标头不完整	HTTP 406，返回一个 JSON-RPC error 对象（-32000）——其格式与工具错误完全相同的传输拒绝，见上文
身份验证失败	HTTP 401，完全没有 JSON-RPC 帧
工具名称未知	HTTP 200，返回一个包含数值代码的真实 JSON-RPC error 对象——这是唯一以这种形式带内返回的失败，因为它发生在分派之前
其他所有情况：缺少写入权限、验证失败、未找到、冲突、服务器错误	HTTP 200，返回 result.isError === true，错误消息位于 result.content[0].text 中，并且没有 JSON-RPC error 对象

因此：如果存在 error，先查看 HTTP 状态再下结论——406 表示传输层拒绝了你的标头，200 表示工具名称未知。否则，在信任 result.content 之前先检查 result.isError。请先阅读错误消息，不要盲目重试——验证失败会指出确切的字段路径，冲突则会说明触发了哪条规则。

导致大多数写入失败的规则

• **漏斗步骤仅为 { stepSlug, pageId }，不包含其他内容。**顺序由数组顺序决定。步骤在流程中的作用由所引用页面自身的 type 决定；不存在 pageType、order 或 subOrder 字段。add_funnel_page 必须提供 stepSlug，且它在漏斗内必须唯一，并构成 /n/{funnelId}/{stepSlug}——这是一个前向重定向地址，而不是步骤自身的 URL（参见构建顺序）。这些 schema 使用 .strict()，因此额外字段会被拒绝，而非忽略。
• 步骤以其引用的页面为键，因此每个漏斗中一个页面最多出现一次，但同一页面可以被多个漏斗引用。不存在“只能属于一个漏斗”的规则。
• **不存在 LANDING 页面类型。**页面 type 为 CHECKOUT | THANKYOU | UPSELL | ERROR | CUSTOM，存储时使用大写。落地页是漏斗所引用的 CUSTOM 页面。
• 感谢页和错误页步骤是实时引用，不是快照。create_funnel 会为租户现有的感谢页和错误页添加步骤；如果不存在，则会根据模板创建。之后编辑这些页面，会影响所有引用它们的漏斗——如果某个漏斗需要不同版本，请克隆页面。
• **草稿和已发布状态彼此独立。**写入会保存到 draftData；publish: true 会将其发布并使渲染缓存失效。先写入，再通过 get_page 验证，然后在第二次调用中发布。
• **draftData 不会进行结构验证。**保存前不会检查 root / content / zones、必需属性或组件类型名称。格式错误的文档也会被接受，并且只会在渲染时出错。
• 组件类型必须来自 get_template({ key })，不能使用记忆中的列表。组件集会在不同版本中重命名和扩展；由于 draftData 不经过验证，过时的组件名称也能顺利保存，但渲染结果为空白。模板的 JSON 才是权威结构。
• 内容必须与页面的 editorType 匹配。create_page 中的 editorType 是可选项，且默认值为 PUCK，因此未指定该选项创建的 HTML 页面会被静默设为 Puck 页面。create_page 只接受 draftData；update_page 对 PUCK 页面接受 draftData，对 HTML / GRAPESJS 页面接受 htmlContent，若两者不匹配，则会报错（page <id> has editorType HTML; use htmlContent, not draftData），而不会写入渲染器永远不会读取的列。创建时请明确设置 editorType——创建后无法通过这些工具更改页面的编辑器类型。
• 先准备媒体，再创建页面。upload_media 会在服务器端获取 URL，并返回供组件属性使用的 CDN URL。无法为本地文件提供 URL，因此应改用 REST：POST /api/v1.1/media/upload，使用 multipart/form-data 并包含一个 file 部分；成功时返回 201 和 { assetId, url }。只接受 image/jpeg|png|webp|gif 和 video/mp4|webm；没有 writeAccess 的密钥会像其他写入端点一样，收到相同的 403 写入拒绝响应。如果从未配置存储，此请求会返回 412 并指出 Settings -> Storage，而不是通用的 500。
• **无法通过 API 删除页面。**没有 delete_page 工具，/api/v1.1/pages/{pageId} 上也没有 DELETE——只有 GET 和 PUT。可以删除漏斗（delete_funnel），但不能删除页面，因此所有废弃或命名错误的页面都会永久保留，除非有人在管理界面中将其移除。请在首次尝试时慎重选择 slug，并在临时实例上试运行，而不是在正在构建的租户上操作。
• **get_stats 统计的是独立用户数，而非浏览量。**同一访客访问五次，计为 1。
• list_orders 无法按漏斗筛选，并且会将金额除以 100，适用于 USD/EUR，但不适用于 JPY 或 BHD。
• **无法通过 MCP 或 REST 获取广告支出。**管理界面内置了 Facebook、Google Ads 和 TikTok 的广告级支出、点击量和转化报告（在 Settings → Ads 下连接，在 Analytics → Ads 或漏斗自身的 Analytics 标签页中查看），并会与您自己的订单进行对账——但这些都不是 MCP 工具，也不是 /api/v1.1/ 端点。通过 MCP 操作此实例的 Agent 完全无法查询广告系列或支出；必须由人工打开管理界面查看。Bing 在任何地方（包括管理界面）都不提供支出/点击量报告——它仍仅支持 token 模式的转化回传。

构建顺序

list_products → list_templates → get_template
  → media first:  remote URL → upload_media (MCP)
                  local file → POST /api/v1.1/media/upload (REST, multipart)
                  then swap the returned CDN url into the content you are about to write
  → create_page × N (name, slug, type, editorType) → update_page (draftData or htmlContent)
  → get_page (verify) → update_page({ publish: true })
  → create_funnel → add_funnel_page × N (pageId + unique stepSlug) → get_funnel
  → GET /storefront/{page.slug} → expect 200

/n/ URL 永远不会渲染它所指向的步骤。 /n/{funnelId}/{stepSlug} 是一个向前重定向：它会找到该步骤，302 重定向到下一步的纯页面 slug，并附加 ?funnelId=；如果是最后一步，则返回 404 No next step in funnel。将它指向你的落地步骤，你得到的会是结账页；如果后面没有步骤，则会得到 404——无论哪种情况，都不是落地页。

entryStepSlug 也不是适合宣传的 URL。 它实际就是 steps[0]，而 create_funnel 会在你添加任何内容之前追加感谢页和错误页，所以按这种方式创建的漏斗中，steps[0] 就是感谢页。

页面通过商店域名下的纯 slug 提供服务：https://{storefront-host}/{page.slug}。从 get_funnel 读取 steps，选择 page.type 为 CUSTOM 的步骤，并宣传该步骤的 page.slug。只有在页面绑定到多个漏斗时，才附加 ?funnelId={id}；如果只绑定一个漏斗，漏斗上下文会自动解析。

纯 slug 只能在非管理主机上使用。 当主机与 ADMIN_DOMAIN 不匹配时，中间件会将 /{slug} 重写到商店渲染器；在管理主机本身上，该路径会落入管理应用并返回 404，看起来就像页面尚未发布。因而，仅通过 *.workers.dev 管理主机访问的 Workers 部署没有可用的落地页 URL，除非绑定商店域名——购买流量前请先绑定。

只用 API 密钥验证时，请请求 /storefront/{slug}。 这个前缀在所有主机（包括管理主机）上都是公开的，并会渲染购物者看到的内容。它只提供已发布的页面——草稿会在这里返回 404，而 get_page 仍会正常返回其 draftData。/preview/{slug} 确实会渲染草稿，但需要已登录的会话，因此 API 密钥无法使用它。花钱推广之前，请确认响应为 200，且正文包含预期文案。

修改线上页面时：get_page → 只编辑你要更改的属性 → 不发布地调用 update_page → 用 get_page 对比 → 发布。不要为了修改一个标题就重新生成整个 draftData 数据块；update_page 会整体替换文档，而组件 JSON 中包含你没有写入、也无法还原的属性值。

REST 并非相同的接口

REST 使用与 MCP 相同的 Authorization: Bearer <api-key> 请求头；缺少该请求头时会直接返回 401。

另有十三个工具可通过运行相同 schema 和处理程序的桥接层使用 REST，因此两者不会出现偏差。七个工具仅支持 MCP：list_funnels、get_funnel、list_pages、get_page、list_products、deliver_order、get_stats。其中一些工具在相同路径上有较早编写、相互独立的 REST 端点，其响应格式或参数名称不同（GET /products 使用 q，而不是 search）。不要假定 REST 端点与同名工具相匹配。

有一个路径陷阱：/api/v1.1/templates 列出的是 Settings 中的电子邮件模板，而不是 Puck 页面模板。页面模板位于 /api/v1.1/page-templates。

如实说明运维成本

请直接说明以下内容，不要等用户上线后才让他们发现：

• Workers 方案：无需维护服务器，但 Postgres 及其备份由你负责；免费套餐的限制是每日上限，超过后操作会失败，而不是向你收费。流量激增前，请了解自己最接近哪项限制。
• Docker 方案：升级、备份和正常运行时间都由你负责。Schema 变更随镜像发布，升级时必须应用。
• 在任何方案中，支付配置及其 PCI 范围都由运营方负责。
• 可自托管版本没有支持 SLA。GitHub Issues 和 Discussions 是支持渠道。
• 首次生产部署请按小时而不是按分钟预留时间。所谓两分钟，是指本地 Docker 评估，不是上线部署。

文档：https://autonnel.com/docs · Issues 和 Discussions：https://github.com/autonnel/autonnel