# 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：

```text
mrlee/havline:1.9.0
```

使用带认证的 Registry API 可以正常读取 OCI index。Docker CLI 的
`push` 与 `pull` 仍然失败：

```text
failed to authorize: failed to fetch oauth token:
authorization server did not include a token in the response
```

## 二、根因

Gitea 当前生成的 Registry 认证地址是 HTTP：

```text
WWW-Authenticate: Bearer realm="http://jayhub.top/v2/token",
service="container_registry",scope="*"
```

实际 token 接口已经通过 HTTPS 提供服务。Docker 遇到 HTTP 到 HTTPS 的
跨协议跳转时，会丢掉用于换取 token 的 Basic 认证信息，最终拿不到带权限
的 token。

同时，匿名请求得到的 token 没有 `pull` scope：

```text
scope=[]
user=-1
```

这意味着飞牛设备在没有 Registry 登录凭据时，即使服务器修好 realm，也
仍然会被公开包的认证策略拦截。仓库和包本身虽然是 public，但当前 Gitea
Registry 仍要求客户端登录。

## 三、服务器端修复

### 1. 修正 Gitea 的 ROOT_URL

编辑 Gitea 的 `app.ini`，把 `ROOT_URL` 从 HTTP 改为 HTTPS：

```ini
[server]
ROOT_URL = https://jayhub.top/
```

### 2. 确保 Nginx 传递正确协议

在 Gitea 的反向代理配置中加入：

```nginx
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

```bash
docker restart gitea
```

如果容器名不同，先执行：

```bash
docker ps --format '{{.Names}} {{.Image}}'
```

### 4. 验证 realm

```bash
curl -sSI https://jayhub.top/v2/ | grep -i www-authenticate
```

期望结果：

```text
WWW-Authenticate: Bearer realm="https://jayhub.top/v2/token",
service="container_registry",scope="*"
```

### 5. 验证 Docker 拉取

```bash
docker pull jayhub.top/mrlee/havline:1.9.0
```

如果本机已经登录过 `jayhub.top`，先执行一次：

```bash
docker logout jayhub.top
docker login jayhub.top
```

## 四、飞牛端仍被 401 拦截时的处理

### 方案 A：在飞牛设备登录 Registry（推荐用于继续使用 Gitea）

在飞牛终端中执行：

```bash
docker login jayhub.top -u mrlee
```

密码建议使用 Gitea Personal Access Token，而不是账号密码。Token 权限
至少需要：

```text
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 客户端直接推送：

```powershell
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`。

## 六、发布前检查清单

```text
[ ] Gitea ROOT_URL 已改为 https://jayhub.top/
[ ] Nginx 已传递 X-Forwarded-Proto https
[ ] curl /v2/ 返回的 realm 是 https
[ ] docker pull 在干净客户端上成功
[ ] 飞牛设备无需额外操作即可安装
[ ] amd64 与 arm64 镜像都能被设备拉取
```