Directus：开源无头 CMS 与数据库可视化平台部署与使用指南

一、项目官方信息

Directus 是面向开发者与 AI 的“协作式后端”（The Collaborative Backend for Builders & AI）。官方 README 的定位是：连上任意 SQL 数据库，立刻获得 REST 与 GraphQL API、可视化管理 Studio，以及一个供 AI agent 使用的原生 MCP 服务器。

它的核心思路是：工程师掌控数据库 schema 与访问权限，非技术同事和 AI 则可以直接在可视化界面里操作真实数据，无需提单、无需样板代码。主要能力包括：

• 从数据库 schema 自动生成 REST & GraphQL API，零配置；
• 完整的可视化 Studio 管理后台；
• 内嵌 AI 助手与原生 MCP Server（可对接 Claude、Cursor、ChatGPT 等）；
• 基于策略的细粒度访问控制，权限可下放到字段级，人和 AI 用同一套权限；
• 自带数据库支持：Postgres、MySQL、MariaDB、MS SQL、SQLite、OracleDB、CockroachDB 等；
• 高度可扩展：自定义端点、hooks、interfaces、modules；
• 可自托管或使用 Directus Cloud。

二、官方图片

上图为 Directus 仓库在 GitHub 上的社交预览图。部署完成后，Studio 是一个纯 Web 后台：左侧为数据模型与内容集合，右侧为记录表格与字段编辑，对应自动生成的 API 直接可调用。

三、环境要求

• Node.js 18 LTS 及以上（用于 npx 方式）；或 Docker / Docker Compose（推荐生产）。
• 一个受支持的 SQL 数据库：PostgreSQL（官方推荐）、MySQL/MariaDB、SQL Server、SQLite 等。
• 推荐搭配 Redis（缓存与队列）。
• 默认端口 8055。
• 资源：内存 1GB 以上；生产建议 2GB+ 并外接独立数据库。

四、完整部署步骤

方式 A：npx 快速初始化（推荐入门）

Directus 提供官方脚手架，交互式生成配置并启动：

npx directus init

按提示选择数据库、填写连接信息、设置管理员账号后，脚手架会生成 .env 并安装依赖。完成后启动：

npx directus start

方式 B：Docker 生产部署

新建目录 docker-compose.yml：

services:
  database:
    image: postgres:16
    container_name: directus-db
    restart: unless-stopped
    environment:
      POSTGRES_USER: directus
      POSTGRES_PASSWORD: 请改成强密码
      POSTGRES_DB: directus
    volumes:
      - pgdata:/var/lib/postgresql/data

  cache:
    image: redis:7
    container_name: directus-redis
    restart: unless-stopped

  directus:
    image: directus/directus:latest
    container_name: directus
    restart: unless-stopped
    ports:
      - "8055:8055"
    environment:
      KEY: 请替换为随机长串
      SECRET: 请替换为另一个随机长串
      ADMIN_EMAIL: admin@example.com
      ADMIN_PASSWORD: 请改成强密码
      DB_CLIENT: pg
      DB_HOST: database
      DB_PORT: 5432
      DB_DATABASE: directus
      DB_USER: directus
      DB_PASSWORD: 请改成强密码
      CACHE_STORE: redis
      REDIS: redis://cache:6379
    depends_on:
      - database
      - cache
    volumes:
      - uploads:/directus/uploads

volumes:
  pgdata:
  uploads:

启动：

docker compose up -d
docker compose logs -f directus

说明：KEY 与 SECRET 必须是随机长串（可用 openssl rand -hex 32 生成），用于签名与加密；ADMIN_EMAIL / ADMIN_PASSWORD 是首次启动创建的超级管理员。

验证

浏览器打开 http://服务器IP:8055，用 ADMIN_EMAIL / ADMIN_PASSWORD 登录，看到 Directus Studio 后台即部署成功。

五、使用方法

• 建数据模型（Collections）：在 Studio 的「Data Model Model」里新建集合（相当于一张表），再为其添加字段（文本、数字、单选、图片、关联等）。保存后 Directus 会在数据库里自动建表，并自动生成对应的 REST/GraphQL 接口。
• 录入与管理内容：在「Content」里以表格形式浏览、筛选、新增、编辑记录，类似一个带权限的在线表格。
• 调用 API：直接用生成的 REST 接口，例如 GET /items/集合名?access_token=...，或在 GraphQL 里查询同一批数据。
• 权限控制：设置 Roles（角色）与 Permissions，对每个集合的增删改查、乃至字段级权限做精细控制；AI agent 也复用同一套角色权限。
• 文件与媒体：上传的文件存放在 uploads（或配置 S3 等外部存储），可在字段中引用。
• AI 与 MCP：在 Studio 中开启 AI 助手，并通过内置 MCP Server 把数据连接给支持 MCP 的工具。
• 扩展：可安装/开发自定义端点、hooks、界面（interfaces）与模块（modules），按需扩展。

六、常见问题 FAQ

1. Directus 是传统 CMS 吗？需要先有数据库吗？ 它是无头 CMS / 数据后端。官方理念是“连接你已有的 SQL 数据库”——你可以让它连一个空库，它通过建集合帮你生成 schema；也可以连一个已有库，它会自动映射出对应的 API。

2. 默认端口是多少？登录不了？ 默认 8055。确认容器/进程已启动（docker compose ps 或日志），防火墙放行 8055；首次登录用 .env 里的 ADMIN_EMAIL / ADMIN_PASSWORD。

3. KEY 和 SECRET 是干什么的？ 用于签名 Token、加密敏感配置。必须设为随机长串，且生产环境不要泄露；泄露后需更换并让旧会话失效。

4. 支持哪些数据库？ README 列出 Postgres、MySQL、MariaDB、MS SQL、SQLite、OracleDB、CockroachDB 等。Docker 示例用 PostgreSQL，是官方推荐的生产选择。

5. 它是完全免费的吗？ 采用 MSCL 1.0 源码可见协议：年营收低于 500 万美元且员工少于 50 人的组织可通过 Open Innovation Grant 免费使用；另有面向所有人的免费 Core 层；超过该门槛或使用高级/企业功能需要商业授权。

6. 可以不用 Docker，直接用 Node 跑吗？ 可以。用 npx directus init 交互式初始化后 npx directus start，适合本地开发；生产仍推荐 Docker 并外接数据库与 Redis。

七、跳转链接

• GitHub 仓库：https://github.com/directus/directus
• 官方文档：https://docs.directus.io/
• 快速开始：https://docs.directus.io/getting-started/quickstart
• npm 包：https://www.npmjs.com/package/directus