directus

Directus

概述

Directus 是一个开源无头 CMS 和数据平台，可为任意 SQL 数据库提供自动生成的 REST 和 GraphQL API、可视化管理面板、基于角色的访问控制、文件存储和自动化流。与 Strapi（它定义自己的架构）不同，Directus 会映射现有数据库——在管理界面或直接在 SQL 中添加列，API 会立即更新。可将其用于内容管理、内部工具、数据 API 和后端即服务。

说明

步骤 1：部署

当前版本为 Directus 12（12.4.x，2026 年 9 月；npm 上的 directus 需要 Node 22+）。生产环境请固定版本标签，不要使用 latest。许可证为 MSCL-1.0（可获取源代码，四年后转为 GPL-3.0），目前不是 MIT/GPL；从 v12 起，部分功能（SSO、自定义权限规则）需要许可证密钥，详见 https://directus.com/license。

# Docker (quickest start, SQLite)
docker run -d --name directus \
  -p 8055:8055 \
  -e SECRET="$DIRECTUS_SECRET" \
  -e ADMIN_EMAIL="[email protected]" \
  -e ADMIN_PASSWORD="$DIRECTUS_ADMIN_PASSWORD" \
  -e DB_CLIENT="sqlite3" \
  -e DB_FILENAME="/directus/database/data.db" \
  -v directus_data:/directus/database \
  -v directus_uploads:/directus/uploads \
  directus/directus:12.4.1

# Production: Docker Compose with PostgreSQL (+ Redis cache), as in the official guide
#   services: database (postgis/postgis:17-3.5), cache (redis:7), directus (directus/directus:12.4.1)
#   directus env: SECRET, DB_CLIENT=pg, DB_HOST=database, DB_PORT=5432, DB_DATABASE, DB_USER, DB_PASSWORD,
#   CACHE_ENABLED=true, CACHE_STORE=redis, REDIS=redis://cache:6379, ADMIN_EMAIL, ADMIN_PASSWORD, PUBLIC_URL
#   volumes: ./uploads:/directus/uploads  ./extensions:/directus/extensions

# Admin (Data Studio): http://localhost:8055

在反向代理后运行时，设置 IP_TRUST_PROXY=true（从 v12 起默认值为 false）和 PUBLIC_URL。监控：/server/ping 为公开端点；从 v12 起，/server/health 需要身份验证。使用 openssl rand -base64 32 生成 SECRET。

步骤 2：数据建模

通过管理界面或 REST API 创建集合（表）和字段。从用户个人资料的 Token 字段获取静态令牌，或使用 POST /auth/login 登录；从 v11 起，请求不存在的字段会报错。

# Create a "posts" collection via API
curl -X POST http://localhost:8055/collections \
  -H "Authorization: Bearer $DIRECTUS_ADMIN_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "collection": "posts",
    "meta": { "icon": "article", "note": "Blog posts" },
    "fields": [
      { "field": "id", "type": "uuid", "meta": { "special": ["uuid"] }, "schema": { "is_primary_key": true } },
      { "field": "title", "type": "string", "meta": { "required": true } },
      { "field": "slug", "type": "string", "meta": { "interface": "input" } },
      { "field": "content", "type": "text", "meta": { "interface": "input-rich-text-html" } },
      { "field": "status", "type": "string", "meta": { "interface": "select-dropdown", "options": { "choices": [{"text":"Draft","value":"draft"},{"text":"Published","value":"published"}] } } },
      { "field": "published_at", "type": "timestamp" }
    ]
  }'

步骤 3：自动生成 API

创建集合后，Directus 会自动生成完整的 CRUD API：

# REST — List all published posts
curl 'http://localhost:8055/items/posts?filter[status][_eq]=published&sort=-published_at&limit=10' \
  -H "Authorization: Bearer $DIRECTUS_TOKEN"

# REST — Get single post with related author
curl 'http://localhost:8055/items/posts/4f1c2a9e-7b3d-4e58-9c61-2d0a8e5b7f10?fields=*,author.name,author.avatar' \
  -H "Authorization: Bearer $DIRECTUS_TOKEN"

# REST — Create post
curl -X POST http://localhost:8055/items/posts \
  -H "Authorization: Bearer $DIRECTUS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"title": "Launch checklist", "content": "<p>Hello world</p>", "status": "draft"}'

