🪢 Langfuse 图解教程Langfuse Visual Guide 第十部分 · 平台与运维Part 10 · Platform & Operations 50 / 55
第十部分 · 平台与运维Part 10 · Platform & Operations

开源核与权益Open-core & entitlements

🧭 读前Before you start
先读 第10课 的多租户,本课讲开源核与商业权益的边界。
Read Lesson 10 on multi-tenancy; this lesson covers the open-core / commercial entitlement boundary.

Langfuse 是开源的——你现在读的这套源码,从摄取到查询、从评估到自动化,全都摆在公开仓库里。但它又是一家公司,得靠卖东西活下去。这两件事怎么共存?答案是 open-core(开源核)商业模式:核心免费开源,少数企业级功能(审计日志、数据保留策略、多租户 SSO、admin API…)需要付费计划或企业许可证才能启用。妙的是,这些「付费功能」的代码也是开源的、就在这个仓库里——你能读、能学,但要在生产里用,得有相应的 plan(计划)。 这一课讲这套「门票系统」怎么用极少的代码实现:一张 entitlementAccess 总表把每个 plan 映射到「能用哪些功能、各有什么额度」,一个 hasEntitlement() 函数就是所有功能门口的那道闸。还会看到自托管版怎么用一把 langfuse_ee_ 开头的许可证密钥解锁企业功能。

📋 生活类比
open-core 像一家「菜谱全公开的餐厅」:它把所有菜的做法都印在墙上、任人抄走自己回家做(开源——代码全公开、可自托管)。那它靠什么赚钱?靠会员制的「招牌服务」:普通客人能吃到绝大多数菜(免费核心功能),但某些高级服务——比如「专属包厢」「无限续杯」「私人厨师上门」(审计日志、无限额度、多租户 SSO)——得办张会员卡(plan)才享受。 关键在于餐厅怎么验会员:门口不是每个服务各设一个保安,而是一张总表写明「金卡能享哪些服务、银卡哪些、普通客人哪些」,再加一个统一的验卡动作——你点任何高级服务,服务员都只做同一件事:查你的卡在不在这张服务的允许名单里(hasEntitlement)。自己在家照菜谱做(自托管)也想解锁高级服务?那得买一张「企业授权证书」(langfuse_ee_ 许可证密钥)。

开源核:全代码开放,少数功能按 plan 解锁

先厘清一个常见误解:open-core 不是「一半开源一半闭源」。Langfuse 这个仓库里所有功能的代码都是开放的——包括那些「企业级」功能。区别只在运行时能不能启用:每个组织挂着一个 plan,免费的默认是 "oss"(自托管开源版),付费的有云上五档 cloud:hobby / core / pro / team / enterprise,以及自托管两档 self-hosted:pro / enterprise。isCloudPlan / isSelfHostedPlan 这两个小助手按前缀区分它们。功能用不用得了,全看你的 plan 在不在那张允许名单里。

