MallokMallok

Features0.1 包含什么

多语言企业官网需要的都有,其余的边界也讲清楚。

Mallok 是一套完整的 CMS——内容、主题、后台、CLI、询盘和 SEO——以一个 npm 包发布,以一个 Worker 运行。这一页列出它做什么、怎么做,以及有意不做什么。

01内容

标准 Markdown,原样存储。

内容是 CommonMark + GFM,外加一段 YAML front matter。D1 保存每个文件的完整文本;图片和附件用相对路径引用,文件存放在 R2。

  • 草稿、已发布、定时发布三种状态。
  • 页面和文章之外的内容类型由主题声明——B2B starter 自带产品、分类、案例、FAQ 和新闻。
  • 内容一律视为不可信:生成片段时按白名单净化 HTML,存储的 Markdown 原文不会被改动。
  • 导出得到的内容包,就是导入接受的格式。往返一致性有测试覆盖;完整恢复到第二个线上部署仍在验收清单上。
一个内容包导入 / 导出格式
titanium-price-2026-08/
├── index.md        # 默认语言
├── index.zh-CN.md  # 其他语言,写在文件名里
├── index.de.md
├── images/         # 各语言共用
│   ├── hero.jpg
│   └── chart.png
└── files/
    └── datasheet.pdf

02多语言

语言是内容的属性,不是插件。

每条内容都带语言和翻译组。主语言的 URL 不加前缀,其他语言各自有前缀。

  • sitemap 里的 hreflang 和 canonical 链接自动生成。
  • 一个内容包包含同一条内容的全部译文,并共用图片。
  • 主题的界面文字通过语言包跟随站点语言。
  • 0.1 提供内容模型、URL 规则和基础的翻译管理。机器翻译在路线图里,目前还没有。
/products/titanium-baren · 主语言,无前缀
/zh-CN/products/titanium-barzh-CN
/de/products/titanium-barde
sitemap.xml自动生成
<url>
  <loc>https://example.com/products/titanium-bar</loc>
  <xhtml:link rel="alternate" hreflang="en" href="…/products/titanium-bar"/>
  <xhtml:link rel="alternate" hreflang="zh-CN" href="…/zh-CN/products/titanium-bar"/>
  <xhtml:link rel="alternate" hreflang="de" href="…/de/products/titanium-bar"/>
</url>

sitemap 输出的简化示意。

03主题与插件

声明式主题,真正的插件,部署这件事都不含糊。

主题是一个目录:受限的 Liquid 模板加一份 theme.json。插件是真正的 JavaScript,有自己的数据表、路由、设置和定时任务。两者都放在项目源码里,构建时打包。

  • 主题里没有任意 JavaScript;需要的客户端脚本必须在 theme.json 里声明。
  • 切换主题不改内容 id,也不改公开 URL。新主题不认识的类型,会用它的页面布局渲染。
  • 官方插件和第三方插件走同一条路:源码进仓库,构建时打包。
  • 安装或更换主题、插件都需要构建并重新部署。部署之后,插件的启用开关、设置和密钥可以在后台即时修改。
  • 插件在你自己的账号里真实运行——信任边界和 WordPress 插件一样。请像审查其他上线代码那样审查它。
src/themes/atelier/theme.json节选
{
  "id": "atelier",
  "kinds": {
    "product": {
      "layout": "layouts/product.liquid",
      "listLayout": "layouts/list.liquid",
      "base": "products",
      "fields": {
        "grade": { "type": "string", "label": "Grade" },
        "specs": { "type": "keyvalue", "label": "Properties" },
        "gallery": { "type": "image[]", "label": "Gallery" },
        "datasheet": { "type": "file", "accept": [".pdf"] }
      }
    }
  },
  "clientScripts": [ /* 必须显式声明 */ ]
}

04询盘

一张表单,从产品页到收件箱。

官方询盘插件把产品目录变成获客渠道。在页面里写上 [[inquiry]],启用插件后表单就会出现。

  • Cloudflare Turnstile 防刷。
  • 通过 Resend 给你发信,可选自动回复买家。
  • 每条询盘都存进 D1,在后台像收件箱一样查看,可导出 CSV。
  • 第三方密钥以 AES-GCM 加密后才写入 D1,不会出现在内容或源码里。
  1. 买家提交表单[[inquiry]]
  2. Turnstile防刷校验
  3. 存入 D1
  4. Resend发给你,可选自动回复买家
  5. 后台收件箱CSV 导出

