配置选项 Config-Options

配置文件

默认情况下，Directus 将读取位于项目 package.json 旁边的 .env 文件(通常位于项目的根文件夹中)以进行配置。 您可以在启动 Directus 之前通过设置 CONFIG_PATH 环境变量来更改此路径和文件名。 例如：

CONFIG_PATH="/path/to/config.js" npx directus start

如果您更喜欢使用配置文件而不是环境变量，您还可以使用 CONFIG_PATH 环境变量来指示 Directus 使用本地配置文件而不是环境变量。 配置文件可以是以下格式之一：

• .env
• config.json
• config.yaml
• config.js

.env

如果配置路径没有文件扩展名，或者文件扩展名不是其他支持的格式之一，Directus 将尝试将文件配置路径读取为环境变量。 它具有以下结构：

HOST="0.0.0.0"
PORT=8055

DB_CLIENT="pg"
DB_HOST="localhost"
DB_PORT=5432

etc

config.json

如果您更喜欢使用单个 JSON 文件进行配置，请使用环境变量作为键创建 JSON 文件，例如：

CONFIG_PATH="/path/to/config.json"

{
  "HOST": "0.0.0.0",
  "PORT": 8055,

  "DB_CLIENT": "pg",
  "DB_HOST": "localhost",
  "DB_PORT": 5432

  // etc
}

config.yaml

与 JSON 类似，您可以在配置中使用 .yaml(或 .yml)文件：

CONFIG_PATH="/path/to/config.yaml"

HOST: 0.0.0.0
PORT: 8055

DB_CLIENT: pg
DB_HOST: localhost
DB_PORT: 5432
#
# etc

config.js

为您的配置使用 JavaScript 文件允许您在启动期间动态生成项目的配置。 JavaScript 配置支持两种不同的格式，一种是 Object Structure，其中键是环境变量名称：

// Object Syntax

module.exports = {
  HOST: '0.0.0.0',
  PORT: 8055,

  DB_CLIENT: 'pg',
  DB_HOST: 'localhost',
  DB_PORT: 5432,

  // etc
}

或者一个 功能结构 returns 与上述相同的对象格式。 该函数将 process.env 作为其参数。

// Function Syntax

module.exports = function (env) {
  return {
    HOST: '0.0.0.0',
    PORT: 8055,

    DB_CLIENT: 'pg',
    DB_HOST: 'localhost',
    DB_PORT: 5432,

    // etc
  }
}

环境变量文件

通过将 _FILE 附加到环境变量名称，可以从文件中导入任何环境变量值。 这在与 Docker Secrets 结合使用时特别有用，因此您可以将敏感数据排除在撰写文件之外。 例如：

DB_PASSWORD_FILE="/run/secrets/db_password"

类型转换和嵌套

环境变量会根据变量的结构自动进行类型转换，例如：

PUBLIC_URL="https://example.com"
// "https://example.com"

DB_HOST="3306"
// 3306

CORS_ENABLED="false"
// false

STORAGE_LOCATIONS="s3,local,example"
// ["s3", "local", "example"]

在环境变量被转换为第三方库使用的配置对象的情况下，例如在 DB_* 或 RATE_LIMITER_REDIS_* 中，环境变量将被转换为 camelCase。 您可以对嵌套对象使用双下划线 (__)：

DB_CLIENT="pg"
DB_CONNECTION_STRING="postgresql://postgres:example@127.0.0.1"
DB_SSL__REJECT_UNAUTHORIZED="false"

{
 client: "pg",
 connectionString: "postgresql://postgres:example@127.0.0.1",
 ssl: {
  rejectUnauthorized: false
 }
}

环境语法前缀

Directus 将尝试根据上下文线索自动键入转换环境变量。 如果您对给定类型有特定需求，您可以通过在值前加上“{type}:”来告诉 Directus 为给定值使用什么类型。 有以下类型可用：

General

服务器

数据库

安全性

散列

