Skip to main content

管理面板配置

🌐 Admin panel configuration

Page summary:

/config/admin中的选项允许你调整管理员面板的行为和服务器设置，包括自定义URL、主机和端口。

/config/admin 文件用于定义 Strapi 应用的 管理面板 配置。

🌐 The /config/admin file is used to define the admin panel configuration for the Strapi application.

本页面作为参考，列出了你可以在 /config/admin 文件中找到的所有配置参数和数值，并按主题分组。有关每个功能的工作原理的更多信息，请参阅各小节介绍中提供的链接。

🌐 The present page acts as a reference for all the configuration parameters and values that you can find in the /config/admin file, grouped by topic. For additional information on how each feature works, please refer to links given in the introduction of each sub-section.

管理面板行为​

🌐 Admin panel behavior

管理面板行为可以通过以下参数配置：

🌐 The admin panel behavior can be configured with the following parameters:

参数描述类型默认值
autoOpen启用或禁用启动时管理面板的开启。布尔值true
watchIgnoreFiles添加在开发期间不应被监视的自定义文件。

查看更多 here (属性 ignored)。		数组(字符串)[]
serveAdminPanel如果为 false，则管理面板不会被提供，并且启动时不需要 auth.secret。

注意：index.html 仍将被提供		布尔值true
config/admin vs. src/admin/app configurations

管理员面板的一些 UI 元素必须在 src/admin/app 文件中配置：

🌐 Some UI elements of the admin panel must be configured in the src/admin/app file:

教程视频 要禁用包含教程视频的信息框，请将 config.tutorials 键设置为 false。

发布通知 要禁用关于新 Strapi 版本的通知，请将 config.notifications.releases 键设置为 false。

/src/admin/app.js
const config = {
  // … other customization options go here
  tutorials: false,
  notifications: { releases: false },
};

export default {
  config,
};

管理面板服务器​

🌐 Admin panel server

默认情况下，Strapi 的管理面板通过 http://localhost:1337/admin 暴露。出于安全原因，主机、端口和路径可以更新。

🌐 By default, Strapi's admin panel is exposed via http://localhost:1337/admin. For security reasons, the host, port, and path can be updated.

管理面板的服务器配置可以使用以下参数进行配置：

🌐 The server configuration for the admin panel can be configured with the following parameters:

参数描述类型默认值
url访问管理员面板的路径。如果 URL 是相对路径，它将与服务器 URL 连接。

示例：/dashboard 使管理员面板可以通过 http://localhost:1337/dashboard 访问。		字符串/admin
host管理员面板服务器的主机。字符串localhost
port管理员面板服务器的端口。字符串8000
Note

如果你在 url 选项中添加路径，它不会为你的应用加前缀。要做到这一点，可以使用像 Nginx 这样的代理服务器（参见 可选软件部署指南）。

🌐 If you add a path to the url option, it won't prefix your application. To do so, use a proxy server like Nginx (see optional software deployment guides).

仅更新管理员面板的路径​

🌐 Update the admin panel's path only

要使管理员面板在另一个路径可访问，例如在 http://localhost:1337/dashboard，请定义或更新 url 属性：

🌐 To make the admin panel accessible at another path, for instance at http://localhost:1337/dashboard, define or update the url property:

/config/admin.js
module.exports = ({ env }) => ({
  // … other configuration properties
  url: "/dashboard",
});
Cookie path must match

自 Strapi 5.51 起，管理员认证 cookie 的路径无论 url 怎样都默认是 /admin。当你修改 url 时，也需要把 auth.cookie.path 设置成同样的值。否则管理员面板无法读取自己的认证 cookie：登录请求成功，但之后的每个请求都会被拒绝，面板会回到登录页且没有任何错误提示。

🌐 Since Strapi 5.51, the admin authentication cookie path defaults to /admin regardless of url. When you change url, also set auth.cookie.path to the same value. Otherwise the admin panel cannot read its own authentication cookie: the login request succeeds, every request after it is rejected, and the panel returns to the login page with no error.

/config/admin.js
module.exports = ({ env }) => ({
  url: "/dashboard",
  auth: {
    cookie: {
      path: "/dashboard", // must match url
    },
  },
});

在更改 auth.cookie.path 后，在启动 Strapi 之前重建管理员面板，因为这个值在构建时会内嵌到管理员包中。

