webhippie/errors

errors 镜像文档

镜像概述与主要用途

errors镜像是一个为Kubernetes集群中的Nginx Ingress Controller提供自定义默认页面和错误页面的解决方案。该项目默认内置简洁美观的标准错误页面（如404、500等），同时支持用户根据需求自定义页面内容，适用于需要统一入口页面风格或品牌化错误响应的Kubernetes环境。

核心功能与特性

• 自定义页面支持：允许用户根据业务需求定制默认页面和错误页面内容
• 内置标准错误页面：默认包含常见HTTP错误状态码的简洁页面，无需额外配置即可使用
• 多平台镜像发布：镜像同时发布于GHCR、Docker Hub和Quay，支持多种容器环境
• 轻量级设计：基于Go语言构建，镜像体积小，资源占用低，适合Kubernetes集群部署
• 开发便捷：支持热重载，便于开发阶段快速调试页面样式和功能

使用场景与适用范围

• Kubernetes Ingress默认后端：作为Nginx Ingress Controller的默认后端服务，处理未匹配路由的请求
• 统一错误页面管理：为Kubernetes集群中的所有服务提供一致的错误页面展示
• 品牌化入口页面：自定义默认页面以展示品牌信息或服务说明
• 开发与测试环境：快速部署用于测试Ingress路由和错误响应的场景

详细使用方法与配置说明

获取镜像

该镜像可从以下仓库拉取：

• GHCR：ghcr.io/webhippie/errors:latest
• Docker Hub：webhippie/errors:latest
• Quay：quay.io/webhippie/errors:latest

拉取命令示例：

bash
# 从GHCR拉取最新版
docker pull ghcr.io/webhippie/errors:latest

# 从Docker Hub拉取特定版本
docker pull webhippie/errors:v1.0.0

本地测试

使用以下命令在本地启动容器进行测试：

bash
docker run -d -p 8080:8080 --name errors-demo ghcr.io/webhippie/errors:latest

启动后可通过访问以下地址验证：

• 默认页面：http://localhost:8080
• 404错误页面：http://localhost:8080/404
• 500错误页面：http://localhost:8080/500

Kubernetes部署

1. 部署后端服务

创建Deployment和Service资源清单（errors-backend.yaml）：

yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: errors-backend
  namespace: ingress-nginx
spec:
  replicas: 2
  selector:
    matchLabels:
      app: errors-backend
  template:
    metadata:
      labels:
        app: errors-backend
    spec:
      containers:
      - name: errors
        image: ghcr.io/webhippie/errors:latest
        ports:
        - containerPort: 8080
        resources:
          requests:
            cpu: 10m
            memory: 16Mi
          limits:
            cpu: 100m
            memory: 64Mi
---
apiVersion: v1
kind: Service
metadata:
  name: errors-backend
  namespace: ingress-nginx
spec:
  selector:
    app: errors-backend
  ports:
  - port: 80
    targetPort: 8080

应用部署清单：

bash
kubectl apply -f errors-backend.yaml

2. 配置Nginx Ingress Controller

修改Nginx Ingress Controller的部署配置，设置默认后端服务：

bash
# 假设Ingress Controller部署在ingress-nginx命名空间
kubectl edit deployment nginx-ingress-controller -n ingress-nginx

在spec.template.spec.containers.args中添加或修改：

yaml
- --default-backend-service=ingress-nginx/errors-backend

自定义页面配置

方法1：挂载自定义页面目录

通过ConfigMap或PersistentVolume挂载自定义页面文件到容器的/app/public目录（需根据实际项目结构调整路径）：

yaml
# 在Deployment中添加volume挂载配置
spec:
  containers:
  - name: errors
    image: ghcr.io/webhippie/errors:latest
    volumeMounts:
    - name: custom-pages
      mountPath: /app/public
  volumes:
  - name: custom-pages
    configMap:
      name: errors-custom-pages  # 包含自定义HTML文件的ConfigMap

方法2：构建自定义镜像

基于官方镜像添加自定义页面文件，创建Dockerfile：

dockerfile
FROM ghcr.io/webhippie/errors:latest
COPY ./custom-pages /app/public

构建并推送自定义镜像：

bash
docker build -t my-custom-errors:latest .
docker push my-custom-errors:latest

镜像构建（可选）

若需自行构建镜像，需满足以下环境要求：

• Go >= 1.24.0
• go-task构建工具

构建步骤：

bash
# 克隆代码仓库
git clone https://github.com/webhippie/errors.git
cd errors

# 构建二进制文件
task build

# 构建Docker镜像
docker build -t custom-errors:latest .

安全与贡献

• 安全报告：发现安全问题请联系***
• 贡献指南：采用Fork -> Patch -> Push -> Pull Request流程提交贡献
• 许可证：该项目基于Apache-2.0许可证开源

镜像来源

官方镜像仓库：

• https://github.com/webhippie/errors/pkgs/container/errors
• https://hub.docker.com/r/webhippie/errors
• Quay