代码全公开;功能按 plan 解锁 整个仓库(全部开源) 免费核心(人人可用)摄取·查询·评估·prompt·dashboard… 企业级功能(代码也开源!)审计日志·数据保留·多租户SSOadmin API·定时blob导出·UI定制…能读能学,但启用要 plan/license 组织的 plan 决定能启用哪些 oss(默认·免费) cloud:hobby/core云·入门 cloud:pro/team/enterprise云·高级 self-hosted:pro/enterprise isCloudPlan / isSelfHostedPlan 按前缀区分 plan 越高,allow 名单越长、额度越大 下一节:entitlementAccess 总表 + hasEntitlement 闸
开源核分层:代码全在仓库里(web/src/features/entitlements/*、packages/shared/src/server/ee/* 也开源)。Plan 见 plans.ts:21(type Plan = keyof typeof planLabels,含 cloud:hobby/core/pro/team/enterprise + self-hosted:pro/enterprise),默认 "oss";plans.ts:26-27 isCloudPlan/isSelfHostedPlan 按前缀判断。
示例:权益 × 套餐矩阵(开源核) 代码全开源;■=该档解锁此权益,□=需更高档/许可证 OSS Cloud Pro Cloud Team Self-host EE entitlement trace-deletion ✓ ✓ ✓ ✓ data-retention ✗ ✓ ✓ ✓ rbac-project-roles ✗ ✗ ✓ ✓ audit-logs ✗ ✗ ✓ ✓ admin-api ✗ ✗ ✓ ✓ prompt-protected-labels ✗ ✗ ✓ ✓ self-host-ui-customization ✗ ✗ ✗ ✓ hasEntitlement(key) 按 plan 查这张表 —— 代码看得到,能不能用由 plan/license 决定
开源核 = 代码全开放,但「能不能启用」由权益表决定(取自 features/entitlements/constants/entitlements.ts 的 entitlementAccess: Record<Plan, …>,真实映射):基础权益(trace-deletion)人人都有;data-retention 从 Cloud Pro 起;rbac-project-roles/audit-logs/admin-api 这些治理类要 Cloud Team 或自托管企业版;self-host-ui-customization 是自托管企业版独有。运行时一句 hasEntitlement("audit-logs") 按当前 plan 查表放行。所以你能读到全部源码,但启用企业特性仍需对应 plan 或 license——这正是「open-core」。
免费oss 开源核(默认 plan)
自托管下来直接能用的全部核心:摄取、查询、评估、prompt、dashboard、自动化……占了功能的绝大多数。组织没有付费 plan 时,plan ?? "oss" 兜底到这里——默认落到免费,而非默认付费。
付费cloud / self-hosted 各档
云上 hobby→core→pro→team→enterprise、自托管 pro→enterprise,逐级解锁更多企业功能、放宽更多额度。同一套代码,按 plan 给不同组织开不同的「门」。
透明企业功能也开源
关键区别于「闭源商业版」:审计日志、数据保留、多租户 SSO 这些企业功能的代码同样公开,放在 ee/ 与 shared/.../ee/。你能审计、能学习、能给自己改——只是生产启用需要授权。

一张总表 + 一道闸:entitlementAccess 与 hasEntitlement

整套「门票系统」的心脏,是一张 entitlementAccess: Record<Plan, {entitlements, entitlementLimits}> 总表,把每个 plan 映射到两样东西:① entitlements(二元开关:某功能有/没有,如 data-retention、audit-logs、admin-api);② entitlementLimits(数值额度:某资源能用多少,如 organization-member-count、data-access-days、monitor-count,值是数字表示有上限,或 false 表示无限)。比如 cloud:hobby 限 2 个成员、30 天数据、1 个标注队列;cloud:core 放宽到成员无限、90 天;cloud:pro 再加上 data-retention 功能。

所有功能门口就一道闸:hasEntitlement({ sessionUser, orgId, entitlement })。它的逻辑朴素得让人安心:① admin 直接放行;② 找到所属组织、取其 plan,没有就兜底成 "oss";③ 查这个 plan 的 entitlements 名单里含不含所求功能。就这三步。功能代码里不写「if plan==pro」散落各处,而是统一问这道闸——和第 49 课 RBAC「问 scope」如出一辙:把「谁能用什么」收敛到一张表 + 一个函数。

所有功能共用一道闸:hasEntitlement 功能代码想用 data-retention?先问闸 hasEntitlement① admin?→ 直接放行② org.plan ?? "oss"③ 查 plan 名单 includes?默认兜底到免费,不是付费 entitlementAccess 总表 Record<Plan,…>cloud:hobby → {entitlements:[…], limits:{members:2,days:30}}cloud:core → {…, members:false(无限), days:90}cloud:pro → {+data-retention, queues:false} entitlementLimits:数值额度number=有上限 · false=无限(hasEntitlementLimit 查) 含 → 放行 / 不含 → 拒绝功能据此显示/启用或隐藏/禁用
总表 + 闸:entitlements.ts:54 entitlementAccess: Record<Plan, {entitlements, entitlementLimits}>(entitlements:6 二元功能、entitlementLimits:38 数值额度 number|false)。hasEntitlement.ts:17::18 admin→true、:25 org.plan ?? "oss"、:40 entitlementAccess[plan].entitlements.includes(entitlement)。
web/src/features/entitlements/constants/entitlements.ts · server/hasEntitlement.ts总表 + 闸
// 二元功能开关 + 数值额度(number=有上限 / false=无限)
export const entitlements = ["audit-logs", "data-retention", "admin-api",
  "cloud-multi-tenant-sso", "scheduled-blob-exports", …] as const;

export const entitlementAccess: Record<Plan, {…}> = {
  "cloud:hobby": { entitlements: […], entitlementLimits: {
                     "organization-member-count": 2, "data-access-days": 30 } },
  "cloud:core":  { entitlements: […], entitlementLimits: {
                     "organization-member-count": false/*无限*/, "data-access-days": 90 } },
  "cloud:pro":   { entitlements: [… "data-retention"], … },
  // self-hosted:pro/enterprise, cloud:enterprise …
};

// 所有功能门口的同一道闸
export const hasEntitlement = (p) => {
  if (p.sessionUser.admin) return true;                 // admin 直接放行
  const plan = org?.plan ?? "oss";                     // 默认兜底到免费版
  return entitlementAccess[plan].entitlements.includes(p.entitlement);
};

