feat(core): migrate admin updater to R2 latest.json manifest

- Replace GitHub Releases path with ADMIN_UPDATE.s3BaseUrl + latest.json (default https://admin-r2.innei.dev).
- UpdateService.fetchAdminManifest resolves {version,url,sha256?}; leader streams via UpdateDownloadService.downloadDirect with sha256 verification.
- Restrict GitHub auth header to api.github.com hosts so the R2 fetch stays anonymous.
- Relax update.controller cross-version gate to block only major jumps; minor/patch upgrade freely.
- Drop dead ADMIN_DASHBOARD_REPO constant and pageproxy GH-release helper.
- release.yml latest.json now includes sha256 to match admin-release.yml.

Author: Innei

.github/workflows/release.yml

@@ -114,11 +114,13 @@ jobs:
           ADMIN_ZIP="admin-${ADMIN_VERSION}.zip"
           # Package the locally-built admin (apps/admin/dist) with a top-level dist/ wrapper.
           ( cd apps/admin && zip -r "../../${ADMIN_ZIP}" dist )
+          SHA="$(sha256sum "${ADMIN_ZIP}" | awk '{print $1}')"
           cat > latest.json <<EOF
           {
             "version": "${ADMIN_VERSION}",
             "file": "${ADMIN_ZIP}",
             "url": "${ADMIN_PUBLIC_BASE%/}/${ADMIN_ZIP}",
+            "sha256": "${SHA}",
             "tag": "${{ github.ref_name }}"
           }
           EOF

.husky/pre-commit

@@ -0,0 +1,12 @@
+#!/bin/sh
+
+if [ "$SKIP_SIMPLE_GIT_HOOKS" = "1" ]; then
+    echo "[INFO] SKIP_SIMPLE_GIT_HOOKS is set to 1, skipping hook."
+    exit 0
+fi
+
+if [ -f "$SIMPLE_GIT_HOOKS_RC" ]; then
+    . "$SIMPLE_GIT_HOOKS_RC"
+fi
+
+pnpm lint-staged

apps/core/src/app.config.ts

@@ -199,10 +199,10 @@ const commander = program
   .option('--pg_max_pool_size <number>', 'PostgreSQL pool size')
   .option('--pg_ssl', 'enable PostgreSQL TLS')
 
-  // admin asset update (reserved)
+  // admin asset update — R2 manifest base URL (default points at the public bucket)
   .option(
     '--admin_update_s3_base_url <string>',
-    'reserved: S3 base URL for admin asset updates (empty = disabled, falls back to GitHub releases)',
+    'S3/R2 base URL hosting latest.json + admin-<version>.zip',
   )
 
 commander.parse()
@@ -388,12 +388,12 @@ export const POSTGRES = {
       : false,
 }
 
-// Reserved for the future electron-style admin asset update source.
-// When `s3BaseUrl` is non-empty, the admin updater will fetch a `latest.json`
-// manifest + admin zip from S3 instead of GitHub releases. Empty string is the
-// "disabled" sentinel, keeping the current GitHub upgrade path as the default.
+// Admin asset update source. `latest.json` and `admin-<version>.zip` are read
+// from this base URL. Default points at the public R2 bucket that release.yml
+// and admin-release.yml publish to; override with --admin_update_s3_base_url or
+// ADMIN_UPDATE_S3_BASE_URL when self-hosting the bucket.
 export const ADMIN_UPDATE = {
   s3BaseUrl: (argv.admin_update_s3_base_url ||
     process.env.ADMIN_UPDATE_S3_BASE_URL ||
-    '') as string,
+    'https://admin-r2.innei.dev') as string,
 }

apps/core/src/constants/admin.constant.ts

