Fix Bilibili 412 error: inject dm_img risk-control params into yt-dlp wbi/playurl requests

将 README 社区区块中 5 个会过期的微信群二维码，替换为公众号二维码，
关注后回复「交流群」获取最新群码，避免群码失效。与关于页保持一致。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.github/workflows/docker-build.yml

@@ -42,6 +42,16 @@ jobs:
             type=sha,prefix=
             type=raw,value=latest,enable={{is_default_branch}}
 
+      - name: Resolve app version
+        id: app-version
+        shell: bash
+        run: |
+          if [[ "$GITHUB_REF" == refs/tags/v* ]]; then
+            echo "version=${GITHUB_REF_NAME#v}" >> "$GITHUB_OUTPUT"
+          else
+            echo "version=" >> "$GITHUB_OUTPUT"
+          fi
+
       - name: Build and Push Docker Image
         uses: docker/build-push-action@v6
         with:
@@ -50,6 +60,8 @@ jobs:
           push: true
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
+          build-args: |
+            VITE_APP_VERSION=${{ steps.app-version.outputs.version }}
           cache-from: type=gha
           cache-to: type=gha,mode=max
           platforms: linux/amd64,linux/arm64
@@ -66,6 +78,9 @@ jobs:
           echo "Run the container:"
           echo "  docker run -d -p 80:80 \\"
           echo "    -v bilinote-data:/app/backend/data \\"
+          echo "    -v bilinote-config:/app/backend/config \\"
+          echo "    -v bilinote-static:/app/backend/static \\"
+          echo "    -v bilinote-models:/app/backend/models \\"
           echo "    --name bilinote \\"
           echo "    ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest"
           echo ""

.github/workflows/main.yml

@@ -79,6 +79,19 @@ jobs:
           key: ${{ runner.os }}-cargo-${{ hashFiles('BillNote_frontend/src-tauri/Cargo.lock') }}
           restore-keys: ${{ runner.os }}-cargo-
 
+      # 从 tag 注入版本号到 tauri.conf.json：Tauri 取该文件的静态 version 作为
+      # 产物版本，不同步的话构建产物会恒为 conf 里写死的值（此前的 2.0.0）。
+      # github.ref_name 形如 v2.3.2，去掉前缀 v。workflow_dispatch（无 tag）时跳过，保留静态值。
+      - name: Sync version from tag
+        if: startsWith(github.ref, 'refs/tags/v')
+        working-directory: BillNote_frontend
+        shell: bash
+        run: |
+          VERSION="${GITHUB_REF_NAME#v}"
+          echo "Injecting version $VERSION into tauri.conf.json"
+          node -e "const f='src-tauri/tauri.conf.json'; const fs=require('fs'); const j=JSON.parse(fs.readFileSync(f,'utf8')); j.version=process.argv[1]; fs.writeFileSync(f, JSON.stringify(j,null,2)+'\n');" "$VERSION"
+          node -e "console.log('tauri.conf.json version =', require('./src-tauri/tauri.conf.json').version)"
+
       # 打包 Tauri 应用
       - name: Build Tauri App
         working-directory: BillNote_frontend

BillNote_extension/src/background/main.ts

@@ -3,6 +3,7 @@ import type { Settings, TaskRecord } from '~/logic/types'
 import { DEFAULT_SETTINGS, MAX_TASKS, SETTINGS_KEY, TASKS_KEY } from '~/logic/constants'
 import { detectPlatform } from '~/logic/platform'
 import { fetchBilibiliSubtitle } from '~/logic/bilibili-subtitle'
