Files
docker-center/docs/publish-image.md
T

8.9 KiB
Raw Blame History

把镜像发布到公开仓库

目标:让别人 docker pull 就能用,不用 clone 源码、不用装 Node、不用现编译。

本仓库自带 scripts/push-image.sh,一次构建、多处推送。


先说结论(按推荐顺序)

仓库 免费额度 国内拉取速度 适合场景 需要什么
腾讯云 TCR 个人版 免费(个人版) 快(可选地域,本仓库用东京 jpccr) 首选:对外分发(已验证可推可拉) 腾讯云账号
自建 Gitea(本机) 无限 取决于你家带宽 国内备用 / 内网自用 无(已有)
阿里云 ACR 个人版 — 快 ⚠️ 已停止新用户开通,旧版 API 已下线,新账号只能用付费企业版 付费
Docker Hub 公开仓免费不限 慢/常被墙 给海外用户、写进 README 好看 代理 + 账号

两个可用地址内容一致(digest sha256:37022ce4080b26b1d9f8c3e9ba08612cc1169a87fb55eb65a746714f9ce98f01): jpccr.ccs.tencentyun.com/jinghui/docker-center:1.0.1(腾讯云)、gitea.88531.cn/jinghui/docker-center:1.0.1(自建),二者都已用「清空凭据」的方式实测匿名拉取成功。


方案一:腾讯云 TCR 个人版(推荐,已在本仓库验证)

本项目的正式对外地址:jpccr.ccs.tencentyun.com/jinghui/docker-center:1.0.1

实测事实(2026-10-27)

  • 地域选的是东京,所以域名叫 jpccr.ccs.tencentyun.com(jp = 东京);国内地域对应 ccr.ccs.tencentyun.com 或 hkccr/sgccr 等
  • 登录用户名不是邮箱,而是腾讯云账号 ID(本账号 100042126615),密码是个人版「访问凭证」里设的固定密码
  • 个人版仓库默认私有,推上去后匿名拉取会 unauthorized;必须到控制台把仓库类型改成「公开」
  • 命名空间必须事先在控制台建好;推错命名空间报 DENIED: no permission! are you logined with another ccr account?(这个报错很误导,其实是命名空间不存在或不属于你)
  • DescribeInstances API 不返回个人版实例,所以别指望用 API 判断个人版是否已开通,只能看控制台

步骤

  1. 控制台 → 容器镜像服务 TCR → 个人版 → 开通(免费)→ 建命名空间(本仓库用 jinghui)→ 建仓库 docker-center
  2. 个人版 → 访问凭证 → 设固定密码
  3. 登录并推送:
docker login jpccr.ccs.tencentyun.com -u <腾讯云账号ID>
REGISTRY=jpccr.ccs.tencentyun.com NAMESPACE=jinghui REUSE=1 ./scripts/push-image.sh custom 1.0.1
  1. 把仓库改成公开,然后用清空凭据的方式验证:
mkdir -p /tmp/nocreds && echo '{}' > /tmp/nocreds/config.json
DOCKER_CONFIG=/tmp/nocreds docker pull jpccr.ccs.tencentyun.com/jinghui/docker-center:1.0.1

腾讯云 API 里没有「创建个人版实例」这个动作(CreateInstance 的 RegistryType 只有 basic/standard/premium,都是企业版且要 TCR_QCSRole 服务角色授权、按量计费),所以个人版只能在控制台点开通,脚本层无法代劳。


方案二:阿里云 ACR 个人版(⚠️ 已停止新用户开通)

2026-10 实测结论:阿里云已关闭个人版新用户开通,且旧版 API(版本 2016-06-07)整条产品线已下线:

GetAuthorizationToken v2016-06-07 → InvalidAction.NotFound
GetAuthorizationToken v2018-12-01 → MissingInstanceId   ← 新版只认企业版实例 ID (cri-xxx)
CreateNamespace       v2018-12-01 → MissingInstanceId
ListInstance(5 个地域)          → TotalCount = 0

新账号只能用付费企业版(API 里连 CreateInstance 都没有,须控制台/ Terraform 建)。若你已有存量个人版实例,流程仍是:建命名空间 + 公开仓库 → docker login registry.cn-hangzhou.aliyuncs.com -u <账号> → NAMESPACE=<ns> ./scripts/push-image.sh aliyun 1.0.1。


方案三:Docker Hub

本机直连 Docker Hub 不通(registry-1.docker.io 连接超时),需要给 docker 守护进程配代理:

# /etc/systemd/system/docker.service.d/http-proxy.conf
[Service]
Environment="HTTP_PROXY=http://127.0.0.1:7890"
Environment="HTTPS_PROXY=http://127.0.0.1:7890"
Environment="NO_PROXY=localhost,127.0.0.1,192.168.0.0/16"
systemctl daemon-reload && systemctl restart docker   # 注意:会重启所有容器

docker login -u <dockerhub用户名>
NAMESPACE=<dockerhub用户名> ./scripts/push-image.sh dockerhub 1.0.0