进行中: 当前候选版尚未完成真实 Turnstile 与 Resend 送达的端到端验收。正式依赖之前,请先用自己掌握的邮箱测试。

05后台

后台只展示你真正能改的东西。

React 单页后台,由同一个 Worker 提供,支持英文和简体中文。使用它的人不需要知道 Worker、D1 或缓存标签是什么。

  • Markdown 源码编辑器,配上按内容类型 schema 生成的字段表单。
  • 媒体库;上传时由浏览器转成 WebP 并生成多种宽度。
  • 安装向导:管理员、站点名称、语言、示例内容和域名。
  • 给 CLI 和内容流水线使用的分权限 API 令牌。
内容Markdown 编辑器 + 按类型 schema 生成的字段
媒体上传、WebP 多宽度、选择器
询盘像收件箱一样查看,可导出 CSV
设置站点、语言、导航、SEO、邮件、缓存
插件启用开关与设置,立即生效
主题、插件安装需要重新部署——界面会明说

06CLI

同一条数据通路,在终端里走。

CLI 调用的是后台同一套管理 API,所以 CI 里发布的目录和浏览器里保存的文章,存储、渲染和清缓存的方式完全一样。

命令作用
mallok create <dir>创建项目、校验,然后部署到你的 Cloudflare 账号。加 --no-deploy 则不创建任何云资源。
mallok publish <dir>发布一个或多个内容包,连同图片。
mallok import <dir>导入内容包,状态以 front matter 为准。
mallok export <dir>把整个站点导出为内容包目录。
mallok build <dir>把本地目录编译成静态网站,不碰 D1,也不联网。
mallok upgrade --to <version>把项目切换到另一个 Mallok 版本,重新部署后生效。
mallok preview <dir>在本地离线渲染内容包。

此外还有 media push、setup-key、repair、destroy。站点类命令都支持 --dry-run 和 --json。详见 CLI 参考(英文)。

07渲染与缓存

两个阶段,三层缓存,一个确定性的渲染核心。

渲染核心不依赖任何平台 API,所以 CLI 的本地预览、后台的实时预览和线上的 Worker 跑的是同一个函数,输出同样的字节。

第一阶段 · 保存时 Markdown+ YAML front matter解析 + 净化remark / rehype,白名单解析媒体路径images/ → R2 地址、srcsetHTML 片段D1 render_cache(派生数据) 第二阶段 · 请求时(缓存未命中) 片段 + 数据有界的 D1 批量查询Liquid 主题模板随 Worker 打包完整页面Cache-Control + Cache-Tag边缘缓存cache.put(),按标签清除 相同的 Markdown + 管线版本 + 主题版本 → 逐字节一致的 HTML。渲染核心不读取时钟、随机数或请求数据。
层位置键解决什么
边缘缓存Cache API请求 URL访客请求不会走到渲染
片段缓存D1 render_cacheMarkdown 哈希 + 管线版本 + 插件哈希冷渲染不解析 Markdown
模板缓存isolate 模块作用域主题 id + 版本同一个 isolate 里 Liquid 只解析一次

有界的冷渲染

无论站点有多少内容,一次冷渲染最多 4 次 D1 往返。列表页从不解析正文 Markdown,也不会逐条查询。

按标签清除

每个页面都带站点、内容、类型和语言的 Cache-Tag。保存时只清除展示了该内容的页面。在 main 分支上,清除失败会被记录并显示在后台;已发布的候选版(到 rc.11)可能把失败的清除显示为成功。

边缘缓存长存,浏览器每次校验

页面默认在边缘缓存一小时(可调),同时要求浏览器每次重新校验,这样清除缓存不会被访客浏览器里的旧副本抵消。

rc.5 单次部署的实测数据

缓存命中 · CPU
0 ms p50 / p95

30 次确认命中里最大值为 1 ms。0 是平台记录的数值,并不表示没有任何计算。

冷渲染 · CPU,30 次确认未命中

免费套餐目标:10 ms。30 次冷渲染里有 16 次超出,全部请求成功。

移动端 Lighthouse
95–97 性能

首页与文章页共六次测试,无障碍、最佳实践和 SEO 均为 100。

请按实际含义看待这些数字。 它们来自 0.1.0-rc.5 在自定义域名上的一次隔离部署。rc.6 到 rc.11 没有重新采样,而且这些版本给冷渲染增加了开销,所以这些数字不能代表当前候选版。冷渲染超过 10 ms CPU 是候选版已知并已接受的限制。 完整发布状态

