fix(backend): improve captcha validation and forward service sync (#219)

## Summary
- Add cloudflare site/secret key validation for captcha enabled check to
prevent incomplete captcha config
- Fix forward create to use UpdateService with tolerateExists for
idempotent service sync
- Introduce isAlreadyExistsMessage helper that correctly excludes
"address already in use" errors from being tolerated
- Add contract tests for forward toggle (pause/resume), address-in-use
rollback, and captcha compatibility

## Test Plan
- Contract tests added: `TestForwardCreateThenPauseResumeContract`,
`TestForwardCreateRollbackWhenServiceDispatchReturnsAddressInUseContract`,
`TestIsAlreadyExistsMessage`
- Captcha login flow tests updated for cloudflare key validation

.gitignore

@@ -259,6 +259,8 @@ gitee/
 doraemon.jks
 device.id
 commit.sh
+.opencode/
+analysis/
 sql/
 !go-backend/internal/store/sqlite/sql/
 !go-backend/internal/store/sqlite/sql/schema.sql
@@ -266,3 +268,6 @@ sql/
 !go-backend/internal/store/postgres/sql/
 !go-backend/internal/store/postgres/sql/schema.sql
 !go-backend/internal/store/postgres/sql/data.sql
+go-backend/gost.db-shm
+.gitignore
+go-backend/gost.db-wal

.sisyphus/ralph-loop.local.md

@@ -1,9 +0,0 @@
----
-active: true
-iteration: 1
-max_iterations: 100
-completion_promise: "DONE"
-started_at: "2026-02-15T16:38:58.212Z"
-session_id: "ses_39dd49703ffeveg711aA1D1YAk"
----
-现状后端数据库兼容sqlite和postgresql，每一次新增功能需要维护两套数据库sql，需求是使用一个数据库驱动能同时兼容两个数据库，请仔细分析，列出计划，全量迁移，并且写好所有的测试，确保重构后所有的功能都能正常运行，由于工程量大，请写一个计划列表的markdown记录，每次完成一个就记录一下进度

AGENTS.md

@@ -1,11 +1,12 @@
 # PROJECT KNOWLEDGE BASE
 
-**Generated:** Sun Feb 15 2026
-**Commit:** e5e22ba
+**Generated:** Thu Feb 26 2026
+**Commit:** 21008cc
 **Branch:** main
+**Tag:** 2.1.5-rc15
 
 ## OVERVIEW
-FLVX (formerly Flux Panel) is a traffic forwarding management system built on a forked GOST v3 stack. It ships as a Go-based admin API (SQLite) + Vite/React UI + Go forwarding agent, with optional mobile WebView wrappers.
+FLVX (formerly Flux Panel) is a traffic forwarding management system built on a forked GOST v3 stack. It ships as a Go-based admin API (SQLite/PostgreSQL) + Vite/React UI + Go forwarding agent, with optional mobile WebView wrappers.
 
 ## STRUCTURE
 ```
@@ -13,12 +14,14 @@ FLVX (formerly Flux Panel) is a traffic forwarding management system built on a
 ├── go-gost/               # Go forwarding agent (forked gost + local x/)
 │   └── x/                 # Local fork of github.com/go-gost/x (replace => ./x)
 ├── go-backend/            # Go Admin API (GORM + SQLite/PostgreSQL, net/http)
-├── vite-frontend/         # React/Vite dashboard (HeroUI + Tailwind)
+│   └── tests/contract/    # Integration/contract tests
+├── vite-frontend/         # React/Vite dashboard (shadcn bridge + Tailwind v4)
+│   └── src/shadcn-bridge/heroui/  # HeroUI-compatible facade
 ├── docker-compose-v4.yml  # Panel deploy (IPv4-only bridge)
 ├── docker-compose-v6.yml  # Panel deploy (IPv6-enabled bridge)
 ├── panel_install.sh       # Panel installer/upgrader (downloads compose)
 ├── install.sh             # Node installer/upgrader (downloads gost binary)
-└── .github/workflows/     # CI: build/push images + release artifacts
+└── .github/workflows/     # CI: build/test + Docker push + release artifacts
 ```
 
 ## WHERE TO LOOK
@@ -28,10 +31,15 @@ FLVX (formerly Flux Panel) is a traffic forwarding management system built on a
 | **Deploy (IPv6)** | `docker-compose-v6.yml` | Same as v4 + IPv6-enabled bridge |
 | **Panel install** | `panel_install.sh` | Picks v4/v6, generates `JWT_SECRET`, downloads compose |
 | **Node install** | `install.sh` | Installs `/etc/flux_agent/flux_agent` + writes `config.json`/`gost.json` + systemd `flux_agent.service` |
-| **Admin API** | `go-backend/` | Go Admin API (SQLite) |
-| **Web UI** | `vite-frontend/` | React/Vite dashboard (HeroUI + Tailwind) |
+| **Admin API** | `go-backend/` | Go Admin API (SQLite/PostgreSQL) |
+| **Web UI** | `vite-frontend/` | React/Vite dashboard (shadcn bridge + Tailwind v4) |
+| **UI Compatibility** | `vite-frontend/src/shadcn-bridge/heroui/` | HeroUI-compatible API wrappers backed by shadcn/radix |
+| **Theme Tokens** | `vite-frontend/src/styles/tailwind-theme.pcss` | Tailwind v4 `@theme inline` semantic color mapping |
 | **Go Agent** | `go-gost/` | Forwarding agent (forked gost + local x/) |
 | **Go Core** | `go-gost/x/` | Handlers/listeners/dialers + management API |
+| **Repository Layer** | `go-backend/internal/store/repo/` | GORM data access (repository.go 83k LOC) |
+| **Contract Tests** | `go-backend/tests/contract/` | Integration tests for auth, federation, tunnels |
+| **CI Workflows** | `.github/workflows/` | ci-build.yml, docker-build.yml, deploy-docs.yml |
 
 ## CODE MAP
 | Symbol | Type | Location | Role |
@@ -40,13 +48,18 @@ FLVX (formerly Flux Panel) is a traffic forwarding management system built on a
 | `main` | Func | `go-backend/cmd/paneld/main.go` | Backend Entry |
 | `App` | Component | `vite-frontend/src/App.tsx` | Frontend Entry |
 | `main` | Func | `go-gost/main.go` | Agent Entry |
-
+| `Repository` | Struct | `go-backend/internal/store/repo/repository.go` | Data Access Layer |
+| `Handler` | Struct | `go-backend/internal/http/handler/handler.go` | HTTP Handlers |
+| `websocket_reporter` | Func | `go-gost/x/socket/websocket_reporter.go` | Panel Telemetry |
 
 ## CONVENTIONS
 - **Auth**: `Authorization` header carries the raw JWT token (no `Bearer` prefix) between `vite-frontend/` and `go-backend/`.
 - **Module Fork**: `go-gost/` uses `replace github.com/go-gost/x => ./x` and `go-gost/x/` is also its own Go module.
 - **Encryption**: Agent-to-panel communication uses AES encryption with node `secret` as PSK.
 - **API Envelope**: All REST responses follow `{code, msg, data, ts}` structure (code 0 = success).
+- **Frontend UI Layer**: Import UI primitives from `src/shadcn-bridge/heroui/*` (legacy-compatible facade), not direct `@heroui/*` packages.
+- **Tailwind v4 Semantic Colors**: `src/styles/globals.css` must import `src/styles/tailwind-theme.pcss`; removing it breaks semantic classes like `bg-primary`, `text-foreground`, and `border-input`.
+- **Go Versions**: `go-backend` uses Go 1.24, `go-gost` uses Go 1.23, `go-gost/x` uses Go 1.22.
 
 ## ANTI-PATTERNS (THIS PROJECT)
 - **DO NOT EDIT** generated protobuf output: `go-gost/x/internal/util/grpc/proto/*.pb.go`, `go-gost/x/internal/util/grpc/proto/*_grpc.pb.go`.
@@ -54,6 +67,9 @@ FLVX (formerly Flux Panel) is a traffic forwarding management system built on a
 - **DO NOT MODIFY** `install.sh` or `panel_install.sh` locally - CI overwrites these on release.
 - **DO NOT** let backend handlers call `repo.DB()` directly — add a Repository method instead.
 - **DO NOT ADD** frontend tests - project has no test infrastructure (Vitest/Jest not configured).
+- **DO NOT REINTRODUCE** `@heroui/*` or `@nextui-org/*` dependencies; migration is now shadcn bridge-based.
+- **DO NOT** use `type:jsonb` or `type:serial` in GORM tags (SQLite incompatible).
+- **DO NOT** omit `TableName()` on new models — GORM pluralizes by default.
 
 ## COMMANDS
 ```bash
@@ -69,15 +85,21 @@ docker compose -f docker-compose-v6.yml up -d
 (cd go-backend && make build)
 (cd vite-frontend && npm run dev)
 (cd go-gost && go run .)
+
+# Testing
+(cd go-backend && go test ./...)
+(cd go-backend && go test ./tests/contract/...)
 ```
 
 ## UNIQUE STYLES
 - **Flat Monorepo**: Language-prefixed dirs (`go-backend`, `go-gost`, `vite-frontend`) instead of `apps/`/`libs/`.
 - **Asymmetric Go Layout**: `go-backend` follows `cmd/<app>/main.go` while `go-gost` uses `root/main.go`.
 - **Frontend Hybrid Mode**: `App.tsx` detects "H5 mode" (mobile WebView) vs desktop, dictating layout strategy.
+- **Experimental Bundler**: `vite-frontend` uses `rolldown-vite` (Rust-based) instead of standard Vite.
+- **Non-minified Builds**: `vite.config.ts` sets `minify: false`, `treeshake: false` for debugging.
 
 ## NOTES
-- LSP servers are not installed in this environment (gopls/jdtls/typescript-language-server); rely on grep-based navigation.
+- LSP servers are not installed in this environment (gopls/typescript-language-server); rely on grep-based navigation.
 - `vite-frontend/vite.config.ts` sets `minify: false` and disables treeshake; expect larger bundles.
 - `vite-frontend` uses `rolldown-vite` (experimental Rust bundler) instead of standard Vite.
 - Install scripts (`install.sh`, `panel_install.sh`) self-delete after execution - common pattern in one-liner installs.
@@ -85,5 +107,9 @@ docker compose -f docker-compose-v6.yml up -d
 - CI dynamically injects `PINNED_VERSION` into install scripts and docker-compose files during releases.
 - `panel_install.sh` auto-detects IPv6 and modifies `/etc/docker/daemon.json` to enable IPv6 bridge.
 - Download proxy `https://gcode.hostcentral.cc/` used for GitHub downloads in China/restricted environments.
-- Backend has contract tests in `go-backend/tests/contract/` - frontend has no test infrastructure (Vitest/Jest not configured).
+- Backend has contract tests in `go-backend/tests/contract/` - frontend has no test infrastructure.
 - `analysis/3x-ui/` contains a separate git repo for reference/comparison - not part of FLVX core.
+- CI workflows: `ci-build.yml` (build check), `docker-build.yml` (multi-arch images + release), `deploy-docs.yml` (MkDocs).
+- PostgreSQL migration supported via `panel_install.sh` menu option using pgloader.
+- Repository layer is large: `repository.go` (83k LOC), `repository_mutations.go` (43k LOC).
+- Button visual parity relies on `vite-frontend/src/shadcn-bridge/heroui/button.tsx` color mapping + `vite-frontend/src/styles/tailwind-theme.pcss` token export.

IMPLEMENTATION_PLAN.md

@@ -0,0 +1,148 @@
+# 限速功能重构实施计划
+
+## 一、需求概述
+
+**原始需求**: 限速功能当前绑定到具体隧道，需要改为不绑定隧道，创建限速后可以自由在隧道上限速，也可以在转发上限速。
+
+**核心变更**:
+1. 限速规则(SpeedLimit)与隧道的绑定关系改为可选
+2. 转发(Forward)支持独立的限速规则
+
+---
+
+## 二、实施计划清单
+
+### 2.0 计划状态（审计更新：2026-02-26）
+
+- 总体状态：**进行中（未验收通过）**
+- 已完成：模型、仓储查询、限速 CRUD、控制面优先级、限速页与类型改造、编译与测试通过
+- 未完成：**Forward 独立限速写入链路**（前端表单 -> API handler -> repository 落库 `forward.speed_id`）
+
+### 2.1 后端模型层 (Model)
+
+| 序号 | 任务 | 文件 | 状态 |
+|------|------|------|------|
+| M1 | SpeedLimit.TunnelID 改为 sql.NullInt64 (可空) | `go-backend/internal/store/model/model.go` | ✅ 完成 |
+| M2 | SpeedLimit.TunnelName 改为 sql.NullString (可空) | `go-backend/internal/store/model/model.go` | ✅ 完成 |
+| M3 | Forward 添加 SpeedID sql.NullInt64 字段 | `go-backend/internal/store/model/model.go` | ✅ 完成 |
+| M4 | ForwardRecord 添加 SpeedID sql.NullInt64 字段 | `go-backend/internal/store/model/model.go` | ✅ 完成 |
+| M5 | SpeedLimitBackup.TunnelID 改为指针类型 | `go-backend/internal/store/model/model.go` | ✅ 完成 |
+| M6 | ForwardBackup 添加 SpeedID *int64 字段 | `go-backend/internal/store/model/model.go` | ✅ 完成 |
+
+### 2.2 后端仓储层 (Repository)
+
+| 序号 | 任务 | 文件 | 状态 |
+|------|------|------|------|
+| R1 | ListSpeedLimits() 返回可空 tunnelId/tunnelName | `go-backend/internal/store/repo/repository.go` | ✅ 完成 |
+| R2 | ListForwards() 返回 speedId 字段 | `go-backend/internal/store/repo/repository.go` | ✅ 完成 |
+| R3 | CreateSpeedLimit() 参数 tunnelID 改为 *int64 | `go-backend/internal/store/repo/repository_mutations.go` | ✅ 完成 |
+| R4 | UpdateSpeedLimit() 参数 tunnelID 改为 *int64 | `go-backend/internal/store/repo/repository_mutations.go` | ✅ 完成 |
+| R5 | GetSpeedLimitTunnelID() 返回 sql.NullInt64 | `go-backend/internal/store/repo/repository_mutations.go` | ✅ 完成 |
+| R6 | exportSpeedLimits() 处理可空字段 | `go-backend/internal/store/repo/repository.go` | ✅ 完成 |
+| R7 | importSpeedLimits() 处理可空字段 | `go-backend/internal/store/repo/repository.go` | ✅ 完成 |
+| R8 | GetSpeedLimitSpeed() 新增方法 | `go-backend/internal/store/repo/repository_flow.go` | ✅ 完成 |
+| R9 | ListForwardsByTunnel() 返回 SpeedID | `go-backend/internal/store/repo/repository_control.go` | ✅ 完成 |
+| R10 | ListActiveForwardsByUser() 返回 SpeedID | `go-backend/internal/store/repo/repository_flow.go` | ✅ 完成 |
+| R11 | ListActiveForwardsByUserTunnel() 返回 SpeedID | `go-backend/internal/store/repo/repository_flow.go` | ✅ 完成 |
+| R12 | GetForwardRecord() 返回 SpeedID | `go-backend/internal/store/repo/repository_flow.go` | ✅ 完成 |
+
+### 2.3 后端处理器层 (Handler)
+
+| 序号 | 任务 | 文件 | 状态 |
+|------|------|------|------|
+| H1 | speedLimitCreate 处理可选 tunnelId | `go-backend/internal/http/handler/mutations.go` | ✅ 完成 |
+| H2 | speedLimitUpdate 处理可选 tunnelId | `go-backend/internal/http/handler/mutations.go` | ✅ 完成 |
+| H3 | speedLimitDelete 处理可空 tunnelID | `go-backend/internal/http/handler/mutations.go` | ✅ 完成 |
+
+### 2.4 后端控制平面 (Control Plane)
+
+| 序号 | 任务 | 文件 | 状态 |
+|------|------|------|------|
+| C1 | syncForwardServices 优先使用 Forward.SpeedID | `go-backend/internal/http/handler/control_plane.go` | ✅ 完成 |
+| C2 | 回退到 UserTunnel 的 speed limit | `go-backend/internal/http/handler/control_plane.go` | ✅ 完成 |
+
+### 2.5 前端类型定义 (TypeScript Types)
+
+| 序号 | 任务 | 文件 | 状态 |
+|------|------|------|------|
+| T1 | SpeedLimitApiItem.tunnelId 改为可选 | `vite-frontend/src/api/types.ts` | ✅ 完成 |
+| T2 | ForwardApiItem 添加 speedId 字段 | `vite-frontend/src/api/types.ts` | ✅ 完成 |
+| T3 | ForwardMutationPayload 添加 speedId 字段 | `vite-frontend/src/api/types.ts` | ✅ 完成 |
+| T4 | SpeedLimitMutationPayload.tunnelId 改为可选 | `vite-frontend/src/api/types.ts` | ✅ 完成 |
+
+### 2.6 前端页面组件
+
+| 序号 | 任务 | 文件 | 状态 |
+|------|------|------|------|
+| F1 | SpeedLimitRule 接口更新 | `vite-frontend/src/pages/limit.tsx` | ✅ 完成 |
+| F2 | SpeedLimitForm 接口更新 | `vite-frontend/src/pages/limit.tsx` | ✅ 完成 |
+| F3 | validateForm 移除 tunnelId 必填校验 | `vite-frontend/src/pages/limit.tsx` | ✅ 完成 |
+| F4 | Select 组件改为可选 | `vite-frontend/src/pages/limit.tsx` | ✅ 完成 |
+| F5 | 显示"未绑定"状态 | `vite-frontend/src/pages/limit.tsx` | ✅ 完成 |
+
+### 2.7 编译验证
+
+| 序号 | 任务 | 状态 |
+|------|------|------|
+| B1 | Go 后端编译通过 | ✅ 完成 |
+| B2 | TypeScript 类型检查通过 | ✅ 完成 |
+| B3 | `go test ./...` 全量通过 | ✅ 完成 |
+| B4 | `go test ./tests/contract/... -run SpeedLimit` 通过 | ✅ 完成 |
+
+### 2.8 Forward 独立限速写入链路补全（新增）
+
+| 序号 | 任务 | 文件 | 状态 |
+|------|------|------|------|
+| N1 | forwardCreate 支持接收并校验可选 speedId，写入 Forward.SpeedID | `go-backend/internal/http/handler/mutations.go` | ✅ 完成 |
+| N2 | forwardUpdate 支持更新/清空 speedId，并触发服务重下发 | `go-backend/internal/http/handler/mutations.go` | ✅ 完成 |
+| N3 | CreateForwardTx 支持落库 speed_id | `go-backend/internal/store/repo/repository_mutations.go` | ✅ 完成 |
+| N4 | UpdateForward 支持更新 speed_id | `go-backend/internal/store/repo/repository_mutations.go` | ✅ 完成 |
+| N5 | Forward 页面新增限速选择并透传 speedId | `vite-frontend/src/pages/forward.tsx` | ✅ 完成 |
+| N6 | Forward 相关契约测试补充 speedId 写入/清空断言 | `go-backend/tests/contract/forward_contract_test.go` | ✅ 完成 |
+
+---
+
+## 三、优先级说明
+
+限速规则应用优先级:
+1. **Forward.SpeedID** - 转发级别的限速 (最高优先)
+2. **UserTunnel.SpeedID** - 用户隧道权限级别的限速 (回退)
+
+---
+
+## 四、数据库兼容性
+
+- SpeedLimit 表: `tunnel_id` 和 `tunnel_name` 字段改为可空 (GORM AutoMigrate 自动处理)
+- Forward 表: 新增 `speed_id` 可空字段 (GORM AutoMigrate 自动处理)
+
+---
+
+## 五、验证检查项
+
+### 5.1 功能验证（审计后）
+
+- [x] 创建不限速规则的限速 (不绑定隧道)
+- [x] 创建绑定隧道的限速 (兼容旧逻辑)
+- [x] 编辑限速规则，切换隧道绑定状态
+- [ ] 删除限速规则
+- [ ] 转发列表正确显示 speedId
+
+### 5.2 API 验证（审计后）
+
+- [x] GET /api/speed-limit/list 返回可选 tunnelId
+- [x] POST /api/speed-limit/create 接受可选 tunnelId
+- [x] POST /api/speed-limit/update 接受可选 tunnelId
+- [ ] GET /api/forward/list 返回 speedId
+
+### 5.3 兼容性验证（审计后）
+
+- [x] 现有绑定隧道的限速规则继续正常工作
+- [ ] 现有 UserTunnel 的限速继续正常工作
+- [ ] 备份/恢复功能正常
+
+### 5.4 Forward 独立限速闭环验证（新增）
+
+- [x] POST /api/forward/create 接受 speedId 并写入 `forward.speed_id`
+- [x] POST /api/forward/update 可更新/清空 speedId
+- [x] Forward 表单可选择限速并提交 speedId
+- [ ] `syncForwardServices` 实际使用 Forward.SpeedID 而非仅回退 UserTunnel.SpeedID

README.md

@@ -129,27 +129,28 @@ docker compose up -d
 - **License**: Apache License 2.0
 
 ## Modifications
-The following major changes and additions have been made in this fork (FLVX):
+This fork (FLVX) is no longer a light patch on top of the upstream project. It has been deeply reworked, with both backend and frontend rebuilt around a Go-based architecture.
 
-### 1. Backend Architecture (Replaced)
-- **Removed**: The original `springboot-backend/` (Java/Spring Boot) has been entirely removed.
-- **Added**: A new `go-backend/` (Go/SQLite) implementation replaces the original backend.
+### 1. Backend (Rewritten)
+- **Removed**: The original `springboot-backend/` (Java/Spring Boot) implementation.
+- **Added**: A fully rewritten `go-backend/` service (Go), including updated data and API handling for panel management.
 
-### 2. Forwarding Agent (Modified)
-- **Modified**: `go-gost/` - Modified forwarding agent wrapper.
-- **Modified**: `go-gost/x/` - Modified local fork of the `gost` extensions library.
+### 2. Frontend (Reworked)
+- **Reworked**: `vite-frontend/` has been substantially rebuilt to match the new backend contract and current UI layer architecture.
+- **Updated**: Dashboard pages/components and interaction flows for the current React/Vite stack.
 
-### 3. Frontend (Modified)
-- **Modified**: `vite-frontend/` - Significant updates to the React/Vite dashboard to compatible with the new Go backend, including UI/UX improvements (HeroUI + Tailwind).
+### 3. Forwarding Stack (Modified)
+- **Modified**: `go-gost/` forwarding agent wrapper.
+- **Modified**: `go-gost/x/` local fork of `github.com/go-gost/x`.
 
-### 4. Mobile Applications (Removed)
-- **Removed**: `android-app/` - Source code for the Android client.
-- **Removed**: `ios-app/` - Source code for the iOS client.
+### 4. Mobile Clients (Removed)
+- **Removed**: `android-app/` source code.
+- **Removed**: `ios-app/` source code.
 
-### 5. Infrastructure & Scripts
-- **Modified**: `docker-compose.yml` (installer output name, auto-selects IPv4/IPv6 template, updated for Go backend).
-- **Modified**: `install.sh`, `panel_install.sh` (Updated installation logic).
-- **Added**: `AGENTS.md` (Project documentation).
+### 5. Deployment & Project Infrastructure
+- **Updated**: Docker deployment templates and installer output flow (IPv4/IPv6 compose variants).
+- **Updated**: Release installation scripts (`install.sh`, `panel_install.sh`) and supporting automation.
+- **Added/Updated**: Project-level engineering documentation (for example `AGENTS.md`).
 
 ---
 

go-backend/AGENTS.md

@@ -2,7 +2,7 @@
 
 ## OVERVIEW
 Go-based Admin API for FLVX. Replaced legacy Spring Boot backend.
-**Stack:** Go 1.23, net/http (std lib), GORM + SQLite/PostgreSQL (glebarez/sqlite - CGO-free).
+**Stack:** Go 1.24, net/http (std lib), GORM + SQLite/PostgreSQL (glebarez/sqlite - CGO-free).
 
 ## STRUCTURE
 ```
@@ -17,14 +17,15 @@ go-backend/
 │   ├── store/
 │   │   ├── model/model.go    # GORM model structs (single source of truth)
 │   │   └── repo/             # Data Access Layer (Repository pattern, GORM)
-│   │       ├── repository.go           # Core queries, Open/OpenPostgres, AutoMigrate
-│   │       ├── repository_mutations.go # Mutation helpers (user/node/tunnel/forward CRUD)
-│   │       ├── repository_federation.go# Federation-specific queries
+│   │       ├── repository.go           # Core queries, Open/OpenPostgres, AutoMigrate (83k LOC)
+│   │       ├── repository_mutations.go # Mutation helpers (user/node/tunnel/forward CRUD, 43k LOC)
+│   │       ├── repository_federation.go # Federation-specific queries
 │   │       ├── repository_flow.go      # Flow/forward status queries
-│   │       └── repository_control.go   # Control plane queries
+│   │       ├── repository_control.go   # Control plane queries
+│   │       └── repository_groups.go    # Group management queries
 │   └── auth/                 # Auth logic
-├── tests/                    # Integration/Contract tests
-├── Dockerfile                # Multi-stage build (alpine)
+├── tests/contract/            # Integration/contract tests (14 tests)
+├── Dockerfile                # Multi-stage build (golang:1.24-bookworm → debian:bookworm-slim)
 └── Makefile                  # Build commands
 ```
 
@@ -36,6 +37,7 @@ go-backend/
 | **Repository** | `go-backend/internal/store/repo/` | GORM-based queries, all DB ops encapsulated |
 | **Auth Middleware** | `go-backend/internal/http/middleware/jwt.go` | Extracts `Authorization` header |
 | **WebSocket** | `go-backend/internal/ws/` | Real-time updates (traffic, status) |
+| **Contract Tests** | `go-backend/tests/contract/` | Integration tests for auth, federation, tunnels |
 
 ## CONVENTIONS
 - **GORM ORM**: Uses GORM with `glebarez/sqlite` (CGO-free) and `gorm.io/driver/postgres`.
@@ -47,6 +49,7 @@ go-backend/
 - **API Envelope**: All responses use `response.R{code, msg, data, ts}` structure.
 - **Config**: Loaded from environment variables (see `cmd/paneld/main.go`).
 - **SQLite Constraints**: `MaxOpenConns(1)`, WAL mode, busy_timeout=5000.
+- **PostgreSQL**: Supported via `DB_TYPE=postgres` and `DATABASE_URL` env vars.
 
 ## ANTI-PATTERNS
 - **DO NOT** let handlers call `repo.DB()` directly — add a Repository method instead.
@@ -58,6 +61,7 @@ go-backend/
 ```bash
 cd go-backend
 go run ./cmd/paneld       # Default: SERVER_ADDR=:6365
-go test ./...
+go test ./...             # Unit tests
+go test ./tests/contract/... # Contract tests
 make build
 ```

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

@@ -1,10 +1,10 @@
 # BACKEND HTTP HANDLER KNOWLEDGE BASE
 
-**Generated:** Sun Feb 15 2026
+**Generated:** Thu Feb 26 2026
 
 ## OVERVIEW
 HTTP request handlers for FLVX Admin API. Core business logic layer.
-**Stack:** Go 1.23, net/http, GORM via Repository pattern.
+**Stack:** Go 1.24, net/http, GORM via Repository pattern.
 
 ## STRUCTURE
 ```
@@ -14,7 +14,7 @@ handler/
 ├── federation.go     # Federation/cluster sync API
 ├── flow_policy.go    # Traffic policy API
 ├── jobs.go           # Background job management (sync, cleanup)
-├── mutations.go      # CRUD for users, tunnels, forwards (largest: 100k+ LOC)
+├── mutations.go      # CRUD for users, tunnels, forwards (~3700 LOC)
 └── upgrade.go        # System upgrade API
 ```
 
@@ -26,10 +26,11 @@ handler/
 | **Federation Sync** | `federation.go` | Panel-to-panel sync |
 | **Traffic Policies** | `flow_policy.go` | Flow limiting, quota management |
 | **Background Jobs** | `jobs.go` | Scheduled sync/cleanup tasks |
+| **Node Control** | `control_plane.go` | Node add/delete/list operations |
 
 ## CONVENTIONS
 - Inherits from parent: GORM via Repository pattern, JWT in Authorization header.
-- Large files expected (`mutations.go` 3716 LOC - central mutation hub).
+- Large files expected (`mutations.go` ~3700 LOC - central mutation hub).
 - Uses `repo.Repository` for DB access via `h.repo.XXX()` methods.
 - Handlers never call `repo.DB()` directly — all queries go through Repository methods.
 - Domain-driven file split: one file per functional area (federation, jobs, etc.).

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

@@ -152,11 +152,32 @@ func (h *Handler) syncForwardServices(forward *forwardRecord, method string, all
 		return errors.New("转发入口端口不存在")
 	}
 
-	userTunnelID, limiterID, speed, err := h.resolveUserTunnelAndLimiter(forward.UserID, forward.TunnelID)
-	if err != nil {
-		return err
+	// Determine limiter from forward's SpeedID first, fallback to UserTunnel's limiter
+	var limiterID *int64
+	var speed *int
+
+	if forward.SpeedID.Valid && forward.SpeedID.Int64 > 0 {
+		// Forward has its own speed limit
+		speedVal, err := h.repo.GetSpeedLimitSpeed(forward.SpeedID.Int64)
+		if err == nil && speedVal > 0 {
+			limiterID = &forward.SpeedID.Int64
+			speed = &speedVal
+		}
 	}
-	serviceBase := buildForwardServiceBase(forward.ID, forward.UserID, userTunnelID)
+
+	if limiterID == nil {
+		// Fall back to UserTunnel speed limit
+		var utLimiterID *int64
+		var utSpeed *int
+		_, utLimiterID, utSpeed, err = h.resolveUserTunnelAndLimiter(forward.UserID, forward.TunnelID)
+		if err != nil {
+			return err
+		}
+		limiterID = utLimiterID
+		speed = utSpeed
+	}
+
+	serviceBase := buildForwardServiceBase(forward.ID, forward.UserID, 0)
 	tunnelTLSProtocol, err := h.isTunnelSelectedTLSProtocol(forward.TunnelID)
 	if err != nil {
 		return err
@@ -164,7 +185,9 @@ func (h *Handler) syncForwardServices(forward *forwardRecord, method string, all
 
 	for _, fp := range ports {
 		if limiterID != nil && speed != nil {
-			h.ensureLimiterOnNode(fp.NodeID, *limiterID, *speed)
+			if err := h.ensureLimiterOnNode(fp.NodeID, *limiterID, *speed); err != nil {
+				return err
+			}
 		}
 
 		node, err := h.getNodeRecord(fp.NodeID)
@@ -288,7 +311,7 @@ func (h *Handler) sendNodeCommand(nodeID int64, commandType string, data interfa
 	}
 	msg := strings.ToLower(strings.TrimSpace(err.Error()))
 	if tolerateExists {
-		if strings.Contains(msg, "exists") || strings.Contains(msg, "already") || strings.Contains(msg, "已存在") {
+		if isAlreadyExistsMessage(msg) {
 			return result, nil
 		}
 	}
@@ -360,6 +383,8 @@ func (h *Handler) diagnoseForwardRuntime(forward *forwardRecord) (map[string]int
 		return nil, errors.New("隧道配置不完整")
 	}
 
+	ipPreference := h.repo.GetTunnelIPPreference(forward.TunnelID)
+
 	inNodes, chainHops, outNodes := splitChainNodeGroups(chainRows)
 	results := make([]map[string]interface{}, 0, len(chainRows)*2+len(targets))
 	nodeCache := map[int64]*nodeRecord{}
@@ -383,7 +408,7 @@ func (h *Handler) diagnoseForwardRuntime(forward *forwardRecord) (map[string]int
 						"fromChainType": 1,
 						"toChainType":   2,
 						"toInx":         firstNode.Inx,
-					})
+					}, ipPreference)
 				}
 			} else {
 				for _, outNode := range outNodes {
@@ -391,7 +416,7 @@ func (h *Handler) diagnoseForwardRuntime(forward *forwardRecord) (map[string]int
 					h.appendChainHopDiagnosis(&results, nodeCache, inNode.NodeID, outNode, description, map[string]interface{}{
 						"fromChainType": 1,
 						"toChainType":   3,
-					})
+					}, ipPreference)
 				}
 			}
 		}
@@ -406,7 +431,7 @@ func (h *Handler) diagnoseForwardRuntime(forward *forwardRecord) (map[string]int
 							"fromInx":       currentNode.Inx,
 							"toChainType":   2,
 							"toInx":         nextNode.Inx,
-						})
+						}, ipPreference)
 					}
 				} else {
 					for _, outNode := range outNodes {
@@ -415,7 +440,7 @@ func (h *Handler) diagnoseForwardRuntime(forward *forwardRecord) (map[string]int
 							"fromChainType": 2,
 							"fromInx":       currentNode.Inx,
 							"toChainType":   3,
-						})
+						}, ipPreference)
 					}
 				}
 			}
@@ -470,6 +495,7 @@ func (h *Handler) diagnoseTunnelRuntime(tunnelID int64) (map[string]interface{},
 		return nil, errors.New("隧道配置不完整")
 	}
 
+	ipPreference := h.repo.GetTunnelIPPreference(tunnelID)
 	inNodes, chainHops, outNodes := splitChainNodeGroups(chainRows)
 	results := make([]map[string]interface{}, 0, len(chainRows)*2)
 	nodeCache := map[int64]*nodeRecord{}
@@ -478,7 +504,7 @@ func (h *Handler) diagnoseTunnelRuntime(tunnelID int64) (map[string]interface{},
 	case 1:
 		for _, inNode := range inNodes {
 			description := fmt.Sprintf("入口(%s)->外网", inNode.NodeName)
-			h.appendPathDiagnosis(&results, nodeCache, inNode.NodeID, "www.google.com", 443, description, map[string]interface{}{
+			h.appendPathDiagnosis(&results, nodeCache, inNode.NodeID, "www.bing.com", 443, description, map[string]interface{}{
 				"fromChainType": 1,
 			})
 		}
@@ -491,7 +517,7 @@ func (h *Handler) diagnoseTunnelRuntime(tunnelID int64) (map[string]interface{},
 						"fromChainType": 1,
 						"toChainType":   2,
 						"toInx":         firstNode.Inx,
-					})
+					}, ipPreference)
 				}
 			} else {
 				for _, outNode := range outNodes {
@@ -499,7 +525,7 @@ func (h *Handler) diagnoseTunnelRuntime(tunnelID int64) (map[string]interface{},
 					h.appendChainHopDiagnosis(&results, nodeCache, inNode.NodeID, outNode, description, map[string]interface{}{
 						"fromChainType": 1,
 						"toChainType":   3,
-					})
+					}, ipPreference)
 				}
 			}
 		}
@@ -514,7 +540,7 @@ func (h *Handler) diagnoseTunnelRuntime(tunnelID int64) (map[string]interface{},
 							"fromInx":       currentNode.Inx,
 							"toChainType":   2,
 							"toInx":         nextNode.Inx,
-						})
+						}, ipPreference)
 					}
 				} else {
 					for _, outNode := range outNodes {
@@ -523,7 +549,7 @@ func (h *Handler) diagnoseTunnelRuntime(tunnelID int64) (map[string]interface{},
 							"fromChainType": 2,
 							"fromInx":       currentNode.Inx,
 							"toChainType":   3,
-						})
+						}, ipPreference)
 					}
 				}
 			}
@@ -531,14 +557,14 @@ func (h *Handler) diagnoseTunnelRuntime(tunnelID int64) (map[string]interface{},
 
 		for _, outNode := range outNodes {
 			description := fmt.Sprintf("出口(%s)->外网", outNode.NodeName)
-			h.appendPathDiagnosis(&results, nodeCache, outNode.NodeID, "www.google.com", 443, description, map[string]interface{}{
+			h.appendPathDiagnosis(&results, nodeCache, outNode.NodeID, "www.bing.com", 443, description, map[string]interface{}{
 				"fromChainType": 3,
 			})
 		}
 	default:
 		for _, inNode := range inNodes {
 			description := fmt.Sprintf("入口(%s)->外网", inNode.NodeName)
-			h.appendPathDiagnosis(&results, nodeCache, inNode.NodeID, "www.google.com", 443, description, map[string]interface{}{
+			h.appendPathDiagnosis(&results, nodeCache, inNode.NodeID, "www.bing.com", 443, description, map[string]interface{}{
 				"fromChainType": 1,
 			})
 		}
@@ -693,13 +719,14 @@ func (h *Handler) appendPathDiagnosis(results *[]map[string]interface{}, nodeCac
 	*results = append(*results, item)
 }
 
-func (h *Handler) appendChainHopDiagnosis(results *[]map[string]interface{}, nodeCache map[int64]*nodeRecord, fromNodeID int64, toNode chainNodeRecord, description string, metadata map[string]interface{}) {
+func (h *Handler) appendChainHopDiagnosis(results *[]map[string]interface{}, nodeCache map[int64]*nodeRecord, fromNodeID int64, toNode chainNodeRecord, description string, metadata map[string]interface{}, ipPreference string) {
+	fromNode, _ := h.cachedNode(nodeCache, fromNodeID)
 	targetNode, err := h.cachedNode(nodeCache, toNode.NodeID)
 	if err != nil {
 		h.appendFailedDiagnosis(results, nodeCache, fromNodeID, "", 0, description, metadata, err.Error())
 		return
 	}
-	targetIP, targetPort, err := resolveChainProbeTarget(targetNode, toNode.Port)
+	targetIP, targetPort, err := resolveChainProbeTarget(fromNode, targetNode, toNode.Port, ipPreference)
 	if err != nil {
 		h.appendFailedDiagnosis(results, nodeCache, fromNodeID, strings.Trim(strings.TrimSpace(targetNode.ServerIP), "[]"), toNode.Port, description, metadata, err.Error())
 		return
@@ -707,11 +734,14 @@ func (h *Handler) appendChainHopDiagnosis(results *[]map[string]interface{}, nod
 	h.appendPathDiagnosis(results, nodeCache, fromNodeID, targetIP, targetPort, description, metadata)
 }
 
-func resolveChainProbeTarget(targetNode *nodeRecord, preferredPort int) (string, int, error) {
+func resolveChainProbeTarget(fromNode, targetNode *nodeRecord, preferredPort int, ipPreference string) (string, int, error) {
 	if targetNode == nil {
 		return "", 0, errors.New("目标节点不存在")
 	}
-	host := strings.Trim(strings.TrimSpace(targetNode.ServerIP), "[]")
+	host, err := selectTunnelDialHost(fromNode, targetNode, ipPreference)
+	if err != nil {
+		host = strings.Trim(strings.TrimSpace(targetNode.ServerIP), "[]")
+	}
 	if host == "" {
 		return "", 0, errors.New("目标节点地址为空")
 	}
@@ -877,6 +907,17 @@ func isNotFoundError(err error) bool {
 	return strings.Contains(msg, "not found") || strings.Contains(msg, "不存在")
 }
 
+func isAlreadyExistsMessage(message string) bool {
+	msg := strings.ToLower(strings.TrimSpace(message))
+	if msg == "" {
+		return false
+	}
+	if strings.Contains(msg, "address already in use") {
+		return false
+	}
+	return strings.Contains(msg, "already exists") || strings.Contains(msg, "已存在")
+}
+
 func buildForwardServiceConfigs(baseName string, forward *forwardRecord, tunnel *tunnelRecord, node *nodeRecord, port int, limiterID *int64, tunnelTLSProtocol bool) []map[string]interface{} {
 	protocols := []string{"tcp", "udp"}
 	services := make([]map[string]interface{}, 0, 2)
@@ -1023,12 +1064,16 @@ func (h *Handler) sendDeleteLimiterConfig(limiterID int64, tunnelID int64) error
 	return nil
 }
 
-func (h *Handler) ensureLimiterOnNode(nodeID int64, limiterID int64, speed int) {
+func (h *Handler) ensureLimiterOnNode(nodeID int64, limiterID int64, speed int) error {
 	rate := float64(speed) / 8.0
 	limitStr := fmt.Sprintf("$ %.1fMB %.1fMB", rate, rate)
 	payload := map[string]interface{}{
 		"name":   strconv.FormatInt(limiterID, 10),
 		"limits": []string{limitStr},
 	}
-	_, _ = h.sendNodeCommand(nodeID, "AddLimiters", payload, false, false)
+	if _, err := h.sendNodeCommand(nodeID, "AddLimiters", payload, false, false); err != nil {
+		return fmt.Errorf("限速规则下发失败: %w", err)
+	}
+
+	return nil
 }

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

@@ -53,3 +53,15 @@ func TestShouldTryLegacySingleService(t *testing.T) {
 		t.Fatalf("DeleteService should not require legacy fallback")
 	}
 }
+
+func TestIsAlreadyExistsMessage(t *testing.T) {
+	if !isAlreadyExistsMessage("service demo already exists") {
+		t.Fatalf("expected already exists message to be tolerated")
+	}
+	if !isAlreadyExistsMessage("服务已存在") {
+		t.Fatalf("expected Chinese already exists message to be tolerated")
+	}
+	if isAlreadyExistsMessage("listen tcp [::]:10001: bind: address already in use") {
+		t.Fatalf("address already in use must not be treated as already exists")
+	}
+}

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

@@ -477,9 +477,14 @@ func (h *Handler) federationRemoteUsageList(w http.ResponseWriter, r *http.Reque
 			response.WriteJSON(w, response.Err(-2, err.Error()))
 			return
 		}
+		forwardPortRows, err := h.repo.ListActiveForwardPortsForNode(nodeID)
+		if err != nil {
+			response.WriteJSON(w, response.Err(-2, err.Error()))
+			return
+		}
 
 		usedSet := make(map[int]struct{})
-		bindings := make([]remoteUsageBindingItem, 0, len(bindingRows))
+		bindings := make([]remoteUsageBindingItem, 0, len(bindingRows)+len(forwardPortRows))
 		for _, b := range bindingRows {
 			bindings = append(bindings, remoteUsageBindingItem{
 				BindingID:       b.ID,
@@ -496,6 +501,29 @@ func (h *Handler) federationRemoteUsageList(w http.ResponseWriter, r *http.Reque
 				usedSet[b.AllocatedPort] = struct{}{}
 			}
 		}
+		for _, fp := range forwardPortRows {
+			bindings = append(bindings, remoteUsageBindingItem{
+				BindingID:       -fp.ForwardID,
+				TunnelID:        fp.TunnelID,
+				TunnelName:      fp.TunnelName,
+				ChainType:       1,
+				HopInx:          0,
+				AllocatedPort:   fp.Port,
+				ResourceKey:     fmt.Sprintf("forward:%d", fp.ForwardID),
+				RemoteBindingID: "",
+				UpdatedTime:     fp.UpdatedTime,
+			})
+			if fp.Port > 0 {
+				usedSet[fp.Port] = struct{}{}
+			}
+		}
+
+		sort.Slice(bindings, func(i, j int) bool {
+			if bindings[i].AllocatedPort == bindings[j].AllocatedPort {
+				return bindings[i].BindingID < bindings[j].BindingID
+			}
+			return bindings[i].AllocatedPort < bindings[j].AllocatedPort
+		})
 
 		usedPorts := make([]int, 0, len(usedSet))
 		for port := range usedSet {
@@ -766,6 +794,37 @@ func (h *Handler) federationTunnelCreate(w http.ResponseWriter, r *http.Request)
 		return
 	}
 
+	usedPorts, err := h.repo.ListUsedPortsOnNode(share.NodeID)
+	if err != nil {
+		response.WriteJSON(w, response.Err(-2, err.Error()))
+		return
+	}
+	for _, port := range usedPorts {
+		if port == req.RemotePort {
+			response.WriteJSON(w, response.Err(403, "Port already in use"))
+			return
+		}
+	}
+
+	runtimeOnPort, err := h.repo.GetActiveForwardPeerShareRuntimeByPort(share.ID, req.RemotePort)
+	if err != nil {
+		response.WriteJSON(w, response.Err(-2, err.Error()))
+		return
+	}
+	if runtimeOnPort != nil {
+		response.WriteJSON(w, response.Err(403, "Port already in use"))
+		return
+	}
+	existsOnNodePort, err := h.repo.ExistsActivePeerShareRuntimeOnNodePort(share.NodeID, req.RemotePort)
+	if err != nil {
+		response.WriteJSON(w, response.Err(-2, err.Error()))
+		return
+	}
+	if existsOnNodePort {
+		response.WriteJSON(w, response.Err(403, "Port already in use"))
+		return
+	}
+
 	now := time.Now().UnixMilli()
 	tunnelID, err := h.repo.CreateFederationTunnel(
 		fmt.Sprintf("Share-%d-Port-%d", share.ID, req.RemotePort),
@@ -780,6 +839,30 @@ func (h *Handler) federationTunnelCreate(w http.ResponseWriter, r *http.Request)
 		return
 	}
 
+	runtime := &repo.PeerShareRuntime{
+		ShareID:       share.ID,
+		NodeID:        share.NodeID,
+		ReservationID: randomToken(24),
+		ResourceKey:   fmt.Sprintf("federation-forward-%d-%d-%d", share.ID, tunnelID, req.RemotePort),
+		BindingID:     "",
+		Role:          "forward",
+		ChainName:     "",
+		ServiceName:   "",
+		Protocol:      defaultString(req.Protocol, "tcp"),
+		Strategy:      "fifo",
+		Port:          req.RemotePort,
+		Target:        strings.TrimSpace(req.Target),
+		Applied:       0,
+		Status:        1,
+		CreatedTime:   now,
+		UpdatedTime:   now,
+	}
+	if err := h.repo.CreatePeerShareRuntime(runtime); err != nil {
+		_ = h.deleteTunnelByID(tunnelID)
+		response.WriteJSON(w, response.Err(-2, err.Error()))
+		return
+	}
+
 	h.wsServer.SendCommand(share.NodeID, "reload", nil, time.Second*5)
 
 	response.WriteJSON(w, response.OK(map[string]interface{}{
@@ -1211,9 +1294,182 @@ func (h *Handler) federationRuntimeCommand(w http.ResponseWriter, r *http.Reques
 		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)
+	}
 	response.WriteJSON(w, response.OK(res))
 }
 
+type federationForwardServiceBinding struct {
+	Name string
+	Port int
+}
+
+func extractFederationServiceEntries(data interface{}) []map[string]interface{} {
+	if data == nil {
+		return nil
+	}
+
+	if entries := asMapSlice(data); len(entries) > 0 {
+		return entries
+	}
+
+	dataMap, ok := data.(map[string]interface{})
+	if !ok {
+		return nil
+	}
+
+	if entries := asMapSlice(dataMap["services"]); len(entries) > 0 {
+		return entries
+	}
+
+	return nil
+}
+
+func parseFederationForwardServiceBindings(data interface{}) []federationForwardServiceBinding {
+	serviceList := extractFederationServiceEntries(data)
+	bindings := make([]federationForwardServiceBinding, 0, len(serviceList))
+	for _, svcMap := range serviceList {
+		name := normalizeForwardRuntimeServiceName(asString(svcMap["name"]))
+		if name == "" {
+			continue
+		}
+		if _, _, _, ok := parseFlowServiceIDs(name); !ok {
+			continue
+		}
+		addr := strings.TrimSpace(asString(svcMap["addr"]))
+		if addr == "" {
+			continue
+		}
+		_, portStr, err := net.SplitHostPort(addr)
+		if err != nil {
+			continue
+		}
+		port, err := strconv.Atoi(portStr)
+		if err != nil || port <= 0 {
+			continue
+		}
+		bindings = append(bindings, federationForwardServiceBinding{Name: name, Port: port})
+	}
+	return bindings
+}
+
+func parseFederationForwardServiceNamesForRelease(data interface{}) []string {
+	names := make(map[string]struct{})
+	appendName := func(raw string) {
+		name := normalizeForwardRuntimeServiceName(raw)
+		if name == "" {
+			return
+		}
+		if _, _, _, ok := parseFlowServiceIDs(name); !ok {
+			return
+		}
+		names[name] = struct{}{}
+	}
+
+	for _, svcMap := range extractFederationServiceEntries(data) {
+		appendName(asString(svcMap["name"]))
+	}
+
+	if dataMap, ok := data.(map[string]interface{}); ok {
+		for _, item := range asAnySlice(dataMap["services"]) {
+			appendName(asString(item))
+		}
+	}
+
+	for _, item := range asAnySlice(data) {
+		appendName(asString(item))
+	}
+
+	if len(names) == 0 {
+		return nil
+	}
+
+	out := make([]string, 0, len(names))
+	for name := range names {
+		out = append(out, name)
+	}
+	sort.Strings(out)
+	return out
+}
+
+func (h *Handler) bindPeerShareForwardRuntimeServices(share *repo.PeerShare, data interface{}) {
+	if h == nil || h.repo == nil || share == nil {
+		return
+	}
+	bindings := parseFederationForwardServiceBindings(data)
+	if len(bindings) == 0 {
+		return
+	}
+
+	now := time.Now().UnixMilli()
+	for _, binding := range bindings {
+		runtime, err := h.repo.GetActiveForwardPeerShareRuntimeByPort(share.ID, binding.Port)
+		if err != nil {
+			continue
+		}
+		if runtime == nil {
+			runtime, err = h.repo.GetActiveForwardPeerShareRuntimeByServiceName(share.ID, binding.Name)
+			if err != nil {
+				continue
+			}
+		}
+		if runtime == nil {
+			_ = h.repo.CreatePeerShareRuntime(&repo.PeerShareRuntime{
+				ShareID:       share.ID,
+				NodeID:        share.NodeID,
+				ReservationID: randomToken(24),
+				ResourceKey:   fmt.Sprintf("forward-runtime:%d:%s:%d:%s", share.ID, binding.Name, binding.Port, randomToken(8)),
+				BindingID:     "",
+				Role:          "forward",
+				ChainName:     "",
+				ServiceName:   binding.Name,
+				Protocol:      "tcp",
+				Strategy:      "fifo",
+				Port:          binding.Port,
+				Target:        "",
+				Applied:       1,
+				Status:        1,
+				CreatedTime:   now,
+				UpdatedTime:   now,
+			})
+			continue
+		}
+		if runtime.ServiceName == binding.Name && runtime.Applied == 1 && runtime.Port == binding.Port && runtime.Status == 1 {
+			continue
+		}
+		runtime.ServiceName = binding.Name
+		runtime.Port = binding.Port
+		runtime.Applied = 1
+		runtime.Status = 1
+		runtime.UpdatedTime = now
+		if strings.TrimSpace(runtime.Protocol) == "" {
+			runtime.Protocol = "tcp"
+		}
+		if strings.TrimSpace(runtime.Strategy) == "" {
+			runtime.Strategy = "fifo"
+		}
+		_ = h.repo.UpdatePeerShareRuntime(runtime)
+	}
+}
+
+func (h *Handler) releasePeerShareForwardRuntimeServices(share *repo.PeerShare, data interface{}) {
+	if h == nil || h.repo == nil || share == nil {
+		return
+	}
+	names := parseFederationForwardServiceNamesForRelease(data)
+	if len(names) == 0 {
+		return
+	}
+
+	now := time.Now().UnixMilli()
+	for _, name := range names {
+		_ = h.repo.MarkForwardPeerShareRuntimeReleasedByServiceName(share.ID, name, now)
+	}
+}
+
 func isFederationRuntimeCommandAllowed(commandType string) bool {
 	switch strings.ToLower(strings.TrimSpace(commandType)) {
 	case "addservice", "updateservice", "deleteservice", "pauseservice", "resumeservice", "addchains", "deletechains", "addlimiters", "deletelimiters", "tcpping", "reload":
@@ -1236,36 +1492,26 @@ func validateFederationCommandPorts(share *repo.PeerShare, data interface{}) err
 	if share == nil || (share.PortRangeStart <= 0 && share.PortRangeEnd <= 0) {
 		return nil
 	}
-	dataMap, ok := data.(map[string]interface{})
-	if !ok {
+
+	serviceList := extractFederationServiceEntries(data)
+	if len(serviceList) == 0 {
 		return nil
 	}
-
-	if services, ok := dataMap["services"]; ok {
-		serviceList, ok := services.([]interface{})
-		if !ok {
-			return fmt.Errorf("invalid services format")
+	for _, svcMap := range serviceList {
+		addr := asString(svcMap["addr"])
+		if addr == "" {
+			continue
 		}
-		for _, svc := range serviceList {
-			svcMap, ok := svc.(map[string]interface{})
-			if !ok {
-				return fmt.Errorf("invalid service entry format")
-			}
-			addr, ok := svcMap["addr"].(string)
-			if !ok || addr == "" {
-				continue
-			}
-			_, portStr, err := net.SplitHostPort(addr)
-			if err != nil {
-				return fmt.Errorf("invalid service address: %s", addr)
-			}
-			port, err := strconv.Atoi(portStr)
-			if err != nil || port <= 0 {
-				return fmt.Errorf("invalid port in service address: %s", addr)
-			}
-			if port < share.PortRangeStart || port > share.PortRangeEnd {
-				return fmt.Errorf("port %d out of allowed range %d-%d", port, share.PortRangeStart, share.PortRangeEnd)
-			}
+		_, portStr, err := net.SplitHostPort(addr)
+		if err != nil {
+			return fmt.Errorf("invalid service address: %s", addr)
+		}
+		port, err := strconv.Atoi(portStr)
+		if err != nil || port <= 0 {
+			return fmt.Errorf("invalid port in service address: %s", addr)
+		}
+		if port < share.PortRangeStart || port > share.PortRangeEnd {
+			return fmt.Errorf("port %d out of allowed range %d-%d", port, share.PortRangeStart, share.PortRangeEnd)
 		}
 	}
 

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

@@ -414,6 +414,445 @@ func TestFederationShareResetFlow(t *testing.T) {
 	}
 }
 
+func TestFederationTunnelCreateCreatesPeerShareRuntime(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")
+	now := time.Now().UnixMilli()
+
+	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(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, "federation-forward-node", "federation-forward-secret", "10.90.80.70", "10.90.80.70", "", "24000-24020", "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", 0, 0, "", "", "").Error; err != nil {
+		t.Fatalf("insert node: %v", err)
+	}
+	nodeID := mustLastInsertID(t, r, "federation-forward-node")
+
+	if err := r.CreatePeerShare(&repo.PeerShare{
+		Name:           "federation-forward-share",
+		NodeID:         nodeID,
+		Token:          "federation-forward-token",
+		MaxBandwidth:   0,
+		CurrentFlow:    0,
+		PortRangeStart: 24000,
+		PortRangeEnd:   24020,
+		IsActive:       1,
+		CreatedTime:    now,
+		UpdatedTime:    now,
+	}); err != nil {
+		t.Fatalf("create share: %v", err)
+	}
+	share, err := r.GetPeerShareByToken("federation-forward-token")
+	if err != nil || share == nil {
+		t.Fatalf("load share: %v", err)
+	}
+
+	body, err := json.Marshal(federationTunnelRequest{
+		Protocol:   "tcp",
+		RemotePort: 24001,
+		Target:     "1.1.1.1:443",
+	})
+	if err != nil {
+		t.Fatalf("marshal request: %v", err)
+	}
+
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/federation/tunnel/create", bytes.NewReader(body))
+	req.Header.Set("Authorization", "Bearer "+share.Token)
+	req.Header.Set("Content-Type", "application/json")
+	res := httptest.NewRecorder()
+
+	h.federationTunnelCreate(res, req)
+
+	if res.Code != http.StatusOK {
+		t.Fatalf("expected status %d, got %d", http.StatusOK, res.Code)
+	}
+
+	var payload response.R
+	if err := json.NewDecoder(res.Body).Decode(&payload); err != nil {
+		t.Fatalf("decode response: %v", err)
+	}
+	if payload.Code != 0 {
+		t.Fatalf("expected response code 0, got %d (%s)", payload.Code, payload.Msg)
+	}
+
+	runtimeCount := mustQueryInt(t, r, `SELECT COUNT(1) FROM peer_share_runtime WHERE share_id = ? AND port = ? AND status = 1`, share.ID, 24001)
+	if runtimeCount != 1 {
+		t.Fatalf("expected 1 runtime row for new federation forward tunnel, got %d", runtimeCount)
+	}
+}
+
+func TestFederationTunnelCreateRejectsOccupiedPort(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")
+	now := time.Now().UnixMilli()
+
+	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(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, "federation-port-check-node", "federation-port-check-secret", "10.91.80.70", "10.91.80.70", "", "24100-24120", "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", 0, 0, "", "", "").Error; err != nil {
+		t.Fatalf("insert node: %v", err)
+	}
+	nodeID := mustLastInsertID(t, r, "federation-port-check-node")
+
+	if err := r.CreatePeerShare(&repo.PeerShare{
+		Name:           "federation-port-check-share",
+		NodeID:         nodeID,
+		Token:          "federation-port-check-token",
+		MaxBandwidth:   0,
+		CurrentFlow:    0,
+		PortRangeStart: 24100,
+		PortRangeEnd:   24120,
+		IsActive:       1,
+		CreatedTime:    now,
+		UpdatedTime:    now,
+	}); err != nil {
+		t.Fatalf("create share: %v", err)
+	}
+
+	create := func() response.R {
+		body, err := json.Marshal(federationTunnelRequest{Protocol: "tcp", RemotePort: 24101, Target: "1.1.1.1:443"})
+		if err != nil {
+			t.Fatalf("marshal request: %v", err)
+		}
+		req := httptest.NewRequest(http.MethodPost, "/api/v1/federation/tunnel/create", bytes.NewReader(body))
+		req.Header.Set("Authorization", "Bearer federation-port-check-token")
+		req.Header.Set("Content-Type", "application/json")
+		res := httptest.NewRecorder()
+		h.federationTunnelCreate(res, req)
+		if res.Code != http.StatusOK {
+			t.Fatalf("expected status %d, got %d", http.StatusOK, res.Code)
+		}
+		var payload response.R
+		if err := json.NewDecoder(res.Body).Decode(&payload); err != nil {
+			t.Fatalf("decode response: %v", err)
+		}
+		return payload
+	}
+
+	first := create()
+	if first.Code != 0 {
+		t.Fatalf("expected first create success, got %d (%s)", first.Code, first.Msg)
+	}
+
+	second := create()
+	if second.Code != 403 {
+		t.Fatalf("expected second create to be rejected with 403, got %d (%s)", second.Code, second.Msg)
+	}
+	if second.Msg != "Port already in use" {
+		t.Fatalf("expected occupied port message, got %q", second.Msg)
+	}
+}
+
+func TestDeleteTunnelReleasesFederationForwardRuntimeByPort(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")
+	now := time.Now().UnixMilli()
+
+	if err := r.CreatePeerShare(&repo.PeerShare{
+		Name:           "delete-forward-share",
+		NodeID:         1,
+		Token:          "delete-forward-token",
+		MaxBandwidth:   0,
+		CurrentFlow:    0,
+		PortRangeStart: 25000,
+		PortRangeEnd:   25020,
+		IsActive:       1,
+		CreatedTime:    now,
+		UpdatedTime:    now,
+	}); err != nil {
+		t.Fatalf("create share: %v", err)
+	}
+	share, err := r.GetPeerShareByToken("delete-forward-token")
+	if err != nil || share == nil {
+		t.Fatalf("load share: %v", err)
+	}
+
+	tunnelName := fmt.Sprintf("Share-%d-Port-%d", share.ID, 25001)
+	if err := r.DB().Exec(`
+		INSERT INTO tunnel(id, name, traffic_ratio, type, protocol, flow, created_time, updated_time, status, in_ip, inx)
+		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, 1, tunnelName, 1.0, 1, "tcp", 1, now, now, 1, nil, 0).Error; err != nil {
+		t.Fatalf("insert tunnel: %v", err)
+	}
+
+	if err := r.DB().Exec(`
+		INSERT INTO peer_share_runtime(share_id, node_id, reservation_id, resource_key, binding_id, role, chain_name, service_name, protocol, strategy, port, target, applied, status, created_time, updated_time)
+		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, share.ID, share.NodeID, "del-r1", "del-rk1", "", "forward", "", "20_2_10", "tcp", "fifo", 25001, "", 1, 1, now, now).Error; err != nil {
+		t.Fatalf("insert runtime: %v", err)
+	}
+
+	if err := h.deleteTunnelByID(1); err != nil {
+		t.Fatalf("delete tunnel: %v", err)
+	}
+
+	activeCount := mustQueryInt(t, r, `SELECT COUNT(1) FROM peer_share_runtime WHERE share_id = ? AND port = ? AND status = 1`, share.ID, 25001)
+	if activeCount != 0 {
+		t.Fatalf("expected runtime released after tunnel delete, active rows=%d", activeCount)
+	}
+}
+
+func TestBindPeerShareForwardRuntimeServicesOnlyBindsForwardRole(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")
+	now := time.Now().UnixMilli()
+
+	if err := r.CreatePeerShare(&repo.PeerShare{
+		Name:           "bind-forward-role-share",
+		NodeID:         1,
+		Token:          "bind-forward-role-token",
+		MaxBandwidth:   0,
+		CurrentFlow:    0,
+		PortRangeStart: 26000,
+		PortRangeEnd:   26020,
+		IsActive:       1,
+		CreatedTime:    now,
+		UpdatedTime:    now,
+	}); err != nil {
+		t.Fatalf("create share: %v", err)
+	}
+	share, err := r.GetPeerShareByToken("bind-forward-role-token")
+	if err != nil || share == nil {
+		t.Fatalf("load share: %v", err)
+	}
+
+	if err := r.DB().Exec(`
+		INSERT INTO peer_share_runtime(id, share_id, node_id, reservation_id, resource_key, binding_id, role, chain_name, service_name, protocol, strategy, port, target, applied, status, created_time, updated_time)
+		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?),
+		      (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`,
+		1, share.ID, share.NodeID, "bind-r1", "bind-rk1", "", "forward", "", "", "tcp", "fifo", 26001, "", 0, 1, now, now,
+		2, share.ID, share.NodeID, "bind-r2", "bind-rk2", "", "middle", "", "", "tcp", "round", 26002, "", 0, 1, now, now,
+	).Error; err != nil {
+		t.Fatalf("insert runtimes: %v", err)
+	}
+
+	h.bindPeerShareForwardRuntimeServices(share, map[string]interface{}{
+		"services": []interface{}{
+			map[string]interface{}{"name": "77_2_10_tcp", "addr": "[::]:26001"},
+			map[string]interface{}{"name": "88_2_10_tcp", "addr": "[::]:26002"},
+		},
+	})
+
+	forwardServiceName := ""
+	middleServiceName := ""
+	if err := r.DB().Raw(`SELECT service_name FROM peer_share_runtime WHERE id = 1`).Scan(&forwardServiceName).Error; err != nil {
+		t.Fatalf("load forward runtime service name: %v", err)
+	}
+	if err := r.DB().Raw(`SELECT service_name FROM peer_share_runtime WHERE id = 2`).Scan(&middleServiceName).Error; err != nil {
+		t.Fatalf("load middle runtime service name: %v", err)
+	}
+
+	if forwardServiceName != "77_2_10" {
+		t.Fatalf("expected forward runtime service name bound, got %q", forwardServiceName)
+	}
+	if middleServiceName != "" {
+		t.Fatalf("expected non-forward runtime unchanged, got %q", middleServiceName)
+	}
+}
+
+func TestBindPeerShareForwardRuntimeServicesAcceptsTopLevelServiceArray(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")
+	now := time.Now().UnixMilli()
+
+	if err := r.CreatePeerShare(&repo.PeerShare{
+		Name:           "bind-array-share",
+		NodeID:         1,
+		Token:          "bind-array-token",
+		MaxBandwidth:   0,
+		CurrentFlow:    0,
+		PortRangeStart: 26100,
+		PortRangeEnd:   26120,
+		IsActive:       1,
+		CreatedTime:    now,
+		UpdatedTime:    now,
+	}); err != nil {
+		t.Fatalf("create share: %v", err)
+	}
+	share, err := r.GetPeerShareByToken("bind-array-token")
+	if err != nil || share == nil {
+		t.Fatalf("load share: %v", err)
+	}
+
+	if err := r.DB().Exec(`
+		INSERT INTO peer_share_runtime(id, share_id, node_id, reservation_id, resource_key, binding_id, role, chain_name, service_name, protocol, strategy, port, target, applied, status, created_time, updated_time)
+		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`,
+		1, share.ID, share.NodeID, "bind-array-r1", "bind-array-rk1", "", "forward", "", "", "tcp", "fifo", 26101, "", 0, 1, now, now,
+	).Error; err != nil {
+		t.Fatalf("insert runtime: %v", err)
+	}
+
+	h.bindPeerShareForwardRuntimeServices(share, []interface{}{
+		map[string]interface{}{"name": "99_2_10_tcp", "addr": "[::]:26101"},
+		map[string]interface{}{"name": "99_2_10_udp", "addr": "[::]:26101"},
+	})
+
+	forwardServiceName := ""
+	if err := r.DB().Raw(`SELECT service_name FROM peer_share_runtime WHERE id = 1`).Scan(&forwardServiceName).Error; err != nil {
+		t.Fatalf("load forward runtime service name: %v", err)
+	}
+	if forwardServiceName != "99_2_10" {
+		t.Fatalf("expected forward runtime service name bound from top-level array, got %q", forwardServiceName)
+	}
+}
+
+func TestBindPeerShareForwardRuntimeServicesCreatesRuntimeWhenMissing(t *testing.T) {
+	r, err := repo.Open(filepath.Join(t.TempDir(), "panel-bind-create-runtime.db"))
+	if err != nil {
+		t.Fatalf("open sqlite: %v", err)
+	}
+	t.Cleanup(func() { _ = r.Close() })
+
+	h := New(r, "test-jwt-secret")
+	now := time.Now().UnixMilli()
+
+	if err := r.CreatePeerShare(&repo.PeerShare{
+		Name:           "bind-create-runtime-share",
+		NodeID:         1,
+		Token:          "bind-create-runtime-token",
+		MaxBandwidth:   0,
+		CurrentFlow:    0,
+		PortRangeStart: 26300,
+		PortRangeEnd:   26320,
+		IsActive:       1,
+		CreatedTime:    now,
+		UpdatedTime:    now,
+	}); err != nil {
+		t.Fatalf("create share: %v", err)
+	}
+	share, err := r.GetPeerShareByToken("bind-create-runtime-token")
+	if err != nil || share == nil {
+		t.Fatalf("load share: %v", err)
+	}
+
+	h.bindPeerShareForwardRuntimeServices(share, map[string]interface{}{
+		"services": []interface{}{
+			map[string]interface{}{"name": "55_2_10_tcp", "addr": "[::]:26301"},
+		},
+	})
+
+	var count int64
+	if err := r.DB().Raw(`SELECT COUNT(1) FROM peer_share_runtime WHERE share_id = ? AND role = ? AND status = 1`, share.ID, "forward").Scan(&count).Error; err != nil {
+		t.Fatalf("query runtime count: %v", err)
+	}
+	if count != 1 {
+		t.Fatalf("expected 1 active forward runtime row, got %d", count)
+	}
+
+	var serviceName string
+	var port int
+	var applied int
+	if err := r.DB().Raw(`SELECT service_name, port, applied FROM peer_share_runtime WHERE share_id = ? AND role = ? ORDER BY id DESC LIMIT 1`, share.ID, "forward").Row().Scan(&serviceName, &port, &applied); err != nil {
+		t.Fatalf("query created runtime: %v", err)
+	}
+	if serviceName != "55_2_10" {
+		t.Fatalf("expected service_name=55_2_10, got %q", serviceName)
+	}
+	if port != 26301 {
+		t.Fatalf("expected port=26301, got %d", port)
+	}
+	if applied != 1 {
+		t.Fatalf("expected applied=1, got %d", applied)
+	}
+}
+
+func TestReleasePeerShareForwardRuntimeServicesMarksRuntimeReleased(t *testing.T) {
+	r, err := repo.Open(filepath.Join(t.TempDir(), "panel-release-runtime.db"))
+	if err != nil {
+		t.Fatalf("open sqlite: %v", err)
+	}
+	t.Cleanup(func() { _ = r.Close() })
+
+	h := New(r, "test-jwt-secret")
+	now := time.Now().UnixMilli()
+
+	if err := r.CreatePeerShare(&repo.PeerShare{
+		Name:           "release-runtime-share",
+		NodeID:         1,
+		Token:          "release-runtime-token",
+		MaxBandwidth:   0,
+		CurrentFlow:    0,
+		PortRangeStart: 26400,
+		PortRangeEnd:   26420,
+		IsActive:       1,
+		CreatedTime:    now,
+		UpdatedTime:    now,
+	}); err != nil {
+		t.Fatalf("create share: %v", err)
+	}
+	share, err := r.GetPeerShareByToken("release-runtime-token")
+	if err != nil || share == nil {
+		t.Fatalf("load share: %v", err)
+	}
+
+	if err := r.DB().Exec(`
+		INSERT INTO peer_share_runtime(share_id, node_id, reservation_id, resource_key, binding_id, role, chain_name, service_name, protocol, strategy, port, target, applied, status, created_time, updated_time)
+		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, share.ID, share.NodeID, "release-r1", "release-rk1", "", "forward", "", "77_2_10", "tcp", "fifo", 26401, "", 1, 1, now, now).Error; err != nil {
+		t.Fatalf("insert runtime: %v", err)
+	}
+
+	h.releasePeerShareForwardRuntimeServices(share, map[string]interface{}{
+		"services": []interface{}{"77_2_10_tcp"},
+	})
+
+	var status int
+	var applied int
+	var serviceName string
+	if err := r.DB().Raw(`SELECT status, applied, service_name FROM peer_share_runtime WHERE share_id = ? AND role = ? ORDER BY id DESC LIMIT 1`, share.ID, "forward").Row().Scan(&status, &applied, &serviceName); err != nil {
+		t.Fatalf("query released runtime: %v", err)
+	}
+	if status != 0 {
+		t.Fatalf("expected status=0 after release, got %d", status)
+	}
+	if applied != 0 {
+		t.Fatalf("expected applied=0 after release, got %d", applied)
+	}
+	if serviceName != "" {
+		t.Fatalf("expected service_name cleared after release, got %q", serviceName)
+	}
+}
+
+func TestValidateFederationCommandPortsAcceptsTopLevelServiceArray(t *testing.T) {
+	share := &repo.PeerShare{
+		PortRangeStart: 26200,
+		PortRangeEnd:   26210,
+	}
+	err := validateFederationCommandPorts(share, []interface{}{
+		map[string]interface{}{"name": "11_2_10_tcp", "addr": "[::]:26201"},
+		map[string]interface{}{"name": "11_2_10_udp", "addr": "[::]:26201"},
+	})
+	if err != nil {
+		t.Fatalf("expected top-level service array to pass port validation, got: %v", err)
+	}
+}
+
 func TestFederationRemoteUsageList(t *testing.T) {
 	r, err := repo.Open(filepath.Join(t.TempDir(), "panel.db"))
 	if err != nil {
@@ -502,6 +941,110 @@ func TestFederationRemoteUsageList(t *testing.T) {
 	}
 }
 
+func TestFederationRemoteUsageListIncludesForwardPorts(t *testing.T) {
+	r, err := repo.Open(filepath.Join(t.TempDir(), "panel-forward-usage.db"))
+	if err != nil {
+		t.Fatalf("open sqlite: %v", err)
+	}
+	t.Cleanup(func() { _ = r.Close() })
+
+	h := New(r, "test-jwt-secret")
+	now := time.Now().UnixMilli()
+
+	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(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, "forward-usage-remote-node", "forward-usage-secret", "10.60.70.80", "10.60.70.80", "", "33000-33010", "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", 0, 1, "", "", `{"shareId":99,"maxBandwidth":0,"currentFlow":0,"portRangeStart":33000,"portRangeEnd":33010}`).Error; err != nil {
+		t.Fatalf("insert remote node: %v", err)
+	}
+
+	var nodeID int64
+	if err := r.DB().Raw(`SELECT id FROM node WHERE name = ? ORDER BY id DESC LIMIT 1`, "forward-usage-remote-node").Row().Scan(&nodeID); err != nil {
+		t.Fatalf("query node id: %v", err)
+	}
+
+	if err := r.DB().Exec(`
+		INSERT INTO tunnel(name, type, protocol, flow, created_time, updated_time, status, in_ip, inx)
+		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, "forward-usage-tunnel", 1, "tls", 1, now, now, 1, "", 0).Error; err != nil {
+		t.Fatalf("insert tunnel: %v", err)
+	}
+
+	var tunnelID int64
+	if err := r.DB().Raw(`SELECT id FROM tunnel WHERE name = ? ORDER BY id DESC LIMIT 1`, "forward-usage-tunnel").Row().Scan(&tunnelID); err != nil {
+		t.Fatalf("query tunnel id: %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(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, 1, "tester", "forward-usage-item", tunnelID, "1.1.1.1:443", "fifo", 0, 0, now, now, 1, 0).Error; err != nil {
+		t.Fatalf("insert forward: %v", err)
+	}
+
+	var forwardID int64
+	if err := r.DB().Raw(`SELECT id FROM forward WHERE name = ? ORDER BY id DESC LIMIT 1`, "forward-usage-item").Row().Scan(&forwardID); err != nil {
+		t.Fatalf("query forward id: %v", err)
+	}
+
+	if err := r.DB().Exec(`INSERT INTO forward_port(forward_id, node_id, port) VALUES(?, ?, ?)`, forwardID, nodeID, 33001).Error; err != nil {
+		t.Fatalf("insert forward_port: %v", err)
+	}
+
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/federation/share/remote-usage/list", nil)
+	res := httptest.NewRecorder()
+	h.federationRemoteUsageList(res, req)
+
+	if res.Code != http.StatusOK {
+		t.Fatalf("expected status %d, got %d", http.StatusOK, res.Code)
+	}
+
+	var payload response.R
+	if err := json.NewDecoder(res.Body).Decode(&payload); err != nil {
+		t.Fatalf("decode response: %v", err)
+	}
+	if payload.Code != 0 {
+		t.Fatalf("expected response code 0, got %d (%s)", payload.Code, payload.Msg)
+	}
+
+	rows, ok := payload.Data.([]interface{})
+	if !ok || len(rows) == 0 {
+		t.Fatalf("expected non-empty usage list, got %T", payload.Data)
+	}
+
+	first, ok := rows[0].(map[string]interface{})
+	if !ok {
+		t.Fatalf("expected usage row map, got %T", rows[0])
+	}
+
+	usedPortsRaw, ok := first["usedPorts"].([]interface{})
+	if !ok {
+		t.Fatalf("expected usedPorts array, got %T", first["usedPorts"])
+	}
+	if len(usedPortsRaw) != 1 || int(usedPortsRaw[0].(float64)) != 33001 {
+		t.Fatalf("expected usedPorts [33001], got %v", usedPortsRaw)
+	}
+
+	bindingsRaw, ok := first["bindings"].([]interface{})
+	if !ok {
+		t.Fatalf("expected bindings array, got %T", first["bindings"])
+	}
+	if len(bindingsRaw) != 1 {
+		t.Fatalf("expected 1 binding row from forward usage, got %d", len(bindingsRaw))
+	}
+
+	binding, ok := bindingsRaw[0].(map[string]interface{})
+	if !ok {
+		t.Fatalf("expected binding row object, got %T", bindingsRaw[0])
+	}
+	if int(binding["allocatedPort"].(float64)) != 33001 {
+		t.Fatalf("expected allocatedPort=33001, got %v", binding["allocatedPort"])
+	}
+	if int(binding["chainType"].(float64)) != 1 {
+		t.Fatalf("expected chainType=1 for forward usage row, got %v", binding["chainType"])
+	}
+}
+
 func TestAuthPeerAllowedIPs(t *testing.T) {
 	r, err := repo.Open(filepath.Join(t.TempDir(), "panel.db"))
 	if err != nil {

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

@@ -2,9 +2,12 @@ package handler
 
 import (
 	"encoding/json"
+	"log"
 	"strconv"
 	"strings"
 	"time"
+
+	"go-backend/internal/store/model"
 )
 
 const bytesPerGB int64 = 1024 * 1024 * 1024
@@ -30,7 +33,7 @@ type namedConfigItem struct {
 	Name string `json:"name"`
 }
 
-func (h *Handler) processFlowItem(item flowItem) {
+func (h *Handler) processFlowItem(nodeID int64, item flowItem) {
 	serviceName := strings.TrimSpace(item.N)
 	if serviceName == "" || serviceName == "web_api" {
 		return
@@ -40,6 +43,7 @@ func (h *Handler) processFlowItem(item flowItem) {
 	if ok {
 		inFlow, outFlow := h.scaleFlowByTunnel(forwardID, item.D, item.U)
 		_ = h.repo.AddFlow(forwardID, userID, userTunnelID, inFlow, outFlow)
+		h.processPeerShareFlowFromForward(forwardID, nodeID, serviceName, item)
 
 		if userTunnelID > 0 {
 			h.enforceFlowPolicies(userID, userTunnelID)
@@ -87,6 +91,45 @@ func parsePeerShareRuntimeServiceID(serviceName string) (int64, bool) {
 	return runtimeID, true
 }
 
+func parsePeerShareInfoFromFederationTunnelName(tunnelName string) (int64, int, bool) {
+	tunnelName = strings.TrimSpace(tunnelName)
+	if !strings.HasPrefix(tunnelName, "Share-") {
+		return 0, 0, false
+	}
+	raw := strings.TrimPrefix(tunnelName, "Share-")
+	idx := strings.Index(raw, "-Port-")
+	if idx <= 0 {
+		return 0, 0, false
+	}
+	shareID, err := strconv.ParseInt(raw[:idx], 10, 64)
+	if err != nil || shareID <= 0 {
+		return 0, 0, false
+	}
+	portValue := strings.TrimSpace(raw[idx+len("-Port-"):])
+	port, err := strconv.Atoi(portValue)
+	if err != nil || port <= 0 {
+		return 0, 0, false
+	}
+	return shareID, port, true
+}
+
+func parsePeerShareIDFromFederationTunnelName(tunnelName string) (int64, bool) {
+	tunnelName = strings.TrimSpace(tunnelName)
+	if !strings.HasPrefix(tunnelName, "Share-") {
+		return 0, false
+	}
+	raw := strings.TrimPrefix(tunnelName, "Share-")
+	idx := strings.Index(raw, "-Port-")
+	if idx <= 0 {
+		return 0, false
+	}
+	shareID, err := strconv.ParseInt(raw[:idx], 10, 64)
+	if err != nil || shareID <= 0 {
+		return 0, false
+	}
+	return shareID, true
+}
+
 func (h *Handler) processPeerShareFlow(runtimeID int64, item flowItem) {
 	if h == nil || h.repo == nil || runtimeID <= 0 {
 		return
@@ -113,6 +156,121 @@ func (h *Handler) processPeerShareFlow(runtimeID int64, item flowItem) {
 	h.enforcePeerShareFlowLimit(share.ID)
 }
 
+func (h *Handler) processPeerShareFlowFromForward(forwardID int64, nodeID int64, serviceName string, item flowItem) {
+	if h == nil || h.repo == nil || forwardID <= 0 {
+		return
+	}
+
+	delta := item.D + item.U
+	if delta <= 0 {
+		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
+	}
+	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 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 {
+	name := strings.TrimSpace(serviceName)
+	if strings.HasSuffix(name, "_tcp") {
+		return strings.TrimSuffix(name, "_tcp")
+	}
+	if strings.HasSuffix(name, "_udp") {
+		return strings.TrimSuffix(name, "_udp")
+	}
+	return name
+}
+
+func (h *Handler) processPeerShareFlowByServiceName(nodeID int64, serviceName string, item flowItem) {
+	if h == nil || h.repo == nil || strings.TrimSpace(serviceName) == "" {
+		return
+	}
+
+	delta := item.D + item.U
+	if delta <= 0 {
+		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 {
+			return
+		}
+		if len(runtimes) == 0 && normalized != serviceName {
+			runtimes, err = h.repo.ListActiveForwardPeerShareRuntimesByNodeAndServiceName(nodeID, serviceName)
+			if err != nil {
+				return
+			}
+		}
+	}
+
+	// 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)
+	}
+}
+
 func (h *Handler) enforcePeerShareFlowLimit(shareID int64) {
 	if h == nil || h.repo == nil || shareID <= 0 {
 		return
@@ -271,15 +429,46 @@ func (h *Handler) cleanNodeConfigs(nodeID int64, rawConfig string) {
 }
 
 func (h *Handler) cleanOrphanedServices(nodeID int64, services []namedConfigItem) {
+	runtimeServiceNames, err := h.repo.ListActiveForwardPeerShareRuntimeServiceNamesByNode(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
+	}
+	runtimeServiceSet := make(map[string]struct{}, len(runtimeServiceNames))
+	for _, serviceName := range runtimeServiceNames {
+		serviceName = strings.TrimSpace(serviceName)
+		if serviceName == "" {
+			continue
+		}
+		runtimeServiceSet[serviceName] = struct{}{}
+	}
+
 	for _, item := range services {
 		name := strings.TrimSpace(item.Name)
 		if name == "" || name == "web_api" {
 			continue
 		}
+		if strings.HasPrefix(name, "fed_svc_") {
+			continue
+		}
+		normalizedName := normalizeForwardRuntimeServiceName(name)
+		if _, ok := runtimeServiceSet[normalizedName]; ok {
+			continue
+		}
+		if _, ok := runtimeServiceSet[name]; ok {
+			continue
+		}
 
 		parts := strings.Split(name, "_")
 		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
@@ -299,6 +488,9 @@ 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
 			}

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

@@ -2,6 +2,7 @@ package handler
 
 import (
 	"path/filepath"
+	"strconv"
 	"testing"
 	"time"
 
@@ -43,7 +44,7 @@ func TestProcessFlowItemTracksPeerShareFlowAndEnforcesLimit(t *testing.T) {
 	}
 
 	h := &Handler{repo: r}
-	h.processFlowItem(flowItem{N: "fed_svc_17", U: 1200, D: 900})
+	h.processFlowItem(1, flowItem{N: "fed_svc_17", U: 1200, D: 900})
 
 	updatedShare, err := r.GetPeerShare(share.ID)
 	if err != nil || updatedShare == nil {
@@ -61,3 +62,345 @@ func TestProcessFlowItemTracksPeerShareFlowAndEnforcesLimit(t *testing.T) {
 		t.Fatalf("expected runtime status=0 after limit enforcement, got %d", runtime.Status)
 	}
 }
+
+func TestProcessFlowItemTracksPeerShareFlowForFederationPortForward(t *testing.T) {
+	r, err := repo.Open(filepath.Join(t.TempDir(), "panel-forward.db"))
+	if err != nil {
+		t.Fatalf("open repo: %v", err)
+	}
+	defer r.Close()
+
+	now := time.Now().UnixMilli()
+	if err := r.CreatePeerShare(&repo.PeerShare{
+		Name:           "forward-share",
+		NodeID:         1,
+		Token:          "forward-share-token",
+		MaxBandwidth:   0,
+		CurrentFlow:    0,
+		PortRangeStart: 30000,
+		PortRangeEnd:   30010,
+		IsActive:       1,
+		CreatedTime:    now,
+		UpdatedTime:    now,
+	}); err != nil {
+		t.Fatalf("create peer share: %v", err)
+	}
+	share, err := r.GetPeerShareByToken("forward-share-token")
+	if err != nil || share == nil {
+		t.Fatalf("load peer share: %v", err)
+	}
+
+	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, 'u2', 'x', 1, ?, 99999, 0, 0, 1, 1, ?, ?, 1)
+	`, now+24*60*60*1000, now, now).Error; err != nil {
+		t.Fatalf("insert user: %v", err)
+	}
+
+	tunnelName := "Share-" + strconv.FormatInt(share.ID, 10) + "-Port-30001"
+	if err := r.DB().Exec(`
+		INSERT INTO tunnel(id, name, traffic_ratio, type, protocol, flow, created_time, updated_time, status, in_ip, inx)
+		VALUES(1, ?, 1.0, 1, 'tls', 1, ?, ?, 1, NULL, 0)
+	`, tunnelName, now, now).Error; err != nil {
+		t.Fatalf("insert 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(10, 2, 1, NULL, 1, 99999, 0, 0, 1, ?, 1)
+	`, now+24*60*60*1000).Error; err != nil {
+		t.Fatalf("insert user_tunnel: %v", err)
+	}
+
+	if err := r.DB().Exec(`
+		INSERT INTO forward(id, user_id, user_name, name, tunnel_id, remote_addr, strategy, in_flow, out_flow, created_time, updated_time, status, inx)
+		VALUES(20, 2, 'u2', 'f20', 1, '1.1.1.1:443', 'fifo', 0, 0, ?, ?, 1, 0)
+	`, now, now).Error; err != nil {
+		t.Fatalf("insert forward: %v", err)
+	}
+
+	h := &Handler{repo: r}
+	h.processFlowItem(1, flowItem{N: "20_2_10", U: 120, D: 80})
+
+	updatedShare, err := r.GetPeerShare(share.ID)
+	if err != nil || updatedShare == nil {
+		t.Fatalf("reload share: %v", err)
+	}
+	if updatedShare.CurrentFlow != 200 {
+		t.Fatalf("expected current_flow=200, got %d", updatedShare.CurrentFlow)
+	}
+}
+
+func TestProcessFlowItemTracksPeerShareFlowByForwardServiceName(t *testing.T) {
+	r, err := repo.Open(filepath.Join(t.TempDir(), "panel-forward-service.db"))
+	if err != nil {
+		t.Fatalf("open repo: %v", err)
+	}
+	defer r.Close()
+
+	now := time.Now().UnixMilli()
+	if err := r.CreatePeerShare(&repo.PeerShare{
+		Name:           "forward-service-share",
+		NodeID:         1,
+		Token:          "forward-service-token",
+		MaxBandwidth:   0,
+		CurrentFlow:    0,
+		PortRangeStart: 31000,
+		PortRangeEnd:   31010,
+		IsActive:       1,
+		CreatedTime:    now,
+		UpdatedTime:    now,
+	}); err != nil {
+		t.Fatalf("create peer share: %v", err)
+	}
+	share, err := r.GetPeerShareByToken("forward-service-token")
+	if err != nil || share == nil {
+		t.Fatalf("load peer share: %v", err)
+	}
+
+	if err := r.DB().Exec(`
+		INSERT INTO peer_share_runtime(share_id, node_id, reservation_id, resource_key, binding_id, role, chain_name, service_name, protocol, strategy, port, target, applied, status, created_time, updated_time)
+		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, share.ID, share.NodeID, "svc-r1", "svc-rk1", "", "forward", "", "20_2_10", "tcp", "fifo", 31001, "", 1, 1, now, now).Error; err != nil {
+		t.Fatalf("insert peer_share_runtime: %v", err)
+	}
+
+	h := &Handler{repo: r}
+	h.processFlowItem(1, flowItem{N: "20_2_10_tcp", U: 120, D: 80})
+
+	updatedShare, err := r.GetPeerShare(share.ID)
+	if err != nil || updatedShare == nil {
+		t.Fatalf("reload share: %v", err)
+	}
+	if updatedShare.CurrentFlow != 200 {
+		t.Fatalf("expected current_flow=200, got %d", updatedShare.CurrentFlow)
+	}
+}
+
+func TestProcessFlowItemFallsBackToServiceNameWhenForwardIDCollidesAcrossPanels(t *testing.T) {
+	r, err := repo.Open(filepath.Join(t.TempDir(), "panel-forward-collision.db"))
+	if err != nil {
+		t.Fatalf("open repo: %v", err)
+	}
+	defer r.Close()
+
+	now := time.Now().UnixMilli()
+	if err := r.CreatePeerShare(&repo.PeerShare{
+		Name:           "collision-share",
+		NodeID:         1,
+		Token:          "collision-token",
+		MaxBandwidth:   0,
+		CurrentFlow:    0,
+		PortRangeStart: 31400,
+		PortRangeEnd:   31410,
+		IsActive:       1,
+		CreatedTime:    now,
+		UpdatedTime:    now,
+	}); err != nil {
+		t.Fatalf("create peer share: %v", err)
+	}
+	share, err := r.GetPeerShareByToken("collision-token")
+	if err != nil || share == nil {
+		t.Fatalf("load peer share: %v", err)
+	}
+
+	if err := r.DB().Exec(`
+		INSERT INTO peer_share_runtime(share_id, node_id, reservation_id, resource_key, binding_id, role, chain_name, service_name, protocol, strategy, port, target, applied, status, created_time, updated_time)
+		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, share.ID, share.NodeID, "collision-r1", "collision-rk1", "", "forward", "", "20_2_10", "tcp", "fifo", 31401, "", 1, 1, now, now).Error; err != nil {
+		t.Fatalf("insert peer_share_runtime: %v", err)
+	}
+
+	if err := r.DB().Exec(`
+		INSERT INTO tunnel(id, name, traffic_ratio, type, protocol, flow, created_time, updated_time, status, in_ip, inx)
+		VALUES(2, 'local-tunnel-with-colliding-forward-id', 1.0, 1, 'tls', 1, ?, ?, 1, NULL, 0)
+	`, now, now).Error; err != nil {
+		t.Fatalf("insert local tunnel: %v", err)
+	}
+
+	if err := r.DB().Exec(`
+		INSERT INTO forward(id, user_id, user_name, name, tunnel_id, remote_addr, strategy, in_flow, out_flow, created_time, updated_time, status, inx)
+		VALUES(20, 1, 'local-user', 'local-f20', 2, '8.8.8.8:53', 'fifo', 0, 0, ?, ?, 1, 0)
+	`, now, now).Error; err != nil {
+		t.Fatalf("insert local forward: %v", err)
+	}
+
+	h := &Handler{repo: r}
+	h.processFlowItem(1, flowItem{N: "20_2_10_tcp", U: 120, D: 80})
+
+	updatedShare, err := r.GetPeerShare(share.ID)
+	if err != nil || updatedShare == nil {
+		t.Fatalf("reload share: %v", err)
+	}
+	if updatedShare.CurrentFlow != 200 {
+		t.Fatalf("expected current_flow=200, got %d", updatedShare.CurrentFlow)
+	}
+}
+
+func TestProcessFlowItemSkipsPeerShareFlowWhenServiceNameIsAmbiguous(t *testing.T) {
+	r, err := repo.Open(filepath.Join(t.TempDir(), "panel-forward-ambiguous.db"))
+	if err != nil {
+		t.Fatalf("open repo: %v", err)
+	}
+	defer r.Close()
+
+	now := time.Now().UnixMilli()
+	if err := r.CreatePeerShare(&repo.PeerShare{
+		Name:           "ambiguous-share-a",
+		NodeID:         1,
+		Token:          "ambiguous-token-a",
+		MaxBandwidth:   0,
+		CurrentFlow:    0,
+		PortRangeStart: 31100,
+		PortRangeEnd:   31110,
+		IsActive:       1,
+		CreatedTime:    now,
+		UpdatedTime:    now,
+	}); err != nil {
+		t.Fatalf("create share A: %v", err)
+	}
+	if err := r.CreatePeerShare(&repo.PeerShare{
+		Name:           "ambiguous-share-b",
+		NodeID:         1,
+		Token:          "ambiguous-token-b",
+		MaxBandwidth:   0,
+		CurrentFlow:    0,
+		PortRangeStart: 31200,
+		PortRangeEnd:   31210,
+		IsActive:       1,
+		CreatedTime:    now,
+		UpdatedTime:    now,
+	}); err != nil {
+		t.Fatalf("create share B: %v", err)
+	}
+	shareA, _ := r.GetPeerShareByToken("ambiguous-token-a")
+	shareB, _ := r.GetPeerShareByToken("ambiguous-token-b")
+
+	if err := r.DB().Exec(`
+		INSERT INTO peer_share_runtime(share_id, node_id, reservation_id, resource_key, binding_id, role, chain_name, service_name, protocol, strategy, port, target, applied, status, created_time, updated_time)
+		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?),
+		      (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`,
+		shareA.ID, 1, "amb-r1", "amb-rk1", "", "forward", "", "99_2_10", "tcp", "fifo", 31101, "", 1, 1, now, now,
+		shareB.ID, 1, "amb-r2", "amb-rk2", "", "forward", "", "99_2_10", "tcp", "fifo", 31201, "", 1, 1, now, now,
+	).Error; err != nil {
+		t.Fatalf("insert ambiguous runtimes: %v", err)
+	}
+
+	h := &Handler{repo: r}
+	h.processFlowItem(1, flowItem{N: "99_2_10_tcp", U: 120, D: 80})
+
+	updatedA, _ := r.GetPeerShare(shareA.ID)
+	updatedB, _ := r.GetPeerShare(shareB.ID)
+	if updatedA.CurrentFlow != 0 || updatedB.CurrentFlow != 0 {
+		t.Fatalf("expected ambiguous service flow to be skipped, got shareA=%d shareB=%d", updatedA.CurrentFlow, updatedB.CurrentFlow)
+	}
+}
+
+func TestCleanOrphanedServicesSkipsActiveSharedForwardRuntimeServices(t *testing.T) {
+	r, err := repo.Open(filepath.Join(t.TempDir(), "panel-cleanup-runtime.db"))
+	if err != nil {
+		t.Fatalf("open repo: %v", err)
+	}
+	defer r.Close()
+
+	now := time.Now().UnixMilli()
+	if err := r.CreatePeerShare(&repo.PeerShare{
+		Name:           "cleanup-runtime-share",
+		NodeID:         1,
+		Token:          "cleanup-runtime-token",
+		MaxBandwidth:   0,
+		CurrentFlow:    0,
+		PortRangeStart: 31300,
+		PortRangeEnd:   31310,
+		IsActive:       1,
+		CreatedTime:    now,
+		UpdatedTime:    now,
+	}); err != nil {
+		t.Fatalf("create peer share: %v", err)
+	}
+	share, err := r.GetPeerShareByToken("cleanup-runtime-token")
+	if err != nil || share == nil {
+		t.Fatalf("load peer share: %v", err)
+	}
+
+	if err := r.DB().Exec(`
+		INSERT INTO peer_share_runtime(share_id, node_id, reservation_id, resource_key, binding_id, role, chain_name, service_name, protocol, strategy, port, target, applied, status, created_time, updated_time)
+		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, share.ID, share.NodeID, "cleanup-r1", "cleanup-rk1", "", "forward", "", "20_2_10", "tcp", "fifo", 31301, "", 1, 1, now, now).Error; err != nil {
+		t.Fatalf("insert peer_share_runtime: %v", err)
+	}
+
+	h := &Handler{repo: r}
+
+	defer func() {
+		if rec := recover(); rec != nil {
+			t.Fatalf("cleanOrphanedServices should skip active shared runtime service; got panic: %v", rec)
+		}
+	}()
+
+	h.cleanOrphanedServices(share.NodeID, []namedConfigItem{{Name: "20_2_10_tcp"}})
+}
+
+func TestCleanOrphanedServicesSkipsFederationServicePrefix(t *testing.T) {
+	r, err := repo.Open(filepath.Join(t.TempDir(), "panel-cleanup-fed-svc.db"))
+	if err != nil {
+		t.Fatalf("open repo: %v", err)
+	}
+	defer r.Close()
+
+	h := &Handler{repo: r}
+
+	defer func() {
+		if rec := recover(); rec != nil {
+			t.Fatalf("cleanOrphanedServices should skip fed_svc_ service names; got panic: %v", rec)
+		}
+	}()
+
+	h.cleanOrphanedServices(1, []namedConfigItem{{Name: "fed_svc_999_tcp"}})
+}
+
+func TestCleanOrphanedServicesSkipsForwardPatternWhenNodeHasActivePeerShareForwardRuntime(t *testing.T) {
+	r, err := repo.Open(filepath.Join(t.TempDir(), "panel-cleanup-forward-runtime-empty-service.db"))
+	if err != nil {
+		t.Fatalf("open repo: %v", err)
+	}
+	defer r.Close()
+
+	now := time.Now().UnixMilli()
+	if err := r.CreatePeerShare(&repo.PeerShare{
+		Name:           "cleanup-forward-runtime-empty-service",
+		NodeID:         1,
+		Token:          "cleanup-forward-runtime-empty-service-token",
+		MaxBandwidth:   0,
+		CurrentFlow:    0,
+		PortRangeStart: 31420,
+		PortRangeEnd:   31430,
+		IsActive:       1,
+		CreatedTime:    now,
+		UpdatedTime:    now,
+	}); err != nil {
+		t.Fatalf("create peer share: %v", err)
+	}
+	share, err := r.GetPeerShareByToken("cleanup-forward-runtime-empty-service-token")
+	if err != nil || share == nil {
+		t.Fatalf("load peer share: %v", err)
+	}
+
+	if err := r.DB().Exec(`
+		INSERT INTO peer_share_runtime(share_id, node_id, reservation_id, resource_key, binding_id, role, chain_name, service_name, protocol, strategy, port, target, applied, status, created_time, updated_time)
+		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, share.ID, share.NodeID, "cleanup-forward-empty-r1", "cleanup-forward-empty-rk1", "", "forward", "", "", "tcp", "fifo", 31421, "", 0, 1, now, now).Error; err != nil {
+		t.Fatalf("insert peer_share_runtime with empty service name: %v", err)
+	}
+
+	h := &Handler{repo: r}
+
+	defer func() {
+		if rec := recover(); rec != nil {
+			t.Fatalf("cleanOrphanedServices should skip forward-pattern services when active peer-share forward runtime exists; got panic: %v", rec)
+		}
+	}()
+
+	h.cleanOrphanedServices(share.NodeID, []namedConfigItem{{Name: "20_2_10_tcp"}})
+}

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

@@ -34,6 +34,9 @@ type Handler struct {
 	jobsCancel  context.CancelFunc
 	jobsStarted bool
 	jobsWG      sync.WaitGroup
+
+	upgradeMu              sync.Mutex
+	pendingUpgradeRedeploy map[int64]struct{}
 }
 
 type loginRequest struct {
@@ -70,12 +73,15 @@ type flowItem struct {
 }
 
 func New(repo *repo.Repository, jwtSecret string) *Handler {
-	return &Handler{
-		repo:          repo,
-		jwtSecret:     jwtSecret,
-		wsServer:      ws.NewServer(repo, jwtSecret),
-		captchaTokens: make(map[string]int64),
+	h := &Handler{
+		repo:                   repo,
+		jwtSecret:              jwtSecret,
+		wsServer:               ws.NewServer(repo, jwtSecret),
+		captchaTokens:          make(map[string]int64),
+		pendingUpgradeRedeploy: make(map[int64]struct{}),
 	}
+	h.wsServer.SetNodeOnlineHook(h.onNodeOnline)
+	return h
 }
 
 func (h *Handler) WebSocketHandler() http.Handler {
@@ -89,6 +95,7 @@ func (h *Handler) Register(mux *http.ServeMux) {
 	mux.HandleFunc("/api/v1/user/update", h.userUpdate)
 	mux.HandleFunc("/api/v1/user/delete", h.userDelete)
 	mux.HandleFunc("/api/v1/user/reset", h.userResetFlow)
+	mux.HandleFunc("/api/v1/user/groups", h.userGroups)
 	mux.HandleFunc("/api/v1/config/get", h.getConfigByName)
 	mux.HandleFunc("/api/v1/config/list", h.getConfigs)
 	mux.HandleFunc("/api/v1/config/update", h.updateConfigs)
@@ -212,7 +219,7 @@ func (h *Handler) login(w http.ResponseWriter, r *http.Request) {
 		response.WriteJSON(w, response.Err(-2, err.Error()))
 		return
 	}
-	if captchaEnabled {
+	if captchaEnabled && !h.apiClientCaptchaBypassEnabled(r) {
 		captchaID := strings.TrimSpace(req.CaptchaID)
 		if captchaID == "" {
 			response.WriteJSON(w, response.ErrDefault("验证码校验失败"))
@@ -697,7 +704,8 @@ func (h *Handler) flowConfig(w http.ResponseWriter, r *http.Request) {
 
 func (h *Handler) flowUpload(w http.ResponseWriter, r *http.Request) {
 	secret := r.URL.Query().Get("secret")
-	if ok, _ := h.repo.NodeExistsBySecret(secret); !ok {
+	node, _ := h.repo.GetNodeBySecret(secret)
+	if node == nil {
 		w.Header().Set("Content-Type", "text/plain; charset=utf-8")
 		_, _ = w.Write([]byte("ok"))
 		return
@@ -708,7 +716,7 @@ func (h *Handler) flowUpload(w http.ResponseWriter, r *http.Request) {
 		var items []flowItem
 		if json.Unmarshal([]byte(raw), &items) == nil {
 			for _, item := range items {
-				h.processFlowItem(item)
+				h.processFlowItem(node.ID, item)
 			}
 		}
 	}
@@ -981,10 +989,41 @@ func (h *Handler) captchaEnabled() (bool, error) {
 	if err != nil {
 		return false, err
 	}
-	if cfg == nil {
+	if cfg == nil || !strings.EqualFold(strings.TrimSpace(cfg.Value), "true") {
 		return false, nil
 	}
-	return strings.EqualFold(cfg.Value, "true"), nil
+
+	siteCfg, err := h.repo.GetConfigByName("cloudflare_site_key")
+	if err != nil {
+		return false, err
+	}
+	if siteCfg == nil || strings.TrimSpace(siteCfg.Value) == "" {
+		return false, nil
+	}
+
+	secretCfg, err := h.repo.GetConfigByName("cloudflare_secret_key")
+	if err != nil {
+		return false, err
+	}
+	if secretCfg == nil || strings.TrimSpace(secretCfg.Value) == "" {
+		return false, nil
+	}
+
+	return true, nil
+}
+
+func (h *Handler) apiClientCaptchaBypassEnabled(r *http.Request) bool {
+	if r == nil {
+		return false
+	}
+
+	client := strings.ToLower(strings.TrimSpace(r.Header.Get("X-FLVX-API-Client")))
+	switch client {
+	case "whmcs", "whmcs-module":
+		return true
+	default:
+		return false
+	}
 }
 
 func (h *Handler) markCaptchaToken(token string) {

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

@@ -69,6 +69,13 @@ func TestRunResetAndExpiryJobResetsFlowAndDisablesExpiredRecords(t *testing.T) {
 		t.Fatalf("insert expired user: %v", err)
 	}
 
+	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(3, 'non_expiring_user', 'x', 1, 0, 100, 1000, 2000, 15, 1, ?, ?, 1)
+	`, nowMs, nowMs).Error; err != nil {
+		t.Fatalf("insert non-expiring user: %v", err)
+	}
+
 	if err := r.DB().Exec(`
 		INSERT INTO tunnel(id, name, traffic_ratio, type, protocol, flow, created_time, updated_time, status, in_ip, inx)
 		VALUES(1, 't1', 1.0, 1, 'tls', 1, ?, ?, 1, NULL, 0)
@@ -83,6 +90,13 @@ func TestRunResetAndExpiryJobResetsFlowAndDisablesExpiredRecords(t *testing.T) {
 		t.Fatalf("insert expired user_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(11, 3, 1, NULL, 1, 1, 300, 400, 15, 0, 1)
+	`).Error; err != nil {
+		t.Fatalf("insert non-expiring user_tunnel: %v", err)
+	}
+
 	if err := r.DB().Exec(`
 		INSERT INTO forward(id, user_id, user_name, name, tunnel_id, remote_addr, strategy, in_flow, out_flow, created_time, updated_time, status, inx)
 		VALUES(20, 2, 'expired_user', 'f1', 1, '1.1.1.1:443', 'fifo', 0, 0, ?, ?, 1, 0)
@@ -90,6 +104,13 @@ func TestRunResetAndExpiryJobResetsFlowAndDisablesExpiredRecords(t *testing.T) {
 		t.Fatalf("insert forward: %v", err)
 	}
 
+	if err := r.DB().Exec(`
+		INSERT INTO forward(id, user_id, user_name, name, tunnel_id, remote_addr, strategy, in_flow, out_flow, created_time, updated_time, status, inx)
+		VALUES(21, 3, 'non_expiring_user', 'f2', 1, '1.1.1.1:443', 'fifo', 0, 0, ?, ?, 1, 1)
+	`, nowMs, nowMs).Error; err != nil {
+		t.Fatalf("insert non-expiring forward: %v", err)
+	}
+
 	h.runResetAndExpiryJob(now)
 
 	userIn, userOut, userStatus := mustQueryInt64Int64Int(t, r, `SELECT in_flow, out_flow, status FROM user WHERE id = 2`)
@@ -106,4 +127,19 @@ func TestRunResetAndExpiryJobResetsFlowAndDisablesExpiredRecords(t *testing.T) {
 	if forwardStatus != 0 {
 		t.Fatalf("expected forward status=0 after expiry handling, got %d", forwardStatus)
 	}
+
+	nonExpUserStatus := mustQueryInt(t, r, `SELECT status FROM user WHERE id = 3`)
+	if nonExpUserStatus != 1 {
+		t.Fatalf("expected non-expiring user to remain enabled, got status=%d", nonExpUserStatus)
+	}
+
+	nonExpTunnelStatus := mustQueryInt(t, r, `SELECT status FROM user_tunnel WHERE id = 11`)
+	if nonExpTunnelStatus != 1 {
+		t.Fatalf("expected non-expiring user_tunnel to remain enabled, got status=%d", nonExpTunnelStatus)
+	}
+
+	nonExpForwardStatus := mustQueryInt(t, r, `SELECT status FROM forward WHERE id = 21`)
+	if nonExpForwardStatus != 1 {
+		t.Fatalf("expected non-expiring forward to remain enabled, got status=%d", nonExpForwardStatus)
+	}
 }

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

@@ -60,10 +60,21 @@ func (h *Handler) userCreate(w http.ResponseWriter, r *http.Request) {
 	roleID := 1
 	now := time.Now().UnixMilli()
 
-	if err := h.repo.CreateUser(username, security.MD5(pwd), roleID, expTime, flow, flowResetTime, num, status, now); err != nil {
+	userID, err := h.repo.CreateUser(username, security.MD5(pwd), roleID, expTime, flow, flowResetTime, num, status, now)
+	if err != nil {
 		response.WriteJSON(w, response.Err(-2, err.Error()))
 		return
 	}
+
+	groupIDs := asInt64Slice(req["groupIds"])
+	if len(groupIDs) > 0 {
+		if addErr := h.repo.AddUserToGroups(userID, groupIDs, now); addErr == nil {
+			for _, gid := range groupIDs {
+				_ = h.syncPermissionsByUserGroup(gid)
+			}
+		}
+	}
+
 	response.WriteJSON(w, response.OKEmpty())
 }
 
@@ -133,9 +144,36 @@ func (h *Handler) userUpdate(w http.ResponseWriter, r *http.Request) {
 	}
 
 	h.repo.PropagateUserFlowToTunnels(id, flow, num, expTime, flowResetTime)
+
+	if groupIDsRaw, ok := req["groupIds"]; ok {
+		newGroupIDs := asInt64Slice(groupIDsRaw)
+		if affected, replaceErr := h.repo.ReplaceUserGroupsByUserID(id, newGroupIDs, now); replaceErr == nil {
+			for _, gid := range affected {
+				_ = h.syncPermissionsByUserGroup(gid)
+			}
+		}
+	}
+
 	response.WriteJSON(w, response.OKEmpty())
 }
 
+func (h *Handler) userGroups(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		response.WriteJSON(w, response.ErrDefault("请求失败"))
+		return
+	}
+	id := idFromBody(r, w)
+	if id <= 0 {
+		return
+	}
+	ids, err := h.repo.GetUserGroupIDsByUserID(id)
+	if err != nil {
+		response.WriteJSON(w, response.Err(-2, err.Error()))
+		return
+	}
+	response.WriteJSON(w, response.OK(ids))
+}
+
 func (h *Handler) userDelete(w http.ResponseWriter, r *http.Request) {
 	if r.Method != http.MethodPost {
 		response.WriteJSON(w, response.ErrDefault("请求失败"))
@@ -317,11 +355,28 @@ func (h *Handler) nodeInstall(w http.ResponseWriter, r *http.Request) {
 		response.WriteJSON(w, response.ErrDefault("请求失败"))
 		return
 	}
-	id := idFromBody(r, w)
-	if id <= 0 {
+
+	var req struct {
+		ID      int64  `json:"id"`
+		Channel string `json:"channel"`
+	}
+	if err := decodeJSON(r.Body, &req); err != nil {
+		response.WriteJSON(w, response.ErrDefault("请求参数错误"))
 		return
 	}
-	secret, err := h.repo.GetNodeSecret(id)
+	if req.ID <= 0 {
+		response.WriteJSON(w, response.ErrDefault("参数错误"))
+		return
+	}
+
+	channel := normalizeReleaseChannel(req.Channel)
+	version, err := resolveLatestReleaseByChannel(channel)
+	if err != nil {
+		response.WriteJSON(w, response.Err(-2, fmt.Sprintf("获取最新%s失败: %v", releaseChannelLabel(channel), err)))
+		return
+	}
+
+	secret, err := h.repo.GetNodeSecret(req.ID)
 	if err != nil {
 		response.WriteJSON(w, response.ErrDefault("节点不存在"))
 		return
@@ -335,7 +390,7 @@ func (h *Handler) nodeInstall(w http.ResponseWriter, r *http.Request) {
 		response.WriteJSON(w, response.Err(-2, err.Error()))
 		return
 	}
-	cmd := fmt.Sprintf("curl -L https://gcode.hostcentral.cc/https://github.com/Sagit-chu/flvx/releases/latest/download/install.sh -o ./install.sh && chmod +x ./install.sh && ./install.sh -a %s -s %s", processServerAddress(panelAddr), secret)
+	cmd := fmt.Sprintf("curl -L https://gcode.hostcentral.cc/https://github.com/Sagit-chu/flvx/releases/download/%s/install.sh -o ./install.sh && chmod +x ./install.sh && VERSION=%s ./install.sh -a %s -s %s", version, version, processServerAddress(panelAddr), secret)
 	response.WriteJSON(w, response.OK(cmd))
 }
 
@@ -437,7 +492,7 @@ func (h *Handler) tunnelCreate(w http.ResponseWriter, r *http.Request) {
 	}
 	runtimeState.IPPreference = ipPreference
 	if strings.TrimSpace(inIP) == "" {
-		inIP = buildTunnelInIP(runtimeState.InNodes, runtimeState.Nodes)
+		inIP = buildTunnelInIP(runtimeState.InNodes, runtimeState.Nodes, ipPreference)
 	}
 
 	if len(runtimeState.InNodes) > 0 {
@@ -634,7 +689,7 @@ func (h *Handler) tunnelUpdate(w http.ResponseWriter, r *http.Request) {
 	runtimeState.TunnelID = id
 	runtimeState.IPPreference = ipPreference
 
-	inIp := buildTunnelInIP(runtimeState.InNodes, runtimeState.Nodes)
+	inIp := buildTunnelInIP(runtimeState.InNodes, runtimeState.Nodes, ipPreference)
 
 	var federationBindings []repo.FederationTunnelBinding
 	var federationReleaseRefs []federationRuntimeReleaseRef
@@ -696,6 +751,12 @@ func (h *Handler) tunnelUpdate(w http.ResponseWriter, r *http.Request) {
 		}
 	}
 
+	if forwards, fwdErr := h.listForwardsByTunnel(id); fwdErr == nil {
+		for i := range forwards {
+			_ = h.syncForwardServices(&forwards[i], "UpdateService", true)
+		}
+	}
+
 	response.WriteJSON(w, response.OKEmpty())
 }
 
@@ -857,6 +918,58 @@ func (h *Handler) reconstructTunnelState(tunnelID int64) (*tunnelCreateState, er
 	return state, nil
 }
 
+func (h *Handler) redeployTunnelAndForwards(tunnelID int64) error {
+	tunnel, err := h.getTunnelRecord(tunnelID)
+	if err != nil {
+		return err
+	}
+
+	if tunnel.Type == 2 {
+		h.cleanupTunnelRuntime(tunnelID)
+		h.cleanupFederationRuntime(tunnelID)
+		state, err := h.reconstructTunnelState(tunnelID)
+		if err != nil {
+			return err
+		}
+		federationBindings, federationReleaseRefs, fedErr := h.applyFederationRuntime(state, h.federationLocalDomain())
+		if fedErr != nil {
+			return fedErr
+		}
+		tx := h.repo.BeginTx()
+		if tx.Error != nil {
+			h.releaseFederationRuntimeRefs(federationReleaseRefs)
+			return tx.Error
+		}
+		if replaceErr := h.repo.ReplaceFederationTunnelBindingsTx(tx, tunnelID, federationBindings); replaceErr != nil {
+			tx.Rollback()
+			h.releaseFederationRuntimeRefs(federationReleaseRefs)
+			return replaceErr
+		}
+		if commitErr := tx.Commit().Error; commitErr != nil {
+			h.releaseFederationRuntimeRefs(federationReleaseRefs)
+			return commitErr
+		}
+		_, _, applyErr := h.applyTunnelRuntime(state)
+		if applyErr != nil {
+			h.releaseFederationRuntimeRefs(federationReleaseRefs)
+			_ = h.repo.DeleteFederationTunnelBindingsByTunnel(tunnelID)
+			return applyErr
+		}
+	}
+
+	forwards, err := h.listForwardsByTunnel(tunnelID)
+	if err != nil {
+		return err
+	}
+	for i := range forwards {
+		if err := h.syncForwardServices(&forwards[i], "UpdateService", true); err != nil {
+			return err
+		}
+	}
+
+	return nil
+}
+
 func (h *Handler) tunnelBatchRedeploy(w http.ResponseWriter, r *http.Request) {
 	ids := idsFromBody(r, w)
 	if ids == nil {
@@ -865,72 +978,11 @@ func (h *Handler) tunnelBatchRedeploy(w http.ResponseWriter, r *http.Request) {
 	success := 0
 	fail := 0
 	for _, tunnelID := range ids {
-		tunnel, err := h.getTunnelRecord(tunnelID)
-		if err != nil {
+		if err := h.redeployTunnelAndForwards(tunnelID); err != nil {
 			fail++
 			continue
 		}
-
-		if tunnel.Type == 2 {
-			h.cleanupTunnelRuntime(tunnelID)
-			h.cleanupFederationRuntime(tunnelID)
-			state, err := h.reconstructTunnelState(tunnelID)
-			if err != nil {
-				fail++
-				continue
-			}
-			federationBindings, federationReleaseRefs, fedErr := h.applyFederationRuntime(state, h.federationLocalDomain())
-			if fedErr != nil {
-				fail++
-				continue
-			}
-			tx := h.repo.BeginTx()
-			if tx.Error != nil {
-				h.releaseFederationRuntimeRefs(federationReleaseRefs)
-				fail++
-				continue
-			}
-			if replaceErr := h.repo.ReplaceFederationTunnelBindingsTx(tx, tunnelID, federationBindings); replaceErr != nil {
-				tx.Rollback()
-				h.releaseFederationRuntimeRefs(federationReleaseRefs)
-				fail++
-				continue
-			}
-			if commitErr := tx.Commit().Error; commitErr != nil {
-				h.releaseFederationRuntimeRefs(federationReleaseRefs)
-				fail++
-				continue
-			}
-			_, _, applyErr := h.applyTunnelRuntime(state)
-			if applyErr != nil {
-				h.releaseFederationRuntimeRefs(federationReleaseRefs)
-				_ = h.repo.DeleteFederationTunnelBindingsByTunnel(tunnelID)
-				fail++
-				continue
-			}
-		}
-
-		forwards, err := h.listForwardsByTunnel(tunnelID)
-		if err != nil {
-			fail++
-			continue
-		}
-		if len(forwards) == 0 {
-			success++
-			continue
-		}
-		ok := true
-		for i := range forwards {
-			if err := h.syncForwardServices(&forwards[i], "UpdateService", true); err != nil {
-				ok = false
-				break
-			}
-		}
-		if ok {
-			success++
-		} else {
-			fail++
-		}
+		success++
 	}
 	response.WriteJSON(w, response.OK(map[string]interface{}{"successCount": success, "failCount": fail}))
 }
@@ -996,21 +1048,55 @@ func (h *Handler) userTunnelUpdate(w http.ResponseWriter, r *http.Request) {
 		response.WriteJSON(w, response.ErrDefault("权限ID不能为空"))
 		return
 	}
+
+	speedID := asAnyToInt64Ptr(req["speedId"])
+	if err := h.validateSpeedLimitReference(speedID); err != nil {
+		response.WriteJSON(w, response.Err(-2, err.Error()))
+		return
+	}
+
+	userID, tunnelID, utErr := h.repo.GetUserTunnelUserAndTunnel(id)
+	if utErr != nil {
+		response.WriteJSON(w, response.Err(-2, utErr.Error()))
+		return
+	}
+
+	_, oldFlow, oldNum, oldExpTime, oldFlowReset, oldSpeedID, oldStatus, oldErr :=
+		h.repo.GetExistingUserTunnel(userID, tunnelID)
+	if oldErr != nil {
+		response.WriteJSON(w, response.Err(-2, oldErr.Error()))
+		return
+	}
+
 	if err := h.repo.UpdateUserTunnel(id,
 		asInt64(req["flow"], 0),
 		asInt(req["num"], 0),
 		asInt64(req["expTime"], time.Now().Add(365*24*time.Hour).UnixMilli()),
 		asInt64(req["flowResetTime"], 1),
-		nullableInt(asAnyToInt64Ptr(req["speedId"])),
+		nullableInt(speedID),
 		asInt(req["status"], 1),
 	); err != nil {
 		response.WriteJSON(w, response.Err(-2, err.Error()))
 		return
 	}
 
-	userID, tunnelID, utErr := h.repo.GetUserTunnelUserAndTunnel(id)
-	if utErr == nil {
-		h.syncUserTunnelForwards(userID, tunnelID)
+	if syncErr := h.syncUserTunnelForwards(userID, tunnelID); syncErr != nil {
+		rollbackErr := h.repo.UpdateUserTunnel(
+			id,
+			oldFlow,
+			int(oldNum),
+			oldExpTime,
+			oldFlowReset,
+			oldSpeedID,
+			oldStatus,
+		)
+		if rollbackErr != nil {
+			response.WriteJSON(w, response.Err(-2, fmt.Sprintf("下发失败且回滚失败: %v; 回滚错误: %v", syncErr, rollbackErr)))
+			return
+		}
+
+		response.WriteJSON(w, response.Err(-2, fmt.Sprintf("下发失败，已回滚: %v", syncErr)))
+		return
 	}
 
 	response.WriteJSON(w, response.OKEmpty())
@@ -1051,6 +1137,18 @@ func (h *Handler) forwardCreate(w http.ResponseWriter, r *http.Request) {
 		response.WriteJSON(w, response.ErrDefault("转发名称和目标地址不能为空"))
 		return
 	}
+	speedID := asAnyToInt64Ptr(req["speedId"])
+	if speedID != nil {
+		exists, speedErr := h.repo.SpeedLimitExists(*speedID)
+		if speedErr != nil {
+			response.WriteJSON(w, response.Err(-2, speedErr.Error()))
+			return
+		}
+		if !exists {
+			response.WriteJSON(w, response.ErrDefault("限速规则不存在"))
+			return
+		}
+	}
 	port := asInt(req["inPort"], 0)
 	if port <= 0 {
 		port = h.pickTunnelPort(tunnelID)
@@ -1075,7 +1173,7 @@ func (h *Handler) forwardCreate(w http.ResponseWriter, r *http.Request) {
 	if userName == "" {
 		userName = "user"
 	}
-	forwardID, err := h.repo.CreateForwardTx(userID, userName, name, tunnelID, remoteAddr, defaultString(asString(req["strategy"]), "fifo"), now, inx, entryNodes, port)
+	forwardID, err := h.repo.CreateForwardTx(userID, userName, name, tunnelID, remoteAddr, defaultString(asString(req["strategy"]), "fifo"), now, inx, entryNodes, port, nullableInt(speedID))
 	if err != nil {
 		response.WriteJSON(w, response.Err(-2, err.Error()))
 		return
@@ -1085,7 +1183,7 @@ func (h *Handler) forwardCreate(w http.ResponseWriter, r *http.Request) {
 		response.WriteJSON(w, response.Err(-2, err.Error()))
 		return
 	}
-	if err := h.syncForwardServices(createdForward, "AddService", false); err != nil {
+	if err := h.syncForwardServices(createdForward, "UpdateService", true); err != nil {
 		_ = h.deleteForwardByID(forwardID)
 		response.WriteJSON(w, response.ErrDefault(err.Error()))
 		return
@@ -1150,6 +1248,24 @@ func (h *Handler) forwardUpdate(w http.ResponseWriter, r *http.Request) {
 	if strategy == "" {
 		strategy = forward.Strategy
 	}
+	speedID := asAnyToInt64Ptr(req["speedId"])
+	if speedID != nil {
+		exists, speedErr := h.repo.SpeedLimitExists(*speedID)
+		if speedErr != nil {
+			response.WriteJSON(w, response.Err(-2, speedErr.Error()))
+			return
+		}
+		if !exists {
+			response.WriteJSON(w, response.ErrDefault("限速规则不存在"))
+			return
+		}
+	}
+	newSpeedID := forward.SpeedID
+	if speedID != nil {
+		newSpeedID = sql.NullInt64{Int64: *speedID, Valid: true}
+	} else if _, ok := req["speedId"]; ok {
+		newSpeedID = sql.NullInt64{Valid: false}
+	}
 
 	port := asInt(req["inPort"], 0)
 	if port <= 0 {
@@ -1173,7 +1289,7 @@ func (h *Handler) forwardUpdate(w http.ResponseWriter, r *http.Request) {
 		}
 	}
 	now := time.Now().UnixMilli()
-	if err := h.repo.UpdateForward(id, name, tunnelID, remoteAddr, strategy, now); err != nil {
+	if err := h.repo.UpdateForward(id, name, tunnelID, remoteAddr, strategy, now, newSpeedID); err != nil {
 		response.WriteJSON(w, response.Err(-2, err.Error()))
 		return
 	}
@@ -1534,29 +1650,37 @@ func (h *Handler) speedLimitCreate(w http.ResponseWriter, r *http.Request) {
 		response.WriteJSON(w, response.ErrDefault("请求参数错误"))
 		return
 	}
-	tunnelID := asInt64(req["tunnelId"], 0)
-	if tunnelID <= 0 {
-		response.WriteJSON(w, response.ErrDefault("隧道ID不能为空"))
-		return
-	}
+
 	name := asString(req["name"])
 	if name == "" {
 		response.WriteJSON(w, response.ErrDefault("名称不能为空"))
 		return
 	}
-	tunnelName := h.repo.GetTunnelNameByID(tunnelID)
-	if tunnelName == "" {
-		response.WriteJSON(w, response.ErrDefault("隧道不存在"))
-		return
-	}
-	now := time.Now().UnixMilli()
+
 	speed := asInt(req["speed"], 100)
+
+	var tunnelID *int64
+	var tunnelName string
+	if tid := asInt64(req["tunnelId"], 0); tid > 0 {
+		tunnelID = &tid
+		tunnelName = h.repo.GetTunnelNameByID(tid)
+		if tunnelName == "" {
+			response.WriteJSON(w, response.ErrDefault("隧道不存在"))
+			return
+		}
+	}
+
+	now := time.Now().UnixMilli()
 	id, err := h.repo.CreateSpeedLimit(name, speed, tunnelID, tunnelName, now, asInt(req["status"], 1))
 	if err != nil {
 		response.WriteJSON(w, response.Err(-2, err.Error()))
 		return
 	}
-	_ = h.sendLimiterConfig(id, speed, tunnelID)
+
+	if tunnelID != nil && *tunnelID > 0 {
+		_ = h.sendLimiterConfig(id, speed, *tunnelID)
+	}
+
 	response.WriteJSON(w, response.OKEmpty())
 }
 
@@ -1566,23 +1690,41 @@ func (h *Handler) speedLimitUpdate(w http.ResponseWriter, r *http.Request) {
 		response.WriteJSON(w, response.ErrDefault("请求参数错误"))
 		return
 	}
+
 	id := asInt64(req["id"], 0)
-	tunnelID := asInt64(req["tunnelId"], 0)
-	if id <= 0 || tunnelID <= 0 {
-		response.WriteJSON(w, response.ErrDefault("请求参数错误"))
+	if id <= 0 {
+		response.WriteJSON(w, response.ErrDefault("限速规则ID不能为空"))
 		return
 	}
-	tunnelName := h.repo.GetTunnelNameByID(tunnelID)
-	if tunnelName == "" {
-		response.WriteJSON(w, response.ErrDefault("隧道不存在"))
+
+	name := asString(req["name"])
+	if name == "" {
+		response.WriteJSON(w, response.ErrDefault("名称不能为空"))
 		return
 	}
+
 	speed := asInt(req["speed"], 100)
-	if err := h.repo.UpdateSpeedLimit(id, asString(req["name"]), speed, tunnelID, tunnelName, asInt(req["status"], 1), time.Now().UnixMilli()); err != nil {
+
+	var tunnelID *int64
+	var tunnelName string
+	if tid := asInt64(req["tunnelId"], 0); tid > 0 {
+		tunnelID = &tid
+		tunnelName = h.repo.GetTunnelNameByID(tid)
+		if tunnelName == "" {
+			response.WriteJSON(w, response.ErrDefault("隧道不存在"))
+			return
+		}
+	}
+
+	if err := h.repo.UpdateSpeedLimit(id, name, speed, tunnelID, tunnelName, asInt(req["status"], 1), time.Now().UnixMilli()); err != nil {
 		response.WriteJSON(w, response.Err(-2, err.Error()))
 		return
 	}
-	_ = h.sendLimiterConfig(id, speed, tunnelID)
+
+	if tunnelID != nil && *tunnelID > 0 {
+		_ = h.sendLimiterConfig(id, speed, *tunnelID)
+	}
+
 	response.WriteJSON(w, response.OKEmpty())
 }
 
@@ -1591,15 +1733,18 @@ func (h *Handler) speedLimitDelete(w http.ResponseWriter, r *http.Request) {
 	if id <= 0 {
 		return
 	}
+
 	tunnelID := h.repo.GetSpeedLimitTunnelID(id)
 
 	if err := h.repo.DeleteSpeedLimit(id); err != nil {
 		response.WriteJSON(w, response.Err(-2, err.Error()))
 		return
 	}
-	if tunnelID > 0 {
-		_ = h.sendDeleteLimiterConfig(id, tunnelID)
+
+	if tunnelID.Valid && tunnelID.Int64 > 0 {
+		_ = h.sendDeleteLimiterConfig(id, tunnelID.Int64)
 	}
+
 	response.WriteJSON(w, response.OKEmpty())
 }
 
@@ -1995,32 +2140,42 @@ func (h *Handler) prepareTunnelCreateState(tx *gorm.DB, req map[string]interface
 	return state, nil
 }
 
-func buildTunnelInIP(inNodes []tunnelRuntimeNode, nodes map[int64]*nodeRecord) string {
+func buildTunnelInIP(inNodes []tunnelRuntimeNode, nodes map[int64]*nodeRecord, ipPreference string) string {
 	set := make(map[string]struct{})
 	ordered := make([]string, 0)
+	preferV6 := strings.TrimSpace(ipPreference) == "v6"
 	for _, inNode := range inNodes {
 		node := nodes[inNode.NodeID]
 		if node == nil {
 			continue
 		}
-		if v := strings.TrimSpace(node.ServerIPv4); v != "" {
-			if _, ok := set[v]; !ok {
-				set[v] = struct{}{}
-				ordered = append(ordered, v)
+		v4 := strings.TrimSpace(node.ServerIPv4)
+		v6 := strings.TrimSpace(node.ServerIPv6)
+		var addrs []string
+		if preferV6 {
+			if v6 != "" {
+				addrs = append(addrs, v6)
+			}
+			if v4 != "" {
+				addrs = append(addrs, v4)
+			}
+		} else {
+			if v4 != "" {
+				addrs = append(addrs, v4)
+			}
+			if v6 != "" {
+				addrs = append(addrs, v6)
 			}
 		}
-		if v := strings.TrimSpace(node.ServerIPv6); v != "" {
-			if _, ok := set[v]; !ok {
-				set[v] = struct{}{}
-				ordered = append(ordered, v)
-			}
-		}
-		if strings.TrimSpace(node.ServerIPv4) == "" && strings.TrimSpace(node.ServerIPv6) == "" {
+		if len(addrs) == 0 {
 			if v := strings.TrimSpace(node.ServerIP); v != "" {
-				if _, ok := set[v]; !ok {
-					set[v] = struct{}{}
-					ordered = append(ordered, v)
-				}
+				addrs = append(addrs, v)
+			}
+		}
+		for _, a := range addrs {
+			if _, ok := set[a]; !ok {
+				set[a] = struct{}{}
+				ordered = append(ordered, a)
 			}
 		}
 	}
@@ -2651,7 +2806,7 @@ func pickNodeAddressV6(node *nodeRecord) string {
 func (h *Handler) replaceTunnelChainsTx(tx *gorm.DB, tunnelID int64, req map[string]interface{}) error {
 	allocated := map[int64]int{}
 	inNodes := asMapSlice(req["inNodeId"])
-	for _, n := range inNodes {
+	for i, n := range inNodes {
 		nodeID := asInt64(n["nodeId"], 0)
 		if nodeID <= 0 {
 			continue
@@ -2663,13 +2818,13 @@ func (h *Handler) replaceTunnelChainsTx(tx *gorm.DB, tunnelID int64, req map[str
 			nodeID,
 			sql.NullInt64{},
 			defaultString(asString(n["strategy"]), "round"),
-			0,
+			i+1,
 			defaultString(asString(n["protocol"]), "tls"),
 		); err != nil {
 			return err
 		}
 	}
-	for _, n := range asMapSlice(req["outNodeId"]) {
+	for i, n := range asMapSlice(req["outNodeId"]) {
 		nodeID := asInt64(n["nodeId"], 0)
 		if nodeID <= 0 {
 			continue
@@ -2689,7 +2844,7 @@ func (h *Handler) replaceTunnelChainsTx(tx *gorm.DB, tunnelID int64, req map[str
 			nodeID,
 			sql.NullInt64{Int64: int64(port), Valid: true},
 			defaultString(asString(n["strategy"]), "round"),
-			0,
+			i+1,
 			defaultString(asString(n["protocol"]), "tls"),
 		); err != nil {
 			return err
@@ -2732,7 +2887,21 @@ func (h *Handler) deleteNodeByID(id int64) error {
 }
 
 func (h *Handler) deleteTunnelByID(id int64) error {
-	return h.repo.DeleteTunnelCascade(id)
+	if h == nil || h.repo == nil {
+		return errors.New("repository not initialized")
+	}
+
+	tunnelName, _ := h.repo.GetTunnelName(id)
+	if err := h.repo.DeleteTunnelCascade(id); err != nil {
+		return err
+	}
+
+	shareID, port, ok := parsePeerShareInfoFromFederationTunnelName(tunnelName)
+	if !ok {
+		return nil
+	}
+
+	return h.repo.MarkPeerShareRuntimeReleasedByPort(shareID, port, time.Now().UnixMilli())
 }
 
 func (h *Handler) deleteForwardByID(id int64) error {
@@ -2901,6 +3070,7 @@ func (h *Handler) rollbackForwardMutation(oldForward *forwardRecord, oldPorts []
 	h.repo.RollbackForwardFields(
 		oldForward.ID, oldForward.UserID, oldForward.UserName, oldForward.Name,
 		oldForward.TunnelID, oldForward.RemoteAddr, oldForward.Strategy, oldForward.Status,
+		oldForward.SpeedID,
 		time.Now().UnixMilli(),
 	)
 
@@ -2922,6 +3092,10 @@ func (h *Handler) upsertUserTunnel(req map[string]interface{}) error {
 		h.repo.GetExistingUserTunnel(userID, tunnelID)
 
 	speedID := asAnyToInt64Ptr(req["speedId"])
+	if err := h.validateSpeedLimitReference(speedID); err != nil {
+		return err
+	}
+
 	reqFlow := asInt64(req["flow"], -1)
 	reqNum := asInt(req["num"], -1)
 	reqExpTime := asInt64(req["expTime"], -1)
@@ -2962,7 +3136,24 @@ func (h *Handler) upsertUserTunnel(req map[string]interface{}) error {
 			reqStatus = 1
 		}
 
-		return h.repo.InsertUserTunnel(userID, tunnelID, nullableInt(speedID), reqNum, reqFlow, reqFlowReset, reqExpTime, reqStatus)
+		if err := h.repo.InsertUserTunnel(userID, tunnelID, nullableInt(speedID), reqNum, reqFlow, reqFlowReset, reqExpTime, reqStatus); err != nil {
+			return err
+		}
+
+		if syncErr := h.syncUserTunnelForwards(userID, tunnelID); syncErr != nil {
+			insertedID, _, _, _, _, _, _, lookupErr := h.repo.GetExistingUserTunnel(userID, tunnelID)
+			if lookupErr != nil {
+				return fmt.Errorf("下发失败且回滚失败: %v; 回滚查询错误: %w", syncErr, lookupErr)
+			}
+
+			if rollbackErr := h.repo.DeleteUserTunnel(insertedID); rollbackErr != nil {
+				return fmt.Errorf("下发失败且回滚失败: %v; 回滚删除错误: %w", syncErr, rollbackErr)
+			}
+
+			return fmt.Errorf("下发失败，已回滚: %w", syncErr)
+		}
+
+		return nil
 	}
 	if err != nil {
 		return err
@@ -3000,25 +3191,61 @@ func (h *Handler) upsertUserTunnel(req map[string]interface{}) error {
 		newSpeedID = sql.NullInt64{Valid: false}
 	}
 
-	err = h.repo.UpdateUserTunnelFields(existingID, newSpeedID, newFlow, newNum, newExpTime, newFlowReset, newStatus)
-
-	if err == nil {
-		h.syncUserTunnelForwards(userID, tunnelID)
+	if err := h.repo.UpdateUserTunnelFields(existingID, newSpeedID, newFlow, newNum, newExpTime, newFlowReset, newStatus); err != nil {
+		return err
 	}
-	return err
+
+	if syncErr := h.syncUserTunnelForwards(userID, tunnelID); syncErr != nil {
+		rollbackErr := h.repo.UpdateUserTunnelFields(
+			existingID,
+			currentSpeedID,
+			currentFlow,
+			int(currentNum),
+			currentExpTime,
+			currentFlowReset,
+			currentStatus,
+		)
+		if rollbackErr != nil {
+			return fmt.Errorf("下发失败且回滚失败: %v; 回滚错误: %w", syncErr, rollbackErr)
+		}
+
+		return fmt.Errorf("下发失败，已回滚: %w", syncErr)
+	}
+
+	return nil
 }
 
-func (h *Handler) syncUserTunnelForwards(userID, tunnelID int64) {
+func (h *Handler) syncUserTunnelForwards(userID, tunnelID int64) error {
 	forwards, err := h.listForwardsByTunnel(tunnelID)
 	if err != nil {
-		return
+		return err
 	}
 	for i := range forwards {
 		f := &forwards[i]
 		if f.UserID == userID {
-			_ = h.syncForwardServices(f, "UpdateService", true)
+			if err := h.syncForwardServices(f, "UpdateService", true); err != nil {
+				return err
+			}
 		}
 	}
+
+	return nil
+}
+
+func (h *Handler) validateSpeedLimitReference(speedID *int64) error {
+	if speedID == nil {
+		return nil
+	}
+
+	exists, err := h.repo.SpeedLimitExists(*speedID)
+	if err != nil {
+		return err
+	}
+	if !exists {
+		return errors.New("限速规则不存在")
+	}
+
+	return nil
 }
 
 func asAnySlice(v interface{}) []interface{} {
@@ -3188,3 +3415,17 @@ func randomToken(n int) string {
 	}
 	return hex.EncodeToString(buf)
 }
+
+func asInt64Slice(v interface{}) []int64 {
+	arr := asAnySlice(v)
+	if len(arr) == 0 {
+		return nil
+	}
+	ids := make([]int64, 0, len(arr))
+	for _, x := range arr {
+		if id := asInt64(x, 0); id > 0 {
+			ids = append(ids, id)
+		}
+	}
+	return ids
+}

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

@@ -5,6 +5,7 @@ import (
 	"fmt"
 	"io"
 	"net/http"
+	"regexp"
 	"strings"
 	"sync"
 	"time"
@@ -19,8 +20,104 @@ const (
 	githubHTMLBase = "https://github.com"
 	upgradeTimeout = 5 * time.Minute
 	batchWorkers   = 5
+
+	releaseChannelStable = "stable"
+	releaseChannelDev    = "dev"
 )
 
+var (
+	stableVersionPattern = regexp.MustCompile(`^\d+(?:\.\d+)+$`)
+	testKeywordPattern   = regexp.MustCompile(`(?i)(alpha|beta|rc)`)
+)
+
+type githubRelease struct {
+	TagName     string `json:"tag_name"`
+	Name        string `json:"name"`
+	PublishedAt string `json:"published_at"`
+	Prerelease  bool   `json:"prerelease"`
+	Draft       bool   `json:"draft"`
+}
+
+func normalizeReleaseChannel(channel string) string {
+	switch strings.ToLower(strings.TrimSpace(channel)) {
+	case releaseChannelDev:
+		return releaseChannelDev
+	default:
+		return releaseChannelStable
+	}
+}
+
+func releaseChannelFromTag(tag string) string {
+	normalized := strings.ToLower(strings.TrimSpace(tag))
+	if normalized == "" {
+		return releaseChannelDev
+	}
+	if testKeywordPattern.MatchString(normalized) {
+		return releaseChannelDev
+	}
+	if stableVersionPattern.MatchString(normalized) {
+		return releaseChannelStable
+	}
+
+	return releaseChannelDev
+}
+
+func releaseChannelLabel(channel string) string {
+	if normalizeReleaseChannel(channel) == releaseChannelDev {
+		return "测试版"
+	}
+
+	return "正式版"
+}
+
+func fetchGitHubReleases(perPage int) ([]githubRelease, error) {
+	if perPage <= 0 {
+		perPage = 20
+	}
+
+	client := &http.Client{Timeout: 15 * time.Second}
+	resp, err := client.Get(fmt.Sprintf("%s/repos/%s/releases?per_page=%d", githubAPIBase, githubRepo, perPage))
+	if err != nil {
+		return nil, fmt.Errorf("请求GitHub API失败: %v", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		body, _ := io.ReadAll(io.LimitReader(resp.Body, 512))
+		return nil, fmt.Errorf("GitHub API返回 %d: %s", resp.StatusCode, string(body))
+	}
+
+	var releases []githubRelease
+	if err := json.NewDecoder(resp.Body).Decode(&releases); err != nil {
+		return nil, fmt.Errorf("解析GitHub API响应失败: %v", err)
+	}
+
+	return releases, nil
+}
+
+func resolveLatestReleaseByChannel(channel string) (string, error) {
+	normalizedChannel := normalizeReleaseChannel(channel)
+	releases, err := fetchGitHubReleases(50)
+	if err != nil {
+		return "", err
+	}
+
+	for _, r := range releases {
+		if r.Draft {
+			continue
+		}
+		tag := strings.TrimSpace(r.TagName)
+		if tag == "" {
+			continue
+		}
+		if releaseChannelFromTag(tag) == normalizedChannel {
+			return tag, nil
+		}
+	}
+
+	return "", fmt.Errorf("未找到%s版本号", releaseChannelLabel(normalizedChannel))
+}
+
 func (h *Handler) nodeUpgrade(w http.ResponseWriter, r *http.Request) {
 	if r.Method != http.MethodPost {
 		response.WriteJSON(w, response.ErrDefault("请求失败"))
@@ -30,6 +127,7 @@ func (h *Handler) nodeUpgrade(w http.ResponseWriter, r *http.Request) {
 	var req struct {
 		ID      int64  `json:"id"`
 		Version string `json:"version"`
+		Channel string `json:"channel"`
 	}
 	if err := decodeJSON(r.Body, &req); err != nil {
 		response.WriteJSON(w, response.ErrDefault("请求参数错误"))
@@ -40,12 +138,13 @@ func (h *Handler) nodeUpgrade(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
+	channel := normalizeReleaseChannel(req.Channel)
 	version := strings.TrimSpace(req.Version)
 	if version == "" {
 		var err error
-		version, err = resolveLatestRelease()
+		version, err = resolveLatestReleaseByChannel(channel)
 		if err != nil {
-			response.WriteJSON(w, response.Err(-2, fmt.Sprintf("获取最新版本失败: %v", err)))
+			response.WriteJSON(w, response.Err(-2, fmt.Sprintf("获取最新%s失败: %v", releaseChannelLabel(channel), err)))
 			return
 		}
 	}
@@ -67,6 +166,7 @@ func (h *Handler) nodeUpgrade(w http.ResponseWriter, r *http.Request) {
 		response.WriteJSON(w, response.Err(-2, fmt.Sprintf("升级失败: %v", err)))
 		return
 	}
+	h.markNodePendingUpgradeRedeploy(req.ID)
 
 	response.WriteJSON(w, response.OK(map[string]interface{}{
 		"version": version,
@@ -75,61 +175,11 @@ func (h *Handler) nodeUpgrade(w http.ResponseWriter, r *http.Request) {
 }
 
 func resolveLatestRelease() (string, error) {
-	client := &http.Client{
-		CheckRedirect: func(req *http.Request, via []*http.Request) error {
-			return http.ErrUseLastResponse
-		},
-		Timeout: 10 * time.Second,
-	}
-
-	resp, err := client.Get(githubProxy + "/" + githubHTMLBase + "/" + githubRepo + "/releases/latest")
-	if err != nil {
-		return "", fmt.Errorf("请求GitHub失败: %v", err)
-	}
-	defer resp.Body.Close()
-
-	if resp.StatusCode != http.StatusFound && resp.StatusCode != http.StatusMovedPermanently {
-		return resolveLatestReleaseAPI()
-	}
-
-	location := resp.Header.Get("Location")
-	if location == "" {
-		return resolveLatestReleaseAPI()
-	}
-
-	parts := strings.Split(location, "/")
-	tag := parts[len(parts)-1]
-	if tag == "" || tag == "latest" {
-		return resolveLatestReleaseAPI()
-	}
-
-	return tag, nil
+	return resolveLatestReleaseByChannel(releaseChannelStable)
 }
 
 func resolveLatestReleaseAPI() (string, error) {
-	client := &http.Client{Timeout: 10 * time.Second}
-	resp, err := client.Get(githubAPIBase + "/repos/" + githubRepo + "/releases/latest")
-	if err != nil {
-		return "", fmt.Errorf("请求GitHub API失败: %v", err)
-	}
-	defer resp.Body.Close()
-
-	if resp.StatusCode != http.StatusOK {
-		body, _ := io.ReadAll(io.LimitReader(resp.Body, 512))
-		return "", fmt.Errorf("GitHub API返回 %d: %s", resp.StatusCode, string(body))
-	}
-
-	var release struct {
-		TagName string `json:"tag_name"`
-	}
-	if err := json.NewDecoder(resp.Body).Decode(&release); err != nil {
-		return "", fmt.Errorf("解析GitHub API响应失败: %v", err)
-	}
-	if strings.TrimSpace(release.TagName) == "" {
-		return "", fmt.Errorf("无法从GitHub获取最新版本号")
-	}
-
-	return release.TagName, nil
+	return resolveLatestReleaseByChannel(releaseChannelStable)
 }
 
 func (h *Handler) nodeBatchUpgrade(w http.ResponseWriter, r *http.Request) {
@@ -141,6 +191,7 @@ func (h *Handler) nodeBatchUpgrade(w http.ResponseWriter, r *http.Request) {
 	var req struct {
 		IDs     []int64 `json:"ids"`
 		Version string  `json:"version"`
+		Channel string  `json:"channel"`
 	}
 	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
 		response.WriteJSON(w, response.ErrDefault("请求参数错误"))
@@ -151,12 +202,13 @@ func (h *Handler) nodeBatchUpgrade(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
+	channel := normalizeReleaseChannel(req.Channel)
 	version := strings.TrimSpace(req.Version)
 	if version == "" {
 		var err error
-		version, err = resolveLatestRelease()
+		version, err = resolveLatestReleaseByChannel(channel)
 		if err != nil {
-			response.WriteJSON(w, response.Err(-2, fmt.Sprintf("获取最新版本失败: %v", err)))
+			response.WriteJSON(w, response.Err(-2, fmt.Sprintf("获取最新%s失败: %v", releaseChannelLabel(channel), err)))
 			return
 		}
 	}
@@ -195,6 +247,7 @@ func (h *Handler) nodeBatchUpgrade(w http.ResponseWriter, r *http.Request) {
 				results[index] = upgradeResult{ID: nodeID, Success: false, Message: err.Error()}
 				return
 			}
+			h.markNodePendingUpgradeRedeploy(nodeID)
 			results[index] = upgradeResult{ID: nodeID, Success: true, Message: result.Message}
 		}(i, id)
 	}
@@ -212,37 +265,28 @@ func (h *Handler) listReleases(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	client := &http.Client{Timeout: 15 * time.Second}
-	resp, err := client.Get(githubAPIBase + "/repos/" + githubRepo + "/releases?per_page=20")
+	var req struct {
+		Channel string `json:"channel"`
+	}
+	if err := decodeJSON(r.Body, &req); err != nil && err != io.EOF {
+		response.WriteJSON(w, response.ErrDefault("请求参数错误"))
+		return
+	}
+
+	channel := normalizeReleaseChannel(req.Channel)
+
+	releases, err := fetchGitHubReleases(50)
 	if err != nil {
 		response.WriteJSON(w, response.Err(-2, fmt.Sprintf("获取版本列表失败: %v", err)))
 		return
 	}
-	defer resp.Body.Close()
-
-	if resp.StatusCode != http.StatusOK {
-		body, _ := io.ReadAll(io.LimitReader(resp.Body, 512))
-		response.WriteJSON(w, response.Err(-2, fmt.Sprintf("获取版本列表失败: GitHub API返回 %d: %s", resp.StatusCode, string(body))))
-		return
-	}
-
-	var releases []struct {
-		TagName     string `json:"tag_name"`
-		Name        string `json:"name"`
-		PublishedAt string `json:"published_at"`
-		Prerelease  bool   `json:"prerelease"`
-		Draft       bool   `json:"draft"`
-	}
-	if err := json.NewDecoder(resp.Body).Decode(&releases); err != nil {
-		response.WriteJSON(w, response.Err(-2, fmt.Sprintf("解析版本列表失败: %v", err)))
-		return
-	}
 
 	type releaseItem struct {
 		Version     string `json:"version"`
 		Name        string `json:"name"`
 		PublishedAt string `json:"publishedAt"`
 		Prerelease  bool   `json:"prerelease"`
+		Channel     string `json:"channel"`
 	}
 
 	items := make([]releaseItem, 0, len(releases))
@@ -250,11 +294,20 @@ func (h *Handler) listReleases(w http.ResponseWriter, r *http.Request) {
 		if r.Draft {
 			continue
 		}
+		tag := strings.TrimSpace(r.TagName)
+		if tag == "" {
+			continue
+		}
+		itemChannel := releaseChannelFromTag(tag)
+		if itemChannel != channel {
+			continue
+		}
 		items = append(items, releaseItem{
-			Version:     r.TagName,
+			Version:     tag,
 			Name:        r.Name,
 			PublishedAt: r.PublishedAt,
-			Prerelease:  r.Prerelease,
+			Prerelease:  itemChannel == releaseChannelDev,
+			Channel:     itemChannel,
 		})
 	}
 
@@ -289,3 +342,66 @@ func (h *Handler) nodeRollback(w http.ResponseWriter, r *http.Request) {
 		"message": result.Message,
 	}))
 }
+
+func (h *Handler) markNodePendingUpgradeRedeploy(nodeID int64) {
+	if h == nil || nodeID <= 0 {
+		return
+	}
+	h.upgradeMu.Lock()
+	h.pendingUpgradeRedeploy[nodeID] = struct{}{}
+	h.upgradeMu.Unlock()
+}
+
+func (h *Handler) consumeNodePendingUpgradeRedeploy(nodeID int64) bool {
+	if h == nil || nodeID <= 0 {
+		return false
+	}
+	h.upgradeMu.Lock()
+	_, ok := h.pendingUpgradeRedeploy[nodeID]
+	if ok {
+		delete(h.pendingUpgradeRedeploy, nodeID)
+	}
+	h.upgradeMu.Unlock()
+	return ok
+}
+
+func (h *Handler) onNodeOnline(nodeID int64) {
+	if !h.consumeNodePendingUpgradeRedeploy(nodeID) {
+		return
+	}
+	h.redeployNodeRuntimeAfterUpgrade(nodeID)
+}
+
+func (h *Handler) redeployNodeRuntimeAfterUpgrade(nodeID int64) {
+	tunnelIDs, err := h.repo.ListActiveTunnelIDsByNode(nodeID)
+	if err != nil {
+		fmt.Printf("post-upgrade redeploy: list tunnels for node %d failed: %v\n", nodeID, err)
+		return
+	}
+	forwardIDs, err := h.repo.ListActiveForwardIDsByNode(nodeID)
+	if err != nil {
+		fmt.Printf("post-upgrade redeploy: list forwards for node %d failed: %v\n", nodeID, err)
+		return
+	}
+
+	tunnelFailed := make(map[int64]struct{})
+	for _, tunnelID := range tunnelIDs {
+		if err := h.redeployTunnelAndForwards(tunnelID); err != nil {
+			tunnelFailed[tunnelID] = struct{}{}
+			fmt.Printf("post-upgrade redeploy: tunnel %d failed on node %d: %v\n", tunnelID, nodeID, err)
+		}
+	}
+
+	for _, forwardID := range forwardIDs {
+		forward, getErr := h.getForwardRecord(forwardID)
+		if getErr != nil || forward == nil {
+			continue
+		}
+		if _, skipped := tunnelFailed[forward.TunnelID]; skipped {
+			continue
+		}
+		if err := h.syncForwardServices(forward, "UpdateService", true); err != nil {
+			fmt.Printf("post-upgrade redeploy: forward %d failed on node %d: %v\n", forwardID, nodeID, err)
+		}
+	}
+}

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

@@ -0,0 +1,46 @@
+package handler
+
+import "testing"
+
+func TestReleaseChannelFromTag(t *testing.T) {
+	tests := []struct {
+		name    string
+		tag     string
+		expects string
+	}{
+		{name: "stable semantic version", tag: "2.1.4", expects: releaseChannelStable},
+		{name: "v prefix should be dev", tag: "v2.1.4", expects: releaseChannelDev},
+		{name: "rc release", tag: "2.1.4-rc2", expects: releaseChannelDev},
+		{name: "beta release", tag: "2.1.4-beta.1", expects: releaseChannelDev},
+		{name: "alpha release", tag: "2.1.4-alpha", expects: releaseChannelDev},
+		{name: "non numeric tag", tag: "nightly", expects: releaseChannelDev},
+		{name: "empty tag", tag: "", expects: releaseChannelDev},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := releaseChannelFromTag(tc.tag); got != tc.expects {
+				t.Fatalf("releaseChannelFromTag(%q) = %q, want %q", tc.tag, got, tc.expects)
+			}
+		})
+	}
+}
+
+func TestNormalizeReleaseChannel(t *testing.T) {
+	tests := []struct {
+		input   string
+		expects string
+	}{
+		{input: "", expects: releaseChannelStable},
+		{input: "stable", expects: releaseChannelStable},
+		{input: "dev", expects: releaseChannelDev},
+		{input: "DEV", expects: releaseChannelDev},
+		{input: "preview", expects: releaseChannelStable},
+	}
+
+	for _, tc := range tests {
+		if got := normalizeReleaseChannel(tc.input); got != tc.expects {
+			t.Fatalf("normalizeReleaseChannel(%q) = %q, want %q", tc.input, got, tc.expects)
+		}
+	}
+}

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

@@ -29,19 +29,20 @@ func (User) TableName() string { return "user" }
 
 // Forward maps to the "forward" table.
 type Forward struct {
-	ID          int64  `gorm:"primaryKey;autoIncrement"`
-	UserID      int64  `gorm:"column:user_id;not null"`
-	UserName    string `gorm:"column:user_name;type:varchar(100);not null"`
-	Name        string `gorm:"type:varchar(100);not null"`
-	TunnelID    int64  `gorm:"column:tunnel_id;not null"`
-	RemoteAddr  string `gorm:"column:remote_addr;type:text;not null"`
-	Strategy    string `gorm:"type:varchar(100);not null;default:'fifo'"`
-	InFlow      int64  `gorm:"column:in_flow;not null;default:0"`
-	OutFlow     int64  `gorm:"column:out_flow;not null;default:0"`
-	CreatedTime int64  `gorm:"column:created_time;not null"`
-	UpdatedTime int64  `gorm:"column:updated_time;not null"`
-	Status      int    `gorm:"not null"`
-	Inx         int    `gorm:"not null;default:0"`
+	ID          int64         `gorm:"primaryKey;autoIncrement"`
+	UserID      int64         `gorm:"column:user_id;not null"`
+	UserName    string        `gorm:"column:user_name;type:varchar(100);not null"`
+	Name        string        `gorm:"type:varchar(100);not null"`
+	TunnelID    int64         `gorm:"column:tunnel_id;not null"`
+	RemoteAddr  string        `gorm:"column:remote_addr;type:text;not null"`
+	Strategy    string        `gorm:"type:varchar(100);not null;default:'fifo'"`
+	InFlow      int64         `gorm:"not null;default:0"`
+	OutFlow     int64         `gorm:"column:out_flow;not null;default:0"`
+	CreatedTime int64         `gorm:"column:created_time;not null"`
+	UpdatedTime int64         `gorm:"column:updated_time;not null"`
+	Status      int           `gorm:"not null"`
+	Inx         int           `gorm:"not null;default:0"`
+	SpeedID     sql.NullInt64 `gorm:"column:speed_id"`
 }
 
 func (Forward) TableName() string { return "forward" }
@@ -83,14 +84,14 @@ type Node struct {
 func (Node) TableName() string { return "node" }
 
 type SpeedLimit struct {
-	ID          int64         `gorm:"primaryKey;autoIncrement"`
-	Name        string        `gorm:"type:varchar(100);not null"`
-	Speed       int           `gorm:"not null"`
-	TunnelID    int64         `gorm:"column:tunnel_id;not null"`
-	TunnelName  string        `gorm:"column:tunnel_name;type:varchar(100);not null"`
-	CreatedTime int64         `gorm:"column:created_time;not null"`
-	UpdatedTime sql.NullInt64 `gorm:"column:updated_time"`
-	Status      int           `gorm:"not null"`
+	ID          int64          `gorm:"primaryKey;autoIncrement"`
+	Name        string         `gorm:"type:varchar(100);not null"`
+	Speed       int            `gorm:"not null"`
+	TunnelID    sql.NullInt64  `gorm:"column:tunnel_id"`
+	TunnelName  sql.NullString `gorm:"column:tunnel_name;type:varchar(100)"`
+	CreatedTime int64          `gorm:"column:created_time;not null"`
+	UpdatedTime sql.NullInt64  `gorm:"column:updated_time"`
+	Status      int            `gorm:"not null"`
 }
 
 func (SpeedLimit) TableName() string { return "speed_limit" }
@@ -395,6 +396,7 @@ type ForwardBackup struct {
 	UpdatedTime  int64                `json:"updatedTime"`
 	Status       int                  `json:"status"`
 	Inx          int                  `json:"inx"`
+	SpeedID      *int64               `json:"speedId,omitempty"`
 	ForwardPorts *[]ForwardPortBackup `json:"forwardPorts,omitempty"`
 }
 
@@ -421,8 +423,8 @@ type SpeedLimitBackup struct {
 	ID          int64  `json:"id"`
 	Name        string `json:"name"`
 	Speed       int64  `json:"speed"`
-	TunnelID    int64  `json:"tunnelId"`
-	TunnelName  string `json:"tunnelName"`
+	TunnelID    *int64 `json:"tunnelId,omitempty"`
+	TunnelName  string `json:"tunnelName,omitempty"`
 	CreatedTime int64  `json:"createdTime"`
 	UpdatedTime int64  `json:"updatedTime,omitempty"`
 	Status      int    `json:"status"`
@@ -492,6 +494,7 @@ type ForwardRecord struct {
 	RemoteAddr string
 	Strategy   string
 	Status     int
+	SpeedID    sql.NullInt64
 }
 
 // TunnelRecord is a minimal tunnel view used by control plane.

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

@@ -127,6 +127,11 @@ func OpenPostgres(dsn string) (*Repository, error) {
 		return nil, err
 	}
 
+	if err := preparePostgresLegacySchema(db); err != nil {
+		_ = sqlDB.Close()
+		return nil, fmt.Errorf("prepare postgres legacy schema: %w", err)
+	}
+
 	if err := autoMigrateAll(db); err != nil {
 		_ = sqlDB.Close()
 		return nil, fmt.Errorf("auto migrate: %w", err)
@@ -205,6 +210,49 @@ func autoMigrateAll(db *gorm.DB) error {
 	return nil
 }
 
+// preparePostgresLegacySchema renames unique constraints that were created by
+// the old schema.sql (which used inline UNIQUE column syntax) to the names
+// expected by GORM's NamingStrategy ("uni_<table>_<column>"). Without this,
+// GORM's AutoMigrate emits "DROP CONSTRAINT uni_..." against constraints that
+// don't exist under that name, crashing startup on upgraded PostgreSQL installs.
+func preparePostgresLegacySchema(db *gorm.DB) error {
+	if db == nil || db.Dialector.Name() != "postgres" {
+		return nil
+	}
+
+	type rename struct{ table, oldName, newName string }
+	renames := []rename{
+		{"vite_config", "vite_config_name_key", "uni_vite_config_name"},
+		{"peer_share", "peer_share_token_key", "uni_peer_share_token"},
+		{"peer_share_runtime", "peer_share_runtime_reservation_id_key", "uni_peer_share_runtime_reservation_id"},
+		{"peer_share_runtime", "peer_share_runtime_resource_key_key", "uni_peer_share_runtime_resource_key"},
+		{"federation_tunnel_binding", "federation_tunnel_binding_resource_key_key", "uni_federation_tunnel_binding_resource_key"},
+	}
+
+	for _, r := range renames {
+		var count int64
+		if err := db.Raw(
+			`SELECT COUNT(*) FROM information_schema.table_constraints
+			 WHERE constraint_schema = current_schema()
+			   AND table_name = ?
+			   AND constraint_name = ?
+			   AND constraint_type = 'UNIQUE'`,
+			r.table, r.oldName,
+		).Scan(&count).Error; err != nil {
+			return fmt.Errorf("check constraint %s.%s: %w", r.table, r.oldName, err)
+		}
+		if count == 0 {
+			continue
+		}
+		if err := db.Exec(
+			fmt.Sprintf(`ALTER TABLE %q RENAME CONSTRAINT %q TO %q`, r.table, r.oldName, r.newName),
+		).Error; err != nil {
+			return fmt.Errorf("rename constraint %s.%s→%s: %w", r.table, r.oldName, r.newName, err)
+		}
+	}
+	return nil
+}
+
 func prepareSQLiteLegacyColumns(db *gorm.DB) error {
 	if db == nil || db.Dialector.Name() != "sqlite" {
 		return nil
@@ -608,7 +656,7 @@ func (r *Repository) ListUsers() ([]map[string]interface{}, error) {
 		return nil, errors.New("repository not initialized")
 	}
 	var users []model.User
-	if err := r.db.Where("role_id != ?", 0).Order("id ASC").Find(&users).Error; err != nil {
+	if err := r.db.Where("role_id != ?", 0).Order("id DESC").Find(&users).Error; err != nil {
 		return nil, err
 	}
 	items := make([]map[string]interface{}, 0, len(users))
@@ -630,17 +678,23 @@ func (r *Repository) ListSpeedLimits() ([]map[string]interface{}, error) {
 		return nil, errors.New("repository not initialized")
 	}
 	var limits []model.SpeedLimit
-	if err := r.db.Order("id ASC").Find(&limits).Error; err != nil {
+	if err := r.db.Order("id DESC").Find(&limits).Error; err != nil {
 		return nil, err
 	}
 	items := make([]map[string]interface{}, 0, len(limits))
 	for _, sl := range limits {
-		items = append(items, map[string]interface{}{
+		item := map[string]interface{}{
 			"id": sl.ID, "name": sl.Name, "speed": sl.Speed,
-			"tunnelId": sl.TunnelID, "tunnelName": sl.TunnelName,
 			"status": sl.Status, "createdTime": sl.CreatedTime,
 			"updatedTime": nullableInt64(sl.UpdatedTime),
-		})
+		}
+		if sl.TunnelID.Valid {
+			item["tunnelId"] = sl.TunnelID.Int64
+		}
+		if sl.TunnelName.Valid {
+			item["tunnelName"] = sl.TunnelName.String
+		}
+		items = append(items, item)
 	}
 	return items, nil
 }
@@ -664,11 +718,12 @@ func (r *Repository) ListForwards() ([]map[string]interface{}, error) {
 		CreatedTime int64
 		Status      int
 		Inx         int
+		SpeedID     sql.NullInt64
 	}
 
 	var rows []fwdRow
 	err := r.db.Model(&model.Forward{}).
-		Select("forward.id, forward.user_id, forward.user_name, forward.name, forward.tunnel_id, COALESCE(tunnel.name, '') AS tunnel_name, forward.remote_addr, COALESCE(forward.strategy, 'fifo') AS strategy, forward.in_flow, forward.out_flow, forward.created_time, forward.status, forward.inx").
+		Select("forward.id, forward.user_id, forward.user_name, forward.name, forward.tunnel_id, COALESCE(tunnel.name, '') AS tunnel_name, forward.remote_addr, COALESCE(forward.strategy, 'fifo') AS strategy, forward.in_flow, forward.out_flow, forward.created_time, forward.status, forward.inx, forward.speed_id").
 		Joins("LEFT JOIN tunnel ON tunnel.id = forward.tunnel_id").
 		Order("forward.inx ASC, forward.id ASC").
 		Find(&rows).Error
@@ -682,14 +737,18 @@ func (r *Repository) ListForwards() ([]map[string]interface{}, error) {
 		if err != nil {
 			return nil, err
 		}
-		items = append(items, map[string]interface{}{
+		item := map[string]interface{}{
 			"id": row.ID, "userId": row.UserID, "userName": row.UserName,
 			"name": row.Name, "tunnelId": row.TunnelID, "tunnelName": row.TunnelName,
 			"inIp": nullableForwardIngress(inIP), "inPort": nullableInt64(inPort),
 			"remoteAddr": row.RemoteAddr, "strategy": row.Strategy,
 			"inFlow": row.InFlow, "outFlow": row.OutFlow,
 			"createdTime": row.CreatedTime, "status": row.Status, "inx": int64(row.Inx),
-		})
+		}
+		if row.SpeedID.Valid {
+			item["speedId"] = row.SpeedID.Int64
+		}
+		items = append(items, item)
 	}
 	return items, nil
 }
@@ -1222,6 +1281,175 @@ func (r *Repository) ListActivePeerShareRuntimePorts(shareID int64, nodeID int64
 	return ports, nil
 }
 
+func (r *Repository) ListActiveForwardPeerShareRuntimesByServiceName(serviceName string) ([]model.PeerShareRuntime, error) {
+	if r == nil || r.db == nil {
+		return nil, errors.New("repository not initialized")
+	}
+	var items []model.PeerShareRuntime
+	err := r.db.Where("service_name = ? AND status = 1 AND role = ?", serviceName, "forward").
+		Order("id ASC").
+		Find(&items).Error
+	if err != nil {
+		return nil, err
+	}
+	if items == nil {
+		items = make([]model.PeerShareRuntime, 0)
+	}
+	return items, nil
+}
+
+func (r *Repository) ListActiveForwardPeerShareRuntimesByNodeAndServiceName(nodeID int64, serviceName string) ([]model.PeerShareRuntime, error) {
+	if r == nil || r.db == nil {
+		return nil, errors.New("repository not initialized")
+	}
+	serviceName = strings.TrimSpace(serviceName)
+	if serviceName == "" {
+		return []model.PeerShareRuntime{}, nil
+	}
+	var items []model.PeerShareRuntime
+	err := r.db.Where("node_id = ? AND service_name = ? AND status = 1 AND role = ?", nodeID, serviceName, "forward").
+		Order("id ASC").
+		Find(&items).Error
+	if err != nil {
+		return nil, err
+	}
+	if items == nil {
+		items = make([]model.PeerShareRuntime, 0)
+	}
+	return items, nil
+}
+
+func (r *Repository) ListActiveForwardPeerShareRuntimeServiceNamesByNode(nodeID int64) ([]string, 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
+	if err != nil {
+		return nil, err
+	}
+	if names == nil {
+		names = make([]string, 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
+}
+
+func (r *Repository) GetActiveForwardPeerShareRuntimeByPort(shareID int64, port int) (*model.PeerShareRuntime, error) {
+	if r == nil || r.db == nil {
+		return nil, errors.New("repository not initialized")
+	}
+	var item model.PeerShareRuntime
+	err := r.db.Where("share_id = ? AND port = ? AND status = 1 AND role = ?", shareID, port, "forward").First(&item).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	return &item, nil
+}
+
+func (r *Repository) GetActiveForwardPeerShareRuntimeByServiceName(shareID int64, serviceName string) (*model.PeerShareRuntime, error) {
+	if r == nil || r.db == nil {
+		return nil, errors.New("repository not initialized")
+	}
+	serviceName = strings.TrimSpace(serviceName)
+	if shareID <= 0 || serviceName == "" {
+		return nil, nil
+	}
+	var item model.PeerShareRuntime
+	err := r.db.Where("share_id = ? AND service_name = ? AND status = 1 AND role = ?", shareID, serviceName, "forward").
+		Order("id ASC").
+		First(&item).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	return &item, nil
+}
+
+func (r *Repository) ExistsActivePeerShareRuntimeOnNodePort(nodeID int64, port int) (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 port = ? AND status = 1", nodeID, port).
+		Count(&count).Error
+	if err != nil {
+		return false, err
+	}
+	return count > 0, nil
+}
+
+func (r *Repository) UpdatePeerShareRuntimeServiceName(id int64, serviceName string, updatedTime 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{}{
+		"service_name": serviceName,
+		"applied":      1,
+		"updated_time": updatedTime,
+	}).Error
+}
+
+func (r *Repository) MarkPeerShareRuntimeReleasedByPort(shareID int64, port int, updatedTime int64) error {
+	if r == nil || r.db == nil {
+		return errors.New("repository not initialized")
+	}
+	if shareID <= 0 || port <= 0 {
+		return nil
+	}
+	if updatedTime <= 0 {
+		updatedTime = unixMilliNow()
+	}
+	return r.db.Model(&model.PeerShareRuntime{}).Where("share_id = ? AND port = ? AND status = 1", shareID, port).Updates(map[string]interface{}{
+		"status":       0,
+		"applied":      0,
+		"service_name": "",
+		"updated_time": updatedTime,
+	}).Error
+}
+
+func (r *Repository) MarkForwardPeerShareRuntimeReleasedByServiceName(shareID int64, serviceName string, updatedTime int64) error {
+	if r == nil || r.db == nil {
+		return errors.New("repository not initialized")
+	}
+	serviceName = strings.TrimSpace(serviceName)
+	if shareID <= 0 || serviceName == "" {
+		return nil
+	}
+	if updatedTime <= 0 {
+		updatedTime = unixMilliNow()
+	}
+	return r.db.Model(&model.PeerShareRuntime{}).
+		Where("share_id = ? AND status = 1 AND role = ? AND service_name = ?", shareID, "forward", serviceName).
+		Updates(map[string]interface{}{
+			"status":       0,
+			"applied":      0,
+			"service_name": "",
+			"updated_time": updatedTime,
+		}).Error
+}
+
 // ─── FederationTunnelBinding ─────────────────────────────────────────
 
 func (r *Repository) UpsertFederationTunnelBinding(item *model.FederationTunnelBinding) error {
@@ -1595,9 +1823,15 @@ func (r *Repository) exportSpeedLimits() ([]model.SpeedLimitBackup, error) {
 	for _, sl := range sls {
 		b := model.SpeedLimitBackup{
 			ID: sl.ID, Name: sl.Name, Speed: int64(sl.Speed),
-			TunnelID: sl.TunnelID, TunnelName: sl.TunnelName,
 			CreatedTime: sl.CreatedTime, Status: sl.Status,
 		}
+		if sl.TunnelID.Valid {
+			tid := sl.TunnelID.Int64
+			b.TunnelID = &tid
+		}
+		if sl.TunnelName.Valid {
+			b.TunnelName = sl.TunnelName.String
+		}
 		if sl.UpdatedTime.Valid {
 			b.UpdatedTime = sl.UpdatedTime.Int64
 		}
@@ -1968,12 +2202,18 @@ func importSpeedLimits(tx *gorm.DB, speedLimits []model.SpeedLimitBackup, now in
 			ID:          sl.ID,
 			Name:        sl.Name,
 			Speed:       int(sl.Speed),
-			TunnelID:    sl.TunnelID,
-			TunnelName:  sl.TunnelName,
+			TunnelID:    sql.NullInt64{Int64: 0, Valid: false},
+			TunnelName:  sql.NullString{String: "", Valid: false},
 			CreatedTime: sl.CreatedTime,
 			UpdatedTime: sql.NullInt64{Int64: now, Valid: true},
 			Status:      sl.Status,
 		}
+		if sl.TunnelID != nil {
+			item.TunnelID = sql.NullInt64{Int64: *sl.TunnelID, Valid: true}
+		}
+		if sl.TunnelName != "" {
+			item.TunnelName = sql.NullString{String: sl.TunnelName, Valid: true}
+		}
 		err := tx.Clauses(clause.OnConflict{
 			Columns: []clause.Column{{Name: "id"}},
 			DoUpdates: clause.AssignmentColumns([]string{
@@ -2187,7 +2427,7 @@ func (r *Repository) ListExpiredActiveUserIDs(nowMs int64) ([]int64, error) {
 	}
 	var ids []int64
 	err := r.db.Model(&model.User{}).
-		Where("role_id != 0 AND status = 1 AND exp_time IS NOT NULL AND exp_time < ?", nowMs).
+		Where("role_id != 0 AND status = 1 AND exp_time > 0 AND exp_time < ?", nowMs).
 		Pluck("id", &ids).Error
 	if err != nil {
 		return nil, err
@@ -2207,7 +2447,7 @@ func (r *Repository) ListExpiredActiveUserTunnels(nowMs int64) ([]model.ExpiredU
 		return nil, errors.New("repository not initialized")
 	}
 	var uts []model.UserTunnel
-	err := r.db.Where("status = 1 AND exp_time IS NOT NULL AND exp_time < ?", nowMs).Find(&uts).Error
+	err := r.db.Where("status = 1 AND exp_time > 0 AND exp_time < ?", nowMs).Find(&uts).Error
 	if err != nil {
 		return nil, err
 	}

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

@@ -46,6 +46,7 @@ func (r *Repository) ListForwardsByTunnel(tunnelID int64) ([]model.ForwardRecord
 			RemoteAddr: f.RemoteAddr,
 			Strategy:   f.Strategy,
 			Status:     f.Status,
+			SpeedID:    f.SpeedID,
 		})
 	}
 	for i := range rows {
@@ -56,6 +57,40 @@ func (r *Repository) ListForwardsByTunnel(tunnelID int64) ([]model.ForwardRecord
 	return rows, nil
 }
 
+func (r *Repository) ListActiveTunnelIDsByNode(nodeID int64) ([]int64, error) {
+	if r == nil || r.db == nil {
+		return nil, errors.New("repository not initialized")
+	}
+	var ids []int64
+	err := r.db.Model(&model.ChainTunnel{}).
+		Joins("JOIN tunnel ON tunnel.id = chain_tunnel.tunnel_id").
+		Where("chain_tunnel.node_id = ? AND tunnel.status = 1", nodeID).
+		Select("DISTINCT chain_tunnel.tunnel_id").
+		Order("chain_tunnel.tunnel_id ASC").
+		Pluck("chain_tunnel.tunnel_id", &ids).Error
+	if err != nil {
+		return nil, err
+	}
+	return ids, nil
+}
+
+func (r *Repository) ListActiveForwardIDsByNode(nodeID int64) ([]int64, error) {
+	if r == nil || r.db == nil {
+		return nil, errors.New("repository not initialized")
+	}
+	var ids []int64
+	err := r.db.Model(&model.ForwardPort{}).
+		Joins("JOIN forward ON forward.id = forward_port.forward_id").
+		Where("forward_port.node_id = ? AND forward.status = 1", nodeID).
+		Select("DISTINCT forward_port.forward_id").
+		Order("forward_port.forward_id ASC").
+		Pluck("forward_port.forward_id", &ids).Error
+	if err != nil {
+		return nil, err
+	}
+	return ids, nil
+}
+
 func (r *Repository) ListForwardPorts(forwardID int64) ([]model.ForwardPortRecord, error) {
 	if r == nil || r.db == nil {
 		return nil, errors.New("repository not initialized")

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

@@ -38,6 +38,14 @@ type FederationBindingRow struct {
 	UpdatedTime     int64
 }
 
+type ActiveForwardPortRow struct {
+	ForwardID   int64
+	TunnelID    int64
+	TunnelName  string
+	Port        int
+	UpdatedTime int64
+}
+
 // ListRemoteNodes returns all nodes with is_remote=1, ordered by id desc.
 func (r *Repository) ListRemoteNodes() ([]RemoteNodeRow, error) {
 	if r == nil || r.db == nil {
@@ -87,6 +95,27 @@ func (r *Repository) ListActiveBindingsForNode(nodeID int64) ([]FederationBindin
 	return result, nil
 }
 
+func (r *Repository) ListActiveForwardPortsForNode(nodeID int64) ([]ActiveForwardPortRow, error) {
+	if r == nil || r.db == nil {
+		return nil, errors.New("repository not initialized")
+	}
+	var result []ActiveForwardPortRow
+	err := r.db.Model(&model.ForwardPort{}).
+		Select("forward_port.forward_id, forward.tunnel_id, COALESCE(tunnel.name, '') AS tunnel_name, forward_port.port, forward.updated_time").
+		Joins("JOIN forward ON forward.id = forward_port.forward_id").
+		Joins("LEFT JOIN tunnel ON tunnel.id = forward.tunnel_id").
+		Where("forward_port.node_id = ? AND forward_port.port > 0", nodeID).
+		Order("forward_port.port ASC, forward_port.id ASC").
+		Find(&result).Error
+	if err != nil {
+		return nil, err
+	}
+	if result == nil {
+		result = make([]ActiveForwardPortRow, 0)
+	}
+	return result, nil
+}
+
 // GetNodeBasicInfo returns the name, server_ip, and status for a given node.
 func (r *Repository) GetNodeBasicInfo(nodeID int64) (*NodeBasicInfo, error) {
 	if r == nil || r.db == nil {
@@ -199,7 +228,6 @@ func (r *Repository) ListTunnelIDsByNamePrefix(prefix string) ([]int64, error) {
 	return ids, nil
 }
 
-// NextIndex returns COALESCE(MAX(inx), -1) + 1 for the given table.
 func (r *Repository) NextIndex(table string) int {
 	if r == nil || r.db == nil {
 		return 0
@@ -222,7 +250,7 @@ func (r *Repository) NextIndex(table string) int {
 	var row inxRow
 	err := r.db.Model(modelRef).
 		Select("inx").
-		Order("inx DESC").
+		Order("inx ASC, id ASC").
 		Limit(1).
 		Take(&row).Error
 	if errors.Is(err, gorm.ErrRecordNotFound) {
@@ -231,10 +259,7 @@ func (r *Repository) NextIndex(table string) int {
 	if err != nil {
 		return 0
 	}
-	if row.Inx < 0 {
-		return 0
-	}
-	return row.Inx + 1
+	return row.Inx - 1
 }
 
 // CreateRemoteNode inserts a new remote node.

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

@@ -38,6 +38,7 @@ func (r *Repository) ListActiveForwardsByUser(userID int64) ([]model.ForwardReco
 			RemoteAddr: f.RemoteAddr,
 			Strategy:   f.Strategy,
 			Status:     f.Status,
+			SpeedID:    f.SpeedID,
 		})
 	}
 	for i := range rows {
@@ -68,6 +69,7 @@ func (r *Repository) ListActiveForwardsByUserTunnel(userID, tunnelID int64) ([]m
 			RemoteAddr: f.RemoteAddr,
 			Strategy:   f.Strategy,
 			Status:     f.Status,
+			SpeedID:    f.SpeedID,
 		})
 	}
 	for i := range rows {
@@ -99,6 +101,7 @@ func (r *Repository) GetForwardRecord(forwardID int64) (*model.ForwardRecord, er
 		RemoteAddr: f.RemoteAddr,
 		Strategy:   f.Strategy,
 		Status:     f.Status,
+		SpeedID:    f.SpeedID,
 	}
 	if strings.TrimSpace(fr.Strategy) == "" {
 		fr.Strategy = "fifo"
@@ -169,3 +172,15 @@ func (r *Repository) SpeedLimitExists(id int64) (bool, error) {
 	}
 	return count > 0, nil
 }
+
+func (r *Repository) GetSpeedLimitSpeed(id int64) (int, error) {
+	if r == nil || r.db == nil {
+		return 0, errors.New("repository not initialized")
+	}
+	var sl model.SpeedLimit
+	err := r.db.Select("speed").Where("id = ?", id).First(&sl).Error
+	if err != nil {
+		return 0, err
+	}
+	return sl.Speed, nil
+}

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

@@ -50,8 +50,17 @@ func (r *Repository) ListGroupPermissionPairsByUserGroup(userGroupID int64) ([][
 	return result, err
 }
 
-// ListGroupPermissionPairsByTunnelGroup returns [userGroupID, tunnelGroupID] pairs
-// for all group permissions associated with a tunnel group.
+func (r *Repository) GetUserGroupIDsByUserID(userID int64) ([]int64, error) {
+	if r == nil || r.db == nil {
+		return nil, errors.New("repository not initialized")
+	}
+	var ids []int64
+	err := r.db.Model(&model.UserGroupUser{}).
+		Where("user_id = ?", userID).
+		Pluck("user_group_id", &ids).Error
+	return ids, err
+}
+
 func (r *Repository) ListGroupPermissionPairsByTunnelGroup(tunnelGroupID int64) ([][2]int64, error) {
 	if r == nil || r.db == nil {
 		return nil, errors.New("repository not initialized")

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

@@ -34,9 +34,9 @@ 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 int, now int64) error {
+func (r *Repository) CreateUser(username, pwdHash string, roleID int, expTime, flow, flowResetTime int64, num, status int, now int64) (int64, error) {
 	if r == nil || r.db == nil {
-		return errors.New("repository not initialized")
+		return 0, errors.New("repository not initialized")
 	}
 	user := model.User{
 		User:          username,
@@ -52,7 +52,10 @@ func (r *Repository) CreateUser(username, pwdHash string, roleID int, expTime, f
 		UpdatedTime:   sql.NullInt64{Int64: now, Valid: true},
 		Status:        status,
 	}
-	return r.db.Create(&user).Error
+	if err := r.db.Create(&user).Error; err != nil {
+		return 0, err
+	}
+	return user.ID, nil
 }
 
 func (r *Repository) GetUserRoleID(userID int64) (int, error) {
@@ -654,7 +657,7 @@ func (r *Repository) GetMinForwardPort(forwardID int64) sql.NullInt64 {
 	return p
 }
 
-func (r *Repository) UpdateForward(id int64, name string, tunnelID int64, remoteAddr, strategy string, now int64) error {
+func (r *Repository) UpdateForward(id int64, name string, tunnelID int64, remoteAddr, strategy string, now int64, speedID interface{}) error {
 	if r == nil || r.db == nil {
 		return errors.New("repository not initialized")
 	}
@@ -665,6 +668,7 @@ func (r *Repository) UpdateForward(id int64, name string, tunnelID int64, remote
 			"tunnel_id":    tunnelID,
 			"remote_addr":  remoteAddr,
 			"strategy":     strategy,
+			"speed_id":     nullInt64FromInterface(speedID),
 			"updated_time": now,
 		}).Error
 }
@@ -721,7 +725,7 @@ func (r *Repository) ReplaceForwardPorts(forwardID int64, entries []struct {
 	})
 }
 
-func (r *Repository) RollbackForwardFields(id, userID int64, userName, name string, tunnelID int64, remoteAddr, strategy string, status int, now int64) {
+func (r *Repository) RollbackForwardFields(id, userID int64, userName, name string, tunnelID int64, remoteAddr, strategy string, status int, speedID interface{}, now int64) {
 	if r == nil || r.db == nil {
 		return
 	}
@@ -735,6 +739,7 @@ func (r *Repository) RollbackForwardFields(id, userID int64, userName, name stri
 			"remote_addr":  remoteAddr,
 			"strategy":     strategy,
 			"status":       status,
+			"speed_id":     nullInt64FromInterface(speedID),
 			"updated_time": now,
 		}).Error
 }
@@ -761,51 +766,66 @@ func (r *Repository) GetUsedPortsOnNodeAsMap(nodeID int64) (map[int]bool, error)
 	return used, nil
 }
 
-func (r *Repository) CreateSpeedLimit(name string, speed int, tunnelID int64, tunnelName string, now int64, status int) (int64, error) {
+func (r *Repository) CreateSpeedLimit(name string, speed int, tunnelID *int64, tunnelName string, now int64, status int) (int64, error) {
 	if r == nil || r.db == nil {
 		return 0, errors.New("repository not initialized")
 	}
 	sl := model.SpeedLimit{
 		Name:        name,
 		Speed:       speed,
-		TunnelID:    tunnelID,
-		TunnelName:  tunnelName,
+		TunnelID:    sql.NullInt64{Int64: 0, Valid: false},
+		TunnelName:  sql.NullString{String: "", Valid: false},
 		CreatedTime: now,
 		UpdatedTime: sql.NullInt64{Int64: now, Valid: true},
 		Status:      status,
 	}
+	if tunnelID != nil {
+		sl.TunnelID = sql.NullInt64{Int64: *tunnelID, Valid: true}
+	}
+	if tunnelName != "" {
+		sl.TunnelName = sql.NullString{String: tunnelName, Valid: true}
+	}
 	if err := r.db.Create(&sl).Error; err != nil {
 		return 0, err
 	}
 	return sl.ID, nil
 }
 
-func (r *Repository) UpdateSpeedLimit(id int64, name string, speed int, tunnelID int64, tunnelName string, status int, now int64) error {
+func (r *Repository) UpdateSpeedLimit(id int64, name string, speed int, tunnelID *int64, tunnelName string, status int, now int64) error {
 	if r == nil || r.db == nil {
 		return errors.New("repository not initialized")
 	}
+	updates := map[string]interface{}{
+		"name":   name,
+		"speed":  speed,
+		"status": status,
+		"updated_time": sql.NullInt64{
+			Int64: now,
+			Valid: true,
+		},
+	}
+	if tunnelID != nil {
+		updates["tunnel_id"] = sql.NullInt64{Int64: *tunnelID, Valid: true}
+	} else {
+		updates["tunnel_id"] = sql.NullInt64{Int64: 0, Valid: false}
+	}
+	if tunnelName != "" {
+		updates["tunnel_name"] = sql.NullString{String: tunnelName, Valid: true}
+	} else {
+		updates["tunnel_name"] = sql.NullString{String: "", Valid: false}
+	}
 	return r.db.Model(&model.SpeedLimit{}).
 		Where("id = ?", id).
-		Updates(map[string]interface{}{
-			"name":        name,
-			"speed":       speed,
-			"tunnel_id":   tunnelID,
-			"tunnel_name": tunnelName,
-			"status":      status,
-			"updated_time": sql.NullInt64{
-				Int64: now,
-				Valid: true,
-			},
-		}).Error
+		Updates(updates).Error
 }
 
-func (r *Repository) GetSpeedLimitTunnelID(speedLimitID int64) int64 {
+func (r *Repository) GetSpeedLimitTunnelID(speedLimitID int64) sql.NullInt64 {
 	if r == nil || r.db == nil {
-		return 0
+		return sql.NullInt64{Valid: false}
 	}
 	var sl model.SpeedLimit
 	if err := r.db.Select("tunnel_id").Where("id = ?", speedLimitID).First(&sl).Error; err != nil {
-		return 0
+		return sql.NullInt64{Valid: false}
 	}
 	return sl.TunnelID
 }
@@ -1187,7 +1207,7 @@ func (r *Repository) EnsureUserTunnelGrant(userID, tunnelID int64) (int64, bool,
 	return ut.ID, true, nil
 }
 
-func (r *Repository) CreateForwardTx(userID int64, userName, name string, tunnelID int64, remoteAddr, strategy string, now int64, inx int, entryNodeIDs []int64, port int) (int64, error) {
+func (r *Repository) CreateForwardTx(userID int64, userName, name string, tunnelID int64, remoteAddr, strategy string, now int64, inx int, entryNodeIDs []int64, port int, speedID interface{}) (int64, error) {
 	if r == nil || r.db == nil {
 		return 0, errors.New("repository not initialized")
 	}
@@ -1206,6 +1226,7 @@ func (r *Repository) CreateForwardTx(userID int64, userName, name string, tunnel
 			UpdatedTime: now,
 			Status:      1,
 			Inx:         inx,
+			SpeedID:     nullInt64FromInterface(speedID),
 		}
 		if err := tx.Create(&fwd).Error; err != nil {
 			return err
@@ -1406,3 +1427,70 @@ func parsePortRangeSpec(input string) []int {
 	sort.Ints(out)
 	return out
 }
+
+func (r *Repository) AddUserToGroups(userID int64, groupIDs []int64, now int64) error {
+	if r == nil || r.db == nil {
+		return errors.New("repository not initialized")
+	}
+	if len(groupIDs) == 0 {
+		return nil
+	}
+	rows := make([]model.UserGroupUser, 0, len(groupIDs))
+	for _, gid := range groupIDs {
+		if gid <= 0 {
+			continue
+		}
+		rows = append(rows, model.UserGroupUser{UserGroupID: gid, UserID: userID, CreatedTime: now})
+	}
+	if len(rows) == 0 {
+		return nil
+	}
+	return r.db.Clauses(clause.OnConflict{DoNothing: true}).Create(&rows).Error
+}
+
+func (r *Repository) ReplaceUserGroupsByUserID(userID int64, newGroupIDs []int64, now int64) (affectedGroupIDs []int64, err error) {
+	if r == nil || r.db == nil {
+		return nil, errors.New("repository not initialized")
+	}
+
+	var oldGroupIDs []int64
+	if err = r.db.Model(&model.UserGroupUser{}).
+		Where("user_id = ?", userID).
+		Pluck("user_group_id", &oldGroupIDs).Error; err != nil {
+		return nil, err
+	}
+
+	seen := make(map[int64]struct{})
+	for _, id := range oldGroupIDs {
+		seen[id] = struct{}{}
+	}
+	for _, id := range newGroupIDs {
+		if id > 0 {
+			seen[id] = struct{}{}
+		}
+	}
+	for id := range seen {
+		affectedGroupIDs = append(affectedGroupIDs, id)
+	}
+
+	if err = r.db.Where("user_id = ?", userID).Delete(&model.UserGroupUser{}).Error; err != nil {
+		return nil, err
+	}
+
+	if len(newGroupIDs) == 0 {
+		return affectedGroupIDs, nil
+	}
+	rows := make([]model.UserGroupUser, 0, len(newGroupIDs))
+	for _, gid := range newGroupIDs {
+		if gid <= 0 {
+			continue
+		}
+		rows = append(rows, model.UserGroupUser{UserGroupID: gid, UserID: userID, CreatedTime: now})
+	}
+	if len(rows) > 0 {
+		if err = r.db.Clauses(clause.OnConflict{DoNothing: true}).Create(&rows).Error; err != nil {
+			return nil, err
+		}
+	}
+	return affectedGroupIDs, nil
+}

go-backend/internal/ws/server.go

@@ -68,9 +68,10 @@ type CommandResult struct {
 }
 
 type Server struct {
-	repo      *repo.Repository
-	jwtSecret string
-	upgrader  websocket.Upgrader
+	repo         *repo.Repository
+	jwtSecret    string
+	upgrader     websocket.Upgrader
+	onNodeOnline func(nodeID int64)
 
 	mu      sync.RWMutex
 	admins  map[*connWrap]struct{}
@@ -79,6 +80,15 @@ type Server struct {
 	pending map[string]pendingRequest
 }
 
+func (s *Server) SetNodeOnlineHook(fn func(nodeID int64)) {
+	if s == nil {
+		return
+	}
+	s.mu.Lock()
+	s.onNodeOnline = fn
+	s.mu.Unlock()
+}
+
 func NewServer(repo *repo.Repository, jwtSecret string) *Server {
 	return &Server{
 		repo:      repo,
@@ -183,6 +193,13 @@ func (s *Server) handleNode(w http.ResponseWriter, r *http.Request, nodeID int64
 	_ = s.repo.UpdateNodeOnline(nodeID, 1, version, httpVal, tlsVal, socksVal)
 	s.broadcastStatus(nodeID, 1)
 
+	s.mu.RLock()
+	onlineHook := s.onNodeOnline
+	s.mu.RUnlock()
+	if onlineHook != nil {
+		go onlineHook(nodeID)
+	}
+
 	defer func() {
 		close(done)
 		needOfflineBroadcast := false

go-backend/tests/contract/diagnosis_contract_test.go

@@ -193,6 +193,126 @@ func TestDiagnosisChainCoverageContracts(t *testing.T) {
 	})
 }
 
+func TestForwardDiagnosisRespectsTunnelIPPreferenceContract(t *testing.T) {
+	secret := "contract-jwt-secret"
+	router, r := setupDiagnosisContractRouter(t, secret)
+	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, 'normal_user', '3c85cdebade1c51cf64ca9f3c09d182d', 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, ip_preference)
+		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, "diagnose-ip-pref-forward", 1.0, 2, "tls", 99999, now, now, 1, nil, 0, "v6").Error; err != nil {
+		t.Fatalf("insert tunnel: %v", err)
+	}
+	tunnelID := mustLastInsertID(t, r, "diagnose-ip-pref-forward")
+
+	insertNode := func(name, v4, v6 string) 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, name+"-secret", v4, v4, v6, "30000-30010", "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", 0).Error; err != nil {
+			t.Fatalf("insert node %s: %v", name, err)
+		}
+		return mustLastInsertID(t, r, name)
+	}
+
+	entryNodeID := insertNode("entry-node-v6", "10.10.1.10", "2001:db8:10::10")
+	chainNodeID := insertNode("chain-node-v6", "10.10.1.20", "2001:db8:10::20")
+	exitNodeID := insertNode("exit-node-v6", "10.10.1.30", "2001:db8:10::30")
+
+	if err := r.DB().Exec(`
+		INSERT INTO chain_tunnel(tunnel_id, chain_type, node_id, port, strategy, inx, protocol)
+		VALUES(?, 1, ?, 30001, 'round', 1, 'tls')
+	`, tunnelID, entryNodeID).Error; err != nil {
+		t.Fatalf("insert entry chain: %v", err)
+	}
+	if err := r.DB().Exec(`
+		INSERT INTO chain_tunnel(tunnel_id, chain_type, node_id, port, strategy, inx, protocol)
+		VALUES(?, 2, ?, 30002, 'round', 1, 'tls')
+	`, tunnelID, chainNodeID).Error; err != nil {
+		t.Fatalf("insert middle chain: %v", err)
+	}
+	if err := r.DB().Exec(`
+		INSERT INTO chain_tunnel(tunnel_id, chain_type, node_id, port, strategy, inx, protocol)
+		VALUES(?, 3, ?, 30003, 'round', 1, 'tls')
+	`, tunnelID, exitNodeID).Error; err != nil {
+		t.Fatalf("insert exit chain: %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(?, ?, ?, ?, ?, ?, 0, 0, ?, ?, 1, ?)
+	`, 2, "normal_user", "ip-pref-forward", tunnelID, "8.8.8.8:53", "fifo", now, now, 0).Error; err != nil {
+		t.Fatalf("insert forward: %v", err)
+	}
+	forwardID := mustLastInsertID(t, r, "ip-pref-forward")
+
+	userToken, err := auth.GenerateToken(2, "normal_user", 1, secret)
+	if err != nil {
+		t.Fatalf("generate user token: %v", err)
+	}
+
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/forward/diagnose", bytes.NewBufferString(`{"forwardId":`+strconv.FormatInt(forwardID, 10)+`}`))
+	req.Header.Set("Authorization", userToken)
+	res := httptest.NewRecorder()
+
+	router.ServeHTTP(res, req)
+
+	var out response.R
+	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, got %d (%s)", out.Code, out.Msg)
+	}
+
+	payload, ok := out.Data.(map[string]interface{})
+	if !ok {
+		t.Fatalf("expected object payload, got %T", out.Data)
+	}
+	results, ok := payload["results"].([]interface{})
+	if !ok || len(results) == 0 {
+		t.Fatalf("expected non-empty results, got %v", payload["results"])
+	}
+
+	hasEntryToChain := false
+	hasChainToExit := false
+	for _, raw := range results {
+		item, ok := raw.(map[string]interface{})
+		if !ok {
+			continue
+		}
+		from := valueAsInt(item["fromChainType"])
+		to := valueAsInt(item["toChainType"])
+		targetIP := strings.TrimSpace(valueAsString(item["targetIp"]))
+
+		if from == 1 && to == 2 {
+			hasEntryToChain = true
+			if targetIP != "2001:db8:10::20" {
+				t.Fatalf("expected entry->chain diagnosis target to use IPv6, got %q", targetIP)
+			}
+		}
+
+		if from == 2 && to == 3 {
+			hasChainToExit = true
+			if targetIP != "2001:db8:10::30" {
+				t.Fatalf("expected chain->exit diagnosis target to use IPv6, got %q", targetIP)
+			}
+		}
+	}
+
+	if !hasEntryToChain || !hasChainToExit {
+		t.Fatalf("expected entry->chain and chain->exit steps, got entry=%v chain=%v", hasEntryToChain, hasChainToExit)
+	}
+}
+
 func TestDiagnosisUsesFederationRuntimeForRemoteNodes(t *testing.T) {
 	secret := "contract-jwt-secret"
 	router, r := setupDiagnosisContractRouter(t, secret)

go-backend/tests/contract/federation_dual_panel_contract_test.go

@@ -166,7 +166,7 @@ func TestFederationDualPanelMiddleExitAutoPortContract(t *testing.T) {
 
 	assertCount(t, providerRepo, `SELECT COUNT(1) FROM peer_share_runtime WHERE share_id = ? AND status = 1 AND applied = 1`, middleShareID, 1)
 	assertCount(t, providerRepo, `SELECT COUNT(1) FROM peer_share_runtime WHERE share_id = ? AND status = 1 AND applied = 1`, exitShareID, 1)
-	assertCount(t, providerRepo, `SELECT COUNT(1) FROM peer_share_runtime WHERE share_id = ?`, entryShareID, 0)
+	assertCount(t, providerRepo, `SELECT COUNT(1) FROM peer_share_runtime WHERE share_id = ? AND status = 1 AND applied = 1`, entryShareID, 1)
 }
 
 func TestFederationDualPanelRemoteDiagnosisContract(t *testing.T) {

go-backend/tests/contract/federation_forward_flow_linkage_contract_test.go

@@ -0,0 +1,693 @@
+package contract_test
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"strconv"
+	"strings"
+	"testing"
+	"time"
+
+	"go-backend/internal/auth"
+	"go-backend/internal/http/response"
+	"go-backend/internal/store/repo"
+)
+
+func TestFederationForwardCardFlowLinkageContract(t *testing.T) {
+	secret := "federation-forward-flow-contract-jwt"
+	router, r := setupContractRouter(t, secret)
+
+	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 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(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, "flow-local-node", "flow-local-secret", "10.20.30.40", "10.20.30.40", "", "32000-32020", "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", 0, 0, "", "", "").Error; err != nil {
+		t.Fatalf("insert local node: %v", err)
+	}
+	nodeID := mustLastInsertID(t, r, "flow-local-node")
+
+	shareToken := "flow-linkage-share-token"
+	if err := r.CreatePeerShare(&repo.PeerShare{
+		Name:           "flow-linkage-share",
+		NodeID:         nodeID,
+		Token:          shareToken,
+		MaxBandwidth:   0,
+		CurrentFlow:    1536,
+		ExpiryTime:     0,
+		PortRangeStart: 32000,
+		PortRangeEnd:   32020,
+		IsActive:       1,
+		CreatedTime:    now,
+		UpdatedTime:    now,
+	}); err != nil {
+		t.Fatalf("create share: %v", err)
+	}
+	share, err := r.GetPeerShareByToken(shareToken)
+	if err != nil || share == nil {
+		t.Fatalf("load share: %v", err)
+	}
+
+	tunnelName := fmt.Sprintf("Share-%d-Port-%d", share.ID, 32001)
+	if err := r.DB().Exec(`
+		INSERT INTO tunnel(name, type, protocol, flow, created_time, updated_time, status, in_ip, inx)
+		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, tunnelName, 1, "tcp", 1, now, now, 1, "", 0).Error; err != nil {
+		t.Fatalf("insert share tunnel: %v", err)
+	}
+	tunnelID := mustLastInsertID(t, r, "flow-share-tunnel")
+
+	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(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, 1, "admin_user", "flow-linkage-forward", tunnelID, "1.1.1.1:443", "fifo", 0, 0, now, now, 1, 0).Error; err != nil {
+		t.Fatalf("insert forward: %v", err)
+	}
+	forwardID := mustLastInsertID(t, r, "flow-linkage-forward")
+
+	if err := r.DB().Exec(`INSERT INTO forward_port(forward_id, node_id, port) VALUES(?, ?, ?)`, forwardID, nodeID, 32001).Error; err != nil {
+		t.Fatalf("insert forward_port: %v", err)
+	}
+
+	forwardOut := requestContractEnvelope(t, router, adminToken, "/api/v1/forward/list", nil)
+	if forwardOut.Code != 0 {
+		t.Fatalf("forward list failed: code=%d msg=%q", forwardOut.Code, forwardOut.Msg)
+	}
+	forwardRows := mustContractSlice(t, forwardOut.Data, "forward list data")
+
+	var targetForward map[string]interface{}
+	for _, row := range forwardRows {
+		m, ok := row.(map[string]interface{})
+		if !ok {
+			continue
+		}
+		if contractValueAsInt64(m["id"]) == forwardID {
+			targetForward = m
+			break
+		}
+	}
+	if targetForward == nil {
+		t.Fatalf("target forward %d not found in /forward/list response", forwardID)
+	}
+
+	shareOut := requestContractEnvelope(t, router, adminToken, "/api/v1/federation/share/list", nil)
+	if shareOut.Code != 0 {
+		t.Fatalf("share list failed: code=%d msg=%q", shareOut.Code, shareOut.Msg)
+	}
+	localShareRows := mustContractSlice(t, shareOut.Data, "share list data")
+
+	remoteUsageOut := requestContractEnvelope(t, router, adminToken, "/api/v1/federation/share/remote-usage/list", nil)
+	if remoteUsageOut.Code != 0 {
+		t.Fatalf("remote usage list failed: code=%d msg=%q", remoteUsageOut.Code, remoteUsageOut.Msg)
+	}
+	remoteUsageRows := mustContractSlice(t, remoteUsageOut.Data, "remote usage data")
+	if len(remoteUsageRows) != 0 {
+		t.Fatalf("expected no remote usage rows in local-only fixture, got %d", len(remoteUsageRows))
+	}
+
+	flowByShare := make(map[int64]int64)
+	for _, row := range remoteUsageRows {
+		m, ok := row.(map[string]interface{})
+		if !ok {
+			continue
+		}
+		shareID := contractValueAsInt64(m["shareId"])
+		currentFlow := contractValueAsInt64(m["currentFlow"])
+		if shareID > 0 && currentFlow > 0 {
+			if currentFlow > flowByShare[shareID] {
+				flowByShare[shareID] = currentFlow
+			}
+		}
+	}
+	for _, row := range localShareRows {
+		m, ok := row.(map[string]interface{})
+		if !ok {
+			continue
+		}
+		shareID := contractValueAsInt64(m["id"])
+		currentFlow := contractValueAsInt64(m["currentFlow"])
+		if shareID > 0 && currentFlow > 0 {
+			if currentFlow > flowByShare[shareID] {
+				flowByShare[shareID] = currentFlow
+			}
+		}
+	}
+
+	parsedShareID := contractParseShareIDFromTunnelName(contractValueAsString(targetForward["tunnelName"]))
+	if parsedShareID != share.ID {
+		t.Fatalf("expected parsed shareID=%d, got %d (tunnelName=%q)", share.ID, parsedShareID, contractValueAsString(targetForward["tunnelName"]))
+	}
+
+	forwardCountByShare := make(map[int64]int)
+	for _, row := range forwardRows {
+		m, ok := row.(map[string]interface{})
+		if !ok {
+			continue
+		}
+		sid := contractParseShareIDFromTunnelName(contractValueAsString(m["tunnelName"]))
+		if sid > 0 && flowByShare[sid] > 0 {
+			forwardCountByShare[sid] = forwardCountByShare[sid] + 1
+		}
+	}
+
+	directFlow := contractValueAsInt64(targetForward["inFlow"]) + contractValueAsInt64(targetForward["outFlow"])
+	if directFlow != 0 {
+		t.Fatalf("fixture expectation failed: directFlow should be 0, got %d", directFlow)
+	}
+
+	shareFlow := flowByShare[parsedShareID]
+	if shareFlow <= 0 {
+		t.Fatalf("expected merged share flow > 0 for share %d", parsedShareID)
+	}
+
+	count := forwardCountByShare[parsedShareID]
+	if count <= 0 {
+		count = 1
+	}
+	estimated := shareFlow / int64(count)
+	if estimated < 1 {
+		estimated = 1
+	}
+	displayFlow := estimated
+
+	if displayFlow <= 0 {
+		t.Fatalf("expected displayFlow > 0 after frontend-style merge, got %d", displayFlow)
+	}
+	if displayFlow != share.CurrentFlow {
+		t.Fatalf("expected displayFlow=%d, got %d", share.CurrentFlow, displayFlow)
+	}
+}
+
+func TestFederationForwardCardFlowLinkageContractSplitShareFlowAcrossMultipleForwards(t *testing.T) {
+	secret := "federation-forward-split-flow-contract-jwt"
+	router, r := setupContractRouter(t, secret)
+
+	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 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(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, "flow-split-local-node", "flow-split-local-secret", "10.21.31.41", "10.21.31.41", "", "32100-32120", "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", 0, 0, "", "", "").Error; err != nil {
+		t.Fatalf("insert local node: %v", err)
+	}
+	nodeID := mustLastInsertID(t, r, "flow-split-local-node")
+
+	shareToken := "flow-split-share-token"
+	if err := r.CreatePeerShare(&repo.PeerShare{
+		Name:           "flow-split-share",
+		NodeID:         nodeID,
+		Token:          shareToken,
+		MaxBandwidth:   0,
+		CurrentFlow:    4097,
+		ExpiryTime:     0,
+		PortRangeStart: 32100,
+		PortRangeEnd:   32120,
+		IsActive:       1,
+		CreatedTime:    now,
+		UpdatedTime:    now,
+	}); err != nil {
+		t.Fatalf("create share: %v", err)
+	}
+	share, err := r.GetPeerShareByToken(shareToken)
+	if err != nil || share == nil {
+		t.Fatalf("load share: %v", err)
+	}
+
+	createShareForward := func(name string, port int) int64 {
+		t.Helper()
+
+		tunnelName := fmt.Sprintf("Share-%d-Port-%d", share.ID, port)
+		if err := r.DB().Exec(`
+			INSERT INTO tunnel(name, type, protocol, flow, created_time, updated_time, status, in_ip, inx)
+			VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?)
+		`, tunnelName, 1, "tcp", 1, now, now, 1, "", 0).Error; err != nil {
+			t.Fatalf("insert share tunnel: %v", err)
+		}
+		tunnelID := mustLastInsertID(t, r, "flow-split-tunnel")
+
+		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(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+		`, 1, "admin_user", name, tunnelID, "1.1.1.1:443", "fifo", 0, 0, now, now, 1, 0).Error; err != nil {
+			t.Fatalf("insert forward: %v", err)
+		}
+		forwardID := mustLastInsertID(t, r, name)
+
+		if err := r.DB().Exec(`INSERT INTO forward_port(forward_id, node_id, port) VALUES(?, ?, ?)`, forwardID, nodeID, port).Error; err != nil {
+			t.Fatalf("insert forward_port: %v", err)
+		}
+
+		return forwardID
+	}
+
+	forwardIDA := createShareForward("flow-split-forward-a", 32101)
+	forwardIDB := createShareForward("flow-split-forward-b", 32102)
+
+	forwardOut := requestContractEnvelope(t, router, adminToken, "/api/v1/forward/list", nil)
+	if forwardOut.Code != 0 {
+		t.Fatalf("forward list failed: code=%d msg=%q", forwardOut.Code, forwardOut.Msg)
+	}
+	forwardRows := mustContractSlice(t, forwardOut.Data, "forward list data")
+
+	shareOut := requestContractEnvelope(t, router, adminToken, "/api/v1/federation/share/list", nil)
+	if shareOut.Code != 0 {
+		t.Fatalf("share list failed: code=%d msg=%q", shareOut.Code, shareOut.Msg)
+	}
+	localShareRows := mustContractSlice(t, shareOut.Data, "share list data")
+
+	remoteUsageOut := requestContractEnvelope(t, router, adminToken, "/api/v1/federation/share/remote-usage/list", nil)
+	if remoteUsageOut.Code != 0 {
+		t.Fatalf("remote usage list failed: code=%d msg=%q", remoteUsageOut.Code, remoteUsageOut.Msg)
+	}
+	remoteUsageRows := mustContractSlice(t, remoteUsageOut.Data, "remote usage data")
+	if len(remoteUsageRows) != 0 {
+		t.Fatalf("expected no remote usage rows in local-only fixture, got %d", len(remoteUsageRows))
+	}
+
+	flowByShare := make(map[int64]int64)
+	for _, row := range remoteUsageRows {
+		m, ok := row.(map[string]interface{})
+		if !ok {
+			continue
+		}
+		shareID := contractValueAsInt64(m["shareId"])
+		currentFlow := contractValueAsInt64(m["currentFlow"])
+		if shareID > 0 && currentFlow > 0 {
+			if currentFlow > flowByShare[shareID] {
+				flowByShare[shareID] = currentFlow
+			}
+		}
+	}
+	for _, row := range localShareRows {
+		m, ok := row.(map[string]interface{})
+		if !ok {
+			continue
+		}
+		shareID := contractValueAsInt64(m["id"])
+		currentFlow := contractValueAsInt64(m["currentFlow"])
+		if shareID > 0 && currentFlow > 0 {
+			if currentFlow > flowByShare[shareID] {
+				flowByShare[shareID] = currentFlow
+			}
+		}
+	}
+
+	shareFlow := flowByShare[share.ID]
+	if shareFlow <= 0 {
+		t.Fatalf("expected merged share flow > 0 for share %d", share.ID)
+	}
+
+	forwardCountByShare := make(map[int64]int)
+	for _, row := range forwardRows {
+		m, ok := row.(map[string]interface{})
+		if !ok {
+			continue
+		}
+		sid := contractParseShareIDFromTunnelName(contractValueAsString(m["tunnelName"]))
+		if sid > 0 && flowByShare[sid] > 0 {
+			forwardCountByShare[sid] = forwardCountByShare[sid] + 1
+		}
+	}
+
+	count := forwardCountByShare[share.ID]
+	if count != 2 {
+		t.Fatalf("expected 2 forwards sharing share %d, got %d", share.ID, count)
+	}
+
+	expectedEach := shareFlow / int64(count)
+	if expectedEach < 1 {
+		expectedEach = 1
+	}
+
+	findForward := func(forwardID int64) map[string]interface{} {
+		t.Helper()
+		for _, row := range forwardRows {
+			m, ok := row.(map[string]interface{})
+			if !ok {
+				continue
+			}
+			if contractValueAsInt64(m["id"]) == forwardID {
+				return m
+			}
+		}
+		t.Fatalf("forward %d not found in /forward/list response", forwardID)
+		return nil
+	}
+
+	for _, forwardID := range []int64{forwardIDA, forwardIDB} {
+		forward := findForward(forwardID)
+		sid := contractParseShareIDFromTunnelName(contractValueAsString(forward["tunnelName"]))
+		if sid != share.ID {
+			t.Fatalf("expected parsed shareID=%d, got %d for forward %d", share.ID, sid, forwardID)
+		}
+
+		directFlow := contractValueAsInt64(forward["inFlow"]) + contractValueAsInt64(forward["outFlow"])
+		if directFlow != 0 {
+			t.Fatalf("fixture expectation failed: directFlow should be 0 for forward %d, got %d", forwardID, directFlow)
+		}
+
+		displayFlow := int64(0)
+		if directFlow > 0 {
+			displayFlow = directFlow
+		} else {
+			shareFlowForForward := flowByShare[sid]
+			if shareFlowForForward > 0 {
+				cnt := forwardCountByShare[sid]
+				if cnt <= 0 {
+					cnt = 1
+				}
+				estimated := shareFlowForForward / int64(cnt)
+				if estimated < 1 {
+					estimated = 1
+				}
+				displayFlow = estimated
+			}
+		}
+
+		if displayFlow <= 0 {
+			t.Fatalf("expected displayFlow > 0 for forward %d, got %d", forwardID, displayFlow)
+		}
+		if displayFlow != expectedEach {
+			t.Fatalf("expected displayFlow=%d for forward %d, got %d", expectedEach, forwardID, displayFlow)
+		}
+	}
+}
+
+func TestFederationForwardCardFlowLinkageContractResolvesShareByTunnelBindingWhenTunnelNameIsCustom(t *testing.T) {
+	secret := "federation-forward-binding-flow-contract-jwt"
+	router, r := setupContractRouter(t, secret)
+
+	adminToken, err := auth.GenerateToken(1, "admin_user", 0, secret)
+	if err != nil {
+		t.Fatalf("generate admin token: %v", err)
+	}
+
+	now := time.Now().UnixMilli()
+	remoteShareID := int64(901)
+	remoteShareFlow := int64(5000)
+
+	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(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`,
+		"flow-binding-remote-node", "flow-binding-remote-secret", "10.31.41.51", "10.31.41.51", "", "33000-33020", "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", 0, 1, "", "", fmt.Sprintf(`{"shareId":%d,"maxBandwidth":0,"currentFlow":%d,"portRangeStart":33000,"portRangeEnd":33020}`, remoteShareID, remoteShareFlow),
+	).Error; err != nil {
+		t.Fatalf("insert remote node: %v", err)
+	}
+	remoteNodeID := mustLastInsertID(t, r, "flow-binding-remote-node")
+
+	if err := r.DB().Exec(`
+		INSERT INTO tunnel(name, type, protocol, flow, created_time, updated_time, status, in_ip, inx)
+		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, "federation-port-forward-custom-name", 1, "tcp", 1, now, now, 1, "", 0).Error; err != nil {
+		t.Fatalf("insert custom tunnel: %v", err)
+	}
+	tunnelID := mustLastInsertID(t, r, "flow-binding-custom-tunnel")
+
+	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(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, 1, "admin_user", "flow-binding-forward", tunnelID, "1.1.1.1:443", "fifo", 0, 0, now, now, 1, 0).Error; err != nil {
+		t.Fatalf("insert forward: %v", err)
+	}
+	forwardID := mustLastInsertID(t, r, "flow-binding-forward")
+
+	if err := r.DB().Exec(`INSERT INTO forward_port(forward_id, node_id, port) VALUES(?, ?, ?)`, forwardID, remoteNodeID, 33001).Error; err != nil {
+		t.Fatalf("insert forward_port: %v", err)
+	}
+
+	forwardOut := requestContractEnvelope(t, router, adminToken, "/api/v1/forward/list", nil)
+	if forwardOut.Code != 0 {
+		t.Fatalf("forward list failed: code=%d msg=%q", forwardOut.Code, forwardOut.Msg)
+	}
+	forwardRows := mustContractSlice(t, forwardOut.Data, "forward list data")
+
+	shareOut := requestContractEnvelope(t, router, adminToken, "/api/v1/federation/share/list", nil)
+	if shareOut.Code != 0 {
+		t.Fatalf("share list failed: code=%d msg=%q", shareOut.Code, shareOut.Msg)
+	}
+	localShareRows := mustContractSlice(t, shareOut.Data, "share list data")
+
+	remoteUsageOut := requestContractEnvelope(t, router, adminToken, "/api/v1/federation/share/remote-usage/list", nil)
+	if remoteUsageOut.Code != 0 {
+		t.Fatalf("remote usage list failed: code=%d msg=%q", remoteUsageOut.Code, remoteUsageOut.Msg)
+	}
+	remoteUsageRows := mustContractSlice(t, remoteUsageOut.Data, "remote usage data")
+	if len(remoteUsageRows) == 0 {
+		t.Fatalf("expected non-empty remote usage rows")
+	}
+
+	findForward := func(id int64) map[string]interface{} {
+		t.Helper()
+		for _, row := range forwardRows {
+			m, ok := row.(map[string]interface{})
+			if !ok {
+				continue
+			}
+			if contractValueAsInt64(m["id"]) == id {
+				return m
+			}
+		}
+		t.Fatalf("forward %d not found in /forward/list response", id)
+		return nil
+	}
+
+	flowByShare := make(map[int64]int64)
+	shareIDsByTunnel := make(map[int64]map[int64]struct{})
+
+	for _, row := range remoteUsageRows {
+		m, ok := row.(map[string]interface{})
+		if !ok {
+			continue
+		}
+		shareID := contractValueAsInt64(m["shareId"])
+		currentFlow := contractValueAsInt64(m["currentFlow"])
+		if shareID > 0 && currentFlow > 0 {
+			if currentFlow > flowByShare[shareID] {
+				flowByShare[shareID] = currentFlow
+			}
+		}
+
+		bindings, _ := m["bindings"].([]interface{})
+		for _, bindingRaw := range bindings {
+			binding, ok := bindingRaw.(map[string]interface{})
+			if !ok {
+				continue
+			}
+			tunnelIDVal := contractValueAsInt64(binding["tunnelId"])
+			chainType := contractValueAsInt64(binding["chainType"])
+			if shareID <= 0 || tunnelIDVal <= 0 {
+				continue
+			}
+			if chainType != 1 {
+				continue
+			}
+			setByTunnel, ok := shareIDsByTunnel[tunnelIDVal]
+			if !ok {
+				setByTunnel = make(map[int64]struct{})
+				shareIDsByTunnel[tunnelIDVal] = setByTunnel
+			}
+			setByTunnel[shareID] = struct{}{}
+		}
+	}
+
+	for _, row := range localShareRows {
+		m, ok := row.(map[string]interface{})
+		if !ok {
+			continue
+		}
+		shareID := contractValueAsInt64(m["id"])
+		currentFlow := contractValueAsInt64(m["currentFlow"])
+		if shareID > 0 && currentFlow > 0 {
+			if currentFlow > flowByShare[shareID] {
+				flowByShare[shareID] = currentFlow
+			}
+		}
+	}
+
+	targetForward := findForward(forwardID)
+	parsedByName := contractParseShareIDFromTunnelName(contractValueAsString(targetForward["tunnelName"]))
+	if parsedByName != 0 {
+		t.Fatalf("expected custom tunnel name cannot be parsed as Share-*-Port-*, got %d", parsedByName)
+	}
+
+	resolveShareIDForForward := func(forward map[string]interface{}) int64 {
+		candidates := make(map[int64]struct{})
+
+		shareIDFromName := contractParseShareIDFromTunnelName(contractValueAsString(forward["tunnelName"]))
+		if shareIDFromName > 0 {
+			candidates[shareIDFromName] = struct{}{}
+		}
+
+		tunnelIDVal := contractValueAsInt64(forward["tunnelId"])
+		if setByTunnel, ok := shareIDsByTunnel[tunnelIDVal]; ok {
+			for sid := range setByTunnel {
+				candidates[sid] = struct{}{}
+			}
+		}
+
+		var bestShareID int64
+		bestFlow := int64(0)
+		for sid := range candidates {
+			flow := flowByShare[sid]
+			if flow > bestFlow {
+				bestFlow = flow
+				bestShareID = sid
+			}
+		}
+		return bestShareID
+	}
+
+	resolvedShareID := resolveShareIDForForward(targetForward)
+	if resolvedShareID != remoteShareID {
+		t.Fatalf("expected resolved shareID=%d via tunnel binding, got %d", remoteShareID, resolvedShareID)
+	}
+
+	forwardCountByShare := make(map[int64]int)
+	resolvedByForwardID := make(map[int64]int64)
+	for _, row := range forwardRows {
+		m, ok := row.(map[string]interface{})
+		if !ok {
+			continue
+		}
+		fid := contractValueAsInt64(m["id"])
+		sid := resolveShareIDForForward(m)
+		if sid > 0 {
+			resolvedByForwardID[fid] = sid
+		}
+		if sid > 0 && flowByShare[sid] > 0 {
+			forwardCountByShare[sid] = forwardCountByShare[sid] + 1
+		}
+	}
+
+	directFlow := contractValueAsInt64(targetForward["inFlow"]) + contractValueAsInt64(targetForward["outFlow"])
+	if directFlow != 0 {
+		t.Fatalf("fixture expectation failed: directFlow should be 0, got %d", directFlow)
+	}
+
+	shareFlow := flowByShare[resolvedByForwardID[forwardID]]
+	if shareFlow <= 0 {
+		t.Fatalf("expected merged share flow > 0 for resolved share %d", resolvedByForwardID[forwardID])
+	}
+
+	count := forwardCountByShare[resolvedByForwardID[forwardID]]
+	if count <= 0 {
+		count = 1
+	}
+	estimated := shareFlow / int64(count)
+	if estimated < 1 {
+		estimated = 1
+	}
+
+	displayFlow := estimated
+	if displayFlow <= 0 {
+		t.Fatalf("expected displayFlow > 0 after tunnel-binding-based merge, got %d", displayFlow)
+	}
+	if displayFlow != remoteShareFlow {
+		t.Fatalf("expected displayFlow=%d, got %d", remoteShareFlow, displayFlow)
+	}
+}
+
+func requestContractEnvelope(t *testing.T, router http.Handler, token string, path string, body interface{}) response.R {
+	t.Helper()
+
+	payload := []byte("{}")
+	if body != nil {
+		raw, err := json.Marshal(body)
+		if err != nil {
+			t.Fatalf("marshal request body for %s: %v", path, err)
+		}
+		payload = raw
+	}
+
+	req := httptest.NewRequest(http.MethodPost, path, bytes.NewReader(payload))
+	req.Header.Set("Authorization", token)
+	req.Header.Set("Content-Type", "application/json")
+	res := httptest.NewRecorder()
+	router.ServeHTTP(res, req)
+
+	if res.Code != http.StatusOK {
+		t.Fatalf("expected http 200 for %s, got %d", path, res.Code)
+	}
+
+	var out response.R
+	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
+		t.Fatalf("decode response for %s: %v", path, err)
+	}
+
+	return out
+}
+
+func mustContractSlice(t *testing.T, data interface{}, label string) []interface{} {
+	t.Helper()
+
+	rows, ok := data.([]interface{})
+	if !ok {
+		t.Fatalf("expected %s to be []interface{}, got %T", label, data)
+	}
+	return rows
+}
+
+func contractParseShareIDFromTunnelName(tunnelName string) int64 {
+	normalized := strings.TrimSpace(tunnelName)
+	if !strings.HasPrefix(normalized, "Share-") {
+		return 0
+	}
+	raw := strings.TrimPrefix(normalized, "Share-")
+	idx := strings.Index(raw, "-Port-")
+	if idx <= 0 {
+		return 0
+	}
+	shareID, err := strconv.ParseInt(strings.TrimSpace(raw[:idx]), 10, 64)
+	if err != nil || shareID <= 0 {
+		return 0
+	}
+	return shareID
+}
+
+func contractValueAsInt64(v interface{}) int64 {
+	switch n := v.(type) {
+	case int64:
+		return n
+	case int:
+		return int64(n)
+	case float64:
+		return int64(n)
+	case json.Number:
+		i, err := n.Int64()
+		if err == nil {
+			return i
+		}
+		f, err := n.Float64()
+		if err == nil {
+			return int64(f)
+		}
+		return 0
+	case string:
+		i, err := strconv.ParseInt(strings.TrimSpace(n), 10, 64)
+		if err == nil {
+			return i
+		}
+		return 0
+	default:
+		return 0
+	}
+}
+
+func contractValueAsString(v interface{}) string {
+	s, _ := v.(string)
+	return s
+}

go-backend/tests/contract/forward_contract_test.go

@@ -2,6 +2,7 @@ package contract_test
 
 import (
 	"bytes"
+	"database/sql"
 	"encoding/json"
 	"net/http"
 	"net/http/httptest"
@@ -471,6 +472,234 @@ func TestUserTunnelReassignmentKeepsStableID(t *testing.T) {
 	}
 }
 
+func TestForwardSpeedIDWriteAndClearContracts(t *testing.T) {
+	secret := "contract-jwt-secret"
+	router, repo := setupContractRouter(t, secret)
+	now := time.Now().UnixMilli()
+
+	adminToken, err := auth.GenerateToken(1, "admin_user", 0, secret)
+	if err != nil {
+		t.Fatalf("generate admin token: %v", err)
+	}
+
+	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(2, 'speed_user', '3c85cdebade1c51cf64ca9f3c09d182d', 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-speed-tunnel", 1.0, 1, "tls", 99999, now, now, 1, nil, 0).Error; err != nil {
+		t.Fatalf("insert tunnel: %v", err)
+	}
+	tunnelID := mustLastInsertID(t, repo, "forward-speed-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-speed-node", "forward-speed-secret", "10.30.0.1", "10.30.0.1", "", "31000-31010", "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", 0).Error; err != nil {
+		t.Fatalf("insert node: %v", err)
+	}
+	nodeID := mustLastInsertID(t, repo, "forward-speed-node")
+
+	if err := repo.DB().Exec(`
+		INSERT INTO chain_tunnel(tunnel_id, chain_type, node_id, port, strategy, inx, protocol)
+		VALUES(?, 1, ?, 31001, 'round', 1, 'tls')
+	`, tunnelID, nodeID).Error; err != nil {
+		t.Fatalf("insert chain_tunnel: %v", err)
+	}
+
+	if err := repo.DB().Exec(`
+		INSERT INTO speed_limit(name, speed, tunnel_id, tunnel_name, created_time, updated_time, status)
+		VALUES(?, ?, NULL, NULL, ?, NULL, ?)
+	`, "forward-speed-limit-a", 2048, now, 1).Error; err != nil {
+		t.Fatalf("insert speed limit a: %v", err)
+	}
+	speedIDA := mustLastInsertID(t, repo, "forward-speed-limit-a")
+
+	if err := repo.DB().Exec(`
+		INSERT INTO speed_limit(name, speed, tunnel_id, tunnel_name, created_time, updated_time, status)
+		VALUES(?, ?, NULL, NULL, ?, NULL, ?)
+	`, "forward-speed-limit-b", 4096, now, 1).Error; err != nil {
+		t.Fatalf("insert speed limit b: %v", err)
+	}
+	speedIDB := mustLastInsertID(t, repo, "forward-speed-limit-b")
+
+	server := httptest.NewServer(router)
+	defer server.Close()
+	stopNode := startMockNodeSession(t, server.URL, "forward-speed-secret")
+	defer stopNode()
+
+	createPayload := map[string]interface{}{
+		"name":       "forward-speed-target",
+		"tunnelId":   tunnelID,
+		"remoteAddr": "1.1.1.1:443",
+		"strategy":   "fifo",
+		"speedId":    speedIDA,
+	}
+	createBody, err := json.Marshal(createPayload)
+	if err != nil {
+		t.Fatalf("marshal create payload: %v", err)
+	}
+	createReq := httptest.NewRequest(http.MethodPost, "/api/v1/forward/create", bytes.NewReader(createBody))
+	createReq.Header.Set("Authorization", adminToken)
+	createReq.Header.Set("Content-Type", "application/json")
+	createRes := httptest.NewRecorder()
+	router.ServeHTTP(createRes, createReq)
+	assertCode(t, createRes, 0)
+
+	forwardID := mustLastInsertID(t, repo, "forward-speed-target")
+	storedSpeed := repo.DB().Raw(`SELECT speed_id FROM forward WHERE id = ?`, forwardID).Row()
+	var createdSpeed sql.NullInt64
+	if err := storedSpeed.Scan(&createdSpeed); err != nil {
+		t.Fatalf("query created forward speed_id: %v", err)
+	}
+	if !createdSpeed.Valid || createdSpeed.Int64 != speedIDA {
+		t.Fatalf("expected created speed_id=%d, got valid=%v value=%d", speedIDA, createdSpeed.Valid, createdSpeed.Int64)
+	}
+
+	updateToBPayload := map[string]interface{}{
+		"id":      forwardID,
+		"speedId": speedIDB,
+	}
+	updateToBBody, err := json.Marshal(updateToBPayload)
+	if err != nil {
+		t.Fatalf("marshal update-to-b payload: %v", err)
+	}
+	updateToBReq := httptest.NewRequest(http.MethodPost, "/api/v1/forward/update", bytes.NewReader(updateToBBody))
+	updateToBReq.Header.Set("Authorization", adminToken)
+	updateToBReq.Header.Set("Content-Type", "application/json")
+	updateToBRes := httptest.NewRecorder()
+	router.ServeHTTP(updateToBRes, updateToBReq)
+	assertCode(t, updateToBRes, 0)
+
+	storedSpeed = repo.DB().Raw(`SELECT speed_id FROM forward WHERE id = ?`, forwardID).Row()
+	var updatedSpeed sql.NullInt64
+	if err := storedSpeed.Scan(&updatedSpeed); err != nil {
+		t.Fatalf("query updated forward speed_id: %v", err)
+	}
+	if !updatedSpeed.Valid || updatedSpeed.Int64 != speedIDB {
+		t.Fatalf("expected updated speed_id=%d, got valid=%v value=%d", speedIDB, updatedSpeed.Valid, updatedSpeed.Int64)
+	}
+
+	clearPayload := map[string]interface{}{
+		"id":      forwardID,
+		"speedId": nil,
+	}
+	clearBody, err := json.Marshal(clearPayload)
+	if err != nil {
+		t.Fatalf("marshal clear payload: %v", err)
+	}
+	clearReq := httptest.NewRequest(http.MethodPost, "/api/v1/forward/update", bytes.NewReader(clearBody))
+	clearReq.Header.Set("Authorization", adminToken)
+	clearReq.Header.Set("Content-Type", "application/json")
+	clearRes := httptest.NewRecorder()
+	router.ServeHTTP(clearRes, clearReq)
+	assertCode(t, clearRes, 0)
+
+	storedSpeed = repo.DB().Raw(`SELECT speed_id FROM forward WHERE id = ?`, forwardID).Row()
+	var clearedSpeed sql.NullInt64
+	if err := storedSpeed.Scan(&clearedSpeed); err != nil {
+		t.Fatalf("query cleared forward speed_id: %v", err)
+	}
+	if clearedSpeed.Valid {
+		t.Fatalf("expected cleared speed_id to be NULL, got %d", clearedSpeed.Int64)
+	}
+}
+
+func TestForwardCreateThenPauseResumeContract(t *testing.T) {
+	secret := "contract-jwt-secret"
+	router, repo := setupContractRouter(t, secret)
+
+	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 tunnel(name, traffic_ratio, type, protocol, flow, created_time, updated_time, status, in_ip, inx)
+		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, "forward-toggle-tunnel", 1.0, 1, "tls", 99999, now, now, 1, nil, 0).Error; err != nil {
+		t.Fatalf("insert tunnel: %v", err)
+	}
+	tunnelID := mustLastInsertID(t, repo, "forward-toggle-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-toggle-node", "forward-toggle-secret", "10.31.0.1", "10.31.0.1", "", "41000-41010", "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", 0).Error; err != nil {
+		t.Fatalf("insert node: %v", err)
+	}
+	nodeID := mustLastInsertID(t, repo, "forward-toggle-node")
+
+	if err := repo.DB().Exec(`
+		INSERT INTO chain_tunnel(tunnel_id, chain_type, node_id, port, strategy, inx, protocol)
+		VALUES(?, 1, ?, 41001, 'round', 1, 'tls')
+	`, tunnelID, nodeID).Error; err != nil {
+		t.Fatalf("insert chain_tunnel: %v", err)
+	}
+
+	server := httptest.NewServer(router)
+	defer server.Close()
+	stopNode := startMockNodeSession(t, server.URL, "forward-toggle-secret")
+	defer stopNode()
+
+	createPayload := map[string]interface{}{
+		"name":       "forward-toggle-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)
+	}
+	createReq := httptest.NewRequest(http.MethodPost, "/api/v1/forward/create", bytes.NewReader(createBody))
+	createReq.Header.Set("Authorization", adminToken)
+	createReq.Header.Set("Content-Type", "application/json")
+	createRes := httptest.NewRecorder()
+	router.ServeHTTP(createRes, createReq)
+	assertCode(t, createRes, 0)
+
+	forwardID := mustLastInsertID(t, repo, "forward-toggle-target")
+
+	pauseBody, err := json.Marshal(map[string]interface{}{"id": forwardID})
+	if err != nil {
+		t.Fatalf("marshal pause payload: %v", err)
+	}
+	pauseReq := httptest.NewRequest(http.MethodPost, "/api/v1/forward/pause", bytes.NewReader(pauseBody))
+	pauseReq.Header.Set("Authorization", adminToken)
+	pauseReq.Header.Set("Content-Type", "application/json")
+	pauseRes := httptest.NewRecorder()
+	router.ServeHTTP(pauseRes, pauseReq)
+	assertCode(t, pauseRes, 0)
+
+	pausedStatus := mustQueryInt(t, repo, `SELECT status FROM forward WHERE id = ?`, forwardID)
+	if pausedStatus != 0 {
+		t.Fatalf("expected status=0 after pause, got %d", pausedStatus)
+	}
+
+	resumeBody, err := json.Marshal(map[string]interface{}{"id": forwardID})
+	if err != nil {
+		t.Fatalf("marshal resume payload: %v", err)
+	}
+	resumeReq := httptest.NewRequest(http.MethodPost, "/api/v1/forward/resume", bytes.NewReader(resumeBody))
+	resumeReq.Header.Set("Authorization", adminToken)
+	resumeReq.Header.Set("Content-Type", "application/json")
+	resumeRes := httptest.NewRecorder()
+	router.ServeHTTP(resumeRes, resumeReq)
+	assertCode(t, resumeRes, 0)
+
+	resumedStatus := mustQueryInt(t, repo, `SELECT status FROM forward WHERE id = ?`, forwardID)
+	if resumedStatus != 1 {
+		t.Fatalf("expected status=1 after resume, got %d", resumedStatus)
+	}
+}
+
 func jsonNumber(v int64) string {
 	return strconv.FormatInt(v, 10)
 }

go-backend/tests/contract/limiter_sync_failure_contract_test.go

@@ -0,0 +1,473 @@
+package contract_test
+
+import (
+	"bytes"
+	"database/sql"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/gorilla/websocket"
+
+	"go-backend/internal/auth"
+	"go-backend/internal/http/response"
+	"go-backend/internal/security"
+)
+
+func TestForwardCreateRollbackWhenLimiterDispatchFailsContract(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 tunnel(name, traffic_ratio, type, protocol, flow, created_time, updated_time, status, in_ip, inx)
+		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, "limiter-fail-tunnel", 1.0, 1, "tls", 99999, now, now, 1, nil, 0).Error; err != nil {
+		t.Fatalf("insert tunnel: %v", err)
+	}
+	tunnelID := mustLastInsertID(t, r, "limiter-fail-tunnel")
+
+	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(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, "limiter-fail-node", "limiter-fail-secret", "10.20.0.1", "10.20.0.1", "", "32000-32010", "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", 0).Error; err != nil {
+		t.Fatalf("insert node: %v", err)
+	}
+	nodeID := mustLastInsertID(t, r, "limiter-fail-node")
+
+	if err := r.DB().Exec(`
+		INSERT INTO chain_tunnel(tunnel_id, chain_type, node_id, port, strategy, inx, protocol)
+		VALUES(?, 1, ?, 32001, 'round', 1, 'tls')
+	`, tunnelID, nodeID).Error; err != nil {
+		t.Fatalf("insert chain_tunnel: %v", err)
+	}
+
+	if err := r.DB().Exec(`
+		INSERT INTO speed_limit(name, speed, tunnel_id, tunnel_name, created_time, updated_time, status)
+		VALUES(?, ?, NULL, NULL, ?, NULL, ?)
+	`, "limiter-fail-rule", 1024, now, 1).Error; err != nil {
+		t.Fatalf("insert speed limit: %v", err)
+	}
+	speedID := mustLastInsertID(t, r, "limiter-fail-rule")
+
+	stopNode := startMockNodeSessionWithCommandFailures(t, server.URL, "limiter-fail-secret", map[string]string{
+		"addlimiters": "mock add limiters failed",
+	})
+	defer stopNode()
+
+	payload := map[string]interface{}{
+		"name":       "limiter-fail-forward",
+		"tunnelId":   tunnelID,
+		"remoteAddr": "1.1.1.1:443",
+		"strategy":   "fifo",
+		"speedId":    speedID,
+	}
+	body, err := json.Marshal(payload)
+	if err != nil {
+		t.Fatalf("marshal payload: %v", err)
+	}
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/forward/create", bytes.NewReader(body))
+	req.Header.Set("Authorization", adminToken)
+	req.Header.Set("Content-Type", "application/json")
+	res := httptest.NewRecorder()
+	router.ServeHTTP(res, req)
+
+	var out response.R
+	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
+		t.Fatalf("decode response: %v", err)
+	}
+	if out.Code == 0 {
+		t.Fatalf("expected create failure on limiter dispatch, got code=0")
+	}
+
+	forwardCount := mustQueryInt(t, r, `SELECT COUNT(1) FROM forward WHERE name = ?`, "limiter-fail-forward")
+	if forwardCount != 0 {
+		t.Fatalf("expected forward rollback delete on limiter failure, got count=%d", forwardCount)
+	}
+}
+
+func TestForwardCreateRollbackWhenServiceDispatchReturnsAddressInUseContract(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 tunnel(name, traffic_ratio, type, protocol, flow, created_time, updated_time, status, in_ip, inx)
+		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, "addr-in-use-tunnel", 1.0, 1, "tls", 99999, now, now, 1, nil, 0).Error; err != nil {
+		t.Fatalf("insert tunnel: %v", err)
+	}
+	tunnelID := mustLastInsertID(t, r, "addr-in-use-tunnel")
+
+	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(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, "addr-in-use-node", "addr-in-use-secret", "10.20.0.11", "10.20.0.11", "", "32100-32110", "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", 0).Error; err != nil {
+		t.Fatalf("insert node: %v", err)
+	}
+	nodeID := mustLastInsertID(t, r, "addr-in-use-node")
+
+	if err := r.DB().Exec(`
+		INSERT INTO chain_tunnel(tunnel_id, chain_type, node_id, port, strategy, inx, protocol)
+		VALUES(?, 1, ?, 32101, 'round', 1, 'tls')
+	`, tunnelID, nodeID).Error; err != nil {
+		t.Fatalf("insert chain_tunnel: %v", err)
+	}
+
+	stopNode := startMockNodeSessionWithCommandFailures(t, server.URL, "addr-in-use-secret", map[string]string{
+		"updateservice": "listen tcp [::]:32101: bind: address already in use",
+		"addservice":    "listen tcp [::]:32101: bind: address already in use",
+	})
+	defer stopNode()
+
+	payload := map[string]interface{}{
+		"name":       "addr-in-use-forward",
+		"tunnelId":   tunnelID,
+		"remoteAddr": "1.1.1.1:443",
+		"strategy":   "fifo",
+	}
+	body, err := json.Marshal(payload)
+	if err != nil {
+		t.Fatalf("marshal payload: %v", err)
+	}
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/forward/create", bytes.NewReader(body))
+	req.Header.Set("Authorization", adminToken)
+	req.Header.Set("Content-Type", "application/json")
+	res := httptest.NewRecorder()
+	router.ServeHTTP(res, req)
+
+	var out response.R
+	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
+		t.Fatalf("decode response: %v", err)
+	}
+	if out.Code == 0 {
+		t.Fatalf("expected create failure on address-in-use service dispatch, got code=0")
+	}
+
+	forwardCount := mustQueryInt(t, r, `SELECT COUNT(1) FROM forward WHERE name = ?`, "addr-in-use-forward")
+	if forwardCount != 0 {
+		t.Fatalf("expected forward rollback delete on address-in-use failure, got count=%d", forwardCount)
+	}
+}
+
+func TestBatchAssignRollbackWhenLimiterDispatchFailsContract(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, 'assign_user', '3c85cdebade1c51cf64ca9f3c09d182d', 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(?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, "assign-limiter-fail-tunnel", 1.0, 1, "tls", 99999, now, now, 1, nil, 0).Error; err != nil {
+		t.Fatalf("insert tunnel: %v", err)
+	}
+	tunnelID := mustLastInsertID(t, r, "assign-limiter-fail-tunnel")
+
+	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(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, "assign-limiter-fail-node", "assign-limiter-fail-secret", "10.21.0.1", "10.21.0.1", "", "33000-33010", "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", 0).Error; err != nil {
+		t.Fatalf("insert node: %v", err)
+	}
+	nodeID := mustLastInsertID(t, r, "assign-limiter-fail-node")
+
+	if err := r.DB().Exec(`
+		INSERT INTO chain_tunnel(tunnel_id, chain_type, node_id, port, strategy, inx, protocol)
+		VALUES(?, 1, ?, 33001, 'round', 1, 'tls')
+	`, tunnelID, nodeID).Error; err != nil {
+		t.Fatalf("insert chain_tunnel: %v", err)
+	}
+
+	if err := r.DB().Exec(`
+		INSERT INTO speed_limit(name, speed, tunnel_id, tunnel_name, created_time, updated_time, status)
+		VALUES(?, ?, NULL, NULL, ?, NULL, ?)
+	`, "assign-limiter-fail-rule", 2048, now, 1).Error; err != nil {
+		t.Fatalf("insert speed limit: %v", err)
+	}
+	speedID := mustLastInsertID(t, r, "assign-limiter-fail-rule")
+
+	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(21, 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, 'assign_user', 'assign-limiter-fail-forward', ?, '9.9.9.9:53', 'fifo', 0, 0, ?, ?, 1, 0)
+	`, tunnelID, now, now).Error; err != nil {
+		t.Fatalf("insert forward: %v", err)
+	}
+	forwardID := mustLastInsertID(t, r, "assign-limiter-fail-forward")
+
+	if err := r.DB().Exec(`INSERT INTO forward_port(forward_id, node_id, port) VALUES(?, ?, ?)`, forwardID, nodeID, 33001).Error; err != nil {
+		t.Fatalf("insert forward_port: %v", err)
+	}
+
+	stopNode := startMockNodeSessionWithCommandFailures(t, server.URL, "assign-limiter-fail-secret", map[string]string{
+		"addlimiters": "mock add limiters failed",
+	})
+	defer stopNode()
+
+	assignPayload := map[string]interface{}{
+		"userId": 2,
+		"tunnels": []map[string]interface{}{{
+			"tunnelId": tunnelID,
+			"speedId":  speedID,
+		}},
+	}
+	body, err := json.Marshal(assignPayload)
+	if err != nil {
+		t.Fatalf("marshal assign payload: %v", err)
+	}
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/user/batch-assign", bytes.NewReader(body))
+	req.Header.Set("Authorization", adminToken)
+	req.Header.Set("Content-Type", "application/json")
+	res := httptest.NewRecorder()
+	router.ServeHTTP(res, req)
+
+	var out response.R
+	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
+		t.Fatalf("decode response: %v", err)
+	}
+	if out.Code == 0 {
+		t.Fatalf("expected assign failure on limiter dispatch, got code=0")
+	}
+
+	var persistedSpeedID sql.NullInt64
+	if err := r.DB().Raw(`SELECT speed_id FROM user_tunnel WHERE user_id = 2 AND tunnel_id = ?`, tunnelID).Row().Scan(&persistedSpeedID); err != nil {
+		t.Fatalf("query user_tunnel speed_id: %v", err)
+	}
+	if persistedSpeedID.Valid {
+		t.Fatalf("expected speed_id rollback to NULL, got %d", persistedSpeedID.Int64)
+	}
+}
+
+func TestBatchAssignInsertRollbackWhenLimiterDispatchFailsContract(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(3, 'assign_insert_user', '3c85cdebade1c51cf64ca9f3c09d182d', 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(?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, "assign-insert-limiter-fail-tunnel", 1.0, 1, "tls", 99999, now, now, 1, nil, 0).Error; err != nil {
+		t.Fatalf("insert tunnel: %v", err)
+	}
+	tunnelID := mustLastInsertID(t, r, "assign-insert-limiter-fail-tunnel")
+
+	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(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, "assign-insert-limiter-fail-node", "assign-insert-limiter-fail-secret", "10.22.0.1", "10.22.0.1", "", "34000-34010", "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", 0).Error; err != nil {
+		t.Fatalf("insert node: %v", err)
+	}
+	nodeID := mustLastInsertID(t, r, "assign-insert-limiter-fail-node")
+
+	if err := r.DB().Exec(`
+		INSERT INTO chain_tunnel(tunnel_id, chain_type, node_id, port, strategy, inx, protocol)
+		VALUES(?, 1, ?, 34001, 'round', 1, 'tls')
+	`, tunnelID, nodeID).Error; err != nil {
+		t.Fatalf("insert chain_tunnel: %v", err)
+	}
+
+	if err := r.DB().Exec(`
+		INSERT INTO speed_limit(name, speed, tunnel_id, tunnel_name, created_time, updated_time, status)
+		VALUES(?, ?, NULL, NULL, ?, NULL, ?)
+	`, "assign-insert-limiter-fail-rule", 3072, now, 1).Error; err != nil {
+		t.Fatalf("insert speed limit: %v", err)
+	}
+	speedID := mustLastInsertID(t, r, "assign-insert-limiter-fail-rule")
+
+	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(3, 'assign_insert_user', 'assign-insert-limiter-fail-forward', ?, '8.8.4.4:53', 'fifo', 0, 0, ?, ?, 1, 0)
+	`, tunnelID, now, now).Error; err != nil {
+		t.Fatalf("insert forward: %v", err)
+	}
+	forwardID := mustLastInsertID(t, r, "assign-insert-limiter-fail-forward")
+
+	if err := r.DB().Exec(`INSERT INTO forward_port(forward_id, node_id, port) VALUES(?, ?, ?)`, forwardID, nodeID, 34001).Error; err != nil {
+		t.Fatalf("insert forward_port: %v", err)
+	}
+
+	stopNode := startMockNodeSessionWithCommandFailures(t, server.URL, "assign-insert-limiter-fail-secret", map[string]string{
+		"addlimiters": "mock add limiters failed",
+	})
+	defer stopNode()
+
+	assignPayload := map[string]interface{}{
+		"userId": 3,
+		"tunnels": []map[string]interface{}{{
+			"tunnelId": tunnelID,
+			"speedId":  speedID,
+		}},
+	}
+	body, err := json.Marshal(assignPayload)
+	if err != nil {
+		t.Fatalf("marshal assign payload: %v", err)
+	}
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/user/batch-assign", bytes.NewReader(body))
+	req.Header.Set("Authorization", adminToken)
+	req.Header.Set("Content-Type", "application/json")
+	res := httptest.NewRecorder()
+	router.ServeHTTP(res, req)
+
+	var out response.R
+	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
+		t.Fatalf("decode response: %v", err)
+	}
+	if out.Code == 0 {
+		t.Fatalf("expected assign(insert) failure on limiter dispatch, got code=0")
+	}
+
+	insertedCount := mustQueryInt(t, r, `SELECT COUNT(1) FROM user_tunnel WHERE user_id = 3 AND tunnel_id = ?`, tunnelID)
+	if insertedCount != 0 {
+		t.Fatalf("expected inserted user_tunnel rollback delete, got count=%d", insertedCount)
+	}
+}
+
+func startMockNodeSessionWithCommandFailures(t *testing.T, baseURL string, nodeSecret string, failCommands map[string]string) func() {
+	t.Helper()
+
+	u, err := url.Parse(baseURL)
+	if err != nil {
+		t.Fatalf("parse provider url: %v", err)
+	}
+	if strings.EqualFold(u.Scheme, "https") {
+		u.Scheme = "wss"
+	} else {
+		u.Scheme = "ws"
+	}
+	u.Path = "/system-info"
+	q := u.Query()
+	q.Set("type", "1")
+	q.Set("secret", nodeSecret)
+	q.Set("version", "v1")
+	q.Set("http", "1")
+	q.Set("tls", "1")
+	q.Set("socks", "1")
+	u.RawQuery = q.Encode()
+
+	conn, _, err := websocket.DefaultDialer.Dial(u.String(), nil)
+	if err != nil {
+		t.Fatalf("dial mock node websocket: %v", err)
+	}
+
+	var wg sync.WaitGroup
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		for {
+			_, raw, readErr := conn.ReadMessage()
+			if readErr != nil {
+				return
+			}
+
+			plain := raw
+			var wrap struct {
+				Encrypted bool   `json:"encrypted"`
+				Data      string `json:"data"`
+			}
+			if err := json.Unmarshal(raw, &wrap); err == nil && wrap.Encrypted && strings.TrimSpace(wrap.Data) != "" {
+				crypto, cryptoErr := security.NewAESCrypto(nodeSecret)
+				if cryptoErr == nil {
+					if dec, decErr := crypto.Decrypt(wrap.Data); decErr == nil {
+						plain = []byte(dec)
+					}
+				}
+			}
+
+			var cmd struct {
+				Type      string `json:"type"`
+				RequestID string `json:"requestId"`
+			}
+			if err := json.Unmarshal(plain, &cmd); err != nil {
+				continue
+			}
+			if strings.TrimSpace(cmd.RequestID) == "" {
+				continue
+			}
+
+			cmdType := strings.TrimSpace(cmd.Type)
+			failMsg, shouldFail := failCommands[strings.ToLower(cmdType)]
+
+			respType := fmt.Sprintf("%sResponse", cmdType)
+			respPayload := map[string]interface{}{
+				"type":      respType,
+				"success":   !shouldFail,
+				"message":   "OK",
+				"requestId": cmd.RequestID,
+			}
+			if shouldFail {
+				if strings.TrimSpace(failMsg) == "" {
+					failMsg = "mock command failed"
+				}
+				respPayload["message"] = failMsg
+			}
+
+			respBytes, err := json.Marshal(respPayload)
+			if err != nil {
+				continue
+			}
+			_ = conn.WriteMessage(websocket.TextMessage, respBytes)
+		}
+	}()
+
+	var stopOnce sync.Once
+	return func() {
+		stopOnce.Do(func() {
+			_ = conn.Close()
+			wg.Wait()
+		})
+	}
+}

go-backend/tests/contract/migration_contract_test.go

@@ -25,6 +25,7 @@ import (
 func TestCaptchaVerifyLoginContract(t *testing.T) {
 	secret := "contract-jwt-secret"
 	router, r := setupContractRouter(t, secret)
+	verifiedToken := ""
 
 	if err := r.DB().Exec(`
 		INSERT INTO vite_config(name, value, time)
@@ -34,7 +35,7 @@ func TestCaptchaVerifyLoginContract(t *testing.T) {
 		t.Fatalf("enable captcha: %v", err)
 	}
 
-	t.Run("login denied without verified captcha token", func(t *testing.T) {
+	t.Run("login allowed when cloudflare keys are missing", func(t *testing.T) {
 		body := bytes.NewBufferString(`{"username":"admin_user","password":"admin_user","captchaId":""}`)
 		req := httptest.NewRequest(http.MethodPost, "/api/v1/user/login", body)
 		req.Header.Set("Content-Type", "application/json")
@@ -42,10 +43,10 @@ func TestCaptchaVerifyLoginContract(t *testing.T) {
 
 		router.ServeHTTP(resp, req)
 
-		assertCodeMsg(t, resp, -1, "验证码校验失败")
+		assertCode(t, resp, 0)
 	})
 
-	t.Run("captcha token is one-time and consumed by login", func(t *testing.T) {
+	t.Run("captcha verify remains compatible without cloudflare secret", func(t *testing.T) {
 		verifyReq := httptest.NewRequest(http.MethodPost, "/api/v1/captcha/verify", bytes.NewBufferString(`{"id":"captcha-token-1","data":"ok"}`))
 		verifyReq.Header.Set("Content-Type", "application/json")
 		verifyResp := httptest.NewRecorder()
@@ -65,14 +66,60 @@ func TestCaptchaVerifyLoginContract(t *testing.T) {
 			t.Fatalf("unexpected captcha verify payload: success=%v token=%q", verifyOut.Success, verifyOut.Data.ValidToken)
 		}
 
-		loginBody := bytes.NewBufferString(`{"username":"admin_user","password":"admin_user","captchaId":"captcha-token-1"}`)
+		verifiedToken = verifyOut.Data.ValidToken
+	})
+
+	if err := r.DB().Exec(`
+		INSERT INTO vite_config(name, value, time)
+		VALUES(?, ?, ?)
+		ON CONFLICT(name) DO UPDATE SET value = excluded.value, time = excluded.time
+	`, "cloudflare_site_key", "test-site-key", time.Now().UnixMilli()).Error; err != nil {
+		t.Fatalf("set cloudflare site key: %v", err)
+	}
+	if err := r.DB().Exec(`
+		INSERT INTO vite_config(name, value, time)
+		VALUES(?, ?, ?)
+		ON CONFLICT(name) DO UPDATE SET value = excluded.value, time = excluded.time
+	`, "cloudflare_secret_key", "test-secret-key", time.Now().UnixMilli()).Error; err != nil {
+		t.Fatalf("set cloudflare secret key: %v", err)
+	}
+
+	t.Run("login denied without verified captcha token", func(t *testing.T) {
+		body := bytes.NewBufferString(`{"username":"admin_user","password":"admin_user","captchaId":""}`)
+		req := httptest.NewRequest(http.MethodPost, "/api/v1/user/login", body)
+		req.Header.Set("Content-Type", "application/json")
+		resp := httptest.NewRecorder()
+
+		router.ServeHTTP(resp, req)
+
+		assertCodeMsg(t, resp, -1, "验证码校验失败")
+	})
+
+	t.Run("whmcs api client bypasses captcha", func(t *testing.T) {
+		body := bytes.NewBufferString(`{"username":"admin_user","password":"admin_user","captchaId":""}`)
+		req := httptest.NewRequest(http.MethodPost, "/api/v1/user/login", body)
+		req.Header.Set("Content-Type", "application/json")
+		req.Header.Set("X-FLVX-API-Client", "whmcs")
+		resp := httptest.NewRecorder()
+
+		router.ServeHTTP(resp, req)
+
+		assertCode(t, resp, 0)
+	})
+
+	t.Run("captcha token is one-time and consumed by login", func(t *testing.T) {
+		if strings.TrimSpace(verifiedToken) == "" {
+			t.Fatalf("expected verified token from compatibility captcha verify")
+		}
+
+		loginBody := bytes.NewBufferString(`{"username":"admin_user","password":"admin_user","captchaId":"` + verifiedToken + `"}`)
 		loginReq := httptest.NewRequest(http.MethodPost, "/api/v1/user/login", loginBody)
 		loginReq.Header.Set("Content-Type", "application/json")
 		loginResp := httptest.NewRecorder()
 		router.ServeHTTP(loginResp, loginReq)
 		assertCode(t, loginResp, 0)
 
-		replayBody := bytes.NewBufferString(`{"username":"admin_user","password":"admin_user","captchaId":"captcha-token-1"}`)
+		replayBody := bytes.NewBufferString(`{"username":"admin_user","password":"admin_user","captchaId":"` + verifiedToken + `"}`)
 		replayReq := httptest.NewRequest(http.MethodPost, "/api/v1/user/login", replayBody)
 		replayReq.Header.Set("Content-Type", "application/json")
 		replayResp := httptest.NewRecorder()

go-backend/tests/contract/speed_limit_contract_test.go

@@ -0,0 +1,462 @@
+package contract_test
+
+import (
+	"bytes"
+	"database/sql"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"go-backend/internal/auth"
+	"go-backend/internal/http/response"
+	"go-backend/internal/store/repo"
+)
+
+// TestSpeedLimitWithoutTunnelContract tests that speed limits can be created without binding to a tunnel
+func TestSpeedLimitWithoutTunnelContract(t *testing.T) {
+	secret := "contract-jwt-secret"
+	router, _ := setupContractRouter(t, secret)
+
+	adminToken, err := auth.GenerateToken(1, "admin_user", 0, secret)
+	if err != nil {
+		t.Fatalf("generate admin token: %v", err)
+	}
+
+	// Create a speed limit without tunnel binding
+	t.Run("create speed limit without tunnel", func(t *testing.T) {
+		body := `{"name":"test-limit-no-tunnel","speed":100,"status":1}`
+		req := httptest.NewRequest(http.MethodPost, "/api/v1/speed-limit/create", bytes.NewBufferString(body))
+		req.Header.Set("Authorization", adminToken)
+		req.Header.Set("Content-Type", "application/json")
+		res := httptest.NewRecorder()
+		router.ServeHTTP(res, req)
+
+		assertCode(t, res, 0)
+	})
+
+	// Verify the speed limit has null tunnelId
+	t.Run("list speed limits shows null tunnelId", func(t *testing.T) {
+		req := httptest.NewRequest(http.MethodPost, "/api/v1/speed-limit/list", nil)
+		req.Header.Set("Authorization", adminToken)
+		res := httptest.NewRecorder()
+		router.ServeHTTP(res, req)
+
+		var out response.R
+		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, got %d", out.Code)
+		}
+
+		data, ok := out.Data.([]interface{})
+		if !ok {
+			t.Fatalf("expected data to be array, got %T", out.Data)
+		}
+
+		// Find our speed limit
+		var found bool
+		for _, item := range data {
+			m, ok := item.(map[string]interface{})
+			if !ok {
+				continue
+			}
+			if m["name"] == "test-limit-no-tunnel" {
+				found = true
+				// tunnelId should be nil/not present for unbound speed limits
+				if tunnelID, exists := m["tunnelId"]; exists && tunnelID != nil {
+					t.Fatalf("expected tunnelId to be nil for unbound speed limit, got %v", tunnelID)
+				}
+				break
+			}
+		}
+
+		if !found {
+			t.Fatal("speed limit 'test-limit-no-tunnel' not found in list")
+		}
+	})
+}
+
+// TestSpeedLimitWithTunnelContract tests that speed limits can still be bound to tunnels
+func TestSpeedLimitWithTunnelContract(t *testing.T) {
+	secret := "contract-jwt-secret"
+	router, r := setupContractRouter(t, secret)
+
+	adminToken, err := auth.GenerateToken(1, "admin_user", 0, secret)
+	if err != nil {
+		t.Fatalf("generate admin token: %v", err)
+	}
+
+	// First create a tunnel
+	tunnelID := mustCreateSpeedLimitTunnel(t, r, "test-tunnel-for-limit")
+
+	// Create a speed limit with tunnel binding
+	t.Run("create speed limit with tunnel", func(t *testing.T) {
+		body := `{"name":"test-limit-with-tunnel","speed":200,"tunnelId":` + jsonInt(tunnelID) + `,"status":1}`
+		req := httptest.NewRequest(http.MethodPost, "/api/v1/speed-limit/create", bytes.NewBufferString(body))
+		req.Header.Set("Authorization", adminToken)
+		req.Header.Set("Content-Type", "application/json")
+		res := httptest.NewRecorder()
+		router.ServeHTTP(res, req)
+
+		assertCode(t, res, 0)
+	})
+
+	// Verify the speed limit has the tunnelId
+	t.Run("list speed limits shows tunnelId", func(t *testing.T) {
+		req := httptest.NewRequest(http.MethodPost, "/api/v1/speed-limit/list", nil)
+		req.Header.Set("Authorization", adminToken)
+		res := httptest.NewRecorder()
+		router.ServeHTTP(res, req)
+
+		var out response.R
+		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, got %d", out.Code)
+		}
+
+		data, ok := out.Data.([]interface{})
+		if !ok {
+			t.Fatalf("expected data to be array, got %T", out.Data)
+		}
+
+		var found bool
+		for _, item := range data {
+			m, ok := item.(map[string]interface{})
+			if !ok {
+				continue
+			}
+			if m["name"] == "test-limit-with-tunnel" {
+				found = true
+				tunnelIDVal, exists := m["tunnelId"]
+				if !exists || tunnelIDVal == nil {
+					t.Fatal("expected tunnelId to be present for bound speed limit")
+				}
+				// Verify tunnelId matches
+				if tunnelIDFloat, ok := tunnelIDVal.(float64); ok {
+					if int64(tunnelIDFloat) != tunnelID {
+						t.Fatalf("expected tunnelId %d, got %d", tunnelID, int64(tunnelIDFloat))
+					}
+				}
+				break
+			}
+		}
+
+		if !found {
+			t.Fatal("speed limit 'test-limit-with-tunnel' not found in list")
+		}
+	})
+}
+
+// TestSpeedLimitUpdateTunnelBindingContract tests updating speed limit tunnel binding
+func TestSpeedLimitUpdateTunnelBindingContract(t *testing.T) {
+	secret := "contract-jwt-secret"
+	router, r := setupContractRouter(t, secret)
+
+	adminToken, err := auth.GenerateToken(1, "admin_user", 0, secret)
+	if err != nil {
+		t.Fatalf("generate admin token: %v", err)
+	}
+
+	// Create a tunnel
+	tunnelID := mustCreateSpeedLimitTunnel(t, r, "test-tunnel-update")
+
+	// Create a speed limit without tunnel
+	speedLimitID := mustCreateSpeedLimitRepo(t, r, "test-limit-update", 0)
+
+	// Update to bind to tunnel
+	t.Run("update speed limit to bind tunnel", func(t *testing.T) {
+		body := `{"id":` + jsonInt(speedLimitID) + `,"name":"test-limit-update","speed":150,"tunnelId":` + jsonInt(tunnelID) + `,"status":1}`
+		req := httptest.NewRequest(http.MethodPost, "/api/v1/speed-limit/update", bytes.NewBufferString(body))
+		req.Header.Set("Authorization", adminToken)
+		req.Header.Set("Content-Type", "application/json")
+		res := httptest.NewRecorder()
+		router.ServeHTTP(res, req)
+
+		assertCode(t, res, 0)
+	})
+
+	// Verify binding
+	t.Run("verify tunnel binding after update", func(t *testing.T) {
+		req := httptest.NewRequest(http.MethodPost, "/api/v1/speed-limit/list", nil)
+		req.Header.Set("Authorization", adminToken)
+		res := httptest.NewRecorder()
+		router.ServeHTTP(res, req)
+
+		var out response.R
+		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, got %d", out.Code)
+		}
+
+		data, ok := out.Data.([]interface{})
+		if !ok {
+			t.Fatalf("expected data to be array, got %T", out.Data)
+		}
+
+		for _, item := range data {
+			m, ok := item.(map[string]interface{})
+			if !ok {
+				continue
+			}
+			if m["name"] == "test-limit-update" {
+				tunnelIDVal, exists := m["tunnelId"]
+				if !exists || tunnelIDVal == nil {
+					t.Fatal("expected tunnelId to be present after update")
+				}
+				return
+			}
+		}
+		t.Fatal("speed limit 'test-limit-update' not found")
+	})
+
+	// Update to unbind from tunnel (set tunnelId to null)
+	t.Run("update speed limit to unbind tunnel", func(t *testing.T) {
+		body := `{"id":` + jsonInt(speedLimitID) + `,"name":"test-limit-update","speed":150,"status":1}`
+		req := httptest.NewRequest(http.MethodPost, "/api/v1/speed-limit/update", bytes.NewBufferString(body))
+		req.Header.Set("Authorization", adminToken)
+		req.Header.Set("Content-Type", "application/json")
+		res := httptest.NewRecorder()
+		router.ServeHTTP(res, req)
+
+		assertCode(t, res, 0)
+	})
+
+	// Verify unbinding
+	t.Run("verify tunnel unbinding after update", func(t *testing.T) {
+		req := httptest.NewRequest(http.MethodPost, "/api/v1/speed-limit/list", nil)
+		req.Header.Set("Authorization", adminToken)
+		res := httptest.NewRecorder()
+		router.ServeHTTP(res, req)
+
+		var out response.R
+		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, got %d", out.Code)
+		}
+
+		data, ok := out.Data.([]interface{})
+		if !ok {
+			t.Fatalf("expected data to be array, got %T", out.Data)
+		}
+
+		for _, item := range data {
+			m, ok := item.(map[string]interface{})
+			if !ok {
+				continue
+			}
+			if m["name"] == "test-limit-update" {
+				if tunnelIDVal, exists := m["tunnelId"]; exists && tunnelIDVal != nil {
+					t.Fatalf("expected tunnelId to be nil after unbinding, got %v", tunnelIDVal)
+				}
+				return
+			}
+		}
+		t.Fatal("speed limit 'test-limit-update' not found")
+	})
+}
+
+// TestSpeedLimitDatabaseNullableFields tests database-level nullable fields
+func TestSpeedLimitDatabaseNullableFields(t *testing.T) {
+	dbPath := filepath.Join(t.TempDir(), "speed-limit-null.db")
+	r, err := repo.Open(dbPath)
+	if err != nil {
+		t.Fatalf("open sqlite: %v", err)
+	}
+	t.Cleanup(func() { _ = r.Close() })
+
+	// Create speed limit via repository
+	t.Run("repository create speed limit without tunnel", func(t *testing.T) {
+		id, err := r.CreateSpeedLimit("db-test-limit", 100, nil, "", 1, 1)
+		if err != nil {
+			t.Fatalf("CreateSpeedLimit failed: %v", err)
+		}
+		if id <= 0 {
+			t.Fatalf("expected valid id, got %d", id)
+		}
+	})
+
+	// Verify TunnelID is null in database
+	t.Run("verify null TunnelID in database", func(t *testing.T) {
+		var tunnelID sql.NullInt64
+		var tunnelName sql.NullString
+		err := r.DB().Raw("SELECT tunnel_id, tunnel_name FROM speed_limit WHERE name = ?", "db-test-limit").Row().Scan(&tunnelID, &tunnelName)
+		if err != nil {
+			t.Fatalf("query failed: %v", err)
+		}
+		if tunnelID.Valid {
+			t.Fatalf("expected TunnelID to be NULL, got %d", tunnelID.Int64)
+		}
+		if tunnelName.Valid && tunnelName.String != "" {
+			t.Fatalf("expected TunnelName to be NULL or empty, got %s", tunnelName.String)
+		}
+	})
+
+	// Create a tunnel for binding test
+	tunnelID := mustCreateSpeedLimitTunnel(t, r, "db-test-tunnel")
+
+	// Create speed limit with tunnel
+	t.Run("repository create speed limit with tunnel", func(t *testing.T) {
+		id, err := r.CreateSpeedLimit("db-test-limit-with-tunnel", 200, &tunnelID, "db-test-tunnel", 1, 1)
+		if err != nil {
+			t.Fatalf("CreateSpeedLimit failed: %v", err)
+		}
+		if id <= 0 {
+			t.Fatalf("expected valid id, got %d", id)
+		}
+	})
+
+	// Verify TunnelID is set
+	t.Run("verify TunnelID is set in database", func(t *testing.T) {
+		var dbTunnelID sql.NullInt64
+		var dbTunnelName sql.NullString
+		err := r.DB().Raw("SELECT tunnel_id, tunnel_name FROM speed_limit WHERE name = ?", "db-test-limit-with-tunnel").Row().Scan(&dbTunnelID, &dbTunnelName)
+		if err != nil {
+			t.Fatalf("query failed: %v", err)
+		}
+		if !dbTunnelID.Valid {
+			t.Fatal("expected TunnelID to be valid")
+		}
+		if dbTunnelID.Int64 != tunnelID {
+			t.Fatalf("expected TunnelID %d, got %d", tunnelID, dbTunnelID.Int64)
+		}
+		if !dbTunnelName.Valid || dbTunnelName.String != "db-test-tunnel" {
+			t.Fatalf("expected TunnelName 'db-test-tunnel', got %v", dbTunnelName.String)
+		}
+	})
+
+	// Test GetSpeedLimitTunnelID returns correct nullability
+	t.Run("GetSpeedLimitTunnelID returns null for unbound limit", func(t *testing.T) {
+		result := r.GetSpeedLimitTunnelID(1) // First speed limit (db-test-limit)
+		if result.Valid {
+			t.Fatalf("expected GetSpeedLimitTunnelID to return invalid/null, got valid with value %d", result.Int64)
+		}
+	})
+
+	t.Run("GetSpeedLimitTunnelID returns value for bound limit", func(t *testing.T) {
+		result := r.GetSpeedLimitTunnelID(2) // Second speed limit (db-test-limit-with-tunnel)
+		if !result.Valid {
+			t.Fatal("expected GetSpeedLimitTunnelID to return valid result for bound limit")
+		}
+		if result.Int64 != tunnelID {
+			t.Fatalf("expected TunnelID %d, got %d", tunnelID, result.Int64)
+		}
+	})
+}
+
+// TestSpeedLimitUpdateUnbindFromTunnel tests unbinding a speed limit from a tunnel
+func TestSpeedLimitUpdateUnbindFromTunnel(t *testing.T) {
+	dbPath := filepath.Join(t.TempDir(), "speed-limit-unbind.db")
+	r, err := repo.Open(dbPath)
+	if err != nil {
+		t.Fatalf("open sqlite: %v", err)
+	}
+	t.Cleanup(func() { _ = r.Close() })
+
+	// Create tunnel
+	tunnelID := mustCreateSpeedLimitTunnel(t, r, "unbind-test-tunnel")
+
+	// Create speed limit bound to tunnel
+	speedLimitID, err := r.CreateSpeedLimit("unbind-test-limit", 300, &tunnelID, "unbind-test-tunnel", 1, 1)
+	if err != nil {
+		t.Fatalf("create speed limit: %v", err)
+	}
+
+	// Verify initial binding
+	t.Run("verify initial binding", func(t *testing.T) {
+		result := r.GetSpeedLimitTunnelID(speedLimitID)
+		if !result.Valid {
+			t.Fatal("expected initial binding to tunnel")
+		}
+		if result.Int64 != tunnelID {
+			t.Fatalf("expected tunnel ID %d, got %d", tunnelID, result.Int64)
+		}
+	})
+
+	// Update to unbind
+	t.Run("unbind speed limit from tunnel via UpdateSpeedLimit", func(t *testing.T) {
+		err := r.UpdateSpeedLimit(speedLimitID, "unbind-test-limit", 300, nil, "", 1, time.Now().UnixMilli())
+		if err != nil {
+			t.Fatalf("UpdateSpeedLimit failed: %v", err)
+		}
+	})
+
+	// Verify unbinding
+	t.Run("verify unbinding after update", func(t *testing.T) {
+		result := r.GetSpeedLimitTunnelID(speedLimitID)
+		if result.Valid {
+			t.Fatalf("expected GetSpeedLimitTunnelID to return invalid/null after unbind, got valid with value %d", result.Int64)
+		}
+	})
+}
+
+// TestSpeedLimitGetSpeed tests the GetSpeedLimitSpeed function
+func TestSpeedLimitGetSpeed(t *testing.T) {
+	dbPath := filepath.Join(t.TempDir(), "speed-limit-getspeed.db")
+	r, err := repo.Open(dbPath)
+	if err != nil {
+		t.Fatalf("open sqlite: %v", err)
+	}
+	t.Cleanup(func() { _ = r.Close() })
+
+	// Create speed limit
+	speedLimitID, err := r.CreateSpeedLimit("get-speed-test", 500, nil, "", 1, 1)
+	if err != nil {
+		t.Fatalf("create speed limit: %v", err)
+	}
+
+	// Test GetSpeedLimitSpeed
+	t.Run("GetSpeedLimitSpeed returns correct speed", func(t *testing.T) {
+		speed, err := r.GetSpeedLimitSpeed(speedLimitID)
+		if err != nil {
+			t.Fatalf("GetSpeedLimitSpeed failed: %v", err)
+		}
+		if speed != 500 {
+			t.Fatalf("expected speed 500, got %d", speed)
+		}
+	})
+
+	t.Run("GetSpeedLimitSpeed returns error for non-existent id", func(t *testing.T) {
+		_, err := r.GetSpeedLimitSpeed(99999)
+		if err == nil {
+			t.Fatal("expected error for non-existent speed limit ID")
+		}
+	})
+}
+
+// Helper functions
+
+func mustCreateSpeedLimitTunnel(t *testing.T, r *repo.Repository, name string) int64 {
+	t.Helper()
+	now := time.Now().UnixMilli()
+	if err := r.DB().Exec(`
+		INSERT INTO tunnel(name, traffic_ratio, type, protocol, flow, created_time, updated_time, status, in_ip, inx)
+		VALUES(?, 1.0, 1, 'tls', 99999, ?, ?, 1, NULL, 0)
+	`, name, now, now).Error; err != nil {
+		t.Fatalf("create tunnel failed: %v", err)
+	}
+	return mustLastInsertID(t, r, name)
+}
+
+func mustCreateSpeedLimitRepo(t *testing.T, r *repo.Repository, name string, tunnelID int64) int64 {
+	t.Helper()
+	now := time.Now().UnixMilli()
+	var tid *int64
+	if tunnelID > 0 {
+		tid = &tunnelID
+	}
+	id, err := r.CreateSpeedLimit(name, 100, tid, "", now, 1)
+	if err != nil {
+		t.Fatalf("create speed limit failed: %v", err)
+	}
+	return id
+}

go-gost/AGENTS.md

@@ -1,6 +1,6 @@
 # GO-GOST SERVICE KNOWLEDGE BASE
 
-**Generated:** Sun Feb 15 2026
+**Generated:** Thu Feb 26 2026
 
 ## OVERVIEW
 Forwarding agent built on GOST v3 with a local fork of `github.com/go-gost/x` under `x/`.
@@ -19,16 +19,18 @@ go-gost/
 ## WHERE TO LOOK
 | Task | Location | Notes |
 |------|----------|-------|
-| Panel integration config | `go-gost/config.go` | Expects `config.json` in cwd by default |
-| Service lifecycle/reload | `go-gost/program.go` | Parses config; handles SIGHUP reload |
-| WebSocket reporting | `go-gost/main.go` | Starts reporter + sets HTTP report URL |
-| Protocol behaviors | `go-gost/x/` | Handlers/listeners/dialers live here |
+| **Panel integration config** | `go-gost/config.go` | Expects `config.json` in cwd by default |
+| **Service lifecycle/reload** | `go-gost/program.go` | Parses config; handles SIGHUP reload |
+| **WebSocket reporting** | `go-gost/main.go` | Starts reporter + sets HTTP report URL |
+| **Protocol behaviors** | `go-gost/x/` | Handlers/listeners/dialers live here |
+| **Build** | `go-gost/Makefile` | Cross-compile targets for amd64/arm64 |
 
 ## CONVENTIONS
 - Two configs exist: panel integration uses `config.json`; forwarding services use GOST config (defaults to `gost.{json,yaml}` via viper search paths).
 - `go-gost/x/` is the primary extension surface; avoid editing vendored deps.
 - Agent communicates with panel via WebSocket (real-time commands) + HTTP (batch traffic reports).
 - All panel communication uses AES encryption with node `secret` as PSK.
+- CI builds with `CGO_ENABLED=0` for static binaries, then compresses with UPX.
 
 ## ANTI-PATTERNS
 - **DO NOT EDIT** generated protobuf in `x/internal/util/grpc/proto/`.

go-gost/x/AGENTS.md

@@ -6,27 +6,28 @@ Local fork of `github.com/go-gost/x` used by `go-gost/` via `replace github.com/
 ## STRUCTURE
 ```
 go-gost/x/
-├── api/        # Gin management API + embedded swagger docs
+├── api/        # Gin management API + embedded swagger docs (22 files)
 ├── config/     # Config model + parsing/load/reload
 ├── connector/  # Outbound connect implementations
-├── dialer/     # Outbound dialers (tcp/tls/ws/quic/...) 
+├── dialer/     # Outbound dialers (tcp/tls/ws/quic/...)
 ├── handler/    # Protocol handlers (socks/http/tunnel/relay/...)
 ├── listener/   # Inbound listeners (tcp/udp/tun/tap/redirect/...)
 ├── limiter/    # Traffic/rate/conn limiters
-├── registry/   # Registries for services/handlers/listeners/etc
+├── registry/   # Registries for services/handlers/listeners/etc (20 files)
 ├── service/    # Service wrappers + reporting hooks
-├── socket/     # WebSocket reporter / panel integration
+├── socket/     # WebSocket reporter / panel integration (6 files)
 └── internal/   # Shared internals (grpc proto, net utils, sniffing, tls, ...)
 ```
 
 ## WHERE TO LOOK
 | Task | Location | Notes |
 |------|----------|-------|
-| Management API routes/auth | `go-gost/x/api/api.go` | `/docs`, `/config/*`; BasicAuth + interceptor |
-| Service config parsing | `go-gost/x/config/parsing/` | Converts config to running services |
-| Add a handler | `go-gost/x/handler/` | Per-protocol subdirs |
-| Add a listener/dialer | `go-gost/x/listener/`, `go-gost/x/dialer/` | Transport variants |
-| Panel reporting | `go-gost/x/socket/` | WebSocket + HTTP report URL hooks |
+| **Management API routes/auth** | `go-gost/x/api/api.go` | `/docs`, `/config/*`; BasicAuth + interceptor |
+| **Service config parsing** | `go-gost/x/config/parsing/` | Converts config to running services |
+| **Add a handler** | `go-gost/x/handler/` | Per-protocol subdirs |
+| **Add a listener/dialer** | `go-gost/x/listener/`, `go-gost/x/dialer/` | Transport variants |
+| **Panel reporting** | `go-gost/x/socket/` | WebSocket + HTTP report URL hooks |
+| **Register new component** | `go-gost/x/registry/` | `Register{Type}(name, creator)` |
 
 ## CONVENTIONS
 - `go-gost/x/` is a standalone Go module (`go-gost/x/go.mod`); run go tooling from this dir when debugging module resolution.
@@ -41,4 +42,4 @@ go-gost/x/
 ```bash
 cd go-gost/x
 go test ./...
-```
+```

test-results/.last-run.json

@@ -0,0 +1,4 @@
+{
+  "status": "failed",
+  "failedTests": []
+}

vite-frontend/.env.production

@@ -1 +1,2 @@
-VITE_API_BASE=
+VITE_GITHUB_REPO=https://github.com/Sagit-chu/flvx
+VITE_APP_VERSION=beta

vite-frontend/AGENTS.md

@@ -1,55 +1,65 @@
 # VITE FRONTEND KNOWLEDGE BASE
 
-**Generated:** Sun Feb 15 2026
+**Generated:** Thu Feb 26 2026
+**Commit:** 21008cc
+**Branch:** main
+**Tag:** 2.1.5-rc15
 
 ## OVERVIEW
 Web management console for FLVX.
-**Stack:** React 18, Vite 5 (rolldown-vite), TypeScript, TailwindCSS 4, HeroUI.
+**Stack:** React 18, rolldown-vite, TypeScript, Tailwind CSS v4, shadcn/radix primitives with HeroUI-compatible bridge.
 
 ## STRUCTURE
 ```
 vite-frontend/
 ├── src/
-│   ├── api/          # Axios wrapper + typed endpoint helpers
-│   ├── components/   # Shared UI components (HeroUI based)
-│   ├── config/       # Site config (title, repo, version)
-│   ├── layouts/      # Admin vs H5 page chrome
-│   ├── pages/        # Route views (many large single-file pages)
-│   ├── utils/        # Auth/JWT + WebView helpers
-│   ├── App.tsx       # Routes + ProtectedRoute + H5 layout selection
-│   ├── main.tsx      # ReactDOM + Providers (HeroUI, Theme, Toast)
-│   └── provider.tsx  # Context provider wrapper
-├── vite.config.ts    # base '/', host 0.0.0.0:3000; build minify/treeshake disabled
-├── eslint.config.mjs  # ESLint 9 flat config
+│   ├── api/                      # Axios wrapper + typed endpoint helpers
+│   ├── components/ui/            # shadcn/radix primitive components
+│   ├── shadcn-bridge/heroui/     # HeroUI-compatible facade (23 components)
+│   ├── pages/                    # Route views + page modules (forward/node/tunnel)
+│   ├── hooks/                    # H5/WebView/mobile hooks
+│   ├── styles/
+│   │   ├── globals.css           # Base styles + imports tailwind-theme.pcss
+│   │   └── tailwind-theme.pcss   # Tailwind v4 @theme inline semantic token mapping
+│   ├── App.tsx                   # Routes + ProtectedRoute + H5 layout selection
+│   ├── main.tsx                  # ReactDOM + BrowserRouter + Provider
+│   └── provider.tsx              # Toast/theme/provider composition
+├── components.json               # shadcn/ui config
+├── tailwind.config.js            # Compatibility config for migration scaffolding
+├── vite.config.ts                # base '/', host 0.0.0.0:3000; minify/treeshake disabled
 └── package.json
 ```
 
 ## WHERE TO LOOK
 | Task | Location | Notes |
 |------|----------|-------|
-| **Route definitions** | `src/App.tsx` | React Router v6; H5 detection logic |
-| **API Client** | `src/api/network.ts` | Sets `Authorization` header (raw token) |
-| **Endpoint Calls** | `src/api/index.ts` | Thin `Network.post` wrappers |
+| **Route definitions** | `src/App.tsx` | React Router v6 + ProtectedRoute |
+| **API Client/Auth header** | `src/api/network.ts` | Sends raw JWT in `Authorization` header |
 | **Login Flow** | `src/pages/index.tsx` | Calls `login()`, stores `localStorage.token` |
-| **Auth Logic** | `src/utils/auth.ts` | `isAdmin()` checks `role_id == 0` |
-| **Token Decoding** | `src/utils/jwt.ts` | Checks `exp` vs current time |
-| **WebView Logic** | `src/utils/panel.ts` | Handles panel address selection in app mode |
+| **Auth helpers** | `src/utils/auth.ts`, `src/utils/jwt.ts` | Role checks + token expiration parsing |
+| **UI bridge usage** | `src/shadcn-bridge/heroui/` | Import from bridge, not `@heroui/*` |
+| **Button parity mapping** | `src/shadcn-bridge/heroui/button.tsx` | Legacy `color`/`variant` mapped to shadcn classes |
+| **Semantic theme tokens** | `src/styles/tailwind-theme.pcss` | Restores classes like `bg-primary`, `border-input` |
+| **Theme wiring** | `src/styles/globals.css` | Must import `./tailwind-theme.pcss` |
 
 ## CONVENTIONS
-- **Auth**: JWT stored as `localStorage.token`. Sent in `Authorization` header (no "Bearer" prefix).
-- **API**: Default base URL is `/api/v1/`. Responses follow `{code, msg, data, ts}` structure.
-- **WebView**: In WebView mode, base URL is derived from selected panel address. If unset, API returns `code: -1`.
-- **Routing**: URL query param `h5=true` forces mobile layout.
-- **Build**: `minify: false`, `treeshake: false` - unoptimized production bundles for debugging.
-- **ESLint**: `react-hooks/exhaustive-deps` disabled, unused vars starting with `_` ignored.
-- **Large Pages**: `forward.tsx` (3263 LOC), `tunnel.tsx` (2552 LOC), `node.tsx` (2194 LOC).
+- **Auth Header**: Use raw JWT token (no `Bearer` prefix).
+- **API Envelope**: Responses follow `{code, msg, data, ts}`.
+- **UI Imports**: Use `src/shadcn-bridge/heroui/*` in app pages/layouts for compatibility.
+- **Semantic Colors**: Keep `globals.css -> tailwind-theme.pcss` import intact or semantic classes break.
+- **Build profile**: `minify: false`, `treeshake: false` for debugging.
+- **Layout mode**: H5/mobile mode controlled by existing route/query and hook logic.
 
 ## ANTI-PATTERNS
-- **DO NOT ADD** tests - no test infrastructure (Vitest/Jest not configured).
+- **DO NOT ADD** `Bearer` to auth header in frontend requests.
+- **DO NOT REINTRODUCE** `@heroui/*` or `@nextui-org/*` dependencies.
+- **DO NOT REMOVE** `src/styles/tailwind-theme.pcss` import from `src/styles/globals.css`.
+- **DO NOT ADD** frontend tests; no Vitest/Jest setup exists.
 
 ## NOTES
 - Uses `rolldown-vite` (experimental Rust bundler) instead of standard Vite.
-- ESLint Flat Config format with custom import ordering rules.
+- Build outputs are non-minified (debugging mode).
+- No test infrastructure exists (Vitest/Jest not configured).
 
 ## COMMANDS
 ```bash

vite-frontend/components.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "tailwind.config.js",
+    "css": "src/styles/globals.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "iconLibrary": "lucide"
+}

vite-frontend/docs/frontend-refactor-plan-2026-02-18.md

@@ -0,0 +1,222 @@
+# 前端彻底重构计划（进行中）
+
+- 分支：`frontend/refactor-audit-20260218`
+- 范围：`vite-frontend/src`
+- 更新时间：2026-02-19
+- 当前总体进度：`99.5%`
+
+## 1) 问题审计（已完成）
+
+### P0（高风险，优先修复）
+
+- [x] `src/api/network.ts` 存在 token 过期后 Promise 不 resolve 的路径（`then/catch` 里仅 `return`，调用方可能挂起）
+- [x] 登录态读写逻辑分散在多个页面/布局，存在重复和不一致风险（`src/pages/index.tsx`、`src/layouts/admin.tsx`、`src/layouts/h5.tsx`、`src/pages/profile.tsx`、`src/pages/group.tsx`）
+- [x] 核心页面超大文件导致可维护性差：`forward.tsx`(3263 行)、`tunnel.tsx`(2595 行)、`node.tsx`(2194 行)、`user.tsx`(1761 行)、`dashboard.tsx`(1363 行)
+- [x] `any` 使用过多，类型边界不清（`src/api/index.ts`、`src/api/network.ts`、`src/pages/*`）
+
+### P1（中风险，本次并行推进）
+
+- [x] 多处空 `catch {}` 吞错，定位问题困难（如 `src/App.tsx`、`src/components/navbar.tsx`、`src/pages/config.tsx` 等）
+- [x] 移动端/H5/WebView 判定逻辑重复（`src/App.tsx`、`src/pages/index.tsx`、`src/components/navbar.tsx`）
+- [x] 菜单与权限控制在多处重复定义，布局和页面耦合偏高（`src/layouts/admin.tsx`、`src/layouts/h5.tsx`、`src/pages/profile.tsx`）
+- [x] 路由保护与布局选择逻辑集中在 `src/App.tsx`，可测试性和扩展性偏弱
+
+### P2（优化项，后续阶段）
+
+- [x] `vite.config.ts` 生产构建配置 `minify: false`、`treeshake: false`，性能优化策略待梳理
+- [x] ESLint 中 `react-hooks/exhaustive-deps` 关闭，副作用依赖约束较弱（`eslint.config.mjs`）
+
+## 2) 彻底重构任务清单（边做边更新）
+
+> 状态说明：`[x] 完成` / `[ ] 未开始` / `[-] 进行中`
+
+### Phase A - 会话与权限基建
+
+- [x] A1. 新增统一会话工具模块（token/role/name/admin 的读写与兼容逻辑）
+- [x] A2. 登录页改为调用会话工具写入登录态，去重重复代码
+- [x] A3. 布局与页面的管理员判断改为统一工具，移除重复逻辑
+- [x] A4. `Network` 层统一 token 获取与 token 过期处理，避免悬挂 Promise
+
+### Phase B - Hook 与状态复用
+
+- [x] B1. 提取 `useWebViewMode`，替换 `index/navbar` 重复检测
+- [x] B2. 提取 `useH5Mode`，收敛 `App` 内设备与参数判定逻辑
+- [x] B3. 提取滚动复位逻辑（`H5/H5-simple`）到通用 hook
+
+### Phase C - API 与类型边界
+
+- [x] C1. 收紧 `src/api/network.ts` 的 `any` 边界（优先 `unknown` + 受控转换）
+- [-] C2. 给高频 API 接口补全请求/响应类型（先用户、节点、隧道、转发）
+- [-] C3. 统一错误消息提取策略，避免散落式字符串拼接
+
+### Phase D - 大页面拆分（增量，不大爆炸重写）
+
+- [-] D1. `forward.tsx` 抽离：筛选条、列表视图、批量操作、详情弹窗
+- [-] D2. `tunnel.tsx` 抽离：表单区、列表区、排序区、诊断区
+- [-] D3. `node.tsx` 抽离：状态区、安装命令区、排序区、WebSocket 区
+- [ ] D4. `dashboard.tsx` 抽离：统计卡片、图表区、公告区、刷新逻辑
+
+### Phase E - 体验与可访问性
+
+- [-] E1. 统一关键交互控件的 `aria-label` / 键盘可达性
+- [-] E2. 统一 loading/empty/error 三态展示组件
+- [-] E3. 统一移动端断点与布局响应策略
+
+## 15) 当前实施批次（Batch-12）
+
+- 目标：推进 **D2/D4/E1/E2/E3** 收尾，完成表单模块接入、仪表盘增量拆分与通用能力落地
+- 本批次进度：`6 / 6`
+
+### Batch-12 明细进度
+
+- [x] T51. `tunnel.tsx` 接入 `tunnel/form.ts`（默认值、表单校验、类型/流量展示）
+- [x] T52. 修复 `limit.tsx` 构建阻断问题（移除未使用 `Spinner` 导入）
+- [x] T53. `dashboard.tsx` 抽离公告区与指标卡公共组件（`dashboard/components/*`）
+- [x] T54. `dashboard.tsx` 管理员判定切换为 `session` 统一工具（`getAdminFlag`）
+- [x] T55. `admin.tsx` 接入 `useMobileBreakpoint` 收敛断点监听；`settings.tsx` 回填返回按钮 `aria-label`
+- [x] T56. 执行 `npm run build` + `npm run lint` 校验（lint 仅剩既有 `no-console` warning）
+
+## 3) 当前实施批次（Batch-1）
+
+- 目标：先完成 **A1/A2/A3/A4 + B1/B2 + C1**，优先解决架构一致性和稳定性风险
+- 本批次进度：`7 / 7`
+
+### Batch-1 明细进度
+
+- [x] T1. 新增 `session` 统一会话工具（A1）
+- [x] T2. 登录页切换到会话工具（A2）
+- [x] T3. `admin/h5/profile/group` 切换管理员判定工具（A3）
+- [x] T4. `network` 统一 token 与过期返回（A4 + C1）
+- [x] T5. 新增 `useWebViewMode` 并接入 `index/navbar`（B1）
+- [x] T6. 新增 `useH5Mode` 并接入 `App`（B2）
+- [x] T7. 执行 `npm run build` 与必要诊断校验
+
+## 4) 当前实施批次（Batch-2）
+
+- 目标：推进 **D2/D3 的排序逻辑抽离** 与 **会话 token 复用**，降低大型页面重复代码
+- 本批次进度：`7 / 7`
+
+### Batch-2 明细进度
+
+- [x] T8. 新增通用排序存储工具（node/tunnel 共用）
+- [x] T9. `tunnel.tsx` 接入排序存储工具
+- [x] T10. `node.tsx` 接入排序存储工具
+- [x] T11. `node.tsx` WebSocket token 改用统一会话工具
+- [x] T12. 执行 `npm run build` 与必要诊断校验
+- [x] T13. 新增 `useScrollTopOnPathChange` 通用 hook
+- [x] T14. `h5/h5-simple` 接入滚动复位 hook 并完成构建校验
+
+## 5) 当前实施批次（Batch-3）
+
+- 目标：推进 **D3（node WebSocket 区域）结构化抽离**，先拆出系统信息解析逻辑
+- 本批次进度：`4 / 4`
+
+### Batch-3 明细进度
+
+- [x] T15. 新增 `node` 系统信息解析工具模块
+- [x] T16. `node.tsx` WebSocket `info` 消息处理接入解析工具
+- [x] T17. 保持在线/离线状态切换与速度计算逻辑一致
+- [x] T18. 执行 `npm run build` 与必要诊断校验
+
+## 6) 外部最佳实践参考（已纳入本计划）
+
+- React 官方：重复逻辑应抽为自定义 Hook（`reusing-logic-with-custom-hooks`）
+- React 官方：共享逻辑不共享状态，跨组件共享状态应提升或集中管理
+- Vite 官方：大型项目优先审计插件成本、动态导入与分块策略
+- WAI-ARIA APG：导航与交互组件优先语义化与键盘可达性
+
+## 7) 当前实施批次（Batch-4）
+
+- 目标：继续推进 **D3（node WebSocket 区域）**，抽离连接生命周期与重连策略
+- 本批次进度：`4 / 4`
+
+### Batch-4 明细进度
+
+- [x] T19. 新增 `useNodeRealtime` Hook（连接/重连/断开）
+- [x] T20. `node.tsx` 接入 `useNodeRealtime`，移除内联连接管理代码
+- [x] T21. 保留离线延迟逻辑并在页面卸载时清理离线定时器
+- [x] T22. 执行 `npm run build` 与必要诊断校验
+
+## 8) 当前实施批次（Batch-5）
+
+- 目标：继续推进 **D3（node WebSocket 区域）**，抽离离线延迟定时器生命周期
+- 本批次进度：`4 / 4`
+
+### Batch-5 明细进度
+
+- [x] T23. 新增 `useNodeOfflineTimers` Hook（离线延迟/清理）
+- [x] T24. `node.tsx` 接入 `useNodeOfflineTimers`，移除内联定时器管理
+- [x] T25. 校验状态/信息消息路径行为一致（在线切换与离线延迟）
+- [x] T26. 执行 `npm run build` 与必要诊断校验
+
+## 9) 当前实施批次（Batch-6）
+
+- 目标：推进 **D2（tunnel 诊断区）**，抽离诊断兜底与质量评估逻辑
+- 本批次进度：`4 / 4`
+
+### Batch-6 明细进度
+
+- [x] T27. 新增 `tunnel/diagnosis` 诊断工具模块
+- [x] T28. `tunnel.tsx` 接入诊断兜底与质量评估工具
+- [x] T29. 校验诊断弹窗展示逻辑与质量标签行为一致
+- [x] T30. 执行 `npm run build` 与必要诊断校验
+
+## 10) 当前实施批次（Batch-7）
+
+- 目标：推进 **C2/C3（API 类型边界与错误消息统一）**，先覆盖高频 node/tunnel/forward 路径
+- 本批次进度：`4 / 4`
+
+### Batch-7 明细进度
+
+- [x] T31. 新增 `api` 高频领域类型定义（node/tunnel/forward）
+- [x] T32. `api/index.ts` 的高频列表接口接入类型定义
+- [x] T33. 新增网络错误消息提取工具并接入 `network.ts`
+- [x] T34. 执行 `npm run build` 与必要诊断校验
+
+## 11) 当前实施批次（Batch-8）
+
+- 目标：推进 **D1（forward 排序区）**，抽离直接模式排序初始化逻辑
+- 本批次进度：`4 / 4`
+
+### Batch-8 明细进度
+
+- [x] T35. 新增 `forward/order` 排序工具模块
+- [x] T36. `forward.tsx` 接入排序工具并复用通用存储
+- [x] T37. 校验直接模式排序初始化与拖拽持久化行为一致
+- [x] T38. 执行 `npm run build` 与必要诊断校验
+
+## 12) 当前实施批次（Batch-9）
+
+- 目标：推进 **D1（forward 诊断区）**，抽离诊断兜底与质量评估逻辑
+- 本批次进度：`4 / 4`
+
+### Batch-9 明细进度
+
+- [x] T39. 新增 `forward/diagnosis` 诊断工具模块
+- [x] T40. `forward.tsx` 接入诊断兜底与质量评估工具
+- [x] T41. 校验诊断弹窗展示与质量标签行为一致
+- [x] T42. 执行 `npm run build` 与必要诊断校验
+
+## 13) 当前实施批次（Batch-10）
+
+- 目标：推进 **D1（forward 批量操作区）**，抽离批量动作执行与反馈逻辑
+- 本批次进度：`4 / 4`
+
+### Batch-10 明细进度
+
+- [x] T43. 新增 `forward/batch-actions` 批量操作工具模块
+- [x] T44. `forward.tsx` 接入批量操作工具并移除重复处理分支
+- [x] T45. 校验批量删除/启停/重下发/换隧道行为一致
+- [x] T46. 执行 `npm run build` 与必要诊断校验
+
+## 14) 当前实施批次（Batch-11）
+
+- 目标：推进 **D1（forward 地址展示/复制区）**，抽离地址格式化与弹窗分流逻辑
+- 本批次进度：`4 / 4`
+
+### Batch-11 明细进度
+
+- [x] T47. 新增 `forward/address` 地址工具模块
+- [x] T48. `forward.tsx` 接入地址工具并移除内联格式化/分流逻辑
+- [x] T49. 校验地址单项复制与多项弹窗行为一致
+- [x] T50. 执行 `npm run build` 与必要诊断校验

vite-frontend/docs/shadcn-ui-full-migration-2026-02-19.md

@@ -0,0 +1,52 @@
+# shadcn/ui 全量迁移计划（已完成）
+
+- 分支：`feat/shadcn-ui-full-migration-20260219`
+- 日期：`2026-02-19`
+- 目标：将 `vite-frontend` 从 HeroUI 彻底迁移到 shadcn/ui（含依赖、Provider、组件实现与构建验证）
+- 说明：用户提到的 `shadcu-ui` 按 `shadcn/ui` 执行
+
+## 0. 现状基线（已完成）
+
+- HeroUI 直接使用文件：`22` 个（`src/` 下）
+- HeroUI 组件族：`button/card/input/select/modal/table/chip/spinner/switch/alert/accordion/checkbox/dropdown/tabs/radio/date-picker/progress/navbar/link/system/use-theme` 等
+- 关键复杂页：`forward.tsx`、`tunnel.tsx`、`node.tsx`、`user.tsx`
+- 语义色类大量依赖：`text-default-*`、`bg-primary-*`、`border-divider`、`text-foreground` 等
+
+## 1. 执行步骤
+
+状态标记：`[ ] 未开始` / `[-] 进行中` / `[x] 已完成`
+
+- [x] S1. 创建迁移分支并冻结迁移范围（仅 `vite-frontend`）
+- [x] S2. 完成全量使用点扫描（Grep/rg/AST + 官方文档检索）
+- [x] S3. 建立 shadcn/ui 基础设施（`components.json`、`src/lib/utils.ts`、`src/components/ui/*` 基础原子组件）
+- [x] S4. 建立 HeroUI -> shadcn 兼容桥接层（`src/shadcn-bridge/heroui/*`）并替换全部页面导入
+- [x] S5. 迁移全局 Provider/主题能力（替换 `HeroUIProvider`、`useTheme`、`useDisclosure`）
+- [x] S6. 替换 Tailwind 主题来源（移除 HeroUI 主题插件，补齐语义色 token 与兼容工具类）
+- [x] S7. 移除 HeroUI 依赖并修复构建（`npm install` + `npm run build`）
+- [x] S8. 回写完成记录与验收（确认无 `@heroui/*` 运行时依赖）
+
+## 2. 组件映射策略（本次执行）
+
+- Button -> shadcn `button` + 兼容 `isLoading/isIconOnly/startContent/endContent/onPress`
+- Input/Textarea -> shadcn `input/textarea` + label/description/error 容器
+- Modal -> shadcn `dialog`（兼容 `isOpen/onOpenChange` 与 Header/Body/Footer 插槽）
+- Select -> shadcn `select`（单选）+ 命令式多选兼容实现（多选场景）
+- Table -> shadcn `table`（兼容 `items + render function + empty/loading`）
+- Dropdown/Tabs/Radio/Switch/Checkbox/Accordion/Alert/Progress/Card/Separator -> 对应 shadcn 组件封装
+- DatePicker -> 基于原生日期输入 + 兼容 value/onChange 的桥接实现（保留现有业务数据结构）
+
+## 3. 执行记录（每步完成即更新）
+
+- [2026-02-19] 完成 S1：创建分支 `feat/shadcn-ui-full-migration-20260219`
+- [2026-02-19] 完成 S2：完成 HeroUI 使用点与迁移风险扫描；确认迁移顺序
+- [2026-02-19] 完成 S3：新增 `components.json`、`src/lib/utils.ts` 与 `src/components/ui/*`（button/dialog/dropdown/select/table/checkbox/switch/tabs/accordion/progress 等）
+- [2026-02-19] 完成 S4：新增 `src/shadcn-bridge/heroui/*` 兼容桥接层，并将现网全部导入替换为 `@/shadcn-bridge/heroui/*`
+- [2026-02-19] 完成 S5：通过桥接层接管 `HeroUIProvider`、`useTheme`、`useDisclosure`，保持页面业务逻辑不改动
+- [2026-02-19] 完成 S6：移除 `@heroui/theme` Tailwind 插件，改为本地 token 体系（`tailwind.config.js` + `src/styles/globals.css`）
+- [2026-02-19] 完成 S7：删除全部 HeroUI/NextUI 依赖，补齐 `@internationalized/date` 与 `@react-aria/i18n` 显式依赖
+- [2026-02-19] 完成 S8：构建验收通过（`npm run build`），`package.json` 已无 `heroui/nextui` 依赖
+- [2026-02-19] 验证结果：业务代码中 `@heroui/*` 导入为 `0`，已统一替换为 `@/shadcn-bridge/heroui/*`（22 文件，106 处）
+- [2026-02-19] 后续修复：`src/components/ui/button.tsx` 与 `src/shadcn-bridge/heroui/button.tsx` 改为 `forwardRef`，消除 `DropdownMenuTrigger asChild` 场景 ref 警告；复构建通过
+- [2026-02-19] 回归修复：定位“按钮边框/颜色丢失”根因是 Tailwind v4 下语义色未生成；新增 `src/styles/tailwind-theme.pcss`（由 `src/styles/globals.css` 引入）承载 `@theme inline` token 映射，恢复 `bg-primary`/`text-foreground`/`border-input` 等语义类输出
+- [2026-02-19] 回归修复：增强 `src/shadcn-bridge/heroui/button.tsx` 的 `solid/light/flat/bordered/shadow` 颜色映射，并修正 `src/components/ui/button.tsx` 的 `outline/ghost` hover 语义类，避免依赖未定义的 `accent` 色
+- [2026-02-19] 复验结果：`npm run build` 通过；编译产物已包含关键语义类；页面级视觉回归（forward/tunnel/node/user）通过（后端未启动时仅保留 `ERR_CONNECTION_REFUSED` 噪音）

vite-frontend/index.html

@@ -2,7 +2,12 @@
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
-    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <link rel="icon" type="image/png" href="/pwa-192x192.png" />
+    <meta name="theme-color" content="#2563eb" />
+    <meta name="apple-mobile-web-app-capable" content="yes" />
+    <meta name="apple-mobile-web-app-status-bar-style" content="default" />
+    <meta name="apple-mobile-web-app-title" content="FLVX" />
+    <link rel="apple-touch-icon" href="/apple-touch-icon.png" />
     
     <title>FLVX</title>
     <script>

vite-frontend/package.json

@@ -13,55 +13,46 @@
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/sortable": "^10.0.0",
     "@dnd-kit/utilities": "^3.2.2",
-    "@heroui/accordion": "^2.2.21",
-    "@heroui/alert": "^2.2.24",
-    "@heroui/autocomplete": "^2.3.25",
-    "@heroui/avatar": "^2.2.19",
-    "@heroui/badge": "^2.2.15",
-    "@heroui/button": "2.2.23",
-    "@heroui/card": "^2.2.22",
-    "@heroui/chip": "^2.2.19",
-    "@heroui/code": "2.2.17",
-    "@heroui/date-picker": "^2.3.22",
-    "@heroui/dropdown": "2.3.23",
-    "@heroui/image": "^2.2.15",
-    "@heroui/input": "2.4.24",
-    "@heroui/kbd": "2.2.18",
-    "@heroui/link": "2.2.20",
-    "@heroui/modal": "^2.2.21",
-    "@heroui/navbar": "2.2.21",
-    "@heroui/pagination": "^2.2.21",
-    "@heroui/progress": "^2.2.20",
-    "@heroui/radio": "^2.3.24",
-    "@heroui/select": "^2.4.22",
-    "@heroui/snippet": "2.2.24",
-    "@heroui/spinner": "^2.2.20",
-    "@heroui/switch": "^2.2.21",
-    "@heroui/system": "2.4.19",
-    "@heroui/table": "^2.2.24",
-    "@heroui/tabs": "^2.2.27",
-    "@heroui/theme": "2.4.24",
-    "@heroui/use-theme": "2.1.10",
+    "@internationalized/date": "^3.10.0",
     "@marsidev/react-turnstile": "^1.1.0",
-    "@nextui-org/system": "^2.4.6",
+    "@radix-ui/react-accordion": "^1.2.0",
+    "@radix-ui/react-checkbox": "^1.1.0",
+    "@radix-ui/react-dialog": "^1.1.0",
+    "@radix-ui/react-dropdown-menu": "^2.1.0",
+    "@radix-ui/react-label": "^2.1.0",
+    "@radix-ui/react-progress": "^1.1.0",
+    "@radix-ui/react-radio-group": "^1.2.0",
+    "@radix-ui/react-select": "^2.1.0",
+    "@radix-ui/react-separator": "^1.1.0",
+    "@radix-ui/react-slot": "^1.1.0",
+    "@radix-ui/react-switch": "^1.1.0",
+    "@radix-ui/react-tabs": "^1.1.0",
+    "@react-aria/i18n": "^3.12.12",
     "@react-aria/visually-hidden": "3.8.25",
     "@react-types/shared": "3.30.0",
     "@tailwindcss/postcss": "4.1.11",
     "@tailwindcss/vite": "^4.1.18",
     "@types/react-beautiful-dnd": "^13.1.8",
     "axios": "^1.11.0",
+    "class-variance-authority": "^0.7.1",
     "clsx": "2.1.1",
     "framer-motion": "11.18.2",
+    "lucide-react": "^0.542.0",
     "react": "18.3.1",
     "react-beautiful-dnd": "^13.1.1",
     "react-dom": "18.3.1",
     "react-hot-toast": "^2.5.2",
     "react-is": "^19.2.4",
+    "react-markdown": "^10.1.0",
     "react-router-dom": "6.30.3",
     "recharts": "^3.1.1",
+    "rehype-sanitize": "^6.0.0",
+    "remark-gfm": "^4.0.1",
     "sonner": "^2.0.6",
+    "tailwind-merge": "^2.5.5",
     "tailwind-variants": "1.0.0",
-    "tailwindcss": "4.1.11"
+    "tailwindcss": "4.1.11",
+    "tw-animate-css": "^1.3.0"
   },
   "devDependencies": {
     "@eslint/compat": "1.2.8",
@@ -87,6 +78,7 @@
     "prettier": "3.5.3",
     "typescript": "5.6.3",
     "vite": "npm:rolldown-vite@^7.3.1",
+    "vite-plugin-pwa": "^1.1.0",
     "vite-tsconfig-paths": "^6.0.5"
   }
 }

vite-frontend/src/App.tsx

@@ -1,5 +1,5 @@
 import { Route, Routes, useNavigate } from "react-router-dom";
-import { useEffect, useState } from "react";
+import { useEffect } from "react";
 
 import IndexPage from "@/pages/index";
 import ChangePasswordPage from "@/pages/change-password";
@@ -18,51 +18,8 @@ import AdminLayout from "@/layouts/admin";
 import H5Layout from "@/layouts/h5";
 import H5SimpleLayout from "@/layouts/h5-simple";
 import { isLoggedIn } from "@/utils/auth";
-import { siteConfig } from "@/config/site";
-
-// 检测是否为H5模式
-const useH5Mode = () => {
-  // 立即检测H5模式，避免初始渲染时的闪屏
-  const getInitialH5Mode = () => {
-    // 检测移动设备或小屏幕
-    const isMobile = window.innerWidth <= 768;
-    // 检测是否为移动端浏览器
-    const isMobileBrowser =
-      /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(
-        navigator.userAgent,
-      );
-    // 检测URL参数是否包含h5模式
-    const urlParams = new URLSearchParams(window.location.search);
-    const isH5Param = urlParams.get("h5") === "true";
-
-    return isMobile || isMobileBrowser || isH5Param;
-  };
-
-  const [isH5, setIsH5] = useState(getInitialH5Mode);
-
-  useEffect(() => {
-    const checkH5Mode = () => {
-      // 检测移动设备或小屏幕
-      const isMobile = window.innerWidth <= 768;
-      // 检测是否为移动端浏览器
-      const isMobileBrowser =
-        /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(
-          navigator.userAgent,
-        );
-      // 检测URL参数是否包含h5模式
-      const urlParams = new URLSearchParams(window.location.search);
-      const isH5Param = urlParams.get("h5") === "true";
-
-      setIsH5(isMobile || isMobileBrowser || isH5Param);
-    };
-
-    window.addEventListener("resize", checkH5Mode);
-
-    return () => window.removeEventListener("resize", checkH5Mode);
-  }, []);
-
-  return isH5;
-};
+import { siteConfig, updateSiteConfig } from "@/config/site";
+import { useH5Mode } from "@/hooks/useH5Mode";
 
 // 简化的路由保护组件 - 使用 React Router 导航避免循环
 const ProtectedRoute = ({
@@ -99,15 +56,8 @@ const ProtectedRoute = ({
   }
 
   // 根据模式和页面类型选择布局
-  let Layout;
-
-  if (isH5 && useSimpleLayout) {
-    Layout = H5SimpleLayout;
-  } else if (isH5) {
-    Layout = H5Layout;
-  } else {
-    Layout = AdminLayout;
-  }
+  const Layout =
+    isH5 && useSimpleLayout ? H5SimpleLayout : isH5 ? H5Layout : AdminLayout;
 
   return <Layout>{children}</Layout>;
 };
@@ -140,23 +90,17 @@ function App() {
   useEffect(() => {
     document.title = siteConfig.name;
 
-    // 异步检查是否有配置更新
-    const checkTitleUpdate = async () => {
-      try {
-        // 引入必要的函数
-        const { getCachedConfig } = await import("@/config/site");
-        const cachedAppName = await getCachedConfig("app_name");
+    void updateSiteConfig();
 
-        if (cachedAppName && cachedAppName !== document.title) {
-          document.title = cachedAppName;
-        }
-      } catch {}
+    const handleConfigUpdate = () => {
+      void updateSiteConfig();
     };
 
-    // 延迟检查，避免阻塞初始渲染
-    const timer = setTimeout(checkTitleUpdate, 100);
+    window.addEventListener("configUpdated", handleConfigUpdate);
 
-    return () => clearTimeout(timer);
+    return () => {
+      window.removeEventListener("configUpdated", handleConfigUpdate);
+    };
   }, []);
 
   return (

vite-frontend/src/api/error-message.ts

@@ -0,0 +1,27 @@
+import axios from "axios";
+
+interface ErrorPayload {
+  msg?: string;
+  message?: string;
+}
+
+export const isUnauthorizedError = (error: unknown): boolean => {
+  return axios.isAxiosError(error) && error.response?.status === 401;
+};
+
+export const extractApiErrorMessage = (
+  error: unknown,
+  fallback = "网络请求失败",
+): string => {
+  if (axios.isAxiosError(error)) {
+    const payload = error.response?.data as ErrorPayload | undefined;
+
+    return payload?.msg || payload?.message || error.message || fallback;
+  }
+
+  if (error instanceof Error && error.message) {
+    return error.message;
+  }
+
+  return fallback;
+};

vite-frontend/src/api/index.ts

@@ -1,7 +1,38 @@
+import type {
+  BatchOperationResult,
+  ForwardDiagnosisApiData,
+  ForwardApiItem,
+  GroupPermissionApiItem,
+  NodeReleaseApiItem,
+  NodeApiItem,
+  SpeedLimitApiItem,
+  TunnelDiagnosisApiData,
+  TunnelGroupApiItem,
+  UserApiItem,
+  UserGroupApiItem,
+  UserListQuery,
+  UserPackageInfoApiData,
+  UserTunnelPermissionApiItem,
+  TunnelApiItem,
+  UserTunnelApiItem,
+  UserMutationPayload,
+  NodeMutationPayload,
+  TunnelMutationPayload,
+  UserTunnelAssignPayload,
+  UserTunnelListQuery,
+  UserTunnelRemovePayload,
+  ForwardMutationPayload,
+  SpeedLimitMutationPayload,
+  UpdatePasswordPayload,
+  BackupImportPayload,
+} from "./types";
+
 import axios from "axios";
 
 import Network from "./network";
 
+export type ReleaseChannel = "stable" | "dev";
+
 // 登陆相关接口
 export interface LoginData {
   username: string;
@@ -20,20 +51,27 @@ export const login = (data: LoginData) =>
   Network.post<LoginResponse>("/user/login", data);
 
 // 用户CRUD操作 - 全部使用POST请求
-export const createUser = (data: any) => Network.post("/user/create", data);
-export const getAllUsers = (pageData: any = {}) =>
-  Network.post("/user/list", pageData);
-export const updateUser = (data: any) => Network.post("/user/update", data);
+export const createUser = (data: UserMutationPayload) =>
+  Network.post("/user/create", data);
+export const getAllUsers = (pageData: UserListQuery = {}) =>
+  Network.post<UserApiItem[]>("/user/list", pageData);
+export const updateUser = (data: UserMutationPayload) =>
+  Network.post("/user/update", data);
 export const deleteUser = (id: number) => Network.post("/user/delete", { id });
-export const getUserPackageInfo = () => Network.post("/user/package");
+export const getUserPackageInfo = () =>
+  Network.post<UserPackageInfoApiData>("/user/package");
 
 // 节点CRUD操作 - 全部使用POST请求
-export const createNode = (data: any) => Network.post("/node/create", data);
-export const getNodeList = () => Network.post("/node/list");
-export const updateNode = (data: any) => Network.post("/node/update", data);
+export const createNode = (data: NodeMutationPayload) =>
+  Network.post("/node/create", data);
+export const getNodeList = () => Network.post<NodeApiItem[]>("/node/list");
+export const updateNode = (data: NodeMutationPayload) =>
+  Network.post("/node/update", data);
 export const deleteNode = (id: number) => Network.post("/node/delete", { id });
-export const getNodeInstallCommand = (id: number) =>
-  Network.post("/node/install", { id });
+export const getNodeInstallCommand = (
+  id: number,
+  channel: ReleaseChannel = "stable",
+) => Network.post<string>("/node/install", { id, channel });
 export const updateNodeOrder = (data: {
   nodes: Array<{ id: number; inx: number }>;
 }) => Network.post("/node/update-order", data);
@@ -43,56 +81,70 @@ export const checkNodeStatus = (nodeId?: number) => {
   return Network.post("/node/check-status", params);
 };
 
-export const upgradeNode = (id: number, version?: string) =>
+export const upgradeNode = (
+  id: number,
+  version?: string,
+  channel: ReleaseChannel = "stable",
+) =>
   Network.post(
     "/node/upgrade",
-    { id, version: version || "" },
+    { id, version: version || "", channel },
     { timeout: 5 * 60 * 1000 },
   );
-export const batchUpgradeNodes = (ids: number[], version?: string) =>
+export const batchUpgradeNodes = (
+  ids: number[],
+  version?: string,
+  channel: ReleaseChannel = "stable",
+) =>
   Network.post(
     "/node/batch-upgrade",
-    { ids, version: version || "" },
+    { ids, version: version || "", channel },
     { timeout: 15 * 60 * 1000 },
   );
-export const getNodeReleases = () => Network.post("/node/releases");
+export const getNodeReleases = (channel: ReleaseChannel = "stable") =>
+  Network.post<NodeReleaseApiItem[]>("/node/releases", { channel });
 export const rollbackNode = (id: number) =>
   Network.post("/node/rollback", { id });
 
 // 隧道CRUD操作 - 全部使用POST请求
-export const createTunnel = (data: any) => Network.post("/tunnel/create", data);
-export const getTunnelList = () => Network.post("/tunnel/list");
+export const createTunnel = (data: TunnelMutationPayload) =>
+  Network.post("/tunnel/create", data);
+export const getTunnelList = () =>
+  Network.post<TunnelApiItem[]>("/tunnel/list");
 export const getTunnelById = (id: number) =>
-  Network.post("/tunnel/get", { id });
-export const updateTunnel = (data: any) => Network.post("/tunnel/update", data);
+  Network.post<TunnelApiItem>("/tunnel/get", { id });
+export const updateTunnel = (data: TunnelMutationPayload) =>
+  Network.post("/tunnel/update", data);
 export const deleteTunnel = (id: number) =>
   Network.post("/tunnel/delete", { id });
 export const diagnoseTunnel = (tunnelId: number) =>
-  Network.post("/tunnel/diagnose", { tunnelId });
+  Network.post<TunnelDiagnosisApiData>("/tunnel/diagnose", { tunnelId });
 export const updateTunnelOrder = (data: {
   tunnels: Array<{ id: number; inx: number }>;
 }) => Network.post("/tunnel/update-order", data);
 
 // 用户隧道权限管理操作 - 全部使用POST请求
-export const assignUserTunnel = (data: any) =>
+export const assignUserTunnel = (data: UserTunnelAssignPayload) =>
   Network.post("/tunnel/user/assign", data);
 export const batchAssignUserTunnel = (data: {
   userId: number;
   tunnels: Array<{ tunnelId: number; speedId?: number | null }>;
 }) => Network.post("/tunnel/user/batch-assign", data);
-export const getUserTunnelList = (queryData: any = {}) =>
-  Network.post("/tunnel/user/list", queryData);
-export const removeUserTunnel = (params: any) =>
+export const getUserTunnelList = (queryData: UserTunnelListQuery = {}) =>
+  Network.post<UserTunnelPermissionApiItem[]>("/tunnel/user/list", queryData);
+export const removeUserTunnel = (params: UserTunnelRemovePayload) =>
   Network.post("/tunnel/user/remove", params);
-export const updateUserTunnel = (data: any) =>
+export const updateUserTunnel = (data: UserTunnelAssignPayload) =>
   Network.post("/tunnel/user/update", data);
-export const userTunnel = () => Network.post("/tunnel/user/tunnel");
+export const userTunnel = () =>
+  Network.post<UserTunnelApiItem[]>("/tunnel/user/tunnel");
 
 // 转发CRUD操作 - 全部使用POST请求
-export const createForward = (data: any) =>
+export const createForward = (data: ForwardMutationPayload) =>
   Network.post("/forward/create", data);
-export const getForwardList = () => Network.post("/forward/list");
-export const updateForward = (data: any) =>
+export const getForwardList = () =>
+  Network.post<ForwardApiItem[]>("/forward/list");
+export const updateForward = (data: ForwardMutationPayload) =>
   Network.post("/forward/update", data);
 export const deleteForward = (id: number) =>
   Network.post("/forward/delete", { id });
@@ -107,7 +159,7 @@ export const resumeForwardService = (forwardId: number) =>
 
 // 转发诊断操作
 export const diagnoseForward = (forwardId: number) =>
-  Network.post("/forward/diagnose", { forwardId });
+  Network.post<ForwardDiagnosisApiData>("/forward/diagnose", { forwardId });
 
 // 转发排序操作
 export const updateForwardOrder = (data: {
@@ -115,34 +167,41 @@ export const updateForwardOrder = (data: {
 }) => Network.post("/forward/update-order", data);
 
 // 限速规则CRUD操作 - 全部使用POST请求
-export const createSpeedLimit = (data: any) =>
+export const createSpeedLimit = (data: SpeedLimitMutationPayload) =>
   Network.post("/speed-limit/create", data);
-export const getSpeedLimitList = () => Network.post("/speed-limit/list");
-export const updateSpeedLimit = (data: any) =>
+export const getSpeedLimitList = () =>
+  Network.post<SpeedLimitApiItem[]>("/speed-limit/list");
+export const updateSpeedLimit = (data: SpeedLimitMutationPayload) =>
   Network.post("/speed-limit/update", data);
 export const deleteSpeedLimit = (id: number) =>
   Network.post("/speed-limit/delete", { id });
 
 // 修改密码接口
-export const updatePassword = (data: any) =>
+export const updatePassword = (data: UpdatePasswordPayload) =>
   Network.post("/user/updatePassword", data);
 
 // 重置流量接口
 export const resetUserFlow = (data: { id: number; type: number }) =>
   Network.post("/user/reset", data);
 
+export const getUserGroups = (id: number) =>
+  Network.post<number[]>("/user/groups", { id });
+
 // 网站配置相关接口
-export const getConfigs = () => Network.post("/config/list");
+export const getConfigs = () =>
+  Network.post<Record<string, string>>("/config/list");
 export const getConfigByName = (name: string) =>
-  Network.post("/config/get", { name });
+  Network.post<{ name: string; value: string }>("/config/get", { name });
 export const updateConfigs = (configMap: Record<string, string>) =>
   Network.post("/config/update", configMap);
 export const updateConfig = (name: string, value: string) =>
   Network.post("/config/update-single", { name, value });
 
 export const exportBackupData = () => Network.post("/backup/export");
-export const importBackupData = (data: any) => Network.post("/backup/import", data);
-export const restoreBackupData = (data: any) => Network.post("/backup/restore", data);
+export const importBackupData = (data: BackupImportPayload) =>
+  Network.post("/backup/import", data);
+export const restoreBackupData = (data: BackupImportPayload) =>
+  Network.post("/backup/restore", data);
 
 // 验证码相关接口
 export const checkCaptcha = () => Network.post("/captcha/check");
@@ -152,26 +211,27 @@ export const verifyCaptcha = (data: { captchaId: string; trackData: string }) =>
 
 // 批量操作接口
 export const batchDeleteForwards = (ids: number[]) =>
-  Network.post("/forward/batch-delete", { ids });
+  Network.post<BatchOperationResult>("/forward/batch-delete", { ids });
 export const batchPauseForwards = (ids: number[]) =>
-  Network.post("/forward/batch-pause", { ids });
+  Network.post<BatchOperationResult>("/forward/batch-pause", { ids });
 export const batchResumeForwards = (ids: number[]) =>
-  Network.post("/forward/batch-resume", { ids });
+  Network.post<BatchOperationResult>("/forward/batch-resume", { ids });
 export const batchDeleteTunnels = (ids: number[]) =>
-  Network.post("/tunnel/batch-delete", { ids });
+  Network.post<BatchOperationResult>("/tunnel/batch-delete", { ids });
 export const batchDeleteNodes = (ids: number[]) =>
-  Network.post("/node/batch-delete", { ids });
+  Network.post<BatchOperationResult>("/node/batch-delete", { ids });
 export const batchRedeployForwards = (ids: number[]) =>
-  Network.post("/forward/batch-redeploy", { ids });
+  Network.post<BatchOperationResult>("/forward/batch-redeploy", { ids });
 export const batchRedeployTunnels = (ids: number[]) =>
-  Network.post("/tunnel/batch-redeploy", { ids });
+  Network.post<BatchOperationResult>("/tunnel/batch-redeploy", { ids });
 export const batchChangeTunnel = (data: {
   forwardIds: number[];
   targetTunnelId: number;
-}) => Network.post("/forward/batch-change-tunnel", data);
+}) => Network.post<BatchOperationResult>("/forward/batch-change-tunnel", data);
 
 // 分组与权限分配接口
-export const getTunnelGroupList = () => Network.post("/group/tunnel/list");
+export const getTunnelGroupList = () =>
+  Network.post<TunnelGroupApiItem[]>("/group/tunnel/list");
 export const createTunnelGroup = (data: { name: string; status?: number }) =>
   Network.post("/group/tunnel/create", data);
 export const updateTunnelGroup = (data: {
@@ -186,7 +246,8 @@ export const assignTunnelsToGroup = (data: {
   tunnelIds: number[];
 }) => Network.post("/group/tunnel/assign", data);
 
-export const getUserGroupList = () => Network.post("/group/user/list");
+export const getUserGroupList = () =>
+  Network.post<UserGroupApiItem[]>("/group/user/list");
 export const createUserGroup = (data: { name: string; status?: number }) =>
   Network.post("/group/user/create", data);
 export const updateUserGroup = (data: {
@@ -202,7 +263,7 @@ export const assignUsersToGroup = (data: {
 }) => Network.post("/group/user/assign", data);
 
 export const getGroupPermissionList = () =>
-  Network.post("/group/permission/list");
+  Network.post<GroupPermissionApiItem[]>("/group/permission/list");
 export const assignGroupPermission = (data: {
   userGroupId: number;
   tunnelGroupId: number;
@@ -211,7 +272,8 @@ export const removeGroupPermission = (id: number) =>
   Network.post("/group/permission/remove", { id });
 
 // 面板共享 (Federation) 接口
-export const getPeerShareList = () => Network.post("/federation/share/list");
+export const getPeerShareList = () =>
+  Network.post<Array<Record<string, unknown>>>("/federation/share/list");
 export const createPeerShare = (data: {
   name: string;
   nodeId: number;
@@ -237,7 +299,9 @@ export const deletePeerShare = (id: number) =>
 export const resetPeerShareFlow = (id: number) =>
   Network.post("/federation/share/reset-flow", { id });
 export const getPeerRemoteUsageList = () =>
-  Network.post("/federation/share/remote-usage/list");
+  Network.post<Array<Record<string, unknown>>>(
+    "/federation/share/remote-usage/list",
+  );
 export const importRemoteNode = (data: { remoteUrl: string; token: string }) =>
   Network.post("/federation/node/import", data);
 
@@ -283,7 +347,7 @@ export const exportBackup = async (types: string[] = []) => {
   window.URL.revokeObjectURL(url);
 };
 
-export const importBackup = (data: { types: string[]; [key: string]: any }) =>
+export const importBackup = (data: BackupImportPayload) =>
   Network.post("/backup/import", data);
 
 export interface AnnouncementData {
@@ -291,5 +355,7 @@ export interface AnnouncementData {
   enabled: number;
 }
 
-export const getAnnouncement = () => Network.get<AnnouncementData>("/announcement/get");
-export const updateAnnouncement = (data: AnnouncementData) => Network.post("/announcement/update", data);
+export const getAnnouncement = () =>
+  Network.get<AnnouncementData>("/announcement/get");
+export const updateAnnouncement = (data: AnnouncementData) =>
+  Network.post("/announcement/update", data);

vite-frontend/src/api/network.ts

@@ -1,6 +1,11 @@
 import axios, { AxiosResponse } from "axios";
 
+import {
+  extractApiErrorMessage,
+  isUnauthorizedError,
+} from "@/api/error-message";
 import { getPanelAddresses, isWebViewFunc } from "@/utils/panel";
+import { clearSession, getToken } from "@/utils/session";
 
 interface PanelAddress {
   name: string;
@@ -37,7 +42,7 @@ export const reinitializeBaseURL = () => {
 
 reinitializeBaseURL();
 
-interface ApiResponse<T = any> {
+interface ApiResponse<T = unknown> {
   code: number;
   msg: string;
   data: T;
@@ -49,10 +54,7 @@ interface RequestOptions {
 
 // 处理token失效的逻辑
 function handleTokenExpired() {
-  // 清除localStorage中的token
-  window.localStorage.removeItem("token");
-  window.localStorage.removeItem("role_id");
-  window.localStorage.removeItem("name");
+  clearSession();
 
   // 跳转到登录页面
   if (window.location.pathname !== "/") {
@@ -61,7 +63,7 @@ function handleTokenExpired() {
 }
 
 // 检查响应是否为token失效
-function isTokenExpired(response: ApiResponse) {
+function isTokenExpired(response: ApiResponse<unknown>) {
   return (
     response &&
     response.code === 401 &&
@@ -72,9 +74,9 @@ function isTokenExpired(response: ApiResponse) {
 }
 
 const Network = {
-  get: function <T = any>(
+  get: function <T = unknown>(
     path: string = "",
-    data: any = {},
+    data: unknown = {},
     options: RequestOptions = {},
   ): Promise<ApiResponse<T>> {
     return new Promise(function (resolve) {
@@ -90,38 +92,45 @@ const Network = {
           params: data,
           timeout: options.timeout ?? 30000,
           headers: {
-            Authorization: window.localStorage.getItem("token"),
+            Authorization: getToken(),
           },
         })
         .then(function (response: AxiosResponse<ApiResponse<T>>) {
           // 检查是否token失效
           if (isTokenExpired(response.data)) {
             handleTokenExpired();
-
-            return;
           }
+
           resolve(response.data);
         })
-        .catch(function (error: any) {
+        .catch(function (error: unknown) {
+          const errorMessage = extractApiErrorMessage(error);
+
           // 检查是否是401错误（token失效）
-          if (error.response && error.response.status === 401) {
+          if (isUnauthorizedError(error)) {
             handleTokenExpired();
 
+            resolve({
+              code: 401,
+              msg: "未登录或token已过期",
+              data: null as T,
+            });
+
             return;
           }
 
           resolve({
             code: -1,
-            msg: error.message || "网络请求失败",
+            msg: errorMessage,
             data: null as T,
           });
         });
     });
   },
 
-  post: function <T = any>(
+  post: function <T = unknown>(
     path: string = "",
-    data: any = {},
+    data: unknown = {},
     options: RequestOptions = {},
   ): Promise<ApiResponse<T>> {
     return new Promise(function (resolve) {
@@ -136,7 +145,7 @@ const Network = {
         .post(path, data, {
           timeout: options.timeout ?? 30000,
           headers: {
-            Authorization: window.localStorage.getItem("token"),
+            Authorization: getToken(),
             "Content-Type": "application/json",
           },
         })
@@ -144,22 +153,29 @@ const Network = {
           // 检查是否token失效
           if (isTokenExpired(response.data)) {
             handleTokenExpired();
-
-            return;
           }
+
           resolve(response.data);
         })
-        .catch(function (error: any) {
+        .catch(function (error: unknown) {
+          const errorMessage = extractApiErrorMessage(error);
+
           // 检查是否是401错误（token失效）
-          if (error.response && error.response.status === 401) {
+          if (isUnauthorizedError(error)) {
             handleTokenExpired();
 
+            resolve({
+              code: 401,
+              msg: "未登录或token已过期",
+              data: null as T,
+            });
+
             return;
           }
 
           resolve({
             code: -1,
-            msg: error.message || "网络请求失败",
+            msg: errorMessage,
             data: null as T,
           });
         });

vite-frontend/src/api/types.ts

@@ -0,0 +1,309 @@
+export interface NodeApiItem {
+  id: number;
+  name: string;
+  status: number;
+  inx?: number;
+  syncError?: string;
+  [key: string]: unknown;
+}
+
+export interface UserApiItem {
+  id: number;
+  user: string;
+  name?: string;
+  status: number;
+  flow: number;
+  num: number;
+  expTime?: number;
+  flowResetTime?: number;
+  inFlow?: number;
+  outFlow?: number;
+  [key: string]: unknown;
+}
+
+export interface UserListQuery {
+  current?: number;
+  size?: number;
+  keyword?: string;
+  [key: string]: unknown;
+}
+
+export interface TunnelApiItem {
+  id: number;
+  name: string;
+  type: number;
+  status: number;
+  entryNodeId: number;
+  exitNodeId: number;
+  inx?: number;
+  [key: string]: unknown;
+}
+
+export interface ForwardApiItem {
+  id: number;
+  name: string;
+  status: number;
+  tunnelName?: string;
+  inIp?: string;
+  inPort?: number;
+  remoteAddr?: string;
+  inFlow?: number;
+  outFlow?: number;
+  userId?: number;
+  tunnelId?: number;
+  speedId?: number | null;
+  inx?: number;
+  [key: string]: unknown;
+}
+
+export interface UserTunnelApiItem {
+  id: number;
+  name: string;
+  tunnelId?: number;
+  tunnelName?: string;
+  inNodePortSta?: number;
+  inNodePortEnd?: number;
+  speedId?: number | null;
+  [key: string]: unknown;
+}
+
+export interface UserTunnelPermissionApiItem {
+  id: number;
+  userId: number;
+  tunnelId: number;
+  tunnelName: string;
+  status: number;
+  flow: number;
+  num: number;
+  expTime: number;
+  flowResetTime: number;
+  speedId?: number | null;
+  speedLimitName?: string;
+  inFlow: number;
+  outFlow: number;
+  tunnelFlow?: number;
+  [key: string]: unknown;
+}
+
+export interface StatisticsFlowApiItem {
+  id: number;
+  userId: number;
+  flow: number;
+  totalFlow: number;
+  time: string;
+  [key: string]: unknown;
+}
+
+export interface SpeedLimitApiItem {
+  id: number;
+  name: string;
+  tunnelId?: number | null;
+  speed: number;
+  status: number;
+  tunnelName?: string;
+  createdTime: string;
+  updatedTime: string;
+  uploadSpeed?: number;
+  downloadSpeed?: number;
+  [key: string]: unknown;
+}
+
+export interface TunnelGroupApiItem {
+  id: number;
+  name: string;
+  status: number;
+  tunnelIds: number[];
+  tunnelNames: string[];
+  createdTime: number;
+  [key: string]: unknown;
+}
+
+export interface UserGroupApiItem {
+  id: number;
+  name: string;
+  status: number;
+  userIds: number[];
+  userNames: string[];
+  createdTime: number;
+  [key: string]: unknown;
+}
+
+export interface GroupPermissionApiItem {
+  id: number;
+  userGroupId: number;
+  userGroupName: string;
+  tunnelGroupId: number;
+  tunnelGroupName: string;
+  createdTime: number;
+  [key: string]: unknown;
+}
+
+export interface TunnelDiagnosisApiItem {
+  success: boolean;
+  description: string;
+  nodeName: string;
+  nodeId: string;
+  targetIp: string;
+  targetPort?: number;
+  message?: string;
+  averageTime?: number;
+  packetLoss?: number;
+  fromChainType?: number;
+  fromInx?: number;
+  toChainType?: number;
+  toInx?: number;
+  [key: string]: unknown;
+}
+
+export interface TunnelDiagnosisApiData {
+  tunnelName: string;
+  tunnelType: string;
+  timestamp: number;
+  results: TunnelDiagnosisApiItem[];
+}
+
+export interface ForwardDiagnosisApiData {
+  forwardName: string;
+  timestamp: number;
+  results: TunnelDiagnosisApiItem[];
+}
+
+export interface NodeReleaseApiItem {
+  version: string;
+  name: string;
+  publishedAt: string;
+  prerelease: boolean;
+  channel: "stable" | "dev";
+}
+
+export interface UserPackageInfoApiData {
+  userInfo: {
+    flow: number;
+    inFlow: number;
+    outFlow: number;
+    num: number;
+    expTime?: string;
+    flowResetTime?: number;
+    [key: string]: unknown;
+  };
+  tunnelPermissions: UserTunnelPermissionApiItem[];
+  forwards: ForwardApiItem[];
+  statisticsFlows: StatisticsFlowApiItem[];
+  [key: string]: unknown;
+}
+
+export interface BatchOperationResult {
+  successCount: number;
+  failCount: number;
+  [key: string]: unknown;
+}
+
+export interface UserMutationPayload {
+  id?: number;
+  user?: string;
+  name?: string;
+  password?: string;
+  status?: number;
+  flow?: number;
+  num?: number;
+  expTime?: number | string;
+  flowResetTime?: number;
+  tunnelFlow?: number;
+}
+
+export interface NodeMutationPayload {
+  id?: number | null;
+  name?: string;
+  status?: number;
+  inx?: number;
+  serverIp?: string;
+  serverIpV4?: string;
+  serverIpV6?: string;
+  port?: string;
+  tcpListenAddr?: string;
+  udpListenAddr?: string;
+  interfaceName?: string;
+  http?: number;
+  tls?: number;
+  socks?: number;
+}
+
+export interface TunnelChainNodePayload {
+  nodeId: number;
+  protocol?: string;
+  strategy?: string;
+  chainType?: number;
+  inx?: number;
+}
+
+export interface TunnelMutationPayload {
+  id?: number;
+  name?: string;
+  type?: number;
+  status?: number;
+  flow?: number;
+  trafficRatio?: number;
+  inIp?: string;
+  ipPreference?: string;
+  inNodeId?: TunnelChainNodePayload[];
+  outNodeId?: TunnelChainNodePayload[];
+  chainNodes?: TunnelChainNodePayload[][];
+}
+
+export interface UserTunnelAssignPayload {
+  userId?: number;
+  id?: number;
+  tunnelId?: number;
+  flow?: number;
+  num?: number;
+  expTime?: number;
+  flowResetTime?: number;
+  status?: number;
+  speedId?: number | null;
+  tunnels?: Array<{ tunnelId: number; speedId?: number | null }>;
+}
+
+export interface UserTunnelListQuery {
+  userId?: number;
+  tunnelId?: number;
+  current?: number;
+  size?: number;
+}
+
+export interface UserTunnelRemovePayload {
+  id?: number;
+  userId?: number;
+  tunnelId?: number;
+}
+
+export interface ForwardMutationPayload {
+  id?: number;
+  name?: string;
+  status?: number;
+  tunnelId?: number | null;
+  inIp?: string;
+  inPort?: number | null;
+  remoteAddr?: string;
+  strategy?: string;
+  speedId?: number | null;
+}
+
+export interface SpeedLimitMutationPayload {
+  id?: number;
+  name?: string;
+  speed?: number;
+  status?: number;
+  tunnelId?: number | null;
+  tunnelName?: string;
+}
+
+export interface UpdatePasswordPayload {
+  currentPassword: string;
+  newPassword: string;
+  newUsername?: string;
+}
+
+export interface BackupImportPayload {
+  types: string[];
+  [key: string]: unknown;
+}

vite-frontend/src/components/animated-page.tsx

@@ -0,0 +1,122 @@
+import { motion } from "framer-motion";
+import React from "react";
+
+/**
+ * Wraps page content with a smooth fade-in + slide-up entrance animation.
+ * Use this as the outermost wrapper inside each page component.
+ */
+export const AnimatedPage = ({
+  children,
+  className,
+}: {
+  children: React.ReactNode;
+  className?: string;
+}) => (
+  <motion.div
+    animate={{ opacity: 1, y: 0 }}
+    className={className}
+    exit={{ opacity: 0, y: -8 }}
+    initial={{ opacity: 0, y: 16 }}
+    transition={{ duration: 0.28, ease: [0.25, 0.46, 0.45, 0.94] }}
+  >
+    {children}
+  </motion.div>
+);
+
+/**
+ * Stagger container — apply to the parent of a list/grid of animated items.
+ * Children should use `staggerItem` as their `variants` prop.
+ */
+export const staggerContainer = {
+  hidden: { opacity: 0 },
+  show: {
+    opacity: 1,
+    transition: {
+      staggerChildren: 0.05,
+      delayChildren: 0.05,
+    },
+  },
+};
+
+/**
+ * Individual stagger item variant — fade-in + slide-up.
+ */
+export const staggerItem = {
+  hidden: { opacity: 0, y: 12 },
+  show: {
+    opacity: 1,
+    y: 0,
+    transition: { duration: 0.25, ease: [0.25, 0.46, 0.45, 0.94] },
+  },
+};
+
+/**
+ * Convenience wrapper for a stagger list.
+ * Renders a `motion.div` (or `motion.ul/motion.tbody`) with stagger behaviour.
+ */
+export const StaggerList = ({
+  children,
+  className,
+  as = "div",
+}: {
+  children: React.ReactNode;
+  className?: string;
+  as?: "div" | "ul" | "tbody";
+}) => {
+  const Component = motion[as] as React.ElementType;
+
+  return (
+    <Component
+      animate="show"
+      className={className}
+      initial="hidden"
+      variants={staggerContainer}
+    >
+      {children}
+    </Component>
+  );
+};
+
+/**
+ * Individual animated item for use inside StaggerList.
+ */
+export const StaggerItem = ({
+  children,
+  className,
+  as = "div",
+}: {
+  children: React.ReactNode;
+  className?: string;
+  as?: "div" | "li" | "tr";
+}) => {
+  const Component = motion[as] as React.ElementType;
+
+  return (
+    <Component className={className} variants={staggerItem}>
+      {children}
+    </Component>
+  );
+};
+
+/**
+ * Simple fade-in animation for standalone elements (chips, badges, counters, etc.)
+ * Uses opacity + translateY to avoid font blurriness caused by scale transforms.
+ */
+export const FadeIn = ({
+  children,
+  delay = 0,
+  className,
+}: {
+  children: React.ReactNode;
+  delay?: number;
+  className?: string;
+}) => (
+  <motion.div
+    animate={{ opacity: 1, y: 0 }}
+    className={className}
+    initial={{ opacity: 0, y: 8 }}
+    transition={{ duration: 0.2, delay, ease: "easeOut" }}
+  >
+    {children}
+  </motion.div>
+);

vite-frontend/src/components/brand-logo.tsx

@@ -0,0 +1,79 @@
+import { useEffect, useState } from "react";
+
+import { siteConfig, getCachedConfigs } from "@/config/site";
+import { Logo } from "@/components/icons";
+
+type BrandLogoProps = {
+  size?: number;
+  className?: string;
+  alt?: string;
+};
+
+export const BrandLogo = ({
+  size = 24,
+  className,
+  alt = "brand logo",
+}: BrandLogoProps) => {
+  const [logoUrl, setLogoUrl] = useState<string>(siteConfig.app_logo || "");
+  const [imageFailed, setImageFailed] = useState(false);
+
+  useEffect(() => {
+    let mounted = true;
+
+    const syncLogo = async () => {
+      try {
+        const configMap = await getCachedConfigs();
+        const nextLogo = (
+          configMap.app_logo ||
+          siteConfig.app_logo ||
+          ""
+        ).trim();
+
+        if (!mounted) {
+          return;
+        }
+
+        siteConfig.app_logo = nextLogo;
+        setLogoUrl(nextLogo);
+        setImageFailed(false);
+      } catch {
+        if (!mounted) {
+          return;
+        }
+        setLogoUrl((siteConfig.app_logo || "").trim());
+      }
+    };
+
+    void syncLogo();
+
+    const handleConfigUpdate = () => {
+      const nextLogo = (siteConfig.app_logo || "").trim();
+
+      setLogoUrl(nextLogo);
+      setImageFailed(false);
+      void syncLogo();
+    };
+
+    window.addEventListener("configUpdated", handleConfigUpdate);
+
+    return () => {
+      mounted = false;
+      window.removeEventListener("configUpdated", handleConfigUpdate);
+    };
+  }, []);
+
+  if (!logoUrl || imageFailed) {
+    return <Logo className={className} size={size} />;
+  }
+
+  return (
+    <img
+      alt={alt}
+      className={className}
+      height={size}
+      src={logoUrl}
+      width={size}
+      onError={() => setImageFailed(true)}
+    />
+  );
+};

vite-frontend/src/components/navbar.tsx

@@ -1,26 +1,21 @@
-import { useState, useEffect } from "react";
-import { Link } from "@heroui/link";
+import { useEffect, useState } from "react";
+import { useNavigate } from "react-router-dom";
+
+import { Link } from "@/shadcn-bridge/heroui/link";
 import {
   Navbar as HeroUINavbar,
   NavbarBrand,
   NavbarContent,
-} from "@heroui/navbar";
-import { useNavigate } from "react-router-dom";
-
-import { isWebViewFunc } from "@/utils/panel";
-import { Logo } from "@/components/icons";
+} from "@/shadcn-bridge/heroui/navbar";
+import { BrandLogo } from "@/components/brand-logo";
 import { siteConfig, getCachedConfig } from "@/config/site";
+import { useWebViewMode } from "@/hooks/useWebViewMode";
 
 export const Navbar = () => {
   const navigate = useNavigate();
   // 初始状态使用siteConfig中已经从缓存读取的值，避免闪烁
   const [appName, setAppName] = useState(siteConfig.name);
-  const [isWebView, setIsWebView] = useState(false);
-
-  // 检测是否在WebView中运行
-  useEffect(() => {
-    setIsWebView(isWebViewFunc());
-  }, []);
+  const isWebView = useWebViewMode();
 
   useEffect(() => {
     // 异步检查是否有更新的配置
@@ -74,7 +69,7 @@ export const Navbar = () => {
               color="foreground"
               href="/"
             >
-              <Logo size={24} />
+              <BrandLogo size={24} />
               <p className="font-bold text-inherit truncate">{appName}</p>
             </Link>
           </NavbarBrand>

vite-frontend/src/components/page-state.tsx

@@ -0,0 +1,42 @@
+import { Spinner } from "@/shadcn-bridge/heroui/spinner";
+
+interface BaseStateProps {
+  message: string;
+  className?: string;
+}
+
+export const PageLoadingState = ({
+  message,
+  className = "h-64",
+}: BaseStateProps) => {
+  return (
+    <div className={`flex items-center justify-center ${className}`}>
+      <div className="flex items-center gap-3">
+        <Spinner size="sm" />
+        <span className="text-default-600">{message}</span>
+      </div>
+    </div>
+  );
+};
+
+export const PageEmptyState = ({
+  message,
+  className = "h-48",
+}: BaseStateProps) => {
+  return (
+    <div className={`flex items-center justify-center ${className}`}>
+      <span className="text-default-500">{message}</span>
+    </div>
+  );
+};
+
+export const PageErrorState = ({
+  message,
+  className = "h-48",
+}: BaseStateProps) => {
+  return (
+    <div className={`flex items-center justify-center ${className}`}>
+      <span className="text-danger">{message}</span>
+    </div>
+  );
+};

vite-frontend/src/components/search-bar.tsx

@@ -0,0 +1,100 @@
+import { motion, AnimatePresence } from "framer-motion";
+
+import { Button } from "@/shadcn-bridge/heroui/button";
+import { Input } from "@/shadcn-bridge/heroui/input";
+import { SearchIcon } from "@/components/icons";
+
+interface SearchBarProps {
+  isVisible: boolean;
+  value: string;
+  placeholder?: string;
+  onOpen: () => void;
+  onClose: () => void;
+  onChange: (value: string) => void;
+}
+
+export function SearchBar({
+  isVisible,
+  value,
+  placeholder = "搜索",
+  onOpen,
+  onClose,
+  onChange,
+}: SearchBarProps) {
+  return (
+    // Fixed h-8 so the container never changes height — eliminates the vertical jitter
+    <div className="flex items-center gap-2 h-8 overflow-hidden">
+      <AnimatePresence initial={false} mode="wait">
+        {!isVisible ? (
+          <motion.div
+            key="search-btn"
+            animate={{ opacity: 1, scale: 1 }}
+            exit={{ opacity: 0 }}
+            initial={{ opacity: 0 }}
+            transition={{ duration: 0.12 }}
+          >
+            <Button
+              isIconOnly
+              aria-label="搜索"
+              className="text-default-600"
+              color="default"
+              size="sm"
+              variant="flat"
+              onPress={onOpen}
+            >
+              <SearchIcon className="w-4 h-4" />
+            </Button>
+          </motion.div>
+        ) : (
+          <motion.div
+            key="search-input"
+            animate={{ opacity: 1, x: 0 }}
+            className="flex w-full items-center gap-2"
+            exit={{ opacity: 0, x: -8 }}
+            initial={{ opacity: 0, x: -16 }}
+            transition={{ duration: 0.18, ease: [0.25, 0.46, 0.45, 0.94] }}
+          >
+            <Input
+              classNames={{
+                base: "bg-default-100",
+                input:
+                  "bg-transparent text-sm focus-visible:ring-0 focus-visible:ring-offset-0 focus-visible:outline-none",
+                inputWrapper: "bg-default-100 border-0 shadow-none h-8 min-h-8",
+              }}
+              placeholder={placeholder}
+              value={value}
+              onChange={(e) => onChange(e.target.value)}
+            />
+            <Button
+              isIconOnly
+              aria-label="关闭搜索"
+              className="text-default-600 shrink-0"
+              color="default"
+              size="sm"
+              variant="light"
+              onPress={() => {
+                onClose();
+                onChange("");
+              }}
+            >
+              <svg
+                aria-hidden="true"
+                className="w-4 h-4"
+                fill="none"
+                stroke="currentColor"
+                viewBox="0 0 24 24"
+              >
+                <path
+                  d="M6 18L18 6M6 6l12 12"
+                  strokeLinecap="round"
+                  strokeLinejoin="round"
+                  strokeWidth={2}
+                />
+              </svg>
+            </Button>
+          </motion.div>
+        )}
+      </AnimatePresence>
+    </div>
+  );
+}

vite-frontend/src/components/theme-provider.tsx

@@ -1,5 +1,6 @@
 import React, { useEffect } from "react";
-import { useTheme } from "@heroui/use-theme";
+
+import { useTheme } from "@/shadcn-bridge/heroui/use-theme";
 
 interface ThemeProviderProps {
   children: React.ReactNode;

vite-frontend/src/components/ui/accordion.tsx

@@ -0,0 +1,64 @@
+import * as React from "react";
+import * as AccordionPrimitive from "@radix-ui/react-accordion";
+import { ChevronDownIcon } from "lucide-react";
+
+import { cn } from "@/lib/utils";
+
+function Accordion({
+  ...props
+}: React.ComponentProps<typeof AccordionPrimitive.Root>) {
+  return <AccordionPrimitive.Root data-slot="accordion" {...props} />;
+}
+
+function AccordionItem({
+  className,
+  ...props
+}: React.ComponentProps<typeof AccordionPrimitive.Item>) {
+  return (
+    <AccordionPrimitive.Item
+      className={cn("border-b", className)}
+      data-slot="accordion-item"
+      {...props}
+    />
+  );
+}
+
+function AccordionTrigger({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<typeof AccordionPrimitive.Trigger>) {
+  return (
+    <AccordionPrimitive.Header className="flex" data-slot="accordion-header">
+      <AccordionPrimitive.Trigger
+        className={cn(
+          "flex flex-1 items-center justify-between gap-3 px-3 py-4 text-sm font-medium transition-all hover:underline [&[data-state=open]>svg]:rotate-180",
+          className,
+        )}
+        data-slot="accordion-trigger"
+        {...props}
+      >
+        {children}
+        <ChevronDownIcon className="h-4 w-4 shrink-0 text-default-500 transition-transform duration-200" />
+      </AccordionPrimitive.Trigger>
+    </AccordionPrimitive.Header>
+  );
+}
+
+function AccordionContent({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<typeof AccordionPrimitive.Content>) {
+  return (
+    <AccordionPrimitive.Content
+      className="overflow-hidden text-sm data-[state=closed]:animate-accordion-up data-[state=open]:animate-accordion-down"
+      data-slot="accordion-content"
+      {...props}
+    >
+      <div className={cn("pb-4 pt-0", className)}>{children}</div>
+    </AccordionPrimitive.Content>
+  );
+}
+
+export { Accordion, AccordionContent, AccordionItem, AccordionTrigger };

vite-frontend/src/components/ui/alert.tsx

@@ -0,0 +1,70 @@
+import * as React from "react";
+import { cva, type VariantProps } from "class-variance-authority";
+
+import { cn } from "@/lib/utils";
+
+const alertVariants = cva(
+  "relative w-full rounded-lg border px-4 py-3 text-sm",
+  {
+    variants: {
+      variant: {
+        default: "border-default-200 bg-default-50/70 text-foreground",
+        destructive:
+          "border-danger-200 bg-danger-50 text-danger-700 dark:text-danger-300",
+        success:
+          "border-success-200 bg-success-50 text-success-700 dark:text-success-300",
+        warning:
+          "border-warning-200 bg-warning-50 text-warning-700 dark:text-warning-300",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+    },
+  },
+);
+
+function Alert({
+  className,
+  variant,
+  ...props
+}: React.ComponentProps<"div"> & VariantProps<typeof alertVariants>) {
+  return (
+    <div
+      className={cn(alertVariants({ className, variant }))}
+      data-slot="alert"
+      role="alert"
+      {...props}
+    />
+  );
+}
+
+function AlertTitle({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<"h5">) {
+  return (
+    <h5
+      className={cn("mb-1 font-medium leading-none tracking-tight", className)}
+      data-slot="alert-title"
+      {...props}
+    >
+      {children}
+    </h5>
+  );
+}
+
+function AlertDescription({
+  className,
+  ...props
+}: React.ComponentProps<"div">) {
+  return (
+    <div
+      className={cn("text-sm opacity-90", className)}
+      data-slot="alert-description"
+      {...props}
+    />
+  );
+}
+
+export { Alert, AlertDescription, AlertTitle };

vite-frontend/src/components/ui/badge.tsx

@@ -0,0 +1,39 @@
+import * as React from "react";
+import { cva, type VariantProps } from "class-variance-authority";
+
+import { cn } from "@/lib/utils";
+
+const badgeVariants = cva(
+  "inline-flex items-center rounded-full border px-2.5 py-0.5 text-xs font-semibold transition-colors",
+  {
+    variants: {
+      variant: {
+        default: "border-transparent bg-primary text-primary-foreground",
+        secondary: "border-transparent bg-secondary text-secondary-foreground",
+        destructive: "border-transparent bg-danger text-white",
+        outline: "text-foreground",
+        success: "border-transparent bg-success text-white",
+        warning: "border-transparent bg-warning text-white",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+    },
+  },
+);
+
+function Badge({
+  className,
+  variant,
+  ...props
+}: React.ComponentProps<"span"> & VariantProps<typeof badgeVariants>) {
+  return (
+    <span
+      className={cn(badgeVariants({ className, variant }))}
+      data-slot="badge"
+      {...props}
+    />
+  );
+}
+
+export { Badge, badgeVariants };

vite-frontend/src/components/ui/button.tsx

@@ -0,0 +1,61 @@
+import * as React from "react";
+import { Slot } from "@radix-ui/react-slot";
+import { cva, type VariantProps } from "class-variance-authority";
+
+import { cn } from "@/lib/utils";
+
+const buttonVariants = cva(
+  "inline-flex items-center justify-center whitespace-nowrap rounded-md text-sm font-medium transition-colors transition-transform duration-100 active:scale-95 disabled:active:scale-100 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50",
+  {
+    variants: {
+      variant: {
+        default: "bg-primary text-primary-foreground hover:bg-primary/90",
+        destructive: "bg-danger text-white hover:bg-danger/90",
+        outline:
+          "border border-input bg-background hover:bg-default-100 hover:text-foreground dark:hover:bg-default-200/40",
+        secondary:
+          "bg-secondary text-secondary-foreground hover:bg-secondary/80",
+        ghost:
+          "hover:bg-default-100 hover:text-foreground dark:hover:bg-default-200/40",
+        link: "text-primary underline-offset-4 hover:underline",
+        light:
+          "bg-transparent hover:bg-default-100 dark:hover:bg-default-200/40",
+        flat: "bg-default-100 text-foreground hover:bg-default-200 dark:bg-default-100/40",
+      },
+      size: {
+        default: "h-9 px-4 py-2",
+        sm: "h-8 rounded-md px-3 text-xs",
+        lg: "h-10 rounded-md px-8",
+        icon: "h-9 w-9",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  },
+);
+
+type ButtonProps = React.ComponentProps<"button"> &
+  VariantProps<typeof buttonVariants> & {
+    asChild?: boolean;
+  };
+
+const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
+  ({ asChild = false, className, size, variant, ...props }, ref) => {
+    const Comp = asChild ? Slot : "button";
+
+    return (
+      <Comp
+        ref={ref}
+        className={cn(buttonVariants({ className, size, variant }))}
+        data-slot="button"
+        {...props}
+      />
+    );
+  },
+);
+
+Button.displayName = "Button";
+
+export { Button, buttonVariants };

vite-frontend/src/components/ui/card.tsx

@@ -0,0 +1,84 @@
+import * as React from "react";
+
+import { cn } from "@/lib/utils";
+
+function Card({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      className={cn(
+        "rounded-xl border border-default-200 bg-white text-card-foreground shadow-sm dark:bg-default-50/20",
+        className,
+      )}
+      data-slot="card"
+      {...props}
+    />
+  );
+}
+
+function CardHeader({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      className={cn("flex flex-col gap-1.5 p-6", className)}
+      data-slot="card-header"
+      {...props}
+    />
+  );
+}
+
+function CardTitle({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<"h3">) {
+  return (
+    <h3
+      className={cn(
+        "text-lg font-semibold leading-none tracking-tight",
+        className,
+      )}
+      data-slot="card-title"
+      {...props}
+    >
+      {children}
+    </h3>
+  );
+}
+
+function CardDescription({ className, ...props }: React.ComponentProps<"p">) {
+  return (
+    <p
+      className={cn("text-sm text-default-500", className)}
+      data-slot="card-description"
+      {...props}
+    />
+  );
+}
+
+function CardContent({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      className={cn("p-6 pt-0", className)}
+      data-slot="card-content"
+      {...props}
+    />
+  );
+}
+
+function CardFooter({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      className={cn("flex items-center p-6 pt-0", className)}
+      data-slot="card-footer"
+      {...props}
+    />
+  );
+}
+
+export {
+  Card,
+  CardContent,
+  CardDescription,
+  CardFooter,
+  CardHeader,
+  CardTitle,
+};

vite-frontend/src/components/ui/checkbox.tsx

@@ -0,0 +1,30 @@
+import * as React from "react";
+import * as CheckboxPrimitive from "@radix-ui/react-checkbox";
+import { CheckIcon } from "lucide-react";
+
+import { cn } from "@/lib/utils";
+
+function Checkbox({
+  className,
+  ...props
+}: React.ComponentProps<typeof CheckboxPrimitive.Root>) {
+  return (
+    <CheckboxPrimitive.Root
+      className={cn(
+        "peer h-4 w-4 shrink-0 rounded-sm border border-primary shadow transition-transform duration-100 active:scale-90 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50 data-[state=checked]:bg-primary data-[state=checked]:text-primary-foreground",
+        className,
+      )}
+      data-slot="checkbox"
+      {...props}
+    >
+      <CheckboxPrimitive.Indicator
+        className="flex items-center justify-center text-current data-[state=checked]:animate-in data-[state=checked]:zoom-in-75 data-[state=checked]:duration-150"
+        data-slot="checkbox-indicator"
+      >
+        <CheckIcon className="h-3.5 w-3.5" />
+      </CheckboxPrimitive.Indicator>
+    </CheckboxPrimitive.Root>
+  );
+}
+
+export { Checkbox };

vite-frontend/src/components/ui/dialog.tsx

@@ -0,0 +1,144 @@
+import * as React from "react";
+import * as DialogPrimitive from "@radix-ui/react-dialog";
+import { XIcon } from "lucide-react";
+
+import { cn } from "@/lib/utils";
+
+function Dialog({
+  ...props
+}: React.ComponentProps<typeof DialogPrimitive.Root>) {
+  return <DialogPrimitive.Root data-slot="dialog" {...props} />;
+}
+
+function DialogTrigger({
+  ...props
+}: React.ComponentProps<typeof DialogPrimitive.Trigger>) {
+  return <DialogPrimitive.Trigger data-slot="dialog-trigger" {...props} />;
+}
+
+function DialogPortal({
+  ...props
+}: React.ComponentProps<typeof DialogPrimitive.Portal>) {
+  return <DialogPrimitive.Portal data-slot="dialog-portal" {...props} />;
+}
+
+function DialogClose({
+  ...props
+}: React.ComponentProps<typeof DialogPrimitive.Close>) {
+  return <DialogPrimitive.Close data-slot="dialog-close" {...props} />;
+}
+
+function DialogOverlay({
+  className,
+  ...props
+}: React.ComponentProps<typeof DialogPrimitive.Overlay>) {
+  return (
+    <DialogPrimitive.Overlay
+      className={cn(
+        "fixed inset-0 z-50 bg-black/50 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0",
+        className,
+      )}
+      data-slot="dialog-overlay"
+      {...props}
+    />
+  );
+}
+
+function DialogContent({
+  className,
+  children,
+  showCloseButton = true,
+  ...props
+}: React.ComponentProps<typeof DialogPrimitive.Content> & {
+  showCloseButton?: boolean;
+}) {
+  return (
+    <DialogPortal>
+      <DialogOverlay />
+      <DialogPrimitive.Content
+        className={cn(
+          "fixed left-[50%] top-[50%] z-50 grid w-full max-w-lg translate-x-[-50%] translate-y-[-50%] gap-4 border border-default-200 bg-white p-6 shadow-lg duration-200 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[state=open]:slide-in-from-bottom-4 data-[state=closed]:slide-out-to-bottom-2 sm:rounded-lg dark:bg-default-50",
+          className,
+        )}
+        data-slot="dialog-content"
+        {...props}
+      >
+        {children}
+        {showCloseButton && (
+          <DialogPrimitive.Close className="absolute right-4 top-4 rounded-sm opacity-70 ring-offset-background transition-opacity hover:opacity-100 focus:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:pointer-events-none">
+            <XIcon className="h-4 w-4" />
+            <span className="sr-only">Close</span>
+          </DialogPrimitive.Close>
+        )}
+      </DialogPrimitive.Content>
+    </DialogPortal>
+  );
+}
+
+function DialogHeader({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      className={cn(
+        "flex flex-col space-y-1.5 text-center sm:text-left",
+        className,
+      )}
+      data-slot="dialog-header"
+      {...props}
+    />
+  );
+}
+
+function DialogFooter({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      className={cn(
+        "flex flex-col-reverse sm:flex-row sm:justify-end sm:space-x-2",
+        className,
+      )}
+      data-slot="dialog-footer"
+      {...props}
+    />
+  );
+}
+
+function DialogTitle({
+  className,
+  ...props
+}: React.ComponentProps<typeof DialogPrimitive.Title>) {
+  return (
+    <DialogPrimitive.Title
+      className={cn(
+        "text-lg font-semibold leading-none tracking-tight",
+        className,
+      )}
+      data-slot="dialog-title"
+      {...props}
+    />
+  );
+}
+
+function DialogDescription({
+  className,
+  ...props
+}: React.ComponentProps<typeof DialogPrimitive.Description>) {
+  return (
+    <DialogPrimitive.Description
+      className={cn("text-sm text-default-500", className)}
+      data-slot="dialog-description"
+      {...props}
+    />
+  );
+}
+
+export {
+  Dialog,
+  DialogClose,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogOverlay,
+  DialogPortal,
+  DialogTitle,
+  DialogTrigger,
+};

vite-frontend/src/components/ui/dropdown-menu.tsx

@@ -0,0 +1,252 @@
+import * as React from "react";
+import * as DropdownMenuPrimitive from "@radix-ui/react-dropdown-menu";
+import { CheckIcon, ChevronRightIcon, CircleIcon } from "lucide-react";
+
+import { cn } from "@/lib/utils";
+
+function DropdownMenu({
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Root>) {
+  return <DropdownMenuPrimitive.Root data-slot="dropdown-menu" {...props} />;
+}
+
+function DropdownMenuTrigger({
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Trigger>) {
+  return (
+    <DropdownMenuPrimitive.Trigger
+      data-slot="dropdown-menu-trigger"
+      {...props}
+    />
+  );
+}
+
+function DropdownMenuGroup({
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Group>) {
+  return (
+    <DropdownMenuPrimitive.Group data-slot="dropdown-menu-group" {...props} />
+  );
+}
+
+function DropdownMenuPortal({
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Portal>) {
+  return (
+    <DropdownMenuPrimitive.Portal data-slot="dropdown-menu-portal" {...props} />
+  );
+}
+
+function DropdownMenuSub({
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Sub>) {
+  return <DropdownMenuPrimitive.Sub data-slot="dropdown-menu-sub" {...props} />;
+}
+
+function DropdownMenuRadioGroup({
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.RadioGroup>) {
+  return (
+    <DropdownMenuPrimitive.RadioGroup
+      data-slot="dropdown-menu-radio-group"
+      {...props}
+    />
+  );
+}
+
+function DropdownMenuSubTrigger({
+  className,
+  inset,
+  children,
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.SubTrigger> & {
+  inset?: boolean;
+}) {
+  return (
+    <DropdownMenuPrimitive.SubTrigger
+      className={cn(
+        "flex cursor-default select-none items-center rounded-sm px-2 py-1.5 text-sm outline-none focus:bg-default-100 data-[state=open]:bg-default-100",
+        inset && "pl-8",
+        className,
+      )}
+      data-slot="dropdown-menu-sub-trigger"
+      {...props}
+    >
+      {children}
+      <ChevronRightIcon className="ml-auto h-4 w-4" />
+    </DropdownMenuPrimitive.SubTrigger>
+  );
+}
+
+function DropdownMenuSubContent({
+  className,
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.SubContent>) {
+  return (
+    <DropdownMenuPrimitive.SubContent
+      className={cn(
+        "z-50 min-w-32 overflow-hidden rounded-md border border-default-200 bg-white p-1 text-foreground shadow-lg data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=top]:slide-in-from-bottom-2 data-[side=bottom]:slide-in-from-top-2 dark:bg-default-50",
+        className,
+      )}
+      data-slot="dropdown-menu-sub-content"
+      {...props}
+    />
+  );
+}
+
+function DropdownMenuContent({
+  className,
+  sideOffset = 6,
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Content>) {
+  return (
+    <DropdownMenuPrimitive.Portal>
+      <DropdownMenuPrimitive.Content
+        className={cn(
+          "z-50 min-w-32 overflow-hidden rounded-md border border-default-200 bg-white p-1 text-foreground shadow-md data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=top]:slide-in-from-bottom-2 data-[side=bottom]:slide-in-from-top-2 dark:bg-default-50",
+          className,
+        )}
+        data-slot="dropdown-menu-content"
+        sideOffset={sideOffset}
+        {...props}
+      />
+    </DropdownMenuPrimitive.Portal>
+  );
+}
+
+function DropdownMenuItem({
+  className,
+  inset,
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Item> & {
+  inset?: boolean;
+}) {
+  return (
+    <DropdownMenuPrimitive.Item
+      className={cn(
+        "relative flex cursor-default select-none items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-none transition-colors focus:bg-default-100 data-[disabled]:pointer-events-none data-[disabled]:opacity-50",
+        inset && "pl-8",
+        className,
+      )}
+      data-slot="dropdown-menu-item"
+      {...props}
+    />
+  );
+}
+
+function DropdownMenuCheckboxItem({
+  className,
+  children,
+  checked,
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.CheckboxItem>) {
+  return (
+    <DropdownMenuPrimitive.CheckboxItem
+      checked={checked}
+      className={cn(
+        "relative flex cursor-default select-none items-center rounded-sm py-1.5 pl-8 pr-2 text-sm outline-none transition-colors focus:bg-default-100 data-[disabled]:pointer-events-none data-[disabled]:opacity-50",
+        className,
+      )}
+      data-slot="dropdown-menu-checkbox-item"
+      {...props}
+    >
+      <span className="absolute left-2 flex h-3.5 w-3.5 items-center justify-center">
+        <DropdownMenuPrimitive.ItemIndicator>
+          <CheckIcon className="h-4 w-4" />
+        </DropdownMenuPrimitive.ItemIndicator>
+      </span>
+      {children}
+    </DropdownMenuPrimitive.CheckboxItem>
+  );
+}
+
+function DropdownMenuRadioItem({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.RadioItem>) {
+  return (
+    <DropdownMenuPrimitive.RadioItem
+      className={cn(
+        "relative flex cursor-default select-none items-center rounded-sm py-1.5 pl-8 pr-2 text-sm outline-none transition-colors focus:bg-default-100 data-[disabled]:pointer-events-none data-[disabled]:opacity-50",
+        className,
+      )}
+      data-slot="dropdown-menu-radio-item"
+      {...props}
+    >
+      <span className="absolute left-2 flex h-3.5 w-3.5 items-center justify-center">
+        <DropdownMenuPrimitive.ItemIndicator>
+          <CircleIcon className="h-2 w-2 fill-current" />
+        </DropdownMenuPrimitive.ItemIndicator>
+      </span>
+      {children}
+    </DropdownMenuPrimitive.RadioItem>
+  );
+}
+
+function DropdownMenuLabel({
+  className,
+  inset,
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Label> & {
+  inset?: boolean;
+}) {
+  return (
+    <DropdownMenuPrimitive.Label
+      className={cn(
+        "px-2 py-1.5 text-sm font-semibold",
+        inset && "pl-8",
+        className,
+      )}
+      data-slot="dropdown-menu-label"
+      {...props}
+    />
+  );
+}
+
+function DropdownMenuSeparator({
+  className,
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Separator>) {
+  return (
+    <DropdownMenuPrimitive.Separator
+      className={cn("-mx-1 my-1 h-px bg-divider", className)}
+      data-slot="dropdown-menu-separator"
+      {...props}
+    />
+  );
+}
+
+function DropdownMenuShortcut({
+  className,
+  ...props
+}: React.ComponentProps<"span">) {
+  return (
+    <span
+      className={cn(
+        "ml-auto text-xs tracking-widest text-default-500",
+        className,
+      )}
+      data-slot="dropdown-menu-shortcut"
+      {...props}
+    />
+  );
+}
+
+export {
+  DropdownMenu,
+  DropdownMenuCheckboxItem,
+  DropdownMenuContent,
+  DropdownMenuGroup,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuPortal,
+  DropdownMenuRadioGroup,
+  DropdownMenuRadioItem,
+  DropdownMenuSeparator,
+  DropdownMenuShortcut,
+  DropdownMenuSub,
+  DropdownMenuSubContent,
+  DropdownMenuSubTrigger,
+  DropdownMenuTrigger,
+};

vite-frontend/src/components/ui/input.tsx

@@ -0,0 +1,19 @@
+import * as React from "react";
+
+import { cn } from "@/lib/utils";
+
+function Input({ className, type, ...props }: React.ComponentProps<"input">) {
+  return (
+    <input
+      className={cn(
+        "flex h-9 w-full rounded-md border border-input bg-background px-3 py-1 text-sm shadow-sm transition-colors file:border-0 file:bg-transparent file:text-sm file:font-medium placeholder:text-default-400 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50",
+        className,
+      )}
+      data-slot="input"
+      type={type}
+      {...props}
+    />
+  );
+}
+
+export { Input };

vite-frontend/src/components/ui/label.tsx

@@ -0,0 +1,22 @@
+import * as React from "react";
+import * as LabelPrimitive from "@radix-ui/react-label";
+
+import { cn } from "@/lib/utils";
+
+function Label({
+  className,
+  ...props
+}: React.ComponentProps<typeof LabelPrimitive.Root>) {
+  return (
+    <LabelPrimitive.Root
+      className={cn(
+        "text-sm font-medium leading-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70",
+        className,
+      )}
+      data-slot="label"
+      {...props}
+    />
+  );
+}
+
+export { Label };

vite-frontend/src/components/ui/progress.tsx

@@ -0,0 +1,36 @@
+import * as React from "react";
+import * as ProgressPrimitive from "@radix-ui/react-progress";
+
+import { cn } from "@/lib/utils";
+
+function Progress({
+  className,
+  value,
+  indicatorClassName,
+  ...props
+}: React.ComponentProps<typeof ProgressPrimitive.Root> & {
+  indicatorClassName?: string;
+}) {
+  return (
+    <ProgressPrimitive.Root
+      className={cn(
+        "relative h-2 w-full overflow-hidden rounded-full bg-default-200",
+        className,
+      )}
+      data-slot="progress"
+      value={value}
+      {...props}
+    >
+      <ProgressPrimitive.Indicator
+        className={cn(
+          "h-full w-full flex-1 bg-primary transition-all",
+          indicatorClassName,
+        )}
+        data-slot="progress-indicator"
+        style={{ transform: `translateX(-${100 - (value ?? 0)}%)` }}
+      />
+    </ProgressPrimitive.Root>
+  );
+}
+
+export { Progress };

vite-frontend/src/components/ui/radio-group.tsx

@@ -0,0 +1,43 @@
+import * as React from "react";
+import * as RadioGroupPrimitive from "@radix-ui/react-radio-group";
+import { CircleIcon } from "lucide-react";
+
+import { cn } from "@/lib/utils";
+
+function RadioGroup({
+  className,
+  ...props
+}: React.ComponentProps<typeof RadioGroupPrimitive.Root>) {
+  return (
+    <RadioGroupPrimitive.Root
+      className={cn("grid gap-2", className)}
+      data-slot="radio-group"
+      {...props}
+    />
+  );
+}
+
+function RadioGroupItem({
+  className,
+  ...props
+}: React.ComponentProps<typeof RadioGroupPrimitive.Item>) {
+  return (
+    <RadioGroupPrimitive.Item
+      className={cn(
+        "aspect-square h-4 w-4 rounded-full border border-primary text-primary shadow focus:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50",
+        className,
+      )}
+      data-slot="radio-group-item"
+      {...props}
+    >
+      <RadioGroupPrimitive.Indicator
+        className="flex items-center justify-center"
+        data-slot="radio-group-indicator"
+      >
+        <CircleIcon className="h-2.5 w-2.5 fill-current text-current" />
+      </RadioGroupPrimitive.Indicator>
+    </RadioGroupPrimitive.Item>
+  );
+}
+
+export { RadioGroup, RadioGroupItem };

vite-frontend/src/components/ui/select.tsx

@@ -0,0 +1,177 @@
+import * as React from "react";
+import * as SelectPrimitive from "@radix-ui/react-select";
+import { CheckIcon, ChevronDownIcon, ChevronUpIcon } from "lucide-react";
+
+import { cn } from "@/lib/utils";
+
+function Select({
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.Root>) {
+  return <SelectPrimitive.Root data-slot="select" {...props} />;
+}
+
+function SelectGroup({
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.Group>) {
+  return <SelectPrimitive.Group data-slot="select-group" {...props} />;
+}
+
+function SelectValue({
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.Value>) {
+  return <SelectPrimitive.Value data-slot="select-value" {...props} />;
+}
+
+function SelectTrigger({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.Trigger>) {
+  return (
+    <SelectPrimitive.Trigger
+      className={cn(
+        "flex h-9 w-full items-center justify-between rounded-md border border-input bg-transparent px-3 py-2 text-sm shadow-sm placeholder:text-default-400 focus:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50",
+        className,
+      )}
+      data-slot="select-trigger"
+      {...props}
+    >
+      {children}
+      <SelectPrimitive.Icon asChild>
+        <ChevronDownIcon className="h-4 w-4 opacity-50" />
+      </SelectPrimitive.Icon>
+    </SelectPrimitive.Trigger>
+  );
+}
+
+function SelectScrollUpButton({
+  className,
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.ScrollUpButton>) {
+  return (
+    <SelectPrimitive.ScrollUpButton
+      className={cn(
+        "flex cursor-default items-center justify-center py-1",
+        className,
+      )}
+      data-slot="select-scroll-up-button"
+      {...props}
+    >
+      <ChevronUpIcon className="h-4 w-4" />
+    </SelectPrimitive.ScrollUpButton>
+  );
+}
+
+function SelectScrollDownButton({
+  className,
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.ScrollDownButton>) {
+  return (
+    <SelectPrimitive.ScrollDownButton
+      className={cn(
+        "flex cursor-default items-center justify-center py-1",
+        className,
+      )}
+      data-slot="select-scroll-down-button"
+      {...props}
+    >
+      <ChevronDownIcon className="h-4 w-4" />
+    </SelectPrimitive.ScrollDownButton>
+  );
+}
+
+function SelectContent({
+  className,
+  children,
+  position = "popper",
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.Content>) {
+  return (
+    <SelectPrimitive.Portal>
+      <SelectPrimitive.Content
+        className={cn(
+          "relative z-50 max-h-96 min-w-[8rem] overflow-hidden rounded-md border border-default-200 bg-white text-foreground shadow-md data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=top]:slide-in-from-bottom-2 data-[side=bottom]:slide-in-from-top-2 dark:bg-default-50",
+          position === "popper" &&
+            "data-[side=bottom]:translate-y-1 data-[side=left]:-translate-x-1 data-[side=right]:translate-x-1 data-[side=top]:-translate-y-1",
+          className,
+        )}
+        data-slot="select-content"
+        position={position}
+        {...props}
+      >
+        <SelectScrollUpButton />
+        <SelectPrimitive.Viewport
+          className={cn(
+            "p-1",
+            position === "popper" &&
+              "h-[var(--radix-select-trigger-height)] w-full min-w-[var(--radix-select-trigger-width)]",
+          )}
+        >
+          {children}
+        </SelectPrimitive.Viewport>
+        <SelectScrollDownButton />
+      </SelectPrimitive.Content>
+    </SelectPrimitive.Portal>
+  );
+}
+
+function SelectLabel({
+  className,
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.Label>) {
+  return (
+    <SelectPrimitive.Label
+      className={cn("px-2 py-1.5 text-sm font-semibold", className)}
+      data-slot="select-label"
+      {...props}
+    />
+  );
+}
+
+function SelectItem({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.Item>) {
+  return (
+    <SelectPrimitive.Item
+      className={cn(
+        "relative flex w-full cursor-default select-none items-center rounded-sm py-1.5 pl-8 pr-2 text-sm outline-none focus:bg-default-100 data-[disabled]:pointer-events-none data-[disabled]:opacity-50",
+        className,
+      )}
+      data-slot="select-item"
+      {...props}
+    >
+      <span className="absolute left-2 flex h-3.5 w-3.5 items-center justify-center">
+        <SelectPrimitive.ItemIndicator>
+          <CheckIcon className="h-4 w-4" />
+        </SelectPrimitive.ItemIndicator>
+      </span>
+      <SelectPrimitive.ItemText>{children}</SelectPrimitive.ItemText>
+    </SelectPrimitive.Item>
+  );
+}
+
+function SelectSeparator({
+  className,
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.Separator>) {
+  return (
+    <SelectPrimitive.Separator
+      className={cn("-mx-1 my-1 h-px bg-divider", className)}
+      data-slot="select-separator"
+      {...props}
+    />
+  );
+}
+
+export {
+  Select,
+  SelectContent,
+  SelectGroup,
+  SelectItem,
+  SelectLabel,
+  SelectSeparator,
+  SelectTrigger,
+  SelectValue,
+};

vite-frontend/src/components/ui/separator.tsx

@@ -0,0 +1,27 @@
+import * as React from "react";
+import * as SeparatorPrimitive from "@radix-ui/react-separator";
+
+import { cn } from "@/lib/utils";
+
+function Separator({
+  className,
+  decorative = true,
+  orientation = "horizontal",
+  ...props
+}: React.ComponentProps<typeof SeparatorPrimitive.Root>) {
+  return (
+    <SeparatorPrimitive.Root
+      className={cn(
+        "shrink-0 bg-divider",
+        orientation === "horizontal" ? "h-px w-full" : "h-full w-px",
+        className,
+      )}
+      data-slot="separator"
+      decorative={decorative}
+      orientation={orientation}
+      {...props}
+    />
+  );
+}
+
+export { Separator };

vite-frontend/src/components/ui/switch.tsx

@@ -0,0 +1,29 @@
+import * as React from "react";
+import * as SwitchPrimitive from "@radix-ui/react-switch";
+
+import { cn } from "@/lib/utils";
+
+function Switch({
+  className,
+  ...props
+}: React.ComponentProps<typeof SwitchPrimitive.Root>) {
+  return (
+    <SwitchPrimitive.Root
+      className={cn(
+        "peer inline-flex h-5 w-9 shrink-0 cursor-pointer items-center rounded-full border-2 border-transparent shadow-sm transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50 data-[state=checked]:bg-primary data-[state=unchecked]:bg-default-200",
+        className,
+      )}
+      data-slot="switch"
+      {...props}
+    >
+      <SwitchPrimitive.Thumb
+        className={cn(
+          "pointer-events-none block h-4 w-4 rounded-full bg-white ring-0 transition-transform data-[state=checked]:translate-x-4 data-[state=unchecked]:translate-x-0",
+        )}
+        data-slot="switch-thumb"
+      />
+    </SwitchPrimitive.Root>
+  );
+}
+
+export { Switch };

vite-frontend/src/components/ui/table.tsx

@@ -0,0 +1,111 @@
+import * as React from "react";
+
+import { cn } from "@/lib/utils";
+
+function Table({ className, ...props }: React.ComponentProps<"table">) {
+  return (
+    <div className="relative w-full overflow-auto" data-slot="table-wrapper">
+      <table
+        className={cn("w-full caption-bottom text-sm", className)}
+        data-slot="table"
+        {...props}
+      />
+    </div>
+  );
+}
+
+function TableHeader({ className, ...props }: React.ComponentProps<"thead">) {
+  return (
+    <thead
+      className={cn("[&_tr]:border-b", className)}
+      data-slot="table-header"
+      {...props}
+    />
+  );
+}
+
+function TableBody({ className, ...props }: React.ComponentProps<"tbody">) {
+  return (
+    <tbody
+      className={cn("[&_tr:last-child]:border-0", className)}
+      data-slot="table-body"
+      {...props}
+    />
+  );
+}
+
+function TableFooter({ className, ...props }: React.ComponentProps<"tfoot">) {
+  return (
+    <tfoot
+      className={cn(
+        "border-t bg-default-50/70 font-medium [&>tr]:last:border-b-0",
+        className,
+      )}
+      data-slot="table-footer"
+      {...props}
+    />
+  );
+}
+
+function TableRow({ className, ...props }: React.ComponentProps<"tr">) {
+  return (
+    <tr
+      className={cn(
+        "border-b transition-colors hover:bg-default-50/50",
+        className,
+      )}
+      data-slot="table-row"
+      {...props}
+    />
+  );
+}
+
+function TableHead({ className, ...props }: React.ComponentProps<"th">) {
+  return (
+    <th
+      className={cn(
+        "h-10 px-2 text-left align-middle font-medium text-default-600 [&:has([role=checkbox])]:pr-0",
+        className,
+      )}
+      data-slot="table-head"
+      {...props}
+    />
+  );
+}
+
+function TableCell({ className, ...props }: React.ComponentProps<"td">) {
+  return (
+    <td
+      className={cn(
+        "p-2 align-middle [&:has([role=checkbox])]:pr-0",
+        className,
+      )}
+      data-slot="table-cell"
+      {...props}
+    />
+  );
+}
+
+function TableCaption({
+  className,
+  ...props
+}: React.ComponentProps<"caption">) {
+  return (
+    <caption
+      className={cn("mt-4 text-sm text-default-500", className)}
+      data-slot="table-caption"
+      {...props}
+    />
+  );
+}
+
+export {
+  Table,
+  TableBody,
+  TableCaption,
+  TableCell,
+  TableFooter,
+  TableHead,
+  TableHeader,
+  TableRow,
+};

vite-frontend/src/components/ui/tabs.tsx

@@ -0,0 +1,64 @@
+import * as React from "react";
+import * as TabsPrimitive from "@radix-ui/react-tabs";
+
+import { cn } from "@/lib/utils";
+
+function Tabs({
+  className,
+  ...props
+}: React.ComponentProps<typeof TabsPrimitive.Root>) {
+  return (
+    <TabsPrimitive.Root
+      className={cn("flex flex-col gap-2", className)}
+      data-slot="tabs"
+      {...props}
+    />
+  );
+}
+
+function TabsList({
+  className,
+  ...props
+}: React.ComponentProps<typeof TabsPrimitive.List>) {
+  return (
+    <TabsPrimitive.List
+      className={cn(
+        "inline-flex h-9 items-center justify-center rounded-lg bg-default-100 p-1 text-default-500",
+        className,
+      )}
+      data-slot="tabs-list"
+      {...props}
+    />
+  );
+}
+
+function TabsTrigger({
+  className,
+  ...props
+}: React.ComponentProps<typeof TabsPrimitive.Trigger>) {
+  return (
+    <TabsPrimitive.Trigger
+      className={cn(
+        "inline-flex items-center justify-center whitespace-nowrap rounded-md px-3 py-1 text-sm font-medium ring-offset-background transition-all focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50 data-[state=active]:bg-white data-[state=active]:text-foreground data-[state=active]:shadow-sm dark:data-[state=active]:bg-default-50",
+        className,
+      )}
+      data-slot="tabs-trigger"
+      {...props}
+    />
+  );
+}
+
+function TabsContent({
+  className,
+  ...props
+}: React.ComponentProps<typeof TabsPrimitive.Content>) {
+  return (
+    <TabsPrimitive.Content
+      className={cn("outline-none", className)}
+      data-slot="tabs-content"
+      {...props}
+    />
+  );
+}
+
+export { Tabs, TabsContent, TabsList, TabsTrigger };

vite-frontend/src/components/ui/textarea.tsx

@@ -0,0 +1,18 @@
+import * as React from "react";
+
+import { cn } from "@/lib/utils";
+
+function Textarea({ className, ...props }: React.ComponentProps<"textarea">) {
+  return (
+    <textarea
+      className={cn(
+        "flex min-h-[84px] w-full rounded-md border border-input bg-background px-3 py-2 text-sm shadow-sm placeholder:text-default-400 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50",
+        className,
+      )}
+      data-slot="textarea"
+      {...props}
+    />
+  );
+}
+
+export { Textarea };

vite-frontend/src/components/version-footer.tsx

@@ -0,0 +1,110 @@
+import { useEffect, useState } from "react";
+
+import { siteConfig } from "@/config/site";
+import {
+  UPDATE_CHANNEL_CHANGED_EVENT,
+  type UpdateReleaseChannel,
+  getLatestVersionByChannel,
+  getUpdateReleaseChannel,
+  hasVersionUpdate,
+} from "@/utils/version-update";
+
+const FALLBACK_GITHUB_REPO = "https://github.com/Sagit-chu/flux-panel";
+
+interface VersionFooterProps {
+  version: string;
+  containerClassName?: string;
+  versionClassName?: string;
+  poweredClassName?: string;
+  updateBadgeClassName?: string;
+}
+
+export function VersionFooter({
+  version,
+  containerClassName,
+  versionClassName,
+  poweredClassName,
+  updateBadgeClassName,
+}: VersionFooterProps) {
+  const [channel, setChannel] = useState<UpdateReleaseChannel>(
+    getUpdateReleaseChannel(),
+  );
+  const [updateAvailable, setUpdateAvailable] = useState(false);
+  const [latestUpdateVersion, setLatestUpdateVersion] = useState<string | null>(
+    null,
+  );
+
+  useEffect(() => {
+    const handleChannelChange = () => {
+      setChannel(getUpdateReleaseChannel());
+    };
+
+    window.addEventListener(UPDATE_CHANNEL_CHANGED_EVENT, handleChannelChange);
+    window.addEventListener("storage", handleChannelChange);
+
+    return () => {
+      window.removeEventListener(
+        UPDATE_CHANNEL_CHANGED_EVENT,
+        handleChannelChange,
+      );
+      window.removeEventListener("storage", handleChannelChange);
+    };
+  }, []);
+
+  useEffect(() => {
+    let active = true;
+
+    const checkUpdate = async () => {
+      const latestVersion = await getLatestVersionByChannel(
+        channel,
+        siteConfig.github_repo || FALLBACK_GITHUB_REPO,
+      );
+
+      if (!active) {
+        return;
+      }
+
+      if (!latestVersion) {
+        setUpdateAvailable(false);
+        setLatestUpdateVersion(null);
+
+        return;
+      }
+
+      const hasUpdate = hasVersionUpdate(version, latestVersion);
+
+      setUpdateAvailable(hasUpdate);
+      setLatestUpdateVersion(hasUpdate ? latestVersion : null);
+    };
+
+    void checkUpdate();
+
+    return () => {
+      active = false;
+    };
+  }, [channel, version]);
+
+  return (
+    <div className={containerClassName}>
+      <p className={versionClassName}>
+        v{version}
+        {updateAvailable && latestUpdateVersion && (
+          <span className={updateBadgeClassName} role="status">
+            {latestUpdateVersion}
+          </span>
+        )}
+      </p>
+      <p className={poweredClassName}>
+        Powered by{" "}
+        <a
+          className="text-gray-500 dark:text-gray-400 hover:text-gray-600 dark:hover:text-gray-300 transition-colors"
+          href={siteConfig.github_repo}
+          rel="noopener noreferrer"
+          target="_blank"
+        >
+          FLVX
+        </a>
+      </p>
+    </div>
+  );
+}

vite-frontend/src/config/site.ts

@@ -16,10 +16,15 @@ const getInitialConfig = () => {
       version: VERSION,
       app_version: APP_VERSION,
       github_repo: GITHUB_REPO,
+      app_logo: "",
+      app_favicon: "",
     };
   }
 
   const cachedAppName = localStorage.getItem(CACHE_PREFIX + "app_name");
+  const cachedAppLogo = localStorage.getItem(CACHE_PREFIX + "app_logo") || "";
+  const cachedAppFavicon =
+    localStorage.getItem(CACHE_PREFIX + "app_favicon") || "";
 
   if (cachedAppName) {
     return {
@@ -27,6 +32,8 @@ const getInitialConfig = () => {
       version: VERSION,
       app_version: APP_VERSION,
       github_repo: GITHUB_REPO,
+      app_logo: cachedAppLogo,
+      app_favicon: cachedAppFavicon,
     };
   }
 
@@ -34,6 +41,9 @@ const getInitialConfig = () => {
     name: "FLVX",
     version: VERSION,
     app_version: APP_VERSION,
+    github_repo: GITHUB_REPO,
+    app_logo: cachedAppLogo,
+    app_favicon: cachedAppFavicon,
   };
 };
 
@@ -99,7 +109,7 @@ export const getCachedConfig = async (key: string): Promise<string | null> => {
 // 获取所有配置（优先从缓存）
 export const getCachedConfigs = async (): Promise<Record<string, string>> => {
   // 尝试从缓存获取所有配置
-  const configKeys = ["app_name"];
+  const configKeys = ["app_name", "app_logo", "app_favicon"];
   const cachedConfigs: Record<string, string> = {};
   let hasCachedData = false;
 
@@ -136,15 +146,48 @@ export const getCachedConfigs = async (): Promise<Record<string, string>> => {
   return {};
 };
 
+const updateDocumentFavicon = (faviconUrl: string) => {
+  if (typeof document === "undefined") {
+    return;
+  }
+
+  const normalized = faviconUrl.trim() || "/favicon.ico";
+  const iconLinks = Array.from(
+    document.head.querySelectorAll<HTMLLinkElement>(
+      'link[rel="icon"], link[rel="shortcut icon"]',
+    ),
+  );
+
+  if (iconLinks.length === 0) {
+    const link = document.createElement("link");
+
+    link.rel = "icon";
+    link.href = normalized;
+    document.head.appendChild(link);
+
+    return;
+  }
+
+  iconLinks.forEach((link) => {
+    link.href = normalized;
+  });
+};
+
 // 动态更新网站配置
 export const updateSiteConfig = async () => {
-  const appName = await getCachedConfig("app_name");
+  const configMap = await getCachedConfigs();
+  const appName = (configMap.app_name || "").trim();
+  const appLogo = (configMap.app_logo || "").trim();
+  const appFavicon = (configMap.app_favicon || "").trim();
 
   if (appName && appName !== siteConfig.name) {
     siteConfig.name = appName;
-    // 更新页面标题
-    document.title = appName;
   }
+
+  siteConfig.app_logo = appLogo;
+  siteConfig.app_favicon = appFavicon;
+  document.title = siteConfig.name;
+  updateDocumentFavicon(siteConfig.app_favicon);
 };
 
 // 清除配置缓存的工具函数

vite-frontend/src/hooks/use-local-storage-state.ts

@@ -0,0 +1,51 @@
+import { useCallback, useState, type SetStateAction } from "react";
+
+const readStoredValue = <T>(key: string, fallbackValue: T): T => {
+  try {
+    const rawValue = localStorage.getItem(key);
+
+    if (rawValue === null) {
+      return fallbackValue;
+    }
+
+    return JSON.parse(rawValue) as T;
+  } catch {
+    return fallbackValue;
+  }
+};
+
+export const useLocalStorageState = <T>(
+  key: string,
+  initialValue: T,
+): readonly [T, (value: SetStateAction<T>) => void, () => void] => {
+  const [value, setValue] = useState<T>(() =>
+    readStoredValue(key, initialValue),
+  );
+
+  const setPersistedValue = useCallback(
+    (nextValue: SetStateAction<T>) => {
+      setValue((prevValue) => {
+        const resolvedValue =
+          typeof nextValue === "function"
+            ? (nextValue as (value: T) => T)(prevValue)
+            : nextValue;
+
+        try {
+          localStorage.setItem(key, JSON.stringify(resolvedValue));
+        } catch {}
+
+        return resolvedValue;
+      });
+    },
+    [key],
+  );
+
+  const resetPersistedValue = useCallback(() => {
+    setValue(initialValue);
+    try {
+      localStorage.removeItem(key);
+    } catch {}
+  }, [initialValue, key]);
+
+  return [value, setPersistedValue, resetPersistedValue] as const;
+};

vite-frontend/src/hooks/useH5Mode.ts

@@ -0,0 +1,31 @@
+import { useEffect, useState } from "react";
+
+import { DEFAULT_MOBILE_BREAKPOINT } from "@/hooks/useMobileBreakpoint";
+
+const detectH5Mode = (): boolean => {
+  const isMobile = window.innerWidth <= DEFAULT_MOBILE_BREAKPOINT;
+  const isMobileBrowser =
+    /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(
+      navigator.userAgent,
+    );
+  const urlParams = new URLSearchParams(window.location.search);
+  const isH5Param = urlParams.get("h5") === "true";
+
+  return isMobile || isMobileBrowser || isH5Param;
+};
+
+export const useH5Mode = (): boolean => {
+  const [isH5, setIsH5] = useState(detectH5Mode);
+
+  useEffect(() => {
+    const checkH5Mode = () => {
+      setIsH5(detectH5Mode());
+    };
+
+    window.addEventListener("resize", checkH5Mode);
+
+    return () => window.removeEventListener("resize", checkH5Mode);
+  }, []);
+
+  return isH5;
+};

vite-frontend/src/hooks/useMobileBreakpoint.ts

@@ -0,0 +1,33 @@
+import { useEffect, useState } from "react";
+
+export const DEFAULT_MOBILE_BREAKPOINT = 768;
+
+export const useMobileBreakpoint = (
+  breakpoint = DEFAULT_MOBILE_BREAKPOINT,
+): boolean => {
+  const [isMobile, setIsMobile] = useState(() => {
+    if (typeof window === "undefined") {
+      return false;
+    }
+
+    return window.innerWidth < breakpoint;
+  });
+
+  useEffect(() => {
+    if (typeof window === "undefined") {
+      return;
+    }
+
+    const onResize = () => {
+      setIsMobile(window.innerWidth < breakpoint);
+    };
+
+    window.addEventListener("resize", onResize);
+
+    return () => {
+      window.removeEventListener("resize", onResize);
+    };
+  }, [breakpoint]);
+
+  return isMobile;
+};

vite-frontend/src/hooks/useScrollTopOnPathChange.ts

@@ -0,0 +1,21 @@
+import { useEffect } from "react";
+import { useLocation } from "react-router-dom";
+
+export const useScrollTopOnPathChange = (): void => {
+  const { pathname } = useLocation();
+
+  useEffect(() => {
+    if (!pathname) {
+      return;
+    }
+
+    try {
+      window.scrollTo({ top: 0, left: 0, behavior: "auto" });
+    } catch {
+      window.scrollTo(0, 0);
+    }
+
+    document.body.scrollTop = 0;
+    document.documentElement.scrollTop = 0;
+  }, [pathname]);
+};

vite-frontend/src/hooks/useWebViewMode.ts

@@ -0,0 +1,13 @@
+import { useEffect, useState } from "react";
+
+import { isWebViewFunc } from "@/utils/panel";
+
+export const useWebViewMode = (): boolean => {
+  const [isWebView, setIsWebView] = useState(false);
+
+  useEffect(() => {
+    setIsWebView(isWebViewFunc());
+  }, []);
+
+  return isWebView;
+};

vite-frontend/src/layouts/admin.tsx

@@ -1,12 +1,15 @@
 import React, { useState, useEffect } from "react";
 import { useNavigate, useLocation } from "react-router-dom";
-import { Button } from "@heroui/button";
+import { toast } from "react-hot-toast";
+import { AnimatePresence, motion } from "framer-motion";
+
+import { Button } from "@/shadcn-bridge/heroui/button";
 import {
   Dropdown,
   DropdownTrigger,
   DropdownMenu,
   DropdownItem,
-} from "@heroui/dropdown";
+} from "@/shadcn-bridge/heroui/dropdown";
 import {
   Modal,
   ModalContent,
@@ -14,14 +17,15 @@ import {
   ModalBody,
   ModalFooter,
   useDisclosure,
-} from "@heroui/modal";
-import { Input } from "@heroui/input";
-import { toast } from "react-hot-toast";
-
-import { Logo } from "@/components/icons";
+} from "@/shadcn-bridge/heroui/modal";
+import { Input } from "@/shadcn-bridge/heroui/input";
+import { BrandLogo } from "@/components/brand-logo";
+import { VersionFooter } from "@/components/version-footer";
 import { updatePassword } from "@/api";
 import { safeLogout } from "@/utils/logout";
 import { siteConfig } from "@/config/site";
+import { useMobileBreakpoint } from "@/hooks/useMobileBreakpoint";
+import { getAdminFlag, getSessionName } from "@/utils/session";
 
 interface MenuItem {
   path: string;
@@ -46,8 +50,10 @@ export default function AdminLayout({
   const location = useLocation();
   const { isOpen, onOpen, onOpenChange } = useDisclosure();
 
-  const [isMobile, setIsMobile] = useState(false);
   const [mobileMenuVisible, setMobileMenuVisible] = useState(false);
+  const [isCollapsed, setIsCollapsed] = useState(
+    () => localStorage.getItem("sidebar_collapsed") === "true",
+  );
   const [username, setUsername] = useState("");
   const [isAdmin, setIsAdmin] = useState(false);
   const [passwordLoading, setPasswordLoading] = useState(false);
@@ -57,6 +63,7 @@ export default function AdminLayout({
     newPassword: "",
     confirmPassword: "",
   });
+  const isMobile = useMobileBreakpoint();
 
   // 菜单项配置
   const menuItems: MenuItem[] = [
@@ -170,41 +177,21 @@ export default function AdminLayout({
     },
   ];
 
-  // 检查移动端
-  const checkMobile = () => {
-    setIsMobile(window.innerWidth <= 768);
-    if (window.innerWidth > 768) {
-      setMobileMenuVisible(false);
-    }
-  };
-
   useEffect(() => {
     // 获取用户信息
-    const name = localStorage.getItem("name") || "Admin";
-
-    // 兼容处理：如果没有admin字段，根据role_id判断（0为管理员）
-    let adminFlag = localStorage.getItem("admin") === "true";
-
-    if (localStorage.getItem("admin") === null) {
-      const roleId = parseInt(localStorage.getItem("role_id") || "1", 10);
-
-      adminFlag = roleId === 0;
-      // 补充设置admin字段，避免下次再次判断
-      localStorage.setItem("admin", adminFlag.toString());
-    }
+    const name = getSessionName() || "Admin";
+    const adminFlag = getAdminFlag();
 
     setUsername(name);
     setIsAdmin(adminFlag);
-
-    // 响应式检查
-    checkMobile();
-    window.addEventListener("resize", checkMobile);
-
-    return () => {
-      window.removeEventListener("resize", checkMobile);
-    };
   }, []);
 
+  useEffect(() => {
+    if (!isMobile) {
+      setMobileMenuVisible(false);
+    }
+  }, [isMobile]);
+
   // 退出登录
   const handleLogout = () => {
     safeLogout();
@@ -221,6 +208,14 @@ export default function AdminLayout({
     setMobileMenuVisible(false);
   };
 
+  // 切换折叠状态
+  const toggleCollapse = () => {
+    const newCollapsed = !isCollapsed;
+
+    setIsCollapsed(newCollapsed);
+    localStorage.setItem("sidebar_collapsed", newCollapsed.toString());
+  };
+
   // 菜单点击处理
   const handleMenuClick = (path: string) => {
     navigate(path);
@@ -321,74 +316,143 @@ export default function AdminLayout({
         className={`
         ${isMobile ? "fixed" : "relative"} 
         ${isMobile && !mobileMenuVisible ? "-translate-x-full" : "translate-x-0"}
-        ${isMobile ? "w-64" : "w-72"} 
+        ${isMobile ? "w-64" : isCollapsed ? "w-20" : "w-72"} 
         bg-white dark:bg-black 
         shadow-lg 
         border-r border-gray-200 dark:border-gray-600
         z-50 
-        transition-transform duration-300 ease-in-out
+        transition-all duration-300 ease-in-out
         flex flex-col
         ${isMobile ? "h-screen" : "h-full"}
         ${isMobile ? "top-0 left-0" : ""}
       `}
       >
         {/* Logo 区域 */}
-        <div className="px-3 py-3 h-14 flex items-center">
-          <div className="flex items-center gap-2 w-full">
-            <Logo size={24} />
-            <div className="flex-1 min-w-0">
-              <h1 className="text-sm font-bold text-foreground overflow-hidden whitespace-nowrap">
-                {siteConfig.name}
-              </h1>
-              <p className="text-xs text-default-500">v{siteConfig.version}</p>
-            </div>
+        <div className="px-5 h-14 flex items-center overflow-hidden whitespace-nowrap box-border">
+          <div className="flex-shrink-0 flex items-center justify-center w-10">
+            <BrandLogo size={28} />
+          </div>
+          <div
+            className={`transition-all duration-300 overflow-hidden ${isCollapsed ? "max-w-0 opacity-0 ml-0" : "max-w-[180px] opacity-100 ml-2"}`}
+          >
+            <h1 className="text-sm font-bold text-foreground overflow-hidden whitespace-nowrap text-ellipsis">
+              {siteConfig.name}
+            </h1>
           </div>
         </div>
 
         {/* 菜单导航 */}
-        <nav className="flex-1 px-4 py-6 overflow-y-auto">
+        <nav className="flex-1 px-3 py-6 overflow-y-auto overflow-x-hidden">
           <ul className="space-y-1">
             {filteredMenuItems.map((item) => {
               const isActive = location.pathname === item.path;
 
               return (
                 <li key={item.path}>
-                  <button
+                  <motion.button
                     className={`
-                       w-full flex items-center gap-3 px-4 py-3 rounded-lg text-left
-                       transition-colors duration-200 min-h-[44px]
+                       w-full flex items-center p-2 rounded-lg text-left
+                       relative min-h-[44px] overflow-hidden transition-colors
                        ${
                          isActive
-                           ? "bg-primary-100 dark:bg-primary-600/20 text-primary-600 dark:text-primary-300"
-                           : "text-gray-700 dark:text-gray-200 hover:bg-gray-100 dark:hover:bg-gray-900"
+                           ? "text-primary-600 dark:text-primary-300"
+                           : "text-gray-700 dark:text-gray-200"
                        }
                      `}
+                    title={isCollapsed ? item.label : undefined}
+                    transition={{ duration: 0.15 }}
                     onClick={() => handleMenuClick(item.path)}
                   >
-                    <div className="flex-shrink-0">{item.icon}</div>
-                    <span className="font-medium text-sm">{item.label}</span>
-                  </button>
+                    {isActive && (
+                      <motion.div
+                        className="absolute inset-0 rounded-lg bg-primary-100 dark:bg-primary-600/20"
+                        layoutId="sidebar-active"
+                        transition={{
+                          type: "spring",
+                          stiffness: 380,
+                          damping: 30,
+                        }}
+                      />
+                    )}
+                    {!isActive && (
+                      <motion.div
+                        className="absolute inset-0 rounded-lg bg-gray-100 dark:bg-gray-900 opacity-0"
+                        transition={{ duration: 0.15 }}
+                        whileHover={{ opacity: 1 }}
+                      />
+                    )}
+                    <div className="flex-shrink-0 w-10 h-10 flex items-center justify-center relative z-10">
+                      {item.icon}
+                    </div>
+                    <div
+                      className={`transition-all duration-300 overflow-hidden flex items-center ${isCollapsed ? "max-w-0 opacity-0 ml-0" : "max-w-[200px] opacity-100 ml-2"}`}
+                    >
+                      <span className="font-medium text-sm relative z-10 whitespace-nowrap">
+                        {item.label}
+                      </span>
+                    </div>
+                  </motion.button>
                 </li>
               );
             })}
           </ul>
         </nav>
 
-        {/* 底部版权信息 */}
-        <div className="px-4 py-2 pb-4 mt-auto flex-shrink-0">
-          <div className="text-center">
-            <p className="text-xs text-gray-400 dark:text-gray-500">
-              Powered by{" "}
-              <a
-                className="text-gray-500 dark:text-gray-400 hover:text-gray-600 dark:hover:text-gray-300 transition-colors"
-                href={siteConfig.github_repo}
-                rel="noopener noreferrer"
-                target="_blank"
-              >
-                FLVX
-              </a>
-            </p>
+        {/* 底部版权信息和折叠按钮 */}
+        <div className="px-5 py-2 pb-4 mt-auto flex-shrink-0 flex items-center justify-between overflow-hidden whitespace-nowrap box-border">
+          <div
+            className={`transition-all duration-300 overflow-hidden flex items-center ${isCollapsed ? "max-w-0 opacity-0" : "max-w-[200px] opacity-100"}`}
+          >
+            <VersionFooter
+              poweredClassName="text-xs text-gray-400 dark:text-gray-500"
+              updateBadgeClassName="ml-2 inline-flex items-center rounded-full bg-rose-500/90 px-2 py-0.5 text-[10px] font-semibold tracking-wide text-white"
+              version={siteConfig.version}
+              versionClassName="text-xs text-gray-400 dark:text-gray-500"
+            />
           </div>
+
+          {/* 桌面端折叠按钮 */}
+          {!isMobile && (
+            <Button
+              isIconOnly
+              className="flex-shrink-0 text-gray-400 hover:text-gray-700 dark:text-gray-500 dark:hover:text-gray-300 min-w-0 w-10 h-10 rounded-full ml-auto"
+              size="sm"
+              variant="light"
+              onPress={toggleCollapse}
+            >
+              {isCollapsed ? (
+                // 向右扩展的提示
+                <svg
+                  className="w-5 h-5"
+                  fill="none"
+                  stroke="currentColor"
+                  viewBox="0 0 24 24"
+                >
+                  <path
+                    d="M13 5l7 7-7 7M5 5l7 7-7 7"
+                    strokeLinecap="round"
+                    strokeLinejoin="round"
+                    strokeWidth={2}
+                  />
+                </svg>
+              ) : (
+                // 向左收起的提示
+                <svg
+                  className="w-5 h-5"
+                  fill="none"
+                  stroke="currentColor"
+                  viewBox="0 0 24 24"
+                >
+                  <path
+                    d="M11 19l-7-7 7-7m8 14l-7-7 7-7"
+                    strokeLinecap="round"
+                    strokeLinejoin="round"
+                    strokeWidth={2}
+                  />
+                </svg>
+              )}
+            </Button>
+          )}
         </div>
       </aside>
 
@@ -493,10 +557,19 @@ export default function AdminLayout({
         </header>
 
         {/* 主内容 */}
-        <main
-          className={`flex-1 bg-gray-100 dark:bg-black ${isMobile ? "" : "overflow-y-auto"}`}
-        >
-          {children}
+        <main className="flex-1 bg-gray-100 dark:bg-black overflow-y-auto">
+          <AnimatePresence mode="wait">
+            <motion.div
+              key={location.pathname}
+              animate={{ opacity: 1, y: 0 }}
+              className="h-full"
+              exit={{ opacity: 0, y: -6 }}
+              initial={{ opacity: 0, y: 10 }}
+              transition={{ duration: 0.22, ease: [0.25, 0.46, 0.45, 0.94] }}
+            >
+              {children}
+            </motion.div>
+          </AnimatePresence>
         </main>
       </div>
 

vite-frontend/src/layouts/h5-simple.tsx

@@ -1,9 +1,10 @@
 import React from "react";
-import { useNavigate, useLocation } from "react-router-dom";
-import { Button } from "@heroui/button";
+import { useNavigate } from "react-router-dom";
 
-import { Logo } from "@/components/icons";
+import { Button } from "@/shadcn-bridge/heroui/button";
+import { BrandLogo } from "@/components/brand-logo";
 import { siteConfig } from "@/config/site";
+import { useScrollTopOnPathChange } from "@/hooks/useScrollTopOnPathChange";
 
 export default function H5SimpleLayout({
   children,
@@ -11,18 +12,8 @@ export default function H5SimpleLayout({
   children: React.ReactNode;
 }) {
   const navigate = useNavigate();
-  const location = useLocation();
 
-  // 路由切换时回到顶部，避免上一页滚动位置保留
-  React.useEffect(() => {
-    try {
-      window.scrollTo({ top: 0, left: 0, behavior: "auto" });
-    } catch {
-      window.scrollTo(0, 0);
-    }
-    document.body.scrollTop = 0;
-    document.documentElement.scrollTop = 0;
-  }, [location.pathname]);
+  useScrollTopOnPathChange();
 
   const handleBack = () => {
     navigate("/profile");
@@ -42,7 +33,7 @@ export default function H5SimpleLayout({
               />
             </svg>
           </Button>
-          <Logo size={20} />
+          <BrandLogo size={20} />
           <h1 className="text-sm font-bold text-foreground">
             {siteConfig.name}
           </h1>

vite-frontend/src/layouts/h5.tsx

@@ -1,8 +1,10 @@
 import React, { useState, useEffect } from "react";
 import { useNavigate, useLocation } from "react-router-dom";
 
-import { Logo } from "@/components/icons";
+import { BrandLogo } from "@/components/brand-logo";
 import { siteConfig } from "@/config/site";
+import { getAdminFlag } from "@/utils/session";
+import { useScrollTopOnPathChange } from "@/hooks/useScrollTopOnPathChange";
 
 interface TabItem {
   path: string;
@@ -16,6 +18,8 @@ export default function H5Layout({ children }: { children: React.ReactNode }) {
   const location = useLocation();
   const [isAdmin, setIsAdmin] = useState(false);
 
+  useScrollTopOnPathChange();
+
   // Tabbar配置
   const tabItems: TabItem[] = [
     {
@@ -80,18 +84,7 @@ export default function H5Layout({ children }: { children: React.ReactNode }) {
   ];
 
   useEffect(() => {
-    // 兼容处理：如果没有admin字段，根据role_id判断（0为管理员）
-    let adminFlag = localStorage.getItem("admin") === "true";
-
-    if (localStorage.getItem("admin") === null) {
-      const roleId = parseInt(localStorage.getItem("role_id") || "1", 10);
-
-      adminFlag = roleId === 0;
-      // 补充设置admin字段，避免下次再次判断
-      localStorage.setItem("admin", adminFlag.toString());
-    }
-
-    setIsAdmin(adminFlag);
+    setIsAdmin(getAdminFlag());
   }, []);
 
   // Tab点击处理
@@ -104,23 +97,12 @@ export default function H5Layout({ children }: { children: React.ReactNode }) {
     (item) => !item.adminOnly || isAdmin,
   );
 
-  // 路由切换时回到页面顶部，避免上一页的滚动位置遗留
-  useEffect(() => {
-    try {
-      window.scrollTo({ top: 0, left: 0, behavior: "auto" });
-    } catch {
-      window.scrollTo(0, 0);
-    }
-    document.body.scrollTop = 0;
-    document.documentElement.scrollTop = 0;
-  }, [location.pathname]);
-
   return (
     <div className="flex flex-col min-h-screen bg-gray-100 dark:bg-black">
       {/* 顶部导航栏 */}
       <header className="bg-white dark:bg-black shadow-sm border-b border-gray-200 dark:border-gray-600 h-14 safe-top flex-shrink-0 flex items-center justify-between px-4 relative z-10">
         <div className="flex items-center gap-2">
-          <Logo size={20} />
+          <BrandLogo size={20} />
           <h1 className="text-sm font-bold text-foreground">
             {siteConfig.name}
           </h1>
@@ -133,10 +115,10 @@ export default function H5Layout({ children }: { children: React.ReactNode }) {
       <main className="flex-1 bg-gray-100 dark:bg-black">{children}</main>
 
       {/* 用于给固定 Tabbar 腾出空间的占位元素 */}
-      <div aria-hidden className="h-16 safe-bottom" />
+      <div aria-hidden className="h-[calc(4rem+var(--safe-area-bottom))]" />
 
       {/* 底部Tabbar */}
-      <nav className="bg-white dark:bg-black border-t border-gray-200 dark:border-gray-600 h-16 safe-bottom flex-shrink-0 flex items-center justify-around px-2 fixed bottom-0 left-0 right-0 z-30">
+      <nav className="bg-white dark:bg-black border-t border-gray-200 dark:border-gray-600 h-[calc(4rem+var(--safe-area-bottom))] flex-shrink-0 flex items-center justify-around px-2 fixed bottom-0 left-0 right-0 z-30">
         {filteredTabItems.map((item) => {
           const isActive = location.pathname === item.path;
 
@@ -144,7 +126,7 @@ export default function H5Layout({ children }: { children: React.ReactNode }) {
             <button
               key={item.path}
               className={`
-                flex flex-col items-center justify-center flex-1 h-full
+                flex flex-col items-center justify-center flex-1 h-full pb-[var(--safe-area-bottom)]
                 transition-colors duration-200 min-h-[44px]
                 ${
                   isActive

vite-frontend/src/lib/utils.ts

@@ -0,0 +1,6 @@
+import { type ClassValue, clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

vite-frontend/src/main.tsx

@@ -1,10 +1,13 @@
 import ReactDOM from "react-dom/client";
 import { BrowserRouter } from "react-router-dom";
+import { registerSW } from "virtual:pwa-register";
 
 import App from "./App.tsx";
 import { Provider } from "./provider.tsx";
 import "@/styles/globals.css";
 
+registerSW({ immediate: true });
+
 ReactDOM.createRoot(document.getElementById("root")!).render(
   <BrowserRouter>
     <Provider>

vite-frontend/src/pages/change-password.tsx

@@ -1,10 +1,10 @@
-import { Button } from "@heroui/button";
-import { Input } from "@heroui/input";
-import { Card, CardBody, CardHeader } from "@heroui/card";
 import { useState } from "react";
 import { useNavigate } from "react-router-dom";
 import toast from "react-hot-toast";
 
+import { Button } from "@/shadcn-bridge/heroui/button";
+import { Input } from "@/shadcn-bridge/heroui/input";
+import { Card, CardBody, CardHeader } from "@/shadcn-bridge/heroui/card";
 import { title } from "@/components/primitives";
 import { updatePassword } from "@/api";
 import DefaultLayout from "@/layouts/default";
@@ -115,6 +115,7 @@ export default function ChangePasswordPage() {
             <CardHeader className="pb-0 pt-6 px-6 flex-col items-center">
               <div className="w-12 h-12 bg-warning-100 rounded-full flex items-center justify-center mb-3">
                 <svg
+                  aria-hidden="true"
                   className="w-6 h-6 text-warning-600"
                   fill="currentColor"
                   viewBox="0 0 20 20"
@@ -200,7 +201,7 @@ export default function ChangePasswordPage() {
                   disabled={loading}
                   isLoading={loading}
                   size="lg"
-                  onClick={handleSubmit}
+                  onPress={handleSubmit}
                 >
                   {loading ? "修改中..." : "立即修改账号密码"}
                 </Button>

vite-frontend/src/pages/config.tsx

@@ -1,17 +1,31 @@
 import { useState, useEffect, useRef } from "react";
 import { useNavigate } from "react-router-dom";
-import { Button } from "@heroui/button";
-import { Card, CardBody, CardHeader } from "@heroui/card";
-import { Input } from "@heroui/input";
-import { Textarea } from "@heroui/input";
-import { Spinner } from "@heroui/spinner";
-import { Divider } from "@heroui/divider";
-import { Switch } from "@heroui/switch";
-import { Select, SelectItem } from "@heroui/select";
-import { Checkbox, CheckboxGroup } from "@heroui/checkbox";
 import toast from "react-hot-toast";
 
-import { updateConfigs, exportBackup, importBackup, getAnnouncement, updateAnnouncement, type AnnouncementData } from "@/api";
+import { Button } from "@/shadcn-bridge/heroui/button";
+import { Card, CardBody, CardHeader } from "@/shadcn-bridge/heroui/card";
+import { Input } from "@/shadcn-bridge/heroui/input";
+import { Textarea } from "@/shadcn-bridge/heroui/input";
+import { Spinner } from "@/shadcn-bridge/heroui/spinner";
+import { Divider } from "@/shadcn-bridge/heroui/divider";
+import { Switch } from "@/shadcn-bridge/heroui/switch";
+import { Select, SelectItem } from "@/shadcn-bridge/heroui/select";
+import { Checkbox } from "@/shadcn-bridge/heroui/checkbox";
+import {
+  Modal,
+  ModalBody,
+  ModalContent,
+  ModalFooter,
+  ModalHeader,
+} from "@/shadcn-bridge/heroui/modal";
+import {
+  updateConfigs,
+  exportBackup,
+  importBackup,
+  getAnnouncement,
+  updateAnnouncement,
+  type AnnouncementData,
+} from "@/api";
 import { SettingsIcon } from "@/components/icons";
 import { isAdmin } from "@/utils/auth";
 import {
@@ -19,6 +33,11 @@ import {
   clearConfigCache,
   updateSiteConfig,
 } from "@/config/site";
+import {
+  type UpdateReleaseChannel,
+  getUpdateReleaseChannel,
+  setUpdateReleaseChannel,
+} from "@/utils/version-update";
 
 // 简单的保存图标组件
 const SaveIcon = ({ className }: { className?: string }) => (
@@ -48,6 +67,13 @@ interface ConfigItem {
   dependsValue?: string; // 依赖的配置项值
 }
 
+const BRAND_PREVIEW_KEYS = ["app_logo", "app_favicon"] as const;
+
+type BrandPreviewKey = (typeof BRAND_PREVIEW_KEYS)[number];
+
+const isBrandPreviewKey = (key: string): key is BrandPreviewKey =>
+  BRAND_PREVIEW_KEYS.includes(key as BrandPreviewKey);
+
 // 网站配置项定义
 const CONFIG_ITEMS: ConfigItem[] = [
   {
@@ -72,6 +98,22 @@ const CONFIG_ITEMS: ConfigItem[] = [
     description: "在浏览器标签页和导航栏显示的应用名称",
     type: "input",
   },
+  {
+    key: "app_logo",
+    label: "网页角标 Logo",
+    placeholder: "请输入 Logo 图片 URL",
+    description:
+      "用于页面左上角导航角标，支持站内路径（如 /logo.png）或完整图片 URL",
+    type: "input",
+  },
+  {
+    key: "app_favicon",
+    label: "浏览器缩略图标",
+    placeholder: "请输入 Favicon 图片 URL",
+    description:
+      "用于浏览器标签页图标，支持站内路径（如 /favicon.ico）或完整图片 URL",
+    type: "input",
+  },
   {
     key: "captcha_enabled",
     label: "启用验证码",
@@ -98,6 +140,21 @@ const CONFIG_ITEMS: ConfigItem[] = [
   },
 ];
 
+const BACKUP_TYPE_OPTIONS = [
+  { value: "users", label: "用户" },
+  { value: "nodes", label: "节点" },
+  { value: "tunnels", label: "隧道" },
+  { value: "forwards", label: "转发" },
+  { value: "userTunnels", label: "用户隧道权限" },
+  { value: "speedLimits", label: "限速规则" },
+  { value: "tunnelGroups", label: "隧道分组" },
+  { value: "userGroups", label: "用户分组" },
+  { value: "permissions", label: "分组权限" },
+  { value: "configs", label: "系统配置" },
+] as const;
+
+const BACKUP_TYPE_VALUES = BACKUP_TYPE_OPTIONS.map((option) => option.value);
+
 // 初始化时从缓存读取配置，避免闪烁
 const getInitialConfigs = (): Record<string, string> => {
   if (typeof window === "undefined") return {};
@@ -109,6 +166,8 @@ const getInitialConfigs = (): Record<string, string> => {
     "cloudflare_secret_key",
     "ip",
     "panel_domain",
+    "app_logo",
+    "app_favicon",
   ];
   const initialConfigs: Record<string, string> = {};
 
@@ -142,6 +201,8 @@ export default function ConfigPage() {
   const [importTypes, setImportTypes] = useState<string[]>([]);
   const [exporting, setExporting] = useState(false);
   const [importing, setImporting] = useState(false);
+  const [exportSelectorOpen, setExportSelectorOpen] = useState(false);
+  const [importSelectorOpen, setImportSelectorOpen] = useState(false);
   const [importFileName, setImportFileName] = useState("");
   const fileInputRef = useRef<HTMLInputElement>(null);
 
@@ -151,6 +212,12 @@ export default function ConfigPage() {
   });
   const [announcementLoading, setAnnouncementLoading] = useState(true);
   const [announcementSaving, setAnnouncementSaving] = useState(false);
+  const [updateChannel, setUpdateChannel] = useState<UpdateReleaseChannel>(
+    getUpdateReleaseChannel(),
+  );
+  const [previewLoadFailed, setPreviewLoadFailed] = useState<
+    Partial<Record<BrandPreviewKey, boolean>>
+  >({});
 
   // 权限检查
   useEffect(() => {
@@ -236,11 +303,23 @@ export default function ConfigPage() {
     }
   };
 
+  const handleUpdateChannelChange = (channel: UpdateReleaseChannel) => {
+    setUpdateChannel(channel);
+    setUpdateReleaseChannel(channel);
+    toast.success(
+      `更新通道已切换为${channel === "stable" ? "稳定版" : "开发版"}`,
+    );
+  };
+
   const handleConfigChange = (key: string, value: string) => {
     const newConfigs = { ...configs, [key]: value };
 
     setConfigs(newConfigs);
 
+    if (isBrandPreviewKey(key)) {
+      setPreviewLoadFailed((prev) => ({ ...prev, [key]: false }));
+    }
+
     const hasChangesNow =
       Object.keys(newConfigs).some(
         (k) => newConfigs[k] !== originalConfigs[k],
@@ -272,8 +351,11 @@ export default function ConfigPage() {
         setOriginalConfigs({ ...configs });
         setHasChanges(false);
 
-        // 如果应用名称发生变化，立即更新网站配置
-        if (changedKeys.includes("app_name")) {
+        if (
+          changedKeys.some((key) =>
+            ["app_name", "app_logo", "app_favicon"].includes(key),
+          )
+        ) {
           await updateSiteConfig();
         }
 
@@ -302,6 +384,78 @@ export default function ConfigPage() {
     return configs[item.dependsOn] === item.dependsValue;
   };
 
+  const renderBrandPreview = (key: BrandPreviewKey) => {
+    const previewUrl = (configs[key] || "").trim();
+    const appNamePreview = (configs.app_name || "").trim() || "应用名称";
+    const failed = previewLoadFailed[key] === true;
+    const showImage = previewUrl.length > 0 && !failed;
+
+    return (
+      <div className="mt-3 rounded-lg border border-default-200 dark:border-default-100/30 bg-default-50/60 dark:bg-default-100/10 p-3">
+        <p className="text-xs text-default-500">实时预览</p>
+        <div className="mt-2 rounded-md border border-default-200 dark:border-default-100/30 bg-white dark:bg-black px-3 py-2">
+          {key === "app_logo" ? (
+            <div className="flex h-10 items-center gap-2">
+              {showImage ? (
+                <img
+                  alt="logo preview"
+                  className="h-7 w-7 rounded-sm border border-default-200 object-cover dark:border-default-100/30"
+                  src={previewUrl}
+                  onError={() =>
+                    setPreviewLoadFailed((prev) => ({ ...prev, [key]: true }))
+                  }
+                  onLoad={() =>
+                    setPreviewLoadFailed((prev) => ({ ...prev, [key]: false }))
+                  }
+                />
+              ) : (
+                <div className="flex h-7 w-7 items-center justify-center rounded-sm bg-default-200 text-[10px] font-semibold text-default-600 dark:bg-default-700 dark:text-default-200">
+                  LOGO
+                </div>
+              )}
+              <span className="truncate text-sm font-semibold text-foreground">
+                {appNamePreview}
+              </span>
+            </div>
+          ) : (
+            <div className="flex h-7 max-w-[260px] items-center gap-2 rounded border border-default-200 bg-default-100/70 px-2 dark:border-default-100/30 dark:bg-default-100/20">
+              {showImage ? (
+                <img
+                  alt="favicon preview"
+                  className="h-4 w-4 rounded-sm object-contain"
+                  src={previewUrl}
+                  onError={() =>
+                    setPreviewLoadFailed((prev) => ({ ...prev, [key]: true }))
+                  }
+                  onLoad={() =>
+                    setPreviewLoadFailed((prev) => ({ ...prev, [key]: false }))
+                  }
+                />
+              ) : (
+                <div className="h-4 w-4 rounded-sm bg-default-300 dark:bg-default-600" />
+              )}
+              <span className="truncate text-xs text-default-700 dark:text-default-300">
+                {appNamePreview}
+              </span>
+            </div>
+          )}
+        </div>
+
+        {previewUrl.length === 0 ? (
+          <p className="mt-2 text-xs text-default-500">
+            输入图片 URL 后会实时显示预览
+          </p>
+        ) : null}
+
+        {previewUrl.length > 0 && failed ? (
+          <p className="mt-2 text-xs text-danger">
+            图片加载失败，请检查图片地址是否可访问
+          </p>
+        ) : null}
+      </div>
+    );
+  };
+
   // 渲染不同类型的配置项
   const renderConfigItem = (item: ConfigItem) => {
     const isChanged =
@@ -310,19 +464,22 @@ export default function ConfigPage() {
     switch (item.type) {
       case "input":
         return (
-          <Input
-            classNames={{
-              input: "text-sm",
-              inputWrapper: isChanged
-                ? "border-warning-300 data-[hover=true]:border-warning-400"
-                : "",
-            }}
-            placeholder={item.placeholder}
-            size="md"
-            value={configs[item.key] || ""}
-            variant="bordered"
-            onChange={(e) => handleConfigChange(item.key, e.target.value)}
-          />
+          <>
+            <Input
+              classNames={{
+                input: "text-sm",
+                inputWrapper: isChanged
+                  ? "border-warning-300 data-[hover=true]:border-warning-400"
+                  : "",
+              }}
+              placeholder={item.placeholder}
+              size="md"
+              value={configs[item.key] || ""}
+              variant="bordered"
+              onChange={(e) => handleConfigChange(item.key, e.target.value)}
+            />
+            {isBrandPreviewKey(item.key) ? renderBrandPreview(item.key) : null}
+          </>
         );
 
       case "switch":
@@ -387,6 +544,7 @@ export default function ConfigPage() {
     try {
       await exportBackup(exportTypes);
       toast.success("导出成功");
+      setExportSelectorOpen(false);
     } catch {
       toast.error("导出失败，请重试");
     } finally {
@@ -394,6 +552,17 @@ export default function ConfigPage() {
     }
   };
 
+  const triggerImportFilePicker = () => {
+    if (importTypes.length === 0) {
+      toast.error("请先选择要导入的数据类型");
+
+      return;
+    }
+
+    setImportSelectorOpen(false);
+    requestAnimationFrame(() => fileInputRef.current?.click());
+  };
+
   const handleFileChange = async (e: React.ChangeEvent<HTMLInputElement>) => {
     const file = e.target.files?.[0];
 
@@ -434,6 +603,92 @@ export default function ConfigPage() {
     }
   };
 
+  const toggleTypeSelection = (
+    type: string,
+    setTypes: React.Dispatch<React.SetStateAction<string[]>>,
+  ) => {
+    setTypes((prev) =>
+      prev.includes(type)
+        ? prev.filter((item) => item !== type)
+        : [...prev, type],
+    );
+  };
+
+  const isAllTypesSelected = (types: string[]) =>
+    BACKUP_TYPE_VALUES.every((type) => types.includes(type));
+
+  const renderTypeSelection = (
+    label: string,
+    selectedTypes: string[],
+    setTypes: React.Dispatch<React.SetStateAction<string[]>>,
+  ) => {
+    const allSelected = isAllTypesSelected(selectedTypes);
+
+    return (
+      <div className="space-y-3">
+        <div className="flex flex-wrap items-center justify-between gap-2">
+          <span className="text-sm font-medium text-default-700 dark:text-default-300">
+            {label}
+          </span>
+          <div className="flex items-center gap-2">
+            <Button
+              size="sm"
+              variant="flat"
+              onPress={() =>
+                setTypes(allSelected ? [] : [...BACKUP_TYPE_VALUES])
+              }
+            >
+              {allSelected ? "取消全选" : "全选"}
+            </Button>
+            <Button size="sm" variant="light" onPress={() => setTypes([])}>
+              清空
+            </Button>
+          </div>
+        </div>
+
+        <div className="grid grid-cols-1 sm:grid-cols-2 gap-2">
+          {BACKUP_TYPE_OPTIONS.map((option) => {
+            const isSelected = selectedTypes.includes(option.value);
+
+            return (
+              <button
+                key={option.value}
+                aria-pressed={isSelected}
+                className={`w-full px-4 py-3 rounded-lg border transition-all duration-200 cursor-pointer text-left ${
+                  isSelected
+                    ? "bg-primary-50 dark:bg-primary-900/20 border-primary-300 dark:border-primary-500/50 shadow-sm"
+                    : "bg-white dark:bg-default-50 border-default-200 dark:border-default-100/30 hover:border-primary-200 dark:hover:border-primary-500/30 hover:shadow-sm"
+                }`}
+                type="button"
+                onClick={() => toggleTypeSelection(option.value, setTypes)}
+              >
+                <div className="flex items-center gap-3">
+                  <Checkbox
+                    classNames={{
+                      base: "pointer-events-none",
+                    }}
+                    color="primary"
+                    isSelected={isSelected}
+                    size="md"
+                  />
+                  <span
+                    className={`font-medium ${
+                      isSelected
+                        ? "text-default-900 dark:text-default-100"
+                        : "text-default-700 dark:text-default-500"
+                    }`}
+                  >
+                    {option.label}
+                  </span>
+                </div>
+              </button>
+            );
+          })}
+        </div>
+      </div>
+    );
+  };
+
   if (loading) {
     return (
       <div className="flex items-center justify-center min-h-[400px]">
@@ -456,7 +711,7 @@ export default function ConfigPage() {
       </div>
 
       <Card className="shadow-md">
-        <CardHeader className="pb-4">
+        <CardHeader className="pb-6">
           <div className="flex justify-between items-center w-full">
             <div>
               <h2 className="text-xl font-semibold">基本设置</h2>
@@ -470,7 +725,7 @@ export default function ConfigPage() {
                 disabled={!hasChanges}
                 isLoading={saving}
                 startContent={<SaveIcon className="w-4 h-4" />}
-                onClick={handleSave}
+                onPress={handleSave}
               >
                 {saving ? "保存中..." : "保存配置"}
               </Button>
@@ -480,7 +735,7 @@ export default function ConfigPage() {
 
         <Divider />
 
-        <CardBody className="space-y-6 pt-6">
+        <CardBody className="space-y-6 pt-8 md:pt-8">
           {CONFIG_ITEMS.map((item, index) => {
             // 检查配置项是否应该显示
             if (!shouldShowItem(item)) {
@@ -514,15 +769,51 @@ export default function ConfigPage() {
               </div>
             );
           })}
+
+          <Divider className="my-2" />
+
+          <div className="space-y-3">
+            <div className="flex flex-col gap-1">
+              <p className="text-sm font-medium text-gray-700 dark:text-gray-300">
+                更新通道
+              </p>
+              <p className="text-xs text-gray-500 dark:text-gray-400">
+                稳定版仅匹配纯数字版本；开发版仅匹配包含 alpha / beta / rc
+                的版本。
+              </p>
+            </div>
+
+            <Select
+              selectedKeys={[updateChannel]}
+              size="md"
+              variant="bordered"
+              onSelectionChange={(keys) => {
+                const selected =
+                  (Array.from(keys)[0] as UpdateReleaseChannel) || "stable";
+
+                handleUpdateChannelChange(selected);
+              }}
+            >
+              <SelectItem key="stable" description="仅纯数字版本，如 2.1.4">
+                稳定版
+              </SelectItem>
+              <SelectItem
+                key="dev"
+                description="仅 alpha / beta / rc 关键字版本"
+              >
+                开发版
+              </SelectItem>
+            </Select>
+          </div>
         </CardBody>
       </Card>
 
       {hasChanges && (
         <Card className="mt-4 bg-warning-50 dark:bg-warning-900/20 border-warning-200 dark:border-warning-800">
           <CardBody className="py-3">
-            <div className="flex items-center gap-2 text-warning-700 dark:text-warning-300">
+            <div className="w-full flex items-center justify-center gap-2 text-warning-700 dark:text-warning-300">
               <div className="w-2 h-2 bg-warning-500 rounded-full animate-pulse" />
-              <span className="text-sm">
+              <span className="text-sm font-medium">
                 检测到配置变更，请记得保存您的修改
               </span>
             </div>
@@ -531,7 +822,7 @@ export default function ConfigPage() {
       )}
 
       <Card className="mt-6 shadow-md">
-        <CardHeader className="pb-4">
+        <CardHeader className="pb-6">
           <div className="flex justify-between items-center w-full">
             <div>
               <h2 className="text-xl font-semibold">公告管理</h2>
@@ -544,7 +835,7 @@ export default function ConfigPage() {
 
         <Divider />
 
-        <CardBody className="space-y-4 pt-6">
+        <CardBody className="space-y-4 pt-8 md:pt-8">
           {announcementLoading ? (
             <div className="flex justify-center py-8">
               <Spinner size="lg" />
@@ -555,7 +846,10 @@ export default function ConfigPage() {
                 <Switch
                   isSelected={announcement.enabled === 1}
                   onValueChange={(checked) =>
-                    setAnnouncement({ ...announcement, enabled: checked ? 1 : 0 })
+                    setAnnouncement({
+                      ...announcement,
+                      enabled: checked ? 1 : 0,
+                    })
                   }
                 >
                   <span className="text-sm text-gray-700 dark:text-gray-300">
@@ -569,21 +863,24 @@ export default function ConfigPage() {
 
               <Textarea
                 label="公告内容"
-                placeholder="请输入公告内容"
+                minRows={4}
+                placeholder="支持 Markdown，例如：**加粗**、[链接](https://example.com)、- 列表"
                 value={announcement.content}
                 variant="bordered"
-                minRows={4}
                 onChange={(e) =>
                   setAnnouncement({ ...announcement, content: e.target.value })
                 }
               />
+              <p className="text-xs text-gray-500 dark:text-gray-400">
+                公告支持 Markdown 语法，链接会在新标签页打开
+              </p>
 
               <div className="flex justify-end">
                 <Button
                   color="primary"
                   isLoading={announcementSaving}
                   startContent={<SaveIcon className="w-4 h-4" />}
-                  onClick={saveAnnouncement}
+                  onPress={saveAnnouncement}
                 >
                   保存公告
                 </Button>
@@ -595,7 +892,7 @@ export default function ConfigPage() {
 
       {/* 备份与恢复 */}
       <Card className="mt-6 shadow-md">
-        <CardHeader className="pb-4">
+        <CardHeader className="pb-6">
           <div className="flex justify-between items-center w-full">
             <div>
               <h2 className="text-xl font-semibold">数据备份与恢复</h2>
@@ -608,64 +905,24 @@ export default function ConfigPage() {
 
         <Divider />
 
-        <CardBody className="space-y-6 pt-6">
+        <CardBody className="space-y-6 pt-8 md:pt-8">
           {/* 导出部分 */}
           <div className="space-y-4">
             <h3 className="text-lg font-medium">导出数据</h3>
             <p className="text-sm text-gray-600 dark:text-gray-400">
               选择要导出的数据类型，导出为 JSON 格式文件
             </p>
-
-            <CheckboxGroup
-              classNames={{
-                wrapper: "gap-4",
-              }}
-              label="选择导出内容"
-              orientation="horizontal"
-              value={exportTypes}
-              onValueChange={(values) => setExportTypes(values as string[])}
-            >
-              <Checkbox value="users">用户</Checkbox>
-              <Checkbox value="nodes">节点</Checkbox>
-              <Checkbox value="tunnels">隧道</Checkbox>
-              <Checkbox value="forwards">转发</Checkbox>
-              <Checkbox value="userTunnels">用户隧道权限</Checkbox>
-              <Checkbox value="speedLimits">限速规则</Checkbox>
-              <Checkbox value="tunnelGroups">隧道分组</Checkbox>
-              <Checkbox value="userGroups">用户分组</Checkbox>
-              <Checkbox value="permissions">分组权限</Checkbox>
-              <Checkbox value="configs">系统配置</Checkbox>
-            </CheckboxGroup>
+            <p className="text-xs text-default-500">
+              当前已选 {exportTypes.length} / {BACKUP_TYPE_VALUES.length}
+            </p>
 
             <div className="flex gap-3">
               <Button
                 color="primary"
                 isLoading={exporting}
-                onPress={handleExport}
+                onPress={() => setExportSelectorOpen(true)}
               >
-                {exporting ? "导出中..." : "导出数据"}
-              </Button>
-              <Button
-                variant="bordered"
-                onPress={() => {
-                  setExportTypes([
-                    "users",
-                    "nodes",
-                    "tunnels",
-                    "forwards",
-                    "userTunnels",
-                    "speedLimits",
-                    "tunnelGroups",
-                    "userGroups",
-                    "permissions",
-                    "configs",
-                  ]);
-                }}
-              >
-                全选
-              </Button>
-              <Button variant="flat" onPress={() => setExportTypes([])}>
-                清空
+                {exporting ? "导出中..." : "选择并导出"}
               </Button>
             </div>
           </div>
@@ -678,27 +935,9 @@ export default function ConfigPage() {
             <p className="text-sm text-gray-600 dark:text-gray-400">
               选择要导入的数据类型，支持从备份文件恢复数据
             </p>
-
-            <CheckboxGroup
-              classNames={{
-                wrapper: "gap-4",
-              }}
-              label="选择导入内容"
-              orientation="horizontal"
-              value={importTypes}
-              onValueChange={(values) => setImportTypes(values as string[])}
-            >
-              <Checkbox value="users">用户</Checkbox>
-              <Checkbox value="nodes">节点</Checkbox>
-              <Checkbox value="tunnels">隧道</Checkbox>
-              <Checkbox value="forwards">转发</Checkbox>
-              <Checkbox value="userTunnels">用户隧道权限</Checkbox>
-              <Checkbox value="speedLimits">限速规则</Checkbox>
-              <Checkbox value="tunnelGroups">隧道分组</Checkbox>
-              <Checkbox value="userGroups">用户分组</Checkbox>
-              <Checkbox value="permissions">分组权限</Checkbox>
-              <Checkbox value="configs">系统配置</Checkbox>
-            </CheckboxGroup>
+            <p className="text-xs text-default-500">
+              当前已选 {importTypes.length} / {BACKUP_TYPE_VALUES.length}
+            </p>
 
             <input
               ref={fileInputRef}
@@ -713,9 +952,9 @@ export default function ConfigPage() {
                 color="primary"
                 isLoading={importing}
                 variant="flat"
-                onPress={() => fileInputRef.current?.click()}
+                onPress={() => setImportSelectorOpen(true)}
               >
-                {importing ? "导入中..." : "选择文件导入"}
+                {importing ? "导入中..." : "选择并导入"}
               </Button>
               {importFileName && (
                 <span className="self-center text-sm text-gray-600 dark:text-gray-400">
@@ -726,6 +965,56 @@ export default function ConfigPage() {
           </div>
         </CardBody>
       </Card>
+
+      <Modal isOpen={exportSelectorOpen} onOpenChange={setExportSelectorOpen}>
+        <ModalContent>
+          {(onClose) => (
+            <>
+              <ModalHeader>选择导出内容</ModalHeader>
+              <ModalBody>
+                {renderTypeSelection("导出内容", exportTypes, setExportTypes)}
+              </ModalBody>
+              <ModalFooter>
+                <Button variant="light" onPress={onClose}>
+                  取消
+                </Button>
+                <Button
+                  color="primary"
+                  isLoading={exporting}
+                  onPress={handleExport}
+                >
+                  {exporting ? "导出中..." : "确认导出"}
+                </Button>
+              </ModalFooter>
+            </>
+          )}
+        </ModalContent>
+      </Modal>
+
+      <Modal isOpen={importSelectorOpen} onOpenChange={setImportSelectorOpen}>
+        <ModalContent>
+          {(onClose) => (
+            <>
+              <ModalHeader>选择导入内容</ModalHeader>
+              <ModalBody>
+                {renderTypeSelection("导入内容", importTypes, setImportTypes)}
+              </ModalBody>
+              <ModalFooter>
+                <Button variant="light" onPress={onClose}>
+                  取消
+                </Button>
+                <Button
+                  color="primary"
+                  isDisabled={importTypes.length === 0}
+                  onPress={triggerImportFilePicker}
+                >
+                  下一步选择文件
+                </Button>
+              </ModalFooter>
+            </>
+          )}
+        </ModalContent>
+      </Modal>
     </div>
   );
 }

vite-frontend/src/pages/dashboard.tsx

@@ -1,53 +1,24 @@
-import { Card, CardBody, CardHeader } from "@heroui/card";
-import { Button } from "@heroui/button";
-import { Modal, ModalContent, ModalHeader, ModalBody } from "@heroui/modal";
-import { useState, useEffect } from "react";
+import { useState } from "react";
 import toast from "react-hot-toast";
+
+import { AnimatedPage } from "@/components/animated-page";
+import { Card, CardBody, CardHeader } from "@/shadcn-bridge/heroui/card";
+import { Button } from "@/shadcn-bridge/heroui/button";
 import {
-  LineChart,
-  Line,
-  XAxis,
-  YAxis,
-  CartesianGrid,
-  Tooltip,
-  ResponsiveContainer,
-} from "recharts";
-
-import { getUserPackageInfo, getAnnouncement, type AnnouncementData } from "@/api";
-
-interface UserInfo {
-  flow: number;
-  inFlow: number;
-  outFlow: number;
-  num: number;
-  expTime?: string;
-  flowResetTime?: number;
-}
-
-interface UserTunnel {
-  id: number;
-  tunnelId: number;
-  tunnelName: string;
-  flow: number;
-  inFlow: number;
-  outFlow: number;
-  num: number;
-  expTime?: string;
-  flowResetTime?: number;
-  tunnelFlow: number;
-}
-
-interface Forward {
-  id: number;
-  name: string;
-  tunnelId: number;
-  tunnelName: string;
-  inIp: string;
-  inPort: number;
-  remoteAddr: string;
-  inFlow: number;
-  outFlow: number;
-}
+  Modal,
+  ModalContent,
+  ModalHeader,
+  ModalBody,
+} from "@/shadcn-bridge/heroui/modal";
+import { PageEmptyState, PageLoadingState } from "@/components/page-state";
+import { AnnouncementBanner } from "@/pages/dashboard/components/announcement-banner";
+import { FlowChartCard } from "@/pages/dashboard/components/flow-chart-card";
+import { MetricCard } from "@/pages/dashboard/components/metric-card";
+import {
+  useDashboardData,
+  type DashboardForward as Forward,
+  type DashboardUserTunnel as UserTunnel,
+} from "@/pages/dashboard/use-dashboard-data";
 
 interface AddressItem {
   id: number;
@@ -56,176 +27,21 @@ interface AddressItem {
   copying: boolean;
 }
 
-interface StatisticsFlow {
-  id: number;
-  userId: number;
-  flow: number;
-  totalFlow: number;
-  time: string;
-}
-
 export default function DashboardPage() {
-  const [loading, setLoading] = useState(true);
-  const [userInfo, setUserInfo] = useState<UserInfo>({} as UserInfo);
-  const [userTunnels, setUserTunnels] = useState<UserTunnel[]>([]);
-  const [forwardList, setForwardList] = useState<Forward[]>([]);
-  const [statisticsFlows, setStatisticsFlows] = useState<StatisticsFlow[]>([]);
-  const [isAdmin, setIsAdmin] = useState(false);
-  const [announcement, setAnnouncement] = useState<AnnouncementData | null>(null);
+  const {
+    loading,
+    userInfo,
+    userTunnels,
+    forwardList,
+    statisticsFlows,
+    isAdmin,
+    announcement,
+  } = useDashboardData();
 
   const [addressModalOpen, setAddressModalOpen] = useState(false);
   const [addressModalTitle, setAddressModalTitle] = useState("");
   const [addressList, setAddressList] = useState<AddressItem[]>([]);
 
-  // 检查有效期通知
-  const checkExpirationNotifications = (
-    userInfo: UserInfo,
-    tunnels: UserTunnel[],
-  ) => {
-    // 避免重复通知，检查是否已经显示过
-    const notificationKey = `expiration-${userInfo.expTime}-${tunnels.map((t) => t.expTime).join(",")}`;
-    const lastNotified = localStorage.getItem("lastNotified");
-
-    if (lastNotified === notificationKey) {
-      return; // 已经通知过，不重复显示
-    }
-
-    let hasNotification = false;
-
-    // 检查主账户有效期
-    if (userInfo.expTime) {
-      const expDate = new Date(userInfo.expTime);
-      const now = new Date();
-
-      if (!isNaN(expDate.getTime()) && expDate > now) {
-        const diffTime = expDate.getTime() - now.getTime();
-        const diffDays = Math.ceil(diffTime / (1000 * 60 * 60 * 24));
-
-        if (diffDays <= 7 && diffDays > 0) {
-          hasNotification = true;
-          if (diffDays === 1) {
-            toast("账户将于明天过期，请及时续费", {
-              icon: "⚠️",
-              duration: 6000,
-              style: { background: "#f59e0b", color: "#fff" },
-            });
-          } else {
-            toast(`账户将于${diffDays}天后过期，请及时续费`, {
-              icon: "⚠️",
-              duration: 6000,
-              style: { background: "#f59e0b", color: "#fff" },
-            });
-          }
-        } else if (diffDays <= 0) {
-          hasNotification = true;
-          toast("账户已过期，请立即续费", {
-            icon: "⚠️",
-            duration: 8000,
-            style: { background: "#ef4444", color: "#fff" },
-          });
-        }
-      }
-    }
-
-    // 检查隧道有效期
-    tunnels.forEach((tunnel) => {
-      if (tunnel.expTime) {
-        const expDate = new Date(tunnel.expTime);
-        const now = new Date();
-
-        if (!isNaN(expDate.getTime()) && expDate > now) {
-          const diffTime = expDate.getTime() - now.getTime();
-          const diffDays = Math.ceil(diffTime / (1000 * 60 * 60 * 24));
-
-          if (diffDays <= 7 && diffDays > 0) {
-            hasNotification = true;
-            if (diffDays === 1) {
-              toast(`隧道"${tunnel.tunnelName}"将于明天过期`, {
-                icon: "⚠️",
-                duration: 5000,
-                style: { background: "#f59e0b", color: "#fff" },
-              });
-            } else {
-              toast(`隧道"${tunnel.tunnelName}"将于${diffDays}天后过期`, {
-                icon: "⚠️",
-                duration: 5000,
-                style: { background: "#f59e0b", color: "#fff" },
-              });
-            }
-          } else if (diffDays <= 0) {
-            hasNotification = true;
-            toast(`隧道"${tunnel.tunnelName}"已过期`, {
-              icon: "⚠️",
-              duration: 6000,
-              style: { background: "#ef4444", color: "#fff" },
-            });
-          }
-        }
-      }
-    });
-
-    // 如果显示了通知，记录防止重复
-    if (hasNotification) {
-      localStorage.setItem("lastNotified", notificationKey);
-    }
-  };
-
-  useEffect(() => {
-    setLoading(true);
-    setUserInfo({} as UserInfo);
-    setUserTunnels([]);
-    setForwardList([]);
-    setStatisticsFlows([]);
-
-    const adminStatus = localStorage.getItem("admin");
-
-    setIsAdmin(adminStatus === "true");
-
-    loadPackageData();
-    loadAnnouncement();
-    localStorage.setItem("e", "/dashboard");
-  }, []);
-
-  const loadAnnouncement = async () => {
-    try {
-      const res = await getAnnouncement();
-
-      if (res.code === 0 && res.data && res.data.enabled === 1) {
-        setAnnouncement(res.data);
-      }
-    } catch (error) {
-      console.error("Failed to load announcement:", error);
-    }
-  };
-
-  const loadPackageData = async () => {
-    setLoading(true);
-    try {
-      const res = await getUserPackageInfo();
-
-      if (res.code === 0) {
-        const data = res.data;
-
-        setUserInfo(data.userInfo || {});
-        setUserTunnels(data.tunnelPermissions || []);
-        setForwardList(data.forwards || []);
-        setStatisticsFlows(data.statisticsFlows || []);
-
-        // 检查有效期并显示通知
-        checkExpirationNotifications(
-          data.userInfo,
-          data.tunnelPermissions || [],
-        );
-      } else {
-        toast.error(res.msg || "获取套餐信息失败");
-      }
-    } catch {
-      toast.error("获取套餐信息失败");
-    } finally {
-      setLoading(false);
-    }
-  };
-
   const formatFlow = (value: number, unit: string = "bytes"): string => {
     // 99999 表示无限制
     if (value === 99999) {
@@ -283,7 +99,7 @@ export default function DashboardPage() {
     }));
   };
 
-  const getExpStatus = (expTime?: string) => {
+  const getExpStatus = (expTime?: string | number) => {
     if (!expTime)
       return {
         color: "text-green-600 dark:text-green-400",
@@ -444,7 +260,7 @@ export default function DashboardPage() {
     const now = new Date();
     const currentDay = now.getDate();
 
-    let daysUntilReset;
+    let daysUntilReset: number;
 
     if (resetDay > currentDay) {
       daysUntilReset = resetDay - currentDay;
@@ -527,7 +343,7 @@ export default function DashboardPage() {
     }
 
     const firstIp = items[0];
-    let formattedFirstIp;
+    let formattedFirstIp: string;
 
     if (firstIp.includes(":") && !firstIp.startsWith("[")) {
       formattedFirstIp = `[${firstIp}]`;
@@ -592,7 +408,7 @@ export default function DashboardPage() {
     // 检查是否已经包含端口
     const hasPort = /:\d+$/.test(items[0]);
 
-    let formattedList;
+    let formattedList: AddressItem[];
 
     if (hasPort) {
       // 已经包含完整的 IP:Port 组合，直接使用
@@ -605,7 +421,7 @@ export default function DashboardPage() {
     } else {
       // 只包含IP，需要添加端口
       formattedList = items.map((ip, index) => {
-        let formattedAddress;
+        let formattedAddress: string;
 
         if (ip.includes(":") && !ip.startsWith("[")) {
           formattedAddress = `[${ip}]:${port}`;
@@ -703,324 +519,147 @@ export default function DashboardPage() {
   if (loading) {
     return (
       <div className="px-3 lg:px-6 flex-grow pt-2 lg:pt-4">
-        <div className="flex items-center justify-center h-64">
-          <div className="flex items-center gap-3">
-            <div className="animate-spin h-5 w-5 border-2 border-gray-200 dark:border-gray-700 border-t-gray-600 dark:border-t-gray-300 rounded-full" />
-            <span className="text-default-600">正在加载数据...</span>
-          </div>
-        </div>
+        <PageLoadingState message="正在加载数据..." />
       </div>
     );
   }
 
   return (
-    <div className="px-3 lg:px-6 py-2 lg:py-4">
-      {announcement && announcement.content && (
-        <Card className="mb-4 lg:mb-6 border border-blue-200 dark:border-blue-500/30 bg-gradient-to-r from-blue-50 to-purple-50 dark:from-blue-500/10 dark:to-purple-500/10">
-          <CardBody className="p-4">
-            <div className="flex items-start gap-3">
-              <div className="p-2 bg-blue-100 dark:bg-blue-500/20 rounded-lg flex-shrink-0">
-                <svg
-                  className="w-5 h-5 text-blue-600 dark:text-blue-400"
-                  fill="currentColor"
-                  viewBox="0 0 20 20"
-                >
-                  <path
-                    clipRule="evenodd"
-                    d="M18 10a8 8 0 11-16 0 8 8 0 0116 0zm-7-4a1 1 0 11-2 0 1 1 0 012 0zM9 9a1 1 0 000 2v3a1 1 0 001 1h1a1 1 0 100-2v-3a1 1 0 00-1-1H9z"
-                    fillRule="evenodd"
-                  />
-                </svg>
-              </div>
-              <div className="flex-1 min-w-0">
-                <h3 className="text-sm lg:text-base font-semibold text-blue-900 dark:text-blue-100 mb-1">
-                  公告
-                </h3>
-                <p className="text-xs lg:text-sm text-blue-800 dark:text-blue-200 whitespace-pre-wrap break-words">
-                  {announcement.content}
-                </p>
-              </div>
-            </div>
-          </CardBody>
-        </Card>
-      )}
+    <AnimatedPage className="px-3 lg:px-6 py-2 lg:py-4">
+      {announcement && <AnnouncementBanner announcement={announcement} />}
       <div className="grid grid-cols-2 lg:grid-cols-4 gap-3 lg:gap-4 mb-6 lg:mb-8">
-        <Card className="border border-gray-200 dark:border-default-200 shadow-md hover:shadow-lg transition-shadow">
-          <CardBody className="p-3 lg:p-4">
-            <div className="flex flex-col space-y-2">
-              <div className="flex items-center justify-between">
-                <p className="text-xs lg:text-sm text-default-600 truncate">
-                  总流量
-                </p>
-                <div className="p-1.5 lg:p-2 bg-blue-100 dark:bg-blue-500/20 rounded-lg flex-shrink-0">
-                  <svg
-                    className="w-4 h-4 lg:w-5 lg:h-5 text-blue-600 dark:text-blue-400"
-                    fill="currentColor"
-                    viewBox="0 0 20 20"
-                  >
-                    <path d="M3 4a1 1 0 011-1h12a1 1 0 011 1v2a1 1 0 01-1 1H4a1 1 0 01-1-1V4zM3 10a1 1 0 011-1h6a1 1 0 011 1v6a1 1 0 01-1 1H4a1 1 0 01-1-1v-6zM14 9a1 1 0 00-1 1v6a1 1 0 001 1h2a1 1 0 001-1v-6a1 1 0 00-1-1h-2z" />
-                  </svg>
-                </div>
-              </div>
-              <p className="text-base lg:text-xl font-bold text-foreground truncate">
-                {formatFlow(userInfo.flow, "gb")}
-              </p>
-            </div>
-          </CardBody>
-        </Card>
-
-        <Card className="border border-gray-200 dark:border-default-200 shadow-md hover:shadow-lg transition-shadow">
-          <CardBody className="p-3 lg:p-4">
-            <div className="flex flex-col space-y-2">
-              <div className="flex items-center justify-between">
-                <p className="text-xs lg:text-sm text-default-600 truncate">
-                  已用流量
-                </p>
-                <div className="p-1.5 lg:p-2 bg-green-100 dark:bg-green-500/20 rounded-lg flex-shrink-0">
-                  <svg
-                    className="w-4 h-4 lg:w-5 lg:h-5 text-green-600 dark:text-green-400"
-                    fill="currentColor"
-                    viewBox="0 0 20 20"
-                  >
-                    <path
-                      clipRule="evenodd"
-                      d="M12 7a1 1 0 110-2h5a1 1 0 011 1v5a1 1 0 11-2 0V8.414l-4.293 4.293a1 1 0 01-1.414 0L8 10.414l-4.293 4.293a1 1 0 01-1.414-1.414l5-5a1 1 0 011.414 0L11 10.586 14.586 7H12z"
-                      fillRule="evenodd"
-                    />
-                  </svg>
-                </div>
-              </div>
-              <p className="text-base lg:text-xl font-bold text-foreground truncate">
-                {formatFlow(calculateUserTotalUsedFlow())}
-              </p>
-              <div className="mt-1">
-                {renderProgressBar(
-                  calculateUsagePercentage("flow"),
-                  "sm",
-                  userInfo.flow === 99999,
-                )}
-                <div className="flex items-center justify-between mt-1">
-                  <p className="text-xs text-default-500 truncate">
-                    {userInfo.flow === 99999
-                      ? "无限制"
-                      : `${calculateUsagePercentage("flow").toFixed(1)}%`}
-                  </p>
-                  {userInfo.flowResetTime !== undefined &&
-                    userInfo.flowResetTime !== null && (
-                      <div className="text-xs text-default-500 flex items-center gap-1">
-                        <svg
-                          className="w-3 h-3"
-                          fill="currentColor"
-                          viewBox="0 0 20 20"
-                        >
-                          <path
-                            clipRule="evenodd"
-                            d="M10 18a8 8 0 100-16 8 8 0 000 16zm1-12a1 1 0 10-2 0v4a1 1 0 00.293.707l2.828 2.829a1 1 0 101.415-1.415L11 9.586V6z"
-                            fillRule="evenodd"
-                          />
-                        </svg>
-                        <span className="truncate">
-                          {formatResetTime(userInfo.flowResetTime)}
-                        </span>
-                      </div>
-                    )}
-                </div>
-              </div>
-            </div>
-          </CardBody>
-        </Card>
-
-        <Card className="border border-gray-200 dark:border-default-200 shadow-md hover:shadow-lg transition-shadow">
-          <CardBody className="p-3 lg:p-4">
-            <div className="flex flex-col space-y-2">
-              <div className="flex items-center justify-between">
-                <p className="text-xs lg:text-sm text-default-600 truncate">
-                  转发配额
-                </p>
-                <div className="p-1.5 lg:p-2 bg-purple-100 dark:bg-purple-500/20 rounded-lg flex-shrink-0">
-                  <svg
-                    className="w-4 h-4 lg:w-5 lg:h-5 text-purple-600 dark:text-purple-400"
-                    fill="currentColor"
-                    viewBox="0 0 20 20"
-                  >
-                    <path
-                      clipRule="evenodd"
-                      d="M3 17a1 1 0 011-1h12a1 1 0 110 2H4a1 1 0 01-1-1zm3.293-7.707a1 1 0 011.414 0L9 10.586V3a1 1 0 112 0v7.586l1.293-1.293a1 1 0 111.414 1.414l-3 3a1 1 0 01-1.414 0l-3-3a1 1 0 010-1.414z"
-                      fillRule="evenodd"
-                    />
-                  </svg>
-                </div>
-              </div>
-              <p className="text-base lg:text-xl font-bold text-foreground truncate">
-                {formatNumber(userInfo.num || 0)}
-              </p>
-            </div>
-          </CardBody>
-        </Card>
-
-        <Card className="border border-gray-200 dark:border-default-200 shadow-md hover:shadow-lg transition-shadow">
-          <CardBody className="p-3 lg:p-4">
-            <div className="flex flex-col space-y-2">
-              <div className="flex items-center justify-between">
-                <p className="text-xs lg:text-sm text-default-600 truncate">
-                  已用转发
-                </p>
-                <div className="p-1.5 lg:p-2 bg-orange-100 dark:bg-orange-500/20 rounded-lg flex-shrink-0">
-                  <svg
-                    className="w-4 h-4 lg:w-5 lg:h-5 text-orange-600 dark:text-orange-400"
-                    fill="currentColor"
-                    viewBox="0 0 20 20"
-                  >
-                    <path
-                      clipRule="evenodd"
-                      d="M12.586 4.586a2 2 0 112.828 2.828l-3 3a2 2 0 01-2.828 0 1 1 0 00-1.414 1.414 4 4 0 005.656 0l3-3a4 4 0 00-5.656-5.656l-1.5 1.5a1 1 0 101.414 1.414l1.5-1.5zm-5 5a2 2 0 012.828 0 1 1 0 101.414-1.414 4 4 0 00-5.656 0l-3 3a4 4 0 105.656 5.656l1.5-1.5a1 1 0 10-1.414-1.414l-1.5 1.5a2 2 0 11-2.828-2.828l3-3z"
-                      fillRule="evenodd"
-                    />
-                  </svg>
-                </div>
-              </div>
-              <p className="text-base lg:text-xl font-bold text-foreground truncate">
-                {forwardList.length}
-              </p>
-              <div className="mt-1">
-                {renderProgressBar(
-                  calculateUsagePercentage("forwards"),
-                  "sm",
-                  userInfo.num === 99999,
-                )}
-                <p className="text-xs text-default-500 mt-1 truncate">
-                  {userInfo.num === 99999
-                    ? "无限制"
-                    : `${calculateUsagePercentage("forwards").toFixed(1)}%`}
-                </p>
-              </div>
-            </div>
-          </CardBody>
-        </Card>
-      </div>
-
-      {/* 24小时流量统计图表 */}
-      <Card className="mb-6 lg:mb-8 border border-gray-200 dark:border-default-200 shadow-md">
-        <CardHeader className="pb-3">
-          <div className="flex items-center gap-2">
+        <MetricCard
+          icon={
             <svg
-              className="w-5 h-5 text-primary"
+              aria-hidden="true"
+              className="w-4 h-4 lg:w-5 lg:h-5 text-blue-600 dark:text-blue-400"
               fill="currentColor"
               viewBox="0 0 20 20"
             >
-              <path d="M2 10a8 8 0 018-8v8h8a8 8 0 11-16 0z" />
-              <path d="M12 2.252A8.014 8.014 0 0117.748 8H12V2.252z" />
+              <path d="M3 4a1 1 0 011-1h12a1 1 0 011 1v2a1 1 0 01-1 1H4a1 1 0 01-1-1V4zM3 10a1 1 0 011-1h6a1 1 0 011 1v6a1 1 0 01-1 1H4a1 1 0 01-1-1v-6zM14 9a1 1 0 00-1 1v6a1 1 0 001 1h2a1 1 0 001-1v-6a1 1 0 00-1-1h-2z" />
             </svg>
-            <h2 className="text-lg lg:text-xl font-semibold text-foreground">
-              24小时流量统计
-            </h2>
-          </div>
-        </CardHeader>
-        <CardBody className="pt-0">
-          {statisticsFlows.length === 0 ? (
-            <div className="text-center py-12">
-              <svg
-                className="w-12 h-12 text-default-400 mx-auto mb-4"
-                fill="none"
-                stroke="currentColor"
-                viewBox="0 0 24 24"
-              >
-                <path
-                  d="M9 19v-6a2 2 0 00-2-2H5a2 2 0 00-2 2v6a2 2 0 002 2h2a2 2 0 002-2zm0 0V9a2 2 0 012-2h2a2 2 0 012 2v10m-6 0a2 2 0 002 2h2a2 2 0 002-2m0 0V5a2 2 0 012-2h2a2 2 0 012 2v14a2 2 0 01-2 2h-2a2 2 0 01-2-2z"
-                  strokeLinecap="round"
-                  strokeLinejoin="round"
-                  strokeWidth={1.5}
-                />
-              </svg>
-              <p className="text-default-500">暂无流量统计数据</p>
-            </div>
-          ) : (
-            <div className="space-y-4">
-              {/* 流量趋势图 */}
-              <div className="h-64 lg:h-80 w-full">
-                <ResponsiveContainer height="100%" width="100%">
-                  <LineChart data={processFlowChartData()}>
-                    <CartesianGrid
-                      className="opacity-30"
-                      strokeDasharray="3 3"
-                    />
-                    <XAxis
-                      axisLine={{ stroke: "#e5e7eb", strokeWidth: 1 }}
-                      dataKey="time"
-                      tick={{ fontSize: 12 }}
-                      tickLine={false}
-                    />
-                    <YAxis
-                      axisLine={{ stroke: "#e5e7eb", strokeWidth: 1 }}
-                      tick={{ fontSize: 12 }}
-                      tickFormatter={(value: number | string) => {
-                        const v =
-                          typeof value === "number" ? value : Number(value);
+          }
+          iconClassName="bg-blue-100 dark:bg-blue-500/20"
+          title="总流量"
+          value={formatFlow(userInfo.flow, "gb")}
+        />
 
-                        if (!Number.isFinite(v)) return String(value);
-                        if (v === 0) return "0";
-                        if (v < 1024) return `${v}B`;
-                        if (v < 1024 * 1024) return `${(v / 1024).toFixed(1)}K`;
-                        if (v < 1024 * 1024 * 1024)
-                          return `${(v / (1024 * 1024)).toFixed(1)}M`;
-
-                        return `${(v / (1024 * 1024 * 1024)).toFixed(1)}G`;
-                      }}
-                      tickLine={false}
-                    />
-                    <Tooltip
-                      content={({
-                        active,
-                        payload,
-                        label,
-                      }: {
-                        active?: boolean;
-                        payload?: Array<{ value?: number | string }>;
-                        label?: string | number;
-                      }) => {
-                        if (active && payload && payload.length) {
-                          const firstValue = payload[0]?.value;
-                          const numericValue =
-                            typeof firstValue === "number"
-                              ? firstValue
-                              : Number(firstValue);
-                          const flowValue = Number.isFinite(numericValue)
-                            ? numericValue
-                            : 0;
-
-                          return (
-                            <div className="bg-white dark:bg-default-100 border border-default-200 rounded-lg shadow-lg p-3">
-                              <p className="font-medium text-foreground">{`时间: ${label ?? ""}`}</p>
-                              <p className="text-primary">
-                                {`流量: ${formatFlow(flowValue)}`}
-                              </p>
-                            </div>
-                          );
-                        }
-
-                        return null;
-                      }}
-                    />
-                    <Line
-                      activeDot={{
-                        r: 4,
-                        stroke: "#8b5cf6",
-                        strokeWidth: 2,
-                        fill: "#fff",
-                      }}
-                      dataKey="flow"
-                      dot={false}
-                      stroke="#8b5cf6"
-                      strokeWidth={3}
-                      type="monotone"
-                    />
-                  </LineChart>
-                </ResponsiveContainer>
+        <MetricCard
+          bottomContent={
+            <div className="mt-1">
+              {renderProgressBar(
+                calculateUsagePercentage("flow"),
+                "sm",
+                userInfo.flow === 99999,
+              )}
+              <div className="flex items-center justify-between mt-1">
+                <p className="text-xs text-default-500 truncate">
+                  {userInfo.flow === 99999
+                    ? "无限制"
+                    : `${calculateUsagePercentage("flow").toFixed(1)}%`}
+                </p>
+                {userInfo.flowResetTime !== undefined &&
+                  userInfo.flowResetTime !== null && (
+                    <div className="text-xs text-default-500 flex items-center gap-1">
+                      <svg
+                        aria-hidden="true"
+                        className="w-3 h-3"
+                        fill="currentColor"
+                        viewBox="0 0 20 20"
+                      >
+                        <path
+                          clipRule="evenodd"
+                          d="M10 18a8 8 0 100-16 8 8 0 000 16zm1-12a1 1 0 10-2 0v4a1 1 0 00.293.707l2.828 2.829a1 1 0 101.415-1.415L11 9.586V6z"
+                          fillRule="evenodd"
+                        />
+                      </svg>
+                      <span className="truncate">
+                        {formatResetTime(userInfo.flowResetTime)}
+                      </span>
+                    </div>
+                  )}
               </div>
             </div>
-          )}
-        </CardBody>
-      </Card>
+          }
+          icon={
+            <svg
+              aria-hidden="true"
+              className="w-4 h-4 lg:w-5 lg:h-5 text-green-600 dark:text-green-400"
+              fill="currentColor"
+              viewBox="0 0 20 20"
+            >
+              <path
+                clipRule="evenodd"
+                d="M12 7a1 1 0 110-2h5a1 1 0 011 1v5a1 1 0 11-2 0V8.414l-4.293 4.293a1 1 0 01-1.414 0L8 10.414l-4.293 4.293a1 1 0 01-1.414-1.414l5-5a1 1 0 011.414 0L11 10.586 14.586 7H12z"
+                fillRule="evenodd"
+              />
+            </svg>
+          }
+          iconClassName="bg-green-100 dark:bg-green-500/20"
+          title="已用流量"
+          value={formatFlow(calculateUserTotalUsedFlow())}
+        />
+
+        <MetricCard
+          icon={
+            <svg
+              aria-hidden="true"
+              className="w-4 h-4 lg:w-5 lg:h-5 text-purple-600 dark:text-purple-400"
+              fill="currentColor"
+              viewBox="0 0 20 20"
+            >
+              <path
+                clipRule="evenodd"
+                d="M3 17a1 1 0 011-1h12a1 1 0 110 2H4a1 1 0 01-1-1zm3.293-7.707a1 1 0 011.414 0L9 10.586V3a1 1 0 112 0v7.586l1.293-1.293a1 1 0 111.414 1.414l-3 3a1 1 0 01-1.414 0l-3-3a1 1 0 010-1.414z"
+                fillRule="evenodd"
+              />
+            </svg>
+          }
+          iconClassName="bg-purple-100 dark:bg-purple-500/20"
+          title="转发配额"
+          value={formatNumber(userInfo.num || 0)}
+        />
+
+        <MetricCard
+          bottomContent={
+            <div className="mt-1">
+              {renderProgressBar(
+                calculateUsagePercentage("forwards"),
+                "sm",
+                userInfo.num === 99999,
+              )}
+              <p className="text-xs text-default-500 mt-1 truncate">
+                {userInfo.num === 99999
+                  ? "无限制"
+                  : `${calculateUsagePercentage("forwards").toFixed(1)}%`}
+              </p>
+            </div>
+          }
+          icon={
+            <svg
+              aria-hidden="true"
+              className="w-4 h-4 lg:w-5 lg:h-5 text-orange-600 dark:text-orange-400"
+              fill="currentColor"
+              viewBox="0 0 20 20"
+            >
+              <path
+                clipRule="evenodd"
+                d="M12.586 4.586a2 2 0 112.828 2.828l-3 3a2 2 0 01-2.828 0 1 1 0 00-1.414 1.414 4 4 0 005.656 0l3-3a4 4 0 00-5.656-5.656l-1.5 1.5a1 1 0 101.414 1.414l1.5-1.5zm-5 5a2 2 0 012.828 0 1 1 0 101.414-1.414 4 4 0 00-5.656 0l-3 3a4 4 0 105.656 5.656l1.5-1.5a1 1 0 10-1.414-1.414l-1.5 1.5a2 2 0 11-2.828-2.828l3-3z"
+                fillRule="evenodd"
+              />
+            </svg>
+          }
+          iconClassName="bg-orange-100 dark:bg-orange-500/20"
+          title="已用转发"
+          value={forwardList.length}
+        />
+      </div>
+
+      <FlowChartCard
+        chartData={processFlowChartData()}
+        formatFlow={formatFlow}
+        statisticsFlowsCount={statisticsFlows.length}
+      />
 
       {/* 隧道权限 - 管理员不显示 */}
       {!isAdmin && (
@@ -1028,6 +667,7 @@ export default function DashboardPage() {
           <CardHeader className="pb-3">
             <div className="flex items-center gap-2">
               <svg
+                aria-hidden="true"
                 className="w-5 h-5 text-primary"
                 fill="currentColor"
                 viewBox="0 0 20 20"
@@ -1048,22 +688,7 @@ export default function DashboardPage() {
           </CardHeader>
           <CardBody className="pt-0">
             {userTunnels.length === 0 ? (
-              <div className="text-center py-12">
-                <svg
-                  className="w-12 h-12 text-default-400 mx-auto mb-4"
-                  fill="none"
-                  stroke="currentColor"
-                  viewBox="0 0 24 24"
-                >
-                  <path
-                    d="M20 13V6a2 2 0 00-2-2H6a2 2 0 00-2 2v7m16 0v5a2 2 0 01-2 2H6a2 2 0 01-2-2v-5m16 0h-2.586a1 1 0 00-.707.293l-2.414 2.414a1 1 0 01-.707.293h-3.172a1 1 0 01-.707-.293l-2.414-2.414A1 1 0 006.586 13H4"
-                    strokeLinecap="round"
-                    strokeLinejoin="round"
-                    strokeWidth={1.5}
-                  />
-                </svg>
-                <p className="text-default-500">暂无隧道权限</p>
-              </div>
+              <PageEmptyState className="h-48" message="暂无隧道权限" />
             ) : (
               <div className="space-y-3">
                 {userTunnels.map((tunnel) => {
@@ -1164,6 +789,7 @@ export default function DashboardPage() {
         <CardHeader className="pb-3">
           <div className="flex items-center gap-2">
             <svg
+              aria-hidden="true"
               className="w-5 h-5 text-primary"
               fill="currentColor"
               viewBox="0 0 20 20"
@@ -1186,6 +812,7 @@ export default function DashboardPage() {
           {groupedForwards().length === 0 ? (
             <div className="text-center py-12">
               <svg
+                aria-hidden="true"
                 className="w-12 h-12 text-default-400 mx-auto mb-4"
                 fill="none"
                 stroke="currentColor"
@@ -1324,7 +951,7 @@ export default function DashboardPage() {
           <ModalHeader className="text-base">{addressModalTitle}</ModalHeader>
           <ModalBody className="pb-6">
             <div className="mb-4 text-right">
-              <Button size="sm" onClick={copyAllAddresses}>
+              <Button size="sm" onPress={copyAllAddresses}>
                 复制全部
               </Button>
             </div>
@@ -1342,7 +969,7 @@ export default function DashboardPage() {
                     isLoading={item.copying}
                     size="sm"
                     variant="light"
-                    onClick={() => copyAddress(item)}
+                    onPress={() => copyAddress(item)}
                   >
                     复制
                   </Button>
@@ -1352,6 +979,6 @@ export default function DashboardPage() {
           </ModalBody>
         </ModalContent>
       </Modal>
-    </div>
+    </AnimatedPage>
   );
 }

vite-frontend/src/pages/dashboard/components/announcement-banner.tsx

@@ -0,0 +1,95 @@
+import type { AnnouncementData } from "@/api";
+
+import ReactMarkdown from "react-markdown";
+import rehypeSanitize from "rehype-sanitize";
+import remarkGfm from "remark-gfm";
+
+import { Card, CardBody } from "@/shadcn-bridge/heroui/card";
+
+interface AnnouncementBannerProps {
+  announcement: AnnouncementData;
+}
+
+export const AnnouncementBanner = ({
+  announcement,
+}: AnnouncementBannerProps) => {
+  if (!announcement.content) {
+    return null;
+  }
+
+  return (
+    <Card className="mb-4 lg:mb-6 border border-blue-100 dark:border-blue-500/20 bg-gradient-to-br from-blue-50/80 to-indigo-50/80 dark:from-blue-500/5 dark:to-indigo-500/5 shadow-sm">
+      <CardBody className="p-4 sm:p-5">
+        <div className="flex items-center gap-3.5 sm:gap-4">
+          <div className="w-10 h-10 sm:w-11 sm:h-11 bg-white dark:bg-blue-500/10 rounded-full flex-shrink-0 flex items-center justify-center shadow-sm border border-blue-100 dark:border-blue-500/20">
+            <svg
+              aria-hidden="true"
+              className="w-5 h-5 sm:w-5 sm:h-5 text-blue-500 dark:text-blue-400"
+              fill="currentColor"
+              viewBox="0 0 20 20"
+            >
+              <path
+                clipRule="evenodd"
+                d="M18 10a8 8 0 11-16 0 8 8 0 0116 0zm-7-4a1 1 0 11-2 0 1 1 0 012 0zM9 9a1 1 0 000 2v3a1 1 0 001 1h1a1 1 0 100-2v-3a1 1 0 00-1-1H9z"
+                fillRule="evenodd"
+              />
+            </svg>
+          </div>
+          <div className="flex-1 min-w-0">
+            <h3 className="text-[15px] font-semibold text-blue-900 dark:text-blue-100 tracking-wide mb-1 sm:mb-1.5 mt-1.5">
+              公告
+            </h3>
+            <div className="text-sm text-blue-800/90 dark:text-blue-100/90 break-words leading-relaxed">
+              <ReactMarkdown
+                components={{
+                  p: ({ children }) => (
+                    <p className="mb-2 last:mb-0">{children}</p>
+                  ),
+                  a: ({ children, href }) => (
+                    <a
+                      className="underline decoration-blue-500/70 underline-offset-2 hover:text-blue-700 dark:hover:text-blue-100"
+                      href={href}
+                      rel="noopener noreferrer"
+                      target="_blank"
+                    >
+                      {children}
+                    </a>
+                  ),
+                  ul: ({ children }) => (
+                    <ul className="list-disc pl-5 space-y-1 mb-2 last:mb-0">
+                      {children}
+                    </ul>
+                  ),
+                  ol: ({ children }) => (
+                    <ol className="list-decimal pl-5 space-y-1 mb-2 last:mb-0">
+                      {children}
+                    </ol>
+                  ),
+                  code: ({ children }) => (
+                    <code className="rounded bg-blue-100/80 dark:bg-blue-900/40 px-1 py-0.5 text-[0.92em]">
+                      {children}
+                    </code>
+                  ),
+                  pre: ({ children }) => (
+                    <pre className="mb-2 overflow-x-auto rounded-md bg-blue-100/70 dark:bg-blue-900/40 p-2.5 text-xs leading-relaxed">
+                      {children}
+                    </pre>
+                  ),
+                  blockquote: ({ children }) => (
+                    <blockquote className="mb-2 border-l-2 border-blue-300/80 dark:border-blue-500/60 pl-3 italic">
+                      {children}
+                    </blockquote>
+                  ),
+                }}
+                rehypePlugins={[rehypeSanitize]}
+                remarkPlugins={[remarkGfm]}
+              >
+                {announcement.content}
+              </ReactMarkdown>
+            </div>
+          </div>
+        </div>
+      </CardBody>
+    </Card>
+  );
+};

vite-frontend/src/pages/dashboard/components/flow-chart-card.tsx

@@ -0,0 +1,130 @@
+import {
+  CartesianGrid,
+  Line,
+  LineChart,
+  ResponsiveContainer,
+  Tooltip,
+  XAxis,
+  YAxis,
+} from "recharts";
+
+import { Card, CardBody, CardHeader } from "@/shadcn-bridge/heroui/card";
+import { PageEmptyState } from "@/components/page-state";
+
+interface FlowChartPoint {
+  time: string;
+  flow: number;
+}
+
+interface FlowChartCardProps {
+  statisticsFlowsCount: number;
+  chartData: FlowChartPoint[];
+  formatFlow: (value: number, unit?: string) => string;
+}
+
+export const FlowChartCard = ({
+  statisticsFlowsCount,
+  chartData,
+  formatFlow,
+}: FlowChartCardProps) => {
+  return (
+    <Card className="mb-6 lg:mb-8 border border-gray-200 dark:border-default-200 shadow-md">
+      <CardHeader className="pb-3">
+        <div className="flex items-center gap-2">
+          <svg
+            aria-hidden="true"
+            className="w-5 h-5 text-primary"
+            fill="currentColor"
+            viewBox="0 0 20 20"
+          >
+            <path d="M2 10a8 8 0 018-8v8h8a8 8 0 11-16 0z" />
+            <path d="M12 2.252A8.014 8.014 0 0117.748 8H12V2.252z" />
+          </svg>
+          <h2 className="text-lg lg:text-xl font-semibold text-foreground">
+            24小时流量统计
+          </h2>
+        </div>
+      </CardHeader>
+      <CardBody className="pt-0">
+        {statisticsFlowsCount === 0 ? (
+          <PageEmptyState className="h-48" message="暂无流量统计数据" />
+        ) : (
+          <div className="h-64 lg:h-80 w-full">
+            <ResponsiveContainer height="100%" width="100%">
+              <LineChart data={chartData}>
+                <CartesianGrid className="opacity-30" strokeDasharray="3 3" />
+                <XAxis
+                  axisLine={{ stroke: "#e5e7eb", strokeWidth: 1 }}
+                  dataKey="time"
+                  tick={{ fontSize: 12 }}
+                  tickLine={false}
+                />
+                <YAxis
+                  axisLine={{ stroke: "#e5e7eb", strokeWidth: 1 }}
+                  tick={{ fontSize: 12 }}
+                  tickFormatter={(value: number | string) => {
+                    const v = typeof value === "number" ? value : Number(value);
+
+                    if (!Number.isFinite(v)) return String(value);
+                    if (v === 0) return "0";
+                    if (v < 1024) return `${v}B`;
+                    if (v < 1024 * 1024) return `${(v / 1024).toFixed(1)}K`;
+                    if (v < 1024 * 1024 * 1024)
+                      return `${(v / (1024 * 1024)).toFixed(1)}M`;
+
+                    return `${(v / (1024 * 1024 * 1024)).toFixed(1)}G`;
+                  }}
+                  tickLine={false}
+                />
+                <Tooltip
+                  content={({
+                    active,
+                    payload,
+                    label,
+                  }: {
+                    active?: boolean;
+                    payload?: Array<{ value?: number | string }>;
+                    label?: string | number;
+                  }) => {
+                    if (active && payload && payload.length) {
+                      const firstValue = payload[0]?.value;
+                      const numericValue =
+                        typeof firstValue === "number"
+                          ? firstValue
+                          : Number(firstValue);
+                      const flowValue = Number.isFinite(numericValue)
+                        ? numericValue
+                        : 0;
+
+                      return (
+                        <div className="bg-white dark:bg-default-100 border border-default-200 rounded-lg shadow-lg p-3">
+                          <p className="font-medium text-foreground">{`时间: ${label ?? ""}`}</p>
+                          <p className="text-primary">{`流量: ${formatFlow(flowValue)}`}</p>
+                        </div>
+                      );
+                    }
+
+                    return null;
+                  }}
+                />
+                <Line
+                  activeDot={{
+                    r: 4,
+                    stroke: "#8b5cf6",
+                    strokeWidth: 2,
+                    fill: "#fff",
+                  }}
+                  dataKey="flow"
+                  dot={false}
+                  stroke="#8b5cf6"
+                  strokeWidth={3}
+                  type="monotone"
+                />
+              </LineChart>
+            </ResponsiveContainer>
+          </div>
+        )}
+      </CardBody>
+    </Card>
+  );
+};

vite-frontend/src/pages/dashboard/components/metric-card.tsx

@@ -0,0 +1,42 @@
+import type { ReactNode } from "react";
+
+import { Card, CardBody } from "@/shadcn-bridge/heroui/card";
+
+interface MetricCardProps {
+  title: string;
+  value: string | number;
+  iconClassName: string;
+  icon: ReactNode;
+  bottomContent?: ReactNode;
+}
+
+export const MetricCard = ({
+  title,
+  value,
+  iconClassName,
+  icon,
+  bottomContent,
+}: MetricCardProps) => {
+  return (
+    <Card className="border border-gray-200 dark:border-default-200 shadow-md hover:shadow-lg transition-shadow">
+      <CardBody className="p-3 lg:p-4">
+        <div className="flex flex-col space-y-2">
+          <div className="flex items-center justify-between">
+            <p className="text-xs lg:text-sm text-default-600 truncate">
+              {title}
+            </p>
+            <div
+              className={`p-1.5 lg:p-2 rounded-lg flex-shrink-0 ${iconClassName}`}
+            >
+              {icon}
+            </div>
+          </div>
+          <p className="text-base lg:text-xl font-bold text-foreground truncate">
+            {value}
+          </p>
+          {bottomContent}
+        </div>
+      </CardBody>
+    </Card>
+  );
+};

vite-frontend/src/pages/dashboard/use-dashboard-data.ts

@@ -0,0 +1,257 @@
+import type { ForwardApiItem } from "@/api/types";
+
+import { useEffect, useState } from "react";
+import toast from "react-hot-toast";
+
+import {
+  getAnnouncement,
+  getUserPackageInfo,
+  type AnnouncementData,
+} from "@/api";
+import { getAdminFlag } from "@/utils/session";
+
+export interface DashboardUserInfo {
+  flow: number;
+  inFlow: number;
+  outFlow: number;
+  num: number;
+  expTime?: string | number;
+  flowResetTime?: number;
+}
+
+export interface DashboardUserTunnel {
+  id: number;
+  tunnelId: number;
+  tunnelName: string;
+  flow: number;
+  inFlow: number;
+  outFlow: number;
+  num: number;
+  expTime?: number;
+  flowResetTime?: number;
+  tunnelFlow?: number;
+}
+
+export interface DashboardForward {
+  id: number;
+  name: string;
+  tunnelId: number;
+  tunnelName: string;
+  inIp: string;
+  inPort: number;
+  remoteAddr: string;
+  inFlow: number;
+  outFlow: number;
+}
+
+export interface DashboardStatisticsFlow {
+  id: number;
+  userId: number;
+  flow: number;
+  totalFlow: number;
+  time: string;
+}
+
+interface DashboardDataState {
+  loading: boolean;
+  userInfo: DashboardUserInfo;
+  userTunnels: DashboardUserTunnel[];
+  forwardList: DashboardForward[];
+  statisticsFlows: DashboardStatisticsFlow[];
+  isAdmin: boolean;
+  announcement: AnnouncementData | null;
+}
+
+const checkExpirationNotifications = (
+  userInfo: DashboardUserInfo,
+  tunnels: DashboardUserTunnel[],
+) => {
+  const notificationKey = `expiration-${userInfo.expTime}-${tunnels.map((t) => t.expTime).join(",")}`;
+  const lastNotified = localStorage.getItem("lastNotified");
+
+  if (lastNotified === notificationKey) {
+    return;
+  }
+
+  let hasNotification = false;
+
+  if (userInfo.expTime) {
+    const expDate = new Date(userInfo.expTime);
+    const now = new Date();
+
+    if (!isNaN(expDate.getTime()) && expDate > now) {
+      const diffTime = expDate.getTime() - now.getTime();
+      const diffDays = Math.ceil(diffTime / (1000 * 60 * 60 * 24));
+
+      if (diffDays <= 7 && diffDays > 0) {
+        hasNotification = true;
+        if (diffDays === 1) {
+          toast("账户将于明天过期，请及时续费", {
+            icon: "⚠️",
+            duration: 6000,
+            style: { background: "#f59e0b", color: "#fff" },
+          });
+        } else {
+          toast(`账户将于${diffDays}天后过期，请及时续费`, {
+            icon: "⚠️",
+            duration: 6000,
+            style: { background: "#f59e0b", color: "#fff" },
+          });
+        }
+      } else if (diffDays <= 0) {
+        hasNotification = true;
+        toast("账户已过期，请立即续费", {
+          icon: "⚠️",
+          duration: 8000,
+          style: { background: "#ef4444", color: "#fff" },
+        });
+      }
+    }
+  }
+
+  tunnels.forEach((tunnel) => {
+    if (!tunnel.expTime) {
+      return;
+    }
+
+    const expDate = new Date(tunnel.expTime);
+    const now = new Date();
+
+    if (!isNaN(expDate.getTime()) && expDate > now) {
+      const diffTime = expDate.getTime() - now.getTime();
+      const diffDays = Math.ceil(diffTime / (1000 * 60 * 60 * 24));
+
+      if (diffDays <= 7 && diffDays > 0) {
+        hasNotification = true;
+        if (diffDays === 1) {
+          toast(`隧道"${tunnel.tunnelName}"将于明天过期`, {
+            icon: "⚠️",
+            duration: 5000,
+            style: { background: "#f59e0b", color: "#fff" },
+          });
+        } else {
+          toast(`隧道"${tunnel.tunnelName}"将于${diffDays}天后过期`, {
+            icon: "⚠️",
+            duration: 5000,
+            style: { background: "#f59e0b", color: "#fff" },
+          });
+        }
+      } else if (diffDays <= 0) {
+        hasNotification = true;
+        toast(`隧道"${tunnel.tunnelName}"已过期`, {
+          icon: "⚠️",
+          duration: 6000,
+          style: { background: "#ef4444", color: "#fff" },
+        });
+      }
+    }
+  });
+
+  if (hasNotification) {
+    localStorage.setItem("lastNotified", notificationKey);
+  }
+};
+
+const normalizeForwards = (items: ForwardApiItem[]) => {
+  return (items || []).map((item) => ({
+    ...item,
+    name: item.name || "",
+    tunnelId: item.tunnelId ?? 0,
+    tunnelName: item.tunnelName || "",
+    inIp: item.inIp || "",
+    inPort: item.inPort || 0,
+    remoteAddr: item.remoteAddr || "",
+    inFlow: item.inFlow || 0,
+    outFlow: item.outFlow || 0,
+  }));
+};
+
+const normalizeTunnelPermissions = (items: DashboardUserTunnel[]) => {
+  return (items || []).map((item) => ({
+    ...item,
+    inFlow: item.inFlow ?? 0,
+    outFlow: item.outFlow ?? 0,
+  }));
+};
+
+export const useDashboardData = (): DashboardDataState => {
+  const [loading, setLoading] = useState(true);
+  const [userInfo, setUserInfo] = useState<DashboardUserInfo>(
+    {} as DashboardUserInfo,
+  );
+  const [userTunnels, setUserTunnels] = useState<DashboardUserTunnel[]>([]);
+  const [forwardList, setForwardList] = useState<DashboardForward[]>([]);
+  const [statisticsFlows, setStatisticsFlows] = useState<
+    DashboardStatisticsFlow[]
+  >([]);
+  const [isAdmin, setIsAdmin] = useState(false);
+  const [announcement, setAnnouncement] = useState<AnnouncementData | null>(
+    null,
+  );
+
+  useEffect(() => {
+    const loadAnnouncement = async () => {
+      try {
+        const res = await getAnnouncement();
+
+        if (res.code === 0 && res.data && res.data.enabled === 1) {
+          setAnnouncement(res.data);
+        }
+      } catch (error) {
+        console.error("Failed to load announcement:", error);
+      }
+    };
+
+    const loadPackageData = async () => {
+      setLoading(true);
+      try {
+        const res = await getUserPackageInfo();
+
+        if (res.code === 0) {
+          const data = res.data;
+          const normalizedTunnelPermissions = normalizeTunnelPermissions(
+            data.tunnelPermissions || [],
+          );
+          const normalizedForwards = normalizeForwards(data.forwards || []);
+
+          setUserInfo(data.userInfo || ({} as DashboardUserInfo));
+          setUserTunnels(normalizedTunnelPermissions);
+          setForwardList(normalizedForwards);
+          setStatisticsFlows(data.statisticsFlows || []);
+
+          checkExpirationNotifications(
+            data.userInfo,
+            normalizedTunnelPermissions,
+          );
+        } else {
+          toast.error(res.msg || "获取套餐信息失败");
+        }
+      } catch {
+        toast.error("获取套餐信息失败");
+      } finally {
+        setLoading(false);
+      }
+    };
+
+    setLoading(true);
+    setUserInfo({} as DashboardUserInfo);
+    setUserTunnels([]);
+    setForwardList([]);
+    setStatisticsFlows([]);
+    setIsAdmin(getAdminFlag());
+
+    loadPackageData();
+    loadAnnouncement();
+    localStorage.setItem("e", "/dashboard");
+  }, []);
+
+  return {
+    loading,
+    userInfo,
+    userTunnels,
+    forwardList,
+    statisticsFlows,
+    isAdmin,
+    announcement,
+  };
+};

vite-frontend/src/pages/forward/address.ts

@@ -0,0 +1,133 @@
+export interface ForwardAddressItem {
+  id: number;
+  address: string;
+  copying: boolean;
+}
+
+export type ForwardAddressAction =
+  | { type: "none" }
+  | { type: "copy"; text: string; label: string }
+  | { type: "modal"; title: string; items: ForwardAddressItem[] };
+
+const splitAddressEntries = (value: string): string[] => {
+  return value
+    .split(",")
+    .map((item) => item.trim())
+    .filter((item) => item);
+};
+
+const formatAddressWithPort = (ip: string, port: number): string => {
+  if (ip.includes(":") && !ip.startsWith("[")) {
+    return `[${ip}]:${port}`;
+  }
+
+  return `${ip}:${port}`;
+};
+
+export const formatInAddress = (ipString: string, port: number): string => {
+  if (!ipString) {
+    return "";
+  }
+
+  const items = splitAddressEntries(ipString);
+
+  if (items.length === 0) {
+    return "";
+  }
+
+  const hasPort = /:\d+$/.test(items[0]);
+
+  if (hasPort) {
+    if (items.length === 1) {
+      return items[0];
+    }
+
+    return `${items[0]} (+${items.length - 1}个)`;
+  }
+
+  if (!port) {
+    return "";
+  }
+
+  if (items.length === 1) {
+    return formatAddressWithPort(items[0], port);
+  }
+
+  return `${formatAddressWithPort(items[0], port)} (+${items.length - 1}个)`;
+};
+
+export const formatRemoteAddress = (addressString: string): string => {
+  if (!addressString) {
+    return "";
+  }
+
+  const addresses = splitAddressEntries(addressString);
+
+  if (addresses.length === 0) {
+    return "";
+  }
+
+  if (addresses.length === 1) {
+    return addresses[0];
+  }
+
+  return `${addresses[0]} (+${addresses.length - 1})`;
+};
+
+export const hasMultipleAddresses = (addressString: string): boolean => {
+  if (!addressString) {
+    return false;
+  }
+
+  return splitAddressEntries(addressString).length > 1;
+};
+
+export const resolveForwardAddressAction = (
+  addressString: string,
+  port: number | null,
+  title: string,
+): ForwardAddressAction => {
+  if (!addressString) {
+    return { type: "none" };
+  }
+
+  let addresses: string[];
+
+  if (port !== null) {
+    const items = splitAddressEntries(addressString);
+
+    if (items.length <= 1) {
+      return {
+        type: "copy",
+        text: formatInAddress(addressString, port),
+        label: title,
+      };
+    }
+
+    const hasPort = /:\d+$/.test(items[0]);
+
+    addresses = hasPort
+      ? items
+      : items.map((ip) => formatAddressWithPort(ip, port));
+  } else {
+    addresses = splitAddressEntries(addressString);
+
+    if (addresses.length <= 1) {
+      return {
+        type: "copy",
+        text: addressString,
+        label: title,
+      };
+    }
+  }
+
+  return {
+    type: "modal",
+    title: `${title} (${addresses.length}个)`,
+    items: addresses.map((address, index) => ({
+      id: index,
+      address,
+      copying: false,
+    })),
+  };
+};

vite-frontend/src/pages/forward/batch-actions.ts

@@ -0,0 +1,178 @@
+import type { BatchOperationResult } from "@/api/types";
+
+import {
+  batchChangeTunnel,
+  batchDeleteForwards,
+  batchPauseForwards,
+  batchRedeployForwards,
+  batchResumeForwards,
+} from "@/api";
+import { extractApiErrorMessage } from "@/api/error-message";
+
+export interface ForwardBatchActionOutcome {
+  toastVariant: "success" | "error";
+  toastMessage: string;
+  shouldRefresh: boolean;
+  closeDeleteModal?: boolean;
+  closeChangeTunnelModal?: boolean;
+  resetTargetTunnel?: boolean;
+}
+
+const normalizeBatchResult = (value: unknown): BatchOperationResult => {
+  const raw = (value ?? {}) as Partial<BatchOperationResult>;
+
+  return {
+    successCount: Number(raw.successCount ?? 0),
+    failCount: Number(raw.failCount ?? 0),
+  };
+};
+
+const buildBatchToast = (
+  result: BatchOperationResult,
+  successText: string,
+): Pick<ForwardBatchActionOutcome, "toastVariant" | "toastMessage"> => {
+  if (result.failCount === 0) {
+    return {
+      toastVariant: "success",
+      toastMessage: successText,
+    };
+  }
+
+  return {
+    toastVariant: "error",
+    toastMessage: `成功 ${result.successCount} 项，失败 ${result.failCount} 项`,
+  };
+};
+
+export const executeForwardBatchDelete = async (
+  ids: number[],
+): Promise<ForwardBatchActionOutcome> => {
+  try {
+    const response = await batchDeleteForwards(ids);
+
+    if (response.code !== 0) {
+      return {
+        toastVariant: "error",
+        toastMessage: response.msg || "删除失败",
+        shouldRefresh: false,
+      };
+    }
+
+    const summary = normalizeBatchResult(response.data);
+
+    return {
+      ...buildBatchToast(summary, `成功删除 ${summary.successCount} 项`),
+      shouldRefresh: true,
+      closeDeleteModal: true,
+    };
+  } catch (error) {
+    return {
+      toastVariant: "error",
+      toastMessage: extractApiErrorMessage(error, "删除失败"),
+      shouldRefresh: false,
+    };
+  }
+};
+
+export const executeForwardBatchToggleService = async (
+  ids: number[],
+  enable: boolean,
+): Promise<ForwardBatchActionOutcome> => {
+  const fallback = enable ? "启用失败" : "停用失败";
+
+  try {
+    const response = enable
+      ? await batchResumeForwards(ids)
+      : await batchPauseForwards(ids);
+
+    if (response.code !== 0) {
+      return {
+        toastVariant: "error",
+        toastMessage: response.msg || fallback,
+        shouldRefresh: false,
+      };
+    }
+
+    const summary = normalizeBatchResult(response.data);
+
+    return {
+      ...buildBatchToast(
+        summary,
+        enable
+          ? `成功启用 ${summary.successCount} 项`
+          : `成功停用 ${summary.successCount} 项`,
+      ),
+      shouldRefresh: true,
+    };
+  } catch (error) {
+    return {
+      toastVariant: "error",
+      toastMessage: extractApiErrorMessage(error, fallback),
+      shouldRefresh: false,
+    };
+  }
+};
+
+export const executeForwardBatchRedeploy = async (
+  ids: number[],
+): Promise<ForwardBatchActionOutcome> => {
+  try {
+    const response = await batchRedeployForwards(ids);
+
+    if (response.code !== 0) {
+      return {
+        toastVariant: "error",
+        toastMessage: response.msg || "下发失败",
+        shouldRefresh: false,
+      };
+    }
+
+    const summary = normalizeBatchResult(response.data);
+
+    return {
+      ...buildBatchToast(summary, `成功重新下发 ${summary.successCount} 项`),
+      shouldRefresh: true,
+    };
+  } catch (error) {
+    return {
+      toastVariant: "error",
+      toastMessage: extractApiErrorMessage(error, "下发失败"),
+      shouldRefresh: false,
+    };
+  }
+};
+
+export const executeForwardBatchChangeTunnel = async (
+  ids: number[],
+  targetTunnelId: number,
+): Promise<ForwardBatchActionOutcome> => {
+  try {
+    const response = await batchChangeTunnel({
+      forwardIds: ids,
+      targetTunnelId,
+    });
+
+    if (response.code !== 0) {
+      return {
+        toastVariant: "error",
+        toastMessage: response.msg || "隧道失败",
+        shouldRefresh: false,
+      };
+    }
+
+    const summary = normalizeBatchResult(response.data);
+
+    return {
+      ...buildBatchToast(summary, `成功换隧道 ${summary.successCount} 项`),
+      shouldRefresh: true,
+      closeChangeTunnelModal: true,
+      resetTargetTunnel: true,
+    };
+  } catch (error) {
+    return {
+      toastVariant: "error",
+      toastMessage: extractApiErrorMessage(error, "隧道失败"),
+      shouldRefresh: false,
+    };
+  }
+};

vite-frontend/src/pages/forward/diagnosis.ts

@@ -0,0 +1,88 @@
+export interface ForwardDiagnosisEntry {
+  success: boolean;
+  description: string;
+  nodeName: string;
+  nodeId: string;
+  targetIp: string;
+  targetPort?: number;
+  message?: string;
+  averageTime?: number;
+  packetLoss?: number;
+  fromChainType?: number;
+  fromInx?: number;
+  toChainType?: number;
+  toInx?: number;
+}
+
+export interface ForwardDiagnosisResult {
+  forwardName: string;
+  timestamp: number;
+  results: ForwardDiagnosisEntry[];
+}
+
+export interface ForwardDiagnosisFallbackInput {
+  forwardName: string;
+  remoteAddr: string;
+  description: string;
+  message: string;
+}
+
+const pickPrimaryTargetIp = (remoteAddr: string): string => {
+  return remoteAddr.split(",")[0] || "-";
+};
+
+export const buildForwardDiagnosisFallbackResult = ({
+  forwardName,
+  remoteAddr,
+  description,
+  message,
+}: ForwardDiagnosisFallbackInput): ForwardDiagnosisResult => {
+  return {
+    forwardName,
+    timestamp: Date.now(),
+    results: [
+      {
+        success: false,
+        description,
+        nodeName: "-",
+        nodeId: "-",
+        targetIp: pickPrimaryTargetIp(remoteAddr),
+        message,
+      },
+    ],
+  };
+};
+
+export const getForwardDiagnosisQualityDisplay = (
+  averageTime?: number,
+  packetLoss?: number,
+): {
+  text: string;
+  color: "success" | "primary" | "warning" | "danger";
+} | null => {
+  if (averageTime === undefined || packetLoss === undefined) {
+    return null;
+  }
+
+  if (averageTime < 30 && packetLoss === 0) {
+    return { text: "🚀 优秀", color: "success" };
+  }
+
+  if (averageTime < 50 && packetLoss === 0) {
+    return { text: "✨ 很好", color: "success" };
+  }
+
+  if (averageTime < 100 && packetLoss < 1) {
+    return { text: "👍 良好", color: "primary" };
+  }
+
+  if (averageTime < 150 && packetLoss < 2) {
+    return { text: "😐 一般", color: "warning" };
+  }
+
+  if (averageTime < 200 && packetLoss < 5) {
+    return { text: "😟 较差", color: "warning" };
+  }
+
+  return { text: "😵 很差", color: "danger" };
+};