一、homepage介绍

1.1 Homepage简介

Homepage 是一个高度可定制的个人主页（或称起始页、应用仪表盘），专为自托管环境设计，支持 Docker 集成与多种服务 API 对接，兼具美观的现代界面与强大功能，帮助用户打造高效、安全、个性化的每日工作与生活入口。

1.2 Homepage主要特点

• 快速加载：网站在构建时静态生成，实现近乎瞬时的页面加载速度。
• 安全可靠：所有后端服务的 API 请求均通过反向代理转发，有效隐藏敏感密钥，防止泄露。
• 多架构支持：提供 AMD64 和 ARM64 架构的 Docker 镜像，适配 x86 和树莓派等设备。
• 全面国际化：支持超过 40 种语言，满足全球用户本地化需求。
• 书签管理：可添加自定义服务链接和网页书签，集中管理常用网站与应用。
• Docker 集成：实时显示容器状态与资源使用情况，支持通过容器标签自动发现服务。
• 服务集成丰富：内置 100+ 服务集成，涵盖 Sonarr、Radarr、Plex、Portainer 等主流自建服务。
• 功能型小部件：提供天气、时钟、日期、快速搜索等实用小工具，提升日常使用效率。
• 现代设计风格：界面简洁优雅，响应式布局，适配桌面与移动设备。
• 高度可定制：支持主题、布局、网格大小、深色模式等多样化个性化设置。

二、本次实践规划

2.1 本地环境规划

本次实践为个人测试环境，操作系统版本为 Ubuntu 24.04.2 LTS。

2.2 本次实践介绍

1.本次实践部署环境为个人测试环境，生产环境请谨慎；
2.在Docker环境下部署homepage个人导航页工具。

三、本地环境检查

3.1 检查Docker服务状态

检查Docker服务是否正常运行，确保Docker正常运行。

root@jeven:~# systemctl status docker
● docker.service - Docker Application Container Engine
     Loaded: loaded (/usr/lib/systemd/system/docker.service; enabled; preset: enabled)
     Active: active (running) since Mon 2025-08-04 10:10:52 UTC; 30min ago
TriggeredBy: ● docker.socket
       Docs: https://docs.docker.com
   Main PID: 860 (dockerd)
      Tasks: 10
     Memory: 97.2M (peak: 98.4M)
        CPU: 606ms
     CGroup: /system.slice/docker.service

3.2 检查Docker版本

检查Docker版本

root@jeven:~# docker -v
Docker version 28.3.3, build 980b856

3.3 检查docker compose 版本

检查Docker compose版本，确保2.0以上版本。

root@jeven:~# docker -v
Docker version 28.3.3, build 980b856

四、拉取homepage镜像

下载homepage容器镜像，如下所示

docker pull ghcr.io/gethomepage/homepage:latest

五、部署homepage服务

5.1 创建部署目录

• 创建部署目录

mkdir -p /data/homepage/config   &&  cd /data/homepage/

5.2 编辑部署文件

使用docker-cli方式部署，可参考以下命令：

docker run --name homepage \
  -e HOMEPAGE_ALLOWED_HOSTS=gethomepage.dev \
  -e PUID=1000 \
  -e PGID=1000 \
  -p 3000:3000 \
  -v /data/homepage/config:/app/config \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  --restart unless-stopped \
  ghcr.io/gethomepage/homepage:latest

在部署目录下，创建docker-compose.yaml文件，内容如下所示：

vim docker-compose.yaml

services:
  homepage:
    image: ghcr.io/gethomepage/homepage:latest
    container_name: homepage
    environment:
      HOMEPAGE_ALLOWED_HOSTS: 192.168.3.88:3000   # required, may need port. See gethomepage.dev/installation/#homepage_allowed_hosts
      PUID: 1000 # optional, your user id
      PGID: 1000 # optional, your group id
    ports:
      - 3000:3000
    volumes:
      - /data/homepage/config:/app/config # Make sure your local config directory exists
      - /var/run/docker.sock:/var/run/docker.sock:ro # optional, for docker integrations
    restart: unless-stopped

5.3 创建homepage容器

执行以下命令，创建homepage容器。

docker compose up -d

5.4 查看homepage容器状态

检查homepage容器运行状态，确保homepage容器正常启动。

root@jeven:/data/homepage# docker compose ps
NAME       IMAGE                                 COMMAND                   SERVICE    CREATED          STATUS                    PORTS
homepage   ghcr.io/gethomepage/homepage:latest   "docker-entrypoint.s…"   homepage   33 seconds ago   Up 33 seconds (healthy)   0.0.0.0:3000->3000/tcp, [::]:3000->3000/tcp

5.5 检查容器运行日志

检查容器运行日志，确保homepage服务正常运行。

docker compose logs

六、访问homepage服务

6.1 访问homepage首页

浏览器地址： http://<个人的服务器IP>:3000，访问homepager的初始页。如果无法访问，请确保宿主机的防火墙已关闭或已放行相关端口，对于云服务器还需配置相应的安全组规则。

6.2 添加书签

在宿主机的/data/homepage/config目录下，修改bookmarks.yaml文件，可添加收藏网址。

vim bookmarks.yaml

root@jeven:/data/homepage/config# cat bookmarks.yaml
---
# For configuration options and examples, please see:
# https://gethomepage.dev/configs/bookmarks

- Developer:
    - Github:
        - abbr: GH
          href: https://github.com/

- Social:
    - Reddit:
        - abbr: RE
          href: https://reddit.com/

- Entertainment:
    - YouTube:
        - abbr: YT
          href: https://youtube.com/
- Search:
    - 必应:
        - abbr: 搜索
          href: https://cn.bing.com/

刷新homepage网页后，可以看到书签已经成功添加。

七、总结

通过本次实践，我们成功使用Docker部署了Homepage个人导航页工具，打造了一个美观且高效的浏览器起始页面。Homepage凭借其静态化加载、丰富的服务集成和高度可定制的界面，显著提升了日常访问常用服务的效率。通过Docker部署，实现了快速安装与便捷维护，同时利用HOMEPAGE_ALLOWED_HOSTS等配置保障了访问安全。Homepage不仅适合作为个人主页，也能轻松扩展为家庭或团队的统一服务入口，是自托管生态中不可或缺的实用工具。