fix: resolve federation forward card showing zero flow (#212)

## Summary

Fixed federation port-forward tunnels not displaying traffic on forward
cards.

**Root Cause:**
- Frontend's mergeFederationShareFlow only parsed shareId from tunnel
name (Share-{id}-Port-{port} format)
- Federation tunnels with custom names couldn't be resolved, causing
traffic display to show 0

**Fix:**
- Added fallback to resolve shareId via remote-usage bindings[].tunnelId
- Multiple resolution candidates are merged with max(currentFlow)
selection
- Maintains directFlow precedence over federation share flow

**Tests:**
- Added contract test for custom tunnel name with binding-based
resolution
- All existing tests pass
- Frontend builds successfully

Fixes: federation port-forward showing total flow 0

.github/workflows/ci-build.yml

@@ -48,6 +48,43 @@ jobs:
       - name: Build
         run: go build -v ./...
 
+  backend-postgres-contract:
+    name: Go Backend PostgreSQL Contract
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:17
+        env:
+          POSTGRES_USER: flux_test
+          POSTGRES_PASSWORD: flux_test_pass
+          POSTGRES_DB: flux_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U flux_test -d flux_test"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 10
+    defaults:
+      run:
+        working-directory: go-backend
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.23'
+          cache-dependency-path: go-backend/go.sum
+
+      - name: Download dependencies
+        run: go mod download
+
+      - name: Run PostgreSQL contract test
+        env:
+          FLVX_POSTGRES_TEST_DSN: 'postgres://flux_test:flux_test_pass@127.0.0.1:5432/flux_test?sslmode=disable'
+        run: go test ./tests/contract -run TestPostgresNodeCreateRepairsMissingIDDefaultContract -count=1
+
   agent:
     name: Build Agent
     runs-on: ubuntu-latest

.github/workflows/deploy-docs.yml

@@ -0,0 +1,43 @@
+name: Deploy Docs
+on:
+  push:
+    branches:
+      - main
+      - master
+      - beta
+    paths:
+      - 'doc/**'
+      - 'mkdocs.yml'
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
+
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+
+      - name: Install MkDocs and Material Theme
+        run: pip install mkdocs-material
+
+      - name: Build and Deploy
+        run: mkdocs gh-deploy --force

.github/workflows/docker-build.yml

@@ -112,6 +112,12 @@ jobs:
           upx --best --lzma gost-amd64
           upx --best --lzma gost-arm64
 
+      - name: Generate SHA256 checksums
+        working-directory: ./go-gost
+        run: |
+          sha256sum gost-amd64 > gost-amd64.sha256
+          sha256sum gost-arm64 > gost-arm64.sha256
+
       - name: Upload GOST AMD64 artifact
         uses: actions/upload-artifact@v4
         with:
@@ -124,6 +130,18 @@ jobs:
           name: gost-binary-arm64
           path: ./go-gost/gost-arm64
 
+      - name: Upload GOST AMD64 checksum artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: gost-checksum-amd64
+          path: ./go-gost/gost-amd64.sha256
+
+      - name: Upload GOST ARM64 checksum artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: gost-checksum-arm64
+          path: ./go-gost/gost-arm64.sha256
+
   build-vite:
     name: Build & Push Vite Frontend
     needs: check-version
@@ -238,7 +256,20 @@ jobs:
           name: gost-binary-arm64
           path: ./artifacts/arm64
 
+      - name: Download GOST AMD64 checksum
+        uses: actions/download-artifact@v4
+        with:
+          name: gost-checksum-amd64
+          path: ./artifacts/
+
+      - name: Download GOST ARM64 checksum
+        uses: actions/download-artifact@v4
+        with:
+          name: gost-checksum-arm64
+          path: ./artifacts/
+
       - name: Prepare release files
+
         run: |
           VERSION="${{ needs.check-version.outputs.version }}"
           OWNER="${{ needs.check-version.outputs.image_owner }}"
@@ -268,6 +299,10 @@ jobs:
           sed -i "s|2.0.7-beta|${VERSION}|g" ./artifacts/install.sh
           sed -i "s|2.0.7-beta|${VERSION}|g" ./artifacts/panel_install.sh
 
+          # 注入固定版本号，使从 Release 页下载的脚本只安装该版本
+          sed -i "s|^PINNED_VERSION=\"\"|PINNED_VERSION=\"${VERSION}\"|" ./artifacts/install.sh
+          sed -i "s|^PINNED_VERSION=\"\"|PINNED_VERSION=\"${VERSION}\"|" ./artifacts/panel_install.sh
+
       - name: Create Release
         env:
           GH_TOKEN: ${{ github.token }}
@@ -303,14 +338,22 @@ jobs:
 
           ## 🚀 Quick Install
 
-          **Panel:**
+          **Panel (安装此版本 ${VERSION}):**
           \`\`\`bash
           curl -L https://github.com/${{ github.repository }}/releases/download/${VERSION}/panel_install.sh -o panel_install.sh && chmod +x panel_install.sh && ./panel_install.sh
           \`\`\`
 
-          **Node:**
+          **Node (安装此版本 ${VERSION}):**
           \`\`\`bash
           curl -L https://github.com/${{ github.repository }}/releases/download/${VERSION}/install.sh -o install.sh && chmod +x install.sh && ./install.sh
+          \`\`\`
+
+          **安装最新版:**
+          \`\`\`bash
+          # 面板端
+          curl -L https://raw.githubusercontent.com/${{ github.repository }}/main/panel_install.sh -o panel_install.sh && chmod +x panel_install.sh && ./panel_install.sh
+          # 节点端
+          curl -L https://raw.githubusercontent.com/${{ github.repository }}/main/install.sh -o install.sh && chmod +x install.sh && ./install.sh
           \`\`\`" \
             --repo ${{ github.repository }}
 
@@ -319,6 +362,10 @@ jobs:
           gh release upload "${VERSION}" ./artifacts/gost-amd64 --clobber
           gh release upload "${VERSION}" ./artifacts/gost-arm64 --clobber
 
+          echo "📤 上传 GOST 校验文件..."
+          gh release upload "${VERSION}" ./artifacts/gost-amd64.sha256 --clobber
+          gh release upload "${VERSION}" ./artifacts/gost-arm64.sha256 --clobber
+
           echo "📤 上传安装脚本..."
           gh release upload "${VERSION}" ./artifacts/install.sh --clobber
           gh release upload "${VERSION}" ./artifacts/panel_install.sh --clobber
@@ -351,6 +398,18 @@ jobs:
           name: gost-binary-arm64
           path: ./artifacts/arm64
 
+      - name: Download GOST AMD64 checksum
+        uses: actions/download-artifact@v4
+        with:
+          name: gost-checksum-amd64
+          path: ./artifacts/
+
+      - name: Download GOST ARM64 checksum
+        uses: actions/download-artifact@v4
+        with:
+          name: gost-checksum-arm64
+          path: ./artifacts/
+
       - name: Rename binaries
         run: |
           mv ./artifacts/amd64/gost-amd64 ./artifacts/gost-amd64
@@ -367,4 +426,9 @@ jobs:
           gh release upload "${VERSION}" ./artifacts/gost-amd64 --clobber
           gh release upload "${VERSION}" ./artifacts/gost-arm64 --clobber
 
+          echo "📤 上传 GOST 校验文件..."
+          gh release upload "${VERSION}" ./artifacts/gost-amd64.sha256 --clobber
+          gh release upload "${VERSION}" ./artifacts/gost-arm64.sha256 --clobber
+
           echo "✅ GOST 二进制文件更新完成"
+

.gitignore

@@ -176,6 +176,8 @@ build/
 *.so
 *.dylib
 your_app.exe
+go-backend/paneld
+go-gost/gost
 
 # Go 测试二进制文件
 *.test
@@ -257,7 +259,15 @@ gitee/
 doraemon.jks
 device.id
 commit.sh
+.opencode/
+analysis/
 sql/
 !go-backend/internal/store/sqlite/sql/
 !go-backend/internal/store/sqlite/sql/schema.sql
 !go-backend/internal/store/sqlite/sql/data.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

AGENTS.md

@@ -1,21 +1,20 @@
 # PROJECT KNOWLEDGE BASE
 
-**Generated:** Mon Feb 02 2026
-**Commit:** 7ca01ab
-**Branch:** beta
+**Generated:** Thu Feb 19 2026
+**Commit:** 137c34e
+**Branch:** main
+**Tag:** 2.1.4-rc2
 
 ## OVERVIEW
-Flux Panel is a traffic forwarding management system built on a forked GOST v3 stack. It ships as Dockerized Spring Boot (admin API) + 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) + Vite/React UI + Go forwarding agent, with optional mobile WebView wrappers.
 
 ## STRUCTURE
 ```
 ./
 ├── go-gost/               # Go forwarding agent (forked gost + local x/)
 │   └── x/                 # Local fork of github.com/go-gost/x (replace => ./x)
-├── springboot-backend/    # Java/Spring Boot admin API (SQLite/MyBatis)
-├── vite-frontend/         # React/Vite dashboard (HeroUI + Tailwind)
-├── android-app/           # Android WebView wrapper (optional)
-├── ios-app/               # iOS WebView wrapper (optional)
+├── go-backend/            # Go Admin API (GORM + SQLite/PostgreSQL, net/http)
+├── vite-frontend/         # React/Vite dashboard (shadcn bridge + Tailwind v4)
 ├── 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)
@@ -30,20 +29,37 @@ Flux Panel is a traffic forwarding management system built on a forked GOST v3 s
 | **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 entry** | `springboot-backend/src/main/java/com/admin/AdminApplication.java` | Spring Boot app |
-| **Admin API routes** | `springboot-backend/src/main/java/com/admin/controller/` | Mostly `/api/v1/*` controllers |
-| **Admin auth** | `springboot-backend/src/main/java/com/admin/common/interceptor/JwtInterceptor.java` | Checks `Authorization` header |
-| **Web UI routing** | `vite-frontend/src/App.tsx` | React Router v6 + ProtectedRoute/H5 layouts |
-| **Web UI API client** | `vite-frontend/src/api/network.ts` | Axios `baseURL` + `Authorization` header |
-| **Go agent entry** | `go-gost/main.go` | Reads panel `config.json` + starts gost services |
-| **Go x fork** | `go-gost/x/` | Handlers/listeners/dialers + management API |
+| **Admin API** | `go-backend/` | Go Admin API (SQLite) |
+| **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 |
+
+## CODE MAP
+| Symbol | Type | Location | Role |
+|--------|------|----------|------|
+| `flvx` | Project | `.` | Root directory |
+| `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 |
+
 
 ## CONVENTIONS
-- `Authorization` header carries the raw JWT token (no `Bearer` prefix) between `vite-frontend/` and `springboot-backend/`.
-- `go-gost/` uses `replace github.com/go-gost/x => ./x` and `go-gost/x/` is also its own Go module.
+- **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`.
 
 ## 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`.
+- **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`.
+- **DO NOT ADD** `Bearer` prefix to Authorization header - expects raw JWT token.
+- **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.
 
 ## COMMANDS
 ```bash
@@ -56,11 +72,26 @@ docker compose -f docker-compose-v6.yml up -d
 ./install.sh
 
 # Local dev (per subproject)
-(cd springboot-backend && mvn clean package)
+(cd go-backend && make build)
 (cd vite-frontend && npm run dev)
 (cd go-gost && go run .)
 ```
 
+## 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.
+
 ## NOTES
 - LSP servers are not installed in this environment (gopls/jdtls/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.
+- CI uses UPX compression (`--best --lzma`) on Go binaries before release.
+- 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).
+- `analysis/3x-ui/` contains a separate git repo for reference/comparison - not part of FLVX core.
+- PR `#144` (shadcn migration) and PR `#142` (user-group binding) are merged into `main`; release tag `2.1.4-rc2` points to commit `137c34e`.
+- Button visual parity relies on `vite-frontend/src/shadcn-bridge/heroui/button.tsx` color mapping + `vite-frontend/src/styles/tailwind-theme.pcss` token export.

LICENSE

@@ -1,201 +1,674 @@
-                                 Apache License
-                           Version 2.0, January 2004
-                        http://www.apache.org/licenses/
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
 
-   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
 
-   1. Definitions.
+                            Preamble
 
-      "License" shall mean the terms and conditions for use, reproduction,
-      and distribution as defined by Sections 1 through 9 of this document.
+  The GNU General Public License is a free, copyleft license for
+software and other kinds of works.
 
-      "Licensor" shall mean the copyright owner or entity authorized by
-      the copyright owner that is granting the License.
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+the GNU General Public License is intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.  We, the Free Software Foundation, use the
+GNU General Public License for most of our software; it applies also to
+any other work released this way by its authors.  You can apply it to
+your programs, too.
 
-      "Legal Entity" shall mean the union of the acting entity and all
-      other entities that control, are controlled by, or are under common
-      control with that entity. For the purposes of this definition,
-      "control" means (i) the power, direct or indirect, to cause the
-      direction or management of such entity, whether by contract or
-      otherwise, or (ii) ownership of fifty percent (50%) or more of the
-      outstanding shares, or (iii) beneficial ownership of such entity.
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
 
-      "You" (or "Your") shall mean an individual or Legal Entity
-      exercising permissions granted by this License.
+  To protect your rights, we need to prevent others from denying you
+these rights or asking you to surrender the rights.  Therefore, you have
+certain responsibilities if you distribute copies of the software, or if
+you modify it: responsibilities to respect the freedom of others.
 
-      "Source" form shall mean the preferred form for making modifications,
-      including but not limited to software source code, documentation
-      source, and configuration files.
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must pass on to the recipients the same
+freedoms that you received.  You must make sure that they, too, receive
+or can get the source code.  And you must show them these terms so they
+know their rights.
 
-      "Object" form shall mean any form resulting from mechanical
-      transformation or translation of a Source form, including but
-      not limited to compiled object code, generated documentation,
-      and conversions to other media types.
+  Developers that use the GNU GPL protect your rights with two steps:
+(1) assert copyright on the software, and (2) offer you this License
+giving you legal permission to copy, distribute and/or modify it.
 
-      "Work" shall mean the work of authorship, whether in Source or
-      Object form, made available under the License, as indicated by a
-      copyright notice that is included in or attached to the work
-      (an example is provided in the Appendix below).
+  For the developers' and authors' protection, the GPL clearly explains
+that there is no warranty for this free software.  For both users' and
+authors' sake, the GPL requires that modified versions be marked as
+changed, so that their problems will not be attributed erroneously to
+authors of previous versions.
 
-      "Derivative Works" shall mean any work, whether in Source or Object
-      form, that is based on (or derived from) the Work and for which the
-      editorial revisions, annotations, elaborations, or other modifications
-      represent, as a whole, an original work of authorship. For the purposes
-      of this License, Derivative Works shall not include works that remain
-      separable from, or merely link (or bind by name) to the interfaces of,
-      the Work and Derivative Works thereof.
+  Some devices are designed to deny users access to install or run
+modified versions of the software inside them, although the manufacturer
+can do so.  This is fundamentally incompatible with the aim of
+protecting users' freedom to change the software.  The systematic
+pattern of such abuse occurs in the area of products for individuals to
+use, which is precisely where it is most unacceptable.  Therefore, we
+have designed this version of the GPL to prohibit the practice for those
+products.  If such problems arise substantially in other domains, we
+stand ready to extend this provision to those domains in future versions
+of the GPL, as needed to protect the freedom of users.
 
-      "Contribution" shall mean any work of authorship, including
-      the original version of the Work and any modifications or additions
-      to that Work or Derivative Works thereof, that is intentionally
-      submitted to Licensor for inclusion in the Work by the copyright owner
-      or by an individual or Legal Entity authorized to submit on behalf of
-      the copyright owner. For the purposes of this definition, "submitted"
-      means any form of electronic, verbal, or written communication sent
-      to the Licensor or its representatives, including but not limited to
-      communication on electronic mailing lists, source code control systems,
-      and issue tracking systems that are managed by, or on behalf of, the
-      Licensor for the purpose of discussing and improving the Work, but
-      excluding communication that is conspicuously marked or otherwise
-      designated in writing by the copyright owner as "Not a Contribution."
+  Finally, every program is threatened constantly by software patents.
+States should not allow patents to restrict development and use of
+software on general-purpose computers, but in those that do, we wish to
+avoid the special danger that patents applied to a free program could
+make it effectively proprietary.  To prevent this, the GPL assures that
+patents cannot be used to render the program non-free.
 
-      "Contributor" shall mean Licensor and any individual or Legal Entity
-      on behalf of whom a Contribution has been received by Licensor and
-      subsequently incorporated within the Work.
+  The precise terms and conditions for copying, distribution and
+modification follow.
 
-   2. Grant of Copyright License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      copyright license to reproduce, prepare Derivative Works of,
-      publicly display, publicly perform, sublicense, and distribute the
-      Work and such Derivative Works in Source or Object form.
+                       TERMS AND CONDITIONS
 
-   3. Grant of Patent License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      (except as stated in this section) patent license to make, have made,
-      use, offer to sell, sell, import, and otherwise transfer the Work,
-      where such license applies only to those patent claims licensable
-      by such Contributor that are necessarily infringed by their
-      Contribution(s) alone or by combination of their Contribution(s)
-      with the Work to which such Contribution(s) was submitted. If You
-      institute patent litigation against any entity (including a
-      cross-claim or counterclaim in a lawsuit) alleging that the Work
-      or a Contribution incorporated within the Work constitutes direct
-      or contributory patent infringement, then any patent licenses
-      granted to You under this License for that Work shall terminate
-      as of the date such litigation is filed.
+  0. Definitions.
 
-   4. Redistribution. You may reproduce and distribute copies of the
-      Work or Derivative Works thereof in any medium, with or without
-      modifications, and in Source or Object form, provided that You
-      meet the following conditions:
+  "This License" refers to version 3 of the GNU General Public License.
 
-      (a) You must give any other recipients of the Work or
-          Derivative Works a copy of this License; and
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
 
-      (b) You must cause any modified files to carry prominent notices
-          stating that You changed the files; and
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
 
-      (c) You must retain, in the Source form of any Derivative Works
-          that You distribute, all copyright, patent, trademark, and
-          attribution notices from the Source form of the Work,
-          excluding those notices that do not pertain to any part of
-          the Derivative Works; and
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
 
-      (d) If the Work includes a "NOTICE" text file as part of its
-          distribution, then any Derivative Works that You distribute must
-          include a readable copy of the attribution notices contained
-          within such NOTICE file, excluding those notices that do not
-          pertain to any part of the Derivative Works, in at least one
-          of the following places: within a NOTICE text file distributed
-          as part of the Derivative Works; within the Source form or
-          documentation, if provided along with the Derivative Works; or,
-          within a display generated by the Derivative Works, if and
-          wherever such third-party notices normally appear. The contents
-          of the NOTICE file are for informational purposes only and
-          do not modify the License. You may add Your own attribution
-          notices within Derivative Works that You distribute, alongside
-          or as an addendum to the NOTICE text from the Work, provided
-          that such additional attribution notices cannot be construed
-          as modifying the License.
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
 
-      You may add Your own copyright statement to Your modifications and
-      may provide additional or different license terms and conditions
-      for use, reproduction, or distribution of Your modifications, or
-      for any such Derivative Works as a whole, provided Your use,
-      reproduction, and distribution of the Work otherwise complies with
-      the conditions stated in this License.
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
 
-   5. Submission of Contributions. Unless You explicitly state otherwise,
-      any Contribution intentionally submitted for inclusion in the Work
-      by You to the Licensor shall be under the terms and conditions of
-      this License, without any additional terms or conditions.
-      Notwithstanding the above, nothing herein shall supersede or modify
-      the terms of any separate license agreement you may have executed
-      with Licensor regarding such Contributions.
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
 
-   6. Trademarks. This License does not grant permission to use the trade
-      names, trademarks, service marks, or product names of the Licensor,
-      except as required for reasonable and customary use in describing the
-      origin of the Work and reproducing the content of the NOTICE file.
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
 
-   7. Disclaimer of Warranty. Unless required by applicable law or
-      agreed to in writing, Licensor provides the Work (and each
-      Contributor provides its Contributions) on an "AS IS" BASIS,
-      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-      implied, including, without limitation, any warranties or conditions
-      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
-      PARTICULAR PURPOSE. You are solely responsible for determining the
-      appropriateness of using or redistributing the Work and assume any
-      risks associated with Your exercise of permissions under this License.
+  1. Source Code.
 
-   8. Limitation of Liability. In no event and under no legal theory,
-      whether in tort (including negligence), contract, or otherwise,
-      unless required by applicable law (such as deliberate and grossly
-      negligent acts) or agreed to in writing, shall any Contributor be
-      liable to You for damages, including any direct, indirect, special,
-      incidental, or consequential damages of any character arising as a
-      result of this License or out of the use or inability to use the
-      Work (including but not limited to damages for loss of goodwill,
-      work stoppage, computer failure or malfunction, or any and all
-      other commercial damages or losses), even if such Contributor
-      has been advised of the possibility of such damages.
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
 
-   9. Accepting Warranty or Additional Liability. While redistributing
-      the Work or Derivative Works thereof, You may choose to offer,
-      and charge a fee for, acceptance of support, warranty, indemnity,
-      or other liability obligations and/or rights consistent with this
-      License. However, in accepting such obligations, You may act only
-      on Your own behalf and on Your sole responsibility, not on behalf
-      of any other Contributor, and only if You agree to indemnify,
-      defend, and hold each Contributor harmless for any liability
-      incurred by, or claims asserted against, such Contributor by reason
-      of your accepting any such warranty or additional liability.
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
 
-   END OF TERMS AND CONDITIONS
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
 
-   APPENDIX: How to apply the Apache License to your work.
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
 
-      To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "[]"
-      replaced with your own identifying information. (Don't include
-      the brackets!)  The text should be enclosed in the appropriate
-      comment syntax for the file format. We also recommend that a
-      file or class name and description of purpose be included on the
-      same "printed page" as the copyright notice for easier
-      identification within third-party archives.
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
 
-   Copyright [yyyy] [name of copyright owner]
+  The Corresponding Source for a work in source code form is that
+same work.
 
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
+  2. Basic Permissions.
 
-       http://www.apache.org/licenses/LICENSE-2.0
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
 
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer to sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Use with the GNU Affero General Public License.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU Affero General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the special requirements of the GNU Affero General Public License,
+section 13, concerning interaction through a network will apply to the
+combination as such.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If the program does terminal interaction, make it output a short
+notice like this when it starts in an interactive mode:
+
+    <program>  Copyright (C) <year>  <name of author>
+    This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License.  Of course, your program's commands
+might be different; for a GUI interface, you would use an "about box".
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU GPL, see
+<https://www.gnu.org/licenses/>.
+
+  The GNU General Public License does not permit incorporating your program
+into proprietary programs.  If your program is a subroutine library, you
+may consider it more useful to permit linking proprietary applications with
+the library.  If this is what you want to do, use the GNU Lesser General
+Public License instead of this License.  But first, please read
+<https://www.gnu.org/licenses/why-not-lgpl.html>.

LICENSE-APACHE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

NOTICE

@@ -0,0 +1,19 @@
+FLVX
+Copyright 2026 Sagit-chu
+
+This product includes software developed at
+flux-panel (https://github.com/bqlpfy/flux-panel)
+Copyright 2024-2026 bqlpfy
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+-------------------------------------------------------------------------
+This project is a derivative work based on flux-panel.
+Modifications and new components (backend, agents, frontend updates) 
+are licensed under the GNU General Public License v3.0 (GPLv3).
+See the LICENSE file for the full GPLv3 text.
+-------------------------------------------------------------------------

README.md

@@ -1,7 +1,8 @@
-# flux-panel转发面板 哆啦A梦转发面板
+# FLVX
+
+> **联系我们**: [Telegram群组](https://t.me/flvxpanel)
+
 
-本项目基于 [go-gost/gost](https://github.com/go-gost/gost) 和 [go-gost/x](https://github.com/go-gost/x) 两个开源库，实现了转发面板。
----
 ## 特性
 
 - 支持按 **隧道账号级别** 管理流量转发数量，可用于用户/隧道配额控制
@@ -10,12 +11,16 @@
 - 可针对 **指定用户的指定隧道进行限速** 设置
 - 支持配置 **单向或双向流量计费方式**，灵活适配不同计费模型
 - 提供灵活的转发策略配置，适用于多种网络场景
+- 面板分享，支持将节点分享给其他人，面板对接面板
+- 支持分组权限管理，隧道分组、用户分组
+- 支持批量功能，可以批量下发配置，启停等
+- 支持隧道修改配置、转发修改隧道
 
 
 ## 部署流程
 ---
 ### Docker Compose部署
-#### 快速部署
+#### 快速部署（安装最新版）
 面板端：
 ```bash
 curl -L https://raw.githubusercontent.com/Sagit-chu/flux-panel/main/panel_install.sh -o panel_install.sh && chmod +x panel_install.sh && ./panel_install.sh
@@ -25,6 +30,91 @@ curl -L https://raw.githubusercontent.com/Sagit-chu/flux-panel/main/panel_instal
 curl -L https://raw.githubusercontent.com/Sagit-chu/flux-panel/main/install.sh -o install.sh && chmod +x install.sh && ./install.sh
 ```
 
+#### 安装特定版本
+从 [Releases](https://github.com/Sagit-chu/flux-panel/releases) 页面复制对应版本的安装命令，脚本会自动安装该版本而非最新版。
+
+面板端（以 2.1.0 为例）：
+```bash
+curl -L https://github.com/Sagit-chu/flux-panel/releases/download/2.1.0/panel_install.sh -o panel_install.sh && chmod +x panel_install.sh && ./panel_install.sh
+```
+节点端（以 2.1.0 为例）：
+```bash
+curl -L https://github.com/Sagit-chu/flux-panel/releases/download/2.1.0/install.sh -o install.sh && chmod +x install.sh && ./install.sh
+```
+
+#### PostgreSQL 部署（Docker Compose）
+
+安装脚本会根据环境自动下载对应的 Compose 配置并保存为 `docker-compose.yml`。默认仍使用 SQLite，切换到 PostgreSQL 只需要配置环境变量。
+
+1) 在 `docker-compose` 同目录创建或修改 `.env`：
+
+```bash
+JWT_SECRET=replace_with_your_secret
+BACKEND_PORT=6365
+FRONTEND_PORT=6366
+
+DB_TYPE=postgres
+DATABASE_URL=postgres://flux_panel:replace_with_strong_password@postgres:5432/flux_panel?sslmode=disable
+
+POSTGRES_DB=flux_panel
+POSTGRES_USER=flux_panel
+POSTGRES_PASSWORD=replace_with_strong_password
+```
+
+> 📌 使用安装脚本部署时，`POSTGRES_PASSWORD` 会自动随机生成并写入 `.env`。
+
+2) 启动服务：
+
+```bash
+docker compose up -d
+```
+
+3) 如果你想继续使用 SQLite，保留 `DB_TYPE=sqlite`（或不设置 `DB_TYPE`）即可。
+
+#### 从 SQLite 迁移到 PostgreSQL
+
+如果你是通过 `panel_install.sh` 安装面板，推荐直接使用脚本菜单一键迁移：
+
+```bash
+./panel_install.sh
+# 选择 4. 迁移到 PostgreSQL
+```
+
+脚本会自动完成 SQLite 备份、PostgreSQL 启动、`pgloader` 导入、`.env` 中 `DB_TYPE`/`DATABASE_URL` 更新，并重启服务。
+
+如果你希望手动迁移，以下示例基于 Docker Volume `sqlite_data`（项目默认配置）与 `pgloader`：
+
+1) 停止服务并备份 SQLite 数据：
+
+```bash
+docker compose down
+docker run --rm -v sqlite_data:/data -v "$(pwd)":/backup alpine sh -c "cp /data/gost.db /backup/gost.db.bak"
+```
+
+2) 仅启动 PostgreSQL：
+
+```bash
+docker compose up -d postgres
+```
+
+3) 使用 `pgloader` 迁移：
+
+```bash
+source .env
+docker run --rm --network gost-network -v sqlite_data:/sqlite dimitri/pgloader:latest pgloader /sqlite/gost.db "postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}"
+```
+
+4) 切换后端到 PostgreSQL 并启动：
+
+```bash
+source .env
+export DB_TYPE=postgres
+export DATABASE_URL="postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}?sslmode=disable"
+docker compose up -d
+```
+
+5) 迁移完成后，登录面板检查用户、隧道、转发、节点数据是否正确。
+
 #### 默认管理员账号
 
 - **账号**: admin_user
@@ -32,6 +122,38 @@ curl -L https://raw.githubusercontent.com/Sagit-chu/flux-panel/main/install.sh -
 
 > ⚠️ 首次登录后请立即修改默认密码！
 
+---
+## Original Project
+- **Name**: flux-panel
+- **Source**: https://github.com/bqlpfy/flux-panel
+- **License**: Apache License 2.0
+
+## Modifications
+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 (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. 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. Forwarding Stack (Modified)
+- **Modified**: `go-gost/` forwarding agent wrapper.
+- **Modified**: `go-gost/x/` local fork of `github.com/go-gost/x`.
+
+### 4. Mobile Clients (Removed)
+- **Removed**: `android-app/` source code.
+- **Removed**: `ios-app/` source code.
+
+### 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`).
+
+---
+
 
 ## 免责声明
 

doc/faq.md

@@ -0,0 +1,40 @@
+# 常见问题 (FAQ)
+
+### Q1: 安装脚本提示 "Docker command not found"？
+**A**: 请确保您的系统已安装 Docker 和 Docker Compose。
+- Ubuntu/Debian 安装 Docker: `curl -fsSL https://get.docker.com | bash`
+
+### Q2: 面板无法访问 (Connection Refused)？
+**A**:
+1. 检查防火墙是否放行了前端端口（默认 `6366`）。
+2. 检查容器是否正常运行: `docker ps`。
+3. 查看容器日志: `docker logs flux-panel-backend` 或 `docker logs vite-frontend`。
+
+### Q3: 节点显示离线？
+**A**:
+1. 检查节点服务器与面板服务器之间的网络连通性。
+2. 确认在节点端安装时输入的 **面板地址** 和 **密钥** 是否正确。
+3. 检查节点端服务状态: `systemctl status flux_agent`。
+4. 查看节点端日志: `journalctl -u flux_agent -f`。
+
+### Q4: 只有 TCP 能通，UDP 不通？
+**A**: 请检查服务器防火墙和安全组（AWS/阿里云/腾讯云等）是否同时放行了对应端口的 **TCP 和 UDP** 协议。
+
+### Q5: IPv6 无法使用？
+**A**: 面板安装脚本会自动尝试配置 Docker 的 IPv6。如果失败，请手动检查 `/etc/docker/daemon.json` 配置，确保 `ipv6: true` 且分配了正确的 `fixed-cidr-v6` 子网。
+
+### Q6: 如何切换到 PostgreSQL？
+**A**: 在 `.env` 文件中设置 `DB_TYPE=postgres`，并让 `DATABASE_URL` 与 `POSTGRES_*` 保持一致，然后执行 `docker compose up -d` 重启服务即可。使用安装脚本部署时，`POSTGRES_PASSWORD` 会自动随机生成并写入 `.env`。详见 [PostgreSQL 数据库指南](./postgresql.md)。
+
+### Q7: 从 SQLite 迁移到 PostgreSQL 后数据丢失？
+**A**:
+1. 确认迁移前已备份 SQLite 文件（`gost.db.bak`）。
+2. 确认 `pgloader` 命令执行成功，检查其输出是否有报错。
+3. 确认 `.env` 中 `DATABASE_URL` 的密码与 `POSTGRES_PASSWORD` 一致。
+4. 详细迁移步骤参考 [PostgreSQL 数据库指南 - 从 SQLite 迁移](./postgresql.md)。
+
+### Q8: PostgreSQL 容器启动失败？
+**A**:
+1. 检查 `POSTGRES_PASSWORD` 是否已设置（不能为空）。
+2. 查看容器日志：`docker logs flux-panel-postgres`。
+3. 如果是首次启动后修改了密码，需要删除旧的数据卷重新初始化：`docker volume rm postgres_data`。

doc/index.md

@@ -0,0 +1,38 @@
+# FLVX 官方文档
+
+**FLVX** 是一个基于 [go-gost/gost](https://github.com/go-gost/gost) 和 [go-gost/x](https://github.com/go-gost/x) 开发的高性能流量转发管理系统。
+
+> 📞 **联系我们**: [Telegram群组](https://t.me/flvxpanel)
+
+## 核心特性
+
+- **多协议支持**: 完美支持 TCP 和 UDP 协议转发。
+- **灵活转发**: 支持 **端口转发** 与 **隧道转发** 两种模式。
+- **流量控制**: 支持按 **隧道账号级别** 管理流量转发数量，用于用户/隧道配额控制。
+- **限速管理**: 可针对 **指定用户的指定隧道进行限速** 设置。
+- **计费策略**: 支持配置 **单向或双向流量计费方式**，灵活适配不同计费模型。
+- **策略配置**: 提供灵活的转发策略配置，适用于多种网络场景。
+
+## 快速开始
+
+- [安装部署](./install.md)
+- [使用指南](./usage.md)
+- [PostgreSQL 数据库指南](./postgresql.md)
+- [常见问题](./faq.md)
+
+## 免责声明
+
+本项目仅供个人学习与研究使用，基于开源项目进行二次开发。  
+使用本项目所带来的任何风险均由使用者自行承担。本项目为开源的流量转发工具，仅限合法、合规用途。  
+**禁止将本项目用于任何违法或未经授权的行为，包括但不限于网络攻击、数据窃取、非法访问等。**
+
+## 捐赠支持
+
+如果您觉得本项目对您有帮助，欢迎请作者喝杯咖啡！
+
+| 网络       | 地址                                                                 |
+|------------|----------------------------------------------------------------------|
+| BNB(BEP20) | `0xa608708fdc6279a2433fd4b82f0b72b8cbe97ed5`                          |
+| TRC20      | `TM8VYdU3s3gSX5PC8swjAJrAzZFCHKqG2k`                                  |
+| Aptos      | `0x49427bfcba1006a346447430689b2307ac156316bb34850d1d3029ff9d118da5`  |
+| Polygon    | `0xa608708fdc6279a2433fd4b82f0b72b8cbe97ed5`                          |

doc/install.md

@@ -0,0 +1,135 @@
+# 安装部署指南
+
+本文档介绍如何部署 FLVX 面板端及节点端。
+
+## 一、面板端部署
+
+面板端负责管理用户、节点和转发规则。
+
+### 1. 环境要求
+- 操作系统：Linux (推荐 Debian 10+ / Ubuntu 20.04+)
+- 必须安装 Docker 和 Docker Compose
+
+### 2. 一键安装脚本
+
+使用以下命令即可快速安装面板：
+
+```bash
+curl -L https://raw.githubusercontent.com/Sagit-chu/flux-panel/main/panel_install.sh -o panel_install.sh && chmod +x panel_install.sh && ./panel_install.sh
+```
+
+**安装过程中会提示输入以下信息：**
+- **前端端口**: 默认为 `6366`
+- **后端端口**: 默认为 `6365`
+
+脚本会自动检测系统是否支持 IPv6，并自动配置 Docker 的 IPv6 支持。
+
+### 3. 访问面板
+
+安装完成后，访问：
+`http://<服务器IP>:<前端端口>` (默认: `http://<服务器IP>:6366`)
+
+**默认管理员账号：**
+- 用户名: `admin_user`
+- 密码: `admin_user`
+
+> ⚠️ **注意**: 首次登录后，请务必在“个人中心”或“设置”中修改默认密码！
+
+### 4. 维护命令
+
+再次运行 `./panel_install.sh` 脚本可以看到管理菜单：
+1. 安装面板
+2. 更新面板
+3. 卸载面板
+4. 迁移到 PostgreSQL
+5. 退出
+
+---
+
+## 二、节点端部署
+
+节点端运行在实际进行流量转发的服务器上，需要连接到面板端进行管理。
+
+### 1. 获取接入密钥
+1. 登录面板端。
+2. 进入 **节点管理 (Node)** 页面。
+3. 点击 **添加节点**。
+4. 获取该节点的 **接入密钥 (Secret)**。
+
+### 2. 一键安装脚本
+
+在节点服务器上运行：
+
+```bash
+curl -L https://raw.githubusercontent.com/Sagit-chu/flux-panel/main/install.sh -o install.sh && chmod +x install.sh && ./install.sh
+```
+
+**安装过程中会提示输入：**
+- **服务器地址**: 面板端的通信地址（通常是 `http://<面板IP>:<后端端口>`，例如 `http://1.2.3.4:6365`）。
+- **密钥**: 刚才在面板中获取的节点密钥。
+
+或者直接使用带参数的命令（适用于自动化部署）：
+
+```bash
+# 替换 <面板地址> 和 <密钥>
+./install.sh -a "http://1.2.3.4:6365" -s "your_node_secret"
+```
+
+### 3. 验证安装
+安装完成后，服务会自动启动。
+- 查看状态: `systemctl status flux_agent`
+- 回到面板 **节点管理** 页面，该节点状态应显示为 **在线**。
+
+---
+
+## 三、Caddy 反向代理（可选）
+
+如果需要通过域名访问面板并自动获取 HTTPS 证书，可以使用 Caddy 作为反向代理。
+
+### 1. 安装 Caddy
+
+```bash
+# Debian / Ubuntu
+sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl
+curl -1sLf 'https://dl.cloudflare.com/content/v1/e2qwFJ2fRP2b2q/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
+curl -1sLf 'https://dl.cloudflare.com/content/v1/e2qwFJ2fRP2b2q/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
+sudo apt update
+sudo apt install caddy
+```
+
+其他系统请参考 [Caddy 官方安装文档](https://caddyserver.com/docs/install)。
+
+### 2. 配置 Caddyfile
+
+编辑 Caddy 配置文件：
+
+```bash
+sudo nano /etc/caddy/Caddyfile
+```
+
+#### 面板域名配置
+
+将 `panel.example.com` 替换为你自己的域名：
+
+```caddyfile
+panel.example.com {
+    reverse_proxy localhost:6366
+}
+```
+
+Caddy 会自动为域名申请和续期 HTTPS 证书，无需额外配置。
+
+### 3. 重启 Caddy
+
+```bash
+sudo systemctl restart caddy
+```
+
+### 4. 注意事项
+
+- 确保域名已正确解析到服务器 IP。
+- 确保服务器防火墙放行了 **80** 和 **443** 端口（Caddy 自动申请证书需要）。
+- 使用 Caddy 反向代理后，可以在 `.env` 中将前端端口改为仅监听本地，避免直接暴露：
+  ```
+  FRONTEND_PORT=127.0.0.1:6366
+  ```

doc/postgresql.md

@@ -0,0 +1,274 @@
+# PostgreSQL 数据库指南
+
+FLVX 默认使用 SQLite 作为数据库，同时也内置了对 PostgreSQL 的完整支持。本文档介绍如何使用 PostgreSQL 部署面板、从 SQLite 迁移以及日常维护。
+
+## 一、SQLite 与 PostgreSQL 对比
+
+| 特性 | SQLite | PostgreSQL |
+|------|--------|------------|
+| **部署复杂度** | 零配置，开箱即用 | 需要额外的数据库服务 |
+| **并发性能** | 适合小规模单机使用 | 支持高并发读写 |
+| **数据规模** | 适合中小规模数据 | 适合大规模数据 |
+| **备份与恢复** | 直接复制文件 | 支持逻辑备份与物理备份 |
+| **高可用** | 不支持 | 支持主从复制、流复制 |
+
+**建议**：如果你只是个人使用或小团队使用，SQLite 完全够用。如果节点多，推荐使用 PostgreSQL。
+
+---
+
+## 二、环境变量说明
+
+以下环境变量用于配置数据库连接，在 `.env` 文件或 Docker Compose `environment` 中设置。
+
+### 后端服务 (backend) 使用
+
+| 变量名 | 说明 | 默认值 | 示例 |
+|--------|------|--------|------|
+| `DB_TYPE` | 数据库类型，`sqlite` 或 `postgres` | `sqlite` | `postgres` |
+| `DATABASE_URL` | PostgreSQL 连接字符串（仅 `DB_TYPE=postgres` 时必填） | 空 | `postgres://flux_panel:密码@postgres:5432/flux_panel?sslmode=disable` |
+| `DB_PATH` | SQLite 数据库文件路径（仅 `DB_TYPE=sqlite` 时使用） | `/app/data/gost.db` | `/app/data/gost.db` |
+
+### PostgreSQL 容器使用
+
+| 变量名 | 说明 | 默认值 |
+|--------|------|--------|
+| `POSTGRES_DB` | 数据库名称 | `flux_panel` |
+| `POSTGRES_USER` | 数据库用户名 | `flux_panel` |
+| `POSTGRES_PASSWORD` | 数据库密码 | `flux_panel_change_me` |
+
+> ⚠️ **安全提示**：生产环境中请务必修改 `POSTGRES_PASSWORD` 为强密码，不要使用默认值！
+
+---
+
+## 三、全新部署（Docker Compose + PostgreSQL）
+
+安装脚本会根据环境自动下载对应的 Compose 配置并保存为 `docker-compose.yml`。默认使用 SQLite，只需配置环境变量即可切换到 PostgreSQL。
+
+### 1. 创建 `.env` 文件
+
+在 `docker-compose` 同目录创建 `.env` 文件：
+
+```bash
+# 基础配置
+JWT_SECRET=替换为你的密钥
+BACKEND_PORT=6365
+FRONTEND_PORT=6366
+
+# PostgreSQL 配置
+DB_TYPE=postgres
+DATABASE_URL=postgres://flux_panel:替换为强密码@postgres:5432/flux_panel?sslmode=disable
+
+POSTGRES_DB=flux_panel
+POSTGRES_USER=flux_panel
+POSTGRES_PASSWORD=替换为强密码
+```
+
+> ⚠️ `DATABASE_URL` 中的密码必须与 `POSTGRES_PASSWORD` 保持一致。
+
+### 2. 启动服务
+
+```bash
+docker compose up -d
+```
+
+### 3. 验证
+
+```bash
+# 检查所有容器是否正常运行
+docker ps
+
+# 查看后端日志，确认连接 PostgreSQL 成功
+docker logs flux-panel-backend
+
+# 查看 PostgreSQL 容器状态
+docker logs flux-panel-postgres
+```
+
+---
+
+## 四、从 SQLite 迁移到 PostgreSQL
+
+如果你已经在使用 SQLite 并且希望迁移到 PostgreSQL，请按照以下步骤操作。
+
+### 快速方式：脚本菜单一键迁移（推荐）
+
+如果你是通过安装脚本部署面板，可直接执行：
+
+```bash
+./panel_install.sh
+# 选择 4. 迁移到 PostgreSQL
+```
+
+脚本会自动完成以下操作：
+- 备份 SQLite 数据到当前目录（`gost.db.bak`）
+- 启动并等待 PostgreSQL 健康检查通过
+- 使用 `pgloader` 导入 SQLite 数据
+- 自动写入 `.env` 的 `DB_TYPE=postgres` 与 `DATABASE_URL`
+- 重启服务并等待后端健康检查
+
+### 手动方式：按步骤迁移
+
+### 1. 备份 SQLite 数据
+
+```bash
+# 停止所有服务
+docker compose down
+
+# 备份 SQLite 数据文件到当前目录
+docker run --rm -v sqlite_data:/data -v "$(pwd)":/backup alpine sh -c "cp /data/gost.db /backup/gost.db.bak"
+```
+
+### 2. 配置 PostgreSQL 环境变量
+
+在 `.env` 文件中添加 PostgreSQL 配置（参考上方"环境变量说明"）。
+
+### 3. 仅启动 PostgreSQL
+
+```bash
+docker compose up -d postgres
+```
+
+等待 PostgreSQL 完全就绪：
+
+```bash
+# 检查 PostgreSQL 健康状态
+docker inspect --format='{{.State.Health.Status}}' flux-panel-postgres
+# 输出 "healthy" 表示就绪
+```
+
+### 4. 使用 pgloader 迁移数据
+
+```bash
+source .env
+docker run --rm \
+  --network gost-network \
+  -v sqlite_data:/sqlite \
+  dimitri/pgloader:latest \
+  pgloader /sqlite/gost.db "postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}"
+```
+
+> 📌 建议直接从 `.env` 读取 `POSTGRES_USER`、`POSTGRES_PASSWORD`、`POSTGRES_DB`，避免手填密码导致认证失败。
+
+### 5. 启动全部服务
+
+```bash
+source .env
+export DB_TYPE=postgres
+export DATABASE_URL="postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}?sslmode=disable"
+docker compose up -d
+```
+
+### 6. 验证迁移
+
+登录面板后，检查以下数据是否完整：
+- 用户列表和权限
+- 节点信息和状态
+- 隧道配置
+- 转发规则
+- 流量统计数据
+
+---
+
+## 五、独立 PostgreSQL（非 Docker）
+
+如果你不想使用 Docker Compose 中自带的 PostgreSQL 容器，也可以连接外部的 PostgreSQL 实例。
+
+### 1. 准备 PostgreSQL
+
+在目标 PostgreSQL 服务器上创建数据库和用户：
+
+```sql
+CREATE USER flux_panel WITH PASSWORD '你的强密码';
+CREATE DATABASE flux_panel OWNER flux_panel;
+```
+
+### 2. 配置连接
+
+修改 `.env` 文件，将 `DATABASE_URL` 指向外部 PostgreSQL：
+
+```bash
+DB_TYPE=postgres
+DATABASE_URL=postgres://flux_panel:你的强密码@数据库地址:5432/flux_panel?sslmode=disable
+```
+
+> 📌 如果 PostgreSQL 在远程服务器且启用了 SSL，请将 `sslmode=disable` 改为 `sslmode=require` 或 `sslmode=verify-full`。
+
+### 3. 停用内置 PostgreSQL 容器（可选）
+
+如果使用外部 PostgreSQL，可以在启动时不启动内置的 postgres 服务：
+
+```bash
+docker compose up -d backend frontend
+```
+
+---
+
+## 六、数据备份与恢复
+
+### 逻辑备份（pg_dump）
+
+```bash
+# 备份（在 Docker 环境下）
+docker exec flux-panel-postgres pg_dump -U flux_panel flux_panel > backup_$(date +%Y%m%d_%H%M%S).sql
+
+# 恢复
+docker exec -i flux-panel-postgres psql -U flux_panel flux_panel < backup_20260101_120000.sql
+```
+
+### 定时备份（cron）
+
+创建备份脚本 `/opt/flvx/backup.sh`：
+
+```bash
+#!/bin/bash
+BACKUP_DIR="/opt/flvx/backups"
+mkdir -p "$BACKUP_DIR"
+docker exec flux-panel-postgres pg_dump -U flux_panel flux_panel | gzip > "$BACKUP_DIR/flvx_$(date +%Y%m%d_%H%M%S).sql.gz"
+# 清理 30 天前的备份
+find "$BACKUP_DIR" -name "flvx_*.sql.gz" -mtime +30 -delete
+```
+
+添加 cron 任务（每天凌晨 3 点执行）：
+
+```bash
+chmod +x /opt/flvx/backup.sh
+echo "0 3 * * * /opt/flvx/backup.sh" | crontab -
+```
+
+---
+
+## 七、常见问题
+
+### Q: 切换到 PostgreSQL 后启动失败，提示连接被拒绝？
+
+**A**: 
+1. 确认 PostgreSQL 容器已启动并处于 `healthy` 状态：`docker ps`。
+2. 确认 `DATABASE_URL` 中的主机名、端口、用户名、密码正确。
+3. 在 Docker Compose 环境下，主机名应为 `postgres`（服务名），而非 `localhost`。
+
+### Q: pgloader 迁移时报错？
+
+**A**: 
+1. 确认 PostgreSQL 容器已完全就绪（状态为 `healthy`）。
+2. 确认 `--network gost-network` 参数正确，使 pgloader 容器与 PostgreSQL 在同一网络中。
+3. 如果数据库已有表结构，pgloader 可能会报冲突。可以先清空目标数据库后重试。
+
+### Q: 如何查看当前使用的数据库类型？
+
+**A**: 查看后端容器的 `DB_TYPE` 环境变量：
+
+```bash
+docker exec flux-panel-backend printenv DB_TYPE
+```
+
+### Q: 可以同时使用 SQLite 和 PostgreSQL 吗？
+
+**A**: 不可以。`DB_TYPE` 只能设置为 `sqlite` 或 `postgres` 之一。后端启动时根据此配置连接对应的数据库。
+
+### Q: PostgreSQL 数据存储在哪里？
+
+**A**: 在 Docker Compose 部署中，PostgreSQL 数据存储在名为 `postgres_data` 的 Docker Volume 中。可以通过以下命令查看：
+
+```bash
+docker volume inspect postgres_data
+```

doc/usage.md

@@ -0,0 +1,35 @@
+# 使用指南
+
+## 1. 仪表盘 (Dashboard)
+登录系统后首先看到的是仪表盘，这里展示了系统的整体运行状态，包括：
+- 在线节点数量
+- 用户总数
+- 流量统计信息
+
+## 2. 节点管理 (Node)
+节点是实际承载流量转发的服务器。
+- **添加节点**: 点击“添加”，获取密钥用于节点端安装。
+- **管理**: 可以查看节点在线状态、版本信息，以及对节点进行编辑或删除。
+
+## 3. 用户管理 (User)
+管理员可以创建和管理普通用户。
+- **创建用户**: 设置用户名、密码、流量配额等。
+- **用户组**: 可以将用户分配到不同的组 (Group)，便于统一管理权限或策略。
+
+## 4. 转发管理 (Forward)
+这是核心功能区，用于设置端口转发规则。
+- **端口转发**: 将节点服务器的某个端口流量转发到目标地址。
+    - **协议**: 支持 TCP / UDP。
+    - **入口**: 选择入口节点和监听端口。
+    - **出口**: 设置目标 IP 和端口。
+- **隧道转发**: 用于更复杂的网络穿透场景（具体配置视业务需求而定）。
+
+## 5. 限制与策略 (Limit)
+- **限速**: 可以对指定用户或指定隧道进行带宽限制，防止资源滥用。
+- **计费模式**: 支持配置流量计算方式（单向或双向），适合运营场景。
+
+## 6. 系统配置 (Config)
+在此页面进行系统的全局设置。
+
+## 7. 个人设置 (Profile)
+- **修改密码**: 为了安全，建议定期修改管理员密码。

docker-compose-v4.yml

@@ -7,15 +7,17 @@ services:
       driver: json-file
       options:
         max-size: "20m"
+        max-file: "3"
     environment:
+      DB_TYPE: ${DB_TYPE:-sqlite}
       DB_PATH: /app/data/gost.db
+      DATABASE_URL: ${DATABASE_URL:-}
       JWT_SECRET: ${JWT_SECRET}
-      LOG_DIR: /app/logs
       SERVER_ADDR: :6365
+      TZ: Asia/Shanghai
     ports:
       - "${BACKEND_PORT}:6365"
     volumes:
-      - backend_logs:/app/logs
       - sqlite_data:/app/data
     networks:
       - gost-network
@@ -28,6 +30,30 @@ services:
       retries: 5
       start_period: 30s
 
+  postgres:
+    image: postgres:16-alpine
+    container_name: flux-panel-postgres
+    restart: unless-stopped
+    logging:
+      driver: json-file
+      options:
+        max-size: "20m"
+    environment:
+      POSTGRES_DB: ${POSTGRES_DB:-flux_panel}
+      POSTGRES_USER: ${POSTGRES_USER:-flux_panel}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-flux_panel_change_me}
+      TZ: Asia/Shanghai
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    networks:
+      - gost-network
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-flux_panel} -d ${POSTGRES_DB:-flux_panel}"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+      start_period: 20s
+
   frontend:
     image: ghcr.io/sagit-chu/vite-frontend:${FLUX_VERSION:-latest}
     container_name: vite-frontend
@@ -36,6 +62,7 @@ services:
       driver: json-file
       options:
         max-size: "20m"
+        max-file: "3"
     ports:
       - "${FRONTEND_PORT}:80"
     depends_on:
@@ -49,8 +76,8 @@ volumes:
   sqlite_data:
     name: sqlite_data
     driver: local
-  backend_logs:
-    name: backend_logs
+  postgres_data:
+    name: postgres_data
     driver: local
 
 
@@ -60,4 +87,4 @@ networks:
     driver: bridge
     ipam:
       config:
-        - subnet: 172.20.0.0/16 
+        - subnet: 172.80.0.0/16 

docker-compose-v6.yml

@@ -7,15 +7,17 @@ services:
       driver: json-file
       options:
         max-size: "20m"
+        max-file: "3"
     environment:
+      DB_TYPE: ${DB_TYPE:-sqlite}
       DB_PATH: /app/data/gost.db
+      DATABASE_URL: ${DATABASE_URL:-}
       JWT_SECRET: ${JWT_SECRET}
-      LOG_DIR: /app/logs
       SERVER_ADDR: :6365
+      TZ: Asia/Shanghai
     ports:
       - "${BACKEND_PORT}:6365"
     volumes:
-      - backend_logs:/app/logs
       - sqlite_data:/app/data
     networks:
       - gost-network
@@ -28,6 +30,30 @@ services:
       retries: 5
       start_period: 30s
 
+  postgres:
+    image: postgres:16-alpine
+    container_name: flux-panel-postgres
+    restart: unless-stopped
+    logging:
+      driver: json-file
+      options:
+        max-size: "20m"
+    environment:
+      POSTGRES_DB: ${POSTGRES_DB:-flux_panel}
+      POSTGRES_USER: ${POSTGRES_USER:-flux_panel}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-flux_panel_change_me}
+      TZ: Asia/Shanghai
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    networks:
+      - gost-network
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-flux_panel} -d ${POSTGRES_DB:-flux_panel}"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+      start_period: 20s
+
   frontend:
     image: ghcr.io/sagit-chu/vite-frontend:${FLUX_VERSION:-latest}
     container_name: vite-frontend
@@ -36,6 +62,7 @@ services:
       driver: json-file
       options:
         max-size: "20m"
+        max-file: "3"
     ports:
       - "${FRONTEND_PORT}:80"
     depends_on:
@@ -49,8 +76,8 @@ volumes:
   sqlite_data:
     name: sqlite_data
     driver: local
-  backend_logs:
-    name: backend_logs
+  postgres_data:
+    name: postgres_data
     driver: local
 
 
@@ -61,5 +88,5 @@ networks:
     enable_ipv6: true
     ipam:
       config:
-        - subnet: 172.20.0.0/16 
+        - subnet: 172.80.0.0/16 
         - subnet: fd00:dead:beef::/48

go-backend/AGENTS.md

@@ -0,0 +1,63 @@
+# GO BACKEND KNOWLEDGE BASE
+
+## 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).
+
+## STRUCTURE
+```
+go-backend/
+├── cmd/paneld/main.go        # Entry point; starts HTTP server + WebSocket
+├── internal/
+│   ├── http/                 # HTTP layer
+│   │   ├── router.go         # Routes (NewServeMux) + Middleware chain
+│   │   ├── handler/          # API Handlers (User, Tunnel, Node, etc.)
+│   │   ├── middleware/       # JWT, CORS, Logging, Recover
+│   │   └── response/         # JSON response helpers
+│   ├── 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_flow.go      # Flow/forward status queries
+│   │       └── repository_control.go   # Control plane queries
+│   └── auth/                 # Auth logic
+├── tests/                    # Integration/Contract tests
+├── Dockerfile                # Multi-stage build (alpine)
+└── Makefile                  # Build commands
+```
+
+## WHERE TO LOOK
+| Task | Location | Notes |
+|------|----------|-------|
+| **API Routes** | `go-backend/internal/http/router.go` | Registers handlers to `http.ServeMux` |
+| **DB Models** | `go-backend/internal/store/model/model.go` | GORM structs with `TableName()` methods |
+| **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) |
+
+## CONVENTIONS
+- **GORM ORM**: Uses GORM with `glebarez/sqlite` (CGO-free) and `gorm.io/driver/postgres`.
+- **AutoMigrate**: Schema created at startup via `autoMigrateAll()` — no hand-written DDL.
+- **TableName()**: All models define explicit `TableName()` returning singular snake_case names.
+- **Repository Pattern**: Handlers never access `*gorm.DB` directly — all queries go through `repo.Repository` methods.
+- **Standard Lib**: Uses `net/http` for routing (Go 1.22+ patterns).
+- **Auth**: Expects raw JWT in `Authorization` header (no `Bearer` prefix).
+- **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.
+
+## ANTI-PATTERNS
+- **DO NOT** let handlers call `repo.DB()` directly — add a Repository method instead.
+- **DO NOT CHANGE** handler signatures without updating `router.go`.
+- **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
+cd go-backend
+go run ./cmd/paneld       # Default: SERVER_ADDR=:6365
+go test ./...
+make build
+```

go-backend/Dockerfile

@@ -1,11 +1,13 @@
-FROM golang:1.23-bookworm AS builder
+FROM golang:1.24-bookworm AS builder
 WORKDIR /src
 
-COPY go.mod ./
+COPY go.mod go.sum ./
 RUN go mod download
 
 COPY . .
-RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o /out/paneld ./cmd/paneld
+ARG TARGETOS
+ARG TARGETARCH
+RUN CGO_ENABLED=0 GOOS=${TARGETOS:-linux} env ${TARGETARCH:+GOARCH=${TARGETARCH}} go build -o /out/paneld ./cmd/paneld
 
 FROM debian:bookworm-slim
 WORKDIR /app

go-backend/MIGRATION_PLAN.md

@@ -0,0 +1,536 @@
+# 数据库 GORM ORM 迁移计划
+
+**创建时间:** 2026-02-15
+**更新时间:** 2026-02-17 (实施：完成 P1 + P2 + P3 + P5(Repo 查询层 + schema 收尾) + 测试/构建收尾)
+**分支:** main (commit e5e22ba)
+**状态:** 基本完成（保留 4 处 PG 序列修复 DDL `Exec`）
+
+---
+
+## 一、现状分析
+
+### 1.1 迁移前架构 (已归档)
+
+项目原使用 `database/sql` + 手写 raw SQL，通过 `internal/store/db.go` 中的运行时 SQL 重写层实现 SQLite/PostgreSQL 双数据库兼容。
+
+| 组件 | 行数 | 角色 | 当前状态 |
+|------|------|------|----------|
+| `store/db.go` | ~520 | SQL 方言重写层 | **已删除** |
+| `store/sqlite/repository.go` | ~3118 | Repository 查询方法 | **已重写为 store/repo/** |
+| `handler/mutations.go` | ~3748 | Handler 内直接写 raw SQL | **已迁移到 repo（生产 SQL=0）** |
+| `handler/handler.go` | ~1283 | 部分方法用 `repo.DB()` | **大部分已迁移** |
+| `handler/federation.go` | ~若干 | Federation 相关 SQL | **已迁移到 repo** |
+| `handler/control_plane.go` | ~若干 | 控制面相关 SQL | **已迁移到 repo** |
+| `handler/flow_policy.go` | ~若干 | 流量策略相关 SQL | **已迁移到 repo** |
+| `handler/jobs.go` | ~若干 | 后台任务相关 SQL | **已迁移到 repo** |
+| `store/postgres/` | 目录 | PostgreSQL 专用 schema/data | **已删除** |
+
+### 1.2 痛点 (迁移目标)
+
+1. ~~**双 Schema 维护**~~：已通过 AutoMigrate 解决
+2. ~~**SQL 重写层复杂**~~：db.go 已删除
+3. ~~**handler 直接写 SQL**~~：`mutations.go` 生产路径 `tx.Exec`/`tx.Raw` 已清零（测试代码除外）
+4. ~~**无类型安全**~~：repo 业务查询已 GORM 化；剩余 4 处为 PG 序列修复 DDL `Exec`（设计保留）
+5. ~~**模型定义分散**~~：已集中到 model/model.go
+
+---
+
+## 二、方案：引入 GORM ORM（全面重写）
+
+### 2.1 方案变更说明
+
+原计划为 **方案 D（扩展现有 DDL 重写层）**，现变更为 **方案 A（GORM 全面重写）**。
+
+### 2.2 选择 GORM 的理由
+
+1. Go 生态最成熟的 ORM，社区庞大，文档完善
+2. 原生支持 SQLite + PostgreSQL 双数据库，自动处理方言差异
+3. AutoMigrate 消除双 schema 维护，自动处理 AUTOINCREMENT ↔ SERIAL 等
+4. 类型安全的模型定义，编译期检查字段映射
+5. 内置事务管理（closure pattern 自动 rollback/commit）
+6. 自动处理 `"user"` 保留字引号
+
+### 2.3 GORM 驱动选择
+
+| 数据库 | 驱动 | 包 | 备注 |
+|--------|------|-----|------|
+| SQLite | modernc.org/sqlite (CGO-free) | `github.com/glebarez/sqlite` | 纯 Go，无需 CGO |
+| PostgreSQL | pgx/v5 | `gorm.io/driver/postgres` | 默认使用 pgx |
+
+> **注意**：标准 `gorm.io/driver/sqlite` 依赖 CGO，必须使用 `glebarez/sqlite` 包装器。
+
+### 2.4 核心设计原则
+
+1. **Model 集中定义**：所有 GORM Model 在 `internal/store/model/` 包中
+2. **Repository 模式保留**：Repository struct 持有 `*gorm.DB`，对外方法签名尽量不变
+3. **Handler 不直接操作 DB**：所有数据库操作必须封装在 Repository 方法中
+4. **AutoMigrate 替代 schema.sql**：启动时自动迁移，不再维护手写 DDL
+5. **保留 PG 序列修复**：pgloader 迁移场景仍需 `ensurePostgresIDDefaults()`
+6. **Package 重命名**：`store/sqlite` → `store/repo`
+
+---
+
+## 三、Model 设计
+
+### 3.1 GORM 类型映射
+
+| Go 类型 | GORM 行为 | PostgreSQL | SQLite |
+|---------|-----------|------------|--------|
+| `int64` + `primaryKey` | 自增主键 | `bigserial` | `INTEGER PRIMARY KEY AUTOINCREMENT` |
+| `int64` | 64位整数 | `bigint` | `integer` (SQLite 自动 64位) |
+| `int` | 整数 | `integer` | `integer` |
+| `float64` | 浮点 | `double precision` | `real` |
+| `string` + `size:100` | 变长字符 | `varchar(100)` | `varchar(100)` |
+| `string` (无 size) | 文本 | `text` | `text` |
+| `sql.NullInt64` | 可空整数 | `bigint NULL` | `integer NULL` |
+| `sql.NullString` | 可空文本 | `text NULL` | `text NULL` |
+
+### 3.2 表清单（21 张表）
+
+| 表名 | Model | 特殊处理 |
+|------|-------|----------|
+| `user` | `User` | `TableName()` 返回 `"user"` (PG 保留字) |
+| `forward` | `Forward` | |
+| `forward_port` | `ForwardPort` | |
+| `node` | `Node` | |
+| `speed_limit` | `SpeedLimit` | |
+| `statistics_flow` | `StatisticsFlow` | |
+| `tunnel` | `Tunnel` | |
+| `chain_tunnel` | `ChainTunnel` | |
+| `user_tunnel` | `UserTunnel` | 复合唯一索引 (user_id, tunnel_id) |
+| `tunnel_group` | `TunnelGroup` | |
+| `user_group` | `UserGroup` | |
+| `tunnel_group_tunnel` | `TunnelGroupTunnel` | 复合唯一索引 |
+| `user_group_user` | `UserGroupUser` | 复合唯一索引 |
+| `group_permission` | `GroupPermission` | 复合唯一索引 |
+| `group_permission_grant` | `GroupPermissionGrant` | 复合唯一索引 |
+| `vite_config` | `ViteConfig` | name 唯一 |
+| `peer_share` | `PeerShare` | token 唯一 |
+| `peer_share_runtime` | `PeerShareRuntime` | reservation_id, resource_key 唯一 |
+| `federation_tunnel_binding` | `FederationTunnelBinding` | 复合唯一索引 + resource_key 唯一 |
+| `announcement` | `Announcement` | |
+| `schema_version` | `SchemaVersion` | |
+
+---
+
+## 四、详细实施步骤
+
+### 阶段 1：基础设施 — 添加依赖 + 定义 Model ✅ 已完成
+
+| 步骤 | 任务 | 文件 | 状态 |
+|------|------|------|------|
+| 1.1 | `go get gorm.io/gorm gorm.io/driver/postgres github.com/glebarez/sqlite` | `go.mod` | ✅ |
+| 1.2 | 创建 `internal/store/model/model.go`，定义全部 21 个表 Model | 新文件 | ✅ |
+| 1.3 | 为 `user` 表添加 `TableName()` 处理 PG 保留字 | model.go | ✅ |
+| 1.4 | 为复合唯一索引的表添加 GORM 索引 tag | model.go | ✅ |
+| 1.5 | 将 Backup 相关 struct 也迁移到 model/ | model.go | ✅ |
+| 1.6 | 验证 `go build ./...` 编译通过 | - | ✅ |
+
+### 阶段 2：GORM DB 初始化 ✅ 已完成
+
+| 步骤 | 任务 | 文件 | 状态 |
+|------|------|------|------|
+| 2.1 | 修改 Repository struct，`*store.DB` → `*gorm.DB` | repository.go | ✅ |
+| 2.2 | 重写 `Open()` — 用 `glebarez/sqlite` 打开 SQLite | repository.go | ✅ |
+| 2.3 | 重写 `OpenPostgres()` — 用 `gorm.io/driver/postgres` 打开 PG | repository.go | ✅ |
+| 2.4 | 用 `db.AutoMigrate()` 替代 `bootstrapSchema()` | repository.go | ✅ |
+| 2.5 | 实现种子数据逻辑（FirstOrCreate 替代 data.sql） | repository.go | ✅ |
+| 2.6 | 保留并适配 `ensurePostgresIDDefaults()`（用 `db.Exec()`） | repository.go | ✅ |
+| 2.7 | 保留并适配 `migrateSchema()` 增量迁移 | repository.go | ✅ |
+| 2.8 | `DB()` 方法返回 `*gorm.DB` | repository.go | ✅ |
+| 2.9 | SQLite 连接池设置 `MaxOpenConns(1)` 防锁 | repository.go | ✅ |
+
+### 阶段 3：重写 repository 查询方法 ⚠️ ~97% 完成
+
+将所有 raw SQL 查询替换为 GORM 链式调用。
+
+> **2026-02-16 审计**：基础 CRUD 查询已 GORM 化，但 mutation、JOIN 查询、import/export 仍大量使用 raw SQL。
+> **2026-02-17 更新**：已完成 `repository_mutations.go`、Import、以及 `repository_federation/control/flow` 查询层 GORM 化；`repository.go` 中 Raw 已清零，当前仅保留 4 处 PG 序列修复 DDL `Exec`。
+
+| 步骤 | 任务 | 方法数 | 状态 |
+|------|------|--------|------|
+| 3.1 | 用户查询：GetUserByUsername, GetUserByID, UsernameExists* 等 | ~5 | ✅ |
+| 3.2 | 配置查询：GetConfigByName, ListConfigs, UpsertConfig | ~3 | ✅ |
+| 3.3 | 公告查询：GetAnnouncement, UpsertAnnouncement | ~2 | ✅ |
+| 3.4 | 节点查询：GetNodeBy*, ListNodes, UpdateNode* | ~6 | ✅ |
+| 3.5 | 隧道查询：ListTunnels, ListTunnelGroups 等 (含 chain_tunnel 关联) | ~5 | ✅ |
+| 3.6 | 转发查询：ListForwards, resolveForwardIngress | ~3 | ✅ |
+| 3.7 | 用户隧道：GetUserPackageTunnels, GetUserPackageForwards | ~3 | ✅ |
+| 3.8 | 统计/限速：GetStatisticsFlows, ListSpeedLimits, AddFlow | ~4 | ✅ |
+| 3.9 | 分组查询：ListUserGroups, ListGroupPermissions 等 | ~4 | ✅ |
+| 3.10 | PeerShare 全部方法 (CRUD + Runtime) | ~15 | ✅ |
+| 3.11 | FederationTunnelBinding 全部方法 | ~4 | ✅ (Upsert 用 clause.OnConflict) |
+| 3.12 | Export 全部方法 | ~10 | ✅ |
+| 3.13 | Import 全部方法 | ~10 | ✅ 已全部改为 GORM `Clauses(clause.OnConflict)`（见 §9.6） |
+| **3.14** | **repository_mutations.go 全部方法 (~40 个)** | **~40** | **✅ 已全量改为 GORM 链式调用（见 §9.3）** |
+| **3.15** | **repository_federation.go 查询方法** | **~8** | **✅ 已全部改为 GORM 链式调用** |
+| **3.16** | **repository_control.go 复杂查询** | **~5** | **✅ 已全部改为 GORM 链式调用** |
+| **3.17** | **repository_flow.go 查询方法** | **~5** | **✅ 已全部改为 GORM 链式调用** |
+| **3.18** | **Jobs 查询方法 (repository.go 尾部)** | **~8** | **✅ 已 GORM 化** |
+
+### 阶段 4：消除 handler 中直接 SQL — 提取为 Repository 方法 ✅ 已完成
+
+> **2026-02-16 审计**：handler 中的 SQL 已大部分提取到 repo 层，但这些 repo 方法本身仍使用 raw SQL（见阶段 3）。
+> **2026-02-17 更新**：`mutations.go` 直接 `tx.Exec`/`tx.Raw` 已从 27 处降至 0 处（生产代码），详见 §9.4。
+
+mutations.go 和其他 handler 文件中大量直接操作 `h.repo.DB()` 执行 raw SQL，需要：
+1. 将 SQL 逻辑提取为 Repository 方法
+2. Handler 只调用 Repository 方法
+
+| 步骤 | 任务 | 文件 | 状态 |
+|------|------|------|------|
+| 4.1 | 用户 CRUD：userCreate, userUpdate, userDelete, userResetFlow | mutations.go | ✅ 已提取到 repo 方法 |
+| 4.2 | 节点 CRUD：nodeCreate, nodeUpdate, nodeDelete, nodeBatch* | mutations.go | ✅ 已提取到 repo 方法 |
+| 4.3 | 隧道 CRUD：tunnelCreate, tunnelUpdate, tunnelDelete, tunnelBatch* | mutations.go | ✅ tunnelCreate/Update 的 SQL 已下沉 repo |
+| 4.4 | 转发 CRUD：forwardCreate, forwardUpdate, forwardDelete, forwardBatch* | mutations.go | ✅ 已提取到 repo (CreateForwardTx 等) |
+| 4.5 | 限速 CRUD：speedLimitCreate, speedLimitUpdate, speedLimitDelete | mutations.go | ✅ 已提取到 repo 方法 |
+| 4.6 | 分组 CRUD：所有 group* 方法 | mutations.go | ✅ 成员同步/权限管理 SQL 已下沉 repo |
+| 4.7 | 用户隧道：userTunnelAssign, userTunnelRemove, userTunnelUpdate | mutations.go | ✅ 已提取到 repo 方法 |
+| 4.8 | handler.go 中的直接 SQL (openAPISubStore 等) | handler.go | ✅ 已迁移（含 nil 检查清理） |
+| 4.9 | federation.go 中的 raw SQL | federation.go | ✅ 已提取到 repo_federation.go |
+| 4.10 | control_plane.go 中的 raw SQL | control_plane.go | ✅ 已提取到 repo_control.go |
+| 4.11 | flow_policy.go 中的 raw SQL | flow_policy.go | ✅ 已提取到 repo_flow.go |
+| 4.12 | jobs.go 中的 raw SQL | jobs.go | ✅ 已提取到 repo 方法（含 nil 检查清理） |
+
+### 阶段 5：清理旧代码 ✅ 已完成
+
+| 步骤 | 任务 | 文件 | 状态 |
+|------|------|------|------|
+| 5.1 | 删除 `internal/store/postgres/` 整个目录 | 目录删除 | ✅ |
+| 5.2 | 删除 `internal/store/sqlite/sql/` 目录 | 目录删除 | ✅ |
+| 5.3 | 删除 `internal/store/db.go` SQL 重写层 | 文件删除 | ✅ |
+| 5.4 | 删除 `internal/store/db_test.go` | 文件删除 | ✅ |
+| 5.5 | 清理 repository.go 中不再需要的 embed 指令 | 清理 | ✅ |
+
+### 阶段 6：Package 重命名 ✅ 已完成
+
+| 步骤 | 任务 | 文件 | 状态 |
+|------|------|------|------|
+| 6.1 | `internal/store/sqlite/` → `internal/store/repo/` | 目录重命名 | ✅ |
+| 6.2 | 更新所有 import 路径：`store/sqlite` → `store/repo` (13处) | 全局替换 | ✅ |
+
+### 阶段 7：测试 + 验证 ⚠️ 部分完成
+
+| 步骤 | 任务 | 状态 |
+|------|------|------|
+| 7.1 | 更新所有现有测试适配 GORM | ✅ 测试已适配 (使用 repo.DB() 做数据准备) |
+| 7.2 | `go test ./...` 全部通过 | ✅ 已通过（含 `internal/http/handler`、`tests/contract`） |
+| 7.3 | `make build` 构建成功 | ✅ 已通过 |
+
+### 阶段 8：文档更新 ✅ 已完成
+
+| 步骤 | 任务 | 文件 | 状态 |
+|------|------|------|------|
+| 8.1 | 更新 `go-backend/AGENTS.md` — 移除 "DO NOT USE ORM"，记录 GORM 规范 | AGENTS.md | ✅ |
+| 8.2 | 更新根 `AGENTS.md` | AGENTS.md | ✅ |
+| 8.3 | 更新 `handler/AGENTS.md` | AGENTS.md | ✅ |
+
+---
+
+## 五、GORM 使用规范
+
+### 5.1 查询模式
+
+```go
+// 单条查询 - 未找到返回 nil, nil (保持现有语义)
+var user model.User
+err := r.db.Where("id = ?", id).First(&user).Error
+if errors.Is(err, gorm.ErrRecordNotFound) {
+    return nil, nil
+}
+
+// 列表查询
+var users []model.User
+err := r.db.Where("role_id != ?", 0).Order("id ASC").Find(&users).Error
+
+// 创建
+err := r.db.Create(&user).Error
+
+// 更新 (部分字段)
+err := r.db.Model(&model.User{}).Where("id = ?", id).Updates(map[string]interface{}{
+    "user": username, "flow": flow, "updated_time": now,
+}).Error
+
+// 事务 (closure pattern - 自动 rollback/commit)
+err := r.db.Transaction(func(tx *gorm.DB) error {
+    if err := tx.Where("user_id = ?", id).Delete(&model.Forward{}).Error; err != nil {
+        return err
+    }
+    return tx.Where("id = ?", id).Delete(&model.User{}).Error
+})
+
+// 原生 SQL (仅用于复杂查询和 PG 特有操作)
+r.db.Exec("SELECT setval(?::regclass, ?, ?)", seqRef, maxID, true)
+```
+
+### 5.2 关键注意事项
+
+1. **user 保留字**：通过 `TableName()` 返回 `"user"`，GORM 自动处理引号
+2. **SQLite MaxOpenConns**：必须设为 1 防止 "database locked"
+3. **SQLite WAL 模式**：DSN 中配置 `_pragma=journal_mode(WAL)`
+4. **不要用 `type:jsonb`**：SQLite 不支持，用 `serializer:json`
+5. **不要用 `type:serial`**：让 GORM 从 `primaryKey` 自动推断
+6. **AutoMigrate 在 SQLite 中使用 copy-swap-drop**：大表慎用
+
+---
+
+## 六、影响范围
+
+### 需要修改的文件
+
+| 文件 | 修改类型 | 描述 | 当前状态 |
+|------|----------|------|----------|
+| `go.mod` / `go.sum` | 修改 | 添加 GORM + 驱动依赖 | ✅ |
+| `internal/store/model/model.go` | **新增** | 全部 21 个 GORM Model | ✅ |
+| `internal/store/repo/repository.go` | **重写** | 全部查询 GORM 化 | ⚠️ 业务查询已 GORM；仅剩 PG 序列修复 DDL `Exec` 4 处 |
+| `internal/store/repo/repository_mutations.go` | **重写** | Mutation helpers | ✅ 全量 GORM（Raw=0） |
+| `internal/store/repo/repository_federation.go` | **重写** | Federation 查询 | ✅ 已 GORM 化（Raw=0） |
+| `internal/store/repo/repository_control.go` | **重写** | 控制面查询 | ✅ 已 GORM 化（Raw=0） |
+| `internal/store/repo/repository_flow.go` | **重写** | 流量/转发查询 | ✅ 已 GORM 化（Raw=0） |
+| `internal/http/handler/mutations.go` | **重写** | 全部 CRUD 提取到 repo | ✅ 生产代码 `tx.Exec/tx.Raw` = 0 |
+| `internal/http/handler/handler.go` | 修改 | 更新 import、移除直接 SQL | ✅ (仅剩 nil check) |
+| `internal/http/handler/federation.go` | 修改 | GORM 替代 raw SQL | ✅ |
+| `internal/http/handler/control_plane.go` | 修改 | GORM 替代 raw SQL | ✅ |
+| `internal/http/handler/flow_policy.go` | 修改 | GORM 替代 raw SQL | ✅ |
+| `internal/http/handler/jobs.go` | 修改 | GORM 替代 raw SQL | ✅ (仅剩 nil check) |
+| `internal/ws/server.go` | 修改 | 更新 import | ✅ |
+| `internal/app/app.go` | 修改 | 更新 import | ✅ |
+| `internal/store/postgres/` | **删除** | 不再需要 | ✅ |
+| `internal/store/db.go` | **删除** | GORM 自动处理方言 | ✅ |
+| `internal/store/db_test.go` | **删除** | 旧重写层测试 | ✅ |
+| `internal/store/sqlite/sql/` | **删除** | AutoMigrate 替代 | ✅ |
+| `tests/contract/*.go` | 修改 | 适配 GORM | ✅ |
+| `AGENTS.md` (3处) | 更新 | 反映新架构 | ✅ |
+
+### 不需要修改的文件
+
+- `internal/http/router.go` — 路由不变
+- `internal/config/config.go` — 配置不变
+- `internal/auth/` — 认证不变
+- `internal/security/` — 加密不变
+- `internal/http/middleware/` — 中间件不变
+- `internal/http/response/` — 响应格式不变
+- `Dockerfile`, `Makefile` — 构建不变
+
+---
+
+## 七、风险与缓解
+
+| 风险 | 可能性 | 影响 | 缓解措施 |
+|------|--------|------|----------|
+| GORM AutoMigrate SQLite/PG 行为差异 | 中 | 高 | 先写 Model 验证双数据库 AutoMigrate |
+| handler 中散落 raw SQL 遗漏 | 中 | 高 | 全局搜索 `.Exec(`, `.Query(`, `.QueryRow(` |
+| 事务语义变化 | 低 | 中 | 逐方法对比旧代码事务边界 |
+| 大量代码变更导致回归 | 高 | 高 | 分阶段提交，每阶段 `go test` |
+| GORM 性能开销 | 低 | 低 | 此场景下可忽略 |
+| SQLite "database locked" | 中 | 高 | `MaxOpenConns(1)` + WAL 模式 |
+
+---
+
+## 八、迁移顺序原则
+
+1. **先 Model 后查询**：确保 AutoMigrate 双数据库通过
+2. **先 Repository 后 Handler**：Handler 依赖 Repository
+3. **先核心后边缘**：User → Node → Tunnel → Forward → 分组 → Federation
+4. **每步编译**：每完成一组方法确保 `go build ./...` 通过
+5. **最后清理**：全部重写完成后再删除旧代码和重命名 package
+
+---
+
+---
+
+## 九、2026-02-16 审计发现 + 2026-02-17 进展记录
+
+### 9.1 总体完成度
+
+| 指标 | 数值 |
+|------|------|
+| 阶段完成数 | 7/8 完成 (1, 2, 4, 5, 6, 7, 8)，1/8 部分完成 (3) |
+| GORM 链式调用 | ~226 处 |
+| Raw SQL 调用 (`.Exec`/`.Raw`+`.Scan`) | 4 处（生产代码） |
+| GORM 占比 | ~98% |
+| Handler 内 `tx.Exec`/`tx.Raw` | 0 处（生产代码） |
+| `last_insert_rowid()` 生产代码 | 0 处（已消灭） |
+
+### 9.2 ✅ P0：`last_insert_rowid()`（生产代码）已清零
+
+`last_insert_rowid()` 已从生产路径移除，创建主键统一改为 `Create(&model)` 自动回填 ID，
+确保 SQLite / PostgreSQL 双数据库行为一致。
+
+> 备注：测试代码中的历史 SQL 兼容性用例可在后续测试清理阶段单独处理。
+
+### 9.3 ✅ P1：`repository_mutations.go` 已全量 GORM 化
+
+本次已完成 `repository_mutations.go` 的集中清理：
+
+1. User / Node / Tunnel / Forward / UserTunnel / SpeedLimit / Group / Permission 全部 mutation 方法改为 GORM 链式调用。
+2. 事务内级联删除统一为 `tx.Where(...).Delete(&Model{})` 模式。
+3. `ON CONFLICT DO NOTHING` 统一替换为 `Clauses(clause.OnConflict{DoNothing: true})`。
+4. 保留原有调用语义（含 `sql.ErrNoRows` 行为兼容）并完成 `go build ./...` 验证。
+
+> 当前 `repository_mutations.go` 中生产代码 `.Raw(`/`.Exec(` 调用已降为 0。
+
+### 9.4 ✅ P2：Handler `mutations.go` 直接 SQL 已清零
+
+2026-02-17 本轮静态扫描结果：`mutations.go` **0 处** `tx.Exec`/`tx.Raw`（生产代码）。
+
+本轮完成下沉到 repo 的逻辑：
+
+- `tunnelUpdate` 中 `UPDATE tunnel` + `DELETE chain_tunnel`
+- `isRemoteNodeTx` 查询
+- `pickNodePortTx` 的 node/chain_tunnel/forward_port 端口占用查询
+- `replaceTunnelChainsTx` 的 chain_tunnel 写入
+- 分组成员同步（`tunnel_group_tunnel` / `user_group_user`）
+- 权限删除与 grant 回收（`group_permission` / `group_permission_grant` / `user_tunnel`）
+- federation 绑定替换（`federation_tunnel_binding`）
+
+### 9.5 ✅ P3（部分）：已移除 `QueryInt64List` / `QueryPairs` SQL 透传
+
+- `repository_mutations.go` 中两个 SQL 透传入口已删除。
+- Handler 已切换为语义化 repo 方法：
+  - `ListUserIDsByUserGroup`
+  - `ListTunnelIDsByTunnelGroup`
+  - `ListGroupPermissionPairsByUserGroup`
+  - `ListGroupPermissionPairsByTunnelGroup`
+
+### 9.6 ✅ P3：Import 函数已全部 GORM 化
+
+`repository.go` 中 Import 相关函数已完成迁移：
+
+- `importUsers`
+- `importNodes`
+- `importTunnels`（含 `chain_tunnel` 子项 upsert）
+- `importForwards`（含 `forward_port` 覆盖写入）
+- `importUserTunnels`
+- `importSpeedLimits`
+- `importTunnelGroups`
+- `importUserGroups`
+- `importPermissions`
+- `importConfigs`（原本已是 GORM）
+
+迁移后统一采用 `Clauses(clause.OnConflict{Columns: id/name, DoUpdates: ...}).Create(&model)` 模式，
+保留原 `ON CONFLICT ... DO UPDATE` 语义；Import 区段 `tx.Exec`/`tx.Raw` 已清零。
+
+### 9.7 ✅ P4：`h.repo.DB() == nil` 检查已清理
+
+`internal/http/handler/` 下已无 `h.repo.DB()` 直接访问；handler 仅通过语义化 repo 方法进行数据访问。
+
+### 9.8 ✅ P5：Repository 层 Raw 已收敛（仅保留 PG 序列修复 DDL）
+
+当前生产代码中 `.Raw()` 已清零；仅剩 `repository.go` 的 4 处 `Exec()`，全部位于 PG 序列修复 DDL：
+
+- `CREATE SEQUENCE IF NOT EXISTS ...`
+- `ALTER TABLE ... ALTER COLUMN id SET DEFAULT nextval(...)`
+- `ALTER SEQUENCE ... OWNED BY ...`
+- `SELECT setval(...::regclass, ?, ?)`
+
+以上 4 处属于数据库管理 DDL/序列同步语义，当前保留，不再继续向 GORM 链式调用替换。
+
+`repository_federation.go` / `repository_control.go` / `repository_flow.go` 已完成 GORM 化（Raw=0）。
+
+---
+
+## 十、后续工作优先级
+
+| 优先级 | 任务 | 影响范围 | 工作量 |
+|--------|------|----------|--------|
+| **P0** | ✅ 已完成：生产代码中 `last_insert_rowid()` 清零（测试用例待单独清理） | 6 处生产（已完成） | 完成 |
+| **P1** | ✅ 已完成：`repository_mutations.go` ~40 方法改为 GORM 链式调用 | 659 行（已完成） | 完成 |
+| **P2** | ✅ 已完成：`mutations.go` handler 直接 SQL 全部提取为 repo 方法 | mutations.go | 完成 |
+| **P3** | ✅ 已完成：移除 `QueryInt64List`/`QueryPairs` 透传，切换语义化 repo 方法 | 2 个方法 + 调用方（已完成） | 完成 |
+| **P3** | ✅ 已完成：Import 函数 Raw SQL 改为 GORM `Clauses(clause.OnConflict{}).Create()` | 9 个函数（已完成） | 完成 |
+| **P4** | ✅ 已完成：`h.repo.DB() == nil` 检查清理完毕 | 4 处（已完成） | 完成 |
+| **P5** | ✅ 已完成：repo 查询层 Raw 清零，`repository.go` 保留 4 处 PG 序列修复 DDL `Exec`（设计保留） | repository.go | 完成 |
+| **P5** | ✅ 已完成：更新 MIGRATION_PLAN.md 状态标记与收尾记录 | 本文件 | 完成 |
+
+### 10.5 本轮执行记录（2026-02-17，P5 schema 收尾）
+
+1. 完成 `repository.go` schema 迁移段去 Raw：
+   - `normalizeStrategy` 改为 `Model(...).Where(...).Update(...)`
+   - `ensurePostgresIDDefaults`/`ensurePostgresTableIDDefault` 的 information_schema 查询改为 GORM `Table+Joins+Where+Scan`
+   - `syncPostgresTableIDSequence` 的 `MAX(id)` 查询改为 GORM `Table+Select+Scan`
+2. 复扫结果：
+   - `repository.go` `.Raw()` = 0
+   - repo 生产路径剩余 `.Exec()` = 4（全部为 PG 序列修复 DDL）
+3. 验证结果：
+   - `go build ./...` ✅
+   - `go test ./internal/store/repo/...` ✅
+
+### 10.6 本轮执行记录（2026-02-17，测试/构建收尾）
+
+1. 修复事务内 SQLite 连接阻塞（`MaxOpenConns(1)` 场景）：
+   - 新增 `GetNodeRecordTx` 并在 `prepareTunnelCreateState` 使用事务句柄读取节点。
+   - 新增 `GetNodeRemoteFieldsTx` 并在 `tunnelCreate` 事务内改用事务句柄读取远端字段。
+   - `applyFederationRuntime` 改为显式接收 `localDomain`，避免事务内再次走 `repo.GetConfigByName`。
+2. 修复 legacy SQLite schema 迁移契约：
+   - 新增 `prepareSQLiteLegacyColumns` 预补齐 `node/tunnel` 关键列。
+   - SQLite 模式下对已存在 `node/tunnel` 表跳过对应 `AutoMigrate` 重建流程，避免 `node__temp.name` 约束失败。
+3. 验证结果：
+   - `go test ./internal/http/handler/...` ✅
+   - `go test ./tests/contract/...` ✅
+   - `go test ./...` ✅
+   - `go build ./...` ✅
+   - `make build` ✅
+
+### 10.1 本轮执行记录（2026-02-17，P5 查询层）
+
+1. 完成 `repository_federation.go` 全量 GORM 化：
+   - `ListRemoteNodes` / `UpdateNodeRemoteConfig`
+   - `ListActiveBindingsForNode` / `GetNodeBasicInfo`
+   - `ListUsedPortsOnNode` / `ListTunnelIDsByNamePrefix` / `NextIndex`
+2. 完成 `repository_control.go` 全量 GORM 化：
+   - `ListForwardsByTunnel` / `ListForwardPorts` / `GetTunnelOutProtocol`
+   - `ResolveUserTunnelAndLimiter` / `ListChainNodesForTunnel`
+3. 完成 `repository_flow.go` 全量 GORM 化：
+   - `ListActiveForwardsByUser` / `ListActiveForwardsByUserTunnel`
+   - `GetForwardRecord` / `GetTunnelRecord`
+4. 复扫结果：
+   - `repository_federation.go` Raw/Exec = 0
+   - `repository_control.go` Raw/Exec = 0
+   - `repository_flow.go` Raw/Exec = 0
+   - repo 生产路径剩余 Raw/Exec = 9（全部在 `repository.go`）
+5. 验证结果：
+   - `go build ./...` ✅
+   - `go test ./internal/store/repo/...` ✅
+
+### 10.2 本轮执行记录（2026-02-17）
+
+1. 完成 P3 Import 9 个函数的 GORM 化（`repository.go`），并保持 `ON CONFLICT` 语义一致。
+2. 复扫确认：`repository.go` Import 区段 `tx.Exec`/`tx.Raw` 已清零。
+3. 验证结果：
+   - `go build ./...` ✅（使用显式 `GOMODCACHE/GOPATH/GOCACHE/HOME` 环境）
+   - `go test ./internal/store/repo/...` ✅
+
+### 10.3 本轮执行记录（2026-02-17，P2 部分）
+
+1. 将 tunnel 更新/chain 重建路径 SQL 下沉到 `repository_mutations.go`：
+   - 新增 `UpdateTunnelTx`
+   - 新增 `DeleteChainTunnelsByTunnelTx`
+   - 新增 `CreateChainTunnelTx`
+2. 将 handler 内部 SQL helper 迁移到 repo：
+   - 新增 `IsRemoteNodeTx`
+   - 新增 `PickNodePortTx`
+   - `replaceTunnelChainsTx` 改为 handler 方法并改用 repo 调用，不再直接 SQL
+3. 复扫结果：`mutations.go` 直接 SQL 从 27 处降至 17 处。
+4. 验证结果：
+   - `go build ./...` ✅
+   - `go test ./internal/store/repo/...` ✅
+
+### 10.4 本轮执行记录（2026-02-17，P2 收尾）
+
+1. 新增并落地事务语义化 repo 方法：
+   - `ReplaceTunnelGroupMembersTx` / `ReplaceUserGroupMembersTx`
+   - `ListUserIDsByUserGroupTx`
+   - `GetGroupPermissionPairByIDTx` / `DeleteGroupPermissionByIDTx`
+   - `RevokeGroupGrantsForRemovedUsersTx` / `RevokeGroupPermissionPairTx`
+   - `ReplaceFederationTunnelBindingsTx`
+2. 删除 handler 内 SQL helper（`queryInt64ListTx` / `revokeGroupGrantsForRemovedUsersTx` / `revokeGroupPermissionPairTx` / `replaceFederationTunnelBindingsTx`）。
+3. 复扫确认：`mutations.go` 生产路径 `tx.Exec`/`tx.Raw` = 0。
+4. 验证结果：
+   - `go build ./...` ✅
+   - `go test ./internal/store/repo/...` ✅
+
+---
+
+*本文档将随迁移进展实时更新状态标记。*
+*最后审计时间：2026-02-17，审计工具：代码静态分析 (grep/AST) + go build/go test 验证*

go-backend/go.mod

@@ -1,22 +1,35 @@
 module go-backend
 
-go 1.23.0
+go 1.24.0
 
 toolchain go1.24.4
 
 require (
 	github.com/gorilla/websocket v1.5.3
+	github.com/jackc/pgx/v5 v5.7.3
 	modernc.org/sqlite v1.37.1
 )
 
 require (
 	github.com/dustin/go-humanize v1.0.1 // indirect
+	github.com/glebarez/go-sqlite v1.21.2 // indirect
+	github.com/glebarez/sqlite v1.11.0 // indirect
 	github.com/google/uuid v1.6.0 // indirect
+	github.com/jackc/pgpassfile v1.0.0 // indirect
+	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
+	github.com/jackc/puddle/v2 v2.2.2 // indirect
+	github.com/jinzhu/inflection v1.0.0 // indirect
+	github.com/jinzhu/now v1.1.5 // indirect
 	github.com/mattn/go-isatty v0.0.20 // indirect
 	github.com/ncruces/go-strftime v0.1.9 // indirect
 	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
+	golang.org/x/crypto v0.31.0 // indirect
 	golang.org/x/exp v0.0.0-20250408133849-7e4ce0ab07d0 // indirect
+	golang.org/x/sync v0.17.0 // indirect
 	golang.org/x/sys v0.33.0 // indirect
+	golang.org/x/text v0.29.0 // indirect
+	gorm.io/driver/postgres v1.6.0 // indirect
+	gorm.io/gorm v1.31.1 // indirect
 	modernc.org/libc v1.65.7 // indirect
 	modernc.org/mathutil v1.7.1 // indirect
 	modernc.org/memory v1.11.0 // indirect

go-backend/go.sum

@@ -1,28 +1,66 @@
+github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
 github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
+github.com/glebarez/go-sqlite v1.21.2 h1:3a6LFC4sKahUunAmynQKLZceZCOzUthkRkEAl9gAXWo=
+github.com/glebarez/go-sqlite v1.21.2/go.mod h1:sfxdZyhQjTM2Wry3gVYWaW072Ri1WMdWJi0k6+3382k=
+github.com/glebarez/sqlite v1.11.0 h1:wSG0irqzP6VurnMEpFGer5Li19RpIRi2qvQz++w0GMw=
+github.com/glebarez/sqlite v1.11.0/go.mod h1:h8/o8j5wiAsqSPoWELDUdJXhjAhsVliSn7bWZjOhrgQ=
 github.com/google/pprof v0.0.0-20250317173921-a4b03ec1a45e h1:ijClszYn+mADRFY17kjQEVQ1XRhq2/JR1M3sGqeJoxs=
 github.com/google/pprof v0.0.0-20250317173921-a4b03ec1a45e/go.mod h1:boTsfXsheKC2y+lKOCMpSfarhxDeIzfZG1jqGcPl3cA=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
 github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
 github.com/gorilla/websocket v1.5.3 h1:saDtZ6Pbx/0u+bgYQ3q96pZgCzfhKXGPqt7kZ72aNNg=
 github.com/gorilla/websocket v1.5.3/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
+github.com/jackc/pgpassfile v1.0.0 h1:/6Hmqy13Ss2zCq62VdNG8tM1wchn8zjSGOBJ6icpsIM=
+github.com/jackc/pgpassfile v1.0.0/go.mod h1:CEx0iS5ambNFdcRtxPj5JhEz+xB6uRky5eyVu/W2HEg=
+github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 h1:iCEnooe7UlwOQYpKFhBabPMi4aNAfoODPEFNiAnClxo=
+github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761/go.mod h1:5TJZWKEWniPve33vlWYSoGYefn3gLQRzjfDlhSJ9ZKM=
+github.com/jackc/pgx/v5 v5.7.3 h1:PO1wNKj/bTAwxSJnO1Z4Ai8j4magtqg2SLNjEDzcXQo=
+github.com/jackc/pgx/v5 v5.7.3/go.mod h1:ncY89UGWxg82EykZUwSpUKEfccBGGYq1xjrOpsbsfGQ=
+github.com/jackc/puddle/v2 v2.2.2 h1:PR8nw+E/1w0GLuRFSmiioY6UooMp6KJv0/61nB7icHo=
+github.com/jackc/puddle/v2 v2.2.2/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4=
+github.com/jinzhu/inflection v1.0.0 h1:K317FqzuhWc8YvSVlFMCCUb36O/S9MCKRDI7QkRKD/E=
+github.com/jinzhu/inflection v1.0.0/go.mod h1:h+uFLlag+Qp1Va5pdKtLDYj+kHp5pxUVkryuEj+Srlc=
+github.com/jinzhu/now v1.1.5 h1:/o9tlHleP7gOFmsnYNz3RGnqzefHA47wQpKrrdTIwXQ=
+github.com/jinzhu/now v1.1.5/go.mod h1:d3SSVoowX0Lcu0IBviAWJpolVfI5UJVZZ7cO71lE/z8=
 github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
 github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
 github.com/ncruces/go-strftime v0.1.9 h1:bY0MQC28UADQmHmaF5dgpLmImcShSi2kHU9XLdhx/f4=
 github.com/ncruces/go-strftime v0.1.9/go.mod h1:Fwc5htZGVVkseilnfgOVb9mKy6w1naJmn9CehxcKcls=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94icq4NjY3clb7Lk8O1qJ8BdBEF8z0ibU0rE=
 github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo=
+github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
+github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
+github.com/stretchr/testify v1.8.1 h1:w7B6lhMri9wdJUVmEZPGGhZzrYTPvgJArz7wNPgYKsk=
+github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
+golang.org/x/crypto v0.31.0 h1:ihbySMvVjLAeSH1IbfcRTkD/iNscyz8rGzjF/E5hV6U=
+golang.org/x/crypto v0.31.0/go.mod h1:kDsLvtWBEx7MV9tJOj9bnXsPbxwJQ6csT/x4KIN4Ssk=
 golang.org/x/exp v0.0.0-20250408133849-7e4ce0ab07d0 h1:R84qjqJb5nVJMxqWYb3np9L5ZsaDtB+a39EqjV0JSUM=
 golang.org/x/exp v0.0.0-20250408133849-7e4ce0ab07d0/go.mod h1:S9Xr4PYopiDyqSyp5NjCrhFrqg6A5zA2E/iPHPhqnS8=
-golang.org/x/mod v0.24.0 h1:ZfthKaKaT4NrhGVZHO1/WDTwGES4De8KtWO0SIbNJMU=
-golang.org/x/mod v0.24.0/go.mod h1:IXM97Txy2VM4PJ3gI61r1YEk/gAj6zAHN3AdZt6S9Ww=
-golang.org/x/sync v0.14.0 h1:woo0S4Yywslg6hp4eUFjTVOyKt0RookbpAHG4c1HmhQ=
-golang.org/x/sync v0.14.0/go.mod h1:1dzgHSNfp02xaA81J2MS99Qcpr2w7fw1gpm99rleRqA=
+golang.org/x/mod v0.27.0 h1:kb+q2PyFnEADO2IEF935ehFUXlWiNjJWtRNgBLSfbxQ=
+golang.org/x/mod v0.27.0/go.mod h1:rWI627Fq0DEoudcK+MBkNkCe0EetEaDSwJJkCcjpazc=
+golang.org/x/sync v0.17.0 h1:l60nONMj9l5drqw6jlhIELNv9I0A4OFgRsG9k2oT9Ug=
+golang.org/x/sync v0.17.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
 golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.33.0 h1:q3i8TbbEz+JRD9ywIRlyRAQbM0qF7hu24q3teo2hbuw=
 golang.org/x/sys v0.33.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k=
-golang.org/x/tools v0.33.0 h1:4qz2S3zmRxbGIhDIAgjxvFutSvH5EfnsYrRBj0UI0bc=
-golang.org/x/tools v0.33.0/go.mod h1:CIJMaWEY88juyUfo7UbgPqbC8rU2OqfAV1h2Qp0oMYI=
+golang.org/x/text v0.29.0 h1:1neNs90w9YzJ9BocxfsQNHKuAT4pkghyXc4nhZ6sJvk=
+golang.org/x/text v0.29.0/go.mod h1:7MhJOA9CD2qZyOKYazxdYMF85OwPdEr9jTtBpO7ydH4=
+golang.org/x/tools v0.36.0 h1:kWS0uv/zsvHEle1LbV5LE8QujrxB3wfQyxHfhOk0Qkg=
+golang.org/x/tools v0.36.0/go.mod h1:WBDiHKJK8YgLHlcQPYQzNCkUxUypCaa5ZegCVutKm+s=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gorm.io/driver/postgres v1.6.0 h1:2dxzU8xJ+ivvqTRph34QX+WrRaJlmfyPqXmoGVjMBa4=
+gorm.io/driver/postgres v1.6.0/go.mod h1:vUw0mrGgrTK+uPHEhAdV4sfFELrByKVGnaVRkXDhtWo=
+gorm.io/gorm v1.31.1 h1:7CA8FTFz/gRfgqgpeKIBcervUn3xSyPUmr6B2WXJ7kg=
+gorm.io/gorm v1.31.1/go.mod h1:XyQVbO2k6YkOis7C2437jSit3SsDK72s7n7rsSHd+Gs=
 modernc.org/cc/v4 v4.26.1 h1:+X5NtzVBn0KgsBCBe+xkDC7twLb/jNVj9FPgiwSQO3s=
 modernc.org/cc/v4 v4.26.1/go.mod h1:uVtb5OGqUKpoLWhqwNQo/8LwvoiEBLvZXIQ/SmO6mL0=
 modernc.org/ccgo/v4 v4.28.0 h1:rjznn6WWehKq7dG4JtLRKxb52Ecv8OUGah8+Z/SfpNU=

go-backend/internal/app/app.go

@@ -4,28 +4,44 @@ import (
 	"context"
 	"fmt"
 	"net/http"
+	"strings"
 	"time"
 
 	"go-backend/internal/config"
 	httpserver "go-backend/internal/http"
 	"go-backend/internal/http/handler"
-	"go-backend/internal/store/sqlite"
+	"go-backend/internal/store/repo"
 )
 
 type App struct {
 	cfg    config.Config
 	server *http.Server
-	repo   *sqlite.Repository
+	repo   *repo.Repository
 	h      *handler.Handler
 }
 
 func New(cfg config.Config) (*App, error) {
-	repo, err := sqlite.Open(cfg.DBPath)
-	if err != nil {
-		return nil, fmt.Errorf("open sqlite: %w", err)
+	var (
+		r   *repo.Repository
+		err error
+	)
+
+	switch strings.ToLower(strings.TrimSpace(cfg.DBType)) {
+	case "", "sqlite":
+		r, err = repo.Open(cfg.DBPath)
+		if err != nil {
+			return nil, fmt.Errorf("open sqlite: %w", err)
+		}
+	case "postgres", "postgresql":
+		r, err = repo.OpenPostgres(cfg.DatabaseURL)
+		if err != nil {
+			return nil, fmt.Errorf("open postgres: %w", err)
+		}
+	default:
+		return nil, fmt.Errorf("unsupported DB_TYPE %q", cfg.DBType)
 	}
 
-	h := handler.New(repo, cfg.JWTSecret)
+	h := handler.New(r, cfg.JWTSecret)
 	router := httpserver.NewRouter(h, cfg.JWTSecret)
 
 	s := &http.Server{
@@ -37,7 +53,7 @@ func New(cfg config.Config) (*App, error) {
 		IdleTimeout:       60 * time.Second,
 	}
 
-	return &App{cfg: cfg, server: s, repo: repo, h: h}, nil
+	return &App{cfg: cfg, server: s, repo: r, h: h}, nil
 }
 
 func (a *App) Run() error {

go-backend/internal/config/config.go

@@ -3,18 +3,22 @@ package config
 import "os"
 
 type Config struct {
-	Addr      string
-	DBPath    string
-	JWTSecret string
-	LogDir    string
+	Addr        string
+	DBType      string
+	DBPath      string
+	DatabaseURL string
+	JWTSecret   string
+	LogDir      string
 }
 
 func FromEnv() Config {
 	cfg := Config{
-		Addr:      getEnv("SERVER_ADDR", ":6365"),
-		DBPath:    getEnv("DB_PATH", "/app/data/gost.db"),
-		JWTSecret: getEnv("JWT_SECRET", ""),
-		LogDir:    getEnv("LOG_DIR", "/app/logs"),
+		Addr:        getEnv("SERVER_ADDR", ":6365"),
+		DBType:      getEnv("DB_TYPE", "sqlite"),
+		DBPath:      getEnv("DB_PATH", "/app/data/gost.db"),
+		DatabaseURL: getEnv("DATABASE_URL", ""),
+		JWTSecret:   getEnv("JWT_SECRET", ""),
+		LogDir:      getEnv("LOG_DIR", "/app/logs"),
 	}
 
 	return cfg

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

@@ -0,0 +1,386 @@
+package client
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+	"time"
+)
+
+type FederationClient struct {
+	client *http.Client
+}
+
+type RemoteNodeInfo struct {
+	ShareID        int64  `json:"shareId"`
+	ShareName      string `json:"shareName"`
+	NodeID         int64  `json:"nodeId"`
+	NodeName       string `json:"nodeName"`
+	ServerIP       string `json:"serverIp"`
+	Status         int    `json:"status"`
+	MaxBandwidth   int64  `json:"maxBandwidth"`
+	CurrentFlow    int64  `json:"currentFlow"`
+	ExpiryTime     int64  `json:"expiryTime"`
+	PortRangeStart int    `json:"portRangeStart"`
+	PortRangeEnd   int    `json:"portRangeEnd"`
+}
+
+type RemoteTunnelResponse struct {
+	TunnelID int64 `json:"tunnelId"`
+}
+
+type RuntimeReservePortRequest struct {
+	ResourceKey   string `json:"resourceKey"`
+	Protocol      string `json:"protocol"`
+	RequestedPort int    `json:"requestedPort"`
+}
+
+type RuntimeReservePortResponse struct {
+	ReservationID string `json:"reservationId"`
+	BindingID     string `json:"bindingId"`
+	AllocatedPort int    `json:"allocatedPort"`
+}
+
+type RuntimeTarget struct {
+	Host     string `json:"host"`
+	Port     int    `json:"port"`
+	Protocol string `json:"protocol"`
+}
+
+type RuntimeApplyRoleRequest struct {
+	ReservationID string          `json:"reservationId"`
+	ResourceKey   string          `json:"resourceKey"`
+	Role          string          `json:"role"`
+	Protocol      string          `json:"protocol"`
+	Strategy      string          `json:"strategy"`
+	Targets       []RuntimeTarget `json:"targets"`
+}
+
+type RuntimeApplyRoleResponse struct {
+	BindingID     string `json:"bindingId"`
+	ReservationID string `json:"reservationId"`
+	AllocatedPort int    `json:"allocatedPort"`
+}
+
+type RuntimeReleaseRoleRequest struct {
+	BindingID     string `json:"bindingId"`
+	ReservationID string `json:"reservationId"`
+	ResourceKey   string `json:"resourceKey"`
+}
+
+type RuntimeDiagnoseRequest struct {
+	IP      string `json:"ip"`
+	Port    int    `json:"port"`
+	Count   int    `json:"count"`
+	Timeout int    `json:"timeout"`
+}
+
+type RuntimeNodeCommandRequest struct {
+	CommandType string      `json:"commandType"`
+	Data        interface{} `json:"data"`
+}
+
+type RuntimeNodeCommandResponse struct {
+	Type    string                 `json:"type"`
+	Success bool                   `json:"success"`
+	Message string                 `json:"message"`
+	Data    map[string]interface{} `json:"data,omitempty"`
+}
+
+func NewFederationClient() *FederationClient {
+	return &FederationClient{
+		client: &http.Client{
+			Timeout: 10 * time.Second,
+		},
+	}
+}
+
+func NewFederationClientWithTimeout(timeout time.Duration) *FederationClient {
+	return &FederationClient{
+		client: &http.Client{
+			Timeout: timeout,
+		},
+	}
+}
+
+func (c *FederationClient) Connect(url, token, localDomain string) (*RemoteNodeInfo, error) {
+	url = strings.TrimSuffix(url, "/")
+	req, err := http.NewRequest("POST", url+"/api/v1/federation/connect", nil)
+	if err != nil {
+		return nil, err
+	}
+	req.Header.Set("Authorization", "Bearer "+token)
+	if localDomain != "" {
+		req.Header.Set("X-Panel-Domain", localDomain)
+	}
+	req.Header.Set("Content-Type", "application/json")
+
+	resp, err := c.client.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != 200 {
+		body, _ := io.ReadAll(resp.Body)
+		return nil, fmt.Errorf("remote error %d: %s", resp.StatusCode, string(body))
+	}
+
+	var res struct {
+		Code int            `json:"code"`
+		Msg  string         `json:"msg"`
+		Data RemoteNodeInfo `json:"data"`
+	}
+	if err := json.NewDecoder(resp.Body).Decode(&res); err != nil {
+		return nil, err
+	}
+	if res.Code != 0 {
+		return nil, fmt.Errorf("remote api error: %s", res.Msg)
+	}
+
+	return &res.Data, nil
+}
+
+func (c *FederationClient) CreateTunnel(url, token, localDomain, protocol string, remotePort int, target string) (*RemoteTunnelResponse, error) {
+	url = strings.TrimSuffix(url, "/")
+	payload := map[string]interface{}{
+		"protocol":   protocol,
+		"remotePort": remotePort,
+		"target":     target,
+	}
+	bodyBytes, _ := json.Marshal(payload)
+	req, err := http.NewRequest("POST", url+"/api/v1/federation/tunnel/create", strings.NewReader(string(bodyBytes)))
+	if err != nil {
+		return nil, err
+	}
+	req.Header.Set("Authorization", "Bearer "+token)
+	if localDomain != "" {
+		req.Header.Set("X-Panel-Domain", localDomain)
+	}
+	req.Header.Set("Content-Type", "application/json")
+
+	resp, err := c.client.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != 200 {
+		body, _ := io.ReadAll(resp.Body)
+		return nil, fmt.Errorf("remote error %d: %s", resp.StatusCode, string(body))
+	}
+
+	var res struct {
+		Code int                  `json:"code"`
+		Msg  string               `json:"msg"`
+		Data RemoteTunnelResponse `json:"data"`
+	}
+	if err := json.NewDecoder(resp.Body).Decode(&res); err != nil {
+		return nil, err
+	}
+	if res.Code != 0 {
+		return nil, fmt.Errorf("remote api error: %s", res.Msg)
+	}
+
+	return &res.Data, nil
+}
+
+func (c *FederationClient) ReservePort(url, token, localDomain string, reqData RuntimeReservePortRequest) (*RuntimeReservePortResponse, error) {
+	url = strings.TrimSuffix(url, "/")
+	bodyBytes, _ := json.Marshal(reqData)
+	req, err := http.NewRequest("POST", url+"/api/v1/federation/runtime/reserve-port", strings.NewReader(string(bodyBytes)))
+	if err != nil {
+		return nil, err
+	}
+	req.Header.Set("Authorization", "Bearer "+token)
+	if localDomain != "" {
+		req.Header.Set("X-Panel-Domain", localDomain)
+	}
+	req.Header.Set("Content-Type", "application/json")
+
+	resp, err := c.client.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != 200 {
+		body, _ := io.ReadAll(resp.Body)
+		return nil, fmt.Errorf("remote error %d: %s", resp.StatusCode, string(body))
+	}
+
+	var res struct {
+		Code int                        `json:"code"`
+		Msg  string                     `json:"msg"`
+		Data RuntimeReservePortResponse `json:"data"`
+	}
+	if err := json.NewDecoder(resp.Body).Decode(&res); err != nil {
+		return nil, err
+	}
+	if res.Code != 0 {
+		return nil, fmt.Errorf("remote api error: %s", res.Msg)
+	}
+
+	return &res.Data, nil
+}
+
+func (c *FederationClient) ApplyRole(url, token, localDomain string, reqData RuntimeApplyRoleRequest) (*RuntimeApplyRoleResponse, error) {
+	url = strings.TrimSuffix(url, "/")
+	bodyBytes, _ := json.Marshal(reqData)
+	req, err := http.NewRequest("POST", url+"/api/v1/federation/runtime/apply-role", strings.NewReader(string(bodyBytes)))
+	if err != nil {
+		return nil, err
+	}
+	req.Header.Set("Authorization", "Bearer "+token)
+	if localDomain != "" {
+		req.Header.Set("X-Panel-Domain", localDomain)
+	}
+	req.Header.Set("Content-Type", "application/json")
+
+	resp, err := c.client.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != 200 {
+		body, _ := io.ReadAll(resp.Body)
+		return nil, fmt.Errorf("remote error %d: %s", resp.StatusCode, string(body))
+	}
+
+	var res struct {
+		Code int                      `json:"code"`
+		Msg  string                   `json:"msg"`
+		Data RuntimeApplyRoleResponse `json:"data"`
+	}
+	if err := json.NewDecoder(resp.Body).Decode(&res); err != nil {
+		return nil, err
+	}
+	if res.Code != 0 {
+		return nil, fmt.Errorf("remote api error: %s", res.Msg)
+	}
+
+	return &res.Data, nil
+}
+
+func (c *FederationClient) ReleaseRole(url, token, localDomain string, reqData RuntimeReleaseRoleRequest) error {
+	url = strings.TrimSuffix(url, "/")
+	bodyBytes, _ := json.Marshal(reqData)
+	req, err := http.NewRequest("POST", url+"/api/v1/federation/runtime/release-role", strings.NewReader(string(bodyBytes)))
+	if err != nil {
+		return err
+	}
+	req.Header.Set("Authorization", "Bearer "+token)
+	if localDomain != "" {
+		req.Header.Set("X-Panel-Domain", localDomain)
+	}
+	req.Header.Set("Content-Type", "application/json")
+
+	resp, err := c.client.Do(req)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != 200 {
+		body, _ := io.ReadAll(resp.Body)
+		return fmt.Errorf("remote error %d: %s", resp.StatusCode, string(body))
+	}
+
+	var res struct {
+		Code int    `json:"code"`
+		Msg  string `json:"msg"`
+	}
+	if err := json.NewDecoder(resp.Body).Decode(&res); err != nil {
+		return err
+	}
+	if res.Code != 0 {
+		return fmt.Errorf("remote api error: %s", res.Msg)
+	}
+
+	return nil
+}
+
+func (c *FederationClient) Diagnose(url, token, localDomain string, reqData RuntimeDiagnoseRequest) (map[string]interface{}, error) {
+	url = strings.TrimSuffix(url, "/")
+	bodyBytes, _ := json.Marshal(reqData)
+	req, err := http.NewRequest("POST", url+"/api/v1/federation/runtime/diagnose", strings.NewReader(string(bodyBytes)))
+	if err != nil {
+		return nil, err
+	}
+	req.Header.Set("Authorization", "Bearer "+token)
+	if localDomain != "" {
+		req.Header.Set("X-Panel-Domain", localDomain)
+	}
+	req.Header.Set("Content-Type", "application/json")
+
+	resp, err := c.client.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != 200 {
+		body, _ := io.ReadAll(resp.Body)
+		return nil, fmt.Errorf("remote error %d: %s", resp.StatusCode, string(body))
+	}
+
+	var res struct {
+		Code int                    `json:"code"`
+		Msg  string                 `json:"msg"`
+		Data map[string]interface{} `json:"data"`
+	}
+	if err := json.NewDecoder(resp.Body).Decode(&res); err != nil {
+		return nil, err
+	}
+	if res.Code != 0 {
+		return nil, fmt.Errorf("remote api error: %s", res.Msg)
+	}
+
+	if res.Data == nil {
+		return nil, fmt.Errorf("remote api error: empty diagnosis payload")
+	}
+
+	return res.Data, nil
+}
+
+func (c *FederationClient) Command(url, token, localDomain string, reqData RuntimeNodeCommandRequest) (*RuntimeNodeCommandResponse, error) {
+	url = strings.TrimSuffix(url, "/")
+	bodyBytes, _ := json.Marshal(reqData)
+	req, err := http.NewRequest("POST", url+"/api/v1/federation/runtime/command", strings.NewReader(string(bodyBytes)))
+	if err != nil {
+		return nil, err
+	}
+	req.Header.Set("Authorization", "Bearer "+token)
+	if localDomain != "" {
+		req.Header.Set("X-Panel-Domain", localDomain)
+	}
+	req.Header.Set("Content-Type", "application/json")
+
+	resp, err := c.client.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != 200 {
+		body, _ := io.ReadAll(resp.Body)
+		return nil, fmt.Errorf("remote error %d: %s", resp.StatusCode, string(body))
+	}
+
+	var res struct {
+		Code int                        `json:"code"`
+		Msg  string                     `json:"msg"`
+		Data RuntimeNodeCommandResponse `json:"data"`
+	}
+	if err := json.NewDecoder(resp.Body).Decode(&res); err != nil {
+		return nil, err
+	}
+	if res.Code != 0 {
+		return nil, fmt.Errorf("remote api error: %s", res.Msg)
+	}
+
+	return &res.Data, nil
+}

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

@@ -0,0 +1,45 @@
+# BACKEND HTTP HANDLER KNOWLEDGE BASE
+
+**Generated:** Sun Feb 15 2026
+
+## OVERVIEW
+HTTP request handlers for FLVX Admin API. Core business logic layer.
+**Stack:** Go 1.23, net/http, GORM via Repository pattern.
+
+## STRUCTURE
+```
+handler/
+├── handler.go        # Main Handler struct, login/captcha, job scheduling
+├── control_plane.go  # Node control plane API (add/delete/list)
+├── 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)
+└── upgrade.go        # System upgrade API
+```
+
+## WHERE TO LOOK
+| Task | Location | Notes |
+|------|----------|-------|
+| **User/Tunnel CRUD** | `mutations.go` | Largest file; all create/update/delete ops |
+| **Login/Captcha** | `handler.go` | Login flow, captcha verification |
+| **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 |
+
+## CONVENTIONS
+- Inherits from parent: GORM via Repository pattern, JWT in Authorization header.
+- Large files expected (`mutations.go` 3716 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.).
+
+## ANTI-PATTERNS
+- Do NOT let handlers call `repo.DB()` directly — add a Repository method instead.
+- Do NOT change handler signatures without updating router.go.
+
+## COMMANDS
+```bash
+cd go-backend
+go test ./internal/http/handler/...
+```

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

@@ -1,7 +1,6 @@
 package handler
 
 import (
-	"database/sql"
 	"errors"
 	"fmt"
 	"net"
@@ -11,55 +10,19 @@ import (
 	"strings"
 	"time"
 
+	"go-backend/internal/http/client"
+	"go-backend/internal/store/model"
 	"go-backend/internal/ws"
 )
 
 var errForwardNotFound = errors.New("forward not found")
 
-type forwardRecord struct {
-	ID         int64
-	UserID     int64
-	UserName   string
-	Name       string
-	TunnelID   int64
-	RemoteAddr string
-	Strategy   string
-	Status     int
-}
+type forwardRecord = model.ForwardRecord
+type tunnelRecord = model.TunnelRecord
+type forwardPortRecord = model.ForwardPortRecord
+type nodeRecord = model.NodeRecord
 
-type tunnelRecord struct {
-	ID           int64
-	Type         int
-	Status       int
-	Flow         int64
-	TrafficRatio float64
-}
-
-type forwardPortRecord struct {
-	NodeID int64
-	Port   int
-}
-
-type nodeRecord struct {
-	ID            int64
-	Name          string
-	ServerIP      string
-	ServerIPv4    string
-	ServerIPv6    string
-	Status        int
-	PortRange     string
-	TCPListenAddr string
-	UDPListenAddr string
-	InterfaceName string
-}
-
-type chainNodeRecord struct {
-	ChainType int
-	Inx       int64
-	NodeID    int64
-	Port      int
-	NodeName  string
-}
+type chainNodeRecord = model.ChainNodeRecord
 
 type diagnosisTarget struct {
 	Address string
@@ -94,219 +57,82 @@ func (h *Handler) ensureTunnelPermission(userID int64, roleID int, tunnelID int6
 	if roleID == 0 {
 		return nil
 	}
-	var count int
-	err := h.repo.DB().QueryRow(`SELECT COUNT(1) FROM user_tunnel WHERE user_id = ? AND tunnel_id = ? AND status = 1`, userID, tunnelID).Scan(&count)
+	ok, err := h.repo.UserTunnelExistsByUserAndTunnel(userID, tunnelID)
 	if err != nil {
 		return err
 	}
-	if count <= 0 {
+	if !ok {
 		return errors.New("你没有该隧道的权限")
 	}
 	return nil
 }
 
 func (h *Handler) getForwardRecord(forwardID int64) (*forwardRecord, error) {
-	row := h.repo.DB().QueryRow(`
-		SELECT id, user_id, user_name, name, tunnel_id, remote_addr, strategy, status
-		FROM forward WHERE id = ? LIMIT 1
-	`, forwardID)
-	var fr forwardRecord
-	err := row.Scan(&fr.ID, &fr.UserID, &fr.UserName, &fr.Name, &fr.TunnelID, &fr.RemoteAddr, &fr.Strategy, &fr.Status)
+	fr, err := h.repo.GetForwardRecord(forwardID)
 	if err != nil {
-		if errors.Is(err, sql.ErrNoRows) {
-			return nil, errForwardNotFound
-		}
 		return nil, err
 	}
-	if strings.TrimSpace(fr.Strategy) == "" {
-		fr.Strategy = "fifo"
+	if fr == nil {
+		return nil, errForwardNotFound
 	}
-	return &fr, nil
+	return fr, nil
 }
 
 func (h *Handler) getTunnelRecord(tunnelID int64) (*tunnelRecord, error) {
-	row := h.repo.DB().QueryRow(`SELECT id, type, status, flow, traffic_ratio FROM tunnel WHERE id = ? LIMIT 1`, tunnelID)
-	var tr tunnelRecord
-	err := row.Scan(&tr.ID, &tr.Type, &tr.Status, &tr.Flow, &tr.TrafficRatio)
+	tr, err := h.repo.GetTunnelRecord(tunnelID)
 	if err != nil {
-		if errors.Is(err, sql.ErrNoRows) {
-			return nil, errors.New("隧道不存在")
-		}
 		return nil, err
 	}
-	if tr.Flow <= 0 {
-		tr.Flow = 1
+	if tr == nil {
+		return nil, errors.New("隧道不存在")
 	}
-	if tr.TrafficRatio <= 0 {
-		tr.TrafficRatio = 1
-	}
-	return &tr, nil
+	return tr, nil
 }
 
 func (h *Handler) listForwardsByTunnel(tunnelID int64) ([]forwardRecord, error) {
-	rows, err := h.repo.DB().Query(`
-		SELECT id, user_id, user_name, name, tunnel_id, remote_addr, strategy, status
-		FROM forward
-		WHERE tunnel_id = ?
-		ORDER BY id ASC
-	`, tunnelID)
-	if err != nil {
-		return nil, err
-	}
-	defer rows.Close()
-
-	result := make([]forwardRecord, 0)
-	for rows.Next() {
-		var fr forwardRecord
-		if err := rows.Scan(&fr.ID, &fr.UserID, &fr.UserName, &fr.Name, &fr.TunnelID, &fr.RemoteAddr, &fr.Strategy, &fr.Status); err != nil {
-			return nil, err
-		}
-		if strings.TrimSpace(fr.Strategy) == "" {
-			fr.Strategy = "fifo"
-		}
-		result = append(result, fr)
-	}
-	if err := rows.Err(); err != nil {
-		return nil, err
-	}
-	return result, nil
+	return h.repo.ListForwardsByTunnel(tunnelID)
 }
 
 func (h *Handler) listForwardPorts(forwardID int64) ([]forwardPortRecord, error) {
-	rows, err := h.repo.DB().Query(`SELECT node_id, port FROM forward_port WHERE forward_id = ? ORDER BY id ASC`, forwardID)
-	if err != nil {
-		return nil, err
-	}
-	defer rows.Close()
+	return h.repo.ListForwardPorts(forwardID)
+}
 
-	result := make([]forwardPortRecord, 0)
-	for rows.Next() {
-		var item forwardPortRecord
-		if err := rows.Scan(&item.NodeID, &item.Port); err != nil {
-			return nil, err
-		}
-		result = append(result, item)
+func (h *Handler) isTunnelSelectedTLSProtocol(tunnelID int64) (bool, error) {
+	protocol, err := h.repo.GetTunnelOutProtocol(tunnelID)
+	if err != nil {
+		return false, err
 	}
-	if err := rows.Err(); err != nil {
-		return nil, err
-	}
-	return result, nil
+	return isTLSTunnelProtocol(protocol), nil
 }
 
 func (h *Handler) getNodeRecord(nodeID int64) (*nodeRecord, error) {
-	row := h.repo.DB().QueryRow(`
-		SELECT id, name, server_ip, server_ip_v4, server_ip_v6, status, port, tcp_listen_addr, udp_listen_addr, interface_name
-		FROM node
-		WHERE id = ?
-		LIMIT 1
-	`, nodeID)
-	var n nodeRecord
-	var serverIPv4 sql.NullString
-	var serverIPv6 sql.NullString
-	var portRange sql.NullString
-	var tcpListen sql.NullString
-	var udpListen sql.NullString
-	var iface sql.NullString
-	err := row.Scan(&n.ID, &n.Name, &n.ServerIP, &serverIPv4, &serverIPv6, &n.Status, &portRange, &tcpListen, &udpListen, &iface)
+	n, err := h.repo.GetNodeRecord(nodeID)
 	if err != nil {
-		if errors.Is(err, sql.ErrNoRows) {
-			return nil, errors.New("节点不存在")
-		}
 		return nil, err
 	}
-	n.ServerIPv4 = strings.TrimSpace(serverIPv4.String)
-	n.ServerIPv6 = strings.TrimSpace(serverIPv6.String)
-	n.PortRange = strings.TrimSpace(portRange.String)
-	n.TCPListenAddr = strings.TrimSpace(tcpListen.String)
-	n.UDPListenAddr = strings.TrimSpace(udpListen.String)
-	n.InterfaceName = strings.TrimSpace(iface.String)
-	if n.TCPListenAddr == "" {
-		n.TCPListenAddr = "[::]"
+	if n == nil {
+		return nil, errors.New("节点不存在")
 	}
-	if n.UDPListenAddr == "" {
-		n.UDPListenAddr = "[::]"
-	}
-	if strings.TrimSpace(n.Name) == "" {
-		n.Name = fmt.Sprintf("node_%d", n.ID)
-	}
-	return &n, nil
+	return n, nil
 }
 
-func (h *Handler) resolveUserTunnelAndLimiter(userID, tunnelID int64) (int64, *int, error) {
-	row := h.repo.DB().QueryRow(`
-		SELECT ut.id, sl.speed
-		FROM user_tunnel ut
-		LEFT JOIN speed_limit sl ON sl.id = ut.speed_id
-		WHERE ut.user_id = ? AND ut.tunnel_id = ?
-		ORDER BY ut.id ASC
-		LIMIT 1
-	`, userID, tunnelID)
-	var userTunnelID int64
-	var speed sql.NullInt64
-	err := row.Scan(&userTunnelID, &speed)
+func (h *Handler) resolveUserTunnelAndLimiter(userID, tunnelID int64) (int64, *int64, *int, error) {
+	info, err := h.repo.ResolveUserTunnelAndLimiter(userID, tunnelID)
 	if err != nil {
-		if errors.Is(err, sql.ErrNoRows) {
-			return 0, nil, nil
-		}
-		return 0, nil, err
+		return 0, nil, nil, err
 	}
-	if !speed.Valid || speed.Int64 <= 0 {
-		return userTunnelID, nil, nil
+	if info == nil {
+		return 0, nil, nil, nil
 	}
-	v := int(speed.Int64)
-	return userTunnelID, &v, nil
+	return info.UserTunnelID, info.LimiterID, info.Speed, nil
 }
 
 func (h *Handler) listUserTunnelIDs(userID, tunnelID int64) ([]int64, error) {
-	rows, err := h.repo.DB().Query(`
-		SELECT id
-		FROM user_tunnel
-		WHERE user_id = ? AND tunnel_id = ?
-		ORDER BY id ASC
-	`, userID, tunnelID)
-	if err != nil {
-		return nil, err
-	}
-	defer rows.Close()
-
-	out := make([]int64, 0)
-	for rows.Next() {
-		var id int64
-		if err := rows.Scan(&id); err != nil {
-			return nil, err
-		}
-		out = append(out, id)
-	}
-	if err := rows.Err(); err != nil {
-		return nil, err
-	}
-	return out, nil
+	return h.repo.ListUserTunnelIDs(userID, tunnelID)
 }
 
 func (h *Handler) listUserTunnelIDsByUser(userID int64) ([]int64, error) {
-	rows, err := h.repo.DB().Query(`
-		SELECT id
-		FROM user_tunnel
-		WHERE user_id = ?
-		ORDER BY id ASC
-	`, userID)
-	if err != nil {
-		return nil, err
-	}
-	defer rows.Close()
-
-	out := make([]int64, 0)
-	for rows.Next() {
-		var id int64
-		if err := rows.Scan(&id); err != nil {
-			return nil, err
-		}
-		out = append(out, id)
-	}
-	if err := rows.Err(); err != nil {
-		return nil, err
-	}
-	return out, nil
+	return h.repo.ListUserTunnelIDsByUser(userID)
 }
 
 func (h *Handler) syncForwardServices(forward *forwardRecord, method string, allowFallbackAdd bool) error {
@@ -326,18 +152,26 @@ func (h *Handler) syncForwardServices(forward *forwardRecord, method string, all
 		return errors.New("转发入口端口不存在")
 	}
 
-	userTunnelID, limiter, err := h.resolveUserTunnelAndLimiter(forward.UserID, forward.TunnelID)
+	userTunnelID, limiterID, speed, err := h.resolveUserTunnelAndLimiter(forward.UserID, forward.TunnelID)
 	if err != nil {
 		return err
 	}
 	serviceBase := buildForwardServiceBase(forward.ID, forward.UserID, userTunnelID)
+	tunnelTLSProtocol, err := h.isTunnelSelectedTLSProtocol(forward.TunnelID)
+	if err != nil {
+		return err
+	}
 
 	for _, fp := range ports {
+		if limiterID != nil && speed != nil {
+			h.ensureLimiterOnNode(fp.NodeID, *limiterID, *speed)
+		}
+
 		node, err := h.getNodeRecord(fp.NodeID)
 		if err != nil {
 			return err
 		}
-		services := buildForwardServiceConfigs(serviceBase, forward, tunnel, node, fp.Port, limiter)
+		services := buildForwardServiceConfigs(serviceBase, forward, tunnel, node, fp.Port, limiterID, tunnelTLSProtocol)
 		_, err = h.sendNodeCommand(node.ID, method, services, true, false)
 		if err != nil && allowFallbackAdd && method == "UpdateService" {
 			_, err = h.sendNodeCommand(node.ID, "AddService", services, true, false)
@@ -360,7 +194,7 @@ func (h *Handler) controlForwardServices(forward *forwardRecord, commandType str
 	if len(ports) == 0 {
 		return nil
 	}
-	userTunnelID, _, err := h.resolveUserTunnelAndLimiter(forward.UserID, forward.TunnelID)
+	userTunnelID, _, _, err := h.resolveUserTunnelAndLimiter(forward.UserID, forward.TunnelID)
 	if err != nil {
 		return err
 	}
@@ -438,7 +272,17 @@ func (h *Handler) applyNodeProtocolChange(nodeID int64, httpVal, tlsVal, socksVa
 }
 
 func (h *Handler) sendNodeCommand(nodeID int64, commandType string, data interface{}, tolerateExists bool, tolerateNotFound bool) (ws.CommandResult, error) {
-	result, err := h.wsServer.SendCommand(nodeID, commandType, data, 12*time.Second)
+	var (
+		result ws.CommandResult
+		err    error
+	)
+
+	node, nodeErr := h.getNodeRecord(nodeID)
+	if nodeErr == nil && node != nil && node.IsRemote == 1 {
+		result, err = h.sendRemoteNodeCommand(node, commandType, data)
+	} else {
+		result, err = h.wsServer.SendCommand(nodeID, commandType, data, 12*time.Second)
+	}
 	if err == nil {
 		return result, nil
 	}
@@ -456,6 +300,44 @@ func (h *Handler) sendNodeCommand(nodeID int64, commandType string, data interfa
 	return result, err
 }
 
+func (h *Handler) sendRemoteNodeCommand(node *nodeRecord, commandType string, data interface{}) (ws.CommandResult, error) {
+	if node == nil {
+		return ws.CommandResult{}, errors.New("节点不存在")
+	}
+	remoteURL := strings.TrimSpace(node.RemoteURL)
+	remoteToken := strings.TrimSpace(node.RemoteToken)
+	if remoteURL == "" || remoteToken == "" {
+		return ws.CommandResult{}, errors.New("远程节点缺少共享配置")
+	}
+
+	fc := client.NewFederationClient()
+	res, err := fc.Command(remoteURL, remoteToken, h.federationLocalDomain(), client.RuntimeNodeCommandRequest{
+		CommandType: commandType,
+		Data:        data,
+	})
+	if err != nil {
+		return ws.CommandResult{}, err
+	}
+	if res == nil {
+		return ws.CommandResult{}, errors.New("远程节点未返回命令结果")
+	}
+
+	result := ws.CommandResult{
+		Type:    res.Type,
+		Success: res.Success,
+		Message: res.Message,
+		Data:    res.Data,
+	}
+	if !result.Success {
+		msg := strings.TrimSpace(result.Message)
+		if msg == "" {
+			msg = "命令执行失败"
+		}
+		return result, errors.New(msg)
+	}
+	return result, nil
+}
+
 func (h *Handler) diagnoseForwardRuntime(forward *forwardRecord) (map[string]interface{}, error) {
 	if forward == nil {
 		return nil, errForwardNotFound
@@ -478,6 +360,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{}
@@ -501,7 +385,7 @@ func (h *Handler) diagnoseForwardRuntime(forward *forwardRecord) (map[string]int
 						"fromChainType": 1,
 						"toChainType":   2,
 						"toInx":         firstNode.Inx,
-					})
+					}, ipPreference)
 				}
 			} else {
 				for _, outNode := range outNodes {
@@ -509,7 +393,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)
 				}
 			}
 		}
@@ -524,7 +408,7 @@ func (h *Handler) diagnoseForwardRuntime(forward *forwardRecord) (map[string]int
 							"fromInx":       currentNode.Inx,
 							"toChainType":   2,
 							"toInx":         nextNode.Inx,
-						})
+						}, ipPreference)
 					}
 				} else {
 					for _, outNode := range outNodes {
@@ -533,7 +417,7 @@ func (h *Handler) diagnoseForwardRuntime(forward *forwardRecord) (map[string]int
 							"fromChainType": 2,
 							"fromInx":       currentNode.Inx,
 							"toChainType":   3,
-						})
+						}, ipPreference)
 					}
 				}
 			}
@@ -572,13 +456,13 @@ func (h *Handler) diagnoseTunnelRuntime(tunnelID int64) (map[string]interface{},
 		return nil, err
 	}
 
-	var tunnelName string
-	if err := h.repo.DB().QueryRow(`SELECT name FROM tunnel WHERE id = ?`, tunnelID).Scan(&tunnelName); err != nil {
-		if errors.Is(err, sql.ErrNoRows) {
-			return nil, errors.New("隧道不存在")
-		}
+	tunnelName, err := h.repo.GetTunnelName(tunnelID)
+	if err != nil {
 		return nil, err
 	}
+	if tunnelName == "" {
+		return nil, errors.New("隧道不存在")
+	}
 
 	chainRows, err := h.listChainNodesForTunnel(tunnelID)
 	if err != nil {
@@ -588,6 +472,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{}
@@ -596,7 +481,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,
 			})
 		}
@@ -609,7 +494,7 @@ func (h *Handler) diagnoseTunnelRuntime(tunnelID int64) (map[string]interface{},
 						"fromChainType": 1,
 						"toChainType":   2,
 						"toInx":         firstNode.Inx,
-					})
+					}, ipPreference)
 				}
 			} else {
 				for _, outNode := range outNodes {
@@ -617,7 +502,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)
 				}
 			}
 		}
@@ -632,7 +517,7 @@ func (h *Handler) diagnoseTunnelRuntime(tunnelID int64) (map[string]interface{},
 							"fromInx":       currentNode.Inx,
 							"toChainType":   2,
 							"toInx":         nextNode.Inx,
-						})
+						}, ipPreference)
 					}
 				} else {
 					for _, outNode := range outNodes {
@@ -641,7 +526,7 @@ func (h *Handler) diagnoseTunnelRuntime(tunnelID int64) (map[string]interface{},
 							"fromChainType": 2,
 							"fromInx":       currentNode.Inx,
 							"toChainType":   3,
-						})
+						}, ipPreference)
 					}
 				}
 			}
@@ -649,14 +534,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,
 			})
 		}
@@ -773,7 +658,15 @@ func (h *Handler) appendPathDiagnosis(results *[]map[string]interface{}, nodeCac
 	}
 	item["nodeName"] = fromNode.Name
 
-	pingData, pingErr := h.tcpPingViaNode(fromNodeID, targetIP, targetPort)
+	var (
+		pingData map[string]interface{}
+		pingErr  error
+	)
+	if fromNode.IsRemote == 1 {
+		pingData, pingErr = h.tcpPingViaRemoteNode(fromNode, targetIP, targetPort)
+	} else {
+		pingData, pingErr = h.tcpPingViaNode(fromNodeID, targetIP, targetPort)
+	}
 	if pingErr != nil {
 		item["success"] = false
 		item["message"] = pingErr.Error()
@@ -803,13 +696,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
@@ -817,11 +711,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("目标节点地址为空")
 	}
@@ -861,36 +758,7 @@ func firstPortFromRange(portRange string) int {
 }
 
 func (h *Handler) listChainNodesForTunnel(tunnelID int64) ([]chainNodeRecord, error) {
-	rows, err := h.repo.DB().Query(`
-		SELECT ct.chain_type, COALESCE(ct.inx, 0), ct.node_id, COALESCE(ct.port, 0), n.name
-		FROM chain_tunnel ct
-		LEFT JOIN node n ON n.id = ct.node_id
-		WHERE ct.tunnel_id = ?
-		ORDER BY ct.chain_type ASC, COALESCE(ct.inx, 0) ASC, ct.id ASC
-	`, tunnelID)
-	if err != nil {
-		return nil, err
-	}
-	defer rows.Close()
-
-	result := make([]chainNodeRecord, 0)
-	for rows.Next() {
-		var item chainNodeRecord
-		var name sql.NullString
-		if err := rows.Scan(&item.ChainType, &item.Inx, &item.NodeID, &item.Port, &name); err != nil {
-			return nil, err
-		}
-		if strings.TrimSpace(name.String) == "" {
-			item.NodeName = fmt.Sprintf("node_%d", item.NodeID)
-		} else {
-			item.NodeName = name.String
-		}
-		result = append(result, item)
-	}
-	if err := rows.Err(); err != nil {
-		return nil, err
-	}
-	return result, nil
+	return h.repo.ListChainNodesForTunnel(tunnelID)
 }
 
 func (h *Handler) tcpPingViaNode(nodeID int64, ip string, port int) (map[string]interface{}, error) {
@@ -909,6 +777,25 @@ func (h *Handler) tcpPingViaNode(nodeID int64, ip string, port int) (map[string]
 	return res.Data, nil
 }
 
+func (h *Handler) tcpPingViaRemoteNode(node *nodeRecord, ip string, port int) (map[string]interface{}, error) {
+	if node == nil {
+		return nil, errors.New("节点不存在")
+	}
+	remoteURL := strings.TrimSpace(node.RemoteURL)
+	remoteToken := strings.TrimSpace(node.RemoteToken)
+	if remoteURL == "" || remoteToken == "" {
+		return nil, errors.New("远程节点缺少共享配置")
+	}
+
+	fc := client.NewFederationClient()
+	return fc.Diagnose(remoteURL, remoteToken, h.federationLocalDomain(), client.RuntimeDiagnoseRequest{
+		IP:      strings.TrimSpace(ip),
+		Port:    port,
+		Count:   4,
+		Timeout: 5000,
+	})
+}
+
 func splitRemoteTargets(remoteAddr string) []string {
 	parts := strings.Split(remoteAddr, ",")
 	out := make([]string, 0, len(parts))
@@ -997,7 +884,7 @@ func isNotFoundError(err error) bool {
 	return strings.Contains(msg, "not found") || strings.Contains(msg, "不存在")
 }
 
-func buildForwardServiceConfigs(baseName string, forward *forwardRecord, tunnel *tunnelRecord, node *nodeRecord, port int, limiter *int) []map[string]interface{} {
+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)
 	targets := splitRemoteTargets(forward.RemoteAddr)
@@ -1030,7 +917,11 @@ func buildForwardServiceConfigs(baseName string, forward *forwardRecord, tunnel
 			},
 		}
 		if protocol == "udp" {
-			service["listener"].(map[string]interface{})["metadata"] = map[string]interface{}{"keepAlive": true}
+			listenerMetadata := map[string]interface{}{"keepAlive": true}
+			if tunnelTLSProtocol {
+				listenerMetadata["ttl"] = "10s"
+			}
+			service["listener"].(map[string]interface{})["metadata"] = listenerMetadata
 		}
 		if tunnel != nil && tunnel.Type == 2 {
 			service["handler"].(map[string]interface{})["chain"] = fmt.Sprintf("chains_%d", forward.TunnelID)
@@ -1038,8 +929,8 @@ func buildForwardServiceConfigs(baseName string, forward *forwardRecord, tunnel
 		if tunnel != nil && tunnel.Type == 1 && strings.TrimSpace(node.InterfaceName) != "" {
 			service["metadata"] = map[string]interface{}{"interface": node.InterfaceName}
 		}
-		if limiter != nil && *limiter > 0 {
-			service["limiter"] = strconv.Itoa(*limiter)
+		if limiterID != nil && *limiterID > 0 {
+			service["limiter"] = strconv.FormatInt(*limiterID, 10)
 		}
 		services = append(services, service)
 	}
@@ -1102,3 +993,49 @@ func asBool(v interface{}, def bool) bool {
 		return def
 	}
 }
+
+func (h *Handler) sendLimiterConfig(limiterID int64, speedMbps int, tunnelID int64) error {
+	rate := float64(speedMbps) / 8.0
+	limitStr := fmt.Sprintf("$ %.1fMB %.1fMB", rate, rate)
+
+	payload := map[string]interface{}{
+		"name":   strconv.FormatInt(limiterID, 10),
+		"limits": []string{limitStr},
+	}
+
+	nodes, err := h.tunnelEntryNodeIDs(tunnelID)
+	if err != nil {
+		return err
+	}
+
+	for _, nodeID := range nodes {
+		_, _ = h.sendNodeCommand(nodeID, "AddLimiters", payload, false, false)
+	}
+	return nil
+}
+
+func (h *Handler) sendDeleteLimiterConfig(limiterID int64, tunnelID int64) error {
+	payload := map[string]interface{}{
+		"limiter": strconv.FormatInt(limiterID, 10),
+	}
+
+	nodes, err := h.tunnelEntryNodeIDs(tunnelID)
+	if err != nil {
+		return err
+	}
+
+	for _, nodeID := range nodes {
+		_, _ = h.sendNodeCommand(nodeID, "DeleteLimiters", payload, false, true)
+	}
+	return nil
+}
+
+func (h *Handler) ensureLimiterOnNode(nodeID int64, limiterID int64, speed int) {
+	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)
+}

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

@@ -0,0 +1,50 @@
+package handler
+
+import (
+	"testing"
+
+	"go-backend/internal/store/repo"
+)
+
+func mustLastInsertID(t *testing.T, r *repo.Repository, label string) int64 {
+	t.Helper()
+	var id int64
+	if err := r.DB().Raw("SELECT last_insert_rowid()").Row().Scan(&id); err != nil {
+		t.Fatalf("read last_insert_rowid for %s: %v", label, err)
+	}
+	if id <= 0 {
+		t.Fatalf("invalid last_insert_rowid for %s: %d", label, id)
+	}
+	return id
+}
+
+func mustQueryInt(t *testing.T, r *repo.Repository, query string, args ...interface{}) int {
+	t.Helper()
+	var v int
+	if err := r.DB().Raw(query, args...).Row().Scan(&v); err != nil {
+		t.Fatalf("query int failed: %v (query=%q)", err, query)
+	}
+	return v
+}
+
+func mustQueryInt64Int64String(t *testing.T, r *repo.Repository, query string, args ...interface{}) (int64, int64, string) {
+	t.Helper()
+	var a int64
+	var b int64
+	var c string
+	if err := r.DB().Raw(query, args...).Row().Scan(&a, &b, &c); err != nil {
+		t.Fatalf("query int64+int64+string failed: %v (query=%q)", err, query)
+	}
+	return a, b, c
+}
+
+func mustQueryInt64Int64Int(t *testing.T, r *repo.Repository, query string, args ...interface{}) (int64, int64, int) {
+	t.Helper()
+	var a int64
+	var b int64
+	var c int
+	if err := r.DB().Raw(query, args...).Row().Scan(&a, &b, &c); err != nil {
+		t.Fatalf("query int64+int64+int failed: %v (query=%q)", err, query)
+	}
+	return a, b, c
+}

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

@@ -0,0 +1,377 @@
+package handler
+
+import (
+	"testing"
+)
+
+// ---------------------------------------------------------------------------
+// nodeSupportsV4 / nodeSupportsV6
+// ---------------------------------------------------------------------------
+
+func TestNodeSupportsV4_Nil(t *testing.T) {
+	if nodeSupportsV4(nil) {
+		t.Fatal("nil node must not support v4")
+	}
+}
+
+func TestNodeSupportsV6_Nil(t *testing.T) {
+	if nodeSupportsV6(nil) {
+		t.Fatal("nil node must not support v6")
+	}
+}
+
+func TestNodeSupportsV4_ExplicitV4(t *testing.T) {
+	n := &nodeRecord{ServerIPv4: "10.0.0.1"}
+	if !nodeSupportsV4(n) {
+		t.Fatal("explicit server_ip_v4 must support v4")
+	}
+}
+
+func TestNodeSupportsV6_ExplicitV6(t *testing.T) {
+	n := &nodeRecord{ServerIPv6: "2001:db8::1"}
+	if !nodeSupportsV6(n) {
+		t.Fatal("explicit server_ip_v6 must support v6")
+	}
+}
+
+func TestNodeSupportsV4_OnlyV6Set(t *testing.T) {
+	n := &nodeRecord{ServerIPv6: "2001:db8::1"}
+	if nodeSupportsV4(n) {
+		t.Fatal("node with only v6 should not support v4")
+	}
+}
+
+func TestNodeSupportsV6_OnlyV4Set(t *testing.T) {
+	n := &nodeRecord{ServerIPv4: "10.0.0.1"}
+	if nodeSupportsV6(n) {
+		t.Fatal("node with only v4 should not support v6")
+	}
+}
+
+func TestNodeSupportsV4_DualStack(t *testing.T) {
+	n := &nodeRecord{ServerIPv4: "10.0.0.1", ServerIPv6: "2001:db8::1"}
+	if !nodeSupportsV4(n) {
+		t.Fatal("dual-stack node must support v4")
+	}
+}
+
+func TestNodeSupportsV6_DualStack(t *testing.T) {
+	n := &nodeRecord{ServerIPv4: "10.0.0.1", ServerIPv6: "2001:db8::1"}
+	if !nodeSupportsV6(n) {
+		t.Fatal("dual-stack node must support v6")
+	}
+}
+
+func TestNodeSupportsV4_LegacyV4Only(t *testing.T) {
+	n := &nodeRecord{ServerIP: "192.168.1.1"}
+	if !nodeSupportsV4(n) {
+		t.Fatal("legacy v4 ip in server_ip must support v4")
+	}
+	if nodeSupportsV6(n) {
+		t.Fatal("legacy v4 ip in server_ip must not support v6")
+	}
+}
+
+func TestNodeSupportsV6_LegacyV6Only(t *testing.T) {
+	n := &nodeRecord{ServerIP: "2001:db8::1"}
+	if !nodeSupportsV6(n) {
+		t.Fatal("legacy v6 ip in server_ip must support v6")
+	}
+	if nodeSupportsV4(n) {
+		t.Fatal("legacy v6 ip in server_ip must not support v4")
+	}
+}
+
+func TestNodeSupportsV4_EmptyNode(t *testing.T) {
+	n := &nodeRecord{}
+	if nodeSupportsV4(n) {
+		t.Fatal("empty node must not support v4")
+	}
+	if nodeSupportsV6(n) {
+		t.Fatal("empty node must not support v6")
+	}
+}
+
+func TestNodeSupportsV4_LegacyBracketed(t *testing.T) {
+	n := &nodeRecord{ServerIP: "[::1]"}
+	if nodeSupportsV4(n) {
+		t.Fatal("bracketed ipv6 must not support v4")
+	}
+	if !nodeSupportsV6(n) {
+		t.Fatal("bracketed ipv6 must support v6")
+	}
+}
+
+// ---------------------------------------------------------------------------
+// pickNodeAddressV4 / pickNodeAddressV6
+// ---------------------------------------------------------------------------
+
+func TestPickNodeAddressV4_Nil(t *testing.T) {
+	if pickNodeAddressV4(nil) != "" {
+		t.Fatal("nil node must return empty")
+	}
+}
+
+func TestPickNodeAddressV6_Nil(t *testing.T) {
+	if pickNodeAddressV6(nil) != "" {
+		t.Fatal("nil node must return empty")
+	}
+}
+
+func TestPickNodeAddressV4_PreferExplicit(t *testing.T) {
+	n := &nodeRecord{ServerIPv4: "10.0.0.1", ServerIP: "192.168.0.1"}
+	got := pickNodeAddressV4(n)
+	if got != "10.0.0.1" {
+		t.Fatalf("expected explicit v4 10.0.0.1, got %q", got)
+	}
+}
+
+func TestPickNodeAddressV4_FallbackLegacy(t *testing.T) {
+	n := &nodeRecord{ServerIP: "192.168.0.1"}
+	got := pickNodeAddressV4(n)
+	if got != "192.168.0.1" {
+		t.Fatalf("expected legacy 192.168.0.1, got %q", got)
+	}
+}
+
+func TestPickNodeAddressV6_PreferExplicit(t *testing.T) {
+	n := &nodeRecord{ServerIPv6: "2001:db8::1", ServerIP: "::1"}
+	got := pickNodeAddressV6(n)
+	if got != "2001:db8::1" {
+		t.Fatalf("expected explicit v6 2001:db8::1, got %q", got)
+	}
+}
+
+func TestPickNodeAddressV6_FallbackLegacy(t *testing.T) {
+	n := &nodeRecord{ServerIP: "::1"}
+	got := pickNodeAddressV6(n)
+	if got != "::1" {
+		t.Fatalf("expected legacy ::1, got %q", got)
+	}
+}
+
+// ---------------------------------------------------------------------------
+// selectTunnelDialHost — core IP preference selection logic
+// ---------------------------------------------------------------------------
+
+func dualStackNode(name, v4, v6 string) *nodeRecord {
+	return &nodeRecord{
+		Name:       name,
+		ServerIPv4: v4,
+		ServerIPv6: v6,
+	}
+}
+
+func v4OnlyNode(name, v4 string) *nodeRecord {
+	return &nodeRecord{
+		Name:       name,
+		ServerIPv4: v4,
+	}
+}
+
+func v6OnlyNode(name, v6 string) *nodeRecord {
+	return &nodeRecord{
+		Name:       name,
+		ServerIPv6: v6,
+	}
+}
+
+func TestSelectTunnelDialHost_NilNodes(t *testing.T) {
+	_, err := selectTunnelDialHost(nil, nil, "")
+	if err == nil {
+		t.Fatal("expected error for nil nodes")
+	}
+	_, err = selectTunnelDialHost(dualStackNode("a", "1.1.1.1", "::1"), nil, "")
+	if err == nil {
+		t.Fatal("expected error for nil toNode")
+	}
+	_, err = selectTunnelDialHost(nil, dualStackNode("b", "1.1.1.1", "::1"), "")
+	if err == nil {
+		t.Fatal("expected error for nil fromNode")
+	}
+}
+
+func TestSelectTunnelDialHost_DualStack_DefaultPreference(t *testing.T) {
+	from := dualStackNode("from", "10.0.0.1", "2001:db8::1")
+	to := dualStackNode("to", "10.0.0.2", "2001:db8::2")
+
+	host, err := selectTunnelDialHost(from, to, "")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	// Default prefers v4 when both available
+	if host != "10.0.0.2" {
+		t.Fatalf("default preference should pick v4, got %q", host)
+	}
+}
+
+func TestSelectTunnelDialHost_DualStack_PreferV4(t *testing.T) {
+	from := dualStackNode("from", "10.0.0.1", "2001:db8::1")
+	to := dualStackNode("to", "10.0.0.2", "2001:db8::2")
+
+	host, err := selectTunnelDialHost(from, to, "v4")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if host != "10.0.0.2" {
+		t.Fatalf("v4 preference should pick v4 address, got %q", host)
+	}
+}
+
+func TestSelectTunnelDialHost_DualStack_PreferV6(t *testing.T) {
+	from := dualStackNode("from", "10.0.0.1", "2001:db8::1")
+	to := dualStackNode("to", "10.0.0.2", "2001:db8::2")
+
+	host, err := selectTunnelDialHost(from, to, "v6")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if host != "2001:db8::2" {
+		t.Fatalf("v6 preference should pick v6 address, got %q", host)
+	}
+}
+
+func TestSelectTunnelDialHost_V4Only_PreferV6Fallback(t *testing.T) {
+	from := v4OnlyNode("from", "10.0.0.1")
+	to := v4OnlyNode("to", "10.0.0.2")
+
+	// User prefers v6, but both nodes are v4-only — should fallback to v4
+	host, err := selectTunnelDialHost(from, to, "v6")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if host != "10.0.0.2" {
+		t.Fatalf("v6 preference on v4-only nodes should fallback to v4, got %q", host)
+	}
+}
+
+func TestSelectTunnelDialHost_V6Only_PreferV4Fallback(t *testing.T) {
+	from := v6OnlyNode("from", "2001:db8::1")
+	to := v6OnlyNode("to", "2001:db8::2")
+
+	// User prefers v4, but both nodes are v6-only — should fallback to v6
+	host, err := selectTunnelDialHost(from, to, "v4")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if host != "2001:db8::2" {
+		t.Fatalf("v4 preference on v6-only nodes should fallback to v6, got %q", host)
+	}
+}
+
+func TestSelectTunnelDialHost_Incompatible(t *testing.T) {
+	from := v4OnlyNode("from", "10.0.0.1")
+	to := v6OnlyNode("to", "2001:db8::2")
+
+	_, err := selectTunnelDialHost(from, to, "")
+	if err == nil {
+		t.Fatal("expected error for incompatible nodes (v4-only -> v6-only)")
+	}
+}
+
+func TestSelectTunnelDialHost_Incompatible_Reverse(t *testing.T) {
+	from := v6OnlyNode("from", "2001:db8::1")
+	to := v4OnlyNode("to", "10.0.0.2")
+
+	_, err := selectTunnelDialHost(from, to, "")
+	if err == nil {
+		t.Fatal("expected error for incompatible nodes (v6-only -> v4-only)")
+	}
+}
+
+func TestSelectTunnelDialHost_WhitespacePreference(t *testing.T) {
+	from := dualStackNode("from", "10.0.0.1", "2001:db8::1")
+	to := dualStackNode("to", "10.0.0.2", "2001:db8::2")
+
+	// Whitespace should be trimmed, treated as "v6"
+	host, err := selectTunnelDialHost(from, to, "  v6  ")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if host != "2001:db8::2" {
+		t.Fatalf("trimmed v6 preference should pick v6 address, got %q", host)
+	}
+}
+
+func TestSelectTunnelDialHost_MixedStack_FromDualToV4(t *testing.T) {
+	from := dualStackNode("from", "10.0.0.1", "2001:db8::1")
+	to := v4OnlyNode("to", "10.0.0.2")
+
+	// v6 preferred, but target only has v4 — should succeed with v4
+	host, err := selectTunnelDialHost(from, to, "v6")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if host != "10.0.0.2" {
+		t.Fatalf("should fallback to v4 when target is v4-only, got %q", host)
+	}
+}
+
+func TestSelectTunnelDialHost_MixedStack_FromDualToV6(t *testing.T) {
+	from := dualStackNode("from", "10.0.0.1", "2001:db8::1")
+	to := v6OnlyNode("to", "2001:db8::2")
+
+	// v4 preferred, but target only has v6 — should succeed with v6
+	host, err := selectTunnelDialHost(from, to, "v4")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if host != "2001:db8::2" {
+		t.Fatalf("should fallback to v6 when target is v6-only, got %q", host)
+	}
+}
+
+func TestSelectTunnelDialHost_MixedStack_FromV4ToDual(t *testing.T) {
+	from := v4OnlyNode("from", "10.0.0.1")
+	to := dualStackNode("to", "10.0.0.2", "2001:db8::2")
+
+	// v6 preferred, but from only has v4 — should use v4 (from can only reach v4 of target)
+	host, err := selectTunnelDialHost(from, to, "v6")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if host != "10.0.0.2" {
+		t.Fatalf("should use v4 when from is v4-only, got %q", host)
+	}
+}
+
+func TestSelectTunnelDialHost_MixedStack_FromV6ToDual(t *testing.T) {
+	from := v6OnlyNode("from", "2001:db8::1")
+	to := dualStackNode("to", "10.0.0.2", "2001:db8::2")
+
+	// v4 preferred, but from only has v6 — should use v6
+	host, err := selectTunnelDialHost(from, to, "v4")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if host != "2001:db8::2" {
+		t.Fatalf("should use v6 when from is v6-only, got %q", host)
+	}
+}
+
+// ---------------------------------------------------------------------------
+// nodeDisplayName
+// ---------------------------------------------------------------------------
+
+func TestNodeDisplayName_Nil(t *testing.T) {
+	got := nodeDisplayName(nil)
+	if got != "node" {
+		t.Fatalf("nil node display name should be 'node', got %q", got)
+	}
+}
+
+func TestNodeDisplayName_Named(t *testing.T) {
+	n := &nodeRecord{ID: 42, Name: "hk-node"}
+	got := nodeDisplayName(n)
+	if got != "hk-node" {
+		t.Fatalf("expected 'hk-node', got %q", got)
+	}
+}
+
+func TestNodeDisplayName_Unnamed(t *testing.T) {
+	n := &nodeRecord{ID: 42}
+	got := nodeDisplayName(n)
+	if got != "node_42" {
+		t.Fatalf("expected 'node_42', got %q", got)
+	}
+}

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

@@ -0,0 +1,285 @@
+package handler
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"go-backend/internal/http/response"
+	"go-backend/internal/store/repo"
+)
+
+func TestPickPeerSharePortUsesRuntimeReservations(t *testing.T) {
+	r, err := repo.Open(filepath.Join(t.TempDir(), "panel.db"))
+	if err != nil {
+		t.Fatalf("open repo: %v", err)
+	}
+	defer r.Close()
+
+	h := &Handler{repo: r}
+	now := time.Now().UnixMilli()
+
+	if err := r.DB().Exec(`INSERT INTO chain_tunnel(tunnel_id, chain_type, node_id, port, strategy, inx, protocol) VALUES(?, ?, ?, ?, ?, ?, ?)`, 1, 2, 1, 3000, "round", 1, "tls").Error; err != nil {
+		t.Fatalf("insert chain_tunnel: %v", err)
+	}
+	if err := r.DB().Exec(`INSERT INTO forward_port(forward_id, node_id, port) VALUES(?, ?, ?)`, 1, 1, 3001).Error; err != nil {
+		t.Fatalf("insert forward_port: %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(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, 77, 1, "res-1", "rk-1", "b-1", "exit", "", "fed_svc_1", "tls", "round", 3002, "", 1, 1, now, now).Error; err != nil {
+		t.Fatalf("insert peer_share_runtime: %v", err)
+	}
+
+	share := &repo.PeerShare{
+		ID:             77,
+		NodeID:         1,
+		PortRangeStart: 3000,
+		PortRangeEnd:   3004,
+	}
+
+	port, err := h.pickPeerSharePort(share, 0)
+	if err != nil {
+		t.Fatalf("pick auto port: %v", err)
+	}
+	if port != 3003 {
+		t.Fatalf("expected port 3003, got %d", port)
+	}
+
+	if _, err := h.pickPeerSharePort(share, 3001); err == nil {
+		t.Fatalf("expected requested busy port to fail")
+	}
+}
+
+func TestApplyTunnelRuntimeSkipsRemoteChainAndOutNodes(t *testing.T) {
+	r, err := repo.Open(filepath.Join(t.TempDir(), "rt-skip.db"))
+	if err != nil {
+		t.Fatalf("open repo: %v", err)
+	}
+	defer r.Close()
+
+	h := &Handler{repo: r}
+	now := time.Now().UnixMilli()
+	for _, n := range []struct {
+		id   int64
+		name string
+		ip   string
+	}{
+		{12, "remote-chain", "10.99.0.2"},
+		{13, "remote-out", "10.99.0.3"},
+	} {
+		if err := r.DB().Exec(`
+			INSERT INTO node(id, 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)
+			VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+		`, n.id, n.name, n.name+"-secret", n.ip, n.ip, "", "40000-40010", "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", 0, 1, "http://remote-peer", "remote-token").Error; err != nil {
+			t.Fatalf("insert node %s: %v", n.name, err)
+		}
+	}
+
+	state := &tunnelCreateState{
+		TunnelID: 1,
+		Type:     2,
+		InNodes:  []tunnelRuntimeNode{},
+		ChainHops: [][]tunnelRuntimeNode{
+			{
+				{NodeID: 12, ChainType: 2, Inx: 1, Port: 41000, Protocol: "tls", Strategy: "round"},
+			},
+		},
+		OutNodes: []tunnelRuntimeNode{
+			{NodeID: 13, ChainType: 3, Port: 42000, Protocol: "tls", Strategy: "round"},
+		},
+		Nodes: map[int64]*nodeRecord{
+			12: {ID: 12, Name: "remote-chain", IsRemote: 1, ServerIPv4: "10.99.0.2"},
+			13: {ID: 13, Name: "remote-out", IsRemote: 1, ServerIPv4: "10.99.0.3"},
+		},
+	}
+
+	chains, services, err := h.applyTunnelRuntime(state)
+	if err != nil {
+		t.Fatalf("apply runtime: %v", err)
+	}
+	if len(chains) != 0 {
+		t.Fatalf("expected no local chains for remote-only nodes, got %d", len(chains))
+	}
+	if len(services) != 0 {
+		t.Fatalf("expected no local services for remote-only nodes, got %d", len(services))
+	}
+}
+
+func TestPrepareTunnelCreateStateRemoteAutoPortDefersToFederation(t *testing.T) {
+	r, err := repo.Open(filepath.Join(t.TempDir(), "panel.db"))
+	if err != nil {
+		t.Fatalf("open repo: %v", err)
+	}
+	defer r.Close()
+
+	h := &Handler{repo: r}
+	now := time.Now().UnixMilli()
+
+	insertNode := func(name string, status int, portRange string, isRemote int) int64 {
+		if execErr := 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(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+		`, name, name+"-secret", "10.0.0.1", "10.0.0.1", "", portRange, "", "v1", 1, 1, 1, now, now, status, "[::]", "[::]", 0, isRemote, "http://peer", "peer-token", `{"shareId":1}`).Error; execErr != nil {
+			t.Fatalf("insert node %s: %v", name, execErr)
+		}
+		return mustLastInsertID(t, r, name)
+	}
+
+	entryID := insertNode("entry", 1, "31000-31010", 0)
+	remoteOutID := insertNode("remote-out", 1, "30000", 1)
+
+	if err := r.DB().Exec(`INSERT INTO forward_port(forward_id, node_id, port) VALUES(?, ?, ?)`, 1, remoteOutID, 30000).Error; err != nil {
+		t.Fatalf("insert forward_port: %v", err)
+	}
+
+	tx := r.DB().Begin()
+	if tx.Error != nil {
+		t.Fatalf("begin tx: %v", err)
+	}
+	defer tx.Rollback()
+
+	req := map[string]interface{}{
+		"name": "test-tunnel",
+		"inNodeId": []interface{}{
+			map[string]interface{}{"nodeId": float64(entryID), "protocol": "tls", "strategy": "round"},
+		},
+		"outNodeId": []interface{}{
+			map[string]interface{}{"nodeId": float64(remoteOutID), "protocol": "tls", "strategy": "round", "port": float64(0)},
+		},
+		"chainNodes": []interface{}{},
+	}
+
+	state, err := h.prepareTunnelCreateState(tx, req, 2, 0)
+	if err != nil {
+		t.Fatalf("prepare state should not fail for remote auto-port: %v", err)
+	}
+	if len(state.OutNodes) != 1 {
+		t.Fatalf("expected 1 out node, got %d", len(state.OutNodes))
+	}
+	if state.OutNodes[0].Port != 0 {
+		t.Fatalf("expected remote out port to remain 0 before federation reserve, got %d", state.OutNodes[0].Port)
+	}
+}
+
+func TestPrepareTunnelCreateStateAllowsOfflineRemoteMiddleNode(t *testing.T) {
+	r, err := repo.Open(filepath.Join(t.TempDir(), "panel.db"))
+	if err != nil {
+		t.Fatalf("open repo: %v", err)
+	}
+	defer r.Close()
+
+	h := &Handler{repo: r}
+	now := time.Now().UnixMilli()
+
+	insertNode := func(name string, status int, portRange string, isRemote int) int64 {
+		if execErr := 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(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+		`, name, name+"-secret", "10.0.0.1", "10.0.0.1", "", portRange, "", "v1", 1, 1, 1, now, now, status, "[::]", "[::]", 0, isRemote, "http://peer", "peer-token", `{"shareId":2}`).Error; execErr != nil {
+			t.Fatalf("insert node %s: %v", name, execErr)
+		}
+		return mustLastInsertID(t, r, name)
+	}
+
+	entryID := insertNode("entry-local", 1, "32000-32010", 0)
+	remoteMiddleID := insertNode("middle-remote", 0, "33000-33010", 1)
+	outID := insertNode("out-local", 1, "34000-34010", 0)
+
+	tx := r.DB().Begin()
+	if tx.Error != nil {
+		t.Fatalf("begin tx: %v", err)
+	}
+	defer tx.Rollback()
+
+	req := map[string]interface{}{
+		"name": "remote-middle-offline-status",
+		"inNodeId": []interface{}{
+			map[string]interface{}{"nodeId": float64(entryID), "protocol": "tls", "strategy": "round"},
+		},
+		"chainNodes": []interface{}{
+			[]interface{}{
+				map[string]interface{}{"nodeId": float64(remoteMiddleID), "protocol": "tls", "strategy": "round", "port": float64(0)},
+			},
+		},
+		"outNodeId": []interface{}{
+			map[string]interface{}{"nodeId": float64(outID), "protocol": "tls", "strategy": "round", "port": float64(0)},
+		},
+	}
+
+	state, err := h.prepareTunnelCreateState(tx, req, 2, 0)
+	if err != nil {
+		t.Fatalf("prepare state should allow offline remote middle node: %v", err)
+	}
+	if len(state.ChainHops) != 1 || len(state.ChainHops[0]) != 1 {
+		t.Fatalf("expected one middle hop node, got %+v", state.ChainHops)
+	}
+	if state.ChainHops[0][0].NodeID != remoteMiddleID {
+		t.Fatalf("expected remote middle node id %d, got %d", remoteMiddleID, state.ChainHops[0][0].NodeID)
+	}
+	if state.Nodes[remoteMiddleID] == nil || state.Nodes[remoteMiddleID].IsRemote != 1 {
+		t.Fatalf("expected remote middle node metadata in state")
+	}
+}
+
+func TestFederationRuntimeReservePortRejectsWhenShareFlowExceeded(t *testing.T) {
+	r, err := repo.Open(filepath.Join(t.TempDir(), "panel.db"))
+	if err != nil {
+		t.Fatalf("open repo: %v", err)
+	}
+	defer r.Close()
+
+	h := &Handler{repo: r}
+	now := time.Now().UnixMilli()
+
+	if err := r.CreatePeerShare(&repo.PeerShare{
+		Name:           "limited-share",
+		NodeID:         1,
+		Token:          "limited-token",
+		MaxBandwidth:   2048,
+		CurrentFlow:    2048,
+		PortRangeStart: 30000,
+		PortRangeEnd:   30010,
+		IsActive:       1,
+		CreatedTime:    now,
+		UpdatedTime:    now,
+	}); err != nil {
+		t.Fatalf("create share: %v", err)
+	}
+
+	body, err := json.Marshal(map[string]interface{}{
+		"resourceKey":   "tunnel:1:node:1:type:3:hop:0",
+		"protocol":      "tls",
+		"requestedPort": 0,
+	})
+	if err != nil {
+		t.Fatalf("marshal request: %v", err)
+	}
+
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/federation/runtime/reserve-port", bytes.NewReader(body))
+	req.Header.Set("Authorization", "Bearer limited-token")
+	req.Header.Set("Content-Type", "application/json")
+	res := httptest.NewRecorder()
+
+	h.federationRuntimeReservePort(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 != 403 {
+		t.Fatalf("expected response code 403, got %d (%s)", payload.Code, payload.Msg)
+	}
+	if payload.Msg != "Share traffic limit exceeded" {
+		t.Fatalf("unexpected response message: %q", payload.Msg)
+	}
+}

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

@@ -1,11 +1,13 @@
 package handler
 
 import (
-	"database/sql"
 	"encoding/json"
+	"log"
 	"strconv"
 	"strings"
 	"time"
+
+	"go-backend/internal/store/model"
 )
 
 const bytesPerGB int64 = 1024 * 1024 * 1024
@@ -31,23 +33,29 @@ 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
 	}
 
 	forwardID, userID, userTunnelID, ok := parseFlowServiceIDs(serviceName)
-	if !ok {
+	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)
+		}
 		return
 	}
 
-	inFlow, outFlow := h.scaleFlowByTunnel(forwardID, item.D, item.U)
-	_ = h.repo.AddFlow(forwardID, userID, userTunnelID, inFlow, outFlow)
-
-	if userTunnelID > 0 {
-		h.enforceFlowPolicies(userID, userTunnelID)
+	runtimeID, ok := parsePeerShareRuntimeServiceID(serviceName)
+	if !ok {
+		return
 	}
+	h.processPeerShareFlow(runtimeID, item)
 }
 
 func parseFlowServiceIDs(serviceName string) (int64, int64, int64, bool) {
@@ -66,6 +74,226 @@ func parseFlowServiceIDs(serviceName string) (int64, int64, int64, bool) {
 	return forwardID, userID, userTunnelID, true
 }
 
+func parsePeerShareRuntimeServiceID(serviceName string) (int64, bool) {
+	const prefix = "fed_svc_"
+	if !strings.HasPrefix(serviceName, prefix) {
+		return 0, false
+	}
+	raw := strings.TrimPrefix(serviceName, prefix)
+	if raw == "" {
+		return 0, false
+	}
+	parts := strings.SplitN(raw, "_", 2)
+	runtimeID, err := strconv.ParseInt(parts[0], 10, 64)
+	if err != nil || runtimeID <= 0 {
+		return 0, false
+	}
+	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
+	}
+	runtime, err := h.repo.GetPeerShareRuntimeByID(runtimeID)
+	if err != nil || runtime == nil || runtime.ShareID <= 0 || runtime.Status != 1 {
+		return
+	}
+
+	delta := item.D + item.U
+	if delta <= 0 {
+		return
+	}
+
+	_ = h.repo.AddPeerShareCurrentFlow(runtime.ShareID, delta)
+
+	share, err := h.repo.GetPeerShare(runtime.ShareID)
+	if err != nil || share == nil {
+		return
+	}
+	if !isPeerShareFlowExceeded(share) {
+		return
+	}
+	h.enforcePeerShareFlowLimit(share.ID)
+}
+
+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
+	}
+	runtimes, err := h.repo.ListActivePeerShareRuntimesByShareID(shareID)
+	if err != nil || len(runtimes) == 0 {
+		return
+	}
+
+	now := time.Now().UnixMilli()
+	for _, runtime := range runtimes {
+		if h.wsServer != nil && runtime.Applied == 1 {
+			if strings.TrimSpace(runtime.ServiceName) != "" {
+				_, _ = h.sendNodeCommand(runtime.NodeID, "DeleteService", map[string]interface{}{"services": []string{runtime.ServiceName}}, false, true)
+			}
+			if strings.TrimSpace(runtime.Role) == "middle" && strings.TrimSpace(runtime.ChainName) != "" {
+				_, _ = h.sendNodeCommand(runtime.NodeID, "DeleteChains", map[string]interface{}{"chain": runtime.ChainName}, false, true)
+			}
+		}
+		_ = h.repo.MarkPeerShareRuntimeReleased(runtime.ID, now)
+	}
+}
+
 func (h *Handler) scaleFlowByTunnel(forwardID int64, inFlow int64, outFlow int64) (int64, int64) {
 	forward, err := h.getForwardRecord(forwardID)
 	if err != nil || forward == nil {
@@ -136,22 +364,18 @@ func (h *Handler) getUserTunnelPolicy(userTunnelID int64) (*userTunnelPolicy, er
 	if userTunnelID <= 0 {
 		return nil, nil
 	}
-
-	row := h.repo.DB().QueryRow(`
-		SELECT id, user_id, tunnel_id, flow, in_flow, out_flow, exp_time, status
-		FROM user_tunnel
-		WHERE id = ?
-		LIMIT 1
-	`, userTunnelID)
-
-	var policy userTunnelPolicy
-	if err := row.Scan(&policy.ID, &policy.UserID, &policy.TunnelID, &policy.Flow, &policy.InFlow, &policy.OutFlow, &policy.ExpTime, &policy.Status); err != nil {
-		if err == sql.ErrNoRows {
-			return nil, nil
-		}
+	ut, err := h.repo.GetUserTunnelByID(userTunnelID)
+	if err != nil {
 		return nil, err
 	}
-	return &policy, nil
+	if ut == nil {
+		return nil, nil
+	}
+	return &userTunnelPolicy{
+		ID: ut.ID, UserID: ut.UserID, TunnelID: ut.TunnelID,
+		Flow: ut.Flow, InFlow: ut.InFlow, OutFlow: ut.OutFlow,
+		ExpTime: ut.ExpTime, Status: ut.Status,
+	}, nil
 }
 
 func (h *Handler) pauseUserForwards(userID int64, now int64) {
@@ -174,60 +398,20 @@ func (h *Handler) pauseForwardRecords(forwards []forwardRecord, now int64) {
 	for i := range forwards {
 		forward := forwards[i]
 		_ = h.controlForwardServices(&forward, "PauseService", false)
-		_, _ = h.repo.DB().Exec(`UPDATE forward SET status = 0, updated_time = ? WHERE id = ?`, now, forward.ID)
+		_ = h.repo.UpdateForwardStatus(forward.ID, 0, now)
 	}
 }
 
 func (h *Handler) listActiveForwardsByUser(userID int64) ([]forwardRecord, error) {
-	rows, err := h.repo.DB().Query(`
-		SELECT id, user_id, user_name, name, tunnel_id, remote_addr, strategy, status
-		FROM forward
-		WHERE user_id = ? AND status = 1
-		ORDER BY id ASC
-	`, userID)
-	if err != nil {
-		return nil, err
-	}
-	defer rows.Close()
-
-	return scanForwardRecords(rows)
+	return h.repo.ListActiveForwardsByUser(userID)
 }
 
 func (h *Handler) listActiveForwardsByUserTunnel(userID int64, tunnelID int64) ([]forwardRecord, error) {
-	rows, err := h.repo.DB().Query(`
-		SELECT id, user_id, user_name, name, tunnel_id, remote_addr, strategy, status
-		FROM forward
-		WHERE user_id = ? AND tunnel_id = ? AND status = 1
-		ORDER BY id ASC
-	`, userID, tunnelID)
-	if err != nil {
-		return nil, err
-	}
-	defer rows.Close()
-
-	return scanForwardRecords(rows)
-}
-
-func scanForwardRecords(rows *sql.Rows) ([]forwardRecord, error) {
-	out := make([]forwardRecord, 0)
-	for rows.Next() {
-		var record forwardRecord
-		if err := rows.Scan(&record.ID, &record.UserID, &record.UserName, &record.Name, &record.TunnelID, &record.RemoteAddr, &record.Strategy, &record.Status); err != nil {
-			return nil, err
-		}
-		if strings.TrimSpace(record.Strategy) == "" {
-			record.Strategy = "fifo"
-		}
-		out = append(out, record)
-	}
-	if err := rows.Err(); err != nil {
-		return nil, err
-	}
-	return out, nil
+	return h.repo.ListActiveForwardsByUserTunnel(userID, tunnelID)
 }
 
 func (h *Handler) cleanNodeConfigs(nodeID int64, rawConfig string) {
-	if h == nil || h.repo == nil || h.repo.DB() == nil || nodeID <= 0 {
+	if h == nil || h.repo == nil || nodeID <= 0 {
 		return
 	}
 	if strings.TrimSpace(rawConfig) == "" {
@@ -245,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
@@ -273,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
 			}
@@ -312,15 +530,13 @@ func (h *Handler) cleanOrphanedLimiters(nodeID int64, limiters []namedConfigItem
 }
 
 func (h *Handler) tunnelExists(tunnelID int64) bool {
-	var count int
-	err := h.repo.DB().QueryRow(`SELECT COUNT(1) FROM tunnel WHERE id = ?`, tunnelID).Scan(&count)
-	return err == nil && count > 0
+	ok, _ := h.repo.TunnelExists(tunnelID)
+	return ok
 }
 
 func (h *Handler) forwardExists(forwardID int64) bool {
-	var count int
-	err := h.repo.DB().QueryRow(`SELECT COUNT(1) FROM forward WHERE id = ?`, forwardID).Scan(&count)
-	return err == nil && count > 0
+	ok, _ := h.repo.ForwardExists(forwardID)
+	return ok
 }
 
 func (h *Handler) speedLimiterExists(name string) bool {
@@ -331,8 +547,6 @@ func (h *Handler) speedLimiterExists(name string) bool {
 	if err != nil || id <= 0 {
 		return false
 	}
-
-	var count int
-	err = h.repo.DB().QueryRow(`SELECT COUNT(1) FROM speed_limit WHERE id = ?`, id).Scan(&count)
-	return err == nil && count > 0
+	ok, _ := h.repo.SpeedLimitExists(id)
+	return ok
 }

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

@@ -0,0 +1,406 @@
+package handler
+
+import (
+	"path/filepath"
+	"strconv"
+	"testing"
+	"time"
+
+	"go-backend/internal/store/repo"
+)
+
+func TestProcessFlowItemTracksPeerShareFlowAndEnforcesLimit(t *testing.T) {
+	r, err := repo.Open(filepath.Join(t.TempDir(), "panel.db"))
+	if err != nil {
+		t.Fatalf("open repo: %v", err)
+	}
+	defer r.Close()
+
+	now := time.Now().UnixMilli()
+	if err := r.CreatePeerShare(&repo.PeerShare{
+		Name:           "flow-share",
+		NodeID:         1,
+		Token:          "flow-share-token",
+		MaxBandwidth:   3000,
+		CurrentFlow:    1000,
+		PortRangeStart: 32000,
+		PortRangeEnd:   32010,
+		IsActive:       1,
+		CreatedTime:    now,
+		UpdatedTime:    now,
+	}); err != nil {
+		t.Fatalf("create peer share: %v", err)
+	}
+	share, err := r.GetPeerShareByToken("flow-share-token")
+	if err != nil || share == nil {
+		t.Fatalf("load peer 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(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, 17, share.ID, share.NodeID, "res-17", "rk-17", "17", "exit", "", "fed_svc_17", "tls", "round", 32001, "", 1, 1, now, now).Error; err != nil {
+		t.Fatalf("insert peer_share_runtime: %v", err)
+	}
+
+	h := &Handler{repo: r}
+	h.processFlowItem(1, flowItem{N: "fed_svc_17", U: 1200, D: 900})
+
+	updatedShare, err := r.GetPeerShare(share.ID)
+	if err != nil || updatedShare == nil {
+		t.Fatalf("reload share: %v", err)
+	}
+	if updatedShare.CurrentFlow != 3100 {
+		t.Fatalf("expected current_flow=3100, got %d", updatedShare.CurrentFlow)
+	}
+
+	runtime, err := r.GetPeerShareRuntimeByID(17)
+	if err != nil || runtime == nil {
+		t.Fatalf("reload runtime: %v", err)
+	}
+	if runtime.Status != 0 {
+		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

@@ -18,19 +18,25 @@ import (
 	"go-backend/internal/http/middleware"
 	"go-backend/internal/http/response"
 	"go-backend/internal/security"
-	"go-backend/internal/store/sqlite"
+	"go-backend/internal/store/repo"
 	"go-backend/internal/ws"
 )
 
 type Handler struct {
-	repo      *sqlite.Repository
+	repo      *repo.Repository
 	jwtSecret string
 	wsServer  *ws.Server
 
+	captchaMu     sync.Mutex
+	captchaTokens map[string]int64
+
 	jobsMu      sync.Mutex
 	jobsCancel  context.CancelFunc
 	jobsStarted bool
 	jobsWG      sync.WaitGroup
+
+	upgradeMu              sync.Mutex
+	pendingUpgradeRedeploy map[int64]struct{}
 }
 
 type loginRequest struct {
@@ -39,6 +45,11 @@ type loginRequest struct {
 	CaptchaID string `json:"captchaId"`
 }
 
+type captchaVerifyRequest struct {
+	ID   string `json:"id"`
+	Data string `json:"data"`
+}
+
 type nameRequest struct {
 	Name string `json:"name"`
 }
@@ -61,12 +72,16 @@ type flowItem struct {
 	D int64  `json:"d"`
 }
 
-func New(repo *sqlite.Repository, jwtSecret string) *Handler {
-	return &Handler{
-		repo:      repo,
-		jwtSecret: jwtSecret,
-		wsServer:  ws.NewServer(repo, jwtSecret),
+func New(repo *repo.Repository, jwtSecret string) *Handler {
+	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 {
@@ -80,11 +95,19 @@ 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)
 	mux.HandleFunc("/api/v1/config/update-single", h.updateSingleConfig)
+	mux.HandleFunc("/api/v1/backup/export", h.backupExport)
+	mux.HandleFunc("/api/v1/backup/import", h.backupImport)
+	mux.HandleFunc("/api/v1/backup/restore", h.backupImport)
+	mux.HandleFunc("/api/v1/api/v1/backup/export", h.backupExport)
+	mux.HandleFunc("/api/v1/api/v1/backup/import", h.backupImport)
+	mux.HandleFunc("/api/v1/api/v1/backup/restore", h.backupImport)
 	mux.HandleFunc("/api/v1/captcha/check", h.checkCaptcha)
+	mux.HandleFunc("/api/v1/captcha/verify", h.captchaVerify)
 	mux.HandleFunc("/api/v1/user/package", h.userPackage)
 	mux.HandleFunc("/api/v1/user/updatePassword", h.updatePassword)
 	mux.HandleFunc("/api/v1/node/list", h.nodeList)
@@ -95,6 +118,10 @@ func (h *Handler) Register(mux *http.ServeMux) {
 	mux.HandleFunc("/api/v1/node/update-order", h.nodeUpdateOrder)
 	mux.HandleFunc("/api/v1/node/batch-delete", h.nodeBatchDelete)
 	mux.HandleFunc("/api/v1/node/check-status", h.nodeCheckStatus)
+	mux.HandleFunc("/api/v1/node/upgrade", h.nodeUpgrade)
+	mux.HandleFunc("/api/v1/node/batch-upgrade", h.nodeBatchUpgrade)
+	mux.HandleFunc("/api/v1/node/rollback", h.nodeRollback)
+	mux.HandleFunc("/api/v1/node/releases", h.listReleases)
 	mux.HandleFunc("/api/v1/tunnel/list", h.tunnelList)
 	mux.HandleFunc("/api/v1/tunnel/create", h.tunnelCreate)
 	mux.HandleFunc("/api/v1/tunnel/get", h.tunnelGet)
@@ -143,6 +170,22 @@ func (h *Handler) Register(mux *http.ServeMux) {
 	mux.HandleFunc("/api/v1/group/permission/assign", h.groupPermissionAssign)
 	mux.HandleFunc("/api/v1/group/permission/remove", h.groupPermissionRemove)
 	mux.HandleFunc("/api/v1/open_api/sub_store", h.openAPISubStore)
+	mux.HandleFunc("/api/v1/federation/share/list", h.federationShareList)
+	mux.HandleFunc("/api/v1/federation/share/create", h.federationShareCreate)
+	mux.HandleFunc("/api/v1/federation/share/update", h.federationShareUpdate)
+	mux.HandleFunc("/api/v1/federation/share/delete", h.federationShareDelete)
+	mux.HandleFunc("/api/v1/federation/share/reset-flow", h.federationShareResetFlow)
+	mux.HandleFunc("/api/v1/federation/share/remote-usage/list", h.federationRemoteUsageList)
+	mux.HandleFunc("/api/v1/federation/connect", h.authPeer(h.federationConnect))
+	mux.HandleFunc("/api/v1/federation/tunnel/create", h.authPeer(h.federationTunnelCreate))
+	mux.HandleFunc("/api/v1/federation/runtime/reserve-port", h.authPeer(h.federationRuntimeReservePort))
+	mux.HandleFunc("/api/v1/federation/runtime/apply-role", h.authPeer(h.federationRuntimeApplyRole))
+	mux.HandleFunc("/api/v1/federation/runtime/release-role", h.authPeer(h.federationRuntimeReleaseRole))
+	mux.HandleFunc("/api/v1/federation/runtime/diagnose", h.authPeer(h.federationRuntimeDiagnose))
+	mux.HandleFunc("/api/v1/federation/runtime/command", h.authPeer(h.federationRuntimeCommand))
+	mux.HandleFunc("/api/v1/federation/node/import", h.nodeImport)
+	mux.HandleFunc("/api/v1/announcement/get", h.getAnnouncement)
+	mux.HandleFunc("/api/v1/announcement/update", h.updateAnnouncement)
 
 	mux.HandleFunc("/flow/test", h.flowTest)
 	mux.HandleFunc("/flow/config", h.flowConfig)
@@ -176,21 +219,24 @@ func (h *Handler) login(w http.ResponseWriter, r *http.Request) {
 		response.WriteJSON(w, response.Err(-2, err.Error()))
 		return
 	}
-	if captchaEnabled {
-		if strings.TrimSpace(req.CaptchaID) == "" {
+	if captchaEnabled && !h.apiClientCaptchaBypassEnabled(r) {
+		captchaID := strings.TrimSpace(req.CaptchaID)
+		if captchaID == "" {
 			response.WriteJSON(w, response.ErrDefault("验证码校验失败"))
 			return
 		}
 
-		secretCfg, err := h.repo.GetConfigByName("cloudflare_secret_key")
-		if err != nil || secretCfg == nil || secretCfg.Value == "" {
-			response.WriteJSON(w, response.ErrDefault("验证码配置错误：未配置Secret Key"))
-			return
-		}
+		if !h.consumeCaptchaToken(captchaID) {
+			secretCfg, err := h.repo.GetConfigByName("cloudflare_secret_key")
+			if err != nil || secretCfg == nil || strings.TrimSpace(secretCfg.Value) == "" {
+				response.WriteJSON(w, response.ErrDefault("验证码校验失败"))
+				return
+			}
 
-		if !h.verifyCloudflareTurnstile(req.CaptchaID, secretCfg.Value) {
-			response.WriteJSON(w, response.ErrDefault("验证码校验失败"))
-			return
+			if !h.verifyCloudflareTurnstile(captchaID, strings.TrimSpace(secretCfg.Value)) {
+				response.WriteJSON(w, response.ErrDefault("验证码校验失败"))
+				return
+			}
 		}
 	}
 
@@ -276,11 +322,35 @@ func (h *Handler) userList(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
+	var req struct {
+		Current int    `json:"current"`
+		Size    int    `json:"size"`
+		Keyword string `json:"keyword"`
+	}
+	if err := decodeJSON(r.Body, &req); err != nil && err != io.EOF {
+		response.WriteJSON(w, response.ErrDefault("请求参数错误"))
+		return
+	}
+
 	users, err := h.repo.ListUsers()
 	if err != nil {
 		response.WriteJSON(w, response.Err(-2, err.Error()))
 		return
 	}
+
+	keyword := strings.ToLower(strings.TrimSpace(req.Keyword))
+	if keyword != "" {
+		filtered := make([]map[string]interface{}, 0, len(users))
+		for _, item := range users {
+			username := strings.ToLower(strings.TrimSpace(fmt.Sprint(item["user"])))
+			displayName := strings.ToLower(strings.TrimSpace(fmt.Sprint(item["name"])))
+			if strings.Contains(username, keyword) || strings.Contains(displayName, keyword) {
+				filtered = append(filtered, item)
+			}
+		}
+		users = filtered
+	}
+
 	response.WriteJSON(w, response.OK(users))
 }
 
@@ -295,6 +365,9 @@ func (h *Handler) nodeList(w http.ResponseWriter, r *http.Request) {
 		response.WriteJSON(w, response.Err(-2, err.Error()))
 		return
 	}
+
+	h.syncRemoteNodeStatuses(items)
+
 	response.WriteJSON(w, response.OK(items))
 }
 
@@ -360,7 +433,7 @@ func (h *Handler) openAPISubStore(w http.ResponseWriter, r *http.Request) {
 		response.WriteJSON(w, response.ErrDefault("请求失败"))
 		return
 	}
-	if h == nil || h.repo == nil || h.repo.DB() == nil {
+	if h == nil || h.repo == nil {
 		response.WriteJSON(w, response.Err(-2, "database unavailable"))
 		return
 	}
@@ -403,27 +476,21 @@ func (h *Handler) openAPISubStore(w http.ResponseWriter, r *http.Request) {
 			return
 		}
 
-		var userID int64
-		var inFlow int64
-		var outFlow int64
-		var flow int64
-		var expTime int64
-		err = h.repo.DB().QueryRow(`SELECT user_id, in_flow, out_flow, flow, exp_time FROM user_tunnel WHERE id = ? LIMIT 1`, tunnelID).
-			Scan(&userID, &inFlow, &outFlow, &flow, &expTime)
+		ut, err := h.repo.GetUserTunnelByID(tunnelID)
 		if err != nil {
-			if err == sql.ErrNoRows {
-				response.WriteJSON(w, response.ErrDefault("隧道不存在"))
-				return
-			}
 			response.WriteJSON(w, response.Err(-2, err.Error()))
 			return
 		}
-		if userID != user.ID {
+		if ut == nil {
+			response.WriteJSON(w, response.ErrDefault("隧道不存在"))
+			return
+		}
+		if ut.UserID != user.ID {
 			response.WriteJSON(w, response.ErrDefault("隧道不存在"))
 			return
 		}
 
-		headerValue = buildSubscriptionHeader(outFlow, inFlow, flow*giga, expTime/1000)
+		headerValue = buildSubscriptionHeader(ut.OutFlow, ut.InFlow, ut.Flow*giga, ut.ExpTime/1000)
 	}
 
 	w.Header().Set("subscription-userinfo", headerValue)
@@ -579,6 +646,40 @@ func (h *Handler) checkCaptcha(w http.ResponseWriter, r *http.Request) {
 	response.WriteJSON(w, response.OK(0))
 }
 
+func (h *Handler) captchaVerify(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		response.WriteJSON(w, response.ErrDefault("请求失败"))
+		return
+	}
+
+	var req captchaVerifyRequest
+	if err := decodeJSON(r.Body, &req); err != nil {
+		h.writeCaptchaVerifyResult(w, false, "")
+		return
+	}
+	id := strings.TrimSpace(req.ID)
+	data := strings.TrimSpace(req.Data)
+	if id == "" || data == "" {
+		h.writeCaptchaVerifyResult(w, false, "")
+		return
+	}
+
+	verified := false
+	secretCfg, err := h.repo.GetConfigByName("cloudflare_secret_key")
+	if err == nil && secretCfg != nil && strings.TrimSpace(secretCfg.Value) != "" {
+		verified = h.verifyCloudflareTurnstile(data, strings.TrimSpace(secretCfg.Value))
+	} else {
+		verified = data == "ok"
+	}
+	if !verified {
+		h.writeCaptchaVerifyResult(w, false, "")
+		return
+	}
+
+	h.markCaptchaToken(id)
+	h.writeCaptchaVerifyResult(w, true, id)
+}
+
 func (h *Handler) flowTest(w http.ResponseWriter, _ *http.Request) {
 	w.Header().Set("Content-Type", "text/plain; charset=utf-8")
 	_, _ = w.Write([]byte("test"))
@@ -603,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
@@ -614,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)
 			}
 		}
 	}
@@ -893,6 +995,83 @@ func (h *Handler) captchaEnabled() (bool, error) {
 	return strings.EqualFold(cfg.Value, "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) {
+	if h == nil {
+		return
+	}
+	token = strings.TrimSpace(token)
+	if token == "" {
+		return
+	}
+	now := time.Now().UnixMilli()
+	exp := now + int64(5*time.Minute/time.Millisecond)
+
+	h.captchaMu.Lock()
+	defer h.captchaMu.Unlock()
+	if h.captchaTokens == nil {
+		h.captchaTokens = make(map[string]int64)
+	}
+	for k, v := range h.captchaTokens {
+		if v <= now {
+			delete(h.captchaTokens, k)
+		}
+	}
+	h.captchaTokens[token] = exp
+}
+
+func (h *Handler) consumeCaptchaToken(token string) bool {
+	if h == nil {
+		return false
+	}
+	token = strings.TrimSpace(token)
+	if token == "" {
+		return false
+	}
+	now := time.Now().UnixMilli()
+
+	h.captchaMu.Lock()
+	defer h.captchaMu.Unlock()
+	if h.captchaTokens == nil {
+		return false
+	}
+	for k, v := range h.captchaTokens {
+		if v <= now {
+			delete(h.captchaTokens, k)
+		}
+	}
+	exp, ok := h.captchaTokens[token]
+	if !ok {
+		return false
+	}
+	delete(h.captchaTokens, token)
+	return exp > now
+}
+
+func (h *Handler) writeCaptchaVerifyResult(w http.ResponseWriter, success bool, token string) {
+	w.Header().Set("Content-Type", "application/json; charset=utf-8")
+	payload := map[string]interface{}{
+		"success": success,
+		"data": map[string]interface{}{
+			"validToken": token,
+		},
+	}
+	_ = json.NewEncoder(w).Encode(payload)
+}
+
 func decodeJSON(body io.ReadCloser, out interface{}) error {
 	defer body.Close()
 	decoder := json.NewDecoder(body)
@@ -986,3 +1165,134 @@ func (h *Handler) verifyCloudflareTurnstile(token, secretKey string) bool {
 	}
 	return body.Success
 }
+
+type backupExportRequest struct {
+	Types []string `json:"types"`
+}
+
+func (h *Handler) backupExport(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		response.WriteJSON(w, response.ErrDefault("请求失败"))
+		return
+	}
+
+	var req backupExportRequest
+	if err := decodeJSON(r.Body, &req); err != nil {
+		response.WriteJSON(w, response.Err(500, "请求参数错误"))
+		return
+	}
+
+	var backup interface{}
+	var err error
+
+	if len(req.Types) == 0 {
+		backup, err = h.repo.ExportAll()
+	} else {
+		backup, err = h.repo.ExportPartial(req.Types)
+	}
+
+	if err != nil {
+		response.WriteJSON(w, response.Err(-2, err.Error()))
+		return
+	}
+
+	w.Header().Set("Content-Disposition", "attachment; filename=backup.json")
+	w.Header().Set("Content-Type", "application/json")
+	if err := json.NewEncoder(w).Encode(backup); err != nil {
+		response.WriteJSON(w, response.Err(-2, err.Error()))
+		return
+	}
+}
+
+type backupImportRequest struct {
+	Types []string `json:"types"`
+	repo.BackupData
+}
+
+func (h *Handler) backupImport(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		response.WriteJSON(w, response.ErrDefault("请求失败"))
+		return
+	}
+
+	var req backupImportRequest
+	if err := decodeJSON(r.Body, &req); err != nil {
+		response.WriteJSON(w, response.Err(500, "请求参数错误"))
+		return
+	}
+
+	if len(req.Types) == 0 {
+		response.WriteJSON(w, response.Err(500, "请选择要导入的数据类型"))
+		return
+	}
+
+	autoBackup, err := h.repo.ExportAll()
+	if err != nil {
+		response.WriteJSON(w, response.Err(-2, fmt.Sprintf("导入前自动备份失败: %v", err)))
+		return
+	}
+
+	if req.BackupData.Version == "" {
+		response.WriteJSON(w, response.Err(500, "备份数据格式错误"))
+		return
+	}
+
+	result, err := h.repo.Import(&req.BackupData, req.Types)
+	if err != nil {
+		response.WriteJSON(w, response.Err(-2, fmt.Sprintf("导入失败: %v", err)))
+		return
+	}
+
+	result.AutoBackup = autoBackup
+	response.WriteJSON(w, response.OK(result))
+}
+
+func (h *Handler) getAnnouncement(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet {
+		response.WriteJSON(w, response.ErrDefault("请求失败"))
+		return
+	}
+
+	ann, err := h.repo.GetAnnouncement()
+	if err != nil {
+		response.WriteJSON(w, response.Err(-1, fmt.Sprintf("获取公告失败: %v", err)))
+		return
+	}
+
+	if ann == nil {
+		response.WriteJSON(w, response.OK(map[string]interface{}{
+			"content": "",
+			"enabled": 0,
+		}))
+		return
+	}
+
+	response.WriteJSON(w, response.OK(map[string]interface{}{
+		"content": ann.Content,
+		"enabled": ann.Enabled,
+	}))
+}
+
+func (h *Handler) updateAnnouncement(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		response.WriteJSON(w, response.ErrDefault("请求失败"))
+		return
+	}
+
+	var req struct {
+		Content string `json:"content"`
+		Enabled int    `json:"enabled"`
+	}
+	if err := decodeJSON(r.Body, &req); err != nil {
+		response.WriteJSON(w, response.Err(500, "请求参数错误"))
+		return
+	}
+
+	now := time.Now().UnixMilli()
+	if err := h.repo.UpsertAnnouncement(req.Content, req.Enabled, now); err != nil {
+		response.WriteJSON(w, response.Err(-1, fmt.Sprintf("更新公告失败: %v", err)))
+		return
+	}
+
+	response.WriteJSON(w, response.OKEmpty())
+}

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

@@ -2,12 +2,11 @@ package handler
 
 import (
 	"context"
-	"database/sql"
 	"time"
 )
 
 func (h *Handler) StartBackgroundJobs() {
-	if h == nil || h.repo == nil || h.repo.DB() == nil {
+	if h == nil || h.repo == nil {
 		return
 	}
 
@@ -97,47 +96,28 @@ func durationUntilNextDailyMaintenance(now time.Time) time.Duration {
 }
 
 func (h *Handler) runStatisticsFlowJob(now time.Time) {
-	if h == nil || h.repo == nil || h.repo.DB() == nil {
+	if h == nil || h.repo == nil {
 		return
 	}
 
-	db := h.repo.DB()
 	nowMs := now.UnixMilli()
 	cutoffMs := nowMs - int64((48*time.Hour)/time.Millisecond)
-	_, _ = db.Exec(`DELETE FROM statistics_flow WHERE created_time < ?`, cutoffMs)
+	_ = h.repo.PurgeOldStatisticsFlows(cutoffMs)
 
 	hourMark := now.Truncate(time.Hour)
 	hourText := hourMark.Format("15:04")
 	createdTime := hourMark.UnixMilli()
 
-	rows, err := db.Query(`SELECT id, in_flow, out_flow FROM user ORDER BY id ASC`)
+	users, err := h.repo.ListAllUserFlowSnapshots()
 	if err != nil {
 		return
 	}
-	type userFlowSnapshot struct {
-		userID  int64
-		inFlow  int64
-		outFlow int64
-	}
-	users := make([]userFlowSnapshot, 0)
-
-	for rows.Next() {
-		var userID int64
-		var inFlow int64
-		var outFlow int64
-		if err := rows.Scan(&userID, &inFlow, &outFlow); err != nil {
-			continue
-		}
-		users = append(users, userFlowSnapshot{userID: userID, inFlow: inFlow, outFlow: outFlow})
-	}
-	_ = rows.Close()
 
 	for _, user := range users {
-		currentTotal := user.inFlow + user.outFlow
+		currentTotal := user.InFlow + user.OutFlow
 		increment := currentTotal
 
-		var lastTotal sql.NullInt64
-		err := db.QueryRow(`SELECT total_flow FROM statistics_flow WHERE user_id = ? ORDER BY id DESC LIMIT 1`, user.userID).Scan(&lastTotal)
+		lastTotal, err := h.repo.GetLastStatisticsFlowTotal(user.UserID)
 		if err == nil && lastTotal.Valid {
 			increment = currentTotal - lastTotal.Int64
 			if increment < 0 {
@@ -145,15 +125,12 @@ func (h *Handler) runStatisticsFlowJob(now time.Time) {
 			}
 		}
 
-		_, _ = db.Exec(`
-			INSERT INTO statistics_flow(user_id, flow, total_flow, time, created_time)
-			VALUES(?, ?, ?, ?, ?)
-		`, user.userID, increment, currentTotal, hourText, createdTime)
+		_ = h.repo.CreateStatisticsFlow(user.UserID, increment, currentTotal, hourText, createdTime)
 	}
 }
 
 func (h *Handler) runResetAndExpiryJob(now time.Time) {
-	if h == nil || h.repo == nil || h.repo.DB() == nil {
+	if h == nil || h.repo == nil {
 		return
 	}
 
@@ -163,108 +140,39 @@ func (h *Handler) runResetAndExpiryJob(now time.Time) {
 }
 
 func (h *Handler) resetMonthlyFlow(now time.Time) {
-	db := h.repo.DB()
 	currentDay := now.Day()
 	lastDay := time.Date(now.Year(), now.Month()+1, 0, 0, 0, 0, 0, now.Location()).Day()
 
-	if currentDay == lastDay {
-		_, _ = db.Exec(`
-			UPDATE user
-			SET in_flow = 0, out_flow = 0
-			WHERE flow_reset_time != 0
-			  AND (flow_reset_time = ? OR flow_reset_time > ?)
-		`, currentDay, lastDay)
-		_, _ = db.Exec(`
-			UPDATE user_tunnel
-			SET in_flow = 0, out_flow = 0
-			WHERE flow_reset_time != 0
-			  AND (flow_reset_time = ? OR flow_reset_time > ?)
-		`, currentDay, lastDay)
-		return
-	}
-
-	_, _ = db.Exec(`
-		UPDATE user
-		SET in_flow = 0, out_flow = 0
-		WHERE flow_reset_time != 0
-		  AND flow_reset_time = ?
-	`, currentDay)
-	_, _ = db.Exec(`
-		UPDATE user_tunnel
-		SET in_flow = 0, out_flow = 0
-		WHERE flow_reset_time != 0
-		  AND flow_reset_time = ?
-	`, currentDay)
+	_ = h.repo.ResetUserMonthlyFlow(currentDay, lastDay)
+	_ = h.repo.ResetUserTunnelMonthlyFlow(currentDay, lastDay)
 }
 
 func (h *Handler) disableExpiredUsers(nowMs int64) {
-	db := h.repo.DB()
-	rows, err := db.Query(`
-		SELECT id
-		FROM user
-		WHERE role_id != 0
-		  AND status = 1
-		  AND exp_time IS NOT NULL
-		  AND exp_time < ?
-	`, nowMs)
+	userIDs, err := h.repo.ListExpiredActiveUserIDs(nowMs)
 	if err != nil {
 		return
 	}
-	userIDs := make([]int64, 0)
-
-	for rows.Next() {
-		var userID int64
-		if err := rows.Scan(&userID); err != nil {
-			continue
-		}
-		userIDs = append(userIDs, userID)
-	}
-	_ = rows.Close()
 
 	for _, userID := range userIDs {
 		forwards, err := h.listActiveForwardsByUser(userID)
 		if err == nil {
 			h.pauseForwardRecords(forwards, nowMs)
 		}
-		_, _ = db.Exec(`UPDATE user SET status = 0 WHERE id = ?`, userID)
+		_ = h.repo.DisableUser(userID)
 	}
 }
 
 func (h *Handler) disableExpiredUserTunnels(nowMs int64) {
-	db := h.repo.DB()
-	rows, err := db.Query(`
-		SELECT id, user_id, tunnel_id
-		FROM user_tunnel
-		WHERE status = 1
-		  AND exp_time IS NOT NULL
-		  AND exp_time < ?
-	`, nowMs)
+	items, err := h.repo.ListExpiredActiveUserTunnels(nowMs)
 	if err != nil {
 		return
 	}
-	type expiredUserTunnel struct {
-		userTunnelID int64
-		userID       int64
-		tunnelID     int64
-	}
-	items := make([]expiredUserTunnel, 0)
-
-	for rows.Next() {
-		var userTunnelID int64
-		var userID int64
-		var tunnelID int64
-		if err := rows.Scan(&userTunnelID, &userID, &tunnelID); err != nil {
-			continue
-		}
-		items = append(items, expiredUserTunnel{userTunnelID: userTunnelID, userID: userID, tunnelID: tunnelID})
-	}
-	_ = rows.Close()
 
 	for _, item := range items {
-		forwards, err := h.listActiveForwardsByUserTunnel(item.userID, item.tunnelID)
+		forwards, err := h.listActiveForwardsByUserTunnel(item.UserID, item.TunnelID)
 		if err == nil {
 			h.pauseForwardRecords(forwards, nowMs)
 		}
-		_, _ = db.Exec(`UPDATE user_tunnel SET status = 0 WHERE id = ?`, item.userTunnelID)
+		_ = h.repo.DisableUserTunnel(item.ID)
 	}
 }

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

@@ -5,48 +5,40 @@ import (
 	"testing"
 	"time"
 
-	"go-backend/internal/store/sqlite"
+	"go-backend/internal/store/repo"
 )
 
 func TestRunStatisticsFlowJobTracksIncrementAndPrunes(t *testing.T) {
 	dbPath := filepath.Join(t.TempDir(), "jobs-stats.db")
-	repo, err := sqlite.Open(dbPath)
+	r, err := repo.Open(dbPath)
 	if err != nil {
 		t.Fatalf("open sqlite: %v", err)
 	}
-	t.Cleanup(func() { _ = repo.Close() })
+	t.Cleanup(func() { _ = r.Close() })
 
-	h := New(repo, "secret")
+	h := New(r, "secret")
 	now := time.Date(2026, 2, 7, 12, 0, 0, 0, time.UTC)
 	nowMs := now.UnixMilli()
 
-	if _, err := repo.DB().Exec(`UPDATE user SET in_flow = 100, out_flow = 200 WHERE id = 1`); err != nil {
+	if err := r.DB().Exec(`UPDATE user SET in_flow = 100, out_flow = 200 WHERE id = 1`).Error; err != nil {
 		t.Fatalf("seed user flow: %v", err)
 	}
 
-	if _, err := repo.DB().Exec(`INSERT INTO statistics_flow(user_id, flow, total_flow, time, created_time) VALUES(1, 250, 250, '11:00', ?)`, now.Add(-time.Hour).UnixMilli()); err != nil {
+	if err := r.DB().Exec(`INSERT INTO statistics_flow(user_id, flow, total_flow, time, created_time) VALUES(1, 250, 250, '11:00', ?)`, now.Add(-time.Hour).UnixMilli()).Error; err != nil {
 		t.Fatalf("seed recent statistics row: %v", err)
 	}
-	if _, err := repo.DB().Exec(`INSERT INTO statistics_flow(user_id, flow, total_flow, time, created_time) VALUES(1, 10, 10, '00:00', ?)`, now.Add(-49*time.Hour).UnixMilli()); err != nil {
+	if err := r.DB().Exec(`INSERT INTO statistics_flow(user_id, flow, total_flow, time, created_time) VALUES(1, 10, 10, '00:00', ?)`, now.Add(-49*time.Hour).UnixMilli()).Error; err != nil {
 		t.Fatalf("seed stale statistics row: %v", err)
 	}
 
 	h.runStatisticsFlowJob(now)
 
-	var staleCount int
-	if err := repo.DB().QueryRow(`SELECT COUNT(1) FROM statistics_flow WHERE created_time < ?`, nowMs-int64((48*time.Hour)/time.Millisecond)).Scan(&staleCount); err != nil {
-		t.Fatalf("query stale statistics rows: %v", err)
-	}
+	staleCount := mustQueryInt(t, r, `SELECT COUNT(1) FROM statistics_flow WHERE created_time < ?`, nowMs-int64((48*time.Hour)/time.Millisecond))
 	if staleCount != 0 {
 		t.Fatalf("expected stale statistics rows to be pruned, got %d", staleCount)
 	}
 
-	var flow int64
-	var total int64
-	var hour string
-	if err := repo.DB().QueryRow(`SELECT flow, total_flow, time FROM statistics_flow WHERE user_id = 1 ORDER BY id DESC LIMIT 1`).Scan(&flow, &total, &hour); err != nil {
-		t.Fatalf("query latest statistics row: %v", err)
-	}
+	flow, total, hour := mustQueryInt64Int64String(t, r, `SELECT flow, total_flow, time FROM statistics_flow WHERE user_id = 1 ORDER BY id DESC LIMIT 1`)
 	if flow != 50 {
 		t.Fatalf("expected increment flow 50, got %d", flow)
 	}
@@ -60,69 +52,94 @@ func TestRunStatisticsFlowJobTracksIncrementAndPrunes(t *testing.T) {
 
 func TestRunResetAndExpiryJobResetsFlowAndDisablesExpiredRecords(t *testing.T) {
 	dbPath := filepath.Join(t.TempDir(), "jobs-reset.db")
-	repo, err := sqlite.Open(dbPath)
+	r, err := repo.Open(dbPath)
 	if err != nil {
 		t.Fatalf("open sqlite: %v", err)
 	}
-	t.Cleanup(func() { _ = repo.Close() })
+	t.Cleanup(func() { _ = r.Close() })
 
-	h := New(repo, "secret")
+	h := New(r, "secret")
 	now := time.Date(2026, 3, 15, 0, 0, 5, 0, time.UTC)
 	nowMs := now.UnixMilli()
 
-	if _, err := repo.DB().Exec(`
+	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, 'expired_user', 'x', 1, ?, 100, 1000, 2000, 15, 1, ?, ?, 1)
-	`, nowMs-1000, nowMs, nowMs); err != nil {
+	`, nowMs-1000, nowMs, nowMs).Error; err != nil {
 		t.Fatalf("insert expired user: %v", err)
 	}
 
-	if _, err := repo.DB().Exec(`
+	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)
-	`, nowMs, nowMs); err != nil {
+	`, nowMs, nowMs).Error; err != nil {
 		t.Fatalf("insert tunnel: %v", err)
 	}
 
-	if _, err := repo.DB().Exec(`
+	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, 1, 300, 400, 15, ?, 1)
-	`, nowMs-1000); err != nil {
+	`, nowMs-1000).Error; err != nil {
 		t.Fatalf("insert expired user_tunnel: %v", err)
 	}
 
-	if _, err := repo.DB().Exec(`
+	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)
-	`, nowMs, nowMs); err != nil {
+	`, nowMs, nowMs).Error; err != nil {
 		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)
 
-	var userIn, userOut int64
-	var userStatus int
-	if err := repo.DB().QueryRow(`SELECT in_flow, out_flow, status FROM user WHERE id = 2`).Scan(&userIn, &userOut, &userStatus); err != nil {
-		t.Fatalf("query user after maintenance: %v", err)
-	}
+	userIn, userOut, userStatus := mustQueryInt64Int64Int(t, r, `SELECT in_flow, out_flow, status FROM user WHERE id = 2`)
 	if userIn != 0 || userOut != 0 || userStatus != 0 {
 		t.Fatalf("expected user reset+disabled, got in=%d out=%d status=%d", userIn, userOut, userStatus)
 	}
 
-	var utIn, utOut int64
-	var utStatus int
-	if err := repo.DB().QueryRow(`SELECT in_flow, out_flow, status FROM user_tunnel WHERE id = 10`).Scan(&utIn, &utOut, &utStatus); err != nil {
-		t.Fatalf("query user_tunnel after maintenance: %v", err)
-	}
+	utIn, utOut, utStatus := mustQueryInt64Int64Int(t, r, `SELECT in_flow, out_flow, status FROM user_tunnel WHERE id = 10`)
 	if utIn != 0 || utOut != 0 || utStatus != 0 {
 		t.Fatalf("expected user_tunnel reset+disabled, got in=%d out=%d status=%d", utIn, utOut, utStatus)
 	}
 
-	var forwardStatus int
-	if err := repo.DB().QueryRow(`SELECT status FROM forward WHERE id = 20`).Scan(&forwardStatus); err != nil {
-		t.Fatalf("query forward after maintenance: %v", err)
-	}
+	forwardStatus := mustQueryInt(t, r, `SELECT status FROM forward WHERE id = 20`)
 	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/upgrade.go

@@ -0,0 +1,407 @@
+package handler
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"regexp"
+	"strings"
+	"sync"
+	"time"
+
+	"go-backend/internal/http/response"
+)
+
+const (
+	githubRepo     = "Sagit-chu/flvx"
+	githubProxy    = "https://gcode.hostcentral.cc"
+	githubAPIBase  = "https://api.github.com"
+	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("请求失败"))
+		return
+	}
+
+	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("请求参数错误"))
+		return
+	}
+	if req.ID <= 0 {
+		response.WriteJSON(w, response.ErrDefault("节点ID无效"))
+		return
+	}
+
+	channel := normalizeReleaseChannel(req.Channel)
+	version := strings.TrimSpace(req.Version)
+	if version == "" {
+		var err error
+		version, err = resolveLatestReleaseByChannel(channel)
+		if err != nil {
+			response.WriteJSON(w, response.Err(-2, fmt.Sprintf("获取最新%s失败: %v", releaseChannelLabel(channel), err)))
+			return
+		}
+	}
+
+	downloadURL := fmt.Sprintf(
+		githubProxy+"/%s/%s/releases/download/%s/gost-{ARCH}",
+		githubHTMLBase, githubRepo, version,
+	)
+	checksumURL := fmt.Sprintf(
+		githubProxy+"/%s/%s/releases/download/%s/gost-{ARCH}.sha256",
+		githubHTMLBase, githubRepo, version,
+	)
+
+	result, err := h.wsServer.SendCommand(req.ID, "UpgradeAgent", map[string]interface{}{
+		"downloadUrl": downloadURL,
+		"checksumUrl": checksumURL,
+	}, upgradeTimeout)
+	if err != nil {
+		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,
+		"message": result.Message,
+	}))
+}
+
+func resolveLatestRelease() (string, error) {
+	return resolveLatestReleaseByChannel(releaseChannelStable)
+}
+
+func resolveLatestReleaseAPI() (string, error) {
+	return resolveLatestReleaseByChannel(releaseChannelStable)
+}
+
+func (h *Handler) nodeBatchUpgrade(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		response.WriteJSON(w, response.ErrDefault("请求失败"))
+		return
+	}
+
+	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("请求参数错误"))
+		return
+	}
+	if len(req.IDs) == 0 {
+		response.WriteJSON(w, response.ErrDefault("ids不能为空"))
+		return
+	}
+
+	channel := normalizeReleaseChannel(req.Channel)
+	version := strings.TrimSpace(req.Version)
+	if version == "" {
+		var err error
+		version, err = resolveLatestReleaseByChannel(channel)
+		if err != nil {
+			response.WriteJSON(w, response.Err(-2, fmt.Sprintf("获取最新%s失败: %v", releaseChannelLabel(channel), err)))
+			return
+		}
+	}
+
+	downloadURL := fmt.Sprintf(
+		githubProxy+"/%s/%s/releases/download/%s/gost-{ARCH}",
+		githubHTMLBase, githubRepo, version,
+	)
+	checksumURL := fmt.Sprintf(
+		githubProxy+"/%s/%s/releases/download/%s/gost-{ARCH}.sha256",
+		githubHTMLBase, githubRepo, version,
+	)
+
+	type upgradeResult struct {
+		ID      int64  `json:"id"`
+		Success bool   `json:"success"`
+		Message string `json:"message"`
+	}
+
+	results := make([]upgradeResult, len(req.IDs))
+	sem := make(chan struct{}, batchWorkers)
+	var wg sync.WaitGroup
+
+	for i, id := range req.IDs {
+		wg.Add(1)
+		go func(index int, nodeID int64) {
+			defer wg.Done()
+			sem <- struct{}{}
+			defer func() { <-sem }()
+
+			result, err := h.wsServer.SendCommand(nodeID, "UpgradeAgent", map[string]interface{}{
+				"downloadUrl": downloadURL,
+				"checksumUrl": checksumURL,
+			}, upgradeTimeout)
+			if err != nil {
+				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)
+	}
+	wg.Wait()
+
+	response.WriteJSON(w, response.OK(map[string]interface{}{
+		"version": version,
+		"results": results,
+	}))
+}
+
+func (h *Handler) listReleases(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		response.WriteJSON(w, response.ErrDefault("请求失败"))
+		return
+	}
+
+	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
+	}
+
+	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))
+	for _, r := range releases {
+		if r.Draft {
+			continue
+		}
+		tag := strings.TrimSpace(r.TagName)
+		if tag == "" {
+			continue
+		}
+		itemChannel := releaseChannelFromTag(tag)
+		if itemChannel != channel {
+			continue
+		}
+		items = append(items, releaseItem{
+			Version:     tag,
+			Name:        r.Name,
+			PublishedAt: r.PublishedAt,
+			Prerelease:  itemChannel == releaseChannelDev,
+			Channel:     itemChannel,
+		})
+	}
+
+	response.WriteJSON(w, response.OK(items))
+}
+
+func (h *Handler) nodeRollback(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		response.WriteJSON(w, response.ErrDefault("请求失败"))
+		return
+	}
+
+	var req struct {
+		ID int64 `json:"id"`
+	}
+	if err := decodeJSON(r.Body, &req); err != nil {
+		response.WriteJSON(w, response.ErrDefault("请求参数错误"))
+		return
+	}
+	if req.ID <= 0 {
+		response.WriteJSON(w, response.ErrDefault("节点ID无效"))
+		return
+	}
+
+	result, err := h.wsServer.SendCommand(req.ID, "RollbackAgent", map[string]interface{}{}, 30*time.Second)
+	if err != nil {
+		response.WriteJSON(w, response.Err(-2, fmt.Sprintf("回退失败: %v", err)))
+		return
+	}
+
+	response.WriteJSON(w, response.OK(map[string]interface{}{
+		"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/http/middleware/auth.go

@@ -81,6 +81,20 @@ func shouldSkip(path string) bool {
 		return true
 	case path == "/api/v1/user/login":
 		return true
+	case path == "/api/v1/federation/connect":
+		return true
+	case path == "/api/v1/federation/tunnel/create":
+		return true
+	case path == "/api/v1/federation/runtime/reserve-port":
+		return true
+	case path == "/api/v1/federation/runtime/apply-role":
+		return true
+	case path == "/api/v1/federation/runtime/release-role":
+		return true
+	case path == "/api/v1/federation/runtime/diagnose":
+		return true
+	case path == "/api/v1/federation/runtime/command":
+		return true
 	default:
 		return false
 	}
@@ -91,6 +105,10 @@ func requiresAdmin(path string) bool {
 		return true
 	}
 
+	if strings.HasPrefix(path, "/api/v1/federation/share/") {
+		return true
+	}
+
 	if strings.HasPrefix(path, "/api/v1/node/") {
 		return true
 	}
@@ -99,6 +117,14 @@ func requiresAdmin(path string) bool {
 		return true
 	}
 
+	if strings.HasPrefix(path, "/api/v1/backup/") {
+		return true
+	}
+
+	if strings.HasPrefix(path, "/api/v1/api/v1/backup/") {
+		return true
+	}
+
 	if strings.HasPrefix(path, "/api/v1/tunnel/") {
 		if strings.HasPrefix(path, "/api/v1/tunnel/user/tunnel") {
 			return false
@@ -111,6 +137,8 @@ func requiresAdmin(path string) bool {
 		return true
 	case "/api/v1/config/update", "/api/v1/config/update-single":
 		return true
+	case "/api/v1/announcement/update":
+		return true
 	default:
 		return false
 	}

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

@@ -0,0 +1,591 @@
+// Package model defines GORM model structs for all database tables,
+// providing a single source of truth for the schema that works
+// transparently with both SQLite and PostgreSQL.
+package model
+
+import "database/sql"
+
+// ─── Core Business Tables ────────────────────────────────────────────
+
+// User maps to the "user" table. PostgreSQL treats "user" as a reserved
+// word, so TableName() is required for correct quoting.
+type User struct {
+	ID            int64         `gorm:"primaryKey;autoIncrement"`
+	User          string        `gorm:"column:user;type:varchar(100);not null"`
+	Pwd           string        `gorm:"type:varchar(100);not null"`
+	RoleID        int           `gorm:"column:role_id;not null"`
+	ExpTime       int64         `gorm:"column:exp_time;not null"`
+	Flow          int64         `gorm:"not null"`
+	InFlow        int64         `gorm:"column:in_flow;not null;default:0"`
+	OutFlow       int64         `gorm:"column:out_flow;not null;default:0"`
+	FlowResetTime int64         `gorm:"column:flow_reset_time;not null"`
+	Num           int           `gorm:"not null"`
+	CreatedTime   int64         `gorm:"column:created_time;not null"`
+	UpdatedTime   sql.NullInt64 `gorm:"column:updated_time"`
+	Status        int           `gorm:"not null"`
+}
+
+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"`
+}
+
+func (Forward) TableName() string { return "forward" }
+
+type ForwardPort struct {
+	ID        int64 `gorm:"primaryKey;autoIncrement"`
+	ForwardID int64 `gorm:"column:forward_id;not null"`
+	NodeID    int64 `gorm:"column:node_id;not null"`
+	Port      int   `gorm:"not null"`
+}
+
+func (ForwardPort) TableName() string { return "forward_port" }
+
+type Node struct {
+	ID            int64          `gorm:"primaryKey;autoIncrement"`
+	Name          string         `gorm:"type:varchar(100);not null"`
+	Secret        string         `gorm:"type:varchar(100);not null"`
+	ServerIP      string         `gorm:"column:server_ip;type:varchar(100);not null"`
+	ServerIPV4    sql.NullString `gorm:"column:server_ip_v4;type:varchar(100)"`
+	ServerIPV6    sql.NullString `gorm:"column:server_ip_v6;type:varchar(100)"`
+	Port          string         `gorm:"type:text;not null"`
+	InterfaceName sql.NullString `gorm:"column:interface_name;type:varchar(200)"`
+	Version       sql.NullString `gorm:"type:varchar(100)"`
+	HTTP          int            `gorm:"column:http;not null;default:0"`
+	TLS           int            `gorm:"column:tls;not null;default:0"`
+	Socks         int            `gorm:"not null;default:0"`
+	CreatedTime   int64          `gorm:"column:created_time;not null"`
+	UpdatedTime   sql.NullInt64  `gorm:"column:updated_time"`
+	Status        int            `gorm:"not null"`
+	TCPListenAddr string         `gorm:"column:tcp_listen_addr;type:varchar(100);not null;default:'[::]'"`
+	UDPListenAddr string         `gorm:"column:udp_listen_addr;type:varchar(100);not null;default:'[::]'"`
+	Inx           int            `gorm:"not null;default:0"`
+	IsRemote      int            `gorm:"column:is_remote;default:0"`
+	RemoteURL     sql.NullString `gorm:"column:remote_url;type:text"`
+	RemoteToken   sql.NullString `gorm:"column:remote_token;type:text"`
+	RemoteConfig  sql.NullString `gorm:"column:remote_config;type:text"`
+}
+
+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"`
+}
+
+func (SpeedLimit) TableName() string { return "speed_limit" }
+
+type StatisticsFlow struct {
+	ID          int64  `gorm:"primaryKey;autoIncrement" json:"id"`
+	UserID      int64  `gorm:"column:user_id;not null" json:"userId"`
+	Flow        int64  `gorm:"not null" json:"flow"`
+	TotalFlow   int64  `gorm:"column:total_flow;not null" json:"totalFlow"`
+	Time        string `gorm:"type:varchar(100);not null" json:"time"`
+	CreatedTime int64  `gorm:"column:created_time;not null" json:"-"`
+}
+
+func (StatisticsFlow) TableName() string { return "statistics_flow" }
+
+type Tunnel struct {
+	ID           int64          `gorm:"primaryKey;autoIncrement"`
+	Name         string         `gorm:"type:varchar(100);not null"`
+	TrafficRatio float64        `gorm:"column:traffic_ratio;not null;default:1.0"`
+	Type         int            `gorm:"not null"`
+	Protocol     string         `gorm:"type:varchar(10);not null;default:'tls'"`
+	Flow         int64          `gorm:"not null"`
+	CreatedTime  int64          `gorm:"column:created_time;not null"`
+	UpdatedTime  int64          `gorm:"column:updated_time;not null"`
+	Status       int            `gorm:"not null"`
+	InIP         sql.NullString `gorm:"column:in_ip;type:text"`
+	Inx          int            `gorm:"not null;default:0"`
+	IPPreference string         `gorm:"column:ip_preference;type:varchar(10);not null;default:''"`
+}
+
+func (Tunnel) TableName() string { return "tunnel" }
+
+type ChainTunnel struct {
+	ID        int64          `gorm:"primaryKey;autoIncrement"`
+	TunnelID  int64          `gorm:"column:tunnel_id;not null"`
+	ChainType string         `gorm:"column:chain_type;type:varchar(10);not null"`
+	NodeID    int64          `gorm:"column:node_id;not null"`
+	Port      sql.NullInt64  `gorm:"column:port"`
+	Strategy  sql.NullString `gorm:"type:varchar(10)"`
+	Inx       sql.NullInt64  `gorm:"column:inx"`
+	Protocol  sql.NullString `gorm:"type:varchar(10)"`
+}
+
+func (ChainTunnel) TableName() string { return "chain_tunnel" }
+
+type UserTunnel struct {
+	ID            int64         `gorm:"primaryKey;autoIncrement"`
+	UserID        int64         `gorm:"column:user_id;not null;uniqueIndex:idx_user_tunnel_unique"`
+	TunnelID      int64         `gorm:"column:tunnel_id;not null;uniqueIndex:idx_user_tunnel_unique"`
+	SpeedID       sql.NullInt64 `gorm:"column:speed_id"`
+	Num           int           `gorm:"not null"`
+	Flow          int64         `gorm:"not null"`
+	InFlow        int64         `gorm:"column:in_flow;not null;default:0"`
+	OutFlow       int64         `gorm:"column:out_flow;not null;default:0"`
+	FlowResetTime int64         `gorm:"column:flow_reset_time;not null"`
+	ExpTime       int64         `gorm:"column:exp_time;not null"`
+	Status        int           `gorm:"not null"`
+}
+
+func (UserTunnel) TableName() string { return "user_tunnel" }
+
+type TunnelGroup struct {
+	ID          int64  `gorm:"primaryKey;autoIncrement"`
+	Name        string `gorm:"type:varchar(100);not null;uniqueIndex:idx_tunnel_group_name"`
+	CreatedTime int64  `gorm:"column:created_time;not null"`
+	UpdatedTime int64  `gorm:"column:updated_time;not null"`
+	Status      int    `gorm:"not null"`
+}
+
+func (TunnelGroup) TableName() string { return "tunnel_group" }
+
+type UserGroup struct {
+	ID          int64  `gorm:"primaryKey;autoIncrement"`
+	Name        string `gorm:"type:varchar(100);not null;uniqueIndex:idx_user_group_name"`
+	CreatedTime int64  `gorm:"column:created_time;not null"`
+	UpdatedTime int64  `gorm:"column:updated_time;not null"`
+	Status      int    `gorm:"not null"`
+}
+
+func (UserGroup) TableName() string { return "user_group" }
+
+type TunnelGroupTunnel struct {
+	ID            int64 `gorm:"primaryKey;autoIncrement"`
+	TunnelGroupID int64 `gorm:"column:tunnel_group_id;not null;uniqueIndex:idx_tunnel_group_tunnel_unique"`
+	TunnelID      int64 `gorm:"column:tunnel_id;not null;uniqueIndex:idx_tunnel_group_tunnel_unique"`
+	CreatedTime   int64 `gorm:"column:created_time;not null"`
+}
+
+func (TunnelGroupTunnel) TableName() string { return "tunnel_group_tunnel" }
+
+type UserGroupUser struct {
+	ID          int64 `gorm:"primaryKey;autoIncrement"`
+	UserGroupID int64 `gorm:"column:user_group_id;not null;uniqueIndex:idx_user_group_user_unique"`
+	UserID      int64 `gorm:"column:user_id;not null;uniqueIndex:idx_user_group_user_unique"`
+	CreatedTime int64 `gorm:"column:created_time;not null"`
+}
+
+func (UserGroupUser) TableName() string { return "user_group_user" }
+
+type GroupPermission struct {
+	ID            int64 `gorm:"primaryKey;autoIncrement"`
+	UserGroupID   int64 `gorm:"column:user_group_id;not null;uniqueIndex:idx_group_permission_unique"`
+	TunnelGroupID int64 `gorm:"column:tunnel_group_id;not null;uniqueIndex:idx_group_permission_unique"`
+	CreatedTime   int64 `gorm:"column:created_time;not null"`
+}
+
+func (GroupPermission) TableName() string { return "group_permission" }
+
+type GroupPermissionGrant struct {
+	ID             int64 `gorm:"primaryKey;autoIncrement"`
+	UserGroupID    int64 `gorm:"column:user_group_id;not null;uniqueIndex:idx_group_permission_grant_unique"`
+	TunnelGroupID  int64 `gorm:"column:tunnel_group_id;not null;uniqueIndex:idx_group_permission_grant_unique"`
+	UserTunnelID   int64 `gorm:"column:user_tunnel_id;not null;uniqueIndex:idx_group_permission_grant_unique"`
+	CreatedByGroup int   `gorm:"column:created_by_group;not null;default:0"`
+	CreatedTime    int64 `gorm:"column:created_time;not null"`
+}
+
+func (GroupPermissionGrant) TableName() string { return "group_permission_grant" }
+
+type ViteConfig struct {
+	ID    int64  `gorm:"primaryKey;autoIncrement" json:"id"`
+	Name  string `gorm:"type:varchar(200);not null;uniqueIndex" json:"name"`
+	Value string `gorm:"type:varchar(200);not null" json:"value"`
+	Time  int64  `gorm:"not null" json:"time"`
+}
+
+func (ViteConfig) TableName() string { return "vite_config" }
+
+type Announcement struct {
+	ID          int64         `gorm:"primaryKey;autoIncrement" json:"id"`
+	Content     string        `gorm:"type:text;not null" json:"content"`
+	Enabled     int           `gorm:"not null;default:1" json:"enabled"`
+	CreatedTime int64         `gorm:"column:created_time;not null" json:"created_time"`
+	UpdatedTime sql.NullInt64 `gorm:"column:updated_time" json:"updated_time,omitempty"`
+}
+
+func (Announcement) TableName() string { return "announcement" }
+
+type SchemaVersion struct {
+	Version int `gorm:"not null;default:0"`
+}
+
+func (SchemaVersion) TableName() string { return "schema_version" }
+
+type PeerShare struct {
+	ID             int64  `gorm:"primaryKey;autoIncrement" json:"id"`
+	Name           string `gorm:"type:text;not null" json:"name"`
+	NodeID         int64  `gorm:"column:node_id;not null" json:"nodeId"`
+	Token          string `gorm:"type:text;not null;uniqueIndex" json:"token"`
+	MaxBandwidth   int64  `gorm:"column:max_bandwidth;default:0" json:"maxBandwidth"`
+	ExpiryTime     int64  `gorm:"column:expiry_time;default:0" json:"expiryTime"`
+	PortRangeStart int    `gorm:"column:port_range_start;default:0" json:"portRangeStart"`
+	PortRangeEnd   int    `gorm:"column:port_range_end;default:0" json:"portRangeEnd"`
+	CurrentFlow    int64  `gorm:"column:current_flow;default:0" json:"currentFlow"`
+	IsActive       int    `gorm:"column:is_active;default:1" json:"isActive"`
+	CreatedTime    int64  `gorm:"column:created_time;not null" json:"createdTime"`
+	UpdatedTime    int64  `gorm:"column:updated_time;not null" json:"updatedTime"`
+	AllowedDomains string `gorm:"column:allowed_domains;type:text;default:''" json:"allowedDomains"`
+	AllowedIPs     string `gorm:"column:allowed_ips;type:text;default:''" json:"allowedIps"`
+}
+
+func (PeerShare) TableName() string { return "peer_share" }
+
+type PeerShareRuntime struct {
+	ID            int64  `gorm:"primaryKey;autoIncrement"`
+	ShareID       int64  `gorm:"column:share_id;not null;index:idx_peer_share_runtime_share_node_status"`
+	NodeID        int64  `gorm:"column:node_id;not null;index:idx_peer_share_runtime_share_node_status"`
+	ReservationID string `gorm:"column:reservation_id;type:text;not null;uniqueIndex"`
+	ResourceKey   string `gorm:"column:resource_key;type:text;not null;uniqueIndex"`
+	BindingID     string `gorm:"column:binding_id;type:text;not null;default:'';index:idx_peer_share_runtime_binding_id"`
+	Role          string `gorm:"type:text;not null;default:''"`
+	ChainName     string `gorm:"column:chain_name;type:text;not null;default:''"`
+	ServiceName   string `gorm:"column:service_name;type:text;not null;default:''"`
+	Protocol      string `gorm:"type:text;not null;default:'tls'"`
+	Strategy      string `gorm:"type:text;not null;default:'round'"`
+	Port          int    `gorm:"not null;default:0"`
+	Target        string `gorm:"type:text;not null;default:''"`
+	Applied       int    `gorm:"not null;default:0"`
+	Status        int    `gorm:"not null;default:1;index:idx_peer_share_runtime_share_node_status"`
+	CreatedTime   int64  `gorm:"column:created_time;not null"`
+	UpdatedTime   int64  `gorm:"column:updated_time;not null"`
+}
+
+func (PeerShareRuntime) TableName() string { return "peer_share_runtime" }
+
+type FederationTunnelBinding struct {
+	ID              int64  `gorm:"primaryKey;autoIncrement"`
+	TunnelID        int64  `gorm:"column:tunnel_id;not null;uniqueIndex:idx_federation_tunnel_binding_unique;index:idx_federation_tunnel_binding_tunnel"`
+	NodeID          int64  `gorm:"column:node_id;not null;uniqueIndex:idx_federation_tunnel_binding_unique"`
+	ChainType       int    `gorm:"column:chain_type;not null;uniqueIndex:idx_federation_tunnel_binding_unique"`
+	HopInx          int    `gorm:"column:hop_inx;not null;default:0;uniqueIndex:idx_federation_tunnel_binding_unique"`
+	RemoteURL       string `gorm:"column:remote_url;type:text;not null"`
+	ResourceKey     string `gorm:"column:resource_key;type:text;not null;uniqueIndex"`
+	RemoteBindingID string `gorm:"column:remote_binding_id;type:text;not null"`
+	AllocatedPort   int    `gorm:"column:allocated_port;not null"`
+	Status          int    `gorm:"not null;default:1;index:idx_federation_tunnel_binding_tunnel"`
+	CreatedTime     int64  `gorm:"column:created_time;not null"`
+	UpdatedTime     int64  `gorm:"column:updated_time;not null"`
+}
+
+func (FederationTunnelBinding) TableName() string { return "federation_tunnel_binding" }
+
+// ─── Backup / Import-Export Structs ──────────────────────────────────
+// These are not GORM models; they define the JSON wire format for the
+// backup/restore API and MUST keep their existing json tags unchanged.
+
+// BackupData represents the full backup structure.
+type BackupData struct {
+	Version      string              `json:"version"`
+	ExportedAt   int64               `json:"exportedAt"`
+	Users        []UserBackup        `json:"users,omitempty"`
+	Nodes        []NodeBackup        `json:"nodes,omitempty"`
+	Tunnels      []TunnelBackup      `json:"tunnels,omitempty"`
+	Forwards     []ForwardBackup     `json:"forwards,omitempty"`
+	UserTunnels  []UserTunnelBackup  `json:"userTunnels,omitempty"`
+	SpeedLimits  []SpeedLimitBackup  `json:"speedLimits,omitempty"`
+	TunnelGroups []TunnelGroupBackup `json:"tunnelGroups,omitempty"`
+	UserGroups   []UserGroupBackup   `json:"userGroups,omitempty"`
+	Permissions  []PermissionBackup  `json:"permissions,omitempty"`
+	Configs      map[string]string   `json:"configs,omitempty"`
+}
+
+type UserBackup struct {
+	ID            int64  `json:"id"`
+	User          string `json:"user"`
+	Pwd           string `json:"pwd"`
+	RoleID        int    `json:"roleId"`
+	ExpTime       int64  `json:"expTime"`
+	Flow          int64  `json:"flow"`
+	InFlow        int64  `json:"inFlow"`
+	OutFlow       int64  `json:"outFlow"`
+	FlowResetTime int64  `json:"flowResetTime"`
+	Num           int    `json:"num"`
+	CreatedTime   int64  `json:"createdTime"`
+	UpdatedTime   int64  `json:"updatedTime,omitempty"`
+	Status        int    `json:"status"`
+}
+
+type NodeBackup struct {
+	ID            int64  `json:"id"`
+	Name          string `json:"name"`
+	Secret        string `json:"secret"`
+	ServerIP      string `json:"serverIp"`
+	ServerIPv4    string `json:"serverIpV4,omitempty"`
+	ServerIPv6    string `json:"serverIpV6,omitempty"`
+	Port          string `json:"port"`
+	InterfaceName string `json:"interfaceName,omitempty"`
+	Version       string `json:"version,omitempty"`
+	HTTP          int    `json:"http"`
+	TLS           int    `json:"tls"`
+	Socks         int    `json:"socks"`
+	CreatedTime   int64  `json:"createdTime"`
+	UpdatedTime   int64  `json:"updatedTime,omitempty"`
+	Status        int    `json:"status"`
+	TCPListenAddr string `json:"tcpListenAddr"`
+	UDPListenAddr string `json:"udpListenAddr"`
+	Inx           int    `json:"inx"`
+	IsRemote      int    `json:"isRemote"`
+	RemoteURL     string `json:"remoteUrl,omitempty"`
+	RemoteToken   string `json:"remoteToken,omitempty"`
+	RemoteConfig  string `json:"remoteConfig,omitempty"`
+}
+
+type TunnelBackup struct {
+	ID           int64               `json:"id"`
+	Name         string              `json:"name"`
+	TrafficRatio float64             `json:"trafficRatio"`
+	Type         int                 `json:"type"`
+	Protocol     string              `json:"protocol"`
+	Flow         int64               `json:"flow"`
+	CreatedTime  int64               `json:"createdTime"`
+	UpdatedTime  int64               `json:"updatedTime"`
+	Status       int                 `json:"status"`
+	InIP         string              `json:"inIp,omitempty"`
+	Inx          int                 `json:"inx"`
+	IPPreference string              `json:"ipPreference,omitempty"`
+	ChainTunnels []ChainTunnelBackup `json:"chainTunnels,omitempty"`
+}
+
+type ChainTunnelBackup struct {
+	ID        int64  `json:"id"`
+	TunnelID  int64  `json:"tunnelId"`
+	ChainType string `json:"chainType"`
+	NodeID    int64  `json:"nodeId"`
+	Port      int    `json:"port,omitempty"`
+	Strategy  string `json:"strategy,omitempty"`
+	Inx       int    `json:"inx,omitempty"`
+	Protocol  string `json:"protocol,omitempty"`
+}
+
+type ForwardBackup struct {
+	ID           int64                `json:"id"`
+	UserID       int64                `json:"userId"`
+	UserName     string               `json:"userName"`
+	Name         string               `json:"name"`
+	TunnelID     int64                `json:"tunnelId"`
+	RemoteAddr   string               `json:"remoteAddr"`
+	Strategy     string               `json:"strategy"`
+	InFlow       int64                `json:"inFlow"`
+	OutFlow      int64                `json:"outFlow"`
+	CreatedTime  int64                `json:"createdTime"`
+	UpdatedTime  int64                `json:"updatedTime"`
+	Status       int                  `json:"status"`
+	Inx          int                  `json:"inx"`
+	ForwardPorts *[]ForwardPortBackup `json:"forwardPorts,omitempty"`
+}
+
+type ForwardPortBackup struct {
+	NodeID int64 `json:"nodeId"`
+	Port   int   `json:"port"`
+}
+
+type UserTunnelBackup struct {
+	ID            int64 `json:"id"`
+	UserID        int64 `json:"userId"`
+	TunnelID      int64 `json:"tunnelId"`
+	SpeedID       int64 `json:"speedId,omitempty"`
+	Num           int   `json:"num"`
+	Flow          int64 `json:"flow"`
+	InFlow        int64 `json:"inFlow"`
+	OutFlow       int64 `json:"outFlow"`
+	FlowResetTime int64 `json:"flowResetTime"`
+	ExpTime       int64 `json:"expTime"`
+	Status        int   `json:"status"`
+}
+
+type SpeedLimitBackup struct {
+	ID          int64  `json:"id"`
+	Name        string `json:"name"`
+	Speed       int64  `json:"speed"`
+	TunnelID    int64  `json:"tunnelId"`
+	TunnelName  string `json:"tunnelName"`
+	CreatedTime int64  `json:"createdTime"`
+	UpdatedTime int64  `json:"updatedTime,omitempty"`
+	Status      int    `json:"status"`
+}
+
+type TunnelGroupBackup struct {
+	ID          int64   `json:"id"`
+	Name        string  `json:"name"`
+	CreatedTime int64   `json:"createdTime"`
+	UpdatedTime int64   `json:"updatedTime"`
+	Status      int     `json:"status"`
+	Tunnels     []int64 `json:"tunnels,omitempty"`
+}
+
+type UserGroupBackup struct {
+	ID          int64   `json:"id"`
+	Name        string  `json:"name"`
+	CreatedTime int64   `json:"createdTime"`
+	UpdatedTime int64   `json:"updatedTime"`
+	Status      int     `json:"status"`
+	Users       []int64 `json:"users,omitempty"`
+}
+
+type PermissionBackup struct {
+	ID             int64                   `json:"id"`
+	UserGroupID    int64                   `json:"userGroupId"`
+	TunnelGroupID  int64                   `json:"tunnelGroupId"`
+	CreatedTime    int64                   `json:"createdTime"`
+	CreatedByGroup int                     `json:"createdByGroup"`
+	Grants         []PermissionGrantBackup `json:"grants,omitempty"`
+}
+
+type PermissionGrantBackup struct {
+	ID             int64 `json:"id"`
+	UserGroupID    int64 `json:"userGroupId"`
+	TunnelGroupID  int64 `json:"tunnelGroupId"`
+	UserTunnelID   int64 `json:"userTunnelId"`
+	CreatedTime    int64 `json:"createdTime"`
+	CreatedByGroup int   `json:"createdByGroup"`
+}
+
+// ImportResult contains the result of an import operation.
+type ImportResult struct {
+	UsersImported        int         `json:"usersImported"`
+	NodesImported        int         `json:"nodesImported"`
+	TunnelsImported      int         `json:"tunnelsImported"`
+	ForwardsImported     int         `json:"forwardsImported"`
+	UserTunnelsImported  int         `json:"userTunnelsImported"`
+	SpeedLimitsImported  int         `json:"speedLimitsImported"`
+	TunnelGroupsImported int         `json:"tunnelGroupsImported"`
+	UserGroupsImported   int         `json:"userGroupsImported"`
+	PermissionsImported  int         `json:"permissionsImported"`
+	ConfigsImported      int         `json:"configsImported"`
+	AutoBackup           *BackupData `json:"autoBackup,omitempty"`
+}
+
+// ─── View Structs (used by Repository, not GORM models) ─────────────
+// These are used for JOIN query results that don't map 1:1 to a table.
+
+// ForwardRecord is a minimal forward view used by control plane and flow policy.
+type ForwardRecord struct {
+	ID         int64
+	UserID     int64
+	UserName   string
+	Name       string
+	TunnelID   int64
+	RemoteAddr string
+	Strategy   string
+	Status     int
+}
+
+// TunnelRecord is a minimal tunnel view used by control plane.
+type TunnelRecord struct {
+	ID           int64
+	Type         int
+	Status       int
+	Flow         int64
+	TrafficRatio float64
+}
+
+// ForwardPortRecord is a forward port mapping used by control plane.
+type ForwardPortRecord struct {
+	NodeID int64
+	Port   int
+}
+
+// NodeRecord is a node view used by control plane.
+type NodeRecord struct {
+	ID            int64
+	Name          string
+	ServerIP      string
+	ServerIPv4    string
+	ServerIPv6    string
+	Status        int
+	PortRange     string
+	TCPListenAddr string
+	UDPListenAddr string
+	InterfaceName string
+	IsRemote      int
+	RemoteURL     string
+	RemoteToken   string
+	RemoteConfig  string
+}
+
+type ChainNodeRecord struct {
+	ChainType int
+	Inx       int64
+	NodeID    int64
+	Port      int
+	NodeName  string
+	Protocol  string
+	Strategy  string
+}
+
+type UserTunnelLimiterInfo struct {
+	UserTunnelID int64
+	LimiterID    *int64
+	Speed        *int
+}
+
+// UserFlowSnapshot holds a user's current flow counters (used by stats job).
+type UserFlowSnapshot struct {
+	UserID  int64
+	InFlow  int64
+	OutFlow int64
+}
+
+// ExpiredUserTunnel holds minimal info for an expired user_tunnel row.
+type ExpiredUserTunnel struct {
+	ID       int64
+	UserID   int64
+	TunnelID int64
+}
+
+// UserTunnelDetail is a joined view of user_tunnel + tunnel + speed_limit.
+type UserTunnelDetail struct {
+	ID            int64
+	UserID        int64
+	TunnelID      int64
+	TunnelName    string
+	TunnelFlow    int
+	Flow          int64
+	InFlow        int64
+	OutFlow       int64
+	Num           int
+	FlowResetTime int64
+	ExpTime       int64
+	SpeedID       sql.NullInt64
+	SpeedLimit    sql.NullString
+	Speed         sql.NullInt64
+}
+
+// UserForwardDetail is a joined view of forward + tunnel.
+type UserForwardDetail struct {
+	ID         int64
+	Name       string
+	TunnelID   int64
+	TunnelName string
+	InIP       string
+	InPort     sql.NullInt64
+	RemoteAddr string
+	InFlow     int64
+	OutFlow    int64
+	Status     int
+	CreatedAt  int64
+}

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

@@ -0,0 +1,342 @@
+package repo
+
+import (
+	"database/sql"
+	"errors"
+	"fmt"
+	"strconv"
+	"strings"
+
+	"gorm.io/gorm"
+
+	"go-backend/internal/store/model"
+)
+
+func (r *Repository) UserTunnelExistsByUserAndTunnel(userID, tunnelID int64) (bool, error) {
+	if r == nil || r.db == nil {
+		return false, errors.New("repository not initialized")
+	}
+	var count int64
+	err := r.db.Model(&model.UserTunnel{}).
+		Where("user_id = ? AND tunnel_id = ? AND status = 1", userID, tunnelID).
+		Count(&count).Error
+	if err != nil {
+		return false, err
+	}
+	return count > 0, nil
+}
+
+func (r *Repository) ListForwardsByTunnel(tunnelID int64) ([]model.ForwardRecord, error) {
+	if r == nil || r.db == nil {
+		return nil, errors.New("repository not initialized")
+	}
+	var forwards []model.Forward
+	err := r.db.Where("tunnel_id = ?", tunnelID).Order("id ASC").Find(&forwards).Error
+	if err != nil {
+		return nil, err
+	}
+	rows := make([]model.ForwardRecord, 0, len(forwards))
+	for _, f := range forwards {
+		rows = append(rows, model.ForwardRecord{
+			ID:         f.ID,
+			UserID:     f.UserID,
+			UserName:   f.UserName,
+			Name:       f.Name,
+			TunnelID:   f.TunnelID,
+			RemoteAddr: f.RemoteAddr,
+			Strategy:   f.Strategy,
+			Status:     f.Status,
+		})
+	}
+	for i := range rows {
+		if strings.TrimSpace(rows[i].Strategy) == "" {
+			rows[i].Strategy = "fifo"
+		}
+	}
+	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")
+	}
+	var ports []model.ForwardPort
+	err := r.db.Where("forward_id = ?", forwardID).Order("id ASC").Find(&ports).Error
+	if err != nil {
+		return nil, err
+	}
+	rows := make([]model.ForwardPortRecord, 0, len(ports))
+	for _, p := range ports {
+		rows = append(rows, model.ForwardPortRecord{NodeID: p.NodeID, Port: p.Port})
+	}
+	return rows, nil
+}
+
+func (r *Repository) GetTunnelOutProtocol(tunnelID int64) (string, error) {
+	if r == nil || r.db == nil {
+		return "", errors.New("repository not initialized")
+	}
+	var ct model.ChainTunnel
+	err := r.db.Select("protocol").
+		Where("tunnel_id = ? AND chain_type = ?", tunnelID, "3").
+		Order("id ASC").
+		Take(&ct).Error
+	if err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return "", nil
+		}
+		return "", err
+	}
+	if ct.Protocol.Valid {
+		return ct.Protocol.String, nil
+	}
+	return "", nil
+}
+
+func (r *Repository) GetNodeRecord(nodeID int64) (*model.NodeRecord, error) {
+	if r == nil || r.db == nil {
+		return nil, errors.New("repository not initialized")
+	}
+	var n model.Node
+	err := r.db.Where("id = ?", nodeID).First(&n).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	return nodeRecordFromModel(&n), nil
+}
+
+func (r *Repository) GetNodeRecordTx(tx *gorm.DB, nodeID int64) (*model.NodeRecord, error) {
+	if tx == nil {
+		return nil, errors.New("database unavailable")
+	}
+	var n model.Node
+	err := tx.Where("id = ?", nodeID).First(&n).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	return nodeRecordFromModel(&n), nil
+}
+
+func nodeRecordFromModel(n *model.Node) *model.NodeRecord {
+	if n == nil {
+		return nil
+	}
+	rec := &model.NodeRecord{
+		ID:            n.ID,
+		Name:          n.Name,
+		ServerIP:      n.ServerIP,
+		Status:        n.Status,
+		PortRange:     n.Port,
+		TCPListenAddr: n.TCPListenAddr, UDPListenAddr: n.UDPListenAddr,
+		IsRemote: n.IsRemote,
+	}
+	if n.ServerIPV4.Valid {
+		rec.ServerIPv4 = strings.TrimSpace(n.ServerIPV4.String)
+	}
+	if n.ServerIPV6.Valid {
+		rec.ServerIPv6 = strings.TrimSpace(n.ServerIPV6.String)
+	}
+	if n.InterfaceName.Valid {
+		rec.InterfaceName = strings.TrimSpace(n.InterfaceName.String)
+	}
+	if n.RemoteURL.Valid {
+		rec.RemoteURL = strings.TrimSpace(n.RemoteURL.String)
+	}
+	if n.RemoteToken.Valid {
+		rec.RemoteToken = strings.TrimSpace(n.RemoteToken.String)
+	}
+	if n.RemoteConfig.Valid {
+		rec.RemoteConfig = strings.TrimSpace(n.RemoteConfig.String)
+	}
+	if rec.TCPListenAddr == "" {
+		rec.TCPListenAddr = "[::]"
+	}
+	if rec.UDPListenAddr == "" {
+		rec.UDPListenAddr = "[::]"
+	}
+	if strings.TrimSpace(rec.Name) == "" {
+		rec.Name = fmt.Sprintf("node_%d", rec.ID)
+	}
+	return rec
+}
+
+func (r *Repository) ResolveUserTunnelAndLimiter(userID, tunnelID int64) (*model.UserTunnelLimiterInfo, error) {
+	if r == nil || r.db == nil {
+		return nil, errors.New("repository not initialized")
+	}
+	type row struct {
+		UserTunnelID int64         `gorm:"column:user_tunnel_id"`
+		LimiterID    sql.NullInt64 `gorm:"column:limiter_id"`
+		Speed        sql.NullInt64 `gorm:"column:speed"`
+	}
+	var rec row
+	err := r.db.Model(&model.UserTunnel{}).
+		Select("user_tunnel.id AS user_tunnel_id, speed_limit.id AS limiter_id, speed_limit.speed AS speed").
+		Joins("LEFT JOIN speed_limit ON speed_limit.id = user_tunnel.speed_id").
+		Where("user_tunnel.user_id = ? AND user_tunnel.tunnel_id = ?", userID, tunnelID).
+		Order("user_tunnel.id ASC").
+		Limit(1).
+		Take(&rec).Error
+	if err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return &model.UserTunnelLimiterInfo{}, nil
+		}
+		return nil, err
+	}
+	info := &model.UserTunnelLimiterInfo{UserTunnelID: rec.UserTunnelID}
+	if rec.LimiterID.Valid && rec.LimiterID.Int64 > 0 {
+		v := rec.LimiterID.Int64
+		info.LimiterID = &v
+		s := int(rec.Speed.Int64)
+		info.Speed = &s
+	}
+	return info, nil
+}
+
+func (r *Repository) ListUserTunnelIDs(userID, tunnelID int64) ([]int64, error) {
+	if r == nil || r.db == nil {
+		return nil, errors.New("repository not initialized")
+	}
+	var ids []int64
+	err := r.db.Model(&model.UserTunnel{}).
+		Where("user_id = ? AND tunnel_id = ?", userID, tunnelID).
+		Order("id ASC").Pluck("id", &ids).Error
+	if err != nil {
+		return nil, err
+	}
+	return ids, nil
+}
+
+func (r *Repository) ListUserTunnelIDsByUser(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.UserTunnel{}).
+		Where("user_id = ?", userID).
+		Order("id ASC").Pluck("id", &ids).Error
+	if err != nil {
+		return nil, err
+	}
+	return ids, nil
+}
+
+func (r *Repository) GetTunnelName(tunnelID int64) (string, error) {
+	if r == nil || r.db == nil {
+		return "", errors.New("repository not initialized")
+	}
+	var name string
+	err := r.db.Model(&model.Tunnel{}).Where("id = ?", tunnelID).Pluck("name", &name).Error
+	if err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return "", nil
+		}
+		return "", err
+	}
+	return name, nil
+}
+
+func (r *Repository) ListChainNodesForTunnel(tunnelID int64) ([]model.ChainNodeRecord, error) {
+	if r == nil || r.db == nil {
+		return nil, errors.New("repository not initialized")
+	}
+	type row struct {
+		ChainType string
+		Inx       sql.NullInt64
+		NodeID    int64
+		Port      sql.NullInt64
+		Name      sql.NullString
+		Protocol  sql.NullString
+		Strategy  sql.NullString
+	}
+	var rows []row
+	err := r.db.Model(&model.ChainTunnel{}).
+		Select("chain_tunnel.chain_type, chain_tunnel.inx, chain_tunnel.node_id, chain_tunnel.port, node.name, chain_tunnel.protocol, chain_tunnel.strategy").
+		Joins("LEFT JOIN node ON node.id = chain_tunnel.node_id").
+		Where("chain_tunnel.tunnel_id = ?", tunnelID).
+		Order("chain_tunnel.chain_type ASC, chain_tunnel.inx ASC, chain_tunnel.id ASC").
+		Find(&rows).Error
+	if err != nil {
+		return nil, err
+	}
+	result := make([]model.ChainNodeRecord, 0, len(rows))
+	for _, row := range rows {
+		chainType := 0
+		if v := strings.TrimSpace(row.ChainType); v != "" {
+			if parsed, parseErr := strconv.Atoi(v); parseErr == nil {
+				chainType = parsed
+			}
+		}
+		inx := int64(0)
+		if row.Inx.Valid {
+			inx = row.Inx.Int64
+		}
+		port := 0
+		if row.Port.Valid {
+			port = int(row.Port.Int64)
+		}
+		item := model.ChainNodeRecord{
+			ChainType: chainType,
+			Inx:       inx,
+			NodeID:    row.NodeID,
+			Port:      port,
+		}
+		if strings.TrimSpace(row.Name.String) == "" {
+			item.NodeName = fmt.Sprintf("node_%d", row.NodeID)
+		} else {
+			item.NodeName = row.Name.String
+		}
+		if strings.TrimSpace(row.Protocol.String) == "" {
+			item.Protocol = "tls"
+		} else {
+			item.Protocol = row.Protocol.String
+		}
+		if strings.TrimSpace(row.Strategy.String) == "" {
+			item.Strategy = "round"
+		} else {
+			item.Strategy = row.Strategy.String
+		}
+		result = append(result, item)
+	}
+	return result, nil
+}

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

@@ -0,0 +1,298 @@
+package repo
+
+import (
+	"database/sql"
+	"errors"
+
+	"go-backend/internal/store/model"
+
+	"gorm.io/gorm"
+)
+
+// RemoteNodeRow holds the columns fetched for a remote node listing.
+type RemoteNodeRow struct {
+	ID           int64
+	Name         string
+	RemoteURL    sql.NullString
+	RemoteToken  sql.NullString
+	RemoteConfig sql.NullString
+}
+
+// NodeBasicInfo holds name, server_ip, and status for a node.
+type NodeBasicInfo struct {
+	Name     string
+	ServerIP string
+	Status   int
+}
+
+// FederationBindingRow holds the columns for an active federation tunnel binding.
+type FederationBindingRow struct {
+	ID              int64
+	TunnelID        int64
+	TunnelName      string
+	ChainType       int
+	HopInx          int
+	AllocatedPort   int
+	ResourceKey     string
+	RemoteBindingID string
+	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 {
+		return nil, errors.New("repository not initialized")
+	}
+	var result []RemoteNodeRow
+	err := r.db.Model(&model.Node{}).
+		Select("id, name, remote_url, remote_token, remote_config").
+		Where("is_remote = 1").
+		Order("id DESC").
+		Find(&result).Error
+	if err != nil {
+		return nil, err
+	}
+	if result == nil {
+		result = make([]RemoteNodeRow, 0)
+	}
+	return result, nil
+}
+
+// UpdateNodeRemoteConfig sets the remote_config JSON for a given node.
+func (r *Repository) UpdateNodeRemoteConfig(nodeID int64, configJSON string) error {
+	if r == nil || r.db == nil {
+		return errors.New("repository not initialized")
+	}
+	return r.db.Model(&model.Node{}).Where("id = ?", nodeID).Update("remote_config", configJSON).Error
+}
+
+// ListActiveBindingsForNode returns active federation tunnel bindings for a node.
+func (r *Repository) ListActiveBindingsForNode(nodeID int64) ([]FederationBindingRow, error) {
+	if r == nil || r.db == nil {
+		return nil, errors.New("repository not initialized")
+	}
+	var result []FederationBindingRow
+	err := r.db.Model(&model.FederationTunnelBinding{}).
+		Select("federation_tunnel_binding.id, federation_tunnel_binding.tunnel_id, COALESCE(tunnel.name, '') AS tunnel_name, federation_tunnel_binding.chain_type, federation_tunnel_binding.hop_inx, federation_tunnel_binding.allocated_port, federation_tunnel_binding.resource_key, federation_tunnel_binding.remote_binding_id, federation_tunnel_binding.updated_time").
+		Joins("LEFT JOIN tunnel ON tunnel.id = federation_tunnel_binding.tunnel_id").
+		Where("federation_tunnel_binding.node_id = ? AND federation_tunnel_binding.status = 1", nodeID).
+		Order("federation_tunnel_binding.allocated_port ASC, federation_tunnel_binding.id ASC").
+		Find(&result).Error
+	if err != nil {
+		return nil, err
+	}
+	if result == nil {
+		result = make([]FederationBindingRow, 0)
+	}
+	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 {
+		return nil, errors.New("repository not initialized")
+	}
+	var n model.Node
+	err := r.db.Select("name", "server_ip", "status").Where("id = ?", nodeID).First(&n).Error
+	if err != nil {
+		return nil, err
+	}
+	return &NodeBasicInfo{Name: n.Name, ServerIP: n.ServerIP, Status: n.Status}, nil
+}
+
+// CreateFederationTunnel creates a tunnel and chain_tunnel entry in a transaction,
+// returning the new tunnel ID.
+func (r *Repository) CreateFederationTunnel(name string, tunnelType int, protocol string, now int64, nodeID int64, remotePort int) (int64, error) {
+	if r == nil || r.db == nil {
+		return 0, errors.New("repository not initialized")
+	}
+	tunnel := model.Tunnel{
+		Name:        name,
+		Type:        tunnelType,
+		Protocol:    protocol,
+		Flow:        0,
+		CreatedTime: now,
+		UpdatedTime: now,
+		Status:      1,
+		InIP:        sql.NullString{String: "", Valid: false},
+	}
+	err := r.db.Transaction(func(tx *gorm.DB) error {
+		if err := tx.Create(&tunnel).Error; err != nil {
+			return err
+		}
+		ct := model.ChainTunnel{
+			TunnelID:  tunnel.ID,
+			ChainType: "1",
+			NodeID:    nodeID,
+			Port:      sql.NullInt64{Int64: int64(remotePort), Valid: true},
+			Strategy:  sql.NullString{String: "fifo", Valid: true},
+			Inx:       sql.NullInt64{Int64: 0, Valid: true},
+			Protocol:  sql.NullString{String: protocol, Valid: true},
+		}
+		if err := tx.Create(&ct).Error; err != nil {
+			return err
+		}
+		return nil
+	})
+	if err != nil {
+		return 0, err
+	}
+	return tunnel.ID, nil
+}
+
+// ListUsedPortsOnNode returns all ports in use on a given node from chain_tunnel and forward_port tables.
+func (r *Repository) ListUsedPortsOnNode(nodeID int64) ([]int, error) {
+	if r == nil || r.db == nil {
+		return nil, errors.New("repository not initialized")
+	}
+	used := make(map[int]struct{})
+
+	var chainPorts []int
+	err := r.db.Model(&model.ChainTunnel{}).
+		Where("node_id = ? AND port > 0", nodeID).
+		Pluck("port", &chainPorts).Error
+	if err != nil {
+		return nil, err
+	}
+	for _, p := range chainPorts {
+		if p > 0 {
+			used[p] = struct{}{}
+		}
+	}
+
+	var forwardPorts []int
+	err = r.db.Model(&model.ForwardPort{}).
+		Where("node_id = ? AND port > 0", nodeID).
+		Pluck("port", &forwardPorts).Error
+	if err != nil {
+		return nil, err
+	}
+	for _, p := range forwardPorts {
+		if p > 0 {
+			used[p] = struct{}{}
+		}
+	}
+
+	result := make([]int, 0, len(used))
+	for p := range used {
+		result = append(result, p)
+	}
+	return result, nil
+}
+
+// ListTunnelIDsByNamePrefix returns all tunnel IDs whose name starts with the given prefix.
+func (r *Repository) ListTunnelIDsByNamePrefix(prefix string) ([]int64, error) {
+	if r == nil || r.db == nil {
+		return nil, errors.New("repository not initialized")
+	}
+	var ids []int64
+	err := r.db.Model(&model.Tunnel{}).
+		Where("name LIKE ?", prefix+"%").
+		Order("id ASC").
+		Pluck("id", &ids).Error
+	if err != nil {
+		return nil, err
+	}
+	if ids == nil {
+		ids = make([]int64, 0)
+	}
+	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
+	}
+	var modelRef interface{}
+	switch table {
+	case "node":
+		modelRef = &model.Node{}
+	case "tunnel":
+		modelRef = &model.Tunnel{}
+	case "forward":
+		modelRef = &model.Forward{}
+	default:
+		return 0
+	}
+
+	type inxRow struct {
+		Inx int
+	}
+	var row inxRow
+	err := r.db.Model(modelRef).
+		Select("inx").
+		Order("inx DESC").
+		Limit(1).
+		Take(&row).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return 0
+	}
+	if err != nil {
+		return 0
+	}
+	if row.Inx < 0 {
+		return 0
+	}
+	return row.Inx + 1
+}
+
+// CreateRemoteNode inserts a new remote node.
+func (r *Repository) CreateRemoteNode(name, secret, serverIP, portRange string, now int64, status int, inx int, remoteURL, remoteToken, remoteConfigJSON string) error {
+	if r == nil || r.db == nil {
+		return errors.New("repository not initialized")
+	}
+	node := model.Node{
+		Name:          name,
+		Secret:        secret,
+		ServerIP:      serverIP,
+		ServerIPV4:    sql.NullString{},
+		ServerIPV6:    sql.NullString{},
+		Port:          portRange,
+		InterfaceName: sql.NullString{},
+		Version:       sql.NullString{},
+		HTTP:          0,
+		TLS:           0,
+		Socks:         0,
+		CreatedTime:   now,
+		UpdatedTime:   sql.NullInt64{Int64: now, Valid: true},
+		Status:        status,
+		TCPListenAddr: "[::]",
+		UDPListenAddr: "[::]",
+		Inx:           inx,
+		IsRemote:      1,
+		RemoteURL:     sql.NullString{String: remoteURL, Valid: remoteURL != ""},
+		RemoteToken:   sql.NullString{String: remoteToken, Valid: remoteToken != ""},
+		RemoteConfig:  sql.NullString{String: remoteConfigJSON, Valid: remoteConfigJSON != ""},
+	}
+	return r.db.Create(&node).Error
+}

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

@@ -0,0 +1,171 @@
+package repo
+
+import (
+	"errors"
+	"strings"
+
+	"gorm.io/gorm"
+
+	"go-backend/internal/store/model"
+)
+
+func (r *Repository) UpdateForwardStatus(forwardID int64, status int, now int64) error {
+	if r == nil || r.db == nil {
+		return errors.New("repository not initialized")
+	}
+	return r.db.Model(&model.Forward{}).Where("id = ?", forwardID).Updates(map[string]interface{}{
+		"status": status, "updated_time": now,
+	}).Error
+}
+
+func (r *Repository) ListActiveForwardsByUser(userID int64) ([]model.ForwardRecord, error) {
+	if r == nil || r.db == nil {
+		return nil, errors.New("repository not initialized")
+	}
+	var forwards []model.Forward
+	err := r.db.Where("user_id = ? AND status = 1", userID).Order("id ASC").Find(&forwards).Error
+	if err != nil {
+		return nil, err
+	}
+	rows := make([]model.ForwardRecord, 0, len(forwards))
+	for _, f := range forwards {
+		rows = append(rows, model.ForwardRecord{
+			ID:         f.ID,
+			UserID:     f.UserID,
+			UserName:   f.UserName,
+			Name:       f.Name,
+			TunnelID:   f.TunnelID,
+			RemoteAddr: f.RemoteAddr,
+			Strategy:   f.Strategy,
+			Status:     f.Status,
+		})
+	}
+	for i := range rows {
+		if strings.TrimSpace(rows[i].Strategy) == "" {
+			rows[i].Strategy = "fifo"
+		}
+	}
+	return rows, nil
+}
+
+func (r *Repository) ListActiveForwardsByUserTunnel(userID, tunnelID int64) ([]model.ForwardRecord, error) {
+	if r == nil || r.db == nil {
+		return nil, errors.New("repository not initialized")
+	}
+	var forwards []model.Forward
+	err := r.db.Where("user_id = ? AND tunnel_id = ? AND status = 1", userID, tunnelID).Order("id ASC").Find(&forwards).Error
+	if err != nil {
+		return nil, err
+	}
+	rows := make([]model.ForwardRecord, 0, len(forwards))
+	for _, f := range forwards {
+		rows = append(rows, model.ForwardRecord{
+			ID:         f.ID,
+			UserID:     f.UserID,
+			UserName:   f.UserName,
+			Name:       f.Name,
+			TunnelID:   f.TunnelID,
+			RemoteAddr: f.RemoteAddr,
+			Strategy:   f.Strategy,
+			Status:     f.Status,
+		})
+	}
+	for i := range rows {
+		if strings.TrimSpace(rows[i].Strategy) == "" {
+			rows[i].Strategy = "fifo"
+		}
+	}
+	return rows, nil
+}
+
+func (r *Repository) GetForwardRecord(forwardID int64) (*model.ForwardRecord, error) {
+	if r == nil || r.db == nil {
+		return nil, errors.New("repository not initialized")
+	}
+	var f model.Forward
+	err := r.db.Where("id = ?", forwardID).First(&f).Error
+	if err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return nil, nil
+		}
+		return nil, err
+	}
+	fr := model.ForwardRecord{
+		ID:         f.ID,
+		UserID:     f.UserID,
+		UserName:   f.UserName,
+		Name:       f.Name,
+		TunnelID:   f.TunnelID,
+		RemoteAddr: f.RemoteAddr,
+		Strategy:   f.Strategy,
+		Status:     f.Status,
+	}
+	if strings.TrimSpace(fr.Strategy) == "" {
+		fr.Strategy = "fifo"
+	}
+	return &fr, nil
+}
+
+func (r *Repository) GetTunnelRecord(tunnelID int64) (*model.TunnelRecord, error) {
+	if r == nil || r.db == nil {
+		return nil, errors.New("repository not initialized")
+	}
+	var t model.Tunnel
+	err := r.db.Where("id = ?", tunnelID).First(&t).Error
+	if err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			return nil, nil
+		}
+		return nil, err
+	}
+	tr := model.TunnelRecord{
+		ID:           t.ID,
+		Type:         t.Type,
+		Status:       t.Status,
+		Flow:         t.Flow,
+		TrafficRatio: t.TrafficRatio,
+	}
+	if tr.Flow <= 0 {
+		tr.Flow = 1
+	}
+	if tr.TrafficRatio <= 0 {
+		tr.TrafficRatio = 1
+	}
+	return &tr, nil
+}
+
+func (r *Repository) TunnelExists(tunnelID int64) (bool, error) {
+	if r == nil || r.db == nil {
+		return false, errors.New("repository not initialized")
+	}
+	var count int64
+	err := r.db.Model(&model.Tunnel{}).Where("id = ?", tunnelID).Count(&count).Error
+	if err != nil {
+		return false, err
+	}
+	return count > 0, nil
+}
+
+func (r *Repository) ForwardExists(forwardID int64) (bool, error) {
+	if r == nil || r.db == nil {
+		return false, errors.New("repository not initialized")
+	}
+	var count int64
+	err := r.db.Model(&model.Forward{}).Where("id = ?", forwardID).Count(&count).Error
+	if err != nil {
+		return false, err
+	}
+	return count > 0, nil
+}
+
+func (r *Repository) SpeedLimitExists(id int64) (bool, error) {
+	if r == nil || r.db == nil {
+		return false, errors.New("repository not initialized")
+	}
+	var count int64
+	err := r.db.Model(&model.SpeedLimit{}).Where("id = ?", id).Count(&count).Error
+	if err != nil {
+		return false, err
+	}
+	return count > 0, nil
+}

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

@@ -0,0 +1,78 @@
+package repo
+
+import (
+	"errors"
+
+	"go-backend/internal/store/model"
+)
+
+// ─── Semantic Group Queries (replacing QueryInt64List/QueryPairs passthrough) ─
+
+// ListUserIDsByUserGroup returns all user IDs belonging to a user group.
+func (r *Repository) ListUserIDsByUserGroup(userGroupID 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_group_id = ?", userGroupID).
+		Pluck("user_id", &ids).Error
+	return ids, err
+}
+
+// ListTunnelIDsByTunnelGroup returns all tunnel IDs belonging to a tunnel group.
+func (r *Repository) ListTunnelIDsByTunnelGroup(tunnelGroupID int64) ([]int64, error) {
+	if r == nil || r.db == nil {
+		return nil, errors.New("repository not initialized")
+	}
+	var ids []int64
+	err := r.db.Model(&model.TunnelGroupTunnel{}).
+		Where("tunnel_group_id = ?", tunnelGroupID).
+		Pluck("tunnel_id", &ids).Error
+	return ids, err
+}
+
+// ListGroupPermissionPairsByUserGroup returns [userGroupID, tunnelGroupID] pairs
+// for all group permissions associated with a user group.
+func (r *Repository) ListGroupPermissionPairsByUserGroup(userGroupID int64) ([][2]int64, error) {
+	if r == nil || r.db == nil {
+		return nil, errors.New("repository not initialized")
+	}
+	var perms []model.GroupPermission
+	err := r.db.Where("user_group_id = ?", userGroupID).Find(&perms).Error
+	if err != nil {
+		return nil, err
+	}
+	result := make([][2]int64, len(perms))
+	for i, p := range perms {
+		result[i] = [2]int64{p.UserGroupID, p.TunnelGroupID}
+	}
+	return result, err
+}
+
+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")
+	}
+	var perms []model.GroupPermission
+	err := r.db.Where("tunnel_group_id = ?", tunnelGroupID).Find(&perms).Error
+	if err != nil {
+		return nil, err
+	}
+	result := make([][2]int64, len(perms))
+	for i, p := range perms {
+		result[i] = [2]int64{p.UserGroupID, p.TunnelGroupID}
+	}
+	return result, err
+}

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

@@ -0,0 +1,85 @@
+package repo
+
+import (
+	"errors"
+	"testing"
+
+	gsqlite "github.com/glebarez/sqlite"
+	"gorm.io/gorm"
+	"gorm.io/gorm/logger"
+)
+
+func TestMigrateSchemaRunsPostgresIDRepairEvenAtCurrentVersion(t *testing.T) {
+	db, err := gorm.Open(gsqlite.Open(":memory:"), &gorm.Config{
+		Logger: logger.Default.LogMode(logger.Silent),
+	})
+	if err != nil {
+		t.Fatalf("open sqlite: %v", err)
+	}
+	t.Cleanup(func() {
+		sqlDB, _ := db.DB()
+		if sqlDB != nil {
+			_ = sqlDB.Close()
+		}
+	})
+
+	if err := db.Exec(`CREATE TABLE schema_version (version INTEGER NOT NULL DEFAULT 0)`).Error; err != nil {
+		t.Fatalf("create schema_version: %v", err)
+	}
+	if err := db.Exec(`INSERT INTO schema_version(version) VALUES(?)`, currentSchemaVersion).Error; err != nil {
+		t.Fatalf("seed schema_version: %v", err)
+	}
+
+	called := 0
+	original := ensurePostgresIDDefaultsFn
+	ensurePostgresIDDefaultsFn = func(db *gorm.DB) error {
+		called++
+		return nil
+	}
+	t.Cleanup(func() {
+		ensurePostgresIDDefaultsFn = original
+	})
+
+	if err := migrateSchema(db); err != nil {
+		t.Fatalf("migrateSchema: %v", err)
+	}
+	if called != 1 {
+		t.Fatalf("expected postgres id repair to run once, got %d", called)
+	}
+}
+
+func TestMigrateSchemaReturnsPostgresIDRepairError(t *testing.T) {
+	db, err := gorm.Open(gsqlite.Open(":memory:"), &gorm.Config{
+		Logger: logger.Default.LogMode(logger.Silent),
+	})
+	if err != nil {
+		t.Fatalf("open sqlite: %v", err)
+	}
+	t.Cleanup(func() {
+		sqlDB, _ := db.DB()
+		if sqlDB != nil {
+			_ = sqlDB.Close()
+		}
+	})
+
+	if err := db.Exec(`CREATE TABLE schema_version (version INTEGER NOT NULL DEFAULT 0)`).Error; err != nil {
+		t.Fatalf("create schema_version: %v", err)
+	}
+	if err := db.Exec(`INSERT INTO schema_version(version) VALUES(?)`, currentSchemaVersion).Error; err != nil {
+		t.Fatalf("seed schema_version: %v", err)
+	}
+
+	wantErr := errors.New("repair failed")
+	original := ensurePostgresIDDefaultsFn
+	ensurePostgresIDDefaultsFn = func(db *gorm.DB) error {
+		return wantErr
+	}
+	t.Cleanup(func() {
+		ensurePostgresIDDefaultsFn = original
+	})
+
+	err = migrateSchema(db)
+	if !errors.Is(err, wantErr) {
+		t.Fatalf("expected error %v, got %v", wantErr, err)
+	}
+}

go-backend/internal/store/sqlite/sql/data.sql

@@ -1,5 +0,0 @@
-INSERT OR IGNORE INTO user (id, user, pwd, role_id, exp_time, flow, in_flow, out_flow, flow_reset_time, num, created_time, updated_time, status)
-VALUES (1, 'admin_user', '3c85cdebade1c51cf64ca9f3c09d182d', 0, 2727251700000, 99999, 0, 0, 1, 99999, 1748914865000, 1754011744252, 1);
-
-INSERT OR IGNORE INTO vite_config (id, name, value, time)
-VALUES (1, 'app_name', 'flux', 1755147963000);

go-backend/internal/store/sqlite/sql/schema.sql

@@ -1,183 +0,0 @@
--- SQLite Auto-generated schema
--- This will be executed automatically on startup if tables don't exist
-
-CREATE TABLE IF NOT EXISTS forward (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  user_id INTEGER NOT NULL,
-  user_name VARCHAR(100) NOT NULL,
-  name VARCHAR(100) NOT NULL,
-  tunnel_id INTEGER NOT NULL,
-  remote_addr TEXT NOT NULL,
-  strategy VARCHAR(100) NOT NULL DEFAULT 'fifo',
-  in_flow INTEGER NOT NULL DEFAULT 0,
-  out_flow INTEGER NOT NULL DEFAULT 0,
-  created_time INTEGER NOT NULL,
-  updated_time INTEGER NOT NULL,
-  status INTEGER NOT NULL,
-  inx INTEGER NOT NULL DEFAULT 0
-);
-
-CREATE TABLE IF NOT EXISTS forward_port (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  forward_id INTEGER NOT NULL,
-  node_id INTEGER NOT NULL,
-  port INTEGER NOT NULL
-);
-
-CREATE TABLE IF NOT EXISTS node (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  name VARCHAR(100) NOT NULL,
-  secret VARCHAR(100) NOT NULL,
-  server_ip VARCHAR(100) NOT NULL,
-  server_ip_v4 VARCHAR(100),
-  server_ip_v6 VARCHAR(100),
-  port TEXT NOT NULL,
-  interface_name VARCHAR(200),
-  version VARCHAR(100),
-  http INTEGER NOT NULL DEFAULT 0,
-  tls INTEGER NOT NULL DEFAULT 0,
-  socks INTEGER NOT NULL DEFAULT 0,
-  created_time INTEGER NOT NULL,
-  updated_time INTEGER,
-  status INTEGER NOT NULL,
-  tcp_listen_addr VARCHAR(100) NOT NULL DEFAULT '[::]',
-  udp_listen_addr VARCHAR(100) NOT NULL DEFAULT '[::]',
-  inx INTEGER NOT NULL DEFAULT 0
-);
-
-CREATE TABLE IF NOT EXISTS speed_limit (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  name VARCHAR(100) NOT NULL,
-  speed INTEGER NOT NULL,
-  tunnel_id INTEGER NOT NULL,
-  tunnel_name VARCHAR(100) NOT NULL,
-  created_time INTEGER NOT NULL,
-  updated_time INTEGER,
-  status INTEGER NOT NULL
-);
-
-CREATE TABLE IF NOT EXISTS statistics_flow (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  user_id INTEGER NOT NULL,
-  flow INTEGER NOT NULL,
-  total_flow INTEGER NOT NULL,
-  time VARCHAR(100) NOT NULL,
-  created_time INTEGER NOT NULL
-);
-
-CREATE TABLE IF NOT EXISTS tunnel (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  name VARCHAR(100) NOT NULL,
-  traffic_ratio REAL NOT NULL DEFAULT 1.0,
-  type INTEGER NOT NULL,
-  protocol VARCHAR(10) NOT NULL DEFAULT 'tls',
-  flow INTEGER NOT NULL,
-  created_time INTEGER NOT NULL,
-  updated_time INTEGER NOT NULL,
-  status INTEGER NOT NULL,
-  in_ip TEXT,
-  inx INTEGER NOT NULL DEFAULT 0
-);
-
-CREATE TABLE IF NOT EXISTS chain_tunnel (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    tunnel_id INTEGER NOT NULL ,
-    chain_type VARCHAR(10) NOT NULL,
-    node_id INTEGER NOT NULL ,
-    port INTEGER,
-    strategy VARCHAR(10),
-    inx  INTEGER,
-    protocol  VARCHAR(10)
-);
-
-
-CREATE TABLE IF NOT EXISTS user (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  user VARCHAR(100) NOT NULL,
-  pwd VARCHAR(100) NOT NULL,
-  role_id INTEGER NOT NULL,
-  exp_time INTEGER NOT NULL,
-  flow INTEGER NOT NULL,
-  in_flow INTEGER NOT NULL DEFAULT 0,
-  out_flow INTEGER NOT NULL DEFAULT 0,
-  flow_reset_time INTEGER NOT NULL,
-  num INTEGER NOT NULL,
-  created_time INTEGER NOT NULL,
-  updated_time INTEGER,
-  status INTEGER NOT NULL
-);
-
-CREATE TABLE IF NOT EXISTS user_tunnel (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  user_id INTEGER NOT NULL,
-  tunnel_id INTEGER NOT NULL,
-  speed_id INTEGER,
-  num INTEGER NOT NULL,
-  flow INTEGER NOT NULL,
-  in_flow INTEGER NOT NULL DEFAULT 0,
-  out_flow INTEGER NOT NULL DEFAULT 0,
-  flow_reset_time INTEGER NOT NULL,
-  exp_time INTEGER NOT NULL,
-  status INTEGER NOT NULL
-);
-
-CREATE TABLE IF NOT EXISTS tunnel_group (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  name VARCHAR(100) NOT NULL,
-  created_time INTEGER NOT NULL,
-  updated_time INTEGER NOT NULL,
-  status INTEGER NOT NULL
-);
-
-CREATE TABLE IF NOT EXISTS user_group (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  name VARCHAR(100) NOT NULL,
-  created_time INTEGER NOT NULL,
-  updated_time INTEGER NOT NULL,
-  status INTEGER NOT NULL
-);
-
-CREATE TABLE IF NOT EXISTS tunnel_group_tunnel (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  tunnel_group_id INTEGER NOT NULL,
-  tunnel_id INTEGER NOT NULL,
-  created_time INTEGER NOT NULL
-);
-
-CREATE TABLE IF NOT EXISTS user_group_user (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  user_group_id INTEGER NOT NULL,
-  user_id INTEGER NOT NULL,
-  created_time INTEGER NOT NULL
-);
-
-CREATE TABLE IF NOT EXISTS group_permission (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  user_group_id INTEGER NOT NULL,
-  tunnel_group_id INTEGER NOT NULL,
-  created_time INTEGER NOT NULL
-);
-
-CREATE TABLE IF NOT EXISTS group_permission_grant (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  user_group_id INTEGER NOT NULL,
-  tunnel_group_id INTEGER NOT NULL,
-  user_tunnel_id INTEGER NOT NULL,
-  created_by_group INTEGER NOT NULL DEFAULT 0,
-  created_time INTEGER NOT NULL
-);
-
-CREATE UNIQUE INDEX IF NOT EXISTS idx_tunnel_group_name ON tunnel_group(name);
-CREATE UNIQUE INDEX IF NOT EXISTS idx_user_group_name ON user_group(name);
-CREATE UNIQUE INDEX IF NOT EXISTS idx_tunnel_group_tunnel_unique ON tunnel_group_tunnel(tunnel_group_id, tunnel_id);
-CREATE UNIQUE INDEX IF NOT EXISTS idx_user_group_user_unique ON user_group_user(user_group_id, user_id);
-CREATE UNIQUE INDEX IF NOT EXISTS idx_group_permission_unique ON group_permission(user_group_id, tunnel_group_id);
-CREATE UNIQUE INDEX IF NOT EXISTS idx_group_permission_grant_unique ON group_permission_grant(user_group_id, tunnel_group_id, user_tunnel_id);
-CREATE UNIQUE INDEX IF NOT EXISTS idx_user_tunnel_unique ON user_tunnel(user_id, tunnel_id);
-
-CREATE TABLE IF NOT EXISTS vite_config (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  name VARCHAR(200) NOT NULL UNIQUE,
-  value VARCHAR(200) NOT NULL,
-  time INTEGER NOT NULL
-);

go-backend/internal/ws/server.go

@@ -15,7 +15,7 @@ import (
 
 	"go-backend/internal/auth"
 	"go-backend/internal/security"
-	"go-backend/internal/store/sqlite"
+	"go-backend/internal/store/repo"
 )
 
 type encryptedMessage struct {
@@ -54,6 +54,12 @@ type pendingRequest struct {
 	ch     chan CommandResult
 }
 
+const (
+	wsPingPeriod = 15 * time.Second
+	wsPongWait   = 45 * time.Second
+	wsWriteWait  = 5 * time.Second
+)
+
 type CommandResult struct {
 	Type    string                 `json:"type"`
 	Success bool                   `json:"success"`
@@ -62,9 +68,10 @@ type CommandResult struct {
 }
 
 type Server struct {
-	repo      *sqlite.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{}
@@ -73,7 +80,16 @@ type Server struct {
 	pending map[string]pendingRequest
 }
 
-func NewServer(repo *sqlite.Repository, jwtSecret string) *Server {
+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,
 		jwtSecret: jwtSecret,
@@ -120,12 +136,19 @@ func (s *Server) handleAdmin(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 	cw := &connWrap{conn: conn}
+	_ = conn.SetReadDeadline(time.Now().Add(wsPongWait))
+	conn.SetPongHandler(func(string) error {
+		return conn.SetReadDeadline(time.Now().Add(wsPongWait))
+	})
+	done := make(chan struct{})
+	go startKeepalive(cw, done)
 
 	s.mu.Lock()
 	s.admins[cw] = struct{}{}
 	s.mu.Unlock()
 
 	defer func() {
+		close(done)
 		s.mu.Lock()
 		delete(s.admins, cw)
 		s.mu.Unlock()
@@ -145,6 +168,12 @@ func (s *Server) handleNode(w http.ResponseWriter, r *http.Request, nodeID int64
 		return
 	}
 	cw := &connWrap{conn: conn}
+	_ = conn.SetReadDeadline(time.Now().Add(wsPongWait))
+	conn.SetPongHandler(func(string) error {
+		return conn.SetReadDeadline(time.Now().Add(wsPongWait))
+	})
+	done := make(chan struct{})
+	go startKeepalive(cw, done)
 
 	version := r.URL.Query().Get("version")
 	httpVal := parseIntDefault(r.URL.Query().Get("http"), 0)
@@ -164,7 +193,15 @@ 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
 		s.mu.Lock()
 		current, ok := s.nodes[nodeID]
@@ -190,7 +227,15 @@ func (s *Server) handleNode(w http.ResponseWriter, r *http.Request, nodeID int64
 
 		msg := decryptIfNeeded(payload, secret)
 		s.tryResolvePending(nodeID, msg)
-		s.broadcastInfo(nodeID, msg)
+
+		var parsed struct {
+			Type string `json:"type"`
+		}
+		if json.Unmarshal([]byte(msg), &parsed) == nil && parsed.Type == "UpgradeProgress" {
+			s.broadcastTyped(nodeID, "upgrade_progress", msg)
+		} else {
+			s.broadcastInfo(nodeID, msg)
+		}
 	}
 }
 
@@ -264,7 +309,9 @@ func (s *Server) SendCommand(nodeID int64, cmdType string, data interface{}, tim
 	}
 
 	ns.conn.mu.Lock()
+	_ = ns.conn.conn.SetWriteDeadline(time.Now().Add(wsWriteWait))
 	err = ns.conn.conn.WriteMessage(websocket.TextMessage, messageData)
+	_ = ns.conn.conn.SetWriteDeadline(time.Time{})
 	ns.conn.mu.Unlock()
 	if err != nil {
 		cleanup()
@@ -385,6 +432,12 @@ func (s *Server) broadcastInfo(nodeID int64, data string) {
 	s.broadcastToAdmins(string(raw))
 }
 
+func (s *Server) broadcastTyped(nodeID int64, msgType string, data string) {
+	payload := broadcastMessage{ID: nodeID, Type: msgType, Data: data}
+	raw, _ := json.Marshal(payload)
+	s.broadcastToAdmins(string(raw))
+}
+
 func (s *Server) broadcastToAdmins(message string) {
 	s.mu.RLock()
 	admins := make([]*connWrap, 0, len(s.admins))
@@ -395,7 +448,9 @@ func (s *Server) broadcastToAdmins(message string) {
 
 	for _, c := range admins {
 		c.mu.Lock()
+		_ = c.conn.SetWriteDeadline(time.Now().Add(wsWriteWait))
 		err := c.conn.WriteMessage(websocket.TextMessage, []byte(message))
+		_ = c.conn.SetWriteDeadline(time.Time{})
 		c.mu.Unlock()
 		if err != nil {
 			log.Printf("websocket broadcast failed: %v", err)
@@ -428,3 +483,28 @@ func parseIntDefault(v string, fallback int) int {
 	}
 	return x
 }
+
+func startKeepalive(cw *connWrap, done <-chan struct{}) {
+	if cw == nil || cw.conn == nil {
+		return
+	}
+	ticker := time.NewTicker(wsPingPeriod)
+	defer ticker.Stop()
+
+	for {
+		select {
+		case <-done:
+			return
+		case <-ticker.C:
+			cw.mu.Lock()
+			_ = cw.conn.SetWriteDeadline(time.Now().Add(wsWriteWait))
+			err := cw.conn.WriteMessage(websocket.PingMessage, nil)
+			_ = cw.conn.SetWriteDeadline(time.Time{})
+			cw.mu.Unlock()
+			if err != nil {
+				_ = cw.conn.Close()
+				return
+			}
+		}
+	}
+}

go-backend/tests/contract/db_test_helper_internal_test.go

@@ -0,0 +1,19 @@
+package contract
+
+import (
+	"testing"
+
+	"go-backend/internal/store/repo"
+)
+
+func mustLastInsertID(t *testing.T, r *repo.Repository, label string) int64 {
+	t.Helper()
+	var id int64
+	if err := r.DB().Raw("SELECT last_insert_rowid()").Row().Scan(&id); err != nil {
+		t.Fatalf("read last_insert_rowid for %s: %v", label, err)
+	}
+	if id <= 0 {
+		t.Fatalf("invalid last_insert_rowid for %s: %d", label, id)
+	}
+	return id
+}

go-backend/tests/contract/db_test_helper_test.go

@@ -0,0 +1,119 @@
+package contract_test
+
+import (
+	"database/sql"
+	"testing"
+
+	"go-backend/internal/store/repo"
+)
+
+func mustLastInsertID(t *testing.T, r *repo.Repository, label string) int64 {
+	t.Helper()
+	var id int64
+	if err := r.DB().Raw("SELECT last_insert_rowid()").Row().Scan(&id); err != nil {
+		t.Fatalf("read last_insert_rowid for %s: %v", label, err)
+	}
+	if id <= 0 {
+		t.Fatalf("invalid last_insert_rowid for %s: %d", label, id)
+	}
+	return id
+}
+
+func mustQueryInt(t *testing.T, r *repo.Repository, query string, args ...interface{}) int {
+	t.Helper()
+	var v int
+	if err := r.DB().Raw(query, args...).Row().Scan(&v); err != nil {
+		t.Fatalf("query int failed: %v (query=%q)", err, query)
+	}
+	return v
+}
+
+func mustQueryInt64(t *testing.T, r *repo.Repository, query string, args ...interface{}) int64 {
+	t.Helper()
+	var v int64
+	if err := r.DB().Raw(query, args...).Row().Scan(&v); err != nil {
+		t.Fatalf("query int64 failed: %v (query=%q)", err, query)
+	}
+	return v
+}
+
+func mustQueryString(t *testing.T, r *repo.Repository, query string, args ...interface{}) string {
+	t.Helper()
+	var v string
+	if err := r.DB().Raw(query, args...).Row().Scan(&v); err != nil {
+		t.Fatalf("query string failed: %v (query=%q)", err, query)
+	}
+	return v
+}
+
+func mustQueryInt64Int(t *testing.T, r *repo.Repository, query string, args ...interface{}) (int64, int) {
+	t.Helper()
+	var a int64
+	var b int
+	if err := r.DB().Raw(query, args...).Row().Scan(&a, &b); err != nil {
+		t.Fatalf("query int64+int failed: %v (query=%q)", err, query)
+	}
+	return a, b
+}
+
+func tryQueryString(t *testing.T, r *repo.Repository, query string, args ...interface{}) (string, error) {
+	t.Helper()
+	var v string
+	err := r.DB().Raw(query, args...).Row().Scan(&v)
+	if err != nil {
+		return "", err
+	}
+	return v, nil
+}
+
+func mustQueryNullString(t *testing.T, r *repo.Repository, query string, args ...interface{}) sql.NullString {
+	t.Helper()
+	var v sql.NullString
+	if err := r.DB().Raw(query, args...).Row().Scan(&v); err != nil {
+		t.Fatalf("query null string failed: %v (query=%q)", err, query)
+	}
+	return v
+}
+
+func mustQueryTwoNullStrings(t *testing.T, r *repo.Repository, query string, args ...interface{}) (sql.NullString, sql.NullString) {
+	t.Helper()
+	var a sql.NullString
+	var b sql.NullString
+	if err := r.DB().Raw(query, args...).Row().Scan(&a, &b); err != nil {
+		t.Fatalf("query two null strings failed: %v (query=%q)", err, query)
+	}
+	return a, b
+}
+
+func mustQueryNodePorts(t *testing.T, r *repo.Repository, query string, args ...interface{}) map[int64]int {
+	t.Helper()
+	rows, err := r.DB().Raw(query, args...).Rows()
+	if err != nil {
+		t.Fatalf("query node ports failed: %v (query=%q)", err, query)
+	}
+	defer rows.Close()
+
+	out := make(map[int64]int)
+	for rows.Next() {
+		var nodeID int64
+		var port int
+		if err := rows.Scan(&nodeID, &port); err != nil {
+			t.Fatalf("scan node ports row failed: %v (query=%q)", err, query)
+		}
+		out[nodeID] = port
+	}
+	if err := rows.Err(); err != nil {
+		t.Fatalf("iterate node ports rows failed: %v (query=%q)", err, query)
+	}
+	return out
+}
+
+func tryQueryInt(t *testing.T, r *repo.Repository, query string, args ...interface{}) (int, error) {
+	t.Helper()
+	var v int
+	err := r.DB().Raw(query, args...).Row().Scan(&v)
+	if err != nil {
+		return 0, err
+	}
+	return v, nil
+}

go-backend/tests/contract/diagnosis_contract_test.go

@@ -8,6 +8,7 @@ import (
 	"path/filepath"
 	"strconv"
 	"strings"
+	"sync/atomic"
 	"testing"
 	"time"
 
@@ -15,82 +16,69 @@ import (
 	httpserver "go-backend/internal/http"
 	"go-backend/internal/http/handler"
 	"go-backend/internal/http/response"
-	"go-backend/internal/store/sqlite"
+	"go-backend/internal/store/repo"
 )
 
 func TestDiagnosisChainCoverageContracts(t *testing.T) {
 	secret := "contract-jwt-secret"
-	router, repo := setupDiagnosisContractRouter(t, secret)
+	router, r := setupDiagnosisContractRouter(t, secret)
 	now := time.Now().UnixMilli()
 
-	if _, err := repo.DB().Exec(`
+	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); err != nil {
+	`, now, now).Error; err != nil {
 		t.Fatalf("insert user: %v", err)
 	}
 
-	tunnelRes, err := repo.DB().Exec(`
+	if err := r.DB().Exec(`
 		INSERT INTO tunnel(name, traffic_ratio, type, protocol, flow, created_time, updated_time, status, in_ip, inx)
 		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-	`, "diagnose-chain-tunnel", 1.0, 2, "tls", 99999, now, now, 1, nil, 0)
-	if err != nil {
+	`, "diagnose-chain-tunnel", 1.0, 2, "tls", 99999, now, now, 1, nil, 0).Error; err != nil {
 		t.Fatalf("insert tunnel: %v", err)
 	}
-	tunnelID, err := tunnelRes.LastInsertId()
-	if err != nil {
-		t.Fatalf("get tunnel id: %v", err)
-	}
+	tunnelID := mustLastInsertID(t, r, "diagnose-chain-tunnel")
 
 	insertNode := func(name, ip string) int64 {
-		res, err := repo.DB().Exec(`
+		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", ip, ip, "", "30000-30010", "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", 0)
-		if err != nil {
+		`, name, name+"-secret", ip, ip, "", "30000-30010", "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", 0).Error; err != nil {
 			t.Fatalf("insert node %s: %v", name, err)
 		}
-		id, err := res.LastInsertId()
-		if err != nil {
-			t.Fatalf("get node id %s: %v", name, err)
-		}
-		return id
+		return mustLastInsertID(t, r, name)
 	}
 
 	entryNodeID := insertNode("entry-node", "10.0.1.10")
 	chainNodeID := insertNode("chain-node", "10.0.1.20")
 	exitNodeID := insertNode("exit-node", "10.0.1.30")
 
-	if _, err := repo.DB().Exec(`
+	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); err != nil {
+	`, tunnelID, entryNodeID).Error; err != nil {
 		t.Fatalf("insert entry chain: %v", err)
 	}
-	if _, err := repo.DB().Exec(`
+	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); err != nil {
+	`, tunnelID, chainNodeID).Error; err != nil {
 		t.Fatalf("insert middle chain: %v", err)
 	}
-	if _, err := repo.DB().Exec(`
+	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); err != nil {
+	`, tunnelID, exitNodeID).Error; err != nil {
 		t.Fatalf("insert exit chain: %v", err)
 	}
 
-	forwardRes, err := repo.DB().Exec(`
+	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", "chain-forward", tunnelID, "8.8.8.8:53", "fifo", now, now, 0)
-	if err != nil {
+	`, 2, "normal_user", "chain-forward", tunnelID, "8.8.8.8:53", "fifo", now, now, 0).Error; err != nil {
 		t.Fatalf("insert forward: %v", err)
 	}
-	forwardID, err := forwardRes.LastInsertId()
-	if err != nil {
-		t.Fatalf("get forward id: %v", err)
-	}
+	forwardID := mustLastInsertID(t, r, "chain-forward")
 
 	userToken, err := auth.GenerateToken(2, "normal_user", 1, secret)
 	if err != nil {
@@ -205,6 +193,279 @@ 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)
+	now := time.Now().UnixMilli()
+
+	remoteToken := "remote-diagnose-token"
+	var remoteDiagnoseCalls int32
+	remoteServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/api/v1/federation/runtime/diagnose" {
+			http.NotFound(w, r)
+			return
+		}
+		if got := strings.TrimSpace(r.Header.Get("Authorization")); got != "Bearer "+remoteToken {
+			w.WriteHeader(http.StatusUnauthorized)
+			_ = json.NewEncoder(w).Encode(map[string]interface{}{"code": -1, "msg": "unauthorized"})
+			return
+		}
+
+		var req map[string]interface{}
+		if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+			w.WriteHeader(http.StatusBadRequest)
+			_ = json.NewEncoder(w).Encode(map[string]interface{}{"code": -1, "msg": "bad request"})
+			return
+		}
+		if strings.TrimSpace(valueAsString(req["ip"])) != "10.50.0.30" {
+			w.WriteHeader(http.StatusBadRequest)
+			_ = json.NewEncoder(w).Encode(map[string]interface{}{"code": -1, "msg": "unexpected target ip"})
+			return
+		}
+		if valueAsInt(req["port"]) != 30003 {
+			w.WriteHeader(http.StatusBadRequest)
+			_ = json.NewEncoder(w).Encode(map[string]interface{}{"code": -1, "msg": "unexpected target port"})
+			return
+		}
+
+		atomic.AddInt32(&remoteDiagnoseCalls, 1)
+		_ = json.NewEncoder(w).Encode(map[string]interface{}{
+			"code": 0,
+			"msg":  "success",
+			"data": map[string]interface{}{
+				"success":     true,
+				"averageTime": 12.5,
+				"packetLoss":  0,
+				"message":     "remote tcp ok",
+			},
+		})
+	}))
+	defer remoteServer.Close()
+
+	insertLocalNode := func(name, ip 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", ip, ip, "", "30000-30010", "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", 0).Error; err != nil {
+			t.Fatalf("insert local node %s: %v", name, err)
+		}
+		return mustLastInsertID(t, r, name)
+	}
+
+	insertRemoteNode := func(name, ip 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, is_remote, remote_url, remote_token, remote_config)
+			VALUES(?, ?, ?, ?, ?, ?, ?, ?, 0, 0, 0, ?, ?, 1, ?, ?, ?, 1, ?, ?, ?)
+		`, name, name+"-secret", ip, "", "", "31000-31010", "", "", now, now, "[::]", "[::]", 1, remoteServer.URL, remoteToken, `{"shareId": 123}`).Error; err != nil {
+			t.Fatalf("insert remote node %s: %v", name, err)
+		}
+		return mustLastInsertID(t, r, name)
+	}
+
+	entryNodeID := insertLocalNode("entry-local", "10.50.0.10")
+	remoteChainNodeID := insertRemoteNode("middle-remote", "10.50.0.20")
+	exitNodeID := insertLocalNode("exit-local", "10.50.0.30")
+
+	if err := r.DB().Exec(`
+		INSERT INTO tunnel(name, traffic_ratio, type, protocol, flow, created_time, updated_time, status, in_ip, inx)
+		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, "diagnose-remote-tunnel", 1.0, 2, "tls", 99999, now, now, 1, nil, 0).Error; err != nil {
+		t.Fatalf("insert tunnel: %v", err)
+	}
+	tunnelID := mustLastInsertID(t, r, "diagnose-remote-tunnel")
+
+	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, remoteChainNodeID).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)
+	}
+
+	adminToken, err := auth.GenerateToken(1, "admin_user", 0, secret)
+	if err != nil {
+		t.Fatalf("generate admin token: %v", err)
+	}
+
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/diagnose", bytes.NewBufferString(`{"tunnelId":`+strconv.FormatInt(tunnelID, 10)+`}`))
+	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 (%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"])
+	}
+
+	remoteStepFound := false
+	for _, raw := range results {
+		item, ok := raw.(map[string]interface{})
+		if !ok {
+			continue
+		}
+		if valueAsInt(item["fromChainType"]) == 2 && valueAsInt(item["toChainType"]) == 3 {
+			remoteStepFound = true
+			if !valueAsBool(item["success"]) {
+				t.Fatalf("expected remote chain->exit diagnosis success, got item=%v", item)
+			}
+			if strings.TrimSpace(valueAsString(item["message"])) != "remote tcp ok" {
+				t.Fatalf("expected remote diagnosis message, got %q", valueAsString(item["message"]))
+			}
+		}
+	}
+
+	if !remoteStepFound {
+		t.Fatalf("expected chain->exit diagnosis item for remote node")
+	}
+	if atomic.LoadInt32(&remoteDiagnoseCalls) == 0 {
+		t.Fatalf("expected federation runtime diagnose endpoint to be called")
+	}
+}
+
 func valueAsInt(v interface{}) int {
 	switch n := v.(type) {
 	case float64:
@@ -223,17 +484,35 @@ func valueAsString(v interface{}) string {
 	return s
 }
 
-func setupDiagnosisContractRouter(t *testing.T, jwtSecret string) (http.Handler, *sqlite.Repository) {
+func valueAsBool(v interface{}) bool {
+	switch b := v.(type) {
+	case bool:
+		return b
+	case float64:
+		return b != 0
+	case int:
+		return b != 0
+	case int64:
+		return b != 0
+	case string:
+		s := strings.TrimSpace(strings.ToLower(b))
+		return s == "1" || s == "t" || s == "true" || s == "yes" || s == "y"
+	default:
+		return false
+	}
+}
+
+func setupDiagnosisContractRouter(t *testing.T, jwtSecret string) (http.Handler, *repo.Repository) {
 	t.Helper()
 	dbPath := filepath.Join(t.TempDir(), "diagnosis-contract.db")
-	repo, err := sqlite.Open(dbPath)
+	r, err := repo.Open(dbPath)
 	if err != nil {
 		t.Fatalf("open sqlite: %v", err)
 	}
 	t.Cleanup(func() {
-		_ = repo.Close()
+		_ = r.Close()
 	})
 
-	h := handler.New(repo, jwtSecret)
-	return httpserver.NewRouter(h, jwtSecret), repo
+	h := handler.New(r, jwtSecret)
+	return httpserver.NewRouter(h, jwtSecret), r
 }

go-backend/tests/contract/federation_dual_panel_contract_test.go

@@ -0,0 +1,770 @@
+package contract_test
+
+import (
+	"bytes"
+	"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"
+	"go-backend/internal/store/repo"
+)
+
+func TestFederationDualPanelMiddleExitAutoPortContract(t *testing.T) {
+	providerSecret := "provider-contract-jwt"
+	providerRouter, providerRepo := setupContractRouter(t, providerSecret)
+	providerServer := httptest.NewServer(providerRouter)
+	defer providerServer.Close()
+
+	consumerSecret := "consumer-contract-jwt"
+	consumerRouter, consumerRepo := setupContractRouter(t, consumerSecret)
+
+	consumerAdminToken, err := auth.GenerateToken(1, "consumer-admin", 0, consumerSecret)
+	if err != nil {
+		t.Fatalf("generate consumer admin token: %v", err)
+	}
+
+	now := time.Now().UnixMilli()
+	providerEntryNodeID := insertContractNode(t, providerRepo, "provider-entry", "198.51.100.11", "43000-43010", "provider-entry-secret", 1)
+	providerMiddleNodeID := insertContractNode(t, providerRepo, "provider-middle", "198.51.100.12", "44000-44010", "provider-middle-secret", 1)
+	providerExitNodeID := insertContractNode(t, providerRepo, "provider-exit", "198.51.100.13", "45000-45010", "provider-exit-secret", 1)
+
+	entryShareID := insertPeerShare(t, providerRepo, &repo.PeerShare{
+		Name:           "entry-share",
+		NodeID:         providerEntryNodeID,
+		Token:          "share-entry-token",
+		PortRangeStart: 43000,
+		PortRangeEnd:   43010,
+		IsActive:       1,
+		CreatedTime:    now,
+		UpdatedTime:    now,
+	})
+	middleShareID := insertPeerShare(t, providerRepo, &repo.PeerShare{
+		Name:           "middle-share",
+		NodeID:         providerMiddleNodeID,
+		Token:          "share-middle-token",
+		PortRangeStart: 44000,
+		PortRangeEnd:   44010,
+		IsActive:       1,
+		CreatedTime:    now,
+		UpdatedTime:    now,
+	})
+	exitShareID := insertPeerShare(t, providerRepo, &repo.PeerShare{
+		Name:           "exit-share",
+		NodeID:         providerExitNodeID,
+		Token:          "share-exit-token",
+		PortRangeStart: 45000,
+		PortRangeEnd:   45010,
+		IsActive:       1,
+		CreatedTime:    now,
+		UpdatedTime:    now,
+	})
+
+	importRemoteNodeForContract(t, consumerRouter, consumerAdminToken, providerServer.URL, "share-entry-token")
+	importRemoteNodeForContract(t, consumerRouter, consumerAdminToken, providerServer.URL, "share-middle-token")
+	importRemoteNodeForContract(t, consumerRouter, consumerAdminToken, providerServer.URL, "share-exit-token")
+
+	entryRemoteNodeID := queryRemoteNodeIDByToken(t, consumerRepo, "share-entry-token")
+	middleRemoteNodeID := queryRemoteNodeIDByToken(t, consumerRepo, "share-middle-token")
+	exitRemoteNodeID := queryRemoteNodeIDByToken(t, consumerRepo, "share-exit-token")
+
+	stopEntry := startMockNodeSession(t, providerServer.URL, "provider-entry-secret")
+	defer stopEntry()
+	stopMiddle := startMockNodeSession(t, providerServer.URL, "provider-middle-secret")
+	defer stopMiddle()
+	stopExit := startMockNodeSession(t, providerServer.URL, "provider-exit-secret")
+	defer stopExit()
+
+	createTunnel := func(name string) int64 {
+		payload := map[string]interface{}{
+			"name":   name,
+			"type":   2,
+			"flow":   99999,
+			"status": 1,
+			"inNodeId": []map[string]interface{}{
+				{"nodeId": entryRemoteNodeID, "protocol": "tls", "strategy": "round"},
+			},
+			"chainNodes": [][]map[string]interface{}{
+				{{"nodeId": middleRemoteNodeID, "protocol": "tls", "strategy": "round"}},
+			},
+			"outNodeId": []map[string]interface{}{
+				{"nodeId": exitRemoteNodeID, "protocol": "tls", "strategy": "round"},
+			},
+		}
+		body, err := json.Marshal(payload)
+		if err != nil {
+			t.Fatalf("marshal create payload: %v", err)
+		}
+		req := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/create", bytes.NewReader(body))
+		req.Header.Set("Authorization", consumerAdminToken)
+		req.Header.Set("Content-Type", "application/json")
+		res := httptest.NewRecorder()
+		consumerRouter.ServeHTTP(res, req)
+		assertCode(t, res, 0)
+
+		tunnelID := mustQueryInt64(t, consumerRepo, `SELECT id FROM tunnel WHERE name = ? ORDER BY id DESC LIMIT 1`, name)
+		if tunnelID <= 0 {
+			t.Fatalf("invalid tunnel id for %s", name)
+		}
+		return tunnelID
+	}
+
+	firstTunnelID := createTunnel("dual-panel-middle-exit-1")
+
+	assertTunnelPortInRange(t, consumerRepo, firstTunnelID, 2, middleRemoteNodeID, 44000, 44010)
+	assertTunnelPortInRange(t, consumerRepo, firstTunnelID, 3, exitRemoteNodeID, 45000, 45010)
+
+	assertCount(t, consumerRepo, `SELECT COUNT(1) FROM federation_tunnel_binding WHERE tunnel_id = ? AND status = 1`, firstTunnelID, 2)
+	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)
+
+	deleteBody, err := json.Marshal(map[string]interface{}{"id": firstTunnelID})
+	if err != nil {
+		t.Fatalf("marshal delete payload: %v", err)
+	}
+	deleteReq := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/delete", bytes.NewReader(deleteBody))
+	deleteReq.Header.Set("Authorization", consumerAdminToken)
+	deleteReq.Header.Set("Content-Type", "application/json")
+	deleteRes := httptest.NewRecorder()
+	consumerRouter.ServeHTTP(deleteRes, deleteReq)
+	assertCode(t, deleteRes, 0)
+
+	assertCount(t, consumerRepo, `SELECT COUNT(1) FROM federation_tunnel_binding WHERE tunnel_id = ?`, firstTunnelID, 0)
+	assertCount(t, providerRepo, `SELECT COUNT(1) FROM peer_share_runtime WHERE share_id = ? AND status = 0`, middleShareID, 1)
+	assertCount(t, providerRepo, `SELECT COUNT(1) FROM peer_share_runtime WHERE share_id = ? AND status = 0`, exitShareID, 1)
+
+	secondTunnelID := createTunnel("dual-panel-middle-exit-2")
+	assertTunnelPortInRange(t, consumerRepo, secondTunnelID, 2, middleRemoteNodeID, 44000, 44010)
+	assertTunnelPortInRange(t, consumerRepo, secondTunnelID, 3, exitRemoteNodeID, 45000, 45010)
+
+	forwardPayload := map[string]interface{}{
+		"name":       "dual-panel-remote-entry-forward",
+		"tunnelId":   secondTunnelID,
+		"remoteAddr": "1.1.1.1:443",
+		"strategy":   "fifo",
+	}
+	forwardBody, err := json.Marshal(forwardPayload)
+	if err != nil {
+		t.Fatalf("marshal forward payload: %v", err)
+	}
+	forwardReq := httptest.NewRequest(http.MethodPost, "/api/v1/forward/create", bytes.NewReader(forwardBody))
+	forwardReq.Header.Set("Authorization", consumerAdminToken)
+	forwardReq.Header.Set("Content-Type", "application/json")
+	forwardRes := httptest.NewRecorder()
+	consumerRouter.ServeHTTP(forwardRes, forwardReq)
+	assertCode(t, forwardRes, 0)
+
+	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 = ? AND status = 1 AND applied = 1`, entryShareID, 1)
+}
+
+func TestFederationDualPanelRemoteDiagnosisContract(t *testing.T) {
+	providerSecret := "provider-contract-jwt"
+	providerRouter, providerRepo := setupContractRouter(t, providerSecret)
+	providerServer := httptest.NewServer(providerRouter)
+	defer providerServer.Close()
+
+	consumerSecret := "consumer-contract-jwt"
+	consumerRouter, consumerRepo := setupContractRouter(t, consumerSecret)
+
+	consumerAdminToken, err := auth.GenerateToken(1, "consumer-admin", 0, consumerSecret)
+	if err != nil {
+		t.Fatalf("generate consumer admin token: %v", err)
+	}
+
+	now := time.Now().UnixMilli()
+	providerEntryNodeID := insertContractNode(t, providerRepo, "provider-entry-dx", "203.0.113.11", "53000-53010", "provider-entry-dx-secret", 1)
+	providerMiddleNodeID := insertContractNode(t, providerRepo, "provider-middle-dx", "203.0.113.12", "54000-54010", "provider-middle-dx-secret", 1)
+	providerExitNodeID := insertContractNode(t, providerRepo, "provider-exit-dx", "203.0.113.13", "55000-55010", "provider-exit-dx-secret", 1)
+
+	entryShareID := insertPeerShare(t, providerRepo, &repo.PeerShare{
+		Name:           "entry-share-dx",
+		NodeID:         providerEntryNodeID,
+		Token:          "share-entry-dx-token",
+		PortRangeStart: 53000,
+		PortRangeEnd:   53010,
+		IsActive:       1,
+		CreatedTime:    now,
+		UpdatedTime:    now,
+	})
+	middleShareID := insertPeerShare(t, providerRepo, &repo.PeerShare{
+		Name:           "middle-share-dx",
+		NodeID:         providerMiddleNodeID,
+		Token:          "share-middle-dx-token",
+		PortRangeStart: 54000,
+		PortRangeEnd:   54010,
+		IsActive:       1,
+		CreatedTime:    now,
+		UpdatedTime:    now,
+	})
+	exitShareID := insertPeerShare(t, providerRepo, &repo.PeerShare{
+		Name:           "exit-share-dx",
+		NodeID:         providerExitNodeID,
+		Token:          "share-exit-dx-token",
+		PortRangeStart: 55000,
+		PortRangeEnd:   55010,
+		IsActive:       1,
+		CreatedTime:    now,
+		UpdatedTime:    now,
+	})
+
+	importRemoteNodeForContract(t, consumerRouter, consumerAdminToken, providerServer.URL, "share-entry-dx-token")
+	importRemoteNodeForContract(t, consumerRouter, consumerAdminToken, providerServer.URL, "share-middle-dx-token")
+	importRemoteNodeForContract(t, consumerRouter, consumerAdminToken, providerServer.URL, "share-exit-dx-token")
+
+	entryRemoteNodeID := queryRemoteNodeIDByToken(t, consumerRepo, "share-entry-dx-token")
+	middleRemoteNodeID := queryRemoteNodeIDByToken(t, consumerRepo, "share-middle-dx-token")
+	exitRemoteNodeID := queryRemoteNodeIDByToken(t, consumerRepo, "share-exit-dx-token")
+
+	stopMiddle := startMockNodeSession(t, providerServer.URL, "provider-middle-dx-secret")
+	defer stopMiddle()
+	stopExit := startMockNodeSession(t, providerServer.URL, "provider-exit-dx-secret")
+	defer stopExit()
+
+	createPayload := map[string]interface{}{
+		"name":   "dual-panel-diagnose-remote",
+		"type":   2,
+		"flow":   99999,
+		"status": 1,
+		"inNodeId": []map[string]interface{}{
+			{"nodeId": entryRemoteNodeID, "protocol": "tls", "strategy": "round"},
+		},
+		"chainNodes": [][]map[string]interface{}{
+			{{"nodeId": middleRemoteNodeID, "protocol": "tls", "strategy": "round"}},
+		},
+		"outNodeId": []map[string]interface{}{
+			{"nodeId": exitRemoteNodeID, "protocol": "tls", "strategy": "round"},
+		},
+	}
+	body, err := json.Marshal(createPayload)
+	if err != nil {
+		t.Fatalf("marshal create payload: %v", err)
+	}
+	createReq := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/create", bytes.NewReader(body))
+	createReq.Header.Set("Authorization", consumerAdminToken)
+	createReq.Header.Set("Content-Type", "application/json")
+	createRes := httptest.NewRecorder()
+	consumerRouter.ServeHTTP(createRes, createReq)
+	assertCode(t, createRes, 0)
+
+	tunnelID := mustQueryInt64(t, consumerRepo, `SELECT id FROM tunnel WHERE name = ? ORDER BY id DESC LIMIT 1`, "dual-panel-diagnose-remote")
+	if tunnelID <= 0 {
+		t.Fatalf("invalid tunnel id")
+	}
+
+	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)
+
+	diagnoseReq := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/diagnose", bytes.NewBufferString(fmt.Sprintf(`{"tunnelId":%d}`, tunnelID)))
+	diagnoseReq.Header.Set("Authorization", consumerAdminToken)
+	diagnoseRes := httptest.NewRecorder()
+	consumerRouter.ServeHTTP(diagnoseRes, diagnoseReq)
+
+	var out response.R
+	if err := json.NewDecoder(diagnoseRes.Body).Decode(&out); err != nil {
+		t.Fatalf("decode diagnose response: %v", err)
+	}
+	if out.Code != 0 {
+		t.Fatalf("expected diagnose code 0, got %d (%s)", out.Code, out.Msg)
+	}
+
+	payload, ok := out.Data.(map[string]interface{})
+	if !ok {
+		t.Fatalf("expected map 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"])
+	}
+
+	chainToExitFound := false
+	for _, raw := range results {
+		item, ok := raw.(map[string]interface{})
+		if !ok {
+			continue
+		}
+		if valueAsInt(item["fromChainType"]) == 2 && valueAsInt(item["toChainType"]) == 3 {
+			chainToExitFound = true
+			if !valueAsBool(item["success"]) {
+				t.Fatalf("expected chain->exit diagnosis success, got item=%v", item)
+			}
+			if msg := strings.TrimSpace(valueAsString(item["message"])); msg != "mock tcp ok" {
+				t.Fatalf("expected remote diagnosis message 'mock tcp ok', got %q", msg)
+			}
+		}
+	}
+	if !chainToExitFound {
+		t.Fatalf("expected chain->exit diagnosis item in results")
+	}
+}
+
+func TestFederationDualPanelRemoteEntryRuntimeContract(t *testing.T) {
+	providerSecret := "provider-contract-jwt"
+	providerRouter, providerRepo := setupContractRouter(t, providerSecret)
+	providerServer := httptest.NewServer(providerRouter)
+	defer providerServer.Close()
+
+	consumerSecret := "consumer-contract-jwt"
+	consumerRouter, consumerRepo := setupContractRouter(t, consumerSecret)
+
+	consumerAdminToken, err := auth.GenerateToken(1, "consumer-admin", 0, consumerSecret)
+	if err != nil {
+		t.Fatalf("generate consumer admin token: %v", err)
+	}
+
+	now := time.Now().UnixMilli()
+	providerEntryNodeID := insertContractNode(t, providerRepo, "provider-entry-rt", "198.51.100.21", "43020-43030", "provider-entry-rt-secret", 1)
+	providerMiddleNodeID := insertContractNode(t, providerRepo, "provider-middle-rt", "198.51.100.22", "44020-44030", "provider-middle-rt-secret", 1)
+	providerExitNodeID := insertContractNode(t, providerRepo, "provider-exit-rt", "198.51.100.23", "45020-45030", "provider-exit-rt-secret", 1)
+
+	insertPeerShare(t, providerRepo, &repo.PeerShare{
+		Name:           "entry-share-rt",
+		NodeID:         providerEntryNodeID,
+		Token:          "share-entry-rt-token",
+		PortRangeStart: 43020,
+		PortRangeEnd:   43030,
+		IsActive:       1,
+		CreatedTime:    now,
+		UpdatedTime:    now,
+	})
+	insertPeerShare(t, providerRepo, &repo.PeerShare{
+		Name:           "middle-share-rt",
+		NodeID:         providerMiddleNodeID,
+		Token:          "share-middle-rt-token",
+		PortRangeStart: 44020,
+		PortRangeEnd:   44030,
+		IsActive:       1,
+		CreatedTime:    now,
+		UpdatedTime:    now,
+	})
+	insertPeerShare(t, providerRepo, &repo.PeerShare{
+		Name:           "exit-share-rt",
+		NodeID:         providerExitNodeID,
+		Token:          "share-exit-rt-token",
+		PortRangeStart: 45020,
+		PortRangeEnd:   45030,
+		IsActive:       1,
+		CreatedTime:    now,
+		UpdatedTime:    now,
+	})
+
+	importRemoteNodeForContract(t, consumerRouter, consumerAdminToken, providerServer.URL, "share-entry-rt-token")
+	importRemoteNodeForContract(t, consumerRouter, consumerAdminToken, providerServer.URL, "share-middle-rt-token")
+	importRemoteNodeForContract(t, consumerRouter, consumerAdminToken, providerServer.URL, "share-exit-rt-token")
+
+	entryRemoteNodeID := queryRemoteNodeIDByToken(t, consumerRepo, "share-entry-rt-token")
+	middleRemoteNodeID := queryRemoteNodeIDByToken(t, consumerRepo, "share-middle-rt-token")
+	exitRemoteNodeID := queryRemoteNodeIDByToken(t, consumerRepo, "share-exit-rt-token")
+
+	var commandMu sync.Mutex
+	entryCommands := make([]string, 0, 8)
+	stopEntry := startMockNodeSessionWithHook(t, providerServer.URL, "provider-entry-rt-secret", func(cmdType string) {
+		commandMu.Lock()
+		entryCommands = append(entryCommands, cmdType)
+		commandMu.Unlock()
+	})
+	defer stopEntry()
+	stopMiddle := startMockNodeSession(t, providerServer.URL, "provider-middle-rt-secret")
+	defer stopMiddle()
+	stopExit := startMockNodeSession(t, providerServer.URL, "provider-exit-rt-secret")
+	defer stopExit()
+
+	createTunnel := func(name string) int64 {
+		payload := map[string]interface{}{
+			"name":   name,
+			"type":   2,
+			"flow":   99999,
+			"status": 1,
+			"inNodeId": []map[string]interface{}{
+				{"nodeId": entryRemoteNodeID, "protocol": "tls", "strategy": "round"},
+			},
+			"chainNodes": [][]map[string]interface{}{
+				{{"nodeId": middleRemoteNodeID, "protocol": "tls", "strategy": "round"}},
+			},
+			"outNodeId": []map[string]interface{}{
+				{"nodeId": exitRemoteNodeID, "protocol": "tls", "strategy": "round"},
+			},
+		}
+		body, err := json.Marshal(payload)
+		if err != nil {
+			t.Fatalf("marshal create payload: %v", err)
+		}
+		req := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/create", bytes.NewReader(body))
+		req.Header.Set("Authorization", consumerAdminToken)
+		req.Header.Set("Content-Type", "application/json")
+		res := httptest.NewRecorder()
+		consumerRouter.ServeHTTP(res, req)
+		assertCode(t, res, 0)
+
+		tunnelID := mustQueryInt64(t, consumerRepo, `SELECT id FROM tunnel WHERE name = ? ORDER BY id DESC LIMIT 1`, name)
+		if tunnelID <= 0 {
+			t.Fatalf("invalid tunnel id for %s", name)
+		}
+		return tunnelID
+	}
+
+	createTunnel("dual-panel-remote-entry-online")
+
+	commandMu.Lock()
+	seenAddChains := false
+	seenCommands := append([]string(nil), entryCommands...)
+	for _, cmdType := range entryCommands {
+		if strings.EqualFold(strings.TrimSpace(cmdType), "AddChains") {
+			seenAddChains = true
+			break
+		}
+	}
+	commandMu.Unlock()
+	if !seenAddChains {
+		t.Fatalf("expected entry remote node to receive AddChains, commands=%v", seenCommands)
+	}
+
+	stopEntry()
+	waitNodeStatus(t, providerRepo, providerEntryNodeID, 0)
+
+	createTunnel("dual-panel-remote-entry-offline")
+}
+
+func insertContractNode(t *testing.T, r *repo.Repository, name, ip, portRange, secret string, status int) int64 {
+	t.Helper()
+	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)
+		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, name, secret, ip, ip, "", portRange, "", "v1", 1, 1, 1, now, now, status, "[::]", "[::]", 0).Error; err != nil {
+		t.Fatalf("insert node %s: %v", name, err)
+	}
+	return mustLastInsertID(t, r, name)
+}
+
+func insertPeerShare(t *testing.T, r *repo.Repository, share *repo.PeerShare) int64 {
+	t.Helper()
+	if share == nil {
+		t.Fatalf("share is nil")
+	}
+	if err := r.CreatePeerShare(share); err != nil {
+		t.Fatalf("create peer share %s: %v", share.Name, err)
+	}
+	saved, err := r.GetPeerShareByToken(share.Token)
+	if err != nil {
+		t.Fatalf("query peer share %s: %v", share.Name, err)
+	}
+	if saved == nil {
+		t.Fatalf("peer share %s not found after create", share.Name)
+	}
+	return saved.ID
+}
+
+func importRemoteNodeForContract(t *testing.T, router http.Handler, adminToken, remoteURL, token string) {
+	t.Helper()
+	body, err := json.Marshal(map[string]string{
+		"remoteUrl": remoteURL,
+		"token":     token,
+	})
+	if err != nil {
+		t.Fatalf("marshal import payload: %v", err)
+	}
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/federation/node/import", bytes.NewReader(body))
+	req.Header.Set("Authorization", adminToken)
+	req.Header.Set("Content-Type", "application/json")
+	res := httptest.NewRecorder()
+	router.ServeHTTP(res, req)
+	assertCode(t, res, 0)
+}
+
+func queryRemoteNodeIDByToken(t *testing.T, r *repo.Repository, token string) int64 {
+	t.Helper()
+	id := mustQueryInt64(t, r, `SELECT id FROM node WHERE is_remote = 1 AND remote_token = ? ORDER BY id DESC LIMIT 1`, token)
+	if id <= 0 {
+		t.Fatalf("invalid remote node id for token %s", token)
+	}
+	return id
+}
+
+func assertTunnelPortInRange(t *testing.T, r *repo.Repository, tunnelID int64, chainType int, nodeID int64, minPort int, maxPort int) {
+	t.Helper()
+	port := mustQueryInt(t, r, `SELECT port FROM chain_tunnel WHERE tunnel_id = ? AND chain_type = ? AND node_id = ? LIMIT 1`, tunnelID, chainType, nodeID)
+	if port < minPort || port > maxPort {
+		t.Fatalf("expected port in range [%d,%d], got %d", minPort, maxPort, port)
+	}
+}
+
+func assertCount(t *testing.T, r *repo.Repository, query string, arg interface{}, expected int) {
+	t.Helper()
+	got := mustQueryInt(t, r, query, arg)
+	if got != expected {
+		t.Fatalf("expected count %d, got %d (query: %s, arg: %v)", expected, got, query, arg)
+	}
+}
+
+func startMockNodeSession(t *testing.T, baseURL string, nodeSecret string) func() {
+	return startMockNodeSessionWithHook(t, baseURL, nodeSecret, nil)
+}
+
+func startMockNodeSessionWithHook(t *testing.T, baseURL string, nodeSecret string, onCommand func(cmdType 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
+			}
+			if onCommand != nil {
+				onCommand(strings.TrimSpace(cmd.Type))
+			}
+
+			respType := fmt.Sprintf("%sResponse", cmd.Type)
+			respPayload := map[string]interface{}{
+				"type":      respType,
+				"success":   true,
+				"message":   "OK",
+				"requestId": cmd.RequestID,
+			}
+			if strings.EqualFold(strings.TrimSpace(cmd.Type), "TcpPing") {
+				respPayload["data"] = map[string]interface{}{
+					"success":     true,
+					"averageTime": 8.5,
+					"packetLoss":  0,
+					"message":     "mock tcp ok",
+				}
+			}
+			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()
+		})
+	}
+}
+
+func waitNodeStatus(t *testing.T, r *repo.Repository, nodeID int64, expectedStatus int) {
+	t.Helper()
+	deadline := time.Now().Add(2 * time.Second)
+	for {
+		status, err := tryQueryInt(t, r, `SELECT status FROM node WHERE id = ?`, nodeID)
+		if err == nil && status == expectedStatus {
+			return
+		}
+		if time.Now().After(deadline) {
+			t.Fatalf("node %d status did not reach %d before timeout", nodeID, expectedStatus)
+		}
+		time.Sleep(20 * time.Millisecond)
+	}
+}
+
+func valueAsInt(v interface{}) int {
+	switch n := v.(type) {
+	case float64:
+		return int(n)
+	case int:
+		return n
+	case int64:
+		return int(n)
+	default:
+		return 0
+	}
+}
+
+func valueAsString(v interface{}) string {
+	s, _ := v.(string)
+	return s
+}
+
+func valueAsBool(v interface{}) bool {
+	switch b := v.(type) {
+	case bool:
+		return b
+	case float64:
+		return b != 0
+	case int:
+		return b != 0
+	case int64:
+		return b != 0
+	case string:
+		s := strings.TrimSpace(strings.ToLower(b))
+		return s == "1" || s == "t" || s == "true" || s == "yes" || s == "y"
+	default:
+		return false
+	}
+}
+
+func TestFederationRuntimeCommandPortRangeEnforcement(t *testing.T) {
+	providerSecret := "provider-portrange-jwt"
+	providerRouter, providerRepo := setupContractRouter(t, providerSecret)
+	providerServer := httptest.NewServer(providerRouter)
+	defer providerServer.Close()
+
+	now := time.Now().UnixMilli()
+	providerNodeID := insertContractNode(t, providerRepo, "provider-portrange-node", "198.51.100.50", "44000-44010", "provider-portrange-secret", 1)
+
+	insertPeerShare(t, providerRepo, &repo.PeerShare{
+		Name:           "portrange-share",
+		NodeID:         providerNodeID,
+		Token:          "share-portrange-token",
+		PortRangeStart: 44000,
+		PortRangeEnd:   44010,
+		IsActive:       1,
+		CreatedTime:    now,
+		UpdatedTime:    now,
+	})
+
+	stopNode := startMockNodeSession(t, providerServer.URL, "provider-portrange-secret")
+	defer stopNode()
+
+	sendCommand := func(token string, cmdType string, data interface{}) *httptest.ResponseRecorder {
+		payload := map[string]interface{}{
+			"commandType": cmdType,
+			"data":        data,
+		}
+		body, err := json.Marshal(payload)
+		if err != nil {
+			t.Fatalf("marshal command payload: %v", err)
+		}
+		req := httptest.NewRequest(http.MethodPost, "/api/v1/federation/runtime/command", bytes.NewReader(body))
+		req.Header.Set("Authorization", "Bearer "+token)
+		req.Header.Set("Content-Type", "application/json")
+		res := httptest.NewRecorder()
+		providerRouter.ServeHTTP(res, req)
+		return res
+	}
+
+	// Test: AddService with port OUTSIDE allowed range should be rejected
+	outOfRangeData := map[string]interface{}{
+		"services": []map[string]interface{}{
+			{
+				"name": "test_service_tcp",
+				"addr": "[::]:55555",
+				"handler": map[string]interface{}{
+					"type": "tcp",
+				},
+				"listener": map[string]interface{}{
+					"type": "tcp",
+				},
+			},
+		},
+	}
+	res := sendCommand("share-portrange-token", "AddService", outOfRangeData)
+	var out response.R
+	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
+		t.Fatalf("decode response: %v", err)
+	}
+	if out.Code != 403 {
+		t.Fatalf("expected code 403 for out-of-range port, got %d (msg: %s)", out.Code, out.Msg)
+	}
+
+	// Test: UpdateService with port OUTSIDE allowed range should be rejected
+	res = sendCommand("share-portrange-token", "UpdateService", outOfRangeData)
+	out = response.R{}
+	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
+		t.Fatalf("decode response: %v", err)
+	}
+	if out.Code != 403 {
+		t.Fatalf("expected code 403 for out-of-range UpdateService, got %d (msg: %s)", out.Code, out.Msg)
+	}
+
+	// Test: AddService with port INSIDE allowed range should succeed
+	inRangeData := map[string]interface{}{
+		"services": []map[string]interface{}{
+			{
+				"name": "test_service_ok_tcp",
+				"addr": "[::]:44005",
+				"handler": map[string]interface{}{
+					"type": "tcp",
+				},
+				"listener": map[string]interface{}{
+					"type": "tcp",
+				},
+			},
+		},
+	}
+	res = sendCommand("share-portrange-token", "AddService", inRangeData)
+	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 for in-range port, got %d (msg: %s)", out.Code, out.Msg)
+	}
+
+	// Test: Non-service commands should pass through without port validation
+	res = sendCommand("share-portrange-token", "reload", nil)
+	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 for reload command, got %d (msg: %s)", out.Code, out.Msg)
+	}
+}

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

@@ -18,67 +18,51 @@ func TestForwardOwnershipAndScopeContracts(t *testing.T) {
 	router, repo := setupContractRouter(t, secret)
 	now := time.Now().UnixMilli()
 
-	if _, err := repo.DB().Exec(`
+	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, 'normal_user', '3c85cdebade1c51cf64ca9f3c09d182d', 1, 2727251700000, 99999, 0, 0, 1, 99999, ?, ?, 1)
-	`, now, now); err != nil {
+	`, now, now).Error; err != nil {
 		t.Fatalf("insert user: %v", err)
 	}
 
-	res, err := repo.DB().Exec(`
+	if err := repo.DB().Exec(`
 		INSERT INTO tunnel(name, traffic_ratio, type, protocol, flow, created_time, updated_time, status, in_ip, inx)
 		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-	`, "contract-tunnel", 1.0, 1, "tls", 99999, now, now, 1, nil, 0)
-	if err != nil {
+	`, "contract-tunnel", 1.0, 1, "tls", 99999, now, now, 1, nil, 0).Error; err != nil {
 		t.Fatalf("insert tunnel: %v", err)
 	}
-	tunnelID, err := res.LastInsertId()
-	if err != nil {
-		t.Fatalf("get tunnel id: %v", err)
-	}
+	tunnelID := mustLastInsertID(t, repo, "contract-tunnel")
 
-	nodeRes, err := repo.DB().Exec(`
+	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(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-	`, "entry-node", "entry-secret", "10.0.0.10", "10.0.0.10", "", "20000-20010", "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", 0)
-	if err != nil {
+	`, "entry-node", "entry-secret", "10.0.0.10", "10.0.0.10", "", "20000-20010", "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", 0).Error; err != nil {
 		t.Fatalf("insert node: %v", err)
 	}
-	entryNodeID, err := nodeRes.LastInsertId()
-	if err != nil {
-		t.Fatalf("get node id: %v", err)
-	}
+	entryNodeID := mustLastInsertID(t, repo, "entry-node")
 
-	if _, err := repo.DB().Exec(`
+	if err := repo.DB().Exec(`
 		INSERT INTO chain_tunnel(tunnel_id, chain_type, node_id, port, strategy, inx, protocol)
 		VALUES(?, 1, ?, 20001, 'round', 1, 'tls')
-	`, tunnelID, entryNodeID); err != nil {
+	`, tunnelID, entryNodeID).Error; err != nil {
 		t.Fatalf("insert chain_tunnel: %v", err)
 	}
 
-	resAdmin, err := repo.DB().Exec(`
+	if err := repo.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, ?)
-	`, 1, "admin_user", "admin-forward", tunnelID, "1.1.1.1:443", "fifo", now, now, 0)
-	if err != nil {
+	`, 1, "admin_user", "admin-forward", tunnelID, "1.1.1.1:443", "fifo", now, now, 0).Error; err != nil {
 		t.Fatalf("insert admin forward: %v", err)
 	}
-	adminForwardID, err := resAdmin.LastInsertId()
-	if err != nil {
-		t.Fatalf("get admin forward id: %v", err)
-	}
+	adminForwardID := mustLastInsertID(t, repo, "admin-forward")
 
-	resUser, err := repo.DB().Exec(`
+	if err := repo.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", "user-forward", tunnelID, "8.8.8.8:53", "fifo", now, now, 1)
-	if err != nil {
+	`, 2, "normal_user", "user-forward", tunnelID, "8.8.8.8:53", "fifo", now, now, 1).Error; err != nil {
 		t.Fatalf("insert user forward: %v", err)
 	}
-	userForwardID, err := resUser.LastInsertId()
-	if err != nil {
-		t.Fatalf("get user forward id: %v", err)
-	}
+	userForwardID := mustLastInsertID(t, repo, "user-forward")
 
 	userToken, err := auth.GenerateToken(2, "normal_user", 1, secret)
 	if err != nil {
@@ -207,41 +191,31 @@ func TestForwardSwitchTunnelRollbackOnSyncFailure(t *testing.T) {
 		t.Fatalf("generate admin token: %v", err)
 	}
 
-	if _, err := repo.DB().Exec(`
+	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, 'switch_user', '3c85cdebade1c51cf64ca9f3c09d182d', 1, 2727251700000, 99999, 0, 0, 1, 99999, ?, ?, 1)
-	`, now, now); err != nil {
+	`, now, now).Error; err != nil {
 		t.Fatalf("insert user: %v", err)
 	}
 
 	insertTunnel := func(name string, inx int) int64 {
-		res, err := repo.DB().Exec(`
+		if err := repo.DB().Exec(`
 			INSERT INTO tunnel(name, traffic_ratio, type, protocol, flow, created_time, updated_time, status, in_ip, inx)
 			VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-		`, name, 1.0, 1, "tls", 99999, now, now, 1, nil, inx)
-		if err != nil {
+		`, name, 1.0, 1, "tls", 99999, now, now, 1, nil, inx).Error; err != nil {
 			t.Fatalf("insert tunnel %s: %v", name, err)
 		}
-		id, err := res.LastInsertId()
-		if err != nil {
-			t.Fatalf("get tunnel id %s: %v", name, err)
-		}
-		return id
+		return mustLastInsertID(t, repo, name)
 	}
 
 	insertNode := func(name, ip, portRange string, inx int) int64 {
-		res, err := repo.DB().Exec(`
+		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(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-		`, name, name+"-secret", ip, ip, "", portRange, "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", inx)
-		if err != nil {
+		`, name, name+"-secret", ip, ip, "", portRange, "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", inx).Error; err != nil {
 			t.Fatalf("insert node %s: %v", name, err)
 		}
-		id, err := res.LastInsertId()
-		if err != nil {
-			t.Fatalf("get node id %s: %v", name, err)
-		}
-		return id
+		return mustLastInsertID(t, repo, name)
 	}
 
 	tunnelA := insertTunnel("switch-tunnel-a", 0)
@@ -249,45 +223,41 @@ func TestForwardSwitchTunnelRollbackOnSyncFailure(t *testing.T) {
 	nodeA := insertNode("switch-node-a", "10.10.0.1", "21000-21010", 0)
 	nodeB := insertNode("switch-node-b", "10.10.0.2", "22000-22010", 1)
 
-	if _, err := repo.DB().Exec(`
+	if err := repo.DB().Exec(`
 		INSERT INTO chain_tunnel(tunnel_id, chain_type, node_id, port, strategy, inx, protocol)
 		VALUES(?, 1, ?, 21001, 'round', 1, 'tls')
-	`, tunnelA, nodeA); err != nil {
+	`, tunnelA, nodeA).Error; err != nil {
 		t.Fatalf("insert chain_tunnel tunnelA: %v", err)
 	}
-	if _, err := repo.DB().Exec(`
+	if err := repo.DB().Exec(`
 		INSERT INTO chain_tunnel(tunnel_id, chain_type, node_id, port, strategy, inx, protocol)
 		VALUES(?, 1, ?, 22001, 'round', 1, 'tls')
-	`, tunnelB, nodeB); err != nil {
+	`, tunnelB, nodeB).Error; err != nil {
 		t.Fatalf("insert chain_tunnel tunnelB: %v", err)
 	}
 
-	if _, err := repo.DB().Exec(`
+	if err := repo.DB().Exec(`
 		INSERT INTO user_tunnel(id, user_id, tunnel_id, speed_id, num, flow, in_flow, out_flow, flow_reset_time, exp_time, status)
 		VALUES(10, 2, ?, NULL, 999, 99999, 0, 0, 1, 2727251700000, 1)
-	`, tunnelA); err != nil {
+	`, tunnelA).Error; err != nil {
 		t.Fatalf("insert user_tunnel A: %v", err)
 	}
-	if _, err := repo.DB().Exec(`
+	if err := repo.DB().Exec(`
 		INSERT INTO user_tunnel(id, user_id, tunnel_id, speed_id, num, flow, in_flow, out_flow, flow_reset_time, exp_time, status)
 		VALUES(11, 2, ?, NULL, 999, 99999, 0, 0, 1, 2727251700000, 1)
-	`, tunnelB); err != nil {
+	`, tunnelB).Error; err != nil {
 		t.Fatalf("insert user_tunnel B: %v", err)
 	}
 
-	forwardRes, err := repo.DB().Exec(`
+	if err := repo.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, 'switch_user', 'switch-forward', ?, '8.8.8.8:53', 'fifo', 0, 0, ?, ?, 1, 0)
-	`, tunnelA, now, now)
-	if err != nil {
+	`, tunnelA, now, now).Error; err != nil {
 		t.Fatalf("insert forward: %v", err)
 	}
-	forwardID, err := forwardRes.LastInsertId()
-	if err != nil {
-		t.Fatalf("get forward id: %v", err)
-	}
+	forwardID := mustLastInsertID(t, repo, "switch-forward")
 
-	if _, err := repo.DB().Exec(`INSERT INTO forward_port(forward_id, node_id, port) VALUES(?, ?, ?)`, forwardID, nodeA, 21001); err != nil {
+	if err := repo.DB().Exec(`INSERT INTO forward_port(forward_id, node_id, port) VALUES(?, ?, ?)`, forwardID, nodeA, 21001).Error; err != nil {
 		t.Fatalf("insert forward_port: %v", err)
 	}
 
@@ -307,19 +277,12 @@ func TestForwardSwitchTunnelRollbackOnSyncFailure(t *testing.T) {
 		t.Fatalf("expected update failure when node is offline")
 	}
 
-	var tunnelAfter int64
-	if err := repo.DB().QueryRow(`SELECT tunnel_id FROM forward WHERE id = ?`, forwardID).Scan(&tunnelAfter); err != nil {
-		t.Fatalf("query forward tunnel_id: %v", err)
-	}
+	tunnelAfter := mustQueryInt64(t, repo, `SELECT tunnel_id FROM forward WHERE id = ?`, forwardID)
 	if tunnelAfter != tunnelA {
 		t.Fatalf("expected tunnel rollback to %d, got %d", tunnelA, tunnelAfter)
 	}
 
-	var nodeAfter int64
-	var portAfter int
-	if err := repo.DB().QueryRow(`SELECT node_id, port FROM forward_port WHERE forward_id = ? LIMIT 1`, forwardID).Scan(&nodeAfter, &portAfter); err != nil {
-		t.Fatalf("query forward_port: %v", err)
-	}
+	nodeAfter, portAfter := mustQueryInt64Int(t, repo, `SELECT node_id, port FROM forward_port WHERE forward_id = ? LIMIT 1`, forwardID)
 	if nodeAfter != nodeA || portAfter != 21001 {
 		t.Fatalf("expected forward_port rollback to node=%d port=21001, got node=%d port=%d", nodeA, nodeAfter, portAfter)
 	}
@@ -335,73 +298,68 @@ func TestForwardBatchChangeTunnelRollbackOnSyncFailure(t *testing.T) {
 		t.Fatalf("generate admin token: %v", err)
 	}
 
-	if _, err := repo.DB().Exec(`
+	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, 'batch_switch_user', '3c85cdebade1c51cf64ca9f3c09d182d', 1, 2727251700000, 99999, 0, 0, 1, 99999, ?, ?, 1)
-	`, now, now); err != nil {
+	`, now, now).Error; err != nil {
 		t.Fatalf("insert user: %v", err)
 	}
 
-	tunnelResA, err := repo.DB().Exec(`
+	if err := repo.DB().Exec(`
 		INSERT INTO tunnel(name, traffic_ratio, type, protocol, flow, created_time, updated_time, status, in_ip, inx)
 		VALUES('batch-switch-tunnel-a', 1.0, 1, 'tls', 99999, ?, ?, 1, NULL, 0)
-	`, now, now)
-	if err != nil {
+	`, now, now).Error; err != nil {
 		t.Fatalf("insert tunnel A: %v", err)
 	}
-	tunnelA, _ := tunnelResA.LastInsertId()
+	tunnelA := mustLastInsertID(t, repo, "batch-switch-tunnel-a")
 
-	tunnelResB, err := repo.DB().Exec(`
+	if err := repo.DB().Exec(`
 		INSERT INTO tunnel(name, traffic_ratio, type, protocol, flow, created_time, updated_time, status, in_ip, inx)
 		VALUES('batch-switch-tunnel-b', 1.0, 1, 'tls', 99999, ?, ?, 1, NULL, 1)
-	`, now, now)
-	if err != nil {
+	`, now, now).Error; err != nil {
 		t.Fatalf("insert tunnel B: %v", err)
 	}
-	tunnelB, _ := tunnelResB.LastInsertId()
+	tunnelB := mustLastInsertID(t, repo, "batch-switch-tunnel-b")
 
-	nodeResA, err := repo.DB().Exec(`
+	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('batch-switch-node-a', 'batch-switch-node-a-secret', '10.11.0.1', '10.11.0.1', '', '23000-23010', '', 'v1', 1, 1, 1, ?, ?, 1, '[::]', '[::]', 0)
-	`, now, now)
-	if err != nil {
+	`, now, now).Error; err != nil {
 		t.Fatalf("insert node A: %v", err)
 	}
-	nodeA, _ := nodeResA.LastInsertId()
+	nodeA := mustLastInsertID(t, repo, "batch-switch-node-a")
 
-	nodeResB, err := repo.DB().Exec(`
+	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('batch-switch-node-b', 'batch-switch-node-b-secret', '10.11.0.2', '10.11.0.2', '', '24000-24010', '', 'v1', 1, 1, 1, ?, ?, 1, '[::]', '[::]', 1)
-	`, now, now)
-	if err != nil {
+	`, now, now).Error; err != nil {
 		t.Fatalf("insert node B: %v", err)
 	}
-	nodeB, _ := nodeResB.LastInsertId()
+	nodeB := mustLastInsertID(t, repo, "batch-switch-node-b")
 
-	if _, err := repo.DB().Exec(`INSERT INTO chain_tunnel(tunnel_id, chain_type, node_id, port, strategy, inx, protocol) VALUES(?, 1, ?, 23001, 'round', 1, 'tls')`, tunnelA, nodeA); err != nil {
+	if err := repo.DB().Exec(`INSERT INTO chain_tunnel(tunnel_id, chain_type, node_id, port, strategy, inx, protocol) VALUES(?, 1, ?, 23001, 'round', 1, 'tls')`, tunnelA, nodeA).Error; err != nil {
 		t.Fatalf("insert chain_tunnel A: %v", err)
 	}
-	if _, err := repo.DB().Exec(`INSERT INTO chain_tunnel(tunnel_id, chain_type, node_id, port, strategy, inx, protocol) VALUES(?, 1, ?, 24001, 'round', 1, 'tls')`, tunnelB, nodeB); err != nil {
+	if err := repo.DB().Exec(`INSERT INTO chain_tunnel(tunnel_id, chain_type, node_id, port, strategy, inx, protocol) VALUES(?, 1, ?, 24001, 'round', 1, 'tls')`, tunnelB, nodeB).Error; err != nil {
 		t.Fatalf("insert chain_tunnel B: %v", err)
 	}
 
-	if _, err := repo.DB().Exec(`INSERT INTO user_tunnel(id, user_id, tunnel_id, speed_id, num, flow, in_flow, out_flow, flow_reset_time, exp_time, status) VALUES(20, 2, ?, NULL, 999, 99999, 0, 0, 1, 2727251700000, 1)`, tunnelA); err != nil {
+	if err := repo.DB().Exec(`INSERT INTO user_tunnel(id, user_id, tunnel_id, speed_id, num, flow, in_flow, out_flow, flow_reset_time, exp_time, status) VALUES(20, 2, ?, NULL, 999, 99999, 0, 0, 1, 2727251700000, 1)`, tunnelA).Error; err != nil {
 		t.Fatalf("insert user_tunnel A: %v", err)
 	}
-	if _, err := repo.DB().Exec(`INSERT INTO user_tunnel(id, user_id, tunnel_id, speed_id, num, flow, in_flow, out_flow, flow_reset_time, exp_time, status) VALUES(21, 2, ?, NULL, 999, 99999, 0, 0, 1, 2727251700000, 1)`, tunnelB); err != nil {
+	if err := repo.DB().Exec(`INSERT INTO user_tunnel(id, user_id, tunnel_id, speed_id, num, flow, in_flow, out_flow, flow_reset_time, exp_time, status) VALUES(21, 2, ?, NULL, 999, 99999, 0, 0, 1, 2727251700000, 1)`, tunnelB).Error; err != nil {
 		t.Fatalf("insert user_tunnel B: %v", err)
 	}
 
-	forwardRes, err := repo.DB().Exec(`
+	if err := repo.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, 'batch_switch_user', 'batch-switch-forward', ?, '1.1.1.1:443', 'fifo', 0, 0, ?, ?, 1, 0)
-	`, tunnelA, now, now)
-	if err != nil {
+	`, tunnelA, now, now).Error; err != nil {
 		t.Fatalf("insert forward: %v", err)
 	}
-	forwardID, _ := forwardRes.LastInsertId()
+	forwardID := mustLastInsertID(t, repo, "batch-switch-forward")
 
-	if _, err := repo.DB().Exec(`INSERT INTO forward_port(forward_id, node_id, port) VALUES(?, ?, ?)`, forwardID, nodeA, 23001); err != nil {
+	if err := repo.DB().Exec(`INSERT INTO forward_port(forward_id, node_id, port) VALUES(?, ?, ?)`, forwardID, nodeA, 23001).Error; err != nil {
 		t.Fatalf("insert forward_port: %v", err)
 	}
 
@@ -429,19 +387,12 @@ func TestForwardBatchChangeTunnelRollbackOnSyncFailure(t *testing.T) {
 		t.Fatalf("expected failCount=1, got %v", result["failCount"])
 	}
 
-	var tunnelAfter int64
-	if err := repo.DB().QueryRow(`SELECT tunnel_id FROM forward WHERE id = ?`, forwardID).Scan(&tunnelAfter); err != nil {
-		t.Fatalf("query forward tunnel_id: %v", err)
-	}
+	tunnelAfter := mustQueryInt64(t, repo, `SELECT tunnel_id FROM forward WHERE id = ?`, forwardID)
 	if tunnelAfter != tunnelA {
 		t.Fatalf("expected tunnel rollback to %d, got %d", tunnelA, tunnelAfter)
 	}
 
-	var nodeAfter int64
-	var portAfter int
-	if err := repo.DB().QueryRow(`SELECT node_id, port FROM forward_port WHERE forward_id = ? LIMIT 1`, forwardID).Scan(&nodeAfter, &portAfter); err != nil {
-		t.Fatalf("query forward_port: %v", err)
-	}
+	nodeAfter, portAfter := mustQueryInt64Int(t, repo, `SELECT node_id, port FROM forward_port WHERE forward_id = ? LIMIT 1`, forwardID)
 	if nodeAfter != nodeA || portAfter != 23001 {
 		t.Fatalf("expected forward_port rollback to node=%d port=23001, got node=%d port=%d", nodeA, nodeAfter, portAfter)
 	}
@@ -457,21 +408,20 @@ func TestUserTunnelReassignmentKeepsStableID(t *testing.T) {
 		t.Fatalf("generate admin token: %v", err)
 	}
 
-	if _, err := repo.DB().Exec(`
+	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(100, 'stable_user', 'pwd', 1, 2727251700000, 99999, 0, 0, 1, 99999, ?, ?, 1)
-	`, now, now); err != nil {
+	`, now, now).Error; err != nil {
 		t.Fatalf("insert user: %v", err)
 	}
 
-	tunnelRes, err := repo.DB().Exec(`
+	if err := repo.DB().Exec(`
 		INSERT INTO tunnel(name, traffic_ratio, type, protocol, flow, created_time, updated_time, status, in_ip, inx)
 		VALUES('stable-tunnel', 1.0, 1, 'tls', 99999, ?, ?, 1, NULL, 0)
-	`, now, now)
-	if err != nil {
+	`, now, now).Error; err != nil {
 		t.Fatalf("insert tunnel: %v", err)
 	}
-	tunnelID, _ := tunnelRes.LastInsertId()
+	tunnelID := mustLastInsertID(t, repo, "stable-tunnel")
 
 	// 1. Assign permission (creates new user_tunnel)
 	// userTunnelBatchAssign expects structure: {userId: 123, tunnels: [{tunnelId: 456, ...}]}
@@ -490,10 +440,7 @@ func TestUserTunnelReassignmentKeepsStableID(t *testing.T) {
 		t.Fatalf("expected code 0, got %d msg=%q", out.Code, out.Msg)
 	}
 
-	var initialID int64
-	if err := repo.DB().QueryRow(`SELECT id FROM user_tunnel WHERE user_id = 100 AND tunnel_id = ?`, tunnelID).Scan(&initialID); err != nil {
-		t.Fatalf("query initial user_tunnel id: %v", err)
-	}
+	initialID := mustQueryInt64(t, repo, `SELECT id FROM user_tunnel WHERE user_id = 100 AND tunnel_id = ?`, tunnelID)
 
 	// 2. Re-assign permission (should UPDATE, not INSERT)
 	reassignPayload := `{"userId":100,"tunnels":[{"tunnelId":` + jsonNumber(tunnelID) + `}]}`
@@ -512,18 +459,12 @@ func TestUserTunnelReassignmentKeepsStableID(t *testing.T) {
 	}
 
 	// 3. Verify stable ID and no duplicates
-	var count int
-	if err := repo.DB().QueryRow(`SELECT COUNT(1) FROM user_tunnel WHERE user_id = 100 AND tunnel_id = ?`, tunnelID).Scan(&count); err != nil {
-		t.Fatalf("query count: %v", err)
-	}
+	count := mustQueryInt(t, repo, `SELECT COUNT(1) FROM user_tunnel WHERE user_id = 100 AND tunnel_id = ?`, tunnelID)
 	if count != 1 {
 		t.Fatalf("expected exactly 1 user_tunnel record, got %d", count)
 	}
 
-	var currentID int64
-	if err := repo.DB().QueryRow(`SELECT id FROM user_tunnel WHERE user_id = 100 AND tunnel_id = ?`, tunnelID).Scan(&currentID); err != nil {
-		t.Fatalf("query current user_tunnel: %v", err)
-	}
+	currentID := mustQueryInt64(t, repo, `SELECT id FROM user_tunnel WHERE user_id = 100 AND tunnel_id = ?`, tunnelID)
 
 	if currentID != initialID {
 		t.Fatalf("user_tunnel ID changed from %d to %d (unstable ID!)", initialID, currentID)

go-backend/tests/contract/group_permission_contract_test.go

@@ -0,0 +1,167 @@
+package contract_test
+
+import (
+	"bytes"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"go-backend/internal/auth"
+)
+
+func TestGroupUserUnbindRevokesInheritedTunnelPermission(t *testing.T) {
+	secret := "contract-jwt-secret"
+	router, repo := setupContractRouter(t, secret)
+	now := time.Now().UnixMilli()
+
+	if err := repo.DB().Exec(`
+		INSERT INTO user(id, user, pwd, role_id, exp_time, flow, in_flow, out_flow, flow_reset_time, num, created_time, updated_time, status)
+		VALUES(200, 'group_user_contract', '3c85cdebade1c51cf64ca9f3c09d182d', 1, 2727251700000, 99999, 0, 0, 1, 99999, ?, ?, 1)
+	`, now, now).Error; err != nil {
+		t.Fatalf("insert test 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('group-contract-tunnel', 1.0, 1, 'tls', 99999, ?, ?, 1, NULL, 0)
+	`, now, now).Error; err != nil {
+		t.Fatalf("insert tunnel: %v", err)
+	}
+	tunnelID := mustLastInsertID(t, repo, "group-contract-tunnel")
+
+	if err := repo.DB().Exec(`INSERT INTO user_group(name, created_time, updated_time, status) VALUES('ug-contract', ?, ?, 1)`, now, now).Error; err != nil {
+		t.Fatalf("insert user_group: %v", err)
+	}
+	userGroupID := mustLastInsertID(t, repo, "ug-contract")
+
+	if err := repo.DB().Exec(`INSERT INTO tunnel_group(name, created_time, updated_time, status) VALUES('tg-contract', ?, ?, 1)`, now, now).Error; err != nil {
+		t.Fatalf("insert tunnel_group: %v", err)
+	}
+	tunnelGroupID := mustLastInsertID(t, repo, "tg-contract")
+
+	if err := repo.DB().Exec(`INSERT INTO tunnel_group_tunnel(tunnel_group_id, tunnel_id, created_time) VALUES(?, ?, ?)`, tunnelGroupID, tunnelID, now).Error; err != nil {
+		t.Fatalf("insert tunnel_group_tunnel: %v", err)
+	}
+	if err := repo.DB().Exec(`INSERT INTO group_permission(user_group_id, tunnel_group_id, created_time) VALUES(?, ?, ?)`, userGroupID, tunnelGroupID, now).Error; err != nil {
+		t.Fatalf("insert group_permission: %v", err)
+	}
+
+	adminToken, err := auth.GenerateToken(1, "admin_user", 0, secret)
+	if err != nil {
+		t.Fatalf("generate admin token: %v", err)
+	}
+
+	bindReq := httptest.NewRequest(http.MethodPost, "/api/v1/group/user/assign", bytes.NewBufferString(`{"groupId":`+jsonNumber(userGroupID)+`,"userIds":[200]}`))
+	bindReq.Header.Set("Authorization", adminToken)
+	bindRes := httptest.NewRecorder()
+	router.ServeHTTP(bindRes, bindReq)
+	assertCode(t, bindRes, 0)
+
+	userTunnelID := mustQueryInt64(t, repo, `SELECT id FROM user_tunnel WHERE user_id = 200 AND tunnel_id = ?`, tunnelID)
+
+	grantCount := mustQueryInt(t, repo, `SELECT COUNT(1) FROM group_permission_grant WHERE user_tunnel_id = ?`, userTunnelID)
+	if grantCount == 0 {
+		t.Fatalf("expected non-zero grants after bind")
+	}
+
+	unbindReq := httptest.NewRequest(http.MethodPost, "/api/v1/group/user/assign", bytes.NewBufferString(`{"groupId":`+jsonNumber(userGroupID)+`,"userIds":[]}`))
+	unbindReq.Header.Set("Authorization", adminToken)
+	unbindRes := httptest.NewRecorder()
+	router.ServeHTTP(unbindRes, unbindReq)
+	assertCode(t, unbindRes, 0)
+
+	grantCount = mustQueryInt(t, repo, `SELECT COUNT(1) FROM group_permission_grant WHERE user_tunnel_id = ?`, userTunnelID)
+	if grantCount != 0 {
+		t.Fatalf("expected grants revoked after unbind, got %d", grantCount)
+	}
+
+	userTunnelCount := mustQueryInt(t, repo, `SELECT COUNT(1) FROM user_tunnel WHERE id = ?`, userTunnelID)
+	if userTunnelCount != 0 {
+		t.Fatalf("expected user_tunnel revoked after unbind, got %d", userTunnelCount)
+	}
+}
+
+func TestGroupPermissionRemoveRevokesInheritedTunnelPermission(t *testing.T) {
+	secret := "contract-jwt-secret"
+	router, repo := setupContractRouter(t, secret)
+	now := time.Now().UnixMilli()
+
+	if err := repo.DB().Exec(`
+		INSERT INTO user(id, user, pwd, role_id, exp_time, flow, in_flow, out_flow, flow_reset_time, num, created_time, updated_time, status)
+		VALUES(201, 'group_user_permission_remove', '3c85cdebade1c51cf64ca9f3c09d182d', 1, 2727251700000, 99999, 0, 0, 1, 99999, ?, ?, 1)
+	`, now, now).Error; err != nil {
+		t.Fatalf("insert test 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('group-remove-tunnel', 1.0, 1, 'tls', 99999, ?, ?, 1, NULL, 0)
+	`, now, now).Error; err != nil {
+		t.Fatalf("insert tunnel: %v", err)
+	}
+	tunnelID := mustLastInsertID(t, repo, "group-remove-tunnel")
+
+	if err := repo.DB().Exec(`INSERT INTO user_group(name, created_time, updated_time, status) VALUES('ug-remove-contract', ?, ?, 1)`, now, now).Error; err != nil {
+		t.Fatalf("insert user_group: %v", err)
+	}
+	userGroupID := mustLastInsertID(t, repo, "ug-remove-contract")
+
+	if err := repo.DB().Exec(`INSERT INTO tunnel_group(name, created_time, updated_time, status) VALUES('tg-remove-contract', ?, ?, 1)`, now, now).Error; err != nil {
+		t.Fatalf("insert tunnel_group: %v", err)
+	}
+	tunnelGroupID := mustLastInsertID(t, repo, "tg-remove-contract")
+
+	adminToken, err := auth.GenerateToken(1, "admin_user", 0, secret)
+	if err != nil {
+		t.Fatalf("generate admin token: %v", err)
+	}
+
+	assignTunnelReq := httptest.NewRequest(http.MethodPost, "/api/v1/group/tunnel/assign", bytes.NewBufferString(`{"groupId":`+jsonNumber(tunnelGroupID)+`,"tunnelIds":[`+jsonNumber(tunnelID)+`]}`))
+	assignTunnelReq.Header.Set("Authorization", adminToken)
+	assignTunnelRes := httptest.NewRecorder()
+	router.ServeHTTP(assignTunnelRes, assignTunnelReq)
+	assertCode(t, assignTunnelRes, 0)
+
+	assignUserReq := httptest.NewRequest(http.MethodPost, "/api/v1/group/user/assign", bytes.NewBufferString(`{"groupId":`+jsonNumber(userGroupID)+`,"userIds":[201]}`))
+	assignUserReq.Header.Set("Authorization", adminToken)
+	assignUserRes := httptest.NewRecorder()
+	router.ServeHTTP(assignUserRes, assignUserReq)
+	assertCode(t, assignUserRes, 0)
+
+	assignPermissionReq := httptest.NewRequest(http.MethodPost, "/api/v1/group/permission/assign", bytes.NewBufferString(`{"userGroupId":`+jsonNumber(userGroupID)+`,"tunnelGroupId":`+jsonNumber(tunnelGroupID)+`}`))
+	assignPermissionReq.Header.Set("Authorization", adminToken)
+	assignPermissionRes := httptest.NewRecorder()
+	router.ServeHTTP(assignPermissionRes, assignPermissionReq)
+	assertCode(t, assignPermissionRes, 0)
+
+	permissionID := mustQueryInt64(t, repo, `SELECT id FROM group_permission WHERE user_group_id = ? AND tunnel_group_id = ?`, userGroupID, tunnelGroupID)
+
+	userTunnelID := mustQueryInt64(t, repo, `SELECT id FROM user_tunnel WHERE user_id = 201 AND tunnel_id = ?`, tunnelID)
+
+	grantCount := mustQueryInt(t, repo, `SELECT COUNT(1) FROM group_permission_grant WHERE user_tunnel_id = ?`, userTunnelID)
+	if grantCount == 0 {
+		t.Fatalf("expected non-zero grants after permission assign")
+	}
+
+	removeReq := httptest.NewRequest(http.MethodPost, "/api/v1/group/permission/remove", bytes.NewBufferString(`{"id":`+jsonNumber(permissionID)+`}`))
+	removeReq.Header.Set("Authorization", adminToken)
+	removeRes := httptest.NewRecorder()
+	router.ServeHTTP(removeRes, removeReq)
+	assertCode(t, removeRes, 0)
+
+	permissionCount := mustQueryInt(t, repo, `SELECT COUNT(1) FROM group_permission WHERE id = ?`, permissionID)
+	if permissionCount != 0 {
+		t.Fatalf("expected group_permission removed, got %d", permissionCount)
+	}
+
+	grantCount = mustQueryInt(t, repo, `SELECT COUNT(1) FROM group_permission_grant WHERE user_tunnel_id = ?`, userTunnelID)
+	if grantCount != 0 {
+		t.Fatalf("expected grants removed after permission remove, got %d", grantCount)
+	}
+
+	userTunnelCount := mustQueryInt(t, repo, `SELECT COUNT(1) FROM user_tunnel WHERE id = ?`, userTunnelID)
+	if userTunnelCount != 0 {
+		t.Fatalf("expected user_tunnel revoked after permission remove, got %d", userTunnelCount)
+	}
+}

go-backend/tests/contract/migration_contract_test.go

@@ -2,6 +2,7 @@ package contract_test
 
 import (
 	"bytes"
+	"database/sql"
 	"encoding/json"
 	"io"
 	"net/http"
@@ -16,19 +17,20 @@ import (
 	httpserver "go-backend/internal/http"
 	"go-backend/internal/http/handler"
 	"go-backend/internal/http/response"
-	"go-backend/internal/store/sqlite"
+	"go-backend/internal/store/repo"
+
+	"gorm.io/gorm"
 )
 
 func TestCaptchaVerifyLoginContract(t *testing.T) {
 	secret := "contract-jwt-secret"
-	router, repo := setupContractRouter(t, secret)
+	router, r := setupContractRouter(t, secret)
 
-	_, err := repo.DB().Exec(`
+	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
-	`, "captcha_enabled", "true", time.Now().UnixMilli())
-	if err != nil {
+	`, "captcha_enabled", "true", time.Now().UnixMilli()).Error; err != nil {
 		t.Fatalf("enable captcha: %v", err)
 	}
 
@@ -43,6 +45,18 @@ func TestCaptchaVerifyLoginContract(t *testing.T) {
 		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) {
 		verifyReq := httptest.NewRequest(http.MethodPost, "/api/v1/captcha/verify", bytes.NewBufferString(`{"id":"captcha-token-1","data":"ok"}`))
 		verifyReq.Header.Set("Content-Type", "application/json")
@@ -80,7 +94,7 @@ func TestCaptchaVerifyLoginContract(t *testing.T) {
 }
 
 func TestOpenAPISubStoreContracts(t *testing.T) {
-	router, repo := setupContractRouter(t, "contract-jwt-secret")
+	router, r := setupContractRouter(t, "contract-jwt-secret")
 
 	const tunnelFlowGB = int64(500)
 	const tunnelInFlow = int64(123)
@@ -88,17 +102,13 @@ func TestOpenAPISubStoreContracts(t *testing.T) {
 	const tunnelExpTimeMs = int64(2727251700000)
 
 	now := time.Now().UnixMilli()
-	res, err := repo.DB().Exec(`INSERT INTO tunnel(name, traffic_ratio, type, protocol, flow, created_time, updated_time, status, in_ip, inx) VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
-		"contract-tunnel", 1.0, 1, "tls", 1, now, now, 1, nil, 0)
-	if err != nil {
+	if err := r.DB().Exec(`INSERT INTO tunnel(name, traffic_ratio, type, protocol, flow, created_time, updated_time, status, in_ip, inx) VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+		"contract-tunnel", 1.0, 1, "tls", 1, now, now, 1, nil, 0).Error; err != nil {
 		t.Fatalf("insert tunnel: %v", err)
 	}
-	tunnelID, err := res.LastInsertId()
-	if err != nil {
-		t.Fatalf("last insert id: %v", err)
-	}
-	if _, err := repo.DB().Exec(`INSERT INTO user_tunnel(user_id, tunnel_id, speed_id, num, flow, in_flow, out_flow, flow_reset_time, exp_time, status) VALUES(?, ?, NULL, ?, ?, ?, ?, ?, ?, ?)`,
-		1, tunnelID, 99999, tunnelFlowGB, tunnelInFlow, tunnelOutFlow, 1, tunnelExpTimeMs, 1); err != nil {
+	tunnelID := mustLastInsertID(t, r, "contract-tunnel")
+	if err := r.DB().Exec(`INSERT INTO user_tunnel(user_id, tunnel_id, speed_id, num, flow, in_flow, out_flow, flow_reset_time, exp_time, status) VALUES(?, ?, NULL, ?, ?, ?, ?, ?, ?, ?)`,
+		1, tunnelID, 99999, tunnelFlowGB, tunnelInFlow, tunnelOutFlow, 1, tunnelExpTimeMs, 1).Error; err != nil {
 		t.Fatalf("insert user_tunnel: %v", err)
 	}
 
@@ -199,17 +209,489 @@ func TestSpeedLimitTunnelsRouteAlias(t *testing.T) {
 	})
 }
 
-func setupContractRouter(t *testing.T, jwtSecret string) (http.Handler, *sqlite.Repository) {
+func TestBackupExportImportRestoreContracts(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)
+	}
+	userToken, err := auth.GenerateToken(2, "normal_user", 1, secret)
+	if err != nil {
+		t.Fatalf("generate user token: %v", err)
+	}
+
+	key := "backup_contract_key"
+	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
+	`, key, "v1", time.Now().UnixMilli()).Error; err != nil {
+		t.Fatalf("seed config for backup contract: %v", err)
+	}
+
+	t.Run("non-admin is blocked on backup export", func(t *testing.T) {
+		req := httptest.NewRequest(http.MethodPost, "/api/v1/backup/export", nil)
+		req.Header.Set("Authorization", userToken)
+		resp := httptest.NewRecorder()
+
+		router.ServeHTTP(resp, req)
+		assertCodeMsg(t, resp, 403, "权限不足，仅管理员可操作")
+	})
+
+	t.Run("standard and duplicate export routes both work", func(t *testing.T) {
+		payloadA := exportBackupPayload(t, router, "/api/v1/backup/export", adminToken)
+		if len(payloadA.Configs) == 0 {
+			t.Fatalf("expected exported configs, got none")
+		}
+		if _, ok := payloadA.Configs[key]; !ok {
+			t.Fatalf("expected %q in exported configs", key)
+		}
+
+		payloadB := exportBackupPayload(t, router, "/api/v1/api/v1/backup/export", adminToken)
+		if len(payloadB.Configs) == 0 {
+			t.Fatalf("expected exported configs from duplicate-prefix route, got none")
+		}
+	})
+
+	t.Run("backup import applies exported data", func(t *testing.T) {
+		payload := exportBackupPayload(t, router, "/api/v1/backup/export", adminToken)
+		payload.Configs[key] = "v2"
+		raw, err := json.Marshal(backupImportPayload{Types: []string{"configs"}, backupExportPayload: payload})
+		if err != nil {
+			t.Fatalf("marshal import payload: %v", err)
+		}
+
+		req := httptest.NewRequest(http.MethodPost, "/api/v1/backup/import", bytes.NewReader(raw))
+		req.Header.Set("Authorization", adminToken)
+		req.Header.Set("Content-Type", "application/json")
+		resp := httptest.NewRecorder()
+
+		router.ServeHTTP(resp, req)
+		var out response.R
+		if err := json.NewDecoder(resp.Body).Decode(&out); err != nil {
+			t.Fatalf("decode import response: %v", err)
+		}
+		if out.Code != 0 {
+			t.Fatalf("expected import code 0, got %d (%s)", out.Code, out.Msg)
+		}
+
+		cfg, err := r.GetConfigByName(key)
+		if err != nil {
+			t.Fatalf("query imported config: %v", err)
+		}
+		if cfg == nil || cfg.Value != "v2" {
+			t.Fatalf("expected imported config value v2, got %+v", cfg)
+		}
+	})
+
+	t.Run("backup restore alias applies exported data", func(t *testing.T) {
+		payload := exportBackupPayload(t, router, "/api/v1/backup/export", adminToken)
+		payload.Configs[key] = "v3"
+		raw, err := json.Marshal(backupImportPayload{Types: []string{"configs"}, backupExportPayload: payload})
+		if err != nil {
+			t.Fatalf("marshal restore payload: %v", err)
+		}
+
+		req := httptest.NewRequest(http.MethodPost, "/api/v1/backup/restore", bytes.NewReader(raw))
+		req.Header.Set("Authorization", adminToken)
+		req.Header.Set("Content-Type", "application/json")
+		resp := httptest.NewRecorder()
+
+		router.ServeHTTP(resp, req)
+		var out response.R
+		if err := json.NewDecoder(resp.Body).Decode(&out); err != nil {
+			t.Fatalf("decode restore response: %v", err)
+		}
+		if out.Code != 0 {
+			t.Fatalf("expected restore code 0, got %d (%s)", out.Code, out.Msg)
+		}
+
+		cfg, err := r.GetConfigByName(key)
+		if err != nil {
+			t.Fatalf("query restored config: %v", err)
+		}
+		if cfg == nil || cfg.Value != "v3" {
+			t.Fatalf("expected restored config value v3, got %+v", cfg)
+		}
+	})
+
+	t.Run("backup export and import preserve forward ports", func(t *testing.T) {
+		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(?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+		`, "backup-forward-tunnel", 1.0, 1, "tls", 0, now, now, 1, "", 88).Error; err != nil {
+			t.Fatalf("seed tunnel for forward backup: %v", err)
+		}
+		tunnelID := mustLastInsertID(t, r, "backup-forward-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", "backup-forward", tunnelID, "127.0.0.1:9000", "fifo", 0, 0, now, now, 1, 88).Error; err != nil {
+			t.Fatalf("seed forward for backup: %v", err)
+		}
+		forwardID := mustLastInsertID(t, r, "backup-forward")
+
+		expected := map[int64]int{
+			2001: 21001,
+			2002: 21002,
+		}
+		for nodeID, port := range expected {
+			if err := r.DB().Exec(`INSERT INTO forward_port(forward_id, node_id, port) VALUES(?, ?, ?)`, forwardID, nodeID, port).Error; err != nil {
+				t.Fatalf("seed forward_port %d:%d: %v", nodeID, port, err)
+			}
+		}
+
+		exportReq := httptest.NewRequest(http.MethodPost, "/api/v1/backup/export", bytes.NewBufferString(`{"types":["forwards"]}`))
+		exportReq.Header.Set("Authorization", adminToken)
+		exportReq.Header.Set("Content-Type", "application/json")
+		exportResp := httptest.NewRecorder()
+		router.ServeHTTP(exportResp, exportReq)
+
+		if exportResp.Code != http.StatusOK {
+			t.Fatalf("expected export status 200, got %d", exportResp.Code)
+		}
+
+		exportBody, err := io.ReadAll(exportResp.Body)
+		if err != nil {
+			t.Fatalf("read forwards backup body: %v", err)
+		}
+
+		var payload map[string]interface{}
+		if err := json.Unmarshal(exportBody, &payload); err != nil {
+			t.Fatalf("decode forwards backup payload: %v", err)
+		}
+		version, _ := payload["version"].(string)
+		if strings.TrimSpace(version) == "" {
+			t.Fatalf("expected backup payload version, body=%s", string(exportBody))
+		}
+
+		forwardsRaw, ok := payload["forwards"].([]interface{})
+		if !ok {
+			t.Fatalf("expected forwards array in payload, body=%s", string(exportBody))
+		}
+
+		foundForward := false
+		foundPorts := map[int64]int{}
+		for _, item := range forwardsRaw {
+			forwardMap, ok := item.(map[string]interface{})
+			if !ok {
+				continue
+			}
+			idValue, ok := forwardMap["id"].(float64)
+			if !ok || int64(idValue) != forwardID {
+				continue
+			}
+			foundForward = true
+
+			portsRaw, ok := forwardMap["forwardPorts"].([]interface{})
+			if !ok {
+				t.Fatalf("expected forwardPorts for forward %d in payload", forwardID)
+			}
+			for _, p := range portsRaw {
+				portMap, ok := p.(map[string]interface{})
+				if !ok {
+					continue
+				}
+				nodeID, nodeOK := portMap["nodeId"].(float64)
+				port, portOK := portMap["port"].(float64)
+				if nodeOK && portOK {
+					foundPorts[int64(nodeID)] = int(port)
+				}
+			}
+			break
+		}
+
+		if !foundForward {
+			t.Fatalf("expected forward %d in exported forwards payload", forwardID)
+		}
+		if len(foundPorts) != len(expected) {
+			t.Fatalf("expected %d exported forward ports, got %d", len(expected), len(foundPorts))
+		}
+		for nodeID, port := range expected {
+			if got, ok := foundPorts[nodeID]; !ok || got != port {
+				t.Fatalf("expected exported forward port node=%d port=%d, got %v", nodeID, port, foundPorts)
+			}
+		}
+
+		if err := r.DB().Exec(`DELETE FROM forward_port WHERE forward_id = ?`, forwardID).Error; err != nil {
+			t.Fatalf("clear forward_port before import: %v", err)
+		}
+		if err := r.DB().Exec(`INSERT INTO forward_port(forward_id, node_id, port) VALUES(?, ?, ?)`, forwardID, 9999, 39999).Error; err != nil {
+			t.Fatalf("seed wrong forward_port before import: %v", err)
+		}
+
+		payload["types"] = []string{"forwards"}
+		importBody, err := json.Marshal(payload)
+		if err != nil {
+			t.Fatalf("marshal forwards import payload: %v", err)
+		}
+
+		importReq := httptest.NewRequest(http.MethodPost, "/api/v1/backup/import", bytes.NewReader(importBody))
+		importReq.Header.Set("Authorization", adminToken)
+		importReq.Header.Set("Content-Type", "application/json")
+		importResp := httptest.NewRecorder()
+		router.ServeHTTP(importResp, importReq)
+
+		var out response.R
+		if err := json.NewDecoder(importResp.Body).Decode(&out); err != nil {
+			t.Fatalf("decode forwards import response: %v", err)
+		}
+		if out.Code != 0 {
+			t.Fatalf("expected forwards import code 0, got %d (%s)", out.Code, out.Msg)
+		}
+
+		after := mustQueryNodePorts(t, r, `SELECT node_id, port FROM forward_port WHERE forward_id = ? ORDER BY id ASC`, forwardID)
+
+		if len(after) != len(expected) {
+			t.Fatalf("expected %d forward ports after import, got %d (%v)", len(expected), len(after), after)
+		}
+		for nodeID, port := range expected {
+			if got, ok := after[nodeID]; !ok || got != port {
+				t.Fatalf("expected forward_port node=%d port=%d after import, got %v", nodeID, port, after)
+			}
+		}
+	})
+
+	t.Run("backup export tolerates nullable legacy tunnel chain fields", func(t *testing.T) {
+		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(?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+		`, "legacy-null-chain", 1.0, 1, "tls", 1000, now, now, 1, nil, 1).Error; err != nil {
+			t.Fatalf("seed tunnel for nullable chain export: %v", err)
+		}
+		tunnelID := mustLastInsertID(t, r, "legacy-null-chain")
+
+		if err := r.DB().Exec(`
+			INSERT INTO chain_tunnel(tunnel_id, chain_type, node_id, port, strategy, inx, protocol)
+			VALUES(?, ?, ?, ?, ?, ?, ?)
+		`, tunnelID, "1", 1, nil, nil, nil, nil).Error; err != nil {
+			t.Fatalf("seed nullable chain_tunnel row: %v", err)
+		}
+
+		req := httptest.NewRequest(http.MethodPost, "/api/v1/backup/export", bytes.NewBufferString(`{"types":["tunnels"]}`))
+		req.Header.Set("Authorization", adminToken)
+		req.Header.Set("Content-Type", "application/json")
+		resp := httptest.NewRecorder()
+		router.ServeHTTP(resp, req)
+
+		if resp.Code != http.StatusOK {
+			t.Fatalf("expected status 200, got %d", resp.Code)
+		}
+
+		var payload struct {
+			Version string `json:"version"`
+			Tunnels []struct {
+				ID           int64 `json:"id"`
+				ChainTunnels []struct {
+					Inx      int    `json:"inx"`
+					Strategy string `json:"strategy"`
+					Protocol string `json:"protocol"`
+				} `json:"chainTunnels"`
+			} `json:"tunnels"`
+		}
+		if err := json.NewDecoder(resp.Body).Decode(&payload); err != nil {
+			t.Fatalf("decode tunnels backup payload: %v", err)
+		}
+		if strings.TrimSpace(payload.Version) == "" {
+			t.Fatalf("expected backup payload version, got empty")
+		}
+
+		found := false
+		for _, tunnel := range payload.Tunnels {
+			if tunnel.ID != tunnelID {
+				continue
+			}
+			if len(tunnel.ChainTunnels) != 1 {
+				t.Fatalf("expected one chain tunnel for seeded tunnel %d, got %d", tunnelID, len(tunnel.ChainTunnels))
+			}
+			if tunnel.ChainTunnels[0].Inx != 0 {
+				t.Fatalf("expected nullable chain inx to export as 0, got %d", tunnel.ChainTunnels[0].Inx)
+			}
+			if tunnel.ChainTunnels[0].Strategy != "" {
+				t.Fatalf("expected nullable chain strategy to export as empty string, got %q", tunnel.ChainTunnels[0].Strategy)
+			}
+			if tunnel.ChainTunnels[0].Protocol != "" {
+				t.Fatalf("expected nullable chain protocol to export as empty string, got %q", tunnel.ChainTunnels[0].Protocol)
+			}
+			found = true
+			break
+		}
+		if !found {
+			t.Fatalf("expected seeded tunnel %d in backup export", tunnelID)
+		}
+	})
+}
+
+type backupExportPayload struct {
+	Version    string            `json:"version"`
+	ExportedAt int64             `json:"exportedAt"`
+	Configs    map[string]string `json:"configs"`
+}
+
+type backupImportPayload struct {
+	Types []string `json:"types"`
+	backupExportPayload
+}
+
+func exportBackupPayload(t *testing.T, router http.Handler, path, token string) backupExportPayload {
+	t.Helper()
+	req := httptest.NewRequest(http.MethodPost, path, bytes.NewBufferString(`{"types":["configs"]}`))
+	req.Header.Set("Authorization", token)
+	req.Header.Set("Content-Type", "application/json")
+	resp := httptest.NewRecorder()
+
+	router.ServeHTTP(resp, req)
+	if resp.Code != http.StatusOK {
+		t.Fatalf("expected status 200 on %s, got %d", path, resp.Code)
+	}
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		t.Fatalf("read backup payload from %s: %v", path, err)
+	}
+
+	var payload backupExportPayload
+	if err := json.Unmarshal(body, &payload); err != nil {
+		t.Fatalf("decode backup payload from %s: %v", path, err)
+	}
+	if strings.TrimSpace(payload.Version) == "" {
+		var out response.R
+		if err := json.Unmarshal(body, &out); err == nil {
+			t.Fatalf("expected backup payload on %s, got envelope code=%d msg=%q", path, out.Code, out.Msg)
+		}
+		t.Fatalf("expected non-empty backup payload version on %s, body=%s", path, string(body))
+	}
+	if payload.Configs == nil {
+		t.Fatalf("expected configs map in backup payload on %s", path)
+	}
+	return payload
+}
+
+func setupContractRouter(t *testing.T, jwtSecret string) (http.Handler, *repo.Repository) {
 	t.Helper()
 	dbPath := filepath.Join(t.TempDir(), "contract.db")
-	repo, err := sqlite.Open(dbPath)
+	r, err := repo.Open(dbPath)
 	if err != nil {
 		t.Fatalf("open sqlite: %v", err)
 	}
 	t.Cleanup(func() {
-		_ = repo.Close()
+		_ = r.Close()
 	})
 
-	h := handler.New(repo, jwtSecret)
-	return httpserver.NewRouter(h, jwtSecret), repo
+	h := handler.New(r, jwtSecret)
+	return httpserver.NewRouter(h, jwtSecret), r
+}
+
+func TestOpenMigratesLegacyNodeDualStackColumns(t *testing.T) {
+	dbPath := filepath.Join(t.TempDir(), "legacy-2.0.7-beta.db")
+	legacyDB, err := sql.Open("sqlite", dbPath)
+	if err != nil {
+		t.Fatalf("open legacy sqlite: %v", err)
+	}
+
+	t.Cleanup(func() {
+		_ = legacyDB.Close()
+	})
+
+	if _, err := legacyDB.Exec(`
+		CREATE TABLE IF NOT EXISTS node (
+			id INTEGER PRIMARY KEY AUTOINCREMENT,
+			name VARCHAR(100) NOT NULL,
+			secret VARCHAR(100) NOT NULL,
+			server_ip VARCHAR(100) NOT NULL,
+			port TEXT NOT NULL,
+			interface_name VARCHAR(200),
+			version VARCHAR(100),
+			http INTEGER NOT NULL DEFAULT 0,
+			tls INTEGER NOT NULL DEFAULT 0,
+			socks INTEGER NOT NULL DEFAULT 0,
+			created_time INTEGER NOT NULL,
+			updated_time INTEGER,
+			status INTEGER NOT NULL,
+			tcp_listen_addr VARCHAR(100) NOT NULL DEFAULT '[::]',
+			udp_listen_addr VARCHAR(100) NOT NULL DEFAULT '[::]'
+		)
+	`); err != nil {
+		t.Fatalf("create legacy node table: %v", err)
+	}
+
+	if _, err := legacyDB.Exec(`
+		CREATE TABLE IF NOT EXISTS tunnel (
+			id INTEGER PRIMARY KEY AUTOINCREMENT,
+			name VARCHAR(100) NOT NULL,
+			traffic_ratio REAL NOT NULL DEFAULT 1.0,
+			type INTEGER NOT NULL,
+			protocol VARCHAR(10) NOT NULL DEFAULT 'tls',
+			flow INTEGER NOT NULL,
+			created_time INTEGER NOT NULL,
+			updated_time INTEGER NOT NULL,
+			status INTEGER NOT NULL,
+			in_ip TEXT
+		)
+	`); err != nil {
+		t.Fatalf("create legacy tunnel table: %v", err)
+	}
+
+	now := time.Now().UnixMilli()
+	if _, err := legacyDB.Exec(`
+		INSERT INTO node(name, secret, server_ip, port, interface_name, version, http, tls, socks, created_time, updated_time, status, tcp_listen_addr, udp_listen_addr)
+		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, "legacy-node", "legacy-secret", "10.10.0.1", "10000-10010", "eth0", "v-old", 1, 1, 1, now, now, 1, "[::]", "[::]"); err != nil {
+		t.Fatalf("seed legacy node row: %v", err)
+	}
+
+	r, err := repo.Open(dbPath)
+	if err != nil {
+		t.Fatalf("open migrated sqlite: %v", err)
+	}
+	t.Cleanup(func() {
+		_ = r.Close()
+	})
+
+	nodes, err := r.ListNodes()
+	if err != nil {
+		t.Fatalf("list nodes after migration: %v", err)
+	}
+	if len(nodes) != 1 {
+		t.Fatalf("expected 1 node after migration, got %d", len(nodes))
+	}
+
+	columns := readTableColumns(t, r.DB(), "node")
+
+	for _, required := range []string{"server_ip_v4", "server_ip_v6", "inx"} {
+		if !columns[required] {
+			t.Fatalf("expected node column %q to exist after migration", required)
+		}
+	}
+
+	tunnelColumns := readTableColumns(t, r.DB(), "tunnel")
+	if !tunnelColumns["inx"] {
+		t.Fatalf("expected tunnel column %q to exist after migration", "inx")
+	}
+}
+
+func readTableColumns(t *testing.T, db *gorm.DB, table string) map[string]bool {
+	t.Helper()
+
+	columnTypes, err := db.Migrator().ColumnTypes(table)
+	if err != nil {
+		t.Fatalf("inspect %s columns: %v", table, err)
+	}
+
+	columns := map[string]bool{}
+	for _, col := range columnTypes {
+		name := strings.TrimSpace(col.Name())
+		if name == "" {
+			continue
+		}
+		columns[name] = true
+	}
+
+	return columns
 }

go-backend/tests/contract/postgres_node_id_repair_contract_test.go

@@ -0,0 +1,109 @@
+package contract_test
+
+import (
+	"database/sql"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"os"
+	"strconv"
+	"strings"
+	"testing"
+	"time"
+
+	_ "github.com/jackc/pgx/v5/stdlib"
+
+	"go-backend/internal/auth"
+	httpserver "go-backend/internal/http"
+	"go-backend/internal/http/handler"
+	"go-backend/internal/store/repo"
+)
+
+func TestPostgresNodeCreateRepairsMissingIDDefaultContract(t *testing.T) {
+	baseDSN := strings.TrimSpace(os.Getenv("FLVX_POSTGRES_TEST_DSN"))
+	if baseDSN == "" {
+		t.Skip("set FLVX_POSTGRES_TEST_DSN to run postgres contract tests")
+	}
+
+	schemaName := "contract_node_id_" + strconv.FormatInt(time.Now().UnixNano(), 36)
+	adminDB, err := sql.Open("pgx", baseDSN)
+	if err != nil {
+		t.Fatalf("open postgres admin connection: %v", err)
+	}
+	t.Cleanup(func() {
+		_, _ = adminDB.Exec(`DROP SCHEMA IF EXISTS "` + schemaName + `" CASCADE`)
+		_ = adminDB.Close()
+	})
+
+	if _, err := adminDB.Exec(`CREATE SCHEMA "` + schemaName + `"`); err != nil {
+		t.Fatalf("create schema %s: %v", schemaName, err)
+	}
+
+	testDSN, err := withSearchPath(baseDSN, schemaName)
+	if err != nil {
+		t.Fatalf("build schema dsn: %v", err)
+	}
+
+	r, err := repo.OpenPostgres(testDSN)
+	if err != nil {
+		t.Fatalf("open postgres repository: %v", err)
+	}
+	if err := r.DB().Exec(`ALTER TABLE node ALTER COLUMN id DROP DEFAULT`).Error; err != nil {
+		_ = r.Close()
+		t.Fatalf("drop node.id default to simulate drift: %v", err)
+	}
+	if err := r.Close(); err != nil {
+		t.Fatalf("close repository before reopen: %v", err)
+	}
+
+	r, err = repo.OpenPostgres(testDSN)
+	if err != nil {
+		t.Fatalf("reopen postgres repository: %v", err)
+	}
+	t.Cleanup(func() {
+		_ = r.Close()
+	})
+
+	columnDefault := mustQueryNullString(t, r, `
+		SELECT column_default
+		FROM information_schema.columns
+		WHERE table_schema = current_schema()
+		  AND table_name = 'node'
+		  AND column_name = 'id'
+		LIMIT 1
+	`)
+	if !columnDefault.Valid || !strings.Contains(strings.ToLower(columnDefault.String), "nextval(") {
+		t.Fatalf("expected node.id default to be nextval(...), got %q", columnDefault.String)
+	}
+
+	jwtSecret := "postgres-contract-secret"
+	router := httpserver.NewRouter(handler.New(r, jwtSecret), jwtSecret)
+	token, err := auth.GenerateToken(1, "admin_user", 0, jwtSecret)
+	if err != nil {
+		t.Fatalf("generate admin token: %v", err)
+	}
+
+	body := strings.NewReader(`{"name":"pg-repair-node","serverIp":"10.77.0.10"}`)
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/node/create", body)
+	req.Header.Set("Authorization", token)
+	req.Header.Set("Content-Type", "application/json")
+	resp := httptest.NewRecorder()
+	router.ServeHTTP(resp, req)
+	assertCode(t, resp, 0)
+
+	nodeID := mustQueryInt64(t, r, `SELECT id FROM node WHERE name = ? ORDER BY id DESC LIMIT 1`, "pg-repair-node")
+	if nodeID <= 0 {
+		t.Fatalf("expected positive node id, got %d", nodeID)
+	}
+}
+
+func withSearchPath(dsn, schema string) (string, error) {
+	u, err := url.Parse(dsn)
+	if err != nil {
+		return "", err
+	}
+	q := u.Query()
+	q.Set("search_path", schema)
+	u.RawQuery = q.Encode()
+	return u.String(), nil
+}

go-backend/tests/contract/tunnel_create_contract_test.go

@@ -25,18 +25,13 @@ func TestTunnelCreateRuntimeRollbackContract(t *testing.T) {
 	}
 
 	insertNode := func(name, ip, portRange string) int64 {
-		res, err := repo.DB().Exec(`
+		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(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-		`, name, name+"-secret", ip, ip, "", portRange, "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", 0)
-		if err != nil {
+		`, name, name+"-secret", ip, ip, "", portRange, "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", 0).Error; err != nil {
 			t.Fatalf("insert node %s: %v", name, err)
 		}
-		id, err := res.LastInsertId()
-		if err != nil {
-			t.Fatalf("get node id %s: %v", name, err)
-		}
-		return id
+		return mustLastInsertID(t, repo, name)
 	}
 
 	entryID := insertNode("create-entry", "10.20.0.1", "30000-30010")
@@ -62,18 +57,12 @@ func TestTunnelCreateRuntimeRollbackContract(t *testing.T) {
 		t.Fatalf("expected node-related error, got %q", out.Msg)
 	}
 
-	var tunnelCount int
-	if err := repo.DB().QueryRow(`SELECT COUNT(1) FROM tunnel WHERE name = ?`, "runtime-rollback-tunnel").Scan(&tunnelCount); err != nil {
-		t.Fatalf("count tunnel: %v", err)
-	}
+	tunnelCount := mustQueryInt(t, repo, `SELECT COUNT(1) FROM tunnel WHERE name = ?`, "runtime-rollback-tunnel")
 	if tunnelCount != 0 {
 		t.Fatalf("expected tunnel rollback, found %d records", tunnelCount)
 	}
 
-	var chainCount int
-	if err := repo.DB().QueryRow(`SELECT COUNT(1) FROM chain_tunnel`).Scan(&chainCount); err != nil {
-		t.Fatalf("count chain_tunnel: %v", err)
-	}
+	chainCount := mustQueryInt(t, repo, `SELECT COUNT(1) FROM chain_tunnel`)
 	if chainCount != 0 {
 		t.Fatalf("expected chain_tunnel rollback, found %d records", chainCount)
 	}
@@ -90,35 +79,26 @@ func TestTunnelUpdateAssignsChainPortsContract(t *testing.T) {
 	}
 
 	insertNode := func(name, ip, portRange string) int64 {
-		res, err := repo.DB().Exec(`
+		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(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-		`, name, name+"-secret", ip, ip, "", portRange, "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", 0)
-		if err != nil {
+		`, name, name+"-secret", ip, ip, "", portRange, "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", 0).Error; err != nil {
 			t.Fatalf("insert node %s: %v", name, err)
 		}
-		id, err := res.LastInsertId()
-		if err != nil {
-			t.Fatalf("get node id %s: %v", name, err)
-		}
-		return id
+		return mustLastInsertID(t, repo, name)
 	}
 
 	entryID := insertNode("update-entry", "10.30.0.1", "40000-40010")
 	chainID := insertNode("update-chain", "10.30.0.2", "41000-41010")
 	exitID := insertNode("update-exit", "10.30.0.3", "42000-42010")
 
-	tunnelRes, err := repo.DB().Exec(`
+	if err := repo.DB().Exec(`
 		INSERT INTO tunnel(name, traffic_ratio, type, protocol, flow, created_time, updated_time, status, in_ip, inx)
 		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-	`, "update-port-tunnel", 1.0, 1, "tls", 99999, now, now, 1, nil, 0)
-	if err != nil {
+	`, "update-port-tunnel", 1.0, 1, "tls", 99999, now, now, 1, nil, 0).Error; err != nil {
 		t.Fatalf("insert tunnel: %v", err)
 	}
-	tunnelID, err := tunnelRes.LastInsertId()
-	if err != nil {
-		t.Fatalf("get tunnel id: %v", err)
-	}
+	tunnelID := mustLastInsertID(t, repo, "update-port-tunnel")
 
 	payload := `{"id":` + jsonInt(tunnelID) + `,"name":"update-port-tunnel","type":2,"flow":99999,"trafficRatio":1.0,"status":1,"inNodeId":[{"nodeId":` + jsonInt(entryID) + `,"protocol":"tls"}],"chainNodes":[[{"nodeId":` + jsonInt(chainID) + `,"protocol":"tls","strategy":"round"}]],"outNodeId":[{"nodeId":` + jsonInt(exitID) + `,"protocol":"tls"}]}`
 	req := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/update", bytes.NewBufferString(payload))
@@ -129,21 +109,23 @@ func TestTunnelUpdateAssignsChainPortsContract(t *testing.T) {
 	router.ServeHTTP(res, req)
 	assertCode(t, res, 0)
 
-	var chainPort int
-	if err := repo.DB().QueryRow(`SELECT port FROM chain_tunnel WHERE tunnel_id = ? AND chain_type = 2 LIMIT 1`, tunnelID).Scan(&chainPort); err != nil {
-		t.Fatalf("query chain port: %v", err)
-	}
+	chainPort := mustQueryInt(t, repo, `SELECT port FROM chain_tunnel WHERE tunnel_id = ? AND chain_type = 2 LIMIT 1`, tunnelID)
 	if chainPort <= 0 {
 		t.Fatalf("expected chain node port to be assigned, got %d", chainPort)
 	}
 
-	var outPort int
-	if err := repo.DB().QueryRow(`SELECT port FROM chain_tunnel WHERE tunnel_id = ? AND chain_type = 3 LIMIT 1`, tunnelID).Scan(&outPort); err != nil {
-		t.Fatalf("query out port: %v", err)
-	}
+	outPort := mustQueryInt(t, repo, `SELECT port FROM chain_tunnel WHERE tunnel_id = ? AND chain_type = 3 LIMIT 1`, tunnelID)
 	if outPort <= 0 {
 		t.Fatalf("expected out node port to be assigned, got %d", outPort)
 	}
+
+	entryStrategy := mustQueryNullString(t, repo, `SELECT strategy FROM chain_tunnel WHERE tunnel_id = ? AND chain_type = 1 LIMIT 1`, tunnelID)
+	if !entryStrategy.Valid || strings.TrimSpace(entryStrategy.String) == "" {
+		t.Fatalf("expected entry strategy to be non-null and non-empty")
+	}
+	if entryStrategy.String != "round" {
+		t.Fatalf("expected entry strategy round, got %q", entryStrategy.String)
+	}
 }
 
 func jsonInt(v int64) string {

go-backend/tests/contract/tunnel_ip_preference_contract_test.go

@@ -0,0 +1,263 @@
+package contract_test
+
+import (
+	"bytes"
+	"database/sql"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"go-backend/internal/auth"
+	"go-backend/internal/http/response"
+)
+
+func TestTunnelCreateWithIPPreferenceContract(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)
+	}
+
+	insertDualStackNode := func(name, v4, v6, portRange string) int64 {
+		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(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+		`, name, name+"-secret", v4, v4, v6, portRange, "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", 0).Error; err != nil {
+			t.Fatalf("insert node %s: %v", name, err)
+		}
+		return mustLastInsertID(t, repo, name)
+	}
+
+	entryID := insertDualStackNode("ip-pref-entry", "10.50.0.1", "2001:db8::1", "50000-50010")
+	exitID := insertDualStackNode("ip-pref-exit", "10.50.0.2", "2001:db8::2", "51000-51010")
+
+	for _, tc := range []struct {
+		name       string
+		preference string
+	}{
+		{"v4-preference", "v4"},
+		{"v6-preference", "v6"},
+		{"empty-preference", ""},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			payload := `{"name":"tunnel-` + tc.name + `","type":2,"flow":99999,"status":1,"ipPreference":"` + tc.preference + `","inNodeId":[{"nodeId":` + jsonInt(entryID) + `,"protocol":"tls"}],"chainNodes":[],"outNodeId":[{"nodeId":` + jsonInt(exitID) + `,"protocol":"tls"}]}`
+			req := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/create", bytes.NewBufferString(payload))
+			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)
+			}
+
+			stored, err := tryQueryString(t, repo, `SELECT COALESCE(ip_preference, '') FROM tunnel WHERE name = ?`, "tunnel-"+tc.name)
+			if err != nil {
+				if err == sql.ErrNoRows {
+					t.Skipf("tunnel not created (nodes offline), skipping DB verification")
+				}
+				t.Fatalf("query ip_preference: %v", err)
+			}
+			if stored != tc.preference {
+				t.Fatalf("expected ip_preference=%q in DB, got %q", tc.preference, stored)
+			}
+		})
+	}
+}
+
+func TestTunnelUpdateIPPreferenceContract(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)
+	}
+
+	insertDualStackNode := func(name, v4, v6, portRange string) int64 {
+		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(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+		`, name, name+"-secret", v4, v4, v6, portRange, "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", 0).Error; err != nil {
+			t.Fatalf("insert node %s: %v", name, err)
+		}
+		return mustLastInsertID(t, repo, name)
+	}
+
+	entryID := insertDualStackNode("upd-entry", "10.60.0.1", "2001:db8:1::1", "60000-60010")
+	exitID := insertDualStackNode("upd-exit", "10.60.0.2", "2001:db8:1::2", "61000-61010")
+
+	if err := repo.DB().Exec(`
+		INSERT INTO tunnel(name, traffic_ratio, type, protocol, flow, created_time, updated_time, status, in_ip, inx, ip_preference)
+		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, "update-ip-pref-tunnel", 1.0, 1, "tls", 99999, now, now, 1, nil, 0, "").Error; err != nil {
+		t.Fatalf("insert tunnel: %v", err)
+	}
+	tunnelID := mustLastInsertID(t, repo, "update-ip-pref-tunnel")
+
+	payload := `{"id":` + jsonInt(tunnelID) + `,"name":"update-ip-pref-tunnel","type":2,"flow":99999,"trafficRatio":1.0,"status":1,"ipPreference":"v6","inNodeId":[{"nodeId":` + jsonInt(entryID) + `,"protocol":"tls"}],"chainNodes":[],"outNodeId":[{"nodeId":` + jsonInt(exitID) + `,"protocol":"tls"}]}`
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/update", bytes.NewBufferString(payload))
+	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)
+	}
+
+	stored := mustQueryString(t, repo, `SELECT COALESCE(ip_preference, '') FROM tunnel WHERE id = ?`, tunnelID)
+	if stored != "v6" {
+		t.Fatalf("expected ip_preference='v6' after update, got %q", stored)
+	}
+}
+
+func TestTunnelListReturnsIPPreferenceContract(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)
+	}
+
+	err = repo.DB().Exec(`
+		INSERT INTO tunnel(name, traffic_ratio, type, protocol, flow, created_time, updated_time, status, in_ip, inx, ip_preference)
+		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, "list-ip-pref-tunnel", 1.0, 2, "tls", 99999, now, now, 1, nil, 0, "v6").Error
+	if err != nil {
+		t.Fatalf("insert tunnel: %v", err)
+	}
+
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/tunnel/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 (msg=%s)", out.Code, out.Msg)
+	}
+
+	tunnels, ok := out.Data.([]interface{})
+	if !ok || len(tunnels) == 0 {
+		t.Fatalf("expected non-empty tunnel list, got %v", out.Data)
+	}
+
+	found := false
+	for _, raw := range tunnels {
+		tm, ok := raw.(map[string]interface{})
+		if !ok {
+			continue
+		}
+		if tm["name"] == "list-ip-pref-tunnel" {
+			found = true
+			pref, _ := tm["ipPreference"].(string)
+			if pref != "v6" {
+				t.Fatalf("expected ipPreference='v6' in list response, got %q", pref)
+			}
+			break
+		}
+	}
+	if !found {
+		t.Fatal("tunnel 'list-ip-pref-tunnel' not found in list response")
+	}
+}
+
+func TestIPPreferenceColumnDefaultContract(t *testing.T) {
+	_, repo := setupContractRouter(t, "contract-jwt-secret")
+	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(?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, "no-pref-tunnel", 1.0, 2, "tls", 99999, now, now, 1, nil, 0).Error; err != nil {
+		t.Fatalf("insert tunnel without ip_preference: %v", err)
+	}
+
+	stored := mustQueryString(t, repo, `SELECT COALESCE(ip_preference, '') FROM tunnel WHERE name = ?`, "no-pref-tunnel")
+	if stored != "" {
+		t.Fatalf("expected default ip_preference='', got %q", stored)
+	}
+}
+
+func TestIPPreferenceColumnMigrationContract(t *testing.T) {
+	_, repo := setupContractRouter(t, "contract-jwt-secret")
+
+	colCount := mustQueryInt(t, repo, `SELECT COUNT(*) FROM pragma_table_info('tunnel') WHERE name = 'ip_preference'`)
+	if colCount != 1 {
+		t.Fatalf("expected ip_preference column to exist in tunnel table, found %d", colCount)
+	}
+}
+
+func TestIPPreferenceCoalesceNullSafety(t *testing.T) {
+	_, repo := setupContractRouter(t, "contract-jwt-secret")
+	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, ip_preference)
+		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL)
+	`, "null-pref-tunnel", 1.0, 2, "tls", 99999, now, now, 1, nil, 0).Error; err != nil {
+		t.Skipf("DB does not allow NULL ip_preference (NOT NULL constraint): %v", err)
+	}
+
+	stored := mustQueryString(t, repo, `SELECT COALESCE(ip_preference, '') FROM tunnel WHERE name = ?`, "null-pref-tunnel")
+	if stored != "" {
+		t.Fatalf("COALESCE should convert NULL to empty string, got %q", stored)
+	}
+}
+
+func TestDualStackNodeIPFieldsStoredContract(t *testing.T) {
+	_, repo := setupContractRouter(t, "contract-jwt-secret")
+	now := time.Now().UnixMilli()
+
+	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(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, "ds-verify-node", "ds-secret", "10.70.0.1", "10.70.0.1", "2001:db8:2::1", "70000-70010", "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", 0).Error; err != nil {
+		t.Fatalf("insert dual-stack node: %v", err)
+	}
+
+	v4, v6 := mustQueryTwoNullStrings(t, repo, `SELECT server_ip_v4, server_ip_v6 FROM node WHERE name = ?`, "ds-verify-node")
+	if !v4.Valid || v4.String != "10.70.0.1" {
+		t.Fatalf("expected server_ip_v4='10.70.0.1', got %v", v4)
+	}
+	if !v6.Valid || v6.String != "2001:db8:2::1" {
+		t.Fatalf("expected server_ip_v6='2001:db8:2::1', got %v", v6)
+	}
+}
+
+func TestIPPreferenceValidValuesContract(t *testing.T) {
+	_, repo := setupContractRouter(t, "contract-jwt-secret")
+	now := time.Now().UnixMilli()
+
+	for _, pref := range []string{"", "v4", "v6"} {
+		name := "valid-pref-" + pref
+		if pref == "" {
+			name = "valid-pref-empty"
+		}
+		if err := repo.DB().Exec(`
+			INSERT INTO tunnel(name, traffic_ratio, type, protocol, flow, created_time, updated_time, status, in_ip, inx, ip_preference)
+			VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+		`, name, 1.0, 2, "tls", 99999, now, now, 1, nil, 0, pref).Error; err != nil {
+			t.Fatalf("insert tunnel with ip_preference=%q: %v", pref, err)
+		}
+
+		stored := mustQueryString(t, repo, `SELECT COALESCE(ip_preference, '') FROM tunnel WHERE name = ?`, name)
+		if stored != pref {
+			t.Fatalf("expected ip_preference=%q, got %q for %s", pref, stored, name)
+		}
+	}
+}

go-backend/tests/contract/tunnel_visibility_contract_test.go

@@ -16,48 +16,43 @@ func TestUserTunnelVisibleListContracts(t *testing.T) {
 	router, repo := setupDiagnosisContractRouter(t, secret)
 	now := time.Now().UnixMilli()
 
-	if _, err := repo.DB().Exec(`
+	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, 'normal_user', '3c85cdebade1c51cf64ca9f3c09d182d', 1, 2727251700000, 99999, 0, 0, 1, 99999, ?, ?, 1)
-	`, now, now); err != nil {
+	`, now, now).Error; err != nil {
 		t.Fatalf("insert user: %v", err)
 	}
 
 	insertTunnel := func(name string, status int, inx int64) int64 {
-		res, err := repo.DB().Exec(`
+		if err := repo.DB().Exec(`
 			INSERT INTO tunnel(name, traffic_ratio, type, protocol, flow, created_time, updated_time, status, in_ip, inx)
 			VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-		`, name, 1.0, 1, "tls", 99999, now, now, status, nil, inx)
-		if err != nil {
+		`, name, 1.0, 1, "tls", 99999, now, now, status, nil, inx).Error; err != nil {
 			t.Fatalf("insert tunnel %s: %v", name, err)
 		}
-		id, err := res.LastInsertId()
-		if err != nil {
-			t.Fatalf("get tunnel id %s: %v", name, err)
-		}
-		return id
+		return mustLastInsertID(t, repo, name)
 	}
 
 	enabledA := insertTunnel("enabled-A", 1, 1)
 	enabledB := insertTunnel("enabled-B", 1, 2)
 	disabledC := insertTunnel("disabled-C", 0, 3)
 
-	if _, err := repo.DB().Exec(`
+	if err := repo.DB().Exec(`
 		INSERT INTO user_tunnel(user_id, tunnel_id, speed_id, num, flow, in_flow, out_flow, flow_reset_time, exp_time, status)
 		VALUES(?, ?, NULL, ?, ?, 0, 0, ?, ?, ?)
-	`, 2, enabledA, 100, 1000, 1, 2727251700000, 0); err != nil {
+	`, 2, enabledA, 100, 1000, 1, 2727251700000, 0).Error; err != nil {
 		t.Fatalf("insert user_tunnel enabledA: %v", err)
 	}
-	if _, err := repo.DB().Exec(`
+	if err := repo.DB().Exec(`
 		INSERT INTO user_tunnel(user_id, tunnel_id, speed_id, num, flow, in_flow, out_flow, flow_reset_time, exp_time, status)
 		VALUES(?, ?, NULL, ?, ?, 0, 0, ?, ?, ?)
-	`, 2, enabledB, 100, 1000, 1, 2727251700000, 1); err != nil {
+	`, 2, enabledB, 100, 1000, 1, 2727251700000, 1).Error; err != nil {
 		t.Fatalf("insert user_tunnel enabledB: %v", err)
 	}
-	if _, err := repo.DB().Exec(`
+	if err := repo.DB().Exec(`
 		INSERT INTO user_tunnel(user_id, tunnel_id, speed_id, num, flow, in_flow, out_flow, flow_reset_time, exp_time, status)
 		VALUES(?, ?, NULL, ?, ?, 0, 0, ?, ?, ?)
-	`, 2, disabledC, 100, 1000, 1, 2727251700000, 1); err != nil {
+	`, 2, disabledC, 100, 1000, 1, 2727251700000, 1).Error; err != nil {
 		t.Fatalf("insert user_tunnel disabledC: %v", err)
 	}
 

go-gost/AGENTS.md

@@ -1,6 +1,6 @@
 # GO-GOST SERVICE KNOWLEDGE BASE
 
-**Generated:** Mon Feb 02 2026
+**Generated:** Sun Feb 15 2026
 
 ## OVERVIEW
 Forwarding agent built on GOST v3 with a local fork of `github.com/go-gost/x` under `x/`.
@@ -27,6 +27,11 @@ go-gost/
 ## 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.
+
+## ANTI-PATTERNS
+- **DO NOT EDIT** generated protobuf in `x/internal/util/grpc/proto/`.
 
 ## COMMANDS
 ```bash

go-gost/x/AGENTS.md

@@ -1,7 +1,7 @@
 # GO-GOST/X KNOWLEDGE BASE
 
 ## OVERVIEW
-Local fork of `github.com/go-gost/x` used by `go-gost/` via `replace github.com/go-gost/x => ./x`. Most protocol/runtime behavior changes happen here.
+Local fork of `github.com/go-gost/x` used by `go-gost/` via `replace github.com/go-gost/x => ./x`. Most protocol/runtime behavior changes happen here. 30+ top-level packages - framework-style layout.
 
 ## STRUCTURE
 ```
@@ -31,6 +31,8 @@ go-gost/x/
 ## CONVENTIONS
 - `go-gost/x/` is a standalone Go module (`go-gost/x/go.mod`); run go tooling from this dir when debugging module resolution.
 - Generated gRPC/proto code lives under `go-gost/x/internal/util/grpc/proto/`.
+- Handlers/listeners/dialers follow consistent pattern: `{type}.go` + `metadata.go` per protocol.
+- OS-specific code uses `name_[os].go` suffix (e.g., `tun_linux.go`, `tun_darwin.go`).
 
 ## ANTI-PATTERNS
 - Do not edit generated files in `go-gost/x/internal/util/grpc/proto/` (`*.pb.go`, `*_grpc.pb.go`).

go-gost/x/config/parsing/service/parse.go

@@ -3,6 +3,7 @@ package service
 import (
 	"fmt"
 	"runtime"
+	"strconv"
 	"strings"
 	"time"
 
@@ -30,6 +31,7 @@ import (
 	logger_parser "github.com/go-gost/x/config/parsing/logger"
 	selector_parser "github.com/go-gost/x/config/parsing/selector"
 	tls_util "github.com/go-gost/x/internal/util/tls"
+	xtraffic "github.com/go-gost/x/limiter/traffic"
 	cache_limiter "github.com/go-gost/x/limiter/traffic/cache"
 	"github.com/go-gost/x/metadata"
 	mdutil "github.com/go-gost/x/metadata/util"
@@ -181,6 +183,32 @@ func ParseService(cfg *config.ServiceConfig) (service.Service, error) {
 		)
 	}
 
+	var trafficLimiter listener.Option
+	if cfg.Limiter != "" {
+		lim := registry.TrafficLimiterRegistry().Get(cfg.Limiter)
+		if lim == nil {
+			// Try to parse as simple number (bandwidth in bytes/sec)
+			if val, err := strconv.Atoi(cfg.Limiter); err == nil && val > 0 {
+				lim = xtraffic.NewTrafficLimiter(
+					xtraffic.LimitsOption(fmt.Sprintf("%s %dB %dB", xtraffic.ServiceLimitKey, val, val)),
+				)
+			}
+			if lim == nil {
+				lim = xtraffic.NewTrafficLimiter(
+					xtraffic.LimitsOption(fmt.Sprintf("%s %s %s", xtraffic.ServiceLimitKey, cfg.Limiter, cfg.Limiter)),
+				)
+			}
+		}
+		trafficLimiter = listener.TrafficLimiterOption(
+			cache_limiter.NewCachedTrafficLimiter(
+				lim,
+				cache_limiter.RefreshIntervalOption(limiterRefreshInterval),
+				cache_limiter.CleanupIntervalOption(limiterCleanupInterval),
+				cache_limiter.ScopeOption(limiterScope),
+			),
+		)
+	}
+
 	listenOpts := []listener.Option{
 		listener.AddrOption(cfg.Addr),
 		listener.RouterOption(xchain.NewRouter(routerOpts...)),
@@ -188,14 +216,6 @@ func ParseService(cfg *config.ServiceConfig) (service.Service, error) {
 		listener.AuthOption(auth_parser.Info(cfg.Listener.Auth)),
 		listener.TLSConfigOption(tlsConfig),
 		listener.AdmissionOption(xadmission.AdmissionGroup(admissions...)),
-		listener.TrafficLimiterOption(
-			cache_limiter.NewCachedTrafficLimiter(
-				registry.TrafficLimiterRegistry().Get(cfg.Limiter),
-				cache_limiter.RefreshIntervalOption(limiterRefreshInterval),
-				cache_limiter.CleanupIntervalOption(limiterCleanupInterval),
-				cache_limiter.ScopeOption(limiterScope),
-			),
-		),
 		listener.ConnLimiterOption(registry.ConnLimiterRegistry().Get(cfg.CLimiter)),
 		listener.ServiceOption(cfg.Name),
 		listener.ProxyProtocolOption(ppv),
@@ -203,6 +223,9 @@ func ParseService(cfg *config.ServiceConfig) (service.Service, error) {
 		listener.NetnsOption(netnsIn),
 		listener.LoggerOption(listenerLogger),
 	}
+	if trafficLimiter != nil {
+		listenOpts = append(listenOpts, trafficLimiter)
+	}
 
 	if netnsIn != "" {
 		runtime.LockOSThread()

go-gost/x/connector/AGENTS.md

@@ -0,0 +1,39 @@
+# GOST CONNECTOR KNOWLEDGE BASE
+
+**Generated:** Fri Feb 13 2026
+
+## OVERVIEW
+Connection initiators (clients) for various protocols in GOST forwarding.
+**Stack:** Go, GOST core.
+
+## STRUCTURE
+```
+connector/
+├── direct/    # Direct connection
+├── forward/   # Forward proxy
+├── http/      # HTTP connector
+├── http2/     # HTTP/2 connector
+├── relay/     # Relay protocol
+├── router/    # Router connector
+├── serial/    # Serial port
+├── sni/       # SNI routing
+├── socks/     # SOCKS4/5
+├── ss/        # Shadowsocks
+├── sshd/      # SSH daemon
+├── tcp/       # TCP connector
+├── tunnel/    # Tunnel mode
+└── unix/      # Unix socket
+```
+
+## CONVENTIONS
+- Inherits from parent `go-gost/x/` conventions.
+- Each subdir implements `Connector` interface from GOST core.
+
+## ANTI-PATTERNS
+- DO NOT EDIT generated protobuf in `go-gost/x/internal/util/grpc/proto/`.
+
+## COMMANDS
+```bash
+cd go-gost
+go test ./x/connector/...
+```

go-gost/x/go.mod

@@ -4,9 +4,7 @@ go 1.22.0
 
 toolchain go1.23.4
 
-require (
-	github.com/shirou/gopsutil/v3 v3.24.5
-)
+require github.com/shirou/gopsutil/v3 v3.24.5
 
 require (
 	github.com/alecthomas/units v0.0.0-20211218093645-b94a6e3cc137
@@ -76,6 +74,7 @@ require (
 	github.com/fsnotify/fsnotify v1.7.0 // indirect
 	github.com/gabriel-vasile/mimetype v1.4.3 // indirect
 	github.com/gin-contrib/sse v0.1.0 // indirect
+	github.com/go-ole/go-ole v1.2.6 // indirect
 	github.com/go-playground/locales v0.14.1 // indirect
 	github.com/go-playground/universal-translator v0.18.1 // indirect
 	github.com/go-playground/validator/v10 v10.20.0 // indirect
@@ -91,6 +90,7 @@ require (
 	github.com/klauspost/cpuid/v2 v2.2.7 // indirect
 	github.com/klauspost/reedsolomon v1.11.8 // indirect
 	github.com/leodido/go-urn v1.4.0 // indirect
+	github.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0 // indirect
 	github.com/magiconair/properties v1.8.7 // indirect
 	github.com/mattn/go-isatty v0.0.20 // indirect
 	github.com/mitchellh/mapstructure v1.5.0 // indirect
@@ -103,6 +103,7 @@ require (
 	github.com/pion/udp/v2 v2.0.1 // indirect
 	github.com/pkg/errors v0.9.1 // indirect
 	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
+	github.com/power-devops/perfstat v0.0.0-20210106213030-5aafc221ea8c // indirect
 	github.com/prometheus/client_model v0.6.0 // indirect
 	github.com/prometheus/common v0.48.0 // indirect
 	github.com/prometheus/procfs v0.12.0 // indirect
@@ -110,6 +111,7 @@ require (
 	github.com/riobard/go-bloom v0.0.0-20200614022211-cdc8013cb5b3 // indirect
 	github.com/sagikazarmark/locafero v0.4.0 // indirect
 	github.com/sagikazarmark/slog-shim v0.1.0 // indirect
+	github.com/shoenig/go-m1cpu v0.1.6 // indirect
 	github.com/sourcegraph/conc v0.3.0 // indirect
 	github.com/spf13/afero v1.11.0 // indirect
 	github.com/spf13/cast v1.6.0 // indirect
@@ -118,8 +120,11 @@ require (
 	github.com/templexxx/cpu v0.1.0 // indirect
 	github.com/templexxx/xorsimd v0.4.2 // indirect
 	github.com/tjfoc/gmsm v1.4.1 // indirect
+	github.com/tklauser/go-sysconf v0.3.12 // indirect
+	github.com/tklauser/numcpus v0.6.1 // indirect
 	github.com/twitchyliquid64/golang-asm v0.15.1 // indirect
 	github.com/ugorji/go/codec v1.2.12 // indirect
+	github.com/yusufpapurcu/wmi v1.2.4 // indirect
 	go.uber.org/mock v0.5.0 // indirect
 	go.uber.org/multierr v1.11.0 // indirect
 	golang.org/x/arch v0.8.0 // indirect

go-gost/x/go.sum

@@ -65,6 +65,8 @@ github.com/go-gost/tls-dissector v0.1.1 h1:2zUOTPzCQAUQ54Rpy0UEi3JPMQSYsIFSeFeKr
 github.com/go-gost/tls-dissector v0.1.1/go.mod h1:/9QfdewqmHdaE362Hv5nDaSWLx3pCmtD870d6GaquXs=
 github.com/go-logr/logr v1.4.2 h1:6pFjapn8bFcIbiKo3XT4j/BhANplGihG6tvd+8rYgrY=
 github.com/go-logr/logr v1.4.2/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
+github.com/go-ole/go-ole v1.2.6 h1:/Fpf6oFPoeFik9ty7siob0G6Ke8QvQEuVcuChpwXzpY=
+github.com/go-ole/go-ole v1.2.6/go.mod h1:pprOEPIfldk/42T2oK7lQ4v4JSDwmV0As9GaiUsvbm0=
 github.com/go-playground/assert/v2 v2.2.0 h1:JvknZsQTYeFEAhQwI4qEt9cyV5ONwRHC+lYKSsYSR8s=
 github.com/go-playground/assert/v2 v2.2.0/go.mod h1:VDjEfimB/XKnb+ZQfWdccd7VUvScMdVu0Titje2rxJ4=
 github.com/go-playground/locales v0.14.1 h1:EWaQ/wswjilfKLTECiXz7Rh+3BjFhfDFKv/oXslEjJA=
@@ -102,6 +104,7 @@ github.com/google/go-cmp v0.2.0/go.mod h1:oXzfMopK8JAjlY9xF4vHSVASa0yLyX7SntLO5a
 github.com/google/go-cmp v0.3.0/go.mod h1:8QqcDgzrUqlUb/G2PQTWiueGozuR1884gddMywk6iLU=
 github.com/google/go-cmp v0.3.1/go.mod h1:8QqcDgzrUqlUb/G2PQTWiueGozuR1884gddMywk6iLU=
 github.com/google/go-cmp v0.4.0/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
+github.com/google/go-cmp v0.5.6/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
 github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
 github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
 github.com/google/gofuzz v1.0.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=
@@ -133,6 +136,8 @@ github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
 github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
 github.com/leodido/go-urn v1.4.0 h1:WT9HwE9SGECu3lg4d/dIA+jxlljEa1/ffXKmRjqdmIQ=
 github.com/leodido/go-urn v1.4.0/go.mod h1:bvxc+MVxLKB4z00jd1z+Dvzr47oO32F/QSNjSBOlFxI=
+github.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0 h1:6E+4a0GO5zZEnZ81pIr0yLvtUWk2if982qA3F3QD6H4=
+github.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0/go.mod h1:zJYVVT2jmtg6P3p1VtQj7WsuWi/y4VnjVBn7F8KPB3I=
 github.com/magiconair/properties v1.8.7 h1:IeQXZAiQcpL9mgcAe1Nu6cX9LLw6ExEHKjN0VQdvPDY=
 github.com/magiconair/properties v1.8.7/go.mod h1:Dhd985XPs7jluiymwWYZ0G4Z61jb3vdS329zhj2hYo0=
 github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
@@ -175,6 +180,8 @@ github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINE
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
 github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/power-devops/perfstat v0.0.0-20210106213030-5aafc221ea8c h1:ncq/mPwQF4JjgDlrVEn3C11VoGHZN7m8qihwgMEtzYw=
+github.com/power-devops/perfstat v0.0.0-20210106213030-5aafc221ea8c/go.mod h1:OmDBASR4679mdNQnz2pUhc2G8CO2JrUAVFDRBDP/hJE=
 github.com/prometheus/client_golang v1.19.1 h1:wZWJDwK+NameRJuPGDhlnFgx8e8HN3XHQeLaYJFJBOE=
 github.com/prometheus/client_golang v1.19.1/go.mod h1:mP78NwGzrVks5S2H6ab8+ZZGJLZUq1hoULYBAYBw1Ho=
 github.com/prometheus/client_model v0.0.0-20190812154241-14fe0d1b01d4/go.mod h1:xMI15A0UPsDsEKsMN9yxemIoYk6Tm2C1GtYGdfGttqA=
@@ -204,7 +211,12 @@ github.com/shadowsocks/go-shadowsocks2 v0.1.5 h1:PDSQv9y2S85Fl7VBeOMF9StzeXZyK1H
 github.com/shadowsocks/go-shadowsocks2 v0.1.5/go.mod h1:AGGpIoek4HRno4xzyFiAtLHkOpcoznZEkAccaI/rplM=
 github.com/shadowsocks/shadowsocks-go v0.0.0-20200409064450-3e585ff90601 h1:XU9hik0exChEmY92ALW4l9WnDodxLVS9yOSNh2SizaQ=
 github.com/shadowsocks/shadowsocks-go v0.0.0-20200409064450-3e585ff90601/go.mod h1:mttDPaeLm87u74HMrP+n2tugXvIKWcwff/cqSX0lehY=
+github.com/shirou/gopsutil/v3 v3.24.5 h1:i0t8kL+kQTvpAYToeuiVk3TgDeKOFioZO3Ztz/iZ9pI=
 github.com/shirou/gopsutil/v3 v3.24.5/go.mod h1:bsoOS1aStSs9ErQ1WWfxllSeS1K5D+U30r2NfcubMVk=
+github.com/shoenig/go-m1cpu v0.1.6 h1:nxdKQNcEB6vzgA2E2bvzKIYRuNj7XNJ4S/aRSwKzFtM=
+github.com/shoenig/go-m1cpu v0.1.6/go.mod h1:1JJMcUBvfNwpq05QDQVAnx3gUHr9IYF7GNg9SUEw2VQ=
+github.com/shoenig/test v0.6.4 h1:kVTaSd7WLz5WZ2IaoM0RSzRsUD+m8wRR+5qvntpn4LU=
+github.com/shoenig/test v0.6.4/go.mod h1:byHiCGXqrVaflBLAMq/srcZIHynQPQgeyvkvXnjqq0k=
 github.com/sirupsen/logrus v1.7.0/go.mod h1:yWOB1SBYBC5VeMP7gHvWumXLIWorT60ONWic61uBYv0=
 github.com/sirupsen/logrus v1.8.1 h1:dJKuHgqk1NNQlqoA6BTlM1Wf9DOH3NBjQyu0h9+AZZE=
 github.com/sirupsen/logrus v1.8.1/go.mod h1:yWOB1SBYBC5VeMP7gHvWumXLIWorT60ONWic61uBYv0=
@@ -244,6 +256,10 @@ github.com/templexxx/xorsimd v0.4.2 h1:ocZZ+Nvu65LGHmCLZ7OoCtg8Fx8jnHKK37SjvngUo
 github.com/templexxx/xorsimd v0.4.2/go.mod h1:HgwaPoDREdi6OnULpSfxhzaiiSUY4Fi3JPn1wpt28NI=
 github.com/tjfoc/gmsm v1.4.1 h1:aMe1GlZb+0bLjn+cKTPEvvn9oUEBlJitaZiiBwsbgho=
 github.com/tjfoc/gmsm v1.4.1/go.mod h1:j4INPkHWMrhJb38G+J6W4Tw0AbuN8Thu3PbdVYhVcTE=
+github.com/tklauser/go-sysconf v0.3.12 h1:0QaGUFOdQaIVdPgfITYzaTegZvdCjmYO52cSFAEVmqU=
+github.com/tklauser/go-sysconf v0.3.12/go.mod h1:Ho14jnntGE1fpdOqQEEaiKRpvIavV0hSfmBq8nJbHYI=
+github.com/tklauser/numcpus v0.6.1 h1:ng9scYS7az0Bk4OZLvrNXNSAO2Pxr1XXRAPyjhIx+Fk=
+github.com/tklauser/numcpus v0.6.1/go.mod h1:1XfjsgE2zo8GVw7POkMbHENHzVg3GzmoZ9fESEdAacY=
 github.com/twitchyliquid64/golang-asm v0.15.1 h1:SU5vSMR7hnwNxj24w34ZyCi/FmDZTkS4MhqMhdFk5YI=
 github.com/twitchyliquid64/golang-asm v0.15.1/go.mod h1:a1lVb/DtPvCB8fslRZhAngC2+aY1QWCk3Cedj/Gdt08=
 github.com/ugorji/go/codec v1.2.12 h1:9LC83zGrHhuUA9l16C9AHXAqEV/2wBQ4nkvumAE65EE=
@@ -266,6 +282,8 @@ github.com/xtaci/tcpraw v1.2.25/go.mod h1:dKyZ2V75s0cZ7cbgJYdxPvms7af0joIeOyx1Gg
 github.com/yl2chen/cidranger v1.0.2 h1:lbOWZVCG1tCRX4u24kuM1Tb4nHqWkDxwLdoS+SevawU=
 github.com/yl2chen/cidranger v1.0.2/go.mod h1:9U1yz7WPYDwf0vpNWFaeRh0bjwz5RVgRy/9UEQfHl0g=
 github.com/yuin/goldmark v1.4.13/go.mod h1:6yULJ656Px+3vBD8DxQVa3kxgyrAnzto9xy5taEt/CY=
+github.com/yusufpapurcu/wmi v1.2.4 h1:zFUKzehAFReQwLys1b/iSMl+JQGSCSjtVqQn9bBrPo0=
+github.com/yusufpapurcu/wmi v1.2.4/go.mod h1:SBZ9tNy3G9/m5Oi98Zks0QjeHVDvuK0qfxQmPyzfmi0=
 github.com/zalando/go-keyring v0.2.4 h1:wi2xxTqdiwMKbM6TWwi+uJCG/Tum2UV0jqaQhCa9/68=
 github.com/zalando/go-keyring v0.2.4/go.mod h1:HL4k+OXQfJUWaMnqyuSOc0drfGPX2b51Du6K+MRgZMk=
 go.uber.org/mock v0.5.0 h1:KAMbZvZPyBPWgD14IrIQ38QCyjwpvVVV6K/bHl1IwQU=
@@ -321,15 +339,19 @@ golang.org/x/sys v0.0.0-20180830151530-49385e6e1522/go.mod h1:STP8DvDyc/dI5b8T5h
 golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
 golang.org/x/sys v0.0.0-20190412213103-97732733099d/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20190606203320-7fc4e5ec1444/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20190916202348-b4ddaad3f8a3/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20191026070338-33540a1f6037/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20200930185726-fdedc70b468f/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20201204225414-ed752295db88/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20210615035016-665e8c7367d1/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20220520151302-bc2c85ada10a/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20220722155257-8c9f86f7a55f/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.4.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.5.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.8.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.11.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.28.0 h1:Fksou7UEQUWlKvIdsqzJmUmCX3cZuD2+P3XyyzwMhlA=
 golang.org/x/sys v0.28.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
 golang.org/x/term v0.0.0-20201117132131-f5c789dd3221/go.mod h1:Nr5EML6q2oocZ2LXRh80K7BxOlk5/8JxuGnuhpl+muw=

go-gost/x/limiter/traffic/traffic.go

@@ -136,6 +136,9 @@ func (l *trafficLimiter) In(ctx context.Context, key string, opts ...limiter.Opt
 		return nil
 
 	case limiter.ScopeClient:
+		if lim, ok := l.inLimits.Get(key); ok && lim != nil {
+			return lim.(traffic.Limiter)
+		}
 		return nil
 
 	case limiter.ScopeConn:
@@ -215,6 +218,9 @@ func (l *trafficLimiter) Out(ctx context.Context, key string, opts ...limiter.Op
 		return nil
 
 	case limiter.ScopeClient:
+		if lim, ok := l.outLimits.Get(key); ok && lim != nil {
+			return lim.(traffic.Limiter)
+		}
 		return nil
 
 	case limiter.ScopeConn:

go-gost/x/service/service.go

@@ -54,10 +54,10 @@ var needWrap = false
 
 // SetProtocolBlock sets protocol blocking switches and recomputes wrapper need
 func SetProtocolBlock(httpOn int, tlsOn int, socksOn int) {
-    isHttp = httpOn
-    isTls = tlsOn
-    isSocks = socksOn
-    needWrap = isTls+isSocks+isHttp > 0
+	isHttp = httpOn
+	isTls = tlsOn
+	isSocks = socksOn
+	needWrap = isTls+isSocks+isHttp > 0
 }
 
 type Option func(opts *options)
@@ -292,7 +292,9 @@ func (s *defaultService) Serve() error {
 			}
 
 			if err := s.handler.Handle(ctx, conn); err != nil {
-				log.Error(err)
+				if !errors.Is(err, net.ErrClosed) {
+					log.Error(err)
+				}
 				if v := xmetrics.GetCounter(xmetrics.MetricServiceHandlerErrorsCounter,
 					metrics.Labels{"service": s.name, "client": clientIP}); v != nil {
 					v.Inc()
@@ -403,12 +405,12 @@ func (s *defaultService) observeStats(ctx context.Context) {
 						TotalErrs:    st.Get(stats.KindTotalErrs),
 					},
 				}
-				
+
 				// 将流量累积到全局管理器，而不是立即上报
 				if outputBytes > 0 || inputBytes > 0 {
 					globalManager := GetGlobalTrafficManager()
 					globalManager.AddTraffic(s.name, int64(outputBytes), int64(inputBytes))
-					
+
 					// 立即重置流量计数（因为已经记录到全局管理器中）
 					if xstats, ok := st.(*xstats.Stats); ok {
 						xstats.ResetTraffic(st.Get(stats.KindInputBytes)-inputBytes, st.Get(stats.KindOutputBytes)-outputBytes)

go-gost/x/socket/AGENTS.md

@@ -0,0 +1,38 @@
+# GOST SOCKET KNOWLEDGE BASE
+
+**Generated:** Sun Feb 15 2026
+
+## OVERVIEW
+WebSocket reporter and socket utilities for panel integration.
+**Stack:** Go, GOST core, gorilla/websocket.
+
+## STRUCTURE
+```
+socket/
+├── websocket_reporter.go  # Agent-to-panel telemetry (1504 LOC)
+├── service.go             # Socket service orchestration (534 LOC)
+├── socket.go              # Core socket interface
+├── udp.go                 # UDP socket handling
+├── packet.go              # Packet framing
+└── packetconn.go          # Packet connection wrapper
+```
+
+## WHERE TO LOOK
+| Task | Location | Notes |
+|------|----------|-------|
+| **Panel Reporting** | `websocket_reporter.go` | Real-time system info (CPU, mem, uptime) every 2s |
+| **Command Handling** | `websocket_reporter.go` | Processes `AddService`, `UpgradeAgent`, etc. |
+
+## CONVENTIONS
+- Inherits from parent `go-gost/x/` conventions.
+- Low-level network primitives.
+- All panel communication is AES-encrypted using node `secret`.
+
+## ANTI-PATTERNS
+- DO NOT EDIT generated protobuf.
+
+## COMMANDS
+```bash
+cd go-gost
+go test ./x/socket/...
+```

go-gost/x/socket/chain.go

@@ -43,8 +43,8 @@ func updateChain(req updateChainRequest) error {
 
 	name := strings.TrimSpace(req.Chain)
 
-	if !registry.ChainRegistry().IsRegistered(name) {
-		return errors.New("chain " + name + " not found")
+	if registry.ChainRegistry().IsRegistered(name) {
+		registry.ChainRegistry().Unregister(name)
 	}
 
 	req.Data.Name = name
@@ -54,19 +54,22 @@ func updateChain(req updateChainRequest) error {
 		return errors.New("create chain " + name + " failed: " + err.Error())
 	}
 
-	registry.ChainRegistry().Unregister(name)
-
 	if err := registry.ChainRegistry().Register(name, v); err != nil {
 		return errors.New("chain " + name + " already exists")
 	}
 
 	config.OnUpdate(func(c *config.Config) error {
+		found := false
 		for i := range c.Chains {
 			if c.Chains[i].Name == name {
 				c.Chains[i] = &req.Data
+				found = true
 				break
 			}
 		}
+		if !found {
+			c.Chains = append(c.Chains, &req.Data)
+		}
 		return nil
 	})
 
@@ -77,10 +80,9 @@ func deleteChain(req deleteChainRequest) error {
 
 	name := strings.TrimSpace(req.Chain)
 
-	if !registry.ChainRegistry().IsRegistered(name) {
-		return errors.New("chain " + name + " not found")
+	if registry.ChainRegistry().IsRegistered(name) {
+		registry.ChainRegistry().Unregister(name)
 	}
-	registry.ChainRegistry().Unregister(name)
 
 	config.OnUpdate(func(c *config.Config) error {
 		chains := c.Chains

go-gost/x/socket/config.go

@@ -10,7 +10,7 @@ import (
 // configMutex 保护配置文件的并发写入
 var configMutex sync.Mutex
 
-func saveConfig() {
+func saveConfig() error {
 	configMutex.Lock()
 	defer configMutex.Unlock()
 
@@ -18,14 +18,13 @@ func saveConfig() {
 
 	f, err := os.Create(file)
 	if err != nil {
-		return
+		return err
 	}
 	defer f.Close()
 
 	if err := config.Global().Write(f, "json"); err != nil {
-
-		return
+		return err
 	}
 
-	return
+	return nil
 }

go-gost/x/socket/limiter.go

@@ -37,27 +37,30 @@ func updateLimiter(req updateLimiterRequest) error {
 
 	name := strings.TrimSpace(req.Limiter)
 
-	if !registry.TrafficLimiterRegistry().IsRegistered(name) {
-		return errors.New("limiter " + name + " not found")
+	if registry.TrafficLimiterRegistry().IsRegistered(name) {
+		registry.TrafficLimiterRegistry().Unregister(name)
 	}
 
 	req.Data.Name = name
 
 	v := parser.ParseTrafficLimiter(&req.Data)
 
-	registry.TrafficLimiterRegistry().Unregister(name)
-
 	if err := registry.TrafficLimiterRegistry().Register(name, v); err != nil {
 		return errors.New("limiter " + name + " already exists")
 	}
 
 	config.OnUpdate(func(c *config.Config) error {
+		found := false
 		for i := range c.Limiters {
 			if c.Limiters[i].Name == name {
 				c.Limiters[i] = &req.Data
+				found = true
 				break
 			}
 		}
+		if !found {
+			c.Limiters = append(c.Limiters, &req.Data)
+		}
 		return nil
 	})
 
@@ -68,10 +71,9 @@ func deleteLimiter(req deleteLimiterRequest) error {
 
 	name := strings.TrimSpace(req.Limiter)
 
-	if !registry.TrafficLimiterRegistry().IsRegistered(name) {
-		return errors.New("limiter " + name + " not found")
+	if registry.TrafficLimiterRegistry().IsRegistered(name) {
+		registry.TrafficLimiterRegistry().Unregister(name)
 	}
-	registry.TrafficLimiterRegistry().Unregister(name)
 
 	config.OnUpdate(func(c *config.Config) error {
 		limiteres := c.Limiters

go-gost/x/socket/service.go

@@ -87,36 +87,32 @@ func updateServices(req updateServicesRequest) error {
 		return errors.New("services list cannot be empty")
 	}
 
-	// 第一阶段：验证所有服务存在
-	for _, serviceConfig := range req.Data {
-		name := strings.TrimSpace(serviceConfig.Name)
+	// 第一阶段：验证所有服务名称有效性
+	for i := range req.Data {
+		name := strings.TrimSpace(req.Data[i].Name)
 		if name == "" {
 			return errors.New("service name is required")
 		}
-		serviceConfig.Name = name
-
-		old := registry.ServiceRegistry().Get(name)
-		if old == nil {
-			return errors.New("service " + name + " not found")
-		}
+		req.Data[i].Name = name
 	}
 
-	// 第二阶段：按照原来的updateService逻辑，逐个更新服务
-	for _, serviceConfig := range req.Data {
-		name := strings.TrimSpace(serviceConfig.Name)
-		serviceConfig.Name = name
+	// 第二阶段：逐个更新服务（Upsert模式：存在则更新，不存在则创建）
+	for i := range req.Data {
+		serviceConfig := &req.Data[i]
+		name := serviceConfig.Name
 
 		// 1. 获取旧服务
 		old := registry.ServiceRegistry().Get(name)
 
-		// 2. 关闭旧服务
-		old.Close()
-
-		// 3. 从注册表移除旧服务
-		registry.ServiceRegistry().Unregister(name)
+		// 2. 关闭旧服务 (如果存在)
+		if old != nil {
+			old.Close()
+			// 3. 从注册表移除旧服务
+			registry.ServiceRegistry().Unregister(name)
+		}
 
 		// 4. 解析新服务配置
-		svc, err := parser.ParseService(&serviceConfig)
+		svc, err := parser.ParseService(serviceConfig)
 		if err != nil {
 			return errors.New("create service " + name + " failed: " + err.Error())
 		}
@@ -133,13 +129,20 @@ func updateServices(req updateServicesRequest) error {
 
 	// 第三阶段：更新配置
 	config.OnUpdate(func(c *config.Config) error {
-		for _, serviceConfig := range req.Data {
-			for i := range c.Services {
-				if c.Services[i].Name == serviceConfig.Name {
-					c.Services[i] = &serviceConfig
+		for i := range req.Data {
+			// 创建副本以确保指针安全
+			cfgCopy := req.Data[i]
+			found := false
+			for j := range c.Services {
+				if c.Services[j].Name == cfgCopy.Name {
+					c.Services[j] = &cfgCopy
+					found = true
 					break
 				}
 			}
+			if !found {
+				c.Services = append(c.Services, &cfgCopy)
+			}
 		}
 		return nil
 	})
@@ -158,22 +161,22 @@ func deleteServices(req deleteServicesRequest) error {
 		name    string
 		service service.Service
 	}
+	var namesToRemove []string
 
 	for _, serviceName := range req.Services {
 		name := strings.TrimSpace(serviceName)
 		if name == "" {
 			return errors.New("service name is required")
 		}
+		namesToRemove = append(namesToRemove, name)
 
 		svc := registry.ServiceRegistry().Get(name)
-		if svc == nil {
-			return errors.New("service " + name + " not found")
+		if svc != nil {
+			servicesToDelete = append(servicesToDelete, struct {
+				name    string
+				service service.Service
+			}{name, svc})
 		}
-
-		servicesToDelete = append(servicesToDelete, struct {
-			name    string
-			service service.Service
-		}{name, svc})
 	}
 
 	// 第二阶段：删除所有服务
@@ -181,6 +184,12 @@ func deleteServices(req deleteServicesRequest) error {
 		registry.ServiceRegistry().Unregister(std.name)
 		std.service.Close()
 	}
+	// 确保所有请求删除的服务都从注册表中移除（即使之前未找到实例）
+	for _, name := range namesToRemove {
+		if registry.ServiceRegistry().IsRegistered(name) {
+			registry.ServiceRegistry().Unregister(name)
+		}
+	}
 
 	// 第三阶段：更新配置
 	config.OnUpdate(func(c *config.Config) error {
@@ -188,8 +197,8 @@ func deleteServices(req deleteServicesRequest) error {
 		c.Services = nil
 		for _, s := range services {
 			shouldDelete := false
-			for _, std := range servicesToDelete {
-				if s.Name == std.name {
+			for _, name := range namesToRemove {
+				if s.Name == name {
 					shouldDelete = true
 					break
 				}

go-gost/x/socket/websocket_reporter.go

@@ -4,10 +4,17 @@ import (
 	"bytes"
 	"compress/gzip"
 	"context"
+	"crypto/sha256"
+	"encoding/hex"
 	"encoding/json"
 	"fmt"
+	"io"
 	"net"
+	"net/http"
 	"net/url"
+	"os"
+	"os/exec"
+	"runtime"
 	"strconv"
 	"strings"
 	"sync" // 新增：用于管理连接状态的互斥锁
@@ -21,7 +28,6 @@ import (
 	"github.com/shirou/gopsutil/v3/host"
 	"github.com/shirou/gopsutil/v3/mem"
 	psnet "github.com/shirou/gopsutil/v3/net"
-	"os"
 )
 
 // SystemInfo 系统信息结构体
@@ -85,6 +91,11 @@ type TcpPingResponse struct {
 	RequestId    string  `json:"requestId,omitempty"`
 }
 
+const (
+	reporterReadWait  = 60 * time.Second
+	reporterWriteWait = 5 * time.Second
+)
+
 type WebSocketReporter struct {
 	url            string
 	addr           string // 保存服务器地址
@@ -237,6 +248,14 @@ func (w *WebSocketReporter) connect() error {
 
 	w.conn = conn
 	w.connected = true
+	_ = conn.SetReadDeadline(time.Now().Add(reporterReadWait))
+	conn.SetPingHandler(func(appData string) error {
+		_ = conn.SetReadDeadline(time.Now().Add(reporterReadWait))
+		return conn.WriteControl(websocket.PongMessage, []byte(appData), time.Now().Add(reporterWriteWait))
+	})
+	conn.SetPongHandler(func(string) error {
+		return conn.SetReadDeadline(time.Now().Add(reporterReadWait))
+	})
 
 	// 设置关闭处理器来检测连接状态
 	w.conn.SetCloseHandler(func(code int, text string) error {
@@ -377,7 +396,7 @@ func (w *WebSocketReporter) receiveMessages() {
 			}
 
 			// 设置读取超时
-			conn.SetReadDeadline(time.Now().Add(30 * time.Second))
+			conn.SetReadDeadline(time.Now().Add(reporterReadWait))
 
 			messageType, message, err := conn.ReadMessage()
 			if err != nil {
@@ -466,9 +485,8 @@ func (w *WebSocketReporter) handleReceivedMessage(messageType int, message []byt
 			}
 
 			if cmdMsg.Type != "call" {
-				// TcpPing 诊断命令异步执行，避免阻塞其他命令
 				// 其他状态变更命令保持同步，确保顺序执行
-				if cmdMsg.Type == "TcpPing" {
+				if cmdMsg.Type == "TcpPing" || cmdMsg.Type == "UpgradeAgent" || cmdMsg.Type == "RollbackAgent" {
 					go w.routeCommand(cmdMsg)
 				} else {
 					w.routeCommand(cmdMsg)
@@ -483,9 +501,8 @@ func (w *WebSocketReporter) handleReceivedMessage(messageType int, message []byt
 				return
 			}
 			if cmdMsg.Type != "call" {
-				// TcpPing 诊断命令异步执行，避免阻塞其他命令
 				// 其他状态变更命令保持同步，确保顺序执行
-				if cmdMsg.Type == "TcpPing" {
+				if cmdMsg.Type == "TcpPing" || cmdMsg.Type == "UpgradeAgent" || cmdMsg.Type == "RollbackAgent" {
 					go w.routeCommand(cmdMsg)
 				} else {
 					w.routeCommand(cmdMsg)
@@ -579,6 +596,18 @@ func (w *WebSocketReporter) routeCommand(cmd CommandMessage) {
 		response.Type = "SetProtocolResponse"
 		needSaveConfig = true
 
+	// 升级 Agent 命令（异步执行，不需要保存配置）
+	case "UpgradeAgent":
+		err = w.handleUpgradeAgent(cmd.Data)
+		response.Type = "UpgradeAgentResponse"
+		// needSaveConfig = false (默认值)
+
+	// 回退 Agent 到旧版本
+	case "RollbackAgent":
+		err = w.handleRollbackAgent(cmd.Data)
+		response.Type = "RollbackAgentResponse"
+		// needSaveConfig = false (默认值)
+
 	default:
 		err = fmt.Errorf("未知命令类型: %s", cmd.Type)
 		response.Type = "UnknownCommandResponse"
@@ -586,7 +615,16 @@ func (w *WebSocketReporter) routeCommand(cmd CommandMessage) {
 
 	// 只有状态变更命令才保存配置
 	if needSaveConfig {
-		saveConfig()
+		if saveErr := saveConfig(); saveErr != nil {
+			fmt.Printf("❌ 保存配置失败: %v\n", saveErr)
+			if err == nil {
+				err = fmt.Errorf("保存配置失败: %v", saveErr)
+			} else {
+				err = fmt.Errorf("%v; 保存配置失败: %v", err, saveErr)
+			}
+		} else {
+			fmt.Println("✅ 配置已保存到 gost.json")
+		}
 	}
 
 	// 发送响应
@@ -872,6 +910,186 @@ func (w *WebSocketReporter) handleSetProtocol(data interface{}) error {
 	return nil
 }
 
+// sendUpgradeProgress 通过 WS 发送升级进度消息
+func (w *WebSocketReporter) sendUpgradeProgress(stage string, percent int, message string) {
+	response := CommandResponse{
+		Type:    "UpgradeProgress",
+		Success: true,
+		Message: message,
+		Data: map[string]interface{}{
+			"stage":   stage,
+			"percent": percent,
+		},
+	}
+	w.sendResponse(response)
+}
+
+func (w *WebSocketReporter) handleUpgradeAgent(data interface{}) error {
+	jsonData, err := json.Marshal(data)
+	if err != nil {
+		return fmt.Errorf("序列化数据失败: %v", err)
+	}
+
+	var req struct {
+		DownloadURL string `json:"downloadUrl"`
+		ChecksumURL string `json:"checksumUrl"`
+	}
+	if err := json.Unmarshal(jsonData, &req); err != nil {
+		return fmt.Errorf("解析升级参数失败: %v", err)
+	}
+	if strings.TrimSpace(req.DownloadURL) == "" {
+		return fmt.Errorf("下载地址不能为空")
+	}
+
+	// 替换架构占位符
+	downloadURL := strings.ReplaceAll(req.DownloadURL, "{ARCH}", runtime.GOARCH)
+	checksumURL := strings.ReplaceAll(req.ChecksumURL, "{ARCH}", runtime.GOARCH)
+
+	w.sendUpgradeProgress("downloading", 0, "开始下载升级包...")
+	fmt.Printf("📦 开始下载升级包: %s\n", downloadURL)
+
+	// 下载新版本二进制
+	const binaryPath = "/etc/flux_agent/flux_agent"
+	tmpPath := binaryPath + ".new"
+	backupPath := binaryPath + ".old"
+
+	resp, err := http.Get(downloadURL)
+	if err != nil {
+		return fmt.Errorf("下载升级包失败: %v", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		return fmt.Errorf("下载升级包失败, HTTP状态码: %d", resp.StatusCode)
+	}
+
+	outFile, err := os.Create(tmpPath)
+	if err != nil {
+		return fmt.Errorf("创建临时文件失败: %v", err)
+	}
+
+	// 带进度的下载
+	totalSize := resp.ContentLength
+	var downloaded int64
+	buf := make([]byte, 32*1024)
+	lastPercent := 0
+	hasher := sha256.New()
+
+	for {
+		n, readErr := resp.Body.Read(buf)
+		if n > 0 {
+			if _, wErr := outFile.Write(buf[:n]); wErr != nil {
+				outFile.Close()
+				os.Remove(tmpPath)
+				return fmt.Errorf("写入升级包失败: %v", wErr)
+			}
+			hasher.Write(buf[:n])
+			downloaded += int64(n)
+			if totalSize > 0 {
+				percent := int(downloaded * 100 / totalSize)
+				if percent-lastPercent >= 10 {
+					lastPercent = percent
+					w.sendUpgradeProgress("downloading", percent, fmt.Sprintf("下载中... %d%%", percent))
+				}
+			}
+		}
+		if readErr != nil {
+			if readErr == io.EOF {
+				break
+			}
+			outFile.Close()
+			os.Remove(tmpPath)
+			return fmt.Errorf("读取升级包失败: %v", readErr)
+		}
+	}
+	outFile.Close()
+
+	if downloaded == 0 {
+		os.Remove(tmpPath)
+		return fmt.Errorf("下载的升级包为空")
+	}
+
+	w.sendUpgradeProgress("downloading", 100, fmt.Sprintf("下载完成 (%d bytes)", downloaded))
+
+	// Checksum 校验
+	if checksumURL != "" {
+		w.sendUpgradeProgress("verifying", 0, "校验文件完整性...")
+		checksumResp, err := http.Get(checksumURL)
+		if err == nil {
+			defer checksumResp.Body.Close()
+			if checksumResp.StatusCode == http.StatusOK {
+				checksumBody, err := io.ReadAll(checksumResp.Body)
+				if err == nil {
+					// 格式: "<hash>  <filename>" 或 "<hash>"
+					expectedHash := strings.TrimSpace(strings.Split(string(checksumBody), " ")[0])
+					actualHash := hex.EncodeToString(hasher.Sum(nil))
+					if !strings.EqualFold(expectedHash, actualHash) {
+						os.Remove(tmpPath)
+						return fmt.Errorf("校验失败: 期望 %s, 实际 %s", expectedHash, actualHash)
+					}
+					fmt.Printf("✅ Checksum 校验通过: %s\n", actualHash)
+				}
+			}
+		}
+		w.sendUpgradeProgress("verifying", 100, "校验通过")
+	}
+
+	if err := os.Chmod(tmpPath, 0755); err != nil {
+		os.Remove(tmpPath)
+		return fmt.Errorf("设置执行权限失败: %v", err)
+	}
+
+	// 备份旧版本
+	w.sendUpgradeProgress("installing", 50, "备份旧版本...")
+	if _, err := os.Stat(binaryPath); err == nil {
+		// 复制旧文件作为备份（不用 rename，因为可能正在运行）
+		oldData, err := os.ReadFile(binaryPath)
+		if err == nil {
+			_ = os.WriteFile(backupPath, oldData, 0755)
+			fmt.Println("📦 旧版本已备份到", backupPath)
+		}
+	}
+
+	w.sendUpgradeProgress("installing", 80, "准备重启...")
+	fmt.Printf("✅ 升级包下载完成 (%d bytes), 准备重启...\n", downloaded)
+
+	// 执行重启脚本
+	// 使用 systemd-run 在独立的 transient unit 中运行重启脚本，
+	// 避免 systemctl stop 杀死 flux_agent cgroup 内所有进程（包括此脚本自身）导致 mv 未执行。
+	script := fmt.Sprintf("sleep 1 && systemctl stop flux_agent && mv %s %s && systemctl start flux_agent", tmpPath, binaryPath)
+	cmd := exec.Command("systemd-run", "--quiet", "/bin/sh", "-c", script)
+	if err := cmd.Start(); err != nil {
+		os.Remove(tmpPath)
+		return fmt.Errorf("启动重启脚本失败: %v", err)
+	}
+
+	w.sendUpgradeProgress("installing", 100, "重启中...")
+	fmt.Println("🔄 重启脚本已启动, Agent 将在 1 秒后重启...")
+	return nil
+}
+
+func (w *WebSocketReporter) handleRollbackAgent(data interface{}) error {
+	const binaryPath = "/etc/flux_agent/flux_agent"
+	backupPath := binaryPath + ".old"
+
+	// 检查备份文件是否存在
+	if _, err := os.Stat(backupPath); os.IsNotExist(err) {
+		return fmt.Errorf("没有可用的备份文件，无法回退")
+	}
+
+	fmt.Println("🔄 开始回退到旧版本...")
+
+	// 执行回退脚本（同升级逻辑，使用 systemd-run 避免 cgroup 问题）
+	script := fmt.Sprintf("sleep 1 && systemctl stop flux_agent && cp %s %s && systemctl start flux_agent", backupPath, binaryPath)
+	cmd := exec.Command("systemd-run", "--quiet", "/bin/sh", "-c", script)
+	if err := cmd.Start(); err != nil {
+		return fmt.Errorf("启动回退脚本失败: %v", err)
+	}
+
+	fmt.Println("🔄 回退脚本已启动, Agent 将在 1 秒后重启...")
+	return nil
+}
+
 // updateLocalConfigJSON 将 http/tls/socks 写入工作目录下的 config.json
 func updateLocalConfigJSON(httpVal int, tlsVal int, socksVal int) error {
 	path := "config.json"

install.sh

@@ -3,6 +3,9 @@
 # GitHub repo used for release downloads
 REPO="Sagit-chu/flux-panel"
 
+# 固定版本号（Release 构建时自动填充，留空则获取最新版）
+PINNED_VERSION=""
+
 # 获取系统架构
 get_architecture() {
     ARCH=$(uname -m)
@@ -22,16 +25,10 @@ get_architecture() {
 # 安装目录
 INSTALL_DIR="/etc/flux_agent"
 
-# 识别国家（用于镜像加速）
-COUNTRY=$(curl -s https://ipinfo.io/country)
-
+# 镜像加速（所有下载均经过镜像源，以支持 IPv6）
 maybe_proxy_url() {
   local url="$1"
-  if [ "$COUNTRY" = "CN" ]; then
-    echo "https://ghfast.top/${url}"
-  else
-    echo "$url"
-  fi
+  echo "https://gcode.hostcentral.cc/${url}"
 }
 
 resolve_latest_release_tag() {
@@ -40,39 +37,19 @@ resolve_latest_release_tag() {
   latest_url="https://github.com/${REPO}/releases/latest"
   api_url="https://api.github.com/repos/${REPO}/releases/latest"
 
-  # 方式1：跟随重定向，取最终 URL 的最后一段作为 tag
-  effective_url=$(curl -fsSL -o /dev/null -w '%{url_effective}' -L "$latest_url" 2>/dev/null || true)
+  effective_url=$(curl -fsSL -o /dev/null -w '%{url_effective}' -L "$(maybe_proxy_url "$latest_url")" 2>/dev/null || true)
   tag="${effective_url##*/}"
   if [[ -n "$tag" && "$tag" != "latest" ]]; then
     echo "$tag"
     return 0
   fi
 
-  # CN 环境下可尝试通过镜像访问（不影响非 CN）
-  if [ "$COUNTRY" = "CN" ]; then
-    effective_url=$(curl -fsSL -o /dev/null -w '%{url_effective}' -L "$(maybe_proxy_url "$latest_url")" 2>/dev/null || true)
-    tag="${effective_url##*/}"
-    if [[ -n "$tag" && "$tag" != "latest" ]]; then
-      echo "$tag"
-      return 0
-    fi
-  fi
-
-  # 方式2：GitHub API（无需 jq）
-  api_tag=$(curl -fsSL "$api_url" 2>/dev/null | grep -m1 '"tag_name"' | sed -E 's/.*"tag_name"[[:space:]]*:[[:space:]]*"([^"]+)".*/\1/' || true)
+  api_tag=$(curl -fsSL "$(maybe_proxy_url "$api_url")" 2>/dev/null | grep -m1 '"tag_name"' | sed -E 's/.*"tag_name"[[:space:]]*:[[:space:]]*"([^"]+)".*/\1/' || true)
   if [[ -n "$api_tag" ]]; then
     echo "$api_tag"
     return 0
   fi
 
-  if [ "$COUNTRY" = "CN" ]; then
-    api_tag=$(curl -fsSL "$(maybe_proxy_url "$api_url")" 2>/dev/null | grep -m1 '"tag_name"' | sed -E 's/.*"tag_name"[[:space:]]*:[[:space:]]*"([^"]+)".*/\1/' || true)
-    if [[ -n "$api_tag" ]]; then
-      echo "$api_tag"
-      return 0
-    fi
-  fi
-
   return 1
 }
 
@@ -85,6 +62,10 @@ resolve_version() {
     echo "$FLUX_VERSION"
     return 0
   fi
+  if [[ -n "${PINNED_VERSION:-}" ]]; then
+    echo "$PINNED_VERSION"
+    return 0
+  fi
 
   if resolve_latest_release_tag; then
     return 0

mkdocs.yml

@@ -0,0 +1,40 @@
+site_name: FLVX 文档
+site_url: https://sagit-chu.github.io/flux-panel/
+site_description: FLVX官方文档
+site_author: Sagit-chu
+
+theme:
+  name: material
+  language: zh
+  palette:
+    - scheme: default
+      primary: indigo
+      accent: indigo
+    - scheme: slate
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/brightness-4
+        name: Switch to dark mode
+  features:
+    - navigation.tabs
+    - navigation.sections
+    - navigation.top
+    - search.suggest
+    - search.highlight
+    - content.code.copy
+
+docs_dir: doc
+
+nav:
+  - 首页: index.md
+  - 安装部署: install.md
+  - 使用指南: usage.md
+  - 常见问题: faq.md
+
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences
+  - pymdownx.tabbed:
+      alternate_style: true

openspec/changes/document-existing-specs/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-02-17

openspec/changes/document-existing-specs/design.md

@@ -0,0 +1,29 @@
+## Context
+
+FLVX is a distributed system consisting of a central management panel (Backend + Frontend) and multiple forwarding agents (Nodes). The backend manages configuration, users, and billing, while agents handle the actual traffic forwarding using a modified GOST v3 stack. Communication between the panel and agents is secured and synchronized.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Document the high-level architecture of the system.
+- Describe the data model for users, tunnels, and nodes.
+- Explain the communication protocol between Panel and Agent.
+- Detail the authentication and authorization mechanisms.
+
+**Non-Goals:**
+- Refactoring the existing architecture.
+- Detailed code-level documentation of every function.
+- Changing the database schema.
+
+## Decisions
+
+- **Architecture**: The system follows a client-server model where the Panel acts as the server and Agents act as clients that pull configuration and push status.
+- **Data Model**: Core entities are Users, Nodes (Agents), Tunnels (Groups of rules), and Forwarding Rules.
+- **Communication**: Agents use a heartbeat mechanism to report status and fetch configuration updates. The protocol uses AES encryption with a pre-shared key (Node Secret).
+- **Authentication**: JWT for Frontend-Backend communication; API Key (Node Secret) for Agent-Backend communication.
+
+## Risks / Trade-offs
+
+- **Security**: The security of the agent communication relies heavily on the secrecy of the Node Secret.
+- **Scalability**: Centralized management might become a bottleneck with a very large number of agents.
+- **Complexity**: Synchronizing state across distributed agents introduces complexity in handling failures and inconsistencies.

openspec/changes/document-existing-specs/proposal.md

@@ -0,0 +1,28 @@
+## Why
+
+The current system lacks formal specification documents describing its capabilities. This makes it difficult for new developers to understand the intended behavior and for existing developers to ensure consistency when adding new features. Documenting the existing functionality will serve as a baseline for future changes and help in identifying gaps or inconsistencies.
+
+## What Changes
+
+- Create formal specification documents for core system capabilities.
+- Document user management features (roles, limits).
+- Document tunnel and forwarding management (protocols, rules).
+- Document agent interactions and management.
+- Document system-level configurations.
+
+## Capabilities
+
+### New Capabilities
+- `user-management`: Authentication, user roles, and resource limits.
+- `tunnel-management`: Creation and management of traffic tunnels (TCP/UDP).
+- `forwarding-rules`: Configuration of port forwarding and tunnel forwarding rules, including rate limiting.
+- `agent-management`: Management of forwarding agents, including installation and configuration synchronization.
+- `system-config`: Global system settings and configurations.
+
+### Modified Capabilities
+<!-- None, as this is a documentation effort for existing features. -->
+
+## Impact
+
+- **Documentation**: New spec files in `openspec/specs/`.
+- **No Code Changes**: This change is purely documentation-focused.

openspec/changes/document-existing-specs/specs/agent-management/spec.md

@@ -0,0 +1,29 @@
+## ADDED Requirements
+
+### Requirement: Agent Registration
+The system SHALL require new agents (Nodes) to register using a unique node key/secret.
+
+#### Scenario: Node Connection
+- **WHEN** a new agent starts up with a valid configuration
+- **THEN** it connects to the backend and is registered as active.
+
+### Requirement: Heartbeat Monitoring
+The system SHALL monitor the status of all registered agents using periodic heartbeats.
+
+#### Scenario: Agent Status
+- **WHEN** an agent sends periodic heartbeats
+- **THEN** the system updates its last-seen timestamp and marks it as online.
+
+### Requirement: Configuration Sync
+The system MUST synchronize configuration changes (tunnels, rules) to agents securely and reliably.
+
+#### Scenario: Push Config
+- **WHEN** a configuration change is made in the panel
+- **THEN** the agent receives the updated configuration via the next heartbeat or push mechanism.
+
+### Requirement: Version Management
+The system SHOULD track the version of the agent software running on each node.
+
+#### Scenario: Version Reporting
+- **WHEN** an agent connects
+- **THEN** it reports its version number to the backend for tracking.

openspec/changes/document-existing-specs/specs/forwarding-rules/spec.md

@@ -0,0 +1,22 @@
+## ADDED Requirements
+
+### Requirement: Port Forwarding Rules
+The system SHALL support configuring port forwarding rules, defining the listening port on the node and the destination IP/port.
+
+#### Scenario: Rule Configuration
+- **WHEN** an admin creates a port forwarding rule
+- **THEN** the rule is stored and synchronized to the assigned node.
+
+### Requirement: Rate Limiting
+The system SHALL support configuring bandwidth rate limits for tunnels and users.
+
+#### Scenario: Bandwidth Restriction
+- **WHEN** a rate limit is applied to a user
+- **THEN** their total bandwidth usage does not exceed the specified limit across all their tunnels.
+
+### Requirement: Traffic Accounting
+The system MUST track incoming and outgoing traffic volume for each tunnel and user for billing and quota enforcement.
+
+#### Scenario: Traffic Calculation
+- **WHEN** traffic flows through a tunnel
+- **THEN** the system increments the user's traffic usage counter accurately.

openspec/changes/document-existing-specs/specs/system-config/spec.md

@@ -0,0 +1,22 @@
+## ADDED Requirements
+
+### Requirement: Site Settings
+The system SHALL allow customization of the site title, logo, and other branding elements.
+
+#### Scenario: Update Branding
+- **WHEN** an administrator changes the site logo
+- **THEN** the new logo is displayed across the interface.
+
+### Requirement: Notification Settings
+The system SHALL support configuring notifications for user registration, traffic limits, and other events.
+
+#### Scenario: User Limit Alert
+- **WHEN** a user approaches their traffic quota
+- **THEN** a notification is sent to the user/admin.
+
+### Requirement: Backup & Restore
+The system SHOULD provide a mechanism to backup and restore database configurations.
+
+#### Scenario: Restore Database
+- **WHEN** initiating a restore operation
+- **THEN** the system accepts a valid backup file and overwrites the current database state.

openspec/changes/document-existing-specs/specs/tunnel-management/spec.md

@@ -0,0 +1,22 @@
+## ADDED Requirements
+
+### Requirement: Tunnel Creation
+The system SHALL allow administrators to create tunnels, specifying protocols (TCP, UDP), listening ports, and destination endpoints.
+
+#### Scenario: Create TCP Tunnel
+- **WHEN** an admin creates a new TCP tunnel configuration
+- **THEN** the backend stores the tunnel definition and assigns it to a node.
+
+### Requirement: Tunnel Forwarding Configuration
+The system SHALL support both standard port forwarding (listening on a port and forwarding to a destination) and tunnel forwarding modes.
+
+#### Scenario: Configure Port Forwarding
+- **WHEN** configuring a tunnel for port forwarding
+- **THEN** traffic arriving at the specified port is forwarded to the destination IP:port.
+
+### Requirement: Tunnel Assignment
+The system SHALL allow tunnels to be assigned to specific users, tracking their usage against the user's quota.
+
+#### Scenario: User Tunnel Usage
+- **WHEN** a user is assigned a tunnel
+- **THEN** traffic passing through that tunnel is accounted for under the user's usage.

openspec/changes/document-existing-specs/specs/user-management/spec.md

@@ -0,0 +1,29 @@
+## ADDED Requirements
+
+### Requirement: User Registration
+The system SHALL allow new users to register an account with a username and password.
+
+#### Scenario: Successful Registration
+- **WHEN** a user submits valid registration details
+- **THEN** a new user account is created and the user can log in.
+
+### Requirement: User Authentication
+The system MUST authenticate users using JWT tokens. The `Authorization` header MUST contain the raw token without a `Bearer` prefix.
+
+#### Scenario: Valid Login
+- **WHEN** a user provides correct credentials
+- **THEN** the system returns a valid JWT token.
+
+### Requirement: Role Management
+The system SHALL support different user roles, specifically Administrator and Regular User, with distinct permissions.
+
+#### Scenario: Admin Access
+- **WHEN** an administrator logs in
+- **THEN** they have access to system-wide settings and all user management functions.
+
+### Requirement: Resource Quotas
+The system SHALL allow administrators to set traffic limits and connection limits for individual users.
+
+#### Scenario: Traffic Limit Enforcement
+- **WHEN** a user exceeds their traffic quota
+- **THEN** the system prevents further traffic forwarding for that user.

openspec/changes/document-existing-specs/tasks.md

@@ -0,0 +1,30 @@
+## 1. User Management Verification
+
+- [ ] 1.1 Verify User Registration logic in backend
+- [ ] 1.2 Verify JWT Authentication implementation
+- [ ] 1.3 Verify Role Management checks
+- [ ] 1.4 Verify Quota Enforcement logic
+
+## 2. Tunnel Management Verification
+
+- [ ] 2.1 Verify Tunnel Creation API
+- [ ] 2.2 Verify Forwarding Configuration parsing
+- [ ] 2.3 Verify Tunnel Assignment logic
+
+## 3. Forwarding Rules Verification
+
+- [ ] 3.1 Verify Port Forwarding rule processing
+- [ ] 3.2 Verify Rate Limiting implementation (token bucket/leaky bucket?)
+- [ ] 3.3 Verify Traffic Accounting mechanisms
+
+## 4. Agent Management Verification
+
+- [ ] 4.1 Verify Agent Registration handshake
+- [ ] 4.2 Verify Heartbeat processing
+- [ ] 4.3 Verify Config Sync protocol
+
+## 5. System Config Verification
+
+- [ ] 5.1 Verify Site Settings API
+- [ ] 5.2 Verify Notification triggers
+- [ ] 5.3 Verify Backup/Restore functionality

openspec/config.yaml

@@ -0,0 +1,20 @@
+schema: spec-driven
+
+# Project context (optional)
+# This is shown to AI when creating artifacts.
+# Add your tech stack, conventions, style guides, domain knowledge, etc.
+# Example:
+#   context: |
+#     Tech stack: TypeScript, React, Node.js
+#     We use conventional commits
+#     Domain: e-commerce platform
+
+# Per-artifact rules (optional)
+# Add custom rules for specific artifacts.
+# Example:
+#   rules:
+#     proposal:
+#       - Keep proposals under 500 words
+#       - Always include a "Non-goals" section
+#     tasks:
+#       - Break tasks into chunks of max 2 hours

openspec/project.md

@@ -0,0 +1,52 @@
+# Project Overview
+
+**Name**: FLVX (Flux Panel)
+**Description**: Traffic forwarding management system built on a forked GOST v3 stack. It provides a web-based panel for managing traffic tunnels, users, and forwarding rules.
+**Repository**: Monorepo containing Admin API, Web UI, and Forwarding Agent.
+
+## Tech Stack
+
+### Backend (`go-backend/`)
+- **Language**: Go
+- **Database**: SQLite (default), PostgreSQL (supported)
+- **Framework**: Standard library `net/http` (no heavy framework)
+- **ORM**: None (Raw SQL via `database/sql`)
+
+### Frontend (`vite-frontend/`)
+- **Framework**: React
+- **Build Tool**: Vite (using `rolldown-vite` experimental bundler)
+- **UI Library**: HeroUI
+- **Styling**: Tailwind CSS
+- **Mode**: Hybrid (Desktop + Mobile WebView support)
+
+### Agent (`go-gost/`)
+- **Language**: Go
+- **Base**: Fork of `gost` v3
+- **Extensions**: Custom extensions in `go-gost/x/`
+
+### Infrastructure
+- **Containerization**: Docker, Docker Compose (v4/v6)
+- **CI/CD**: GitHub Actions
+- **Installers**: Shell scripts (`panel_install.sh`, `install.sh`)
+
+## Architecture
+
+- **Panel**: Central management server (Go Backend + React Frontend).
+- **Agent**: Forwarding node running on remote servers.
+- **Communication**:
+    - Frontend -> Backend: REST API (JWT Auth, raw token in header).
+    - Agent -> Backend: AES-encrypted heartbeat/config sync.
+
+## Conventions
+
+- **Authentication**: `Authorization` header expects raw JWT token (do NOT add `Bearer ` prefix).
+- **API Response**: Standard envelope `{code, msg, data, ts}` (code 0 = success).
+- **Database**: Backend uses raw SQL queries. Do not introduce an ORM.
+- **File Structure**: Flat monorepo with language-prefixed directories (`go-backend`, `go-gost`).
+- **Protobuf**: Do not edit generated `.pb.go` files manually.
+
+## Development
+
+- **Backend Build**: `cd go-backend && make build`
+- **Frontend Dev**: `cd vite-frontend && npm run dev`
+- **Agent Run**: `cd go-gost && go run .`

panel_install.sh

@@ -10,15 +10,13 @@ export LC_ALL=C
 # GitHub repo used for release downloads
 REPO="Sagit-chu/flux-panel"
 
-COUNTRY=$(curl -s https://ipinfo.io/country)
+# 固定版本号（Release 构建时自动填充，留空则获取最新版）
+PINNED_VERSION=""
 
+# 镜像加速（所有下载均经过镜像源，以支持 IPv6）
 maybe_proxy_url() {
   local url="$1"
-  if [ "$COUNTRY" = "CN" ]; then
-    echo "https://ghfast.top/${url}"
-  else
-    echo "$url"
-  fi
+  echo "https://gcode.hostcentral.cc/${url}"
 }
 
 resolve_latest_release_tag() {
@@ -27,36 +25,19 @@ resolve_latest_release_tag() {
   latest_url="https://github.com/${REPO}/releases/latest"
   api_url="https://api.github.com/repos/${REPO}/releases/latest"
 
-  effective_url=$(curl -fsSL -o /dev/null -w '%{url_effective}' -L "$latest_url" 2>/dev/null || true)
+  effective_url=$(curl -fsSL -o /dev/null -w '%{url_effective}' -L "$(maybe_proxy_url "$latest_url")" 2>/dev/null || true)
   tag="${effective_url##*/}"
   if [[ -n "$tag" && "$tag" != "latest" ]]; then
     echo "$tag"
     return 0
   fi
 
-  if [ "$COUNTRY" = "CN" ]; then
-    effective_url=$(curl -fsSL -o /dev/null -w '%{url_effective}' -L "$(maybe_proxy_url "$latest_url")" 2>/dev/null || true)
-    tag="${effective_url##*/}"
-    if [[ -n "$tag" && "$tag" != "latest" ]]; then
-      echo "$tag"
-      return 0
-    fi
-  fi
-
-  api_tag=$(curl -fsSL "$api_url" 2>/dev/null | grep -m1 '"tag_name"' | sed -E 's/.*"tag_name"[[:space:]]*:[[:space:]]*"([^"]+)".*/\1/' || true)
+  api_tag=$(curl -fsSL "$(maybe_proxy_url "$api_url")" 2>/dev/null | grep -m1 '"tag_name"' | sed -E 's/.*"tag_name"[[:space:]]*:[[:space:]]*"([^"]+)".*/\1/' || true)
   if [[ -n "$api_tag" ]]; then
     echo "$api_tag"
     return 0
   fi
 
-  if [ "$COUNTRY" = "CN" ]; then
-    api_tag=$(curl -fsSL "$(maybe_proxy_url "$api_url")" 2>/dev/null | grep -m1 '"tag_name"' | sed -E 's/.*"tag_name"[[:space:]]*:[[:space:]]*"([^"]+)".*/\1/' || true)
-    if [[ -n "$api_tag" ]]; then
-      echo "$api_tag"
-      return 0
-    fi
-  fi
-
   return 1
 }
 
@@ -69,6 +50,10 @@ resolve_version() {
     echo "$FLUX_VERSION"
     return 0
   fi
+  if [[ -n "${PINNED_VERSION:-}" ]]; then
+    echo "$PINNED_VERSION"
+    return 0
+  fi
 
   if resolve_latest_release_tag; then
     return 0
@@ -218,7 +203,8 @@ show_menu() {
   echo "1. 安装面板"
   echo "2. 更新面板"
   echo "3. 卸载面板"
-  echo "4. 退出"
+  echo "4. 迁移到 PostgreSQL"
+  echo "5. 退出"
   echo "==============================================="
 }
 
@@ -247,6 +233,92 @@ upsert_env_var() {
   mv "$tmp_file" "$file"
 }
 
+get_env_var() {
+  local key="$1"
+  local file="${2:-.env}"
+
+  if [[ ! -f "$file" ]]; then
+    return 0
+  fi
+
+  grep -m1 "^${key}=" "$file" | cut -d= -f2-
+}
+
+get_current_db_type() {
+  local db_type database_url
+
+  db_type=$(get_env_var "DB_TYPE")
+  database_url=$(get_env_var "DATABASE_URL")
+
+  if [[ "$db_type" == "sqlite" ]]; then
+    echo "sqlite"
+  elif [[ "$db_type" == "postgres" || "$database_url" == postgres://* || "$database_url" == postgresql://* ]]; then
+    echo "postgres"
+  else
+    echo "sqlite"
+  fi
+}
+
+wait_for_postgres_healthy() {
+  local pg_health
+
+  echo "🔍 检查 PostgreSQL 服务状态..."
+  for i in {1..90}; do
+    if docker ps --format "{{.Names}}" | grep -q "^flux-panel-postgres$"; then
+      pg_health=$(docker inspect -f '{{.State.Health.Status}}' flux-panel-postgres 2>/dev/null || echo "unknown")
+      if [[ "$pg_health" == "healthy" ]]; then
+        echo "✅ PostgreSQL 服务健康检查通过"
+        return 0
+      elif [[ "$pg_health" == "unhealthy" ]]; then
+        echo "⚠️ PostgreSQL 健康状态：$pg_health"
+      fi
+    else
+      pg_health="not_running"
+    fi
+
+    if [ $i -eq 90 ]; then
+      echo "❌ PostgreSQL 启动超时（90秒）"
+      echo "🔍 当前状态：$(docker inspect -f '{{.State.Health.Status}}' flux-panel-postgres 2>/dev/null || echo '容器不存在')"
+      return 1
+    fi
+
+    if [ $((i % 15)) -eq 1 ]; then
+      echo "⏳ 等待 PostgreSQL 启动... ($i/90) 状态：${pg_health:-unknown}"
+    fi
+    sleep 1
+  done
+}
+
+wait_for_backend_healthy() {
+  local backend_health
+
+  echo "🔍 检查后端服务状态..."
+  for i in {1..90}; do
+    if docker ps --format "{{.Names}}" | grep -q "^flux-panel-backend$"; then
+      backend_health=$(docker inspect -f '{{.State.Health.Status}}' flux-panel-backend 2>/dev/null || echo "unknown")
+      if [[ "$backend_health" == "healthy" ]]; then
+        echo "✅ 后端服务健康检查通过"
+        return 0
+      elif [[ "$backend_health" == "unhealthy" ]]; then
+        echo "⚠️ 后端健康状态：$backend_health"
+      fi
+    else
+      backend_health="not_running"
+    fi
+
+    if [ $i -eq 90 ]; then
+      echo "❌ 后端服务启动超时（90秒）"
+      echo "🔍 当前状态：$(docker inspect -f '{{.State.Health.Status}}' flux-panel-backend 2>/dev/null || echo '容器不存在')"
+      return 1
+    fi
+
+    if [ $((i % 15)) -eq 1 ]; then
+      echo "⏳ 等待后端服务启动... ($i/90) 状态：${backend_health:-unknown}"
+    fi
+    sleep 1
+  done
+}
+
 # 删除脚本自身
 delete_self() {
   echo ""
@@ -268,6 +340,33 @@ get_config_params() {
   read -p "后端端口（默认 6365）: " BACKEND_PORT
   BACKEND_PORT=${BACKEND_PORT:-6365}
 
+  echo "请选择数据库类型："
+  echo "1. SQLite（默认）"
+  echo "2. PostgreSQL"
+  read -p "数据库类型（1/2，默认 1）: " DB_CHOICE
+  case "$DB_CHOICE" in
+    2)
+      DB_TYPE="postgres"
+      ;;
+    ""|1)
+      DB_TYPE="sqlite"
+      ;;
+    *)
+      echo "⚠️ 输入无效，默认使用 SQLite"
+      DB_TYPE="sqlite"
+      ;;
+  esac
+
+  POSTGRES_DB="flux_panel"
+  POSTGRES_USER="flux_panel"
+  POSTGRES_PASSWORD=$(generate_random)
+
+  if [[ "$DB_TYPE" == "postgres" ]]; then
+    DATABASE_URL="postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}?sslmode=disable"
+  else
+    DATABASE_URL=""
+  fi
+
   # 生成JWT密钥
   JWT_SECRET=$(generate_random)
 }
@@ -295,10 +394,23 @@ JWT_SECRET=$JWT_SECRET
 FRONTEND_PORT=$FRONTEND_PORT
 BACKEND_PORT=$BACKEND_PORT
 FLUX_VERSION=$RESOLVED_VERSION
+
+DB_TYPE=$DB_TYPE
+DATABASE_URL=$DATABASE_URL
+
+POSTGRES_DB=$POSTGRES_DB
+POSTGRES_USER=$POSTGRES_USER
+POSTGRES_PASSWORD=$POSTGRES_PASSWORD
 EOF
 
   echo "🚀 启动 docker 服务..."
-  $DOCKER_CMD up -d
+  if [[ "$DB_TYPE" == "postgres" ]]; then
+    $DOCKER_CMD up -d postgres
+    wait_for_postgres_healthy
+    $DOCKER_CMD up -d backend frontend
+  else
+    $DOCKER_CMD up -d backend frontend
+  fi
 
   echo "🎉 部署完成"
   echo "🌐 访问地址: http://服务器IP:$FRONTEND_PORT"
@@ -315,6 +427,12 @@ update_panel() {
   echo "🔄 开始更新面板..."
   check_docker
 
+  if [[ ! -f ".env" ]]; then
+    echo "⚠️ 未找到 .env，默认按 SQLite 模式更新"
+  fi
+  CURRENT_DB_TYPE=$(get_current_db_type)
+  echo "🗄️ 当前数据库类型：$CURRENT_DB_TYPE"
+
   echo "🔍 获取最新版本号..."
   LATEST_VERSION=$(resolve_latest_release_tag) || {
     echo "❌ 无法获取最新版本号，更新终止"
@@ -348,49 +466,113 @@ update_panel() {
   $DOCKER_CMD down
 
   echo "⬇️ 拉取最新镜像..."
-  $DOCKER_CMD pull
+  if [[ "$CURRENT_DB_TYPE" == "postgres" ]]; then
+    $DOCKER_CMD pull backend frontend postgres
+  else
+    $DOCKER_CMD pull backend frontend
+  fi
 
   echo "🚀 启动更新后的服务..."
-  $DOCKER_CMD up -d
+  if [[ "$CURRENT_DB_TYPE" == "postgres" ]]; then
+    $DOCKER_CMD up -d postgres
+    wait_for_postgres_healthy
+    $DOCKER_CMD up -d backend frontend
+  else
+    $DOCKER_CMD up -d backend frontend
+  fi
 
   # 等待服务启动
   echo "⏳ 等待服务启动..."
 
-  # 检查后端容器健康状态
-  echo "🔍 检查后端服务状态..."
-  for i in {1..90}; do
-    if docker ps --format "{{.Names}}" | grep -q "^flux-panel-backend$"; then
-      BACKEND_HEALTH=$(docker inspect -f '{{.State.Health.Status}}' flux-panel-backend 2>/dev/null || echo "unknown")
-      if [[ "$BACKEND_HEALTH" == "healthy" ]]; then
-        echo "✅ 后端服务健康检查通过"
-        break
-      elif [[ "$BACKEND_HEALTH" == "starting" ]]; then
-        # 继续等待
-        :
-      elif [[ "$BACKEND_HEALTH" == "unhealthy" ]]; then
-        echo "⚠️ 后端健康状态：$BACKEND_HEALTH"
-      fi
-    else
-      echo "⚠️ 后端容器未找到或未运行"
-      BACKEND_HEALTH="not_running"
-    fi
-    if [ $i -eq 90 ]; then
-      echo "❌ 后端服务启动超时（90秒）"
-      echo "🔍 当前状态：$(docker inspect -f '{{.State.Health.Status}}' flux-panel-backend 2>/dev/null || echo '容器不存在')"
-      echo "🛑 更新终止"
-      return 1
-    fi
-    # 每15秒显示一次进度
-    if [ $((i % 15)) -eq 1 ]; then
-      echo "⏳ 等待后端服务启动... ($i/90) 状态：${BACKEND_HEALTH:-unknown}"
-    fi
-    sleep 1
-  done
+  if ! wait_for_backend_healthy; then
+    echo "🛑 更新终止"
+    return 1
+  fi
 
   echo "✅ 更新完成"
 }
 
 
+migrate_to_postgres() {
+  local current_db_type postgres_db postgres_user postgres_password database_url
+
+  echo "🔄 开始迁移 SQLite -> PostgreSQL..."
+  check_docker
+
+  if [[ ! -f ".env" ]]; then
+    echo "❌ 未找到 .env 文件，请先安装面板"
+    return 1
+  fi
+
+  if [[ ! -f "docker-compose.yml" ]]; then
+    echo "⚠️ 未找到 docker-compose.yml 文件，正在下载..."
+    DOCKER_COMPOSE_URL=$(get_docker_compose_url)
+    echo "📡 选择配置文件：$(basename "$DOCKER_COMPOSE_URL")"
+    curl -L -o docker-compose.yml "$DOCKER_COMPOSE_URL"
+    echo "✅ docker-compose.yml 下载完成"
+  fi
+
+  current_db_type=$(get_current_db_type)
+  if [[ "$current_db_type" == "postgres" ]]; then
+    echo "ℹ️ 当前已使用 PostgreSQL，无需迁移"
+    return 0
+  fi
+
+  postgres_db=$(get_env_var "POSTGRES_DB")
+  postgres_user=$(get_env_var "POSTGRES_USER")
+  postgres_password=$(get_env_var "POSTGRES_PASSWORD")
+
+  postgres_db=${postgres_db:-flux_panel}
+  postgres_user=${postgres_user:-flux_panel}
+  postgres_password=${postgres_password:-$(generate_random)}
+
+  upsert_env_var ".env" "POSTGRES_DB" "$postgres_db"
+  upsert_env_var ".env" "POSTGRES_USER" "$postgres_user"
+  upsert_env_var ".env" "POSTGRES_PASSWORD" "$postgres_password"
+
+  echo "🛑 停止当前服务..."
+  docker stop -t 30 flux-panel-backend 2>/dev/null || true
+  docker stop -t 10 vite-frontend 2>/dev/null || true
+  echo "⏳ 等待数据同步..."
+  sleep 5
+  $DOCKER_CMD down
+
+  echo "💾 备份 SQLite 数据到当前目录..."
+  if ! docker run --rm -v sqlite_data:/data -v "$(pwd)":/backup alpine sh -c "cp /data/gost.db /backup/gost.db.bak"; then
+    echo "❌ SQLite 备份失败，迁移终止"
+    return 1
+  fi
+
+  echo "🚀 启动 PostgreSQL..."
+  $DOCKER_CMD up -d postgres
+  if ! wait_for_postgres_healthy; then
+    echo "🛑 PostgreSQL 未就绪，迁移终止"
+    return 1
+  fi
+
+  echo "🔄 执行 pgloader 迁移..."
+  if ! docker run --rm --network gost-network -v sqlite_data:/sqlite dimitri/pgloader:latest pgloader /sqlite/gost.db "postgresql://${postgres_user}:${postgres_password}@postgres:5432/${postgres_db}"; then
+    echo "❌ pgloader 迁移失败，迁移终止（如报 28P01，可执行 docker volume rm postgres_data 后重试）"
+    return 1
+  fi
+
+  database_url="postgresql://${postgres_user}:${postgres_password}@postgres:5432/${postgres_db}?sslmode=disable"
+  upsert_env_var ".env" "DB_TYPE" "postgres"
+  upsert_env_var ".env" "DATABASE_URL" "$database_url"
+
+  echo "🚀 启动迁移后的服务..."
+  $DOCKER_CMD up -d postgres backend frontend
+
+  echo "⏳ 等待服务启动..."
+  if ! wait_for_backend_healthy; then
+    echo "🛑 迁移后服务启动失败"
+    return 1
+  fi
+
+  echo "✅ SQLite -> PostgreSQL 迁移完成"
+}
+
+
 
 # 卸载功能
 uninstall_panel() {
@@ -443,6 +625,11 @@ main() {
         exit 0
         ;;
       4)
+        migrate_to_postgres
+        delete_self
+        exit 0
+        ;;
+      5)
         echo "👋 退出脚本"
         delete_self
         exit 0

springboot-backend/.factorypath

@@ -1,3 +0,0 @@
-<factorypath>
-    <factorypathentry kind="VARJAR" id="M2_REPO/org/projectlombok/lombok/1.18.30/lombok-1.18.30.jar" enabled="true" runInBatchMode="false"/>
-</factorypath>

springboot-backend/AGENTS.md

@@ -1,39 +0,0 @@
-# SPRINGBOOT BACKEND KNOWLEDGE BASE
-
-**Generated:** Mon Feb 02 2026
-
-## OVERVIEW
-Admin API for Flux Panel. Manages users, tunnels, nodes, forwards, quotas, and speed limits.
-**Stack:** Java 21, Spring Boot 2.7.18, SQLite, MyBatis Plus (+ join), FastJSON2.
-
-## STRUCTURE
-```
-springboot-backend/
-├── src/main/java/com/admin/
-│   ├── controller/      # /api/v1/* endpoints
-│   ├── entity/          # DB models
-│   ├── mapper/          # MyBatis Plus mappers
-│   ├── service/         # Business logic
-│   ├── config/          # WebMvc/JWT/CORS/WebSocket config
-│   └── common/          # DTOs, auth, exception handling, utilities
-└── src/main/resources/
-    ├── application.yml  # Config (DB_PATH/JWT_SECRET/LOG_DIR)
-    ├── mapper/          # XML mappers
-    ├── schema.sql       # Schema
-    └── data.sql         # Seed data
-```
-
-## CONVENTIONS
-- **DB**: SQLite URL is `jdbc:sqlite:${DB_PATH:/app/data/gost.db}` (`springboot-backend/src/main/resources/application.yml`).
-- **Auth**: JWT in `Authorization` header; enforced by `com.admin.common.interceptor.JwtInterceptor` for `/api/**` (with explicit excludes in `com.admin.config.WebMvcConfig`).
-- **Roles**: `@RequireRole` means admin-only (`role_id == 0`) via `com.admin.common.aop.RoleAspect`.
-- **Responses**: Controllers return `com.admin.common.lang.R` (`code == 0` success).
-- **CORS**: Allow-all origins; `Authorization` is exposed (`com.admin.config.WebMvcConfig`).
-
-## COMMANDS
-```bash
-cd springboot-backend
-mvn clean package
-mvn test
-java -jar target/admin-0.0.1-SNAPSHOT.jar
-```

springboot-backend/Dockerfile

@@ -1,27 +0,0 @@
-# 构建阶段
-FROM maven:3.9.6-eclipse-temurin-21 AS build
-WORKDIR /app
-COPY pom.xml .
-COPY src ./src
-RUN mvn clean package -DskipTests
-
-# 运行阶段
-FROM eclipse-temurin:21-jre
-WORKDIR /app
-ENV JAVA_OPTS="-Xmx512m -Xms256m -Dfile.encoding=UTF-8 -Duser.timezone=Asia/Shanghai"
-ENV LANG=en_US.UTF-8
-ENV LANGUAGE=en_US:en
-ENV LC_ALL=en_US.UTF-8
-
-RUN sed -i 's/archive.ubuntu.com/mirrors.ustc.edu.cn/g' /etc/apt/sources.list \
-    && sed -i 's/security.ubuntu.com/mirrors.ustc.edu.cn/g' /etc/apt/sources.list \
-    && apt-get update \
-    && apt-get install -y --no-install-recommends fontconfig fonts-dejavu sqlite3 \
-    && apt-get clean \
-    && rm -rf /var/lib/apt/lists/*
-
-COPY --from=build /app/target/*.jar app.jar
-
-EXPOSE 6365
-
-ENTRYPOINT ["sh", "-c", "exec java $JAVA_OPTS -jar /app/app.jar"]

springboot-backend/pom.xml

@@ -1,180 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
-    <modelVersion>4.0.0</modelVersion>
-    <groupId>com.admin</groupId>
-    <artifactId>admin</artifactId>
-    <version>0.0.1-SNAPSHOT</version>
-    <name>admin</name>
-    <description>admin</description>
-    <properties>
-        <java.version>21</java.version>
-        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
-        <spring-boot.version>2.7.18</spring-boot.version>
-        <maven.compiler.source>21</maven.compiler.source>
-        <maven.compiler.target>21</maven.compiler.target>
-    </properties>
-    <dependencies>
-
-        <dependency>
-            <groupId>org.springframework.boot</groupId>
-            <artifactId>spring-boot-starter-web</artifactId>
-        </dependency>
-        <dependency>
-            <groupId>com.alibaba.fastjson2</groupId>
-            <artifactId>fastjson2</artifactId>
-            <version>2.0.43</version>
-        </dependency>
-
-
-        <dependency>
-            <groupId>org.projectlombok</groupId>
-            <artifactId>lombok</artifactId>
-            <version>1.18.30</version>
-            <optional>true</optional>
-        </dependency>
-
-        <dependency>
-            <groupId>com.github.yulichang</groupId>
-            <artifactId>mybatis-plus-join</artifactId>
-            <version>1.3.0</version>
-        </dependency>
-
-
-        <dependency>
-            <groupId>com.alibaba</groupId>
-            <artifactId>fastjson</artifactId>
-            <version>1.2.70</version>
-        </dependency>
-
-
-
-
-        <dependency>
-            <groupId>org.springframework.boot</groupId>
-            <artifactId>spring-boot-starter-aop</artifactId>
-        </dependency>
-
-        <dependency>
-            <groupId>com.baomidou</groupId>
-            <artifactId>mybatis-plus-boot-starter</artifactId>
-            <version>3.4.1</version>
-        </dependency>
-
-        <dependency>
-            <groupId>com.baomidou</groupId>
-            <artifactId>mybatis-plus-generator</artifactId>
-            <version>3.4.1</version>
-        </dependency>
-
-        <dependency>
-            <groupId>org.xerial</groupId>
-            <artifactId>sqlite-jdbc</artifactId>
-            <version>3.45.0.0</version>
-        </dependency>
-
-        <dependency>
-            <groupId>cn.hutool</groupId>
-            <artifactId>hutool-all</artifactId>
-            <version>5.3.3</version>
-        </dependency>
-
-        <dependency>
-            <groupId>org.apache.commons</groupId>
-            <artifactId>commons-lang3</artifactId>
-            <version>3.11</version>
-        </dependency>
-
-        <dependency>
-            <groupId>org.springframework.boot</groupId>
-            <artifactId>spring-boot-starter-validation</artifactId>
-        </dependency>
-
-        <dependency>
-            <groupId>org.apache.httpcomponents</groupId>
-            <artifactId>httpclient</artifactId>
-            <version>4.5.14</version>
-        </dependency>
-
-        <dependency>
-            <groupId>org.freemarker</groupId>
-            <artifactId>freemarker</artifactId>
-            <version>2.3.31</version>
-        </dependency>
-
-
-        <dependency>
-            <groupId>org.springframework.boot</groupId>
-            <artifactId>spring-boot-starter</artifactId>
-        </dependency>
-
-        <dependency>
-            <groupId>org.springframework.boot</groupId>
-            <artifactId>spring-boot-starter-websocket</artifactId>
-        </dependency>
-
-        <dependency>
-            <groupId>org.springframework.boot</groupId>
-            <artifactId>spring-boot-starter-test</artifactId>
-            <scope>test</scope>
-        </dependency>
-
-        <!-- tianai-captcha Spring Boot Starter -->
-        <dependency>
-            <groupId>cloud.tianai.captcha</groupId>
-            <artifactId>tianai-captcha-springboot-starter</artifactId>
-            <version>1.5.2</version>
-        </dependency>
-    </dependencies>
-    <dependencyManagement>
-        <dependencies>
-            <dependency>
-                <groupId>org.springframework.boot</groupId>
-                <artifactId>spring-boot-dependencies</artifactId>
-                <version>${spring-boot.version}</version>
-                <type>pom</type>
-                <scope>import</scope>
-            </dependency>
-        </dependencies>
-    </dependencyManagement>
-
-    <build>
-        <plugins>
-            <plugin>
-                <groupId>org.apache.maven.plugins</groupId>
-                <artifactId>maven-compiler-plugin</artifactId>
-                <version>3.11.0</version>
-                <configuration>
-                    <source>21</source>
-                    <target>21</target>
-                    <encoding>UTF-8</encoding>
-                    <annotationProcessorPaths>
-                        <path>
-                            <groupId>org.projectlombok</groupId>
-                            <artifactId>lombok</artifactId>
-                            <version>1.18.30</version>
-                        </path>
-                    </annotationProcessorPaths>
-                </configuration>
-            </plugin>
-            <plugin>
-                <groupId>org.springframework.boot</groupId>
-                <artifactId>spring-boot-maven-plugin</artifactId>
-                <version>${spring-boot.version}</version>
-                <configuration>
-                    <mainClass>com.admin.AdminApplication</mainClass>
-                </configuration>
-                <executions>
-                    <execution>
-                        <id>repackage</id>
-                        <goals>
-                            <goal>repackage</goal>
-                        </goals>
-                    </execution>
-                </executions>
-            </plugin>
-        </plugins>
-    </build>
-
-</project>

springboot-backend/src/main/java/com/admin/AGENTS.md

@@ -1,32 +0,0 @@
-# SPRINGBOOT BACKEND (com.admin) KNOWLEDGE BASE
-
-## OVERVIEW
-Primary Java code for the admin API. Controllers expose `/api/v1/*` endpoints and return `R` response envelopes.
-
-## STRUCTURE
-```
-springboot-backend/src/main/java/com/admin/
-├── controller/  # REST controllers (e.g., /api/v1/user)
-├── service/     # Business logic interfaces + impl/
-├── mapper/      # MyBatis Plus mappers
-├── entity/      # DB entities
-├── config/      # WebMvc/JWT/CORS/WebSocket config
-└── common/      # DTOs, auth, exception handling, utilities
-```
-
-## WHERE TO LOOK
-| Task | Location | Notes |
-|------|----------|-------|
-| User/login endpoints | `springboot-backend/src/main/java/com/admin/controller/UserController.java` | `/api/v1/user/*` |
-| Auth enforcement | `springboot-backend/src/main/java/com/admin/config/WebMvcConfig.java` | Intercepts `/api/**`, excludes login/config/captcha |
-| JWT validation | `springboot-backend/src/main/java/com/admin/common/interceptor/JwtInterceptor.java` | Requires `Authorization` header |
-| Admin-only ops | `springboot-backend/src/main/java/com/admin/common/annotation/RequireRole.java` | Enforced by `RoleAspect` |
-| Response envelope | `springboot-backend/src/main/java/com/admin/common/lang/R.java` | `code == 0` success |
-| Global error handling | `springboot-backend/src/main/java/com/admin/common/exception/GlobalExceptionHandler.java` | Maps exceptions -> `R.err(...)` |
-
-## CONVENTIONS
-- Controllers are mostly `@PostMapping` (even for list/get/delete) and use `/api/v1/*` prefixes.
-- JWT is custom (no 3p lib) and includes `role_id` in payload (`springboot-backend/src/main/java/com/admin/common/utils/JwtUtil.java`).
-
-## ANTI-PATTERNS
-- Do not change auth header format lightly: frontend expects `Authorization: <token>` (no `Bearer`).