diff --git a/BUILD.md b/BUILD.md new file mode 100644 index 0000000..fd2c344 --- /dev/null +++ b/BUILD.md @@ -0,0 +1,108 @@ +# 开发与构建 + +面向开发者的源码运行、打包、配置与架构说明。只想使用应用的用户请看 [README](README.md)。 + +## 源码运行与打包 + +源码开发需要 Node.js 22.19+: + +```bash +npm install +npm start +``` + +生成 Windows 免安装版到 `dist/`: + +```bash +npm run portable +``` + +输出目录固定为 `dist/PeopleLib-windows-x64/`,不随版本号变化,重复构建会保留其中的 `data/` 目录。构建前需退出该目录下正在运行的 `PeopleLib.exe`,否则会因文件占用而中止。 + +发布时将完整的 `dist/PeopleLib-windows-x64/` 目录压缩,上传到 GitHub Release,并使用 `v1.3.0` 形式的版本标签。应用根据最新 Release 标签判断是否需要更新。 + +## 配置 + +### 代理 + +在应用内「设置」填写代理地址,例如 `http://127.0.0.1:7897`。留空表示直连。配置会持久化,重启后仍生效,并应用于所有数据源请求与封面加载。 + +网络受限环境下,多数数据源需要代理才能访问。 + +### Z-Library 账号 + +「设置」中填入邮箱与密码即可登录。登录后可获取下载直链(免费账号有每日下载额度限制)。 + +> 凭据以 base64 混淆后保存在本地 `zlib-auth.json`,**这只是防止肉眼直读,不是加密**。请勿在不受信任的机器上使用。 + +## 数据位置 + +| 模式 | 路径 | +|---|---| +| 开发运行 | `%APPDATA%/PeopleLib`(Windows) | +| 打包运行 | 可执行文件同级的 `data/` 目录 | + +该目录包含: + +- `library.json` 书库索引 +- `settings.json` 应用设置(代理等) +- `zlib-auth.json` Z-Library 凭据与会话 +- `covers/` 封面缓存 + +## 项目结构 + +``` +main.js 主进程:窗口、IPC、代理与证书处理、文件下载 +preload.js 渲染进程 API 桥接 +src/ + settings.js 设置持久化 + library/store.js 书库存储 + sources/ + index.js 数据源注册表 + http.js 统一 HTTP 层:超时、Cookie、代理 + mirror.js 镜像故障转移 + zlib-auth.js Z-Library 凭据存储 + .js 各数据源实现 + ui/ 渲染进程界面 +``` + +### 数据源接口 + +每个数据源模块导出以下结构: + +```js +module.exports = { + id: 'example', + name: '示例源', + supportsSearch: true, + + async list(page) // 浏览:{ items, maxPage, page } + async search(keyword, page) // 搜索:{ items, maxPage, page } + async detail(postId) // 详情:{ title, authors, cover, tags, brief, links } + async download(postId) // 下载:{ files, links } +}; +``` + +新增数据源只需实现该接口,并在 `src/sources/index.js` 中注册。 + +### 网络层说明 + +- 主进程使用 Electron 的 `net.fetch`(Chromium 网络栈),代理通过 `session.setProxy` 生效 +- 纯 Node 环境回退到 undici `ProxyAgent`(Electron 下不启用,该组合存在兼容问题) +- 所有请求默认 15 秒超时,可按调用点覆盖 +- 失效镜像进入 5 分钟冷却,之后自动重试,避免站点恢复后被永久跳过 +- **应用启动时全局忽略 TLS 证书错误**。这是为了兼容大量使用自签名或过期证书的镜像站点,代价是失去对中间人攻击的防护,请仅在受信任的网络环境中使用。 + +## 测试 + +单元测试: + +```bash +npm test +``` + +数据源联通性检查,对主要数据源依次执行搜索、详情、下载链路,输出每一步耗时与结果: + +```bash +npx electron test-search.js --proxy http://127.0.0.1:7897 +``` diff --git a/README.md b/README.md index 66600ee..2e7bcf3 100644 --- a/README.md +++ b/README.md @@ -70,102 +70,9 @@ DRM 保护的 MOBI/AZW/AZW3、KFX、Topaz 以及损坏或不兼容的文件不 当前版本为 **1.3.0**。可在「设置」中手动检查更新,也可启用启动时自动检查。检测到新版本后,应用会打开对应的 GitHub Release 下载页,更新前请退出旧版本并覆盖程序文件,`data/` 目录无需替换。 -## 源码运行与打包 +## 开发 -源码开发需要 Node.js 22.19+: - -```bash -npm install -npm start -``` - -生成 Windows 免安装版到 `dist/`: - -```bash -npm run portable -``` - -发布时将完整的 `dist/PeopleLib-windows-x64/` 目录压缩,上传到 GitHub Release,并使用 `v1.3.0` 形式的版本标签。应用根据最新 Release 标签判断是否需要更新。 - -## 配置 - -### 代理 - -在应用内「设置」填写代理地址,例如 `http://127.0.0.1:7897`。留空表示直连。配置会持久化,重启后仍生效,并应用于所有数据源请求与封面加载。 - -网络受限环境下,多数数据源需要代理才能访问。 - -### Z-Library 账号 - -「设置」中填入邮箱与密码即可登录。登录后可获取下载直链(免费账号有每日下载额度限制)。 - -> 凭据以 base64 混淆后保存在本地 `zlib-auth.json`,**这只是防止肉眼直读,不是加密**。请勿在不受信任的机器上使用。 - -## 数据位置 - -| 模式 | 路径 | -|---|---| -| 开发运行 | `%APPDATA%/PeopleLib`(Windows) | -| 打包运行 | 可执行文件同级的 `data/` 目录 | - -该目录包含: - -- `library.json` 书库索引 -- `settings.json` 应用设置(代理等) -- `zlib-auth.json` Z-Library 凭据与会话 -- `covers/` 封面缓存 - -## 项目结构 - -``` -main.js 主进程:窗口、IPC、代理与证书处理、文件下载 -preload.js 渲染进程 API 桥接 -src/ - settings.js 设置持久化 - library/store.js 书库存储 - sources/ - index.js 数据源注册表 - http.js 统一 HTTP 层:超时、Cookie、代理 - mirror.js 镜像故障转移 - zlib-auth.js Z-Library 凭据存储 - .js 各数据源实现 - ui/ 渲染进程界面 -``` - -### 数据源接口 - -每个数据源模块导出以下结构: - -```js -module.exports = { - id: 'example', - name: '示例源', - supportsSearch: true, - - async list(page) // 浏览:{ items, maxPage, page } - async search(keyword, page) // 搜索:{ items, maxPage, page } - async detail(postId) // 详情:{ title, authors, cover, tags, brief, links } - async download(postId) // 下载:{ files, links } -}; -``` - -新增数据源只需实现该接口,并在 `src/sources/index.js` 中注册。 - -### 网络层说明 - -- 主进程使用 Electron 的 `net.fetch`(Chromium 网络栈),代理通过 `session.setProxy` 生效 -- 纯 Node 环境回退到 undici `ProxyAgent`(Electron 下不启用,该组合存在兼容问题) -- 所有请求默认 15 秒超时,可按调用点覆盖 -- 失效镜像进入 5 分钟冷却,之后自动重试,避免站点恢复后被永久跳过 -- **应用启动时全局忽略 TLS 证书错误**。这是为了兼容大量使用自签名或过期证书的镜像站点,代价是失去对中间人攻击的防护,请仅在受信任的网络环境中使用。 - -## 测试 - -```bash -npx electron test-search.js --proxy http://127.0.0.1:7897 -``` - -对主要数据源依次执行搜索、详情、下载链路,输出每一步耗时与结果。 +源码运行、打包发布、代理与账号配置、数据位置、项目结构与测试见 [BUILD.md](BUILD.md)。 ## 免责声明