🌐 After changing auth.cookie.path, rebuild the admin panel before starting Strapi, as this value is inlined into the admin bundle at build time.

由于默认情况下后端服务器和管理面板服务器运行在相同的主机和端口上，如果你在后端服务器配置文件中保持 host 和 port 属性值不变，只更新 config/admin 文件应该就可以工作。

🌐 Since by default the back-end server and the admin panel server run on the same host and port, only updating the config/admin file should work if you left the host and port property values untouched in the back-end server configuration file.

更新管理员面板的主机和端口​

🌐 Update the admin panel's host and port

如果管理面板服务器和后端服务器不托管在同一台服务器上，你将需要更新管理面板的主机和端口。例如，要将管理面板托管在 my-host.com:3000 上：

🌐 If the admin panel server and the back-end server are not hosted on the same server, you will need to update the host and port of the admin panel. For example, to host the admin panel on my-host.com:3000:

/config/admin.js
module.exports = ({ env }) => ({
  host: "my-host.com",
  port: 3000,
  // Additionally you can define another path instead of the default /admin one 👇
  // url: '/dashboard' 
});

在开发期间信任其他主机​

🌐 Trust additional hosts during development

当你运行 strapi develop 时，管理面板会通过 Strapi 在 中间件模式 下启动的 Vite 开发服务器提供服务，并通过 Koa 应用进行代理。默认情况下，Vite 会将 Host 头部与一小组安全值进行验证。不匹配的请求会被拒绝，并返回“Invalid Host”响应，这会阻止你在通过隧道、反向代理或自定义域访问时预览管理面板。Strapi 提供了 Vite 的 server.allowedHosts 选项，以便在必要时扩展该允许列表。

🌐 When you run strapi develop, the admin panel is served through a Vite development server that Strapi boots in middleware mode and proxies through the Koa app. By default, Vite validates the Host header against a small set of safe values. Requests that do not match are rejected with an "Invalid Host" response, which prevents you from previewing the admin panel when it is reached through a tunnel, reverse proxy, or custom domain. Strapi exposes Vite's server.allowedHosts option so that you can extend that allowlist when necessary.

Strapi 如何加载自定义 Vite 配置​

🌐 How Strapi loads custom Vite configuration

在开发过程中，Strapi 会构建一个基础的 Vite 配置，然后尝试从 ./src/admin/vite.config.{js,ts,mjs} 加载用户提供的配置。如果该文件导出了一个函数，它会以基础配置作为参数调用该函数，Strapi 会使用返回的值。项目模板附带了一个示例文件，该文件仅将自定义别名合并到提供的配置中，这对于你自己的覆盖操作是一个很好的起点。

🌐 During development Strapi builds a base Vite configuration, then tries to load a user-supplied config from ./src/admin/vite.config.{js,ts,mjs}. If the file exports a function it is invoked with the base configuration and Strapi uses the returned value. The project templates ship with an example file that simply merges a custom alias into the provided configuration, which is a good starting point for your own overrides.

允许额外的主机​

🌐 Allow additional hosts

如果 ./src/admin/vite.config.ts（或 .js）尚不存在，则创建它，并扩展开发服务器配置。以下示例片段在保持 Strapi 其余默认设置不变的同时，添加了 2 个自定义域名：

🌐 Create ./src/admin/vite.config.ts (or .js) if it does not already exist and extend the dev-server configuration. The following example snippet adds 2 custom domains while keeping the rest of Strapi's defaults untouched:

src/admin/vite.config.js
import { mergeConfig } from 'vite';

export default (config) => {
  return mergeConfig(config, {
    server: {
      allowedHosts: ['preview.my-app.test', '.example-proxy.internal'],
    },
  });
};

配置 allowedHosts 时的一些小提示：

🌐 A few tips while configuring allowedHosts:

  • 传递一个字符串数组或 'all'，匹配 Vite 接受的形状。
  • 前导点（.example.com）允许任何子域名。
  • 在通过重写端口的隧道访问管理面板时，将此选项与 Strapi 现有的 hmr.clientPort 设置结合使用。

保存文件后，重启 strapi develop。Vite 现在会信任其 Host 头与你提供的条目匹配的请求，因此通过代理或隧道的 URL 将可以加载，而不会触发主机验证错误。

