5.1 KiB
Gitea Registry 镜像拉取问题与修复方案
记录时间：2026-10-02 适用范围：
jayhub.top/mrlee/havline与飞牛应用Fnos-Havline
一、当前状态
Havline 1.9.0 的多架构镜像已经通过 Registry HTTP API 上传成功：
| 平台 | 子 manifest |
|---|---|
| linux/amd64 | sha256:83b31003aaa84435bdfc02e5e436d7e23f71e184326002ff8cdc6bba84e4c77c |
| linux/arm64 | sha256:5f30e660bd8ec4563bfe225c69bc5a1cb80b1766655494c2d7bd863f43aa4b06 |
| 多架构索引 | sha256:6eed17af17349bea312b5e1fd8d6fbbde074d157a9e8687a734d9371c59a8db2 |
Registry 中当前 tag：
mrlee/havline:1.9.0
使用带认证的 Registry API 可以正常读取 OCI index。Docker CLI 的
push 与 pull 仍然失败：
failed to authorize: failed to fetch oauth token:
authorization server did not include a token in the response
二、根因
Gitea 当前生成的 Registry 认证地址是 HTTP：
WWW-Authenticate: Bearer realm="http://jayhub.top/v2/token",
service="container_registry",scope="*"
实际 token 接口已经通过 HTTPS 提供服务。Docker 遇到 HTTP 到 HTTPS 的 跨协议跳转时，会丢掉用于换取 token 的 Basic 认证信息，最终拿不到带权限 的 token。
同时，匿名请求得到的 token 没有 pull scope：
scope=[]
user=-1
这意味着飞牛设备在没有 Registry 登录凭据时，即使服务器修好 realm，也 仍然会被公开包的认证策略拦截。仓库和包本身虽然是 public，但当前 Gitea Registry 仍要求客户端登录。
三、服务器端修复
1. 修正 Gitea 的 ROOT_URL
编辑 Gitea 的 app.ini，把 ROOT_URL 从 HTTP 改为 HTTPS：
[server]
ROOT_URL = https://jayhub.top/
2. 确保 Nginx 传递正确协议
在 Gitea 的反向代理配置中加入：
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
如果你使用的是宝塔、1Panel 或飞牛自带的反代，请在对应站点配置中确认
X-Forwarded-Proto 没有被覆盖为 http。
3. 重启 Gitea
docker restart gitea
如果容器名不同，先执行：
docker ps --format '{{.Names}} {{.Image}}'
4. 验证 realm
curl -sSI https://jayhub.top/v2/ | grep -i www-authenticate
期望结果：
WWW-Authenticate: Bearer realm="https://jayhub.top/v2/token",
service="container_registry",scope="*"
5. 验证 Docker 拉取
docker pull jayhub.top/mrlee/havline:1.9.0
如果本机已经登录过 jayhub.top，先执行一次：
docker logout jayhub.top
docker login jayhub.top
四、飞牛端仍被 401 拦截时的处理
方案 A：在飞牛设备登录 Registry（推荐用于继续使用 Gitea）
在飞牛终端中执行：
docker login jayhub.top -u mrlee
密码建议使用 Gitea Personal Access Token，而不是账号密码。Token 权限 至少需要：
read:package
登录后再安装 havline-1.9.0.fpk。这种方式需要每台安装设备执行一次登录，
不适合完全没有终端操作经验的使用者。
方案 B：改为离线镜像包（推荐给最终用户）
如果希望完全绕开 Gitea Registry 的认证和 realm 问题，可以把 docker save
生成的镜像归档放进飞牛 .fpk，并在安装回调中执行 docker load。这样
安装过程不依赖外网 Registry，也不需要在飞牛设备上保存 Registry 凭据。
这个方案的代价是 .fpk 体积会显著增加，需要同时评估飞牛应用中心的上传
限制和升级包体积。
方案 C：改用允许匿名拉取的公共 Registry
如果继续发布给普通用户使用，建议把镜像推送到 Docker Hub、GHCR 或其它 允许匿名拉取多架构镜像的 Registry，再把飞牛 Compose 中的镜像地址改成 对应的公共地址。这个方案的用户体验最好，但需要额外的 Registry 账号和 发布流程。
五、应急手动推送工具
在 Gitea realm 修好之前，可以使用下面的脚本绕过 Docker 客户端直接推送：
docker buildx build `
--platform linux/amd64 `
--build-arg VERSION_FILE=VERSION `
--output type=oci,dest=build\havline-amd64.oci.tar .
tar -xf build\havline-amd64.oci.tar -C build\havline-amd64
pwsh scripts/push-oci-manual.ps1 `
-LayoutDir build\havline-amd64 `
-Platform linux/amd64 `
-Tag 1.9.0
脚本会从 Git 凭据存储中读取 jayhub.top 的登录信息，通过 HTTPS 请求
Bearer token，再直接调用 Registry HTTP API 上传缺失 blob 和 manifest。
这个脚本只是应急工具，不能替代服务器端的 ROOT_URL 修复。服务器修好
之后，应恢复使用标准的 docker buildx build --push。
六、发布前检查清单
[ ] Gitea ROOT_URL 已改为 https://jayhub.top/
[ ] Nginx 已传递 X-Forwarded-Proto https
[ ] curl /v2/ 返回的 realm 是 https
[ ] docker pull 在干净客户端上成功
[ ] 飞牛设备无需额外操作即可安装
[ ] amd64 与 arm64 镜像都能被设备拉取