1. 项目概述一个为技术人量身定制的信息仪表盘如果你和我一样每天上班第一件事就是打开十几个浏览器标签页查看服务器监控、检查待处理的工单、瞄一眼项目进度、再快速扫过几个关键系统的状态。这种重复、碎片化的信息获取方式不仅效率低下还容易遗漏重要信息。我一直在寻找一个能聚合所有关键信息的“总控台”一个真正属于技术人的浏览器主页。直到我遇到了Homepage。这不仅仅是一个仪表盘项目它更像是一个高度可定制、自托管的“数字工作空间”。它允许你将所有常用的内部工具链接、服务状态、文档、甚至智能家居设备的状态全部整合在一个简洁、美观的页面里。想象一下每天只需打开一个网址你关心的所有信息一目了然那种掌控感和效率的提升是实实在在的。这个项目由gethomepage组织维护其核心价值在于“聚合”与“个性化”。它不生产内容而是内容的优秀“搬运工”和“展示者”。对于运维工程师、开发人员、项目经理甚至是任何需要管理多个在线服务的团队来说Homepage 都能显著优化日常工作流。接下来我将带你从零开始深度拆解如何部署、配置并玩转这个强大的个人仪表盘分享我在实际使用中积累的配置技巧和避坑经验。2. 核心架构与设计哲学解析2.1 为什么是 Homepage同类方案的横向对比在自托管仪表盘领域有几个知名的选择比如 Heimdall、Organizr 和 Dashy。那么 Homepage 的独特优势在哪里我选择它主要基于以下几点考量首先是极致的现代化与美观度。Homepage 的 UI 设计非常现代、清爽支持亮色/暗色主题并且响应式布局做得很好在手机和桌面端都有不错的体验。相比之下一些老牌工具虽然功能强大但界面略显陈旧。其次是“服务发现”与“零配置”的潜力。这是 Homepage 的一个杀手级特性。它内置了对多种主流自托管服务如 Plex, Sonarr, Radarr, AdGuard Home, Nextcloud 等的自动发现能力。当你将 Homepage 部署在与这些服务相同的网络环境中时它可以通过预定义的规则自动探测到这些服务的地址、端口并获取其运行状态健康检查然后自动生成对应的服务卡片。这意味着对于支持的服务你几乎不需要手动输入 IP 和端口大大简化了初始化配置。再者是灵活的组件化设计。Homepage 的页面由“小组件”构成主要分为Services服务卡片和Widgets信息小部件。Services用于展示一个具体应用或服务的链接与状态Widgets则可以嵌入动态信息如天气、系统资源监控CPU、内存、待办事项列表、RSS 订阅等。这种结构清晰配置直观。最后是活跃的社区与丰富的集成。项目在 GitHub 上非常活跃社区贡献了大量第三方服务的图标和集成配置。无论你使用多么小众的自托管应用几乎都能在社区找到对应的配置模板生态非常丰富。注意“零配置”并非完全不用配置。它指的是对于它已知的服务可以自动填充基础连接信息。但你仍然需要通过配置文件来组织这些服务的分类、定义自定义服务、以及调整布局和样式。2.2 技术栈与运行模式剖析Homepage 本质上是一个静态前端应用但它需要一个小型的后端服务来提供动态数据。其技术栈非常轻量前端基于 React 构建提供了流畅的单页应用体验。后端/服务端使用 Node.js主要提供两个核心功能API 代理为了避免前端浏览器直接访问你的内部服务可能遇到的 CORS跨域资源共享问题Homepage 的后端充当了一个代理。前端通过 Homepage 后端去请求你配置的各个服务的状态信息后端再将结果返回给前端。配置服务提供配置文件的热加载和管理。这种前后端分离的架构使得部署非常灵活。官方推荐使用 Docker 进行部署这也是最省心、跨平台兼容性最好的方式。Docker 镜像将前端构建产物、Node.js 后端以及运行环境全部打包你只需要映射出配置文件目录和指定端口即可运行。3. 从零开始的部署与初始化配置3.1 基于 Docker 的一键部署实践我将以最常见的 Docker Docker Compose 方式为例演示部署过程。假设你已经在服务器上安装好了 Docker 和 Docker Compose。首先创建一个项目目录并在此目录下创建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 # 挂载配置文件目录 - /var/run/docker.sock:/var/run/docker.sock:ro # 可选用于Docker集成 environment: - PUID1000 # 设置运行用户的UID与你主机用户一致以避免权限问题 - PGID1000 # 设置运行用户的GID关键参数解析ports: “3000:3000”: 左侧的3000是你服务器上访问 Homepage 的端口可以按需修改如8080:3000。volumes: ./config:/app/config: 这是最重要的部分。它将当前目录下的config文件夹映射到容器内的/app/config你的所有配置文件都将存放在主机的./config目录下。volumes: /var/run/docker.sock:/var/run/docker.sock:ro:这是一个可选但非常强大的挂载。它允许 Homepage 容器访问宿主机的 Docker 守护进程。这样Homepage 就可以自动发现宿主机上运行的其他 Docker 容器并尝试将其作为服务添加实现“服务发现”功能。ro表示只读保证了安全性。PUID/PGID: 建议设置为你的主机非root用户的UID和GID可以通过id -u和id -g命令查看。这能保证生成的文件具有正确的所有者权限。保存文件后在终端中执行docker-compose up -dHomepage 服务就会在后台启动。此时访问http://你的服务器IP:3000你应该能看到一个空白的 Homepage 界面提示你进行配置。3.2 核心配置文件结构与解析Homepage 的配置全部基于 YAML 文件位于你挂载的./config目录下。初始时这个目录是空的你需要手动创建以下核心文件settings.yaml: 全局设置如页面标题、主题、语言等。services.yaml: 定义所有要展示的服务卡片。widgets.yaml: 可选定义信息小部件如天气、资源监控。bookmarks.yaml: 可选定义书签组。docker.yaml: 可选Docker 集成配置用于更精细地控制自动发现的容器。让我们从settings.yaml开始创建一个最基础的配置--- # Homepage 全局设置 title: “我的技术仪表盘” # 页面标题 logo: “https://www.your-logo-url.com/logo.png” # 可选Logo URL favicon: “https://www.your-favicon-url.com/favicon.ico” # 可选网站图标 background: “https://images.unsplash.com/photo-1550745165-9bc0b252726f” # 可选背景图 language: zh # 语言支持中文 theme: dark # 主题可选 light, dark, auto layout: horizontal # 服务卡片布局可选 horizontal水平分类或 vertical垂直列表创建services.yaml文件这是配置的核心。我们先手动添加两个服务作为示例--- # 服务配置 services: - Media: # 这是一个分类Category - Jellyfin: # 服务名称 icon: jellyfin.png # 图标文件名需放置于 ./config/icons/ 目录 href: https://jellyfin.your-domain.com # 服务访问地址 description: 个人媒体库 # 描述信息 widget: # 小部件定义用于显示状态 type: jellyfin # 类型对应特定集成 url: https://jellyfin.your-domain.com # 状态检查地址 username: ${JELLYFIN_USER} # 使用环境变量保护敏感信息 password: ${JELLYFIN_PASS} - Infrastructure: - Server Dashboard: icon: server.png href: http://192.168.1.100:9090 # 内部地址示例 description: 服务器监控 widget: type: prometheus # 使用 Prometheus 获取指标 url: http://192.168.1.100:9090/api/v1/query query: up{job“node”}配置完成后重启 Homepage 容器 (docker-compose restart) 或等待其自动热重载约30秒刷新页面即可看到效果。4. 高级配置与自动化技巧4.1 利用服务发现实现“半自动”配置手动添加服务虽然直观但当服务众多时就很繁琐。Homepage 的“服务发现”功能可以极大提升效率。这需要你在docker-compose.yml中挂载了 Docker Socket。首先确保你的其他服务如 Jellyfin, Nextcloud也通过 Docker 运行并且使用了规范的容器标签Labels。Homepage 会识别这些标签。例如你的 Jellyfin 的docker-compose.yml可以这样添加标签services: jellyfin: image: jellyfin/jellyfin container_name: jellyfin labels: - “homepage.groupMedia” # 指定在Homepage中的分类 - “homepage.nameJellyfin” # 指定显示名称 - “homepage.iconjellyfin.png” # 指定图标 - “homepage.hrefhttps://jellyfin.your-domain.com” # 指定外部访问链接 - “homepage.description我的电影和剧集库” # 描述 # ... 其他配置当 Homepage 启动并挂载了 Docker Socket 后它会在后台扫描所有带有homepage.*标签的容器并自动将它们添加到services.yaml中实际上是动态加载不会修改原文件。你可以在 Homepage 的设置界面看到一个 “Docker” 选项卡里面会列出所有发现的容器你可以选择性地启用或禁用它们。实操心得我建议将核心的、固定的服务如监控、核心数据库依然用手动方式配置在services.yaml中保证其稳定性。而对于经常变更的、临时性的测试服务则使用 Docker 标签进行自动发现。两者可以共存。4.2 Widgets 小部件的深度配置Widgets 是让仪表盘“活”起来的关键。Homepage 内置了多种小部件。资源监控 Widget (Glances/Speedtest):要监控服务器本身的 CPU、内存、磁盘使用率你需要运行一个额外的监控代理如glances。同样用 Docker 部署# 在 homepage 的 docker-compose.yml 中追加 glances: image: nicolargo/glances:latest container_name: glances restart: unless-stopped pid: host network_mode: “host” # 使用主机网络以获取真实数据 privileged: true volumes: - /var/run/docker.sock:/var/run/docker.sock:ro - /sys:/sys:ro - /proc:/proc:ro command: glances -w --disable-webui然后在widgets.yaml中添加--- # 小部件配置 widgets: - resources: # 资源监控 type: glances # 类型 url: http://glances:61208 # glances 容器地址同 Docker 网络下可用容器名访问 columns: 2 # 显示为2列 - weather: # 天气 type: weather location: Beijing # 城市 units: metric # 单位metric 为摄氏度imperial 为华氏度 provider: openweathermap # 提供商需申请 API Key key: ${OPENWEATHER_API_KEY} # 建议使用环境变量环境变量的使用像 API Key、密码等敏感信息绝对不要硬编码在 YAML 文件中。应该使用环境变量。在docker-compose.yml的homepage服务部分添加environment或者使用.env文件。# docker-compose.yml 片段 services: homepage: ... environment: - PUID1000 - PGID1000 - JELLYFIN_USERadmin - JELLYFIN_PASS${JELLYFIN_PASSWORD} # 从 .env 文件读取 - OPENWEATHER_API_KEY${OPENWEATHER_KEY}在项目根目录创建.env文件JELLYFIN_PASSWORDyour_super_secret_password OPENWEATHER_KEYyour_openweather_api_key并在docker-compose.yml中声明使用此文件env_file: .env。这样你的配置文件services.yaml或widgets.yaml中就可以安全地引用${VAR_NAME}了。4.3 样式自定义与书签管理自定义 CSS你可以在./config目录下创建一个custom.css文件Homepage 会自动加载。这里可以覆盖几乎所有样式。/* 示例修改服务卡片的背景和悬停效果 */ .service { border-radius: 12px !important; background-color: rgba(255, 255, 255, 0.05) !important; } .service:hover { background-color: rgba(255, 255, 255, 0.1) !important; transform: translateY(-2px); transition: all 0.2s ease; }书签管理 (bookmarks.yaml):除了服务你还可以快速添加常用的网页链接。--- # 书签配置 bookmarks: - Developer: - GitHub: - “GitHub”: https://github.com - “GitLab”: https://gitlab.com - News: - “Hacker News”: https://news.ycombinator.com - “TechCrunch”: https://techcrunch.com5. 常见问题排查与维护心得5.1 部署与连接问题速查表问题现象可能原因排查步骤与解决方案访问IP:3000无法连接1. 容器未成功启动2. 防火墙/安全组未放行端口1. 运行docker-compose logs homepage查看容器日志检查错误信息。2. 运行docker ps确认容器状态是否为Up。3. 检查服务器防火墙如ufw或云服务商安全组确保3000端口对外开放。页面空白或加载错误1. 配置文件语法错误2. 前端资源加载失败1. 检查所有.yaml文件的缩进和语法YAML 对格式非常敏感。可以使用在线 YAML 校验工具。2. 打开浏览器开发者工具F12查看 Console 和 Network 标签页确认是否有 JS/CSS 文件加载失败。服务状态显示为“离线”或“错误”1. 网络不通2. 代理配置问题3. 认证失败1. 确保 Homepage 容器能访问到目标服务地址。在 Homepage 容器内执行docker exec homepage curl http://目标服务地址测试连通性。2. 如果目标服务需要 HTTPS 或特殊端口检查href和widget.url配置是否正确。3. 如果服务需要认证确保在widget部分正确配置了用户名、密码或 API Key并考虑使用环境变量。Docker 服务发现不工作1. Docker Socket 挂载错误2. 容器标签未正确设置1. 确认docker-compose.yml中挂载了/var/run/docker.sock且权限为ro。2. 检查其他容器的labels配置确保前缀是homepage.。3. 在 Homepage 界面点击设置图标查看 “Docker” 选项卡是否有容器列表。5.2 性能优化与安全建议图标管理将常用的图标文件PNG/SVG格式放入./config/icons/目录然后在配置中通过icon: filename.png引用。这比使用网络链接更可靠、加载更快。社区有庞大的图标库可以寻找现成的资源。反向代理与 HTTPS强烈建议不要将 Homepage 的 3000 端口直接暴露在公网。应该使用 Nginx 或 Caddy 等反向代理工具为其配置域名和 HTTPS 证书。这不仅能提升安全性还能解决可能的端口冲突问题。# Nginx 配置示例 server { listen 443 ssl; server_name dashboard.your-domain.com; ssl_certificate /path/to/cert.pem; ssl_certificate_key /path/to/key.pem; location / { proxy_pass http://localhost:3000; # 指向 Homepage 容器 proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } }配置版本控制你的./config目录包含了所有自定义设置。务必将其纳入 Git 等版本控制系统进行管理。这样在迁移服务器或误操作时可以快速恢复。定期更新Homepage 项目迭代较快定期更新 Docker 镜像可以获取新功能和修复。使用docker-compose pull homepage拉取最新镜像然后docker-compose up -d重启。更新前请备份config目录。5.3 我的个性化配置心得经过一段时间的深度使用我总结出几个让 Homepage 更好用的配置习惯按角色分区我的 Homepage 分为几个区域“运维监控”Grafana, Prometheus, 服务器状态、“开发工具”GitLab, Jenkins, 文档库、“媒体服务”Jellyfin, *Arr系列和“生活智能”智能家居控制台天气。通过清晰的分类我能瞬间聚焦到当前需要的信息。善用状态指示器对于关键服务如数据库、生产环境应用我不仅配置链接更重视其widget状态检查。颜色鲜明的“在线”绿色和“离线”红色指示比任何监控告警都更直观地给我全局健康状态。保持简洁避免将太多不常用的链接塞进去。Homepage 的核心价值是“一眼看到最重要的信息”。如果卡片太多反而失去了快速定位的意义。我每个月会回顾一次清理掉不再需要的服务。组合使用书签和服务对于纯粹的外部链接如公司HR系统、外部API文档我用书签分组管理。对于需要状态监控的内部服务则用服务卡片。两者结合页面既功能完整又条理清晰。部署并调教好 Homepage 后它真的成了我每天数字生活的入口。那种所有关键信息尽在掌握的感觉极大地减少了上下文切换的成本提升了工作的专注度和效率。这个项目的魅力在于它从一个简单的链接聚合开始却能通过持续的配置和优化最终演变成完全贴合你个人工作流和习惯的专属控制中心。