L Harness架构深度解析:Cloudflare Workers + D1 + Next.js单体仓库设计全解
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/ # 发布与测试脚本
这种分层带来三个直接好处:
- 依赖单向流动:
worker依赖db与line-sdk,而web只依赖shared类型——数据库访问逻辑被收敛在packages/db一个地方,Worker 侧不存在"裸写 SQL"散落各处的情况; - 一份 schema 多处消费:packages/db/schema.sql 定义了 63 张表,是部署 CLI 建库、迁移脚本和测试环境共用的唯一事实来源;
- 应用与库解耦发布:
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 监控 |
三个全局约定值得学习:
- ID 一律为应用层生成的 UUID(
crypto.randomUUID()),而非数据库自增——跨账号、跨部署数据迁移不会因自增 ID 冲突; - 时间戳统一 JST(UTC+9) 格式
YYYY-MM-DDTHH:mm:ss.sss+09:00,由packages/db/src/utils.ts的jstNow()统一生成,避免时区逻辑散落各处; - 查询函数即 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 消息预览、场景步骤编辑器)保留自研,是一个务实的组件取舍。
下图是管理后台"个别聊天"(运营者代客对话)界面改版前的布局,会话列表、聊天窗、好友详情三栏各自独立,视觉层次较平:
改版后去掉了冗余的卡片边框与页面大标题,改用更克制的分隔线和留白,三栏比例与信息密度也做了重新分配,长时间盯盘的视觉疲劳明显降低:
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 账号 |
延伸阅读
- 官方架构全景图:docs/wiki/Architecture.md
- 广播安全与隐身设计:docs/BROADCAST-SAFETY.md
- 管理后台认证详解:docs/ADMIN-AUTH.md
- Worker 缓存试点文档:docs/architecture/workers-cache-pilot.md
- 完整 Wiki(部署、API 参考、多账号、BAN 监控等):docs/wiki/
- 一键部署 CLI:packages/create-line-harness/
对 Cloudflare 生态感兴趣的读者,L Harness 的 worker + D1 + Pages 组合是一个可以直接参考的 Serverless 单体仓库模板:把业务逻辑放进 Hono 路由、数据访问封装进独立 db 包、定时任务写成幂等函数——这三步做完,你也就拥有了 90% 的架构骨架。