🔘 entitlement(二元)

某功能有或没有:audit-logs、data-retention、admin-api、cloud-multi-tenant-sso…由 hasEntitlement 查「plan 名单含不含」,返回 true/false。

🔢 entitlementLimit(数值)

某资源能用多少:organization-member-count、data-access-days、monitor-count…值是 number(有上限)或 false(无限),由 hasEntitlementLimit 查。

🔑 license(自托管)

自托管解锁企业层:LANGFUSE_EE_LICENSE_KEY 以 langfuse_ee_ 开头才算企业(langfuse_pro_ 不算);Cloud 任何区域天然有企业功能。

自托管的解锁钥匙:EE 许可证

云上版本由 Langfuse 托管,plan 写在数据库里。但自己部署的版本怎么证明「我买了企业版」?靠一把许可证密钥。isEnterpriseLicenseAvailable() 的判断很干脆:① 是 Langfuse Cloud(任何区域)→ 直接有企业功能;② 自托管 → 看环境变量 LANGFUSE_EE_LICENSE_KEY 是否以 langfuse_ee_ 开头。注意一个细节:langfuse_pro_ 开头的 Pro 许可证不算企业级——前缀本身就编码了授权层级。这把钥匙插对了,自托管实例才解锁那些企业 entitlement。

isEnterpriseLicenseAvailable():前缀编码授权层级 实例 部署形态? ① Cloud(任意区域)→ 有企业功能 ② 自托管 → 看 EE_LICENSE_KEY 前缀 langfuse_ee_ → ✓ 企业 entitlement langfuse_pro_ → Pro(不算企业) 无 / 其它 → oss 兜底免费
问题open-core 的答案
企业功能的代码闭源吗?不,全在公开仓库(ee/、shared/.../ee/),能读能学能自改
那靠什么区分免费/付费?运行时的 plan + hasEntitlement 闸,而非「代码有没有」
没有 plan 的组织怎么办?plan ?? "oss" 兜底到免费——默认最安全的(最少权益),不是默认付费
自托管怎么解锁企业版?设 LANGFUSE_EE_LICENSE_KEY=langfuse_ee_…(Pro 的 langfuse_pro_ 不算企业)
EE 代码放哪、谁能依赖它?独立包 @langfuse/ee;依赖方向 web → @langfuse/ee → @langfuse/shared

把这张表连起来看,open-core 的精巧就清楚了:「能不能用」与「有没有代码」彻底解耦。代码 100% 公开(透明、可审计、社区可贡献),而商业边界靠一层轻薄的运行时门控(plan + entitlement + license)划出。这让 Langfuse 既是真开源、又能有可持续的商业模式——两者不矛盾。

🎯 设计取舍
为什么把「能不能用某功能」做成一道统一的 hasEntitlement 闸 + 一张 entitlementAccess 总表,而不是在每个功能里各自写「if plan == pro」? 这和第 49 课 RBAC 用「角色→scope」是同一种智慧,原因也一样:收敛权威、便于演进与审计。商业 plan 会变——加一档套餐、调一次额度、把某功能从 pro 下放到 core,都是常事。如果「pro 才能用 X」这种判断散落在几十处功能代码里,每次调整都要全仓库搜改,极易漏、易错、还难复盘「到底哪个 plan 能用什么」。把它收进一张声明式总表后:调整商业策略=改这张表的一行,功能代码完全不动;想知道「pro 包含什么」=读表的一行。把易变的商业规则从稳定的功能逻辑里抽出来、集中声明,是让系统能跟上商业节奏的关键。

