🚀 Directus：不用写后端了？一个把数据库直接变成 API + 后台的神器

Directus 是一款开源 Headless CMS 数据平台，连接任意 SQL 数据库即可自动生成 REST + GraphQL API，附赠可视化管理后台、实时订阅、Flows 自动化与原生 MCP Server。BSUL 1.1 协议下完全免费自托管，Docker 一行命令即可启动。

🎤 引言

手头有个老项目，数据库里塞了七八年的 MySQL 数据，想给它套一个现代化的可视化管理后台，让非技术同事也能直接增删改查，又不想把数据搬出来重新折腾。

这种"我的数据、我的 API、但我想直接有个面板"的诉求，在过去通常只有两条路：要么用 Strapi 这种"自带数据库"的 CMS 把现有数据迁过去，要么干脆自己用 Retool 低代码平台搭一个。直到翻到 directus/directus 这个 36.3k Star 的仓库——它做的事情说穿了很简单：连接任意 SQL 数据库，自动反射出完整的 REST + GraphQL API，再送你一个开箱即用的管理后台（官方叫 Studio）。

更意外的是 v12 直接内置了 MCP Server，可以直接被 Claude、Cursor 这类 AI 编程工具通过 MCP 协议读写数据，相当于给 AI 配了一个"会查数据库"的后端。

---

⭐ 核心功能

1. 数据库反射（Database Reflection）

这是 Directus 最核心的设计哲学——它不拥有你的数据库。你可以把任意已有的 PostgreSQL、MySQL、SQLite、MSSQL、Oracle、CockroachDB、MariaDB 接进来，Directus 会自动读取表结构，在 Studio 里渲染出对应的"集合（Collections）"和"字段（Fields）"。

数据结构改了？直接 ALTER TABLE 就行，Directus 会跟着变。这意味着：

• 不会因为换 CMS 把旧数据迁移一遍
• ORM/迁移工具照常用，Directus 只是挂在前面
• 多套应用共享同一个数据库也能用同一个后台管理

2. 自动生成 REST + GraphQL API

每个 Collection 都会自动获得完整的 CRUD API（支持过滤、排序、分页、聚合、搜索、全文检索），同时附带 GraphQL 端点，不需要写一行 Schema：

# 获取所有文章，支持过滤、字段选择、分页
curl http://localhost:8055/items/articles \
  -H "Authorization: Bearer <access_token>" \
  -G \
  --data-urlencode "filter[status][_eq]=published" \
  --data-urlencode "fields=id,title,published_date,author.name" \
  --data-urlencode "limit=20"

3. Studio 管理后台

一个完整的 no-code 数据管理界面，支持：自定义布局、暗色/亮色主题、白标（替换 Logo/字体/主题色）、字段级权限、数字资产管理（上传 + 按需生成任意尺寸缩略图、CDN 就绪）、可视化 Insights 仪表盘、Realtime 协作（同一行多人编辑时实时同步光标位置）。

4. Realtime & WebSockets

订阅任意 Collection 就能拿到数据变更事件，配合前端框架可以做出实时仪表盘、协作工具、即时聊天后端等场景：

import { Directus } from '@directus/sdk';
const client = new Directus('https://api.example.com');

const { subscription } = client.subscribe('messages', {
  event: 'create',
  query: { fields: ['*', 'user.*'] }
});

for await (const message of subscription) {
  console.log('New message:', message);
}

5. Flows 自动化

后台可视化编排 if-this-then-that 工作流，类似 n8n 但与数据深度集成，可以监听某个 Collection 变更后触发 HTTP 请求、发邮件、写日志、调用 Webhook 等。

6. 原生 MCP Server（v12 新增）

这是 v12 最大的亮点。Directus 直接暴露一个 MCP 端点，Claude Desktop、Cursor、Continue.dev 等 AI 编程工具可以以 MCP 协议读取/写入你的数据，AI 真正"看得见"你的业务表结构。

7. 细粒度权限

角色 → 策略 → 字段/行级过滤，支持最多 4 层嵌套权限继承，能精确到"销售只能看自己的客户、不能看客户手机号"这种程度。

---

📥 安装与使用

最简单的方式（仅供体验，停止容器后数据丢失）：

docker run -p 8055:8055 directus/directus

浏览器访问 http://localhost:8055 就能看到引导页，跟着创建第一个管理员账号。

推荐方式：Docker Compose + SQLite（生产可用）

新建一个目录 directus，里面再建 database、uploads、extensions 三个子目录，然后写 docker-compose.yml：

