lonelyman0108/home-nexus repository overview

⁠HomeNexus

⁠✨ 特性

• 🖥️ 多服务器管理 - 统一管理家庭网络中的所有服务器
• 🔗 服务导航 - 快速访问各类服务的内外网地址
• 💚 健康监控 - 自动定时检查服务状态，实时监控可用性
• 🏷️ 标签分类 - 灵活的标签系统，轻松组织和查找服务
• 🔍 全局搜索 - 快速搜索服务器和服务
• 📊 可视化看板 - 直观的统计图表和趋势分析
• 🎨 现代UI - 简洁优雅的用户界面
• 🔐 权限控制 - 基于角色的访问控制
• 🗄️ 多数据库支持 - 支持H2、MySQL、PostgreSQL、SQLite

⁠📸 截图

⁠🚀 快速开始

⁠环境要求

后端:

• JDK 21+
• Maven 3.6+

前端:

• Node.js 20.19.0+ 或 22.12.0+
• npm 或 pnpm

⁠安装步骤

⁠1. 克隆项目

git clone https://github.com/lonelyman0108/HomeNexus.git
cd HomeNexus

⁠2. 启动后端

cd api
mvn spring-boot:run

后端服务将运行在 http://localhost:8080

⁠3. 启动前端

cd web
npm install
npm run dev

前端服务将运行在 http://localhost:5173

⁠4. 访问应用

打开浏览器访问 http://localhost:5173

默认管理员账户:

• 用户名: admin
• 密码: admin123

⁠📁 项目结构

HomeNexus/
├── api/                  # 后端项目 (Spring Boot)
│   ├── src/
│   │   ├── main/
│   │   │   ├── java/     # Java源代码
│   │   │   └── resources/
│   │   │       ├── application.yml
│   │   │       └── db/migration/  # 数据库迁移脚本
│   │   └── test/
│   ├── pom.xml
│   └── README.md
├── web/                  # 前端项目 (Vue 3)
│   ├── src/
│   │   ├── components/   # Vue组件
│   │   ├── views/        # 页面视图
│   │   ├── router/       # 路由配置
│   │   ├── stores/       # Pinia状态管理
│   │   └── utils/        # 工具函数
│   ├── package.json
│   └── vite.config.ts
├── docs/                 # 项目文档
│   ├── API.md            # API接口文档
│   └── DESIGN_SPEC.md    # 设计规范
├── Dockerfile            # Docker配置
├── PLAN.md              # 项目计划
└── README.md            # 项目说明

⁠🛠️ 技术栈

⁠后端

• 框架: Spring Boot 3.5.8
• 语言: Java 21
• ORM: MyBatis Plus 3.5.15
• 认证: Sa-Token 1.39.0
• 数据库迁移: Flyway
• 数据库: H2 (默认) / MySQL / PostgreSQL / SQLite
• 工具: Lombok, Apache HttpClient 5

⁠前端

• 框架: Vue 3.5.25
• 构建工具: Vite 7.2.4
• 路由: Vue Router 4.6.3
• 状态管理: Pinia 3.0.4
• UI组件: shadcn-vue, Radix Vue
• HTTP客户端: Axios 1.13.2
• 样式: TailwindCSS 3.4
• 图表: Vue Flow (用于服务器/服务关系可视化)
• 图标: lucide-vue-next

⁠📖 核心功能

⁠1. 服务器管理

• 添加、编辑、删除服务器
• 配置内网/外网地址
• 物理位置标注
• 启用/禁用状态管理

⁠2. 服务管理

• 服务CRUD操作
• 支持HTTP、HTTPS、TCP、UDP协议
• 内外网地址分离配置
• 自定义图标和描述
• 多标签分类

⁠3. 健康检查

• 自动定时健康检查 (默认5分钟)
• 实时状态监控 (ONLINE/OFFLINE/UNKNOWN)
• 响应时间记录
• 7天历史趋势分析
• 手动触发检查

⁠4. 搜索与过滤

• 全局搜索服务器和服务
• 按标签筛选
• 按状态筛选
• 按服务器分组查看

⁠5. 权限管理

• 用户角色: USER / ADMIN
• 可配置的查询接口公开访问
• 管理员专属的修改权限

⁠⚙️ 配置

⁠后端配置

编辑 api/src/main/resources/application.yml:

# 数据库配置
spring:
  datasource:
    url: jdbc:h2:./data/homenexus
    driver-class-name: org.h2.Driver

# 健康检查配置
app:
  health-check:
    enabled: true
    interval: 300000  # 5分钟
    timeout: 5000     # 5秒

# 安全配置
app:
  security:
    require-login-for-query: false  # 是否要求登录才能查询