🌐 After saving the file, restart strapi develop. Vite will now trust requests whose Host header matches the entries you provided, so proxied or tunneled URLs will load without triggering host validation errors.

在不同的服务器上部署​

🌐 Deploy on different servers

除非你选择将 Strapi 的后端服务器和管理面板服务器部署在不同的服务器上，否则默认情况下：

🌐 Unless you chose to deploy Strapi's back-end server and admin panel server on different servers, by default:

  • 后端服务器和管理面板服务器都运行在相同的主机和端口（http://localhost:1337/）
  • 管理面板可以通过 /admin 路径访问，而后端服务器可以通过 /api 路径访问

要将管理面板和后端部署在完全不同的服务器上，你需要配置服务器（/config/server）和管理面板（/config/admin-panel）的配置。

🌐 To deploy the admin panel and the back-end on completely different servers, you need to configure both the server (/config/server) and admin panel (/config/admin-panel) configurations.

以下示例设置允许你从一个域提供管理面板，而 API 在另一个域上运行：

🌐 The following example setup allows you to serve the admin panel from one domain while the API runs on another:

/config/server.js
module.exports = ({ env }) => ({
  host: env("HOST", "0.0.0.0"),
  port: env.int("PORT", 1337),
  url: "http://yourbackend.com",
});
/config/admin.js
module.exports = ({ env }) => ({
  /**
   * Note: The administration will be accessible from the root of the domain 
   * (ex: http://yourfrontend.com/)
   */ 
  url: "/",
  serveAdminPanel: false, // http://yourbackend.com will not serve any static admin files
});

使用此配置：

🌐 With this configuration:

  • 管理面板将在 http://yourfrontend.com 处可访问
  • 面板的所有 API 请求将发送到 http://yourbackend.com
  • 由于 serveAdminPanel: false，后端服务器将不会提供任何静态管理文件

API 令牌​

🌐 API tokens

API 令牌 功能可以通过以下参数进行配置：

🌐 The API tokens feature can be configured with the following parameters:

参数描述类型默认值
apiToken.salt用于生成 API 令牌的盐（适用于 content-api 和 admin 两种令牌类型）。字符串随机字符串
apiToken.secrets.encryptionKey用于在管理面板中设置 API 令牌可见性的加密密钥。设置后，令牌的所有者可以随时查看令牌密钥。字符串随机字符串
Tip

管理员令牌，是用于以编程方式访问管理员面板功能的新型 API 令牌，完全可以从管理员面板进行配置。除了上面的参数外，不需要额外的基于代码的配置（参见 管理员令牌）。

🌐 Admin tokens, the new kind of API token for programmatic access to the Admin pane features, are configured entirely from the admin panel. No additional code-based configuration is required beyond the parameters above (see Admin tokens).

审计日志​

🌐 Audit logs

可以使用以下参数配置 审核日志 功能：

🌐 The Audit Logs feature can be configured with the following parameters:

参数描述类型默认
auditLogs.enabled启用或禁用审计日志功能布尔值true
auditLogs.retentionDays审计日志的保存时长，以天为单位。

自托管与 Strapi 云客户的行为有所不同，请参见表格下方的备注.		整数90
auditLogs.exportMaxRows单次 CSV 导出包含的最大条目数 5.53+整数1000000
auditLogs.exportPartRows导出审核日志为 CSV 时每次请求获取的条目数。超过 100000 的值将被限制为 100000。 5.53+整数50000
Retention days for self-hosted vs. Strapi Cloud users

对于 Strapi Cloud 客户，除非在 config/admin.js|ts 配置文件中定义了一个 较小的 retentionDays 值，否则使用存储在许可信息中的 auditLogs.retentionDays 值。

🌐 For Strapi Cloud customers, the auditLogs.retentionDays value stored in the license information is used, unless a smaller retentionDays value is defined in the config/admin.js|ts configuration file.

Tip

导出审计日志需要 read 和 export 审计日志权限。可以在 设置 > 管理面板 > 角色 的审计日志部分授予这些权限。如果缺少任一权限，GET /admin/audit-logs/export 接口会返回 403。

🌐 Exporting audit logs requires the read and export Audit Logs permissions. Grant these under Settings > Administration Panel > Roles, in the Audit Logs section. The GET /admin/audit-logs/export endpoint returns a 403 if either permission is missing.

