本目录包含 drpy-node-admin 解耦与 SPA 插件化重构的完整规划文档：
- SPEC.md - 总体规划与架构设计
- IMPLEMENTATION.md - 详细实现指南与代码示例
- API.md - REST API 接口完整文档
- ROADMAP.md - 本文件，实施路线图
┌─────────────────────────────────────────────────────┐
│ 当前架构 │
├─────────────────────────────────────────────────────┤
│ │
│ drpy-node-admin │
│ │ │
│ ├──→ /admin/mcp (调用 MCP 工具) │
│ │ │
│ drpy-node │
│ │ │
│ └──→ import('../drpy-node-mcp/tools/*.js') ❌ │
│ │
│ drpy-node-mcp (独立项目) │
│ │ │
│ └──→ 依赖 drpy-node (仅用于开发调试) │
│ │
└─────────────────────────────────────────────────────┘
核心问题: drpy-node 作为主服务，不应该依赖 drpy-node-mcp
┌─────────────────────────────────────────────────────┐
│ 目标架构 │
├─────────────────────────────────────────────────────┤
│ │
│ drpy-node (主服务) │
│ │ │
│ ├──→ /api/admin/* (REST API) │
│ │ │
│ ├──→ /admin/* (静态文件) │
│ │ │
│ └──→ apps/admin/ (编译后的 SPA) ✓ │
│ │
│ drpy-node-admin (开发时) │
│ │ │
│ └──→ npm run dev (开发服务器) │
│ │
│ drpy-node-mcp (独立项目) │
│ │ │
│ └──→ 依赖 drpy-node 的 API (可选) │
│ │
└─────────────────────────────────────────────────────┘
| 操作 | 文件路径 | 说明 |
|---|---|---|
| 重构 | controllers/admin.js |
移除 MCP 依赖，实现直接业务逻辑 |
| 新增 | controllers/admin/*.js |
6 个子控制器模块 |
| 新增 | utils/admin/*.js |
3 个工具模块 |
| 新增 | apps/admin/ |
编译后的 SPA 静态文件 |
| 操作 | 文件路径 | 说明 |
|---|---|---|
| 重构 | src/api/*.js |
所有 API 调用改用 REST API |
| 新增 | src/api/admin.js |
统一 API 调用模块 |
| 修改 | vite.config.js |
输出目录改为 ../apps/admin |
| 修改 | src/stores/*.js |
适配新的 API 响应格式 |
目标: 实现所有必需的 REST API 接口
✓ controllers/admin/systemController.js - 系统管理
✓ controllers/admin/logsController.js - 日志管理
✓ controllers/admin/sourcesController.js - 源管理
✓ controllers/admin/filesController.js - 文件管理
✓ controllers/admin/dbController.js - 数据库查询
✓ controllers/admin/routesController.js - 路由信息
✓ 移除 import('../drpy-node-mcp/...') 代码
✓ 注册子控制器路由
✓ 实现 WebSocket 日志流
✓ 添加静态文件服务
✓ utils/admin/logReader.js - 日志读取
✓ utils/admin/configManager.js - 配置管理
✓ utils/admin/fileValidator.js - 路径安全验证
✓ 使用 Postman/Thunder 测试所有 API
✓ 验证响应格式正确性
✓ 测试 WebSocket 连接
目标: 前端改用新的 REST API
✓ src/api/admin.js - 统一 API 调用
✓ src/api/system.js - 系统相关
✓ src/api/spider.js - 源管理
✓ src/api/file.js - 文件管理
✓ src/api/db.js - 数据库查询 (新增)
✓ 修改 build.outDir 为 ../apps/admin
✓ 修改 base 为 /admin/
✓ 调整 proxy 配置
✓ 开发模式测试所有功能
✓ 验证 API 调用正常
✓ 测试 WebSocket 日志流
目标: 完成 SPA 插件构建和集成
✓ 添加 scripts/build-admin.js
✓ 更新 package.json 脚本
✓ npm run admin:build
✓ 验证 apps/admin/ 目录生成
✓ 检查 index.html 和 assets
✓ 启动 drpy-node 服务
✓ 访问 http://localhost:5757/admin/
✓ 全面功能测试
✓ 性能测试
目标: 移除 MCP 依赖，优化代码
✓ 移除 /admin/mcp 端点
✓ 清理相关注释
✓ 提取公共逻辑
✓ 添加错误处理
✓ 完善日志记录
✓ 更新 README.md
✓ 更新 API.md
✓ 添加部署文档
drpy-node/
├── controllers/admin/
│ ├── systemController.js ← 新增
│ ├── logsController.js ← 新增
│ ├── sourcesController.js ← 新增
│ ├── filesController.js ← 新增
│ ├── dbController.js ← 新增
│ └── routesController.js ← 新增
└── utils/admin/
├── logReader.js ← 新增
├── configManager.js ← 新增
└── fileValidator.js ← 新增
drpy-node/
└── controllers/
└── admin.js ← 重构
drpy-node-admin/
└── src/api/
└── admin.js ← 新增
drpy-node-admin/
├── src/api/
│ ├── client.js ← 修改 baseURL
│ ├── system.js ← 重构 API 调用
│ ├── spider.js ← 重构 API 调用
│ └── file.js ← 重构 API 调用
└── vite.config.js ← 修改构建配置
drpy-node-admin
│
│ POST /admin/mcp
│ { "name": "list_sources", "arguments": {} }
↓
drpy-node (admin.js)
│
│ import('../drpy-node-mcp/tools/spiderTools.js')
↓
drpy-node-mcp
│
│ return { content: [{ type: "text", text: JSON.stringify(...) }] }
↓
drpy-node-admin
│
│ JSON.parse(response.content[0].text)
drpy-node-admin
│
│ GET /api/admin/sources
↓
drpy-node (admin.js)
│
│ 直接调用 sourcesController.listSources()
│
│ return { js: [...], catvod: [...] }
↓
drpy-node-admin
# 终端 1: 启动 drpy-node
npm run dev
# 终端 2: 启动 drpy-node-admin 开发服务器
cd drpy-node-admin
npm run dev
# 访问: http://localhost:5174/
# API 请求自动代理到 http://localhost:5757cd drpy-node-admin
npm run build
# 输出到: ../apps/admin/
# 包含: index.html, assets/*.js, assets/*.css# 启动 drpy-node
npm run dev
# 访问: http://localhost:5757/admin/选择: 使用 @fastify/websocket
原因:
- drpy-node 已使用 Fastify
- @fastify/websocket 官方插件
- 与现有架构兼容
替代方案:
- Socket.io (需要额外依赖)
- 原生 WebSocket (需要手动处理)
选择: 使用 POST JSON body 传输内容
限制:
- 适合中小文件
- 不支持大文件上传
如果需要大文件支持:
- 可考虑 multipart/form-data
- 或分片上传
策略:
- 白名单方式（只允许特定目录）
- 禁止路径遍历（..）
- 禁止敏感文件
策略:
- 只允许 SELECT 查询
- 关键词黑名单过滤
- 参数化查询（如需要）
- 所有现有功能可正常使用
- API 响应时间与之前相当
- WebSocket 日志流稳定
- 无 MCP 依赖
- 代码结构清晰
- 有适当的错误处理
- API 文档完整
- 代码注释充分
- 易于扩展
-
审查文档
- 仔细阅读 SPEC.md
- 理解 IMPLEMENTATION.md 中的代码示例
- 熟悉 API.md 中的接口规范
-
确认计划
- 评估时间估算是否合理
- 确认技术方案可行
- 提出调整建议（如有）
-
开始实施
- 按照 Phase 1 → Phase 2 → Phase 3 顺序执行
- 每个阶段完成后进行测试
- 遇到问题及时调整
如有疑问或需要调整，请及时沟通。在开始实施前，请确保：
- ✅ 已完整阅读所有规划文档
- ✅ 理解技术方案和架构设计
- ✅ 确认实施计划和时间安排
- ✅ 了解风险和应对措施
准备好后，请指示开始实施！