Directus 12.5 配置参数详解

目标：把 Directus 12.5.0 的核心环境变量逐组讲清并逐组实测——KEY/SECRET、数据库连接 DB_、初始管理员 ADMIN_、缓存 CACHE_/REDIS_、跨域 CORS_、文件存储 STORAGE_ 等，每组给出参数说明、官方默认值与真实改参实测回显，全部回显逐字来自 2026-10-19 在本机 8103 实例上的实测。部署过程见 《Directus Docker Compose 部署指南》，产品定位见 《Directus 12.5 介绍与选型指南》。

一、环境信息

Directus 12.5 没有主配置文件，全部配置以环境变量注入（这是它与 MySQL/Redis 等「配置文件型」组件最大的差异），因此本文的「修改参数」都是改环境变量后重启实例。

二、前置条件

按 《Directus Docker Compose 部署指南》第四章完成部署并验证 /server/ping 通：

curl -s http://127.0.0.1:8103/server/ping -w " HTTP %{http_code}\n"

实测回显：

pong HTTP 200

管理员登录换 token（后续受保护端点均用它）：

curl -s -X POST http://127.0.0.1:8103/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@example.com","password":"q1w2e3r4"}' \
  | python3 -c "import json,sys;print(json.load(sys.stdin)['data']['access_token'])"

实测回显（token 为 260 字符左右 JWT，此处截断）：

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjcxMDNiNjdiLWIzNzYtNGZmYi1hYzBkLTE0YzVjY2ZkMTdkYiIs...(截断)

三、参数查看与修改方式

3.1 查看当前生效值

Directus 不提供「导出全部配置」的管理 API，最直接的核对方式是看进程环境变量：

cd /opt/data/quzuo/directus-12-5 && docker compose exec -T directus env | grep -E '^(KEY|SECRET|DB_CLIENT|DB_HOST|CACHE_ENABLED|CACHE_STORE|CORS_ENABLED|PUBLIC_URL)='

实测回显：

SECRET=6116487b-cda1-52c2-b5b5-c8022c45e263
DB_HOST=db
DB_CLIENT=pg
CORS_ENABLED=true
CACHE_STORE=redis
CACHE_ENABLED=true
KEY=255d861b-5ea1-5996-9aa3-922530ec40b1
PUBLIC_URL=http://192.168.146.128:8103

⚠️ 注意：SECRET 会原样出现在环境变量里，排查时避免把该命令输出贴到不受控场合。

3.2 修改方式与生效条件

• compose 部署：改 docker-compose.yml 的 environment: 段后 docker compose up -d directus 重建应用（约 15 秒恢复）；
• 数据库连接类参数改错会启动失败（见第六章实测）；KEY/SECRET 改动会立刻影响登录态（见第五章实测）；
• ADMIN_EMAIL/ADMIN_PASSWORD 只在首次初始化生效，后续改了也不影响已有账号（见第七章实测）。

3.3 命名规则

环境变量按域分组：DB_* 数据库、CACHE_*/REDIS_* 缓存、CORS_* 跨域、STORAGE_* 文件存储、RATE_LIMITER_* 限流、EMAIL_* 邮件、WEBSOCKETS_* 实时推送、ACCESS_TOKEN_TTL/REFRESH_TOKEN_TTL 令牌有效期、ADMIN_* 初始账号、KEY/SECRET/PUBLIC_URL 项目级三项。

四、参数总览

下表汇总本文涉及的核心变量（默认值取自官方 configuration 文档页与实测观察，标「实测」的为本次环境验证过的）：

关键解读：Directus 的「缓存」「跨域」「实时」默认全部关闭，按需打开；CACHE_* 中真正影响数据读取的是 CACHE_ENABLED + CACHE_TTL + CACHE_AUTO_PURGE 三件套，后文逐组实测。

五、KEY 与 SECRET：项目标识与签名密钥

5.1 参数说明