身份验证​

🌐 Authentication

身份验证系统，包括单点登录配置和会话管理，可以使用以下参数进行配置：

🌐 The authentication system, including SSO configuration and session management, can be configured with the following parameters:

基本认证​

🌐 Basic authentication

要配置基本身份验证，请使用以下参数：

🌐 To configure basic authentication, use the following parameters:

参数描述类型默认
auth认证配置对象-
auth.secret用于编码 JWT 令牌的秘密。当 serveAdminPanel 为 true（默认值）时必填。在使用 serveAdminPanel: false 运行的仅 API 部署可以省略。stringundefined
auth.domain在 cookie 中用于 SSO 认证的域 EnterpriseThis feature is available with an Enterprise plan. SSOThis feature is available with the SSO add-on.)字符串undefined
auth.providers用于 SSO 的身份验证提供商列表数组(对象)-
auth.options传递给 jsonwebtoken 的选项对象。

已弃用：请改用 auth.sessions.options 。		对象-
'auth.options.expiresIn'已弃用。不设置访问令牌的寿命（参见“auth.sessions.accessTokenLifespan”）。仅在“auth.sessions.maxRefreshTokenLifespan”和“auth.sessions.maxSessionLifespan”未设置时用作备份值，此时 Strapi 在启动时会记录弃用警告。字符串 |数字“30d”
auth.events记录所有订阅者注册认证的事件对象{}
auth.events.onConnectionSuccess当管理员用户成功登录管理面板时调用的函数函数undefined
auth.events.onConnectionError当管理员用户登录管理面板失败时调用的函数函数undefined

还有额外的配置参数可用于会话管理。

🌐 Additional configuration parameters are available for session management.

会话管理​

🌐 Session management

管理员身份验证默认使用会话管理以增强安全性。

🌐 Admin authentication uses session management by default for enhanced security.

会话管理通过使用短期有效的访问令牌配合长期有效的刷新令牌，为 Strapi 应用中的身份验证提供增强的安全性。这种方法降低了令牌被盗的风险，并允许对用户会话进行更细粒度的控制。

🌐 Session management provides enhanced security for authentication in Strapi applications by using short-lived access tokens paired with longer-lived refresh tokens. This approach reduces the risk of token theft and allows for more granular control over user sessions.

Serving the admin panel over HTTPS

自从 v5.24.0This feature requires Strapi version v5.24.0 or later.以来，Strapi 会把管理员的认证数据存储在安全的、仅限 HTTP 的 Cookie 中。浏览器只会在 HTTPS 连接上接受和发送这些 Cookie，所以如果通过普通的 HTTP 访问管理面板，session Cookie 就无法设置，登录也会失败。在生产环境中一定要通过 HTTPS 来暴露管理面板（例如，把 Strapi 放在一个终止 TLS 的代理或负载均衡器后面）。本地开发在默认配置下还能继续使用，因为在那个环境中 Cookie 并没有被标记为安全。

Strapi 的会话管理系统支持通过 用户与权限功能 进行管理面板身份验证和内容 API 身份验证。该系统提供：

🌐 Strapi's session management system supports both admin panel authentication and Content API authentication through the Users & Permissions feature. The system provides:

  • 用于 API 请求的短期访问令牌（通常为 30 分钟）
  • 用于获取新访问令牌的刷新令牌
  • 用于特定设备会话的定向注销
  • 可配置令牌有效期，以满足不同的安全要求

过期的访问令牌不会结束管理员会话。在 Strapi 中，空闲超过 accessTokenLifespan 的标签页会保持打开状态，保留任何未保存的工作，下一次请求会在用户不注意的情况下刷新令牌。真正结束会话的是刷新窗口：下面的 idleSessionLifespan 和 maxSessionLifespan，或者在会话页面撤销的会话。管理员面板只有在这些情况下，以及用户注销时，才会提醒有未保存的更改。

要配置会话生命周期和行为，请使用以下参数：

🌐 To configure session lifespans and behavior, use the following parameters:

