fix(panel): make self-upgrades durable and observable (#572)

Persist upgrade jobs and progress across backend restarts; preserve Compose identity and database mounts, isolate backups, and fail safely on uncertain recreation. Add frontend recovery handling and lifecycle/permission regressions.

.github/workflows/ci-build.yml

@@ -7,6 +7,18 @@ on:
     branches: ['**']
 
 jobs:
+  install-scripts:
+    name: Test Installer Scripts (systemd and Alpine OpenRC)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Run installer regression tests
+        run: bash test-install-scripts-proxy.sh
+
+      - name: Test Alpine bootstrap and OpenRC lifecycle
+        run: docker run --rm -v "$PWD:/workspace:ro" alpine:3.22 sh /workspace/test-install-scripts-alpine.sh
+
   frontend:
     name: Build Frontend
     runs-on: ubuntu-latest
@@ -19,10 +31,10 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '20.19.0'
+          node-version-file: '.node-version'
 
       - name: Install pnpm
-        run: npm install -g pnpm
+        run: npm install -g pnpm@10.28.1
 
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
@@ -42,7 +54,7 @@ jobs:
       - name: Setup Go
         uses: actions/setup-go@v5
         with:
-          go-version: '1.23'
+          go-version-file: 'go-backend/go.mod'
           cache-dependency-path: go-backend/go.sum
 
       - name: Download dependencies
@@ -51,6 +63,11 @@ jobs:
       - name: Build
         run: go build -v ./...
 
+      - name: Test panel upgrade lifecycle and permissions
+        run: |
+          go test ./internal/panelupgrade -count=1
+          go test ./internal/http/handler ./tests/contract -run 'SystemUpgrade|SelectComposeAsset|DownloadReleaseAsset|UpgradeBackup|RestoreBackup' -count=1
+
   backend-postgres-contract:
     name: Go Backend PostgreSQL Contract
     runs-on: ubuntu-latest
@@ -77,7 +94,7 @@ jobs:
       - name: Setup Go
         uses: actions/setup-go@v5
         with:
-          go-version: '1.23'
+          go-version-file: 'go-backend/go.mod'
           cache-dependency-path: go-backend/go.sum
 
       - name: Download dependencies
@@ -100,7 +117,7 @@ jobs:
       - name: Setup Go
         uses: actions/setup-go@v5
         with:
-          go-version: '1.23'
+          go-version-file: 'go-gost/go.mod'
           cache-dependency-path: go-gost/go.sum
 
       - name: Download dependencies

.github/workflows/docker-build.yml

@@ -79,7 +79,7 @@ jobs:
       - name: Set up Go
         uses: actions/setup-go@v5
         with:
-          go-version: '1.23'
+          go-version-file: 'go-gost/go.mod'
 
       - name: Cache Go modules
         uses: actions/cache@v4
@@ -197,7 +197,7 @@ jobs:
       - name: Set up Go
         uses: actions/setup-go@v5
         with:
-          go-version: '1.23'
+          go-version-file: 'go-backend/go.mod'
 
       - name: Cache Go dependencies
         uses: actions/cache@v4
@@ -304,6 +304,9 @@ jobs:
           sed -i "s|^PINNED_VERSION=\"\"|PINNED_VERSION=\"${VERSION}\"|" ./artifacts/install.sh
           sed -i "s|^PINNED_VERSION=\"\"|PINNED_VERSION=\"${VERSION}\"|" ./artifacts/panel_install.sh
 
+      - name: Verify release installer on Alpine OpenRC
+        run: docker run --rm -v "$PWD:/workspace:ro" alpine:3.22 sh /workspace/test-install-scripts-alpine.sh /workspace/artifacts/install.sh
+
       - name: Create Release
         env:
           GH_TOKEN: ${{ github.token }}

.github/workflows/publish-skill.yml

@@ -19,7 +19,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version-file: '.node-version'
           registry-url: 'https://registry.npmjs.org'
 
       - name: Get version from tag

.github/workflows/udp-destination.yml

@@ -0,0 +1,87 @@
+name: UDP Destination Regression
+
+on:
+  push:
+    branches: ['main', 'fix/udp-wildcard-source', 'pr/udp-wildcard-source']
+  pull_request:
+    paths:
+      - 'go-gost/**'
+      - '.github/workflows/udp-destination.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: udp-destination-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  linux:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: 'go-gost/go.mod'
+          cache-dependency-path: |
+            go-gost/go.sum
+            go-gost/x/go.sum
+
+      - name: Test agent module
+        working-directory: go-gost
+        run: go test ./...
+
+      - name: Test protocol module
+        working-directory: go-gost/x
+        run: go test ./...
+
+      - name: Check UDP races
+        working-directory: go-gost/x
+        run: go test -race ./internal/net/udp ./listener/udp
+
+      - name: Vet UDP implementation
+        working-directory: go-gost/x
+        run: go vet ./internal/net/udp ./listener/udp
+
+      - name: Build destination regression executable
+        working-directory: go-gost/x
+        run: |
+          go test -c -race -o "$RUNNER_TEMP/udp-destination.test" ./listener/udp
+          go test -c -race -o "$RUNNER_TEMP/udp-packet.test" ./internal/net/udp
+
+      - name: Test multiple destinations in isolated network namespace
+        run: |
+          sudo unshare --net -- sh -eu -c '
+            sysctl -qw net.ipv6.conf.all.disable_ipv6=0
+            ip link set lo up
+            ip addr add 198.18.0.1/32 dev lo
+            ip addr add 169.254.1.2/32 dev lo
+            ip -6 addr add fd00:1::1/128 dev lo nodad
+            ip -6 addr add fd00:2::1/128 dev lo nodad
+            ip -6 addr add fd00:3::1/128 dev lo nodad
+            for suffix in "" 2; do
+              ip link add "mc-tx$suffix" type veth peer name "mc-rx$suffix"
+              ip link set "mc-tx$suffix" addrgenmode none up
+              ip link set "mc-rx$suffix" addrgenmode none up
+              ip -6 addr add fe80::1/64 dev "mc-tx$suffix" nodad
+              ip -6 addr add fe80::2/64 dev "mc-rx$suffix" nodad
+            done
+            ip addr add 198.18.1.1/24 dev mc-tx
+            ip addr add 198.18.2.1/24 dev mc-tx2
+            export FLUX_TEST_IPV6_ADDRS=fd00:1::1,fd00:2::1,fd00:3::1
+            export FLUX_TEST_IPV4_LINK_LOCAL=169.254.1.2
+            export FLUX_TEST_MULTICAST_RX=mc-rx FLUX_TEST_MULTICAST_TX=mc-tx
+            export FLUX_TEST_MULTICAST_RX2=mc-rx2 FLUX_TEST_MULTICAST_TX2=mc-tx2
+            "$1" -test.v -test.timeout=60s -test.count=5
+            exec "$2" -test.v -test.timeout=60s -test.count=5
+          ' sh "$RUNNER_TEMP/udp-destination.test" "$RUNNER_TEMP/udp-packet.test"
+
+      - name: Build Linux agent
+        working-directory: go-gost
+        env:
+          CGO_ENABLED: '0'
+          GOOS: linux
+          GOARCH: amd64
+        run: go build -trimpath -o "$RUNNER_TEMP/flux-agent" .

.node-version

@@ -0,0 +1 @@
+22.23.4

AGENTS.md

@@ -40,7 +40,8 @@ FLVX — traffic forwarding panel: Go admin API + Vite/React UI + Go agent.
 - **Backend DB**: handlers use Repository methods, never `repo.DB()` directly.
 - **GORM models**: always define `TableName()` (GORM pluralizes by default).
 - **GORM tags**: no `type:jsonb` or `type:serial` (SQLite incompatible).
-- **Go versions**: `go.mod` says 1.25.0 for all three modules; CI builds with 1.23.
+- **Go versions**: all three modules require Go 1.26.10 or newer (CVE-2026-111943); CI reads the module's `go.mod`. Do not use Go 1.27.0–1.27.2, which also lack this fix.
+- **Node.js versions**: `.node-version` pins 22.23.4 for CI; local builds also support patched 24.22.1+ and 26.12.1+ (CVE-2026-111497).
 
 ## Anti-patterns
 

README.md

@@ -17,6 +17,12 @@
 - 支持隧道修改配置、转发修改隧道
 
 
+## 构建环境
+
+Go 后端和 agent 的最低编译版本为 **Go 1.26.10**；若使用 Go 1.27，须为 **1.27.3 或更新补丁版**。前端与 skill 发布使用 **Node.js 22.23.4**（见 `.node-version`），本地也支持 24.22.1+ 或 26.12.1+。前端使用 `pnpm@10.28.1`。
+
+这些版本包含 2026 年 10 月的运行时安全修复。已有部署还需重新构建并更新后端镜像及所有 agent 二进制，详见 [安全排查与升级说明](docs/security/2026-10-runtime-updates.md)。
+
 ## 部署流程
 ---
 ### Docker Compose部署
@@ -71,6 +77,45 @@ docker compose up -d
 
 3) 如果你想继续使用 SQLite，保留 `DB_TYPE=sqlite`（或不设置 `DB_TYPE`）即可。
 
+#### 通行证密钥登录（可选）
+
+通行证密钥登录默认关闭，需要管理员在部署环境中主动启用。它不依赖 Cloudflare Turnstile，但用户必须在验证码可用时先用密码登录并绑定密钥；未绑定的账号不能用此功能绕过验证码。原密码登录始终可用。
+
+**新部署与旧版本升级：**新安装生成的 `.env` 默认没有 `FLVX_WEBAUTHN_ORIGIN`。升级到支持通行证密钥的版本也**不会自动启用**：安装脚本保留已有 `.env`，不会向其中添加该变量。如果手动升级时保留了旧版 `docker-compose.yml`，还需检查 `backend.environment` 是否包含下文的变量传递项。未设置该变量时，仅更新镜像或版本号后看不到入口是预期行为。
+
+1. 在实际部署目录的 `.env` 中添加浏览器访问面板时的公开前端 origin，将示例域名换成自己的域名：
+
+   ```dotenv
+   FLVX_WEBAUTHN_ORIGIN=https://panel.example.com
+   ```
+
+   必须使用完整 HTTPS origin（协议、域名、必要时的端口），不能带路径、查询参数或尾部 `/`。仅本机开发可用 `http://localhost:3000` 或 `http://127.0.0.1:3000`。经反向代理访问时仍填浏览器地址栏中的**前端** origin，不填容器地址、后端监听地址或代理转发头；API 即使在另一个域名，也不改变此值。自行部署时将该变量传给 `paneld` 进程。
+
+2. 确认实际使用的 `docker-compose.yml` 在 `backend` 服务的 `environment` 下有以下传递项；新版 Compose 模板已包含，旧模板若缺失需补上：
+
+   ```yaml
+   FLVX_WEBAUTHN_ORIGIN: ${FLVX_WEBAUTHN_ORIGIN:-}
+   ```
+
+   在该部署目录运行 `docker compose up -d --force-recreate backend`，使新环境变量进入后端容器。后端重建期间，面板 API 会短暂中断。容器恢复后重新加载前端页面；如果 PWA 提示“发现新版本”，选择“刷新”，也可以用新的无痕窗口核对是否仍加载旧页面。
+
+3. 用户照常用密码登录，桌面端点右上角“个人资料”，手机端点底部“我的”（均进入 `/profile`）；在页面顶部的“通行证密钥”卡片输入**当前密码**、可选名称，点击“绑定通行证密钥”并完成设备解锁。新绑定要求设备支持可发现凭据（resident key），不支持的设备会在绑定时失败。绑定或删除均需当前密码，且用户只能管理自己账号的密钥。
+
+4. 以后在登录页直接点击“选择通行证密钥登录”，由设备选择账号并解锁，**无需先填写用户名**。账号被停用时密钥登录也会被拒绝。撤销密钥仍到个人资料页输入当前密码并删除。
+
+   旧版本绑定时只“优先”请求可发现凭据，现有密钥是否能直接选账号取决于当时的设备，不能按绑定版本统一判定或批量删除。若设备不显示某把旧密钥，请使用密码登录，在个人资料页删除该密钥并重新绑定；确认新密钥与密码恢复途径可用后再清理其他旧密钥。登录页不提供用户名密钥回退。
+
+**入口未显示时，按顺序检查：**
+
+1. 在部署目录运行 `docker compose exec backend printenv FLVX_WEBAUTHN_ORIGIN`，仅检查这一项是否为预期的公开前端 origin；不要贴出完整 `docker compose config` 或其他环境变量，以免泄露密码和密钥。若为空，检查 `.env` 和实际 Compose 模板的 `backend.environment`，然后按步骤 2 重建后端。
+2. 向浏览器实际调用的后端地址发送公开状态请求，例如将以下示例地址替换为自己的 API 地址后运行 `curl -sS -X POST 'https://api.example.com/api/v1/user/passkey/status' -H 'Content-Type: application/json' -d '{}'`。应返回 `code: 0` 且 `data.enabled: true`；若为 `false`，后端尚未接受有效配置。此接口无需登录或提供密码。
+3. 在访问面板的浏览器控制台检查 `window.isSecureContext` 为 `true`，且 `typeof window.PublicKeyCredential` 不是 `"undefined"`。普通公网 HTTP 页面或不支持 WebAuthn 的浏览器不会显示入口。确认后刷新页面，并查看 `/api/v1/user/passkey/status` 的实际网络响应。
+4. 若状态已启用且浏览器满足条件，检查 `docker compose images frontend` 中的前端镜像版本，并按步骤 2 的 PWA 提示刷新或使用无痕窗口。登录页按钮与个人资料页卡片均不存在时，通常是旧前端页面或状态请求未成功；只有其中一个缺失时，记录页面地址和该请求的响应再排查。
+
+**安全配置与恢复：**未设置或设置错误时，通行证密钥接口拒绝新的绑定和登录，登录页与个人资料页不显示对应入口；密码登录不受影响。不要把不可信的请求 `Host` / `X-Forwarded-Host` 当作可信 origin。域名变化会改变 RP ID，旧域名下绑定的密钥不能用于新域名；迁移时需保留原域名或可用的密码登录途径，再在新域名重新绑定。仅更改同一域名的端口也需同步更新此 origin。正在进行的密钥挑战只保存在后端内存中，重启后需重新开始；多副本部署需要共享会话方案，未实现前请保持单个后端实例。
+
+建议保留至少一种可用的密码恢复途径。数据库级备份会保留密钥记录；当前面板的 JSON 导出不包含通行证密钥，使用 JSON 导入迁移后，用户需要通过密码登录并重新绑定。
+
 #### 从 SQLite 迁移到 PostgreSQL
 
 如果你是通过 `panel_install.sh` 安装面板，推荐直接使用脚本菜单一键迁移：

docker-compose-v4.yml

@@ -13,6 +13,7 @@ services:
       DB_PATH: /app/data/gost.db
       DATABASE_URL: ${DATABASE_URL:-}
       JWT_SECRET: ${JWT_SECRET}
+      FLVX_WEBAUTHN_ORIGIN: ${FLVX_WEBAUTHN_ORIGIN:-}
       SERVER_ADDR: :6365
       TZ: Asia/Shanghai
       FLUX_VERSION: ${FLUX_VERSION:-dev}

docker-compose-v6.yml

@@ -13,6 +13,7 @@ services:
       DB_PATH: /app/data/gost.db
       DATABASE_URL: ${DATABASE_URL:-}
       JWT_SECRET: ${JWT_SECRET}
+      FLVX_WEBAUTHN_ORIGIN: ${FLVX_WEBAUTHN_ORIGIN:-}
       SERVER_ADDR: :6365
       TZ: Asia/Shanghai
       FLUX_VERSION: ${FLUX_VERSION:-dev}

docs/security/2026-10-runtime-updates.md

@@ -0,0 +1,37 @@
+# 2026-10-22 运行时漏洞排查与升级
+
+## 排查结论
+
+| 漏洞 | 本项目涉及范围 | 修复措施 |
+| --- | --- | --- |
+| CVE-2026-109618、CVE-2026-109619（PHP RCE） | 仓库无 PHP 源码、Composer 依赖或 PHP 容器。项目后端为 Go，前端生产容器为 Nginx 静态服务。 | 本项目无 PHP 运行时需要更新；同机部署的其他 PHP 服务需单独排查。转发 PHP 网站的流量不会修复目标网站的 PHP。 |
+| CVE-2026-111497（Node.js Brotli 越界写入） | 前端 Docker 构建使用 Node.js 22；CI 原使用已停止支持的 Node.js 20。Node.js 用于构建、开发及 skill 安装/发布，不是面板生产服务端。未发现项目源码直接调用 Brotli 解码，但构建依赖和下载工具仍运行于 Node.js。 | Docker、CI 和 `.node-version` 固定为 22.23.4；包声明仅接受已修复的 22.23.4+、24.22.1+、26.12.1+ 分支，前端启用 `engine-strict`。 |
+| CVE-2026-111943（Go crypto/x509 中间证书信任） | 后端的版本检查、升级下载、授权验证等使用 HTTPS；agent 的更新下载、TLS 拨号和证书验证使用 Go 标准库。原 Go 1.25 工具链缺少此次拒绝信任修复。 | 三个 Go 模块最低版本升至 1.26.10，CI 从对应 `go.mod` 读取，后端 Docker 使用 1.26.10-bookworm。 |
+
+Go 漏洞涉及一组特定中间证书，并非拒绝所有包含八层中间证书的证书链。官方修复在 `crypto/x509.Certificate.Verify` 中拒绝包含这些证书的链。Go 1.27.0–1.27.2 也未修复；手动选择 Go 1.27 时必须使用 1.27.3+。`go.mod` 的最低版本无法排除该较新分支里的旧补丁版本，因此发布必须使用仓库固定的工具链。
+
+## 让已部署实例获得修复
+
+1. 使用本次修改后的构建配置发布新版本，重新构建后端及前端镜像、Linux amd64/arm64 agent。Go 标准库编译进二进制，仅更新宿主机 Go 或 `ca-certificates` 不会替换已有二进制中的标准库。已有镜像标签也不会因源码更新自动修复。
+2. 在面板实际部署目录，将 `.env` 中的 `FLUX_VERSION` 设置为包含本次修复的**已发布版本**，再执行 `docker compose pull backend frontend` 和 `docker compose up -d backend frontend`。如使用独立构建或私有仓库，应部署对应的新镜像。
+3. 将所有节点的 agent 更新为同一安全版本并重启服务，包括离线节点。使用解压后的构建产物执行 `go version -m /path/to/gost` 或 `go version -m /path/to/paneld`，核对构建版本为 go1.26.10（或已修复的更新版本）；UPX 压缩可能需要先对副本解压以读取构建信息。
+4. 开发机和自托管构建机也需升级 Node.js。本次排查时本机为 v26.0.0，属于受影响版本；应升级至 26.12.1+，或切换到 `.node-version` 的 22.23.4。无需在运行静态前端的 Nginx 容器内安装 Node.js。
+
+本次代码修改不表示远端部署已经更新；须完成新版本发布、镜像替换与节点升级后，才能确认线上获得修复。更新系统 CA 信任包可作为额外措施，但不能替代 Go 二进制重建。
+
+## 本次验证
+
+- Go 1.26.10 下，`go-backend`、`go-gost`、`go-gost/x` 各自的 `go test ./...` 全部通过。PostgreSQL 外部数据库契约测试仍需配置 `FLVX_POSTGRES_TEST_DSN` 后单独执行。
+- Node.js 22.23.4、pnpm 10.28.1 下，前端 `pnpm install --frozen-lockfile` 与 `pnpm run build` 通过，无需更改依赖锁文件。
+- 本机 Node.js 26.0.0 执行前端构建时，被 `engine-strict` 拒绝。
+- 使用 `CGO_ENABLED=0` 交叉编译后端和 agent 的 Linux amd64/arm64 共四个二进制成功；`go version -m` 确认均为 go1.26.10。
+- Docker Hub 上两个固定构建镜像标签均存在，且包含 Linux amd64/arm64。未执行 Docker 镜像构建或线上部署。
+- 工作流 YAML、包 JSON 解析及 `git diff --check` 通过。
+
+## 官方依据
+
+- [PHP 官方安全公告](https://www.php.net/archive/2026.php#2026-10-21-4)
+- [Node.js 2026-10-21 安全更新及修复版本](https://nodejs.org/en/blog/vulnerability/october-2026-security-releases)
+- [Go 官方问题 #82345](https://go.dev/issue/82345)
+- [Go 漏洞库 GO-2026-6809](https://pkg.go.dev/vuln/GO-2026-6809)
+- [Go 官方发布记录](https://go.dev/doc/devel/release)

docs/udp-wildcard-source.md

@@ -0,0 +1,133 @@
+# Preserve UDP reply source addresses on Linux
+
+The Linux UDP listener preserves the destination address of each incoming
+datagram so that replies use the correct local source. This change was developed
+against FLVX `3.0.1-rc4`, commit
+`d9303032cad09b33cd0b7c91704fd671fbfdd078`.
+It also includes the `3.0.1-rc5` runtime update at
+`c794586cc7773e5f967783895d3071538442bbf7`.
+
+## Problem
+
+A wildcard UDP socket bound to `0.0.0.0:port` or `[::]:port` can receive datagrams
+addressed to several local IP addresses. Previously, the listener retained only
+the client address. A reply sent through `WriteTo` could therefore use a source
+IP chosen by the kernel instead of the IP the client contacted. DNS clients, for
+example, can reject such replies as coming from an unexpected source.
+
+The UDP session pool was also keyed only by the client address and port. When
+one client socket contacted multiple local addresses on the same listener port,
+these requests could share a session despite having different destinations.
+
+## Changes
+
+- Linux wildcard UDP sockets enable IPv4/IPv6 packet information. `recvmsg`
+  preserves the datagram's local destination and interface; `sendmsg` uses the
+  corresponding source address and interface when replying.
+- IPv4 keeps the original destination (`ipi_addr`) separate from the local
+  reply address (`ipi_spec_dst`), so broadcast requests receive unicast replies
+  rather than attempting to send with a broadcast source address.
+- IPv6 multicast destinations remain part of session identity, but replies
+  leave the source unspecified and retain the received interface index so the
+  kernel can select a valid local unicast source.
+- The destination metadata travels through existing metrics, statistics,
+  admission and traffic-limiter wrappers. The exposed remote address remains
+  the real client address.
+- Sessions are keyed by the local destination endpoint, remote client endpoint
+  and received interface index. Identical IPv4 broadcast or multicast endpoints
+  on different interfaces therefore retain separate reply control information.
+  An accepted session reports its actual local destination.
+  Link-local IPv6 unicast and link-local or interface-local multicast
+  destinations retain their interface zone, keeping identical multicast groups
+  on different interfaces separate even when the client uses the same
+  non-link-local IP and source port.
+  IPv4 destinations, including link-local unicast and multicast, never receive
+  an IPv6 zone; their interface isolation uses the separate index in the key.
+- Explicitly bound UDP sockets retain their existing behavior. Non-Linux
+  platforms retain their existing implementation. No configuration keys or
+  panel API changes are required.
+
+The fix affects the shared UDP listener, including services dynamically created
+after startup. It does not configure listening addresses, NAT, routing or
+firewalls. Multi-homed hosts still need correct source policy routing for their
+uplinks; this patch does not fix SSH/TCP routing or packet loss before ingress.
+
+## Build
+
+Use Go 1.26.10 or a compatible newer toolchain. From the repository root:
+
+```sh
+cd go-gost
+CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath \
+  -ldflags '-s -w' -o flux_agent .
+```
+
+Use the agent with the normal panel integration and forwarding configuration.
+Selecting a wildcard listener enables destination preservation automatically
+on Linux. The patch does not select a listener address or change the upstream
+connection's outbound interface.
+
+## Regression tests
+
+The Linux destination tests cover IPv4 wildcard and dual-stack wildcard sockets,
+explicit IPv4/IPv6 bindings, one client source port contacting multiple local
+destinations, repeated requests, session expiry, and active metrics, statistics,
+admission and traffic-limit wrappers. A separate IPv6 case binds the client to
+`::1` and checks the exact remote IP and port for every destination. Broadcast
+tests exercise both IPv4 and dual-stack listeners, retaining the broadcast
+destination while checking that replies use a local unicast address.
+An IPv6 multicast regression sends across an isolated veth pair and checks the
+multicast session destination and the unicast reply, including interface zones.
+A two-interface case uses one fixed ULA client endpoint to contact the same
+link-local or interface-local multicast group on both interfaces and checks
+distinct sessions and their individual reply-interface metadata.
+IPv4 and dual-stack cases likewise use a single fixed client endpoint to send
+to one multicast group or the limited broadcast address on two interfaces,
+checking separate sessions and their reply-interface indices.
+Link-local IPv4 unicast and multicast regressions also check that accepted
+local endpoints have no IPv6 zone, on both IPv4 and dual-stack listeners.
+
+Run the standard suites on Linux:
+
+```sh
+(cd go-gost && go test ./...)
+(cd go-gost/x && go test ./...)
+```
+
+To exercise multiple IPv6 addresses without modifying the host's live network,
+compile the tests first and run them inside a disposable network namespace.
+The following commands require Linux, root access for `unshare`, and `iproute2`:
+
+```sh
+cd go-gost/x
+go test -c -race -o /tmp/flvx-udp-destination.test ./listener/udp
+go test -c -race -o /tmp/flvx-udp-packet.test ./internal/net/udp
+sudo unshare --net -- sh -eu -c '
+  sysctl -qw net.ipv6.conf.all.disable_ipv6=0
+  ip link set lo up
+  ip addr add 198.18.0.1/32 dev lo
+  ip addr add 169.254.1.2/32 dev lo
+  ip -6 addr add fd00:1::1/128 dev lo nodad
+  ip -6 addr add fd00:2::1/128 dev lo nodad
+  ip -6 addr add fd00:3::1/128 dev lo nodad
+  for suffix in "" 2; do
+    ip link add "mc-tx$suffix" type veth peer name "mc-rx$suffix"
+    ip link set "mc-tx$suffix" addrgenmode none up
+    ip link set "mc-rx$suffix" addrgenmode none up
+    ip -6 addr add fe80::1/64 dev "mc-tx$suffix" nodad
+    ip -6 addr add fe80::2/64 dev "mc-rx$suffix" nodad
+  done
+  ip addr add 198.18.1.1/24 dev mc-tx
+  ip addr add 198.18.2.1/24 dev mc-tx2
+  export FLUX_TEST_IPV6_ADDRS=fd00:1::1,fd00:2::1,fd00:3::1
+  export FLUX_TEST_IPV4_LINK_LOCAL=169.254.1.2
+  export FLUX_TEST_MULTICAST_RX=mc-rx FLUX_TEST_MULTICAST_TX=mc-tx
+  export FLUX_TEST_MULTICAST_RX2=mc-rx2 FLUX_TEST_MULTICAST_TX2=mc-tx2
+  /tmp/flvx-udp-destination.test -test.v -test.timeout=60s -test.count=5
+  exec /tmp/flvx-udp-packet.test -test.v -test.timeout=60s -test.count=5
+'
+```
+
+The addresses above are isolated test addresses, not deployment settings.
+The `UDP Destination Regression` GitHub Actions workflow runs these namespace
+tests, the race detector, both agent module suites, and a Linux agent build.

go-backend/Dockerfile

@@ -1,4 +1,5 @@
-FROM golang:1.25-bookworm AS builder
+# CVE-2026-111943: crypto/x509 is linked into paneld; rebuild with the fixed Go release.
+FROM golang:1.26.10-bookworm AS builder
 WORKDIR /src
 
 COPY go.mod go.sum ./

go-backend/cmd/paneld/main.go

@@ -12,9 +12,17 @@ import (
 
 	"go-backend/internal/app"
 	"go-backend/internal/config"
+	"go-backend/internal/panelupgrade"
 )
 
 func main() {
+	if len(os.Args) == 3 && os.Args[1] == "panel-upgrade-helper" {
+		if panelupgrade.RunHelper(os.Args[2]) != nil {
+			log.Print("panel upgrade helper stopped; inspect durable job status")
+			os.Exit(1)
+		}
+		return
+	}
 	cfg := config.FromEnv()
 	if cfg.JWTSecret == "" {
 		log.Println("warning: JWT_SECRET is empty")

go-backend/go.mod

@@ -1,13 +1,15 @@
 module go-backend
 
-go 1.25.0
+go 1.26.10
 
 require (
+	github.com/fxamacker/cbor/v2 v2.9.0
 	github.com/glebarez/sqlite v1.11.0
+	github.com/go-webauthn/webauthn v0.14.0
 	github.com/google/uuid v1.6.0
 	github.com/gorilla/websocket v1.5.3
 	github.com/jackc/pgx/v5 v5.9.2
-	golang.org/x/crypto v0.31.0
+	golang.org/x/crypto v0.42.0
 	gorm.io/driver/postgres v1.6.0
 	gorm.io/gorm v1.31.1
 )
@@ -15,14 +17,19 @@ require (
 require (
 	github.com/dustin/go-humanize v1.0.1 // indirect
 	github.com/glebarez/go-sqlite v1.21.2 // indirect
+	github.com/go-webauthn/x v0.1.25 // indirect
+	github.com/golang-jwt/jwt/v5 v5.3.0 // indirect
+	github.com/google/go-tpm v0.9.5 // indirect
 	github.com/jackc/pgpassfile v1.0.0 // indirect
 	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
 	github.com/jackc/puddle/v2 v2.2.2 // indirect
 	github.com/jinzhu/inflection v1.0.0 // indirect
 	github.com/jinzhu/now v1.1.5 // indirect
 	github.com/mattn/go-isatty v0.0.20 // indirect
+	github.com/mitchellh/mapstructure v1.5.0 // indirect
 	github.com/ncruces/go-strftime v0.1.9 // indirect
 	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
+	github.com/x448/float16 v0.8.4 // indirect
 	golang.org/x/exp v0.0.0-20250408133849-7e4ce0ab07d0 // indirect
 	golang.org/x/sync v0.20.0 // indirect
 	golang.org/x/sys v0.43.0 // indirect

go-backend/go.sum

@@ -3,10 +3,20 @@ github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
 github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
+github.com/fxamacker/cbor/v2 v2.9.0 h1:NpKPmjDBgUfBms6tr6JZkTHtfFGcMKsw3eGcmD/sapM=
+github.com/fxamacker/cbor/v2 v2.9.0/go.mod h1:vM4b+DJCtHn+zz7h3FFp/hDAI9WNWCsZj23V5ytsSxQ=
 github.com/glebarez/go-sqlite v1.21.2 h1:3a6LFC4sKahUunAmynQKLZceZCOzUthkRkEAl9gAXWo=
 github.com/glebarez/go-sqlite v1.21.2/go.mod h1:sfxdZyhQjTM2Wry3gVYWaW072Ri1WMdWJi0k6+3382k=
 github.com/glebarez/sqlite v1.11.0 h1:wSG0irqzP6VurnMEpFGer5Li19RpIRi2qvQz++w0GMw=
 github.com/glebarez/sqlite v1.11.0/go.mod h1:h8/o8j5wiAsqSPoWELDUdJXhjAhsVliSn7bWZjOhrgQ=
+github.com/go-webauthn/webauthn v0.14.0 h1:ZLNPUgPcDlAeoxe+5umWG/tEeCoQIDr7gE2Zx2QnhL0=
+github.com/go-webauthn/webauthn v0.14.0/go.mod h1:QZzPFH3LJ48u5uEPAu+8/nWJImoLBWM7iAH/kSVSo6k=
+github.com/go-webauthn/x v0.1.25 h1:g/0noooIGcz/yCVqebcFgNnGIgBlJIccS+LYAa+0Z88=
+github.com/go-webauthn/x v0.1.25/go.mod h1:ieblaPY1/BVCV0oQTsA/VAo08/TWayQuJuo5Q+XxmTY=
+github.com/golang-jwt/jwt/v5 v5.3.0 h1:pv4AsKCKKZuqlgs5sUmn4x8UlGa0kEVt/puTpKx9vvo=
+github.com/golang-jwt/jwt/v5 v5.3.0/go.mod h1:fxCRLWMO43lRc8nhHWY6LGqRcf+1gQWArsqaEUEa5bE=
+github.com/google/go-tpm v0.9.5 h1:ocUmnDebX54dnW+MQWGQRbdaAcJELsa6PqZhJ48KwVU=
+github.com/google/go-tpm v0.9.5/go.mod h1:h9jEsEECg7gtLis0upRBQU+GhYVH6jMjrFxI8u6bVUY=
 github.com/google/pprof v0.0.0-20250317173921-a4b03ec1a45e h1:ijClszYn+mADRFY17kjQEVQ1XRhq2/JR1M3sGqeJoxs=
 github.com/google/pprof v0.0.0-20250317173921-a4b03ec1a45e/go.mod h1:boTsfXsheKC2y+lKOCMpSfarhxDeIzfZG1jqGcPl3cA=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
@@ -27,6 +37,8 @@ github.com/jinzhu/now v1.1.5 h1:/o9tlHleP7gOFmsnYNz3RGnqzefHA47wQpKrrdTIwXQ=
 github.com/jinzhu/now v1.1.5/go.mod h1:d3SSVoowX0Lcu0IBviAWJpolVfI5UJVZZ7cO71lE/z8=
 github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
 github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
+github.com/mitchellh/mapstructure v1.5.0 h1:jeMsZIYE/09sWLaz43PL7Gy6RuMjD2eJVyuac5Z2hdY=
+github.com/mitchellh/mapstructure v1.5.0/go.mod h1:bFUtVrKA4DC2yAKiSyO/QUcy7e+RRV2QTWOzhPopBRo=
 github.com/ncruces/go-strftime v0.1.9 h1:bY0MQC28UADQmHmaF5dgpLmImcShSi2kHU9XLdhx/f4=
 github.com/ncruces/go-strftime v0.1.9/go.mod h1:Fwc5htZGVVkseilnfgOVb9mKy6w1naJmn9CehxcKcls=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
@@ -38,8 +50,12 @@ github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UV
 github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
 github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
-golang.org/x/crypto v0.31.0 h1:ihbySMvVjLAeSH1IbfcRTkD/iNscyz8rGzjF/E5hV6U=
-golang.org/x/crypto v0.31.0/go.mod h1:kDsLvtWBEx7MV9tJOj9bnXsPbxwJQ6csT/x4KIN4Ssk=
+github.com/x448/float16 v0.8.4 h1:qLwI1I70+NjRFUR3zs1JPUCgaCXSh3SW62uAKT1mSBM=
+github.com/x448/float16 v0.8.4/go.mod h1:14CWIYCyZA/cWjXOioeEpHeN/83MdbZDRQHoFcYsOfg=
+go.uber.org/mock v0.6.0 h1:hyF9dfmbgIX5EfOdasqLsWD6xqpNZlXblLB/Dbnwv3Y=
+go.uber.org/mock v0.6.0/go.mod h1:KiVJ4BqZJaMj4svdfmHM0AUx4NJYO8ZNpPnZn1Z+BBU=
+golang.org/x/crypto v0.42.0 h1:chiH31gIWm57EkTXpwnqf8qeuMUi0yekh6mT2AvFlqI=
+golang.org/x/crypto v0.42.0/go.mod h1:4+rDnOTJhQCx2q7/j6rAN5XDw8kPjeaXEUR2eL94ix8=
 golang.org/x/exp v0.0.0-20250408133849-7e4ce0ab07d0 h1:R84qjqJb5nVJMxqWYb3np9L5ZsaDtB+a39EqjV0JSUM=
 golang.org/x/exp v0.0.0-20250408133849-7e4ce0ab07d0/go.mod h1:S9Xr4PYopiDyqSyp5NjCrhFrqg6A5zA2E/iPHPhqnS8=
 golang.org/x/mod v0.34.0 h1:xIHgNUUnW6sYkcM5Jleh05DvLOtwc6RitGHbDk4akRI=
@@ -49,6 +65,8 @@ golang.org/x/sync v0.20.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
 golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.43.0 h1:Rlag2XtaFTxp19wS8MXlJwTvoh8ArU6ezoyFsMyCTNI=
 golang.org/x/sys v0.43.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/term v0.35.0 h1:bZBVKBudEyhRcajGcNc3jIfWPqV4y/Kt2XcoigOWtDQ=
+golang.org/x/term v0.35.0/go.mod h1:TPGtkTLesOwf2DE8CgVYiZinHAOuy5AYUYT1lENIZnA=
 golang.org/x/text v0.36.0 h1:JfKh3XmcRPqZPKevfXVpI1wXPTqbkE5f7JA92a55Yxg=
 golang.org/x/text v0.36.0/go.mod h1:NIdBknypM8iqVmPiuco0Dh6P5Jcdk8lJL0CUebqK164=
 golang.org/x/tools v0.43.0 h1:12BdW9CeB3Z+J/I/wj34VMl8X+fEXBxVR90JeMX5E7s=

go-backend/internal/http/client/federation.go

@@ -3,6 +3,7 @@ package client
 import (
 	"encoding/json"
 	"fmt"
+	"go-backend/internal/relaysecurity"
 	"io"
 	"net/http"
 	"strings"
@@ -14,17 +15,18 @@ type FederationClient struct {
 }
 
 type RemoteNodeInfo struct {
-	ShareID        int64  `json:"shareId"`
-	ShareName      string `json:"shareName"`
-	NodeID         int64  `json:"nodeId"`
-	NodeName       string `json:"nodeName"`
-	ServerIP       string `json:"serverIp"`
-	Status         int    `json:"status"`
-	MaxBandwidth   int64  `json:"maxBandwidth"`
-	CurrentFlow    int64  `json:"currentFlow"`
-	ExpiryTime     int64  `json:"expiryTime"`
-	PortRangeStart int    `json:"portRangeStart"`
-	PortRangeEnd   int    `json:"portRangeEnd"`
+	RelayAuthVersion int    `json:"relayAuthVersion"`
+	ShareID          int64  `json:"shareId"`
+	ShareName        string `json:"shareName"`
+	NodeID           int64  `json:"nodeId"`
+	NodeName         string `json:"nodeName"`
+	ServerIP         string `json:"serverIp"`
+	Status           int    `json:"status"`
+	MaxBandwidth     int64  `json:"maxBandwidth"`
+	CurrentFlow      int64  `json:"currentFlow"`
+	ExpiryTime       int64  `json:"expiryTime"`
+	PortRangeStart   int    `json:"portRangeStart"`
+	PortRangeEnd     int    `json:"portRangeEnd"`
 }
 
 type RemoteTunnelResponse struct {
@@ -38,30 +40,34 @@ type RuntimeReservePortRequest struct {
 }
 
 type RuntimeReservePortResponse struct {
-	ReservationID string `json:"reservationId"`
-	BindingID     string `json:"bindingId"`
-	AllocatedPort int    `json:"allocatedPort"`
+	RelayAuthVersion int    `json:"relayAuthVersion"`
+	ReservationID    string `json:"reservationId"`
+	BindingID        string `json:"bindingId"`
+	AllocatedPort    int    `json:"allocatedPort"`
 }
 
 type RuntimeTarget struct {
-	Host     string `json:"host"`
-	Port     int    `json:"port"`
-	Protocol string `json:"protocol"`
+	RelayAuth *relaysecurity.Credentials `json:"relayAuth,omitempty"`
+	Host      string                     `json:"host"`
+	Port      int                        `json:"port"`
+	Protocol  string                     `json:"protocol"`
 }
 
 type RuntimeApplyRoleRequest struct {
-	ReservationID string          `json:"reservationId"`
-	ResourceKey   string          `json:"resourceKey"`
-	Role          string          `json:"role"`
-	Protocol      string          `json:"protocol"`
-	Strategy      string          `json:"strategy"`
-	Targets       []RuntimeTarget `json:"targets"`
+	RelayAuth     *relaysecurity.Credentials `json:"relayAuth,omitempty"`
+	ReservationID string                     `json:"reservationId"`
+	ResourceKey   string                     `json:"resourceKey"`
+	Role          string                     `json:"role"`
+	Protocol      string                     `json:"protocol"`
+	Strategy      string                     `json:"strategy"`
+	Targets       []RuntimeTarget            `json:"targets"`
 }
 
 type RuntimeApplyRoleResponse struct {
-	BindingID     string `json:"bindingId"`
-	ReservationID string `json:"reservationId"`
-	AllocatedPort int    `json:"allocatedPort"`
+	RelayAuthVersion int    `json:"relayAuthVersion"`
+	BindingID        string `json:"bindingId"`
+	ReservationID    string `json:"reservationId"`
+	AllocatedPort    int    `json:"allocatedPort"`
 }
 
 type RuntimeReleaseRoleRequest struct {
@@ -247,6 +253,9 @@ func (c *FederationClient) ApplyRole(url, token, localDomain string, reqData Run
 	defer resp.Body.Close()
 
 	if resp.StatusCode != 200 {
+		if reqData.RelayAuth != nil {
+			return nil, fmt.Errorf("remote authenticated relay apply failed: HTTP %d", resp.StatusCode)
+		}
 		body, _ := io.ReadAll(resp.Body)
 		return nil, fmt.Errorf("remote error %d: %s", resp.StatusCode, string(body))
 	}
@@ -260,9 +269,16 @@ func (c *FederationClient) ApplyRole(url, token, localDomain string, reqData Run
 		return nil, err
 	}
 	if res.Code != 0 {
+		if reqData.RelayAuth != nil {
+			return nil, fmt.Errorf("remote authenticated relay apply failed: code %d", res.Code)
+		}
 		return nil, fmt.Errorf("remote api error: %s", res.Msg)
 	}
 
+	if reqData.RelayAuth != nil && res.Data.RelayAuthVersion != relaysecurity.Version {
+		return nil, fmt.Errorf("remote did not acknowledge required relay authentication")
+	}
+
 	return &res.Data, nil
 }
 

go-backend/internal/http/handler/config_access_test.go

@@ -19,6 +19,8 @@ func TestPublicConfigGetAllowsBrandKeys(t *testing.T) {
 	seedConfigValue(t, r, "app_logo", "logo-data")
 	seedConfigValue(t, r, "app_favicon", "favicon-data")
 	seedConfigValue(t, r, "app_bg_image", "bg-data")
+	seedConfigValue(t, r, "app_bg_image_light", "light-bg-data")
+	seedConfigValue(t, r, "app_bg_image_dark", "dark-bg-data")
 	seedConfigValue(t, r, "cloudflare_site_key", "site-key")
 
 	req := httptest.NewRequest(http.MethodPost, "/api/v1/public/config/get", bytes.NewBufferString(`{"name":"app_name"}`))
@@ -28,6 +30,16 @@ func TestPublicConfigGetAllowsBrandKeys(t *testing.T) {
 	router.ServeHTTP(resp, req)
 
 	assertHandlerCode(t, resp, 0)
+	for name, want := range map[string]string{
+		"app_bg_image_light": "light-bg-data",
+		"app_bg_image_dark":  "dark-bg-data",
+	} {
+		req := httptest.NewRequest(http.MethodPost, "/api/v1/public/config/get", bytes.NewBufferString(`{"name":"`+name+`"}`))
+		req.Header.Set("Content-Type", "application/json")
+		resp := httptest.NewRecorder()
+		router.ServeHTTP(resp, req)
+		assertHandlerConfigValue(t, resp, name, want)
+	}
 }
 
 func TestPublicBrandConfigFallsBackWithoutCommercialLicense(t *testing.T) {

go-backend/internal/http/handler/control_plane.go

@@ -534,7 +534,22 @@ func buildForwardServiceDeleteNames(bases []string) []string {
 	return names
 }
 
+type forwardServiceControlOptions struct {
+	tolerateNotFound bool
+	tolerateOffline  bool
+	allowSelfHeal    bool
+	continueOnError  bool
+}
+
 func (h *Handler) controlForwardServices(forward *forwardRecord, commandType string, tolerateNotFound bool) error {
+	return h.controlForwardServicesWithOptions(forward, commandType, forwardServiceControlOptions{
+		tolerateNotFound: tolerateNotFound,
+		tolerateOffline:  true,
+		allowSelfHeal:    true,
+	})
+}
+
+func (h *Handler) controlForwardServicesWithOptions(forward *forwardRecord, commandType string, opts forwardServiceControlOptions) error {
 	if h == nil || forward == nil {
 		return errors.New("invalid forward control context")
 	}
@@ -561,6 +576,7 @@ func (h *Handler) controlForwardServices(forward *forwardRecord, commandType str
 	candidateTunnelIDs = append(candidateTunnelIDs, userTunnelIDs...)
 	candidateTunnelIDs = append(candidateTunnelIDs, allUserTunnelIDs...)
 	bases := buildForwardServiceBaseCandidates(forward.ID, forward.UserID, userTunnelID, candidateTunnelIDs)
+	var nodeErrors []error
 	if strings.EqualFold(strings.TrimSpace(commandType), "DeleteService") {
 		seen := map[int64]struct{}{}
 		for _, fp := range ports {
@@ -569,16 +585,20 @@ func (h *Handler) controlForwardServices(forward *forwardRecord, commandType str
 			}
 			seen[fp.NodeID] = struct{}{}
 			if err := h.deleteForwardServiceBasesOnNode(fp.NodeID, bases); err != nil {
-				if isNodeOfflineOrTimeoutError(err) {
+				if opts.tolerateOffline && isNodeOfflineOrTimeoutError(err) {
 					continue
 				}
-				if tolerateNotFound && isNotFoundError(err) {
+				if opts.tolerateNotFound && isNotFoundError(err) {
+					continue
+				}
+				if opts.continueOnError {
+					nodeErrors = append(nodeErrors, h.nodeCommandError(fp.NodeID, err))
 					continue
 				}
 				return err
 			}
 		}
-		return nil
+		return errors.Join(nodeErrors...)
 	}
 	seen := map[int64]struct{}{}
 	healed := false
@@ -588,37 +608,50 @@ func (h *Handler) controlForwardServices(forward *forwardRecord, commandType str
 		}
 		seen[fp.NodeID] = struct{}{}
 
-		nodeHandled, lastNotFoundErr, err := h.controlForwardServicesOnNode(fp.NodeID, bases, commandType)
-		if err != nil {
-			if isNodeOfflineOrTimeoutError(err) {
-				continue
-			}
-			return err
-		}
-
-		if !nodeHandled && lastNotFoundErr != nil && !healed && shouldSelfHealForwardServiceControl(commandType) {
-			if healErr := h.syncForwardServices(forward, "UpdateService", true); healErr != nil {
-				return healErr
-			}
-			healed = true
-			nodeHandled, lastNotFoundErr, err = h.controlForwardServicesOnNode(fp.NodeID, bases, commandType)
+		nodeErr := func() error {
+			nodeHandled, lastNotFoundErr, err := h.controlForwardServicesOnNode(fp.NodeID, bases, commandType)
 			if err != nil {
+				if opts.tolerateOffline && isNodeOfflineOrTimeoutError(err) {
+					return nil
+				}
 				return err
 			}
-		}
 
-		if nodeHandled {
-			continue
+			if opts.allowSelfHeal && !nodeHandled && lastNotFoundErr != nil && !healed && shouldSelfHealForwardServiceControl(commandType) {
+				if healErr := h.syncForwardServices(forward, "UpdateService", true); healErr != nil {
+					return healErr
+				}
+				healed = true
+				nodeHandled, lastNotFoundErr, err = h.controlForwardServicesOnNode(fp.NodeID, bases, commandType)
+				if err != nil {
+					return err
+				}
+			}
+
+			if nodeHandled || opts.tolerateNotFound {
+				return nil
+			}
+			if lastNotFoundErr != nil {
+				return lastNotFoundErr
+			}
+			return errors.New("service control failed")
+		}()
+		if nodeErr != nil {
+			if !opts.continueOnError {
+				return nodeErr
+			}
+			nodeErrors = append(nodeErrors, h.nodeCommandError(fp.NodeID, nodeErr))
 		}
-		if tolerateNotFound {
-			continue
-		}
-		if lastNotFoundErr != nil {
-			return lastNotFoundErr
-		}
-		return errors.New("service control failed")
 	}
-	return nil
+	return errors.Join(nodeErrors...)
+}
+
+func (h *Handler) nodeCommandError(nodeID int64, err error) error {
+	name := strconv.FormatInt(nodeID, 10)
+	if node, lookupErr := h.getNodeRecord(nodeID); lookupErr == nil && node != nil {
+		name = defaultString(strings.TrimSpace(node.Name), name)
+	}
+	return fmt.Errorf("节点 %s (ID %d): %w", name, nodeID, err)
 }
 
 func (h *Handler) controlForwardServicesOnNode(nodeID int64, bases []string, commandType string) (bool, error, error) {
@@ -1939,7 +1972,12 @@ func buildForwardServiceConfigs(baseName string, forward *forwardRecord, tunnel
 			service["listener"].(map[string]interface{})["metadata"] = listenerMetadata
 		}
 		if tunnel != nil && tunnel.Type == 2 {
-			service["handler"].(map[string]interface{})["chain"] = fmt.Sprintf("chains_%d", forward.TunnelID)
+			handlerConfig := service["handler"].(map[string]interface{})
+			handlerConfig["chain"] = fmt.Sprintf("chains_%d", forward.TunnelID)
+			if handlerConfig["metadata"] == nil {
+				handlerConfig["metadata"] = map[string]interface{}{}
+			}
+			handlerConfig["metadata"].(map[string]interface{})["chain.strict"] = true
 		}
 		if tunnel != nil && tunnel.Type == 1 && strings.TrimSpace(node.InterfaceName) != "" {
 			serviceMetadata := ensureServiceMetadata(service)

go-backend/internal/http/handler/federation.go

@@ -1,8 +1,11 @@
 package handler
 
 import (
+	"bytes"
 	"encoding/json"
+	"errors"
 	"fmt"
+	"io"
 	"net"
 	"net/http"
 	"net/url"
@@ -14,6 +17,7 @@ import (
 
 	"go-backend/internal/http/client"
 	"go-backend/internal/http/response"
+	"go-backend/internal/relaysecurity"
 	"go-backend/internal/store/repo"
 )
 
@@ -65,18 +69,20 @@ type federationRuntimeReservePortRequest struct {
 }
 
 type federationRuntimeTarget struct {
-	Host     string `json:"host"`
-	Port     int    `json:"port"`
-	Protocol string `json:"protocol"`
+	RelayAuth *relaysecurity.Credentials `json:"relayAuth,omitempty"`
+	Host      string                     `json:"host"`
+	Port      int                        `json:"port"`
+	Protocol  string                     `json:"protocol"`
 }
 
 type federationRuntimeApplyRoleRequest struct {
-	ReservationID string                    `json:"reservationId"`
-	ResourceKey   string                    `json:"resourceKey"`
-	Role          string                    `json:"role"`
-	Protocol      string                    `json:"protocol"`
-	Strategy      string                    `json:"strategy"`
-	Targets       []federationRuntimeTarget `json:"targets"`
+	RelayAuth     *relaysecurity.Credentials `json:"relayAuth,omitempty"`
+	ReservationID string                     `json:"reservationId"`
+	ResourceKey   string                     `json:"resourceKey"`
+	Role          string                     `json:"role"`
+	Protocol      string                     `json:"protocol"`
+	Strategy      string                     `json:"strategy"`
+	Targets       []federationRuntimeTarget  `json:"targets"`
 }
 
 type federationRuntimeReleaseRoleRequest struct {
@@ -112,6 +118,13 @@ func buildFederationMiddleChainConfig(chainName string, runtimeID int64, protoco
 		connector := map[string]interface{}{
 			"type": "relay",
 		}
+		if target.RelayAuth != nil {
+			if err := target.RelayAuth.Validate(); err != nil {
+				return nil, err
+			}
+			connector["auth"] = target.RelayAuth.Config()
+		}
+
 		if isTCPTunnelProtocol(targetProtocol) {
 			connector["metadata"] = map[string]interface{}{
 				"nodelay":               true,
@@ -218,7 +231,7 @@ type remoteUsageNodeItem struct {
 	SyncError        string                   `json:"syncError,omitempty"`
 }
 
-func buildFederationServiceConfig(serviceName, addr, protocol, role, chainName string, targetCount int, interfaceName string) map[string]interface{} {
+func buildFederationServiceConfig(serviceName, addr, protocol, role, chainName string, targetCount int, interfaceName string, credentials *relaysecurity.Credentials) map[string]interface{} {
 	service := map[string]interface{}{
 		"name": serviceName,
 		"addr": addr,
@@ -227,6 +240,10 @@ func buildFederationServiceConfig(serviceName, addr, protocol, role, chainName s
 		},
 		"listener": buildTunnelListenerConfig(protocol),
 	}
+	if credentials != nil {
+		service["handler"].(map[string]interface{})["auth"] = credentials.Config()
+	}
+
 	if isTCPTunnelProtocol(protocol) {
 		service["handler"].(map[string]interface{})["metadata"] = map[string]interface{}{
 			"nodelay":               true,
@@ -240,6 +257,13 @@ func buildFederationServiceConfig(serviceName, addr, protocol, role, chainName s
 		}
 	}
 	if role == "middle" {
+		handler := service["handler"].(map[string]interface{})
+		md, _ := handler["metadata"].(map[string]interface{})
+		if md == nil {
+			md = map[string]interface{}{}
+			handler["metadata"] = md
+		}
+		md["chain.strict"] = true
 		service["handler"].(map[string]interface{})["chain"] = chainName
 		if targetCount > 1 {
 			service["handler"].(map[string]interface{})["retries"] = targetCount - 1
@@ -408,9 +432,26 @@ func (h *Handler) federationShareDelete(w http.ResponseWriter, r *http.Request)
 		return
 	}
 
-	share, _ := h.repo.GetPeerShare(req.ID)
+	share, err := h.repo.GetPeerShare(req.ID)
+	if err != nil {
+		response.WriteJSON(w, response.ErrDefault(err.Error()))
+		return
+	}
+	if share != nil {
+		// Revoke new allocations before cleanup; failed deletions keep the
+		// disabled share and its reservations available for retry.
+		share.IsActive = 0
+		share.UpdatedTime = time.Now().UnixMilli()
+		if err := h.repo.UpdatePeerShare(share); err != nil {
+			response.WriteJSON(w, response.ErrDefault(err.Error()))
+			return
+		}
+	}
 
-	h.cleanupPeerShareRuntimes(req.ID)
+	if err := h.cleanupPeerShareRuntimes(req.ID); err != nil {
+		response.WriteJSON(w, response.ErrDefault(err.Error()))
+		return
+	}
 	h.cleanupFederationTunnels(req.ID)
 
 	if err := h.repo.DeletePeerShare(req.ID); err != nil {
@@ -418,10 +459,6 @@ func (h *Handler) federationShareDelete(w http.ResponseWriter, r *http.Request)
 		return
 	}
 
-	if share != nil && h.wsServer != nil {
-		h.wsServer.SendCommand(share.NodeID, "reload", nil, time.Second*5)
-	}
-
 	response.WriteJSON(w, response.OKEmpty())
 }
 
@@ -805,16 +842,6 @@ func (h *Handler) authPeer(next http.HandlerFunc) http.HandlerFunc {
 			return
 		}
 
-		if share.IsActive == 0 {
-			response.WriteJSON(w, response.Err(403, "Share is disabled"))
-			return
-		}
-
-		if share.ExpiryTime > 0 && share.ExpiryTime < time.Now().UnixMilli() {
-			response.WriteJSON(w, response.Err(403, "Share expired"))
-			return
-		}
-
 		if strings.TrimSpace(share.AllowedIPs) != "" {
 			clientIP := resolvePeerClientIP(r)
 			if clientIP == nil {
@@ -847,10 +874,48 @@ func (h *Handler) authPeer(next http.HandlerFunc) http.HandlerFunc {
 			}
 		}
 
+		if share.IsActive != 1 || (share.ExpiryTime > 0 && share.ExpiryTime <= time.Now().UnixMilli()) || isPeerShareFlowExceeded(share) {
+			if !isFederationCleanupRequest(r) {
+				response.WriteJSON(w, response.Err(403, "Share is inactive, expired, or over quota"))
+				return
+			}
+		}
+
 		next(w, r)
 	}
 }
 
+// Revoked allocation privileges must not revoke cleanup privileges. Inspect
+// only supported destructive commands, preserving the body for the handler.
+func isFederationCleanupRequest(r *http.Request) bool {
+	if r.Method != http.MethodPost {
+		return false
+	}
+	switch r.URL.Path {
+	case "/api/v1/federation/runtime/release-role":
+		return true
+	case "/api/v1/federation/runtime/command":
+		if r.Body == nil {
+			return false
+		}
+		var copied bytes.Buffer
+		original := r.Body
+		var request federationRuntimeCommandRequest
+		err := json.NewDecoder(io.TeeReader(io.LimitReader(original, 1<<20), &copied)).Decode(&request)
+		r.Body = struct {
+			io.Reader
+			io.Closer
+		}{Reader: io.MultiReader(&copied, original), Closer: original}
+		if err != nil || !isFederationRuntimeCommandAllowed(request.CommandType) {
+			return false
+		}
+		_, action := federationResourceCommandKind(request.CommandType)
+		return action == "delete"
+	default:
+		return false
+	}
+}
+
 func (h *Handler) federationConnect(w http.ResponseWriter, r *http.Request) {
 	if r.Method != http.MethodPost {
 		response.WriteJSON(w, response.ErrDefault("Invalid method"))
@@ -871,17 +936,18 @@ func (h *Handler) federationConnect(w http.ResponseWriter, r *http.Request) {
 	}
 
 	response.WriteJSON(w, response.OK(map[string]interface{}{
-		"shareId":        share.ID,
-		"shareName":      share.Name,
-		"nodeId":         share.NodeID,
-		"nodeName":       nodeInfo.Name,
-		"serverIp":       nodeInfo.ServerIP,
-		"status":         nodeInfo.Status,
-		"maxBandwidth":   share.MaxBandwidth,
-		"currentFlow":    share.CurrentFlow,
-		"expiryTime":     share.ExpiryTime,
-		"portRangeStart": share.PortRangeStart,
-		"portRangeEnd":   share.PortRangeEnd,
+		"shareId":          share.ID,
+		"relayAuthVersion": relaysecurity.Version,
+		"shareName":        share.Name,
+		"nodeId":           share.NodeID,
+		"nodeName":         nodeInfo.Name,
+		"serverIp":         nodeInfo.ServerIP,
+		"status":           nodeInfo.Status,
+		"maxBandwidth":     share.MaxBandwidth,
+		"currentFlow":      share.CurrentFlow,
+		"expiryTime":       share.ExpiryTime,
+		"portRangeStart":   share.PortRangeStart,
+		"portRangeEnd":     share.PortRangeEnd,
 	}))
 }
 
@@ -982,8 +1048,6 @@ func (h *Handler) federationTunnelCreate(w http.ResponseWriter, r *http.Request)
 		return
 	}
 
-	h.wsServer.SendCommand(share.NodeID, "reload", nil, time.Second*5)
-
 	response.WriteJSON(w, response.OK(map[string]interface{}{
 		"tunnelId": tunnelID,
 	}))
@@ -1013,21 +1077,35 @@ func (h *Handler) federationRuntimeReservePort(w http.ResponseWriter, r *http.Re
 		return
 	}
 
+	peerRoleRuntimeMu.Lock()
+	defer peerRoleRuntimeMu.Unlock()
+	share, err = h.repo.GetPeerShare(share.ID)
+	if err != nil || share == nil || share.IsActive != 1 || (share.ExpiryTime > 0 && share.ExpiryTime <= time.Now().UnixMilli()) {
+		response.WriteJSON(w, response.Err(403, "Share is unavailable"))
+		return
+	}
+
+	if isPeerShareFlowExceeded(share) {
+		response.WriteJSON(w, response.Err(403, "Share traffic limit exceeded"))
+		return
+	}
+
 	existing, err := h.repo.GetPeerShareRuntimeByResourceKey(share.ID, req.ResourceKey)
 	if err != nil {
 		response.WriteJSON(w, response.Err(-2, err.Error()))
 		return
 	}
-	if existing != nil && existing.Status == 1 {
-		response.WriteJSON(w, response.OK(map[string]interface{}{
-			"reservationId": existing.ReservationID,
-			"allocatedPort": existing.Port,
-			"bindingId":     existing.BindingID,
-		}))
+	if existing != nil && existing.ReleasePending != 0 {
+		response.WriteJSON(w, response.ErrDefault("Runtime release is pending"))
 		return
 	}
-	if isPeerShareFlowExceeded(share) {
-		response.WriteJSON(w, response.Err(403, "Share traffic limit exceeded"))
+	if existing != nil && existing.Status == 1 {
+		response.WriteJSON(w, response.OK(map[string]interface{}{
+			"reservationId":    existing.ReservationID,
+			"allocatedPort":    existing.Port,
+			"relayAuthVersion": relaysecurity.Version,
+			"bindingId":        existing.BindingID,
+		}))
 		return
 	}
 
@@ -1039,6 +1117,7 @@ func (h *Handler) federationRuntimeReservePort(w http.ResponseWriter, r *http.Re
 
 	now := time.Now().UnixMilli()
 	if existing != nil {
+		existing.ReservationID = randomToken(24)
 		existing.Protocol = defaultString(req.Protocol, "tls")
 		existing.Port = allocatedPort
 		existing.BindingID = ""
@@ -1047,6 +1126,8 @@ func (h *Handler) federationRuntimeReservePort(w http.ResponseWriter, r *http.Re
 		existing.ServiceName = ""
 		existing.Strategy = "round"
 		existing.Target = ""
+		existing.RelayAuth = ""
+		existing.RelayAuthVersion = 0
 		existing.Applied = 0
 		existing.Status = 1
 		existing.UpdatedTime = now
@@ -1055,9 +1136,10 @@ func (h *Handler) federationRuntimeReservePort(w http.ResponseWriter, r *http.Re
 			return
 		}
 		response.WriteJSON(w, response.OK(map[string]interface{}{
-			"reservationId": existing.ReservationID,
-			"allocatedPort": existing.Port,
-			"bindingId":     existing.BindingID,
+			"reservationId":    existing.ReservationID,
+			"allocatedPort":    existing.Port,
+			"relayAuthVersion": relaysecurity.Version,
+			"bindingId":        existing.BindingID,
 		}))
 		return
 	}
@@ -1086,9 +1168,10 @@ func (h *Handler) federationRuntimeReservePort(w http.ResponseWriter, r *http.Re
 	}
 
 	response.WriteJSON(w, response.OK(map[string]interface{}{
-		"reservationId": runtime.ReservationID,
-		"allocatedPort": runtime.Port,
-		"bindingId":     runtime.BindingID,
+		"reservationId":    runtime.ReservationID,
+		"allocatedPort":    runtime.Port,
+		"relayAuthVersion": relaysecurity.Version,
+		"bindingId":        runtime.BindingID,
 	}))
 }
 
@@ -1116,6 +1199,14 @@ func (h *Handler) federationRuntimeApplyRole(w http.ResponseWriter, r *http.Requ
 		return
 	}
 
+	peerRoleRuntimeMu.Lock()
+	defer peerRoleRuntimeMu.Unlock()
+	share, err = h.repo.GetPeerShare(share.ID)
+	if err != nil || share == nil || share.IsActive != 1 || (share.ExpiryTime > 0 && share.ExpiryTime <= time.Now().UnixMilli()) {
+		response.WriteJSON(w, response.ErrDefault("Share is unavailable"))
+		return
+	}
+
 	var runtime *repo.PeerShareRuntime
 	if strings.TrimSpace(req.ReservationID) != "" {
 		runtime, err = h.repo.GetPeerShareRuntimeByReservationID(share.ID, strings.TrimSpace(req.ReservationID))
@@ -1131,115 +1222,59 @@ func (h *Handler) federationRuntimeApplyRole(w http.ResponseWriter, r *http.Requ
 		return
 	}
 
-	node, err := h.getNodeRecord(share.NodeID)
-	if err != nil {
-		response.WriteJSON(w, response.ErrDefault(err.Error()))
-		return
-	}
-
-	protocol := defaultString(req.Protocol, runtime.Protocol)
-	strategy := defaultString(req.Strategy, "round")
-	chainName := defaultString(runtime.ChainName, federationRuntimeChainName(runtime.BindingID))
-	if chainName == "" {
-		chainName = federationRuntimeChainName(fmt.Sprintf("%d", runtime.ID))
-	}
-	serviceName := fmt.Sprintf("fed_svc_%d", runtime.ID)
-	if runtime.Applied == 1 && strings.TrimSpace(runtime.BindingID) != "" {
-		if req.Role == "middle" && len(req.Targets) > 0 {
-			chainData, buildErr := buildFederationMiddleChainConfig(chainName, runtime.ID, protocol, strategy, req.Targets, node.InterfaceName)
-			if buildErr != nil {
-				response.WriteJSON(w, response.ErrDefault(buildErr.Error()))
-				return
-			}
-			if _, err := h.sendNodeCommand(share.NodeID, "UpdateChains", updateChainPayload(chainName, chainData), false, false); err != nil {
-				response.WriteJSON(w, response.ErrDefault(err.Error()))
-				return
-			}
-			targetBytes, _ := json.Marshal(req.Targets)
-			runtime.Role = req.Role
-			runtime.ChainName = chainName
-			runtime.Protocol = protocol
-			runtime.Strategy = strategy
-			runtime.Target = string(targetBytes)
-			runtime.Status = 1
-			runtime.UpdatedTime = time.Now().UnixMilli()
-			if err := h.repo.UpdatePeerShareRuntime(runtime); err != nil {
-				response.WriteJSON(w, response.Err(-2, err.Error()))
-				return
-			}
-		}
-		response.WriteJSON(w, response.OK(map[string]interface{}{
-			"bindingId":     runtime.BindingID,
-			"allocatedPort": runtime.Port,
-			"reservationId": runtime.ReservationID,
-		}))
+	if runtime.ReleasePending != 0 {
+		response.WriteJSON(w, response.ErrDefault("Runtime release is pending"))
 		return
 	}
 	if isPeerShareFlowExceeded(share) {
 		response.WriteJSON(w, response.Err(403, "Share traffic limit exceeded"))
 		return
 	}
-
-	if share.PortRangeStart > 0 && share.PortRangeEnd > 0 && runtime.Port > 0 {
-		if runtime.Port < share.PortRangeStart || runtime.Port > share.PortRangeEnd {
-			response.WriteJSON(w, response.Err(403, fmt.Sprintf("port %d out of allowed range %d-%d", runtime.Port, share.PortRangeStart, share.PortRangeEnd)))
-			return
-		}
+	if runtime.Role != "" && runtime.Role != req.Role {
+		response.WriteJSON(w, response.ErrDefault("Runtime role cannot change without release"))
+		return
+	}
+	if share.PortRangeStart > 0 && share.PortRangeEnd > 0 && (runtime.Port < share.PortRangeStart || runtime.Port > share.PortRangeEnd) {
+		response.WriteJSON(w, response.ErrDefault("Reserved port is outside share range"))
+		return
+	}
+	if _, err := decodeRuntimeRelayAuth(runtime); err != nil {
+		response.WriteJSON(w, response.ErrDefault(err.Error()))
+		return
+	}
+	if err := validateFederationRelayAuth(runtime.RelayAuth, req.RelayAuth, req.Targets); err != nil {
+		response.WriteJSON(w, response.ErrDefault(err.Error()))
+		return
+	}
+	if req.RelayAuth != nil {
+		encoded, _ := json.Marshal(req.RelayAuth)
+		runtime.RelayAuth = string(encoded)
+		runtime.RelayAuthVersion = relaysecurity.Version
 	}
 
+	if strings.TrimSpace(runtime.BindingID) == "" {
+		runtime.BindingID = randomToken(24)
+	}
+	runtime.Role = req.Role
+	runtime.ServiceName = fmt.Sprintf("fed_svc_%d", runtime.ID)
+	runtime.ChainName = ""
 	if req.Role == "middle" {
-		chainData, buildErr := buildFederationMiddleChainConfig(chainName, runtime.ID, protocol, strategy, req.Targets, node.InterfaceName)
-		if buildErr != nil {
-			response.WriteJSON(w, response.ErrDefault(buildErr.Error()))
-			return
-		}
-		if _, err := h.sendNodeCommand(share.NodeID, "AddChains", chainData, true, false); err != nil {
-			response.WriteJSON(w, response.ErrDefault(err.Error()))
-			return
-		}
+		runtime.ChainName = federationRuntimeChainName(runtime.BindingID)
 	}
-
-	targetCount := len(req.Targets)
-	service := buildFederationServiceConfig(
-		serviceName,
-		fmt.Sprintf("%s:%d", node.TCPListenAddr, runtime.Port),
-		protocol,
-		req.Role,
-		chainName,
-		targetCount,
-		node.InterfaceName,
-	)
-	if _, err := h.sendNodeCommand(share.NodeID, "AddService", []map[string]interface{}{service}, true, false); err != nil {
-		if req.Role == "middle" {
-			_, _ = h.sendNodeCommand(share.NodeID, "DeleteChains", map[string]interface{}{"chain": chainName}, false, true)
-		}
+	runtime.Protocol = defaultString(req.Protocol, runtime.Protocol)
+	runtime.Strategy = defaultString(req.Strategy, "round")
+	targetBytes, _ := json.Marshal(req.Targets)
+	runtime.Target = string(targetBytes)
+	if err := h.applyPeerShareRoleRuntime(runtime); err != nil {
 		response.WriteJSON(w, response.ErrDefault(err.Error()))
 		return
 	}
 
-	targetBytes, _ := json.Marshal(req.Targets)
-	runtime.BindingID = fmt.Sprintf("%d", runtime.ID)
-	runtime.Role = req.Role
-	runtime.ChainName = ""
-	if req.Role == "middle" {
-		runtime.ChainName = chainName
-	}
-	runtime.ServiceName = serviceName
-	runtime.Protocol = protocol
-	runtime.Strategy = strategy
-	runtime.Target = string(targetBytes)
-	runtime.Applied = 1
-	runtime.Status = 1
-	runtime.UpdatedTime = time.Now().UnixMilli()
-	if err := h.repo.UpdatePeerShareRuntime(runtime); err != nil {
-		response.WriteJSON(w, response.Err(-2, err.Error()))
-		return
-	}
-
 	response.WriteJSON(w, response.OK(map[string]interface{}{
-		"bindingId":     runtime.BindingID,
-		"reservationId": runtime.ReservationID,
-		"allocatedPort": runtime.Port,
+		"relayAuthVersion": relayAuthVersion(req.RelayAuth),
+		"bindingId":        runtime.BindingID,
+		"reservationId":    runtime.ReservationID,
+		"allocatedPort":    runtime.Port,
 	}))
 }
 
@@ -1282,17 +1317,8 @@ func (h *Handler) federationRuntimeReleaseRole(w http.ResponseWriter, r *http.Re
 		return
 	}
 
-	if runtime.Applied == 1 {
-		if strings.TrimSpace(runtime.ServiceName) != "" {
-			_, _ = h.sendNodeCommand(share.NodeID, "DeleteService", map[string]interface{}{"services": []string{runtime.ServiceName}}, false, true)
-		}
-		if strings.TrimSpace(runtime.Role) == "middle" && strings.TrimSpace(runtime.ChainName) != "" {
-			_, _ = h.sendNodeCommand(share.NodeID, "DeleteChains", map[string]interface{}{"chain": runtime.ChainName}, false, true)
-		}
-	}
-
-	if err := h.repo.MarkPeerShareRuntimeReleased(runtime.ID, time.Now().UnixMilli()); err != nil {
-		response.WriteJSON(w, response.Err(-2, err.Error()))
+	if err := h.releasePeerShareRuntime(runtime); err != nil {
+		response.WriteJSON(w, response.ErrDefault(err.Error()))
 		return
 	}
 
@@ -1385,6 +1411,15 @@ func (h *Handler) federationRuntimeCommand(w http.ResponseWriter, r *http.Reques
 		return
 	}
 
+	h.peerResourceMu.Lock()
+	defer h.peerResourceMu.Unlock()
+	// Recheck after acquiring the mutation lock: an earlier authentication
+	// decision cannot authorize a recreation after quota/expiry cleanup.
+	share, err = h.repo.GetPeerShare(share.ID)
+	if err != nil || share == nil {
+		response.WriteJSON(w, response.ErrDefault("share ownership unavailable"))
+		return
+	}
 	if isFederationServiceCommand(cmd) {
 		if err := validateFederationCommandPorts(share, req.Data); err != nil {
 			response.WriteJSON(w, response.Err(403, err.Error()))
@@ -1392,17 +1427,35 @@ func (h *Handler) federationRuntimeCommand(w http.ResponseWriter, r *http.Reques
 		}
 	}
 
-	res, err := h.sendNodeCommand(share.NodeID, cmd, req.Data, false, false)
+	_, action := federationResourceCommandKind(cmd)
+	if action != "delete" && (share.IsActive != 1 || (share.ExpiryTime > 0 && share.ExpiryTime <= time.Now().UnixMilli()) || isPeerShareFlowExceeded(share)) {
+		response.WriteJSON(w, response.Err(403, "share is inactive, expired, or over quota"))
+		return
+	}
+	if strings.EqualFold(cmd, "tcpping") {
+		res, err := h.sendNodeCommand(share.NodeID, "TcpPing", req.Data, false, false)
+		if err != nil {
+			response.WriteJSON(w, response.ErrDefault(err.Error()))
+			return
+		}
+		response.WriteJSON(w, response.OK(res))
+		return
+	}
+	items, err := h.preparePeerResourceCommand(share, cmd, req.Data)
 	if err != nil {
 		response.WriteJSON(w, response.ErrDefault(err.Error()))
 		return
 	}
-	if strings.EqualFold(cmd, "addservice") || strings.EqualFold(cmd, "updateservice") {
-		h.bindPeerShareForwardRuntimeServices(share, req.Data)
-	} else if strings.EqualFold(cmd, "deleteservice") {
-		h.releasePeerShareForwardRuntimeServices(share, req.Data)
+	var result interface{} = map[string]interface{}{"success": true}
+	for _, item := range items {
+		res, err := h.applyPeerShareResource(item)
+		if err != nil {
+			response.WriteJSON(w, response.ErrDefault(err.Error()))
+			return
+		}
+		result = res
 	}
-	response.WriteJSON(w, response.OK(res))
+	response.WriteJSON(w, response.OK(result))
 }
 
 type federationForwardServiceBinding struct {
@@ -1436,10 +1489,15 @@ func parseFederationForwardServiceBindings(data interface{}) []federationForward
 	bindings := make([]federationForwardServiceBinding, 0, len(serviceList))
 	for _, svcMap := range serviceList {
 		name := normalizeForwardRuntimeServiceName(asString(svcMap["name"]))
+		originalName := name
+		if shareID, original, ok := parsePeerShareServiceName(asString(svcMap["name"])); ok {
+			originalName = normalizeForwardRuntimeServiceName(original)
+			name = peerShareResourceName(shareID, "service", originalName)
+		}
 		if name == "" {
 			continue
 		}
-		if _, _, _, ok := parseFlowServiceIDs(name); !ok {
+		if _, _, _, ok := parseFlowServiceIDs(originalName); !ok {
 			continue
 		}
 		addr := strings.TrimSpace(asString(svcMap["addr"]))
@@ -1498,29 +1556,29 @@ func parseFederationForwardServiceNamesForRelease(data interface{}) []string {
 	return out
 }
 
-func (h *Handler) bindPeerShareForwardRuntimeServices(share *repo.PeerShare, data interface{}) {
+func (h *Handler) bindPeerShareForwardRuntimeServices(share *repo.PeerShare, data interface{}) error {
 	if h == nil || h.repo == nil || share == nil {
-		return
+		return nil
 	}
 	bindings := parseFederationForwardServiceBindings(data)
 	if len(bindings) == 0 {
-		return
+		return nil
 	}
 
 	now := time.Now().UnixMilli()
 	for _, binding := range bindings {
 		runtime, err := h.repo.GetActiveForwardPeerShareRuntimeByPort(share.ID, binding.Port)
 		if err != nil {
-			continue
+			return err
 		}
 		if runtime == nil {
 			runtime, err = h.repo.GetActiveForwardPeerShareRuntimeByServiceName(share.ID, binding.Name)
 			if err != nil {
-				continue
+				return err
 			}
 		}
 		if runtime == nil {
-			_ = h.repo.CreatePeerShareRuntime(&repo.PeerShareRuntime{
+			if err := h.repo.CreatePeerShareRuntime(&repo.PeerShareRuntime{
 				ShareID:       share.ID,
 				NodeID:        share.NodeID,
 				ReservationID: randomToken(24),
@@ -1537,9 +1595,14 @@ func (h *Handler) bindPeerShareForwardRuntimeServices(share *repo.PeerShare, dat
 				Status:        1,
 				CreatedTime:   now,
 				UpdatedTime:   now,
-			})
+			}); err != nil {
+				return err
+			}
 			continue
 		}
+		if runtime.ReleasePending != 0 {
+			return fmt.Errorf("runtime release is pending")
+		}
 		if runtime.ServiceName == binding.Name && runtime.Applied == 1 && runtime.Port == binding.Port && runtime.Status == 1 {
 			continue
 		}
@@ -1554,8 +1617,11 @@ func (h *Handler) bindPeerShareForwardRuntimeServices(share *repo.PeerShare, dat
 		if strings.TrimSpace(runtime.Strategy) == "" {
 			runtime.Strategy = "fifo"
 		}
-		_ = h.repo.UpdatePeerShareRuntime(runtime)
+		if err := h.repo.UpdatePeerShareRuntime(runtime); err != nil {
+			return err
+		}
 	}
+	return nil
 }
 
 func (h *Handler) releasePeerShareForwardRuntimeServices(share *repo.PeerShare, data interface{}) {
@@ -1575,7 +1641,7 @@ func (h *Handler) releasePeerShareForwardRuntimeServices(share *repo.PeerShare,
 
 func isFederationRuntimeCommandAllowed(commandType string) bool {
 	switch strings.ToLower(strings.TrimSpace(commandType)) {
-	case "addservice", "updateservice", "deleteservice", "pauseservice", "resumeservice", "addchains", "deletechains", "addlimiters", "updatelimiters", "deletelimiters", "tcpping", "reload":
+	case "addservice", "updateservice", "deleteservice", "pauseservice", "resumeservice", "addchains", "updatechains", "deletechains", "addlimiters", "updatelimiters", "deletelimiters", "addclimiters", "updateclimiters", "deleteclimiters", "tcpping":
 		return true
 	default:
 		return false
@@ -1893,27 +1959,24 @@ func (h *Handler) syncRemoteNodeStatuses(items []map[string]interface{}) {
 	}
 }
 
-func (h *Handler) cleanupPeerShareRuntimes(shareID int64) {
+func (h *Handler) cleanupPeerShareRuntimes(shareID int64) error {
 	if h == nil || h.repo == nil || shareID <= 0 {
-		return
+		return nil
+	}
+	if err := h.releasePeerShareResources(shareID); err != nil {
+		return err
 	}
 	runtimes, err := h.repo.ListActivePeerShareRuntimesByShareID(shareID)
-	if err != nil || len(runtimes) == 0 {
-		return
+	if err != nil {
+		return err
 	}
-
-	now := time.Now().UnixMilli()
-	for _, runtime := range runtimes {
-		if h.wsServer != nil && runtime.Applied == 1 {
-			if strings.TrimSpace(runtime.ServiceName) != "" {
-				_, _ = h.sendNodeCommand(runtime.NodeID, "DeleteService", map[string]interface{}{"services": []string{runtime.ServiceName}}, false, true)
-			}
-			if strings.TrimSpace(runtime.Role) == "middle" && strings.TrimSpace(runtime.ChainName) != "" {
-				_, _ = h.sendNodeCommand(runtime.NodeID, "DeleteChains", map[string]interface{}{"chain": runtime.ChainName}, false, true)
-			}
+	var cleanupErr error
+	for i := range runtimes {
+		if err := h.releasePeerShareRuntime(&runtimes[i]); err != nil {
+			cleanupErr = errors.Join(cleanupErr, err)
 		}
-		_ = h.repo.MarkPeerShareRuntimeReleased(runtime.ID, now)
 	}
+	return cleanupErr
 }
 
 func (h *Handler) cleanupFederationTunnels(shareID int64) {

go-backend/internal/http/handler/federation_consumer_cleanup_test.go

@@ -0,0 +1,275 @@
+package handler
+
+import (
+	"bytes"
+	"database/sql"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"strings"
+	"sync/atomic"
+	"testing"
+
+	"go-backend/internal/http/response"
+	"go-backend/internal/store/model"
+	"go-backend/internal/store/repo"
+	"go-backend/internal/ws"
+)
+
+func consumerCleanupFixture(t *testing.T, remoteURL string) (*repo.Repository, *Handler) {
+	t.Helper()
+	r, err := repo.Open(filepath.Join(t.TempDir(), "consumer-cleanup.db"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = r.Close() })
+	if err := r.DB().Create(&model.Node{ID: 1, Name: "remote", Secret: "remote", ServerIP: "127.0.0.1", Port: "31000-31010", IsRemote: 1, Status: 1, RemoteURL: sql.NullString{String: remoteURL, Valid: true}, RemoteToken: sql.NullString{String: "token", Valid: true}}).Error; err != nil {
+		t.Fatal(err)
+	}
+	if err := r.UpsertFederationTunnelBinding(&repo.FederationTunnelBinding{TunnelID: 42, NodeID: 1, ChainType: 3, RemoteURL: remoteURL, ResourceKey: "tunnel:42:node:1:type:3:hop:0", RemoteBindingID: "binding-old", AllocatedPort: 31001, Status: 1}); err != nil {
+		t.Fatal(err)
+	}
+	if err := r.DB().Create(&model.Tunnel{ID: 42, Name: "live tunnel", Type: 2, Protocol: "tls", Flow: 1, TrafficRatio: 1, Status: 1}).Error; err != nil {
+		t.Fatal(err)
+	}
+	return r, &Handler{repo: r, wsServer: ws.NewServer(r, "consumer-cleanup")}
+}
+
+func TestTunnelUpdateValidationPreservesSharedRuntime(t *testing.T) {
+	for _, body := range []string{
+		`{"id":42,"type":2,"name":"invalid update","inNodeId":[]}`,
+		`{"id":42,"type":2,"name":"invalid update","inNodeId":[{"nodeId":999}],"outNodeId":[{"nodeId":1,"port":31001}]}`,
+	} {
+		t.Run(body, func(t *testing.T) {
+			var releases atomic.Int64
+			remote := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
+				releases.Add(1)
+				response.WriteJSON(w, response.OKEmpty())
+			}))
+			defer remote.Close()
+			r, h := consumerCleanupFixture(t, remote.URL)
+			req := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/update", bytes.NewBufferString(body))
+			rec := httptest.NewRecorder()
+			h.tunnelUpdate(rec, req)
+			var payload response.R
+			if err := json.Unmarshal(rec.Body.Bytes(), &payload); err != nil {
+				t.Fatal(err)
+			}
+			bindings, err := r.ListActiveFederationTunnelBindingsByTunnel(42)
+			if err != nil {
+				t.Fatal(err)
+			}
+			name, err := r.GetTunnelName(42)
+			if err != nil {
+				t.Fatal(err)
+			}
+			if payload.Code == 0 || releases.Load() != 0 || len(bindings) != 1 || name != "live tunnel" {
+				t.Fatalf("invalid update changed runtime: code=%d releases=%d bindings=%v name=%s", payload.Code, releases.Load(), bindings, name)
+			}
+		})
+	}
+}
+
+func TestFederationCleanupRetainsFailedBindingAndRetriesOnlyPending(t *testing.T) {
+	var unavailable atomic.Bool
+	unavailable.Store(true)
+	var releases atomic.Int64
+	remote := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
+		releases.Add(1)
+		if unavailable.Load() {
+			http.Error(w, "peer unavailable", http.StatusServiceUnavailable)
+			return
+		}
+		response.WriteJSON(w, response.OKEmpty())
+	}))
+	defer remote.Close()
+	r, h := consumerCleanupFixture(t, remote.URL)
+	if err := r.UpsertFederationTunnelBinding(&repo.FederationTunnelBinding{TunnelID: 43, NodeID: 1, ChainType: 3, RemoteURL: remote.URL, RemoteBindingID: "unrelated", ResourceKey: "unrelated", Status: 1}); err != nil {
+		t.Fatal(err)
+	}
+	if err := h.cleanupFederationRuntime(42); err == nil {
+		t.Fatal("expected release failure")
+	}
+	pending, err := r.ListPendingFederationTunnelBindings()
+	if err != nil || len(pending) != 1 {
+		t.Fatalf("lost pending cleanup: %v %v", pending, err)
+	}
+	if err := h.cleanupFederationRuntime(42); err == nil {
+		t.Fatal("expected second release failure")
+	}
+	if releases.Load() != 2 {
+		t.Fatalf("cleanup was not retried: %d", releases.Load())
+	}
+	unavailable.Store(false)
+	if err := h.retryPendingFederationRuntimeCleanup(); err != nil {
+		t.Fatal(err)
+	}
+	pending, err = r.ListPendingFederationTunnelBindings()
+	if err != nil || len(pending) != 0 {
+		t.Fatalf("completed cleanup remains: %v %v", pending, err)
+	}
+	active, err := r.ListActiveFederationTunnelBindingsByTunnel(43)
+	if err != nil || len(active) != 1 || releases.Load() != 3 {
+		t.Fatalf("retry touched active binding: %v %v calls=%d", active, err, releases.Load())
+	}
+}
+
+func TestTunnelDeleteReportsRemoteFailureAndKeepsTunnel(t *testing.T) {
+	remote := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
+		http.Error(w, "peer unavailable", http.StatusServiceUnavailable)
+	}))
+	defer remote.Close()
+	r, h := consumerCleanupFixture(t, remote.URL)
+	rec := httptest.NewRecorder()
+	h.tunnelDelete(rec, httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/delete", strings.NewReader(`{"id":42}`)))
+	var payload response.R
+	if err := json.Unmarshal(rec.Body.Bytes(), &payload); err != nil {
+		t.Fatal(err)
+	}
+	if payload.Code == 0 {
+		t.Fatal("delete reported success before peer cleanup")
+	}
+	if name, err := r.GetTunnelName(42); err != nil || name != "live tunnel" {
+		t.Fatalf("lost tunnel: %s %v", name, err)
+	}
+	pending, err := r.ListPendingFederationTunnelBindings()
+	if err != nil || len(pending) != 1 {
+		t.Fatalf("lost binding: %v %v", pending, err)
+	}
+}
+
+func TestFederationRollbackReleaseIsDurableAndRetryable(t *testing.T) {
+	var unavailable atomic.Bool
+	unavailable.Store(true)
+	remote := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
+		if unavailable.Load() {
+			http.Error(w, "peer unavailable", http.StatusServiceUnavailable)
+			return
+		}
+		response.WriteJSON(w, response.OKEmpty())
+	}))
+	defer remote.Close()
+	r, h := consumerCleanupFixture(t, remote.URL)
+	refs := []federationRuntimeReleaseRef{{RemoteURL: remote.URL, RemoteToken: "token", BindingID: "new-binding", ReservationID: "new-reservation", ResourceKey: "new-key"}}
+	if err := h.releaseFederationRuntimeRefs(refs); err == nil {
+		t.Fatal("expected release error")
+	}
+	if err := h.releaseFederationRuntimeRefs(refs); err == nil {
+		t.Fatal("expected repeat error")
+	}
+	pending, err := r.ListPendingFederationReleases()
+	if err != nil || len(pending) != 1 {
+		t.Fatalf("rollback queue lost or duplicated release: %v %v", pending, err)
+	}
+	unavailable.Store(false)
+	// A new Handler has no in-memory state from the failed rollback.
+	restarted := &Handler{repo: r}
+	if err := restarted.retryPendingFederationRuntimeCleanup(); err != nil {
+		t.Fatal(err)
+	}
+	pending, err = r.ListPendingFederationReleases()
+	if err != nil || len(pending) != 0 {
+		t.Fatalf("completed rollback remains queued: %v %v", pending, err)
+	}
+	active, err := r.ListActiveFederationTunnelBindingsByTunnel(42)
+	if err != nil || len(active) != 1 {
+		t.Fatalf("rollback retry removed active binding: %v %v", active, err)
+	}
+}
+
+func TestFederationApplyFailureReturnsReservationForRollback(t *testing.T) {
+	remote := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
+		if strings.HasSuffix(req.URL.Path, "reserve-port") {
+			response.WriteJSON(w, response.OK(map[string]interface{}{"reservationId": "reserved", "bindingId": "binding", "allocatedPort": 31001}))
+			return
+		}
+		http.Error(w, "apply failed", http.StatusServiceUnavailable)
+	}))
+	defer remote.Close()
+	_, h := consumerCleanupFixture(t, remote.URL)
+	state := &tunnelCreateState{TunnelID: 43, Type: 2, OutNodes: []tunnelRuntimeNode{{NodeID: 1, Port: 31001}}, Nodes: map[int64]*nodeRecord{1: {ID: 1, Name: "remote", IsRemote: 1, RemoteURL: remote.URL, RemoteToken: "token"}}}
+	_, refs, err := h.applyFederationRuntime(state, "")
+	if err == nil || len(refs) != 1 || refs[0].ReservationID != "reserved" {
+		t.Fatalf("failed apply lost reservation: refs=%+v err=%v", refs, err)
+	}
+}
+
+func TestTunnelUpdateDatabaseValidationPreservesSharedRuntime(t *testing.T) {
+	var releases atomic.Int64
+	remote := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
+		releases.Add(1)
+		response.WriteJSON(w, response.OKEmpty())
+	}))
+	defer remote.Close()
+	r, h := consumerCleanupFixture(t, remote.URL)
+	if err := r.DB().Create(&model.Node{ID: 2, Name: "entry", Secret: "entry", ServerIP: "127.0.0.2", Port: "31000-31010", Status: 1}).Error; err != nil {
+		t.Fatal(err)
+	}
+	if err := r.DB().Exec(`CREATE TRIGGER reject_tunnel_update BEFORE UPDATE ON tunnel BEGIN SELECT RAISE(ABORT, 'test constraint rejected'); END`).Error; err != nil {
+		t.Fatal(err)
+	}
+	rec := httptest.NewRecorder()
+	h.tunnelUpdate(rec, httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/update", strings.NewReader(`{"id":42,"type":2,"name":"new name","inNodeId":[{"nodeId":2}],"outNodeId":[{"nodeId":1,"port":31001}]}`)))
+	var payload response.R
+	if err := json.Unmarshal(rec.Body.Bytes(), &payload); err != nil {
+		t.Fatal(err)
+	}
+	active, err := r.ListActiveFederationTunnelBindingsByTunnel(42)
+	if err != nil || payload.Code == 0 || !strings.Contains(payload.Msg, "test constraint rejected") || releases.Load() != 0 || len(active) != 1 {
+		t.Fatalf("DB validation touched runtime: payload=%+v bindings=%v calls=%d err=%v", payload, active, releases.Load(), err)
+	}
+}
+
+func TestTunnelUpdateRemoteReleaseFailurePreservesMetadata(t *testing.T) {
+	var requests atomic.Int64
+	remote := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
+		requests.Add(1)
+		http.Error(w, "peer unavailable", http.StatusServiceUnavailable)
+	}))
+	defer remote.Close()
+	r, h := consumerCleanupFixture(t, remote.URL)
+	if err := r.DB().Create(&model.Node{ID: 2, Name: "entry", Secret: "entry", ServerIP: "127.0.0.2", Port: "31000-31010", Status: 1}).Error; err != nil {
+		t.Fatal(err)
+	}
+	rec := httptest.NewRecorder()
+	h.tunnelUpdate(rec, httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/update", strings.NewReader(`{"id":42,"type":2,"name":"new name","inNodeId":[{"nodeId":2}],"outNodeId":[{"nodeId":1,"port":31001}]}`)))
+	var payload response.R
+	if err := json.Unmarshal(rec.Body.Bytes(), &payload); err != nil {
+		t.Fatal(err)
+	}
+	name, err := r.GetTunnelName(42)
+	pending, pendingErr := r.ListPendingFederationTunnelBindings()
+	if err != nil || pendingErr != nil || payload.Code == 0 || name != "live tunnel" || requests.Load() != 1 || len(pending) != 1 {
+		t.Fatalf("failed cleanup continued update: payload=%+v name=%s calls=%d pending=%v err=%v/%v", payload, name, requests.Load(), pending, err, pendingErr)
+	}
+}
+
+func TestTunnelUpdateChainWriteValidationPreservesSharedRuntime(t *testing.T) {
+	var calls atomic.Int64
+	remote := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
+		calls.Add(1)
+		response.WriteJSON(w, response.OKEmpty())
+	}))
+	defer remote.Close()
+	r, h := consumerCleanupFixture(t, remote.URL)
+	if err := r.DB().Create(&model.Node{ID: 2, Name: "entry", Secret: "entry", ServerIP: "127.0.0.2", Port: "31000-31010", Status: 1}).Error; err != nil {
+		t.Fatal(err)
+	}
+	if err := r.DB().Exec(`CREATE TRIGGER reject_chain_insert BEFORE INSERT ON chain_tunnel BEGIN SELECT RAISE(ABORT, 'chain write rejected'); END`).Error; err != nil {
+		t.Fatal(err)
+	}
+	rec := httptest.NewRecorder()
+	h.tunnelUpdate(rec, httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/update", strings.NewReader(`{"id":42,"type":2,"name":"new name","inNodeId":[{"nodeId":2}],"outNodeId":[{"nodeId":1,"port":31001}]}`)))
+	var payload response.R
+	if err := json.Unmarshal(rec.Body.Bytes(), &payload); err != nil {
+		t.Fatal(err)
+	}
+	active, err := r.ListActiveFederationTunnelBindingsByTunnel(42)
+	if err != nil || payload.Code == 0 || !strings.Contains(payload.Msg, "chain write rejected") || calls.Load() != 0 || len(active) != 1 {
+		t.Fatalf("chain validation touched runtime: payload=%+v active=%v calls=%d err=%v", payload, active, calls.Load(), err)
+	}
+	if name, err := r.GetTunnelName(42); err != nil || name != "live tunnel" {
+		t.Fatalf("preflight metadata update was committed: %s %v", name, err)
+	}
+}

go-backend/internal/http/handler/federation_resources.go

@@ -0,0 +1,703 @@
+package handler
+
+import (
+	"encoding/base64"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"sort"
+	"strconv"
+	"strings"
+	"time"
+
+	"go-backend/internal/store/repo"
+	"go-backend/internal/ws"
+)
+
+const peerShareResourcePrefix = "peer-share-"
+
+func peerShareResourceName(shareID int64, kind, original string) string {
+	return fmt.Sprintf("%s%d-%s-%s", peerShareResourcePrefix, shareID, kind, base64.RawURLEncoding.EncodeToString([]byte(original)))
+}
+
+func parsePeerShareServiceName(name string) (shareID int64, originalName string, ok bool) {
+	if !strings.HasPrefix(name, peerShareResourcePrefix) {
+		return
+	}
+	parts := strings.SplitN(strings.TrimPrefix(name, peerShareResourcePrefix), "-", 3)
+	if len(parts) != 3 || parts[1] != "service" {
+		return
+	}
+	shareID, err := strconv.ParseInt(parts[0], 10, 64)
+	if err != nil || shareID <= 0 {
+		return 0, "", false
+	}
+	decoded, err := base64.RawURLEncoding.DecodeString(parts[2])
+	if err != nil || len(decoded) == 0 {
+		return 0, "", false
+	}
+	return shareID, string(decoded), true
+}
+
+func federationResourceCommandKind(cmd string) (kind, action string) {
+	lower := strings.ToLower(cmd)
+	for _, entry := range []struct{ suffix, kind string }{{"service", "service"}, {"chains", "chain"}, {"climiters", "climiter"}, {"limiters", "limiter"}} {
+		if strings.HasSuffix(lower, entry.suffix) {
+			return entry.kind, strings.TrimSuffix(lower, entry.suffix)
+		}
+	}
+	return "", ""
+}
+
+// Every peer-supplied reference is resolved within the same share namespace.
+// Composite traffic limiters use a comma-separated list in GOST.
+func scopePeerResourceReferences(value interface{}, shareID int64) {
+	switch v := value.(type) {
+	case map[string]interface{}:
+		for key, child := range v {
+			if strings.EqualFold(key, "chains") {
+				if names, ok := child.([]interface{}); ok {
+					for i, name := range names {
+						if raw, ok := name.(string); ok {
+							names[i] = peerShareResourceName(shareID, "chain", raw)
+						}
+					}
+					continue
+				}
+			}
+			kind := ""
+			switch strings.ToLower(key) {
+			case "chain":
+				kind = "chain"
+			case "limiter":
+				kind = "limiter"
+			case "climiter":
+				kind = "climiter"
+			}
+			if raw, ok := child.(string); ok && kind != "" && strings.TrimSpace(raw) != "" {
+				names := strings.Split(raw, ",")
+				for i, name := range names {
+					names[i] = peerShareResourceName(shareID, kind, strings.TrimSpace(name))
+				}
+				v[key] = strings.Join(names, ",")
+			} else {
+				scopePeerResourceReferences(child, shareID)
+			}
+		}
+	case []interface{}:
+		for _, child := range v {
+			scopePeerResourceReferences(child, shareID)
+		}
+	}
+}
+
+func peerResourceDeletePayload(item repo.PeerShareResource) interface{} {
+	if item.Kind == "service" {
+		return map[string]interface{}{"services": []string{item.RuntimeName}}
+	}
+	key := item.Kind
+	if key == "climiter" {
+		key = "limiter"
+	}
+	return map[string]interface{}{key: item.RuntimeName}
+}
+func peerResourceDeleteCommand(kind string) string {
+	switch kind {
+	case "service":
+		return "DeleteService"
+	case "chain":
+		return "DeleteChains"
+	case "climiter":
+		return "DeleteCLimiters"
+	default:
+		return "DeleteLimiters"
+	}
+}
+
+// preparePeerResourceCommand validates and writes desired state before the node
+// sees any command, closing the flow-report race even without a reservation.
+func (h *Handler) preparePeerResourceCommand(share *repo.PeerShare, cmd string, data interface{}) ([]repo.PeerShareResource, error) {
+	kind, action := federationResourceCommandKind(cmd)
+	if kind == "" {
+		return nil, fmt.Errorf("command not allowed")
+	}
+	raw, err := json.Marshal(data)
+	if err != nil {
+		return nil, err
+	}
+	var decoded interface{}
+	if err = json.Unmarshal(raw, &decoded); err != nil {
+		return nil, err
+	}
+	var configs []map[string]interface{}
+	var names []string
+	setting := action == "add" || action == "update"
+	if setting {
+		if kind == "service" {
+			configs = extractFederationServiceEntries(decoded)
+		} else if m, ok := decoded.(map[string]interface{}); ok {
+			if nested, ok := m["data"].(map[string]interface{}); ok {
+				configs = []map[string]interface{}{nested}
+			} else {
+				configs = []map[string]interface{}{m}
+			}
+		}
+		if len(configs) == 0 {
+			return nil, fmt.Errorf("resource configuration is required")
+		}
+		for _, c := range configs {
+			names = append(names, strings.TrimSpace(asString(c["name"])))
+		}
+	} else {
+		if kind == "service" {
+			if m, ok := decoded.(map[string]interface{}); ok {
+				for _, v := range asAnySlice(m["services"]) {
+					names = append(names, strings.TrimSpace(asString(v)))
+				}
+			}
+		} else {
+			if s, ok := decoded.(string); ok {
+				names = []string{strings.TrimSpace(s)}
+			} else if m, ok := decoded.(map[string]interface{}); ok {
+				key := kind
+				if key == "climiter" {
+					key = "limiter"
+				}
+				names = []string{strings.TrimSpace(asString(m[key]))}
+			}
+		}
+		if len(names) == 0 {
+			return nil, fmt.Errorf("resource name is required")
+		}
+	}
+	requestedNames := make(map[string]bool, len(names))
+	for _, name := range names {
+		requestedNames[name] = true
+	}
+	items := make([]repo.PeerShareResource, 0, len(names))
+	seen := map[string]bool{}
+	for i, name := range names {
+		if name == "" || strings.HasPrefix(name, peerShareResourcePrefix) {
+			return nil, fmt.Errorf("invalid peer resource name")
+		}
+		if seen[name] {
+			return nil, fmt.Errorf("duplicate resource name")
+		}
+		seen[name] = true
+		old, err := h.repo.GetPeerShareResource(share.ID, kind, name)
+		if err != nil {
+			return nil, err
+		}
+		item := repo.PeerShareResource{ShareID: share.ID, NodeID: share.NodeID, Kind: kind, OriginalName: name, RuntimeName: peerShareResourceName(share.ID, kind, name), DesiredState: "active", UpdatedTime: time.Now().UnixMilli()}
+		if old != nil {
+			item = *old
+			item.Applied = 0
+			item.UpdatedTime = time.Now().UnixMilli()
+		}
+		if setting {
+			if old == nil && kind == "service" {
+				legacy, err := h.peerShareLegacyServiceNames(share, name)
+				if err != nil {
+					return nil, err
+				}
+				if len(legacy) > 0 {
+					encoded, _ := json.Marshal(legacy)
+					item.LegacyNames = string(encoded)
+					item.LegacyServiceBase = normalizeForwardRuntimeServiceName(name)
+				}
+			}
+			config := configs[i]
+			if err := validatePeerResourceReferences(config, kind); err != nil {
+				return nil, err
+			}
+			scopePeerResourceReferences(config, share.ID)
+			config["name"] = item.RuntimeName
+			encoded, err := json.Marshal(config)
+			if err != nil {
+				return nil, err
+			}
+			item.Config = string(encoded)
+			item.DesiredState = "active"
+			item.ReleaseLegacyFamily = false
+		} else {
+			if old == nil {
+				// Delete callers send candidate base/TCP/UDP names. Missing names
+				// are safe no-ops; never forward a raw legacy name to the node.
+				if action == "delete" {
+					if kind != "service" {
+						continue
+					}
+					legacy, err := h.peerShareLegacyServiceNames(share, name)
+					if err != nil {
+						return nil, err
+					}
+					if len(legacy) == 0 {
+						continue
+					}
+					encoded, _ := json.Marshal(legacy)
+					item.LegacyNames = string(encoded)
+					item.LegacyServiceBase = normalizeForwardRuntimeServiceName(name)
+				} else {
+					return nil, fmt.Errorf("service %q not found", name)
+				}
+			}
+			if old != nil && old.DesiredState == "deleted" && action != "delete" {
+				return nil, fmt.Errorf("service %q not found", name)
+			}
+			switch action {
+			case "delete":
+				item.DesiredState = "deleted"
+				base := normalizeForwardRuntimeServiceName(name)
+				if requestedNames[base] && requestedNames[base+"_tcp"] && requestedNames[base+"_udp"] {
+					item.ReleaseLegacyFamily = true
+				}
+			case "pause":
+				item.DesiredState = "paused"
+			case "resume":
+				if item.Config == "" {
+					return nil, fmt.Errorf("resource has no saved configuration")
+				}
+				item.DesiredState = "active"
+			default:
+				return nil, fmt.Errorf("command not allowed")
+			}
+		}
+		items = append(items, item)
+	}
+	// Ownership and desired config commit atomically. A failed resource write
+	// must not rename a legacy binding and expose its remaining transports.
+	err = h.repo.WithPeerShareResourceTransaction(func(tx *repo.Repository) error {
+		if setting && kind == "service" {
+			scoped := make([]interface{}, 0, len(items))
+			for _, item := range items {
+				var c map[string]interface{}
+				_ = json.Unmarshal([]byte(item.Config), &c)
+				scoped = append(scoped, c)
+			}
+			binder := &Handler{repo: tx}
+			if err := binder.bindPeerShareForwardRuntimeServices(share, scoped); err != nil {
+				return err
+			}
+		}
+		return tx.SavePeerShareResources(items)
+	})
+	if err != nil {
+		return nil, err
+	}
+	return items, nil
+}
+
+func (h *Handler) applyPeerShareResource(item repo.PeerShareResource) (ws.CommandResult, error) {
+	var result ws.CommandResult
+	var err error
+	if item.LegacyNames != "" {
+		var names []string
+		if err := json.Unmarshal([]byte(item.LegacyNames), &names); err != nil {
+			return result, err
+		}
+		share, loadErr := h.repo.GetPeerShare(item.ShareID)
+		if loadErr != nil {
+			return result, loadErr
+		}
+		if share == nil {
+			return result, fmt.Errorf("legacy resource ownership missing")
+		}
+		for _, name := range names {
+			owned, checkErr := h.peerShareLegacyServiceNames(share, name)
+			if checkErr != nil {
+				return result, checkErr
+			}
+			if len(owned) == 0 {
+				return result, fmt.Errorf("legacy resource ownership missing")
+			}
+		}
+		if _, err = h.sendNodeCommand(item.NodeID, "DeleteService", map[string]interface{}{"services": names}, false, true); err != nil {
+			return result, err
+		}
+		if err = h.repo.ClearPeerShareResourceLegacyNames(item.ShareID, item.Kind, item.OriginalName); err != nil {
+			return result, err
+		}
+	}
+	if item.DesiredState == "deleted" || item.DesiredState == "paused" {
+		// The provider retains the paused configuration durably. Keep the
+		// listener absent on reconnect instead of briefly starting it before
+		// sending a second pause command. Resume reapplies the saved config.
+		result, err = h.sendNodeCommand(item.NodeID, peerResourceDeleteCommand(item.Kind), peerResourceDeletePayload(item), false, true)
+	} else {
+		var config map[string]interface{}
+		if err = json.Unmarshal([]byte(item.Config), &config); err != nil {
+			return result, err
+		}
+		if item.Kind == "service" {
+			result, err = h.sendNodeCommand(item.NodeID, "UpdateService", []interface{}{config}, false, false)
+		} else {
+			suffix := "Limiters"
+			key := "limiter"
+			if item.Kind == "chain" {
+				suffix = "Chains"
+				key = "chain"
+			}
+			if item.Kind == "climiter" {
+				suffix = "CLimiters"
+			}
+			result, err = h.sendNodeCommand(item.NodeID, "Add"+suffix, config, false, false)
+			if err != nil && isAlreadyExistsMessage(err.Error()) {
+				result, err = h.sendNodeCommand(item.NodeID, "Update"+suffix, map[string]interface{}{key: item.RuntimeName, "data": config}, false, false)
+			}
+		}
+	}
+	if err != nil {
+		return result, err
+	}
+	if item.Kind == "service" && item.DesiredState == "deleted" {
+		// TCP and UDP may share one reservation. Release only after all variants
+		// have an acknowledged tombstone.
+		items, listErr := h.repo.ListPeerShareResourcesByNode(item.NodeID)
+		if listErr != nil {
+			return result, listErr
+		}
+		base := normalizeForwardRuntimeServiceName(item.OriginalName)
+		for _, other := range items {
+			if other.ShareID == item.ShareID && other.Kind == "service" && other.OriginalName != item.OriginalName && normalizeForwardRuntimeServiceName(other.OriginalName) == base && (other.DesiredState != "deleted" || other.Applied == 0) {
+				return result, h.repo.MarkPeerShareResourceApplied(item.ShareID, item.Kind, item.OriginalName)
+			}
+		}
+		legacyBase := item.LegacyServiceBase
+		if legacyBase == "" {
+			for _, other := range items {
+				if other.ShareID == item.ShareID && normalizeForwardRuntimeServiceName(other.OriginalName) == base && other.LegacyServiceBase != "" {
+					legacyBase = other.LegacyServiceBase
+					break
+				}
+			}
+		}
+		if legacyBase != "" && item.ReleaseLegacyFamily {
+			share, loadErr := h.repo.GetPeerShare(item.ShareID)
+			if loadErr != nil {
+				return result, loadErr
+			}
+			if share == nil {
+				return result, fmt.Errorf("share ownership missing")
+			}
+			if _, checkErr := h.peerShareLegacyServiceNames(share, legacyBase); checkErr != nil {
+				return result, checkErr
+			}
+			if _, deleteErr := h.sendNodeCommand(item.NodeID, "DeleteService", map[string]interface{}{"services": buildForwardServiceDeleteNames([]string{legacyBase})}, false, true); deleteErr != nil {
+				return result, deleteErr
+			}
+		}
+		if legacyBase != "" && !item.ReleaseLegacyFamily {
+			return result, h.repo.MarkPeerShareResourceApplied(item.ShareID, item.Kind, item.OriginalName)
+		}
+		runtimes, listErr := h.repo.ListActivePeerShareRuntimesByShareID(item.ShareID)
+		if listErr != nil {
+			return result, listErr
+		}
+		return result, h.repo.WithPeerShareResourceTransaction(func(tx *repo.Repository) error {
+			for _, runtime := range runtimes {
+				sid, original, scoped := parsePeerShareServiceName(runtime.ServiceName)
+				ownedScoped := scoped && sid == item.ShareID && normalizeForwardRuntimeServiceName(original) == base
+				ownedLegacy := !scoped && runtime.Role == "forward" && item.ReleaseLegacyFamily && legacyBase != "" && normalizeForwardRuntimeServiceName(runtime.ServiceName) == legacyBase
+				if ownedScoped || ownedLegacy {
+					if err = tx.CompletePeerShareRuntimeRelease(runtime.ID); err != nil {
+						return err
+					}
+				}
+			}
+			if legacyBase != "" && item.ReleaseLegacyFamily {
+				if err := tx.ClearPeerShareResourceLegacyFamily(item.ShareID, legacyBase); err != nil {
+					return err
+				}
+			}
+			return tx.MarkPeerShareResourceApplied(item.ShareID, item.Kind, item.OriginalName)
+		})
+	}
+	return result, h.repo.MarkPeerShareResourceApplied(item.ShareID, item.Kind, item.OriginalName)
+}
+
+func orderPeerShareResources(items []repo.PeerShareResource) {
+	rank := func(item repo.PeerShareResource) int {
+		if item.DesiredState == "deleted" {
+			if item.Kind == "service" {
+				return 0
+			}
+			return 1
+		}
+		if item.Kind == "service" {
+			return 4
+		}
+		if item.Kind == "chain" {
+			return 3
+		}
+		return 2
+	}
+	sort.SliceStable(items, func(i, j int) bool { return rank(items[i]) < rank(items[j]) })
+}
+
+func (h *Handler) reconcilePeerShareResourcesOnNode(nodeID int64) error {
+	return h.reconcilePeerShareResources(nodeID, false)
+}
+func (h *Handler) retryPendingPeerShareResourcesOnNode(nodeID int64) error {
+	return h.reconcilePeerShareResources(nodeID, true)
+}
+func (h *Handler) reconcilePeerShareResources(nodeID int64, pendingOnly bool) error {
+	h.peerResourceMu.Lock()
+	defer h.peerResourceMu.Unlock()
+	items, err := h.repo.ListPeerShareResourcesByNode(nodeID)
+	if err != nil {
+		return err
+	}
+	runtimes, err := h.repo.ListActivePeerShareRuntimesByNode(nodeID)
+	if err != nil {
+		return err
+	}
+	pending := map[string]bool{}
+	for _, runtime := range runtimes {
+		if runtime.ReleasePending != 0 {
+			sid, name, ok := parsePeerShareServiceName(runtime.ServiceName)
+			if ok {
+				pending[fmt.Sprintf("%d:%s", sid, normalizeForwardRuntimeServiceName(name))] = true
+			}
+		}
+	}
+	groups := map[int64][]repo.PeerShareResource{}
+	var ids []int64
+	for _, item := range items {
+		if _, ok := groups[item.ShareID]; !ok {
+			ids = append(ids, item.ShareID)
+		}
+		groups[item.ShareID] = append(groups[item.ShareID], item)
+	}
+	var failures []error
+	for _, shareID := range ids {
+		share, err := h.repo.GetPeerShare(shareID)
+		if err != nil {
+			failures = append(failures, err)
+			continue
+		}
+		expired := share == nil || share.IsActive != 1 || (share.ExpiryTime > 0 && share.ExpiryTime <= time.Now().UnixMilli()) || isPeerShareFlowExceeded(share)
+		group := groups[shareID]
+		var changed []repo.PeerShareResource
+		for i := range group {
+			item := &group[i]
+			if (expired || (item.Kind == "service" && pending[fmt.Sprintf("%d:%s", item.ShareID, normalizeForwardRuntimeServiceName(item.OriginalName))])) && (item.DesiredState != "deleted" || item.Applied == 0 || item.LegacyServiceBase != "") {
+				item.DesiredState = "deleted"
+				item.ReleaseLegacyFamily = true
+				item.Applied = 0
+				changed = append(changed, *item)
+			}
+		}
+		if err := h.repo.SavePeerShareResources(changed); err != nil {
+			failures = append(failures, err)
+			continue
+		}
+		orderPeerShareResources(group)
+		dependencyFailed := false
+		deletionFailed := false
+		for _, item := range group {
+			if item.Applied == 1 && (pendingOnly || item.DesiredState == "deleted") {
+				continue
+			}
+			if dependencyFailed && item.Kind == "service" && item.DesiredState != "deleted" {
+				continue
+			}
+			if deletionFailed && item.Kind != "service" && item.DesiredState == "deleted" {
+				continue
+			}
+			if _, err := h.applyPeerShareResource(item); err != nil {
+				failures = append(failures, fmt.Errorf("share %d %s %s: %w", item.ShareID, item.Kind, item.OriginalName, err))
+				if item.Kind != "service" {
+					dependencyFailed = true
+				}
+				if item.DesiredState == "deleted" {
+					deletionFailed = true
+				}
+			}
+		}
+	}
+	return errors.Join(failures...)
+}
+
+func (h *Handler) releasePeerShareResources(shareID int64) error {
+	h.peerResourceMu.Lock()
+	defer h.peerResourceMu.Unlock()
+	share, err := h.repo.GetPeerShare(shareID)
+	if err != nil {
+		return err
+	}
+	if share == nil {
+		return nil
+	}
+	all, err := h.repo.ListPeerShareResourcesByNode(share.NodeID)
+	if err != nil {
+		return err
+	}
+	var items []repo.PeerShareResource
+	for _, item := range all {
+		if item.ShareID == shareID && !(item.DesiredState == "deleted" && item.Applied == 1 && item.LegacyServiceBase == "") {
+			item.DesiredState = "deleted"
+			item.ReleaseLegacyFamily = true
+			item.Applied = 0
+			items = append(items, item)
+		}
+	}
+	if err = h.repo.SavePeerShareResources(items); err != nil {
+		return err
+	}
+	orderPeerShareResources(items)
+	for _, item := range items {
+		if _, err = h.applyPeerShareResource(item); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+// A legacy name is eligible for migration only when its runtime registration
+// proves unique ownership. An identically numbered local forward is ambiguous.
+func (h *Handler) peerShareLegacyServiceNames(share *repo.PeerShare, original string) ([]string, error) {
+	base := normalizeForwardRuntimeServiceName(original)
+	runtimes, err := h.repo.ListActiveForwardPeerShareRuntimesByNodeAndServiceName(share.NodeID, base)
+	if err != nil {
+		return nil, err
+	}
+	owned := false
+	for _, runtime := range runtimes {
+		if runtime.ShareID != share.ID {
+			return nil, fmt.Errorf("legacy resource %q has ambiguous ownership", original)
+		}
+		if runtime.ReleasePending != 0 {
+			return nil, fmt.Errorf("runtime release is pending")
+		}
+		owned = true
+	}
+	if !owned {
+		resources, err := h.repo.ListPeerShareResourcesByNode(share.NodeID)
+		if err != nil {
+			return nil, err
+		}
+		for _, resource := range resources {
+			if resource.ShareID == share.ID && resource.LegacyServiceBase == base {
+				owned = true
+				break
+			}
+		}
+	}
+	if !owned {
+		return nil, nil
+	}
+	if id, _, _, ok := parseFlowServiceIDs(base); ok {
+		local, err := h.repo.GetForwardRecord(id)
+		if err != nil {
+			return nil, err
+		}
+		if local != nil {
+			return nil, fmt.Errorf("legacy resource %q collides with a local forward", original)
+		}
+	}
+	// Only delete the requested transport. Other variants remain registered to
+	// their legacy runtime until they are independently migrated.
+	return []string{original}, nil
+}
+
+// releasePeerShareForwardRuntimeResources removes exact persisted transport
+// names belonging to a single forward reservation, retaining failed tombstones.
+func (h *Handler) releasePeerShareForwardRuntimeResources(runtime *repo.PeerShareRuntime) error {
+	h.peerResourceMu.Lock()
+	defer h.peerResourceMu.Unlock()
+	shareID, original, ok := parsePeerShareServiceName(runtime.ServiceName)
+	if !ok || shareID != runtime.ShareID {
+		return fmt.Errorf("runtime is not a scoped shared forward")
+	}
+	all, err := h.repo.ListPeerShareResourcesByNode(runtime.NodeID)
+	if err != nil {
+		return err
+	}
+	var items []repo.PeerShareResource
+	for _, item := range all {
+		if item.ShareID == runtime.ShareID && item.Kind == "service" && normalizeForwardRuntimeServiceName(item.OriginalName) == normalizeForwardRuntimeServiceName(original) {
+			item.DesiredState = "deleted"
+			item.ReleaseLegacyFamily = true
+			item.Applied = 0
+			items = append(items, item)
+		}
+	}
+	if len(items) == 0 {
+		return fmt.Errorf("shared forward resource ownership is missing")
+	}
+	if err = h.repo.SavePeerShareResources(items); err != nil {
+		return err
+	}
+	for _, item := range items {
+		if _, err = h.applyPeerShareResource(item); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+// Registry kinds without an owned command API cannot be referenced by peers.
+func validatePeerResourceReferences(value interface{}, kind string) error {
+	var walk func(interface{}) error
+	walk = func(value interface{}) error {
+		switch v := value.(type) {
+		case map[string]interface{}:
+			for key, child := range v {
+				switch strings.ToLower(key) {
+				case "auther", "authers", "admission", "admissions", "bypass", "bypasses", "resolver", "hosts", "rlimiter", "logger", "loggers", "observer", "recorders", "hop", "sd":
+					if child != nil {
+						empty := false
+						switch x := child.(type) {
+						case string:
+							empty = strings.TrimSpace(x) == ""
+						case []interface{}:
+							empty = len(x) == 0
+						}
+						if !empty {
+							return fmt.Errorf("unsupported shared registry reference: %s", key)
+						}
+					}
+				case "forwarder":
+					if f, ok := child.(map[string]interface{}); ok {
+						for field, value := range f {
+							if strings.EqualFold(field, "name") && strings.TrimSpace(asString(value)) != "" {
+								return fmt.Errorf("named shared forwarder references are unsupported")
+							}
+						}
+					}
+				case "hops":
+					for _, hop := range asMapSlice(child) {
+						if _, ok := hop["nodes"]; !ok {
+							return fmt.Errorf("shared chains require inline hop nodes")
+						}
+						for _, loader := range []string{"file", "redis", "http", "plugin"} {
+							if hop[loader] != nil {
+								return fmt.Errorf("shared hop loaders are unsupported")
+							}
+						}
+					}
+				}
+				if err := walk(child); err != nil {
+					return err
+				}
+			}
+		case []interface{}:
+			for _, child := range v {
+				if err := walk(child); err != nil {
+					return err
+				}
+			}
+		}
+		return nil
+	}
+	if kind == "limiter" || kind == "climiter" {
+		if config, ok := value.(map[string]interface{}); ok {
+			for _, loader := range []string{"file", "redis", "http", "plugin"} {
+				if config[loader] != nil {
+					return fmt.Errorf("shared limiter loaders are unsupported")
+				}
+			}
+		}
+	}
+	return walk(value)
+}

go-backend/internal/http/handler/federation_resources_test.go

@@ -0,0 +1,540 @@
+package handler
+
+import (
+	"bytes"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"go-backend/internal/http/response"
+	"go-backend/internal/store/repo"
+	"gorm.io/gorm"
+)
+
+func resourceTestShare(t *testing.T, h *Handler, token string) *repo.PeerShare {
+	t.Helper()
+	now := time.Now().UnixMilli()
+	share := &repo.PeerShare{Name: token, NodeID: 1, Token: token, IsActive: 1, PortRangeStart: 31000, PortRangeEnd: 32000, CreatedTime: now, UpdatedTime: now}
+	if err := h.repo.CreatePeerShare(share); err != nil {
+		t.Fatal(err)
+	}
+	return share
+}
+func resourceTestCommand(t *testing.T, h *Handler, share *repo.PeerShare, cmd string, data interface{}) response.R {
+	t.Helper()
+	body, err := json.Marshal(federationRuntimeCommandRequest{CommandType: cmd, Data: data})
+	if err != nil {
+		t.Fatal(err)
+	}
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/federation/runtime/command", bytes.NewReader(body))
+	req.Header.Set("Authorization", "Bearer "+share.Token)
+	rec := httptest.NewRecorder()
+	h.federationRuntimeCommand(rec, req)
+	var result response.R
+	if err = json.Unmarshal(rec.Body.Bytes(), &result); err != nil {
+		t.Fatal(err)
+	}
+	return result
+}
+func resourceTestService(name string, port int) []interface{} {
+	return []interface{}{map[string]interface{}{"name": name, "addr": fmt.Sprintf(":%d", port), "handler": map[string]interface{}{"type": "tcp", "chain": "70"}, "listener": map[string]interface{}{"type": "tcp"}, "limiter": "10,20", "climiter": "30"}}
+}
+
+func TestPeerResourceCommandIsolationAndDurableRestore(t *testing.T) {
+	a := newCleanupAgent(t)
+	first := resourceTestShare(t, a.h, "resource-first")
+	second := resourceTestShare(t, a.h, "resource-second")
+	for i, share := range []*repo.PeerShare{first, second} {
+		for _, entry := range []struct{ cmd, name string }{{"AddLimiters", "10"}, {"AddCLimiters", "30"}, {"AddChains", "70"}} {
+			result := resourceTestCommand(t, a.h, share, entry.cmd, map[string]interface{}{"name": entry.name})
+			if result.Code != 0 {
+				t.Fatal(result.Msg)
+			}
+		}
+		result := resourceTestCommand(t, a.h, share, "AddService", resourceTestService("70_1_0_tcp", 31001+i))
+		if result.Code != 0 {
+			t.Fatal(result.Msg)
+		}
+	}
+	commands := a.commandsOfType("UpdateService")
+	if len(commands) != 2 {
+		t.Fatalf("commands: %+v", commands)
+	}
+	for i, share := range []*repo.PeerShare{first, second} {
+		var configs []map[string]interface{}
+		if err := json.Unmarshal(commands[i].Data, &configs); err != nil {
+			t.Fatal(err)
+		}
+		c := configs[0]
+		if c["name"] != peerShareResourceName(share.ID, "service", "70_1_0_tcp") {
+			t.Fatalf("unscoped service: %v", c)
+		}
+		if c["handler"].(map[string]interface{})["chain"] != peerShareResourceName(share.ID, "chain", "70") {
+			t.Fatalf("unscoped chain: %v", c)
+		}
+		want := peerShareResourceName(share.ID, "limiter", "10") + "," + peerShareResourceName(share.ID, "limiter", "20")
+		if c["limiter"] != want || c["climiter"] != peerShareResourceName(share.ID, "climiter", "30") {
+			t.Fatalf("unscoped limiter: %v", c)
+		}
+	}
+	result := resourceTestCommand(t, a.h, first, "DeleteService", map[string]interface{}{"services": []string{"70_1_0_tcp"}})
+	if result.Code != 0 {
+		t.Fatal(result.Msg)
+	}
+	deleted := a.commandsOfType("DeleteService")
+	if len(deleted) != 1 || !strings.Contains(string(deleted[0].Data), peerShareResourceName(first.ID, "service", "70_1_0_tcp")) {
+		t.Fatalf("wrong deletion: %+v", deleted)
+	}
+	// A new Handler simulates restart with only durable desired state retained.
+	restarted := &Handler{repo: a.h.repo, wsServer: a.h.wsServer}
+	if err := restarted.reconcilePeerShareResourcesOnNode(1); err != nil {
+		t.Fatal(err)
+	}
+	commands = a.commandsOfType("UpdateService")
+	if len(commands) != 3 || !strings.Contains(string(commands[2].Data), peerShareResourceName(second.ID, "service", "70_1_0_tcp")) {
+		t.Fatalf("wrong recovery: %+v", commands)
+	}
+	if got := resourceTestCommand(t, a.h, first, "DeleteService", map[string]interface{}{"services": []string{peerShareResourceName(second.ID, "service", "70_1_0_tcp")}}); got.Code == 0 {
+		t.Fatal("accepted foreign scoped name")
+	}
+	if got := resourceTestCommand(t, a.h, first, "Reload", nil); got.Code == 0 {
+		t.Fatal("accepted global reload")
+	}
+}
+
+func TestPeerResourcePreRegistrationAndDatabaseFailure(t *testing.T) {
+	a := newCleanupAgent(t)
+	share := resourceTestShare(t, a.h, "resource-preregister")
+	items, err := a.h.preparePeerResourceCommand(share, "AddService", resourceTestService("70_1_0_tcp", 31001))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(a.commandsOfType("UpdateService")) != 0 {
+		t.Fatal("prepare sent service before persistence")
+	}
+	stored, err := a.h.repo.GetPeerShareResource(share.ID, "service", "70_1_0_tcp")
+	if err != nil || stored == nil || stored.Applied != 0 {
+		t.Fatalf("missing pending ownership: %+v %v", stored, err)
+	}
+	runCleanupPath(a.h, "single", []string{items[0].RuntimeName})
+	a.probe(t)
+	if len(a.commandsOfType("DeleteService")) != 0 {
+		t.Fatal("flow report removed pending service")
+	}
+	if err := a.h.repo.DB().Callback().Create().Before("gorm:create").Register("fail-resource-registration", func(tx *gorm.DB) {
+		if tx.Statement.Table == "peer_share_resource" {
+			tx.AddError(errors.New("simulated resource write failure"))
+		}
+	}); err != nil {
+		t.Fatal(err)
+	}
+	defer a.h.repo.DB().Callback().Create().Remove("fail-resource-registration")
+	got := resourceTestCommand(t, a.h, share, "AddService", resourceTestService("71_1_0", 31002))
+	if got.Code == 0 {
+		t.Fatal("database failure returned success")
+	}
+	if len(a.commandsOfType("UpdateService")) != 0 {
+		t.Fatal("node received command after persistence failure")
+	}
+}
+
+func TestPeerResourceBindingDatabaseFailure(t *testing.T) {
+	a := newCleanupAgent(t)
+	share := resourceTestShare(t, a.h, "resource-bind-failure")
+	if err := a.h.repo.DB().Callback().Create().Before("gorm:create").Register("fail-runtime-registration", func(tx *gorm.DB) {
+		if tx.Statement.Table == "peer_share_runtime" {
+			tx.AddError(errors.New("simulated binding failure"))
+		}
+	}); err != nil {
+		t.Fatal(err)
+	}
+	defer a.h.repo.DB().Callback().Create().Remove("fail-runtime-registration")
+	got := resourceTestCommand(t, a.h, share, "AddService", resourceTestService("70_1_0", 31001))
+	if got.Code == 0 {
+		t.Fatal("binding failure returned success")
+	}
+	if len(a.commandsOfType("UpdateService")) != 0 {
+		t.Fatal("service sent before successful binding")
+	}
+}
+
+func TestPeerResourceScopedNameRoundTrip(t *testing.T) {
+	for _, name := range []string{"70_1_0", "70_1_0_tcp", "70_1_0_udp", "a-b_c"} {
+		scoped := peerShareResourceName(12, "service", name)
+		id, got, ok := parsePeerShareServiceName(scoped)
+		if !ok || id != 12 || got != name {
+			t.Fatalf("round trip failed: %q", scoped)
+		}
+	}
+}
+
+func TestPeerResourceDeletesCandidateNamesAndPreservesFailedTombstone(t *testing.T) {
+	a := newCleanupAgent(t)
+	share := resourceTestShare(t, a.h, "resource-delete-candidates")
+	got := resourceTestCommand(t, a.h, share, "AddService", resourceTestService("70_1_0_tcp", 31001))
+	if got.Code != 0 {
+		t.Fatal(got.Msg)
+	}
+	got = resourceTestCommand(t, a.h, share, "DeleteService", map[string]interface{}{"services": []string{"70_1_0_tcp", "70_1_0_udp", "70_1_0"}})
+	if got.Code != 0 {
+		t.Fatal(got.Msg)
+	}
+	if len(a.commandsOfType("DeleteService")) != 1 {
+		t.Fatal("unregistered names were sent to the node")
+	}
+	// A disconnected node cannot acknowledge deletion: keep the pending row.
+	if got = resourceTestCommand(t, a.h, share, "AddService", resourceTestService("71_1_0", 31002)); got.Code != 0 {
+		t.Fatal(got.Msg)
+	}
+	offline := &Handler{repo: a.h.repo}
+	got = resourceTestCommand(t, offline, share, "DeleteService", map[string]interface{}{"services": []string{"71_1_0"}})
+	if got.Code == 0 {
+		t.Fatal("offline deletion reported success")
+	}
+	pending, err := a.h.repo.GetPeerShareResource(share.ID, "service", "71_1_0")
+	if err != nil || pending.DesiredState != "deleted" || pending.Applied != 0 {
+		t.Fatalf("lost pending deletion: %+v %v", pending, err)
+	}
+	if err := a.h.reconcilePeerShareResourcesOnNode(1); err != nil {
+		t.Fatal(err)
+	}
+	pending, err = a.h.repo.GetPeerShareResource(share.ID, "service", "71_1_0")
+	if err != nil || pending.Applied != 1 {
+		t.Fatalf("deletion not retried: %+v %v", pending, err)
+	}
+	if got = resourceTestCommand(t, a.h, share, "ResumeService", map[string]interface{}{"services": []string{"71_1_0"}}); got.Code == 0 {
+		t.Fatal("resume resurrected a deleted resource")
+	}
+}
+
+func TestPeerResourceLegacyMigrationRequiresUnambiguousOwner(t *testing.T) {
+	a := newCleanupAgent(t)
+	shareID := a.addRuntime(t, "70_1_0", 1, 1, 1, time.Now())
+	share, err := a.h.repo.GetPeerShare(shareID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	got := resourceTestCommand(t, a.h, share, "AddService", resourceTestService("70_1_0_tcp", 31001))
+	if got.Code != 0 {
+		t.Fatal(got.Msg)
+	}
+	deleted := a.commandsOfType("DeleteService")
+	if len(deleted) != 1 || string(deleted[0].Data) != `{"services":["70_1_0_tcp"]}` {
+		t.Fatalf("legacy deletion was not exact: %+v", deleted)
+	}
+	item, err := a.h.repo.GetPeerShareResource(share.ID, "service", "70_1_0_tcp")
+	if err != nil || item.LegacyNames != "" {
+		t.Fatalf("legacy migration acknowledgment not persisted: %+v %v", item, err)
+	}
+	// Two shares with the same legacy name are never resolved by guessing.
+	other := resourceTestShare(t, a.h, "resource-ambiguous")
+	now := time.Now().UnixMilli()
+	for i, sid := range []int64{share.ID, other.ID} {
+		if err := a.h.repo.CreatePeerShareRuntime(&repo.PeerShareRuntime{ShareID: sid, NodeID: 1, ReservationID: fmt.Sprintf("ambiguous-%d", i), ResourceKey: fmt.Sprintf("ambiguous-%d", i), Role: "forward", ServiceName: "71_1_0", Port: 31003 + i, Applied: 1, Status: 1, CreatedTime: now, UpdatedTime: now}); err != nil {
+			t.Fatal(err)
+		}
+	}
+	got = resourceTestCommand(t, a.h, share, "AddService", resourceTestService("71_1_0_tcp", 31003))
+	if got.Code == 0 {
+		t.Fatal("ambiguous legacy owner accepted")
+	}
+	if len(a.commandsOfType("DeleteService")) != 1 {
+		t.Fatal("ambiguous legacy service deleted")
+	}
+}
+
+func TestPeerResourceLegacyFamilyPersistsAcrossPartialMigration(t *testing.T) {
+	a := newCleanupAgent(t)
+	shareID := a.addRuntime(t, "70_1_0", 1, 1, 1, time.Now())
+	share, err := a.h.repo.GetPeerShare(shareID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := resourceTestCommand(t, a.h, share, "AddService", resourceTestService("70_1_0_tcp", 31001)); got.Code != 0 {
+		t.Fatal(got.Msg)
+	}
+	item, err := a.h.repo.GetPeerShareResource(share.ID, "service", "70_1_0_tcp")
+	if err != nil || item.LegacyServiceBase != "70_1_0" {
+		t.Fatalf("lost legacy family ownership: %+v %v", item, err)
+	}
+	// A later request can still prove ownership of the old UDP transport.
+	if got := resourceTestCommand(t, a.h, share, "AddService", resourceTestService("70_1_0_udp", 31001)); got.Code != 0 {
+		t.Fatal(got.Msg)
+	}
+	deletes := a.commandsOfType("DeleteService")
+	if len(deletes) != 2 || string(deletes[1].Data) != `{"services":["70_1_0_udp"]}` {
+		t.Fatalf("lost UDP migration ownership: %+v", deletes)
+	}
+	if got := resourceTestCommand(t, a.h, share, "DeleteService", map[string]interface{}{"services": []string{"70_1_0_tcp", "70_1_0_udp", "70_1_0"}}); got.Code != 0 {
+		t.Fatal(got.Msg)
+	}
+	item, err = a.h.repo.GetPeerShareResource(share.ID, "service", "70_1_0_tcp")
+	if err != nil || item.LegacyServiceBase != "" {
+		t.Fatalf("legacy family not released: %+v %v", item, err)
+	}
+}
+
+func TestPeerResourceFailedRegistrationDoesNotRenameLegacyRuntime(t *testing.T) {
+	a := newCleanupAgent(t)
+	shareID := a.addRuntime(t, "70_1_0", 1, 1, 1, time.Now())
+	share, err := a.h.repo.GetPeerShare(shareID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := a.h.repo.DB().Callback().Create().Before("gorm:create").Register("fail-atomic-resource", func(tx *gorm.DB) {
+		if tx.Statement.Table == "peer_share_resource" {
+			tx.AddError(errors.New("simulated desired-state failure"))
+		}
+	}); err != nil {
+		t.Fatal(err)
+	}
+	defer a.h.repo.DB().Callback().Create().Remove("fail-atomic-resource")
+	if got := resourceTestCommand(t, a.h, share, "AddService", resourceTestService("70_1_0_tcp", 31001)); got.Code == 0 {
+		t.Fatal("registration failure returned success")
+	}
+	runtimes, err := a.h.repo.ListActivePeerShareRuntimesByShareID(share.ID)
+	if err != nil || len(runtimes) != 1 || runtimes[0].ServiceName != "70_1_0" {
+		t.Fatalf("legacy binding changed after rollback: %+v %v", runtimes, err)
+	}
+	if len(a.commandsOfType("DeleteService"))+len(a.commandsOfType("UpdateService")) != 0 {
+		t.Fatal("node mutated despite transaction rollback")
+	}
+}
+
+func TestPeerResourcePausedReconcileNeverStartsListener(t *testing.T) {
+	a := newCleanupAgent(t)
+	share := resourceTestShare(t, a.h, "resource-pause-recovery")
+	for _, cmd := range []string{"AddService", "PauseService"} {
+		var data interface{} = resourceTestService("70_1_0_tcp", 31001)
+		if cmd == "PauseService" {
+			data = map[string]interface{}{"services": []string{"70_1_0_tcp"}}
+		}
+		if got := resourceTestCommand(t, a.h, share, cmd, data); got.Code != 0 {
+			t.Fatal(got.Msg)
+		}
+	}
+	if err := a.h.reconcilePeerShareResourcesOnNode(1); err != nil {
+		t.Fatal(err)
+	}
+	if len(a.commandsOfType("UpdateService")) != 1 {
+		t.Fatal("paused listener started during reconciliation")
+	}
+	if got := resourceTestCommand(t, a.h, share, "ResumeService", map[string]interface{}{"services": []string{"70_1_0_tcp"}}); got.Code != 0 {
+		t.Fatal(got.Msg)
+	}
+	if len(a.commandsOfType("UpdateService")) != 2 {
+		t.Fatal("resume did not restore saved service")
+	}
+}
+
+func TestPeerResourceDeleteUnmigratedLegacyOwner(t *testing.T) {
+	a := newCleanupAgent(t)
+	shareID := a.addRuntime(t, "70_1_0", 1, 1, 1, time.Now())
+	share, err := a.h.repo.GetPeerShare(shareID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	got := resourceTestCommand(t, a.h, share, "DeleteService", map[string]interface{}{"services": []string{"70_1_0_tcp", "70_1_0_udp", "70_1_0"}})
+	if got.Code != 0 {
+		t.Fatal(got.Msg)
+	}
+	removed := false
+	for _, cmd := range a.commandsOfType("DeleteService") {
+		var body struct {
+			Services []string `json:"services"`
+		}
+		if err = json.Unmarshal(cmd.Data, &body); err != nil {
+			t.Fatal(err)
+		}
+		for _, name := range body.Services {
+			if name == "70_1_0" {
+				removed = true
+			}
+		}
+	}
+	if !removed {
+		t.Fatal("legacy delete reported success without sending old service deletion")
+	}
+}
+
+func TestPeerResourcePartialDeletePreservesLegacyFamily(t *testing.T) {
+	a := newCleanupAgent(t)
+	shareID := a.addRuntime(t, "70_1_0", 1, 1, 1, time.Now())
+	share, err := a.h.repo.GetPeerShare(shareID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := resourceTestCommand(t, a.h, share, "AddService", resourceTestService("70_1_0_tcp", 31001)); got.Code != 0 {
+		t.Fatal(got.Msg)
+	}
+	if got := resourceTestCommand(t, a.h, share, "DeleteService", map[string]interface{}{"services": []string{"70_1_0_tcp"}}); got.Code != 0 {
+		t.Fatal(got.Msg)
+	}
+	item, err := a.h.repo.GetPeerShareResource(share.ID, "service", "70_1_0_tcp")
+	if err != nil || item.LegacyServiceBase != "70_1_0" {
+		t.Fatalf("partial delete lost remaining legacy family: %+v %v", item, err)
+	}
+	for _, cmd := range a.commandsOfType("DeleteService") {
+		if strings.Contains(string(cmd.Data), `"70_1_0_udp"`) {
+			t.Fatal("partial TCP delete removed legacy UDP")
+		}
+	}
+	if err = a.h.releasePeerShareResources(share.ID); err != nil {
+		t.Fatal(err)
+	}
+	item, err = a.h.repo.GetPeerShareResource(share.ID, "service", "70_1_0_tcp")
+	if err != nil || item.LegacyServiceBase != "" {
+		t.Fatalf("full release lost legacy cleanup: %+v %v", item, err)
+	}
+}
+
+func TestPeerResourceChainGroupsAreScopedAndOtherRegistriesRejected(t *testing.T) {
+	a := newCleanupAgent(t)
+	share := resourceTestShare(t, a.h, "resource-chain-groups")
+	data := resourceTestService("70_1_0", 31001)
+	data[0].(map[string]interface{})["handler"].(map[string]interface{})["chainGroup"] = map[string]interface{}{"chains": []string{"one", "two"}}
+	if got := resourceTestCommand(t, a.h, share, "AddService", data); got.Code != 0 {
+		t.Fatal(got.Msg)
+	}
+	body := string(a.commandsOfType("UpdateService")[0].Data)
+	for _, name := range []string{"one", "two"} {
+		if !strings.Contains(body, peerShareResourceName(share.ID, "chain", name)) {
+			t.Fatalf("chainGroup reference was not scoped: %s", body)
+		}
+	}
+	for _, reference := range []string{"resolver", "auther", "observer", "hop"} {
+		data := resourceTestService("71_1_0", 31002)
+		data[0].(map[string]interface{})[reference] = "global-resource"
+		if got := resourceTestCommand(t, a.h, share, "AddService", data); got.Code == 0 {
+			t.Fatalf("accepted global %s reference", reference)
+		}
+	}
+}
+
+func TestPeerResourceReconcileContinuesAfterAnotherShareFails(t *testing.T) {
+	a := newCleanupAgent(t)
+	first := resourceTestShare(t, a.h, "resource-failed-share")
+	second := resourceTestShare(t, a.h, "resource-good-share")
+	for i, share := range []*repo.PeerShare{first, second} {
+		if got := resourceTestCommand(t, a.h, share, "AddService", resourceTestService("70_1_0", 31001+i)); got.Code != 0 {
+			t.Fatal(got.Msg)
+		}
+	}
+	if err := a.h.repo.SavePeerShareResources([]repo.PeerShareResource{{ShareID: first.ID, NodeID: 1, Kind: "limiter", OriginalName: "broken", RuntimeName: peerShareResourceName(first.ID, "limiter", "broken"), Config: "{", DesiredState: "active", UpdatedTime: time.Now().UnixMilli()}}); err != nil {
+		t.Fatal(err)
+	}
+	if err := a.h.reconcilePeerShareResourcesOnNode(1); err == nil {
+		t.Fatal("invalid dependency was not reported")
+	}
+	commands := a.commandsOfType("UpdateService")
+	if len(commands) != 3 || !strings.Contains(string(commands[2].Data), peerShareResourceName(second.ID, "service", "70_1_0")) {
+		t.Fatalf("failed share blocked healthy share, or failed dependency service was started: %+v", commands)
+	}
+}
+
+func TestPeerResourceRechecksShareBeforeRecreation(t *testing.T) {
+	for _, state := range []string{"inactive", "expired", "exceeded"} {
+		t.Run(state, func(t *testing.T) {
+			a := newCleanupAgent(t)
+			share := resourceTestShare(t, a.h, "resource-state-"+state)
+			switch state {
+			case "inactive":
+				share.IsActive = 0
+			case "expired":
+				share.ExpiryTime = time.Now().Add(-time.Hour).UnixMilli()
+			case "exceeded":
+				share.MaxBandwidth = 1
+				share.CurrentFlow = 1 << 40
+			}
+			if err := a.h.repo.UpdatePeerShare(share); err != nil {
+				t.Fatal(err)
+			}
+			if state == "exceeded" {
+				if err := a.h.repo.AddPeerShareCurrentFlow(share.ID, share.CurrentFlow); err != nil {
+					t.Fatal(err)
+				}
+			}
+			if got := resourceTestCommand(t, a.h, share, "AddService", resourceTestService("70_1_0", 31001)); got.Code == 0 {
+				t.Fatal("invalid share recreated resources")
+			}
+			if len(a.commandsOfType("UpdateService")) != 0 {
+				t.Fatal("invalid share reached the node")
+			}
+		})
+	}
+}
+
+func TestPeerResourcePendingRetryLeavesAppliedSiblingAlone(t *testing.T) {
+	a := newCleanupAgent(t)
+	share := resourceTestShare(t, a.h, "resource-pending-only")
+	offline := &Handler{repo: a.h.repo}
+	if got := resourceTestCommand(t, offline, share, "AddService", resourceTestService("70_1_0", 31001)); got.Code == 0 {
+		t.Fatal("offline apply reported success")
+	}
+	if got := resourceTestCommand(t, a.h, share, "AddService", resourceTestService("71_1_0", 31002)); got.Code != 0 {
+		t.Fatal(got.Msg)
+	}
+	if err := a.h.retryPendingPeerShareResourcesOnNode(1); err != nil {
+		t.Fatal(err)
+	}
+	commands := a.commandsOfType("UpdateService")
+	if len(commands) != 2 || !strings.Contains(string(commands[1].Data), peerShareResourceName(share.ID, "service", "70_1_0")) {
+		t.Fatalf("pending retry restarted applied sibling: %+v", commands)
+	}
+	if err := a.h.retryPendingPeerShareResourcesOnNode(1); err != nil {
+		t.Fatal(err)
+	}
+	if len(a.commandsOfType("UpdateService")) != 2 {
+		t.Fatal("no-op pending retry restarted applied services")
+	}
+}
+
+func TestPeerResourceLegacyReleaseAcknowledgmentIsAtomic(t *testing.T) {
+	var failCompletion atomic.Bool
+	a := newCleanupAgent(t, func(r *repo.Repository) {
+		if err := r.DB().Callback().Update().Before("gorm:update").Register("fail-runtime-release", func(tx *gorm.DB) {
+			if failCompletion.Load() && tx.Statement.Table == "peer_share_runtime" {
+				tx.AddError(errors.New("simulated completion failure"))
+			}
+		}); err != nil {
+			t.Fatal(err)
+		}
+	})
+	shareID := a.addRuntime(t, "70_1_0", 1, 1, 1, time.Now())
+	share, err := a.h.repo.GetPeerShare(shareID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	failCompletion.Store(true)
+	got := resourceTestCommand(t, a.h, share, "DeleteService", map[string]interface{}{"services": []string{"70_1_0", "70_1_0_tcp", "70_1_0_udp"}})
+	if got.Code == 0 {
+		t.Fatal("completion database failure reported success")
+	}
+	items, err := a.h.repo.ListPeerShareResourcesByNode(1)
+	if err != nil {
+		t.Fatal(err)
+	}
+	proof := false
+	pending := false
+	for _, item := range items {
+		proof = proof || item.LegacyServiceBase == "70_1_0"
+		pending = pending || item.Applied == 0
+	}
+	if !proof || !pending {
+		t.Fatalf("failure lost ownership or retry marker: %+v", items)
+	}
+	failCompletion.Store(false)
+	if err := a.h.retryPendingPeerShareResourcesOnNode(1); err != nil {
+		t.Fatal(err)
+	}
+	runtimes, err := a.h.repo.ListActivePeerShareRuntimesByShareID(share.ID)
+	if err != nil || len(runtimes) != 0 {
+		t.Fatalf("retry leaked legacy reservation: %+v %v", runtimes, err)
+	}
+}

go-backend/internal/http/handler/federation_runtime_test.go

@@ -228,7 +228,7 @@ func TestPrepareTunnelCreateStateAllowsOfflineRemoteMiddleNode(t *testing.T) {
 }
 
 func TestBuildFederationServiceConfig_MiddleRoleWithMultipleTargets_SetsRetries(t *testing.T) {
-	service := buildFederationServiceConfig("svc-middle", ":40000", "tls", "middle", "chain-next", 3, "")
+	service := buildFederationServiceConfig("svc-middle", ":40000", "tls", "middle", "chain-next", 3, "", nil)
 	handler := service["handler"].(map[string]interface{})
 	if handler["chain"] != "chain-next" {
 		t.Fatalf("expected chain 'chain-next', got %v", handler["chain"])
@@ -239,7 +239,7 @@ func TestBuildFederationServiceConfig_MiddleRoleWithMultipleTargets_SetsRetries(
 }
 
 func TestBuildFederationServiceConfig_MiddleRoleWithSingleTarget_NoRetries(t *testing.T) {
-	service := buildFederationServiceConfig("svc-middle", ":40000", "tls", "middle", "chain-next", 1, "")
+	service := buildFederationServiceConfig("svc-middle", ":40000", "tls", "middle", "chain-next", 1, "", nil)
 	handler := service["handler"].(map[string]interface{})
 	if handler["chain"] != "chain-next" {
 		t.Fatalf("expected chain 'chain-next', got %v", handler["chain"])
@@ -250,7 +250,7 @@ func TestBuildFederationServiceConfig_MiddleRoleWithSingleTarget_NoRetries(t *te
 }
 
 func TestBuildFederationServiceConfig_ExitRole_NoRetriesRegardlessOfTargets(t *testing.T) {
-	service := buildFederationServiceConfig("svc-exit", ":40000", "tls", "exit", "", 3, "eth0")
+	service := buildFederationServiceConfig("svc-exit", ":40000", "tls", "exit", "", 3, "eth0", nil)
 	handler := service["handler"].(map[string]interface{})
 	if _, hasChain := handler["chain"]; hasChain {
 		t.Fatalf("expected no chain for exit role, got %v", handler["chain"])
@@ -265,7 +265,7 @@ func TestBuildFederationServiceConfig_ExitRole_NoRetriesRegardlessOfTargets(t *t
 }
 
 func TestBuildFederationServiceConfig_TLSTunnelProtocol_SetsNodelay(t *testing.T) {
-	service := buildFederationServiceConfig("svc-tls", ":40000", "tls", "middle", "chain-next", 2, "")
+	service := buildFederationServiceConfig("svc-tls", ":40000", "tls", "middle", "chain-next", 2, "", nil)
 	handler := service["handler"].(map[string]interface{})
 	meta := handler["metadata"].(map[string]interface{})
 	if meta["nodelay"] != true {
@@ -274,10 +274,14 @@ func TestBuildFederationServiceConfig_TLSTunnelProtocol_SetsNodelay(t *testing.T
 }
 
 func TestBuildFederationServiceConfig_NonTLSProtocol_NoNodelay(t *testing.T) {
-	service := buildFederationServiceConfig("svc-tcp", ":40000", "tcp", "middle", "chain-next", 2, "")
+	service := buildFederationServiceConfig("svc-tcp", ":40000", "tcp", "middle", "chain-next", 2, "", nil)
 	handler := service["handler"].(map[string]interface{})
-	if _, hasMeta := handler["metadata"]; hasMeta {
-		t.Fatalf("expected no metadata for non-TLS protocol, got %v", handler["metadata"])
+	metadata, _ := handler["metadata"].(map[string]interface{})
+	if _, hasNodelay := metadata["nodelay"]; hasNodelay {
+		t.Fatal("non-TLS protocol must not set nodelay")
+	}
+	if metadata["chain.strict"] != true {
+		t.Fatal("middle relay must require its configured chain")
 	}
 }
 

go-backend/internal/http/handler/federation_share_test.go

@@ -224,18 +224,14 @@ func TestFederationShareListIncludesRemoteUsedPorts(t *testing.T) {
 }
 
 func TestFederationShareDeleteCleansUpRuntimes(t *testing.T) {
-	r, err := repo.Open(filepath.Join(t.TempDir(), "panel.db"))
-	if err != nil {
-		t.Fatalf("open sqlite: %v", err)
-	}
-	t.Cleanup(func() { _ = r.Close() })
-
-	h := New(r, "test-jwt-secret")
+	agent := newCleanupAgent(t)
+	r := agent.h.repo
+	h := agent.h
 	now := time.Now().UnixMilli()
 
 	if err := r.CreatePeerShare(&repo.PeerShare{
 		Name:           "delete-cleanup-share",
-		NodeID:         99,
+		NodeID:         1,
 		Token:          "delete-cleanup-token",
 		MaxBandwidth:   4096,
 		PortRangeStart: 40000,
@@ -257,8 +253,8 @@ func TestFederationShareDeleteCleansUpRuntimes(t *testing.T) {
 		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?),
 		      (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
 	`,
-		share.ID, 99, "dc-r1", "dc-rk1", "dc-b1", "exit", "", "fed_svc_dc1", "tls", "round", 40001, "", 1, 1, now, now,
-		share.ID, 99, "dc-r2", "dc-rk2", "dc-b2", "middle", "fed_chain_dc2", "fed_svc_dc2", "tls", "round", 40002, "", 1, 1, now, now,
+		share.ID, 1, "dc-r1", "dc-rk1", "dc-b1", "exit", "", "fed_svc_dc1", "tls", "round", 40001, "", 1, 1, now, now,
+		share.ID, 1, "dc-r2", "dc-rk2", "dc-b2", "middle", "fed_chain_dc2", "fed_svc_dc2", "tls", "round", 40002, "", 1, 1, now, now,
 	).Error; err != nil {
 		t.Fatalf("insert peer_share_runtime rows: %v", err)
 	}
@@ -309,11 +305,17 @@ func TestFederationRemoteUsageListSyncErrorFallback(t *testing.T) {
 
 	h := New(r, "test-jwt-secret")
 	now := time.Now().UnixMilli()
+	// Model an unavailable provider entirely on loopback instead of relying on
+	// external DNS or network restrictions to produce the sync error.
+	provider := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		http.Error(w, "provider unavailable", http.StatusServiceUnavailable)
+	}))
+	defer provider.Close()
 
 	if err := r.DB().Exec(`
 		INSERT INTO node(name, secret, server_ip, server_ip_v4, server_ip_v6, port, interface_name, version, http, tls, socks, created_time, updated_time, status, tcp_listen_addr, udp_listen_addr, inx, is_remote, remote_url, remote_token, remote_config)
 		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-	`, "sync-error-node", "sync-error-secret", "10.50.60.70", "10.50.60.70", "", "32000-32010", "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", 0, 1, "http://unreachable.invalid:9999", "bad-token", `{"shareId":42,"maxBandwidth":5368709120,"currentFlow":999999,"portRangeStart":32000,"portRangeEnd":32010}`).Error; err != nil {
+	`, "sync-error-node", "sync-error-secret", "10.50.60.70", "10.50.60.70", "", "32000-32010", "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", 0, 1, provider.URL, "bad-token", `{"shareId":42,"maxBandwidth":5368709120,"currentFlow":999999,"portRangeStart":32000,"portRangeEnd":32010}`).Error; err != nil {
 		t.Fatalf("insert remote node: %v", err)
 	}
 
@@ -352,7 +354,7 @@ func TestFederationRemoteUsageListSyncErrorFallback(t *testing.T) {
 
 	syncErr, _ := first["syncError"].(string)
 	if syncErr == "" {
-		t.Fatalf("expected non-empty syncError field on unreachable provider")
+		t.Fatalf("expected non-empty syncError field on unavailable provider")
 	}
 }
 
@@ -862,11 +864,15 @@ func TestFederationRemoteUsageList(t *testing.T) {
 
 	h := New(r, "test-jwt-secret")
 	now := time.Now().UnixMilli()
+	provider := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		http.Error(w, "provider unavailable", http.StatusServiceUnavailable)
+	}))
+	defer provider.Close()
 
 	if err := r.DB().Exec(`
 		INSERT INTO node(name, secret, server_ip, server_ip_v4, server_ip_v6, port, interface_name, version, http, tls, socks, created_time, updated_time, status, tcp_listen_addr, udp_listen_addr, inx, is_remote, remote_url, remote_token, remote_config)
 		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-	`, "remote-consumer-node", "remote-consumer-secret", "10.30.40.50", "10.30.40.50", "", "31000-31010", "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", 0, 1, "http://peer.example", "peer-token", `{"shareId":88,"maxBandwidth":2147483648,"currentFlow":1073741824,"portRangeStart":31000,"portRangeEnd":31010}`).Error; err != nil {
+	`, "remote-consumer-node", "remote-consumer-secret", "10.30.40.50", "10.30.40.50", "", "31000-31010", "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", 0, 1, provider.URL, "peer-token", `{"shareId":88,"maxBandwidth":2147483648,"currentFlow":1073741824,"portRangeStart":31000,"portRangeEnd":31010}`).Error; err != nil {
 		t.Fatalf("insert remote node: %v", err)
 	}
 	nodeID := mustLastInsertID(t, r, "remote-consumer-node")
@@ -886,8 +892,8 @@ func TestFederationRemoteUsageList(t *testing.T) {
 		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?),
 		      (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
 	`,
-		tunnelAID, nodeID, 2, 1, "http://peer.example", "rk-a", "rb-a", 31001, 1, now, now,
-		tunnelBID, nodeID, 3, 0, "http://peer.example", "rk-b", "rb-b", 31002, 1, now, now,
+		tunnelAID, nodeID, 2, 1, provider.URL, "rk-a", "rb-a", 31001, 1, now, now,
+		tunnelBID, nodeID, 3, 0, provider.URL, "rk-b", "rb-b", 31002, 1, now, now,
 	).Error; err != nil {
 		t.Fatalf("insert federation bindings: %v", err)
 	}

go-backend/internal/http/handler/flow_cleanup_regression_test.go

@@ -0,0 +1,305 @@
+package handler
+
+import (
+	"encoding/json"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"reflect"
+	"sort"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/gorilla/websocket"
+	"gorm.io/gorm"
+
+	"go-backend/internal/security"
+	"go-backend/internal/store/model"
+	"go-backend/internal/store/repo"
+	"go-backend/internal/ws"
+)
+
+type cleanupAgentCommand struct {
+	Type      string          `json:"type"`
+	Data      json.RawMessage `json:"data"`
+	RequestID string          `json:"requestId"`
+}
+
+// cleanupAgent exercises the actual command transport. Each command is recorded
+// before its ACK, so synchronous handler calls need no sleeps to inspect it.
+type cleanupAgent struct {
+	h        *Handler
+	mu       sync.Mutex
+	commands []cleanupAgentCommand
+}
+
+func newCleanupAgent(t *testing.T, setup ...func(*repo.Repository)) *cleanupAgent {
+	t.Helper()
+	r, err := repo.Open(filepath.Join(t.TempDir(), "cleanup.db"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = r.Close() })
+	const secret = "cleanup-regression-node"
+	if err := r.DB().Create(&model.Node{ID: 1, Name: "relay", Secret: secret, ServerIP: "127.0.0.1", Port: "30000", Status: 1}).Error; err != nil {
+		t.Fatal(err)
+	}
+	// Register test-local database callbacks before WebSocket goroutines can
+	// execute them. Keep registries immutable until the fixture is closed.
+	for _, configure := range setup {
+		configure(r)
+	}
+	server := ws.NewServer(r, "test-jwt-secret")
+	online := make(chan struct{})
+	server.SetNodeOnlineHook(func(int64) { close(online) })
+	serverDone := make(chan struct{})
+	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
+		defer close(serverDone)
+		server.ServeHTTP(w, req)
+	}))
+	t.Cleanup(ts.Close)
+	conn, _, err := websocket.DefaultDialer.Dial("ws"+strings.TrimPrefix(ts.URL, "http")+"?type=1&secret="+secret, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	crypto, err := security.NewAESCrypto(secret)
+	if err != nil {
+		t.Fatal(err)
+	}
+	a := &cleanupAgent{h: &Handler{repo: r, wsServer: server}}
+	readerDone := make(chan struct{})
+	go func() {
+		defer close(readerDone)
+		for {
+			_, payload, err := conn.ReadMessage()
+			if err != nil {
+				return
+			}
+			var envelope struct {
+				Encrypted bool   `json:"encrypted"`
+				Data      string `json:"data"`
+			}
+			if err := json.Unmarshal(payload, &envelope); err != nil {
+				t.Errorf("decode command envelope: %v", err)
+				return
+			}
+			if envelope.Encrypted {
+				payload, err = crypto.Decrypt(envelope.Data)
+				if err != nil {
+					t.Errorf("decrypt command: %v", err)
+					return
+				}
+			}
+			var command cleanupAgentCommand
+			if err := json.Unmarshal(payload, &command); err != nil {
+				t.Errorf("decode command: %v", err)
+				return
+			}
+			a.mu.Lock()
+			a.commands = append(a.commands, command)
+			a.mu.Unlock()
+			if err := conn.WriteJSON(map[string]interface{}{"type": command.Type, "requestId": command.RequestID, "success": true}); err != nil {
+				return
+			}
+		}
+	}()
+	t.Cleanup(func() {
+		_ = conn.Close()
+		<-readerDone
+		<-serverDone
+	})
+	select {
+	case <-online:
+	case <-time.After(3 * time.Second):
+		t.Fatal("mock node did not come online")
+	}
+	a.probe(t)
+	return a
+}
+
+func (a *cleanupAgent) probe(t *testing.T) {
+	t.Helper()
+	if _, err := a.h.wsServer.SendCommand(1, "CleanupTestProbe", nil, time.Second); err != nil {
+		t.Fatalf("mock agent transport unavailable: %v", err)
+	}
+}
+
+func (a *cleanupAgent) commandsOfType(commandType string) []cleanupAgentCommand {
+	a.mu.Lock()
+	defer a.mu.Unlock()
+	var commands []cleanupAgentCommand
+	for _, command := range a.commands {
+		if command.Type == commandType {
+			commands = append(commands, command)
+		}
+	}
+	return commands
+}
+
+func (a *cleanupAgent) addRuntime(t *testing.T, name string, nodeID int64, status, applied int, updated time.Time) int64 {
+	t.Helper()
+	now := time.Now().UnixMilli()
+	share := &repo.PeerShare{Name: "shared", NodeID: nodeID, Token: "cleanup-share-token", PortRangeStart: 31000, PortRangeEnd: 31010, IsActive: 1, CreatedTime: now, UpdatedTime: now}
+	if err := a.h.repo.CreatePeerShare(share); err != nil {
+		t.Fatal(err)
+	}
+	stored, err := a.h.repo.GetPeerShareByToken(share.Token)
+	if err != nil || stored == nil {
+		t.Fatalf("load share: %v", err)
+	}
+	// SQL preserves status=0; GORM's default tag would replace that with 1.
+	if err := a.h.repo.DB().Exec(`INSERT INTO peer_share_runtime
+		(share_id, node_id, reservation_id, resource_key, role, service_name, applied, status, created_time, updated_time)
+		VALUES (?, ?, 'cleanup-reservation', 'cleanup-resource', 'forward', ?, ?, ?, ?, ?)`,
+		stored.ID, nodeID, name, applied, status, now, updated.UnixMilli()).Error; err != nil {
+		t.Fatal(err)
+	}
+	return stored.ID
+}
+
+func TestSharedForwardCleanupRegression(t *testing.T) {
+	for _, mode := range []string{"single", "batch", "config"} {
+		for _, runtimeName := range []string{"70_1_0", "70_1_0_tcp", "70_1_0_udp"} {
+			t.Run(mode+"/active/"+runtimeName, func(t *testing.T) {
+				a := newCleanupAgent(t)
+				shareID := a.addRuntime(t, runtimeName, 1, 1, 1, time.Now())
+				runCleanupPath(a.h, mode, []string{"70_1_0", "70_1_0_tcp", "70_1_0_udp"})
+				a.probe(t)
+				if commands := a.commandsOfType("DeleteService"); len(commands) != 0 {
+					t.Fatalf("active shared service family was deleted: %+v", commands)
+				}
+				if mode != "config" && runtimeName == "70_1_0" {
+					share, err := a.h.repo.GetPeerShare(shareID)
+					if err != nil || share == nil || share.CurrentFlow != 600 {
+						t.Fatalf("shared traffic should accumulate 600 bytes: share=%+v err=%v", share, err)
+					}
+				}
+			})
+		}
+		for _, tc := range []struct {
+			name        string
+			serviceName string
+			nodeID      int64
+			status      int
+			applied     int
+			age         time.Duration
+			wantDelete  bool
+		}{
+			{name: "recent-unbound", nodeID: 1, status: 1, age: time.Minute},
+			{name: "stale-unbound", nodeID: 1, status: 1, age: 11 * time.Minute, wantDelete: true},
+			{name: "released", serviceName: "70_1_0", nodeID: 1, applied: 1, wantDelete: true},
+			{name: "other-node-bound", serviceName: "70_1_0", nodeID: 2, status: 1, applied: 1, wantDelete: true},
+			{name: "other-node-unbound", nodeID: 2, status: 1, wantDelete: true},
+			{name: "unrelated-active-family", serviceName: "71_1_0", nodeID: 1, status: 1, applied: 1, wantDelete: true},
+		} {
+			t.Run(mode+"/"+tc.name, func(t *testing.T) {
+				a := newCleanupAgent(t)
+				a.addRuntime(t, tc.serviceName, tc.nodeID, tc.status, tc.applied, time.Now().Add(-tc.age))
+				runCleanupPath(a.h, mode, []string{"70_1_0_tcp"})
+				a.probe(t)
+				commands := a.commandsOfType("DeleteService")
+				if !tc.wantDelete {
+					if len(commands) != 0 {
+						t.Fatalf("recent unbound shared runtime was deleted: %+v", commands)
+					}
+					return
+				}
+				if len(commands) != 1 {
+					t.Fatalf("expected one orphan cleanup command, got %+v", commands)
+				}
+				var data struct {
+					Services []string `json:"services"`
+				}
+				if err := json.Unmarshal(commands[0].Data, &data); err != nil {
+					t.Fatal(err)
+				}
+				sort.Strings(data.Services)
+				if want := []string{"70_1_0", "70_1_0_tcp", "70_1_0_udp"}; !reflect.DeepEqual(data.Services, want) {
+					t.Fatalf("orphan cleanup must delete complete family: got %v, want %v", data.Services, want)
+				}
+			})
+		}
+	}
+}
+
+func runCleanupPath(h *Handler, mode string, names []string) {
+	items := make([]flowItem, 0, len(names))
+	services := make([]namedConfigItem, 0, len(names))
+	for _, name := range names {
+		items = append(items, flowItem{N: name, U: 120, D: 80})
+		services = append(services, namedConfigItem{Name: name})
+	}
+	switch mode {
+	case "single":
+		for _, item := range items {
+			h.processFlowItem(1, item)
+		}
+	case "batch":
+		h.applyFlowUploadBatch(1, h.buildNodeFlowUploadBatch(1, items, nil), time.Now())
+	case "config":
+		h.cleanOrphanedServices(1, services)
+	}
+}
+
+func TestSharedForwardCleanupMissingMetadataPreservesLocalForward(t *testing.T) {
+	a := newCleanupAgent(t)
+	if err := a.h.repo.DB().Create(&model.Forward{ID: 70, UserID: 1, UserName: "local", Name: "local", TunnelID: 1, RemoteAddr: "127.0.0.1:80", Status: 1}).Error; err != nil {
+		t.Fatal(err)
+	}
+	runCleanupPath(a.h, "batch", []string{"70_1_0", "70_1_0_tcp", "70_1_0_udp"})
+	a.probe(t)
+	if commands := a.commandsOfType("DeleteService"); len(commands) != 0 {
+		t.Fatalf("missing batch metadata must not delete a local forward: %+v", commands)
+	}
+}
+
+func TestSharedForwardCleanupChecksActualDeleteFamily(t *testing.T) {
+	for _, mode := range []string{"single", "batch", "config"} {
+		t.Run(mode, func(t *testing.T) {
+			a := newCleanupAgent(t)
+			a.addRuntime(t, "70_1_0", 1, 1, 1, time.Now())
+			// Legacy parsing accepts additional suffixes. Cleanup must check
+			// the family it would delete, not just the reported service name.
+			runCleanupPath(a.h, mode, []string{"70_1_0_old", "70_1_0_old_tcp"})
+			a.probe(t)
+			if commands := a.commandsOfType("DeleteService"); len(commands) != 0 {
+				t.Fatalf("suffix variation must not delete a protected shared family: %+v", commands)
+			}
+		})
+	}
+}
+
+func TestSharedForwardCleanupQueryFailurePreservesServices(t *testing.T) {
+	for _, mode := range []string{"single", "batch", "config"} {
+		for _, failure := range []string{"forward", "peer_share_runtime"} {
+			t.Run(mode+"/"+failure, func(t *testing.T) {
+				a := newCleanupAgent(t)
+				// Fail only the ownership lookup; leave node lookup and WebSocket
+				// delivery functional so an erroneous delete remains observable.
+				callback := "test:cleanup-query-failure"
+				var injected atomic.Int32
+				if err := a.h.repo.DB().Callback().Query().Before("gorm:query").Register(callback, func(tx *gorm.DB) {
+					if tx.Statement.Table == failure {
+						injected.Add(1)
+						tx.AddError(errors.New("injected ownership query failure"))
+					}
+				}); err != nil {
+					t.Fatal(err)
+				}
+				t.Cleanup(func() { _ = a.h.repo.DB().Callback().Query().Remove(callback) })
+				runCleanupPath(a.h, mode, []string{"70_1_0_tcp"})
+				a.probe(t)
+				if injected.Load() == 0 {
+					t.Fatal("test did not inject the expected query failure")
+				}
+				if commands := a.commandsOfType("DeleteService"); len(commands) != 0 {
+					t.Fatalf("ownership query failure must preserve services: %+v", commands)
+				}
+			})
+		}
+	}
+}

go-backend/internal/http/handler/flow_config_cleanup_test.go

@@ -0,0 +1,145 @@
+package handler
+
+import (
+	"encoding/json"
+	"errors"
+	"testing"
+	"time"
+
+	"gorm.io/gorm"
+)
+
+func TestConfigCleanupPreservesSharedDependencies(t *testing.T) {
+	a := newCleanupAgent(t)
+	a.addRuntime(t, "70_1_0", 1, 1, 1, time.Now())
+	a.h.cleanNodeConfigs(1, `{
+		"services": [{"name":"70_1_0_tcp", "handler":{"chain":"chains_88"}, "limiter":"13, rule_traffic_limit_70"}],
+		"chains": [{"name":"fed_chain_17"}, {"name":"chains_88"}, {"name":"chains_999"}],
+		"limiters": [{"name":"13"}, {"name":"rule_traffic_limit_70"}, {"name":"99"}]
+	}`)
+	a.probe(t)
+	if commands := a.commandsOfType("DeleteService"); len(commands) != 0 {
+		t.Fatalf("shared service was deleted: %+v", commands)
+	}
+	assertCleanupDependency(t, a, "DeleteChains", "chain", "chains_999")
+	assertCleanupDependency(t, a, "DeleteLimiters", "limiter", "99")
+}
+
+func TestConfigCleanupRemovesOrphanedForwardLimiter(t *testing.T) {
+	a := newCleanupAgent(t)
+	a.h.cleanNodeConfigs(1, `{"limiters":[{"name":"rule_traffic_limit_70"}]}`)
+	a.probe(t)
+	assertCleanupDependency(t, a, "DeleteLimiters", "limiter", "rule_traffic_limit_70")
+}
+
+func TestConfigCleanupProtectsPendingSharedDependencies(t *testing.T) {
+	for _, tc := range []struct {
+		name string
+		age  time.Duration
+		keep bool
+	}{
+		{name: "pending", age: time.Minute, keep: true},
+		{name: "expired-reservation", age: 11 * time.Minute},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			a := newCleanupAgent(t)
+			a.addRuntime(t, "", 1, 1, 0, time.Now().Add(-tc.age))
+			// Dependencies may arrive before the service and its runtime binding.
+			a.h.cleanNodeConfigs(1, `{"chains":[{"name":"chains_88"}],"limiters":[{"name":"13"}]}`)
+			a.probe(t)
+			if tc.keep {
+				for _, commandType := range []string{"DeleteChains", "DeleteLimiters"} {
+					if commands := a.commandsOfType(commandType); len(commands) != 0 {
+						t.Fatalf("pending shared dependencies deleted: %+v", commands)
+					}
+				}
+				return
+			}
+			assertCleanupDependency(t, a, "DeleteChains", "chain", "chains_88")
+			assertCleanupDependency(t, a, "DeleteLimiters", "limiter", "13")
+		})
+	}
+}
+
+func TestConfigCleanupPreservesDependenciesOnLookupFailure(t *testing.T) {
+	for _, table := range []string{"peer_share_runtime", "tunnel", "speed_limit", "forward"} {
+		t.Run(table, func(t *testing.T) {
+			a := newCleanupAgent(t)
+			callback := "test:config-cleanup-query-failure"
+			injected := false
+			if err := a.h.repo.DB().Callback().Query().Before("gorm:query").Register(callback, func(tx *gorm.DB) {
+				if tx.Statement.Table == table {
+					injected = true
+					tx.AddError(errors.New("injected dependency lookup failure"))
+				}
+			}); err != nil {
+				t.Fatal(err)
+			}
+			t.Cleanup(func() { _ = a.h.repo.DB().Callback().Query().Remove(callback) })
+			configs := map[string]string{
+				"peer_share_runtime": `{"chains":[{"name":"chains_88"}],"limiters":[{"name":"13"}]}`,
+				"tunnel":             `{"chains":[{"name":"chains_88"}]}`,
+				"speed_limit":        `{"limiters":[{"name":"13"}]}`,
+				"forward":            `{"limiters":[{"name":"rule_traffic_limit_70"}]}`,
+			}
+			a.h.cleanNodeConfigs(1, configs[table])
+			a.probe(t)
+			if !injected {
+				t.Fatal("expected dependency lookup failure to be injected")
+			}
+			for _, commandType := range []string{"DeleteChains", "DeleteLimiters"} {
+				if commands := a.commandsOfType(commandType); len(commands) != 0 {
+					t.Fatalf("lookup failure must not authorize cleanup: %+v", commands)
+				}
+			}
+		})
+	}
+}
+
+func TestSharedForwardCleanupDuringRuntimeBinding(t *testing.T) {
+	for _, mode := range []string{"single", "batch", "config"} {
+		t.Run(mode, func(t *testing.T) {
+			a := newCleanupAgent(t)
+			a.addRuntime(t, "", 1, 1, 0, time.Now())
+			callback := "test:bind-during-cleanup"
+			bound := false
+			if err := a.h.repo.DB().Callback().Query().After("gorm:query").Register(callback, func(tx *gorm.DB) {
+				if tx.Statement.Table != "peer_share_runtime" || bound {
+					return
+				}
+				bound = true
+				// Reproduce binding immediately after the first ownership read.
+				// Separate name/unbound queries would both miss this runtime.
+				if err := a.h.repo.DB().Exec("UPDATE peer_share_runtime SET service_name = ?, applied = 1", "70_1_0").Error; err != nil {
+					t.Errorf("bind shared runtime: %v", err)
+				}
+			}); err != nil {
+				t.Fatal(err)
+			}
+			t.Cleanup(func() { _ = a.h.repo.DB().Callback().Query().Remove(callback) })
+			runCleanupPath(a.h, mode, []string{"70_1_0_tcp"})
+			a.probe(t)
+			if !bound {
+				t.Fatal("binding transition did not run")
+			}
+			if commands := a.commandsOfType("DeleteService"); len(commands) != 0 {
+				t.Fatalf("service was deleted during binding: %+v", commands)
+			}
+		})
+	}
+}
+
+func assertCleanupDependency(t *testing.T, a *cleanupAgent, commandType, key, want string) {
+	t.Helper()
+	commands := a.commandsOfType(commandType)
+	if len(commands) != 1 {
+		t.Fatalf("expected one %s for %s, got %+v", commandType, want, commands)
+	}
+	var data map[string]string
+	if err := json.Unmarshal(commands[0].Data, &data); err != nil {
+		t.Fatal(err)
+	}
+	if data[key] != want {
+		t.Fatalf("unexpected %s target: got %q, want %q", commandType, data[key], want)
+	}
+}

go-backend/internal/http/handler/flow_ownership.go

@@ -0,0 +1,118 @@
+package handler
+
+import (
+	"log"
+	"strings"
+
+	"go-backend/internal/store/repo"
+)
+
+// Classify ownership before building local counters or enforcing local quotas.
+// Numeric IDs from a consuming panel are not IDs in the provider's database.
+func (h *Handler) buildNodeFlowUploadBatch(nodeID int64, items []flowItem, metas map[int64]repo.FlowUploadForwardMeta) flowUploadBatch {
+	if h == nil || h.repo == nil || nodeID <= 0 {
+		return flowUploadBatch{}
+	}
+	runtimes, err := h.repo.ListActiveForwardPeerShareRuntimesByNode(nodeID)
+	if err != nil {
+		log.Printf("flow ownership lookup failed node_id=%d err=%v", nodeID, err)
+		return flowUploadBatch{}
+	}
+	resources, err := h.repo.ListPeerShareResourcesByNode(nodeID)
+	if err != nil {
+		log.Printf("flow resource lookup failed node_id=%d err=%v", nodeID, err)
+		return flowUploadBatch{}
+	}
+	forwardIDs, err := h.repo.ListForwardIDsByNode(nodeID)
+	if err != nil {
+		log.Printf("flow node ownership lookup failed node_id=%d err=%v", nodeID, err)
+		return flowUploadBatch{}
+	}
+	nodeForwards := make(map[int64]struct{}, len(forwardIDs))
+	for _, forwardID := range forwardIDs {
+		nodeForwards[forwardID] = struct{}{}
+	}
+	legacyOwners := make(map[string]map[int64]struct{})
+	addLegacyOwner := func(name string, shareID int64) {
+		name = normalizeForwardRuntimeServiceName(name)
+		if name == "" {
+			return
+		}
+		if legacyOwners[name] == nil {
+			legacyOwners[name] = make(map[int64]struct{})
+		}
+		legacyOwners[name][shareID] = struct{}{}
+	}
+	for _, runtime := range runtimes {
+		addLegacyOwner(runtime.ServiceName, runtime.ShareID)
+	}
+	resourceOwners := make(map[string]int64)
+	for _, resource := range resources {
+		// A migrated TCP service may still own a legacy UDP sibling. This alias
+		// remains authoritative until the whole legacy family is acknowledged gone.
+		addLegacyOwner(resource.LegacyServiceBase, resource.ShareID)
+		// A deletion intent does not prove the listener is gone. Failed or
+		// timed-out commands retain ownership until the node acknowledges it.
+		if resource.Kind == "service" && (resource.DesiredState != "deleted" || resource.Applied == 0) {
+			resourceOwners[resource.RuntimeName] = resource.ShareID
+		}
+	}
+	localItems := make([]flowItem, 0, len(items))
+	sharedUsage := make(map[int64]int64)
+	for _, item := range items {
+		name := strings.TrimSpace(item.N)
+		if strings.HasPrefix(name, "peer-share-") {
+			shareID, _, ok := parsePeerShareServiceName(name)
+			if ok && resourceOwners[name] == shareID && item.U >= 0 && item.D >= 0 {
+				sharedUsage[shareID] += item.U + item.D
+			}
+			// Unknown or confirmed-deleted scoped names must never become local IDs.
+			continue
+		}
+		if owners := legacyOwners[normalizeForwardRuntimeServiceName(name)]; len(owners) > 0 {
+			forwardID, userID, userTunnelID, parsed := parseFlowServiceIDs(name)
+			meta, local := metas[forwardID]
+			_, onNode := nodeForwards[forwardID]
+			if parsed && local && onNode && meta.UserID == userID && meta.UserTunnelID == userTunnelID {
+				// Legacy names can be genuinely ambiguous. Preserve the listener
+				// but do not debit either owner based on an ID guess.
+				log.Printf("ambiguous legacy flow ownership node_id=%d service=%s", nodeID, name)
+				continue
+			}
+			if len(owners) == 1 && item.U >= 0 && item.D >= 0 {
+				for shareID := range owners {
+					sharedUsage[shareID] += item.U + item.D
+				}
+			}
+			continue
+		}
+		if forwardID, userID, _, ok := parseFlowServiceIDs(name); ok {
+			if meta, exists := metas[forwardID]; exists {
+				if _, onNode := nodeForwards[forwardID]; !onNode || meta.UserID != userID {
+					continue
+				}
+			}
+		}
+		localItems = append(localItems, item)
+	}
+	batch := h.buildFlowUploadBatch(localItems, metas)
+	batch.peerShareUsage = sharedUsage
+	return batch
+}
+
+func (h *Handler) addPeerShareFlow(nodeID, shareID, delta int64) {
+	if nodeID <= 0 || shareID <= 0 || delta <= 0 {
+		return
+	}
+	share, err := h.repo.GetPeerShare(shareID)
+	if err != nil || share == nil || share.NodeID != nodeID {
+		return
+	}
+	if err := h.repo.AddPeerShareCurrentFlow(shareID, delta); err != nil {
+		return
+	}
+	share, err = h.repo.GetPeerShare(shareID)
+	if err == nil && isPeerShareFlowExceeded(share) {
+		h.enforcePeerShareFlowLimit(shareID)
+	}
+}

go-backend/internal/http/handler/flow_ownership_test.go

@@ -0,0 +1,235 @@
+package handler
+
+import (
+	"go-backend/internal/store/model"
+	"go-backend/internal/store/repo"
+	"testing"
+	"time"
+)
+
+func TestFlowOwnershipSharedFlowDoesNotChargeLocalCollision(t *testing.T) {
+	a := newCleanupAgent(t)
+	shareID := a.addRuntime(t, "70_1_0", 1, 1, 1, time.Now())
+	if err := a.h.repo.DB().Create(&model.Tunnel{ID: 9, Name: "local", TrafficRatio: 1, Flow: 1, Type: 1, Status: 1}).Error; err != nil {
+		t.Fatal(err)
+	}
+	if err := a.h.repo.DB().Create(&model.Forward{ID: 70, UserID: 2, UserName: "local", Name: "local", TunnelID: 9, RemoteAddr: "127.0.0.1:80", Status: 1}).Error; err != nil {
+		t.Fatal(err)
+	}
+	metas, err := a.h.repo.GetFlowUploadForwardMetas([]int64{70})
+	if err != nil {
+		t.Fatal(err)
+	}
+	a.h.applyFlowUploadBatch(1, a.h.buildNodeFlowUploadBatch(1, []flowItem{{N: "70_1_0_tcp", U: 120, D: 80}}, metas), time.Now())
+	var local model.Forward
+	if err := a.h.repo.DB().First(&local, 70).Error; err != nil {
+		t.Fatal(err)
+	}
+	shared, err := a.h.repo.GetPeerShare(shareID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Logf("local user=%d local bytes=%d shared bytes=%d", local.UserID, local.InFlow+local.OutFlow, shared.CurrentFlow)
+	if local.InFlow+local.OutFlow != 0 {
+		t.Errorf("shared flow charged colliding local forward: %d", local.InFlow+local.OutFlow)
+	}
+	if shared.CurrentFlow != 200 {
+		t.Errorf("shared flow missing: %d", shared.CurrentFlow)
+	}
+}
+
+func TestFlowOwnershipScopedServiceRequiresStoredNodeOwnership(t *testing.T) {
+	a := newCleanupAgent(t)
+	shareID := a.addRuntime(t, "70_1_0", 1, 1, 1, time.Now())
+	name := peerShareResourceName(shareID, "service", "70_1_0_tcp")
+	if err := a.h.repo.SavePeerShareResources([]repo.PeerShareResource{{
+		ShareID: shareID, NodeID: 1, Kind: "service", OriginalName: "70_1_0_tcp",
+		RuntimeName: name, DesiredState: "active", Applied: 1,
+	}}); err != nil {
+		t.Fatal(err)
+	}
+	for _, nodeID := range []int64{2, 1} {
+		batch := a.h.buildNodeFlowUploadBatch(nodeID, []flowItem{{N: name, U: 120, D: 80}}, nil)
+		a.h.applyFlowUploadBatch(nodeID, batch, time.Now())
+		share, err := a.h.repo.GetPeerShare(shareID)
+		if err != nil {
+			t.Fatal(err)
+		}
+		want := int64(0)
+		if nodeID == 1 {
+			want = 200
+		}
+		if share.CurrentFlow != want {
+			t.Fatalf("node=%d: got flow=%d want=%d", nodeID, share.CurrentFlow, want)
+		}
+		if len(batch.flowDeltas) != 0 || len(batch.quotaUsage) != 0 || len(batch.orphanServices) != 0 {
+			t.Fatalf("scoped traffic entered local accounting: %+v", batch)
+		}
+	}
+	a.probe(t)
+	if cmds := a.commandsOfType("DeleteService"); len(cmds) != 0 {
+		t.Fatalf("scoped service deleted: %+v", cmds)
+	}
+}
+
+func TestFlowOwnershipRoleRuntimeRequiresReportingNode(t *testing.T) {
+	a := newCleanupAgent(t)
+	shareID := a.addRuntime(t, "fed_svc_17", 1, 1, 1, time.Now())
+	if err := a.h.repo.DB().Exec("UPDATE peer_share_runtime SET id = 17, role = 'exit'").Error; err != nil {
+		t.Fatal(err)
+	}
+	a.h.processFlowItem(2, flowItem{N: "fed_svc_17", U: 120, D: 80})
+	share, err := a.h.repo.GetPeerShare(shareID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if share.CurrentFlow != 0 {
+		t.Fatalf("wrong node charged role runtime: %d", share.CurrentFlow)
+	}
+	a.h.processFlowItem(1, flowItem{N: "fed_svc_17", U: 120, D: 80})
+	share, err = a.h.repo.GetPeerShare(shareID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if share.CurrentFlow != 200 {
+		t.Fatalf("owner node flow missing: %d", share.CurrentFlow)
+	}
+}
+
+func TestFlowOwnershipAmbiguousLegacyNameDoesNotDebitEitherOwner(t *testing.T) {
+	a := newCleanupAgent(t)
+	shareID := a.addRuntime(t, "70_1_0", 1, 1, 1, time.Now())
+	if err := a.h.repo.DB().Create(&model.Forward{ID: 70, UserID: 1, UserName: "local", Name: "local", TunnelID: 9, RemoteAddr: "127.0.0.1:80", Status: 1}).Error; err != nil {
+		t.Fatal(err)
+	}
+	if err := a.h.repo.DB().Create(&model.ForwardPort{ForwardID: 70, NodeID: 1, Port: 32000}).Error; err != nil {
+		t.Fatal(err)
+	}
+	metas, err := a.h.repo.GetFlowUploadForwardMetas([]int64{70})
+	if err != nil {
+		t.Fatal(err)
+	}
+	batch := a.h.buildNodeFlowUploadBatch(1, []flowItem{{N: "70_1_0_tcp", U: 120, D: 80}}, metas)
+	a.h.applyFlowUploadBatch(1, batch, time.Now())
+	share, err := a.h.repo.GetPeerShare(shareID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if share.CurrentFlow != 0 || len(batch.flowDeltas) != 0 {
+		t.Fatalf("ambiguous flow charged an owner: share=%d local=%+v", share.CurrentFlow, batch.flowDeltas)
+	}
+	a.probe(t)
+	if commands := a.commandsOfType("DeleteService"); len(commands) != 0 {
+		t.Fatalf("ambiguous legacy service deleted: %+v", commands)
+	}
+}
+
+func TestFlowOwnershipPreservesUnmigratedLegacyTransport(t *testing.T) {
+	a := newCleanupAgent(t)
+	shareID := a.addRuntime(t, peerShareResourceName(1, "service", "70_1_0"), 1, 1, 1, time.Now())
+	if err := a.h.repo.SavePeerShareResources([]repo.PeerShareResource{{
+		ShareID: shareID, NodeID: 1, Kind: "service", OriginalName: "70_1_0_tcp",
+		RuntimeName:       peerShareResourceName(shareID, "service", "70_1_0_tcp"),
+		LegacyServiceBase: "70_1_0", DesiredState: "deleted", Applied: 1,
+	}}); err != nil {
+		t.Fatal(err)
+	}
+	a.h.processFlowItem(1, flowItem{N: "70_1_0_udp", U: 120, D: 80})
+	a.h.cleanNodeConfigs(1, `{"services":[{"name":"70_1_0_udp"}]}`)
+	a.probe(t)
+	if commands := a.commandsOfType("DeleteService"); len(commands) != 0 {
+		t.Fatalf("unmigrated transport deleted: %+v", commands)
+	}
+	share, err := a.h.repo.GetPeerShare(shareID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if share.CurrentFlow != 200 {
+		t.Fatalf("legacy transport accounting lost: %d", share.CurrentFlow)
+	}
+}
+
+func TestFlowOwnershipLocalForwardRequiresReportingNode(t *testing.T) {
+	a := newCleanupAgent(t)
+	if err := a.h.repo.DB().Create(&model.Forward{ID: 70, UserID: 1, UserName: "local", Name: "local", TunnelID: 9, RemoteAddr: "127.0.0.1:80", Status: 1}).Error; err != nil {
+		t.Fatal(err)
+	}
+	if err := a.h.repo.DB().Create(&model.ForwardPort{ForwardID: 70, NodeID: 2, Port: 32000}).Error; err != nil {
+		t.Fatal(err)
+	}
+	metas, err := a.h.repo.GetFlowUploadForwardMetas([]int64{70})
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, nodeID := range []int64{1, 2} {
+		batch := a.h.buildNodeFlowUploadBatch(nodeID, []flowItem{{N: "70_1_0_tcp", U: 120, D: 80}}, metas)
+		a.h.applyFlowUploadBatch(nodeID, batch, time.Now())
+		var forward model.Forward
+		if err := a.h.repo.DB().First(&forward, 70).Error; err != nil {
+			t.Fatal(err)
+		}
+		want := int64(0)
+		if nodeID == 2 {
+			want = 200
+		}
+		if forward.InFlow+forward.OutFlow != want {
+			t.Fatalf("node %d local traffic=%d want=%d", nodeID, forward.InFlow+forward.OutFlow, want)
+		}
+	}
+}
+
+func TestPeerShareMaintenanceRetriesOnlyUnfinishedOperations(t *testing.T) {
+	a := newCleanupAgent(t)
+	shareID := a.addRuntime(t, "70_1_0", 1, 1, 1, time.Now())
+	name := peerShareResourceName(shareID, "service", "80_1_0_tcp")
+	if err := a.h.repo.SavePeerShareResources([]repo.PeerShareResource{{ShareID: shareID, NodeID: 1,
+		Kind: "service", OriginalName: "80_1_0_tcp", RuntimeName: name, DesiredState: "deleted", Applied: 0,
+	}}); err != nil {
+		t.Fatal(err)
+	}
+	a.h.retryPendingPeerShareOperations()
+	a.probe(t)
+	if commands := a.commandsOfType("DeleteService"); len(commands) != 1 {
+		t.Fatalf("pending delete was not retried: %+v", commands)
+	}
+	a.h.retryPendingPeerShareOperations()
+	a.probe(t)
+	if commands := a.commandsOfType("DeleteService"); len(commands) != 1 {
+		t.Fatalf("completed delete was replayed: %+v", commands)
+	}
+	ids, err := a.h.repo.ListPendingPeerShareNodeIDs()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(ids) != 0 {
+		t.Fatalf("completed operation still pending: %v", ids)
+	}
+}
+
+func TestFlowOwnershipDoesNotCrossNodes(t *testing.T) {
+	a := newCleanupAgent(t)
+	shareID := a.addRuntime(t, "70_1_0", 1, 1, 1, time.Now())
+	share, err := a.h.repo.GetPeerShare(shareID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	share.MaxBandwidth = 100
+	if err := a.h.repo.UpdatePeerShare(share); err != nil {
+		t.Fatal(err)
+	}
+	// Node 2 has no shared runtime. It reports the same local numeric service name.
+	a.h.applyFlowUploadBatch(2, a.h.buildNodeFlowUploadBatch(2, []flowItem{{N: "70_1_0_tcp", U: 120, D: 80}}, nil), time.Now())
+	a.probe(t)
+	share, err = a.h.repo.GetPeerShare(shareID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	commands := a.commandsOfType("DeleteService")
+	t.Logf("node1 share charged from node2: %d; node1 delete commands: %+v", share.CurrentFlow, commands)
+	if share.CurrentFlow != 0 {
+		t.Errorf("flow crossed node boundary: %d", share.CurrentFlow)
+	}
+	if len(commands) != 0 {
+		t.Errorf("node2 flow deleted node1 shared service: %+v", commands)
+	}
+}

go-backend/internal/http/handler/flow_pending_deletion_test.go

@@ -0,0 +1,57 @@
+package handler
+
+import (
+	"testing"
+	"time"
+)
+
+func TestFlowOwnershipPendingDeletionRemainsBillableUntilAcknowledged(t *testing.T) {
+	for _, mode := range []string{"single", "batch"} {
+		t.Run(mode, func(t *testing.T) {
+			a := newCleanupAgent(t)
+			share := resourceTestShare(t, a.h, "pending-deletion-"+mode)
+			if got := resourceTestCommand(t, a.h, share, "AddService", resourceTestService("70_1_0_tcp", 31001)); got.Code != 0 {
+				t.Fatal(got.Msg)
+			}
+			name := peerShareResourceName(share.ID, "service", "70_1_0_tcp")
+			// Simulate a failed delivery after the deletion intent is committed. The
+			// mock node's previously installed listener has received no delete command.
+			disconnected := &Handler{repo: a.h.repo}
+			if got := resourceTestCommand(t, disconnected, share, "DeleteService", map[string]interface{}{"services": []string{"70_1_0_tcp"}}); got.Code == 0 {
+				t.Fatal("failed deletion reported success")
+			}
+			resource, err := a.h.repo.GetPeerShareResource(share.ID, "service", "70_1_0_tcp")
+			if err != nil || resource == nil || resource.DesiredState != "deleted" || resource.Applied != 0 {
+				t.Fatalf("missing pending tombstone: %+v %v", resource, err)
+			}
+			report := func() {
+				item := flowItem{N: name, U: 120, D: 80}
+				if mode == "single" {
+					a.h.processFlowItem(1, item)
+				} else {
+					a.h.applyFlowUploadBatch(1, a.h.buildNodeFlowUploadBatch(1, []flowItem{item}, nil), time.Now())
+				}
+			}
+			report()
+			stored, err := a.h.repo.GetPeerShare(share.ID)
+			if err != nil || stored.CurrentFlow != 200 {
+				t.Fatalf("unconfirmed deletion stopped billing: share=%+v err=%v", stored, err)
+			}
+			if len(a.commandsOfType("DeleteService")) != 0 {
+				t.Fatal("flow handling deleted a pending shared listener")
+			}
+			if err := a.h.retryPendingPeerShareResourcesOnNode(1); err != nil {
+				t.Fatal(err)
+			}
+			resource, err = a.h.repo.GetPeerShareResource(share.ID, "service", "70_1_0_tcp")
+			if err != nil || resource.Applied != 1 {
+				t.Fatalf("deletion acknowledgment not recorded: %+v %v", resource, err)
+			}
+			report()
+			stored, err = a.h.repo.GetPeerShare(share.ID)
+			if err != nil || stored.CurrentFlow != 200 {
+				t.Fatalf("confirmed-deleted listener was billed again: share=%+v err=%v", stored, err)
+			}
+		})
+	}
+}

go-backend/internal/http/handler/flow_policy.go

@@ -3,21 +3,36 @@ package handler
 import (
 	"encoding/json"
 	"errors"
+	"fmt"
 	"log"
+	"math"
 	"strconv"
 	"strings"
 	"time"
-
-	"go-backend/internal/store/model"
 )
 
 const bytesPerGB int64 = 1024 * 1024 * 1024
+const bytesPerMiB int64 = 1024 * 1024
+
+func flowLimitBytes(flowGB, flowMiB int64) int64 {
+	if flowMiB > 0 {
+		if flowMiB > math.MaxInt64/bytesPerMiB {
+			return math.MaxInt64
+		}
+		return flowMiB * bytesPerMiB
+	}
+	if flowGB > math.MaxInt64/bytesPerGB {
+		return math.MaxInt64
+	}
+	return flowGB * bytesPerGB
+}
 
 type userTunnelPolicy struct {
 	ID       int64
 	UserID   int64
 	TunnelID int64
 	Flow     int64
+	FlowMiB  int64
 	InFlow   int64
 	OutFlow  int64
 	ExpTime  int64
@@ -32,38 +47,22 @@ type gostConfigSnapshot struct {
 }
 
 type namedConfigItem struct {
-	Name string `json:"name"`
+	Name    string `json:"name"`
+	Limiter string `json:"limiter,omitempty"`
+	Handler *struct {
+		Chain string `json:"chain"`
+	} `json:"handler,omitempty"`
 }
 
 func (h *Handler) processFlowItem(nodeID int64, item flowItem) {
-	serviceName := strings.TrimSpace(item.N)
-	if serviceName == "" || serviceName == "web_api" {
+	if h == nil || h.repo == nil || nodeID <= 0 {
 		return
 	}
-
-	forwardID, userID, userTunnelID, ok := parseFlowServiceIDs(serviceName)
-	if ok {
-		if h.forwardExists(forwardID) {
-			inFlow, outFlow := h.scaleFlowByTunnel(forwardID, item.D, item.U)
-			_ = h.repo.AddFlow(forwardID, userID, userTunnelID, inFlow, outFlow)
-			if quota, quotaErr := h.repo.AddUserQuotaUsage(userID, inFlow+outFlow, time.Now()); quotaErr == nil {
-				h.enforceUserQuotaIfNeeded(userID, quota)
-			}
-			if userTunnelID > 0 {
-				h.enforceFlowPolicies(userID, userTunnelID)
-			}
-		} else if nodeID > 0 {
-			h.sendDeleteOrphanedForwardService(nodeID, serviceName)
-		}
-		h.processPeerShareFlowFromForward(forwardID, nodeID, serviceName, item)
-		return
+	metas, err := h.repo.GetFlowUploadForwardMetas(collectFlowUploadForwardIDs([]flowItem{item}))
+	if err != nil {
+		metas = nil
 	}
-
-	runtimeID, ok := parsePeerShareRuntimeServiceID(serviceName)
-	if !ok {
-		return
-	}
-	h.processPeerShareFlow(runtimeID, item)
+	h.applyFlowUploadBatch(nodeID, h.buildNodeFlowUploadBatch(nodeID, []flowItem{item}, metas), time.Now())
 }
 
 func parseFlowServiceIDs(serviceName string) (int64, int64, int64, bool) {
@@ -138,73 +137,49 @@ func parsePeerShareIDFromFederationTunnelName(tunnelName string) (int64, bool) {
 	return shareID, true
 }
 
-func (h *Handler) processPeerShareFlow(runtimeID int64, item flowItem) {
-	if h == nil || h.repo == nil || runtimeID <= 0 {
+func (h *Handler) processPeerShareFlow(nodeID, runtimeID int64, item flowItem) {
+	if h == nil || h.repo == nil || nodeID <= 0 || runtimeID <= 0 {
 		return
 	}
 	runtime, err := h.repo.GetPeerShareRuntimeByID(runtimeID)
-	if err != nil || runtime == nil || runtime.ShareID <= 0 || runtime.Status != 1 {
+	if err != nil || runtime == nil || runtime.NodeID != nodeID || runtime.Status != 1 {
 		return
 	}
-
-	delta := item.D + item.U
-	if delta <= 0 {
-		return
-	}
-
-	_ = h.repo.AddPeerShareCurrentFlow(runtime.ShareID, delta)
-
-	share, err := h.repo.GetPeerShare(runtime.ShareID)
-	if err != nil || share == nil {
-		return
-	}
-	if !isPeerShareFlowExceeded(share) {
-		return
-	}
-	h.enforcePeerShareFlowLimit(share.ID)
+	h.addPeerShareFlow(nodeID, runtime.ShareID, item.D+item.U)
 }
 
 func (h *Handler) processPeerShareFlowFromForward(forwardID int64, nodeID int64, serviceName string, item flowItem) {
-	if h == nil || h.repo == nil || forwardID <= 0 {
+	if h == nil || h.repo == nil || forwardID <= 0 || nodeID <= 0 {
 		return
 	}
-
-	delta := item.D + item.U
-	if delta <= 0 {
+	// Prefer the reporting node's explicit shared ownership over a coincidentally
+	// equal local forward ID. Never fall back to a service on another node.
+	runtimes, err := h.repo.ListActiveForwardPeerShareRuntimesByNode(nodeID)
+	if err != nil {
 		return
 	}
-
+	for _, runtime := range runtimes {
+		if normalizeForwardRuntimeServiceName(runtime.ServiceName) == normalizeForwardRuntimeServiceName(serviceName) {
+			h.processPeerShareFlowByServiceName(nodeID, serviceName, item)
+			return
+		}
+	}
 	forward, err := h.getForwardRecord(forwardID)
 	if err != nil || forward == nil {
-		// Forward not found in local database - might be a federation port-forward
-		// Try to find by service name in peer_share_runtime
-		h.processPeerShareFlowByServiceName(nodeID, serviceName, item)
+		return
+	}
+	_, userID, _, ok := parseFlowServiceIDs(serviceName)
+	if !ok || userID != forward.UserID {
 		return
 	}
 	tunnelName, err := h.repo.GetTunnelName(forward.TunnelID)
 	if err != nil {
-		h.processPeerShareFlowByServiceName(nodeID, serviceName, item)
 		return
 	}
 	shareID, ok := parsePeerShareIDFromFederationTunnelName(tunnelName)
-	if !ok {
-		h.processPeerShareFlowByServiceName(nodeID, serviceName, item)
-		return
+	if ok {
+		h.addPeerShareFlow(nodeID, shareID, item.D+item.U)
 	}
-
-	if err := h.repo.AddPeerShareCurrentFlow(shareID, delta); err != nil {
-		h.processPeerShareFlowByServiceName(nodeID, serviceName, item)
-		return
-	}
-
-	share, err := h.repo.GetPeerShare(shareID)
-	if err != nil || share == nil {
-		return
-	}
-	if !isPeerShareFlowExceeded(share) {
-		return
-	}
-	h.enforcePeerShareFlowLimit(share.ID)
 }
 
 func normalizeForwardRuntimeServiceName(serviceName string) string {
@@ -219,63 +194,26 @@ func normalizeForwardRuntimeServiceName(serviceName string) string {
 }
 
 func (h *Handler) processPeerShareFlowByServiceName(nodeID int64, serviceName string, item flowItem) {
-	if h == nil || h.repo == nil || strings.TrimSpace(serviceName) == "" {
+	if h == nil || h.repo == nil || nodeID <= 0 || strings.TrimSpace(serviceName) == "" {
 		return
 	}
-
-	delta := item.D + item.U
-	if delta <= 0 {
+	runtimes, err := h.repo.ListActiveForwardPeerShareRuntimesByNode(nodeID)
+	if err != nil {
 		return
 	}
-
-	normalized := normalizeForwardRuntimeServiceName(serviceName)
-	var runtimes []model.PeerShareRuntime
-	var err error
-
-	// Try node-scoped query first if nodeID is valid
-	if nodeID > 0 {
-		runtimes, err = h.repo.ListActiveForwardPeerShareRuntimesByNodeAndServiceName(nodeID, normalized)
-		if err != nil {
+	var shareID int64
+	for _, runtime := range runtimes {
+		if normalizeForwardRuntimeServiceName(runtime.ServiceName) != normalizeForwardRuntimeServiceName(serviceName) {
+			continue
+		}
+		if shareID != 0 {
+			log.Printf("ambiguous peer share runtime service=%s node_id=%d", serviceName, nodeID)
 			return
 		}
-		if len(runtimes) == 0 && normalized != serviceName {
-			runtimes, err = h.repo.ListActiveForwardPeerShareRuntimesByNodeAndServiceName(nodeID, serviceName)
-			if err != nil {
-				return
-			}
-		}
+		shareID = runtime.ShareID
 	}
-
-	// Fallback to global query if node-scoped query returned nothing or nodeID is invalid
-	if len(runtimes) == 0 {
-		runtimes, err = h.repo.ListActiveForwardPeerShareRuntimesByServiceName(normalized)
-		if err != nil {
-			return
-		}
-		if len(runtimes) == 0 && normalized != serviceName {
-			runtimes, err = h.repo.ListActiveForwardPeerShareRuntimesByServiceName(serviceName)
-			if err != nil {
-				return
-			}
-		}
-	}
-
-	if len(runtimes) != 1 {
-		if len(runtimes) > 1 {
-			log.Printf("WARN: ambiguous peer share runtime match for service=%s nodeID=%d count=%d", serviceName, nodeID, len(runtimes))
-		}
-		return
-	}
-	runtime := runtimes[0]
-
-	_ = h.repo.AddPeerShareCurrentFlow(runtime.ShareID, delta)
-
-	matchedShare, err := h.repo.GetPeerShare(runtime.ShareID)
-	if err != nil || matchedShare == nil {
-		return
-	}
-	if isPeerShareFlowExceeded(matchedShare) {
-		h.enforcePeerShareFlowLimit(matchedShare.ID)
+	if shareID > 0 {
+		h.addPeerShareFlow(nodeID, shareID, item.D+item.U)
 	}
 }
 
@@ -283,22 +221,8 @@ func (h *Handler) enforcePeerShareFlowLimit(shareID int64) {
 	if h == nil || h.repo == nil || shareID <= 0 {
 		return
 	}
-	runtimes, err := h.repo.ListActivePeerShareRuntimesByShareID(shareID)
-	if err != nil || len(runtimes) == 0 {
-		return
-	}
-
-	now := time.Now().UnixMilli()
-	for _, runtime := range runtimes {
-		if h.wsServer != nil && runtime.Applied == 1 {
-			if strings.TrimSpace(runtime.ServiceName) != "" {
-				_, _ = h.sendNodeCommand(runtime.NodeID, "DeleteService", map[string]interface{}{"services": []string{runtime.ServiceName}}, false, true)
-			}
-			if strings.TrimSpace(runtime.Role) == "middle" && strings.TrimSpace(runtime.ChainName) != "" {
-				_, _ = h.sendNodeCommand(runtime.NodeID, "DeleteChains", map[string]interface{}{"chain": runtime.ChainName}, false, true)
-			}
-		}
-		_ = h.repo.MarkPeerShareRuntimeReleased(runtime.ID, now)
+	if err := h.cleanupPeerShareRuntimes(shareID); err != nil {
+		log.Printf("peer share quota cleanup pending share_id=%d err=%v", shareID, err)
 	}
 }
 
@@ -358,7 +282,7 @@ func (h *Handler) ensureUserTunnelForwardAllowed(userID int64, tunnelID int64, n
 		return errors.New("账号已过期")
 	}
 
-	flowLimit := user.Flow * bytesPerGB
+	flowLimit := flowLimitBytes(user.Flow, user.FlowMiB)
 	current := user.InFlow + user.OutFlow
 	if flowLimit < current {
 		return errors.New("流量已超额，禁止开启转发")
@@ -400,7 +324,7 @@ func (h *Handler) ensureUserTunnelForwardAllowed(userID int64, tunnelID int64, n
 		return errors.New("该隧道已过期")
 	}
 
-	utFlowLimit := policy.Flow * bytesPerGB
+	utFlowLimit := flowLimitBytes(policy.Flow, policy.FlowMiB)
 	utCurrent := policy.InFlow + policy.OutFlow
 	if utCurrent >= utFlowLimit {
 		return errors.New("该隧道流量已超额，禁止开启转发")
@@ -425,7 +349,7 @@ func (h *Handler) shouldPauseUser(userID int64, now int64) bool {
 		return false
 	}
 
-	flowLimit := user.Flow * bytesPerGB
+	flowLimit := flowLimitBytes(user.Flow, user.FlowMiB)
 	current := user.InFlow + user.OutFlow
 	if flowLimit < current {
 		return true
@@ -441,7 +365,7 @@ func shouldPauseUserTunnel(policy *userTunnelPolicy, now int64) bool {
 		return false
 	}
 
-	flowLimit := policy.Flow * bytesPerGB
+	flowLimit := flowLimitBytes(policy.Flow, policy.FlowMiB)
 	current := policy.InFlow + policy.OutFlow
 	if current >= flowLimit {
 		return true
@@ -465,11 +389,53 @@ func (h *Handler) getUserTunnelPolicy(userTunnelID int64) (*userTunnelPolicy, er
 	}
 	return &userTunnelPolicy{
 		ID: ut.ID, UserID: ut.UserID, TunnelID: ut.TunnelID,
-		Flow: ut.Flow, InFlow: ut.InFlow, OutFlow: ut.OutFlow,
+		Flow: ut.Flow, FlowMiB: ut.FlowMiB, InFlow: ut.InFlow, OutFlow: ut.OutFlow,
 		ExpTime: ut.ExpTime, Status: ut.Status, Num: ut.Num,
 	}, nil
 }
 
+// disableUserAccess retains unconfirmed forwards as active so a repeated disable
+// can retry them. Login and tunnel access remain disabled when a node is offline.
+func (h *Handler) disableUserAccess(userID int64, now int64) error {
+	permissionErr := h.repo.DisableUserTunnels(userID)
+	forwards, err := h.listActiveForwardsByUser(userID)
+	if err != nil {
+		return errors.Join(permissionErr, err)
+	}
+	errs := []error{permissionErr}
+	for i := range forwards {
+		forward := &forwards[i]
+		nftMode, entryNodeIDs, pauseErr := h.tunnelUsesNftables(forward.TunnelID)
+		if pauseErr == nil {
+			if nftMode {
+				// Exclude the rule from the desired plan before marking its pause
+				// confirmed. A failed SSH apply must remain eligible for retry.
+				pauseErr = h.syncNftablesNode(entryNodeIDs[0], forward.ID)
+				if pauseErr != nil {
+					pauseErr = h.nodeCommandError(entryNodeIDs[0], pauseErr)
+				}
+			} else {
+				// Missing services are already stopped. Self-healing would recreate
+				// services on every entry and could restart one already paused.
+				pauseErr = h.controlForwardServicesWithOptions(forward, "PauseService", forwardServiceControlOptions{
+					tolerateNotFound: true,
+					tolerateOffline:  false,
+					allowSelfHeal:    false,
+					continueOnError:  true,
+				})
+			}
+		}
+		if pauseErr != nil {
+			errs = append(errs, fmt.Errorf("转发 %d 暂停失败: %w", forward.ID, pauseErr))
+			continue
+		}
+		if err := h.repo.UpdateForwardStatus(forward.ID, 0, now); err != nil {
+			errs = append(errs, err)
+		}
+	}
+	return errors.Join(errs...)
+}
+
 func (h *Handler) pauseUserForwards(userID int64, now int64) {
 	forwards, err := h.listActiveForwardsByUser(userID)
 	if err != nil {
@@ -515,43 +481,102 @@ func (h *Handler) cleanNodeConfigs(nodeID int64, rawConfig string) {
 		return
 	}
 
-	h.cleanOrphanedServices(nodeID, snapshot.Services)
-	h.cleanOrphanedChains(nodeID, snapshot.Chains)
-	h.cleanOrphanedLimiters(nodeID, snapshot.Limiters)
-}
-
-func (h *Handler) cleanOrphanedServices(nodeID int64, services []namedConfigItem) {
-	runtimeServiceNames, err := h.repo.ListActiveForwardPeerShareRuntimeServiceNamesByNode(nodeID)
+	protection, err := h.loadForwardServiceProtection(nodeID)
 	if err != nil {
 		return
 	}
-	minUpdatedTime := time.Now().Add(-10 * time.Minute).UnixMilli()
-	hasUnboundForwardPeerRuntime, err := h.repo.HasRecentUnboundForwardPeerShareRuntimeOnNode(nodeID, minUpdatedTime)
-	if err != nil {
-		hasUnboundForwardPeerRuntime = false
+	h.cleanOrphanedServicesWithProtection(nodeID, snapshot.Services, protection)
+	// Dependencies are sent before services. A pending shared reservation may
+	// therefore have chains/limiters that are not referenced in this snapshot yet.
+	if protection.unbound {
+		return
 	}
-	runtimeServiceSet := make(map[string]struct{}, len(runtimeServiceNames))
-	for _, serviceName := range runtimeServiceNames {
-		serviceName = strings.TrimSpace(serviceName)
+	chainsInUse := make(map[string]struct{})
+	limitersInUse := make(map[string]struct{})
+	for _, service := range snapshot.Services {
+		if service.Handler != nil {
+			if chain := strings.TrimSpace(service.Handler.Chain); chain != "" {
+				chainsInUse[chain] = struct{}{}
+			}
+		}
+		for _, limiter := range strings.Split(service.Limiter, ",") {
+			if limiter = strings.TrimSpace(limiter); limiter != "" {
+				limitersInUse[limiter] = struct{}{}
+			}
+		}
+	}
+	// Keep dependencies referenced by the reported services, even when their
+	// IDs belong to a different panel. Orphan dependencies can be collected on
+	// the next report after their services have actually disappeared.
+	h.cleanOrphanedChains(nodeID, snapshot.Chains, chainsInUse)
+	h.cleanOrphanedLimiters(nodeID, snapshot.Limiters, limitersInUse)
+}
+
+type forwardServiceProtection struct {
+	sharedNames map[string]struct{}
+	unbound     bool
+}
+
+// Shared forward IDs belong to another panel and need not exist in our forward
+// table. Use the same node-scoped ownership check for config and flow reports.
+func (h *Handler) loadForwardServiceProtection(nodeID int64) (forwardServiceProtection, error) {
+	protection := forwardServiceProtection{sharedNames: make(map[string]struct{})}
+	// Read names and pending bindings in one snapshot, so a concurrent bind
+	// cannot fall between two queries and disappear from both protections.
+	runtimes, err := h.repo.ListActiveForwardPeerShareRuntimesByNode(nodeID)
+	if err != nil {
+		return protection, err
+	}
+	minUpdatedTime := time.Now().Add(-10 * time.Minute).UnixMilli()
+	for _, runtime := range runtimes {
+		serviceName := normalizeForwardRuntimeServiceName(runtime.ServiceName)
 		if serviceName == "" {
+			if runtime.Applied == 0 && runtime.UpdatedTime >= minUpdatedTime {
+				protection.unbound = true
+			}
 			continue
 		}
-		runtimeServiceSet[serviceName] = struct{}{}
+		protection.sharedNames[serviceName] = struct{}{}
 	}
+	resources, err := h.repo.ListPeerShareResourcesByNode(nodeID)
+	if err != nil {
+		return protection, err
+	}
+	for _, resource := range resources {
+		if base := normalizeForwardRuntimeServiceName(resource.LegacyServiceBase); base != "" {
+			protection.sharedNames[base] = struct{}{}
+		}
+	}
+	return protection, nil
+}
 
+func (p forwardServiceProtection) preserves(serviceName string) bool {
+	_, shared := p.sharedNames[normalizeForwardRuntimeServiceName(serviceName)]
+	return shared || p.unbound
+}
+
+func (h *Handler) cleanOrphanedServices(nodeID int64, services []namedConfigItem) {
+	if h == nil || h.repo == nil || nodeID <= 0 {
+		return
+	}
+	protection, err := h.loadForwardServiceProtection(nodeID)
+	if err != nil {
+		// A failed ownership lookup must never authorize deletion.
+		return
+	}
+	h.cleanOrphanedServicesWithProtection(nodeID, services, protection)
+}
+
+func (h *Handler) cleanOrphanedServicesWithProtection(nodeID int64, services []namedConfigItem, protection forwardServiceProtection) {
 	for _, item := range services {
 		name := strings.TrimSpace(item.Name)
 		if name == "" || name == "web_api" {
 			continue
 		}
-		if strings.HasPrefix(name, "fed_svc_") {
+		if strings.HasPrefix(name, "fed_svc_") || strings.HasPrefix(name, "peer-share-") {
 			continue
 		}
-		normalizedName := normalizeForwardRuntimeServiceName(name)
-		if _, ok := runtimeServiceSet[normalizedName]; ok {
-			continue
-		}
-		if _, ok := runtimeServiceSet[name]; ok {
+		if _, ok := protection.sharedNames[normalizeForwardRuntimeServiceName(name)]; ok {
 			continue
 		}
 
@@ -564,15 +589,9 @@ func (h *Handler) cleanOrphanedServices(nodeID int64, services []namedConfigItem
 			continue
 		}
 
-		if len(parts) >= 3 {
-			forwardID, err := strconv.ParseInt(parts[0], 10, 64)
-			if err == nil && forwardID > 0 && hasUnboundForwardPeerRuntime {
-				continue
-			}
-			if err == nil && forwardID > 0 && !h.forwardExists(forwardID) {
-				_, _ = h.sendNodeCommand(nodeID, "DeleteService", map[string]interface{}{"services": []string{name, parts[0] + "_" + parts[1] + "_" + parts[2], parts[0] + "_" + parts[1] + "_" + parts[2] + "_tcp", parts[0] + "_" + parts[1] + "_" + parts[2] + "_udp"}}, false, true)
-				continue
-			}
+		if _, _, _, ok := parseFlowServiceIDs(name); ok {
+			h.deleteOrphanedForwardService(nodeID, name, protection)
+			continue
 		}
 		suffix := parts[len(parts)-1]
 
@@ -591,23 +610,17 @@ func (h *Handler) cleanOrphanedServices(nodeID int64, services []namedConfigItem
 				}
 				continue
 			}
-			forwardID, err := strconv.ParseInt(parts[0], 10, 64)
-			if err == nil && forwardID > 0 && hasUnboundForwardPeerRuntime {
-				continue
-			}
-			if err != nil || forwardID <= 0 || h.forwardExists(forwardID) {
-				continue
-			}
-			base := strings.TrimSuffix(name, "_tcp")
-			_, _ = h.sendNodeCommand(nodeID, "DeleteService", map[string]interface{}{"services": []string{base + "_tcp", base + "_udp"}}, false, true)
 		}
 	}
 }
 
-func (h *Handler) cleanOrphanedChains(nodeID int64, chains []namedConfigItem) {
+func (h *Handler) cleanOrphanedChains(nodeID int64, chains []namedConfigItem, inUse map[string]struct{}) {
 	for _, item := range chains {
 		name := strings.TrimSpace(item.Name)
-		if name == "" {
+		if name == "" || strings.HasPrefix(name, "fed_chain_") || strings.HasPrefix(name, "peer-share-") {
+			continue
+		}
+		if _, ok := inUse[name]; ok {
 			continue
 		}
 
@@ -616,17 +629,28 @@ func (h *Handler) cleanOrphanedChains(nodeID int64, chains []namedConfigItem) {
 			continue
 		}
 		tunnelID, err := strconv.ParseInt(name[idx+1:], 10, 64)
-		if err != nil || tunnelID <= 0 || h.tunnelExists(tunnelID) {
+		if err != nil || tunnelID <= 0 {
+			continue
+		}
+		exists, err := h.repo.TunnelExists(tunnelID)
+		if err != nil || exists {
 			continue
 		}
 		_, _ = h.sendNodeCommand(nodeID, "DeleteChains", map[string]interface{}{"chain": name}, false, true)
 	}
 }
 
-func (h *Handler) cleanOrphanedLimiters(nodeID int64, limiters []namedConfigItem) {
+func (h *Handler) cleanOrphanedLimiters(nodeID int64, limiters []namedConfigItem, inUse map[string]struct{}) {
 	for _, item := range limiters {
 		name := strings.TrimSpace(item.Name)
-		if name == "" || h.speedLimiterExists(name) {
+		if name == "" || strings.HasPrefix(name, "peer-share-") {
+			continue
+		}
+		if _, ok := inUse[name]; ok {
+			continue
+		}
+		exists, err := h.lookupSpeedLimiter(name)
+		if err != nil || exists {
 			continue
 		}
 		_, _ = h.sendNodeCommand(nodeID, "DeleteLimiters", map[string]interface{}{"limiter": name}, false, true)
@@ -644,40 +668,78 @@ func (h *Handler) forwardExists(forwardID int64) bool {
 }
 
 func (h *Handler) sendDeleteOrphanedForwardService(nodeID int64, serviceName string) {
+	h.sendDeleteOrphanedForwardServices(nodeID, []string{serviceName})
+}
+
+func (h *Handler) sendDeleteOrphanedForwardServices(nodeID int64, serviceNames []string) {
+	if h == nil || h.repo == nil || nodeID <= 0 || len(serviceNames) == 0 {
+		return
+	}
+	protection, err := h.loadForwardServiceProtection(nodeID)
+	if err != nil {
+		return
+	}
+	seen := make(map[string]struct{}, len(serviceNames))
+	for _, serviceName := range serviceNames {
+		serviceName = normalizeForwardRuntimeServiceName(serviceName)
+		if _, ok := seen[serviceName]; ok {
+			continue
+		}
+		seen[serviceName] = struct{}{}
+		h.deleteOrphanedForwardService(nodeID, serviceName, protection)
+	}
+}
+
+func (h *Handler) deleteOrphanedForwardService(nodeID int64, serviceName string, protection forwardServiceProtection) {
+	forwardID, _, _, ok := parseFlowServiceIDs(serviceName)
+	if !ok || protection.preserves(serviceName) {
+		return
+	}
 	parts := strings.Split(serviceName, "_")
-	if len(parts) < 3 {
-		return
-	}
-	forwardID, err := strconv.ParseInt(parts[0], 10, 64)
-	if err != nil || forwardID <= 0 {
-		return
-	}
 	base := parts[0] + "_" + parts[1] + "_" + parts[2]
+	// Parsing accepts legacy suffixes, while deletion targets the entire base
+	// family. Verify the actual targets cannot include a protected share.
+	if protection.preserves(base) {
+		return
+	}
+	// Batch metadata can be missing after a read failure, or stale by the time
+	// cleanup runs. Confirm absence before issuing a destructive command.
+	exists, err := h.repo.ForwardExists(forwardID)
+	if err != nil || exists {
+		return
+	}
 	_, _ = h.sendNodeCommand(nodeID, "DeleteService", map[string]interface{}{
-		"services": []string{base + "_tcp", base + "_udp"},
+		"services": buildForwardServiceDeleteNames([]string{base}),
 	}, false, true)
 }
 
 func (h *Handler) speedLimiterExists(name string) bool {
+	exists, _ := h.lookupSpeedLimiter(name)
+	return exists
+}
+
+func (h *Handler) lookupSpeedLimiter(name string) (bool, error) {
 	name = strings.TrimSpace(name)
 	if name == "" {
-		return false
+		return false, nil
 	}
 
 	const forwardRulePrefix = "rule_traffic_limit_"
 	if strings.HasPrefix(name, forwardRulePrefix) {
 		forwardID, err := strconv.ParseInt(strings.TrimPrefix(name, forwardRulePrefix), 10, 64)
 		if err != nil || forwardID <= 0 {
-			return false
+			return false, nil
 		}
 		forward, err := h.getForwardRecord(forwardID)
-		return err == nil && forward != nil && forward.IPSpeedID.Valid && forward.IPSpeedID.Int64 > 0
+		if errors.Is(err, errForwardNotFound) {
+			return false, nil
+		}
+		return forward != nil && forward.IPSpeedID.Valid && forward.IPSpeedID.Int64 > 0, err
 	}
 
 	id, err := strconv.ParseInt(name, 10, 64)
 	if err != nil || id <= 0 {
-		return false
+		return false, nil
 	}
-	ok, _ := h.repo.SpeedLimitExists(id)
-	return ok
+	return h.repo.SpeedLimitExists(id)
 }

go-backend/internal/http/handler/flow_policy_federation_test.go

@@ -10,11 +10,8 @@ import (
 )
 
 func TestProcessFlowItemTracksPeerShareFlowAndEnforcesLimit(t *testing.T) {
-	r, err := repo.Open(filepath.Join(t.TempDir(), "panel.db"))
-	if err != nil {
-		t.Fatalf("open repo: %v", err)
-	}
-	defer r.Close()
+	a := newCleanupAgent(t)
+	r := a.h.repo
 
 	now := time.Now().UnixMilli()
 	if err := r.CreatePeerShare(&repo.PeerShare{
@@ -43,7 +40,7 @@ func TestProcessFlowItemTracksPeerShareFlowAndEnforcesLimit(t *testing.T) {
 		t.Fatalf("insert peer_share_runtime: %v", err)
 	}
 
-	h := &Handler{repo: r}
+	h := a.h
 	h.processFlowItem(1, flowItem{N: "fed_svc_17", U: 1200, D: 900})
 
 	updatedShare, err := r.GetPeerShare(share.ID)
@@ -120,6 +117,9 @@ func TestProcessFlowItemTracksPeerShareFlowForFederationPortForward(t *testing.T
 	}
 
 	h := &Handler{repo: r}
+	if err := r.DB().Exec("INSERT INTO forward_port(forward_id, node_id, port) VALUES(20, 1, 30001)").Error; err != nil {
+		t.Fatal(err)
+	}
 	h.processFlowItem(1, flowItem{N: "20_2_10", U: 120, D: 80})
 
 	updatedShare, err := r.GetPeerShare(share.ID)

go-backend/internal/http/handler/flow_upload_batch.go

@@ -23,6 +23,7 @@ type flowUploadBatch struct {
 	orphanServices        map[string]struct{}
 	peerShareForwardItems map[string]flowItem
 	peerShareRuntimeItems map[int64]flowItem
+	peerShareUsage        map[int64]int64
 }
 
 func (h *Handler) buildFlowUploadBatch(items []flowItem, metas map[int64]repo.FlowUploadForwardMeta) flowUploadBatch {
@@ -65,6 +66,9 @@ func (h *Handler) buildFlowUploadBatch(items []flowItem, metas map[int64]repo.Fl
 			batch.orphanServices[serviceName] = struct{}{}
 			continue
 		}
+		// Local accounting uses database ownership, not foreign IDs embedded in
+		// a service name (including stale user-tunnel IDs after reassignment).
+		userID, userTunnelID = meta.UserID, meta.UserTunnelID
 
 		raw := batch.forwardTraffic[forwardID]
 		raw.bytesIn += item.D
@@ -120,8 +124,12 @@ func (h *Handler) applyFlowUploadBatch(nodeID int64, batch flowUploadBatch, now
 		}
 		h.enforceFlowPolicies(target.UserID, target.UserTunnelID)
 	}
-	for serviceName := range batch.orphanServices {
-		h.sendDeleteOrphanedForwardService(nodeID, serviceName)
+	if len(batch.orphanServices) > 0 {
+		serviceNames := make([]string, 0, len(batch.orphanServices))
+		for serviceName := range batch.orphanServices {
+			serviceNames = append(serviceNames, serviceName)
+		}
+		h.sendDeleteOrphanedForwardServices(nodeID, serviceNames)
 	}
 	for serviceName, item := range batch.peerShareForwardItems {
 		forwardID, _, _, ok := parseFlowServiceIDs(serviceName)
@@ -130,7 +138,10 @@ func (h *Handler) applyFlowUploadBatch(nodeID int64, batch flowUploadBatch, now
 		}
 	}
 	for runtimeID, item := range batch.peerShareRuntimeItems {
-		h.processPeerShareFlow(runtimeID, item)
+		h.processPeerShareFlow(nodeID, runtimeID, item)
+	}
+	for shareID, delta := range batch.peerShareUsage {
+		h.addPeerShareFlow(nodeID, shareID, delta)
 	}
 }
 

go-backend/internal/http/handler/flow_upload_batch_test.go

@@ -14,6 +14,8 @@ func TestBuildFlowUploadBatchAggregatesForwardQuotaPeerShareAndCleanupTargets(t
 	metas := map[int64]repo.FlowUploadForwardMeta{
 		20: {
 			ForwardID:    20,
+			UserID:       2,
+			UserTunnelID: 10,
 			TunnelID:     1,
 			TrafficRatio: 2,
 			TunnelFlow:   3,

go-backend/internal/http/handler/handler.go

@@ -39,8 +39,14 @@ type Handler struct {
 	healthCheck     *health.Checker
 	nftablesManager nftablesRuntimeManager
 
-	captchaMu     sync.Mutex
-	captchaTokens map[string]int64
+	tunnelLifecycleMu    sync.Mutex
+	tunnelLifecycleLocks map[int64]*tunnelLifecycleLock
+
+	peerResourceMu sync.Mutex
+	captchaMu      sync.Mutex
+	captchaTokens  map[string]int64
+	passkeyMu      sync.Mutex
+	passkeyPending map[string]passkeyCeremony
 
 	jobsMu              sync.Mutex
 	jobsCancel          context.CancelFunc
@@ -49,12 +55,13 @@ type Handler struct {
 	fingerprintMu       sync.Mutex
 	licenseValidationMu sync.Mutex
 
-	upgradeMu                sync.Mutex
-	systemUpgradeMu          sync.Mutex
-	pendingUpgradeRedeploy   map[int64]struct{}
-	nodeOnlineRedeployAt     map[int64]time.Time
-	nodeOnlineRedeployQueued map[int64]struct{}
-	nodeOnlineRedeploying    map[int64]struct{}
+	upgradeMu                   sync.Mutex
+	systemUpgradeMu             sync.Mutex
+	pendingUpgradeRedeploy      map[int64]struct{}
+	nodeOnlineRedeployAt        map[int64]time.Time
+	nodeOnlineRedeployQueued    map[int64]struct{}
+	nodeOnlineRedeploying       map[int64]struct{}
+	nodeLocalRuntimeRetryQueued map[int64]struct{}
 
 	qualityProber *tunnelQualityProber
 	bestExit      *bestExitManager
@@ -114,6 +121,7 @@ func New(repo *repo.Repository, jwtSecret string) *Handler {
 		healthCheck:              nil,
 		nftablesManager:          runtimenft.NewManager(nil),
 		captchaTokens:            make(map[string]int64),
+		passkeyPending:           make(map[string]passkeyCeremony),
 		pendingUpgradeRedeploy:   make(map[int64]struct{}),
 		nodeOnlineRedeployAt:     make(map[int64]time.Time),
 		nodeOnlineRedeployQueued: make(map[int64]struct{}),
@@ -155,6 +163,13 @@ func (h *Handler) GetUserAuthState(userID int64) (*auth.UserAuthState, error) {
 
 func (h *Handler) Register(mux *http.ServeMux) {
 	mux.HandleFunc("/api/v1/user/login", h.login)
+	mux.HandleFunc("/api/v1/user/passkey/status", h.passkeyStatus)
+	mux.HandleFunc("/api/v1/user/passkey/login/begin", h.passkeyLoginBegin)
+	mux.HandleFunc("/api/v1/user/passkey/login/finish", h.passkeyLoginFinish)
+	mux.HandleFunc("/api/v1/user/passkey/register/begin", h.passkeyRegisterBegin)
+	mux.HandleFunc("/api/v1/user/passkey/register/finish", h.passkeyRegisterFinish)
+	mux.HandleFunc("/api/v1/user/passkey/list", h.passkeyList)
+	mux.HandleFunc("/api/v1/user/passkey/delete", h.passkeyDelete)
 	mux.HandleFunc("/api/v1/user/list", h.userList)
 	mux.HandleFunc("/api/v1/user/create", h.userCreate)
 	mux.HandleFunc("/api/v1/user/update", h.userUpdate)
@@ -171,6 +186,7 @@ func (h *Handler) Register(mux *http.ServeMux) {
 	mux.HandleFunc("/api/v1/system/version", h.systemVersion)
 	mux.HandleFunc("/api/v1/system/check-updates", h.systemCheckUpdates)
 	mux.HandleFunc("/api/v1/system/upgrade", h.systemUpgrade)
+	mux.HandleFunc("/api/v1/system/upgrade/status", h.systemUpgradeStatus)
 	mux.HandleFunc("/api/v1/license/activate", h.licenseActivate)
 	mux.HandleFunc("/api/v1/backup/export", h.backupExport)
 	mux.HandleFunc("/api/v1/backup/import", h.backupImport)
@@ -719,6 +735,7 @@ func (h *Handler) userTunnelList(w http.ResponseWriter, r *http.Request) {
 			"tunnelName":     t.TunnelName,
 			"status":         t.Status,
 			"flow":           t.Flow,
+			"flowMiB":        t.FlowMiB,
 			"num":            t.Num,
 			"expTime":        t.ExpTime,
 			"flowResetTime":  t.FlowResetTime,
@@ -875,7 +892,7 @@ func (h *Handler) flowUpload(w http.ResponseWriter, r *http.Request) {
 				log.Printf("flow upload metadata lookup failed node_id=%d err=%v", node.ID, metaErr)
 				metas = map[int64]repo.FlowUploadForwardMeta{}
 			}
-			batch := h.buildFlowUploadBatch(items, metas)
+			batch := h.buildNodeFlowUploadBatch(node.ID, items, metas)
 			h.recordTunnelMetricsFromForwardBatch(node.ID, batch.forwardTraffic, metas, now.UnixMilli())
 			h.applyFlowUploadBatch(node.ID, batch, now)
 		}
@@ -1213,6 +1230,7 @@ func (h *Handler) userPackage(w http.ResponseWriter, r *http.Request) {
 			"tunnelName":     t.TunnelName,
 			"tunnelFlow":     t.TunnelFlow,
 			"flow":           t.Flow,
+			"flowMiB":        t.FlowMiB,
 			"inFlow":         t.InFlow,
 			"outFlow":        t.OutFlow,
 			"num":            t.Num,
@@ -1262,6 +1280,7 @@ func (h *Handler) userPackage(w http.ResponseWriter, r *http.Request) {
 			"user":          user.User,
 			"status":        user.Status,
 			"flow":          user.Flow,
+			"flowMiB":       user.FlowMiB,
 			"inFlow":        user.InFlow,
 			"outFlow":       user.OutFlow,
 			"num":           user.Num,

go-backend/internal/http/handler/jobs.go

@@ -21,7 +21,7 @@ func (h *Handler) StartBackgroundJobs() {
 	ctx, cancel := context.WithCancel(context.Background())
 	h.jobsCancel = cancel
 	h.jobsStarted = true
-	h.jobsWG.Add(8)
+	h.jobsWG.Add(9)
 	h.jobsMu.Unlock()
 
 	go h.runHourlyStatsLoop(ctx)
@@ -32,6 +32,52 @@ func (h *Handler) StartBackgroundJobs() {
 	go h.runTunnelQualityProber(ctx)
 	go h.runValidateLicenseJob(ctx)
 	go h.runNftablesTrafficCollectLoop(ctx)
+	go h.runFederationCleanupRetryLoop(ctx)
+}
+
+func (h *Handler) runFederationCleanupRetryLoop(ctx context.Context) {
+	defer h.jobsWG.Done()
+	ticker := time.NewTicker(30 * time.Second)
+	defer ticker.Stop()
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		default:
+		}
+		if err := h.retryPendingFederationRuntimeCleanup(); err != nil {
+			log.Printf("federation cleanup remains pending: %v", err)
+		}
+		if err := h.retryPendingTunnelRuntimeCleanup(); err != nil {
+			log.Printf("tunnel runtime cleanup remains pending: %v", err)
+		}
+		h.retryPendingPeerShareOperations()
+		select {
+		case <-ctx.Done():
+			return
+		case <-ticker.C:
+		}
+	}
+}
+
+func (h *Handler) retryPendingPeerShareOperations() {
+	nodeIDs, err := h.repo.ListPendingPeerShareNodeIDs()
+	if err != nil {
+		log.Printf("peer share pending operation lookup failed: %v", err)
+		return
+	}
+	for _, nodeID := range nodeIDs {
+		node, err := h.repo.GetNodeByID(nodeID)
+		if err != nil || node == nil || node.Status != 1 {
+			continue
+		}
+		if err := h.retryPendingPeerShareResourcesOnNode(nodeID); err != nil {
+			log.Printf("peer share resource retry failed node_id=%d err=%v", nodeID, err)
+		}
+		if err := h.retryPendingPeerShareRoleRuntimesOnNode(nodeID); err != nil {
+			log.Printf("peer share role retry failed node_id=%d err=%v", nodeID, err)
+		}
+	}
 }
 
 func (h *Handler) runValidateLicenseJob(ctx context.Context) {

go-backend/internal/http/handler/nftables_runtime.go

@@ -7,6 +7,7 @@ import (
 	"fmt"
 	"net"
 	"net/http"
+	"slices"
 	"strings"
 	"time"
 
@@ -150,7 +151,7 @@ func (h *Handler) validateNftablesTunnelStateTx(tx *gorm.DB, entryNodeIDs []int6
 	return nil
 }
 
-func (h *Handler) buildNftablesNodePlan(nodeID int64) (runtimenft.NodePlan, *model.NodeSSHConfig, error) {
+func (h *Handler) buildNftablesNodePlan(nodeID int64, excludedForwardIDs ...int64) (runtimenft.NodePlan, *model.NodeSSHConfig, error) {
 	cfg, err := h.repo.GetNodeSSHConfig(nodeID)
 	if err != nil {
 		return runtimenft.NodePlan{}, nil, err
@@ -162,6 +163,9 @@ func (h *Handler) buildNftablesNodePlan(nodeID int64) (runtimenft.NodePlan, *mod
 	plan := runtimenft.NodePlan{NodeID: nodeID, Rules: make([]runtimenft.Rule, 0, len(forwards))}
 	for i := range forwards {
 		forward := &forwards[i]
+		if slices.Contains(excludedForwardIDs, forward.ID) {
+			continue
+		}
 		tunnel, err := h.getTunnelRecord(forward.TunnelID)
 		if err != nil || tunnel == nil || tunnel.Status != 1 {
 			continue
@@ -201,11 +205,11 @@ func (h *Handler) buildNftablesNodePlan(nodeID int64) (runtimenft.NodePlan, *mod
 	return plan, cfg, nil
 }
 
-func (h *Handler) syncNftablesNode(nodeID int64) error {
+func (h *Handler) syncNftablesNode(nodeID int64, excludedForwardIDs ...int64) error {
 	if h == nil || h.repo == nil {
 		return errors.New("handler not initialized")
 	}
-	plan, cfgModel, err := h.buildNftablesNodePlan(nodeID)
+	plan, cfgModel, err := h.buildNftablesNodePlan(nodeID, excludedForwardIDs...)
 	if err != nil {
 		return err
 	}

go-backend/internal/http/handler/passkey.go

@@ -0,0 +1,440 @@
+package handler
+
+import (
+	"bytes"
+	"crypto/rand"
+	"encoding/base64"
+	"encoding/binary"
+	"encoding/json"
+	"net/http"
+	"net/url"
+	"os"
+	"strings"
+	"time"
+
+	"go-backend/internal/auth"
+	"go-backend/internal/http/response"
+	"go-backend/internal/security"
+	"go-backend/internal/store/model"
+
+	"github.com/go-webauthn/webauthn/protocol"
+	"github.com/go-webauthn/webauthn/webauthn"
+)
+
+const passkeyTTL = 2 * time.Minute
+
+type passkeyCeremony struct {
+	userID  int64
+	kind    string
+	origin  string
+	session webauthn.SessionData
+}
+
+type passkeyUser struct {
+	id          int64
+	name        string
+	credentials []webauthn.Credential
+}
+
+func (u passkeyUser) WebAuthnID() []byte {
+	id := make([]byte, 8)
+	binary.BigEndian.PutUint64(id, uint64(u.id))
+	return id
+}
+func (u passkeyUser) WebAuthnName() string                       { return u.name }
+func (u passkeyUser) WebAuthnDisplayName() string                { return u.name }
+func (u passkeyUser) WebAuthnCredentials() []webauthn.Credential { return u.credentials }
+
+func passkeyConfig() (*webauthn.WebAuthn, string) {
+	raw := strings.TrimSpace(os.Getenv("FLVX_WEBAUTHN_ORIGIN"))
+	u, err := url.Parse(raw)
+	if err != nil || u == nil || u.Host == "" || u.User != nil || u.Path != "" || u.RawQuery != "" || u.Fragment != "" {
+		return nil, ""
+	}
+	host := u.Hostname()
+	if host == "" || strings.ContainsAny(host, " /\\") || (u.Scheme != "https" && !(u.Scheme == "http" && (host == "localhost" || host == "127.0.0.1"))) {
+		return nil, ""
+	}
+	origin := u.Scheme + "://" + u.Host
+	wa, err := webauthn.New(&webauthn.Config{
+		RPID:                   host,
+		RPDisplayName:          "FLVX",
+		RPOrigins:              []string{origin},
+		AuthenticatorSelection: protocol.AuthenticatorSelection{UserVerification: protocol.VerificationRequired, ResidentKey: protocol.ResidentKeyRequirementRequired},
+		Timeouts: webauthn.TimeoutsConfig{
+			Login:        webauthn.TimeoutConfig{Enforce: true, Timeout: passkeyTTL},
+			Registration: webauthn.TimeoutConfig{Enforce: true, Timeout: passkeyTTL},
+		},
+	})
+	if err != nil {
+		return nil, ""
+	}
+	return wa, origin
+}
+
+func (h *Handler) passkeyStatus(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		response.WriteJSON(w, response.ErrDefault("请求失败"))
+		return
+	}
+	wa, _ := passkeyConfig()
+	response.WriteJSON(w, response.OK(map[string]bool{"enabled": wa != nil}))
+}
+
+func (h *Handler) putPasskeyCeremony(c passkeyCeremony) (string, bool) {
+	buf := make([]byte, 32)
+	if _, err := rand.Read(buf); err != nil {
+		return "", false
+	}
+	id := base64.RawURLEncoding.EncodeToString(buf)
+	h.passkeyMu.Lock()
+	defer h.passkeyMu.Unlock()
+	for k, v := range h.passkeyPending {
+		if time.Now().After(v.session.Expires) {
+			delete(h.passkeyPending, k)
+		}
+	}
+	if len(h.passkeyPending) >= 1000 {
+		return "", false
+	}
+	h.passkeyPending[id] = c
+	return id, true
+}
+
+func (h *Handler) takePasskeyCeremony(id, kind, origin string, userID int64) (webauthn.SessionData, bool) {
+	h.passkeyMu.Lock()
+	c, ok := h.passkeyPending[id]
+	delete(h.passkeyPending, id)
+	h.passkeyMu.Unlock()
+	if !ok || c.kind != kind || c.origin != origin || c.userID != userID || time.Now().After(c.session.Expires) {
+		return webauthn.SessionData{}, false
+	}
+	return c.session, true
+}
+
+func (h *Handler) takePasskeyLoginCeremony(id, origin string) (passkeyCeremony, bool) {
+	h.passkeyMu.Lock()
+	c, ok := h.passkeyPending[id]
+	delete(h.passkeyPending, id)
+	h.passkeyMu.Unlock()
+	if !ok || c.kind != "login-discoverable" || c.origin != origin || time.Now().After(c.session.Expires) {
+		return passkeyCeremony{}, false
+	}
+	return c, true
+}
+
+func (h *Handler) loadPasskeyUser(userID int64) (passkeyUser, error) {
+	user, err := h.repo.GetUserByID(userID)
+	if err != nil || user == nil || user.Status != 1 {
+		return passkeyUser{}, errInvalidPasskey
+	}
+	rows, err := h.repo.ListPasskeys(userID)
+	if err != nil {
+		return passkeyUser{}, err
+	}
+	u := passkeyUser{id: user.ID, name: user.User}
+	for _, row := range rows {
+		var credential webauthn.Credential
+		if err := json.Unmarshal([]byte(row.CredentialJSON), &credential); err != nil {
+			return passkeyUser{}, err
+		}
+		u.credentials = append(u.credentials, credential)
+	}
+	return u, nil
+}
+
+var errInvalidPasskey = &passkeyError{}
+
+type passkeyError struct{}
+
+func (*passkeyError) Error() string { return "invalid passkey user" }
+
+func passkeyBody(r *http.Request, out interface{}) bool {
+	return json.NewDecoder(http.MaxBytesReader(nil, r.Body, 64*1024)).Decode(out) == nil
+}
+
+func (h *Handler) passkeyRegisterBegin(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		response.WriteJSON(w, response.ErrDefault("请求失败"))
+		return
+	}
+	wa, origin := passkeyConfig()
+	if wa == nil {
+		response.WriteJSON(w, response.ErrDefault("通行证密钥未配置"))
+		return
+	}
+	userID, err := userIDFromRequest(r)
+	if err != nil {
+		response.WriteJSON(w, response.Err(401, "未登录或token已过期"))
+		return
+	}
+	var req struct {
+		Password string `json:"password"`
+	}
+	if !passkeyBody(r, &req) {
+		response.WriteJSON(w, response.ErrDefault("请求参数错误"))
+		return
+	}
+	user, err := h.repo.GetUserByID(userID)
+	if err != nil || user == nil || user.Status != 1 {
+		response.WriteJSON(w, response.ErrDefault("账号不可用"))
+		return
+	}
+	if ok, _ := security.VerifyPassword(user.Pwd, req.Password); !ok {
+		response.WriteJSON(w, response.ErrDefault("当前密码错误"))
+		return
+	}
+	u, err := h.loadPasskeyUser(userID)
+	if err != nil {
+		response.WriteJSON(w, response.ErrDefault("无法读取通行证密钥"))
+		return
+	}
+	options, session, err := wa.BeginRegistration(u, webauthn.WithResidentKeyRequirement(protocol.ResidentKeyRequirementRequired))
+	if err != nil {
+		response.WriteJSON(w, response.ErrDefault("无法创建通行证密钥挑战"))
+		return
+	}
+	id, ok := h.putPasskeyCeremony(passkeyCeremony{userID: userID, kind: "register", origin: origin, session: *session})
+	if !ok {
+		response.WriteJSON(w, response.ErrDefault("无法创建通行证密钥挑战"))
+		return
+	}
+	response.WriteJSON(w, response.OK(map[string]interface{}{"sessionId": id, "options": options}))
+}
+
+type passkeyFinishRequest struct {
+	SessionID  string          `json:"sessionId"`
+	Credential json.RawMessage `json:"credential"`
+	Name       string          `json:"name"`
+}
+
+func (h *Handler) passkeyRegisterFinish(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		response.WriteJSON(w, response.ErrDefault("请求失败"))
+		return
+	}
+	wa, origin := passkeyConfig()
+	if wa == nil {
+		response.WriteJSON(w, response.ErrDefault("通行证密钥未配置"))
+		return
+	}
+	userID, err := userIDFromRequest(r)
+	if err != nil {
+		response.WriteJSON(w, response.Err(401, "未登录或token已过期"))
+		return
+	}
+	var req passkeyFinishRequest
+	if !passkeyBody(r, &req) {
+		response.WriteJSON(w, response.ErrDefault("请求参数错误"))
+		return
+	}
+	session, ok := h.takePasskeyCeremony(req.SessionID, "register", origin, userID)
+	if !ok {
+		response.WriteJSON(w, response.ErrDefault("通行证密钥挑战已过期"))
+		return
+	}
+	u, err := h.loadPasskeyUser(userID)
+	if err != nil {
+		response.WriteJSON(w, response.ErrDefault("账号不可用"))
+		return
+	}
+	credential, err := wa.FinishRegistration(u, session, credentialRequest(r, req.Credential))
+	if err != nil {
+		response.WriteJSON(w, response.ErrDefault("通行证密钥验证失败"))
+		return
+	}
+	credentialJSON, err := json.Marshal(credential)
+	if err != nil {
+		response.WriteJSON(w, response.ErrDefault("通行证密钥保存失败"))
+		return
+	}
+	name := strings.TrimSpace(req.Name)
+	if len([]rune(name)) > 100 {
+		name = string([]rune(name)[:100])
+	}
+	if name == "" {
+		name = "Passkey"
+	}
+	err = h.repo.CreatePasskey(&model.Passkey{ID: base64.RawURLEncoding.EncodeToString(credential.ID), UserID: userID, Name: name, CredentialJSON: string(credentialJSON), CreatedAt: time.Now().UnixMilli()})
+	if err != nil {
+		response.WriteJSON(w, response.ErrDefault("通行证密钥保存失败"))
+		return
+	}
+	response.WriteJSON(w, response.OK(nil))
+}
+
+func credentialRequest(original *http.Request, body []byte) *http.Request {
+	r := original.Clone(original.Context())
+	r.Body = http.NoBody
+	if len(body) > 0 {
+		r.Body = ioNopCloser{bytes.NewReader(body)}
+	}
+	return r
+}
+
+type ioNopCloser struct{ *bytes.Reader }
+
+func (ioNopCloser) Close() error { return nil }
+
+func (h *Handler) passkeyLoginBegin(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		response.WriteJSON(w, response.ErrDefault("请求失败"))
+		return
+	}
+	wa, origin := passkeyConfig()
+	if wa == nil {
+		response.WriteJSON(w, response.ErrDefault("通行证密钥未配置"))
+		return
+	}
+	var req struct {
+		Username string `json:"username"`
+	}
+	if !passkeyBody(r, &req) || strings.TrimSpace(req.Username) != "" {
+		response.WriteJSON(w, response.ErrDefault("请求参数错误"))
+		return
+	}
+	options, session, err := wa.BeginDiscoverableLogin(webauthn.WithUserVerification(protocol.VerificationRequired))
+	if err != nil {
+		response.WriteJSON(w, response.ErrDefault("无法创建通行证密钥挑战"))
+		return
+	}
+	id, ok := h.putPasskeyCeremony(passkeyCeremony{kind: "login-discoverable", origin: origin, session: *session})
+	if !ok {
+		response.WriteJSON(w, response.ErrDefault("无法创建通行证密钥挑战"))
+		return
+	}
+	response.WriteJSON(w, response.OK(map[string]interface{}{"sessionId": id, "options": options}))
+}
+
+func (h *Handler) passkeyLoginFinish(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		response.WriteJSON(w, response.ErrDefault("请求失败"))
+		return
+	}
+	wa, origin := passkeyConfig()
+	if wa == nil {
+		response.WriteJSON(w, response.ErrDefault("通行证密钥未配置"))
+		return
+	}
+	var req passkeyFinishRequest
+	if !passkeyBody(r, &req) {
+		response.WriteJSON(w, response.ErrDefault("请求参数错误"))
+		return
+	}
+	pending, ok := h.takePasskeyLoginCeremony(req.SessionID, origin)
+	if !ok {
+		response.WriteJSON(w, response.ErrDefault("通行证密钥挑战已过期"))
+		return
+	}
+	resolved, credential, err := wa.FinishPasskeyLogin(func(rawID, userHandle []byte) (webauthn.User, error) {
+		// The credential ID determines ownership. A supplied userHandle cannot select another account.
+		if len(rawID) == 0 || len(userHandle) != 8 {
+			return nil, errInvalidPasskey
+		}
+		row, lookupErr := h.repo.GetPasskeyByID(base64.RawURLEncoding.EncodeToString(rawID))
+		if lookupErr != nil || row == nil {
+			return nil, errInvalidPasskey
+		}
+		owner, loadErr := h.loadPasskeyUser(row.UserID)
+		if loadErr != nil || !bytes.Equal(userHandle, owner.WebAuthnID()) {
+			return nil, errInvalidPasskey
+		}
+		return owner, nil
+	}, pending.session, credentialRequest(r, req.Credential))
+	var u passkeyUser
+	if err == nil {
+		var valid bool
+		u, valid = resolved.(passkeyUser)
+		if !valid {
+			err = errInvalidPasskey
+		}
+	}
+	if err != nil || credential == nil || credential.Authenticator.CloneWarning {
+		response.WriteJSON(w, response.ErrDefault("通行证密钥验证失败"))
+		return
+	}
+	credentialID := base64.RawURLEncoding.EncodeToString(credential.ID)
+	stored, err := h.repo.GetPasskey(u.id, credentialID)
+	if err != nil || stored == nil {
+		response.WriteJSON(w, response.ErrDefault("通行证密钥验证失败"))
+		return
+	}
+	updated, err := json.Marshal(credential)
+	if err != nil {
+		response.WriteJSON(w, response.ErrDefault("通行证密钥验证失败"))
+		return
+	}
+	ok, err = h.repo.UpdatePasskeyCredential(u.id, credentialID, stored.CredentialJSON, string(updated), time.Now().UnixMilli())
+	if err != nil || !ok {
+		response.WriteJSON(w, response.ErrDefault("通行证密钥验证失败"))
+		return
+	}
+	user, err := h.repo.GetUserByID(u.id)
+	if err != nil || user == nil || user.Status != 1 {
+		response.WriteJSON(w, response.ErrDefault("账号不可用"))
+		return
+	}
+	token, err := auth.GenerateTokenAt(user.ID, user.User, user.RoleID, h.jwtSecret, time.Now())
+	if err != nil {
+		response.WriteJSON(w, response.ErrDefault("登录失败"))
+		return
+	}
+	response.WriteJSON(w, response.OK(map[string]interface{}{"token": token, "name": user.User, "role_id": user.RoleID, "requirePasswordChange": user.User == "admin_user"}))
+}
+
+func (h *Handler) passkeyList(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		response.WriteJSON(w, response.ErrDefault("请求失败"))
+		return
+	}
+	userID, err := userIDFromRequest(r)
+	if err != nil {
+		response.WriteJSON(w, response.Err(401, "未登录或token已过期"))
+		return
+	}
+	rows, err := h.repo.ListPasskeys(userID)
+	if err != nil {
+		response.WriteJSON(w, response.ErrDefault("获取通行证密钥失败"))
+		return
+	}
+	out := make([]map[string]interface{}, 0, len(rows))
+	for _, row := range rows {
+		out = append(out, map[string]interface{}{"id": row.ID, "name": row.Name, "createdAt": row.CreatedAt, "lastUsedAt": row.LastUsedAt})
+	}
+	response.WriteJSON(w, response.OK(out))
+}
+
+func (h *Handler) passkeyDelete(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		response.WriteJSON(w, response.ErrDefault("请求失败"))
+		return
+	}
+	userID, err := userIDFromRequest(r)
+	if err != nil {
+		response.WriteJSON(w, response.Err(401, "未登录或token已过期"))
+		return
+	}
+	var req struct {
+		ID       string `json:"id"`
+		Password string `json:"password"`
+	}
+	if !passkeyBody(r, &req) || req.ID == "" {
+		response.WriteJSON(w, response.ErrDefault("请求参数错误"))
+		return
+	}
+	user, err := h.repo.GetUserByID(userID)
+	if err != nil || user == nil || user.Status != 1 {
+		response.WriteJSON(w, response.ErrDefault("账号不可用"))
+		return
+	}
+	if ok, _ := security.VerifyPassword(user.Pwd, req.Password); !ok {
+		response.WriteJSON(w, response.ErrDefault("当前密码错误"))
+		return
+	}
+	deleted, err := h.repo.DeletePasskey(userID, req.ID)
+	if err != nil || !deleted {
+		response.WriteJSON(w, response.ErrDefault("通行证密钥不存在"))
+		return
+	}
+	response.WriteJSON(w, response.OK(nil))
+}

go-backend/internal/http/handler/passkey_test.go

@@ -0,0 +1,56 @@
+package handler
+
+import (
+	"testing"
+	"time"
+
+	"github.com/go-webauthn/webauthn/webauthn"
+)
+
+func TestPasskeyChallengeExpiresAndIsSingleUse(t *testing.T) {
+	h := &Handler{passkeyPending: make(map[string]passkeyCeremony)}
+	id, ok := h.putPasskeyCeremony(passkeyCeremony{userID: 7, kind: "register", origin: "https://panel.example.test", session: webauthn.SessionData{Expires: time.Now().Add(time.Minute)}})
+	if !ok {
+		t.Fatal("could not create challenge")
+	}
+	if _, ok := h.takePasskeyCeremony(id, "register", "https://panel.example.test", 7); !ok {
+		t.Fatal("valid challenge was rejected")
+	}
+	if _, ok := h.takePasskeyCeremony(id, "register", "https://panel.example.test", 7); ok {
+		t.Fatal("challenge was reusable")
+	}
+	id, ok = h.putPasskeyCeremony(passkeyCeremony{userID: 7, kind: "register", origin: "https://panel.example.test", session: webauthn.SessionData{Expires: time.Now().Add(-time.Second)}})
+	if !ok {
+		t.Fatal("could not create expired challenge")
+	}
+	if _, ok := h.takePasskeyCeremony(id, "register", "https://panel.example.test", 7); ok {
+		t.Fatal("expired challenge was accepted")
+	}
+	id, ok = h.putPasskeyCeremony(passkeyCeremony{kind: "login-discoverable", origin: "https://panel.example.test", session: webauthn.SessionData{Expires: time.Now().Add(time.Minute)}})
+	if !ok {
+		t.Fatal("could not create discoverable challenge")
+	}
+	if _, ok := h.takePasskeyLoginCeremony(id, "https://wrong.example.test"); ok {
+		t.Fatal("wrong origin was accepted")
+	}
+	if _, ok := h.takePasskeyLoginCeremony(id, "https://panel.example.test"); ok {
+		t.Fatal("failed discoverable challenge was reusable")
+	}
+	id, ok = h.putPasskeyCeremony(passkeyCeremony{kind: "login-discoverable", origin: "https://panel.example.test", session: webauthn.SessionData{Expires: time.Now().Add(time.Minute)}})
+	if !ok {
+		t.Fatal("could not create discoverable challenge")
+	}
+	if _, ok := h.takePasskeyLoginCeremony(id, "https://panel.example.test"); !ok {
+		t.Fatal("valid discoverable challenge was rejected")
+	}
+	if _, ok := h.takePasskeyLoginCeremony(id, "https://panel.example.test"); ok {
+		t.Fatal("discoverable challenge was reusable")
+	}
+	id, ok = h.putPasskeyCeremony(passkeyCeremony{kind: "login-discoverable", origin: "https://panel.example.test", session: webauthn.SessionData{Expires: time.Now().Add(-time.Second)}})
+	if !ok {
+		t.Fatal("could not create expired discoverable challenge")
+	}
+	if _, ok := h.takePasskeyLoginCeremony(id, "https://panel.example.test"); ok {
+		t.Fatal("expired discoverable challenge was accepted")
+	}
+}

go-backend/internal/http/handler/peer_share_auth_cleanup_test.go

@@ -0,0 +1,160 @@
+package handler
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+
+	"go-backend/internal/http/response"
+	"go-backend/internal/store/repo"
+)
+
+func TestPeerShareRestrictedShareAllowsOnlyAuthenticatedCleanup(t *testing.T) {
+	for _, state := range []string{"disabled", "expired", "over-quota"} {
+		t.Run(state, func(t *testing.T) {
+			agent := newCleanupAgent(t)
+			runtime := roleRuntimeFixture(t, agent, "exit")
+			changes := map[string]interface{}{"allowed_ips": "203.0.113.10", "allowed_domains": "owner.example"}
+			switch state {
+			case "disabled":
+				changes["is_active"] = 0
+			case "expired":
+				changes["expiry_time"] = time.Now().Add(-time.Hour).UnixMilli()
+			case "over-quota":
+				changes["max_bandwidth"] = 1
+				changes["current_flow"] = 2
+			}
+			if err := agent.h.repo.DB().Model(&repo.PeerShare{}).Where("id = ?", runtime.ShareID).Updates(changes).Error; err != nil {
+				t.Fatal(err)
+			}
+			tests := []struct {
+				command string
+				allowed bool
+			}{
+				{"release-role", true}, {"DeleteService", true}, {"DeleteChains", true}, {"DeleteLimiters", true}, {"DeleteCLimiters", true},
+				{"AddService", false}, {"UpdateService", false}, {"ResumeService", false}, {"PauseService", false}, {"DeleteEverything", false},
+			}
+			for _, test := range tests {
+				t.Run(test.command, func(t *testing.T) {
+					path := "/api/v1/federation/runtime/command"
+					body := fmt.Sprintf(`{"commandType":%q,"data":{"services":["70_1_0_tcp"]}}`, test.command)
+					if test.command == "release-role" {
+						path = "/api/v1/federation/runtime/release-role"
+						body = `{"reservationId":"role-reservation"}`
+					}
+					req := httptest.NewRequest(http.MethodPost, path, strings.NewReader(body))
+					req.Header.Set("Authorization", "Bearer role-recovery-token")
+					req.Header.Set("X-Panel-Domain", "owner.example")
+					req.RemoteAddr = "203.0.113.10:12345"
+					reached := false
+					next := func(w http.ResponseWriter, r *http.Request) {
+						reached = true
+						received, err := io.ReadAll(r.Body)
+						if err != nil || string(received) != body {
+							t.Errorf("auth consumed request body: %s %v", received, err)
+						}
+						response.WriteJSON(w, response.OKEmpty())
+					}
+					agent.h.authPeer(next)(httptest.NewRecorder(), req)
+					if reached != test.allowed {
+						t.Fatalf("restricted %s %s allowed=%t want=%t", state, test.command, reached, test.allowed)
+					}
+				})
+			}
+			for _, invalid := range []string{"token", "domain", "ip"} {
+				t.Run("reject-"+invalid, func(t *testing.T) {
+					req := httptest.NewRequest(http.MethodPost, "/api/v1/federation/runtime/release-role", strings.NewReader(`{"reservationId":"role-reservation"}`))
+					req.Header.Set("Authorization", "Bearer role-recovery-token")
+					req.Header.Set("X-Panel-Domain", "owner.example")
+					req.RemoteAddr = "203.0.113.10:12345"
+					switch invalid {
+					case "token":
+						req.Header.Set("Authorization", "Bearer wrong-token")
+					case "domain":
+						req.Header.Set("X-Panel-Domain", "other.example")
+					case "ip":
+						req.RemoteAddr = "198.51.100.1:12345"
+					}
+					reached := false
+					agent.h.authPeer(func(http.ResponseWriter, *http.Request) { reached = true })(httptest.NewRecorder(), req)
+					if reached {
+						t.Fatalf("cleanup bypassed %s authentication", invalid)
+					}
+				})
+			}
+			// Exercise the actual release handler through auth, not only the gate.
+			req := httptest.NewRequest(http.MethodPost, "/api/v1/federation/runtime/release-role", strings.NewReader(`{"reservationId":"role-reservation"}`))
+			req.Header.Set("Authorization", "Bearer role-recovery-token")
+			req.Header.Set("X-Panel-Domain", "owner.example")
+			req.RemoteAddr = "203.0.113.10:12345"
+			res := httptest.NewRecorder()
+			agent.h.authPeer(agent.h.federationRuntimeReleaseRole)(res, req)
+			var result response.R
+			if err := json.Unmarshal(res.Body.Bytes(), &result); err != nil || result.Code != 0 {
+				t.Fatalf("authenticated cleanup did not complete: %s %v", res.Body.String(), err)
+			}
+			stored, err := agent.h.repo.GetPeerShareRuntimeByID(runtime.ID)
+			if err != nil || stored.Status != 0 {
+				t.Fatalf("cleanup did not release runtime: %+v %v", stored, err)
+			}
+		})
+	}
+}
+
+func TestPeerShareOldReleaseIdentityCannotDeleteReusedReservation(t *testing.T) {
+	agent := newCleanupAgent(t)
+	old := roleRuntimeFixture(t, agent, "exit")
+	if err := agent.h.releasePeerShareRuntime(old); err != nil {
+		t.Fatal(err)
+	}
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/federation/runtime/reserve-port", strings.NewReader(`{"resourceKey":"role-resource","requestedPort":31000,"protocol":"tls"}`))
+	req.Header.Set("Authorization", "Bearer role-recovery-token")
+	res := httptest.NewRecorder()
+	agent.h.federationRuntimeReservePort(res, req)
+	var result response.R
+	if err := json.Unmarshal(res.Body.Bytes(), &result); err != nil || result.Code != 0 {
+		t.Fatalf("new generation reserve failed: %s %v", res.Body.String(), err)
+	}
+	fresh, err := agent.h.repo.GetPeerShareRuntimeByID(old.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if fresh.ReservationID == old.ReservationID {
+		t.Fatal("reservation identity was reused")
+	}
+	if code := roleRuntimeRequest(t, agent.h, fmt.Sprintf(`{"reservationId":%q,"role":"exit"}`, fresh.ReservationID), false); code != 0 {
+		t.Fatal("new generation apply failed")
+	}
+	fresh, err = agent.h.repo.GetPeerShareRuntimeByID(old.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if fresh.BindingID == old.BindingID || fresh.BindingID == "" {
+		t.Fatal("binding identity was reused")
+	}
+	deletesBefore := len(agent.commandsOfType("DeleteService"))
+	for _, body := range []string{
+		fmt.Sprintf(`{"bindingId":%q,"reservationId":%q,"resourceKey":"role-resource"}`, old.BindingID, old.ReservationID),
+		fmt.Sprintf(`{"reservationId":%q,"resourceKey":"role-resource"}`, old.ReservationID),
+	} {
+		if code := roleRuntimeRequest(t, agent.h, body, true); code != 0 {
+			t.Fatal("obsolete release should acknowledge completion")
+		}
+	}
+	// Also cover an old lookup snapshot waiting behind reservation renewal.
+	if err := agent.h.releasePeerShareRuntime(old); err != nil {
+		t.Fatal(err)
+	}
+	after, err := agent.h.repo.GetPeerShareRuntimeByID(old.ID)
+	if err != nil || after.Status != 1 || after.BindingID != fresh.BindingID {
+		t.Fatalf("old cleanup released new generation: %+v %v", after, err)
+	}
+	if len(agent.commandsOfType("DeleteService")) != deletesBefore {
+		t.Fatal("old cleanup sent deletion for new generation")
+	}
+}

go-backend/internal/http/handler/peer_share_runtime_lifecycle.go

@@ -0,0 +1,197 @@
+package handler
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"strings"
+	"sync"
+	"time"
+
+	"go-backend/internal/store/repo"
+)
+
+// Serialize desired-state changes with reconnect reconciliation. In particular,
+// a stale reconnect snapshot must never revive an acknowledged release.
+var peerRoleRuntimeMu sync.Mutex
+
+// applyPeerShareRoleRuntime requires peerRoleRuntimeMu. Persist the validated
+// desired configuration before creating resources, so failed or interrupted
+// commands remain recoverable rather than producing untracked listeners.
+func (h *Handler) applyPeerShareRoleRuntime(runtime *repo.PeerShareRuntime) error {
+	if runtime.ReleasePending != 0 || runtime.Status != 1 {
+		return errors.New("runtime is being released")
+	}
+	if runtime.Role != "middle" && runtime.Role != "exit" {
+		return errors.New("invalid runtime role")
+	}
+	node, err := h.getNodeRecord(runtime.NodeID)
+	if err != nil {
+		return err
+	}
+	credentials, err := decodeRuntimeRelayAuth(runtime)
+	if err != nil {
+		return err
+	}
+	var targets []federationRuntimeTarget
+	if strings.TrimSpace(runtime.Target) != "" {
+		if err := json.Unmarshal([]byte(runtime.Target), &targets); err != nil {
+			return err
+		}
+	}
+	if err := validateFederationRelayAuth(runtime.RelayAuth, credentials, targets); err != nil {
+		return err
+	}
+	var chain map[string]interface{}
+	if runtime.Role == "middle" {
+		chain, err = buildFederationMiddleChainConfig(runtime.ChainName, runtime.ID, runtime.Protocol, runtime.Strategy, targets, node.InterfaceName)
+		if err != nil {
+			return err
+		}
+	}
+	service := buildFederationServiceConfig(runtime.ServiceName, fmt.Sprintf("%s:%d", node.TCPListenAddr, runtime.Port), runtime.Protocol, runtime.Role, runtime.ChainName, len(targets), node.InterfaceName, credentials)
+	runtime.Applied = 0
+	runtime.UpdatedTime = time.Now().UnixMilli()
+	if err := h.repo.UpdatePeerShareRuntime(runtime); err != nil {
+		return err
+	}
+	if h.wsServer == nil {
+		return errors.New("node command transport unavailable")
+	}
+	if chain != nil {
+		if _, err := h.sendNodeCommand(runtime.NodeID, "UpdateChains", updateChainPayload(runtime.ChainName, chain), false, false); err != nil {
+			return err
+		}
+	}
+	// UpdateService and UpdateChains are upserts, including on an empty agent.
+	if _, err := h.sendNodeCommand(runtime.NodeID, "UpdateService", []map[string]interface{}{service}, false, false); err != nil {
+		return err
+	}
+	runtime.Applied = 1
+	runtime.UpdatedTime = time.Now().UnixMilli()
+	return h.repo.UpdatePeerShareRuntime(runtime)
+}
+
+func (h *Handler) releasePeerShareRuntime(runtime *repo.PeerShareRuntime) error {
+	peerRoleRuntimeMu.Lock()
+	defer peerRoleRuntimeMu.Unlock()
+	if runtime == nil {
+		return nil
+	}
+	current, err := h.repo.GetPeerShareRuntimeByID(runtime.ID)
+	if err != nil {
+		return err
+	}
+	if current != nil && (current.ReservationID != runtime.ReservationID || current.BindingID != runtime.BindingID) {
+		// A completed reservation may have been reused while this release
+		// waited for the mutation lock. Never release the new generation.
+		return nil
+	}
+	return h.releasePeerShareRuntimeLocked(current)
+}
+
+func (h *Handler) releasePeerShareRuntimeLocked(runtime *repo.PeerShareRuntime) error {
+	if runtime == nil || runtime.Status == 0 {
+		return nil
+	}
+	if err := h.repo.SetPeerShareRuntimeReleasePending(runtime.ID); err != nil {
+		return err
+	}
+	runtime.ReleasePending = 1
+	if runtime.Role == "forward" {
+		if _, _, scoped := parsePeerShareServiceName(runtime.ServiceName); scoped {
+			if err := h.releasePeerShareForwardRuntimeResources(runtime); err != nil {
+				return err
+			}
+			return h.repo.CompletePeerShareRuntimeRelease(runtime.ID)
+		}
+		// Older agents used unscoped names. Do not delete a name shared by
+		// another reservation or by a local forward during migration.
+		owners, err := h.repo.ListActiveForwardPeerShareRuntimesByNodeAndServiceName(runtime.NodeID, runtime.ServiceName)
+		if err != nil {
+			return err
+		}
+		for _, owner := range owners {
+			if owner.ShareID != runtime.ShareID {
+				return fmt.Errorf("legacy runtime %q has ambiguous ownership", runtime.ServiceName)
+			}
+		}
+		if forwardID, _, _, ok := parseFlowServiceIDs(normalizeForwardRuntimeServiceName(runtime.ServiceName)); ok {
+			local, err := h.repo.GetForwardRecord(forwardID)
+			if err != nil {
+				return err
+			}
+			if local != nil {
+				return fmt.Errorf("legacy runtime %q collides with a local forward", runtime.ServiceName)
+			}
+		}
+	}
+	// ServiceName is saved before apply; Applied=0 can therefore mean an
+	// unacknowledged command, and must not bypass deletion.
+	if strings.TrimSpace(runtime.ServiceName) != "" || strings.TrimSpace(runtime.ChainName) != "" {
+		if h.wsServer == nil {
+			return errors.New("node command transport unavailable")
+		}
+		if strings.TrimSpace(runtime.ServiceName) != "" {
+			names := []string{runtime.ServiceName}
+			if runtime.Role == "forward" {
+				names = append(names, runtime.ServiceName+"_tcp", runtime.ServiceName+"_udp")
+			}
+			if _, err := h.sendNodeCommand(runtime.NodeID, "DeleteService", map[string]interface{}{"services": names}, false, true); err != nil {
+				return err
+			}
+		}
+		if strings.TrimSpace(runtime.ChainName) != "" {
+			if _, err := h.sendNodeCommand(runtime.NodeID, "DeleteChains", map[string]interface{}{"chain": runtime.ChainName}, false, true); err != nil {
+				return err
+			}
+		}
+	}
+	return h.repo.CompletePeerShareRuntimeRelease(runtime.ID)
+}
+
+func (h *Handler) reconcilePeerShareRoleRuntimesOnNode(nodeID int64) error {
+	return h.reconcilePeerShareRoleRuntimes(nodeID, false)
+}
+
+// Maintenance retries only unfinished desired state. Replaying acknowledged
+// services while an unrelated operation is failing can interrupt live traffic.
+func (h *Handler) retryPendingPeerShareRoleRuntimesOnNode(nodeID int64) error {
+	return h.reconcilePeerShareRoleRuntimes(nodeID, true)
+}
+
+func (h *Handler) reconcilePeerShareRoleRuntimes(nodeID int64, pendingOnly bool) error {
+	peerRoleRuntimeMu.Lock()
+	defer peerRoleRuntimeMu.Unlock()
+	runtimes, err := h.repo.ListActivePeerShareRuntimesByNode(nodeID)
+	if err != nil {
+		return err
+	}
+	var reconcileErr error
+	for i := range runtimes {
+		runtime := &runtimes[i]
+		if pendingOnly && runtime.Applied == 1 && runtime.ReleasePending == 0 {
+			continue
+		}
+		if runtime.ReleasePending != 0 {
+			reconcileErr = errors.Join(reconcileErr, h.releasePeerShareRuntimeLocked(runtime))
+			continue
+		}
+		if runtime.Role != "middle" && runtime.Role != "exit" {
+			continue
+		}
+		share, err := h.repo.GetPeerShare(runtime.ShareID)
+		if err != nil {
+			reconcileErr = errors.Join(reconcileErr, err)
+			continue
+		}
+		if share == nil || share.IsActive != 1 || (share.ExpiryTime > 0 && share.ExpiryTime <= time.Now().UnixMilli()) || isPeerShareFlowExceeded(share) {
+			reconcileErr = errors.Join(reconcileErr, h.releasePeerShareRuntimeLocked(runtime))
+			continue
+		}
+		if err := h.applyPeerShareRoleRuntime(runtime); err != nil {
+			reconcileErr = errors.Join(reconcileErr, fmt.Errorf("shared runtime %d: %w", runtime.ID, err))
+		}
+	}
+	return reconcileErr
+}

go-backend/internal/http/handler/peer_share_runtime_lifecycle_test.go

@@ -0,0 +1,358 @@
+package handler
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"go-backend/internal/store/repo"
+	"go-backend/internal/ws"
+	"gorm.io/gorm"
+)
+
+func roleRuntimeFixture(t *testing.T, agent *cleanupAgent, role string) *repo.PeerShareRuntime {
+	t.Helper()
+	now := time.Now().UnixMilli()
+	share := &repo.PeerShare{Name: "role-recovery", NodeID: 1, Token: "role-recovery-token", PortRangeStart: 31000, PortRangeEnd: 31010, IsActive: 1, CreatedTime: now, UpdatedTime: now}
+	if err := agent.h.repo.CreatePeerShare(share); err != nil {
+		t.Fatal(err)
+	}
+	runtime := &repo.PeerShareRuntime{ShareID: share.ID, NodeID: 1, ReservationID: "role-reservation", ResourceKey: "role-resource", BindingID: "333", Role: role, ServiceName: "fed_svc_333", Protocol: "tls", Strategy: "round", Port: 31000, Applied: 1, Status: 1, CreatedTime: now, UpdatedTime: now}
+	if role == "middle" {
+		runtime.ChainName = "fed_chain_333"
+		runtime.Target = `[{"host":"127.0.0.1","port":32000,"protocol":"tls"}]`
+	}
+	if err := agent.h.repo.CreatePeerShareRuntime(runtime); err != nil {
+		t.Fatal(err)
+	}
+	// Runtime-generated names use the provider's globally unique runtime ID.
+	runtime.BindingID = fmt.Sprint(runtime.ID)
+	runtime.ServiceName = fmt.Sprintf("fed_svc_%d", runtime.ID)
+	if role == "middle" {
+		runtime.ChainName = federationRuntimeChainName(runtime.BindingID)
+	}
+	if err := agent.h.repo.UpdatePeerShareRuntime(runtime); err != nil {
+		t.Fatal(err)
+	}
+	return runtime
+}
+
+func roleRuntimeRequest(t *testing.T, h *Handler, body string, release bool) int {
+	t.Helper()
+	req := httptest.NewRequest(http.MethodPost, "/runtime", strings.NewReader(body))
+	req.Header.Set("Authorization", "Bearer role-recovery-token")
+	res := httptest.NewRecorder()
+	if release {
+		h.federationRuntimeReleaseRole(res, req)
+	} else {
+		h.federationRuntimeApplyRole(res, req)
+	}
+	var result struct {
+		Code int    `json:"code"`
+		Msg  string `json:"msg"`
+	}
+	if err := json.Unmarshal(res.Body.Bytes(), &result); err != nil {
+		t.Fatal(err)
+	}
+	t.Logf("runtime response: %s", res.Body.String())
+	return result.Code
+}
+
+func TestPeerShareAppliedRuntimeRepairsEmptyAgent(t *testing.T) {
+	for _, role := range []string{"exit", "middle"} {
+		t.Run(role, func(t *testing.T) {
+			agent := newCleanupAgent(t)
+			roleRuntimeFixture(t, agent, role)
+			if !agent.h.redeployNodeRuntimeAfterUpgrade(1) {
+				t.Fatal("reconnect reconciliation failed")
+			}
+			if got := len(agent.commandsOfType("UpdateService")); got != 1 {
+				t.Fatalf("reconnect did not restore service: %d", got)
+			}
+			targets := ""
+			if role == "middle" {
+				targets = `,"targets":[{"host":"127.0.0.1","port":32000,"protocol":"tls"}]`
+			}
+			if code := roleRuntimeRequest(t, agent.h, `{"reservationId":"role-reservation","role":"`+role+`","protocol":"tls"`+targets+`}`, false); code != 0 {
+				t.Fatalf("apply failed: %d", code)
+			}
+			if got := len(agent.commandsOfType("UpdateService")); got != 2 {
+				t.Fatalf("Applied=1 skipped service repair: %d", got)
+			}
+			if role == "middle" {
+				if got := len(agent.commandsOfType("UpdateChains")); got != 2 {
+					t.Fatalf("missing middle chains: %d", got)
+				}
+				agent.mu.Lock()
+				defer agent.mu.Unlock()
+				chainSeen := false
+				for _, cmd := range agent.commands {
+					if cmd.Type == "UpdateChains" {
+						chainSeen = true
+					}
+					if cmd.Type == "UpdateService" && !chainSeen {
+						t.Fatal("service started before chain")
+					}
+				}
+			}
+		})
+	}
+}
+
+func TestPeerShareReleaseOfflineKeepsPortAndReconnectDeletes(t *testing.T) {
+	agent := newCleanupAgent(t)
+	runtime := roleRuntimeFixture(t, agent, "middle")
+	liveServer := agent.h.wsServer
+	agent.h.wsServer = ws.NewServer(agent.h.repo, "offline-test")
+	if code := roleRuntimeRequest(t, agent.h, `{"reservationId":"role-reservation"}`, true); code == 0 {
+		t.Fatal("offline release reported success")
+	}
+	stored, err := agent.h.repo.GetPeerShareRuntimeByID(runtime.ID)
+	if err != nil || stored.Status != 1 || stored.ReleasePending != 1 {
+		t.Fatalf("pending release lost: %+v err=%v", stored, err)
+	}
+	occupied, err := agent.h.repo.ExistsActivePeerShareRuntimeOnNodePort(1, 31000)
+	if err != nil || !occupied {
+		t.Fatalf("pending release freed occupied port: %t %v", occupied, err)
+	}
+	if code := roleRuntimeRequest(t, agent.h, `{"reservationId":"role-reservation","role":"middle","targets":[{"host":"127.0.0.1","port":32000}]}`, false); code == 0 {
+		t.Fatal("pending release was revived by apply")
+	}
+	agent.h.wsServer = liveServer
+	if !agent.h.redeployNodeRuntimeAfterUpgrade(1) {
+		t.Fatal("reconnect cleanup failed")
+	}
+	stored, err = agent.h.repo.GetPeerShareRuntimeByID(runtime.ID)
+	if err != nil || stored.Status != 0 || stored.Applied != 0 || stored.ReleasePending != 0 {
+		t.Fatalf("release not completed: %+v %v", stored, err)
+	}
+	if len(agent.commandsOfType("DeleteService")) != 1 || len(agent.commandsOfType("DeleteChains")) != 1 {
+		t.Fatal("reconnect did not delete both service and chain")
+	}
+	if len(agent.commandsOfType("UpdateService")) != 0 || len(agent.commandsOfType("UpdateChains")) != 0 {
+		t.Fatal("reconnect revived pending release")
+	}
+	occupied, err = agent.h.repo.ExistsActivePeerShareRuntimeOnNodePort(1, 31000)
+	if err != nil || occupied {
+		t.Fatalf("acknowledged release still occupies port: %t %v", occupied, err)
+	}
+}
+
+func TestPeerShareApplyPersistsBeforeCommand(t *testing.T) {
+	var failDesiredWrite atomic.Bool
+	agent := newCleanupAgent(t, func(r *repo.Repository) {
+		if err := r.DB().Callback().Update().Before("gorm:update").Register("test:fail-role-desired-write", func(tx *gorm.DB) {
+			if failDesiredWrite.Load() && tx.Statement.Table == "peer_share_runtime" {
+				tx.AddError(errors.New("desired-state write failed"))
+			}
+		}); err != nil {
+			t.Fatal(err)
+		}
+	})
+	runtime := roleRuntimeFixture(t, agent, "exit")
+	failDesiredWrite.Store(true)
+	// Only the atomic flag changes while the WebSocket is running; GORM's
+	// callback registry stays immutable through node-status teardown writes.
+	if code := roleRuntimeRequest(t, agent.h, `{"reservationId":"role-reservation","role":"exit"}`, false); code == 0 {
+		t.Fatal("failed ownership persistence reported success")
+	}
+	if len(agent.commandsOfType("UpdateService")) != 0 {
+		t.Fatal("service started before ownership persisted")
+	}
+	stored, err := agent.h.repo.GetPeerShareRuntimeByID(runtime.ID)
+	if err != nil || stored.Applied != 1 {
+		t.Fatalf("old runtime changed on failed persistence: %+v %v", stored, err)
+	}
+}
+
+func TestPeerShareApplyInvalidMiddleKeepsDesiredConfig(t *testing.T) {
+	agent := newCleanupAgent(t)
+	runtime := roleRuntimeFixture(t, agent, "middle")
+	if code := roleRuntimeRequest(t, agent.h, `{"reservationId":"role-reservation","role":"middle","targets":[]}`, false); code == 0 {
+		t.Fatal("invalid middle targets accepted")
+	}
+	stored, err := agent.h.repo.GetPeerShareRuntimeByID(runtime.ID)
+	if err != nil || stored.Target != runtime.Target || stored.Applied != 1 {
+		t.Fatalf("invalid update changed desired runtime: %+v %v", stored, err)
+	}
+	if len(agent.commandsOfType("UpdateService"))+len(agent.commandsOfType("UpdateChains")) != 0 {
+		t.Fatal("invalid config sent to agent")
+	}
+}
+
+func TestPeerShareUnacknowledgedApplyRecoversOrReleases(t *testing.T) {
+	for _, release := range []bool{false, true} {
+		t.Run(fmt.Sprintf("release=%t", release), func(t *testing.T) {
+			agent := newCleanupAgent(t)
+			runtime := roleRuntimeFixture(t, agent, "middle")
+			liveServer := agent.h.wsServer
+			agent.h.wsServer = ws.NewServer(agent.h.repo, "offline-test")
+			if code := roleRuntimeRequest(t, agent.h, `{"reservationId":"role-reservation","role":"middle","targets":[{"host":"127.0.0.1","port":32001,"protocol":"tls"}]}`, false); code == 0 {
+				t.Fatal("offline apply reported success")
+			}
+			stored, err := agent.h.repo.GetPeerShareRuntimeByID(runtime.ID)
+			if err != nil || stored.Applied != 0 || !strings.Contains(stored.Target, "32001") || stored.ServiceName == "" {
+				t.Fatalf("unacknowledged desired state lost: %+v %v", stored, err)
+			}
+			if release {
+				if code := roleRuntimeRequest(t, agent.h, `{"reservationId":"role-reservation"}`, true); code == 0 {
+					t.Fatal("unacknowledged listener was freed offline")
+				}
+			}
+			agent.h.wsServer = liveServer
+			if !agent.h.redeployNodeRuntimeAfterUpgrade(1) {
+				t.Fatal("reconnect failed")
+			}
+			stored, err = agent.h.repo.GetPeerShareRuntimeByID(runtime.ID)
+			if err != nil {
+				t.Fatal(err)
+			}
+			if release {
+				if stored.Status != 0 || len(agent.commandsOfType("DeleteService")) != 1 || len(agent.commandsOfType("UpdateService")) != 0 {
+					t.Fatalf("unacknowledged apply revived after release: %+v", stored)
+				}
+			} else {
+				if stored.Status != 1 || stored.Applied != 1 || len(agent.commandsOfType("UpdateService")) != 1 {
+					t.Fatalf("unacknowledged desired state not recovered: %+v", stored)
+				}
+			}
+		})
+	}
+}
+
+func TestPeerShareDeleteOfflineRetainsDisabledShare(t *testing.T) {
+	agent := newCleanupAgent(t)
+	runtime := roleRuntimeFixture(t, agent, "exit")
+	liveServer := agent.h.wsServer
+	agent.h.wsServer = ws.NewServer(agent.h.repo, "offline-test")
+	req := httptest.NewRequest(http.MethodPost, "/share/delete", strings.NewReader(fmt.Sprintf(`{"id":%d}`, runtime.ShareID)))
+	res := httptest.NewRecorder()
+	agent.h.federationShareDelete(res, req)
+	var result struct {
+		Code int `json:"code"`
+	}
+	if err := json.Unmarshal(res.Body.Bytes(), &result); err != nil {
+		t.Fatal(err)
+	}
+	if result.Code == 0 {
+		t.Fatal("offline share delete reported success")
+	}
+	share, err := agent.h.repo.GetPeerShare(runtime.ShareID)
+	if err != nil || share == nil || share.IsActive != 0 {
+		t.Fatalf("cleanup retry record lost or still accepts allocations: %+v %v", share, err)
+	}
+	occupied, err := agent.h.repo.ExistsActivePeerShareRuntimeOnNodePort(1, 31000)
+	if err != nil || !occupied {
+		t.Fatal("offline share deletion released its port")
+	}
+	agent.h.wsServer = liveServer
+	if !agent.h.redeployNodeRuntimeAfterUpgrade(1) {
+		t.Fatal("disabled share cleanup did not retry")
+	}
+	if len(agent.commandsOfType("DeleteService")) != 1 || len(agent.commandsOfType("UpdateService")) != 0 {
+		t.Fatal("disabled share was recreated")
+	}
+}
+
+func TestPeerShareLegacyReleaseWithoutLocalCollisionDeletesFamily(t *testing.T) {
+	agent := newCleanupAgent(t)
+	runtime := roleRuntimeFixture(t, agent, "forward")
+	runtime.ServiceName = "70_1_0"
+	if err := agent.h.repo.UpdatePeerShareRuntime(runtime); err != nil {
+		t.Fatal(err)
+	}
+	if err := agent.h.releasePeerShareRuntime(runtime); err != nil {
+		t.Fatal(err)
+	}
+	commands := agent.commandsOfType("DeleteService")
+	if len(commands) != 1 {
+		t.Fatalf("expected one family cleanup, got %d", len(commands))
+	}
+	var payload struct {
+		Services []string `json:"services"`
+	}
+	if err := json.Unmarshal(commands[0].Data, &payload); err != nil {
+		t.Fatal(err)
+	}
+	got := strings.Join(payload.Services, ",")
+	if got != "70_1_0,70_1_0_tcp,70_1_0_udp" {
+		t.Fatalf("incomplete legacy cleanup: %s", got)
+	}
+	stored, err := agent.h.repo.GetPeerShareRuntimeByID(runtime.ID)
+	if err != nil || stored.Status != 0 || stored.ReleasePending != 0 {
+		t.Fatalf("legacy release incomplete: %+v %v", stored, err)
+	}
+}
+
+func TestPeerSharePendingRoleRetryDoesNotReplaySuccessfulServices(t *testing.T) {
+	agent := newCleanupAgent(t)
+	runtime := roleRuntimeFixture(t, agent, "exit")
+	if err := agent.h.retryPendingPeerShareRoleRuntimesOnNode(1); err != nil {
+		t.Fatal(err)
+	}
+	if len(agent.commandsOfType("UpdateService")) != 0 {
+		t.Fatal("maintenance replayed an acknowledged service")
+	}
+	runtime.Applied = 0
+	if err := agent.h.repo.UpdatePeerShareRuntime(runtime); err != nil {
+		t.Fatal(err)
+	}
+	if err := agent.h.retryPendingPeerShareRoleRuntimesOnNode(1); err != nil {
+		t.Fatal(err)
+	}
+	if len(agent.commandsOfType("UpdateService")) != 1 {
+		t.Fatal("maintenance did not retry unfinished service")
+	}
+	if err := agent.h.retryPendingPeerShareRoleRuntimesOnNode(1); err != nil {
+		t.Fatal(err)
+	}
+	if len(agent.commandsOfType("UpdateService")) != 1 {
+		t.Fatal("maintenance repeated a successful retry")
+	}
+}
+
+func TestPeerShareResourceFailureDoesNotBlockRoleOrLocalRecovery(t *testing.T) {
+	agent := newCleanupAgent(t)
+	runtime := roleRuntimeFixture(t, agent, "exit")
+	if err := agent.h.repo.SavePeerShareResources([]repo.PeerShareResource{{ShareID: runtime.ShareID, NodeID: 1, Kind: "chain", OriginalName: "broken", RuntimeName: "broken", Config: "invalid-json", DesiredState: "active", Applied: 0, UpdatedTime: time.Now().UnixMilli()}}); err != nil {
+		t.Fatal(err)
+	}
+	var localQueries atomic.Int32
+	if err := agent.h.repo.DB().Callback().Query().Before("gorm:query").Register("test:observe-local-recovery", func(tx *gorm.DB) {
+		if tx.Statement.Table == "chain_tunnel" || tx.Statement.Table == "forward_port" {
+			localQueries.Add(1)
+		}
+	}); err != nil {
+		t.Fatal(err)
+	}
+	if agent.h.redeployNodeRuntimeAfterUpgrade(1) {
+		t.Fatal("invalid shared resource was reported recovered")
+	}
+	if len(agent.commandsOfType("UpdateService")) != 1 {
+		t.Fatal("resource failure blocked independent role service recovery")
+	}
+	if localQueries.Load() < 2 {
+		t.Fatal("shared failure blocked independent local recovery")
+	}
+	// A shared failure is owned by pending maintenance, without full-redeploy
+	// timers that would periodically restart healthy listeners.
+	agent.h.onNodeOnline(1)
+	agent.h.upgradeMu.Lock()
+	_, fullQueued := agent.h.nodeOnlineRedeployQueued[1]
+	_, localQueued := agent.h.nodeLocalRuntimeRetryQueued[1]
+	agent.h.upgradeMu.Unlock()
+	if fullQueued || localQueued {
+		t.Fatal("shared-only failure queued a full or local redeploy")
+	}
+	before := len(agent.commandsOfType("UpdateService"))
+	agent.h.retryNodeLocalRuntime(1)
+	if len(agent.commandsOfType("UpdateService")) != before {
+		t.Fatal("local retry replayed shared listeners")
+	}
+}

go-backend/internal/http/handler/relay_auth.go

@@ -0,0 +1,125 @@
+package handler
+
+import (
+	"encoding/json"
+	"fmt"
+	"go-backend/internal/http/client"
+	"go-backend/internal/relaysecurity"
+	"go-backend/internal/store/repo"
+	"gorm.io/gorm"
+)
+
+func (h *Handler) resolveTunnelRelayAuth(tx *gorm.DB, state *tunnelCreateState, create bool) error {
+	if state.Type != 2 || state.RelayAuthMode == relaysecurity.Legacy {
+		return nil
+	}
+	if state.RelayAuthMode != relaysecurity.Required {
+		return fmt.Errorf("unsupported relay authentication mode")
+	}
+	for i := range state.OutNodes {
+		c, err := h.repo.RelayEndpointCredentials(tx, state.TunnelID, state.OutNodes[i].NodeID, 3, create)
+		if err != nil {
+			return err
+		}
+		state.OutNodes[i].RelayAuth = c
+	}
+	for hop := range state.ChainHops {
+		for i := range state.ChainHops[hop] {
+			c, err := h.repo.RelayEndpointCredentials(tx, state.TunnelID, state.ChainHops[hop][i].NodeID, 2, create)
+			if err != nil {
+				return err
+			}
+			state.ChainHops[hop][i].RelayAuth = c
+		}
+	}
+	return nil
+}
+
+func (h *Handler) resolveBestExitRelayAuth(tunnelID int64, targets []tunnelRuntimeNode) error {
+	tunnel, err := h.repo.GetTunnelRecord(tunnelID)
+	if err != nil {
+		return err
+	}
+	if tunnel == nil {
+		return fmt.Errorf("tunnel not found")
+	}
+	return h.resolveTunnelRelayAuth(nil, &tunnelCreateState{TunnelID: tunnelID, Type: tunnel.Type, RelayAuthMode: tunnel.RelayAuthMode, OutNodes: targets}, false)
+}
+
+func relayAuthVersion(c *relaysecurity.Credentials) int {
+	if c == nil {
+		return 0
+	}
+	return c.Version
+}
+func decodePersistedRelayAuth(raw string) (*relaysecurity.Credentials, error) {
+	if raw == "" {
+		return nil, nil
+	}
+	var c relaysecurity.Credentials
+	if err := json.Unmarshal([]byte(raw), &c); err != nil {
+		return nil, fmt.Errorf("invalid persisted relay authentication")
+	}
+	if err := c.Validate(); err != nil {
+		return nil, err
+	}
+	return &c, nil
+}
+func validateFederationRelayAuth(persisted string, c *relaysecurity.Credentials, targets []federationRuntimeTarget) error {
+	old, err := decodePersistedRelayAuth(persisted)
+	if err != nil {
+		return err
+	}
+	if old != nil && (c == nil || *old != *c) {
+		return fmt.Errorf("authenticated relay cannot be downgraded or rotated by reapply")
+	}
+	if c != nil {
+		if err := c.Validate(); err != nil {
+			return err
+		}
+		for _, target := range targets {
+			if err := target.RelayAuth.Validate(); err != nil {
+				return err
+			}
+		}
+	} else {
+		for _, target := range targets {
+			if target.RelayAuth != nil {
+				if err := target.RelayAuth.Validate(); err != nil {
+					return err
+				}
+			}
+		}
+	}
+	return nil
+}
+
+func (h *Handler) preflightFederationRelayAuth(state *tunnelCreateState, domain string) error {
+	if state.RelayAuthMode != relaysecurity.Required || state.Type != 2 {
+		return nil
+	}
+	for _, node := range state.Nodes {
+		if node == nil || node.IsRemote != 1 {
+			continue
+		}
+		info, err := client.NewFederationClient().Connect(node.RemoteURL, node.RemoteToken, domain)
+		if err != nil {
+			return fmt.Errorf("relay authentication capability check failed for remote node %d", node.ID)
+		}
+		if info.RelayAuthVersion != relaysecurity.Version {
+			return fmt.Errorf("remote node %d does not support required relay authentication", node.ID)
+		}
+	}
+	return nil
+}
+
+func decodeRuntimeRelayAuth(runtime *repo.PeerShareRuntime) (*relaysecurity.Credentials, error) {
+	c, err := decodePersistedRelayAuth(runtime.RelayAuth)
+	if err != nil {
+		return nil, err
+	}
+	if runtime.RelayAuthVersion != relayAuthVersion(c) {
+		return nil, fmt.Errorf("persisted relay authentication version or credentials unavailable")
+	}
+	return c, nil
+}

go-backend/internal/http/handler/system_upgrade.go

@@ -15,6 +15,7 @@ import (
 	"time"
 
 	"go-backend/internal/http/response"
+	"go-backend/internal/panelupgrade"
 )
 
 const (
@@ -75,6 +76,7 @@ type systemUpgradeCheckData struct {
 }
 
 type systemUpgradeRunData struct {
+	JobID           string `json:"jobId"`
 	Version         string `json:"version"`
 	Channel         string `json:"channel"`
 	ComposeAsset    string `json:"composeAsset"`
@@ -118,17 +120,7 @@ func validateBackendContainerName(value string) error {
 	return nil
 }
 
-func validateUpgradeVersion(value string) error {
-	if strings.TrimSpace(value) == "" {
-		return fmt.Errorf("upgrade version is empty")
-	}
-	for _, r := range value {
-		if r < 0x20 || r == 0x7f {
-			return fmt.Errorf("unsafe upgrade version: contains control character")
-		}
-	}
-	return nil
-}
+func validateUpgradeVersion(value string) error { return panelupgrade.ValidateVersion(value) }
 
 func (e *systemUpgradeExecutor) composePath() string {
 	return filepath.Join(e.deployDir, "docker-compose.yml")
@@ -136,6 +128,8 @@ func (e *systemUpgradeExecutor) composePath() string {
 func (e *systemUpgradeExecutor) envPath() string { return filepath.Join(e.deployDir, ".env") }
 
 func (e *systemUpgradeExecutor) capability(ctx context.Context) systemUpgradeCapabilityData {
+	ctx, cancel := context.WithTimeout(ctx, 15*time.Second)
+	defer cancel()
 	reasons := make([]string, 0)
 	if !filepath.IsAbs(e.deployDir) {
 		reasons = append(reasons, "部署目录必须是绝对路径")
@@ -143,8 +137,8 @@ func (e *systemUpgradeExecutor) capability(ctx context.Context) systemUpgradeCap
 	if err := validateBackendContainerName(e.backendContainer); err != nil {
 		reasons = append(reasons, err.Error())
 	}
-	if out, err := exec.CommandContext(ctx, "docker", "--version").CombinedOutput(); err != nil {
-		reasons = append(reasons, fmt.Sprintf("docker CLI不可用: %v: %s", err, strings.TrimSpace(string(out))))
+	if err := exec.CommandContext(ctx, "docker", "--version").Run(); err != nil {
+		reasons = append(reasons, "docker CLI不可用")
 	}
 	if info, err := os.Stat(dockerSocketPath); err != nil {
 		reasons = append(reasons, "docker socket不可用: "+err.Error())
@@ -161,10 +155,10 @@ func (e *systemUpgradeExecutor) capability(ctx context.Context) systemUpgradeCap
 	} else if info.IsDir() {
 		reasons = append(reasons, "部署.env不是文件")
 	}
-	if out, err := exec.CommandContext(ctx, "docker", "compose", "version").CombinedOutput(); err != nil {
-		reasons = append(reasons, fmt.Sprintf("docker compose不可用: %v: %s", err, strings.TrimSpace(string(out))))
+	if err := exec.CommandContext(ctx, "docker", "compose", "version").Run(); err != nil {
+		reasons = append(reasons, "docker compose不可用")
 	}
-	if _, err := e.currentBackendImage(ctx); err != nil {
+	if _, err := (panelupgrade.Manager{Dir: e.deployDir, Backend: e.backendContainer}).Identity(ctx); err != nil {
 		reasons = append(reasons, err.Error())
 	}
 
@@ -183,144 +177,6 @@ func (e *systemUpgradeExecutor) selectComposeAsset(current []byte) string {
 	return "docker-compose-v4.yml"
 }
 
-func (e *systemUpgradeExecutor) helperScript() string {
-	return `set -eu
-LOGFILE="$PANEL_DEPLOY_DIR/upgrade.log"
-log() { echo "[$(date '+%Y-%m-%d %H:%M:%S')] $*" | tee -a "$LOGFILE"; }
-
-cd "$PANEL_DEPLOY_DIR"
-echo "" > "$LOGFILE"
-log "开始面板升级"
-log "工作目录: $(pwd)"
-
-if [ ! -f docker-compose.yml ]; then
-  log "错误: docker-compose.yml 不存在"
-  exit 1
-fi
-if [ ! -f .env ]; then
-  log "错误: .env 不存在"
-  exit 1
-fi
-
-log "拉取新镜像..."
-if ! docker compose pull backend frontend >> "$LOGFILE" 2>&1; then
-  log "错误: 拉取镜像失败"
-  exit 1
-fi
-
-log "等待旧容器释放资源..."
-sleep 3
-
-log "重启服务（force-recreate）..."
-if ! docker compose up -d --force-recreate --remove-orphans backend frontend >> "$LOGFILE" 2>&1; then
-  log "错误: 重启服务失败"
-  exit 1
-fi
-
-log "升级完成"
-`
-}
-
-func (e *systemUpgradeExecutor) buildHelperRunArgs(imageID, helperName string) ([]string, error) {
-	if err := validateBackendContainerName(e.backendContainer); err != nil {
-		return nil, err
-	}
-	return []string{
-		"run", "-d", "--rm", "--name", helperName,
-		"--volumes-from", e.backendContainer,
-		"-v", dockerSocketPath + ":" + dockerSocketPath,
-		"-e", panelDeployDirEnv + "=" + e.deployDir,
-		"--entrypoint", "/bin/sh", imageID,
-		"-c", e.helperScript(),
-	}, nil
-}
-
-func (e *systemUpgradeExecutor) updateEnvVersion(envPath, version string) error {
-	if err := validateUpgradeVersion(version); err != nil {
-		return err
-	}
-	mode, err := fileModeOrDefault(envPath, 0o600)
-	if err != nil {
-		return err
-	}
-	data, err := os.ReadFile(envPath)
-	if err != nil {
-		return err
-	}
-	lines := strings.Split(string(data), "\n")
-	replaced := false
-	for i, line := range lines {
-		if strings.HasPrefix(line, "FLUX_VERSION=") {
-			lines[i] = "FLUX_VERSION=" + version
-			replaced = true
-		}
-	}
-	if !replaced {
-		trimmed := strings.TrimRight(strings.Join(lines, "\n"), "\n")
-		if trimmed == "" {
-			trimmed = "FLUX_VERSION=" + version
-		} else {
-			trimmed += "\nFLUX_VERSION=" + version
-		}
-		return writeFileWithMode(envPath, []byte(trimmed+"\n"), mode)
-	}
-	content := strings.TrimRight(strings.Join(lines, "\n"), "\n") + "\n"
-	return writeFileWithMode(envPath, []byte(content), mode)
-}
-
-func (e *systemUpgradeExecutor) backupFile(path string) (string, error) {
-	mode, err := fileModeOrDefault(path, 0o600)
-	if err != nil {
-		return "", err
-	}
-	data, err := os.ReadFile(path)
-	if err != nil {
-		return "", err
-	}
-	backupPath := path + ".upgrade.bak"
-	if err := writeFileWithMode(backupPath, data, mode); err != nil {
-		return "", err
-	}
-	return backupPath, nil
-}
-
-func (e *systemUpgradeExecutor) restoreBackup(path string) error {
-	backupPath := path + ".upgrade.bak"
-	mode, err := fileModeOrDefault(backupPath, 0o600)
-	if err != nil {
-		return err
-	}
-	data, err := os.ReadFile(backupPath)
-	if err != nil {
-		return err
-	}
-	return writeFileWithMode(path, data, mode)
-}
-
-func (e *systemUpgradeExecutor) restoreUpgradeBackups(paths ...string) error {
-	var errs []string
-	for _, path := range paths {
-		if err := e.restoreBackup(path); err != nil {
-			errs = append(errs, fmt.Sprintf("%s: %v", path, err))
-		}
-	}
-	if len(errs) > 0 {
-		return fmt.Errorf("%s", strings.Join(errs, "; "))
-	}
-	return nil
-}
-
-func (e *systemUpgradeExecutor) replaceCompose(path string, data []byte) error {
-	if len(bytes.TrimSpace(data)) == 0 {
-		return fmt.Errorf("compose asset is empty")
-	}
-	mode, err := fileModeOrDefault(path, 0o644)
-	if err != nil {
-		return err
-	}
-	return writeFileWithMode(path, data, mode)
-}
-
 func (h *Handler) buildSystemUpgradeDownloadURL(version, filename string) string {
 	enabled, proxyURL := h.getGithubProxyConfig()
 	base := fmt.Sprintf("%s/%s/releases/download/%s/%s", strings.TrimRight(systemUpgradeReleaseBaseURL, "/"), githubRepo, version, filename)
@@ -383,55 +239,6 @@ func (h *Handler) resolveSystemUpgradeLatestReleaseByChannel(channel string) (st
 	return "", fmt.Errorf("未找到%s版本号", releaseChannelLabel(normalizedChannel))
 }
 
-func fileModeOrDefault(path string, fallback os.FileMode) (os.FileMode, error) {
-	info, err := os.Stat(path)
-	if err != nil {
-		if os.IsNotExist(err) {
-			return fallback, nil
-		}
-		return 0, err
-	}
-	return info.Mode().Perm(), nil
-}
-
-func writeFileWithMode(path string, data []byte, mode os.FileMode) error {
-	if err := os.WriteFile(path, data, mode); err != nil {
-		return err
-	}
-	return os.Chmod(path, mode)
-}
-
-func (e *systemUpgradeExecutor) currentBackendImage(ctx context.Context) (string, error) {
-	if err := validateBackendContainerName(e.backendContainer); err != nil {
-		return "", err
-	}
-	out, err := exec.CommandContext(ctx, "docker", "inspect", "-f", "{{.Image}}", e.backendContainer).CombinedOutput()
-	if err != nil {
-		return "", fmt.Errorf("inspect backend image failed: %v: %s", err, strings.TrimSpace(string(out)))
-	}
-	imageID := strings.TrimSpace(string(out))
-	if imageID == "" {
-		return "", fmt.Errorf("backend image id is empty")
-	}
-	return imageID, nil
-}
-
-func (e *systemUpgradeExecutor) startHelper(ctx context.Context, imageID, helperName string) (string, error) {
-	args, err := e.buildHelperRunArgs(imageID, helperName)
-	if err != nil {
-		return "", err
-	}
-	out, err := exec.CommandContext(ctx, "docker", args...).CombinedOutput()
-	if err != nil {
-		return "", fmt.Errorf("start helper failed: %v: %s", err, strings.TrimSpace(string(out)))
-	}
-	containerID := strings.TrimSpace(string(out))
-	if containerID == "" {
-		containerID = helperName
-	}
-	return containerID, nil
-}
-
 func (h *Handler) downloadReleaseAsset(version, filename string) ([]byte, error) {
 	url := h.buildSystemUpgradeDownloadURL(version, filename)
 	client := &http.Client{Timeout: 60 * time.Second}
@@ -485,16 +292,26 @@ func releasesForChannel(releases []githubRelease, channel string) []systemUpgrad
 
 func decodeSystemUpgradeRequest(r *http.Request, req *systemUpgradeRequest) error {
 	defer r.Body.Close()
-	body, err := io.ReadAll(r.Body)
+	body, err := io.ReadAll(io.LimitReader(r.Body, 4097))
 	if err != nil {
 		return err
 	}
+	if len(body) > 4096 {
+		return fmt.Errorf("request too large")
+	}
 	if len(bytes.TrimSpace(body)) == 0 {
 		return nil
 	}
 	decoder := json.NewDecoder(bytes.NewReader(body))
 	decoder.DisallowUnknownFields()
-	return decoder.Decode(req)
+	if err := decoder.Decode(req); err != nil {
+		return err
+	}
+	var extra any
+	if decoder.Decode(&extra) != io.EOF {
+		return fmt.Errorf("unexpected trailing JSON")
+	}
+	return nil
 }
 
 func systemUpgradeVersionResponse(current, channel, latest string, lookupErr error, capability systemUpgradeCapabilityData) systemUpgradeVersionData {
@@ -595,63 +412,63 @@ func (h *Handler) systemUpgrade(w http.ResponseWriter, r *http.Request) {
 			return
 		}
 	}
-	imageID, err := exec.currentBackendImage(r.Context())
-	if err != nil {
-		response.WriteJSON(w, response.Err(-2, err.Error()))
+
+	if err := validateUpgradeVersion(version); err != nil {
+		response.WriteJSON(w, response.ErrDefault("版本号格式无效"))
 		return
 	}
-
-	composePath := exec.composePath()
-	envPath := exec.envPath()
-	composeData, err := os.ReadFile(composePath)
+	composeData, err := os.ReadFile(exec.composePath())
 	if err != nil {
-		response.WriteJSON(w, response.Err(-2, "读取compose失败: "+err.Error()))
+		response.WriteJSON(w, response.ErrDefault("读取部署配置失败"))
 		return
 	}
 	composeAsset := exec.selectComposeAsset(composeData)
 	newCompose, err := h.downloadReleaseAsset(version, composeAsset)
 	if err != nil {
-		response.WriteJSON(w, response.Err(-2, err.Error()))
+		response.WriteJSON(w, response.ErrDefault("下载目标 Compose 失败"))
 		return
 	}
-	if _, err := exec.backupFile(composePath); err != nil {
-		response.WriteJSON(w, response.Err(-2, "备份compose失败: "+err.Error()))
-		return
-	}
-	if _, err := exec.backupFile(envPath); err != nil {
-		response.WriteJSON(w, response.Err(-2, "备份.env失败: "+err.Error()))
-		return
-	}
-	if err := exec.replaceCompose(composePath, newCompose); err != nil {
-		if restoreErr := exec.restoreUpgradeBackups(composePath, envPath); restoreErr != nil {
-			err = fmt.Errorf("%v; 回滚失败: %v", err, restoreErr)
-		}
-		response.WriteJSON(w, response.Err(-2, "替换compose失败: "+err.Error()))
-		return
-	}
-	if err := exec.updateEnvVersion(envPath, version); err != nil {
-		if restoreErr := exec.restoreUpgradeBackups(composePath, envPath); restoreErr != nil {
-			err = fmt.Errorf("%v; 回滚失败: %v", err, restoreErr)
-		}
-		response.WriteJSON(w, response.Err(-2, "更新版本配置失败: "+err.Error()))
-		return
-	}
-	helperName := fmt.Sprintf("flvx-upgrade-helper-%d", time.Now().Unix())
-	helperContainer, err := exec.startHelper(r.Context(), imageID, helperName)
+	// A detached helper must not be canceled when the browser disconnects.
+	ctx, cancel := context.WithTimeout(context.Background(), 90*time.Second)
+	defer cancel()
+	job, imageID, err := (panelupgrade.Manager{Dir: exec.deployDir, Backend: exec.backendContainer}).Start(ctx, version, newCompose)
 	if err != nil {
-		if restoreErr := exec.restoreUpgradeBackups(composePath, envPath); restoreErr != nil {
-			err = fmt.Errorf("%v; 回滚失败: %v", err, restoreErr)
-		}
-		response.WriteJSON(w, response.Err(-2, err.Error()))
+		response.WriteJSON(w, response.ErrDefault(err.Error()))
 		return
 	}
-
-	response.WriteJSON(w, response.OK(systemUpgradeRunData{
-		Version:         version,
-		Channel:         channel,
-		ComposeAsset:    composeAsset,
-		HelperContainer: helperContainer,
-		BackendImageID:  imageID,
-		Message:         systemUpgradeMessage,
-	}))
+	response.WriteJSON(w, response.OK(systemUpgradeRunData{JobID: job.ID, Version: version, Channel: channel, ComposeAsset: composeAsset, HelperContainer: job.HelperContainer, BackendImageID: imageID, Message: systemUpgradeMessage}))
+}
+
+func (h *Handler) systemUpgradeStatus(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		response.WriteJSON(w, response.ErrDefault("请求失败"))
+		return
+	}
+	var req struct {
+		JobID string `json:"jobId"`
+	}
+	defer r.Body.Close()
+	decoder := json.NewDecoder(io.LimitReader(r.Body, 4097))
+	decoder.DisallowUnknownFields()
+	if err := decoder.Decode(&req); err != nil && err != io.EOF {
+		response.WriteJSON(w, response.ErrDefault("请求参数错误"))
+		return
+	}
+	var extra any
+	if decoder.Decode(&extra) != io.EOF {
+		response.WriteJSON(w, response.ErrDefault("请求参数错误"))
+		return
+	}
+	e := newSystemUpgradeExecutor()
+	ctx, cancel := context.WithTimeout(r.Context(), 5*time.Second)
+	defer cancel()
+	job, err := (panelupgrade.Manager{Dir: e.deployDir, Backend: e.backendContainer}).Status(ctx, req.JobID)
+	if err != nil {
+		response.WriteJSON(w, response.ErrDefault("无法读取升级任务状态"))
+		return
+	}
+	response.WriteJSON(w, response.OK(struct {
+		CurrentVersion string            `json:"currentVersion"`
+		Job            *panelupgrade.Job `json:"job"`
+	}{currentPanelVersion(), job}))
 }

go-backend/internal/http/handler/system_upgrade_test.go

@@ -8,7 +8,6 @@ import (
 	"net/http/httptest"
 	"os"
 	"path/filepath"
-	"reflect"
 	"strings"
 	"testing"
 	"time"
@@ -128,149 +127,12 @@ func TestSelectComposeAssetFallsBackToIPv4Template(t *testing.T) {
 	}
 }
 
-func TestUpdateEnvVersionReplacesExistingValue(t *testing.T) {
-	dir := t.TempDir()
-	envPath := filepath.Join(dir, ".env")
-	if err := os.WriteFile(envPath, []byte("FLUX_VERSION=2.1.8\nJWT_SECRET=test\n"), 0o644); err != nil {
-		t.Fatalf("WriteFile() error = %v", err)
-	}
-
-	exec := &systemUpgradeExecutor{deployDir: dir, backendContainer: "flux-panel-backend"}
-	if err := exec.updateEnvVersion(envPath, "2.1.9"); err != nil {
-		t.Fatalf("updateEnvVersion() error = %v", err)
-	}
-
-	data, err := os.ReadFile(envPath)
-	if err != nil {
-		t.Fatalf("ReadFile() error = %v", err)
-	}
-
-	want := "FLUX_VERSION=2.1.9\nJWT_SECRET=test\n"
-	if string(data) != want {
-		t.Fatalf("env content = %q, want %q", string(data), want)
-	}
-}
-
-func TestUpdateEnvVersionAppendsMissingValue(t *testing.T) {
-	dir := t.TempDir()
-	envPath := filepath.Join(dir, ".env")
-	if err := os.WriteFile(envPath, []byte("JWT_SECRET=test\n"), 0o644); err != nil {
-		t.Fatalf("WriteFile() error = %v", err)
-	}
-
-	exec := &systemUpgradeExecutor{deployDir: dir, backendContainer: "flux-panel-backend"}
-	if err := exec.updateEnvVersion(envPath, "2.1.9"); err != nil {
-		t.Fatalf("updateEnvVersion() error = %v", err)
-	}
-
-	data, err := os.ReadFile(envPath)
-	if err != nil {
-		t.Fatalf("ReadFile() error = %v", err)
-	}
-
-	want := "JWT_SECRET=test\nFLUX_VERSION=2.1.9\n"
-	if string(data) != want {
-		t.Fatalf("env content = %q, want %q", string(data), want)
-	}
-}
-
-func TestUpdateEnvVersionRejectsUnsafeValue(t *testing.T) {
-	for _, version := range []string{"", "2.1.9\nJWT_SECRET=bad", "2.1.9\rbad", "2.1.9\x00bad", "2.1.9\x1fbad"} {
-		t.Run(version, func(t *testing.T) {
-			dir := t.TempDir()
-			envPath := filepath.Join(dir, ".env")
-			original := []byte("JWT_SECRET=test\n")
-			if err := os.WriteFile(envPath, original, 0o644); err != nil {
-				t.Fatalf("WriteFile() error = %v", err)
-			}
-
-			exec := &systemUpgradeExecutor{deployDir: dir, backendContainer: "flux-panel-backend"}
-			if err := exec.updateEnvVersion(envPath, version); err == nil {
-				t.Fatal("expected unsafe version to fail validation")
-			}
-
-			data, err := os.ReadFile(envPath)
-			if err != nil {
-				t.Fatalf("ReadFile() error = %v", err)
-			}
-			if string(data) != string(original) {
-				t.Fatalf("env content changed to %q, want %q", string(data), string(original))
-			}
-		})
-	}
-}
-
-func TestUpdateEnvVersionAcceptsVersionLabels(t *testing.T) {
-	for _, version := range []string{"2.1.9", "2.1.9-beta14", "v-test"} {
-		t.Run(version, func(t *testing.T) {
-			dir := t.TempDir()
-			envPath := filepath.Join(dir, ".env")
-			if err := os.WriteFile(envPath, []byte("JWT_SECRET=test\n"), 0o644); err != nil {
-				t.Fatalf("WriteFile() error = %v", err)
-			}
-
-			exec := &systemUpgradeExecutor{deployDir: dir, backendContainer: "flux-panel-backend"}
-			if err := exec.updateEnvVersion(envPath, version); err != nil {
-				t.Fatalf("updateEnvVersion() error = %v", err)
-			}
-		})
-	}
-}
-
-func TestUpdateEnvVersionPreservesFileMode(t *testing.T) {
-	dir := t.TempDir()
-	envPath := filepath.Join(dir, ".env")
-	if err := os.WriteFile(envPath, []byte("FLUX_VERSION=2.1.8\nJWT_SECRET=test\n"), 0o600); err != nil {
-		t.Fatalf("WriteFile() error = %v", err)
-	}
-
-	exec := &systemUpgradeExecutor{deployDir: dir, backendContainer: "flux-panel-backend"}
-	if err := exec.updateEnvVersion(envPath, "2.1.9"); err != nil {
-		t.Fatalf("updateEnvVersion() error = %v", err)
-	}
-
-	info, err := os.Stat(envPath)
-	if err != nil {
-		t.Fatalf("Stat() error = %v", err)
-	}
-	if got := info.Mode().Perm(); got != 0o600 {
-		t.Fatalf("env mode = %o, want 0600", got)
-	}
-}
-
 func TestValidateBackendContainerNameRejectsUnsafeValue(t *testing.T) {
 	if err := validateBackendContainerName("flux-panel-backend;rm -rf /"); err == nil {
 		t.Fatal("expected unsafe container name to fail validation")
 	}
 }
 
-func TestBuildHelperRunArgsUsesDetachedContainer(t *testing.T) {
-	exec := &systemUpgradeExecutor{deployDir: "/opt/flvx-panel", backendContainer: "flux-panel-backend"}
-	args, err := exec.buildHelperRunArgs("sha256:abc", "flvx-upgrade-helper")
-	if err != nil {
-		t.Fatalf("buildHelperRunArgs() error = %v", err)
-	}
-	want := []string{
-		"run", "-d", "--rm", "--name", "flvx-upgrade-helper",
-		"--volumes-from", "flux-panel-backend",
-		"-v", "/var/run/docker.sock:/var/run/docker.sock",
-		"-e", "PANEL_DEPLOY_DIR=/opt/flvx-panel",
-		"--entrypoint", "/bin/sh", "sha256:abc",
-		"-c", exec.helperScript(),
-	}
-
-	if !reflect.DeepEqual(args, want) {
-		t.Fatalf("buildHelperRunArgs() = %#v, want %#v", args, want)
-	}
-}
-
-func TestBuildHelperRunArgsRejectsUnsafeBackendContainer(t *testing.T) {
-	exec := &systemUpgradeExecutor{deployDir: "/opt/flvx-panel", backendContainer: "flux-panel-backend;rm -rf /"}
-	if _, err := exec.buildHelperRunArgs("sha256:abc", "flvx-upgrade-helper"); err == nil {
-		t.Fatal("expected unsafe backend container name to fail validation")
-	}
-}
-
 func TestSystemVersionRejectsWrongMethod(t *testing.T) {
 	h := &Handler{}
 	req := httptest.NewRequest(http.MethodGet, "/api/v1/system/version", nil)
@@ -350,64 +212,6 @@ func TestSystemUpgradeFailsFastBeforeMutatingFiles(t *testing.T) {
 	}
 }
 
-func TestUpgradeBackupUsesStablePathAndRestoreRestoresOriginal(t *testing.T) {
-	dir := t.TempDir()
-	path := filepath.Join(dir, "docker-compose.yml")
-	if err := os.WriteFile(path, []byte("original"), 0o644); err != nil {
-		t.Fatalf("WriteFile() error = %v", err)
-	}
-
-	exec := &systemUpgradeExecutor{deployDir: dir, backendContainer: "flux-panel-backend"}
-	backupPath, err := exec.backupFile(path)
-	if err != nil {
-		t.Fatalf("backupFile() error = %v", err)
-	}
-	if backupPath != path+".upgrade.bak" {
-		t.Fatalf("backup path = %q, want %q", backupPath, path+".upgrade.bak")
-	}
-	if err := os.WriteFile(path, []byte("mutated"), 0o644); err != nil {
-		t.Fatalf("WriteFile() error = %v", err)
-	}
-
-	if err := exec.restoreBackup(path); err != nil {
-		t.Fatalf("restoreBackup() error = %v", err)
-	}
-	data, err := os.ReadFile(path)
-	if err != nil {
-		t.Fatalf("ReadFile() error = %v", err)
-	}
-	if string(data) != "original" {
-		t.Fatalf("restored content = %q, want original", string(data))
-	}
-}
-
-func TestRestoreBackupPreservesOriginalFileMode(t *testing.T) {
-	dir := t.TempDir()
-	path := filepath.Join(dir, ".env")
-	if err := os.WriteFile(path, []byte("FLUX_VERSION=2.1.8\nJWT_SECRET=test\n"), 0o600); err != nil {
-		t.Fatalf("WriteFile() error = %v", err)
-	}
-
-	exec := &systemUpgradeExecutor{deployDir: dir, backendContainer: "flux-panel-backend"}
-	if _, err := exec.backupFile(path); err != nil {
-		t.Fatalf("backupFile() error = %v", err)
-	}
-	if err := os.Remove(path); err != nil {
-		t.Fatalf("Remove() error = %v", err)
-	}
-	if err := exec.restoreBackup(path); err != nil {
-		t.Fatalf("restoreBackup() error = %v", err)
-	}
-
-	info, err := os.Stat(path)
-	if err != nil {
-		t.Fatalf("Stat() error = %v", err)
-	}
-	if got := info.Mode().Perm(); got != 0o600 {
-		t.Fatalf("restored mode = %o, want 0600", got)
-	}
-}
-
 func TestDecodeSystemUpgradeRequestRejectsTruncatedJSON(t *testing.T) {
 	req := httptest.NewRequest(http.MethodPost, "/api/v1/system/check-updates", strings.NewReader(`{"channel":"stable"`))
 	var payload systemUpgradeRequest

go-backend/internal/http/handler/traffic_limit.go

@@ -0,0 +1,28 @@
+package handler
+
+import (
+	"fmt"
+	"math"
+	"strconv"
+)
+
+// flowMiB is optional so older clients can keep sending the GB-based flow field.
+// A positive value takes precedence and preserves sub-GB limits exactly.
+func parseTrafficLimit(req map[string]interface{}, defaultGB int64) (flowGB, flowMiB int64, err error) {
+	flowGB = asInt64(req["flow"], defaultGB)
+	if flowGB < 0 {
+		return 0, 0, fmt.Errorf("流量限制不能小于0")
+	}
+	raw, present := req["flowMiB"]
+	if !present {
+		return flowGB, 0, nil
+	}
+	flowMiB, err = strconv.ParseInt(asString(raw), 10, 64)
+	if err != nil || flowMiB < 0 || flowMiB > math.MaxInt64/bytesPerMiB {
+		return 0, 0, fmt.Errorf("流量限制超出范围")
+	}
+	if flowMiB > 0 {
+		flowGB = (flowMiB-1)/1024 + 1
+	}
+	return flowGB, flowMiB, nil
+}

go-backend/internal/http/handler/traffic_limit_test.go

@@ -0,0 +1,39 @@
+package handler
+
+import (
+	"testing"
+	"time"
+)
+
+func TestTrafficLimitMiBOverridesLegacyGB(t *testing.T) {
+	flowGB, flowMiB, err := parseTrafficLimit(map[string]interface{}{
+		"flow": float64(1), "flowMiB": float64(500),
+	}, 100)
+	if err != nil || flowGB != 1 || flowMiB != 500 {
+		t.Fatalf("parseTrafficLimit = (%d, %d, %v), want (1, 500, nil)", flowGB, flowMiB, err)
+	}
+	limit := flowLimitBytes(flowGB, flowMiB)
+	if limit != 500*bytesPerMiB {
+		t.Fatalf("limit = %d, want %d", limit, 500*bytesPerMiB)
+	}
+	policy := &userTunnelPolicy{Flow: flowGB, FlowMiB: flowMiB, InFlow: limit - 1, Status: 1}
+	if shouldPauseUserTunnel(policy, time.Now().UnixMilli()) {
+		t.Fatal("policy paused before reaching 500 MiB")
+	}
+	policy.InFlow = limit
+	if !shouldPauseUserTunnel(policy, time.Now().UnixMilli()) {
+		t.Fatal("policy did not pause at 500 MiB")
+	}
+}
+
+func TestTrafficLimitLegacyAndInvalidValues(t *testing.T) {
+	flowGB, flowMiB, err := parseTrafficLimit(map[string]interface{}{"flow": float64(2)}, 100)
+	if err != nil || flowGB != 2 || flowMiB != 0 || flowLimitBytes(flowGB, flowMiB) != 2*bytesPerGB {
+		t.Fatalf("legacy GB limit changed: (%d, %d, %v)", flowGB, flowMiB, err)
+	}
+	for _, value := range []interface{}{"1.5", -1, "999999999999999999999"} {
+		if _, _, err := parseTrafficLimit(map[string]interface{}{"flowMiB": value}, 100); err == nil {
+			t.Fatalf("accepted invalid flowMiB %v", value)
+		}
+	}
+}

go-backend/internal/http/handler/tunnel_delete_resolution.go

@@ -371,6 +371,8 @@ func summarizeTunnelDeleteRuleFailures(failures []batchFailureDetail) string {
 }
 
 func (h *Handler) processTunnelDeleteWithForwards(tunnelID int64, action string, targetTunnelID int64) (tunnelDeleteWithForwardsResult, []batchFailureDetail, error) {
+	unlock := h.lockTunnelLifecycle(tunnelID, targetTunnelID)
+	defer unlock()
 	preview, err := h.buildTunnelDeletePreview(tunnelID)
 	if err != nil {
 		return tunnelDeleteWithForwardsResult{}, nil, err
@@ -431,9 +433,14 @@ func (h *Handler) processTunnelDeleteReplaceAction(tunnelID, targetTunnelID int6
 	}
 
 	if err := h.deleteTunnelAndCleanup(tunnelID); err != nil {
-		h.rollbackTunnelForwardMigrationPlans(plans)
-		_ = h.redeployTunnelAndForwards(tunnelID)
-		return tunnelDeleteWithForwardsResult{}, nil, err
+		var pending *tunnelDeletionCleanupPendingError
+		if errors.As(err, &pending) {
+			warnings = append(warnings, err.Error())
+		} else {
+			h.rollbackTunnelForwardMigrationPlans(plans)
+			_ = h.redeployTunnelAndForwardsLocked(tunnelID)
+			return tunnelDeleteWithForwardsResult{}, nil, err
+		}
 	}
 
 	result.MigratedCount = len(plans)
@@ -639,8 +646,9 @@ func (h *Handler) rollbackTunnelForwardMigrationPlans(plans []tunnelForwardMigra
 }
 
 func (h *Handler) deleteTunnelAndCleanup(tunnelID int64) error {
-	h.cleanupTunnelRuntime(tunnelID)
-	h.cleanupFederationRuntime(tunnelID)
+	if err := h.cleanupFederationRuntime(tunnelID); err != nil {
+		return err
+	}
 	if err := h.deleteTunnelByID(tunnelID); err != nil {
 		return err
 	}

go-backend/internal/http/handler/tunnel_lifecycle.go

@@ -0,0 +1,153 @@
+package handler
+
+import (
+	"database/sql"
+	"errors"
+	"go-backend/internal/http/response"
+	"gorm.io/gorm"
+	"slices"
+	"sort"
+	"sync"
+)
+
+type tunnelLifecycleLock struct {
+	mu    sync.Mutex
+	users int
+}
+
+// lockTunnelLifecycle serializes snapshots, persistence and node acknowledgements.
+// Multiple tunnels (forward migration) are locked in ID order to avoid deadlocks.
+// Callers must not acquire these locks recursively or hold a database transaction.
+func (h *Handler) lockTunnelLifecycle(ids ...int64) func() {
+	unique := make(map[int64]bool, len(ids))
+	ordered := make([]int64, 0, len(ids))
+	for _, id := range ids {
+		if id > 0 && !unique[id] {
+			unique[id] = true
+			ordered = append(ordered, id)
+		}
+	}
+	sort.Slice(ordered, func(i, j int) bool { return ordered[i] < ordered[j] })
+	locks := make([]*tunnelLifecycleLock, 0, len(ordered))
+	for _, id := range ordered {
+		h.tunnelLifecycleMu.Lock()
+		if h.tunnelLifecycleLocks == nil {
+			h.tunnelLifecycleLocks = make(map[int64]*tunnelLifecycleLock)
+		}
+		lock := h.tunnelLifecycleLocks[id]
+		if lock == nil {
+			lock = &tunnelLifecycleLock{}
+			h.tunnelLifecycleLocks[id] = lock
+		}
+		lock.users++
+		h.tunnelLifecycleMu.Unlock()
+		lock.mu.Lock()
+		locks = append(locks, lock)
+	}
+	return func() {
+		for i := len(locks) - 1; i >= 0; i-- {
+			h.tunnelLifecycleMu.Lock()
+			locks[i].mu.Unlock()
+			locks[i].users--
+			if locks[i].users == 0 {
+				delete(h.tunnelLifecycleLocks, ordered[i])
+			}
+			h.tunnelLifecycleMu.Unlock()
+		}
+	}
+}
+
+// Probes run without the lifecycle lock. Recheck their topology under the lock
+// so a late result cannot restore a removed middle hop or deleted tunnel.
+func (h *Handler) validateBestExitSnapshot(tunnelID, ownerNodeID int64, exits []chainNodeRecord, ipPreference string) error {
+	tunnel, err := h.getTunnelRecord(tunnelID)
+	if err != nil {
+		return err
+	}
+	if tunnel.Type != 2 || h.repo.GetTunnelIPPreference(tunnelID) != ipPreference {
+		return errors.New("best exit topology changed; retry next probe")
+	}
+	rows, err := h.listChainNodesForTunnel(tunnelID)
+	if err != nil {
+		return err
+	}
+	ins, hops, currentExits := splitChainNodeGroups(rows)
+	if !slices.Equal(exits, currentExits) {
+		return errors.New("best exit targets changed; retry next probe")
+	}
+	for _, owner := range bestExitChainOwners(ins, hops) {
+		if owner.NodeID == ownerNodeID {
+			return nil
+		}
+	}
+	return errors.New("best exit owner changed; retry next probe")
+}
+
+// A newly allocated ID is not visible yet. Claim it without waiting while the
+// insert transaction is open: an overlapping request for that ID must not make
+// creation wait on a lifecycle lock whose owner is waiting for this transaction.
+func (h *Handler) tryLockNewTunnelLifecycle(id int64) (func(), bool) {
+	h.tunnelLifecycleMu.Lock()
+	defer h.tunnelLifecycleMu.Unlock()
+	if h.tunnelLifecycleLocks == nil {
+		h.tunnelLifecycleLocks = make(map[int64]*tunnelLifecycleLock)
+	}
+	if h.tunnelLifecycleLocks[id] != nil {
+		return nil, false
+	}
+	lock := &tunnelLifecycleLock{users: 1}
+	lock.mu.Lock()
+	h.tunnelLifecycleLocks[id] = lock
+	return func() {
+		h.tunnelLifecycleMu.Lock()
+		defer h.tunnelLifecycleMu.Unlock()
+		lock.mu.Unlock()
+		lock.users--
+		if lock.users == 0 {
+			delete(h.tunnelLifecycleLocks, id)
+		}
+	}, true
+}
+
+// Pending is not successful application. HTTP create/update retain their
+// accepted-config contract, while redeploy returns this error to its batch result.
+type tunnelRuntimePendingError struct{ cause error }
+
+func (e *tunnelRuntimePendingError) Error() string { return "运行时待同步: " + e.cause.Error() }
+func isTunnelRuntimePending(err error) bool {
+	var pending *tunnelRuntimePendingError
+	return errors.As(err, &pending)
+}
+func tunnelRuntimePendingResponse(tunnelID int64, err error) response.R {
+	message := "配置已保存，部分节点运行时待同步：" + err.Error()
+	out := response.OK(map[string]interface{}{"runtimeStatus": "pending", "tunnelId": tunnelID, "message": message})
+	out.Msg = message
+	return out
+}
+
+// Reserve locally allocated ports with the initial desired state, before any
+// remote acknowledgment. Remote ports remain unallocated until their provider
+// returns; the second transaction replaces these rows with the final bindings.
+func (h *Handler) persistPreparedTunnelChainsTx(tx *gorm.DB, state *tunnelCreateState) error {
+	save := func(node tunnelRuntimeNode, kind string, inx int) error {
+		return h.repo.CreateChainTunnelTx(tx, state.TunnelID, kind, node.NodeID, sql.NullInt64{Int64: int64(node.Port), Valid: node.Port > 0}, defaultString(node.Strategy, "round"), inx, defaultString(node.Protocol, "tls"), node.ConnectIP)
+	}
+	for i, node := range state.InNodes {
+		if err := save(node, "1", i+1); err != nil {
+			return err
+		}
+	}
+	for i, node := range state.OutNodes {
+		if err := save(node, "3", i+1); err != nil {
+			return err
+		}
+	}
+	for i, hop := range state.ChainHops {
+		for _, node := range hop {
+			if err := save(node, "2", i+1); err != nil {
+				return err
+			}
+		}
+	}
+	return nil
+}

go-backend/internal/http/handler/tunnel_runtime_cleanup.go

@@ -0,0 +1,180 @@
+package handler
+
+import (
+	"errors"
+	"fmt"
+	"go-backend/internal/store/model"
+	"gorm.io/gorm"
+)
+
+func tunnelStateRuntimeRows(state *tunnelCreateState) []chainNodeRecord {
+	if state.Type != 2 {
+		return nil
+	}
+	var rows []chainNodeRecord
+	for _, n := range state.InNodes {
+		rows = append(rows, chainNodeRecord{NodeID: n.NodeID, ChainType: 1})
+	}
+	for _, hop := range state.ChainHops {
+		for _, n := range hop {
+			rows = append(rows, chainNodeRecord{NodeID: n.NodeID, ChainType: 2, Port: n.Port})
+		}
+	}
+	for _, n := range state.OutNodes {
+		rows = append(rows, chainNodeRecord{NodeID: n.NodeID, ChainType: 3, Port: n.Port})
+	}
+	return rows
+}
+func (h *Handler) queueObsoleteTunnelRuntimeTx(tx *gorm.DB, tunnelID int64, oldRows, newRows []chainNodeRecord) error {
+	var items []model.TunnelRuntimeCleanup
+	for _, nodeID := range removedTunnelRuntimeNodeIDs(oldRows, newRows, tunnelRuntimeNeedsService) {
+		port := 0
+		for _, row := range oldRows {
+			if row.NodeID == nodeID {
+				port = row.Port
+				break
+			}
+		}
+		items = append(items, model.TunnelRuntimeCleanup{TunnelID: tunnelID, NodeID: nodeID, Kind: "service", Port: port})
+	}
+	for _, old := range oldRows {
+		if !tunnelRuntimeNeedsService(old) {
+			continue
+		}
+		for _, current := range newRows {
+			if current.NodeID == old.NodeID && tunnelRuntimeNeedsService(current) && (current.Port != old.Port || current.ChainType != old.ChainType) {
+				items = append(items, model.TunnelRuntimeCleanup{TunnelID: tunnelID, NodeID: old.NodeID, Kind: "service", Port: old.Port})
+			}
+		}
+	}
+	for _, nodeID := range removedTunnelRuntimeNodeIDs(oldRows, newRows, tunnelRuntimeNeedsChain) {
+		items = append(items, model.TunnelRuntimeCleanup{TunnelID: tunnelID, NodeID: nodeID, Kind: "chain"})
+	}
+	return h.repo.QueueTunnelRuntimeCleanupTx(tx, items)
+}
+
+// Caller holds the tunnel lifecycle lock. Recheck current desired roles before
+// every retry so a delayed deletion cannot remove a re-added runtime.
+func (h *Handler) retryTunnelRuntimeCleanupLocked(tunnelID int64) error {
+	items, err := h.repo.ListTunnelRuntimeCleanup(tunnelID)
+	if err != nil {
+		return err
+	}
+	if len(items) == 0 {
+		return nil
+	}
+	tunnel, err := h.repo.GetTunnelRecord(tunnelID)
+	if err != nil {
+		return err
+	}
+	var rows []chainNodeRecord
+	if tunnel != nil && tunnel.Type == 2 {
+		rows, err = h.listChainNodesForTunnel(tunnelID)
+		if err != nil {
+			return err
+		}
+	}
+	var failures []error
+	liveServices := map[int64]bool{}
+	for _, item := range items {
+		desired := false
+		for _, row := range rows {
+			if row.NodeID == item.NodeID && ((item.Kind == "service" && tunnelRuntimeNeedsService(row)) || (item.Kind == "chain" && tunnelRuntimeNeedsChain(row))) {
+				desired = true
+				break
+			}
+		}
+		if desired && item.Kind == "service" {
+			// Desired state does not prove that the old receiver was replaced.
+			// Keep this barrier (even at the same port) and protect its old
+			// chain until acknowledgeTunnelServiceReplacements observes ACK.
+			liveServices[item.NodeID] = true
+			continue
+		}
+		if !desired {
+			if item.Kind == "chain" && liveServices[item.NodeID] {
+				continue
+			}
+			var commandErr error
+			if item.Kind == "service" {
+				_, commandErr = h.sendNodeCommand(item.NodeID, "DeleteService", map[string]interface{}{"services": tunnelRuntimeServiceNames(tunnelID)}, false, true)
+			} else {
+				_, commandErr = h.sendNodeCommand(item.NodeID, "DeleteChains", map[string]interface{}{"chain": fmt.Sprintf("chains_%d", tunnelID)}, false, true)
+			}
+			if commandErr != nil {
+				if item.Kind == "service" {
+					liveServices[item.NodeID] = true
+				}
+				failures = append(failures, fmt.Errorf("节点 %d 旧运行时清理失败: %w", item.NodeID, commandErr))
+				continue
+			}
+		}
+		if err := h.repo.DeleteTunnelRuntimeCleanup(item.ID); err != nil {
+			if item.Kind == "service" {
+				liveServices[item.NodeID] = true
+			}
+			failures = append(failures, err)
+		}
+	}
+	return errors.Join(failures...)
+}
+
+func (h *Handler) acknowledgeTunnelServiceReplacements(tunnelID int64, nodeIDs []int64) error {
+	if len(nodeIDs) == 0 {
+		return nil
+	}
+	items, err := h.repo.ListTunnelRuntimeCleanup(tunnelID)
+	if err != nil {
+		return err
+	}
+	for _, item := range items {
+		if item.Kind == "service" {
+			for _, nodeID := range nodeIDs {
+				if item.NodeID == nodeID {
+					if err := h.repo.DeleteTunnelRuntimeCleanup(item.ID); err != nil {
+						return err
+					}
+					break
+				}
+			}
+		}
+	}
+	return nil
+}
+func (h *Handler) retryPendingTunnelRuntimeCleanup() error {
+	return h.retryPendingTunnelRuntimeCleanupOnNode(0)
+}
+
+func (h *Handler) retryPendingTunnelRuntimeCleanupOnNode(nodeID int64) error {
+	items, err := h.repo.ListTunnelRuntimeCleanup(0)
+	if err != nil {
+		return err
+	}
+	seen := map[int64]bool{}
+	var failures []error
+	for _, item := range items {
+		if nodeID > 0 && item.NodeID != nodeID {
+			continue
+		}
+		if seen[item.TunnelID] {
+			continue
+		}
+		seen[item.TunnelID] = true
+		unlock := h.lockTunnelLifecycle(item.TunnelID)
+		err := h.retryTunnelRuntimeCleanupLocked(item.TunnelID)
+		unlock()
+		if err != nil {
+			failures = append(failures, err)
+		}
+	}
+	return errors.Join(failures...)
+}
+
+// The desired tunnel has already been deleted; callers must not roll back a
+// completed forward migration merely because asynchronous cleanup is pending.
+type tunnelDeletionCleanupPendingError struct{ cause error }
+
+func (e *tunnelDeletionCleanupPendingError) Error() string {
+	return "隧道配置已删除，运行时清理待重试: " + e.cause.Error()
+}
+func (e *tunnelDeletionCleanupPendingError) Unwrap() error { return e.cause }

go-backend/internal/http/handler/upgrade.go

@@ -398,15 +398,83 @@ func (h *Handler) consumeNodePendingUpgradeRedeploy(nodeID int64) bool {
 }
 
 func (h *Handler) onNodeOnline(nodeID int64) {
+	if h == nil || h.repo == nil || h.wsServer == nil {
+		return
+	}
+	if node, err := h.getNodeRecord(nodeID); err == nil && (node == nil || node.Status != 1) {
+		return // The next connection will resume any pending reconciliation.
+	}
 	if !h.startNodeOnlineRedeploy(nodeID, time.Now()) {
 		return
 	}
 	defer h.finishNodeOnlineRedeploy(nodeID)
 
-	// Reconcile node runtime on the first reconnect, but suppress rapid flapping
-	// so websocket churn does not trigger repeated full redeploy storms.
-	if !h.redeployNodeRuntimeAfterUpgrade(nodeID) {
-		h.markNodePendingUpgradeRedeploy(nodeID)
+	// A fresh agent needs a full restore. Shared failures remain persisted and
+	// are retried by maintenance without restarting acknowledged services.
+	if err := h.retryPendingTunnelRuntimeCleanupOnNode(nodeID); err != nil {
+		fmt.Printf("reconnect obsolete tunnel cleanup remains pending: %v\n", err)
+	}
+	h.reconcileSharedNodeRuntime(nodeID)
+	if !h.redeployLocalNodeRuntime(nodeID) {
+		h.scheduleNodeLocalRuntimeRetry(nodeID)
+	} else {
+		h.clearNodeLocalRuntimeRetry(nodeID)
+	}
+}
+
+// Local retries are separate from reconnect reconciliation: a failed local
+// forward must not cause every shared listener to be replayed every 30 seconds.
+func (h *Handler) scheduleNodeLocalRuntimeRetry(nodeID int64) {
+	h.upgradeMu.Lock()
+	defer h.upgradeMu.Unlock()
+	if h.nodeLocalRuntimeRetryQueued == nil {
+		h.nodeLocalRuntimeRetryQueued = make(map[int64]struct{})
+	}
+	if _, queued := h.nodeLocalRuntimeRetryQueued[nodeID]; queued {
+		return
+	}
+	h.nodeLocalRuntimeRetryQueued[nodeID] = struct{}{}
+	time.AfterFunc(nodeOnlineRedeployCooldown, func() {
+		h.upgradeMu.Lock()
+		_, queued := h.nodeLocalRuntimeRetryQueued[nodeID]
+		delete(h.nodeLocalRuntimeRetryQueued, nodeID)
+		h.upgradeMu.Unlock()
+		if !queued {
+			return
+		}
+		h.retryNodeLocalRuntime(nodeID)
+	})
+}
+
+func (h *Handler) clearNodeLocalRuntimeRetry(nodeID int64) {
+	h.upgradeMu.Lock()
+	delete(h.nodeLocalRuntimeRetryQueued, nodeID)
+	h.upgradeMu.Unlock()
+}
+
+func (h *Handler) retryNodeLocalRuntime(nodeID int64) {
+	if h == nil || h.repo == nil || h.wsServer == nil {
+		return
+	}
+	if node, err := h.getNodeRecord(nodeID); err == nil && (node == nil || node.Status != 1) {
+		return
+	}
+	h.upgradeMu.Lock()
+	if _, inFlight := h.nodeOnlineRedeploying[nodeID]; inFlight {
+		h.upgradeMu.Unlock()
+		h.scheduleNodeLocalRuntimeRetry(nodeID)
+		return
+	}
+	if h.nodeOnlineRedeploying == nil {
+		h.nodeOnlineRedeploying = make(map[int64]struct{})
+	}
+	h.nodeOnlineRedeploying[nodeID] = struct{}{}
+	h.upgradeMu.Unlock()
+	defer h.finishNodeOnlineRedeploy(nodeID)
+	if !h.redeployLocalNodeRuntime(nodeID) {
+		h.scheduleNodeLocalRuntimeRetry(nodeID)
+	} else {
+		h.clearNodeLocalRuntimeRetry(nodeID)
 	}
 }
 
@@ -503,6 +571,26 @@ func (h *Handler) finishNodeOnlineRedeploy(nodeID int64) {
 }
 
 func (h *Handler) redeployNodeRuntimeAfterUpgrade(nodeID int64) bool {
+	cleanupOK := h.retryPendingTunnelRuntimeCleanupOnNode(nodeID) == nil
+	sharedOK := h.reconcileSharedNodeRuntime(nodeID)
+	localOK := h.redeployLocalNodeRuntime(nodeID)
+	return cleanupOK && sharedOK && localOK
+}
+
+func (h *Handler) reconcileSharedNodeRuntime(nodeID int64) bool {
+	succeeded := true
+	if err := h.reconcilePeerShareResourcesOnNode(nodeID); err != nil {
+		fmt.Printf("reconnect shared resource reconciliation failed on node %d: %v\n", nodeID, err)
+		succeeded = false
+	}
+	if err := h.reconcilePeerShareRoleRuntimesOnNode(nodeID); err != nil {
+		fmt.Printf("reconnect shared role reconciliation failed on node %d: %v\n", nodeID, err)
+		succeeded = false
+	}
+	return succeeded
+}
+
+func (h *Handler) redeployLocalNodeRuntime(nodeID int64) bool {
 	tunnelIDs, err := h.repo.ListActiveTunnelIDsByNode(nodeID)
 	if err != nil {
 		fmt.Printf("post-upgrade redeploy: list tunnels for node %d failed: %v\n", nodeID, err)
@@ -567,6 +655,7 @@ func (h *Handler) retryFailedRedeploys(nodeID int64, tunnelFailed map[int64]stru
 		return true
 	}
 
+	permanentFailure := false
 	const maxRetries = 3
 	baseDelay := time.Second
 
@@ -580,7 +669,8 @@ func (h *Handler) retryFailedRedeploys(nodeID int64, tunnelFailed map[int64]stru
 				delete(tunnelFailed, tunnelID)
 				fmt.Printf("post-upgrade redeploy retry: tunnel %d succeeded on node %d (attempt %d)\n", tunnelID, nodeID, attempt)
 			} else if !isRetryableError(err) {
-				delete(tunnelFailed, tunnelID) // Non-retryable, don't retry again
+				permanentFailure = true
+				delete(tunnelFailed, tunnelID) // Preserve failure while avoiding immediate retries.
 			} else {
 				fmt.Printf("post-upgrade redeploy retry: tunnel %d still failing on node %d (attempt %d): %v\n", tunnelID, nodeID, attempt, err)
 			}
@@ -596,7 +686,7 @@ func (h *Handler) retryFailedRedeploys(nodeID int64, tunnelFailed map[int64]stru
 			if err := h.syncForwardServices(ff.forward, "UpdateService", true); err == nil {
 				fmt.Printf("post-upgrade redeploy retry: forward %d succeeded on node %d (attempt %d)\n", ff.id, nodeID, attempt)
 			} else if !isRetryableError(err) {
-				// Non-retryable, drop it
+				permanentFailure = true // Keep reconciliation pending for a later reconnect.
 			} else {
 				stillFailed = append(stillFailed, ff)
 				fmt.Printf("post-upgrade redeploy retry: forward %d still failing on node %d (attempt %d): %v\n", ff.id, nodeID, attempt, err)
@@ -606,7 +696,7 @@ func (h *Handler) retryFailedRedeploys(nodeID int64, tunnelFailed map[int64]stru
 
 		if len(tunnelFailed) == 0 && len(failedForwards) == 0 {
 			fmt.Printf("post-upgrade redeploy retry: all items recovered on node %d\n", nodeID)
-			return true
+			return !permanentFailure
 		}
 	}
 

go-backend/internal/http/handler/upgrade_test.go

@@ -12,7 +12,7 @@ func TestStartNodeOnlineRedeploySkipsRecentReconnects(t *testing.T) {
 		nodeOnlineRedeployQueued: map[int64]struct{}{},
 		nodeOnlineRedeploying:    map[int64]struct{}{},
 	}
-	now := time.Unix(1_777_176_720, 0)
+	now := time.Now()
 
 	if !h.startNodeOnlineRedeploy(54, now) {
 		t.Fatalf("expected first reconnect to redeploy")
@@ -34,7 +34,7 @@ func TestStartNodeOnlineRedeployAllowsPendingUpgradeDuringCooldown(t *testing.T)
 		nodeOnlineRedeployQueued: map[int64]struct{}{},
 		nodeOnlineRedeploying:    map[int64]struct{}{},
 	}
-	now := time.Unix(1_777_176_720, 0)
+	now := time.Now()
 
 	if !h.startNodeOnlineRedeploy(54, now) {
 		t.Fatalf("expected first reconnect to redeploy")
@@ -57,7 +57,7 @@ func TestStartNodeOnlineRedeployQueuesCooldownReconnect(t *testing.T) {
 		nodeOnlineRedeployQueued: map[int64]struct{}{},
 		nodeOnlineRedeploying:    map[int64]struct{}{},
 	}
-	now := time.Unix(1_777_176_720, 0)
+	now := time.Now()
 
 	if !h.startNodeOnlineRedeploy(54, now) {
 		t.Fatalf("expected first reconnect to redeploy")
@@ -67,7 +67,10 @@ func TestStartNodeOnlineRedeployQueuesCooldownReconnect(t *testing.T) {
 	if h.startNodeOnlineRedeploy(54, now.Add(5*time.Second)) {
 		t.Fatalf("expected cooldown reconnect to skip immediate redeploy")
 	}
-	if _, queued := h.nodeOnlineRedeployQueued[54]; !queued {
+	h.upgradeMu.Lock()
+	_, queued := h.nodeOnlineRedeployQueued[54]
+	h.upgradeMu.Unlock()
+	if !queued {
 		t.Fatalf("expected cooldown reconnect to queue a follow-up redeploy")
 	}
 }
@@ -79,7 +82,7 @@ func TestStartNodeOnlineRedeployKeepsPendingUpgradeWhileInFlight(t *testing.T) {
 		nodeOnlineRedeployQueued: map[int64]struct{}{},
 		nodeOnlineRedeploying:    map[int64]struct{}{},
 	}
-	now := time.Unix(1_777_176_720, 0)
+	now := time.Now()
 
 	if !h.startNodeOnlineRedeploy(54, now) {
 		t.Fatalf("expected first reconnect to redeploy")
@@ -96,7 +99,7 @@ func TestStartNodeOnlineRedeployKeepsPendingUpgradeWhileInFlight(t *testing.T) {
 }
 
 func TestNextNodeOnlineRedeployFireAtDefersExpiredInFlightReconnect(t *testing.T) {
-	now := time.Unix(1_777_176_720, 0)
+	now := time.Now()
 	last := now.Add(-nodeOnlineRedeployCooldown - 5*time.Second)
 
 	fireAt, start := nextNodeOnlineRedeployFireAt(last, now, false, true)

go-backend/internal/http/handler/user_disable_test.go

@@ -0,0 +1,527 @@
+package handler
+
+import (
+	"bytes"
+	"database/sql"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"go-backend/internal/http/response"
+	"go-backend/internal/store/model"
+	"go-backend/internal/ws"
+)
+
+func TestUserUpdateDisablesPermissionsAndRunningForwards(t *testing.T) {
+	for _, password := range []string{"", "replacement-password"} {
+		t.Run(fmt.Sprintf("password_changed=%t", password != ""), func(t *testing.T) {
+			a := newCleanupAgent(t)
+			now := time.Now().UnixMilli()
+			for _, userID := range []int64{2, 3} {
+				if err := a.h.repo.DB().Create(&model.User{ID: userID, User: fmt.Sprintf("user%d", userID), Pwd: "pwd", RoleID: 1, Status: 1, ExpTime: now + 86400000, Flow: 100, Num: 10}).Error; err != nil {
+					t.Fatal(err)
+				}
+			}
+			if err := a.h.repo.DB().Create(&model.Tunnel{ID: 1, Name: "test", Type: 1, Protocol: "tls", Status: 1, Flow: 1}).Error; err != nil {
+				t.Fatal(err)
+			}
+			for _, permission := range []model.UserTunnel{
+				{ID: 10, UserID: 2, TunnelID: 1, Status: 1, Flow: 100, Num: 10},
+				{ID: 11, UserID: 2, TunnelID: 2, Status: 0, Flow: 100, Num: 10},
+				{ID: 12, UserID: 3, TunnelID: 1, Status: 1, Flow: 100, Num: 10},
+			} {
+				if err := a.h.repo.DB().Create(&permission).Error; err != nil {
+					t.Fatal(err)
+				}
+			}
+			for _, forward := range []model.Forward{
+				{ID: 20, UserID: 2, UserName: "user2", Name: "running", TunnelID: 1, RemoteAddr: "127.0.0.1:80", Status: 1},
+				{ID: 21, UserID: 2, UserName: "user2", Name: "paused", TunnelID: 1, RemoteAddr: "127.0.0.1:81", Status: 0},
+				{ID: 22, UserID: 3, UserName: "user3", Name: "other-user", TunnelID: 1, RemoteAddr: "127.0.0.1:82", Status: 1},
+			} {
+				if err := a.h.repo.DB().Create(&forward).Error; err != nil {
+					t.Fatal(err)
+				}
+				if err := a.h.repo.DB().Create(&model.ForwardPort{ForwardID: forward.ID, NodeID: 1, Port: 31000 + int(forward.ID)}).Error; err != nil {
+					t.Fatal(err)
+				}
+			}
+
+			update := func(status int) {
+				t.Helper()
+				payload, err := json.Marshal(map[string]interface{}{"id": 2, "user": "user2", "status": status, "pwd": password, "flow": 100, "num": 10, "expTime": now + 86400000})
+				if err != nil {
+					t.Fatal(err)
+				}
+				res := httptest.NewRecorder()
+				a.h.userUpdate(res, httptest.NewRequest(http.MethodPost, "/api/v1/user/update", bytes.NewReader(payload)))
+				var result response.R
+				if err := json.Unmarshal(res.Body.Bytes(), &result); err != nil {
+					t.Fatal(err)
+				}
+				if result.Code != 0 {
+					t.Fatalf("update user: %d %s", result.Code, result.Msg)
+				}
+			}
+
+			update(1)
+			if got := mustQueryInt(t, a.h.repo, "SELECT status FROM user_tunnel WHERE id = 10"); got != 1 {
+				t.Errorf("ordinary account update disabled an enabled permission: %d", got)
+			}
+			if len(a.commandsOfType("PauseService")) != 0 {
+				t.Error("ordinary account update paused services")
+			}
+			update(0)
+			for _, check := range []struct {
+				table string
+				id    int64
+				want  int
+			}{{"user", 2, 0}, {"user_tunnel", 10, 0}, {"user_tunnel", 11, 0}, {"user_tunnel", 12, 1}, {"forward", 20, 0}, {"forward", 21, 0}, {"forward", 22, 1}} {
+				if got := mustQueryInt(t, a.h.repo, "SELECT status FROM "+check.table+" WHERE id = ?", check.id); got != check.want {
+					t.Errorf("%s %d status = %d, want %d", check.table, check.id, got, check.want)
+				}
+			}
+			commands := a.commandsOfType("PauseService")
+			if len(commands) == 0 {
+				t.Error("running forward never received PauseService")
+			}
+			for _, command := range commands {
+				var data struct {
+					Services []string `json:"services"`
+				}
+				if err := json.Unmarshal(command.Data, &data); err != nil {
+					t.Fatal(err)
+				}
+				for _, name := range data.Services {
+					if !strings.HasPrefix(name, "20_2_") {
+						t.Errorf("paused unrelated service %q", name)
+					}
+				}
+			}
+			update(0)
+			if len(a.commandsOfType("PauseService")) != len(commands) {
+				t.Error("repeated disable replayed pauses for already paused forwards")
+			}
+
+			// Account edits and re-enabling must not grant disabled permissions or
+			// resume forwards that an administrator previously paused.
+			update(1)
+			if got := mustQueryInt(t, a.h.repo, "SELECT status FROM user_tunnel WHERE id = 10"); got != 0 {
+				t.Errorf("account re-enable unexpectedly granted a disabled permission: %d", got)
+			}
+			if got := mustQueryInt(t, a.h.repo, "SELECT status FROM user_tunnel WHERE id = 11"); got != 0 {
+				t.Errorf("re-enabled independently disabled permission: %d", got)
+			}
+			if got := mustQueryInt(t, a.h.repo, "SELECT status FROM forward WHERE id = 21"); got != 0 {
+				t.Errorf("resumed previously paused forward: %d", got)
+			}
+			if len(a.commandsOfType("ResumeService")) != 0 {
+				t.Error("account re-enable unexpectedly resumed services")
+			}
+		})
+	}
+}
+
+func TestUserDisableMultiEntryNeverRecreatesMissingServices(t *testing.T) {
+	for _, secondNodeState := range []string{"missing", "offline", "timeout"} {
+		t.Run(secondNodeState, func(t *testing.T) {
+			a := newCleanupAgent(t)
+			var remoteMu sync.Mutex
+			remoteServices := make(map[string]bool)
+			var remoteCommands []string
+			remote := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				var command struct {
+					Type string          `json:"commandType"`
+					Data json.RawMessage `json:"data"`
+				}
+				if err := json.NewDecoder(r.Body).Decode(&command); err != nil {
+					t.Error(err)
+					return
+				}
+				remoteMu.Lock()
+				defer remoteMu.Unlock()
+				remoteCommands = append(remoteCommands, command.Type)
+				switch command.Type {
+				case "UpdateService", "AddService":
+					var services []struct {
+						Name string `json:"name"`
+					}
+					if err := json.Unmarshal(command.Data, &services); err != nil {
+						t.Error(err)
+						return
+					}
+					for _, service := range services {
+						remoteServices[service.Name] = true
+					}
+				case "PauseService":
+					if secondNodeState != "missing" {
+						message := "节点不在线"
+						if secondNodeState == "timeout" {
+							message = "等待节点响应超时"
+						}
+						response.WriteJSON(w, response.ErrDefault(message))
+						return
+					}
+					var data struct {
+						Services []string `json:"services"`
+					}
+					if err := json.Unmarshal(command.Data, &data); err != nil {
+						t.Error(err)
+						return
+					}
+					for _, name := range data.Services {
+						if _, exists := remoteServices[name]; !exists {
+							response.WriteJSON(w, response.OK(map[string]interface{}{"success": false, "message": "service not found"}))
+							return
+						}
+						remoteServices[name] = false
+					}
+				}
+				response.WriteJSON(w, response.OK(map[string]interface{}{"success": true, "type": command.Type}))
+			}))
+			defer remote.Close()
+			now := time.Now().UnixMilli()
+			userID, err := a.h.repo.CreateUser("multi-entry-disable", "pwd", 1, now+86400000, 100, 1, 10, 1, 0, now)
+			if err != nil {
+				t.Fatal(err)
+			}
+			for _, value := range []interface{}{
+				&model.Node{ID: 2, Name: "second-entry", Secret: "test", ServerIP: "127.0.0.1", Status: 1, IsRemote: 1, RemoteURL: sql.NullString{String: remote.URL, Valid: true}, RemoteToken: sql.NullString{String: "test-token", Valid: true}},
+				&model.Tunnel{ID: 1, Name: "multi-entry", Type: 1, Status: 1, Protocol: "tls", Flow: 1},
+				&model.ChainTunnel{TunnelID: 1, NodeID: 1, ChainType: "1"},
+				&model.ChainTunnel{TunnelID: 1, NodeID: 2, ChainType: "1"},
+				&model.UserTunnel{ID: 10, UserID: userID, TunnelID: 1, Status: 1, Flow: 100, Num: 10},
+				&model.Forward{ID: 20, UserID: userID, UserName: "multi-entry-disable", Name: "running", TunnelID: 1, RemoteAddr: "127.0.0.1:80", Status: 1},
+				&model.ForwardPort{ForwardID: 20, NodeID: 1, Port: 31020},
+				&model.ForwardPort{ForwardID: 20, NodeID: 2, Port: 31020},
+			} {
+				if err := a.h.repo.DB().Create(value).Error; err != nil {
+					t.Fatal(err)
+				}
+			}
+			res := postJSONToHandler(t, a.h.userUpdate, map[string]interface{}{"id": userID, "user": "multi-entry-disable", "status": 0})
+			var out response.R
+			if err := json.Unmarshal(res.Body.Bytes(), &out); err != nil {
+				t.Fatal(err)
+			}
+			wantStatus := 1
+			if secondNodeState == "missing" {
+				wantStatus = 0
+				if out.Code != 0 {
+					t.Errorf("missing service should count as stopped: %s", out.Msg)
+				}
+			} else if out.Code == 0 {
+				t.Error("unconfirmed second entry pause returned success")
+			}
+			if got := mustQueryInt(t, a.h.repo, "SELECT status FROM forward WHERE id = 20"); got != wantStatus {
+				t.Errorf("forward status = %d, want %d", got, wantStatus)
+			}
+			a.mu.Lock()
+			commands := append([]cleanupAgentCommand(nil), a.commands...)
+			a.mu.Unlock()
+			firstEntryRunning := true
+			for _, command := range commands {
+				switch command.Type {
+				case "PauseService":
+					firstEntryRunning = false
+				case "UpdateService", "AddService", "ResumeService":
+					firstEntryRunning = true
+					t.Errorf("disable sent %s to already paused entry A", command.Type)
+				}
+			}
+			if firstEntryRunning {
+				t.Error("entry A is running after disable")
+			}
+			remoteMu.Lock()
+			defer remoteMu.Unlock()
+			if len(remoteCommands) == 0 {
+				t.Error("entry B was never checked")
+			}
+			for _, command := range remoteCommands {
+				if command != "PauseService" {
+					t.Errorf("disable sent %s to entry B", command)
+				}
+			}
+			for name, running := range remoteServices {
+				if running {
+					t.Errorf("entry B service %s is still running", name)
+				}
+			}
+		})
+	}
+}
+
+func TestUserDisableContinuesAcrossNodesAndForwards(t *testing.T) {
+	for _, failure := range []string{"节点不在线", "等待节点响应超时", "pause rejected"} {
+		for _, failedNodeFirst := range []bool{false, true} {
+			t.Run(fmt.Sprintf("%s/failed_node_first=%t", failure, failedNodeFirst), func(t *testing.T) {
+				a := newCleanupAgent(t)
+				var mu sync.Mutex
+				recovered := false
+				attempts := make(map[string]int)
+				remote := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+					var command struct {
+						Type string `json:"commandType"`
+					}
+					if err := json.NewDecoder(r.Body).Decode(&command); err != nil {
+						t.Error(err)
+						return
+					}
+					if command.Type != "PauseService" {
+						t.Errorf("disable sent %s", command.Type)
+					}
+					mu.Lock()
+					attempts[r.Header.Get("Authorization")]++
+					isRecovered := recovered
+					mu.Unlock()
+					if !isRecovered {
+						response.WriteJSON(w, response.ErrDefault(failure))
+						return
+					}
+					response.WriteJSON(w, response.OK(map[string]interface{}{"success": true, "type": command.Type}))
+				}))
+				defer remote.Close()
+				now := time.Now().UnixMilli()
+				userID, err := a.h.repo.CreateUser("continue-disable", "pwd", 1, now+86400000, 100, 1, 10, 1, 0, now)
+				if err != nil {
+					t.Fatal(err)
+				}
+				for _, value := range []interface{}{
+					&model.Tunnel{ID: 1, Name: "multi-entry", Type: 2, Status: 1, Flow: 1},
+					&model.Node{ID: 4, Name: "offline-middle", Secret: "test", ServerIP: "127.0.0.1", Status: 0},
+					&model.ChainTunnel{TunnelID: 1, NodeID: 4, ChainType: "2"},
+					&model.UserTunnel{ID: 10, UserID: userID, TunnelID: 1, Status: 1, Flow: 100, Num: 10},
+					&model.Forward{ID: 20, UserID: userID, UserName: "continue-disable", Name: "mixed-nodes", TunnelID: 1, RemoteAddr: "127.0.0.1:80", Status: 1},
+					&model.Forward{ID: 21, UserID: userID, UserName: "continue-disable", Name: "healthy-forward", TunnelID: 1, RemoteAddr: "127.0.0.1:81", Status: 1},
+				} {
+					if err := a.h.repo.DB().Create(value).Error; err != nil {
+						t.Fatal(err)
+					}
+				}
+				for _, nodeID := range []int64{2, 3} {
+					node := model.Node{ID: nodeID, Name: fmt.Sprintf("failed-node-%d", nodeID), Secret: "test", ServerIP: "127.0.0.1", Status: 1, IsRemote: 1, RemoteURL: sql.NullString{String: remote.URL, Valid: true}, RemoteToken: sql.NullString{String: fmt.Sprintf("test-node-%d", nodeID), Valid: true}}
+					if err := a.h.repo.DB().Create(&node).Error; err != nil {
+						t.Fatal(err)
+					}
+				}
+				nodeOrder := []int64{1, 2, 3}
+				if failedNodeFirst {
+					nodeOrder = []int64{2, 1, 3}
+				}
+				for _, nodeID := range nodeOrder {
+					if err := a.h.repo.DB().Create(&model.ForwardPort{ForwardID: 20, NodeID: nodeID, Port: 31020}).Error; err != nil {
+						t.Fatal(err)
+					}
+					if err := a.h.repo.DB().Create(&model.ChainTunnel{TunnelID: 1, NodeID: nodeID, ChainType: "1"}).Error; err != nil {
+						t.Fatal(err)
+					}
+				}
+				if err := a.h.repo.DB().Create(&model.ForwardPort{ForwardID: 21, NodeID: 1, Port: 31021}).Error; err != nil {
+					t.Fatal(err)
+				}
+				update := func() response.R {
+					t.Helper()
+					res := postJSONToHandler(t, a.h.userUpdate, map[string]interface{}{"id": userID, "user": "continue-disable", "status": 0})
+					var out response.R
+					if err := json.Unmarshal(res.Body.Bytes(), &out); err != nil {
+						t.Fatal(err)
+					}
+					return out
+				}
+				out := update()
+				if out.Code == 0 {
+					t.Error("partial node failure reported complete success")
+				}
+				state, ok := out.Data.(map[string]interface{})
+				if !ok || state["userDisabled"] != true {
+					t.Errorf("partial response did not tell the UI the account is disabled: %#v", out.Data)
+				}
+				for _, nodeID := range []int64{2, 3} {
+					if !strings.Contains(out.Msg, fmt.Sprintf("failed-node-%d", nodeID)) || !strings.Contains(out.Msg, fmt.Sprintf("ID %d", nodeID)) {
+						t.Errorf("failure response did not identify node %d: %s", nodeID, out.Msg)
+					}
+					mu.Lock()
+					count := attempts[fmt.Sprintf("Bearer test-node-%d", nodeID)]
+					mu.Unlock()
+					if count == 0 {
+						t.Errorf("failure on another node prevented node %d from being attempted", nodeID)
+					}
+				}
+				paused := make(map[string]bool)
+				for _, command := range a.commandsOfType("PauseService") {
+					var data struct {
+						Services []string `json:"services"`
+					}
+					if err := json.Unmarshal(command.Data, &data); err != nil {
+						t.Fatal(err)
+					}
+					for _, name := range data.Services {
+						paused[strings.Split(name, "_")[0]] = true
+					}
+				}
+				for _, id := range []string{"20", "21"} {
+					if !paused[id] {
+						t.Errorf("healthy node never paused forward %s", id)
+					}
+				}
+				if got := mustQueryInt(t, a.h.repo, "SELECT status FROM forward WHERE id = 20"); got != 1 {
+					t.Errorf("unconfirmed forward status = %d", got)
+				}
+				if got := mustQueryInt(t, a.h.repo, "SELECT status FROM forward WHERE id = 21"); got != 0 {
+					t.Errorf("healthy later forward was not paused: %d", got)
+				}
+				mu.Lock()
+				recovered = true
+				mu.Unlock()
+				if retry := update(); retry.Code != 0 {
+					t.Errorf("retry after recovery failed: %s", retry.Msg)
+				}
+				if got := mustQueryInt(t, a.h.repo, "SELECT status FROM forward WHERE id = 20"); got != 0 {
+					t.Errorf("retry did not confirm all nodes: %d", got)
+				}
+				for _, kind := range []string{"UpdateService", "AddService", "ResumeService"} {
+					if len(a.commandsOfType(kind)) != 0 {
+						t.Errorf("disable sent %s", kind)
+					}
+				}
+			})
+		}
+	}
+}
+
+func TestUserDisableRemovesNftablesRuleOnlyAfterConfirmedApply(t *testing.T) {
+	fixture := setupNftablesHandler(t)
+	h := fixture.handler
+	t.Cleanup(func() { _ = h.repo.Close() })
+	seedNftablesSSHConfig(t, h, fixture.nodeID)
+	tunnelID := seedTunnelForNftables(t, h, "disable-nft", fixture.nodeID)
+	forward := seedForwardForNftables(t, h, tunnelID, fixture.nodeID, "203.0.113.9:8080")
+	now := time.Now().UnixMilli()
+	userID, err := h.repo.CreateUser("disable-nft", "pwd", 1, now+86400000, 100, 1, 10, 1, 0, now)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := h.repo.DB().Model(&model.Forward{}).Where("id = ?", forward.ID).Update("user_id", userID).Error; err != nil {
+		t.Fatal(err)
+	}
+	if err := h.repo.DB().Create(&model.UserTunnel{UserID: userID, TunnelID: tunnelID, Status: 1, Flow: 100, Num: 10}).Error; err != nil {
+		t.Fatal(err)
+	}
+	otherForwardID := forward.ID + 100
+	for _, value := range []interface{}{
+		&model.Forward{ID: otherForwardID, UserID: 1, UserName: "admin", Name: "other-user", TunnelID: tunnelID, RemoteAddr: "203.0.113.9:8081", Status: 1},
+		&model.ForwardPort{ForwardID: otherForwardID, NodeID: fixture.nodeID, Port: 20001},
+	} {
+		if err := h.repo.DB().Create(value).Error; err != nil {
+			t.Fatal(err)
+		}
+	}
+	manager := &fakeNftablesManager{reconcileErr: errors.New("ssh unavailable")}
+	h.nftablesManager = manager
+	update := func() response.R {
+		t.Helper()
+		res := postJSONToHandler(t, h.userUpdate, map[string]interface{}{"id": userID, "user": "disable-nft", "status": 0})
+		var out response.R
+		if err := json.Unmarshal(res.Body.Bytes(), &out); err != nil {
+			t.Fatal(err)
+		}
+		return out
+	}
+	if out := update(); out.Code == 0 {
+		t.Error("failed SSH apply returned success")
+	}
+	if got := mustQueryInt(t, h.repo, "SELECT status FROM forward WHERE id = ?", forward.ID); got != 1 {
+		t.Errorf("unconfirmed nftables pause marked completed: %d", got)
+	}
+	if manager.reconcileCount() != 1 || len(manager.lastPlan.Rules) != 1 || manager.lastPlan.Rules[0].ForwardID != otherForwardID {
+		t.Fatalf("did not attempt to remove disabled user's nftables rule: %+v", manager.lastPlan)
+	}
+	manager.reconcileErr = nil
+	if out := update(); out.Code != 0 {
+		t.Fatalf("retry nftables disable: %s", out.Msg)
+	}
+	if got := mustQueryInt(t, h.repo, "SELECT status FROM forward WHERE id = ?", forward.ID); got != 0 {
+		t.Errorf("confirmed nftables pause was not stored: %d", got)
+	}
+	if manager.reconcileCount() != 2 || len(manager.lastPlan.Rules) != 1 || manager.lastPlan.Rules[0].ForwardID != otherForwardID {
+		t.Errorf("retry did not apply a plan without disabled forward: %+v", manager.lastPlan)
+	}
+	if got := mustQueryInt(t, h.repo, "SELECT status FROM forward WHERE id = ?", otherForwardID); got != 1 {
+		t.Errorf("disabled another user's nftables forward: %d", got)
+	}
+}
+
+func TestUserDisableReportsPauseFailureAndCanRetry(t *testing.T) {
+	for _, offline := range []bool{false, true} {
+		t.Run(fmt.Sprintf("offline=%t", offline), func(t *testing.T) {
+			a := newCleanupAgent(t)
+			now := time.Now().UnixMilli()
+			userID, err := a.h.repo.CreateUser("disable-retry", "pwd", 1, now+86400000, 100, 1, 10, 1, 0, now)
+			if err != nil {
+				t.Fatal(err)
+			}
+			for _, value := range []interface{}{
+				&model.Tunnel{ID: 1, Name: "test", Type: 1, Status: 1, Flow: 1},
+				&model.UserTunnel{ID: 10, UserID: userID, TunnelID: 1, Status: 1, Flow: 100, Num: 10},
+				&model.Forward{ID: 20, UserID: userID, UserName: "disable-retry", Name: "running", TunnelID: 1, RemoteAddr: "127.0.0.1:80", Status: 1},
+				&model.ForwardPort{ForwardID: 20, NodeID: 1, Port: 31020},
+			} {
+				if err := a.h.repo.DB().Create(value).Error; err != nil {
+					t.Fatal(err)
+				}
+			}
+			onlineServer := a.h.wsServer
+			if offline {
+				a.h.wsServer = ws.NewServer(a.h.repo, "test-jwt-secret")
+			} else {
+				ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+					response.WriteJSON(w, response.ErrDefault("pause rejected"))
+				}))
+				defer ts.Close()
+				if err := a.h.repo.DB().Model(&model.Node{}).Where("id = 1").Updates(map[string]interface{}{"is_remote": 1, "remote_url": ts.URL, "remote_token": "test-token"}).Error; err != nil {
+					t.Fatal(err)
+				}
+			}
+			update := func() response.R {
+				t.Helper()
+				res := postJSONToHandler(t, a.h.userUpdate, map[string]interface{}{"id": userID, "user": "disable-retry", "status": 0})
+				var out response.R
+				if err := json.Unmarshal(res.Body.Bytes(), &out); err != nil {
+					t.Fatal(err)
+				}
+				return out
+			}
+			if out := update(); out.Code == 0 {
+				t.Error("pause failure returned success")
+			}
+			if got := mustQueryInt(t, a.h.repo, "SELECT status FROM user WHERE id = ?", userID); got != 0 {
+				t.Errorf("failed pause restored account access: %d", got)
+			}
+			if got := mustQueryInt(t, a.h.repo, "SELECT status FROM user_tunnel WHERE id = 10"); got != 0 {
+				t.Errorf("failed pause restored tunnel access: %d", got)
+			}
+			if got := mustQueryInt(t, a.h.repo, "SELECT status FROM forward WHERE id = 20"); got != 1 {
+				t.Errorf("unconfirmed pause marked completed, status = %d", got)
+			}
+			a.h.wsServer = onlineServer
+			if err := a.h.repo.DB().Model(&model.Node{}).Where("id = 1").Update("is_remote", 0).Error; err != nil {
+				t.Fatal(err)
+			}
+			if out := update(); out.Code != 0 {
+				t.Fatalf("retry failed: %s", out.Msg)
+			}
+			if got := mustQueryInt(t, a.h.repo, "SELECT status FROM forward WHERE id = 20"); got != 0 {
+				t.Errorf("retry did not pause forward: %d", got)
+			}
+			if len(a.commandsOfType("PauseService")) == 0 {
+				t.Error("retry never sent PauseService")
+			}
+		})
+	}
+}

go-backend/internal/http/middleware/auth.go

@@ -116,6 +116,8 @@ func shouldSkip(path string) bool {
 		return false
 	case path == "/api/v1/user/login":
 		return true
+	case path == "/api/v1/user/passkey/status" || path == "/api/v1/user/passkey/login/begin" || path == "/api/v1/user/passkey/login/finish":
+		return true
 	case path == "/api/v1/public/config/get":
 		return true
 	case path == "/api/v1/federation/connect":

go-backend/internal/panelupgrade/README.md

@@ -0,0 +1,66 @@
+# Panel upgrade safety and recovery
+
+The helper is a subcommand in the **currently running image**, dispatched before
+application/database initialization. This fix must first be installed through the
+normal administrator deployment procedure on older releases lacking the helper.
+It cannot retroactively repair an already-running legacy upgrade helper.
+
+Supported deployments have one `docker-compose.yml`, the original Compose project
+labels, and a writable host bind mount containing that file and `.env`. The
+helper mounts that directory at its **host absolute path** and passes explicit
+project, project-directory, env-file and compose-file options. Multiple Compose
+files, mismatched mounts/resources, or changed database settings fail closed.
+
+Jobs are under `<deployment>/.panel-upgrades/<jobId>/` (directory 0700, files
+0600). `*.original` contains immutable per-job configuration snapshots, not a live
+database backup. `events.log` contains safe phase messages only. Legacy
+`.upgrade.bak` files and `upgrade.log` are never changed. Helper containers remain
+for diagnosis; they are intentionally not automatically removed. Operators may
+remove completed helpers after retaining the job's files.
+
+The `latest` pointer plus filesystem lock prevents simultaneous jobs across API
+processes and backend replacement. Failed validation/pull leaves live files
+untouched. A failed configuration application attempts to restore both files
+before any recreate. Once `restarting` is recorded, failures require recovery:
+no automatic database rollback, image rollback, or container rollback is safe.
+The helper has a 30 minute overall deadline, including a maximum five minute
+post-recreate verification window. Docker client timeout during recreation can
+leave daemon work in flight; it is always treated as uncertain, not retried.
+
+## Operator recovery after an interrupted/uncertain job
+
+There is intentionally no remotely callable “clear lock” endpoint. Do not delete
+job directories or rewrite status JSON to force another attempt.
+
+1. Work on the Docker host and identify the job from `latest`, `status.json` and
+   `plan.json`. Preserve the entire job directory, live Compose/env files, and
+   container inspection information in a private location. These files can
+   contain credentials. Never paste `.env` or raw Compose config into public logs.
+2. Restore Docker daemon access if necessary. Inspect the exact helper container
+   named by the job. If it is running, let it finish or explicitly stop it as an
+   administrator. Verify it has stopped. If launch was uncertain, establish that
+   no matching helper exists and no Docker create/up operation remains in flight.
+   Do not clear the job while any of these facts are uncertain.
+3. Inspect the original project's backend and frontend container IDs, images,
+   mounts and health. Check the actual database and application logs privately.
+   After any attempted recreation, assume migrations may already have occurred.
+   Preserve a current database snapshot before further manual deployment work.
+   Use the normal documented deployment procedure to bring both services to a
+   consistent, healthy state. Do not copy an old database over the current one or
+   blindly redeploy an older image. Configuration snapshots alone cannot undo a
+   schema migration.
+4. Only after verifying no helper/daemon work remains and both services and their
+   database are consistent, archive the `latest` pointer under a unique filename
+   in `.panel-upgrades/` (for example `resolved-<jobId>.pointer`). Do this while
+   the API is stopped, or hold an exclusive OS flock on `.panel-upgrades/lock`,
+   so no other start can race this manual recovery. Keep the job directory and
+   archived pointer. This permits a new job without changing recovery evidence.
+5. Restart the API if stopped and reload the browser settings page so it discovers
+   the current `latest` task instead of following the resolved task ID. No current
+   job is expected. A fresh start creates a new ID and new backups, never
+   overwriting old evidence.
+
+A lost helper, unavailable daemon, or stale status is displayed as
+`recovery_required` while retaining the active lock. This is intentionally a
+conservative derived status, so a helper that is still completing work can report
+its actual durable result without racing a status request.

go-backend/internal/panelupgrade/helper.go

@@ -0,0 +1,311 @@
+package panelupgrade
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"os"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"time"
+)
+
+const helperTimeout = 30 * time.Minute
+
+var verificationTimeout = 5 * time.Minute
+
+type composeConfig struct {
+	FullServices map[string]map[string]any `json:"-"`
+	Services     map[string]struct {
+		Image         string            `json:"image"`
+		ContainerName string            `json:"container_name"`
+		Volumes       []map[string]any  `json:"volumes"`
+		Environment   map[string]string `json:"environment"`
+	} `json:"services"`
+	Volumes  map[string]any `json:"volumes"`
+	Networks map[string]any `json:"networks"`
+}
+
+func composeArgs(p Plan, dir string, args ...string) []string {
+	return append([]string{"compose", "--project-name", p.Project, "--project-directory", p.HostDir, "--env-file", filepath.Join(dir, ".env"), "-f", filepath.Join(dir, "docker-compose.yml")}, args...)
+}
+func config(ctx context.Context, p Plan, dir string) (composeConfig, error) {
+	var c composeConfig
+	b, e := docker(ctx, composeArgs(p, dir, "config", "--format", "json")...)
+	if e != nil {
+		return c, e
+	}
+	e = json.Unmarshal(b, &c)
+	if e == nil {
+		var raw struct {
+			Services map[string]map[string]any `json:"services"`
+		}
+		e = json.Unmarshal(b, &raw)
+		c.FullServices = raw.Services
+	}
+	return c, e
+}
+func validateConfig(old, next composeConfig, p Plan) error {
+	// Compare complete normalized services, not a projection that can silently drop
+	// host bindings, commands, security options, networks or dependency changes.
+	if old.FullServices == nil || next.FullServices == nil {
+		return errors.New("missing full Compose configuration")
+	}
+	raw, _ := json.Marshal(old.FullServices)
+	var expected map[string]map[string]any
+	if json.Unmarshal(raw, &expected) != nil {
+		return errors.New("invalid configuration")
+	}
+	for _, service := range []string{"backend", "frontend"} {
+		if expected[service] == nil || next.FullServices[service] == nil {
+			return errors.New("missing service")
+		}
+		expected[service]["image"] = next.FullServices[service]["image"]
+	}
+	if env, ok := expected["backend"]["environment"].(map[string]any); ok {
+		env["FLUX_VERSION"] = p.Job.TargetVersion
+	} else {
+		return errors.New("missing backend environment")
+	}
+	if !reflect.DeepEqual(expected, next.FullServices) {
+		return errors.New("unsupported service configuration change; manual upgrade required")
+	}
+
+	for service, image := range map[string]string{"backend": "ghcr.io/sagit-chu/flux-panel-backend:", "frontend": "ghcr.io/sagit-chu/vite-frontend:"} {
+		a, ok := old.Services[service]
+		b, present := next.Services[service]
+		if !ok || !present || b.Image != image+p.Job.TargetVersion || a.ContainerName != b.ContainerName || !reflect.DeepEqual(a.Volumes, b.Volumes) {
+			return errors.New("service image, container identity or persistent mounts do not match the supported deployment")
+		}
+	}
+	if next.Services["backend"].ContainerName != p.Backend || next.Services["backend"].Environment["FLUX_VERSION"] != p.Job.TargetVersion {
+		return errors.New("backend identity/version mismatch")
+	}
+
+	for service := range next.Services {
+		if service != "backend" && service != "frontend" && service != "postgres" {
+			return errors.New("unsupported service")
+		}
+	}
+	for key, value := range old.Services["backend"].Environment {
+		if key != "FLUX_VERSION" && next.Services["backend"].Environment[key] != value {
+			return errors.New("backend environment changed; manual upgrade required")
+		}
+	}
+	for key, value := range next.Services["backend"].Environment {
+		if key != "FLUX_VERSION" && old.Services["backend"].Environment[key] != value {
+			return errors.New("backend environment changed; manual upgrade required")
+		}
+	}
+	// Database configuration and shared resource identities are not upgrade targets.
+	if !reflect.DeepEqual(old.Services["postgres"], next.Services["postgres"]) || !reflect.DeepEqual(old.Volumes, next.Volumes) || !reflect.DeepEqual(old.Networks, next.Networks) {
+		return errors.New("database or shared resource configuration changed; manual upgrade required")
+	}
+	return nil
+}
+
+// validateLive proves the normalized source configuration still describes the running
+// backend. In particular, Compose must not attach a fresh database volume by accident.
+func validateLive(ctx context.Context, p Plan, c composeConfig) error {
+	live, err := inspect(ctx, p.Backend)
+	if err != nil {
+		return err
+	}
+	if live.Image != p.Image || !live.State.Running || live.Config.Labels["com.docker.compose.project"] != p.Project || live.Config.Labels["com.docker.compose.service"] != "backend" {
+		return errors.New("running backend changed")
+	}
+	if len(live.Mounts) != len(c.Services["backend"].Volumes) {
+		return errors.New("unexpected live mounts; manual upgrade required")
+	}
+	for _, v := range c.Services["backend"].Volumes {
+		typ, _ := v["type"].(string)
+		src, _ := v["source"].(string)
+		dst, _ := v["target"].(string)
+		if typ == "volume" {
+			spec, ok := c.Volumes[src].(map[string]any)
+			if !ok {
+				return errors.New("unknown volume")
+			}
+			src, _ = spec["name"].(string)
+		}
+		if src == "" || dst == "" || (typ != "volume" && typ != "bind") {
+			return errors.New("unsupported mount")
+		}
+		found := false
+		for _, mount := range live.Mounts {
+			actual := mount.Source
+			if typ == "volume" {
+				actual = mount.Name
+			}
+			if mount.Type == typ && mount.Destination == dst && actual == src && mount.RW != (v["read_only"] == true) {
+				found = true
+			}
+		}
+		if !found {
+			return errors.New("live persistent mount does not match Compose")
+		}
+	}
+	env := map[string]string{}
+	for _, v := range live.Config.Env {
+		parts := strings.SplitN(v, "=", 2)
+		if len(parts) == 2 {
+			env[parts[0]] = parts[1]
+		}
+	}
+	for _, key := range []string{"DB_TYPE", "DB_PATH", "DATABASE_URL", "PANEL_DEPLOY_DIR", "PANEL_BACKEND_CONTAINER"} {
+		if env[key] != c.Services["backend"].Environment[key] {
+			return errors.New("live database/deployment environment does not match Compose")
+		}
+	}
+	return nil
+}
+
+// RunHelper runs before app/database initialization and does not depend on the old backend process.
+func RunHelper(planPath string) error {
+	b, e := os.ReadFile(planPath)
+	if e != nil {
+		return e
+	}
+	var p Plan
+	if e = json.Unmarshal(b, &p); e != nil {
+		return e
+	}
+	if !idPattern.MatchString(p.Job.ID) || ValidateVersion(p.Job.TargetVersion) != nil || !projectPattern.MatchString(p.Project) {
+		return errors.New("invalid plan")
+	}
+	m := Manager{Dir: p.HostDir, Backend: p.Backend}
+	dir := m.jobDir(p.Job.ID)
+	if filepath.Clean(planPath) != filepath.Join(dir, "plan.json") {
+		return errors.New("invalid plan location")
+	}
+	// Reject duplicate helper invocations without affecting the live job.
+	f, e := os.OpenFile(filepath.Join(dir, "helper.started"), os.O_CREATE|os.O_EXCL|os.O_WRONLY, 0600)
+	if e != nil {
+		return e
+	}
+	f.Close()
+	j, e := m.read(p.Job.ID)
+	if e != nil {
+		return e
+	}
+	if !j.Active {
+		return errors.New("job is not active")
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), helperTimeout)
+	defer cancel()
+	fail := func(msg string) error {
+		if e := m.write(j, "failed", msg); e != nil {
+			return e
+		}
+		return errors.New(msg)
+	}
+	recovery := func(msg string) error {
+		m.write(j, "recovery_required", msg+"；请管理员核对容器、数据库和任务备份后人工恢复，禁止自动回滚或重复升级")
+		return errors.New(msg)
+	}
+	if e = m.write(j, "preparing", "校验部署配置和持久化资源"); e != nil {
+		return e
+	}
+	old, e := config(ctx, p, p.HostDir)
+	if e != nil {
+		return fail("现有 Compose 配置校验失败，线上配置未变更")
+	}
+	next, e := config(ctx, p, dir)
+	if e != nil {
+		return fail("目标 Compose 配置校验失败，线上配置未变更")
+	}
+	if validateConfig(old, next, p) != nil {
+		return fail("目标镜像、服务或持久化资源不匹配，需手动升级")
+	}
+	if validateLive(ctx, p, old) != nil {
+		return fail("运行中后端与部署配置不一致，需手动升级")
+	}
+	if e = m.write(j, "pulling", "正在拉取并检查目标镜像，线上配置尚未变更"); e != nil {
+		return e
+	}
+	if _, e = docker(ctx, composeArgs(p, dir, "pull", "backend", "frontend")...); e != nil {
+		return fail("镜像拉取失败或超时，线上配置未变更")
+	}
+	targets := map[string]string{}
+	for _, service := range []string{"backend", "frontend"} {
+		out, err := docker(ctx, "image", "inspect", "--format", "{{.Id}}", next.Services[service].Image)
+		if err != nil || !strings.HasPrefix(strings.TrimSpace(string(out)), "sha256:") {
+			return fail("目标镜像校验失败，线上配置未变更")
+		}
+		targets[service] = strings.TrimSpace(string(out))
+	}
+	if validateLive(ctx, p, old) != nil {
+		return fail("拉取期间运行中后端发生变化，已安全取消")
+	}
+	// Detect edits since snapshots before replacing either live file.
+	for _, name := range []string{"docker-compose.yml", ".env"} {
+		live, err := os.ReadFile(filepath.Join(p.HostDir, name))
+		if err != nil {
+			return fail("读取线上配置失败")
+		}
+		backup, err := os.ReadFile(filepath.Join(dir, name+".original"))
+		if err != nil || string(live) != string(backup) {
+			return fail("线上配置已被修改，本任务已安全取消")
+		}
+	}
+	if e = m.write(j, "applying", "正在应用已校验配置"); e != nil {
+		return e
+	}
+	for _, name := range []string{"docker-compose.yml", ".env"} {
+		data, err := os.ReadFile(filepath.Join(dir, name))
+		if err == nil {
+			err = atomic(filepath.Join(p.HostDir, name), data)
+		}
+		if err != nil {
+			for _, restore := range []string{"docker-compose.yml", ".env"} {
+				original, re := os.ReadFile(filepath.Join(dir, restore+".original"))
+				if re != nil || atomic(filepath.Join(p.HostDir, restore), original) != nil {
+					return recovery("配置恢复失败，尚未执行容器重建")
+				}
+			}
+			return fail("应用配置失败，已恢复原配置，未执行容器重建")
+		}
+	}
+	// Persist the point of no automatic rollback BEFORE Docker can recreate any service.
+	if e = m.write(j, "restarting", "正在重建面板服务"); e != nil {
+		return recovery("无法记录重建状态，已停止执行")
+	}
+	if _, e = docker(ctx, composeArgs(p, p.HostDir, "up", "-d", "--no-deps", "--force-recreate", "--pull", "never", "backend", "frontend")...); e != nil {
+		return recovery("容器重建失败或超时，可能已部分生效")
+	}
+	if e = m.write(j, "verifying", "正在验证服务版本及健康状态"); e != nil {
+		return e
+	}
+	deadline := time.Now().Add(verificationTimeout)
+	for time.Now().Before(deadline) && ctx.Err() == nil {
+		ready := true
+		for _, service := range []string{"backend", "frontend"} {
+			c, err := inspect(ctx, next.Services[service].ContainerName)
+			if err != nil || !c.State.Running || c.Image != targets[service] || c.Config.Labels["com.docker.compose.project"] != p.Project || c.Config.Labels["com.docker.compose.service"] != service {
+				ready = false
+				continue
+			}
+			if c.State.Health != nil && c.State.Health.Status != "healthy" {
+				ready = false
+			}
+			if service == "backend" && c.State.Health == nil {
+				ready = false
+			}
+		}
+		if ready { // Frontend has no Docker healthcheck in the stock template.
+			probeCtx, probeCancel := context.WithTimeout(ctx, 10*time.Second)
+			_, probeErr := docker(probeCtx, "exec", next.Services["frontend"].ContainerName, "wget", "-q", "-T", "5", "-O", "/dev/null", "http://127.0.0.1:80/")
+			probeCancel()
+			ready = probeErr == nil
+		}
+		if ready {
+			return m.write(j, "succeeded", "升级完成，目标镜像和服务健康状态已验证")
+		}
+		select {
+		case <-ctx.Done():
+		case <-time.After(3 * time.Second):
+		}
+	}
+	return recovery("升级后服务健康检查失败或超时")
+}

go-backend/internal/panelupgrade/jobs.go

@@ -0,0 +1,310 @@
+// Package panelupgrade implements durable, conservative Docker Compose upgrades.
+package panelupgrade
+
+import (
+	"context"
+	"crypto/rand"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"regexp"
+	"strings"
+	"syscall"
+	"time"
+)
+
+var versionPattern = regexp.MustCompile(`^v?[0-9]+\.[0-9]+\.[0-9]+(?:-[A-Za-z0-9][A-Za-z0-9.-]*)?$`)
+var idPattern = regexp.MustCompile(`^[a-f0-9]{32}$`)
+var projectPattern = regexp.MustCompile(`^[a-z0-9][a-z0-9_-]*$`)
+
+func ValidateVersion(v string) error {
+	if !versionPattern.MatchString(v) || len(v) > 128 {
+		return errors.New("invalid release version")
+	}
+	return nil
+}
+
+type Job struct {
+	ID               string `json:"id"`
+	TargetVersion    string `json:"targetVersion"`
+	Stage            string `json:"stage"`
+	Active           bool   `json:"active"`
+	RequiresRecovery bool   `json:"requiresRecovery"`
+	Message          string `json:"message"`
+	StartedAt        int64  `json:"startedAt"`
+	UpdatedAt        int64  `json:"updatedAt"`
+	HelperContainer  string `json:"helperContainer,omitempty"`
+	BackupDir        string `json:"backupDir,omitempty"`
+}
+type Plan struct {
+	Job                                         Job
+	DeployDir, HostDir, Project, Backend, Image string
+}
+type Manager struct{ Dir, Backend string }
+
+func (m Manager) root() string            { return filepath.Join(m.Dir, ".panel-upgrades") }
+func (m Manager) jobDir(id string) string { return filepath.Join(m.root(), id) }
+func atomic(path string, b []byte) error {
+	f, e := os.CreateTemp(filepath.Dir(path), ".write-")
+	if e != nil {
+		return e
+	}
+	n := f.Name()
+	defer os.Remove(n)
+	if e = f.Chmod(0600); e == nil {
+		_, e = f.Write(b)
+	}
+	if e == nil {
+		e = f.Sync()
+	}
+	ce := f.Close()
+	if e == nil {
+		e = ce
+	}
+	if e != nil {
+		return e
+	}
+	if e = os.Rename(n, path); e != nil {
+		return e
+	}
+	d, e := os.Open(filepath.Dir(path))
+	if e != nil {
+		return e
+	}
+	defer d.Close()
+	return d.Sync()
+}
+func save(path string, v any) error {
+	b, e := json.Marshal(v)
+	if e != nil {
+		return e
+	}
+	return atomic(path, b)
+}
+func (m Manager) lock() (func(), error) {
+	if e := os.MkdirAll(m.root(), 0700); e != nil {
+		return nil, e
+	}
+	f, e := os.OpenFile(filepath.Join(m.root(), "lock"), os.O_CREATE|os.O_RDWR, 0600)
+	if e != nil {
+		return nil, e
+	}
+	if e = syscall.Flock(int(f.Fd()), syscall.LOCK_EX|syscall.LOCK_NB); e != nil {
+		f.Close()
+		return nil, errors.New("another upgrade operation is in progress")
+	}
+	return func() { syscall.Flock(int(f.Fd()), syscall.LOCK_UN); f.Close() }, nil
+}
+func docker(ctx context.Context, args ...string) ([]byte, error) {
+	cmd := exec.CommandContext(ctx, "docker", args...)
+	cmd.WaitDelay = 2 * time.Second
+	b, e := cmd.Output()
+	if e != nil {
+		return nil, errors.New("Docker operation failed (details suppressed to protect credentials)")
+	}
+	return b, nil
+}
+
+type container struct {
+	Image  string
+	Config struct {
+		Labels map[string]string
+		Env    []string
+	}
+	State struct {
+		Running bool
+		Health  *struct{ Status string }
+	}
+	Mounts []struct {
+		Type, Source, Destination, Name string
+		RW                              bool
+	}
+}
+
+func inspect(ctx context.Context, name string) (container, error) {
+	var c []container
+	b, e := docker(ctx, "inspect", name)
+	if e != nil {
+		return container{}, e
+	}
+	if json.Unmarshal(b, &c) != nil || len(c) != 1 {
+		return container{}, errors.New("invalid Docker inspection")
+	}
+	return c[0], nil
+}
+func (m Manager) Identity(ctx context.Context) (Plan, error) {
+	p := Plan{DeployDir: m.Dir, Backend: m.Backend}
+	if !filepath.IsAbs(m.Dir) || filepath.Clean(m.Dir) != m.Dir {
+		return p, errors.New("deployment directory must be an absolute clean path")
+	}
+	c, e := inspect(ctx, m.Backend)
+	if e != nil {
+		return p, e
+	}
+	p.Image = c.Image
+	p.Project = c.Config.Labels["com.docker.compose.project"]
+	if !c.State.Running || !projectPattern.MatchString(p.Project) || c.Config.Labels["com.docker.compose.service"] != "backend" || !strings.HasPrefix(p.Image, "sha256:") {
+		return p, errors.New("cannot establish original Compose identity")
+	}
+	for _, v := range c.Mounts {
+		if v.Destination == m.Dir && v.Type == "bind" && v.RW {
+			p.HostDir = v.Source
+		}
+	}
+	if p.HostDir == "/" || !filepath.IsAbs(p.HostDir) || strings.ContainsAny(p.HostDir, ",\n\r") || filepath.Clean(p.HostDir) != p.HostDir {
+		return p, errors.New("deployment directory must be a writable host bind mount")
+	}
+
+	for _, protected := range []string{"/app/paneld", "/usr/local/bin/docker", "/usr/local/libexec/docker/cli-plugins/docker-compose", "/var/run/docker.sock", "/bin", "/lib", "/etc", "/proc", "/sys", "/dev"} {
+		if p.HostDir == protected || strings.HasPrefix(protected, p.HostDir+"/") || strings.HasPrefix(p.HostDir, protected+"/") {
+			return p, errors.New("host deployment mount would shadow helper runtime paths")
+		}
+	}
+	if c.Config.Labels["com.docker.compose.project.working_dir"] != p.HostDir || c.Config.Labels["com.docker.compose.project.config_files"] != filepath.Join(p.HostDir, "docker-compose.yml") {
+		return p, errors.New("custom or multiple Compose paths require manual upgrade")
+	}
+	return p, nil
+}
+func (m Manager) read(id string) (*Job, error) {
+	if !idPattern.MatchString(id) {
+		return nil, errors.New("invalid job ID")
+	}
+	b, e := os.ReadFile(filepath.Join(m.jobDir(id), "status.json"))
+	if e != nil {
+		return nil, e
+	}
+	var j Job
+	e = json.Unmarshal(b, &j)
+	return &j, e
+}
+func (m Manager) Status(ctx context.Context, id string) (*Job, error) {
+	if id == "" {
+		b, e := os.ReadFile(filepath.Join(m.root(), "latest"))
+		if os.IsNotExist(e) {
+			return nil, nil
+		}
+		if e != nil {
+			return nil, e
+		}
+		id = string(b)
+	}
+	j, e := m.read(id)
+	if e != nil {
+		return nil, e
+	}
+	if !j.Active || time.Now().UnixMilli()-j.UpdatedAt < 90000 {
+		return j, nil
+	}
+	// An unavailable daemon, missing helper, or uncertain launch must never release the task lock.
+	c, e := inspect(ctx, j.HelperContainer)
+	if e == nil && c.State.Running {
+		return j, nil
+	}
+	j.RequiresRecovery = true
+	j.Message = "升级 helper 已停止或无法确认状态。请管理员检查任务备份和容器状态；在确认安全前禁止再次升级。"
+	// This is a derived view: do not race the helper's durable state writes.
+	j.Stage = "recovery_required"
+	return j, nil
+}
+func (m Manager) write(j *Job, stage, msg string) error {
+	j.Stage = stage
+	j.Message = msg
+	j.UpdatedAt = time.Now().UnixMilli()
+	j.Active = stage != "succeeded" && stage != "failed"
+	j.RequiresRecovery = stage == "recovery_required"
+	if e := save(filepath.Join(m.jobDir(j.ID), "status.json"), j); e != nil {
+		return e
+	}
+	f, e := os.OpenFile(filepath.Join(m.jobDir(j.ID), "events.log"), os.O_CREATE|os.O_APPEND|os.O_WRONLY, 0600)
+	if e != nil {
+		return e
+	}
+	defer f.Close()
+	_, e = fmt.Fprintf(f, "%d %s %s\n", j.UpdatedAt, stage, msg)
+	return e
+}
+func (m Manager) Start(ctx context.Context, version string, compose []byte) (*Job, string, error) {
+	if e := ValidateVersion(version); e != nil {
+		return nil, "", e
+	}
+	unlock, e := m.lock()
+	if e != nil {
+		return nil, "", e
+	}
+	defer unlock()
+	old, e := m.Status(ctx, "")
+	if e != nil {
+		return nil, "", e
+	}
+	if old != nil && (old.Active || old.RequiresRecovery) {
+		return old, "", errors.New("已有面板升级任务执行中或需要人工恢复")
+	}
+	p, e := m.Identity(ctx)
+	if e != nil {
+		return nil, "", e
+	}
+	b := make([]byte, 16)
+	if _, e = rand.Read(b); e != nil {
+		return nil, "", e
+	}
+	id := hex.EncodeToString(b)
+	dir := m.jobDir(id)
+	if e = os.Mkdir(dir, 0700); e != nil {
+		return nil, "", e
+	}
+	j := Job{ID: id, TargetVersion: version, StartedAt: time.Now().UnixMilli(), HelperContainer: "flvx-upgrade-" + id, BackupDir: filepath.Join(p.HostDir, ".panel-upgrades", id)}
+	p.Job = j
+	if e = m.write(&j, "preparing", "正在准备独立升级任务"); e != nil {
+		return nil, "", e
+	}
+	if e = atomic(filepath.Join(m.root(), "latest"), []byte(id)); e != nil {
+		return nil, "", e
+	}
+	fail := func(err error) (*Job, string, error) {
+		m.write(&j, "failed", "准备失败，线上配置未变更")
+		return &j, p.Image, err
+	}
+	for _, name := range []string{"docker-compose.yml", ".env"} {
+		data, err := os.ReadFile(filepath.Join(m.Dir, name))
+		if err != nil {
+			return fail(err)
+		}
+		if err = atomic(filepath.Join(dir, name+".original"), data); err != nil {
+			return fail(err)
+		}
+	}
+	env, e := os.ReadFile(filepath.Join(dir, ".env.original"))
+	if e != nil {
+		return fail(e)
+	}
+	lines := strings.Split(string(env), "\n")
+	for i, line := range lines {
+		if strings.HasPrefix(strings.TrimSpace(line), "FLUX_VERSION=") || strings.HasPrefix(strings.TrimSpace(line), "export FLUX_VERSION=") {
+			lines[i] = ""
+		}
+	}
+	env = []byte(strings.Join(lines, "\n") + "\nFLUX_VERSION=" + version + "\n")
+	if e = atomic(filepath.Join(dir, ".env"), env); e != nil {
+		return fail(e)
+	}
+	if e = atomic(filepath.Join(dir, "docker-compose.yml"), compose); e != nil {
+		return fail(e)
+	}
+	p.Job = j
+	if e = save(filepath.Join(dir, "plan.json"), p); e != nil {
+		return fail(e)
+	}
+	// No --rm: an exited helper is evidence needed after a daemon/client timeout.
+	args := []string{"run", "-d", "--name", j.HelperContainer, "--label", "io.flvx.upgrade-job=" + id, "--mount", "type=bind,src=" + p.HostDir + ",dst=" + p.HostDir, "--mount", "type=bind,src=/var/run/docker.sock,dst=/var/run/docker.sock", "--entrypoint", "/app/paneld", p.Image, "panel-upgrade-helper", filepath.Join(p.HostDir, ".panel-upgrades", id, "plan.json")}
+	if _, e = docker(ctx, args...); e != nil {
+		c, ie := inspect(ctx, j.HelperContainer)
+		if ie != nil || !c.State.Running {
+			return &j, p.Image, errors.New("helper 启动结果不确定；任务已保留，请查询升级状态，勿重复启动")
+		}
+	}
+	return &j, p.Image, nil
+}

go-backend/internal/panelupgrade/jobs_test.go

@@ -0,0 +1,302 @@
+package panelupgrade
+
+import (
+	"context"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+)
+
+func fakeDocker(t *testing.T, body string) {
+	t.Helper()
+	d := t.TempDir()
+	if e := os.WriteFile(filepath.Join(d, "docker"), []byte("#!/bin/sh\n"+body), 0700); e != nil {
+		t.Fatal(e)
+	}
+	t.Setenv("PATH", d+":"+os.Getenv("PATH"))
+}
+func fixture(t *testing.T) (Manager, Plan) {
+	t.Helper()
+	dir := t.TempDir()
+	m := Manager{Dir: dir, Backend: "flux-panel-backend"}
+	id := strings.Repeat("a", 32)
+	os.MkdirAll(m.jobDir(id), 0700)
+	j := Job{ID: id, TargetVersion: "2.5.0", HelperContainer: "helper", StartedAt: time.Now().UnixMilli()}
+	m.write(&j, "preparing", "ready")
+	atomic(filepath.Join(m.root(), "latest"), []byte(id))
+	p := Plan{Job: j, HostDir: dir, DeployDir: "/opt/flvx-panel", Project: "original-project", Backend: m.Backend, Image: "sha256:old"}
+	save(filepath.Join(m.jobDir(id), "plan.json"), p)
+	for _, n := range []string{".env", "docker-compose.yml"} {
+		atomic(filepath.Join(dir, n), []byte("original"))
+		atomic(filepath.Join(m.jobDir(id), n+".original"), []byte("original"))
+		atomic(filepath.Join(m.jobDir(id), n), []byte("target"))
+	}
+	return m, p
+}
+func TestVersionRejectsComposeAndPathInjection(t *testing.T) {
+	for _, v := range []string{"latest", "../v1", "1.2.3\nSECRET=x", "1.2.3${TOKEN}", "1.2.3 x", "1.2.3;id"} {
+		if ValidateVersion(v) == nil {
+			t.Fatal(v)
+		}
+	}
+	for _, v := range []string{"2.5.0-rc10", "v2.5.0", "2.1.9-beta6"} {
+		if ValidateVersion(v) != nil {
+			t.Fatal(v)
+		}
+	}
+}
+func TestPersistentLockAcrossManagers(t *testing.T) {
+	m, p := fixture(t)
+	fakeDocker(t, "exit 1\n")
+	_, _, e := m.Start(context.Background(), "2.5.0", nil)
+	if e == nil {
+		t.Fatal("accepted concurrent job")
+	}
+	b, _ := os.ReadFile(filepath.Join(m.root(), "latest"))
+	if string(b) != p.Job.ID {
+		t.Fatal("changed active job")
+	}
+}
+func TestUncertainHelperNeverUnlocks(t *testing.T) {
+	m, p := fixture(t)
+	j, _ := m.read(p.Job.ID)
+	j.UpdatedAt = 1
+	save(filepath.Join(m.jobDir(j.ID), "status.json"), j)
+	fakeDocker(t, "exit 1\n")
+	j, e := m.Status(context.Background(), "")
+	if e != nil || !j.Active || !j.RequiresRecovery || j.Stage != "recovery_required" {
+		t.Fatalf("%+v %v", j, e)
+	}
+	if _, _, e = m.Start(context.Background(), "2.5.0", nil); e == nil {
+		t.Fatal("uncertain launch unlocked")
+	}
+}
+func configs(p Plan) (string, string) {
+	old := composeConfig{}
+	json.Unmarshal([]byte(`{"services":{"backend":{"image":"old","container_name":"flux-panel-backend","environment":{"FLUX_VERSION":"old"}},"frontend":{"image":"old","container_name":"vite-frontend"}}}`), &old)
+	a, _ := json.Marshal(old)
+	next := old
+	next.Services = make(map[string]struct {
+		Image         string            `json:"image"`
+		ContainerName string            `json:"container_name"`
+		Volumes       []map[string]any  `json:"volumes"`
+		Environment   map[string]string `json:"environment"`
+	})
+	for k, v := range old.Services {
+		next.Services[k] = v
+	}
+	v := next.Services["backend"]
+	v.Image = "ghcr.io/sagit-chu/flux-panel-backend:" + p.Job.TargetVersion
+	v.Environment = map[string]string{"FLUX_VERSION": p.Job.TargetVersion}
+	next.Services["backend"] = v
+	v = next.Services["frontend"]
+	v.Image = "ghcr.io/sagit-chu/vite-frontend:" + p.Job.TargetVersion
+	next.Services["frontend"] = v
+	b, _ := json.Marshal(next)
+	return string(a), string(b)
+}
+func TestHelperFailureBoundaries(t *testing.T) {
+	for _, stage := range []string{"config", "pull", "apply", "up", "health", "success"} {
+		t.Run(stage, func(t *testing.T) {
+			m, p := fixture(t)
+			old, next := configs(p)
+			dir := m.jobDir(p.Job.ID)
+			if stage == "apply" {
+				os.Remove(filepath.Join(dir, ".env"))
+				os.Mkdir(filepath.Join(dir, ".env"), 0700)
+			}
+			if stage == "health" {
+				before := verificationTimeout
+				verificationTimeout = 0
+				t.Cleanup(func() { verificationTimeout = before })
+			}
+			script := `case "$*" in
+ *"config --format json"*)
+ case "$*" in *"` + p.Job.ID + `"*) echo '` + next + `';; *) echo '` + old + `';; esac
+ ;;
+ *"pull backend frontend"*) `
+			if stage == "pull" {
+				script += "echo SECRET >&2; exit 1"
+			} else {
+				script += "exit 0"
+			}
+			script += `;;
+ "image inspect"*) echo sha256:target;;
+ *"up -d"*) `
+			if stage == "up" {
+				script += "exit 1"
+			} else {
+				script += "touch \"" + filepath.Join(dir, "recreated") + "\"; exit 0"
+			}
+			script += `;;
+ "inspect flux-panel-backend") if [ -f "` + filepath.Join(dir, "recreated") + `" ]; then IMG=sha256:target; else IMG=sha256:old; fi; echo '[{"Image":"'"$IMG"'","State":{"Running":true,"Health":{"Status":"healthy"}},"Config":{"Labels":{"com.docker.compose.project":"original-project","com.docker.compose.service":"backend"}}}]';;
+ "inspect vite-frontend") echo '[{"Image":"sha256:target","State":{"Running":true},"Config":{"Labels":{"com.docker.compose.project":"original-project","com.docker.compose.service":"frontend"}}}]';;
+ "exec vite-frontend wget"*) exit 0;;
+ *) exit 1;; esac
+`
+			if stage == "config" {
+				script = "echo SECRET >&2;exit 1\n"
+			}
+			fakeDocker(t, script)
+			e := RunHelper(filepath.Join(dir, "plan.json"))
+			j, _ := m.read(p.Job.ID)
+			want := "failed"
+			if stage == "up" || stage == "health" {
+				want = "recovery_required"
+			}
+			if stage == "success" {
+				want = "succeeded"
+				if e != nil {
+					t.Fatal(e)
+				}
+			}
+			if j.Stage != want {
+				t.Fatalf("stage=%s error=%v", j.Stage, e)
+			}
+			for _, n := range []string{".env", "docker-compose.yml"} {
+				b, _ := os.ReadFile(filepath.Join(m.Dir, n))
+				expected := "original"
+				if stage == "up" || stage == "success" || stage == "health" {
+					expected = "target"
+				}
+				if string(b) != expected {
+					t.Fatalf("%s mutated unexpectedly", n)
+				}
+				b, _ = os.ReadFile(filepath.Join(dir, n+".original"))
+				if string(b) != "original" {
+					t.Fatal("backup overwritten")
+				}
+			}
+			b, _ := os.ReadFile(filepath.Join(dir, "events.log"))
+			if strings.Contains(string(b), "SECRET") {
+				t.Fatal("secret leaked")
+			}
+		})
+	}
+}
+func TestComposeUsesOriginalHostPathAndProject(t *testing.T) {
+	p := Plan{Project: "my-project", HostDir: "/srv/panel"}
+	s := strings.Join(composeArgs(p, "/srv/panel/.panel-upgrades/job", "pull", "backend", "frontend"), " ")
+	if !strings.Contains(s, "--project-name my-project --project-directory /srv/panel") || strings.Contains(s, "remove-orphans") {
+		t.Fatal(s)
+	}
+}
+func TestStatusWithoutJobNeedsNoDocker(t *testing.T) {
+	fakeDocker(t, "exit 99\n")
+	j, e := (Manager{Dir: t.TempDir()}).Status(context.Background(), "")
+	if e != nil || j != nil {
+		t.Fatalf("%v %v", j, e)
+	}
+}
+
+func TestFullConfigRejectsUnintendedChanges(t *testing.T) {
+	for _, field := range []string{"ports", "network_mode", "command", "entrypoint", "privileged", "networks"} {
+		t.Run(field, func(t *testing.T) {
+			_, p := fixture(t)
+			oldJSON, nextJSON := configs(p)
+			var old, next composeConfig
+			json.Unmarshal([]byte(oldJSON), &old)
+			json.Unmarshal([]byte(nextJSON), &next)
+			var a, b struct {
+				Services map[string]map[string]any `json:"services"`
+			}
+			json.Unmarshal([]byte(oldJSON), &a)
+			json.Unmarshal([]byte(nextJSON), &b)
+			old.FullServices = a.Services
+			next.FullServices = b.Services
+			old.FullServices["frontend"][field] = "private-custom-setting"
+			if validateConfig(old, next, p) == nil {
+				t.Fatal("accepted service setting removal: " + field)
+			}
+		})
+	}
+}
+func TestLiveRejectsShadowMount(t *testing.T) {
+	_, p := fixture(t)
+	fakeDocker(t, `echo '[{"Image":"sha256:old","State":{"Running":true},"Config":{"Labels":{"com.docker.compose.project":"original-project","com.docker.compose.service":"backend"}},"Mounts":[{"Type":"bind","Source":"/srv/db/gost.db","Destination":"/app/data/gost.db","RW":true}]}]'`)
+	oldJSON, _ := configs(p)
+	var old composeConfig
+	json.Unmarshal([]byte(oldJSON), &old)
+	if validateLive(context.Background(), p, old) == nil {
+		t.Fatal("accepted undeclared shadow mount")
+	}
+}
+func identityJSON(dir, host, project, files string) string {
+	c := map[string]any{"Image": "sha256:old", "State": map[string]any{"Running": true}, "Config": map[string]any{"Labels": map[string]string{"com.docker.compose.project": project, "com.docker.compose.service": "backend", "com.docker.compose.project.working_dir": host, "com.docker.compose.project.config_files": files}}, "Mounts": []map[string]any{{"Type": "bind", "Source": host, "Destination": dir, "RW": true}}}
+	b, _ := json.Marshal([]any{c})
+	return string(b)
+}
+func TestStartUsesHostMountAndKeepsUniqueBackups(t *testing.T) {
+	dir := t.TempDir()
+	m := Manager{Dir: dir, Backend: "backend"}
+	for _, n := range []string{".env", "docker-compose.yml", ".env.upgrade.bak"} {
+		os.WriteFile(filepath.Join(dir, n), []byte("original-secret"), 0600)
+	}
+	args := filepath.Join(t.TempDir(), "args")
+	fakeDocker(t, `case "$1" in inspect) echo '`+identityJSON(dir, "/srv/original-panel", "original-project", "/srv/original-panel/docker-compose.yml")+`';; run) printf '%s\n' "$@" > '`+args+`'; echo container-id;; *) exit 1;; esac`)
+	j, _, e := m.Start(context.Background(), "2.5.0-rc10", []byte("target"))
+	if e != nil {
+		t.Fatal(e)
+	}
+	b, _ := os.ReadFile(args)
+	s := string(b)
+	for _, expected := range []string{"type=bind,src=/srv/original-panel,dst=/srv/original-panel", "/app/paneld", "sha256:old", "panel-upgrade-helper"} {
+		if !strings.Contains(s, expected) {
+			t.Fatal(s)
+		}
+	}
+	if strings.Contains(s, "--rm") || strings.Contains(s, "--volumes-from") {
+		t.Fatal(s)
+	}
+	first := j.ID
+	m.write(j, "failed", "safe failure")
+	j, _, e = m.Start(context.Background(), "2.5.1", []byte("target2"))
+	if e != nil || j.ID == first {
+		t.Fatalf("%v %v", j, e)
+	}
+	for _, n := range []string{".env", "docker-compose.yml", ".env.upgrade.bak"} {
+		b, _ := os.ReadFile(filepath.Join(dir, n))
+		if string(b) != "original-secret" {
+			t.Fatal("live or legacy overwritten")
+		}
+	}
+	b, _ = os.ReadFile(filepath.Join(m.jobDir(first), ".env.original"))
+	if string(b) != "original-secret" {
+		t.Fatal("old job backup changed")
+	}
+}
+func TestIdentityFailsClosed(t *testing.T) {
+	for _, host := range []string{"/", "/app", "/usr", "/var/run", "/proc", "relative", "/srv/bad,host"} {
+		t.Run(host, func(t *testing.T) {
+			dir := t.TempDir()
+			fakeDocker(t, "echo '"+identityJSON(dir, host, "project", filepath.Join(host, "docker-compose.yml"))+"'\n")
+			if _, e := (Manager{Dir: dir, Backend: "backend"}).Identity(context.Background()); e == nil {
+				t.Fatal(host)
+			}
+		})
+	}
+}
+func TestUncertainRunIsNotRetriedOrUnlocked(t *testing.T) {
+	dir := t.TempDir()
+	m := Manager{Dir: dir, Backend: "backend"}
+	for _, n := range []string{".env", "docker-compose.yml"} {
+		os.WriteFile(filepath.Join(dir, n), []byte("original"), 0600)
+	}
+	calls := filepath.Join(t.TempDir(), "runs")
+	fakeDocker(t, `case "$*" in "inspect backend") echo '`+identityJSON(dir, "/srv/panel", "project", "/srv/panel/docker-compose.yml")+`';; run*) echo run >> '`+calls+`'; exit 1;; *) exit 1;; esac`)
+	j, _, e := m.Start(context.Background(), "2.5.0", []byte("target"))
+	if e == nil || j == nil || !j.Active {
+		t.Fatalf("%v %v", j, e)
+	}
+	_, _, e = m.Start(context.Background(), "2.5.0", nil)
+	if e == nil {
+		t.Fatal("retry accepted")
+	}
+	b, _ := os.ReadFile(calls)
+	if string(b) != "run\n" {
+		t.Fatal("retried uncertain docker run")
+	}
+}

go-backend/internal/relaysecurity/auth.go

@@ -0,0 +1,41 @@
+// Package relaysecurity defines the versioned, endpoint-scoped relay contract.
+// It authenticates relay clients, not the confidentiality of their transport.
+package relaysecurity
+
+import (
+	"crypto/rand"
+	"encoding/hex"
+	"errors"
+	"strings"
+)
+
+const Version = 1
+const Required = "required"
+const Legacy = "legacy"
+
+type Credentials struct {
+	Version  int    `json:"version"`
+	Username string `json:"username"`
+	Password string `json:"password"`
+}
+
+func New() (*Credentials, error) {
+	b := make([]byte, 32)
+	if _, err := rand.Read(b); err != nil {
+		return nil, errors.New("relay credential randomness unavailable")
+	}
+	u := make([]byte, 12)
+	if _, err := rand.Read(u); err != nil {
+		return nil, errors.New("relay credential randomness unavailable")
+	}
+	return &Credentials{Version: Version, Username: "relay-" + hex.EncodeToString(u), Password: hex.EncodeToString(b)}, nil
+}
+func (c *Credentials) Validate() error {
+	if c == nil || c.Version != Version || strings.TrimSpace(c.Username) == "" || len(c.Username) > 255 || len(c.Password) < 32 || len(c.Password) > 255 {
+		return errors.New("invalid required relay authentication")
+	}
+	return nil
+}
+func (c *Credentials) Config() map[string]interface{} {
+	return map[string]interface{}{"username": c.Username, "password": c.Password}
+}

go-backend/internal/runtime/nftables/renderer.go

@@ -46,7 +46,8 @@ func RenderTable(plan NodePlan) string {
 		}
 		targetHost := strings.Trim(strings.TrimSpace(rule.TargetHost), "[]")
 		for _, protocol := range normalizedProtocols(rule.Protocols) {
-			b.WriteString(fmt.Sprintf("    ct original proto-dst %d %s daddr %s %s dport %d counter comment %q\n",
+			b.WriteString(fmt.Sprintf("    meta l4proto %s ct original proto-dst %d %s daddr %s %s dport %d counter comment %q\n",
+				protocol,
 				rule.InPort,
 				family,
 				targetHost,
@@ -54,7 +55,8 @@ func RenderTable(plan NodePlan) string {
 				rule.TargetPort,
 				counterComment(rule.ForwardID, CounterDirectionToTarget, protocol),
 			))
-			b.WriteString(fmt.Sprintf("    ct original proto-dst %d %s saddr %s %s sport %d counter comment %q\n",
+			b.WriteString(fmt.Sprintf("    meta l4proto %s ct original proto-dst %d %s saddr %s %s sport %d counter comment %q\n",
+				protocol,
 				rule.InPort,
 				family,
 				targetHost,

go-backend/internal/runtime/nftables/renderer_test.go

@@ -62,10 +62,10 @@ func TestRenderTableIncludesForwardAccountingCounters(t *testing.T) {
 	wantLines := []string{
 		`tcp dport 12345 counter dnat ip to 198.51.100.20:443 comment "flvx forward:42 dnat tcp"`,
 		`udp dport 12345 counter dnat ip to 198.51.100.20:443 comment "flvx forward:42 dnat udp"`,
-		`ct original proto-dst 12345 ip daddr 198.51.100.20 tcp dport 443 counter comment "flvx forward:42 to-target tcp"`,
-		`ct original proto-dst 12345 ip saddr 198.51.100.20 tcp sport 443 counter comment "flvx forward:42 from-target tcp"`,
-		`ct original proto-dst 12345 ip daddr 198.51.100.20 udp dport 443 counter comment "flvx forward:42 to-target udp"`,
-		`ct original proto-dst 12345 ip saddr 198.51.100.20 udp sport 443 counter comment "flvx forward:42 from-target udp"`,
+		`meta l4proto tcp ct original proto-dst 12345 ip daddr 198.51.100.20 tcp dport 443 counter comment "flvx forward:42 to-target tcp"`,
+		`meta l4proto tcp ct original proto-dst 12345 ip saddr 198.51.100.20 tcp sport 443 counter comment "flvx forward:42 from-target tcp"`,
+		`meta l4proto udp ct original proto-dst 12345 ip daddr 198.51.100.20 udp dport 443 counter comment "flvx forward:42 to-target udp"`,
+		`meta l4proto udp ct original proto-dst 12345 ip saddr 198.51.100.20 udp sport 443 counter comment "flvx forward:42 from-target udp"`,
 	}
 	for _, want := range wantLines {
 		if !strings.Contains(got, want) {
@@ -89,8 +89,8 @@ func TestRenderTableIncludesIPv6ForwardAccountingCounters(t *testing.T) {
 	got := RenderTable(plan)
 	wantLines := []string{
 		`tcp dport 12346 counter dnat ip6 to [2001:db8::20]:8443 comment "flvx forward:43 dnat tcp"`,
-		`ct original proto-dst 12346 ip6 daddr 2001:db8::20 tcp dport 8443 counter comment "flvx forward:43 to-target tcp"`,
-		`ct original proto-dst 12346 ip6 saddr 2001:db8::20 tcp sport 8443 counter comment "flvx forward:43 from-target tcp"`,
+		`meta l4proto tcp ct original proto-dst 12346 ip6 daddr 2001:db8::20 tcp dport 8443 counter comment "flvx forward:43 to-target tcp"`,
+		`meta l4proto tcp ct original proto-dst 12346 ip6 saddr 2001:db8::20 tcp sport 8443 counter comment "flvx forward:43 from-target tcp"`,
 	}
 	for _, want := range wantLines {
 		if !strings.Contains(got, want) {
@@ -110,8 +110,8 @@ func TestRenderTableAccountingCountersIncludeOriginalPort(t *testing.T) {
 
 	got := RenderTable(plan)
 	wantLines := []string{
-		`ct original proto-dst 12345 ip daddr 198.51.100.20 tcp dport 443 counter comment "flvx forward:42 to-target tcp"`,
-		`ct original proto-dst 12346 ip daddr 198.51.100.20 tcp dport 443 counter comment "flvx forward:43 to-target tcp"`,
+		`meta l4proto tcp ct original proto-dst 12345 ip daddr 198.51.100.20 tcp dport 443 counter comment "flvx forward:42 to-target tcp"`,
+		`meta l4proto tcp ct original proto-dst 12346 ip daddr 198.51.100.20 tcp dport 443 counter comment "flvx forward:43 to-target tcp"`,
 	}
 	for _, want := range wantLines {
 		if !strings.Contains(got, want) {

go-backend/internal/runtime/nftables/runner.go

@@ -26,23 +26,58 @@ func NewSSHRunner() *SSHRunner {
 }
 
 func (r *SSHRunner) Test(ctx context.Context, cfg SSHConfig) error {
-	return r.run(ctx, cfg, "command -v nft >/dev/null 2>&1 && nft --version >/dev/null 2>&1")
+	nft := nftBinary(cfg)
+	tableName := fmt.Sprintf("flvx_capability_%d", time.Now().UnixNano())
+	return r.run(ctx, cfg, buildCapabilityCheckCommand(nft, tableName))
+}
+
+func buildCapabilityCheckCommand(nft, tableName string) string {
+	script := RenderTable(NodePlan{
+		Rules: []Rule{{
+			ForwardID:  1,
+			InPort:     12345,
+			TargetHost: "192.0.2.1",
+			TargetPort: 443,
+			Protocols:  []string{"tcp", "udp"},
+		}},
+	})
+	script = strings.Replace(script, "table inet flvx {", "table inet "+tableName+" {", 1)
+	return "set -eu\n" +
+		"command -v nft >/dev/null 2>&1\n" +
+		nft + " --version >/dev/null 2>&1\n" +
+		"tmp=$(mktemp /tmp/flvx-nft-capability-XXXXXX.nft)\n" +
+		"trap 'rm -f \"$tmp\"' EXIT\n" +
+		"cat > \"$tmp\" <<'EOF'\n" + script + "\nEOF\n" +
+		"if ! " + nft + " -c -f \"$tmp\"; then\n" +
+		"  echo 'nftables cannot validate the generated FLVX rules' >&2\n" +
+		"  exit 1\n" +
+		"fi"
 }
 
 func (r *SSHRunner) ApplyScript(ctx context.Context, cfg SSHConfig, script string) error {
-	nft := nftBinary(cfg)
-	command := "tmp=$(mktemp /tmp/flvx-nft-XXXXXX.nft) || exit 1\n" +
+	command := buildApplyCommand(nftBinary(cfg), script)
+	return r.run(ctx, cfg, command)
+}
+
+func buildApplyCommand(nft, script string) string {
+	return "set -eu\n" +
+		"tmp=$(mktemp /tmp/flvx-nft-XXXXXX.nft)\n" +
+		"batch=$(mktemp /tmp/flvx-nft-batch-XXXXXX.nft) || { rm -f \"$tmp\"; exit 1; }\n" +
 		"cleanup() {\n" +
-		"  rm -f \"$tmp\"\n" +
+		"  rm -f \"$tmp\" \"$batch\"\n" +
 		"}\n" +
 		"trap cleanup EXIT\n" +
 		"cat > \"$tmp\" <<'EOF'\n" + script + "\nEOF\n" +
-		nft + " -c -f \"$tmp\"\n" +
 		"if " + nft + " list table inet flvx >/dev/null 2>&1; then\n" +
-		"  " + nft + " delete table inet flvx\n" +
+		"  { printf '%s\\n' 'delete table inet flvx'; cat \"$tmp\"; } > \"$batch\"\n" +
+		"else\n" +
+		"  cp \"$tmp\" \"$batch\"\n" +
 		"fi\n" +
-		nft + " -f \"$tmp\""
-	return r.run(ctx, cfg, command)
+		"if ! " + nft + " -c -f \"$batch\"; then\n" +
+		"  echo 'nftables rule validation failed; active rules were preserved' >&2\n" +
+		"  exit 1\n" +
+		"fi\n" +
+		nft + " -f \"$batch\""
 }
 
 func (r *SSHRunner) ListTableJSON(ctx context.Context, cfg SSHConfig) ([]byte, error) {

go-backend/internal/runtime/nftables/runner_test.go

@@ -5,10 +5,113 @@ import (
 	"crypto/rsa"
 	"crypto/x509"
 	"encoding/pem"
+	"os"
+	"os/exec"
+	"path/filepath"
 	"strings"
 	"testing"
 )
 
+func TestBuildApplyCommandStopsAfterValidationFailure(t *testing.T) {
+	dir := t.TempDir()
+	logPath := filepath.Join(dir, "calls.log")
+	applyMarker := filepath.Join(dir, "applied")
+	nftPath := filepath.Join(dir, "nft")
+	fake := `#!/bin/sh
+echo "$*" >> "` + logPath + `"
+if [ "$1" = "list" ]; then
+  exit 0
+fi
+if [ "$1" = "-c" ]; then
+  exit 1
+fi
+touch "` + applyMarker + `"
+`
+	if err := os.WriteFile(nftPath, []byte(fake), 0o755); err != nil {
+		t.Fatalf("write fake nft: %v", err)
+	}
+
+	command := buildApplyCommand(nftPath, "table inet flvx { }")
+	result := exec.Command("sh", "-c", command)
+	if err := result.Run(); err == nil {
+		t.Fatal("expected validation failure")
+	}
+	if _, err := os.Stat(applyMarker); !os.IsNotExist(err) {
+		t.Fatalf("apply ran after validation failure, stat err=%v", err)
+	}
+	calls, err := os.ReadFile(logPath)
+	if err != nil {
+		t.Fatalf("read fake nft calls: %v", err)
+	}
+	if strings.Count(string(calls), "-f ") != 1 {
+		t.Fatalf("expected validation only, got calls:\n%s", calls)
+	}
+}
+
+func TestBuildCapabilityCheckCommandValidatesRenderedRulesWithoutApplying(t *testing.T) {
+	dir := t.TempDir()
+	logPath := filepath.Join(dir, "calls.log")
+	nftPath := filepath.Join(dir, "nft")
+	fake := `#!/bin/sh
+echo "$*" >> "` + logPath + `"
+if [ "$1" = "--version" ] || [ "$1" = "-c" ]; then
+  exit 0
+fi
+exit 1
+`
+	if err := os.WriteFile(nftPath, []byte(fake), 0o755); err != nil {
+		t.Fatalf("write fake nft: %v", err)
+	}
+
+	command := strings.Replace(buildCapabilityCheckCommand(nftPath, "flvx_capability_test"), "command -v nft", "command -v "+nftPath, 1)
+	result := exec.Command("sh", "-c", command)
+	if output, err := result.CombinedOutput(); err != nil {
+		t.Fatalf("capability command failed: %v: %s", err, output)
+	}
+	calls, err := os.ReadFile(logPath)
+	if err != nil {
+		t.Fatalf("read fake nft calls: %v", err)
+	}
+	if strings.Count(string(calls), "-c -f ") != 1 || strings.Contains(string(calls), "\n-f ") {
+		t.Fatalf("expected one check-only invocation, got calls:\n%s", calls)
+	}
+	if !strings.Contains(command, "table inet flvx_capability_test") || !strings.Contains(command, "meta l4proto tcp ct original proto-dst") {
+		t.Fatalf("capability check does not contain representative rendered rules:\n%s", command)
+	}
+}
+
+func TestBuildApplyCommandUsesAtomicReplacementBatch(t *testing.T) {
+	dir := t.TempDir()
+	batchPath := filepath.Join(dir, "batch.nft")
+	nftPath := filepath.Join(dir, "nft")
+	fake := `#!/bin/sh
+if [ "$1" = "list" ]; then
+  exit 0
+fi
+if [ "$1" = "-f" ]; then
+  cp "$2" "` + batchPath + `"
+fi
+exit 0
+`
+	if err := os.WriteFile(nftPath, []byte(fake), 0o755); err != nil {
+		t.Fatalf("write fake nft: %v", err)
+	}
+
+	script := "table inet flvx {\n  chain forward { }\n}"
+	result := exec.Command("sh", "-c", buildApplyCommand(nftPath, script))
+	if output, err := result.CombinedOutput(); err != nil {
+		t.Fatalf("apply command failed: %v: %s", err, output)
+	}
+	batch, err := os.ReadFile(batchPath)
+	if err != nil {
+		t.Fatalf("read applied batch: %v", err)
+	}
+	want := "delete table inet flvx\n" + script + "\n"
+	if string(batch) != want {
+		t.Fatalf("atomic batch = %q, want %q", batch, want)
+	}
+}
+
 func TestAuthMethodsDefaultToPrivateKey(t *testing.T) {
 	privateKey := mustGeneratePrivateKey(t)
 	methods, err := authMethods(SSHConfig{PrivateKey: privateKey})

go-backend/internal/store/model/federation_release.go

@@ -0,0 +1,15 @@
+package model
+
+// FederationPendingRelease keeps rollback work after a failed remote release.
+// It is independent of tunnels, which may never have committed or be deleted.
+type FederationPendingRelease struct {
+	ID            string `gorm:"primaryKey;size:64"`
+	RemoteURL     string `gorm:"not null"`
+	RemoteToken   string `gorm:"not null"`
+	BindingID     string
+	ReservationID string
+	ResourceKey   string
+	CreatedTime   int64
+}
+
+func (FederationPendingRelease) TableName() string { return "federation_pending_release" }

go-backend/internal/store/model/model.go

@@ -16,6 +16,7 @@ type User struct {
 	RoleID            int           `gorm:"column:role_id;not null"`
 	ExpTime           int64         `gorm:"column:exp_time;not null"`
 	Flow              int64         `gorm:"not null"`
+	FlowMiB           int64         `gorm:"column:flow_mib;not null;default:0"`
 	InFlow            int64         `gorm:"column:in_flow;not null;default:0"`
 	OutFlow           int64         `gorm:"column:out_flow;not null;default:0"`
 	FlowResetTime     int64         `gorm:"column:flow_reset_time;not null"`
@@ -174,6 +175,7 @@ type StatisticsFlow struct {
 func (StatisticsFlow) TableName() string { return "statistics_flow" }
 
 type Tunnel struct {
+	RelayAuthMode   string         `gorm:"column:relay_auth_mode;type:varchar(20);not null;default:legacy"`
 	ID              int64          `gorm:"primaryKey;autoIncrement"`
 	Name            string         `gorm:"type:varchar(100);not null"`
 	TrafficRatio    float64        `gorm:"column:traffic_ratio;not null;default:1.0"`
@@ -230,6 +232,7 @@ type UserTunnel struct {
 	SpeedID       sql.NullInt64 `gorm:"column:speed_id"`
 	Num           int           `gorm:"not null"`
 	Flow          int64         `gorm:"not null"`
+	FlowMiB       int64         `gorm:"column:flow_mib;not null;default:0"`
 	InFlow        int64         `gorm:"column:in_flow;not null;default:0"`
 	OutFlow       int64         `gorm:"column:out_flow;not null;default:0"`
 	FlowResetTime int64         `gorm:"column:flow_reset_time;not null"`
@@ -352,23 +355,26 @@ type PeerShare struct {
 func (PeerShare) TableName() string { return "peer_share" }
 
 type PeerShareRuntime struct {
-	ID            int64  `gorm:"primaryKey;autoIncrement"`
-	ShareID       int64  `gorm:"column:share_id;not null;index:idx_peer_share_runtime_share_node_status"`
-	NodeID        int64  `gorm:"column:node_id;not null;index:idx_peer_share_runtime_share_node_status"`
-	ReservationID string `gorm:"column:reservation_id;type:text;not null;uniqueIndex"`
-	ResourceKey   string `gorm:"column:resource_key;type:text;not null;uniqueIndex"`
-	BindingID     string `gorm:"column:binding_id;type:text;not null;default:'';index:idx_peer_share_runtime_binding_id"`
-	Role          string `gorm:"type:text;not null;default:''"`
-	ChainName     string `gorm:"column:chain_name;type:text;not null;default:''"`
-	ServiceName   string `gorm:"column:service_name;type:text;not null;default:''"`
-	Protocol      string `gorm:"type:text;not null;default:'tls'"`
-	Strategy      string `gorm:"type:text;not null;default:'round'"`
-	Port          int    `gorm:"not null;default:0"`
-	Target        string `gorm:"type:text;not null;default:''"`
-	Applied       int    `gorm:"not null;default:0"`
-	Status        int    `gorm:"not null;default:1;index:idx_peer_share_runtime_share_node_status"`
-	CreatedTime   int64  `gorm:"column:created_time;not null"`
-	UpdatedTime   int64  `gorm:"column:updated_time;not null"`
+	RelayAuthVersion int    `gorm:"column:relay_auth_version;not null;default:0" json:"-"`
+	RelayAuth        string `gorm:"column:relay_auth;type:text;not null;default:''" json:"-"`
+	ID               int64  `gorm:"primaryKey;autoIncrement"`
+	ShareID          int64  `gorm:"column:share_id;not null;index:idx_peer_share_runtime_share_node_status"`
+	NodeID           int64  `gorm:"column:node_id;not null;index:idx_peer_share_runtime_share_node_status"`
+	ReservationID    string `gorm:"column:reservation_id;type:text;not null;uniqueIndex"`
+	ResourceKey      string `gorm:"column:resource_key;type:text;not null;uniqueIndex"`
+	BindingID        string `gorm:"column:binding_id;type:text;not null;default:'';index:idx_peer_share_runtime_binding_id"`
+	Role             string `gorm:"type:text;not null;default:''"`
+	ChainName        string `gorm:"column:chain_name;type:text;not null;default:''"`
+	ServiceName      string `gorm:"column:service_name;type:text;not null;default:''"`
+	Protocol         string `gorm:"type:text;not null;default:'tls'"`
+	Strategy         string `gorm:"type:text;not null;default:'round'"`
+	Port             int    `gorm:"not null;default:0"`
+	Target           string `gorm:"type:text;not null;default:''" json:"-"`
+	Applied          int    `gorm:"not null;default:0"`
+	ReleasePending   int    `gorm:"column:release_pending;not null;default:0"`
+	Status           int    `gorm:"not null;default:1;index:idx_peer_share_runtime_share_node_status"`
+	CreatedTime      int64  `gorm:"column:created_time;not null"`
+	UpdatedTime      int64  `gorm:"column:updated_time;not null"`
 }
 
 func (PeerShareRuntime) TableName() string { return "peer_share_runtime" }
@@ -417,6 +423,7 @@ type UserBackup struct {
 	RoleID          int    `json:"roleId"`
 	ExpTime         int64  `json:"expTime"`
 	Flow            int64  `json:"flow"`
+	FlowMiB         int64  `json:"flowMiB,omitempty"`
 	InFlow          int64  `json:"inFlow"`
 	OutFlow         int64  `json:"outFlow"`
 	FlowResetTime   int64  `json:"flowResetTime"`
@@ -460,6 +467,7 @@ type NodeBackup struct {
 }
 
 type TunnelBackup struct {
+	RelayAuthMode   string              `json:"relayAuthMode,omitempty"`
 	ID              int64               `json:"id"`
 	Name            string              `json:"name"`
 	TrafficRatio    float64             `json:"trafficRatio"`
@@ -523,6 +531,7 @@ type UserTunnelBackup struct {
 	SpeedID       int64 `json:"speedId,omitempty"`
 	Num           int   `json:"num"`
 	Flow          int64 `json:"flow"`
+	FlowMiB       int64 `json:"flowMiB,omitempty"`
 	InFlow        int64 `json:"inFlow"`
 	OutFlow       int64 `json:"outFlow"`
 	FlowResetTime int64 `json:"flowResetTime"`
@@ -616,6 +625,7 @@ type ForwardRecord struct {
 
 // TunnelRecord is a minimal tunnel view used by control plane.
 type TunnelRecord struct {
+	RelayAuthMode   string
 	ID              int64
 	Type            int
 	Status          int
@@ -706,6 +716,7 @@ type UserTunnelDetail struct {
 	Status        int
 	TunnelFlow    int
 	Flow          int64
+	FlowMiB       int64 `gorm:"column:flow_mib"`
 	InFlow        int64
 	OutFlow       int64
 	Num           int
@@ -811,3 +822,23 @@ type TunnelQuality struct {
 }
 
 func (TunnelQuality) TableName() string { return "tunnel_quality" }
+
+// PeerShareResource is the durable desired state for a namespaced peer command.
+// Rows are retained as tombstones until deletion has been acknowledged.
+type PeerShareResource struct {
+	ID                  int64  `gorm:"primaryKey;autoIncrement"`
+	ShareID             int64  `gorm:"column:share_id;not null;uniqueIndex:idx_peer_share_resource_key"`
+	NodeID              int64  `gorm:"column:node_id;not null;index"`
+	Kind                string `gorm:"type:text;not null;uniqueIndex:idx_peer_share_resource_key"`
+	OriginalName        string `gorm:"column:original_name;type:text;not null;uniqueIndex:idx_peer_share_resource_key"`
+	RuntimeName         string `gorm:"column:runtime_name;type:text;not null;index"`
+	LegacyNames         string `gorm:"column:legacy_names;type:text;not null;default:''"`
+	LegacyServiceBase   string `gorm:"column:legacy_service_base;type:text;not null;default:''"`
+	ReleaseLegacyFamily bool   `gorm:"column:release_legacy_family;not null;default:false"`
+	Config              string `gorm:"type:text;not null;default:''"`
+	DesiredState        string `gorm:"column:desired_state;type:text;not null;default:'active'"`
+	Applied             int    `gorm:"not null;default:0"`
+	UpdatedTime         int64  `gorm:"column:updated_time;not null"`
+}
+
+func (PeerShareResource) TableName() string { return "peer_share_resource" }

go-backend/internal/store/model/passkey.go

@@ -0,0 +1,13 @@
+package model
+
+// Passkey stores a WebAuthn credential for exactly one panel user.
+type Passkey struct {
+	ID             string `gorm:"primaryKey;type:varchar(512)"`
+	UserID         int64  `gorm:"column:user_id;not null;index"`
+	Name           string `gorm:"type:varchar(100);not null"`
+	CredentialJSON string `gorm:"column:credential_json;type:text;not null"`
+	CreatedAt      int64  `gorm:"column:created_at;not null"`
+	LastUsedAt     int64  `gorm:"column:last_used_at;not null;default:0"`
+}
+
+func (Passkey) TableName() string { return "passkey" }

go-backend/internal/store/model/relay_auth.go

@@ -0,0 +1,15 @@
+package model
+
+// RelayEndpointAuth is private desired state, never an API or backup DTO.
+// Retained endpoint identities keep their credentials across topology edits.
+type RelayEndpointAuth struct {
+	ID        int64  `gorm:"primaryKey;autoIncrement" json:"-"`
+	TunnelID  int64  `gorm:"not null;uniqueIndex:idx_relay_endpoint" json:"-"`
+	NodeID    int64  `gorm:"not null;uniqueIndex:idx_relay_endpoint" json:"-"`
+	ChainType int    `gorm:"not null;uniqueIndex:idx_relay_endpoint" json:"-"`
+	Version   int    `gorm:"not null" json:"-"`
+	Username  string `gorm:"type:text;not null" json:"-"`
+	Password  string `gorm:"type:text;not null" json:"-"`
+}
+
+func (RelayEndpointAuth) TableName() string { return "relay_endpoint_auth" }

go-backend/internal/store/model/tunnel_runtime_cleanup.go

@@ -0,0 +1,13 @@
+package model
+
+// TunnelRuntimeCleanup retains ownership until an obsolete local runtime is
+// acknowledged removed. It intentionally survives deletion of its tunnel.
+type TunnelRuntimeCleanup struct {
+	ID       int64  `gorm:"primaryKey;autoIncrement"`
+	TunnelID int64  `gorm:"not null;uniqueIndex:idx_tunnel_cleanup"`
+	NodeID   int64  `gorm:"not null;uniqueIndex:idx_tunnel_cleanup"`
+	Kind     string `gorm:"type:varchar(16);not null;uniqueIndex:idx_tunnel_cleanup"`
+	Port     int    `gorm:"not null;default:0;uniqueIndex:idx_tunnel_cleanup"`
+}
+
+func (TunnelRuntimeCleanup) TableName() string { return "tunnel_runtime_cleanup" }

go-backend/internal/store/repo/config_policy.go

@@ -14,6 +14,8 @@ var publicConfigKeys = map[string]struct{}{
 	"app_logo":            {},
 	"app_favicon":         {},
 	"app_bg_image":        {},
+	"app_bg_image_light":  {},
+	"app_bg_image_dark":   {},
 	"cloudflare_site_key": {},
 	"is_commercial":       {},
 	"hide_footer_brand":   {},

go-backend/internal/store/repo/config_policy_test.go

@@ -12,6 +12,8 @@ func TestConfigPolicy(t *testing.T) {
 		{name: "app_logo is public", key: "app_logo", want: ConfigAccessPublic},
 		{name: "app_favicon is public", key: "app_favicon", want: ConfigAccessPublic},
 		{name: "app_bg_image is public", key: "app_bg_image", want: ConfigAccessPublic},
+		{name: "app_bg_image_light is public", key: "app_bg_image_light", want: ConfigAccessPublic},
+		{name: "app_bg_image_dark is public", key: "app_bg_image_dark", want: ConfigAccessPublic},
 		{name: "cloudflare_site_key is public", key: "cloudflare_site_key", want: ConfigAccessPublic},
 		{name: "is_commercial is public", key: "is_commercial", want: ConfigAccessPublic},
 		{name: "hide_footer_brand is public", key: "hide_footer_brand", want: ConfigAccessPublic},
@@ -31,7 +33,7 @@ func TestConfigPolicy(t *testing.T) {
 }
 
 func TestConfigPolicyHelpers(t *testing.T) {
-	publicKeys := []string{"app_name", "app_logo", "app_favicon", "app_bg_image", "cloudflare_site_key", "is_commercial", "hide_footer_brand"}
+	publicKeys := []string{"app_name", "app_logo", "app_favicon", "app_bg_image", "app_bg_image_light", "app_bg_image_dark", "cloudflare_site_key", "is_commercial", "hide_footer_brand"}
 	for _, key := range publicKeys {
 		if !IsPublicConfigKey(key) {
 			t.Fatalf("expected %q to be public", key)

go-backend/internal/store/repo/peer_share_resources.go

@@ -0,0 +1,55 @@
+package repo
+
+import (
+	"errors"
+	"go-backend/internal/store/model"
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+)
+
+func (r *Repository) SavePeerShareResources(items []PeerShareResource) error {
+	if r == nil || r.db == nil {
+		return errors.New("repository not initialized")
+	}
+	if len(items) == 0 {
+		return nil
+	}
+	return r.db.Transaction(func(tx *gorm.DB) error {
+		for i := range items {
+			if err := tx.Clauses(clause.OnConflict{Columns: []clause.Column{{Name: "share_id"}, {Name: "kind"}, {Name: "original_name"}}, DoUpdates: clause.AssignmentColumns([]string{"node_id", "runtime_name", "legacy_names", "legacy_service_base", "release_legacy_family", "config", "desired_state", "applied", "updated_time"})}).Create(&items[i]).Error; err != nil {
+				return err
+			}
+		}
+		return nil
+	})
+}
+
+func (r *Repository) GetPeerShareResource(shareID int64, kind, originalName string) (*PeerShareResource, error) {
+	var item model.PeerShareResource
+	err := r.db.Where("share_id = ? AND kind = ? AND original_name = ?", shareID, kind, originalName).First(&item).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &item, err
+}
+
+func (r *Repository) ListPeerShareResourcesByNode(nodeID int64) ([]PeerShareResource, error) {
+	var items []PeerShareResource
+	err := r.db.Where("node_id = ?", nodeID).Order("id").Find(&items).Error
+	return items, err
+}
+
+func (r *Repository) MarkPeerShareResourceApplied(shareID int64, kind, name string) error {
+	return r.db.Model(&model.PeerShareResource{}).Where("share_id = ? AND kind = ? AND original_name = ?", shareID, kind, name).Update("applied", 1).Error
+}
+
+func (r *Repository) ClearPeerShareResourceLegacyNames(shareID int64, kind, name string) error {
+	return r.db.Model(&model.PeerShareResource{}).Where("share_id = ? AND kind = ? AND original_name = ?", shareID, kind, name).Update("legacy_names", "").Error
+}
+
+func (r *Repository) WithPeerShareResourceTransaction(fn func(*Repository) error) error {
+	return r.db.Transaction(func(tx *gorm.DB) error { return fn(&Repository{db: tx, dbPath: r.dbPath}) })
+}
+func (r *Repository) ClearPeerShareResourceLegacyFamily(shareID int64, base string) error {
+	return r.db.Model(&model.PeerShareResource{}).Where("share_id = ? AND legacy_service_base = ?", shareID, base).Update("legacy_service_base", "").Error
+}

go-backend/internal/store/repo/peer_share_runtime_lifecycle.go

@@ -0,0 +1,32 @@
+package repo
+
+import (
+	"errors"
+	"go-backend/internal/store/model"
+	"time"
+)
+
+// A pending release remains active until the agent acknowledges deletion. This
+// keeps its port reserved even if the control connection is unavailable.
+func (r *Repository) SetPeerShareRuntimeReleasePending(id int64) error {
+	if r == nil || r.db == nil {
+		return errors.New("repository not initialized")
+	}
+	return r.db.Model(&model.PeerShareRuntime{}).Where("id = ? AND status = 1", id).Updates(map[string]interface{}{"release_pending": 1, "updated_time": time.Now().UnixMilli()}).Error
+}
+
+func (r *Repository) CompletePeerShareRuntimeRelease(id int64) error {
+	if r == nil || r.db == nil {
+		return errors.New("repository not initialized")
+	}
+	return r.db.Model(&model.PeerShareRuntime{}).Where("id = ?", id).Updates(map[string]interface{}{"status": 0, "applied": 0, "release_pending": 0, "updated_time": time.Now().UnixMilli()}).Error
+}
+
+func (r *Repository) ListActivePeerShareRuntimesByNode(nodeID int64) ([]model.PeerShareRuntime, error) {
+	if r == nil || r.db == nil {
+		return nil, errors.New("repository not initialized")
+	}
+	var items []model.PeerShareRuntime
+	err := r.db.Where("node_id = ? AND status = 1", nodeID).Order("release_pending DESC, id ASC").Find(&items).Error
+	return items, err
+}

go-backend/internal/store/repo/repository.go

@@ -43,6 +43,7 @@ type UserForwardDetail = model.UserForwardDetail
 type StatisticsFlow = model.StatisticsFlow
 type Node = model.Node
 type PeerShare = model.PeerShare
+type PeerShareResource = model.PeerShareResource
 type PeerShareRuntime = model.PeerShareRuntime
 type FederationTunnelBinding = model.FederationTunnelBinding
 type BackupData = model.BackupData
@@ -287,6 +288,7 @@ func autoMigrateAll(db *gorm.DB) error {
 
 	models := []interface{}{
 		&model.User{},
+		&model.Passkey{},
 		&model.UserQuota{},
 		&model.Forward{},
 		&model.ForwardPort{},
@@ -297,6 +299,8 @@ func autoMigrateAll(db *gorm.DB) error {
 		&model.SpeedLimit{},
 		&model.StatisticsFlow{},
 		&model.Tunnel{},
+		&model.RelayEndpointAuth{},
+		&model.TunnelRuntimeCleanup{},
 		&model.ChainTunnel{},
 		&model.UserTunnel{},
 		&model.TunnelGroup{},
@@ -309,7 +313,9 @@ func autoMigrateAll(db *gorm.DB) error {
 		&model.ViteConfig{},
 		&model.PeerShare{},
 		&model.PeerShareRuntime{},
+		&model.PeerShareResource{},
 		&model.FederationTunnelBinding{},
+		&model.FederationPendingRelease{},
 		&model.Announcement{},
 		&model.SchemaVersion{},
 		&model.NodeMetric{},
@@ -669,7 +675,7 @@ func (r *Repository) GetUserPackageTunnels(userID int64) ([]model.UserTunnelDeta
 	}
 	var items []model.UserTunnelDetail
 	err := r.db.Model(&model.UserTunnel{}).
-		Select("user_tunnel.id, user_tunnel.user_id, user_tunnel.tunnel_id, tunnel.name AS tunnel_name, user_tunnel.status, tunnel.flow AS tunnel_flow, user_tunnel.flow, user_tunnel.in_flow, user_tunnel.out_flow, user_tunnel.num, user_tunnel.flow_reset_time, user_tunnel.exp_time, user_tunnel.speed_id, speed_limit.name AS speed_limit, speed_limit.speed").
+		Select("user_tunnel.id, user_tunnel.user_id, user_tunnel.tunnel_id, tunnel.name AS tunnel_name, user_tunnel.status, tunnel.flow AS tunnel_flow, user_tunnel.flow, user_tunnel.flow_mib, user_tunnel.in_flow, user_tunnel.out_flow, user_tunnel.num, user_tunnel.flow_reset_time, user_tunnel.exp_time, user_tunnel.speed_id, speed_limit.name AS speed_limit, speed_limit.speed").
 		Joins("LEFT JOIN tunnel ON tunnel.id = user_tunnel.tunnel_id").
 		Joins("LEFT JOIN speed_limit ON speed_limit.id = user_tunnel.speed_id").
 		Where("user_tunnel.user_id = ?", userID).
@@ -924,7 +930,7 @@ func (r *Repository) ListUsers() ([]map[string]interface{}, error) {
 		item := map[string]interface{}{
 			"id": u.ID, "user": u.User, "name": u.User,
 			"roleId": u.RoleID, "status": u.Status,
-			"flow": u.Flow, "num": u.Num, "expTime": u.ExpTime,
+			"flow": u.Flow, "flowMiB": u.FlowMiB, "num": u.Num, "expTime": u.ExpTime,
 			"flowResetTime": u.FlowResetTime, "createdTime": u.CreatedTime,
 			"updatedTime": nullableInt64(u.UpdatedTime),
 			"inFlow":      u.InFlow, "outFlow": u.OutFlow,
@@ -1248,7 +1254,8 @@ func (r *Repository) ListTunnels() ([]map[string]interface{}, error) {
 		tunnelMap[t.ID] = map[string]interface{}{
 			"id": t.ID, "inx": t.Inx, "name": t.Name,
 			"type": t.Type, "flow": t.Flow, "trafficRatio": t.TrafficRatio,
-			"status": t.Status, "createdTime": t.CreatedTime,
+			"relayAuthMode": t.RelayAuthMode,
+			"status":        t.Status, "createdTime": t.CreatedTime,
 			"inIp":            nullableString(t.InIP),
 			"ipPreference":    t.IPPreference,
 			"probeTargetHost": t.ProbeTargetHost,
@@ -1514,7 +1521,12 @@ func (r *Repository) DeletePeerShare(id int64) error {
 		return errors.New("repository not initialized")
 	}
 	return r.db.Transaction(func(tx *gorm.DB) error {
-		tx.Where("share_id = ?", id).Delete(&model.PeerShareRuntime{})
+		if err := tx.Where("share_id = ?", id).Delete(&model.PeerShareRuntime{}).Error; err != nil {
+			return err
+		}
+		if err := tx.Where("share_id = ?", id).Delete(&model.PeerShareResource{}).Error; err != nil {
+			return err
+		}
 		return tx.Where("id = ?", id).Delete(&model.PeerShare{}).Error
 	})
 }
@@ -1607,7 +1619,10 @@ func (r *Repository) UpdatePeerShareRuntime(item *model.PeerShareRuntime) error
 		return errors.New("runtime item is nil")
 	}
 	return r.db.Model(&model.PeerShareRuntime{}).Where("id = ?", item.ID).Updates(map[string]interface{}{
-		"binding_id": item.BindingID, "role": item.Role,
+		"reservation_id":     item.ReservationID,
+		"relay_auth":         item.RelayAuth,
+		"relay_auth_version": item.RelayAuthVersion,
+		"binding_id":         item.BindingID, "role": item.Role,
 		"chain_name": item.ChainName, "service_name": item.ServiceName,
 		"protocol": item.Protocol, "strategy": item.Strategy,
 		"port": item.Port, "target": item.Target,
@@ -1755,35 +1770,19 @@ func (r *Repository) ListActiveForwardPeerShareRuntimesByNodeAndServiceName(node
 	return items, nil
 }
 
-func (r *Repository) ListActiveForwardPeerShareRuntimeServiceNamesByNode(nodeID int64) ([]string, error) {
+func (r *Repository) ListActiveForwardPeerShareRuntimesByNode(nodeID int64) ([]model.PeerShareRuntime, error) {
 	if r == nil || r.db == nil {
 		return nil, errors.New("repository not initialized")
 	}
-	var names []string
-	err := r.db.Model(&model.PeerShareRuntime{}).
-		Where("node_id = ? AND status = 1 AND role = ? AND service_name <> ''", nodeID, "forward").
-		Pluck("service_name", &names).Error
+	var items []model.PeerShareRuntime
+	err := r.db.Where("node_id = ? AND status = 1 AND role = ?", nodeID, "forward").Find(&items).Error
 	if err != nil {
 		return nil, err
 	}
-	if names == nil {
-		names = make([]string, 0)
+	if items == nil {
+		items = make([]model.PeerShareRuntime, 0)
 	}
-	return names, nil
-}
-
-func (r *Repository) HasRecentUnboundForwardPeerShareRuntimeOnNode(nodeID int64, minUpdatedTime int64) (bool, error) {
-	if r == nil || r.db == nil {
-		return false, errors.New("repository not initialized")
-	}
-	var count int64
-	err := r.db.Model(&model.PeerShareRuntime{}).
-		Where("node_id = ? AND status = 1 AND role = ? AND applied = 0 AND updated_time >= ? AND (service_name = '' OR service_name IS NULL)", nodeID, "forward", minUpdatedTime).
-		Count(&count).Error
-	if err != nil {
-		return false, err
-	}
-	return count > 0, nil
+	return items, nil
 }
 
 func (r *Repository) GetActiveForwardPeerShareRuntimeByPort(shareID int64, port int) (*model.PeerShareRuntime, error) {
@@ -2094,7 +2093,7 @@ func (r *Repository) exportUsers() ([]model.UserBackup, error) {
 	for _, u := range users {
 		b := model.UserBackup{
 			ID: u.ID, User: u.User, Pwd: u.Pwd, RoleID: u.RoleID,
-			ExpTime: u.ExpTime, Flow: u.Flow, InFlow: u.InFlow, OutFlow: u.OutFlow,
+			ExpTime: u.ExpTime, Flow: u.Flow, FlowMiB: u.FlowMiB, InFlow: u.InFlow, OutFlow: u.OutFlow,
 			FlowResetTime: u.FlowResetTime, Num: u.Num,
 			CreatedTime: u.CreatedTime, Status: u.Status,
 		}
@@ -2167,7 +2166,8 @@ func (r *Repository) exportTunnels() ([]model.TunnelBackup, error) {
 	out := make([]model.TunnelBackup, 0, len(tunnels))
 	for _, t := range tunnels {
 		b := model.TunnelBackup{
-			ID: t.ID, Name: t.Name, TrafficRatio: t.TrafficRatio,
+			RelayAuthMode: t.RelayAuthMode,
+			ID:            t.ID, Name: t.Name, TrafficRatio: t.TrafficRatio,
 			Type: t.Type, Protocol: t.Protocol, Flow: t.Flow,
 			CreatedTime: t.CreatedTime, UpdatedTime: t.UpdatedTime,
 			Status: t.Status, Inx: t.Inx, IPPreference: t.IPPreference,
@@ -2270,7 +2270,7 @@ func (r *Repository) exportUserTunnels() ([]model.UserTunnelBackup, error) {
 	for _, ut := range uts {
 		b := model.UserTunnelBackup{
 			ID: ut.ID, UserID: ut.UserID, TunnelID: ut.TunnelID,
-			Num: ut.Num, Flow: ut.Flow, InFlow: ut.InFlow, OutFlow: ut.OutFlow,
+			Num: ut.Num, Flow: ut.Flow, FlowMiB: ut.FlowMiB, InFlow: ut.InFlow, OutFlow: ut.OutFlow,
 			FlowResetTime: ut.FlowResetTime, ExpTime: ut.ExpTime, Status: ut.Status,
 		}
 		if ut.SpeedID.Valid {
@@ -2467,6 +2467,7 @@ func importUsers(tx *gorm.DB, users []model.UserBackup, now int64) (int, error)
 			RoleID:            u.RoleID,
 			ExpTime:           u.ExpTime,
 			Flow:              u.Flow,
+			FlowMiB:           u.FlowMiB,
 			InFlow:            u.InFlow,
 			OutFlow:           u.OutFlow,
 			FlowResetTime:     u.FlowResetTime,
@@ -2479,7 +2480,7 @@ func importUsers(tx *gorm.DB, users []model.UserBackup, now int64) (int, error)
 		err = tx.Clauses(clause.OnConflict{
 			Columns: []clause.Column{{Name: "id"}},
 			DoUpdates: clause.AssignmentColumns([]string{
-				"user", "pwd", "role_id", "exp_time", "flow", "in_flow", "out_flow",
+				"user", "pwd", "role_id", "exp_time", "flow", "flow_mib", "in_flow", "out_flow",
 				"flow_reset_time", "num", "updated_time", "status", "password_changed_at",
 			}),
 		}).Create(&item).Error
@@ -2600,6 +2601,18 @@ func importNodes(tx *gorm.DB, nodes []model.NodeBackup, now int64) (int, error)
 func importTunnels(tx *gorm.DB, tunnels []model.TunnelBackup, now int64) (int, error) {
 	count := 0
 	for _, t := range tunnels {
+		if t.RelayAuthMode != "" && t.RelayAuthMode != "legacy" {
+			return count, errors.New("authenticated relay tunnels require a full database restore; configuration backup has no private relay credentials")
+		}
+		var existing model.Tunnel
+		lookupErr := tx.First(&existing, t.ID).Error
+		if lookupErr != nil && !errors.Is(lookupErr, gorm.ErrRecordNotFound) {
+			return count, lookupErr
+		}
+		if lookupErr == nil && existing.RelayAuthMode == "required" {
+			return count, errors.New("configuration import cannot replace an authenticated relay tunnel")
+		}
+
 		item := model.Tunnel{
 			ID:              t.ID,
 			Name:            t.Name,
@@ -2717,6 +2730,7 @@ func importUserTunnels(tx *gorm.DB, userTunnels []model.UserTunnelBackup, _ int6
 			SpeedID:       sql.NullInt64{Int64: ut.SpeedID, Valid: ut.SpeedID > 0},
 			Num:           ut.Num,
 			Flow:          ut.Flow,
+			FlowMiB:       ut.FlowMiB,
 			InFlow:        ut.InFlow,
 			OutFlow:       ut.OutFlow,
 			FlowResetTime: ut.FlowResetTime,
@@ -2726,7 +2740,7 @@ func importUserTunnels(tx *gorm.DB, userTunnels []model.UserTunnelBackup, _ int6
 		err := tx.Clauses(clause.OnConflict{
 			Columns: []clause.Column{{Name: "id"}},
 			DoUpdates: clause.AssignmentColumns([]string{
-				"user_id", "tunnel_id", "speed_id", "num", "flow", "in_flow", "out_flow",
+				"user_id", "tunnel_id", "speed_id", "num", "flow", "flow_mib", "in_flow", "out_flow",
 				"flow_reset_time", "exp_time", "status",
 			}),
 		}).Create(&item).Error

go-backend/internal/store/repo/repository_federation.go

@@ -202,6 +202,13 @@ func (r *Repository) ListUsedPortsOnNode(nodeID int64) ([]int, error) {
 		}
 	}
 
+	pendingPorts, err := r.PendingTunnelCleanupPortsTx(nil, nodeID, 0)
+	if err != nil {
+		return nil, err
+	}
+	for _, port := range pendingPorts {
+		used[port] = struct{}{}
+	}
 	result := make([]int, 0, len(used))
 	for p := range used {
 		result = append(result, p)

go-backend/internal/store/repo/repository_federation_cleanup.go

@@ -0,0 +1,55 @@
+package repo
+
+import (
+	"crypto/sha256"
+	"fmt"
+
+	"go-backend/internal/store/model"
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+)
+
+const FederationBindingPendingRelease = 2
+
+func (r *Repository) ListTunnelChainNodeIDsTx(tx *gorm.DB, tunnelID int64) ([]int64, error) {
+	var ids []int64
+	err := tx.Model(&model.ChainTunnel{}).Where("tunnel_id = ?", tunnelID).Pluck("node_id", &ids).Error
+	return ids, err
+}
+
+func (r *Repository) ListFederationTunnelBindingsForCleanup(tunnelID int64) ([]model.FederationTunnelBinding, error) {
+	var rows []model.FederationTunnelBinding
+	err := r.db.Where("tunnel_id = ? AND status IN ?", tunnelID, []int{1, FederationBindingPendingRelease}).Order("id").Find(&rows).Error
+	return rows, err
+}
+
+func (r *Repository) ListPendingFederationTunnelBindings() ([]model.FederationTunnelBinding, error) {
+	var rows []model.FederationTunnelBinding
+	err := r.db.Where("status = ?", FederationBindingPendingRelease).Order("id").Find(&rows).Error
+	return rows, err
+}
+
+func (r *Repository) MarkFederationTunnelBindingPendingRelease(id int64) error {
+	return r.db.Model(&model.FederationTunnelBinding{}).Where("id = ?", id).
+		Updates(map[string]interface{}{"status": FederationBindingPendingRelease, "updated_time": unixMilliNow()}).Error
+}
+
+func (r *Repository) DeleteFederationTunnelBinding(id int64) error {
+	return r.db.Where("id = ?", id).Delete(&model.FederationTunnelBinding{}).Error
+}
+
+func (r *Repository) SavePendingFederationRelease(item *model.FederationPendingRelease) error {
+	item.ID = fmt.Sprintf("%x", sha256.Sum256([]byte(item.RemoteURL+"\n"+item.BindingID+"\n"+item.ReservationID+"\n"+item.ResourceKey)))
+	item.CreatedTime = unixMilliNow()
+	return r.db.Clauses(clause.OnConflict{DoNothing: true}).Create(item).Error
+}
+
+func (r *Repository) ListPendingFederationReleases() ([]model.FederationPendingRelease, error) {
+	var rows []model.FederationPendingRelease
+	err := r.db.Order("created_time, id").Find(&rows).Error
+	return rows, err
+}
+
+func (r *Repository) DeletePendingFederationRelease(id string) error {
+	return r.db.Where("id = ?", id).Delete(&model.FederationPendingRelease{}).Error
+}

go-backend/internal/store/repo/repository_federation_reconcile.go

@@ -0,0 +1,35 @@
+package repo
+
+import (
+	"sort"
+
+	"go-backend/internal/store/model"
+)
+
+// Only retry unfinished operations. Successful desired state must be replayed
+// on a real reconnect, not every maintenance tick while the agent stays online.
+func (r *Repository) ListPendingPeerShareNodeIDs() ([]int64, error) {
+	var resourceNodes, runtimeNodes []int64
+	if err := r.db.Model(&model.PeerShareResource{}).Where("applied = 0").Distinct("node_id").Pluck("node_id", &resourceNodes).Error; err != nil {
+		return nil, err
+	}
+	if err := r.db.Model(&model.PeerShareRuntime{}).
+		Where("status = 1 AND (release_pending <> 0 OR (applied = 0 AND service_name <> '' AND role IN ?))", []string{"middle", "exit"}).
+		Distinct("node_id").Pluck("node_id", &runtimeNodes).Error; err != nil {
+		return nil, err
+	}
+	seen := make(map[int64]struct{})
+	for _, ids := range [][]int64{resourceNodes, runtimeNodes} {
+		for _, id := range ids {
+			if id > 0 {
+				seen[id] = struct{}{}
+			}
+		}
+	}
+	out := make([]int64, 0, len(seen))
+	for id := range seen {
+		out = append(out, id)
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i] < out[j] })
+	return out, nil
+}

go-backend/internal/store/repo/repository_flow.go

@@ -272,6 +272,7 @@ func (r *Repository) GetTunnelRecord(tunnelID int64) (*model.TunnelRecord, error
 		return nil, err
 	}
 	tr := model.TunnelRecord{
+		RelayAuthMode:   t.RelayAuthMode,
 		ID:              t.ID,
 		Type:            t.Type,
 		Status:          t.Status,

go-backend/internal/store/repo/repository_mutations.go

@@ -37,7 +37,14 @@ func (r *Repository) UserExistsExcluding(username string, excludeID int64) (bool
 	return cnt > 0, err
 }
 
-func (r *Repository) CreateUser(username, pwdHash string, roleID int, expTime, flow, flowResetTime int64, num, status, maxConn int, now int64) (int64, error) {
+func optionalFlowMiB(values []int64) int64 {
+	if len(values) > 0 {
+		return values[0]
+	}
+	return 0
+}
+
+func (r *Repository) CreateUser(username, pwdHash string, roleID int, expTime, flow, flowResetTime int64, num, status, maxConn int, now int64, flowMiB ...int64) (int64, error) {
 	if r == nil || r.db == nil {
 		return 0, errors.New("repository not initialized")
 	}
@@ -47,6 +54,7 @@ func (r *Repository) CreateUser(username, pwdHash string, roleID int, expTime, f
 		RoleID:            roleID,
 		ExpTime:           expTime,
 		Flow:              flow,
+		FlowMiB:           optionalFlowMiB(flowMiB),
 		InFlow:            0,
 		OutFlow:           0,
 		FlowResetTime:     flowResetTime,
@@ -75,7 +83,7 @@ func (r *Repository) GetUserRoleID(userID int64) (int, error) {
 	return user.RoleID, nil
 }
 
-func (r *Repository) UpdateUserWithPassword(id int64, username, pwdHash string, flow int64, num int, expTime, flowResetTime int64, status, maxConn int, now int64) error {
+func (r *Repository) UpdateUserWithPassword(id int64, username, pwdHash string, flow int64, num int, expTime, flowResetTime int64, status, maxConn int, now int64, flowMiB ...int64) error {
 	if r == nil || r.db == nil {
 		return errors.New("repository not initialized")
 	}
@@ -85,6 +93,7 @@ func (r *Repository) UpdateUserWithPassword(id int64, username, pwdHash string,
 			"user":                username,
 			"pwd":                 pwdHash,
 			"flow":                flow,
+			"flow_mib":            optionalFlowMiB(flowMiB),
 			"num":                 num,
 			"exp_time":            expTime,
 			"flow_reset_time":     flowResetTime,
@@ -95,7 +104,7 @@ func (r *Repository) UpdateUserWithPassword(id int64, username, pwdHash string,
 		}).Error
 }
 
-func (r *Repository) UpdateUserWithoutPassword(id int64, username string, flow int64, num int, expTime, flowResetTime int64, status, maxConn int, now int64) error {
+func (r *Repository) UpdateUserWithoutPassword(id int64, username string, flow int64, num int, expTime, flowResetTime int64, status, maxConn int, now int64, flowMiB ...int64) error {
 	if r == nil || r.db == nil {
 		return errors.New("repository not initialized")
 	}
@@ -104,6 +113,7 @@ func (r *Repository) UpdateUserWithoutPassword(id int64, username string, flow i
 		Updates(map[string]interface{}{
 			"user":            username,
 			"flow":            flow,
+			"flow_mib":        optionalFlowMiB(flowMiB),
 			"num":             num,
 			"exp_time":        expTime,
 			"flow_reset_time": flowResetTime,
@@ -126,7 +136,7 @@ func (r *Repository) UpdateUserPassword(userID int64, pwdHash string, now int64)
 		}).Error
 }
 
-func (r *Repository) PropagateUserFlowToTunnels(userID int64, flow int64, num int, expTime, flowResetTime int64) {
+func (r *Repository) PropagateUserFlowToTunnels(userID int64, flow int64, num int, expTime, flowResetTime int64, flowMiB ...int64) {
 	if r == nil || r.db == nil {
 		return
 	}
@@ -134,17 +144,28 @@ func (r *Repository) PropagateUserFlowToTunnels(userID int64, flow int64, num in
 		Where("user_id = ?", userID).
 		Updates(map[string]interface{}{
 			"flow":            flow,
+			"flow_mib":        optionalFlowMiB(flowMiB),
 			"num":             num,
 			"exp_time":        expTime,
 			"flow_reset_time": flowResetTime,
 		}).Error
 }
 
+func (r *Repository) DisableUserTunnels(userID int64) error {
+	if r == nil || r.db == nil {
+		return errors.New("repository not initialized")
+	}
+	return r.db.Model(&model.UserTunnel{}).Where("user_id = ?", userID).Update("status", 0).Error
+}
+
 func (r *Repository) DeleteUserCascade(userID int64) error {
 	if r == nil || r.db == nil {
 		return errors.New("repository not initialized")
 	}
 	return r.db.Transaction(func(tx *gorm.DB) error {
+		if err := tx.Where("user_id = ?", userID).Delete(&model.Passkey{}).Error; err != nil {
+			return err
+		}
 		forwardIDs := tx.Model(&model.Forward{}).Select("id").Where("user_id = ?", userID)
 		if err := tx.Where("forward_id IN (?)", forwardIDs).Delete(&model.ForwardPort{}).Error; err != nil {
 			return err
@@ -563,6 +584,13 @@ func (r *Repository) pickNodePortTx(tx *gorm.DB, nodeID int64, allocated map[int
 		}
 	}
 
+	pendingPorts, err := r.PendingTunnelCleanupPortsTx(tx, nodeID, excludeTunnelID)
+	if err != nil {
+		return 0, err
+	}
+	for _, port := range pendingPorts {
+		used[port] = struct{}{}
+	}
 	var available []int
 	for _, candidate := range candidates {
 		if candidate <= 0 {
@@ -608,6 +636,9 @@ func (r *Repository) DeleteTunnelCascade(tunnelID int64) error {
 		return errors.New("repository not initialized")
 	}
 	return r.db.Transaction(func(tx *gorm.DB) error {
+		if err := r.queueDeletedTunnelRuntimeTx(tx, tunnelID); err != nil {
+			return err
+		}
 		forwardIDs := tx.Model(&model.Forward{}).Select("id").Where("tunnel_id = ?", tunnelID)
 		if err := tx.Where("forward_id IN (?)", forwardIDs).Delete(&model.ForwardPort{}).Error; err != nil {
 			return err
@@ -624,6 +655,9 @@ func (r *Repository) DeleteTunnelCascade(tunnelID int64) error {
 		if err := tx.Where("tunnel_id = ?", tunnelID).Delete(&model.FederationTunnelBinding{}).Error; err != nil {
 			return err
 		}
+		if err := tx.Where("tunnel_id = ?", tunnelID).Delete(&model.RelayEndpointAuth{}).Error; err != nil {
+			return err
+		}
 		return tx.Where("id = ?", tunnelID).Delete(&model.Tunnel{}).Error
 	})
 }
@@ -650,7 +684,7 @@ func (r *Repository) DeleteUserTunnel(id int64) error {
 	return r.db.Where("id = ?", id).Delete(&model.UserTunnel{}).Error
 }
 
-func (r *Repository) UpdateUserTunnel(id int64, flow int64, num int, expTime, flowResetTime int64, speedID interface{}, status int) error {
+func (r *Repository) UpdateUserTunnel(id int64, flow int64, num int, expTime, flowResetTime int64, speedID interface{}, status int, flowMiB ...int64) error {
 	if r == nil || r.db == nil {
 		return errors.New("repository not initialized")
 	}
@@ -658,6 +692,7 @@ func (r *Repository) UpdateUserTunnel(id int64, flow int64, num int, expTime, fl
 		Where("id = ?", id).
 		Updates(map[string]interface{}{
 			"flow":            flow,
+			"flow_mib":        optionalFlowMiB(flowMiB),
 			"num":             num,
 			"exp_time":        expTime,
 			"flow_reset_time": flowResetTime,
@@ -692,7 +727,7 @@ func (r *Repository) GetExistingUserTunnel(userID, tunnelID int64) (id int64, fl
 	return ut.ID, ut.Flow, int64(ut.Num), ut.ExpTime, ut.FlowResetTime, ut.SpeedID, ut.Status, nil
 }
 
-func (r *Repository) InsertUserTunnel(userID, tunnelID int64, speedID interface{}, num int, flow, flowResetTime, expTime int64, status int) error {
+func (r *Repository) InsertUserTunnel(userID, tunnelID int64, speedID interface{}, num int, flow, flowResetTime, expTime int64, status int, flowMiB ...int64) error {
 	if r == nil || r.db == nil {
 		return errors.New("repository not initialized")
 	}
@@ -702,6 +737,7 @@ func (r *Repository) InsertUserTunnel(userID, tunnelID int64, speedID interface{
 		SpeedID:       nullInt64FromInterface(speedID),
 		Num:           num,
 		Flow:          flow,
+		FlowMiB:       optionalFlowMiB(flowMiB),
 		InFlow:        0,
 		OutFlow:       0,
 		FlowResetTime: flowResetTime,
@@ -711,7 +747,7 @@ func (r *Repository) InsertUserTunnel(userID, tunnelID int64, speedID interface{
 	return r.db.Create(&ut).Error
 }
 
-func (r *Repository) UpdateUserTunnelFields(id int64, speedID interface{}, flow int64, num int, expTime, flowResetTime int64, status int) error {
+func (r *Repository) UpdateUserTunnelFields(id int64, speedID interface{}, flow int64, num int, expTime, flowResetTime int64, status int, flowMiB ...int64) error {
 	if r == nil || r.db == nil {
 		return errors.New("repository not initialized")
 	}
@@ -720,6 +756,7 @@ func (r *Repository) UpdateUserTunnelFields(id int64, speedID interface{}, flow
 		Updates(map[string]interface{}{
 			"speed_id":        nullInt64FromInterface(speedID),
 			"flow":            flow,
+			"flow_mib":        optionalFlowMiB(flowMiB),
 			"num":             num,
 			"exp_time":        expTime,
 			"flow_reset_time": flowResetTime,
@@ -880,6 +917,13 @@ func (r *Repository) GetUsedPortsOnNodeAsMap(nodeID int64) (map[int]bool, error)
 	for _, p := range chainPorts {
 		used[p] = true
 	}
+	pendingPorts, err := r.PendingTunnelCleanupPortsTx(nil, nodeID, 0)
+	if err != nil {
+		return nil, err
+	}
+	for _, port := range pendingPorts {
+		used[port] = true
+	}
 	return used, nil
 }
 
@@ -1293,7 +1337,7 @@ func (r *Repository) EnsureUserTunnelGrant(userID, tunnelID int64) (int64, bool,
 		return 0, false, err
 	}
 	var user model.User
-	if err := r.db.Select("flow, num, exp_time, flow_reset_time").Where("id = ?", userID).First(&user).Error; err != nil {
+	if err := r.db.Select("flow, flow_mib, num, exp_time, flow_reset_time").Where("id = ?", userID).First(&user).Error; err != nil {
 		return 0, false, err
 	}
 	flow := user.Flow
@@ -1305,6 +1349,7 @@ func (r *Repository) EnsureUserTunnelGrant(userID, tunnelID int64) (int64, bool,
 		TunnelID:      tunnelID,
 		Num:           num,
 		Flow:          flow,
+		FlowMiB:       user.FlowMiB,
 		InFlow:        0,
 		OutFlow:       0,
 		FlowResetTime: flowReset,

go-backend/internal/store/repo/repository_passkey.go

@@ -0,0 +1,51 @@
+package repo
+
+import (
+	"errors"
+
+	"go-backend/internal/store/model"
+	"gorm.io/gorm"
+)
+
+func (r *Repository) ListPasskeys(userID int64) ([]model.Passkey, error) {
+	var keys []model.Passkey
+	err := r.db.Where("user_id = ?", userID).Order("created_at desc").Find(&keys).Error
+	return keys, err
+}
+
+func (r *Repository) GetPasskey(userID int64, id string) (*model.Passkey, error) {
+	var key model.Passkey
+	err := r.db.Where("user_id = ? AND id = ?", userID, id).Take(&key).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &key, err
+}
+
+// Credential IDs are unique across all users. Resolve the owner from the stored
+// credential before checking the untrusted user handle in a discoverable login.
+func (r *Repository) GetPasskeyByID(id string) (*model.Passkey, error) {
+	var key model.Passkey
+	err := r.db.Where("id = ?", id).Take(&key).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	return &key, err
+}
+
+func (r *Repository) CreatePasskey(key *model.Passkey) error {
+	return r.db.Create(key).Error
+}
+
+func (r *Repository) DeletePasskey(userID int64, id string) (bool, error) {
+	result := r.db.Where("user_id = ? AND id = ?", userID, id).Delete(&model.Passkey{})
+	return result.RowsAffected == 1, result.Error
+}
+
+// Compare-and-swap prevents a concurrent assertion from reusing an old sign counter.
+func (r *Repository) UpdatePasskeyCredential(userID int64, id, oldJSON, newJSON string, now int64) (bool, error) {
+	result := r.db.Model(&model.Passkey{}).
+		Where("user_id = ? AND id = ? AND credential_json = ?", userID, id, oldJSON).
+		Updates(map[string]interface{}{"credential_json": newJSON, "last_used_at": now})
+	return result.RowsAffected == 1, result.Error
+}

go-backend/internal/store/repo/repository_relay_auth.go

@@ -0,0 +1,64 @@
+package repo
+
+import (
+	"errors"
+	"go-backend/internal/relaysecurity"
+	"go-backend/internal/store/model"
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+)
+
+// RelayEndpointCredentials loads existing state, creating only when explicitly
+// requested by a new endpoint operation. Reconnects must never recreate a secret.
+func (r *Repository) RelayEndpointCredentials(tx *gorm.DB, tunnelID, nodeID int64, role int, create bool) (*relaysecurity.Credentials, error) {
+	db := tx
+	if db == nil {
+		db = r.db
+	}
+	var row model.RelayEndpointAuth
+	find := func() error {
+		return db.Where("tunnel_id = ? AND node_id = ? AND chain_type = ?", tunnelID, nodeID, role).First(&row).Error
+	}
+	err := find()
+	if errors.Is(err, gorm.ErrRecordNotFound) && create {
+		var existing int64
+		if e := db.Model(&model.ChainTunnel{}).Where("tunnel_id = ? AND node_id = ? AND chain_type = ?", tunnelID, nodeID, role).Count(&existing).Error; e != nil {
+			return nil, e
+		}
+		if existing > 0 {
+			var tunnel model.Tunnel
+			if e := db.First(&tunnel, tunnelID).Error; e != nil {
+				return nil, e
+			}
+			if tunnel.Type == 2 || tunnel.RelayAuthMode == relaysecurity.Required {
+				return nil, errors.New("required relay endpoint credentials unavailable; refusing regeneration")
+			}
+		}
+
+		c, e := relaysecurity.New()
+		if e != nil {
+			return nil, e
+		}
+		row = model.RelayEndpointAuth{TunnelID: tunnelID, NodeID: nodeID, ChainType: role, Version: c.Version, Username: c.Username, Password: c.Password}
+		if e = db.Clauses(clause.OnConflict{DoNothing: true}).Create(&row).Error; e != nil {
+			return nil, e
+		}
+		row = model.RelayEndpointAuth{}
+		err = find()
+	}
+	if err != nil {
+		return nil, errors.New("required relay endpoint credentials unavailable")
+	}
+	c := &relaysecurity.Credentials{Version: row.Version, Username: row.Username, Password: row.Password}
+	if err := c.Validate(); err != nil {
+		return nil, err
+	}
+	return c, nil
+}
+
+func (r *Repository) SetTunnelRelayAuthModeTx(tx *gorm.DB, tunnelID int64, mode string) error {
+	if mode != relaysecurity.Required && mode != relaysecurity.Legacy {
+		return errors.New("invalid relay authentication mode")
+	}
+	return tx.Model(&model.Tunnel{}).Where("id = ?", tunnelID).Update("relay_auth_mode", mode).Error
+}

go-backend/internal/store/repo/repository_traffic_limit_test.go

@@ -0,0 +1,67 @@
+package repo
+
+import (
+	"path/filepath"
+	"testing"
+	"time"
+
+	"go-backend/internal/store/model"
+)
+
+func TestTrafficLimitMiBSurvivesBackupRestore(t *testing.T) {
+	source, err := Open(filepath.Join(t.TempDir(), "source.db"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer source.Close()
+
+	now := time.Now().UnixMilli()
+	userID, err := source.CreateUser("mib-user", "hash", 1, now+86400000, 1, 1, 10, 1, 0, now, 500)
+	if err != nil {
+		t.Fatal(err)
+	}
+	tunnel := model.Tunnel{Name: "mib-tunnel", TrafficRatio: 1, Type: 1, Protocol: "tls", Flow: 1, CreatedTime: now, UpdatedTime: now, Status: 1, Inx: 1}
+	if err := source.DB().Create(&tunnel).Error; err != nil {
+		t.Fatal(err)
+	}
+	if _, _, err := source.EnsureUserTunnelGrant(userID, tunnel.ID); err != nil {
+		t.Fatal(err)
+	}
+	grants, err := source.GetUserPackageTunnels(userID)
+	if err != nil || len(grants) != 1 || grants[0].FlowMiB != 500 {
+		t.Fatalf("inherited tunnel quota = %+v, err = %v", grants, err)
+	}
+	backup, err := source.ExportAll()
+	if err != nil {
+		t.Fatal(err)
+	}
+	found := false
+	for _, user := range backup.Users {
+		if user.User == "mib-user" {
+			found = user.Flow == 1 && user.FlowMiB == 500
+		}
+	}
+	if !found {
+		t.Fatal("500 MiB user quota missing from backup")
+	}
+	if len(backup.UserTunnels) != 1 || backup.UserTunnels[0].FlowMiB != 500 {
+		t.Fatalf("tunnel quota missing from backup: %+v", backup.UserTunnels)
+	}
+
+	dest, err := Open(filepath.Join(t.TempDir(), "dest.db"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer dest.Close()
+	if _, err := dest.Import(backup, []string{"users", "tunnels", "userTunnels"}); err != nil {
+		t.Fatal(err)
+	}
+	user, err := dest.GetUserByUsername("mib-user")
+	if err != nil || user == nil || user.Flow != 1 || user.FlowMiB != 500 {
+		t.Fatalf("restored quota = %+v, err = %v", user, err)
+	}
+	grants, err = dest.GetUserPackageTunnels(user.ID)
+	if err != nil || len(grants) != 1 || grants[0].FlowMiB != 500 {
+		t.Fatalf("restored tunnel quota = %+v, err = %v", grants, err)
+	}
+}

go-backend/internal/store/repo/repository_tunnel_cleanup.go

@@ -0,0 +1,71 @@
+package repo
+
+import (
+	"go-backend/internal/store/model"
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+)
+
+func (r *Repository) QueueTunnelRuntimeCleanupTx(tx *gorm.DB, items []model.TunnelRuntimeCleanup) error {
+	for _, item := range items {
+		var node model.Node
+		if err := tx.Select("id", "is_remote").Where("id = ?", item.NodeID).First(&node).Error; err != nil {
+			return err
+		}
+		if node.IsRemote == 1 {
+			continue
+		}
+		if err := tx.Clauses(clause.OnConflict{Columns: []clause.Column{{Name: "tunnel_id"}, {Name: "node_id"}, {Name: "kind"}, {Name: "port"}}, DoNothing: true}).Create(&item).Error; err != nil {
+			return err
+		}
+	}
+	return nil
+}
+func (r *Repository) ListTunnelRuntimeCleanup(tunnelID int64) ([]model.TunnelRuntimeCleanup, error) {
+	var items []model.TunnelRuntimeCleanup
+	q := r.db.Model(&model.TunnelRuntimeCleanup{})
+	if tunnelID > 0 {
+		q = q.Where("tunnel_id = ?", tunnelID)
+	}
+	err := q.Order("tunnel_id, node_id, kind DESC").Find(&items).Error
+	return items, err
+}
+func (r *Repository) DeleteTunnelRuntimeCleanup(id int64) error {
+	return r.db.Where("id = ?", id).Delete(&model.TunnelRuntimeCleanup{}).Error
+}
+func (r *Repository) PendingTunnelCleanupPortsTx(tx *gorm.DB, nodeID, excludeTunnelID int64) ([]int, error) {
+	if tx == nil {
+		tx = r.db
+	}
+	q := tx.Model(&model.TunnelRuntimeCleanup{}).Where("node_id = ? AND kind = ? AND port > 0", nodeID, "service")
+	if excludeTunnelID > 0 {
+		q = q.Where("tunnel_id != ?", excludeTunnelID)
+	}
+	var ports []int
+	err := q.Pluck("port", &ports).Error
+	return ports, err
+}
+
+func (r *Repository) queueDeletedTunnelRuntimeTx(tx *gorm.DB, tunnelID int64) error {
+	var tunnels []model.Tunnel
+	if err := tx.Where("id = ? AND type = ?", tunnelID, 2).Find(&tunnels).Error; err != nil {
+		return err
+	}
+	if len(tunnels) == 0 {
+		return nil
+	}
+	var rows []model.ChainTunnel
+	if err := tx.Where("tunnel_id = ?", tunnelID).Find(&rows).Error; err != nil {
+		return err
+	}
+	var items []model.TunnelRuntimeCleanup
+	for _, row := range rows {
+		if row.ChainType == "2" || row.ChainType == "3" {
+			items = append(items, model.TunnelRuntimeCleanup{TunnelID: tunnelID, NodeID: row.NodeID, Kind: "service", Port: int(row.Port.Int64)})
+		}
+		if row.ChainType == "1" || row.ChainType == "2" {
+			items = append(items, model.TunnelRuntimeCleanup{TunnelID: tunnelID, NodeID: row.NodeID, Kind: "chain"})
+		}
+	}
+	return r.QueueTunnelRuntimeCleanupTx(tx, items)
+}

go-backend/tests/contract/federation_dual_panel_contract_test.go

@@ -743,7 +743,7 @@ func TestFederationRuntimeCommandPortRangeEnforcement(t *testing.T) {
 	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
 		t.Fatalf("decode response: %v", err)
 	}
-	if out.Code != 0 {
-		t.Fatalf("expected code 0 for reload command, got %d (msg: %s)", out.Code, out.Msg)
+	if out.Code == 0 {
+		t.Fatal("a shared-node token must not reload the entire provider node")
 	}
 }

go-backend/tests/contract/flow_upload_batch_contract_test.go

@@ -38,6 +38,9 @@ func TestFlowUploadAggregatesRepeatedItemsAndDisablesQuotaImmediately(t *testing
 	if err := repo.DB().Create(forward).Error; err != nil {
 		t.Fatalf("seed forward: %v", err)
 	}
+	if err := repo.DB().Create(&model.ForwardPort{ForwardID: forward.ID, NodeID: node.ID, Port: 10000}).Error; err != nil {
+		t.Fatalf("seed forward node ownership: %v", err)
+	}
 	if err := repo.DB().Exec(`INSERT INTO user_quota(user_id, daily_limit_gb, monthly_limit_gb, daily_used_bytes, monthly_used_bytes, day_key, month_key, disabled_by_quota, disabled_at, paused_forward_ids, created_time, updated_time) VALUES(2, 1, 0, ?, ?, ?, ?, 0, 0, '', ?, ?)`, bytesPerGB-100, bytesPerGB-100, dayKey, monthKey, nowMs, nowMs).Error; err != nil {
 		t.Fatalf("insert user_quota: %v", err)
 	}

go-backend/tests/contract/forward_required_chain_contract_test.go

@@ -0,0 +1,131 @@
+package contract_test
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"sync"
+	"testing"
+	"time"
+
+	"go-backend/internal/auth"
+)
+
+func TestForwardEntryRequiresTunnelChainContract(t *testing.T) {
+	for _, tunnelType := range []int{1, 2} {
+		t.Run(fmt.Sprintf("type-%d", tunnelType), func(t *testing.T) {
+			secret := "contract-jwt-secret"
+			router, repo := setupContractRouter(t, secret)
+			server := httptest.NewServer(router)
+			defer server.Close()
+
+			adminToken, err := auth.GenerateToken(1, "admin_user", 0, secret)
+			if err != nil {
+				t.Fatalf("generate admin token: %v", err)
+			}
+
+			now := time.Now().UnixMilli()
+			if err := repo.DB().Exec(`
+		INSERT INTO user(id, user, pwd, role_id, exp_time, flow, in_flow, out_flow, flow_reset_time, num, created_time, updated_time, status)
+		VALUES(202, 'forward_bind_retry_user', 'pwd', 1, 2727251700000, 99999, 0, 0, 1, 99999, ?, ?, 1)
+	`, now, now).Error; err != nil {
+				t.Fatalf("insert user: %v", err)
+			}
+
+			if err := repo.DB().Exec(`
+		INSERT INTO tunnel(name, traffic_ratio, type, protocol, flow, created_time, updated_time, status, in_ip, inx)
+		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, "forward-bind-retry-tunnel", 1.0, tunnelType, "tls", 99999, now, now, 1, nil, 0).Error; err != nil {
+				t.Fatalf("insert tunnel: %v", err)
+			}
+			tunnelID := mustLastInsertID(t, repo, "forward-bind-retry-tunnel")
+
+			if err := repo.DB().Exec(`
+		INSERT INTO node(name, secret, server_ip, server_ip_v4, server_ip_v6, port, interface_name, version, http, tls, socks, created_time, updated_time, status, tcp_listen_addr, udp_listen_addr, inx)
+		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, "forward-bind-retry-node", "forward-bind-retry-secret", "10.42.0.1", "10.42.0.1", "", "44000-44010", "", "v1", 1, 1, 1, now, now, 1, "10.42.0.9", "[::]", 0).Error; err != nil {
+				t.Fatalf("insert node: %v", err)
+			}
+			nodeID := mustLastInsertID(t, repo, "forward-bind-retry-node")
+
+			if err := repo.DB().Exec(`
+		INSERT INTO chain_tunnel(tunnel_id, chain_type, node_id, port, strategy, inx, protocol)
+		VALUES(?, 1, ?, 44001, 'round', 1, 'tls')
+	`, tunnelID, nodeID).Error; err != nil {
+				t.Fatalf("insert chain_tunnel: %v", err)
+			}
+
+			if tunnelType == 2 {
+				if err := repo.DB().Exec(`
+		INSERT INTO chain_tunnel(tunnel_id, chain_type, node_id, port, strategy, inx, protocol)
+		VALUES(?, 3, ?, 44002, 'round', 1, 'tls')
+	`, tunnelID, nodeID).Error; err != nil {
+					t.Fatalf("insert exit chain: %v", err)
+				}
+			}
+
+			if err := repo.DB().Exec(`
+		INSERT INTO user_tunnel(id, user_id, tunnel_id, speed_id, num, flow, in_flow, out_flow, flow_reset_time, exp_time, status)
+		VALUES(41, 202, ?, NULL, 999, 99999, 0, 0, 1, 2727251700000, 1)
+	`, tunnelID).Error; err != nil {
+				t.Fatalf("insert user_tunnel: %v", err)
+			}
+
+			createPayload := map[string]interface{}{
+				"name":       "forward-bind-retry-target",
+				"tunnelId":   tunnelID,
+				"remoteAddr": "1.1.1.1:443",
+				"strategy":   "fifo",
+			}
+			createBody, err := json.Marshal(createPayload)
+			if err != nil {
+				t.Fatalf("marshal create payload: %v", err)
+			}
+
+			var mu sync.Mutex
+			var emitted []map[string]interface{}
+			stop := startMockNodeSessionWithCommandRecorder(t, server.URL, "forward-bind-retry-secret", func(kind string, data json.RawMessage) (bool, string) {
+				if kind == "AddService" || kind == "UpdateService" {
+					var services []map[string]interface{}
+					if json.Unmarshal(data, &services) == nil {
+						mu.Lock()
+						emitted = append(emitted, services...)
+						mu.Unlock()
+					}
+				}
+				return false, ""
+			})
+			defer stop()
+			waitNodeStatus(t, repo, nodeID, 1)
+			req := httptest.NewRequest(http.MethodPost, "/api/v1/forward/create", bytes.NewReader(createBody))
+			req.Header.Set("Authorization", adminToken)
+			req.Header.Set("Content-Type", "application/json")
+			res := httptest.NewRecorder()
+			router.ServeHTTP(res, req)
+			assertCode(t, res, 0)
+			mu.Lock()
+			defer mu.Unlock()
+			found := 0
+			for _, svc := range emitted {
+				h, ok := svc["handler"].(map[string]interface{})
+				if !ok || (h["type"] != "tcp" && h["type"] != "udp") {
+					continue
+				}
+				found++
+				md, _ := h["metadata"].(map[string]interface{})
+				if tunnelType == 2 {
+					if h["chain"] != fmt.Sprintf("chains_%d", tunnelID) || md["chain.strict"] != true {
+						t.Fatalf("tunnel forward must require chain, got %v", h)
+					}
+				} else if md["chain.strict"] == true {
+					t.Fatal("direct forward cannot require a tunnel chain")
+				}
+			}
+			if found < 2 {
+				t.Fatalf("expected TCP and UDP forwarding commands, got %d", found)
+			}
+		})
+	}
+}

go-backend/tests/contract/passkey_contract_test.go

@@ -0,0 +1,316 @@
+package contract_test
+
+import (
+	"bytes"
+	"crypto/ecdsa"
+	"crypto/elliptic"
+	"crypto/rand"
+	"crypto/sha256"
+	"encoding/base64"
+	"encoding/binary"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/fxamacker/cbor/v2"
+	"go-backend/internal/auth"
+	"go-backend/internal/http/response"
+)
+
+const passkeyTestOrigin = "https://panel.example.test"
+
+func passkeyPost(t *testing.T, router http.Handler, path, token string, body interface{}) response.R {
+	t.Helper()
+	raw, err := json.Marshal(body)
+	if err != nil {
+		t.Fatal(err)
+	}
+	req := httptest.NewRequest(http.MethodPost, path, bytes.NewReader(raw))
+	req.Header.Set("Content-Type", "application/json")
+	if token != "" {
+		req.Header.Set("Authorization", token)
+	}
+	rec := httptest.NewRecorder()
+	router.ServeHTTP(rec, req)
+	var out response.R
+	if err := json.Unmarshal(rec.Body.Bytes(), &out); err != nil {
+		t.Fatalf("decode %s: %v", path, err)
+	}
+	return out
+}
+
+func passkeyData(t *testing.T, out response.R) map[string]interface{} {
+	t.Helper()
+	if out.Code != 0 {
+		t.Fatalf("unexpected response: code=%d msg=%s", out.Code, out.Msg)
+	}
+	return out.Data.(map[string]interface{})
+}
+
+func passkeyChallenge(t *testing.T, data map[string]interface{}) string {
+	t.Helper()
+	options := data["options"].(map[string]interface{})
+	return options["publicKey"].(map[string]interface{})["challenge"].(string)
+}
+
+func TestPasskeyConfigurationFailsClosedAndPasswordLoginStillWorks(t *testing.T) {
+	t.Setenv("FLVX_WEBAUTHN_ORIGIN", "https://panel.example.test/path")
+	router, r := setupContractRouter(t, "passkey-test-secret")
+	seedLegacyUser(t, r, 9301, "passkey-disabled", "test-password")
+	status := passkeyData(t, passkeyPost(t, router, "/api/v1/user/passkey/status", "", map[string]string{}))
+	if status["enabled"] != false {
+		t.Fatalf("invalid origin enabled passkeys: %v", status)
+	}
+	if result := passkeyPost(t, router, "/api/v1/user/passkey/login/begin", "", map[string]string{}); result.Code == 0 {
+		t.Fatal("login begin succeeded with invalid origin")
+	}
+	if result := passkeyPost(t, router, "/api/v1/user/login", "", map[string]string{"username": "passkey-disabled", "password": "test-password"}); result.Code != 0 {
+		t.Fatalf("password login regressed: %s", result.Msg)
+	}
+}
+
+func TestPasskeyRegistrationAndOwnership(t *testing.T) {
+	t.Setenv("FLVX_WEBAUTHN_ORIGIN", passkeyTestOrigin)
+	router, r := setupContractRouter(t, "passkey-test-secret")
+	seedLegacyUser(t, r, 9302, "passkey-alice", "alice-password")
+	seedLegacyUser(t, r, 9303, "passkey-bob", "bob-password")
+	aliceToken, _ := auth.GenerateToken(9302, "passkey-alice", 1, "passkey-test-secret")
+	bobToken, _ := auth.GenerateToken(9303, "passkey-bob", 1, "passkey-test-secret")
+
+	if result := passkeyPost(t, router, "/api/v1/user/passkey/register/begin", "", map[string]string{"password": "alice-password"}); result.Code == 0 {
+		t.Fatal("unauthenticated registration was allowed")
+	}
+	if result := passkeyPost(t, router, "/api/v1/user/passkey/register/begin", aliceToken, map[string]string{"password": "wrong"}); result.Code == 0 {
+		t.Fatal("registration did not require password re-verification")
+	}
+	begin := passkeyData(t, passkeyPost(t, router, "/api/v1/user/passkey/register/begin", aliceToken, map[string]string{"password": "alice-password"}))
+	if result := passkeyPost(t, router, "/api/v1/user/passkey/register/finish", bobToken, map[string]interface{}{"sessionId": begin["sessionId"], "credential": map[string]string{}}); result.Code == 0 {
+		t.Fatal("another user completed Alice's registration")
+	}
+	// The failed cross-user attempt consumes the challenge.
+	begin = passkeyData(t, passkeyPost(t, router, "/api/v1/user/passkey/register/begin", aliceToken, map[string]string{"password": "alice-password"}))
+	selection := begin["options"].(map[string]interface{})["publicKey"].(map[string]interface{})["authenticatorSelection"].(map[string]interface{})
+	if selection["residentKey"] != "required" || selection["requireResidentKey"] != true {
+		t.Fatalf("registration did not require a discoverable credential: %v", selection)
+	}
+	privateKey, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
+	if err != nil {
+		t.Fatal(err)
+	}
+	credentialID := make([]byte, 32)
+	if _, err := rand.Read(credentialID); err != nil {
+		t.Fatal(err)
+	}
+	registerResponse := makeRegistrationResponse(t, privateKey, credentialID, passkeyChallenge(t, begin), passkeyTestOrigin)
+	finishBody := map[string]interface{}{"sessionId": begin["sessionId"], "credential": registerResponse, "name": "Laptop"}
+	if result := passkeyPost(t, router, "/api/v1/user/passkey/register/finish", aliceToken, finishBody); result.Code != 0 {
+		t.Fatalf("register: %s", result.Msg)
+	}
+	if result := passkeyPost(t, router, "/api/v1/user/passkey/register/finish", aliceToken, finishBody); result.Code == 0 {
+		t.Fatal("registration challenge was reusable")
+	}
+	keyID := base64.RawURLEncoding.EncodeToString(credentialID)
+	if items := passkeyPost(t, router, "/api/v1/user/passkey/list", bobToken, map[string]string{}).Data.([]interface{}); len(items) != 0 {
+		t.Fatal("Alice's credential appeared in Bob's list")
+	}
+	if result := passkeyPost(t, router, "/api/v1/user/passkey/delete", bobToken, map[string]string{"id": keyID, "password": "bob-password"}); result.Code == 0 {
+		t.Fatal("Bob deleted Alice's credential")
+	}
+	if result := passkeyPost(t, router, "/api/v1/user/passkey/delete", aliceToken, map[string]string{"id": keyID, "password": "wrong"}); result.Code == 0 {
+		t.Fatal("delete did not require password re-verification")
+	}
+	if result := passkeyPost(t, router, "/api/v1/user/passkey/delete", aliceToken, map[string]string{"id": keyID, "password": "alice-password"}); result.Code != 0 {
+		t.Fatalf("delete: %s", result.Msg)
+	}
+	loginBegin := passkeyData(t, passkeyPost(t, router, "/api/v1/user/passkey/login/begin", "", map[string]string{}))
+	aliceHandle := make([]byte, 8)
+	binary.BigEndian.PutUint64(aliceHandle, 9302)
+	assertion := makeAssertionResponseWithHandle(t, privateKey, credentialID, passkeyChallenge(t, loginBegin), passkeyTestOrigin, "panel.example.test", true, 1, aliceHandle)
+	if result := passkeyPost(t, router, "/api/v1/user/passkey/login/finish", "", map[string]interface{}{"sessionId": loginBegin["sessionId"], "credential": assertion}); result.Code == 0 {
+		t.Fatal("deleted credential could still complete login")
+	}
+	// Deletion must not prevent the same account from binding a new key.
+	rebind := passkeyData(t, passkeyPost(t, router, "/api/v1/user/passkey/register/begin", aliceToken, map[string]string{"password": "alice-password"}))
+	newID := make([]byte, 32)
+	if _, err := rand.Read(newID); err != nil {
+		t.Fatal(err)
+	}
+	newResponse := makeRegistrationResponse(t, privateKey, newID, passkeyChallenge(t, rebind), passkeyTestOrigin)
+	if result := passkeyPost(t, router, "/api/v1/user/passkey/register/finish", aliceToken, map[string]interface{}{"sessionId": rebind["sessionId"], "credential": newResponse}); result.Code != 0 {
+		t.Fatalf("rebind after delete: %s", result.Msg)
+	}
+	if result := passkeyPost(t, router, "/api/v1/user/login", "", map[string]string{"username": "passkey-alice", "password": "alice-password"}); result.Code != 0 {
+		t.Fatalf("password login regressed after enabling passkeys: %s", result.Msg)
+	}
+}
+
+func TestPasskeyDiscoverableLoginAndOwnership(t *testing.T) {
+	t.Setenv("FLVX_WEBAUTHN_ORIGIN", passkeyTestOrigin)
+	router, r := setupContractRouter(t, "passkey-test-secret")
+	seedLegacyUser(t, r, 9311, "discover-alice", "alice-password")
+	seedLegacyUser(t, r, 9312, "discover-bob", "bob-password")
+	aliceToken, _ := auth.GenerateToken(9311, "discover-alice", 1, "passkey-test-secret")
+	privateKey, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
+	if err != nil {
+		t.Fatal(err)
+	}
+	credentialID := make([]byte, 32)
+	if _, err := rand.Read(credentialID); err != nil {
+		t.Fatal(err)
+	}
+	register := passkeyData(t, passkeyPost(t, router, "/api/v1/user/passkey/register/begin", aliceToken, map[string]string{"password": "alice-password"}))
+	registration := makeRegistrationResponse(t, privateKey, credentialID, passkeyChallenge(t, register), passkeyTestOrigin)
+	if result := passkeyPost(t, router, "/api/v1/user/passkey/register/finish", aliceToken, map[string]interface{}{"sessionId": register["sessionId"], "credential": registration}); result.Code != 0 {
+		t.Fatalf("register: %s", result.Msg)
+	}
+	aliceHandle := make([]byte, 8)
+	binary.BigEndian.PutUint64(aliceHandle, 9311)
+	bobHandle := make([]byte, 8)
+	binary.BigEndian.PutUint64(bobHandle, 9312)
+	begin := func(body interface{}) map[string]interface{} {
+		t.Helper()
+		return passkeyData(t, passkeyPost(t, router, "/api/v1/user/passkey/login/begin", "", body))
+	}
+	if result := passkeyPost(t, router, "/api/v1/user/passkey/login/begin", "", map[string]string{"username": "discover-alice"}); result.Code == 0 {
+		t.Fatal("username-based passkey fallback was accepted")
+	}
+	finish := func(session map[string]interface{}, assertion map[string]interface{}) response.R {
+		t.Helper()
+		return passkeyPost(t, router, "/api/v1/user/passkey/login/finish", "", map[string]interface{}{"sessionId": session["sessionId"], "credential": assertion})
+	}
+	assertionFor := func(session map[string]interface{}, handle []byte, origin, rpID string, uv bool, count uint32) map[string]interface{} {
+		t.Helper()
+		return makeAssertionResponseWithHandle(t, privateKey, credentialID, passkeyChallenge(t, session), origin, rpID, uv, count, handle)
+	}
+
+	// No username and no allowCredentials let the authenticator offer an account.
+	session := begin(map[string]string{})
+	options := session["options"].(map[string]interface{})["publicKey"].(map[string]interface{})
+	if list, exists := options["allowCredentials"]; exists && list != nil {
+		t.Fatalf("discoverable login unexpectedly restricted credentials: %v", list)
+	}
+	if options["userVerification"] != "required" {
+		t.Fatalf("discoverable login did not require UV: %v", options)
+	}
+	wrongHandle := assertionFor(session, bobHandle, passkeyTestOrigin, "panel.example.test", true, 1)
+	if result := finish(session, wrongHandle); result.Code == 0 {
+		t.Fatal("Bob's user handle selected Alice's credential")
+	}
+	if result := finish(session, wrongHandle); result.Code == 0 {
+		t.Fatal("failed discoverable challenge was reusable")
+	}
+
+	session = begin(map[string]string{})
+	// Older preferred resident-key registrations may have no discoverable userHandle.
+	missingHandle := assertionFor(session, nil, passkeyTestOrigin, "panel.example.test", true, 1)
+	if result := finish(session, missingHandle); result.Code == 0 {
+		t.Fatal("discoverable login accepted a missing user handle")
+	}
+	session = begin(map[string]string{})
+	unknownID := assertionFor(session, aliceHandle, passkeyTestOrigin, "panel.example.test", true, 1)
+	unknownID["id"] = base64.RawURLEncoding.EncodeToString([]byte("unknown-credential"))
+	unknownID["rawId"] = unknownID["id"]
+	if result := finish(session, unknownID); result.Code == 0 {
+		t.Fatal("unknown credential ID selected Alice's account")
+	}
+
+	for _, test := range []struct {
+		name   string
+		origin string
+		rpID   string
+		uv     bool
+	}{
+		{"origin", "https://wrong.example.test", "panel.example.test", true},
+		{"RP ID", passkeyTestOrigin, "wrong.example.test", true},
+		{"user verification", passkeyTestOrigin, "panel.example.test", false},
+	} {
+		session := begin(map[string]string{})
+		assertion := assertionFor(session, aliceHandle, test.origin, test.rpID, test.uv, 1)
+		if result := finish(session, assertion); result.Code == 0 {
+			t.Fatalf("invalid discoverable assertion was accepted: %s", test.name)
+		}
+	}
+	session = begin(map[string]string{})
+	badSignature := assertionFor(session, aliceHandle, passkeyTestOrigin, "panel.example.test", true, 1)
+	badSignature["response"].(map[string]interface{})["signature"] = base64.RawURLEncoding.EncodeToString([]byte("invalid-signature"))
+	if result := finish(session, badSignature); result.Code == 0 {
+		t.Fatal("invalid signature was accepted")
+	}
+
+	session = begin(map[string]string{})
+	valid := assertionFor(session, aliceHandle, passkeyTestOrigin, "panel.example.test", true, 1)
+	if got := passkeyData(t, finish(session, valid))["name"]; got != "discover-alice" {
+		t.Fatalf("discoverable login selected the wrong account: %v", got)
+	}
+	if result := finish(session, valid); result.Code == 0 {
+		t.Fatal("discoverable assertion was replayed")
+	}
+	session = begin(map[string]string{})
+	reusedCounter := assertionFor(session, aliceHandle, passkeyTestOrigin, "panel.example.test", true, 1)
+	if result := finish(session, reusedCounter); result.Code == 0 {
+		t.Fatal("discoverable login accepted a reused nonzero signature counter")
+	}
+
+	if err := r.DB().Exec("UPDATE user SET status = 0 WHERE id = ?", 9311).Error; err != nil {
+		t.Fatal(err)
+	}
+	session = begin(map[string]string{})
+	disabled := assertionFor(session, aliceHandle, passkeyTestOrigin, "panel.example.test", true, 2)
+	if result := finish(session, disabled); result.Code == 0 {
+		t.Fatal("disabled account logged in with a discoverable credential")
+	}
+}
+
+func makeRegistrationResponse(t *testing.T, privateKey *ecdsa.PrivateKey, id []byte, challenge, origin string) map[string]interface{} {
+	t.Helper()
+	pub := privateKey.PublicKey
+	cose, err := cbor.Marshal(map[int]interface{}{1: 2, 3: -7, -1: 1, -2: pub.X.FillBytes(make([]byte, 32)), -3: pub.Y.FillBytes(make([]byte, 32))})
+	if err != nil {
+		t.Fatal(err)
+	}
+	rpHash := sha256.Sum256([]byte("panel.example.test"))
+	authData := append([]byte{}, rpHash[:]...)
+	authData = append(authData, 0x45, 0, 0, 0, 0)
+	authData = append(authData, make([]byte, 16)...)
+	length := make([]byte, 2)
+	binary.BigEndian.PutUint16(length, uint16(len(id)))
+	authData = append(authData, length...)
+	authData = append(authData, id...)
+	authData = append(authData, cose...)
+	attestation, err := cbor.Marshal(map[string]interface{}{"fmt": "none", "authData": authData, "attStmt": map[string]interface{}{}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	client, _ := json.Marshal(map[string]interface{}{"type": "webauthn.create", "challenge": challenge, "origin": origin})
+	return map[string]interface{}{"id": base64.RawURLEncoding.EncodeToString(id), "rawId": base64.RawURLEncoding.EncodeToString(id), "type": "public-key", "response": map[string]interface{}{"attestationObject": base64.RawURLEncoding.EncodeToString(attestation), "clientDataJSON": base64.RawURLEncoding.EncodeToString(client)}}
+}
+
+func makeAssertionResponse(t *testing.T, privateKey *ecdsa.PrivateKey, id []byte, challenge, origin, rpID string, verified bool, count uint32) map[string]interface{} {
+	return makeAssertionResponseWithHandle(t, privateKey, id, challenge, origin, rpID, verified, count, nil)
+}
+
+func makeAssertionResponseWithHandle(t *testing.T, privateKey *ecdsa.PrivateKey, id []byte, challenge, origin, rpID string, verified bool, count uint32, handle []byte) map[string]interface{} {
+	t.Helper()
+	rpHash := sha256.Sum256([]byte(rpID))
+	authData := append([]byte{}, rpHash[:]...)
+	flags := byte(0x01)
+	if verified {
+		flags |= 0x04
+	}
+	authData = append(authData, flags, 0, 0, 0, 0)
+	binary.BigEndian.PutUint32(authData[33:37], count)
+	client, _ := json.Marshal(map[string]interface{}{"type": "webauthn.get", "challenge": challenge, "origin": origin})
+	clientHash := sha256.Sum256(client)
+	signed := append(append([]byte{}, authData...), clientHash[:]...)
+	hash := sha256.Sum256(signed)
+	signature, err := ecdsa.SignASN1(rand.Reader, privateKey, hash[:])
+	if err != nil {
+		t.Fatal(err)
+	}
+	var userHandle interface{}
+	if handle != nil {
+		userHandle = base64.RawURLEncoding.EncodeToString(handle)
+	}
+	return map[string]interface{}{"id": base64.RawURLEncoding.EncodeToString(id), "rawId": base64.RawURLEncoding.EncodeToString(id), "type": "public-key", "response": map[string]interface{}{"authenticatorData": base64.RawURLEncoding.EncodeToString(authData), "clientDataJSON": base64.RawURLEncoding.EncodeToString(client), "signature": base64.RawURLEncoding.EncodeToString(signature), "userHandle": userHandle}}
+}

go-backend/tests/contract/relay_auth_contract_test.go

@@ -0,0 +1,637 @@
+package contract_test
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"sync"
+	"testing"
+	"time"
+
+	"go-backend/internal/auth"
+	"go-backend/internal/store/repo"
+)
+
+func TestNewRelayTunnelEmitsMatchingPrivateEndpointAuthentication(t *testing.T) {
+	router, r := setupContractRouter(t, "relay-auth-contract")
+	server := httptest.NewServer(router)
+	defer server.Close()
+	token, err := auth.GenerateToken(1, "admin", 0, "relay-auth-contract")
+	if err != nil {
+		t.Fatal(err)
+	}
+	entry := insertContractNode(t, r, "auth-entry", "192.0.2.10", "41000-41010", "entry-management-secret", 1)
+	exit := insertContractNode(t, r, "auth-exit", "192.0.2.11", "42000-42010", "exit-management-secret", 1)
+	var mu sync.Mutex
+	var connector, receiver map[string]interface{}
+	reconnectEvents := make(chan string, 8)
+	watchReconnect := false
+	record := func(kind string, data json.RawMessage) (bool, string) {
+		mu.Lock()
+		defer mu.Unlock()
+		if kind == "AddChains" || kind == "UpdateChains" {
+			var c map[string]interface{}
+			_ = json.Unmarshal(data, &c)
+			if nested, ok := c["data"].(map[string]interface{}); ok {
+				c = nested
+			}
+			hops, _ := c["hops"].([]interface{})
+			if len(hops) > 0 {
+				nodes := hops[0].(map[string]interface{})["nodes"].([]interface{})
+				connector, _ = nodes[0].(map[string]interface{})["connector"].(map[string]interface{})["auth"].(map[string]interface{})
+			}
+		}
+		if kind == "AddService" || kind == "UpdateService" {
+			var services []map[string]interface{}
+			_ = json.Unmarshal(data, &services)
+			if len(services) > 0 {
+				receiver, _ = services[0]["handler"].(map[string]interface{})["auth"].(map[string]interface{})
+				if watchReconnect {
+					p, _ := receiver["password"].(string)
+					select {
+					case reconnectEvents <- p:
+					default:
+					}
+				}
+			}
+		}
+		return false, ""
+	}
+	stopEntry := startMockNodeSessionWithCommandRecorder(t, server.URL, "entry-management-secret", record)
+	defer stopEntry()
+	stopExit := startMockNodeSessionWithCommandRecorder(t, server.URL, "exit-management-secret", record)
+	defer stopExit()
+	payload := map[string]interface{}{"name": "authenticated-new-tunnel", "type": 2, "inNodeId": []map[string]interface{}{{"nodeId": entry, "protocol": "tls"}}, "outNodeId": []map[string]interface{}{{"nodeId": exit, "protocol": "tls"}}}
+	body, _ := json.Marshal(payload)
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/create", bytes.NewReader(body))
+	req.Header.Set("Authorization", token)
+	res := httptest.NewRecorder()
+	router.ServeHTTP(res, req)
+	assertCode(t, res, 0)
+	mu.Lock()
+	if connector == nil || receiver == nil {
+		t.Fatal("new relay tunnel emitted no endpoint authentication")
+	}
+	if connector["username"] == "" || connector["password"] == "" || connector["username"] != receiver["username"] || connector["password"] != receiver["password"] {
+		t.Fatal("relay endpoint credentials missing or mismatched")
+	}
+	if receiver["password"] == "entry-management-secret" || receiver["password"] == "exit-management-secret" {
+		t.Fatal("management secret reused for relay")
+	}
+	listReq := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/list", bytes.NewBufferString(`{}`))
+	listReq.Header.Set("Authorization", token)
+	listRes := httptest.NewRecorder()
+	router.ServeHTTP(listRes, listReq)
+	if !bytes.Contains(listRes.Body.Bytes(), []byte(`"relayAuthMode":"required"`)) {
+		t.Fatalf("tunnel list does not expose required authentication state: %s", listRes.Body.String())
+	}
+	password, _ := receiver["password"].(string)
+	if bytes.Contains(listRes.Body.Bytes(), []byte(password)) {
+		t.Fatal("tunnel list disclosed relay credential")
+	}
+	exportReq := httptest.NewRequest(http.MethodPost, "/api/v1/backup/export", bytes.NewBufferString(`{"types":["tunnels"]}`))
+	exportReq.Header.Set("Authorization", token)
+	exportRes := httptest.NewRecorder()
+	router.ServeHTTP(exportRes, exportReq)
+	if !bytes.Contains(exportRes.Body.Bytes(), []byte(`"relayAuthMode":"required"`)) {
+		t.Fatal("configuration export lost required authentication policy")
+	}
+	if bytes.Contains(exportRes.Body.Bytes(), []byte(password)) {
+		t.Fatal("configuration export disclosed private relay password")
+	}
+	originalPassword := password
+	mu.Unlock()
+	var listed struct {
+		Data []struct {
+			ID int64 `json:"id"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(listRes.Body.Bytes(), &listed); err != nil || len(listed.Data) != 1 {
+		t.Fatal("missing created tunnel in list")
+	}
+	payload["id"] = listed.Data[0].ID
+	body, _ = json.Marshal(payload)
+	updateReq := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/update", bytes.NewReader(body))
+	updateReq.Header.Set("Authorization", token)
+	updateRes := httptest.NewRecorder()
+	router.ServeHTTP(updateRes, updateReq)
+
+	assertCode(t, updateRes, 0)
+	mu.Lock()
+	if connector == nil || receiver == nil || connector["password"] != originalPassword || receiver["password"] != originalPassword {
+		t.Fatal("topology reapply lost or changed persisted endpoint authentication")
+	}
+
+	watchReconnect = true
+	mu.Unlock()
+	stopExit()
+	stopReconnected := startMockNodeSessionWithCommandRecorder(t, server.URL, "exit-management-secret", record)
+	defer stopReconnected()
+	// Request reconciliation explicitly rather than waiting for the production
+	// reconnect debounce (30 seconds). This crosses the same HTTP/command seam.
+	redeployBody, _ := json.Marshal(map[string]interface{}{"ids": []int64{listed.Data[0].ID}})
+	redeployReq := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/batch-redeploy", bytes.NewReader(redeployBody))
+	redeployReq.Header.Set("Authorization", token)
+	redeployRes := httptest.NewRecorder()
+	router.ServeHTTP(redeployRes, redeployReq)
+	assertCode(t, redeployRes, 0)
+
+	select {
+	case password := <-reconnectEvents:
+		if password != originalPassword {
+			t.Fatal("node reconnect lost persisted authentication")
+		}
+	case <-time.After(5 * time.Second):
+		t.Fatal("node reconnect did not reconcile relay service")
+	}
+	// Corrupt private desired state as a fault fixture. Reapply must stop rather
+	// than regenerating a password or emitting an anonymous listener.
+	if err := r.DB().Exec("DELETE FROM relay_endpoint_auth WHERE tunnel_id = ?", listed.Data[0].ID).Error; err != nil {
+		t.Fatal(err)
+	}
+	missingReq := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/update", bytes.NewReader(body))
+	missingReq.Header.Set("Authorization", token)
+	missingRes := httptest.NewRecorder()
+	router.ServeHTTP(missingRes, missingReq)
+	var missing struct {
+		Code int `json:"code"`
+	}
+	_ = json.Unmarshal(missingRes.Body.Bytes(), &missing)
+	if missing.Code == 0 {
+		t.Fatal("missing required credentials silently regenerated or downgraded")
+	}
+}
+
+func TestFederatedRelayRequiresVersionedAuthAndRejectsDowngrade(t *testing.T) {
+	router, r := setupContractRouter(t, "provider-auth-contract")
+	server := httptest.NewServer(router)
+	defer server.Close()
+	node := insertContractNode(t, r, "provider-auth", "192.0.2.30", "45000-45010", "provider-management", 1)
+	insertPeerShare(t, r, &repo.PeerShare{Name: "auth-share", NodeID: node, Token: "auth-share-token", PortRangeStart: 45000, PortRangeEnd: 45010, IsActive: 1})
+	var mu sync.Mutex
+	var received map[string]interface{}
+	stop := startMockNodeSessionWithCommandRecorder(t, server.URL, "provider-management", func(kind string, data json.RawMessage) (bool, string) {
+		if kind == "UpdateService" {
+			var services []map[string]interface{}
+			_ = json.Unmarshal(data, &services)
+			if len(services) > 0 {
+				mu.Lock()
+				received, _ = services[0]["handler"].(map[string]interface{})["auth"].(map[string]interface{})
+				mu.Unlock()
+			}
+		}
+		return false, ""
+	})
+	defer stop()
+	post := func(path string, payload interface{}) *httptest.ResponseRecorder {
+		b, _ := json.Marshal(payload)
+		req := httptest.NewRequest(http.MethodPost, path, bytes.NewReader(b))
+		req.Header.Set("Authorization", "Bearer auth-share-token")
+		res := httptest.NewRecorder()
+		router.ServeHTTP(res, req)
+		return res
+	}
+	reserve := post("/api/v1/federation/runtime/reserve-port", map[string]interface{}{"resourceKey": "auth-contract-endpoint", "protocol": "tls"})
+	var reservation struct {
+		Code int `json:"code"`
+		Data struct {
+			ReservationID    string `json:"reservationId"`
+			RelayAuthVersion int    `json:"relayAuthVersion"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(reserve.Body.Bytes(), &reservation); err != nil || reservation.Code != 0 {
+		t.Fatal("reserve failed")
+	}
+	if reservation.Data.RelayAuthVersion != 1 {
+		t.Fatal("provider did not advertise relay authentication capability")
+	}
+	creds := map[string]interface{}{"version": 1, "username": "test-relay-user", "password": "test-only-relay-password-32-bytes-long"}
+	request := map[string]interface{}{"reservationId": reservation.Data.ReservationID, "resourceKey": "auth-contract-endpoint", "role": "exit", "protocol": "tls", "relayAuth": creds}
+	applied := post("/api/v1/federation/runtime/apply-role", request)
+	if !bytes.Contains(applied.Body.Bytes(), []byte(`"relayAuthVersion":1`)) {
+		t.Fatal("provider did not acknowledge authenticated runtime")
+	}
+	assertCode(t, applied, 0)
+	mu.Lock()
+	actual := received
+	mu.Unlock()
+	if actual == nil || actual["username"] != creds["username"] || actual["password"] != creds["password"] {
+		t.Fatal("provider omitted requested relay authentication")
+	}
+	delete(request, "relayAuth")
+	rejected := post("/api/v1/federation/runtime/apply-role", request)
+	var result struct {
+		Code int `json:"code"`
+	}
+	_ = json.Unmarshal(rejected.Body.Bytes(), &result)
+	if result.Code == 0 {
+		t.Fatal("provider silently downgraded authenticated runtime")
+	}
+
+	// Loss of private persisted state must not be mistaken for legacy mode.
+	if err := r.DB().Exec("UPDATE peer_share_runtime SET relay_auth = '' WHERE resource_key = ?", "auth-contract-endpoint").Error; err != nil {
+		t.Fatal(err)
+	}
+	request["relayAuth"] = creds
+	missing := post("/api/v1/federation/runtime/apply-role", request)
+	_ = json.Unmarshal(missing.Body.Bytes(), &result)
+	if result.Code == 0 {
+		t.Fatal("provider recreated missing protected state instead of failing closed")
+	}
+}
+
+func TestNewFederatedTunnelAuthenticatesEveryRelayHop(t *testing.T) {
+	providerSecret := "provider-contract-jwt"
+	providerRouter, providerRepo := setupContractRouter(t, providerSecret)
+	providerServer := httptest.NewServer(providerRouter)
+	defer providerServer.Close()
+
+	consumerSecret := "consumer-contract-jwt"
+	consumerRouter, consumerRepo := setupContractRouter(t, consumerSecret)
+
+	consumerAdminToken, err := auth.GenerateToken(1, "consumer-admin", 0, consumerSecret)
+	if err != nil {
+		t.Fatalf("generate consumer admin token: %v", err)
+	}
+
+	now := time.Now().UnixMilli()
+	providerEntryNodeID := insertContractNode(t, providerRepo, "provider-entry", "198.51.100.11", "43000-43010", "provider-entry-secret", 1)
+	providerMiddleNodeID := insertContractNode(t, providerRepo, "provider-middle", "198.51.100.12", "44000-44010", "provider-middle-secret", 1)
+	providerExitNodeID := insertContractNode(t, providerRepo, "provider-exit", "198.51.100.13", "45000-45010", "provider-exit-secret", 1)
+
+	_ = insertPeerShare(t, providerRepo, &repo.PeerShare{
+		Name:           "entry-share",
+		NodeID:         providerEntryNodeID,
+		Token:          "share-entry-token",
+		PortRangeStart: 43000,
+		PortRangeEnd:   43010,
+		IsActive:       1,
+		CreatedTime:    now,
+		UpdatedTime:    now,
+	})
+	_ = insertPeerShare(t, providerRepo, &repo.PeerShare{
+		Name:           "middle-share",
+		NodeID:         providerMiddleNodeID,
+		Token:          "share-middle-token",
+		PortRangeStart: 44000,
+		PortRangeEnd:   44010,
+		IsActive:       1,
+		CreatedTime:    now,
+		UpdatedTime:    now,
+	})
+	_ = insertPeerShare(t, providerRepo, &repo.PeerShare{
+		Name:           "exit-share",
+		NodeID:         providerExitNodeID,
+		Token:          "share-exit-token",
+		PortRangeStart: 45000,
+		PortRangeEnd:   45010,
+		IsActive:       1,
+		CreatedTime:    now,
+		UpdatedTime:    now,
+	})
+
+	importRemoteNodeForContract(t, consumerRouter, consumerAdminToken, providerServer.URL, "share-entry-token")
+	importRemoteNodeForContract(t, consumerRouter, consumerAdminToken, providerServer.URL, "share-middle-token")
+	importRemoteNodeForContract(t, consumerRouter, consumerAdminToken, providerServer.URL, "share-exit-token")
+
+	entryRemoteNodeID := queryRemoteNodeIDByToken(t, consumerRepo, "share-entry-token")
+	middleRemoteNodeID := queryRemoteNodeIDByToken(t, consumerRepo, "share-middle-token")
+	exitRemoteNodeID := queryRemoteNodeIDByToken(t, consumerRepo, "share-exit-token")
+
+	var mu sync.Mutex
+	services := map[string]string{}
+	strictMiddle, strictExit := false, false
+	connectors := map[string]string{}
+	record := func(kind string, data json.RawMessage) (bool, string) {
+		mu.Lock()
+		defer mu.Unlock()
+		if kind == "UpdateService" || kind == "AddService" {
+			var items []map[string]interface{}
+			_ = json.Unmarshal(data, &items)
+			for _, item := range items {
+				handler, _ := item["handler"].(map[string]interface{})
+				if handler["type"] == "relay" {
+					md, _ := handler["metadata"].(map[string]interface{})
+					if handler["chain"] != nil {
+						strictMiddle, _ = md["chain.strict"].(bool)
+					} else {
+						strictExit, _ = md["chain.strict"].(bool)
+					}
+					a, _ := handler["auth"].(map[string]interface{})
+					if a != nil {
+						user, _ := a["username"].(string)
+						pass, _ := a["password"].(string)
+						services[user] = pass
+					}
+				}
+			}
+		}
+		if kind == "UpdateChains" || kind == "AddChains" {
+			var c map[string]interface{}
+			_ = json.Unmarshal(data, &c)
+			if d, ok := c["data"].(map[string]interface{}); ok {
+				c = d
+			}
+			hops, _ := c["hops"].([]interface{})
+			for _, hop := range hops {
+				nodes, _ := hop.(map[string]interface{})["nodes"].([]interface{})
+				for _, node := range nodes {
+					a, _ := node.(map[string]interface{})["connector"].(map[string]interface{})["auth"].(map[string]interface{})
+					if a != nil {
+						user, _ := a["username"].(string)
+						pass, _ := a["password"].(string)
+						connectors[user] = pass
+					}
+				}
+			}
+		}
+		return false, ""
+	}
+	stopEntry := startMockNodeSessionWithCommandRecorder(t, providerServer.URL, "provider-entry-secret", record)
+	defer stopEntry()
+	stopMiddle := startMockNodeSessionWithCommandRecorder(t, providerServer.URL, "provider-middle-secret", record)
+	defer stopMiddle()
+	stopExit := startMockNodeSessionWithCommandRecorder(t, providerServer.URL, "provider-exit-secret", record)
+	defer stopExit()
+
+	createTunnel := func(name string) int64 {
+		payload := map[string]interface{}{
+			"name":   name,
+			"type":   2,
+			"flow":   99999,
+			"status": 1,
+			"inNodeId": []map[string]interface{}{
+				{"nodeId": entryRemoteNodeID, "protocol": "tls", "strategy": "round"},
+			},
+			"chainNodes": [][]map[string]interface{}{
+				{{"nodeId": middleRemoteNodeID, "protocol": "tls", "strategy": "round"}},
+			},
+			"outNodeId": []map[string]interface{}{
+				{"nodeId": exitRemoteNodeID, "protocol": "tls", "strategy": "round"},
+			},
+		}
+		body, err := json.Marshal(payload)
+		if err != nil {
+			t.Fatalf("marshal create payload: %v", err)
+		}
+		req := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/create", bytes.NewReader(body))
+		req.Header.Set("Authorization", consumerAdminToken)
+		req.Header.Set("Content-Type", "application/json")
+		res := httptest.NewRecorder()
+		consumerRouter.ServeHTTP(res, req)
+		assertCode(t, res, 0)
+
+		tunnelID := mustQueryInt64(t, consumerRepo, `SELECT id FROM tunnel WHERE name = ? ORDER BY id DESC LIMIT 1`, name)
+		if tunnelID <= 0 {
+			t.Fatalf("invalid tunnel id for %s", name)
+		}
+		return tunnelID
+	}
+
+	_ = createTunnel("dual-panel-middle-exit-1")
+
+	mu.Lock()
+	defer mu.Unlock()
+	if !strictMiddle || strictExit {
+		t.Fatal("middle must require its chain and exit must permit direct dialing")
+	}
+	if len(services) != 2 || len(connectors) != 2 {
+		t.Fatalf("expected two authenticated receivers and matching connectors, got %d and %d", len(services), len(connectors))
+	}
+	for user, pass := range services {
+		if pass == "" || connectors[user] != pass {
+			t.Fatal("federation relay credentials do not match")
+		}
+	}
+}
+
+func TestRelayAuthenticationSurvivesInsertingBeforeExistingMiddle(t *testing.T) {
+	router, r := setupContractRouter(t, "insert-auth-contract")
+	server := httptest.NewServer(router)
+	defer server.Close()
+	token, _ := auth.GenerateToken(1, "admin", 0, "insert-auth-contract")
+	ids := []int64{}
+	var mu sync.Mutex
+	received := map[string]string{}
+	for i, name := range []string{"entry-a", "middle-b", "middle-c", "exit-d"} {
+		id := insertContractNode(t, r, name, fmt.Sprintf("192.0.2.%d", 40+i), fmt.Sprintf("%d-%d", 46000+i*100, 46010+i*100), name+"-secret", 1)
+		ids = append(ids, id)
+		stop := startMockNodeSessionWithCommandRecorder(t, server.URL, name+"-secret", func(kind string, data json.RawMessage) (bool, string) {
+			if kind == "AddService" || kind == "UpdateService" {
+				var items []map[string]interface{}
+				_ = json.Unmarshal(data, &items)
+				for _, item := range items {
+					handler, _ := item["handler"].(map[string]interface{})
+					if a, ok := handler["auth"].(map[string]interface{}); ok {
+						mu.Lock()
+						received[name], _ = a["password"].(string)
+						mu.Unlock()
+					}
+				}
+			}
+			return false, ""
+		})
+		defer stop()
+	}
+	node := func(id int64) map[string]interface{} { return map[string]interface{}{"nodeId": id, "protocol": "tls"} }
+	payload := map[string]interface{}{"name": "insert-auth", "type": 2, "inNodeId": []map[string]interface{}{node(ids[0])}, "chainNodes": [][]map[string]interface{}{{node(ids[1])}}, "outNodeId": []map[string]interface{}{node(ids[3])}}
+	post := func(path string) *httptest.ResponseRecorder {
+		b, _ := json.Marshal(payload)
+		req := httptest.NewRequest(http.MethodPost, path, bytes.NewReader(b))
+		req.Header.Set("Authorization", token)
+		res := httptest.NewRecorder()
+		router.ServeHTTP(res, req)
+		return res
+	}
+	assertCode(t, post("/api/v1/tunnel/create"), 0)
+	mu.Lock()
+	original := received["middle-b"]
+	mu.Unlock()
+	if original == "" {
+		t.Fatal("original middle missing auth")
+	}
+	payload["id"] = mustQueryInt64(t, r, "SELECT id FROM tunnel WHERE name = ?", "insert-auth")
+	payload["chainNodes"] = [][]map[string]interface{}{{node(ids[2])}, {node(ids[1])}}
+	assertCode(t, post("/api/v1/tunnel/update"), 0)
+	mu.Lock()
+	defer mu.Unlock()
+	if received["middle-b"] != original || received["middle-c"] == "" || received["middle-c"] == original {
+		t.Fatal("hop insertion changed existing receiver identity or reused another credential")
+	}
+}
+
+func TestConvertingDirectTunnelRequiresRelayAuthentication(t *testing.T) {
+	router, r := setupContractRouter(t, "relay-auth-contract")
+	server := httptest.NewServer(router)
+	defer server.Close()
+	token, err := auth.GenerateToken(1, "admin", 0, "relay-auth-contract")
+	if err != nil {
+		t.Fatal(err)
+	}
+	entry := insertContractNode(t, r, "auth-entry", "192.0.2.10", "41000-41010", "entry-management-secret", 1)
+	exit := insertContractNode(t, r, "auth-exit", "192.0.2.11", "42000-42010", "exit-management-secret", 1)
+	var mu sync.Mutex
+	var connector, receiver map[string]interface{}
+	record := func(kind string, data json.RawMessage) (bool, string) {
+		mu.Lock()
+		defer mu.Unlock()
+		if kind == "AddChains" || kind == "UpdateChains" {
+			var c map[string]interface{}
+			_ = json.Unmarshal(data, &c)
+			if nested, ok := c["data"].(map[string]interface{}); ok {
+				c = nested
+			}
+			hops, _ := c["hops"].([]interface{})
+			if len(hops) > 0 {
+				nodes := hops[0].(map[string]interface{})["nodes"].([]interface{})
+				connector, _ = nodes[0].(map[string]interface{})["connector"].(map[string]interface{})["auth"].(map[string]interface{})
+			}
+		}
+		if kind == "AddService" || kind == "UpdateService" {
+			var services []map[string]interface{}
+			_ = json.Unmarshal(data, &services)
+			if len(services) > 0 {
+				receiver, _ = services[0]["handler"].(map[string]interface{})["auth"].(map[string]interface{})
+			}
+		}
+		return false, ""
+	}
+	stopEntry := startMockNodeSessionWithCommandRecorder(t, server.URL, "entry-management-secret", record)
+	defer stopEntry()
+	stopExit := startMockNodeSessionWithCommandRecorder(t, server.URL, "exit-management-secret", record)
+	defer stopExit()
+	payload := map[string]interface{}{"name": "authenticated-new-tunnel", "type": 1, "inNodeId": []map[string]interface{}{{"nodeId": entry, "protocol": "tls"}}, "outNodeId": []map[string]interface{}{{"nodeId": exit, "protocol": "tls"}}}
+	body, _ := json.Marshal(payload)
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/create", bytes.NewReader(body))
+	req.Header.Set("Authorization", token)
+	res := httptest.NewRecorder()
+	router.ServeHTTP(res, req)
+	assertCode(t, res, 0)
+	payload["type"] = 2
+	payload["id"] = mustQueryInt64(t, r, "SELECT id FROM tunnel WHERE name = ?", "authenticated-new-tunnel")
+	conversionBody, _ := json.Marshal(payload)
+	conversionReq := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/update", bytes.NewReader(conversionBody))
+	conversionReq.Header.Set("Authorization", token)
+	conversionRes := httptest.NewRecorder()
+	router.ServeHTTP(conversionRes, conversionReq)
+	assertCode(t, conversionRes, 0)
+
+	mu.Lock()
+	if connector == nil || receiver == nil {
+		t.Fatal("new relay tunnel emitted no endpoint authentication")
+	}
+	if connector["username"] == "" || connector["password"] == "" || connector["username"] != receiver["username"] || connector["password"] != receiver["password"] {
+		t.Fatal("relay endpoint credentials missing or mismatched")
+	}
+	if receiver["password"] == "entry-management-secret" || receiver["password"] == "exit-management-secret" {
+		t.Fatal("management secret reused for relay")
+	}
+	listReq := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/list", bytes.NewBufferString(`{}`))
+	listReq.Header.Set("Authorization", token)
+	listRes := httptest.NewRecorder()
+	router.ServeHTTP(listRes, listReq)
+	if !bytes.Contains(listRes.Body.Bytes(), []byte(`"relayAuthMode":"required"`)) {
+		t.Fatalf("tunnel list does not expose required authentication state: %s", listRes.Body.String())
+	}
+	password, _ := receiver["password"].(string)
+	if bytes.Contains(listRes.Body.Bytes(), []byte(password)) {
+		t.Fatal("tunnel list disclosed relay credential")
+	}
+	originalPassword := password
+	mu.Unlock()
+	var listed struct {
+		Data []struct {
+			ID int64 `json:"id"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(listRes.Body.Bytes(), &listed); err != nil || len(listed.Data) != 1 {
+		t.Fatal("missing created tunnel in list")
+	}
+	payload["id"] = listed.Data[0].ID
+	body, _ = json.Marshal(payload)
+	updateReq := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/update", bytes.NewReader(body))
+	updateReq.Header.Set("Authorization", token)
+	updateRes := httptest.NewRecorder()
+	router.ServeHTTP(updateRes, updateReq)
+
+	assertCode(t, updateRes, 0)
+	mu.Lock()
+	defer mu.Unlock()
+	if connector == nil || receiver == nil || connector["password"] != originalPassword || receiver["password"] != originalPassword {
+		t.Fatal("topology reapply lost or changed persisted endpoint authentication")
+	}
+}
+
+func TestBackupImportCannotSilentlyDowngradeRequiredRelay(t *testing.T) {
+	router, _ := setupContractRouter(t, "backup-relay-auth")
+	token, _ := auth.GenerateToken(1, "admin", 0, "backup-relay-auth")
+	request := httptest.NewRequest(http.MethodPost, "/api/v1/backup/import", bytes.NewBufferString(`{"version":"1","types":["tunnels"],"tunnels":[{"id":92,"name":"protected-backup","type":2,"protocol":"tls","flow":1,"trafficRatio":1,"createdTime":1000,"status":1,"relayAuthMode":"required"}]}`))
+	request.Header.Set("Authorization", token)
+	result := httptest.NewRecorder()
+	router.ServeHTTP(result, request)
+	var out struct {
+		Code int `json:"code"`
+	}
+	if err := json.Unmarshal(result.Body.Bytes(), &out); err != nil {
+		t.Fatal(err)
+	}
+
+	if out.Code == 0 {
+		t.Fatal("configuration backup restored required relay without its private credentials")
+	}
+}
+
+func TestNewRelayTunnelRefusesLegacyFederationBeforeReservation(t *testing.T) {
+	var mu sync.Mutex
+	mutations := 0
+	oldPeer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
+		if req.URL.Path != "/api/v1/federation/connect" {
+			mu.Lock()
+			mutations++
+			mu.Unlock()
+		}
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"code":0,"data":{"shareId":1,"shareName":"legacy","nodeId":1,"nodeName":"legacy-exit","serverIp":"192.0.2.80","status":1,"portRangeStart":49000,"portRangeEnd":49010}}`))
+	}))
+	defer oldPeer.Close()
+	router, r := setupContractRouter(t, "legacy-peer-contract")
+	token, _ := auth.GenerateToken(1, "admin", 0, "legacy-peer-contract")
+	entry := insertContractNode(t, r, "legacy-test-entry", "192.0.2.79", "48000-48010", "legacy-test-entry-secret", 1)
+	importRemoteNodeForContract(t, router, token, oldPeer.URL, "legacy-share-token")
+	exit := queryRemoteNodeIDByToken(t, r, "legacy-share-token")
+	payload := map[string]interface{}{"name": "must-not-downgrade", "type": 2, "inNodeId": []map[string]interface{}{{"nodeId": entry, "protocol": "tls"}}, "outNodeId": []map[string]interface{}{{"nodeId": exit, "protocol": "tls"}}}
+	b, _ := json.Marshal(payload)
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/create", bytes.NewReader(b))
+	req.Header.Set("Authorization", token)
+	res := httptest.NewRecorder()
+	router.ServeHTTP(res, req)
+	var out struct {
+		Code int `json:"code"`
+	}
+	_ = json.Unmarshal(res.Body.Bytes(), &out)
+	if out.Code == 0 {
+		t.Fatal("new tunnel silently accepted legacy federation")
+	}
+	mu.Lock()
+	defer mu.Unlock()
+	if mutations != 0 {
+		t.Fatal("legacy peer was mutated before capability refusal")
+	}
+}
+
+func TestLegacyRelayStateRemainsExplicitInList(t *testing.T) {
+	router, r := setupContractRouter(t, "legacy-mode-contract")
+	token, _ := auth.GenerateToken(1, "admin", 0, "legacy-mode-contract")
+	if err := r.DB().Exec(`INSERT INTO tunnel(name,traffic_ratio,type,protocol,flow,created_time,updated_time,status,inx) VALUES('legacy-existing',1,2,'tls',1,1000,1000,1,0)`).Error; err != nil {
+		t.Fatal(err)
+	}
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/list", nil)
+	req.Header.Set("Authorization", token)
+	res := httptest.NewRecorder()
+	router.ServeHTTP(res, req)
+	if !bytes.Contains(res.Body.Bytes(), []byte(`"relayAuthMode":"legacy"`)) {
+		t.Fatal("legacy relay exposure is hidden from API clients")
+	}
+}

go-backend/tests/contract/system_upgrade_status_contract_test.go

@@ -0,0 +1,73 @@
+package contract_test
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"strings"
+	"testing"
+
+	"go-backend/internal/auth"
+	"go-backend/internal/http/response"
+)
+
+func TestSystemUpgradeStatusRequiresAdminAndReturnsLocalState(t *testing.T) {
+	secret := "upgrade-status-contract-secret"
+	dir := t.TempDir()
+	t.Setenv("PANEL_DEPLOY_DIR", dir)
+	t.Setenv("FLUX_VERSION", "3.0.1-rc10")
+	// A status read with no job must not require Docker or contact GitHub.
+	t.Setenv("PATH", t.TempDir())
+	router, r := setupContractRouter(t, secret)
+	seedContractUser(t, r, 2, "normal_user", 1, 1)
+	adminToken, err := auth.GenerateToken(1, "admin_user", 0, secret)
+	if err != nil {
+		t.Fatal(err)
+	}
+	userToken, err := auth.GenerateToken(2, "normal_user", 1, secret)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, tc := range []struct {
+		name, token string
+		want        int
+	}{{"anonymous", "", 401}, {"normal user", userToken, 403}, {"admin", adminToken, 0}} {
+		t.Run(tc.name, func(t *testing.T) {
+			req := httptest.NewRequest(http.MethodPost, "/api/v1/system/upgrade/status", strings.NewReader(`{}`))
+			req.Header.Set("Authorization", tc.token)
+			rr := httptest.NewRecorder()
+			router.ServeHTTP(rr, req)
+			var out response.R
+			if err := json.NewDecoder(rr.Body).Decode(&out); err != nil {
+				t.Fatal(err)
+			}
+			if out.Code != tc.want {
+				t.Fatalf("expected code %d, got %d: %s", tc.want, out.Code, out.Msg)
+			}
+			if tc.want == 0 {
+				data, ok := out.Data.(map[string]interface{})
+				if !ok || data["currentVersion"] != "3.0.1-rc10" || data["job"] != nil {
+					t.Fatalf("unexpected idle status: %#v", out.Data)
+				}
+			}
+		})
+	}
+	entries, err := os.ReadDir(dir)
+	if err != nil || len(entries) != 0 {
+		t.Fatalf("idle status should not mutate deployment: entries=%v err=%v", entries, err)
+	}
+	for _, body := range []string{`{"jobId":"../../.env"}`, `{"jobId":`, `{"jobId":123}`} {
+		req := httptest.NewRequest(http.MethodPost, "/api/v1/system/upgrade/status", strings.NewReader(body))
+		req.Header.Set("Authorization", adminToken)
+		rr := httptest.NewRecorder()
+		router.ServeHTTP(rr, req)
+		var out response.R
+		if err := json.NewDecoder(rr.Body).Decode(&out); err != nil {
+			t.Fatal(err)
+		}
+		if out.Code == 0 || out.Data != nil || strings.Contains(out.Msg, dir) || strings.Contains(out.Msg, ".env") {
+			t.Fatalf("invalid request must fail without leaking filesystem detail: %#v", out)
+		}
+	}
+}

go-backend/tests/contract/tunnel_create_lifecycle_test.go

@@ -0,0 +1,311 @@
+package contract_test
+
+import (
+	"bytes"
+	"encoding/json"
+	"go-backend/internal/auth"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+)
+
+func TestTunnelDeleteWaitsForCreateRuntime(t *testing.T) {
+	router, r := setupContractRouter(t, "create-lifecycle")
+	server := httptest.NewServer(router)
+	defer server.Close()
+	token, err := auth.GenerateToken(1, "admin", 0, "create-lifecycle")
+	if err != nil {
+		t.Fatal(err)
+	}
+	entry := insertContractNode(t, r, "create-entry", "192.0.2.10", "41000-41010", "create-entry-secret", 1)
+	exit := insertContractNode(t, r, "create-exit", "192.0.2.11", "42000-42010", "create-exit-secret", 1)
+	entered, release := make(chan struct{}), make(chan struct{})
+	var once, releaseOnce sync.Once
+	unblock := func() { releaseOnce.Do(func() { close(release) }) }
+	deleted := make(chan struct{}, 1)
+	stopEntry := startMockNodeSessionWithCommandRecorder(t, server.URL, "create-entry-secret", func(kind string, _ json.RawMessage) (bool, string) {
+		if kind == "DeleteChains" {
+			select {
+			case deleted <- struct{}{}:
+			default:
+			}
+		}
+		return false, ""
+	})
+	defer stopEntry()
+	stopExit := startMockNodeSessionWithCommandRecorder(t, server.URL, "create-exit-secret", func(kind string, _ json.RawMessage) (bool, string) {
+		if kind == "AddService" {
+			once.Do(func() { close(entered); <-release })
+		}
+		return false, ""
+	})
+	defer stopExit()
+	defer unblock()
+	post := func(path string, payload interface{}) *httptest.ResponseRecorder {
+		raw, _ := json.Marshal(payload)
+		req := httptest.NewRequest(http.MethodPost, path, bytes.NewReader(raw))
+		req.Header.Set("Authorization", token)
+		res := httptest.NewRecorder()
+		router.ServeHTTP(res, req)
+		return res
+	}
+	created := make(chan *httptest.ResponseRecorder, 1)
+	go func() {
+		created <- post("/api/v1/tunnel/create", map[string]interface{}{"name": "create-race", "type": 2, "inNodeId": []map[string]interface{}{{"nodeId": entry, "protocol": "tls"}}, "outNodeId": []map[string]interface{}{{"nodeId": exit, "protocol": "tls"}}})
+	}()
+	select {
+	case <-entered:
+	case <-time.After(5 * time.Second):
+		t.Fatal("create did not reach runtime gate")
+	}
+	listed := post("/api/v1/tunnel/list", map[string]interface{}{})
+	var list struct {
+		Data []struct {
+			ID int64 `json:"id"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(listed.Body.Bytes(), &list); err != nil || len(list.Data) != 1 {
+		t.Fatal("committed create not listed")
+	}
+	deleteDone := make(chan *httptest.ResponseRecorder, 1)
+	go func() { deleteDone <- post("/api/v1/tunnel/delete", map[string]interface{}{"id": list.Data[0].ID}) }()
+	select {
+	case <-deleted:
+		t.Error("delete removed runtime while create was still applying")
+	case <-time.After(150 * time.Millisecond):
+	}
+	unblock()
+	for _, done := range []chan *httptest.ResponseRecorder{created, deleteDone} {
+		select {
+		case res := <-done:
+			assertCode(t, res, 0)
+		case <-time.After(5 * time.Second):
+			t.Fatal("lifecycle operation stuck")
+		}
+	}
+	listed = post("/api/v1/tunnel/list", map[string]interface{}{})
+	if err := json.Unmarshal(listed.Body.Bytes(), &list); err != nil || len(list.Data) != 0 {
+		t.Fatal("deleted tunnel remains listed")
+	}
+}
+
+func TestOfflineTunnelCreateReportsPendingRuntime(t *testing.T) {
+	router, r := setupContractRouter(t, "pending-lifecycle")
+	token, err := auth.GenerateToken(1, "admin", 0, "pending-lifecycle")
+	if err != nil {
+		t.Fatal(err)
+	}
+	entry := insertContractNode(t, r, "pending-entry", "192.0.2.10", "41000-41010", "pending-entry-secret", 1)
+	exit := insertContractNode(t, r, "pending-exit", "192.0.2.11", "42000-42010", "pending-exit-secret", 1)
+	payload := map[string]interface{}{"name": "pending-tunnel", "type": 2, "inNodeId": []map[string]interface{}{{"nodeId": entry, "protocol": "tls"}}, "outNodeId": []map[string]interface{}{{"nodeId": exit, "protocol": "tls"}}}
+	raw, _ := json.Marshal(payload)
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/create", bytes.NewReader(raw))
+	req.Header.Set("Authorization", token)
+	res := httptest.NewRecorder()
+	router.ServeHTTP(res, req)
+	var out struct {
+		Code int    `json:"code"`
+		Msg  string `json:"msg"`
+		Data struct {
+			RuntimeStatus string `json:"runtimeStatus"`
+			TunnelID      int64  `json:"tunnelId"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(res.Body.Bytes(), &out); err != nil {
+		t.Fatal(err)
+	}
+	if out.Code != 0 || out.Data.RuntimeStatus != "pending" || out.Data.TunnelID <= 0 || out.Msg == "操作成功" {
+		t.Fatalf("offline create must preserve config but explicitly report pending: %s", res.Body.String())
+	}
+
+	payload["id"] = out.Data.TunnelID
+	raw, _ = json.Marshal(payload)
+	req = httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/update", bytes.NewReader(raw))
+	req.Header.Set("Authorization", token)
+	res = httptest.NewRecorder()
+	router.ServeHTTP(res, req)
+	out.Data.RuntimeStatus = ""
+	if err := json.Unmarshal(res.Body.Bytes(), &out); err != nil {
+		t.Fatal(err)
+	}
+	if out.Code != 0 || out.Data.RuntimeStatus != "pending" {
+		t.Fatalf("offline update must report pending: %s", res.Body.String())
+	}
+	raw, _ = json.Marshal(map[string]interface{}{"ids": []int64{out.Data.TunnelID}})
+	req = httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/batch-redeploy", bytes.NewReader(raw))
+	req.Header.Set("Authorization", token)
+	res = httptest.NewRecorder()
+	router.ServeHTTP(res, req)
+	var batch struct {
+		Data struct {
+			SuccessCount int `json:"successCount"`
+			FailCount    int `json:"failCount"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(res.Body.Bytes(), &batch); err != nil {
+		t.Fatal(err)
+	}
+	if batch.Data.SuccessCount != 0 || batch.Data.FailCount != 1 {
+		t.Fatalf("pending redeploy must not count as success: %s", res.Body.String())
+	}
+}
+
+func TestPendingTunnelUpdateStillRemovesObsoleteRelay(t *testing.T) {
+	testPendingTunnelRemoval(t, false, false)
+}
+func TestFailedObsoleteRelayRemovalPreservesItsChain(t *testing.T) {
+	testPendingTunnelRemoval(t, true, false)
+}
+func TestRedesiredRelayKeepsOldPortReservedUntilReplacementAcknowledged(t *testing.T) {
+	testPendingTunnelRemoval(t, true, true)
+}
+
+func testPendingTunnelRemoval(t *testing.T, failCleanup, readd bool) {
+	router, r := setupContractRouter(t, "pending-removal")
+	server := httptest.NewServer(router)
+	defer server.Close()
+	token, err := auth.GenerateToken(1, "admin", 0, "pending-removal")
+	if err != nil {
+		t.Fatal(err)
+	}
+	entry := insertContractNode(t, r, "removal-entry", "192.0.2.10", "41000-41010", "removal-entry-secret", 1)
+	middle := insertContractNode(t, r, "removal-middle", "192.0.2.20", "42000-42010", "removal-middle-secret", 1)
+	exit := insertContractNode(t, r, "removal-exit", "192.0.2.30", "43000-43010", "removal-exit-secret", 1)
+	var entryTimeout atomic.Bool
+	stopEntry := startMockNodeSessionWithCommandRecorder(t, server.URL, "removal-entry-secret", func(kind string, _ json.RawMessage) (bool, string) {
+		if entryTimeout.Load() && (kind == "AddChains" || kind == "UpdateChains") {
+			return true, "等待节点响应超时"
+		}
+		return false, ""
+	})
+	defer stopEntry()
+	var mu sync.Mutex
+	deleted := map[string]bool{}
+	var timeoutReplacement bool
+	stopMiddle := startMockNodeSessionWithCommandRecorder(t, server.URL, "removal-middle-secret", func(kind string, _ json.RawMessage) (bool, string) {
+		mu.Lock()
+		defer mu.Unlock()
+		if kind == "DeleteService" || kind == "DeleteChains" {
+			deleted[kind] = true
+		}
+		if timeoutReplacement && kind == "UpdateService" {
+			return true, "等待节点响应超时"
+		}
+		if failCleanup && kind == "DeleteService" {
+			return true, "cleanup rejected"
+		}
+		return false, ""
+	})
+	defer stopMiddle()
+	stopExit := startMockNodeSession(t, server.URL, "removal-exit-secret")
+	defer stopExit()
+	post := func(path string, payload interface{}) *httptest.ResponseRecorder {
+		raw, _ := json.Marshal(payload)
+		req := httptest.NewRequest(http.MethodPost, path, bytes.NewReader(raw))
+		req.Header.Set("Authorization", token)
+		res := httptest.NewRecorder()
+		router.ServeHTTP(res, req)
+		return res
+	}
+	payload := map[string]interface{}{"name": "pending-removal", "type": 2, "inNodeId": []map[string]interface{}{{"nodeId": entry, "protocol": "tls"}}, "chainNodes": [][]map[string]interface{}{{{"nodeId": middle, "protocol": "tls", "port": 42000}}}, "outNodeId": []map[string]interface{}{{"nodeId": exit, "protocol": "tls"}}}
+	assertCode(t, post("/api/v1/tunnel/create", payload), 0)
+	listed := post("/api/v1/tunnel/list", map[string]interface{}{})
+	var list struct {
+		Data []struct {
+			ID int64 `json:"id"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(listed.Body.Bytes(), &list); err != nil || len(list.Data) != 1 {
+		t.Fatal("missing tunnel")
+	}
+	if readd {
+		entryTimeout.Store(true)
+	} else {
+		stopEntry()
+		waitNodeStatus(t, r, entry, 0)
+	}
+	payload["id"] = list.Data[0].ID
+	payload["chainNodes"] = [][]map[string]interface{}{}
+	res := post("/api/v1/tunnel/update", payload)
+	var out struct {
+		Msg  string `json:"msg"`
+		Code int    `json:"code"`
+		Data struct {
+			RuntimeStatus string `json:"runtimeStatus"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(res.Body.Bytes(), &out); err != nil {
+		t.Fatal(err)
+	}
+	if out.Code != 0 || out.Data.RuntimeStatus != "pending" {
+		t.Fatalf("expected pending update: %s", res.Body.String())
+	}
+	mu.Lock()
+	defer mu.Unlock()
+	if failCleanup {
+		if !deleted["DeleteService"] || deleted["DeleteChains"] {
+			t.Fatalf("failed listener deletion must preserve its required chain: %v", deleted)
+		}
+		if !strings.Contains(out.Msg, "cleanup rejected") {
+			t.Fatalf("cleanup failure hidden: %s", out.Msg)
+		}
+		if readd {
+			deleted = map[string]bool{}
+			timeoutReplacement = true
+			mu.Unlock()
+			payload["chainNodes"] = [][]map[string]interface{}{{{"nodeId": middle, "protocol": "tls", "port": 42001}}}
+			changed := post("/api/v1/tunnel/update", payload)
+			if err := json.Unmarshal(changed.Body.Bytes(), &out); err != nil {
+				t.Fatal(err)
+			}
+			if out.Code != 0 || out.Data.RuntimeStatus != "pending" {
+				t.Fatalf("expected pending replacement: %s", changed.Body.String())
+			}
+			contender := map[string]interface{}{"name": "old-port-contender", "type": 2, "inNodeId": payload["inNodeId"], "outNodeId": payload["outNodeId"], "chainNodes": [][]map[string]interface{}{{{"nodeId": middle, "protocol": "tls", "port": 42000}}}}
+			blocked := post("/api/v1/tunnel/create", contender)
+			if err := json.Unmarshal(blocked.Body.Bytes(), &out); err != nil {
+				t.Fatal(err)
+			}
+			if out.Code == 0 || !strings.Contains(out.Msg, "旧运行时清理") {
+				t.Fatalf("unacknowledged old port was not reserved: %s", blocked.Body.String())
+			}
+			mu.Lock()
+			timeoutReplacement = false
+			mu.Unlock()
+			post("/api/v1/tunnel/batch-redeploy", map[string]interface{}{"ids": []int64{list.Data[0].ID}})
+			accepted := post("/api/v1/tunnel/create", contender)
+			if err := json.Unmarshal(accepted.Body.Bytes(), &out); err != nil {
+				t.Fatal(err)
+			}
+			if out.Code != 0 {
+				t.Fatalf("acknowledged replacement did not release old port: %s", accepted.Body.String())
+			}
+			mu.Lock()
+			if len(deleted) != 0 {
+				t.Fatalf("delayed cleanup deleted re-desired relay: %v", deleted)
+			}
+			return
+		}
+		failCleanup = false
+		deleted = map[string]bool{}
+		mu.Unlock()
+		post("/api/v1/tunnel/batch-redeploy", map[string]interface{}{"ids": []int64{list.Data[0].ID}})
+		mu.Lock()
+		if !deleted["DeleteService"] || !deleted["DeleteChains"] {
+			t.Fatalf("redeploy lost obsolete cleanup ownership after failure: %v", deleted)
+		}
+		deleted = map[string]bool{}
+		mu.Unlock()
+		post("/api/v1/tunnel/batch-redeploy", map[string]interface{}{"ids": []int64{list.Data[0].ID}})
+		mu.Lock()
+		if len(deleted) != 0 {
+			t.Fatalf("acknowledged cleanup repeated: %v", deleted)
+		}
+	} else if !deleted["DeleteService"] || !deleted["DeleteChains"] {
+		t.Fatalf("pending update left removed relay live: %v", deleted)
+	}
+}

go-backend/tests/contract/tunnel_create_port_reservation_test.go

@@ -0,0 +1,92 @@
+package contract_test
+
+import (
+	"bytes"
+	"encoding/json"
+	"go-backend/internal/auth"
+	"go-backend/internal/store/repo"
+	"net/http"
+	"net/http/httptest"
+	"sync"
+	"testing"
+	"time"
+)
+
+func TestConcurrentCreatesReserveLocalPortsBeforeFederationAcknowledgment(t *testing.T) {
+	provider, pr := setupContractRouter(t, "port-provider")
+	entered, release := make(chan struct{}), make(chan struct{})
+	var gateOnce, releaseOnce sync.Once
+	unblock := func() { releaseOnce.Do(func() { close(release) }) }
+	ps := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path == "/api/v1/federation/runtime/apply-role" {
+			gateOnce.Do(func() { close(entered); <-release })
+		}
+		provider.ServeHTTP(w, r)
+	}))
+	defer ps.Close()
+	exit := insertContractNode(t, pr, "provider-port-exit", "192.0.2.30", "43000-43010", "provider-port-exit-secret", 1)
+	now := time.Now().UnixMilli()
+	insertPeerShare(t, pr, &repo.PeerShare{Name: "port-share", NodeID: exit, Token: "port-share-token", PortRangeStart: 43000, PortRangeEnd: 43010, IsActive: 1, CreatedTime: now, UpdatedTime: now})
+	stop := startMockNodeSession(t, ps.URL, "provider-port-exit-secret")
+	defer stop()
+	defer unblock()
+	consumer, cr := setupContractRouter(t, "port-consumer")
+	token, err := auth.GenerateToken(1, "admin", 0, "port-consumer")
+	if err != nil {
+		t.Fatal(err)
+	}
+	entry := insertContractNode(t, cr, "local-port-entry", "192.0.2.10", "41000-41010", "local-port-entry-secret", 1)
+	middle := insertContractNode(t, cr, "local-port-middle", "192.0.2.20", "42000", "local-port-middle-secret", 1)
+	importRemoteNodeForContract(t, consumer, token, ps.URL, "port-share-token")
+	remoteExit := queryRemoteNodeIDByToken(t, cr, "port-share-token")
+	create := func(name string) *httptest.ResponseRecorder {
+		payload := map[string]interface{}{"name": name, "type": 2, "inNodeId": []map[string]interface{}{{"nodeId": entry, "protocol": "tls"}}, "chainNodes": [][]map[string]interface{}{{{"nodeId": middle, "protocol": "tls"}}}, "outNodeId": []map[string]interface{}{{"nodeId": remoteExit, "protocol": "tls"}}}
+		raw, _ := json.Marshal(payload)
+		req := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/create", bytes.NewReader(raw))
+		req.Header.Set("Authorization", token)
+		res := httptest.NewRecorder()
+		consumer.ServeHTTP(res, req)
+		return res
+	}
+	first := make(chan *httptest.ResponseRecorder, 1)
+	go func() { first <- create("port-owner") }()
+	select {
+	case <-entered:
+	case <-time.After(5 * time.Second):
+		t.Fatal("first create did not reach provider gate")
+	}
+	second := make(chan *httptest.ResponseRecorder, 1)
+	go func() { second <- create("port-contender") }()
+	secondCompleted := false
+	select {
+	case res := <-second:
+		secondCompleted = true
+		var out struct {
+			Code int `json:"code"`
+		}
+		if err := json.Unmarshal(res.Body.Bytes(), &out); err != nil {
+			t.Fatal(err)
+		}
+		if out.Code == 0 {
+			t.Errorf("second create reused the only reserved local port: %s", res.Body.String())
+		}
+	case <-time.After(300 * time.Millisecond):
+		t.Error("second create did not reject the reserved local port before provider acknowledgment")
+	}
+	unblock()
+	select {
+	case res := <-first:
+		assertCode(t, res, 0)
+	case <-time.After(5 * time.Second):
+		t.Fatal("first create stuck")
+	}
+	// If the regression let the second request reach the gated provider, drain it
+	// before closing test servers; its success still cannot erase the failure above.
+	if !secondCompleted {
+		select {
+		case <-second:
+		case <-time.After(5 * time.Second):
+			t.Fatal("second create stuck after gate release")
+		}
+	}
+}

go-backend/tests/contract/tunnel_deleted_cleanup_test.go

@@ -0,0 +1,110 @@
+package contract_test
+
+import (
+	"bytes"
+	"encoding/json"
+	"go-backend/internal/auth"
+	httpserver "go-backend/internal/http"
+	"go-backend/internal/http/handler"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync/atomic"
+	"testing"
+)
+
+func TestDeletedTunnelCleanupSurvivesHandlerReplacement(t *testing.T) {
+	const secret = "deleted-cleanup"
+	router, r := setupContractRouter(t, secret)
+	server := httptest.NewServer(router)
+	defer server.Close()
+	token, err := auth.GenerateToken(1, "admin", 0, secret)
+	if err != nil {
+		t.Fatal(err)
+	}
+	entry := insertContractNode(t, r, "deleted-entry", "192.0.2.10", "41000-41010", "deleted-entry-secret", 1)
+	exit := insertContractNode(t, r, "deleted-exit", "192.0.2.20", "42000", "deleted-exit-secret", 1)
+	stopEntry := startMockNodeSession(t, server.URL, "deleted-entry-secret")
+	defer stopEntry()
+	var rejectDelete atomic.Bool
+	rejectDelete.Store(true)
+	stopExit := startMockNodeSessionWithCommandRecorder(t, server.URL, "deleted-exit-secret", func(kind string, _ json.RawMessage) (bool, string) {
+		if kind == "DeleteService" && rejectDelete.Load() {
+			return true, "cleanup rejected"
+		}
+		return false, ""
+	})
+	defer stopExit()
+	post := func(path string, payload interface{}) *httptest.ResponseRecorder {
+		raw, _ := json.Marshal(payload)
+		req := httptest.NewRequest(http.MethodPost, path, bytes.NewReader(raw))
+		req.Header.Set("Authorization", token)
+		res := httptest.NewRecorder()
+		router.ServeHTTP(res, req)
+		return res
+	}
+	payload := map[string]interface{}{"name": "deleted-owner", "type": 2, "inNodeId": []map[string]interface{}{{"nodeId": entry, "protocol": "tls"}}, "outNodeId": []map[string]interface{}{{"nodeId": exit, "protocol": "tls", "port": 42000}}}
+	assertCode(t, post("/api/v1/tunnel/create", payload), 0)
+	listed := post("/api/v1/tunnel/list", map[string]interface{}{})
+	var list struct {
+		Data []struct {
+			ID int64 `json:"id"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(listed.Body.Bytes(), &list); err != nil || len(list.Data) != 1 {
+		t.Fatal("missing tunnel")
+	}
+	id := list.Data[0].ID
+	res := post("/api/v1/tunnel/delete", map[string]interface{}{"id": id})
+	var out struct {
+		Code int    `json:"code"`
+		Msg  string `json:"msg"`
+	}
+	if err := json.Unmarshal(res.Body.Bytes(), &out); err != nil {
+		t.Fatal(err)
+	}
+	if out.Code == 0 || !strings.Contains(out.Msg, "待重试") {
+		t.Fatalf("failed post-delete cleanup not reported: %s", res.Body.String())
+	}
+	listed = post("/api/v1/tunnel/list", map[string]interface{}{})
+	if err := json.Unmarshal(listed.Body.Bytes(), &list); err != nil || len(list.Data) != 0 {
+		t.Fatal("desired tunnel not deleted")
+	}
+	payload["name"] = "deleted-port-contender"
+	res = post("/api/v1/tunnel/create", payload)
+	if err := json.Unmarshal(res.Body.Bytes(), &out); err != nil {
+		t.Fatal(err)
+	}
+	if out.Code == 0 || !strings.Contains(out.Msg, "旧运行时清理") {
+		t.Fatalf("deleted tunnel lost port ownership: %s", res.Body.String())
+	}
+	stopEntry()
+	stopExit()
+	waitNodeStatus(t, r, entry, 0)
+	waitNodeStatus(t, r, exit, 0)
+	// A fresh handler has no old in-memory topology, locks, or cleanup state.
+	router = httpserver.NewRouter(handler.New(r, secret), secret)
+	recoveredServer := httptest.NewServer(router)
+	defer recoveredServer.Close()
+	newEntry := startMockNodeSession(t, recoveredServer.URL, "deleted-entry-secret")
+	defer newEntry()
+	var deleted atomic.Int32
+	newExit := startMockNodeSessionWithCommandRecorder(t, recoveredServer.URL, "deleted-exit-secret", func(kind string, _ json.RawMessage) (bool, string) {
+		if kind == "DeleteService" {
+			deleted.Add(1)
+		}
+		return false, ""
+	})
+	defer newExit()
+	waitNodeStatus(t, r, entry, 1)
+	waitNodeStatus(t, r, exit, 1)
+	assertCode(t, post("/api/v1/tunnel/delete", map[string]interface{}{"id": id}), 0)
+	if deleted.Load() != 1 {
+		t.Fatalf("fresh handler did not recover obsolete listener ownership: %d", deleted.Load())
+	}
+	assertCode(t, post("/api/v1/tunnel/create", payload), 0)
+	post("/api/v1/tunnel/batch-redeploy", map[string]interface{}{"ids": []int64{id}})
+	if deleted.Load() != 1 {
+		t.Fatal("acknowledged cleanup replayed against replacement tunnel")
+	}
+}

go-backend/tests/contract/tunnel_federation_lifecycle_regression_test.go

@@ -0,0 +1,214 @@
+package contract_test
+
+import (
+	"bytes"
+	"encoding/json"
+	"go-backend/internal/auth"
+	"go-backend/internal/store/repo"
+	"net/http"
+	"net/http/httptest"
+	"sync"
+	"testing"
+	"time"
+)
+
+func TestFederationRedeployPreservesExistingBindings(t *testing.T) {
+	testFederationRedeploy(t, false, false)
+}
+func TestFederationFailedRedeployPreservesExistingBindings(t *testing.T) {
+	testFederationRedeploy(t, true, false)
+}
+func TestFederationCreateDoesNotHoldDatabaseDuringAcknowledgment(t *testing.T) {
+	testFederationRedeploy(t, false, true)
+}
+
+func testFederationRedeploy(t *testing.T, failRedeploy, gateCreate bool) {
+	providerSecret := "provider-contract-jwt"
+	providerRouter, providerRepo := setupContractRouter(t, providerSecret)
+	entered, release := make(chan struct{}), make(chan struct{})
+	var gateOnce, releaseOnce sync.Once
+	unblock := func() { releaseOnce.Do(func() { close(release) }) }
+	providerServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if gateCreate && r.URL.Path == "/api/v1/federation/runtime/apply-role" {
+			gateOnce.Do(func() { close(entered); <-release })
+		}
+		providerRouter.ServeHTTP(w, r)
+	}))
+	defer providerServer.Close()
+
+	consumerSecret := "consumer-contract-jwt"
+	consumerRouter, consumerRepo := setupContractRouter(t, consumerSecret)
+
+	consumerAdminToken, err := auth.GenerateToken(1, "consumer-admin", 0, consumerSecret)
+	if err != nil {
+		t.Fatalf("generate consumer admin token: %v", err)
+	}
+
+	now := time.Now().UnixMilli()
+	providerEntryNodeID := insertContractNode(t, providerRepo, "provider-entry", "198.51.100.11", "43000-43010", "provider-entry-secret", 1)
+	providerMiddleNodeID := insertContractNode(t, providerRepo, "provider-middle", "198.51.100.12", "44000-44010", "provider-middle-secret", 1)
+	providerExitNodeID := insertContractNode(t, providerRepo, "provider-exit", "198.51.100.13", "45000-45010", "provider-exit-secret", 1)
+
+	_ = insertPeerShare(t, providerRepo, &repo.PeerShare{
+		Name:           "entry-share",
+		NodeID:         providerEntryNodeID,
+		Token:          "share-entry-token",
+		PortRangeStart: 43000,
+		PortRangeEnd:   43010,
+		IsActive:       1,
+		CreatedTime:    now,
+		UpdatedTime:    now,
+	})
+	_ = insertPeerShare(t, providerRepo, &repo.PeerShare{
+		Name:           "middle-share",
+		NodeID:         providerMiddleNodeID,
+		Token:          "share-middle-token",
+		PortRangeStart: 44000,
+		PortRangeEnd:   44010,
+		IsActive:       1,
+		CreatedTime:    now,
+		UpdatedTime:    now,
+	})
+	_ = insertPeerShare(t, providerRepo, &repo.PeerShare{
+		Name:           "exit-share",
+		NodeID:         providerExitNodeID,
+		Token:          "share-exit-token",
+		PortRangeStart: 45000,
+		PortRangeEnd:   45010,
+		IsActive:       1,
+		CreatedTime:    now,
+		UpdatedTime:    now,
+	})
+
+	importRemoteNodeForContract(t, consumerRouter, consumerAdminToken, providerServer.URL, "share-entry-token")
+	importRemoteNodeForContract(t, consumerRouter, consumerAdminToken, providerServer.URL, "share-middle-token")
+	importRemoteNodeForContract(t, consumerRouter, consumerAdminToken, providerServer.URL, "share-exit-token")
+
+	entryRemoteNodeID := queryRemoteNodeIDByToken(t, consumerRepo, "share-entry-token")
+	middleRemoteNodeID := queryRemoteNodeIDByToken(t, consumerRepo, "share-middle-token")
+	exitRemoteNodeID := queryRemoteNodeIDByToken(t, consumerRepo, "share-exit-token")
+
+	var mu sync.Mutex
+	var destructive []string
+	var armed bool
+	recorder := func(kind string, data json.RawMessage) (bool, string) {
+		mu.Lock()
+		defer mu.Unlock()
+		if kind == "DeleteService" || kind == "DeleteChains" {
+			destructive = append(destructive, kind)
+		}
+		if armed && failRedeploy && kind == "UpdateService" {
+			return true, "simulated node update failure"
+		}
+		return false, ""
+	}
+	stopEntry := startMockNodeSessionWithCommandRecorder(t, providerServer.URL, "provider-entry-secret", recorder)
+	defer stopEntry()
+	stopMiddle := startMockNodeSessionWithCommandRecorder(t, providerServer.URL, "provider-middle-secret", recorder)
+	defer stopMiddle()
+	stopExit := startMockNodeSessionWithCommandRecorder(t, providerServer.URL, "provider-exit-secret", recorder)
+	defer stopExit()
+
+	createTunnel := func(name string) int64 {
+		payload := map[string]interface{}{
+			"name":   name,
+			"type":   2,
+			"flow":   99999,
+			"status": 1,
+			"inNodeId": []map[string]interface{}{
+				{"nodeId": entryRemoteNodeID, "protocol": "tls", "strategy": "round"},
+			},
+			"chainNodes": [][]map[string]interface{}{
+				{{"nodeId": middleRemoteNodeID, "protocol": "tls", "strategy": "round"}},
+			},
+			"outNodeId": []map[string]interface{}{
+				{"nodeId": exitRemoteNodeID, "protocol": "tls", "strategy": "round"},
+			},
+		}
+		body, err := json.Marshal(payload)
+		if err != nil {
+			t.Fatalf("marshal create payload: %v", err)
+		}
+		req := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/create", bytes.NewReader(body))
+		req.Header.Set("Authorization", consumerAdminToken)
+		req.Header.Set("Content-Type", "application/json")
+		res := httptest.NewRecorder()
+		consumerRouter.ServeHTTP(res, req)
+		assertCode(t, res, 0)
+
+		tunnelID := mustQueryInt64(t, consumerRepo, `SELECT id FROM tunnel WHERE name = ? ORDER BY id DESC LIMIT 1`, name)
+		if tunnelID <= 0 {
+			t.Fatalf("invalid tunnel id for %s", name)
+		}
+		return tunnelID
+	}
+
+	defer unblock()
+	var firstTunnelID int64
+	if gateCreate {
+		created := make(chan int64, 1)
+		go func() { created <- createTunnel("dual-panel-middle-exit-1") }()
+		select {
+		case <-entered:
+		case <-time.After(5 * time.Second):
+			t.Fatal("create did not reach federation gate")
+		}
+		listed := make(chan struct{})
+		go func() {
+			defer close(listed)
+			req := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/list", bytes.NewBufferString("{}"))
+			req.Header.Set("Authorization", consumerAdminToken)
+			consumerRouter.ServeHTTP(httptest.NewRecorder(), req)
+		}()
+		select {
+		case <-listed:
+		case <-time.After(300 * time.Millisecond):
+			t.Error("federation create held database while waiting for acknowledgment")
+		}
+		unblock()
+		select {
+		case firstTunnelID = <-created:
+		case <-time.After(5 * time.Second):
+			t.Fatal("create stuck after release")
+		}
+		select {
+		case <-listed:
+		case <-time.After(5 * time.Second):
+			t.Fatal("list stuck after release")
+		}
+		return
+	}
+	firstTunnelID = createTunnel("dual-panel-middle-exit-1")
+
+	mu.Lock()
+	destructive = nil
+	armed = true
+	mu.Unlock()
+	body, _ := json.Marshal(map[string]interface{}{"ids": []int64{firstTunnelID}})
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/batch-redeploy", bytes.NewReader(body))
+	req.Header.Set("Authorization", consumerAdminToken)
+	res := httptest.NewRecorder()
+	consumerRouter.ServeHTTP(res, req)
+	var out struct {
+		Code int `json:"code"`
+		Data struct {
+			SuccessCount int `json:"successCount"`
+			FailCount    int `json:"failCount"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(res.Body.Bytes(), &out); err != nil {
+		t.Fatal(err)
+	}
+	expectedSuccess, expectedFailure := 1, 0
+	if failRedeploy {
+		expectedSuccess, expectedFailure = 0, 1
+	}
+	if out.Code != 0 || out.Data.SuccessCount != expectedSuccess || out.Data.FailCount != expectedFailure {
+		t.Fatalf("redeploy failed: %s", res.Body.String())
+	}
+	mu.Lock()
+	defer mu.Unlock()
+	if len(destructive) > 0 {
+		t.Fatalf("redeploy destroyed existing federation runtime: %v", destructive)
+	}
+}

go-backend/tests/contract/tunnel_insert_middle_hop_investigation_test.go

@@ -0,0 +1,510 @@
+package contract_test
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"go-backend/internal/auth"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+)
+
+func TestTunnelInsertMiddleHopRecordedRuntimeContract(t *testing.T) {
+	secret := "contract-jwt-secret"
+	router, r := setupContractRouter(t, secret)
+	server := httptest.NewServer(router)
+	defer server.Close()
+
+	adminToken, err := auth.GenerateToken(1, "admin_user", 0, secret)
+	if err != nil {
+		t.Fatalf("generate admin token: %v", err)
+	}
+
+	now := time.Now().UnixMilli()
+	if err := r.DB().Exec(`
+		INSERT INTO user(id, user, pwd, role_id, exp_time, flow, in_flow, out_flow, flow_reset_time, num, created_time, updated_time, status)
+		VALUES(2, 'issue281_transition_user', 'pwd', 1, 2727251700000, 99999, 0, 0, 1, 99999, ?, ?, 1)
+	`, now, now).Error; err != nil {
+		t.Fatalf("insert user: %v", err)
+	}
+
+	if err := r.DB().Exec(`
+		INSERT INTO tunnel(name, traffic_ratio, type, protocol, flow, created_time, updated_time, status, in_ip, inx)
+		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, "issue281-transition-tunnel", 1.0, 2, "tls", 99999, now, now, 1, nil, 0).Error; err != nil {
+		t.Fatalf("insert tunnel: %v", err)
+	}
+	tunnelID := mustLastInsertID(t, r, "issue281-transition-tunnel")
+
+	insertNode := func(name, secretValue, ip, portRange string, inx int) int64 {
+		if err := r.DB().Exec(`
+			INSERT INTO node(name, secret, server_ip, server_ip_v4, server_ip_v6, port, interface_name, version, http, tls, socks, created_time, updated_time, status, tcp_listen_addr, udp_listen_addr, inx)
+			VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+		`, name, secretValue, ip, ip, "", portRange, "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", inx).Error; err != nil {
+			t.Fatalf("insert node %s: %v", name, err)
+		}
+		return mustLastInsertID(t, r, name)
+	}
+
+	entryA := insertNode("issue281-transition-entry-a", "issue281-transition-entry-a-secret", "10.52.0.1", "54000-54010", 0)
+	entryB := insertNode("issue281-transition-entry-b", "issue281-transition-entry-b-secret", "10.52.0.2", "54000-54010", 1)
+	entryC := insertNode("issue281-transition-entry-c", "issue281-transition-entry-c-secret", "10.52.0.3", "54000-54010", 2)
+	exitNodeID := insertNode("issue281-transition-exit", "issue281-transition-exit-secret", "10.52.0.4", "57000-57010", 3)
+
+	if err := r.DB().Exec(`
+		INSERT INTO chain_tunnel(tunnel_id, chain_type, node_id, port, strategy, inx, protocol)
+		VALUES(?, 1, ?, 54001, 'round', 1, 'tls')
+	`, tunnelID, entryA).Error; err != nil {
+		t.Fatalf("insert initial entry chain_tunnel: %v", err)
+	}
+	if err := r.DB().Exec(`
+		INSERT INTO chain_tunnel(tunnel_id, chain_type, node_id, port, strategy, inx, protocol)
+		VALUES(?, 3, ?, 57001, 'round', 1, 'tls')
+	`, tunnelID, exitNodeID).Error; err != nil {
+		t.Fatalf("insert exit chain_tunnel: %v", err)
+	}
+
+	if err := r.DB().Exec(`
+		INSERT INTO user_tunnel(id, user_id, tunnel_id, speed_id, num, flow, in_flow, out_flow, flow_reset_time, exp_time, status)
+		VALUES(282, 2, ?, NULL, 999, 99999, 0, 0, 1, 2727251700000, 1)
+	`, tunnelID).Error; err != nil {
+		t.Fatalf("insert user_tunnel: %v", err)
+	}
+
+	if err := r.DB().Exec(`
+		INSERT INTO forward(user_id, user_name, name, tunnel_id, remote_addr, strategy, in_flow, out_flow, created_time, updated_time, status, inx)
+		VALUES(2, 'issue281_transition_user', 'issue281-transition-forward', ?, '1.1.1.1:443', 'fifo', 0, 0, ?, ?, 1, 0)
+	`, tunnelID, now, now).Error; err != nil {
+		t.Fatalf("insert forward: %v", err)
+	}
+	forwardID := mustLastInsertID(t, r, "issue281-transition-forward")
+
+	if err := r.DB().Exec(`INSERT INTO forward_port(forward_id, node_id, port) VALUES(?, ?, ?)`, forwardID, entryA, 54001).Error; err != nil {
+		t.Fatalf("insert forward_port: %v", err)
+	}
+
+	// This mock records control-plane commands only; it does not forward traffic.
+	type command struct {
+		node, kind string
+		data       json.RawMessage
+	}
+	var mu sync.Mutex
+	var commands []command
+	for _, n := range []struct {
+		name, secret string
+		id           int64
+	}{
+		{"A", "issue281-transition-entry-a-secret", entryA},
+		{"B", "issue281-transition-entry-b-secret", entryB},
+		{"C", "issue281-transition-entry-c-secret", entryC},
+		{"D", "issue281-transition-exit-secret", exitNodeID},
+	} {
+		name := n.name
+		stop := startMockNodeSessionWithCommandRecorder(t, server.URL, n.secret, func(kind string, data json.RawMessage) (bool, string) {
+			mu.Lock()
+			defer mu.Unlock()
+			commands = append(commands, command{name, kind, append(json.RawMessage(nil), data...)})
+			return false, ""
+		})
+		defer stop()
+		waitNodeStatus(t, r, n.id, 1)
+	}
+	// Let initial mock-node reconnect reconciliation finish before the topology edit.
+	time.Sleep(time.Second)
+	node := func(id int64) map[string]interface{} {
+		return map[string]interface{}{"nodeId": id, "protocol": "tls", "strategy": "round"}
+	}
+	update := func(hops [][]map[string]interface{}) {
+		mu.Lock()
+		commands = nil
+		mu.Unlock()
+		payload := map[string]interface{}{"id": tunnelID, "name": "issue281-transition-tunnel", "type": 2, "flow": 99999, "trafficRatio": 1.0, "status": 1,
+			"inNodeId": []map[string]interface{}{node(entryA)}, "chainNodes": hops,
+			"outNodeId": []map[string]interface{}{{"nodeId": exitNodeID, "protocol": "tls", "strategy": "round", "port": 57001}}}
+		raw, _ := json.Marshal(payload)
+		req := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/update", bytes.NewReader(raw))
+		req.Header.Set("Authorization", adminToken)
+		req.Header.Set("Content-Type", "application/json")
+		res := httptest.NewRecorder()
+		router.ServeHTTP(res, req)
+		assertCode(t, res, 0)
+	}
+	check := func(edges map[string]int64) {
+		mu.Lock()
+		defer mu.Unlock()
+		expectedChain := fmt.Sprintf("chains_%d", tunnelID)
+		got := map[string]bool{}
+		services := map[string]bool{}
+		lastChains := map[string]int{}
+		lastServices := map[string]int{}
+		for i, c := range commands {
+			if c.kind == "UpdateChains" || c.kind == "AddChains" {
+				lastChains[c.node] = i
+			}
+			if c.kind == "UpdateService" || c.kind == "AddService" {
+				lastServices[c.node] = i
+			}
+		}
+		for i, c := range commands {
+			if c.kind == "DeleteChains" {
+				t.Fatalf("unexpected chain deletion on %s: %s", c.node, c.data)
+			}
+			if c.kind == "UpdateChains" || c.kind == "AddChains" {
+				if lastChains[c.node] != i {
+					continue
+				}
+				var raw map[string]interface{}
+				if err := json.Unmarshal(c.data, &raw); err != nil {
+					t.Fatal(err)
+				}
+				if nested, ok := raw["data"].(map[string]interface{}); ok {
+					raw = nested
+				}
+				target, ok := edges[c.node]
+				if !ok {
+					t.Fatalf("unexpected chain owner %s", c.node)
+				}
+				port := mustQueryInt(t, r, `SELECT port FROM chain_tunnel WHERE tunnel_id = ? AND node_id = ? LIMIT 1`, tunnelID, target)
+				ip := map[int64]string{entryB: "10.52.0.2", entryC: "10.52.0.3", exitNodeID: "10.52.0.4"}[target]
+				hops := raw["hops"].([]interface{})
+				nodes := hops[0].(map[string]interface{})["nodes"].([]interface{})
+				addr := nodes[0].(map[string]interface{})["addr"]
+				if len(hops) != 1 || len(nodes) != 1 || addr != fmt.Sprintf("%s:%d", ip, port) {
+					t.Fatalf("bad edge %s: %s", c.node, c.data)
+				}
+				got[c.node] = true
+				t.Logf("%s -> %s via %s", c.node, ip, addr)
+			}
+			if strings.EqualFold(c.kind, "UpdateService") || strings.EqualFold(c.kind, "AddService") {
+				if lastServices[c.node] != i {
+					continue
+				}
+				var ss []map[string]interface{}
+				if err := json.Unmarshal(c.data, &ss); err != nil {
+					t.Fatal(err)
+				}
+				for _, s := range ss {
+					if s["name"] != fmt.Sprintf("tunnel_%d", tunnelID) {
+						continue
+					}
+					h := s["handler"].(map[string]interface{})
+					if c.node == "B" || c.node == "C" {
+						if h["chain"] != expectedChain {
+							t.Fatalf("missing chain on %s: %s", c.node, c.data)
+						}
+					}
+					if c.node == "D" && h["chain"] != nil {
+						t.Fatalf("exit has unexpected chain")
+					}
+					services[c.node] = true
+				}
+			}
+		}
+		for owner := range edges {
+			if !got[owner] {
+				t.Errorf("no chain update for %s", owner)
+			}
+			if owner != "A" && !services[owner] {
+				t.Errorf("no relay service for %s", owner)
+			}
+		}
+		if !services["D"] {
+			t.Error("no exit relay service")
+		}
+	}
+	update([][]map[string]interface{}{{node(entryB)}})
+	check(map[string]int64{"A": entryB, "B": exitNodeID})
+	update([][]map[string]interface{}{{node(entryB)}, {node(entryC)}})
+	check(map[string]int64{"A": entryB, "B": entryC, "C": exitNodeID})
+	// A remains the entry and the user's forward remains bound there.
+	after, _ := mustQueryInt64Int(t, r, `SELECT node_id,port FROM forward_port WHERE forward_id = ? LIMIT 1`, forwardID)
+	if after != entryA {
+		t.Fatalf("forward entry changed: %d", after)
+	}
+}
+
+func TestTunnelRedeployEditMissingChainWindowInvestigation(t *testing.T) {
+	t.Skip("Pre-repair characterization; preserved in plans/evidence/070-tunnel-insert-middle-hop-investigation.go.txt. Replaced by TestTunnelRedeployPreservesLiveRoutes and TestTunnelEditWaitsForRedeploy.")
+	secret := "contract-jwt-secret"
+	router, r := setupContractRouter(t, secret)
+	server := httptest.NewServer(router)
+	defer server.Close()
+
+	adminToken, err := auth.GenerateToken(1, "admin_user", 0, secret)
+	if err != nil {
+		t.Fatalf("generate admin token: %v", err)
+	}
+
+	now := time.Now().UnixMilli()
+	if err := r.DB().Exec(`
+		INSERT INTO user(id, user, pwd, role_id, exp_time, flow, in_flow, out_flow, flow_reset_time, num, created_time, updated_time, status)
+		VALUES(2, 'issue281_transition_user', 'pwd', 1, 2727251700000, 99999, 0, 0, 1, 99999, ?, ?, 1)
+	`, now, now).Error; err != nil {
+		t.Fatalf("insert user: %v", err)
+	}
+
+	if err := r.DB().Exec(`
+		INSERT INTO tunnel(name, traffic_ratio, type, protocol, flow, created_time, updated_time, status, in_ip, inx)
+		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, "issue281-transition-tunnel", 1.0, 2, "tls", 99999, now, now, 1, nil, 0).Error; err != nil {
+		t.Fatalf("insert tunnel: %v", err)
+	}
+	tunnelID := mustLastInsertID(t, r, "issue281-transition-tunnel")
+
+	insertNode := func(name, secretValue, ip, portRange string, inx int) int64 {
+		if err := r.DB().Exec(`
+			INSERT INTO node(name, secret, server_ip, server_ip_v4, server_ip_v6, port, interface_name, version, http, tls, socks, created_time, updated_time, status, tcp_listen_addr, udp_listen_addr, inx)
+			VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+		`, name, secretValue, ip, ip, "", portRange, "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", inx).Error; err != nil {
+			t.Fatalf("insert node %s: %v", name, err)
+		}
+		return mustLastInsertID(t, r, name)
+	}
+
+	entryA := insertNode("issue281-transition-entry-a", "issue281-transition-entry-a-secret", "10.52.0.1", "54000-54010", 0)
+	entryB := insertNode("issue281-transition-entry-b", "issue281-transition-entry-b-secret", "10.52.0.2", "54000-54010", 1)
+	entryC := insertNode("issue281-transition-entry-c", "issue281-transition-entry-c-secret", "10.52.0.3", "54000-54010", 2)
+	exitNodeID := insertNode("issue281-transition-exit", "issue281-transition-exit-secret", "10.52.0.4", "57000-57010", 3)
+
+	if err := r.DB().Exec(`
+		INSERT INTO chain_tunnel(tunnel_id, chain_type, node_id, port, strategy, inx, protocol)
+		VALUES(?, 1, ?, 54001, 'round', 1, 'tls')
+	`, tunnelID, entryA).Error; err != nil {
+		t.Fatalf("insert initial entry chain_tunnel: %v", err)
+	}
+	if err := r.DB().Exec(`
+		INSERT INTO chain_tunnel(tunnel_id, chain_type, node_id, port, strategy, inx, protocol)
+		VALUES(?, 3, ?, 57001, 'round', 1, 'tls')
+	`, tunnelID, exitNodeID).Error; err != nil {
+		t.Fatalf("insert exit chain_tunnel: %v", err)
+	}
+
+	if err := r.DB().Exec(`
+		INSERT INTO user_tunnel(id, user_id, tunnel_id, speed_id, num, flow, in_flow, out_flow, flow_reset_time, exp_time, status)
+		VALUES(282, 2, ?, NULL, 999, 99999, 0, 0, 1, 2727251700000, 1)
+	`, tunnelID).Error; err != nil {
+		t.Fatalf("insert user_tunnel: %v", err)
+	}
+
+	if err := r.DB().Exec(`
+		INSERT INTO forward(user_id, user_name, name, tunnel_id, remote_addr, strategy, in_flow, out_flow, created_time, updated_time, status, inx)
+		VALUES(2, 'issue281_transition_user', 'issue281-transition-forward', ?, '1.1.1.1:443', 'fifo', 0, 0, ?, ?, 1, 0)
+	`, tunnelID, now, now).Error; err != nil {
+		t.Fatalf("insert forward: %v", err)
+	}
+	forwardID := mustLastInsertID(t, r, "issue281-transition-forward")
+
+	if err := r.DB().Exec(`INSERT INTO forward_port(forward_id, node_id, port) VALUES(?, ?, ?)`, forwardID, entryA, 54001).Error; err != nil {
+		t.Fatalf("insert forward_port: %v", err)
+	}
+
+	// This mock records control-plane commands only; it does not forward traffic.
+	type command struct {
+		node, kind string
+		data       json.RawMessage
+	}
+	var mu sync.Mutex
+	var commands []command
+	armed := false
+	chainPresent, servicePresent := map[string]bool{}, map[string]bool{}
+	atDeleteService, releaseDeleteService, editReachedA := make(chan struct{}), make(chan struct{}), make(chan struct{}, 1)
+	var gateOnce, releaseOnce sync.Once
+	release := func() { releaseOnce.Do(func() { close(releaseDeleteService) }) }
+	defer release()
+
+	for _, n := range []struct {
+		name, secret string
+		id           int64
+	}{
+		{"A", "issue281-transition-entry-a-secret", entryA},
+		{"B", "issue281-transition-entry-b-secret", entryB},
+		{"C", "issue281-transition-entry-c-secret", entryC},
+		{"D", "issue281-transition-exit-secret", exitNodeID},
+	} {
+		name := n.name
+		stop := startMockNodeSessionWithCommandRecorder(t, server.URL, n.secret, func(kind string, data json.RawMessage) (bool, string) {
+			mu.Lock()
+			active := armed
+			shouldGate := active && name == "B" && kind == "DeleteService"
+			if active && name == "A" && kind == "UpdateChains" {
+				select {
+				case editReachedA <- struct{}{}:
+				default:
+				}
+			}
+			mu.Unlock()
+			if shouldGate {
+				gateOnce.Do(func() { close(atDeleteService); <-releaseDeleteService })
+			}
+			mu.Lock()
+			defer mu.Unlock()
+			if kind == "DeleteChains" {
+				chainPresent[name] = false
+			}
+			if kind == "AddChains" || kind == "UpdateChains" {
+				chainPresent[name] = true
+			}
+			if kind == "DeleteService" {
+				servicePresent[name] = false
+			}
+			if kind == "AddService" || kind == "UpdateService" {
+				servicePresent[name] = true
+			}
+			commands = append(commands, command{name, kind, append(json.RawMessage(nil), data...)})
+			return false, ""
+		})
+		defer stop()
+		waitNodeStatus(t, r, n.id, 1)
+	}
+	// Let initial mock-node reconnect reconciliation finish before the topology edit.
+	time.Sleep(time.Second)
+	node := func(id int64) map[string]interface{} {
+		return map[string]interface{}{"nodeId": id, "protocol": "tls", "strategy": "round"}
+	}
+	update := func(hops [][]map[string]interface{}) {
+		mu.Lock()
+		commands = nil
+		mu.Unlock()
+		payload := map[string]interface{}{"id": tunnelID, "name": "issue281-transition-tunnel", "type": 2, "flow": 99999, "trafficRatio": 1.0, "status": 1,
+			"inNodeId": []map[string]interface{}{node(entryA)}, "chainNodes": hops,
+			"outNodeId": []map[string]interface{}{{"nodeId": exitNodeID, "protocol": "tls", "strategy": "round", "port": 57001}}}
+		raw, _ := json.Marshal(payload)
+		req := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/update", bytes.NewReader(raw))
+		req.Header.Set("Authorization", adminToken)
+		req.Header.Set("Content-Type", "application/json")
+		res := httptest.NewRecorder()
+		router.ServeHTTP(res, req)
+		assertCode(t, res, 0)
+	}
+	check := func(edges map[string]int64) {
+		mu.Lock()
+		defer mu.Unlock()
+		expectedChain := fmt.Sprintf("chains_%d", tunnelID)
+		got := map[string]bool{}
+		services := map[string]bool{}
+		lastChains := map[string]int{}
+		lastServices := map[string]int{}
+		for i, c := range commands {
+			if c.kind == "UpdateChains" || c.kind == "AddChains" {
+				lastChains[c.node] = i
+			}
+			if c.kind == "UpdateService" || c.kind == "AddService" {
+				lastServices[c.node] = i
+			}
+		}
+		for i, c := range commands {
+			if c.kind == "DeleteChains" {
+				t.Fatalf("unexpected chain deletion on %s: %s", c.node, c.data)
+			}
+			if c.kind == "UpdateChains" || c.kind == "AddChains" {
+				if lastChains[c.node] != i {
+					continue
+				}
+				var raw map[string]interface{}
+				if err := json.Unmarshal(c.data, &raw); err != nil {
+					t.Fatal(err)
+				}
+				if nested, ok := raw["data"].(map[string]interface{}); ok {
+					raw = nested
+				}
+				target, ok := edges[c.node]
+				if !ok {
+					t.Fatalf("unexpected chain owner %s", c.node)
+				}
+				port := mustQueryInt(t, r, `SELECT port FROM chain_tunnel WHERE tunnel_id = ? AND node_id = ? LIMIT 1`, tunnelID, target)
+				ip := map[int64]string{entryB: "10.52.0.2", entryC: "10.52.0.3", exitNodeID: "10.52.0.4"}[target]
+				hops := raw["hops"].([]interface{})
+				nodes := hops[0].(map[string]interface{})["nodes"].([]interface{})
+				addr := nodes[0].(map[string]interface{})["addr"]
+				if len(hops) != 1 || len(nodes) != 1 || addr != fmt.Sprintf("%s:%d", ip, port) {
+					t.Fatalf("bad edge %s: %s", c.node, c.data)
+				}
+				got[c.node] = true
+				t.Logf("%s -> %s via %s", c.node, ip, addr)
+			}
+			if strings.EqualFold(c.kind, "UpdateService") || strings.EqualFold(c.kind, "AddService") {
+				if lastServices[c.node] != i {
+					continue
+				}
+				var ss []map[string]interface{}
+				if err := json.Unmarshal(c.data, &ss); err != nil {
+					t.Fatal(err)
+				}
+				for _, s := range ss {
+					if s["name"] != fmt.Sprintf("tunnel_%d", tunnelID) {
+						continue
+					}
+					h := s["handler"].(map[string]interface{})
+					if c.node == "B" || c.node == "C" {
+						if h["chain"] != expectedChain {
+							t.Fatalf("missing chain on %s: %s", c.node, c.data)
+						}
+					}
+					if c.node == "D" && h["chain"] != nil {
+						t.Fatalf("exit has unexpected chain")
+					}
+					services[c.node] = true
+				}
+			}
+		}
+		for owner := range edges {
+			if !got[owner] {
+				t.Errorf("no chain update for %s", owner)
+			}
+			if owner != "A" && !services[owner] {
+				t.Errorf("no relay service for %s", owner)
+			}
+		}
+		if !services["D"] {
+			t.Error("no exit relay service")
+		}
+	}
+	update([][]map[string]interface{}{{node(entryB)}})
+	check(map[string]int64{"A": entryB, "B": exitNodeID})
+
+	mu.Lock()
+	armed = true
+	mu.Unlock()
+	redeployDone := make(chan struct{})
+	go func() {
+		defer close(redeployDone)
+		raw, _ := json.Marshal(map[string]interface{}{"ids": []int64{tunnelID}})
+		req := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/batch-redeploy", bytes.NewReader(raw))
+		req.Header.Set("Authorization", adminToken)
+		req.Header.Set("Content-Type", "application/json")
+		res := httptest.NewRecorder()
+		router.ServeHTTP(res, req)
+		t.Logf("redeploy response: %s", res.Body.String())
+	}()
+	await := func(ch <-chan struct{}, label string) {
+		t.Helper()
+		select {
+		case <-ch:
+		case <-time.After(10 * time.Second):
+			release()
+			t.Fatalf("timeout waiting for %s", label)
+		}
+	}
+	await(atDeleteService, "B DeleteService gate")
+	editDone := make(chan struct{})
+	go func() { defer close(editDone); update([][]map[string]interface{}{{node(entryB)}, {node(entryC)}}) }()
+	await(editReachedA, "edit UpdateChains on A")
+	mu.Lock()
+	missing, live := !chainPresent["B"], servicePresent["B"]
+	mu.Unlock()
+	if !missing || !live {
+		release()
+		t.Fatalf("expected B live service with missing chain during overlap, missing=%v live=%v", missing, live)
+	}
+	t.Log("Deterministic overlap confirmed: edit reached A while redeploy had deleted B chain but had not deleted B relay service")
+	release()
+	await(editDone, "edit completion")
+	await(redeployDone, "redeploy completion")
+	mu.Lock()
+	defer mu.Unlock()
+	t.Logf("final mock runtime chain presence: A=%v B=%v C=%v; services B=%v C=%v D=%v", chainPresent["A"], chainPresent["B"], chainPresent["C"], servicePresent["B"], servicePresent["C"], servicePresent["D"])
+}

go-backend/tests/contract/tunnel_lifecycle_regression_test.go

@@ -0,0 +1,363 @@
+package contract_test
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"go-backend/internal/auth"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+)
+
+func TestTunnelRedeployPreservesLiveRoutes(t *testing.T) {
+	testTunnelLifecycle(t, false, false, false)
+}
+
+func TestTunnelEditWaitsForRedeploy(t *testing.T) {
+	testTunnelLifecycle(t, true, false, false)
+}
+
+func TestTunnelFailedRedeployPreservesLiveRoutes(t *testing.T) {
+	testTunnelLifecycle(t, false, true, false)
+}
+
+func TestTunnelDeleteWaitsForRedeploy(t *testing.T) { testTunnelLifecycle(t, true, false, true) }
+
+func testTunnelLifecycle(t *testing.T, concurrentEdit, failRedeploy, concurrentDelete bool) {
+	secret := "contract-jwt-secret"
+	router, r := setupContractRouter(t, secret)
+	server := httptest.NewServer(router)
+	defer server.Close()
+
+	adminToken, err := auth.GenerateToken(1, "admin_user", 0, secret)
+	if err != nil {
+		t.Fatalf("generate admin token: %v", err)
+	}
+
+	now := time.Now().UnixMilli()
+	if err := r.DB().Exec(`
+		INSERT INTO user(id, user, pwd, role_id, exp_time, flow, in_flow, out_flow, flow_reset_time, num, created_time, updated_time, status)
+		VALUES(2, 'issue281_transition_user', 'pwd', 1, 2727251700000, 99999, 0, 0, 1, 99999, ?, ?, 1)
+	`, now, now).Error; err != nil {
+		t.Fatalf("insert user: %v", err)
+	}
+
+	if err := r.DB().Exec(`
+		INSERT INTO tunnel(name, traffic_ratio, type, protocol, flow, created_time, updated_time, status, in_ip, inx)
+		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, "issue281-transition-tunnel", 1.0, 2, "tls", 99999, now, now, 1, nil, 0).Error; err != nil {
+		t.Fatalf("insert tunnel: %v", err)
+	}
+	tunnelID := mustLastInsertID(t, r, "issue281-transition-tunnel")
+
+	insertNode := func(name, secretValue, ip, portRange string, inx int) int64 {
+		if err := r.DB().Exec(`
+			INSERT INTO node(name, secret, server_ip, server_ip_v4, server_ip_v6, port, interface_name, version, http, tls, socks, created_time, updated_time, status, tcp_listen_addr, udp_listen_addr, inx)
+			VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+		`, name, secretValue, ip, ip, "", portRange, "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", inx).Error; err != nil {
+			t.Fatalf("insert node %s: %v", name, err)
+		}
+		return mustLastInsertID(t, r, name)
+	}
+
+	entryA := insertNode("issue281-transition-entry-a", "issue281-transition-entry-a-secret", "10.52.0.1", "54000-54010", 0)
+	entryB := insertNode("issue281-transition-entry-b", "issue281-transition-entry-b-secret", "10.52.0.2", "54000-54010", 1)
+	entryC := insertNode("issue281-transition-entry-c", "issue281-transition-entry-c-secret", "10.52.0.3", "54000-54010", 2)
+	exitNodeID := insertNode("issue281-transition-exit", "issue281-transition-exit-secret", "10.52.0.4", "57000-57010", 3)
+
+	if err := r.DB().Exec(`
+		INSERT INTO chain_tunnel(tunnel_id, chain_type, node_id, port, strategy, inx, protocol)
+		VALUES(?, 1, ?, 54001, 'round', 1, 'tls')
+	`, tunnelID, entryA).Error; err != nil {
+		t.Fatalf("insert initial entry chain_tunnel: %v", err)
+	}
+	if err := r.DB().Exec(`
+		INSERT INTO chain_tunnel(tunnel_id, chain_type, node_id, port, strategy, inx, protocol)
+		VALUES(?, 3, ?, 57001, 'round', 1, 'tls')
+	`, tunnelID, exitNodeID).Error; err != nil {
+		t.Fatalf("insert exit chain_tunnel: %v", err)
+	}
+
+	if err := r.DB().Exec(`
+		INSERT INTO user_tunnel(id, user_id, tunnel_id, speed_id, num, flow, in_flow, out_flow, flow_reset_time, exp_time, status)
+		VALUES(282, 2, ?, NULL, 999, 99999, 0, 0, 1, 2727251700000, 1)
+	`, tunnelID).Error; err != nil {
+		t.Fatalf("insert user_tunnel: %v", err)
+	}
+
+	if err := r.DB().Exec(`
+		INSERT INTO forward(user_id, user_name, name, tunnel_id, remote_addr, strategy, in_flow, out_flow, created_time, updated_time, status, inx)
+		VALUES(2, 'issue281_transition_user', 'issue281-transition-forward', ?, '1.1.1.1:443', 'fifo', 0, 0, ?, ?, 1, 0)
+	`, tunnelID, now, now).Error; err != nil {
+		t.Fatalf("insert forward: %v", err)
+	}
+	forwardID := mustLastInsertID(t, r, "issue281-transition-forward")
+
+	if err := r.DB().Exec(`INSERT INTO forward_port(forward_id, node_id, port) VALUES(?, ?, ?)`, forwardID, entryA, 54001).Error; err != nil {
+		t.Fatalf("insert forward_port: %v", err)
+	}
+
+	// This mock records control-plane commands only; it does not forward traffic.
+	type command struct {
+		node, kind string
+		data       json.RawMessage
+	}
+	var mu sync.Mutex
+	var commands []command
+	var armed, gateClaimed bool
+	entered := make(chan struct{})
+	release := make(chan struct{})
+	var gateOnce, releaseOnce sync.Once
+	unblock := func() { releaseOnce.Do(func() { close(release) }) }
+	defer unblock()
+	editApplied := make(chan struct{}, 1)
+
+	for _, n := range []struct {
+		name, secret string
+		id           int64
+	}{
+		{"A", "issue281-transition-entry-a-secret", entryA},
+		{"B", "issue281-transition-entry-b-secret", entryB},
+		{"C", "issue281-transition-entry-c-secret", entryC},
+		{"D", "issue281-transition-exit-secret", exitNodeID},
+	} {
+		name := n.name
+		stop := startMockNodeSessionWithCommandRecorder(t, server.URL, n.secret, func(kind string, data json.RawMessage) (bool, string) {
+			mu.Lock()
+			gate := armed && !gateClaimed && name == "D" && kind == "UpdateService"
+			if gate {
+				gateClaimed = true
+			}
+			if armed && ((name == "C" && (kind == "UpdateChains" || kind == "AddChains")) || (concurrentDelete && kind == "DeleteChains")) {
+				select {
+				case editApplied <- struct{}{}:
+				default:
+				}
+			}
+			mu.Unlock()
+			if gate {
+				gateOnce.Do(func() { close(entered); <-release })
+			}
+			mu.Lock()
+			defer mu.Unlock()
+			commands = append(commands, command{name, kind, append(json.RawMessage(nil), data...)})
+			if armed && failRedeploy && name == "B" && kind == "UpdateService" {
+				return true, "bind: address already in use"
+			}
+			return false, ""
+		})
+		defer stop()
+		waitNodeStatus(t, r, n.id, 1)
+	}
+	// Let initial mock-node reconnect reconciliation finish before the topology edit.
+	time.Sleep(time.Second)
+	node := func(id int64) map[string]interface{} {
+		return map[string]interface{}{"nodeId": id, "protocol": "tls", "strategy": "round", "port": 54002}
+	}
+	update := func(hops [][]map[string]interface{}) {
+		mu.Lock()
+		commands = nil
+		mu.Unlock()
+		payload := map[string]interface{}{"id": tunnelID, "name": "issue281-transition-tunnel", "type": 2, "flow": 99999, "trafficRatio": 1.0, "status": 1,
+			"inNodeId": []map[string]interface{}{node(entryA)}, "chainNodes": hops,
+			"outNodeId": []map[string]interface{}{{"nodeId": exitNodeID, "protocol": "tls", "strategy": "round", "port": 57001}}}
+		raw, _ := json.Marshal(payload)
+		req := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/update", bytes.NewReader(raw))
+		req.Header.Set("Authorization", adminToken)
+		req.Header.Set("Content-Type", "application/json")
+		res := httptest.NewRecorder()
+		router.ServeHTTP(res, req)
+		assertCode(t, res, 0)
+	}
+	check := func(edges map[string]int64) {
+		mu.Lock()
+		defer mu.Unlock()
+		expectedChain := fmt.Sprintf("chains_%d", tunnelID)
+		got := map[string]bool{}
+		services := map[string]bool{}
+		lastChains := map[string]int{}
+		lastServices := map[string]int{}
+		for i, c := range commands {
+			if c.kind == "UpdateChains" || c.kind == "AddChains" {
+				lastChains[c.node] = i
+			}
+			if c.kind == "UpdateService" || c.kind == "AddService" {
+				lastServices[c.node] = i
+			}
+		}
+		for i, c := range commands {
+			if c.kind == "DeleteChains" {
+				t.Fatalf("unexpected chain deletion on %s: %s", c.node, c.data)
+			}
+			if c.kind == "UpdateChains" || c.kind == "AddChains" {
+				if lastChains[c.node] != i {
+					continue
+				}
+				var raw map[string]interface{}
+				if err := json.Unmarshal(c.data, &raw); err != nil {
+					t.Fatal(err)
+				}
+				if nested, ok := raw["data"].(map[string]interface{}); ok {
+					raw = nested
+				}
+				target, ok := edges[c.node]
+				if !ok {
+					t.Fatalf("unexpected chain owner %s", c.node)
+				}
+				port := 54002
+				if target == exitNodeID {
+					port = 57001
+				}
+				ip := map[int64]string{entryB: "10.52.0.2", entryC: "10.52.0.3", exitNodeID: "10.52.0.4"}[target]
+				hops := raw["hops"].([]interface{})
+				nodes := hops[0].(map[string]interface{})["nodes"].([]interface{})
+				addr := nodes[0].(map[string]interface{})["addr"]
+				if len(hops) != 1 || len(nodes) != 1 || addr != fmt.Sprintf("%s:%d", ip, port) {
+					t.Fatalf("bad edge %s: %s", c.node, c.data)
+				}
+				got[c.node] = true
+				t.Logf("%s -> %s via %s", c.node, ip, addr)
+			}
+			if strings.EqualFold(c.kind, "UpdateService") || strings.EqualFold(c.kind, "AddService") {
+				if lastServices[c.node] != i {
+					continue
+				}
+				var ss []map[string]interface{}
+				if err := json.Unmarshal(c.data, &ss); err != nil {
+					t.Fatal(err)
+				}
+				for _, s := range ss {
+					if s["name"] != fmt.Sprintf("tunnel_%d", tunnelID) {
+						continue
+					}
+					h := s["handler"].(map[string]interface{})
+					if c.node == "B" || c.node == "C" {
+						if h["chain"] != expectedChain {
+							t.Fatalf("missing chain on %s: %s", c.node, c.data)
+						}
+					}
+					if c.node == "D" && h["chain"] != nil {
+						t.Fatalf("exit has unexpected chain")
+					}
+					services[c.node] = true
+				}
+			}
+		}
+		for owner := range edges {
+			if !got[owner] {
+				t.Errorf("no chain update for %s", owner)
+			}
+			if owner != "A" && !services[owner] {
+				t.Errorf("no relay service for %s", owner)
+			}
+		}
+		if !services["D"] {
+			t.Error("no exit relay service")
+		}
+	}
+	update([][]map[string]interface{}{{node(entryB)}})
+	check(map[string]int64{"A": entryB, "B": exitNodeID})
+	mu.Lock()
+	commands = nil
+	mu.Unlock()
+	raw, _ := json.Marshal(map[string]interface{}{"ids": []int64{tunnelID}})
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/batch-redeploy", bytes.NewReader(raw))
+	req.Header.Set("Authorization", adminToken)
+	res := httptest.NewRecorder()
+	if !concurrentEdit {
+		mu.Lock()
+		armed = failRedeploy
+		mu.Unlock()
+		router.ServeHTTP(res, req)
+		if failRedeploy {
+			var out struct {
+				Data struct {
+					FailCount    int `json:"failCount"`
+					SuccessCount int `json:"successCount"`
+				} `json:"data"`
+			}
+			if err := json.Unmarshal(res.Body.Bytes(), &out); err != nil {
+				t.Fatal(err)
+			}
+			if out.Data.FailCount != 1 || out.Data.SuccessCount != 0 {
+				t.Fatalf("expected redeploy failure: %s", res.Body.String())
+			}
+			mu.Lock()
+			defer mu.Unlock()
+			for _, c := range commands {
+				if c.kind == "DeleteService" || c.kind == "DeleteChains" {
+					t.Errorf("failed redeploy removed existing runtime: %s on %s", c.kind, c.node)
+				}
+			}
+		} else {
+			assertCode(t, res, 0)
+			check(map[string]int64{"A": entryB, "B": exitNodeID})
+		}
+		return
+	}
+	mu.Lock()
+	armed = true
+	mu.Unlock()
+	redeployDone := make(chan struct{})
+	go func() { defer close(redeployDone); router.ServeHTTP(res, req) }()
+	select {
+	case <-entered:
+	case <-time.After(5 * time.Second):
+		t.Fatal("redeploy did not reach command gate")
+	}
+	editDone := make(chan struct{})
+	go func() {
+		defer close(editDone)
+		if concurrentDelete {
+			body, _ := json.Marshal(map[string]interface{}{"id": tunnelID})
+			req := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/delete", bytes.NewReader(body))
+			req.Header.Set("Authorization", adminToken)
+			res := httptest.NewRecorder()
+			router.ServeHTTP(res, req)
+			assertCode(t, res, 0)
+		} else {
+			update([][]map[string]interface{}{{node(entryB)}, {node(entryC)}})
+		}
+	}()
+	select {
+	case <-editApplied:
+		t.Error("concurrent mutation changed runtime before redeploy finished")
+	case <-time.After(150 * time.Millisecond):
+	}
+	unblock()
+	for _, done := range []chan struct{}{redeployDone, editDone} {
+		select {
+		case <-done:
+		case <-time.After(5 * time.Second):
+			t.Fatal("lifecycle operation did not complete")
+		}
+	}
+	assertCode(t, res, 0)
+	if !concurrentDelete {
+		mu.Lock()
+		defer mu.Unlock()
+		latest := map[string]string{}
+		for _, c := range commands {
+			if c.kind != "UpdateChains" && c.kind != "AddChains" {
+				continue
+			}
+			var raw map[string]interface{}
+			if err := json.Unmarshal(c.data, &raw); err != nil {
+				t.Fatal(err)
+			}
+			if nested, ok := raw["data"].(map[string]interface{}); ok {
+				raw = nested
+			}
+			hops := raw["hops"].([]interface{})
+			nodes := hops[0].(map[string]interface{})["nodes"].([]interface{})
+			latest[c.node] = nodes[0].(map[string]interface{})["addr"].(string)
+		}
+		if latest["B"] != "10.52.0.3:54002" {
+			t.Fatalf("stale redeploy overwrote edit: B targets %s", latest["B"])
+		}
+	}
+}

go-backend/tests/contract/tunnel_metrics_ingestion_contract_test.go

@@ -58,6 +58,9 @@ func TestFlowUploadInsertsTunnelMetrics(t *testing.T) {
 	if err := repo.DB().Create(forward).Error; err != nil {
 		t.Fatalf("seed forward: %v", err)
 	}
+	if err := repo.DB().Create(&model.ForwardPort{ForwardID: forward.ID, NodeID: node.ID, Port: 10000}).Error; err != nil {
+		t.Fatalf("seed forward node ownership: %v", err)
+	}
 
 	serviceName := jsonNumber(forward.ID) + "_123_0"
 	body, _ := json.Marshal([]map[string]interface{}{{

go-backend/tests/contract/tunnel_role_transition_test.go

@@ -0,0 +1,117 @@
+package contract_test
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"go-backend/internal/auth"
+	"net/http"
+	"net/http/httptest"
+	"sync"
+	"testing"
+)
+
+func TestMiddleToExitKeepsChainUntilReceiverReplacementAcknowledged(t *testing.T) {
+	for _, port := range []int{42000, 42001} {
+		for _, failure := range []string{"等待节点响应超时", "replacement rejected"} {
+			t.Run(fmt.Sprintf("port=%d/failure=%s", port, failure), func(t *testing.T) {
+				router, r := setupContractRouter(t, "role-transition")
+				server := httptest.NewServer(router)
+				defer server.Close()
+				token, err := auth.GenerateToken(1, "admin", 0, "role-transition")
+				if err != nil {
+					t.Fatal(err)
+				}
+				entry := insertContractNode(t, r, "role-entry", "192.0.2.10", "41000-41010", "role-entry-secret", 1)
+				middle := insertContractNode(t, r, "role-middle", "192.0.2.20", "42000-42010", "role-middle-secret", 1)
+				exit := insertContractNode(t, r, "role-exit", "192.0.2.30", "43000-43010", "role-exit-secret", 1)
+				stopEntry := startMockNodeSession(t, server.URL, "role-entry-secret")
+				defer stopEntry()
+				var mu sync.Mutex
+				failReplacement := false
+				replacementAccepted := false
+				unsafeDeletion := false
+				chainDeletes := 0
+				stopMiddle := startMockNodeSessionWithCommandRecorder(t, server.URL, "role-middle-secret", func(kind string, data json.RawMessage) (bool, string) {
+					mu.Lock()
+					defer mu.Unlock()
+					if kind == "UpdateService" {
+						if failReplacement {
+							return true, failure
+						}
+						var services []struct {
+							Handler struct {
+								Chain string `json:"chain"`
+							} `json:"handler"`
+						}
+						if err := json.Unmarshal(data, &services); err == nil && len(services) > 0 && services[0].Handler.Chain == "" {
+							replacementAccepted = true
+						}
+					}
+					if kind == "DeleteChains" {
+						chainDeletes++
+						if !replacementAccepted {
+							unsafeDeletion = true
+						}
+					}
+					return false, ""
+				})
+				defer stopMiddle()
+				stopExit := startMockNodeSession(t, server.URL, "role-exit-secret")
+				defer stopExit()
+				post := func(path string, payload interface{}) *httptest.ResponseRecorder {
+					raw, _ := json.Marshal(payload)
+					req := httptest.NewRequest(http.MethodPost, path, bytes.NewReader(raw))
+					req.Header.Set("Authorization", token)
+					res := httptest.NewRecorder()
+					router.ServeHTTP(res, req)
+					return res
+				}
+				payload := map[string]interface{}{"name": "role-transition", "type": 2, "inNodeId": []map[string]interface{}{{"nodeId": entry, "protocol": "tls"}}, "chainNodes": [][]map[string]interface{}{{{"nodeId": middle, "protocol": "tls", "port": 42000}}}, "outNodeId": []map[string]interface{}{{"nodeId": exit, "protocol": "tls", "port": 43000}}}
+				assertCode(t, post("/api/v1/tunnel/create", payload), 0)
+				listed := post("/api/v1/tunnel/list", map[string]interface{}{})
+				var list struct {
+					Data []struct {
+						ID int64 `json:"id"`
+					} `json:"data"`
+				}
+				if err := json.Unmarshal(listed.Body.Bytes(), &list); err != nil || len(list.Data) != 1 {
+					t.Fatal("missing tunnel")
+				}
+				id := list.Data[0].ID
+				mu.Lock()
+				failReplacement = true
+				mu.Unlock()
+				payload["id"] = id
+				payload["chainNodes"] = [][]map[string]interface{}{}
+				payload["outNodeId"] = []map[string]interface{}{{"nodeId": middle, "protocol": "tls", "port": port}}
+				post("/api/v1/tunnel/update", payload)
+				post("/api/v1/tunnel/batch-redeploy", map[string]interface{}{"ids": []int64{id}})
+				mu.Lock()
+				if chainDeletes != 0 || unsafeDeletion {
+					t.Errorf("old middle chain removed before receiver replacement ACK: deletes=%d unsafe=%v", chainDeletes, unsafeDeletion)
+				}
+				failReplacement = false
+				mu.Unlock()
+				recovered := post("/api/v1/tunnel/batch-redeploy", map[string]interface{}{"ids": []int64{id}})
+				var result struct {
+					Data struct {
+						SuccessCount int `json:"successCount"`
+						FailCount    int `json:"failCount"`
+					} `json:"data"`
+				}
+				if err := json.Unmarshal(recovered.Body.Bytes(), &result); err != nil {
+					t.Fatal(err)
+				}
+				if result.Data.SuccessCount != 1 || result.Data.FailCount != 0 {
+					t.Fatalf("replacement retry failed: %s", recovered.Body.String())
+				}
+				mu.Lock()
+				defer mu.Unlock()
+				if !replacementAccepted || chainDeletes != 1 || unsafeDeletion {
+					t.Fatalf("obsolete chain must be removed exactly after successful exit replacement: accepted=%v deletes=%d unsafe=%v", replacementAccepted, chainDeletes, unsafeDeletion)
+				}
+			})
+		}
+	}
+}

go-backend/tests/contract/user_disable_contract_test.go

@@ -0,0 +1,87 @@
+package contract_test
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"go-backend/internal/auth"
+	"go-backend/internal/http/response"
+	"go-backend/internal/store/model"
+)
+
+func TestManualUserDisableRevokesLoginTokenAndForwardAccess(t *testing.T) {
+	const secret = "contract-jwt-secret"
+	router, r := setupContractRouter(t, secret)
+	seedContractUser(t, r, 2, "disable-contract", 1, 1)
+	for _, value := range []interface{}{
+		&model.Tunnel{ID: 1, Name: "disable-contract", Type: 1, Status: 1, Flow: 1},
+		&model.UserTunnel{ID: 10, UserID: 2, TunnelID: 1, Status: 1, Flow: 100, Num: 10},
+		&model.Forward{ID: 20, UserID: 2, UserName: "disable-contract", Name: "paused", TunnelID: 1, RemoteAddr: "127.0.0.1:80", Status: 0},
+	} {
+		if err := r.DB().Create(value).Error; err != nil {
+			t.Fatal(err)
+		}
+	}
+	userToken, err := auth.GenerateToken(2, "disable-contract", 1, secret)
+	if err != nil {
+		t.Fatal(err)
+	}
+	adminToken, err := auth.GenerateToken(1, "admin_user", 0, secret)
+	if err != nil {
+		t.Fatal(err)
+	}
+	request := func(path, token, body string) response.R {
+		t.Helper()
+		req := httptest.NewRequest(http.MethodPost, path, bytes.NewBufferString(body))
+		req.Header.Set("Authorization", token)
+		req.Header.Set("Content-Type", "application/json")
+		res := httptest.NewRecorder()
+		router.ServeHTTP(res, req)
+		var out response.R
+		if err := json.Unmarshal(res.Body.Bytes(), &out); err != nil {
+			t.Fatal(err)
+		}
+		return out
+	}
+	if out := request("/api/v1/forward/list", userToken, `{}`); out.Code != 0 {
+		t.Fatalf("token invalid before disable: %s", out.Msg)
+	}
+	if out := request("/api/v1/user/update", adminToken, `{"id":2,"user":"disable-contract","status":0}`); out.Code != 0 {
+		t.Fatalf("disable user: %s", out.Msg)
+	}
+	for _, check := range []struct{ path, body string }{
+		{"/api/v1/forward/list", `{}`},
+		{"/api/v1/forward/create", `{"tunnelId":1,"name":"bypass","remoteAddr":"127.0.0.1:80"}`},
+		{"/api/v1/forward/resume", `{"id":20}`},
+		{"/api/v1/forward/batch-resume", `{"ids":[20]}`},
+	} {
+		if out := request(check.path, userToken, check.body); out.Code != 401 {
+			t.Errorf("disabled user's old token accepted at %s: %+v", check.path, out)
+		}
+	}
+	if out := request("/api/v1/user/login", "", `{"username":"disable-contract","password":"contract-pass","captchaId":""}`); out.Code == 0 || !strings.Contains(out.Msg, "停用") {
+		t.Errorf("disabled account login: %+v", out)
+	}
+	if out := request("/api/v1/forward/resume", adminToken, `{"id":20}`); out.Code == 0 || !strings.Contains(out.Msg, "禁用") {
+		t.Errorf("admin bypassed disabled owner's policy: %+v", out)
+	}
+	out := request("/api/v1/tunnel/user/list", adminToken, `{"userId":2}`)
+	if out.Code != 0 {
+		t.Fatalf("list permissions: %s", out.Msg)
+	}
+	items, ok := out.Data.([]interface{})
+	if !ok || len(items) != 1 {
+		t.Fatalf("permission list: %#v", out.Data)
+	}
+	permission, ok := items[0].(map[string]interface{})
+	if !ok || permission["status"] != float64(0) {
+		t.Errorf("permission still displayed as enabled: %#v", items[0])
+	}
+	if got := mustQueryInt(t, r, "SELECT status FROM forward WHERE id = 20"); got != 0 {
+		t.Errorf("disabled forward resumed: %d", got)
+	}
+}

go-gost/go.mod

@@ -1,6 +1,6 @@
 module github.com/go-gost/gost
 
-go 1.25.0
+go 1.26.10
 
 require (
 	github.com/go-gost/core v0.3.1

go-gost/main.go

@@ -125,11 +125,13 @@ func main() {
 
 	distro := socket.DetectDistro()
 	fullVersion := fmt.Sprintf("%s (%s/%s)", version, distro, runtime.GOARCH)
-	wsReporter := socket.StartWebSocketReporterWithConfig(config.Addr, config.Secret, config.Http, config.Tls, config.Socks, fullVersion)
-	defer wsReporter.Stop()
 	service.SetHTTPReportURL(config.Addr, config.Secret)
 
-	p := &program{}
+	p := &program{
+		startReporter: func() reporter {
+			return socket.StartWebSocketReporterWithConfig(config.Addr, config.Secret, config.Http, config.Tls, config.Socks, fullVersion)
+		},
+	}
 	if err := svc.Run(p); err != nil {
 		logger.Default().Fatal(err)
 	}

go-gost/program.go

@@ -3,6 +3,14 @@ package main
 import (
 	"context"
 	"errors"
+	"net"
+	"net/http"
+	"os"
+	"os/signal"
+	"strings"
+	"syscall"
+	"time"
+
 	"github.com/go-gost/core/auth"
 	"github.com/go-gost/core/logger"
 	"github.com/go-gost/core/service"
@@ -18,20 +26,22 @@ import (
 	xservice "github.com/go-gost/x/service"
 	"github.com/go-gost/x/socket"
 	"github.com/judwhite/go-svc"
-	"net/http"
-	"os"
-	"os/signal"
-	"strings"
-	"syscall"
-	"time"
 )
 
-type program struct {
-	srvApi       service.Service
-	srvMetrics   service.Service
-	srvProfiling *http.Server
+type reporter interface {
+	Stop()
+}
 
-	cancel context.CancelFunc
+type program struct {
+	startReporter     func() reporter
+	reporter          reporter
+	srvApi            service.Service
+	srvMetrics        service.Service
+	srvProfiling      *http.Server
+	profilingListener net.Listener
+
+	cancel  context.CancelFunc
+	stopped bool
 }
 
 func (p *program) Init(env svc.Environment) error {
@@ -48,7 +58,15 @@ func (p *program) Init(env svc.Environment) error {
 	return nil
 }
 
-func (p *program) Start() error {
+func (p *program) Start() (err error) {
+	unlock := config.LockMutation()
+	defer unlock()
+	p.stopped = false
+	defer func() {
+		if err != nil {
+			p.stopRuntime()
+		}
+	}()
 	cfg, err := parser.Parse()
 	if err != nil {
 		return err
@@ -61,23 +79,28 @@ func (p *program) Start() error {
 		os.Exit(0)
 	}
 
-	config.Set(cfg)
-
 	if err := loader.Load(cfg); err != nil {
 		return err
 	}
 
-	// Enable config persistence after initial load so runtime mutations
-	// (AddService, UpdateService, DeleteService, etc.) are saved to disk.
-	socket.EnableConfigPersist()
-
 	if err := p.run(cfg); err != nil {
 		return err
 	}
 
+	config.Set(cfg)
+	socket.EnableConfigPersist()
+
 	ctx, cancel := context.WithCancel(context.Background())
 	p.cancel = cancel
-	go p.reload(ctx)
+	c := make(chan os.Signal, 1)
+	signal.Notify(c, syscall.SIGHUP)
+	go p.reload(ctx, c)
+
+	// A connected panel may immediately send commands. Only expose the agent
+	// after initial config loading, runtime startup and persistence are ready.
+	if p.startReporter != nil {
+		p.reporter = p.startReporter()
+	}
 
 	go func() {
 		select {
@@ -91,7 +114,14 @@ func (p *program) Start() error {
 	return nil
 }
 
-func (p *program) run(cfg *config.Config) error {
+func (p *program) run(cfg *config.Config) (err error) {
+	defer func() {
+		if err != nil {
+			// Auxiliary listeners may occupy ports required by the rollback config.
+			// Release all resources opened by this attempt before rebuilding it.
+			p.stopRuntime()
+		}
+	}()
 	for _, svc := range registry.ServiceRegistry().GetAll() {
 		svc := svc
 		go func() {
@@ -152,6 +182,10 @@ func (p *program) run(cfg *config.Config) error {
 
 	if p.srvProfiling != nil {
 		p.srvProfiling.Close()
+		if p.profilingListener != nil {
+			p.profilingListener.Close()
+			p.profilingListener = nil
+		}
 		p.srvProfiling = nil
 	}
 	if cfg.Profiling != nil {
@@ -162,7 +196,12 @@ func (p *program) run(cfg *config.Config) error {
 		s := &http.Server{
 			Addr: addr,
 		}
+		ln, err := net.Listen("tcp", addr)
+		if err != nil {
+			return err
+		}
 		p.srvProfiling = s
+		p.profilingListener = ln
 
 		go func() {
 			defer s.Close()
@@ -170,7 +209,7 @@ func (p *program) run(cfg *config.Config) error {
 			log := logger.Default().WithFields(map[string]any{"kind": "service", "service": "@profiling"})
 
 			log.Info("listening on ", addr)
-			if err := s.ListenAndServe(); !errors.Is(err, http.ErrServerClosed) {
+			if err := s.Serve(ln); !errors.Is(err, http.ErrServerClosed) {
 				log.Error(err)
 			}
 		}()
@@ -184,30 +223,45 @@ func (p *program) Stop() error {
 		p.cancel()
 	}
 
-	for name, srv := range registry.ServiceRegistry().GetAll() {
-		srv.Close()
+	if p.reporter != nil {
+		p.reporter.Stop()
+	}
+	unlock := config.LockMutation()
+	defer unlock()
+	p.stopped = true
+	p.stopRuntime()
+	return nil
+}
+
+func (p *program) stopRuntime() {
+	for name := range registry.ServiceRegistry().GetAll() {
+		registry.ServiceRegistry().Unregister(name)
 		logger.Default().Debugf("service %s shutdown", name)
 	}
 
 	if p.srvApi != nil {
 		p.srvApi.Close()
+		p.srvApi = nil
 		logger.Default().Debug("service @api shutdown")
 	}
 	if p.srvMetrics != nil {
 		p.srvMetrics.Close()
+		p.srvMetrics = nil
 		logger.Default().Debug("service @metrics shutdown")
 	}
 	if p.srvProfiling != nil {
 		p.srvProfiling.Close()
+		if p.profilingListener != nil {
+			p.profilingListener.Close()
+			p.profilingListener = nil
+		}
+		p.srvProfiling = nil
 		logger.Default().Debug("service @profiling shutdown")
 	}
-
-	return nil
 }
 
-func (p *program) reload(ctx context.Context) {
-	c := make(chan os.Signal, 1)
-	signal.Notify(c, syscall.SIGHUP)
+func (p *program) reload(ctx context.Context, c chan os.Signal) {
+	defer signal.Stop(c)
 
 	for {
 		select {
@@ -225,13 +279,16 @@ func (p *program) reload(ctx context.Context) {
 }
 
 func (p *program) reloadConfig() error {
+	unlock := config.LockMutation()
+	defer unlock()
+	if p.stopped {
+		return errors.New("agent is shutting down")
+	}
 	cfg, err := parser.Parse()
 	if err != nil {
 		return err
 	}
-	config.Set(cfg)
-
-	if err := loader.Load(cfg); err != nil {
+	if err := loader.Reload(cfg, p.run); err != nil {
 		return err
 	}
 	activeServices := make(map[string]struct{}, len(cfg.Services))
@@ -242,10 +299,6 @@ func (p *program) reloadConfig() error {
 	}
 	xservice.GetGlobalTrafficManager().RetainServices(activeServices)
 
-	if err := p.run(cfg); err != nil {
-		return err
-	}
-
 	return nil
 }