Directus 自托管内容 API本地 CMS 跑通后用 cpolar 给前端远程验收接口和后台前端做官网、活动页、App 配置页时最怕内容接口还没稳定字段名今天一个版本权限明天一个版本图片上传又要单独找人联调。Directus 适合解决这类问题。它不是简单的数据库管理台而是把测试库里的内容模型变成可用的后台、REST API、GraphQL API 和媒体库。这篇从零跑一套本地 DirectusDocker 部署使用 SQLite 测试库创建文章内容集合和媒体字段配置只读角色权限验证 REST/GraphQL 接口最后用 cpolar 开一个短时 HTTPS 入口让前端同事远程验收后台、接口、字段权限和媒体上传。边界先说清楚本文只使用测试库和脱敏内容不暴露数据库端口、Admin 密码、静态密钥和服务器目录不开放公开注册cpolar 只短时转发 Directus Web/API验收结束立即关闭隧道。长期环境请换正式 HTTPS 域名、备份、最小权限角色和审计策略。1. 准备目录和 docker-composeDirectus 可以连接 PostgreSQL、MySQL、SQLite 等数据库。为了本地验收简单可复现这里用 SQLite 测试库。它适合 Demo、字段确认和前端接口验收不要拿生产数据文件直接做公网联调。新建目录mkdir -p ~/demo/directus-content-api cd ~/demo/directus-content-api mkdir -p database uploads extensions创建docker-compose.ymlservices: directus: image: directus/directus:11 container_name: directus-content-demo ports: - 127.0.0.1:8055:8055 volumes: - ./database:/directus/database - ./uploads:/directus/uploads - ./extensions:/directus/extensions environment: KEY: replace-with-a-long-random-key-for-demo SECRET: replace-with-a-long-random-secret-for-demo ADMIN_EMAIL: adminexample.local ADMIN_PASSWORD: ChangeMe-Directus-2026! DB_CLIENT: sqlite3 DB_FILENAME: /directus/database/data.db WEBSOCKETS_ENABLED: true PUBLIC_URL: http://127.0.0.1:8055这里有两个细节ports绑定到127.0.0.1:8055只允许本机访问不把 Directus 直接监听到局域网或公网。KEY、SECRET、ADMIN_PASSWORD演示时也要换成自己的随机值不要提交到 Git 仓库更不要发给前端群。启动docker compose up -d查看日志docker compose logs -f directus看到服务运行后打开后台http://127.0.0.1:8055/admin用ADMIN_EMAIL和ADMIN_PASSWORD登录。登录后先进入 Settings确认没有开放公开注册。这个演示只给前端一个低权限账号不让外部用户自行注册。2. 创建内容模型articles 集合我们做一个“官网文章/活动页内容”模型前端验收时能覆盖标题、摘要、富文本、封面、状态和排序这些常见字段。在 Directus 后台进入Settings → Data Model新建集合Collection Name: articles Display Template: {{title}}字段按下面配置字段类型用途titleString文章标题必填slugString前端路由或详情页标识必填且唯一summaryText列表摘要contentText / WYSIWYG正文内容coverFile封面图关联 Directus FilesstatusStringdraft / publishedsortInteger首页排序published_atDateTime发布时间cover字段选择 File 类型Directus 会使用内置的directus_files媒体库。这样前端既能拿文章 JSON也能拿文件 ID再通过 Directus 的 assets 地址显示图片。保存后进入Content → articles新增两条脱敏测试内容标题暑期活动页上线说明 slugsummer-campaign summary用于前端远程验收的测试内容 statuspublished sort10再新增一条草稿标题未发布内容测试 slugdraft-demo summary用于验证角色权限是否能过滤草稿 statusdraft sort99封面图片使用无敏感信息的测试图。不要上传客户合同、真实用户头像、生产素材原图或带 EXIF 定位信息的照片。3. 配置前端验收角色和权限Directus 的关键价值不只是“生成接口”而是能把字段权限和角色权限一起交给前端验证。这里创建一个专门的验收角色避免把 Admin 账号发出去。进入Settings → Roles Permissions新建角色Role Name: frontend_reviewer Description: 前端远程验收 Directus 内容 API只读 articles可上传测试媒体给这个角色配置权限articles 权限Read允许Create不允许Update不允许Delete不允许Read 的过滤条件设置为{ status: { _eq: published } }这样前端用验收账号只能看到已发布内容看不到草稿。字段权限建议开放id, title, slug, summary, content, cover, status, sort, published_at如果内部还有cost_price、internal_note、owner_phone这类敏感字段就不要给该角色读取权限。前端验收时要专门检查这些字段是否从接口响应里消失。directus_files 权限为了验收媒体上传给directus_files配置Read允许Create允许Update不允许Delete不允许这代表前端同事可以上传测试图片能读取自己上传和文章关联的图片但不能删除媒体库文件。正式环境还要进一步限制文件大小、MIME 类型、存储后端和生命周期。创建验收用户进入User Directory创建用户Email: reviewerexample.local Role: frontend_reviewer Status: Active Password: Review-Only-2026!这个密码只用于本次短时验收。验收结束后禁用用户或重置密码。4. 本机验证 REST APIDirectus 默认提供 REST API。先用 Admin 登录后台确认有内容再开一个终端测试匿名或验收用户访问。如果 articles 集合允许公开读取可以直接请求curl http://127.0.0.1:8055/items/articles?fieldsid,title,slug,summary,cover,statusfilter[status][_eq]published更推荐使用验收账号登录拿 tokencurl -s -X POST http://127.0.0.1:8055/auth/login \ -H Content-Type: application/json \ -d {email:reviewerexample.local,password:Review-Only-2026!}返回里会有access_token。为了演示方便保存到变量TOKEN粘贴上一步返回的 access_token请求文章列表curl http://127.0.0.1:8055/items/articles?fieldsid,title,slug,summary,cover,status,published_atsortsort \ -H Authorization: Bearer $TOKEN检查点有三个返回结果只包含statuspublished的内容。响应字段只包含前端需要的字段。草稿draft-demo不出现在列表里。如果上传过封面REST 响应里会有文件 ID。访问图片资源curl -I http://127.0.0.1:8055/assets/文件ID前端页面里可使用http://127.0.0.1:8055/assets/文件ID远程验收时把域名换成 cpolar 的 HTTPS 地址即可。5. 验证 GraphQL APIDirectus 也内置 GraphQL前端如果使用 Apollo、urql 或其他 GraphQL 客户端可以直接验收查询结构。请求示例curl -X POST http://127.0.0.1:8055/graphql \ -H Content-Type: application/json \ -H Authorization: Bearer $TOKEN \ -d { query: query { articles(filter: { status: { _eq: \published\ } }, sort: [\sort\]) { id title slug summary status published_at cover { id filename_disk type } } } }这一步要让前端确认两件事GraphQL schema 里的字段名和页面组件需要的一致。角色权限仍然生效不能因为换成 GraphQL 就读到草稿或敏感字段。如果 GraphQL 返回权限错误不要急着把角色权限全开。先看报错字段再逐个补齐需要读取的字段权限。权限调试的原则是“前端需要什么给什么”不要为了省事直接给 Admin。6. 用 cpolar 开短时 HTTPS 验收入口本机确认 Directus 可用后再给前端同事远程验收。这里 cpolar 的作用很明确只把本机8055上的 Directus Web/API 临时映射成 HTTPS 地址。不要转发数据库端口不要转发 Docker socket不要转发服务器文件目录。确认 Directus 仍在本机运行curl -I http://127.0.0.1:8055/server/health启动 cpolar 隧道cpolar http 8055终端会显示一个 HTTPS 地址形如https://xxxx.cpolar.top把 Directus 的公开地址临时改成这个 HTTPS 地址有助于媒体资源、回调地址和前端请求保持一致。编辑docker-compose.ymlPUBLIC_URL: https://xxxx.cpolar.top重启 Directusdocker compose up -d远程访问后台地址https://xxxx.cpolar.top/admin发给前端同事的信息只需要包含Directus 后台https://xxxx.cpolar.top/admin REST 列表https://xxxx.cpolar.top/items/articles?fieldsid,title,slug,summary,cover,status,published_atsortsort GraphQLhttps://xxxx.cpolar.top/graphql 验收账号reviewerexample.local 验收密码单独私信发送本次验收结束后失效密码不要和链接放在同一条群消息里也不要截图展示 Admin 控制台。7. 前端验收清单我会让前端同事按这个清单验收而不是只说“你打开看看”能打开https://xxxx.cpolar.top/admin使用frontend_reviewer用户登录。在 Content 里只能看到articles和允许读取的媒体内容。文章列表只出现published内容草稿内容不可见。REST 接口能返回页面需要的字段字段名稳定。GraphQL 查询能跑通schema 与组件数据结构匹配。上传一张测试封面图确认assets/文件ID能通过 HTTPS 打开。尝试新增、修改、删除文章应被权限拦截。尝试读取未授权字段应不出现在响应中或返回权限错误。这个清单能把“后台能看”“接口能调”“字段权限生效”“媒体上传可用”一次性确认完。对于官网、活动页、内容运营后台这比发几张截图可靠得多。8. 验收结束后的收尾验收完成后先停 cpolar# 在运行 cpolar 的终端按 CtrlC再禁用验收用户或重置密码Settings → User Directory → reviewerexample.local → Status: Suspended如果这套 Directus 只是临时 Demo可以停止容器docker compose down测试库和上传目录还在本机~/demo/directus-content-api/database ~/demo/directus-content-api/uploads保留它们前确认里面没有真实客户数据、真实用户手机号、内部文档附件或不可公开图片。要删除演示环境可以执行cd ~ rm -rf ~/demo/directus-content-api删除前再次确认路径避免误删其他项目目录。9. 长期使用时要换正式方案cpolar 很适合短时验收但不要把临时隧道当长期生产入口。Directus 一旦用于正式内容后台至少要补齐这些配置使用正式 HTTPS 域名和反向代理例如 Nginx、Caddy 或云负载均衡。数据库使用可备份、可监控的 PostgreSQL/MySQL并建立备份恢复流程。Admin 开启强密码和成员最小权限不共享账号。前端只使用低权限角色或服务端代理不把 Admin token 写进浏览器代码。媒体文件限制大小和类型接入对象存储时配置私有桶与访问策略。定期查看 Directus 活动日志审计内容修改、登录和文件上传记录。分离开发、测试、生产环境测试库只放脱敏内容。这也是我推荐先用 SQLite 本地跑通的原因字段、权限、接口和媒体流程先让前端验收清楚再决定生产库、域名、对象存储和部署架构。Directus 的优势在于内容模型能快速变成 API但权限边界必须从第一天就按真实项目去配置。小结这套流程的重点不是“把本地服务暴露出去”而是把 Directus 作为自托管内容 API 跑完整Docker 启动、SQLite 测试库、articles 内容模型、媒体上传、角色权限、REST/GraphQL 查询再用 cpolar 的临时 HTTPS 地址完成远程验收。前端拿到的不是截图而是能登录的后台、能请求的接口、能验证的字段权限和能打开的媒体资源。验收结束关掉 cpolar、禁用验收账号环境就回到本机。等要长期使用时再上正式域名、数据库备份、对象存储、审计和更细的角色权限。