Directus：驱动 AI 内容工作流的开源 Headless CMS — 2026 设置与 API 指南

mkdir ~/directus && cd ~/directus

# 创建 compose 文件
cat > docker-compose.yml << 'EOF'
version: "3"
services:
  directus:
    image: directus/directus:11.3.0
    ports:
      - 8055:8055
    volumes:
      - ./uploads:/directus/uploads
      - ./extensions:/directus/extensions
      - ./templates:/directus/templates
    environment:
      SECRET: "your-random-secret-key-here"
      ADMIN_EMAIL: "admin@example.com"
      ADMIN_PASSWORD: "SecureAdminPass123!"
      DB_CLIENT: "pg"
      DB_HOST: "database"
      DB_PORT: "5432"
      DB_DATABASE: "directus"
      DB_USER: "directus"
      DB_PASSWORD: "directus-pass"
      WEBSOCKETS_ENABLED: "true"
      CORS_ENABLED: "true"
      CORS_ORIGIN: "true"
    depends_on:
      - database
      - redis

  database:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: "directus"
      POSTGRES_USER: "directus"
      POSTGRES_PASSWORD: "directus-pass"
    volumes:
      - pg-data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    volumes:
      - redis-data:/data

volumes:
  pg-data:
  redis-data:
EOF

docker compose up -d

# 等待初始化完成，然后验证
curl -s http://localhost:8055/server/health | jq .
# 预期输出: {"status":"ok","release":"11.3.0"}

# 生产环境 .env 文件
cat > .env << 'EOF'
# 安全
SECRET=super-random-64-char-secret-for-jwt-signing
KEY=your-instance-unique-key

# 数据库
DB_CLIENT=pg
DB_HOST=database
DB_PORT=5432
DB_DATABASE=directus
DB_USER=directus
DB_PASSWORD=$(openssl rand -base64 32)

# 缓存与会话
CACHE_ENABLED=true
CACHE_STORE=redis
CACHE_REDIS=redis://redis:6379
RATE_LIMITER_ENABLED=true
RATE_LIMITER_STORE=redis

# 文件存储 (生产用 S3)
STORAGE_LOCATIONS=s3
STORAGE_S3_DRIVER=s3
STORAGE_S3_KEY=your-access-key
STORAGE_S3_SECRET=your-secret-key
STORAGE_S3_BUCKET=your-bucket
STORAGE_S3_REGION=us-east-1
STORAGE_S3_ENDPOINT=s3.amazonaws.com

# 邮件
EMAIL_TRANSPORT=smtp
EMAIL_SMTP_HOST=smtp.sendgrid.net
EMAIL_SMTP_PORT=587
EMAIL_SMTP_USER=apikey
EMAIL_SMTP_PASSWORD=your-sendgrid-key

# AI / 扩展
EXTENSIONS_PATH=./extensions
EXTENSIONS_AUTO_RELOAD=true
EOF

# 通过 REST API 创建集合
curl -X POST http://localhost:8055/collections \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin-token>" \
  -d '{
    "collection": "articles",
    "schema": { "name": "articles" },
    "meta": { "icon": "article", "singleton": false },
    "fields": [
      { "field": "id", "type": "uuid", "meta": { "special": ["uuid"] }, "schema": { "is_primary_key": true } },
      { "field": "title", "type": "string", "meta": {}, "schema": {} },
      { "field": "content", "type": "text", "meta": {}, "schema": {} },
      { "field": "status", "type": "string", "meta": { "interface": "select-dropdown", "options": { "choices": [{ "text": "草稿", "value": "draft" }, { "text": "已发布", "value": "published" }] } }, "schema": { "default_value": "draft" } },
      { "field": "ai_generated", "type": "boolean", "meta": {}, "schema": { "default_value": false } },
      { "field": "seo_score", "type": "integer", "meta": {}, "schema": {} },
      { "field": "published_at", "type": "timestamp", "meta": {}, "schema": {} },
      { "field": "hero_image", "type": "uuid", "meta": { "special": ["file"] }, "schema": {} }
    ]
  }'

