XuJiacheng
7ac3949dfa
重构项目心跳数据结构为Redis LIST，更新相关文档和OpenSpec规范。主要变更包括： - 将项目心跳从STRING改为LIST类型 - 更新后端服务以支持LIST操作 - 同步更新文档和OpenSpec规范 - 统一后端端口为3001 - 添加部署指南和Windows部署文档 修复前端API请求路径，移除硬编码的localhost地址。添加PM2和Nginx配置文件模板，完善部署流程文档。更新Redis集成协议文档，明确LIST数据结构和外部项目对接规范。
337 lines
8.4 KiB
Markdown
337 lines
8.4 KiB
Markdown
# BLS Project Console
|
||
|
||
## 项目概述
|
||
|
||
BLS Project Console是一个前后端分离的Node.js项目，用于从Redis队列读取日志记录并展示在控制台界面中，同时提供发送控制台指令到Redis队列的功能，以便其他程序读取和执行。
|
||
|
||
### 主要功能
|
||
|
||
- **日志记录展示**：从Redis队列实时读取日志记录，以友好的格式展示在控制台界面中
|
||
- **控制台指令发送**：允许用户发送控制台指令到Redis队列，供其他程序读取和执行
|
||
- **实时更新**：日志记录和指令状态实时更新，提供良好的用户体验
|
||
- **响应式设计**：适配不同屏幕尺寸，提供良好的移动端体验
|
||
|
||
## 技术栈
|
||
|
||
### 前端
|
||
|
||
- Vue 3.x：渐进式JavaScript框架
|
||
- Vue Router：前端路由管理
|
||
- Axios：HTTP客户端，用于与后端API通信
|
||
- CSS3：样式设计
|
||
|
||
### 后端
|
||
|
||
- Node.js：JavaScript运行时环境
|
||
- Express：Web应用框架
|
||
- Redis客户端：用于与Redis服务器通信
|
||
- CORS：跨域资源共享中间件
|
||
|
||
### 构建工具和开发工具
|
||
|
||
- Vite：现代化前端构建工具
|
||
- ESLint：JavaScript代码质量检查工具
|
||
- Prettier：代码格式化工具
|
||
- nodemon：Node.js开发服务器，支持热重载
|
||
|
||
## 快速开始
|
||
|
||
### 环境要求
|
||
|
||
- Node.js >= 16.x
|
||
- npm >= 8.x
|
||
- Redis >= 6.x
|
||
|
||
### 安装步骤
|
||
|
||
1. 克隆项目代码
|
||
|
||
```bash
|
||
git clone <repository-url>
|
||
cd Web_BLS_ProjectConsole
|
||
```
|
||
|
||
2. 安装依赖
|
||
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
3. 配置环境变量
|
||
|
||
创建 `.env` 文件，配置Redis连接参数：
|
||
|
||
```env
|
||
# Redis配置
|
||
REDIS_HOST=localhost
|
||
REDIS_PORT=6379
|
||
REDIS_PASSWORD=
|
||
REDIS_DB=15
|
||
```
|
||
|
||
### 运行项目
|
||
|
||
#### 开发模式
|
||
|
||
同时启动前端和后端开发服务器：
|
||
|
||
```bash
|
||
# 启动前端开发服务器（端口3000）
|
||
npm run dev
|
||
|
||
# 启动后端开发服务器（端口3001）
|
||
npm run start:dev
|
||
```
|
||
|
||
#### 生产模式
|
||
|
||
1. 构建前端项目
|
||
|
||
```bash
|
||
npm run build
|
||
```
|
||
|
||
2. 启动后端服务器
|
||
|
||
```bash
|
||
npm start
|
||
```
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
Web_BLS_ProjectConsole/
|
||
├── .github/ # GitHub配置文件
|
||
│ └── prompts/ # OpenSpec提示文件
|
||
├── openspec/ # OpenSpec规格文档
|
||
│ ├── project.md # 项目概述和规范
|
||
│ ├── AGENTS.md # AI代理指令
|
||
│ └── specs/ # 核心能力规格
|
||
│ ├── logging/ # 日志功能规格
|
||
│ ├── command/ # 指令功能规格
|
||
│ └── redis-connection/ # Redis连接规格
|
||
├── public/ # 静态资源文件
|
||
│ └── index.html # HTML入口文件
|
||
├── src/ # 源代码
|
||
│ ├── frontend/ # 前端代码
|
||
│ │ ├── assets/ # 静态资源
|
||
│ │ ├── components/ # Vue组件
|
||
│ │ ├── views/ # 页面视图
|
||
│ │ ├── router/ # 路由配置
|
||
│ │ ├── store/ # 状态管理
|
||
│ │ ├── App.vue # 根组件
|
||
│ │ └── main.js # 入口文件
|
||
│ └── backend/ # 后端代码
|
||
│ ├── routes/ # API路由
|
||
│ ├── services/ # 业务逻辑
|
||
│ ├── config/ # 配置文件
|
||
│ └── server.js # 服务器入口文件
|
||
├── .eslintrc.js # ESLint配置
|
||
├── .gitignore # Git忽略文件
|
||
├── .prettierrc # Prettier配置
|
||
├── vite.config.js # Vite配置
|
||
├── package.json # 项目配置和依赖管理
|
||
└── README.md # 项目说明文档
|
||
```
|
||
|
||
## 功能模块
|
||
|
||
### 日志记录展示
|
||
|
||
日志记录展示模块负责从 Redis LIST 读取日志记录，并以友好的格式展示在控制台界面中。
|
||
|
||
#### 主要功能
|
||
|
||
- 实时读取 Redis LIST 中的日志记录
|
||
- 以列表形式展示日志记录，包含时间戳、日志级别和消息内容
|
||
- 支持按日志级别和时间范围过滤日志
|
||
- 自动滚动到最新日志（可选）
|
||
- 支持查看历史日志
|
||
|
||
#### 技术实现
|
||
|
||
- 使用Redis List作为日志队列
|
||
- 使用轮询方式拉取最新日志
|
||
- 前端使用Vue组件化开发，实现日志列表和过滤功能
|
||
|
||
### 控制台指令发送
|
||
|
||
控制台指令发送模块允许用户发送控制台指令到目标项目的 HTTP API（由心跳中的 `apiBaseUrl` 提供基地址）。
|
||
|
||
#### 主要功能
|
||
|
||
- 提供指令输入框，允许用户输入控制台指令
|
||
- 支持指令验证，确保指令格式正确
|
||
- 支持发送指令到目标项目 API
|
||
- 显示指令发送状态和结果
|
||
- 维护指令历史记录，支持重新发送历史指令
|
||
|
||
#### 技术实现
|
||
|
||
- 后端根据项目心跳解析目标项目 `apiBaseUrl` 并转发调用
|
||
- 前端使用Vue组件化开发，实现指令表单和历史记录功能
|
||
- 后端实现指令验证和发送逻辑
|
||
|
||
## 开发指南
|
||
|
||
### 代码风格规范
|
||
|
||
- **JavaScript**：使用ES模块语法（import/export）
|
||
- **Vue**：使用Composition API
|
||
- **命名规范**：
|
||
- 文件名：小驼峰命名（如：logView.vue）
|
||
- 组件名：大驼峰命名（如：LogView）
|
||
- 变量名：小驼峰命名
|
||
- 常量名：大写蛇形命名（如：REDIS_QUEUE_NAME）
|
||
- **代码格式化**：使用Prettier自动格式化
|
||
- **代码质量**：使用ESLint进行静态代码检查
|
||
|
||
### 开发流程
|
||
|
||
1. 创建分支：从develop分支创建功能分支
|
||
|
||
```bash
|
||
git checkout develop
|
||
git checkout -b feature/feature-name
|
||
```
|
||
|
||
2. 开发功能：实现功能代码，确保代码质量
|
||
|
||
3. 提交代码：使用Conventional Commits规范提交代码
|
||
|
||
```bash
|
||
git add .
|
||
git commit -m "feat: add feature-name"
|
||
```
|
||
|
||
4. 推送代码：将功能分支推送到远程仓库
|
||
|
||
```bash
|
||
git push origin feature/feature-name
|
||
```
|
||
|
||
5. 创建PR：创建Pull Request，请求合并到develop分支
|
||
|
||
6. 代码审查：等待团队成员代码审查
|
||
|
||
7. 合并代码：代码审查通过后，合并到develop分支
|
||
|
||
### 测试指南
|
||
|
||
#### 测试
|
||
|
||
```bash
|
||
npm test
|
||
```
|
||
|
||
#### 开发时 watch
|
||
|
||
```bash
|
||
npm run test:watch
|
||
```
|
||
|
||
#### 代码质量检查
|
||
|
||
```bash
|
||
# ESLint检查
|
||
npm run lint
|
||
|
||
# Prettier格式化
|
||
npm run format
|
||
```
|
||
|
||
## 部署说明
|
||
|
||
### 生产环境部署
|
||
|
||
1. 配置生产环境变量
|
||
|
||
```env
|
||
# Redis配置
|
||
REDIS_HOST=redis-server
|
||
REDIS_PORT=6379
|
||
REDIS_PASSWORD=your-redis-password
|
||
REDIS_DB=15
|
||
|
||
# 服务器配置
|
||
PORT=3001
|
||
NODE_ENV=production
|
||
```
|
||
|
||
2. 构建前端项目
|
||
|
||
```bash
|
||
npm run build
|
||
```
|
||
|
||
3. 启动后端服务器
|
||
|
||
```bash
|
||
npm start
|
||
```
|
||
|
||
### Docker部署（可选）
|
||
|
||
创建Dockerfile：
|
||
|
||
```dockerfile
|
||
FROM node:16-alpine
|
||
|
||
WORKDIR /app
|
||
|
||
COPY package*.json ./
|
||
RUN npm install --production
|
||
|
||
COPY . .
|
||
RUN npm run build
|
||
|
||
EXPOSE 3001
|
||
|
||
CMD ["npm", "start"]
|
||
```
|
||
|
||
构建Docker镜像：
|
||
|
||
```bash
|
||
docker build -t bls-project-console .
|
||
```
|
||
|
||
运行Docker容器：
|
||
|
||
```bash
|
||
docker run -p 3001:3001 --env-file .env bls-project-console
|
||
```
|
||
|
||
## 配置说明
|
||
|
||
### Redis配置
|
||
|
||
| 配置项 | 环境变量 | 默认值 | 说明 |
|
||
| ------------ | ---------------------------- | ----------- | ----------------------------- |
|
||
| 主机名 | REDIS_HOST | localhost | Redis服务器主机名 |
|
||
| 端口 | REDIS_PORT | 6379 | Redis服务器端口 |
|
||
| 密码 | REDIS_PASSWORD | | Redis服务器密码 |
|
||
| 数据库索引 | REDIS_DB | 15 | Redis数据库索引 |
|
||
| 连接超时 | REDIS_CONNECT_TIMEOUT | 10000 | 连接超时时间（毫秒） |
|
||
| 最大重试次数 | REDIS_MAX_RETRIES | 3 | 最大重试次数 |
|
||
| 重连策略 | REDIS_RECONNECT_STRATEGY | exponential | 重连策略（exponential/fixed） |
|
||
| 重连间隔 | REDIS_RECONNECT_INTERVAL | 1000 | 重连间隔（毫秒） |
|
||
| 最大重连间隔 | REDIS_MAX_RECONNECT_INTERVAL | 30000 | 最大重连间隔（毫秒） |
|
||
|
||
### 服务器配置
|
||
|
||
| 配置项 | 环境变量 | 默认值 | 说明 |
|
||
| ------ | -------- | ----------- | ---------------------------------- |
|
||
| 端口 | PORT | 3001 | 服务器端口 |
|
||
| 环境 | NODE_ENV | development | 运行环境（development/production） |
|
||
|
||
## 贡献指南
|
||
|
||
1. Fork项目代码
|
||
2. 创建功能分支
|
||
3. 实现功能或修复bug
|
||
4. 提交代码，使用Conventional Commits规范
|
||
5. 创建Pull Request
|
||
6. 等待代码审查
|
||
7. 代码审查通过后，合并到主分支
|