kumahq/notary-internal

Docker 镜像签名仓库（预览/内部标签版）技术文档

1. 镜像概述

本镜像是一个轻量级 Docker 镜像签名仓库，专为管理预览版本和内部标签镜像的签名信息设计。它提供了签名存储、验证、标签分类等核心能力，帮助团队在开发、测试流程中确保镜像的完整性和来源可信，同时支持对内部流转和预览版本的镜像进行精细化管理。

2. 核心功能与特性

2.1 签名管理

• 支持 Docker Content Trust (DCT) 规范的签名存储与检索
• 自动关联镜像 digest 与签名元数据（如创建时间、签名者、标签类型）
• 提供签名版本控制，支持历史签名记录查询

2.2 标签类型支持

• 预览标签：针对开发中的临时版本（如 preview-v1.2.3-rc1），支持自动过期清理
• 内部标签：针对团队内部流转的正式版本（如 internal-v1.2.3），支持权限隔离与审计

2.3 安全性与兼容性

• 集成 Docker 客户端签名验证流程，支持 docker pull 时自动校验签名
• 支持 RSA/ECDSA 等主流签名算法，兼容 Notary v2 规范
• 内置基础访问控制（ACL），支持基于角色的权限管理（如只读/读写权限）

2.4 存储与扩展性

• 支持本地文件系统、S3 兼容对象存储、NAS 等多后端存储
• 轻量化设计，容器化部署资源占用低（默认内存 < 256MB）
• 支持水平扩展，可通过负载均衡实现高可用部署

3. 使用场景与适用范围

3.1 开发环境镜像管理

• 为开发团队构建的临时镜像（如 feature 分支产物）添加签名，确保构建产物未被篡改
• 自动关联 Git 提交信息与镜像签名，实现代码-镜像溯源

3.2 内部测试版本追踪

• 对测试环境的候选版本镜像（内部标签）进行签名归档，支持按测试阶段（如 test-staging、test-prod）分类
• 通过签名元数据快速定位镜像对应的测试报告与审批记录

3.3 预览版本安全分发

• 为对外预览的版本（如客户试用版）添加签名，防止未授权篡改
• 结合 CDN 或内部 registry，实现带签名的预览镜像安全分发

3.4 团队协作流程集成

• 与 CI/CD 流水线集成（如 Jenkins、GitHub Actions），自动为构建镜像添加签名并推送至仓库
• 支持多团队隔离，不同团队的内部标签签名数据独立存储

4. 使用方法与配置说明

4.1 镜像拉取

从指定 registry 拉取镜像（需替换 <registry> 和 <tag> 为实际值）：

bash
docker pull <registry>/image-signature-repo:preview-internal-<tag>

4.2 基础运行命令（docker run）

4.2.1 最简启动（默认配置）

bash
docker run -d \
  --name sig-repo \
  -p 8080:8080 \
  -v /local/data:/data \  # 持久化存储签名数据
  <registry>/image-signature-repo:preview-internal-<tag>

4.2.2 自定义配置启动（指定存储后端与访问控制）

bash
docker run -d \
  --name sig-repo \
  -p 8080:8080 \
  -v /local/data:/data \
  -e STORAGE_BACKEND=s3 \  # 使用 S3 存储后端
  -e S3_ENDPOINT=https://s3.example.com \
  -e S3_BUCKET=sig-repo-bucket \
  -e S3_ACCESS_KEY=AKIAEXAMPLE \
  -e S3_SECRET_KEY=secret \
  -e AUTH_ENABLED=true \  # 启用基本认证
  -e AUTH_USER=admin \
  -e AUTH_PASSWORD=secure-pass \
  <registry>/image-signature-repo:preview-internal-<tag>

4.3 docker-compose 配置示例

yaml
version: '3.8'
services:
  sig-repo:
    image: <registry>/image-signature-repo:preview-internal-<tag>
    container_name: sig-repo
    ports:
      - "8080:8080"
    volumes:
      - sig-repo-data:/data  # 数据卷持久化
    environment:
      - STORAGE_BACKEND=filesystem  # 本地文件系统存储
      - DATA_DIR=/data  # 存储路径（容器内）
      - PORT=8080  # 服务端口
      - LOG_LEVEL=info  # 日志级别（debug/info/warn/error）
      - PREVIEW_TAG_TTL=7d  # 预览标签自动过期时间（默认 7 天）
      - AUTH_ENABLED=true
      - AUTH_USER=team-admin
      - AUTH_PASSWORD=team-pass-123
    restart: unless-stopped

volumes:
  sig-repo-data:  # 定义持久化数据卷

4.4 环境变量配置说明

4.5 核心操作示例

4.5.1 添加镜像签名

通过 HTTP API 提交镜像签名（需替换 <image-digest>、<tag-type> 等参数）：

bash
curl -X POST http://localhost:8080/api/v1/signatures \
  -H "Content-Type: application/json" \
  -u "admin:secure-pass" \  # 若启用认证
  -d '{
    "image_digest": "sha256:abc123...",  # 镜像唯一 digest
    "tag": "preview-v1.2.3-rc1",  # 镜像标签
    "tag_type": "preview",  # 标签类型：preview/internal
    "signature": "base64-encoded-signature...",  # 签名内容（base64 编码）
    "signer": "ci-bot@example.com",  # 签名者信息
    "metadata": {"git_commit": "a1b2c3d"}  # 附加元数据
  }'

4.5.2 验证镜像签名

查询并验证指定镜像 digest 的签名：

bash
curl -X GET "http://localhost:8080/api/v1/signatures?digest=sha256:abc123..." \
  -u "admin:secure-pass"

响应示例：

json
{
  "digest": "sha256:abc123...",
  "signatures": [
    {
      "tag": "preview-v1.2.3-rc1",
      "tag_type": "preview",
      "signer": "ci-bot@example.com",
      "created_at": "2024-05-20T10:30:00Z",
      "metadata": {"git_commit": "a1b2c3d"},
      "is_valid": true
    }
  ]
}

4.5.3 管理内部标签

列出所有内部标签的签名记录：

bash
curl -X GET "http://localhost:8080/api/v1/tags?type=internal" \
  -u "admin:secure-pass"

5. 注意事项

• 数据持久化：务必通过 -v 挂载数据卷或配置外部存储后端（如 S3），避免容器重启导致签名数据丢失。
• 安全配置：生产环境需启用 AUTH_ENABLED 并使用强密码，建议结合 TLS 加密（通过反向代理如 Nginx 配置 HTTPS）。
• 版本兼容性：镜像标签 preview-internal-<tag> 中，<tag> 为版本号，需与 Docker 客户端版本（建议 20.10+）及 Notary 工具（建议 v2.0+）兼容。
• 预览标签清理：默认 PREVIEW_TAG_TTL=7d，过期预览标签将自动清理，如需保留历史数据可调整该参数或禁用自动清理（设置 PREVIEW_TAG_TTL=0）。