Skip to content

SPEC.md

Latest commit

 

History

History
581 lines (496 loc) · 15 KB

SPEC.md

File metadata and controls

581 lines (496 loc) · 15 KB

drpy-node-admin 解耦与 SPA 插件化重构 SPEC

1. 项目概述

1.1 当前状态

  • drpy-node-admin: 独立的 Vue 3 后台管理项目
  • 数据依赖: 通过 MCP (Model Context Protocol) 工具调用 drpy-node 功能
  • 耦合问题: admin.js 中动态导入 drpy-node-mcp 模块，违反依赖方向

1.2 目标架构

┌─────────────────────────────────────────────────────────────┐
│                        drpy-node                            │
│  ┌──────────────┐  ┌───────────────┐  ┌──────────────┐     │
│  │  Core APIs   │  │   Controllers  │  │   Static     │     │
│  │              │  │               │  │   Files      │     │
│  │ - /api/*     │◄─┤ - admin.js    │◄─┤ /apps/admin  │     │
│  │ - /admin/*   │  │ - api.js       │  │              │     │
│  │              │  │ - config.js    │  │ - index.html │     │
│  │              │  │ - ...          │  │ - assets/*   │     │
│  └──────────────┘  └───────────────┘  └──────────────┘     │
│         ▲                                    ▲               │
│         │                                    │               │
│         └──────────────┬─────────────────────┘               │
│                        │                                     │
│  ┌─────────────────────────────────────────────────────────┐│
│  │              drpy-node-admin (SPA Plugin)              ││
│  │  ┌─────────┐  ┌──────────┐  ┌────────────┐           ││
│  │  │  Views  │  │ Stores   │  │Components   │           ││
│  │  └────┬────┘  └────┬─────┘  └──────┬─────┘           ││
│  │       │            │               │                    ││
│  │       └──────┬─────┴───────────────┴────┐              ││
│  │              │  API Client (axios)    │              ││
│  │              └───────────┬─────────────┘              ││
│  │                          │                             ││
│  │              ┌───────────┴─────────────┐              ││
│  │              │  REST API Interface     │              ││
│  │              │  /api/admin/*           │              ││
│  │              └──────────────────────────┘              ││
│  └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘

                        ▲
                        │
        ┌───────────────┴───────────────┐
        │   drpy-node-mcp (Independent)  │
        │   ┌────────────────────────┐  │
        │   │  MCP Tools              │  │
        │   │  - systemTools.js       │  │
        │   │  - spiderTools.js       │  │
        │   │  - fsTools.js           │  │
        │   │  - dbTools.js           │  │
        │   │  - apiTools.js          │  │
        │   └────────────────────────┘  │
        │            ▲                   │
        │            │ (depends on)      │
        │            └───────────────────┘
        └──────────────────────────────────┘

2. 需要实现的 REST API

2.1 系统管理 API

2.1.1 健康检查

GET /api/admin/health
Response: {
  status: "ok" | "error",
  uptime: number,
  memory: { used: number, total: number },
  version: string
}

2.1.2 服务重启

POST /api/admin/restart
Response: {
  success: boolean,
  message: string
}

2.2 日志 API

2.2.1 读取日志

GET /api/admin/logs?lines=50
Response: {
  file: string,
  content: string
}

2.2.2 WebSocket 实时日志

WS /api/admin/logs/stream
Message: {
  type: "log" | "error" | "end",
  content: string,
  timestamp: number
}

2.3 配置管理 API

2.3.1 获取配置

GET /api/admin/config?key=section.key
Response: any (配置值)

2.3.2 更新配置

POST /api/admin/config
Body: {
  key: string,
  value: any
}
Response: {
  success: boolean,
  message: string
}

2.4 源管理 API

2.4.1 列出所有源

GET /api/admin/sources
Response: {
  js: string[],
  catvod: string[]
}

2.4.2 验证源

POST /api/admin/sources/validate
Body: {
  path: string
}
Response: {
  isValid: boolean,
  message: string
}

2.4.3 检查语法

POST /api/admin/sources/syntax
Body: {
  path: string
}
Response: {
  isValid: boolean,
  error?: string
}

2.4.4 获取模板

GET /api/admin/sources/template
Response: {
  template: string
}

2.5 文件系统 API

2.5.1 列出目录

GET /api/admin/files/list?path=spider/js
Response: [{
  name: string,
  path: string,
  isDirectory: boolean,
  size?: number
}]

2.5.2 读取文件

GET /api/admin/files/read?path=spider/js/test.js
Response: {
  type: "text" | "image",
  content?: string,
  mimeType?: string,
  dataUrl?: string
}

2.5.3 写入文件

POST /api/admin/files/write
Body: {
  path: string,
  content: string
}
Response: {
  success: boolean,
  message: string
}

2.5.4 删除文件

DELETE /api/admin/files/delete?path=spider/js/test.js
Response: {
  success: boolean,
  message: string
}

2.6 数据库 API

2.6.1 执行查询

POST /api/admin/db/query
Body: {
  sql: string
}
Response: [{
  // 查询结果行
}]

2.7 路由信息 API

2.7.1 获取路由列表

GET /api/admin/routes
Response: {
  registered_controllers: string[]
}

3. 文件结构规划

3.1 drpy-node 新增文件

drpy-node/
├── controllers/
│   ├── admin.js                    # 重构，移除 MCP 依赖
│   └── admin/
│       ├── systemController.js     # 系统管理
│       ├── logsController.js       # 日志管理
│       ├── sourcesController.js    # 源管理
│       ├── filesController.js      # 文件管理
│       ├── dbController.js         # 数据库查询
│       └── routesController.js    # 路由信息
├── utils/
│   └── admin/
│       ├── logReader.js            # 日志读取工具
│       ├── configManager.js        # 配置管理工具
│       └── fileValidator.js        # 文件安全验证
└── apps/
    └── admin/                      # 新增：编译后的 admin SPA
        ├── index.html
        └── assets/
            ├── index-*.js
            └── index-*.css

3.2 drpy-node-admin 文件调整

drpy-node-admin/
├── src/
│   ├── api/
│   │   ├── client.js               # 保持，调整 baseURL
│   │   ├── admin.js                # 新增：统一的 admin API 调用
│   │   ├── system.js               # 重构：使用 /api/admin/system
│   │   ├── sources.js              # 重构：使用 /api/admin/sources
│   │   ├── files.js                # 重构：使用 /api/admin/files
│   │   └── db.js                   # 重构：使用 /api/admin/db
│   ├── views/
│   │   └── ... (保持不变)
│   ├── stores/
│   │   └── ... (保持不变)
│   └── components/
│       └── ... (保持不变)
├── vite.config.js                   # 调整：output 指向 apps/admin
├── package.json
└── tailwind.config.js

4. 实施步骤

Phase 1: API 层实现 (drpy-node)

步骤 1.1: 创建 admin 子控制器

  1. 创建 controllers/admin/ 目录
  2. 实现 6 个子控制器模块
  3. 每个控制器实现对应的 API 接口

步骤 1.2: 重构 admin.js

  1. 移除 import('../drpy-node-mcp/...') 动态导入
  2. 实现独立的业务逻辑
  3. 注册子控制器路由
  4. 添加静态文件服务指向 apps/admin/

步骤 1.3: 实现工具函数

  1. utils/admin/logReader.js - 日志文件读取
  2. utils/admin/configManager.js - 配置文件管理
  3. utils/admin/fileValidator.js - 路径安全验证

Phase 2: 前端适配 (drpy-node-admin)

步骤 2.1: API 客户端重构

  1. 调整 baseURL 为 /api/admin
  2. 移除 MCP 响应解析逻辑
  3. 实现标准的 REST API 调用

步骤 2.2: Vite 配置调整

  1. 修改 build.outDir 为 ../apps/admin
  2. 修改 base 为 /admin/
  3. 添加构建优化配置

步骤 2.3: 路由模式调整

  1. 使用 history 模式或 hash 模式
  2. 添加路由回退处理

Phase 3: 构建与集成

步骤 3.1: 本地测试

  1. 运行 npm run admin:build 构建
  2. 验证生成的文件在 apps/admin/ 目录
  3. 测试所有功能正常工作

步骤 3.2: 最终验证

  1. 清理 MCP 依赖
  2. 确认 drpy-node 可以独立运行
  3. 性能测试

5. API 详细规范

5.1 通用响应格式

// 成功响应
{
  success: true,
  data?: any,
  message?: string
}

// 错误响应
{
  success: false,
  error: string,
  code?: string
}

5.2 错误码定义

const ErrorCodes = {
  UNAUTHORIZED: 'UNAUTHORIZED',
  FORBIDDEN: 'FORBIDDEN',
  NOT_FOUND: 'NOT_FOUND',
  INVALID_PATH: 'INVALID_PATH',
  SYNTAX_ERROR: 'SYNTAX_ERROR',
  VALIDATION_ERROR: 'VALIDATION_ERROR',
  INTERNAL_ERROR: 'INTERNAL_ERROR'
}

5.3 认证与授权

// 使用与 /apps/ 相同的认证机制
// 所有 /api/admin/* 接口需要 basic auth

6. WebSocket 实时日志规范

6.1 连接

WS /api/admin/logs/stream

6.2 消息格式

// 客户端 → 服务端
{
  action: "subscribe" | "unsubscribe" | "clear",
  lines?: number
}

// 服务端 → 客户端
{
  type: "log" | "error" | "end",
  timestamp: number,
  content: string
}

6.3 心跳机制

// 每 30 秒发送一次心跳
// 客户端
setInterval(() => {
  ws.send(JSON.stringify({ type: 'heartbeat' }))
}, 30000)

// 服务端响应
{ type: 'pong' }

7. 安全考虑

7.1 路径验证

// 只允许访问特定目录
const ALLOWED_PATHS = [
  'spider/js',
  'spider/js_dr2',
  'spider/catvod',
  'spider/py',
  'spider/xbpq',
  'config',
  'json',
  'docs'
];

// 禁止路径遍历
function validatePath(path) {
  return !path.includes('..') &&
         !path.includes('~') &&
         !path.startsWith('/');

}

7.2 SQL 注入防护

// 只允许 SELECT 查询
if (!query.trim().toLowerCase().startsWith('select')) {
  throw new Error('Only SELECT queries allowed');
}

7.3 文件操作限制

// 禁止写入关键文件
const PROTECTED_FILES = [
  'package.json',
  'index.js',
  'database.db'
];

8. 性能优化

8.1 日志流式传输

// 使用流式传输大日志文件
const stream = fs.createReadStream(logPath);
stream.on('data', (chunk) => {
  ws.send({ type: 'log', content: chunk.toString() });
});

8.2 静态资源缓存

// admin 静态资源缓存策略
fastify.register(fastifyStatic, {
  root: adminDistPath,
  prefix: '/admin/',
  cacheControl: 3600, // 1 小时
  etag: true
});

8.3 API 响应压缩

// 启用 gzip 压缩
import fastifyCompress from '@fastify/compress';
fastify.register(fastifyCompress);

9. 兼容性说明

9.1 向后兼容

  • 保留 /admin/mcp 接口作为临时兼容层（可配置开关）
  • 给予过渡期，逐步迁移到新 API

9.2 版本控制

// API 版本号
const API_VERSION = 'v1';
// 所有响应头包含版本
reply.header('X-API-Version', API_VERSION);

10. 测试计划

10.1 单元测试

  • 每个控制器函数的单元测试
  • 工具函数的单元测试
  • API 响应格式验证

10.2 集成测试

  • API 端到端测试
  • WebSocket 连接测试
  • 文件上传下载测试

10.3 性能测试

  • 日志流式传输性能
  • 大文件读取性能
  • 并发请求处理

11. 交付物清单

11.1 drpy-node 修改

  • controllers/admin.js - 重构完成
  • controllers/admin/systemController.js - 新增
  • controllers/admin/logsController.js - 新增
  • controllers/admin/sourcesController.js - 新增
  • controllers/admin/filesController.js - 新增
  • controllers/admin/dbController.js - 新增
  • controllers/admin/routesController.js - 新增
  • utils/admin/logReader.js - 新增
  • utils/admin/configManager.js - 新增
  • utils/admin/fileValidator.js - 新增

11.2 drpy-node-admin 修改

  • src/api/client.js - baseURL 调整
  • src/api/admin.js - 统一 API 调用
  • src/api/system.js - API 重构
  • src/api/spider.js - API 重构
  • src/api/file.js - API 重构
  • src/api/db.js - API 重构
  • vite.config.js - 构建配置调整
  • package.json - 脚本更新

11.3 文档

  • API 接口文档
  • 部署指南
  • 开发指南更新
  • 变更日志

12. 时间估算

阶段 任务 预计时间
Phase 1 API 层实现 2-3 天
Phase 2 前端适配 1-2 天
Phase 3 构建与集成 1 天
测试与修复 全面测试 1-2 天
总计 5-8 天

13. 风险与应对

13.1 技术风险

风险: 解耦后功能缺失 应对: 详细的功能对比测试清单

13.2 兼容性风险

风险: 现有部署环境适配问题 应对: 保持 MCP 临时兼容层

13.3 性能风险

风险: 新架构性能下降 应对: 性能基准测试和优化

14. 后续优化方向

14.1 功能增强

  • 添加源市场功能
  • 添加源订阅功能
  • 添加统计分析功能

14.2 用户体验优化

  • 实现主题自定义
  • 添加快捷键支持
  • 优化移动端体验

14.3 运维功能

  • 添加系统监控图表
  • 实现日志分析功能
  • 添加性能指标展示