🚀 使用 Docker Compose 部署 Heimdall

🚀 使用 Docker Compose 部署 Heimdall

本文是一篇关于使用 Docker Compose 部署 Heimdall 的详尽教程，旨在帮助您，特别是新手用户，轻松掌握这款现代化、开源的个人导航页面的部署和使用。

📝 项目简介

Heimdall 是一个优雅的应用程序仪表板和启动器，旨在帮助您通过一个简洁的网页来组织和管理所有常用的网站与 Web 应用程序链接。您可以把它看作是一个高度可定制的浏览器首页，让你告别杂乱的书签栏。

核心特点：

• 简洁直观：通过清晰的图标和布局展示所有应用，避免在众多书签中迷失。
• 高度可定制：支持添加任意网页链接，并可以自定义图标、名称和排序。
• 集成搜索：内置搜索栏，支持使用 Google、Bing 或 DuckDuckGo 进行搜索。
• 多语言支持：新版本已支持中文界面，同时也提供了手动汉化的可能性。
• 跨平台：基于 Docker，可以在多种硬件架构（如 x86-64、arm64）上运行。

🔧 部署前准备

在开始部署之前，请确保您的环境满足以下要求，并完成必要的准备工作。

系统环境要求

• 操作系统：支持 Linux、Windows、macOS 等主流操作系统。
• Docker 引擎：确保已安装 Docker 服务。
• Docker Compose：确保已安装 Docker Compose。
• 硬件架构：支持 x86-64、arm64、armhf 等多种硬件平台。
• 防火墙端口：确保计划使用的端口（如教程中的 40049 和 40050）在防火墙中是放行的。

环境检查

1. 检查 Docker 服务状态： bash systemctl status docker 确保 Docker 服务处于 active (running) 状态。

2. 检查 Docker Compose 版本： bash docker compose version 确认版本可用。

创建部署目录

建议创建一个独立的目录来管理您的 Heimdall 部署文件和数据：

mkdir -p /home/compose/heimdall && cd /home/compose/heimdall

此目录将作为您的工作目录，后续的 docker-compose.yml 文件将放置于此。

⚙️ 配置 Docker Compose

接下来，我们需要创建 Docker Compose 配置文件。根据您提供的配置，以下是一个详细的解释和说明。

配置文件详解

在您的工作目录（例如 /home/compose/heimdall）下，创建一个名为 docker-compose.yml 的文件。

基本的配置文件内容如下，它定义了一个使用官方 Heimdall 镜像的服务：

#name: <name>   #name: heimdall-docker
services:
    heimdall:
        container_name: heimdall  # 容器名称，便于管理（如停止/查看日志）
        restart: always  # 容器退出后自动重启（保障服务稳定，也可改为 unless-stopped）#restart: unless-stopped  
        #ports:
            #- 181:80   # HTTP 端口映射：主机 40049 → 容器 80（主要访问端口）
            #- 442:443
        ports:
            - 40049:80   # HTTP 端口映射：主机 40049 → 容器 80（主要访问端口）
            - 40050:443  # HTTPS 端口映射：主机 40050 → 容器 443（如需加密可启用）
        volumes:
            - ./config:/config  # 核心挂载：配置文件持久化（必须！否则重启丢失设置）
            # 可选：语言文件挂载（用于汉化，需手动准备文件，参考注释说明）
            #- ./lang:/var/www/localhost/heimdall/resources/lang/ 
            #比如说我要替换的德语文件夹的目录就是 /var/www/localhost/heimdall/resources/lang/de/ ，这个目录下就一个文件——app.php，直接用notepad编辑进行汉化即可。

            #如果准备自行汉化的同学，建议把该路径下的英文语言包下载下来进行汉化，然后再替换其他语言的语言包，如下图是原版的英文语言包：
            #文章的链接地址：https://post.smzdm.com/p/a99v2nqo/
            #覆盖后不用重启，直接在主页中切换语言为Deutsch(German)，就变成中文UI了。
            #可以看到还有些许瑕疵，不过不要紧啦，基本上已经可以接受了。

        environment:
            - PUID=1000  # 运行容器的用户 ID（通常为 1000，与宿主机当前用户一致）
            - PGID=1000  # 运行容器的用户组 ID（同上，保持与 PUID 一致）
            #- TZ=Europe/London
            - TZ=Etc/UTC  # 时区设置（可改为 Asia/Shanghai 同步北京时间）
        #network_mode: 'host'   #默认用自带原先的端口，应该是这意思。
        #privileged: true  #特权:真
        #image: linuxserver/heimdall:amd64-latest
        image: lscr.io/linuxserver/heimdall:latest  # 官方最新镜像（自动更新）



