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",
});

由于默认情况下后端服务器和管理面板服务器运行在相同的主机和端口上，如果你在后端服务器配置文件中保持 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 Cloud 客户，行为有所不同，请参阅表格下方的注释。		整数90
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.

身份验证​

🌐 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.options.expiresInjsonwebtoken 中使用的 JWT 过期时间对象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.

Serve the admin panel over HTTPS

自 v5.24.0 起，Strapi 将管理员身份验证数据存储在安全的仅 HTTP Cookie 中。浏览器仅在 HTTPS 连接上接受和发送这些 Cookie，因此通过普通 HTTP 访问管理面板会导致无法设置会话 Cookie，从而导致登录失败。在生产环境中始终通过 HTTPS 暴露管理面板（例如，将 Strapi 放在终止 TLS 的代理或负载均衡器之后）。在本地开发环境中，由于 Cookie 在该环境中未标记为安全，因此默认配置仍然可以正常工作。

🌐 Since v5.24.0, Strapi stores admin authentication data in secure, HTTP-only cookies. Browsers only accept and send these cookies over HTTPS connections, so attempting to access the admin panel via plain HTTP prevents the session cookie from being set and results in failed logins. Always expose the admin panel through HTTPS in production (for example, by placing Strapi behind a TLS-terminating proxy or load balancer). Local development continues to work with the default configuration because cookies are not marked as secure in that environment.

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

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

New projects

使用 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.

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

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

🌐 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小时）

🌐 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.pathCookie 路径字符串'/admin'
auth.cookie.sameSiteSameSite cookie attribute字符串'lax'

功能标记​

🌐 Feature flags

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

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

参数描述类型默认值
flags用于开启或关闭管理员的某些功能或元素的设置对象
flags.nps启用/禁用净推荐值（Net Promoter Score）弹出窗口布尔值true
flags.promoteEE启用/禁用 Strapi 企业版功能推广布尔值true

忘记密码​

🌐 Forgot password

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

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

参数描述类型默认值
forgotPassword自定义忘记密码邮件的设置对象
forgotPassword.emailTemplate邮件插件中定义的邮件模板对象默认模板
forgotPassword.from发件人邮箱地址字符串在
你的提供商配置中定义的默认值
forgotPassword.replyTo收件人被要求回复的默认地址或地址列表字符串在
你的提供商配置中定义的默认值

速率限制​

🌐 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，为内容类型构建器和媒体库添加功能，具有 GrowthThis feature is available with a Growth plan. 计划，可以启用或禁用：

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

转移令牌​

🌐 Transfer tokens

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

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

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

如果未定义传输令牌盐，则传输功能将被禁用。		字符串一个随机字符串
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.

配置示例​

🌐 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