参数描述类型默认
auth.sessions会话管理配置对象{}
auth.sessions.accessTokenLifespan访问令牌有效期（秒）数字1800（30分钟）
auth.sessions.maxRefreshTokenLifespan刷新令牌的最长有效期（秒）数字2592000（30天，或旧版 expiresIn 值）
auth.sessions.idleRefreshTokenLifespan空闲刷新令牌超时（秒）数字604800（7天）
auth.sessions.maxSessionLifespan会话最长持续时间（秒）数字2592000（30天，或者传统的 expiresIn 值）
auth.sessions.idleSessionLifespan会话空闲超时时间（秒）数字3600（1小时）
auth.sessions.options用于签名和验证管理员令牌时传递给 jsonwebtoken 的选项。会合并到已弃用的 auth.options 上。expiresIn 在令牌签发前会被剥离，所以它不会设置令牌有效期，但当 maxRefreshTokenLifespan 和 maxSessionLifespan 未设置时，仍会作为后备值读取。对象{}
auth.sessions.options.algorithm用于签署管理员令牌的算法（例如，HS256、RS256、ES256）。对称 HS* 算法使用 auth.secret 作为密钥。字符串HS256
auth.sessions.options.privateKey用于签署令牌的私钥。对于非对称算法（RS*、ES*、PS*）是必需的：没有它无法签署令牌，产生的错误会指向旧的 admin.auth.options.privateKey 路径。字符串-
auth.sessions.options.publicKey用于验证令牌的公钥。对于非对称算法（RS*、ES*、PS*）是必需的：没有它无法验证令牌，错误信息会指出旧的 admin.auth.options.publicKey 路径。字符串-
Notes

使用 create-strapi-app 架构的应用在生成的 config/plugins.* 文件中，Users & Permissions 功能默认设置了 jwtManagement: 'refresh' 和 sessions.httpOnly: true。这使得 Content API 用户可以开箱即用地使用基于刷新令牌的认证和仅限 HTTP 的会话 Cookie。

🌐 Apps scaffolded with create-strapi-app have jwtManagement: 'refresh' and sessions.httpOnly: true set by default for the Users & Permissions feature in the generated config/plugins.* file. This enables refresh-token-based authentication with HTTP-only session cookies for Content API users out of the box.

🌐 Cookie configuration

要配置用于管理员身份验证的 HTTP Cookie，请使用以下参数：

🌐 To configure HTTP cookies for admin authentication, use the following parameters:

参数描述类型默认
auth.cookie管理员身份验证的 Cookie 配置对象{}
auth.cookie.name管理员访问令牌 cookie 的名称。其值会被修剪并按照 RFC 6265 的 cookie 名称字符进行验证。无效值将回退到默认值。字符串'jwtToken'
auth.cookie.domainCookie 域（如果未设置则继承自服务器）字符串undefined
auth.cookie.path管理员认证 Cookie 的路径。如果未设置，access-token Cookie 会从 admin.url 派生，以便面板读取；refresh Cookie 仍保持在 /admin 用于认证端点。如果设置，则同时应用于两个 Cookie。两个 Cookie 都包含任何 server.url 子路径。如果配置的路径没有覆盖管理员 API，refresh Cookie 会被忽略并发出警告。字符串undefined（自动派生自 admin.url）
auth.cookie.sameSiteSameSite cookie attribute字符串'lax'
auth.cookie.secure管理员认证 Cookie 上是否设置了 Secure 属性。如果未设置，在生产环境的 HTTPS 下会自动启用；在生产环境将其设置为 false 会记录警告。布尔值undefined

内容历史​

🌐 Content history

内容历史 功能可以通过以下参数进行配置：

🌐 The Content History feature can be configured with the following parameter:

参数描述类型默认值
history.retentionDays历史版本保存的天数。

该值只能缩短保留周期，见表格下的说明。		整数由许可证定义
Retention days for Content History

history.retentionDays 值只有在它 小于 存储在许可信息中的值时才会被考虑。它不能用于将历史版本保存超过许可允许的时间。许可将保留期设置为 Growth 计划的 14 天和 Enterprise 计划的 30 天，在 Enterprise 计划中可以最多延长到 90 天（参见 内容历史）。

🌐 The history.retentionDays value is only taken into account if it is smaller than the value stored in the license information. It cannot be used to keep history versions for longer than the license allows. The license sets the retention period to 14 days on the Growth plan and 30 days on the Enterprise plan, where it can be raised up to a 90-day maximum (see Content History).

