Chuyaoyuan/home4j

Fork 0

Files

T

Chuyaoyuan 8e96524e0b init

2026-04-29 14:59:24 +08:00

25 KiB

Raw Permalink Blame History

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 书签管理

用户故事：

作为一名独立开发者，我希望能够添加、编辑、删除我的服务书签，以便快速访问我的各种自托管服务。

关键交互流程：

[首页] → [点击添加按钮] → [填写书签信息表单] 
      → [选择分组和图标] → [保存] → [首页显示新书签]

书签数据结构：

bookmarks:
  - name: "GitLab"
    url: "https://gitlab.example.com"
    icon: "gitlab"  # 支持：内置图标名 / URL / base64
    group: "开发工具"
    description: "代码仓库"
    tags: ["开发", "Git"]

验收标准：

支持添加书签（名称、URL、图标、分组、描述）
支持编辑和删除书签
书签点击在新标签页打开
支持拖拽排序
数据持久化到数据库

3.3.2 分组分类

用户故事：

作为用户，我希望将书签按照用途分组（如：开发工具、监控系统、文档资料），以便快速找到目标。

分组数据结构：

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 一键部署（推荐）

docker run -d \
  --name home4j \
  -p 8080:8080 \
  -v /path/to/data:/app/data \
  home4j/home4j:latest

Docker Compose

version: '3'
services:
  home4j:
    image: home4j/home4j:latest
    ports:
      - "8080:8080"
    volumes:
      - ./data:/app/data
    environment:
      - TZ=Asia/Shanghai
    restart: unless-stopped

JAR 直接运行

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 图标处理逻辑：

前端尝试加载用户填写的 URL 图标
如果加载失败（超时/404/跨域），自动降级显示默认图标
默认图标为一个灰色的「问号」或「链接断裂」样式

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. 发布技术博客分享 2. 提交到 awesome-selfhosted 列表 3. 录制视频教程
与成熟竞品竞争	高	Flame/Homer 已有稳定用户群	1. 差异化定位 Java 用户 2. 功能上做精不做多 3. 强调离线部署优势
Quarkus 学习曲线	中	团队对 Quarkus 熟悉度	1. 使用 JVM 模式降低复杂度 2. 参考官方示例 3. 保持核心依赖简单
单人维护精力有限	中	开源项目持续维护挑战	1. MVP 功能精简 2. 代码质量优先 3. 积极培养社区贡献者
用户需求分散	中	不同用户对功能期望差异大	1. 坚持「导航工具」核心定位 2. 通过插件满足扩展需求 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，便于企业用户采用和二次开发。

文档结束
本文档将随项目进展持续更新，欢迎提出反馈和建议。

25 KiB Raw Permalink Blame History Unescape Escape

Home4j 产品设计文档（PDD）

1. 概述与愿景

1.1 项目一句话介绍

1.2 核心价值主张

1.3 与竞品的差异化定位

1.4 从参考项目中学到的最关键启发

2. 用户与市场分析

2.1 目标用户画像

Persona 1：独立开发者「小明」

Persona 2：小型团队技术负责人「阿杰」

Persona 3：内容创作者「小美」

2.2 竞品分析

2.3 用户核心痛点与机会点

3. 核心功能设计（MVP）

3.1 MVP 范围界定说明

3.2 核心功能列表

3.3 核心功能详细描述

3.3.1 书签管理

3.3.2 分组分类

3.3.3 搜索功能

3.3.4 主题切换

3.3.5 数据存储策略

3.3.6 管理员登录

4. 功能路线图（MVP → v1.0 → 未来方向）

4.1 分阶段功能规划

4.2 关键里程碑

5. 用户体验与交互设计原则

5.1 整体设计语言与调性

5.2 核心用户旅程

首次使用旅程

5.3 关键页面交互逻辑

首页（Dashboard）

设置页面（Settings）

6. 技术架构与实现约束（产品视角）

6.1 推荐技术栈

6.2 部署方式

Docker 一键部署（推荐）

Docker Compose

JAR 直接运行

6.3 数据目录规划

6.4 图标系统实现

6.5 扩展性与插件机制

6.6 性能与安全底线要求

7. 非功能性需求

7.1 性能目标

7.2 安全性与隐私保护

7.3 可观测性

7.4 国际化与可访问性

8. 风险、挑战与应对

9. 附录

9.1 名词表 / 术语定义

9.2 参考资料与灵感来源

9.3 其他补充说明

项目目录结构（建议）

开源协议建议

25 KiB

Raw Permalink Blame History