私有仓库Token认证需三部分协同：认证服务签发带scope的JWT、Registry配置信任并返回正确WWW-Authenticate头、客户端自动获取与携带Token。
私有仓库的 Token 认证不是简单“填个密码”就能生效的机制，它依赖一套完整的认证服务链路——Registry 本身不直接验密，而是把验证委托给独立的 Auth Server（如 Harbor 的 core 组件、Docker Registry 的 token server 或 Keycloak 等）。配置的关键在于让客户端能正确获取并携带有效 Token，同时服务端严格校验其签名、范围和时效。
Token 认证的核心组成
要真正落地，必须同时具备以下三部分：
-
认证服务（Auth Server）：提供
/auth接口，接收用户名/密码或 OAuth 凭据，签发带 scope 的 JWT Token（例如：scope=repository:myapp:pull,push） -
镜像仓库（Registry）：配置为信任该 Auth Server，并在返回 401 响应时附带正确的
WWW-Authenticate头，指向 Auth Server 地址 - 客户端凭证管理：Docker、Buildah 或 containerd 需将登录凭据存入对应 config 文件，并在请求时自动完成 Token 获取与携带
以 Harbor 为例的典型配置流程
Harbor 是开箱即用的 Token 认证方案，无需额外部署 Auth Server：
- 安装时启用 HTTPS（必需），否则 Docker 客户端拒绝发送敏感凭据
- 确保 Harbor 的
core服务正常运行——它既是 UI/API 入口，也是内置的 Auth Server - 客户端执行
docker login https://harbor.example.com，输入 Harbor 用户名密码 - Docker 自动向
https://harbor.example.com/service/token请求 Token，并缓存到~/.docker/config.json - 后续
pull/push请求中，Docker 在 Header 中自动添加Authorization: Bearer <token>
手动配置 Registry + 外部 Token Server（进阶场景）
若使用原生 Docker Registry 并对接自建 Auth Server（如 nginx + auth_token 模块或 Dex）：
- Registry 配置文件
config.yml中需明确指定auth.token区块：
token:
realm: "https://auth.example.com/auth"
service: "harbor-registry"
issuer: "auth-server"
rootcertbundle: /etc/registry/auth.crt
- Auth Server 必须返回符合 Docker Registry 规范的 JWT：含
iss、exp、aud，且access_tokenpayload 中包含scope字段（如repository:prod/app:pull） - 客户端仍用
docker login，但目标地址需与 Registry 的realm一致；Token 由 Auth Server 颁发，Registry 只负责校验签名和 scope
安全准入控制的实际落地点
Token 本身只是载体，真正的“准入控制”靠的是 scope 和后端权限系统协同：
-
Scope 粒度控制：Token 中的
scope=repository:team-a/web:pull,push表示仅允许对指定仓库路径执行拉取和推送，不能越权操作其他项目 - 用户角色映射：Auth Server（如 Harbor）需将登录用户绑定到项目/仓库级别的角色（访客、开发者、管理员），并在签发 Token 时写入对应 scope
-
Token 有效期与吊销：设置合理
exp（建议 24 小时内），并通过 Auth Server 提供 Token 吊销接口，配合 Registry 的 cache TTL 控制失效延迟 -
禁止 Basic Auth 直连：在 Registry 配置中禁用
htpasswd等基础认证方式，强制所有流量走 Token 流程
不复杂但容易忽略。Token 认证的有效性不取决于客户端是否“登录”，而取决于整个链路中每一环是否按规范协作——Auth Server 的 scope 是否精准、Registry 的 realm 是否可访问、客户端 config 是否被正确读取，缺一不可。
