L Harness架构深度解析:Cloudflare Workers + D1 + Next.js单体仓库设计全解

原创2026-11-16 17:57:381,869 阅读

L Harness架构深度解析:Cloudflare Workers + D1 + Next.js单体仓库设计全解

L Harness 是一款完全开源的 LINE 官方账号 CRM 系统,核心架构采用 Cloudflare Workers 承载全部 API 与 Webhook、D1(SQLite)作为数据库、Next.js 构建管理后台,三者通过 pnpm workspace 组织在同一个单体仓库(monorepo)中,配合 TypeScript SDK 与 MCP Server 形成完整的营销自动化生态。本文带你从全局到细节,完整拆解这套架构的设计思路与落地细节。

一、架构选型:为什么是 Cloudflare Workers + D1?

L Harness 要解决的核心问题是:以零软件费用替代 L社、U社等商业 LINE 营销工具,同时保持功能完整(步骤消息、分群广播、表单、预约、评分、IF-THEN 自动化)。这决定了它对基础设施的三个硬性要求:

选型诉求 对应方案
全球低延迟接收 LINE Webhook Cloudflare Workers(边缘运行时)
免运维的关系型数据库 D1(边缘 SQLite,Serverless)
静态资源与 SPA 托管 Workers Assets / CF Pages
定时任务(步骤消息、广播) Cron Trigger + Durable Objects
文件存储(图片上传) R2 对象存储

整套系统没有传统意义上的服务器:一个 Worker 进程同时承担 API 网关、Webhook 处理器、定时任务执行器和静态站点服务器四个角色。这也是它对个人开发者友好的关键——Cloudflare 免费额度即可运行,npx create-line-harness 一条命令完成全部部署(约 5 分钟)。

📌 官方架构图与完整说明见 docs/wiki/Architecture.md

二、单体仓库全景:pnpm workspace 的组织方式

仓库根目录通过 pnpm-workspace.yaml 声明了两个通配分组 apps/* 和 packages/*,形成经典的"应用 + 共享包"分层:

line-harness-oss/
├── apps/
│   ├── worker/          # 核心:Cloudflare Workers(API + Webhook + 定时任务)
│   ├── web/             # Next.js 15 管理后台(部署到 CF Pages)
│   └── liff/            # Vite + React 的 LINE 内嵌应用(表单/预约)
├── packages/
│   ├── db/              # D1 表结构 + 全部数据库查询函数
│   ├── line-sdk/        # LINE Messaging API 类型化封装
│   ├── sdk/             # 对外发布的 @line-harness/sdk 客户端
│   ├── shared/          # 前后端共享类型
│   ├── mcp-server/      # MCP Server(AI Agent 操作入口)
│   ├── update-engine/   # 自更新引擎(Worker 云端 + CLI 共用)
│   └── create-line-harness/  # 一键部署 CLI
└── scripts/             # 发布与测试脚本

这种分层带来三个直接好处:

  1. 依赖单向流动:worker 依赖 db 与 line-sdk,而 web 只依赖 shared 类型——数据库访问逻辑被收敛在 packages/db 一个地方,Worker 侧不存在"裸写 SQL"散落各处的情况;
  2. 一份 schema 多处消费:packages/db/schema.sql 定义了 63 张表,是部署 CLI 建库、迁移脚本和测试环境共用的唯一事实来源;
  3. 应用与库解耦发布:sdk、mcp-server、update-engine 都是独立的 npm 包,第三方可以只安装 SDK 而不部署整个系统。

三、apps/worker:一个 Worker 撑起全部后端

3.1 路由与中间件:Hono 搭起 API 网关

Worker 入口 apps/worker/src/index.ts 使用轻量框架 Hono 构建应用。中间件按固定顺序生效,体现了典型的安全纵深设计:

defaultCachePolicyMiddleware  →  CORS(来源白名单反射)  →  rateLimitMiddleware  →  authMiddleware
  • 缓存策略:所有响应默认 no-store,仅显式声明公开 Cache-Control 的路由可进缓存,防止用户数据被边缘缓存泄漏(详见 docs/architecture/workers-cache-pilot.md);
  • CORS:凭据式 Cookie 认证不允许通配符来源,仅反射同源与 ADMIN_ORIGIN 白名单,SDK/CLI 这类不带 Origin 头的调用方不受影响;
  • 认证中间件:apps/worker/src/middleware/auth.ts 对 /api/* 强制 Authorization: Bearer {API_KEY},同时豁免 Webhook、表单提交、追踪链接重定向等公开路径。

路由层挂载了 50+ 个路由组,按领域划分(friends、scenarios、broadcasts、booking、webinars……),每个路由文件都是单一职责的 Hono sub-router,源码位于 apps/worker/src/routes/。

3.2 双保险定时任务:Cron Trigger + Durable Objects

步骤消息、定时广播、提醒、账号健康巡检都依赖 scheduled() 定时入口(apps/worker/src/scheduled.ts)。设计上有一个值得注意的细节:

  • Cron Trigger(apps/worker/wrangler.toml 中配置 * * * * * 与 0 */6 * * *)是平台侧配置,理论上存在"部署成功但触发器从未发火"这种静默故障;
  • 因此项目额外实现了一个 Durable Object —— TenantScheduler,它每 60 秒给自己重新设置 alarm,即使某次 tick 失败也能自我修复调度链;
  • 两者同时触发并不可怕,因为所有任务都采用乐观锁"领取"模式(UPDATE ... WHERE status = 'scheduled'),双触发天然幂等。