# 读取所有已发布文章，带过滤和字段选择
curl -s "http://localhost:8055/items/articles?filter[status][_eq]=published&fields=id,title,seo_score,published_at&sort=-published_at&limit=10" \
  -H "Authorization: Bearer <token>" | jq .

# 创建文章
curl -X POST http://localhost:8055/items/articles \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"title":"Directus 入门指南","content":"Directus 是一个 Headless CMS...","status":"draft","seo_score":85}'

# 部分更新
curl -X PATCH http://localhost:8055/items/articles/<id> \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"status":"published","published_at":"2026-05-19T10:00:00Z"}'

# 聚合查询：按状态平均 SEO 分数
curl -s "http://localhost:8055/items/articles?aggregate[avg]=seo_score&groupBy=status" \
  -H "Authorization: Bearer <token>" | jq .

# 深层关联查询：带作者信息和图片转换的文章
curl -s "http://localhost:8055/items/articles?fields=id,title,author.name,author.email,hero_image.id,hero_image.filename_disk&filter[status][_eq]=published" \
  -H "Authorization: Bearer <token>" | jq .

# 内省模式
curl -X POST http://localhost:8055/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "{ __schema { types { name } } }"}' | jq .

# 带过滤的查询
curl -X POST http://localhost:8055/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "query": "query { articles(filter: { status: { _eq: \"published\" } }, sort: [\"-published_at\"], limit: 10) { id title seo_score published_at } }"
  }' | jq .

# 变更：创建文章
curl -X POST http://localhost:8055/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "query": "mutation { create_articles_item(data: { title: \"GraphQL 指南\", content: \"内容在此...\", status: \"draft\", seo_score: 90 }) { id title } }"
  }' | jq .

npm install @directus/sdk@18.0.0

import { createDirectus, rest, readItems, createItem, staticToken } from '@directus/sdk';

const client = createDirectus('http://localhost:8055')
  .with(rest())
  .with(staticToken('your-static-token'));

// 带过滤获取文章
const articles = await client.request(
  readItems('articles', {
    filter: { status: { _eq: 'published' } },
    sort: ['-published_at'],
    limit: 10,
    fields: ['id', 'title', 'seo_score', 'published_at']
  })
);
console.log(`Found ${articles.length} articles`);

// 创建文章
const newArticle = await client.request(
  createItem('articles', {
    title: 'AI 驱动的内容策略',
    content: '使用 GPT-4 生成...',
    status: 'draft',
    ai_generated: true,
    seo_score: 92
  })
);
console.log('Created:', newArticle.id);

# 通过 API 创建 Flow，当文章以 ai_flag=true 创建时触发
curl -X POST http://localhost:8055/flows \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin-token>" \
  -d '{
    "name": "AI 内容生成器",
    "status": "active",
    "trigger": "event",
    "accountability": "all",
    "options": { "type": "filter", "scope": ["items.create.articles"] }
  }'

// extensions/hooks/ai-content/index.js
import { defineHook } from '@directus/extensions-sdk';

export default defineHook(({ filter, action }) => {
  filter('articles.items.create', async (payload, meta, context) => {
    if (payload.ai_generate === true && !payload.content) {
      const { OpenAI } = await import('openai');
      const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

      const response = await openai.chat.completions.create({
        model: 'gpt-4o',
        messages: [
          { role: 'system', content: 'You are a technical content writer.' },
          { role: 'user', content: `Write a blog post titled: "${payload.title}". Output JSON with fields: content, excerpt, seo_keywords (array).` }
        ],
        response_format: { type: 'json_object' },
        max_tokens: 2000
      });

      const result = JSON.parse(response.choices[0].message.content);
      payload.content = result.content;
      payload.excerpt = result.excerpt;
      payload.seo_keywords = result.seo_keywords;
      payload.ai_generated = true;
      payload.status = 'review'; // 强制审核状态
    }
    return payload;
  });

  // 记录 AI 生成事件
  action('articles.items.create', async (meta, context) => {
    if (meta.payload.ai_generated) {
      await context.database('activity').insert({
        action: 'ai_generate',
        user: meta.user,
        collection: 'articles',
        item: meta.key,
        timestamp: new Date()
      });
    }
  });
});