为什么没有 plan 的组织要默认兜底成 "oss"(免费),而不是报错或默认给最高权限? 这是一个「fail-safe(失败安全)」默认值的选择,方向很重要。如果默认给最高权限,一旦某组织的 plan 字段因 bug、迁移、数据缺失而读不到,它就会意外解锁所有付费功能——商业上漏损、安全上越权。如果默认报错,又会让「绝大多数自托管开源用户」(他们本就该是 oss)寸步难行。兜底到 "oss" 恰好两全:开源用户开箱即用(这是最常见、最该顺滑的路径),而付费功能默认是关的、必须由明确的 plan 或 license 主动打开。安全的默认值,应该是「权限最小、影响最轻」的那一个——entitlement 默认关、登录默认拒、IP 解析失败默认拦(第 44 课),都是同一条原则的不同侧影。
🎯 本课要点
  • open-core ≠ 半闭源:Langfuse 全部功能(含企业级)的代码都在公开仓库,可读可学可自改。免费与付费的区别在运行时能否启用,不在「有没有代码」。
  • plan 分层:组织挂一个 plan,默认 "oss"(免费自托管),付费有 cloud:hobby/core/pro/team/enterprise + self-hosted:pro/enterprise;isCloudPlan/isSelfHostedPlan 按前缀分。
  • 总表 + 一道闸:entitlementAccess: Record<Plan,{entitlements, entitlementLimits}> 把每个 plan 映射到「有哪些二元功能 + 各资源额度(number/false无限)」;hasEntitlement(admin→true、plan ?? "oss"、includes)是所有功能共用的那道闸——收敛权威、便于演进,同第49课 RBAC 一脉。
  • EE 许可证:isEnterpriseLicenseAvailable——Cloud(任何区域)有企业功能;自托管看 LANGFUSE_EE_LICENSE_KEY 是否 langfuse_ee_ 开头(langfuse_pro_ 不算企业,前缀编码授权层级)。
  • fail-safe 默认:无 plan 兜底到 "oss"(最小权益、付费功能默认关),而非默认报错或默认全开——与「登录默认拒、IP 解析失败默认拦」同源的安全默认观。EE 代码在独立包 @langfuse/ee,依赖方向 web→ee→shared。

🧪 自测 · 想一想为什么这么设计

1. 关于 Langfuse 的 open-core 模式,下面哪种理解是正确的?
  1. 整个仓库的代码全是开源的(包括审计日志、数据保留等企业功能),免费与付费的区别只在「运行时这个组织的 plan 能不能启用某功能」,而不在「代码是否公开」——能不能用与有没有代码彻底解耦
  2. 付费功能在编译时被移除,开源版没有这些代码
  3. 企业功能的代码是闭源的,开源的只有核心部分
  4. 所有功能都免费,Langfuse 靠捐赠盈利
看答案与解析 点击展开
答案:A。open-core 常被误解为「一半开源一半闭源」,但 Langfuse 不是:连审计日志、数据保留、多租户 SSO 这些企业功能的代码都在公开仓库里(ee/ 与 shared/.../ee/),你能读、能学、能自己改。真正划出商业边界的,是一层轻薄的运行时门控——组织挂的 plan + hasEntitlement 闸。所以「能不能用」取决于你的 plan,而非「代码在不在」。这种把代码透明性与商业可持续性同时拿到的设计,正是 open-core 的精巧之处:100% 公开 + 一层 entitlement 门控。
2. hasEntitlement 在找不到组织的 plan 时,用 `org?.plan ?? "oss"` 兜底成免费的 oss,而不是默认报错或默认给最高权限。这个默认值的选择体现了什么原则?
  1. 为了让代码更短
  2. oss 查询比其他 plan 快
  3. fail-safe(失败安全)默认:默认值应是「权限最小、影响最轻」的那个。若默认给最高权限,plan 因 bug/迁移读不到时会意外解锁所有付费功能(漏损+越权);兜底到 oss 则开源用户开箱即用、付费功能默认关——与登录默认拒、IP解析失败默认拦同源
  4. 为了兼容老版本数据库
看答案与解析 点击展开
答案:C。默认值的方向是个安全决策。设想 plan 字段因某个 bug、数据迁移、或字段缺失而读不到:若默认给最高权限,这个组织会瞬间解锁所有付费功能——商业上是漏损、安全上是越权;若默认报错,又会让绝大多数本就是 oss 的自托管开源用户用不了。兜底到 oss 两全:开源用户(最常见路径)开箱即用,付费功能默认关、必须由明确 plan/license 主动打开。这与第44课「IP 解析失败默认拦截」、第48课「登录默认拒绝」是同一条 fail-safe 原则——拿不准时,选权限最小、影响最轻的那个默认。
3. Langfuse 把「哪个 plan 能用哪些功能」收进一张声明式的 entitlementAccess 总表,所有功能门口只调同一个 hasEntitlement 闸,而不是在各功能里散写「if plan==pro」。这样做最大的好处是?
  1. 把易变的商业规则从稳定的功能逻辑里抽出、集中声明:加套餐/调额度/把功能从pro下放到core,只需改总表一行,功能代码不动;想知道某plan包含什么,读表一行即可——便于演进与审计,避免散落判断改漏改错
  2. 总表查询比散落的 if 判断运行更快
  3. 总表能自动生成计费账单
  4. 这样就不需要 plan 概念了
