OpenMausBot 双许可架构详解:Apache 2.0 核心、enterprise/ 授权边界与 Ed25519 许可证密钥机制
OpenMausBot 双许可架构详解:Apache 2.0 核心、enterprise/ 授权边界与 Ed25519 许可证密钥机制
OpenMausBot 采用"开放核心(open core)"的双层许可结构:仓库主体以 Apache License 2.0 发布,只有 enterprise/ 一个目录走独立的源码可见(source-available)许可。这篇指南沿着 LICENSING.md 的脉络,逐条拆解这条边界的法务含义、代码落点与运行时表现,并深入到 server/enterprise.ts 与 enterprise/server/license.ts 的实现,说明许可证密钥 omb1.<claims>.<signature> 如何在没有联网校验的前提下决定一台服务器是 oss 还是 enterprise、功能如何按 entitlement id 逐项放行、到期后 7 天宽限期如何生效,以及自建、二次分发与贡献代码时各自该遵守什么规则。
一、两层许可的整体版图
LICENSING.md 开篇给出的结论很短:OpenMausBot 以 Apache License 2.0 开源,"with one carve-out and a few notes"。这一个 carve-out 指的就是 enterprise/ 目录,其余几条注记分别关于贡献流程、第三方组件与商标。
| 范围 | 许可 | 典型使用者 | 关键义务 |
|---|---|---|---|
仓库根目录及 enterprise/ 之外的一切 |
Apache License 2.0(LICENSE) | 自建用户、二次开发者、公开 PR 贡献者 | 保留版权与许可声明、NOTICE、商标条款 |
enterprise/ 目录 |
OpenMausBot Enterprise License(enterprise/LICENSE) | 托管部署方、白标合作伙伴 | 生产环境启用功能需有效密钥;不得再分发 |
需要特别注意:Apache 2.0 覆盖的是"其余一切",而不是"整个产品"。判断某个文件属于哪一层,唯一依据是路径是否位于 enterprise/ 下——enterprise/LICENSE 第 5 条明确写道,该目录内的全部内容 NOT covered by the Apache License 2.0。仓库根部的 NOTICE 记录了项目从 MIT 迁移到 Apache 2.0 的历史,以及内嵌第三方代码的归属,这是 Apache 2.0 第 4(d) 条要求随分发保留的文件。
二、enterprise/ 的授权边界:能做什么、不能做什么
enterprise/LICENSE 用五条把边界划得很清楚,比 LICENSING.md 中的概述更具体。逐条对照如下。
第 1 条:源码可见(source-available)与自由评估。 你可以阅读、构建、评估这份代码,并且可以为评估目的修改它——目的说得也很直白:"so that you know exactly what runs"。开发、测试、评估用途免费。这意味着安全团队可以在采购前完整审计这一层,而不需要拿到二进制。
第 2 条:生产启用需要许可证密钥。 在生产环境启用企业功能,需要版权持有人为你的组织签发的、未过期的许可证密钥,且受一份单独协议约束,该协议规定授权功能、席位与期限。功能集合由密钥里的 claims 决定,而不是由代码分支决定。
第 3 条:不得再分发、不得绕过许可检查。 不得再分发、再许可、出售、为第三方托管或作为服务提供这个目录或其修改版本;也不得移除、禁用或规避许可检查。为第三方托管、转售、白标,只有在与版权持有人签署书面合作伙伴协议后才被允许。这对应 LICENSING.md 中"Hosting it for third parties or white-labelling the product needs a partner agreement"的表述。
第 4 条:删除即回归开源版。 删掉这个目录,仓库其余部分仍可构建并以 Apache 2.0 的开源版运行,不受本许可任何义务约束。这一条是整套设计的技术基石,后文第三节会看到它是如何在代码和 CI 中被真正验证的。
第 5 条:无担保。 代码按 "as is" 提供,不附带任何形式的担保,并在法律允许范围内免除版权持有人的责任。
把这几条翻译成日常决策:
| 场景 | 是否允许 | 依据 |
|---|---|---|
| 自建一套服务器自用,只用开源功能 | 允许,Apache 2.0 | LICENSING.md |
阅读 enterprise/ 源码做安全审计 |
允许 | enterprise/LICENSE 第 1 条 |
| 在测试环境跑白标功能做验证 | 允许,免费 | enterprise/LICENSE 第 1 条 |
在生产环境启用 whitelabel、admin 等功能 |
需要为该组织签发的有效密钥 | enterprise/LICENSE 第 2 条 |
把改过的 enterprise/ 放到自己的公开仓库 |
不允许 | enterprise/LICENSE 第 3 条 |
| 拿 OpenMausBot 做成 SaaS 卖给客户 | 需要书面合作伙伴协议 | LICENSING.md、enterprise/LICENSE 第 3 条 |
fork 仓库并删除 enterprise/ 后对外发行 |
允许,回归 Apache 2.0 版 | enterprise/LICENSE 第 4 条 |
三、删掉 enterprise/ 之后:hook 点、加载顺序与降级
LICENSING.md 用一句话描述删除后的行为:"the server reports {"edition":"oss"} and ordinary standalone operation is unchanged"。这句话背后是一个刻意设计得很窄的接缝。
3.1 单一 hook 点,核心从不静态引用
enterprise/README.md 说得很明确:核心只通过一个 hook 点 server/enterprise.ts 触达这一层,没有任何核心文件从 enterprise/ 里 import 任何东西。落到代码上,server/enterprise.ts 的 loadEnterpriseLayer() 使用动态 import():
const loaded: unknown = await import(pathToFileURL(entry).href);
const access: unknown = Reflect.get(Object(loaded), "createWorkspaceAccess");
if (typeof access === "function") workspaceAccessFactory = access as (options: WorkspaceAccessOptions) => WorkspaceAccess;
const register: unknown = Reflect.get(Object(loaded), "register");
if (typeof register !== "function") throw new Error(`${entry} does not export register()`);
这也是为什么删除目录后 pnpm typecheck 仍能通过——类型上根本没有指向该目录的静态依赖。动态导入的返回值还要过一遍 Zod 校验(layerSchema),因为它是"外部代码":customer 必须是非空字符串,features 必须是字符串数组,expiresAt 必须是字符串或 null。
3.2 查找顺序:三种部署形态的统一入口
enterpriseLayerDirs()(server/enterprise.ts)定义了目录解析顺序:
export function enterpriseLayerDirs(env: NodeJS.ProcessEnv = process.env, serverRoot: string = SERVER_ROOT): string[] {
if (env.OMB_ENTERPRISE_DIR) return [env.OMB_ENTERPRISE_DIR];
return [join(serverRoot, "..", "enterprise"), join(serverRoot, "enterprise")];
}
对应到实际部署:
- 设置了
OMB_ENTERPRISE_DIR时,只看这一个目录; - 否则先看 server root 的兄弟目录(源码检出、npm 包布局);
- 再看 server root 内部(
dist-server/enterprise/,Docker 镜像与打包桌面端只有这一份)。
每个目录里,layerEntry() 会依次尝试 server/index.ts 与 server/index.js。打包环节负责把 TypeScript 源编译成后者:scripts/bundle-server.mjs 仅在 enterprise/server/index.ts 存在时才产出 dist-server/enterprise/server/index.js,并把 enterprise/LICENSE 一并复制过去——分发二进制时许可文本跟着走,这本身就是许可合规的一部分。
server/enterprise.test.ts 对这个顺序做了完整断言,包括"三层都不存在时,notice 会把所有查找过的路径都列出来"这种对运维非常友好的行为:
OMB_LICENSE_KEY is set but no enterprise layer exists at <root>/enterprise or <root>/dist-server/enterprise
3.3 降级绝不抛异常
loadEnterpriseLayer() 的注释只有一句但很关键:"Never throws: a broken layer or key degrades to the open-source edition with a notice saying what to fix." 所有失败路径都收敛到 oss(notice)(server/enterprise.ts):
| 触发条件 | 上报结果 |
|---|---|
找不到层,但设了 OMB_LICENSE_KEY |
oss + "no enterprise layer exists at …" |
找到层,但没设 OMB_LICENSE_KEY |
oss + "enterprise layer present but OMB_LICENSE_KEY is not set" |
层未导出 register() |
oss + "does not export register()" |
register() 抛错(签名错误、已过期等) |
oss + "enterprise layer disabled: <原因>" |
register() 返回结构不合法 |
oss + "enterprise layer disabled: …" |
这条策略的意义在自建场景下尤其明显:一张写错的密钥不应该让一台独立服务器起不来,运维只需要看日志或 GET /api/edition 的 notice 就知道该修什么。
3.4 有一个例外:托管工作区必须 fail closed
LICENSING.md 单独用一段提醒:一个被显式配置为托管登录的工作区,在缺少这个可选适配器时拒绝远程访问;移除企业层绝不能绕过它已配置的登录权威。这条不是建议而是硬性设计,代码里体现为 createWorkspaceAccess()(server/enterprise.ts):
export function createWorkspaceAccess(options: Omit<WorkspaceAccessOptions, "entitled">): WorkspaceAccess | null {
if (!hostedWorkspaceConfigured(options.env)) return null;
return workspaceAccessFactory?.({ ...options, entitled: () => entitled("admin") }) ?? null;
}
hostedWorkspaceConfigured() 只要看到 OMB_ADMIN_URL、OMB_ADMIN_WORKSPACE、OMB_ADMIN_MEMBERSHIP 中任意一个被设置(哪怕设成空字符串)就返回 true(server/enterprise.test.ts 明确断言了 OMB_ADMIN_URL: "" 也算已配置)。此时如果适配器工厂不存在,函数返回 null,服务器不会退回到邮件验证码或配对码登录,而是拒绝远程访问。换句话说:普通单机部署少一个目录只是少了几个企业功能;托管部署少一个目录是明确拒绝服务,而不是悄悄降级成弱认证。
3.5 CI 如何证明这条承诺
.github 中的 foss 作业就把 LICENSING.md 的承诺变成了可执行的检查(.github/workflows/ci.yml):
name: open-source edition builds without enterprise/
...
- name: Delete the enterprise folder
run: rm -rf enterprise
- run: pnpm typecheck
- run: pnpm exec vitest run server/enterprise.test.ts server/brand.test.ts
随后它用 OMB_LICENSE_KEY=omb1.not.real 启动服务器,请求 /api/edition,并断言响应里同时出现 "edition":"oss" 与 no enterprise layer exists。这一步很巧妙:它证明的不只是"能编译",而是"即使有人误设了密钥,缺目录时也不会崩、也不会谎称自己是企业版"。
LICENSING.md 也坦白了这个作业的覆盖边界:它证明 OSS 构建、启动响应与适配器工厂缺失,"does not exercise every hosted HTTP route";托管工作区的登录与吊销路径由隔离的托管测试单独验证(可参见 server/hosted-access.test.ts)。这种"说明自己没测什么"的写法,比笼统宣称"全链路验证"更值得信任。
四、许可证密钥:omb1.<claims>.<signature>
这是整套授权机制的技术核心。设计目标写在 enterprise/server/license.ts 的注释里:一个构建服务所有客户,密钥(而非代码)决定功能集合,校验完全离线,不向任何服务器回连。
4.1 密钥结构
omb1.<base64url(claims JSON)>.<base64url(Ed25519 signature)>
- 固定前缀
omb1,PREFIX = "omb1"; - 中间段是 可直接阅读的 base64url 编码 JSON claims——enterprise/scripts/issue-license.mjs 明确说 "Claims are visible to the customer",只有签名是密钥派生的;
- 末段是对 claims 字节的 Ed25519 签名(
sign(null, signed, privateKey),Ed25519 不使用单独的摘要算法,故传null)。
格式不对时给出可操作错误(enterprise/server/license.ts):
OMB_LICENSE_KEY is not an OpenMausBot license key (expected "omb1.<claims>.<signature>")
4.2 claims 的四个字段
claimsSchema 用 Zod 定义(enterprise/server/license.ts):
export const claimsSchema = z.object({
v: z.literal(1),
customer: z.string().min(1),
features: z.array(z.string().min(1)),
issued: z.iso.date("issued must be a YYYY-MM-DD date"),
expires: z.iso.date("expires must be a YYYY-MM-DD date").nullable(),
});
| 字段 | 类型 | 含义 | 实现细节 |
|---|---|---|---|
v |
字面量 1 |
claims 版本 | 目前只接受 1,为将来演进留位 |
customer |
非空字符串 | 授权对象,UI 与启动日志都会显示 | describeEdition() 拼成 "openmausbot enterprise edition for Acme" |
features |
非空字符串数组 | entitlement id 列表 | 载入后 [...new Set(features)].sort() 去重排序 |
issued |
YYYY-MM-DD |
签发日 | 由脚本以 new Date().toISOString().slice(0, 10) 写入 |
expires |
YYYY-MM-DD 或 null |
失效日,null 表示永久 |
解析为 UTC 零点比较 |
features 里放未知 id 不会导致失败——这是刻意的,见第六节。
4.3 五个校验步骤与对应错误
verifyLicenseKey()(enterprise/server/license.ts)按顺序做五件事,每类失败都给出"下一步该做什么",而不是只抛一个 invalid key:
- 分段与前缀:必须正好三段、首段为
omb1、后两段非空; - 签名验证:对每个内置公钥尝试
verify(null, signed, publicKey, signature),任一通过即可; - JSON 解析:失败提示 "claims are not JSON; ask for the key to be reissued";
- Schema 校验:失败提示具体是哪一条 claim 不合法;
- 有效期比较:
expires非null且now >= expires时抛错,"OMB_LICENSE_KEY expired on …; renew it to keep enterprise features"。
签名失败时的措辞值得注意(enterprise/server/license.ts):"the key was altered, or it was issued for a different build"。这解释了为什么公钥被硬编码在源码里——公钥进代码,私钥不进仓库:
export const LICENSE_PUBLIC_KEYS: readonly string[] = [
"6CHdwwJzxKJFimRkC79eQ5FR__bX2WaU2BBGNGPQTQU",
];
数组注释给出轮换规则:按追加顺序排列,在仍有密钥在用的情况下永不编辑或删除已有条目。这样老客户手里的旧密钥不会因为一次轮换失效。
4.4 一次构建,服务所有客户
因为功能集合来自密钥而非编译期开关,同一个 Docker 镜像、同一个 npm 包、同一个桌面端安装包可以发给所有客户。这也是 enterprise/README.md 那句 "one build serves every customer" 的技术根据。对企业采购方而言,好处是审计对象唯一;对项目方而言,好处是无需为每个客户单独出包。
五、到期、宽限期与降级:7 天是怎么算的
许可到期不是一个"开关",而是一段有明确时间线、有分级可见性的过程。
5.1 三个常量
export const LICENSE_WARN_DAYS = 30;
export const LICENSE_GRACE_DAYS = 7;
const DAY_MS = 24 * 60 * 60_000;
企业层自身还有一道夹紧(clamp):enterprise/server/index.ts 的 MAX_GRACE_DAYS = 14,并且要求传入值有限、非负:
const graceDays = Math.min(MAX_GRACE_DAYS, Math.max(0, Number.isFinite(options.graceDays) ? options.graceDays! : 0));
const claims = verifyLicenseKey(options.licenseKey, { now: new Date((options.now ?? Date.now()) - graceDays * DAY_MS) });
"宽限"的实现极简:把用于比较的时间往前拨 7 天。密钥格式与签名逻辑一行都不用改,企业层只是接受"过期不到 7 天"的密钥。核心传 7,层最多接受 14,超出的数字不被信任——这是核心对外部代码的第二次防御(第一次是 Zod 校验返回结构)。
5.2 时间线
| 阶段 | 条件 | edition |
行为 |
|---|---|---|---|
| 正常 | now < expires |
enterprise |
功能全部按 claims 放行;带 expiresInDays |
| 临期预警 | expiresInDays <= 30 |
enterprise |
启动时 console.warn,管理员 Settings 出现横幅 |
| 宽限期 | expires <= now < expires + 7d |
enterprise |
功能继续可用,附 graceEndsAt 与续期提示 |
| 已失效 | now >= expires + 7d |
oss |
功能停止,无需重启 |
"无需重启"对应 editionStatus()(server/enterprise.ts)的实现——它每次调用都重新判断是否越过 at + LICENSE_GRACE_DAYS * DAY_MS,而不是在启动时缓存一个布尔值:
function expired(now: number): boolean {
const at = expiryAt();
return at !== null && now >= at + LICENSE_GRACE_DAYS * DAY_MS;
}
entitled(feature)(server/enterprise.ts)因此每次都同时检查"未失效"和"id 在列表中":
export function entitled(feature: string, now: number = Date.now()): boolean {
return !expired(now) && current.features.includes(feature);
}
server/enterprise.test.ts 对边界做了秒级断言:2026-12-31T23:59:59Z 为 true、2027-01-01T00:00:00Z(到期瞬间)在宽限期内仍为 true、2027-01-07T23:59:59Z 仍为 true、再往后为 false。
5.3 谁能看到"什么时候到期"
这是一个容易被忽略但很实用的设计:普通成员看不到倒计时。GET /api/edition 按会话权限分流(server/routes/status.ts):
if (method === "GET" && path === "/api/edition") {
// A member learns what is entitled; when the key lapses is for admins.
const status = editionStatus();
return json(res, 200, auth.scopes.includes("admin") ? status : editionForMembers(status));
}
editionForMembers() 把 expiresInDays、graceEndsAt、notice 三个字段摘掉(server/enterprise.ts),成员只知道"有哪些功能",不知道采购与续期细节。Settings 侧还有 editionForSettings(),只在临近或已过到期日时才返回 license 块,避免长期挂着一个无意义的横幅。
5.4 三种真实的 /api/edition 响应
{ "edition": "enterprise", "customer": "Acme", "features": ["budgets", "whitelabel"], "expiresAt": "2027-09-02", "expiresInDays": 12 }
{ "edition": "enterprise", "customer": "Acme", "features": ["budgets", "whitelabel"], "expiresAt": "2027-09-02", "expiresInDays": -2, "graceEndsAt": "2027-09-09", "notice": "OMB_LICENSE_KEY expired on 2027-09-02; enterprise features keep working until 2027-09-09 while it is renewed" }
{ "edition": "oss", "features": [], "notice": "enterprise layer disabled: OMB_LICENSE_KEY expired on 2027-09-02; renew it to keep enterprise features" }
注意第二条的 expiresInDays 是负数(Math.ceil 得出的剩余天数一旦为负就表示已过期几天),同时 graceEndsAt 出现,这就是"运维还有 5 天"的可观测信号。第三条则完全退回 oss,notice 里保留了原因,方便排障。
启动时的可观测性在 server/index.ts 里:服务器在接受请求之前先解析版本并打印一行,再判断是否需要告警。
// Resolve the edition before accepting requests so /api/edition is never a guess.
console.log(describeEdition(await loadEnterpriseLayer()));
const startupLicenseWarning = licenseWarning(editionStatus());
if (startupLicenseWarning) console.warn(startupLicenseWarning);
describeEdition() 的输出形如 openmausbot enterprise edition for Acme until 2027-09-02: budgets, whitelabel,开源版则附带 notice 括号。
六、entitlement id:功能是怎么被逐个放行的
LICENSING.md 只指了一句"列表在 enterprise/FEATURES",而 enterprise/README.md 给出了完整表格。两份文档的地位不同:FEATURES 是权威清单,README 是说明。
6.1 当前 id 一览
| id | 解锁内容 | 状态 |
|---|---|---|
whitelabel |
从 brand.json 读取产品名、标语、强调色、logo、favicon、支持链接 |
shipped |
sso |
通过 OIDC 身份提供方登录(含 scope 映射规划) | 尚未落地:目前没有任何检查点 |
admin |
Settings → Installations,以及可选的托管工作区登录适配器 | shipped |
budgets |
整个工作区一个月度支出上限,触顶后拒绝新回合,带预警百分比与管理员通知 | shipped |
billing |
按模型的售价:Usage → History 的可计费列与 CSV,以及替换成本估算里的标价 | shipped |
FEATURES 文件还额外写了两条实现约定:
- 未知 id 不授权任何东西,因此密钥可以先于功能落地签发(对应
entitled()里的includes判断); - 新增 id 时,同一 PR 里要在
FEATURES加一行,并加上对应的entitled("id")检查。
第 2 条是防止"文档说有、代码没门"的漂移。sso 的状态描述正是这种诚实的体现——它在表里,但没人检查它。
6.2 entitled() 的真实调用点
光看文档容易以为门控只有一个入口,实际搜一遍源码会看到四类用法,各有各的语义:
server/index.ts:1389 entitled("billing") → 是否用自定义售价替换标价
server/index.ts:743 entitled("admin") → 共享工作区全量访问是否生效
server/index.ts:12280 entitled("admin") → 托管 Slack 路由是否就绪
server/index.ts:12736 entitled("admin") → 门禁托管成员资格
server/routes/status.ts:86 entitled("admin") → /api/fleet* 系列
server/brand.ts:76 entitled("whitelabel")→ brand.json 是否应用
server/spend.ts:81 entitled("budgets") → 月度支出上限是否强制
其中 whitelabel 的落点最直观(server/brand.ts):文件存在、JSON 合法、Schema 通过之后,还要过最后一道门,否则退回默认品牌并把原因写进 notice。
if (!isEntitled("whitelabel")) {
return fallback(`${file} found but this server is not licensed for whitelabel; using the default brand`);
}
budgets 的门控同样直接(server/spend.ts):未授权、或配置里的 monthlyUsd 不是正数,都直接返回 null,即"无上限",而不是"上限为零"——这个默认值的方向很重要,避免误配把工作区锁死。
admin 在 server/routes/status.ts 的表现是一个明确的 403:
if (!entitled("admin")) return json(res, 403, { error: "Workspaces need an enterprise licence with the admin feature." });
而且它排在"fleet agent 是否存在"检查之前——先告诉你缺授权,再告诉你缺进程,排查路径清晰。
七、签发密钥:两条命令与一份私钥
enterprise/scripts/issue-license.mjs 是唯一的签发工具,依赖 Node 内置 crypto 的 generateKeyPairSync("ed25519")。
7.1 生成签名密钥对(只做一次)
node enterprise/scripts/issue-license.mjs keygen # once; prints the public key to add to license.ts
默认写到 ~/.config/openmausbot-enterprise/signing-key.json,可用 --out 指定。脚本在安全细节上做了三件事:
- 目录以
mode: 0o700创建; - 私钥以
mode: 0o600+flag: "wx"一次性写入,注释写道 "no window where a 0666 file holds the key",即不存在"先创建 666 再 chmod"的竞态窗口; - 目标文件已存在时直接失败:
already exists; move it away first (a lost key means reissuing every customer)。
成功后它会打印一行公钥,需要手工追加到 enterprise/server/license.ts 的 LICENSE_PUBLIC_KEYS。
7.2 签发一张密钥
node enterprise/scripts/issue-license.mjs issue --customer "Acme" --features whitelabel,sso --expires 2027-09-02
参数语义:
| 参数 | 必填 | 说明 |
|---|---|---|
--customer |
是 | 授权对象名称,会出现在 UI 与启动日志 |
--features |
是 | 逗号分隔的 entitlement id,会 trim 并过滤空项 |
--expires |
否 | YYYY-MM-DD;省略即 null,表示永久 |
--key |
否 | 私钥路径,默认 ~/.config/openmausbot-enterprise/signing-key.json |
脚本把 issued 自动填成当天,v 固定为 1,然后调用 enterprise/server/license.ts 的 issueLicenseKey(),把整串密钥打到 stdout,方便直接喂给 OMB_LICENSE_KEY。
flags() 解析器对格式很严格:任何不以 -- 开头的参数、或用 -- 开头的值都会立即失败并打印用法。这避免了 --expires 忘写值却静默生成永久密钥的常见事故。
7.3 私钥的三条纪律
enterprise/scripts/issue-license.mjs 顶部一句话概括:"The private key never enters the repo, a chat, or a container image." 配套约束:
- 不进仓库——
LICENSE_PUBLIC_KEYS里只有公钥的 JWKx值; - 不进镜像——「校验离线」意味着运行中的服务器只需要公钥,签发可以在完全隔离的机器上完成;
- 必须备份——丢失私钥的后果是"给所有客户重发密钥",因为旧密钥虽然仍能验证,但无法再为新客户或新功能签发。
轮换方式:keygen --out 造新对,把新公钥追加到数组末尾,旧条目保留;旧密钥签出的密钥在到期前继续有效。
八、部署形态:同一份许可在四种环境里的落点
| 形态 | 企业层位置 | 关键配置 | 备注 |
|---|---|---|---|
| 源码检出 | <repo>/enterprise/ |
OMB_LICENSE_KEY |
兄弟目录优先 |
| npm 包 | <package>/enterprise/ |
同上 | 打包时保留 |
| Docker 镜像 | dist-server/enterprise/server/index.js |
同上,通常配 /data 卷 |
由 scripts/bundle-server.mjs 生成 |
| 桌面端 | 同上(只带 dist-server/) |
同上 | 桌面端不启动托管控制台 |
OMB_ENTERPRISE_DIR 用于把这些默认打破,例如把授权层挂到只读卷上统一管理。注意它一旦设置就只看这一个位置,设错不会回退到兄弟目录——server/enterprise.test.ts 专门断言了这一点。
enterprise/README.md 还提到 scripts/bundle-server.mjs 会把 LICENSE 一起写进 bundle。这解释了一个运维常见疑问:"为什么镜像里有个 dist-server/enterprise/LICENSE?"——因为分发该目录必须随附它的许可,这与 Apache 2.0 要求保留 NOTICE 是同一类义务。
托管场景下的相关环境变量(来自 hostedWorkspaceConfiguration() 的校验逻辑,server/enterprise.ts):
| 变量 | 约束 |
|---|---|
OMB_ADMIN_URL |
必须是 https: 的纯 origin(不能带路径) |
OMB_PUBLIC_URL |
同上 |
OMB_ADMIN_WORKSPACE |
需匹配 ^[a-z][a-z0-9-]{1,30}$ |
OMB_ADMIN_MEMBERSHIP |
只接受 local 或 portal(大小写敏感) |
OMB_SHARED_WORKSPACE_FULL_ACCESS |
仅 "1" 生效,且要求 OMB_DESKTOP_PARENT !== "1"、托管配置完整且 portalMembership 为真 |
任意一项不满足,hostedWorkspaceConfiguration() 返回 null,托管配置被视为不完整——"partial setting is never standalone"。OMB_SHARED_WORKSPACE_FULL_ACCESS 被限定为只能来自专用、由门户托管的服务器,"never an HTTP setting or a desktop grant",这是防止通过请求或桌面授权提权。
白标配置文件的位置由 brandFile() 决定(server/brand.ts):优先 OMB_BRAND_FILE,否则 OMB_DATA_DIR(Docker 下即 /data 卷)中的 brand.json。文件在每次 GET /api/brand 时重新读取,所以改完刷新即可生效;而且应用在首帧之前就取品牌,窗口不会先闪一下默认名字。
brand.json 完整字段见 enterprise/README.md:
{
"name": "Reliable Platform",
"tagline": "Back office, on autopilot",
"accent": "#1D4ED8",
"logo": "data:image/svg+xml;base64,…",
"favicon": "data:image/png;base64,…",
"supportUrl": "https://help.example.com"
}
只有 name 必填;logo 是内联 data:image/… URI 或 https:// URL;accent 为 6 位十六进制,文字颜色按对比度自动推导。README 同时列出了 brand.json 改不动的东西,因为它们烘进了打包产物:桌面端 bundle 与菜单栏名称、安装包名、macOS 权限提示、iOS 应用名、辅助程序路径。真正完整的桌面端换牌是"每客户打包作业",不是配置。
九、贡献规则:目录决定流程
LICENSING.md 把贡献分成两种,判断依据只有一条——改的是不是 enterprise/。
9.1 目录外:Apache 2.0,无需 DCO、无需 CLA
- Outside `enterprise/`: contribute under Apache 2.0. No DCO sign-off or CLA is
required. Submit only code you wrote or have the right to contribute.
- Inside `enterprise/`: sign the Contributor License Agreement once, by
commenting on your pull request.
对企业贡献者来说这是相当宽松的门槛:不需要 Signed-off-by 尾巴,不需要签署任何文件,PR 直接按 Apache 2.0 授权。前提是你提交的确实是你写的、或你有权提交的代码。
9.2 目录内:一次性 CLA
CLA.md 说明覆盖范围仅限 enterprise/,签署方式是在 PR 下评论一句话:"I have read the CLA Document and I hereby sign the CLA"。性质是许可而非转让(第 6 条明确 "You keep your rights"),但授权范围较宽:永久、全球、非独占、免费、不可撤销的版权与专利许可,允许版权持有人以包括 OpenMausBot Enterprise License 与 Apache 2.0 在内的任意许可分发你的贡献。
这正是"同一份代码双重许可"能成立的法律前提:如果贡献者只肯按 Apache 2.0 授权,项目就无法把该目录继续放在企业许可下分发。第 3、4 条还要求你有权作出该授权(含雇主权利的处理),且贡献为你原创——包含他人代码时须在 PR 中标注来源与许可。
9.3 CODEOWNERS 把边界钉在评审流程里
LICENSING.md 说 "The open-core boundary, the cloud seam and this file are covered by CODEOWNERS: a maintainer reviews changes there",具体清单在 .github/CODEOWNERS:
/enterprise/ @milind-soni
/server/enterprise.ts @milind-soni
/server/enterprise.test.ts @milind-soni
/server/brand.ts @milind-soni
/server/tunnel.ts @milind-soni
/cloudflare/control-plane/ @milind-soni
/LICENSE @milind-soni
/LICENSING.md @milind-soni
/CLA.md @milind-soni
这份清单很有信息量:它同时保护了企业层本身、hook 点及其测试、受 entitlement 门控的品牌模块、云侧接缝,以及全部许可文本。注意 /server/license-expiry-api.test.ts 之类的验证测试也在 server/ 下,但真正被指定的是边界相关的关键文件——这些文件的改动会直接改变许可行为,必须由维护者过目。
十、第三方组件与商标:最容易踩的两条
10.1 内嵌组件的许可各自独立
LICENSING.md:随附的第三方软件保留其自身许可,声明、许可全文、源码位置与 SBOM 列在 NOTICE 与 third_party/ 中。目录里能看到 t3-code、playwright-injected、puppeteer、opencode、cloudflared、cua-driver、hpke-js、onepassword-sdk 等条目,每个子目录一份许可文本。例如 NOTICE 说明 Google Antigravity ACP 集成改编自 T3 Code(MIT),并指向 third_party/t3-code/LICENSE。
实际含义:如果你要对外分发构建产物,Apache 2.0 的合规动作(保留 NOTICE、LICENSE)不等于完成了全部合规——third_party/ 下每个组件的许可条款仍需各自满足。项目把这些材料集中在一个目录里,就是为了让这项核对可执行。
10.2 商标不在 Apache 2.0 的授权范围内
LICENSING.md 指出 OpenMausBot 与 MausBot 名称及吉祥物是 Supamaus Software Private Limited 的商标,而 Apache License 第 6 条明确不授予商标权。因此基于 OpenMausBot 构建的产品需要自己的名字,除非有合作伙伴协议另作约定。
这条与白标功能容易被混为一谈,但两者完全不同:
白标(whitelabel) |
商标 | |
|---|---|---|
| 控制手段 | 你的许可证里的 entitlement + brand.json |
法律条款,无法通过配置解除 |
| 能改什么 | 应用内显示的名称、标语、配色、logo、支持链接 | 不能改:仓库名、版权声明、许可文本 |
| 不能改什么 | 打包期固定的安装包名、菜单栏名、系统权限提示等 | 不能把 OpenMausBot/MausBot 用作你的产品名 |
所以"我买了 whitelabel 就能把产品叫 OpenMausBot Pro 卖出去"是错误理解:配置能改的是运行时品牌,商标权从未随代码授予。反过来,"我删了 enterprise/ 用 Apache 2.0 版"也不自动获得商标使用权——你仍然需要为自己的发行版起名。
十一、把路由规则用起来:新功能该放哪
LICENSING.md 给出一个可以逐字套用的判定流程,enterprise/README.md 复述了一遍:
- 任何开源用户都可能想要它吗? → 放核心,走公开 PR,Apache 2.0。
- 是组织级、管理级、分层级的,或者是"下一任企业负责人会被展示"的东西? → 放
enterprise/,挂在 entitlement 后面。 - 客户专属的品牌、技能、包、连接器? → 放客户自己的仓库,以数据和配置形式存在,永远不要 fork。
第 3 条最值得强调:为单个客户 fork 主仓库会让升级、安全补丁和许可边界同时失控。项目明确把这些内容定义为"数据与配置",意味着它们应当通过 brand.json、技能目录、连接器配置这类机制注入,而不是改代码。
配合这套规则的还有 FEATURES 文件里的维护约定——新增 entitlement 时,文档与 entitled("id") 检查必须在同一个 PR 里出现。这条约定让"文档承诺"与"代码事实"保持同步,避免出现第 6.1 节提到的 sso 那样的状态被误读成"已可用"。
十二、上线前自检清单
面向不同角色,把上面的内容压缩成可执行的核对项。
自建 / 单机部署
- [ ] 只用开源功能时,无需
OMB_LICENSE_KEY;设置它反而会在缺目录时产生 notice。 - [ ] 启动日志里
describeEdition()那一行是否与预期一致? - [ ]
curl -s http://127.0.0.1:<port>/api/edition的edition字段是否为oss或enterprise? - [ ] 若为
oss且带 notice,按提示修复(缺目录 / 缺密钥 / 签名不符 / 已过期)。
企业部署
- [ ] 密钥的
customer与实际授权主体一致;features覆盖所需 id。 - [ ]
expires已登记进续期日历,且不晚于expires + 7 天触发告警。 - [ ] 管理员会话下 Settings 是否出现临期横幅(仅在
expiresInDays <= 30时出现)。 - [ ] 若启用托管登录:
OMB_ADMIN_URL/OMB_PUBLIC_URL均为纯 origin 的 https 地址,OMB_ADMIN_WORKSPACE符合命名规则。 - [ ] 明确知道:托管工作区在缺少
adminentitlement 或适配器时会 拒绝远程访问,不会退回邮件/配对码。
分发与二次开发
- [ ] 若删除
enterprise/,确认pnpm typecheck与server/enterprise.test.ts、server/brand.test.ts通过。 - [ ] 分发产物中保留 LICENSE、NOTICE 与 third_party/ 下各组件的许可文本。
- [ ] 产品名不使用 OpenMausBot / MausBot 及吉祥物,除非有书面合作伙伴协议。
- [ ] 不修改、不绕过
entitled()与密钥校验逻辑。
贡献者
- [ ] 改动落在
enterprise/之外:无需 DCO/CLA,按 Apache 2.0 提交。 - [ ] 改动落在
enterprise/之内:PR 中评论签署 CLA.md,并确认贡献为原创或已标注第三方来源。 - [ ] 新增 entitlement 时,同一 PR 内更新 enterprise/FEATURES 并加上
entitled("id")检查。
结语
OpenMausBot 的许可设计有两个值得借鉴的工程习惯。第一,把法律边界变成一个可执行的文件边界:enterprise/ 是唯一的分界线,核心只通过一个动态导入的 hook 触达它,CI 里有一条名为 open-source edition builds without enterprise/ 的作业真去 rm -rf enterprise 然后编译、测试、启动、断言 "edition":"oss"。第二,把授权状态变成可观测的运行时事实:GET /api/edition 把 customer、features、expiresInDays、graceEndsAt、notice 一并暴露,启动日志先打印版本再接受请求,降级永不抛异常也永不静默。
理解了 omb1.<claims>.<signature> 的结构、entitled("id") 的调用点、30 天预警与 7 天宽限的时间线,以及"删目录即 OSS"这条被 CI 守护的承诺,你就能在自己部署、二次分发或参与贡献时,准确判断每一步落在哪一层许可、需要做什么、以及出问题时先看哪个端点。