管理面板配置

页面摘要： /config/admin 中的选项可用于调整管理面板的行为和服务器设置，包括自定义 URL、主机（host）和端口（port）。

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

本页面充当 /config/admin 文件中所有配置参数和取值的参考，按主题分组。如需了解各功能的具体工作方式，请参阅每个小节开篇给出的链接。

管理面板行为

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

详见 此处（属性 ignored）。 | array(string) | [] | | serveAdminPanel | 如果为 false，将不提供管理面板，且启动时不需要 auth.secret。

注意：index.html 仍会被提供。 | boolean | true |

const config = {
  // … other customization options go here
  tutorials: false,
  notifications: { releases: false },
};

export default {
  config,
};

管理面板服务器

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

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

例如：/dashboard 会使管理面板可通过 http://localhost:1337/dashboard 访问。 | string | /admin | | host | 管理面板服务器的主机。 | string | localhost | | port | 管理面板服务器的端口。 | string | 8000 |

仅更新管理面板的路径

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

module.exports = ({ env }) => ({
  // … other configuration properties
  url: "/dashboard",
});

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

由于默认情况下后端服务器和管理面板服务器运行在相同的主机和端口上，只要你在后端服务器配置文件中未改动 host 和 port 属性值，仅更新 config/admin 文件即可生效。

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

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

JavaScript

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

TypeScript

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

开发期间信任额外主机

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

Strapi 如何加载自定义 Vite 配置

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

允许额外主机

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

JavaScript

import { mergeConfig } from 'vite';

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

TypeScript

import { mergeConfig, type UserConfig } from 'vite';

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

配置 allowedHosts 时的几个提示：

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

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

部署在不同服务器上 {#deploy-on-different-servers}

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

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

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

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

JavaScript

module.exports = ({ env }) => ({
  host: env("HOST", "0.0.0.0"),
  port: env.int("PORT", 1337),
  url: "http://yourbackend.com",
});

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

TypeScript

export default ({ env }) => ({
  host: env("HOST", "0.0.0.0"),
  port: env.int("PORT", 1337),
  url: "http://yourbackend.com",
});

export default ({ 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
});

使用此配置：

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

API 令牌

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

审计日志

审计日志功能可通过以下参数进行配置：

自托管用户与 Strapi Cloud 客户的行为不同，请参阅表下方的说明。 | integer | 90 | | auditLogs.exportMaxRows | 单次 CSV 导出中包含的最大条目数 （v5.53+） | integer | 1000000 |

身份验证

身份验证系统，包括 SSO 配置和会话管理，可通过以下参数进行配置：

基础身份验证

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

会话管理还提供了额外的配置参数。

会话管理

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

会话管理通过使用短生命周期访问令牌与较长生命周期刷新令牌配对，为 Strapi 应用程序中的身份验证提供了增强的安全性。这种方式降低了令牌被盗的风险，并允许对用户会话进行更精细的控制。

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

• 用于 API 请求的短生命周期访问令牌（通常为 30 分钟）
• 用于获取新访问令牌的刷新令牌
• 用于定向登出的设备级会话
• 可针对不同安全需求配置的令牌生命周期

已过期的访问令牌不会结束管理员会话。在 Strapi （v5.54.0+） 中，闲置超过 accessTokenLifespan 的标签页会保持打开，保留任何未保存的工作，下一次请求会在用户无感知的情况下续期令牌。结束会话的是刷新窗口：下面的 idleSessionLifespan 和 maxSessionLifespan，或者从 Sessions 页面撤销的会话。管理面板仅在这些情况下以及用户登出时才会警告未保存的更改。

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

Cookie 配置

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

内容历史

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

该值只能缩短保留期，请参阅表下方的说明。 | integer | Defined by the license |

功能标记

功能标记可通过以下参数进行配置：

忘记密码

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

速率限制

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

Strapi AI （新增） {#strapi-ai}

Strapi AI 为内容类型构建器和媒体库添加了功能，适用于 （Growth 计划） 套餐，可以启用或禁用：

传输令牌

数据传输功能的传输令牌可通过以下参数进行配置：

如果未定义传输令牌盐，传输功能将被禁用。 | string | a random string |

配置示例

/config/admin 文件至少应包含包含身份验证和 API 令牌所需参数的最小配置。也可以包含额外参数以构成完整配置。

Minimal configuration

默认配置创建于任何新项目，应至少包含以下内容：

JavaScript

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

TypeScript

export default ({ 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'),
    } 
  },
});

