[优化] go 引用调整

2026-09-30 06:16:37 +08:00 · 2026-06-06 10:26:20 +08:00
parent ee1110b752
commit 3cfefb4367
552 changed files with 1642 additions and 2185 deletions
@@ -127,7 +127,7 @@ Manual execution:
 Running from source:

 ```bash
-cd openflare_agent
+cd openflare-agent
 export LOG_LEVEL='info'
 go run ./cmd/agent -config /path/to/agent.json
 ```
@@ -135,7 +135,7 @@ go run ./cmd/agent -config /path/to/agent.json
 Running compiled binary:

 ```bash
-cd openflare_agent
+cd openflare-agent
 go build -o openflare-agent ./cmd/agent
 export LOG_LEVEL='info'
 ./openflare-agent -config /path/to/agent.json
@@ -134,7 +134,7 @@ Access `http://localhost:3000` for the first time, using the default credentials
 First, build the admin frontend:

 ```bash
-cd openflare_server/web
+cd openflare-server/web
 corepack enable
 pnpm install
 pnpm build
@@ -143,7 +143,7 @@ pnpm build
 Then, launch the Server:

 ```bash
-cd openflare_server
+cd openflare-server
 export SESSION_SECRET='replace-with-a-long-random-string'
 export SQLITE_PATH='./openflare.db'
 export LOG_LEVEL='info'
@@ -230,7 +230,7 @@ journalctl -u openflare-agent -f
 Running from source:

 ```bash
-cd openflare_agent
+cd openflare-agent
 export LOG_LEVEL='info'
 go run ./cmd/agent -config /path/to/agent.json
 ```
@@ -238,7 +238,7 @@ go run ./cmd/agent -config /path/to/agent.json
 Running compiled binary:

 ```bash
-cd openflare_agent
+cd openflare-agent
 go build -o openflare-agent ./cmd/agent
 export LOG_LEVEL='info'
 ./openflare-agent -config /path/to/agent.json
@@ -1,6 +1,6 @@
 # Deploy Relay (Tunnel Relay)

-You will learn: The responsibilities of a TunnelRelay node, `openflare_relay` configuration parameters and environment variables, how to run the Relay via Docker, and how to build and deploy the Relay from source manually.
+You will learn: The responsibilities of a TunnelRelay node, `openflare-relay` configuration parameters and environment variables, how to run the Relay via Docker, and how to build and deploy the Relay from source manually.

 In the OpenFlare intranet penetration architecture, the **TunnelRelay node** plays a key role. Unlike standard Edge Nodes, in addition to running the traditional Agent (managing OpenResty for HTTPS/WAF processing), it co-locates the **Relay (frps tunnel manager)** service, responsible for listening to intranet client (OpenFlared) tunnel connections and relaying traffic.

@@ -21,7 +21,7 @@ Before deploying a TunnelRelay node, ensure:

 ## Configuration & Environment Variables

-`openflare_relay` reads `relay.json` in the working directory by default on startup. Overriding options via environment variables is fully supported.
+`openflare-relay` reads `relay.json` in the working directory by default on startup. Overriding options via environment variables is fully supported.

 ### Configuration Fields Details

@@ -68,7 +68,7 @@ If you prefer to run the Relay directly on a physical host or VM:
 ### 1. Compile the Binary

 ```bash
-cd openflare_relay
+cd openflare-relay
 go build -o openflare-relay ./cmd/relay
 ```

@@ -17,10 +17,10 @@ In production environments, we highly recommend explicitly configuring `SESSION_

 ## Build the Admin Frontend

-The Go Server hosts static assets located in `openflare_server/web/build`. Before starting the Server from source, build the frontend:
+The Go Server hosts static assets located in `openflare-server/web/build`. Before starting the Server from source, build the frontend:

 ```bash
-cd openflare_server/web
+cd openflare-server/web
 corepack enable
 pnpm install
 pnpm build
@@ -37,7 +37,7 @@ pnpm test
 ## Start with SQLite

 ```bash
-cd openflare_server
+cd openflare-server
 export SESSION_SECRET='replace-with-a-long-random-string'
 export SQLITE_PATH='./openflare.db'
 export LOG_LEVEL='info'