这是一个很实用的生产经验:定时任务不要只依赖单一触发源,且任务本体必须幂等。

3.3 静态资源与 OGP:run_worker_first 的巧思

wrangler.toml 中 run_worker_first = true 配置让静态资源请求也先经过 Worker 逻辑再落盘。这样当 LINE / X / Facebook 的链接预览爬虫抓取分享链接时,Worker 能识别爬虫 UA 并动态生成 OGP 卡片 HTML(lib/og-bot.ts、lib/og-html.ts),让预约页和表单页在聊天软件里展示精美的预览卡片——这是纯静态托管做不到的能力。

四、D1 数据库设计:63 张表的领域划分

数据库 schema 由 packages/db/schema.sql 统一定义,并配套 packages/db/migrations/ 下 70+ 个按序号命名的迁移文件,保证存量部署可以平滑升级。核心表的领域划分如下:

领域 代表表 作用
好友与标签 friends / tags / friend_tags LINE 友达资料、多对多标签关系
场景与广播 scenarios / scenario_steps / friend_scenarios / broadcasts 步骤消息定义、每人的推进进度、群发状态机
自动化 automations / scoring_rules / auto_replies IF-THEN 规则、线索评分、自动回复
转化与归因 conversion_points / tracked_links / entry_routes / affiliate_clicks CV 记录、链接追踪、入口路由
预约体系 calendar_bookings / webinars / event_bookings Google Calendar 预约、网络研讨会
多账号 line_accounts / traffic_pools / account_health_logs 多 LINE 账号池、流量分配、BAN 监控

三个全局约定值得学习:

  1. ID 一律为应用层生成的 UUID(crypto.randomUUID()),而非数据库自增——跨账号、跨部署数据迁移不会因自增 ID 冲突;
  2. 时间戳统一 JST(UTC+9) 格式 YYYY-MM-DDTHH:mm:ss.sss+09:00,由 packages/db/src/utils.ts 的 jstNow() 统一生成,避免时区逻辑散落各处;
  3. 查询函数即 API 边界:packages/db/src/ 下每个领域一个文件(friends.ts、broadcasts.ts……),Worker 路由只调用这些函数,测试时可用 better-sqlite3 直接跑真实 SQL,不需要 mock。

五、数据流:从一条 Webhook 到自动消息的完整链路

这是整个系统的心脏,也是理解 L Harness 架构的最佳路径。

① 接收:LINE 平台向 POST /webhook 推送事件,packages/line-sdk/src/webhook.ts 用 HMAC-SHA256 校验 X-Line-Signature 签名。注意签名失败也返回 200(LINE 规范要求),随后用 waitUntil 立即响应、异步处理——因为 LINE 要求 1 秒内应答。

② 处理(以用户添加好友为例):

follow 事件
 ├─ 拉取好友 Profile → upsert 到 friends 表
 ├─ 匹配 friend_add 场景 → 注册到 friend_scenarios(delay=0 则立即推送)
 └─ fireEvent('friend_add') 事件总线
     ├─ 外发 Webhook(HMAC 签名)
     ├─ 评分规则引擎(scoring_rules)
     ├─ IF-THEN 自动化(加标签/发场景/切菜单)
     └─ 通知规则(生成站内通知)

③ 投递:5 分钟一次的 scheduled() 扫描 friend_scenarios 中到期记录,执行条件判断(标签存在/元数据相等)、构建消息、调用 pushMessage,然后推进 next_delivery_at。投递还内置"隐身"策略——±5 分钟随机抖动、每 500 条一批的批间延迟、零宽字符消息变体、自主限速 1000 次/分钟——让群发行为与正常运营难以区分,相关安全设计见 docs/BROADCAST-SAFETY.md。

④ 认证体系采用三通道隔离,各场景互不越权:

