awesometic/h5ai

docker-h5ai

镜像概述和主要用途

h5ai是一款现代HTTP Web服务器文件索引器，专注于文件展示，通过多种视图、面包屑导航和树形概览增强目录浏览体验。本Docker镜像基于Alpine Linux构建，集成Nginx、PHP和h5ai，旨在为Docker用户提供轻量级、功能完整的文件索引服务。

核心功能和特性

核心组件

• 基础镜像：Alpine Linux 3.14（轻量级设计）
• Web服务：Nginx 1.21.1
• 运行环境：PHP 8.0.8（默认启用JIT编译器）
• 核心应用：h5ai 0.30.0
• 进程管理：Supervisor（统一管理所有服务进程）

功能特点

• 全功能启用：支持音频/视频缩略图显示、缓存优化等h5ai扩展功能
• PHP 8 JIT加速：默认启用PHP 8引入的JIT编译器，提升性能
• 多架构支持：通过GitHub Actions构建，支持AMD64(x86_64)、ARM64、ARMv7、ARMv6架构

使用场景和适用范围

• 个人文件共享服务器
• 本地/局域网文件索引服务
• 轻量级Web文件浏览器
• 开发/测试环境的文件管理工具

详细使用方法和配置说明

前提条件

已在系统中安装Docker

拉取镜像

bash
docker pull awesometic/h5ai

基本用法

临时测试运行

bash
docker run -it --rm \
-p 80:80 \
-v /shared/dir:/h5ai \
-v /config/dir:/config \
-e PUID=$UID \
-e PGID=$GID \
-e TZ=Asia/Seoul \
awesometic/h5ai

--rm选项会在容器停止后自动删除容器，适用于测试场景

作为后台服务运行

bash
docker run -d --name=h5ai \
-p 80:80 \
-v /shared/dir:/h5ai \
-v /config/dir:/config \
-e PUID=$UID \
-e PGID=$GID \
-e TZ=Asia/Seoul \
awesometic/h5ai

开机自启动

bash
docker run -d --name=h5ai \
-p 80:80 \
-v /shared/dir:/h5ai \
-v /config/dir:/config \
-e PUID=$UID \
-e PGID=$GID \
-e TZ=Asia/Seoul \
--restart unless-stopped \
awesometic/h5ai

目录挂载说明

• /h5ai：共享文件存放目录（需映射到宿主机目录）
• /config：h5ai和Nginx配置文件存放目录（需映射到宿主机目录）

环境变量说明

• PUID：进程用户ID（默认911）
• PGID：进程组ID（默认911）
• TZ：时区设置（如Asia/Seoul）
• HTPASSWD：是否启用基本认证（设为true启用）
• HTPASSWD_USER：认证用户名
• HTPASSWD_PW：认证密码（非交互模式下设置）

访问控制设置

启用基本认证以防止***访问：

交互模式（首次设置密码）

bash
docker run -it --name=h5ai \
-p 80:80 \
-v /shared/dir:/h5ai \
-v /config/dir:/config \
-e PUID=$UID \
-e PGID=$GID \
-e TZ=Asia/Seoul \
-e HTPASSWD=true \
-e HTPASSWD_USER=awesometic \
awesometic/h5ai

运行后需按提示输入密码

非交互模式（直接设置密码）

bash
docker run -d --name=h5ai \
-p 80:80 \
-v /shared/dir:/h5ai \
-v /config/dir:/config \
-e PUID=$UID \
-e PGID=$GID \
-e TZ=Asia/Seoul \
-e HTPASSWD=true \
-e HTPASSWD_USER=awesometic \
-e HTPASSWD_PW=yourpassword \
--restart unless-stopped \
awesometic/h5ai

访问服务

容器运行后，通过浏览器访问：

http
http://localhost/

更新注意事项

当h5ai版本更新时，镜像会覆盖部分配置文件。建议在更新前备份自定义配置。系统会自动备份旧版options.json文件（位于/config目录下，命名格式如YYYYMMDD_HHMMSS_options.json.bak），但其他自定义文件需手动备份。

HTTPS配置

本镜像未内置HTTPS支持，建议通过反向代理实现HTTPS，推荐使用https://hub.docker.com/r/linuxserver/swag%E3%80%82

TODO

• 简化options.json配置访问
• 支持htpasswd访问控制
• 支持PUID/PGID权限设置
• 将Nginx和PHP日志暴露到宿主机

许可证

本项目采用MIT许可证，详见https://github.com/awesometic/docker-h5ai/blob/master/LICENSE%E3%80%82

注意：本文档内容可能过时，请访问https://github.com/awesometic/docker-h5ai%E8%8E%B7%E5%8F%96%E6%9C%80%E6%96%B0%E4%BF%A1%E6%81%AF%E3%80%82