@@ -53,7 +53,7 @@ http://localhost:3000
 ## Start with PostgreSQL

 ```bash
-cd openflare_server
+cd openflare-server
 export SESSION_SECRET='replace-with-a-long-random-string'
 export DSN='postgres://openflare:secret@127.0.0.1:5432/openflare?sslmode=disable'
 export LOG_LEVEL='info'
@@ -61,19 +61,19 @@ Internal Service (192.168.x.x)

 ## Server

-`openflare_server` is the single-control-plane monolith:
+`openflare-server` is the single-control-plane monolith:

 * Gin provides the HTTP services.
 * GORM accesses SQLite or PostgreSQL.
 * The existing login system provides Admin Session management.
 * Authentication sources support GitHub OAuth and standard OIDC logins with external account binding.
-* The Go Server hosts the `openflare_server/web` static build assets.
+* The Go Server hosts the `openflare-server/web` static build assets.

 The Server does not directly SSH to nodes, nor does it modify node files online. It only stores control plane state, generates complete configuration versions, and lets nodes actively pull them via the Agent API.

 ## Agent

-`openflare_agent` is a Go monolithic application:
+`openflare-agent` is a Go monolithic application:

 * Runs as a single binary on the node side.
 * Reads or generates local node information on startup.
@@ -88,7 +88,7 @@ The node IP is maintained by default through Agent registration and heartbeat re

 ## Frontend

-`openflare_server/web` is the official Next.js-based frontend:
+`openflare-server/web` is the official Next.js-based frontend:

 * Next.js 15 App Router.
 * React 19.
@@ -22,7 +22,7 @@ For details on the physical directory structure and responsibilities of each mod
 ## Initializing Frontend Dependencies

 ```bash
-cd openflare_server/web
+cd openflare-server/web
 corepack enable
 pnpm install
 ```
@@ -38,7 +38,7 @@ pnpm build
 SQLite Mode:

 ```bash
-cd openflare_server
+cd openflare-server
 export SESSION_SECRET='dev-session-secret'
 export SQLITE_PATH='./openflare-dev.db'
 export LOG_LEVEL='debug'
@@ -48,7 +48,7 @@ go run .
 PostgreSQL Mode:

 ```bash
-cd openflare_server
+cd openflare-server
 export SESSION_SECRET='dev-session-secret'
 export DSN='postgres://openflare:secret@127.0.0.1:5432/openflare?sslmode=disable'
 export LOG_LEVEL='debug'
@@ -68,7 +68,7 @@ The default credentials are `root` / `123456`.
 The frontend dev server listens to port `3001` by default and proxies requests to the backend via `NEXT_DEV_BACKEND_URL`:

 ```bash
-cd openflare_server/web
+cd openflare-server/web
 export NEXT_DEV_BACKEND_URL='http://127.0.0.1:3000'
 pnpm dev
 ```
@@ -96,7 +96,7 @@ Create a local `agent.json`:
 Run:

 ```bash
-cd openflare_agent
+cd openflare-agent
 export LOG_LEVEL='debug'
 go run ./cmd/agent -config ./agent.json
 ```
@@ -108,21 +108,21 @@ If `openresty_path` is not configured, the Agent calls `openresty` by default. F
 Server:

 ```bash
-cd openflare_server
+cd openflare-server
 GOCACHE=/tmp/openflare-go-cache go test ./...
 ```

 Agent:

 ```bash
-cd openflare_agent
+cd openflare-agent
 GOCACHE=/tmp/openflare-go-cache go test ./...
 ```

 Frontend:

 ```bash
-cd openflare_server/web
+cd openflare-server/web
 pnpm lint
 pnpm typecheck
 pnpm test
@@ -141,21 +141,21 @@ pnpm build
 Admin static assets:

 ```bash
-cd openflare_server/web
+cd openflare-server/web
 pnpm build
 ```

 Server binary:

 ```bash
-cd openflare_server
+cd openflare-server
 go build -o openflare-server .
 ```

 Agent binary:

 ```bash
-cd openflare_agent
+cd openflare-agent
 go build -o openflare-agent ./cmd/agent
 ```

