Chuyaoyuan/home4j
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

init

Browse Source
This commit is contained in:
Chuyaoyuan
2026-04-29 14:59:24 +08:00
parent e2fdaa8fe8
commit 8e96524e0b
81 changed files with 9151 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/文档.md
+594
View File
@@ -0,0 +1,594 @@
# Home4j 产品设计文档（PDD）
> **文档版本**：v1.1
> **创建日期**：2026年1月30日
> **最后更新**：2026年2月3日
> **文档状态**：修订版
---
## 1. 概述与愿景
### 1.1 项目一句话介绍
**Home4j** 是一款基于 Java 技术栈的极简、高性能、可自托管的 Home 仪表盘和导航工具，专为独立开发者、内容创作者和小型团队打造。
### 1.2 核心价值主张
> 市面上鲜有基于 Java 的 Home 仪表盘解决方案。Home4j 填补这一空白，为 Java 生态用户提供**轻量级、高度可定制、开箱即用**的首页导航工具，让用户在熟悉的技术栈中获得一流的自托管体验。
### 1.3 与竞品的差异化定位
| 差异化维度 | Home4j 定位 |
|-----------|------------|
| **技术栈** | 基于 **Quarkus** 的轻量级 Java 方案，对 Java 开发者友好 |
| **配置方式** | **Web UI 为主**，数据库存储配置，支持导出备份 |
| **资源占用** | 目标内存 < 128MB，启动时间 < 3秒（JVM 模式） |
| **扩展性** | 预留 Widget 插件机制，支持企业级二次开发 |
| **部署体验** | 单 JAR 文件 / Docker 一键部署，零外部依赖 |
| **离线友好** | 所有资源本地化（图标、CSS），支持内网离线部署 |
### 1.4 从参考项目中学到的最关键启发
| 参考项目 | 核心启发 | 应用到 Home4j |
|---------|---------|--------------|
| **Flame** | 极简至上，专注核心功能；书签+应用分类清晰 | 采用相似的简洁 UI 哲学，MVP 聚焦书签管理 |
| **Homer** | YAML 配置驱动，声明式管理；图标系统完善 | 支持 YAML 配置文件，内置图标库 |
| **Glance** | Widget 化设计，信息聚合能力强 | 预留 Widget 扩展架构 |
| **Homepage** | 服务状态监控集成，实用性强 | v1.0 加入服务健康检查 |
| **Dashy** | 高度可定制，主题丰富 | 基于 DaisyUI 实现多主题切换 |
| **Heimdall** | 应用启动器思维，增强型书签概念 | 支持应用分组和快捷访问 |
---
## 2. 用户与市场分析
### 2.1 目标用户画像
#### Persona 1：独立开发者「小明」
| 属性 | 描述 |
|-----|------|
| **背景** | 全栈开发者，自建 NAS 和多个服务（GitLab、Jenkins、Portainer等） |
| **典型场景** | 需要统一入口管理 10+ 个自托管服务，希望一目了然 |
| **痛点** | 现有工具要么太重（Dashy），要么不熟悉技术栈（Node.js） |
| **期望** | 轻量、快速、能用 Java 二次开发、Docker 部署简单 |
#### Persona 2：小型团队技术负责人「阿杰」
| 属性 | 描述 |
|-----|------|
| **背景** | 5人创业团队 CTO，管理内部工具和文档入口 |
| **典型场景** | 为团队搭建内部 Portal，整合 Notion、飞书、内部系统 |
| **痛点** | 需要简单的权限控制，但不想引入复杂系统 |
| **期望** | 支持多用户、可配置访问权限、界面专业美观 |
#### Persona 3：内容创作者「小美」
| 属性 | 描述 |
|-----|------|
| **背景** | 技术博主，自建博客、图床、评论系统等 |
| **典型场景** | 希望有一个美观的个人主页展示所有项目入口 |
| **痛点** | 设计能力有限，希望开箱即用且美观 |
| **期望** | 多主题可选、支持自定义背景、移动端适配好 |
### 2.2 竞品分析
| 维度 | Flame | Homer | Dashy | Heimdall | **Home4j** |
|-----|-------|-------|-------|----------|------------|
| **技术栈** | Node.js | Vue/静态 | Vue | PHP/Laravel | **Java/Solon** |
| **配置方式** | Web UI | YAML | YAML + UI | Web UI | **YAML + Web UI** |
| **资源占用** | 低 | 极低 | 中等 | 中等 | **低** |
| **学习曲线** | 低 | 中 | 高 | 低 | **低** |
| **Widget 支持** | 有限 | 无 | 丰富 | 无 | **可扩展** |
| **服务状态监控** | ✅ | ❌ | ✅ | ❌ | **✅ (v1.0)** |
| **多用户** | ❌ | ❌ | ✅ | ❌ | **✅ (v1.0)** |
| **中文支持** | 一般 | 一般 | 良好 | 一般 | **原生支持** |
### 2.3 用户核心痛点与机会点
| 痛点 | 机会点 |
|-----|-------|
| Java 生态缺乏优质 Dashboard 工具 | 填补市场空白，吸引 Java 开发者群体 |
| 现有工具配置复杂或资源占用高 | 主打"极简 + 轻量"差异化 |
| 纯 YAML 配置对非技术用户不友好 | 提供 Web UI 可视化配置 |
| 大多数工具不支持中文优先 | 原生中文支持，国际化架构 |
| 企业内部使用缺乏基础权限控制 | 提供简单实用的多用户机制 |
---
## 3. 核心功能设计（MVP）
### 3.1 MVP 范围界定说明
MVP 目标：**让用户在 5 分钟内完成部署，10 分钟内配置出可用的个人导航页**。
**MVP 边界原则**：
- ✅ 必须有：书签管理、分组分类、主题切换、Docker 部署、管理员登录
- ⏳ 延后：Widget 系统、服务监控、多用户权限
- ❌ 不做：复杂的仪表盘编辑器、第三方集成、竞品数据导入
**MVP 权限模式**：
- **只读访问**：普通访客可浏览所有书签
- **管理员编辑**：需登录后才能添加/编辑/删除书签和配置
### 3.2 核心功能列表
| 功能名称 | 用户价值 | 优先级 | 参考来源 |
|---------|---------|--------|---------|
| **书签管理** | 快速访问常用服务和网站 | P0 | Flame, Homer |
| **分组分类** | 按场景/类型组织书签，提升查找效率 | P0 | Flame, Heimdall |
| **搜索功能** | 快速定位目标书签 | P0 | Dashy |
| **主题切换** | 满足个性化需求，适应不同场景 | P0 | Dashy |
| **管理员登录** | 保护编辑权限，防止误操作 | P0 | 通用需求 |
| **Web UI 配置** | 可视化管理所有设置 | P0 | Flame |
| **响应式布局** | 多设备访问体验一致 | P0 | 通用需求 |
| **图标系统** | 提升视觉识别效率（本地化） | P0 | Homer, Dashy |
| **Docker 部署** | 一键启动，环境隔离 | P0 | 所有参考项目 |
### 3.3 核心功能详细描述
#### 3.3.1 书签管理
**用户故事**：
> 作为一名独立开发者，我希望能够添加、编辑、删除我的服务书签，以便快速访问我的各种自托管服务。
**关键交互流程**：
```
[首页] → [点击添加按钮] → [填写书签信息表单]
→ [选择分组和图标] → [保存] → [首页显示新书签]
```
**书签数据结构**：
```yaml
bookmarks:
- name: "GitLab"
url: "https://gitlab.example.com"
icon: "gitlab" # 支持：内置图标名 / URL / base64
group: "开发工具"
description: "代码仓库"
tags: ["开发", "Git"]
```
**验收标准**：
- [ ] 支持添加书签（名称、URL、图标、分组、描述）
- [ ] 支持编辑和删除书签
- [ ] 书签点击在新标签页打开
- [ ] 支持拖拽排序
- [ ] 数据持久化到数据库
#### 3.3.2 分组分类
**用户故事**：
> 作为用户，我希望将书签按照用途分组（如：开发工具、监控系统、文档资料），以便快速找到目标。
**分组数据结构**：
```yaml
groups:
- name: "开发工具"
icon: "code"
order: 1
collapsed: false # 是否默认折叠
- name: "监控系统"
icon: "monitor"
order: 2
```
**验收标准**：
- [ ] 支持创建、编辑、删除分组
- [ ] 支持分组排序
- [ ] 支持分组折叠/展开
- [ ] 未分组书签显示在"默认"分组
#### 3.3.3 搜索功能
**用户故事**：
> 当我有大量书签时，我希望通过关键词快速搜索定位，而不是逐个查找。
**交互设计**：
- 快捷键 `/` 或 `Ctrl+K` 激活搜索框
- 支持搜索：书签名称、URL、描述、标签
- 实时过滤，高亮匹配内容
- 支持键盘导航（↑↓选择，Enter打开）
**验收标准**：
- [ ] 搜索响应时间 < 100ms
- [ ] 支持模糊匹配
- [ ] 搜索结果高亮显示
- [ ] 空结果友好提示
#### 3.3.4 主题切换
**用户故事**：
> 我希望根据个人喜好和使用场景切换界面主题，比如夜间使用深色模式。
**主题方案（基于 DaisyUI）**：
| 主题名称 | 适用场景 |
|---------|---------|
| light | 日间默认 |
| dark | 夜间模式 |
| cyberpunk | 科技风格 |
| nord | 护眼柔和 |
| dracula | 开发者偏好 |
**验收标准**：
- [ ] 支持至少 5 个预设主题
- [ ] 主题切换即时生效，无刷新
- [ ] 记住用户主题偏好
- [ ] 支持跟随系统深色模式
#### 3.3.5 数据存储策略
**设计理念**：
- **所有数据统一存储在数据库**：书签、分组、应用配置、用户偏好
- **Web UI 为主要配置入口**：用户通过界面管理所有设置
- **支持数据导出**：可导出为 JSON/YAML 格式用于备份和迁移
**数据分类**：
| 数据类型 | 存储位置 | 说明 |
|---------|---------|------|
| 书签数据 | 数据库 | 书签、分组的增删改查 |
| 应用配置 | 数据库 | 标题、副标题、主题、布局等全局设置 |
| 用户账号 | 数据库 | 管理员账号信息 |
| 用户偏好 | 数据库 + LocalStorage | 主题选择、语言偏好（支持游客记忆） |
**配置页面功能**：
- 常规设置：网站标题、副标题、Logo
- 外观设置：主题、布局、背景
- 数据管理：导入、导出、备份
- 账号管理：修改密码
---
#### 3.3.6 管理员登录
**用户故事**：
> 作为网站管理员，我希望通过登录验证后才能编辑内容，防止他人误操作或恶意修改。
**交互流程**：
```
[首页] → [点击设置/编辑按钮] → [跳转登录页]
→ [输入用户名密码] → [登录成功] → [进入管理模式]
```
**首次启动流程**：
```
[首次访问] → [初始化向导] → [设置管理员账号密码] → [完成] → [进入首页]
```
**验收标准**：
- [ ] 首次启动强制设置管理员账号
- [ ] 未登录用户只能浏览，不能编辑
- [ ] 登录状态支持 Session 保持
- [ ] 支持退出登录
- [ ] 支持修改密码
---
## 4. 功能路线图（MVP → v1.0 → 未来方向）
### 4.1 分阶段功能规划
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
MVP (v0.1) v0.5 v1.0 未来
2个月 2个月 2个月 持续
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[书签管理] [图标库增强] [简单状态监控] [插件市场]
[分组分类] [数据导入导出] [多用户支持] [移动端APP]
[搜索功能] [自定义CSS] [访问统计] [团队协作]
[主题切换] [背景自定义] [API开放] [AI推荐]
[管理员登录] [快捷键系统] [基础Widget] [公开分享]
[Web UI配置] [PWA支持] [数据备份恢复]
[Docker部署]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```
### 4.2 关键里程碑
| 版本 | 时间节点 | 关键目标 | 成功指标 |
|-----|---------|---------|---------|
| **MVP (v0.1)** | M+2 | 核心功能可用，Docker 可部署 | 完成冒烟测试，GitHub 发布首个 Release |
| **v0.5** | M+4 | 体验优化，功能完善 | 收集 50+ 用户反馈，GitHub Star > 100 |
| **v1.0** | M+6 | 生产可用，企业特性 | 稳定运行 30 天无重大 Bug，Star > 500 |
---
## 5. 用户体验与交互设计原则
### 5.1 整体设计语言与调性
| 维度 | 设计原则 |
|-----|---------|
| **视觉风格** | 简洁克制、呼吸感强、信息层次清晰 |
| **交互理念** | 减少点击、键盘友好、即时反馈 |
| **色彩运用** | 主色调由主题决定，强调色用于交互元素 |
| **动效策略** | 轻量过渡动画，提升流畅感但不干扰 |
| **信息密度** | 可配置，支持紧凑/标准/宽松三种模式 |
### 5.2 核心用户旅程
#### 首次使用旅程
```
┌─────────────────────────────────────────────────────────────┐
│ 1. 部署启动 │
│ docker run -p 8080:8080 home4j/home4j │
│ ↓ │
│ 2. 访问首页 │
│ 浏览器打开 http://localhost:8080 │
│ ↓ │
│ 3. 初始化向导（首次，可跳过部分步骤） │
│ [设置管理员账号] → [选择主题] → [添加第一个书签] → [完成] │
│ ↓ │
│ 4. 日常使用 │
│ 游客：查看书签 → 点击访问 / 搜索定位 │
│ 管理员：登录 → 管理编辑 → 退出登录 │
└─────────────────────────────────────────────────────────────┘
```
**说明**：初始化向导由前端驱动，除「设置管理员账号」为必填外，其他步骤可跳过。
### 5.3 关键页面交互逻辑
#### 首页（Dashboard）
```
┌────────────────────────────────────────────────────────────┐
│ 🏠 Home4j [搜索框 Ctrl+K] [设置⚙️] │
├────────────────────────────────────────────────────────────┤
│ │
│ 📁 开发工具 [+] │
│ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ │
│ │GitHub│ │GitLab│ │Jenkins│ │Notion│ │
│ └──────┘ └──────┘ └──────┘ └──────┘ │
│ │
│ 📁 监控系统 [+] │
│ ┌──────┐ ┌──────┐ ┌──────┐ │
│ │Grafana│ │Portainer│ │Uptime│ │
│ └──────┘ └──────┘ └──────┘ │
│ │
├────────────────────────────────────────────────────────────┤
│ Powered by Home4j [主题切换🌙] │
└────────────────────────────────────────────────────────────┘
```
#### 设置页面（Settings）
- **Tab 式导航**：常规 | 外观 | 数据 | 关于
- **实时预览**：修改即可看到效果
- **导入导出**：支持 JSON/YAML 格式
---
## 6. 技术架构与实现约束（产品视角）
### 6.1 推荐技术栈
| 层级 | 技术选型 | 选型理由 |
|-----|---------|---------|
| **后端框架** | Quarkus | 轻量级 Java 框架，启动快、内存占用低，生态完善 |
| **模板引擎** | Qute | Quarkus 原生模板引擎，类型安全，性能优秀 |
| **前端样式** | DaisyUI + Tailwind（本地） | 开箱即用的组件库，主题切换方便，**本地引用无 CDN 依赖** |
| **数据库** | H2（默认，文件模式）/ MySQL（可选） | H2 零配置，MySQL 满足企业需求 |
| **ORM** | Panache（Hibernate） | Quarkus 原生 ORM，简化数据库操作 |
| **容器化** | Docker | 标准化部署，环境一致性 |
### 6.2 部署方式
#### Docker 一键部署（推荐）
```bash
docker run -d \
--name home4j \
-p 8080:8080 \
-v /path/to/data:/app/data \
home4j/home4j:latest
```
#### Docker Compose
```yaml
version: '3'
services:
home4j:
image: home4j/home4j:latest
ports:
- "8080:8080"
volumes:
- ./data:/app/data
environment:
- TZ=Asia/Shanghai
restart: unless-stopped
```
#### JAR 直接运行
```bash
java -jar home4j-runner.jar
```
### 6.3 数据目录规划
```
/app/ # 应用根目录（Docker 内）
├── home4j-runner.jar # 应用主程序
├── resources/ # 资源目录
│ ├── static/ # 静态资源
│ │ ├── css/ # DaisyUI/Tailwind 本地文件
│ │ ├── js/ # JavaScript 文件
│ │ └── icons/ # 内置图标库
│ └── templates/ # Qute 模板文件
├── data/ # 数据目录（**需挂载**）
│ ├── home4j.mv.db # H2 数据库文件
│ ├── home4j.trace.db # H2 跟踪文件（可选）
│ └── uploads/ # 用户上传文件
│ └── icons/ # 用户上传的自定义图标
└── logs/ # 日志目录（可选挂载）
└── home4j.log
```
**挂载说明**：
- `/app/data` **必须挂载**：包含数据库和用户上传文件，确保数据持久化
- `/app/logs` 可选挂载：便于查看日志
### 6.4 图标系统实现
| 图标类型 | 存储位置 | 说明 |
|---------|---------|------|
| **内置图标** | `/resources/static/icons/` | 打包在 JAR 中，500+ 常用图标 |
| **URL 图标** | 外部 URL | 用户填写的图片 URL |
| **上传图标** | `/data/uploads/icons/` | 用户上传的自定义图标 |
| **默认图标** | `/resources/static/icons/default.svg` | URL 不可访问时的降级显示 |
**URL 图标处理逻辑**：
1. 前端尝试加载用户填写的 URL 图标
2. 如果加载失败（超时/404/跨域），自动降级显示默认图标
3. 默认图标为一个灰色的「问号」或「链接断裂」样式
### 6.5 扩展性与插件机制
**Widget 插件架构（v1.0+）**：
```
┌─────────────────────────────────────────┐
│ Home4j Core │
├─────────────────────────────────────────┤
│ Widget API (SPI) │
├──────────┬──────────┬──────────┬────────┤
│ 时钟组件 │ 搜索组件 │ 待办组件 │ 自定义 │
└──────────┴──────────┴──────────┴────────┘
```
- 基于 Quarkus 扩展机制或 Java SPI 加载插件
- 插件独立 JAR 包，放入 `/plugins` 目录自动加载
- v1.0 提供简单的内置 Widget，复杂插件延后到 v1.x
### 6.6 性能与安全底线要求
| 指标 | 目标值 |
|-----|-------|
| 冷启动时间 | < 3 秒（JVM 模式） |
| 内存占用 | < 128 MB（默认配置） |
| 首页加载时间 | < 500 ms |
| 并发支持 | > 100 QPS（单实例） |
| Docker 镜像大小 | < 200 MB |
---
## 7. 非功能性需求
### 7.1 性能目标
| 场景 | 指标 | 目标 |
|-----|-----|------|
| 首页渲染 | TTFB | < 100ms |
| 书签搜索 | 响应时间 | < 50ms（1000条书签内） |
| 配置保存 | 响应时间 | < 200ms |
| 主题切换 | 生效时间 | < 100ms，无闪烁 |
### 7.2 安全性与隐私保护
| 安全措施 | 说明 |
|---------|------|
| **数据本地化** | 所有数据存储在用户自己的服务器，不上传云端 |
| **HTTPS 支持** | 支持反向代理 SSL 终结 |
| **XSS 防护** | 输入输出转义，CSP 策略 |
| **CSRF 防护** | Token 验证机制 |
| **认证机制（v1.0）** | 支持基础认证，可选 OAuth2 |
### 7.3 可观测性
| 维度 | 实现方案 |
|-----|---------|
| **日志** | SLF4J + Logback，支持日志级别动态调整 |
| **健康检查** | `/actuator/health` 端点 |
| **指标暴露** | Prometheus 格式 `/metrics`（可选） |
### 7.4 国际化与可访问性
- **语言支持**：中文（默认）、英文
- **i18n 机制**：基于 `messages.properties` 资源文件
- **可访问性**：
- 语义化 HTML 结构
- 键盘完整可操作
- 支持屏幕阅读器
- 颜色对比度符合 WCAG 2.1 AA
---
## 8. 风险、挑战与应对
| 风险 | 等级 | 描述 | 缓解措施 |
|-----|------|------|---------|
| **市场认知度低** | 高 | Java Dashboard 类工具用户认知少 | 1. 发布技术博客分享<br>2. 提交到 awesome-selfhosted 列表<br>3. 录制视频教程 |
| **与成熟竞品竞争** | 高 | Flame/Homer 已有稳定用户群 | 1. 差异化定位 Java 用户<br>2. 功能上做精不做多<br>3. 强调离线部署优势 |
| **Quarkus 学习曲线** | 中 | 团队对 Quarkus 熟悉度 | 1. 使用 JVM 模式降低复杂度<br>2. 参考官方示例<br>3. 保持核心依赖简单 |
| **单人维护精力有限** | 中 | 开源项目持续维护挑战 | 1. MVP 功能精简<br>2. 代码质量优先<br>3. 积极培养社区贡献者 |
| **用户需求分散** | 中 | 不同用户对功能期望差异大 | 1. 坚持「导航工具」核心定位<br>2. 通过插件满足扩展需求<br>3. 建立 RFC 机制收集反馈 |
---
## 9. 附录
### 9.1 名词表 / 术语定义
| 术语 | 定义 |
|-----|------|
| **书签（Bookmark）** | 用户添加的链接条目，包含名称、URL、图标等属性 |
| **分组（Group）** | 书签的逻辑分类容器 |
| **Widget** | 可嵌入仪表盘的小组件，如时钟、天气等 |
| **主题（Theme）** | 预定义的视觉风格配置，包含颜色、字体等 |
| **YAML 配置** | 使用 YAML 格式定义应用配置的文件 |
### 9.2 参考资料与灵感来源
| 项目 | 地址 | 主要参考点 |
|-----|------|-----------|
| Flame | https://github.com/pawelmalak/flame | 极简设计、书签管理 |
| Homer | https://github.com/bastienwirtz/homer | YAML 配置、图标系统 |
| Glance | https://github.com/glanceapp/glance | Widget 架构 |
| Homepage | https://github.com/gethomepage/homepage | 服务状态集成 |
| Dashy | https://github.com/Lissy93/dashy | 主题系统、高级功能 |
| Heimdall | https://github.com/linuxserver/Heimdall | 应用启动器概念 |
### 9.3 其他补充说明
#### 项目目录结构（建议）
```
home4j/
├── src/
│ ├── main/
│ │ ├── java/com/home4j/
│ │ │ ├── resource/ # REST 资源（Controller）
│ │ │ ├── service/ # 业务逻辑
│ │ │ ├── repository/ # 数据访问（Panache）
│ │ │ ├── entity/ # 数据实体
│ │ │ ├── dto/ # 数据传输对象
│ │ │ ├── config/ # 配置类
│ │ │ └── plugin/ # 插件机制
│ │ ├── resources/
│ │ │ ├── templates/ # Qute 模板
│ │ │ ├── META-INF/
│ │ │ │ └── resources/ # 静态资源
│ │ │ │ ├── css/ # DaisyUI/Tailwind 本地文件
│ │ │ │ ├── js/ # JavaScript 文件
│ │ │ │ └── icons/ # 内置图标库
│ │ │ └── application.properties
├── docker/
│ └── Dockerfile
├── docs/ # 文档
└── README.md
```
#### 开源协议建议
推荐使用 **MIT License**，便于企业用户采用和二次开发。
---
> **文档结束**
> 本文档将随项目进展持续更新，欢迎提出反馈和建议。