Full configuration

JavaScript

module.exports = ({ env }) => ({
  apiToken: {
    salt: env('API_TOKEN_SALT', 'someRandomLongString'),
    secrets: {
      encryptionKey: env('ENCRYPTION_KEY'),
    },
  },
  ai: {
    enabled: false, // use this to disable Strapi AI
  },
  auditLogs: { // only accessible with an Enterprise plan
    enabled: env.bool('AUDIT_LOGS_ENABLED', true),
    retentionDays: 120,
  },
  auth: {
    events: {
      onConnectionSuccess(e) {
        console.log(e.user, e.provider);
      },
      onConnectionError(e) {
        console.error(e.error, e.provider);
      },
    },
    options: {
      expiresIn: '7d',
    },
    secret: env('ADMIN_JWT_SECRET', 'someSecretKey'),
    sessions: {
      accessTokenLifespan: 1800, // 30 minutes
      maxRefreshTokenLifespan: 2592000, // 30 days
      idleRefreshTokenLifespan: 604800, // 7 days
      maxSessionLifespan: 604800, // 7 days
      idleSessionLifespan: 3600, // 1 hour
    },
    cookie: {
      domain: env('ADMIN_COOKIE_DOMAIN'),
      path: '/admin',
      sameSite: 'lax',
    },
  },
  history: { // only accessible with a Growth or Enterprise plan
    retentionDays: 30,
  },
  url: env('PUBLIC_ADMIN_URL', '/dashboard'),
  autoOpen: false,
  watchIgnoreFiles: [
    './my-custom-folder', // Folder
    './scripts/someScript.sh', // File
  ],
  host: 'localhost',
  port: 8003,
  serveAdminPanel: env.bool('SERVE_ADMIN', true),
  forgotPassword: {
    from: 'no-reply@example.com',
    replyTo: 'no-reply@example.com',
  },
  rateLimit: {
    interval: { hour: 1, min: 30 },
    timeWait: 3*1000,
    max: 10,
  },
  transfer: { 
    token: { 
      salt: env('TRANSFER_TOKEN_SALT', 'anotherRandomLongString'),
    } 
  },
});

TypeScript

export default ({ env }) => ({
  apiToken: {
    salt: env('API_TOKEN_SALT', 'someRandomLongString'),
    secrets: {
      encryptionKey: env('ENCRYPTION_KEY'),
    },
  },
  ai: {
    enabled: false, // use this to disable Strapi AI
  },
  auditLogs: { // only accessible with an Enterprise plan
    enabled: env.bool('AUDIT_LOGS_ENABLED', true),
    retentionDays: 120,
  },
  auth: {
    events: {
      onConnectionSuccess(e) {
        console.log(e.user, e.provider);
      },
      onConnectionError(e) {
        console.error(e.error, e.provider);
      },
    },
    options: {
      expiresIn: '7d',
    },
    secret: env('ADMIN_JWT_SECRET', 'someSecretKey'),
    sessions: {
      accessTokenLifespan: 1800, // 30 minutes
      maxRefreshTokenLifespan: 2592000, // 30 days
      idleRefreshTokenLifespan: 604800, // 7 days
      maxSessionLifespan: 604800, // 7 days
      idleSessionLifespan: 3600, // 1 hour
    },
    cookie: {
      domain: env('ADMIN_COOKIE_DOMAIN'),
      path: '/admin',
      sameSite: 'lax',
    },
  },
  history: { // only accessible with a Growth or Enterprise plan
    retentionDays: 30,
  },
  url: env('PUBLIC_ADMIN_URL', '/dashboard'),
  autoOpen: false,
  watchIgnoreFiles: [
    './my-custom-folder', // Folder
    './scripts/someScript.sh', // File
  ],
  host: 'localhost',
  port: 8003,
  serveAdminPanel: env.bool('SERVE_ADMIN', true),
  forgotPassword: {
    from: 'no-reply@example.com',
    replyTo: 'no-reply@example.com',
  },
  rateLimit: {
    interval: { hour: 1, min: 30 },
    timeWait: 3*1000,
    max: 10,
  },
  transfer: { 
    token: { 
      salt: env('TRANSFER_TOKEN_SALT', 'anotherRandomLongString'),
    } 
  },
});