mkcert 容器镜像文档

镜像概述

本镜像为mkcert工具的容器化封装。mkcert是一款由FiloSottile开发的轻量级工具，旨在帮助开发者快速生成本地信任的SSL/TLS证书，避免在开发环境中因使用自签名证书导致的浏览器安全警告。通过容器化部署，无需在本地系统直接安装mkcert，即可便捷使用其全部功能。

核心功能与特性

• 容器化封装：无需在宿主机安装mkcert及其依赖，通过Docker即可运行，保持系统环境整洁
• 跨平台一致性：在Windows、macOS、Linux等不同操作系统上提供一致的使用体验
• 隔离存储：证书和根CA存储在容器指定路径，可通过挂载卷持久化保存
• 自动信任根CA：支持将生成的根证书自动添加到容器内模拟的信任存储（如需宿主机信任需额外配置）
• 多域名支持：可一次性为多个域名（含通配符域名）生成证书，如example.com "*.example.com" localhost
• 零配置CA：内置简化的CA管理，自动处理根证书生成与轮换，无需手动配置证书颁发机构

使用场景与适用范围

适用场景

• 本地Web开发环境中快速配置HTTPS，测试SSL相关功能
• 微服务架构本地开发时，服务间通信的加密传输测试
• 前端本地调试需模拟HTTPS环境（如PWA、Service Worker）
• CI/CD流程中临时生成测试证书

适用人群

• Web开发者（前后端、全栈）
• 微服务架构测试人员
• 需要在本地快速验证HTTPS功能的技术团队

使用方法与配置说明

基本使用流程

1. 挂载宿主机目录到容器内证书存储路径（持久化证书）
2. 运行容器执行mkcert命令生成证书
3. （可选）导出根CA证书并在宿主机信任

Docker命令示例

1. 生成基础证书（单域名）

bash
# 挂载当前目录下的certs文件夹用于存储证书
docker run --rm -v $(pwd)/certs:/certs mkcert-image example.com

• --rm：容器退出后自动删除
• -v $(pwd)/certs:/certs：将宿主机当前目录下的certs文件夹挂载到容器内的/certs（证书生成目录）
• mkcert-image：替换为实际镜像名称（如filosottile/mkcert或自定义镜像名）
• example.com：目标域名（可替换为实际需要的域名）

2. 生成多域名证书（含通配符和本地地址）

bash
docker run --rm -v $(pwd)/certs:/certs mkcert-image "*.example.com" example.com localhost 127.0.0.1 ::1

生成包含通配符域名（*.example.com）、标准域名（example.com）、本地回环地址（localhost、127.0.0.1、::1）的证书

3. 查看根CA存储路径

bash
docker run --rm mkcert-image -CAROOT

输出容器内根CA证书存储路径（默认/root/.local/share/mkcert），用于导出根CA

4. 导出根CA证书到宿主机

bash
# 先获取根CA路径
CAROOT=$(docker run --rm mkcert-image -CAROOT)
# 复制根CA证书到宿主机
docker run --rm -v $(pwd)/certs:/certs mkcert-image cp $CAROOT/rootCA.pem /certs/

执行后，根CA证书（rootCA.pem）将保存到宿主机./certs目录

5. 强制重新生成根CA

bash
docker run --rm -v $(pwd)/certs:/certs mkcert-image -install

重新生成根CA并安装到容器内信任存储（宿主机信任需手动处理）

配置参数说明

核心挂载路径

常用mkcert命令参数

宿主机信任根CA（关键步骤）

容器内生成的根CA默认仅在容器内信任，需手动在宿主机信任以消除浏览器警告：

macOS

bash
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ./certs/rootCA.pem

Linux（Debian/Ubuntu）

bash
sudo cp ./certs/rootCA.pem /usr/local/share/ca-certificates/
sudo update-ca-certificates

Windows（PowerShell管理员模式）

powershell
Import-Certificate -FilePath .\certs\rootCA.pem -CertStoreLocation Cert:\LocalMachine\Root

注意事项

• 生产环境禁用：本镜像生成的证书仅用于本地开发/测试，不可用于生产环境（根CA仅本地信任，无公信力）
• 证书权限：宿主机证书文件权限默认继承容器内权限（通常为root），可能需要手动调整权限（如chmod 644 *.pem）
• 跨平台差异：Windows和WSL2环境下挂载路径格式需调整（如/mnt/c/Users/...替换$(pwd)）
• 根CA轮换：若根CA泄露或过期，可通过-install参数重新生成并更新宿主机信任

常见问题

• Q：证书生成后浏览器仍提示不安全？
  A：检查是否已在宿主机信任根CA，或确认证书域名与访问域名一致（含端口号差异）

• Q：容器重启后证书丢失？
  A：确保已正确挂载宿主机目录持久化存储证书（-v参数）

• Q：支持生成ECC证书吗？
  A：支持，添加-ecdsa参数即可生成ECC类型证书（如docker run --rm -v $(pwd)/certs:/certs mkcert-image -ecdsa example.com）