功能标记​

🌐 Feature flags

功能标志可以通过以下参数配置：

🌐 The feature flags can be configured with the following parameters:

参数描述类型默认值
flags用于开启或关闭管理后台的某些功能或元素的设置对象
flags.nps启用/禁用净推荐值弹窗布尔值true
flags.promoteEE启用/禁用 Strapi 企业版功能推广布尔值true
flags.docLinks启用/禁用管理面板中显示的文档链接布尔值true

忘记密码​

🌐 Forgot password

忘记密码功能，包括电子邮件模板，可以通过以下参数进行配置：

🌐 The forgot password functionality, including email templating, can be configured with the following parameters:

参数描述类型默认
forgotPassword用于自定义忘记密码邮件的设置对象
forgotPassword.emailTemplate邮件插件中定义的电子邮件模板对象默认模板
forgotPassword.from发件人邮箱地址字符串默认值在
你的服务提供商配置中定义
forgotPassword.replyTo默认地址或收件人需要回复的地址字符串默认值在
你的提供商配置中定义
'forgotPassword.expiresIn'密码重置令牌的存活时间。接受秒数或简写字符串（例如，''15m''， ''1h''）。配置在此选项之前发出的令牌被视为过期并被拒绝。字符串 |数字“'1h'”

速率限制​

🌐 Rate limiting

管理员面板的身份验证端点的速率限制可以通过以下参数进行配置。额外的配置选项来自 koa2-ratelimit 包：

参数描述类型默认
rateLimit用于自定义管理员面板身份验证端点速率限制的设置对象
rateLimit.enabled启用或禁用速率限制器布尔值true
rateLimit.interval请求被视为属于同一速率限制桶的时间窗口对象{ min: 5 }
rateLimit.max在时间窗口内允许的最大请求数整数5
rateLimit.delayAfter在延迟响应之前允许的请求次数整数1
rateLimit.timeWait响应请求前的等待时间（毫秒）整数3000
rateLimit.prefixKey限流键的前缀字符串${userEmail}:${ctx.request.path}:${ctx.request.ip}
rateLimit.whitelist要从速率限制中加入白名单的IP地址数组数组(字符串)[]
rateLimit.store速率限制存储位置（Memory、Sequelize 或 Redis）。更多信息请参见 koa2-ratelimit 文档对象MemoryStore

Strapi AI NewThis content is new.​

Strapi AI，为内容类型构建器、国际化和媒体库添加功能，可以启用或禁用。无论 Strapi AI 是由 Strapi 管理、使用 GrowthThis feature is available with a Growth plan. 计划，还是通过自带 AI 密钥插件在 EnterpriseThis feature is available with an Enterprise plan. 计划上运行，此设置都适用：

参数描述类型默认值
ai.enabledStrapi AI 是否启用布尔值true

转移令牌​

🌐 Transfer tokens

可以使用以下参数为 数据传输 功能配置令牌传输：

🌐 Transfer tokens for the Data transfer feature can be configured with the following parameters:

参数描述类型默认值
transfer.token.salt用于生成传输令牌的盐。

如果未定义传输令牌盐，则传输功能将被禁用。		字符串一个随机字符串

配置示例​

🌐 Configuration examples

/config/admin 文件至少应包含带有 身份验证 和 API 令牌 所需参数的最小配置。完整配置可以包含其他参数。

🌐 The /config/admin file should at least include a minimal configuration with required parameters for authentication and API tokens. Additional parameters can be included for a full configuration.

Note

环境配置（即使用 env() 助手）不需要包含所有值，只要它们存在于默认的 /config/server 中即可。

使用任何新项目创建的默认配置至少应包括以下内容：

🌐 The default configuration created with any new project should at least include the following:

/config/admin.js
module.exports = ({ env }) => ({
  apiToken: {
    salt: env('API_TOKEN_SALT', 'someRandomLongString'),
  },
  auditLogs: { // only accessible with an Enterprise plan
    enabled: env.bool('AUDIT_LOGS_ENABLED', true),
  },
  auth: {
    secret: env('ADMIN_JWT_SECRET', 'someSecretKey'),
  },
  transfer: { 
    token: { 
      salt: env('TRANSFER_TOKEN_SALT', 'anotherRandomLongString'),
    } 
  },
});

On this page