Directus 将 Argon2 的散列函数用于三个目的：1) 散列用户密码，2) 为集合中的 Hash 字段类型生成散列，以及 3) 生成散列 API 端点。

所有 HASH_* 环境变量参数都传递给 argon2.hash 函数。 请参阅 node-argon2 库选项页面 以供参考。

跨域

Rate Limiting

您可以使用内置的速率限制器来防止用户过多地访问 API。 简单地启用速率限制器将设置默认最大值为每秒 50 个请求，在内存中进行跟踪。 一旦您在负载均衡器下运行了多个 Directus 副本，或者您的用户群增长如此之快以至于内存不再是存储速率限制器信息的可行位置，您可以使用外部“memcache”或“redis”实例来存储 速率限制器数据。

根据使用的 RATE_LIMITER_STORE，您还必须提供以下配置：

内存

无需额外配置。

Redis

或者，您可以提供单独的连接参数：

Memcache

Example: Basic

// 10 requests per 5 seconds

RATE_LIMITER_POINTS="10"
RATE_LIMITER_DURATION="5"

Example: Redis

RATE_LIMITER_ENABLED="true"

RATE_LIMITER_POINTS="10"
RATE_LIMITER_DURATION="5"

RATE_LIMITER_STORE="redis"

RATE_LIMITER_REDIS="redis://@127.0.0.1"

# If you are using Redis ACL
RATE_LIMITER_REDIS_USERNAME="default"
RATE_LIMITER_REDIS_PASSWORD="yourRedisPassword"
RATE_LIMITER_REDIS_HOST="127.0.0.1"
RATE_LIMITER_REDIS_PORT=6379
RATE_LIMITER_REDIS_DB=0

Cache

Directus 有一个内置的数据缓存选项。 启用此功能会将请求的输出(基于当前用户和使用的确切查询参数)缓存到配置的缓存存储位置。 这极大地提高了 API 性能，因为后续请求直接从此缓存中提供。 启用缓存还将使 Directus 返回准确的缓存控制标头。 根据您的设置，这将通过在中间人服务器(如 CDN)甚至浏览器中缓存请求来进一步提高性能。

¹ CACHE_TTL 根据您项目的需要，您可能能够主动缓存您的数据，只需要大约每小时获取一次新数据。这使您可以从 Directus 实例中获得最大的性能。这对于您拥有大量(公共)读取访问权限且更新不是实时的应用程序(例如网站)非常有用。 CACHE_TTL 使用 ms 来解析该值，因此您可以使用人类可读的值(例如 2 days、7 hrs、 5m)。

² CACHE_AUTO_PURGE 允许您保持 Directus API 的实时性，同时仍然在快速后续读取时获得性能优势。

³ 不受 CACHE_ENABLED 值的影响。

⁴ CACHE_STORE 对于较大的项目，您很可能不想依赖本地内存进行缓存。相反，您可以使用上面的 CACHE_STORE 环境变量来使用 memcache 或 redis 作为缓存存储。根据选择的 CACHE_STORE，您还必须提供以下配置：

内存

无需额外配置。

Redis

或者，您可以提供单独的连接参数：

Memcache

文件存储

默认情况下，Directus 将所有上传的文件本地存储在磁盘上。 但是，您也可以将 Directus 配置为使用 S3、Google Cloud Storage 或 Azure。 您还可以同时配置_多个_存储适配器。 这使您可以逐个文件选择上传文件的位置。 在 Admin App 中，文件将自动上传到第一个配置的存储位置(在本例中为“本地”)。 使用的存储位置保存在 directus_files 中的 storage 下。

STORAGE_LOCATIONS="local"
STORAGE_LOCAL_ROOT="./uploads"

STORAGE_LOCATIONS="s3"
STORAGE_s3_DRIVER="s3" # Will not work, lowercase "s3" ❌

STORAGE_LOCATIONS="s3"
STORAGE_S3_DRIVER="s3" # Will work, "s3" is uppercased ✅

