自定义品牌信息

Yuxi 的品牌配置分为两部分：后端读取的站点信息，以及前端源码中的主题样式。前者可以通过 YAML 文件替换名称、Logo 和协议链接；后者需要修改前端资源。

配置站点信息

1. 创建本地配置

复制模板。info.local.yaml 通常是本地未跟踪文件；如果目标文件已经存在，不要覆盖它，直接编辑或先备份：

cp -n backend/package/yuxi/config/static/info.template.yaml \
  backend/package/yuxi/config/static/info.local.yaml

在 info.local.yaml 中修改：

organization:
  name: "Example Organization"
  logo: "/logo.svg"
  avatar: "/avatar.jpg"
  login_bg: "/login-bg.jpg"

branding:
  name: "Example App"
  title: "让团队知识更容易被使用"
  subtitle: "知识库与智能体工作台"

footer:
  copyright: "© Example Organization"
  user_agreement_url: "/protocols/user-agreement.html"
  privacy_policy_url: "/protocols/privacy-policy.html"

图片和协议页面放在 web/public 下，路径从网站根目录开始写，例如 /logo.svg。Compose 中 API 的工作目录是 /app，因此默认配置路径可以写成：

YUXI_BRAND_FILE_PATH=package/yuxi/config/static/info.local.yaml

也可以在 .env 中设置绝对路径，但文件必须挂载到 API 容器中。路径不存在时，API 会回退到 info.template.yaml；它不会把两个 YAML 文件合并。

2. 重新加载

开发环境的 API 直接挂载 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 指向容器内路径；修改该环境变量后同样要重新创建容器。页面会通过公开的 /api/system/info 读取站点信息，版本占位符 由 API 替换为当前版本。

登录协议

当 footer.user_agreement_url 和 footer.privacy_policy_url 同时有值时，登录和初始化页面显示协议勾选项；任一链接为空时，不显示勾选项。用户未勾选时，登录或初始化会被页面拦截并提示先同意协议。

仓库提供了两个模板：

• web/public/protocols/user-agreement.template.html
• web/public/protocols/privacy-policy.template.html

可以直接替换模板内容和其中的 、、 等占位符，也可以把配置指向自定义的站内或外部页面。正式上线前请让法务审核协议文本。

修改主题样式

主题色变量位于：

• web/src/assets/css/base.css：浅色模式；
• web/src/assets/css/base.dark.css：暗色模式；
• web/src/stores/theme.js：主题选择器的默认配置。

优先修改已有 CSS 变量，不要在组件中散落新的硬编码颜色。当前主题的主要变量包括 --main-1000、--main-900 和 --main-color；如果调整主色，还要同步修改 web/src/stores/theme.js 中的 colorPrimary，否则 Ant Design 组件和自定义样式可能出现颜色不一致。新增颜色时，同时检查浅色、暗色、hover、focus、禁用和错误状态的对比度。

开发环境会通过 Vite 热更新样式；生产环境需要重新构建 Web 镜像：

docker compose -f docker-compose.prod.yml --env-file .env.prod \
  up -d --build web

品牌 YAML、主题颜色和图标属于不同配置面：YAML 影响站点信息接口，CSS 和 theme.js 影响前端资源。修改其中一项不会自动改动另一项。