用 Homepage 整理自己部署的应用入口

笔记、书签、监控和面板的地址不好记，可以用 Homepage 放在一个页面里，按用途分组。已有机器通常就能部署。它只整理链接，不会替你登录或保护被链接的应用。

这篇先建立一个通过 SSH 访问的私人导航页，再考虑域名和状态组件。这样即使暂时没配好代理，内部地址和组件凭据也不会先暴露在公网。

先通过 SSH 转发安装

准备一台已安装 Docker Engine 与 Compose 插件的 Linux 服务器。下面把应用放在 /opt/homepage，宿主机使用 3100 端口，容器内部仍为 3000。账户需要有 Docker 权限；创建 /opt 下的目录时使用有相应权限的账户。

sudo mkdir -p /opt/homepage/config
sudo chown "$(id -u):$(id -g)" /opt/homepage/config
cd /opt/homepage
umask 077
printf 'PUID=%s\nPGID=%s\n' "$(id -u)" "$(id -g)" > .env
printf 'AUTH_SECRET=%s\n' "$(openssl rand -hex 32)" >> .env
printf 'AUTH_PASSWORD=%s\n' "$(openssl rand -hex 24)" >> .env
chmod 600 .env

密码保存在 .env，用本机可信编辑器查看并保存到密码管理器，别把整个文件提交到仓库。创建 compose.yaml：

services:
  homepage:
    image: ghcr.io/gethomepage/homepage:latest
    restart: unless-stopped
    ports:
      - "127.0.0.1:3100:3000"
    volumes:
      - ./config:/app/config
    environment:
      PUID: ${PUID:?set PUID}
      PGID: ${PGID:?set PGID}
      HOMEPAGE_ALLOWED_HOSTS: "127.0.0.1:3100,localhost:3100"
      HOMEPAGE_AUTH_ENABLED: "true"
      HOMEPAGE_AUTH_SECRET: ${AUTH_SECRET:?set AUTH_SECRET}
      HOMEPAGE_AUTH_PASSWORD: ${AUTH_PASSWORD:?set AUTH_PASSWORD}
      HOMEPAGE_EXTERNAL_URL: "http://127.0.0.1:3100"

当前 Homepage 提供内置认证；老版本教程中“只能靠外部认证”的说法不能直接沿用。这里启用密码登录，同时限制宿主机监听范围。latest 会变化，首次确认正常后记录镜像摘要，固定为已验证版本或摘要；升级前阅读对应发布说明。

docker compose config --quiet
docker compose pull
docker compose up -d
docker compose logs --tail=80 homepage

在自己的电脑建立转发，再打开 http://127.0.0.1:3100：

ssh -N -L 127.0.0.1:3100:127.0.0.1:3100 user@YOUR_VPS_IP

本机 3100 被占用时，可以改本机转发端口，但 HOMEPAGE_EXTERNAL_URL 和允许的 Host 也要随实际浏览器地址调整。允许的 Host 使用域名及必要端口，多个值逗号分隔，不含空格；它与完整的访问 URL 是两种配置。

链接要用自己的电脑能访问的地址

应用生成配置后，编辑 config/services.yaml。下面是文件结构示例，替换成自己实际可访问的 HTTPS 地址：

- 日常使用:
    - 笔记:
        href: https://notes.example.com/
        description: 项目资料与维护记录
    - 书签:
        href: https://bookmarks.example.com/
        description: 待读资料与常用文档
- 维护:
    - 监控:
        href: https://status.example.com/
        description: 网站响应与故障记录

浏览器点击链接发生在自己的电脑上。写成 http://127.0.0.1:8080，指向的是读者电脑，通常不是 VPS；写容器服务名，电脑也未必能解析。需要 SSH 才能访问的工具，应安排对应转发或 VPN，再填写实际入口。

先检查三个链接、中文描述和手机点击，再加图标和状态组件。组件读取数据通常还需要 URL、凭据以及 Homepage 到后端的网络连通性；“链接能打开”和“组件能读 API”应分开检查。不要把管理员令牌写进可公开下载的配置。

不挂 Docker socket，也能用导航页

本例没有挂载 /var/run/docker.sock。基础导航不需要它；即便挂载后缀写了 :ro，也不能理解成 Docker API 只有查看权限。以后需要容器状态时，先选择受限制的集成方式，再核对它能执行哪些操作。

如果改用公网域名，更新允许的 Host 与 HOMEPAGE_EXTERNAL_URL，后者使用实际 HTTPS 地址。内置密码认证没有应用层的尝试速率限制，公网部署还应在网关设置相应控制。每个被链接的应用仍要保留自己的权限；导航页的密码不会自动覆盖其他服务。

备份配置、密钥和镜像版本

保留 compose.yaml、.env 和整个 config，记录镜像摘要。用受保护的异地副本保存，恢复时先在另一回环端口启动，核对分组、链接、登录和组件权限，再接回正式域名。换机器后内部 IP、网关与组件地址也可能需要修改。

少量链接可以和已有应用放在同一台 VPS 上。准备同时运行笔记、书签和监控时，再按照应用总内存、磁盘增长与备份方式比较小型 Docker 应用的 VPS 选择。只为了收拢几个入口，通常没有必要再买一台服务器。

私人导航只是少量链接时可与已有应用共机；带状态组件、同时运行笔记与数据库时，可以按合计负载比较 2 GB 或 4 GB 内存实例。新手统一管理可查看雨云 RCS 的小应用与面板选项，自行管理可比较 Evoxt 的 Linux 实例。先核对实际访问入口与备份空间，组件凭据和 Docker 权限仍由自己管理，新增机器也不会自动限制这些权限。

先通过 SSH 转发安装

链接要用自己的电脑能访问的地址

不挂 Docker socket，也能用导航页

备份配置、密钥和镜像版本

接着读