fix: make all self-managed file downloads/installs atomic, with real completion status (#5711)

* fix(script): download the live x-ui.sh script atomically before replacing it

update_menu(), update_shell(), and update.sh's update_x-ui() all overwrote
/usr/bin/x-ui in place via `curl -o`, truncating and rewriting the same
inode a currently-running x-ui process may still be reading from. A
network hiccup or slow write during that overwrite leaves a
half-old/half-new script on disk, which then fails with bogus syntax
errors on the next run. Download to /usr/bin/x-ui-temp and `mv -f` into
place instead, matching the atomic pattern install.sh already uses.

Also fixes update_menu() checking chmod's exit code instead of curl's,
which meant a failed download could still report "Update successful."

* fix(script): close remaining gaps in the atomic script-update path

Code review of the previous commit found the atomic mv fix was itself
incomplete:

- None of the mv -f calls checked their exit status, so a failed move
  fell through to chmod and "success" messaging while /usr/bin/x-ui
  stayed on the old file.
- update_shell()'s `[[ -s x-ui-temp ]]` guard couldn't tell "curl -z
  got a 304, nothing to do" from "a stale temp file survived an
  earlier crashed run" -- the latter could get moved into place with
  no freshness check.
- update_menu(), update_shell(), and update_x-ui() all hardcoded the
  same /usr/bin/x-ui-temp path, so two concurrent updates (e.g. a
  cron auto-update racing an interactive menu update) could collide.
- update.sh's update_x-ui() was missing the non-empty-file guard
  update_shell() already had.

x-ui.sh's update_menu() and update_shell() now share a
replace_xui_script() helper that uses a PID-suffixed temp path
(/usr/bin/x-ui-temp.$$), pre-cleans it before every attempt, and
checks the exit status of curl, the non-empty test, and mv before
treating the update as successful. update.sh's update_x-ui() gets the
same sequence inlined (it's fetched as a standalone script and can't
call x-ui.sh's function), closing the missing-guard gap and using its
own unique temp path.

* fix(script,panel): harden the remaining self-update download paths

install.sh had the same unguarded /usr/bin/x-ui-temp overwrite the two
already-fixed scripts had: no exit-status check on mv, and a fixed temp
name shared with x-ui.sh/update.sh's (now-unique) temp files. Give it
its own PID-suffixed temp path, an empty-file guard, and an mv
exit-status check, matching the pattern used there.

Audited the web dashboard's Go-native updater (panel.go) for the same
bug class: it already uses os.CreateTemp for a genuinely unique temp
file and cleans up via both a deferred Remove and a shell EXIT trap, so
it was never exposed to the fixed-path race. It was missing a check
for a zero-byte download (a 200 OK with an empty body would chmod +x
and exec an empty script) -- added that alongside the existing size
cap.

Not addressed here: once startUpdate()'s child process starts, the Go
service releases it and returns success immediately. If update.sh
fails partway through, the still-running old panel keeps answering
/status, so the frontend's poll can report success with no update
having happened. Fixing that needs update.sh to signal completion
status back and the frontend to check it -- a separate follow-up.

* feat(panel): report real completion status for the web self-update

Fixes the fire-and-forget gap flagged in the atomic-overwrite fix: once
startUpdate() launches update.sh detached, the Go service had no way to
learn whether it actually succeeded. If update.sh failed partway
(network drop, disk full, permission denied), the still-running old
panel kept answering /status, so the frontend's poll reported success
with nothing having changed.

update.sh now writes its outcome to a small JSON status file
(/etc/x-ui/update-status.json by default) via `trap ... EXIT`, which
covers every exit path in the script -- including the two bare `exit 1`
call sites that don't go through the existing _fail() helper. The Go
service generates a run ID before launching, passes it and the status
path to update.sh via XUI_UPDATE_RUN_ID/XUI_UPDATE_STATUS_FILE, and a
new GET /panel/api/server/getUpdateStatus endpoint reports it back. The
frontend now polls that instead of blindly trusting HTTP reachability,
and shows a distinct error or "couldn't confirm" message instead of
silently reloading into a false success.

Adversarial review of this surfaced three more issues, fixed here:
- No lock stopped two concurrent /updatePanel calls from launching two
  update.sh runs that would race each other on the actual update work
  (tar extraction, service unit swap). Added an in-memory guard with a
  5-minute self-expiring window, so a run that never reaches a terminal
  state doesn't lock out retries indefinitely.
- XUI_UPDATE_RUN_ID is read from the environment and was interpolated
  unquoted into the status JSON; a malformed value would produce
  invalid JSON. Now validated as digits-only before use.
- The run ID is a UnixNano timestamp (19 digits), sent as a raw JSON
  number it would lose precision in JavaScript (past
  Number.MAX_SAFE_INTEGER), letting two different runs round to the
  same value on the wire and defeat the whole comparison. It's now a
  decimal string end to end (Go, the status file, and the generated
  frontend type).

install.sh's equivalent temp-file/mv path and the Go-native
downloadPanelUpdater() path were audited for the same bug classes
during this work; findings from that audit were addressed separately.

* fix(panel): release the update lock as soon as the run finishes

An exhaustive multi-angle review of the whole branch (12 finder angles,
3-vote adversarial verification, a fresh-eyes sweep) surfaced a real
bug in the concurrency guard added in the previous commit, plus several
smaller issues; this fixes what's actionable now.

The bug: acquireUpdateSlot only ever released on the 5-minute stale
timeout or if launching itself failed. If update.sh launched fine but
failed fast (bad GitHub API response, "x-ui not installed", any of its
early exit paths), the status file correctly reported "failed" within
seconds, but a retry was still rejected with "a panel update is
already in progress" for up to 5 more minutes -- the guard never
looked at the very status file this branch built to know a run was
done. It now tracks which run ID currently holds the slot and checks
that run's own status before falling back to the timeout, so a fast
failure clears the way for an immediate retry. Added a regression test
for this, plus one confirming a stale, unrelated runID can't be
mistaken for the current run finishing.

Also:
- Added a genuinely concurrent test for the guard: 200 goroutines
  racing acquireUpdateSlot, asserting exactly one wins. The previous
  tests only ever called it from one goroutine, so they gave no signal
  if the mutex's check-then-set were silently broken -- verified this
  by temporarily removing the lock and confirming the old tests still
  passed while the new one caught it immediately under -race.
- Removed the redundant upfront "pending" status write: GetUpdateStatus
  already defaults a missing/stale file to pending, and the frontend
  matches by run ID regardless, so the write changed no observable
  behavior. Deleted writeUpdateStatus entirely since that was its only
  caller.
- Renamed replace_xui_script()'s unclear "conditional" parameter to
  use_if_modified_since, matching what it actually controls.
- Added HTTP-level tests for the new getUpdateStatus endpoint,
  including a regression test that the runId wire format is a JSON
  string (decoding into a Go string field fails outright if it were
  ever a bare number). updatePanel's actual launch path is not
  covered: on a Linux test runner it would make a real network call
  and could exec a real update.sh, so only its non-Linux guard path is
  safely testable without mocking.

Not fixed here, tracked separately: the same unsafe-overwrite pattern
this branch eliminated for /usr/bin/x-ui is still present for the
systemd unit file install in update.sh and install.sh (lower severity
since systemd only reads it on daemon-reload, not continuously); and
startUpdate's systemd-run-vs-detached-fallback branching has no test
coverage since testing it safely needs dependency injection this fix
doesn't warrant bundling in.

* fix(script): make systemd unit file installation atomic

Same anti-pattern as the /usr/bin/x-ui overwrite fixed earlier: every
site that lands the systemd unit at ${xui_service}/x-ui.service --
copying it from the extracted release tarball, or falling back to a
GitHub download per distro family -- wrote straight onto the live
path via cp/curl, no temp file, no verification. A network drop
mid-download or an interrupted cp leaves the unit file truncated;
systemd then fails to parse it on the next daemon-reload/start,
leaving the panel unable to come up until an operator manually
re-copies a good unit file.

Lower severity than the /usr/bin/x-ui case (systemd only reads this
file on demand at daemon-reload time, not continuously the way bash
interprets a running script line by line), but it's the identical
gap, just left uncovered when that fix landed.

Added a small shared helper in both update.sh and install.sh --
_install_xui_service_unit() -- covering both source types (cp from
the tarball, curl from GitHub): write to a PID-suffixed temp file,
verify the copy/download succeeded and the result is non-empty, then
mv -f into place and check that exit status too, matching the pattern
already used for /usr/bin/x-ui. All 4 cp sites and the 3-way curl
fallback in each file now go through it; verified no other site
writes new content to the unit path (the remaining ${xui_service}
references are a pre-install existence check, an rm during old-version
cleanup, and the chown/chmod that already ran after the file is safely
in place -- none of those need atomicity).

Verified with bash -n on both files, plus a standalone scratch test
exercising cp-success, cp-with-missing-source, cp-with-empty-source,
and curl-failure paths: on every failure the previous, good unit file
content is left untouched and no temp file is leaked behind.

* fix(script): make Alpine's OpenRC init script install atomic; drop a stray comment

A final maximum-rigor review of the whole PR (12 finder angles including
a repo-wide sweep for any remaining instance of the bug class this PR
fixes) found two more real issues:

- Alpine's /etc/init.d/x-ui startup script is downloaded via a bare
  `curl -fLRo` straight onto the live path in both update.sh and
  install.sh -- the exact same unguarded-overwrite pattern already
  fixed for /usr/bin/x-ui and the systemd unit file, just left
  uncovered on the OpenRC side. A network drop mid-download truncates
  the live init script; OpenRC then fails to source/execute it on the
  next start, leaving the panel unable to come up. Fixed with the same
  temp-file + non-empty check + mv -f (with its own exit-status check)
  pattern used everywhere else in this PR. Verified with bash -n and a
  standalone scratch-script test covering success, empty-download, and
  destination-preserved-on-failure paths.

- internal/web/service/panel/panel_test.go had one line-level `//`
  comment on a call site, which the root CLAUDE.md's hard rule ("No //
  line comments in committed Go/TS... rename instead of annotating")
  explicitly prohibits. The comment duplicated context already stated
  in the test's own doc comment two lines above, so it's simply
  removed rather than reworded.

Also flagged, deliberately not bundled here since it's a different
subsystem: x-ui.sh's update_geofiles() downloads Xray's live
geoip.dat/geosite.dat with the same unguarded curl -o pattern. Tracked
as its own follow-up.

* fix(script): make geo-data file downloads atomic

Same anti-pattern as /usr/bin/x-ui, the systemd unit file, and the
Alpine init script fixed in prior PRs: update_geofiles() downloaded
Xray's live geoip.dat/geosite.dat (and the IR/RU variants) with curl
writing straight onto the exact path Xray reads at runtime
(internal/xray/process.go's GetGeoipPath/GetGeositePath), no temp
file, no verification. The existing check only inspected the reported
HTTP status via -w '%{http_code}', not file integrity, so a network
drop mid-download could leave a truncated .dat file on disk that
passes the status check. Xray then fails to parse it on the next
restart/reload, breaking any routing rules that reference geoip:/
geosite:.

The -z conditional-GET usage needed care here: the original code
pointed both -z and -o at the same live path. Fixed by pointing -z at
the live file (to keep the "already current" freshness check) while
-o writes to a PID-suffixed temp file, matching the pattern already
proven in x-ui.sh's replace_xui_script(). Verified with a local HTTP
server that a 304 response leaves the temp file untouched/nonexistent
(so the existing "already up to date" branch still works unchanged),
and added a non-empty check plus a checked mv -f before treating a
download as installed.

Verified with bash -n and an end-to-end scratch test against a local
server covering: fresh download, 304-not-modified, empty response
body, and a 404 -- confirming a failure at any stage leaves the
previous good .dat file completely untouched and no temp file behind.

* fix(script): verify the release tarball extraction, not just the download

The final maximum-rigor review found the most significant remaining gap
in this whole effort: update.sh and install.sh check the tarball
download's exit status, but never check tar's exit status, and never
verify the extracted x-ui binary actually exists before continuing.
Worse, by the time extraction runs, the previous installation has
already been stopped and deleted -- there's no rollback. A truncated
download that still passes curl's own check, or a tar failure (disk
full, killed process), left the panel silently in a broken half-state:
chmod/config/service-install all continued to run against a missing or
empty binary, with no error surfaced anywhere. This is the same bug
class as everything else in this PR (unverified write to a path
something then depends on), just for the tarball itself rather than a
single file -- and it also covers the geo-data files this PR already
fixed once for the interactive/cron path, since they ship inside this
same tarball on every panel update.

Added: a non-empty check on the downloaded archive (both files, both
install.sh call sites) and a check that tar succeeded and produced a
non-empty x-ui binary before proceeding, failing loudly with a message
that explicitly says the previous install is already gone, since
silently continuing here is worse than anywhere else in this PR.

This doesn't make the multi-file extraction fully atomic (that would
mean extracting to a temp directory and atomically swapping the whole
install tree into place, a materially larger restructuring than
anything else in this PR) -- but it closes the "fails silently, user
discovers it days later when Xray can't start" gap, which was the
actual reported problem this whole effort traces back to.

Also fixed, all much smaller:
- replace_xui_script() in x-ui.sh implicitly returned chmod's exit
  status instead of success, so a successful atomic install could be
  reported as failed if chmod transiently failed after the mv already
  landed the new script. Added an explicit `return 0`.
- update_geofiles() had no default case branch; an unrecognized
  argument would silently reuse whatever dat_files/dat_source values a
  previous call left in the un-scoped globals instead of failing.
  Currently unreachable (all three call sites pass fixed literals) but
  cheap, defensive, and worth having.
- internal/web/controller/server.go's updatePanel has one branch (an
  unparseable "dev" form value) that's both untested and safe to test
  on any platform, since it's rejected before any real exec/network
  call. Added the missing test case.