对于列出的每个存储位置，您必须提供以下配置：

根据您配置的驱动程序，您还必须提供以下配置：

Local (local)

S3 (s3)

Azure (azure)

Google Cloud Storage (gcs)

Example: 多个存储适配器

下面展示了存储位置名称的 CSV，每个名称都有一个配置块：

STORAGE_LOCATIONS="local,aws"

STORAGE_LOCAL_DRIVER="local"
STORAGE_LOCAL_ROOT="local"

STORAGE_AWS_KEY="tp15c...510vk"
STORAGE_AWS_SECRET="yk29b...b932n"
STORAGE_AWS_REGION="us-east-2"
STORAGE_AWS_BUCKET="my-files"

Metadata

上传图像时，Directus 会保留可用 EXIF 元数据中的 描述、标题和标签。 出于安全目的，必须配置额外元数据的收集：

¹：当文件具有异常大的元数据集时，提取所有元数据可能会导致内存问题

Assets

图像转换在内存使用方面可能相当繁重。 如果您使用的系统具有 1GB 或更少的可用内存，我们建议降低允许的并发转换，以防止您的服务器溢出。

Authentiaction

对于您列出的每个身份验证提供程序，您还必须提供以下配置：

根据身份验证驱动程序，您可能还需要指定其他变量。 请参阅下面的配置详细信息。

SAML

SAML 是一个开放标准、基于 XML 的身份验证框架，用于在两个实体之间进行身份验证和授权，无需密码。

• 服务提供者 (SP) 同意信任身份提供者对用户进行身份验证。
• 身份提供者 (IdP) 对用户进行身份验证并向服务提供者提供指示用户已通过身份验证的身份验证断言。

¹ 进行身份验证时，Directus 会将来自外部用户配置文件的标识符值匹配到 Directus 用户“外部标识符”。

SP_metadata 和 IDP_metadata 变量应该分别设置为服务提供者和身份提供者提供的 XML 元数据，或者可以设置为启动时获取的 URL。

本地(local)

默认 Directus 电子邮件/密码身份验证流程。

无需额外配置。

SSO (oauth2 and openid)

Directus 的 SSO 集成提供了强大的替代方法来验证您的项目。 Directus 将要求您登录外部服务，并返回通过与该服务链接的 Directus 帐户进行的身份验证。

例如，您可以通过在 GitHub 中创建 OAuth 2.0 应用程序 并在 Directus 中添加以下配置，使用 GitHub 帐户登录 Directus：

AUTH_PROVIDERS="github"

AUTH_GITHUB_DRIVER="oauth2"
AUTH_GITHUB_CLIENT_ID="99d3...c3c4"
AUTH_GITHUB_CLIENT_SECRET="34ae...f963"
AUTH_GITHUB_AUTHORIZE_URL="https://github.com/login/oauth/authorize"
AUTH_GITHUB_ACCESS_URL="https://github.com/login/oauth/access_token"
AUTH_GITHUB_PROFILE_URL="https://api.github.com/user"

更多示例 SSO 配置 可以在这里找到.

OAuth 2.0

¹ 进行身份验证时，Directus 会将来自外部用户配置文件的标识符值匹配到 Directus 用户“外部标识符”。

OpenID

OpenID 是基于 OAuth 2.0 构建的身份验证协议，应尽可能优先于标准 OAuth 2.0。

进行身份验证时，Directus 会将来自外部用户配置文件的标识符值匹配到 Directus 用户“外部标识符”。¹

sub 表示由 OpenID 提供者定义的唯一用户标识符。 对于不依赖PUBLIC_REGISTRATION的用户，建议使用人类可读的标识符，例如email。²

LDAP (ldap)

LDAP 允许 Active Directory 用户进行身份验证和使用 Directus，而无需手动配置。 用户信息和角色将从 Active Directory 分配。

绑定用户必须具有查询用户和组的权限才能执行身份验证。 匿名绑定可以通过为 BIND_DN 和 BIND_PASSWORD 设置一个空值来实现。 ¹