@@ -4,10 +4,10 @@ You will learn: The responsibilities of Server, Agent, Frontend, scripts, and do

 | Path | Responsibility |
 | --- | --- |
-| `openflare_server` | Gin + GORM + SQLite/PostgreSQL single monolithic control plane |
-| `openflare_server/web` | Next.js 15 App Router Admin Frontend, hosted by Go Server |
-| `openflare_agent` | Go monolithic Agent running on the node side |
-| `openflare_relay` | Tunnel relay daemon running on public edges, managing frps processes |
+| `openflare-server` | Gin + GORM + SQLite/PostgreSQL single monolithic control plane |
+| `openflare-server/web` | Next.js 15 App Router Admin Frontend, hosted by Go Server |
+| `openflare-agent` | Go monolithic Agent running on the node side |
+| `openflare-relay` | Tunnel relay daemon running on public edges, managing frps processes |
 | `openflared` | Tunnel client running on intranet servers, managing frpc processes |
 | `scripts` | System helper scripts for installation, self-updating, etc. |
 | `docs` | VitePress documentation website, design baselines, specifications, and configurations |
@@ -40,7 +40,7 @@ graph TD
    FlaredFrpc -->|Forward Local Request| LocalOrigin[5. Intranet Origin 192.168.x.x]

    %% Control Flow & Heartbeats
-    Server[OpenFlare Server Control Plane] <-->|Relay API / Heartbeat| RelayManager[openflare_relay process]
+    Server[OpenFlare Server Control Plane] <-->|Relay API / Heartbeat| RelayManager[openflare-relay process]
    Server <-->|Client API / Heartbeat| ClientManager[openflared process]

    RelayManager -.->|Control Process & Config| RelayFrps
@@ -51,14 +51,14 @@ graph TD
    style Server fill:#f96,stroke:#333,stroke-width:2px
 ```

-* **Control Plane**: The Server maintains the database state. The `openflare_relay` process on relay nodes and the `openflared` process on intranet servers synchronize tunnel configurations via HTTP heartbeats and long-lived WebSocket connections.
-* **Data Plane**: Public traffic enters the public edge Agent (OpenResty), where the TLS handshake, HTTPS termination, and WAF filtering are executed. It is then forwarded via `proxy_pass` to the co-located `openflare_relay (frps)` on the loopback address. `frps` encapsulates the HTTP requests into the encrypted TCP tunnel and sends them down to the intranet `openflared (frpc)`. Finally, `frpc` unpacks the requests and forwards them to the actual intranet origin service.
+* **Control Plane**: The Server maintains the database state. The `openflare-relay` process on relay nodes and the `openflared` process on intranet servers synchronize tunnel configurations via HTTP heartbeats and long-lived WebSocket connections.
+* **Data Plane**: Public traffic enters the public edge Agent (OpenResty), where the TLS handshake, HTTPS termination, and WAF filtering are executed. It is then forwarded via `proxy_pass` to the co-located `openflare-relay (frps)` on the loopback address. `frps` encapsulates the HTTP requests into the encrypted TCP tunnel and sends them down to the intranet `openflared (frpc)`. Finally, `frpc` unpacks the requests and forwards them to the actual intranet origin service.

 ---

 ## Relay (Server-side) Design

-`openflare_relay` is a relay manager deployed on the public edge, running on nodes of type `tunnel_relay`.
+`openflare-relay` is a relay manager deployed on the public edge, running on nodes of type `tunnel_relay`.

 ### 1. Core Architecture & Logic
 * **Process Daemon**: The Relay process embeds the `frps` binary, spawning the `frps -c frps.toml` subprocess via `exec.Command` and using goroutines to asynchronously listen to its exit status. If `frps` exits unexpectedly, it automatically restarts using an exponential backoff policy.
@@ -98,7 +98,7 @@ Admin modifies tunnel/intranet port mappings -> Click Publish -> Generate new Tu
 +-----------------------------------------------------------------------+-----------------------------------------------------------------------+
 |                                                                                                                                               |
 v (Relay Side)                                                                                                                                  v (Client Side)
-openflare_relay heartbeat detects frps port/Token change                                                                                        openflared heartbeat detects tunnel_version change
+openflare-relay heartbeat detects frps port/Token change                                                                                        openflared heartbeat detects tunnel_version change
 Re-render local frps.toml                                                                                                                       Request full proxy configuration details
 Kill and restart the frps process                                                                                                               Re-render frpc_<relay_id>.toml configs
 Report health status as healthy                                                                                                                 Restart or hot-reload changed frpc processes
@@ -64,7 +64,7 @@ curl -I http://127.0.0.1:3000
 2. If running from source, verify that the frontend static assets have been built:

 ```bash