#.env推荐的配置
#PANEL_APP_PORT_HTTP=40049
#PANEL_APP_PORT_HTTPS=40050
#TIME_ZONE="Asia/Shanghai"

为了更灵活地管理配置，您还可以创建一个 .env 文件来设置环境变量。这样做的好处是，如果需要修改端口等配置，只需更改 .env 文件而无需触动主要的 docker-compose.yml 文件。

.env 文件示例：

# 自定义 HTTP 和 HTTPS 端口
PANEL_APP_PORT_HTTP=40049
PANEL_APP_PORT_HTTPS=40050

# 设置时区为上海
TIME_ZONE="Asia/Shanghai"

修改 docker-compose.yml 以使用 .env 变量：

name: heimdall-docker

services:
    heimdall:
        container_name: heimdall
        restart: always
        ports:
            - "${PANEL_APP_PORT_HTTP:-40049}:80"    # 使用环境变量定义 HTTP 端口
            - "${PANEL_APP_PORT_HTTPS:-40050}:443"  # 使用环境变量定义 HTTPS 端口
        volumes:
            - ./config:/config
        environment:
            - PUID=1000
            - PGID=1000
            - TZ=${TIME_ZONE:-Etc/UTC}  # 使用环境变量定义时区，默认为 UTC
        image: lscr.io/linuxserver/heimdall:latest

关键配置说明

1. 镜像选择 (image):

   • 使用 lscr.io/linuxserver/heimdall:latest 可以获取最新的稳定版本。
   • 如果需要特定架构的版本（例如在树莓派等ARM设备上），可以使用 linuxserver/heimdall:latest，Docker 通常会自动选择匹配的版本。

2. 端口映射 (ports):

   • 40049:80: 将容器的 80 端口（HTTP）映射到宿主机的 40049 端口，您可以通过 http://<服务器IP>:40049 访问。
   • 40050:443: 将容器的 443 端口（HTTPS）映射到宿主机的 40050 端口。
   • 您可以根据需要修改冒号左侧的宿主机端口，确保它们不与系统其他服务冲突。

3. 数据持久化 (volumes):

   • ./config:/config: 将容器内的 /config 目录挂载到宿主机的 ./config 目录。这确保了您的 Heimdall 配置、上传的图标等在容器重建后不会丢失。

4. 环境变量 (environment):

   • PUID 和 PGID: 用于设置容器内运行进程的用户和组ID，这关系到挂载卷的文件权限。通常设置为当前宿主机用户的 UID 和 GID。
   • TZ: 设置容器的时区，确保日志和时间显示正确。在 .env 文件中我们已设置为 Asia/Shanghai。

5. 重启策略 (restart: always):

   • 设置为 always 意味着如果 Docker 守护进程启动时容器停止运行（例如系统重启），Docker 会自动启动该容器，确保服务高可用。

🚀 启动与验证

配置完成后，就可以启动 Heimdall 服务了。

启动服务

在包含 docker-compose.yml 文件的目录下，执行以下命令来启动服务：

docker compose up -d

参数 -d 表示在后台运行容器。

验证服务状态

1. 检查容器状态： 执行 docker ps 命令，查看名为 heimdall 的容器状态是否为 Up。

2. 查看服务日志（可选）： 如果无法访问，可以通过 docker compose logs 或 docker logs heimdall 查看容器日志以排查问题。

3. 访问 Heimdall 管理界面：

   • 在浏览器中输入 http://您的服务器IP地址:40049。
   • 如果一切正常，您将看到 Heimdall 的初始界面。

🔌 基础配置与使用

成功访问 Heimdall 后，您将看到一个直观的 Web 管理界面。

初始界面与语言设置

1. 设置中文界面：

   • 新版本的 Heimdall 已支持官方中文。点击界面右下角的设置图标（齿轮）。
   • 在 Language 选项中选择 Zh (Chinese)。
   • 点击 Save 保存设置，界面将刷新为中文。