Verified: bash -n on all three scripts; an empirical scratch test
covering an empty downloaded archive, a corrupt (non-gzip) archive,
and a successfully-extracting-but-empty archive, confirming each is
caught before the script proceeds; full go build/vet/test -race
across the whole module; frontend generation confirmed still in sync.

* fix(panel): base the update-slot staleness fallback on process liveness

Addresses the automated review on the upstream PR (MHSanaei/3x-ui#5711).

Blocking finding: acquireUpdateSlot's staleness fallback freed the
update slot purely on elapsed wall-clock time (5 minutes), with no
check on whether the update.sh process it launched was actually still
running. update.sh runs install_base() (apt-get/dnf/pacman update and
install) before update_x-ui even starts, plus several GitHub
downloads (release tarball, x-ui.sh, and possibly a service unit or
x-ui.rc) -- on a slow or throttled host, a small VPS being the typical
deployment target for this project, that alone can plausibly exceed 5
minutes with nothing wrong. A second /updatePanel call arriving in
that window (an admin retrying after the frontend's 90s poll times
out, or overlapping master-node bulk-update calls) would launch a
second update.sh, racing the exact rm/tar/mv/systemctl sequence this
whole PR exists to make safe.

Fixed by recording the launched process's PID (detached-fallback path
only; the systemd-run path's own process has already exited by the
time startUpdate returns, so it never learns update.sh's real PID) and
checking it via the standard POSIX kill(pid, 0) liveness probe before
treating a run as stale, following the existing panel_unix.go /
panel_other.go platform-split pattern already used for
setDetachedProcess. A confirmed-alive process now keeps the slot held
past updateStaleAfter (raised from 5 to 20 minutes as a safer baseline
for the systemd-run path, which still has no way to check liveness
directly). updateHardCeiling (2 hours) is an absolute backstop so a
genuinely wedged run can never lock out retries permanently even on
the PID-tracked path.

Added two regression tests exercising the new logic (gated to Linux,
since processAlive is a no-op stub elsewhere): a live PID keeps the
slot held past the stale window, and the hard ceiling overrides
liveness. Traced both by hand against the new acquireUpdateSlot logic;
could not execute-verify processAlive itself on this Windows dev
machine (no WSL distro installed, and installing one felt
disproportionate to validate kill(pid, 0), an extremely well-established
POSIX primitive), but cross-compiled clean for linux/amd64 and this
repo's CI runs the real test suite on Linux.

Also fixed, both suggestions from the same review:
- install.sh: two failure paths right after tarball extraction were
  exiting without cleaning up the already-downloaded x-ui.sh temp file
  (xui_script_temp), leaving it behind. Every other new failure branch
  in this PR removes its temp file before exiting; these two now do
  too.
- frontend/src/pages/api-docs/endpoints.ts: updatePanel's doc entry
  did not reflect that a successful response now carries an obj with
  runId. Added an inline response example matching the existing
  pattern used for other ad hoc (non-schema-backed) responses like
  getWebCertFiles.

Verified: go build/vet clean on both windows (native) and a linux/amd64
cross-compile; full go test ./... clean; go test -race on the panel
and controller packages; bash -n on all three shell scripts; npm run
gen confirms the openapi.json diff is exactly the new response example
with no stray changes to src/generated; TestAPIRoutesDocumented still
passes.

frontend/public/openapi.json

@@ -2147,6 +2147,34 @@
         ],
         "type": "object"
       },
+      "PanelUpdateStatus": {
+        "description": "PanelUpdateStatus reports the outcome of the most recently launched panel\nself-update. RunID lets the caller confirm this status belongs to the\nupdate it started rather than a stale result left over from an earlier\nrun; State is one of \"pending\", \"success\", or \"failed\". RunID is a decimal\nstring, not a JSON number: it's a formatted UnixNano timestamp, and\nJavaScript's number type can't represent that precisely (it exceeds\nNumber.MAX_SAFE_INTEGER), which would let two different runs round to the\nsame value on the wire and defeat the whole point of this field.",
+        "properties": {
+          "exitCode": {
+            "example": 0,
+            "type": "integer"
+          },
+          "finishedAt": {
+            "example": 1735689612,
+            "type": "integer"
+          },
+          "runId": {
+            "example": "1735689600123456789",
+            "type": "string"
+          },
+          "state": {
+            "example": "success",
+            "type": "string"
+          }
+        },
+        "required": [
+          "exitCode",
+          "finishedAt",
+          "runId",
+          "state"
+        ],
+        "type": "object"
+      },
       "ProbeResultUI": {
         "properties": {
           "cpuPct": {
@@ -3901,6 +3929,47 @@
         }
       }
     },
+    "/panel/api/server/getUpdateStatus": {
+      "get": {
+        "tags": [
+          "Server"
+        ],
+        "summary": "Report the outcome of the most recently launched panel self-update (see POST updatePanel). Compare the returned runId against the one updatePanel returned to tell this run apart from a stale result.",
+        "operationId": "get_panel_api_server_getUpdateStatus",
+        "responses": {
+          "200": {
+            "description": "Successful response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "success": {
+                      "type": "boolean"
+                    },
+                    "msg": {
+                      "type": "string"
+                    },
+                    "obj": {
+                      "$ref": "#/components/schemas/PanelUpdateStatus"
+                    }
+                  }
+                },
+                "example": {
+                  "success": true,
+                  "obj": {
+                    "exitCode": 0,
+                    "finishedAt": 1735689612,
+                    "runId": "1735689600123456789",
+                    "state": "success"
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/panel/api/server/getConfigJson": {
       "get": {
         "tags": [
@@ -4427,6 +4496,12 @@
                     },
                     "obj": {}
                   }
+                },
+                "example": {
+                  "success": true,
+                  "obj": {
+                    "runId": "1735689600123456789"
+                  }
                 }
               }
             }

frontend/src/generated/examples.ts

@@ -468,6 +468,12 @@ export const EXAMPLES: Record<string, unknown> = {
     "total": 0,
     "up": 0
   },
+  "PanelUpdateStatus": {
+    "exitCode": 0,
+    "finishedAt": 1735689612,
+    "runId": "1735689600123456789",
+    "state": "success"
+  },
   "ProbeResultUI": {
     "cpuPct": 12.5,
     "error": "",

frontend/src/generated/schemas.ts

@@ -2121,6 +2121,34 @@ export const SCHEMAS: Record<string, unknown> = {
     ],
     "type": "object"
   },