+import { normalizeVideoTitle } from '~/logic/task-display'
 
 // only on dev mode
 if (import.meta.hot) {
@@ -56,8 +57,9 @@ async function upsertTask(record: TaskRecord) {
 
 // ---------- 启动任务 ----------
 
-async function startTask(url: string): Promise<{ ok: boolean, taskId?: string, error?: string }> {
+async function startTask(url: string, title?: string): Promise<{ ok: boolean, taskId?: string, error?: string }> {
   const platform = detectPlatform(url)
+  const displayTitle = normalizeVideoTitle(title)
   if (!platform)
     return { ok: false, error: '当前链接不是支持的视频平台' }
 
@@ -107,6 +109,7 @@ async function startTask(url: string): Promise<{ ok: boolean, taskId?: string, e
       message: '已提交',
       createdAt: Date.now(),
       updatedAt: Date.now(),
+      title: displayTitle,
     })
     return { ok: true, taskId: body.data.task_id }
   }
@@ -129,8 +132,8 @@ async function openSidePanelInTab(tabId?: number) {
 
 // ---------- 消息桥 ----------
 
-onMessage<{ url: string }, 'bilinote-start'>('bilinote-start', async ({ data, sender }) => {
-  const result = await startTask(data.url)
+onMessage<{ url: string; title?: string }, 'bilinote-start'>('bilinote-start', async ({ data, sender }) => {
+  const result = await startTask(data.url, data.title)
   // 成功就把侧边栏拉起来给用户看进度
   if (result.ok)
     await openSidePanelInTab(sender?.tabId)
@@ -168,7 +171,7 @@ browser.contextMenus?.onClicked.addListener(async (info, tab) => {
   const url = info.linkUrl || tab?.url
   if (!url)
     return
-  const result = await startTask(url)
+  const result = await startTask(url, tab?.title)
   if (result.ok)
     await openSidePanelInTab(tab?.id)
   else

BillNote_extension/src/components/MindMap.vue

@@ -1,32 +1,181 @@
 <script setup lang="ts">
-import { onMounted, ref, watch } from 'vue'
+import { nextTick, onMounted, onUnmounted, ref, watch } from 'vue'
 import { Transformer } from 'markmap-lib'
 import { Markmap } from 'markmap-view'
 import { absolutizeMarkdownImages, stripSourceLink } from '~/logic/api'
 
 const props = defineProps<{ markdown: string }>()
 
+const wrapRef = ref<HTMLDivElement | null>(null)
 const svgRef = ref<SVGSVGElement | null>(null)
 let mm: Markmap | null = null
+let resizeObserver: ResizeObserver | null = null
 const transformer = new Transformer()
+const MIN_EXPORT_FONT_PX = 256
+const MIN_EXPORT_WIDTH = 12800
+const MAX_EXPORT_SCALE = 24
+const MAX_CANVAS_SIDE = 32767
 
-function render() {
-  if (!svgRef.value)
-    return
-  const md = absolutizeMarkdownImages(stripSourceLink(props.markdown || ''))
-  const { root } = transformer.transform(md)
-  if (!mm)
-    mm = Markmap.create(svgRef.value, undefined, root)
-  else
-    mm.setData(root).then(() => mm?.fit())
+function canvasToBlob(canvas: HTMLCanvasElement): Promise<Blob> {
+  return new Promise((resolve, reject) => {
+    canvas.toBlob((blob) => {
+      if (blob)
+        resolve(blob)
+      else
+        reject(new Error('导出思维导图图片失败'))
+    }, 'image/png')
+  })
 }
 
-onMounted(render)
+function createSvgElement<K extends keyof SVGElementTagNameMap>(tag: K): SVGElementTagNameMap[K] {
+  return document.createElementNS('http://www.w3.org/2000/svg', tag)
+}
+
+function sanitizeSvgForCanvas(svg: SVGSVGElement): SVGSVGElement {
+  const cloned = svg.cloneNode(true) as SVGSVGElement
+
+  cloned.querySelectorAll('image').forEach(el => el.remove())
+  cloned.querySelectorAll('foreignObject').forEach((foreignObject) => {
+    const textContent = foreignObject.textContent?.replace(/\s+/g, ' ').trim()
+    if (!textContent) {
+      foreignObject.remove()
+      return
+    }
+
+    const x = Number(foreignObject.getAttribute('x') || 0)
+    const y = Number(foreignObject.getAttribute('y') || 0)
+    const height = Number(foreignObject.getAttribute('height') || 20)
+    const text = createSvgElement('text')
+    text.setAttribute('x', String(x))
+    text.setAttribute('y', String(y + height / 2))
+    text.setAttribute('dominant-baseline', 'middle')
+    text.setAttribute('font-size', '14')
+    text.setAttribute('font-family', 'Arial, "Microsoft YaHei", sans-serif')
+    text.setAttribute('fill', '#333')
+    text.textContent = textContent
+    foreignObject.replaceWith(text)
+  })
+
+  return cloned
+}
+
+function getExportFontSize(svg: SVGSVGElement): number {
+  const text = svg.querySelector('text, foreignObject')
+  if (!text)
+    return 14
+
+  const fontSize = Number.parseFloat(getComputedStyle(text).fontSize || '')
+  if (Number.isFinite(fontSize) && fontSize > 0)
+    return fontSize
+
+  const attrSize = Number.parseFloat(text.getAttribute('font-size') || '')
+  return Number.isFinite(attrSize) && attrSize > 0 ? attrSize : 14
+}
+
+function stripMindmapNoise(md: string): string {
+  return absolutizeMarkdownImages(stripSourceLink(md || ''))
+    // 笔记里的截图/封面图片在思维导图中会被当作超大 SVG foreignObject，
+    // 容易把导图挤成截图里那种“只剩半框/一条竖线”的效果。导图只保留文字层级。
+    .replace(/!\[[^\]]*\]\([^)]*\)/g, '')
+    .replace(/<img\b[^>]*>/gi, '')
+}
+
+async function fit() {
+  await nextTick()
+  requestAnimationFrame(() => mm?.fit())
+}
+
+async function render() {
+  if (!svgRef.value)
+    return
+  const { root } = transformer.transform(stripMindmapNoise(props.markdown))
+  if (!mm)
+    mm = Markmap.create(svgRef.value, { autoFit: true }, root)
+  else
+    await mm.setData(root)
+  await fit()
+}
+
+async function toPngBlob(): Promise<Blob> {
+  await fit()
+  await nextTick()
+  if (!svgRef.value)
+    throw new Error('思维导图尚未渲染完成')
+
+  const svg = svgRef.value
+  const bbox = svg.getBBox()
+  const padding = 48
+  const x = Math.floor(bbox.x - padding)
+  const y = Math.floor(bbox.y - padding)
+  const width = Math.max(Math.ceil(bbox.width + padding * 2), 1)
+  const height = Math.max(Math.ceil(bbox.height + padding * 2), 1)
+  const cloned = sanitizeSvgForCanvas(svg)
+
+  cloned.setAttribute('xmlns', 'http://www.w3.org/2000/svg')
+  cloned.setAttribute('width', String(width))
+  cloned.setAttribute('height', String(height))
+  cloned.setAttribute('viewBox', `${x} ${y} ${width} ${height}`)
+  cloned.insertAdjacentHTML('afterbegin', `<rect width="100%" height="100%" fill="#fff"/>`)
+
+  const svgText = new XMLSerializer().serializeToString(cloned)
+  const url = URL.createObjectURL(new Blob([svgText], { type: 'image/svg+xml;charset=utf-8' }))
+
+  try {
+    const img = new Image()
+    img.decoding = 'async'
+    img.src = url
+    await img.decode()
+
+    // 不写死某个导出宽度：按导图内容和文字字号动态反推 PNG 倍率。
+    // 目标是让导出的正文至少有 MIN_EXPORT_FONT_PX 像素高，小图自动放大，
+    // 大图则按内容尺寸导出；同时限制最大边长，避免复杂导图撑爆内存。
+    const fontScale = MIN_EXPORT_FONT_PX / getExportFontSize(svg)
+    const widthScale = MIN_EXPORT_WIDTH / width
+    const rawScale = Math.max(window.devicePixelRatio || 1, fontScale, widthScale)
+    const sideLimitScale = Math.min(MAX_CANVAS_SIDE / width, MAX_CANVAS_SIDE / height)
+    const scale = Math.max(1, Math.min(rawScale, MAX_EXPORT_SCALE, sideLimitScale))
+    const canvas = document.createElement('canvas')
+    canvas.width = Math.ceil(width * scale)
+    canvas.height = Math.ceil(height * scale)
+    const ctx = canvas.getContext('2d')
+    if (!ctx)
+      throw new Error('当前浏览器不支持 Canvas 导出')
+    ctx.fillStyle = '#fff'
+    ctx.fillRect(0, 0, canvas.width, canvas.height)
+    ctx.scale(scale, scale)
+    ctx.drawImage(img, 0, 0, width, height)
+    return await canvasToBlob(canvas)
+  }
+  finally {
+    URL.revokeObjectURL(url)
+  }
+}
+
+defineExpose({
+  toPngBlob,
+})
+
+onMounted(() => {
+  render()
+  if (wrapRef.value) {
+    resizeObserver = new ResizeObserver(() => fit())
+    resizeObserver.observe(wrapRef.value)
+  }
+})
+
+onUnmounted(() => {
+  resizeObserver?.disconnect()
+  resizeObserver = null
+  mm?.destroy()
+  mm = null
+})
+
 watch(() => props.markdown, render)
+
 </script>
 
 <template>
-  <div class="w-full h-full bg-white rounded border overflow-hidden">
-    <svg ref="svgRef" class="w-full h-full" />
+  <div ref="wrapRef" class="w-full h-full min-h-[360px] bg-white rounded border overflow-hidden">
+    <svg ref="svgRef" class="w-full h-full min-h-[360px]" />
   </div>
 </template>

BillNote_extension/src/contentScripts/views/App.vue

@@ -19,6 +19,7 @@ async function trigger() {
     const res = await sendMessage('bilinote-start', {
       url: window.location.href,
       platform,
+      title: document.title,
     }, 'background')
     const ok = res && (res as any).ok
     toast.value = ok

BillNote_extension/src/logic/task-display.ts

@@ -0,0 +1,21 @@
+import type { TaskRecord } from './types'
+
+const SITE_SUFFIX_RE = /\s*[-_—–|｜]\s*(哔哩哔哩|bilibili|youtube|抖音|douyin|快手|kuaishou)\s*$/i
+
+export function normalizeVideoTitle(title: string | undefined | null): string | undefined {
+  const value = title?.trim()
+  if (!value)
+    return undefined
+  return value
+    .replace(SITE_SUFFIX_RE, '')
+    .trim() || value
+}
+
+export function getTaskDisplayTitle(task: TaskRecord | undefined | null, fallbackTitle?: string): string {
+  if (!task)
+    return normalizeVideoTitle(fallbackTitle) || ''
+  return normalizeVideoTitle((task.result?.audio_meta as { title?: string } | undefined)?.title)
+    || normalizeVideoTitle(task.title)
+    || normalizeVideoTitle(fallbackTitle)
+    || task.videoUrl
+}

BillNote_extension/src/logic/types.ts

@@ -79,6 +79,8 @@ export interface TaskRecord {
   createdAt: number
   updatedAt: number
   result?: NoteResult
+  // 从浏览器 tab.title 抓取，任务完成前用来替代 videoUrl 显示
+  title?: string
 }
 
 // 与 backend/app/gpt/prompt_builder.py note_styles 一一对齐

BillNote_extension/src/popup/Popup.vue

@@ -5,6 +5,7 @@ import { settings, settingsReady, tasks, tasksReady, upsertTask } from '~/logic/
 import { generateNote, getTaskStatus, resolveImageUrl } from '~/logic/api'
 import { fetchBilibiliSubtitle } from '~/logic/bilibili-subtitle'
 import { NOTE_FORMATS, NOTE_STYLES, type NoteFormat, type TaskRecord } from '~/logic/types'
+import { getTaskDisplayTitle, normalizeVideoTitle } from '~/logic/task-display'
 
 const tabUrl = ref<string>('')
 const tabTitle = ref<string>('')
@@ -43,6 +44,7 @@ async function poll(taskId: string) {
       createdAt: activeTask.value?.createdAt ?? Date.now(),
       updatedAt: Date.now(),
       result: res.result ?? activeTask.value?.result,
+      title: activeTask.value?.title || normalizeVideoTitle(tabTitle.value),
     })
     if (res.status !== 'SUCCESS' && res.status !== 'FAILED')
       pollTimer = setTimeout(() => poll(taskId), 3000)
@@ -94,6 +96,7 @@ async function start() {
       message: '已提交',
       createdAt: Date.now(),
       updatedAt: Date.now(),
+      title: normalizeVideoTitle(tabTitle.value),
     })
     poll(task_id)
     // 提交后顺手把侧边栏拉起来，免得用户来回切窗口
@@ -142,7 +145,7 @@ function selectTask(id: string) {
 }
 
 const activeCover = computed(() => activeTask.value?.result?.audio_meta?.cover_url as string | undefined)
-const activeTitle = computed(() => (activeTask.value?.result?.audio_meta?.title as string | undefined) || tabTitle.value)
+const activeTitle = computed(() => getTaskDisplayTitle(activeTask.value, tabTitle.value))
 
 function fmtTime(ts?: number) {
   if (!ts)
@@ -177,8 +180,8 @@ onUnmounted(() => {
       <button class="text-xs text-gray-500 hover:text-gray-800" @click="openOptions">设置</button>
     </header>
 
-    <div class="text-xs text-gray-500 truncate" :title="tabUrl">
-      {{ tabUrl || '当前没有打开的标签页' }}
+    <div class="text-xs text-gray-500 truncate" :title="normalizeVideoTitle(tabTitle) || tabUrl">
+      {{ normalizeVideoTitle(tabTitle) || tabUrl || '当前没有打开的标签页' }}
     </div>
 
     <div v-if="!supported" class="text-xs text-amber-700 bg-amber-50 p-2 rounded">
@@ -331,8 +334,8 @@ onUnmounted(() => {
           :class="{ 'bg-blue-50': t.taskId === activeTaskId }"
           @click="selectTask(t.taskId)"
         >
-          <span class="truncate flex-1" :title="t.videoUrl">
-            {{ (t.result?.audio_meta as { title?: string } | undefined)?.title || t.videoUrl }}
+          <span class="truncate flex-1" :title="getTaskDisplayTitle(t)">
+            {{ getTaskDisplayTitle(t) }}
           </span>
           <span class="text-gray-500 shrink-0">{{ t.status }}</span>
         </li>

BillNote_extension/src/sidepanel/Sidepanel.vue

@@ -3,14 +3,17 @@ import { computed, onMounted, onUnmounted, ref } from 'vue'
 import { getTaskStatus, resolveImageUrl } from '~/logic/api'
 import { tasks, tasksReady, settingsReady, upsertTask } from '~/logic/storage'
 import type { TaskRecord } from '~/logic/types'
+import { getTaskDisplayTitle } from '~/logic/task-display'
 
 type ViewMode = 'markdown' | 'mindmap' | 'chat'
 
 const activeTaskId = ref<string>('')
 const activeTask = computed<TaskRecord | undefined>(() => tasks.value?.find(t => t.taskId === activeTaskId.value))
 const errorMsg = ref('')
+const successMsg = ref('')
 const viewMode = ref<ViewMode>('markdown')
 const showHistory = ref(false)
+const mindMapRef = ref<{ toPngBlob: () => Promise<Blob> } | null>(null)
 
 const isDone = computed(() => activeTask.value?.status === 'SUCCESS')
 const isFailed = computed(() => activeTask.value?.status === 'FAILED')
@@ -41,6 +44,7 @@ async function poll(taskId: string) {
         message: res.message,
         result: res.result ?? cur.result,
         updatedAt: Date.now(),
+        title: cur.title || getTaskDisplayTitle(cur),
       })
     }
     if (res.status !== 'SUCCESS' && res.status !== 'FAILED')
@@ -74,11 +78,19 @@ async function copyMarkdown() {
     await navigator.clipboard.writeText(md)
 }
 
+function safeFilename(name: string): string {
+  return (name || 'bilinote')
+    .replace(/[\\/:*?"<>|]/g, '_')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, 120) || 'bilinote'
+}
+
 function downloadMarkdown() {
   const md = activeTask.value?.result?.markdown
   if (!md)
     return
-  const title = (activeTask.value?.result?.audio_meta as { title?: string } | undefined)?.title || 'bilinote'
+  const title = safeFilename(getTaskDisplayTitle(activeTask.value))
   const blob = new Blob([md], { type: 'text/markdown;charset=utf-8' })
   const url = URL.createObjectURL(blob)
   const a = document.createElement('a')
@@ -88,8 +100,44 @@ function downloadMarkdown() {
   URL.revokeObjectURL(url)
 }
 
-const activeTitle = computed(() =>
-  (activeTask.value?.result?.audio_meta as { title?: string } | undefined)?.title || activeTask.value?.videoUrl || '')
+async function copyMindMapImage() {
+  try {
+    errorMsg.value = ''
+    successMsg.value = ''
+    const blob = await mindMapRef.value?.toPngBlob()
+    if (!blob)
+      return
+    await navigator.clipboard.write([
+      new ClipboardItem({ [blob.type]: blob }),
+    ])
+    successMsg.value = '思维导图图片已复制'
+    setTimeout(() => { successMsg.value = '' }, 2000)
+  }
+  catch (e) {
+    errorMsg.value = (e as Error).message || '复制思维导图图片失败'
+  }
+}
+
+async function downloadMindMapImage() {
+  try {
+    errorMsg.value = ''
+    successMsg.value = ''
+    const blob = await mindMapRef.value?.toPngBlob()
+    if (!blob)
+      return
+    const url = URL.createObjectURL(blob)
+    const a = document.createElement('a')
+    a.href = url
+    a.download = `${safeFilename(getTaskDisplayTitle(activeTask.value))}.png`
+    a.click()
+    URL.revokeObjectURL(url)
+  }
+  catch (e) {
+    errorMsg.value = (e as Error).message || '下载思维导图图片失败'
+  }
+}
+
+const activeTitle = computed(() => getTaskDisplayTitle(activeTask.value))
 
 const activeCover = computed(() =>
   (activeTask.value?.result?.audio_meta as { cover_url?: string } | undefined)?.cover_url)
@@ -140,8 +188,8 @@ onUnmounted(() => {
           :class="{ 'bg-white border': t.taskId === activeTaskId }"
           @click="selectTask(t.taskId)"
         >
-          <span class="truncate flex-1" :title="t.videoUrl">
-            {{ (t.result?.audio_meta as { title?: string } | undefined)?.title || t.videoUrl }}
+          <span class="truncate flex-1" :title="getTaskDisplayTitle(t)">
+            {{ getTaskDisplayTitle(t) }}
           </span>
           <span class="text-gray-400 shrink-0">{{ STAGE_LABELS[t.status] || t.status }}</span>
         </li>
@@ -151,6 +199,9 @@ onUnmounted(() => {
     <div v-if="errorMsg" class="text-xs text-red-600 px-3 py-1 break-words bg-red-50 shrink-0">
       {{ errorMsg }}
     </div>
+    <div v-if="successMsg" class="text-xs text-green-700 px-3 py-1 break-words bg-green-50 shrink-0">
+      {{ successMsg }}
+    </div>
 
     <section v-if="!activeTask" class="flex-1 flex items-center justify-center text-gray-400 text-xs px-4 text-center">
       还没有任务。在视频页点悬浮按钮、在 popup 提交，或右键菜单选「用 BiliNote 总结」。
@@ -170,7 +221,7 @@ onUnmounted(() => {
           class="text-sm font-medium leading-tight line-clamp-1 break-all flex-1 min-w-0 hover:text-blue-600"
           :href="activeTask.videoUrl"
           target="_blank"
-          :title="activeTask.videoUrl"
+          :title="activeTitle || activeTask.videoUrl"
         >{{ activeTitle }}</a>
         <span
           v-if="isDone"
@@ -224,6 +275,18 @@ onUnmounted(() => {
           title="下载 .md"
           @click="downloadMarkdown"
         >下载</button>
+        <button
+          v-if="viewMode === 'mindmap'"
+          class="text-gray-500 hover:text-gray-800 px-1.5 py-1 rounded hover:bg-gray-100"
+          title="复制思维导图图片"
+          @click="copyMindMapImage"
+        >复制</button>
+        <button
+          v-if="viewMode === 'mindmap'"
+          class="text-gray-500 hover:text-gray-800 px-1.5 py-1 rounded hover:bg-gray-100"
+          title="下载思维导图 PNG"
+          @click="downloadMindMapImage"
+        >下载</button>
       </div>
 
       <!-- 内容区：占满剩余空间 -->
@@ -236,6 +299,7 @@ onUnmounted(() => {
         />
         <MindMap
           v-else-if="isDone && activeTask.result?.markdown && viewMode === 'mindmap'"
+          ref="mindMapRef"
           :markdown="activeTask.result.markdown"
           class="h-full"
         />

BillNote_frontend/Dockerfile

@@ -5,6 +5,10 @@
 ARG BASE_REGISTRY=docker.io
 FROM ${BASE_REGISTRY}/library/node:20-alpine AS builder
 
+# 可由发布 workflow 从 git tag 注入，用于前端 About 页展示版本；未传时由 Vite 回退读取 tauri.conf.json。
+ARG VITE_APP_VERSION=
+ENV VITE_APP_VERSION=${VITE_APP_VERSION}
+
 # pnpm pin 到 9.x：lockfile 是 v9 生成；pnpm 11 要求 Node 22+ 与 node:20 不兼容
 RUN corepack enable && corepack prepare pnpm@9.15.0 --activate
 

BillNote_frontend/package.json

@@ -57,6 +57,7 @@
     "react-router-dom": "^7.5.1",
     "react-syntax-highlighter": "^15.6.1",
     "rehype-katex": "^6.0.2",
+    "rehype-slug": "5.1.0",
     "remark-gfm": "3.0.1",
     "remark-math": "^5.1.1",
     "sonner": "^2.0.3",

BillNote_frontend/pnpm-lock.yaml

@@ -13,7 +13,7 @@ importers:
         version: 2.4.0(antd@5.29.3(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       '@hookform/resolvers':
         specifier: ^5.0.1
-        version: 5.2.2(react-hook-form@7.72.0(react@19.2.4))
+        version: 5.4.0(react-hook-form@7.72.0(react@19.2.4))
       '@lobehub/icons':
         specifier: ^1.97.1
         version: 1.98.0(@babel/core@7.29.0)(@types/mdast@4.0.4)(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(antd@5.29.3(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(framer-motion@12.38.0(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(micromark-util-types@2.0.2)(micromark@4.0.2)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
@@ -52,7 +52,7 @@ importers:
         version: 1.2.8(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       '@tailwindcss/vite':
         specifier: ^4.1.3
-        version: 4.2.2(vite@6.4.1(@types/node@22.19.15)(jiti@2.6.1)(lightningcss@1.32.0)(yaml@2.8.3))
+        version: 4.2.2(vite@6.4.2(@types/node@22.19.15)(jiti@2.6.1)(lightningcss@1.32.0)(yaml@2.8.3))
       '@tauri-apps/api':
         specifier: ^2.11.0
         version: 2.11.0
@@ -61,7 +61,7 @@ importers:
         version: 2.3.5
       '@uiw/react-markdown-preview':
         specifier: ^5.1.3
-        version: 5.1.5(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+        version: 5.2.1(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       antd:
         specifier: ^5.24.8
         version: 5.29.3(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
@@ -76,13 +76,13 @@ importers:
         version: 2.1.1
       fuse.js:
         specifier: ^7.1.0
-        version: 7.1.0
+        version: 7.3.0
       github-markdown-css:
         specifier: ^5.8.1
         version: 5.9.0
       idb-keyval:
         specifier: ^6.2.2
-        version: 6.2.2
+        version: 6.2.4
       jszip:
         specifier: ^3.10.1
         version: 3.10.1
@@ -149,6 +149,9 @@ importers:
       rehype-katex:
         specifier: ^6.0.2
         version: 6.0.3
+      rehype-slug:
+        specifier: 5.1.0
+        version: 5.1.0
       remark-gfm:
         specifier: 3.0.1
         version: 3.0.1
@@ -169,7 +172,7 @@ importers:
         version: 1.4.0
       uuid:
         specifier: ^11.1.0
-        version: 11.1.0
+        version: 11.1.1
       zod:
         specifier: ^3.24.2
         version: 3.25.76
@@ -197,7 +200,7 @@ importers:
         version: 19.2.3(@types/react@19.2.14)
       '@vitejs/plugin-react':
         specifier: ^4.3.4
-        version: 4.7.0(vite@6.4.1(@types/node@22.19.15)(jiti@2.6.1)(lightningcss@1.32.0)(yaml@2.8.3))
+        version: 4.7.0(vite@6.4.2(@types/node@22.19.15)(jiti@2.6.1)(lightningcss@1.32.0)(yaml@2.8.3))
       autoprefixer:
         specifier: ^10.4.21
         version: 10.4.27(postcss@8.5.8)
@@ -227,7 +230,7 @@ importers:
         version: 8.57.1(eslint@9.39.4(jiti@2.6.1))(typescript@5.7.3)
       vite:
         specifier: ^6.2.0
-        version: 6.4.1(@types/node@22.19.15)(jiti@2.6.1)(lightningcss@1.32.0)(yaml@2.8.3)
+        version: 6.4.2(@types/node@22.19.15)(jiti@2.6.1)(lightningcss@1.32.0)(yaml@2.8.3)
 
 packages:
 
@@ -732,8 +735,8 @@ packages:
       react: ^16 || ^17 || ^18 || ^19
       react-dom: ^16 || ^17 || ^18 || ^19
 
-  '@hookform/resolvers@5.2.2':
-    resolution: {integrity: sha512-A/IxlMLShx3KjV/HeTcTfaMxdwy690+L/ZADoeaTltLx+CVuzkeVIPuybK3jrRfw7YZnmdKsVVHAlEPIAEUNlA==}
+  '@hookform/resolvers@5.4.0':
+    resolution: {integrity: sha512-EIsqr/t/qbinPIhGjMdtvutIN1Kk4uwbROE9/UQ93CAVGR7GkA7Y92+fX80OzXi/OB67jVFYwKGO1WzkxmkFZw==}
     peerDependencies:
       react-hook-form: ^7.55.0
 
@@ -1786,6 +1789,9 @@ packages:
   '@types/estree@1.0.8':
     resolution: {integrity: sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w==}
 
+  '@types/estree@1.0.9':
+    resolution: {integrity: sha512-GhdPgy1el4/ImP05X05Uw4cw2/M93BCUmnEvWZNStlCzEKME4Fkk+YpoA5OiHNQmoS7Cafb8Xa3Pya8m1Qrzeg==}
+
   '@types/geojson@7946.0.16':
     resolution: {integrity: sha512-6C8nqWur3j98U6+lXDfTUWIfgvZU+EumvpHKcYjujKH7woYyLj2sUmff0tRhrqM7BohUw7Pz3ZB1jj2gW9Fvmg==}
 
@@ -1910,8 +1916,8 @@ packages:
   '@uiw/copy-to-clipboard@1.0.20':
     resolution: {integrity: sha512-IFQhS62CLNon1YgYJTEzXR2N3WVXg7V1FaBRDLMlzU6JY5X6Hr3OPAcw4WNoKcz2XcFD6XCgwEjlsmj+JA0mWA==}
 
-  '@uiw/react-markdown-preview@5.1.5':
-    resolution: {integrity: sha512-DNOqx1a6gJR7Btt57zpGEKTfHRlb7rWbtctMRO2f82wWcuoJsxPBrM+JWebDdOD0LfD8oe2CQvW2ICQJKHQhZg==}
+  '@uiw/react-markdown-preview@5.2.1':
+    resolution: {integrity: sha512-JjvcHveT6glhlJYJx1XGBZij6wkw+VwREV6Z6m/GpsjPPdLjF1x8nlPBSB/ATyUF4lD7C8ttMkCqVH9N9XMgEA==}
     peerDependencies:
       react: '>=16.8.0'
       react-dom: '>=16.8.0'
@@ -1919,6 +1925,9 @@ packages:
   '@ungap/structured-clone@1.3.0':
     resolution: {integrity: sha512-WmoN8qaIAo7WTYWbAZuG8PYEhn5fkz7dZrqTBZ7dtt//lL2Gwms1IcnQ5yHqjDfX8Ft5j4YzDM23f87zBfDe9g==}
 
+  '@ungap/structured-clone@1.3.1':
+    resolution: {integrity: sha512-mUFwbeTqrVgDQxFveS+df2yfap6iuP20NAKAsBt5jDEoOTDew+zwLAOilHCeQJOVSvmgCX4ogqIrA0mnyr08yQ==}
+
   '@upsetjs/venn.js@2.0.0':
     resolution: {integrity: sha512-WbBhLrooyePuQ1VZxrJjtLvTc4NVfpOyKx0sKqioq9bX1C1m7Jgykkn8gLrtwumBioXIqam8DLxp88Adbue6Hw==}
 
@@ -2689,8 +2698,8 @@ packages:
   function-bind@1.1.2:
     resolution: {integrity: sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA==}
 
-  fuse.js@7.1.0:
-    resolution: {integrity: sha512-trLf4SzuuUxfusZADLINj+dE8clK1frKdmqiJNb1Es75fmI5oY6X2mxLVUciLLjxqw/xr72Dhy+lER6dGd02FQ==}
+  fuse.js@7.3.0:
+    resolution: {integrity: sha512-plz8RVjfcDedTGfVngWH1jmJvBvAwi1v2jecfDerbEnMcmOYUEEwKFTHbNoCiYyzaK2Ws8lABkTCcRSqCY1q4w==}
     engines: {node: '>=10'}
 
   gensync@1.0.0-beta.2:
@@ -2794,9 +2803,15 @@ packages:
   hast-util-from-parse5@8.0.3:
     resolution: {integrity: sha512-3kxEVkEKt0zvcZ3hCRYI8rqrgwtlIOFMWkbclACvjlDw8Li9S2hk/d51OI0nr/gIpdMHNepwgOKqZ/sy0Clpyg==}
 
+  hast-util-has-property@2.0.1:
+    resolution: {integrity: sha512-X2+RwZIMTMKpXUzlotatPzWj8bspCymtXH3cfG3iQKV+wPF53Vgaqxi/eLqGck0wKq1kS9nvoB1wchbCPEL8sg==}
+
   hast-util-has-property@3.0.0:
     resolution: {integrity: sha512-MNilsvEKLFpV604hwfhVStK0usFY/QmM5zX16bo7EjnAEGofr5YyI37kzopBlZJkHD4t887i+q/C8/tr5Q94cA==}
 
+  hast-util-heading-rank@2.1.1:
+    resolution: {integrity: sha512-iAuRp+ESgJoRFJbSyaqsfvJDY6zzmFoEnL1gtz1+U8gKtGGj1p0CVlysuUAUjq95qlZESHINLThwJzNGmgGZxA==}
+
   hast-util-heading-rank@3.0.0:
     resolution: {integrity: sha512-EJKb8oMUXVHcWZTDepnr+WNbfnXKFNf9duMesmr4S8SXTJBJ9M4Yok08pu9vxdJwdlGRhVumk9mEhkEvKGifwA==}
 
@@ -2833,6 +2848,9 @@ packages:
   hast-util-to-parse5@8.0.1:
     resolution: {integrity: sha512-MlWT6Pjt4CG9lFCjiz4BH7l9wmrMkfkJYCxFwKQic8+RTZgWPuWxwAfjJElsXkex7DJjfSJsQIt931ilUgmwdA==}
 
+  hast-util-to-string@2.0.0:
+    resolution: {integrity: sha512-02AQ3vLhuH3FisaMM+i/9sm4OXGSq1UhOOCpTLLQtHdL3tZt7qil69r8M8iDkZYyC0HCFylcYoP+8IO7ddta1A==}
+
   hast-util-to-string@3.0.1:
     resolution: {integrity: sha512-XelQVTDWvqcl3axRfI0xSeoVKzyIFPwsAGSLIsKdJKQMXDYJS4WYrBNF/8J7RdhIcFI2BOHgAifggsvsxp/3+A==}
 
@@ -2883,8 +2901,8 @@ packages:
     resolution: {integrity: sha512-4fCk79wshMdzMp2rH06qWrJE4iolqLhCUH+OiuIgU++RB0+94NlDL81atO7GX55uUKueo0txHNtvEyI6D7WdMw==}
     engines: {node: '>=0.10.0'}
 
-  idb-keyval@6.2.2:
-    resolution: {integrity: sha512-yjD9nARJ/jb1g+CvD0tlhUHOrJ9Sy0P8T9MF3YaLlHnSRpwPfpTX0XIvpmw3gAJUmEu3FiICLBDPXVwyEvrleg==}
+  idb-keyval@6.2.4:
+    resolution: {integrity: sha512-D/NzHWUmYJGXi++z67aMSrnisb9A3621CyRK5G89JyTlN13C8xf0g04DLxUKMufPem3e3L2JAXR6Z00OWy183Q==}
 
   ignore@5.3.2:
     resolution: {integrity: sha512-hsBTNUqQTDwkWtcdYI2i06Y/nUBEsNEDJKjWdigLvegy8kDuJAS8uRlpkkcQpyEXL0Z/pjDy5HBmMjRCJ2gq+g==}
@@ -4228,12 +4246,6 @@ packages:
       '@types/react': '>=16'
       react: '>=16'
 
-  react-markdown@9.0.3:
-    resolution: {integrity: sha512-Yk7Z94dbgYTOrdk41Z74GoKA7rThnsbbqBTRYuxoe08qvfQ9tJVhmAKw6BJS/ZORG7kTy/s1QvYzSuaoBA1qfw==}
-    peerDependencies:
-      '@types/react': '>=18'
-      react: '>=18'
-
   react-medium-image-zoom@5.4.1:
     resolution: {integrity: sha512-DD2iZYaCfAwiQGR8AN62r/cDJYoXhezlYJc5HY4TzBUGuGge43CptG0f7m0PEIM72aN6GfpjohvY1yYdtCJB7g==}
     peerDependencies:
@@ -4372,8 +4384,8 @@ packages:
   regex@6.1.0:
     resolution: {integrity: sha512-6VwtthbV4o/7+OaAF9I5L5V3llLEsoPyq9P1JVXkedTP33c7MfCG0/5NOPcSJn0TzXcG9YUrR0gQSWioew3LDg==}
 
-  rehype-attr@3.0.3:
-    resolution: {integrity: sha512-Up50Xfra8tyxnkJdCzLBIBtxOcB2M1xdeKe1324U06RAvSjYm7ULSeoM+b/nYPQPVd7jsXJ9+39IG1WAJPXONw==}
+  rehype-attr@4.0.0:
+    resolution: {integrity: sha512-tANn9EmhG4mEZlNdDDRKuS0OXPDvc6P6OjJ1yApzOjIdCvKNLiuU2HdMSLTpiVi3D/FyLK6B+ZZ8PYtRxiGg7Q==}
     engines: {node: '>=16'}
 
   rehype-autolink-headings@7.1.0:
@@ -4408,6 +4420,9 @@ packages:
     resolution: {integrity: sha512-L/FO96EOzSA6bzOam4DVu61/PB3AGKcSPXpa53yMIozoxH4qg1+bVZDF8zh1EsuxtSauAhzt5cCnvoplAaSLrw==}
     engines: {node: '>=16.0.0'}
 
+  rehype-slug@5.1.0:
+    resolution: {integrity: sha512-Gf91dJoXneiorNEnn+Phx97CO7oRMrpi+6r155tTxzGuLtm+QrI4cTwCa9e1rtePdL4i9tSO58PeSS6HWfgsiw==}
+
   rehype-slug@6.0.0:
     resolution: {integrity: sha512-lWyvf/jwu+oS5+hL5eClVd3hNdmwM1kAC0BUvEGD19pajQMIzcNUd/k9GsfQ+FfECvX+JE+e9/btsKH0EjJT6A==}
 
@@ -4822,12 +4837,12 @@ packages:
   util-deprecate@1.0.2:
     resolution: {integrity: sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw==}
 
-  uuid@11.1.0:
-    resolution: {integrity: sha512-0/A9rDy9P7cJ+8w1c9WD9V//9Wj15Ce2MPz8Ri6032usz+NfePxx5AcN3bN+r6ZL6jEo066/yNYB3tn4pQEx+A==}
+  uuid@11.1.1:
+    resolution: {integrity: sha512-vIYxrBCC/N/K+Js3qSN88go7kIfNPssr/hHCesKCQNAjmgvYS2oqr69kIufEG+O4+PfezOH4EbIeHCfFov8ZgQ==}
     hasBin: true
 
-  uuid@13.0.0:
-    resolution: {integrity: sha512-XQegIaBTVUjSHliKqcnFqYypAd4S+WCYt5NIeRs6w/UAry7z8Y9j5ZwRRL4kzq9U3sD6v+85er9FvkEaBpji2w==}
+  uuid@13.0.2:
+    resolution: {integrity: sha512-vzi9uRZ926x4XV73S/4qQaTwPXM2JBj6/6lI/byHH1jOpCzb0zDbfytgA9LcN/hzb2l7WQSQnxITOVx5un/wGw==}
     hasBin: true
 
   uvu@0.5.6:
@@ -4856,8 +4871,8 @@ packages:
   vfile@6.0.3:
     resolution: {integrity: sha512-KzIbH/9tXat2u30jf+smMwFCsno4wHVdNmzFyL+T/L3UGqqk6JKfVqOFOZEpZSHADH1k40ab6NUIXZq422ov3Q==}
 
-  vite@6.4.1:
-    resolution: {integrity: sha512-+Oxm7q9hDoLMyJOYfUYBuHQo+dkAloi33apOPP56pzj+vsdJDzr+j1NISE5pyaAuKL4A3UD34qd0lx5+kfKp2g==}
+  vite@6.4.2:
+    resolution: {integrity: sha512-2N/55r4JDJ4gdrCvGgINMy+HH3iRpNIz8K6SFwVsA+JbQScLiC+clmAxBgwiSPgcG9U15QmvqCGWzMbqda5zGQ==}
     engines: {node: ^18.0.0 || ^20.0.0 || >=22.0.0}
     hasBin: true
     peerDependencies:
@@ -5534,7 +5549,7 @@ snapshots:
       react: 19.2.4
       react-dom: 19.2.4(react@19.2.4)
 
-  '@hookform/resolvers@5.2.2(react-hook-form@7.72.0(react@19.2.4))':
+  '@hookform/resolvers@5.4.0(react-hook-form@7.72.0(react@19.2.4))':
     dependencies:
       '@standard-schema/utils': 0.3.0
       react-hook-form: 7.72.0(react@19.2.4)
@@ -5725,7 +5740,7 @@ snapshots:
       unified: 11.0.5
       url-join: 5.0.0
       use-merge-value: 1.2.0(react@19.2.4)
-      uuid: 13.0.0
+      uuid: 13.0.2
     transitivePeerDependencies:
       - '@babel/core'
       - '@types/mdast'
@@ -6456,12 +6471,12 @@ snapshots:
       postcss: 8.5.8
       tailwindcss: 4.2.2
 
-  '@tailwindcss/vite@4.2.2(vite@6.4.1(@types/node@22.19.15)(jiti@2.6.1)(lightningcss@1.32.0)(yaml@2.8.3))':
+  '@tailwindcss/vite@4.2.2(vite@6.4.2(@types/node@22.19.15)(jiti@2.6.1)(lightningcss@1.32.0)(yaml@2.8.3))':
     dependencies:
       '@tailwindcss/node': 4.2.2
       '@tailwindcss/oxide': 4.2.2
       tailwindcss: 4.2.2
-      vite: 6.4.1(@types/node@22.19.15)(jiti@2.6.1)(lightningcss@1.32.0)(yaml@2.8.3)
+      vite: 6.4.2(@types/node@22.19.15)(jiti@2.6.1)(lightningcss@1.32.0)(yaml@2.8.3)
 
   '@tauri-apps/api@2.11.0': {}
 
@@ -6664,6 +6679,8 @@ snapshots:
 
   '@types/estree@1.0.8': {}
 
+  '@types/estree@1.0.9': {}
+
   '@types/geojson@7946.0.16': {}
 
   '@types/hast@2.3.10':
@@ -6811,14 +6828,14 @@ snapshots:
 
   '@uiw/copy-to-clipboard@1.0.20': {}
 
-  '@uiw/react-markdown-preview@5.1.5(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+  '@uiw/react-markdown-preview@5.2.1(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
     dependencies:
       '@babel/runtime': 7.29.2
       '@uiw/copy-to-clipboard': 1.0.20
       react: 19.2.4
       react-dom: 19.2.4(react@19.2.4)
-      react-markdown: 9.0.3(@types/react@19.2.14)(react@19.2.4)
-      rehype-attr: 3.0.3
+      react-markdown: 10.1.0(@types/react@19.2.14)(react@19.2.4)
+      rehype-attr: 4.0.0
       rehype-autolink-headings: 7.1.0
       rehype-ignore: 2.0.3
       rehype-prism-plus: 2.0.0
@@ -6834,6 +6851,8 @@ snapshots:
 
   '@ungap/structured-clone@1.3.0': {}
 
+  '@ungap/structured-clone@1.3.1': {}
+
   '@upsetjs/venn.js@2.0.0':
     optionalDependencies:
       d3-selection: 3.0.0
@@ -6846,7 +6865,7 @@ snapshots:
       '@use-gesture/core': 10.3.1
       react: 19.2.4
 
-  '@vitejs/plugin-react@4.7.0(vite@6.4.1(@types/node@22.19.15)(jiti@2.6.1)(lightningcss@1.32.0)(yaml@2.8.3))':
+  '@vitejs/plugin-react@4.7.0(vite@6.4.2(@types/node@22.19.15)(jiti@2.6.1)(lightningcss@1.32.0)(yaml@2.8.3))':
     dependencies:
       '@babel/core': 7.29.0
       '@babel/plugin-transform-react-jsx-self': 7.27.1(@babel/core@7.29.0)
@@ -6854,7 +6873,7 @@ snapshots:
       '@rolldown/pluginutils': 1.0.0-beta.27
       '@types/babel__core': 7.20.5
       react-refresh: 0.17.0
-      vite: 6.4.1(@types/node@22.19.15)(jiti@2.6.1)(lightningcss@1.32.0)(yaml@2.8.3)
+      vite: 6.4.2(@types/node@22.19.15)(jiti@2.6.1)(lightningcss@1.32.0)(yaml@2.8.3)
     transitivePeerDependencies:
       - supports-color
 
@@ -7630,7 +7649,7 @@ snapshots:
 
   estree-util-attach-comments@3.0.0:
     dependencies:
-      '@types/estree': 1.0.8
+      '@types/estree': 1.0.9
 
   estree-util-build-jsx@3.0.1:
     dependencies:
@@ -7742,7 +7761,7 @@ snapshots:
 
   function-bind@1.1.2: {}
 
-  fuse.js@7.1.0: {}
+  fuse.js@7.3.0: {}
 
   gensync@1.0.0-beta.2: {}
 
@@ -7871,10 +7890,16 @@ snapshots:
       vfile-location: 5.0.3
       web-namespaces: 2.0.1
 
+  hast-util-has-property@2.0.1: {}
+
   hast-util-has-property@3.0.0:
     dependencies:
       '@types/hast': 3.0.4
 
+  hast-util-heading-rank@2.1.1:
+    dependencies:
+      '@types/hast': 2.3.10
+
   hast-util-heading-rank@3.0.0:
     dependencies:
       '@types/hast': 3.0.4
@@ -7934,7 +7959,7 @@ snapshots:
 
   hast-util-to-estree@3.1.3:
     dependencies:
-      '@types/estree': 1.0.8
+      '@types/estree': 1.0.9
       '@types/estree-jsx': 1.0.5
       '@types/hast': 3.0.4
       comma-separated-tokens: 2.0.3
@@ -7969,7 +7994,7 @@ snapshots:
 
   hast-util-to-jsx-runtime@2.3.6:
     dependencies:
-      '@types/estree': 1.0.8
+      '@types/estree': 1.0.9
       '@types/hast': 3.0.4
       '@types/unist': 3.0.3
       comma-separated-tokens: 2.0.3
@@ -7997,6 +8022,10 @@ snapshots:
       web-namespaces: 2.0.1
       zwitch: 2.0.4
 
+  hast-util-to-string@2.0.0:
+    dependencies:
+      '@types/hast': 2.3.10
+
   hast-util-to-string@3.0.1:
     dependencies:
       '@types/hast': 3.0.4
@@ -8070,7 +8099,7 @@ snapshots:
     dependencies:
       safer-buffer: 2.1.2
 
-  idb-keyval@6.2.2: {}
+  idb-keyval@6.2.4: {}
 
   ignore@5.3.2: {}
 
@@ -8690,7 +8719,7 @@ snapshots:
     dependencies:
       '@types/hast': 3.0.4
       '@types/mdast': 4.0.4
-      '@ungap/structured-clone': 1.3.0
+      '@ungap/structured-clone': 1.3.1
       devlop: 1.1.0
       micromark-util-sanitize-uri: 2.0.1
       trim-lines: 3.0.1
@@ -8760,7 +8789,7 @@ snapshots:
       roughjs: 4.6.6
       stylis: 4.3.6
       ts-dedent: 2.2.0
-      uuid: 11.1.0
+      uuid: 11.1.1
 
   micromark-core-commonmark@1.1.0:
     dependencies:
@@ -8957,7 +8986,7 @@ snapshots:
 
   micromark-extension-mdx-expression@3.0.1:
     dependencies:
-      '@types/estree': 1.0.8
+      '@types/estree': 1.0.9
       devlop: 1.1.0
       micromark-factory-mdx-expression: 2.0.3
       micromark-factory-space: 2.0.1
@@ -8968,7 +8997,7 @@ snapshots:
 
   micromark-extension-mdx-jsx@3.0.2:
     dependencies:
-      '@types/estree': 1.0.8
+      '@types/estree': 1.0.9
       devlop: 1.1.0
       estree-util-is-identifier-name: 3.0.0
       micromark-factory-mdx-expression: 2.0.3
@@ -8985,7 +9014,7 @@ snapshots:
 
   micromark-extension-mdxjs-esm@3.0.0:
     dependencies:
-      '@types/estree': 1.0.8
+      '@types/estree': 1.0.9
       devlop: 1.1.0
       micromark-core-commonmark: 2.0.3
       micromark-util-character: 2.1.1
@@ -9034,7 +9063,7 @@ snapshots:
 
   micromark-factory-mdx-expression@2.0.3:
     dependencies:
-      '@types/estree': 1.0.8
+      '@types/estree': 1.0.9
       devlop: 1.1.0
       micromark-factory-space: 2.0.1
       micromark-util-character: 2.1.1
@@ -9150,7 +9179,7 @@ snapshots:
 
   micromark-util-events-to-acorn@2.0.3:
     dependencies:
-      '@types/estree': 1.0.8
+      '@types/estree': 1.0.9
       '@types/unist': 3.0.3
       devlop: 1.1.0
       estree-util-visit: 2.0.0
@@ -9936,23 +9965,6 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  react-markdown@9.0.3(@types/react@19.2.14)(react@19.2.4):
-    dependencies:
-      '@types/hast': 3.0.4
-      '@types/react': 19.2.14
-      devlop: 1.1.0
-      hast-util-to-jsx-runtime: 2.3.6
-      html-url-attributes: 3.0.1
-      mdast-util-to-hast: 13.2.1
-      react: 19.2.4
-      remark-parse: 11.0.0
-      remark-rehype: 11.1.2
-      unified: 11.0.5
-      unist-util-visit: 5.1.0
-      vfile: 6.0.3
-    transitivePeerDependencies:
-      - supports-color
-
   react-medium-image-zoom@5.4.1(react-dom@19.2.4(react@19.2.4))(react@19.2.4):
     dependencies:
       react: 19.2.4
@@ -10078,7 +10090,7 @@ snapshots:
 
   recma-parse@1.0.0:
     dependencies:
-      '@types/estree': 1.0.8
+      '@types/estree': 1.0.9
       esast-util-from-js: 2.0.1
       unified: 11.0.5
       vfile: 6.0.3
@@ -10120,7 +10132,7 @@ snapshots:
     dependencies:
       regex-utilities: 2.3.0
 
-  rehype-attr@3.0.3:
+  rehype-attr@4.0.0:
     dependencies:
       unified: 11.0.5
       unist-util-visit: 5.0.0
@@ -10201,6 +10213,16 @@ snapshots:
       unified: 11.0.5
       unist-util-visit: 5.1.0
 
+  rehype-slug@5.1.0:
+    dependencies:
+      '@types/hast': 2.3.10
+      github-slugger: 2.0.0
+      hast-util-has-property: 2.0.1
+      hast-util-heading-rank: 2.1.1
+      hast-util-to-string: 2.0.0
+      unified: 10.1.2
+      unist-util-visit: 4.1.2
+
   rehype-slug@6.0.0:
     dependencies:
       '@types/hast': 3.0.4
@@ -10696,9 +10718,9 @@ snapshots:
 
   util-deprecate@1.0.2: {}
 
-  uuid@11.1.0: {}
+  uuid@11.1.1: {}
 
-  uuid@13.0.0: {}
+  uuid@13.0.2: {}
 
   uvu@0.5.6:
     dependencies:
@@ -10741,7 +10763,7 @@ snapshots:
       '@types/unist': 3.0.3
       vfile-message: 4.0.3
 
-  vite@6.4.1(@types/node@22.19.15)(jiti@2.6.1)(lightningcss@1.32.0)(yaml@2.8.3):
+  vite@6.4.2(@types/node@22.19.15)(jiti@2.6.1)(lightningcss@1.32.0)(yaml@2.8.3):
     dependencies:
       esbuild: 0.25.12
       fdir: 6.5.0(picomatch@4.0.3)

BillNote_frontend/src-tauri/tauri.conf.json

@@ -1,7 +1,7 @@
 {
   "$schema": "../node_modules/@tauri-apps/cli/config.schema.json",
   "productName": "BiliNote",
-  "version": "2.0.0",
+  "version": "2.4.0",
   "identifier": "com.jefferyhuang.bilinote",
   "build": {
     "frontendDist": "../dist",

BillNote_frontend/src/App.tsx

@@ -1,6 +1,6 @@
 import './App.css'
 import { lazy, Suspense, useEffect } from 'react'
-import { BrowserRouter, Navigate, Routes, Route } from 'react-router-dom'
+import { BrowserRouter, HashRouter, Navigate, Routes, Route } from 'react-router-dom'
 import { useTaskPolling } from '@/hooks/useTaskPolling.ts'
 import { useCheckBackend } from '@/hooks/useCheckBackend.ts'
 import { systemCheck } from '@/services/system.ts'
@@ -57,12 +57,16 @@ function App() {
     )
   }
 
+  // 桌面端使用 HashRouter 避免刷新 404；Web 端继续使用 BrowserRouter
+  const isTauri = typeof window !== 'undefined' && '__TAURI_INTERNALS__' in window
+  const Router = isTauri ? HashRouter : BrowserRouter
+
   // 后端已初始化，渲染主应用
   return (
     <>
       <StartupBanner />
       <BackendHealthIndicator />
-      <BrowserRouter>
+      <Router>
         <Suspense fallback={<div className="flex h-screen items-center justify-center">加载中…</div>}>
           <Routes>
             <Route path="/onboarding" element={<Onboarding />} />
@@ -86,7 +90,7 @@ function App() {
             </Route>
           </Routes>
         </Suspense>
-      </BrowserRouter>
+      </Router>
     </>
   )
 }

BillNote_frontend/src/pages/HomePage/components/MarkdownViewer.tsx

@@ -14,6 +14,7 @@ import 'react-medium-image-zoom/dist/styles.css'
 import gfm from 'remark-gfm'
 import remarkMath from 'remark-math'
 import rehypeKatex from 'rehype-katex'
+import rehypeSlug from 'rehype-slug'
 import 'katex/dist/katex.min.css'
 import 'github-markdown-css/github-markdown-light.css'
 import { ScrollArea } from '@/components/ui/scroll-area.tsx'
@@ -47,7 +48,7 @@ const steps = [
 ]
 
 const remarkPlugins = [gfm, remarkMath]
-const rehypePlugins = [rehypeKatex]
+const rehypePlugins = [rehypeKatex, rehypeSlug]
 
 /**
  * 构建 ReactMarkdown components 对象，baseURL 用于修正图片路径。
@@ -117,6 +118,51 @@ function createMarkdownComponents(baseURL: string) {
         )
       }
 
+      // 处理笔记内部锚点链接（如目录跳转）
+      if (href?.startsWith('#')) {
+        const handleAnchorClick = (e: React.MouseEvent) => {
+          e.preventDefault()
+          const id = decodeURIComponent(href.slice(1))
+
+          // 1. 优先精确匹配 id
+          let target = document.getElementById(id)
+
+          // 2. 精确失败时按 heading 文本模糊匹配
+          // LLM 生成的目录锚点可能和 heading 实际文本不完全一致
+          //（例如 heading 带 *Content-[00:00]* 后缀，目录链接里没有）
+          if (!target) {
+            const normalize = (s: string) =>
+              s.replace(/[-：:\s*\[\]]/g, '').toLowerCase()
+            const search = normalize(id)
+            const headings = document.querySelectorAll('h1, h2, h3, h4, h5, h6')
+            for (const h of headings) {
+              const text = h.textContent || ''
+              if (normalize(text).includes(search) || search.includes(normalize(text))) {
+                target = h
+                break
+              }
+            }
+          }
+
+          if (target) {
+            target.scrollIntoView({ behavior: 'smooth', block: 'start' })
+          } else {
+            toast.error('未找到对应章节')
+          }
+        }
+
+        return (
+          <a
+            href={href}
+            onClick={handleAnchorClick}
+            className="text-primary hover:text-primary/80 inline-flex items-center gap-0.5 font-medium underline underline-offset-4"
+            {...props}
+          >
+            {children}
+          </a>
+        )
+      }
+
       return (
         <a
           href={href}

BillNote_frontend/src/pages/HomePage/components/MarkmapComponent.tsx

@@ -5,6 +5,171 @@ import { Toolbar } from 'markmap-toolbar'
 import 'markmap-toolbar/dist/style.css'
 import JSZip from 'jszip'
 
+const MIN_EXPORT_FONT_PX = 256
+const MIN_EXPORT_WIDTH = 12800
+const WEB_EXPORT_SCALE_FACTOR = 0.34
+const MAX_EXPORT_SCALE = 24
+const MAX_CANVAS_SIDE = 32767
+const MAX_CANVAS_PIXELS = 268000000
+
+function canvasToBlob(canvas: HTMLCanvasElement): Promise<Blob> {
+  return new Promise((resolve, reject) => {
+    canvas.toBlob((blob) => {
+      if (blob) {
+        resolve(blob)
+      } else {
+        reject(new Error('无法创建PNG图片'))
+      }
+    }, 'image/png')
+  })
+}
+
+function createSvgElement<K extends keyof SVGElementTagNameMap>(tag: K): SVGElementTagNameMap[K] {
+  return document.createElementNS('http://www.w3.org/2000/svg', tag)
+}
+
+function sanitizeSvgForCanvas(svg: SVGSVGElement): SVGSVGElement {
+  const cloned = svg.cloneNode(true) as SVGSVGElement
+
+  // markmap 会在 SVG 的顶层 <g> 上写入当前预览视口的 pan/zoom transform。
+  // 导出时我们按内容 bbox 裁剪，如果保留这个视口 transform，会产生双重偏移，
+  // 导致图片内容跑到角落并留下大片空白。这里只移除顶层视口 transform，
+  // 保留内部节点自身的布局 transform。
+  cloned.querySelector(':scope > g')?.removeAttribute('transform')
+
+  cloned.querySelectorAll('image').forEach(el => el.remove())
+  cloned.querySelectorAll('foreignObject').forEach((foreignObject) => {
+    const textContent = foreignObject.textContent?.replace(/\s+/g, ' ').trim()
+    if (!textContent) {
+      foreignObject.remove()
+      return
+    }
+
+    const x = Number(foreignObject.getAttribute('x') || 0)
+    const y = Number(foreignObject.getAttribute('y') || 0)
+    const height = Number(foreignObject.getAttribute('height') || 20)
+    const text = createSvgElement('text')
+    text.setAttribute('x', String(x))
+    text.setAttribute('y', String(y + height / 2))
+    text.setAttribute('dominant-baseline', 'middle')
+    text.setAttribute('font-size', '14')
+    text.setAttribute('font-family', 'Arial, "Microsoft YaHei", sans-serif')
+    text.setAttribute('fill', '#333')
+    text.textContent = textContent
+    foreignObject.replaceWith(text)
+  })
+
+  return cloned
+}
+
+function getExportFontSize(svg: SVGSVGElement): number {
+  const text = svg.querySelector('text, foreignObject')
+  if (!text) return 14
+
+  const fontSize = Number.parseFloat(getComputedStyle(text).fontSize || '')
+  if (Number.isFinite(fontSize) && fontSize > 0) return fontSize
+
+  const attrSize = Number.parseFloat(text.getAttribute('font-size') || '')
+  return Number.isFinite(attrSize) && attrSize > 0 ? attrSize : 14
+}
+
+function getMindmapBounds(svg: SVGSVGElement) {
+  const target = svg.querySelector('g') || svg
+  const bbox = target.getBBox()
+  const padding = 50
+  return {
+    x: Math.floor(bbox.x - padding),
+    y: Math.floor(bbox.y - padding),
+    width: Math.max(Math.ceil(bbox.width + padding * 2), 1),
+    height: Math.max(Math.ceil(bbox.height + padding * 2), 1),
+  }
+}
+
+function stripMindmapImages(markdown: string) {
+  return (markdown || '')
+    // 思维导图只保留文字结构，图片节点会让预览排版和 PNG 导出效果都很差。
+    .replace(/!\[[^\]]*\]\([^)]*\)/g, '')
+    .replace(/<img\b[^>]*>/gi, '')
+}
+
+function transformMindmap(markdown: string) {
+  return transformer.transform(stripMindmapImages(markdown))
+}
+
+function createExportSvg(svgEl: SVGSVGElement) {
+  const bounds = getMindmapBounds(svgEl)
+  const clonedSvg = sanitizeSvgForCanvas(svgEl)
+
+  clonedSvg.setAttribute('xmlns', 'http://www.w3.org/2000/svg')
+  clonedSvg.setAttribute('xmlns:xlink', 'http://www.w3.org/1999/xlink')
+  clonedSvg.setAttribute('width', String(bounds.width))
+  clonedSvg.setAttribute('height', String(bounds.height))
+  clonedSvg.setAttribute('viewBox', `${bounds.x} ${bounds.y} ${bounds.width} ${bounds.height}`)
+  clonedSvg.setAttribute('preserveAspectRatio', 'xMidYMid meet')
+
+  const bgRect = document.createElementNS('http://www.w3.org/2000/svg', 'rect')
+  bgRect.setAttribute('x', String(bounds.x))
+  bgRect.setAttribute('y', String(bounds.y))
+  bgRect.setAttribute('width', String(bounds.width))
+  bgRect.setAttribute('height', String(bounds.height))
+  bgRect.setAttribute('fill', 'white')
+  const firstG = clonedSvg.querySelector('g')
+  clonedSvg.insertBefore(bgRect, firstG || clonedSvg.firstChild)
+
+  return { clonedSvg, ...bounds }
+}
+
+async function exportSvgToPngBlob(svgEl: SVGSVGElement): Promise<Blob> {
+  const { clonedSvg, width, height } = createExportSvg(svgEl)
+  const svgData = new XMLSerializer().serializeToString(clonedSvg)
+  const svgUrl = URL.createObjectURL(new Blob([svgData], { type: 'image/svg+xml;charset=utf-8' }))
+
+  try {
+    const img = new Image()
+    img.decoding = 'async'
+    img.src = svgUrl
+    await img.decode()
+
+    // 按导图内容尺寸和字号动态反推 PNG 倍率，而不是按预览容器或固定倍率导出。
+    const fontScale = MIN_EXPORT_FONT_PX / getExportFontSize(svgEl)
+    const widthScale = MIN_EXPORT_WIDTH / width
+    const rawScale = Math.max(window.devicePixelRatio || 1, fontScale, widthScale)
+    const sideLimitScale = Math.min(MAX_CANVAS_SIDE / width, MAX_CANVAS_SIDE / height)
+    const pixelLimitScale = Math.sqrt(MAX_CANVAS_PIXELS / (width * height))
+    const baseScale = Math.min(rawScale, MAX_EXPORT_SCALE, sideLimitScale, pixelLimitScale)
+    const scale = Math.max(1, baseScale * WEB_EXPORT_SCALE_FACTOR)
+
+    let currentScale = scale
+    let lastError: unknown
+    while (currentScale >= 1) {
+      try {
+        const canvas = document.createElement('canvas')
+        canvas.width = Math.ceil(width * currentScale)
+        canvas.height = Math.ceil(height * currentScale)
+
+        const ctx = canvas.getContext('2d')
+        if (!ctx) {
+          throw new Error('无法获取Canvas上下文')
+        }
+
+        ctx.fillStyle = '#FFFFFF'
+        ctx.fillRect(0, 0, canvas.width, canvas.height)
+        ctx.setTransform(currentScale, 0, 0, currentScale, 0, 0)
+        ctx.drawImage(img, 0, 0, width, height)
+        ctx.setTransform(1, 0, 0, 1, 0, 0)
+
+        return await canvasToBlob(canvas)
+      } catch (error) {
+        lastError = error
+        currentScale = Math.floor(currentScale / 2)
+      }
+    }
+    throw lastError || new Error('导出PNG失败')
+  } finally {
+    URL.revokeObjectURL(svgUrl)
+  }
+}
+
 export interface MarkmapEditorProps {
   /** 要渲染的 Markdown 文本 */
   value: string
@@ -34,6 +199,13 @@ export default function MarkmapEditor({
 
   // 用于跟踪是否处于全屏状态
   const [isFullscreen, setIsFullscreen] = useState(false)
+  const [pngAction, setPngAction] = useState<'idle' | 'exporting' | 'copying'>('idle')
+  const [pngMessage, setPngMessage] = useState('')
+
+  const showPngMessage = (message: string) => {
+    setPngMessage(message)
+    window.setTimeout(() => setPngMessage(''), 2500)
+  }
 
   // 监听全屏状态变化
   useEffect(() => {
@@ -64,7 +236,7 @@ export default function MarkmapEditor({
   // 导出HTML思维导图
   const exportHtml = () => {
     try {
-      const { root } = transformer.transform(value)
+      const { root } = transformMindmap(value)
       const data = JSON.stringify(root)
       
       // 创建HTML内容
@@ -202,7 +374,7 @@ export default function MarkmapEditor({
   // 导出XMind格式思维导图
   const exportXMind = async () => {
     try {
-      const { root } = transformer.transform(value);
+      const { root } = transformMindmap(value);
 
       // 生成唯一ID
       const generateId = () => Math.random().toString(36).substring(2, 15);
@@ -311,100 +483,44 @@ export default function MarkmapEditor({
     try {
       if (!svgRef.current || !mmRef.current) return;
 
-      const svgEl = svgRef.current;
-      const mm = mmRef.current;
-
-      // 先调用fit()确保显示完整的思维导图内容
-      await mm.fit();
-      // 等待渲染完成
-      await new Promise(resolve => setTimeout(resolve, 100));
-      
-      // 获取SVG实际尺寸
-      const svgWidth = svgEl.width.baseVal.value || svgEl.clientWidth || 800;
-      const svgHeight = svgEl.height.baseVal.value || svgEl.clientHeight || 600;
-      
-      // 设置足够大的缩放比例以确保高清输出
-      const scale = 3;
-      
-      // 克隆SVG以避免修改原始SVG
-      const clonedSvg = svgEl.cloneNode(true) as SVGSVGElement;
-      
-      // 设置SVG的背景为白色
-      const style = document.createElementNS('http://www.w3.org/2000/svg', 'style');
-      style.textContent = 'svg { background-color: white; }';
-      clonedSvg.insertBefore(style, clonedSvg.firstChild);
-      
-      // 确保SVG有正确的命名空间
-      clonedSvg.setAttribute('xmlns', 'http://www.w3.org/2000/svg');
-      clonedSvg.setAttribute('width', svgWidth.toString());
-      clonedSvg.setAttribute('height', svgHeight.toString());
-      
-      // 将SVG转换为Data URI (避免使用Blob URL来解决跨域问题)
-      const svgData = new XMLSerializer().serializeToString(clonedSvg);
-      const svgBase64 = btoa(unescape(encodeURIComponent(svgData)));
-      const dataUri = `data:image/svg+xml;base64,${svgBase64}`;
-      
-      // 创建Canvas
-      const canvas = document.createElement('canvas');
-      canvas.width = svgWidth * scale;
-      canvas.height = svgHeight * scale;
-      
-      // 获取上下文并设置白色背景
-      const ctx = canvas.getContext('2d');
-      if (!ctx) {
-        throw new Error('无法获取Canvas上下文');
-      }
-      
-      // 设置白色背景
-      ctx.fillStyle = '#FFFFFF';
-      ctx.fillRect(0, 0, canvas.width, canvas.height);
-      
-      // 创建Image对象
-      const img = new Image();
-      
-      // 当图片加载完成后，在Canvas上绘制并导出
-      img.onload = () => {
-        try {
-          // 应用缩放
-          ctx.setTransform(scale, 0, 0, scale, 0, 0);
-          
-          // 绘制SVG
-          ctx.drawImage(img, 0, 0);
-          
-          // 重置变换
-          ctx.setTransform(1, 0, 0, 1, 0, 0);
-          
-          // 将Canvas转换为PNG Blob
-          canvas.toBlob((blob) => {
-            if (blob) {
-              // 创建下载链接
-              const url = URL.createObjectURL(blob);
-              const a = document.createElement('a');
-              a.href = url;
-              a.download = `${title || 'mindmap'}.png`;
-              document.body.appendChild(a);
-              a.click();
-              document.body.removeChild(a);
-              URL.revokeObjectURL(url);
-            } else {
-              console.error('无法创建Blob对象');
-            }
-          }, 'image/png');
-        } catch (err) {
-          console.error('Canvas处理失败:', err);
-        }
-      };
-      
-      // 设置图片加载错误处理
-      img.onerror = (error) => {
-        console.error('导出PNG失败（图片加载错误）:', error);
-      };
-      
-      // 开始加载SVG图像 (使用Data URI而不是Blob URL)
-      img.src = dataUri;
-      
+      setPngAction('exporting');
+      setPngMessage('正在生成高清 PNG…');
+      const blob = await exportSvgToPngBlob(svgRef.current);
+      const url = URL.createObjectURL(blob);
+      const a = document.createElement('a');
+      a.href = url;
+      a.download = `${title || 'mindmap'}.png`;
+      document.body.appendChild(a);
+      a.click();
+      document.body.removeChild(a);
+      URL.revokeObjectURL(url);
+      showPngMessage('PNG 已开始下载');
     } catch (error) {
       console.error('导出PNG失败:', error);
+      showPngMessage('导出 PNG 失败，请查看控制台');
+    } finally {
+      setPngAction('idle');
+    }
+  };
+
+  // 复制PNG思维导图
+  const copyPng = async () => {
+    try {
+      if (!svgRef.current || !mmRef.current) return;
+
+      setPngAction('copying');
+      setPngMessage('正在复制高清 PNG…');
+      await navigator.clipboard.write([
+        new ClipboardItem({
+          'image/png': exportSvgToPngBlob(svgRef.current),
+        }),
+      ]);
+      showPngMessage('PNG 已复制');
+    } catch (error) {
+      console.error('复制PNG失败:', error);
+      showPngMessage('复制 PNG 失败，请查看控制台');
+    } finally {
+      setPngAction('idle');
     }
   };
 
@@ -428,7 +544,7 @@ export default function MarkmapEditor({
   useEffect(() => {
     const mm = mmRef.current
     if (!mm) return
-    const { root } = transformer.transform(value)
+    const { root } = transformMindmap(value)
     mm.setData(root).then(() => mm.fit())
   }, [value])
 
@@ -459,8 +575,17 @@ export default function MarkmapEditor({
           onClick={exportPng}
           className="rounded p-1 hover:bg-gray-200"
           title="导出PNG图片"
+          disabled={pngAction !== 'idle'}
         >
-          🖼️
+          {pngAction === 'exporting' ? '⏳' : '🖼️'}
+        </button>
+        <button
+          onClick={copyPng}
+          className="rounded p-1 hover:bg-gray-200"
+          title="复制PNG图片"
+          disabled={pngAction !== 'idle'}
+        >
+          {pngAction === 'copying' ? '⏳' : '📋'}
         </button>
         <button
           onClick={exportHtml}
@@ -483,6 +608,11 @@ export default function MarkmapEditor({
           </button>
         )}
       </div>
+      {pngMessage && (
+        <div className="absolute top-11 right-2 z-20 rounded bg-white/95 px-2 py-1 text-xs text-gray-600 shadow">
+          {pngMessage}
+        </div>
+      )}
 
       {/* 如果需要编辑区，就自己加一个 <textarea> 并把 handleChange 绑上 */}
       {/* <textarea value={value} onChange={handleChange} className="mb-2 p-2 border rounded" /> */}

BillNote_frontend/src/pages/SettingPage/about.tsx

@@ -5,9 +5,14 @@ import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs'
 import { Github, Star, ExternalLink, Download } from 'lucide-react'
 import { ScrollArea } from '@/components/ui/scroll-area.tsx'
 import logo from '@/assets/icon.svg'
-import wechatQr from '@/assets/wechat.png'
+
+// 二维码统一走 GitHub 在线地址：后续在仓库替换图片后，已打包的 App 会自动更新，无需重新发版
+const GITHUB_DOC_RAW = 'https://raw.githubusercontent.com/JefferyHcool/BiliNote/master/doc'
+const wechatQr = `${GITHUB_DOC_RAW}/wechat-gzh.png`
+const remoteInstallQr = `${GITHUB_DOC_RAW}/remote-install-wechat.png`
 
 export default function AboutPage() {
+  const appVersion = __APP_VERSION__
   const images = [
     'https://common-1304618721.cos.ap-chengdu.myqcloud.com/20250504102850.png',
     'https://common-1304618721.cos.ap-chengdu.myqcloud.com/20250504103028.png',
@@ -27,7 +32,7 @@ export default function AboutPage() {
               height={50}
               className="rounded-lg"
             />
-            <h1 className="text-4xl font-bold">BiliNote v2.0.0</h1>
+            <h1 className="text-4xl font-bold">BiliNote v{appVersion}</h1>
           </div>
           <p className="text-muted-foreground mb-6 text-xl italic">
             AI 视频笔记生成工具 让 AI 为你的视频做笔记
@@ -197,12 +202,28 @@ export default function AboutPage() {
         <section className="mb-16">
           <h2 className="mb-8 text-center text-3xl font-bold">联系和加入社区</h2>
           <div className="mx-auto max-w-3xl">
-            <div className="flex flex-col items-center justify-center gap-8">
+            <div className="flex flex-col items-center justify-center gap-10 md:flex-row md:items-start">
               <div className="text-center">
-                <h3 className="mb-3 text-xl font-semibold">BiliNote 交流微信群</h3>
+                <h3 className="mb-3 text-xl font-semibold">BiliNote 公众号</h3>
                 <div className="bg-muted mx-auto flex h-52 w-52 items-center justify-center rounded-md">
-                  <img src={wechatQr} alt="BiliNote 交流微信群" className="h-full w-full object-contain" />
+                  <img src={wechatQr} alt="BiliNote 公众号" className="h-full w-full object-contain" />
                 </div>
+                <p className="text-muted-foreground mt-3 text-sm">扫描公众号，回复「交流群」获取二维码</p>
+              </div>
+              <div className="text-center">
+                <h3 className="mb-3 text-xl font-semibold">BiliNote AI笔记系统一对一搭建服务</h3>
+                <div className="bg-muted mx-auto flex h-52 w-52 items-center justify-center rounded-md">
+                  <img
+                    src={remoteInstallQr}
+                    alt="BiliNote AI笔记系统一对一搭建服务"
+                    className="h-full w-full object-contain"
+                  />
+                </div>
+                <p className="text-muted-foreground mt-3 text-sm">
+                  专人一对一远程协助，从部署到上手全程陪跑
+                  <br />
+                  扫码加微信，备注「搭建服务」即可咨询
+                </p>
               </div>
             </div>
           </div>

BillNote_frontend/src/pages/SettingPage/transcriber.tsx

@@ -10,13 +10,16 @@ import {
   SelectValue,
 } from '@/components/ui/select'
 import { Alert, AlertDescription } from '@/components/ui/alert'
-import { AudioLines, AlertTriangle, CheckCircle2, Download, Loader2, Save, XCircle } from 'lucide-react'
+import { Input } from '@/components/ui/input'
+import { AudioLines, AlertTriangle, CheckCircle2, Download, Loader2, Save, XCircle, Plus, Trash2, Boxes } from 'lucide-react'
 import { toast } from 'react-hot-toast'
 import {
   getTranscriberConfig,
   updateTranscriberConfig,
   getModelsStatus,
   downloadModel,
+  addWhisperModel,
+  deleteWhisperModel,
   TranscriberConfig,
   ModelStatus,
 } from '@/services/transcriber'
@@ -33,6 +36,19 @@ export default function Transcriber() {
   const [modelStatuses, setModelStatuses] = useState<ModelStatus[]>([])
   const [mlxModelStatuses, setMlxModelStatuses] = useState<ModelStatus[]>([])
   const [mlxAvailable, setMlxAvailable] = useState(false)
+  // 自定义模型表单
+  const [newModelName, setNewModelName] = useState('')
+  const [newModelTarget, setNewModelTarget] = useState('')
+  const [addingModel, setAddingModel] = useState(false)
+
+  // 重新拉取配置（不重置用户当前的选择），用于增删自定义模型后刷新下拉与列表
+  const reloadConfig = useCallback(async () => {
+    try {
+      setConfig(await getTranscriberConfig())
+    } catch {
+      // 静默
+    }
+  }, [])
 
   const fetchModelsStatus = useCallback(async () => {
     try {
@@ -123,6 +139,41 @@ export default function Transcriber() {
     }
   }
 
+  const handleAddCustomModel = async () => {
+    const name = newModelName.trim()
+    const target = newModelTarget.trim()
+    if (!name || !target) {
+      toast.error('请填写模型名称和 HF repo_id / 本地路径')
+      return
+    }
+    setAddingModel(true)
+    try {
+      await addWhisperModel({ name, target })
+      toast.success(`已添加自定义模型 ${name}`)
+      setNewModelName('')
+      setNewModelTarget('')
+      await reloadConfig()
+      await fetchModelsStatus()
+    } catch {
+      // 后端的具体错误（如重名）已由请求拦截器 toast，这里不重复提示
+    } finally {
+      setAddingModel(false)
+    }
+  }
+
+  const handleDeleteCustomModel = async (name: string) => {
+    try {
+      await deleteWhisperModel(name)
+      toast.success(`已删除自定义模型 ${name}`)
+      // 删的正好是当前选中的，回退到 tiny，避免选中一个不存在的名称
+      if (selectedModelSize === name) setSelectedModelSize('tiny')
+      await reloadConfig()
+      await fetchModelsStatus()
+    } catch {
+      // 拦截器已提示
+    }
+  }
+
   if (loading) {
     return (
       <div className="flex h-64 items-center justify-center">
@@ -272,6 +323,97 @@ export default function Transcriber() {
           </CardContent>
         </Card>
       )}
+
+      {/* 自定义 Whisper 模型（仅 fast-whisper：名称不符合内置 Systran 约定的模型在此登记映射） */}
+      {selectedType === 'fast-whisper' && (
+        <Card>
+          <CardHeader>
+            <CardTitle className="flex items-center gap-2 text-lg">
+              <Boxes className="h-5 w-5" />
+              自定义模型
+              <span className="text-sm font-normal text-neutral-400">
+                登记名称不符合内置约定的模型
+              </span>
+            </CardTitle>
+          </CardHeader>
+          <CardContent className="space-y-4">
+            <Alert className="text-sm">
+              <AlertDescription>
+                填 <strong>HF repo_id</strong>（如{' '}
+                <code className="rounded bg-neutral-100 px-1">Systran/faster-whisper-large-v3</code>
+                ，会自动下载）或<strong>本地模型目录</strong>（如{' '}
+                <code className="rounded bg-neutral-100 px-1">/app/backend/models/my-whisper</code>
+                ，目录内需含 <code className="rounded bg-neutral-100 px-1">model.bin</code>，下载会跳过）。
+                添加后即可在上方「模型大小」下拉中选用。Docker 部署请把模型目录挂载进容器（见 README 的{' '}
+                <code className="rounded bg-neutral-100 px-1">models</code> 卷）。
+              </AlertDescription>
+            </Alert>
+
+            {config.whisper_custom_models &&
+            Object.keys(config.whisper_custom_models).length > 0 ? (
+              <div className="space-y-2">
+                {Object.entries(config.whisper_custom_models).map(([name, target]) => {
+                  const status = modelStatuses.find(m => m.model_size === name)
+                  return (
+                    <div
+                      key={name}
+                      className="flex items-center justify-between gap-3 rounded-md border px-4 py-2.5"
+                    >
+                      <div className="min-w-0">
+                        <div className="flex items-center gap-2 font-medium">
+                          {name}
+                          {status?.downloaded && (
+                            <CheckCircle2 className="h-3.5 w-3.5 text-green-500" />
+                          )}
+                          {status?.downloading && (
+                            <Loader2 className="h-3.5 w-3.5 animate-spin text-neutral-400" />
+                          )}
+                        </div>
+                        <div className="truncate text-xs text-neutral-400" title={target}>
+                          {target}
+                        </div>
+                      </div>
+                      <Button
+                        size="sm"
+                        variant="ghost"
+                        className="text-red-500 hover:text-red-600"
+                        onClick={() => handleDeleteCustomModel(name)}
+                      >
+                        <Trash2 className="h-4 w-4" />
+                      </Button>
+                    </div>
+                  )
+                })}
+              </div>
+            ) : (
+              <p className="text-sm text-neutral-400">还没有自定义模型</p>
+            )}
+
+            <div className="flex flex-col gap-2 sm:flex-row sm:items-center">
+              <Input
+                placeholder="模型名称（自定义，如 my-large-v3）"
+                value={newModelName}
+                onChange={e => setNewModelName(e.target.value)}
+                className="sm:max-w-[220px]"
+              />
+              <Input
+                placeholder="HF repo_id 或本地路径"
+                value={newModelTarget}
+                onChange={e => setNewModelTarget(e.target.value)}
+                className="flex-1"
+              />
+              <Button onClick={handleAddCustomModel} disabled={addingModel}>
+                {addingModel ? (
+                  <Loader2 className="mr-1 h-4 w-4 animate-spin" />
+                ) : (
+                  <Plus className="mr-1 h-4 w-4" />
+                )}
+                添加
+              </Button>
+            </div>
+          </CardContent>
+        </Card>
+      )}
     </div>
   )
 }

BillNote_frontend/src/services/transcriber.ts

@@ -5,6 +5,10 @@ export interface TranscriberConfig {
   whisper_model_size: string
   available_types: { value: string; label: string }[]
   whisper_model_sizes: string[]
+  /** 内置模型映射：size → HF repo_id */
+  whisper_builtin_models?: Record<string, string>
+  /** 用户自定义模型映射：名称 → HF repo_id 或本地路径 */
+  whisper_custom_models?: Record<string, string>
   mlx_whisper_available: boolean
 }
 
@@ -41,3 +45,23 @@ export const downloadModel = async (data: {
 }) => {
   return await request.post('/transcriber_download', data)
 }
+
+export interface WhisperModelsResponse {
+  builtin: Record<string, string>
+  custom: Record<string, string>
+}
+
+/** 列出内置 + 自定义 whisper 模型映射 */
+export const listWhisperModels = async (): Promise<WhisperModelsResponse> => {
+  return await request.get('/whisper_models')
+}
+
+/** 新增自定义模型映射（名称 → HF repo_id 或本地路径） */
+export const addWhisperModel = async (data: { name: string; target: string }) => {
+  return await request.post('/whisper_models', data)
+}
+
+/** 删除自定义模型映射（不会删除已下载的模型文件） */
+export const deleteWhisperModel = async (name: string) => {
+  return await request.delete(`/whisper_models/${encodeURIComponent(name)}`)
+}

BillNote_frontend/src/vite-env.d.ts

@@ -1 +1,3 @@
 /// <reference types="vite/client" />
+
+declare const __APP_VERSION__: string

BillNote_frontend/vite.config.ts

@@ -1,11 +1,25 @@
 import { defineConfig, loadEnv } from 'vite'
 import react from '@vitejs/plugin-react'
+import fs from 'fs'
 import path from 'path'
 import { fileURLToPath } from 'url'
 import tailwindcss from '@tailwindcss/vite'
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 
+function readAppVersion() {
+  const fallbackVersion = '0.0.0'
+
+  try {
+    const tauriConfigPath = path.resolve(__dirname, 'src-tauri/tauri.conf.json')
+    const tauriConfig = JSON.parse(fs.readFileSync(tauriConfigPath, 'utf-8')) as { version?: string }
+    return tauriConfig.version || fallbackVersion
+  }
+  catch {
+    return fallbackVersion
+  }
+}
+
 // https://vitejs.dev/config/
 export default defineConfig(({ mode }) => {
   // 在 Docker 环境中，父目录可能没有 .env 文件，使用当前目录
@@ -14,9 +28,13 @@ export default defineConfig(({ mode }) => {
 
   const apiBaseUrl = env.VITE_API_BASE_URL || 'http://127.0.0.1:8483'
   const port = parseInt(env.VITE_FRONTEND_PORT || '3015', 10)
+  const appVersion = env.VITE_APP_VERSION || process.env.VITE_APP_VERSION || readAppVersion()
 
   return {
     base: './',
+    define: {
+      __APP_VERSION__: JSON.stringify(appVersion),
+    },
     plugins: [react(), tailwindcss()],
     resolve: {
       alias: {

CHANGELOG.md

@@ -2,6 +2,41 @@
 
 本项目所有重要变更记录于此。格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [2.4.0] - 2026-06-07
+
+### Added
+
+- **可配置 Whisper 模型**：转写设置支持自定义 Whisper 模型与名称映射，可指定自定义 HuggingFace repo 或本地路径（新增 `backend/app/transcriber/whisper_models.py` + 测试），转写设置页可选择 / 配置模型。
+- **关注公众号获取交流群**：关于页群二维码改为公众号二维码，关注公众号后回复「交流群」即可获取最新群二维码，避免群码过期失效。
+
+### Fixed
+
+- **浏览器扩展**：修复标题显示异常，优化脑图（Markmap）导出。
+
+### Docs
+
+- **GPU/CUDA 部署**：README 补全 GPU/CUDA 部署说明。
+
+## [2.3.4] - 2026-05-27
+
+### Added
+
+- **一对一搭建服务二维码**：新增「BiliNote AI 笔记系统一对一搭建服务」二维码（README + 关于页），扫码加微信、备注「搭建服务」即可咨询。
+
+## [2.3.3] - 2026-05-22
+
+### Fixed
+
+- **预构建 Docker 镜像数据持久化**：文档的 `docker run` 只挂了 `data/`（媒体缓存），而 SQLite 数据库（LLM 供应商配置 + 笔记历史）和笔记文件不在该卷下，导致删除 / 升级容器时丢失配置与历史。现将数据库重定向到 `/app/backend/data/bili_note.db`、笔记到 `data/note_results`（随 data 卷持久化）；README 更新为挂载 `data` / `config` / `static` / `models` 四个数据卷，并提示**勿**挂整个 `/app/backend`（命名卷会固化镜像内代码，导致 `docker pull` 升级不生效）。`docker-compose` 路径本就正确（`./backend:/app` 整目录绑挂），未受影响。
+
+## [2.3.2] - 2026-05-22
+
+### Fixed
+
+- **后端启动崩溃（Docker）**：`python:3.11-slim` 基础镜像升级到 Debian 13 / glibc 2.41 后，`ctranslate2` 4.5.0 预编译库带「可执行栈」标记被 glibc 拒绝加载（`cannot enable executable stack ... Invalid argument`）。由于 `from faster_whisper import WhisperModel` 在顶层 import，import 失败直接拖垮整个后端启动 → 容器反复重启。升级 `ctranslate2` 4.5.0→4.6.0（wheel 加入 `noexecstack` 链接标志，从二进制层根治）
+- **whisper 模型误报「离线模式找不到模型」**：下载（modelscope 自定义目录）与加载（faster-whisper HF cache）布局不一致导致命不中缓存。统一为下载 / 加载 / 完整性检测 / 损坏自愈都走 HF cache 布局，并向后兼容老 modelscope 目录
+- **桌面端构建产物版本恒为 2.0.0**：Release 工作流在 `pnpm tauri build` 前从 git tag 注入版本号到 `tauri.conf.json`，使产物版本与 Release 版本对齐
+
 ## [2.3.1] - 2026-05-22
 
 ### Changed

Dockerfile.complete

@@ -35,6 +35,10 @@ COPY ./backend /tmp/backend
 ARG BASE_REGISTRY=docker.io
 FROM ${BASE_REGISTRY}/library/node:20-alpine AS frontend-builder
 
+# 可由发布 workflow 从 git tag 注入，用于前端 About 页展示版本；未传时由 Vite 回退读取 tauri.conf.json。
+ARG VITE_APP_VERSION=
+ENV VITE_APP_VERSION=${VITE_APP_VERSION}
+
 # pnpm 版本 pin 到 9 系列：
 # - lockfile (BillNote_frontend/pnpm-lock.yaml) 是 lockfileVersion '9.0'，由 pnpm 9 生成
 # - pnpm 11+ 要求 Node 22+，与 node:20 不兼容（ERR_UNKNOWN_BUILTIN_MODULE）
@@ -95,14 +99,16 @@ COPY ./nginx/default.conf /etc/nginx/conf.d/default.conf
 # 在 [supervisord] 块用 environment= 设兜底默认值；在 [program:backend] 用
 # %(ENV_*)s 显式引用，等价于「把 host 通过 docker run -e 或 env_file 传进来的
 # 变量再透传给 python main.py」。漏掉这一步就是用户「改 .env 没反应」的根因。
-RUN mkdir -p /var/log/supervisor
+# /app/backend/data 用于持久化数据库与笔记（见下方 DATABASE_URL / NOTE_OUTPUT_DIR），
+# 预建好目录，避免不挂卷启动时 sqlite 因父目录不存在而创建库失败。
+RUN mkdir -p /var/log/supervisor /app/backend/data
 COPY <<EOF /etc/supervisor/conf.d/supervisord.conf
 [supervisord]
 nodaemon=true
 user=root
 logfile=/var/log/supervisor/supervisord.log
 pidfile=/var/run/supervisord.pid
-environment=BACKEND_PORT="8483",BACKEND_HOST="0.0.0.0",TRANSCRIBER_TYPE="fast-whisper",WHISPER_MODEL_SIZE="tiny",FFMPEG_BIN_PATH="",HF_ENDPOINT="https://hf-mirror.com",STATIC="/static",OUT_DIR="./static/screenshots",DATA_DIR="data",NOTE_OUTPUT_DIR="note_results",IMAGE_BASE_URL="/static/screenshots",ENV="production",GROQ_TRANSCRIBER_MODEL="whisper-large-v3-turbo"
+environment=BACKEND_PORT="8483",BACKEND_HOST="0.0.0.0",TRANSCRIBER_TYPE="fast-whisper",WHISPER_MODEL_SIZE="tiny",FFMPEG_BIN_PATH="",HF_ENDPOINT="https://hf-mirror.com",STATIC="/static",OUT_DIR="./static/screenshots",DATA_DIR="data",NOTE_OUTPUT_DIR="data/note_results",DATABASE_URL="sqlite:////app/backend/data/bili_note.db",IMAGE_BASE_URL="/static/screenshots",ENV="production",GROQ_TRANSCRIBER_MODEL="whisper-large-v3-turbo"
 
 [program:nginx]
 command=nginx -g "daemon off;"
@@ -118,7 +124,7 @@ stdout_logfile=/var/log/supervisor/backend.log
 stderr_logfile=/var/log/supervisor/backend.log
 autorestart=true
 priority=20
-environment=BACKEND_PORT="%(ENV_BACKEND_PORT)s",BACKEND_HOST="%(ENV_BACKEND_HOST)s",TRANSCRIBER_TYPE="%(ENV_TRANSCRIBER_TYPE)s",WHISPER_MODEL_SIZE="%(ENV_WHISPER_MODEL_SIZE)s",FFMPEG_BIN_PATH="%(ENV_FFMPEG_BIN_PATH)s",HF_ENDPOINT="%(ENV_HF_ENDPOINT)s",STATIC="%(ENV_STATIC)s",OUT_DIR="%(ENV_OUT_DIR)s",DATA_DIR="%(ENV_DATA_DIR)s",NOTE_OUTPUT_DIR="%(ENV_NOTE_OUTPUT_DIR)s",IMAGE_BASE_URL="%(ENV_IMAGE_BASE_URL)s",ENV="%(ENV_ENV)s",GROQ_TRANSCRIBER_MODEL="%(ENV_GROQ_TRANSCRIBER_MODEL)s"
+environment=BACKEND_PORT="%(ENV_BACKEND_PORT)s",BACKEND_HOST="%(ENV_BACKEND_HOST)s",TRANSCRIBER_TYPE="%(ENV_TRANSCRIBER_TYPE)s",WHISPER_MODEL_SIZE="%(ENV_WHISPER_MODEL_SIZE)s",FFMPEG_BIN_PATH="%(ENV_FFMPEG_BIN_PATH)s",HF_ENDPOINT="%(ENV_HF_ENDPOINT)s",STATIC="%(ENV_STATIC)s",OUT_DIR="%(ENV_OUT_DIR)s",DATA_DIR="%(ENV_DATA_DIR)s",NOTE_OUTPUT_DIR="%(ENV_NOTE_OUTPUT_DIR)s",DATABASE_URL="%(ENV_DATABASE_URL)s",IMAGE_BASE_URL="%(ENV_IMAGE_BASE_URL)s",ENV="%(ENV_ENV)s",GROQ_TRANSCRIBER_MODEL="%(ENV_GROQ_TRANSCRIBER_MODEL)s"
 EOF
 
 # 修改 nginx 配置以使用本地 backend

README.md

@@ -3,7 +3,7 @@
     <p align="center">
   <img src="./doc/icon.svg" alt="BiliNote Banner" width="50" height="50"  />
 </p>
-<h1 align="center" > BiliNote v2.3.1</h1>
+<h1 align="center" > BiliNote v2.4.0</h1>
 </div>
 
 <p align="center"><i>AI 视频笔记生成工具 让 AI 为你的视频做笔记</i></p>
@@ -53,6 +53,16 @@ BiliNote 是一个开源的 AI 视频笔记助手，支持通过哔哩哔哩、Y
 
 > Windows 用户请注意：一定要在没有中文路径的环境下运行。
 
+## 💎 BiliNote AI笔记系统一对一搭建服务
+
+提供 **BiliNote AI笔记系统一对一搭建服务**：专人一对一远程协助，从环境部署、模型配置到上手使用全程陪跑，帮你快速跑通整套系统。扫码添加微信，备注「搭建服务」即可咨询：
+
+<table align="center">
+  <tr>
+    <td align="center"><img src="./doc/remote-install-wechat.png" alt="BiliNote AI笔记系统一对一搭建服务" width="220" /><br/>BiliNote AI笔记系统一对一搭建服务</td>
+  </tr>
+</table>
+
 ## 🔧 功能特性
 
 - 支持多平台：Bilibili、YouTube、本地视频、抖音、快手
@@ -163,10 +173,17 @@ docker pull ghcr.io/jefferyhcool/bilinote:latest
 
 docker run -d -p 80:80 \
   -v bilinote-data:/app/backend/data \
+  -v bilinote-config:/app/backend/config \
+  -v bilinote-static:/app/backend/static \
+  -v bilinote-models:/app/backend/models \
   --name bilinote \
   ghcr.io/jefferyhcool/bilinote:latest
 ```
 
+上面四个卷分别持久化：`data`（SQLite 数据库 + 生成的笔记）、`config`（LLM 供应商配置 / Cookie / 转写设置）、`static`（笔记引用的视频截图）、`models`（Whisper 模型缓存，可选，避免每次重新下载）。这样 `docker pull` 升级新镜像、删旧容器重建后，配置和历史都不会丢。
+
+> ⚠️ **不要**用 `-v 卷名:/app/backend` 挂整个后端目录——命名卷会用首次启动时的镜像内容固化，之后 `docker pull` 升级也会被旧代码盖住，导致「升级不生效」。只挂上面这些数据子目录即可。
+
 访问：`http://localhost`
 
 也可以使用 docker-compose 本地构建：
@@ -286,10 +303,42 @@ sudo apt install ffmpeg
 >
 > Docker 部署已内置 FFmpeg，无需额外安装。
 
-### 🚀 CUDA 加速（可选）
-若你希望更快地执行音频转写任务，可使用具备 NVIDIA GPU 的机器，并启用 fast-whisper + CUDA 加速版本：
+### 🚀 CUDA / GPU 加速（可选）
 
-具体 `fast-whisper` 配置方法，请参考：[fast-whisper 项目地址](http://github.com/SYSTRAN/faster-whisper#requirements)
+本地 **Faster Whisper** 转写可用 NVIDIA GPU 加速（在线引擎 Groq / 必剪 / 快手 与 GPU 无关）。仓库已自带 GPU 镜像与编排，**无需改代码、无需手动配置 device**——后端会自动检测 CUDA，可用就走 GPU，否则回退 CPU。
+
+**1. 宿主机前提**
+
+- NVIDIA 显卡 + 较新驱动（CUDA ≥ 12.4），宿主机 `nvidia-smi` 能正常输出；
+- 安装 [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html)（最易漏的一步，没它 Docker 进不去 GPU）。装完验证：
+  ```bash
+  docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi
+  ```
+  能列出显卡即 OK。
+
+**2. 切换到 GPU 编排**（在源码目录里）
+
+CPU 与 GPU 两套 compose 用了相同的容器名，先停掉当前栈再起 GPU 栈：
+
+```bash
+docker-compose down                                     # 停掉当前（CPU）栈
+docker-compose -f docker-compose.gpu.yml up --build -d   # 用 GPU 栈重建
+```
+
+- GPU 栈用 `backend/Dockerfile.gpu`（CUDA 12.4.1 + cuDNN 基础镜像，并额外装 torch 用于 CUDA 检测），compose 已声明 `deploy...devices: nvidia` 自动透传 GPU。
+- **数据不丢**：两套 compose 都把 `./backend` 整目录绑挂进容器，数据库 / 配置 / 已下载模型都保留。
+- 首次构建较大较慢（CUDA 基础镜像数 GB + torch），耐心等。
+
+**3. 启用并确认**
+
+- 「设置 → 音频转写配置」转写引擎选 **Faster Whisper（本地）**，GPU 下可放心选大模型（如 `large-v3`）。
+- 确认真的走了 GPU：`docker logs bilinote-backend | grep -i cuda` 看到 `CUDA 可用，使用 GPU`；或转写时宿主机 `nvidia-smi` 能看到 python 进程占显存。
+
+**国内镜像**：GPU compose 支持 `BASE_REGISTRY` / `APT_MIRROR` / `PIP_INDEX` 这几个 build-arg（注意 `BASE_REGISTRY` 选的源必须支持 `nvidia/cuda` 命名空间，否则拉不到 CUDA 基础镜像）。
+
+**起来了但没走 GPU？** 依次排查：① 宿主机 `nvidia-smi` 是否正常 → ② NVIDIA Container Toolkit 是否装好（上面 `--gpus all` 测试是否通过）→ ③ `docker logs bilinote-backend` 是否有 CUDA / cuDNN 报错（驱动 CUDA 版本需 ≥ 12.4）。
+
+`fast-whisper` 本身的 GPU 依赖说明可参考：[faster-whisper 项目](https://github.com/SYSTRAN/faster-whisper#requirements)
 
 ### 🐳 使用 Docker 一键部署
 
@@ -302,10 +351,17 @@ docker pull ghcr.io/jefferyhcool/bilinote:latest
 # 运行容器
 docker run -d -p 80:80 \
   -v bilinote-data:/app/backend/data \
+  -v bilinote-config:/app/backend/config \
+  -v bilinote-static:/app/backend/static \
+  -v bilinote-models:/app/backend/models \
   --name bilinote \
   ghcr.io/jefferyhcool/bilinote:latest
 ```
 
+上面四个卷分别持久化：`data`（SQLite 数据库 + 生成的笔记）、`config`（LLM 供应商配置 / Cookie / 转写设置）、`static`（笔记引用的视频截图）、`models`（Whisper 模型缓存，可选，避免每次重新下载）。这样 `docker pull` 升级新镜像、删旧容器重建后，配置和历史都不会丢。
+
+> ⚠️ **不要**用 `-v 卷名:/app/backend` 挂整个后端目录——命名卷会用首次启动时的镜像内容固化，之后 `docker pull` 升级也会被旧代码盖住，导致「升级不生效」。只挂上面这些数据子目录即可。
+
 访问：`http://localhost`
 
 也可以使用 docker-compose 本地构建：
@@ -314,8 +370,8 @@ docker run -d -p 80:80 \
 # 标准部署
 docker-compose up -d
 
-# GPU 加速部署（需要 NVIDIA GPU）
-docker-compose -f docker-compose.gpu.yml up -d
+# GPU 加速部署（需要 NVIDIA GPU + NVIDIA Container Toolkit，详见上方「CUDA / GPU 加速」）
+docker-compose -f docker-compose.gpu.yml up --build -d
 ```
 
 ## 🧠 TODO
@@ -330,18 +386,11 @@ docker-compose -f docker-compose.gpu.yml up -d
 
 ### Contact and Join-联系和加入社区
 
-扫码加入 BiliNote 交流微信群（共 5 个群，任选一个即可；二维码会定期更新，如已失效请到 [Issues](https://github.com/JefferyHcool/BiliNote/issues) 反馈）：
+扫描下方公众号二维码，关注后回复 **「交流群」** 即可获取最新的微信交流群二维码（群码会自动更新，避免过期失效）：
 
 <table align="center">
   <tr>
-    <td align="center"><img src="./doc/wechat-group-1.png" alt="BiliNote 交流群 1" width="200" /><br/>交流群 1</td>
-    <td align="center"><img src="./doc/wechat-group-2.png" alt="BiliNote 交流群 2" width="200" /><br/>交流群 2</td>
-    <td align="center"><img src="./doc/wechat-group-3.png" alt="BiliNote 交流群 3" width="200" /><br/>交流群 3</td>
-  </tr>
-  <tr>
-    <td align="center"><img src="./doc/wechat-group-4.png" alt="BiliNote 交流群 4" width="200" /><br/>交流群 4</td>
-    <td align="center"><img src="./doc/wechat-group-5.png" alt="BiliNote 交流群 5" width="200" /><br/>交流群 5</td>
-    <td></td>
+    <td align="center"><img src="./doc/wechat-gzh.png" alt="BiliNote 公众号" width="200" /><br/>BiliNote 公众号</td>
   </tr>
 </table>
 

backend/app/downloaders/bilibili_downloader.py

@@ -1,6 +1,9 @@
+import base64
 import os
 import json
 import logging
+import random
+import string
 import tempfile
 from abc import ABC
 from typing import Union, Optional, List
@@ -18,6 +21,54 @@ from app.services.cookie_manager import CookieConfigManager
 logger = logging.getLogger(__name__)
 
 
+def _patch_bilibili_extractor():
+    """
+    Monkey-patch yt-dlp's BilibiliBaseIE._download_playinfo to inject the
+    dm_img_* / web_location risk-control parameters that Bilibili's
+    wbi/playurl gateway started requiring (returns HTTP 412 without them).
+
+    The parameter format (string.printable source + [:-2] base64 truncation)
+    mirrors yt-dlp's own implementation for the same fields in the channel
+    search endpoint (yt_dlp/extractor/bilibili.py, BiliBiliSpaceIE).
+    """
+    try:
+        from yt_dlp.extractor.bilibili import BilibiliBaseIE
+
+        # Guard: skip if already patched (e.g. module reloaded in tests)
+        if getattr(BilibiliBaseIE._download_playinfo, '_bili_dm_patched', False):
+            return
+
+        _original_download_playinfo = BilibiliBaseIE._download_playinfo
+
+        def _patched_download_playinfo(self, bvid, cid, headers=None, query=None):
+            # Inject dummy risk-control fingerprints expected by Bilibili's gateway.
+            # The [:-2] truncation and string.printable source intentionally match
+            # yt-dlp's own pattern used for the x/space/wbi/arc/search endpoint.
+            extra = {
+                'web_location': 1550101,
+                'dm_img_list': '[]',
+                'dm_img_str': base64.b64encode(
+                    ''.join(random.choices(string.printable, k=random.randint(16, 64))).encode()
+                )[:-2].decode(),
+                'dm_cover_img_str': base64.b64encode(
+                    ''.join(random.choices(string.printable, k=random.randint(32, 128))).encode()
+                )[:-2].decode(),
+                'dm_img_inter': '{"ds":[],"wh":[6093,6631,31],"of":[430,760,380]}',
+            }
+            # Caller-supplied query params take precedence over the dummy values
+            merged_query = {**extra, **(query or {})}
+            return _original_download_playinfo(self, bvid, cid, headers=headers, query=merged_query)
+
+        _patched_download_playinfo._bili_dm_patched = True
+        BilibiliBaseIE._download_playinfo = _patched_download_playinfo
+        logger.info("Applied Bilibili wbi/playurl dm_img patch to yt-dlp BilibiliBaseIE")
+    except Exception as e:
+        logger.warning("Failed to apply Bilibili dm_img patch: %s", e)
+
+
+_patch_bilibili_extractor()
+
+
 class BilibiliDownloader(Downloader, ABC):
     def __init__(self):
         super().__init__()

backend/app/routers/config.py

@@ -61,16 +61,53 @@ WHISPER_MODEL_SIZES = ["tiny", "base", "small", "medium", "large-v3", "large-v3-
 @router.get("/transcriber_config")
 def get_transcriber_config():
     from app.transcriber.transcriber_provider import MLX_WHISPER_AVAILABLE
+    from app.transcriber.whisper_models import get_registry, BUILTIN_WHISPER_MODELS
 
+    registry = get_registry()
     config = transcriber_config_manager.get_config()
     return R.success(data={
         **config,
         "available_types": AVAILABLE_TRANSCRIBER_TYPES,
-        "whisper_model_sizes": WHISPER_MODEL_SIZES,
+        # 内置可见档位 + 用户自定义模型，供前端下拉
+        "whisper_model_sizes": registry.visible_model_names(),
+        "whisper_builtin_models": BUILTIN_WHISPER_MODELS,
+        "whisper_custom_models": registry.get_custom_models(),
         "mlx_whisper_available": MLX_WHISPER_AVAILABLE,
     })
 
 
+class WhisperCustomModelRequest(BaseModel):
+    name: str
+    target: str  # HF repo_id（如 Systran/faster-whisper-large-v3）或本地模型目录路径
+
+
+@router.get("/whisper_models")
+def list_whisper_models():
+    """列出内置 + 用户自定义的 whisper 模型映射。"""
+    from app.transcriber.whisper_models import get_registry, BUILTIN_WHISPER_MODELS
+    reg = get_registry()
+    return R.success(data={"builtin": BUILTIN_WHISPER_MODELS, "custom": reg.get_custom_models()})
+
+
+@router.post("/whisper_models")
+def add_whisper_model(data: WhisperCustomModelRequest):
+    """新增自定义 whisper 模型映射（名称 → HF repo_id 或本地路径）。"""
+    from app.transcriber.whisper_models import get_registry
+    try:
+        custom = get_registry().add_custom_model(data.name, data.target)
+    except ValueError as e:
+        return R.error(msg=str(e))
+    return R.success(data={"custom": custom}, msg="已添加自定义模型")
+
+
+@router.delete("/whisper_models/{name}")
+def delete_whisper_model(name: str):
+    """删除自定义 whisper 模型映射（不会删除已下载的模型文件）。"""
+    from app.transcriber.whisper_models import get_registry
+    custom = get_registry().remove_custom_model(name)
+    return R.success(data={"custom": custom}, msg="已删除自定义模型")
+
+
 @router.post("/transcriber_config")
 def update_transcriber_config(data: TranscriberConfigRequest):
     config = transcriber_config_manager.update_config(
@@ -119,12 +156,34 @@ _downloading: dict[str, str] = {}  # model_size -> status ("downloading" | "done
 def _check_whisper_model_exists(model_size: str, subdir: str = "whisper") -> bool:
     """检查指定 whisper 模型是否已下载完整到本地。
 
-    必须 model.bin 落盘才算完成，仅有空目录或半成品不能算「已下载」——
-    否则监控页会显示绿勾但加载时报「Unable to open file 'model.bin'」。
+    先把模型名 resolve 成可加载标识，再按类型判定：
+      - 本地路径模型 → 直接看该目录下有没有 model.bin
+      - HF repo_id → 看 HF cache 布局
+        <model_dir>/models--{org}--{name}/snapshots/<hash>/model.bin
+        （历史 modelscope 布局 <model_dir>/whisper-{size}/model.bin 也兼容识别）
     """
-    model_dir = get_model_dir(subdir)
-    model_path = os.path.join(model_dir, f"whisper-{model_size}")
-    return (Path(model_path) / "model.bin").exists()
+    from app.transcriber.whisper_models import (
+        resolve_whisper_model,
+        is_local_target,
+        hf_cache_dirname,
+    )
+    try:
+        target = resolve_whisper_model(model_size)
+    except Exception:
+        return False
+    if is_local_target(target):
+        return (Path(target) / "model.bin").exists()
+
+    model_dir = Path(get_model_dir(subdir))
+    # HF cache 布局（适配任意 org/repo，不再写死 Systran）
+    hf_repo_dir = model_dir / hf_cache_dirname(target) / "snapshots"
+    if hf_repo_dir.exists():
+        for snapshot in hf_repo_dir.iterdir():
+            if (snapshot / "model.bin").exists():
+                return True
+    # 历史 modelscope 布局（向后兼容老用户）
+    legacy = model_dir / f"whisper-{model_size}" / "model.bin"
+    return legacy.exists()
 
 
 def _check_mlx_whisper_model_exists(model_size: str) -> bool:
@@ -148,9 +207,10 @@ def _check_mlx_whisper_model_exists(model_size: str) -> bool:
 
 @router.get("/transcriber_models_status")
 def get_transcriber_models_status():
-    """返回所有 whisper 模型的下载状态。"""
+    """返回所有 whisper 模型的下载状态（含用户自定义模型）。"""
+    from app.transcriber.whisper_models import get_registry
     statuses = []
-    for size in WHISPER_MODEL_SIZES:
+    for size in get_registry().visible_model_names():
         downloaded = _check_whisper_model_exists(size, "whisper")
         download_status = _downloading.get(size)
         statuses.append({
@@ -189,24 +249,48 @@ class ModelDownloadRequest(BaseModel):
 
 
 def _do_download_whisper(model_size: str):
-    """后台下载 faster-whisper 模型。"""
-    from app.transcriber.whisper import MODEL_MAP
-    from modelscope import snapshot_download
+    """后台下载 faster-whisper 模型（支持内置 size / 自定义 repo_id / 本地路径）。
+
+    模型名先 resolve：
+      - 本地路径模型：无需下载，目录里有 model.bin 即 done，否则 failed；
+      - HF repo_id：snapshot_download 到 HF cache 布局（cache_dir=model_dir），
+        与加载逻辑 WhisperModel(download_root=model_dir) 完全对齐。
+    """
+    from huggingface_hub import snapshot_download
+    from app.transcriber.whisper_models import resolve_whisper_model, is_local_target
 
     try:
         _downloading[model_size] = "downloading"
         model_dir = get_model_dir("whisper")
-        model_path = os.path.join(model_dir, f"whisper-{model_size}")
-        # 用 model.bin 判定而非目录存在：半成品目录不能算「已下载」
-        if (Path(model_path) / "model.bin").exists():
+
+        # 已经下好就不重复下
+        if _check_whisper_model_exists(model_size, "whisper"):
             _downloading[model_size] = "done"
             return
-        repo_id = MODEL_MAP.get(model_size)
-        if not repo_id:
-            _downloading[model_size] = "failed"
+
+        target = resolve_whisper_model(model_size)
+        if is_local_target(target):
+            # 本地模型不下载，只校验 model.bin 是否就位
+            ok = (Path(target) / "model.bin").exists()
+            _downloading[model_size] = "done" if ok else "failed"
+            if not ok:
+                logger.warning(f"本地模型 {model_size} 路径 {target} 下没有 model.bin，无法使用")
             return
-        logger.info(f"开始下载 whisper 模型: {model_size}")
-        snapshot_download(repo_id, local_dir=model_path)
+
+        logger.info(f"开始下载 whisper 模型: {model_size} ← {target}")
+        # 跟 faster-whisper utils.py 用同样的 allow_patterns，避免多下无关文件；
+        # 不传 local_dir 让它走 HF 默认 cache 布局（与加载逻辑对齐）
+        snapshot_download(
+            target,
+            cache_dir=model_dir,
+            allow_patterns=[
+                "config.json",
+                "preprocessor_config.json",
+                "model.bin",
+                "tokenizer.json",
+                "vocabulary.*",
+            ],
+        )
         logger.info(f"whisper 模型下载完成: {model_size}")
         _downloading[model_size] = "done"
     except Exception as e:
@@ -246,11 +330,11 @@ def _do_download_mlx_whisper(model_size: str):
 
 @router.post("/transcriber_download")
 def download_transcriber_model(data: ModelDownloadRequest, background_tasks: BackgroundTasks):
-    """触发后台下载指定的 whisper 模型。"""
-    if data.model_size not in WHISPER_MODEL_SIZES:
-        return R.error(msg=f"不支持的模型大小: {data.model_size}")
-
+    """触发后台下载指定的 whisper 模型（fast-whisper 支持内置档位 + 自定义模型）。"""
     if data.transcriber_type == "mlx-whisper":
+        # mlx 只认内置档位（mlx-community 的固定映射）
+        if data.model_size not in WHISPER_MODEL_SIZES:
+            return R.error(msg=f"MLX 不支持的模型大小: {data.model_size}")
         if platform.system() != "Darwin":
             return R.error(msg="MLX Whisper 仅支持 macOS")
         key = f"mlx-{data.model_size}"
@@ -258,6 +342,10 @@ def download_transcriber_model(data: ModelDownloadRequest, background_tasks: Bac
             return R.success(msg="模型正在下载中")
         background_tasks.add_task(_do_download_mlx_whisper, data.model_size)
     else:
+        # fast-whisper：内置档位 / 自定义 repo_id / 本地路径都允许
+        from app.transcriber.whisper_models import get_registry
+        if not get_registry().is_known(data.model_size):
+            return R.error(msg=f"不支持的模型: {data.model_size}（请先在自定义模型中登记）")
         if _downloading.get(data.model_size) == "downloading":
             return R.success(msg="模型正在下载中")
         background_tasks.add_task(_do_download_whisper, data.model_size)

backend/app/services/provider.py

@@ -129,6 +129,10 @@ class ProviderService:
         try:
         # 过滤掉空值
             filtered_data = {k: v for k, v in data.items() if v is not None and k != 'id'}
+            # 防御掩码污染：前端展示时 api_key 被 mask_key() 处理过（如 a92f****...2d3a），
+            # 如果用户未重新输入直接保存，带星号的值不应覆盖原 key。
+            if 'api_key' in filtered_data and '*' in str(filtered_data.get('api_key', '')):
+                filtered_data.pop('api_key')
             print('更新模型供应商',filtered_data)
             update_provider(id, **filtered_data)
             # 获取更新后的供应商信息

backend/app/transcriber/whisper.py

@@ -3,6 +3,11 @@ from faster_whisper import WhisperModel
 from app.decorators.timeit import timeit
 from app.models.transcriber_model import TranscriptSegment, TranscriptResult
 from app.transcriber.base import Transcriber
+from app.transcriber.whisper_models import (
+    resolve_whisper_model,
+    is_local_target,
+    hf_cache_dirname,
+)
 from app.utils.env_checker import is_cuda_available, is_torch_installed
 from app.utils.logger import get_logger
 from app.utils.path_helper import get_model_dir
@@ -11,8 +16,6 @@ from events import transcription_finished
 from pathlib import Path
 import os
 import shutil
-from tqdm import tqdm
-from modelscope import snapshot_download
 
 
 '''
@@ -20,19 +23,16 @@ from modelscope import snapshot_download
 '''
 logger=get_logger(__name__)
 
-MODEL_MAP={
-    "tiny": "pengzhendong/faster-whisper-tiny",
-    'base':'pengzhendong/faster-whisper-base',
-    'small':'pengzhendong/faster-whisper-small',
-    'medium':'pengzhendong/faster-whisper-medium',
-    'large-v1':'pengzhendong/faster-whisper-large-v1',
-    'large-v2':'pengzhendong/faster-whisper-large-v2',
-    'large-v3':'pengzhendong/faster-whisper-large-v3',
-    'large-v3-turbo':'pengzhendong/faster-whisper-large-v3-turbo',
-}
-
+# 历史遗留：之前用 modelscope 下载到自定义目录然后把路径传给 WhisperModel。
+# 但 faster-whisper 1.1.1 的 download_model（utils.py:76）逻辑是：
+# 只要 size_or_id 里含 "/" 就当 HF repo_id 处理，没有「本地目录直接返回」分支。
+# 我们传 /app/models/whisper/whisper-tiny 进去 → 被当成不存在的 HF repo →
+# 在线请求失败 → fallback local_files_only=True → HF cache 找不到（因为是
+# modelscope 目录布局不是 HF）→ LocalEntryNotFoundError，误导说"离线模式"。
+# 解法：彻底让 faster-whisper 自己处理下载——传 size name，配 download_root
+# 作为 HF cache 根目录，HF_ENDPOINT 已经在 Dockerfile 里指到 hf-mirror.com，
+# 国内能用。删掉 modelscope 那一套，避免布局不匹配。
 class WhisperTranscriber(Transcriber):
-    # TODO:修改为可配置
     def __init__(
             self,
             model_size: str = "base",
@@ -48,44 +48,53 @@ class WhisperTranscriber(Transcriber):
                 print('没有 cuda 使用 cpu进行计算')
 
         self.compute_type = compute_type or ("float16" if self.device == "cuda" else "int8")
+        self.model_size = model_size
 
         model_dir = get_model_dir("whisper")
-        model_path = os.path.join(model_dir, f"whisper-{model_size}")
-        repo_id = MODEL_MAP[model_size]
-
-        # 第一步：目录 / model.bin 不在 → 下载。
-        # 关键判据用 model.bin 而不是目录存在：首次下载若被打断（网络中断 / 磁盘满 /
-        # 容器被 kill）会留下半成品目录，只看目录存在会跳过下载。
-        model_bin = Path(model_path) / "model.bin"
-        if not model_bin.exists():
-            if Path(model_path).exists():
-                logger.warning(f"模型目录 {model_path} 存在但 model.bin 缺失（上次下载未完成），重新下载")
-            else:
-                logger.info(f"模型 whisper-{model_size} 不存在，开始下载...")
-            model_path = snapshot_download(repo_id, local_dir=model_path)
-            logger.info("模型下载完成")
-
-        # 第二步：加载。model.bin 可能存在但【内容截断】（下载到一半被 kill），
-        # 此时 WhisperModel() 会抛 "File model.bin is incomplete: failed to read a buffer..."。
-        # 捕获后删掉损坏目录、重新下载、再试一次——自愈，避免 500 死循环。
         try:
-            self.model = WhisperModel(
-                model_size_or_path=model_path,
-                device=self.device,
-                compute_type=self.compute_type,
-                download_root=model_dir,
-            )
+            self.model = self._build_model(model_size, model_dir)
         except Exception as e:
-            logger.warning(f"加载 whisper-{model_size} 失败（疑似模型文件损坏 / 截断）：{e}；删除后重新下载")
-            shutil.rmtree(model_path, ignore_errors=True)
-            model_path = snapshot_download(repo_id, local_dir=model_path)
-            logger.info("模型重新下载完成，重试加载")
-            self.model = WhisperModel(
-                model_size_or_path=model_path,
-                device=self.device,
-                compute_type=self.compute_type,
-                download_root=model_dir,
+            # 自愈：损坏 / 截断 / 半成品 cache → 删掉对应 HF cache 重下一次
+            logger.warning(f"加载 whisper-{model_size} 失败：{e}；清理 cache 后重新下载")
+            self._purge_cache(model_dir, model_size)
+            self.model = self._build_model(model_size, model_dir)
+
+    def _build_model(self, model_size: str, model_dir: str) -> WhisperModel:
+        # resolve 把模型名映射成可加载标识：内置 size→Systran repo_id、自定义映射、
+        # 直通的 repo_id 或本地路径。faster-whisper 对本地目录走 os.path.isdir 分支，
+        # 对 repo_id 走 download_model(cache_dir=download_root)，两者都吃 model_size_or_path。
+        target = resolve_whisper_model(model_size)
+        return WhisperModel(
+            model_size_or_path=target,
+            device=self.device,
+            compute_type=self.compute_type,
+            download_root=model_dir,
+        )
+
+    @staticmethod
+    def _purge_cache(model_dir: str, model_size: str) -> None:
+        """加载失败时清掉对应 HF cache 的 snapshot 目录，强制下次重下。
+
+        关键：本地路径模型**绝不删**——那是用户自己的文件，删了就是数据丢失；
+        只清 HF cache 布局 <model_dir>/models--{org}--{name}/（含历史 modelscope 目录）。
+        """
+        try:
+            target = resolve_whisper_model(model_size)
+        except Exception:
+            target = model_size
+        if is_local_target(target):
+            logger.warning(
+                f"模型 {model_size} 指向本地路径 {target}，加载失败不清理用户文件，请检查该目录是否完整"
             )
+            return
+        candidates = [
+            Path(model_dir) / hf_cache_dirname(target),       # HF cache: models--org--name
+            Path(model_dir) / f"whisper-{model_size}",        # 历史 modelscope 目录，顺手清掉
+        ]
+        for path in candidates:
+            if path.exists():
+                logger.info(f"清理损坏 cache: {path}")
+                shutil.rmtree(path, ignore_errors=True)
     @staticmethod
     def is_torch_installed() -> bool:
         try:

backend/app/transcriber/whisper_models.py

@@ -0,0 +1,156 @@
+"""fast-whisper 模型名 → 可加载标识（HF repo_id 或本地路径）的映射注册表。
+
+背景：faster-whisper 加载时 `WhisperModel(model_size_or_path=...)` 接受三种入参——
+内置 size 名、HF repo_id（含 "/"）、或本地模型目录（`os.path.isdir` 命中则直接用）。
+此前后端把「size → Systran/faster-whisper-{size}」这层约定**隐式**散落在加载/下载/
+检测三处，用户想用命名不符合该约定的模型（比如社区微调版、或自己下到本地的模型）就接不上。
+
+本模块把映射**显式化 + 可配置**（对齐 mlx_whisper_transcriber.MLX_MODEL_MAP 的模式）：
+  - 内置：size → Systran/faster-whisper-{size}
+  - 自定义：用户在 config/whisper_models.json 登记 {名称: "<repo_id 或本地路径>"}
+    （JSON 持久化；Docker 下随 config 卷持久化）
+
+解析优先级（resolve）：自定义 > 内置 > 直通（含 "/" 当 repo_id；已存在目录当本地路径）。
+加载 / 下载 / 完整性检测三处统一调用 resolve，路径不再各写各的。
+"""
+import json
+import os
+from pathlib import Path
+from typing import Dict, List
+
+from app.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+# 内置模型：size → faster-whisper 兼容的 HF repo_id（CTranslate2 转换版，Systran 官方维护）。
+BUILTIN_WHISPER_MODELS: Dict[str, str] = {
+    "tiny": "Systran/faster-whisper-tiny",
+    "base": "Systran/faster-whisper-base",
+    "small": "Systran/faster-whisper-small",
+    "medium": "Systran/faster-whisper-medium",
+    "large-v1": "Systran/faster-whisper-large-v1",
+    "large-v2": "Systran/faster-whisper-large-v2",
+    "large-v3": "Systran/faster-whisper-large-v3",
+    "large-v3-turbo": "Systran/faster-whisper-large-v3-turbo",
+}
+
+# 前端下拉默认展示的内置档位（保持与历史 WHISPER_MODEL_SIZES 一致，不把 8 个全列出来）
+DEFAULT_VISIBLE_BUILTINS: List[str] = ["tiny", "base", "small", "medium", "large-v3", "large-v3-turbo"]
+
+
+def is_local_target(target: str) -> bool:
+    """判断解析出的 target 是本地路径而非 HF repo_id。
+
+    HF repo_id 形如 'Org/Name'（恰一个斜杠、无前导斜杠、非已存在目录）。
+    本地路径：绝对路径 / 以 . 或 ~ 开头 / 已存在的目录。
+    """
+    if not target:
+        return False
+    if os.path.isabs(target) or target.startswith(".") or target.startswith("~"):
+        return True
+    return os.path.isdir(target)
+
+
+def hf_cache_dirname(repo_id: str) -> str:
+    """huggingface_hub snapshot 的本地缓存目录名：Org/Name → models--Org--Name。"""
+    return "models--" + repo_id.replace("/", "--")
+
+
+class WhisperModelRegistry:
+    """内置 + 用户自定义的 whisper 模型映射，自定义部分持久化到 JSON。"""
+
+    def __init__(self, filepath: str = "config/whisper_models.json"):
+        self.path = Path(filepath)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+
+    # ---- 持久化 ----
+    def _read_custom(self) -> Dict[str, str]:
+        if not self.path.exists():
+            return {}
+        try:
+            with self.path.open("r", encoding="utf-8") as f:
+                data = json.load(f) or {}
+        except Exception as e:
+            logger.warning(f"读取自定义 whisper 模型配置失败，按空处理: {e}")
+            return {}
+        out: Dict[str, str] = {}
+        for name, val in data.items():
+            if isinstance(val, str) and val.strip():
+                out[name] = val.strip()
+            elif isinstance(val, dict) and isinstance(val.get("target"), str):
+                out[name] = val["target"].strip()
+        return out
+
+    def _write_custom(self, data: Dict[str, str]) -> None:
+        with self.path.open("w", encoding="utf-8") as f:
+            json.dump(data, f, ensure_ascii=False, indent=2)
+
+    # ---- 查询 ----
+    def get_custom_models(self) -> Dict[str, str]:
+        return self._read_custom()
+
+    def visible_model_names(self) -> List[str]:
+        """给前端下拉 / 下载状态用：默认可见内置档位 + 全部自定义名称。"""
+        names = list(DEFAULT_VISIBLE_BUILTINS)
+        for name in self._read_custom():
+            if name not in names:
+                names.append(name)
+        return names
+
+    def is_known(self, name: str) -> bool:
+        try:
+            self.resolve(name)
+            return True
+        except ValueError:
+            return False
+
+    def resolve(self, name: str) -> str:
+        """模型名 → 可加载标识（HF repo_id 或本地路径）。
+
+        优先级：自定义映射 > 内置映射 > 直通（含 "/" 的 repo_id / 已存在的本地目录）。
+        无法识别时抛 ValueError。
+        """
+        name = (name or "").strip()
+        custom = self._read_custom()
+        if name in custom:
+            return custom[name]
+        if name in BUILTIN_WHISPER_MODELS:
+            return BUILTIN_WHISPER_MODELS[name]
+        # 直通：用户直接把 repo_id（含 "/"）或本地已存在目录当 model_size 传进来
+        if "/" in name or os.path.isdir(name):
+            return name
+        raise ValueError(
+            f"未知 whisper 模型 '{name}'。内置可选: {', '.join(BUILTIN_WHISPER_MODELS)}；"
+            "或在「音频转写配置」添加自定义模型（HF repo_id 或本地路径）。"
+        )
+
+    # ---- 增删 ----
+    def add_custom_model(self, name: str, target: str) -> Dict[str, str]:
+        name = (name or "").strip()
+        target = (target or "").strip()
+        if not name or not target:
+            raise ValueError("模型名称与目标（HF repo_id 或本地路径）都不能为空")
+        if name in BUILTIN_WHISPER_MODELS:
+            raise ValueError(f"'{name}' 与内置模型重名，请换一个名称")
+        data = self._read_custom()
+        data[name] = target
+        self._write_custom(data)
+        return data
+
+    def remove_custom_model(self, name: str) -> Dict[str, str]:
+        data = self._read_custom()
+        data.pop((name or "").strip(), None)
+        self._write_custom(data)
+        return data
+
+
+# 模块级单例
+_registry = WhisperModelRegistry()
+
+
+def get_registry() -> WhisperModelRegistry:
+    return _registry
+
+
+def resolve_whisper_model(name: str) -> str:
+    return _registry.resolve(name)

backend/ffmpeg_helper.py

@@ -1,11 +1,41 @@
 import os
 import subprocess
+import sys
 from dotenv import load_dotenv
 
 from app.utils.logger import get_logger
 logger = get_logger(__name__)
 
-load_dotenv()
+
+def _load_dotenv_from_multiple_paths():
+    """尝试多个位置加载 .env，适配源码运行和 PyInstaller 打包场景。
+
+    PyInstaller 打包后当前工作目录是 EXE 所在目录，而源码运行时 .env
+    通常在项目根目录或 backend/ 同级。遍历常见候选路径确保能命中。
+    """
+    candidates = []
+    # 1. 当前工作目录（EXE 所在目录）
+    candidates.append(os.path.join(os.getcwd(), '.env'))
+    # 2. 本脚本所在目录（backend/）
+    script_dir = os.path.dirname(os.path.abspath(__file__))
+    candidates.append(os.path.join(script_dir, '.env'))
+    # 3. 项目根目录（backend/../.env）
+    candidates.append(os.path.join(script_dir, '..', '.env'))
+    # 4. PyInstaller 打包后的 _internal/ 子目录
+    if getattr(sys, 'frozen', False):
+        exe_dir = os.path.dirname(sys.executable)
+        candidates.append(os.path.join(exe_dir, '_internal', '.env'))
+
+    for path in candidates:
+        normalized = os.path.normpath(path)
+        if os.path.isfile(normalized):
+            load_dotenv(normalized)
+            return
+    # 都没找到，fallback 到默认行为（从 CWD 找）
+    load_dotenv()
+
+
+_load_dotenv_from_multiple_paths()
 def check_ffmpeg_exists() -> bool:
     """
     检查 ffmpeg 是否可用。优先使用 FFMPEG_BIN_PATH 环境变量指定的路径。

backend/requirements.txt

@@ -24,7 +24,7 @@ click-repl==0.3.0
 colorama==0.4.6
 coloredlogs==15.0.1
 cssselect2==0.8.0
-ctranslate2==4.5.0
+ctranslate2==4.6.0
 distro==1.9.0
 dnspython==2.7.0
 email_validator==2.2.0

backend/tests/test_whisper_models.py

@@ -0,0 +1,132 @@
+"""Unit tests for app.transcriber.whisper_models（whisper 模型名→标识 的映射注册表）。
+
+直接按文件路径加载被测模块，并桩掉 app.utils.logger，避免触发 app/__init__.py
+（会 import faster_whisper / ctranslate2 等重依赖），使本测试无需安装转写依赖即可运行。
+"""
+import importlib.util
+import logging
+import os
+import pathlib
+import sys
+import tempfile
+import types
+import unittest
+
+ROOT = pathlib.Path(__file__).resolve().parents[1]
+MODULE_PATH = ROOT / "app" / "transcriber" / "whisper_models.py"
+
+
+def _load_module():
+    if "app" not in sys.modules:
+        app_pkg = types.ModuleType("app")
+        app_pkg.__path__ = []  # 标记为 package
+        sys.modules["app"] = app_pkg
+    if "app.utils" not in sys.modules:
+        utils_pkg = types.ModuleType("app.utils")
+        utils_pkg.__path__ = []
+        sys.modules["app.utils"] = utils_pkg
+    if "app.utils.logger" not in sys.modules:
+        logger_mod = types.ModuleType("app.utils.logger")
+        logger_mod.get_logger = lambda name=None: logging.getLogger(name or "test")
+        sys.modules["app.utils.logger"] = logger_mod
+    spec = importlib.util.spec_from_file_location("whisper_models_under_test", MODULE_PATH)
+    assert spec and spec.loader
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    return mod
+
+
+wm = _load_module()
+
+
+class TestResolve(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.cfg = os.path.join(self.tmp.name, "whisper_models.json")
+        self.reg = wm.WhisperModelRegistry(filepath=self.cfg)
+
+    def tearDown(self):
+        self.tmp.cleanup()
+
+    def test_builtin_resolves_to_systran(self):
+        self.assertEqual(self.reg.resolve("tiny"), "Systran/faster-whisper-tiny")
+        self.assertEqual(self.reg.resolve("large-v3-turbo"), "Systran/faster-whisper-large-v3-turbo")
+
+    def test_passthrough_repo_id(self):
+        # 用户直接把 HF repo_id 当 model_size 传进来（含 "/"）
+        self.assertEqual(self.reg.resolve("SomeOrg/my-whisper-ct2"), "SomeOrg/my-whisper-ct2")
+
+    def test_unknown_raises(self):
+        with self.assertRaises(ValueError):
+            self.reg.resolve("definitely-not-a-model")
+
+    def test_custom_overrides_and_persists(self):
+        self.reg.add_custom_model("myhf", "someorg/whisper-ct2")
+        self.assertEqual(self.reg.resolve("myhf"), "someorg/whisper-ct2")
+        # 新实例读同一文件 → 确认持久化（Docker 下随 config 卷保留）
+        reg2 = wm.WhisperModelRegistry(filepath=self.cfg)
+        self.assertEqual(reg2.resolve("myhf"), "someorg/whisper-ct2")
+
+    def test_custom_can_override_builtin_key_resolution(self):
+        # 自定义优先级高于内置：把 "tiny" 强行指到别的 repo（resolve 层允许；add 层禁止重名）
+        self.reg._write_custom({"tiny": "Other/tiny-ct2"})
+        self.assertEqual(self.reg.resolve("tiny"), "Other/tiny-ct2")
+
+    def test_local_path_resolution_and_detection(self):
+        model_dir = os.path.join(self.tmp.name, "mymodel")
+        os.makedirs(model_dir)
+        self.reg.add_custom_model("local1", model_dir)
+        self.assertEqual(self.reg.resolve("local1"), model_dir)
+        self.assertTrue(wm.is_local_target(self.reg.resolve("local1")))
+
+    def test_bare_existing_dir_passthrough(self):
+        # 没登记、但直接传一个已存在目录 → 直通为本地路径
+        model_dir = os.path.join(self.tmp.name, "bare")
+        os.makedirs(model_dir)
+        self.assertEqual(self.reg.resolve(model_dir), model_dir)
+
+    def test_add_rejects_builtin_collision_and_empty(self):
+        with self.assertRaises(ValueError):
+            self.reg.add_custom_model("tiny", "x/y")  # 与内置重名
+        with self.assertRaises(ValueError):
+            self.reg.add_custom_model("", "x/y")
+        with self.assertRaises(ValueError):
+            self.reg.add_custom_model("ok", "")
+
+    def test_remove(self):
+        self.reg.add_custom_model("tmpm", "a/b")
+        self.assertIn("tmpm", self.reg.get_custom_models())
+        self.reg.remove_custom_model("tmpm")
+        self.assertNotIn("tmpm", self.reg.get_custom_models())
+
+    def test_visible_includes_builtin_and_custom(self):
+        self.reg.add_custom_model("zzz", "a/b")
+        names = self.reg.visible_model_names()
+        self.assertIn("tiny", names)
+        self.assertIn("large-v3", names)
+        self.assertIn("zzz", names)
+
+    def test_is_known(self):
+        self.assertTrue(self.reg.is_known("base"))
+        self.assertTrue(self.reg.is_known("Org/Name"))
+        self.assertFalse(self.reg.is_known("nope-not-real"))
+
+
+class TestHelpers(unittest.TestCase):
+    def test_hf_cache_dirname(self):
+        self.assertEqual(
+            wm.hf_cache_dirname("Systran/faster-whisper-tiny"),
+            "models--Systran--faster-whisper-tiny",
+        )
+        self.assertEqual(wm.hf_cache_dirname("Org/Name"), "models--Org--Name")
+
+    def test_is_local_target(self):
+        self.assertTrue(wm.is_local_target("/abs/path"))
+        self.assertTrue(wm.is_local_target("./rel"))
+        self.assertTrue(wm.is_local_target("~/home/model"))
+        self.assertFalse(wm.is_local_target("Org/Name"))  # repo_id 不是本地路径
+        self.assertFalse(wm.is_local_target(""))
+
+
+if __name__ == "__main__":
+    unittest.main()