进阶 docs.pangolin.net 2026-11-21 15:06:37 · 2 阅读

第13章 Pangolin 品牌定制指南

品牌定制了解如何通过自定义品牌设置,个性化你的 Pangolin 仪表盘和登录页面的外观。

通过仪表盘进行组织级品牌定制,在 Pangolin Cloud 和自托管 Enterprise Edition 中均可用。privateConfig.yml 文件仅适用于自托管安装。

定制 Pangolin 品牌有两种方式:

在仪表盘中按组织设置。打开组织设置,使用"认证页面品牌"部分为该组织的登录页和资源认证页设置 logo、主色和标题。适用于 Pangolin Cloud 和自托管 Enterprise Edition。 在配置文件中对整个服务器设置。如果你是自托管用户,希望品牌设置作用于整个服务器(包括仪表盘本身),或需要更多控制选项(如配色方案、页脚和邮件样式),可以使用 privateConfig.yml。仅限自托管 Enterprise Edition。

组织级品牌定制 每个组织都可以为自己的登录页和资源认证页设置品牌。打开组织设置,进入 Authentication Pages,填写 Custom Branding 部分。这些设置仅对该组织生效,并会覆盖配置文件中的相关设置。

常规设置 主色(Primary Color):hex 颜色值 用于该组织登录页和资源认证页上按钮、链接和聚焦框的强调色,也会应用在该组织资源的浏览器端 SSH、RDP 和 VNC 页面上。填写 hex 格式颜色,如 #1d4ed8 或 #f60。默认值:#f36117

Logo URL:字符串 登录卡片顶部显示的 logo。在 Pangolin Cloud 中,填写可公开访问的图片 URL。在自托管 Enterprise Edition 中,也可以填写挂载到容器内的本地路径,如 /branding/acme-logo.svg。留空则不显示 logo。

宽度(px)/ 高度(px):整数 Logo 的显示尺寸,单位为像素。默认值:100 × 100

组织登录页 以下字段在 Pangolin Cloud 以及 app.identity_provider_mode 设为 "org" 的自托管安装中出现,用于控制组织自身登录页上的文字,用户通过组织的身份提供方在该页面登录。

标题:字符串 组织登录页的标题。{{orgName}} 会被替换为组织名称。默认值:Log in to {{orgName}}

副标题:字符串 标题下方的文字。{{orgName}} 会被替换为组织名称。默认值:Log in to {{orgName}}

资源认证页 这些字段控制用户访问受保护资源时看到的认证页面上的文字。

标题:字符串 资源认证页的标题。{{resourceName}} 会被替换为所访问资源的名称。默认值:Authenticate to Access {{resourceName}}

副标题:字符串 标题下方的文字。{{resourceName}} 会被替换为所访问资源的名称。默认值:Choose your preferred authentication method for {{resourceName}}

自定义 CSS 自定义 CSS 仅在自托管 Enterprise Edition 中可用。

在 Custom CSS 字段中粘贴样式表,即可重新设计组织的登录页和资源认证页样式。清空该字段即可移除自定义 CSS。字段最多接受 100,000 个字符。

组织登录页和资源认证页的内容(logo、登录卡片和链接)都包裹在一个 class 为 .branded-auth-surface 的元素中。你输入的 CSS 会添加到整个页面且不会被自动限定作用域,因此请以 .branded-auth-surface 作为选择器开头,只对登录内容生效,不影响页面其余部分(主题切换器和页脚)。

/* 登录卡片 */ .branded-auth-surface .rounded-lg.border { border-width: 2px; border-radius: 1rem; box-shadow: 0 20px 40px rgb(0 0 0 / 0.15); }

/* 卡片标题 */ .branded-auth-surface h3 { font-family: "Georgia", serif; font-size: 1.75rem; }

/* 按钮 */ .branded-auth-surface button { border-radius: 9999px; text-transform: uppercase; letter-spacing: 0.05em; }

/* 输入框 */ .branded-auth-surface input { border-radius: 0.75rem; }

/* 深色模式覆盖 */ .dark .branded-auth-surface .rounded-lg.border { box-shadow: 0 20px 40px rgb(0 0 0 / 0.5); }

要修改按钮和链接的强调色,请使用"主色"设置而非 CSS。它会直接设置 .branded-auth-surface 上的 --primary 变量,优先级高于样式表中的 --primary 值。

这些页面使用了工具类(如上文中的 .rounded-lg),它们可能随 Pangolin 版本更新而变化。建议优先使用元素选择器和 .branded-auth-surface,并在升级后检查样式效果。

移除品牌设置 点击 Remove Branding 可删除该组织的全部品牌设置,页面将恢复为服务器级品牌设置;若服务器级也未设置,则恢复为 Pangolin 默认样式。

你还可以通过自定义域名提供组织登录页。该功能配合组织级身份提供方使用效果最佳;否则页面上只会显示一个 Pangolin 凭证登录按钮,点击后跳转到主登录页。

服务器级品牌定制(自托管) 首先,在现有 config.yml 旁边创建 privateConfig.yml 文件:

privateConfig.yml branding: app_name: "MyApp" logo: light_path: "/branding/logo-light.svg" dark_path: "/branding/logo-dark.svg" colors: light: primary: "hsl(212, 65%, 35%)" ring: "hsl(212, 65%, 35%)" primary-foreground: "hsl(0 0% 98%)" dark: primary: "hsl(212, 65%, 45%)" ring: "hsl(212, 65%, 35%)" primary-foreground: "hsl(0 0% 98%)"

挂载品牌资源 对于 logo、背景图等图片资源,需要向 Pangolin 容器挂载卷,使应用能够访问它们:

docker-compose.yml volumes: - ./config:/app/config - ./branding:/app/public/branding

目录结构应如下所示:

. ├── config/ │ ├── config.yml │ └── privateConfig.yml └── branding/ ├── logo-light.svg ├── logo-dark.svg └── favicon.ico

配置参考 所有品牌配置项都是可选的,只需配置你想自定义的部分。

应用名称 app_name:字符串 应用名称,会显示在 UI 的多个位置。示例:"MyApp"

Favicon 要自定义 favicon,请将其挂载到容器的 /app/public/favicon.ico。

docker-compose.yml volumes: - ./config:/app/config - ./branding/favicon.ico:/app/public/favicon.ico

背景图 background_image_path:字符串 认证页面使用的自定义背景图路径。示例:"/branding/backgrounds/bg.png"。需要挂载卷到 /app/public。

颜色 colors:对象 自定义配色方案,覆盖 shadcn 组件默认的 Tailwind 样式。颜色可用 OKLCH 或 HSL 格式,分别作用于亮色和深色模式。

可用颜色属性包括:background、foreground、card、card-foreground、popover、popover-foreground、primary、primary-foreground、secondary、secondary-foreground、muted、muted-foreground、accent、accent-foreground、destructive、destructive-foreground、border、input、ring、radius,以及 chart-1 至 chart-5。

示例: colors: light: primary: "hsl(212, 65%, 35%)" background: "hsl(212, 65%, 35%)" foreground: "hsl(0 0% 98%)" dark: primary: "hsl(212, 65%, 45%)" background: "hsl(212, 65%, 35%)" foreground: "hsl(0 0% 98%)"

shadcn 组件使用的完整 Tailwind 颜色类列表,请参阅 shadcn/ui 文档。

Logo logo:对象 应用各部分的 logo 配置。

light_path:字符串 亮色模式下使用的 logo 图片路径。示例:"/branding/logo-light.svg"

dark_path:字符串 深色模式下使用的 logo 图片路径。示例:"/branding/logo-dark.svg"

auth_page:对象 认证页面的 logo 尺寸。

width:整数,logo 宽度(像素)。示例:200 height:整数,logo 高度(像素)。示例:80

navbar:对象 导航栏的 logo 尺寸。

width:整数,logo 宽度(像素)。示例:150 height:整数,logo 高度(像素)。示例:60

页脚 footer:对象数组 页面底部显示的自定义页脚链接。示例: footer: - text: "Privacy Policy" href: "https://example.com/privacy" - text: "Terms of Service" href: "https://example.com/terms"

text:字符串,页脚链接的显示文字。 href:字符串,页脚链接的 URL 或路径。

隐藏认证页页脚 hide_auth_layout_footer:布尔值 隐藏所有认证页面底部布局中的水平页脚文字。默认值:false

认证页自定义 CSS auth_page_custom_css:字符串 添加到所有认证页面的样式表,涵盖仪表盘登录页、注册页、密码重置页、组织登录页和资源认证页。最多 100,000 个字符。

使用 YAML 块标量(|)可以跨多行编写 CSS。示例: branding: auth_page_custom_css: | .auth-layout { background: linear-gradient(135deg, #0f172a 0%, #1e3a8a 100%); }

.auth-layout h3 { font-family: "Georgia", serif; letter-spacing: 0.02em; }

.auth-layout button { border-radius: 9999px; }

登录页 login_page:对象 登录页的自定义文字。

subtitle_text:字符串,标题下方显示的副标题。示例:"Sign in to continue to your account"

注册页 signup_page:对象 注册页的自定义文字。

subtitle_text:字符串,标题下方显示的副标题。示例:"Join us and get started today"

资源认证页 resource_auth_page:对象 用户访问受保护资源时看到的资源认证页配置。

show_logo:布尔值,是否在资源认证页显示 logo。默认值:true hide_powered_by:布尔值,是否隐藏资源认证页上的 "Powered by Pangolin" 文字。默认值:false title_text:字符串,资源认证页显示的主标题。示例:"Access Restricted" subtitle_text:字符串,标题下方显示的副标题。示例:"Please sign in to view this resource"

邮件 emails:对象 邮件自定义设置。

signature:字符串,附加在发出邮件末尾的自定义签名。示例:"Best regards,\nThe MyApp Team"。签名中的换行使用 \n。

colors:对象,邮件配色方案。

primary:字符串,邮件元素的主色。示例:"oklch(0.6717 0.1946 41.93)"

应用更改 创建或修改 privateConfig.yml 后,必须重启 Pangolin 容器才能使更改生效。

这个页面有帮助吗?

评论 (0)