annat/acme

/.well-known 目录服务Docker镜像

镜像概述

该Docker镜像专为Web服务中的/.well-known目录托管设计，基于轻量级基础镜像（如nginx:alpine或busybox）构建，体积小巧（通常<10MB）且启动迅速（<1秒）。主要用于集中管理站点范围的元数据文件，解决复杂Web架构中/.well-known目录配置分散的问题，特别适用于SSL证书自动续期、站点所有权验证等场景。

核心功能与特性

• 轻量级设计：基于极简基础镜像，资源占用低，适合边缘设备及资源受限环境部署。
• 灵活文件管理：支持通过宿主机目录或Docker Volume挂载自定义文件，实现元数据持久化与动态更新。
• ACME协议兼容：原生支持Let's Encrypt等ACME客户端的HTTP-01挑战文件存放，无缝对接证书自动续期流程。
• 多场景适配：兼容站点验证（如Google Search Console、Bing Webmaster）、安全元数据（security.txt）、WebFinger等标准元数据格式。
• 可扩展配置：支持自定义Web服务器配置（如Nginx配置文件挂载），可添加CORS头、缓存策略等高级特性。

使用场景与适用范围

典型应用场景

1. SSL证书自动续期
   配合Certbot等ACME客户端，托管/.well-known/acme-challenge/目录下的验证文件，实现Let's Encrypt等免费SSL证书的自动签发与续期。

2. 站点所有权验证
   存放Google、Bing等平台要求的HTML验证文件（如google123456.html），快速完成站点所有权验证。

3. 安全元数据托管
   部署security.txt（安全联系信息）、robots.txt扩展配置等，提升站点安全性与合规性。

4. 微服务架构集成
   在微服务环境中作为独立服务部署，统一管理跨服务的/.well-known元数据，避免重复配置。

使用方法与配置说明

基本部署（docker run）

通过宿主机目录挂载启动服务，示例命令如下：

bash
docker run -d \
  --name well-known-service \
  -p 80:80 \  # ACME验证默认使用80端口，建议保持映射
  -v /path/host-well-known:/usr/share/nginx/html/.well-known \  # 挂载宿主机目录
  --restart unless-stopped \  # 确保服务持续运行
  username/well-known:latest  # 替换为实际镜像名称

Docker Compose配置

创建docker-compose.yml文件，适合多服务协同部署：

yaml
version: '3'
services:
  well-known:
    image: username/well-known:latest
    container_name: well-known-service
    ports:
      - "80:80"  # 暴露80端口用于HTTP验证
    volumes:
      - ./host-well-known:/usr/share/nginx/html/.well-known  # 宿主机目录挂载
      # 可选：挂载自定义Nginx配置
      # - ./custom-nginx.conf:/etc/nginx/conf.d/default.conf
    restart: unless-stopped
    networks:
      - web-network  # 如需与其他Web服务通信，加入共同网络

networks:
  web-network:
    external: true  # 关联外部Web服务网络（如已有Nginx反向代理网络）

高级配置说明

文件挂载与权限

• 挂载路径：容器内默认文档根目录为Web服务器根路径（如Nginx默认/usr/share/nginx/html），需确保挂载目录对应/.well-known子路径（如上述示例中的/usr/share/nginx/html/.well-known）。
• 权限设置：宿主机挂载目录建议设置权限为755，避免容器内用户因权限不足无法读取文件：

  bash
  chmod 755 /path/host-well-known
  

自定义Web服务器配置（以Nginx为例）

若需调整服务器行为（如添加CORS头），可挂载自定义Nginx配置文件：

1. 创建自定义配置文件custom-nginx.conf：

   nginx
   server {
       listen 80;
       server_name _;  # 匹配所有域名
       
       location /.well-known/ {
           root /usr/share/nginx/html;
           autoindex off;  # 禁用目录索引
           add_header Access-Control-Allow-Origin *;  # 允许跨域访问（按需开启）
           expires 1h;  # 设置缓存时间
       }
   }
   

2. 通过挂载启动容器：

   bash
   docker run -d \
     --name well-known-service \
     -p 80:80 \
     -v /path/host-well-known:/usr/share/nginx/html/.well-known \
     -v /path/custom-nginx.conf:/etc/nginx/conf.d/default.conf \  # 挂载自定义配置
     username/well-known:latest
   

注意事项

• 端口冲突处理：若主机已运行其他Web服务（如主站Nginx），可通过反向代理将/.well-known/路径代理至该容器，避免80端口占用（示例Nginx反向代理配置）：

  nginx
  location /.well-known/ {
      proxy_pass http://well-known-service:80;  # 指向容器服务
      proxy_set_header Host $host;
      proxy_set_header X-Real-IP $remote_addr;
  }
  

• 文件安全：避免在/.well-known目录存放敏感信息，建议通过Web服务器配置限制访问来源（如仅允许ACME服务器IP）。
• 跨平台支持：镜像通常提供amd64、arm64等多架构标签，部署前需确认目标平台架构（如树莓派使用arm64标签）。