diff --git a/README.md b/README.md deleted file mode 100644 index c989546..0000000 --- a/README.md +++ /dev/null @@ -1,3 +0,0 @@ -# verdaccio-cache-manager - -verdaccio-cache-manager \ No newline at end of file diff --git a/doc/bright/design-mockup-v2.html b/doc/bright/design-mockup-v2.html new file mode 100644 index 0000000..9a2fbe4 --- /dev/null +++ b/doc/bright/design-mockup-v2.html @@ -0,0 +1,1414 @@ + + + + + +Verdaccio 缓存可视化管理面板 — 多巴胺效果图 + + + + + + +
+ +
+
+
+

DESIGN-02Verdaccio 缓存可视化管理面板

+

依据《需求文档.docx 前端界面设计文档》· 多巴胺 C 端风格 · 暖白底 + 大圆角卡片 + 预警呼吸光晕

+
+
设计稿 · v0.2
画面：概览 / 检索 / 详情抽屉 / 忽略列表 / 最近动态
2026-09
+
+ + +
+
FRAME 01 · 缓存概览（9 项统计 + Top30 排行 + 包卡片）
+
+
+
+
+
📦
+
+
Verdaccio Manager
+
你的缓存 · 尽在掌握
+
+
+ +
+ +
👤
+
+
+ +
+ +
+
+
+ 📦 包的数量 + 🗃️ +
+
1,247个缓存包
+
+
+
+ 💾 占用空间 + 🧊 +
+
12.8GB
+
+
+
+ 🚨 预警数量 + 🔥 +
+
23个需关注
+
+
+
+ 🧹 可清理空间 + ✨ +
+
3.2GB
+ ✨ 立即清理 +
+
+ + +
+
+
🏆访问排行展开
+
Top 30
+
lodash · axios · react
+
+
+
📈今日下载量
+
1,234
+
较昨日 +18%
+
+
+
🐘最大包
+
tensorflow2.1 GB
+
24 个版本
+
+
+
⏳最老包时间
+
3 年前⏰
+
legacy-utils · 未更新
+
+
+
🧩版本数分布查看详情
+
>50 版本12 个
+
>30: 41 · >15: 128
+
+
+ + +
+
+
🏆访问次数 Top 30按热度排序
+ 收起 ▴ +
+ + + + + + + + + + +
排名包名访问次数热度
1📚lodash12,456
85%
2🔌axios9,832
72%
3📊@antv/g27,654
58%
4⚛️react6,543
49%
5💚vue5,218
41%
6🚀express4,376
35%
+
+ + +
+ 🎁你的缓存 + 共 1,247 个包 · 预警置顶 · 同状态按版本数降序 +
+
+
+
+
📚
+
+
lodash 🔥 预警
+
超阈值 10 个版本
+
+
+
+
25
版本数
+
128.5 MB
占用空间
+
+
+ + +
+
+
+
+
📊
+
+
@antv/g2 🔥 预警
+
超阈值 17 个版本
+
+
+
+
32
版本数
+
256.8 MB
占用空间
+
+
+ + +
+
+
+
+
🔌
+
+
axios 🔥 预警
+
超阈值 3 个版本
+
+
+
+
18
版本数
+
45.2 MB
占用空间
+
+
+ + +
+
+
+
+
⚛️
+
+
react ✅ 正常
+
最近更新 2026-09-12
+
+
+
+
8
版本数
+
42.1 MB
占用空间
+
+
+
+
+
+
🚀
+
+
express ✅ 正常
+
最近更新 2026-09-08
+
+
+
+
6
版本数
+
18.9 MB
占用空间
+
+
+
+
+
+
🛡️
+
+
vue 💤 已忽略
+
标记于 2026-08-30
+
+
+
+
19
版本数
+
88.3 MB
占用空间
+
+
+
+
+
+
+
+
+ + +
+
FRAME 02 · 全局检索（大圆角搜索框 + pill 筛选 + 无边框虚拟表格）
+ +
+ + +
+
FRAME 03 · 阈值配置（全局默认 + 单包例外 · 命中即预警）
+
+
+
+
+
📦
+
+
Verdaccio Manager
+
你的缓存 · 尽在掌握
+
+
+ +
+ +
👤
+
+
+
+
⚙️阈值配置
+
命中阈值即预警 · 全局默认 + 单包例外 · 保存后立即生效，历史缓存包即时重算状态
+ +
+
+
+
📦版本数阈值命中即预警
+ 恢复默认 50 +
+
包内缓存版本数达到阈值后，该包被标记为「预警」，并置顶展示在概览与检索结果中。
+
+
+ +
+ 个版本 +
+
+
+
+
+
🧊包大小阈值命中即预警
+ 恢复默认 500 +
+
包占用空间达到阈值后标记预警。预警包内的低版本可一键清理，释放可清理空间。
+
+
+ +
+ MB +
+
+
+
+ +
💡 保存后立即生效 · 历史缓存包将即时重算预警状态 · 无需重启服务
+ +
+ 🔧单包例外 + 例外的阈值优先于全局配置 · 用于个别大包 / 特殊包 +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
包名版本数阈值包大小阈值命中状态操作
📊@antv/g215200 MB🔥 命中 2 项
📚lodash301 GB✅ 正常
🐘tensorflow203 GB✅ 正常
🗃️zod10100 MB🔥 命中 1 项
+
+
+ + + + +
+
+
+
+
+ + +
+
FRAME 04 · 包详情抽屉（版本列表 / 删除单版本 / 批量操作）
+
+
+
+
+
+
+ 📚 + lodash + 🔥 预警 +
+ ✕ +
+
+
+
版本数
25
+
占用空间
128.5 MB
+
最后更新
2026-09-15
+
首次缓存
2019-03-10
+
+
版本列表 25 个版本 · 按 semver 降序
+
+
+ 4.17.21 + 1.2 MB + 2026-09-15 + +
+
+ 4.17.20 + 1.2 MB + 2025-08-22 + +
+
+ 4.17.19 + 1.1 MB + 2025-03-10 + +
+
+ 4.17.18 + 1.1 MB + 2024-11-02 + +
+
+ 4.17.17 + 1.1 MB + 2024-06-28 + +
+
▾ 共 25 个版本 · 支持虚拟滚动
+
+
+
+ + +
+
+
+
+
+ + +
+
FRAME 05 · 忽略列表（已忽略包管理 / 取消忽略）
+
+
+
+
+
📦
+
+
Verdaccio Manager
+
你的缓存 · 尽在掌握
+
+
+ +
+ +
👤
+
+
+
+
💤忽略列表
+
已标记忽略的包不再触发预警 · 共 15 个已忽略包 · 取消忽略后自动恢复状态判断
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
包名版本数占用空间忽略时间操作
📚lodash25128.5 MB2026-08-30 14:20
💚vue1988.3 MB2026-08-30 14:21
🗃️zod2231.6 MB2026-09-02 09:15
🗓️moment1726.4 MB2026-09-05 16:42
+
+
+
+
+
+ + +
+
FRAME 06 · 最近动态（操作日志 · 最近 50 条 · 时间倒序）
+
+
+
+
+
📦
+
+
Verdaccio Manager
+
你的缓存 · 尽在掌握
+
+
+ +
+ +
👤
+
+
+
+
+
+ 🕒最近动态 + 每次清理自动记录 · 最近 50 条 · 时间倒序 +
+ 实时 +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
时间包名删除版本删除数量释放空间
2026-09-18 14:32📚lodash2.0.0 · 2.1.0 · 2.4.0 · 3.0.0 · 3.1.0 …1064 MB
2026-09-17 09:05🔌axios0.18.0 · 0.19.0 · 0.21.1 …622 MB
2026-09-15 18:47📊@antv/g24.0.15 · 4.1.0 · 4.1.2 …731 MB
2026-09-12 11:20🗓️moment2.24.0 · 2.26.0 · 2.27.0 · 2.28.0 …712 MB
2026-09-08 16:03🚀react-router5.2.0 · 5.3.0 …49 MB
+
+
+
+
+
+ +
+
FRAME 07 · 移动端竖版（390×844 · 收起态 / 展开态 · 底部 Tab）
+
+
+
+
收起态 · 点击右上角 ☰ 展开
+
+
+
+
+
+
VerdaccioManager
+ +
+
+
+
🗃️
1,247缓存包
+
🧊
12.8 GB占用空间
+
🔥
23预警数量
+
✨
3.2 GB可清理
+
+
+ 🔥 23 个包超出阈值 + +
+
🎁 预警包
+
+
+ 📚 +
lodash25 个版本 · 128.5 MB · 访问 Top 1
+ 🔥 预警 +
+
+
+
+
+ 📊 +
@antv/g232 个版本 · 256.8 MB · 访问 Top 3
+ 🔥 预警 +
+
+
+
+
+ ⚛️ +
react8 个版本 · 42.1 MB · 最近更新 09-12
+ ✅ 正常 +
+
+
▼ 向下滚动查看更多
+
+
+ 🏠概览 + 🔍检索 + ⚙️阈值 + 🕒动态 +
+
+
+
+
+
+
+
展开态 · 点击 ☰ 右侧滑出设置抽屉
+
+
+
+
+
+
VerdaccioManager
+ +
+
+
+
🗃️
1,247缓存包
+
🧊
12.8 GB占用空间
+
🔥
23预警数量
+
✨
3.2 GB可清理
+
+
+ 🔥 23 个包超出阈值 + +
+
🎁 预警包
+
+
+ 📚 +
lodash25 个版本 · 128.5 MB · 访问 Top 1
+ 🔥 预警 +
+
+
+
+
+ 📊 +
@antv/g232 个版本 · 256.8 MB · 访问 Top 3
+ 🔥 预警 +
+
+
+
+
+ ⚛️ +
react8 个版本 · 42.1 MB · 最近更新 09-12
+ ✅ 正常 +
+
+
▼ 向下滚动查看更多
+
+
+ 🏠概览 + 🔍检索 + ⚙️阈值 + 🕒动态 +
+
+
+
+
+
⚙️ 更多与设置✕
+
+
+
👤
+
缓存管理员admin@verdaccio.local
+
+
🌙 主题切换当前：亮色
+
⚙️ 阈值配置版本数 50 · 500MB
+
📦 版本信息v0.2.0
+
+
+
+
+
+
+
+
+
+
+ + + + + +
+
FRAME 08 · 登录页（渐变背景 + 居中卡片 · 三端适配：桌面 420px / 平板自适应 / 手机 100%）
+
+ +
+
+ +
Verdaccio Cache Manager · 设计稿 v0.2 · 多巴胺 C 端风格 · 依据 doc/Verdaccio 缓存可视化管理面板 — 需求文档.docx（前端界面设计文档）输出
+ + + + diff --git a/doc/bright/design-v2-drawer.png b/doc/bright/design-v2-drawer.png new file mode 100644 index 0000000..17b4000 Binary files /dev/null and b/doc/bright/design-v2-drawer.png differ diff --git a/doc/bright/design-v2-ignore.png b/doc/bright/design-v2-ignore.png new file mode 100644 index 0000000..d173a1a Binary files /dev/null and b/doc/bright/design-v2-ignore.png differ diff --git a/doc/bright/design-v2-login.png b/doc/bright/design-v2-login.png new file mode 100644 index 0000000..f1e79f1 Binary files /dev/null and b/doc/bright/design-v2-login.png differ diff --git a/doc/bright/design-v2-logs.png b/doc/bright/design-v2-logs.png new file mode 100644 index 0000000..b27b921 Binary files /dev/null and b/doc/bright/design-v2-logs.png differ diff --git a/doc/bright/design-v2-mobile.png b/doc/bright/design-v2-mobile.png new file mode 100644 index 0000000..cbb997e Binary files /dev/null and b/doc/bright/design-v2-mobile.png differ diff --git a/doc/bright/design-v2-overview.png b/doc/bright/design-v2-overview.png new file mode 100644 index 0000000..49e6450 Binary files /dev/null and b/doc/bright/design-v2-overview.png differ diff --git a/doc/bright/design-v2-search.png b/doc/bright/design-v2-search.png new file mode 100644 index 0000000..831eb13 Binary files /dev/null and b/doc/bright/design-v2-search.png differ diff --git a/doc/bright/design-v2-threshold.png b/doc/bright/design-v2-threshold.png new file mode 100644 index 0000000..2eb6998 Binary files /dev/null and b/doc/bright/design-v2-threshold.png differ diff --git a/doc/dark/design-mockup-v2-dark.html b/doc/dark/design-mockup-v2-dark.html new file mode 100644 index 0000000..43a2eed --- /dev/null +++ b/doc/dark/design-mockup-v2-dark.html @@ -0,0 +1,1417 @@ + + + + + +Verdaccio 缓存可视化管理面板 — 暗色调效果图 + + + + + + +
+ +
+
+
+

