pierrezemb/gostatic

goStatic 

镜像概述和主要用途

goStatic是一个超轻量级的Docker静态Web服务器镜像，旨在为静态文件提供最小化的容器解决方案。利用Go语言生成完全静态二进制文件的特性，该镜像无需额外依赖，可高效托管HTML、CSS、JavaScript等静态资源。

核心功能和特性

• 极致轻量：仅6MB大小的完全静态Web服务器
• 无框架设计：纯Go实现，不依赖任何Web框架
• Docker优化：专为容器环境构建，适配各类容器化部署场景
• 安全增强：相比官方镜像更安全（详见下方说明）
• 日志支持：可启用请求日志记录
• 自定义响应头：支持按路径和文件类型配置自定义响应头(详情)
• 健康检查：提供健康检查端点，适用于Kubernetes等编排平台

为什么选择goStatic

官方Golang镜像体积过大（约1/2GB，见下方镜像大小徽章）且可能存在安全隐患，而容器化的核心价值之一就是轻量级。以下资源可进一步说明这一理念：

• 超过30%的Docker Hub官方镜像存在高优先级安全漏洞
• 创建最小可能的Docker容器
• 为静态Go二进制文件构建Docker镜像
• Go应用的小型Docker镜像

注意：已移除不安全HTTPS支持。如需HTTPS，推荐使用caddy配合Let's Encrypt实现自动HTTPS。

使用场景和适用范围

• 静态网站托管（个人博客、企业官网等）
• 单页应用（SPA）部署，支持前端路由回退
• 轻量级静态资源服务（文档、图片、下载文件等）
• Kubernetes、OpenFaas等容器编排平台的静态资源服务

使用方法和配置说明

基本部署示例

bash
docker run -d -p 80:8043 -v /path/to/website:/srv/http --name goStatic pierrezemb/gostatic

命令参数说明

通过./goStatic --help可查看所有配置参数：

Usage of ./goStatic:
  -append-header HeaderName:Value
        HTTP响应头，格式为HeaderName:Value，将添加到所有响应中。
  -context string
        提供文件服务的"上下文"路径，例如'doc'将在'http://localhost:<port>/doc/'提供文件
  -default-user-basic-auth string
        定义默认用户（默认"gopher"）
  -enable-basic-auth
        启用基本认证。默认情况下，密码随机生成。使用--set-basic-auth设置密码。
  -enable-health
        启用健康检查端点。可访问/health获取200响应。适用于Kubernetes、OpenFaas等。
  -enable-logging
        启用请求日志
  -fallback string
        默认回退文件。可以是绝对路径（/index.html）指向特定资源，或相对路径（index.html）递归查找
  -header-config-path string
        自定义响应头配置文件路径（默认"/config/headerConfig.json"）
  -https-promote
        将所有HTTP请求重定向到HTTPS
  -password-length int
        随机密码长度（默认16）
  -path string
        静态文件路径（默认"/srv/http"）
  -port int
        监听端口（默认8043）
  -set-basic-auth string
        定义基本认证信息。格式必须为user:password

Fallback（回退）功能详解

Fallback选项专为单页应用（SPA）设计，解决前端路由路径与实际文件路径不匹配的问题，支持两种使用方式：

1. 绝对路径模式：所有未找到的请求都解析到同一个指定文件（如-fallback /index.html）
2. 相对路径模式：在请求路径的目录树中向上递归搜索指定文件（如-fallback index.html）

第二种方式适用于同一文件系统中存在多个SPA的场景（例如根目录/和管理后台/admin各有独立SPA）。