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 生成自动生成标准的 APIREST 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.10Docker Compose 2.0内存最低 2GB推荐 4GB磁盘根据数据量而定2.2 创建部署目录mkdir-p/opt/directuscd/opt/directus# 创建数据目录mkdir-p./uploads ./database2.3 创建 docker-compose.ymlcatdocker-compose.ymlEOF version: 3.8 services: directus: image: directus/directus:latest container_name: directus ports: - 8055:8055 volumes: - ./uploads:/directus/uploads - ./database:/directus/database environment: - KEYyour-secret-key - SECRETyour-secret-value - ADMIN_EMAILadminexample.com - ADMIN_PASSWORDyour-admin-password - DB_CLIENTpostgres - DB_HOSTdb - DB_PORT5432 - DB_DATABASEdirectus - DB_USERdirectus - DB_PASSWORDyour_db_password - REDISredis://redis:6379 depends_on: - db - redis db: image: postgres:15-alpine container_name: directus-db environment: - POSTGRES_USERdirectus - POSTGRES_PASSWORDyour_db_password - POSTGRES_DBdirectus 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: EOF2.4 环境变量说明变量说明示例KEY加密密钥随机字符串SECRET密钥值随机字符串ADMIN_EMAIL管理员邮箱adminexample.comADMIN_PASSWORD管理员密码strong-passwordDB_CLIENT数据库类型postgresDB_HOST数据库主机db生成随机密钥openssl rand-hex322.5 启动服务# 启动服务dockercompose up-d# 查看服务状态dockercomposeps# 查看日志dockercompose logs-f2.6 访问 Directus服务启动后访问http://your-server-ip:8055。使用管理员账户登录邮箱adminexample.com密码your-admin-password.env 中设置的密码2.7 Nginx 反向代理cat/etc/nginx/sites-available/directusEOF 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; } } EOFln-s/etc/nginx/sites-available/directus /etc/nginx/sites-enabled/ nginx-tsystemctl reload nginx# 启用 HTTPSapt-getinstall-ycertbot python3-certbot-nginx certbot--nginx-ddirectus.your-domain.com三、快速入门3.1 界面布局Directus 管理界面主要包含顶部导航搜索、通知、设置左侧边栏集合、文件、设置入口主内容区数据展示和操作界面右侧面板字段配置、详情查看3.2 创建集合集合Collection对应数据库中的表。3.2.1 新建集合点击左侧创建集合输入集合名称英文设置集合选项完成创建3.2.2 配置字段添加字段进入集合设置点击添加字段选择字段类型设置字段名称和选项支持的字段类型类型说明string字符串text长文本integer整数float浮点数boolean布尔值datetime日期时间date日期time时间uuidUUIDjsonJSON 数据csvCSV 数据email邮箱地址urlURL 地址file文件关联user用户关联m2o多对一关联o2m一对多关联m2m多对多关联3.3 数据操作3.3.1 添加数据进入集合页面点击右上角按钮填写数据字段点击保存3.3.2 编辑数据点击数据行修改字段值自动保存或点击保存按钮3.3.3 删除数据选择要删除的数据点击删除按钮确认删除3.4 文件管理3.4.1 上传文件点击左侧文件入口点击上传文件选择本地文件上传完成3.4.2 使用文件在字段类型中选择file可以直接关联文件编辑数据点击文件字段从已上传文件中选择或重新上传四、API 使用4.1 获取 API 密钥进入个人设置点击API 密钥创建新密钥复制密钥值4.2 REST API4.2.1 基础请求# 获取集合数据curlhttps://your-directus.com/items/posts\-HAuthorization: Bearer YOUR_API_KEY# 获取单条数据curlhttps://your-directus.com/items/posts/1\-HAuthorization: Bearer YOUR_API_KEY# 创建数据curl-XPOST https://your-directus.com/items/posts\-HAuthorization: Bearer YOUR_API_KEY\-HContent-Type: application/json\-d{title: Hello World, content: This is my first post}# 更新数据curl-XPATCH https://your-directus.com/items/posts/1\-HAuthorization: Bearer YOUR_API_KEY\-HContent-Type: application/json\-d{title: Updated Title}# 删除数据curl-XDELETE https://your-directus.com/items/posts/1\-HAuthorization: Bearer YOUR_API_KEY4.2.2 查询参数参数说明示例fields指定返回字段fieldsid,title,contentfilter筛选条件filter[status][_eq]publishedsort排序sort-created_atlimit限制数量limit10offset偏移量offset10page页码page2筛选示例# 筛选 published 状态的帖子curlhttps://your-directus.com/items/posts?filter[status][_eq]published\-HAuthorization: Bearer YOUR_API_KEY4.3 GraphQL APIcurl-XPOST https://your-directus.com/graphql\-HAuthorization: Bearer YOUR_API_KEY\-HContent-Type: application/json\-d{ query: query { posts { id title content } } }4.4 文件 API# 上传文件curl-XPOST https://your-directus.com/files\-HAuthorization: Bearer YOUR_API_KEY\-Ffile/path/to/image.jpg# 获取文件信息curlhttps://your-directus.com/files/FILE_ID\-HAuthorization: Bearer YOUR_API_KEY五、权限管理5.1 角色管理5.1.1 创建角色进入设置 → “角色”点击创建角色输入角色名称配置权限5.1.2 内置角色Directus 内置了两个角色管理员完全访问权限公共未登录用户的默认权限5.2 权限配置5.2.1 集合权限为角色配置集合访问权限权限说明none无权限read只读create创建数据update更新数据delete删除数据read只读含字段create创建含字段update更新含字段delete删除含字段5.2.2 字段权限细粒度控制字段权限选择权限级别点击字段选择允许访问的字段5.3 用户管理5.3.1 创建用户进入用户点击创建用户填写用户信息选择用户角色发送邀请或设置密码六、扩展和定制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.jsmodule.exports(router,{env}){router.get(/custom-endpoint,(req,res){res.json({message:Hello from custom endpoint!});});};6.3 钩子配置配置数据变更钩子进入设置 → “钩子”点击创建钩子选择触发时机配置处理逻辑七、数据迁移7.1 导入数据7.1.1 CSV 导入进入集合页面点击导入选择 CSV 文件映射字段开始导入7.1.2 JSON 导入curl-XPOST https://your-directus.com/utils/import\-HAuthorization: Bearer YOUR_API_KEY\-Fcollectionposts\-Ffiledata.json7.2 导出数据7.2.1 CSV 导出curlhttps://your-directus.com/items/posts?exportcsv\-HAuthorization: Bearer YOUR_API_KEY八、常见问题8.1 部署问题Q服务启动失败A检查日志dockercompose logs directus确认数据库和 Redis 连接正常。Q上传文件失败A检查存储目录权限chmod755./uploads8.2 使用问题QAPI 返回 403A检查权限配置确保当前用户/密钥有访问权限。Q关联数据无法查询A检查关联字段配置确保在 fields 参数中包含关联字段。九、总结Directus 作为开源的无头 CMS 平台以其数据库无关、即时 API 生成、现代化管理界面等特点为开发者提供了一个高效的数据管理解决方案。通过本文的保姆级教程读者应该已经掌握了Docker 部署使用 Docker Compose 快速部署 Directus集合管理创建集合、配置字段数据操作增删改查数据API 使用REST API 和 GraphQL API权限管理角色和权限配置扩展定制自定义端点和钩子对于需要快速构建后端 API 的开发团队Directus 是一个值得尝试的开源选择。本文由无边界科技技术团队分享专注软件开发与技术解决方案。官网wubianj.com© 版权归无边界科技所有版权所有。
Directus：即时API与后台管理完全指南：数据库CMS的完整教程
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 生成自动生成标准的 APIREST 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.10Docker Compose 2.0内存最低 2GB推荐 4GB磁盘根据数据量而定2.2 创建部署目录mkdir-p/opt/directuscd/opt/directus# 创建数据目录mkdir-p./uploads ./database2.3 创建 docker-compose.ymlcatdocker-compose.ymlEOF version: 3.8 services: directus: image: directus/directus:latest container_name: directus ports: - 8055:8055 volumes: - ./uploads:/directus/uploads - ./database:/directus/database environment: - KEYyour-secret-key - SECRETyour-secret-value - ADMIN_EMAILadminexample.com - ADMIN_PASSWORDyour-admin-password - DB_CLIENTpostgres - DB_HOSTdb - DB_PORT5432 - DB_DATABASEdirectus - DB_USERdirectus - DB_PASSWORDyour_db_password - REDISredis://redis:6379 depends_on: - db - redis db: image: postgres:15-alpine container_name: directus-db environment: - POSTGRES_USERdirectus - POSTGRES_PASSWORDyour_db_password - POSTGRES_DBdirectus 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: EOF2.4 环境变量说明变量说明示例KEY加密密钥随机字符串SECRET密钥值随机字符串ADMIN_EMAIL管理员邮箱adminexample.comADMIN_PASSWORD管理员密码strong-passwordDB_CLIENT数据库类型postgresDB_HOST数据库主机db生成随机密钥openssl rand-hex322.5 启动服务# 启动服务dockercompose up-d# 查看服务状态dockercomposeps# 查看日志dockercompose logs-f2.6 访问 Directus服务启动后访问http://your-server-ip:8055。使用管理员账户登录邮箱adminexample.com密码your-admin-password.env 中设置的密码2.7 Nginx 反向代理cat/etc/nginx/sites-available/directusEOF 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; } } EOFln-s/etc/nginx/sites-available/directus /etc/nginx/sites-enabled/ nginx-tsystemctl reload nginx# 启用 HTTPSapt-getinstall-ycertbot python3-certbot-nginx certbot--nginx-ddirectus.your-domain.com三、快速入门3.1 界面布局Directus 管理界面主要包含顶部导航搜索、通知、设置左侧边栏集合、文件、设置入口主内容区数据展示和操作界面右侧面板字段配置、详情查看3.2 创建集合集合Collection对应数据库中的表。3.2.1 新建集合点击左侧创建集合输入集合名称英文设置集合选项完成创建3.2.2 配置字段添加字段进入集合设置点击添加字段选择字段类型设置字段名称和选项支持的字段类型类型说明string字符串text长文本integer整数float浮点数boolean布尔值datetime日期时间date日期time时间uuidUUIDjsonJSON 数据csvCSV 数据email邮箱地址urlURL 地址file文件关联user用户关联m2o多对一关联o2m一对多关联m2m多对多关联3.3 数据操作3.3.1 添加数据进入集合页面点击右上角按钮填写数据字段点击保存3.3.2 编辑数据点击数据行修改字段值自动保存或点击保存按钮3.3.3 删除数据选择要删除的数据点击删除按钮确认删除3.4 文件管理3.4.1 上传文件点击左侧文件入口点击上传文件选择本地文件上传完成3.4.2 使用文件在字段类型中选择file可以直接关联文件编辑数据点击文件字段从已上传文件中选择或重新上传四、API 使用4.1 获取 API 密钥进入个人设置点击API 密钥创建新密钥复制密钥值4.2 REST API4.2.1 基础请求# 获取集合数据curlhttps://your-directus.com/items/posts\-HAuthorization: Bearer YOUR_API_KEY# 获取单条数据curlhttps://your-directus.com/items/posts/1\-HAuthorization: Bearer YOUR_API_KEY# 创建数据curl-XPOST https://your-directus.com/items/posts\-HAuthorization: Bearer YOUR_API_KEY\-HContent-Type: application/json\-d{title: Hello World, content: This is my first post}# 更新数据curl-XPATCH https://your-directus.com/items/posts/1\-HAuthorization: Bearer YOUR_API_KEY\-HContent-Type: application/json\-d{title: Updated Title}# 删除数据curl-XDELETE https://your-directus.com/items/posts/1\-HAuthorization: Bearer YOUR_API_KEY4.2.2 查询参数参数说明示例fields指定返回字段fieldsid,title,contentfilter筛选条件filter[status][_eq]publishedsort排序sort-created_atlimit限制数量limit10offset偏移量offset10page页码page2筛选示例# 筛选 published 状态的帖子curlhttps://your-directus.com/items/posts?filter[status][_eq]published\-HAuthorization: Bearer YOUR_API_KEY4.3 GraphQL APIcurl-XPOST https://your-directus.com/graphql\-HAuthorization: Bearer YOUR_API_KEY\-HContent-Type: application/json\-d{ query: query { posts { id title content } } }4.4 文件 API# 上传文件curl-XPOST https://your-directus.com/files\-HAuthorization: Bearer YOUR_API_KEY\-Ffile/path/to/image.jpg# 获取文件信息curlhttps://your-directus.com/files/FILE_ID\-HAuthorization: Bearer YOUR_API_KEY五、权限管理5.1 角色管理5.1.1 创建角色进入设置 → “角色”点击创建角色输入角色名称配置权限5.1.2 内置角色Directus 内置了两个角色管理员完全访问权限公共未登录用户的默认权限5.2 权限配置5.2.1 集合权限为角色配置集合访问权限权限说明none无权限read只读create创建数据update更新数据delete删除数据read只读含字段create创建含字段update更新含字段delete删除含字段5.2.2 字段权限细粒度控制字段权限选择权限级别点击字段选择允许访问的字段5.3 用户管理5.3.1 创建用户进入用户点击创建用户填写用户信息选择用户角色发送邀请或设置密码六、扩展和定制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.jsmodule.exports(router,{env}){router.get(/custom-endpoint,(req,res){res.json({message:Hello from custom endpoint!});});};6.3 钩子配置配置数据变更钩子进入设置 → “钩子”点击创建钩子选择触发时机配置处理逻辑七、数据迁移7.1 导入数据7.1.1 CSV 导入进入集合页面点击导入选择 CSV 文件映射字段开始导入7.1.2 JSON 导入curl-XPOST https://your-directus.com/utils/import\-HAuthorization: Bearer YOUR_API_KEY\-Fcollectionposts\-Ffiledata.json7.2 导出数据7.2.1 CSV 导出curlhttps://your-directus.com/items/posts?exportcsv\-HAuthorization: Bearer YOUR_API_KEY八、常见问题8.1 部署问题Q服务启动失败A检查日志dockercompose logs directus确认数据库和 Redis 连接正常。Q上传文件失败A检查存储目录权限chmod755./uploads8.2 使用问题QAPI 返回 403A检查权限配置确保当前用户/密钥有访问权限。Q关联数据无法查询A检查关联字段配置确保在 fields 参数中包含关联字段。九、总结Directus 作为开源的无头 CMS 平台以其数据库无关、即时 API 生成、现代化管理界面等特点为开发者提供了一个高效的数据管理解决方案。通过本文的保姆级教程读者应该已经掌握了Docker 部署使用 Docker Compose 快速部署 Directus集合管理创建集合、配置字段数据操作增删改查数据API 使用REST API 和 GraphQL API权限管理角色和权限配置扩展定制自定义端点和钩子对于需要快速构建后端 API 的开发团队Directus 是一个值得尝试的开源选择。本文由无边界科技技术团队分享专注软件开发与技术解决方案。官网wubianj.com© 版权归无边界科技所有版权所有。
