Web 前端（frontend/）

WeKnora 的 Web 前端是一个基于 Vue 3 + TypeScript + Vite 的单页应用（SPA），承载知识库管理、Agent 对话、组织协作、系统设置等全部交互界面。同一份代码同时服务三种形态：

1. 标准 Web 部署：Vite 构建产物由 nginx 容器托管，/api 反向代理到后端；
2. 网页嵌入（Embed）：独立的轻量入口 frontend/embed.html + frontend/src/embed-main.ts，供第三方网站以 iframe / 浮窗方式嵌入智能体对话；
3. 桌面端（Wails）：通过 frontend/src/wailsjs/ 下的自动生成绑定与桌面进程的 Go 侧通信，前端代码中可见大量对桌面形态的适配（如 --wails-draggable 拖拽区域、窗口深浅色同步）。

技术栈总览

依据 frontend/package.json（版本 0.7.2）：

值得注意的依赖细节：

• xlsx 不走 npm registry，而是安装本地 tarball："xlsx": "file:./packages/xlsx-0.20.2.tgz"（即 frontend/packages/ 目录的用途，锁定版本、离线可装）；
• frontend/pnpm-workspace.yaml 并非声明子包 workspace，只包含 allowBuilds 白名单（允许 @vue-office/pptx、esbuild、vue-demi 执行构建脚本），用于 pnpm 的构建脚本安全策略；
• overrides / resolutions 中禁用了 lightningcss 并统一 esbuild、serialize-javascript 版本。

模块结构

