Instatic：自带可视化编辑器的自托管 CMS，输出纯净 HTML/CSS

今天在 GitHub Trending 上看到一个有意思的项目：Instatic，一个自带可视化编辑器的自托管 CMS，最让人惊喜的是它输出的前端代码——没有 React、没有 Vue、没有编辑器运行时，只有干净的语义 HTML 和紧凑的 CSS。

一、项目概述

Instatic 的核心主张可以用一句话概括：Own your site. Love building it. 它是一个自托管的 CMS，但和传统的 Headless CMS + 前端框架的组合不同，Instatic 把可视化编辑器、内容引擎和发布器全部放在一个 Bun 服务器里，最终发布出来的页面是纯粹的静态 HTML/CSS 文件。

项目作者是 David Babinec，团队背后还有 Motion.page 和 Core Framework 两个产品的积累，在 WordPress 生态有较深的耕耘背景。

二、技术原理

架构设计

Instatic 的架构可以用三层来理解：

┌─────────────────────────────────────┐
│          React Admin (Vite)         │  ← 编辑器前端
├─────────────────────────────────────┤
│        Bun Server (HTTP)            │  ← 统一后端
│  - Auth / API / Publisher / Plugins │
├─────────────────────────────────────┤
│     SQLite / Postgres               │  ← 数据存储
└─────────────────────────────────────┘

关键点在于**发布器（Publisher）**的设计。Instatic 的发布流程分三层：

1. 静态页面：发布时直接 bake 成磁盘文件，原子替换，访问者拿到的是纯文件，不是动态渲染
2. 变化路由：放在内存缓存里，每次发布时整块失效，保证不出现脏数据
3. 真正每访客不同的部分：自动检测，用约 0.7kB 的懒加载运行时处理

这意味着最终实现的效果是：页面加载速度极快，因为几乎没有 JS 需要执行。

核心技术栈

插件沙箱机制

这是 Instatic 最有技术含量的部分之一。插件以 zip 包分发，在 QuickJS-WASM 沙箱中运行：

• 无文件系统访问：沙箱不暴露 fs
• 无环境变量：无法读取 host 敏感信息
• 网络默认关闭：插件想发请求，必须由站点所有者逐 host 授权
• SDK 能力丰富：插件可以添加 HTTP 路由、管理后台页面、存储、定时任务、Canvas 模块等

// 插件 manifest 示例（概念性）
{
  "name": "my-plugin",
  "permissions": {
    "network": ["api.example.com"],
    "storage": true
  }
}

这种设计和 VS Code 的 Extension Host 有相似之处，但安全边界更严格。

设计令牌引擎

Instatic 内置了 Core Framework 的设计令牌系统：

• 颜色令牌：定义一个品牌色，自动生成完整的色阶（tint/shade）
• 字体标尺：用数学比例生成流体排版尺度，随视口缩放
• 间距标尺：统一所有断点的节奏感
• 工具类生成器：生成锁定的一小份 framework.css，无冗余

这套系统使得整个设计系统以数据形式存在，修改一个令牌，所有引用它的页面同步更新。

三、安装与快速开始

环境要求

• Bun >= 1.3.0（唯一依赖）
• SQLite（默认，无需额外安装）或 Postgres

本地开发

git clone https://github.com/corebunch/instatic.git
cd instatic
bun install
bun run dev

打开 http://localhost:5173，首次访问会引导你创建站点和所有者账号。

生产构建

bun run start
# 构建 admin 并通过 Bun 服务器提供服务
# 访问 http://localhost:3001/admin

一键部署（推荐）

最快捷的方式是部署到 Railway（推荐），约两分钟即可上线，自动处理密钥生成、存储卷挂载和健康检查：

• SQLite 版本部署（适合单站点）
• Postgres 版本部署（适合多作者、需要托管备份的场景）

Docker 部署

INSTATIC_IMAGE=ghcr.io/corebunch/instatic:latest \
  docker compose -f compose.prod.yml -f compose.sqlite.yml up -d

四、使用方法与实战

可视化编辑

Instatic 的编辑器是真正的 Canvas，不是「表单 + 预览窗格」的组合。核心用法：

1. 多断点帧并列编辑：把桌面和移动帧并排，改桌面帧，移动帧实时响应
2. 实时模式：直接编辑完整尺寸页面
3. 设计令牌面板：修改颜色、字体、间距令牌，全局同步

组件系统

Visual Components 是可复用的带参数组件：

• 参数类型：string、number、boolean、color、image、URL、rich text、enum、content slot
• 修改组件定义，所有实例同步更新
• 循环引用在创建时就被阻止

AI 辅助编辑

Instatic 内置 AI Agent，能够通过 28 个工具在实际的 Canvas 上编辑页面：

• 描述需求，Agent 在 Canvas 上生成真实的、可编辑的节点
• 支持自带模型：Claude、OpenAI、OpenRouter、本地 Ollama
• API Key 由用户自己提供，账单自己承担

Loop 功能

Loop 是 Instatic 的内容渲染核心，可以对集合进行布局重复：

Loop(Posts) → Variant A / Variant B 交替 → 文章列表
Loop(Products) → Grid 布局 → 产品网格

五、常见问题与解决方案

Q1: Instatic 处于 0.0.x 版本，生产环境能用吗？

A: 官方明确说明这是 pre-1.0 软件，API 和工作流在 1.0 之前可能变化。如果是生产关键项目，建议等 1.0；如果是个人项目或想参与塑造产品方向，现在是好时机。

Q2: 输出真的是纯 HTML/CSS 吗？有没有隐藏的 JS？

A: 根据架构设计，公共页面确实没有框架运行时。唯一的 JS 是约 0.7kB 的懒加载运行时，用于处理真正需要每访客差异化的部分（如表单提交）。编辑器运行时不会出现在公共页面上。

Q3: 如何从现有静态站点迁移？

A: Instatic 提供 Super Import 功能：可以粘贴原始 HTML 转换为可编辑节点，也可以拖入整个静态站点（HTML + CSS + 图片 + 字体），导入过程有冲突预览，且整个导入操作支持单次撤销。

Q4: 插件安全吗？

A: 插件运行在 QuickJS-WASM 沙箱中，默认无文件访问、无环境变量访问、无网络访问。网络权限需要站点所有者逐 host 明确授权。从历史经验看，这种沙箱设计能有效防止「插件把数据库邮件给陌生人」的情况。

Q5: 备份策略是什么？

A: 备份数据库（SQLite 文件或 Postgres dump）+ 上传文件夹，就完成了整个站点的备份。文档提供了详细说明。

六、总结

Instatic 是一个很有想法的项目，它直面了现代 Web 开发的一个核心矛盾：我们为了让建站更简单，堆砌了多少不必要的复杂度？ 它的答案相当激进——一个 Bun 服务器搞定所有事情，输出尽可能简单的 HTML/CSS。

值得关注的亮点：

• 发布器设计保证了输出质量，不依赖开发者的自律
• 插件沙箱设计在自托管 CMS 中很少见，安全边界清晰
• Core Framework 的内置使得设计系统成为一等公民
• MIT 许可证，无 open-core 花招

需要注意的地方：

• 目前是 0.0.x 版本，API 可能变化
• 生态还在早期，模块和插件数量有限
• 分析功能（Analytics）还在路线图中，尚未实现

总体而言，如果你在寻找一个输出干净、自托管、可视化编辑的 CMS，并且不介意早期采用者的身份，Instatic 值得深入试用。

GitHub: CoreBunch/Instatic 官网: instatic.com