-cd openflare_server/web
+cd openflare-server/web
 pnpm build
 ```

@@ -73,7 +73,7 @@ pnpm build
 4. If accessing via the frontend dev server, verify the backend proxy configuration:

 ```bash
-cd openflare_server/web
+cd openflare-server/web
 NEXT_DEV_BACKEND_URL=http://127.0.0.1:3000 pnpm dev
 ```

@@ -220,7 +220,7 @@ Domains without a bound certificate will not be added to the HTTPS configuration
 Execute:

 ```bash
-cd openflare_server/web
+cd openflare-server/web
 corepack enable
 pnpm install
 pnpm lint
@@ -152,4 +152,4 @@ Once logged into the management console, the Swagger page is accessible at:
 /swagger/index.html
 ```

-The Swagger definition file is stored in `openflare_server/docs`, generated by `swag init`.
+The Swagger definition file is stored in `openflare-server/docs`, generated by `swag init`.
@@ -7,7 +7,7 @@ You will learn: Common commands for starting, building, testing, installing, and
 Start from source:

 ```bash
-cd openflare_server
+cd openflare-server
 export SESSION_SECRET='replace-with-random-string'
 export SQLITE_PATH='./openflare.db'
 export LOG_LEVEL='info'
@@ -23,7 +23,7 @@ go run . --port 3000 --log-dir ./logs
 Run tests:

 ```bash
-cd openflare_server
+cd openflare-server
 GOCACHE=/tmp/openflare-go-cache go test ./...
 ```

@@ -32,7 +32,7 @@ GOCACHE=/tmp/openflare-go-cache go test ./...
 Development:

 ```bash
-cd openflare_server/web
+cd openflare-server/web
 pnpm install
 pnpm dev
 ```
@@ -40,14 +40,14 @@ pnpm dev
 Build static assets:

 ```bash
-cd openflare_server/web
+cd openflare-server/web
 pnpm build
 ```

 Linting and testing checks:

 ```bash
-cd openflare_server/web
+cd openflare-server/web
 pnpm lint
 pnpm typecheck
 pnpm test
@@ -58,21 +58,21 @@ pnpm test
 Run from source:

 ```bash
-cd openflare_agent
+cd openflare-agent
 go run ./cmd/agent -config /path/to/agent.json
 ```

 Compile:

 ```bash
-cd openflare_agent
+cd openflare-agent
 go build -o openflare-agent ./cmd/agent
 ```

 Run tests:

 ```bash
-cd openflare_agent
+cd openflare-agent
 GOCACHE=/tmp/openflare-go-cache go test ./...
 ```

@@ -81,14 +81,14 @@ GOCACHE=/tmp/openflare-go-cache go test ./...
 Run from source:

 ```bash
-cd openflare_relay
+cd openflare-relay
 go run ./cmd -config /path/to/relay.json
 ```

 Compile:

 ```bash
-cd openflare_relay
+cd openflare-relay
 go build -o openflare-relay ./cmd
 ```

@@ -128,7 +128,7 @@ Regenerate Swagger documentation:

 ```bash
 go install github.com/swaggo/swag/cmd/swag@v1.16.4
-cd openflare_server
+cd openflare-server
 swag init -g main.go -o docs
 ```

@@ -46,7 +46,7 @@ The Client (Intranet Client) supports:
 ## Server CLI Arguments

 ```bash
-cd openflare_server
+cd openflare-server
 go run . --port 3000 --log-dir ./logs
 ```