kekru/docker-remote-api-tls

Docker Remote API TLS 认证代理镜像

镜像概述和主要用途

本镜像通过容器化方式提供带TLS客户端认证的Docker Remote API访问能力，客户端必须通过TLS证书进行身份验证。作为直接在Docker守护进程上配置TLS的替代方案，本镜像简化了安全暴露Docker Remote API的流程，适用于需要安全远程管理Docker主机的场景。

核心功能和特性

• 强制TLS客户端认证：仅允许持有有效客户端证书的请求访问Docker Remote API
• 双模式证书管理：支持使用外部CA证书或自动生成CA及证书链
• 灵活的证书配置：可自定义证书有效期、服务器主机名等关键参数
• 安全存储支持：可通过Docker Swarm Secrets管理证书密码，避免明文环境变量
• 轻量级代理：基于Nginx实现，性能高效且资源占用低

使用场景和适用范围

• 安全远程管理：需要通过网络远程访问Docker主机API的场景
• 多主机Docker环境：跨主机管理Docker容器集群时的安全通信需求
• 自动化部署流程：CI/CD管道中需要安全调用Docker API的场景
• 第三方集成：允许可信服务通过API与Docker守护进程交互的场景
• 测试环境快速搭建：需要临时暴露API但不愿修改Docker守护进程配置的场景

详细使用方法和配置说明

前提条件

• Docker Engine 18.06+ 或 Docker Desktop
• Docker Compose 1.25+（如需使用compose文件部署）
• 本地文件系统路径（用于存储证书，需具备读写权限）

方式一：使用外部CA证书

准备工作

1. 生成证书文件
   需准备CA根证书、服务器证书及私钥，可通过以下方式生成：

   • 参考Docker官方文档：保护Docker守护进程套接字
   • 使用脚本：https://github.com/kekru/linux-utils/blob/master/cert-generate/create-certs.sh%EF%BC%88%E8%AF%A6%E8%A7%81%E4%BD%BF%E7%94%A8%E8%AF%B4%E6%98%8E%EF%BC%9Ahttps://gist.github.com/kekru/974e40bb1cd4b947a53cca5ba4b0bbe5#create-certificate-files%EF%BC%89

2. 整理证书文件
   将以下文件放入本地目录（后续挂载到容器）：

   ca-cert.pem      # CA根证书
   server-cert.pem  # 服务器证书
   server-key.pem   # 服务器私钥
   

   客户端需使用ca-cert.pem、cert.pem（客户端证书）和key.pem（客户端私钥）进行认证

部署配置

创建docker-compose.yml文件：

yaml
version: "3.4"
services:
  remote-api:
    image: kekru/docker-remote-api-tls:v0.4.0
    ports:
      - 2376:443  # 标准Docker TLS端口映射
    volumes:
      - <本地证书目录>:/data/certs:ro  # 只读挂载证书目录
      - /var/run/docker.sock:/var/run/docker.sock:ro  # 只读挂载Docker套接字

启动服务

bash
# 使用Docker Compose启动
docker-compose up -d

# 或使用Docker Swarm部署
docker stack deploy --compose-file=docker-compose.yml remoteapi

服务启动后，Docker Remote API将通过https://<主机IP>:2376暴露，客户端需使用cert.pem和key.pem进行认证。

方式二：自动生成CA及证书

准备工作

无需提前生成证书，镜像将自动创建CA根证书、服务器证书、客户端证书及私钥。需准备：

• 本地空目录（用于存储生成的证书，需具备读写权限）
• 证书密码（用于加密私钥）
• 服务器主机名（将写入服务器证书的Subject Alternative Name字段）

部署配置

创建docker-compose.yml文件：

yaml
version: "3.4"
services:
  remote-api:
    image: kekru/docker-remote-api-tls:v0.4.0
    ports:
      - 2376:443
    environment:
      - CREATE_CERTS_WITH_PW=supersecret  # 证书加密密码（必填）
      - CERT_HOSTNAME=remote-api.example.com  # API访问主机名（必填）
      # 可选：自定义证书有效期
      # - CERT_EXPIRATION_DAYS=365  # 服务器/客户端证书有效期（默认365天）
      # - CA_EXPIRATION_DAYS=900    # CA根证书有效期（默认900天）
    volumes:
      - <本地证书目录>:/data/certs  # 读写挂载，用于存储生成的证书
      - /var/run/docker.sock:/var/run/docker.sock:ro

启动服务

bash
# 使用Docker Compose启动
docker-compose up -d

# 或使用Docker Swarm部署
docker stack deploy --compose-file=docker-compose.yml remoteapi

证书文件位置

生成的证书将存储在<本地证书目录>：

• 服务器证书：ca-cert.pem、server-cert.pem、server-key.pem
• 客户端证书：<本地证书目录>/client/ca.pem、cert.pem、key.pem

环境变量说明

客户端配置指南

获取客户端证书

• 外部CA模式：客户端证书需自行准备（ca-cert.pem、cert.pem、key.pem）
• 自动生成模式：客户端证书位于<本地证书目录>/client/

配置Docker客户端

通过环境变量指定证书路径和API地址：

bash
export DOCKER_HOST=tcp://remote-api.example.com:2376
export DOCKER_TLS_VERIFY=1
export DOCKER_CERT_PATH=<客户端证书目录>  # 包含ca.pem、cert.pem、key.pem的目录

测试连接：

bash
docker ps  # 应返回远程主机上的容器列表

使用dockerRemote脚本

项目提供dockerRemote脚本简化客户端访问：

1. 下载脚本：wget https://raw.githubusercontent.com/kekru/docker-remote-api-tls/master/dockerRemote
2. 修改脚本中的DOCKER_HOST和DOCKER_CERT_PATH为实际值
3. 执行命令：./dockerRemote ps

快速测试步骤

1. 克隆仓库：

   bash
   git clone https://github.com/kekru/docker-remote-api-tls.git
   cd docker-remote-api-tls
   

2. 启动服务（自动生成证书模式）：

   bash
   # 修改docker-compose.yml中的CERT_HOSTNAME为本地IP或主机名
   docker-compose up -d
   

3. 测试API访问：

   bash
   # 使用项目提供的dockerRemote脚本
   ./dockerRemote ps
   

变更日志

v0.4.0

• 升级Nginx版本至1.20.2

v0.3.0

• 升级Nginx版本
• 新增证书有效期配置（CERT_EXPIRATION_DAYS和CA_EXPIRATION_DAYS）
• 新增支持通过Docker Swarm Secrets存储证书密码（CERTS_PASSWORD_FILE）
• 新增自动化测试

v0.2.0

• 首个稳定版本
• 感谢https://github.com/smiller171%E7%9A%84%E8%B4%A1%E7%8C%AE