Yuxi 品牌自定义指南站点信息、登录协议与主题样式的完整配置方案【免费下载链接】Yuxi可私有部署的多租户知识智能体平台统一 RAG、知识图谱、多智能体、MCP/Skills、沙盒与权限管理。Self-hosted knowledge agent platform for RAG, knowledge graphs and multi-agent workflows.项目地址: https://gitcode.com/GitHub_Trending/yu/YuxiYuxi 是支持私有部署的多租户知识智能体平台其品牌信息分为后端读取的站点信息名称、Logo、协议链接与前端源码中的主题样式两个层面。本文基于 docs/advanced/branding.md 系统讲解如何通过 YAML 文件替换站点名称、Logo 与协议链接如何启用登录协议勾选以及如何调整主题色变量并结合仓库源码说明底层加载逻辑与部署生效方式。读完本文你将能够独立完成 Yuxi 从品牌文案到主题皮肤的完整定制。品牌配置的整体架构Yuxi 的品牌定制并不存在一个一键换肤的总开关而是由三个相互独立的配置面组成配置面载体作用对象生效方式站点信息info.local.yamlYAML后端/api/system/info接口重启 API / 重建容器主题样式base.css、base.dark.css、theme.js前端资源Vite 热更新 / 重建 Web 镜像协议页面web/public/protocols/*.template.html静态页面随 Web 资源发布修改其中任何一项都不会自动联动另一项这一点在定制时需要特别留意。下面的章节将逐一展开。配置站点信息YAML第一步创建本地配置文件仓库为品牌信息提供了模板文件 info.template.yaml。在开发环境中建议复制一份本地文件并在此基础上修改cp -n backend/package/yuxi/config/static/info.template.yaml \ backend/package/yuxi/config/static/info.local.yamlinfo.local.yaml通常是本地未跟踪文件位于.gitignore之外、不会被提交如果目标文件已经存在-n参数会避免覆盖它此时应直接编辑现有文件或先备份再覆盖。第二步理解 YAML 字段结构模板文件的完整结构如下每一层都有明确职责# 组织信息 organization: name: 语析 # 完整组织名称 logo: /favicon.svg # Logo文件路径放在 web/public 目录下 avatar: /favicon.svg # 头像文件路径放在 web/public 目录下 login_bg: /login-bg.jpg # 登录背景图片路径放在 web/public 目录下 # 项目信息 branding: name: Yuxi title: 让团队知识可连接让智能体可行动 # 系统标题 subtitle: 知识库 × 知识图谱 × 智能体 Harness开源且可私有部署 # 副标题subtitles 为空时使用 subtitles: - 知识与智能体真正协同每个回答都可溯源 - 从回答问题到交付任务工具与沙盒一站完成 - 多租户、权限与模型治理面向团队而非 Demo - Docker Compose 一键部署数据不出你的内网 # 页脚信息 footer: copyright: © 语析 2026 v{{YUXI_VERSION}} user_agreement_url: /protocols/user-agreement.template.html privacy_policy_url: /protocols/privacy-policy.template.html各字段的取值说明organization.name组织完整名称会出现在首页、登录页和侧边栏。organization.logo/organization.avatarLogo 与头像分别用于首页展示见 HomeView.vue和布局侧边栏见 AppLayout.vue。organization.login_bg登录页背景图前端在 LoginView.vue 中读取取不到时回退到/login-bg.jpg。branding.name应用品牌名。前端展示逻辑中若组织名与品牌名都存在且不同则优先展示品牌名否则取组织名或品牌名见 LoginView.vue。branding.title首页大标题branding.subtitle为副标题仅当subtitles列表为空时用作回退branding.subtitles支持多行轮换文案首页会按列表逐条渲染见 HomeView.vue。footer.copyright页脚版权文案可直接嵌入{{YUXI_VERSION}}版本占位符。footer.user_agreement_url/footer.privacy_policy_url用户协议与隐私政策页面地址控制登录协议勾选的显隐详见下文。第三步放置静态资源并填写路径图片与协议页面统一放在web/public目录下YAML 中的路径从网站根目录开始书写例如/logo.svg、/avatar.jpg、/login-bg.jpg。仓库自带的默认资源包括web/public/favicon.svgweb/public/avatar.jpgweb/public/login-bg.jpgweb/public/protocols/user-agreement.template.htmlweb/public/protocols/privacy-policy.template.html前端 Pinia store 在 info.js 中对organization、branding、footer三组字段做了默认值兜底即使接口返回缺字段也不会导致页面报错。第四步通过环境变量指定配置文件API 侧通过YUXI_BRAND_FILE_PATH环境变量定位品牌文件其加载逻辑在 system_router.py 的load_info_config()中实现读取环境变量YUXI_BRAND_FILE_PATH默认值为package/yuxi/config/static/info.local.yaml若该路径不存在则回退到info.template.yaml读取文件内容将{{YUXI_VERSION}}占位符替换为当前版本get_version()定义于 yuxi/init.py通过 YAML 解析后返回配置对象。docker-compose 中 API 容器的工作目录是/app因此默认配置路径可以写成YUXI_BRAND_FILE_PATHpackage/yuxi/config/static/info.local.yaml也可以在.env中设置绝对路径但文件必须挂载到 API 容器内。注意路径不存在时 API 只回退到模板不会把两个 YAML 文件合并——即你不能期望模板中没写的字段从本地文件补充本地文件必须自成完整配置。第五步让配置生效重新加载开发环境backend/package直接挂载进容器修改 YAML 后重启 API 即可docker compose restart api生产环境生产 Compose 不挂载仓库源码品牌 YAML 会在构建 API 镜像时复制进镜像。修改backend/package/yuxi/config/static/info.local.yaml后需要重新构建并重建 API/worker 容器docker compose --env-file .env.prod -f docker-compose.prod.yml \ up -d --build --force-recreate api worker如果使用仓库之外的品牌文件需要在 Compose 覆盖配置中把它只读挂载到 API 容器并让YUXI_BRAND_FILE_PATH指向容器内路径修改该环境变量后同样需要--force-recreate重建容器。第六步验证站点信息接口页面通过公开的/api/system/info接口读取站点信息前端封装见 system_api.js 的brandApi.getInfoConfig()由 info.js 的loadInfoConfig统一加载并合并并发请求。该接口无需登录即可访问对应的集成测试在 test_system_router_api.py 中验证了其公开性。此外接口还提供了管理员专用的POST /api/system/info/reload见 system_router.py用于不重启进程地重新加载品牌配置其权限与可用性同样有集成测试覆盖见 test_system_router_api.py。{{YUXI_VERSION}}占位符在加载时会被 API 替换为当前版本号。登录协议启用勾选与替换模板当footer.user_agreement_url和footer.privacy_policy_url同时有值时登录页和初始化页面会显示协议勾选项任一链接为空则不显示勾选项。前端判断逻辑在 LoginView.vueconst userAgreementUrl computed(() { return infoStore.footer?.user_agreement_url?.trim() || }) const privacyPolicyUrl computed(() { return infoStore.footer?.privacy_policy_url?.trim() || }) const showAgreementConsent computed(() { return Boolean(userAgreementUrl.value privacyPolicyUrl.value) })用户未勾选时登录或初始化会被页面拦截并提示先同意协议agreementAccepted状态控制提交。因此只配置其中一个链接并不会出现只勾一个协议的折中效果而是直接不显示勾选项。仓库提供两个可直接使用的协议模板web/public/protocols/user-agreement.template.htmlweb/public/protocols/privacy-policy.template.html模板内置了三个占位符{{ORG_NAME}}适用组织、{{PRODUCT_NAME}}产品名称、{{EFFECTIVE_DATE}}生效日期例如用户协议模板中的div classmeta适用组织{{ORG_NAME}} | 生效日期{{EFFECTIVE_DATE}}/div p欢迎使用 {{PRODUCT_NAME}}。在使用本平台提供的服务前请仔细阅读并充分理解本协议。/p替换模板内容后记得同步处理占位符也可以把 YAML 中的user_agreement_url/privacy_policy_url指向自定义的站内页面或站外合规页面。正式上线前请务必让法务审核协议文本。修改主题样式主题文件与变量体系主题样式涉及三个前端文件文件作用web/src/assets/css/base.css浅色模式主题变量与全局样式web/src/assets/css/base.dark.css暗色模式主题变量覆盖web/src/stores/theme.js主题选择器的默认配置与 Ant Design 主题 TokenYuxi 采用 CSS 变量驱动的主题体系。以浅色模式 base.css 为例主色是一个从深到浅的完整色阶:root { --main-1000: #01151f; --main-900: #023944; --main-800: #035065; --main-700: #046a82; --main-600: #24839a; --main-500: #3996ae; --main-400: #5faec2; --main-300: #82c3d6; --main-200: #a3d8e8; --main-100: #c4eaf5; --main-50: #e1f6fb; /* ... */ --main-color: var(--main-700); --main-bright: #0188a6; }暗色模式在 base.dark.css 中会对同一组变量做反相覆盖例如--main-1000: #e1f6fb、--main-color: #4a9fb8因此调整主色时浅色与暗色两套文件都要同步修改。必须同步theme.js中的 colorPrimary这是最容易踩坑的一步Ant Design 组件使用设计 Token而不是直接读取 CSS 变量。在 theme.js 的commonTheme.token中const commonTheme { token: { fontFamily: HarmonyOS Sans SC, Inter, -apple-system, ..., colorPrimary: #24839b, colorLink: var(--main-color), colorLinkHover: var(--main-600), colorLinkActive: var(--main-800), borderRadius: 8, wireframe: false } }其中colorPrimary是 Ant Design 组件的主色值与 CSS 变量各自独立存在。如果只修改 CSS 变量而不改colorPrimary会出现自定义组件已换色、Ant Design 组件仍是旧色的颜色不一致问题。建议的做法是先确定新的主色值同步更新colorPrimary与--main-*色阶中对应的基准色。对比度与状态色检查新增颜色或调整主色时要同时检查浅色、暗色、hover、focus、禁用和错误状态的对比度。Yuxi 的主题变量体系中还包含辅助暖金色系--second-*基准--second-500交互状态色如 hover 使用--main-600、active 使用--main-800分布在各组件样式中保证色阶完整才能让所有状态视觉协调。优先修改已有 CSS 变量不要在组件中散落新的硬编码颜色。生效方式开发环境Vite 会通过热更新HMR自动刷新样式修改base.css、base.dark.css或theme.js后无需重启。生产环境需要重新构建 Web 镜像docker compose -f docker-compose.prod.yml --env-file .env.prod \ up -d --build web主题选择器本身由theme.js管理默认浅色用户切换后写入localStorage的theme字段并通过document.documentElement上的darkclass 切换暗色变量见 theme.js。三个配置面的边界与最佳实践最后再次强调 Yuxi 品牌定制的核心边界品牌 YAML、主题颜色和图标/协议页面属于不同配置面——YAML 影响站点信息接口/api/system/infoCSS 与theme.js影响前端资源协议与图片属于静态资源。修改其中一项不会自动改动另一项也不会互相回退。一次完整的品牌定制通常按以下顺序推进复制info.template.yaml为info.local.yaml填写组织名、Logo、头像、登录背景与品牌文案将 Logo、头像、背景图与协议页面放入web/public并把 YAML 路径改为根路径形式按需替换协议模板内容与{{ORG_NAME}}、{{PRODUCT_NAME}}、{{EFFECTIVE_DATE}}占位符修改base.css与base.dark.css的主色色阶同时同步theme.js的colorPrimary开发环境docker compose restart api验证站点信息生产环境分别重建 API/worker 与 web 镜像。遵循这一流程即可在不改任何业务代码的前提下让 Yuxi 呈现完全属于自己团队的组织形象与视觉风格。【免费下载链接】Yuxi可私有部署的多租户知识智能体平台统一 RAG、知识图谱、多智能体、MCP/Skills、沙盒与权限管理。Self-hosted knowledge agent platform for RAG, knowledge graphs and multi-agent workflows.项目地址: https://gitcode.com/GitHub_Trending/yu/Yuxi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考