• KEY：项目唯一标识，参与缓存键等场景的隔离；多项目共用一套缓存/数据库时必须互不相同；
• SECRET：登录态（access_token JWT、会话）的签名密钥，是整个实例最敏感的值——泄露等于任何人可伪造管理员登录态；生产必须为随机值（如 openssl rand -hex 32 生成）。

两者一旦上线就不要再改：SECRET 更换会让全部已签发登录态失效。

5.2 实测：更换 SECRET 后旧令牌立即失效

先用原 SECRET 登录拿到 token，再把 compose 中 SECRET 临时改为 c1-test-secret-temp-value 并 docker compose up -d directus，用旧 token 请求：

curl -s http://127.0.0.1:8103/users/me -H "Authorization: Bearer $TOKEN" -w "\nHTTP %{http_code}\n"

实测回显：

{"errors":[{"message":"Invalid token.","extensions":{"code":"INVALID_TOKEN"}}]}

HTTP 403

要点：旧 token 立即被拒，错误码 INVALID_TOKEN，HTTP 状态是 403（不是 401）。新 SECRET 下重新登录返回 200，链路正常。改回原值后无需任何清理即可继续用原账号登录。

💡 技术拓展：令牌校验失败时 Directus 返回 401 与 403 有明确分工——没有凭证或 refresh 失效多为 401（INVALID_CREDENTIALS），凭证带了但校验不过（如 SECRET 轮换后的旧 JWT）返回 403 INVALID_TOKEN。做网关/客户端重试逻辑时应把 403 INVALID_TOKEN 当作「必须重新登录」处理。

六、数据库连接参数 DB_*

6.1 参数清单

💡 技术拓展：连接信息有两种写法——离散 DB_* 变量与整体 DB_CONNECTION_STRING。连接串便于从环境密钥管理器整体注入，离散变量便于逐项覆盖与阅读；两者同时配置时以连接串优先。

6.2 实测：口令错误启动失败实录

把 DB_PASSWORD 临时改为 wrong-pass-123 后 docker compose up -d directus，应用反复崩溃重启，日志实测：

error: password authentication failed for user "directus"
    at parseErrorMessage (/directus/node_modules/.pnpm/pg-protocol@1.16.0/node_modules/pg-protocol/dist/parser.js:306:11)
    at Parser.handlePacket (/directus/node_modules/.pnpm/pg-protocol@1.16.0/node_modules/pg-protocol/dist/parser.js:143:27)

    routine: 'auth_failed'
error: password authentication failed for user "directus"

服务状态实测：

Restarting (1) 1 second ago

定位要点：PostgreSQL 原生错误 password authentication failed + routine: 'auth_failed' 直接给出根因；状态 Restarting (1) 表示崩溃循环。改回正确口令后一次拉起（/server/ping 200）。

⚠️ 注意：若改的是数据库侧 POSTGRES_PASSWORD，在数据目录已初始化的前提下不会生效（该变量只在空数据目录首次启动时建账号），需进库执行 ALTER USER，详见第十三章 FAQ。

七、ADMIN_*：初始管理员账号

7.1 参数说明

• ADMIN_EMAIL / ADMIN_PASSWORD：仅在首次初始化（数据目录为空、系统表刚装好）时用于创建第一个管理员；密码最短 8 位；
• 实例部署后没有「浏览器安装向导」——初始账号完全由这两个变量决定，不配置则首次启动后没有管理员可登录。

7.2 实测：二次启动改值不生效

把 compose 中 ADMIN_PASSWORD 改为 changed-but-ignored 并重启应用，分别用新旧两个口令登录：

curl -s -X POST http://127.0.0.1:8103/auth/login -H 'Content-Type: application/json' \
  -d '{"email":"admin@example.com","password":"q1w2e3r4"}' -o /dev/null -w '旧口令 HTTP %{http_code}\n'
curl -s -X POST http://127.0.0.1:8103/auth/login -H 'Content-Type: application/json' \
  -d '{"email":"admin@example.com","password":"changed-but-ignored"}' -o /dev/null -w '新变量值 HTTP %{http_code}\n'

实测回显：

