Directus：即时API与后台管理完全指南：数据库CMS的完整教程

背景

在现代应用开发中，数据库与前端之间的数据交互是核心环节。传统的开发模式需要开发者编写大量的后端代码来实现 CRUD 操作、权限控制、API 文档等工作，这不仅耗时，还容易出错。

Directus 正是为解决这一痛点而生的开源工具。它能够将任意的 SQL 数据库直接转换为可用的 RESTful API，同时提供了一个现代化的后台管理界面。对于追求开发效率的团队而言，Directus 是一个值得考虑的选择。

本文将提供一份保姆级教程，详细讲解 Directus 的部署与配置，帮助读者快速掌握这一强大的数据库 API 平台。

一、项目概述

1.1 Directus 简介

Directus 是一款开源的无头 CMS 和数据库管理平台，GitHub Star 数超过 20K。它能够与任意的 SQL 数据库连接，自动生成标准的 RESTful API 和 GraphQL 接口。

Directus 的核心特点：

  • 数据库无关：支持 MySQL、PostgreSQL、SQLite 等
  • 即时 API：自动生成 CRUD API
  • 可视化后台：提供现代化的管理界面
  • 权限控制：细粒度的角色和权限管理
  • 文件管理：内置文件上传和管理
  • 扩展性强：支持自定义扩展和插件

1.2 核心功能

1.2.1 数据管理

Directus 提供了完整的数据管理能力：

  • 集合管理：创建和管理数据集合（表）
  • 字段配置：配置字段类型、验证规则
  • 关系定义：建立表之间的关联关系
  • 数据操作：可视化的数据增删改查
1.2.2 API 生成

自动生成标准的 API：

  • REST API：完整的 CRUD 接口
  • GraphQL API：灵活的查询接口
  • 实时订阅：WebSocket 实时数据
  • API 文档：自动生成的 API 文档
1.2.3 后台管理

现代化的管理界面：

  • 用户管理：用户和角色管理
  • 文件管理：上传和管理文件资产
  • 活动日志：记录所有操作
  • 设置中心：系统配置管理

1.3 技术架构

Directus 采用现代化的技术栈：

  • 后端：基于 Node.js + TypeScript
  • 前端：基于 Vue.js + TypeScript
  • 数据库：支持多种 SQL 数据库
  • 缓存：支持 Redis 缓存
  • 文件存储：支持本地存储和 S3 兼容存储

二、Docker Compose 部署

2.1 环境准备

确保服务器已安装：

  • Docker 20.10+
  • Docker Compose 2.0+
  • 内存：最低 2GB，推荐 4GB+
  • 磁盘：根据数据量而定

2.2 创建部署目录

mkdir -p /opt/directus
cd /opt/directus

# 创建数据目录
mkdir -p ./uploads ./database

2.3 创建 docker-compose.yml

cat > docker-compose.yml << 'EOF'
version: "3.8"

services:
  directus:
    image: directus/directus:latest
    container_name: directus
    ports:
      - "8055:8055"
    volumes:
      - ./uploads:/directus/uploads
      - ./database:/directus/database
    environment:
      - KEY=your-secret-key
      - SECRET=your-secret-value
      - ADMIN_EMAIL=admin@example.com
      - ADMIN_PASSWORD=your-admin-password
      - DB_CLIENT=postgres
      - DB_HOST=db
      - DB_PORT=5432
      - DB_DATABASE=directus
      - DB_USER=directus
      - DB_PASSWORD=your_db_password
      - REDIS=redis://redis:6379
    depends_on:
      - db
      - redis

  db:
    image: postgres:15-alpine
    container_name: directus-db
    environment:
      - POSTGRES_USER=directus
      - POSTGRES_PASSWORD=your_db_password
      - POSTGRES_DB=directus
    volumes:
      - postgres_data:/var/lib/postgresql/data
    restart: unless-stopped

  redis:
    image: redis:6-alpine
    container_name: directus-redis
    volumes:
      - redis_data:/data
    restart: unless-stopped

volumes:
  postgres_data:
  redis_data:
EOF

2.4 环境变量说明

变量 说明 示例
KEY 加密密钥 随机字符串
SECRET 密钥值 随机字符串
ADMIN_EMAIL 管理员邮箱 admin@example.com
ADMIN_PASSWORD 管理员密码 strong-password
DB_CLIENT 数据库类型 postgres
DB_HOST 数据库主机 db