看答案与解析 点击展开
答案:A。商业 plan 是会频繁变动的:加一档套餐、调一次额度、把某功能从 pro 下放到 core,都很常见。如果「pro 才能用 X」散落在几十处功能代码里,每次调整都要全仓搜改,极易漏、易错、还难复盘「到底哪个 plan 能用什么」。收进一张声明式总表后:改商业策略=改表的一行,功能代码完全不动;查「pro 包含什么」=读表一行。这与第49课 RBAC 用「角色→scope」总表是同一种智慧——把易变规则从稳定逻辑里抽出、集中声明,让系统能跟上商业节奏,也让权限/权益一目了然、可审计。
💭 发散思考(没有标准答案,动手或动脑想想)
  • open-core 让 Langfuse「代码全公开 + 商业可持续」两者兼得:100% 开源,靠一层轻薄的运行时门控(plan + entitlement + license)划出商业边界。请谈谈你的看法:相比「纯开源(全免费)」和「纯闭源(全收费)」,open-core 在商业与社区之间的取舍是什么?它对使用者(能读到全部代码、能自托管、但企业功能要授权)是更友好还是更受限?如果你要把一个项目商业化,会选哪种模式,为什么?

Langfuse is open source — the source you're reading, from ingestion to query, from evaluation to automation, is all laid out in a public repo. Yet it's also a company that must sell something to survive. How do these coexist? The answer is the open-core business model: the core is free and open, while a few enterprise features (audit logs, data-retention policy, multi-tenant SSO, admin API…) require a paid plan or enterprise license to enable. The clever part: the code for these "paid features" is also open, right here in this repo — you can read and learn it, but to use it in production you need the corresponding plan. This lesson shows how that "ticket system" is implemented with very little code: one entitlementAccess master table mapping each plan to "which features, with what limits," and one hasEntitlement() function that is the single gate in front of every feature. You'll also see how a self-hosted version unlocks enterprise features with a license key starting with langfuse_ee_.

📋 Analogy
Open-core is like a "restaurant with a fully-public recipe book": it prints every dish's recipe on the wall, free for anyone to copy and cook at home (open source — code fully public, self-hostable). So how does it make money? Through a membership for "signature service": regular guests can eat the vast majority of dishes (free core features), but some premium services — a "private room," "unlimited refills," "a personal chef at home" (audit logs, unlimited quotas, multi-tenant SSO) — require a membership card (plan). The key is how the restaurant verifies membership: not a separate bouncer per service, but one master table stating "gold card enjoys these services, silver these, regular guests these," plus one unified card-check action — for any premium service, the waiter does the same one thing: check whether your card is on that service's allow list (hasEntitlement). Cooking from the recipe at home (self-hosting) and want premium service too? Then buy an "enterprise license certificate" (a langfuse_ee_ license key).

Open core: all code open, a few features unlocked by plan

First clear up a common misconception: open-core is not "half open-source, half closed". In this Langfuse repo all features' code is open — including the "enterprise" ones. The difference is only whether they can be enabled at runtime: each org carries a plan, free defaults to "oss" (self-hosted open-source), paid has five cloud tiers cloud:hobby / core / pro / team / enterprise plus two self-hosted self-hosted:pro / enterprise. The helpers isCloudPlan / isSelfHostedPlan distinguish them by prefix. Whether a feature works hinges entirely on whether your plan is on its allow list.