# GraphQL — Same queries
curl -X POST http://localhost:8055/graphql \
  -H "Authorization: Bearer $DIRECTUS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"query": "{ posts(filter: {status: {_eq: \"published\"}}, sort: [\"-published_at\"], limit: 10) { id title content published_at author { name } } }"}'

步骤 4：SDK 集成

// lib/directus.js — JavaScript SDK for frontend/backend integration
import { createDirectus, rest, readItems, createItem, authentication } from '@directus/sdk'

const client = createDirectus('http://localhost:8055')
  .with(authentication())
  .with(rest())
// await client.login({ email, password })  (object argument since SDK v11+; static token: client.setToken(token))

// Fetch published posts
const posts = await client.request(
  readItems('posts', {
    filter: { status: { _eq: 'published' } },
    sort: ['-published_at'],
    limit: 10,
    fields: ['id', 'title', 'slug', 'content', 'published_at', { author: ['name', 'avatar'] }],
  })
)

// Create a new post
const newPost = await client.request(
  createItem('posts', {
    title: 'Launch checklist',
    content: '<p>Step one</p>',
    status: 'draft',
  })
)

步骤 5：角色、策略和权限

从 Directus 11 起，权限归属于策略，而非角色。策略（包含 admin_access、app_access、enforce_tfa、ip_access）会关联到某个角色或直接关联到用户；角色可以嵌套。多个策略的权限会累加。默认情况下，公共（未经身份验证）角色没有任何允许的操作。

# 1. Role
curl -X POST http://localhost:8055/roles \
  -H "Authorization: Bearer $DIRECTUS_ADMIN_TOKEN" -H 'Content-Type: application/json' \
  -d '{"name": "Viewer"}'
# -> note data.id as ROLE_ID

# 2. Policy, attached to the role through the access table
curl -X POST http://localhost:8055/policies \
  -H "Authorization: Bearer $DIRECTUS_ADMIN_TOKEN" -H 'Content-Type: application/json' \
  -d '{"name": "Read published posts", "admin_access": false, "app_access": false,
       "roles": ["3b6d0f2a-91c4-4a7e-8d52-6c1f0a9e4b27"]}'
# -> note data.id as POLICY_ID

# 3. Permission on the policy: read published posts only
curl -X POST http://localhost:8055/permissions \
  -H "Authorization: Bearer $DIRECTUS_ADMIN_TOKEN" -H 'Content-Type: application/json' \
  -d '{
    "policy": "a8e41c70-5d2b-4f93-b0c6-17d9e2f3a845",
    "collection": "posts",
    "action": "read",
    "permissions": { "status": { "_eq": "published" } },
    "fields": ["id", "title", "content", "published_at"]
  }'

将两个 UUID 替换为前两次调用返回的 ID。在 Data Studio 中，此设置位于 Settings > Access Policies。

步骤 6：Flows（自动化）

Directus Flows 是由事件、webhook、计划任务或手动按钮触发的可视化自动化流水线（内置功能，类似 Zapier）。一个 Flow 由一个触发器和一系列串联操作组成（发送电子邮件、请求 URL、运行脚本、更新条目……）。在 Settings > Flows 中构建操作；下面的 API 调用只会创建触发器，没有操作的 Flow 不会执行任何操作。

curl -X POST http://localhost:8055/flows \
  -H "Authorization: Bearer $DIRECTUS_ADMIN_TOKEN" -H 'Content-Type: application/json' \
  -d '{
    "name": "Notify on Publish",
    "trigger": "event",
    "options": { "type": "action", "scope": ["items.update"], "collections": ["posts"] },
    "accountability": "all",
    "status": "active"
  }'

从 12.3 起，查询为空的更新/删除操作不会再影响所有条目；如果确实需要这样做，请显式传入 {"limit": -1}。

示例

示例 1：为营销网站构建内容 API

用户提示词：“我需要为我们的营销网站搭建一个 CMS 后端——包括博客文章、团队成员、案例研究和常见问题。非技术编辑应该能够通过可视化面板管理内容。”

Agent 将会：

1. 使用 Docker + PostgreSQL 部署 Directus。
2. 创建 posts、team_members、case_studies 和 faqs 集合。
3. 设置关联字段（posts → author、case studies → tags）。
4. 为前端配置一个仅有只读权限的公共角色。
5. 使用 Directus SDK 连接 Next.js/Astro 前端。

示例 2：为运营数据构建内部工具

用户提示词：“我们的运营团队用电子表格跟踪订单、供应商和库存。请搭建一个带管理面板的正规后端，让他们能够管理所有数据。”

Agent 将会：

1. 部署 Directus，并将其连接到现有 PostgreSQL 数据库。
2. Directus 会自动检测现有表并生成 API 和管理界面。
3. 创建角色：admin（完全访问权限）、manager（CRUD 权限）、viewer（只读权限）。
4. 设置用于发送通知的 Flow（新订单 → Slack 提醒）。

指南

• Directus 会映射你的数据库架构，而不拥有它。你可以通过 Directus 管理界面或直接在 SQL 中添加列，两者会保持同步。因此，它适用于现有数据库。
• 将 Directus 用作内容密集型应用的后端即服务。对于复杂的业务逻辑（多步骤工作流、自定义计算），请通过自定义端点扩展，或使用单独的 API 层。
• 谨慎配置 PUBLIC 角色——它决定了未经身份验证的用户可以访问哪些内容。对于公开博客，只允许读取已发布的文章。
• 文件上传默认使用本地存储。在生产环境中，请配置 S3、Cloudflare R2 或 Google Cloud Storage，以实现可扩展性。
• 从 11 升级时，请检查 12 版的破坏性变更：IP_TRUST_PROXY 默认值为 false，/server/health 需要身份验证，?version=main 改为 ?version=published，按查询更新／删除会遵循读取权限（12.4），导入文件大小上限为 50 MB，Docker 镜像使用捆绑的 pm2，运行时不包含 npm/npx。从 10 升级到 11 时，权限从角色迁移到了策略。完整列表：https://directus.com/docs/releases/breaking-changes
• Directus 支持 PostgreSQL、MySQL、MariaDB、MS SQL、SQLite、CockroachDB 和 OracleDB（不再支持 MySQL 5.7）。建议在生产环境中使用 PostgreSQL。