生成随机密钥：

openssl rand -hex 32

2.5 启动服务

# 启动服务
docker compose up -d

# 查看服务状态
docker compose ps

# 查看日志
docker compose logs -f

2.6 访问 Directus

服务启动后，访问 http://your-server-ip:8055。

使用管理员账户登录：

  • 邮箱：admin@example.com
  • 密码：your-admin-password（.env 中设置的密码）

2.7 Nginx 反向代理

cat > /etc/nginx/sites-available/directus << 'EOF'
server {
    listen 80;
    server_name directus.your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:8055;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
EOF

ln -s /etc/nginx/sites-available/directus /etc/nginx/sites-enabled/
nginx -t
systemctl reload nginx

# 启用 HTTPS
apt-get install -y certbot python3-certbot-nginx
certbot --nginx -d directus.your-domain.com

三、快速入门

3.1 界面布局

Directus 管理界面主要包含：

  • 顶部导航：搜索、通知、设置
  • 左侧边栏：集合、文件、设置入口
  • 主内容区：数据展示和操作界面
  • 右侧面板：字段配置、详情查看

3.2 创建集合

集合（Collection）对应数据库中的表。

3.2.1 新建集合
  1. 点击左侧"创建集合"
  2. 输入集合名称（英文）
  3. 设置集合选项
  4. 完成创建
3.2.2 配置字段

添加字段：

  1. 进入集合设置
  2. 点击"添加字段"
  3. 选择字段类型
  4. 设置字段名称和选项

支持的字段类型：

类型 说明
string 字符串
text 长文本
integer 整数
float 浮点数
boolean 布尔值
datetime 日期时间
date 日期
time 时间
uuid UUID
json JSON 数据
csv CSV 数据
email 邮箱地址
url URL 地址
file 文件关联
user 用户关联
m2o 多对一关联
o2m 一对多关联
m2m 多对多关联

3.3 数据操作

3.3.1 添加数据
  1. 进入集合页面
  2. 点击右上角"+"按钮
  3. 填写数据字段
  4. 点击"保存"
3.3.2 编辑数据
  1. 点击数据行
  2. 修改字段值
  3. 自动保存或点击保存按钮
3.3.3 删除数据
  1. 选择要删除的数据
  2. 点击删除按钮
  3. 确认删除

3.4 文件管理

3.4.1 上传文件
  1. 点击左侧"文件"入口
  2. 点击"上传文件"
  3. 选择本地文件
  4. 上传完成
3.4.2 使用文件

在字段类型中选择"file"，可以直接关联文件：

  1. 编辑数据
  2. 点击文件字段
  3. 从已上传文件中选择或重新上传

四、API 使用

4.1 获取 API 密钥

  1. 进入个人设置
  2. 点击"API 密钥"
  3. 创建新密钥
  4. 复制密钥值

4.2 REST API

4.2.1 基础请求
# 获取集合数据
curl https://your-directus.com/items/posts \
  -H "Authorization: Bearer YOUR_API_KEY"

# 获取单条数据
curl https://your-directus.com/items/posts/1 \
  -H "Authorization: Bearer YOUR_API_KEY"

# 创建数据
curl -X POST https://your-directus.com/items/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Hello World", "content": "This is my first post"}'

# 更新数据
curl -X PATCH https://your-directus.com/items/posts/1 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Updated Title"}'

# 删除数据
curl -X DELETE https://your-directus.com/items/posts/1 \
  -H "Authorization: Bearer YOUR_API_KEY"
4.2.2 查询参数
参数 说明 示例
fields 指定返回字段 fields=id,title,content
filter 筛选条件 filter[status][_eq]=published
sort 排序 sort=-created_at
limit 限制数量 limit=10
offset 偏移量 offset=10
page 页码 page=2

筛选示例：

# 筛选 published 状态的帖子
curl "https://your-directus.com/items/posts?filter[status][_eq]=published" \
  -H "Authorization: Bearer YOUR_API_KEY"

4.3 GraphQL API

curl -X POST https://your-directus.com/graphql \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query { posts { id title content } }"
  }'

4.4 文件 API

# 上传文件
curl -X POST https://your-directus.com/files \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/image.jpg"