范围定义了以下行为：²

• base：将范围限制为由关联 DN 定义的单个对象。
• one：搜索关联 DN 中的所有对象。
• sub：搜索关联 DN 中的所有对象和子对象。
  如果指定了 GROUP_DN，则用户的角色将始终在验证到 AD 中配置的匹配组时更新，或回退到 DEFAULT_ROLE_ID。³

Example: LDAP

AUTH_PROVIDERS="ldap"

AUTH_LDAP_DRIVER="ldap"
AUTH_LDAP_CLIENT_URL="ldap://ldap.directus.io"
AUTH_LDAP_BIND_DN="CN=Bind User,OU=Users,DC=ldap,DC=directus,DC=io"
AUTH_LDAP_BIND_PASSWORD="p455w0rd"
AUTH_LDAP_USER_DN="OU=Users,DC=ldap,DC=directus,DC=io"
AUTH_LDAP_GROUP_DN="OU=Groups,DC=ldap,DC=directus,DC=io"

Example: 多个身份验证提供程序

您可以配置多个提供程序来处理 Directus 中的身份验证。 这允许登录时使用不同的选项。为此，请提供以逗号分隔的提供程序名称列表，以及每个提供程序的配置块：

AUTH_PROVIDERS="google,facebook"

AUTH_GOOGLE_DRIVER="openid"
AUTH_GOOGLE_CLIENT_ID="830d...29sd"
AUTH_GOOGLE_CLIENT_SECRET="la23...4k2l"
AUTH_GOOGLE_ISSUER_URL="https://accounts.google.com/.well-known/openid-configuration"
AUTH_GOOGLE_IDENTIFIER_KEY="email"
AUTH_GOOGLE_ICON="google"

AUTH_FACEBOOK_DRIVER="oauth2"
AUTH_FACEBOOK_CLIENT_ID="830d...29sd"
AUTH_FACEBOOK_CLIENT_SECRET="jd8x...685z"
AUTH_FACEBOOK_AUTHORIZE_URL="https://www.facebook.com/dialog/oauth"
AUTH_FACEBOOK_ACCESS_URL="https://graph.facebook.com/oauth/access_token"
AUTH_FACEBOOK_PROFILE_URL="https://graph.facebook.com/me?fields=email"
AUTH_FACEBOOK_ICON="facebook"

Flows

const axios = require('axios')

const publicUrl = data.$env.PUBLIC_URL
// OR
const publicUrl = data.$env.PUBLIC_URL
// OR
const publicUrl = process.env.PUBLIC_URL

Extensions

¹EXTENSIONS_CACHE_TTL 环境变量控制自定义应用程序扩展(例如，界面、显示、布局、模块、面板)被浏览器缓存多长时间。 缓存可以加快应用程序的加载速度，因为扩展代码不需要在每次应用程序重新加载时从服务器重新获取。 另一方面，这意味着在 EXTENSIONS_CACHE_TTL 过期之前，浏览器不会考虑对应用程序扩展的代码更改。 默认情况下，不缓存扩展。 此环境变量的输入数据类型与 CACHE_TTL 相同。

Messenger

或者，您可以提供单独的连接参数：

redis 应该用于 Directus 的负载平衡安装¹

Email

根据使用的 EMAIL_TRANSPORT，您还必须提供以下配置：

Sendmail (sendmail)

SMTP (smtp)

Mailgun (mailgun)

SendGrid (sendgrid)

AWS SES (ses)

管理员帐户

如果您依赖 Docker 和/或 directus bootstrap CLI 命令，可以传递以下两个环境变量来自动配置第一个用户：

遥测

为了更准确地衡量安装频率、版本碎片和用户群的总体规模，Directus 收集了关于您的环境的少量匿名数据。 您可以使用以下环境变量轻松选择退出：

限制和优化

允许您配置硬技术限制，以防止滥用并针对您的特定服务器环境进行优化。