拉取:docker pull <用户名>/docker-center:1.0.0

公开仓库免费且数量不限;私有仓库免费版只有 1 个。


方案四:自建 Gitea(本机,内网用)

Gitea 自带容器仓库(Docker Registry V2,本项目实测可用)。

一次性准备(已在本机做过)

# 1) 允许 HTTP 仓库(Gitea 在 3200 端口跑 HTTP)
#    编辑 /etc/docker/daemon.json,加:
#    "insecure-registries": ["192.168.68.19:3200"]
systemctl reload docker        # reload 即可,不会重启容器

# 2) 签发有 package 权限的 token(普通 git token 没有 package 权限,会报 unauthorized: reqPackageAccess)
docker exec -u git gitea gitea admin user generate-access-token \
  --username jinghui --token-name docker-push \
  --scopes write:package,read:package,write:repository,read:repository

# 3) 登录
docker login 192.168.68.19:3200 -u jinghui

推送

REUSE=1 ./scripts/push-image.sh gitea-lan 1.0.0

推完可在 http://192.168.68.19:3200/jinghui/-/packages 看到包。

用公网域名 https://gitea.88531.cn(外网用户)

链路:gitea.88531.cn → 43.163.242.147(frp/宝塔 nginx + WAF)→ NPC 隧道 → 本机 Gitea:3200。

  • /v2/、token、建上传会话都正常
  • 已修复:此前 >1MB 的 blob 上传被宝塔 WAF 拦掉,返回 <title>Nginx缓冲区溢出</title>,docker 表现为无限 Retrying

上游宝塔 WAF 拦截大文件(已修复,留档)

根因:/www/server/btwaf/modules/post.lua 里 ngx.req.get_post_args(1000000) 在请求体超过 client_body_buffer_size 时返回 nil,WAF 直接吐「Nginx缓冲区溢出」页面(HTTP 200)。docker 发的是 application/octet-stream,正好命中 WAF 的 body 检查分支。

另一个坑:url_white.json 里原本只有某一个具体上传会话的 UUID(^/v2/jinghui/docker-center/blobs/uploads/er8vtd...),所以每次 docker 新建会话都被拦——看起来像「时好时坏」。

修复(在 43.163.242.147 上执行):

cp /www/server/btwaf/rule/url_white.json{,.bak.$(date +%s)}
python3 - <<'PYEOF'
import json
p='/www/server/btwaf/rule/url_white.json'
d=json.load(open(p))
d=[x for x in d if '/blobs/uploads/' not in x]
for pat in ('^/v2/jinghui/docker-center/','^/v2/token'):
    if pat not in d: d.append(pat)
json.dump(d,open(p,'w'),ensure_ascii=False)
PYEOF
nginx -t && nginx -s reload      # WAF 规则在 init 阶段读取,必须 reload

实测:公网 PUT 100KB / 6MB / 40MB 层均返回 201(40MB 约 16.7 秒)。

面板里「URL 加白」按钮加的也是这个文件,但它只会加当前那一条完整 URL(带 UUID),对 registry 无效——必须换成路径前缀。 只调 client_body_buffer_size 4096K 也没用,那只覆盖 4MB,镜像层动辄几十 MB。

改完验证:

curl -s -o /dev/null -w "%{http_code}\n" https://gitea.88531.cn/v2/    # 期望 401

然后用公网域名推送(走 HTTPS,不需要 insecure-registries):

docker login gitea.88531.cn -u jinghui
REUSE=1 ./scripts/push-image.sh gitea 1.0.1

拉取(外网用户,匿名):

docker pull gitea.88531.cn/jinghui/docker-center:1.0.1

多架构(amd64 + arm64)

群晖/飞牛 ARM 机型、Mac M 系列、树莓派都是 arm64。想一个镜像通吃:

# 一次性装 qemu 模拟(本机当前没装)
docker run --privileged --rm tonistiigi/binfmt --install all

MULTIARCH=1 NAMESPACE=jinghui ./scripts/push-image.sh aliyun 1.0.0

buildx 会直接 --push,不会在本地留镜像。


版本号怎么打

  • 每次功能变更 → 1.0.1、1.1.0 递增,同时覆盖 latest
  • 不删旧版本(用户可能锁版本),仓库里累积
  • 本仓库 CHANGELOG.md 与 tag 对应,方便用户对版本

常见报错

报错 原因 解决
unauthorized: reqPackageAccess token 缺 package 权限 用 --scopes write:package 重新签发
Get .../v2/: EOF 走隧道/被墙 换局域网地址或用云仓库
http: server gave HTTP response to HTTPS client 未加 insecure-registries 加进 daemon.json 后 systemctl reload docker
denied: requested access to the resource is denied 命名空间/仓库名不对,或没登录 核对控制台的 registry 地址与命名空间
层一直 Retrying 上传带宽不够/代理不稳 换云仓库,或 MULTIARCH=0 单架构推