From 4bdfa50b0c7a6fa49b2765d9dc0e0ce86c21564a Mon Sep 17 00:00:00 2001 From: sagit <36596628+Sagit-chu@users.noreply.github.com> Date: Thu, 26 Feb 2026 09:52:11 +0800 Subject: [PATCH] docs: update AGENTS.md files with current project state (#213) - Update root AGENTS.md to commit 21008cc / tag 2.1.5-rc15 - Add CI workflows info (ci-build.yml, docker-build.yml, deploy-docs.yml) - Add Repository Layer and Contract Tests to WHERE TO LOOK - Add websocket_reporter to CODE MAP - Add Go version conventions (1.24/1.23/1.22) - Add PostgreSQL migration support note - Update go-backend AGENTS.md with PostgreSQL support and contract tests - Update go-gost AGENTS.md with CI build conventions - Update vite-frontend AGENTS.md with component counts - Update go-gost/x AGENTS.md with file counts and registry reference - Update handler AGENTS.md with LOC estimates --- AGENTS.md | 40 ++++++++++++++++------ go-backend/AGENTS.md | 20 ++++++----- go-backend/internal/http/handler/AGENTS.md | 9 ++--- go-gost/AGENTS.md | 12 ++++--- go-gost/x/AGENTS.md | 21 ++++++------ vite-frontend/AGENTS.md | 23 ++++++------- 6 files changed, 75 insertions(+), 50 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 99fe253..d248e54 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,12 +1,12 @@ # PROJECT KNOWLEDGE BASE -**Generated:** Thu Feb 19 2026 -**Commit:** 137c34e +**Generated:** Thu Feb 26 2026 +**Commit:** 21008cc **Branch:** main -**Tag:** 2.1.4-rc2 +**Tag:** 2.1.5-rc15 ## OVERVIEW -FLVX (formerly Flux Panel) is a traffic forwarding management system built on a forked GOST v3 stack. It ships as a Go-based admin API (SQLite) + Vite/React UI + Go forwarding agent, with optional mobile WebView wrappers. +FLVX (formerly Flux Panel) is a traffic forwarding management system built on a forked GOST v3 stack. It ships as a Go-based admin API (SQLite/PostgreSQL) + Vite/React UI + Go forwarding agent, with optional mobile WebView wrappers. ## STRUCTURE ``` @@ -14,12 +14,14 @@ FLVX (formerly Flux Panel) is a traffic forwarding management system built on a ├── go-gost/ # Go forwarding agent (forked gost + local x/) │ └── x/ # Local fork of github.com/go-gost/x (replace => ./x) ├── go-backend/ # Go Admin API (GORM + SQLite/PostgreSQL, net/http) +│ └── tests/contract/ # Integration/contract tests ├── vite-frontend/ # React/Vite dashboard (shadcn bridge + Tailwind v4) +│ └── src/shadcn-bridge/heroui/ # HeroUI-compatible facade ├── docker-compose-v4.yml # Panel deploy (IPv4-only bridge) ├── docker-compose-v6.yml # Panel deploy (IPv6-enabled bridge) ├── panel_install.sh # Panel installer/upgrader (downloads compose) ├── install.sh # Node installer/upgrader (downloads gost binary) -└── .github/workflows/ # CI: build/push images + release artifacts +└── .github/workflows/ # CI: build/test + Docker push + release artifacts ``` ## WHERE TO LOOK @@ -29,12 +31,15 @@ FLVX (formerly Flux Panel) is a traffic forwarding management system built on a | **Deploy (IPv6)** | `docker-compose-v6.yml` | Same as v4 + IPv6-enabled bridge | | **Panel install** | `panel_install.sh` | Picks v4/v6, generates `JWT_SECRET`, downloads compose | | **Node install** | `install.sh` | Installs `/etc/flux_agent/flux_agent` + writes `config.json`/`gost.json` + systemd `flux_agent.service` | -| **Admin API** | `go-backend/` | Go Admin API (SQLite) | +| **Admin API** | `go-backend/` | Go Admin API (SQLite/PostgreSQL) | | **Web UI** | `vite-frontend/` | React/Vite dashboard (shadcn bridge + Tailwind v4) | | **UI Compatibility** | `vite-frontend/src/shadcn-bridge/heroui/` | HeroUI-compatible API wrappers backed by shadcn/radix | | **Theme Tokens** | `vite-frontend/src/styles/tailwind-theme.pcss` | Tailwind v4 `@theme inline` semantic color mapping | | **Go Agent** | `go-gost/` | Forwarding agent (forked gost + local x/) | | **Go Core** | `go-gost/x/` | Handlers/listeners/dialers + management API | +| **Repository Layer** | `go-backend/internal/store/repo/` | GORM data access (repository.go 83k LOC) | +| **Contract Tests** | `go-backend/tests/contract/` | Integration tests for auth, federation, tunnels | +| **CI Workflows** | `.github/workflows/` | ci-build.yml, docker-build.yml, deploy-docs.yml | ## CODE MAP | Symbol | Type | Location | Role | @@ -43,7 +48,9 @@ FLVX (formerly Flux Panel) is a traffic forwarding management system built on a | `main` | Func | `go-backend/cmd/paneld/main.go` | Backend Entry | | `App` | Component | `vite-frontend/src/App.tsx` | Frontend Entry | | `main` | Func | `go-gost/main.go` | Agent Entry | - +| `Repository` | Struct | `go-backend/internal/store/repo/repository.go` | Data Access Layer | +| `Handler` | Struct | `go-backend/internal/http/handler/handler.go` | HTTP Handlers | +| `websocket_reporter` | Func | `go-gost/x/socket/websocket_reporter.go` | Panel Telemetry | ## CONVENTIONS - **Auth**: `Authorization` header carries the raw JWT token (no `Bearer` prefix) between `vite-frontend/` and `go-backend/`. @@ -52,6 +59,7 @@ FLVX (formerly Flux Panel) is a traffic forwarding management system built on a - **API Envelope**: All REST responses follow `{code, msg, data, ts}` structure (code 0 = success). - **Frontend UI Layer**: Import UI primitives from `src/shadcn-bridge/heroui/*` (legacy-compatible facade), not direct `@heroui/*` packages. - **Tailwind v4 Semantic Colors**: `src/styles/globals.css` must import `src/styles/tailwind-theme.pcss`; removing it breaks semantic classes like `bg-primary`, `text-foreground`, and `border-input`. +- **Go Versions**: `go-backend` uses Go 1.24, `go-gost` uses Go 1.23, `go-gost/x` uses Go 1.22. ## ANTI-PATTERNS (THIS PROJECT) - **DO NOT EDIT** generated protobuf output: `go-gost/x/internal/util/grpc/proto/*.pb.go`, `go-gost/x/internal/util/grpc/proto/*_grpc.pb.go`. @@ -60,6 +68,8 @@ FLVX (formerly Flux Panel) is a traffic forwarding management system built on a - **DO NOT** let backend handlers call `repo.DB()` directly — add a Repository method instead. - **DO NOT ADD** frontend tests - project has no test infrastructure (Vitest/Jest not configured). - **DO NOT REINTRODUCE** `@heroui/*` or `@nextui-org/*` dependencies; migration is now shadcn bridge-based. +- **DO NOT** use `type:jsonb` or `type:serial` in GORM tags (SQLite incompatible). +- **DO NOT** omit `TableName()` on new models — GORM pluralizes by default. ## COMMANDS ```bash @@ -75,15 +85,21 @@ docker compose -f docker-compose-v6.yml up -d (cd go-backend && make build) (cd vite-frontend && npm run dev) (cd go-gost && go run .) + +# Testing +(cd go-backend && go test ./...) +(cd go-backend && go test ./tests/contract/...) ``` ## UNIQUE STYLES - **Flat Monorepo**: Language-prefixed dirs (`go-backend`, `go-gost`, `vite-frontend`) instead of `apps/`/`libs/`. - **Asymmetric Go Layout**: `go-backend` follows `cmd//main.go` while `go-gost` uses `root/main.go`. - **Frontend Hybrid Mode**: `App.tsx` detects "H5 mode" (mobile WebView) vs desktop, dictating layout strategy. +- **Experimental Bundler**: `vite-frontend` uses `rolldown-vite` (Rust-based) instead of standard Vite. +- **Non-minified Builds**: `vite.config.ts` sets `minify: false`, `treeshake: false` for debugging. ## NOTES -- LSP servers are not installed in this environment (gopls/jdtls/typescript-language-server); rely on grep-based navigation. +- LSP servers are not installed in this environment (gopls/typescript-language-server); rely on grep-based navigation. - `vite-frontend/vite.config.ts` sets `minify: false` and disables treeshake; expect larger bundles. - `vite-frontend` uses `rolldown-vite` (experimental Rust bundler) instead of standard Vite. - Install scripts (`install.sh`, `panel_install.sh`) self-delete after execution - common pattern in one-liner installs. @@ -91,7 +107,9 @@ docker compose -f docker-compose-v6.yml up -d - CI dynamically injects `PINNED_VERSION` into install scripts and docker-compose files during releases. - `panel_install.sh` auto-detects IPv6 and modifies `/etc/docker/daemon.json` to enable IPv6 bridge. - Download proxy `https://gcode.hostcentral.cc/` used for GitHub downloads in China/restricted environments. -- Backend has contract tests in `go-backend/tests/contract/` - frontend has no test infrastructure (Vitest/Jest not configured). +- Backend has contract tests in `go-backend/tests/contract/` - frontend has no test infrastructure. - `analysis/3x-ui/` contains a separate git repo for reference/comparison - not part of FLVX core. -- PR `#144` (shadcn migration) and PR `#142` (user-group binding) are merged into `main`; release tag `2.1.4-rc2` points to commit `137c34e`. -- Button visual parity relies on `vite-frontend/src/shadcn-bridge/heroui/button.tsx` color mapping + `vite-frontend/src/styles/tailwind-theme.pcss` token export. +- CI workflows: `ci-build.yml` (build check), `docker-build.yml` (multi-arch images + release), `deploy-docs.yml` (MkDocs). +- PostgreSQL migration supported via `panel_install.sh` menu option using pgloader. +- Repository layer is large: `repository.go` (83k LOC), `repository_mutations.go` (43k LOC). +- Button visual parity relies on `vite-frontend/src/shadcn-bridge/heroui/button.tsx` color mapping + `vite-frontend/src/styles/tailwind-theme.pcss` token export. \ No newline at end of file diff --git a/go-backend/AGENTS.md b/go-backend/AGENTS.md index 0a5201c..44975dd 100644 --- a/go-backend/AGENTS.md +++ b/go-backend/AGENTS.md @@ -2,7 +2,7 @@ ## OVERVIEW Go-based Admin API for FLVX. Replaced legacy Spring Boot backend. -**Stack:** Go 1.23, net/http (std lib), GORM + SQLite/PostgreSQL (glebarez/sqlite - CGO-free). +**Stack:** Go 1.24, net/http (std lib), GORM + SQLite/PostgreSQL (glebarez/sqlite - CGO-free). ## STRUCTURE ``` @@ -17,14 +17,15 @@ go-backend/ │ ├── store/ │ │ ├── model/model.go # GORM model structs (single source of truth) │ │ └── repo/ # Data Access Layer (Repository pattern, GORM) -│ │ ├── repository.go # Core queries, Open/OpenPostgres, AutoMigrate -│ │ ├── repository_mutations.go # Mutation helpers (user/node/tunnel/forward CRUD) -│ │ ├── repository_federation.go# Federation-specific queries +│ │ ├── repository.go # Core queries, Open/OpenPostgres, AutoMigrate (83k LOC) +│ │ ├── repository_mutations.go # Mutation helpers (user/node/tunnel/forward CRUD, 43k LOC) +│ │ ├── repository_federation.go # Federation-specific queries │ │ ├── repository_flow.go # Flow/forward status queries -│ │ └── repository_control.go # Control plane queries +│ │ ├── repository_control.go # Control plane queries +│ │ └── repository_groups.go # Group management queries │ └── auth/ # Auth logic -├── tests/ # Integration/Contract tests -├── Dockerfile # Multi-stage build (alpine) +├── tests/contract/ # Integration/contract tests (14 tests) +├── Dockerfile # Multi-stage build (golang:1.24-bookworm → debian:bookworm-slim) └── Makefile # Build commands ``` @@ -36,6 +37,7 @@ go-backend/ | **Repository** | `go-backend/internal/store/repo/` | GORM-based queries, all DB ops encapsulated | | **Auth Middleware** | `go-backend/internal/http/middleware/jwt.go` | Extracts `Authorization` header | | **WebSocket** | `go-backend/internal/ws/` | Real-time updates (traffic, status) | +| **Contract Tests** | `go-backend/tests/contract/` | Integration tests for auth, federation, tunnels | ## CONVENTIONS - **GORM ORM**: Uses GORM with `glebarez/sqlite` (CGO-free) and `gorm.io/driver/postgres`. @@ -47,6 +49,7 @@ go-backend/ - **API Envelope**: All responses use `response.R{code, msg, data, ts}` structure. - **Config**: Loaded from environment variables (see `cmd/paneld/main.go`). - **SQLite Constraints**: `MaxOpenConns(1)`, WAL mode, busy_timeout=5000. +- **PostgreSQL**: Supported via `DB_TYPE=postgres` and `DATABASE_URL` env vars. ## ANTI-PATTERNS - **DO NOT** let handlers call `repo.DB()` directly — add a Repository method instead. @@ -58,6 +61,7 @@ go-backend/ ```bash cd go-backend go run ./cmd/paneld # Default: SERVER_ADDR=:6365 -go test ./... +go test ./... # Unit tests +go test ./tests/contract/... # Contract tests make build ``` diff --git a/go-backend/internal/http/handler/AGENTS.md b/go-backend/internal/http/handler/AGENTS.md index 5d14ed9..0438ab9 100644 --- a/go-backend/internal/http/handler/AGENTS.md +++ b/go-backend/internal/http/handler/AGENTS.md @@ -1,10 +1,10 @@ # BACKEND HTTP HANDLER KNOWLEDGE BASE -**Generated:** Sun Feb 15 2026 +**Generated:** Thu Feb 26 2026 ## OVERVIEW HTTP request handlers for FLVX Admin API. Core business logic layer. -**Stack:** Go 1.23, net/http, GORM via Repository pattern. +**Stack:** Go 1.24, net/http, GORM via Repository pattern. ## STRUCTURE ``` @@ -14,7 +14,7 @@ handler/ ├── federation.go # Federation/cluster sync API ├── flow_policy.go # Traffic policy API ├── jobs.go # Background job management (sync, cleanup) -├── mutations.go # CRUD for users, tunnels, forwards (largest: 100k+ LOC) +├── mutations.go # CRUD for users, tunnels, forwards (~3700 LOC) └── upgrade.go # System upgrade API ``` @@ -26,10 +26,11 @@ handler/ | **Federation Sync** | `federation.go` | Panel-to-panel sync | | **Traffic Policies** | `flow_policy.go` | Flow limiting, quota management | | **Background Jobs** | `jobs.go` | Scheduled sync/cleanup tasks | +| **Node Control** | `control_plane.go` | Node add/delete/list operations | ## CONVENTIONS - Inherits from parent: GORM via Repository pattern, JWT in Authorization header. -- Large files expected (`mutations.go` 3716 LOC - central mutation hub). +- Large files expected (`mutations.go` ~3700 LOC - central mutation hub). - Uses `repo.Repository` for DB access via `h.repo.XXX()` methods. - Handlers never call `repo.DB()` directly — all queries go through Repository methods. - Domain-driven file split: one file per functional area (federation, jobs, etc.). diff --git a/go-gost/AGENTS.md b/go-gost/AGENTS.md index 6d97324..dcf330e 100644 --- a/go-gost/AGENTS.md +++ b/go-gost/AGENTS.md @@ -1,6 +1,6 @@ # GO-GOST SERVICE KNOWLEDGE BASE -**Generated:** Sun Feb 15 2026 +**Generated:** Thu Feb 26 2026 ## OVERVIEW Forwarding agent built on GOST v3 with a local fork of `github.com/go-gost/x` under `x/`. @@ -19,16 +19,18 @@ go-gost/ ## WHERE TO LOOK | Task | Location | Notes | |------|----------|-------| -| Panel integration config | `go-gost/config.go` | Expects `config.json` in cwd by default | -| Service lifecycle/reload | `go-gost/program.go` | Parses config; handles SIGHUP reload | -| WebSocket reporting | `go-gost/main.go` | Starts reporter + sets HTTP report URL | -| Protocol behaviors | `go-gost/x/` | Handlers/listeners/dialers live here | +| **Panel integration config** | `go-gost/config.go` | Expects `config.json` in cwd by default | +| **Service lifecycle/reload** | `go-gost/program.go` | Parses config; handles SIGHUP reload | +| **WebSocket reporting** | `go-gost/main.go` | Starts reporter + sets HTTP report URL | +| **Protocol behaviors** | `go-gost/x/` | Handlers/listeners/dialers live here | +| **Build** | `go-gost/Makefile` | Cross-compile targets for amd64/arm64 | ## CONVENTIONS - Two configs exist: panel integration uses `config.json`; forwarding services use GOST config (defaults to `gost.{json,yaml}` via viper search paths). - `go-gost/x/` is the primary extension surface; avoid editing vendored deps. - Agent communicates with panel via WebSocket (real-time commands) + HTTP (batch traffic reports). - All panel communication uses AES encryption with node `secret` as PSK. +- CI builds with `CGO_ENABLED=0` for static binaries, then compresses with UPX. ## ANTI-PATTERNS - **DO NOT EDIT** generated protobuf in `x/internal/util/grpc/proto/`. diff --git a/go-gost/x/AGENTS.md b/go-gost/x/AGENTS.md index 057ac0b..6d81366 100644 --- a/go-gost/x/AGENTS.md +++ b/go-gost/x/AGENTS.md @@ -6,27 +6,28 @@ Local fork of `github.com/go-gost/x` used by `go-gost/` via `replace github.com/ ## STRUCTURE ``` go-gost/x/ -├── api/ # Gin management API + embedded swagger docs +├── api/ # Gin management API + embedded swagger docs (22 files) ├── config/ # Config model + parsing/load/reload ├── connector/ # Outbound connect implementations -├── dialer/ # Outbound dialers (tcp/tls/ws/quic/...) +├── dialer/ # Outbound dialers (tcp/tls/ws/quic/...) ├── handler/ # Protocol handlers (socks/http/tunnel/relay/...) ├── listener/ # Inbound listeners (tcp/udp/tun/tap/redirect/...) ├── limiter/ # Traffic/rate/conn limiters -├── registry/ # Registries for services/handlers/listeners/etc +├── registry/ # Registries for services/handlers/listeners/etc (20 files) ├── service/ # Service wrappers + reporting hooks -├── socket/ # WebSocket reporter / panel integration +├── socket/ # WebSocket reporter / panel integration (6 files) └── internal/ # Shared internals (grpc proto, net utils, sniffing, tls, ...) ``` ## WHERE TO LOOK | Task | Location | Notes | |------|----------|-------| -| Management API routes/auth | `go-gost/x/api/api.go` | `/docs`, `/config/*`; BasicAuth + interceptor | -| Service config parsing | `go-gost/x/config/parsing/` | Converts config to running services | -| Add a handler | `go-gost/x/handler/` | Per-protocol subdirs | -| Add a listener/dialer | `go-gost/x/listener/`, `go-gost/x/dialer/` | Transport variants | -| Panel reporting | `go-gost/x/socket/` | WebSocket + HTTP report URL hooks | +| **Management API routes/auth** | `go-gost/x/api/api.go` | `/docs`, `/config/*`; BasicAuth + interceptor | +| **Service config parsing** | `go-gost/x/config/parsing/` | Converts config to running services | +| **Add a handler** | `go-gost/x/handler/` | Per-protocol subdirs | +| **Add a listener/dialer** | `go-gost/x/listener/`, `go-gost/x/dialer/` | Transport variants | +| **Panel reporting** | `go-gost/x/socket/` | WebSocket + HTTP report URL hooks | +| **Register new component** | `go-gost/x/registry/` | `Register{Type}(name, creator)` | ## CONVENTIONS - `go-gost/x/` is a standalone Go module (`go-gost/x/go.mod`); run go tooling from this dir when debugging module resolution. @@ -41,4 +42,4 @@ go-gost/x/ ```bash cd go-gost/x go test ./... -``` +``` \ No newline at end of file diff --git a/vite-frontend/AGENTS.md b/vite-frontend/AGENTS.md index 0acc864..7786736 100644 --- a/vite-frontend/AGENTS.md +++ b/vite-frontend/AGENTS.md @@ -1,9 +1,9 @@ # VITE FRONTEND KNOWLEDGE BASE -**Generated:** Thu Feb 19 2026 -**Commit:** 137c34e +**Generated:** Thu Feb 26 2026 +**Commit:** 21008cc **Branch:** main -**Tag:** 2.1.4-rc2 +**Tag:** 2.1.5-rc15 ## OVERVIEW Web management console for FLVX. @@ -15,8 +15,8 @@ vite-frontend/ ├── src/ │ ├── api/ # Axios wrapper + typed endpoint helpers │ ├── components/ui/ # shadcn/radix primitive components -│ ├── shadcn-bridge/heroui/ # HeroUI-compatible facade used by pages/layouts -│ ├── pages/ # Route views + page modules (forward/node/tunnel split helpers) +│ ├── shadcn-bridge/heroui/ # HeroUI-compatible facade (23 components) +│ ├── pages/ # Route views + page modules (forward/node/tunnel) │ ├── hooks/ # H5/WebView/mobile hooks │ ├── styles/ │ │ ├── globals.css # Base styles + imports tailwind-theme.pcss @@ -25,8 +25,8 @@ vite-frontend/ │ ├── main.tsx # ReactDOM + BrowserRouter + Provider │ └── provider.tsx # Toast/theme/provider composition ├── components.json # shadcn/ui config -├── tailwind.config.js # Compatibility config still used by migration scaffolding -├── vite.config.ts # base '/', host 0.0.0.0:3000; build minify/treeshake disabled +├── tailwind.config.js # Compatibility config for migration scaffolding +├── vite.config.ts # base '/', host 0.0.0.0:3000; minify/treeshake disabled └── package.json ``` @@ -47,8 +47,8 @@ vite-frontend/ - **API Envelope**: Responses follow `{code, msg, data, ts}`. - **UI Imports**: Use `src/shadcn-bridge/heroui/*` in app pages/layouts for compatibility. - **Semantic Colors**: Keep `globals.css -> tailwind-theme.pcss` import intact or semantic classes break. -- **Build profile**: `minify: false`, `treeshake: false` for easier debugging. -- **Layout mode**: H5/mobile mode still controlled by existing route/query and hook logic. +- **Build profile**: `minify: false`, `treeshake: false` for debugging. +- **Layout mode**: H5/mobile mode controlled by existing route/query and hook logic. ## ANTI-PATTERNS - **DO NOT ADD** `Bearer` to auth header in frontend requests. @@ -57,10 +57,9 @@ vite-frontend/ - **DO NOT ADD** frontend tests; no Vitest/Jest setup exists. ## NOTES -- PR `#144` (shadcn migration) and PR `#142` (user-group binding) are merged in `main`. -- Release tag `2.1.4-rc2` points to commit `137c34e`. -- Button border/color parity depends on both bridge mapping and semantic Tailwind token export. - Uses `rolldown-vite` (experimental Rust bundler) instead of standard Vite. +- Build outputs are non-minified (debugging mode). +- No test infrastructure exists (Vitest/Jest not configured). ## COMMANDS ```bash