VideoSearch v0.1.0

VideoSearch 是一款本机运行的视频聚合搜索桌面应用。它通过 Electron 启动本地 FastAPI 服务，由 Vue 界面并发检索多个已启用资源站，统一展示视频详情和播放线路，并在本机保存搜索历史、收藏、观看进度、日志与监控数据。

当前桌面打包支持 macOS 与 Windows。macOS 产物按构建机 CPU 架构生成；Windows 应在 Windows 主机或 CI runner 上构建。

核心能力

多源搜索：按启用站点并发搜索，逐站展示搜索中、成功或失败状态，失败站点可单独重试。
视频详情：统一整理海报、简介、演职员、年份、评分、状态和按线路分组的剧集。
视频播放：基于 Artplayer 与 HLS.js 播放 HLS 或普通媒体地址，支持线路/剧集切换、倍速、画中画、全屏和自动连播。
个人数据：在本地保存搜索历史、收藏和观看位置，并在首页提供继续观看入口。
资源站管理：支持站点增删改、启停、单站/批量连接测试，以及配置导入导出。
日志与监控：支持日志筛选、分页、详情、JSON/CSV 导出和清理，并聚合请求趋势、站点性能、热门关键词和健康状态。
桌面编排：Electron 自动启动后端、等待健康检查、处理启动失败重试，并提供无边框窗口控制。

系统结构

flowchart LR
    User[用户] --> Desktop[Electron 桌面壳]
    Desktop --> UI[Vue 前端]
    Desktop --> Backend[FastAPI 本地后端]
    UI --> Backend
    Backend --> Sites[第三方资源站]
    Backend --> Data[(SQLite)]
    Backend --> Files[配置与日志]
    Sites --> Media[外部媒体地址]
    UI --> Media

Electron 负责桌面窗口和本地后端进程生命周期。
Vue 前端负责页面交互、并发搜索状态、播放器和数据可视化。
FastAPI 后端负责资源站配置、外部请求、数据适配、个人数据和日志统计。
SQLite 与本地文件保存单机用户数据，不依赖远程账号服务。

技术栈

版本约束来自当前依赖清单；实际锁定版本见对应 lock 文件或模块说明文档。

范围	技术
桌面端	Electron `^43.2.0`、electron-builder `^26.15.3`、electron-updater `6.8.9`
前端	Vue `^3.5.13`、Pinia `^3.0.1`、Vue Router `^4.5.0`、Axios `^1.7.9`
播放与图表	Artplayer `^5.4.0`、HLS.js `^1.5.20`、ECharts `^5.5.1`
样式与构建	Tailwind CSS `^3.4.17`、Vite `^6.0.7`、FontAwesome 6
后端	Python `>=3.11`、FastAPI `>=0.115.0`、Uvicorn `>=0.30.0`
数据与外部请求	SQLAlchemy `>=2.0.51`、SQLite、HTTPX `>=0.27.0`
环境与打包	uv、Pydantic Settings、PyInstaller、electron-updater、NSIS

项目结构

LocalVideoSearch/
├── backend/                 # FastAPI 后端、SQLite 数据层和 PyInstaller 入口
│   ├── app/
│   ├── entry.py
│   ├── pyproject.toml
│   └── uv.lock
├── electron/                # Electron 主进程与 preload 安全桥接
├── frontend/                # Vue 3 前端及 Vite/Tailwind 配置
├── resources/               # 首次运行使用的默认资源站配置
├── doc/                     # 项目结构导航和业务模块说明
├── 规范文档/                # 前后端开发规范入口
├── package.json             # Electron 启动与 macOS/Windows 打包配置
└── README.md

完整目录职责和逐文件说明见项目结构导航文档。

环境要求

请先安装：

Node.js 与 npm（项目未固定具体版本）
Python 3.11 或更高版本
uv

开发态后端虚拟环境必须位于 backend/.venv/。Electron 会按平台查找：

Windows：backend/.venv/Scripts/python.exe
macOS / Linux：backend/.venv/bin/python

安装依赖

在项目根目录执行：

npm install
npm --prefix frontend install
uv sync --directory backend --group build

三条命令分别安装 Electron、前端和 Python 后端依赖。

开发运行

一键启动

依赖安装完成后：

macOS

./start-dev.command

start-dev.command 会先尝试结束占用 4739、4740 端口的进程，再启动 Vite 和 Electron。执行前请确认这些端口上没有其他需要保留的服务。

Windows

start-dev.bat

两个脚本都会先启动前端开发服务，再启动 Electron；Electron 会自动启动本地 FastAPI 后端。

手动启动

使用两个终端，在项目根目录分别执行：

# 终端 1：前端开发服务
npm --prefix frontend run dev

# 终端 2：Electron；会自动启动后端
npm run electron

单独调试后端

uv run --directory backend uvicorn app.main:app \
  --host 127.0.0.1 \
  --port 4740 \
  --reload

