Homepage 仪表板首页搭建教程

当你在搬瓦工 VPS 上部署了越来越多的自托管服务后，一个统一的仪表板首页就变得非常必要。Homepage 是一款现代化的开源服务器仪表板，界面美观、配置简单，支持丰富的服务集成和小组件。本文将介绍如何在搬瓦工 VPS 上部署 Homepage 并配置各种服务的集成。

一、Homepage 功能特点

• 美观界面：现代化设计，支持明暗主题切换和自定义背景。
• 服务集成：内置 200+ 服务集成，可以显示各服务的实时状态和统计数据。
• 系统信息：显示 CPU、内存、磁盘使用率等系统资源信息。
• Docker 集成：自动发现 Docker 容器并显示运行状态。
• 书签管理：可以添加常用网站书签，快速访问。
• 搜索功能：内置搜索框，支持多种搜索引擎。
• 天气小组件：可以显示当地天气信息。
• YAML 配置：通过 YAML 文件配置，简单直观。

二、环境准备

• 搬瓦工 VPS 一台，512MB 内存即可（使用优惠码 NODESEEK2026 享受 6.77% 折扣）。
• 已安装 Docker 和 Docker Compose（参考 Docker 安装教程）。

2.1 创建项目目录

mkdir -p /opt/homepage/config
cd /opt/homepage

三、Docker Compose 部署

cat > /opt/homepage/docker-compose.yml <<'EOF'
version: '3.8'

services:
  homepage:
    image: ghcr.io/gethomepage/homepage:latest
    restart: always
    ports:
      - "3000:3000"
    volumes:
      - /opt/homepage/config:/app/config
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      PUID: 1000
      PGID: 1000
EOF

挂载 Docker socket 是为了让 Homepage 自动发现运行中的容器。

四、配置服务

4.1 服务配置（services.yaml）

cat > /opt/homepage/config/services.yaml <<'EOF'
- 云服务:
    - Nextcloud:
        href: https://cloud.yourdomain.com
        description: 私有云盘
        icon: nextcloud
        server: my-docker
        container: nextcloud

    - Gitea:
        href: https://git.yourdomain.com
        description: 代码仓库
        icon: gitea
        server: my-docker
        container: gitea

- 开发工具:
    - Code Server:
        href: https://code.yourdomain.com
        description: 在线 VS Code
        icon: vscode
        server: my-docker
        container: code-server

    - IT-Tools:
        href: https://tools.yourdomain.com
        description: 开发者工具箱
        icon: it-tools

- 监控:
    - Uptime Kuma:
        href: https://status.yourdomain.com
        description: 服务监控
        icon: uptime-kuma
        server: my-docker
        container: uptime-kuma
EOF

4.2 书签配置（bookmarks.yaml）

cat > /opt/homepage/config/bookmarks.yaml <<'EOF'
- 常用网站:
    - GitHub:
        - abbr: GH
          href: https://github.com
    - 搬瓦工:
        - abbr: BW
          href: https://bwh81.net/aff.php?aff=74585

- 技术文档:
    - Docker Docs:
        - abbr: DK
          href: https://docs.docker.com
    - Nginx Docs:
        - abbr: NX
          href: https://nginx.org/en/docs/
EOF

4.3 小组件配置（widgets.yaml）

cat > /opt/homepage/config/widgets.yaml <<'EOF'
- resources:
    cpu: true
    memory: true
    disk: /

- search:
    provider: google
    target: _blank

- datetime:
    text_size: xl
    format:
      dateStyle: long
      timeStyle: short
      hour12: false
EOF

4.4 Docker 集成配置（docker.yaml）

cat > /opt/homepage/config/docker.yaml <<'EOF'
my-docker:
  socket: /var/run/docker.sock
EOF

五、启动 Homepage

cd /opt/homepage
docker compose up -d

访问 http://VPS_IP:3000 查看效果。

六、配置反向代理

cat > /etc/nginx/sites-available/homepage <<'EOF'
server {
    listen 80;
    server_name home.yourdomain.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
EOF

ln -sf /etc/nginx/sites-available/homepage /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx
certbot --nginx -d home.yourdomain.com

七、高级配置

7.1 自定义主题和背景

cat > /opt/homepage/config/settings.yaml <<'EOF'
title: My Server Dashboard
theme: dark
color: slate
background:
  image: https://images.unsplash.com/photo-xxx
  blur: sm
  opacity: 50
headerStyle: boxed
layout:
  云服务:
    style: row
    columns: 3
  开发工具:
    style: row
    columns: 2
EOF

7.2 服务状态小组件

Homepage 支持通过 API 获取各服务的实时数据。例如配置 Nextcloud 的存储使用量显示：

- Nextcloud:
    href: https://cloud.yourdomain.com
    icon: nextcloud
    widget:
      type: nextcloud
      url: https://cloud.yourdomain.com
      username: admin
      password: your_password

八、版本更新

cd /opt/homepage
docker compose pull
docker compose up -d
docker image prune -f

九、常见问题

Docker 容器状态不显示

确认 Docker socket 已正确挂载，并且 docker.yaml 配置正确。

配置修改不生效

Homepage 会自动监听配置文件变化，但有时需要重启容器才能生效：

docker compose restart

总结

Homepage 是一个优秀的服务器仪表板工具，可以将你在搬瓦工 VPS 上部署的所有服务集中展示在一个美观的页面上。搭配 Flame 书签管理器 或 IT-Tools 工具箱 使用效果更佳。选购搬瓦工 VPS 请访问 bwh81.net，使用优惠码 NODESEEK2026 享受 6.77% 折扣。