mendhak/http-https-echo 镜像文档

mendhak/http-https-echo 是一个 Docker 镜像，能够将各种 HTTP 请求属性回显给客户端，并同时记录到 Docker 容器日志中。它提供多种可操作响应输出的选项，完整功能列表参见下文。

!浏览器展示

该镜像可在 Docker Hub 获取：mendhak/http-https-echo:31
也可在 GitHub 容器仓库 获取：ghcr.io/mendhak/http-https-echo:31

请勿使用 :latest 标签，它可能会无预警地失效，请使用具体版本标签。

此镜像默认以非 root 用户执行，完全兼容 Kubernetes 或 OpenShift 部署。

基本使用

Docker 运行

docker run -p 8080:8080 -p 8443:8443 --rm -t mendhak/http-https-echo:31

Docker Compose 运行

docker-compose up

然后，通过浏览器或 curl 发送请求，观察响应内容及容器日志输出：

curl -k -X PUT -H "Arbitrary:Header" -d aaa=bbb https://localhost:8443/hello-world

自定义端口

可通过 HTTP_PORT 和 HTTPS_PORT 环境变量修改内部端口（默认 8080/8443）。

示例：将 HTTP 端口设为 8888，HTTPS 端口设为 9999

docker run -e HTTP_PORT=8888 -e HTTPS_PORT=9999 -p 8080:8888 -p 8443:9999 --rm -t mendhak/http-https-echo:31

Docker Compose 配置：

my-http-listener:
    image: mendhak/http-https-echo:31
    environment:
        - HTTP_PORT=8888
        - HTTPS_PORT=9999
    ports:
        - "8080:8888"
        - "8443:9999"

使用自定义证书

默认证书路径为 /app/fullchain.pem（证书）和 /app/privkey.pem（私钥）。可通过卷挂载替换为自定义证书：

my-http-listener:
    image: mendhak/http-https-echo:31
    ports:
        - "8080:8080"
        - "8443:8443"
    volumes:
        - /etc/ssl/certs/ssl-cert-snakeoil.pem:/app/fullchain.pem
        - /etc/ssl/private/ssl-cert-snakeoil.key:/app/privkey.pem

也可通过 HTTPS_CERT_FILE 和 HTTPS_KEY_FILE 环境变量指定容器内证书路径。

解码 JWT 头

通过 JWT_HEADER 环境变量指定包含 JWT 的请求头，回显输出将包含解码后的 JWT 信息：

docker run -e JWT_HEADER=Authentication -p 8080:8080 -p 8443:8443 --rm -it mendhak/http-https-echo:31

发送包含 JWT 的请求（支持 Authentication: Bearer <token> 格式）：

curl -k -H "Authentication: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" http://localhost:8080/

响应中将出现 jwt 字段。

禁用 ExpressJS 日志行

设置 DISABLE_REQUEST_LOGS=true 可禁用 ExpressJS 特定请求日志行（如 ::ffff:172.17.0.1 - - [03/Jan/2022:21:31:51 +0000] "GET /xyz HTTP/1.1" 200 423 "-" "curl/7.68.0"），JSON 输出不受影响：

docker run --rm -e DISABLE_REQUEST_LOGS=true --name http-echo-tests -p 8080:8080 -p 8443:8443 -t mendhak/http-https-echo:31

忽略特定路径日志

通过 LOG_IGNORE_PATH 环境变量设置无需详细记录到 stdout 的路径，可减少健康检查等场景的日志噪音：

docker run -e LOG_IGNORE_PATH=/ping -p 8080:8080 -p 8443:8443 --rm -t mendhak/http-https-echo:31

Docker Compose 配置：

my-http-listener:
    image: mendhak/http-https-echo:31
    environment:
        - LOG_IGNORE_PATH=/ping
    ports:
        - "8080:8080"
        - "8443:8443"

JSON 负载与输出

当请求体为 JSON 且 Content-Type 为 application/json 时，响应将包含解析后的 JSON 数据：

curl -X POST -H "Content-Type: application/json" -d '{"a":"b"}' http://localhost:8080/

响应/输出中将出现 json 字段：

{
    ...
    "xhr": false,
    "connection": {},
    "json": {
        "a": "b"
    }
}

日志无换行

设置 LOG_WITHOUT_NEWLINE=true 可禁用日志输出中的换行：

docker run -e LOG_WITHOUT_NEWLINE=true -p 8080:8080 -p 8443:8443 --rm -t mendhak/http-https-echo:31

空响应

设置 ECHO_BACK_TO_CLIENT=false 可禁用响应中的 JSON 输出：

docker run -e ECHO_BACK_TO_CLIENT=false -p 8080:8080 -p 8443:8443 --rm -t mendhak/http-https-echo:31

自定义状态码

通过 x-set-response-status-code 头或查询参数设置响应状态码：

作为请求头

curl -v -H "x-set-response-status-code: 401" http://localhost:8080/

作为查询参数

curl -v http://localhost:8080/some/path?x-set-response-status-code=401

响应状态码将变为：

HTTP/1.1 401 Unauthorized

设置响应 Content-Type

通过 x-set-response-content-type 头或查询参数设置响应 Content-Type：

作为请求头

curl -H "X-Set-Response-Content-Type: text/plain" -kv https://localhost:8443/

作为查询参数

curl -kv https://localhost:8443/path?x-set-response-content-type=text/plain

响应头将包含：

< Content-Type: text/plain; charset=utf-8

响应延迟

通过 x-set-response-delay-ms 头或查询参数设置响应延迟（毫秒），用于模拟慢响应：

作为请求头

curl -v -H "x-set-response-delay-ms: 6000" http://localhost:8080/

作为查询参数

curl -v http://localhost:8080/some/path?x-set-response-delay-ms=6000

仅返回请求体

使用查询参数 response_body_only=true 可仅返回请求体，不包含元数据：

curl -s -k -X POST -d 'cauliflower' http://localhost:8080/a/b/c?response_body_only=true

输出将为 cauliflower。

响应包含环境变量

设置 ECHO_INCLUDE_ENV_VARS=1 可在响应中包含容器进程可见的环境变量（默认不启用，因可能包含敏感信息）：

docker run -d --rm -e ECHO_INCLUDE_ENV_VARS=1 --name http-echo-tests -p 8080:8080 -p 8443:8443 -t mendhak/http-https-echo:31

请求后响应中将出现 env 字段。

客户端证书详情（mTLS）

设置 MTLS_ENABLE=1 可在响应中包含客户端证书详情（客户端证书不会被验证）。

示例：使用 curl 传递客户端证书和密钥

curl -k --cert cert.pem --key privkey.pem https://localhost:8443/

响应中将包含客户端证书详情。

浏览器访问：Firefox 仅在导入与服务器同签发者的证书时才会提示选择客户端证书。如需浏览器提示，需将证书转换为 PKCS12 格式：

openssl pkcs12 -export -in cert.pem -inkey privkey.pem -out certpkcs12.pfx

Prometheus 指标

设置 PROMETHEUS_ENABLED=true 可暴露 HTTP 性能指标，指标路径默认为 /metrics（基于 express-prom-bundle 中间件）。

可通过以下变量配置指标：

更多详情参见 中间件文档。

截图

curl 输出

!curl

docker logs 输出

!dockerlogs

构建与测试

构建镜像

docker build -t mendhak/http-https-echo .

运行测试

./tests.sh

推送新版本

git tag -s 16
git push --tags

变更日志

参见 changelog