⁠前端配置

编辑 web/.env.development:

VITE_API_BASE_URL=http://localhost:8080

⁠🐳 Docker部署

HomeNexus支持完全通过Docker部署，并且可以灵活配置数据源。

⁠快速开始

使用H2数据库（默认）:

docker-compose up -d

使用其他数据库:

# 1. 复制环境变量模板
cp .env.example .env

# 2. 编辑.env文件，选择数据库配置
nano .env

# 3. 启动服务
docker-compose up -d

⁠环境变量配置

所有支持的环境变量（详见 .env.example）：

⁠数据库配置

数据库示例配置：

• H2 (默认):

  SPRING_DATASOURCE_URL=jdbc:h2:./data/homenexus
  SPRING_DATASOURCE_DRIVER_CLASS_NAME=org.h2.Driver
  SPRING_DATASOURCE_USERNAME=sa
  SPRING_DATASOURCE_PASSWORD=
  

  Copy

• MySQL:

  SPRING_DATASOURCE_URL=jdbc:mysql://mysql:3306/homenexus?useUnicode=true&characterEncoding=utf-8&serverTimezone=Asia/Shanghai
  SPRING_DATASOURCE_DRIVER_CLASS_NAME=com.mysql.cj.jdbc.Driver
  SPRING_DATASOURCE_USERNAME=homenexus
  SPRING_DATASOURCE_PASSWORD=homenexus_password
  

  Copy

• PostgreSQL:

  SPRING_DATASOURCE_URL=jdbc:postgresql://postgres:5432/homenexus
  SPRING_DATASOURCE_DRIVER_CLASS_NAME=org.postgresql.Driver
  SPRING_DATASOURCE_USERNAME=homenexus
  SPRING_DATASOURCE_PASSWORD=homenexus_password
  

  Copy

• SQLite:

  SPRING_DATASOURCE_URL=jdbc:sqlite:./data/homenexus.db
  SPRING_DATASOURCE_DRIVER_CLASS_NAME=org.sqlite.JDBC
  SPRING_DATASOURCE_USERNAME=
  SPRING_DATASOURCE_PASSWORD=
  

  Copy

⁠应用配置

⁠健康检查配置

⁠安全配置

⁠常用命令

# 查看运行状态
docker-compose ps

# 查看日志
docker-compose logs -f homenexus

# 重启服务
docker-compose restart

# 停止服务
docker-compose stop

# 停止并删除容器
docker-compose down

# 停止并删除容器及数据卷（⚠️ 会删除数据）
docker-compose down -v

⁠📚 文档

• API接口文档⁠ - 完整的REST API文档
• 设计规范⁠ - UI/UX设计规范
• 后端README⁠ - 后端项目说明

⁠🔧 开发指南

⁠后端开发

cd api

# 运行开发环境
mvn spring-boot:run

# 运行测试
mvn test

# 构建生产包
mvn clean package

详见 api/README.md⁠

⁠前端开发

cd web

# 安装依赖
npm install

# 开发服务器
npm run dev

# 类型检查
npm run type-check

# 代码格式化
npm run format

# 构建生产版本
npm run build

⁠🤝 贡献

欢迎贡献代码！请遵循以下步骤：

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交改动 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

⁠📝 更新日志

⁠v0.0.1 (当前版本)

• ✅ 基础项目框架搭建
• ✅ 服务器和服务管理
• ✅ 健康检查功能
• ✅ 用户认证与授权
• ✅ 标签系统
• ✅ 搜索功能
• ✅ 前端基础界面

⁠🗺️ 路线图

• 服务依赖关系可视化
• Docker容器状态监控集成
• 通知和告警系统
• 数据导出/导入
• 移动端适配优化
• 暗色模式
• 多语言支持
• 服务分组和文件夹功能

⁠❓ 常见问题

⁠如何切换数据库？

编辑 api/src/main/resources/application.yml，修改数据源配置即可。项目支持H2、MySQL、PostgreSQL、SQLite。

⁠健康检查支持哪些协议？

目前支持HTTP、HTTPS和TCP协议的健康检查，UDP协议检查计划在未来版本支持。

⁠如何修改健康检查间隔？

在 application.yml 中修改 app.health-check.interval 配置项（单位：毫秒）。

⁠可以配置公开访问吗？

可以。设置 app.security.require-login-for-query: false 允许未登录用户查看服务列表，但修改操作仍需要管理员权限。

⁠📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE⁠ 文件了解详情

⁠🙏 致谢

• Spring Boot⁠
• Vue.js⁠
• MyBatis Plus⁠
• Sa-Token⁠
• shadcn-vue⁠
• TailwindCSS⁠