Homepage · 现代化、可高度定制的自托管应用仪表盘 · 中文部署与使用全指南

项目仓库： https://github.com/gethomepage/homepage

开源协议：GPL-3.0（以仓库 LICENSE 为准） · 技术栈：Next.js · 镜像：ghcr.io/gethomepage/homepage:latest · 架构：AMD64 / ARM64 · 默认端口：3000 · 配置：YAML 文件 / Docker labels 自动发现

1 项目简介

Homepage（仓库名 gethomepage/homepage）是一个现代、快速、安全、完全代理化、高度可定制的应用仪表盘，集成 100+ 服务、支持 40+ 语言，通过 YAML 文件或 Docker label 自动发现来配置。它是你每天开始的理想首页。

安全提示：Homepage 的 widget 会访问你的个人信息（如家庭自动化系统）。若从不可信网络可达，必须放在带鉴权、TLS、严格校验 Host 头的反向代理 / VPN 后面；可选内置 OIDC 登录或简单密码登录（opt-in）。

1.1 核心信息一览

1.2 适用场景

• 想把自托管服务（Radarr、Sonarr、Plex、Jellyfin、qBittorrent 等）聚合到一个首页。
• 需要天气、时钟、搜索、书签等信息小部件。
• 想用 YAML 或 Docker labels 自动发现服务，不想手写大量配置。

1.3 能力边界（官方口径）

• 所有后端 API 请求都经 Homepage 代理，隐藏 API key。
• 从不可信网络可达时必须放鉴权反向代理后。

2 功能特性

• 快：缓存仪表盘数据、优化资源。
• 安全：API 请求代理化，隐藏密钥。
• Docker 集成：容器状态与统计，按 labels 自动发现服务。
• 100+ 服务集成：*arr 全家桶、Plex、Jellyfin、qBittorrent、Transmission 等。
• 信息小部件：天气、时间、日期、搜索、glances。
• 高度定制：自定义主题、CSS/JS、布局、本地化。
• 全 i18n（40+ 语言）。

3 官方界面预览

封面为 Homepage 官方横幅。界面在 http://localhost:3000。

4 官方跳转链接汇总

5 前置要求

• Docker（推荐）。
• 准备好配置目录（挂载到 /app/config）。

6 方式一：Docker Compose 部署（官方）

services:
  homepage:
    image: ghcr.io/gethomepage/homepage:latest
    container_name: homepage
    environment:
      HOMEPAGE_ALLOWED_HOSTS: gethomepage.dev   # 必填，按你的域名改
      PUID: 1000      # 可选
      PGID: 1000      # 可选
    ports:
      - 3000:3000
    volumes:
      - /path/to/config:/app/config        # 本地配置目录需存在
      - /var/run/docker.sock:/var/run/docker.sock:ro   # 可选，Docker 集成
    restart: unless-stopped

等价 docker run：

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

7 方式二：源码运行

git clone https://github.com/gethomepage/homepage.git
cd homepage
pnpm install
pnpm build
# 首次：把 src/skeleton 复制到 config/ 作为初始示例配置
HOMEPAGE_ALLOWED_HOSTS=gethomepage.dev:1234 pnpm start

8 配置项说明

• HOMEPAGE_ALLOWED_HOSTS：必填，允许访问的 Host（含端口），防止 Host 头攻击。
• PUID / PGID：文件归属。
• 配置目录 /app/config 下放 YAML（services、widgets、settings 等）。
• Docker label 自动发现：在容器 labels 里标注 Homepage 元信息。

9 常用运维命令

docker logs -f homepage
docker restart homepage
docker pull ghcr.io/gethomepage/homepage:latest && docker rm -f homepage && docker run ...

10 常见故障排查

• Host 头报错 / 白屏：确认 HOMEPAGE_ALLOWED_HOSTS 含你的访问域名和端口。
• Docker 集成不显示：确认只读挂载了 /var/run/docker.sock。
• 配置不生效：检查 YAML 缩进，查官方 troubleshooting。
• 从公网能访问但无鉴权：必须放反向代理鉴权后，或开启内置 OIDC / 密码登录。

11 风险与合规说明

• 开源许可；Homepage widget 会访问你的内部服务 API，暴露个人信息，公网可达务必反向代理鉴权 + TLS。
• API key 经 Homepage 代理，配置文件含 key，注意目录权限。
• 本文命令、端口、环境变量来自官方 README 与文档，随版本可能调整，以 gethomepage.dev 为准。