# 获取文件信息
curl https://your-directus.com/files/FILE_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

五、权限管理

5.1 角色管理

5.1.1 创建角色
  1. 进入"设置" → “角色”
  2. 点击"创建角色"
  3. 输入角色名称
  4. 配置权限
5.1.2 内置角色

Directus 内置了两个角色：

  • 管理员：完全访问权限
  • 公共：未登录用户的默认权限

5.2 权限配置

5.2.1 集合权限

为角色配置集合访问权限：

权限 说明
none 无权限
read 只读
create 创建数据
update 更新数据
delete 删除数据
read+ 只读（含字段）
create+ 创建（含字段）
update+ 更新（含字段）
delete+ 删除（含字段）
5.2.2 字段权限

细粒度控制字段权限：

  1. 选择权限级别
  2. 点击"字段"
  3. 选择允许访问的字段

5.3 用户管理

5.3.1 创建用户
  1. 进入"用户"
  2. 点击"创建用户"
  3. 填写用户信息
  4. 选择用户角色
  5. 发送邀请或设置密码

六、扩展和定制

6.1 自定义字段类型

Directus 支持创建自定义字段类型插件：

// 自定义字段类型示例
module.exports = {
  id: 'my-custom-field',
  types: ['string'],
  fields: [
    {
      field: 'format',
      type: 'string',
      schema: { default_value: 'default' }
    }
  ]
};

6.2 自定义 API 端点

创建自定义 API 端点：

// custom endpoints/example.js
module.exports = (router, { env }) => {
  router.get('/custom-endpoint', (req, res) => {
    res.json({ message: 'Hello from custom endpoint!' });
  });
};

6.3 钩子配置

配置数据变更钩子：

  1. 进入"设置" → “钩子”
  2. 点击"创建钩子"
  3. 选择触发时机
  4. 配置处理逻辑

七、数据迁移

7.1 导入数据

7.1.1 CSV 导入
  1. 进入集合页面
  2. 点击"导入"
  3. 选择 CSV 文件
  4. 映射字段
  5. 开始导入
7.1.2 JSON 导入
curl -X POST https://your-directus.com/utils/import \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "collection=posts" \
  -F "file=@data.json"

7.2 导出数据

7.2.1 CSV 导出
curl "https://your-directus.com/items/posts?export=csv" \
  -H "Authorization: Bearer YOUR_API_KEY"

八、常见问题

8.1 部署问题

Q：服务启动失败

A：检查日志：

docker compose logs directus

确认数据库和 Redis 连接正常。

Q：上传文件失败

A：检查存储目录权限：

chmod 755 ./uploads

8.2 使用问题

Q：API 返回 403

A：检查权限配置，确保当前用户/密钥有访问权限。

Q：关联数据无法查询

A：检查关联字段配置，确保在 fields 参数中包含关联字段。

九、总结

Directus 作为开源的无头 CMS 平台，以其数据库无关、即时 API 生成、现代化管理界面等特点，为开发者提供了一个高效的数据管理解决方案。

通过本文的保姆级教程，读者应该已经掌握了：

  1. Docker 部署：使用 Docker Compose 快速部署 Directus
  2. 集合管理：创建集合、配置字段
  3. 数据操作：增删改查数据
  4. API 使用：REST API 和 GraphQL API
  5. 权限管理：角色和权限配置
  6. 扩展定制：自定义端点和钩子

对于需要快速构建后端 API 的开发团队，Directus 是一个值得尝试的开源选择。

© 版权归无边界科技所有，版权所有。

# 数据库
Logo
DAMO开发者矩阵

DAMO开发者矩阵，由阿里巴巴达摩院和中国互联网协会联合发起，致力于探讨最前沿的技术趋势与应用成果，搭建高质量的交流与分享平台，推动技术创新与产业应用链接，围绕“人工智能与新型计算”构建开放共享的开发者生态。

更多推荐

cover

2026 WAIC | 星源智刘东：跨本体数据不能“混着训”，统一标准比扩大规模更重要

avatar DAMO开发者矩阵
cover

一目科技完成超 10 亿元 E 轮融资，百亿估值筑牢机器人触觉基座

avatar DAMO开发者矩阵
cover

WAIC 2026｜摩尔线程发布多项训练推理成果 三大 AI 工厂激活算力价值

avatar DAMO开发者矩阵