Code all public; features unlocked by plan the entire repo (all open source) free core (everyone)ingest·query·eval·prompt·dashboard… enterprise features (code also open!)audit logs·data retention·multi-tenant SSOadmin API·scheduled blob export·UI customization…read & learn, but enabling needs plan/license the org's plan decides what can be enabled oss (default · free) cloud:hobby/corecloud · entry cloud:pro/team/enterprisecloud · premium self-hosted:pro/enterprise isCloudPlan / isSelfHostedPlan distinguish by prefix higher plan = longer allow list, larger quotas next: entitlementAccess master table + hasEntitlement gate
Open-core layering: the code is all in the repo (web/src/features/entitlements/*, packages/shared/src/server/ee/* are open too). Plans at plans.ts:21 (type Plan = keyof typeof planLabels, including cloud:hobby/core/pro/team/enterprise + self-hosted:pro/enterprise), defaulting to "oss"; plans.ts:26-27 isCloudPlan/isSelfHostedPlan judge by prefix.
Example: entitlement × plan matrix (open-core) code is fully open; ■ = tier unlocks it, □ = needs a higher tier / license OSS Cloud Pro Cloud Team Self-host EE entitlement trace-deletion ✓ ✓ ✓ ✓ data-retention ✗ ✓ ✓ ✓ rbac-project-roles ✗ ✗ ✓ ✓ audit-logs ✗ ✗ ✓ ✓ admin-api ✗ ✗ ✓ ✓ prompt-protected-labels ✗ ✗ ✓ ✓ self-host-ui-customization ✗ ✗ ✗ ✓ hasEntitlement(key) checks this table by plan — the code is visible, but whether you can use it depends on plan/license
Open-core = the code is fully open, but "can you enable it" is decided by the entitlement table (from entitlementAccess: Record<Plan, …> in features/entitlements/constants/entitlements.ts, real mapping): base entitlements (trace-deletion) are universal; data-retention starts at Cloud Pro; governance ones like rbac-project-roles/audit-logs/admin-api need Cloud Team or self-host Enterprise; self-host-ui-customization is self-host-Enterprise only. At runtime a single hasEntitlement("audit-logs") checks this table by the current plan. So you can read all the source, but enabling enterprise features still needs the matching plan or license — that's "open-core".
freeoss open core (default plan)
Everything a self-host install runs out of the box: ingestion, query, eval, prompt, dashboard, automation… the vast majority of features. When an org has no paid plan, plan ?? "oss" falls back here — defaulting to free, not to paid.
paidcloud / self-hosted tiers
Cloud hobby→core→pro→team→enterprise, self-hosted pro→enterprise, progressively unlocking more enterprise features and loosening more quotas. Same code, different "doors" opened for different orgs by plan.
transparententerprise features are open too
The key difference from a "closed-source commercial edition": the code for audit logs, data retention, multi-tenant SSO is equally public, in ee/ and shared/.../ee/. You can audit, learn, and modify it for yourself — only production enablement needs a license.

One master table + one gate: entitlementAccess and hasEntitlement

The heart of the whole "ticket system" is one entitlementAccess: Record<Plan, {entitlements, entitlementLimits}> master table, mapping each plan to two things: ① entitlements (binary switches: a feature on/off, like data-retention, audit-logs, admin-api); ② entitlementLimits (numeric quotas: how much of a resource you may use, like organization-member-count, data-access-days, monitor-count — the value is a number for a cap, or false for unlimited). For example cloud:hobby caps at 2 members, 30 days of data, 1 annotation queue; cloud:core loosens to unlimited members, 90 days; cloud:pro additionally adds the data-retention feature.

There's just one gate in front of every feature: hasEntitlement({ sessionUser, orgId, entitlement }). Its logic is reassuringly plain: ① admin passes outright; ② find the owning org, take its plan, falling back to "oss" if none; ③ check whether this plan's entitlements list includes the requested feature. Just those three steps. Feature code doesn't scatter "if plan==pro" everywhere but asks this one gate — exactly like Lesson 49's RBAC "ask the scope": converge "who can use what" into one table + one function.

All features share one gate: hasEntitlement feature codewant data-retention?ask the gate first hasEntitlement① admin? → pass outright② org.plan ?? "oss"③ plan list includes?defaults to free, not paid entitlementAccess master Record<Plan,…>cloud:hobby → {entitlements:[…], limits:{members:2,days:30}}cloud:core → {…, members:false(unlimited), days:90}cloud:pro → {+data-retention, queues:false} entitlementLimits: numeric quotasnumber=capped · false=unlimited (hasEntitlementLimit checks) includes → allow / not → denyfeature shows/enables or hides/disables
Master table + gate: entitlements.ts:54 entitlementAccess: Record<Plan, {entitlements, entitlementLimits}> (entitlements:6 binary features, entitlementLimits:38 numeric quotas number|false). hasEntitlement.ts:17: :18 admin→true, :25 org.plan ?? "oss", :40 entitlementAccess[plan].entitlements.includes(entitlement).
web/src/features/entitlements/constants/entitlements.ts · server/hasEntitlement.tsmaster table + gate
// binary feature switches + numeric quotas (number=capped / false=unlimited)
export const entitlements = ["audit-logs", "data-retention", "admin-api",
  "cloud-multi-tenant-sso", "scheduled-blob-exports", …] as const;

export const entitlementAccess: Record<Plan, {…}> = {
  "cloud:hobby": { entitlements: […], entitlementLimits: {
                     "organization-member-count": 2, "data-access-days": 30 } },
  "cloud:core":  { entitlements: […], entitlementLimits: {
                     "organization-member-count": false/*unlimited*/, "data-access-days": 90 } },
  "cloud:pro":   { entitlements: [… "data-retention"], … },
  // self-hosted:pro/enterprise, cloud:enterprise …
};

// the same one gate in front of every feature
export const hasEntitlement = (p) => {
  if (p.sessionUser.admin) return true;                 // admin passes outright
  const plan = org?.plan ?? "oss";                     // default fall back to free
  return entitlementAccess[plan].entitlements.includes(p.entitlement);
};

🔘 entitlement (binary)