旧口令 HTTP 200
新变量值 HTTP 401

结论：ADMIN_* 只在首次初始化写库，之后改环境变量对账号无任何影响——排障时不要试图靠改它来「找回密码」。

7.3 正确的密码重置方式

用镜像内置 CLI（注意 12.5 镜像内没有 npx，直接 node /directus/cli.js）：

cd /opt/data/quzuo/directus-12-5 && docker compose exec -T directus node /directus/cli.js users passwd \
  --email admin@example.com --password q1w2e3r4

实测回显：

[00:44:05.932] INFO: Extensions loaded
[00:44:06.050] INFO: Password is updated for user 7103b67b-b376-4ffb-ac0d-14c5ccfd17db

重置后立即登录验证通过（HTTP 200）。

八、缓存参数 CACHE_* 与 REDIS_*

8.1 参数清单

💡 技术拓展：缓存后端 memory 与 redis 的取舍——

后端	原理	适用
memory（默认）	进程内 Map	单实例、免依赖；重启即空、多实例不共享
redis	独立缓存服务	多实例共享、重启不丢、可观测（redis-cli 直接看键）；官方多实例部署的必需组件

本环境实际采用 redis：一方面为水平扩展预留，另一方面缓存键可直接观测，便于实测取证。

8.2 实测：缓存写入 Redis 与 TTL

管理员登录后连续请求同一数据端点，观察 Redis：

docker compose exec -T cache redis-cli dbsize
docker compose exec -T cache redis-cli TTL "sets:namespace:system-cache:system-cache:31dfefa0031a537f859d170f06a16df3739bbc99__expires_at"

实测回显：

6
198

键已落 Redis，TTL 198 秒（条目写入后剩余寿命），与官方默认 CACHE_TTL=5m（300 秒）一致——该键写于约 100 秒前。

8.3 实测：CACHE_STATUS_HEADER 让命中状态可见

默认配置下缓存命中对外不可见。临时在 compose 中加 CACHE_STATUS_HEADER: "X-Data-Cache" 并重启，用普通账号 viewer@example.com 连续请求同一端点：

curl -s -o /dev/null -D - "http://127.0.0.1:8103/items/articles?fields=id,title" -H "Authorization: Bearer $VTOKEN" | grep -i x-data-cache

实测回显（连续三次）：

X-Data-Cache: HIT
X-Data-Cache: HIT
X-Data-Cache: HIT

同一 URL 已被缓存，后续请求全部 HIT。管理员账号请求同样 HIT：

admin X-Data-Cache: HIT
admin X-Data-Cache: HIT
viewer X-Data-Cache: HIT

8.4 实测：CACHE_AUTO_PURGE 两种取值对比

取值 true（本环境默认）：管理员 PATCH 修改标题后，viewer 再查同一端点：

1) viewer GET(应 HIT):
X-Data-Cache: HIT
2) admin PATCH 修改标题:
PATCH 200
3) viewer GET(应 MISS 并返回新值):
X-Data-Cache: MISS
{"data":[{"id":1,"title":"缓存实测第四版"}]}

写操作自动清掉了相关缓存条目，下一次读 MISS 并从数据库取到新值——这正是 AUTO_PURGE 的语义：保持数据实时，同时享受连续读的缓存加速。

取值 false（对照实验）：把 AUTO_PURGE 改为 false 重启后重演「读→改→读」：

--- GET 写缓存(当前 v2):
{"data":[{"id":1,"title":"缓存实测第二版"}]}
--- PATCH 改 v3:
PATCH 200
--- AUTO_PURGE=false 后立即 GET:
{"data":[{"id":1,"title":"缓存实测第二版"}]}

PATCH 明明已改成第三版，读到的仍是缓存里的第二版（陈旧读）。false 模式下只能等 CACHE_TTL 到期。

8.5 缓存清理手段

陈旧读的恢复手段实测（清空 Redis 缓存，缓存重建不影响数据库数据）：

docker compose exec -T cache redis-cli flushall
docker compose exec -T cache redis-cli dbsize