DESIGN-02-DARKVerdaccio 缓存可视化管理面板

+

暗色调版本 · 与 v2-1 同构布局 · 暖黑底 + 霓虹多巴胺点缀 · 预警呼吸光晕

+
+
设计稿 · v2_2 暗色调
画面：概览 / 检索 / 详情抽屉 / 忽略列表 / 最近动态
2026-09
+
+ + +
+
FRAME 01 · 缓存概览（9 项统计 + Top30 排行 + 包卡片）
+
+
+
+
+
📦
+
+
Verdaccio Manager
+
你的缓存 · 尽在掌握
+
+
+ +
+ +
👤
+
+
+ +
+ +
+
+
+ 📦 包的数量 + 🗃️ +
+
1,247个缓存包
+
+
+
+ 💾 占用空间 + 🧊 +
+
12.8GB
+
+
+
+ 🚨 预警数量 + 🔥 +
+
23个需关注
+
+
+
+ 🧹 可清理空间 + ✨ +
+
3.2GB
+ ✨ 立即清理 +
+
+ + +
+
+
🏆访问排行展开
+
Top 30
+
lodash · axios · react
+
+
+
📈今日下载量
+
1,234
+
较昨日 +18%
+
+
+
🐘最大包
+
tensorflow2.1 GB
+
24 个版本
+
+
+
⏳最老包时间
+
3 年前⏰
+
legacy-utils · 未更新
+
+
+
🧩版本数分布查看详情
+
>50 版本12 个
+
>30: 41 · >15: 128
+
+
+ + +
+
+
🏆访问次数 Top 30按热度排序
+ 收起 ▴ +
+ + + + + + + + + + +
排名包名访问次数热度
1📚lodash12,456
85%
2🔌axios9,832
72%
3📊@antv/g27,654
58%
4⚛️react6,543
49%
5💚vue5,218
41%
6🚀express4,376
35%
+
+ + +
+ 🎁你的缓存 + 共 1,247 个包 · 预警置顶 · 同状态按版本数降序 +
+
+
+
+
📚
+
+
lodash 🔥 预警
+
超阈值 10 个版本
+
+
+
+
25
版本数
+
128.5 MB
占用空间
+
+
+ + +
+
+
+
+
📊
+
+
@antv/g2 🔥 预警
+
超阈值 17 个版本
+
+
+
+
32
版本数
+
256.8 MB
占用空间
+
+
+ + +
+
+
+
+
🔌
+
+
axios 🔥 预警
+
超阈值 3 个版本
+
+
+
+
18
版本数
+
45.2 MB
占用空间
+
+
+ + +
+
+
+
+
⚛️
+
+
react ✅ 正常
+
最近更新 2026-09-12
+
+
+
+
8
版本数
+
42.1 MB
占用空间
+
+
+
+
+
+
🚀
+
+
express ✅ 正常
+
最近更新 2026-09-08
+
+
+
+
6
版本数
+
18.9 MB
占用空间
+
+
+
+
+
+
🛡️
+
+
vue 💤 已忽略
+
标记于 2026-08-30
+
+
+
+
19
版本数
+
88.3 MB
占用空间
+
+
+
+
+
+
+
+
+ + +
+
FRAME 02 · 全局检索（大圆角搜索框 + pill 筛选 + 无边框虚拟表格）
+ +
+ + +
+
FRAME 03 · 阈值配置（全局默认 + 单包例外 · 命中即预警）
+
+
+
+
+
📦
+
+
Verdaccio Manager
+
你的缓存 · 尽在掌握
+
+
+ +
+ +
👤
+
+
+
+
⚙️阈值配置
+
命中阈值即预警 · 全局默认 + 单包例外 · 保存后立即生效，历史缓存包即时重算状态
+ +
+
+
+
📦版本数阈值命中即预警
+ 恢复默认 50 +
+
包内缓存版本数达到阈值后，该包被标记为「预警」，并置顶展示在概览与检索结果中。
+
+
+ +
+ 个版本 +
+
+
+
+
+
🧊包大小阈值命中即预警
+ 恢复默认 500 +
+
包占用空间达到阈值后标记预警。预警包内的低版本可一键清理，释放可清理空间。
+
+
+ +
+ MB +
+
+
+
+ +
💡 保存后立即生效 · 历史缓存包将即时重算预警状态 · 无需重启服务
+ +
+ 🔧单包例外 + 例外的阈值优先于全局配置 · 用于个别大包 / 特殊包 +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
包名版本数阈值包大小阈值命中状态操作
📊@antv/g215200 MB🔥 命中 2 项
📚lodash301 GB✅ 正常
🐘tensorflow203 GB✅ 正常
🗃️zod10100 MB🔥 命中 1 项
+
+
+ + + + +
+
+
+
+
+ + +
+
FRAME 04 · 包详情抽屉（版本列表 / 删除单版本 / 批量操作）
+
+
+
+
+
+
+ 📚 + lodash + 🔥 预警 +
+ ✕ +
+
+
+
版本数
25
+
占用空间
128.5 MB
+
最后更新
2026-09-15
+
首次缓存
2019-03-10
+
+
版本列表 25 个版本 · 按 semver 降序
+
+
+ 4.17.21 + 1.2 MB + 2026-09-15 + +
+
+ 4.17.20 + 1.2 MB + 2025-08-22 + +
+
+ 4.17.19 + 1.1 MB + 2025-03-10 + +
+
+ 4.17.18 + 1.1 MB + 2024-11-02 + +
+
+ 4.17.17 + 1.1 MB + 2024-06-28 + +
+
▾ 共 25 个版本 · 支持虚拟滚动
+
+
+
+ + +
+
+
+
+
+ + +
+
FRAME 05 · 忽略列表（已忽略包管理 / 取消忽略）
+
+
+
+
+
📦
+
+
Verdaccio Manager
+
你的缓存 · 尽在掌握
+
+
+ +
+ +
👤
+
+
+
+
💤忽略列表
+
已标记忽略的包不再触发预警 · 共 15 个已忽略包 · 取消忽略后自动恢复状态判断
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
包名版本数占用空间忽略时间操作
📚lodash25128.5 MB2026-08-30 14:20
💚vue1988.3 MB2026-08-30 14:21
🗃️zod2231.6 MB2026-09-02 09:15
🗓️moment1726.4 MB2026-09-05 16:42
+
+
+
+
+
+ + +
+
FRAME 06 · 最近动态（操作日志 · 最近 50 条 · 时间倒序）
+
+
+
+
+
📦
+
+
Verdaccio Manager
+
你的缓存 · 尽在掌握
+
+
+ +
+ +
👤
+
+
+
+
+
+ 🕒最近动态 + 每次清理自动记录 · 最近 50 条 · 时间倒序 +
+ 实时 +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
时间包名删除版本删除数量释放空间
2026-09-18 14:32📚lodash2.0.0 · 2.1.0 · 2.4.0 · 3.0.0 · 3.1.0 …1064 MB
2026-09-17 09:05🔌axios0.18.0 · 0.19.0 · 0.21.1 …622 MB
2026-09-15 18:47📊@antv/g24.0.15 · 4.1.0 · 4.1.2 …731 MB
2026-09-12 11:20🗓️moment2.24.0 · 2.26.0 · 2.27.0 · 2.28.0 …712 MB
2026-09-08 16:03🚀react-router5.2.0 · 5.3.0 …49 MB
+
+
+
+
+
+ +
+
FRAME 07 · 移动端竖版（390×844 · 收起态 / 展开态 · 底部 Tab）
+
+
+
+
收起态 · 点击右上角 ☰ 展开
+
+
+
+
+
+
VerdaccioManager
+ +
+
+
+
🗃️
1,247缓存包
+
🧊
12.8 GB占用空间
+
🔥
23预警数量
+
✨
3.2 GB可清理
+
+
+ 🔥 23 个包超出阈值 + +
+
🎁 预警包
+
+
+ 📚 +
lodash25 个版本 · 128.5 MB · 访问 Top 1
+ 🔥 预警 +
+
+
+
+
+ 📊 +
@antv/g232 个版本 · 256.8 MB · 访问 Top 3
+ 🔥 预警 +
+
+
+
+
+ ⚛️ +
react8 个版本 · 42.1 MB · 最近更新 09-12
+ ✅ 正常 +
+
+
▼ 向下滚动查看更多
+
+
+ 🏠概览 + 🔍检索 + ⚙️阈值 + 🕒动态 +
+
+
+
+
+
+
+
展开态 · 点击 ☰ 右侧滑出设置抽屉
+
+
+
+
+
+
VerdaccioManager
+ +
+
+
+
🗃️
1,247缓存包
+
🧊
12.8 GB占用空间
+
🔥
23预警数量
+
✨
3.2 GB可清理
+
+
+ 🔥 23 个包超出阈值 + +
+
🎁 预警包
+
+
+ 📚 +
lodash25 个版本 · 128.5 MB · 访问 Top 1
+ 🔥 预警 +
+
+
+
+
+ 📊 +
@antv/g232 个版本 · 256.8 MB · 访问 Top 3
+ 🔥 预警 +
+
+
+
+
+ ⚛️ +
react8 个版本 · 42.1 MB · 最近更新 09-12
+ ✅ 正常 +
+
+
▼ 向下滚动查看更多
+
+
+ 🏠概览 + 🔍检索 + ⚙️阈值 + 🕒动态 +
+
+
+
+
+
⚙️ 更多与设置✕
+
+
+
👤
+
缓存管理员admin@verdaccio.local
+
+
🌙 主题切换当前：暗色
+
⚙️ 阈值配置版本数 50 · 500MB
+
📦 版本信息v0.2.0
+
+
+
+
+
+
+
+
+
+
+ + + + + +
+
FRAME 08 · 登录页（渐变背景 + 居中卡片 · 三端适配：桌面 420px / 平板自适应 / 手机 100%）
+
+ +
+
+ +
Verdaccio Cache Manager · 设计稿 v2_2 暗色调 · 与 v2-1 同构 · 暖黑底 + 霓虹多巴胺点缀
+ + + + diff --git a/doc/dark/design-v2-dark-drawer.png b/doc/dark/design-v2-dark-drawer.png new file mode 100644 index 0000000..bd10fcb Binary files /dev/null and b/doc/dark/design-v2-dark-drawer.png differ diff --git a/doc/dark/design-v2-dark-ignore.png b/doc/dark/design-v2-dark-ignore.png new file mode 100644 index 0000000..1c4fadd Binary files /dev/null and b/doc/dark/design-v2-dark-ignore.png differ diff --git a/doc/dark/design-v2-dark-login.png b/doc/dark/design-v2-dark-login.png new file mode 100644 index 0000000..5c02789 Binary files /dev/null and b/doc/dark/design-v2-dark-login.png differ diff --git a/doc/dark/design-v2-dark-logs.png b/doc/dark/design-v2-dark-logs.png new file mode 100644 index 0000000..0744e7b Binary files /dev/null and b/doc/dark/design-v2-dark-logs.png differ diff --git a/doc/dark/design-v2-dark-mobile.png b/doc/dark/design-v2-dark-mobile.png new file mode 100644 index 0000000..796a540 Binary files /dev/null and b/doc/dark/design-v2-dark-mobile.png differ diff --git a/doc/dark/design-v2-dark-overview.png b/doc/dark/design-v2-dark-overview.png new file mode 100644 index 0000000..997f11e Binary files /dev/null and b/doc/dark/design-v2-dark-overview.png differ diff --git a/doc/dark/design-v2-dark-search.png b/doc/dark/design-v2-dark-search.png new file mode 100644 index 0000000..6950280 Binary files /dev/null and b/doc/dark/design-v2-dark-search.png differ diff --git a/doc/dark/design-v2-dark-threshold.png b/doc/dark/design-v2-dark-threshold.png new file mode 100644 index 0000000..b08c60c Binary files /dev/null and b/doc/dark/design-v2-dark-threshold.png differ diff --git a/doc/design-spec.md b/doc/design-spec.md new file mode 100644 index 0000000..a1dcd01 --- /dev/null +++ b/doc/design-spec.md @@ -0,0 +1,268 @@ +# Verdaccio 缓存可视化管理面板 — 设计规范（编码阶段参考） + +> 文档依据： +> 1. `doc/需求文档.md`（完整版：第一部分 功能需求 + 第二部分 前端界面设计） +> 2. `doc/bright/`（浅色设计稿：design-mockup-v2.html + 7 张效果图） +> 3. `doc/dark/`（暗色设计稿：design-mockup-v2-dark.html + 7 张效果图） +> 4. 手机版竖屏效果基准：`bright/design-v2-mobile.png`、`dark/design-v2-dark-mobile.png` +> +> 编码方式：**一套代码 + CSS 变量双主题**（bright=浅色默认 / dark=暗色），**三端适配（电脑 ≥1024px / 平板 768~1023px / 手机 <768px）**，手机端效果以 dark/、bright/ 目录的 mobile 效果图为基准。 + +--- + +## 1. 设计 Token（bright / dark 双主题） + +### 1.1 多巴胺色板 + +| Token | bright（浅色） | dark（暗色） | 用途 | +| --- | --- | --- | --- | +| `--green` | `#32CD32` | `#3DDB4D` | 正常状态标签、选中态标签 | +| `--green-soft` | `#E9F9E9` | `rgba(61,219,77,.14)` | 绿色标签底色 | +| `--orange` | `#FF8C00` | `#FFA033` | 清理按钮、Logo、搜索按钮 | +| `--orange-soft` | `#FFF3E2` | `rgba(255,160,51,.14)` | 橙色标签/数字底色 | +| `--red` | `#FF4500` | `#FF5630` | 预警标签、删除按钮、预警数量 | +| `--red-soft` | `#FFE9E2` | `rgba(255,86,48,.15)` | 红色标签/危险按钮底色 | +| `--blue` | `#1E90FF` | `#45A2FF` | 忽略类标签、信息类 | +| `--blue-soft` | `#E6F2FF` | `rgba(69,162,255,.15)` | 蓝色标签底色 | + +### 1.2 中性色 / 背景 + +| Token | bright | dark | 用途 | +| --- | --- | --- | --- | +| `--ink` | `#2B2B33` | `#F1E8DE` | 主文字 | +| `--ink-dim` | `#8A8A94` | `#A79E91` | 次级文字 | +| `--ink-faint` | `#B9B9C2` | `#6E655A` | 弱化文字/提示 | +| `--line` | `#F1E7DA` | `#3A2F25` | 边框、分隔线 | +| `--card` | `#FFFFFF` | `#221B14` | 卡片/面板底色 | +| `--card-2` | `#FFFFFF` | `#2A211A` | 次级面板（抽屉内用户卡等） | +| `--bg` | `#FFF8EF` | `#16110C` | 页面底色（暖白 / 暖黑） | +| `--bg-deep` | `#FFFDF9` | `#100C08` | 深一档背景（画板容器） | + +### 1.3 字体 + +| Token | 值 | 用途 | +| --- | --- | --- | +| `--num` | `'Fredoka','PingFang SC',sans-serif` | 数字/统计值/徽章/表格数字 | +| `--sans` | `'PingFang SC','Hiragino Sans GB','Microsoft YaHei',sans-serif` | 正文 | +| `--display` | `'ZCOOL QingKe HuangYou','PingFang SC',sans-serif` | 展示性标题 | + +字号梯度：30（页面大标题）/ 16.5（品牌名）/ 14–15（卡片标题）/ 13.5（导航）/ 12–12.5（次要）/ 11–11.5（弱化）。 + +### 1.4 圆角 / 阴影 / 渐变 + +| Token | 值 | 用途 | +| --- | --- | --- | +| `--r-lg` | `22px` | 大卡片 | +| `--r-md` | `16px` | 中小卡片/输入框 | +| pill | `99px` | 按钮、标签、搜索框、导航项 | +| `--shadow` | bright：`0 10px 30px -12px rgba(180,120,60,.18), 0 2px 8px -2px rgba(180,120,60,.08)` / dark：`0 12px 32px -14px rgba(0,0,0,.6), 0 2px 8px -2px rgba(0,0,0,.4)` | 卡片常态 | +| `--shadow-hover` | bright：`0 18px 44px -14px rgba(180,120,60,.30), 0 4px 14px -4px rgba(180,120,60,.12)` / dark：`0 20px 46px -16px rgba(0,0,0,.75), 0 4px 14px -4px rgba(0,0,0,.5)` | hover 上浮 | + +渐变常量（两版一致）：主按钮 `linear-gradient(120deg,#FFB347,#FF8C00)`；预警按钮 bright `#FF5E1A→#FF8C00`、dark `#FF5630→#FF8C00`；头像 `#7CC6FF→#1E90FF`（dark `#5FA8E8→#2B74B9`）。 + +--- + +## 2. 双主题实现方案 + +```css +:root { /* bright 浅色 token（默认） */ } +html[data-theme="dark"] { /* 覆盖 dark token + 氛围背景 */ } +``` + +- 切换入口：顶栏右侧 pill 按钮（bright 显示「🌙 切到暗色」，dark 显示「☀️ 切到亮色」）；移动端并入设置抽屉「🌙 主题切换」项 +- 记忆：`localStorage` 键 `vcm-theme`，加载时读取 +- 注意：dark 下需同步覆盖 `.ambient` 氛围渐变、点阵背景、搜索框聚焦光圈、呼吸光晕强度等硬编码色（对照 bright/dark 两版 HTML） + +--- + +## 3. 功能需求要点（编码约束，来自第一部分） + +### 3.1 包列表与状态 +- 字段：包名 / 版本数 / 占用空间 / 状态（正常·预警·已忽略）/ 操作（清理、忽略、取消忽略） +- 状态规则：正常 = 版本数 ≤ 阈值；预警 = 版本数 > 阈值 且未被忽略；已忽略 = 用户手动标记 +- 排序：预警置顶 → 正常居中 → 已忽略垫底；同状态按版本数降序 + +### 3.2 检索 +- 输入框实时过滤（防抖 300ms），一键清空；匹配：不区分大小写子串，仅匹配包名（界面文档扩展为包名/版本号/文件大小，编码以扩展版为准） +- 反馈：实时更新 + 「共找到 X 个包」；清空恢复完整列表 + +### 3.3 阈值配置 +- **版本数阈值：取值范围 1~100，默认 15**（功能需求为准；界面设计稿示例为 50，编码以 15 为默认并可在 UI 调整） +- 持久化：保存到 SQLite `settings` 表，重启不丢失，加载时读取；修改后列表状态立即重算 +- 界面扩展配置项（设计稿已实现）：单包大小阈值（默认 500MB）、单包例外（覆盖全局）、恢复默认、保存生效提示 + +### 3.4 预警清理 +- 超阈值包：预警标签、自动置顶、清理按钮可用 +- 清理确认弹窗：包名、当前版本数、保留版本数输入（默认=阈值）、将删除版本列表（Tag）、将删除数量、取消、确认清理（loading） +- 清理原子逻辑：读 package.json → 按 semver 排序保留最新 N 个 → 删低版本 versions/time 记录 → 修正 dist-tags（如 latest 指向已删版本）→ 写回元数据 → 物理删 .tgz → 记日志 → 返回「删除数量、释放空间」 +- 反馈：成功「已清理 X 个版本，释放 Y MB」；失败展示错误、不修改任何文件 + +### 3.5 忽略标记 +- 标记/取消忽略立即持久化到 `ignored_packages` 表；取消后若仍超阈值自动回预警 + +### 3.6 操作日志 +- 每次清理自动记录：包名、删除版本列表、删除数量、释放空间、操作时间（UTC） +- 按时间倒序展示最近 50 条，支持查看详情 + +### 3.7 非功能要求 +- 性能：500 包加载 <2s、检索 <200ms、单包清理 <5s +- 可靠：清理原子性、元数据损坏标记「异常」不影响其他包、崩溃无脏数据 +- 安全：非 root（UID 10000）、storage 只读挂载、仅改目标包文件 + +--- + +## 4. 数据模型与 API（编码依据） + +### 4.1 SQLite +```sql +CREATE TABLE settings (key TEXT PRIMARY KEY, value TEXT); -- version_threshold 默认 '15' +CREATE TABLE ignored_packages (pkg_name TEXT PRIMARY KEY, ignored_at DATETIME DEFAULT CURRENT_TIMESTAMP); +CREATE TABLE logs (id INTEGER PRIMARY KEY AUTOINCREMENT, pkg_name TEXT, + deleted_versions TEXT, deleted_count INTEGER, freed_space TEXT, created_at DATETIME DEFAULT CURRENT_TIMESTAMP); +``` + +### 4.2 REST API +| 方法 | 路径 | 说明 | +| --- | --- | --- | +| GET/POST | `/api/threshold` | 获取/设置阈值 | +| GET | `/api/ignored` | 获取已忽略包名 | +| POST | `/api/ignore` | 标记忽略 | +| DELETE | `/api/ignore/:pkgName` | 取消忽略 | +| GET | `/api/packages?keyword=` | 扫描包列表（模糊检索） | +| POST | `/api/clean` | 执行清理 | +| GET | `/api/logs` | 最近 50 条日志 | + +--- + +## 5. 页面清单（画板 → 页面） + +| # | 页面/视图 | 关键内容 | 路由建议 | +| --- | --- | --- | --- | +| 1 | 缓存概览 | 4 核心统计卡 + 5 辅助指标、预警横幅卡、Top 30 访问排行、包卡片列表 | `/` | +| 2 | 全局检索 | 48px 大圆角搜索框、快捷筛选 pill、无边框结果表格 | `/search` | +| 3 | 阈值配置 | 全局阈值卡×2（版本数/大小，−/+ 步进器、恢复默认、保存）、单包例外表格、行内添加例外表单 | `/thresholds` | +| 4 | 包详情抽屉 | 600px 右侧滑出，包信息 + 版本列表（单版本删除、清理全部、忽略） | 覆盖层 | +| 5 | 忽略列表 | 已忽略包表格 + 移出忽略（二次确认） | `/ignored` | +| 6 | 最近动态 | 时间倒序操作日志表格，删除数量/释放空间 chip | `/logs` | +| 7 | 移动端竖版 | 底部 4 Tab（概览/检索/阈值/动态）、2×2 统计、单列包卡、设置抽屉；效果图：`bright/design-v2-mobile.png`、`dark/design-v2-dark-mobile.png` | 响应式实现 | +| 8 | 登录页 | 渐变背景 + 居中卡片 420px、emoji 输入框、渐变登录按钮、记住我/忘记密码；效果图 FRAME 08：`bright/design-v2-login.png`、`dark/design-v2-dark-login.png`（按需求文档 14 节） | `/login` | + +--- + +## 6. 组件清单（来自设计稿） + +| 组件 | 要点 | +| --- | --- | +| 顶栏 Topbar | 64px；Logo 渐变块 + 品牌名 + 副标题；中部 pill 导航（active 橙色渐变）；右侧主题切换按钮 + 圆形头像 | +| 统计卡 Stat1 | 4 个：图标 + Fredoka 数字 + 标签；四色 tone；预警数量卡红色呼吸光晕 | +| 辅助指标 Stat2 | 5 个轻量小卡（访问排行/今日下载/最大包/最老包/版本数分布） | +| 预警卡 Alert | 红色渐变边框 + 呼吸光晕 + 立即清理按钮 | +| 清理卡 Clean | 橙色渐变 + 可清理空间 + 立即清理按钮 | +| Top30 排行 | 表格：金银铜徽章、包名（scoped 省略+tooltip）、访问次数、热度进度条 | +| 包卡片 | 图标、包名、版本数/占用/最近更新、状态标签、清理/忽略按钮；warn 卡呼吸光晕 | +| 搜索框 | 48px 高、大圆角、放大镜 + 快捷键提示；focus 橙色光圈 | +| Pill 筛选 | 状态过滤 + 排序切换，选中态绿色 | +| 结果表格 | 无边框、hover 行高亮、状态标签、删除操作 | +| 阈值卡 | 全局阈值 + −/+ 步进器 + 恢复默认 + 保存按钮 + 生效提示条 | +| 例外表格 | 包名/版本数阈值/大小阈值/命中状态/删除；行内添加例外表单 | +| 抽屉 Drawer | 600px 右滑 + 遮罩；包详情版本列表、单版本删除、清理全部/忽略 | +| 忽略表 | 已忽略包 + 取消忽略 | +| 日志表 | 时间倒序；操作类型 + 版本数/释放空间 chip | +| 移动端系列 | M-Topbar（☰）、M-Stats 2×2、M-Banner 预警横幅、M-Card 单列、M-Tabbar 底部 4 Tab、M-Drawer 设置抽屉（主题/阈值入口/版本信息/退出登录） | +| 登录页 | 渐变背景、居中白卡 420px、emoji 输入框、渐变登录按钮、记住我/忘记密码 | + +--- + +## 7. 响应式断点（三端，以需求文档为准） + +| 断点 | 尺寸 | 导航 | 统计卡 | 包列表 | 忽略列表 | 搜索框 | 包详情抽屉 | +| --- | --- | --- | --- | --- | --- | --- | --- | +| 桌面端 | ≥1024px | 顶部 pill 按钮 | 4 列 | 4 列卡片网格 | 3 列网格 | 居中 600px | 右侧 600px | +| 平板端 | 768~1023px | 紧凑 pill | 2×2 | 2 列 | 2 列 | 100%（max 500px） | 右侧 50% | +| 手机端 | <768px | 汉堡/☰ + 抽屉 | 单列 | 单列 | 单列 | 全宽 | 底部弹窗 85vh | + +> 差异标注：需求文档手机端导航为「汉堡菜单 + 左侧 280px 侧边抽屉」；设计稿 FRAME 07 为「右上角 ☰ + 右侧设置抽屉（主题/阈值/版本/退出）+ 底部 4 Tab 核心导航」。**编码以设计稿为准**（设置类进抽屉、页面切换走底部 Tab），汉堡抽屉用于承载非核心设置项。 + +--- + +## 8. 动效规范 + +| 场景 | 动效 | +| --- | --- | +| 页面切换 | 平滑淡入 + 轻微上滑（300ms） | +| 卡片悬停 | 上浮 2px + 阴影增强 + 边框强调 | +| 按钮点击 | 缩放 0.95 + 回弹 | +| 弹窗/抽屉 | 右侧滑入（0.35s cubic-bezier(.2,.8,.25,1)）+ 遮罩淡入；移动端底部滑入 | +| 预警呼吸 | 红色光晕呼吸动效（2.4~2.6s ease-in-out 循环） | +| 清理成功 | 卡片缩小消失 + 成功 toast | + +--- + +## 9. 文案风格（C 端对照） + +| 后台风 | C 端 | +| --- | --- | +| 缓存管理 | 你的缓存 | +| 操作日志 | 最近动态 | +| 忽略列表 | 已忽略的包 | +| 阈值配置 | 预警设置 | +| 执行清理 | 一键清理 | +| 共 156 条记录 | 156 条动态 | + +--- + +## 10. 技术选型与编码建议 + +- 后端：Node.js 18-slim + Express + better-sqlite3（单文件嵌入），Docker 单容器，storage 只读挂载、`manager-data` 读写挂载，非 root（UID 10000），端口 3000 +- 前端：Vue 3 + Vite（pnpm 管理）+ **Element Plus 按需引入**；组件样式按 §1/§2 双主题 token **二次重写**为设计稿风格（覆盖 el-card/el-table/el-table-v2/el-drawer/el-tag/el-input-number/el-pagination 等的圆角、阴影、边框、hover 态与预警呼吸光晕） +- 目录建议：`src/components/`（§6 组件逐一落地）、`src/views/`（§5 页面）、`src/styles/tokens.css`（双主题 token） +- 图标：emoji（与设计稿一致，无外部图标库） +- 数据：mock 先行跑通 UI，接口按 §4.2 对接 +- 验收对照：需求文档 AC-1~8（包列表/检索/阈值/预警/清理/忽略/日志/原子性） + +--- + +## 11. 已确认决策（编码按此执行） + +1. **阈值默认值：15**（功能需求 1~100 为准，UI 可调） +2. **登录页：补效果图**（FRAME 08 已输出 bright/dark 两版，见 §5 #8） +3. **UI 库：Element Plus 按需引入**，组件样式按 §1/§2 token 重写覆盖为设计稿风格 + +--- + +## 12. Verdaccio 缓存目录配置与部署（编码依据） + +### 12.1 目录配置机制 +- Verdaccio 侧：缓存目录由 `config.yaml` 的 `storage` 字段指定（Docker 镜像内默认 `/verdaccio/storage`） +- 面板侧：**环境变量 `VERDACCIO_STORAGE` 优先** → 其次 UI「设置」中配置并持久化到 SQLite `settings` 表（key = `storage_dir`）→ 均无时进入**首次启动引导页**要求配置 +- 校验：保存/启动时校验目录存在、可读、含 `package.json` / `.tgz`；无效时提示重新配置，面板不启动扫描 +- 扫描逻辑：递归 `**/package.json` 解析 `versions`/`time`，匹配 `.tgz` 计算占用；支持 scoped 包（`@scope/name` 嵌套目录） + +### 12.2 部署方式一：Docker（与 Verdaccio 同主机） +```yaml +services: + verdaccio: + image: verdaccio/verdaccio + volumes: ["./storage:/verdaccio/storage"] # Verdaccio 读写 + verdaccio-manager: + build: ./ # node:18-slim 约 180MB + environment: [VERDACCIO_STORAGE=/verdaccio/storage, PORT=3000] + volumes: + - "./storage:/verdaccio/storage:ro" # 只读挂载 Verdaccio 存储 + - "./manager-data:/app/data" # 读写：SQLite 数据 + ports: ["3000:3000"] +``` + +### 12.3 部署方式二：虚拟机 / 裸机 +- 环境：Node.js 18 + pnpm，构建前端后 `node server.js`，pm2/systemd 守护 +- 配置（环境变量或 `.env`）： + ``` + VERDACCIO_STORAGE=/var/lib/verdaccio/storage + PORT=3000 + DATA_DIR=/var/lib/verdaccio-manager/data + ``` +- Verdaccio 侧 `config.yaml`：`storage: /var/lib/verdaccio/storage`（与面板指向同一目录） + +### 12.4 UI 配置入口 +- 首次启动：无 `storage_dir` 时展示引导页，提供缓存目录输入 + 「自动探测」（读环境变量/常见路径）按钮 +- 后续修改：顶栏头像下拉「设置」/ 移动端设置抽屉中修改，保存后重新扫描并刷新概览 diff --git a/doc/需求文档.md b/doc/需求文档.md new file mode 100644 index 0000000..81d29a7 --- /dev/null +++ b/doc/需求文档.md @@ -0,0 +1,993 @@ +# Verdaccio 缓存可视化管理面板 — 需求文档（完整版） +本文档由两部分合并而成：第一部分为功能需求，第二部分为前端界面设计。 +## 第一部分 功能需求 +## Verdaccio 缓存可视化管理面板 — 需求文档 +### 1. 项目概述 +#### 1.1 项目背景 +团队使用 Verdaccio 作为私有 npm 仓库代理，长期运行后存储目录会积累大量历史版本缓存包。当某个包的版本数超过设定阈值时，会占用大量磁盘空间，且难以手动识别和清理。 +当前痛点： +无法直观看到哪些包占用了大量空间 +清理版本需要手动操作 Verdaccio 存储目录，风险高 +没有预警机制，磁盘空间被不知不觉耗尽 +某些包虽然版本多但需要保留，无法标记"忽略" +#### 1.2 项目目标 +开发一个轻量级的可视化管理面板，运行在 Docker 容器中，与 Verdaccio 共享存储目录，提供以下核心能力： +可视化管理缓存包：以表格形式展示所有缓存包的版本数、占用空间、预警状态 +全局模糊检索：支持按包名关键词实时筛选 +阈值可配置：可设置版本数阈值，持久化存储 +预警清单：超阈值的包自动列入预警清单，标红展示 +忽略标记：预警包可手工标记为"忽略"，标记后不再触发预警 +#### 1.3 非目标 +不替代 Verdaccio 本身，仅作为管理工具 +不实现用户认证/权限系统（单用户内部工具） +不实现定时自动清理（仅手动触发） +不实现跨 Verdaccio 实例管理（仅管理单个实例） +### 2. 用户角色 +| 角色 | 描述 | +|---|---| +| 运维/开发人员 | 唯一使用者，负责查看缓存状态、配置阈值、执行清理操作 | + +### 3. 功能需求 +#### 3.1 可视化管理缓存包 +##### 3.1.1 包列表展示 +系统应提供一个表格，展示 Verdaccio 存储目录中的所有缓存包，包含以下字段： +| 字段 | 说明 | 示例 | +|---|---|---| +| 包名 | npm 包名称 | lodash | +| 版本数 | 该包当前缓存的版本总数 | 25 | +| 占用空间 | 该包所有版本文件占用的磁盘空间 | 128.5 MB | +| 状态 | 正常 / ️ 预警 / ️ 已忽略 | 见下文状态规则 | +| 操作 | 根据状态显示不同操作按钮 | 清理 / 忽略 / 取消忽略 | + +##### 3.1.2 状态规则 +| 状态 | 触发条件 | 展示样式 | +|---|---|---| +| 正常 | 版本数 ≤ 阈值 | 无特殊标记 | +| ️ 预警 | 版本数 > 阈值 且 未被忽略 | 红色标签 | +| ️ 已忽略 | 用户手动标记忽略 | 灰色标签 | + +##### 3.1.3 排序规则 +列表默认按以下优先级排序： +预警包排在最前面 +正常包排在中间 +已忽略包排在最后 +同状态下按版本数降序排列 +#### 3.2 全局模糊检索 +##### 3.2.1 检索输入框 +位于列表上方，占位符提示" 输入包名关键词..." +支持实时输入，输入后立即过滤列表 +支持一键清空 +##### 3.2.2 检索规则 +匹配方式：不区分大小写的子串匹配 +匹配范围：仅匹配包名 +示例：输入 react 可匹配 react、react-dom、@types/react +##### 3.2.3 检索反馈 +检索结果实时更新，无需点击搜索按钮 +列表上方显示"共找到 X 个包" +清空检索条件后恢复完整列表 +#### 3.3 阈值可配置 +##### 3.3.1 阈值设置 +提供数字输入框，允许设置版本数阈值 +取值范围：1 ~ 100 +默认值：15 +##### 3.3.2 阈值持久化 +阈值修改后自动保存到 SQLite 数据库 +服务重启后阈值不丢失 +页面加载时自动读取已保存的阈值 +##### 3.3.3 阈值生效 +修改阈值后，列表状态立即重新计算 +原本正常的包可能变为预警，原本预警的包可能变为正常 +#### 3.4 预警清单与清理 +##### 3.4.1 预警触发 +当包的版本数超过阈值时： +该包在列表中显示 ️ 预警标签 +该包自动排在列表最前面 +"清理"按钮变为可用状态 +##### 3.4.2 清理确认弹窗 +点击"清理"按钮后，弹出确认对话框，包含以下内容： +| 元素 | 说明 | +|---|---| +| 包名标题 | 显示正在清理的包名 | +| 当前版本数 | 显示该包当前有多少个版本 | +| 保留版本数输入框 | 数字输入框，默认值为当前阈值，可调整 | +| 将删除版本列表 | 展示将被删除的低版本号列表（Tag 形式） | +| 将删除数量 | 显示即将删除的版本个数 | +| 取消按钮 | 关闭弹窗，不执行任何操作 | +| 确认清理按钮 | 执行清理操作，按钮带 loading 状态 | + +##### 3.4.3 清理执行逻辑 +确认清理后，系统执行以下原子操作： +读取该包的 package.json 元数据 +按语义化版本号排序，保留最新的 N 个版本 +从元数据中删除低版本的 versions 和 time 记录 +检查并修正 dist-tags（如 latest 指向了被删除的版本） +将修改后的元数据写回 package.json +物理删除对应的 .tgz 文件 +记录操作日志到数据库 +返回清理结果：删除数量、释放空间 +##### 3.4.4 清理结果反馈 +成功：显示"已清理 X 个版本，释放 Y MB" +失败：显示错误信息，不修改任何文件 +#### 3.5 忽略标记 +##### 3.5.1 标记忽略 +预警包旁边显示"忽略"按钮 +点击后，该包从预警状态变为"已忽略"状态 +标记立即保存到 SQLite 数据库 +该包不再触发预警，即使版本数仍超过阈值 +##### 3.5.2 取消忽略 +已忽略包旁边显示"取消忽略"按钮 +点击后，恢复该包的正常状态判断 +如果版本数仍超过阈值，自动变回预警状态 +标记立即从数据库中删除 +##### 3.5.3 忽略持久化 +忽略标记保存到 SQLite 的 ignored_packages 表 +服务重启后忽略标记不丢失 +页面加载时自动读取已忽略的包列表 +#### 3.6 操作日志（附加功能） +##### 3.6.1 日志记录 +每次清理操作后，系统自动记录以下信息： +| 字段 | 说明 | +|---|---| +| 包名 | 被清理的包名称 | +| 删除版本列表 | 被删除的版本号，逗号分隔 | +| 删除数量 | 删除的版本个数 | +| 释放空间 | 释放的磁盘空间（格式化后） | +| 操作时间 | 清理执行的 UTC 时间 | + +##### 3.6.2 日志查看 +提供独立的日志页面或弹窗 +按时间倒序展示最近 50 条操作记录 +支持查看历史清理详情 +### 3.7 Verdaccio 缓存目录配置 +#### 3.7.1 配置方式 +系统需配置 Verdaccio 缓存目录（storage/）路径，支持以下来源，按优先级生效： +| 优先级 | 来源 | 说明 | +|---|---|---| +| 1 | 环境变量 VERDACCIO_STORAGE | Docker / 虚拟机部署时注入 | +| 2 | UI 设置 | 面板内配置，持久化到 SQLite settings 表（key = storage_dir） | +| 3 | 首次启动引导页 | 均未配置时展示引导页，要求填写缓存目录 | + +#### 3.7.2 目录校验 +保存 / 启动时校验目录存在、可读、包含 package.json 或 .tgz 文件 +校验失败时提示重新配置，面板不启动扫描 + +#### 3.7.3 扫描逻辑 +递归扫描目录下所有包的 package.json，解析 versions / time 字段获取版本列表 +匹配对应 .tgz 文件计算占用空间 +支持 scoped 包（@scope/name 嵌套目录） + +#### 3.7.4 UI 入口 +首次启动引导页：缓存目录输入框 + 「自动探测」按钮（读取环境变量 / 常见路径） +后续修改：顶栏头像下拉「设置」/ 移动端设置抽屉中修改，保存后重新扫描并刷新概览 + +#### 3.7.5 两种部署方式 +| 部署方式 | 说明 | +|---|---| +| Docker 部署 | 与 Verdaccio 同主机，共享宿主机 storage 目录：面板容器只读挂载 storage（:ro），manager-data 读写挂载存 SQLite；环境变量注入 VERDACCIO_STORAGE | +| 虚拟机部署 | 本机安装 Node.js 18 + pnpm，环境变量或 .env 指向 Verdaccio 缓存目录，pm2 / systemd 守护进程 | +### 4. 非功能需求 +#### 4.1 性能要求 +| 指标 | 要求 | +|---|---| +| 包列表加载 | 500 个包以内，加载时间 < 2 秒 | +| 检索响应 | 输入后 < 200ms 内完成过滤 | +| 清理操作 | 单个包清理 < 5 秒 | + +#### 4.2 可靠性要求 +清理操作必须是原子性的：要么全部成功，要么全部回滚 +元数据文件损坏时，该包在列表中标记为"异常"，不影响其他包 +服务崩溃后，已完成的清理操作不丢失，未完成的清理不产生脏数据 +#### 4.3 安全性要求 +容器以非 root 用户运行（UID 10000） +Verdaccio 存储目录以只读方式挂载 +仅允许修改目标包的元数据和文件，不遍历其他目录 +#### 4.4 兼容性要求 +支持 Verdaccio 5.x 存储结构 +支持 scoped 包（如 @antv/g2） +支持语义化版本号（semver）排序 +### 5. 数据模型 +#### 5.1 SQLite 表结构 +-- 配置表 +CREATE TABLE settings ( + key TEXT PRIMARY KEY, + value TEXT +); + +-- 忽略标记表 +CREATE TABLE ignored_packages ( + pkg_name TEXT PRIMARY KEY, + ignored_at DATETIME DEFAULT CURRENT_TIMESTAMP +); + +-- 操作日志表 +CREATE TABLE logs ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + pkg_name TEXT, + deleted_versions TEXT, + deleted_count INTEGER, + freed_space TEXT, + created_at DATETIME DEFAULT CURRENT_TIMESTAMP +); +#### 5.2 默认配置 +| key | value | 说明 | +|---|---|---| +| version_threshold | 15 | 版本数阈值 | + +### 6. API 接口设计 +#### 6.1 阈值管理 +| 方法 | 路径 | 说明 | +|---|---|---| +| GET | /api/threshold | 获取当前阈值 | +| POST | /api/threshold | 设置新阈值 | + +#### 6.2 忽略标记 +| 方法 | 路径 | 说明 | +|---|---|---| +| GET | /api/ignored | 获取所有已忽略的包名 | +| POST | /api/ignore | 标记某个包为忽略 | +| DELETE | /api/ignore/:pkgName | 取消某个包的忽略标记 | + +#### 6.3 包管理 +| 方法 | 路径 | 说明 | +|---|---|---| +| GET | /api/packages?keyword=xxx | 扫描并获取所有包列表（支持模糊检索） | +| POST | /api/clean | 执行清理操作 | + +#### 6.4 日志 +| 方法 | 路径 | 说明 | +|---|---|---| +| GET | /api/logs | 获取最近 50 条操作日志 | + +### 7. 界面原型 +#### 7.1 主页面布局 +┌─────────────────────────────────────────────────────────────────┐ +│ Verdaccio 缓存管理器 │ +├─────────────────────────────────────────────────────────────────┤ +│ ┌───────────────────────────────────────────────────────────┐ │ +│ │ 版本数阈值: [ 15 ] [输入包名关键词...] 共 128 个包 │ │ +│ └───────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌───────────────────────────────────────────────────────────┐ │ +│ │ 包名 │ 版本数 │ 空间 │ 状态 │ 操作 │ │ +│ ├───────────────┼─────────┼──────────┼──────────┼────────────┤ │ +│ │ lodash │ 25 │ 128 MB │ ️ 预警 │ [清理][忽略]│ │ +│ │ @antv/g2 │ 22 │ 96 MB │ ️ 预警 │ [清理][忽略]│ │ +│ │ react │ 8 │ 42 MB │ 正常 │ — │ │ +│ │ vue │ 19 │ 88 MB │ ️ 已忽略│ [取消忽略] │ │ +│ └───────────────────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────────┘ +#### 7.2 清理确认弹窗 +┌──────────────────────────────────────────┐ +│ 清理 lodash │ +│ ────────────────────────────────────── │ +│ 当前 25 个版本，将保留最近的 [ 15 ] 个 │ +│ │ +│ 将删除以下 10 个版本： │ +│ [3.0.0] [3.1.0] [3.5.0] [3.10.0] ... │ +│ │ +│ [取消] [确认清理] │ +└──────────────────────────────────────────┘ +### 8. 技术选型 +| 层级 | 选型 | 理由 | +|---|---|---| +| 运行时 | Node.js 18-slim | 轻量，JSON 操作天然友好 | +| Web 框架 | Express | 轻量，零学习成本 | +| 数据库 | better-sqlite3 | 单文件嵌入式，无需额外部署 | +| 前端框架 | Vue 3 | 响应式，组件化 | +| UI 组件库 | Element Plus | 组件丰富，开箱即用 | +| 部署方式 | Docker 单容器 | 与 Verdaccio 同主机部署 | + +### 9. 部署架构 +绿联 DX4600+ NAS +├── Verdaccio 容器（端口 4873） +│ └── 存储目录: /volume1/docker/verdaccio/storage +│ +└── Verdaccio Manager 容器（端口 3000） + ├── 只读挂载: /volume1/docker/verdaccio/storage → /verdaccio/storage + ├── 读写挂载: ./manager-data → /app/data + └── 镜像: node:18-slim（最终约 180MB） +#### 9.1 Docker 部署（compose 示例） +```yaml +services: + verdaccio: + image: verdaccio/verdaccio + volumes: ["./storage:/verdaccio/storage"] # Verdaccio 读写 + + verdaccio-manager: + build: ./ # node:18-slim 约 180MB + environment: + - VERDACCIO_STORAGE=/verdaccio/storage + - PORT=3000 + volumes: + - "./storage:/verdaccio/storage:ro" # 只读挂载 Verdaccio 存储 + - "./manager-data:/app/data" # 读写：SQLite 数据 + ports: + - "3000:3000" +``` +#### 9.2 虚拟机部署 +- 环境：Node.js 18 + pnpm；构建前端后 `node server.js`，pm2 / systemd 守护 +- 配置（环境变量或 `.env`）： +``` +VERDACCIO_STORAGE=/var/lib/verdaccio/storage +PORT=3000 +DATA_DIR=/var/lib/verdaccio-manager/data +``` +- Verdaccio 侧 `config.yaml`：`storage: /var/lib/verdaccio/storage`（与面板指向同一目录） +### 10. 验收标准 +| 编号 | 验收项 | 通过标准 | +|---|---|---| +| AC-1 | 包列表展示 | 能正确列出所有包，版本数、空间、状态准确 | +| AC-2 | 模糊检索 | 输入关键词后列表实时过滤，结果正确 | +| AC-3 | 阈值配置 | 修改阈值后保存，刷新页面不丢失，列表状态立即更新 | +| AC-4 | 预警触发 | 版本数超阈值的包自动标红并排在最前 | +| AC-5 | 清理操作 | 清理后 package.json 和 .tgz 文件同步删除，dist-tags 正确修正 | +| AC-6 | 忽略标记 | 标记后不再预警，取消后恢复判断，重启不丢失 | +| AC-7 | 操作日志 | 每次清理自动记录，可查询历史 | +| AC-8 | 原子性 | 清理过程中断不会产生脏数据 | + +这份需求文档覆盖了核心功能、数据模型、API 设计、界面原型和验收标准。需要我基于这份文档继续输出详细设计文档（含类图/时序图）或直接开始编码实现吗？ +(AI生成) +## 第二部分 前端界面设计文档 +## Verdaccio 缓存管理工具 — 前端界面设计文档 +### 一、项目概述 +本工具为 Verdaccio 私有 npm 仓库的缓存管理前端界面，用于可视化管理 storage/ 目录下的缓存包文件。工具定位为一款精致的 C 端产品，而非冷冰冰的后台管理系统。 +#### 1.1 设计风格定位 +| 维度 | 后台管理系统风格（拒绝） | C端风格（采用） | +|---|---|---| +| 布局 | 左侧固定导航 + 右侧内容区 | 顶部导航栏 + 全宽内容区 | +| 色彩 | 蓝白灰，严肃冷淡 | 多巴胺配色，活力温暖 | +| 圆角 | 4px 小圆角 | 12-24px 大圆角 | +| 阴影 | 无阴影或硬边 | 柔和弥散阴影 | +| 动效 | 无动效或生硬切换 | 平滑过渡 + 微动效 | +| 文案 | “缓存管理”“操作日志” | “你的缓存”“最近动态” | +| 图标 | 线性图标 | 圆润填充图标 + emoji | +| 页面切换 | 无过渡 | 平滑淡入 + 轻微上滑 | + +#### 1.2 多巴胺配色方案 +| 颜色角色 | 色值 | 用途 | +|---|---|---| +| 清新绿 | #32CD32 | 正常状态标签、选中态标签 | +| 活力橙 | #FF8C00 | 清理按钮、Logo、搜索按钮 | +| 热情红 | #FF4500 | 预警标签、删除按钮、预警数量卡片 | +| 静谧蓝 | #1E90FF | 忽略按钮、忽略标签、访问排行卡片 | +| 卡片背景 | 白色 + 大圆角 | 所有卡片容器 | +| 预警卡片 | 红色边框 + 呼吸光晕动效 | 触发阈值的包卡片 | + +#### 1.3 设计原则 +行动导向优先：能直接引导用户操作的指标优先（如”可清理空间”比”预警数量”更有驱动力） +宏观 + 微观结合：既有整体数据（包数量、总空间），也有极端值（最大包、最老包），帮助用户快速定位问题 +避免信息过载：顶部卡片控制在 4-7 个，更多细节通过点击展开或第二行展示 +C端体验优先：拒绝千篇一律的后台管理系统风格，打造轻盈、有趣、有温度的产品 +### 二、菜单结构 +#### 2.1 导航菜单 +| 序号 | 菜单名 | 图标 | 说明 | +|---|---|---|---| +| 1 | 缓存概览 | | 主页/仪表盘，展示包卡片列表、存储空间统计、预警信息 | +| 2 | 全局检索 | | 按包名/版本/大小搜索，支持筛选条件 | +| 3 | 阈值配置 | | 设置缓存预警阈值（如单包最大体积、总缓存上限等） | +| 4 | 忽略列表 | | 管理已标记忽略的包，支持取消忽略 | +| 5 | 操作日志 | | 查看清理、删除、忽略等操作的历史记录 | + +#### 2.2 顶部导航栏设计 +┌────────────────────────────────────────────────────────────────┐ +│ 📦 Verdaccio Manager │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ +│ │ 概览 │ │ 搜索 │ │ 设置 │ │ 动态 │ │ +│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ +│ 👤 │ +└────────────────────────────────────────────────────────────────┘ +设计要点： - 顶部通栏：高度 64px，白色背景 + 底部 1px 浅灰线 - Pill 导航按钮：圆角 20px，选中态用多巴胺色块背景 - Logo：左侧 emoji + 系统名，用活力橙 #FF8C00 - 用户头像：右侧圆形头像，点击弹出下拉菜单（含”忽略列表”入口） - 响应式：移动端折叠为汉堡菜单 +#### 2.3 补充说明 +不需要”设置”菜单：阈值配置已经覆盖了核心设置项，其他系统级配置（如 Verdaccio 连接地址）可以在首次启动时通过弹窗配置，或放在用户头像的下拉菜单中。 +不需要”用户管理”菜单：本工具定位为个人/小团队内部使用，暂不涉及多用户权限管理。 +### 三、缓存概览页 +#### 3.1 统计指标（共 9 个） +| 序号 | 指标 | 图标 | 说明 | +|---|---|---|---| +| 1 | 包的数量 | | 缓存包总数 | +| 2 | 占用空间 | | 总占用空间 | +| 3 | 预警数量 | | 触发阈值的包数量 | +| 4 | 访问排行 | | Top 30 包访问次数 | +| 5 | 今日/本周下载量 | | 当天或本周下载总次数 | +| 6 | 可清理空间 | | 预估可释放的空间 | +| 7 | 最大包 | | 占用空间最大的包 | +| 8 | 最老包时间 | | 最久未更新的包的时间 | +| 9 | 版本数分布 | | 单包版本数分布情况 | + +#### 3.2 布局设计 +##### 第一行（核心指标 · 4 个） +┌──────────────┬──────────────┬──────────────┬──────────────┐ +│ 包的数量 │ 占用空间 │ 预警数量 │ 可清理空间 │ +│ 1,247 │ 12.8 GB │ 23 │ 3.2 GB │ +│ 清新绿 │ 活力橙 │ 热情红呼吸 │ 静谧蓝 │ +│ │ │ │ [立即清理] │ +└──────────────┴──────────────┴──────────────┴──────────────┘ +指标说明： - 包的数量：扫描 storage/ 目录下的包文件夹数量 - 占用空间：递归计算 storage/ 下所有 .tgz 文件总大小 - 预警数量：对比阈值配置，统计触发条件的包数量 - 可清理空间：根据阈值规则，预估可释放的空间，给用户”清理动力” - 访问排行：点击可展开 Top 30 详情 +##### 第二行（辅助指标 · 5 个） +┌──────────────┬──────────────┬──────────────┬──────────────┬──────────────┐ +│ 访问排行 │ 今日下载量 │ 最大包 │ 最老包时间 │ 版本数分布 │ +│ Top 30 │ 1,234 │ tensorflow │ 3 年前 │ >50版本: 12个│ +│ [展开] │ 2.1 GB │ 2.1 GB │ legacy-utils │ [查看详情] │ +└──────────────┴──────────────┴──────────────┴──────────────┴──────────────┘ +#### 3.3 访问次数 Top 30 排行 +点击”访问排行”卡片后，下方滑出排行榜，采用表格 + 进度条形式： +┌────────────────────────────────────────────────────────────────┐ +│ 访问次数 Top 30 │ +├──────┬──────────────────────┬──────────┬───────────────────────┤ +│ 排名 │ 包名 │ 访问次数 │ 热度 │ +├──────┼──────────────────────┼──────────┼───────────────────────┤ +│ │ lodash │ 12,456 │ ████████████░░ 85% │ +│ │ axios │ 9,832 │ █████████░░░ 72% │ +│ │ @antv/g2 │ 7,654 │ ███████░░░░░ 58% │ +│ 4 │ react │ 6,543 │ ██████░░░░░░ 49% │ +│ ... │ ... │ ... │ ... │ +└──────┴──────────────────────┴──────────┴───────────────────────┘ +设计要点： - 前三名用金银铜标识，多巴胺配色高亮 - 热度进度条直观展示相对访问频率 - 包名支持 scoped（如 @antv/g2），超出宽度省略 + tooltip - 点击包名可跳转到该包的详情卡片 +#### 3.4 缓存包列表（卡片形式） +以圆角卡片形式展示每个缓存包的核心信息，卡片采用多巴胺配色，按状态排序： +┌──────────────────────────────────────────────────────────────┐ +│ 📦 lodash │ +│ 版本: 25 | 空间: 128.5 MB │ +│ 🔥 预警 (红色光晕呼吸动效) │ +│ [✨ 清理] [💤 忽略] │ +└──────────────────────────────────────────────────────────────┘ +卡片字段： - 包名（支持 scoped 包如 @antv/g2） - 版本数 - 占用空间（格式化后，如 128.5 MB） - 状态标签（正常 / 预警 / 已忽略） - 操作按钮（清理、忽略） +排序规则： 预警包置顶 → 正常包居中 → 已忽略包垫底，同状态按版本数降序。 +#### 3.5 数据来源说明 +| 指标 | 数据来源 | +|---|---| +| 包的数量 | 扫描 storage/ 目录下的包文件夹数量 | +| 占用空间 | 递归计算 storage/ 下所有 .tgz 文件总大小 | +| 预警数量 | 对比阈值配置，统计触发条件的包数量 | +| 访问次数 | 解析 Verdaccio 的 logs/ 日志或 storage/ 下各包的 package.json 中的 downloads 字段 | + +### 四、全局检索页 +#### 4.1 顶部搜索框（百度风格） +┌────────────────────────────────────────────────────────────────┐ +│ │ +│ ┌──────────────────────────────────────────────────────┐ │ +│ │ 输入包名、版本、大小进行模糊搜索... │ │ +│ └──────────────────────────────────────────────────────┘ │ +│ │ +│ [全部] [预警包] [已忽略] [按大小排序] [按版本数排序] │ +│ │ +└────────────────────────────────────────────────────────────────┘ +设计要点： - 大圆角搜索框：border-radius: 24px，高度 48px，居中展示 - 占位符提示：输入包名、版本、大小进行模糊搜索… - 实时搜索：输入时防抖 300ms，自动触发检索 - 快捷筛选标签：搜索框下方一排 pill 按钮，支持状态过滤和排序切换 - 多巴胺配色：搜索按钮用活力橙 #FF8C00，选中态标签用清新绿 #32CD32 +#### 4.2 搜索结果列表（无边框虚拟表格） +┌────────────────────────────────────────────────────────────────┐ +│ 包名 │ 版本数 │ 占用空间 │ 状态 │ 最后更新 │ +├────────────────────────────────────────────────────────────────┤ +│ lodash │ 25 │ 128.5 MB │ 预警 │ 2024-01-15 │ +│ axios │ 18 │ 45.2 MB │ 正常 │ 2024-03-22 │ +│ @antv/g2 │ 32 │ 256.8 MB │ 预警 │ 2024-02-10 │ +│ react │ 15 │ 89.3 MB │ 正常 │ 2024-04-01 │ +│ ... │ ... │ ... │ ... │ ... │ +└────────────────────────────────────────────────────────────────┘ +技术实现： - 虚拟滚动：使用 Element Plus 的 el-table-v2 或 vue-virtual-scroller，仅渲染可视区域 DOM，支持万级数据流畅滚动 - 无边框设计：border: none，行与行之间用浅灰分割线 #F0F0F0（1px） - 按需加载：初始加载 50 条，滚动到底部自动加载下一页（Infinite Scroll） - 悬停高亮：鼠标悬停行背景变为浅多巴胺色 #FFF8F0 - 点击跳转：点击任意行，打开该包的详情抽屉/弹窗 +#### 4.3 包详情页（点击行后展开） +点击列表行后，从右侧滑出抽屉（Drawer），展示该包的完整信息： +┌────────────────────────────────────────────────────────────────┐ +│ lodash [× 关闭] │ +├────────────────────────────────────────────────────────────────┤ +│ 版本数: 25 | 占用空间: 128.5 MB | 状态: 预警 │ +│ 最后更新: 2024-01-15 | 首次缓存: 2020-03-10 │ +├────────────────────────────────────────────────────────────────┤ +│ 版本列表 │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ 4.17.21 | 1.2 MB | 2024-01-15 | [🗑️ 删除] │ │ +│ │ 4.17.20 | 1.2 MB | 2023-08-22 | [🗑️ 删除] │ │ +│ │ 4.17.19 | 1.1 MB | 2023-03-10 | [🗑️ 删除] │ │ +│ │ ... │ │ +│ └──────────────────────────────────────────────────────────┘ │ +├────────────────────────────────────────────────────────────────┤ +│ [ 清理全部版本] [ 忽略此包] │ +└────────────────────────────────────────────────────────────────┘ +抽屉交互： - 宽度：600px（桌面端），移动端全屏 - 遮罩层：点击遮罩或按 ESC 关闭 - 版本列表：支持虚拟滚动，按语义化版本排序 - 批量操作：底部提供”清理全部版本”和”忽略此包”快捷按钮 +#### 4.4 搜索逻辑 +模糊检索：匹配包名、版本号、文件大小 +const filteredPackages = packages.filter(pkg => { + return ( + pkg.name.toLowerCase().includes(keyword.toLowerCase()) || + pkg.versions.some(v => v.includes(keyword)) || + formatSize(pkg.size).includes(keyword) + ); +}); +#### 4.5 技术选型 +| 组件 | 用途 | +|---|---| +| el-input | 大圆角搜索框，带搜索图标 | +| el-table-v2 | 虚拟表格，支持万级数据 | +| el-drawer | 包详情抽屉，右侧滑出 | +| el-tag | 状态标签（预警/正常/已忽略） | +| vue-infinite-scroll | 滚动加载更多 | + +### 五、忽略列表页 +#### 5.1 界面布局 +┌────────────────────────────────────────────────────────────────┐ +│ 忽略列表 │ +├────────────────────────────────────────────────────────────────┤ +│ 共 15 个已忽略包 │ +├────────────────────────────────────────────────────────────────┤ +│ 包名 │ 版本数 │ 占用空间 │ 忽略时间 │ 操作 │ +├────────────────────────────────────────────────────────────────┤ +│ lodash │ 25 │ 128.5 MB │ 2024-01-15 │ [取消忽略] │ +│ @antv/g2 │ 32 │ 256.8 MB │ 2024-02-10 │ [取消忽略] │ +│ tensorflow │ 18 │ 2.1 GB │ 2024-03-05 │ [取消忽略] │ +│ legacy-utils │ 8 │ 45.2 MB │ 2024-04-01 │ [取消忽略] │ +│ ... │ ... │ ... │ ... │ ... │ +└────────────────────────────────────────────────────────────────┘ +设计要点： - 虚拟滚动：使用 el-table-v2，支持大量忽略包流畅滚动 - 无边框：行与行之间用浅灰分割线 #F0F0F0（1px） - 悬停高亮：鼠标悬停行背景变为 #FFF8F0 - 取消忽略：点击后弹出二次确认，确认后该包恢复至缓存概览列表 - 批量操作：顶部提供 [批量取消忽略] 按钮，支持勾选多个包批量恢复 +#### 5.2 交互说明 +点击 [取消忽略] → 弹出确认弹窗 → 确认后从忽略列表移除，恢复至缓存概览 +勾选多个包 → 点击 [批量取消忽略] → 批量恢复 +#### 5.3 技术选型 +| 组件 | 用途 | +|---|---| +| el-table-v2 | 虚拟表格，支持大量数据流畅滚动 | +| el-popconfirm | 取消忽略二次确认 | + +### 六、操作日志页 +#### 6.1 界面布局 +┌────────────────────────────────────────────────────────────────┐ +│ 操作日志 │ +├────────────────────────────────────────────────────────────────┤ +│ 筛选: [全部] [清理操作] [删除操作] [忽略操作] │ +├────────────────────────────────────────────────────────────────┤ +│ 时间 │ 操作类型 │ 包名 │ 详情 │ +├────────────────────────────────────────────────────────────────┤ +│ 2024-04-15 14:30 │ 清理 │ lodash │ 删除 3 个版本 │ +│ 2024-04-15 14:28 │ 忽略 │ @antv/g2 │ 标记为忽略 │ +│ 2024-04-15 14:25 │ 删除 │ legacy-utils │ 删除全部版本 │ +│ 2024-04-15 14:20 │ 清理 │ tensorflow │ 删除 5 个版本 │ +│ ... │ ... │ ... │ ... │ +├────────────────────────────────────────────────────────────────┤ +│ 共 156 条记录 < 1 2 3 4 5 ... 16 > 每页 10 条 │ +└────────────────────────────────────────────────────────────────┘ +设计要点： - 普通分页表格：使用 el-table + el-pagination，每页 10/20/50 条可选 - 操作类型标签：清理（活力橙）、删除（热情红）、忽略（静谧蓝） - 筛选器：顶部 pill 按钮，按操作类型过滤 - 时间倒序：最新操作在最上方 - 详情展开：点击行可展开查看完整操作详情（如删除了哪些具体版本） +#### 6.2 交互说明 +点击筛选标签 → 实时过滤对应类型的日志 +点击分页 → 切换页码，保持筛选条件 +点击行 → 展开查看详情（可选） +#### 6.3 技术选型 +| 组件 | 用途 | +|---|---| +| el-table | 普通分页表格 | +| el-pagination | 分页器 | +| el-tag | 操作类型标签 | +| el-collapse | 行详情展开 | + +### 七、阈值配置页 +#### 7.1 功能说明 +阈值配置页用于设置缓存预警规则，用户可以在这里自定义”多大算大”“多少版本算多”。 +#### 7.2 配置项（建议） +| 配置项 | 说明 | 默认值 | +|---|---|---| +| 单包最大版本数 | 超过此版本数的包标记为预警 | 20 | +| 单包最大占用空间 | 超过此大小的包标记为预警 | 500 MB | +| 总缓存上限 | 超过此总量的预警提示 | 50 GB | +| 版本保留最少数量 | 清理时至少保留的版本数 | 3 | +| 自动清理规则 | 是否开启自动清理旧版本 | 关闭 | + +#### 7.3 界面风格 +采用 C 端风格卡片表单，每个配置项为一个圆角卡片，包含： - 配置项名称 + 说明文字 - 输入框/开关控件 - 多巴胺配色的高亮保存按钮 +### 八、响应式设计 +#### 8.1 断点定义 +| 断点 | 尺寸范围 | 设备类型 | +|---|---|---| +| 手机端 | < 768px | 手机竖屏 | +| 平板端 | 768px ~ 1023px | 平板竖屏 / 小屏笔记本 | +| 桌面端 | ≥ 1024px | 主流显示器 / 平板横屏 | + +#### 8.2 顶部导航栏 — 三端适配 +桌面端（≥1024px） +┌────────────────────────────────────────────────────────────────┐ +│ 📦 Verdaccio Manager │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ +│ │ 概览 │ │ 搜索 │ │ 设置 │ │ 动态 │ │ +│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ +│ 👤 │ +└────────────────────────────────────────────────────────────────┘ +平板端（768px~1023px） +┌──────────────────────────────────────────────┐ +│ 📦 Verdaccio Manager │ +│ [概览] [搜索] [设置] [动态] 👤 │ +└──────────────────────────────────────────────┘ +导航按钮缩小为紧凑 pill，文字缩小至 14px +头像保持右侧 +手机端（<768px） +┌────────────────────────────────────┐ +│ 📦 Verdaccio Manager ☰ 👤 │ +└────────────────────────────────────┘ +导航按钮折叠为汉堡菜单 ☰ +点击汉堡菜单，从左侧滑出侧边抽屉，显示全部导航项 +侧边抽屉宽度 280px，遮罩层可点击关闭 +#### 8.3 缓存概览 — 三端适配 +桌面端（≥1024px）— 4 列网格 +┌──────────────┬──────────────┬──────────────┬──────────────────┐ +│ 📦 1,247 │ 💾 12.8 GB │ 🔥 23 │ 🧹 可省 3.2 GB │ +│ 个包 │ 占用空间 │ 个预警 │ [一键清理] │ +└──────────────┴──────────────┴──────────────┴──────────────────┘ +平板端（768px~1023px）— 2×2 网格 +┌──────────────┬──────────────┐ +│ 📦 1,247 │ 💾 12.8 GB │ +│ 个包 │ 占用空间 │ +├──────────────┼──────────────┤ +│ 🔥 23 │ 🧹 可省 3.2 GB │ +│ 个预警 │ [一键清理] │ +└──────────────┴──────────────┘ +手机端（<768px）— 单列滚动 +┌────────────────────────────────────┐ +│ 📦 1,247 个包 │ +├────────────────────────────────────┤ +│ 💾 12.8 GB 占用空间 │ +├────────────────────────────────────┤ +│ 🔥 23 个预警 │ +├────────────────────────────────────┤ +│ 🧹 可省 3.2 GB [一键清理] │ +└────────────────────────────────────┘ +每个卡片高度压缩至 80px +“一键清理”按钮缩小为图标按钮，放在卡片右侧 +#### 8.4 包列表 — 三端适配 +桌面端 — 卡片网格（4 列） +┌──────────────┬──────────────┬──────────────┬──────────────┐ +│ 📦 lodash │ 📦 axios │ 📦 @antv/g2 │ 📦 react │ +│ 25 版本 │ 18 版本 │ 32 版本 │ 15 版本 │ +│ 128.5 MB │ 45.2 MB │ 256.8 MB │ 89.3 MB │ +│ 🔥 预警 │ ✅ 正常 │ 🔥 预警 │ ✅ 正常 │ +│ [清理] [忽略]│ [清理] [忽略]│ [清理] [忽略]│ [清理] [忽略]│ +└──────────────┴──────────────┴──────────────┴──────────────┘ +平板端 — 卡片网格（2 列） +┌──────────────┬──────────────┐ +│ 📦 lodash │ 📦 axios │ +│ 25 版本 │ 18 版本 │ +│ 128.5 MB │ 45.2 MB │ +│ 🔥 预警 │ ✅ 正常 │ +│ [清理] [忽略]│ [清理] [忽略]│ +└──────────────┴──────────────┘ +手机端 — 单列卡片列表 +┌────────────────────────────────────┐ +│ 📦 lodash │ +│ 25 版本 · 128.5 MB · 🔥 预警 │ +│ [清理] [忽略] │ +├────────────────────────────────────┤ +│ 📦 axios │ +│ 18 版本 · 45.2 MB · ✅ 正常 │ +│ [清理] [忽略] │ +├────────────────────────────────────┤ +│ 📦 @antv/g2 │ +│ 32 版本 · 256.8 MB · 🔥 预警 │ +│ [清理] [忽略] │ +└────────────────────────────────────┘ +卡片高度压缩，操作按钮缩小为图标 +虚拟滚动保持，流畅不卡顿 +#### 8.5 全局搜索 — 三端适配 +桌面端 — 居中宽搜索框 +┌────────────────────────────────────────────────────────────────┐ +│ │ +│ 📦 搜索你的缓存包 │ +│ ┌──────────────────────────────────────────────────────┐ │ +│ │ 🔍 输入包名、版本、大小... │ │ +│ └──────────────────────────────────────────────────────┘ │ +│ │ +│ 热门: lodash axios react @antv/g2 │ +│ │ +└────────────────────────────────────────────────────────────────┘ +搜索框宽度 600px，高度 56px +平板端 — 居中搜索框（缩小） +┌──────────────────────────────────────────────┐ +│ │ +│ 📦 搜索你的缓存包 │ +│ ┌────────────────────────────────────┐ │ +│ │ 🔍 输入包名、版本... │ │ +│ └────────────────────────────────────┘ │ +│ │ +│ 热门: lodash axios react │ +│ │ +└──────────────────────────────────────────────┘ +搜索框宽度 100%（最大 500px），高度 48px +手机端 — 全宽搜索框 +┌────────────────────────────────────┐ +│ │ +│ 📦 搜索缓存包 │ +│ ┌──────────────────────────┐ │ +│ │ 🔍 搜索... │ │ +│ └──────────────────────────┘ │ +│ │ +│ 热门: lodash axios │ +│ │ +└────────────────────────────────────┘ +搜索框宽度 100%，高度 44px +热门搜索标签换行显示 +#### 8.6 忽略列表 — 三端适配 +桌面端 — 3 列卡片网格 +┌──────────────┬──────────────┬──────────────┐ +│ 📦 lodash │ 📦 @antv/g2 │ 📦 tensorflow│ +│ 25 版本 │ 32 版本 │ 18 版本 │ +│ 128.5 MB │ 256.8 MB │ 2.1 GB │ +│ [取消忽略] │ [取消忽略] │ [取消忽略] │ +└──────────────┴──────────────┴──────────────┘ +平板端 — 2 列卡片网格 +┌──────────────┬──────────────┐ +│ 📦 lodash │ 📦 @antv/g2 │ +│ 25 版本 │ 32 版本 │ +│ 128.5 MB │ 256.8 MB │ +│ [取消忽略] │ [取消忽略] │ +└──────────────┴──────────────┘ +手机端 — 单列卡片列表 +┌────────────────────────────────────┐ +│ 📦 lodash │ +│ 25 版本 · 128.5 MB │ +│ [取消忽略] │ +├────────────────────────────────────┤ +│ 📦 @antv/g2 │ +│ 32 版本 · 256.8 MB │ +│ [取消忽略] │ +└────────────────────────────────────┘ +#### 8.7 操作日志（时间线）— 三端适配 +桌面端 — 左右分栏 +┌────────────────────────────────────────────────────────────────┐ +│ 🕐 最近动态 │ +├────────────────────────────────────────────────────────────────┤ +│ 今天 │ +│ ● 14:30 清理了 lodash 的 3 个旧版本 🧹 │ +│ ● 14:28 忽略了 @antv/g2 💤 │ +│ │ +│ 昨天 │ +│ ● 09:15 删除了 legacy-utils 的全部版本 🗑️ │ +└────────────────────────────────────────────────────────────────┘ +平板端 — 单栏（缩小间距） +时间线节点间距缩小 +emoji 保持，文字缩小至 14px +手机端 — 单栏（紧凑） +┌────────────────────────────────────┐ +│ 🕐 最近动态 │ +├────────────────────────────────────┤ +│ 今天 │ +│ ● 14:30 清理 lodash 3 版本 🧹 │ +│ ● 14:28 忽略 @antv/g2 💤 │ +│ │ +│ 昨天 │ +│ ● 09:15 删除 legacy-utils 🗑️ │ +│ │ +│ [加载更多] │ +└────────────────────────────────────┘ +文案精简，去掉冗余文字 +时间线节点缩小 +#### 8.8 包详情抽屉 — 三端适配 +桌面端 — 右侧抽屉（600px） +┌────────────────────────────────────────────────────────────────┐ +│ 主内容区 │ 📦 lodash [×] │ +│ │ 25 版本 · 128.5 MB │ +│ │ 🔥 预警 │ +│ │ │ +│ │ 版本列表 │ +│ │ 4.17.21 · 1.2 MB │ +│ │ 4.17.20 · 1.2 MB │ +│ │ │ +│ │ [🧹 清理全部] [💤 忽略] │ +└────────────────────────────────────────────────────────────────┘ +平板端 — 右侧抽屉（50% 宽度） +抽屉宽度为屏幕的 50% +内容自适应 +手机端 — 底部弹窗（全屏） +┌────────────────────────────────────┐ +│ │ +│ ┌──────────────────────────────┐ │ +│ │ 📦 lodash [×] │ │ +│ │ 25 版本 · 128.5 MB │ │ +│ │ 🔥 预警 │ │ +│ │ │ │ +│ │ 版本列表 │ │ +│ │ 4.17.21 · 1.2 MB │ │ +│ │ 4.17.20 · 1.2 MB │ │ +│ │ │ │ +│ │ [🧹 清理] [💤 忽略] │ │ +│ └──────────────────────────────┘ │ +│ │ +└────────────────────────────────────┘ +从底部滑出，高度 85vh +顶部大圆角 24px +支持向下滑动关闭 +#### 8.9 CSS 断点实现（Tailwind 风格） +/* 桌面端：≥1024px */ +@media (min-width: 1024px) { + .grid-cards { grid-template-columns: repeat(4, 1fr); } + .grid-ignore { grid-template-columns: repeat(3, 1fr); } + .search-box { width: 600px; height: 56px; } + .drawer { width: 600px; } +} + +/* 平板端：768px ~ 1023px */ +@media (min-width: 768px) and (max-width: 1023px) { + .grid-cards { grid-template-columns: repeat(2, 1fr); } + .grid-ignore { grid-template-columns: repeat(2, 1fr); } + .search-box { width: 100%; max-width: 500px; height: 48px; } + .drawer { width: 50%; } +} + +/* 手机端：<768px */ +@media (max-width: 767px) { + .grid-cards { grid-template-columns: 1fr; } + .grid-ignore { grid-template-columns: 1fr; } + .search-box { width: 100%; height: 44px; } + .drawer { width: 100%; height: 85vh; border-radius: 24px 24px 0 0; } + .nav-pills { display: none; } + .hamburger { display: block; } +} +#### 8.10 响应式速查表 +| 组件 | 桌面端 | 平板端 | 手机端 | +|---|---|---|---| +| 导航栏 | 顶部 pill 按钮 | 顶部紧凑 pill | 汉堡菜单 + 侧边抽屉 | +| 统计卡片 | 4 列网格 | 2×2 网格 | 单列滚动 | +| 包列表 | 4 列卡片网格 | 2 列卡片网格 | 单列卡片列表 | +| 忽略列表 | 3 列卡片网格 | 2 列卡片网格 | 单列卡片列表 | +| 搜索框 | 居中 600px | 居中 100%（max 500px） | 全宽 100% | +| 操作日志 | 左右分栏时间线 | 单栏时间线 | 单栏紧凑时间线 | +| 包详情 | 右侧抽屉 600px | 右侧抽屉 50% | 底部弹窗 85vh | + +### 九、动效规范 +| 场景 | 动效 | +|---|---| +| 页面切换 | 平滑淡入 + 轻微上滑 | +| 卡片悬停 | 轻微上浮 + 阴影加深 | +| 按钮点击 | 缩放 0.95 + 回弹 | +| 弹窗打开 | 从底部滑入 + 遮罩淡入 | +| 清理操作 | 卡片缩小消失 + 成功提示 toast | + +### 十、文案风格对照 +| 后台管理系统 | C端风格 | +|---|---| +| “缓存管理” | “你的缓存” | +| “操作日志” | “最近动态” | +| “忽略列表” | “已忽略的包” | +| “阈值配置” | “预警设置” | +| “执行清理” | “一键清理” | +| “共 156 条记录” | “156 条动态” | + +### 十一、技术组件选型汇总 +| 页面 | 核心组件 | 用途 | +|---|---|---| +| 缓存概览 | el-card + el-tag + el-progress | 统计卡片 + 状态标签 + 进度条 | +| 全局检索 | el-input + el-table-v2 + el-drawer | 搜索框 + 虚拟表格 + 详情抽屉 | +| 忽略列表 | el-table-v2 + el-popconfirm | 虚拟表格 + 二次确认 | +| 操作日志 | el-table + el-pagination + el-collapse | 分页表格 + 分页器 + 详情展开 | +| 阈值配置 | el-form + el-switch + el-input-number | 表单配置 | +| 全局 | el-tooltip + el-toast | 工具提示 + 操作反馈 | + +### 十二、后端数据扫描逻辑 +后端扫描 Verdaccio storage/ 目录时，按以下逻辑聚合数据： +storage/ +├── lodash/ +│ └── package.json ← 读取 versions、time、_rev +├── @antv/ +│ └── g2/ +│ └── package.json +└── ... +遍历 storage/ 下所有包的 package.json +解析 versions 字段获取版本列表 +读取对应 .tgz 文件计算占用空间 +返回聚合后的 JSON 数据给前端 +### 十三、方案对比：卡片列表 vs 文件树 +| 方案 | 优点 | 缺点 | +|---|---|---| +| 文件树 | 还原真实目录结构 | 层级深、信息分散、scoped 包路径嵌套混乱 | +| 卡片列表（推荐） | 信息聚合、一目了然、操作便捷 | 不展示原始文件路径（但本工具不需要） | + +Verdaccio 的存储结构是以包为单位的扁平目录，每个包下只有一个 package.json 和若干 .tgz 文件。直接展示文件树会让用户看到大量无意义的目录嵌套（如 @antv/g2/package.json），而卡片列表能直接呈现用户关心的包维度信息，更符合本工具的管理目标。 +### 十四、登录页面 +#### 14.1 页面定位 +登录页面是用户进入系统的入口，也是塑造产品第一印象的关键页面。遵循 C 端设计风格，登录页不应是冷冰冰的表单堆砌，而应传达出产品的温度与品质感。整体采用居中卡片式布局，搭配多巴胺配色渐变背景，营造轻盈、友好的视觉体验。 +#### 14.2 界面布局 +登录页面采用全屏渐变背景 + 居中白色卡片的设计模式，卡片承载所有登录表单元素。桌面端卡片宽度固定，平板端自适应，手机端卡片宽度 100% 并去除多余外边距。 +┌────────────────────────────────────────────────────────────────┐ +│ │ +│ (渐变背景) │ +│ │ +│ ┌──────────────────────────────┐ │ +│ │ │ │ +│ │ 📦 Verdaccio Manager │ │ +│ │ │ │ +│ │ 欢迎回来，请登录你的账户 │ │ +│ │ │ │ +│ │ ┌────────────────────────┐ │ │ +│ │ │ 👤 用户名 │ │ │ +│ │ └────────────────────────┘ │ │ +│ │ │ │ +│ │ ┌────────────────────────┐ │ │ +│ │ │ 🔒 密码 │ │ │ +│ │ └────────────────────────┘ │ │ +│ │ │ │ +│ │ ┌────────────────────────┐ │ │ +│ │ │ 登 录 │ │ │ +│ │ └────────────────────────┘ │ │ +│ │ │ │ +│ │ [ ] 记住我 忘记密码？ │ │ +│ └──────────────────────────────┘ │ +│ │ +└────────────────────────────────────────────────────────────────┘ +#### 14.3 设计要点 +| 设计元素 | 规格 | 说明 | +|---|---|---| +| 背景 | 渐变背景 | 多巴胺配色渐变（如清新绿 #32CD32 → 静谧蓝 #1E90FF），营造活力氛围 | +| 卡片 | 白色圆角卡片 | border-radius: 24px，柔和弥散阴影，宽度 420px（桌面端） | +| Logo | 📦 Verdaccio Manager | 卡片顶部居中展示，字号 24px，活力橙 #FF8C00 | +| 副标题 | 欢迎回来，请登录你的账户 | 字号 14px，浅灰色 #666666，传递温度感 | +| 输入框 | 大圆角 + emoji 图标 | border-radius: 12px，左侧 emoji 图标（👤/🔒），高度 48px | +| 登录按钮 | 多巴胺色渐变按钮 | 圆角 12px，高度 48px，渐变背景（活力橙 → 热情红），悬停微上浮 | + +#### 14.4 表单字段说明 +| 字段 | 类型 | 说明 | +|---|---|---| +| 用户名 | 文本输入框 | 支持邮箱或用户名登录，带实时校验（格式是否正确） | +| 密码 | 密码输入框 | 支持明文/密文切换（眼睛图标），最少 6 位 | +| 记住我 | 复选框 | 勾选后 Cookie 保存登录状态，7 天免登录 | +| 忘记密码 | 链接文字 | 点击跳转至密码找回流程（邮件重置） | + +#### 14.5 交互说明 +• 输入框聚焦：边框变为活力橙 #FF8C00，底部出现橙色下划线动画 +• 登录按钮点击：按钮缩小至 0.95 倍 + 加载旋转图标，防止重复提交 +• 登录成功：按钮变为绿色 + "登录成功" 提示，1s 后跳转首页 +• 登录失败：输入框边框变红 #FF4500，下方显示错误提示文字（如"用户名或密码错误"） +• 记住我：勾选后本地加密存储 token，下次打开自动填充用户名 +• 忘记密码：点击后平滑过渡到密码找回页面（同一卡片内切换内容） +#### 14.6 三端适配 +登录页面作为全站入口，需要在所有设备上都有良好的体验。以下是三端适配方案： +桌面端（≥1024px） +┌────────────────────────────────────────────────────────────────┐ +│ ┌──────────────────────────────┐ │ +│ │ 📦 Verdaccio Manager │ │ +│ │ 欢迎回来，请登录你的账户 │ │ +│ │ [👤 用户名输入框] │ │ +│ │ [🔒 密码输入框] │ │ +│ │ [ 登 录 ] │ │ +│ │ [ ] 记住我 忘记密码？ │ │ +│ └──────────────────────────────┘ │ +└────────────────────────────────────────────────────────────────┘ +卡片宽度 420px，居中显示，背景渐变全屏铺满。 +平板端（768px~1023px） +┌──────────────────────────────────────┐ +│ ┌────────────────────────────┐ │ +│ │ 📦 Verdaccio Manager │ │ +│ │ 欢迎回来，请登录 │ │ +│ │ [👤 用户名] │ │ +│ │ [🔒 密码] │ │ +│ │ [ 登 录 ] │ │ +│ │ [ ] 记住我 忘记密码？ │ │ +│ └────────────────────────────┘ │ +└──────────────────────────────────────┘ +卡片宽度 100%（最大 420px），外边距自动居中，背景渐变保持。 +手机端（<768px） +┌────────────────────────────┐ +│ ┌────────────────────────┐ │ +│ │ 📦 Verdaccio Manager │ │ +│ │ 欢迎回来，请登录 │ │ +│ │ [👤 用户名] │ │ +│ │ [🔒 密码] │ │ +│ │ [ 登 录 ] │ │ +│ │ [ ] 记住我 忘记密码？ │ │ +│ └────────────────────────┘ │ +└────────────────────────────┘ +卡片宽度 100%（去除左右外边距），输入框高度压缩至 44px，按钮高度 44px，整体间距缩小，适配手指触控操作。 +#### 14.7 登录页响应式速查表 +| 设备 | 卡片宽度 | 特殊适配 | +|---|---|---| +| 桌面端（≥1024px） | 420px 固定 | 居中显示，背景渐变全屏 | +| 平板端（768px~1023px） | 100%（max 420px） | 外边距自动居中 | +| 手机端（<768px） | 100%（无边距） | 输入框/按钮高度压缩至 44px，适配触控 | +| 横屏适配 | 420px 或 100% | 横屏时卡片改为左右分栏（左侧品牌区 + 右侧表单区） | + +#### 14.8 技术选型 +| 组件/技术 | 用途 | +|---|---| +| el-form + el-form-item | 表单容器与字段校验 | +| el-input（带前缀图标） | 用户名/密码输入框 | +| el-button（渐变背景） | 登录按钮 | +| el-checkbox | 记住我复选框 | + +#### 14.9 安全建议 +• 密码传输必须使用 HTTPS 加密 +• 登录失败超过 5 次锁定账户 15 分钟 +• Token 采用 JWT 格式，设置合理的过期时间（建议 24 小时） +• 敏感操作（如批量清理）需二次确认或重新输入密码 +• 防止 XSS 攻击：所有用户输入进行转义处理 +• 防止 CSRF 攻击：关键接口携带 CSRF Token \ No newline at end of file