通道 使用方 验证方式
API Key(Bearer) 管理后台 / SDK / curl Authorization: Bearer {API_KEY}
LINE Signature Webhook X-Line-Signature(HMAC-SHA256)
LIFF ID Token LINE 内嵌应用 /api/liff/* 路由内验证

管理后台还支持管理员 Cookie 会话与外部 SSO 集成,细节可参考 docs/ADMIN-AUTH.md。

六、前端双端:Next.js 管理后台与 LIFF 应用

6.1 apps/web:Next.js 15 管理后台

管理后台采用 Next.js 15 App Router(apps/web/src/app/),页面按领域目录组织(/scenarios、/broadcasts、/booking 等),前端通过 Bearer Token 调用 Worker API。UI 层正在从 Tailwind 迁移到 Cloudflare 官方的 Kumo 设计系统(@cloudflare/kumo),迁移策略记录在 docs/ui/kumo-migration.md——通用控件用 Kumo,产品特化组件(Rich Menu 画布、Flex 消息预览、场景步骤编辑器)保留自研,是一个务实的组件取舍。

下图是管理后台"个别聊天"(运营者代客对话)界面改版前的布局,会话列表、聊天窗、好友详情三栏各自独立,视觉层次较平:

改版前的 L Harness 管理后台个别聊天界面:三栏式布局,展示会话列表与好友标签信息

改版后去掉了冗余的卡片边框与页面大标题,改用更克制的分隔线和留白,三栏比例与信息密度也做了重新分配,长时间盯盘的视觉疲劳明显降低:

改版后的 L Harness 管理后台个别聊天界面:更简洁的分栏布局,突出消息流与好友详情

6.2 apps/liff:跑在 LINE 里的前端

apps/liff 是独立的 Vite + React 应用,通过 LIFF 框架运行在 LINE 客户端内部,承载表单填写、沙龙预约、活动报名、Webinar 注册等用户侧流程(页面含 Booking.tsx、Event.tsx、Webinar.tsx 等)。它与管理后台共用同一套 API,但走 LIFF ID Token 认证通道,无需 API Key。

一个值得注意的部署细节:三个前端面(Worker 自身的 SPA、管理后台、LIFF 应用)最终可以打进同一个 ASSETS 绑定按路径前缀分发(见 index.ts 的 SPA fallback 注释),配合 run_worker_first 实现"一个域名同时服务三端"的极简部署形态。

七、生态扩展:SDK、MCP Server 与自更新引擎

单体仓库中还有三个让 L Harness 区别于普通开源项目的"外延层":

  • TypeScript SDK(packages/sdk/):LineHarness 主类封装了全部 REST API,内置 parseDelay("30m" | "1h")、统一错误类型与高层工作流(workflows.ts),让集成方用几行代码驱动整个 CRM;
  • MCP Server(packages/mcp-server/):提供 30+ 个 MCP 工具,使 Claude Code 等 AI Agent 能够直接操作 LINE 账号——查好友、建场景、发广播、改标签,"用自然语言运营 LINE 账号"是该项目最有辨识度的卖点;
  • 自更新引擎(packages/update-engine/):Worker 云端(/admin/update/*)与本地 CLI(npx create-line-harness update)共用同一套更新逻辑——拉取 release manifest、校验哈希、执行迁移、重新部署,保证云端与本地两条升级路径行为一致。

插件机制(docs/plugins/README.md)则允许把自定义规则拆到独立 Worker 仓库,通过 SDK 与本体通信,避免本体更新覆盖用户代码。

八、架构亮点小结

设计点 方案 解决的问题
单一后端进程 Workers + Hono 承载 API/Webhook/Cron/静态 零服务器运维,免费额度可跑
数据访问收敛 packages/db 统一管理 63 张表 无裸 SQL 散落,测试可跑真实 SQL
定时任务双触发 Cron + Durable Object alarm + 幂等领取 静默失效故障 + tick 失败自愈
三通道认证 Bearer / LINE 签名 / LIFF Token 隔离 管理端、平台端、用户端互不越权
安全纵深 默认 no-store + CORS 白名单 + 全局限速 边缘缓存不泄漏用户数据
一份代码多端复用 update-engine 同时服务 Worker 与 CLI 云端/本地升级行为一致
AI 原生 内置 MCP Server + 全功能开放 API AI Agent 直接运营 LINE 账号

延伸阅读

对 Cloudflare 生态感兴趣的读者,L Harness 的 worker + D1 + Pages 组合是一个可以直接参考的 Serverless 单体仓库模板:把业务逻辑放进 Hono 路由、数据访问封装进独立 db 包、定时任务写成幂等函数——这三步做完,你也就拥有了 90% 的架构骨架。

登录后查看全文
line-harness-oss