2. 手动汉化（备用方案）：

   • 如果您的版本暂无官方中文，可以参考社区提供的手动汉化方法。
   • 根据配置中的注释，您可以挂载语言包目录，并用汉化后的文件覆盖对应语言（如德语）的文件，然后在界面中选择该语言即可显示中文。
   • 此方法涉及文件操作，建议新手优先选择使用内置官方中文的镜像版本。

添加应用程序链接

1. 点击界面上的 "+" 号 开始添加新的应用链接。
2. 选择应用类型：
   • 预定义应用：Heimdall 内置了大量常见应用（如 AdGuard Home、Nextcloud 等）的图标和配置模板。
   • 自定义应用：您可以添加任何网页链接，并手动上传图标、设置名称和颜色。
3. 填写详细信息：包括应用名称、URL、图标颜色以及上传自定义图标（如果需要）。
4. 保存：保存后，新的应用图标就会出现在您的主仪表板上。

界面个性化

• 拖拽排序：您可以随时通过拖拽应用图标来调整它们在页面上的位置。
• 更改布局：在设置中，您可以调整图标的间距、大小等，让界面更符合您的审美和使用习惯。
• 设置为主页：将 Heimdall 设置为您的浏览器主页，这样每次打开浏览器就能快速访问所有常用服务。

🛠️ 维护与管理

日常维护

• 服务启停： ```bash # 停止服务 docker compose down

# 启动服务 docker compose up -d

# 重启服务 docker compose restart ```

• 数据备份： 定期备份工作目录下的 config 文件夹。这个文件夹包含了 Heimdall 的所有配置和上传的图标。 bash tar -czf heimdall-backup-$(date +%Y%m%d).tar.gz ./config

• 服务更新： 要更新到最新版本的 Heimdall，请在部署目录下执行： bash docker compose pull # 拉取最新镜像 docker compose down # 停止当前容器 docker compose up -d # 用新镜像重新启动容器 注意：保持容器版本更新有时能解决一些预料之外的问题。

监控与日志

• 查看实时日志： bash docker compose logs -f heimdall

• 进入容器（用于高级调试）： bash docker exec -it heimdall /bin/bash

• 查看版本信息： bash docker inspect -f '{{ index .Config.Labels "build_version" }}' heimdall

🐛 常见问题排查

在使用过程中，可能会遇到一些问题，以下是一些常见问题的排查思路：

1. 无法通过浏览器访问 Heimdall

   • 检查防火墙：确认服务器安全组和防火墙是否放行了您配置的端口（例如 40049 和 40050）。
   • 检查容器状态：使用 docker ps 确认 Heimdall 容器是否正常运行。如果状态异常，使用 docker logs heimdall 查看错误日志。
   • 确认端口占用：检查宿主机端口是否被其他进程占用。可以尝试更换 docker-compose.yml 中的宿主机端口。

2. 添加应用时出现 500 服务器错误

   • 此问题可能出现在特定版本的 Heimdall 中，尤其是在添加预定义应用时。
   • 解决方案：尝试将容器更新到最新版本，这通常能解决问题。如果问题依旧，可以暂时使用"自定义应用"方式手动添加链接。

3. 界面访问缓慢或异常

   • 此类问题可能与前端存储访问错误或数据损坏有关。
   • 解决方案：可以尝试清除浏览器缓存。如果问题持续，可以考虑通过停止容器后，删除 ./config 目录下除 www 子目录（可能包含核心应用数据）外的其他内容，然后重启容器来重置部分配置。

4. 应用图标不显示或配置丢失

   • 检查文件权限：确保宿主机上 ./config 目录对于容器内进程（由 PUID/PGID 指定）是可读可写的。在某些情况下，错误权限会导致配置保存失败。
   • 验证数据持久化：确认 volumes 挂载正确，且磁盘空间充足。

---

希望这篇教程能帮助您顺利完成 Heimdall 的部署和使用。作为一款简洁高效的个人导航工具，Heimdall 能显著提升您访问和管理网络应用的效率。如果在使用中遇到更复杂的问题，可以参考 Heimdall 项目的官方文档或在相关技术社区寻求帮助。