# 构建并部署扩展
cd extensions/hooks/ai-content
npm install
npm run build

# Directus 会热重载扩展
cp -r dist/* /directus/extensions/hooks/ai-content/

// 获取待审核的文章
const pendingReview = await client.request(
  readItems('articles', {
    filter: {
      _and: [
        { status: { _eq: 'review' } },
        { ai_generated: { _eq: true } }
      ]
    },
    fields: ['id', 'title', 'excerpt', 'seo_score', 'seo_keywords', 'date_created']
  })
);

// 内容编辑者审批
await client.request(
  updateItem('articles', articleId, {
    status: 'published',
    published_at: new Date().toISOString()
  })
);

# 使用读副本水平扩展 API
version: "3"
services:
  directus-api-1:
    image: directus/directus:11.3.0
    environment:
      DB_CLIENT: "pg"
      DB_HOST: "postgres-primary"
      # ... 其他环境变量

  directus-api-2:
    image: directus/directus:11.3.0
    environment:
      DB_CLIENT: "pg"
      DB_HOST: "postgres-replica"
      # ... 其他环境变量

  nginx:
    image: nginx:alpine
    ports:
      - "8055:8055"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf

#!/bin/bash
# backup.sh — 通过 cron 每天运行
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR=/backups/directus
mkdir -p $BACKUP_DIR

# 数据库备份
docker exec directus-database pg_dump -U directus directus \
  | gzip > $BACKUP_DIR/db_$TIMESTAMP.sql.gz

# 上传文件备份
tar czf $BACKUP_DIR/uploads_$TIMESTAMP.tar.gz ./uploads/

# 同步到 S3
aws s3 sync $BACKUP_DIR s3://backup-bucket/directus/ --delete

# 保留 14 天
find $BACKUP_DIR -mtime +14 -delete

// extensions/endpoints/stats/index.js
import { defineEndpoint } from '@directus/extensions-sdk';

export default defineEndpoint((router, { services, database }) => {
  const { ItemsService } = services;

  router.get('/content-stats', async (req, res) => {
    const articles = new ItemsService('articles', { schema: req.schema, accountability: req.accountability });

    const [total, published, draft, aiGenerated] = await Promise.all([
      articles.count(),
      articles.count({ status: { _eq: 'published' } }),
      articles.count({ status: { _eq: 'draft' } }),
      articles.count({ ai_generated: { _eq: true } })
    ]);

    res.json({ total, published, draft, aiGenerated, ratio: Math.round((aiGenerated / total) * 100) });
  });

  router.get('/seo-report', async (req, res) => {
    const result = await database.raw(`
      SELECT status, AVG(seo_score) as avg_score, COUNT(*) as count
      FROM articles
      GROUP BY status
    `);
    res.json(result.rows);
  });
});

// 授予编辑角色对 SEO 字段只读，对内容完全访问
const rolePermissions = {
  collection: 'articles',
  role: 'editor-role-id',
  action: 'read',
  permissions: { status: { _eq: 'published' } },
  fields: ['id', 'title', 'content', 'published_at'], // 不包含 seo_score, ai_generated
  validation: null
};

// 管理员角色可查看所有内容
const adminPermissions = {
  collection: 'articles',
  role: 'admin-role-id',
  action: 'read',
  permissions: {},
  fields: ['*'], // 所有字段
  validation: null
};

// extensions/endpoints/metrics/index.js
import { defineEndpoint } from '@directus/extensions-sdk';

export default defineEndpoint((router, { database }) => {
  router.get('/metrics', async (_req, res) => {
    const metrics = await database.raw(`
      SELECT schemaname, tablename, n_tup_ins, n_tup_upd, n_tup_del
      FROM pg_stat_user_tables
      WHERE schemaname = 'public'
    `);

    let output = '';
    metrics.rows.forEach(row => {
      output += `directus_table_inserts{table="${row.tablename}"} ${row.n_tup_ins}\n`;
      output += `directus_table_updates{table="${row.tablename}"} ${row.n_tup_upd}\n`;
    });

    res.setHeader('Content-Type', 'text/plain');
    res.send(output);
  });
});