docs: add proxy protocol analysis and panel self-upgrade plans

## Summary

- `node:20.19.0` + `corepack` + `pnpm@11` →
`ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING`
- `pnpm@11` blocks `@tailwindcss/oxide` build scripts by default
- Fix: `node:22-alpine` + `corepack prepare pnpm@10 --activate &&
corepack enable pnpm`

## Verification (all local)

| Check | Result |
|-------|--------|
| `docker build ./vite-frontend` | ✅ |
| `go test ./...` | ✅ 498 passed |
| `pnpm run build` | ✅ |
| `pnpm run lint` | ✅ |

.github/ISSUES/forward-show-tunnel-ratio.md

@@ -0,0 +1,62 @@
+# 功能请求：在规则页面显示隧道倍率
+
+## 问题描述
+
+当前规则（Forward）页面在列表中显示隧道名称，但**不显示隧道的流量倍率（trafficRatio）**。管理员在管理规则时无法快速查看该规则所使用的隧道倍率信息，需要跳转到隧道页面才能查看。
+
+## 期望行为
+
+在规则列表页面中，在隧道名称旁边或单独列显示该隧道的流量倍率（例如：`1x`, `0.5x`, `2x`）。
+
+## 建议实现位置
+
+### 前端修改
+
+1. **`vite-frontend/src/pages/forward.tsx`**
+   - 在 `Forward` interface 中添加 `tunnelTrafficRatio?: number` 字段
+   - 在表格列中添加倍率显示（可以在隧道名称 Chip 旁边或单独一列）
+   - 从 `userTunnel` 或 `getTunnelList` API 获取隧道倍率信息
+
+2. **显示格式建议**
+   ```tsx
+   <Chip className="...">
+     {forward.tunnelName} ({forward.tunnelTrafficRatio}x)
+   </Chip>
+   ```
+   或者单独一列：
+   ```tsx
+   <TableCell>
+     {forward.tunnelTrafficRatio}x
+   </TableCell>
+   ```
+
+### 后端修改
+
+1. **`go-backend/internal/http/handler/handler.go`**
+   - 在 `forwardList` 接口返回中添加隧道的 `trafficRatio` 字段
+   - 需要在查询 Forward 时 JOIN Tunnel 表获取倍率信息
+
+2. **或者在前端加载规则后，批量获取隧道信息**
+   - 调用 `getTunnelList` 获取所有隧道信息
+   - 根据 `tunnelId` 匹配倍率
+
+## 相关文件
+
+- 前端：`vite-frontend/src/pages/forward.tsx`
+- 前端类型：`vite-frontend/src/api/types.ts`
+- 后端：`go-backend/internal/http/handler/handler.go`
+- 隧道类型定义：`vite-frontend/src/api/types.ts` (TunnelApiItem)
+
+## 优先级
+
+中等 - 不影响核心功能，但能提升管理效率
+
+## 截图参考
+
+隧道页面已显示倍率：
+- 位置：隧道卡片统计信息区域
+- 显示格式：`流量倍率 {trafficRatio}x`
+
+---
+
+**Labels**: `enhancement`, `frontend`, `backend`, `ui/ux`

.github/workflows/ci-build.yml

@@ -0,0 +1,110 @@
+name: CI Build Check
+
+on:
+  push:
+    branches: ['**']
+  pull_request:
+    branches: ['**']
+
+jobs:
+  frontend:
+    name: Build Frontend
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: vite-frontend
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20.19.0'
+
+      - name: Install pnpm
+        run: npm install -g pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build
+        run: pnpm run build
+
+  backend:
+    name: Build Go Backend
+    runs-on: ubuntu-latest
+    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: 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
+    defaults:
+      run:
+        working-directory: go-gost
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.23'
+          cache-dependency-path: go-gost/go.sum
+
+      - name: Download dependencies
+        run: go mod download
+
+      - name: Build
+        run: go build -v .

.github/workflows/deploy-docs.yml

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

.github/workflows/docker-build.yml

@@ -6,9 +6,6 @@ env:
 
 on:
   push:
-    branches:
-      - main
-      - beta
     tags:
       - '[0-9]*'  # 匹配 2.0.8, 2.0.8-beta 等格式
 
@@ -103,11 +100,11 @@ jobs:
 
       - name: Build GOST binary (AMD64)
         working-directory: ./go-gost
-        run: CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags="-s -w" -o gost-amd64
+        run: CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags="-s -w -X main.version=${{ needs.check-version.outputs.version }}" -o gost-amd64
 
       - name: Build GOST binary (ARM64)
         working-directory: ./go-gost
-        run: CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -ldflags="-s -w" -o gost-arm64
+        run: CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -ldflags="-s -w -X main.version=${{ needs.check-version.outputs.version }}" -o gost-arm64
 
       - name: Compress with UPX
         working-directory: ./go-gost
@@ -115,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:
@@ -127,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
@@ -168,8 +183,8 @@ jobs:
             -t ${{ env.REGISTRY }}/${OWNER}/vite-frontend:${VERSION} \
             ./vite-frontend
 
-  build-java:
-    name: Build & Push Spring Boot Backend
+  build-go-backend:
+    name: Build & Push Go Backend
     needs: check-version
     if: needs.check-version.outputs.should_build == 'true'
     runs-on: ubuntu-latest
@@ -179,22 +194,23 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - name: Set up JDK and Maven
-        uses: actions/setup-java@v4
+      - name: Set up Go
+        uses: actions/setup-go@v5
         with:
-          java-version: 21
-          distribution: 'temurin'
+          go-version: '1.23'
 
-      - name: Cache Maven dependencies
+      - name: Cache Go dependencies
         uses: actions/cache@v4
         with:
-          path: ~/.m2
-          key: ${{ runner.os }}-m2-${{ hashFiles('**/pom.xml') }}
-          restore-keys: ${{ runner.os }}-m2
+          path: |
+            ~/.cache/go-build
+            ~/go/pkg/mod
+          key: ${{ runner.os }}-go-backend-${{ hashFiles('go-backend/go.sum') }}
+          restore-keys: ${{ runner.os }}-go-backend-
 
-      - name: Build Java JAR
-        working-directory: ./springboot-backend
-        run: mvn clean package -DskipTests
+      - name: Download dependencies
+        working-directory: ./go-backend
+        run: go mod download
 
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
@@ -206,7 +222,7 @@ jobs:
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Build and push Java Docker images
+      - name: Build and push Go backend Docker images
         run: |
           VERSION="${{ needs.check-version.outputs.version }}"
           OWNER="${{ needs.check-version.outputs.image_owner }}"
@@ -214,13 +230,13 @@ jobs:
           docker buildx build \
             --platform linux/amd64,linux/arm64 \
             --push \
-            -t ${{ env.REGISTRY }}/${OWNER}/springboot-backend:latest \
-            -t ${{ env.REGISTRY }}/${OWNER}/springboot-backend:${VERSION} \
-            ./springboot-backend
+            -t ${{ env.REGISTRY }}/${OWNER}/flux-panel-backend:latest \
+            -t ${{ env.REGISTRY }}/${OWNER}/flux-panel-backend:${VERSION} \
+            ./go-backend
 
   create-release:
     name: Create Release (Tag Only)
-    needs: [check-version, build-gost, build-vite, build-java]
+    needs: [check-version, build-gost, build-vite, build-go-backend]
     if: needs.check-version.outputs.is_tag == 'true'
     runs-on: ubuntu-latest
     permissions:
@@ -240,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 }}"
@@ -255,10 +284,10 @@ jobs:
           cp docker-compose-v6.yml ./artifacts/docker-compose-v6.yml
 
           # 替换镜像地址为 GHCR
-          sed -i "s|bqlpfy/springboot-backend:[^[:space:]]*|${{ env.REGISTRY }}/${OWNER}/springboot-backend:${VERSION}|g" ./artifacts/docker-compose-v4.yml
-          sed -i "s|bqlpfy/vite-frontend:[^[:space:]]*|${{ env.REGISTRY }}/${OWNER}/vite-frontend:${VERSION}|g" ./artifacts/docker-compose-v4.yml
-          sed -i "s|bqlpfy/springboot-backend:[^[:space:]]*|${{ env.REGISTRY }}/${OWNER}/springboot-backend:${VERSION}|g" ./artifacts/docker-compose-v6.yml
-          sed -i "s|bqlpfy/vite-frontend:[^[:space:]]*|${{ env.REGISTRY }}/${OWNER}/vite-frontend:${VERSION}|g" ./artifacts/docker-compose-v6.yml
+          sed -i "s|image: .*flux-panel-backend:[^[:space:]]*|image: ${{ env.REGISTRY }}/${OWNER}/flux-panel-backend:${VERSION}|g" ./artifacts/docker-compose-v4.yml
+          sed -i "s|image: .*vite-frontend:[^[:space:]]*|image: ${{ env.REGISTRY }}/${OWNER}/vite-frontend:${VERSION}|g" ./artifacts/docker-compose-v4.yml
+          sed -i "s|image: .*flux-panel-backend:[^[:space:]]*|image: ${{ env.REGISTRY }}/${OWNER}/flux-panel-backend:${VERSION}|g" ./artifacts/docker-compose-v6.yml
+          sed -i "s|image: .*vite-frontend:[^[:space:]]*|image: ${{ env.REGISTRY }}/${OWNER}/vite-frontend:${VERSION}|g" ./artifacts/docker-compose-v6.yml
 
           # 复制并修改安装脚本
           cp install.sh ./artifacts/install.sh
@@ -270,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 }}
@@ -297,7 +330,7 @@ jobs:
 
           \`\`\`bash
           # Backend
-          docker pull ${{ env.REGISTRY }}/${OWNER}/springboot-backend:${VERSION}
+          docker pull ${{ env.REGISTRY }}/${OWNER}/flux-panel-backend:${VERSION}
 
           # Frontend
           docker pull ${{ env.REGISTRY }}/${OWNER}/vite-frontend:${VERSION}
@@ -305,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 }}
 
@@ -321,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
@@ -353,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
@@ -369,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 二进制文件更新完成"
+

.github/workflows/publish-skill.yml

@@ -0,0 +1,48 @@
+name: Publish Skill to npm
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Get version from tag
+        id: version
+        run: |
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            VERSION=$(node -p "require('./skills/flvx-api/package.json').version")
+          else
+            VERSION="${GITHUB_REF#refs/tags/v}"
+          fi
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          echo "Publishing skill version: $VERSION"
+
+      - name: Publish to npm
+        working-directory: skills/flvx-api
+        run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Create GitHub Release
+        if: github.event_name == 'push'
+        uses: softprops/action-gh-release@v1
+        with:
+          name: Skill v${{ steps.version.outputs.version }}
+          generate_release_notes: true
+          files: skills/flvx-api/package.json

.gitignore

@@ -62,8 +62,12 @@ go-gost/ss/
 .classpath
 .project
 .settings/
+
+# OpenCode session metadata
+.entire/
 bin/
 tmp/
+.worktrees/
 *.swp
 *.bak
 
@@ -176,6 +180,8 @@ build/
 *.so
 *.dylib
 your_app.exe
+go-backend/paneld
+go-gost/gost
 
 # Go 测试二进制文件
 *.test
@@ -257,4 +263,15 @@ gitee/
 doraemon.jks
 device.id
 commit.sh
-sql/
+.opencode/
+analysis/
+sql/
+!go-backend/internal/store/sqlite/sql/
+!go-backend/internal/store/sqlite/sql/schema.sql
+!go-backend/internal/store/sqlite/sql/data.sql
+!go-backend/internal/store/postgres/sql/
+!go-backend/internal/store/postgres/sql/schema.sql
+!go-backend/internal/store/postgres/sql/data.sql
+go-backend/gost.db-shm
+.gitignore
+go-backend/gost.db-wal

.sisyphus/plans/001-setup-dev-environment.md

@@ -1,71 +0,0 @@
-# Plan: 搭建开发环境
-
-## 目标
-为 Flux Panel 项目安装所有缺失的开发依赖，使 3 个子项目都能本地开发和构建。
-
-## 当前状态
-
-### ✅ 已安装
-| 工具 | 版本 | 用途 |
-|------|------|------|
-| Node.js | v20.19.2 | vite-frontend |
-| npm | 9.2.0 | vite-frontend |
-| Go | 1.24.4 | go-gost |
-| Docker | 29.1.4 | 容器化部署 |
-
-### ❌ 缺失
-| 工具 | 需求版本 | 用途 |
-|------|----------|------|
-| Java | 21 | springboot-backend |
-| Maven | 3.x | 构建后端 |
-| Docker Compose | v2 | 容器编排 |
-
----
-
-## 执行任务
-
-### Task 1: 安装 Java 21
-```bash
-apt-get update && apt-get install -y openjdk-21-jdk
-```
-**验证**: `java -version` 应显示 openjdk 21
-
-### Task 2: 安装 Maven
-```bash
-apt-get install -y maven
-```
-**验证**: `mvn -v` 应显示 Maven 3.x
-
-### Task 3: 安装 Docker Compose Plugin
-```bash
-apt-get install -y docker-compose-plugin
-```
-**验证**: `docker compose version` 应显示版本号
-
-### Task 4: 安装前端依赖
-```bash
-cd /root/flux-panel/vite-frontend && npm install
-```
-**验证**: `node_modules/` 目录存在
-
-### Task 5: 验证后端可构建
-```bash
-cd /root/flux-panel/springboot-backend && mvn clean compile -q
-```
-**验证**: 编译成功无错误
-
-### Task 6: 验证 Go 模块
-```bash
-cd /root/flux-panel/go-gost && go mod download
-```
-**验证**: 依赖下载成功
-
----
-
-## 完成标准
-- [ ] `java -version` → openjdk 21
-- [ ] `mvn -v` → Maven 3.x
-- [ ] `docker compose version` → v2.x
-- [ ] 前端: `npm run dev` 可启动
-- [ ] 后端: `mvn compile` 成功
-- [ ] Go: `go build .` 成功

.sisyphus/ralph-loop.local.md

@@ -1,9 +0,0 @@
----
-active: true
-iteration: 1
-max_iterations: 100
-completion_promise: "DONE"
-started_at: "2026-01-24T05:20:50.887Z"
-session_id: "ses_41192b7d7ffewFHxf1dDS7ESHO"
----
-Complete the task as instructed

AGENTS.md

@@ -1,43 +1,62 @@
-# PROJECT KNOWLEDGE BASE
+# AGENTS
 
-**Generated:** Sat Jan 24 2026
-**Context:** Monorepo for Flux Panel (Traffic Forwarding)
+FLVX — traffic forwarding panel: Go admin API + Vite/React UI + Go agent.
 
-## OVERVIEW
-Flux Panel is a traffic forwarding management system based on [go-gost](https://github.com/go-gost/gost). It manages tunnels, port forwarding, and user quotas.
-**Stack:** Monorepo (Java/Spring Boot Backend + React/Vite Frontend + Go/GOST Service).
+## Structure
 
-## STRUCTURE
-```
-/root/flux-panel/
-├── springboot-backend/  # Java 21 + Spring Boot 2.7 Admin API
-├── vite-frontend/       # React 18 + Vite + HeroUI/NextUI
-├── go-gost/             # Go 1.23 + GOST Extensions (Core logic)
-├── docker-compose*.yml  # Deployment configs (v4/v6)
-└── *.sh                 # Install scripts (panel_install.sh, install.sh)
-```
+| Dir | Role | Entry |
+|-----|------|-------|
+| `go-backend/` | Admin API (GORM + SQLite/PG, net/http) | `cmd/paneld/main.go` |
+| `go-gost/` | Forwarding agent (forked GOST) | `main.go` |
+| `go-gost/x/` | Protocol handlers/dialers/listeners (own module) | — |
+| `vite-frontend/` | React dashboard (shadcn bridge + Tailwind v4) | `src/App.tsx` |
 
-## WHERE TO LOOK
-| Task | Location | Notes |
-|------|----------|-------|
-| **Admin API** | `springboot-backend/` | Users, quotas, billing logic |
-| **UI/Dashboard** | `vite-frontend/` | Management console |
-| **Core Forwarding** | `go-gost/` | GOST implementation & extensions |
-| **Deploy** | `docker-compose-v4.yml` | Container orchestration |
+`go-gost/go.mod` uses `replace github.com/go-gost/x => ./x`.
 
-## CONVENTIONS
-- **Monorepo**: 3 distinct languages/stacks. Treat each subdir as a separate project.
-- **Docker**: Primary deployment method.
-- **Scripts**: `panel_install.sh` for panel, `install.sh` for nodes.
+## Commands
 
-## COMMANDS
 ```bash
-# Quick Deploy (Panel)
-./panel_install.sh
+# Backend
+(cd go-backend && go run ./cmd/paneld)        # SERVER_ADDR defaults to :6365
+(cd go-backend && make build)
+(cd go-backend && go test ./...)
 
-# Quick Deploy (Node)
-./install.sh
+# Frontend
+(cd vite-frontend && pnpm install)
+(cd vite-frontend && pnpm run dev)             # host 0.0.0.0:3000
+(cd vite-frontend && pnpm run build)           # tsc && vite build
+(cd vite-frontend && pnpm run lint)            # eslint --fix (no typecheck command)
 
-# Docker
-docker-compose -f docker-compose-v4.yml up -d
+# Agent
+(cd go-gost && go run .)
 ```
+
+## Conventions
+
+- **Auth**: raw JWT in `Authorization` header — **no `Bearer` prefix** (both frontend and backend).
+- **API envelope**: all responses `{code, msg, data, ts}` (code 0 = success).
+- **Frontend UI**: import from `src/shadcn-bridge/heroui/*`, never `@heroui/*` or `@nextui-org/*`.
+- **Tailwind theme**: `globals.css` must import `tailwind-theme.pcss` or semantic classes break.
+- **Backend DB**: handlers use Repository methods, never `repo.DB()` directly.
+- **GORM models**: always define `TableName()` (GORM pluralizes by default).
+- **GORM tags**: no `type:jsonb` or `type:serial` (SQLite incompatible).
+- **Go versions**: `go.mod` says 1.25.0 for all three modules; CI builds with 1.23.
+
+## Anti-patterns
+
+- Don't edit `install.sh` or `panel_install.sh` locally (CI overwrites on release).
+- Don't edit `go-gost/x/internal/util/grpc/proto/*.pb.go` (generated).
+- Don't add frontend tests (no Vitest/Jest configured).
+- Don't reintroduce `@heroui/*` or `@nextui-org/*` packages.
+
+## Testing
+
+- Backend: `(cd go-backend && go test ./...)` — includes contract tests in `tests/contract/`.
+- Frontend: no test infrastructure.
+- CI runs one PostgreSQL contract test: env var `FLVX_POSTGRES_TEST_DSN`.
+
+## Build quirks
+
+- `vite-frontend` uses `rolldown-vite` (Rust bundler), not standard Vite.
+- `vite.config.ts`: `minify: false`, `treeshake: false` (debugging mode).
+- CI builds `go-gost` with `CGO_ENABLED=0` then compresses with UPX `--best --lzma`.

LICENSE

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

LICENSE-APACHE

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

NOTICE

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

README.md

@@ -1,7 +1,8 @@
-# flux-panel转发面板 哆啦A梦转发面板
+# FLVX
+
+> **联系我们**: [Telegram群组](https://t.me/flvxchannel)
+
 
-本项目基于 [go-gost/gost](https://github.com/go-gost/gost) 和 [go-gost/x](https://github.com/go-gost/x) 两个开源库，实现了转发面板。
----
 ## 特性
 
 - 支持按 **隧道账号级别** 管理流量转发数量，可用于用户/隧道配额控制
@@ -10,32 +11,110 @@
 - 可针对 **指定用户的指定隧道进行限速** 设置
 - 支持配置 **单向或双向流量计费方式**，灵活适配不同计费模型
 - 提供灵活的转发策略配置，适用于多种网络场景
+- 面板分享，支持将节点分享给其他人，面板对接面板
+- 支持分组权限管理，隧道分组、用户分组
+- 支持批量功能，可以批量下发配置，启停等
+- 支持隧道修改配置、转发修改隧道
 
 
 ## 部署流程
 ---
 ### 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.9-beta6 为例）：
 ```bash
-curl -L https://raw.githubusercontent.com/Sagit-chu/flux-panel/beta/panel_install.sh -o panel_install.sh && chmod +x panel_install.sh && ./panel_install.sh
+curl -L https://github.com/Sagit-chu/flux-panel/releases/download/2.1.9-beta6/panel_install.sh -o panel_install.sh && chmod +x panel_install.sh && ./panel_install.sh
 ```
-节点端(开发版)：
+节点端（以 2.1.9-beta6 为例）：
 ```bash
-curl -L https://raw.githubusercontent.com/Sagit-chu/flux-panel/beta/install.sh -o install.sh && chmod +x install.sh && ./install.sh
-
+curl -L https://github.com/Sagit-chu/flux-panel/releases/download/2.1.9-beta6/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
@@ -43,6 +122,38 @@ curl -L https://raw.githubusercontent.com/Sagit-chu/flux-panel/beta/install.sh -
 
 > ⚠️ 首次登录后请立即修改默认密码！
 
+---
+## Original Project
+- **Name**: flux-panel
+- **Source**: https://github.com/bqlpfy/flux-panel
+- **License**: Apache License 2.0
+
+## Modifications
+This fork (FLVX) is no longer a light patch on top of the upstream project. It has been deeply reworked, with both backend and frontend rebuilt around a Go-based architecture.
+
+### 1. Backend (Rewritten)
+- **Removed**: The original `springboot-backend/` (Java/Spring Boot) implementation.
+- **Added**: A fully rewritten `go-backend/` service (Go), including updated data and API handling for panel management.
+
+### 2. Frontend (Reworked)
+- **Reworked**: `vite-frontend/` has been substantially rebuilt to match the new backend contract and current UI layer architecture.
+- **Updated**: Dashboard pages/components and interaction flows for the current React/Vite stack.
+
+### 3. Forwarding Stack (Modified)
+- **Modified**: `go-gost/` forwarding agent wrapper.
+- **Modified**: `go-gost/x/` local fork of `github.com/go-gost/x`.
+
+### 4. Mobile Clients (Removed)
+- **Removed**: `android-app/` source code.
+- **Removed**: `ios-app/` source code.
+
+### 5. Deployment & Project Infrastructure
+- **Updated**: Docker deployment templates and installer output flow (IPv4/IPv6 compose variants).
+- **Updated**: Release installation scripts (`install.sh`, `panel_install.sh`) and supporting automation.
+- **Added/Updated**: Project-level engineering documentation (for example `AGENTS.md`).
+
+---
+
 
 ## 免责声明
 
@@ -66,4 +177,13 @@ curl -L https://raw.githubusercontent.com/Sagit-chu/flux-panel/beta/install.sh -
 作者对因使用本项目所造成的任何直接或间接损失概不负责，亦不提供任何形式的担保、承诺或技术支持。  
 
 
-请务必在合法、合规、安全的前提下使用本项目。
+请务必在合法、合规、安全的前提下使用本项目。
+
+---
+## ⭐ 喝杯咖啡！（USDT）
+
+| 网络       | 地址                                                                 |
+|------------|----------------------------------------------------------------------|
+| BNB(BEP20) | `0x271327ce49140e670eA0F772d9886BF90E9022Ee`                          |
+| TRC20      | `TARxZWggaxFqYgxGVBxPkyykgYKNmGndmE`                                  |
+| polygon    |  `0x271327ce49140e670eA0F772d9886BF90E9022Ee`    |

android-app/.gitignore

@@ -1,15 +0,0 @@
-*.iml
-.gradle
-/local.properties
-/.idea/caches
-/.idea/libraries
-/.idea/modules.xml
-/.idea/workspace.xml
-/.idea/navEditor.xml
-/.idea/assetWizardSettings.xml
-.DS_Store
-/build
-/captures
-.externalNativeBuild
-.cxx
-local.properties

android-app/app/.gitignore

@@ -1 +0,0 @@
-/build

android-app/app/build.gradle

@@ -1,45 +0,0 @@
-plugins {
-    id 'com.android.application'
-    id 'org.jetbrains.kotlin.android'
-}
-
-android {
-    namespace 'com.flux'
-    compileSdk 34
-
-    defaultConfig {
-        applicationId "com.flux"
-        minSdk 24
-        targetSdk 34
-        versionCode 1
-        versionName "1.0.1"
-
-        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
-    }
-
-    buildTypes {
-        release {
-            minifyEnabled false
-            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
-        }
-    }
-    compileOptions {
-        sourceCompatibility JavaVersion.VERSION_1_8
-        targetCompatibility JavaVersion.VERSION_1_8
-    }
-    kotlinOptions {
-        jvmTarget = '1.8'
-    }
-}
-
-dependencies {
-
-    implementation 'androidx.core:core-ktx:1.9.0'
-    implementation 'androidx.appcompat:appcompat:1.7.1'
-    implementation 'com.google.android.material:material:1.12.0'
-    implementation 'androidx.constraintlayout:constraintlayout:2.2.1'
-    implementation 'androidx.webkit:webkit:1.8.0'
-    testImplementation 'junit:junit:4.13.2'
-    androidTestImplementation 'androidx.test.ext:junit:1.3.0'
-    androidTestImplementation 'androidx.test.espresso:espresso-core:3.7.0'
-}

android-app/app/proguard-rules.pro

@@ -1,21 +0,0 @@
-# Add project specific ProGuard rules here.
-# You can control the set of applied configuration files using the
-# proguardFiles setting in build.gradle.
-#
-# For more details, see
-#   http://developer.android.com/guide/developing/tools/proguard.html
-
-# If your project uses WebView with JS, uncomment the following
-# and specify the fully qualified class name to the JavaScript interface
-# class:
-#-keepclassmembers class fqcn.of.javascript.interface.for.webview {
-#   public *;
-#}
-
-# Uncomment this to preserve the line number information for
-# debugging stack traces.
-#-keepattributes SourceFile,LineNumberTable
-
-# If you keep the line number information, uncomment this to
-# hide the original source file name.
-#-renamesourcefileattribute SourceFile

android-app/app/release/output-metadata.json

@@ -1,20 +0,0 @@
-{
-  "version": 3,
-  "artifactType": {
-    "type": "APK",
-    "kind": "Directory"
-  },
-  "applicationId": "com.flux",
-  "variantName": "release",
-  "elements": [
-    {
-      "type": "SINGLE",
-      "filters": [],
-      "attributes": [],
-      "versionCode": 1,
-      "versionName": "1.0.1",
-      "outputFile": "app-release.apk"
-    }
-  ],
-  "elementType": "File"
-}

android-app/app/src/androidTest/java/com/flux/ExampleInstrumentedTest.kt

@@ -1,24 +0,0 @@
-package com.flux
-
-import androidx.test.platform.app.InstrumentationRegistry
-import androidx.test.ext.junit.runners.AndroidJUnit4
-
-import org.junit.Test
-import org.junit.runner.RunWith
-
-import org.junit.Assert.*
-
-/**
- * Instrumented test, which will execute on an Android device.
- *
- * See [testing documentation](http://d.android.com/tools/testing).
- */
-@RunWith(AndroidJUnit4::class)
-class ExampleInstrumentedTest {
-    @Test
-    fun useAppContext() {
-        // Context of the app under test.
-        val appContext = InstrumentationRegistry.getInstrumentation().targetContext
-        assertEquals("com.flux", appContext.packageName)
-    }
-}

android-app/app/src/main/AndroidManifest.xml

@@ -1,32 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<manifest xmlns:android="http://schemas.android.com/apk/res/android"
-    xmlns:tools="http://schemas.android.com/tools"
-    package="com.flux" >
-
-    <uses-permission android:name="android.permission.INTERNET" />
-    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
-
-    <application
-        android:allowBackup="true"
-        android:dataExtractionRules="@xml/data_extraction_rules"
-        android:fullBackupContent="@xml/backup_rules"
-        android:icon="@mipmap/ic_launcher"
-        android:label="@string/app_name"
-        android:roundIcon="@mipmap/ic_launcher_round"
-        android:supportsRtl="true"
-        android:theme="@style/Theme.Flux"
-        android:usesCleartextTraffic="true"
-        tools:targetApi="31" >
-        <activity
-            android:name="com.flux.MainActivity"
-            android:exported="true"
-            android:configChanges="uiMode|orientation|screenSize" >
-            <intent-filter>
-                <action android:name="android.intent.action.MAIN" />
-
-                <category android:name="android.intent.category.LAUNCHER" />
-            </intent-filter>
-        </activity>
-    </application>
-
-</manifest>

android-app/app/src/main/java/com/flux/MainActivity.kt

@@ -1,214 +0,0 @@
-package com.flux
-
-import androidx.core.content.edit
-import android.graphics.Color
-import android.os.Build
-import android.os.Bundle
-import android.view.View
-import android.view.WindowInsetsController
-import androidx.appcompat.app.AppCompatActivity
-import android.webkit.*
-import android.content.res.Configuration
-import org.json.JSONArray
-import org.json.JSONObject
-
-
-class MainActivity : AppCompatActivity() {
-
-    private lateinit var webView: WebView
-
-    override fun onCreate(savedInstanceState: Bundle?) {
-        super.onCreate(savedInstanceState)
-        setContentView(R.layout.activity_main)
-
-        webView = findViewById(R.id.webView)
-        WebView.setWebContentsDebuggingEnabled(true)
-        setupWebView()
-        loadUrl()
-
-        setupSystemBars()
-        setupRootBackground()
-    }
-
-    private fun setupWebView() {
-        val settings = webView.settings
-        settings.javaScriptEnabled = true
-        settings.domStorageEnabled = true
-        settings.databaseEnabled = true
-        settings.loadWithOverviewMode = true
-        settings.useWideViewPort = true
-        settings.setSupportZoom(true)
-        settings.builtInZoomControls = true
-        settings.displayZoomControls = false
-
-        // 隐藏滚动条但不影响滚动
-        webView.isVerticalScrollBarEnabled = false
-        webView.isHorizontalScrollBarEnabled = false
-        webView.scrollBarStyle = View.SCROLLBARS_INSIDE_OVERLAY
-        webView.overScrollMode = View.OVER_SCROLL_NEVER
-
-
-        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP) {
-            settings.mixedContentMode = WebSettings.MIXED_CONTENT_ALWAYS_ALLOW
-        }
-
-        val isDarkTheme = resources.configuration.uiMode and
-                Configuration.UI_MODE_NIGHT_MASK ==
-                Configuration.UI_MODE_NIGHT_YES
-
-        webView.setBackgroundColor(if (isDarkTheme) Color.BLACK else Color.WHITE)
-
-
-        // 添加JavaScript接口
-        webView.addJavascriptInterface(object {
-
-            @android.webkit.JavascriptInterface
-            fun getPanelAddresses(callback: String) {
-                val sharedPrefs = getSharedPreferences("panel_config", MODE_PRIVATE)
-                val addresses = sharedPrefs.getString("panel_addresses", "[]")
-                webView.post {
-                    webView.evaluateJavascript("window.$callback($addresses);", null)
-                }
-            }
-
-            @android.webkit.JavascriptInterface
-            fun savePanelAddress(name: String, address: String) {
-                val json = JSONObject()
-                json.put("name", name)
-                json.put("address", address)
-                json.put("inx", false)
-                val sharedPrefs = getSharedPreferences("panel_config", MODE_PRIVATE)
-                val addresses = sharedPrefs.getString("panel_addresses", "[]")
-                val jsonArray = JSONArray(addresses)
-                jsonArray.put(json)
-                sharedPrefs.edit {
-                    putString("panel_addresses", jsonArray.toString())
-                }
-                webView.post {
-                    webView.evaluateJavascript("window.setPanelAddresses(${jsonArray.toString()});", null)
-                }
-            }
-
-            @android.webkit.JavascriptInterface
-            fun setCurrentPanelAddress(name: String) {
-
-                val sharedPrefs = getSharedPreferences("panel_config", MODE_PRIVATE)
-                val addresses = sharedPrefs.getString("panel_addresses", "[]")
-                val jsonArray = JSONArray(addresses)
-                for (i in 0 until jsonArray.length()) {
-                    val obj = jsonArray.getJSONObject(i)
-                    if (name == obj.getString("name")) {
-                        obj.put("inx", true)
-                    }else{
-                        obj.put("inx", false)
-                    }
-                }
-                sharedPrefs.edit {
-                    putString("panel_addresses", jsonArray.toString())
-                }
-                webView.post {
-                    webView.evaluateJavascript("window.setPanelAddresses(${jsonArray.toString()});", null)
-                }
-            }
-
-            @android.webkit.JavascriptInterface
-            fun deletePanelAddress(name: String) {
-                val jsonArray = JSONArray()
-                val sharedPrefs = getSharedPreferences("panel_config", MODE_PRIVATE)
-                val addresses = sharedPrefs.getString("panel_addresses", "[]")
-                val jsonArraya = JSONArray(addresses)
-                for (i in 0 until jsonArraya.length()) {
-                    val obj = jsonArraya.getJSONObject(i)
-                    if (name != obj.getString("name")) {
-                        jsonArray.put(obj)
-                    }
-                }
-                sharedPrefs.edit {
-                    putString("panel_addresses", jsonArray.toString())
-                }
-                webView.post {
-                    webView.evaluateJavascript("window.setPanelAddresses(${jsonArray.toString()});", null)
-                }
-            }
-        }, "JsInterface")
-
-    }
-
-    private fun loadUrl() {
-        //webView.loadUrl("http://192.168.100.9:3000")
-        webView.loadUrl("file:///android_asset/index.html")
-    }
-
-    private fun setupSystemBars() {
-        val isDarkTheme = resources.configuration.uiMode and
-                Configuration.UI_MODE_NIGHT_MASK ==
-                Configuration.UI_MODE_NIGHT_YES
-
-        if (isDarkTheme) {
-            window.statusBarColor = Color.BLACK
-            window.navigationBarColor = Color.BLACK
-            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
-                window.insetsController?.setSystemBarsAppearance(
-                    0,
-                    WindowInsetsController.APPEARANCE_LIGHT_STATUS_BARS or
-                            WindowInsetsController.APPEARANCE_LIGHT_NAVIGATION_BARS
-                )
-            } else if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
-                @Suppress("DEPRECATION")
-                window.decorView.systemUiVisibility =
-                    window.decorView.systemUiVisibility and View.SYSTEM_UI_FLAG_LIGHT_STATUS_BAR.inv()
-                if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
-                    @Suppress("DEPRECATION")
-                    window.decorView.systemUiVisibility =
-                        window.decorView.systemUiVisibility and View.SYSTEM_UI_FLAG_LIGHT_NAVIGATION_BAR.inv()
-                }
-            }
-        } else {
-            window.statusBarColor = Color.WHITE
-            window.navigationBarColor = Color.WHITE
-            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
-                window.insetsController?.setSystemBarsAppearance(
-                    WindowInsetsController.APPEARANCE_LIGHT_STATUS_BARS or
-                            WindowInsetsController.APPEARANCE_LIGHT_NAVIGATION_BARS,
-                    WindowInsetsController.APPEARANCE_LIGHT_STATUS_BARS or
-                            WindowInsetsController.APPEARANCE_LIGHT_NAVIGATION_BARS
-                )
-            } else if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
-                @Suppress("DEPRECATION")
-                window.decorView.systemUiVisibility =
-                    window.decorView.systemUiVisibility or View.SYSTEM_UI_FLAG_LIGHT_STATUS_BAR
-                if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
-                    @Suppress("DEPRECATION")
-                    window.decorView.systemUiVisibility =
-                        window.decorView.systemUiVisibility or View.SYSTEM_UI_FLAG_LIGHT_NAVIGATION_BAR
-                }
-            }
-        }
-    }
-
-    override fun onBackPressed() {
-        if (webView.canGoBack()) webView.goBack() else super.onBackPressed()
-    }
-
-    override fun onConfigurationChanged(newConfig: Configuration) {
-        super.onConfigurationChanged(newConfig)
-        setupSystemBars()
-        setupWebViewBackground()
-        setupRootBackground()
-    }
-
-    private fun setupWebViewBackground() {
-        val isDarkTheme = resources.configuration.uiMode and
-                Configuration.UI_MODE_NIGHT_MASK ==
-                Configuration.UI_MODE_NIGHT_YES
-        webView.setBackgroundColor(if (isDarkTheme) Color.BLACK else Color.WHITE)
-    }
-
-    private fun setupRootBackground() {
-        val isDarkTheme = resources.configuration.uiMode and
-                Configuration.UI_MODE_NIGHT_MASK ==
-                Configuration.UI_MODE_NIGHT_YES
-        val rootView = findViewById<View>(android.R.id.content)
-        rootView.setBackgroundColor(if (isDarkTheme) Color.BLACK else Color.WHITE)
-    }
-}

android-app/app/src/main/res/drawable/ic_launcher_background.xml

@@ -1,74 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<vector
-    android:height="108dp"
-    android:width="108dp"
-    android:viewportHeight="108"
-    android:viewportWidth="108"
-    xmlns:android="http://schemas.android.com/apk/res/android">
-    <path android:fillColor="#3DDC84"
-          android:pathData="M0,0h108v108h-108z"/>
-    <path android:fillColor="#00000000" android:pathData="M9,0L9,108"
-          android:strokeColor="#33FFFFFF" android:strokeWidth="0.8"/>
-    <path android:fillColor="#00000000" android:pathData="M19,0L19,108"
-          android:strokeColor="#33FFFFFF" android:strokeWidth="0.8"/>
-    <path android:fillColor="#00000000" android:pathData="M29,0L29,108"
-          android:strokeColor="#33FFFFFF" android:strokeWidth="0.8"/>
-    <path android:fillColor="#00000000" android:pathData="M39,0L39,108"
-          android:strokeColor="#33FFFFFF" android:strokeWidth="0.8"/>
-    <path android:fillColor="#00000000" android:pathData="M49,0L49,108"
-          android:strokeColor="#33FFFFFF" android:strokeWidth="0.8"/>
-    <path android:fillColor="#00000000" android:pathData="M59,0L59,108"
-          android:strokeColor="#33FFFFFF" android:strokeWidth="0.8"/>
-    <path android:fillColor="#00000000" android:pathData="M69,0L69,108"
-          android:strokeColor="#33FFFFFF" android:strokeWidth="0.8"/>
-    <path android:fillColor="#00000000" android:pathData="M79,0L79,108"
-          android:strokeColor="#33FFFFFF" android:strokeWidth="0.8"/>
-    <path android:fillColor="#00000000" android:pathData="M89,0L89,108"
-          android:strokeColor="#33FFFFFF" android:strokeWidth="0.8"/>
-    <path android:fillColor="#00000000" android:pathData="M99,0L99,108"
-          android:strokeColor="#33FFFFFF" android:strokeWidth="0.8"/>
-    <path android:fillColor="#00000000" android:pathData="M0,9L108,9"
-          android:strokeColor="#33FFFFFF" android:strokeWidth="0.8"/>
-    <path android:fillColor="#00000000" android:pathData="M0,19L108,19"
-          android:strokeColor="#33FFFFFF" android:strokeWidth="0.8"/>
-    <path android:fillColor="#00000000" android:pathData="M0,29L108,29"
-          android:strokeColor="#33FFFFFF" android:strokeWidth="0.8"/>
-    <path android:fillColor="#00000000" android:pathData="M0,39L108,39"
-          android:strokeColor="#33FFFFFF" android:strokeWidth="0.8"/>
-    <path android:fillColor="#00000000" android:pathData="M0,49L108,49"
-          android:strokeColor="#33FFFFFF" android:strokeWidth="0.8"/>
-    <path android:fillColor="#00000000" android:pathData="M0,59L108,59"
-          android:strokeColor="#33FFFFFF" android:strokeWidth="0.8"/>
-    <path android:fillColor="#00000000" android:pathData="M0,69L108,69"
-          android:strokeColor="#33FFFFFF" android:strokeWidth="0.8"/>
-    <path android:fillColor="#00000000" android:pathData="M0,79L108,79"
-          android:strokeColor="#33FFFFFF" android:strokeWidth="0.8"/>
-    <path android:fillColor="#00000000" android:pathData="M0,89L108,89"
-          android:strokeColor="#33FFFFFF" android:strokeWidth="0.8"/>
-    <path android:fillColor="#00000000" android:pathData="M0,99L108,99"
-          android:strokeColor="#33FFFFFF" android:strokeWidth="0.8"/>
-    <path android:fillColor="#00000000" android:pathData="M19,29L89,29"
-          android:strokeColor="#33FFFFFF" android:strokeWidth="0.8"/>
-    <path android:fillColor="#00000000" android:pathData="M19,39L89,39"
-          android:strokeColor="#33FFFFFF" android:strokeWidth="0.8"/>
-    <path android:fillColor="#00000000" android:pathData="M19,49L89,49"
-          android:strokeColor="#33FFFFFF" android:strokeWidth="0.8"/>
-    <path android:fillColor="#00000000" android:pathData="M19,59L89,59"
-          android:strokeColor="#33FFFFFF" android:strokeWidth="0.8"/>
-    <path android:fillColor="#00000000" android:pathData="M19,69L89,69"
-          android:strokeColor="#33FFFFFF" android:strokeWidth="0.8"/>
-    <path android:fillColor="#00000000" android:pathData="M19,79L89,79"
-          android:strokeColor="#33FFFFFF" android:strokeWidth="0.8"/>
-    <path android:fillColor="#00000000" android:pathData="M29,19L29,89"
-          android:strokeColor="#33FFFFFF" android:strokeWidth="0.8"/>
-    <path android:fillColor="#00000000" android:pathData="M39,19L39,89"
-          android:strokeColor="#33FFFFFF" android:strokeWidth="0.8"/>
-    <path android:fillColor="#00000000" android:pathData="M49,19L49,89"
-          android:strokeColor="#33FFFFFF" android:strokeWidth="0.8"/>
-    <path android:fillColor="#00000000" android:pathData="M59,19L59,89"
-          android:strokeColor="#33FFFFFF" android:strokeWidth="0.8"/>
-    <path android:fillColor="#00000000" android:pathData="M69,19L69,89"
-          android:strokeColor="#33FFFFFF" android:strokeWidth="0.8"/>
-    <path android:fillColor="#00000000" android:pathData="M79,19L79,89"
-          android:strokeColor="#33FFFFFF" android:strokeWidth="0.8"/>
-</vector>

android-app/app/src/main/res/drawable/ic_launcher_foreground.xml

@@ -1,30 +0,0 @@
-<vector xmlns:android="http://schemas.android.com/apk/res/android"
-    xmlns:aapt="http://schemas.android.com/aapt"
-    android:width="108dp"
-    android:height="108dp"
-    android:viewportWidth="108"
-    android:viewportHeight="108">
-    <path android:pathData="M31,63.928c0,0 6.4,-11 12.1,-13.1c7.2,-2.6 26,-1.4 26,-1.4l38.1,38.1L107,108.928l-32,-1L31,63.928z">
-        <aapt:attr name="android:fillColor">
-            <gradient
-                android:endX="85.84757"
-                android:endY="92.4963"
-                android:startX="42.9492"
-                android:startY="49.59793"
-                android:type="linear">
-                <item
-                    android:color="#44000000"
-                    android:offset="0.0" />
-                <item
-                    android:color="#00000000"
-                    android:offset="1.0" />
-            </gradient>
-        </aapt:attr>
-    </path>
-    <path
-        android:fillColor="#FFFFFF"
-        android:fillType="nonZero"
-        android:pathData="M65.3,45.828l3.8,-6.6c0.2,-0.4 0.1,-0.9 -0.3,-1.1c-0.4,-0.2 -0.9,-0.1 -1.1,0.3l-3.9,6.7c-6.3,-2.8 -13.4,-2.8 -19.7,0l-3.9,-6.7c-0.2,-0.4 -0.7,-0.5 -1.1,-0.3C38.8,38.328 38.7,38.828 38.9,39.228l3.8,6.6C36.2,49.428 31.7,56.028 31,63.928h46C76.3,56.028 71.8,49.428 65.3,45.828zM43.4,57.328c-0.8,0 -1.5,-0.5 -1.8,-1.2c-0.3,-0.7 -0.1,-1.5 0.4,-2.1c0.5,-0.5 1.4,-0.7 2.1,-0.4c0.7,0.3 1.2,1 1.2,1.8C45.3,56.528 44.5,57.328 43.4,57.328L43.4,57.328zM64.6,57.328c-0.8,0 -1.5,-0.5 -1.8,-1.2s-0.1,-1.5 0.4,-2.1c0.5,-0.5 1.4,-0.7 2.1,-0.4c0.7,0.3 1.2,1 1.2,1.8C66.5,56.528 65.6,57.328 64.6,57.328L64.6,57.328z"
-        android:strokeWidth="1"
-        android:strokeColor="#00000000" />
-</vector>

android-app/app/src/main/res/layout/activity_main.xml

@@ -1,19 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<androidx.constraintlayout.widget.ConstraintLayout
-    xmlns:android="http://schemas.android.com/apk/res/android"
-    xmlns:tools="http://schemas.android.com/tools"
-    xmlns:app="http://schemas.android.com/apk/res-auto"
-    android:layout_width="match_parent"
-    android:layout_height="match_parent"
-    tools:context=".MainActivity">
-
-    <WebView
-        android:id="@+id/webView"
-        android:layout_width="0dp"
-        android:layout_height="0dp"
-        app:layout_constraintBottom_toBottomOf="parent"
-        app:layout_constraintStart_toStartOf="parent"
-        app:layout_constraintEnd_toEndOf="parent"
-        app:layout_constraintTop_toTopOf="parent" />
-
-</androidx.constraintlayout.widget.ConstraintLayout>

android-app/app/src/main/res/mipmap-anydpi-v26/ic_launcher.xml

@@ -1,5 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
-    <background android:drawable="@drawable/ic_launcher_background"/>
-    <foreground android:drawable="@mipmap/ic_launcher_foreground"/>
-</adaptive-icon>

android-app/app/src/main/res/mipmap-anydpi-v26/ic_launcher_round.xml

@@ -1,5 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
-    <background android:drawable="@drawable/ic_launcher_background"/>
-    <foreground android:drawable="@mipmap/ic_launcher_foreground"/>
-</adaptive-icon>

android-app/app/src/main/res/values-night/themes.xml

@@ -1,9 +0,0 @@
-<resources xmlns:tools="http://schemas.android.com/tools">
-    <!-- Base application theme. -->
-    <style name="Base.Theme.Flux" parent="Theme.Material3.DayNight.NoActionBar">
-        <!-- Customize your dark theme here. -->
-        <!-- <item name="colorPrimary">@color/my_dark_primary</item> -->
-        <item name="android:statusBarColor">@android:color/transparent</item>
-        <item name="android:navigationBarColor">@android:color/transparent</item>
-    </style>
-</resources>

android-app/app/src/main/res/values/colors.xml

@@ -1,6 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<resources>
-    <color name="black">#FF000000</color>
-    <color name="white">#FFFFFFFF</color>
-
-</resources>

android-app/app/src/main/res/values/strings.xml

@@ -1,3 +0,0 @@
-<resources>
-    <string name="app_name">Flux</string>
-</resources>

android-app/app/src/main/res/values/themes.xml

@@ -1,11 +0,0 @@
-<resources xmlns:tools="http://schemas.android.com/tools">
-    <!-- Base application theme. -->
-    <style name="Base.Theme.Flux" parent="Theme.Material3.DayNight.NoActionBar">
-        <!-- Customize your light theme here. -->
-        <!-- <item name="colorPrimary">@color/my_light_primary</item> -->
-        <item name="android:statusBarColor">@android:color/transparent</item>
-        <item name="android:navigationBarColor">@android:color/transparent</item>
-    </style>
-
-    <style name="Theme.Flux" parent="Base.Theme.Flux" />
-</resources>

android-app/app/src/main/res/xml/backup_rules.xml

@@ -1,13 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?><!--
-   Sample backup rules file; uncomment and customize as necessary.
-   See https://developer.android.com/guide/topics/data/autobackup
-   for details.
-   Note: This file is ignored for devices older that API 31
-   See https://developer.android.com/about/versions/12/backup-restore
--->
-<full-backup-content>
-    <!--
-   <include domain="sharedpref" path="."/>
-   <exclude domain="sharedpref" path="device.xml"/>
--->
-</full-backup-content>

android-app/app/src/main/res/xml/data_extraction_rules.xml

@@ -1,19 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?><!--
-   Sample data extraction rules file; uncomment and customize as necessary.
-   See https://developer.android.com/about/versions/12/backup-restore#xml-changes
-   for details.
--->
-<data-extraction-rules>
-    <cloud-backup>
-        <!-- TODO: Use <include> and <exclude> to control what is backed up.
-        <include .../>
-        <exclude .../>
-        -->
-    </cloud-backup>
-    <!--
-    <device-transfer>
-        <include .../>
-        <exclude .../>
-    </device-transfer>
-    -->
-</data-extraction-rules>

android-app/app/src/test/java/com/flux/ExampleUnitTest.kt

@@ -1,17 +0,0 @@
-package com.flux
-
-import org.junit.Test
-
-import org.junit.Assert.*
-
-/**
- * Example local unit test, which will execute on the development machine (host).
- *
- * See [testing documentation](http://d.android.com/tools/testing).
- */
-class ExampleUnitTest {
-    @Test
-    fun addition_isCorrect() {
-        assertEquals(4, 2 + 2)
-    }
-}

android-app/build.gradle

@@ -1,5 +0,0 @@
-// Top-level build file where you can add configuration options common to all sub-projects/modules.
-plugins {
-    id 'com.android.application' version '8.2.2' apply false
-    id 'org.jetbrains.kotlin.android' version '1.8.0' apply false
-}

android-app/gradle.properties

@@ -1,23 +0,0 @@
-# Project-wide Gradle settings.
-# IDE (e.g. Android Studio) users:
-# Gradle settings configured through the IDE *will override*
-# any settings specified in this file.
-# For more details on how to configure your build environment visit
-# http://www.gradle.org/docs/current/userguide/build_environment.html
-# Specifies the JVM arguments used for the daemon process.
-# The setting is particularly useful for tweaking memory settings.
-org.gradle.jvmargs=-Xmx2048m -Dfile.encoding=UTF-8
-# When configured, Gradle will run in incubating parallel mode.
-# This option should only be used with decoupled projects. More details, visit
-# http://www.gradle.org/docs/current/userguide/multi_project_builds.html#sec:decoupled_projects
-# org.gradle.parallel=true
-# AndroidX package structure to make it clearer which packages are bundled with the
-# Android operating system, and which are packaged with your app's APK
-# https://developer.android.com/topic/libraries/support-library/androidx-rn
-android.useAndroidX=true
-# Kotlin code style for this project: "official" or "obsolete":
-kotlin.code.style=official
-# Enables namespacing of each library's R class so that its R class includes only the
-# resources declared in the library itself and none from the library's dependencies,
-# thereby reducing the size of the R class for that library
-android.nonTransitiveRClass=true

android-app/gradle/wrapper/gradle-wrapper.properties

@@ -1,6 +0,0 @@
-#Wed Aug 20 09:15:27 CST 2025
-distributionBase=GRADLE_USER_HOME
-distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-8.2.1-bin.zip
-zipStoreBase=GRADLE_USER_HOME
-zipStorePath=wrapper/dists

android-app/gradlew

@@ -1,185 +0,0 @@
-#!/usr/bin/env sh
-
-#
-# Copyright 2015 the original author or authors.
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#      https://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-#
-
-##############################################################################
-##
-##  Gradle start up script for UN*X
-##
-##############################################################################
-
-# Attempt to set APP_HOME
-# Resolve links: $0 may be a link
-PRG="$0"
-# Need this for relative symlinks.
-while [ -h "$PRG" ] ; do
-    ls=`ls -ld "$PRG"`
-    link=`expr "$ls" : '.*-> \(.*\)$'`
-    if expr "$link" : '/.*' > /dev/null; then
-        PRG="$link"
-    else
-        PRG=`dirname "$PRG"`"/$link"
-    fi
-done
-SAVED="`pwd`"
-cd "`dirname \"$PRG\"`/" >/dev/null
-APP_HOME="`pwd -P`"
-cd "$SAVED" >/dev/null
-
-APP_NAME="Gradle"
-APP_BASE_NAME=`basename "$0"`
-
-# Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
-DEFAULT_JVM_OPTS='"-Xmx64m" "-Xms64m"'
-
-# Use the maximum available, or set MAX_FD != -1 to use that value.
-MAX_FD="maximum"
-
-warn () {
-    echo "$*"
-}
-
-die () {
-    echo
-    echo "$*"
-    echo
-    exit 1
-}
-
-# OS specific support (must be 'true' or 'false').
-cygwin=false
-msys=false
-darwin=false
-nonstop=false
-case "`uname`" in
-  CYGWIN* )
-    cygwin=true
-    ;;
-  Darwin* )
-    darwin=true
-    ;;
-  MINGW* )
-    msys=true
-    ;;
-  NONSTOP* )
-    nonstop=true
-    ;;
-esac
-
-CLASSPATH=$APP_HOME/gradle/wrapper/gradle-wrapper.jar
-
-
-# Determine the Java command to use to start the JVM.
-if [ -n "$JAVA_HOME" ] ; then
-    if [ -x "$JAVA_HOME/jre/sh/java" ] ; then
-        # IBM's JDK on AIX uses strange locations for the executables
-        JAVACMD="$JAVA_HOME/jre/sh/java"
-    else
-        JAVACMD="$JAVA_HOME/bin/java"
-    fi
-    if [ ! -x "$JAVACMD" ] ; then
-        die "ERROR: JAVA_HOME is set to an invalid directory: $JAVA_HOME
-
-Please set the JAVA_HOME variable in your environment to match the
-location of your Java installation."
-    fi
-else
-    JAVACMD="java"
-    which java >/dev/null 2>&1 || die "ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
-
-Please set the JAVA_HOME variable in your environment to match the
-location of your Java installation."
-fi
-
-# Increase the maximum file descriptors if we can.
-if [ "$cygwin" = "false" -a "$darwin" = "false" -a "$nonstop" = "false" ] ; then
-    MAX_FD_LIMIT=`ulimit -H -n`
-    if [ $? -eq 0 ] ; then
-        if [ "$MAX_FD" = "maximum" -o "$MAX_FD" = "max" ] ; then
-            MAX_FD="$MAX_FD_LIMIT"
-        fi
-        ulimit -n $MAX_FD
-        if [ $? -ne 0 ] ; then
-            warn "Could not set maximum file descriptor limit: $MAX_FD"
-        fi
-    else
-        warn "Could not query maximum file descriptor limit: $MAX_FD_LIMIT"
-    fi
-fi
-
-# For Darwin, add options to specify how the application appears in the dock
-if $darwin; then
-    GRADLE_OPTS="$GRADLE_OPTS \"-Xdock:name=$APP_NAME\" \"-Xdock:icon=$APP_HOME/media/gradle.icns\""
-fi
-
-# For Cygwin or MSYS, switch paths to Windows format before running java
-if [ "$cygwin" = "true" -o "$msys" = "true" ] ; then
-    APP_HOME=`cygpath --path --mixed "$APP_HOME"`
-    CLASSPATH=`cygpath --path --mixed "$CLASSPATH"`
-
-    JAVACMD=`cygpath --unix "$JAVACMD"`
-
-    # We build the pattern for arguments to be converted via cygpath
-    ROOTDIRSRAW=`find -L / -maxdepth 1 -mindepth 1 -type d 2>/dev/null`
-    SEP=""
-    for dir in $ROOTDIRSRAW ; do
-        ROOTDIRS="$ROOTDIRS$SEP$dir"
-        SEP="|"
-    done
-    OURCYGPATTERN="(^($ROOTDIRS))"
-    # Add a user-defined pattern to the cygpath arguments
-    if [ "$GRADLE_CYGPATTERN" != "" ] ; then
-        OURCYGPATTERN="$OURCYGPATTERN|($GRADLE_CYGPATTERN)"
-    fi
-    # Now convert the arguments - kludge to limit ourselves to /bin/sh
-    i=0
-    for arg in "$@" ; do
-        CHECK=`echo "$arg"|egrep -c "$OURCYGPATTERN" -`
-        CHECK2=`echo "$arg"|egrep -c "^-"`                                 ### Determine if an option
-
-        if [ $CHECK -ne 0 ] && [ $CHECK2 -eq 0 ] ; then                    ### Added a condition
-            eval `echo args$i`=`cygpath --path --ignore --mixed "$arg"`
-        else
-            eval `echo args$i`="\"$arg\""
-        fi
-        i=`expr $i + 1`
-    done
-    case $i in
-        0) set -- ;;
-        1) set -- "$args0" ;;
-        2) set -- "$args0" "$args1" ;;
-        3) set -- "$args0" "$args1" "$args2" ;;
-        4) set -- "$args0" "$args1" "$args2" "$args3" ;;
-        5) set -- "$args0" "$args1" "$args2" "$args3" "$args4" ;;
-        6) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" ;;
-        7) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" ;;
-        8) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" "$args7" ;;
-        9) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" "$args7" "$args8" ;;
-    esac
-fi
-
-# Escape application args
-save () {
-    for i do printf %s\\n "$i" | sed "s/'/'\\\\''/g;1s/^/'/;\$s/\$/' \\\\/" ; done
-    echo " "
-}
-APP_ARGS=`save "$@"`
-
-# Collect all arguments for the java command, following the shell quoting and substitution rules
-eval set -- $DEFAULT_JVM_OPTS $JAVA_OPTS $GRADLE_OPTS "\"-Dorg.gradle.appname=$APP_BASE_NAME\"" -classpath "\"$CLASSPATH\"" org.gradle.wrapper.GradleWrapperMain "$APP_ARGS"
-
-exec "$JAVACMD" "$@"

android-app/gradlew.bat

@@ -1,89 +0,0 @@
-@rem
-@rem Copyright 2015 the original author or authors.
-@rem
-@rem Licensed under the Apache License, Version 2.0 (the "License");
-@rem you may not use this file except in compliance with the License.
-@rem You may obtain a copy of the License at
-@rem
-@rem      https://www.apache.org/licenses/LICENSE-2.0
-@rem
-@rem Unless required by applicable law or agreed to in writing, software
-@rem distributed under the License is distributed on an "AS IS" BASIS,
-@rem WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-@rem See the License for the specific language governing permissions and
-@rem limitations under the License.
-@rem
-
-@if "%DEBUG%" == "" @echo off
-@rem ##########################################################################
-@rem
-@rem  Gradle startup script for Windows
-@rem
-@rem ##########################################################################
-
-@rem Set local scope for the variables with windows NT shell
-if "%OS%"=="Windows_NT" setlocal
-
-set DIRNAME=%~dp0
-if "%DIRNAME%" == "" set DIRNAME=.
-set APP_BASE_NAME=%~n0
-set APP_HOME=%DIRNAME%
-
-@rem Resolve any "." and ".." in APP_HOME to make it shorter.
-for %%i in ("%APP_HOME%") do set APP_HOME=%%~fi
-
-@rem Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
-set DEFAULT_JVM_OPTS="-Xmx64m" "-Xms64m"
-
-@rem Find java.exe
-if defined JAVA_HOME goto findJavaFromJavaHome
-
-set JAVA_EXE=java.exe
-%JAVA_EXE% -version >NUL 2>&1
-if "%ERRORLEVEL%" == "0" goto execute
-
-echo.
-echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
-echo.
-echo Please set the JAVA_HOME variable in your environment to match the
-echo location of your Java installation.
-
-goto fail
-
-:findJavaFromJavaHome
-set JAVA_HOME=%JAVA_HOME:"=%
-set JAVA_EXE=%JAVA_HOME%/bin/java.exe
-
-if exist "%JAVA_EXE%" goto execute
-
-echo.
-echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME%
-echo.
-echo Please set the JAVA_HOME variable in your environment to match the
-echo location of your Java installation.
-
-goto fail
-
-:execute
-@rem Setup the command line
-
-set CLASSPATH=%APP_HOME%\gradle\wrapper\gradle-wrapper.jar
-
-
-@rem Execute Gradle
-"%JAVA_EXE%" %DEFAULT_JVM_OPTS% %JAVA_OPTS% %GRADLE_OPTS% "-Dorg.gradle.appname=%APP_BASE_NAME%" -classpath "%CLASSPATH%" org.gradle.wrapper.GradleWrapperMain %*
-
-:end
-@rem End local scope for the variables with windows NT shell
-if "%ERRORLEVEL%"=="0" goto mainEnd
-
-:fail
-rem Set variable GRADLE_EXIT_CONSOLE if you need the _script_ return code instead of
-rem the _cmd.exe /c_ return code!
-if  not "" == "%GRADLE_EXIT_CONSOLE%" exit 1
-exit /b 1
-
-:mainEnd
-if "%OS%"=="Windows_NT" endlocal
-
-:omega

android-app/settings.gradle

@@ -1,17 +0,0 @@
-pluginManagement {
-    repositories {
-        google()
-        mavenCentral()
-        gradlePluginPortal()
-    }
-}
-dependencyResolutionManagement {
-    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
-    repositories {
-        google()
-        mavenCentral()
-    }
-}
-
-rootProject.name = "Flux"
-include ':app'

doc/ai-skill.md

@@ -0,0 +1,220 @@
+# AI Skill 使用指南
+
+让大模型直接操作 FLVX 面板的技能包。支持 OpenCode、OpenClaw、Claude Code 等工具。
+
+## 安装
+
+### 方式 1: npm (推荐)
+
+```bash
+npm install -g @flvx/skill-api
+```
+
+postinstall 脚本会自动链接到 `~/.agents/skills/flvx-api/`。
+
+### 方式 2: 手动链接
+
+```bash
+# 从 FLVX 源码
+cd /path/to/flvx
+mkdir -p ~/.agents/skills
+ln -sf $(pwd)/skills/flvx-api ~/.agents/skills/
+
+# 或从 GitHub
+git clone https://github.com/Sagit-chu/flvx.git
+cd flvx
+ln -sf $(pwd)/skills/flvx-api ~/.agents/skills/
+```
+
+## 配置
+
+设置环境变量：
+
+```bash
+export FLVX_BASE_URL="https://your-panel.example.com"
+export FLVX_USERNAME="admin"
+export FLVX_PASSWORD="your-password"
+```
+
+或使用凭证文件：
+
+```bash
+mkdir -p ~/.flvx
+cat > ~/.flvx/.env << 'EOF'
+export FLVX_BASE_URL="https://panel.example.com"
+export FLVX_USERNAME="admin"
+export FLVX_PASSWORD="your-password"
+EOF
+chmod 600 ~/.flvx/.env
+source ~/.flvx/.env
+```
+
+---
+
+## 工具接入方法
+
+### OpenCode
+
+OpenCode 是命令行 AI 编程助手，支持通过 skills 扩展能力。
+
+**安装 skill:**
+```bash
+npm install -g @flvx/skill-api
+```
+
+**使用:**
+```bash
+export FLVX_BASE_URL="https://panel.example.com"
+export FLVX_USERNAME="admin"
+export FLVX_PASSWORD="your-password"
+
+opencode
+```
+
+**示例对话:**
+```
+你: 查看我的转发列表
+你: 创建一个转发到 192.168.1.100:80 使用隧道 1
+你: 检查节点状态
+你: 查看流量使用情况
+```
+
+---
+
+### OpenClaw
+
+OpenClaw 同样支持 skills 机制。
+
+**安装 skill:**
+```bash
+npm install -g @flvx/skill-api
+
+# 或手动链接
+mkdir -p ~/.openclaw/skills
+ln -sf /path/to/flvx/skills/flvx-api ~/.openclaw/skills/flvx-api
+```
+
+**使用:**
+```bash
+openclaw
+
+>>> 查看所有节点状态
+>>> 给用户 alice 分配 50GB 流量
+>>> 导出系统备份
+```
+
+---
+
+### Claude Code
+
+Claude Code 是 Anthropic 官方的命令行工具，支持通过 CLAUDE.md 扩展。
+
+#### 方式 1: 项目级 CLAUDE.md
+
+在项目根目录创建 `CLAUDE.md`：
+
+```markdown
+# FLVX API Skill
+
+你可以通过 REST API 操作 FLVX 面板。
+
+## 环境变量
+- FLVX_BASE_URL: 面板地址
+- FLVX_USERNAME: 用户名
+- FLVX_PASSWORD: 密码
+
+## 认证规则
+- Authorization 头使用原始 JWT token，不加 "Bearer " 前缀
+- 所有 API 使用 POST 方法
+
+## 常用 API
+
+### 登录获取 token
+POST /api/v1/user/login
+{"username": "...", "password": "..."}
+
+### 查看转发列表
+POST /api/v1/forward/list
+Authorization: <token>
+{}
+
+### 创建转发
+POST /api/v1/forward/create
+{"name": "xxx", "tunnelId": 1, "remoteAddr": "1.2.3.4:80"}
+
+### 查看节点
+POST /api/v1/node/list
+{}
+```
+
+**使用:**
+```bash
+cd /path/to/your/project
+claude
+```
+
+#### 方式 2: 全局 CLAUDE.md
+
+```bash
+mkdir -p ~/.claude
+cat > ~/.claude/CLAUDE.md << 'EOF'
+# FLVX Panel Operations
+
+使用 FLVX REST API 操作流量转发面板。
+
+环境变量: FLVX_BASE_URL, FLVX_USERNAME, FLVX_PASSWORD
+调用方式: curl -X POST "$FLVX_BASE_URL/api/v1/..." -H "Authorization: $TOKEN"
+注意: Authorization 不要加 Bearer 前缀
+EOF
+```
+
+#### 方式 3: 复制 SKILL.md
+
+```bash
+cat ~/.agents/skills/flvx-api/SKILL.md >> ~/.claude/CLAUDE.md
+```
+
+**示例对话:**
+```
+>>> 帮我查看 FLVX 面板上有哪些节点
+>>> 创建一个名为 test 的转发，目标地址 10.0.0.1:80
+>>> 查看我的流量使用情况
+```
+
+---
+
+## API 覆盖
+
+| 模块 | 操作 |
+|------|------|
+| 认证 | 登录、Token 管理 |
+| 用户 | 增删改查、流量重置、密码 |
+| 节点 | 增删改查、安装、升级、状态 |
+| 隧道 | 增删改查、用户分配 |
+| 转发 | 增删改查、暂停/恢复、诊断 |
+| 分组 | 用户/隧道分组、权限 |
+| 限速 | 增删改查 |
+| 联邦 | 节点共享、远程节点 |
+| 备份 | 导出/导入 |
+
+## 安全提示
+
+- ⚠️ 环境变量在进程列表中可见
+- 使用 `~/.flvx/.env` 文件并设置 `chmod 600`
+- 添加 `export HISTIGNORE="*FLVX_PASSWORD*"` 防止密码进入历史记录
+- Token 仅在会话内存中缓存，不写入磁盘
+
+## 发布
+
+维护者可通过以下方式发布新版本：
+
+```bash
+# 方式 1: 推送 tag
+git tag skill-v2.1.6
+git push --tags
+
+# 方式 2: GitHub Actions 手动触发
+# 在 Actions 页面运行 publish-skill workflow
+```
+
+需要在 GitHub 仓库设置 `NPM_TOKEN` secret。

doc/faq.md

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

doc/index.md

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

doc/install.md

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

doc/postgresql.md

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

doc/usage.md

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

docker-compose-v4.yml

@@ -1,18 +1,29 @@
 services:
   backend:
-    image: bqlpfy/springboot-backend:2.0.7-beta
-    container_name: springboot-backend
+    image: ghcr.io/sagit-chu/flux-panel-backend:${FLUX_VERSION:-latest}
+    container_name: flux-panel-backend
     restart: unless-stopped
+    logging:
+      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
-      JAVA_OPTS: "-Xms256m -Xmx512m -Dfile.encoding=UTF-8 -Duser.timezone=Asia/Shanghai"
+      SERVER_ADDR: :6365
+      TZ: Asia/Shanghai
+      FLUX_VERSION: ${FLUX_VERSION:-dev}
+      PANEL_DEPLOY_DIR: /opt/flvx-panel
+      PANEL_BACKEND_CONTAINER: flux-panel-backend
     ports:
       - "${BACKEND_PORT}:6365"
     volumes:
-      - backend_logs:/app/logs
       - sqlite_data:/app/data
+      - /var/run/docker.sock:/var/run/docker.sock
+      - ./:/opt/flvx-panel
     networks:
       - gost-network
     stop_grace_period: 30s
@@ -22,12 +33,41 @@ services:
       interval: 30s
       timeout: 10s
       retries: 5
-      start_period: 60s
+      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: bqlpfy/vite-frontend:2.0.7-beta
+    image: ghcr.io/sagit-chu/vite-frontend:${FLUX_VERSION:-latest}
     container_name: vite-frontend
     restart: unless-stopped
+    logging:
+      driver: json-file
+      options:
+        max-size: "20m"
+        max-file: "3"
     ports:
       - "${FRONTEND_PORT}:80"
     depends_on:
@@ -41,8 +81,8 @@ volumes:
   sqlite_data:
     name: sqlite_data
     driver: local
-  backend_logs:
-    name: backend_logs
+  postgres_data:
+    name: postgres_data
     driver: local
 
 
@@ -52,4 +92,4 @@ networks:
     driver: bridge
     ipam:
       config:
-        - subnet: 172.20.0.0/16 
+        - subnet: 172.80.0.0/16 

docker-compose-v6.yml

@@ -1,18 +1,29 @@
 services:
   backend:
-    image: bqlpfy/springboot-backend:2.0.7-beta
-    container_name: springboot-backend
+    image: ghcr.io/sagit-chu/flux-panel-backend:${FLUX_VERSION:-latest}
+    container_name: flux-panel-backend
     restart: unless-stopped
+    logging:
+      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
-      JAVA_OPTS: "-Xms256m -Xmx512m -Dfile.encoding=UTF-8 -Duser.timezone=Asia/Shanghai"
+      SERVER_ADDR: :6365
+      TZ: Asia/Shanghai
+      FLUX_VERSION: ${FLUX_VERSION:-dev}
+      PANEL_DEPLOY_DIR: /opt/flvx-panel
+      PANEL_BACKEND_CONTAINER: flux-panel-backend
     ports:
       - "${BACKEND_PORT}:6365"
     volumes:
-      - backend_logs:/app/logs
       - sqlite_data:/app/data
+      - /var/run/docker.sock:/var/run/docker.sock
+      - ./:/opt/flvx-panel
     networks:
       - gost-network
     stop_grace_period: 30s
@@ -22,12 +33,41 @@ services:
       interval: 30s
       timeout: 10s
       retries: 5
-      start_period: 60s
+      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: bqlpfy/vite-frontend:2.0.7-beta
+    image: ghcr.io/sagit-chu/vite-frontend:${FLUX_VERSION:-latest}
     container_name: vite-frontend
     restart: unless-stopped
+    logging:
+      driver: json-file
+      options:
+        max-size: "20m"
+        max-file: "3"
     ports:
       - "${FRONTEND_PORT}:80"
     depends_on:
@@ -41,8 +81,8 @@ volumes:
   sqlite_data:
     name: sqlite_data
     driver: local
-  backend_logs:
-    name: backend_logs
+  postgres_data:
+    name: postgres_data
     driver: local
 
 
@@ -53,5 +93,5 @@ networks:
     enable_ipv6: true
     ipam:
       config:
-        - subnet: 172.20.0.0/16 
-        - subnet: fd00:dead:beef::/48
+        - subnet: 172.80.0.0/16 
+        - subnet: fd00:dead:beef::/48

docs/proxy-protocol-analysis.md

@@ -0,0 +1,178 @@
+# Proxy Protocol 传输分析报告
+
+**日期**: 2026-05-07  
+**测试环境**: 20.118.172.127 (Server 1) ↔ 108.181.90.137 (Server 2)
+
+---
+
+## 1. 代码流程分析
+
+### 完整数据链路
+
+```
+前端 (proxyProtocol: 0|1|2)
+  → 后端 handler mutations.go:1936
+  → 数据库存储 forward.proxy_protocol (model.go:50)
+  → 控制面 buildForwardServiceConfigs (control_plane.go:1791-1796)
+  → handler metadata: {"proxyProtocol": 2}
+  → Agent metadata 解析 (metadata.go:42)
+  → handler.go:256 WrapClientConn()
+  → conn.go:14 HeaderProxyFromAddrs(byte(ppv), src, dst)
+  → conn.go:15 header.WriteTo(c)
+  → 目标服务器收到 PROXY protocol header
+```
+
+### 关键代码
+
+**写入 PROXY header** (`go-gost/x/internal/net/proxyproto/conn.go`):
+```go
+func WrapClientConn(ppv int, src, dst net.Addr, c net.Conn) net.Conn {
+    if ppv <= 0 {
+        return c
+    }
+    header := proxyproto.HeaderProxyFromrs(byte(ppv), src, dst)
+    header.WriteTo(c)
+    return c
+}
+```
+
+**Handler 调用** (`go-gost/x/handler/forward/local/handler.go:256`):
+```go
+cc = proxyproto.WrapClientConn(h.md.proxyProtocol, conn.RemoteAddr(), conn.LocalAddr(), cc)
+```
+
+- `src` = `conn.RemoteAddr()` → 客户端真实 IP ✅
+- `dst` = `conn.LocalAddr()` → agent 监听地址 ✅
+- `ppv` = 1 或 2 → 版本号正确 ✅
+
+---
+
+## 2. 实际传输测试结果
+
+### 测试方法
+
+1. 在 Server 2 启动 Python TCP 监听器，解析 PROXY protocol header
+2. 在 Server 1 用当前代码编译 gost，配置 `proxyProtocol: 2` 转发到 Server 2
+3. 通过 `nc` 发送测试数据，验证 Server 2 是否收到正确的 PROXY header
+
+### 测试结果
+
+| 版本 | 状态 | 接收到的 Header |
+|------|------|----------------|
+| **PPv2** | ✅ 成功 | `PP2 family=1 alen=12 SRC=127.0.0.1:45410 DST=127.0.0.1:20001` |
+| **PPv1** | ✅ 成功 | `PROXY TCP4 127.0.0.1 127.0.0.1 43816 20001` |
+
+### 测试详情
+
+**PPv2 原始数据**:
+```
+Got 28 bytes
+PP2 family=1 alen=12
+SRC=127.0.0.1:45410 DST=127.0.0.1:20001
+```
+
+**PPv1 原始数据** (hex):
+```
+50524f58592054435034203132372e302e302e31203132372e302e302e312034333831362032303030310d0a
+```
+解码: `PROXY TCP4 127.0.0.1 127.0.0.1 43816 20001`
+
+---
+
+## 3. 单元测试结果
+
+```
+go-gost/x/handler/forward/local/  → TestLocalForwardHandlerSendsProxyProtocolToTarget ✅
+go-backend/internal/http/handler/ → TestBuildForwardServiceConfigsSendsProxyProtocolToForwardHandler ✅
+go-backend/internal/store/repo/   → TestGetForwardRecordIncludesProxyProtocol ✅
+```
+
+全部通过 (3/3)。
+
+---
+
+## 4. 发现的问题
+
+### 问题 1: `WriteTo` 错误未检查
+
+**位置**: `go-gost/x/internal/net/proxyproto/conn.go:15`
+
+```go
+header.WriteTo(c)  // 返回 (int64, error) 被忽略
+```
+
+**影响**: 如果写入失败（连接已断开、网络错误等），后续数据传输会在没有 PROXY header 的情况下继续，目标服务器可能解析出错。
+
+**建议**:
+```go
+if _, err := header.WriteTo(c); err != nil {
+    return c  // 或包装一个带错误的 conn
+}
+```
+
+**严重程度**: 低（实际场景中，写入失败后 `Transport` 也会很快失败）
+
+---
+
+### 问题 2: 部署版本过旧
+
+**服务器状态**:
+
+| 服务器 | 组件 | 版本 | 状态 |
+|--------|------|------|------|
+| 20.118.172.127 | flux_agent | UPX 压缩，无法读取版本 | ✅ 运行中 |
+| 20.118.172.127 | paneld | `/app/paneld` | ✅ 运行中 |
+| 20.118.172.127 | /usr/local/bin/gost | v3.0.0 (go1.23.4) | 旧版，不支持 handler metadata 中的 proxyProtocol |
+| 108.181.90.137 | flux_agent | 8.8MB | ✅ 运行中 |
+
+**影响**: 旧版 gost 二进制不识别 handler metadata 中的 `proxyProtocol` 字段，PROXY protocol 功能在生产环境不可用。
+
+**验证**: 用旧版 gost 测试时，目标服务器收到的原始数据为空，无 PROXY header。
+
+---
+
+### 问题 3: 数据库 Schema 缺失
+
+**位置**: 20.118.172.127 的 `/app/data/gost.db`
+
+**当前 forward 表 schema**:
+```sql
+CREATE TABLE `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,
+    `speed_id` integer
+);
+```
+
+**缺失字段**:
+- `proxy_protocol` — PROXY protocol 版本
+- `max_conn` — 最大连接数
+- `ip_max_conn` — 每 IP 最大连接数
+- `ip_speed_id` — 每 IP 限速 ID
+
+**影响**: 后端无法存储和读取 proxy_protocol 配置，前端设置不会生效。
+
+---
+
+## 5. 结论
+
+| 维度 | 状态 | 说明 |
+|------|------|------|
+| **代码实现** | ✅ 正确 | 完整的写入链路，版本/地址正确 |
+| **单元测试** | ✅ 通过 | 3/3 测试覆盖 handler、repo、控制面 |
+| **实际传输 (新编译版)** | ✅ 成功 | PPv1 和 PPv2 均正确传输 |
+| **实际传输 (部署版)** | ❌ 不工作 | 旧版不支持 handler metadata 中的 proxyProtocol |
+| **数据库 Schema** | ❌ 缺字段 | 需要迁移添加 proxy_protocol 等列 |
+
+**总结**: 代码实现正确，PROXY protocol 传输逻辑无误。但生产服务器运行的是旧版本，需要升级 backend 和 agent 才能启用此功能。

docs/superpowers/plans/001-floating-save-button.md

@@ -0,0 +1,132 @@
+# Floating Save Button Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add a floating save button (FAB) to the config page that appears when configuration changes are detected.
+
+**Architecture:** Inline FAB implementation using framer-motion AnimatePresence for enter/exit animations. Fixed-position circular button with slide-up animation, reusing existing hasChanges state and handleSave function.
+
+**Tech Stack:** React, framer-motion (v11.18.2), shadcn-bridge/heroui Button, Tailwind CSS
+
+---
+
+## File Structure
+
+| File | Action | Purpose |
+|------|--------|---------|
+| `vite-frontend/src/pages/config.tsx` | Modify | Add FAB imports and component at page bottom |
+
+---
+
+### Task 1: Add framer-motion Imports
+
+**Files:**
+- Modify: `vite-frontend/src/pages/config.tsx:1-5`
+
+- [ ] **Step 1: Add AnimatePresence and motion imports**
+
+Add import statement after existing framer-motion imports (or at top if none exist).
+
+Current imports at line 1-2:
+```typescript
+import { useState, useEffect, useRef } from "react";
+import { useNavigate } from "react-router-dom";
+```
+
+Add new import after line 2:
+```typescript
+import { AnimatePresence, motion } from "framer-motion";
+```
+
+- [ ] **Step 2: Commit import addition**
+
+```bash
+git add vite-frontend/src/pages/config.tsx
+git commit -m "feat(config): add framer-motion imports for FAB animation"
+```
+
+---
+
+### Task 2: Add FAB Component
+
+**Files:**
+- Modify: `vite-frontend/src/pages/config.tsx:1220-1224` (end of component)
+
+- [ ] **Step 1: Add FAB at end of component (before closing div)**
+
+Locate the end of `ConfigPage` component (line ~1223, the closing `</div>` after all modals).
+
+Insert FAB component before the closing `</div>`:
+
+```tsx
+      {/* Floating Save Button (FAB) */}
+      <AnimatePresence>
+        {hasChanges && (
+          <motion.div
+            initial={{ y: 100, opacity: 0 }}
+            animate={{ y: 0, opacity: 1 }}
+            exit={{ y: 100, opacity: 0 }}
+            transition={{ type: "spring", damping: 20, stiffness: 300 }}
+            className="fixed bottom-6 right-6 z-50"
+          >
+            <Button
+              isIconOnly
+              color="primary"
+              size="lg"
+              className="w-12 h-12 rounded-full shadow-lg"
+              isLoading={saving}
+              onPress={handleSave}
+            >
+              {!saving && <SaveIcon className="w-5 h-5" />}
+            </Button>
+          </motion.div>
+        )}
+      </AnimatePresence>
+    </div>
+  );
+}
+```
+
+- [ ] **Step 2: Run dev server to verify**
+
+```bash
+cd vite-frontend && npm run dev
+```
+
+Manual verification checklist:
+- Open config page at http://localhost:3000/config
+- Modify any config field
+- Verify FAB appears with slide-up animation
+- Click FAB to save
+- Verify FAB disappears with slide-down animation after save
+- Scroll page and verify FAB stays fixed in viewport corner
+- Test on mobile viewport (resize browser or use dev tools)
+
+- [ ] **Step 3: Commit FAB implementation**
+
+```bash
+git add vite-frontend/src/pages/config.tsx
+git commit -m "feat(config): add floating save button (FAB) for issue #266"
+```
+
+---
+
+## Verification Summary
+
+| Requirement | Verification Method |
+|-------------|---------------------|
+| FAB hidden by default | Visual: no FAB on page load with no changes |
+| FAB appears on change | Visual: modify field → FAB slides up |
+| Fixed position | Visual: scroll page → FAB stays in corner |
+| Slide-up animation | Visual: observe animation timing/bounce |
+| Slide-down on save | Visual: click save → FAB slides down |
+| Loading state | Visual: click save → spinner shown during save |
+| Mobile compatibility | Visual: resize to mobile viewport → same behavior |
+
+---
+
+## Self-Review Checklist
+
+- [x] Spec coverage: All requirements from design doc covered (imports + FAB component, animation params, button style, interaction behavior)
+- [x] No placeholders: All code shown, no TBD/TODO
+- [x] Type consistency: SaveIcon (line 45-59), handleSave (line 372-434), hasChanges (line 214), saving (line 213) all exist in config.tsx

docs/superpowers/plans/2026-04-01-github-proxy-config.md

@@ -0,0 +1,520 @@
+# GitHub 加速地址自定义配置实现计划
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 允许用户在面板设置中自定义 GitHub 加速地址，支持开启/关闭加速，配置影响全部下载场景。
+
+**Architecture:** 使用现有 `vite_config` 表存储配置，后端 Handler 读取配置替换硬编码，前端复用现有配置项渲染逻辑，安装脚本支持环境变量和交互式询问。
+
+**Tech Stack:** Go 1.24, React/TypeScript, Shell/Bash
+
+---
+
+## 文件结构
+
+| 文件 | 操作 | 说明 |
+|------|------|------|
+| `go-backend/internal/http/handler/upgrade.go` | 修改 | 移除硬编码，添加配置读取函数 |
+| `go-backend/internal/http/handler/mutations.go` | 修改 | `nodeInstall` 函数使用动态配置 |
+| `vite-frontend/src/pages/config.tsx` | 修改 | 添加两个新配置项 |
+| `install.sh` | 修改 | 支持交互式询问和环境变量 |
+| `panel_install.sh` | 修改 | 支持交互式询问和环境变量 |
+| `test-install-scripts-proxy.sh` | 新增 | 覆盖代理交互与下载 URL 回归 |
+
+---
+
+## Task 1: 后端 - upgrade.go 修改
+
+**Files:**
+- Modify: `go-backend/internal/http/handler/upgrade.go`
+
+- [x] **Step 1: 移除硬编码常量，添加配置读取函数**
+
+在 `upgrade.go` 中，移除 `githubProxy` 常量，添加 `getGithubProxyConfig` 函数：
+
+找到第 16-26 行：
+```go
+const (
+	githubRepo     = "Sagit-chu/flvx"
+	githubProxy    = "https://gcode.hostcentral.cc"
+	githubAPIBase  = "https://api.github.com"
+	githubHTMLBase = "https://github.com"
+	upgradeTimeout = 5 * time.Minute
+	batchWorkers   = 5
+
+	releaseChannelStable = "stable"
+	releaseChannelDev    = "dev"
+)
+```
+
+替换为：
+```go
+const (
+	githubRepo     = "Sagit-chu/flvx"
+	githubAPIBase  = "https://api.github.com"
+	githubHTMLBase = "https://github.com"
+	upgradeTimeout = 5 * time.Minute
+	batchWorkers   = 5
+
+	releaseChannelStable = "stable"
+	releaseChannelDev    = "dev"
+
+	defaultGithubProxyEnabled = true
+	defaultGithubProxyURL     = "https://gcode.hostcentral.cc"
+)
+```
+
+然后在 `releaseChannelLabel` 函数后（约第 71 行之后）添加新函数：
+```go
+// getGithubProxyConfig 获取 GitHub 加速配置
+// 返回: (是否开启加速, 加速地址)
+func (h *Handler) getGithubProxyConfig() (enabled bool, proxyURL string) {
+	enabled = defaultGithubProxyEnabled
+	proxyURL = defaultGithubProxyURL
+
+	if h == nil || h.repo == nil {
+		return
+	}
+
+	// 读取开启状态
+	if enabledCfg, err := h.repo.GetConfigByName("github_proxy_enabled"); err == nil && enabledCfg != nil {
+		enabled = enabledCfg.Value != "false"
+	}
+
+	// 读取加速地址
+	if urlCfg, err := h.repo.GetConfigByName("github_proxy_url"); err == nil && urlCfg != nil && urlCfg.Value != "" {
+		proxyURL = strings.TrimSpace(urlCfg.Value)
+		// 确保 URL 格式正确
+		if !strings.HasPrefix(proxyURL, "http://") && !strings.HasPrefix(proxyURL, "https://") {
+			proxyURL = "https://" + proxyURL
+		}
+		proxyURL = strings.TrimSuffix(proxyURL, "/")
+	}
+
+	return
+}
+
+// buildGithubDownloadURL 构建 GitHub 下载地址
+func (h *Handler) buildGithubDownloadURL(version, filename string) string {
+	enabled, proxyURL := h.getGithubProxyConfig()
+	base := fmt.Sprintf("%s/%s/releases/download/%s/%s", githubHTMLBase, githubRepo, version, filename)
+
+	if enabled {
+		return fmt.Sprintf("%s/%s", proxyURL, base)
+	}
+	return base
+}
+```
+
+- [x] **Step 2: 修改 nodeUpgrade 函数使用动态配置**
+
+找到第 152-159 行：
+```go
+	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,
+	)
+```
+
+替换为：
+```go
+	downloadURL := h.buildGithubDownloadURL(version, "gost-{ARCH}")
+	checksumURL := h.buildGithubDownloadURL(version, "gost-{ARCH}.sha256")
+```
+
+- [x] **Step 3: 修改 nodeBatchUpgrade 函数使用动态配置**
+
+找到第 216-223 行：
+```go
+	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,
+	)
+```
+
+替换为：
+```go
+	downloadURL := h.buildGithubDownloadURL(version, "gost-{ARCH}")
+	checksumURL := h.buildGithubDownloadURL(version, "gost-{ARCH}.sha256")
+```
+
+- [x] **Step 4: 验证编译**
+
+Run: `cd go-backend && go build ./...`
+Expected: 编译成功，无错误
+
+- [x] **Step 5: 提交**
+
+```bash
+git add go-backend/internal/http/handler/upgrade.go
+git commit -m "feat(backend): use configurable github proxy for node upgrades"
+```
+
+---
+
+## Task 2: 后端 - mutations.go 修改
+
+**Files:**
+- Modify: `go-backend/internal/http/handler/mutations.go`
+
+- [x] **Step 1: 修改 nodeInstall 函数使用动态配置**
+
+找到第 456 行：
+```go
+	cmd := fmt.Sprintf("curl -L https://gcode.hostcentral.cc/https://github.com/Sagit-chu/flvx/releases/download/%s/install.sh -o ./install.sh && chmod +x ./install.sh && VERSION=%s ./install.sh -a %s -s %s", version, version, processServerAddress(panelAddr), secret)
+```
+
+替换为：
+```go
+	enabled, proxyURL := h.getGithubProxyConfig()
+
+	var cmd string
+	if enabled {
+		cmd = fmt.Sprintf("curl -L %s/https://github.com/%s/releases/download/%s/install.sh -o ./install.sh && chmod +x ./install.sh && PROXY_ENABLED=true PROXY_URL=%s VERSION=%s ./install.sh -a %s -s %s",
+			proxyURL, githubRepo, version, proxyURL, version, processServerAddress(panelAddr), secret)
+	} else {
+		cmd = fmt.Sprintf("curl -L https://github.com/%s/releases/download/%s/install.sh -o ./install.sh && chmod +x ./install.sh && PROXY_ENABLED=false VERSION=%s ./install.sh -a %s -s %s",
+			githubRepo, version, version, processServerAddress(panelAddr), secret)
+	}
+```
+
+- [x] **Step 2: 验证编译**
+
+Run: `cd go-backend && go build ./...`
+Expected: 编译成功，无错误
+
+- [x] **Step 3: 提交**
+
+```bash
+git add go-backend/internal/http/handler/mutations.go
+git commit -m "feat(backend): use configurable github proxy for node install command"
+```
+
+---
+
+## Task 3: 前端 - config.tsx 添加配置项
+
+**Files:**
+- Modify: `vite-frontend/src/pages/config.tsx`
+
+- [x] **Step 1: 在 CONFIG_ITEMS 数组中添加配置项**
+
+找到第 158 行（`CONFIG_ITEMS` 数组的结束位置）：
+```go
+  {
+    key: "cloudflare_secret_key",
+    label: "Cloudflare Secret Key",
+    placeholder: "请输入 Cloudflare Secret Key",
+    description: "Cloudflare Turnstile 密钥",
+    type: "input",
+    dependsOn: "captcha_enabled",
+    dependsValue: "true",
+  },
+];
+```
+
+在 `];` 之前添加：
+```typescript
+  {
+    key: "github_proxy_enabled",
+    label: "开启 GitHub 加速",
+    description: "用于节点更新和安装脚本下载，解决部分地区 GitHub 访问受限问题",
+    type: "switch",
+  },
+  {
+    key: "github_proxy_url",
+    label: "加速地址",
+    placeholder: "https://gcode.hostcentral.cc",
+    description: "GitHub 下载加速代理地址，开启加速后生效",
+    type: "input",
+    dependsOn: "github_proxy_enabled",
+    dependsValue: "true",
+  },
+```
+
+- [x] **Step 2: 在缓存键列表中添加新键**
+
+找到第 179-190 行：
+```typescript
+  const configKeys = [
+    "app_name",
+    "captcha_enabled",
+    "cloudflare_site_key",
+    "cloudflare_secret_key",
+    "forward_compact_mode",
+    "monitor_tunnel_quality_enabled",
+    "ip",
+    "panel_domain",
+    "app_logo",
+    "app_favicon",
+  ];
+```
+
+在 `"app_favicon",` 之后添加：
+```typescript
+    "github_proxy_enabled",
+    "github_proxy_url",
+```
+
+- [x] **Step 3: 验证前端编译**
+
+Run: `cd vite-frontend && npm run build`
+Expected: 编译成功，无错误
+
+- [x] **Step 4: 提交**
+
+```bash
+git add vite-frontend/src/pages/config.tsx
+git commit -m "feat(frontend): add github proxy config settings"
+```
+
+---
+
+## Task 4: 安装脚本 - install.sh 修改
+
+**Files:**
+- Modify: `install.sh`
+
+- [x] **Step 1: 添加环境变量声明和修改 maybe_proxy_url 函数**
+
+找到第 28-32 行：
+```bash
+# 镜像加速（所有下载均经过镜像源，以支持 IPv6）
+maybe_proxy_url() {
+  local url="$1"
+  echo "https://gcode.hostcentral.cc/${url}"
+}
+```
+
+替换为：
+```bash
+# 镜像加速配置（可由面板传入或交互式询问）
+PROXY_ENABLED="${PROXY_ENABLED:-}"
+PROXY_URL="${PROXY_URL:-}"
+
+# 镜像加速
+maybe_proxy_url() {
+  local url="$1"
+
+  # 如果明确关闭加速
+  if [[ "$PROXY_ENABLED" == "false" ]]; then
+    echo "$url"
+    return
+  fi
+
+  # 默认开启加速
+  local proxy="${PROXY_URL:-gcode.hostcentral.cc}"
+
+  # 处理 URL 格式
+  if [[ "$proxy" == https://* || "$proxy" == http://* ]]; then
+    proxy="${proxy%/}"
+  else
+    proxy="https://${proxy}"
+  fi
+
+  echo "${proxy}/${url}"
+}
+
+# 询问加速配置（如果未由面板传入）
+ask_proxy_config() {
+  if [[ -n "$PROXY_ENABLED" ]]; then
+    return
+  fi
+
+  echo ""
+  echo "==============================================="
+  echo "           GitHub 加速配置"
+  echo "==============================================="
+  read -p "是否开启 GitHub 加速? (Y/n): " proxy_choice
+  case "$proxy_choice" in
+    n|N)
+      PROXY_ENABLED="false"
+      echo "已关闭加速，将直连 GitHub"
+      ;;
+    *)
+      PROXY_ENABLED="true"
+      read -p "加速地址 (默认 gcode.hostcentral.cc): " input_url
+      PROXY_URL="${input_url:-gcode.hostcentral.cc}"
+      echo "已开启加速: $PROXY_URL"
+      ;;
+  esac
+  echo "==============================================="
+}
+```
+
+- [x] **Step 2: 修改 install_flux_agent 函数添加询问**
+
+找到第 211-214 行：
+```bash
+# 安装功能
+install_flux_agent() {
+  echo "🚀 开始安装 flux_agent..."
+  get_config_params
+```
+
+替换为：
+```bash
+# 安装功能
+install_flux_agent() {
+  echo "🚀 开始安装 flux_agent..."
+
+  # 询问加速配置（如果未由面板传入）
+  ask_proxy_config
+
+  get_config_params
+```
+
+- [ ] **Step 3: 提交**
+
+```bash
+git add install.sh
+git commit -m "feat(script): add configurable github proxy for install.sh"
+```
+
+---
+
+## Task 5: 安装脚本 - panel_install.sh 修改
+
+**Files:**
+- Modify: `panel_install.sh`
+
+- [x] **Step 1: 添加环境变量声明和修改 maybe_proxy_url 函数**
+
+找到第 16-20 行：
+```bash
+# 镜像加速（所有下载均经过镜像源，以支持 IPv6）
+maybe_proxy_url() {
+  local url="$1"
+  echo "https://gcode.hostcentral.cc/${url}"
+}
+```
+
+替换为：
+```bash
+# 镜像加速配置（可由面板传入或交互式询问）
+PROXY_ENABLED="${PROXY_ENABLED:-}"
+PROXY_URL="${PROXY_URL:-}"
+
+# 镜像加速
+maybe_proxy_url() {
+  local url="$1"
+
+  # 如果明确关闭加速
+  if [[ "$PROXY_ENABLED" == "false" ]]; then
+    echo "$url"
+    return
+  fi
+
+  # 默认开启加速
+  local proxy="${PROXY_URL:-gcode.hostcentral.cc}"
+
+  # 处理 URL 格式
+  if [[ "$proxy" == https://* || "$proxy" == http://* ]]; then
+    proxy="${proxy%/}"
+  else
+    proxy="https://${proxy}"
+  fi
+
+  echo "${proxy}/${url}"
+}
+
+# 询问加速配置（如果未由面板传入）
+ask_proxy_config() {
+  if [[ -n "$PROXY_ENABLED" ]]; then
+    return
+  fi
+
+  echo ""
+  echo "==============================================="
+  echo "           GitHub 加速配置"
+  echo "==============================================="
+  read -p "是否开启 GitHub 加速? (Y/n): " proxy_choice
+  case "$proxy_choice" in
+    n|N)
+      PROXY_ENABLED="false"
+      echo "已关闭加速，将直连 GitHub"
+      ;;
+    *)
+      PROXY_ENABLED="true"
+      read -p "加速地址 (默认 gcode.hostcentral.cc): " input_url
+      PROXY_URL="${input_url:-gcode.hostcentral.cc}"
+      echo "已开启加速: $PROXY_URL"
+      ;;
+  esac
+  echo "==============================================="
+}
+```
+
+- [x] **Step 2: 修改 install_panel 函数添加询问**
+
+找到第 375-378 行：
+```bash
+# 安装功能
+install_panel() {
+  echo "🚀 开始安装面板..."
+  check_docker
+  get_config_params
+```
+
+替换为：
+```bash
+# 安装功能
+install_panel() {
+  echo "🚀 开始安装面板..."
+
+  # 询问加速配置（如果未由面板传入）
+  ask_proxy_config
+
+  check_docker
+  get_config_params
+```
+
+- [ ] **Step 3: 提交**
+
+```bash
+git add panel_install.sh
+git commit -m "feat(script): add configurable github proxy for panel_install.sh"
+```
+
+---
+
+## Task 6: 最终验证和提交
+
+- [x] **Step 1: 验证后端编译**
+
+Run: `cd go-backend && go build ./...`
+Expected: 编译成功
+
+- [x] **Step 2: 验证前端编译**
+
+Run: `cd vite-frontend && npm run build`
+Expected: 编译成功
+
+- [x] **Step 3: 验证脚本语法**
+
+Run: `bash -n install.sh && bash -n panel_install.sh && bash test-install-scripts-proxy.sh`
+Expected: 无语法错误，且脚本代理回归测试通过
+
+- [ ] **Step 4: 推送所有提交**
+
+```bash
+git push
+```
+
+---
+
+## 验收标准
+
+1. 面板设置页面显示 GitHub 加速配置项
+2. 开关关闭后，下载地址直连 GitHub
+3. 自定义加速地址后，节点更新和安装命令使用自定义地址
+4. 安装脚本支持交互式询问加速配置
+5. 面板生成的安装命令包含加速配置环境变量

docs/superpowers/plans/2026-04-03-commercial-white-label-plan.md

@@ -0,0 +1,220 @@
+# Commercial White-Label Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Allow users with a valid license key to activate commercial white-label features, enabling them to remove FLVX branding and use their own app name, logos, and footer.
+**Architecture:** Backend API handles license validation and stores state (`is_commercial`). Both frontend and backend check this state to conditionally render or allow modifications to brand config.
+**Tech Stack:** Go (Backend API), React + Vite (Frontend UI).
+
+---
+
+### Task 1: Backend License Activation Endpoint
+
+**Files:**
+- Modify: `go-backend/internal/http/handler/handler.go`
+
+- [ ] **Step 1: Add license request struct**
+Add the `licenseActivateRequest` struct in `handler.go`.
+
+```go
+type licenseActivateRequest struct {
+	LicenseKey string `json:"license_key"`
+}
+```
+
+- [ ] **Step 2: Add `licenseActivate` handler method**
+Add the method to validate the key in `handler.go`.
+
+```go
+func (h *Handler) licenseActivate(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		response.WriteJSON(w, response.ErrDefault("请求失败"))
+		return
+	}
+
+	var req licenseActivateRequest
+	if err := decodeJSON(r.Body, &req); err != nil {
+		response.WriteJSON(w, response.ErrDefault("授权码不能为空"))
+		return
+	}
+	
+	key := strings.TrimSpace(req.LicenseKey)
+	if !strings.HasPrefix(key, "FLVX-") {
+		response.WriteJSON(w, response.ErrDefault("无效的商业授权码"))
+		return
+	}
+
+	now := time.Now().UnixMilli()
+	if err := h.repo.UpsertConfig("license_key", key, now); err != nil {
+		response.WriteJSON(w, response.Err(-2, err.Error()))
+		return
+	}
+	if err := h.repo.UpsertConfig("is_commercial", "true", now); err != nil {
+		response.WriteJSON(w, response.Err(-2, err.Error()))
+		return
+	}
+
+	response.WriteJSON(w, response.OKEmpty())
+}
+```
+
+- [ ] **Step 3: Register the route**
+In `handler.go` inside `Register(mux *http.ServeMux)`, add the route.
+
+```go
+	mux.HandleFunc("/api/v1/license/activate", h.licenseActivate)
+```
+
+- [ ] **Step 4: Commit**
+```bash
+git add go-backend/internal/http/handler/handler.go
+git commit -m "feat: add license activation endpoint"
+```
+
+### Task 2: Backend Config Update Validation
+
+**Files:**
+- Modify: `go-backend/internal/http/handler/handler.go`
+
+- [ ] **Step 1: Add permission check in `updateConfigs`**
+In `updateConfigs`, fetch `isCommercial := h.repo.GetConfig("is_commercial")`. Inside the loop, check if the user is trying to update protected keys.
+
+```go
+	isCommercial, _ := h.repo.GetConfig("is_commercial")
+	protectedKeys := map[string]bool{
+		"app_name":          true,
+		"app_logo":          true,
+		"app_favicon":       true,
+		"hide_footer_brand": true,
+	}
+```
+Inside `for k, v := range payload`:
+```go
+		if protectedKeys[key] && isCommercial.Value != "true" {
+			response.WriteJSON(w, response.ErrDefault("需要商业版授权"))
+			return
+		}
+```
+
+- [ ] **Step 2: Add permission check in `updateSingleConfig`**
+In `updateSingleConfig`, do the same check before calling `normalizeAndValidateConfigValue`.
+
+```go
+	isCommercial, _ := h.repo.GetConfig("is_commercial")
+	if (name == "app_name" || name == "app_logo" || name == "app_favicon" || name == "hide_footer_brand") && isCommercial.Value != "true" {
+		response.WriteJSON(w, response.ErrDefault("需要商业版授权"))
+		return
+	}
+```
+
+- [ ] **Step 3: Commit**
+```bash
+git add go-backend/internal/http/handler/handler.go
+git commit -m "feat: add authorization check for commercial config keys"
+```
+
+### Task 3: Frontend API & Site Config Update
+
+**Files:**
+- Modify: `vite-frontend/src/api/index.ts`
+- Modify: `vite-frontend/src/config/site.ts`
+
+- [ ] **Step 1: Add `activateLicense` API**
+In `vite-frontend/src/api/index.ts`:
+
+```typescript
+export const activateLicense = (licenseKey: string) =>
+  Network.post("/license/activate", { license_key: licenseKey });
+```
+
+- [ ] **Step 2: Update `siteConfig` defaults**
+In `vite-frontend/src/config/site.ts`, inside `getInitialConfig()`, add properties.
+
+```typescript
+    app_logo: cachedAppLogo,
+    app_favicon: cachedAppFavicon,
+    is_commercial: configCache.get("is_commercial") === "true",
+    hide_footer_brand: configCache.get("hide_footer_brand") === "true",
+```
+
+- [ ] **Step 3: Update `updateSiteConfig`**
+In `updateSiteConfig` inside `site.ts`, extract and update `is_commercial` and `hide_footer_brand`.
+
+```typescript
+  const isCommercial = resolvedConfigMap.is_commercial === "true";
+  const hideFooterBrand = resolvedConfigMap.hide_footer_brand === "true";
+  siteConfig.is_commercial = isCommercial;
+  siteConfig.hide_footer_brand = hideFooterBrand;
+```
+
+- [ ] **Step 4: Commit**
+```bash
+git add vite-frontend/src/api/index.ts vite-frontend/src/config/site.ts
+git commit -m "feat: add frontend api and update site config state for license"
+```
+
+### Task 4: Frontend Footer Component Update
+
+**Files:**
+- Modify: `vite-frontend/src/components/version-footer.tsx`
+
+- [ ] **Step 1: Conditionally hide "Powered by FLVX"**
+In the render block, wrap the `Powered by FLVX` text.
+
+```tsx
+      {siteConfig.hide_footer_brand !== true && (
+        <p className={poweredClassName}>
+          Powered by{" "}
+          <a
+            className="text-gray-500 dark:text-gray-400 hover:text-gray-600 dark:hover:text-gray-300 transition-colors"
+            href={siteConfig.github_repo}
+            rel="noopener noreferrer"
+            target="_blank"
+          >
+            FLVX
+          </a>
+        </p>
+      )}
+```
+
+- [ ] **Step 2: Commit**
+```bash
+git add vite-frontend/src/components/version-footer.tsx
+git commit -m "feat: conditionally hide flvx footer brand"
+```
+
+### Task 5: Frontend Settings Page UI Update
+
+**Files:**
+- Modify: `vite-frontend/src/pages/config.tsx`
+
+- [ ] **Step 1: Add config keys to initialization**
+In `getInitialConfigs`, add `"is_commercial"` and `"hide_footer_brand"` to `configKeys`.
+
+- [ ] **Step 2: Add `hide_footer_brand` switch field**
+Add it to the `CONFIG_ITEMS` array.
+
+```typescript
+  {
+    key: "hide_footer_brand",
+    label: "隐藏页面底部 FLVX 版权信息",
+    description: "需商业版授权才能生效",
+    type: "switch",
+  },
+```
+
+- [ ] **Step 3: Add license activation UI**
+Above the System Config Card (near `value="configs"`), add a new `Card` for "商业版授权". You will need a local state `licenseKey` and an `handleActivateLicense` function that calls `activateLicense(licenseKey)` and refetches configs on success. 
+
+- [ ] **Step 4: Disable brand settings when not commercial**
+In `renderConfigItem`, compute `isDisabled` and pass it to the `<Input>`, `<Switch>`, and `BrandUploading` UI. Update the logic to disable modifications and add a lock icon or a tooltip explaining that a commercial license is required.
+
+```typescript
+const isCommercialDisabled = ["app_name", "app_logo", "app_favicon", "hide_footer_brand"].includes(item.key) && configs.is_commercial !== "true";
+```
+
+- [ ] **Step 5: Commit**
+```bash
+git add vite-frontend/src/pages/config.tsx
+git commit -m "feat: ui settings for commercial white-label and license activation"
+```

docs/superpowers/plans/2026-04-03-keygen-integration-plan.md

@@ -0,0 +1,347 @@
+# Commercial White-Label (Keygen) Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Implement Keygen.sh license activation and periodic validation to manage commercial white-label features, replacing the temporary mock logic.
+**Architecture:** The backend generates a machine fingerprint, validates the license via the Keygen.sh API, and creates a machine associated with the license. A periodic job verifies the license status to support remote revocation.
+**Tech Stack:** Go (Backend API), Keygen.sh API.
+
+---
+
+### Task 1: Generate and Store Machine Fingerprint
+
+**Files:**
+- Modify: `go-backend/internal/http/handler/handler.go`
+
+- [ ] **Step 1: Add `getOrCreateMachineFingerprint` helper function**
+Add a helper function in `handler.go` (or a dedicated license file) to get or generate the machine fingerprint. Use `github.com/google/uuid`.
+
+```go
+import "github.com/google/uuid"
+
+func (h *Handler) getOrCreateMachineFingerprint() (string, error) {
+	fp, _ := h.repo.GetViteConfigValue("machine_fingerprint")
+	if fp != "" {
+		return fp, nil
+	}
+
+	newFp := uuid.New().String()
+	now := time.Now().UnixMilli()
+	if err := h.repo.UpsertConfig("machine_fingerprint", newFp, now); err != nil {
+		return "", err
+	}
+	return newFp, nil
+}
+```
+
+- [ ] **Step 2: Commit**
+```bash
+git add go-backend/internal/http/handler/handler.go
+git commit -m "feat: add machine fingerprint generation"
+```
+
+### Task 2: Create Keygen Client Package
+
+**Files:**
+- Create: `go-backend/internal/license/keygen.go`
+
+- [ ] **Step 1: Create Keygen client structs and interface**
+Create the file and define the request/response structs for Keygen's `/licenses/actions/validate-key` and `/machines` endpoints. Also define an interface for the client.
+
+```go
+package license
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"time"
+)
+
+type KeygenClient struct {
+	AccountID string
+	Token     string
+	HTTPClient *http.Client
+}
+
+func NewKeygenClient(accountID, token string) *KeygenClient {
+	return &KeygenClient{
+		AccountID: accountID,
+		Token:     token,
+		HTTPClient: &http.Client{Timeout: 10 * time.Second},
+	}
+}
+
+type ValidateResponse struct {
+	Meta struct {
+		Valid bool   `json:"valid"`
+		Code  string `json:"code"`
+	} `json:"meta"`
+	Data struct {
+		ID string `json:"id"`
+	} `json:"data"`
+}
+
+type ActivateMachineRequest struct {
+	Data struct {
+		Type       string `json:"type"`
+		Attributes struct {
+			Fingerprint string `json:"fingerprint"`
+		} `json:"attributes"`
+		Relationships struct {
+			License struct {
+				Data struct {
+					Type string `json:"type"`
+					ID   string `json:"id"`
+				} `json:"data"`
+			} `json:"license"`
+		} `json:"relationships"`
+	} `json:"data"`
+}
+```
+
+- [ ] **Step 2: Implement `ValidateKey`**
+Add the `ValidateKey` method.
+
+```go
+func (c *KeygenClient) ValidateKey(key string) (*ValidateResponse, error) {
+	url := fmt.Sprintf("https://api.keygen.sh/v1/accounts/%s/licenses/actions/validate-key", c.AccountID)
+	
+	reqBody := map[string]interface{}{
+		"meta": map[string]string{
+			"key": key,
+		},
+	}
+	bodyBytes, _ := json.Marshal(reqBody)
+
+	req, _ := http.NewRequest(http.MethodPost, url, bytes.NewBuffer(bodyBytes))
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Accept", "application/json")
+	if c.Token != "" {
+		req.Header.Set("Authorization", "Bearer "+c.Token)
+	}
+
+	resp, err := c.HTTPClient.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("keygen api error: status %d", resp.StatusCode)
+	}
+
+	var valResp ValidateResponse
+	if err := json.NewDecoder(resp.Body).Decode(&valResp); err != nil {
+		return nil, err
+	}
+
+	return &valResp, nil
+}
+```
+
+- [ ] **Step 3: Implement `ActivateMachine`**
+Add the `ActivateMachine` method.
+
+```go
+func (c *KeygenClient) ActivateMachine(licenseID, fingerprint string) error {
+	url := fmt.Sprintf("https://api.keygen.sh/v1/accounts/%s/machines", c.AccountID)
+	
+	var reqBody ActivateMachineRequest
+	reqBody.Data.Type = "machines"
+	reqBody.Data.Attributes.Fingerprint = fingerprint
+	reqBody.Data.Relationships.License.Data.Type = "licenses"
+	reqBody.Data.Relationships.License.Data.ID = licenseID
+
+	bodyBytes, _ := json.Marshal(reqBody)
+
+	req, _ := http.NewRequest(http.MethodPost, url, bytes.NewBuffer(bodyBytes))
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Accept", "application/json")
+	if c.Token != "" {
+		req.Header.Set("Authorization", "Bearer "+c.Token)
+	}
+
+	resp, err := c.HTTPClient.Do(req)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode == http.StatusCreated || resp.StatusCode == http.StatusOK {
+		return nil
+	}
+
+	if resp.StatusCode == http.StatusConflict { // 409 usually means fingerprint already exists
+		return nil // Machine might already be registered
+	}
+
+	body, _ := io.ReadAll(resp.Body)
+	return fmt.Errorf("failed to activate machine: status %d, response: %s", resp.StatusCode, string(body))
+}
+```
+
+- [ ] **Step 4: Commit**
+```bash
+git add go-backend/internal/license/keygen.go
+git commit -m "feat: add keygen.sh api client"
+```
+
+### Task 3: Integrate Keygen into License Activation Endpoint
+
+**Files:**
+- Modify: `go-backend/internal/http/handler/handler.go`
+
+- [ ] **Step 1: Update `licenseActivate` logic**
+Modify `licenseActivate` to use the Keygen client instead of the mock logic. Note: For this implementation, we will use an environment variable `KEYGEN_ACCOUNT_ID`. We can use `os.Getenv` directly for simplicity, or hardcode a fallback if not present.
+
+```go
+import (
+	"go-backend/internal/license"
+	"os"
+)
+
+func (h *Handler) licenseActivate(w http.ResponseWriter, r *http.Request) {
+	// ... (keep request parsing)
+
+	key := strings.TrimSpace(req.LicenseKey)
+	if key == "" {
+		response.WriteJSON(w, response.ErrDefault("授权码不能为空"))
+		return
+	}
+
+	accountID := os.Getenv("KEYGEN_ACCOUNT_ID")
+	if accountID == "" {
+		// Fallback for mock/development if no keygen account configured
+		if strings.HasPrefix(key, "FLVX-") {
+			now := time.Now().UnixMilli()
+			h.repo.UpsertConfig("license_key", key, now)
+			h.repo.UpsertConfig("is_commercial", "true", now)
+			response.WriteJSON(w, response.OKEmpty())
+			return
+		}
+		response.WriteJSON(w, response.ErrDefault("系统未配置 Keygen 账号 ID"))
+		return
+	}
+
+	fingerprint, err := h.getOrCreateMachineFingerprint()
+	if err != nil {
+		response.WriteJSON(w, response.ErrDefault("生成设备指纹失败"))
+		return
+	}
+
+	client := license.NewKeygenClient(accountID, "") // Token may be optional for validate-key depending on policy, or can be passed if needed
+	
+	valResp, err := client.ValidateKey(key)
+	if err != nil {
+		response.WriteJSON(w, response.ErrDefault("连接授权服务器失败: "+err.Error()))
+		return
+	}
+
+	if !valResp.Meta.Valid {
+		response.WriteJSON(w, response.ErrDefault("授权码无效或已过期 (Code: "+valResp.Meta.Code+")"))
+		return
+	}
+
+	// Try to activate machine
+	err = client.ActivateMachine(valResp.Data.ID, fingerprint)
+	if err != nil {
+		response.WriteJSON(w, response.ErrDefault("设备绑定失败: "+err.Error()))
+		return
+	}
+
+	now := time.Now().UnixMilli()
+	if err := h.repo.UpsertConfig("license_key", key, now); err != nil {
+		response.WriteJSON(w, response.Err(-2, err.Error()))
+		return
+	}
+	if err := h.repo.UpsertConfig("is_commercial", "true", now); err != nil {
+		response.WriteJSON(w, response.Err(-2, err.Error()))
+		return
+	}
+
+	response.WriteJSON(w, response.OKEmpty())
+}
+```
+
+- [ ] **Step 2: Commit**
+```bash
+git add go-backend/internal/http/handler/handler.go
+git commit -m "feat: integrate keygen into license activation endpoint"
+```
+
+### Task 4: Add Periodic License Validation Job
+
+**Files:**
+- Modify: `go-backend/internal/http/handler/jobs.go`
+- Modify: `go-backend/internal/http/handler/handler.go`
+
+- [ ] **Step 1: Add `validateLicenseJob` function in `jobs.go`**
+Create a new function that performs the background validation.
+
+```go
+import "os"
+
+func (h *Handler) validateLicenseJob() {
+	if h == nil || h.repo == nil {
+		return
+	}
+
+	accountID := os.Getenv("KEYGEN_ACCOUNT_ID")
+	if accountID == "" {
+		return // Skip if not configured
+	}
+
+	key, _ := h.repo.GetViteConfigValue("license_key")
+	isCommercial, _ := h.repo.GetViteConfigValue("is_commercial")
+
+	if key == "" || isCommercial != "true" {
+		return // Nothing to validate
+	}
+
+	client := license.NewKeygenClient(accountID, "")
+	valResp, err := client.ValidateKey(key)
+	
+	if err != nil {
+		// Network error or timeout. We implement a grace period by NOT revoking immediately here.
+		// In a production system, you might count consecutive failures.
+		// For now, we skip revocation on network errors.
+		return
+	}
+
+	if !valResp.Meta.Valid {
+		// License is invalid (e.g., revoked, suspended, expired). Downgrade the system.
+		now := time.Now().UnixMilli()
+		_ = h.repo.UpsertConfig("is_commercial", "false", now)
+		// We could optionally clear brand configs here, or just let them be disabled in UI
+	}
+}
+```
+
+- [ ] **Step 2: Register the job in `RunJobs`**
+In `handler.go` or `jobs.go`, wherever the periodic cron jobs are registered (usually `go h.runJobs()`), ensure `validateLicenseJob` is called periodically (e.g., every 12 hours). Look for `h.startCronJobs()` or similar in `handler.go`. 
+
+If a central `RunJobs` loop exists in `jobs.go` (like a `for` loop with a `time.Ticker`), add it there. If not, create a simple goroutine in `Register` or `NewHandler`.
+
+*Assuming there's a `startJobs` or `Init` block in `handler.go`:*
+```go
+// Inside handler initialization or Register:
+go func() {
+	ticker := time.NewTicker(12 * time.Hour)
+	defer ticker.Stop()
+	for {
+		select {
+		case <-ticker.C:
+			h.validateLicenseJob()
+		}
+	}
+}()
+```
+
+- [ ] **Step 3: Commit**
+```bash
+git add go-backend/internal/http/handler/jobs.go go-backend/internal/http/handler/handler.go
+git commit -m "feat: add periodic license validation job"
+```

docs/superpowers/plans/2026-04-04-announcement-popup-plan.md

@@ -0,0 +1,262 @@
+# Announcement Popup Notification Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add a popup modal for announcements that automatically shows to users when a new or updated announcement is published.
+
+**Architecture:** We will modify the Go backend to return `update_time` along with the announcement data. In the Vite frontend, we will store the user's `flvx_announcement_seen_time` in `localStorage`. If the fetched `update_time` is greater than the stored timestamp, we trigger a NextUI Modal displaying the announcement content.
+
+**Tech Stack:** Go, Vite, React, TailwindCSS, NextUI.
+
+---
+
+### Task 1: Update API Response in Go Backend
+
+**Files:**
+- Modify: `go-backend/internal/http/handler/handler.go`
+
+- [ ] **Step 1: Write the minimal implementation**
+
+Modify the `getAnnouncement` function in `go-backend/internal/http/handler/handler.go`. 
+Find the response map inside `getAnnouncement` and add the `update_time` key:
+
+```go
+	if ann == nil {
+		response.WriteJSON(w, response.OK(map[string]interface{}{
+			"content":     "",
+			"enabled":     0,
+			"update_time": 0,
+		}))
+		return
+	}
+
+	updateTime := ann.CreatedTime
+	if ann.UpdatedTime.Valid {
+		updateTime = ann.UpdatedTime.Int64
+	}
+
+	response.WriteJSON(w, response.OK(map[string]interface{}{
+		"content":     ann.Content,
+		"enabled":     ann.Enabled,
+		"update_time": updateTime,
+	}))
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add go-backend/internal/http/handler/handler.go
+git commit -m "feat(api): include update_time in announcement response"
+```
+
+---
+
+### Task 2: Update Frontend API Interface
+
+**Files:**
+- Modify: `vite-frontend/src/api/index.ts`
+
+- [ ] **Step 1: Write the minimal implementation**
+
+Modify the `AnnouncementData` interface in `vite-frontend/src/api/index.ts` to include `update_time`.
+
+```typescript
+export interface AnnouncementData {
+  content: string;
+  enabled: number;
+  update_time?: number;
+}
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add vite-frontend/src/api/index.ts
+git commit -m "feat(ui): add update_time to AnnouncementData interface"
+```
+
+---
+
+### Task 3: Create AnnouncementModal Component
+
+**Files:**
+- Create: `vite-frontend/src/pages/dashboard/components/announcement-modal.tsx`
+
+- [ ] **Step 1: Write the minimal implementation**
+
+Create `vite-frontend/src/pages/dashboard/components/announcement-modal.tsx` with the following content:
+
+```tsx
+import type { AnnouncementData } from "@/api";
+import { Button } from "@/shadcn-bridge/heroui/button";
+import {
+  Modal,
+  ModalBody,
+  ModalContent,
+  ModalFooter,
+  ModalHeader,
+} from "@/shadcn-bridge/heroui/modal";
+import ReactMarkdown from "react-markdown";
+import remarkGfm from "remark-gfm";
+
+interface AnnouncementModalProps {
+  announcement: AnnouncementData;
+  isOpen: boolean;
+  onClose: () => void;
+  onDontShowAgain: () => void;
+}
+
+export const AnnouncementModal = ({
+  announcement,
+  isOpen,
+  onClose,
+  onDontShowAgain,
+}: AnnouncementModalProps) => {
+  return (
+    <Modal isOpen={isOpen} onOpenChange={(open) => !open && onClose()} size="2xl">
+      <ModalContent>
+        <ModalHeader className="flex flex-col gap-1">平台公告</ModalHeader>
+        <ModalBody>
+          <div className="prose prose-sm dark:prose-invert max-w-none max-h-[60vh] overflow-y-auto">
+            <ReactMarkdown remarkPlugins={[remarkGfm]}>
+              {announcement.content}
+            </ReactMarkdown>
+          </div>
+        </ModalBody>
+        <ModalFooter>
+          <Button variant="flat" onPress={onDontShowAgain}>
+            不再提示
+          </Button>
+          <Button color="primary" onPress={onClose}>
+            关闭
+          </Button>
+        </ModalFooter>
+      </ModalContent>
+    </Modal>
+  );
+};
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add vite-frontend/src/pages/dashboard/components/announcement-modal.tsx
+git commit -m "feat(ui): create AnnouncementModal component"
+```
+
+---
+
+### Task 4: Integrate Modal State in Dashboard Custom Hook
+
+**Files:**
+- Modify: `vite-frontend/src/pages/dashboard/use-dashboard-data.ts`
+
+- [ ] **Step 1: Update the hook return type interface**
+
+At the top of `vite-frontend/src/pages/dashboard/use-dashboard-data.ts` where `DashboardData` is or similar, add the new properties (if it uses an explicit return type). If it's inferred, skip this. Wait, let's check the code:
+
+```typescript
+  isAnnouncementModalOpen: boolean;
+  setIsAnnouncementModalOpen: (isOpen: boolean) => void;
+  dismissAnnouncementModal: () => void;
+```
+Ensure they are added to the returned object at the bottom of the `useDashboardData` hook.
+
+Find the `const loadAnnouncement` function. 
+
+- [ ] **Step 2: Write the minimal implementation**
+
+First, add state at the top of the hook:
+```typescript
+  const [isAnnouncementModalOpen, setIsAnnouncementModalOpen] = useState(false);
+```
+
+Then, modify the `loadAnnouncement` logic inside `useDashboardData`:
+```typescript
+      if (res.code === 0 && res.data && res.data.enabled === 1) {
+        setAnnouncement(res.data);
+        
+        try {
+          const storedTimeStr = localStorage.getItem("flvx_announcement_seen_time");
+          const storedTime = storedTimeStr ? parseInt(storedTimeStr, 10) : 0;
+          const updateTime = res.data.update_time || 0;
+          
+          if (updateTime > storedTime) {
+            setIsAnnouncementModalOpen(true);
+          }
+        } catch (err) {
+          console.warn("Failed to read localStorage for announcement state", err);
+          setIsAnnouncementModalOpen(true);
+        }
+      } else {
+        setAnnouncement(null);
+      }
+```
+
+Add the dismiss handler inside the hook:
+```typescript
+  const dismissAnnouncementModal = useCallback(() => {
+    setIsAnnouncementModalOpen(false);
+    if (announcement && announcement.update_time) {
+      try {
+        localStorage.setItem("flvx_announcement_seen_time", announcement.update_time.toString());
+      } catch (err) {
+        console.warn("Failed to set localStorage for announcement state", err);
+      }
+    }
+  }, [announcement]);
+```
+
+Ensure these are included in the return object of the hook:
+```typescript
+    isAnnouncementModalOpen,
+    setIsAnnouncementModalOpen,
+    dismissAnnouncementModal,
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add vite-frontend/src/pages/dashboard/use-dashboard-data.ts
+git commit -m "feat(ui): manage announcement modal state in dashboard hook"
+```
+
+---
+
+### Task 5: Add Modal to Dashboard Layout
+
+**Files:**
+- Modify: `vite-frontend/src/pages/dashboard.tsx`
+
+- [ ] **Step 1: Write the minimal implementation**
+
+Import the modal component at the top:
+```tsx
+import { AnnouncementModal } from "@/pages/dashboard/components/announcement-modal";
+```
+
+Add the new properties to the destructured `useDashboardData` object:
+```tsx
+    isAnnouncementModalOpen,
+    setIsAnnouncementModalOpen,
+    dismissAnnouncementModal,
+```
+
+Add the modal instance near the end of the dashboard rendering (just below `{announcement && <AnnouncementBanner ... />}` or inside the main `<div>`):
+```tsx
+      {announcement && (
+        <AnnouncementModal
+          announcement={announcement}
+          isOpen={isAnnouncementModalOpen}
+          onClose={() => setIsAnnouncementModalOpen(false)}
+          onDontShowAgain={dismissAnnouncementModal}
+        />
+      )}
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add vite-frontend/src/pages/dashboard.tsx
+git commit -m "feat(ui): add announcement modal to dashboard layout"
+```

docs/superpowers/plans/2026-04-04-flvx-ios26-redesign-plan.md

@@ -0,0 +1,140 @@
+# Flvx iOS 26 Liquid Glass UI Redesign Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Transform the Flvx frontend interface entirely into an "Apple iOS 26 Liquid Glass" visual style by utilizing high-radius squircles, heavy background blurs, mesh gradients, and highly semantic translucent containers.
+
+**Architecture:** We will approach this from the ground up: first defining the global TailwindCSS design tokens and the base mesh-gradient layout, then systematically replacing the structural styling inside each React page component (`vite-frontend/src/pages/*.tsx`).
+
+**Tech Stack:** React DOM, TailwindCSS (v4), shadcn-bridge (HeroUI), Vite
+
+---
+
+### Task 1: Setup Global CSS Variables and App Shell
+
+**Files:**
+- Modify: `vite-frontend/src/styles/globals.css` (or `index.css`)
+- Modify: `vite-frontend/tailwind.config.js`
+- Modify: `vite-frontend/src/App.tsx` (or `main.tsx` / `layouts` depending on structural entry point)
+
+- [ ] **Step 1: Inject Liquid Glass theme variables**
+  Open the main CSS file and add variables for the new blur radius, box-shadows, and background gradients.
+  ```css
+  :root {
+    --glass-bg: rgba(255, 255, 255, 0.6);
+    --glass-border: rgba(255, 255, 255, 0.8);
+    --glass-card: rgba(255, 255, 255, 0.7);
+    --glass-overlay: rgba(0, 0, 0, 0.3);
+  }
+  .dark {
+    --glass-bg: rgba(30, 30, 30, 0.6);
+    --glass-border: rgba(255, 255, 255, 0.15);
+    --glass-card: rgba(40, 40, 40, 0.6);
+  }
+  .bg-mesh-gradient {
+    background: radial-gradient(at 0% 0%, #ff9a9e 0%, transparent 50%),
+                radial-gradient(at 100% 0%, #fecfef 0%, transparent 50%),
+                radial-gradient(at 100% 100%, #c2e9fb 0%, transparent 50%),
+                radial-gradient(at 0% 100%, #a1c4fd 0%, transparent 50%);
+    background-color: #f2f2f7;
+  }
+  ```
+
+- [ ] **Step 2: Update App Layout**
+  Modify the root app container to use `.bg-mesh-gradient` and ensure the main container occupies `min-h-screen`.
+
+### Task 2: Refactor Global Components (Card & Modal)
+
+**Files:**
+- Modify: `vite-frontend/src/shadcn-bridge/heroui/card.tsx`
+- Modify: `vite-frontend/src/shadcn-bridge/heroui/modal.tsx`
+
+- [ ] **Step 1: Liquid Card Base**
+  Update the default className string for `Card` to incorporate: `backdrop-blur-3xl bg-white/60 dark:bg-zinc-900/60 border border-white/80 dark:border-white/10 rounded-2xl shadow-[0_10px_30px_rgba(0,0,0,0.1)]`.
+
+- [ ] **Step 2: Modal Overlay Base**
+  Update the default overlay className for `Modal` to use `bg-black/30 backdrop-blur-sm`, and its content panel to use the same `glass_card` classes as the Card component but with `rounded-3xl`.
+
+### Task 3: Redesign Dashboard Page
+
+**Files:**
+- Modify: `vite-frontend/src/pages/dashboard.tsx`
+
+- [ ] **Step 1: Replace hardcoded borders/bg with glass semantics**
+  Find hardcoded `bg-white`, `border-gray-200`, `shadow-md` inside `DashboardPage` and `MetricCard`, replace with `bg-white/60 backdrop-blur-3xl shadow-[0_10px_30px_rgba(0,0,0,0.1)] border-white/80 rounded-2xl`.
+- [ ] **Step 2: Adjust spacing**
+  Ensure all metric cards have uniform `h-48` equivalent height and are strictly `rounded-2xl` with `p-6` padding.
+- [ ] **Step 3: Update Flow Chart Card**
+  Replace standard grid backgrounds in the flow chart with transparent spacing and vibrant `bg-blue-500` squircle bars without harsh borders.
+
+### Task 4: Redesign Node Management Page
+
+**Files:**
+- Modify: `vite-frontend/src/pages/node.tsx`
+
+- [ ] **Step 1: Replace standard List/Table view with Grid Cards**
+  Update the node rendering map to output `glass_card` containers (`rounded-2xl`, blur, padding `p-6`).
+- [ ] **Step 2: Apply semantic status highlights**
+  Refactor the Online/Offline badges into pill-shapes (`rounded-full`) using the defined semantic colors (e.g. `bg-green-500/20 text-green-600` with a 6px inner dot `bg-green-500`).
+- [ ] **Step 3: Embed Micro-charts**
+  For CPU/RAM data inside the node card, switch standard progress bars to ultra-thin (height 4px) continuous lines utilizing standard brand colors.
+
+### Task 5: Redesign Tunnels & Rules Configuration
+
+**Files:**
+- Modify: `vite-frontend/src/pages/tunnel.tsx`
+- Modify: `vite-frontend/src/pages/forward.tsx`
+
+- [ ] **Step 1: Update Tunnel lists into nested Glass Panels**
+  Encapsulate each tunnel configuration into a wide `glass_card`.
+- [ ] **Step 2: Create Visual Rule Tags**
+  For the Forwarding rules, wrap the target IP/Port logic into visual badges: `bg-green-500/20` for Entry and `bg-blue-500/20` for Target.
+- [ ] **Step 3: Refactor the "Add Rule" Floating action**
+  Ensure the plus button follows the squircle format (`rounded-full`) with a prominent diffused shadow (`shadow-[0_4px_12px_rgba(0,122,255,0.3)]`).
+
+### Task 6: Redesign Monitor Page
+
+**Files:**
+- Modify: `vite-frontend/src/pages/monitor.tsx`
+
+- [ ] **Step 1: Style the Top Hero Metrics**
+  Replace flat stat boxes with high-contrast, large typography inside `glass_card` backgrounds.
+- [ ] **Step 2: Refactor Latency Indicators**
+  Format the connection list rows as `bg-white/50 dark:bg-black/30` strips with pill-shaped status tags (`Healthy`, `Warning`, `Offline`) mapping exactly to the green/orange/red semantics from the design spec.
+
+### Task 7: Redesign Group & Sharing Pages
+
+**Files:**
+- Modify: `vite-frontend/src/pages/group.tsx`
+- Modify: `vite-frontend/src/pages/panel-sharing.tsx`
+
+- [ ] **Step 1: Update Tab Switchers**
+  Refactor the internal navigation tabs (e.g., "Tunnel Groups" vs "User Groups") into an encapsulated `p-1 rounded-xl bg-white/40 backdrop-blur-lg` container with animated active states (`shadow-sm bg-white`).
+- [ ] **Step 2: Style Share Cards**
+  Transform flat panel sharing list items into rich `glass_card` entities. Highlight expiration dates with the accent text color.
+
+### Task 8: Redesign Settings, Config, and User Management
+
+**Files:**
+- Modify: `vite-frontend/src/pages/config.tsx`
+- Modify: `vite-frontend/src/pages/settings.tsx`
+- Modify: `vite-frontend/src/pages/user.tsx`
+- Modify: `vite-frontend/src/pages/limit.tsx`
+
+- [ ] **Step 1: Flatten Forms**
+  Convert traditional input groups into `rounded-xl bg-white/50 border border-white/60` containers. Remove outer boxing for standard `label + input` pairs.
+- [ ] **Step 2: iOS Toggle Switches**
+  Ensure that any `<Switch>` or `<Checkbox>` components use the new Accent brand color (`#007aff`) with full `rounded-full` geometry.
+- [ ] **Step 3: Refactor User Badges**
+  In `user.tsx`, replace text-based role columns with circular Avatar badges (e.g., `w-10 h-10 rounded-full bg-blue-500 text-white` with the first two letters of the username).
+
+### Task 9: Profile & Password Modal Restyling
+
+**Files:**
+- Modify: `vite-frontend/src/pages/profile.tsx`
+- Modify: `vite-frontend/src/pages/change-password.tsx`
+
+- [ ] **Step 1: Apply Profile Card Structure**
+  Create a split view on desktop using flex: Left side (Avatar + User Info + Admin Shortcuts), Right side (Password Form).
+- [ ] **Step 2: Restyle Auth Inputs**
+  Ensure all password inputs use `bg-white/50 backdrop-blur-md border border-white/60` and the update button has heavy shadow-glow.

docs/superpowers/plans/2026-04-23-max-conn-limit.md

@@ -0,0 +1,482 @@
+# 最大连接数限制实现计划
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`[x]`) syntax for tracking.
+
+**Goal:** 在 FLVX 中实现基于用户的全局最大连接数限制和基于单条规则的独立最大连接数限制功能。前端输入框为 0 或空时表示不限制。
+
+**Architecture:** 采用“覆盖逻辑”（方案二）。
+1. 数据库层面：在 `user` 和 `forward` 表中各增加一个整型字段 `max_conn`，默认值为 0（表示不限制）。
+2. 后端接口层面：提供 API 更新该字段，在组装下发给 GOST 的配置时，判断规则的 `max_conn` 是否大于 0：
+   - 如果规则 `max_conn > 0`，则为此规则动态生成一个唯一的连接限制器配置，并在下发服务的 `climiter` 字段中引用该限制器。
+   - 如果规则 `max_conn == 0`，则检查该规则所属用户的 `max_conn`。
+   - 如果用户 `max_conn > 0`，则引用以用户维度的连接限制器配置（如 `user_conn_limit_<user_id>`）。
+   - 否则不下发 `climiter`。
+3. 后端服务控制平面：需要在下发服务前，将需要的连接限制器（Rule 或 User 维度）推送到节点上。
+   - **重要发现：** 当前 `go-gost` 的 WebSocket Reporter (`go-gost/x/socket/websocket_reporter.go`) 仅支持 `TrafficLimiter` 的动态增删（如 `AddLimiters` 等），**不支持** `ConnLimiter`（即 `CLimiters`）。
+   - **计划修改：** 我们需要先在 `go-gost` 侧（`go-gost/x/socket`）添加针对 `CLimiters` 的 WebSocket 指令（`AddCLimiters`, `UpdateCLimiters`, `DeleteCLimiters`）以及对应的处理函数（参考 `AddLimiters` 等的实现，调用现有的针对 `ConnLimiterRegistry` 的相关接口和配置存储逻辑，具体需要实现类似 `createLimiter` 到 `createConnLimiter` 的逻辑）。
+   - 完成底层修改后，`go-backend` 再通过这些新增加的 WebSocket 指令，在 `ensureLimiterOnNode` 时下发最大连接数限制规则。
+4. 前端层面：在用户管理和规则管理页面增加输入框组件。
+
+**Tech Stack:** Go, GORM, SQLite/PostgreSQL, React, Vite, TypeScript, TailwindCSS.
+
+---
+
+### Task 1: 扩展 go-gost WebSocket 接口以支持 CLimiters
+
+**Files:**
+- Modify: `go-gost/x/socket/limiter.go`
+- Modify: `go-gost/x/socket/websocket_reporter.go`
+
+[x] **Step 1: 实现 `createConnLimiter` 等功能**
+
+在 `go-gost/x/socket/limiter.go` 中参考现有 `createLimiter` 添加对 `CLimiters` 的支持：
+
+```go
+func createConnLimiter(req createLimiterRequest) error {
+	name := strings.TrimSpace(req.Data.Name)
+	if name == "" {
+		return errors.New("limiter name is required")
+	}
+	req.Data.Name = name
+
+	if registry.ConnLimiterRegistry().IsRegistered(name) {
+		return errors.New("conn limiter " + name + " already exists")
+	}
+
+	v := parser.ParseConnLimiter(&req.Data)
+
+	if err := registry.ConnLimiterRegistry().Register(name, v); err != nil {
+		return errors.New("conn limiter " + name + " already exists")
+	}
+
+	if c := config.Global(); c != nil {
+		c.CLimiters = append(c.CLimiters, &req.Data)
+	}
+	return nil
+}
+
+func updateConnLimiter(req updateLimiterRequest) error {
+	name := strings.TrimSpace(req.Limiter)
+	req.Data.Name = name
+	if registry.ConnLimiterRegistry().IsRegistered(name) {
+		registry.ConnLimiterRegistry().Unregister(name)
+	}
+
+	v := parser.ParseConnLimiter(&req.Data)
+
+	if err := registry.ConnLimiterRegistry().Register(name, v); err != nil {
+		return errors.New("conn limiter " + name + " already exists")
+	}
+
+	if c := config.Global(); c != nil {
+		for i := range c.CLimiters {
+			if c.CLimiters[i].Name == name {
+				c.CLimiters[i] = &req.Data
+				return nil
+			}
+		}
+		c.CLimiters = append(c.CLimiters, &req.Data)
+	}
+	return nil
+}
+
+func deleteConnLimiter(req deleteLimiterRequest) error {
+	name := strings.TrimSpace(req.Limiter)
+
+	if registry.ConnLimiterRegistry().IsRegistered(name) {
+		registry.ConnLimiterRegistry().Unregister(name)
+	}
+
+	if c := config.Global(); c != nil {
+		limiteres := c.CLimiters
+		c.CLimiters = nil
+		for _, s := range limiteres {
+			if s.Name == name {
+				continue
+			}
+			c.CLimiters = append(c.CLimiters, s)
+		}
+	}
+	return nil
+}
+```
+
+[x] **Step 2: 在 `WebSocketReporter` 注册命令**
+
+在 `go-gost/x/socket/websocket_reporter.go` 的 `ProcessCommand` 中添加 case：
+
+```go
+	case "AddCLimiters":
+		err = w.handleAddCLimiter(cmd.Data)
+		response.Type = "AddCLimitersResponse"
+		needSaveConfig = true
+	case "UpdateCLimiters":
+		err = w.handleUpdateCLimiter(cmd.Data)
+		response.Type = "UpdateCLimitersResponse"
+		needSaveConfig = true
+	case "DeleteCLimiters":
+		err = w.handleDeleteCLimiter(cmd.Data)
+		response.Type = "DeleteCLimitersResponse"
+		needSaveConfig = true
+```
+
+[x] **Step 3: 实现 Handler 方法**
+
+在 `go-gost/x/socket/websocket_reporter.go` 中添加：
+
+```go
+func (w *WebSocketReporter) handleAddCLimiter(data interface{}) error {
+	jsonData, err := json.Marshal(data)
+	if err != nil {
+		return fmt.Errorf("序列化数据失败: %v", err)
+	}
+
+	var limiterConfig config.LimiterConfig
+	if err := json.Unmarshal(jsonData, &limiterConfig); err != nil {
+		return fmt.Errorf("解析限流器配置失败: %v", err)
+	}
+
+	req := createLimiterRequest{Data: limiterConfig}
+	return createConnLimiter(req)
+}
+
+func (w *WebSocketReporter) handleUpdateCLimiter(data interface{}) error {
+	jsonData, err := json.Marshal(data)
+	if err != nil {
+		return fmt.Errorf("序列化数据失败: %v", err)
+	}
+
+	var updateReq struct {
+		Limiter string               `json:"limiter"`
+		Data    config.LimiterConfig `json:"data"`
+	}
+
+	if err := json.Unmarshal(jsonData, &updateReq); err != nil {
+		var limiterConfig config.LimiterConfig
+		if err := json.Unmarshal(jsonData, &limiterConfig); err != nil {
+			return fmt.Errorf("解析更新请求失败: %v", err)
+		}
+		updateReq.Limiter = limiterConfig.Name
+		updateReq.Data = limiterConfig
+	}
+
+	req := updateLimiterRequest{
+		Limiter: updateReq.Limiter,
+		Data:    updateReq.Data,
+	}
+	return updateConnLimiter(req)
+}
+
+func (w *WebSocketReporter) handleDeleteCLimiter(data interface{}) error {
+	jsonData, err := json.Marshal(data)
+	if err != nil {
+		return fmt.Errorf("序列化数据失败: %v", err)
+	}
+
+	var deleteReq deleteLimiterRequest
+
+	if err := json.Unmarshal(jsonData, &deleteReq); err != nil {
+		var limiterName string
+		if err := json.Unmarshal(jsonData, &limiterName); err != nil {
+			return fmt.Errorf("解析删除请求失败: %v", err)
+		}
+		deleteReq.Limiter = limiterName
+	}
+
+	return deleteConnLimiter(deleteReq)
+}
+```
+
+[x] **Step 4: Commit**
+
+```bash
+cd go-gost
+git add x/socket/limiter.go x/socket/websocket_reporter.go
+git commit -m "feat: add CLimiters support for websocket reporter"
+cd ..
+```
+
+---
+
+### Task 2: 数据库迁移与模型更新
+
+**Files:**
+- Modify: `go-backend/internal/store/model/model.go`
+- Modify: `go-backend/internal/store/repo/repository.go`
+
+[x] **Step 1: 更新数据库模型**
+
+在 `go-backend/internal/store/model/model.go` 的 `User` 和 `Forward` 结构体中添加 `MaxConn` 字段。
+
+```go
+// 在 User 结构体中
+type User struct {
+	// ...
+	MaxConn       int           `gorm:"column:max_conn;not null;default:0"`
+	// ...
+}
+
+// 在 Forward 结构体中
+type Forward struct {
+	// ...
+	MaxConn       int           `gorm:"column:max_conn;not null;default:0"`
+	// ...
+}
+```
+
+[x] **Step 2: 编写数据库迁移**
+
+在 `go-backend/internal/store/repo/repository.go` 的 `AutoMigrate` 逻辑前（如果有自定义迁移）或利用 gorm 自动迁移机制，由于这是 autoMigrate，添加字段只要 `db.AutoMigrate(&model.User{}, &model.Forward{})` 被调用就能自动加上。确认已执行迁移。由于 `FLVX` 通常会自动执行迁移，只需修改模型即可。我们需要处理默认值，由于使用了 `default:0`，GORM 会处理新增字段的默认值，但为了安全起见，如果在旧环境中，可能直接 alter table。
+
+```go
+// 无需手动编写 SQL，依赖现有的 gorm AutoMigrate 即可。
+```
+
+[x] **Step 3: 运行并验证迁移通过**
+
+Run: `make build` (在 go-backend 中)，或者运行一个相关的存储单元测试。
+
+[x] **Step 4: Commit**
+
+```bash
+cd go-backend
+git add internal/store/model/model.go
+git commit -m "feat: add max_conn field to user and forward models"
+cd ..
+```
+
+---
+
+### Task 3: 后端控制平面 - 连接数限制器的组装与下发
+
+**Files:**
+- Modify: `go-backend/internal/http/handler/control_plane.go`
+- Modify: `go-backend/internal/store/repo/repository_control.go`
+
+[x] **Step 1: 更新存储层以获取 User 的 MaxConn**
+
+在 `go-backend/internal/store/repo/repository_control.go` 中：
+
+需要一个方法获取 User，或者如果已经有，确保可以拿到 `MaxConn`。
+
+[x] **Step 2: 编写下发 CLimiter 到节点的辅助函数**
+
+在 `go-backend/internal/http/handler/control_plane.go`，参考 `ensureLimiterOnNode` 和 `upsertLimiterOnNode`：
+
+```go
+func (h *Handler) ensureConnLimiterOnNode(nodeID int64, limiterName string, maxConn int) error {
+	limitStr := fmt.Sprintf("$ %d", maxConn)
+	
+	payload := map[string]interface{}{
+		"name":   limiterName,
+		"limits": []string{limitStr},
+	}
+	
+	if _, err := h.sendNodeCommand(nodeID, "AddCLimiters", payload, false, false); err != nil {
+		if !isAlreadyExistsMessage(err.Error()) {
+			return fmt.Errorf("连接限制器下发失败: %w", err)
+		}
+		updatePayload := map[string]interface{}{
+			"limiter": limiterName,
+			"data":    payload,
+		}
+		if _, updateErr := h.sendNodeCommand(nodeID, "UpdateCLimiters", updatePayload, false, false); updateErr != nil {
+			return fmt.Errorf("连接限制器更新失败: %w", updateErr)
+		}
+	}
+	return nil
+}
+```
+
+[x] **Step 3: 更新组装配置逻辑以绑定 `climiter`**
+
+在 `control_plane.go` 的 `syncForwardServicesWithWarnings` 及其辅助函数 `buildForwardServiceConfigs` 附近：
+
+修改 `buildForwardServiceConfigs` 的签名，传入 `maxConn int` 和对应的 `cLimiterName string`。
+
+```go
+func buildForwardServiceConfigs(baseName string, forward *model.Forward, tunnel *model.Tunnel, node *model.Node, port int, bindIP string, limiterID *int64, cLimiterName string) []map[string]interface{} {
+	// ... 现有逻辑
+	// 在服务配置生成的部分增加：
+	if cLimiterName != "" {
+		service["climiter"] = cLimiterName
+	}
+	// ...
+}
+```
+
+[x] **Step 4: 在转发服务同步主流程中决定并下发 `climiter`**
+
+在 `syncForwardServicesWithWarnings` (可能在多个重载/处理入口处，如 `ensureForwardServices`)，查出转发所属 user 的 `MaxConn`，以及转发本身的 `MaxConn`。
+
+```go
+	// 获取 User
+	user, err := h.repo.GetUser(forward.UserID)
+	if err != nil {
+		return nil, err
+	}
+
+	var cLimiterName string
+	var maxConnToSet int
+
+	if forward.MaxConn > 0 {
+		maxConnToSet = forward.MaxConn
+		cLimiterName = fmt.Sprintf("rule_conn_limit_%d", forward.ID)
+	} else if user != nil && user.MaxConn > 0 {
+		maxConnToSet = user.MaxConn
+		cLimiterName = fmt.Sprintf("user_conn_limit_%d", user.ID)
+	}
+
+	if cLimiterName != "" {
+		for _, fp := range ports {
+			if err := h.ensureConnLimiterOnNode(fp.NodeID, cLimiterName, maxConnToSet); err != nil {
+				warnings = append(warnings, fmt.Sprintf("节点 %d 连接限制器下发失败: %v", fp.NodeID, err))
+			}
+		}
+	}
+
+	// 传递给 buildForwardServiceConfigs
+	// ...
+```
+*(注意：需要确保更新涉及 `buildForwardServiceConfigs` 的所有调用点)*
+
+[x] **Step 5: Commit**
+
+```bash
+cd go-backend
+git add internal/http/handler/control_plane.go internal/store/repo/repository_control.go
+git commit -m "feat: implement max conn limiter dispatching"
+cd ..
+```
+
+---
+
+### Task 4: 后端接口 - 用户和规则的 CRUD 支持
+
+**Files:**
+- Modify: `go-backend/internal/http/handler/admin_user.go`
+- Modify: `go-backend/internal/http/handler/forward.go`
+
+[x] **Step 1: 用户接口更新**
+
+在 `go-backend/internal/http/handler/admin_user.go`，修改用户创建和更新请求的结构体（如果有），接收 `MaxConn`，并在保存到数据库时赋值。
+
+```go
+type CreateUserReq struct {
+	// ...
+	MaxConn *int `json:"maxConn"`
+}
+// 接收后：
+if req.MaxConn != nil {
+	user.MaxConn = *req.MaxConn
+}
+```
+
+在获取用户列表时，确保 `MaxConn` 返回给前端。
+
+[x] **Step 2: 规则接口更新**
+
+在 `go-backend/internal/http/handler/forward.go` 中，更新 `CreateForwardReq` 和 `UpdateForwardReq` 结构体，增加 `MaxConn`，并在创建/更新 Forward 时保存到数据库。
+
+如果转发规则的 `MaxConn` 或相关信息改变，触发节点上的规则重载（重新下发服务）。这一步由于更改了数据库，复用现有的 `syncForwardServices` 就会带上最新的配置。
+
+[x] **Step 3: 测试接口**
+
+Run: 可以启动后使用 curl 测试。
+
+[x] **Step 4: Commit**
+
+```bash
+cd go-backend
+git add internal/http/handler/admin_user.go internal/http/handler/forward.go
+git commit -m "feat: add maxConn to user and forward CRUD API"
+cd ..
+```
+
+---
+
+### Task 5: 前端 - 用户管理页面集成
+
+**Files:**
+- Modify: `vite-frontend/src/api/types.ts`
+- Modify: `vite-frontend/src/api/index.ts`
+- Modify: `vite-frontend/src/pages/users.tsx` (或者对应的用户管理页面文件)
+
+[x] **Step 1: 类型更新**
+
+在 `vite-frontend/src/api/types.ts` 中：
+为 `UserApiItem` 和相关的 mutation payload 增加 `maxConn?: number` 属性。
+
+[x] **Step 2: UI 修改**
+
+在用户创建/编辑弹窗中，增加“最大连接数”输入框：
+(假设使用 `@nextui-org/react` 的 `Input`)
+
+```tsx
+<Input
+  type="number"
+  label="最大并发连接数"
+  placeholder="0 或空表示不限制"
+  value={formData.maxConn === 0 ? "" : String(formData.maxConn || "")}
+  onValueChange={(val) => {
+	const num = parseInt(val, 10);
+	setFormData({ ...formData, maxConn: isNaN(num) ? 0 : num });
+  }}
+/>
+```
+并在用户的表格列中展示 `最大连接数`（值为 0 显示“不限制”）。
+
+[x] **Step 3: 运行 Vite 进行验证**
+
+[x] **Step 4: Commit**
+
+```bash
+cd vite-frontend
+git add src/api/types.ts src/api/index.ts src/pages/users.tsx
+git commit -m "feat: add max conn UI to user management"
+cd ..
+```
+
+---
+
+### Task 6: 前端 - 转发规则页面集成
+
+**Files:**
+- Modify: `vite-frontend/src/pages/forward.tsx`
+
+[x] **Step 1: 类型更新**
+
+在 `api/types.ts` 中 `ForwardMutationPayload` 和 `ForwardApiItem` 中增加 `maxConn?: number`。
+
+[x] **Step 2: UI 修改**
+
+在 `vite-frontend/src/pages/forward.tsx` 的创建/编辑规则弹窗（在 "规则限速" 附近）增加“最大连接数”输入框：
+
+```tsx
+<Input
+  type="number"
+  label="最大并发连接数"
+  placeholder="0 或空表示不限制"
+  value={formData.maxConn === 0 ? "" : String(formData.maxConn || "")}
+  onValueChange={(val) => {
+	const num = parseInt(val, 10);
+	setFormData({ ...formData, maxConn: isNaN(num) ? 0 : num });
+  }}
+  description="此设置优先于用户的全局连接数限制。0 表示不限制（或使用用户的全局限制）。"
+/>
+```
+
+如果是在列表/卡片中展示，可以增加一个小标签或者 Tooltip 显示其最大连接数设置。
+
+[x] **Step 3: 验证**
+
+在前端验证该功能能正确读写规则的连接限制字段。
+
+[x] **Step 4: Commit**
+
+```bash
+cd vite-frontend
+git add src/pages/forward.tsx src/api/types.ts
+git commit -m "feat: add max conn UI to forward rules"
+cd ..
+```

docs/superpowers/plans/2026-04-26-allow-local-remote-addr.md

@@ -0,0 +1,171 @@
+# Allow Local Remote Address Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add a global settings toggle that allows non-admin forward rules to target local/private addresses when explicitly enabled.
+
+**Architecture:** Keep the existing remote-address safety validator as the default path for non-admin rule changes, but gate its use behind a single backend config lookup in forward create/update handlers. Surface the toggle through the existing `vite_config` settings page and prove behavior with backend contract tests first.
+
+**Tech Stack:** Go `net/http` + GORM backend, React + TypeScript frontend settings page, Go contract tests.
+
+---
+
+### Task 1: Backend Contract Coverage
+
+**Files:**
+- Modify: `go-backend/tests/contract/forward_contract_test.go`
+
+- [ ] **Step 1: Write the failing tests**
+
+Add contract tests that prove the desired behavior:
+
+```go
+t.Run("local remote address is rejected when toggle is off", func(t *testing.T) {
+	createPayload := map[string]interface{}{
+		"name":       "deny-local-remote",
+		"tunnelId":   tunnelID,
+		"remoteAddr": "127.0.0.1:8080",
+		"strategy":   "fifo",
+	}
+	createBody, _ := json.Marshal(createPayload)
+	createReq := httptest.NewRequest(http.MethodPost, "/api/v1/forward/create", bytes.NewReader(createBody))
+	createReq.Header.Set("Authorization", adminToken)
+	createReq.Header.Set("Content-Type", "application/json")
+	createRes := httptest.NewRecorder()
+	router.ServeHTTP(createRes, createReq)
+
+	var out response.R
+	_ = json.NewDecoder(createRes.Body).Decode(&out)
+	if out.Code == 0 {
+		t.Fatalf("expected local remote address to be rejected when toggle is off")
+	}
+})
+
+t.Run("local remote address is allowed when toggle is on", func(t *testing.T) {
+	if err := repo.DB().Exec(`
+		INSERT INTO vite_config(name, value, time)
+		VALUES(?, ?, ?)
+		ON CONFLICT(name) DO UPDATE SET value = excluded.value, time = excluded.time
+	`, "allow_local_remote_addr", "1", time.Now().UnixMilli()).Error; err != nil {
+		t.Fatalf("enable allow_local_remote_addr: %v", err)
+	}
+
+	createPayload := map[string]interface{}{
+		"name":       "allow-local-remote",
+		"tunnelId":   tunnelID,
+		"remoteAddr": "127.0.0.1:8080",
+		"strategy":   "fifo",
+	}
+	createBody, _ := json.Marshal(createPayload)
+	createReq := httptest.NewRequest(http.MethodPost, "/api/v1/forward/create", bytes.NewReader(createBody))
+	createReq.Header.Set("Authorization", adminToken)
+	createReq.Header.Set("Content-Type", "application/json")
+	createRes := httptest.NewRecorder()
+	router.ServeHTTP(createRes, createReq)
+	assertCode(t, createRes, 0)
+})
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `go test ./tests/contract/... -run 'TestForwardContracts|local remote address'`
+Expected: FAIL because backend still rejects local/private addresses unconditionally.
+
+- [ ] **Step 3: Commit**
+
+Do not commit yet; combine with Task 2 after implementation passes.
+
+### Task 2: Backend Toggle Implementation
+
+**Files:**
+- Modify: `go-backend/internal/http/handler/mutations.go`
+
+- [ ] **Step 1: Add a tiny config helper**
+
+Add a helper near other handler helpers:
+
+```go
+func (h *Handler) allowLocalRemoteAddr() bool {
+	if h == nil || h.repo == nil {
+		return false
+	}
+	cfg, err := h.repo.GetConfigByName("allow_local_remote_addr")
+	if err != nil || cfg == nil {
+		return false
+	}
+	return strings.TrimSpace(cfg.Value) == "1"
+}
+```
+
+- [ ] **Step 2: Gate create/update validation behind the helper**
+
+Replace the unconditional checks with:
+
+```go
+if !h.allowLocalRemoteAddr() {
+	if err := IsSafeRemoteAddr(remoteAddr); err != nil {
+		response.WriteJSON(w, response.Err(403, err.Error()))
+		return
+	}
+}
+```
+
+- [ ] **Step 3: Run contract tests to verify they pass**
+
+Run: `go test ./tests/contract/... -run 'TestForwardContracts|local remote address'`
+Expected: PASS
+
+- [ ] **Step 4: Run full backend tests**
+
+Run: `go test ./...`
+Expected: PASS
+
+### Task 3: Settings Page Toggle
+
+**Files:**
+- Modify: `vite-frontend/src/pages/config.tsx`
+
+- [ ] **Step 1: Add the config item to the settings schema**
+
+Add a switch-style item for `allow_local_remote_addr` with warning copy about reduced safety.
+
+- [ ] **Step 2: Ensure the key is included in config loading/saving paths**
+
+Add `allow_local_remote_addr` anywhere the page enumerates config keys or groups persisted config values.
+
+- [ ] **Step 3: Run frontend build**
+
+Run: `pnpm run build`
+Expected: PASS
+
+- [ ] **Step 4: Run frontend lint**
+
+Run: `pnpm run lint`
+Expected: 0 errors; existing warnings may remain.
+
+### Task 4: Final Verification
+
+**Files:**
+- Verify only
+
+- [ ] **Step 1: Re-run backend contracts for the toggle**
+
+Run: `go test ./tests/contract/... -run 'TestForwardContracts|local remote address'`
+Expected: PASS
+
+- [ ] **Step 2: Re-run full backend tests**
+
+Run: `go test ./...`
+Expected: PASS
+
+- [ ] **Step 3: Re-run frontend build/lint**
+
+Run: `pnpm run build && pnpm run lint`
+Expected: Build passes, lint has no errors.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add go-backend/internal/http/handler/mutations.go go-backend/tests/contract/forward_contract_test.go vite-frontend/src/pages/config.tsx docs/superpowers/specs/2026-04-26-allow-local-remote-addr-design.md docs/superpowers/plans/2026-04-26-allow-local-remote-addr.md
+git commit -m "feat: add allow-local-remote-address toggle"
+```

docs/superpowers/plans/2026-04-26-flow-upload-batch-optimization.md

@@ -0,0 +1,849 @@
+# flow/upload Batch Optimization Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Reduce `POST /flow/upload` database pressure by converting the hot path from per-item queries and per-item transactions to per-request aggregation, batched metadata reads, and batched writes, while preserving immediate quota disable / forward pause behavior inside the same upload.
+
+**Architecture:** Parse one upload into a batch object in the handler layer, fetch one shared `forward+tunnel` metadata map, then reuse that map for flow accounting and tunnel metric aggregation. Replace `AddFlow` and `AddUserQuotaUsage` per-item transactions with one batched flow transaction and one batched quota transaction; run policy enforcement, orphan cleanup, and peer-share flow handling once per affected target instead of once per item.
+
+**Tech Stack:** Go, net/http, GORM, SQLite/PostgreSQL, existing backend contract tests.
+
+---
+
+## File Map
+
+- Create: `go-backend/internal/http/handler/flow_upload_batch.go`
+  Responsibility: request-scoped parsing, aggregation, and application of one `/flow/upload` batch.
+- Create: `go-backend/internal/http/handler/flow_upload_batch_test.go`
+  Responsibility: unit coverage for batch aggregation semantics.
+- Create: `go-backend/internal/store/repo/repository_flow_batch_test.go`
+  Responsibility: unit coverage for batched flow and quota persistence.
+- Create: `go-backend/tests/contract/flow_upload_batch_contract_test.go`
+  Responsibility: contract coverage that repeated items still accumulate correctly and still disable quota immediately.
+- Modify: `go-backend/internal/http/handler/handler.go`
+  Responsibility: switch `/flow/upload` entrypoint to the new batch pipeline.
+- Modify: `go-backend/internal/http/handler/tunnel_metrics_ingestion.go`
+  Responsibility: accept pre-aggregated forward deltas plus shared forward metadata instead of reparsing the raw items.
+- Modify: `go-backend/internal/store/repo/repository.go`
+  Responsibility: add batched flow persistence primitives near the existing flow update code.
+- Modify: `go-backend/internal/store/repo/repository_flow.go`
+  Responsibility: add shared flow-upload metadata query helpers.
+- Modify: `go-backend/internal/store/repo/repository_user_quota.go`
+  Responsibility: add batched quota usage persistence that still returns normalized quota views for immediate enforcement.
+
+---
+
+### Task 1: Add Failing Tests For Batched flow/upload Semantics
+
+**Files:**
+- Create: `go-backend/internal/http/handler/flow_upload_batch_test.go`
+- Create: `go-backend/tests/contract/flow_upload_batch_contract_test.go`
+
+- [ ] **Step 1: Write the failing handler unit test**
+
+Create `go-backend/internal/http/handler/flow_upload_batch_test.go` with a unit test that locks in the new aggregation contract.
+
+```go
+package handler
+
+import (
+	"testing"
+
+	"go-backend/internal/store/repo"
+)
+
+func TestBuildFlowUploadBatchAggregatesForwardQuotaPeerShareAndCleanupTargets(t *testing.T) {
+	h := &Handler{}
+	metas := map[int64]repo.FlowUploadForwardMeta{
+		20: {
+			ForwardID:     20,
+			TunnelID:      1,
+			TrafficRatio:  2,
+			TunnelFlow:    3,
+		},
+	}
+
+	batch := h.buildFlowUploadBatch([]flowItem{
+		{N: "20_2_10", U: 70, D: 50},
+		{N: "20_2_10_tcp", U: 40, D: 30},
+		{N: "99_2_10", U: 12, D: 8},
+		{N: "fed_svc_17", U: 9, D: 1},
+	}, metas)
+
+	if len(batch.flowDeltas) != 1 {
+		t.Fatalf("expected 1 flow delta, got %d", len(batch.flowDeltas))
+	}
+	delta := batch.flowDeltas[0]
+	if delta.ForwardID != 20 || delta.UserID != 2 || delta.UserTunnelID != 10 {
+		t.Fatalf("unexpected flow delta identity: %#v", delta)
+	}
+	if delta.InFlow != 480 || delta.OutFlow != 660 {
+		t.Fatalf("expected scaled flow in=480 out=660, got in=%d out=%d", delta.InFlow, delta.OutFlow)
+	}
+	if batch.quotaUsage[2] != 1140 {
+		t.Fatalf("expected quota usage 1140, got %d", batch.quotaUsage[2])
+	}
+	if len(batch.policyTargets) != 1 {
+		t.Fatalf("expected 1 policy target, got %d", len(batch.policyTargets))
+	}
+	if batch.policyTargets[0].UserID != 2 || batch.policyTargets[0].UserTunnelID != 10 {
+		t.Fatalf("unexpected policy target: %#v", batch.policyTargets[0])
+	}
+	traffic := batch.forwardTraffic[20]
+	if traffic.bytesIn != 80 || traffic.bytesOut != 110 {
+		t.Fatalf("expected raw traffic in=80 out=110, got in=%d out=%d", traffic.bytesIn, traffic.bytesOut)
+	}
+	if _, ok := batch.orphanServices["99_2_10"]; !ok {
+		t.Fatalf("expected orphan service cleanup target for 99_2_10")
+	}
+	if item, ok := batch.peerShareForwardItems["20_2_10"]; !ok || item.U != 110 || item.D != 80 {
+		t.Fatalf("expected merged peer-share forward item, got %#v ok=%v", item, ok)
+	}
+	if item, ok := batch.peerShareRuntimeItems[17]; !ok || item.U != 9 || item.D != 1 {
+		t.Fatalf("expected merged peer-share runtime item, got %#v ok=%v", item, ok)
+	}
+}
+```
+
+- [ ] **Step 2: Run the handler unit test to verify RED**
+
+Run:
+
+```bash
+go test ./internal/http/handler -run TestBuildFlowUploadBatchAggregatesForwardQuotaPeerShareAndCleanupTargets -v
+```
+
+Expected: FAIL because `FlowUploadForwardMeta`, `buildFlowUploadBatch`, and the new batch fields do not exist yet.
+
+- [ ] **Step 3: Write the contract test that guards current behavior**
+
+Create `go-backend/tests/contract/flow_upload_batch_contract_test.go` so the optimization cannot weaken same-request quota enforcement.
+
+```go
+package contract_test
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"go-backend/internal/store/model"
+)
+
+func TestFlowUploadAggregatesRepeatedItemsAndDisablesQuotaImmediately(t *testing.T) {
+	secret := "monitoring-jwt-secret"
+	router, repo := setupContractRouter(t, secret)
+	now := time.Now()
+	nowMs := now.UnixMilli()
+	dayKey := int64(now.Year()*10000 + int(now.Month())*100 + now.Day())
+	monthKey := int64(now.Year()*100 + int(now.Month()))
+	const bytesPerGB = int64(1024 * 1024 * 1024)
+
+	node := &model.Node{Name: "node-1", Secret: "node-secret", ServerIP: "127.0.0.1", Port: "10000-10010", TCPListenAddr: "[::]", UDPListenAddr: "[::]", CreatedTime: nowMs, Status: 1}
+	if err := repo.DB().Create(node).Error; err != nil {
+		t.Fatalf("seed node: %v", err)
+	}
+	if err := repo.DB().Exec(`INSERT INTO user(id, user, pwd, role_id, exp_time, flow, in_flow, out_flow, flow_reset_time, num, created_time, updated_time, status) VALUES(2, 'flow_user', 'pwd', 1, 2727251700000, 99999, 0, 0, 1, 99999, ?, ?, 1)`, nowMs, nowMs).Error; err != nil {
+		t.Fatalf("insert user: %v", err)
+	}
+	tunnel := &model.Tunnel{Name: "tunnel-1", TrafficRatio: 1.0, Type: 1, Protocol: "tls", Flow: 1, CreatedTime: nowMs, UpdatedTime: nowMs, Status: 1}
+	if err := repo.DB().Create(tunnel).Error; err != nil {
+		t.Fatalf("seed tunnel: %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(10, 2, ?, NULL, 99999, 99999, 0, 0, 1, 2727251700000, 1)`, tunnel.ID).Error; err != nil {
+		t.Fatalf("insert user_tunnel: %v", err)
+	}
+	forward := &model.Forward{ID: 20, UserID: 2, UserName: "flow_user", Name: "forward-20", TunnelID: tunnel.ID, RemoteAddr: "1.1.1.1:80", Strategy: "fifo", CreatedTime: nowMs, UpdatedTime: nowMs, Status: 1}
+	if err := repo.DB().Create(forward).Error; err != nil {
+		t.Fatalf("seed forward: %v", err)
+	}
+	if err := repo.DB().Exec(`INSERT INTO user_quota(user_id, daily_limit_gb, monthly_limit_gb, daily_used_bytes, monthly_used_bytes, day_key, month_key, disabled_by_quota, disabled_at, paused_forward_ids, created_time, updated_time) VALUES(2, 1, 0, ?, ?, ?, ?, 0, 0, '', ?, ?)`, bytesPerGB-100, bytesPerGB-100, dayKey, monthKey, nowMs, nowMs).Error; err != nil {
+		t.Fatalf("insert user_quota: %v", err)
+	}
+
+	body, err := json.Marshal([]map[string]interface{}{
+		{"n": "20_2_10", "u": 70, "d": 50},
+		{"n": "20_2_10_tcp", "u": 40, "d": 30},
+	})
+	if err != nil {
+		t.Fatalf("marshal body: %v", err)
+	}
+	req := httptest.NewRequest(http.MethodPost, "/flow/upload?secret="+node.Secret, bytes.NewReader(body))
+	res := httptest.NewRecorder()
+	router.ServeHTTP(res, req)
+
+	if res.Code != http.StatusOK {
+		t.Fatalf("expected status 200, got %d", res.Code)
+	}
+	if got := mustQueryInt(t, repo, `SELECT status FROM forward WHERE id = 20`); got != 0 {
+		t.Fatalf("expected forward paused immediately, got status=%d", got)
+	}
+	if got := mustQueryInt(t, repo, `SELECT disabled_by_quota FROM user_quota WHERE user_id = 2`); got != 1 {
+		t.Fatalf("expected quota disabled flag=1, got %d", got)
+	}
+	if got := mustQueryInt(t, repo, `SELECT in_flow FROM forward WHERE id = 20`); got != 80 {
+		t.Fatalf("expected forward in_flow=80, got %d", got)
+	}
+	if got := mustQueryInt(t, repo, `SELECT out_flow FROM forward WHERE id = 20`); got != 110 {
+		t.Fatalf("expected forward out_flow=110, got %d", got)
+	}
+	metrics, err := repo.GetTunnelMetrics(tunnel.ID, 0, nowMs+60_000)
+	if err != nil {
+		t.Fatalf("get tunnel metrics: %v", err)
+	}
+	if len(metrics) != 1 || metrics[0].BytesIn != 80 || metrics[0].BytesOut != 110 {
+		t.Fatalf("expected one aggregated metric row, got %#v", metrics)
+	}
+}
+```
+
+- [ ] **Step 4: Run the contract test to verify the same-request guard stays green or reveals an existing regression**
+
+Run:
+
+```bash
+go test ./tests/contract/... -run TestFlowUploadAggregatesRepeatedItemsAndDisablesQuotaImmediately -v
+```
+
+Expected: this test may already PASS before the refactor because it locks in existing external behavior. Keep it either way; it is the guardrail for the optimization.
+
+- [ ] **Step 5: Optional commit if the user explicitly requested commits**
+
+```bash
+git add go-backend/internal/http/handler/flow_upload_batch_test.go go-backend/tests/contract/flow_upload_batch_contract_test.go
+git commit -m "test: cover flow upload batch semantics"
+```
+
+---
+
+### Task 2: Add Batched Repository Primitives
+
+**Files:**
+- Modify: `go-backend/internal/store/repo/repository_flow.go`
+- Modify: `go-backend/internal/store/repo/repository.go`
+- Modify: `go-backend/internal/store/repo/repository_user_quota.go`
+- Create: `go-backend/internal/store/repo/repository_flow_batch_test.go`
+
+- [ ] **Step 1: Write the failing repository tests**
+
+Create `go-backend/internal/store/repo/repository_flow_batch_test.go` with coverage for both the shared metadata query and the batched counter/quota writes.
+
+```go
+package repo
+
+import (
+	"path/filepath"
+	"testing"
+	"time"
+)
+
+func TestGetFlowUploadForwardMetasAndApplyFlowUploadDeltasBatch(t *testing.T) {
+	r, err := Open(filepath.Join(t.TempDir(), "flow-batch.db"))
+	if err != nil {
+		t.Fatalf("open repo: %v", err)
+	}
+	defer r.Close()
+
+	now := time.Now().UnixMilli()
+	if err := r.DB().Exec(`INSERT INTO user(id, user, pwd, role_id, exp_time, flow, in_flow, out_flow, flow_reset_time, num, created_time, updated_time, status) VALUES(2, 'u2', 'pwd', 1, 2727251700000, 99999, 0, 0, 1, 99999, ?, ?, 1)`, now, now).Error; err != nil {
+		t.Fatalf("insert user: %v", err)
+	}
+	if err := r.DB().Exec(`INSERT INTO tunnel(id, name, traffic_ratio, type, protocol, flow, created_time, updated_time, status, in_ip, inx) VALUES(1, 't1', 2.0, 1, 'tls', 3, ?, ?, 1, NULL, 0)`, now, now).Error; err != nil {
+		t.Fatalf("insert tunnel: %v", err)
+	}
+	if err := r.DB().Exec(`INSERT INTO user_tunnel(id, user_id, tunnel_id, speed_id, num, flow, in_flow, out_flow, flow_reset_time, exp_time, status) VALUES(10, 2, 1, NULL, 99999, 99999, 0, 0, 1, 2727251700000, 1)`).Error; err != nil {
+		t.Fatalf("insert user_tunnel: %v", err)
+	}
+	if err := r.DB().Exec(`INSERT INTO forward(id, user_id, user_name, name, tunnel_id, remote_addr, strategy, in_flow, out_flow, created_time, updated_time, status, inx) VALUES(20, 2, 'u2', 'f20', 1, '1.1.1.1:80', 'fifo', 0, 0, ?, ?, 1, 0)`, now, now).Error; err != nil {
+		t.Fatalf("insert forward: %v", err)
+	}
+
+	metas, err := r.GetFlowUploadForwardMetas([]int64{20, 99})
+	if err != nil {
+		t.Fatalf("get metas: %v", err)
+	}
+	if metas[20].TunnelID != 1 || metas[20].TrafficRatio != 2 || metas[20].TunnelFlow != 3 {
+		t.Fatalf("unexpected meta for forward 20: %#v", metas[20])
+	}
+	if _, ok := metas[99]; ok {
+		t.Fatalf("did not expect meta for missing forward 99")
+	}
+
+	err = r.ApplyFlowUploadDeltasBatch([]FlowUploadCounterDelta{{ForwardID: 20, UserID: 2, UserTunnelID: 10, InFlow: 480, OutFlow: 660}})
+	if err != nil {
+		t.Fatalf("apply flow batch: %v", err)
+	}
+	if got := mustFlowBatchCount(t, r, `SELECT in_flow FROM forward WHERE id = 20`); got != 480 {
+		t.Fatalf("expected forward in_flow=480, got %d", got)
+	}
+	if got := mustFlowBatchCount(t, r, `SELECT out_flow FROM user WHERE id = 2`); got != 660 {
+		t.Fatalf("expected user out_flow=660, got %d", got)
+	}
+	if got := mustFlowBatchCount(t, r, `SELECT in_flow FROM user_tunnel WHERE id = 10`); got != 480 {
+		t.Fatalf("expected user_tunnel in_flow=480, got %d", got)
+	}
+}
+
+func TestAddUserQuotaUsageBatchReturnsNormalizedViews(t *testing.T) {
+	r, err := Open(filepath.Join(t.TempDir(), "quota-batch.db"))
+	if err != nil {
+		t.Fatalf("open repo: %v", err)
+	}
+	defer r.Close()
+
+	now := time.Now()
+	nowMs := now.UnixMilli()
+	if err := r.DB().Exec(`INSERT INTO user(id, user, pwd, role_id, exp_time, flow, in_flow, out_flow, flow_reset_time, num, created_time, updated_time, status) VALUES(2, 'u2', 'pwd', 1, 2727251700000, 99999, 0, 0, 1, 99999, ?, ?, 1)`, nowMs, nowMs).Error; err != nil {
+		t.Fatalf("insert user: %v", err)
+	}
+	views, err := r.AddUserQuotaUsageBatch(map[int64]int64{2: 1140}, now)
+	if err != nil {
+		t.Fatalf("batch quota update: %v", err)
+	}
+	if views[2] == nil || views[2].DailyUsedBytes != 1140 || views[2].MonthlyUsedBytes != 1140 {
+		t.Fatalf("unexpected quota view: %#v", views[2])
+	}
+}
+
+func mustFlowBatchCount(t *testing.T, r *Repository, query string, args ...interface{}) int64 {
+	t.Helper()
+	var value int64
+	if err := r.DB().Raw(query, args...).Row().Scan(&value); err != nil {
+		t.Fatalf("query %q failed: %v", query, err)
+	}
+	return value
+}
+```
+
+- [ ] **Step 2: Run the repository tests to verify RED**
+
+Run:
+
+```bash
+go test ./internal/store/repo -run 'TestGetFlowUploadForwardMetasAndApplyFlowUploadDeltasBatch|TestAddUserQuotaUsageBatchReturnsNormalizedViews' -v
+```
+
+Expected: FAIL because `GetFlowUploadForwardMetas`, `ApplyFlowUploadDeltasBatch`, `FlowUploadCounterDelta`, and `AddUserQuotaUsageBatch` do not exist yet.
+
+- [ ] **Step 3: Implement shared flow-upload metadata and batched persistence**
+
+Update `go-backend/internal/store/repo/repository_flow.go`, `repository.go`, and `repository_user_quota.go` with the following concrete APIs. Add `sort` to the `repository_user_quota.go` import list.
+
+```go
+// repository_flow.go
+type FlowUploadForwardMeta struct {
+	ForwardID    int64
+	TunnelID     int64
+	TrafficRatio float64
+	TunnelFlow   int64
+}
+
+func (r *Repository) GetFlowUploadForwardMetas(forwardIDs []int64) (map[int64]FlowUploadForwardMeta, error) {
+	if r == nil || r.db == nil {
+		return nil, errors.New("repository not initialized")
+	}
+	if len(forwardIDs) == 0 {
+		return map[int64]FlowUploadForwardMeta{}, nil
+	}
+	ids := make([]int64, 0, len(forwardIDs))
+	seen := make(map[int64]struct{}, len(forwardIDs))
+	for _, id := range forwardIDs {
+		if id <= 0 {
+			continue
+		}
+		if _, ok := seen[id]; ok {
+			continue
+		}
+		seen[id] = struct{}{}
+		ids = append(ids, id)
+	}
+	type row struct {
+		ForwardID    int64   `gorm:"column:forward_id"`
+		TunnelID     int64   `gorm:"column:tunnel_id"`
+		TrafficRatio float64 `gorm:"column:traffic_ratio"`
+		TunnelFlow   int64   `gorm:"column:tunnel_flow"`
+	}
+	var rows []row
+	err := r.db.Table("forward AS f").
+		Select("f.id AS forward_id, f.tunnel_id AS tunnel_id, t.traffic_ratio AS traffic_ratio, t.flow AS tunnel_flow").
+		Joins("JOIN tunnel t ON t.id = f.tunnel_id").
+		Where("f.id IN ?", ids).
+		Scan(&rows).Error
+	if err != nil {
+		return nil, err
+	}
+	out := make(map[int64]FlowUploadForwardMeta, len(rows))
+	for _, row := range rows {
+		if row.TunnelFlow <= 0 {
+			row.TunnelFlow = 1
+		}
+		if row.TrafficRatio <= 0 {
+			row.TrafficRatio = 1
+		}
+		out[row.ForwardID] = FlowUploadForwardMeta{ForwardID: row.ForwardID, TunnelID: row.TunnelID, TrafficRatio: row.TrafficRatio, TunnelFlow: row.TunnelFlow}
+	}
+	return out, nil
+}
+```
+
+```go
+// repository.go
+type FlowUploadCounterDelta struct {
+	ForwardID    int64
+	UserID       int64
+	UserTunnelID int64
+	InFlow       int64
+	OutFlow      int64
+}
+
+func (r *Repository) ApplyFlowUploadDeltasBatch(deltas []FlowUploadCounterDelta) error {
+	if r == nil || r.db == nil {
+		return errors.New("repository not initialized")
+	}
+	if len(deltas) == 0 {
+		return nil
+	}
+	forwardTotals := make(map[int64][2]int64, len(deltas))
+	userTotals := make(map[int64][2]int64, len(deltas))
+	userTunnelTotals := make(map[int64][2]int64, len(deltas))
+	for _, delta := range deltas {
+		if delta.ForwardID > 0 {
+			current := forwardTotals[delta.ForwardID]
+			current[0] += delta.InFlow
+			current[1] += delta.OutFlow
+			forwardTotals[delta.ForwardID] = current
+		}
+		if delta.UserID > 0 {
+			current := userTotals[delta.UserID]
+			current[0] += delta.InFlow
+			current[1] += delta.OutFlow
+			userTotals[delta.UserID] = current
+		}
+		if delta.UserTunnelID > 0 {
+			current := userTunnelTotals[delta.UserTunnelID]
+			current[0] += delta.InFlow
+			current[1] += delta.OutFlow
+			userTunnelTotals[delta.UserTunnelID] = current
+		}
+	}
+	return r.db.Transaction(func(tx *gorm.DB) error {
+		for forwardID, total := range forwardTotals {
+			if err := tx.Model(&model.Forward{}).Where("id = ?", forwardID).UpdateColumns(map[string]interface{}{"in_flow": gorm.Expr("in_flow + ?", total[0]), "out_flow": gorm.Expr("out_flow + ?", total[1])}).Error; err != nil {
+				return err
+			}
+		}
+		for userID, total := range userTotals {
+			if err := tx.Model(&model.User{}).Where("id = ?", userID).UpdateColumns(map[string]interface{}{"in_flow": gorm.Expr("in_flow + ?", total[0]), "out_flow": gorm.Expr("out_flow + ?", total[1])}).Error; err != nil {
+				return err
+			}
+		}
+		for userTunnelID, total := range userTunnelTotals {
+			if err := tx.Model(&model.UserTunnel{}).Where("id = ?", userTunnelID).UpdateColumns(map[string]interface{}{"in_flow": gorm.Expr("in_flow + ?", total[0]), "out_flow": gorm.Expr("out_flow + ?", total[1])}).Error; err != nil {
+				return err
+			}
+		}
+		return nil
+	})
+}
+```
+
+```go
+// repository_user_quota.go
+func (r *Repository) AddUserQuotaUsageBatch(usages map[int64]int64, now time.Time) (map[int64]*model.UserQuotaView, error) {
+	if r == nil || r.db == nil {
+		return nil, errors.New("repository not initialized")
+	}
+	if len(usages) == 0 {
+		return map[int64]*model.UserQuotaView{}, nil
+	}
+	result := make(map[int64]*model.UserQuotaView, len(usages))
+	err := r.db.Transaction(func(tx *gorm.DB) error {
+		userIDs := make([]int64, 0, len(usages))
+		for userID := range usages {
+			if userID > 0 {
+				userIDs = append(userIDs, userID)
+			}
+		}
+		sort.Slice(userIDs, func(i, j int) bool { return userIDs[i] < userIDs[j] })
+		for _, userID := range userIDs {
+			q, err := r.loadOrCreateUserQuotaTx(tx, userID, now)
+			if err != nil {
+				return err
+			}
+			applyUserQuotaWindowRoll(q, now)
+			if usages[userID] > 0 {
+				q.DailyUsedBytes += usages[userID]
+				q.MonthlyUsedBytes += usages[userID]
+			}
+			q.UpdatedTime = now.UnixMilli()
+			if err := tx.Model(&model.UserQuota{}).Where("user_id = ?", userID).Updates(map[string]interface{}{"daily_used_bytes": q.DailyUsedBytes, "monthly_used_bytes": q.MonthlyUsedBytes, "day_key": q.DayKey, "month_key": q.MonthKey, "updated_time": q.UpdatedTime}).Error; err != nil {
+				return err
+			}
+			result[userID] = normalizeUserQuotaView(cloneUserQuotaView(*q), now)
+		}
+		return nil
+	})
+	if err != nil {
+		return nil, err
+	}
+	return result, nil
+}
+```
+
+- [ ] **Step 4: Run the repository tests to verify GREEN**
+
+Run:
+
+```bash
+go test ./internal/store/repo -run 'TestGetFlowUploadForwardMetasAndApplyFlowUploadDeltasBatch|TestAddUserQuotaUsageBatchReturnsNormalizedViews' -v
+```
+
+Expected: PASS.
+
+- [ ] **Step 5: Optional commit if the user explicitly requested commits**
+
+```bash
+git add go-backend/internal/store/repo/repository.go go-backend/internal/store/repo/repository_flow.go go-backend/internal/store/repo/repository_user_quota.go go-backend/internal/store/repo/repository_flow_batch_test.go
+git commit -m "refactor: batch flow upload persistence"
+```
+
+---
+
+### Task 3: Refactor flow/upload To Use One Parsed Batch
+
+**Files:**
+- Create: `go-backend/internal/http/handler/flow_upload_batch.go`
+- Modify: `go-backend/internal/http/handler/handler.go`
+- Modify: `go-backend/internal/http/handler/tunnel_metrics_ingestion.go`
+- Modify: `go-backend/internal/http/handler/flow_upload_batch_test.go`
+- Modify: `go-backend/tests/contract/flow_upload_batch_contract_test.go`
+
+- [ ] **Step 1: Write the new handler batch implementation**
+
+Create `go-backend/internal/http/handler/flow_upload_batch.go` and move the request-scoped aggregation there.
+
+```go
+package handler
+
+import (
+	"log"
+	"sort"
+	"strings"
+	"time"
+
+	"go-backend/internal/store/repo"
+)
+
+type flowPolicyTarget struct {
+	UserID       int64
+	UserTunnelID int64
+}
+
+type flowUploadBatch struct {
+	flowDeltas           []repo.FlowUploadCounterDelta
+	quotaUsage           map[int64]int64
+	policyTargets        []flowPolicyTarget
+	forwardTraffic       map[int64]tunnelTrafficDelta
+	orphanServices       map[string]struct{}
+	peerShareForwardItems map[string]flowItem
+	peerShareRuntimeItems map[int64]flowItem
+}
+
+func (h *Handler) buildFlowUploadBatch(items []flowItem, metas map[int64]repo.FlowUploadForwardMeta) flowUploadBatch {
+	batch := flowUploadBatch{
+		quotaUsage:            make(map[int64]int64),
+		forwardTraffic:        make(map[int64]tunnelTrafficDelta),
+		orphanServices:        make(map[string]struct{}),
+		peerShareForwardItems: make(map[string]flowItem),
+		peerShareRuntimeItems: make(map[int64]flowItem),
+	}
+	policySeen := map[flowPolicyTarget]struct{}{}
+	flowSeen := map[int64]int{}
+
+	for _, item := range items {
+		serviceName := strings.TrimSpace(item.N)
+		if serviceName == "" || serviceName == "web_api" {
+			continue
+		}
+		if runtimeID, ok := parsePeerShareRuntimeServiceID(serviceName); ok {
+			merged := batch.peerShareRuntimeItems[runtimeID]
+			merged.N = serviceName
+			merged.U += item.U
+			merged.D += item.D
+			batch.peerShareRuntimeItems[runtimeID] = merged
+			continue
+		}
+		forwardID, userID, userTunnelID, ok := parseFlowServiceIDs(serviceName)
+		if !ok {
+			continue
+		}
+		meta, exists := metas[forwardID]
+		if !exists {
+			batch.orphanServices[serviceName] = struct{}{}
+			continue
+		}
+		raw := batch.forwardTraffic[forwardID]
+		raw.bytesIn += item.D
+		raw.bytesOut += item.U
+		batch.forwardTraffic[forwardID] = raw
+
+		scaledIn := int64(float64(item.D)*meta.TrafficRatio) * meta.TunnelFlow
+		scaledOut := int64(float64(item.U)*meta.TrafficRatio) * meta.TunnelFlow
+		if idx, ok := flowSeen[forwardID]; ok {
+			batch.flowDeltas[idx].InFlow += scaledIn
+			batch.flowDeltas[idx].OutFlow += scaledOut
+		} else {
+			flowSeen[forwardID] = len(batch.flowDeltas)
+			batch.flowDeltas = append(batch.flowDeltas, repo.FlowUploadCounterDelta{ForwardID: forwardID, UserID: userID, UserTunnelID: userTunnelID, InFlow: scaledIn, OutFlow: scaledOut})
+		}
+		batch.quotaUsage[userID] += scaledIn + scaledOut
+		target := flowPolicyTarget{UserID: userID, UserTunnelID: userTunnelID}
+		if _, seen := policySeen[target]; !seen {
+			policySeen[target] = struct{}{}
+			batch.policyTargets = append(batch.policyTargets, target)
+		}
+		merged := batch.peerShareForwardItems[normalizeForwardRuntimeServiceName(serviceName)]
+		merged.N = normalizeForwardRuntimeServiceName(serviceName)
+		merged.U += item.U
+		merged.D += item.D
+		batch.peerShareForwardItems[normalizeForwardRuntimeServiceName(serviceName)] = merged
+	}
+
+	sort.Slice(batch.policyTargets, func(i, j int) bool {
+		if batch.policyTargets[i].UserID == batch.policyTargets[j].UserID {
+			return batch.policyTargets[i].UserTunnelID < batch.policyTargets[j].UserTunnelID
+		}
+		return batch.policyTargets[i].UserID < batch.policyTargets[j].UserID
+	})
+	return batch
+}
+
+func (h *Handler) applyFlowUploadBatch(nodeID int64, batch flowUploadBatch, now time.Time) {
+	if h == nil || h.repo == nil {
+		return
+	}
+	if err := h.repo.ApplyFlowUploadDeltasBatch(batch.flowDeltas); err != nil {
+		log.Printf("flow upload write failed op=flow.batch_apply node_id=%d err=%v", nodeID, err)
+		return
+	}
+	quotaViews, err := h.repo.AddUserQuotaUsageBatch(batch.quotaUsage, now)
+	if err != nil {
+		log.Printf("flow upload write failed op=quota.batch_apply node_id=%d err=%v", nodeID, err)
+		return
+	}
+	for userID, quota := range quotaViews {
+		h.enforceUserQuotaIfNeeded(userID, quota)
+	}
+	for _, target := range batch.policyTargets {
+		if target.UserID <= 0 || target.UserTunnelID <= 0 {
+			continue
+		}
+		h.enforceFlowPolicies(target.UserID, target.UserTunnelID)
+	}
+	for serviceName := range batch.orphanServices {
+		h.sendDeleteOrphanedForwardService(nodeID, serviceName)
+	}
+	for serviceName, item := range batch.peerShareForwardItems {
+		forwardID, _, _, ok := parseFlowServiceIDs(serviceName)
+		if ok {
+			h.processPeerShareFlowFromForward(forwardID, nodeID, serviceName, item)
+		}
+	}
+	for runtimeID, item := range batch.peerShareRuntimeItems {
+		h.processPeerShareFlow(runtimeID, item)
+	}
+}
+```
+
+- [ ] **Step 2: Switch the `/flow/upload` entrypoint and tunnel metric ingestion to the shared batch**
+
+Modify `handler.go` and `tunnel_metrics_ingestion.go` so the raw JSON is parsed once and the same forward metadata powers both flow counters and tunnel metrics.
+
+```go
+// handler.go
+func (h *Handler) flowUpload(w http.ResponseWriter, r *http.Request) {
+	secret := r.URL.Query().Get("secret")
+	node, _ := h.repo.GetNodeBySecret(secret)
+	if node == nil {
+		w.Header().Set("Content-Type", "text/plain; charset=utf-8")
+		_, _ = w.Write([]byte("ok"))
+		return
+	}
+
+	raw, err := readAndDecryptFlowBody(r.Body, secret)
+	if err == nil && strings.TrimSpace(raw) != "" {
+		var items []flowItem
+		if json.Unmarshal([]byte(raw), &items) == nil {
+			now := time.Now()
+			forwardIDs := collectFlowUploadForwardIDs(items)
+			metas, metaErr := h.repo.GetFlowUploadForwardMetas(forwardIDs)
+			if metaErr != nil {
+				log.Printf("flow upload metadata lookup failed node_id=%d err=%v", node.ID, metaErr)
+				metas = map[int64]repo.FlowUploadForwardMeta{}
+			}
+			batch := h.buildFlowUploadBatch(items, metas)
+			h.recordTunnelMetricsFromForwardBatch(node.ID, batch.forwardTraffic, metas, now.UnixMilli())
+			h.applyFlowUploadBatch(node.ID, batch, now)
+		}
+	}
+
+	w.Header().Set("Content-Type", "text/plain; charset=utf-8")
+	_, _ = w.Write([]byte("ok"))
+}
+```
+
+```go
+// tunnel_metrics_ingestion.go
+func collectFlowUploadForwardIDs(items []flowItem) []int64 {
+	ids := make([]int64, 0, len(items))
+	seen := make(map[int64]struct{}, len(items))
+	for _, item := range items {
+		forwardID, _, _, ok := parseFlowServiceIDs(strings.TrimSpace(item.N))
+		if !ok || forwardID <= 0 {
+			continue
+		}
+		if _, exists := seen[forwardID]; exists {
+			continue
+		}
+		seen[forwardID] = struct{}{}
+		ids = append(ids, forwardID)
+	}
+	return ids
+}
+
+func (h *Handler) recordTunnelMetricsFromForwardBatch(nodeID int64, forwardDeltas map[int64]tunnelTrafficDelta, metas map[int64]repo.FlowUploadForwardMeta, nowMs int64) {
+	if h == nil || h.repo == nil || nodeID <= 0 || len(forwardDeltas) == 0 {
+		return
+	}
+	bucketTs := unixMilliBucketMinute(nowMs)
+	if bucketTs <= 0 {
+		return
+	}
+	tunnelAgg := make(map[int64]tunnelTrafficDelta)
+	for forwardID, delta := range forwardDeltas {
+		meta, ok := metas[forwardID]
+		if !ok || meta.TunnelID <= 0 {
+			continue
+		}
+		current := tunnelAgg[meta.TunnelID]
+		current.bytesIn += delta.bytesIn
+		current.bytesOut += delta.bytesOut
+		tunnelAgg[meta.TunnelID] = current
+	}
+	metrics := make([]*model.TunnelMetric, 0, len(tunnelAgg))
+	for tunnelID, delta := range tunnelAgg {
+		if delta.bytesIn == 0 && delta.bytesOut == 0 {
+			continue
+		}
+		metrics = append(metrics, &model.TunnelMetric{TunnelID: tunnelID, NodeID: nodeID, Timestamp: bucketTs, BytesIn: delta.bytesIn, BytesOut: delta.bytesOut})
+	}
+	if len(metrics) == 0 {
+		return
+	}
+	if err := h.repo.UpsertTunnelMetricBuckets(metrics); err != nil {
+		log.Printf("monitoring write failed op=tunnel_metric.upsert_buckets node_id=%d bucket_ts=%d count=%d err=%v", nodeID, bucketTs, len(metrics), err)
+		return
+	}
+	log.Printf("monitoring ok op=tunnel_metric.upsert_buckets node_id=%d bucket_ts=%d count=%d", nodeID, bucketTs, len(metrics))
+}
+```
+
+- [ ] **Step 3: Run focused handler and contract tests to verify GREEN**
+
+Run:
+
+```bash
+go test ./internal/http/handler -run TestBuildFlowUploadBatchAggregatesForwardQuotaPeerShareAndCleanupTargets -v
+go test ./tests/contract/... -run TestFlowUploadAggregatesRepeatedItemsAndDisablesQuotaImmediately -v
+```
+
+Expected: PASS.
+
+- [ ] **Step 4: Run the full backend suite**
+
+Run:
+
+```bash
+go test ./...
+```
+
+Expected: PASS across the backend module.
+
+- [ ] **Step 5: Optional commit if the user explicitly requested commits**
+
+```bash
+git add go-backend/internal/http/handler/handler.go go-backend/internal/http/handler/tunnel_metrics_ingestion.go go-backend/internal/http/handler/flow_upload_batch.go go-backend/internal/http/handler/flow_upload_batch_test.go go-backend/tests/contract/flow_upload_batch_contract_test.go
+git commit -m "refactor: batch flow upload processing"
+```
+
+---
+
+### Task 4: Final Verification And Performance Sanity Check
+
+**Files:**
+- Modify: `go-backend/tests/contract/flow_upload_batch_contract_test.go`
+
+- [ ] **Step 1: Add a same-batch duplicate-item stress assertion**
+
+Extend the contract test with a second request that repeats the same service name multiple times and assert the counters advance by exactly the summed amount.
+
+```go
+body, err = json.Marshal([]map[string]interface{}{
+	{"n": "20_2_10", "u": 10, "d": 20},
+	{"n": "20_2_10", "u": 10, "d": 20},
+	{"n": "20_2_10_tcp", "u": 10, "d": 20},
+})
+if err != nil {
+	t.Fatalf("marshal body: %v", err)
+}
+req = httptest.NewRequest(http.MethodPost, "/flow/upload?secret="+node.Secret, bytes.NewReader(body))
+res = httptest.NewRecorder()
+router.ServeHTTP(res, req)
+
+if got := mustQueryInt(t, repo, `SELECT in_flow FROM forward WHERE id = 20`); got != 140 {
+	t.Fatalf("expected forward in_flow=140 after second request, got %d", got)
+}
+if got := mustQueryInt(t, repo, `SELECT out_flow FROM forward WHERE id = 20`); got != 140 {
+	t.Fatalf("expected forward out_flow=140 after second request, got %d", got)
+}
+```
+
+- [ ] **Step 2: Run the targeted contract test again**
+
+Run:
+
+```bash
+go test ./tests/contract/... -run TestFlowUploadAggregatesRepeatedItemsAndDisablesQuotaImmediately -v
+```
+
+Expected: PASS.
+
+- [ ] **Step 3: Re-run the full backend suite before claiming completion**
+
+Run:
+
+```bash
+go test ./...
+```
+
+Expected: PASS.
+
+- [ ] **Step 4: Optional local profiling sanity check**
+
+Run a short local comparison before and after the change with the same repeated flow payload.
+
+```bash
+go test ./tests/contract/... -run TestFlowUploadAggregatesRepeatedItemsAndDisablesQuotaImmediately -count=10
+```
+
+Expected: the test remains stable across repeated runs and does not introduce flakiness.
+
+- [ ] **Step 5: Optional commit if the user explicitly requested commits**
+
+```bash
+git add go-backend/tests/contract/flow_upload_batch_contract_test.go
+git commit -m "test: harden flow upload batch regression coverage"
+```

docs/superpowers/plans/2026-04-28-monitoring-retention-storage.md

@@ -0,0 +1,598 @@
+# Monitoring Retention And Storage Display Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add configurable monitoring data retention and show database storage usage on the config page.
+
+**Architecture:** Store retention in `vite_config` as `monitor_retention_days`, parse it through a focused monitoring helper, and reuse it from existing cleanup loops. Add a repository storage-summary helper, expose it via an admin-only API, and render it in the existing React config page.
+
+**Tech Stack:** Go `net/http`, GORM, SQLite/PostgreSQL, Vite/React/TypeScript, existing shadcn bridge components.
+
+---
+
+## File Structure
+
+- Create: `go-backend/internal/monitoring/retention.go` for retention constants, parsing, and validation.
+- Test: `go-backend/internal/monitoring/retention_test.go`.
+- Modify: `go-backend/internal/metrics/ingestion.go` and `go-backend/internal/metrics/ingestion_test.go` for config-driven cleanup.
+- Modify: `go-backend/internal/http/handler/tunnel_quality_prober.go` so `tunnel_quality` uses the same retention and still prunes when probing is disabled.
+- Create: `go-backend/internal/store/repo/repository_storage.go` and `go-backend/internal/store/repo/repository_storage_test.go` for database size summaries.
+- Modify: `go-backend/internal/store/repo/repository.go` to keep the SQLite DB path on `Repository`.
+- Create: `go-backend/internal/http/handler/storage.go` for the storage endpoint.
+- Modify: `go-backend/internal/http/handler/handler.go` to register `/api/v1/system/storage` and validate `monitor_retention_days`.
+- Modify: `go-backend/internal/http/middleware/auth.go` so `/api/v1/system/*` is admin-only.
+- Create: `go-backend/tests/contract/storage_contract_test.go` for endpoint auth/shape coverage.
+- Modify: `vite-frontend/src/api/types.ts`, `vite-frontend/src/api/index.ts`, and `vite-frontend/src/pages/config.tsx` for UI display.
+
+Implementation should not create git commits unless the user explicitly requests them.
+
+---
+
+### Task 1: Add Retention Config Helper
+
+**Files:**
+- Create: `go-backend/internal/monitoring/retention.go`
+- Create: `go-backend/internal/monitoring/retention_test.go`
+- Modify: `go-backend/internal/http/handler/handler.go`
+
+- [ ] **Step 1: Write the failing tests**
+
+Create `go-backend/internal/monitoring/retention_test.go`:
+
+```go
+package monitoring
+
+import "testing"
+
+func TestMonitoringRetentionDaysFromConfigMap(t *testing.T) {
+	tests := []struct {
+		name string
+		cfg  map[string]string
+		want int
+	}{
+		{"missing uses default", nil, 7},
+		{"valid custom", map[string]string{ConfigMonitorRetentionDays: "3"}, 3},
+		{"trimmed custom", map[string]string{ConfigMonitorRetentionDays: " 30 "}, 30},
+		{"invalid uses default", map[string]string{ConfigMonitorRetentionDays: "abc"}, 7},
+		{"too small uses default", map[string]string{ConfigMonitorRetentionDays: "0"}, 7},
+		{"too large uses default", map[string]string{ConfigMonitorRetentionDays: "3651"}, 7},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := MonitoringRetentionDaysFromConfigMap(tc.cfg); got != tc.want {
+				t.Fatalf("expected %d, got %d", tc.want, got)
+			}
+		})
+	}
+}
+
+func TestNormalizeMonitoringRetentionDays(t *testing.T) {
+	for _, value := range []string{"1", "7", "3650", " 30 "} {
+		if got, err := NormalizeMonitoringRetentionDays(value); err != nil || got == "" {
+			t.Fatalf("expected %q valid, got value=%q err=%v", value, got, err)
+		}
+	}
+	for _, value := range []string{"", "0", "-1", "3651", "abc", "1.5"} {
+		if got, err := NormalizeMonitoringRetentionDays(value); err == nil {
+			t.Fatalf("expected %q invalid, got value=%q", value, got)
+		}
+	}
+}
+```
+
+- [ ] **Step 2: Run tests to verify failure**
+
+Run: `go test ./internal/monitoring -run 'TestMonitoringRetentionDaysFromConfigMap|TestNormalizeMonitoringRetentionDays' -count=1`
+
+Expected: FAIL with undefined `ConfigMonitorRetentionDays`, `MonitoringRetentionDaysFromConfigMap`, and `NormalizeMonitoringRetentionDays`.
+
+- [ ] **Step 3: Implement helper**
+
+Create `go-backend/internal/monitoring/retention.go`:
+
+```go
+package monitoring
+
+import (
+	"fmt"
+	"strconv"
+	"strings"
+)
+
+const (
+	ConfigMonitorRetentionDays = "monitor_retention_days"
+	DefaultMonitorRetentionDays = 7
+	MinMonitorRetentionDays     = 1
+	MaxMonitorRetentionDays     = 3650
+)
+
+func MonitoringRetentionDaysFromConfigMap(cfg map[string]string) int {
+	if cfg == nil {
+		return DefaultMonitorRetentionDays
+	}
+	days, err := parseMonitoringRetentionDays(cfg[ConfigMonitorRetentionDays])
+	if err != nil {
+		return DefaultMonitorRetentionDays
+	}
+	return days
+}
+
+func NormalizeMonitoringRetentionDays(value string) (string, error) {
+	days, err := parseMonitoringRetentionDays(value)
+	if err != nil {
+		return "", err
+	}
+	return strconv.Itoa(days), nil
+}
+
+func parseMonitoringRetentionDays(value string) (int, error) {
+	trimmed := strings.TrimSpace(value)
+	if trimmed == "" {
+		return 0, fmt.Errorf("监控数据保留天数不能为空")
+	}
+	days, err := strconv.Atoi(trimmed)
+	if err != nil {
+		return 0, fmt.Errorf("监控数据保留天数必须是整数")
+	}
+	if days < MinMonitorRetentionDays || days > MaxMonitorRetentionDays {
+		return 0, fmt.Errorf("监控数据保留天数必须在 %d 到 %d 之间", MinMonitorRetentionDays, MaxMonitorRetentionDays)
+	}
+	return days, nil
+}
+```
+
+- [ ] **Step 4: Validate config updates**
+
+In `go-backend/internal/http/handler/handler.go`, add this case to `normalizeAndValidateConfigValue`:
+
+```go
+	case monitoring.ConfigMonitorRetentionDays:
+		return monitoring.NormalizeMonitoringRetentionDays(value)
+```
+
+- [ ] **Step 5: Run tests**
+
+Run: `go test ./internal/monitoring ./internal/http/handler -run 'TestMonitoringRetention|TestNormalize|Test' -count=1`
+
+Expected: PASS or only unrelated pre-existing failures, which must be investigated before continuing.
+
+---
+
+### Task 2: Use Retention Config In Cleanup
+
+**Files:**
+- Modify: `go-backend/internal/metrics/ingestion.go`
+- Modify: `go-backend/internal/metrics/ingestion_test.go`
+- Modify: `go-backend/internal/http/handler/tunnel_quality_prober.go`
+
+- [ ] **Step 1: Write failing cleanup test**
+
+Append to `go-backend/internal/metrics/ingestion_test.go`, adding `go-backend/internal/store/model` to imports:
+
+```go
+func TestPruneMetricsUsesConfiguredRetentionDays(t *testing.T) {
+	r, err := repo.Open(":memory:")
+	if err != nil {
+		t.Fatalf("open repo: %v", err)
+	}
+	defer r.Close()
+
+	now := time.Now().UnixMilli()
+	if err := r.UpsertConfig("monitor_retention_days", "2", now); err != nil {
+		t.Fatalf("upsert retention config: %v", err)
+	}
+
+	oldMetric := &model.NodeMetric{NodeID: 1, Timestamp: now - int64(3*24*time.Hour/time.Millisecond), CPUUsage: 10}
+	newMetric := &model.NodeMetric{NodeID: 1, Timestamp: now - int64(1*24*time.Hour/time.Millisecond), CPUUsage: 20}
+	if err := r.InsertNodeMetric(oldMetric); err != nil {
+		t.Fatalf("insert old metric: %v", err)
+	}
+	if err := r.InsertNodeMetric(newMetric); err != nil {
+		t.Fatalf("insert new metric: %v", err)
+	}
+
+	svc := NewIngestionService(r)
+	svc.pruneMetricsAt(time.UnixMilli(now))
+
+	metrics, err := r.GetNodeMetrics(1, now-int64(4*24*time.Hour/time.Millisecond), now+1000)
+	if err != nil {
+		t.Fatalf("get node metrics: %v", err)
+	}
+	if len(metrics) != 1 || metrics[0].CPUUsage != 20 {
+		t.Fatalf("expected only newer metric to remain, got %#v", metrics)
+	}
+}
+```
+
+- [ ] **Step 2: Run test to verify failure**
+
+Run: `go test ./internal/metrics -run TestPruneMetricsUsesConfiguredRetentionDays -count=1`
+
+Expected: FAIL with undefined `pruneMetricsAt`.
+
+- [ ] **Step 3: Implement config-driven prune**
+
+In `go-backend/internal/metrics/ingestion.go`, import `go-backend/internal/monitoring` and replace `pruneMetrics` with:
+
+```go
+func (s *IngestionService) retentionDaysFromConfig() int {
+	if s == nil || s.repo == nil {
+		return monitoring.DefaultMonitorRetentionDays
+	}
+	cfg, err := s.repo.GetConfigsByNames([]string{monitoring.ConfigMonitorRetentionDays})
+	if err != nil {
+		return monitoring.DefaultMonitorRetentionDays
+	}
+	return monitoring.MonitoringRetentionDaysFromConfigMap(cfg)
+}
+
+func (s *IngestionService) pruneMetrics() {
+	s.pruneMetricsAt(time.Now())
+}
+
+func (s *IngestionService) pruneMetricsAt(now time.Time) {
+	cutoff := now.Add(-time.Duration(s.retentionDaysFromConfig()) * 24 * time.Hour).UnixMilli()
+	if s.repo == nil {
+		return
+	}
+	if err := s.repo.PruneNodeMetrics(cutoff); err != nil {
+		log.Printf("monitoring prune failed op=node_metric cutoff=%d err=%v", cutoff, err)
+	}
+	if err := s.repo.PruneTunnelMetrics(cutoff); err != nil {
+		log.Printf("monitoring prune failed op=tunnel_metric cutoff=%d err=%v", cutoff, err)
+	}
+	if err := s.repo.PruneServiceMonitorResults(cutoff); err != nil {
+		log.Printf("monitoring prune failed op=service_monitor_result cutoff=%d err=%v", cutoff, err)
+	}
+}
+```
+
+Remove the unused `retentionDays` field from `IngestionService` and remove `svc.retentionDays = 1` from existing tests.
+
+- [ ] **Step 4: Update tunnel quality pruning**
+
+In `go-backend/internal/http/handler/tunnel_quality_prober.go`, import `go-backend/internal/monitoring`, remove `tunnelQualityRetention`, remove the `if !p.isEnabled() { return }` guard from `maybePrune`, and calculate cutoff with:
+
+```go
+func (p *tunnelQualityProber) retentionDays() int {
+	if p == nil || p.handler == nil || p.handler.repo == nil {
+		return monitoring.DefaultMonitorRetentionDays
+	}
+	cfg, err := p.handler.repo.GetConfigsByNames([]string{monitoring.ConfigMonitorRetentionDays})
+	if err != nil {
+		return monitoring.DefaultMonitorRetentionDays
+	}
+	return monitoring.MonitoringRetentionDaysFromConfigMap(cfg)
+}
+```
+
+Then use:
+
+```go
+	cutoff := now - int64(time.Duration(p.retentionDays())*24*time.Hour/time.Millisecond)
+```
+
+- [ ] **Step 5: Run cleanup tests**
+
+Run: `go test ./internal/metrics ./internal/http/handler -run 'TestPruneMetrics|TestPruneMetricsUsesConfiguredRetentionDays|TunnelQuality' -count=1`
+
+Expected: PASS.
+
+---
+
+### Task 3: Add Storage Summary Backend API
+
+**Files:**
+- Modify: `go-backend/internal/store/repo/repository.go`
+- Create: `go-backend/internal/store/repo/repository_storage.go`
+- Create: `go-backend/internal/store/repo/repository_storage_test.go`
+- Create: `go-backend/internal/http/handler/storage.go`
+- Modify: `go-backend/internal/http/handler/handler.go`
+- Modify: `go-backend/internal/http/middleware/auth.go`
+- Create: `go-backend/tests/contract/storage_contract_test.go`
+
+- [ ] **Step 1: Write failing repository tests**
+
+Create `go-backend/internal/store/repo/repository_storage_test.go`:
+
+```go
+package repo
+
+import (
+	"path/filepath"
+	"testing"
+
+	"go-backend/internal/store/model"
+)
+
+func TestDatabaseStorageSummarySQLiteIncludesSize(t *testing.T) {
+	dbPath := filepath.Join(t.TempDir(), "storage.db")
+	r, err := Open(dbPath)
+	if err != nil {
+		t.Fatalf("open repo: %v", err)
+	}
+	defer r.Close()
+
+	if err := r.InsertNodeMetric(&model.NodeMetric{NodeID: 1, Timestamp: 123, CPUUsage: 1}); err != nil {
+		t.Fatalf("insert metric: %v", err)
+	}
+	summary, err := r.DatabaseStorageSummary()
+	if err != nil {
+		t.Fatalf("storage summary: %v", err)
+	}
+	if summary.DBType != "sqlite" || summary.DatabaseSizeBytes <= 0 || summary.DatabaseSizeText == "" {
+		t.Fatalf("unexpected summary: %#v", summary)
+	}
+}
+
+func TestFormatDatabaseSize(t *testing.T) {
+	for _, tc := range []struct{ bytes int64; want string }{{0, "0 B"}, {512, "512 B"}, {1024, "1.0 KB"}, {1024 * 1024, "1.0 MB"}} {
+		if got := formatDatabaseSize(tc.bytes); got != tc.want {
+			t.Fatalf("formatDatabaseSize(%d)=%q want %q", tc.bytes, got, tc.want)
+		}
+	}
+}
+```
+
+- [ ] **Step 2: Run test to verify failure**
+
+Run: `go test ./internal/store/repo -run 'TestDatabaseStorageSummarySQLiteIncludesSize|TestFormatDatabaseSize' -count=1`
+
+Expected: FAIL with undefined `DatabaseStorageSummary` and `formatDatabaseSize`.
+
+- [ ] **Step 3: Implement repository helper**
+
+Modify `Repository` in `repository.go`:
+
+```go
+type Repository struct {
+	db     *gorm.DB
+	dbPath string
+}
+```
+
+Return `&Repository{db: db, dbPath: path}` from `Open` and `&Repository{db: db}` from `OpenPostgres`.
+
+Create `go-backend/internal/store/repo/repository_storage.go`:
+
+```go
+package repo
+
+import (
+	"errors"
+	"fmt"
+	"os"
+)
+
+type DatabaseStorageSummary struct {
+	DBType            string `json:"dbType"`
+	DatabaseSizeBytes int64  `json:"databaseSizeBytes"`
+	DatabaseSizeText  string `json:"databaseSizeText"`
+}
+
+func (r *Repository) DatabaseStorageSummary() (DatabaseStorageSummary, error) {
+	if r == nil || r.db == nil {
+		return DatabaseStorageSummary{}, errors.New("repository not initialized")
+	}
+	switch r.db.Dialector.Name() {
+	case "sqlite":
+		size, err := sqliteDatabaseFileSize(r.dbPath)
+		if err != nil { return DatabaseStorageSummary{}, err }
+		return DatabaseStorageSummary{"sqlite", size, formatDatabaseSize(size)}, nil
+	case "postgres":
+		var size int64
+		if err := r.db.Raw("SELECT pg_database_size(current_database())").Scan(&size).Error; err != nil { return DatabaseStorageSummary{}, err }
+		return DatabaseStorageSummary{"postgres", size, formatDatabaseSize(size)}, nil
+	default:
+		return DatabaseStorageSummary{}, fmt.Errorf("unsupported database dialect %q", r.db.Dialector.Name())
+	}
+}
+
+func sqliteDatabaseFileSize(path string) (int64, error) {
+	if path == "" || path == ":memory:" { return 0, nil }
+	var total int64
+	for _, candidate := range []string{path, path + "-wal", path + "-shm"} {
+		info, err := os.Stat(candidate)
+		if err != nil {
+			if os.IsNotExist(err) { continue }
+			return 0, err
+		}
+		if !info.IsDir() { total += info.Size() }
+	}
+	return total, nil
+}
+
+func formatDatabaseSize(bytes int64) string {
+	if bytes < 1024 { return fmt.Sprintf("%d B", bytes) }
+	units := []string{"KB", "MB", "GB", "TB"}
+	value := float64(bytes) / 1024
+	for _, unit := range units {
+		if value < 1024 || unit == "TB" { return fmt.Sprintf("%.1f %s", value, unit) }
+		value /= 1024
+	}
+	return fmt.Sprintf("%d B", bytes)
+}
+```
+
+- [ ] **Step 4: Add API handler and route**
+
+Create `go-backend/internal/http/handler/storage.go`:
+
+```go
+package handler
+
+import (
+	"net/http"
+
+	"go-backend/internal/http/response"
+)
+
+func (h *Handler) storageSummary(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet && r.Method != http.MethodPost {
+		response.WriteJSON(w, response.ErrDefault("请求失败"))
+		return
+	}
+	if h == nil || h.repo == nil {
+		response.WriteJSON(w, response.Err(-2, "repository not initialized"))
+		return
+	}
+	summary, err := h.repo.DatabaseStorageSummary()
+	if err != nil {
+		response.WriteJSON(w, response.Err(-2, err.Error()))
+		return
+	}
+	response.WriteJSON(w, response.OK(summary))
+}
+```
+
+Register in `Handler.Register`: `mux.HandleFunc("/api/v1/system/storage", h.storageSummary)`.
+
+In `requiresAdmin`, add:
+
+```go
+	if strings.HasPrefix(path, "/api/v1/system/") {
+		return true
+	}
+```
+
+- [ ] **Step 5: Write contract test for auth and shape**
+
+Create `go-backend/tests/contract/storage_contract_test.go` with a test that sends GET `/api/v1/system/storage` as non-admin and expects `403`, then as admin and expects `code == 0`, `dbType`, numeric `databaseSizeBytes`, and `databaseSizeText`.
+
+- [ ] **Step 6: Run storage tests**
+
+Run: `go test ./internal/store/repo ./tests/contract -run 'TestDatabaseStorageSummarySQLiteIncludesSize|TestFormatDatabaseSize|TestStorageSummaryRequiresAdminAndReturnsSize' -count=1`
+
+Expected: PASS.
+
+---
+
+### Task 4: Add Frontend Config UI
+
+**Files:**
+- Modify: `vite-frontend/src/api/types.ts`
+- Modify: `vite-frontend/src/api/index.ts`
+- Modify: `vite-frontend/src/pages/config.tsx`
+
+- [ ] **Step 1: Add API type and function**
+
+In `types.ts` add:
+
+```ts
+export interface StorageSummaryApiData {
+  dbType: string;
+  databaseSizeBytes: number;
+  databaseSizeText: string;
+}
+```
+
+In `index.ts`, import `StorageSummaryApiData` and add:
+
+```ts
+export const getStorageSummary = () =>
+  Network.get<StorageSummaryApiData>("/system/storage");
+```
+
+- [ ] **Step 2: Add retention config item**
+
+In `config.tsx`, add to `CONFIG_ITEMS` near monitoring:
+
+```ts
+  {
+    key: "monitor_retention_days",
+    label: "监控数据保留天数",
+    placeholder: "7",
+    description:
+      "统一清理节点指标、隧道流量、服务监控结果和隧道质量历史；默认 7 天。",
+    type: "input",
+  },
+```
+
+Add `"monitor_retention_days"` to `getInitialConfigs()` keys.
+
+- [ ] **Step 3: Fetch and display database size**
+
+In `config.tsx`, add state:
+
+```ts
+const [storageSummary, setStorageSummary] = useState<string>("加载中...");
+```
+
+Add a load effect:
+
+```ts
+useEffect(() => {
+  let mounted = true;
+  getStorageSummary()
+    .then((response) => {
+      if (!mounted) return;
+      if (response.code === 0 && response.data?.databaseSizeText) {
+        setStorageSummary(response.data.databaseSizeText);
+      } else {
+        setStorageSummary("获取失败");
+      }
+    })
+    .catch(() => {
+      if (mounted) setStorageSummary("获取失败");
+    });
+  return () => {
+    mounted = false;
+  };
+}, []);
+```
+
+Render inside the basic settings card before the save button:
+
+```tsx
+<Divider className="my-2" />
+<div className="space-y-1">
+  <p className="text-sm font-medium text-gray-700 dark:text-gray-300">
+    数据库占用
+  </p>
+  <p className="text-xs text-gray-500 dark:text-gray-400">
+    当前后端数据库文件/实例占用空间，仅用于容量参考。
+  </p>
+  <div className="rounded-lg border border-divider bg-default-50/60 dark:bg-default-100/10 px-4 py-3 text-sm font-semibold text-default-800 dark:text-default-200">
+    {storageSummary}
+  </div>
+</div>
+```
+
+- [ ] **Step 4: Build frontend**
+
+Run: `pnpm run build` from `vite-frontend`.
+
+Expected: TypeScript and Vite build pass.
+
+---
+
+### Task 5: Final Verification
+
+**Files:**
+- All files changed by previous tasks.
+
+- [ ] **Step 1: Run backend tests**
+
+Run: `go test ./...` from `go-backend`.
+
+Expected: PASS.
+
+- [ ] **Step 2: Run frontend build**
+
+Run: `pnpm run build` from `vite-frontend`.
+
+Expected: PASS.
+
+- [ ] **Step 3: Review diff**
+
+Run: `git diff --stat` and `git diff -- docs/superpowers/specs/2026-04-28-monitoring-retention-storage-design.md docs/superpowers/plans/2026-04-28-monitoring-retention-storage.md go-backend vite-frontend`.
+
+Expected: Diff is limited to retention config, storage summary, tests, and config UI.
+
+---
+
+## Self-Review
+
+- Spec coverage: retention config, uniform cleanup, storage summary API, frontend display, validation, and verification are covered.
+- Placeholder scan: no TBD/TODO placeholders; the one contract-test step describes exact assertions even though the surrounding helper functions already exist in contract tests.
+- Type consistency: backend JSON fields match frontend `StorageSummaryApiData` exactly: `dbType`, `databaseSizeBytes`, `databaseSizeText`.

docs/superpowers/plans/2026-05-01-best-exit-current-display.md

@@ -0,0 +1,892 @@
+# Best Exit Current Display Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Show the currently applied `best` exit selection in the tunnel list information, including per-entry/per-final-hop details for multi-owner tunnels.
+
+**Architecture:** Add a backend-only display layer that snapshots `bestExitManager` state and attaches `bestExitState` to existing `tunnelList`/`tunnelGet` responses. Render that state in the existing tunnel table/grid topology area using compact text and a native `title` detail tooltip. No routing, scoring, persistence, polling, or runtime update behavior changes.
+
+**Tech Stack:** Go `net/http` handlers + existing repository methods, React/TypeScript in `vite-frontend/src/pages/tunnel.tsx`, Tailwind/shadcn bridge components already in the file.
+
+---
+
+## File Structure
+
+- Create `go-backend/internal/http/handler/tunnel_best_exit_display.go`: response DTOs, manager snapshot method, tunnel-response parsing helpers, and `Handler.attachBestExitStates`.
+- Create `go-backend/internal/http/handler/tunnel_best_exit_display_test.go`: backend display-state unit tests.
+- Modify `go-backend/internal/http/handler/handler.go`: call `h.attachBestExitStatesOrLog(items)` in `tunnelList`.
+- Modify `go-backend/internal/http/handler/mutations.go`: call `h.attachBestExitStatesOrLog(items)` before returning a single tunnel in `tunnelGet`.
+- Modify `vite-frontend/src/pages/tunnel.tsx`: add `bestExitState` types, map API state, helper render functions, and table/grid display.
+
+---
+
+### Task 1: Backend Snapshot And Display-State Tests
+
+**Files:**
+- Create: `go-backend/internal/http/handler/tunnel_best_exit_display_test.go`
+
+- [ ] **Step 1: Write failing backend display tests**
+
+Create `go-backend/internal/http/handler/tunnel_best_exit_display_test.go`:
+
+```go
+package handler
+
+import (
+	"testing"
+	"time"
+)
+
+func TestBestExitDecisionSnapshotIsDefensiveCopy(t *testing.T) {
+	m := newBestExitManager()
+	key := bestExitOwnerKey{TunnelID: 77, OwnerNodeID: 10}
+	now := time.Unix(100, 0)
+	score := scoreBestExitCandidate(10, chainNodeRecord{NodeID: 30, NodeName: "exit-a"}, 10, 0, 20, 0)
+
+	m.observeScores(key, []bestExitCandidateScore{score}, now)
+	snapshot, ok := m.snapshot(key)
+	if !ok {
+		t.Fatalf("expected snapshot")
+	}
+	if snapshot.AppliedExitNodeID != 30 || snapshot.UpdatedAt != now.UnixMilli() {
+		t.Fatalf("unexpected snapshot: %+v", snapshot)
+	}
+	if len(snapshot.Scores) != 1 {
+		t.Fatalf("expected one score in snapshot, got %+v", snapshot.Scores)
+	}
+	snapshot.Scores[0].ExitNodeID = 99
+
+	again, ok := m.snapshot(key)
+	if !ok {
+		t.Fatalf("expected second snapshot")
+	}
+	if again.Scores[0].ExitNodeID != 30 {
+		t.Fatalf("snapshot score mutation leaked into manager state: %+v", again.Scores)
+	}
+}
+
+func TestBuildBestExitDisplayStateForDirectMultiEntryOwners(t *testing.T) {
+	m := newBestExitManager()
+	now := time.Unix(100, 0)
+	m.setApplied(bestExitOwnerKey{TunnelID: 77, OwnerNodeID: 10}, 30, now)
+	m.setApplied(bestExitOwnerKey{TunnelID: 77, OwnerNodeID: 11}, 31, now.Add(time.Second))
+
+	tunnel := map[string]interface{}{
+		"id": int64(77),
+		"inNodeId": []map[string]interface{}{
+			{"nodeId": int64(10)},
+			{"nodeId": int64(11)},
+		},
+		"outNodeId": []map[string]interface{}{
+			{"nodeId": int64(30), "strategy": tunnelStrategyBest},
+			{"nodeId": int64(31), "strategy": tunnelStrategyBest},
+		},
+		"chainNodes": [][]map[string]interface{}{},
+	}
+	names := map[int64]string{10: "入口 A", 11: "入口 B", 30: "香港节点", 31: "日本节点"}
+
+	state, ok := buildBestExitDisplayState(tunnel, m, testBestExitNameLookup(names))
+	if !ok {
+		t.Fatalf("expected best exit state")
+	}
+	if !state.Enabled || state.Summary != "多个出口" || state.Status != "applied" {
+		t.Fatalf("unexpected state summary: %+v", state)
+	}
+	if state.UpdatedAt != now.Add(time.Second).UnixMilli() {
+		t.Fatalf("expected latest updatedAt, got %d", state.UpdatedAt)
+	}
+	if len(state.Items) != 2 {
+		t.Fatalf("expected two owner items, got %+v", state.Items)
+	}
+	if state.Items[0].OwnerRole != "entry" || state.Items[0].OwnerNodeName != "入口 A" || state.Items[0].ExitNodeName != "香港节点" {
+		t.Fatalf("unexpected first item: %+v", state.Items[0])
+	}
+	if state.Items[1].OwnerRole != "entry" || state.Items[1].OwnerNodeName != "入口 B" || state.Items[1].ExitNodeName != "日本节点" {
+		t.Fatalf("unexpected second item: %+v", state.Items[1])
+	}
+}
+
+func TestBuildBestExitDisplayStateForFinalChainHopOwners(t *testing.T) {
+	m := newBestExitManager()
+	now := time.Unix(200, 0)
+	m.setApplied(bestExitOwnerKey{TunnelID: 88, OwnerNodeID: 20}, 30, now)
+	m.setApplied(bestExitOwnerKey{TunnelID: 88, OwnerNodeID: 21}, 30, now.Add(time.Second))
+
+	tunnel := map[string]interface{}{
+		"id": int64(88),
+		"inNodeId": []map[string]interface{}{
+			{"nodeId": int64(10)},
+		},
+		"outNodeId": []map[string]interface{}{
+			{"nodeId": int64(30), "strategy": tunnelStrategyBest},
+			{"nodeId": int64(31), "strategy": tunnelStrategyBest},
+		},
+		"chainNodes": [][]map[string]interface{}{
+			{{"nodeId": int64(15), "inx": int64(0)}},
+			{{"nodeId": int64(20), "inx": int64(1)}, {"nodeId": int64(21), "inx": int64(1)}},
+		},
+	}
+	names := map[int64]string{20: "中转 M1", 21: "中转 M2", 30: "香港节点", 31: "日本节点"}
+
+	state, ok := buildBestExitDisplayState(tunnel, m, testBestExitNameLookup(names))
+	if !ok {
+		t.Fatalf("expected best exit state")
+	}
+	if state.Summary != "香港节点" || state.Status != "applied" {
+		t.Fatalf("expected single-exit summary, got %+v", state)
+	}
+	if len(state.Items) != 2 {
+		t.Fatalf("expected two final-hop owner items, got %+v", state.Items)
+	}
+	if state.Items[0].OwnerRole != "chain" || state.Items[0].OwnerNodeName != "中转 M1" || state.Items[0].ExitNodeName != "香港节点" {
+		t.Fatalf("unexpected first chain owner item: %+v", state.Items[0])
+	}
+	if state.Items[1].OwnerRole != "chain" || state.Items[1].OwnerNodeName != "中转 M2" || state.Items[1].ExitNodeName != "香港节点" {
+		t.Fatalf("unexpected second chain owner item: %+v", state.Items[1])
+	}
+}
+
+func TestBuildBestExitDisplayStateWaitingWhenNoAppliedDecisionExists(t *testing.T) {
+	tunnel := map[string]interface{}{
+		"id": int64(77),
+		"inNodeId": []map[string]interface{}{
+			{"nodeId": int64(10)},
+		},
+		"outNodeId": []map[string]interface{}{
+			{"nodeId": int64(30), "strategy": tunnelStrategyBest},
+			{"nodeId": int64(31), "strategy": tunnelStrategyBest},
+		},
+		"chainNodes": [][]map[string]interface{}{},
+	}
+	names := map[int64]string{10: "入口 A", 30: "香港节点", 31: "日本节点"}
+
+	state, ok := buildBestExitDisplayState(tunnel, newBestExitManager(), testBestExitNameLookup(names))
+	if !ok {
+		t.Fatalf("expected waiting best exit state")
+	}
+	if state.Summary != "等待探测" || state.Status != "waiting" {
+		t.Fatalf("expected waiting state, got %+v", state)
+	}
+	if len(state.Items) != 1 || state.Items[0].ExitNodeID != 0 || state.Items[0].ExitNodeName != "等待探测" {
+		t.Fatalf("unexpected waiting item: %+v", state.Items)
+	}
+}
+
+func TestBuildBestExitDisplayStateSkipsNonBestAndSingleExitTunnels(t *testing.T) {
+	nonBest := map[string]interface{}{
+		"id":       int64(77),
+		"inNodeId": []map[string]interface{}{{"nodeId": int64(10)}},
+		"outNodeId": []map[string]interface{}{
+			{"nodeId": int64(30), "strategy": "round"},
+			{"nodeId": int64(31), "strategy": "round"},
+		},
+	}
+	if state, ok := buildBestExitDisplayState(nonBest, newBestExitManager(), testBestExitNameLookup(nil)); ok || state != nil {
+		t.Fatalf("expected non-best tunnel to skip state, got %+v", state)
+	}
+
+	singleExit := map[string]interface{}{
+		"id":       int64(78),
+		"inNodeId": []map[string]interface{}{{"nodeId": int64(10)}},
+		"outNodeId": []map[string]interface{}{
+			{"nodeId": int64(30), "strategy": tunnelStrategyBest},
+		},
+	}
+	if state, ok := buildBestExitDisplayState(singleExit, newBestExitManager(), testBestExitNameLookup(nil)); ok || state != nil {
+		t.Fatalf("expected single-exit tunnel to skip state, got %+v", state)
+	}
+}
+
+func testBestExitNameLookup(names map[int64]string) bestExitNodeNameLookup {
+	return func(nodeID int64) (string, bool) {
+		name := names[nodeID]
+		return name, name != ""
+	}
+}
+```
+
+- [ ] **Step 2: Run backend display tests to verify failure**
+
+Run from `go-backend`:
+
+```bash
+go test ./internal/http/handler -run 'TestBestExitDecisionSnapshot|TestBuildBestExitDisplayState' -count=1
+```
+
+Expected: FAIL with undefined `snapshot`, `buildBestExitDisplayState`, and `bestExitNodeNameLookup`.
+
+---
+
+### Task 2: Backend Display State Implementation
+
+**Files:**
+- Create: `go-backend/internal/http/handler/tunnel_best_exit_display.go`
+- Modify: `go-backend/internal/http/handler/tunnel_best_exit.go`
+- Test: `go-backend/internal/http/handler/tunnel_best_exit_display_test.go`
+
+- [ ] **Step 1: Implement display state and snapshot helpers**
+
+Create `go-backend/internal/http/handler/tunnel_best_exit_display.go`:
+
+```go
+package handler
+
+import (
+	"log"
+	"strings"
+)
+
+const (
+	bestExitDisplayStatusApplied = "applied"
+	bestExitDisplayStatusWaiting = "waiting"
+	bestExitDisplaySummaryMulti  = "多个出口"
+	bestExitDisplaySummaryWait   = "等待探测"
+	bestExitUnknownExitName      = "未知出口"
+	bestExitUnknownEntryName     = "未知入口"
+	bestExitUnknownChainName     = "未知中转"
+)
+
+type bestExitDecisionSnapshot struct {
+	AppliedExitNodeID int64
+	UpdatedAt         int64
+	Reason            string
+	Scores            []bestExitCandidateScore
+}
+
+type bestExitDisplayState struct {
+	Enabled   bool                  `json:"enabled"`
+	Summary   string                `json:"summary"`
+	Status    string                `json:"status"`
+	UpdatedAt int64                 `json:"updatedAt,omitempty"`
+	Reason    string                `json:"reason,omitempty"`
+	Items     []bestExitDisplayItem `json:"items"`
+}
+
+type bestExitDisplayItem struct {
+	OwnerNodeID   int64  `json:"ownerNodeId"`
+	OwnerNodeName string `json:"ownerNodeName"`
+	OwnerRole     string `json:"ownerRole"`
+	ExitNodeID    int64  `json:"exitNodeId,omitempty"`
+	ExitNodeName  string `json:"exitNodeName"`
+	UpdatedAt     int64  `json:"updatedAt,omitempty"`
+	Reason        string `json:"reason,omitempty"`
+}
+
+type bestExitNodeNameLookup func(nodeID int64) (string, bool)
+
+func (m *bestExitManager) snapshot(key bestExitOwnerKey) (bestExitDecisionSnapshot, bool) {
+	if m == nil {
+		return bestExitDecisionSnapshot{}, false
+	}
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	d := m.decisions[key]
+	if d == nil {
+		return bestExitDecisionSnapshot{}, false
+	}
+	updatedAt := int64(0)
+	if !d.LastSwitchAt.IsZero() {
+		updatedAt = d.LastSwitchAt.UnixMilli()
+	}
+	return bestExitDecisionSnapshot{
+		AppliedExitNodeID: d.AppliedExitNodeID,
+		UpdatedAt:         updatedAt,
+		Reason:            d.LastReason,
+		Scores:            cloneBestExitScores(d.Scores),
+	}, true
+}
+
+func (h *Handler) attachBestExitStates(items []map[string]interface{}) {
+	if h == nil || len(items) == 0 {
+		return
+	}
+	lookup := h.bestExitNodeNameLookup()
+	for _, item := range items {
+		state, ok := buildBestExitDisplayState(item, h.bestExit, lookup)
+		if !ok {
+			delete(item, "bestExitState")
+			continue
+		}
+		item["bestExitState"] = state
+	}
+}
+
+func (h *Handler) bestExitNodeNameLookup() bestExitNodeNameLookup {
+	cache := map[int64]string{}
+	return func(nodeID int64) (string, bool) {
+		if nodeID <= 0 || h == nil {
+			return "", false
+		}
+		if name, ok := cache[nodeID]; ok {
+			return name, name != ""
+		}
+		node, err := h.getNodeRecord(nodeID)
+		if err != nil || node == nil {
+			cache[nodeID] = ""
+			return "", false
+		}
+		name := strings.TrimSpace(node.Name)
+		cache[nodeID] = name
+		return name, name != ""
+	}
+}
+
+func buildBestExitDisplayState(tunnel map[string]interface{}, manager *bestExitManager, lookup bestExitNodeNameLookup) (*bestExitDisplayState, bool) {
+	if tunnel == nil {
+		return nil, false
+	}
+	tunnelID := asInt64(tunnel["id"], 0)
+	outNodes := bestExitDisplayMapSlice(tunnel["outNodeId"])
+	if tunnelID <= 0 || len(outNodes) <= 1 {
+		return nil, false
+	}
+	if !isBestTunnelStrategy(asString(outNodes[0]["strategy"])) {
+		return nil, false
+	}
+
+	owners, ownerRole := bestExitDisplayOwners(tunnel)
+	state := &bestExitDisplayState{
+		Enabled: true,
+		Summary: bestExitDisplaySummaryWait,
+		Status:  bestExitDisplayStatusWaiting,
+		Items:   make([]bestExitDisplayItem, 0, len(owners)),
+	}
+
+	exitsByID := map[int64]map[string]interface{}{}
+	for _, exit := range outNodes {
+		if id := asInt64(exit["nodeId"], 0); id > 0 {
+			exitsByID[id] = exit
+		}
+	}
+	appliedExitIDs := map[int64]string{}
+	appliedCount := 0
+	latestUpdatedAt := int64(0)
+	latestReason := ""
+	for _, owner := range owners {
+		ownerNodeID := asInt64(owner["nodeId"], 0)
+		if ownerNodeID <= 0 {
+			continue
+		}
+		item := bestExitDisplayItem{
+			OwnerNodeID:   ownerNodeID,
+			OwnerNodeName: bestExitDisplayNodeName(owner, ownerNodeID, lookup, bestExitUnknownOwnerName(ownerRole)),
+			OwnerRole:     ownerRole,
+			ExitNodeName:  bestExitDisplaySummaryWait,
+			Reason:        bestExitDisplayStatusWaiting,
+		}
+		if snapshot, ok := manager.snapshot(bestExitOwnerKey{TunnelID: tunnelID, OwnerNodeID: ownerNodeID}); ok && snapshot.AppliedExitNodeID > 0 {
+			item.ExitNodeID = snapshot.AppliedExitNodeID
+			item.ExitNodeName = bestExitDisplayNodeName(exitsByID[snapshot.AppliedExitNodeID], snapshot.AppliedExitNodeID, lookup, bestExitUnknownExitName)
+			item.UpdatedAt = snapshot.UpdatedAt
+			item.Reason = snapshot.Reason
+			appliedExitIDs[item.ExitNodeID] = item.ExitNodeName
+			appliedCount++
+			if snapshot.UpdatedAt > latestUpdatedAt {
+				latestUpdatedAt = snapshot.UpdatedAt
+				latestReason = snapshot.Reason
+			}
+		}
+		state.Items = append(state.Items, item)
+	}
+
+	if appliedCount == 0 {
+		return state, true
+	}
+	state.Status = bestExitDisplayStatusApplied
+	state.UpdatedAt = latestUpdatedAt
+	state.Reason = latestReason
+	if len(appliedExitIDs) == 1 {
+		for _, name := range appliedExitIDs {
+			state.Summary = name
+		}
+	} else {
+		state.Summary = bestExitDisplaySummaryMulti
+	}
+	return state, true
+}
+
+func bestExitDisplayOwners(tunnel map[string]interface{}) ([]map[string]interface{}, string) {
+	chainGroups := bestExitDisplayChainGroups(tunnel["chainNodes"])
+	if len(chainGroups) > 0 {
+		return chainGroups[len(chainGroups)-1], "chain"
+	}
+	return bestExitDisplayMapSlice(tunnel["inNodeId"]), "entry"
+}
+
+func bestExitDisplayMapSlice(v interface{}) []map[string]interface{} {
+	switch arr := v.(type) {
+	case []map[string]interface{}:
+		return arr
+	case []interface{}:
+		out := make([]map[string]interface{}, 0, len(arr))
+		for _, item := range arr {
+			if m, ok := item.(map[string]interface{}); ok {
+				out = append(out, m)
+			}
+		}
+		return out
+	default:
+		return nil
+	}
+}
+
+func bestExitDisplayChainGroups(v interface{}) [][]map[string]interface{} {
+	switch groups := v.(type) {
+	case [][]map[string]interface{}:
+		return groups
+	case []interface{}:
+		out := make([][]map[string]interface{}, 0, len(groups))
+		for _, group := range groups {
+			items := bestExitDisplayMapSlice(group)
+			if len(items) > 0 {
+				out = append(out, items)
+			}
+		}
+		return out
+	default:
+		return nil
+	}
+}
+
+func bestExitDisplayNodeName(source map[string]interface{}, nodeID int64, lookup bestExitNodeNameLookup, fallback string) string {
+	if source != nil {
+		for _, key := range []string{"nodeName", "name"} {
+			if name := strings.TrimSpace(asString(source[key])); name != "" {
+				return name
+			}
+		}
+	}
+	if lookup != nil {
+		if name, ok := lookup(nodeID); ok && strings.TrimSpace(name) != "" {
+			return strings.TrimSpace(name)
+		}
+	}
+	return fallback
+}
+
+func bestExitUnknownOwnerName(role string) string {
+	if role == "chain" {
+		return bestExitUnknownChainName
+	}
+	return bestExitUnknownEntryName
+}
+
+func (h *Handler) attachBestExitStatesOrLog(items []map[string]interface{}) {
+	defer func() {
+		if recovered := recover(); recovered != nil {
+			log.Printf("best_exit: attach display state failed: %v", recovered)
+		}
+	}()
+	h.attachBestExitStates(items)
+}
+```
+
+- [ ] **Step 2: Replace direct attach calls with panic-safe wrapper**
+
+Keep `attachBestExitStates` for tests, and use `attachBestExitStatesOrLog` from handlers in Task 3. This step only creates the function above; no handler wiring yet.
+
+- [ ] **Step 3: Run backend display tests**
+
+Run from `go-backend`:
+
+```bash
+go test ./internal/http/handler -run 'TestBestExitDecisionSnapshot|TestBuildBestExitDisplayState' -count=1
+```
+
+Expected: PASS.
+
+- [ ] **Step 4: Run gofmt**
+
+```bash
+gofmt -w internal/http/handler/tunnel_best_exit_display.go internal/http/handler/tunnel_best_exit_display_test.go
+```
+
+- [ ] **Step 5: Commit backend display implementation**
+
+```bash
+git add go-backend/internal/http/handler/tunnel_best_exit_display.go go-backend/internal/http/handler/tunnel_best_exit_display_test.go
+git commit -m "feat: build best exit display state"
+```
+
+---
+
+### Task 3: Attach Best-Exit State To Tunnel List And Get Responses
+
+**Files:**
+- Modify: `go-backend/internal/http/handler/handler.go`
+- Modify: `go-backend/internal/http/handler/mutations.go`
+- Test: `go-backend/internal/http/handler/tunnel_best_exit_display_test.go`
+
+- [ ] **Step 1: Write failing handler attach tests**
+
+Append to `go-backend/internal/http/handler/tunnel_best_exit_display_test.go`:
+
+```go
+func TestAttachBestExitStatesAddsStateToBestTunnelOnly(t *testing.T) {
+	h := &Handler{bestExit: newBestExitManager()}
+	now := time.Unix(300, 0)
+	h.bestExit.setApplied(bestExitOwnerKey{TunnelID: 77, OwnerNodeID: 10}, 30, now)
+
+	items := []map[string]interface{}{
+		{
+			"id":       int64(77),
+			"inNodeId": []map[string]interface{}{{"nodeId": int64(10)}},
+			"outNodeId": []map[string]interface{}{
+				{"nodeId": int64(30), "strategy": tunnelStrategyBest},
+				{"nodeId": int64(31), "strategy": tunnelStrategyBest},
+			},
+		},
+		{
+			"id":       int64(78),
+			"inNodeId": []map[string]interface{}{{"nodeId": int64(12)}},
+			"outNodeId": []map[string]interface{}{
+				{"nodeId": int64(40), "strategy": "round"},
+				{"nodeId": int64(41), "strategy": "round"},
+			},
+		},
+	}
+
+	h.attachBestExitStates(items)
+	state, ok := items[0]["bestExitState"].(*bestExitDisplayState)
+	if !ok {
+		t.Fatalf("expected bestExitState on best tunnel, got %#v", items[0]["bestExitState"])
+	}
+	if state.Summary != bestExitUnknownExitName || state.Items[0].ExitNodeID != 30 {
+		t.Fatalf("unexpected state with fallback names: %+v", state)
+	}
+	if _, exists := items[1]["bestExitState"]; exists {
+		t.Fatalf("non-best tunnel should not have bestExitState: %+v", items[1])
+	}
+}
+```
+
+- [ ] **Step 2: Run attach test to verify failure**
+
+Run from `go-backend`:
+
+```bash
+go test ./internal/http/handler -run TestAttachBestExitStatesAddsStateToBestTunnelOnly -count=1
+```
+
+Expected: PASS.
+
+- [ ] **Step 3: Wire tunnel list response**
+
+In `go-backend/internal/http/handler/handler.go`, change `tunnelList` from:
+
+```go
+	items, err := h.repo.ListTunnels()
+	if err != nil {
+		response.WriteJSON(w, response.Err(-2, err.Error()))
+		return
+	}
+	response.WriteJSON(w, response.OK(items))
+```
+
+to:
+
+```go
+	items, err := h.repo.ListTunnels()
+	if err != nil {
+		response.WriteJSON(w, response.Err(-2, err.Error()))
+		return
+	}
+	h.attachBestExitStatesOrLog(items)
+	response.WriteJSON(w, response.OK(items))
+```
+
+- [ ] **Step 4: Wire single tunnel response**
+
+In `go-backend/internal/http/handler/mutations.go`, change `tunnelGet` from:
+
+```go
+	items, err := h.repo.ListTunnels()
+	if err != nil {
+		response.WriteJSON(w, response.Err(-2, err.Error()))
+		return
+	}
+	for _, it := range items {
+		if asInt64(it["id"], 0) == id {
+			response.WriteJSON(w, response.OK(it))
+			return
+		}
+	}
+```
+
+to:
+
+```go
+	items, err := h.repo.ListTunnels()
+	if err != nil {
+		response.WriteJSON(w, response.Err(-2, err.Error()))
+		return
+	}
+	h.attachBestExitStatesOrLog(items)
+	for _, it := range items {
+		if asInt64(it["id"], 0) == id {
+			response.WriteJSON(w, response.OK(it))
+			return
+		}
+	}
+```
+
+- [ ] **Step 5: Run focused backend tests**
+
+Run from `go-backend`:
+
+```bash
+go test ./internal/http/handler -run 'TestBestExitDecisionSnapshot|TestBuildBestExitDisplayState|TestAttachBestExitStatesAddsStateToBestTunnelOnly' -count=1
+```
+
+Expected: PASS.
+
+- [ ] **Step 6: Run gofmt**
+
+```bash
+gofmt -w internal/http/handler/handler.go internal/http/handler/mutations.go internal/http/handler/tunnel_best_exit_display.go internal/http/handler/tunnel_best_exit_display_test.go
+```
+
+- [ ] **Step 7: Commit response wiring**
+
+```bash
+git add go-backend/internal/http/handler/handler.go go-backend/internal/http/handler/mutations.go go-backend/internal/http/handler/tunnel_best_exit_display.go go-backend/internal/http/handler/tunnel_best_exit_display_test.go
+git commit -m "feat: expose best exit display state"
+```
+
+---
+
+### Task 4: Frontend Tunnel List Display
+
+**Files:**
+- Modify: `vite-frontend/src/pages/tunnel.tsx`
+
+- [ ] **Step 1: Add TypeScript types**
+
+In `vite-frontend/src/pages/tunnel.tsx`, add these interfaces after `interface ChainTunnel`:
+
+```ts
+interface BestExitStateItem {
+  ownerNodeId: number;
+  ownerNodeName: string;
+  ownerRole: "entry" | "chain";
+  exitNodeId?: number;
+  exitNodeName: string;
+  updatedAt?: number;
+  reason?: string;
+}
+
+interface BestExitState {
+  enabled: boolean;
+  summary: string;
+  status: "applied" | "waiting";
+  updatedAt?: number;
+  reason?: string;
+  items: BestExitStateItem[];
+}
+```
+
+Then add the optional field to `interface Tunnel`:
+
+```ts
+  bestExitState?: BestExitState | null;
+```
+
+- [ ] **Step 2: Preserve API state during mapping**
+
+In `mapTunnelApiItems`, add `bestExitState` to the returned object:
+
+```ts
+    bestExitState:
+      tunnel.bestExitState && typeof tunnel.bestExitState === "object"
+        ? {
+            ...tunnel.bestExitState,
+            items: Array.isArray(tunnel.bestExitState.items)
+              ? tunnel.bestExitState.items
+              : [],
+          }
+        : null,
+```
+
+The mapped object should include this field before `createdTime` or immediately after it.
+
+- [ ] **Step 3: Add render helpers**
+
+Add these helper functions after `mapTunnelApiItems` and before `export default function TunnelPage()`:
+
+```tsx
+const bestExitOwnerRoleText = (role: BestExitStateItem["ownerRole"]) => {
+  return role === "chain" ? "中转" : "入口";
+};
+
+const bestExitDetailTitle = (state?: BestExitState | null) => {
+  if (!state?.enabled || !state.items?.length) {
+    return "";
+  }
+  return state.items
+    .map((item) => {
+      const ownerName = item.ownerNodeName || `${bestExitOwnerRoleText(item.ownerRole)} ${item.ownerNodeId}`;
+      const exitName = item.exitNodeName || "等待探测";
+      return `${ownerName} -> ${exitName}`;
+    })
+    .join("\n");
+};
+
+const renderBestExitState = (state?: BestExitState | null) => {
+  if (!state?.enabled) {
+    return null;
+  }
+  const title = bestExitDetailTitle(state);
+  const isWaiting = state.status === "waiting";
+
+  return (
+    <div
+      className={`mt-1 text-[11px] leading-4 ${
+        isWaiting
+          ? "text-default-500"
+          : "text-emerald-700 dark:text-emerald-300"
+      }`}
+      title={title || undefined}
+    >
+      最优出口：{state.summary || "等待探测"}
+    </div>
+  );
+};
+```
+
+- [ ] **Step 4: Render in table topology cell**
+
+In the table topology `<TableCell>` around line 1674, change the cell content from:
+
+```tsx
+                        <div className="flex items-center gap-1.5 text-xs">
+                          <span className="font-semibold text-primary-700 dark:text-primary-400">
+                            {tunnel.inNodeId?.length || 0}入口
+                          </span>
+                          <span className="text-default-400">→</span>
+                          <span className="font-semibold text-secondary-700 dark:text-secondary-400">
+                            {tunnel.type === 2
+                              ? tunnel.chainNodes?.length || 0
+                              : 0}
+                            跳
+                          </span>
+                          <span className="text-default-400">→</span>
+                          <span className="font-semibold text-success-700 dark:text-success-400">
+                            {tunnel.type === 2
+                              ? tunnel.outNodeId?.length || 0
+                              : tunnel.inNodeId?.length || 0}
+                            出口
+                          </span>
+                        </div>
+```
+
+to:
+
+```tsx
+                        <div>
+                          <div className="flex items-center gap-1.5 text-xs">
+                            <span className="font-semibold text-primary-700 dark:text-primary-400">
+                              {tunnel.inNodeId?.length || 0}入口
+                            </span>
+                            <span className="text-default-400">→</span>
+                            <span className="font-semibold text-secondary-700 dark:text-secondary-400">
+                              {tunnel.type === 2
+                                ? tunnel.chainNodes?.length || 0
+                                : 0}
+                              跳
+                            </span>
+                            <span className="text-default-400">→</span>
+                            <span className="font-semibold text-success-700 dark:text-success-400">
+                              {tunnel.type === 2
+                                ? tunnel.outNodeId?.length || 0
+                                : tunnel.inNodeId?.length || 0}
+                              出口
+                            </span>
+                          </div>
+                          {renderBestExitState(tunnel.bestExitState)}
+                        </div>
+```
+
+- [ ] **Step 5: Render in grid card topology section**
+
+In the grid card topology section, after the closing `</div>` for the topology row at the end of the block containing `出口` and before the enclosing border section closes, add:
+
+```tsx
+                                <div className="text-center">
+                                  {renderBestExitState(tunnel.bestExitState)}
+                                </div>
+```
+
+The result should put the best-exit summary under the entry -> hop -> exit row inside the topology section.
+
+- [ ] **Step 6: Run frontend build**
+
+Run from `vite-frontend`:
+
+```bash
+pnpm run build
+```
+
+Expected: PASS with `tsc && vite build` completing successfully.
+
+- [ ] **Step 7: Commit frontend display**
+
+```bash
+git add vite-frontend/src/pages/tunnel.tsx
+git commit -m "feat: show current best exit in tunnel list"
+```
+
+---
+
+### Task 5: Full Verification And Review
+
+**Files:**
+- Verify only.
+
+- [ ] **Step 1: Run backend tests**
+
+Run from `go-backend`:
+
+```bash
+go test ./...
+```
+
+Expected: PASS.
+
+- [ ] **Step 2: Run frontend build**
+
+Run from `vite-frontend`:
+
+```bash
+pnpm run build
+```
+
+Expected: PASS.
+
+- [ ] **Step 3: Inspect final diff**
+
+Run from repository root:
+
+```bash
+git diff --stat origin/main...HEAD
+git diff -- go-backend/internal/http/handler/tunnel_best_exit_display.go go-backend/internal/http/handler/tunnel_best_exit_display_test.go go-backend/internal/http/handler/handler.go go-backend/internal/http/handler/mutations.go vite-frontend/src/pages/tunnel.tsx
+```
+
+Expected: Diff only adds best-exit display state, response attachment, frontend list display, and tests. It must not change best-exit scoring, switching, runtime chain update, or agent code.
+
+- [ ] **Step 4: Request final code review**
+
+Ask a reviewer to check:
+
+```text
+Review the best-exit current display implementation. Confirm it only exposes current in-memory best-exit state in tunnel list/get responses and renders it in the tunnel list. Verify it does not change routing, scoring, switching, persistence, or polling behavior.
+```
+
+Expected: No blocking findings.
+
+---
+
+## Self-Review
+
+- Spec coverage: Backend response state is Task 2 and Task 3; direct vs final-hop owner semantics are covered by Task 1 tests; frontend list/grid display is Task 4; no polling and no routing changes are preserved by Task 5 review instructions.
+- Placeholder scan: The plan contains concrete files, function names, code blocks, commands, and expected outcomes.
+- Type consistency: `BestExitState`, `BestExitStateItem`, `bestExitDisplayState`, `bestExitDisplayItem`, `bestExitDecisionSnapshot`, and `bestExitNodeNameLookup` are defined before use and names match across tasks.

docs/superpowers/specs/2026-04-01-floating-save-button-design.md

@@ -0,0 +1,162 @@
+# Floating Save Button Design
+
+**Date:** 2026-04-01
+**Issue:** https://github.com/Sagit-chu/flvx/issues/266
+**Status:** Approved
+
+## Overview
+
+Add a Floating Action Button (FAB) to the config page (`vite-frontend/src/pages/config.tsx`) that appears when configuration changes are detected, allowing users to save without scrolling to the top.
+
+## Requirements
+
+From Issue #266:
+
+1. **Default hidden**: FAB not visible when no config changes
+2. **Show on change**: Auto-display when `hasChanges` becomes true
+3. **Fixed position**: Suspended at bottom-right corner, does not scroll with page
+4. **Mobile compatible**: Same behavior on desktop and mobile devices
+
+## Design Decisions
+
+### 1. Implementation Approach
+
+**Inline FAB in config.tsx** (not a reusable component)
+
+- Rationale: Current need is limited to config page only
+- State management (`hasChanges`, `saving`) already exists in the page
+- framer-motion patterns already established in project
+- Avoids over-abstraction (YAGNI)
+
+### 2. UI Structure
+
+Position: `fixed bottom-6 right-6` (24px from viewport edges)
+
+Visual layout:
+```
+┌──────────────────────────────────────┐
+│  [页面内容，可滚动]                    │
+│                                      │
+│                                [●]   │ ← FAB (fixed position)
+└──────────────────────────────────────┘
+```
+
+### 3. Button Appearance
+
+- Shape: Circular (`w-12 h-12 rounded-full`)
+- Color: Primary (matches existing save button)
+- Icon: SaveIcon (already defined in config.tsx)
+- Shadow: `shadow-lg` for visual hierarchy
+- Style: Icon-only (no text label)
+
+### 4. Animation
+
+Using framer-motion with `AnimatePresence`:
+
+| Phase | Properties |
+|-------|------------|
+| `initial` | `{ y: 100, opacity: 0 }` - starts below viewport |
+| `animate` | `{ y: 0, opacity: 1 }` - slides up to position |
+| `exit` | `{ y: 100, opacity: 0 }` - slides back down on hide |
+
+Transition config:
+```typescript
+transition={{ type: "spring", damping: 20, stiffness: 300 }}
+```
+
+Spring parameters produce Material Design-like feel: smooth entrance, slight bounce settle.
+
+### 5. Interaction Details
+
+- **Click**: Calls existing `handleSave()` function
+- **Loading state**: Button shows Spinner when `saving === true`
+- **Hover**: Inherits Button component's primary color hover behavior
+- **z-index**: `z-50` (above page content, below modals)
+- **Prevent duplicate click**: Button disabled when `saving === true`
+
+## Technical Implementation
+
+### Code Location
+
+File: `vite-frontend/src/pages/config.tsx`
+
+### Required Imports
+
+```typescript
+import { AnimatePresence, motion } from "framer-motion";
+```
+
+### FAB Component Structure
+
+```tsx
+<AnimatePresence>
+  {hasChanges && (
+    <motion.div
+      initial={{ y: 100, opacity: 0 }}
+      animate={{ y: 0, opacity: 1 }}
+      exit={{ y: 100, opacity: 0 }}
+      transition={{ type: "spring", damping: 20, stiffness: 300 }}
+      className="fixed bottom-6 right-6 z-50"
+    >
+      <Button
+        isIconOnly
+        color="primary"
+        size="lg"
+        className="w-12 h-12 rounded-full shadow-lg"
+        isLoading={saving}
+        onPress={handleSave}
+      >
+        {!saving && <SaveIcon className="w-5 h-5" />}
+      </Button>
+    </motion.div>
+  )}
+</AnimatePresence>
+```
+
+### Placement
+
+Insert FAB at the end of the component, before the closing `</div>` (after all Cards and Modals).
+
+### Dependencies
+
+- framer-motion: Already installed (v11.18.2)
+- Button: Already imported from `@/shadcn-bridge/heroui/button`
+- SaveIcon: Already defined in config.tsx
+
+## Behavior Matrix
+
+| State | FAB Visibility | Button Enabled |
+|-------|----------------|----------------|
+| `hasChanges = false` | Hidden (not rendered) | N/A |
+| `hasChanges = true, saving = false` | Visible, animating in | Yes |
+| `hasChanges = true, saving = true` | Visible | No (loading) |
+| Save success | Hidden (animating out) | N/A |
+
+## Responsive Behavior
+
+No special handling needed. `fixed bottom-6 right-6` works identically on:
+- Desktop browsers
+- Mobile browsers
+- H5/WebView mode
+
+The FAB maintains consistent 24px margin from viewport edges regardless of screen size.
+
+## Edge Cases
+
+1. **Multiple rapid toggles**: AnimatePresence handles gracefully - exit animation completes before new enter animation
+2. **Page unload with unsaved changes**: Not addressed in this design (separate concern)
+3. **FAB covers existing warning banner**: z-50 places FAB above the warning banner at line 1004-1013
+
+## Testing Checklist
+
+After implementation, verify:
+
+- [ ] FAB appears when any config field is modified
+- [ ] FAB slides up from bottom on appearance
+- [ ] FAB slides down to bottom on disappearance
+- [ ] FAB fixed position during page scroll
+- [ ] FAB triggers save on click
+- [ ] FAB shows spinner during save
+- [ ] FAB disappears after successful save
+- [ ] FAB works on mobile viewport
+- [ ] FAB does not interfere with Modal dialogs

docs/superpowers/specs/2026-04-01-github-proxy-config-design.md

@@ -0,0 +1,274 @@
+# GitHub 加速地址自定义配置设计
+
+**日期**: 2026-04-01
+**状态**: 待审核
+**作者**: AI Assistant
+
+## 概述
+
+允许用户在面板设置中自定义 GitHub 加速地址，支持开启/关闭加速功能。配置后，面板更新节点、生成安装命令以及安装脚本都使用配置的加速地址。
+
+## 背景
+
+当前 `gcode.hostcentral.cc` 硬编码在多个位置：
+- `go-backend/internal/http/handler/upgrade.go` - 节点升级下载 URL
+- `go-backend/internal/http/handler/mutations.go` - 节点安装命令生成
+- `install.sh` - 节点安装脚本
+- `panel_install.sh` - 面板安装脚本
+
+用户无法自定义加速地址或关闭加速功能。
+
+## 目标
+
+1. 面板设置中支持配置加速开关和加速地址
+2. 配置影响全部下载场景（面板端 + 安装脚本）
+3. 安装脚本支持交互式询问加速配置
+4. 面板生成的安装命令自动嵌入加速配置
+
+## 影响范围
+
+### 后端
+- `go-backend/internal/http/handler/upgrade.go`
+- `go-backend/internal/http/handler/mutations.go`
+
+### 前端
+- `vite-frontend/src/pages/config.tsx`
+- `vite-frontend/src/config/site.ts`（缓存配置键）
+
+### 安装脚本
+- `install.sh`
+- `panel_install.sh`
+
+## 详细设计
+
+### 1. 数据存储
+
+使用现有 `vite_config` 表存储两个配置项：
+
+| name | value | 说明 |
+|------|-------|------|
+| `github_proxy_enabled` | `"true"` / `"false"` | 是否开启加速，默认 `"true"` |
+| `github_proxy_url` | URL 字符串 | 加速地址，默认 `"https://gcode.hostcentral.cc"` |
+
+### 2. 后端 Handler 修改
+
+#### upgrade.go
+
+移除硬编码常量，新增辅助函数：
+
+```go
+// getGithubProxyConfig 获取 GitHub 加速配置
+// 返回: (是否开启, 加速地址)
+func (h *Handler) getGithubProxyConfig() (enabled bool, proxyURL string) {
+    enabled = true  // 默认开启
+    proxyURL = "https://gcode.hostcentral.cc"  // 默认地址
+    
+    if h == nil || h.repo == nil {
+        return
+    }
+    
+    // 读取开启状态
+    if enabledCfg, err := h.repo.GetConfigByName("github_proxy_enabled"); err == nil && enabledCfg != nil {
+        enabled = enabledCfg.Value != "false"
+    }
+    
+    // 读取加速地址
+    if urlCfg, err := h.repo.GetConfigByName("github_proxy_url"); err == nil && urlCfg != nil && urlCfg.Value != "" {
+        proxyURL = strings.TrimSpace(urlCfg.Value)
+        // 确保 URL 格式正确
+        if !strings.HasPrefix(proxyURL, "http://") && !strings.HasPrefix(proxyURL, "https://") {
+            proxyURL = "https://" + proxyURL
+        }
+        proxyURL = strings.TrimSuffix(proxyURL, "/")
+    }
+    
+    return
+}
+
+// buildDownloadURL 构建下载地址
+func (h *Handler) buildDownloadURL(version, arch string) string {
+    enabled, proxyURL := h.getGithubProxyConfig()
+    base := fmt.Sprintf("https://github.com/%s/releases/download/%s/gost-%s", githubRepo, version, arch)
+    
+    if enabled {
+        return fmt.Sprintf("%s/%s", proxyURL, base)
+    }
+    return base
+}
+```
+
+修改 `nodeUpgrade` 和 `nodeBatchUpgrade` 使用动态配置。
+
+#### mutations.go
+
+修改 `getNodeInstallCmd` 函数（约第 440-456 行）：
+
+```go
+func (h *Handler) getNodeInstallCmd(w http.ResponseWriter, r *http.Request) {
+    // ... 现有逻辑 ...
+    
+    enabled, proxyURL := h.getGithubProxyConfig()
+    
+    var cmd string
+    if enabled {
+        cmd = fmt.Sprintf(
+            "curl -L %s/https://github.com/%s/releases/download/%s/install.sh -o ./install.sh && chmod +x ./install.sh && PROXY_ENABLED=true PROXY_URL=%s VERSION=%s ./install.sh -a %s -s %s",
+            proxyURL, githubRepo, version, proxyURL, version, processServerAddress(panelAddr), secret,
+        )
+    } else {
+        cmd = fmt.Sprintf(
+            "curl -L https://github.com/%s/releases/download/%s/install.sh -o ./install.sh && chmod +x ./install.sh && PROXY_ENABLED=false VERSION=%s ./install.sh -a %s -s %s",
+            githubRepo, version, version, processServerAddress(panelAddr), secret,
+        )
+    }
+    
+    response.WriteJSON(w, response.OK(cmd))
+}
+```
+
+### 3. 前端修改
+
+#### config.tsx
+
+在 `CONFIG_ITEMS` 数组中添加配置项（约第 87-158 行之后）：
+
+```typescript
+{
+  key: "github_proxy_enabled",
+  label: "开启 GitHub 加速",
+  description: "用于节点更新和安装脚本下载，解决部分地区 GitHub 访问受限问题",
+  type: "switch",
+},
+{
+  key: "github_proxy_url",
+  label: "加速地址",
+  placeholder: "https://gcode.hostcentral.cc",
+  description: "GitHub 下载加速代理地址，开启加速后生效",
+  type: "input",
+  dependsOn: "github_proxy_enabled",
+  dependsValue: "true",
+},
+```
+
+在 `getInitialConfigs` 函数的 `configKeys` 数组中添加缓存键：
+
+```typescript
+"github_proxy_enabled",
+"github_proxy_url",
+```
+
+### 4. 安装脚本修改
+
+#### install.sh
+
+在脚本开头添加配置变量和环境变量读取：
+
+```bash
+# 镜像加速配置（可由面板传入）
+PROXY_ENABLED="${PROXY_ENABLED:-}"
+PROXY_URL="${PROXY_URL:-}"
+```
+
+修改 `maybe_proxy_url` 函数：
+
+```bash
+# 镜像加速
+maybe_proxy_url() {
+  local url="$1"
+  
+  # 如果明确关闭加速
+  if [[ "$PROXY_ENABLED" == "false" ]]; then
+    echo "$url"
+    return
+  fi
+  
+  # 默认开启加速
+  local proxy="${PROXY_URL:-gcode.hostcentral.cc}"
+  
+  # 处理 URL 格式
+  if [[ "$proxy" == https://* || "$proxy" == http://* ]]; then
+    proxy="${proxy%/}"  # 移除末尾斜杠
+  else
+    proxy="https://${proxy}"
+  fi
+  
+  echo "${proxy}/${url}"
+}
+```
+
+在 `install_flux_agent` 函数开头添加交互式询问：
+
+```bash
+install_flux_agent() {
+  echo "🚀 开始安装 flux_agent..."
+  
+  # 询问加速配置（如果未由面板传入）
+  if [[ -z "$PROXY_ENABLED" ]]; then
+    echo ""
+    read -p "是否开启 GitHub 加速? (Y/n): " proxy_choice
+    case "$proxy_choice" in
+      n|N) PROXY_ENABLED="false" ;;
+      *)   
+        PROXY_ENABLED="true"
+        read -p "加速地址 (默认 gcode.hostcentral.cc): " input_url
+        PROXY_URL="${input_url:-gcode.hostcentral.cc}"
+        ;;
+    esac
+  fi
+  
+  # ... 现有安装逻辑 ...
+}
+```
+
+#### panel_install.sh
+
+类似修改，在 `install_panel` 函数开头添加询问逻辑。
+
+### 5. 配置缓存
+
+#### site.ts
+
+在配置缓存键列表中添加新键（如果需要前端缓存加速配置）。
+
+## 默认行为
+
+- `github_proxy_enabled`: 默认 `"true"`（开启加速）
+- `github_proxy_url`: 默认 `"https://gcode.hostcentral.cc"`
+
+## 测试要点
+
+1. **后端 API 测试**：
+   - 未配置时使用默认值
+   - 配置后正确读取并应用
+   - 关闭加速后直连 GitHub
+
+2. **前端 UI 测试**：
+   - Switch 开关正确切换
+   - 关闭加速时隐藏地址输入框
+   - 保存配置后正确持久化
+
+3. **安装脚本测试**：
+   - 交互式询问正常工作
+   - 环境变量传入时跳过询问
+   - 加速关闭时直连 GitHub
+
+4. **集成测试**：
+   - 面板生成安装命令正确包含加速配置
+   - 节点升级下载使用配置的加速地址
+
+## 风险与缓解
+
+| 风险 | 缓解措施 |
+|------|----------|
+| 用户输入无效加速地址 | 后端验证 URL 格式，前端添加格式提示 |
+| 旧版本安装脚本不兼容 | 保持 `maybe_proxy_url` 函数签名不变，仅修改内部逻辑 |
+| 配置缺失时行为不一致 | 在 `getGithubProxyConfig` 中提供合理的默认值 |
+
+## 任务清单
+
+- [ ] 后端：upgrade.go 修改
+- [ ] 后端：mutations.go 修改
+- [ ] 前端：config.tsx 添加配置项
+- [ ] 脚本：install.sh 修改
+- [ ] 脚本：panel_install.sh 修改
+- [ ] 测试：验证功能正常

docs/superpowers/specs/2026-04-03-commercial-white-label-design.md

@@ -0,0 +1,49 @@
+# FLVX 商业版白标授权功能设计方案
+
+## 1. 目标
+通过在设置面板中引入商业版激活码（License Key），允许已授权的用户去除前端页面的 FLVX 品牌标识，并使用自己的 App Name、Logo、Favicon 和隐藏版权信息，从而实现“白标”定制。
+
+## 2. 功能范围
+*   **授权校验（服务端）**：提供一个激活码输入与验证的接口。初始版本采用**在线 Mock 验证**，后续可通过替换验证服务器地址实现真实的在线发卡与吊销逻辑。
+*   **配置存储（服务端）**：一旦授权成功，在数据库（如 `vite_config` 或现有的配置表）中记录授权状态（例如 `license_key`、`is_commercial` 等），并放开商业白标相关字段的写入权限（`app_name`, `app_logo`, `app_favicon`, `hide_footer_brand`）。
+*   **权限拦截（服务端）**：拦截未授权用户的请求，禁止他们更新相关的品牌字段。
+*   **前端 UI（客户端）**：
+    *   在配置页面（或单独的“授权/个性化” Tab）提供激活码输入框。
+    *   如果未激活：界面仅展示默认品牌配置，并提示“需要商业授权以解锁自定义品牌”。
+    *   如果已激活：展示站名、Logo、Favicon 的上传和替换表单，提供隐藏“Powered by FLVX”脚标的开关。
+
+## 3. 架构设计
+
+### 3.1 数据库/配置结构
+扩展配置系统中的以下字段：
+*   `license_key` (String)：存储用户激活的商业版密钥。
+*   `is_commercial` (String/Boolean)：标识是否为合法的商业授权状态（"true" 或 "false"）。
+*   `hide_footer_brand` (String/Boolean)：是否隐藏底部的 FLVX 信息。
+
+注意：现有的 `app_name`, `app_logo`, `app_favicon` 字段将收紧修改权限。
+
+### 3.2 服务端 API 变更
+*   **新增 API `POST /api/license/activate` (或将逻辑集成到现有配置修改接口)**：
+    *   接收 `{ "license_key": "FLVX-xxxx" }`。
+    *   **Mock 逻辑**：如果是 `FLVX-` 开头则视为合法。
+    *   合法则更新系统配置，设置 `license_key` 并将状态标为 `is_commercial: "true"`。
+*   **修改 API 权限校验（如保存系统设置的接口）**：
+    *   当接收到更新 `app_name`、`app_logo`、`app_favicon`、`hide_footer_brand` 的请求时，检查当前系统中的 `is_commercial` 状态。
+    *   如果未授权且尝试修改白标字段，返回错误（如 `403 Forbidden`）提示需要商业授权。
+
+### 3.3 前端设计
+*   **授权卡片**：在全局设置（Settings / Config）页加入「商业版授权」或「个性化」区块。
+*   **表单按需显示**：使用配置中的 `is_commercial === "true"` 来控制相关表单组件的展示：
+    *   如果未授权，白标字段（Logo、Favicon、App Name、Hide Footer）不可修改（呈 Disabled）或覆盖了一层“锁”图标。
+    *   底部 Footer 组件读取 `hide_footer_brand === "true"` 决定是否渲染 `Powered by FLVX`。
+*   **全局状态同步**：当用户激活或上传完 Logo 后，通过现有的 `syncLogo` / `syncFavicon` 等机制全局刷新外观。
+
+## 4. 安全与降级
+*   **本地缓存失效**：如果后台在线验证服务器（未来）判断该 key 被吊销，可以在后续获取 config 的接口中重置白标配置为空，强制回退到默认 FLVX 主题。
+*   **接口防绕过**：所有跟商业字段相关的变更，必须经过后端 API 的鉴权，确保纯前端绕过是无效的。
+
+## 5. 测试策略
+1.  **输入非法激活码**，提示错误，白标设置项仍被锁定。
+2.  **输入合法激活码 (`FLVX-...`)**，提示成功，白标设置项解锁。
+3.  **成功后上传 Logo 和修改站名**，刷新页面，前端应正常应用新配置且没有 FLVX 标记。
+4.  **接口测试**：在未授权状态下，尝试强行通过 API 更新 `app_logo`，接口应返回权限不足。

docs/superpowers/specs/2026-04-03-keygen-license-integration-design.md

@@ -0,0 +1,59 @@
+# FLVX 商业版 Keygen.sh 授权集成设计方案
+
+## 1. 目标
+使用 [Keygen.sh](https://keygen.sh/) 替换当前 FLVX 中基于 Mock 的商业版授权验证逻辑。通过接入 Keygen.sh，实现安全、可控的许可证分发、设备绑定（防止一码多用）、定期验证以及远程吊销功能，为 FLVX 的商业化白标功能提供生产级支持。
+
+## 2. Keygen.sh 核心概念映射
+*   **Account (账户)**：您在 Keygen 注册的商户账号。
+*   **Product (产品)**：在 Keygen 中创建一个名为 `FLVX Panel` 的产品。
+*   **Policy (策略)**：定义授权规则。例如，创建一个 `White-Label Policy`，限制每个 License 只能绑定 **1 个 Machine**（即一个 FLVX 面板实例），并可配置有效期（如按年订阅或永久有效）。
+*   **License (许可证)**：发给客户的激活码（Key），格式可自定义（如 `FLVX-XXXX-XXXX`）。
+*   **Machine (机器/设备)**：运行 FLVX 的具体服务器或面板实例。为了防止一码多开，FLVX 激活时需要向 Keygen 注册一台 Machine。
+
+## 3. 架构设计与集成流程
+
+### 3.1 唯一设备标识 (Machine Fingerprint)
+为了在 Keygen 中标识不同的 FLVX 面板，FLVX 后端需要生成并持久化一个唯一的机器指纹（Fingerprint）。
+*   **生成时机**：FLVX 首次启动或首次激活时，生成一个 UUID v4。
+*   **存储**：保存在数据库 `vite_config` 表中，键名为 `machine_fingerprint`。
+
+### 3.2 激活流程 (License Activation)
+当用户在前端输入激活码并点击“激活”时：
+1.  **FLVX 后端验证 Key**：调用 Keygen API `POST /v1/accounts/{account}/licenses/actions/validate-key`，传入 `key`。
+2.  **检查 License 状态**：如果返回 `valid: true`，说明 License 合法且未过期。
+3.  **激活 Machine (设备绑定)**：
+    *   调用 Keygen API `POST /v1/accounts/{account}/machines`。
+    *   关联刚才验证的 `licenseId`，并传入 FLVX 的 `machine_fingerprint`。
+    *   *异常处理*：如果该 License 已绑定了其他 Machine（达到 Policy 上限），Keygen 会报错，FLVX 后端需返回“该授权码已在其他设备使用”。
+4.  **持久化状态**：激活成功后，在本地数据库保存 `license_key`、`is_commercial: "true"`，以及从 Keygen 返回的额外信息（如过期时间 `license_expiry`）。
+
+### 3.3 定期心跳与验证 (Periodic Validation)
+为了防止用户激活后断网或通过修改数据库绕过，以及实现**远程吊销**：
+*   **定时任务**：FLVX 后端增加一个后台协程（如每天运行一次，或每 12 小时运行一次）。
+*   **验证逻辑**：调用 Keygen API 验证当前的 `license_key` 和 `machine_fingerprint`。
+*   **吊销/过期处理**：如果 Keygen 明确返回 License 已吊销（Suspended/Revoked/Banned）或已过期，或者当前 Machine 不再属于该 License，FLVX 后端需将 `is_commercial` 强制设为 `"false"`，并清空本地缓存，恢复官方品牌展示。
+*   **宽限期 (Grace Period)**：考虑到用户服务器可能偶尔网络不通，如果请求 Keygen 超时或失败，不应立刻吊销。可设置一个宽限期（如连续 3 天请求失败才降级）。
+
+## 4. 后端 API 改造计划 (`go-backend`)
+
+### 4.1 新增环境变量/配置
+*   `KEYGEN_ACCOUNT_ID`: 您的 Keygen 账户 ID（打包时可硬编码，或作为全局环境变量）。
+*   （可选）`KEYGEN_PRODUCT_TOKEN` 或仅使用 License Key 进行验证（取决于 Keygen 验证方式的选择，推荐直接使用 License Key 进行无状态验证）。
+
+### 4.2 改造 `/api/v1/license/activate`
+*   引入 HTTP 客户端向 `api.keygen.sh` 发起请求。
+*   实现上述提到的 Validate Key 和 Activate Machine 两步走逻辑。
+*   返回具体的错误信息给前端（例如：“授权码不存在”、“授权码已过期”、“激活设备数达上限”）。
+
+## 5. 前端改造计划 (`vite-frontend`)
+前端在目前的 UI 基础上几乎不需要大改，只需配合后端的增强：
+1.  **展示过期时间**：如果后端返回了 `license_expiry`，可以在“商业版授权”卡片中展示“授权有效期至：YYYY-MM-DD”。
+2.  **错误提示优化**：透传后端返回的 Keygen 验证错误，给予用户明确的指引。
+3.  **解绑/停用功能（可选）**：未来可增加“停用授权”按钮，调用后端接口在 Keygen 中删除 Machine 绑定，以便用户将 License 迁移到新的服务器。
+
+## 6. 实施步骤建议
+1.  在 Keygen.sh 注册账号，创建 Product 和 Policy，生成测试用的 License Key。
+2.  在 FLVX 的 `go-backend` 中新建一个 `pkg/keygen` 或 `internal/license` 包，封装 Keygen API 的调用（Validate, Activate Machine）。
+3.  修改现有的 `licenseActivate` 接口，接入真正的验证逻辑。
+4.  添加定期验证的 Cron Job。
+5.  测试激活、吊销、过期、断网等各种场景。

docs/superpowers/specs/2026-04-04-announcement-popup-design.md

@@ -0,0 +1,36 @@
+# Announcement Popup Notification Design
+
+## Overview
+This feature implements a popup notification modal for important dashboard announcements to ensure users see them immediately, addressing GitHub Issue #169.
+
+## Requirements
+1. Automatic display of a popup modal when opening the dashboard page if a new/updated announcement exists.
+2. Includes a "Don't show again" option to remember the user's choice to dismiss it.
+3. Smart triggering: Only pops up for *new* or *updated* announcements.
+4. Support Markdown formatting for the announcement content.
+5. Retain the existing permanent top banner as a fallback.
+
+## Backend Changes (Go)
+The `/api/v1/announcement/get` API currently only returns `content` and `enabled`. It must be updated to return the timestamp of the last update to enable the frontend to detect changes.
+
+1.  **Repository (`internal/store/repo/repository.go`)**: Ensure `GetAnnouncement` retrieves `UpdatedTime` (or falls back to `CreatedTime`).
+2.  **Handler (`internal/http/handler/handler.go`)**: Modify `getAnnouncement` to include an `update_time` (int64) field in its JSON response.
+
+## Frontend Changes (Vite/React/Tailwind)
+1.  **API Interface (`src/api/index.ts`)**:
+    *   Update `AnnouncementData` to include `update_time: number`.
+2.  **Storage Mechanism**:
+    *   Use browser `localStorage` to persist the user's view state. Key: `flvx_announcement_seen_time`.
+3.  **UI Component (`AnnouncementModal`)**:
+    *   Create a new modal component for the dashboard.
+    *   The modal content will render the markdown of the announcement.
+    *   It will feature two primary actions:
+        *   **"Close"**: Closes the modal temporarily for this session (does NOT update `localStorage`). It will pop up again on the next page load.
+        *   **"Don't show again"**: Closes the modal AND sets `localStorage.setItem('flvx_announcement_seen_time', announcement.update_time)`.
+4.  **Integration (`src/pages/dashboard.tsx` & `use-dashboard-data.ts`)**:
+    *   Add state to manage the modal visibility (e.g., `isAnnouncementModalOpen`).
+    *   On data load, compare the fetched `update_time` with the stored `flvx_announcement_seen_time`. If the fetched time is greater (or if no stored time exists), set `isAnnouncementModalOpen(true)`.
+
+## Error Handling and Edge Cases
+*   If `localStorage` is unavailable or throws an error (e.g., Private Browsing mode restrictions), the modal may show repeatedly. The code should safely catch `localStorage` access errors.
+*   If `update_time` is missing from an old database record, the backend should gracefully fall back to the creation time or a safe default (like 0) to ensure the logic doesn't break.

docs/superpowers/specs/2026-04-04-flvx-ios26-redesign-design.md

@@ -0,0 +1,60 @@
+# Flvx iOS 26 Liquid Glass UI Redesign Spec
+
+## 1. Overview
+This document specifies the comprehensive UI/UX redesign of the Flvx frontend using an "Apple iOS 26 Liquid Glass" design language. The goal is to elevate the visual quality of the entire application, making it modern, spatially aware, and highly legible through extensive use of blur, translucency, squircle borders, and semantic contrast.
+
+## 2. Scope
+The redesign covers 100% of the frontend routing pages and overlay components under `vite-frontend/src/pages/` and global UI modules:
+- Dashboard (`dashboard.tsx`)
+- Node Management (`node.tsx`)
+- Tunnel & Rule Configurations (`tunnel.tsx`, `forward.tsx`)
+- System Monitor (`monitor.tsx`)
+- User Management (`user.tsx`)
+- Speed Limit Management (`limit.tsx`)
+- Group Management (`group.tsx`)
+- Panel Sharing (`panel-sharing.tsx`)
+- Global Settings & Config (`config.tsx`, `settings.tsx`)
+- Profile & Change Password (`profile.tsx`, `change-password.tsx`)
+- All related Modals, Drawers, and floating UI (e.g., "Create Node", "Add Rule" forms).
+
+## 3. Design System & Tokens
+The new UI replaces traditional solid-color borders and flat surfaces with the following spatial design tokens:
+
+### 3.1. Corner Radii (Squircles)
+- **Outer Shell / Viewports**: 32px (`rounded-3xl` equivalent)
+- **Cards / Containers**: 24px (`rounded-2xl`)
+- **Buttons / Inputs**: 16px (`rounded-xl` or `rounded-full`)
+- **Badges / Tags**: 6px or fully rounded.
+
+### 3.2. Backgrounds & Blurs
+- **Global Background**: A mesh gradient blending soft pinks and blues (`#ff9a9e`, `#fecfef`, `#a1c4fd`, `#c2e9fb`).
+- **Glass Base (Primary Containers)**: `backdrop-blur-3xl` with an ultra-thin white overlay (`rgba(255, 255, 255, 0.6)` or `#ffffff99`).
+- **Glass Inner Glow (Borders)**: 1px solid `rgba(255, 255, 255, 0.8)` (`#ffffffcc`).
+- **Modals Background Overlay**: 30% black overlay (`#0000004d`).
+
+### 3.3. Semantic Colors
+- **Brand / Active / Primary / TCP**: Blue `#007aff`
+- **Healthy / Success / Online**: Green `#34c759`
+- **Warning / Wait / UDP**: Orange `#ff9500`
+- **Danger / Offline / Delete**: Red `#ff3b30`
+- **Secondary / Purple / Data**: Purple `#af52de`
+- **Text**: Primary (`#1d1d1f`), Secondary (`#86868b`).
+
+### 3.4. Elevation & Shadow
+- Soft, highly diffused drop shadows rather than sharp lines: e.g., `box-shadow: 0 10px 30px rgba(0, 0, 0, 0.1)`.
+
+## 4. Implementation Strategy
+We will implement the redesign systematically across the React + TailwindCSS + shadcn/HeroUI stack:
+1. **CSS Variables / Tailwind Config**: Inject the new Liquid Glass design tokens (colors, extended radiuses, customized backdrop blurs, box shadows) into `tailwind.config.js` and `globals.css`.
+2. **Global App Shell**: Update the root layout (`index.tsx` or main `App` layout) to host the dynamic mesh gradient background and the new translucent sidebar.
+3. **Component Re-styling**: 
+   - Override HeroUI default card, input, and modal styles using custom `classNames`.
+   - Update `MetricCard`, `PageEmptyState`, `PageLoadingState`, and other base components to support the `glass_card` spec.
+4. **Page-by-Page Integration**: Rewrite the JSX of each page to utilize the new layout structure, ensuring all existing interactive state and API logic is seamlessly preserved.
+5. **Modal System Update**: Apply the transparent `#0000004d` overlay and 480px width glassy card style to all global dialogs.
+
+## 5. Success Criteria
+- [ ] No regression in business logic; all forms, interactions, and data rendering operate exactly as before.
+- [ ] The visual system consistently employs the `glass_bg`, `glass_card`, and corresponding squircle radiuses across 100% of the UI.
+- [ ] Modals and Overlays correctly blur the background mesh gradient.
+- [ ] All responsive layouts appropriately wrap the card components on smaller displays.

docs/superpowers/specs/2026-04-26-allow-local-remote-addr-design.md

@@ -0,0 +1,133 @@
+# 允许转发到本地地址开关设计
+
+**日期**: 2026-04-26
+**状态**: 待审核
+**作者**: AI Assistant
+
+## 概述
+
+新增一个全局设置开关，控制规则目标地址是否允许指向本地/内网地址。默认关闭，保持当前安全策略不变；开启后，规则创建和编辑时允许将目标地址设置为 `127.0.0.1`、`10.x.x.x`、`172.16-31.x.x`、`192.168.x.x` 等本地或私网地址。
+
+## 背景
+
+当前后端在规则创建和编辑时会调用 `IsSafeRemoteAddr()`，统一禁止目标地址指向本地/内网地址，用来降低 SSRF / 开放代理风险。这一行为是全局硬编码的，无法按部署场景调整。
+
+有些用户需要把规则转发到本机或内网服务，因此需要一个显式、全局的开关来放宽这条限制。
+
+## 目标
+
+1. 在设置页提供一个全局开关控制该行为。
+2. 默认关闭，不改变现有安全默认值。
+3. 开启后，规则创建和编辑允许本地/内网目标地址。
+4. 不影响其他安全校验和其他业务流程。
+
+## 影响范围
+
+### 后端
+- `go-backend/internal/http/handler/security_utils.go`
+- `go-backend/internal/http/handler/mutations.go`
+- `go-backend/internal/http/handler/handler.go`
+
+### 前端
+- `vite-frontend/src/pages/config.tsx`
+
+### 测试
+- `go-backend/tests/contract/forward_contract_test.go` 或新增独立 contract test
+
+## 详细设计
+
+### 1. 配置存储
+
+使用现有 `vite_config` 表新增一个配置项：
+
+| name | value | 说明 |
+|------|-------|------|
+| `allow_local_remote_addr` | `"1"` / `"0"` | 是否允许规则目标地址指向本地/内网地址 |
+
+约定：
+- 未配置时按 `"0"` 处理
+- `"1"` 表示允许
+- 其他值一律按关闭处理
+
+### 2. 后端行为
+
+新增一个轻量辅助函数，用于读取该配置开关：
+
+```go
+func (h *Handler) allowLocalRemoteAddr() bool {
+    if h == nil || h.repo == nil {
+        return false
+    }
+    cfg, err := h.repo.GetConfigByName("allow_local_remote_addr")
+    if err != nil || cfg == nil {
+        return false
+    }
+    return strings.TrimSpace(cfg.Value) == "1"
+}
+```
+
+在以下路径中应用：
+- `forwardCreate`
+- `forwardUpdate`
+
+行为改为：
+- 当开关关闭时，继续执行 `IsSafeRemoteAddr(remoteAddr)`
+- 当开关开启时，跳过这条“本地/内网地址禁止”校验
+
+这样可以把改动范围限定在规则创建/编辑，不改变其他依赖 `IsSafeRemoteAddr()` 的场景。
+
+### 3. 前端设置页
+
+在 `vite-frontend/src/pages/config.tsx` 增加一个全局开关配置项。
+
+建议文案：
+
+- 标签：`允许转发到本地地址`
+- 描述：`开启后，规则目标地址可指向 127.0.0.1、10.x.x.x、172.16-31.x.x、192.168.x.x 等本地或内网地址。默认关闭以降低开放代理风险。`
+
+控件类型：
+- 使用现有设置页的布尔开关模式
+
+默认显示策略：
+- 不依赖其他配置项
+- 直接显示在设置页的网络/安全相关区域；若现有页面没有单独分区，则先按现有配置项组织方式加入即可
+
+### 4. 错误与兼容性
+
+关闭开关时：
+- 保持现有错误行为，继续阻止本地/内网地址
+
+开启开关时：
+- 仅放开“本地/内网地址禁止”这条限制
+- 仍保留地址格式解析失败等其他错误
+
+### 5. 测试
+
+需要补两类后端契约测试：
+
+1. 开关关闭时拒绝本地/内网地址
+- 创建规则时使用本地/内网地址
+- 断言接口返回非 0 code
+
+2. 开关开启时允许本地/内网地址
+- 先写入 `vite_config(name=allow_local_remote_addr, value=1)`
+- 创建或更新规则时使用相同地址
+- 断言接口成功
+
+建议至少覆盖：
+- create 路径
+- update 路径
+- 多目标地址输入（逗号或换行分隔）中包含本地地址时的行为
+
+## 风险与约束
+
+1. 该开关会降低默认安全防护，应明确标注风险。
+2. 这是全局开关，不做用户级或规则级细分控制。
+3. 该开关只影响规则目标地址校验，不影响其他独立的安全策略。
+
+## 推荐实施顺序
+
+1. 先补失败的后端契约测试
+2. 实现后端配置读取与创建/更新分支控制
+3. 在设置页增加开关
+4. 跑后端测试与前端构建验证

docs/superpowers/specs/2026-04-27-per-ip-rule-limits-design.md

@@ -0,0 +1,321 @@
+# 规则每 IP 连接数与限速设计
+
+**日期**: 2026-04-27
+**状态**: 待审核
+**作者**: AI Assistant
+
+## 概述
+
+在转发规则的高级设置中新增两类每客户端 IP 限制：每 IP 最大连接数、每 IP 带宽限速。保留现有总量限制语义不变，新增字段只在用户显式配置时生效。
+
+实现优先复用 GOST 已有能力：`climiters` 的 `$$ N` 表示每个客户端 IP 独立最大连接数；`limiters` 支持 IP/CIDR 级带宽桶，可用 `0.0.0.0/0` 和 `::/0` 实现默认覆盖所有 IPv4/IPv6 客户端的每 IP 带宽限速。
+
+## 背景
+
+当前 FLVX 已经支持规则级最大连接数和规则级限速，但这两个限制都是规则总量：
+
+- `maxConn` 下发为 GOST `climiters` 的 `$ N`，限制整条规则的总并发连接数。
+- `speedId` 下发为 GOST `limiters` 的 `$ in out`，限制整条规则的总带宽。
+
+用户需要的是按客户端 IP 隔离的限制，例如每个 IP 最多 5 个连接、每个 IP 最多 10 Mbps，而不是所有客户端共享同一个总量。
+
+## GOST 能力确认
+
+### 连接数限制
+
+`go-gost/x/limiter/conn/conn.go` 已内置以下语义：
+
+| Key | 含义 |
+|-----|------|
+| `$` | 全局连接数限制，所有客户端共享一个 limiter |
+| `$$` | 每个客户端 IP 独立连接数限制，每个 IP 创建自己的 limiter |
+| `IP` / `CIDR` | 指定 IP 或 CIDR 的连接数限制 |
+
+因此每 IP 连接数无需新增 agent 限制器，只需后端下发 `$$ N`。
+
+### 带宽限制
+
+`go-gost/x/limiter/traffic/traffic.go` 已内置以下语义：
+
+| Key | 含义 |
+|-----|------|
+| `$` | 服务级总带宽限制 |
+| `$$` | 连接级带宽限制 |
+| `IP` / `CIDR` | 客户端 IP 或 CIDR 级带宽限制 |
+
+CIDR 级限制使用 generator，为命中的客户端 IP 创建独立 limiter。使用 `0.0.0.0/0` 和 `::/0` 可以覆盖所有 IPv4/IPv6 客户端，实现每 IP 带宽限速。
+
+### 现有缺口
+
+TCP listener 已在 Accept 后用客户端地址包装连接级 traffic limiter，路径可用于每 IP 带宽。UDP listener 当前只在 PacketConn 上应用服务级 limiter，没有在 `Accept()` 后按客户端 UDP pseudo-connection 包装 limiter，也没有挂接 connection limiter。因此要让 UDP 与 TCP 语义一致，需要补齐 UDP listener 的 per-client wrapper。
+
+## 目标
+
+1. 保留现有 `maxConn` 和 `speedId` 的总量语义。
+2. 在规则上新增每 IP 最大连接数。
+3. 在规则上新增每 IP 带宽限速。
+4. 同一规则允许同时配置总量限制和每 IP 限制。
+5. 普通用户不能设置或修改限速规则字段，保持现有权限模型。
+6. TCP 和 UDP 入口都尽量遵循相同限制语义。
+
+## 非目标
+
+1. 不新增按用户组、节点组、国家地区、ASN 的限制。
+2. 不新增请求频率限制；本次“每个 IP 限速”指带宽限速，不是新建连接频率。
+3. 不改变已有 speed limit 规则表的单位和含义。
+4. 不把用户级默认最大连接数改成每 IP 语义；用户级 `maxConn` 继续作为默认总连接数。
+
+## 数据模型
+
+在 `forward` 表新增两个字段：
+
+| 字段 | 类型 | 默认 | 说明 |
+|------|------|------|------|
+| `ip_max_conn` | int | `0` | 每 IP 最大连接数，`0` 表示不启用 |
+| `ip_speed_id` | nullable int64 | `NULL` | 每 IP 带宽限速规则 ID，`NULL` 表示不启用 |
+
+Go 模型新增：
+
+```go
+IPMaxConn int           `gorm:"column:ip_max_conn;not null;default:0"`
+IPSpeedID sql.NullInt64 `gorm:"column:ip_speed_id"`
+```
+
+字段会通过现有 auto-migrate 机制创建，保持 SQLite/PostgreSQL 兼容，不使用 SQLite 不兼容的 GORM tags。
+
+## API 行为
+
+### 创建规则
+
+`/forward/create` 新增入参：
+
+```json
+{
+  "ipMaxConn": 5,
+  "ipSpeedId": 123
+}
+```
+
+规则：
+
+- `ipMaxConn` 缺省或小于等于 `0` 时按 `0` 存储，不启用每 IP 连接数限制。
+- `ipSpeedId` 缺省或不存在时存为 `NULL`，不启用每 IP 带宽限速。
+- `ipSpeedId` 指向不存在的限速规则时按 `NULL` 处理，沿用现有 `speedId` 的容错策略。
+- 普通用户提交非空 `ipSpeedId` 时返回错误，保持与 `speedId` 一致的权限边界。
+
+### 更新规则
+
+`/forward/update` 新增入参：
+
+```json
+{
+  "ipMaxConn": 5,
+  "ipSpeedId": 123
+}
+```
+
+规则：
+
+- 未提交 `ipMaxConn` 时保留原值；提交空值或 `0` 时清除每 IP 连接数限制。
+- 未提交 `ipSpeedId` 时保留原值；提交 `null` 时清除每 IP 带宽限速。
+- 普通用户不能把 `ipSpeedId` 改成不同的非空值。
+- 更新后重新同步运行时服务和 limiter。
+
+### 列表返回
+
+`/forward/list` 返回项新增：
+
+```json
+{
+  "ipMaxConn": 5,
+  "ipSpeedId": 123,
+  "ipSpeedLimitName": "每IP 10Mbps"
+}
+```
+
+`ipSpeedLimitName` 可选，但建议返回，便于前端显示缺失或已删除的限速规则。
+
+## 后端运行时同步
+
+### 连接数限制器
+
+将现有连接限制器构建从单一总量扩展为组合规则。
+
+当前行为：
+
+```json
+{
+  "name": "rule_conn_limit_42",
+  "limits": ["$ 100"]
+}
+```
+
+新增行为：
+
+```json
+{
+  "name": "rule_conn_limit_42",
+  "limits": ["$ 100", "$$ 5"]
+}
+```
+
+规则：
+
+- `maxConn > 0` 时追加 `$ maxConn`。
+- `ipMaxConn > 0` 时追加 `$$ ipMaxConn`。
+- 如果规则未配置 `maxConn` 且用户有 `MaxConn > 0`，继续继承用户级总连接数，追加 `$ user.MaxConn`。
+- 如果两者都没有，则不下发 `climiter`，服务不引用 `climiter`。
+- limiter 名称继续优先使用 `rule_conn_limit_<forwardID>`；只有用户级默认总连接数且规则没有任何连接限制时可继续使用 `user_conn_limit_<userID>`，避免不必要的 per-rule limiter。
+
+### 带宽限制器
+
+将现有规则限速从单一 `speedId` 扩展为组合 limiter。
+
+当前行为：
+
+```json
+{
+  "name": "123",
+  "limits": ["$ 1.3MB 1.3MB"]
+}
+```
+
+新增每 IP 行为：
+
+```json
+{
+  "name": "rule_traffic_limit_42",
+  "limits": [
+    "$ 1.3MB 1.3MB",
+    "0.0.0.0/0 1.3MB 1.3MB",
+    "::/0 1.3MB 1.3MB"
+  ]
+}
+```
+
+规则：
+
+- 只有总量 `speedId` 时，保持现有名称和下发路径，服务继续引用 `speedId` 字符串。
+- 只有每 IP `ipSpeedId` 时，创建 `rule_traffic_limit_<forwardID>`，只包含 IPv4/IPv6 CIDR 行。
+- 总量和每 IP 同时存在时，创建 `rule_traffic_limit_<forwardID>`，同时包含 `$` 和 CIDR 行。
+- 如果规则没有 `speedId`，则总量仍可继承 user tunnel 的 `speedId`，保持现有 fallback 语义；当继承的总量限速与 `ipSpeedId` 同时存在时，也使用 `rule_traffic_limit_<forwardID>` 组合 limiter。
+- 每 IP 限速不从 user tunnel 继承，只由规则字段控制。
+- `AddLimiters` 失败且提示已存在时，使用 `UpdateLimiters` 更新。
+
+### 服务配置
+
+`buildForwardServiceConfigs` 需要从当前 `limiterID *int64` / `cLimiterName string` 扩展为更明确的运行时限制描述，例如：
+
+```go
+type forwardRuntimeLimiters struct {
+    TrafficLimiter string
+    ConnLimiter    string
+}
+```
+
+服务配置只关心最终引用的 limiter 名称：
+
+- `service["limiter"] = runtimeLimiters.TrafficLimiter`
+- `service["climiter"] = runtimeLimiters.ConnLimiter`
+
+这样可以把“如何构建 limiter payload”的逻辑和“如何构建 service JSON”的逻辑分开。
+
+## Agent/GOST 调整
+
+### WebSocket 命令
+
+当前 agent WebSocket 已支持：
+
+- `AddLimiters` / `UpdateLimiters` / `DeleteLimiters`
+- `AddCLimiters` / `UpdateCLimiters` / `DeleteCLimiters`
+
+本设计无需新增命令类型。
+
+### UDP listener
+
+补齐 `go-gost/x/listener/udp/listener.go` 的 `Accept()` 包装逻辑，使 UDP pseudo-connection 与 TCP listener 一致：
+
+- 对 `l.options.ConnLimiter` 按客户端地址应用连接数限制。
+- 对 `l.options.TrafficLimiter` 按 `conn.RemoteAddr().String()` 应用连接级 traffic wrapper。
+
+需要注意 UDP pseudo-connection 的生命周期由内部 UDP listener 的 TTL/keepalive 控制；connection limiter 必须在 pseudo-connection 关闭时释放计数。
+
+## 前端设计
+
+在 `vite-frontend/src/pages/forward.tsx` 的规则高级设置中新增两个控件：
+
+1. `每 IP 最大连接数`
+- 类型：number input。
+- 文案：`每个客户端 IP 可同时建立的最大连接数；0 或空表示不限制。`
+- 字段：`ipMaxConn`。
+
+2. `每 IP 限速`
+- 类型：Select，复用现有限速规则列表。
+- 文案：`每个客户端 IP 独享该带宽限制；不选择表示不限制。`
+- 字段：`ipSpeedId`。
+- 只对管理员显示，保持与 `规则限速` 一致。
+
+前端类型需要同步更新：
+
+- `ForwardApiItem`
+- `ForwardMutationPayload`
+- `ForwardForm` 或页面内等价类型
+
+## 错误处理与兼容性
+
+1. 旧数据默认 `ip_max_conn=0`、`ip_speed_id=NULL`，行为与当前版本一致。
+2. 现有 agent 已支持 limiter 命令和 GOST limiter 语法；发布时需要包含 UDP 修复，才能让 TCP/UDP 都获得完整语义。
+3. 节点离线时沿用现有 warning 行为，规则仍可保存，在线节点跳过下发。
+4. 如果每 IP speed limit ID 被删除，更新时按 `NULL` 处理，列表页可提示或自动清除，和现有 `speedId` 行为一致。
+5. 如果 IPv6 CIDR 在某些监听路径未命中，IPv4 行仍正常生效；测试应覆盖 IPv4，IPv6 通过 payload 合同保证下发。
+
+## 测试计划
+
+### 后端 contract 测试
+
+新增或扩展 `go-backend/tests/contract/max_conn_limit_contract_test.go`：
+
+1. 创建规则时设置 `ipMaxConn=5`，断言 `AddCLimiters` payload 包含 `$$ 5`。
+2. 同时设置 `maxConn=100` 和 `ipMaxConn=5`，断言 payload 包含 `$ 100` 和 `$$ 5`。
+3. 用户级 `MaxConn` 存在且规则 `ipMaxConn=5` 时，断言 payload 包含 `$ userMaxConn` 和 `$$ 5`。
+
+新增每 IP 限速 contract 测试：
+
+1. 创建规则时设置 `ipSpeedId`，断言 `AddLimiters` payload 包含 `0.0.0.0/0 ...` 和 `::/0 ...`。
+2. 同时设置 `speedId` 和 `ipSpeedId`，断言组合 limiter 包含 `$ ...` 与两个 CIDR 行，服务引用 `rule_traffic_limit_<forwardID>`。
+3. 普通用户提交 `ipSpeedId` 返回错误。
+
+### Repository/API 测试
+
+1. `CreateForwardTx`、`UpdateForward`、列表查询读写 `ip_max_conn` 和 `ip_speed_id`。
+2. `/forward/list` 返回 `ipMaxConn`、`ipSpeedId`。
+
+### GOST/x 测试
+
+1. `go-gost/x/limiter/conn`：验证 `$$ N` 为不同 IP 创建独立 limiter。
+2. `go-gost/x/limiter/traffic`：验证 `0.0.0.0/0` 为不同 IPv4 创建独立 limiter。
+3. UDP listener：验证 Accept 返回的 UDP pseudo-connection 关闭后释放 connection limiter。
+
+### 验证命令
+
+```bash
+(cd go-backend && go test ./...)
+(cd go-gost/x && go test ./limiter/... ./listener/udp/...)
+(cd vite-frontend && pnpm run build)
+```
+
+## 推荐实施顺序
+
+1. 后端模型、repo DTO、API 字段读写。
+2. 后端 limiter payload 构建与服务引用重构。
+3. Contract 测试覆盖连接数和带宽 payload。
+4. GOST UDP listener per-client wrapper 与相关测试。
+5. 前端高级设置表单和类型更新。
+6. 运行后端测试、GOST/x 相关测试、前端构建。
+
+## 风险
+
+1. UDP pseudo-connection 生命周期和 TCP 连接不同，连接数释放必须依赖 Close 包装正确执行。
+2. 总带宽和每 IP 带宽组合时 limiter 名称从纯 speed ID 变为 rule-level 名称，需要确保更新已有规则时不会留下错误引用。
+3. 旧节点如果没有 UDP wrapper 修复，TCP 生效但 UDP 每 IP 语义可能不完整；发布时应要求 agent 同步升级。
+4. 每 IP 带宽是每个入口节点本地独立限制，不是跨节点全局聚合限制。

docs/superpowers/specs/2026-04-28-monitoring-retention-storage-design.md

@@ -0,0 +1,74 @@
+# Monitoring Retention And Storage Display Design
+
+## Goal
+
+Add an administrator-facing configuration for monitoring data retention and display the current database storage usage in the configuration page.
+
+## Scope
+
+- Add a single config key: `monitor_retention_days`.
+- Default retention is `7` days.
+- Apply the retention window uniformly to:
+  - `node_metric`
+  - `tunnel_metric`
+  - `service_monitor_result`
+  - `tunnel_quality`
+- Show database usage on the config page as a read-only operational value.
+
+## Non-Goals
+
+- No per-table retention settings.
+- No manual purge button.
+- No database vacuum/compaction action.
+- No frontend test framework changes.
+
+## Backend Design
+
+### Retention Config
+
+- Store `monitor_retention_days` in `vite_config`, consistent with existing site settings.
+- Accept integer values from `1` through `3650`.
+- Missing or invalid stored values fall back to `7` days.
+- `normalizeAndValidateConfigValue` rejects invalid user-submitted values so bad config does not get saved through the API.
+
+### Cleanup Flow
+
+- `metrics.IngestionService.pruneMetrics()` reads `monitor_retention_days` from the repository each hourly cleanup cycle.
+- The computed cutoff is used for `node_metric`, `tunnel_metric`, and `service_monitor_result`.
+- `tunnel_quality` uses the same retention config.
+- `tunnel_quality` cleanup must run even when real-time tunnel quality probing is disabled; disabling probing should stop new probe writes, not stop cleanup.
+
+### Database Storage API
+
+- Add an admin-only API endpoint for storage summary, for example `/api/v1/system/storage`.
+- Response fields:
+  - `dbType`: `sqlite` or `postgres`
+  - `databaseSizeBytes`: raw byte count
+  - `databaseSizeText`: human-readable formatted size
+- SQLite implementation reports the DB file size and includes `-wal` and `-shm` sidecar files when present.
+- PostgreSQL implementation uses `pg_database_size(current_database())`.
+- If size cannot be determined, return an API error rather than a misleading zero.
+
+## Frontend Design
+
+- Add `monitor_retention_days` to the config page.
+- Label: `监控数据保留天数`.
+- Description: `统一清理节点指标、隧道流量、服务监控结果和隧道质量历史；默认 7 天。`
+- Use a regular numeric input through the existing config rendering path.
+- Fetch database storage summary when the config page loads.
+- Display a read-only card/row named `数据库占用` with `databaseSizeText`.
+- If fetching fails, show `获取失败` and keep config editing usable.
+
+## Error Handling
+
+- Invalid retention values return a validation error on save.
+- Cleanup logs individual prune failures and continues with other tables, matching existing monitoring cleanup behavior.
+- Storage summary failures are non-blocking in the frontend.
+
+## Testing
+
+- Backend unit tests for retention config parsing and validation.
+- Backend tests proving custom retention is used by monitoring cleanup.
+- Backend API/repository test for SQLite storage size returning a non-negative byte count and formatted text.
+- Run `go test ./...` in `go-backend`.
+- Run `pnpm run build` in `vite-frontend`.

docs/superpowers/specs/2026-05-01-best-exit-current-display-design.md

@@ -0,0 +1,156 @@
+# Best Exit Current Selection Display Design
+
+## Goal
+
+When a tunnel uses the `best` multi-exit strategy, show the currently applied best exit in the tunnel list information. Users should be able to see which exit is currently selected without opening logs or diagnosing the tunnel manually.
+
+The display is informational only. It must not change routing, scoring, switching behavior, or the saved tunnel configuration.
+
+## Current Context
+
+- `3.0.0-beta6` adds `best` as a multi-exit strategy.
+- Runtime selection is stored in the backend `bestExitManager` in memory, keyed by `TunnelID + OwnerNodeID`.
+- Direct multi-entry tunnels make one independent best-exit decision per entry node.
+- Tunnels with intermediate chain hops make one independent best-exit decision per final-hop chain node before the exits.
+- `tunnelList` and `tunnelGet` currently return `repo.ListTunnels()` output directly, so frontend tunnel data only includes configured exits from the database, not the currently applied runtime choice.
+- The frontend tunnel page maps API items in `vite-frontend/src/pages/tunnel.tsx` and renders list information from that data.
+
+## User Decisions
+
+- Show the current best-exit choice in the tunnel list information.
+- Use a summary plus detail model for multiple owners.
+- Follow the existing tunnel list refresh cadence; do not add polling or a realtime stream in this phase.
+- Work text-only; no visual companion is needed.
+
+## Approach
+
+Extend the existing tunnel list/detail response with a lightweight runtime state object for `best` tunnels, then render that state beside the tunnel's exit/strategy information in the existing frontend list UI.
+
+This keeps the display close to the data users already inspect and avoids a separate API or extra frontend request.
+
+## Backend Design
+
+### Response Shape
+
+Add a `bestExitState` object to each tunnel item returned by `tunnelList` and `tunnelGet` when the tunnel has a multi-exit group whose strategy is `best`.
+
+Response shape:
+
+```json
+{
+  "enabled": true,
+  "summary": "香港节点",
+  "status": "applied",
+  "updatedAt": 1777584000000,
+  "reason": "current exit remains best",
+  "items": [
+    {
+      "ownerNodeId": 10,
+      "ownerNodeName": "入口 A",
+      "ownerRole": "entry",
+      "exitNodeId": 30,
+      "exitNodeName": "香港节点",
+      "updatedAt": 1777584000000,
+      "reason": "current exit remains best"
+    }
+  ]
+}
+```
+
+If the tunnel is not using `best`, omit `bestExitState` or set it to `null`.
+
+### Owner Semantics
+
+The display must match the routing model:
+
+- If there are no middle chain hops, each entry node is an owner.
+- If there are middle chain hops, each node in the final middle-hop group is an owner.
+
+Each owner can have a different current best exit. The UI must not imply that a multi-owner tunnel has one global best exit when the owners differ.
+
+### Summary Rules
+
+- If all owners currently apply the same exit, `summary` is that exit node name.
+- If owners apply different exits, `summary` is `多个出口`.
+- If no applied decision exists yet, `summary` is `等待探测`.
+- If the tunnel has only one exit, `bestExitState` is not needed because there is no dynamic choice.
+
+### State Source
+
+Use the in-memory `bestExitManager` as the source of currently applied decisions.
+
+Add a read-only snapshot method that returns defensive copies of decision state without exposing mutable internal slices. The handler should convert node IDs to display names from the existing tunnel response data first, then fall back to `h.getNodeRecord` only when the current response does not contain the node.
+
+The feature should not persist current choices to the database in this phase. A panel restart may reset the displayed runtime state to `等待探测` until the prober initializes it again from the current saved first exit.
+
+## Frontend Design
+
+Extend the tunnel item type with optional `bestExitState`.
+
+In the tunnel list, only render the current best-exit display when:
+
+- `bestExitState.enabled === true`, or
+- the tunnel has an exit group with `strategy === "best"` and the backend returns a waiting state.
+
+Display format:
+
+- Single applied exit: `最优出口：香港节点`
+- Multiple applied exits: `最优出口：多个出口`
+- Waiting: `最优出口：等待探测`
+
+For multiple owners, render the summary as compact secondary text in the topology/list information cell and set its native `title` attribute to newline-separated detail rows. This avoids adding a new UI dependency or a custom popover. Detail rows should use:
+
+```text
+入口 A -> 香港节点
+入口 B -> 日本节点
+```
+
+For tunnels with middle chain hops, label owners as chain nodes when useful:
+
+```text
+中转 M1 -> 香港节点
+中转 M2 -> 日本节点
+```
+
+Do not add a new periodic refresh. The display updates when the existing tunnel list is refreshed.
+
+## Error Handling
+
+- If the manager has no decision for an owner, show that owner as `等待探测`.
+- If an exit node ID no longer exists in the current tunnel response, show `未知出口` for that item and keep the list usable.
+- If an owner node ID no longer exists, show `未知入口` or `未知中转` based on the owner role.
+- If the backend cannot compute state for one tunnel, omit `bestExitState` for that tunnel and log the error; do not fail the whole tunnel list response.
+
+## Testing
+
+Backend tests:
+
+- `bestExitManager` snapshot returns applied exit IDs without exposing mutable manager state.
+- Direct multi-entry `best` tunnel produces one display item per entry owner.
+- Middle-hop tunnel produces one display item per final-hop owner.
+- Summary is the single exit name when all owners choose the same exit.
+- Summary is `多个出口` when owners choose different exits.
+- Summary is `等待探测` when no applied decision exists.
+- Non-`best` tunnels do not receive `bestExitState`.
+
+Frontend verification:
+
+- Tunnel list renders `最优出口：<name>` for a single applied exit.
+- Tunnel list renders `最优出口：多个出口` plus owner details for multiple applied exits.
+- Tunnel list renders `最优出口：等待探测` for waiting state.
+- `pnpm run build` passes.
+
+Verification commands:
+
+```bash
+(cd go-backend && go test ./...)
+(cd vite-frontend && pnpm run build)
+```
+
+## Non-Goals
+
+- Do not add a new realtime stream or polling loop.
+- Do not add a detailed best-exit scoring dashboard.
+- Do not persist current best-exit choices to the database.
+- Do not change switching thresholds, probing targets, or runtime chain update behavior.
+- Do not change existing non-`best` tunnel display behavior.

docs/superpowers/specs/2026-05-01-best-exit-selection-design.md

@@ -0,0 +1,186 @@
+# Best Exit Selection Design
+
+## Goal
+
+Add a multi-exit tunnel strategy named `best` that always sends new connections through the currently best-quality exit. The feature should prevent traffic from continuing to use an exit whose latency or packet loss has degraded while the exit is still technically online.
+
+Existing connections must not be interrupted. Switching affects only new connections created after the runtime chain update is applied.
+
+## Current Context
+
+- Tunnel forwarding stores entry, chain, and exit nodes in `chain_tunnel`.
+- Multi-exit runtime chains are currently rendered as one GOST hop with multiple nodes.
+- GOST selectors support `fifo`, `round`, `rand`, and `hash`, plus fail filtering through `maxFails` and `failTimeout`.
+- The current fail filter only reacts to dial, handshake, or transport failures. It does not react to high latency when the exit is still reachable.
+- `tunnel_quality_prober` already runs panel-side TCP probes and stores tunnel quality history, but it currently probes representative nodes and does not drive runtime routing decisions.
+
+## User Decisions
+
+- Add a `best` option for multi-exit tunnels.
+- `best` means always choose the current best exit for new connections.
+- Score exits by end-to-end quality.
+- Keep the existing public probe target: `www.bing.com:443`.
+- Do not disrupt established connections.
+
+## Approach
+
+Implement `best` as a panel-driven control-plane strategy.
+
+The database stores the user's intended strategy as `best`. When the panel renders runtime GOST config for a `best` exit group, it sends a GOST selector strategy of `fifo`. The panel dynamically sorts the candidate exits so the current best exit is first. GOST then chooses the first node for new connections.
+
+This avoids adding active probing logic inside every GOST agent and reuses the existing panel-to-agent command path.
+
+## Components
+
+### Frontend
+
+The tunnel form adds `最优` to the multi-exit load strategy selector.
+
+- Label: `最优`
+- Value: `best`
+- Scope: tunnel forwarding exit groups, alongside `主备/fifo`, `轮询/round`, and `随机/rand`
+- Create and edit forms must submit and restore `best` unchanged.
+
+### Backend Data Model
+
+No schema change is required.
+
+The existing `chain_tunnel.strategy` column stores `best`. Repository and handler paths should preserve the value in API responses and updates.
+
+### Runtime Chain Rendering
+
+When building runtime chain config:
+
+- If the configured strategy is not `best`, keep existing behavior.
+- If the configured strategy is `best`, emit GOST selector strategy `fifo`.
+- Sort the target nodes using the panel's latest best-exit decision before rendering the node list.
+- If no quality decision exists yet, keep the saved node order.
+
+This preserves the user's `best` intent in storage while using a GOST selector that can execute the panel's sorted decision.
+
+### Quality Prober
+
+Extend `tunnel_quality_prober` to evaluate all candidates in `best` exit groups.
+
+For each chain owner node and candidate exit, measure:
+
+- Chain owner node to candidate exit using TCP ping.
+- Candidate exit to `www.bing.com:443` using TCP ping.
+
+For direct entry-to-exit tunnels, each entry node owns its own chain decision. For tunnels with intermediate chain hops, each node in the last hop group before the exits owns its own chain decision. This allows different entry or chain nodes to choose different best exits when their path quality differs.
+
+### Scoring
+
+Each exit candidate gets an end-to-end score for a specific chain owner node.
+
+- Total latency is the sum of owner-to-exit latency and exit-to-Bing latency.
+- Total loss combines both legs by success probability: `1 - (1 - lossA) * (1 - lossB)`.
+- Failed or unreachable candidates are sorted behind successful candidates.
+- The score should heavily penalize packet loss so that low-latency but lossy exits are not selected over stable exits.
+
+A practical scoring formula can be:
+
+```text
+score = totalLatencyMs + (totalLossPercent * lossPenaltyMsPerPercent)
+```
+
+Use `lossPenaltyMsPerPercent = 100` initially. For example, 5% loss adds 500ms to the score.
+
+### Switching Rules
+
+The panel should not update chains on every probe round.
+
+Switch only when all conditions are true:
+
+- The candidate best exit is different from the currently applied first exit.
+- The candidate is successful.
+- The candidate remains best for consecutive probe rounds.
+- The candidate beats the current exit by a minimum advantage threshold.
+- The chain owner node has passed a minimum switch cooldown.
+
+Initial constants:
+
+- Consecutive confirmations: 3 rounds.
+- Switch cooldown: 30 seconds per chain owner node.
+- Minimum advantage: the candidate score must improve by at least `max(20ms, currentScore * 0.15)`.
+
+If all exits fail, keep the current runtime order and do not issue a destructive update.
+
+### Runtime Update
+
+When a `best` chain owner node changes best exit:
+
+1. Rebuild that node's `chains_<tunnelID>` payload with the best exit first and remaining candidates sorted by quality for that node.
+2. Send `UpdateChains` to that chain owner node.
+3. Do not restart or update tunnel services.
+4. Record success or failure in logs and in the in-memory decision state.
+
+This affects only future connections. Existing TCP connections keep using the `net.Conn` created before the update and continue through their original exit.
+
+### Agent Safety Improvement
+
+The current agent `UpdateChains` path unregisters the old chain before registering the new chain. This does not kill existing connections, but it creates a small window where a new connection can fail because the chain name is temporarily absent.
+
+Improve the update path so it parses the new chain first and only replaces the registered chain after parsing succeeds. The replacement window should be as small as possible. If parsing fails, the old chain must remain active.
+
+## Error Handling
+
+- If probing one candidate fails, continue scoring other candidates.
+- If a chain owner node is offline or times out, skip decisions for that owner during the round instead of marking every candidate failed.
+- If a candidate has no successful required probe data, mark it failed for that round.
+- If `UpdateChains` fails, keep the current applied order and retry on a later round.
+- If the tunnel has one exit or an incomplete config, `best` behaves like the saved order and does not trigger dynamic switching.
+- If `monitor_tunnel_quality_enabled=false`, dynamic `best` switching pauses. The last applied runtime order remains in effect.
+
+## Observability
+
+The prober should maintain in-memory decision state per `best` tunnel and chain owner node.
+
+Useful fields:
+
+- Tunnel ID and chain owner node ID.
+- Current applied best exit node ID.
+- Candidate best exit node ID.
+- Candidate scores.
+- Last switch timestamp.
+- Last switch result.
+- Reason for not switching, such as cooldown, insufficient advantage, candidate unstable, or all exits failed.
+
+Initial UI scope is limited to supporting create, update, and display of the `best` strategy. A later enhancement can expose current best exit and candidate scores in the tunnel monitor view.
+
+## Testing
+
+Backend tests:
+
+- Score calculation orders candidates by latency and packet loss.
+- Packet loss penalty prevents lossy exits from winning only because latency is low.
+- All-failed candidates do not trigger a switch.
+- Consecutive confirmation and cooldown prevent flapping.
+- `strategy=best` persists in `chain_tunnel.strategy` and is returned by tunnel list/get APIs.
+- Runtime rendering maps `best` to GOST `fifo` and places the chosen best exit first.
+
+Agent tests:
+
+- `UpdateChains` parse failure keeps the old chain registered.
+- Successful `UpdateChains` updates the chain used by new connections.
+
+Frontend verification:
+
+- Tunnel form includes `最优` in the exit strategy selector.
+- Existing tunnels with `strategy=best` render correctly.
+- Create and update requests submit `best` unchanged.
+
+Verification commands:
+
+```bash
+(cd go-backend && go test ./...)
+(cd go-gost && go test ./...)
+(cd vite-frontend && pnpm run build)
+```
+
+## Non-Goals
+
+- Do not move existing live connections to a new exit.
+- Do not add per-tunnel custom probe targets in this phase.
+- Do not implement active best-exit probing inside GOST agents.
+- Do not add a detailed best-exit UI dashboard in this phase.

docs/superpowers/specs/2026-05-01-custom-best-exit-probe-target-design.md

@@ -0,0 +1,180 @@
+# Custom Best-Exit Probe Target Design
+
+Date: 2026-05-01
+Status: Approved design
+
+## Goal
+
+Allow each tunnel to define the TCP target used for exit-side quality probing instead of always probing `www.bing.com:443`.
+
+The custom target must be used consistently by:
+
+- `best` exit scoring: each exit probes the configured target to measure exit-to-public quality.
+- Tunnel quality monitoring: the existing exit-side quality check probes the same configured target.
+
+If a tunnel does not configure a target, behavior remains compatible with today: `www.bing.com:443`.
+
+## Non-Goals
+
+- Do not add HTTP/HTTPS request probing in this phase. The probe remains TCP host/port measurement.
+- Do not add a global default target setting in this phase.
+- Do not require existing tunnels to be edited or migrated manually.
+- Do not change the `best` switching thresholds, confirmation rounds, cooldowns, or runtime chain ordering semantics.
+- Do not add frontend test infrastructure.
+
+## User-Facing Behavior
+
+Each tunnel form gets a compact quality target section:
+
+- Host input, placeholder `www.bing.com`.
+- Port input, placeholder `443`.
+- Helper text: this target is used for tunnel quality detection and `best` optimal-exit scoring; leaving it empty uses `www.bing.com:443`.
+
+Tunnel list/get responses include the configured target so edit forms can round-trip it. The UI displays the effective target near quality/best-exit information as `测试目标：host:port`.
+
+## Data Model
+
+Add nullable/default-compatible fields to `model.Tunnel`:
+
+- `ProbeTargetHost string` mapped to `probe_target_host`, `type:text`, default `''`.
+- `ProbeTargetPort int` mapped to `probe_target_port`, default `0`.
+
+Effective target resolution:
+
+- If `ProbeTargetHost` is non-empty and `ProbeTargetPort` is valid, use it.
+- Otherwise use `www.bing.com:443`.
+
+The existing `TunnelQuality` persisted fields `exit_to_bing_latency` and `exit_to_bing_loss` remain unchanged for compatibility. They will semantically mean exit-to-configured-test-target after this change. API/UI labels should avoid saying `Bing` for new displays.
+
+## Validation
+
+On create/update:
+
+- Empty host and empty/zero port are allowed and mean default target.
+- If either host or port is set, validate both as a pair.
+- Host is trimmed and must not contain URL scheme, path, query, or whitespace.
+- Host can be a domain, IPv4, or IPv6 literal. Bracketed IPv6 input should be normalized by removing surrounding brackets.
+- Port must be an integer from `1` to `65535`.
+- Do not perform network probing during save; external network failures must not block configuration changes.
+
+Errors should be specific, for example:
+
+- `测试目标 Host 不能为空`
+- `测试目标端口必须是 1-65535`
+- `测试目标 Host 不能包含协议或路径`
+
+## Backend Flow
+
+Introduce a small value/helper near the tunnel quality and best-exit code:
+
+```go
+type tunnelProbeTarget struct {
+    Host string
+    Port int
+}
+```
+
+Helpers:
+
+- `defaultTunnelProbeTarget() tunnelProbeTarget` returns `www.bing.com:443`.
+- `normalizeTunnelProbeTarget(host string, port int) (tunnelProbeTarget, bool, error)` validates user input; the boolean indicates whether the user explicitly configured a target.
+- `effectiveTunnelProbeTarget(tunnel *model.Tunnel) tunnelProbeTarget` returns configured target or default.
+
+Use the effective target in `tunnelQualityProber.probeTunnel`:
+
+- Type 1 and unknown tunnel fallback probes entry node to effective target instead of hardcoded Bing.
+- Type 2 probes the selected/current exit node to effective target instead of hardcoded Bing.
+- `probeBestExitOwners` receives the effective target and passes it into best-exit owner scoring.
+
+Use the effective target in `evaluateBestExitOwner`:
+
+- Owner-to-exit measurement stays unchanged.
+- Exit-to-public measurement probes `target.Host:target.Port` instead of `bestExitPublicTargetHost:bestExitPublicTargetPort`.
+- The per-round public probe cache key must include node ID plus target host and port so future extensions cannot reuse measurements across different targets.
+
+## API Shape
+
+Tunnel list/get data includes:
+
+```json
+{
+  "probeTargetHost": "example.com",
+  "probeTargetPort": 443
+}
+```
+
+For old/default tunnels, return empty host and `0` to represent `use default`. The edit form must preserve default-as-empty unless the user explicitly saves a custom target.
+
+Quality monitoring response includes effective target display metadata:
+
+```json
+{
+  "probeTargetHost": "www.bing.com",
+  "probeTargetPort": 443
+}
+```
+
+Existing `exitToBingLatency` and `exitToBingLoss` keys stay to avoid breaking frontend and external consumers.
+
+## Frontend Flow
+
+Extend `ChainTunnel` only if needed for node-level data; the target belongs to the tunnel, so `Tunnel` and `TunnelForm` get:
+
+- `probeTargetHost?: string`
+- `probeTargetPort?: number`
+
+On edit:
+
+- Populate form fields from tunnel response.
+- Empty or zero means default target.
+
+On submit:
+
+- Trim host.
+- Convert blank port to `0`.
+- Send `probeTargetHost` and `probeTargetPort` with create/update payload.
+
+Display:
+
+- In the form helper, show default target behavior.
+- In quality/best-exit display areas, avoid `Bing` wording; prefer `测试目标` or the concrete `host:port`.
+
+## Error Handling
+
+- Invalid target input returns a normal API error envelope with a specific message.
+- Probe failures use existing quality error paths and best-exit scoring failure entries.
+- If all exit-to-target probes fail, best-exit behavior remains the same as today when all Bing probes fail: no valid best decision is applied from that round.
+
+## Testing
+
+Backend tests:
+
+- Normalize default target when host/port are empty.
+- Reject partial host/port configuration and invalid port ranges.
+- Reject host values with URL scheme/path/whitespace.
+- Create/update tunnel persists `probeTargetHost` and `probeTargetPort`.
+- `ListTunnels` returns target fields.
+- `tunnelQualityProber` uses configured target instead of `www.bing.com:443`.
+- `best` scoring uses configured target for exit-to-target probes.
+- Empty target preserves old default `www.bing.com:443` behavior.
+
+Frontend verification:
+
+- `pnpm run build` passes.
+- Manual UI check: create/edit tunnel with blank target and custom target, confirm payload and round-trip display.
+
+## Rollout And Compatibility
+
+- Existing tunnels continue using `www.bing.com:443` because empty target resolves to default.
+- SQLite/PostgreSQL schema changes are handled by existing auto-migration.
+- Historical `TunnelQuality` rows keep existing columns and are not rewritten.
+- No runtime agent change is required; the panel already performs these quality probes through existing node ping APIs.
+
+## Open Decisions
+
+None. User-approved decisions:
+
+- Per-tunnel fields are `host + port`.
+- The target applies to both `best` scoring and tunnel quality monitoring.
+- Probe type remains TCP host/port.
+- Empty target defaults to `www.bing.com:443`.

docs/superpowers/specs/2026-05-04-panel-self-upgrade-design.md

@@ -0,0 +1,295 @@
+# 面板本体一键升级设计
+
+**日期**: 2026-05-04
+**状态**: 待审核
+**作者**: AI Assistant
+
+## 概述
+
+在 FLVX 管理面板中增加“面板升级”能力，使管理员可以在网页上检查 GitHub Release 并触发面板本体升级。目标是升级整套面板，而不是只升级转发节点或只替换后端二进制。
+
+本设计采用 Docker Compose 整套升级方案：后端容器通过受限的 Docker socket 能力更新宿主机部署目录中的 `docker-compose.yml` 和 `.env`，然后启动独立的升级 helper 容器，由 helper 拉取新版 backend/frontend 镜像并重新启动 `backend` 与 `frontend` 服务。
+
+## sub2api 参考结论
+
+sub2api 的一键升级不是在宿主机执行 `docker compose pull/up`。它的运行形态是单体 Go 服务：前端构建产物 embed 到后端二进制，容器内只运行 `/app/sub2api`。升级接口下载 GitHub Release 中匹配当前系统和架构的 `sub2api_<version>_<os>_<arch>.tar.gz` 以及 `checksums.txt`，校验后把当前 `os.Executable()` 指向的 `/app/sub2api` 改名为 `/app/sub2api.backup`，再把新二进制原子替换到原路径。重启接口延迟调用 `os.Exit(0)`，依赖 Docker Compose 的 `restart: unless-stopped` 拉起同一个容器。
+
+这种方式在 sub2api 的 Docker 部署中可行，是因为它的前后端在同一个二进制里。FLVX 当前是 `flux-panel-backend` 与 `vite-frontend` 两个容器，替换 `/app/paneld` 只能升级后端，不能升级前端页面。因此 FLVX 的“面板本体升级”需要更新 Compose 版本和两个镜像，而不是照搬二进制替换。
+
+## 目标
+
+1. 管理员可在面板上查看当前版本、最新版本、升级通道和升级能力状态。
+2. 管理员可一键升级整套面板 backend/frontend。
+3. 升级复用现有 GitHub Release 和 `FLUX_VERSION` 版本机制。
+4. 升级复用现有 GitHub 加速配置 `github_proxy_enabled` / `github_proxy_url`。
+5. 升级过程不接受任意命令、任意 URL 或任意 compose 路径。
+6. 环境不满足时清晰提示不可用原因，不静默失败。
+
+## 非目标
+
+1. 不实现 sub2api 式后端二进制替换作为本次主路径。
+2. 不支持从非本仓库 Release 下载升级资产。
+3. 不支持普通用户触发升级。
+4. 不支持在前端执行 shell 命令。
+5. 不修改 `install.sh` 或 `panel_install.sh` 的本地安装菜单逻辑；发布流程仍可能覆盖这些脚本。
+6. 不引入前端测试框架。
+
+## 影响范围
+
+### 后端
+
+- `go-backend/internal/http/handler/handler.go`
+- `go-backend/internal/http/handler/upgrade.go`
+- 新增 `go-backend/internal/http/handler/system_upgrade.go`
+- 新增 `go-backend/internal/http/handler/system_upgrade_test.go`
+- `go-backend/Dockerfile`
+
+### 部署模板
+
+- `docker-compose-v4.yml`
+- `docker-compose-v6.yml`
+
+### 前端
+
+- `vite-frontend/src/api/index.ts`
+- `vite-frontend/src/api/types.ts`
+- `vite-frontend/src/pages/config.tsx`
+
+## 运行前提
+
+升级能力仅在 Docker Compose 部署中可用，并要求后端容器具备以下条件：
+
+1. 容器内存在 Docker CLI，且支持 `docker compose version`。
+2. `/var/run/docker.sock` 挂载到后端容器。
+3. 宿主部署目录挂载到容器内固定路径，例如 `/opt/flvx-panel`。
+4. 环境变量 `PANEL_DEPLOY_DIR=/opt/flvx-panel`。
+5. 环境变量 `PANEL_BACKEND_CONTAINER=flux-panel-backend`，为空时默认使用 `flux-panel-backend`；值必须匹配容器名安全字符集 `[A-Za-z0-9_.-]+`。
+6. 部署目录内存在 `.env` 和 `docker-compose.yml`。
+
+如果任一条件不满足，检查接口返回 `capable=false` 和明确的 `reason`，升级按钮禁用。
+
+## 后端设计
+
+### API
+
+新增系统升级接口，路径使用 `/api/v1/system/*`，继续受现有 middleware 管控，仅管理员可访问。
+
+| 方法 | 路径 | 用途 |
+|------|------|------|
+| `POST` | `/api/v1/system/version` | 返回当前版本、升级通道、能力状态和可选最新版本 |
+| `POST` | `/api/v1/system/check-updates` | 强制查询 GitHub Release，返回最新版本和候选列表 |
+| `POST` | `/api/v1/system/upgrade` | 执行升级 |
+
+请求体：
+
+```json
+{
+  "channel": "stable",
+  "version": ""
+}
+```
+
+`channel` 使用现有节点升级的通道语义：`stable` 匹配纯数字版本，`dev` 匹配 `alpha` / `beta` / `rc`。`version` 为空时自动选择该通道最新 Release。
+
+`/api/v1/system/version` 返回：
+
+```json
+{
+  "currentVersion": "2.1.9-beta14",
+  "channel": "stable",
+  "latestVersion": "2.1.9",
+  "hasUpdate": true,
+  "capable": true,
+  "reason": "",
+  "deployDir": "/opt/flvx-panel",
+  "composeFile": "/opt/flvx-panel/docker-compose.yml",
+  "backendContainer": "flux-panel-backend"
+}
+```
+
+`/api/v1/system/upgrade` 成功返回：
+
+```json
+{
+  "version": "2.1.9",
+  "message": "升级 helper 已启动，面板服务将短暂重启",
+  "commands": [
+    "docker run -d --rm --volumes-from flux-panel-backend ...",
+    "docker compose pull backend frontend",
+    "docker compose up -d backend frontend"
+  ]
+}
+```
+
+返回的 `commands` 只用于 UI 展示固定步骤，不包含用户输入或 shell 拼接结果。
+
+### 版本来源
+
+当前版本优先从容器环境变量读取：
+
+1. `FLUX_VERSION`
+2. `VITE_APP_VERSION` 不在后端容器中可靠存在，不作为后端版本来源。
+3. 为空时返回 `dev`。
+
+发布流程已经在 `panel_install.sh` 写入 `.env` 的 `FLUX_VERSION`，Compose 模板需要把该变量传给 backend 容器，保证后端可感知当前版本。
+
+### Release 查询
+
+复用现有 `fetchGitHubReleases`、`resolveLatestReleaseByChannel`、`normalizeReleaseChannel`、`releaseChannelFromTag`、`releaseChannelLabel` 和 GitHub 加速配置能力。新增函数只负责筛选系统升级所需资产：
+
+- `docker-compose-v4.yml`
+- `docker-compose-v6.yml`
+
+是否下载 v4/v6 compose 文件通过当前部署目录中的 `docker-compose.yml` 判断：如果网络定义包含 `enable_ipv6: true`，选择 `docker-compose-v6.yml`；否则选择 `docker-compose-v4.yml`。
+
+### 升级执行器
+
+新增 `systemUpgradeExecutor`，职责明确分为可测试的小函数：
+
+1. `checkSystemUpgradeCapability()` 检查 Docker CLI、Docker socket、部署目录、`.env`、`docker-compose.yml`。
+2. `selectComposeAsset(currentCompose []byte) string` 选择 v4/v6 compose 资产。
+3. `updateEnvVersion(path, version string) error` 原子更新 `.env` 中的 `FLUX_VERSION`。
+4. `downloadCompose(version, assetName, dest string) error` 下载新版 compose 模板到临时文件。
+5. `currentBackendImage(containerName string) (string, error)` 获取当前 backend 容器镜像 ID。
+6. `startSystemUpgradeHelper(version string) error` 启动独立 helper 容器执行固定升级流程。
+
+升级流程：
+
+1. 获取全局升级锁，拒绝并发升级。
+2. 校验目标版本存在且不是 draft。
+3. 检查升级能力。
+4. 备份 `.env` 为 `.env.upgrade.bak`，备份 `docker-compose.yml` 为 `docker-compose.yml.upgrade.bak`。
+5. 下载目标版本的 compose 文件到部署目录临时文件。
+6. 原子替换 `docker-compose.yml`。
+7. 原子更新 `.env` 的 `FLUX_VERSION`。
+8. 通过 Docker socket 查询当前 backend 容器的镜像 ID。
+9. 使用当前 backend 镜像启动一个不属于 Compose 项目的临时 helper 容器。
+10. helper 通过 `--volumes-from flux-panel-backend` 继承部署目录挂载，并显式挂载 `/var/run/docker.sock`。
+11. helper 在 `PANEL_DEPLOY_DIR` 下执行 `docker compose pull backend frontend`。
+12. helper 等待 5 秒，让 SQLite WAL 等文件刷盘。
+13. helper 执行 `docker compose up -d backend frontend`，由 Compose 重建前端和后端。
+14. 后端接口在 helper 成功启动后立即返回；浏览器随后会经历短暂断线。
+
+PostgreSQL 模式不主动 pull 或重建 `postgres` 服务，避免无关数据库变动。新版 compose 文件仍保留 postgres 配置供后续手动迁移或重建使用。
+
+### 命令安全
+
+后端不暴露通用命令执行能力。后端只直接执行 Docker CLI 的固定参数，用于获取当前镜像和启动 helper：
+
+```go
+exec.CommandContext(ctx, "docker", "inspect", "-f", "{{.Image}}", backendContainer)
+exec.CommandContext(ctx, "docker", "run", "-d", "--rm", "--name", helperName,
+  "--volumes-from", backendContainer,
+  "-v", "/var/run/docker.sock:/var/run/docker.sock",
+  "-e", "PANEL_DEPLOY_DIR=/opt/flvx-panel",
+  "--entrypoint", "/bin/sh", imageID,
+  "-c", helperScript)
+```
+
+`helperScript` 由后端固定生成，不拼接用户输入：
+
+```sh
+cd "$PANEL_DEPLOY_DIR" && docker compose pull backend frontend && sleep 5 && docker compose up -d backend frontend
+```
+
+工作目录固定为 `PANEL_DEPLOY_DIR`。`PANEL_DEPLOY_DIR` 必须是绝对路径，且必须包含 `.env` 和 `docker-compose.yml`。接口输入只允许影响 `channel` 和已验证的 Release `version`。
+
+### 超时和错误处理
+
+1. Release 查询超时沿用现有 GitHub API 客户端超时。
+2. 下载 compose 文件使用 60 秒超时。
+3. 启动 helper 使用 30 秒超时，helper 内部命令不受原 HTTP 请求生命周期影响。
+4. 任一步失败时返回错误信息，并尽量保留 `.upgrade.bak` 供人工恢复。
+5. 如果 `.env` 更新后后续步骤失败，不自动回滚镜像或容器，避免误判导致更大破坏；错误信息提示备份文件位置。
+
+## 部署模板设计
+
+`docker-compose-v4.yml` 和 `docker-compose-v6.yml` 的 backend 服务增加：
+
+```yaml
+environment:
+  FLUX_VERSION: ${FLUX_VERSION:-dev}
+  PANEL_DEPLOY_DIR: /opt/flvx-panel
+  PANEL_BACKEND_CONTAINER: flux-panel-backend
+volumes:
+  - sqlite_data:/app/data
+  - /var/run/docker.sock:/var/run/docker.sock
+  - ./:/opt/flvx-panel
+```
+
+`go-backend/Dockerfile` 的 runtime 镜像通过多阶段构建从官方 `docker:27-cli` 镜像复制 Docker CLI 和 compose 插件到 Debian runtime 镜像，避免依赖 Debian apt 源中的 Docker 包可用性：
+
+```dockerfile
+FROM docker:27-cli AS dockercli
+FROM debian:bookworm-slim
+COPY --from=dockercli /usr/local/bin/docker /usr/local/bin/docker
+COPY --from=dockercli /usr/local/libexec/docker/cli-plugins/docker-compose /usr/local/libexec/docker/cli-plugins/docker-compose
+```
+
+实现时保留现有 Go builder 和 `/app/paneld` 入口，仅增加 Docker CLI stage 和复制步骤。
+
+helper 容器使用当前 backend 容器的镜像 ID 启动，而不是额外依赖 `docker:cli` 镜像。这样不引入新的镜像仓库依赖，并保证 helper 内可用的 Docker CLI 与当前后端一致。
+
+## 前端设计
+
+在 `vite-frontend/src/pages/config.tsx` 的基本设置或数据库占用附近增加“面板升级”卡片，避免隐藏在节点页导致误解为“节点升级”。
+
+展示内容：
+
+1. 当前版本。
+2. 最新版本。
+3. 更新通道选择，复用现有 `stable` / `dev` 语义和 `UpdateReleaseChannel` 本地存储。
+4. 升级能力状态：可用、不可用原因、Docker socket 高权限提示。
+5. 操作按钮：检查更新、立即升级。
+
+交互：
+
+1. 页面加载时调用 `/system/version`。
+2. 点击“检查更新”调用 `/system/check-updates`。
+3. 点击“立即升级”前弹出确认框，明确提示服务会短暂中断，并提示 Docker socket 具备宿主高权限。
+4. 升级请求只等待 helper 启动，超时设置为 60 秒。
+5. 成功后 toast 显示“升级已触发，面板将在数十秒内重启”，并可提示用户稍后刷新。
+
+## 安全边界
+
+Docker socket 挂载等同于给后端容器宿主机级别控制能力。这是本设计的主要风险。缓解措施：
+
+1. 仅 `/api/v1/system/*` 管理员接口可触发。
+2. 不提供任意命令执行接口。
+3. 不允许用户传入下载 URL。
+4. 不允许用户传入 compose 路径。
+5. 只升级本仓库 GitHub Release，且跳过 draft。
+6. 前端明确展示 Docker socket 权限提示。
+
+## 测试策略
+
+### Go 单测
+
+新增 `system_upgrade_test.go` 覆盖：
+
+1. `selectComposeAsset` 对 v4/v6 compose 内容的判断。
+2. `.env` 中已有 `FLUX_VERSION` 时更新值。
+3. `.env` 中缺少 `FLUX_VERSION` 时追加值。
+4. 缺少部署目录、`.env`、`docker-compose.yml`、Docker socket 时返回不可用原因。
+5. helper 命令构造固定命令序列，不拼接用户输入。
+6. 并发升级锁会拒绝第二个升级请求。
+
+### 手动/集成验证
+
+1. `go-backend`: `go test ./...`
+2. `vite-frontend`: `pnpm run build`
+3. 本地容器验证：启动 Compose 后检查设置页升级卡片可显示能力状态。
+4. 在无 Docker socket 的开发环境验证按钮禁用并显示原因。
+
+## 回滚与恢复
+
+自动升级失败时不做自动容器回滚。后端会保留：
+
+1. `.env.upgrade.bak`
+2. `docker-compose.yml.upgrade.bak`
+
+人工恢复步骤由错误信息提示：进入部署目录，按需恢复备份文件，再执行 `docker compose up -d backend frontend`。
+
+## 决策记录
+
+本设计已确定采用 Docker socket 整套升级方案，不再保留二进制替换作为本次实现路径。Docker socket 的权限风险通过管理员限制、命令白名单和前端提示控制。

go-backend/AGENTS.md

@@ -0,0 +1,38 @@
+# go-backend
+
+Admin API for FLVX. Go + net/http + GORM (SQLite/PostgreSQL).
+
+## Structure
+
+| Dir | Role |
+|-----|------|
+| `cmd/paneld/main.go` | Entry point, HTTP server + WebSocket |
+| `internal/http/router.go` | Route registration (`http.ServeMux`) + middleware chain |
+| `internal/http/handler/` | API handlers |
+| `internal/http/middleware/` | JWT, CORS, logging, recover |
+| `internal/http/response/` | JSON envelope helpers |
+| `internal/store/model/model.go` | All GORM models (single file) |
+| `internal/store/repo/` | Repository layer (never access DB directly) |
+| `internal/auth/` | Auth logic |
+| `tests/contract/` | Integration tests |
+
+## Conventions
+
+- **Auth**: raw JWT in `Authorization` header — no `Bearer` prefix.
+- **API envelope**: `{code, msg, data, ts}`, code 0 = success.
+- **Repository pattern**: handlers call repo methods, never `repo.DB()` directly.
+- **GORM**: `TableName()` on every model (GORM pluralizes by default).
+- **GORM tags**: no `type:jsonb` or `type:serial` (SQLite incompatible).
+- **SQLite**: `MaxOpenConns(1)`, WAL mode, `busy_timeout=5000`.
+- **Schema**: created via `autoMigrateAll()` at startup, no hand-written DDL.
+- **PostgreSQL**: set `DB_TYPE=postgres` and `DATABASE_URL` env vars.
+- **Config**: all from environment variables.
+
+## Commands
+
+```bash
+go run ./cmd/paneld           # SERVER_ADDR defaults to :6365
+make build
+go test ./...                 # includes contract tests
+go test ./tests/contract/...  # contract tests only
+```

go-backend/Dockerfile

@@ -0,0 +1,23 @@
+FROM golang:1.25-bookworm AS builder
+WORKDIR /src
+
+COPY go.mod go.sum ./
+RUN go mod download
+
+COPY . .
+ARG TARGETOS
+ARG TARGETARCH
+RUN CGO_ENABLED=0 GOOS=${TARGETOS:-linux} env ${TARGETARCH:+GOARCH=${TARGETARCH}} go build -o /out/paneld ./cmd/paneld
+
+FROM docker:27-cli AS dockercli
+
+FROM debian:bookworm-slim
+WORKDIR /app
+RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates wget && rm -rf /var/lib/apt/lists/*
+COPY --from=builder /out/paneld /app/paneld
+COPY --from=dockercli /usr/local/bin/docker /usr/local/bin/docker
+COPY --from=dockercli /usr/local/libexec/docker/cli-plugins/docker-compose /usr/local/libexec/docker/cli-plugins/docker-compose
+
+ENV SERVER_ADDR=:6365
+EXPOSE 6365
+ENTRYPOINT ["/app/paneld"]

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` | 增加 `proxy_protocol` 字段 |
+| `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/Makefile

@@ -0,0 +1,12 @@
+GO ?= go
+
+.PHONY: test build run
+
+test:
+	$(GO) test ./...
+
+build:
+	$(GO) build ./cmd/paneld
+
+run:
+	SERVER_ADDR=:6365 $(GO) run ./cmd/paneld