1. 项目概述：一个现代、轻量的个人仪表盘
如果你和我一样，每天上班第一件事就是打开十几个浏览器标签页，在邮箱、项目管理工具、服务器监控、待办清单、常用文档之间来回切换，那么你一定能理解那种“数字工作台”杂乱无章带来的烦躁感。我们需要的不是一个又一个孤立的网页，而是一个能聚合所有关键信息、快速触达常用服务的“控制中心”。这就是homepage项目诞生的初衷。
homepage是一个用现代 Web 技术栈（React, TypeScript, Tailwind CSS）构建的、高度可定制的个人仪表盘应用。它不是一个臃肿的企业级门户，而是一个为个人或小团队设计的、运行在你自家服务器上的轻量级工具。你可以把它想象成你浏览器主页的终极进化形态：一个完全由你掌控，可以集成任何支持 API 或 Web 服务的“数字驾驶舱”。无论是查看服务器状态、快速跳转到 Git 仓库、监控智能家居设备，还是展示天气预报和待办事项，homepage都能通过一个个简洁的“小组件”（Widget）来实现。
这个项目在 GitHub 上由gethomepage组织维护，获得了极高的关注度，这背后反映的正是现代数字工作者对效率工具“主权”的强烈需求。我们不再满足于使用那些充满广告、追踪和功能限制的第三方主页服务，而是希望拥有一个私有的、功能强大的、且颜值在线的个人工作入口。接下来，我将带你深入拆解homepage，从设计理念到部署实践，分享如何将它打造成你专属的生产力中枢。
2. 核心设计理念与架构解析
2.1 为什么是“服务聚合”而非“信息聚合”？
很多仪表盘项目侧重于信息展示，比如 RSS 阅读器或新闻聚合。homepage的核心设计哲学略有不同，它更强调“服务聚合”和“快速行动”。它的主要界面元素是“服务”（Services）和“小组件”（Widgets）。
- 服务（Services）：通常表现为一个带有图标的卡片。点击后，它不是一个展示信息的页面，而是直接跳转到对应的 Web 应用，比如点击“Gitea”图标直接打开你的自建 Git 服务，点击“Jellyfin”直接进入媒体库。它的核心作用是“快捷入口”。
- 小组件（Widgets）：这才是信息展示的核心。一个小组件会主动调用某个服务的 API，将关键信息以美观的格式呈现在仪表盘上。例如，一个“服务器监控”小组件会显示 CPU、内存、磁盘使用率；一个“日历”小组件会展示接下来的日程。
这种“服务+组件”的二元结构非常巧妙。服务解决了“快速去哪”的问题，小组件解决了“快速看啥”的问题。两者结合，使得homepage既是一个启动器，又是一个监控面板。
2.2 技术栈选型：现代、高效与可维护
homepage选择了 React + TypeScript + Tailwind CSS 这套组合拳，这几乎是当前构建现代化、高性能前端应用的事实标准。
- React：提供了高效的组件化开发模型。
homepage中的每一个服务卡片、每一个小组件都是一个独立的 React 组件，这使得功能模块高度解耦，开发和自定义变得非常清晰。 - TypeScript：为这个高度可配置的项目带来了巨大的优势。所有的配置（服务列表、小组件参数）都是通过 YAML 文件定义的。TypeScript 确保了在编写这些配置文件时，能有良好的类型提示和错误检查，极大减少了因拼写错误或格式问题导致的配置失败。
- Tailwind CSS：一个实用优先的 CSS 框架。它让
homepage实现了极其精致和一致的 UI 风格，同时保证了极高的自定义自由度。开发者（或高级用户）可以通过简单的工具类（Utility Classes）调整组件的间距、颜色、大小，而无需编写一行自定义 CSS。
这套技术栈不仅保证了应用的性能与用户体验，更重要的是，它降低了社区贡献和用户自定义的门槛。清晰的组件结构和类型安全的配置，让添加一个新服务的集成变得有章可循。
2.3 配置驱动：一切皆 YAML
homepage的灵魂在于其“配置即代码”的理念。整个仪表盘的外观、布局、集成的服务，完全由一系列 YAML 配置文件定义。你不需要修改任何 React 源代码，就能打造出独一无二的仪表盘。
主要的配置文件包括：
services.yaml: 定义所有服务卡片，包括名称、图标、链接地址、分组等。widgets.yaml: 定义所有信息展示小组件，包括类型（如 CPU、内存、天气）、数据源 API、刷新频率等。settings.yaml: 定义全局设置，如页面标题、主题、布局列数等。docker-compose.yaml: 官方推荐的部署方式，通过 Docker Compose 一键启动。
注意：虽然配置是 YAML，但
homepage利用 TypeScript 的类型定义生成了 JSON Schema。这意味着在支持 YAML 语言服务器的编辑器（如 VSCode）中编写配置时，你可以获得自动补全、悬停提示和错误验证，体验堪比编写代码。
3. 从零开始部署与基础配置实战
3.1 部署方式选择：Docker 是最佳路径
homepage官方强烈推荐使用 Docker 部署，这是最简单、最干净、依赖问题最少的方式。它将所有运行时环境打包在一个容器中，你只需要关心配置文件和数据持久化。
首先，在你的服务器上创建一个项目目录，例如~/homepage，并进入该目录。
mkdir -p ~/homepage && cd ~/homepage接下来，创建两个必要的子目录，用于存放配置和缓存数据：
mkdir -p ./config ./cache./config: 用于挂载所有的 YAML 配置文件。这是最重要的目录。./cache: 用于挂载应用内部缓存（如图标缓存），可以提升加载速度。
3.2 编写 Docker Compose 配置文件
在~/homepage目录下，创建docker-compose.yml文件：
version: '3.8' services: homepage: image: ghcr.io/gethomepage/homepage:latest container_name: homepage restart: unless-stopped ports: - "3000:3000" # 将容器的3000端口映射到主机的3000端口 volumes: - ./config:/app/config # 挂载配置文件目录 - ./cache:/app/cache # 挂载缓存目录 environment: - PUID=1000 # 设置容器内运行的用户ID，通常与你的主机用户ID一致 - PGID=1000 # 设置容器内运行的组ID - TZ=Asia/Shanghai # 设置时区参数解析：
image: ghcr.io/gethomepage/homepage:latest: 使用 GitHub Container Registry 上的最新镜像。restart: unless-stopped: 确保容器在意外退出（非手动停止）时自动重启，提高可用性。ports: - "3000:3000": 应用默认在容器内监听 3000 端口，我们将其映射到宿主机的 3000 端口。你可以将前面的3000改为任何未被占用的主机端口，如8080:3000。volumes: 这是关键。将本地的config和cache目录挂载到容器内，这样你的配置得以持久化，且容器重建后不会丢失。environment: 设置环境变量。PUID/PGID用于匹配文件权限，避免容器内进程创建的文件属于 root 导致管理困难。使用id $USER命令可以查看你的 UID 和 GID。
3.3 创建最简配置并启动
在挂载的./config目录下，我们创建第一个配置文件settings.yaml：
--- title: "我的工作台" # 仪表盘的标题是的，最初只需要这一个配置。然后，在~/homepage目录下运行：
docker-compose up -d-d参数代表后台运行。此时，访问http://你的服务器IP:3000，你应该能看到一个带有“我的工作台”标题的空白仪表盘。恭喜，homepage已经成功运行！
3.4 基础配置详解：打造骨架
一个完整的homepage配置通常从settings.yaml开始。让我们丰富它：
--- title: "小明的工作台" logo: "/icon.png" # 可以放置一个logo图片到./config目录下 favicon: "/favicon.ico" # 同上 headerStyle: "clean" # 标题栏样式，可选 'clean', 'fancy' layout: columns: 4 # 桌面端显示的列数 visibleWidgets: 6 # 初始可见的小组件数量，其余可点击展开 theme: "dark" # 主题，可选 'light', 'dark', 'auto' language: "zh" # 界面语言，支持中文接下来是重头戏：添加服务。创建./config/services.yaml：
--- # 服务可以分组，组可以嵌套 - Developer: - Gitea: icon: "simple-icons:gitea" # 使用Simple Icons中的图标名 href: "https://git.myhome.com" description: "自建Git服务" widget: # 关联一个widget，显示仓库信息 type: "gitea" url: "https://git.myhome.com" username: "myuser" token: "your_gitea_token_here" # 在Gitea设置中生成 - GitHub: icon: "simple-icons:github" href: "https://github.com" description: "代码托管平台" - Homelab: - Jellyfin: icon: "simple-icons:jellyfin" href: "http://nas.myhome.com:8096" description: "媒体服务器" - Nextcloud: icon: "simple-icons:nextcloud" href: "https://cloud.myhome.com" description: "私有云盘" - Monitoring: - Server Stats: icon: "material-symbols:monitor-heart" # 使用Material Symbols图标 href: "#" # 可以不设置链接 widget: type: "resource-monitor" # 资源监控小组件 columns: 2 # 在服务卡片中占2列宽度实操心得：
- 图标系统：
homepage集成了多个图标库（Simple Icons, Material Symbols, FontAwesome等）。去对应的官网搜索你需要的服务图标名称，格式通常是库名:图标名。这是让仪表盘变得美观的关键。 - Widget 关联：在服务卡片下直接定义
widget，是这个项目非常人性化的设计。它让信息（Widget）和动作（Service）在视觉和逻辑上紧密结合。 - 安全性：注意配置中的
token、password等敏感信息。绝对不要将它们明文提交到版本库。一种推荐的做法是使用环境变量。你可以在docker-compose.yml中定义环境变量，然后在 YAML 配置中使用{ { .Env.VARIABLE_NAME } }的语法来引用（注意去掉大括号内的空格，这里为避免渲染做了处理）。更复杂的需求可以使用专门的 secrets 管理。
4. 核心功能实现：Widgets 深度集成指南
Widget 是homepage的“智慧”所在。它通过调用各种 API 将动态数据带到你的仪表盘上。
4.1 系统资源监控 Widget
这是最常用的 Widget 之一，用于监控运行homepage的宿主机（或指定服务器）的状态。 在./config/widgets.yaml中配置：
--- - server-stats: type: "resource-monitor" label: "家庭服务器" host: "192.168.1.100" # 可选，默认为宿主机 port: 22 # SSH端口 username: "monitor_user" useKey: true # 使用SSH密钥认证，比密码更安全 keyPath: "/config/id_rsa" # 容器内私钥路径，需要提前将私钥放入./config目录 interval: 60 # 数据刷新间隔，单位秒 columns: 2 # 在仪表盘上占据的列宽 show: # 选择要显示的指标 - cpu - memory - disk - uptime实现原理：这个 Widget 实际上是通过 SSH 连接到目标服务器，执行如top,free,df等命令来获取系统指标。因此，你需要确保：
- 目标服务器开启了 SSH 服务。
- 用于连接的密钥对已配置好。你需要将私钥（如
id_rsa）复制到本地的./config目录下，并在配置中指定正确的路径。 - 对应的公钥已添加到目标服务器的
~/.ssh/authorized_keys中。
踩坑提醒：SSH 密钥的权限必须正确。在宿主机上，确保
./config/id_rsa的权限是600(chmod 600 ./config/id_rsa)。否则容器内的进程可能无法读取，导致连接失败。
4.2 容器状态监控 (Docker / Kubernetes)
对于 Homelab 用户，监控所有容器的状态至关重要。homepage可以集成 Docker Socket 或调用 Docker API。
- docker-status: type: "docker" label: "容器状态" url: "unix:///var/run/docker.sock" # 通过Unix Socket连接（需挂载socket文件） # 或者使用HTTP API: url: "http://docker-host:2375" interval: 30 columns: 2 hide: # 可选，隐藏某些容器 - homepage # 隐藏自己，避免递归监控关键步骤：要让容器内的homepage访问到宿主机的 Docker Socket，需要修改docker-compose.yml，添加一个卷挂载：
services: homepage: # ... 其他配置 ... volumes: - ./config:/app/config - ./cache:/app/cache - /var/run/docker.sock:/var/run/docker.sock:ro # 挂载Docker Socket，只读这样，homepage就拥有了读取宿主机 Docker 状态的权限。请注意安全风险：这意味着如果homepage应用存在漏洞，攻击者可能通过它控制宿主机 Docker。在可信的网络环境（如家庭内网）中使用是常见的做法。
4.3 集成第三方服务：以天气和日历为例
许多第三方服务提供了开放的 API。
- 天气 Widget(使用 Open-Meteo API，免费且无需注册)：
- weather: type: "weather" label: "本地天气" latitude: 31.2304 # 上海纬度 longitude: 121.4737 # 上海经度 units: "metric" # 公制单位 interval: 900 # 15分钟刷新一次 - 日历 Widget(支持 iCal 格式，如 Google Calendar)：
- family-calendar: type: "calendar" label: "家庭日程" url: "https://calendar.google.com/calendar/ical/xxx/basic.ics" # 你的iCal地址 days: 7 # 显示未来7天的事件
实操心得：寻找服务的 API 或集成方式是配置 Widget 的核心。homepage官方文档维护了一个庞大的“服务集成”列表，涵盖了从 AdGuard Home、Bitwarden 到 Plex、Sonarr 等上百种常见服务。在配置前，先去文档里搜一下，往往能直接找到可用的配置模板和必要的 API Key 获取方法。
5. 高级定制与自动化技巧
5.1 主题与样式深度定制
虽然homepage提供了亮色/暗色主题，但你可以通过自定义 CSS 进行更精细的调整。在./config目录下创建custom.css文件，它会被自动加载。
/* 修改所有服务卡片的背景和悬停效果 */ .service-card { border-radius: 12px !important; background: linear-gradient(135deg, var(--color-primary) 0%, var(--color-secondary) 100%) !important; transition: transform 0.2s ease-in-out !important; } .service-card:hover { transform: translateY(-4px) !important; box-shadow: 0 10px 25px rgba(0,0,0,0.2) !important; } /* 修改标题字体 */ h1.header-title { font-family: 'Segoe UI', 'Microsoft YaHei', sans-serif !important; font-weight: 300 !important; }通过浏览器开发者工具检查元素，找到对应的 CSS 类名或变量（CSS Custom Properties，如--color-primary），你就可以实现高度个性化的界面。
5.2 利用环境变量管理敏感配置
明文密码和 Token 是安全隐患。最佳实践是使用环境变量。首先，在docker-compose.yml中定义环境变量，或者使用一个.env文件。
# docker-compose.yml services: homepage: # ... environment: - PUID=1000 - PGID=1000 - TZ=Asia/Shanghai - GITEA_TOKEN=${GITEA_TOKEN} # 从.env文件或shell环境读取 - EMBY_API_KEY=${EMBY_API_KEY}然后，在services.yaml或widgets.yaml中引用：
# 在YAML中，使用 { { .Env.VARIABLE_NAME } } 语法（去掉大括号内空格） widget: type: "gitea" url: "https://git.myhome.com" username: "myuser" token: "{ { .Env.GITEA_TOKEN } }"最后，创建一个.env文件（确保在.gitignore中忽略它）：
GITEA_TOKEN=glpat-xxxxxxxxxx EMBY_API_KEY=yyyyyyyyyy启动时，Docker Compose 会自动注入这些变量。
5.3 配置版本化管理与自动化部署
将./config目录纳入 Git 版本控制是一个好习惯，但务必排除敏感文件。创建.gitignore：
# 在 ~/homepage/.gitignore cache/ .env config/*.key config/id_rsa然后，你可以将配置推送到私有 Git 仓库。结合 CI/CD（如 GitHub Actions），可以在你更新配置后，自动拉取到服务器并重启homepage容器，实现仪表盘配置的自动化部署。
6. 常见问题排查与性能优化
6.1 常见问题速查表
| 问题现象 | 可能原因 | 排查步骤与解决方案 |
|---|---|---|
访问http://IP:3000无响应 | 1. 容器未启动 2. 端口被占用或防火墙阻止 | 1.docker-compose ps查看状态，docker-compose logs查看日志。2. netstat -tlnp | grep :3000检查端口，调整docker-compose.yml中的主机端口或配置防火墙。 |
| 页面空白或加载错误 | 1. 配置文件语法错误 2. 挂载卷权限问题 | 1. 检查 YAML 语法，特别是缩进和冒号后的空格。利用编辑器的 JSON Schema 验证功能。 2. 检查 ./config目录的权限，确保容器用户（PUID/PGID）有读取权限。 |
| Widget 显示“无法连接”或“错误” | 1. API 地址/Token 错误 2. 网络不通 3. 目标服务未运行 | 1. 仔细核对配置中的 URL、端口、用户名、Token。 2. 从 homepage容器内部 (docker exec -it homepage sh) 尝试ping或curl目标地址。3. 确认目标服务（如 Gitea、Jellyfin）本身运行正常。 |
| Docker Socket 挂载后仍无法显示容器 | 1. Socket 文件权限问题 2. 配置 URL 错误 | 1. 确保宿主机/var/run/docker.sock存在且容器内路径映射正确 (:ro表示只读)。2. 配置中 url应为unix:///var/run/docker.sock。 |
| 图标不显示 | 1. 图标名称错误 2. 网络问题导致图标库加载失败 | 1. 去 Simple Icons 或 Material Symbols 官网确认图标名称。 2. 检查浏览器控制台网络请求，看是否被广告拦截器阻止。 |
6.2 性能优化建议
- 调整刷新间隔：每个 Widget 的
interval参数决定了其数据刷新频率（秒）。对于不常变化的信息（如天气、服务器基本信息），可以设置为 300（5分钟）甚至 1800（30分钟）。对于监控类 Widget（如资源监控），30-60秒是合理的。过短的间隔会增加服务器和 API 源的负载。 - 善用缓存目录：确保
./cache目录被正确挂载。homepage会将图标等静态资源缓存于此，避免每次加载都从网络获取，显著提升页面打开速度。 - 精简 Widget 数量：仪表盘不是信息黑洞。只添加你真正需要高频查看的信息。过多的 Widget 不仅影响页面加载和渲染性能，也会造成视觉干扰，违背了提升效率的初衷。定期审视和清理不必要的组件。
- 使用反向代理：在生产环境，不建议直接暴露
3000端口。应该使用 Nginx 或 Caddy 作为反向代理，配置域名、SSL 证书（HTTPS）和访问认证，这样既安全又便于管理。
通过以上步骤，你不仅能搭建起一个功能强大的个人仪表盘，更能理解其运作机制，并能够根据自身需求进行无限扩展和定制。homepage的魅力就在于，它从一个简洁的工具开始，最终能成长为你数字生活中不可或缺的指挥中心。
