docs: document Gitea registry OAuth fix and add manual OCI pusher

2026-10-02 13:26:27 +08:00
parent 244297f96c
commit 9ca5da4523
3 changed files with 312 additions and 0 deletions
@@ -22,6 +22,7 @@ scripts/*
 !scripts/havline-install.sh
 !scripts/upgrade.sh
 !scripts/upgrade-hub.sh
+!scripts/push-oci-manual.ps1
 # 本地压缩包与导出产物不入库（如 web/src.rar）
 *.rar
 *.zip
@@ -0,0 +1,185 @@
+# 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 镜像都能被设备拉取
+```
@@ -0,0 +1,126 @@
+<#
+Manual OCI layout pusher for registries whose token realm is misconfigured.
+
+This script is an emergency fallback. It reads Docker's OCI layout output,
+obtains a Bearer token over HTTPS from the Git credential store, and uploads
+the blobs and image manifest directly through the Registry HTTP API.
+#>
+param(
+  [Parameter(Mandatory = $true)][string]$LayoutDir,
+  [Parameter(Mandatory = $true)][string]$Platform,
+  [Parameter(Mandatory = $true)][string]$Tag,
+  [string]$Registry = "jayhub.top",
+  [string]$Repository = "mrlee/havline",
+  [string]$CredentialHost = "jayhub.top"
+)
+
+$ErrorActionPreference = "Stop"
+$script:Registry = $Registry
+$script:Repository = $Repository
+
+function Get-RegistryBasicAuth {
+  $cred = "protocol=https`nhost=$CredentialHost`n`n" | git credential fill 2>$null
+  $values = @{}
+  $cred -split "`n" | ForEach-Object {
+    if ($_ -match '^(.*?)=(.*)$') { $values[$matches[1]] = $matches[2] }
+  }
+  if (-not $values.username -or -not $values.password) {
+    throw "No Git credential found for $CredentialHost"
+  }
+  $raw = $values.username + ":" + $values.password
+  return "Basic " + [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($raw))
+}
+
+function Get-BearerToken([string]$Scope) {
+  $basic = Get-RegistryBasicAuth
+  $url = "https://$Registry/v2/token?service=container_registry&scope=$Scope"
+  $response = Invoke-RestMethod -Uri $url -Headers @{ Authorization = $basic }
+  if (-not $response.token) { throw "Registry did not return a token" }
+  return $response.token
+}
+
+function Get-BlobPath([string]$LayoutRoot, [string]$Digest) {
+  return Join-Path $LayoutRoot ("blobs\sha256\" + ($Digest -replace '^sha256:', ''))
+}
+
+function Read-JsonBlob([string]$LayoutRoot, [string]$Digest) {
+  $path = Get-BlobPath $LayoutRoot $Digest
+  return Get-Content $path -Raw | ConvertFrom-Json
+}
+
+function Find-PlatformManifest($Index, [string]$Arch, [string]$Os) {
+  foreach ($entry in $Index.manifests) {
+    if ($entry.platform.architecture -eq $Arch -and $entry.platform.os -eq $Os) {
+      return $entry
+    }
+  }
+  return $null
+}
+
+function Resolve-ImageManifest([string]$LayoutRoot, [string]$Arch, [string]$Os) {
+  $index = Get-Content (Join-Path $LayoutRoot "index.json") -Raw | ConvertFrom-Json
+  foreach ($entry in $index.manifests) {
+    $document = Read-JsonBlob $LayoutRoot $entry.digest
+    if ($document.mediaType -eq "application/vnd.oci.image.manifest.v1+json") {
+      return @{ Digest = $entry.digest; Document = $document }
+    }
+    $match = Find-PlatformManifest $document $Arch $Os
+    if ($match) {
+      return @{ Digest = $match.digest; Document = (Read-JsonBlob $LayoutRoot $match.digest) }
+    }
+  }
+  throw "No image manifest found for $Os/$Arch"
+}
+
+function Test-BlobExists([string]$Digest, [string]$Token) {
+  $url = "https://$Registry/v2/$Repository/blobs/$Digest"
+  $response = Invoke-WebRequest -Uri $url -Method Head -Headers @{ Authorization = "Bearer $Token" } -SkipHttpErrorCheck
+  return $response.StatusCode -eq 200
+}
+
+function Push-Blob([string]$LayoutRoot, [string]$Digest, [string]$Token) {
+  if (Test-BlobExists $Digest $Token) {
+    Write-Output "Blob already exists: $Digest"
+    return
+  }
+  $postUrl = "https://$Registry/v2/$Repository/blobs/uploads/"
+  $post = Invoke-WebRequest -Uri $postUrl -Method Post -Headers @{ Authorization = "Bearer $Token" } -SkipHttpErrorCheck
+  if ($post.StatusCode -ne 202) { throw "Create upload session failed: HTTP $($post.StatusCode)" }
+  $location = $post.Headers["Location"]
+  if ($location -is [array]) { $location = $location[0] }
+  if ($location -notmatch '^https?://') { $location = "https://$Registry$location" }
+  $separator = "?"
+  if ($location -match '\?') { $separator = "&" }
+  $putUrl = $location + $separator + "digest=" + $Digest
+  $path = Get-BlobPath $LayoutRoot $Digest
+  $curlArgs = @(
+    "-sS", "-o", "NUL", "-w", "%{http_code}", "-X", "PUT",
+    "-H", "Authorization: Bearer $Token",
+    "-H", "Content-Type: application/octet-stream",
+    "--data-binary", ("@" + $path), $putUrl
+  )
+  $status = (& curl.exe @curlArgs).Trim()
+  if ($status -ne "201") { throw "Upload blob failed: $Digest -> HTTP $status" }
+  Write-Output "Uploaded blob: $Digest"
+}
+
+function Push-Manifest([string]$TagValue, [string]$MediaType, [string]$Json, [string]$Token) {
+  $url = "https://$Registry/v2/$Repository/manifests/$TagValue"
+  $response = Invoke-WebRequest -Uri $url -Method Put -Headers @{ Authorization = "Bearer $Token" } -ContentType $MediaType -Body ([Text.Encoding]::UTF8.GetBytes($Json)) -SkipHttpErrorCheck
+  if ($response.StatusCode -ne 201) {
+    throw "Push manifest failed: HTTP $($response.StatusCode) $($response.Content)"
+  }
+  return $response.Headers["Docker-Content-Digest"]
+}
+
+$parts = $Platform -split "/"
+if ($parts.Count -ne 2) { throw "Platform must look like linux/amd64" }
+$layoutRoot = (Resolve-Path $LayoutDir).Path
+$manifest = Resolve-ImageManifest $layoutRoot $parts[1] $parts[0]
+$allBlobs = @($manifest.Document.config.digest) + @($manifest.Document.layers | ForEach-Object { $_.digest })
+$token = Get-BearerToken "repository:$Repository`:push,pull"
+foreach ($blob in $allBlobs) { Push-Blob $layoutRoot $blob $token }
+$manifestJson = Get-Content (Get-BlobPath $layoutRoot $manifest.Digest) -Raw
+$digest = Push-Manifest $Tag $manifest.Document.mediaType $manifestJson $token
+Write-Output "Manifest: $digest"
+Write-Output ("Tag: {0}/{1}:{2}" -f $Registry, $Repository, $Tag)