实测回显：

OK
0

随后再读同端点，返回数据库中的最新值，dbsize 恢复增长（实测 3）。

⚠️ 注意：flushall 会连系统缓存（schema/权限）一并清掉，Directus 会自动重建，属安全操作；生产可改用 redis-cli --scan --pattern 'sets:namespace:system-cache:*' | xargs redis-cli del 做定向清理。

九、CORS 跨域参数

9.1 参数清单

9.2 实测：CORS_ORIGIN=true 反射来源

curl -s -o /dev/null -D - http://127.0.0.1:8103/server/ping -H 'Origin: http://192.168.1.100' | grep -i access-control

实测回显：

Access-Control-Allow-Origin: http://192.168.1.100
Access-Control-Allow-Credentials: true
Access-Control-Expose-Headers: Content-Range

CORS_ORIGIN: true 把任意来源反射进 Access-Control-Allow-Origin，同时按官方默认值回带 Allow-Credentials 与 Expose-Headers。生产建议把 CORS_ORIGIN 收敛为确定的前端域名白名单，避免「任意源 + 允许凭证」的宽松组合。

十、文件存储参数 STORAGE_*

10.1 参数说明

Directus 文件存储采用「多位置（location）适配器」模型：

• STORAGE_LOCATIONS：启用的位置名列表，默认 local；
• STORAGE_LOCAL_DRIVER / STORAGE_LOCAL_ROOT：local 位置的驱动与根目录，默认 local / /directus/uploads（即 compose 挂载的 ./uploads）；
• 每个位置可换驱动：STORAGE_<位置>_DRIVER 支持 local / s3 / gcs / azure / cloudinary，对象存储类还需配 STORAGE_S3_BUCKET、STORAGE_S3_REGION、STORAGE_S3_ACCESS_KEY_ID、STORAGE_S3_SECRET_ACCESS_KEY 等。

💡 技术拓展：文件存储驱动怎么选——

驱动	原理	适用
local（默认）	写实例本地目录	单实例；需自行做目录级备份
s3 / gcs / azure	对象存储 SDK 直传	多实例共享文件、大容量、免本地盘
cloudinary	云端图片处理服务	依赖云端裁剪/转码能力时

本环境实际采用 local：单实例部署，且 uploads 目录已 bind mount 到宿主固定路径，备份与排查都直观；多实例或容器编排环境下应改用 S3 系对象存储。

10.2 实测：本地上传落盘与回读

上传一个文本文件：

printf 'Directus C1 upload test 2026-10-19\n' > /tmp/c1-upload.txt
curl -s -X POST http://127.0.0.1:8103/files -H "Authorization: Bearer $TOKEN" -F "file=@/tmp/c1-upload.txt" \
  | python3 -c "import json,sys; d=json.load(sys.stdin)['data']; print(json.dumps({k:d[k] for k in ('id','title','filename_download','filesize','type','storage')}, ensure_ascii=False))"

实测回显：

{"id": "fba3d2d4-8fb5-4bf5-8076-d7010209dd4b", "title": "C1 Upload", "filename_download": "c1-upload.txt", "filesize": "35", "type": "text/plain", "storage": "local"}

storage: local 说明走了本地驱动。落盘核对（文件以 UUID 命名落进挂载目录）：

find /opt/data/quzuo/directus-12-5/uploads -type f

实测回显：

/opt/data/quzuo/directus-12-5/uploads/fba3d2d4-8fb5-4bf5-8076-d7010209dd4b.txt

内容回读核对（/assets/<id> 端点）：

curl -s "http://127.0.0.1:8103/assets/fba3d2d4-8fb5-4bf5-8076-d7010209dd4b" -H "Authorization: Bearer $TOKEN"

实测回显：

Directus C1 upload test 2026-10-19

上传→落盘→回读内容一致，本地存储链路完整。

十一、其他常用参数

PUBLIC_URL 与 WEBSOCKETS_ENABLED 的生效证据（本环境启动日志实测）：