flowchart TB
    subgraph entries["构建入口 (vite.config.ts 双入口)"]
        MAIN["index.html + src/main.ts
(主 SPA)"]
        EMBED["embed.html + src/embed-main.ts
(嵌入渠道 /embed/:channelId)"]
    end

    subgraph app["应用层"]
        ROUTER["路由 (src/router/index.ts)
导航守卫: 登录 / 租户 / SystemAdmin"]
        VIEWS["视图层 (src/views)
knowledge / chat / agent / settings / organization / embed ..."]
        COMP["通用组件 (src/components)"]
    end

    subgraph state["状态与逻辑层"]
        STORES["Pinia stores (src/stores)
auth / settings / organization ..."]
        COMPOSABLES["composables (src/composables)
useTheme / useFont / useChatStreamHandler ..."]
        HOOKS["hooks (src/hooks)"]
        UTILS["utils (src/utils)
request.ts / markdown 渲染 / 安全消毒"]
    end

    subgraph io["数据访问层"]
        API["API 封装 (src/api)
axios 实例 + SSE 流式"]
        I18N["多语言 (src/i18n)
zh-CN / en-US / ru-RU / ko-KR"]
        WAILS["桌面绑定 (src/wailsjs)
Wails 自动生成"]
    end

    BACKEND["WeKnora 后端 API
(/api, /files)"]

    MAIN --> ROUTER --> VIEWS
    EMBED --> VIEWS
    VIEWS --> COMP
    VIEWS --> STORES
    VIEWS --> COMPOSABLES
    COMPOSABLES --> UTILS
    STORES --> API
    VIEWS --> API
    API --> BACKEND
    VIEWS --> I18N
    COMPOSABLES --> WAILS

目录速览

页面路由清单

路由定义在 frontend/src/router/index.ts，使用 createWebHistory，所有页面组件均为动态 import（按路由分包懒加载）。

顶层路由

/platform 子路由

独立入口：嵌入页

/embed/:channelId 不属于主 SPA 路由，而是由 frontend/embed.html + frontend/src/embed-main.ts 构成的独立入口（nginx 与 Vite dev server 都将 /embed/* fallback 到 embed.html），组件为 src/views/embed/EmbedPage.vue（配套 EmbedChatView.vue / EmbedChatCore.vue / EmbedBotMessage.vue 等），使用 Embed token 鉴权，供第三方网站 iframe 嵌入。

设置中心的分区与可见性

Settings.vue 把所有分区按七组呈现，用 ?section= 定位：

可见性由两套规则决定，且前端只做收敛展示，后端路由守卫才是权威：

• 空间角色门槛：frontend/src/config/settingsAccess.ts 的 SETTINGS_SECTION_MIN_ROLE 给每个分区规定最低角色。general / models / system / userprofile / tenant / members 是 viewer 起（只读可见），其余（ollama、weknoracloud、websearch、chathistory、vectorstore、parser、storage、mcp）要求 admin。另有 SETTINGS_MANAGEMENT_SHORTCUT_MIN_ROLE：头像菜单里那些标着「管理」的快捷入口门槛更高（成员管理要 owner，模型管理要 admin），避免把只读页面伪装成管理入口。
• 系统管理员白名单：SYSTEM_ADMIN_SETTINGS_SECTIONS（system-global、runtime-queues、platform-api-keys、system-audit-log）只对系统管理员显示，与空间角色无关，详见租户、用户与认证授权的「系统管理员与平台控制台」。

知识库编辑弹窗的分区

不少配置不在设置中心，而在知识库编辑弹窗里（KnowledgeBaseEditorModal.vue），因为它们是按库生效的。侧栏分区按五组组织，其中三个只在「编辑已有知识库」时出现：

全局命令面板（⌘K / Ctrl+K）

components/GlobalCommandPalette.vue 是除侧栏之外的第二条主要导航通路：

• 搜索知识库、文档与会话，支持把范围收窄到某个知识库（scope chip）后再搜；
• 空状态下展示最近搜索与快捷动作（建库、上传、新建会话等）；
• 右上角的入口打开检索设置抽屉（views/settings/RetrievalSettings.vue）。这是调 TopK、向量/关键词阈值、重排参数的地方——它不在设置中心里，找不到的话就是在这。

导航守卫

router.beforeEach 中实现了一条完整的鉴权链（frontend/src/router/index.ts）：

1. OIDC 回调放行：URL hash 含 oidc_result= / oidc_error= 时直接放行，交由 App.vue 消费；
2. Lite / 桌面端深链恢复：Lite 模式硬刷新落在默认首页时，从 sessionStorage 恢复上次访问的 /platform 子路径；
3. 会话恢复：未登录时先用 localStorage 中的 weknora_token 调 getCurrentUser() 恢复会话（同时刷新 memberships，避免角色变更滞后）；
4. Lite 自动登录：恢复失败则尝试一次 autoSetup()（单机版免登录），失败会在 localStorage 打标避免重复尝试；
5. 租户门槛：已登录但无有效租户 → 跳 /onboarding/workspace；
6. SystemAdmin 门槛：requiresSystemAdmin 路由对非系统管理员跳回知识库列表（仅 UI 层拦截，服务端另有强校验）。

状态管理（Pinia）

frontend/src/stores/ 下的 store 与辅助模块：

API 封装（frontend/src/api/）

请求基座

• axios 实例：frontend/src/utils/request.ts 创建统一实例（baseURL 来自 frontend/src/utils/api-base.ts 的 getApiBaseUrl()，尊重 Vite BASE_URL 以支持子路径反代部署；超时 30s）。
• 请求拦截器：自动附加 Authorization: Bearer <weknora_token>（Embed 渠道的 Embed token 不被覆盖）、Accept-Language（当前 i18n 语言）、X-Request-ID（随机串）、X-Tenant-ID（跨空间访问，始终携带激活空间 id 以避免切空间后 header 丢失）。
• 响应拦截器：2xx 解包返回 data；401 触发单飞（single-flight）refresh token 刷新，失败队列重放；公开端点（/auth/login、/auth/auto-setup、/auth/invitations/lookup、/api/v1/embed/ 等 PUBLIC_AUTH_PATHS）的 401 直接抛给页面而不跳登录；Embed 页面永不重定向到 /login。
• SSE 流式：frontend/src/api/chat/streame.ts 基于 @microsoft/fetch-event-source 封装 useStream()，支持流式输出、加载态、错误态与请求调试元数据；上层由 frontend/src/composables/useChatStreamHandler.ts 组织为聊天消息流。

模块清单

对话时间线的等待态

RAG 流水线的可视化进度（views/chat/components/RagPipelineProgress.vue）在「所有可见步骤都完成」到「模型吐出第一个字」之间会有一段静默期。这段空白由 utils/rag-pipeline-state.ts 描述：

• getRagPipelineWaitKind() 判定等待类型：检索步骤确实完成过才叫 model（正在生成回答）；纯附件问答这类没有检索步骤的轮次给中性的 preparing，而不是完全没有反馈；
• createRagWaitController() 负责呈现细节：延迟 RAG_WAIT_REVEAL_DELAY_MS（250ms）才显示，避免模型很快回答时闪一下；超过 RAG_WAIT_STALL_DELAY_MS（60s）转为「停滞」态——SSE 断连时后端不会再发 is_completed，没有这个上限进度条会永远宣称「马上就好」；
• 状态变化通过一个常驻的 aria-live 区域播报，读屏用户不会因为节点整体替换而漏读。

多语言（i18n）

实现于 frontend/src/i18n/index.ts，基于 vue-i18n（legacy: false 的 Composition 模式，globalInjection: true）：

• 支持语言（frontend/src/i18n/locales/）：

  • zh-CN（简体中文，默认与 fallback）
  • en-US（英语）
  • ru-RU（俄语）
  • ko-KR（韩语）

• 语言选择持久化在 localStorage 的 locale key；axios 拦截器会把当前语言写入 Accept-Language 请求头，使后端返回本地化内容。

• 因部分翻译刻意内嵌 <strong> 标记（经 DOMPurify 消毒后 v-html 渲染），配置了 warnHtmlMessage: false 关闭 vue-i18n 的 HTML 告警。

• Embed 独立 i18n：访客侧嵌入页使用单独的 frontend/src/i18n/embed.ts（由 embed-main.ts 加载），管理端「网页嵌入」文案仍在主语言包中；frontend/src/i18n/locales/embed/index.ts 统一 re-export 语言归一化助手（支持从 URL 参数同步 embed 语言）。

• 审计与裁剪工具：语言包体量大、容易积累无人引用的死键或漏翻的新键，因此配套了三个脚本（frontend/package.json）：

  命令	作用
  npm run check-i18n	跑 src/i18n/localeKeyAudit.test.ts，校验各语言包键集一致、无缺失引用
  npm run scan-i18n-gaps	扫描源码中实际用到的 key 与语言包对比，报告未定义与未使用的键
  npm run regenerate-i18n-locales	按扫描结果重新生成裁剪后的语言包

  审计日志的动作名走单独的注册表（i18n/auditActionRegistry.ts + auditActionLocaleDefaults.ts），新增审计动作时在注册表补一条即可，避免裁剪工具把它们当成未引用的死键删掉。

主题与外观

• 主题模式：frontend/src/composables/useTheme.ts 提供 light | dark | system 三态。生效方式是在 document.documentElement 上设置 theme-mode 属性；system 模式监听 prefers-color-scheme 媒体查询自动跟随。
• CSS 变量：frontend/src/assets/theme/theme.css 以 TDesign token 体系（--td-brand-color-*、--td-bg-color-*、--td-text-color-*、字体/圆角/阴影等）分别定义 :root[theme-mode="light"] 与 :root[theme-mode="dark"] 两套变量，品牌色为绿色系；组件样式一律引用变量实现一键换肤。
• 偏好持久化：主题与字体偏好通过 frontend/src/composables/preferenceStorage.ts 按用户 id 命名空间存入 localStorage，登录/登出/切换账号时由 reloadThemeFromStorage() / reloadFontFromStorage() 重载（在 stores/auth.ts 中触发）。
• 字体：frontend/src/composables/useFont.ts 管理界面字体选择，main.ts 启动时 initTheme() + initFont()。
• 桌面端同步：useTheme.ts 中的 syncWailsNativeChrome() 调用 Wails runtime 的 WindowSetDarkTheme / WindowSetLightTheme / WindowSetBackgroundColour，让原生窗口底色与网页主题一致，减轻刷新白闪。

构建与部署

开发与构建（vite.config.ts）

frontend/vite.config.ts 要点：

• 双入口构建：rollupOptions.input 同时构建 index.html（主 SPA）与 embed.html（嵌入页）；开发环境用自定义插件 embedHtmlDevFallback() 把 /embed/:channelId 请求改写到 /embed.html，与 nginx 行为对齐。
• 代码分包：manualChunks 将 mermaid/dagre/cytoscape、marked/katex、highlight.js 分别拆为 vendor-mermaid、vendor-markdown、vendor-highlight；embed 入口通过 modulePreload.resolveDependencies 过滤重型聊天 chunk，保证嵌入页首屏只加载 token 交换所需代码。
• 版本注入：__FRONTEND_VERSION__（package.json version）与 __FRONTEND_COMMIT__（VITE_FRONTEND_COMMIT / GITHUB_SHA / git rev-parse）编译期注入。
• 开发代理：dev server（端口 5173）与 preview（端口 4173）都把 /api、/files 代理到 VITE_DEV_PROXY_TARGET（或 FRONTEND_BACKEND_URL，默认 http://localhost:8080）。
• 别名：@ → frontend/src；并对 @vue-office/pptx 做入口文件探测修正。
• 常用脚本：npm run dev / npm run build / npm run preview（用生产构建产物本地起服务，最接近发布镜像的验证环境）/ npm run type-check / npm run test（tsx --test）。

生产镜像（Dockerfile + nginx）

frontend/Dockerfile：

• 基础镜像固定为 digest 锁定的 nginx:1.30.3-alpine（注释明确禁止改回浮动 tag——更新的 Alpine 3.24+ 在 CentOS 7 旧内核上无法启动，曾导致 v0.7.0 故障）；
• 静态产物需先在宿主机构建（./scripts/build_frontend_dist.sh），镜像只 COPY dist；
• nginx.conf 作为模板放入 /etc/nginx/templates/default.conf.template，暴露 80 端口，入口为 docker-entrypoint.sh。

frontend/docker-entrypoint.sh（运行时配置注入）：

1. 生成 /usr/share/nginx/html/config.js，把 MAX_FILE_SIZE_MB（默认 50）写入 window.__RUNTIME_CONFIG__ 供前端运行时读取；
2. 用 envsubst 渲染 nginx 模板，可配置环境变量：MAX_FILE_SIZE_MB、APP_HOST（默认 app）、APP_PORT（默认 8080）、APP_SCHEME（默认 http，远程 HTTPS 后端可设 https）；
3. 前台启动 nginx。

frontend/nginx.conf 关键行为：

• SPA fallback：/ 下 try_files ... /index.html，且 index.html 设置 no-cache（避免升级后用户拿到旧版本）；带 hash 的 /assets/* 设置一年 immutable 缓存；
• API 代理：/api/ 与 /files 反代到 ${APP_SCHEME}://${APP_HOST}:${APP_PORT}，/api/ 针对 SSE 关闭 proxy_buffering / 缓存 / 分块编码，读写超时放宽到 3600s，并配置 3 次 upstream 重试；
• 资源短链 /r/：location ^~ /r/ 同样反代到后端。IM 渠道把 resource:// 图片改写成 <APP_EXTERNAL_URL>/r/<token>，缺这段配置时请求会落进 SPA fallback，IM 侧图片显示为空白（详见 IM 集成）；
• 嵌入页：/embed/* fallback 到 embed.html（独立 location，不继承主站的 X-Frame-Options: SAMEORIGIN，因此可被第三方 iframe 加载）；/weknora-widget.js 是给第三方站点的静态加载器；文件头部另附可选的独立 embed 子域 server 块示例；
• 启用 gzip（注释记录了实测收益：低带宽下首屏从 25s 降到 3-5s）及一组安全响应头（X-Frame-Options、X-Content-Type-Options、Referrer-Policy 等，在各 location 内重复声明以规避 nginx add_header 不继承的问题）。

桌面端（Wails）关联

frontend/src/wailsjs/ 是 Wails 框架自动生成的绑定代码（文件头标注 "automatically generated. DO NOT EDIT"）：

• wailsjs/go/main/App.d.ts / App.js：Go 侧 App 结构体方法的 JS 绑定，包括 CheckForUpdates / AutoCheckForUpdates（桌面更新检查）、GetAPIBaseURL / GetAPILanBaseURL、桌面内置 HTTP 服务的端口与对外监听设置（GetDesktopHTTPPortSetting、SetDesktopHTTPBindPublicSetting 等）；
• wailsjs/runtime/：Wails runtime API（窗口控制等），前端在浏览器环境下调用会被 try/catch 安静降级（如 useTheme.ts）。

桌面应用的窗口内容就是这份前端代码，Lite 模式（autoSetup 免登录 + 深链恢复）与 --wails-draggable 标记的可拖拽标题区都是为桌面形态准备的适配。