services:
  directus:
    image: directus/directus:12.0.2
    ports:
      - 8055:8055
    volumes:
      - ./database:/directus/database
      - ./uploads:/directus/uploads
      - ./extensions:/directus/extensions
    environment:
      SECRET: "replace-with-random-value"
      DB_CLIENT: "sqlite3"
      DB_FILENAME: "/directus/database/data.db"
      WEBSOCKETS_ENABLED: "true"
      PUBLIC_URL: "http://localhost:8055"
      LICENSE_KEY: ""

启动：

docker compose up -d

接入已有 PostgreSQL 数据库：

services:
  directus:
    image: directus/directus:12.0.2
    ports:
      - 8055:8055
    volumes:
      - ./uploads:/directus/uploads
      - ./extensions:/directus/extensions
    environment:
      SECRET: "your-random-secret"
      DB_CLIENT: "pg"
      DB_HOST: "postgres"
      DB_PORT: 5432
      DB_DATABASE: "mydb"
      DB_USER: "directus"
      DB_PASSWORD: "directus"
      WEBSOCKETS_ENABLED: "true"
      PUBLIC_URL: "http://localhost:8055"

启动后 Directus 会自动读取所有已有表，不需要任何迁移操作。

JS / TS SDK：

npm install @directus/sdk

官方仓库和完整文档：GitHub - directus/directus · 官方文档 · Docker 安装指南

---

🎯 适用场景

• 老项目改造：已有数据库，想加可视化管理面板，不想迁移数据
• 内部工具：业务团队需要一个录入/查询后台，开发团队不想每次都手写 CRUD
• AI Agent 后端：通过 MCP Server 让 AI 编程工具直接读写业务数据
• 中型内容站：博客、产品手册、文档站——需要后台但又不想用 WordPress
• 多端数据中台：Web、iOS、Android、小程序共用同一份数据 + 后台

不太适合：纯静态站点（Ghost/Astro 这种更轻）、需要复杂权限继承的企业级 ERP（建议走商业版 Directus Enterprise）。

---

🔍 对比/替代方案

工具	数据库所有权	API 自动生成	学习曲线	适合场景
Directus	你的数据库	✅ REST + GraphQL + MCP	中	已有数据 + 可视化后台
Strapi	Strapi 自管	✅ REST + GraphQL	中	新项目 + 完整生态
Payload CMS	Payload 自管（可挂外部）	✅ REST + GraphQL + Local API	高	TypeScript 重度用户
Retool	外部	❌ 需手动写	低	内部工具（闭源、SaaS 为主）
n8n + Database 节点	外部	❌ 无可视化管理界面	中	自动化为主、UI 为辅

直接对比 Strapi：Strapi 会自己管理 schema，你的数据在 Strapi 创建的表里；Directus 相反，它"映射"你已有的表。这是设计哲学的根本分歧——要看你更在意"内容与代码同源"还是"数据绝对独立"。

---

⚠️ 注意事项

1. 许可证（必须知道）

Directus 使用 BSUL 1.1（Business Source License），这是 MariaDB 同款"源代码开放 + 延迟开源"模式：

• ✅ 自托管、内部使用、个人项目、教育用途：完全免费
• ✅ 年营收低于 500 万美元的组织：免费
• ❌ 年营收 500 万美元以上的组织提供商业 SaaS：需要商业许可证
• 每次发布后 4 年转为 Apache 2.0

简单说：个人/小团队随便用，做大后要么开源你 fork 的版本要么买 license。

2. 性能边界

虽然 Directus 性能不差（官方基准能扛住百万级行），但它是 Node.js 单进程，没有内置集群模式。单实例扛不住的话需要靠负载均衡 + 多副本 + Redis session 共享自己做。

3. 中文文档

官方文档为英文，社区翻译质量参差不齐，遇到问题建议直接看 GitHub Issues 或 Discord。

4. MCP Server 需要 v12

如果你想用 MCP 给 AI 暴露数据能力，必须升级到 v12，旧版本没有这个能力。

5. Extensions 系统

Hooks、Endpoints、Interfaces、Modules、Panels、Theming 都是基于自定义 Extensions 扩展的，写起来不复杂，但和"直接改源码"是两回事，建议从官方 marketplace 起步。

---

✅ 总结

Directus 适合"已经有数据库、需要一个管理后台和 API"的场景。它最大的不同是不抢你的数据——你可以把它当成"挂在前面的可视化层 + API 网关 + MCP 桥"，底下的数据库该怎么用还是怎么用。

推荐指数：⭐⭐⭐⭐（4/5）

优点：数据库反射设计哲学极其实用、API + Studio + Realtime + MCP 一站式、SQL 数据库全谱系支持、白标能力强
缺点：BSUL 协议对大企业有合规疑问、单实例性能需自行扩展、中文社区资源相对少

适合：开发者、独立团队、中型内容站、有 AI 集成需求的项目
不适合：纯静态站、需要完整 ERP 权限的企业、需要零代码搭建的纯非技术用户