Windows 也可以运行 start-backend.bat。单独打开前端而不启动 Electron 时，需要同时运行此后端服务。

端口与运行配置

服务	默认地址	说明
Vite 开发服务	`http://127.0.0.1:4739`	仅开发态使用
FastAPI 本地服务	`http://127.0.0.1:4740`	Electron 启动后端并等待健康检查通过

后端支持通过环境变量或 backend/.env 覆盖配置；Electron 桌面模式会明确传入固定主机、端口和应用数据目录。

配置项	默认值	适用范围
`API_HOST`	`127.0.0.1`	后端监听地址；桌面模式固定为本机回环地址
`API_PORT`	`4740`	后端端口；桌面模式固定使用该端口
`APP_DATA_DIR`	按平台推导	配置、数据库和日志的可写目录
`VITE_API_BASE_URL`	`http://127.0.0.1:4740`	不通过 Electron 运行前端时的后端地址

普通接口使用统一响应结构：

{
  "code": 0,
  "message": "success",
  "data": {}
}

code === 0 表示业务成功；日志文件下载直接返回二进制响应，不使用该响应壳。

应用数据

开发脚本和打包软件统一使用 Electron 的 userData 目录，目录名固定为 VideoSearch：

系统	典型目录
Windows	`%APPDATA%\VideoSearch\`
macOS	`~/Library/Application Support/VideoSearch/`
Linux	Electron 的应用数据目录下 `VideoSearch/`

单独运行后端且未设置 APP_DATA_DIR 时，Linux 默认使用 ~/.local/share/VideoSearch/。

VideoSearch/
├── resource_sites.json      # 用户可写的资源站配置
├── video_search.db          # 搜索历史、收藏和播放记录
└── logs/
    ├── video_search.log     # 当前 JSON Lines 日志
    └── video_search.log.*   # 轮转备份（存在时）

默认站点来自项目内的 resources/resource_sites.json。首次需要配置时会复制到用户数据目录，之后的增删改、启停和导入操作只修改用户副本。

旧开发目录 videosearch-desktop 首次启动时会迁移可识别的业务文件；目标目录已有同名文件时以目标目录为准，旧目录随后直接删除，不保留备份。

可用脚本

根目录

命令	作用
`npm run electron`	启动 Electron，并自动编排本地后端
`npm run build:frontend`	构建前端生产文件
`npm run build:backend`	使用当前平台的 PyInstaller 构建后端可执行文件
`npm run dist:mac`	构建 macOS DMG 与 ZIP 产物
`npm run dist:dir`	构建 Windows 免安装目录版
`npm run dist:win`	构建 Windows NSIS 安装包

前端

命令	作用
`npm --prefix frontend run dev`	启动 Vite 开发服务
`npm --prefix frontend run build`	构建前端生产文件
`npm --prefix frontend run preview`	预览前端构建结果
`npm --prefix frontend run lint`	检查前端 JavaScript 与 Vue 文件

桌面打包

npm run build:backend 会清理旧的 PyInstaller 输出，并按当前构建机平台生成后端可执行文件。打包阶段使用 --publish never，只生成本地制品，不会自动上传 Release。

macOS

macOS 应在 macOS 主机或对应 CI runner 上执行：

npm run dist:mac

会生成 DMG 与 ZIP，产物写入 release/，文件名包含版本和构建机 CPU 架构。CI 配置了签名/公证环境变量入口；未提供对应 Secrets 时仍会生成未签名、未公证包，首次打开可能需要在系统安全设置中允许，自动更新也可能被系统安全策略拦截。

Windows

Windows 应在 Windows 主机或 Windows CI runner 上执行，因为 PyInstaller 生成当前平台的后端程序：

# 免安装目录版
npm run dist:dir

# NSIS 安装包
npm run dist:win

目录版启动文件为 release/win-unpacked/VideoSearch.exe，必须分发完整的 win-unpacked 目录；NSIS 安装包写入 release/，安装时允许选择目录并创建桌面与开始菜单快捷方式。

构建顺序与资源映射

Vite 生成前端生产文件。
PyInstaller 生成当前平台后端：macOS 为 backend/dist/backend，Windows 为 backend/dist/backend.exe。
electron-builder 将桌面代码、前端产物、后端程序和默认资源组装到 release/。

源路径	macOS 打包后位置	Windows 打包后位置
`backend/dist/backend` / `backend/dist/backend.exe`	`resources/backend/backend`	`resources/backend/backend.exe`
`frontend/dist/`	`resources/frontend/dist/`	`resources/frontend/dist/`
`resources/`	`resources/resources/`	`resources/resources/`

打包后运行不依赖用户本机的 Python 虚拟环境。由于 PyInstaller 不负责跨平台编译，不能把 macOS 构建机的后端直接当作 Windows 发布包；跨平台发布应使用各自原生 runner。

CI 发布

.github/workflows/desktop-release.yml 会在 macOS x64、macOS arm64 和 Windows x64 原生 runner 上构建制品，并在发布前合并两个 macOS 架构的更新元数据。推送与 package.json 版本一致的 tag（例如 v0.1.0）后，Workflow 会校验版本、上传制品并创建 GitHub Release；手动运行 Workflow 只生成 Actions artifacts。

CI 可选读取以下 Secrets：MACOS_CSC_LINK、MACOS_CSC_KEY_PASSWORD、APPLE_ID、APPLE_APP_SPECIFIC_PASSWORD、APPLE_TEAM_ID、WINDOWS_CSC_LINK、WINDOWS_CSC_KEY_PASSWORD。

自动更新

打包环境启动后会自动检查 GitHub Releases。发现新版本时弹出版本信息，用户确认后下载；下载完成后可立即重启安装，也可以稍后退出时安装。开发脚本不会检查线上更新。发布时必须同时上传安装包、ZIP、latest.yml/latest-mac.yml 和 blockmap 文件；macOS 正式更新建议使用签名和公证包。

数据与外部依赖说明

搜索关键词会发送到用户启用的第三方资源站；视频播放会直接访问第三方媒体地址。
搜索历史、收藏、观看记录、配置和日志保存在本机，不提供账号、云同步或多用户隔离。
日志可能包含搜索关键词、资源站地址、耗时和错误信息，但当前不会自动上传到远程服务。
收藏和观看记录只保存关键词，不保存原搜索页码；来自后续结果页的视频在回访时可能无法重新定位。
第三方接口结构、服务可用性和媒体地址均不受本项目控制；单站失败不会阻断其他站点。
当前播放器不提供 DRM、字幕管理或离线下载能力。

常见问题

开发态提示找不到后端 Python

确认已执行：

uv sync --directory backend

并检查平台对应的虚拟环境解释器是否存在：

backend/.venv/Scripts/python.exe   # Windows
backend/.venv/bin/python           # macOS / Linux

打包时提示 `Backend executable not found`

先构建当前平台的后端：

npm run build:backend

macOS 应确认 backend/dist/backend 存在，Windows 应确认 backend/dist/backend.exe 存在，然后再运行对应的 Electron 打包命令。

Electron 打开后无法加载开发页面

确认 Vite 已在 127.0.0.1:4739 运行，再执行 npm run electron。

自动更新不弹出

自动更新只在打包版本启用。确认 GitHub Release 中存在当前平台对应的安装包、latest.yml 或 latest-mac.yml 及 blockmap 文件，并确认正式包已完成代码签名；开发脚本不会弹出更新提示。

后端健康检查超时或端口占用

桌面模式固定使用 127.0.0.1:4740。停止占用该端口的进程后重试；macOS 一键脚本会主动尝试清理该端口。

打包后页面空白或静态资源加载失败

前端构建必须使用相对资源基址。检查 Vite 配置中的 base 是否仍为 ./，并确认 frontend/dist/ 已完整打入应用资源目录。

某个资源站搜索或测试失败

先在设置页单独测试该站点。超时、异常状态、无法解析的数据或反爬页面只会标记该站点失败，不影响其他站点。

Navigation Menu

Repository files navigation

VideoSearch v0.1.0

核心能力

系统结构

技术栈

项目结构

环境要求

安装依赖

开发运行

一键启动

手动启动

单独调试后端

端口与运行配置

应用数据

可用脚本

根目录

前端

桌面打包

macOS

Windows

构建顺序与资源映射

CI 发布

自动更新

数据与外部依赖说明

常见问题

开发态提示找不到后端 Python

打包时提示 `Backend executable not found`

Electron 打开后无法加载开发页面

自动更新不弹出

后端健康检查超时或端口占用

打包后页面空白或静态资源加载失败

某个资源站搜索或测试失败

相关文档

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 23 Commits
.claude		.claude
.github/workflows		.github/workflows
backend		backend
doc		doc
electron		electron
frontend		frontend
resources		resources
scripts		scripts
规范文档		规范文档
.gitignore		.gitignore
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
start-backend.bat		start-backend.bat
start-dev.bat		start-dev.bat
start-dev.command		start-dev.command
start-frontend.bat		start-frontend.bat

Folders and files

Latest commit

History

Repository files navigation

VideoSearch v0.1.0

核心能力

系统结构

技术栈

项目结构

环境要求

安装依赖

开发运行

一键启动

手动启动

单独调试后端

端口与运行配置

应用数据

可用脚本

根目录

前端

桌面打包

macOS

Windows

构建顺序与资源映射

CI 发布

自动更新

数据与外部依赖说明

常见问题

开发态提示找不到后端 Python

打包时提示 Backend executable not found

Electron 打开后无法加载开发页面

自动更新不弹出

后端健康检查超时或端口占用

打包后页面空白或静态资源加载失败

某个资源站搜索或测试失败

相关文档

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

打包时提示 `Backend executable not found`