尧图网页设计 
1. 项目概述与核心价值最近在折腾服务器发现一个痛点随着自建的服务越来越多像什么Docker里的Portainer、Jellyfin还有各种数据库管理界面、监控面板书签里塞得满满当当每次想用哪个都得翻半天。更别提那些部署在内网、需要特定端口访问的服务IP和端口号根本记不住。这让我想起了早年用过的浏览器起始页但那些要么功能太简单要么广告满天飞完全不符合我们这种“自建玩家”的需求。直到我发现了Homepage这个项目它本质上是一个高度可定制、专为自建服务设计的个人导航仪表盘。你可以把它理解为你所有网络服务的“控制中心”或“门户网站”一个页面聚合所有常用链接、服务状态和信息卡片。它的核心价值非常明确统一入口提升效率彰显个性。对于任何拥有VPS、NAS或者哪怕只是一台常年开机的旧电脑的用户来说部署了Homepage之后你只需要记住一个地址比如home.yourdomain.com就能一键跳转到所有内部服务还能实时看到CPU温度、硬盘空间、服务运行状态等关键信息。这不仅仅是方便更是一种优雅的运维方式。它用YAML文件进行配置无需数据库部署简单但扩展性极强社区贡献了大量第三方服务的图标和集成方案。无论是资深Linux玩家还是刚入门的新手花上半小时部署一个Homepage都能让你的自建服务体验提升一个档次。2. 部署环境准备与方案选型在开始动手之前我们需要规划好部署环境。Homepage非常轻量对资源要求极低但为了获得最佳体验和后续维护的便利性前期的方案选型很重要。2.1 硬件与系统要求Homepage本身是一个静态网页应用后端通过一个轻量级的Node.js服务提供API用于获取服务状态、系统信息等。因此它对硬件的要求几乎可以忽略不计CPU/内存单核CPU、128MB内存就足以流畅运行。实际上它在我树莓派Zero 2W512MB内存上跑得都非常欢快。存储空间应用本身占用约50MB配置文件YAML大小几乎可以忽略。主要空间留给Docker镜像如果采用Docker部署或者Node.js环境。网络需要能访问互联网以下载Docker镜像或NPM包并且需要能访问你希望监控的那些服务的网络通常是同一局域网。系统方面绝大多数主流的Linux发行版都可以例如Ubuntu Server 22.04 LTS / 24.04 LTS用户基数大文档丰富适合新手。Debian 12以稳定著称是很多NAS系统如OMV的基础。AlmaLinux / Rocky Linux 9作为CentOS的替代品在企业级环境中更常见。openSUSE / Fedora Server适合喜欢前沿特性的用户。我个人推荐Ubuntu Server LTS或Debian Stable它们在社区支持和软件包可用性上表现最好。确保系统已经更新到最新sudo apt update sudo apt upgrade -y。2.2 部署方式深度对比Homepage主要有三种部署方式Docker推荐、Docker Compose强烈推荐和裸机安装。我们来详细拆解一下各自的优劣和适用场景。1. Docker单容器部署这是最快速、最干净的方式。一条命令就能跑起来所有依赖都被封装在容器里与宿主机隔离。docker run -d \ --name homepage \ -p 3000:3000 \ -v /path/to/your/config:/app/config \ -v /var/run/docker.sock:/var/run/docker.sock \ --restart unless-stopped \ ghcr.io/gethomepage/homepage:latest优点极致简单秒级部署和销毁非常适合快速体验。缺点命令行参数较长管理和更新稍显麻烦需要手动处理卷挂载和重启策略。适合谁想快速尝鲜或者对Docker命令非常熟悉的用户。2. Docker Compose部署首选方案这是目前最主流、最推荐的方式。通过一个docker-compose.yml文件定义所有服务参数管理起来一目了然。version: 3.8 services: homepage: image: ghcr.io/gethomepage/homepage:latest container_name: homepage ports: - 3000:3000 volumes: - ./config:/app/config - /var/run/docker.sock:/var/run/docker.sock restart: unless-stopped优点配置即文档一目了然。一键启动/停止/更新docker-compose up -d易于版本控制和迁移。可以轻松扩展成多服务栈比如把数据库也放进来。缺点需要多学一个docker-compose工具但它的学习成本极低收益巨大。适合谁几乎所有用户尤其是打算长期使用并可能扩展其他服务的用户。3. 裸机安装直接Node.js运行直接从GitHub克隆源码用npm或yarn安装依赖并启动。git clone https://github.com/gethomepage/homepage.git cd homepage npm install npm run build npm start优点最“原生”对宿主机环境控制力最强没有容器层的性能损耗虽然可忽略。缺点需要手动配置Node.js环境处理依赖冲突部署和更新步骤繁琐容易污染系统环境。适合谁对Docker有抵触或者需要在无法运行容器的特殊环境如某些老旧的嵌入式设备中部署的极客。我的实操心得无脑选择Docker Compose。它完美平衡了易用性和可维护性。docker-compose.yml文件就是你的部署清单下次换服务器直接把这个文件和config文件夹拷过去一条命令就能完全复原你的整个导航页这种体验是无可替代的。Docker本身也解决了环境一致性的“玄学”问题。2.3 关键依赖安装无论选择哪种方式宿主机上都需要安装Docker和Docker Compose如果你选方案2或3。以Ubuntu/Debian为例安装Docker# 卸载旧版本 sudo apt remove docker docker-engine docker.io containerd runc # 安装依赖 sudo apt update sudo apt install -y ca-certificates curl gnupg # 添加Docker官方GPG密钥 sudo install -m 0755 -d /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg sudo chmod ar /etc/apt/keyrings/docker.gpg # 设置仓库 echo \ deb [arch$(dpkg --print-architecture) signed-by/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \ $(. /etc/os-release echo $VERSION_CODENAME) stable | \ sudo tee /etc/apt/sources.list.d/docker.list /dev/null # 安装Docker引擎 sudo apt update sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin # 将当前用户加入docker组避免每次用sudo sudo usermod -aG docker $USER # **重要退出当前终端并重新登录使组权限生效**验证安装docker --version docker compose version # 注意是 compose不是 docker-compose (新插件)如果输出类似Docker version 24.0.7和Docker Compose version v2.24.0说明安装成功。注意事项docker-compose这个独立的二进制文件正在被docker compose插件取代。新安装的Docker默认包含后者。如果遇到老教程用的是docker-compose up可以尝试用docker compose up替代或者通过apt install docker-compose安装旧版独立二进制文件。我建议直接适应新的插件命令。3. 使用Docker Compose部署Homepage我们采用最优的Docker Compose方案进行部署。整个过程分为创建目录结构、编写配置文件、启动服务、配置反向代理四个核心步骤。3.1 创建项目目录与配置文件首先为Homepage创建一个独立的工作目录这样所有相关文件都能集中管理。mkdir -p ~/homepage-docker cd ~/homepage-docker在这个目录下创建两个核心文件docker-compose.yml和config目录。touch docker-compose.yml mkdir -p config接下来编辑docker-compose.yml文件。这里我们使用一个功能更丰富的版本它包含了健康检查和对时区的支持version: 3.8 services: homepage: image: ghcr.io/gethomepage/homepage:latest container_name: homepage restart: unless-stopped ports: - 3000:3000 # 默认端口可按需修改 environment: - TZAsia/Shanghai # 设置容器时区非常重要 - PUID1000 # 设置运行的用户ID与宿主机当前用户保持一致方便权限管理 - PGID1000 # 设置运行的组ID volumes: - ./config:/app/config # 将本地config目录挂载到容器内持久化配置 - /var/run/docker.sock:/var/run/docker.sock # 挂载Docker套接字用于监控其他容器状态 healthcheck: # 健康检查让Docker知道服务是否正常 test: [CMD, wget, --no-verbose, --tries1, --spider, http://localhost:3000] interval: 30s timeout: 10s retries: 3 start_period: 40s/var/run/docker.sock挂载这是Homepage能够获取其他Docker容器状态运行/停止的关键。它允许Homepage容器与宿主机的Docker守护进程通信。请注意这带来了一定的安全风险因为它赋予了该容器几乎与宿主机root用户等同的Docker控制权。在可信的内部网络环境中这通常是可接受的。如果你非常在意安全可以考虑使用更细粒度的Docker API或跳过此挂载这样状态检测功能会失效。PUID/PGID这两个环境变量用于指定容器内运行进程的用户和组ID。设置为宿主机你的普通用户ID通常都是1000可以保证在config目录下创建的配置文件其所有者是你的普通用户而不是root这样你直接用文本编辑器修改时就不会遇到权限问题。可以用id -u和id -g命令查看你的UID和GID。3.2 启动Homepage服务配置文件就绪后启动服务非常简单# 在 ~/homepage-docker 目录下执行 docker compose up -d-d参数代表“detached”让服务在后台运行。使用以下命令检查服务状态和日志# 查看容器运行状态 docker compose ps # 应该看到状态为 “running” 且健康检查为 “healthy” # 查看实时日志 docker compose logs -f homepage # 看到类似 “Server is running on http://localhost:3000” 的日志即表示启动成功 # 按 CtrlC 退出日志查看现在你可以通过浏览器访问http://你的服务器IP:3000来看到Homepage的默认界面了。它是一个简洁的欢迎页面告诉你配置文件在哪里。3.3 配置反向代理与HTTPS可选但强烈推荐直接通过IP:端口访问既不安全也不方便。我们通常通过反向代理如Nginx Proxy Manager, Caddy, Traefik为其绑定一个域名并启用HTTPS。这里以最流行的Nginx Proxy Manager (NPM)为例。假设你已经部署了NPM并且拥有一个域名例如home.mydomain.com。在DNS服务商处将home.mydomain.com的A记录指向你的服务器公网IP。登录NPM管理界面通常是http://服务器IP:81。点击 “Proxy Hosts” - “Add Proxy Host”。填写详细信息Domain Names:home.mydomain.comScheme:httpForward Hostname / IP:homepage(如果你和NPM在同一个Docker网络下)或你的服务器内网IPForward Port:3000在 “SSL” 标签页申请并启用SSL证书例如使用Let‘s Encrypt。保存后稍等片刻即可通过https://home.mydomain.com安全地访问你的Homepage。实操心得强烈建议将Homepage和你的反向代理如NPM放在同一个自定义的Docker网络中。这样在NPM里配置转发时可以直接用服务名如homepage代替IP地址即使服务器IP变了也无需修改配置。创建网络命令docker network create my-proxy-network然后在docker-compose.yml中为两个服务都加上networks: - my-proxy-network。4. 核心配置详解打造你的专属仪表盘Homepage的强大和美观完全通过YAML配置文件来驱动。所有配置都存放在你之前挂载的~/homepage-docker/config目录下。首次启动后这个目录是空的你需要手动创建配置文件。主要配置文件有settings.yaml全局设置如主题、语言、标题等。services.yaml定义导航页上显示的所有服务卡片。bookmarks.yaml定义书签小组件。widgets.yaml定义各种信息小组件如系统状态、天气、日历等。docker.yamlDocker集成配置用于自动发现和显示容器状态。4.1 基础全局设置 (settings.yaml)首先创建settings.yaml这是仪表盘的“皮肤”和“行为”总控。--- # Homepage 全局设置 title: 我的数字家园 # 仪表盘左上角显示的标题 favicon: /img/favicon.png # 浏览器标签页图标图片需放在 config/www 目录下 background: /img/background.jpg # 背景图片同上 language: zh # 界面语言支持中文 theme: dark # 主题可选 dark, light, auto headerStyle: underlined # 头部样式可选 underlined, material, faded, clean layout: # 布局设置 media: # 媒体区域如搜索框、欢迎语位置 location: header # 可选 header, footer, disabled search: # 搜索框设置 enabled: true provider: google # 搜索引擎可选 google, duckduckgo, bing 等 target: _blank # 在新标签页打开搜索结果 visibility: # 可见性控制 header: true # 显示头部 footer: true # 显示页脚可放自定义链接创建config/www目录把你的favicon.png和background.jpg放进去刷新页面即可生效。主题切换非常平滑auto会根据系统设置自动切换深浅模式。4.2 服务卡片配置 (services.yaml)这是配置的核心决定了你的导航页上有什么。配置逻辑是分“组”(group)组内放“服务”(items)。--- # 服务分组配置 - Services: # 第一个分组名称叫“Services” icon: fas fa-server # 分组图标使用Font Awesome类名 href: https://portainer.local # 点击分组标题的跳转链接可选 items: # 该分组下的服务列表 - Portainer: description: Docker容器管理 icon: ./assets/portainer.png # 使用本地图标需放在 config/www/assets 下 href: https://portainer.local target: _blank # 新标签页打开 status: # 状态检查 url: https://portainer.local/api/status icon: fas fa-heartbeat - Jellyfin: description: 媒体服务器 icon: ./assets/jellyfin.svg href: https://jellyfin.local badge: # 徽标可以显示动态信息 type: jellyfin value: streamCount # 显示当前播放流数量需集成 - PostgreSQL Adminer: description: 数据库管理 icon: fas fa-database href: http://192.168.1.100:8080 tag: internal # 标签可用于筛选 widget: # 集成小组件显示数据库大小等信息需配置 type: postgres url: postgres://user:passdb-host:5432/dbname - Development: # 第二个分组 icon: fas fa-code items: - GitLab: description: 自建代码仓库 icon: ./assets/gitlab.png href: https://gitlab.local - VS Code Server: description: 在线IDE icon: ./assets/vscode.svg href: https://code.local图标获取技巧Homepage内置了Font Awesome图标库fas fa-xxx。但对于特定服务如Jellyfin, Portainer使用其官方Logo体验更好。推荐去服务的官网或GitHub仓库下载SVG或PNG格式的Logo放到config/www/assets目录下然后像上面那样用相对路径引用。4.3 书签与小组件配置书签 (bookmarks.yaml)适合放一些不常管理但需要快速访问的网页链接比如技术文档、常用工具网站。--- - 技术文档: icon: fas fa-book links: - Docker Docs: icon: ./assets/docker.svg href: https://docs.docker.com/ - Kubernetes Docs: icon: ./assets/kubernetes.svg href: https://kubernetes.io/docs/ - 日常工具: icon: fas fa-tools links: - 翻译: icon: fas fa-language href: https://deepl.com/translator小组件 (widgets.yaml)是信息面板可以实时显示数据。最常用的是“资源监控”和“Docker状态”。--- # 系统资源监控 (需要安装 lmsensors 等工具并在Docker容器中挂载相关设备文件) - resources: type: resources label: 系统状态 columns: 2 # 显示为2列 show: true cpu: true memory: true disk: / # 监控根分区 disk2: /data # 监控数据分区 network: eth0 # 监控网络接口 units: metric # 温度单位metric为摄氏度 refresh: 60 # 刷新间隔秒 # Docker容器状态 (需要挂载 docker.sock) - docker: type: docker label: 容器状态 show: true sort: name # 按名称排序 filter: # 过滤器只显示特定容器 - name: homepage - label: homepage.enabletrue # 通过Docker标签过滤 hide: # 隐藏某些容器 - some-internal-container要使资源监控生效需要在docker-compose.yml中为Homepage容器添加额外的设备挂载volumes: - ./config:/app/config - /var/run/docker.sock:/var/run/docker.sock # 添加以下挂载以读取系统信息 - /proc:/proc:ro - /sys:/sys:ro - /etc/machine-id:/etc/machine-id:ro - /etc/os-release:/etc/os-release:ro # 如果监控温度需要挂载 hwmon路径可能因系统而异 - /sys/class/hwmon:/sys/class/hwmon:ro - /sys/class/thermal:/sys/class/thermal:ro4.4 Docker自动发现配置 (docker.yaml)这是Homepage的“魔法”功能之一可以自动从Docker守护进程获取正在运行的容器列表并尝试自动生成服务卡片。--- # Docker自动发现配置 connection: socket: /var/run/docker.sock # Docker套接字路径与挂载路径一致 containers: - name: .* # 匹配所有容器可以正则匹配 icon: .* # 自动匹配图标 description: .* # 自动匹配描述 href: .* # 自动生成链接基于容器标签 group: Auto-Discovered # 自动归到“自动发现”组 widget: # 尝试为特定容器生成小组件 type: .*更常见的做法是不在docker.yaml里做复杂配置而是直接在运行其他容器时通过Docker标签Labels来告诉Homepage如何展示自己。例如运行Jellyfin时docker run -d \ --name jellyfin \ -p 8096:8096 \ -v /path/to/config:/config \ -v /path/to/media:/media \ -l homepage.nameJellyfin \ -l homepage.iconhttps://cdn.jsdelivr.net/gh/walkxcode/dashboard-icons/png/jellyfin.png \ -l homepage.description我的媒体库 \ -l homepage.hrefhttps://jellyfin.local \ -l homepage.groupMedia \ jellyfin/jellyfin这样Homepage就能自动发现并漂亮地展示这个容器了。社区维护了一个巨大的图标库如walkxcode/dashboard-icons可以直接通过URL引用。5. 高级定制与集成技巧基础配置完成后你的导航页已经很好用了。但Homepage的潜力远不止于此通过一些高级定制它能真正成为你的生产力中枢。5.1 主题深度自定义与CSS注入虽然内置了几个主题但你可能想调整颜色、间距或字体。Homepage支持自定义CSS。在config目录下创建custom.css文件。在settings.yaml中启用它customCSS: /config/custom.css在custom.css中编写样式。例如修改卡片背景和阴影/* 自定义CSS */ .card { background: rgba(30, 30, 46, 0.7) !important; /* 深色半透明背景 */ backdrop-filter: blur(10px) !important; /* 毛玻璃效果 */ border: 1px solid rgba(255, 255, 255, 0.1) !important; border-radius: 16px !important; box-shadow: 0 8px 32px rgba(0, 0, 0, 0.3) !important; transition: transform 0.2s ease, box-shadow 0.2s ease !important; } .card:hover { transform: translateY(-4px) !important; box-shadow: 0 12px 40px rgba(0, 0, 0, 0.4) !important; } /* 修改标题字体 */ .app-title { font-family: Segoe UI, HarmonyOS Sans SC, sans-serif !important; font-weight: 600 !important; }通过浏览器的开发者工具F12检查元素找到对应的CSS类名你就可以进行无限定制。5.2 集成第三方API与动态信息Homepage的小组件支持集成多种API让静态页面“活”起来。1. 天气小组件 去 OpenWeatherMap 或 WeatherAPI 申请一个免费API Key。 在widgets.yaml中添加- weather: type: weather label: 本地天气 location: Beijing # 城市名 units: metric provider: openweathermap # 或 weatherapi key: YOUR_API_KEY_HERE # 你的API密钥 language: zh_cn2. RSS订阅小组件 可以显示技术博客、新闻网站的更新。- rss: type: rss label: 技术资讯 url: https://feeds.feedburner.com/some-tech-blog limit: 5 # 显示最新5条3. 自定义API小组件 如果你自己有一些服务能提供JSON格式的数据可以创建自定义小组件。例如显示当前比特币价格- crypto: type: custom label: 比特币价格 url: https://api.coindesk.com/v1/bpi/currentprice.json headers: # 可选请求头 User-Agent: Homepage method: GET refresh: 300 parser: json # 解析JSON key: bpi.USD.rate # 使用JSONPath提取数据 units: USD你需要根据目标API返回的JSON结构调整key的值。JSONPath语法很简单比如data.items[0].price。5.3 服务状态检测与告警状态检测是Homepage的亮点。除了简单的HTTP状态码检查它还支持更复杂的检测。基础HTTP检测 在services.yaml中为服务添加status字段。- My Service: ... status: url: https://service.local/health # 健康检查端点 icon: fas fa-heartbeat followRedirect: true # 跟随重定向 acceptCodes: [200, 301, 302] # 可接受的状态码如果该端点返回2xx状态码卡片上会显示一个绿色的状态点否则显示红色。高级检测脚本或命令 你可以编写一个脚本放在config/scripts目录下然后通过status字段调用。脚本返回0表示健康非0表示异常。创建config/scripts/check_mysql.sh#!/bin/bash # 检查MySQL是否可连接 mysqladmin -h 192.168.1.101 -u monitor -ppassword ping /dev/null 21 exit $?记得给脚本执行权限chmod x config/scripts/check_mysql.sh在服务配置中引用- MySQL Database: ... status: command: /app/config/scripts/check_mysql.sh icon: fas fa-database避坑指南状态检测命令是在Homepage的Docker容器内执行的。因此你的脚本必须使用容器内可用的命令如curl,wget,nc,pg_isready等。如果需要mysqladmin你可能需要在构建自定义镜像时安装它或者使用一个更通用的HTTP健康检查端点。5.4 备份与迁移策略你的所有心血都在config目录下的YAML文件里。备份和迁移变得极其简单。备份# 直接打包整个配置目录 cd ~/homepage-docker tar -czf homepage-backup-$(date %Y%m%d).tar.gz config/ # 这个压缩包包含了你的所有设置、图标和自定义脚本。迁移到新服务器在新服务器上安装Docker和Docker Compose。将备份的homepage-backup-*.tar.gz上传到新服务器。解压备份并确保目录结构一致。mkdir -p ~/homepage-docker cd ~/homepage-docker tar -xzf /path/to/homepage-backup-*.tar.gz将原来的docker-compose.yml文件也拷贝过来。运行docker compose up -d。如果域名或IP变了记得更新NPM等反向代理的配置。整个过程可以在几分钟内完成实现导航页的“无缝搬家”。这也是我强烈推荐Docker Compose方案的原因——基础设施即代码配置即资产。6. 常见问题与故障排查实录即使按照步骤操作也可能会遇到一些问题。这里记录了我自己和社区里常见的一些“坑”及其解决方案。6.1 部署启动问题问题1容器启动后立即退出日志显示权限错误。现象docker compose logs显示Permission denied或EACCES。原因最常见的是挂载的config目录权限不足容器内用户UID1000无法写入。解决# 确保 config 目录存在且权限正确 cd ~/homepage-docker sudo chown -R 1000:1000 config/ sudo chmod -R 755 config/ # 然后重启容器 docker compose down docker compose up -d问题2访问页面显示 “Cannot GET /config” 或空白页。现象能打开页面但看不到内容浏览器控制台有404错误。原因config目录是空的或者关键的settings.yaml文件不存在。解决检查config目录下是否有YAML配置文件。至少需要创建一个settings.yaml即使是空的和services.yaml。重启容器后Homepage会基于这些文件渲染页面。问题3Docker状态小组件显示 “Cannot connect to Docker”。现象Widgets里Docker状态一片红或者提示连接失败。原因/var/run/docker.sock没有正确挂载或者其权限问题。解决检查docker-compose.yml中的 volumes 部分是否包含- /var/run/docker.sock:/var/run/docker.sock。检查宿主机上该文件的权限ls -la /var/run/docker.sock。通常属于root:docker组。确保运行Homepage容器的用户PUID1000在docker组内。可以将PUID/PGID设置为0root不推荐仅作测试或者将用户加入docker组后重建容器。6.2 配置与显示问题问题4修改了YAML文件但页面没有变化。原因Homepage默认会缓存配置。浏览器也可能有缓存。解决重启容器这是最彻底的方式docker compose restart homepage。强制刷新浏览器按CtrlF5或CmdShiftR。检查YAML语法YAML对缩进非常敏感。可以使用在线YAML校验器如yamlchecker.com检查文件格式。一个常见的错误是使用Tab缩进必须使用空格。问题5自定义图标不显示显示为破碎图片。原因图标文件路径错误或者文件格式不被浏览器支持。解决确认图标文件已放在config/www/assets/目录下。在services.yaml中图标路径应为./assets/your-icon.png注意开头是.。推荐使用SVG格式图标体积小且缩放不失真。对于PNG确保尺寸不要过大建议64x64或128x128像素。检查浏览器控制台F12 - Console是否有404错误确认请求的图片路径是否正确。问题6资源监控小组件不显示CPU温度或磁盘信息。原因容器内无法读取宿主机相应的系统文件。解决确保docker-compose.yml中已经挂载了/proc,/sys,/sys/class/hwmon等目录见4.3节。对于温度监控宿主机可能需要安装lm-sensors并运行sensors-detect来启用传感器。sudo apt install lm-sensors sudo sensors-detect # 全部按回车选yes即可 sudo service kmod start温度传感器路径可能不同。可以进入容器内部查找docker exec -it homepage sh # 在容器内 find /sys -name temp*_input 2/dev/null找到类似/sys/class/hwmon/hwmon0/temp1_input的路径然后在widgets.yaml的resources部分指定hwmonPath: /sys/class/hwmon/hwmon0。6.3 性能与安全优化问题7页面加载速度慢尤其是图标多的时候。优化方案图标本地化不要大量使用外部CDN的图标链接尽量下载到本地assets目录。这能显著提升加载速度和稳定性。启用浏览器缓存在反向代理如NPM中为Homepage的静态资源/img/*,/assets/*设置较长的缓存时间。精简服务数量如果卡片过多考虑分组折叠或分页。Homepage本身非常轻量瓶颈通常在网络和图标加载上。问题8挂载docker.sock的安全顾虑。风险容器内拥有docker.sock的写权限等同于拥有宿主机的root权限。如果Homepage应用存在漏洞可能被利用。缓解措施使用只读挂载- /var/run/docker.sock:/var/run/docker.sock:ro。这样Homepage只能读取容器状态无法控制。使用Docker API over TCP with TLS这是更安全但更复杂的方式。在宿主机上配置Docker守护进程监听受TLS保护的TCP端口然后Homepage通过证书连接。这需要生成CA和客户端证书。定期更新保持Homepage镜像为最新版本以获取安全补丁。网络隔离将Homepage容器放在一个独立的Docker网络中仅允许其与反向代理通信限制其网络访问能力。问题9如何更新Homepage到最新版本方法使用Docker Compose更新非常简单。cd ~/homepage-docker # 拉取最新镜像 docker compose pull homepage # 重启服务 docker compose up -d --force-recreate homepage # 清理旧镜像 docker image prune -f建议在更新前备份你的config目录。部署和配置Homepage的过程就像在精心布置一个数字世界的家。从最初的空旷到逐渐填满各种服务卡片和信息小组件每一次修改都能立刻在页面上得到反馈这种即时成就感是驱动我们不断优化的动力。它不仅仅是一个导航页更是你个人技术栈的“地图”和“控制台”。当你把所有散落的服务聚合在一处并赋予它们状态和美感时那种对自有数字资产的掌控感和秩序感是使用任何现成云服务都无法替代的。 使用Docker Compose部署Homepage：打造个人服务导航仪表盘
1. 项目概述与核心价值最近在折腾服务器发现一个痛点随着自建的服务越来越多像什么Docker里的Portainer、Jellyfin还有各种数据库管理界面、监控面板书签里塞得满满当当每次想用哪个都得翻半天。更别提那些部署在内网、需要特定端口访问的服务IP和端口号根本记不住。这让我想起了早年用过的浏览器起始页但那些要么功能太简单要么广告满天飞完全不符合我们这种“自建玩家”的需求。直到我发现了Homepage这个项目它本质上是一个高度可定制、专为自建服务设计的个人导航仪表盘。你可以把它理解为你所有网络服务的“控制中心”或“门户网站”一个页面聚合所有常用链接、服务状态和信息卡片。它的核心价值非常明确统一入口提升效率彰显个性。对于任何拥有VPS、NAS或者哪怕只是一台常年开机的旧电脑的用户来说部署了Homepage之后你只需要记住一个地址比如home.yourdomain.com就能一键跳转到所有内部服务还能实时看到CPU温度、硬盘空间、服务运行状态等关键信息。这不仅仅是方便更是一种优雅的运维方式。它用YAML文件进行配置无需数据库部署简单但扩展性极强社区贡献了大量第三方服务的图标和集成方案。无论是资深Linux玩家还是刚入门的新手花上半小时部署一个Homepage都能让你的自建服务体验提升一个档次。2. 部署环境准备与方案选型在开始动手之前我们需要规划好部署环境。Homepage非常轻量对资源要求极低但为了获得最佳体验和后续维护的便利性前期的方案选型很重要。2.1 硬件与系统要求Homepage本身是一个静态网页应用后端通过一个轻量级的Node.js服务提供API用于获取服务状态、系统信息等。因此它对硬件的要求几乎可以忽略不计CPU/内存单核CPU、128MB内存就足以流畅运行。实际上它在我树莓派Zero 2W512MB内存上跑得都非常欢快。存储空间应用本身占用约50MB配置文件YAML大小几乎可以忽略。主要空间留给Docker镜像如果采用Docker部署或者Node.js环境。网络需要能访问互联网以下载Docker镜像或NPM包并且需要能访问你希望监控的那些服务的网络通常是同一局域网。系统方面绝大多数主流的Linux发行版都可以例如Ubuntu Server 22.04 LTS / 24.04 LTS用户基数大文档丰富适合新手。Debian 12以稳定著称是很多NAS系统如OMV的基础。AlmaLinux / Rocky Linux 9作为CentOS的替代品在企业级环境中更常见。openSUSE / Fedora Server适合喜欢前沿特性的用户。我个人推荐Ubuntu Server LTS或Debian Stable它们在社区支持和软件包可用性上表现最好。确保系统已经更新到最新sudo apt update sudo apt upgrade -y。2.2 部署方式深度对比Homepage主要有三种部署方式Docker推荐、Docker Compose强烈推荐和裸机安装。我们来详细拆解一下各自的优劣和适用场景。1. Docker单容器部署这是最快速、最干净的方式。一条命令就能跑起来所有依赖都被封装在容器里与宿主机隔离。docker run -d \ --name homepage \ -p 3000:3000 \ -v /path/to/your/config:/app/config \ -v /var/run/docker.sock:/var/run/docker.sock \ --restart unless-stopped \ ghcr.io/gethomepage/homepage:latest优点极致简单秒级部署和销毁非常适合快速体验。缺点命令行参数较长管理和更新稍显麻烦需要手动处理卷挂载和重启策略。适合谁想快速尝鲜或者对Docker命令非常熟悉的用户。2. Docker Compose部署首选方案这是目前最主流、最推荐的方式。通过一个docker-compose.yml文件定义所有服务参数管理起来一目了然。version: 3.8 services: homepage: image: ghcr.io/gethomepage/homepage:latest container_name: homepage ports: - 3000:3000 volumes: - ./config:/app/config - /var/run/docker.sock:/var/run/docker.sock restart: unless-stopped优点配置即文档一目了然。一键启动/停止/更新docker-compose up -d易于版本控制和迁移。可以轻松扩展成多服务栈比如把数据库也放进来。缺点需要多学一个docker-compose工具但它的学习成本极低收益巨大。适合谁几乎所有用户尤其是打算长期使用并可能扩展其他服务的用户。3. 裸机安装直接Node.js运行直接从GitHub克隆源码用npm或yarn安装依赖并启动。git clone https://github.com/gethomepage/homepage.git cd homepage npm install npm run build npm start优点最“原生”对宿主机环境控制力最强没有容器层的性能损耗虽然可忽略。缺点需要手动配置Node.js环境处理依赖冲突部署和更新步骤繁琐容易污染系统环境。适合谁对Docker有抵触或者需要在无法运行容器的特殊环境如某些老旧的嵌入式设备中部署的极客。我的实操心得无脑选择Docker Compose。它完美平衡了易用性和可维护性。docker-compose.yml文件就是你的部署清单下次换服务器直接把这个文件和config文件夹拷过去一条命令就能完全复原你的整个导航页这种体验是无可替代的。Docker本身也解决了环境一致性的“玄学”问题。2.3 关键依赖安装无论选择哪种方式宿主机上都需要安装Docker和Docker Compose如果你选方案2或3。以Ubuntu/Debian为例安装Docker# 卸载旧版本 sudo apt remove docker docker-engine docker.io containerd runc # 安装依赖 sudo apt update sudo apt install -y ca-certificates curl gnupg # 添加Docker官方GPG密钥 sudo install -m 0755 -d /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg sudo chmod ar /etc/apt/keyrings/docker.gpg # 设置仓库 echo \ deb [arch$(dpkg --print-architecture) signed-by/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \ $(. /etc/os-release echo $VERSION_CODENAME) stable | \ sudo tee /etc/apt/sources.list.d/docker.list /dev/null # 安装Docker引擎 sudo apt update sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin # 将当前用户加入docker组避免每次用sudo sudo usermod -aG docker $USER # **重要退出当前终端并重新登录使组权限生效**验证安装docker --version docker compose version # 注意是 compose不是 docker-compose (新插件)如果输出类似Docker version 24.0.7和Docker Compose version v2.24.0说明安装成功。注意事项docker-compose这个独立的二进制文件正在被docker compose插件取代。新安装的Docker默认包含后者。如果遇到老教程用的是docker-compose up可以尝试用docker compose up替代或者通过apt install docker-compose安装旧版独立二进制文件。我建议直接适应新的插件命令。3. 使用Docker Compose部署Homepage我们采用最优的Docker Compose方案进行部署。整个过程分为创建目录结构、编写配置文件、启动服务、配置反向代理四个核心步骤。3.1 创建项目目录与配置文件首先为Homepage创建一个独立的工作目录这样所有相关文件都能集中管理。mkdir -p ~/homepage-docker cd ~/homepage-docker在这个目录下创建两个核心文件docker-compose.yml和config目录。touch docker-compose.yml mkdir -p config接下来编辑docker-compose.yml文件。这里我们使用一个功能更丰富的版本它包含了健康检查和对时区的支持version: 3.8 services: homepage: image: ghcr.io/gethomepage/homepage:latest container_name: homepage restart: unless-stopped ports: - 3000:3000 # 默认端口可按需修改 environment: - TZAsia/Shanghai # 设置容器时区非常重要 - PUID1000 # 设置运行的用户ID与宿主机当前用户保持一致方便权限管理 - PGID1000 # 设置运行的组ID volumes: - ./config:/app/config # 将本地config目录挂载到容器内持久化配置 - /var/run/docker.sock:/var/run/docker.sock # 挂载Docker套接字用于监控其他容器状态 healthcheck: # 健康检查让Docker知道服务是否正常 test: [CMD, wget, --no-verbose, --tries1, --spider, http://localhost:3000] interval: 30s timeout: 10s retries: 3 start_period: 40s/var/run/docker.sock挂载这是Homepage能够获取其他Docker容器状态运行/停止的关键。它允许Homepage容器与宿主机的Docker守护进程通信。请注意这带来了一定的安全风险因为它赋予了该容器几乎与宿主机root用户等同的Docker控制权。在可信的内部网络环境中这通常是可接受的。如果你非常在意安全可以考虑使用更细粒度的Docker API或跳过此挂载这样状态检测功能会失效。PUID/PGID这两个环境变量用于指定容器内运行进程的用户和组ID。设置为宿主机你的普通用户ID通常都是1000可以保证在config目录下创建的配置文件其所有者是你的普通用户而不是root这样你直接用文本编辑器修改时就不会遇到权限问题。可以用id -u和id -g命令查看你的UID和GID。3.2 启动Homepage服务配置文件就绪后启动服务非常简单# 在 ~/homepage-docker 目录下执行 docker compose up -d-d参数代表“detached”让服务在后台运行。使用以下命令检查服务状态和日志# 查看容器运行状态 docker compose ps # 应该看到状态为 “running” 且健康检查为 “healthy” # 查看实时日志 docker compose logs -f homepage # 看到类似 “Server is running on http://localhost:3000” 的日志即表示启动成功 # 按 CtrlC 退出日志查看现在你可以通过浏览器访问http://你的服务器IP:3000来看到Homepage的默认界面了。它是一个简洁的欢迎页面告诉你配置文件在哪里。3.3 配置反向代理与HTTPS可选但强烈推荐直接通过IP:端口访问既不安全也不方便。我们通常通过反向代理如Nginx Proxy Manager, Caddy, Traefik为其绑定一个域名并启用HTTPS。这里以最流行的Nginx Proxy Manager (NPM)为例。假设你已经部署了NPM并且拥有一个域名例如home.mydomain.com。在DNS服务商处将home.mydomain.com的A记录指向你的服务器公网IP。登录NPM管理界面通常是http://服务器IP:81。点击 “Proxy Hosts” - “Add Proxy Host”。填写详细信息Domain Names:home.mydomain.comScheme:httpForward Hostname / IP:homepage(如果你和NPM在同一个Docker网络下)或你的服务器内网IPForward Port:3000在 “SSL” 标签页申请并启用SSL证书例如使用Let‘s Encrypt。保存后稍等片刻即可通过https://home.mydomain.com安全地访问你的Homepage。实操心得强烈建议将Homepage和你的反向代理如NPM放在同一个自定义的Docker网络中。这样在NPM里配置转发时可以直接用服务名如homepage代替IP地址即使服务器IP变了也无需修改配置。创建网络命令docker network create my-proxy-network然后在docker-compose.yml中为两个服务都加上networks: - my-proxy-network。4. 核心配置详解打造你的专属仪表盘Homepage的强大和美观完全通过YAML配置文件来驱动。所有配置都存放在你之前挂载的~/homepage-docker/config目录下。首次启动后这个目录是空的你需要手动创建配置文件。主要配置文件有settings.yaml全局设置如主题、语言、标题等。services.yaml定义导航页上显示的所有服务卡片。bookmarks.yaml定义书签小组件。widgets.yaml定义各种信息小组件如系统状态、天气、日历等。docker.yamlDocker集成配置用于自动发现和显示容器状态。4.1 基础全局设置 (settings.yaml)首先创建settings.yaml这是仪表盘的“皮肤”和“行为”总控。--- # Homepage 全局设置 title: 我的数字家园 # 仪表盘左上角显示的标题 favicon: /img/favicon.png # 浏览器标签页图标图片需放在 config/www 目录下 background: /img/background.jpg # 背景图片同上 language: zh # 界面语言支持中文 theme: dark # 主题可选 dark, light, auto headerStyle: underlined # 头部样式可选 underlined, material, faded, clean layout: # 布局设置 media: # 媒体区域如搜索框、欢迎语位置 location: header # 可选 header, footer, disabled search: # 搜索框设置 enabled: true provider: google # 搜索引擎可选 google, duckduckgo, bing 等 target: _blank # 在新标签页打开搜索结果 visibility: # 可见性控制 header: true # 显示头部 footer: true # 显示页脚可放自定义链接创建config/www目录把你的favicon.png和background.jpg放进去刷新页面即可生效。主题切换非常平滑auto会根据系统设置自动切换深浅模式。4.2 服务卡片配置 (services.yaml)这是配置的核心决定了你的导航页上有什么。配置逻辑是分“组”(group)组内放“服务”(items)。--- # 服务分组配置 - Services: # 第一个分组名称叫“Services” icon: fas fa-server # 分组图标使用Font Awesome类名 href: https://portainer.local # 点击分组标题的跳转链接可选 items: # 该分组下的服务列表 - Portainer: description: Docker容器管理 icon: ./assets/portainer.png # 使用本地图标需放在 config/www/assets 下 href: https://portainer.local target: _blank # 新标签页打开 status: # 状态检查 url: https://portainer.local/api/status icon: fas fa-heartbeat - Jellyfin: description: 媒体服务器 icon: ./assets/jellyfin.svg href: https://jellyfin.local badge: # 徽标可以显示动态信息 type: jellyfin value: streamCount # 显示当前播放流数量需集成 - PostgreSQL Adminer: description: 数据库管理 icon: fas fa-database href: http://192.168.1.100:8080 tag: internal # 标签可用于筛选 widget: # 集成小组件显示数据库大小等信息需配置 type: postgres url: postgres://user:passdb-host:5432/dbname - Development: # 第二个分组 icon: fas fa-code items: - GitLab: description: 自建代码仓库 icon: ./assets/gitlab.png href: https://gitlab.local - VS Code Server: description: 在线IDE icon: ./assets/vscode.svg href: https://code.local图标获取技巧Homepage内置了Font Awesome图标库fas fa-xxx。但对于特定服务如Jellyfin, Portainer使用其官方Logo体验更好。推荐去服务的官网或GitHub仓库下载SVG或PNG格式的Logo放到config/www/assets目录下然后像上面那样用相对路径引用。4.3 书签与小组件配置书签 (bookmarks.yaml)适合放一些不常管理但需要快速访问的网页链接比如技术文档、常用工具网站。--- - 技术文档: icon: fas fa-book links: - Docker Docs: icon: ./assets/docker.svg href: https://docs.docker.com/ - Kubernetes Docs: icon: ./assets/kubernetes.svg href: https://kubernetes.io/docs/ - 日常工具: icon: fas fa-tools links: - 翻译: icon: fas fa-language href: https://deepl.com/translator小组件 (widgets.yaml)是信息面板可以实时显示数据。最常用的是“资源监控”和“Docker状态”。--- # 系统资源监控 (需要安装 lmsensors 等工具并在Docker容器中挂载相关设备文件) - resources: type: resources label: 系统状态 columns: 2 # 显示为2列 show: true cpu: true memory: true disk: / # 监控根分区 disk2: /data # 监控数据分区 network: eth0 # 监控网络接口 units: metric # 温度单位metric为摄氏度 refresh: 60 # 刷新间隔秒 # Docker容器状态 (需要挂载 docker.sock) - docker: type: docker label: 容器状态 show: true sort: name # 按名称排序 filter: # 过滤器只显示特定容器 - name: homepage - label: homepage.enabletrue # 通过Docker标签过滤 hide: # 隐藏某些容器 - some-internal-container要使资源监控生效需要在docker-compose.yml中为Homepage容器添加额外的设备挂载volumes: - ./config:/app/config - /var/run/docker.sock:/var/run/docker.sock # 添加以下挂载以读取系统信息 - /proc:/proc:ro - /sys:/sys:ro - /etc/machine-id:/etc/machine-id:ro - /etc/os-release:/etc/os-release:ro # 如果监控温度需要挂载 hwmon路径可能因系统而异 - /sys/class/hwmon:/sys/class/hwmon:ro - /sys/class/thermal:/sys/class/thermal:ro4.4 Docker自动发现配置 (docker.yaml)这是Homepage的“魔法”功能之一可以自动从Docker守护进程获取正在运行的容器列表并尝试自动生成服务卡片。--- # Docker自动发现配置 connection: socket: /var/run/docker.sock # Docker套接字路径与挂载路径一致 containers: - name: .* # 匹配所有容器可以正则匹配 icon: .* # 自动匹配图标 description: .* # 自动匹配描述 href: .* # 自动生成链接基于容器标签 group: Auto-Discovered # 自动归到“自动发现”组 widget: # 尝试为特定容器生成小组件 type: .*更常见的做法是不在docker.yaml里做复杂配置而是直接在运行其他容器时通过Docker标签Labels来告诉Homepage如何展示自己。例如运行Jellyfin时docker run -d \ --name jellyfin \ -p 8096:8096 \ -v /path/to/config:/config \ -v /path/to/media:/media \ -l homepage.nameJellyfin \ -l homepage.iconhttps://cdn.jsdelivr.net/gh/walkxcode/dashboard-icons/png/jellyfin.png \ -l homepage.description我的媒体库 \ -l homepage.hrefhttps://jellyfin.local \ -l homepage.groupMedia \ jellyfin/jellyfin这样Homepage就能自动发现并漂亮地展示这个容器了。社区维护了一个巨大的图标库如walkxcode/dashboard-icons可以直接通过URL引用。5. 高级定制与集成技巧基础配置完成后你的导航页已经很好用了。但Homepage的潜力远不止于此通过一些高级定制它能真正成为你的生产力中枢。5.1 主题深度自定义与CSS注入虽然内置了几个主题但你可能想调整颜色、间距或字体。Homepage支持自定义CSS。在config目录下创建custom.css文件。在settings.yaml中启用它customCSS: /config/custom.css在custom.css中编写样式。例如修改卡片背景和阴影/* 自定义CSS */ .card { background: rgba(30, 30, 46, 0.7) !important; /* 深色半透明背景 */ backdrop-filter: blur(10px) !important; /* 毛玻璃效果 */ border: 1px solid rgba(255, 255, 255, 0.1) !important; border-radius: 16px !important; box-shadow: 0 8px 32px rgba(0, 0, 0, 0.3) !important; transition: transform 0.2s ease, box-shadow 0.2s ease !important; } .card:hover { transform: translateY(-4px) !important; box-shadow: 0 12px 40px rgba(0, 0, 0, 0.4) !important; } /* 修改标题字体 */ .app-title { font-family: Segoe UI, HarmonyOS Sans SC, sans-serif !important; font-weight: 600 !important; }通过浏览器的开发者工具F12检查元素找到对应的CSS类名你就可以进行无限定制。5.2 集成第三方API与动态信息Homepage的小组件支持集成多种API让静态页面“活”起来。1. 天气小组件 去 OpenWeatherMap 或 WeatherAPI 申请一个免费API Key。 在widgets.yaml中添加- weather: type: weather label: 本地天气 location: Beijing # 城市名 units: metric provider: openweathermap # 或 weatherapi key: YOUR_API_KEY_HERE # 你的API密钥 language: zh_cn2. RSS订阅小组件 可以显示技术博客、新闻网站的更新。- rss: type: rss label: 技术资讯 url: https://feeds.feedburner.com/some-tech-blog limit: 5 # 显示最新5条3. 自定义API小组件 如果你自己有一些服务能提供JSON格式的数据可以创建自定义小组件。例如显示当前比特币价格- crypto: type: custom label: 比特币价格 url: https://api.coindesk.com/v1/bpi/currentprice.json headers: # 可选请求头 User-Agent: Homepage method: GET refresh: 300 parser: json # 解析JSON key: bpi.USD.rate # 使用JSONPath提取数据 units: USD你需要根据目标API返回的JSON结构调整key的值。JSONPath语法很简单比如data.items[0].price。5.3 服务状态检测与告警状态检测是Homepage的亮点。除了简单的HTTP状态码检查它还支持更复杂的检测。基础HTTP检测 在services.yaml中为服务添加status字段。- My Service: ... status: url: https://service.local/health # 健康检查端点 icon: fas fa-heartbeat followRedirect: true # 跟随重定向 acceptCodes: [200, 301, 302] # 可接受的状态码如果该端点返回2xx状态码卡片上会显示一个绿色的状态点否则显示红色。高级检测脚本或命令 你可以编写一个脚本放在config/scripts目录下然后通过status字段调用。脚本返回0表示健康非0表示异常。创建config/scripts/check_mysql.sh#!/bin/bash # 检查MySQL是否可连接 mysqladmin -h 192.168.1.101 -u monitor -ppassword ping /dev/null 21 exit $?记得给脚本执行权限chmod x config/scripts/check_mysql.sh在服务配置中引用- MySQL Database: ... status: command: /app/config/scripts/check_mysql.sh icon: fas fa-database避坑指南状态检测命令是在Homepage的Docker容器内执行的。因此你的脚本必须使用容器内可用的命令如curl,wget,nc,pg_isready等。如果需要mysqladmin你可能需要在构建自定义镜像时安装它或者使用一个更通用的HTTP健康检查端点。5.4 备份与迁移策略你的所有心血都在config目录下的YAML文件里。备份和迁移变得极其简单。备份# 直接打包整个配置目录 cd ~/homepage-docker tar -czf homepage-backup-$(date %Y%m%d).tar.gz config/ # 这个压缩包包含了你的所有设置、图标和自定义脚本。迁移到新服务器在新服务器上安装Docker和Docker Compose。将备份的homepage-backup-*.tar.gz上传到新服务器。解压备份并确保目录结构一致。mkdir -p ~/homepage-docker cd ~/homepage-docker tar -xzf /path/to/homepage-backup-*.tar.gz将原来的docker-compose.yml文件也拷贝过来。运行docker compose up -d。如果域名或IP变了记得更新NPM等反向代理的配置。整个过程可以在几分钟内完成实现导航页的“无缝搬家”。这也是我强烈推荐Docker Compose方案的原因——基础设施即代码配置即资产。6. 常见问题与故障排查实录即使按照步骤操作也可能会遇到一些问题。这里记录了我自己和社区里常见的一些“坑”及其解决方案。6.1 部署启动问题问题1容器启动后立即退出日志显示权限错误。现象docker compose logs显示Permission denied或EACCES。原因最常见的是挂载的config目录权限不足容器内用户UID1000无法写入。解决# 确保 config 目录存在且权限正确 cd ~/homepage-docker sudo chown -R 1000:1000 config/ sudo chmod -R 755 config/ # 然后重启容器 docker compose down docker compose up -d问题2访问页面显示 “Cannot GET /config” 或空白页。现象能打开页面但看不到内容浏览器控制台有404错误。原因config目录是空的或者关键的settings.yaml文件不存在。解决检查config目录下是否有YAML配置文件。至少需要创建一个settings.yaml即使是空的和services.yaml。重启容器后Homepage会基于这些文件渲染页面。问题3Docker状态小组件显示 “Cannot connect to Docker”。现象Widgets里Docker状态一片红或者提示连接失败。原因/var/run/docker.sock没有正确挂载或者其权限问题。解决检查docker-compose.yml中的 volumes 部分是否包含- /var/run/docker.sock:/var/run/docker.sock。检查宿主机上该文件的权限ls -la /var/run/docker.sock。通常属于root:docker组。确保运行Homepage容器的用户PUID1000在docker组内。可以将PUID/PGID设置为0root不推荐仅作测试或者将用户加入docker组后重建容器。6.2 配置与显示问题问题4修改了YAML文件但页面没有变化。原因Homepage默认会缓存配置。浏览器也可能有缓存。解决重启容器这是最彻底的方式docker compose restart homepage。强制刷新浏览器按CtrlF5或CmdShiftR。检查YAML语法YAML对缩进非常敏感。可以使用在线YAML校验器如yamlchecker.com检查文件格式。一个常见的错误是使用Tab缩进必须使用空格。问题5自定义图标不显示显示为破碎图片。原因图标文件路径错误或者文件格式不被浏览器支持。解决确认图标文件已放在config/www/assets/目录下。在services.yaml中图标路径应为./assets/your-icon.png注意开头是.。推荐使用SVG格式图标体积小且缩放不失真。对于PNG确保尺寸不要过大建议64x64或128x128像素。检查浏览器控制台F12 - Console是否有404错误确认请求的图片路径是否正确。问题6资源监控小组件不显示CPU温度或磁盘信息。原因容器内无法读取宿主机相应的系统文件。解决确保docker-compose.yml中已经挂载了/proc,/sys,/sys/class/hwmon等目录见4.3节。对于温度监控宿主机可能需要安装lm-sensors并运行sensors-detect来启用传感器。sudo apt install lm-sensors sudo sensors-detect # 全部按回车选yes即可 sudo service kmod start温度传感器路径可能不同。可以进入容器内部查找docker exec -it homepage sh # 在容器内 find /sys -name temp*_input 2/dev/null找到类似/sys/class/hwmon/hwmon0/temp1_input的路径然后在widgets.yaml的resources部分指定hwmonPath: /sys/class/hwmon/hwmon0。6.3 性能与安全优化问题7页面加载速度慢尤其是图标多的时候。优化方案图标本地化不要大量使用外部CDN的图标链接尽量下载到本地assets目录。这能显著提升加载速度和稳定性。启用浏览器缓存在反向代理如NPM中为Homepage的静态资源/img/*,/assets/*设置较长的缓存时间。精简服务数量如果卡片过多考虑分组折叠或分页。Homepage本身非常轻量瓶颈通常在网络和图标加载上。问题8挂载docker.sock的安全顾虑。风险容器内拥有docker.sock的写权限等同于拥有宿主机的root权限。如果Homepage应用存在漏洞可能被利用。缓解措施使用只读挂载- /var/run/docker.sock:/var/run/docker.sock:ro。这样Homepage只能读取容器状态无法控制。使用Docker API over TCP with TLS这是更安全但更复杂的方式。在宿主机上配置Docker守护进程监听受TLS保护的TCP端口然后Homepage通过证书连接。这需要生成CA和客户端证书。定期更新保持Homepage镜像为最新版本以获取安全补丁。网络隔离将Homepage容器放在一个独立的Docker网络中仅允许其与反向代理通信限制其网络访问能力。问题9如何更新Homepage到最新版本方法使用Docker Compose更新非常简单。cd ~/homepage-docker # 拉取最新镜像 docker compose pull homepage # 重启服务 docker compose up -d --force-recreate homepage # 清理旧镜像 docker image prune -f建议在更新前备份你的config目录。部署和配置Homepage的过程就像在精心布置一个数字世界的家。从最初的空旷到逐渐填满各种服务卡片和信息小组件每一次修改都能立刻在页面上得到反馈这种即时成就感是驱动我们不断优化的动力。它不仅仅是一个导航页更是你个人技术栈的“地图”和“控制台”。当你把所有散落的服务聚合在一处并赋予它们状态和美感时那种对自有数字资产的掌控感和秩序感是使用任何现成云服务都无法替代的。