A feature on or off: audit-logs, data-retention, admin-api, cloud-multi-tenant-sso… hasEntitlement checks "is it in the plan's list", returning true/false.

🔢 entitlementLimit (numeric)

How much of a resource: organization-member-count, data-access-days, monitor-count… the value is a number (capped) or false (unlimited), checked by hasEntitlementLimit.

🔑 license (self-host)

Self-hosting unlocks the enterprise tier: LANGFUSE_EE_LICENSE_KEY must start with langfuse_ee_ to count as enterprise (langfuse_pro_ doesn't); Cloud in any region has enterprise features natively.

The self-hosted unlock key: the EE license

The cloud version is hosted by Langfuse, with the plan written in the database. But how does a self-deployed version prove "I bought enterprise"? Via a license key. isEnterpriseLicenseAvailable()'s decision is crisp: ① is it Langfuse Cloud (any region) → enterprise features directly; ② self-hosted → check whether the env var LANGFUSE_EE_LICENSE_KEY starts with langfuse_ee_. Note one detail: a Pro license starting with langfuse_pro_ does not count as enterprise — the prefix itself encodes the authorization tier. With this key plugged in correctly, a self-hosted instance unlocks those enterprise entitlements.

isEnterpriseLicenseAvailable(): the prefix encodes the tier instance deployment? 1 Cloud (any region) → enterprise 2 self-host → check key prefix langfuse_ee_ → ✓ enterprise entitlement langfuse_pro_ → Pro (not enterprise) none / other → oss free fallback
QuestionOpen-core's answer
Is enterprise-feature code closed?No, all in the public repo (ee/, shared/.../ee/), readable, learnable, self-modifiable
Then what distinguishes free/paid?the runtime plan + hasEntitlement gate, not "whether the code exists"
What about orgs with no plan?plan ?? "oss" falls back to free — defaults to the safest (least entitlement), not to paid
How does self-hosting unlock enterprise?set LANGFUSE_EE_LICENSE_KEY=langfuse_ee_… (Pro's langfuse_pro_ isn't enterprise)
Where's EE code, who can depend on it?a separate package @langfuse/ee; dependency direction web → @langfuse/ee → @langfuse/shared

Connect the rows and open-core's elegance is clear: "can use" and "has code" are fully decoupled. The code is 100% public (transparent, auditable, community-contributable), while the commercial boundary is drawn by a thin runtime gate (plan + entitlement + license). This lets Langfuse be truly open source AND have a sustainable business model — the two aren't in conflict.

🎯 Design trade-off
Why make "can you use a feature" a unified hasEntitlement gate + one entitlementAccess master table, rather than "if plan == pro" in each feature? Same wisdom as Lesson 49's RBAC "role→scope," for the same reason: converge authority, ease evolution and auditing. Commercial plans change — adding a tier, adjusting a quota, demoting a feature from pro to core are all routine. If "pro can use X" judgments are scattered across dozens of feature sites, every change means a repo-wide search-and-edit, easy to miss, error-prone, and hard to review "which plan can use what." Folding it into one declarative master table: change commercial strategy = edit one row of this table, feature code untouched; want to know "what does pro include" = read one row. Extracting volatile commercial rules from stable feature logic and declaring them centrally is the key to keeping the system in step with the business.

Why does an org with no plan default to "oss" (free), rather than erroring or defaulting to the highest privileges? This is a "fail-safe" default choice, and the direction matters. Default to the highest privileges and the moment an org's plan field can't be read (a bug, a migration, missing data), it accidentally unlocks all paid features — a commercial leak and a privilege overreach. Default to erroring and you stall "the vast majority of self-hosted open-source users" (who should be oss anyway). Falling back to "oss" gets both right: open-source users work out of the box (the most common, smoothest path), while paid features are off by default, opened only by an explicit plan or license. A safe default should be the one with "least privilege, lightest impact" — entitlement defaults off, login defaults deny, IP-resolution failure defaults block (Lesson 44) — all facets of the same principle.
🎯 Key points
  • Open-core ≠ half-closed: all Langfuse features' code (incl. enterprise) is in the public repo, readable, learnable, self-modifiable. Free vs paid lies in runtime enablement, not "whether the code exists."
  • Plan tiering: an org carries a plan, defaulting to "oss" (free self-host), paid has cloud:hobby/core/pro/team/enterprise + self-hosted:pro/enterprise; isCloudPlan/isSelfHostedPlan split by prefix.
  • Master table + one gate: entitlementAccess: Record<Plan,{entitlements, entitlementLimits}> maps each plan to "which binary features + each resource's quota (number/false unlimited)"; hasEntitlement (admin→true, plan ?? "oss", includes) is the shared gate in front of every feature — converging authority, easing evolution, of one lineage with Lesson 49's RBAC.
  • EE license: isEnterpriseLicenseAvailable — Cloud (any region) has enterprise features; self-hosting checks whether LANGFUSE_EE_LICENSE_KEY starts with langfuse_ee_ (langfuse_pro_ isn't enterprise; the prefix encodes the tier).
  • Fail-safe default: no plan falls back to "oss" (least entitlement, paid features off by default), not defaulting to error or all-on — the same safe-default view as "login defaults deny, IP-resolution failure defaults block." EE code lives in a separate package @langfuse/ee, dependency direction web→ee→shared.

🧪 Self-test - think about the design

1. Regarding Langfuse's open-core model, which understanding is correct?
  1. the entire repo's code is all open source (including enterprise features like audit logs, data retention); free vs paid lies only in 'whether this org's plan can enable a feature at runtime', not in 'whether the code is public'—can-use and has-code are fully decoupled
  2. paid features are stripped at compile time; the open-source version lacks the code
  3. enterprise-feature code is closed; only the core is open
  4. all features are free; Langfuse profits from donations
Show answer & explanation click to expand
Answer: A. Open-core is often misread as 'half open, half closed', but Langfuse isn't: even audit logs, data retention, multi-tenant SSO code is in the public repo (ee/ and shared/.../ee/)—you can read, learn, modify it. What actually draws the commercial boundary is a thin runtime gate—the org's plan + hasEntitlement. So 'can use' depends on your plan, not 'does the code exist'. This design—getting code transparency and commercial sustainability at once—is open-core's elegance: 100% public + a layer of entitlement gating.
2. When hasEntitlement can't find an org's plan, it falls back to free oss via `org?.plan ?? "oss"`, rather than erroring or defaulting to highest privileges. What principle does this default reflect?
  1. to make the code shorter
  2. oss queries are faster than other plans
  3. fail-safe default: the default should be 'least privilege, lightest impact'. Defaulting to highest privileges would accidentally unlock all paid features when plan can't be read due to a bug/migration (leak + overreach); falling back to oss lets open-source users work out of the box with paid features off by default—same lineage as login-defaults-deny, IP-resolution-failure-defaults-block
  4. for compatibility with old database versions
Show answer & explanation click to expand
Answer: C. The direction of a default is a security decision. Suppose the plan field can't be read due to a bug, data migration, or missing field: defaulting to highest privileges instantly unlocks all paid features for that org—a commercial leak and a privilege overreach; defaulting to error stalls the vast majority of self-hosted open-source users who are oss anyway. Falling back to oss gets both: open-source users (the common path) work out of the box, paid features off by default, opened only by an explicit plan/license. Same fail-safe principle as Lesson 44's 'IP-resolution failure defaults to block' and Lesson 48's 'login defaults to deny'—when unsure, pick the least-privilege, lightest-impact default.
3. Langfuse folds 'which plan can use which features' into one declarative entitlementAccess master table, with every feature calling the same hasEntitlement gate, rather than scattering 'if plan==pro' across features. The biggest benefit is?
  1. extracting volatile commercial rules from stable feature logic and declaring them centrally: adding a tier/adjusting a quota/demoting a feature from pro to core needs editing one table row, feature code untouched; to know what a plan includes, read one row—easing evolution and auditing, avoiding scattered checks being missed or mis-edited
  2. the master table runs faster than scattered if checks
  3. the master table auto-generates billing invoices
  4. this eliminates the need for the plan concept
Show answer & explanation click to expand
Answer: A. Commercial plans change frequently: adding a tier, adjusting a quota, demoting a feature from pro to core are all common. If 'only pro can use X' is scattered across dozens of feature sites, every change means a repo-wide search-and-edit—easy to miss, error-prone, hard to review 'which plan can use what'. Folded into one declarative master table: change strategy = edit one row, feature code untouched; check 'what pro includes' = read one row. Same wisdom as Lesson 49's RBAC 'role→scope' table—extract volatile rules from stable logic and declare centrally, keeping the system in step with the business and making permissions/entitlements auditable at a glance.
💭 Open questions (no single right answer - just think or try)
  • Open-core lets Langfuse have both 'fully public code + commercial sustainability': 100% open source, with a thin runtime gate (plan + entitlement + license) drawing the commercial boundary. Share your view: versus 'pure open source (all free)' and 'pure closed (all paid)', what trade-off does open-core strike between business and community? For users (can read all the code, can self-host, but enterprise features need a license), is it friendlier or more restrictive? If commercializing a project of your own, which model would you choose, and why?