fix(backend): rename legacy postgres unique constraints before AutoMigrate (#138)

Old schema.sql created tables with inline UNIQUE column constraints,
which PostgreSQL auto-names as <table>_<column>_key. GORM expects
uni_<table>_<column> (its NamingStrategy convention). On upgrade,
AutoMigrate issued DROP CONSTRAINT uni_... against a name that did not
exist, crashing startup with SQLSTATE 42704.

Add preparePostgresLegacySchema() that runs before autoMigrateAll and
renames all five mismatched constraints:
- vite_config_name_key -> uni_vite_config_name
- peer_share_token_key -> uni_peer_share_token
- peer_share_runtime_reservation_id_key -> uni_peer_share_runtime_reservation_id
- peer_share_runtime_resource_key_key -> uni_peer_share_runtime_resource_key
- federation_tunnel_binding_resource_key_key -> uni_federation_tunnel_binding_resource_key

The function is idempotent: it checks information_schema before each
rename so re-runs on already-migrated databases are no-ops.

Co-authored-by: Antigravity <antigravity@google.com>

.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/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

@@ -177,6 +177,7 @@ build/
 *.dylib
 your_app.exe
 go-backend/paneld
+go-gost/gost
 
 # Go 测试二进制文件
 *.test
@@ -262,3 +263,6 @@ 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

AGENTS.md

@@ -1,8 +1,8 @@
 # PROJECT KNOWLEDGE BASE
 
-**Generated:** Mon Feb 02 2026
-**Commit:** 7ca01ab
-**Branch:** beta
+**Generated:** Sun Feb 15 2026
+**Commit:** e5e22ba
+**Branch:** main
 
 ## OVERVIEW
 FLVX (formerly Flux Panel) is a traffic forwarding management system built on a forked GOST v3 stack. It ships as a Go-based admin API (SQLite) + Vite/React UI + Go forwarding agent, with optional mobile WebView wrappers.
@@ -12,7 +12,7 @@ FLVX (formerly Flux Panel) is a traffic forwarding management system built on a
 ./
 ├── go-gost/               # Go forwarding agent (forked gost + local x/)
 │   └── x/                 # Local fork of github.com/go-gost/x (replace => ./x)
-├── go-backend/            # Go Admin API (SQLite, net/http)
+├── go-backend/            # Go Admin API (GORM + SQLite/PostgreSQL, net/http)
 ├── vite-frontend/         # React/Vite dashboard (HeroUI + Tailwind)
 ├── docker-compose-v4.yml  # Panel deploy (IPv4-only bridge)
 ├── docker-compose-v6.yml  # Panel deploy (IPv6-enabled bridge)
@@ -43,11 +43,17 @@ FLVX (formerly Flux Panel) is a traffic forwarding management system built on a
 
 
 ## CONVENTIONS
-- `Authorization` header carries the raw JWT token (no `Bearer` prefix) between `vite-frontend/` and `go-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).
 
 ## 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).
 
 ## COMMANDS
 ```bash
@@ -65,6 +71,19 @@ docker compose -f docker-compose-v6.yml up -d
 (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.

README.md

@@ -2,6 +2,127 @@
 
 > **联系我们**: [Telegram群组](https://t.me/flvxpanel)
 
+
+## 特性
+
+- 支持按 **隧道账号级别** 管理流量转发数量，可用于用户/隧道配额控制
+- 支持 **TCP** 和 **UDP** 协议的转发
+- 支持两种转发模式：**端口转发** 与 **隧道转发**
+- 可针对 **指定用户的指定隧道进行限速** 设置
+- 支持配置 **单向或双向流量计费方式**，灵活适配不同计费模型
+- 提供灵活的转发策略配置，适用于多种网络场景
+- 面板分享，支持将节点分享给其他人，面板对接面板
+- 支持分组权限管理，隧道分组、用户分组
+- 支持批量功能，可以批量下发配置，启停等
+- 支持隧道修改配置、转发修改隧道
+
+
+## 部署流程
+---
+### 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
+```
+节点端：
+```bash
+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
+- **密码**: admin_user
+
+> ⚠️ 首次登录后请立即修改默认密码！
+
+---
 ## Original Project
 - **Name**: flux-panel
 - **Source**: https://github.com/bqlpfy/flux-panel
@@ -26,40 +147,11 @@ The following major changes and additions have been made in this fork (FLVX):
 - **Removed**: `ios-app/` - Source code for the iOS client.
 
 ### 5. Infrastructure & Scripts
-- **Modified**: `docker-compose-v4.yml`, `docker-compose-v6.yml` (Updated for Go backend).
+- **Modified**: `docker-compose.yml` (installer output name, auto-selects IPv4/IPv6 template, updated for Go backend).
 - **Modified**: `install.sh`, `panel_install.sh` (Updated installation logic).
 - **Added**: `AGENTS.md` (Project documentation).
 
 ---
-## 特性
-
-- 支持按 **隧道账号级别** 管理流量转发数量，可用于用户/隧道配额控制
-- 支持 **TCP** 和 **UDP** 协议的转发
-- 支持两种转发模式：**端口转发** 与 **隧道转发**
-- 可针对 **指定用户的指定隧道进行限速** 设置
-- 支持配置 **单向或双向流量计费方式**，灵活适配不同计费模型
-- 提供灵活的转发策略配置，适用于多种网络场景
-
-
-## 部署流程
----
-### 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
-```
-节点端：
-```bash
-curl -L https://raw.githubusercontent.com/Sagit-chu/flux-panel/main/install.sh -o install.sh && chmod +x install.sh && ./install.sh
-```
-
-#### 默认管理员账号
-
-- **账号**: admin_user
-- **密码**: admin_user
-
-> ⚠️ 首次登录后请立即修改默认密码！
 
 
 ## 免责声明

doc/faq.md

@@ -22,3 +22,19 @@
 
 ### 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

@@ -17,6 +17,7 @@
 
 - [安装部署](./install.md)
 - [使用指南](./usage.md)
+- [PostgreSQL 数据库指南](./postgresql.md)
 - [常见问题](./faq.md)
 
 ## 免责声明

doc/install.md

@@ -41,6 +41,8 @@ curl -L https://raw.githubusercontent.com/Sagit-chu/flux-panel/main/panel_instal
 1. 安装面板
 2. 更新面板
 3. 卸载面板
+4. 迁移到 PostgreSQL
+5. 退出
 
 ---
 
@@ -77,3 +79,57 @@ curl -L https://raw.githubusercontent.com/Sagit-chu/flux-panel/main/install.sh -
 安装完成后，服务会自动启动。
 - 查看状态: `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
+```

docker-compose-v4.yml

@@ -7,16 +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
@@ -29,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
@@ -37,6 +62,7 @@ services:
       driver: json-file
       options:
         max-size: "20m"
+        max-file: "3"
     ports:
       - "${FRONTEND_PORT}:80"
     depends_on:
@@ -50,8 +76,8 @@ volumes:
   sqlite_data:
     name: sqlite_data
     driver: local
-  backend_logs:
-    name: backend_logs
+  postgres_data:
+    name: postgres_data
     driver: local
 
 
@@ -61,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,16 +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
@@ -29,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
@@ -37,6 +62,7 @@ services:
       driver: json-file
       options:
         max-size: "20m"
+        max-file: "3"
     ports:
       - "${FRONTEND_PORT}:80"
     depends_on:
@@ -50,8 +76,8 @@ volumes:
   sqlite_data:
     name: sqlite_data
     driver: local
-  backend_logs:
-    name: backend_logs
+  postgres_data:
+    name: postgres_data
     driver: local
 
 
@@ -62,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

@@ -1,8 +1,8 @@
 # GO BACKEND KNOWLEDGE BASE
 
 ## OVERVIEW
-Go-based Admin API for FLVX (formerly Flux Panel). Replaces the legacy Spring Boot backend.
-**Stack:** Go 1.23, net/http (std lib), SQLite (modernc.org/sqlite).
+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
 ```
@@ -14,9 +14,14 @@ go-backend/
 │   │   ├── handler/          # API Handlers (User, Tunnel, Node, etc.)
 │   │   ├── middleware/       # JWT, CORS, Logging, Recover
 │   │   └── response/         # JSON response helpers
-│   ├── store/sqlite/         # Data Access Layer (Repository pattern)
-│   │   ├── repository.go     # SQL queries & Struct definitions
-│   │   └── sql/              # Embedded schema.sql & data.sql
+│   ├── 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)
@@ -27,21 +32,32 @@ go-backend/
 | Task | Location | Notes |
 |------|----------|-------|
 | **API Routes** | `go-backend/internal/http/router.go` | Registers handlers to `http.ServeMux` |
-| **DB Schema** | `go-backend/internal/store/sqlite/sql/schema.sql` | Embedded in binary |
-| **SQL Queries** | `go-backend/internal/store/sqlite/repository.go` | Raw SQL, no ORM |
+| **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
-- **No ORM**: Uses raw SQL with `database/sql` and `modernc.org/sqlite`.
+- **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
+go run ./cmd/paneld       # Default: SERVER_ADDR=:6365
 go test ./...
 make build
 ```

go-backend/Dockerfile

@@ -1,7 +1,7 @@
-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 . .

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

@@ -77,6 +77,18 @@ type RuntimeDiagnoseRequest struct {
 	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{
@@ -85,6 +97,14 @@ func NewFederationClient() *FederationClient {
 	}
 }
 
+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)
@@ -325,3 +345,42 @@ func (c *FederationClient) Diagnose(url, token, localDomain string, reqData Runt
 
 	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"
@@ -12,61 +11,18 @@ import (
 	"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
-	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 chainNodeRecord = model.ChainNodeRecord
 
 type diagnosisTarget struct {
 	Address string
@@ -101,227 +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, is_remote, remote_url, remote_token, remote_config
-		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
-	var remoteURL sql.NullString
-	var remoteToken sql.NullString
-	var remoteConfig sql.NullString
-	err := row.Scan(&n.ID, &n.Name, &n.ServerIP, &serverIPv4, &serverIPv6, &n.Status, &portRange, &tcpListen, &udpListen, &iface, &n.IsRemote, &remoteURL, &remoteToken, &remoteConfig)
+	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)
-	n.RemoteURL = strings.TrimSpace(remoteURL.String)
-	n.RemoteToken = strings.TrimSpace(remoteToken.String)
-	n.RemoteConfig = strings.TrimSpace(remoteConfig.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, *int64, *int, error) {
-	row := h.repo.DB().QueryRow(`
-		SELECT ut.id, sl.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 limiterID sql.NullInt64
-	var speed sql.NullInt64
-	err := row.Scan(&userTunnelID, &limiterID, &speed)
+	info, err := h.repo.ResolveUserTunnelAndLimiter(userID, tunnelID)
 	if err != nil {
-		if errors.Is(err, sql.ErrNoRows) {
-			return 0, nil, nil, nil
-		}
 		return 0, nil, nil, err
 	}
-	if !limiterID.Valid || limiterID.Int64 <= 0 {
-		return userTunnelID, nil, nil, nil
+	if info == nil {
+		return 0, nil, nil, nil
 	}
-	v := limiterID.Int64
-	s := int(speed.Int64)
-	return userTunnelID, &v, &s, 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 {
@@ -346,6 +157,10 @@ func (h *Handler) syncForwardServices(forward *forwardRecord, method string, all
 		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 {
@@ -356,7 +171,7 @@ func (h *Handler) syncForwardServices(forward *forwardRecord, method string, all
 		if err != nil {
 			return err
 		}
-		services := buildForwardServiceConfigs(serviceBase, forward, tunnel, node, fp.Port, limiterID)
+		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)
@@ -457,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
 	}
@@ -475,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
@@ -520,7 +383,7 @@ func (h *Handler) diagnoseForwardRuntime(forward *forwardRecord) (map[string]int
 						"fromChainType": 1,
 						"toChainType":   2,
 						"toInx":         firstNode.Inx,
-					})
+					}, "")
 				}
 			} else {
 				for _, outNode := range outNodes {
@@ -528,7 +391,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,
-					})
+					}, "")
 				}
 			}
 		}
@@ -543,7 +406,7 @@ func (h *Handler) diagnoseForwardRuntime(forward *forwardRecord) (map[string]int
 							"fromInx":       currentNode.Inx,
 							"toChainType":   2,
 							"toInx":         nextNode.Inx,
-						})
+						}, "")
 					}
 				} else {
 					for _, outNode := range outNodes {
@@ -552,7 +415,7 @@ func (h *Handler) diagnoseForwardRuntime(forward *forwardRecord) (map[string]int
 							"fromChainType": 2,
 							"fromInx":       currentNode.Inx,
 							"toChainType":   3,
-						})
+						}, "")
 					}
 				}
 			}
@@ -591,13 +454,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 {
@@ -607,6 +470,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{}
@@ -628,7 +492,7 @@ func (h *Handler) diagnoseTunnelRuntime(tunnelID int64) (map[string]interface{},
 						"fromChainType": 1,
 						"toChainType":   2,
 						"toInx":         firstNode.Inx,
-					})
+					}, ipPreference)
 				}
 			} else {
 				for _, outNode := range outNodes {
@@ -636,7 +500,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)
 				}
 			}
 		}
@@ -651,7 +515,7 @@ func (h *Handler) diagnoseTunnelRuntime(tunnelID int64) (map[string]interface{},
 							"fromInx":       currentNode.Inx,
 							"toChainType":   2,
 							"toInx":         nextNode.Inx,
-						})
+						}, ipPreference)
 					}
 				} else {
 					for _, outNode := range outNodes {
@@ -660,7 +524,7 @@ func (h *Handler) diagnoseTunnelRuntime(tunnelID int64) (map[string]interface{},
 							"fromChainType": 2,
 							"fromInx":       currentNode.Inx,
 							"toChainType":   3,
-						})
+						}, ipPreference)
 					}
 				}
 			}
@@ -830,13 +694,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
@@ -844,11 +709,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("目标节点地址为空")
 	}
@@ -888,40 +756,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, ct.protocol, ct.strategy
-		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
-		var protocol sql.NullString
-		var strategy sql.NullString
-		if err := rows.Scan(&item.ChainType, &item.Inx, &item.NodeID, &item.Port, &name, &protocol, &strategy); err != nil {
-			return nil, err
-		}
-		if strings.TrimSpace(name.String) == "" {
-			item.NodeName = fmt.Sprintf("node_%d", item.NodeID)
-		} else {
-			item.NodeName = name.String
-		}
-		item.Protocol = defaultString(protocol.String, "tls")
-		item.Strategy = defaultString(strategy.String, "round")
-		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) {
@@ -1047,7 +882,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, limiterID *int64) []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)
@@ -1080,7 +915,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)

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.go