@@ -89,13 +89,6 @@ export class AdminDownloadManager {
   private startDownload(): void {
     this.initialize()
 
-    // TODO(admin-update S3): future electron-style update source.
-    // When `ADMIN_UPDATE.s3BaseUrl` (env ADMIN_UPDATE_S3_BASE_URL) is set, fetch a
-    // `latest.json` manifest from S3 to resolve the newest admin version + zip URL,
-    // download that zip, and install it via the existing extract/install path —
-    // instead of querying GitHub releases. This is only RESERVED for now: the
-    // built-in admin (built locally at core build time) is the default served asset,
-    // and the GitHub upgrade path below remains the unchanged active behavior.
     this.updateService
       .getLatestAdminVersion()
       .then((version) => {

apps/core/src/modules/pageproxy/admin-download.manager.ts

@@ -5,7 +5,6 @@ import { Injectable, InternalServerErrorException } from '@nestjs/common'
 import { parseHTML } from 'linkedom'
 
 import { API_VERSION } from '~/app.config'
-import { ADMIN_DASHBOARD_REPO } from '~/constants/admin.constant'
 
 import { ConfigsService } from '../configs/configs.service'
 import { OwnerService } from '../owner/owner.service'
@@ -22,26 +21,6 @@ export class PageProxyService {
     return adminExtra.enableAdminProxy || isDev
   }
 
-  /**
-   * @returns {Promise<string>} version `x.y.z` , not startwith `v`
-   * @throws {Error}
-   */
-  async getAdminLastestVersionFromGHRelease(): Promise<string> {
-    const thirdParty = await this.configs.get(
-      'thirdPartyServiceIntegration',
-    )
-    const githubToken = thirdParty.github?.token
-    const response = await fetch(
-      `https://api.github.com/repos/${ADMIN_DASHBOARD_REPO}/releases/latest`,
-      {
-        headers: githubToken ? { Authorization: `Bearer ${githubToken}` } : {},
-      },
-    )
-    const { tag_name } = await response.json()
-
-    return tag_name.replace(/^v/, '')
-  }
-
   async injectAdminEnv(
     htmlEntry: string,
     env: {

apps/core/src/modules/pageproxy/pageproxy.service.ts

@@ -1,3 +1,5 @@
+import { createHash } from 'node:crypto'
+
 import { Injectable } from '@nestjs/common'
 import axios, { AxiosRequestConfig } from 'axios'
 import pc from 'picocolors'
@@ -65,14 +67,15 @@ export class UpdateDownloadService {
     config: AxiosRequestConfig = {},
     retries = this.MAX_RETRIES,
   ): Promise<any> {
+    const isGitHubApiRequest = this.shouldAttachGitHubAuth(url)
     const thirdParty = await this.configService.get(
       'thirdPartyServiceIntegration',
     )
-    const githubToken = thirdParty.github?.token
+    const githubToken = thirdParty?.github?.token
     const token = githubToken || process.env.GITHUB_TOKEN
     const headers = {
       ...config.headers,
-      ...(token && { Authorization: `Bearer ${token}` }),
+      ...(token && isGitHubApiRequest && { Authorization: `Bearer ${token}` }),
     }
 
     for (let attempt = 1; attempt <= retries; attempt++) {
@@ -88,7 +91,11 @@ export class UpdateDownloadService {
 
         if (attempt === retries) {
           let finalMsg = `Failed after ${retries} attempts: ${errorMsg}`
-          if (axios.isAxiosError(error) && error.response?.status === 403) {
+          if (
+            isGitHubApiRequest &&
+            axios.isAxiosError(error) &&
+            error.response?.status === 403
+          ) {
             finalMsg +=
               ' (API Rate Limit Exceeded. Please configure GitHub Token in settings or env GITHUB_TOKEN)'
           }
@@ -101,6 +108,14 @@ export class UpdateDownloadService {
     }
   }
 
+  private shouldAttachGitHubAuth(url: string) {
+    try {
+      return new URL(url).hostname === 'api.github.com'
+    } catch {
+      return false
+    }
+  }
+
   async downloadWithMirrors(
     originalUrl: string,
     expectedSize: number,
@@ -139,6 +154,27 @@ export class UpdateDownloadService {
     return null
   }
 
+  async downloadDirect(
+    url: string,
+    pushProgress: (msg: string) => Promise<void>,
+    opts: { sha256?: string } = {},
+  ): Promise<ArrayBuffer> {
+    await pushProgress(`Downloading ${url}\n`)
+    const buffer = await this.downloadWithProgress(url, pushProgress)
+    if (opts.sha256) {
+      const actual = createHash('sha256')
+        .update(Buffer.from(buffer))
+        .digest('hex')
+      if (actual !== opts.sha256.toLowerCase()) {
+        throw new Error(
+          `Checksum mismatch: expected sha256 ${opts.sha256}, got ${actual}`,
+        )
+      }
+      await pushProgress(pc.green('Checksum verified.\n'))
+    }
+    return buffer
+  }
+
   private async downloadWithProgress(
     url: string,
     pushProgress: (msg: string) => Promise<void>,

apps/core/src/modules/update/update-download.service.ts

@@ -5,7 +5,7 @@ import path from 'node:path'
 import { Query, Sse } from '@nestjs/common'
 import pc from 'picocolors'
 import { catchError, Observable } from 'rxjs'
-import { lt, major, minor } from 'semver'
+import { lt, major } from 'semver'
 
 import { ApiController } from '~/common/decorators/api-controller.decorator'
 import { Auth } from '~/common/decorators/auth.decorator'
@@ -48,9 +48,20 @@ export class UpdateController {
           path.join(adminAssetRoot, 'index.html'),
         )
 
+        let latestVersion: string
+        try {
+          latestVersion = await this.service.getLatestAdminVersion()
+        } catch (error: any) {
+          observer.next(
+            pc.red(`Fetching latest admin version error: ${error.message}\n`),
+          )
+          observer.complete()
+          return
+        }
+
         if (!isExistLocalAdmin) {
           await pipeStream(
-            this.service.startClusterAdminAssetUpdate(currentVersion),
+            this.service.startClusterAdminAssetUpdate(latestVersion),
           )
           observer.complete()
           return
@@ -70,29 +81,16 @@ export class UpdateController {
           }
         }
 
-        let latestVersion: string
-        try {
-          latestVersion = await this.service.getLatestAdminVersion()
-        } catch (error: any) {
-          observer.next(
-            pc.red(`Fetching latest admin version error: ${error.message}\n`),
-          )
-          observer.complete()
-          return
-        }
-
         if (!lt(currentVersion, latestVersion)) {
           observer.next(pc.green(`Admin dashboard is up to date.\n`))
           observer.complete()
           return
         }
-        const isCrossVersion =
-          minor(currentVersion) !== minor(latestVersion) ||
-          major(currentVersion) !== major(latestVersion)
-        if (!force && !isDev && isCrossVersion) {
+        const isMajorJump = major(currentVersion) !== major(latestVersion)
+        if (!force && !isDev && isMajorJump) {
           observer.next(
             pc.red(
-              `The latest version is ${latestVersion}, current version is ${currentVersion}, can not cross-version upgrade.\n`,
+              `Major version jump ${currentVersion} -> ${latestVersion} requires force=true.\n`,
             ),
           )
           observer.complete()

apps/core/src/modules/update/update.controller.ts

@@ -1,4 +1,3 @@
-import { rm } from 'node:fs/promises'
 import { hostname } from 'node:os'
 
 import {
@@ -10,16 +9,22 @@ import {
 import pc from 'picocolors'
 import { Observable, ReplaySubject } from 'rxjs'
 
-import { ADMIN_DASHBOARD_REPO } from '~/constants/admin.constant'
+import { ADMIN_UPDATE } from '~/app.config'
 import { RedisService } from '~/processors/redis/redis.service'
 
 import { UpdateDownloadService } from './update-download.service'
 import { UpdateInstallService } from './update-install.service'
 
-const repo = ADMIN_DASHBOARD_REPO
-
 const REDIS_KEY_PREFIX = 'update:admin'
 
+interface AdminUpdateManifest {
+  version: string
+  file: string
+  url: string
+  sha256?: string
+  tag?: string
+}
+
 const LUA_RELEASE_LOCK = `
 if redis.call("get", KEYS[1]) == ARGV[1] then
   return redis.call("del", KEYS[1])
@@ -196,47 +201,22 @@ export class UpdateService implements OnModuleInit, OnModuleDestroy {
           .catch(() => {})
       }
 
-      const endpoint = `https://api.github.com/repos/${repo}/releases/tags/v${version}`
-      await pushProgress(`Getting release info from ${endpoint}.\n`)
-
-      const releaseInfo = await this.downloadService.fetchWithRetry(endpoint, {
-        timeout: 30000,
-        headers: {
-          'User-Agent': 'Mix-Space-Admin-Updater',
-          Accept: 'application/vnd.github.v3+json',
-        },
-      })
-
-      if (!releaseInfo?.assets) {
-        throw new Error('Release assets not found')
-      }
-
-      const asset = releaseInfo.assets.find(
-        (asset: any) => asset.name === 'release.zip',
-      )
-
-      if (!asset) {
-        const msg = `release.zip not found. Available: ${releaseInfo.assets.map((a: any) => a.name).join(', ')}`
-        throw new Error(msg)
+      const manifest = await this.fetchAdminManifest()
+      if (manifest.version !== version) {
+        throw new Error(
+          `Admin manifest version mismatch: requested ${version}, got ${manifest.version}`,
+        )
       }
-
-      const downloadUrl = asset.browser_download_url
-      const fileSize = asset.size
-
       await pushProgress(
-        `Found release.zip (${this.downloadService.formatBytes(fileSize)})\n`,
+        `Resolved admin v${manifest.version} → ${manifest.url}\n`,
       )
 
-      const buffer = await this.downloadService.downloadWithMirrors(
-        downloadUrl,
-        fileSize,
+      const buffer = await this.downloadService.downloadDirect(
+        manifest.url,
         async (msg: string) => pushProgress(msg),
+        { sha256: manifest.sha256 },
       )
 
-      if (!buffer) {
-        throw new Error('All download sources failed')
-      }
-
       await pushProgress('Storing buffer to Redis for other instances...\n')
       await this.redis.setex(
         keys.bufferKey,
@@ -300,7 +280,6 @@ export class UpdateService implements OnModuleInit, OnModuleDestroy {
         .catch(() => {})
 
       subscriber.next(pc.red(`Download failed: ${errorMsg}\n`))
-      await rm('admin-release.zip', { force: true }).catch(() => {})
     } finally {
       clearInterval(heartbeat)
       await this.redis
@@ -548,24 +527,31 @@ export class UpdateService implements OnModuleInit, OnModuleDestroy {
   }
 
   async getLatestAdminVersion() {
-    const endpoint = `https://api.github.com/repos/${repo}/releases/latest`
+    const manifest = await this.fetchAdminManifest()
+    return manifest.version
+  }
 
+  private async fetchAdminManifest(): Promise<AdminUpdateManifest> {
+    const baseUrl = ADMIN_UPDATE.s3BaseUrl?.replace(/\/+$/, '')
+    if (!baseUrl) {
+      throw new Error(
+        'Admin update source is not configured (ADMIN_UPDATE_S3_BASE_URL)',
+      )
+    }
+    const endpoint = `${baseUrl}/latest.json`
     try {
-      const data = await this.downloadService.fetchWithRetry(endpoint, {
-        headers: {
-          'User-Agent': 'Mix-Space-Admin-Updater',
-          Accept: 'application/vnd.github.v3+json',
-        },
-      })
+      const data = (await this.downloadService.fetchWithRetry(endpoint, {
+        timeout: 30000,
+        headers: { Accept: 'application/json' },
+      })) as Partial<AdminUpdateManifest> | undefined
 
-      const tag = data?.tag_name
-      if (!tag) {
-        throw new Error('tag_name not found in release info')
+      if (!data?.version || !data.url) {
+        throw new Error('latest.json missing required fields (version, url)')
       }
-      return tag.replace(/^v/, '')
+      return data as AdminUpdateManifest
     } catch (error) {
       const errorMsg = error instanceof Error ? error.message : String(error)
-      throw new Error(`Failed to get latest version: ${errorMsg}`, {
+      throw new Error(`Failed to fetch admin manifest: ${errorMsg}`, {
         cause: error,
       })
     }