+  "PanelUpdateStatus": {
+    "description": "PanelUpdateStatus reports the outcome of the most recently launched panel\nself-update. RunID lets the caller confirm this status belongs to the\nupdate it started rather than a stale result left over from an earlier\nrun; State is one of \"pending\", \"success\", or \"failed\". RunID is a decimal\nstring, not a JSON number: it's a formatted UnixNano timestamp, and\nJavaScript's number type can't represent that precisely (it exceeds\nNumber.MAX_SAFE_INTEGER), which would let two different runs round to the\nsame value on the wire and defeat the whole point of this field.",
+    "properties": {
+      "exitCode": {
+        "example": 0,
+        "type": "integer"
+      },
+      "finishedAt": {
+        "example": 1735689612,
+        "type": "integer"
+      },
+      "runId": {
+        "example": "1735689600123456789",
+        "type": "string"
+      },
+      "state": {
+        "example": "success",
+        "type": "string"
+      }
+    },
+    "required": [
+      "exitCode",
+      "finishedAt",
+      "runId",
+      "state"
+    ],
+    "type": "object"
+  },
   "ProbeResultUI": {
     "properties": {
       "cpuPct": {

frontend/src/generated/types.ts

@@ -464,6 +464,13 @@ export interface OutboundTraffics {
   up: number;
 }
 
+export interface PanelUpdateStatus {
+  exitCode: number;
+  finishedAt: number;
+  runId: string;
+  state: string;
+}
+
 export interface ProbeResultUI {
   cpuPct: number;
   error: string;

frontend/src/generated/zod.ts

@@ -495,6 +495,14 @@ export const OutboundTrafficsSchema = z.object({
 });
 export type OutboundTraffics = z.infer<typeof OutboundTrafficsSchema>;
 
+export const PanelUpdateStatusSchema = z.object({
+  exitCode: z.number().int(),
+  finishedAt: z.number().int(),
+  runId: z.string(),
+  state: z.string(),
+});
+export type PanelUpdateStatus = z.infer<typeof PanelUpdateStatusSchema>;
+
 export const ProbeResultUISchema = z.object({
   cpuPct: z.number(),
   error: z.string(),

frontend/src/pages/api-docs/endpoints.ts

@@ -323,6 +323,12 @@ export const sections: readonly Section[] = [
         path: '/panel/api/server/getPanelUpdateInfo',
         summary: 'Check whether a newer 3x-ui release is available on GitHub.',
       },
+      {
+        method: 'GET',
+        path: '/panel/api/server/getUpdateStatus',
+        summary: 'Report the outcome of the most recently launched panel self-update (see POST updatePanel). Compare the returned runId against the one updatePanel returned to tell this run apart from a stale result.',
+        responseSchema: 'PanelUpdateStatus',
+      },
       {
         method: 'GET',
         path: '/panel/api/server/getConfigJson',
@@ -407,6 +413,7 @@ export const sections: readonly Section[] = [
         method: 'POST',
         path: '/panel/api/server/updatePanel',
         summary: 'Self-update the panel to the latest version. The server restarts on success.',
+        response: '{\n  "success": true,\n  "obj": {\n    "runId": "1735689600123456789"\n  }\n}',
       },
       {
         method: 'POST',

frontend/src/pages/index/PanelUpdateModal.tsx

@@ -6,8 +6,11 @@ import axios from 'axios';
 
 import { HttpUtil, PromiseUtil } from '@/utils';
 import { formatPanelVersion } from '@/lib/panel-version';
+import type { PanelUpdateStatus } from '@/generated/types';
 import './PanelUpdateModal.css';
 
+type UpdateOutcome = 'success' | 'failed' | 'timeout';
+
 export interface PanelUpdateInfo {
   channel?: string;
   currentVersion: string;
@@ -45,19 +48,23 @@ export default function PanelUpdateModal({
 
   const isDev = info.channel === 'dev';
 
-  async function pollUntilBack(): Promise<boolean> {
+  async function pollUpdateStatus(expectedRunId: string): Promise<UpdateOutcome> {
     await PromiseUtil.sleep(5000);
     const deadline = Date.now() + 90_000;
     while (Date.now() < deadline) {
       try {
-        const r = await axios.get('/panel/api/server/status', { timeout: 2000 });
-        if (r?.data?.success) return true;
+        const r = await axios.get('/panel/api/server/getUpdateStatus', { timeout: 2000 });
+        const status = r?.data?.obj as PanelUpdateStatus | undefined;
+        if (status?.runId === expectedRunId) {
+          if (status.state === 'success') return 'success';
+          if (status.state === 'failed') return 'failed';
+        }
       } catch {
         /* still restarting */
       }
       await PromiseUtil.sleep(2000);
     }
-    return false;
+    return 'timeout';
   }
 
   async function handleChannel(checked: boolean) {
@@ -81,14 +88,24 @@ export default function PanelUpdateModal({
         const tip = info.latestVersion ? `${baseTip} (${info.latestVersion})` : baseTip;
         onClose();
         onBusy({ busy: true, tip });
-        const result = await HttpUtil.post('/panel/api/server/updatePanel');
+        const result = await HttpUtil.post<{ runId: string }>('/panel/api/server/updatePanel');
         if (!result?.success) {
           onBusy({ busy: false });
           return;
         }
-        const back = await pollUntilBack();
-        if (back) await PromiseUtil.sleep(800);
-        window.location.reload();
+        const outcome = await pollUpdateStatus(result.obj?.runId ?? '');
+        onBusy({ busy: false });
+        if (outcome === 'success') {
+          await PromiseUtil.sleep(800);
+          window.location.reload();
+          return;
+        }
+        modal[outcome === 'failed' ? 'error' : 'warning']({
+          title: t(outcome === 'failed' ? 'pages.index.panelUpdateFailedTitle' : 'pages.index.panelUpdateUnknownTitle'),
+          content: t(outcome === 'failed' ? 'pages.index.panelUpdateFailedDesc' : 'pages.index.panelUpdateUnknownDesc'),
+          okText: t('refresh'),
+          onOk: () => window.location.reload(),
+        });
       },
     });
   }

install.sh

@@ -1326,6 +1326,40 @@ setup_fail2ban() {
     return 0
 }
 
+# Lands a systemd unit file at ${xui_service}/x-ui.service via a temp file +
+# atomic mv, so a failed cp/curl or an interrupted mv never leaves a
+# truncated unit file at the live path -- systemd would then fail to parse
+# it on the next daemon-reload/start. Same pattern already used for
+# /usr/bin/x-ui elsewhere in this script. source_is_url picks cp (from a
+# file already extracted from the release tarball) vs curl (GitHub fallback).
+_install_xui_service_unit() {
+    local source="$1"
+    local source_is_url="$2"
+    local dest="${xui_service}/x-ui.service"
+    local temp_file="${dest}.tmp.$$"
+
+    rm -f "$temp_file"
+    if [[ "$source_is_url" == "true" ]]; then
+        curl -fLRo "$temp_file" "$source" > /dev/null 2>&1
+    else
+        cp -f "$source" "$temp_file" > /dev/null 2>&1
+    fi
+    if [[ $? -ne 0 ]]; then
+        rm -f "$temp_file"
+        return 1
+    fi
+    if [[ ! -s "$temp_file" ]]; then
+        rm -f "$temp_file"
+        return 1
+    fi
+    mv -f "$temp_file" "$dest"
+    if [[ $? -ne 0 ]]; then
+        rm -f "$temp_file"
+        return 1
+    fi
+    return 0
+}
+
 install_x-ui() {
     cd ${xui_folder%/x-ui}/
 
@@ -1342,6 +1376,11 @@ install_x-ui() {
             echo -e "${red}Downloading x-ui failed, please be sure that your server can access GitHub ${plain}"
             exit 1
         fi
+        if [[ ! -s ${xui_folder}-linux-$(arch).tar.gz ]]; then
+            rm ${xui_folder}-linux-$(arch).tar.gz -f
+            echo -e "${red}Downloaded x-ui release archive is empty${plain}"
+            exit 1
+        fi
     else
         tag_version=$1
         # The rolling dev channel ships under a fixed, non-semver tag that is
@@ -1367,12 +1406,25 @@ install_x-ui() {
             echo -e "${red}Download x-ui ${tag_version} failed, please check if the version exists ${plain}"
             exit 1
         fi
+        if [[ ! -s ${xui_folder}-linux-$(arch).tar.gz ]]; then
+            rm ${xui_folder}-linux-$(arch).tar.gz -f
+            echo -e "${red}Downloaded x-ui release archive is empty${plain}"
+            exit 1
+        fi
     fi
-    curl -fLRo /usr/bin/x-ui-temp https://raw.githubusercontent.com/MHSanaei/3x-ui/main/x-ui.sh
+    local xui_script_temp="/usr/bin/x-ui-temp.$$"
+    rm -f "${xui_script_temp}"
+    curl -fLRo "${xui_script_temp}" https://raw.githubusercontent.com/MHSanaei/3x-ui/main/x-ui.sh
     if [[ $? -ne 0 ]]; then
+        rm -f "${xui_script_temp}"
         echo -e "${red}Failed to download x-ui.sh${plain}"
         exit 1
     fi
+    if [[ ! -s "${xui_script_temp}" ]]; then
+        rm -f "${xui_script_temp}"
+        echo -e "${red}Downloaded x-ui.sh is empty${plain}"
+        exit 1
+    fi
 
     # Stop x-ui service and remove old resources
     if [[ -e ${xui_folder}/ ]]; then
@@ -1391,9 +1443,20 @@ install_x-ui() {
 
     # Extract resources and set permissions
     tar zxvf x-ui-linux-$(arch).tar.gz
+    if [[ $? -ne 0 ]]; then
+        rm x-ui-linux-$(arch).tar.gz -f
+        rm -f "${xui_script_temp}"
+        echo -e "${red}Failed to extract the x-ui release archive -- the previous installation has already been removed, so the panel will not start until this is fixed; try running the installer again${plain}"
+        exit 1
+    fi
     rm x-ui-linux-$(arch).tar.gz -f
 
     cd x-ui
+    if [[ $? -ne 0 || ! -s x-ui ]]; then
+        rm -f "${xui_script_temp}"
+        echo -e "${red}Extracted x-ui archive is missing the x-ui binary -- the previous installation has already been removed, so the panel will not start until this is fixed; try running the installer again${plain}"
+        exit 1
+    fi
     chmod +x x-ui
     chmod +x x-ui.sh
 
@@ -1414,7 +1477,12 @@ install_x-ui() {
     fi
 
     # Update x-ui cli and se set permission
-    mv -f /usr/bin/x-ui-temp /usr/bin/x-ui
+    mv -f "${xui_script_temp}" /usr/bin/x-ui
+    if [[ $? -ne 0 ]]; then
+        rm -f "${xui_script_temp}"
+        echo -e "${red}Failed to install x-ui.sh${plain}"
+        exit 1
+    fi
     chmod +x /usr/bin/x-ui
     mkdir -p /var/log/x-ui
     config_after_install
@@ -1434,11 +1502,25 @@ install_x-ui() {
     fi
 
     if [[ $release == "alpine" ]]; then
-        curl -fLRo /etc/init.d/x-ui https://raw.githubusercontent.com/MHSanaei/3x-ui/main/x-ui.rc
+        xui_rc_temp="/etc/init.d/x-ui.tmp.$$"
+        rm -f "${xui_rc_temp}"
+        curl -fLRo "${xui_rc_temp}" https://raw.githubusercontent.com/MHSanaei/3x-ui/main/x-ui.rc
         if [[ $? -ne 0 ]]; then
+            rm -f "${xui_rc_temp}"
             echo -e "${red}Failed to download x-ui.rc${plain}"
             exit 1
         fi
+        if [[ ! -s "${xui_rc_temp}" ]]; then
+            rm -f "${xui_rc_temp}"
+            echo -e "${red}Downloaded x-ui.rc is empty${plain}"
+            exit 1
+        fi
+        mv -f "${xui_rc_temp}" /etc/init.d/x-ui
+        if [[ $? -ne 0 ]]; then
+            rm -f "${xui_rc_temp}"
+            echo -e "${red}Failed to install x-ui.rc${plain}"
+            exit 1
+        fi
         chmod +x /etc/init.d/x-ui
         rc-update add x-ui
         rc-service x-ui start
@@ -1448,8 +1530,7 @@ install_x-ui() {
 
         if [ -f "x-ui.service" ]; then
             echo -e "${green}Found x-ui.service in extracted files, installing...${plain}"
-            cp -f x-ui.service ${xui_service}/ > /dev/null 2>&1
-            if [[ $? -eq 0 ]]; then
+            if _install_xui_service_unit "x-ui.service" "false"; then
                 service_installed=true
             fi
         fi
@@ -1459,8 +1540,7 @@ install_x-ui() {
                 ubuntu | debian | armbian)
                     if [ -f "x-ui.service.debian" ]; then
                         echo -e "${green}Found x-ui.service.debian in extracted files, installing...${plain}"
-                        cp -f x-ui.service.debian ${xui_service}/x-ui.service > /dev/null 2>&1
-                        if [[ $? -eq 0 ]]; then
+                        if _install_xui_service_unit "x-ui.service.debian" "false"; then
                             service_installed=true
                         fi
                     fi
@@ -1468,8 +1548,7 @@ install_x-ui() {
                 arch | manjaro | parch)
                     if [ -f "x-ui.service.arch" ]; then
                         echo -e "${green}Found x-ui.service.arch in extracted files, installing...${plain}"
-                        cp -f x-ui.service.arch ${xui_service}/x-ui.service > /dev/null 2>&1
-                        if [[ $? -eq 0 ]]; then
+                        if _install_xui_service_unit "x-ui.service.arch" "false"; then
                             service_installed=true
                         fi
                     fi
@@ -1477,8 +1556,7 @@ install_x-ui() {
                 *)
                     if [ -f "x-ui.service.rhel" ]; then
                         echo -e "${green}Found x-ui.service.rhel in extracted files, installing...${plain}"
-                        cp -f x-ui.service.rhel ${xui_service}/x-ui.service > /dev/null 2>&1
-                        if [[ $? -eq 0 ]]; then
+                        if _install_xui_service_unit "x-ui.service.rhel" "false"; then
                             service_installed=true
                         fi
                     fi
@@ -1491,17 +1569,17 @@ install_x-ui() {
             echo -e "${yellow}Service files not found in tar.gz, downloading from GitHub...${plain}"
             case "${release}" in
                 ubuntu | debian | armbian)
-                    curl -fLRo ${xui_service}/x-ui.service https://raw.githubusercontent.com/MHSanaei/3x-ui/main/x-ui.service.debian > /dev/null 2>&1
+                    service_unit_url="https://raw.githubusercontent.com/MHSanaei/3x-ui/main/x-ui.service.debian"
                     ;;
                 arch | manjaro | parch)
-                    curl -fLRo ${xui_service}/x-ui.service https://raw.githubusercontent.com/MHSanaei/3x-ui/main/x-ui.service.arch > /dev/null 2>&1
+                    service_unit_url="https://raw.githubusercontent.com/MHSanaei/3x-ui/main/x-ui.service.arch"
                     ;;
                 *)
-                    curl -fLRo ${xui_service}/x-ui.service https://raw.githubusercontent.com/MHSanaei/3x-ui/main/x-ui.service.rhel > /dev/null 2>&1
+                    service_unit_url="https://raw.githubusercontent.com/MHSanaei/3x-ui/main/x-ui.service.rhel"
                     ;;
             esac
 
-            if [[ $? -ne 0 ]]; then
+            if ! _install_xui_service_unit "$service_unit_url" "true"; then
                 echo -e "${red}Failed to install x-ui.service from GitHub${plain}"
                 exit 1
             fi

internal/config/config.go

@@ -169,6 +169,14 @@ func GetDBPath() string {
 	return fmt.Sprintf("%s/%s.db", GetDBFolderPath(), GetName())
 }
 
+// GetUpdateStatusFilePath returns the path to the panel self-update status
+// file update.sh writes on completion. It lives beside the database, outside
+// XUI_MAIN_FOLDER, so it survives an update regardless of what happens to
+// that folder.
+func GetUpdateStatusFilePath() string {
+	return filepath.Join(GetDBFolderPath(), "update-status.json")
+}
+
 // GetDBKind returns the configured database backend: "sqlite" (default) or "postgres".
 func GetDBKind() string {
 	v := strings.ToLower(strings.TrimSpace(os.Getenv("XUI_DB_TYPE")))

internal/web/controller/panel_update_test.go

@@ -0,0 +1,152 @@
+package controller
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"os"
+	"runtime"
+	"strings"
+	"testing"
+
+	"github.com/mhsanaei/3x-ui/v3/internal/config"
+
+	"github.com/gin-gonic/gin"
+)
+
+// newPanelUpdateTestEngine registers only updatePanel/getUpdateStatus directly
+// on the controller's zero value, bypassing NewServerController's cron/metrics
+// setup (unrelated to these two handlers, and unnecessary weight for a unit
+// test). Callers must set up a DB first (newHostTestDB(t)) since StartUpdate
+// reads the dev-channel setting before doing anything else.
+func newPanelUpdateTestEngine() *gin.Engine {
+	a := &ServerController{}
+	engine := gin.New()
+	engine.GET("/panel/api/server/getUpdateStatus", a.getUpdateStatus)
+	engine.POST("/panel/api/server/updatePanel", a.updatePanel)
+	return engine
+}
+
+func doPanelUpdateReq(t *testing.T, engine *gin.Engine, method, path string) hostEnvelope {
+	t.Helper()
+	req := httptest.NewRequest(method, path, nil)
+	w := httptest.NewRecorder()
+	engine.ServeHTTP(w, req)
+	if w.Code != http.StatusOK {
+		t.Fatalf("%s %s: status %d, body=%s", method, path, w.Code, w.Body.String())
+	}
+	var env hostEnvelope
+	if err := json.Unmarshal(w.Body.Bytes(), &env); err != nil {
+		t.Fatalf("%s %s: decode envelope: %v body=%s", method, path, err, w.Body.String())
+	}
+	return env
+}
+
+// TestGetUpdateStatus_NoStatusFileYet exercises the read-only status endpoint
+// with no prior update having run: it must report "pending" (not an error),
+// since a missing status file is an expected, ordinary state, not a failure.
+func TestGetUpdateStatus_NoStatusFileYet(t *testing.T) {
+	newHostTestDB(t)
+	engine := newPanelUpdateTestEngine()
+
+	env := doPanelUpdateReq(t, engine, http.MethodGet, "/panel/api/server/getUpdateStatus")
+	if !env.Success {
+		t.Fatalf("getUpdateStatus should always report success=true (it's a best-effort read): msg=%s", env.Msg)
+	}
+	var status struct {
+		RunID string `json:"runId"`
+		State string `json:"state"`
+	}
+	if err := json.Unmarshal(env.Obj, &status); err != nil {
+		t.Fatalf("decode status: %v", err)
+	}
+	if status.State != "pending" {
+		t.Fatalf("State = %q, want %q", status.State, "pending")
+	}
+}
+
+// TestGetUpdateStatus_RunIdIsAlwaysAString is the regression test for the
+// precision bug found in review: RunID is a 19-digit UnixNano timestamp, so
+// it must round-trip over the wire as a JSON string, never a bare number -- a
+// bare number would silently lose precision in JavaScript past
+// Number.MAX_SAFE_INTEGER, breaking every future runId comparison on the
+// frontend. Decoding into a Go string field below only succeeds if the wire
+// value is actually a JSON string; a bare number there would fail to decode,
+// so this test doubles as the wire-format check.
+func TestGetUpdateStatus_RunIdIsAlwaysAString(t *testing.T) {
+	newHostTestDB(t)
+	engine := newPanelUpdateTestEngine()
+
+	statusPath := config.GetUpdateStatusFilePath()
+	body := `{"runId":"1735689600123456789","state":"success","exitCode":0,"finishedAt":1735689612}`
+	if err := os.WriteFile(statusPath, []byte(body), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	env := doPanelUpdateReq(t, engine, http.MethodGet, "/panel/api/server/getUpdateStatus")
+	var status struct {
+		RunID string `json:"runId"`
+		State string `json:"state"`
+	}
+	if err := json.Unmarshal(env.Obj, &status); err != nil {
+		t.Fatalf("decode status (would fail here if runId were a bare JSON number instead of a string): %v, body=%s", err, env.Obj)
+	}
+	if status.RunID != "1735689600123456789" {
+		t.Fatalf("RunID = %q, want %q", status.RunID, "1735689600123456789")
+	}
+	if status.State != "success" {
+		t.Fatalf("State = %q, want %q", status.State, "success")
+	}
+}
+
+// TestUpdatePanel_UnsupportedPlatformReturnsNoRunId covers the one path of
+// updatePanel that's safe to exercise in an automated test on any OS/CI
+// runner: the runtime.GOOS != "linux" guard. Actually invoking StartUpdate's
+// launch logic on Linux would make a real network call and could launch a
+// real update.sh process, so that path is deliberately not covered here --
+// see the PR description for why.
+func TestUpdatePanel_UnsupportedPlatformReturnsNoRunId(t *testing.T) {
+	if runtime.GOOS == "linux" {
+		t.Skip("this test only exercises the non-Linux guard path; on Linux, updatePanel would attempt a real download/exec")
+	}
+	newHostTestDB(t)
+	engine := newPanelUpdateTestEngine()
+
+	env := doPanelUpdateReq(t, engine, http.MethodPost, "/panel/api/server/updatePanel")
+	if env.Success {
+		t.Fatal("updatePanel on an unsupported platform: success = true, want false")
+	}
+	if len(env.Obj) != 0 && string(env.Obj) != "null" {
+		t.Fatalf("updatePanel error response must not carry an obj/runId: got %s", env.Obj)
+	}
+}
+
+// TestUpdatePanel_InvalidDevValueRejectedBeforeLaunch covers the one branch of
+// updatePanel that's both untested and safe to exercise on any OS/CI runner:
+// an unparseable "dev" form value is rejected by strconv.ParseBool before
+// StartUpdateChannel (and therefore any real exec/network call) is ever
+// reached, on Linux or otherwise.
+func TestUpdatePanel_InvalidDevValueRejectedBeforeLaunch(t *testing.T) {
+	newHostTestDB(t)
+	engine := newPanelUpdateTestEngine()
+
+	form := url.Values{"dev": {"notabool"}}
+	req := httptest.NewRequest(http.MethodPost, "/panel/api/server/updatePanel", strings.NewReader(form.Encode()))
+	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+	w := httptest.NewRecorder()
+	engine.ServeHTTP(w, req)
+	if w.Code != http.StatusOK {
+		t.Fatalf("status %d, body=%s", w.Code, w.Body.String())
+	}
+	var env hostEnvelope
+	if err := json.Unmarshal(w.Body.Bytes(), &env); err != nil {
+		t.Fatalf("decode envelope: %v body=%s", err, w.Body.String())
+	}
+	if env.Success {
+		t.Fatal("updatePanel with dev=notabool: success = true, want false")
+	}
+	if len(env.Obj) != 0 && string(env.Obj) != "null" {
+		t.Fatalf("updatePanel error response must not carry an obj/runId: got %s", env.Obj)
+	}
+}

internal/web/controller/server.go

@@ -51,6 +51,7 @@ func (a *ServerController) initRouter(g *gin.RouterGroup) {
 	g.GET("/xrayObservatoryHistory/:tag/:bucket", a.getXrayObservatoryHistoryBucket)
 	g.GET("/getXrayVersion", a.getXrayVersion)
 	g.GET("/getPanelUpdateInfo", a.getPanelUpdateInfo)
+	g.GET("/getUpdateStatus", a.getUpdateStatus)
 	g.GET("/getConfigJson", a.getConfigJson)
 	g.GET("/getDb", a.getDb)
 	g.GET("/getMigration", a.getMigration)
@@ -209,21 +210,34 @@ func (a *ServerController) installXray(c *gin.Context) {
 
 // updatePanel starts a panel self-update. With no "dev" form value it follows
 // this panel's own channel setting; an explicit "dev" (sent by the master node
-// updater) overrides it for this run.
+// updater) overrides it for this run. The response's runId identifies this
+// update for a later getUpdateStatus poll.
 func (a *ServerController) updatePanel(c *gin.Context) {
 	devParam := c.PostForm("dev")
+	var runID int64
 	var err error
 	if devParam == "" {
-		err = a.panelService.StartUpdate()
+		runID, err = a.panelService.StartUpdate()
 	} else {
 		dev, perr := strconv.ParseBool(devParam)
 		if perr != nil {
 			jsonMsg(c, "invalid data", perr)
 			return
 		}
-		err = a.panelService.StartUpdateChannel(dev)
+		runID, err = a.panelService.StartUpdateChannel(dev)
 	}
-	jsonMsg(c, I18nWeb(c, "pages.index.panelUpdateStartedPopover"), err)
+	var obj any
+	if err == nil {
+		obj = gin.H{"runId": strconv.FormatInt(runID, 10)}
+	}
+	jsonMsgObj(c, I18nWeb(c, "pages.index.panelUpdateStartedPopover"), obj, err)
+}
+
+// getUpdateStatus reports the outcome of the most recently launched panel
+// self-update (see updatePanel). Compare the returned runId against the one
+// updatePanel returned to tell this run's result apart from a stale one.
+func (a *ServerController) getUpdateStatus(c *gin.Context) {
+	jsonObj(c, a.panelService.GetUpdateStatus(), nil)
 }
 
 // setUpdateChannel toggles whether self-update tracks the rolling dev release.

internal/web/service/panel/panel.go

@@ -13,6 +13,7 @@ import (
 	"runtime"
 	"strconv"
 	"strings"
+	"sync"
 	"syscall"
 	"time"
 
@@ -44,10 +45,64 @@ const (
 	// devReleaseTag is the fixed-tag rolling pre-release the CI force-moves to the
 	// newest main commit; the dev update channel installs from it.
 	devReleaseTag = "dev-latest"
+
+	updateStatePending = "pending"
+	updateStateSuccess = "success"
+	updateStateFailed  = "failed"
 )
 
+// PanelUpdateStatus reports the outcome of the most recently launched panel
+// self-update. RunID lets the caller confirm this status belongs to the
+// update it started rather than a stale result left over from an earlier
+// run; State is one of "pending", "success", or "failed". RunID is a decimal
+// string, not a JSON number: it's a formatted UnixNano timestamp, and
+// JavaScript's number type can't represent that precisely (it exceeds
+// Number.MAX_SAFE_INTEGER), which would let two different runs round to the
+// same value on the wire and defeat the whole point of this field.
+type PanelUpdateStatus struct {
+	RunID      string `json:"runId" example:"1735689600123456789"`
+	State      string `json:"state" example:"success"`
+	ExitCode   int    `json:"exitCode" example:"0"`
+	FinishedAt int64  `json:"finishedAt" example:"1735689612"`
+}
+
 var releaseCommitRegex = regexp.MustCompile(`(?i)commit=([0-9a-f]{7,40})`)
 
+// updateMu guards updateRunning/updateStarted/updateRunID/updatePID, which
+// stop a second self-update from launching while one is still in flight (two
+// concurrent update.sh runs would race each other extracting the release
+// tarball and swapping the service unit). A slot is released as soon as the
+// in-flight run's own status file reports success or failure -- checked
+// against updateRunID so a stale file from an even earlier run can't be
+// mistaken for this one finishing -- so a fast failure doesn't lock out a
+// retry.
+//
+// For a run that never reaches a terminal state at all, staleness is judged
+// primarily by whether the process we actually launched is still alive
+// (updatePID, via processAlive), not by wall-clock time alone: update.sh
+// runs install_base() (a package-manager update+install) before anything
+// else, plus several downloads, which can legitimately run past a short
+// fixed timeout on a slow or throttled host without anything being wrong.
+// updateStaleAfter/updatePID together are only a fallback for the systemd-run
+// launch path, where the process we can observe (systemd-run itself) has
+// already exited by the time startUpdate returns and the actual update.sh
+// unit's PID is never recorded -- for that path this is still a pure
+// wall-clock heuristic. updateHardCeiling is an absolute backstop so a
+// genuinely wedged run (alive but hung forever) can never lock out retries
+// permanently, even on the PID-tracked path.
+var (
+	updateMu      sync.Mutex
+	updateRunning bool
+	updateStarted time.Time
+	updateRunID   int64
+	updatePID     int
+)
+
+const (
+	updateStaleAfter  = 20 * time.Minute
+	updateHardCeiling = 2 * time.Hour
+)
+
 func (s *PanelService) RestartPanel(delay time.Duration) error {
 	go func() {
 		time.Sleep(delay)
@@ -122,39 +177,77 @@ func getDevUpdateInfo() (*PanelUpdateInfo, error) {
 	}, nil
 }
 
-// StartUpdate starts the official updater using this panel's own channel setting.
-func (s *PanelService) StartUpdate() error {
+// StartUpdate starts the official updater using this panel's own channel
+// setting. Returns the run ID to pass to GetUpdateStatus so the caller can
+// tell this run's result apart from a stale one.
+func (s *PanelService) StartUpdate() (int64, error) {
 	return s.startUpdate(devChannelActive())
 }
 
 // StartUpdateChannel runs the updater against an explicitly chosen channel,
 // overriding the local dev-channel setting. Used by the master node updater so
 // a node can be moved to the dev channel from the central panel.
-func (s *PanelService) StartUpdateChannel(dev bool) error {
+func (s *PanelService) StartUpdateChannel(dev bool) (int64, error) {
 	return s.startUpdate(dev)
 }
 
-func (s *PanelService) startUpdate(useDev bool) error {
+// GetUpdateStatus reports the outcome of the most recently launched panel
+// self-update, as recorded by update.sh's EXIT trap (see the script for why
+// that covers every exit path, not just the happy one). This is a best-effort
+// side channel: a missing or unreadable status file reads as "pending"
+// rather than an error, since the update itself is what matters, not this
+// status file.
+func (s *PanelService) GetUpdateStatus() *PanelUpdateStatus {
+	data, err := os.ReadFile(config.GetUpdateStatusFilePath())
+	if err != nil {
+		return &PanelUpdateStatus{State: updateStatePending}
+	}
+	var status PanelUpdateStatus
+	if err := json.Unmarshal(data, &status); err != nil {
+		return &PanelUpdateStatus{State: updateStatePending}
+	}
+	if status.State != updateStateSuccess && status.State != updateStateFailed {
+		status.State = updateStatePending
+	}
+	return &status
+}
+
+func (s *PanelService) startUpdate(useDev bool) (int64, error) {
+	runID := time.Now().UnixNano()
+	if !acquireUpdateSlot(runID) {
+		return 0, fmt.Errorf("a panel update is already in progress")
+	}
+	launched := false
+	defer func() {
+		if !launched {
+			releaseUpdateSlot()
+		}
+	}()
+
 	if runtime.GOOS != "linux" {
-		return fmt.Errorf("panel web update is supported only on Linux installations")
+		return 0, fmt.Errorf("panel web update is supported only on Linux installations")
 	}
 
 	bash, err := exec.LookPath("bash")
 	if err != nil {
-		return fmt.Errorf("bash is required to run the panel updater: %w", err)
+		return 0, fmt.Errorf("bash is required to run the panel updater: %w", err)
 	}
 
 	scriptPath, err := downloadPanelUpdater()
 	if err != nil {
-		return err
+		return 0, err
 	}
 
+	statusFile := config.GetUpdateStatusFilePath()
+
 	mainFolder, serviceFolder := resolveUpdateFolders()
 	updateTag := ""
 	if useDev {
 		updateTag = devReleaseTag
 	}
 	updateScript := fmt.Sprintf("set -e; trap 'rm -f %s' EXIT; %s %s", shellQuote(scriptPath), shellQuote(bash), shellQuote(scriptPath))
+	runIDEnv := "XUI_UPDATE_RUN_ID=" + strconv.FormatInt(runID, 10)
+	statusFileEnv := "XUI_UPDATE_STATUS_FILE=" + statusFile
 
 	if systemdRun, err := exec.LookPath("systemd-run"); err == nil {
 		unitName := fmt.Sprintf("x-ui-web-update-%d", time.Now().Unix())
@@ -163,6 +256,8 @@ func (s *PanelService) startUpdate(useDev bool) error {
 			"--setenv", "XUI_MAIN_FOLDER="+mainFolder,
 			"--setenv", "XUI_SERVICE="+serviceFolder,
 			"--setenv", "XUI_UPDATE_TAG="+updateTag,
+			"--setenv", runIDEnv,
+			"--setenv", statusFileEnv,
 			bash, "-lc", updateScript,
 		)
 		out, err := cmd.CombinedOutput()
@@ -171,12 +266,13 @@ func (s *PanelService) startUpdate(useDev bool) error {
 			if !strings.Contains(output, "System has not been booted with systemd") &&
 				!strings.Contains(output, "Failed to connect to bus") {
 				_ = os.Remove(scriptPath)
-				return fmt.Errorf("failed to start panel update job: %w: %s", err, output)
+				return 0, fmt.Errorf("failed to start panel update job: %w: %s", err, output)
 			}
 			logger.Warning("systemd-run is unavailable, falling back to detached update process:", output)
 		} else {
 			logger.Infof("started panel update job via systemd-run unit %s", unitName)
-			return nil
+			launched = true
+			return runID, nil
 		}
 	}
 
@@ -185,17 +281,77 @@ func (s *PanelService) startUpdate(useDev bool) error {
 		"XUI_MAIN_FOLDER="+mainFolder,
 		"XUI_SERVICE="+serviceFolder,
 		"XUI_UPDATE_TAG="+updateTag,
+		runIDEnv,
+		statusFileEnv,
 	)
 	setDetachedProcess(cmd)
 	if err := cmd.Start(); err != nil {
 		_ = os.Remove(scriptPath)
-		return fmt.Errorf("failed to start panel update job: %w", err)
+		return 0, fmt.Errorf("failed to start panel update job: %w", err)
 	}
 	if err := cmd.Process.Release(); err != nil {
 		logger.Warning("failed to release panel update process:", err)
 	}
 	logger.Infof("started panel update job with pid %d", cmd.Process.Pid)
-	return nil
+	recordUpdatePID(cmd.Process.Pid)
+	launched = true
+	return runID, nil
+}
+
+// acquireUpdateSlot claims the single in-flight-update slot for runID. It
+// refuses while another run is genuinely still in flight, but grants the
+// slot immediately once that run's own status file reports a terminal
+// result (success or failure) -- a fast failure shouldn't force the next
+// attempt to wait out updateStaleAfter for no reason. Past updateStaleAfter
+// with no terminal status yet, it grants the slot anyway UNLESS the process
+// we recorded (updatePID) is confirmed still alive, so a merely-slow run
+// isn't mistaken for a crashed one; past updateHardCeiling it grants the
+// slot unconditionally regardless of liveness, so a truly wedged run can
+// never lock out retries forever.
+func acquireUpdateSlot(runID int64) bool {
+	updateMu.Lock()
+	defer updateMu.Unlock()
+	if updateRunning && !previousRunIsTerminal() {
+		elapsed := time.Since(updateStarted)
+		if elapsed < updateHardCeiling {
+			stale := elapsed >= updateStaleAfter
+			alive := updatePID > 0 && processAlive(updatePID)
+			if !stale || alive {
+				return false
+			}
+		}
+	}
+	updateRunning = true
+	updateStarted = time.Now()
+	updateRunID = runID
+	updatePID = 0
+	return true
+}
+
+// recordUpdatePID notes the PID of the detached update.sh process the
+// current slot is tracking, so a later acquireUpdateSlot call can check
+// whether it is actually still running instead of only how long ago it
+// started. Only reachable for the detached-fallback launch path -- the
+// systemd-run path never learns update.sh's own PID, since the process it
+// directly observes (systemd-run) has already exited by the time it returns.
+func recordUpdatePID(pid int) {
+	updateMu.Lock()
+	updatePID = pid
+	updateMu.Unlock()
+}
+
+// previousRunIsTerminal reports whether the run currently recorded in
+// updateRunID has reached success or failure per its status file. Must be
+// called with updateMu held.
+func previousRunIsTerminal() bool {
+	status := (&PanelService{}).GetUpdateStatus()
+	return status.RunID == strconv.FormatInt(updateRunID, 10) && status.State != updateStatePending
+}
+
+func releaseUpdateSlot() {
+	updateMu.Lock()
+	updateRunning = false
+	updateMu.Unlock()
 }
 
 func downloadPanelUpdater() (string, error) {
@@ -230,6 +386,9 @@ func downloadPanelUpdater() (string, error) {
 	if err != nil {
 		return "", fmt.Errorf("write panel updater: %w", err)
 	}
+	if n == 0 {
+		return "", fmt.Errorf("panel updater download is empty")
+	}
 	if n > maxPanelUpdaterBytes {
 		return "", fmt.Errorf("panel updater exceeds %d bytes", maxPanelUpdaterBytes)
 	}

internal/web/service/panel/panel_other.go

@@ -5,3 +5,10 @@ package panel
 import "os/exec"
 
 func setDetachedProcess(cmd *exec.Cmd) {}
+
+// processAlive is never meaningfully consulted outside Linux: startUpdate
+// itself is gated to runtime.GOOS == "linux" before any process is ever
+// launched, so no real PID is ever recorded on this platform.
+func processAlive(pid int) bool {
+	return false
+}

internal/web/service/panel/panel_test.go

@@ -1,8 +1,15 @@
 package panel
 
 import (
+	"fmt"
+	"os"
+	"runtime"
+	"sync"
+	"sync/atomic"
 	"testing"
+	"time"
 
+	"github.com/mhsanaei/3x-ui/v3/internal/config"
 	"github.com/mhsanaei/3x-ui/v3/internal/web/service"
 )
 
@@ -107,3 +114,207 @@ func TestShortCommit(t *testing.T) {
 		t.Fatalf("shortCommit short input = %q, want %q", got, "abc")
 	}
 }
+
+func resetUpdateSlot(t *testing.T) {
+	t.Helper()
+	t.Cleanup(func() {
+		updateMu.Lock()
+		updateRunning = false
+		updateRunID = 0
+		updatePID = 0
+		updateMu.Unlock()
+	})
+}
+
+// writeStatusFile hand-writes the status file in the exact wire format
+// update.sh itself produces (a bare printf, not Go's json.Marshal), since
+// that's the real cross-language contract this package reads in production.
+func writeStatusFile(t *testing.T, path string, runID int64, state string) {
+	t.Helper()
+	body := fmt.Sprintf(`{"runId":"%d","state":"%s","exitCode":0,"finishedAt":%d}`, runID, state, time.Now().Unix())
+	if err := os.WriteFile(path, []byte(body), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestAcquireUpdateSlot(t *testing.T) {
+	resetUpdateSlot(t)
+
+	if !acquireUpdateSlot(1) {
+		t.Fatal("first acquire: got false, want true")
+	}
+	if acquireUpdateSlot(2) {
+		t.Fatal("second acquire while first is held: got true, want false")
+	}
+	releaseUpdateSlot()
+	if !acquireUpdateSlot(3) {
+		t.Fatal("acquire after release: got false, want true")
+	}
+	releaseUpdateSlot()
+}
+
+func TestAcquireUpdateSlotExpiresAfterStaleWindow(t *testing.T) {
+	resetUpdateSlot(t)
+
+	if !acquireUpdateSlot(1) {
+		t.Fatal("first acquire: got false, want true")
+	}
+	updateMu.Lock()
+	updateStarted = time.Now().Add(-(updateStaleAfter + time.Second))
+	updateMu.Unlock()
+
+	if !acquireUpdateSlot(2) {
+		t.Fatal("acquire after stale window elapsed: got false, want true")
+	}
+	releaseUpdateSlot()
+}
+
+// TestAcquireUpdateSlotWaitsForAliveProcessPastStaleWindow is the regression
+// test for the concurrency bug an upstream review found: past
+// updateStaleAfter, the old logic freed the slot purely on elapsed time, even
+// if the process it launched was still genuinely running (not crashed) --
+// update.sh's own package-manager step plus several downloads can plausibly
+// run long on a slow host with nothing actually wrong. Now a confirmed-alive
+// PID keeps the slot held past the stale window.
+func TestAcquireUpdateSlotWaitsForAliveProcessPastStaleWindow(t *testing.T) {
+	if runtime.GOOS != "linux" {
+		t.Skip("processAlive is a no-op stub on non-Linux; this test only exercises real liveness checking on Linux")
+	}
+	resetUpdateSlot(t)
+
+	if !acquireUpdateSlot(1) {
+		t.Fatal("first acquire: got false, want true")
+	}
+	recordUpdatePID(os.Getpid()) // the test process itself: guaranteed alive
+	updateMu.Lock()
+	updateStarted = time.Now().Add(-(updateStaleAfter + time.Second))
+	updateMu.Unlock()
+
+	if acquireUpdateSlot(2) {
+		t.Fatal("acquire past the stale window while the recorded PID is still alive: got true, want false")
+	}
+	releaseUpdateSlot()
+}
+
+// TestAcquireUpdateSlotHardCeilingOverridesLiveness confirms the absolute
+// backstop: even a confirmed-alive process can't hold the slot forever, so a
+// genuinely wedged run can't lock out retries permanently.
+func TestAcquireUpdateSlotHardCeilingOverridesLiveness(t *testing.T) {
+	if runtime.GOOS != "linux" {
+		t.Skip("processAlive is a no-op stub on non-Linux; this test only exercises real liveness checking on Linux")
+	}
+	resetUpdateSlot(t)
+
+	if !acquireUpdateSlot(1) {
+		t.Fatal("first acquire: got false, want true")
+	}
+	recordUpdatePID(os.Getpid())
+	updateMu.Lock()
+	updateStarted = time.Now().Add(-(updateHardCeiling + time.Second))
+	updateMu.Unlock()
+
+	if !acquireUpdateSlot(2) {
+		t.Fatal("acquire past the hard ceiling despite a live PID: got false, want true")
+	}
+	releaseUpdateSlot()
+}
+
+// TestAcquireUpdateSlotReleasesOnTerminalStatus is the regression test for the
+// bug adversarial review found: a fast failure used to still lock out retries
+// for the full updateStaleAfter window, because acquireUpdateSlot only looked
+// at the in-memory started-at timestamp, never at the status file's own
+// terminal state.
+func TestAcquireUpdateSlotReleasesOnTerminalStatus(t *testing.T) {
+	t.Setenv("XUI_DB_FOLDER", t.TempDir())
+	resetUpdateSlot(t)
+	path := config.GetUpdateStatusFilePath()
+
+	if !acquireUpdateSlot(111) {
+		t.Fatal("first acquire: got false, want true")
+	}
+	writeStatusFile(t, path, 111, updateStateFailed)
+
+	if !acquireUpdateSlot(222) {
+		t.Fatal("acquire after the in-flight run reported failed: got false, want true (should not wait out updateStaleAfter)")
+	}
+	releaseUpdateSlot()
+}
+
+// TestAcquireUpdateSlotIgnoresStaleUnrelatedStatus confirms the terminal-state
+// check is scoped to the run it actually launched: a status file left behind
+// by some earlier, unrelated run (different runID) must not be mistaken for
+// this run finishing.
+func TestAcquireUpdateSlotIgnoresStaleUnrelatedStatus(t *testing.T) {
+	t.Setenv("XUI_DB_FOLDER", t.TempDir())
+	resetUpdateSlot(t)
+	path := config.GetUpdateStatusFilePath()
+
+	writeStatusFile(t, path, 999, updateStateSuccess)
+	if !acquireUpdateSlot(111) {
+		t.Fatal("first acquire: got false, want true")
+	}
+
+	if acquireUpdateSlot(222) {
+		t.Fatal("acquire while status file only reflects an unrelated older runID: got true, want false")
+	}
+	releaseUpdateSlot()
+}
+
+// TestAcquireUpdateSlotConcurrency proves the check-then-set is actually
+// atomic under real concurrent access, not just correct when called
+// sequentially. A prior version of this test suite only ever called
+// acquireUpdateSlot from a single goroutine, so it gave no signal if the
+// mutex's core promise (only one concurrent launch wins) were broken.
+func TestAcquireUpdateSlotConcurrency(t *testing.T) {
+	resetUpdateSlot(t)
+
+	const attempts = 200
+	var wins atomic.Int32
+	var wg sync.WaitGroup
+	wg.Add(attempts)
+	for i := range attempts {
+		go func(runID int64) {
+			defer wg.Done()
+			if acquireUpdateSlot(runID) {
+				wins.Add(1)
+			}
+		}(int64(i))
+	}
+	wg.Wait()
+
+	if got := wins.Load(); got != 1 {
+		t.Fatalf("concurrent acquireUpdateSlot: %d of %d attempts won, want exactly 1", got, attempts)
+	}
+	releaseUpdateSlot()
+}
+
+func TestGetUpdateStatus(t *testing.T) {
+	t.Setenv("XUI_DB_FOLDER", t.TempDir())
+	path := config.GetUpdateStatusFilePath()
+	svc := &PanelService{}
+
+	if got := svc.GetUpdateStatus(); got.State != updateStatePending {
+		t.Fatalf("missing status file: State = %q, want %q", got.State, updateStatePending)
+	}
+
+	writeStatusFile(t, path, 1735689600123456789, updateStateSuccess)
+	got := svc.GetUpdateStatus()
+	if got.RunID != "1735689600123456789" {
+		t.Fatalf("RunID = %q, want %q (must round-trip as a decimal string, not a JSON number, or it loses precision past 2^53 in JS)", got.RunID, "1735689600123456789")
+	}
+	if got.State != updateStateSuccess {
+		t.Fatalf("State = %q, want %q", got.State, updateStateSuccess)
+	}
+
+	if err := os.WriteFile(path, []byte("not json"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if got := svc.GetUpdateStatus(); got.State != updateStatePending {
+		t.Fatalf("corrupt status file: State = %q, want %q", got.State, updateStatePending)
+	}
+
+	writeStatusFile(t, path, 1, "some-unrecognized-state")
+	if got := svc.GetUpdateStatus(); got.State != updateStatePending {
+		t.Fatalf("unrecognized state normalizes to pending: State = %q, want %q", got.State, updateStatePending)
+	}
+}

internal/web/service/panel/panel_unix.go

@@ -10,3 +10,17 @@ import (
 func setDetachedProcess(cmd *exec.Cmd) {
 	cmd.SysProcAttr = &syscall.SysProcAttr{Setsid: true}
 }
+
+// processAlive reports whether pid is still a live process, via the standard
+// POSIX kill(pid, 0) liveness check: it sends no actual signal, only checking
+// whether the target exists and is signalable. ESRCH means the process is
+// gone; any other result (including a permission error, which can only mean
+// the PID exists and belongs to someone) is treated as alive, since this is
+// used to decide whether it is safe to let a second update start.
+func processAlive(pid int) bool {
+	if pid <= 0 {
+		return false
+	}
+	err := syscall.Kill(pid, 0)
+	return err == nil || err == syscall.EPERM
+}

internal/web/translation/ar-EG.json

@@ -231,6 +231,10 @@
       "panelUpdateDialogDesc": "ده هيحدث 3X-UI للإصدار #version# وهيعيد تشغيل البانل.",
       "panelUpdateCheckPopover": "فشل التحقق من تحديث البانل",
       "panelUpdateStartedPopover": "بدأ تحديث البانل",
+      "panelUpdateFailedTitle": "فشل تحديث البانل",
+      "panelUpdateFailedDesc": "لم يكتمل التحديث بنجاح. تحقق من سجلات الخادم، أو نفّذ الأمر «x-ui update» من سطر الأوامر.",
+      "panelUpdateUnknownTitle": "تعذّر التأكد من اكتمال التحديث",
+      "panelUpdateUnknownDesc": "لم تُبلغ اللوحة بنتيجة في الوقت المحدد. أعد تحميل الصفحة للتحقق من الإصدار الحالي، أو تحقق من سجلات الخادم.",
       "geofileUpdateDialog": "هل تريد حقًا تحديث ملف الجغرافيا؟",
       "geofileUpdateDialogDesc": "سيؤدي هذا إلى تحديث ملف #filename#.",
       "geofilesUpdateDialogDesc": "سيؤدي هذا إلى تحديث كافة الملفات.",

internal/web/translation/en-US.json

@@ -231,6 +231,10 @@
       "panelUpdateDialogDesc": "This will update 3X-UI to #version# and restart the panel service.",
       "panelUpdateCheckPopover": "Panel update check failed",
       "panelUpdateStartedPopover": "Panel update started",
+      "panelUpdateFailedTitle": "Panel update failed",
+      "panelUpdateFailedDesc": "The update did not finish successfully. Check the server logs, or run 'x-ui update' from the command line.",
+      "panelUpdateUnknownTitle": "Couldn't confirm the update finished",
+      "panelUpdateUnknownDesc": "The panel didn't report a result in time. Reload to check the current version, or check the server logs.",
       "geofileUpdateDialog": "Do you really want to update the geofile?",
       "geofileUpdateDialogDesc": "This will update the #filename# file.",
       "geofilesUpdateDialogDesc": "This will update all geofiles.",

internal/web/translation/es-ES.json

@@ -231,6 +231,10 @@
       "panelUpdateDialogDesc": "Esto actualizará 3X-UI a la versión #version# y reiniciará el servicio del panel.",
       "panelUpdateCheckPopover": "Fallo al comprobar actualización del panel",
       "panelUpdateStartedPopover": "Actualización del panel iniciada",
+      "panelUpdateFailedTitle": "Error al actualizar el panel",
+      "panelUpdateFailedDesc": "La actualización no se completó correctamente. Revisa los registros del servidor o ejecuta 'x-ui update' desde la línea de comandos.",
+      "panelUpdateUnknownTitle": "No se pudo confirmar si la actualización terminó",
+      "panelUpdateUnknownDesc": "El panel no informó un resultado a tiempo. Recarga la página para comprobar la versión actual, o revisa los registros del servidor.",
       "geofileUpdateDialog": "¿Realmente deseas actualizar el geofichero?",
       "geofileUpdateDialogDesc": "Esto actualizará el archivo #filename#.",
       "geofilesUpdateDialogDesc": "Esto actualizará todos los archivos.",

internal/web/translation/fa-IR.json

@@ -231,6 +231,10 @@
       "panelUpdateDialogDesc": "این 3X-UI را به نسخه #version# به‌روزرسانی کرده و سرویس پنل را مجدداً راه‌اندازی می‌کند.",
       "panelUpdateCheckPopover": "خطا در بررسی به‌روزرسانی پنل",
       "panelUpdateStartedPopover": "به‌روزرسانی پنل آغاز شد",
+      "panelUpdateFailedTitle": "به‌روزرسانی پنل ناموفق بود",
+      "panelUpdateFailedDesc": "به‌روزرسانی با موفقیت به پایان نرسید. گزارش‌های سرور را بررسی کنید یا دستور «x-ui update» را از خط فرمان اجرا کنید.",
+      "panelUpdateUnknownTitle": "تأیید نشد که به‌روزرسانی به پایان رسیده باشد",
+      "panelUpdateUnknownDesc": "پنل به‌موقع نتیجه‌ای گزارش نکرد. صفحه را بارگذاری مجدد کنید تا نسخه فعلی را بررسی کنید یا گزارش‌های سرور را بررسی کنید.",
       "geofileUpdateDialog": "آیا واقعاً می‌خواهید فایل جغرافیایی را به‌روز کنید؟",
       "geofileUpdateDialogDesc": "این عمل فایل #filename# را به‌روز می‌کند.",
       "geofilesUpdateDialogDesc": "با این کار همه فایل‌ها به‌روزرسانی می‌شوند.",

internal/web/translation/id-ID.json

@@ -231,6 +231,10 @@
       "panelUpdateDialogDesc": "Ini akan memperbarui 3X-UI ke #version# dan me-restart layanan panel.",
       "panelUpdateCheckPopover": "Pemeriksaan pembaruan panel gagal",
       "panelUpdateStartedPopover": "Pembaruan panel dimulai",
+      "panelUpdateFailedTitle": "Pembaruan panel gagal",
+      "panelUpdateFailedDesc": "Pembaruan tidak selesai dengan sukses. Periksa log server, atau jalankan 'x-ui update' dari baris perintah.",
+      "panelUpdateUnknownTitle": "Tidak dapat memastikan pembaruan selesai",
+      "panelUpdateUnknownDesc": "Panel tidak melaporkan hasil tepat waktu. Muat ulang untuk memeriksa versi saat ini, atau periksa log server.",
       "geofileUpdateDialog": "Apakah Anda yakin ingin memperbarui geofile?",
       "geofileUpdateDialogDesc": "Ini akan memperbarui file #filename#.",
       "geofilesUpdateDialogDesc": "Ini akan memperbarui semua berkas.",

internal/web/translation/ja-JP.json

@@ -231,6 +231,10 @@
       "panelUpdateDialogDesc": "これにより3X-UIが#version#に更新され、パネルサービスが再起動されます。",
       "panelUpdateCheckPopover": "パネルの更新確認に失敗しました",
       "panelUpdateStartedPopover": "パネルの更新を開始しました",
+      "panelUpdateFailedTitle": "パネルの更新に失敗しました",
+      "panelUpdateFailedDesc": "更新が正常に完了しませんでした。サーバーのログを確認するか、コマンドラインで「x-ui update」を実行してください。",
+      "panelUpdateUnknownTitle": "更新が完了したか確認できませんでした",
+      "panelUpdateUnknownDesc": "パネルから時間内に結果が報告されませんでした。再読み込みして現在のバージョンを確認するか、サーバーのログを確認してください。",
       "geofileUpdateDialog": "ジオファイルを本当に更新しますか？",
       "geofileUpdateDialogDesc": "これにより#filename#ファイルが更新されます。",
       "geofilesUpdateDialogDesc": "これにより、すべてのファイルが更新されます。",

internal/web/translation/pt-BR.json

@@ -231,6 +231,10 @@
       "panelUpdateDialogDesc": "Isso atualizará o 3X-UI para #version# e reiniciará o serviço do painel.",
       "panelUpdateCheckPopover": "Falha na verificação de atualização do painel",
       "panelUpdateStartedPopover": "Atualização do painel iniciada",
+      "panelUpdateFailedTitle": "Falha ao atualizar o painel",
+      "panelUpdateFailedDesc": "A atualização não foi concluída com sucesso. Verifique os logs do servidor ou execute 'x-ui update' na linha de comando.",
+      "panelUpdateUnknownTitle": "Não foi possível confirmar se a atualização terminou",
+      "panelUpdateUnknownDesc": "O painel não retornou um resultado a tempo. Recarregue a página para verificar a versão atual, ou verifique os logs do servidor.",
       "geofileUpdateDialog": "Você realmente deseja atualizar o geofile?",
       "geofileUpdateDialogDesc": "Isso atualizará o arquivo #filename#.",
       "geofilesUpdateDialogDesc": "Isso atualizará todos os arquivos.",

internal/web/translation/ru-RU.json

@@ -231,6 +231,10 @@
       "panelUpdateDialogDesc": "Это обновит 3X-UI до версии #version# и перезапустит сервис панели.",
       "panelUpdateCheckPopover": "Проверка обновления панели не удалась",
       "panelUpdateStartedPopover": "Обновление панели началось",
+      "panelUpdateFailedTitle": "Не удалось обновить панель",
+      "panelUpdateFailedDesc": "Обновление не завершилось успешно. Проверьте журналы сервера или выполните 'x-ui update' в командной строке.",
+      "panelUpdateUnknownTitle": "Не удалось подтвердить завершение обновления",
+      "panelUpdateUnknownDesc": "Панель не сообщила результат вовремя. Перезагрузите страницу, чтобы проверить текущую версию, или проверьте журналы сервера.",
       "geofileUpdateDialog": "Вы действительно хотите обновить геофайл?",
       "geofileUpdateDialogDesc": "Это обновит файл #filename#.",
       "geofilesUpdateDialogDesc": "Это обновит все геофайлы.",

internal/web/translation/tr-TR.json

@@ -231,6 +231,10 @@
       "panelUpdateDialogDesc": "Bu işlem 3X-UI'yi #version# sürümüne güncelleyecek ve panel servisini yeniden başlatacaktır.",
       "panelUpdateCheckPopover": "Panel güncelleme kontrolü başarısız oldu",
       "panelUpdateStartedPopover": "Panel güncellemesi başlatıldı",
+      "panelUpdateFailedTitle": "Panel güncellemesi başarısız oldu",
+      "panelUpdateFailedDesc": "Güncelleme başarıyla tamamlanamadı. Sunucu günlüklerini kontrol edin veya komut satırından 'x-ui update' çalıştırın.",
+      "panelUpdateUnknownTitle": "Güncellemenin tamamlandığı doğrulanamadı",
+      "panelUpdateUnknownDesc": "Panel zamanında bir sonuç bildirmedi. Geçerli sürümü kontrol etmek için sayfayı yenileyin veya sunucu günlüklerini kontrol edin.",
       "geofileUpdateDialog": "Geofile'ı gerçekten güncellemek istiyor musunuz?",
       "geofileUpdateDialogDesc": "Bu işlem #filename# dosyasını güncelleyecektir.",
       "geofilesUpdateDialogDesc": "Bu, tüm dosyaları güncelleyecektir.",

internal/web/translation/uk-UA.json

@@ -231,6 +231,10 @@
       "panelUpdateDialogDesc": "Це оновить 3X-UI до #version# та перезапустить сервіс панелі.",
       "panelUpdateCheckPopover": "Перевірка оновлення панелі не вдалася",
       "panelUpdateStartedPopover": "Розпочато оновлення панелі",
+      "panelUpdateFailedTitle": "Не вдалося оновити панель",
+      "panelUpdateFailedDesc": "Оновлення не завершилося успішно. Перевірте журнали сервера або виконайте 'x-ui update' у командному рядку.",
+      "panelUpdateUnknownTitle": "Не вдалося підтвердити завершення оновлення",
+      "panelUpdateUnknownDesc": "Панель не повідомила результат вчасно. Перезавантажте сторінку, щоб перевірити поточну версію, або перевірте журнали сервера.",
       "geofileUpdateDialog": "Ви дійсно хочете оновити геофайл?",
       "geofileUpdateDialogDesc": "Це оновить файл #filename#.",
       "geofilesUpdateDialogDesc": "Це оновить усі геофайли.",

internal/web/translation/vi-VN.json

@@ -231,6 +231,10 @@
       "panelUpdateDialogDesc": "Điều này sẽ cập nhật 3X-UI lên #version# và khởi động lại dịch vụ panel.",
       "panelUpdateCheckPopover": "Kiểm tra cập nhật panel thất bại",
       "panelUpdateStartedPopover": "Bắt đầu cập nhật panel",
+      "panelUpdateFailedTitle": "Cập nhật panel thất bại",
+      "panelUpdateFailedDesc": "Bản cập nhật không hoàn tất thành công. Hãy kiểm tra nhật ký máy chủ, hoặc chạy 'x-ui update' từ dòng lệnh.",
+      "panelUpdateUnknownTitle": "Không thể xác nhận việc cập nhật đã hoàn tất",
+      "panelUpdateUnknownDesc": "Panel không báo cáo kết quả kịp thời. Hãy tải lại trang để kiểm tra phiên bản hiện tại, hoặc kiểm tra nhật ký máy chủ.",
       "geofileUpdateDialog": "Bạn có chắc chắn muốn cập nhật geofile không?",
       "geofileUpdateDialogDesc": "Hành động này sẽ cập nhật tệp #filename#.",
       "geofilesUpdateDialogDesc": "Thao tác này sẽ cập nhật tất cả các tập tin.",

internal/web/translation/zh-CN.json

@@ -231,6 +231,10 @@
       "panelUpdateDialogDesc": "这将把 3X-UI 更新到 #version# 并重启面板服务。",
       "panelUpdateCheckPopover": "面板更新检查失败",
       "panelUpdateStartedPopover": "已开始更新面板",
+      "panelUpdateFailedTitle": "面板更新失败",
+      "panelUpdateFailedDesc": "更新未成功完成。请检查服务器日志，或在命令行运行「x-ui update」。",
+      "panelUpdateUnknownTitle": "无法确认更新是否已完成",
+      "panelUpdateUnknownDesc": "面板未能及时返回结果。请刷新页面查看当前版本，或检查服务器日志。",
       "geofileUpdateDialog": "您确定要更新地理文件吗？",
       "geofileUpdateDialogDesc": "这将更新 #filename# 文件。",
       "geofilesUpdateDialogDesc": "这将更新所有文件。",

internal/web/translation/zh-TW.json

@@ -231,6 +231,10 @@
       "panelUpdateDialogDesc": "這將把 3X-UI 更新到 #version# 並重新啟動面板服務。",
       "panelUpdateCheckPopover": "面板更新檢查失敗",
       "panelUpdateStartedPopover": "面板更新已開始",
+      "panelUpdateFailedTitle": "面板更新失敗",
+      "panelUpdateFailedDesc": "更新未成功完成。請檢查伺服器日誌，或在命令列執行「x-ui update」。",
+      "panelUpdateUnknownTitle": "無法確認更新是否已完成",
+      "panelUpdateUnknownDesc": "面板未能及時回報結果。請重新整理以檢查目前版本，或檢查伺服器日誌。",
       "geofileUpdateDialog": "您確定要更新地理檔案嗎？",
       "geofileUpdateDialogDesc": "這將更新 #filename# 檔案。",
       "geofilesUpdateDialogDesc": "這將更新所有文件。",

tools/openapigen/main.go

@@ -83,7 +83,7 @@ func run(root, outDir string) error {
 		},
 		{
 			Path:        resolveRel(root, "internal/web/service/panel"),
-			StructAllow: setOf("ApiTokenView"),
+			StructAllow: setOf("ApiTokenView", "PanelUpdateStatus"),
 		},
 	}
 

update.sh

@@ -31,6 +31,40 @@ _fail() {
     exit 2
 }
 
+# Records this run's outcome for the panel's web updater to poll, since it
+# launches this script detached and has no other way to learn whether it
+# finished. Written to a fixed path outside XUI_MAIN_FOLDER so it survives
+# the update regardless of what happens to that folder. The EXIT trap below
+# covers every exit path in this file, including the bare `exit 1`/`exit 2`
+# calls that don't go through _fail.
+xui_update_run_id="${XUI_UPDATE_RUN_ID:-0}"
+[[ "${xui_update_run_id}" =~ ^[0-9]+$ ]] || xui_update_run_id="0"
+xui_update_status_file="${XUI_UPDATE_STATUS_FILE:-/etc/x-ui/update-status.json}"
+
+_write_update_status() {
+    local state="$1"
+    local exit_code="$2"
+    local status_dir
+    status_dir="$(dirname "${xui_update_status_file}")"
+    mkdir -p "${status_dir}" > /dev/null 2>&1
+    local tmp_file="${xui_update_status_file}.tmp.$$"
+    printf '{"runId":"%s","state":"%s","exitCode":%s,"finishedAt":%s}\n' \
+        "${xui_update_run_id}" "${state}" "${exit_code}" "$(date +%s)" > "${tmp_file}" 2> /dev/null
+    mv -f "${tmp_file}" "${xui_update_status_file}" > /dev/null 2>&1
+}
+
+_report_update_exit() {
+    local code=$?
+    if [[ "${code}" -eq 0 ]]; then
+        _write_update_status "success" "0"
+    else
+        _write_update_status "failed" "${code}"
+    fi
+}
+trap _report_update_exit EXIT
+trap 'exit 143' TERM
+trap 'exit 130' INT
+
 # check root
 [[ $EUID -ne 0 ]] && _fail "FATAL ERROR: Please run this script with root privilege."
 
@@ -881,6 +915,40 @@ setup_fail2ban() {
     return 0
 }
 
+# Lands a systemd unit file at ${xui_service}/x-ui.service via a temp file +
+# atomic mv, so a failed cp/curl or an interrupted mv never leaves a
+# truncated unit file at the live path -- systemd would then fail to parse
+# it on the next daemon-reload/start. Same pattern already used for
+# /usr/bin/x-ui elsewhere in this script. source_is_url picks cp (from a
+# file already extracted from the release tarball) vs curl (GitHub fallback).
+_install_xui_service_unit() {
+    local source="$1"
+    local source_is_url="$2"
+    local dest="${xui_service}/x-ui.service"
+    local temp_file="${dest}.tmp.$$"
+
+    rm -f "$temp_file"
+    if [[ "$source_is_url" == "true" ]]; then
+        ${curl_bin} -fLRo "$temp_file" "$source" > /dev/null 2>&1
+    else
+        cp -f "$source" "$temp_file" > /dev/null 2>&1
+    fi
+    if [[ $? -ne 0 ]]; then
+        rm -f "$temp_file"
+        return 1
+    fi
+    if [[ ! -s "$temp_file" ]]; then
+        rm -f "$temp_file"
+        return 1
+    fi
+    mv -f "$temp_file" "$dest"
+    if [[ $? -ne 0 ]]; then
+        rm -f "$temp_file"
+        return 1
+    fi
+    return 0
+}
+
 update_x-ui() {
     cd ${xui_folder%/x-ui}/
 
@@ -911,6 +979,10 @@ update_x-ui() {
     if [[ $? -ne 0 ]]; then
         _fail "ERROR: Failed to download x-ui, please be sure that your server can access GitHub"
     fi
+    if [[ ! -s ${xui_folder}-linux-$(arch).tar.gz ]]; then
+        rm ${xui_folder}-linux-$(arch).tar.gz -f > /dev/null 2>&1
+        _fail "ERROR: Downloaded x-ui release archive is empty, please be sure that your server can access GitHub"
+    fi
 
     if [[ -e ${xui_folder}/ ]]; then
         echo -e "${green}Stopping x-ui...${plain}"
@@ -961,8 +1033,15 @@ update_x-ui() {
 
     echo -e "${green}Installing new x-ui version...${plain}"
     tar zxvf x-ui-linux-$(arch).tar.gz > /dev/null 2>&1
+    if [[ $? -ne 0 ]]; then
+        rm x-ui-linux-$(arch).tar.gz -f > /dev/null 2>&1
+        _fail "ERROR: Failed to extract the x-ui release archive -- the previous installation has already been removed, so the panel will not start until this is fixed; try running the update again"
+    fi
     rm x-ui-linux-$(arch).tar.gz -f > /dev/null 2>&1
     cd x-ui > /dev/null 2>&1
+    if [[ $? -ne 0 || ! -s x-ui ]]; then
+        _fail "ERROR: Extracted x-ui archive is missing the x-ui binary -- the previous installation has already been removed, so the panel will not start until this is fixed; try running the update again"
+    fi
     chmod +x x-ui > /dev/null 2>&1
 
     # Check the system's architecture and rename the file accordingly
@@ -974,10 +1053,22 @@ update_x-ui() {
     chmod +x x-ui bin/xray-linux-$(arch) > /dev/null 2>&1
 
     echo -e "${green}Downloading and installing x-ui.sh script...${plain}"
-    ${curl_bin} -fLRo /usr/bin/x-ui https://raw.githubusercontent.com/MHSanaei/3x-ui/main/x-ui.sh > /dev/null 2>&1
+    local xui_script_temp="/usr/bin/x-ui-temp.$$"
+    rm -f "${xui_script_temp}"
+    ${curl_bin} -fLRo "${xui_script_temp}" https://raw.githubusercontent.com/MHSanaei/3x-ui/main/x-ui.sh > /dev/null 2>&1
     if [[ $? -ne 0 ]]; then
+        rm -f "${xui_script_temp}"
         _fail "ERROR: Failed to download x-ui.sh script, please be sure that your server can access GitHub"
     fi
+    if [[ ! -s "${xui_script_temp}" ]]; then
+        rm -f "${xui_script_temp}"
+        _fail "ERROR: Downloaded x-ui.sh script is empty, please be sure that your server can access GitHub"
+    fi
+    mv -f "${xui_script_temp}" /usr/bin/x-ui
+    if [[ $? -ne 0 ]]; then
+        rm -f "${xui_script_temp}"
+        _fail "ERROR: Failed to install x-ui.sh script"
+    fi
 
     chmod +x ${xui_folder}/x-ui.sh > /dev/null 2>&1
     chmod +x /usr/bin/x-ui > /dev/null 2>&1
@@ -993,10 +1084,22 @@ update_x-ui() {
 
     if [[ $release == "alpine" ]]; then
         echo -e "${green}Downloading and installing startup unit x-ui.rc...${plain}"
-        ${curl_bin} -fLRo /etc/init.d/x-ui https://raw.githubusercontent.com/MHSanaei/3x-ui/main/x-ui.rc > /dev/null 2>&1
+        xui_rc_temp="/etc/init.d/x-ui.tmp.$$"
+        rm -f "${xui_rc_temp}"
+        ${curl_bin} -fLRo "${xui_rc_temp}" https://raw.githubusercontent.com/MHSanaei/3x-ui/main/x-ui.rc > /dev/null 2>&1
         if [[ $? -ne 0 ]]; then
+            rm -f "${xui_rc_temp}"
             _fail "ERROR: Failed to download startup unit x-ui.rc, please be sure that your server can access GitHub"
         fi
+        if [[ ! -s "${xui_rc_temp}" ]]; then
+            rm -f "${xui_rc_temp}"
+            _fail "ERROR: Downloaded startup unit x-ui.rc is empty, please be sure that your server can access GitHub"
+        fi
+        mv -f "${xui_rc_temp}" /etc/init.d/x-ui
+        if [[ $? -ne 0 ]]; then
+            rm -f "${xui_rc_temp}"
+            _fail "ERROR: Failed to install startup unit x-ui.rc"
+        fi
         chmod +x /etc/init.d/x-ui > /dev/null 2>&1
         chown root:root /etc/init.d/x-ui > /dev/null 2>&1
         rc-update add x-ui > /dev/null 2>&1
@@ -1004,8 +1107,7 @@ update_x-ui() {
     else
         if [ -f "x-ui.service" ]; then
             echo -e "${green}Installing systemd unit...${plain}"
-            cp -f x-ui.service ${xui_service}/ > /dev/null 2>&1
-            if [[ $? -ne 0 ]]; then
+            if ! _install_xui_service_unit "x-ui.service" "false"; then
                 echo -e "${red}Failed to copy x-ui.service${plain}"
                 exit 1
             fi
@@ -1015,8 +1117,7 @@ update_x-ui() {
                 ubuntu | debian | armbian)
                     if [ -f "x-ui.service.debian" ]; then
                         echo -e "${green}Installing debian-like systemd unit...${plain}"
-                        cp -f x-ui.service.debian ${xui_service}/x-ui.service > /dev/null 2>&1
-                        if [[ $? -eq 0 ]]; then
+                        if _install_xui_service_unit "x-ui.service.debian" "false"; then
                             service_installed=true
                         fi
                     fi
@@ -1024,8 +1125,7 @@ update_x-ui() {
                 arch | manjaro | parch)
                     if [ -f "x-ui.service.arch" ]; then
                         echo -e "${green}Installing arch-like systemd unit...${plain}"
-                        cp -f x-ui.service.arch ${xui_service}/x-ui.service > /dev/null 2>&1
-                        if [[ $? -eq 0 ]]; then
+                        if _install_xui_service_unit "x-ui.service.arch" "false"; then
                             service_installed=true
                         fi
                     fi
@@ -1033,8 +1133,7 @@ update_x-ui() {
                 *)
                     if [ -f "x-ui.service.rhel" ]; then
                         echo -e "${green}Installing rhel-like systemd unit...${plain}"
-                        cp -f x-ui.service.rhel ${xui_service}/x-ui.service > /dev/null 2>&1
-                        if [[ $? -eq 0 ]]; then
+                        if _install_xui_service_unit "x-ui.service.rhel" "false"; then
                             service_installed=true
                         fi
                     fi
@@ -1046,17 +1145,17 @@ update_x-ui() {
                 echo -e "${yellow}Service files not found in tar.gz, downloading from GitHub...${plain}"
                 case "${release}" in
                     ubuntu | debian | armbian)
-                        ${curl_bin} -fLRo ${xui_service}/x-ui.service https://raw.githubusercontent.com/MHSanaei/3x-ui/main/x-ui.service.debian > /dev/null 2>&1
+                        service_unit_url="https://raw.githubusercontent.com/MHSanaei/3x-ui/main/x-ui.service.debian"
                         ;;
                     arch | manjaro | parch)
-                        ${curl_bin} -fLRo ${xui_service}/x-ui.service https://raw.githubusercontent.com/MHSanaei/3x-ui/main/x-ui.service.arch > /dev/null 2>&1
+                        service_unit_url="https://raw.githubusercontent.com/MHSanaei/3x-ui/main/x-ui.service.arch"
                         ;;
                     *)
-                        ${curl_bin} -fLRo ${xui_service}/x-ui.service https://raw.githubusercontent.com/MHSanaei/3x-ui/main/x-ui.service.rhel > /dev/null 2>&1
+                        service_unit_url="https://raw.githubusercontent.com/MHSanaei/3x-ui/main/x-ui.service.rhel"
                         ;;
                 esac
 
-                if [[ $? -ne 0 ]]; then
+                if ! _install_xui_service_unit "$service_unit_url" "true"; then
                     echo -e "${red}Failed to install x-ui.service from GitHub${plain}"
                     exit 1
                 fi

x-ui.sh

@@ -173,6 +173,41 @@ update_dev() {
     fi
 }
 
+replace_xui_script() {
+    local url="$1"
+    local use_if_modified_since="$2"
+    local temp_file="/usr/bin/x-ui-temp.$$"
+
+    rm -f "$temp_file"
+    if [[ "$use_if_modified_since" == "true" ]]; then
+        curl -fLRo "$temp_file" -z /usr/bin/x-ui "$url"
+    else
+        curl -fLRo "$temp_file" "$url"
+    fi
+    if [[ $? != 0 ]]; then
+        rm -f "$temp_file"
+        return 1
+    fi
+
+    if [[ ! -s "$temp_file" ]]; then
+        rm -f "$temp_file"
+        # -z above means "not modified since /usr/bin/x-ui" rather than a
+        # real failure, so an empty download here is success, not an error.
+        [[ "$use_if_modified_since" == "true" ]] && return 0
+        return 1
+    fi
+
+    mv -f "$temp_file" /usr/bin/x-ui
+    if [[ $? != 0 ]]; then
+        rm -f "$temp_file"
+        return 1
+    fi
+    # The move already landed the new script; a transient chmod failure here
+    # shouldn't make callers think the whole replace failed.
+    chmod +x /usr/bin/x-ui
+    return 0
+}
+
 update_menu() {
     echo -e "${yellow}Updating Menu${plain}"
     confirm "This function will update the menu to the latest changes." "y"
@@ -184,11 +219,8 @@ update_menu() {
         return 0
     fi
 
-    curl -fLRo /usr/bin/x-ui https://raw.githubusercontent.com/MHSanaei/3x-ui/main/x-ui.sh
-    chmod +x ${xui_folder}/x-ui.sh
-    chmod +x /usr/bin/x-ui
-
-    if [[ $? == 0 ]]; then
+    if replace_xui_script "https://raw.githubusercontent.com/MHSanaei/3x-ui/main/x-ui.sh" "false"; then
+        chmod +x ${xui_folder}/x-ui.sh
         echo -e "${green}Update successful. The panel has automatically restarted.${plain}"
         exit 0
     else
@@ -804,14 +836,12 @@ enable_bbr() {
 }
 
 update_shell() {
-    curl -fLRo /usr/bin/x-ui -z /usr/bin/x-ui https://github.com/MHSanaei/3x-ui/raw/main/x-ui.sh
-    if [[ $? != 0 ]]; then
-        echo ""
-        LOGE "Failed to download script, Please check whether the machine can connect Github"
+    if replace_xui_script "https://github.com/MHSanaei/3x-ui/raw/main/x-ui.sh" "true"; then
+        LOGI "Upgrade script succeeded, Please rerun the script"
         before_show_menu
     else
-        chmod +x /usr/bin/x-ui
-        LOGI "Upgrade script succeeded, Please rerun the script"
+        echo ""
+        LOGE "Failed to download script, Please check whether the machine can connect Github"
         before_show_menu
     fi
 }
@@ -1198,22 +1228,43 @@ update_geofiles() {
             dat_files=(geoip_RU geosite_RU)
             dat_source="runetfreedom/russia-v2ray-rules-dat"
             ;;
+        *)
+            echo -e "${red}update_geofiles: unknown dataset '${1}'${plain}"
+            return 1
+            ;;
     esac
     local failed=0 http_code
     for dat in "${dat_files[@]}"; do
         # Remove suffix for remote filename (e.g., geoip_IR -> geoip)
         remote_file="${dat%%_*}"
-        # -z skips the download (server answers 304) when the local copy is already current
-        http_code=$(curl -sSfLRo ${xui_folder}/bin/${dat}.dat -z ${xui_folder}/bin/${dat}.dat -w '%{http_code}' \
+        local dest="${xui_folder}/bin/${dat}.dat"
+        local temp_file="${dest}.tmp.$$"
+        rm -f "$temp_file"
+        # -z (against the live file, not the temp file) skips the download
+        # (server answers 304) when the local copy is already current.
+        http_code=$(curl -sSfLRo "$temp_file" -z "$dest" -w '%{http_code}' \
             https://github.com/${dat_source}/releases/latest/download/${remote_file}.dat)
         if [[ $? -ne 0 ]]; then
             echo -e "${red}${dat}.dat: download failed${plain}"
+            rm -f "$temp_file"
             failed=1
         elif [[ "$http_code" == "304" ]]; then
             echo -e "${dat}.dat: already up to date"
+            rm -f "$temp_file"
+        elif [[ ! -s "$temp_file" ]]; then
+            echo -e "${red}${dat}.dat: downloaded file is empty${plain}"
+            rm -f "$temp_file"
+            failed=1
         else
-            echo -e "${green}${dat}.dat: updated${plain}"
-            geo_updated=1
+            mv -f "$temp_file" "$dest"
+            if [[ $? -ne 0 ]]; then
+                echo -e "${red}${dat}.dat: failed to install${plain}"
+                rm -f "$temp_file"
+                failed=1
+            else
+                echo -e "${green}${dat}.dat: updated${plain}"
+                geo_updated=1
+            fi
         fi
     done
     return $failed