@@ -1,18 +1,19 @@
 package handler
 
 import (
-	"database/sql"
 	"encoding/json"
 	"fmt"
 	"net"
 	"net/http"
 	"sort"
+	"strconv"
 	"strings"
+	"sync"
 	"time"
 
 	"go-backend/internal/http/client"
 	"go-backend/internal/http/response"
-	"go-backend/internal/store/sqlite"
+	"go-backend/internal/store/repo"
 )
 
 type federationTunnelRequest struct {
@@ -40,6 +41,17 @@ type resetPeerShareFlowRequest struct {
 	ID int64 `json:"id"`
 }
 
+type updatePeerShareRequest struct {
+	ID             int64  `json:"id"`
+	Name           string `json:"name"`
+	MaxBandwidth   int64  `json:"maxBandwidth"`
+	ExpiryTime     int64  `json:"expiryTime"`
+	PortRangeStart int    `json:"portRangeStart"`
+	PortRangeEnd   int    `json:"portRangeEnd"`
+	AllowedDomains string `json:"allowedDomains"`
+	AllowedIPs     string `json:"allowedIps"`
+}
+
 type nodeImportRequest struct {
 	RemoteURL string `json:"remoteUrl"`
 	Token     string `json:"token"`
@@ -79,6 +91,11 @@ type federationRuntimeDiagnoseRequest struct {
 	Timeout int    `json:"timeout"`
 }
 
+type federationRuntimeCommandRequest struct {
+	CommandType string      `json:"commandType"`
+	Data        interface{} `json:"data"`
+}
+
 type peerShareUsedPort struct {
 	RuntimeID   int64  `json:"runtimeId"`
 	Port        int    `json:"port"`
@@ -90,7 +107,7 @@ type peerShareUsedPort struct {
 }
 
 type peerShareListItem struct {
-	sqlite.PeerShare
+	repo.PeerShare
 	UsedPorts        []int               `json:"usedPorts"`
 	UsedPortDetails  []peerShareUsedPort `json:"usedPortDetails"`
 	ActiveRuntimeNum int                 `json:"activeRuntimeNum"`
@@ -117,9 +134,11 @@ type remoteUsageNodeItem struct {
 	PortRangeEnd     int                      `json:"portRangeEnd"`
 	MaxBandwidth     int64                    `json:"maxBandwidth"`
 	CurrentFlow      int64                    `json:"currentFlow"`
+	ExpiryTime       int64                    `json:"expiryTime"`
 	UsedPorts        []int                    `json:"usedPorts"`
 	Bindings         []remoteUsageBindingItem `json:"bindings"`
 	ActiveBindingNum int                      `json:"activeBindingNum"`
+	SyncError        string                   `json:"syncError,omitempty"`
 }
 
 func (h *Handler) federationShareList(w http.ResponseWriter, r *http.Request) {
@@ -244,7 +263,7 @@ func (h *Handler) federationShareCreate(w http.ResponseWriter, r *http.Request)
 	now := time.Now().UnixMilli()
 	token := randomToken(32)
 
-	share := &sqlite.PeerShare{
+	share := &repo.PeerShare{
 		Name:           req.Name,
 		NodeID:         req.NodeID,
 		Token:          token,
@@ -279,11 +298,20 @@ func (h *Handler) federationShareDelete(w http.ResponseWriter, r *http.Request)
 		return
 	}
 
+	share, _ := h.repo.GetPeerShare(req.ID)
+
+	h.cleanupPeerShareRuntimes(req.ID)
+	h.cleanupFederationTunnels(req.ID)
+
 	if err := h.repo.DeletePeerShare(req.ID); err != nil {
 		response.WriteJSON(w, response.Err(-2, err.Error()))
 		return
 	}
 
+	if share != nil && h.wsServer != nil {
+		h.wsServer.SendCommand(share.NodeID, "reload", nil, time.Second*5)
+	}
+
 	response.WriteJSON(w, response.OKEmpty())
 }
 
@@ -321,71 +349,153 @@ func (h *Handler) federationShareResetFlow(w http.ResponseWriter, r *http.Reques
 	response.WriteJSON(w, response.OKEmpty())
 }
 
+func (h *Handler) federationShareUpdate(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		response.WriteJSON(w, response.ErrDefault("Invalid method"))
+		return
+	}
+
+	var req updatePeerShareRequest
+	if err := decodeJSON(r.Body, &req); err != nil {
+		response.WriteJSON(w, response.ErrDefault("Invalid JSON"))
+		return
+	}
+	if req.ID <= 0 {
+		response.WriteJSON(w, response.ErrDefault("Share ID is required"))
+		return
+	}
+
+	share, err := h.repo.GetPeerShare(req.ID)
+	if err != nil {
+		response.WriteJSON(w, response.Err(-2, err.Error()))
+		return
+	}
+	if share == nil {
+		response.WriteJSON(w, response.ErrDefault("Share not found"))
+		return
+	}
+
+	if req.Name == "" {
+		response.WriteJSON(w, response.ErrDefault("Name is required"))
+		return
+	}
+
+	if req.MaxBandwidth < 0 {
+		response.WriteJSON(w, response.ErrDefault("Max bandwidth cannot be negative"))
+		return
+	}
+
+	if req.ExpiryTime < 0 {
+		response.WriteJSON(w, response.ErrDefault("Expiry time cannot be negative"))
+		return
+	}
+
+	if req.PortRangeStart < 0 || req.PortRangeStart > 65535 || req.PortRangeEnd < 0 || req.PortRangeEnd > 65535 {
+		response.WriteJSON(w, response.ErrDefault("Invalid port range"))
+		return
+	}
+
+	if req.PortRangeStart > req.PortRangeEnd {
+		response.WriteJSON(w, response.ErrDefault("Port range start cannot be greater than end"))
+		return
+	}
+
+	allowedIPs, err := normalizePeerShareAllowedIPs(req.AllowedIPs)
+	if err != nil {
+		response.WriteJSON(w, response.ErrDefault(err.Error()))
+		return
+	}
+
+	share.Name = req.Name
+	share.MaxBandwidth = req.MaxBandwidth
+	share.ExpiryTime = req.ExpiryTime
+	share.PortRangeStart = req.PortRangeStart
+	share.PortRangeEnd = req.PortRangeEnd
+	share.AllowedDomains = req.AllowedDomains
+	share.AllowedIPs = allowedIPs
+	share.UpdatedTime = time.Now().UnixMilli()
+
+	if err := h.repo.UpdatePeerShare(share); err != nil {
+		response.WriteJSON(w, response.Err(-2, err.Error()))
+		return
+	}
+
+	response.WriteJSON(w, response.OKEmpty())
+}
+
 func (h *Handler) federationRemoteUsageList(w http.ResponseWriter, r *http.Request) {
 	if r.Method != http.MethodPost {
 		response.WriteJSON(w, response.ErrDefault("Invalid method"))
 		return
 	}
 
-	rows, err := h.repo.DB().Query(`
-		SELECT id, name, remote_url, remote_config
-		FROM node
-		WHERE is_remote = 1
-		ORDER BY id DESC
-	`)
+	remoteNodes, err := h.repo.ListRemoteNodes()
 	if err != nil {
 		response.WriteJSON(w, response.Err(-2, err.Error()))
 		return
 	}
-	defer rows.Close()
+
+	fc := client.NewFederationClient()
+	localDomain := h.federationLocalDomain()
 
 	items := make([]remoteUsageNodeItem, 0)
-	for rows.Next() {
-		var (
-			nodeID       int64
-			nodeName     string
-			remoteURL    sql.NullString
-			remoteConfig sql.NullString
-		)
-		if err := rows.Scan(&nodeID, &nodeName, &remoteURL, &remoteConfig); err != nil {
-			response.WriteJSON(w, response.Err(-2, err.Error()))
-			return
+	for _, node := range remoteNodes {
+		nodeID := node.ID
+		nodeName := node.Name
+
+		shareID, maxBandwidth, currentFlow, expiryTime, portRangeStart, portRangeEnd := parseRemoteShareUsageConfig(node.RemoteConfig.String)
+
+		var syncError string
+		url := strings.TrimSpace(node.RemoteURL.String)
+		token := strings.TrimSpace(node.RemoteToken.String)
+		if url != "" && token != "" {
+			info, connectErr := fc.Connect(url, token, localDomain)
+			if connectErr != nil {
+				syncError = connectErr.Error()
+			} else if info != nil {
+				shareID = info.ShareID
+				maxBandwidth = info.MaxBandwidth
+				currentFlow = info.CurrentFlow
+				expiryTime = info.ExpiryTime
+				portRangeStart = info.PortRangeStart
+				portRangeEnd = info.PortRangeEnd
+
+				configData, _ := json.Marshal(map[string]interface{}{
+					"shareId":        info.ShareID,
+					"maxBandwidth":   info.MaxBandwidth,
+					"currentFlow":    info.CurrentFlow,
+					"expiryTime":     info.ExpiryTime,
+					"portRangeStart": info.PortRangeStart,
+					"portRangeEnd":   info.PortRangeEnd,
+				})
+				_ = h.repo.UpdateNodeRemoteConfig(nodeID, string(configData))
+			}
 		}
 
-		shareID, maxBandwidth, currentFlow, portRangeStart, portRangeEnd := parseRemoteShareUsageConfig(remoteConfig.String)
-
-		bindingRows, err := h.repo.DB().Query(`
-			SELECT fb.id, fb.tunnel_id, COALESCE(t.name, ''), fb.chain_type, fb.hop_inx, fb.allocated_port, fb.resource_key, fb.remote_binding_id, fb.updated_time
-			FROM federation_tunnel_binding fb
-			LEFT JOIN tunnel t ON t.id = fb.tunnel_id
-			WHERE fb.node_id = ? AND fb.status = 1
-			ORDER BY fb.allocated_port ASC, fb.id ASC
-		`, nodeID)
+		bindingRows, err := h.repo.ListActiveBindingsForNode(nodeID)
 		if err != nil {
 			response.WriteJSON(w, response.Err(-2, err.Error()))
 			return
 		}
 
 		usedSet := make(map[int]struct{})
-		bindings := make([]remoteUsageBindingItem, 0)
-		for bindingRows.Next() {
-			var item remoteUsageBindingItem
-			if err := bindingRows.Scan(&item.BindingID, &item.TunnelID, &item.TunnelName, &item.ChainType, &item.HopInx, &item.AllocatedPort, &item.ResourceKey, &item.RemoteBindingID, &item.UpdatedTime); err != nil {
-				_ = bindingRows.Close()
-				response.WriteJSON(w, response.Err(-2, err.Error()))
-				return
-			}
-			bindings = append(bindings, item)
-			if item.AllocatedPort > 0 {
-				usedSet[item.AllocatedPort] = struct{}{}
+		bindings := make([]remoteUsageBindingItem, 0, len(bindingRows))
+		for _, b := range bindingRows {
+			bindings = append(bindings, remoteUsageBindingItem{
+				BindingID:       b.ID,
+				TunnelID:        b.TunnelID,
+				TunnelName:      b.TunnelName,
+				ChainType:       b.ChainType,
+				HopInx:          b.HopInx,
+				AllocatedPort:   b.AllocatedPort,
+				ResourceKey:     b.ResourceKey,
+				RemoteBindingID: b.RemoteBindingID,
+				UpdatedTime:     b.UpdatedTime,
+			})
+			if b.AllocatedPort > 0 {
+				usedSet[b.AllocatedPort] = struct{}{}
 			}
 		}
-		if err := bindingRows.Err(); err != nil {
-			_ = bindingRows.Close()
-			response.WriteJSON(w, response.Err(-2, err.Error()))
-			return
-		}
-		_ = bindingRows.Close()
 
 		usedPorts := make([]int, 0, len(usedSet))
 		for port := range usedSet {
@@ -396,42 +506,63 @@ func (h *Handler) federationRemoteUsageList(w http.ResponseWriter, r *http.Reque
 		items = append(items, remoteUsageNodeItem{
 			NodeID:           nodeID,
 			NodeName:         nodeName,
-			RemoteURL:        strings.TrimSpace(remoteURL.String),
+			RemoteURL:        url,
 			ShareID:          shareID,
 			PortRangeStart:   portRangeStart,
 			PortRangeEnd:     portRangeEnd,
 			MaxBandwidth:     maxBandwidth,
 			CurrentFlow:      currentFlow,
+			ExpiryTime:       expiryTime,
 			UsedPorts:        usedPorts,
 			Bindings:         bindings,
 			ActiveBindingNum: len(bindings),
+			SyncError:        syncError,
 		})
 	}
-	if err := rows.Err(); err != nil {
-		response.WriteJSON(w, response.Err(-2, err.Error()))
-		return
-	}
 
 	response.WriteJSON(w, response.OK(items))
 }
 
-func parseRemoteShareUsageConfig(raw string) (int64, int64, int64, int, int) {
+func remoteNodePortRange(node *nodeRecord) (int, int) {
+	if node == nil || node.IsRemote != 1 || node.RemoteConfig == "" {
+		return 0, 0
+	}
+	_, _, _, _, portRangeStart, portRangeEnd := parseRemoteShareUsageConfig(node.RemoteConfig)
+	return portRangeStart, portRangeEnd
+}
+
+func validateRemoteNodePort(node *nodeRecord, port int) error {
+	if node == nil || node.IsRemote != 1 || port <= 0 {
+		return nil
+	}
+	start, end := remoteNodePortRange(node)
+	if start <= 0 || end <= 0 {
+		return nil
+	}
+	if port < start || port > end {
+		return fmt.Errorf("远程节点端口 %d 超出允许范围 %d-%d", port, start, end)
+	}
+	return nil
+}
+
+func parseRemoteShareUsageConfig(raw string) (int64, int64, int64, int64, int, int) {
 	raw = strings.TrimSpace(raw)
 	if raw == "" {
-		return 0, 0, 0, 0, 0
+		return 0, 0, 0, 0, 0, 0
 	}
 
 	var cfg map[string]interface{}
 	if err := json.Unmarshal([]byte(raw), &cfg); err != nil {
-		return 0, 0, 0, 0, 0
+		return 0, 0, 0, 0, 0, 0
 	}
 
 	shareID := asInt64(cfg["shareId"], 0)
 	maxBandwidth := asInt64(cfg["maxBandwidth"], 0)
 	currentFlow := asInt64(cfg["currentFlow"], 0)
+	expiryTime := asInt64(cfg["expiryTime"], 0)
 	portRangeStart := int(asInt64(cfg["portRangeStart"], 0))
 	portRangeEnd := int(asInt64(cfg["portRangeEnd"], 0))
-	return shareID, maxBandwidth, currentFlow, portRangeStart, portRangeEnd
+	return shareID, maxBandwidth, currentFlow, expiryTime, portRangeStart, portRangeEnd
 }
 
 func (h *Handler) nodeImport(w http.ResponseWriter, r *http.Request) {
@@ -480,31 +611,21 @@ func (h *Handler) nodeImport(w http.ResponseWriter, r *http.Request) {
 		portRange = fmt.Sprintf("%d-%d", info.PortRangeStart, info.PortRangeEnd)
 	}
 
-	db := h.repo.DB()
-	inx := nextIndex(db, "node")
+	inx := h.repo.NextIndex("node")
 	now := time.Now().UnixMilli()
 
-	_, err = 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, ?, ?, ?)
-	`,
+	if err = h.repo.CreateRemoteNode(
 		fmt.Sprintf("%s (Remote)", info.NodeName),
-		randomToken(16), // Dummy secret
+		randomToken(16),
 		info.ServerIP,
-		"", "", // v4/v6 unknown, use server_ip
 		portRange,
-		"",
-		"",
-		now, now,
+		now,
 		info.Status,
-		"[::]", "[::]",
 		inx,
 		req.RemoteURL,
 		req.Token,
 		string(configBytes),
-	)
-
-	if err != nil {
+	); err != nil {
 		response.WriteJSON(w, response.Err(-2, "Database error: "+err.Error()))
 		return
 	}
@@ -596,11 +717,7 @@ func (h *Handler) federationConnect(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	var nodeName string
-	var serverIP string
-	var status int
-
-	err = h.repo.DB().QueryRow("SELECT name, server_ip, status FROM node WHERE id = ?", share.NodeID).Scan(&nodeName, &serverIP, &status)
+	nodeInfo, err := h.repo.GetNodeBasicInfo(share.NodeID)
 	if err != nil {
 		response.WriteJSON(w, response.Err(-2, "Node not found"))
 		return
@@ -610,9 +727,9 @@ func (h *Handler) federationConnect(w http.ResponseWriter, r *http.Request) {
 		"shareId":        share.ID,
 		"shareName":      share.Name,
 		"nodeId":         share.NodeID,
-		"nodeName":       nodeName,
-		"serverIp":       serverIP,
-		"status":         status,
+		"nodeName":       nodeInfo.Name,
+		"serverIp":       nodeInfo.ServerIP,
+		"status":         nodeInfo.Status,
 		"maxBandwidth":   share.MaxBandwidth,
 		"currentFlow":    share.CurrentFlow,
 		"expiryTime":     share.ExpiryTime,
@@ -649,50 +766,20 @@ func (h *Handler) federationTunnelCreate(w http.ResponseWriter, r *http.Request)
 		return
 	}
 
-	tunnelType := 1
-	if strings.ToLower(req.Protocol) == "udp" {
-		tunnelType = 2
-	}
-
-	tx, err := h.repo.DB().Begin()
-	if err != nil {
-		response.WriteJSON(w, response.Err(-2, err.Error()))
-		return
-	}
-	defer tx.Rollback()
-
 	now := time.Now().UnixMilli()
-	res, err := tx.Exec(`INSERT INTO tunnel (name, type, protocol, flow, created_time, updated_time, status, in_ip) VALUES (?, ?, ?, 0, ?, ?, 1, ?)`,
+	tunnelID, err := h.repo.CreateFederationTunnel(
 		fmt.Sprintf("Share-%d-Port-%d", share.ID, req.RemotePort),
-		tunnelType,
+		1,
 		req.Protocol,
 		now,
-		now,
-		"",
-	)
-	if err != nil {
-		response.WriteJSON(w, response.Err(-2, err.Error()))
-		return
-	}
-
-	tunnelID, _ := res.LastInsertId()
-
-	_, err = tx.Exec(`INSERT INTO chain_tunnel (tunnel_id, chain_type, node_id, port, strategy, inx, protocol) VALUES (?, 1, ?, ?, 'fifo', 0, ?)`,
-		tunnelID,
 		share.NodeID,
 		req.RemotePort,
-		req.Protocol,
 	)
 	if err != nil {
 		response.WriteJSON(w, response.Err(-2, err.Error()))
 		return
 	}
 
-	if err := tx.Commit(); err != nil {
-		response.WriteJSON(w, response.Err(-2, err.Error()))
-		return
-	}
-
 	h.wsServer.SendCommand(share.NodeID, "reload", nil, time.Second*5)
 
 	response.WriteJSON(w, response.OK(map[string]interface{}{
@@ -773,7 +860,7 @@ func (h *Handler) federationRuntimeReservePort(w http.ResponseWriter, r *http.Re
 		return
 	}
 
-	runtime := &sqlite.PeerShareRuntime{
+	runtime := &repo.PeerShareRuntime{
 		ShareID:       share.ID,
 		NodeID:        share.NodeID,
 		ReservationID: randomToken(24),
@@ -827,7 +914,7 @@ func (h *Handler) federationRuntimeApplyRole(w http.ResponseWriter, r *http.Requ
 		return
 	}
 
-	var runtime *sqlite.PeerShareRuntime
+	var runtime *repo.PeerShareRuntime
 	if strings.TrimSpace(req.ReservationID) != "" {
 		runtime, err = h.repo.GetPeerShareRuntimeByReservationID(share.ID, strings.TrimSpace(req.ReservationID))
 	} else {
@@ -855,6 +942,13 @@ func (h *Handler) federationRuntimeApplyRole(w http.ResponseWriter, r *http.Requ
 		return
 	}
 
+	if share.PortRangeStart > 0 && share.PortRangeEnd > 0 && runtime.Port > 0 {
+		if runtime.Port < share.PortRangeStart || runtime.Port > share.PortRangeEnd {
+			response.WriteJSON(w, response.Err(403, fmt.Sprintf("port %d out of allowed range %d-%d", runtime.Port, share.PortRangeStart, share.PortRangeEnd)))
+			return
+		}
+	}
+
 	node, err := h.getNodeRecord(share.NodeID)
 	if err != nil {
 		response.WriteJSON(w, response.ErrDefault(err.Error()))
@@ -878,14 +972,19 @@ func (h *Handler) federationRuntimeApplyRole(w http.ResponseWriter, r *http.Requ
 				response.WriteJSON(w, response.ErrDefault("Invalid target"))
 				return
 			}
+			targetProtocol := defaultString(target.Protocol, protocol)
+			connector := map[string]interface{}{
+				"type": "relay",
+			}
+			if isTLSTunnelProtocol(targetProtocol) {
+				connector["metadata"] = map[string]interface{}{"nodelay": true}
+			}
 			nodeItems = append(nodeItems, map[string]interface{}{
-				"name": fmt.Sprintf("node_%d", i+1),
-				"addr": processServerAddress(fmt.Sprintf("%s:%d", host, target.Port)),
-				"connector": map[string]interface{}{
-					"type": "relay",
-				},
+				"name":      fmt.Sprintf("node_%d", i+1),
+				"addr":      processServerAddress(fmt.Sprintf("%s:%d", host, target.Port)),
+				"connector": connector,
 				"dialer": map[string]interface{}{
-					"type": defaultString(target.Protocol, protocol),
+					"type": targetProtocol,
 				},
 			})
 		}
@@ -924,6 +1023,9 @@ func (h *Handler) federationRuntimeApplyRole(w http.ResponseWriter, r *http.Requ
 			"type": protocol,
 		},
 	}
+	if isTLSTunnelProtocol(protocol) {
+		service["handler"].(map[string]interface{})["metadata"] = map[string]interface{}{"nodelay": true}
+	}
 	if req.Role == "middle" {
 		service["handler"].(map[string]interface{})["chain"] = chainName
 	}
@@ -983,7 +1085,7 @@ func (h *Handler) federationRuntimeReleaseRole(w http.ResponseWriter, r *http.Re
 		return
 	}
 
-	var runtime *sqlite.PeerShareRuntime
+	var runtime *repo.PeerShareRuntime
 	if strings.TrimSpace(req.BindingID) != "" {
 		runtime, err = h.repo.GetPeerShareRuntimeByBindingID(share.ID, strings.TrimSpace(req.BindingID))
 	} else if strings.TrimSpace(req.ReservationID) != "" {
@@ -1069,7 +1171,108 @@ func (h *Handler) federationRuntimeDiagnose(w http.ResponseWriter, r *http.Reque
 	response.WriteJSON(w, response.OK(res.Data))
 }
 
-func (h *Handler) pickPeerSharePort(share *sqlite.PeerShare, requestedPort int) (int, error) {
+func (h *Handler) federationRuntimeCommand(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		response.WriteJSON(w, response.ErrDefault("Invalid method"))
+		return
+	}
+
+	token := extractBearerToken(r)
+	share, err := h.repo.GetPeerShareByToken(token)
+	if err != nil || share == nil {
+		response.WriteJSON(w, response.Err(401, "Unauthorized"))
+		return
+	}
+
+	var req federationRuntimeCommandRequest
+	if err := decodeJSON(r.Body, &req); err != nil {
+		response.WriteJSON(w, response.ErrDefault("Invalid JSON"))
+		return
+	}
+	cmd := strings.TrimSpace(req.CommandType)
+	if cmd == "" {
+		response.WriteJSON(w, response.ErrDefault("commandType is required"))
+		return
+	}
+	if !isFederationRuntimeCommandAllowed(cmd) {
+		response.WriteJSON(w, response.ErrDefault("command not allowed"))
+		return
+	}
+
+	if isFederationServiceCommand(cmd) {
+		if err := validateFederationCommandPorts(share, req.Data); err != nil {
+			response.WriteJSON(w, response.Err(403, err.Error()))
+			return
+		}
+	}
+
+	res, err := h.sendNodeCommand(share.NodeID, cmd, req.Data, false, false)
+	if err != nil {
+		response.WriteJSON(w, response.ErrDefault(err.Error()))
+		return
+	}
+	response.WriteJSON(w, response.OK(res))
+}
+
+func isFederationRuntimeCommandAllowed(commandType string) bool {
+	switch strings.ToLower(strings.TrimSpace(commandType)) {
+	case "addservice", "updateservice", "deleteservice", "pauseservice", "resumeservice", "addchains", "deletechains", "addlimiters", "deletelimiters", "tcpping", "reload":
+		return true
+	default:
+		return false
+	}
+}
+
+func isFederationServiceCommand(commandType string) bool {
+	switch strings.ToLower(strings.TrimSpace(commandType)) {
+	case "addservice", "updateservice":
+		return true
+	default:
+		return false
+	}
+}
+
+func validateFederationCommandPorts(share *repo.PeerShare, data interface{}) error {
+	if share == nil || (share.PortRangeStart <= 0 && share.PortRangeEnd <= 0) {
+		return nil
+	}
+	dataMap, ok := data.(map[string]interface{})
+	if !ok {
+		return nil
+	}
+
+	if services, ok := dataMap["services"]; ok {
+		serviceList, ok := services.([]interface{})
+		if !ok {
+			return fmt.Errorf("invalid services format")
+		}
+		for _, svc := range serviceList {
+			svcMap, ok := svc.(map[string]interface{})
+			if !ok {
+				return fmt.Errorf("invalid service entry format")
+			}
+			addr, ok := svcMap["addr"].(string)
+			if !ok || addr == "" {
+				continue
+			}
+			_, portStr, err := net.SplitHostPort(addr)
+			if err != nil {
+				return fmt.Errorf("invalid service address: %s", addr)
+			}
+			port, err := strconv.Atoi(portStr)
+			if err != nil || port <= 0 {
+				return fmt.Errorf("invalid port in service address: %s", addr)
+			}
+			if port < share.PortRangeStart || port > share.PortRangeEnd {
+				return fmt.Errorf("port %d out of allowed range %d-%d", port, share.PortRangeStart, share.PortRangeEnd)
+			}
+		}
+	}
+
+	return nil
+}
+
+func (h *Handler) pickPeerSharePort(share *repo.PeerShare, requestedPort int) (int, error) {
 	if share == nil {
 		return 0, fmt.Errorf("share not found")
 	}
@@ -1079,29 +1282,13 @@ func (h *Handler) pickPeerSharePort(share *sqlite.PeerShare, requestedPort int)
 
 	used := make(map[int]struct{})
 
-	rows, err := h.repo.DB().Query(`SELECT port FROM chain_tunnel WHERE node_id = ? AND port IS NOT NULL AND port > 0`, share.NodeID)
+	nodePorts, err := h.repo.ListUsedPortsOnNode(share.NodeID)
 	if err != nil {
 		return 0, err
 	}
-	for rows.Next() {
-		var p sql.NullInt64
-		if scanErr := rows.Scan(&p); scanErr == nil && p.Valid && p.Int64 > 0 {
-			used[int(p.Int64)] = struct{}{}
-		}
+	for _, p := range nodePorts {
+		used[p] = struct{}{}
 	}
-	_ = rows.Close()
-
-	rows, err = h.repo.DB().Query(`SELECT port FROM forward_port WHERE node_id = ? AND port > 0`, share.NodeID)
-	if err != nil {
-		return 0, err
-	}
-	for rows.Next() {
-		var p sql.NullInt64
-		if scanErr := rows.Scan(&p); scanErr == nil && p.Valid && p.Int64 > 0 {
-			used[int(p.Int64)] = struct{}{}
-		}
-	}
-	_ = rows.Close()
 
 	ports, err := h.repo.ListActivePeerShareRuntimePorts(share.ID, share.NodeID)
 	if err != nil {
@@ -1142,7 +1329,7 @@ func extractBearerToken(r *http.Request) string {
 	return ""
 }
 
-func isPeerShareFlowExceeded(share *sqlite.PeerShare) bool {
+func isPeerShareFlowExceeded(share *repo.PeerShare) bool {
 	if share == nil {
 		return false
 	}
@@ -1226,7 +1413,7 @@ func parseIPLiteral(raw string) net.IP {
 	}
 
 	if ip := net.ParseIP(value); ip != nil {
-		return ip
+		return normalizeIPAddress(ip)
 	}
 
 	host, _, err := net.SplitHostPort(value)
@@ -1238,7 +1425,17 @@ func parseIPLiteral(raw string) net.IP {
 	if host == "" {
 		return nil
 	}
-	return net.ParseIP(host)
+	return normalizeIPAddress(net.ParseIP(host))
+}
+
+func normalizeIPAddress(ip net.IP) net.IP {
+	if ip == nil {
+		return nil
+	}
+	if v4 := ip.To4(); v4 != nil {
+		return v4
+	}
+	return ip.To16()
 }
 
 func isTrustedProxyIP(ip net.IP) bool {
@@ -1278,3 +1475,109 @@ func isPeerIPAllowed(clientIP net.IP, whitelist string) bool {
 
 	return false
 }
+
+func (h *Handler) syncRemoteNodeStatuses(items []map[string]interface{}) {
+	type remoteEntry struct {
+		index       int
+		remoteURL   string
+		remoteToken string
+	}
+
+	var remotes []remoteEntry
+	for i, item := range items {
+		isRemote, _ := item["isRemote"].(int)
+		if isRemote != 1 {
+			continue
+		}
+		url, _ := item["remoteUrl"].(string)
+		token, _ := item["remoteToken"].(string)
+		url = strings.TrimSpace(url)
+		token = strings.TrimSpace(token)
+		if url == "" || token == "" {
+			continue
+		}
+		remotes = append(remotes, remoteEntry{index: i, remoteURL: url, remoteToken: token})
+	}
+	if len(remotes) == 0 {
+		return
+	}
+
+	localDomain := h.federationLocalDomain()
+	fc := client.NewFederationClientWithTimeout(5 * time.Second)
+
+	type syncResult struct {
+		index     int
+		status    int
+		syncError string
+	}
+
+	results := make([]syncResult, len(remotes))
+	var wg sync.WaitGroup
+	for i, entry := range remotes {
+		wg.Add(1)
+		go func(idx int, e remoteEntry) {
+			defer wg.Done()
+			info, err := fc.Connect(e.remoteURL, e.remoteToken, localDomain)
+			if err != nil {
+				errMsg := err.Error()
+				if strings.Contains(errMsg, "401") || strings.Contains(errMsg, "Invalid token") || strings.Contains(errMsg, "Unauthorized") {
+					results[idx] = syncResult{index: e.index, status: 0, syncError: "provider_share_deleted"}
+				} else if strings.Contains(errMsg, "403") || strings.Contains(errMsg, "Share is disabled") {
+					results[idx] = syncResult{index: e.index, status: 0, syncError: "provider_share_disabled"}
+				} else if strings.Contains(errMsg, "Share expired") {
+					results[idx] = syncResult{index: e.index, status: 0, syncError: "provider_share_expired"}
+				} else {
+					results[idx] = syncResult{index: e.index, status: 0, syncError: errMsg}
+				}
+			} else {
+				results[idx] = syncResult{index: e.index, status: info.Status, syncError: ""}
+			}
+		}(i, entry)
+	}
+	wg.Wait()
+
+	for _, r := range results {
+		items[r.index]["status"] = r.status
+		if r.syncError != "" {
+			items[r.index]["syncError"] = r.syncError
+		}
+	}
+}
+
+func (h *Handler) cleanupPeerShareRuntimes(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) cleanupFederationTunnels(shareID int64) {
+	if h == nil || h.repo == nil || shareID <= 0 {
+		return
+	}
+	namePrefix := fmt.Sprintf("Share-%d-Port-", shareID)
+	tunnelIDs, err := h.repo.ListTunnelIDsByNamePrefix(namePrefix)
+	if err != nil || len(tunnelIDs) == 0 {
+		return
+	}
+
+	for _, tid := range tunnelIDs {
+		_ = h.deleteTunnelByID(tid)
+	}
+}

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

@@ -10,33 +10,33 @@ import (
 	"time"
 
 	"go-backend/internal/http/response"
-	"go-backend/internal/store/sqlite"
+	"go-backend/internal/store/repo"
 )
 
 func TestPickPeerSharePortUsesRuntimeReservations(t *testing.T) {
-	repo, err := sqlite.Open(filepath.Join(t.TempDir(), "panel.db"))
+	r, err := repo.Open(filepath.Join(t.TempDir(), "panel.db"))
 	if err != nil {
 		t.Fatalf("open repo: %v", err)
 	}
-	defer repo.Close()
+	defer r.Close()
 
-	h := &Handler{repo: repo}
+	h := &Handler{repo: r}
 	now := time.Now().UnixMilli()
 
-	if _, err := repo.DB().Exec(`INSERT INTO chain_tunnel(tunnel_id, chain_type, node_id, port, strategy, inx, protocol) VALUES(?, ?, ?, ?, ?, ?, ?)`, 1, 2, 1, 3000, "round", 1, "tls"); err != nil {
+	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 := repo.DB().Exec(`INSERT INTO forward_port(forward_id, node_id, port) VALUES(?, ?, ?)`, 1, 1, 3001); err != nil {
+	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 := repo.DB().Exec(`
+	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); err != nil {
+	`, 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 := &sqlite.PeerShare{
+	share := &repo.PeerShare{
 		ID:             77,
 		NodeID:         1,
 		PortRangeStart: 3000,
@@ -56,14 +56,35 @@ func TestPickPeerSharePortUsesRuntimeReservations(t *testing.T) {
 	}
 }
 
-func TestApplyTunnelRuntimeSkipsRemoteNodes(t *testing.T) {
-	h := &Handler{}
+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{
-			{NodeID: 11, ChainType: 1, Protocol: "tls"},
-		},
+		InNodes:  []tunnelRuntimeNode{},
 		ChainHops: [][]tunnelRuntimeNode{
 			{
 				{NodeID: 12, ChainType: 2, Inx: 1, Port: 41000, Protocol: "tls", Strategy: "round"},
@@ -73,9 +94,8 @@ func TestApplyTunnelRuntimeSkipsRemoteNodes(t *testing.T) {
 			{NodeID: 13, ChainType: 3, Port: 42000, Protocol: "tls", Strategy: "round"},
 		},
 		Nodes: map[int64]*nodeRecord{
-			11: {ID: 11, Name: "remote-in", IsRemote: 1},
-			12: {ID: 12, Name: "remote-chain", IsRemote: 1},
-			13: {ID: 13, Name: "remote-out", IsRemote: 1},
+			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"},
 		},
 	}
 
@@ -84,47 +104,42 @@ func TestApplyTunnelRuntimeSkipsRemoteNodes(t *testing.T) {
 		t.Fatalf("apply runtime: %v", err)
 	}
 	if len(chains) != 0 {
-		t.Fatalf("expected no local chains created, got %d", len(chains))
+		t.Fatalf("expected no local chains for remote-only nodes, got %d", len(chains))
 	}
 	if len(services) != 0 {
-		t.Fatalf("expected no local services created, got %d", len(services))
+		t.Fatalf("expected no local services for remote-only nodes, got %d", len(services))
 	}
 }
 
 func TestPrepareTunnelCreateStateRemoteAutoPortDefersToFederation(t *testing.T) {
-	repo, err := sqlite.Open(filepath.Join(t.TempDir(), "panel.db"))
+	r, err := repo.Open(filepath.Join(t.TempDir(), "panel.db"))
 	if err != nil {
 		t.Fatalf("open repo: %v", err)
 	}
-	defer repo.Close()
+	defer r.Close()
 
-	h := &Handler{repo: repo}
+	h := &Handler{repo: r}
 	now := time.Now().UnixMilli()
 
 	insertNode := func(name string, status int, portRange string, isRemote int) int64 {
-		res, execErr := repo.DB().Exec(`
+		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}`)
-		if execErr != nil {
+		`, 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)
 		}
-		id, idErr := res.LastInsertId()
-		if idErr != nil {
-			t.Fatalf("node id %s: %v", name, idErr)
-		}
-		return id
+		return mustLastInsertID(t, r, name)
 	}
 
 	entryID := insertNode("entry", 1, "31000-31010", 0)
 	remoteOutID := insertNode("remote-out", 1, "30000", 1)
 
-	if _, err := repo.DB().Exec(`INSERT INTO forward_port(forward_id, node_id, port) VALUES(?, ?, ?)`, 1, remoteOutID, 30000); err != nil {
+	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, err := repo.DB().Begin()
-	if err != nil {
+	tx := r.DB().Begin()
+	if tx.Error != nil {
 		t.Fatalf("begin tx: %v", err)
 	}
 	defer tx.Rollback()
@@ -152,17 +167,77 @@ func TestPrepareTunnelCreateStateRemoteAutoPortDefersToFederation(t *testing.T)
 	}
 }
 
-func TestFederationRuntimeReservePortRejectsWhenShareFlowExceeded(t *testing.T) {
-	repo, err := sqlite.Open(filepath.Join(t.TempDir(), "panel.db"))
+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 repo.Close()
+	defer r.Close()
 
-	h := &Handler{repo: repo}
+	h := &Handler{repo: r}
 	now := time.Now().UnixMilli()
 
-	if err := repo.CreatePeerShare(&sqlite.PeerShare{
+	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",

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

@@ -12,30 +12,26 @@ import (
 	"time"
 
 	"go-backend/internal/http/response"
-	"go-backend/internal/store/sqlite"
+	"go-backend/internal/store/repo"
 )
 
 func TestFederationShareCreateRejectsRemoteNode(t *testing.T) {
-	repo, err := sqlite.Open(filepath.Join(t.TempDir(), "panel.db"))
+	r, err := repo.Open(filepath.Join(t.TempDir(), "panel.db"))
 	if err != nil {
 		t.Fatalf("open sqlite: %v", err)
 	}
-	t.Cleanup(func() { _ = repo.Close() })
+	t.Cleanup(func() { _ = r.Close() })
 
-	h := New(repo, "test-jwt-secret")
+	h := New(r, "test-jwt-secret")
 	now := time.Now().UnixMilli()
 
-	insertRes, 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, is_remote, remote_url, remote_token, remote_config)
 		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-	`, "remote-share-node", "remote-share-secret", "10.10.10.1", "10.10.10.1", "", "20000-20010", "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", 0, 1, "http://peer.example", "peer-token", `{"shareId":1}`)
-	if err != nil {
+	`, "remote-share-node", "remote-share-secret", "10.10.10.1", "10.10.10.1", "", "20000-20010", "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", 0, 1, "http://peer.example", "peer-token", `{"shareId":1}`).Error; err != nil {
 		t.Fatalf("insert remote node: %v", err)
 	}
-	remoteNodeID, err := insertRes.LastInsertId()
-	if err != nil {
-		t.Fatalf("get remote node id: %v", err)
-	}
+	remoteNodeID := mustLastInsertID(t, r, "remote-share-node")
 
 	body, err := json.Marshal(createPeerShareRequest{
 		Name:           "remote-node-share",
@@ -70,36 +66,29 @@ func TestFederationShareCreateRejectsRemoteNode(t *testing.T) {
 		t.Fatalf("expected rejection message %q, got %q", "Only local nodes can be shared", payload.Msg)
 	}
 
-	var shareCount int
-	if err := repo.DB().QueryRow(`SELECT COUNT(1) FROM peer_share WHERE node_id = ?`, remoteNodeID).Scan(&shareCount); err != nil {
-		t.Fatalf("query peer_share count: %v", err)
-	}
+	shareCount := mustQueryInt(t, r, `SELECT COUNT(1) FROM peer_share WHERE node_id = ?`, remoteNodeID)
 	if shareCount != 0 {
 		t.Fatalf("expected no share rows for remote node, got %d", shareCount)
 	}
 }
 
 func TestFederationShareCreateRejectsInvalidAllowedIPs(t *testing.T) {
-	repo, err := sqlite.Open(filepath.Join(t.TempDir(), "panel.db"))
+	r, err := repo.Open(filepath.Join(t.TempDir(), "panel.db"))
 	if err != nil {
 		t.Fatalf("open sqlite: %v", err)
 	}
-	t.Cleanup(func() { _ = repo.Close() })
+	t.Cleanup(func() { _ = r.Close() })
 
-	h := New(repo, "test-jwt-secret")
+	h := New(r, "test-jwt-secret")
 	now := time.Now().UnixMilli()
 
-	insertRes, 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, is_remote, remote_url, remote_token, remote_config)
 		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-	`, "local-share-node", "local-share-secret", "10.20.30.40", "10.20.30.40", "", "21000-21010", "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", 0, 0, "", "", "")
-	if err != nil {
+	`, "local-share-node", "local-share-secret", "10.20.30.40", "10.20.30.40", "", "21000-21010", "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", 0, 0, "", "", "").Error; err != nil {
 		t.Fatalf("insert local node: %v", err)
 	}
-	localNodeID, err := insertRes.LastInsertId()
-	if err != nil {
-		t.Fatalf("get local node id: %v", err)
-	}
+	localNodeID := mustLastInsertID(t, r, "local-share-node")
 
 	body, err := json.Marshal(createPeerShareRequest{
 		Name:           "local-node-share",
@@ -135,26 +124,23 @@ func TestFederationShareCreateRejectsInvalidAllowedIPs(t *testing.T) {
 		t.Fatalf("expected invalid IP message, got %q", payload.Msg)
 	}
 
-	var shareCount int
-	if err := repo.DB().QueryRow(`SELECT COUNT(1) FROM peer_share WHERE node_id = ?`, localNodeID).Scan(&shareCount); err != nil {
-		t.Fatalf("query peer_share count: %v", err)
-	}
+	shareCount := mustQueryInt(t, r, `SELECT COUNT(1) FROM peer_share WHERE node_id = ?`, localNodeID)
 	if shareCount != 0 {
 		t.Fatalf("expected no share rows for node, got %d", shareCount)
 	}
 }
 
 func TestFederationShareListIncludesRemoteUsedPorts(t *testing.T) {
-	repo, err := sqlite.Open(filepath.Join(t.TempDir(), "panel.db"))
+	r, err := repo.Open(filepath.Join(t.TempDir(), "panel.db"))
 	if err != nil {
 		t.Fatalf("open sqlite: %v", err)
 	}
-	t.Cleanup(func() { _ = repo.Close() })
+	t.Cleanup(func() { _ = r.Close() })
 
-	h := New(repo, "test-jwt-secret")
+	h := New(r, "test-jwt-secret")
 	now := time.Now().UnixMilli()
 
-	if err := repo.CreatePeerShare(&sqlite.PeerShare{
+	if err := r.CreatePeerShare(&repo.PeerShare{
 		Name:           "provider-share",
 		NodeID:         9,
 		Token:          "share-list-token",
@@ -169,12 +155,12 @@ func TestFederationShareListIncludesRemoteUsedPorts(t *testing.T) {
 		t.Fatalf("create peer share: %v", err)
 	}
 
-	share, err := repo.GetPeerShareByToken("share-list-token")
+	share, err := r.GetPeerShareByToken("share-list-token")
 	if err != nil || share == nil {
 		t.Fatalf("load peer share: %v", err)
 	}
 
-	if _, err := repo.DB().Exec(`
+	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(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?),
 		      (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?),
@@ -183,7 +169,7 @@ func TestFederationShareListIncludesRemoteUsedPorts(t *testing.T) {
 		share.ID, share.NodeID, "r-1", "rk-1", "b-1", "middle", "fed_chain_1", "fed_svc_1", "tls", "round", 22001, "", 1, 1, now, now,
 		share.ID, share.NodeID, "r-2", "rk-2", "b-2", "exit", "", "fed_svc_2", "tls", "round", 22002, "", 1, 1, now, now,
 		share.ID, share.NodeID, "r-3", "rk-3", "", "", "", "", "tls", "round", 22003, "", 0, 0, now, now,
-	); err != nil {
+	).Error; err != nil {
 		t.Fatalf("insert peer_share_runtime rows: %v", err)
 	}
 
@@ -237,16 +223,149 @@ func TestFederationShareListIncludesRemoteUsedPorts(t *testing.T) {
 	}
 }
 
-func TestFederationShareResetFlow(t *testing.T) {
-	repo, err := sqlite.Open(filepath.Join(t.TempDir(), "panel.db"))
+func TestFederationShareDeleteCleansUpRuntimes(t *testing.T) {
+	r, err := repo.Open(filepath.Join(t.TempDir(), "panel.db"))
 	if err != nil {
 		t.Fatalf("open sqlite: %v", err)
 	}
-	t.Cleanup(func() { _ = repo.Close() })
+	t.Cleanup(func() { _ = r.Close() })
 
-	h := New(repo, "test-jwt-secret")
+	h := New(r, "test-jwt-secret")
 	now := time.Now().UnixMilli()
-	if err := repo.CreatePeerShare(&sqlite.PeerShare{
+
+	if err := r.CreatePeerShare(&repo.PeerShare{
+		Name:           "delete-cleanup-share",
+		NodeID:         99,
+		Token:          "delete-cleanup-token",
+		MaxBandwidth:   4096,
+		PortRangeStart: 40000,
+		PortRangeEnd:   40010,
+		IsActive:       1,
+		CreatedTime:    now,
+		UpdatedTime:    now,
+	}); err != nil {
+		t.Fatalf("create peer share: %v", err)
+	}
+
+	share, err := r.GetPeerShareByToken("delete-cleanup-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, 99, "dc-r1", "dc-rk1", "dc-b1", "exit", "", "fed_svc_dc1", "tls", "round", 40001, "", 1, 1, now, now,
+		share.ID, 99, "dc-r2", "dc-rk2", "dc-b2", "middle", "fed_chain_dc2", "fed_svc_dc2", "tls", "round", 40002, "", 1, 1, now, now,
+	).Error; err != nil {
+		t.Fatalf("insert peer_share_runtime rows: %v", err)
+	}
+
+	runtimeCount := mustQueryInt(t, r, `SELECT COUNT(1) FROM peer_share_runtime WHERE share_id = ? AND status = 1`, share.ID)
+	if runtimeCount != 2 {
+		t.Fatalf("expected 2 active runtimes before delete, got %d", runtimeCount)
+	}
+
+	body, err := json.Marshal(deletePeerShareRequest{ID: share.ID})
+	if err != nil {
+		t.Fatalf("marshal request: %v", err)
+	}
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/federation/share/delete", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	res := httptest.NewRecorder()
+
+	h.federationShareDelete(res, req)
+
+	if res.Code != http.StatusOK {
+		t.Fatalf("expected status %d, got %d", http.StatusOK, res.Code)
+	}
+	var payload response.R
+	if err := json.NewDecoder(res.Body).Decode(&payload); err != nil {
+		t.Fatalf("decode response: %v", err)
+	}
+	if payload.Code != 0 {
+		t.Fatalf("expected response code 0, got %d (%s)", payload.Code, payload.Msg)
+	}
+
+	shareCount := mustQueryInt(t, r, `SELECT COUNT(1) FROM peer_share WHERE id = ?`, share.ID)
+	if shareCount != 0 {
+		t.Fatalf("expected peer_share deleted, got %d rows", shareCount)
+	}
+
+	runtimeCountAfter := mustQueryInt(t, r, `SELECT COUNT(1) FROM peer_share_runtime WHERE share_id = ?`, share.ID)
+	if runtimeCountAfter != 0 {
+		t.Fatalf("expected all peer_share_runtime rows deleted, got %d", runtimeCountAfter)
+	}
+}
+
+func TestFederationRemoteUsageListSyncErrorFallback(t *testing.T) {
+	r, err := repo.Open(filepath.Join(t.TempDir(), "panel.db"))
+	if err != nil {
+		t.Fatalf("open sqlite: %v", err)
+	}
+	t.Cleanup(func() { _ = r.Close() })
+
+	h := New(r, "test-jwt-secret")
+	now := time.Now().UnixMilli()
+
+	if err := r.DB().Exec(`
+		INSERT INTO node(name, secret, server_ip, server_ip_v4, server_ip_v6, port, interface_name, version, http, tls, socks, created_time, updated_time, status, tcp_listen_addr, udp_listen_addr, inx, is_remote, remote_url, remote_token, remote_config)
+		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`, "sync-error-node", "sync-error-secret", "10.50.60.70", "10.50.60.70", "", "32000-32010", "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", 0, 1, "http://unreachable.invalid:9999", "bad-token", `{"shareId":42,"maxBandwidth":5368709120,"currentFlow":999999,"portRangeStart":32000,"portRangeEnd":32010}`).Error; err != nil {
+		t.Fatalf("insert remote node: %v", err)
+	}
+
+	req := httptest.NewRequest(http.MethodPost, "/api/v1/federation/share/remote-usage/list", nil)
+	res := httptest.NewRecorder()
+	h.federationRemoteUsageList(res, req)
+
+	if res.Code != http.StatusOK {
+		t.Fatalf("expected status %d, got %d", http.StatusOK, res.Code)
+	}
+
+	var payload response.R
+	if err := json.NewDecoder(res.Body).Decode(&payload); err != nil {
+		t.Fatalf("decode response: %v", err)
+	}
+	if payload.Code != 0 {
+		t.Fatalf("expected response code 0, got %d (%s)", payload.Code, payload.Msg)
+	}
+
+	rows, ok := payload.Data.([]interface{})
+	if !ok || len(rows) == 0 {
+		t.Fatalf("expected non-empty usage list, got %T", payload.Data)
+	}
+
+	first, ok := rows[0].(map[string]interface{})
+	if !ok {
+		t.Fatalf("expected row map, got %T", rows[0])
+	}
+
+	if int64(first["shareId"].(float64)) != 42 {
+		t.Fatalf("expected stale shareId=42 on sync failure, got %v", first["shareId"])
+	}
+	if int64(first["currentFlow"].(float64)) != 999999 {
+		t.Fatalf("expected stale currentFlow=999999 on sync failure, got %v", first["currentFlow"])
+	}
+
+	syncErr, _ := first["syncError"].(string)
+	if syncErr == "" {
+		t.Fatalf("expected non-empty syncError field on unreachable provider")
+	}
+}
+
+func TestFederationShareResetFlow(t *testing.T) {
+	r, err := repo.Open(filepath.Join(t.TempDir(), "panel.db"))
+	if err != nil {
+		t.Fatalf("open sqlite: %v", err)
+	}
+	t.Cleanup(func() { _ = r.Close() })
+
+	h := New(r, "test-jwt-secret")
+	now := time.Now().UnixMilli()
+	if err := r.CreatePeerShare(&repo.PeerShare{
 		Name:           "reset-flow-share",
 		NodeID:         11,
 		Token:          "reset-flow-token",
@@ -260,7 +379,7 @@ func TestFederationShareResetFlow(t *testing.T) {
 	}); err != nil {
 		t.Fatalf("create peer share: %v", err)
 	}
-	share, err := repo.GetPeerShareByToken("reset-flow-token")
+	share, err := r.GetPeerShareByToken("reset-flow-token")
 	if err != nil || share == nil {
 		t.Fatalf("load peer share: %v", err)
 	}
@@ -286,7 +405,7 @@ func TestFederationShareResetFlow(t *testing.T) {
 		t.Fatalf("expected response code 0, got %d (%s)", payload.Code, payload.Msg)
 	}
 
-	updated, err := repo.GetPeerShare(share.ID)
+	updated, err := r.GetPeerShare(share.ID)
 	if err != nil || updated == nil {
 		t.Fatalf("reload peer share: %v", err)
 	}
@@ -296,47 +415,41 @@ func TestFederationShareResetFlow(t *testing.T) {
 }
 
 func TestFederationRemoteUsageList(t *testing.T) {
-	repo, err := sqlite.Open(filepath.Join(t.TempDir(), "panel.db"))
+	r, err := repo.Open(filepath.Join(t.TempDir(), "panel.db"))
 	if err != nil {
 		t.Fatalf("open sqlite: %v", err)
 	}
-	t.Cleanup(func() { _ = repo.Close() })
+	t.Cleanup(func() { _ = r.Close() })
 
-	h := New(repo, "test-jwt-secret")
+	h := New(r, "test-jwt-secret")
 	now := time.Now().UnixMilli()
 
-	resNode, 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, is_remote, remote_url, remote_token, remote_config)
 		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-	`, "remote-consumer-node", "remote-consumer-secret", "10.30.40.50", "10.30.40.50", "", "31000-31010", "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", 0, 1, "http://peer.example", "peer-token", `{"shareId":88,"maxBandwidth":2147483648,"currentFlow":1073741824,"portRangeStart":31000,"portRangeEnd":31010}`)
-	if err != nil {
+	`, "remote-consumer-node", "remote-consumer-secret", "10.30.40.50", "10.30.40.50", "", "31000-31010", "", "v1", 1, 1, 1, now, now, 1, "[::]", "[::]", 0, 1, "http://peer.example", "peer-token", `{"shareId":88,"maxBandwidth":2147483648,"currentFlow":1073741824,"portRangeStart":31000,"portRangeEnd":31010}`).Error; err != nil {
 		t.Fatalf("insert remote node: %v", err)
 	}
-	nodeID, err := resNode.LastInsertId()
-	if err != nil {
-		t.Fatalf("remote node id: %v", err)
-	}
+	nodeID := mustLastInsertID(t, r, "remote-consumer-node")
 
-	resTunnelA, err := repo.DB().Exec(`INSERT INTO tunnel(name, type, protocol, flow, created_time, updated_time, status, in_ip, inx) VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?)`, "consumer-tunnel-a", 2, "tls", 1, now, now, 1, "", 0)
-	if err != nil {
+	if err := r.DB().Exec(`INSERT INTO tunnel(name, type, protocol, flow, created_time, updated_time, status, in_ip, inx) VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?)`, "consumer-tunnel-a", 2, "tls", 1, now, now, 1, "", 0).Error; err != nil {
 		t.Fatalf("insert tunnel a: %v", err)
 	}
-	tunnelAID, _ := resTunnelA.LastInsertId()
+	tunnelAID := mustLastInsertID(t, r, "consumer-tunnel-a")
 
-	resTunnelB, err := repo.DB().Exec(`INSERT INTO tunnel(name, type, protocol, flow, created_time, updated_time, status, in_ip, inx) VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?)`, "consumer-tunnel-b", 2, "tls", 1, now, now, 1, "", 0)
-	if err != nil {
+	if err := r.DB().Exec(`INSERT INTO tunnel(name, type, protocol, flow, created_time, updated_time, status, in_ip, inx) VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?)`, "consumer-tunnel-b", 2, "tls", 1, now, now, 1, "", 0).Error; err != nil {
 		t.Fatalf("insert tunnel b: %v", err)
 	}
-	tunnelBID, _ := resTunnelB.LastInsertId()
+	tunnelBID := mustLastInsertID(t, r, "consumer-tunnel-b")
 
-	if _, err := repo.DB().Exec(`
+	if err := r.DB().Exec(`
 		INSERT INTO federation_tunnel_binding(tunnel_id, node_id, chain_type, hop_inx, remote_url, resource_key, remote_binding_id, allocated_port, status, created_time, updated_time)
 		VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?),
 		      (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
 	`,
 		tunnelAID, nodeID, 2, 1, "http://peer.example", "rk-a", "rb-a", 31001, 1, now, now,
 		tunnelBID, nodeID, 3, 0, "http://peer.example", "rk-b", "rb-b", 31002, 1, now, now,
-	); err != nil {
+	).Error; err != nil {
 		t.Fatalf("insert federation bindings: %v", err)
 	}
 
@@ -390,13 +503,13 @@ func TestFederationRemoteUsageList(t *testing.T) {
 }
 
 func TestAuthPeerAllowedIPs(t *testing.T) {
-	repo, err := sqlite.Open(filepath.Join(t.TempDir(), "panel.db"))
+	r, err := repo.Open(filepath.Join(t.TempDir(), "panel.db"))
 	if err != nil {
 		t.Fatalf("open sqlite: %v", err)
 	}
-	t.Cleanup(func() { _ = repo.Close() })
+	t.Cleanup(func() { _ = r.Close() })
 
-	h := New(repo, "test-jwt-secret")
+	h := New(r, "test-jwt-secret")
 	now := time.Now().UnixMilli()
 
 	tests := []struct {
@@ -425,6 +538,13 @@ func TestAuthPeerAllowedIPs(t *testing.T) {
 			xff:         "198.51.100.20, 172.20.0.3",
 			wantAllowed: true,
 		},
+		{
+			name:        "ipv4-mapped proxy xff allowed",
+			allowedIPs:  "198.51.100.20",
+			remoteAddr:  "[::ffff:172.20.0.3]:34567",
+			xff:         "198.51.100.20, 172.20.0.3",
+			wantAllowed: true,
+		},
 		{
 			name:        "non whitelisted ip denied",
 			allowedIPs:  "203.0.113.10",
@@ -436,7 +556,7 @@ func TestAuthPeerAllowedIPs(t *testing.T) {
 	for idx, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			token := fmt.Sprintf("share-token-%d", idx)
-			if err := repo.CreatePeerShare(&sqlite.PeerShare{
+			if err := r.CreatePeerShare(&repo.PeerShare{
 				Name:           "share-" + tt.name,
 				NodeID:         1,
 				Token:          token,

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

@@ -1,7 +1,6 @@
 package handler
 
 import (
-	"database/sql"
 	"encoding/json"
 	"strconv"
 	"strings"
@@ -207,22 +206,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) {
@@ -245,60 +240,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) == "" {
@@ -383,15 +338,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 {
@@ -402,8 +355,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

@@ -5,18 +5,18 @@ import (
 	"testing"
 	"time"
 
-	"go-backend/internal/store/sqlite"
+	"go-backend/internal/store/repo"
 )
 
 func TestProcessFlowItemTracksPeerShareFlowAndEnforcesLimit(t *testing.T) {
-	repo, err := sqlite.Open(filepath.Join(t.TempDir(), "panel.db"))
+	r, err := repo.Open(filepath.Join(t.TempDir(), "panel.db"))
 	if err != nil {
 		t.Fatalf("open repo: %v", err)
 	}
-	defer repo.Close()
+	defer r.Close()
 
 	now := time.Now().UnixMilli()
-	if err := repo.CreatePeerShare(&sqlite.PeerShare{
+	if err := r.CreatePeerShare(&repo.PeerShare{
 		Name:           "flow-share",
 		NodeID:         1,
 		Token:          "flow-share-token",
@@ -30,22 +30,22 @@ func TestProcessFlowItemTracksPeerShareFlowAndEnforcesLimit(t *testing.T) {
 	}); err != nil {
 		t.Fatalf("create peer share: %v", err)
 	}
-	share, err := repo.GetPeerShareByToken("flow-share-token")
+	share, err := r.GetPeerShareByToken("flow-share-token")
 	if err != nil || share == nil {
 		t.Fatalf("load peer share: %v", err)
 	}
 
-	if _, err := repo.DB().Exec(`
+	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); err != nil {
+	`, 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: repo}
+	h := &Handler{repo: r}
 	h.processFlowItem(flowItem{N: "fed_svc_17", U: 1200, D: 900})
 
-	updatedShare, err := repo.GetPeerShare(share.ID)
+	updatedShare, err := r.GetPeerShare(share.ID)
 	if err != nil || updatedShare == nil {
 		t.Fatalf("reload share: %v", err)
 	}
@@ -53,7 +53,7 @@ func TestProcessFlowItemTracksPeerShareFlowAndEnforcesLimit(t *testing.T) {
 		t.Fatalf("expected current_flow=3100, got %d", updatedShare.CurrentFlow)
 	}
 
-	runtime, err := repo.GetPeerShareRuntimeByID(17)
+	runtime, err := r.GetPeerShareRuntimeByID(17)
 	if err != nil || runtime == nil {
 		t.Fatalf("reload runtime: %v", err)
 	}

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

@@ -18,12 +18,12 @@ 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
 
@@ -69,7 +69,7 @@ type flowItem struct {
 	D int64  `json:"d"`
 }
 
-func New(repo *sqlite.Repository, jwtSecret string) *Handler {
+func New(repo *repo.Repository, jwtSecret string) *Handler {
 	return &Handler{
 		repo:          repo,
 		jwtSecret:     jwtSecret,
@@ -93,6 +93,12 @@ func (h *Handler) Register(mux *http.ServeMux) {
 	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)
@@ -105,6 +111,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)
@@ -155,6 +165,7 @@ func (h *Handler) Register(mux *http.ServeMux) {
 	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)
@@ -164,7 +175,10 @@ func (h *Handler) Register(mux *http.ServeMux) {
 	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)
@@ -301,11 +315,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))
 }
 
@@ -320,6 +358,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))
 }
 
@@ -385,7 +426,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
 	}
@@ -428,27 +469,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)
@@ -1108,3 +1143,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,68 +52,57 @@ 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 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 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)
 	}
 
 	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)
 	}

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

@@ -0,0 +1,291 @@
+package handler
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"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
+)
+
+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"`
+	}
+	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
+	}
+
+	version := strings.TrimSpace(req.Version)
+	if version == "" {
+		var err error
+		version, err = resolveLatestRelease()
+		if err != nil {
+			response.WriteJSON(w, response.Err(-2, fmt.Sprintf("获取最新版本失败: %v", 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
+	}
+
+	response.WriteJSON(w, response.OK(map[string]interface{}{
+		"version": version,
+		"message": result.Message,
+	}))
+}
+
+func resolveLatestRelease() (string, error) {
+	client := &http.Client{
+		CheckRedirect: func(req *http.Request, via []*http.Request) error {
+			return http.ErrUseLastResponse
+		},
+		Timeout: 10 * time.Second,
+	}
+
+	resp, err := client.Get(githubProxy + "/" + githubHTMLBase + "/" + githubRepo + "/releases/latest")
+	if err != nil {
+		return "", fmt.Errorf("请求GitHub失败: %v", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusFound && resp.StatusCode != http.StatusMovedPermanently {
+		return resolveLatestReleaseAPI()
+	}
+
+	location := resp.Header.Get("Location")
+	if location == "" {
+		return resolveLatestReleaseAPI()
+	}
+
+	parts := strings.Split(location, "/")
+	tag := parts[len(parts)-1]
+	if tag == "" || tag == "latest" {
+		return resolveLatestReleaseAPI()
+	}
+
+	return tag, nil
+}
+
+func resolveLatestReleaseAPI() (string, error) {
+	client := &http.Client{Timeout: 10 * time.Second}
+	resp, err := client.Get(githubAPIBase + "/repos/" + githubRepo + "/releases/latest")
+	if err != nil {
+		return "", fmt.Errorf("请求GitHub API失败: %v", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		body, _ := io.ReadAll(io.LimitReader(resp.Body, 512))
+		return "", fmt.Errorf("GitHub API返回 %d: %s", resp.StatusCode, string(body))
+	}
+
+	var release struct {
+		TagName string `json:"tag_name"`
+	}
+	if err := json.NewDecoder(resp.Body).Decode(&release); err != nil {
+		return "", fmt.Errorf("解析GitHub API响应失败: %v", err)
+	}
+	if strings.TrimSpace(release.TagName) == "" {
+		return "", fmt.Errorf("无法从GitHub获取最新版本号")
+	}
+
+	return release.TagName, nil
+}
+
+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"`
+	}
+	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
+	}
+
+	version := strings.TrimSpace(req.Version)
+	if version == "" {
+		var err error
+		version, err = resolveLatestRelease()
+		if err != nil {
+			response.WriteJSON(w, response.Err(-2, fmt.Sprintf("获取最新版本失败: %v", 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
+			}
+			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
+	}
+
+	client := &http.Client{Timeout: 15 * time.Second}
+	resp, err := client.Get(githubAPIBase + "/repos/" + githubRepo + "/releases?per_page=20")
+	if err != nil {
+		response.WriteJSON(w, response.Err(-2, fmt.Sprintf("获取版本列表失败: %v", err)))
+		return
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		body, _ := io.ReadAll(io.LimitReader(resp.Body, 512))
+		response.WriteJSON(w, response.Err(-2, fmt.Sprintf("获取版本列表失败: GitHub API返回 %d: %s", resp.StatusCode, string(body))))
+		return
+	}
+
+	var releases []struct {
+		TagName     string `json:"tag_name"`
+		Name        string `json:"name"`
+		PublishedAt string `json:"published_at"`
+		Prerelease  bool   `json:"prerelease"`
+		Draft       bool   `json:"draft"`
+	}
+	if err := json.NewDecoder(resp.Body).Decode(&releases); err != nil {
+		response.WriteJSON(w, response.Err(-2, fmt.Sprintf("解析版本列表失败: %v", err)))
+		return
+	}
+
+	type releaseItem struct {
+		Version     string `json:"version"`
+		Name        string `json:"name"`
+		PublishedAt string `json:"publishedAt"`
+		Prerelease  bool   `json:"prerelease"`
+	}
+
+	items := make([]releaseItem, 0, len(releases))
+	for _, r := range releases {
+		if r.Draft {
+			continue
+		}
+		items = append(items, releaseItem{
+			Version:     r.TagName,
+			Name:        r.Name,
+			PublishedAt: r.PublishedAt,
+			Prerelease:  r.Prerelease,
+		})
+	}
+
+	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,
+	}))
+}

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

@@ -93,6 +93,8 @@ func shouldSkip(path string) bool {
 		return true
 	case path == "/api/v1/federation/runtime/diagnose":
 		return true
+	case path == "/api/v1/federation/runtime/command":
+		return true
 	default:
 		return false
 	}
@@ -115,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
@@ -127,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,308 @@
+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) 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,269 @@
+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
+}
+
+// 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
+}
+
+// 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,69 @@
+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
+}
+
+// ListGroupPermissionPairsByTunnelGroup returns [userGroupID, tunnelGroupID] pairs
+// for all group permissions associated with a tunnel group.
+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,245 +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,
-  is_remote INTEGER DEFAULT 0,
-  remote_url TEXT,
-  remote_token TEXT,
-  remote_config TEXT
-);
-
-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
-);
-
-CREATE TABLE IF NOT EXISTS peer_share (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    name TEXT NOT NULL,
-    node_id INTEGER NOT NULL,
-    token TEXT NOT NULL UNIQUE,
-    max_bandwidth INTEGER DEFAULT 0,
-    expiry_time INTEGER DEFAULT 0,
-    port_range_start INTEGER DEFAULT 0,
-    port_range_end INTEGER DEFAULT 0,
-    current_flow INTEGER DEFAULT 0,
-    is_active INTEGER DEFAULT 1,
-    created_time INTEGER NOT NULL,
-    updated_time INTEGER NOT NULL,
-    allowed_domains TEXT DEFAULT '',
-    allowed_ips TEXT DEFAULT ''
-);
-
-CREATE TABLE IF NOT EXISTS peer_share_runtime (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    share_id INTEGER NOT NULL,
-    node_id INTEGER NOT NULL,
-    reservation_id TEXT NOT NULL UNIQUE,
-    resource_key TEXT NOT NULL UNIQUE,
-    binding_id TEXT NOT NULL DEFAULT '',
-    role TEXT NOT NULL DEFAULT '',
-    chain_name TEXT NOT NULL DEFAULT '',
-    service_name TEXT NOT NULL DEFAULT '',
-    protocol TEXT NOT NULL DEFAULT 'tls',
-    strategy TEXT NOT NULL DEFAULT 'round',
-    port INTEGER NOT NULL DEFAULT 0,
-    target TEXT NOT NULL DEFAULT '',
-    applied INTEGER NOT NULL DEFAULT 0,
-    status INTEGER NOT NULL DEFAULT 1,
-    created_time INTEGER NOT NULL,
-    updated_time INTEGER NOT NULL
-);
-
-CREATE INDEX IF NOT EXISTS idx_peer_share_runtime_share_node_status ON peer_share_runtime(share_id, node_id, status);
-CREATE INDEX IF NOT EXISTS idx_peer_share_runtime_binding_id ON peer_share_runtime(binding_id);
-
-CREATE TABLE IF NOT EXISTS federation_tunnel_binding (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    tunnel_id INTEGER NOT NULL,
-    node_id INTEGER NOT NULL,
-    chain_type INTEGER NOT NULL,
-    hop_inx INTEGER NOT NULL DEFAULT 0,
-    remote_url TEXT NOT NULL,
-    resource_key TEXT NOT NULL UNIQUE,
-    remote_binding_id TEXT NOT NULL,
-    allocated_port INTEGER NOT NULL,
-    status INTEGER NOT NULL DEFAULT 1,
-    created_time INTEGER NOT NULL,
-    updated_time INTEGER NOT NULL
-);
-
-CREATE UNIQUE INDEX IF NOT EXISTS idx_federation_tunnel_binding_unique ON federation_tunnel_binding(tunnel_id, node_id, chain_type, hop_inx);
-CREATE INDEX IF NOT EXISTS idx_federation_tunnel_binding_tunnel ON federation_tunnel_binding(tunnel_id, status);

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,7 +68,7 @@ type CommandResult struct {
 }
 
 type Server struct {
-	repo      *sqlite.Repository
+	repo      *repo.Repository
 	jwtSecret string
 	upgrader  websocket.Upgrader
 
@@ -73,7 +79,7 @@ type Server struct {
 	pending map[string]pendingRequest
 }
 
-func NewServer(repo *sqlite.Repository, jwtSecret string) *Server {
+func NewServer(repo *repo.Repository, jwtSecret string) *Server {
 	return &Server{
 		repo:      repo,
 		jwtSecret: jwtSecret,
@@ -120,12 +126,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 +158,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)
@@ -165,6 +184,7 @@ func (s *Server) handleNode(w http.ResponseWriter, r *http.Request, nodeID int64
 	s.broadcastStatus(nodeID, 1)
 
 	defer func() {
+		close(done)
 		needOfflineBroadcast := false
 		s.mu.Lock()
 		current, ok := s.nodes[nodeID]
@@ -190,7 +210,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 +292,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 +415,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 +431,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 +466,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

@@ -16,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 {
@@ -208,7 +195,7 @@ func TestDiagnosisChainCoverageContracts(t *testing.T) {
 
 func TestDiagnosisUsesFederationRuntimeForRemoteNodes(t *testing.T) {
 	secret := "contract-jwt-secret"
-	router, repo := setupDiagnosisContractRouter(t, secret)
+	router, r := setupDiagnosisContractRouter(t, secret)
 	now := time.Now().UnixMilli()
 
 	remoteToken := "remote-diagnose-token"
@@ -256,67 +243,53 @@ func TestDiagnosisUsesFederationRuntimeForRemoteNodes(t *testing.T) {
 	defer remoteServer.Close()
 
 	insertLocalNode := 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 local node %s: %v", name, err)
 		}
-		id, err := res.LastInsertId()
-		if err != nil {
-			t.Fatalf("get local node id %s: %v", name, err)
-		}
-		return id
+		return mustLastInsertID(t, r, name)
 	}
 
 	insertRemoteNode := 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, 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}`)
-		if err != nil {
+		`, 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)
 		}
-		id, err := res.LastInsertId()
-		if err != nil {
-			t.Fatalf("get remote node id %s: %v", name, err)
-		}
-		return id
+		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")
 
-	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-remote-tunnel", 1.0, 2, "tls", 99999, now, now, 1, nil, 0)
-	if err != nil {
+	`, "diagnose-remote-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-remote-tunnel")
 
-	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, remoteChainNodeID); err != nil {
+	`, tunnelID, remoteChainNodeID).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)
 	}
 
@@ -409,17 +382,17 @@ func valueAsBool(v interface{}) bool {
 	}
 }
 
-func setupDiagnosisContractRouter(t *testing.T, jwtSecret string) (http.Handler, *sqlite.Repository) {
+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

@@ -17,7 +17,7 @@ import (
 	"go-backend/internal/auth"
 	"go-backend/internal/http/response"
 	"go-backend/internal/security"
-	"go-backend/internal/store/sqlite"
+	"go-backend/internal/store/repo"
 )
 
 func TestFederationDualPanelMiddleExitAutoPortContract(t *testing.T) {
@@ -39,7 +39,7 @@ func TestFederationDualPanelMiddleExitAutoPortContract(t *testing.T) {
 	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, &sqlite.PeerShare{
+	entryShareID := insertPeerShare(t, providerRepo, &repo.PeerShare{
 		Name:           "entry-share",
 		NodeID:         providerEntryNodeID,
 		Token:          "share-entry-token",
@@ -49,7 +49,7 @@ func TestFederationDualPanelMiddleExitAutoPortContract(t *testing.T) {
 		CreatedTime:    now,
 		UpdatedTime:    now,
 	})
-	middleShareID := insertPeerShare(t, providerRepo, &sqlite.PeerShare{
+	middleShareID := insertPeerShare(t, providerRepo, &repo.PeerShare{
 		Name:           "middle-share",
 		NodeID:         providerMiddleNodeID,
 		Token:          "share-middle-token",
@@ -59,7 +59,7 @@ func TestFederationDualPanelMiddleExitAutoPortContract(t *testing.T) {
 		CreatedTime:    now,
 		UpdatedTime:    now,
 	})
-	exitShareID := insertPeerShare(t, providerRepo, &sqlite.PeerShare{
+	exitShareID := insertPeerShare(t, providerRepo, &repo.PeerShare{
 		Name:           "exit-share",
 		NodeID:         providerExitNodeID,
 		Token:          "share-exit-token",
@@ -78,6 +78,8 @@ func TestFederationDualPanelMiddleExitAutoPortContract(t *testing.T) {
 	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")
@@ -110,10 +112,7 @@ func TestFederationDualPanelMiddleExitAutoPortContract(t *testing.T) {
 		consumerRouter.ServeHTTP(res, req)
 		assertCode(t, res, 0)
 
-		var tunnelID int64
-		if err := consumerRepo.DB().QueryRow(`SELECT id FROM tunnel WHERE name = ? ORDER BY id DESC LIMIT 1`, name).Scan(&tunnelID); err != nil {
-			t.Fatalf("query tunnel id (%s): %v", name, err)
-		}
+		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)
 		}
@@ -148,6 +147,23 @@ func TestFederationDualPanelMiddleExitAutoPortContract(t *testing.T) {
 	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 = ?`, entryShareID, 0)
@@ -172,7 +188,7 @@ func TestFederationDualPanelRemoteDiagnosisContract(t *testing.T) {
 	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, &sqlite.PeerShare{
+	entryShareID := insertPeerShare(t, providerRepo, &repo.PeerShare{
 		Name:           "entry-share-dx",
 		NodeID:         providerEntryNodeID,
 		Token:          "share-entry-dx-token",
@@ -182,7 +198,7 @@ func TestFederationDualPanelRemoteDiagnosisContract(t *testing.T) {
 		CreatedTime:    now,
 		UpdatedTime:    now,
 	})
-	middleShareID := insertPeerShare(t, providerRepo, &sqlite.PeerShare{
+	middleShareID := insertPeerShare(t, providerRepo, &repo.PeerShare{
 		Name:           "middle-share-dx",
 		NodeID:         providerMiddleNodeID,
 		Token:          "share-middle-dx-token",
@@ -192,7 +208,7 @@ func TestFederationDualPanelRemoteDiagnosisContract(t *testing.T) {
 		CreatedTime:    now,
 		UpdatedTime:    now,
 	})
-	exitShareID := insertPeerShare(t, providerRepo, &sqlite.PeerShare{
+	exitShareID := insertPeerShare(t, providerRepo, &repo.PeerShare{
 		Name:           "exit-share-dx",
 		NodeID:         providerExitNodeID,
 		Token:          "share-exit-dx-token",
@@ -242,10 +258,7 @@ func TestFederationDualPanelRemoteDiagnosisContract(t *testing.T) {
 	consumerRouter.ServeHTTP(createRes, createReq)
 	assertCode(t, createRes, 0)
 
-	var tunnelID int64
-	if err := consumerRepo.DB().QueryRow(`SELECT id FROM tunnel WHERE name = ? ORDER BY id DESC LIMIT 1`, "dual-panel-diagnose-remote").Scan(&tunnelID); err != nil {
-		t.Fatalf("query tunnel id: %v", err)
-	}
+	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")
 	}
@@ -297,32 +310,154 @@ func TestFederationDualPanelRemoteDiagnosisContract(t *testing.T) {
 	}
 }
 
-func insertContractNode(t *testing.T, repo *sqlite.Repository, name, ip, portRange, secret string, status int) int64 {
-	t.Helper()
+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()
-	res, 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, secret, ip, ip, "", portRange, "", "v1", 1, 1, 1, now, now, status, "[::]", "[::]", 0)
-	if err != nil {
-		t.Fatalf("insert node %s: %v", name, err)
+	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
 	}
-	id, err := res.LastInsertId()
-	if err != nil {
-		t.Fatalf("node id %s: %v", name, err)
+
+	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
+		}
 	}
-	return id
+	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 insertPeerShare(t *testing.T, repo *sqlite.Repository, share *sqlite.PeerShare) int64 {
+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 := repo.CreatePeerShare(share); err != nil {
+	if err := r.CreatePeerShare(share); err != nil {
 		t.Fatalf("create peer share %s: %v", share.Name, err)
 	}
-	saved, err := repo.GetPeerShareByToken(share.Token)
+	saved, err := r.GetPeerShareByToken(share.Token)
 	if err != nil {
 		t.Fatalf("query peer share %s: %v", share.Name, err)
 	}
@@ -349,47 +484,36 @@ func importRemoteNodeForContract(t *testing.T, router http.Handler, adminToken,
 	assertCode(t, res, 0)
 }
 
-func queryRemoteNodeIDByToken(t *testing.T, repo *sqlite.Repository, token string) int64 {
+func queryRemoteNodeIDByToken(t *testing.T, r *repo.Repository, token string) int64 {
 	t.Helper()
-	var id int64
-	if err := repo.DB().QueryRow(`SELECT id FROM node WHERE is_remote = 1 AND remote_token = ? ORDER BY id DESC LIMIT 1`, token).Scan(&id); err != nil {
-		t.Fatalf("query remote node by token %s: %v", token, err)
-	}
+	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, repo *sqlite.Repository, tunnelID int64, chainType int, nodeID int64, minPort int, maxPort int) {
+func assertTunnelPortInRange(t *testing.T, r *repo.Repository, tunnelID int64, chainType int, nodeID int64, minPort int, maxPort int) {
 	t.Helper()
-	var port int
-	err := repo.DB().QueryRow(`
-		SELECT port
-		FROM chain_tunnel
-		WHERE tunnel_id = ? AND chain_type = ? AND node_id = ?
-		LIMIT 1
-	`, tunnelID, chainType, nodeID).Scan(&port)
-	if err != nil {
-		t.Fatalf("query tunnel=%d chainType=%d node=%d port: %v", tunnelID, chainType, nodeID, err)
-	}
+	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, repo *sqlite.Repository, query string, arg interface{}, expected int) {
+func assertCount(t *testing.T, r *repo.Repository, query string, arg interface{}, expected int) {
 	t.Helper()
-	var got int
-	if err := repo.DB().QueryRow(query, arg).Scan(&got); err != nil {
-		t.Fatalf("count query failed: %v", err)
-	}
+	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 {
@@ -449,6 +573,9 @@ func startMockNodeSession(t *testing.T, baseURL string, nodeSecret string) func(
 			if strings.TrimSpace(cmd.RequestID) == "" {
 				continue
 			}
+			if onCommand != nil {
+				onCommand(strings.TrimSpace(cmd.Type))
+			}
 
 			respType := fmt.Sprintf("%sResponse", cmd.Type)
 			respPayload := map[string]interface{}{
@@ -473,9 +600,27 @@ func startMockNodeSession(t *testing.T, baseURL string, nodeSecret string) func(
 		}
 	}()
 
+	var stopOnce sync.Once
 	return func() {
-		_ = conn.Close()
-		wg.Wait()
+		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)
 	}
 }
 
@@ -514,3 +659,112 @@ func valueAsBool(v interface{}) bool {
 		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/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

@@ -17,21 +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"
 
-	_ "modernc.org/sqlite"
+	"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)
 	}
 
@@ -83,7 +82,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)
@@ -91,17 +90,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)
 	}
 
@@ -202,19 +197,383 @@ 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) {
@@ -275,15 +634,15 @@ func TestOpenMigratesLegacyNodeDualStackColumns(t *testing.T) {
 		t.Fatalf("seed legacy node row: %v", err)
 	}
 
-	repo, err := sqlite.Open(dbPath)
+	r, err := repo.Open(dbPath)
 	if err != nil {
 		t.Fatalf("open migrated sqlite: %v", err)
 	}
 	t.Cleanup(func() {
-		_ = repo.Close()
+		_ = r.Close()
 	})
 
-	nodes, err := repo.ListNodes()
+	nodes, err := r.ListNodes()
 	if err != nil {
 		t.Fatalf("list nodes after migration: %v", err)
 	}
@@ -291,7 +650,7 @@ func TestOpenMigratesLegacyNodeDualStackColumns(t *testing.T) {
 		t.Fatalf("expected 1 node after migration, got %d", len(nodes))
 	}
 
-	columns := readTableColumns(t, repo.DB(), "node")
+	columns := readTableColumns(t, r.DB(), "node")
 
 	for _, required := range []string{"server_ip_v4", "server_ip_v6", "inx"} {
 		if !columns[required] {
@@ -299,34 +658,28 @@ func TestOpenMigratesLegacyNodeDualStackColumns(t *testing.T) {
 		}
 	}
 
-	tunnelColumns := readTableColumns(t, repo.DB(), "tunnel")
+	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 *sql.DB, table string) map[string]bool {
+func readTableColumns(t *testing.T, db *gorm.DB, table string) map[string]bool {
 	t.Helper()
 
-	rows, err := db.Query("PRAGMA table_info(" + table + ")")
+	columnTypes, err := db.Migrator().ColumnTypes(table)
 	if err != nil {
 		t.Fatalf("inspect %s columns: %v", table, err)
 	}
-	defer rows.Close()
 
 	columns := map[string]bool{}
-	for rows.Next() {
-		var cid, notNull, pk int
-		var name, typ string
-		var defaultValue sql.NullString
-		if err := rows.Scan(&cid, &name, &typ, &notNull, &defaultValue, &pk); err != nil {
-			t.Fatalf("scan %s pragma row: %v", table, err)
+	for _, col := range columnTypes {
+		name := strings.TrimSpace(col.Name())
+		if name == "" {
+			continue
 		}
 		columns[name] = true
 	}
-	if err := rows.Err(); err != nil {
-		t.Fatalf("iterate %s pragma rows: %v", table, err)
-	}
 
 	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/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/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/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"
@@ -881,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://gcode.hostcentral.cc/${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

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://gcode.hostcentral.cc/${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

vite-frontend/AGENTS.md

@@ -1,10 +1,10 @@
 # VITE FRONTEND KNOWLEDGE BASE
 
-**Generated:** Mon Feb 02 2026
+**Generated:** Sun Feb 15 2026
 
 ## OVERVIEW
-Web management console for FLVX (formerly Flux Panel).
-**Stack:** React 18, Vite 5, TypeScript, TailwindCSS 4, HeroUI.
+Web management console for FLVX.
+**Stack:** React 18, Vite 5 (rolldown-vite), TypeScript, TailwindCSS 4, HeroUI.
 
 ## STRUCTURE
 ```
@@ -37,9 +37,19 @@ vite-frontend/
 
 ## CONVENTIONS
 - **Auth**: JWT stored as `localStorage.token`. Sent in `Authorization` header (no "Bearer" prefix).
-- **API**: Default base URL is `/api/v1/`.
+- **API**: Default base URL is `/api/v1/`. Responses follow `{code, msg, data, ts}` structure.
 - **WebView**: In WebView mode, base URL is derived from selected panel address. If unset, API returns `code: -1`.
 - **Routing**: URL query param `h5=true` forces mobile layout.
+- **Build**: `minify: false`, `treeshake: false` - unoptimized production bundles for debugging.
+- **ESLint**: `react-hooks/exhaustive-deps` disabled, unused vars starting with `_` ignored.
+- **Large Pages**: `forward.tsx` (3263 LOC), `tunnel.tsx` (2552 LOC), `node.tsx` (2194 LOC).
+
+## ANTI-PATTERNS
+- **DO NOT ADD** tests - no test infrastructure (Vitest/Jest not configured).
+
+## NOTES
+- Uses `rolldown-vite` (experimental Rust bundler) instead of standard Vite.
+- ESLint Flat Config format with custom import ordering rules.
 
 ## COMMANDS
 ```bash

vite-frontend/nginx.conf

@@ -87,6 +87,8 @@ http {
             proxy_http_version 1.1;
             proxy_set_header Upgrade $http_upgrade;
             proxy_set_header Connection "upgrade";
+            proxy_read_timeout 3600s;
+            proxy_send_timeout 3600s;
             
             proxy_set_header Host $host;
             proxy_set_header X-Real-IP $remote_addr;
@@ -94,4 +96,4 @@ http {
             proxy_set_header X-Forwarded-Proto $scheme;
         }
     }
-} 
+} 

vite-frontend/package.json

@@ -40,7 +40,7 @@
     "@heroui/system": "2.4.19",
     "@heroui/table": "^2.2.24",
     "@heroui/tabs": "^2.2.27",
-    "@heroui/theme": "2.4.19",
+    "@heroui/theme": "2.4.24",
     "@heroui/use-theme": "2.1.10",
     "@marsidev/react-turnstile": "^1.1.0",
     "@nextui-org/system": "^2.4.6",

vite-frontend/src/api/index.ts

@@ -1,3 +1,5 @@
+import axios from "axios";
+
 import Network from "./network";
 
 // 登陆相关接口
@@ -41,6 +43,22 @@ export const checkNodeStatus = (nodeId?: number) => {
   return Network.post("/node/check-status", params);
 };
 
+export const upgradeNode = (id: number, version?: string) =>
+  Network.post(
+    "/node/upgrade",
+    { id, version: version || "" },
+    { timeout: 5 * 60 * 1000 },
+  );
+export const batchUpgradeNodes = (ids: number[], version?: string) =>
+  Network.post(
+    "/node/batch-upgrade",
+    { ids, version: version || "" },
+    { timeout: 15 * 60 * 1000 },
+  );
+export const getNodeReleases = () => Network.post("/node/releases");
+export const rollbackNode = (id: number) =>
+  Network.post("/node/rollback", { id });
+
 // 隧道CRUD操作 - 全部使用POST请求
 export const createTunnel = (data: any) => Network.post("/tunnel/create", data);
 export const getTunnelList = () => Network.post("/tunnel/list");
@@ -122,6 +140,10 @@ export const updateConfigs = (configMap: Record<string, string>) =>
 export const updateConfig = (name: string, value: string) =>
   Network.post("/config/update-single", { name, value });
 
+export const exportBackupData = () => Network.post("/backup/export");
+export const importBackupData = (data: any) => Network.post("/backup/import", data);
+export const restoreBackupData = (data: any) => Network.post("/backup/restore", data);
+
 // 验证码相关接口
 export const checkCaptcha = () => Network.post("/captcha/check");
 export const generateCaptcha = () => Network.post(`/captcha/generate`);
@@ -200,13 +222,74 @@ export const createPeerShare = (data: {
   allowedDomains?: string;
   allowedIps?: string;
 }) => Network.post("/federation/share/create", data);
+export const updatePeerShare = (data: {
+  id: number;
+  name: string;
+  maxBandwidth: number;
+  expiryTime: number;
+  portRangeStart: number;
+  portRangeEnd: number;
+  allowedDomains: string;
+  allowedIps: string;
+}) => Network.post("/federation/share/update", data);
 export const deletePeerShare = (id: number) =>
   Network.post("/federation/share/delete", { id });
 export const resetPeerShareFlow = (id: number) =>
   Network.post("/federation/share/reset-flow", { id });
 export const getPeerRemoteUsageList = () =>
   Network.post("/federation/share/remote-usage/list");
-export const importRemoteNode = (data: {
-  remoteUrl: string;
-  token: string;
-}) => Network.post("/federation/node/import", data);
+export const importRemoteNode = (data: { remoteUrl: string; token: string }) =>
+  Network.post("/federation/node/import", data);
+
+export interface BackupTypes {
+  users?: boolean;
+  nodes?: boolean;
+  tunnels?: boolean;
+  forwards?: boolean;
+  userTunnels?: boolean;
+  speedLimits?: boolean;
+  tunnelGroups?: boolean;
+  userGroups?: boolean;
+  permissions?: boolean;
+  configs?: boolean;
+}
+
+export const exportBackup = async (types: string[] = []) => {
+  const token = window.localStorage.getItem("token");
+  const baseURL = axios.defaults.baseURL || "/api/v1/";
+
+  const response = await axios.post(
+    `${baseURL}/backup/export`,
+    { types },
+    {
+      headers: {
+        Authorization: token,
+        "Content-Type": "application/json",
+      },
+      responseType: "blob",
+    },
+  );
+
+  const url = window.URL.createObjectURL(new Blob([response.data]));
+  const link = document.createElement("a");
+
+  link.href = url;
+  const timestamp = new Date().toISOString().slice(0, 19).replace(/[:-]/g, "");
+
+  link.setAttribute("download", `backup_${timestamp}.json`);
+  document.body.appendChild(link);
+  link.click();
+  document.body.removeChild(link);
+  window.URL.revokeObjectURL(url);
+};
+
+export const importBackup = (data: { types: string[]; [key: string]: any }) =>
+  Network.post("/backup/import", data);
+
+export interface AnnouncementData {
+  content: string;
+  enabled: number;
+}
+
+export const getAnnouncement = () => Network.get<AnnouncementData>("/announcement/get");
+export const updateAnnouncement = (data: AnnouncementData) => Network.post("/announcement/update", data);

vite-frontend/src/api/network.ts

@@ -43,6 +43,10 @@ interface ApiResponse<T = any> {
   data: T;
 }
 
+interface RequestOptions {
+  timeout?: number;
+}
+
 // 处理token失效的逻辑
 function handleTokenExpired() {
   // 清除localStorage中的token
@@ -71,6 +75,7 @@ const Network = {
   get: function <T = any>(
     path: string = "",
     data: any = {},
+    options: RequestOptions = {},
   ): Promise<ApiResponse<T>> {
     return new Promise(function (resolve) {
       // 如果baseURL是默认值且是WebView环境，说明没有设置面板地址
@@ -83,7 +88,7 @@ const Network = {
       axios
         .get(path, {
           params: data,
-          timeout: 30000,
+          timeout: options.timeout ?? 30000,
           headers: {
             Authorization: window.localStorage.getItem("token"),
           },
@@ -117,6 +122,7 @@ const Network = {
   post: function <T = any>(
     path: string = "",
     data: any = {},
+    options: RequestOptions = {},
   ): Promise<ApiResponse<T>> {
     return new Promise(function (resolve) {
       // 如果baseURL是默认值且是WebView环境，说明没有设置面板地址
@@ -128,7 +134,7 @@ const Network = {
 
       axios
         .post(path, data, {
-          timeout: 30000,
+          timeout: options.timeout ?? 30000,
           headers: {
             Authorization: window.localStorage.getItem("token"),
             "Content-Type": "application/json",

vite-frontend/src/pages/config.tsx

@@ -1,15 +1,17 @@
-import { useState, useEffect } from "react";
+import { useState, useEffect, useRef } from "react";
 import { useNavigate } from "react-router-dom";
 import { Button } from "@heroui/button";
 import { Card, CardBody, CardHeader } from "@heroui/card";
 import { Input } from "@heroui/input";
+import { Textarea } from "@heroui/input";
 import { Spinner } from "@heroui/spinner";
 import { Divider } from "@heroui/divider";
 import { Switch } from "@heroui/switch";
 import { Select, SelectItem } from "@heroui/select";
+import { Checkbox, CheckboxGroup } from "@heroui/checkbox";
 import toast from "react-hot-toast";
 
-import { updateConfigs } from "@/api";
+import { updateConfigs, exportBackup, importBackup, getAnnouncement, updateAnnouncement, type AnnouncementData } from "@/api";
 import { SettingsIcon } from "@/components/icons";
 import { isAdmin } from "@/utils/auth";
 import {
@@ -130,12 +132,26 @@ export default function ConfigPage() {
     useState<Record<string, string>>(initialConfigs);
   const [loading, setLoading] = useState(
     Object.keys(initialConfigs).length === 0,
-  ); // 如果有缓存数据，不显示loading
+  );
   const [saving, setSaving] = useState(false);
   const [hasChanges, setHasChanges] = useState(false);
   const [originalConfigs, setOriginalConfigs] =
     useState<Record<string, string>>(initialConfigs);
 
+  const [exportTypes, setExportTypes] = useState<string[]>([]);
+  const [importTypes, setImportTypes] = useState<string[]>([]);
+  const [exporting, setExporting] = useState(false);
+  const [importing, setImporting] = useState(false);
+  const [importFileName, setImportFileName] = useState("");
+  const fileInputRef = useRef<HTMLInputElement>(null);
+
+  const [announcement, setAnnouncement] = useState<AnnouncementData>({
+    content: "",
+    enabled: 0,
+  });
+  const [announcementLoading, setAnnouncementLoading] = useState(true);
+  const [announcementSaving, setAnnouncementSaving] = useState(false);
+
   // 权限检查
   useEffect(() => {
     if (!isAdmin()) {
@@ -180,21 +196,51 @@ export default function ConfigPage() {
   };
 
   useEffect(() => {
-    // 延迟加载，避免阻塞初始渲染
     const timer = setTimeout(() => {
       loadConfigs(initialConfigs);
+      loadAnnouncement();
     }, 100);
 
     return () => clearTimeout(timer);
-  }, []); // 只在组件挂载时执行一次
+  }, []);
+
+  const loadAnnouncement = async () => {
+    setAnnouncementLoading(true);
+    try {
+      const res = await getAnnouncement();
+
+      if (res.code === 0 && res.data) {
+        setAnnouncement(res.data);
+      }
+    } catch (error) {
+      console.error("Failed to load announcement:", error);
+    } finally {
+      setAnnouncementLoading(false);
+    }
+  };
+
+  const saveAnnouncement = async () => {
+    setAnnouncementSaving(true);
+    try {
+      const res = await updateAnnouncement(announcement);
+
+      if (res.code === 0) {
+        toast.success("公告保存成功");
+      } else {
+        toast.error(res.msg || "保存失败");
+      }
+    } catch {
+      toast.error("保存公告失败，请重试");
+    } finally {
+      setAnnouncementSaving(false);
+    }
+  };
 
-  // 处理配置项变更
   const handleConfigChange = (key: string, value: string) => {
     const newConfigs = { ...configs, [key]: value };
 
     setConfigs(newConfigs);
 
-    // 检查是否有变更
     const hasChangesNow =
       Object.keys(newConfigs).some(
         (k) => newConfigs[k] !== originalConfigs[k],
@@ -331,6 +377,63 @@ export default function ConfigPage() {
     }
   };
 
+  const handleExport = async () => {
+    if (exportTypes.length === 0) {
+      toast.error("请至少选择一种数据类型");
+
+      return;
+    }
+    setExporting(true);
+    try {
+      await exportBackup(exportTypes);
+      toast.success("导出成功");
+    } catch {
+      toast.error("导出失败，请重试");
+    } finally {
+      setExporting(false);
+    }
+  };
+
+  const handleFileChange = async (e: React.ChangeEvent<HTMLInputElement>) => {
+    const file = e.target.files?.[0];
+
+    if (!file) return;
+
+    if (importTypes.length === 0) {
+      toast.error("请先选择要导入的数据类型");
+
+      return;
+    }
+
+    setImportFileName(file.name);
+    setImporting(true);
+
+    try {
+      const text = await file.text();
+      const data = JSON.parse(text);
+
+      const response = await importBackup({
+        types: importTypes,
+        ...data,
+      });
+
+      if (response.code === 0) {
+        toast.success(`导入成功: ${JSON.stringify(response.data)}`);
+        setImportTypes([]);
+        setImportFileName("");
+      } else {
+        toast.error("导入失败: " + response.msg);
+      }
+    } catch {
+      toast.error("导入失败，请检查文件格式");
+    } finally {
+      setImporting(false);
+      if (fileInputRef.current) {
+        fileInputRef.current.value = "";
+      }
+    }
+  };
+
   if (loading) {
     return (
       <div className="flex items-center justify-center min-h-[400px]">
@@ -414,7 +517,6 @@ export default function ConfigPage() {
         </CardBody>
       </Card>
 
-      {/* 操作提示 */}
       {hasChanges && (
         <Card className="mt-4 bg-warning-50 dark:bg-warning-900/20 border-warning-200 dark:border-warning-800">
           <CardBody className="py-3">
@@ -427,6 +529,203 @@ export default function ConfigPage() {
           </CardBody>
         </Card>
       )}
+
+      <Card className="mt-6 shadow-md">
+        <CardHeader className="pb-4">
+          <div className="flex justify-between items-center w-full">
+            <div>
+              <h2 className="text-xl font-semibold">公告管理</h2>
+              <p className="text-sm text-gray-600 dark:text-gray-400">
+                设置首页显示的公告内容
+              </p>
+            </div>
+          </div>
+        </CardHeader>
+
+        <Divider />
+
+        <CardBody className="space-y-4 pt-6">
+          {announcementLoading ? (
+            <div className="flex justify-center py-8">
+              <Spinner size="lg" />
+            </div>
+          ) : (
+            <>
+              <div className="space-y-2">
+                <Switch
+                  isSelected={announcement.enabled === 1}
+                  onValueChange={(checked) =>
+                    setAnnouncement({ ...announcement, enabled: checked ? 1 : 0 })
+                  }
+                >
+                  <span className="text-sm text-gray-700 dark:text-gray-300">
+                    {announcement.enabled === 1 ? "已启用" : "已禁用"}
+                  </span>
+                </Switch>
+                <p className="text-xs text-gray-500 dark:text-gray-400">
+                  启用后，公告将在首页顶部显示
+                </p>
+              </div>
+
+              <Textarea
+                label="公告内容"
+                placeholder="请输入公告内容"
+                value={announcement.content}
+                variant="bordered"
+                minRows={4}
+                onChange={(e) =>
+                  setAnnouncement({ ...announcement, content: e.target.value })
+                }
+              />
+
+              <div className="flex justify-end">
+                <Button
+                  color="primary"
+                  isLoading={announcementSaving}
+                  startContent={<SaveIcon className="w-4 h-4" />}
+                  onClick={saveAnnouncement}
+                >
+                  保存公告
+                </Button>
+              </div>
+            </>
+          )}
+        </CardBody>
+      </Card>
+
+      {/* 备份与恢复 */}
+      <Card className="mt-6 shadow-md">
+        <CardHeader className="pb-4">
+          <div className="flex justify-between items-center w-full">
+            <div>
+              <h2 className="text-xl font-semibold">数据备份与恢复</h2>
+              <p className="text-sm text-gray-600 dark:text-gray-400">
+                导出或导入系统数据，支持选择特定数据类型
+              </p>
+            </div>
+          </div>
+        </CardHeader>
+
+        <Divider />
+
+        <CardBody className="space-y-6 pt-6">
+          {/* 导出部分 */}
+          <div className="space-y-4">
+            <h3 className="text-lg font-medium">导出数据</h3>
+            <p className="text-sm text-gray-600 dark:text-gray-400">
+              选择要导出的数据类型，导出为 JSON 格式文件
+            </p>
+
+            <CheckboxGroup
+              classNames={{
+                wrapper: "gap-4",
+              }}
+              label="选择导出内容"
+              orientation="horizontal"
+              value={exportTypes}
+              onValueChange={(values) => setExportTypes(values as string[])}
+            >
+              <Checkbox value="users">用户</Checkbox>
+              <Checkbox value="nodes">节点</Checkbox>
+              <Checkbox value="tunnels">隧道</Checkbox>
+              <Checkbox value="forwards">转发</Checkbox>
+              <Checkbox value="userTunnels">用户隧道权限</Checkbox>
+              <Checkbox value="speedLimits">限速规则</Checkbox>
+              <Checkbox value="tunnelGroups">隧道分组</Checkbox>
+              <Checkbox value="userGroups">用户分组</Checkbox>
+              <Checkbox value="permissions">分组权限</Checkbox>
+              <Checkbox value="configs">系统配置</Checkbox>
+            </CheckboxGroup>
+
+            <div className="flex gap-3">
+              <Button
+                color="primary"
+                isLoading={exporting}
+                onPress={handleExport}
+              >
+                {exporting ? "导出中..." : "导出数据"}
+              </Button>
+              <Button
+                variant="bordered"
+                onPress={() => {
+                  setExportTypes([
+                    "users",
+                    "nodes",
+                    "tunnels",
+                    "forwards",
+                    "userTunnels",
+                    "speedLimits",
+                    "tunnelGroups",
+                    "userGroups",
+                    "permissions",
+                    "configs",
+                  ]);
+                }}
+              >
+                全选
+              </Button>
+              <Button variant="flat" onPress={() => setExportTypes([])}>
+                清空
+              </Button>
+            </div>
+          </div>
+
+          <Divider />
+
+          {/* 导入部分 */}
+          <div className="space-y-4">
+            <h3 className="text-lg font-medium">导入数据</h3>
+            <p className="text-sm text-gray-600 dark:text-gray-400">
+              选择要导入的数据类型，支持从备份文件恢复数据
+            </p>
+
+            <CheckboxGroup
+              classNames={{
+                wrapper: "gap-4",
+              }}
+              label="选择导入内容"
+              orientation="horizontal"
+              value={importTypes}
+              onValueChange={(values) => setImportTypes(values as string[])}
+            >
+              <Checkbox value="users">用户</Checkbox>
+              <Checkbox value="nodes">节点</Checkbox>
+              <Checkbox value="tunnels">隧道</Checkbox>
+              <Checkbox value="forwards">转发</Checkbox>
+              <Checkbox value="userTunnels">用户隧道权限</Checkbox>
+              <Checkbox value="speedLimits">限速规则</Checkbox>
+              <Checkbox value="tunnelGroups">隧道分组</Checkbox>
+              <Checkbox value="userGroups">用户分组</Checkbox>
+              <Checkbox value="permissions">分组权限</Checkbox>
+              <Checkbox value="configs">系统配置</Checkbox>
+            </CheckboxGroup>
+
+            <input
+              ref={fileInputRef}
+              accept=".json"
+              className="hidden"
+              type="file"
+              onChange={handleFileChange}
+            />
+
+            <div className="flex gap-3">
+              <Button
+                color="primary"
+                isLoading={importing}
+                variant="flat"
+                onPress={() => fileInputRef.current?.click()}
+              >
+                {importing ? "导入中..." : "选择文件导入"}
+              </Button>
+              {importFileName && (
+                <span className="self-center text-sm text-gray-600 dark:text-gray-400">
+                  已选择: {importFileName}
+                </span>
+              )}
+            </div>
+          </div>
+        </CardBody>
+      </Card>
     </div>
   );
 }

vite-frontend/src/pages/dashboard.tsx

@@ -13,7 +13,7 @@ import {
   ResponsiveContainer,
 } from "recharts";
 
-import { getUserPackageInfo } from "@/api";
+import { getUserPackageInfo, getAnnouncement, type AnnouncementData } from "@/api";
 
 interface UserInfo {
   flow: number;
@@ -71,6 +71,7 @@ export default function DashboardPage() {
   const [forwardList, setForwardList] = useState<Forward[]>([]);
   const [statisticsFlows, setStatisticsFlows] = useState<StatisticsFlow[]>([]);
   const [isAdmin, setIsAdmin] = useState(false);
+  const [announcement, setAnnouncement] = useState<AnnouncementData | null>(null);
 
   const [addressModalOpen, setAddressModalOpen] = useState(false);
   const [addressModalTitle, setAddressModalTitle] = useState("");
@@ -170,22 +171,33 @@ export default function DashboardPage() {
   };
 
   useEffect(() => {
-    // 重置状态并加载数据，防止页面切换时显示旧数据
     setLoading(true);
     setUserInfo({} as UserInfo);
     setUserTunnels([]);
     setForwardList([]);
     setStatisticsFlows([]);
 
-    // 检查用户是否是管理员
     const adminStatus = localStorage.getItem("admin");
 
     setIsAdmin(adminStatus === "true");
 
     loadPackageData();
+    loadAnnouncement();
     localStorage.setItem("e", "/dashboard");
   }, []);
 
+  const loadAnnouncement = async () => {
+    try {
+      const res = await getAnnouncement();
+
+      if (res.code === 0 && res.data && res.data.enabled === 1) {
+        setAnnouncement(res.data);
+      }
+    } catch (error) {
+      console.error("Failed to load announcement:", error);
+    }
+  };
+
   const loadPackageData = async () => {
     setLoading(true);
     try {
@@ -703,7 +715,35 @@ export default function DashboardPage() {
 
   return (
     <div className="px-3 lg:px-6 py-2 lg:py-4">
-      {/* 响应式统计卡片 */}
+      {announcement && announcement.content && (
+        <Card className="mb-4 lg:mb-6 border border-blue-200 dark:border-blue-500/30 bg-gradient-to-r from-blue-50 to-purple-50 dark:from-blue-500/10 dark:to-purple-500/10">
+          <CardBody className="p-4">
+            <div className="flex items-start gap-3">
+              <div className="p-2 bg-blue-100 dark:bg-blue-500/20 rounded-lg flex-shrink-0">
+                <svg
+                  className="w-5 h-5 text-blue-600 dark:text-blue-400"
+                  fill="currentColor"
+                  viewBox="0 0 20 20"
+                >
+                  <path
+                    clipRule="evenodd"
+                    d="M18 10a8 8 0 11-16 0 8 8 0 0116 0zm-7-4a1 1 0 11-2 0 1 1 0 012 0zM9 9a1 1 0 000 2v3a1 1 0 001 1h1a1 1 0 100-2v-3a1 1 0 00-1-1H9z"
+                    fillRule="evenodd"
+                  />
+                </svg>
+              </div>
+              <div className="flex-1 min-w-0">
+                <h3 className="text-sm lg:text-base font-semibold text-blue-900 dark:text-blue-100 mb-1">
+                  公告
+                </h3>
+                <p className="text-xs lg:text-sm text-blue-800 dark:text-blue-200 whitespace-pre-wrap break-words">
+                  {announcement.content}
+                </p>
+              </div>
+            </div>
+          </CardBody>
+        </Card>
+      )}
       <div className="grid grid-cols-2 lg:grid-cols-4 gap-3 lg:gap-4 mb-6 lg:mb-8">
         <Card className="border border-gray-200 dark:border-default-200 shadow-md hover:shadow-lg transition-shadow">
           <CardBody className="p-3 lg:p-4">

vite-frontend/src/pages/index.tsx

@@ -83,8 +83,9 @@ export default function IndexPage() {
       if (response.code !== 0) {
         toast.error(response.msg || "登录失败");
         if (showCaptcha) {
-           setForm((prev) => ({ ...prev, captchaId: "" }));
+          setForm((prev) => ({ ...prev, captchaId: "" }));
         }
+
         return;
       }
 
@@ -138,11 +139,7 @@ export default function IndexPage() {
       } else {
         const configResp = await getConfigByName("cloudflare_site_key");
 
-        if (
-          configResp.code === 0 &&
-          configResp.data &&
-          configResp.data.value
-        ) {
+        if (configResp.code === 0 && configResp.data && configResp.data.value) {
           setSiteKey(configResp.data.value);
           setShowCaptcha(true);
         } else {
@@ -241,8 +238,10 @@ export default function IndexPage() {
         {showCaptcha && siteKey && (
           <div className="fixed inset-0 z-50 flex items-center justify-center">
             {/* 背景遮罩层 - 模糊效果，暗黑模式下更深 */}
-            <div 
+            <div
               className="absolute inset-0 bg-black/60 dark:bg-black/80 backdrop-blur-sm captcha-backdrop-enter"
+              role="button"
+              tabIndex={0}
               onClick={() => {
                 setShowCaptcha(false);
                 setLoading(false);
@@ -253,32 +252,35 @@ export default function IndexPage() {
                   setLoading(false);
                 }
               }}
-              role="button"
-              tabIndex={0}
             />
             {/* 验证码容器 */}
             <div className="mb-4 relative z-50 bg-white dark:bg-zinc-900 p-6 rounded-lg shadow-xl">
-              <div className="mb-4 text-center text-sm font-medium text-gray-700 dark:text-gray-200">请完成安全验证</div>
+              <div className="mb-4 text-center text-sm font-medium text-gray-700 dark:text-gray-200">
+                请完成安全验证
+              </div>
               <div className="flex justify-center">
                 <Turnstile
-                  siteKey={siteKey}
-                  onSuccess={(token) => {
-                    setForm((prev) => ({ ...prev, captchaId: token }));
-                    void performLogin(token);
+                  options={{
+                    theme: (document.documentElement.classList.contains(
+                      "dark",
+                    ) ||
+                    document.documentElement.getAttribute("data-theme") ===
+                      "dark" ||
+                    window.matchMedia("(prefers-color-scheme: dark)").matches
+                      ? "dark"
+                      : "light") as "light" | "dark" | "auto",
                   }}
+                  siteKey={siteKey}
                   onError={() => {
                     toast.error("验证失败，请刷新重试");
                     setLoading(false);
                   }}
                   onExpire={() => {
-                     setForm((prev) => ({ ...prev, captchaId: "" }));
+                    setForm((prev) => ({ ...prev, captchaId: "" }));
                   }}
-                  options={{
-                    theme: (document.documentElement.classList.contains("dark") ||
-                    document.documentElement.getAttribute("data-theme") === "dark" ||
-                    window.matchMedia("(prefers-color-scheme: dark)").matches
-                      ? "dark"
-                      : "light") as "light" | "dark" | "auto"
+                  onSuccess={(token) => {
+                    setForm((prev) => ({ ...prev, captchaId: token }));
+                    void performLogin(token);
                   }}
                 />
               </div>

vite-frontend/src/pages/node.tsx

@@ -16,6 +16,7 @@ import { Spinner } from "@heroui/spinner";
 import { Alert } from "@heroui/alert";
 import { Progress } from "@heroui/progress";
 import { Accordion, AccordionItem } from "@heroui/accordion";
+import { Select, SelectItem } from "@heroui/select";
 import { Checkbox } from "@heroui/checkbox";
 import toast from "react-hot-toast";
 import axios from "axios";
@@ -45,6 +46,10 @@ import {
   getNodeInstallCommand,
   updateNodeOrder,
   batchDeleteNodes,
+  upgradeNode,
+  batchUpgradeNodes,
+  getNodeReleases,
+  rollbackNode,
 } from "@/api";
 
 interface Node {
@@ -65,6 +70,7 @@ interface Node {
   status: number;
   isRemote?: number;
   remoteUrl?: string;
+  syncError?: string;
   connectionStatus: "online" | "offline";
   systemInfo?: {
     cpuUsage: number;
@@ -76,6 +82,8 @@ interface Node {
     uptime: number;
   } | null;
   copyLoading?: boolean;
+  upgradeLoading?: boolean;
+  rollbackLoading?: boolean;
 }
 
 interface NodeForm {
@@ -117,7 +125,12 @@ const SortableItem = ({
   };
 
   return (
-    <div ref={setNodeRef} style={style} {...attributes}>
+    <div
+      ref={setNodeRef}
+      style={style}
+      {...attributes}
+      className="overflow-hidden"
+    >
       {children(listeners)}
     </div>
   );
@@ -164,6 +177,29 @@ export default function NodePage() {
   const [installCommand, setInstallCommand] = useState("");
   const [currentNodeName, setCurrentNodeName] = useState("");
 
+  // 升级相关状态
+  const [upgradeModalOpen, setUpgradeModalOpen] = useState(false);
+  const [upgradeTarget, setUpgradeTarget] = useState<"single" | "batch">(
+    "single",
+  );
+  const [upgradeTargetNodeId, setUpgradeTargetNodeId] = useState<number | null>(
+    null,
+  );
+  const [releases, setReleases] = useState<
+    Array<{
+      version: string;
+      name: string;
+      publishedAt: string;
+      prerelease: boolean;
+    }>
+  >([]);
+  const [releasesLoading, setReleasesLoading] = useState(false);
+  const [selectedVersion, setSelectedVersion] = useState("");
+  const [batchUpgradeLoading, setBatchUpgradeLoading] = useState(false);
+  const [upgradeProgress, setUpgradeProgress] = useState<
+    Record<number, { stage: string; percent: number; message: string }>
+  >({});
+
   const websocketRef = useRef<WebSocket | null>(null);
   const reconnectTimerRef = useRef<NodeJS.Timeout | null>(null);
   const reconnectAttemptsRef = useRef(0);
@@ -219,7 +255,12 @@ export default function NodePage() {
         const nodesData: Node[] = (res.data || []).map((node: any) => ({
           ...node,
           inx: node.inx ?? 0,
-          connectionStatus: node.status === 1 ? "online" : "offline",
+          connectionStatus: node.syncError
+            ? "offline"
+            : node.status === 1
+              ? "online"
+              : "offline",
+          syncError: node.syncError || undefined,
           systemInfo: null,
           copyLoading: false,
         }));
@@ -423,6 +464,26 @@ export default function NodePage() {
           return node;
         }),
       );
+    } else if (type === "upgrade_progress") {
+      try {
+        const progressData =
+          typeof messageData === "string"
+            ? JSON.parse(messageData)
+            : messageData;
+
+        if (progressData?.data) {
+          setUpgradeProgress((prev) => ({
+            ...prev,
+            [nodeId]: {
+              stage: progressData.data.stage || "",
+              percent: progressData.data.percent || 0,
+              message: progressData.message || "",
+            },
+          }));
+        }
+      } catch {
+        // ignore parse errors
+      }
     }
   };
 
@@ -768,6 +829,106 @@ export default function NodePage() {
     }
   };
 
+  // 打开版本选择弹窗
+  const openUpgradeModal = async (
+    target: "single" | "batch",
+    nodeId?: number,
+  ) => {
+    setUpgradeTarget(target);
+    setUpgradeTargetNodeId(nodeId || null);
+    setSelectedVersion("");
+    setUpgradeModalOpen(true);
+    setReleasesLoading(true);
+    try {
+      const res = await getNodeReleases();
+
+      if (res.code === 0 && Array.isArray(res.data)) {
+        setReleases(res.data);
+      } else {
+        toast.error(res.msg || "获取版本列表失败");
+      }
+    } catch {
+      toast.error("获取版本列表失败");
+    } finally {
+      setReleasesLoading(false);
+    }
+  };
+
+  // 确认升级（从版本弹窗）
+  const handleConfirmUpgrade = async () => {
+    const version = selectedVersion || undefined;
+
+    if (upgradeTarget === "single" && upgradeTargetNodeId) {
+      setUpgradeModalOpen(false);
+      // Find the node
+      const node = nodeList.find((n) => n.id === upgradeTargetNodeId);
+
+      if (!node) return;
+      setNodeList((prev) =>
+        prev.map((n) =>
+          n.id === upgradeTargetNodeId ? { ...n, upgradeLoading: true } : n,
+        ),
+      );
+      try {
+        const res = await upgradeNode(upgradeTargetNodeId, version);
+
+        if (res.code === 0) {
+          toast.success(`节点升级命令已发送，节点将自动重启`);
+        } else {
+          toast.error(res.msg || "升级失败");
+        }
+      } catch {
+        toast.error("网络错误，请重试");
+      } finally {
+        setNodeList((prev) =>
+          prev.map((n) =>
+            n.id === upgradeTargetNodeId ? { ...n, upgradeLoading: false } : n,
+          ),
+        );
+      }
+    } else if (upgradeTarget === "batch") {
+      setBatchUpgradeLoading(true);
+      setUpgradeModalOpen(false);
+      try {
+        const res = await batchUpgradeNodes(Array.from(selectedIds), version);
+
+        if (res.code === 0) {
+          toast.success(`批量升级命令已发送到 ${selectedIds.size} 个节点`);
+        } else {
+          toast.error(res.msg || "批量升级失败");
+        }
+      } catch {
+        toast.error("网络错误，请重试");
+      } finally {
+        setBatchUpgradeLoading(false);
+      }
+    }
+  };
+
+  // 回退节点
+  const handleRollbackNode = async (node: Node) => {
+    setNodeList((prev) =>
+      prev.map((n) => (n.id === node.id ? { ...n, rollbackLoading: true } : n)),
+    );
+    try {
+      const res = await rollbackNode(node.id);
+
+      if (res.code === 0) {
+        toast.success(`节点 ${node.name} 回退命令已发送，节点将自动重启`);
+      } else {
+        toast.error(res.msg || "回退失败");
+      }
+    } catch {
+      toast.error("网络错误，请重试");
+    } finally {
+      setNodeList((prev) =>
+        prev.map((n) =>
+          n.id === node.id ? { ...n, rollbackLoading: false } : n,
+        ),
+      );
+    }
+  };
+
   // 提交表单
   const handleSubmit = async () => {
     if (!validateForm()) return;
@@ -1046,6 +1207,15 @@ export default function NodePage() {
             <Button size="sm" variant="flat" onPress={deselectAll}>
               清空
             </Button>
+            <Button
+              color="warning"
+              isLoading={batchUpgradeLoading}
+              size="sm"
+              variant="flat"
+              onPress={() => openUpgradeModal("batch")}
+            >
+              升级
+            </Button>
             <Button
               color="danger"
               size="sm"
@@ -1120,251 +1290,282 @@ export default function NodePage() {
                 return (
                   <SortableItem key={node.id} id={node.id}>
                     {(listeners) => (
-                    <Card
-                      key={node.id}
-                      className="group shadow-sm border border-divider hover:shadow-md transition-shadow duration-200"
-                    >
-                      <CardHeader className="pb-2">
-                        <div className="flex justify-between items-start w-full">
-                          <div className="flex items-center gap-2 flex-1 min-w-0">
-                            {selectMode && (
-                              <Checkbox
-                                isSelected={selectedIds.has(node.id)}
-                                onValueChange={() => toggleSelect(node.id)}
-                              />
-                            )}
-                            <h3 className="font-semibold text-foreground truncate text-sm">
-                              {node.name}
-                            </h3>
-                          </div>
-                          <div className="flex items-center gap-1.5 ml-2">
-                            <div
-                              className="cursor-grab active:cursor-grabbing p-2 text-default-400 hover:text-default-600 transition-colors touch-manipulation opacity-100 sm:opacity-0 sm:group-hover:opacity-100"
-                              {...listeners}
-                              style={{ touchAction: "none" }}
-                              title="拖拽排序"
-                            >
-                              <svg
-                                className="w-4 h-4"
-                                fill="currentColor"
-                                viewBox="0 0 20 20"
-                              >
-                                <path d="M7 2a2 2 0 1 1 .001 4.001A2 2 0 0 1 7 2zm0 6a2 2 0 1 1 .001 4.001A2 2 0 0 1 7 8zm0 6a2 2 0 1 1 .001 4.001A2 2 0 0 1 7 14zm6-8a2 2 0 1 1-.001-4.001A2 2 0 0 1 13 6zm0 2a2 2 0 1 1 .001 4.001A2 2 0 0 1 13 8zm0 6a2 2 0 1 1 .001 4.001A2 2 0 0 1 13 14z" />
-                              </svg>
+                      <Card
+                        key={node.id}
+                        className="group shadow-sm border border-divider hover:shadow-md transition-shadow duration-200 overflow-hidden"
+                      >
+                        <CardHeader className="pb-2">
+                          <div className="flex justify-between items-start w-full">
+                            <div className="flex items-center gap-2 flex-1 min-w-0">
+                              {selectMode && (
+                                <Checkbox
+                                  isSelected={selectedIds.has(node.id)}
+                                  onValueChange={() => toggleSelect(node.id)}
+                                />
+                              )}
+                              <h3 className="font-semibold text-foreground truncate text-sm">
+                                {node.name}
+                              </h3>
                             </div>
-                            {isRemoteNode && (
+                            <div className="flex items-center gap-1.5 ml-2">
+                              <div
+                                className="cursor-grab active:cursor-grabbing p-2 text-default-400 hover:text-default-600 transition-colors touch-manipulation opacity-100 sm:opacity-0 sm:group-hover:opacity-100"
+                                {...listeners}
+                                style={{ touchAction: "none" }}
+                                title="拖拽排序"
+                              >
+                                <svg
+                                  className="w-4 h-4"
+                                  fill="currentColor"
+                                  viewBox="0 0 20 20"
+                                >
+                                  <path d="M7 2a2 2 0 1 1 .001 4.001A2 2 0 0 1 7 2zm0 6a2 2 0 1 1 .001 4.001A2 2 0 0 1 7 8zm0 6a2 2 0 1 1 .001 4.001A2 2 0 0 1 7 14zm6-8a2 2 0 1 1-.001-4.001A2 2 0 0 1 13 6zm0 2a2 2 0 1 1 .001 4.001A2 2 0 0 1 13 8zm0 6a2 2 0 1 1 .001 4.001A2 2 0 0 1 13 14z" />
+                                </svg>
+                              </div>
+                              {isRemoteNode && (
+                                <Chip
+                                  className="text-xs"
+                                  color="secondary"
+                                  size="sm"
+                                  variant="flat"
+                                >
+                                  远程
+                                </Chip>
+                              )}
                               <Chip
                                 className="text-xs"
-                                color="secondary"
+                                color={
+                                  node.connectionStatus === "online"
+                                    ? "success"
+                                    : "danger"
+                                }
                                 size="sm"
                                 variant="flat"
                               >
-                                远程
+                                {node.connectionStatus === "online"
+                                  ? "在线"
+                                  : "离线"}
                               </Chip>
-                            )}
-                            <Chip
-                              className="text-xs"
-                              color={
-                                node.connectionStatus === "online"
-                                  ? "success"
-                                  : "danger"
-                              }
-                              size="sm"
-                              variant="flat"
-                            >
-                              {node.connectionStatus === "online"
-                                ? "在线"
-                                : "离线"}
-                            </Chip>
-                          </div>
-                        </div>
-                      </CardHeader>
-
-                      <CardBody className="pt-0 pb-3">
-                        {/* 基础信息 */}
-                        <div className="space-y-2 mb-4">
-                          <div className="flex justify-between items-center text-sm min-w-0">
-                            <span className="text-default-600 flex-shrink-0">
-                              IP
-                            </span>
-                            <div className="text-right text-xs min-w-0 flex-1 ml-2">
-                              {node.serverIpV4?.trim() ||
-                              node.serverIpV6?.trim() ? (
-                                <div className="space-y-0.5">
-                                  {node.serverIpV4?.trim() && (
-                                    <span
-                                      className="font-mono truncate block"
-                                      title={node.serverIpV4.trim()}
-                                    >
-                                      {node.serverIpV4.trim()}
-                                    </span>
-                                  )}
-                                  {node.serverIpV6?.trim() && (
-                                    <span
-                                      className="font-mono truncate block"
-                                      title={node.serverIpV6.trim()}
-                                    >
-                                      {node.serverIpV6.trim()}
-                                    </span>
-                                  )}
-                                </div>
-                              ) : (
-                                <span
-                                  className="font-mono truncate block"
-                                  title={node.serverIp.trim()}
-                                >
-                                  {node.serverIp.trim()}
-                                </span>
-                              )}
                             </div>
                           </div>
+                        </CardHeader>
+
+                        <CardBody className="pt-0 pb-3">
+                          {isRemoteNode && node.syncError && (
+                            <div className="mb-3 px-2 py-1.5 rounded-md bg-warning-50 dark:bg-warning-100/10 text-warning-700 dark:text-warning-400 text-xs">
+                              {node.syncError === "provider_share_deleted"
+                                ? "提供方已删除该分享"
+                                : node.syncError === "provider_share_disabled"
+                                  ? "提供方已禁用该分享"
+                                  : node.syncError === "provider_share_expired"
+                                    ? "提供方分享已过期"
+                                    : `远程同步失败: ${node.syncError}`}
+                            </div>
+                          )}
+                          {/* 基础信息 */}
+                          <div className="space-y-2 mb-4">
+                            <div className="flex justify-between items-center text-sm min-w-0">
+                              <span className="text-default-600 flex-shrink-0">
+                                IP
+                              </span>
+                              <div className="text-right text-xs min-w-0 flex-1 ml-2">
+                                {node.serverIpV4?.trim() ||
+                                node.serverIpV6?.trim() ? (
+                                  <div className="space-y-0.5">
+                                    {node.serverIpV4?.trim() && (
+                                      <span
+                                        className="font-mono truncate block"
+                                        title={node.serverIpV4.trim()}
+                                      >
+                                        {node.serverIpV4.trim()}
+                                      </span>
+                                    )}
+                                    {node.serverIpV6?.trim() && (
+                                      <span
+                                        className="font-mono truncate block"
+                                        title={node.serverIpV6.trim()}
+                                      >
+                                        {node.serverIpV6.trim()}
+                                      </span>
+                                    )}
+                                  </div>
+                                ) : (
+                                  <span
+                                    className="font-mono truncate block"
+                                    title={node.serverIp.trim()}
+                                  >
+                                    {node.serverIp.trim()}
+                                  </span>
+                                )}
+                              </div>
+                            </div>
+                            {!isRemoteNode && (
+                              <>
+                                <div className="flex justify-between text-sm">
+                                  <span className="text-default-600">版本</span>
+                                  <span className="text-xs">
+                                    {node.version || "未知"}
+                                  </span>
+                                </div>
+                                {upgradeProgress[node.id] &&
+                                  upgradeProgress[node.id].percent < 100 && (
+                                    <div className="mt-1">
+                                      <Progress
+                                        showValueLabel
+                                        aria-label="升级进度"
+                                        color="warning"
+                                        label={upgradeProgress[node.id].message}
+                                        size="sm"
+                                        value={upgradeProgress[node.id].percent}
+                                      />
+                                    </div>
+                                  )}
+                                <div className="flex justify-between text-sm">
+                                  <span className="text-default-600">
+                                    开机时间
+                                  </span>
+                                  <span className="text-xs">
+                                    {node.connectionStatus === "online" &&
+                                    node.systemInfo
+                                      ? formatUptime(node.systemInfo.uptime)
+                                      : "-"}
+                                  </span>
+                                </div>
+                              </>
+                            )}
+                          </div>
+
                           {!isRemoteNode && (
                             <>
-                              <div className="flex justify-between text-sm">
-                                <span className="text-default-600">版本</span>
-                                <span className="text-xs">
-                                  {node.version || "未知"}
-                                </span>
-                              </div>
-                              <div className="flex justify-between text-sm">
-                                <span className="text-default-600">开机时间</span>
-                                <span className="text-xs">
-                                  {node.connectionStatus === "online" &&
-                                  node.systemInfo
-                                    ? formatUptime(node.systemInfo.uptime)
-                                    : "-"}
-                                </span>
+                              {/* 系统监控 */}
+                              <div className="space-y-3 mb-4">
+                                <div className="grid grid-cols-2 gap-3">
+                                  <div>
+                                    <div className="flex justify-between text-xs mb-1">
+                                      <span>CPU</span>
+                                      <span className="font-mono">
+                                        {node.connectionStatus === "online" &&
+                                        node.systemInfo
+                                          ? `${node.systemInfo.cpuUsage.toFixed(1)}%`
+                                          : "-"}
+                                      </span>
+                                    </div>
+                                    <Progress
+                                      aria-label="CPU使用率"
+                                      color={getProgressColor(
+                                        node.connectionStatus === "online" &&
+                                          node.systemInfo
+                                          ? node.systemInfo.cpuUsage
+                                          : 0,
+                                        node.connectionStatus !== "online",
+                                      )}
+                                      size="sm"
+                                      value={
+                                        node.connectionStatus === "online" &&
+                                        node.systemInfo
+                                          ? node.systemInfo.cpuUsage
+                                          : 0
+                                      }
+                                    />
+                                  </div>
+                                  <div>
+                                    <div className="flex justify-between text-xs mb-1">
+                                      <span>内存</span>
+                                      <span className="font-mono">
+                                        {node.connectionStatus === "online" &&
+                                        node.systemInfo
+                                          ? `${node.systemInfo.memoryUsage.toFixed(1)}%`
+                                          : "-"}
+                                      </span>
+                                    </div>
+                                    <Progress
+                                      aria-label="内存使用率"
+                                      color={getProgressColor(
+                                        node.connectionStatus === "online" &&
+                                          node.systemInfo
+                                          ? node.systemInfo.memoryUsage
+                                          : 0,
+                                        node.connectionStatus !== "online",
+                                      )}
+                                      size="sm"
+                                      value={
+                                        node.connectionStatus === "online" &&
+                                        node.systemInfo
+                                          ? node.systemInfo.memoryUsage
+                                          : 0
+                                      }
+                                    />
+                                  </div>
+                                </div>
+
+                                <div className="grid grid-cols-2 gap-2 text-xs">
+                                  <div className="text-center p-2 bg-default-50 dark:bg-default-100 rounded">
+                                    <div className="text-default-600 mb-0.5">
+                                      上传
+                                    </div>
+                                    <div className="font-mono">
+                                      {node.connectionStatus === "online" &&
+                                      node.systemInfo
+                                        ? formatSpeed(
+                                            node.systemInfo.uploadSpeed,
+                                          )
+                                        : "-"}
+                                    </div>
+                                  </div>
+                                  <div className="text-center p-2 bg-default-50 dark:bg-default-100 rounded">
+                                    <div className="text-default-600 mb-0.5">
+                                      下载
+                                    </div>
+                                    <div className="font-mono">
+                                      {node.connectionStatus === "online" &&
+                                      node.systemInfo
+                                        ? formatSpeed(
+                                            node.systemInfo.downloadSpeed,
+                                          )
+                                        : "-"}
+                                    </div>
+                                  </div>
+                                </div>
+
+                                {/* 流量统计 */}
+                                <div className="grid grid-cols-2 gap-2 text-xs">
+                                  <div className="text-center p-2 bg-primary-50 dark:bg-primary-100/20 rounded border border-primary-200 dark:border-primary-300/20">
+                                    <div className="text-primary-600 dark:text-primary-400 mb-0.5">
+                                      ↑ 上行流量
+                                    </div>
+                                    <div className="font-mono text-primary-700 dark:text-primary-300">
+                                      {node.connectionStatus === "online" &&
+                                      node.systemInfo
+                                        ? formatTraffic(
+                                            node.systemInfo.uploadTraffic,
+                                          )
+                                        : "-"}
+                                    </div>
+                                  </div>
+                                  <div className="text-center p-2 bg-success-50 dark:bg-success-100/20 rounded border border-success-200 dark:border-success-300/20">
+                                    <div className="text-success-600 dark:text-success-400 mb-0.5">
+                                      ↓ 下行流量
+                                    </div>
+                                    <div className="font-mono text-success-700 dark:text-success-300">
+                                      {node.connectionStatus === "online" &&
+                                      node.systemInfo
+                                        ? formatTraffic(
+                                            node.systemInfo.downloadTraffic,
+                                          )
+                                        : "-"}
+                                    </div>
+                                  </div>
+                                </div>
                               </div>
                             </>
                           )}
-                        </div>
 
-                        {!isRemoteNode && (
-                          <>
-                            {/* 系统监控 */}
-                            <div className="space-y-3 mb-4">
-                              <div className="grid grid-cols-2 gap-3">
-                                <div>
-                                  <div className="flex justify-between text-xs mb-1">
-                                    <span>CPU</span>
-                                    <span className="font-mono">
-                                      {node.connectionStatus === "online" &&
-                                      node.systemInfo
-                                        ? `${node.systemInfo.cpuUsage.toFixed(1)}%`
-                                        : "-"}
-                                    </span>
-                                  </div>
-                                  <Progress
-                                    aria-label="CPU使用率"
-                                    color={getProgressColor(
-                                      node.connectionStatus === "online" &&
-                                        node.systemInfo
-                                        ? node.systemInfo.cpuUsage
-                                        : 0,
-                                      node.connectionStatus !== "online",
-                                    )}
-                                    size="sm"
-                                    value={
-                                      node.connectionStatus === "online" &&
-                                      node.systemInfo
-                                        ? node.systemInfo.cpuUsage
-                                        : 0
-                                    }
-                                  />
-                                </div>
-                                <div>
-                                  <div className="flex justify-between text-xs mb-1">
-                                    <span>内存</span>
-                                    <span className="font-mono">
-                                      {node.connectionStatus === "online" &&
-                                      node.systemInfo
-                                        ? `${node.systemInfo.memoryUsage.toFixed(1)}%`
-                                        : "-"}
-                                    </span>
-                                  </div>
-                                  <Progress
-                                    aria-label="内存使用率"
-                                    color={getProgressColor(
-                                      node.connectionStatus === "online" &&
-                                        node.systemInfo
-                                        ? node.systemInfo.memoryUsage
-                                        : 0,
-                                      node.connectionStatus !== "online",
-                                    )}
-                                    size="sm"
-                                    value={
-                                      node.connectionStatus === "online" &&
-                                      node.systemInfo
-                                        ? node.systemInfo.memoryUsage
-                                        : 0
-                                    }
-                                  />
-                                </div>
-                              </div>
-
-                              <div className="grid grid-cols-2 gap-2 text-xs">
-                                <div className="text-center p-2 bg-default-50 dark:bg-default-100 rounded">
-                                  <div className="text-default-600 mb-0.5">
-                                    上传
-                                  </div>
-                                  <div className="font-mono">
-                                    {node.connectionStatus === "online" &&
-                                    node.systemInfo
-                                      ? formatSpeed(node.systemInfo.uploadSpeed)
-                                      : "-"}
-                                  </div>
-                                </div>
-                                <div className="text-center p-2 bg-default-50 dark:bg-default-100 rounded">
-                                  <div className="text-default-600 mb-0.5">
-                                    下载
-                                  </div>
-                                  <div className="font-mono">
-                                    {node.connectionStatus === "online" &&
-                                    node.systemInfo
-                                      ? formatSpeed(node.systemInfo.downloadSpeed)
-                                      : "-"}
-                                  </div>
-                                </div>
-                              </div>
-
-                              {/* 流量统计 */}
-                              <div className="grid grid-cols-2 gap-2 text-xs">
-                                <div className="text-center p-2 bg-primary-50 dark:bg-primary-100/20 rounded border border-primary-200 dark:border-primary-300/20">
-                                  <div className="text-primary-600 dark:text-primary-400 mb-0.5">
-                                    ↑ 上行流量
-                                  </div>
-                                  <div className="font-mono text-primary-700 dark:text-primary-300">
-                                    {node.connectionStatus === "online" &&
-                                    node.systemInfo
-                                      ? formatTraffic(node.systemInfo.uploadTraffic)
-                                      : "-"}
-                                  </div>
-                                </div>
-                                <div className="text-center p-2 bg-success-50 dark:bg-success-100/20 rounded border border-success-200 dark:border-success-300/20">
-                                  <div className="text-success-600 dark:text-success-400 mb-0.5">
-                                    ↓ 下行流量
-                                  </div>
-                                  <div className="font-mono text-success-700 dark:text-success-300">
-                                    {node.connectionStatus === "online" &&
-                                    node.systemInfo
-                                      ? formatTraffic(
-                                          node.systemInfo.downloadTraffic,
-                                        )
-                                      : "-"}
-                                  </div>
-                                </div>
-                              </div>
-                            </div>
-                          </>
-                        )}
-
-                        {/* 操作按钮 */}
-                        <div className="space-y-1.5">
-                          <div className="flex gap-1.5">
+                          {/* 操作按钮 */}
+                          <div className="space-y-1.5">
                             {!isRemoteNode && (
-                              <>
+                              <div className="grid grid-cols-3 gap-1.5">
                                 <Button
-                                  className="flex-1 min-h-8"
+                                  className="min-h-8"
                                   color="success"
                                   isLoading={node.copyLoading}
                                   size="sm"
@@ -1374,7 +1575,41 @@ export default function NodePage() {
                                   安装
                                 </Button>
                                 <Button
-                                  className="flex-1 min-h-8"
+                                  className="min-h-8"
+                                  color="warning"
+                                  isDisabled={
+                                    node.connectionStatus !== "online"
+                                  }
+                                  isLoading={node.upgradeLoading}
+                                  size="sm"
+                                  variant="flat"
+                                  onPress={() =>
+                                    openUpgradeModal("single", node.id)
+                                  }
+                                >
+                                  升级
+                                </Button>
+                                <Button
+                                  className="min-h-8"
+                                  color="secondary"
+                                  isDisabled={
+                                    node.connectionStatus !== "online"
+                                  }
+                                  isLoading={node.rollbackLoading}
+                                  size="sm"
+                                  variant="flat"
+                                  onPress={() => handleRollbackNode(node)}
+                                >
+                                  回退
+                                </Button>
+                              </div>
+                            )}
+                            <div
+                              className={`grid gap-1.5 ${isRemoteNode ? "grid-cols-1" : "grid-cols-2"}`}
+                            >
+                              {!isRemoteNode && (
+                                <Button
+                                  className="min-h-8"
                                   color="primary"
                                   size="sm"
                                   variant="flat"
@@ -1382,23 +1617,22 @@ export default function NodePage() {
                                 >
                                   编辑
                                 </Button>
-                              </>
-                            )}
-                            <Button
-                              className={`min-h-8 ${isRemoteNode ? "w-full" : "flex-1"}`}
-                              color="danger"
-                              size="sm"
-                              variant="flat"
-                              onPress={() => handleDelete(node)}
-                            >
-                              删除
-                            </Button>
+                              )}
+                              <Button
+                                className="min-h-8"
+                                color="danger"
+                                size="sm"
+                                variant="flat"
+                                onPress={() => handleDelete(node)}
+                              >
+                                删除
+                              </Button>
+                            </div>
                           </div>
-                        </div>
-                      </CardBody>
-                    </Card>
-                  )}
-                </SortableItem>
+                        </CardBody>
+                      </Card>
+                    )}
+                  </SortableItem>
                 );
               })}
             </div>
@@ -1831,6 +2065,90 @@ export default function NodePage() {
         </ModalContent>
       </Modal>
 
+      {/* 版本选择升级模态框 */}
+      <Modal
+        backdrop="blur"
+        isOpen={upgradeModalOpen}
+        placement="center"
+        scrollBehavior="outside"
+        size="md"
+        onOpenChange={setUpgradeModalOpen}
+      >
+        <ModalContent>
+          {(onClose) => (
+            <>
+              <ModalHeader className="flex flex-col gap-1">
+                <h2 className="text-xl font-bold">
+                  {upgradeTarget === "batch"
+                    ? `批量升级 (${selectedIds.size} 个节点)`
+                    : "升级节点"}
+                </h2>
+              </ModalHeader>
+              <ModalBody>
+                {releasesLoading ? (
+                  <div className="flex justify-center py-8">
+                    <Spinner size="lg" />
+                  </div>
+                ) : (
+                  <div className="space-y-4">
+                    <Select
+                      label="选择版本"
+                      placeholder="留空则使用最新版本"
+                      selectedKeys={selectedVersion ? [selectedVersion] : []}
+                      onSelectionChange={(keys) => {
+                        const selected = Array.from(keys)[0] as string;
+
+                        setSelectedVersion(selected || "");
+                      }}
+                    >
+                      {releases.map((r) => (
+                        <SelectItem key={r.version} textValue={r.version}>
+                          <div className="flex justify-between items-center">
+                            <span>{r.version}</span>
+                            <span className="text-xs text-default-400">
+                              {r.publishedAt
+                                ? new Date(r.publishedAt).toLocaleDateString()
+                                : ""}
+                              {r.prerelease && (
+                                <Chip
+                                  className="ml-1"
+                                  color="warning"
+                                  size="sm"
+                                  variant="flat"
+                                >
+                                  预览
+                                </Chip>
+                              )}
+                            </span>
+                          </div>
+                        </SelectItem>
+                      ))}
+                    </Select>
+                    <p className="text-sm text-default-500">
+                      {selectedVersion
+                        ? `将升级到版本 ${selectedVersion}`
+                        : "未选择版本，将自动使用最新稳定版"}
+                    </p>
+                  </div>
+                )}
+              </ModalBody>
+              <ModalFooter>
+                <Button variant="light" onPress={onClose}>
+                  取消
+                </Button>
+                <Button
+                  color="warning"
+                  isDisabled={releasesLoading}
+                  onPress={handleConfirmUpgrade}
+                >
+                  确认升级
+                </Button>
+              </ModalFooter>
+            </>
+          )}
+        </ModalContent>
+      </Modal>
+
       {/* 批量删除确认模态框 */}
       <Modal
         backdrop="blur"

vite-frontend/src/pages/panel-sharing.tsx

@@ -12,6 +12,7 @@ import {
 } from "@heroui/modal";
 import { Select, SelectItem } from "@heroui/select";
 import { toast } from "react-hot-toast";
+
 import {
   getNodeList,
   createPeerShare,
@@ -20,6 +21,7 @@ import {
   resetPeerShareFlow,
   getPeerRemoteUsageList,
   importRemoteNode,
+  updatePeerShare,
 } from "@/api";
 
 interface Node {
@@ -77,6 +79,7 @@ interface RemoteUsageNode {
   usedPorts: number[];
   bindings: RemoteUsageBinding[];
   activeBindingNum: number;
+  syncError?: string;
 }
 
 export default function PanelSharingPage() {
@@ -91,6 +94,7 @@ export default function PanelSharingPage() {
 
   // Modals
   const [createShareOpen, setCreateShareOpen] = useState(false);
+  const [editShareOpen, setEditShareOpen] = useState(false);
   const [importNodeOpen, setImportNodeOpen] = useState(false);
 
   // Forms
@@ -110,10 +114,22 @@ export default function PanelSharingPage() {
     token: "",
   });
 
+  const [editForm, setEditForm] = useState({
+    id: 0,
+    name: "",
+    maxBandwidth: 0,
+    expiryTime: 0,
+    portRangeStart: 10000,
+    portRangeEnd: 20000,
+    allowedDomains: "",
+    allowedIps: "",
+  });
+
   const loadShares = useCallback(async () => {
     setLoading(true);
     try {
       const res = await getPeerShareList();
+
       if (res.code === 0) {
         setShares(res.data || []);
       } else {
@@ -127,10 +143,12 @@ export default function PanelSharingPage() {
   const loadNodes = useCallback(async () => {
     try {
       const res = await getNodeList();
+
       if (res.code === 0) {
         const localNodes: Node[] = (res.data || []).filter(
           (node: Node) => (node?.isRemote ?? 0) !== 1,
         );
+
         setNodes(localNodes);
         setShareForm((prev) => {
           if (!prev.nodeId) {
@@ -139,6 +157,7 @@ export default function PanelSharingPage() {
           const hasSelectedNode = localNodes.some(
             (node: Node) => String(node.id) === prev.nodeId,
           );
+
           return hasSelectedNode ? prev : { ...prev, nodeId: "" };
         });
       }
@@ -151,6 +170,7 @@ export default function PanelSharingPage() {
     setRemoteUsageLoading(true);
     try {
       const res = await getPeerRemoteUsageList();
+
       if (res.code === 0) {
         setRemoteUsageNodes(res.data || []);
       } else {
@@ -165,6 +185,7 @@ export default function PanelSharingPage() {
     if (selectedTab === "my-shares") {
       loadShares();
       loadNodes();
+
       return;
     }
     if (selectedTab === "remote-nodes") {
@@ -175,15 +196,19 @@ export default function PanelSharingPage() {
   const handleCreateShare = async () => {
     if (!shareForm.name || !shareForm.nodeId) {
       toast.error("请填写必要信息");
+
       return;
     }
     const nodeId = parseInt(shareForm.nodeId, 10);
+
     if (Number.isNaN(nodeId) || !nodes.some((node) => node.id === nodeId)) {
       toast.error("仅可选择本地节点");
+
       return;
     }
     if (shareForm.maxBandwidth < 0) {
       toast.error("流量上限不能为负数");
+
       return;
     }
     try {
@@ -199,6 +224,7 @@ export default function PanelSharingPage() {
         allowedDomains: shareForm.allowedDomains,
         allowedIps: shareForm.allowedIps,
       });
+
       if (res.code === 0) {
         toast.success("创建成功");
         setCreateShareOpen(false);
@@ -214,6 +240,7 @@ export default function PanelSharingPage() {
   const handleDeleteShare = async (id: number) => {
     try {
       const res = await deletePeerShare(id);
+
       if (res.code === 0) {
         toast.success("删除成功");
         loadShares();
@@ -228,6 +255,7 @@ export default function PanelSharingPage() {
   const handleResetShareFlow = async (id: number) => {
     try {
       const res = await resetPeerShareFlow(id);
+
       if (res.code === 0) {
         toast.success("共享流量已重置");
         loadShares();
@@ -239,22 +267,77 @@ export default function PanelSharingPage() {
     }
   };
 
+  const openEditShare = (share: PeerShare) => {
+    setEditForm({
+      id: share.id,
+      name: share.name,
+      maxBandwidth:
+        share.maxBandwidth > 0
+          ? Math.round(share.maxBandwidth / (1024 * 1024 * 1024))
+          : 0,
+      expiryTime: share.expiryTime,
+      portRangeStart: share.portRangeStart,
+      portRangeEnd: share.portRangeEnd,
+      allowedDomains: share.allowedDomains || "",
+      allowedIps: share.allowedIps || "",
+    });
+    setEditShareOpen(true);
+  };
+
+  const handleEditShare = async () => {
+    if (!editForm.name) {
+      toast.error("名称不能为空");
+
+      return;
+    }
+    if (editForm.maxBandwidth < 0) {
+      toast.error("流量上限不能为负数");
+
+      return;
+    }
+    try {
+      const res = await updatePeerShare({
+        id: editForm.id,
+        name: editForm.name,
+        maxBandwidth: Math.max(0, editForm.maxBandwidth) * 1024 * 1024 * 1024,
+        expiryTime: editForm.expiryTime,
+        portRangeStart: editForm.portRangeStart,
+        portRangeEnd: editForm.portRangeEnd,
+        allowedDomains: editForm.allowedDomains,
+        allowedIps: editForm.allowedIps,
+      });
+
+      if (res.code === 0) {
+        toast.success("编辑成功");
+        setEditShareOpen(false);
+        loadShares();
+      } else {
+        toast.error(res.msg || "编辑失败");
+      }
+    } catch {
+      toast.error("网络错误");
+    }
+  };
+
   const handleImportNode = async () => {
     if (!importForm.remoteUrl || !importForm.token) {
       toast.error("请填写完整信息");
+
       return;
     }
     try {
       // Automatically add http/https if missing
       let url = importForm.remoteUrl.trim();
+
       if (!url.startsWith("http")) {
         url = "http://" + url;
       }
-      
+
       const res = await importRemoteNode({
         remoteUrl: url,
         token: importForm.token.trim(),
       });
+
       if (res.code === 0) {
         toast.success("导入成功，请前往节点列表查看");
         setImportNodeOpen(false);
@@ -275,9 +358,14 @@ export default function PanelSharingPage() {
 
   const formatFlowGB = (bytes: number) => {
     if (!Number.isFinite(bytes) || bytes <= 0) {
-      return "0.00 GB";
+      return "0 B";
     }
-    return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)} GB`;
+    if (bytes < 1024) return bytes + " B";
+    if (bytes < 1024 * 1024) return (bytes / 1024).toFixed(2) + " KB";
+    if (bytes < 1024 * 1024 * 1024)
+      return (bytes / (1024 * 1024)).toFixed(2) + " MB";
+
+    return (bytes / (1024 * 1024 * 1024)).toFixed(2) + " GB";
   };
 
   const formatChainType = (chainType: number, hopInx: number) => {
@@ -287,6 +375,7 @@ export default function PanelSharingPage() {
     if (chainType === 3) {
       return "出口节点";
     }
+
     return "未知链路";
   };
 
@@ -297,6 +386,7 @@ export default function PanelSharingPage() {
       </div>
 
       <Tabs
+        disableCursorAnimation
         aria-label="Options"
         selectedKey={selectedTab}
         onSelectionChange={(k) => setSelectedTab(k as string)}
@@ -305,11 +395,14 @@ export default function PanelSharingPage() {
           <Card>
             <CardBody>
               <div className="mb-4">
-                <Button color="primary" onPress={() => setCreateShareOpen(true)}>
+                <Button
+                  color="primary"
+                  onPress={() => setCreateShareOpen(true)}
+                >
                   创建分享
                 </Button>
               </div>
-              
+
               {loading ? (
                 <div className="text-center py-10 text-gray-500">加载中...</div>
               ) : shares.length === 0 ? (
@@ -317,10 +410,20 @@ export default function PanelSharingPage() {
               ) : (
                 <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
                   {shares.map((share) => (
-                    <Card key={share.id} className="border border-divider shadow-sm">
+                    <Card
+                      key={share.id}
+                      className="border border-divider shadow-sm"
+                    >
                       <CardHeader className="flex justify-between">
                         <h3 className="font-bold">{share.name}</h3>
                         <div className="flex gap-2">
+                          <Button
+                            size="sm"
+                            variant="flat"
+                            onPress={() => openEditShare(share)}
+                          >
+                            编辑
+                          </Button>
                           <Button
                             size="sm"
                             variant="flat"
@@ -328,29 +431,67 @@ export default function PanelSharingPage() {
                           >
                             重置流量
                           </Button>
-                          <Button size="sm" color="danger" variant="flat" onPress={() => handleDeleteShare(share.id)}>删除</Button>
+                          <Button
+                            color="danger"
+                            size="sm"
+                            variant="flat"
+                            onPress={() => handleDeleteShare(share.id)}
+                          >
+                            删除
+                          </Button>
                         </div>
                       </CardHeader>
                       <CardBody className="text-sm space-y-2">
-                        <p>端口范围: {share.portRangeStart} - {share.portRangeEnd}</p>
-                        <p>流量上限: {share.maxBandwidth > 0 ? formatFlowGB(share.maxBandwidth) : "不限制"}</p>
+                        <p>
+                          端口范围: {share.portRangeStart} -{" "}
+                          {share.portRangeEnd}
+                        </p>
+                        <p>
+                          流量上限:{" "}
+                          {share.maxBandwidth > 0
+                            ? formatFlowGB(share.maxBandwidth)
+                            : "不限制"}
+                        </p>
                         <p>当前流量: {formatFlowGB(share.currentFlow || 0)}</p>
-                        <p>远程占用端口: {share.usedPorts && share.usedPorts.length > 0 ? share.usedPorts.join(", ") : "暂无"}</p>
-                        {share.usedPortDetails && share.usedPortDetails.length > 0 && (
-                          <div className="flex flex-wrap gap-2">
-                            {share.usedPortDetails.map((item) => (
-                              <span key={item.runtimeId} className="text-xs rounded-full px-2 py-1 bg-default-100">
-                                {item.port} / {item.role || "reserved"}
-                              </span>
-                            ))}
-                          </div>
+                        <p>
+                          远程占用端口:{" "}
+                          {share.usedPorts && share.usedPorts.length > 0
+                            ? share.usedPorts.join(", ")
+                            : "暂无"}
+                        </p>
+                        {share.usedPortDetails &&
+                          share.usedPortDetails.length > 0 && (
+                            <div className="flex flex-wrap gap-2">
+                              {share.usedPortDetails.map((item) => (
+                                <span
+                                  key={item.runtimeId}
+                                  className="text-xs rounded-full px-2 py-1 bg-default-100"
+                                >
+                                  {item.port} / {item.role || "reserved"}
+                                </span>
+                              ))}
+                            </div>
+                          )}
+                        {share.allowedDomains && (
+                          <p>允许域名: {share.allowedDomains}</p>
                         )}
-                        {share.allowedDomains && <p>允许域名: {share.allowedDomains}</p>}
-                        {share.allowedIps && <p>允许API IP: {share.allowedIps}</p>}
-                        <p>过期时间: {share.expiryTime === 0 ? "永久" : new Date(share.expiryTime).toLocaleDateString()}</p>
+                        {share.allowedIps && (
+                          <p>允许API IP: {share.allowedIps}</p>
+                        )}
+                        <p>
+                          过期时间:{" "}
+                          {share.expiryTime === 0
+                            ? "永久"
+                            : new Date(share.expiryTime).toLocaleDateString()}
+                        </p>
                         <div className="flex gap-2">
                           <Input readOnly size="sm" value={share.token} />
-                          <Button size="sm" onPress={() => copyToken(share.token)}>复制</Button>
+                          <Button
+                            size="sm"
+                            onPress={() => copyToken(share.token)}
+                          >
+                            复制
+                          </Button>
                         </div>
                       </CardBody>
                     </Card>
@@ -364,7 +505,10 @@ export default function PanelSharingPage() {
           <Card>
             <CardBody>
               <div className="mb-4">
-                <Button color="secondary" onPress={() => setImportNodeOpen(true)}>
+                <Button
+                  color="secondary"
+                  onPress={() => setImportNodeOpen(true)}
+                >
                   导入远程节点
                 </Button>
               </div>
@@ -374,31 +518,71 @@ export default function PanelSharingPage() {
               ) : remoteUsageNodes.length === 0 ? (
                 <div className="text-center py-10 text-gray-500">
                   <p>暂无远程节点占用记录。</p>
-                  <p className="mt-2">导入远程节点并创建隧道后，这里会显示远端端口占用情况。</p>
+                  <p className="mt-2">
+                    导入远程节点并创建隧道后，这里会显示远端端口占用情况。
+                  </p>
                 </div>
               ) : (
                 <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
                   {remoteUsageNodes.map((node) => (
-                    <Card key={node.nodeId} className="border border-divider shadow-sm">
+                    <Card
+                      key={node.nodeId}
+                      className="border border-divider shadow-sm"
+                    >
                       <CardHeader className="flex justify-between">
                         <h3 className="font-bold">{node.nodeName}</h3>
-                        <span className="text-xs text-default-500">绑定 {node.activeBindingNum || 0}</span>
+                        <span className="text-xs text-default-500">
+                          绑定 {node.activeBindingNum || 0}
+                        </span>
                       </CardHeader>
                       <CardBody className="text-sm space-y-2">
+                        {node.syncError && (
+                          <div className="px-2 py-1.5 rounded-md bg-warning-50 dark:bg-warning-100/10 text-warning-700 dark:text-warning-400 text-xs">
+                            {node.syncError === "provider_share_deleted"
+                              ? "提供方已删除该分享"
+                              : node.syncError === "provider_share_disabled"
+                                ? "提供方已禁用该分享"
+                                : node.syncError === "provider_share_expired"
+                                  ? "提供方分享已过期"
+                                  : `远程同步失败: ${node.syncError}`}
+                          </div>
+                        )}
                         {node.remoteUrl && <p>远程地址: {node.remoteUrl}</p>}
                         <p>共享ID: {node.shareId || "-"}</p>
-                        <p>端口范围: {node.portRangeStart > 0 && node.portRangeEnd > 0 ? `${node.portRangeStart} - ${node.portRangeEnd}` : "-"}</p>
-                        <p>共享流量: {node.maxBandwidth > 0 ? `${formatFlowGB(node.currentFlow || 0)} / ${formatFlowGB(node.maxBandwidth)}` : `${formatFlowGB(node.currentFlow || 0)} / 不限制`}</p>
-                        <p>远端占用端口: {node.usedPorts && node.usedPorts.length > 0 ? node.usedPorts.join(", ") : "暂无"}</p>
+                        <p>
+                          端口范围:{" "}
+                          {node.portRangeStart > 0 && node.portRangeEnd > 0
+                            ? `${node.portRangeStart} - ${node.portRangeEnd}`
+                            : "-"}
+                        </p>
+                        <p>
+                          共享流量:{" "}
+                          {node.maxBandwidth > 0
+                            ? `${formatFlowGB(node.currentFlow || 0)} / ${formatFlowGB(node.maxBandwidth)}`
+                            : `${formatFlowGB(node.currentFlow || 0)} / 不限制`}
+                        </p>
+                        <p>
+                          远端占用端口:{" "}
+                          {node.usedPorts && node.usedPorts.length > 0
+                            ? node.usedPorts.join(", ")
+                            : "暂无"}
+                        </p>
                         {node.bindings && node.bindings.length > 0 && (
                           <div className="space-y-1 pt-1">
                             {node.bindings.map((binding) => (
-                              <p key={binding.bindingId} className="text-xs text-default-600">
-                                隧道 {binding.tunnelName || `#${binding.tunnelId}`}
+                              <p
+                                key={binding.bindingId}
+                                className="text-xs text-default-600"
+                              >
+                                隧道{" "}
+                                {binding.tunnelName || `#${binding.tunnelId}`}
                                 {" · "}
                                 端口 {binding.allocatedPort}
                                 {" · "}
-                                {formatChainType(binding.chainType, binding.hopInx)}
+                                {formatChainType(
+                                  binding.chainType,
+                                  binding.hopInx,
+                                )}
                               </p>
                             ))}
                           </div>
@@ -422,13 +606,17 @@ export default function PanelSharingPage() {
               label="名称"
               placeholder="备注名称"
               value={shareForm.name}
-              onChange={(e) => setShareForm({ ...shareForm, name: e.target.value })}
+              onChange={(e) =>
+                setShareForm({ ...shareForm, name: e.target.value })
+              }
             />
             <Select
               label="选择节点"
               placeholder="选择要分享的本地节点"
               selectedKeys={shareForm.nodeId ? [shareForm.nodeId] : []}
-              onChange={(e) => setShareForm({ ...shareForm, nodeId: e.target.value })}
+              onChange={(e) =>
+                setShareForm({ ...shareForm, nodeId: e.target.value })
+              }
             >
               {nodes.map((node) => (
                 <SelectItem key={node.id} textValue={node.name}>
@@ -441,47 +629,168 @@ export default function PanelSharingPage() {
                 label="起始端口"
                 type="number"
                 value={shareForm.portRangeStart.toString()}
-                onChange={(e) => setShareForm({ ...shareForm, portRangeStart: parseInt(e.target.value) })}
+                onChange={(e) =>
+                  setShareForm({
+                    ...shareForm,
+                    portRangeStart: parseInt(e.target.value),
+                  })
+                }
               />
               <Input
                 label="结束端口"
                 type="number"
                 value={shareForm.portRangeEnd.toString()}
-                onChange={(e) => setShareForm({ ...shareForm, portRangeEnd: parseInt(e.target.value) })}
+                onChange={(e) =>
+                  setShareForm({
+                    ...shareForm,
+                    portRangeEnd: parseInt(e.target.value),
+                  })
+                }
               />
             </div>
             <Input
+              description="0 表示永久"
               label="有效期 (天)"
               type="number"
-              description="0 表示永久"
               value={shareForm.expiryDays.toString()}
-              onChange={(e) => setShareForm({ ...shareForm, expiryDays: parseInt(e.target.value) })}
+              onChange={(e) =>
+                setShareForm({
+                  ...shareForm,
+                  expiryDays: parseInt(e.target.value),
+                })
+              }
             />
             <Input
+              description="0 表示不限流量"
               label="流量上限 (GB)"
               type="number"
-              description="0 表示不限流量"
               value={shareForm.maxBandwidth.toString()}
-              onChange={(e) => setShareForm({ ...shareForm, maxBandwidth: parseInt(e.target.value, 10) || 0 })}
+              onChange={(e) =>
+                setShareForm({
+                  ...shareForm,
+                  maxBandwidth: parseInt(e.target.value, 10) || 0,
+                })
+              }
             />
             <Input
+              description="限制使用此Token的来源面板域名，多个域名用逗号分隔，留空不限制"
               label="允许的域名 (可选)"
               placeholder="example.com, panel.test.com"
-              description="限制使用此Token的来源面板域名，多个域名用逗号分隔，留空不限制"
               value={shareForm.allowedDomains}
-              onChange={(e) => setShareForm({ ...shareForm, allowedDomains: e.target.value })}
+              onChange={(e) =>
+                setShareForm({ ...shareForm, allowedDomains: e.target.value })
+              }
             />
             <Input
+              description="仅白名单IP可导入此分享，支持IPv4/IPv6/CIDR，多个用逗号分隔"
               label="允许的API IP (可选)"
               placeholder="203.0.113.10, 2001:db8::10, 198.51.100.0/24"
-              description="仅白名单IP可导入此分享，支持IPv4/IPv6/CIDR，多个用逗号分隔"
               value={shareForm.allowedIps}
-              onChange={(e) => setShareForm({ ...shareForm, allowedIps: e.target.value })}
+              onChange={(e) =>
+                setShareForm({ ...shareForm, allowedIps: e.target.value })
+              }
             />
           </ModalBody>
           <ModalFooter>
             <Button onPress={() => setCreateShareOpen(false)}>取消</Button>
-            <Button color="primary" onPress={handleCreateShare}>创建</Button>
+            <Button color="primary" onPress={handleCreateShare}>
+              创建
+            </Button>
+          </ModalFooter>
+        </ModalContent>
+      </Modal>
+
+      {/* Edit Share Modal */}
+      <Modal isOpen={editShareOpen} onClose={() => setEditShareOpen(false)}>
+        <ModalContent>
+          <ModalHeader>编辑分享</ModalHeader>
+          <ModalBody>
+            <Input
+              label="名称"
+              placeholder="备注名称"
+              value={editForm.name}
+              onChange={(e) =>
+                setEditForm({ ...editForm, name: e.target.value })
+              }
+            />
+            <div className="flex gap-4">
+              <Input
+                label="起始端口"
+                type="number"
+                value={editForm.portRangeStart.toString()}
+                onChange={(e) =>
+                  setEditForm({
+                    ...editForm,
+                    portRangeStart: parseInt(e.target.value) || 0,
+                  })
+                }
+              />
+              <Input
+                label="结束端口"
+                type="number"
+                value={editForm.portRangeEnd.toString()}
+                onChange={(e) =>
+                  setEditForm({
+                    ...editForm,
+                    portRangeEnd: parseInt(e.target.value) || 0,
+                  })
+                }
+              />
+            </div>
+            <Input
+              description="0 表示不限流量"
+              label="流量上限 (GB)"
+              type="number"
+              value={editForm.maxBandwidth.toString()}
+              onChange={(e) =>
+                setEditForm({
+                  ...editForm,
+                  maxBandwidth: parseInt(e.target.value, 10) || 0,
+                })
+              }
+            />
+            <Input
+              description="留空或清除表示永久有效"
+              label="过期时间"
+              type="datetime-local"
+              value={
+                editForm.expiryTime > 0
+                  ? new Date(editForm.expiryTime).toISOString().slice(0, 16)
+                  : ""
+              }
+              onChange={(e) =>
+                setEditForm({
+                  ...editForm,
+                  expiryTime: e.target.value
+                    ? new Date(e.target.value).getTime()
+                    : 0,
+                })
+              }
+            />
+            <Input
+              description="限制使用此Token的来源面板域名，多个域名用逗号分隔，留空不限制"
+              label="允许的域名 (可选)"
+              placeholder="example.com, panel.test.com"
+              value={editForm.allowedDomains}
+              onChange={(e) =>
+                setEditForm({ ...editForm, allowedDomains: e.target.value })
+              }
+            />
+            <Input
+              description="仅白名单IP可导入此分享，支持IPv4/IPv6/CIDR，多个用逗号分隔"
+              label="允许的API IP (可选)"
+              placeholder="203.0.113.10, 2001:db8::10, 198.51.100.0/24"
+              value={editForm.allowedIps}
+              onChange={(e) =>
+                setEditForm({ ...editForm, allowedIps: e.target.value })
+              }
+            />
+          </ModalBody>
+          <ModalFooter>
+            <Button onPress={() => setEditShareOpen(false)}>取消</Button>
+            <Button color="primary" onPress={handleEditShare}>
+              保存
+            </Button>
           </ModalFooter>
         </ModalContent>
       </Modal>
@@ -495,18 +804,24 @@ export default function PanelSharingPage() {
               label="远程面板地址"
               placeholder="http://panel.example.com:8088"
               value={importForm.remoteUrl}
-              onChange={(e) => setImportForm({ ...importForm, remoteUrl: e.target.value })}
+              onChange={(e) =>
+                setImportForm({ ...importForm, remoteUrl: e.target.value })
+              }
             />
             <Input
               label="Token"
               placeholder="Bearer Token"
               value={importForm.token}
-              onChange={(e) => setImportForm({ ...importForm, token: e.target.value })}
+              onChange={(e) =>
+                setImportForm({ ...importForm, token: e.target.value })
+              }
             />
           </ModalBody>
           <ModalFooter>
             <Button onPress={() => setImportNodeOpen(false)}>取消</Button>
-            <Button color="secondary" onPress={handleImportNode}>导入</Button>
+            <Button color="secondary" onPress={handleImportNode}>
+              导入
+            </Button>
           </ModalFooter>
         </ModalContent>
       </Modal>

vite-frontend/src/pages/tunnel.tsx

@@ -67,6 +67,7 @@ interface Tunnel {
   protocol?: string;
   flow: number; // 1: 单向, 2: 双向
   trafficRatio: number;
+  ipPreference?: string;
   status: number;
   createdTime: string;
 }
@@ -87,6 +88,7 @@ interface TunnelForm {
   flow: number;
   trafficRatio: number;
   inIp: string; // 入口IP
+  ipPreference: string;
   status: number;
 }
 
@@ -141,6 +143,7 @@ export default function TunnelPage() {
     flow: 1,
     trafficRatio: 1.0,
     inIp: "",
+    ipPreference: "",
     status: 1,
   });
 
@@ -253,8 +256,8 @@ export default function TunnelPage() {
       }
     }
 
-    if (form.trafficRatio < 0.0 || form.trafficRatio > 100.0) {
-      newErrors.trafficRatio = "流量倍率必须在0.0-100.0之间";
+    if (form.trafficRatio <= 0 || form.trafficRatio > 100.0) {
+      newErrors.trafficRatio = "流量倍率须大于0，支持小数（如 0.5）";
     }
 
     // 隧道转发时的验证
@@ -301,6 +304,7 @@ export default function TunnelPage() {
       flow: 1,
       trafficRatio: 1.0,
       inIp: "",
+      ipPreference: "",
       status: 1,
     });
     setErrors({});
@@ -313,21 +317,22 @@ export default function TunnelPage() {
 
     // 直接使用列表数据，getAllTunnels 已经包含完整的节点信息
     setForm({
-      id: tunnel.id,
-      name: tunnel.name,
-      type: tunnel.type,
-      inNodeId: tunnel.inNodeId || [],
-      outNodeId: tunnel.outNodeId || [],
-      chainNodes: tunnel.chainNodes || [],
-      flow: tunnel.flow,
-      trafficRatio: tunnel.trafficRatio,
-      inIp: tunnel.inIp
-        ? tunnel.inIp
-            .split(",")
-            .map((ip) => ip.trim())
-            .join("\n")
-        : "",
-      status: tunnel.status,
+    id: tunnel.id,
+    name: tunnel.name,
+    type: tunnel.type,
+    inNodeId: tunnel.inNodeId || [],
+    outNodeId: tunnel.outNodeId || [],
+    chainNodes: tunnel.chainNodes || [],
+    flow: tunnel.flow,
+    trafficRatio: tunnel.trafficRatio,
+    inIp: tunnel.inIp
+      ? tunnel.inIp
+          .split(",")
+          .map((ip: string) => ip.trim())
+          .join("\n")
+      : "",
+    ipPreference: tunnel.ipPreference || "",
+    status: tunnel.status,
     });
     setErrors({});
     setModalOpen(true);
@@ -1045,7 +1050,7 @@ export default function TunnelPage() {
                             </div>
 
                             {/* 流量配置 */}
-                            <div className="grid grid-cols-2 gap-2">
+                            <div className={`grid gap-2 ${tunnel.type === 2 && tunnel.ipPreference ? "grid-cols-3" : "grid-cols-2"}`}>
                               <div className="text-center p-1.5 bg-default-50 dark:bg-default-100/30 rounded">
                                 <div className="text-xs text-default-500">
                                   流量计算
@@ -1062,6 +1067,16 @@ export default function TunnelPage() {
                                   {tunnel.trafficRatio}x
                                 </div>
                               </div>
+                              {tunnel.type === 2 && tunnel.ipPreference && (
+                                <div className="text-center p-1.5 bg-default-50 dark:bg-default-100/30 rounded">
+                                  <div className="text-xs text-default-500">
+                                    连接偏好
+                                  </div>
+                                  <div className="text-sm font-semibold text-foreground mt-0.5">
+                                    {tunnel.ipPreference === "v4" ? "IPv4" : "IPv6"}
+                                  </div>
+                                </div>
+                              )}
                             </div>
                           </div>
 
@@ -1265,8 +1280,11 @@ export default function TunnelPage() {
                       errorMessage={errors.trafficRatio}
                       isInvalid={!!errors.trafficRatio}
                       label="流量倍率"
-                      placeholder="请输入流量倍率"
+                      placeholder="例如：0.5 或 1 或 2"
                       type="number"
+                      step="any"
+                      min={0.01}
+                      max={100}
                       value={form.trafficRatio.toString()}
                       variant="bordered"
                       onChange={(e) =>
@@ -1293,6 +1311,27 @@ export default function TunnelPage() {
                     }
                   />
 
+                  {form.type === 2 && (
+                    <Select
+                      description="当节点同时拥有IPv4和IPv6地址时，选择隧道连接使用的地址类型"
+                      label="隧道连接地址偏好"
+                      selectedKeys={[form.ipPreference || ""]}
+                      variant="bordered"
+                      onSelectionChange={(keys) => {
+                        const selectedKey = Array.from(keys)[0] as string;
+
+                        setForm((prev) => ({
+                          ...prev,
+                          ipPreference: selectedKey || "",
+                        }));
+                      }}
+                    >
+                      <SelectItem key="">自动选择</SelectItem>
+                      <SelectItem key="v4">优先IPv4</SelectItem>
+                      <SelectItem key="v6">优先IPv6</SelectItem>
+                    </Select>
+                  )}
+
                   <Divider />
                   <h3 className="text-lg font-semibold">入口配置</h3>
 

vite-frontend/src/styles/globals.css

@@ -46,6 +46,28 @@ html, body {
   --safe-area-bottom: env(safe-area-inset-bottom, 0px);
 }
 
+[data-slot="input-wrapper"] {
+  box-shadow: none;
+}
+
+[data-slot="input-wrapper"]:focus-within:not([data-invalid="true"]),
+[data-slot="input-wrapper"][data-focus="true"]:not([data-invalid="true"]),
+[data-slot="input-wrapper"][data-focused="true"]:not([data-invalid="true"]),
+button[data-slot="trigger"][data-focus="true"]:not([data-invalid="true"]),
+button[data-slot="trigger"][data-open="true"]:not([data-invalid="true"]) {
+  border-color: var(--heroui-default-200, #e5e7eb) !important;
+  outline: none !important;
+  outline-offset: 0 !important;
+  box-shadow: none !important;
+}
+
+[data-slot="input-wrapper"] input:focus,
+[data-slot="input-wrapper"] textarea:focus {
+  outline: none !important;
+  box-shadow: none !important;
+  border-color: transparent !important;
+}
+
 .safe-top {
   padding-top: var(--safe-area-top);
 }
@@ -85,4 +107,4 @@ html, body {
   }
 }
 
-@config "../../tailwind.config.js"
+@config "../../tailwind.config.js"