[00:37:50.320] INFO: GraphQL Subscriptions started at 0.0.0.0:8055/graphql
[00:37:50.321] INFO: WebSocket Server started at 0.0.0.0:8055/websocket
[00:37:50.321] INFO: Logs WebSocket Server started at ws://0.0.0.0:8055/websocket/logs

十二、生产配置模板

适用场景：2 vCPU / 4GB 内存 / SSD 的单实例内容站点或内部数据平台（公网域名对外）。在 compose 的 environment: 段替换/补充以下变量：

      KEY: "<openssl rand -hex 32 生成>"
      SECRET: "<openssl rand -hex 32 生成，与 KEY 不同>"
      PUBLIC_URL: "https://cms.example.com"
      DB_CLIENT: "pg"
      DB_HOST: "db"
      DB_PORT: "5432"
      DB_DATABASE: "directus"
      DB_USER: "directus"
      DB_PASSWORD: "<openssl rand -hex 16 生成>"
      CACHE_ENABLED: "true"
      CACHE_STORE: "redis"
      CACHE_TTL: "10m"
      CACHE_AUTO_PURGE: "true"
      REDIS_HOST: "cache"
      REDIS_PORT: "6379"
      CORS_ENABLED: "true"
      CORS_ORIGIN: "https://www.example.com,https://app.example.com"
      RATE_LIMITER_ENABLED: "true"
      EMAIL_TRANSPORT: "smtp"
      EMAIL_SMTP_HOST: "smtp.example.com"
      EMAIL_SMTP_PORT: "465"
      EMAIL_SMTP_USER: "noreply@example.com"
      EMAIL_SMTP_PASSWORD: "<邮箱授权码>"
      WEBSOCKETS_ENABLED: "false"

逐项理由：KEY/SECRET 换随机值（第五章实测证明 SECRET 泄露的后果）；CACHE_TTL 从默认 5m 放宽到 10m，读多写少场景命中率更高（AUTO_PURGE 保证写后实时）；CORS_ORIGIN 收敛白名单（第九章实测证明 true 会反射任意来源）；限流打开抵御暴力登录；邮件走 SMTP 使密码找回可用；不需要 Realtime 就关 WebSocket 减少攻击面。

十三、常见问题

13.1 改了 POSTGRES_PASSWORD 但连接仍失败

数据库侧 POSTGRES_PASSWORD 只在空数据目录首次启动时创建账号；数据目录已初始化后再改无效。处理：进库改密 docker compose exec -T db psql -U directus -d directus -c "ALTER USER directus WITH PASSWORD '新口令';"，再同步改应用的 DB_PASSWORD。

13.2 开了缓存但读到旧数据

CACHE_AUTO_PURGE=false 时写操作不清缓存，读端点在 TTL 内返回旧值（第八章 8.4 实测复现）。处理：开启 AUTO_PURGE，或临时 redis-cli flushall 立即恢复。

13.3 SECRET 可以随意换吗

不可以当常规运维操作。SECRET 每次更换，全部用户（含管理员）登录态立即失效并收到 403 INVALID_TOKEN（第五章实测），需全员重新登录。仅在密钥泄露等安全事件时更换。

13.4 环境变量写了却不生效

三种常见原因：变量名拼错（Directus 对未知变量不报错）；改的是数据库侧初始变量但库已初始化（ADMIN_*/POSTGRES_PASSWORD 同理）；改完没有 docker compose up -d 重建应用（restart 不重读 environment 变更，需要 up 重建）。核对生效值用 docker compose exec -T directus env（第三章实测）。

十四、参考链接

• 《Directus Docker Compose 部署指南》——本实例的完整部署过程
• 《Directus 12.5 介绍与选型指南》——产品定位与选型
• 《Directus 12.5 API 使用详解》——API 实操
• 官方配置参考：https://directus.com/docs/configuration
• 官方缓存配置：https://directus.com/docs/configuration/cache
• 自托管总览：https://directus.com/docs/self-hosting/overview
• 环境要求：https://directus.com/docs/self-hosting/requirements