08SEO

结构化输出,内置在核心里。

搜索相关的输出不交给插件,也不交给各个主题作者。每个 Mallok 站点的输出都是同一套。

  • 带 hreflang 的 sitemap、RSS、canonical 链接和 Open Graph 标签。
  • Organization、Article、Product、FAQ 四类 JSON-LD。
  • 修改 slug 会自动写入 301 跳转。
  • 内容页是语义化 HTML,主题不输出 JavaScript。你在 Cloudflare 启用的功能(如统计分析)仍可能注入它自己的脚本。
  • sitemap.xml + hreflang
  • RSS
  • rel=canonical
  • Open Graph
  • JSON-LD · Organization
  • JSON-LD · Article
  • JSON-LD · Product
  • JSON-LD · FAQ
  • 改 slug 自动 301
  • 带签名的草稿预览链接

有意不做:自动识别语言并跳转。访客和爬虫请求哪个 URL,就得到哪个 URL。

09静态构建

更想要纯静态文件?还有第二条路。

mallok build 把本地目录(与 mallok export 的导出结构相同)编译成完整的静态站点:内容类型、标签、多语言和 SEO 端点,用的是同一套渲染函数。

  • 不碰 D1,也不联网。
  • 失效的引用会报错,而不是悄悄丢掉。
  • 它是 Worker 之外的另一条路,不是替代品:右边列出的就是代价。
终端不用 D1 的那条路
mallok build ./my-site \
  --theme ./src/themes/atelier \
  --origin https://example.com
询盘表单不可用——构建时移除并提示
后台编辑不可用
即时发布与定时发布改为重新构建并部署

10边界

哪些立即生效,哪些需要重新部署。

这是产品里最重要的一条线,所以不只写在这里,界面上也画得清清楚楚。

立即生效

内容时间线

  1. 保存
  2. 写入 D1
  3. 按标签清缓存
  4. 上线
构建并重新部署

框架时间线

  1. 改源码
  2. 构建
  3. 部署
  4. 上线

由日常运营网站的人在后台或通过 CLI 修改。不需要构建,也不需要部署。

  • 页面、文章、产品、媒体内容
  • 站点名称、语言、导航、SEO 默认值设置
  • 主题开放的选项主题选项
  • 插件的启用开关、设置与密钥插件设置

由技术人员在源码里修改,随代码一起发布,部署后才生效——不会伪装成一键切换。

  • 切换或修改主题主题
  • 安装或更新插件插件
  • 升级 Mallok 版本mallok upgrade
  • 切换主题不迁移内容,也不改变任何 URL保证

11不做什么

0.1 有意不做的事。

知道一个工具的边界在哪里,才谈得上信任它。

不是托管服务

没有 Mallok 账号、计费或多租户控制台。你的网站只运行在你自己的 Cloudflare 账号里。

暂时不是商城

0.1 做到询盘为止:没有购物车、支付、会员和评论。电商是后续方向,以插件形式提供。

不是兼容层

不运行 PHP,不兼容 WordPress 主题和插件,也不运行 Astro 或 Next.js 项目。WordPress 导入工具在路线图里。

不适合写业务应用

需要自由编写服务端业务逻辑、权限体系或复杂表单流程的站点,并不适合用它。

没有协同编辑

0.1 没有实时多人协作编辑。

不是多云

只依赖一家云厂商和一家邮件服务商,我们直说而不掩饰。对策是内容和询盘随时可以导出。

12路线图

是方向,不是承诺。

下面这些都不在当前候选版里,也都没有排期。

  1. 0.2

    • 可视化编辑器
    • 从 CSV 批量导入产品
    • AI 翻译插件
    • 询盘车:多个产品合并成一份询价
    • WordPress 导入工具
  2. 0.3

    • 通过第三方托管的收银页面,支付样品和小额订单
  3. 1.0

    • 面向非技术用户的托管安装助手
    • 主题、starter 和插件市场

来源:产品愿景(英文)第 9 节。“Deploy to Cloudflare” 按钮也在计划中,目前尚不可用。

一条命令,部署到你自己的账号。

Mallok 会在你自己的 Cloudflare 账号里创建 Worker、D1 数据库和 R2 存储桶,并把网站部署上去。Mallok 不托管任何东西,也不需要注册 Mallok 账号。

npx mallok create my-site

需要 Node.js 22 及以上,并先执行 wrangler login。加上 --no-deploy 只在本地生成并检查项目,不创建云资源。当前为 0.1 候选版。