PostHog

在 Nebutra 中配置 PostHog，用于产品分析、功能开关、会话录制和漏斗分析。

PostHog 是 Nebutra 的核心产品分析工具。它追踪产品内的用户行为，驱动与计费方案绑定的功能开关，并录制会话以辅助 UX 调试。

前提条件

一个 PostHog 账户——posthog.com（云端）或自托管实例

一个可访问环境变量的 Nebutra 项目

配置步骤

在 PostHog 项目设置中，复制项目 API 密钥，它以 phc_ 开头。

将以下内容添加到你的 .env.local（开发环境）和部署环境（生产环境）：

POSTHOG_KEY=phc_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
POSTHOG_HOST=https://app.posthog.com
NEXT_PUBLIC_POSTHOG_KEY=phc_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
NEXT_PUBLIC_POSTHOG_HOST=https://app.posthog.com

POSTHOG_KEY 用于服务端产品事件，NEXT_PUBLIC_POSTHOG_KEY 用于浏览器 SDK。如需欧盟数据驻留，请使用 https://eu.posthog.com。如使用自托管实例，请填写你自己的 URL（例如 https://posthog.yourcompany.com）。

启动开发服务器并执行任意操作（注册、创建项目等）。打开 PostHog → 实时事件，确认事件在几秒内出现。

PostHog 云端 vs 自托管

	PostHog 云端	自托管
配置难度	最低	需要基础设施
数据驻留	美国或欧盟区域	你自己的服务器
费用	每月 100 万事件以内免费	仅基础设施成本
维护	托管服务	自行管理升级
HIPAA / SOC 2	付费计划可用	由你负责

对于大多数早期阶段的 Nebutra 部署，PostHog 云端（欧盟区域）是在无需基础设施开销的情况下快速达到合规要求的最佳选择。

自定义事件追踪

客户端（Next.js）

import { useAnalytics } from "@nebutra/analytics";

export function CreateProjectButton() {
  const { track } = useAnalytics();

  const handleCreate = async () => {
    const project = await createProject();

    track("project_created", {
      projectId: project.id,
      plan: subscription.plan,
      tenantId: org.id,
    });
  };

  return <button type="button" onClick={handleCreate}>创建项目</button>;
}

服务端（API Gateway）

对于源自 Hono API 层且没有浏览器上下文的事件，使用 createProductAnalyticsClientFromEnv：

import { createProductAnalyticsClientFromEnv } from "@nebutra/analytics";

app.post("/api/v1/checkout/complete", async (c) => {
  const { organizationId, userId, plan } = c.get("tenantContext");
  const analytics = createProductAnalyticsClientFromEnv();

  const checkout = await completeCheckout(c.req);

  await analytics.track("checkout", {
    action: "completed",
    userId,
    organizationId,
    tier: plan,
  });

  return c.json({ success: true, data: checkout });
});

用户身份识别

在用户登录后调用 identify，这样 PostHog 就可以将登录前的匿名事件关联到已认证用户：

import { useAnalytics } from "@nebutra/analytics";

export function useAuthEffect(user: User, subscription: Subscription, org: Org) {
  const { identify } = useAnalytics();

  useEffect(() => {
    if (!user) return;

    identify(user.id, {
      email: user.email,
      name: user.name,
      plan: subscription.plan,
      orgId: org.id,
      createdAt: user.createdAt,
    });
  }, [user.id]);
}

identify 已由 Nebutra 的认证钩子在会话开始时自动调用。只有在需要更新用户属性时（例如套餐升级后），才需要手动调用。

功能开关

功能开关决策归 @nebutra/feature-flags 管，不归 @nebutra/analytics 管。PostHog 将来可以作为功能开关 provider，但产品事件采集和功能开关评估保持分离。

import { useFeatureFlag } from "@nebutra/feature-flags";

export function AiChatButton() {
  const { enabled, loading } = useFeatureFlag("ai_chat");

  if (loading) return <Skeleton />;
  if (!enabled) return <UpgradePrompt feature="AI Chat" />;

  return <button type="button">打开 AI 对话</button>;
}

在 API 路由中通过 feature-flags 包进行服务端功能开关评估：

import { isFeatureEnabled } from "@nebutra/feature-flags";

const enabled = await isFeatureEnabled("ai_chat", {
  userId,
  tenantId,
});

功能开关的负载（如模型名称、速率限制）在 PostHog 界面的功能开关中管理，无需重新部署代码即可更新。

会话录制

会话录制默认启用，可通过回放用户的精确交互操作来调试 UX 问题。

禁用会话录制

如需全局禁用，在 PostHog 项目设置中找到会话录制 → 关闭录制用户会话。

如需针对特定用户禁用（例如，对要求不采集任何数据的企业客户）：

import { useAnalytics } from "@nebutra/analytics";

const { optOut } = useAnalytics();

// 当用户在账户设置中选择退出分析时调用
optOut();

会话录制会捕获所有 DOM 交互，包括表单输入。请确保敏感字段（密码、卡号）已被遮罩。Nebutra 会自动遮罩 [type="password"] 和 Stripe iframe 元素，但请务必验证任何自定义支付流程。

漏斗分析

PostHog 漏斗功能可帮助你衡量核心流程中每个步骤的转化率。建议在你的 PostHog 项目中创建以下漏斗：

激活漏斗

user_signed_up

org_created

project_created

api_key_created

升级漏斗

quota_warning

定价页面浏览

plan_upgraded

AI 功能使用漏斗

project_created

ai_chat_started

ai_chat_completed

激活漏斗的转化窗口建议设为 7 天，升级漏斗建议设为 30 天，以捕获典型的用户行为模式。

前提条件

配置步骤

PostHog 云端 vs 自托管

自定义事件追踪

客户端（Next.js）

服务端（API Gateway）

用户身份识别

功能开关

会话录制

禁用会话录制

漏斗分析

激活漏斗

升级漏斗

AI 功能使用漏斗

分析概览

Dub.co

功能开关

计费方案

目录