├── cmd └── nodepass │ ├── main.go │ └── core.go ├── Dockerfile ├── .goreleaser.yml ├── go.mod ├── .github ├── workflows │ ├── release.yml │ └── docker.yml └── copilot-instructions.md ├── LICENSE ├── CODE_OF_CONDUCT.md ├── docs ├── zh │ ├── installation.md │ ├── usage.md │ ├── troubleshooting.md │ ├── how-it-works.md │ ├── examples.md │ └── configuration.md └── en │ ├── installation.md │ ├── usage.md │ └── troubleshooting.md ├── go.sum ├── README_zh.md ├── SECURITY.md ├── README.md ├── internal ├── server.go └── client.go └── CONTRIBUTING.md /cmd/nodepass/main.go: -------------------------------------------------------------------------------- 1 | package main 2 | 3 | import "os" 4 | 5 | var version = "dev" 6 | 7 | func main() { 8 | if err := start(os.Args); err != nil { 9 | exit(err) 10 | } 11 | } 12 | -------------------------------------------------------------------------------- /Dockerfile: -------------------------------------------------------------------------------- 1 | FROM golang:alpine AS builder 2 | RUN apk update && apk add --no-cache ca-certificates 3 | WORKDIR /root 4 | ADD . . 5 | ARG VERSION 6 | WORKDIR /root/cmd/nodepass 7 | RUN env CGO_ENABLED=0 go build -v -trimpath -ldflags "-s -w -X main.version=${VERSION}" 8 | FROM scratch 9 | COPY --from=builder /etc/ssl/certs /etc/ssl/certs 10 | COPY --from=builder /root/cmd/nodepass/nodepass /nodepass 11 | ENTRYPOINT ["/nodepass"] 12 | -------------------------------------------------------------------------------- /.goreleaser.yml: -------------------------------------------------------------------------------- 1 | version: 2 2 | 3 | builds: 4 | - env: 5 | - CGO_ENABLED=0 6 | main: ./cmd/nodepass 7 | goos: 8 | - darwin 9 | - freebsd 10 | - linux 11 | - windows 12 | goarch: 13 | - 386 14 | - arm 15 | - amd64 16 | - arm64 17 | - mips 18 | - mipsle 19 | - mips64 20 | - mips64le 21 | goarm: 22 | - 6 23 | - 7 24 | gomips: 25 | - hardfloat 26 | - softfloat 27 | flags: 28 | - -trimpath 29 | ldflags: 30 | - -s -w -X main.version={{ .Tag }} 31 | 32 | archives: 33 | - formats: [tar.gz] 34 | release: 35 | prerelease: true 36 | mode: replace 37 | -------------------------------------------------------------------------------- /go.mod: -------------------------------------------------------------------------------- 1 | module github.com/yosebyte/nodepass 2 | 3 | go 1.25.0 4 | 5 | require ( 6 | github.com/NodePassProject/cert v1.0.1 7 | github.com/NodePassProject/conn v1.0.16 8 | github.com/NodePassProject/logs v1.0.3 9 | github.com/NodePassProject/nph2 v1.0.4 10 | github.com/NodePassProject/npws v1.0.5 11 | github.com/NodePassProject/pool v1.0.50 12 | github.com/NodePassProject/quic v1.0.14 13 | ) 14 | 15 | require ( 16 | github.com/coder/websocket v1.8.14 // indirect 17 | github.com/quic-go/quic-go v0.57.1 // indirect 18 | golang.org/x/crypto v0.46.0 // indirect 19 | golang.org/x/net v0.48.0 // indirect 20 | golang.org/x/sys v0.39.0 // indirect 21 | golang.org/x/text v0.32.0 // indirect 22 | ) 23 | -------------------------------------------------------------------------------- /.github/workflows/release.yml: -------------------------------------------------------------------------------- 1 | name: Release 2 | 3 | on: 4 | push: 5 | tags: [ 'v*.*.*' ] 6 | 7 | jobs: 8 | goreleaser: 9 | runs-on: ubuntu-latest 10 | steps: 11 | - name: Checkout 12 | uses: actions/checkout@v5.0.1 13 | with: 14 | fetch-depth: 0 15 | - name: Set up Go 16 | uses: actions/setup-go@v6.1.0 17 | with: 18 | go-version: '1.25.0' 19 | - name: Run GoReleaser 20 | uses: goreleaser/goreleaser-action@v6.4.0 21 | with: 22 | distribution: goreleaser 23 | version: 'latest' 24 | args: release --clean 25 | env: 26 | GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} 27 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | BSD 3-Clause License 2 | 3 | Copyright (c) 2025, 𝐘𝐨𝐬𝐞𝐛𝐲𝐭𝐞 4 | 5 | Redistribution and use in source and binary forms, with or without 6 | modification, are permitted provided that the following conditions are met: 7 | 8 | 1. Redistributions of source code must retain the above copyright notice, this 9 | list of conditions and the following disclaimer. 10 | 11 | 2. Redistributions in binary form must reproduce the above copyright notice, 12 | this list of conditions and the following disclaimer in the documentation 13 | and/or other materials provided with the distribution. 14 | 15 | 3. Neither the name of the copyright holder nor the names of its 16 | contributors may be used to endorse or promote products derived from 17 | this software without specific prior written permission. 18 | 19 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 20 | AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21 | IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 22 | DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE 23 | FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24 | DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 25 | SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 26 | CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 27 | OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 28 | OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -------------------------------------------------------------------------------- /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Code of Conduct 2 | 3 | ## Our Pledge 4 | 5 | We are committed to providing a friendly, safe and welcoming environment for all, regardless of age, disability, ethnicity, gender identity, level of experience, nationality, personal appearance, race, religion, or sexual orientation. 6 | 7 | ## Our Standards 8 | 9 | **Positive behaviors include:** 10 | 11 | - Using welcoming and inclusive language 12 | - Being respectful of differing viewpoints and experiences 13 | - Gracefully accepting constructive criticism 14 | - Focusing on what is best for the community 15 | - Showing empathy towards other community members 16 | 17 | **Unacceptable behaviors include:** 18 | 19 | - Harassment, trolling, or discriminatory comments 20 | - Personal attacks or insulting/derogatory language 21 | - Publishing others' private information without permission 22 | - Any conduct that could reasonably be considered inappropriate in a professional setting 23 | 24 | ## Enforcement 25 | 26 | Project maintainers are responsible for clarifying standards and may take appropriate corrective action in response to unacceptable behavior, including: 27 | 28 | - Warning the individual 29 | - Temporary restriction from project spaces 30 | - Permanent ban from the project community 31 | 32 | ## Scope 33 | 34 | This Code of Conduct applies to all project spaces, including GitHub repositories, issue trackers, social media accounts, and any events where individuals represent the project. 35 | 36 | ## Reporting 37 | 38 | If you experience or witness unacceptable behavior, please report it to **team@mail.nodepass.eu**. All reports will be handled confidentially. 39 | 40 | ## Attribution 41 | 42 | This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1. 43 | -------------------------------------------------------------------------------- /.github/workflows/docker.yml: -------------------------------------------------------------------------------- 1 | name: Docker 2 | 3 | on: 4 | push: 5 | tags: [ 'v*.*.*' ] 6 | 7 | env: 8 | REGISTRY: ghcr.io 9 | IMAGE_NAME: ${{ github.repository }} 10 | VERSION: ${{ github.ref_name }} 11 | 12 | jobs: 13 | build: 14 | runs-on: ubuntu-latest 15 | permissions: 16 | contents: read 17 | packages: write 18 | id-token: write 19 | 20 | steps: 21 | - name: Checkout repository 22 | uses: actions/checkout@v5.0.1 23 | 24 | - name: Install cosign 25 | if: github.event_name != 'pull_request' 26 | uses: sigstore/cosign-installer@v4.0.0 27 | 28 | - name: Set up Docker Buildx 29 | uses: docker/setup-buildx-action@v3.11.1 30 | 31 | - name: Log into registry ${{ env.REGISTRY }} 32 | if: github.event_name != 'pull_request' 33 | uses: docker/login-action@v3.6.0 34 | with: 35 | registry: ${{ env.REGISTRY }} 36 | username: ${{ github.actor }} 37 | password: ${{ secrets.GITHUB_TOKEN }} 38 | 39 | - name: Extract Docker metadata 40 | id: meta 41 | uses: docker/metadata-action@v5.9.0 42 | with: 43 | images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }} 44 | 45 | - name: Build and push Docker image 46 | id: build-and-push 47 | uses: docker/build-push-action@v6.18.0 48 | with: 49 | context: . 50 | push: ${{ github.event_name != 'pull_request' }} 51 | tags: ${{ steps.meta.outputs.tags }} 52 | labels: ${{ steps.meta.outputs.labels }} 53 | cache-from: type=gha 54 | cache-to: type=gha,mode=max 55 | platforms: linux/amd64,linux/arm64 56 | build-args: VERSION=${{ env.VERSION }} 57 | provenance: false 58 | 59 | - name: Sign the published Docker image 60 | if: ${{ github.event_name != 'pull_request' }} 61 | env: 62 | TAGS: ${{ steps.meta.outputs.tags }} 63 | DIGEST: ${{ steps.build-and-push.outputs.digest }} 64 | run: echo ${{ steps.meta.outputs.tags }} | tr ',' '\n' | xargs -I {} cosign sign --yes {}@${DIGEST} 65 | -------------------------------------------------------------------------------- /docs/zh/installation.md: -------------------------------------------------------------------------------- 1 | # 安装指南 2 | 3 | 本指南提供了使用不同方法安装 NodePass 的详细说明。选择最适合您环境和需求的安装方式。 4 | 5 | ## 系统要求 6 | 7 | - Go 1.25或更高版本(从源代码构建时需要) 8 | - 服务器和客户端端点之间的网络连接 9 | - 绑定1024以下端口可能需要管理员权限 10 | 11 | ## 安装方法 12 | 13 | ### 方式1：预编译二进制文件 14 | 15 | 开始使用 NodePass 的最简单方法是为您的平台下载预编译的二进制文件。 16 | 17 | 1. 访问 GitHub 上的[发布页面](https://github.com/yosebyte/nodepass/releases) 18 | 2. 下载适合您操作系统的二进制文件(Windows、macOS、Linux) 19 | 3. 如有必要，解压缩档案 20 | 4. 使二进制文件可执行(Linux/macOS)： 21 | ```bash 22 | chmod +x nodepass 23 | ``` 24 | 5. 将二进制文件移动到PATH中的位置： 25 | - Linux/macOS：`sudo mv nodepass /usr/local/bin/` 26 | - Windows：将位置添加到PATH环境变量 27 | 28 | ### 方式2：使用Go安装 29 | 30 | 如果您的系统上已安装Go，可以使用`go install`命令： 31 | 32 | ```bash 33 | go install github.com/yosebyte/nodepass/cmd/nodepass@latest 34 | ``` 35 | 36 | 此命令下载源代码，编译它，并将二进制文件安装到您的Go bin目录中(通常是`$GOPATH/bin`)。 37 | 38 | ### 方式3：从源代码构建 39 | 40 | 对于最新的开发版本或自定义构建： 41 | 42 | ```bash 43 | # 克隆仓库 44 | git clone https://github.com/yosebyte/nodepass.git 45 | 46 | # 导航到项目目录 47 | cd nodepass 48 | 49 | # 构建二进制文件 50 | go build -o nodepass ./cmd/nodepass 51 | 52 | # 可选：安装到GOPATH/bin 53 | go install ./cmd/nodepass 54 | ``` 55 | 56 | ### 方式4：使用容器镜像 57 | 58 | NodePass在GitHub容器注册表中提供容器镜像，非常适合容器化环境： 59 | 60 | ```bash 61 | # 拉取容器镜像 62 | docker pull ghcr.io/yosebyte/nodepass:latest 63 | 64 | # 服务器模式运行 65 | docker run -d --name nodepass-server -p 10101:10101 -p 8080:8080 \ 66 | ghcr.io/yosebyte/nodepass server://0.0.0.0:10101/0.0.0.0:8080 67 | 68 | # 客户端模式运行 69 | docker run -d --name nodepass-client \ 70 | -e NP_MIN_POOL_INTERVAL=200ms \ 71 | -e NP_SEMAPHORE_LIMIT=512 \ 72 | -p 8080:8080 \ 73 | ghcr.io/yosebyte/nodepass "client://nodepass-server:10101/127.0.0.1:8080?min=32&max=512" 74 | ``` 75 | 76 | ### 方式5：使用管理脚本(仅限Linux) 77 | 78 | 对于Linux系统，我们提供了一键脚本： 79 | 80 | ```bash 81 | bash <(curl -sSL https://run.nodepass.eu/np.sh) 82 | ``` 83 | 84 | - 本脚本提供了简单易用的 master 模式，即 API 模式的安装、配置和管理功能。 85 | - 详情请参阅[https://github.com/NodePassProject/npsh](https://github.com/NodePassProject/npsh) 86 | 87 | ## 验证安装 88 | 89 | 安装后，通过检查版本来验证NodePass是否正确安装： 90 | 91 | ```bash 92 | nodepass 93 | ``` 94 | 95 | ## 下一步 96 | 97 | 安装NodePass后，您可以： 98 | 99 | - 了解基本[使用方法](/docs/zh/usage.md) 100 | - 探索[配置选项](/docs/zh/configuration.md) 101 | - 尝试一些[使用示例](/docs/zh/examples.md) 102 | 103 | ## 安装问题故障排除 104 | 105 | 如果在安装过程中遇到任何问题： 106 | 107 | - 确保您的系统满足最低要求 108 | - 检查是否具有安装软件的正确权限 109 | - 对于Go相关问题，使用`go version`验证您的Go安装 110 | - 对于容器相关问题，确保Docker正确安装并运行 111 | - 查看我们的[故障排除指南](/docs/zh/troubleshooting.md)获取更多帮助 -------------------------------------------------------------------------------- /go.sum: -------------------------------------------------------------------------------- 1 | github.com/NodePassProject/cert v1.0.1 h1:BDy2tTOudy6yk7hvcmScAJMw4NrpCdSCsbuu7hHsIuw= 2 | github.com/NodePassProject/cert v1.0.1/go.mod h1:wP7joOJeQAIlIuOUmhHPwMExjuwGa4XApMWQYChGSrk= 3 | github.com/NodePassProject/conn v1.0.16 h1:ojHfyBveZMcyOikdUs1SOW4yKp92NOBnNhfNenLYljc= 4 | github.com/NodePassProject/conn v1.0.16/go.mod h1:xfQ7ZLUxrtdLsljGHYYCToW+Hdg6DAbmL1Cs94n5h6E= 5 | github.com/NodePassProject/logs v1.0.3 h1:CDUZVQ477vmmFQHazrQCWM0gJPNINm0C2N3FzC4jVyw= 6 | github.com/NodePassProject/logs v1.0.3/go.mod h1:TwtPXOzLtb8iH+fdduQjEEywICXivsM39cy9AinMSks= 7 | github.com/NodePassProject/nph2 v1.0.4 h1:szvp7hlvMRt1g/g1hF++0DfgM++5yqWWAPlfMDh226c= 8 | github.com/NodePassProject/nph2 v1.0.4/go.mod h1:fzNbTk0zh+0gXer2aKpPXF69o4/BOd15Ys2gvicwWR0= 9 | github.com/NodePassProject/npws v1.0.5 h1:UpVm4UYytNQHq6Nkli4Qqq17wpuwvKqoCY571+vubBA= 10 | github.com/NodePassProject/npws v1.0.5/go.mod h1:cyVS2X3/8f07yOkVEl53D+ozHLljJvHQx/s6xoLl/s8= 11 | github.com/NodePassProject/pool v1.0.50 h1:Xmvb0hSHq24U06moHICr8CkqEHB4ZHBbY9Z+a7fSejQ= 12 | github.com/NodePassProject/pool v1.0.50/go.mod h1:joQFk1oocg56QpJ1QK/2g5Jv/AyqYUQgPXMG1gWe8iA= 13 | github.com/NodePassProject/quic v1.0.14 h1:zx5/cmQ8Tp1ntwCVAmtosODfBWTXTHHuprZdAspSjc8= 14 | github.com/NodePassProject/quic v1.0.14/go.mod h1:JEHezuTn+AWN5NURNl2efa5lVqG6VQeutTBKhf9Y0T8= 15 | github.com/coder/websocket v1.8.14 h1:9L0p0iKiNOibykf283eHkKUHHrpG7f65OE3BhhO7v9g= 16 | github.com/coder/websocket v1.8.14/go.mod h1:NX3SzP+inril6yawo5CQXx8+fk145lPDC6pumgx0mVg= 17 | github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c= 18 | github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= 19 | github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM= 20 | github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= 21 | github.com/quic-go/quic-go v0.57.1 h1:25KAAR9QR8KZrCZRThWMKVAwGoiHIrNbT72ULHTuI10= 22 | github.com/quic-go/quic-go v0.57.1/go.mod h1:ly4QBAjHA2VhdnxhojRsCUOeJwKYg+taDlos92xb1+s= 23 | github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U= 24 | github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U= 25 | go.uber.org/mock v0.5.2 h1:LbtPTcP8A5k9WPXj54PPPbjcI4Y6lhyOZXn+VS7wNko= 26 | go.uber.org/mock v0.5.2/go.mod h1:wLlUxC2vVTPTaE3UD51E0BGOAElKrILxhVSDYQLld5o= 27 | golang.org/x/crypto v0.46.0 h1:cKRW/pmt1pKAfetfu+RCEvjvZkA9RimPbh7bhFjGVBU= 28 | golang.org/x/crypto v0.46.0/go.mod h1:Evb/oLKmMraqjZ2iQTwDwvCtJkczlDuTmdJXoZVzqU0= 29 | golang.org/x/net v0.48.0 h1:zyQRTTrjc33Lhh0fBgT/H3oZq9WuvRR5gPC70xpDiQU= 30 | golang.org/x/net v0.48.0/go.mod h1:+ndRgGjkh8FGtu1w1FGbEC31if4VrNVMuKTgcAAnQRY= 31 | golang.org/x/sys v0.39.0 h1:CvCKL8MeisomCi6qNZ+wbb0DN9E5AATixKsvNtMoMFk= 32 | golang.org/x/sys v0.39.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks= 33 | golang.org/x/text v0.32.0 h1:ZD01bjUt1FQ9WJ0ClOL5vxgxOI/sVCNgX1YtKwcY0mU= 34 | golang.org/x/text v0.32.0/go.mod h1:o/rUWzghvpD5TXrTIBuJU77MTaN0ljMWE47kxGJQ7jY= 35 | golang.org/x/time v0.12.0 h1:ScB/8o8olJvc+CQPWrK3fPZNfh7qgwCrY0zJmoEQLSE= 36 | golang.org/x/time v0.12.0/go.mod h1:CDIdPxbZBQxdj6cxyCIdrNogrJKMJ7pr37NYpMcMDSg= 37 | gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA= 38 | gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= 39 | -------------------------------------------------------------------------------- /docs/en/installation.md: -------------------------------------------------------------------------------- 1 | # Installation Guide 2 | 3 | This guide provides detailed instructions for installing NodePass using different methods. Choose the option that best suits your environment and requirements. 4 | 5 | ## System Requirements 6 | 7 | - Go 1.25 or higher (for building from source) 8 | - Network connectivity between server and client endpoints 9 | - Admin privileges may be required for binding to ports below 1024 10 | 11 | ## Installation Options 12 | 13 | ### Option 1: Pre-built Binaries 14 | 15 | The easiest way to get started with NodePass is to download a pre-built binary for your platform. 16 | 17 | 1. Visit the [releases page](https://github.com/yosebyte/nodepass/releases) on GitHub 18 | 2. Download the appropriate binary for your operating system (Windows, macOS, Linux) 19 | 3. Extract the archive if necessary 20 | 4. Make the binary executable (Linux/macOS): 21 | ```bash 22 | chmod +x nodepass 23 | ``` 24 | 5. Move the binary to a location in your PATH: 25 | - Linux/macOS: `sudo mv nodepass /usr/local/bin/` 26 | - Windows: Add the location to your PATH environment variable 27 | 28 | ### Option 2: Using Go Install 29 | 30 | If you have Go installed on your system, you can use the `go install` command: 31 | 32 | ```bash 33 | go install github.com/yosebyte/nodepass/cmd/nodepass@latest 34 | ``` 35 | 36 | This command downloads the source code, compiles it, and installs the binary in your Go bin directory (usually `$GOPATH/bin`). 37 | 38 | ### Option 3: Building from Source 39 | 40 | For the latest development version or to customize the build: 41 | 42 | ```bash 43 | # Clone the repository 44 | git clone https://github.com/yosebyte/nodepass.git 45 | 46 | # Navigate to the project directory 47 | cd nodepass 48 | 49 | # Build the binary 50 | go build -o nodepass ./cmd/nodepass 51 | 52 | # Optional: Install to your GOPATH/bin 53 | go install ./cmd/nodepass 54 | ``` 55 | 56 | ### Option 4: Using Container Image 57 | 58 | NodePass is available as a container image on GitHub Container Registry, perfect for containerized environments: 59 | 60 | ```bash 61 | # Pull the container image 62 | docker pull ghcr.io/yosebyte/nodepass:latest 63 | 64 | # Run in server mode 65 | docker run -d --name nodepass-server -p 10101:10101 -p 8080:8080 \ 66 | ghcr.io/yosebyte/nodepass server://0.0.0.0:10101/0.0.0.0:8080 67 | 68 | # Run in client mode 69 | docker run -d --name nodepass-client \ 70 | -e NP_MIN_POOL_INTERVAL=200ms \ 71 | -e NP_SEMAPHORE_LIMIT=512 \ 72 | -p 8080:8080 \ 73 | ghcr.io/yosebyte/nodepass "client://nodepass-server:10101/127.0.0.1:8080?min=32&max=512" 74 | ``` 75 | 76 | ### Option 5: Using Management Script (Linux Only) 77 | 78 | For Linux systems, we provide a one-click script: 79 | 80 | ```bash 81 | bash <(curl -sSL https://run.nodepass.eu/np.sh) 82 | ``` 83 | 84 | - This script provides easy-to-use master mode (API mode) installation, configuration, and management functions. 85 | - For details, please refer to [https://github.com/NodePassProject/npsh](https://github.com/NodePassProject/npsh) 86 | 87 | ## Verifying Installation 88 | 89 | After installation, verify that NodePass is correctly installed by checking the version: 90 | 91 | ```bash 92 | nodepass 93 | ``` 94 | 95 | ## Next Steps 96 | 97 | Now that you have NodePass installed, you can: 98 | 99 | - Learn about its basic [usage](/docs/en/usage.md) 100 | - Explore [configuration options](/docs/en/configuration.md) 101 | - Try out some [examples](/docs/en/examples.md) 102 | 103 | ## Troubleshooting Installation Issues 104 | 105 | If you encounter any issues during installation: 106 | 107 | - Ensure your system meets the minimum requirements 108 | - Check that you have the correct permissions to install software 109 | - For Go-related issues, verify your Go installation with `go version` 110 | - For container-related issues, ensure Docker is properly installed and running 111 | - See our [troubleshooting guide](/docs/en/troubleshooting.md) for more help -------------------------------------------------------------------------------- /cmd/nodepass/core.go: -------------------------------------------------------------------------------- 1 | package main 2 | 3 | import ( 4 | "crypto/tls" 5 | "fmt" 6 | "net/url" 7 | "os" 8 | "runtime" 9 | "time" 10 | 11 | "github.com/NodePassProject/cert" 12 | "github.com/NodePassProject/logs" 13 | "github.com/yosebyte/nodepass/internal" 14 | ) 15 | 16 | // start 启动核心逻辑 17 | func start(args []string) error { 18 | if len(args) != 2 { 19 | return fmt.Errorf("start: empty URL command") 20 | } 21 | 22 | parsedURL, err := url.Parse(args[1]) 23 | if err != nil { 24 | return fmt.Errorf("start: parse URL failed: %w", err) 25 | } 26 | 27 | logger := initLogger(parsedURL.Query().Get("log")) 28 | 29 | core, err := createCore(parsedURL, logger) 30 | if err != nil { 31 | return fmt.Errorf("start: create core failed: %w", err) 32 | } 33 | 34 | core.Run() 35 | return nil 36 | } 37 | 38 | // initLogger 初始化日志记录器 39 | func initLogger(level string) *logs.Logger { 40 | logger := logs.NewLogger(logs.Info, true) 41 | switch level { 42 | case "none": 43 | logger.SetLogLevel(logs.None) 44 | case "debug": 45 | logger.SetLogLevel(logs.Debug) 46 | logger.Debug("Init log level: DEBUG") 47 | case "warn": 48 | logger.SetLogLevel(logs.Warn) 49 | logger.Warn("Init log level: WARN") 50 | case "error": 51 | logger.SetLogLevel(logs.Error) 52 | logger.Error("Init log level: ERROR") 53 | case "event": 54 | logger.SetLogLevel(logs.Event) 55 | logger.Event("Init log level: EVENT") 56 | default: 57 | } 58 | return logger 59 | } 60 | 61 | // createCore 创建核心 62 | func createCore(parsedURL *url.URL, logger *logs.Logger) (interface{ Run() }, error) { 63 | switch parsedURL.Scheme { 64 | case "server": 65 | tlsCode, tlsConfig := getTLSProtocol(parsedURL, logger) 66 | return internal.NewServer(parsedURL, tlsCode, tlsConfig, logger) 67 | case "client": 68 | return internal.NewClient(parsedURL, logger) 69 | case "master": 70 | tlsCode, tlsConfig := getTLSProtocol(parsedURL, logger) 71 | return internal.NewMaster(parsedURL, tlsCode, tlsConfig, logger, version) 72 | default: 73 | return nil, fmt.Errorf("createCore: unknown core: %v", parsedURL) 74 | } 75 | } 76 | 77 | // getTLSProtocol 获取TLS配置 78 | func getTLSProtocol(parsedURL *url.URL, logger *logs.Logger) (string, *tls.Config) { 79 | // 生成基本TLS配置 80 | tlsConfig, err := cert.NewTLSConfig(version) 81 | if err != nil { 82 | logger.Error("Generate TLS config failed: %v", err) 83 | logger.Warn("TLS code-0: nil cert") 84 | return "0", nil 85 | } 86 | 87 | tlsConfig.MinVersion = tls.VersionTLS13 88 | 89 | switch parsedURL.Query().Get("tls") { 90 | case "1": 91 | // 使用内存自签证书 92 | logger.Info("TLS code-1: RAM cert with TLS 1.3") 93 | return "1", tlsConfig 94 | case "2": 95 | // 使用自定义证书 96 | crtFile, keyFile := parsedURL.Query().Get("crt"), parsedURL.Query().Get("key") 97 | cert, err := tls.LoadX509KeyPair(crtFile, keyFile) 98 | if err != nil { 99 | logger.Error("Certificate load failed: %v", err) 100 | logger.Warn("TLS code-1: RAM cert with TLS 1.3") 101 | return "1", tlsConfig 102 | } 103 | 104 | // 缓存证书并设置自动重载 105 | cachedCert := cert 106 | lastReload := time.Now() 107 | tlsConfig = &tls.Config{ 108 | MinVersion: tls.VersionTLS13, 109 | GetCertificate: func(clientHello *tls.ClientHelloInfo) (*tls.Certificate, error) { 110 | // 定期重载证书 111 | if time.Since(lastReload) >= internal.ReloadInterval { 112 | newCert, err := tls.LoadX509KeyPair(crtFile, keyFile) 113 | if err != nil { 114 | logger.Error("Certificate reload failed: %v", err) 115 | } else { 116 | logger.Debug("TLS cert reloaded: %v", crtFile) 117 | cachedCert = newCert 118 | } 119 | lastReload = time.Now() 120 | } 121 | return &cachedCert, nil 122 | }, 123 | } 124 | 125 | if cert.Leaf != nil { 126 | logger.Info("TLS code-2: %v with TLS 1.3", cert.Leaf.Subject.CommonName) 127 | } else { 128 | logger.Warn("TLS code-2: unknown cert name with TLS 1.3") 129 | } 130 | return "2", tlsConfig 131 | default: 132 | if poolType := parsedURL.Query().Get("type"); poolType == "1" || poolType == "3" { 133 | // 流池类型不支持明文传输 134 | logger.Info("TLS code-1: RAM cert with TLS 1.3 for stream pool") 135 | return "1", tlsConfig 136 | } 137 | // 不使用加密 138 | logger.Warn("TLS code-0: unencrypted") 139 | return "0", nil 140 | } 141 | } 142 | 143 | // exit 退出程序并显示帮助信息 144 | func exit(err error) { 145 | if err != nil { 146 | fmt.Fprintf(os.Stderr, "Error: %v [%d]\n", err, os.Getpid()) 147 | } 148 | fmt.Printf(` 149 | ╭─────────────────────────────────────╮ 150 | │%*s │ 151 | │%*s │ 152 | ├─────────────────────────────────────┤ 153 | │ server://password@host/host? │ 154 | │ client://password@host/host? │ 155 | │ master://hostname:port/path? │ 156 | ╰─────────────────────────────────────╯ 157 | 158 | `, 36, fmt.Sprintf("nodepass-%s", version), 36, fmt.Sprintf("%s/%s", runtime.GOOS, runtime.GOARCH)) 159 | os.Exit(1) 160 | } 161 | -------------------------------------------------------------------------------- /README_zh.md: -------------------------------------------------------------------------------- 1 |
2 | nodepass 3 | 4 | [![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go#networking) 5 | [![GitHub release](https://img.shields.io/github/v/release/yosebyte/nodepass)](https://github.com/yosebyte/nodepass/releases) 6 | [![GitHub downloads](https://img.shields.io/github/downloads/yosebyte/nodepass/total.svg)](https://github.com/yosebyte/nodepass/releases) 7 | [![Go Report Card](https://goreportcard.com/badge/github.com/yosebyte/nodepass)](https://goreportcard.com/report/github.com/yosebyte/nodepass) 8 | [![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause) 9 | [![Go Reference](https://pkg.go.dev/badge/github.com/yosebyte/nodepass.svg)](https://pkg.go.dev/github.com/yosebyte/nodepass) 10 | [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/yosebyte/nodepass) 11 | ![GitHub last commit](https://img.shields.io/github/last-commit/yosebyte/nodepass) 12 | 13 | 14 | 15 | [English](README.md) | 简体中文 16 |
17 | 18 | **NodePass** 是一款开源、轻量的企业级 TCP/UDP 网络隧道解决方案，采用多合一架构设计，通过控制通道与数据通道分离，实现灵活、高性能的实例管控。支持零配置文件部署，内置智能连接池、分级 TLS 加密和无缝协议转换。专为 DevOps 工程师和系统管理员打造，助力轻松应对复杂网络场景。 19 | 20 | ## 💎 核心功能 21 | 22 | - **🌐 通用网络隧道** 23 | - 基础 TCP/UDP 隧道，具备协议转换能力，适配多种网络结构。 24 | - 完整适配端口映射、内网穿透、流量中转等多场景应用需求。 25 | - 多平台、多架构支持，支持独立二进制文件、容器灵活部署。 26 | 27 | - **🚀 内置连接池** 28 | - 提供 TCP、QUIC、WebSocket、HTTP/2 多种池化传输方式。 29 | - 消除连接的握手等待，通过 0-RTT 支持显著提升性能体验。 30 | - 支持实时容量自适应，动态调整连接池规模。 31 | 32 | - **🧬 创新架构设计** 33 | - Server-Client-Master 多模式整合架构设计，灵活切换。 34 | - 将 S/C 控制通道与数据通道完全解耦，相互独立、各司其职。 35 | - 主控-实例的管理方式，支持动态扩容、多实例协作和集中控制。 36 | 37 | - **🔐 多级安全策略** 38 | - 三种 TLS 模式：明文、自签名、严格验证，适配不同安全等级。 39 | - 满足从开发测试到企业级高安全部署的全场景需求。 40 | - 支持证书文件的热重载，免停运、无缝处理证书更新问题。 41 | 42 | - **⚙️ 极简配置方式** 43 | - 无需配置文件，仅命令行参数即可运行，适合自动化和快速迭代。 44 | - 适配 CI/CD 流程与容器环境，极大提升部署和运维效率。 45 | - 支持超时、限速等高级参数调优，灵活适应不同运行环境。 46 | 47 | - **📈 高性能优化** 48 | - 智能流量调度与自动连接调优，极低资源占用。 49 | - 高并发、高负载状态下卓越的系统稳定性能。 50 | - 负载均衡、健康检查、故障自愈，确保持续高可用。 51 | 52 | - **💡 可视化管理** 53 | - 配套跨平台、多样化的管理前端应用，具备可视化配置能力。 54 | - 主流平台支持一键部署脚本，支撑灵活配置和辅助管理。 55 | - 具备实时隧道监控、实例管理、主控管理、流量统计等丰富功能。 56 | 57 | ## 📋 快速开始 58 | 59 | ### 📥 安装方法 60 | 61 | - **预编译二进制文件**: 从[发布页面](https://github.com/yosebyte/nodepass/releases)下载。 62 | - **容器镜像**: `docker pull ghcr.io/yosebyte/nodepass:latest` 63 | 64 | ### 🚀 基本用法 65 | 66 | **服务端模式** 67 | ```bash 68 | nodepass "server://:10101/127.0.0.1:8080?log=debug&tls=1" 69 | ``` 70 | 71 | **客户端模式** 72 | ```bash 73 | nodepass "client://server:10101/127.0.0.1:8080?min=128" 74 | ``` 75 | 76 | **主控模式 (API)** 77 | ```bash 78 | nodepass "master://:10101/api?log=debug&tls=1" 79 | ``` 80 | 81 | ## 📚 文档 82 | 83 | 探索完整文档以了解更多关于NodePass的信息： 84 | 85 | - [安装指南](/docs/zh/installation.md) 86 | - [使用说明](/docs/zh/usage.md) 87 | - [配置选项](/docs/zh/configuration.md) 88 | - [API参考](/docs/zh/api.md) 89 | - [使用示例](/docs/zh/examples.md) 90 | - [工作原理](/docs/zh/how-it-works.md) 91 | - [故障排除](/docs/zh/troubleshooting.md) 92 | 93 | ## 🌱 生态系统 94 | 95 | [NodePassProject](https://github.com/NodePassProject) 组织开发了各种前端应用和辅助工具来增强 NodePass 体验： 96 | 97 | - **[NodePassDash](https://github.com/NodePassProject/NodePassDash)**: 现代化的 NodePass 管理界面，提供主控管理、实例管理、流量统计、历史记录等功能。 98 | 99 | - **[NodePanel](https://github.com/NodePassProject/NodePanel)**: 轻量化的前端面板，提供可视化的隧道管理功能，在 Vercel 或 Cloudflare Pages 轻松部署。 100 | 101 | - **[npsh](https://github.com/NodePassProject/npsh)**: 简单易用的 NodePass 一键脚本合集，包括 API 主控、Dash 面板的安装部署、灵活配置和辅助管理。 102 | 103 | - **[NodePass-ApplePlatforms](https://github.com/NodePassProject/NodePass-ApplePlatforms)**: 面向服务的 iOS/macOS 应用，为 Apple 用户提供原生体验。 104 | 105 | - **[nodepass-core](https://github.com/NodePassProject/nodepass-core)**: 开发分支，包含新功能预览和性能优化测试，适合高级用户和开发者。 106 | 107 | ## 💬 讨论 108 | 109 | - 关注我们的 [Telegram 频道](https://t.me/NodePassChannel) 获取最新更新和社区支持。 110 | 111 | - 加入我们的 [Discord](https://discord.gg/2cnXcnDMGc) 和 [Telegram 群组](https://t.me/NodePassGroup) 分享经验和想法。 112 | 113 | ## 📄 许可协议 114 | 115 | **NodePass** 项目根据 [BSD 3-Clause 许可证](LICENSE)授权。 116 | 117 | ## ⚖️ 免责声明 118 | 119 | 本项目以"现状"提供，开发者不提供任何明示或暗示的保证。用户使用风险自担，需遵守当地法律法规，仅限合法用途。开发者对任何直接、间接、偶然或后果性损害概不负责。进行二次开发须承诺合法使用并自负法律责任。开发者保留随时修改软件功能及本声明的权利。最终解释权归开发者所有。 120 | 121 | ## 🔗 NFT 支持 122 | 123 | 以独特方式支持 **NodePass**，查看我们在 [OpenSea](https://opensea.io/collection/nodepass) 上的 NFT 收藏。 124 | 125 | ## 🤝 赞助商 126 | 127 | 128 | 129 | 132 | 135 | 136 | 137 | 140 | 143 | 144 | 145 | 148 | 149 |
130 | 131 | 133 | 134 |
138 | 139 | 141 | 142 |
146 | 147 |
150 | 151 | ## ⭐ Star趋势 152 | 153 | [![Stargazers over time](https://starchart.cc/yosebyte/nodepass.svg?variant=adaptive)](https://starchart.cc/yosebyte/nodepass) 154 | -------------------------------------------------------------------------------- /SECURITY.md: -------------------------------------------------------------------------------- 1 | # Security Policy 2 | 3 | ## Supported Versions 4 | 5 | We provide security updates for the following versions of NodePass: 6 | 7 | | Version | Supported | 8 | | ------- | ------------------ | 9 | | Latest | :white_check_mark: | 10 | 11 | ## Security Features 12 | 13 | NodePass implements multiple security layers: 14 | 15 | ### TLS Encryption Modes 16 | 17 | - **TLS Mode 0**: Unencrypted mode for trusted networks (highest performance, no encryption) 18 | - **TLS Mode 1**: Self-signed certificates with TLS 1.3 (balanced security, no verification) 19 | - **TLS Mode 2**: Custom certificate validation with TLS 1.3 (enterprise security, full verification) 20 | 21 | ### Network Security 22 | 23 | - Password-based tunnel authentication 24 | - Connection pooling with capacity limits 25 | - Graceful degradation under load 26 | - Configurable timeout and retry mechanisms 27 | 28 | ## Reporting Security Vulnerabilities 29 | 30 | We take security seriously. If you discover a security vulnerability in NodePass, please report it responsibly. 31 | 32 | ### Where to Report 33 | 34 | - **Email**: team@mail.nodepass.eu 35 | - **Subject**: [SECURITY] Brief description of the issue 36 | 37 | ### What to Include 38 | 39 | Please provide the following information in your report: 40 | 41 | 1. **Description** of the vulnerability 42 | 2. **Steps to reproduce** the issue 43 | 3. **Potential impact** and affected versions 44 | 4. **Your contact information** for follow-up 45 | 5. **Proof-of-concept code** (if applicable) 46 | 47 | ### Response Process 48 | 49 | Our security response timeline: 50 | 51 | 1. **Acknowledgment**: We will acknowledge receipt within 48 hours 52 | 2. **Assessment**: Initial assessment within 5 business days 53 | 3. **Updates**: Regular updates on investigation progress 54 | 4. **Resolution**: Security patch and public disclosure coordination 55 | 56 | ### Responsible Disclosure 57 | 58 | We follow coordinated vulnerability disclosure: 59 | 60 | - Please **do not** create public GitHub issues for security vulnerabilities 61 | - Give us reasonable time to investigate and patch the issue 62 | - We will coordinate public disclosure timing with you 63 | - Security researchers will be credited in our security advisories 64 | 65 | ## Security Best Practices 66 | 67 | ### For Users 68 | 69 | - **Use TLS Mode 1 or 2** in production environments 70 | - **Choose strong passwords** for tunnel authentication 71 | - **Keep NodePass updated** to the latest version 72 | - **Monitor logs** for suspicious activity 73 | - **Limit network exposure** by binding to specific interfaces 74 | - **Use firewall rules** to restrict access to tunnel ports 75 | 76 | ### For Developers 77 | 78 | - **Validate all inputs** including URL parameters and network data 79 | - **Use secure coding practices** following Go security guidelines 80 | - **Implement proper error handling** without leaking sensitive information 81 | - **Test security features** thoroughly before release 82 | - **Follow the principle of least privilege** in code design 83 | 84 | ## Security Architecture 85 | 86 | ### Network Layer 87 | 88 | - TLS 1.3 encryption for secure data transmission 89 | - Certificate validation and auto-reload capabilities 90 | - Protection against common network attacks 91 | 92 | ### Application Layer 93 | 94 | - Input validation and sanitization 95 | - Secure memory handling for sensitive data 96 | - Proper resource cleanup and connection management 97 | 98 | ### Operational Security 99 | 100 | - Minimal container image based on scratch 101 | - No unnecessary dependencies or services 102 | - Clear separation of concerns between components 103 | 104 | ## Known Security Considerations 105 | 106 | ### TLS Mode 0 Usage 107 | 108 | - Only use in completely trusted networks 109 | - Not recommended for internet-facing deployments 110 | - Provides maximum performance at the cost of encryption 111 | 112 | ### Master API Security 113 | 114 | - Secure the API endpoint with proper authentication 115 | - Use reverse proxy for additional security layers 116 | - Monitor API access and implement rate limiting 117 | 118 | ## Security Updates 119 | 120 | Security updates are released as: 121 | 122 | - **Patch releases** for critical vulnerabilities 123 | - **Minor releases** for security enhancements 124 | - **Documentation updates** for security best practices 125 | 126 | Subscribe to our release notifications: 127 | 128 | - [GitHub Releases](https://github.com/yosebyte/nodepass/releases) 129 | - [Telegram Channel](https://t.me/NodePassChannel) 130 | 131 | ## Ecosystem Security 132 | 133 | ### NodePassProject Libraries 134 | 135 | Our core dependencies are maintained by the NodePassProject organization: 136 | 137 | - **cert**: Certificate generation and management 138 | - **conn**: Secure connection handling 139 | - **logs**: Secure logging with sensitive data protection 140 | - **pool**: Connection pool management with resource limits 141 | 142 | ### Third-Party Dependencies 143 | 144 | - We minimize external dependencies 145 | - All dependencies are regularly audited for security issues 146 | - Updates are applied promptly when security issues are discovered 147 | 148 | ## Contact Information 149 | 150 | For security-related questions or concerns: 151 | 152 | - **Security Team**: team@mail.nodepass.eu 153 | - **General Issues**: [GitHub Issues](https://github.com/yosebyte/nodepass/issues) 154 | - **Community**: [Telegram Group](https://t.me/NodePassGroup) 155 | 156 | ## Attribution 157 | 158 | We appreciate security researchers who help improve NodePass security. Contributors to our security will be acknowledged in: 159 | 160 | - Security advisories 161 | - Release notes 162 | - Our contributors list 163 | 164 | --- 165 | 166 | **Note**: This security policy applies to the NodePass core project. For security issues in ecosystem projects (NodePassDash, NodePanel, etc.), please refer to their respective repositories in the [NodePassProject](https://github.com/NodePassProject) organization. 167 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 |
2 | 3 | 4 | [![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go#networking) 5 | [![GitHub release](https://img.shields.io/github/v/release/yosebyte/nodepass)](https://github.com/yosebyte/nodepass/releases) 6 | [![GitHub downloads](https://img.shields.io/github/downloads/yosebyte/nodepass/total.svg)](https://github.com/yosebyte/nodepass/releases) 7 | [![Go Report Card](https://goreportcard.com/badge/github.com/yosebyte/nodepass)](https://goreportcard.com/report/github.com/yosebyte/nodepass) 8 | [![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause) 9 | [![Go Reference](https://pkg.go.dev/badge/github.com/yosebyte/nodepass.svg)](https://pkg.go.dev/github.com/yosebyte/nodepass) 10 | [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/yosebyte/nodepass) 11 | ![GitHub last commit](https://img.shields.io/github/last-commit/yosebyte/nodepass) 12 | 13 | 14 | 15 | English | [简体中文](README_zh.md) 16 |
17 | 18 | **NodePass** is an open-source, lightweight, enterprise-grade TCP/UDP network tunneling solution featuring an all-in-one architecture with separation of control and data channels, along with flexible and high-performance instance control. It supports zero-configuration deployment, intelligent connection pooling, tiered TLS encryption, and seamless protocol conversion. Designed for DevOps professionals and system administrators to effortlessly handle complex network scenarios. 19 | 20 | ## 💎 Key Features 21 | 22 | - **🌐 Universal Functionality** 23 | - Basic TCP/UDP tunneling and protocol conversion across diverse networks. 24 | - Compatible with port mapping, NAT traversal, and traffic relay. 25 | - Cross-platform, multi-architecture, single binary or container. 26 | 27 | - **🚀 Connection Pool** 28 | - Supports TCP, QUIC, WebSocket, HTTP/2 pooling transport methods. 29 | - Eliminates handshake delays, boosts performance with 0-RTT support. 30 | - Auto-scaling with real-time capacity adjustment. 31 | 32 | - **🧬 Innovative Architecture** 33 | - Integrated S/C/M architecture, flexible mode switching. 34 | - Full decoupling of control/data channels. 35 | - API-instance management, multi-instance collaboration. 36 | 37 | - **🔐 Multi-level Security** 38 | - Three TLS modes: plaintext, self-signed, strict validation. 39 | - Covers development to enterprise security needs. 40 | - Hot-reload certificates with zero downtime. 41 | 42 | - **⚙️ Minimal Configuration** 43 | - No config files required, ready to use via CLI. 44 | - Optimized for CI/CD and containers. 45 | - Advanced parameters like timeouts and rate limits. 46 | 47 | - **📈 Performance** 48 | - Intelligent scheduling, auto-tuning, ultra-low resource usage. 49 | - Stable under high concurrency and heavy load. 50 | - Load balancing, health checks, self-healing and more. 51 | 52 | - **💡 Visualization** 53 | - Rich cross-platform visual frontends. 54 | - One-click deployment scripts, easy management. 55 | - Real-time monitoring, API-instance management, traffic stats. 56 | 57 | ## 📋 Quick Start 58 | 59 | ### 📥 Installation 60 | 61 | - **Pre-built Binaries**: Download from [releases page](https://github.com/yosebyte/nodepass/releases). 62 | - **Container Image**: `docker pull ghcr.io/yosebyte/nodepass:latest` 63 | 64 | ### 🚀 Basic Usage 65 | 66 | **Server Mode** 67 | ```bash 68 | nodepass "server://:10101/127.0.0.1:8080?log=debug&tls=1" 69 | ``` 70 | 71 | **Client Mode** 72 | ```bash 73 | nodepass "client://server:10101/127.0.0.1:8080?min=128" 74 | ``` 75 | 76 | **Master Mode (API)** 77 | ```bash 78 | nodepass "master://:10101/api?log=debug&tls=1" 79 | ``` 80 | 81 | ## 📚 Documentation 82 | 83 | Explore the complete documentation to learn more about NodePass: 84 | 85 | - [Installation Guide](/docs/en/installation.md) 86 | - [Usage Instructions](/docs/en/usage.md) 87 | - [Configuration Options](/docs/en/configuration.md) 88 | - [API Reference](/docs/en/api.md) 89 | - [Examples](/docs/en/examples.md) 90 | - [How It Works](/docs/en/how-it-works.md) 91 | - [Troubleshooting](/docs/en/troubleshooting.md) 92 | 93 | ## 🌱 Ecosystem 94 | 95 | The [NodePassProject](https://github.com/NodePassProject) organization develops various frontend applications and auxiliary tools to enhance the NodePass experience: 96 | 97 | - **[NodePassDash](https://github.com/NodePassProject/NodePassDash)**: A modern NodePass management interface that provides master management, instance management, traffic statistics, history records, and more. 98 | 99 | - **[NodePanel](https://github.com/NodePassProject/NodePanel)**: A lightweight frontend panel that provides visual tunnel management, deployable on Vercel or Cloudflare Pages. 100 | 101 | - **[npsh](https://github.com/NodePassProject/npsh)**: A collection of one-click scripts that provide simple deployment for API or Dashboard with flexible configuration and management. 102 | 103 | - **[NodePass-ApplePlatforms](https://github.com/NodePassProject/NodePass-ApplePlatforms)**: A service-oriented iOS/macOS application that offers a native experience for Apple users. 104 | 105 | - **[nodepass-core](https://github.com/NodePassProject/nodepass-core)**: Development branch, featuring previews of new functionalities and performance optimizations, suitable for advanced users and developers. 106 | 107 | ## 💬 Discussion 108 | 109 | - Follow our [Telegram Channel](https://t.me/NodePassChannel) for updates and community support. 110 | 111 | - Join our [Discord](https://discord.gg/2cnXcnDMGc) and [Telegram Group](https://t.me/NodePassGroup) to share experiences and ideas. 112 | 113 | ## 📄 License 114 | 115 | Project **NodePass** is licensed under the [BSD 3-Clause License](LICENSE). 116 | 117 | ## ⚖️ Disclaimer 118 | 119 | This project is provided "as is" without any warranties. Users assume all risks and must comply with local laws for legal use only. Developers are not liable for any direct, indirect, incidental, or consequential damages. Secondary development requires commitment to legal use and self-responsibility for legal compliance. Developers reserve the right to modify software features and this disclaimer at any time. Final interpretation rights belong to developers. 120 | 121 | ## 🔗 NFT Support 122 | 123 | Support **NodePass** in a unique way by checking out our NFT collection on [OpenSea](https://opensea.io/collection/nodepass). 124 | 125 | ## 🤝 Sponsors 126 | 127 | 128 | 129 | 132 | 135 | 136 | 137 | 140 | 143 | 144 | 145 | 148 | 149 |
130 | 131 | 133 | 134 |
138 | 139 | 141 | 142 |
146 | 147 |
150 | 151 | ## ⭐ Stargazers 152 | 153 | [![Stargazers over time](https://starchart.cc/yosebyte/nodepass.svg?variant=adaptive)](https://starchart.cc/yosebyte/nodepass) 154 | -------------------------------------------------------------------------------- /internal/server.go: -------------------------------------------------------------------------------- 1 | // 内部包，实现服务端模式功能 2 | package internal 3 | 4 | import ( 5 | "context" 6 | "crypto/tls" 7 | "encoding/json" 8 | "fmt" 9 | "io" 10 | "net" 11 | "net/http" 12 | "net/url" 13 | "os" 14 | "os/signal" 15 | "strings" 16 | "sync" 17 | "syscall" 18 | "time" 19 | 20 | "github.com/NodePassProject/logs" 21 | "github.com/NodePassProject/nph2" 22 | "github.com/NodePassProject/npws" 23 | "github.com/NodePassProject/pool" 24 | "github.com/NodePassProject/quic" 25 | ) 26 | 27 | // Server 实现服务端模式功能 28 | type Server struct{ Common } 29 | 30 | // NewServer 创建新的服务端实例 31 | func NewServer(parsedURL *url.URL, tlsCode string, tlsConfig *tls.Config, logger *logs.Logger) (*Server, error) { 32 | server := &Server{ 33 | Common: Common{ 34 | parsedURL: parsedURL, 35 | tlsCode: tlsCode, 36 | tlsConfig: tlsConfig, 37 | logger: logger, 38 | signalChan: make(chan string, semaphoreLimit), 39 | tcpBufferPool: &sync.Pool{ 40 | New: func() any { 41 | buf := make([]byte, tcpDataBufSize) 42 | return &buf 43 | }, 44 | }, 45 | udpBufferPool: &sync.Pool{ 46 | New: func() any { 47 | buf := make([]byte, udpDataBufSize) 48 | return &buf 49 | }, 50 | }, 51 | flushURL: &url.URL{Scheme: "np", Fragment: "f"}, 52 | pingURL: &url.URL{Scheme: "np", Fragment: "i"}, 53 | pongURL: &url.URL{Scheme: "np", Fragment: "o"}, 54 | }, 55 | } 56 | if err := server.initConfig(); err != nil { 57 | return nil, fmt.Errorf("newServer: initConfig failed: %w", err) 58 | } 59 | server.initRateLimiter() 60 | return server, nil 61 | } 62 | 63 | // Run 管理服务端生命周期 64 | func (s *Server) Run() { 65 | logInfo := func(prefix string) { 66 | s.logger.Info("%v: server://%v@%v/%v?dns=%v&max=%v&mode=%v&type=%v&dial=%v&read=%v&rate=%v&slot=%v&proxy=%v&block=%v¬cp=%v&noudp=%v", 67 | prefix, s.tunnelKey, s.tunnelTCPAddr, s.getTargetAddrsString(), s.dnsCacheTTL, s.maxPoolCapacity, 68 | s.runMode, s.poolType, s.dialerIP, s.readTimeout, s.rateLimit/125000, s.slotLimit, 69 | s.proxyProtocol, s.blockProtocol, s.disableTCP, s.disableUDP) 70 | } 71 | logInfo("Server started") 72 | 73 | ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM) 74 | 75 | // 启动服务端并处理重启 76 | go func() { 77 | for ctx.Err() == nil { 78 | // 启动服务端 79 | if err := s.start(); err != nil && err != io.EOF { 80 | s.logger.Error("Server error: %v", err) 81 | // 重启服务端 82 | s.stop() 83 | select { 84 | case <-ctx.Done(): 85 | return 86 | case <-time.After(serviceCooldown): 87 | } 88 | logInfo("Server restart") 89 | } 90 | } 91 | }() 92 | 93 | // 监听系统信号以优雅关闭 94 | <-ctx.Done() 95 | stop() 96 | 97 | // 执行关闭过程 98 | shutdownCtx, cancel := context.WithTimeout(context.Background(), shutdownTimeout) 99 | defer cancel() 100 | if err := s.shutdown(shutdownCtx, s.stop); err != nil { 101 | s.logger.Error("Server shutdown error: %v", err) 102 | } else { 103 | s.logger.Info("Server shutdown complete") 104 | } 105 | } 106 | 107 | // start 启动服务端 108 | func (s *Server) start() error { 109 | // 初始化上下文 110 | s.initContext() 111 | 112 | // 初始化隧道监听器 113 | if err := s.initTunnelListener(); err != nil { 114 | return fmt.Errorf("start: initTunnelListener failed: %w", err) 115 | } 116 | 117 | // 关闭UDP监听器 118 | if s.tunnelUDPConn != nil { 119 | s.tunnelUDPConn.Close() 120 | } 121 | 122 | // 运行模式判断 123 | switch s.runMode { 124 | case "1": // 反向模式 125 | if err := s.initTargetListener(); err != nil { 126 | return fmt.Errorf("start: initTargetListener failed: %w", err) 127 | } 128 | s.dataFlow = "-" 129 | case "2": // 正向模式 130 | s.dataFlow = "+" 131 | default: // 自动判断 132 | if err := s.initTargetListener(); err == nil { 133 | s.runMode = "1" 134 | s.dataFlow = "-" 135 | } else { 136 | s.runMode = "2" 137 | s.dataFlow = "+" 138 | } 139 | } 140 | 141 | // 接受隧道握手 142 | s.logger.Info("Pending tunnel handshake...") 143 | s.handshakeStart = time.Now() 144 | if err := s.tunnelHandshake(); err != nil { 145 | return fmt.Errorf("start: tunnelHandshake failed: %w", err) 146 | } 147 | 148 | // 初始化连接池 149 | if err := s.initTunnelPool(); err != nil { 150 | return fmt.Errorf("start: initTunnelPool failed: %w", err) 151 | } 152 | 153 | // 设置控制连接 154 | s.logger.Info("Getting tunnel pool ready...") 155 | if err := s.setControlConn(); err != nil { 156 | return fmt.Errorf("start: setControlConn failed: %w", err) 157 | } 158 | 159 | // 判断数据流向 160 | if s.dataFlow == "-" { 161 | go s.commonLoop() 162 | } 163 | 164 | // 启动共用控制 165 | if err := s.commonControl(); err != nil { 166 | return fmt.Errorf("start: commonControl failed: %w", err) 167 | } 168 | return nil 169 | } 170 | 171 | // initTunnelPool 初始化隧道连接池 172 | func (s *Server) initTunnelPool() error { 173 | switch s.poolType { 174 | case "0": 175 | tcpPool := pool.NewServerPool( 176 | s.maxPoolCapacity, 177 | s.clientIP, 178 | s.tlsConfig, 179 | s.tunnelListener, 180 | reportInterval) 181 | go tcpPool.ServerManager() 182 | s.tunnelPool = tcpPool 183 | case "1": 184 | quicPool := quic.NewServerPool( 185 | s.maxPoolCapacity, 186 | s.clientIP, 187 | s.tlsConfig, 188 | s.tunnelUDPAddr.String(), 189 | reportInterval) 190 | go quicPool.ServerManager() 191 | s.tunnelPool = quicPool 192 | case "2": 193 | websocketPool := npws.NewServerPool( 194 | s.maxPoolCapacity, 195 | "", 196 | s.tlsConfig, 197 | s.tunnelListener, 198 | reportInterval) 199 | go websocketPool.ServerManager() 200 | s.tunnelPool = websocketPool 201 | case "3": 202 | http2Pool := nph2.NewServerPool( 203 | s.maxPoolCapacity, 204 | s.clientIP, 205 | s.tlsConfig, 206 | s.tunnelListener, 207 | reportInterval) 208 | go http2Pool.ServerManager() 209 | s.tunnelPool = http2Pool 210 | default: 211 | return fmt.Errorf("initTunnelPool: unknown pool type: %s", s.poolType) 212 | } 213 | return nil 214 | } 215 | 216 | // tunnelHandshake 与客户端进行HTTP握手 217 | func (s *Server) tunnelHandshake() error { 218 | var clientIP string 219 | done := make(chan struct{}) 220 | 221 | handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { 222 | w.Header().Set("Connection", "close") 223 | 224 | // 验证请求 225 | if r.Method != http.MethodGet { 226 | http.Error(w, "Method Not Allowed", http.StatusMethodNotAllowed) 227 | return 228 | } 229 | 230 | // 验证路径 231 | if r.URL.Path != "/" { 232 | http.Error(w, "Not Found", http.StatusNotFound) 233 | return 234 | } 235 | 236 | // 验证令牌 237 | auth := r.Header.Get("Authorization") 238 | if !strings.HasPrefix(auth, "Bearer ") || !s.verifyAuthToken(strings.TrimPrefix(auth, "Bearer ")) { 239 | http.Error(w, "Unauthorized", http.StatusUnauthorized) 240 | return 241 | } 242 | 243 | // 记录客户端地址 244 | clientIP = r.RemoteAddr 245 | if host, _, err := net.SplitHostPort(clientIP); err == nil { 246 | clientIP = host 247 | } 248 | 249 | // 发送配置 250 | w.Header().Set("Content-Type", "application/json") 251 | json.NewEncoder(w).Encode(map[string]any{ 252 | "flow": s.dataFlow, 253 | "max": s.maxPoolCapacity, 254 | "tls": s.tlsCode, 255 | "type": s.poolType, 256 | }) 257 | 258 | s.logger.Info("Sending tunnel config: FLOW=%v|MAX=%v|TLS=%v|TYPE=%v", 259 | s.dataFlow, s.maxPoolCapacity, s.tlsCode, s.poolType) 260 | 261 | close(done) 262 | }) 263 | 264 | server := &http.Server{Handler: handler} 265 | go server.Serve(s.tunnelListener) 266 | 267 | select { 268 | case <-done: 269 | server.Close() 270 | s.clientIP = clientIP 271 | s.tunnelListener, _ = net.ListenTCP("tcp", s.tunnelTCPAddr) 272 | return nil 273 | case <-s.ctx.Done(): 274 | server.Close() 275 | return fmt.Errorf("tunnelHandshake: context canceled") 276 | } 277 | } 278 | -------------------------------------------------------------------------------- /internal/client.go: -------------------------------------------------------------------------------- 1 | // 内部包，实现客户端模式功能 2 | package internal 3 | 4 | import ( 5 | "context" 6 | "encoding/json" 7 | "fmt" 8 | "io" 9 | "net" 10 | "net/http" 11 | "net/url" 12 | "os" 13 | "os/signal" 14 | "sync" 15 | "syscall" 16 | "time" 17 | 18 | "github.com/NodePassProject/logs" 19 | "github.com/NodePassProject/nph2" 20 | "github.com/NodePassProject/npws" 21 | "github.com/NodePassProject/pool" 22 | "github.com/NodePassProject/quic" 23 | ) 24 | 25 | // Client 实现客户端模式功能 26 | type Client struct{ Common } 27 | 28 | // NewClient 创建新的客户端实例 29 | func NewClient(parsedURL *url.URL, logger *logs.Logger) (*Client, error) { 30 | client := &Client{ 31 | Common: Common{ 32 | parsedURL: parsedURL, 33 | logger: logger, 34 | signalChan: make(chan string, semaphoreLimit), 35 | tcpBufferPool: &sync.Pool{ 36 | New: func() any { 37 | buf := make([]byte, tcpDataBufSize) 38 | return &buf 39 | }, 40 | }, 41 | udpBufferPool: &sync.Pool{ 42 | New: func() any { 43 | buf := make([]byte, udpDataBufSize) 44 | return &buf 45 | }, 46 | }, 47 | flushURL: &url.URL{Scheme: "np", Fragment: "f"}, 48 | pingURL: &url.URL{Scheme: "np", Fragment: "i"}, 49 | pongURL: &url.URL{Scheme: "np", Fragment: "o"}, 50 | }, 51 | } 52 | if err := client.initConfig(); err != nil { 53 | return nil, fmt.Errorf("newClient: initConfig failed: %w", err) 54 | } 55 | client.initRateLimiter() 56 | return client, nil 57 | } 58 | 59 | // Run 管理客户端生命周期 60 | func (c *Client) Run() { 61 | logInfo := func(prefix string) { 62 | c.logger.Info("%v: client://%v@%v/%v?dns=%v&sni=%v&min=%v&mode=%v&dial=%v&read=%v&rate=%v&slot=%v&proxy=%v&block=%v¬cp=%v&noudp=%v", 63 | prefix, c.tunnelKey, c.tunnelTCPAddr, c.getTargetAddrsString(), c.dnsCacheTTL, c.serverName, c.minPoolCapacity, 64 | c.runMode, c.dialerIP, c.readTimeout, c.rateLimit/125000, c.slotLimit, 65 | c.proxyProtocol, c.blockProtocol, c.disableTCP, c.disableUDP) 66 | } 67 | logInfo("Client started") 68 | 69 | ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM) 70 | 71 | // 启动客户端服务并处理重启 72 | go func() { 73 | for ctx.Err() == nil { 74 | // 启动客户端 75 | if err := c.start(); err != nil && err != io.EOF { 76 | c.logger.Error("Client error: %v", err) 77 | // 重启客户端 78 | c.stop() 79 | select { 80 | case <-ctx.Done(): 81 | return 82 | case <-time.After(serviceCooldown): 83 | } 84 | logInfo("Client restart") 85 | } 86 | } 87 | }() 88 | 89 | // 监听系统信号以优雅关闭 90 | <-ctx.Done() 91 | stop() 92 | 93 | // 执行关闭过程 94 | shutdownCtx, cancel := context.WithTimeout(context.Background(), shutdownTimeout) 95 | defer cancel() 96 | if err := c.shutdown(shutdownCtx, c.stop); err != nil { 97 | c.logger.Error("Client shutdown error: %v", err) 98 | } else { 99 | c.logger.Info("Client shutdown complete") 100 | } 101 | } 102 | 103 | // start 启动客户端服务 104 | func (c *Client) start() error { 105 | // 初始化上下文 106 | c.initContext() 107 | 108 | // 运行模式判断 109 | switch c.runMode { 110 | case "1": // 单端模式 111 | if err := c.initTunnelListener(); err == nil { 112 | return c.singleStart() 113 | } else { 114 | return fmt.Errorf("start: initTunnelListener failed: %w", err) 115 | } 116 | case "2": // 双端模式 117 | return c.commonStart() 118 | default: // 自动判断 119 | if err := c.initTunnelListener(); err == nil { 120 | c.runMode = "1" 121 | return c.singleStart() 122 | } else { 123 | c.runMode = "2" 124 | return c.commonStart() 125 | } 126 | } 127 | } 128 | 129 | // singleStart 启动单端转发模式 130 | func (c *Client) singleStart() error { 131 | if err := c.singleControl(); err != nil { 132 | return fmt.Errorf("singleStart: singleControl failed: %w", err) 133 | } 134 | return nil 135 | } 136 | 137 | // commonStart 启动双端握手模式 138 | func (c *Client) commonStart() error { 139 | // 发起隧道握手 140 | c.logger.Info("Pending tunnel handshake...") 141 | c.handshakeStart = time.Now() 142 | if err := c.tunnelHandshake(); err != nil { 143 | return fmt.Errorf("commonStart: tunnelHandshake failed: %w", err) 144 | } 145 | 146 | // 初始化连接池 147 | if err := c.initTunnelPool(); err != nil { 148 | return fmt.Errorf("commonStart: initTunnelPool failed: %w", err) 149 | } 150 | 151 | // 设置控制连接 152 | c.logger.Info("Getting tunnel pool ready...") 153 | if err := c.setControlConn(); err != nil { 154 | return fmt.Errorf("commonStart: setControlConn failed: %w", err) 155 | } 156 | 157 | // 判断数据流向 158 | if c.dataFlow == "+" { 159 | if err := c.initTargetListener(); err != nil { 160 | return fmt.Errorf("commonStart: initTargetListener failed: %w", err) 161 | } 162 | go c.commonLoop() 163 | } 164 | 165 | // 启动共用控制 166 | if err := c.commonControl(); err != nil { 167 | return fmt.Errorf("commonStart: commonControl failed: %w", err) 168 | } 169 | 170 | return nil 171 | } 172 | 173 | // initTunnelPool 初始化隧道连接池 174 | func (c *Client) initTunnelPool() error { 175 | switch c.poolType { 176 | case "0": 177 | tcpPool := pool.NewClientPool( 178 | c.minPoolCapacity, 179 | c.maxPoolCapacity, 180 | minPoolInterval, 181 | maxPoolInterval, 182 | reportInterval, 183 | c.tlsCode, 184 | c.serverName, 185 | func() (net.Conn, error) { 186 | tcpAddr, err := c.getTunnelTCPAddr() 187 | if err != nil { 188 | return nil, err 189 | } 190 | return net.DialTimeout("tcp", tcpAddr.String(), tcpDialTimeout) 191 | }) 192 | go tcpPool.ClientManager() 193 | c.tunnelPool = tcpPool 194 | case "1": 195 | quicPool := quic.NewClientPool( 196 | c.minPoolCapacity, 197 | c.maxPoolCapacity, 198 | minPoolInterval, 199 | maxPoolInterval, 200 | reportInterval, 201 | c.tlsCode, 202 | c.serverName, 203 | func() (string, error) { 204 | udpAddr, err := c.getTunnelUDPAddr() 205 | if err != nil { 206 | return "", err 207 | } 208 | return udpAddr.String(), nil 209 | }) 210 | go quicPool.ClientManager() 211 | c.tunnelPool = quicPool 212 | case "2": 213 | websocketPool := npws.NewClientPool( 214 | c.minPoolCapacity, 215 | c.maxPoolCapacity, 216 | minPoolInterval, 217 | maxPoolInterval, 218 | reportInterval, 219 | c.tlsCode, 220 | c.tunnelAddr) 221 | go websocketPool.ClientManager() 222 | c.tunnelPool = websocketPool 223 | case "3": 224 | http2Pool := nph2.NewClientPool( 225 | c.minPoolCapacity, 226 | c.maxPoolCapacity, 227 | minPoolInterval, 228 | maxPoolInterval, 229 | reportInterval, 230 | c.tlsCode, 231 | c.serverName, 232 | func() (string, error) { 233 | tcpAddr, err := c.getTunnelTCPAddr() 234 | if err != nil { 235 | return "", err 236 | } 237 | return tcpAddr.String(), nil 238 | }) 239 | go http2Pool.ClientManager() 240 | c.tunnelPool = http2Pool 241 | default: 242 | return fmt.Errorf("initTunnelPool: unknown pool type: %s", c.poolType) 243 | } 244 | return nil 245 | } 246 | 247 | // tunnelHandshake 与隧道服务端进行握手 248 | func (c *Client) tunnelHandshake() error { 249 | scheme := "http" 250 | if c.serverPort == "443" { 251 | scheme = "https" 252 | } 253 | 254 | // 构建请求 255 | req, _ := http.NewRequest(http.MethodGet, scheme+"://"+c.tunnelAddr+"/", nil) 256 | req.Host = c.serverName 257 | req.Header.Set("Authorization", "Bearer "+c.generateAuthToken()) 258 | 259 | // 发送请求 260 | client := &http.Client{} 261 | resp, err := client.Do(req) 262 | if err != nil { 263 | return fmt.Errorf("tunnelHandshake: %w", err) 264 | } 265 | defer resp.Body.Close() 266 | 267 | if resp.StatusCode != http.StatusOK { 268 | return fmt.Errorf("tunnelHandshake: status %d", resp.StatusCode) 269 | } 270 | 271 | // 解析配置 272 | var config struct { 273 | Flow string `json:"flow"` 274 | Max int `json:"max"` 275 | TLS string `json:"tls"` 276 | Type string `json:"type"` 277 | } 278 | if err := json.NewDecoder(resp.Body).Decode(&config); err != nil { 279 | return fmt.Errorf("tunnelHandshake: %w", err) 280 | } 281 | 282 | // 更新配置 283 | c.dataFlow = config.Flow 284 | c.maxPoolCapacity = config.Max 285 | c.tlsCode = config.TLS 286 | c.poolType = config.Type 287 | 288 | c.logger.Info("Loading tunnel config: FLOW=%v|MAX=%v|TLS=%v|TYPE=%v", 289 | c.dataFlow, c.maxPoolCapacity, c.tlsCode, c.poolType) 290 | return nil 291 | } 292 | -------------------------------------------------------------------------------- /docs/zh/usage.md: -------------------------------------------------------------------------------- 1 | # 使用说明 2 | 3 | NodePass创建一个带有未加密TCP控制通道的隧道，并为数据交换提供可配置的TLS加密选项。本指南涵盖三种操作模式并说明如何有效地使用每种模式。 4 | 5 | ## 命令行语法 6 | 7 | NodePass命令的一般语法是： 8 | 9 | ```bash 10 | nodepass ":///?log=&tls=&crt=&key=&dns=&min=&max=&mode=&type=&dial=&read=&rate=&slot=&proxy=¬cp=<0|1>&noudp=<0|1>" 11 | ``` 12 | 13 | 其中： 14 | - ``：指定运行模式（`server`、`client` 或 `master`） 15 | - ``：用于控制通道通信的隧道端点地址 16 | - ``：支持双向流的业务数据目标地址（或主控模式下的API前缀） 17 | 18 | ### 查询参数 19 | 20 | 通用查询参数： 21 | - `log=`：日志详细级别（`none`、`debug`、`info`、`warn`、`error` 或 `event`） 22 | - `dns=`：DNS缓存TTL持续时间（默认：`5m`，支持时间单位如`1h`、`30m`、`15s`等） 23 | - `min=`：最小连接池容量（默认：64，由客户端设置） 24 | - `max=`：最大连接池容量（默认：1024，由服务端设置并下发给客户端） 25 | - `mode=`：运行模式控制（`0`、`1` 或 `2`）- 控制操作行为 26 | - `type=`：连接池类型（`0`为TCP连接池，`1`为QUIC UDP连接池，`2`为WebSocket/WSS连接池，`3`为HTTP/2连接池，默认：0，仅服务端配置） 27 | - `dial=`：出站连接的源IP地址（默认：`auto`，支持IPv4和IPv6） 28 | - `read=`：数据读取超时时长（默认：0，支持时间单位如30s、5m、1h等） 29 | - `rate=`：带宽速率限制，单位Mbps（默认：0表示无限制） 30 | - `slot=`：最大并发连接数限制（默认：65536，0表示无限制） 31 | - `proxy=`：PROXY协议支持（默认：`0`，`1`启用PROXY协议v1头部传输） 32 | - `notcp=<0|1>`：TCP支持控制（默认：`0`启用，`1`禁用） 33 | - `noudp=<0|1>`：UDP支持控制（默认：`0`启用，`1`禁用） 34 | 35 | TLS相关参数（仅适用于server/master模式）： 36 | - `tls=`：数据通道的TLS安全级别（`0`、`1` 或 `2`） 37 | - `crt=`：证书文件路径（当`tls=2`时） 38 | - `key=`：私钥文件路径（当`tls=2`时） 39 | 40 | 连接池类型（仅服务端模式）： 41 | - `type=`：连接池类型（`0`为TCP连接池，`1`为QUIC UDP连接池，`2`为WebSocket/WSS连接池，默认：0） 42 | - 服务端配置在握手时自动下发给客户端 43 | - 客户端无需指定type参数 44 | 45 | ## 运行模式 46 | 47 | NodePass提供三种互补的运行模式，以适应各种部署场景。 48 | 49 | ### 服务端模式 50 | 51 | 服务端模式建立隧道控制通道，并支持双向数据流转发。 52 | 53 | ```bash 54 | nodepass "server:///?log=&tls=&crt=&key=&dns=&type=&max=&mode=&dial=&read=&rate=&slot=&proxy=¬cp=<0|1>&noudp=<0|1>" 55 | ``` 56 | 57 | #### 参数 58 | 59 | - `tunnel_addr`：TCP隧道端点地址（控制通道），客户端将连接到此处(例如, 10.1.0.1:10101) 60 | - `target_addr`：业务数据的目标地址，支持双向数据流模式(例如, 10.1.0.1:8080) 61 | - `log`：日志级别(debug, info, warn, error, event) 62 | - `dns`：DNS缓存TTL持续时间（默认：5m，支持时间单位如`1h`、`30m`、`15s`等） 63 | - `type`：连接池类型 (0, 1, 2, 3) 64 | - `0`：使用基于TCP的连接池（默认） 65 | - `1`：使用基于QUIC的UDP连接池，支持流多路复用（需要TLS，至少`tls=1`） 66 | - `2`：使用基于WebSocket/WSS的连接池 67 | - `3`：使用基于HTTP/2的连接池，支持多路复用流（需要TLS，至少`tls=1`） 68 | - 配置在握手时自动下发给客户端 69 | - `tls`：目标数据通道的TLS加密模式 (0, 1, 2) 70 | - `0`：无TLS加密（明文TCP/UDP） 71 | - `1`：自签名证书（自动生成） 72 | - `2`：自定义证书（需要`crt`和`key`参数） 73 | - `crt`：证书文件路径（当`tls=2`时必需） 74 | - `key`：私钥文件路径（当`tls=2`时必需） 75 | - `max`：最大连接池容量（默认：1024） 76 | - `mode`：数据流方向的运行模式控制 77 | - `0`：自动检测（默认）- 首先尝试本地绑定，如果不可用则回退 78 | - `1`：强制反向模式 - 服务器本地绑定目标地址并接收流量 79 | - `2`：强制正向模式 - 服务器连接到远程目标地址 80 | - `dial`：连接目标的出站源IP地址（默认：`auto`为系统选择的IP） 81 | - `read`：数据读取超时时间（默认：0，支持时间单位如 30s、30m、1h 等） 82 | - `rate`：带宽速率限制（默认：0，表示无限制） 83 | - `slot`：最大并发连接数限制（默认：65536，0表示无限制） 84 | - `proxy`：PROXY协议支持（默认：`0`，`1`在数据传输前启用PROXY协议v1头部） 85 | - `notcp`：TCP支持控制（默认：`0`启用，`1`禁用） 86 | - `noudp`：UDP支持控制（默认：`0`启用，`1`禁用） 87 | 88 | #### 服务端模式工作原理 89 | 90 | 服务端模式通过`mode`参数支持自动模式检测或强制模式选择： 91 | 92 | **模式0：自动检测**（默认） 93 | - 首先尝试本地绑定`target_addr` 94 | - 如果成功，以反向模式运行（服务端接收流量） 95 | - 如果绑定失败，以正向模式运行（服务端发送流量） 96 | 97 | **模式1：反向模式**（服务端接收流量） 98 | 1. 在`tunnel_addr`上监听TCP隧道连接（控制通道） 99 | 2. 绑定并在`target_addr`上监听传入的TCP和UDP流量 100 | 3. 当`target_addr`收到连接时，通过控制通道向已连接的客户端发送信号 101 | 4. 为每个连接创建具有指定TLS加密级别的数据通道 102 | 103 | **模式2：正向模式**（服务端发送流量） 104 | 1. 在`tunnel_addr`上监听TCP隧道连接（控制通道） 105 | 2. 等待客户端在其本地监听，并通过隧道接收连接 106 | 3. 建立到远程`target_addr`的连接并转发数据 107 | 108 | #### 示例 109 | 110 | ```bash 111 | # 自动模式检测，无TLS加密 112 | nodepass "server://10.1.0.1:10101/10.1.0.1:8080?log=debug&tls=0" 113 | 114 | # 强制反向模式，自签名证书 115 | nodepass "server://10.1.0.1:10101/10.1.0.1:8080?log=debug&tls=1&mode=1" 116 | 117 | # 强制正向模式，自定义证书 118 | nodepass "server://10.1.0.1:10101/192.168.1.100:8080?log=debug&tls=2&mode=2&crt=/path/to/cert.pem&key=/path/to/key.pem" 119 | 120 | # QUIC连接池，自动启用TLS 121 | nodepass "server://10.1.0.1:10101/192.168.1.100:8080?log=debug&type=1&mode=2" 122 | 123 | # WebSocket连接池，使用自定义证书 124 | nodepass "server://10.1.0.1:10101/192.168.1.100:8080?log=debug&type=2&tls=2&mode=2&crt=/path/to/cert.pem&key=/path/to/key.pem" 125 | 126 | # HTTP/2连接池，自动启用TLS 127 | nodepass "server://10.1.0.1:10101/192.168.1.100:8080?log=debug&type=3&mode=2&tls=1" 128 | ``` 129 | 130 | ### 客户端模式 131 | 132 | 客户端模式连接到NodePass服务端并支持双向数据流转发。 133 | 134 | ```bash 135 | nodepass "client:///?log=&dns=&min=&mode=&dial=&read=&rate=&slot=&proxy=¬cp=<0|1>&noudp=<0|1>" 136 | ``` 137 | 138 | #### 参数 139 | 140 | - `tunnel_addr`：要连接的NodePass服务端隧道端点地址(例如, 10.1.0.1:10101) 141 | - `target_addr`：业务数据的目标地址，支持双向数据流模式(例如, 127.0.0.1:8080) 142 | - `log`：日志级别(debug, info, warn, error, event) 143 | - `dns`：DNS缓存TTL持续时间（默认：5m，支持时间单位如`1h`、`30m`、`15s`等） 144 | - `min`：最小连接池容量（默认：64） 145 | - `mode`：客户端行为的运行模式控制 146 | - `0`：自动检测（默认）- 首先尝试本地绑定，如果失败则回退到握手模式 147 | - `1`：强制单端转发模式 - 带连接池的本地代理 148 | - `2`：强制双端握手模式 - 需要服务器协调 149 | - `dial`：连接目标的出站源IP地址（默认：`auto`为系统选择的IP） 150 | - `read`：数据读取超时时间（默认：0，支持时间单位如30s、5m、1h等） 151 | - `rate`：带宽速率限制，单位Mbps（默认：0表示无限制） 152 | - `slot`：最大并发连接数限制（默认：65536，0表示无限制） 153 | - `proxy`：PROXY协议支持（默认：`0`，`1`在数据传输前启用PROXY协议v1头部） 154 | - `notcp`：TCP支持控制（默认：`0`启用，`1`禁用） 155 | - `noudp`：UDP支持控制（默认：`0`启用，`1`禁用） 156 | 157 | **注意**：连接池类型配置在握手时自动从服务器接收。客户端无需指定`type`参数。 158 | 159 | #### 客户端模式工作原理 160 | 161 | 客户端模式通过`mode`参数支持自动模式检测或强制模式选择： 162 | 163 | **模式0：自动检测**（默认） 164 | - 首先尝试本地绑定`tunnel_addr` 165 | - 如果成功，以单端转发模式运行 166 | - 如果绑定失败，以双端握手模式运行 167 | 168 | **模式1：单端转发模式** 169 | 1. 在本地隧道地址上监听TCP和UDP连接 170 | 2. 使用连接池技术预建立到目标地址的TCP连接，消除连接延迟 171 | 3. 直接将接收到的流量转发到目标地址，实现高性能转发 172 | 4. 无需与服务端握手，实现点对点的直接转发 173 | 5. 适用于本地代理和简单转发场景 174 | 175 | **模式2：双端握手模式** 176 | - **客户端接收流量**（当服务端发送流量时） 177 | 1. 连接到服务端的TCP隧道端点（控制通道） 178 | 2. 在本地监听端口，等待通过隧道传入的连接 179 | 3. 建立到本地`target_addr`的连接并转发数据 180 | 181 | - **客户端发送流量**（当服务端接收流量时） 182 | 1. 连接到服务端的TCP隧道端点（控制通道） 183 | 2. 通过控制通道监听来自服务端的信号 184 | 3. 当收到信号时，使用服务端指定的TLS安全级别建立数据连接 185 | 4. 建立到`target_addr`的连接并转发流量 186 | 187 | #### 示例 188 | 189 | ```bash 190 | # 自动模式检测 - 本地代理监听1080端口，转发到目标服务器 191 | nodepass "client://127.0.0.1:1080/target.example.com:8080?log=debug" 192 | 193 | # 强制单端转发模式 - 高性能本地代理 194 | nodepass "client://127.0.0.1:1080/target.example.com:8080?mode=1&log=debug" 195 | 196 | # 强制双端握手模式 - 连接到NodePass服务端并采用其TLS安全策略 197 | nodepass "client://server.example.com:10101/127.0.0.1:8080?mode=2" 198 | 199 | # 使用调试日志和自定义连接池容量连接 200 | nodepass "client://server.example.com:10101/192.168.1.100:8080?log=debug&min=128" 201 | 202 | # 强制模式的资源受限配置 203 | nodepass "client://server.example.com:10101/127.0.0.1:8080?mode=2&min=16&log=info" 204 | 205 | # 资源受限配置 - 小型连接池 206 | nodepass "client://server.example.com:10101/127.0.0.1:8080?min=16&log=info" 207 | 208 | # 客户端自动从服务器接收连接池类型配置（无需type参数） 209 | nodepass "client://server.example.com:10101/127.0.0.1:8080?mode=2&min=128&log=debug" 210 | 211 | # 实时应用客户端（从服务器获取连接池类型配置） 212 | nodepass "client://server.example.com:10101/127.0.0.1:7777?mode=2&min=64&read=30s" 213 | ``` 214 | 215 | ### 主控模式 (API) 216 | 217 | 主控模式运行RESTful API服务器，用于集中管理NodePass实例。 218 | 219 | ```bash 220 | nodepass "master://[]?log=&tls=&crt=&key=" 221 | ``` 222 | 223 | #### 参数 224 | 225 | - `api_addr`：API服务监听的地址（例如，0.0.0.0:9090） 226 | - `prefix`：可选的API前缀路径（例如，/management）。默认为`/api` 227 | - `log`：日志级别(debug, info, warn, error, event) 228 | - `tls`：API服务的TLS加密模式(0, 1, 2) 229 | - `0`：无TLS加密（HTTP） 230 | - `1`：自签名证书（带自动生成证书的HTTPS） 231 | - `2`：自定义证书（带提供证书的HTTPS） 232 | - `crt`：证书文件路径（当`tls=2`时必需） 233 | - `key`：私钥文件路径（当`tls=2`时必需） 234 | 235 | #### 主控模式工作原理 236 | 237 | 在主控模式下，NodePass： 238 | 1. 运行一个RESTful API服务器，允许动态管理NodePass实例 239 | 2. 提供用于创建、启动、停止和监控客户端和服务端实例的端点 240 | 3. 包含用于轻松API探索的Swagger UI，位于`{prefix}/v1/docs` 241 | 4. 自动继承通过API创建的实例的TLS和日志设置 242 | 243 | #### API端点 244 | 245 | 所有端点都是相对于配置的前缀（默认：`/api`）： 246 | 247 | **受保护的端点（需要API Key）：** 248 | - `GET {prefix}/v1/instances` - 列出所有实例 249 | - `POST {prefix}/v1/instances` - 创建新实例，JSON请求体: `{"url": "server://0.0.0.0:10101/0.0.0.0:8080"}` 250 | - `GET {prefix}/v1/instances/{id}` - 获取实例详情 251 | - `PATCH {prefix}/v1/instances/{id}` - 更新实例，JSON请求体: `{"action": "start|stop|restart"}` 252 | - `DELETE {prefix}/v1/instances/{id}` - 删除实例 253 | - `GET {prefix}/v1/events` - 服务端发送事件流（SSE） 254 | - `GET {prefix}/v1/info` - 获取系统信息 255 | 256 | **公共端点（无需API Key）：** 257 | - `GET {prefix}/v1/openapi.json` - OpenAPI规范 258 | - `GET {prefix}/v1/docs` - Swagger UI文档 259 | 260 | #### 示例 261 | 262 | ```bash 263 | # 启动HTTP主控服务（使用默认API前缀/api） 264 | nodepass "master://0.0.0.0:9090?log=info" 265 | 266 | # 启动带有自定义API前缀的主控服务（/management） 267 | nodepass "master://0.0.0.0:9090/management?log=info" 268 | 269 | # 启动HTTPS主控服务（自签名证书） 270 | nodepass "master://0.0.0.0:9090/admin?log=info&tls=1" 271 | 272 | # 启动HTTPS主控服务（自定义证书） 273 | nodepass "master://0.0.0.0:9090?log=info&tls=2&crt=/path/to/cert.pem&key=/path/to/key.pem" 274 | ``` 275 | 276 | ## 管理NodePass实例 277 | 278 | ### 通过API创建和管理 279 | 280 | NodePass主控模式提供RESTful API来管理实例，所有API请求都需要使用API Key进行身份验证。 281 | 282 | #### API Key获取 283 | 284 | 启动主控模式后，系统会自动生成API Key并在日志中显示： 285 | 286 | ```bash 287 | # 启动主控模式 288 | nodepass "master://0.0.0.0:9090?log=info" 289 | 290 | # 日志输出中会显示： 291 | # INFO: API Key created: abc123def456... 292 | ``` 293 | 294 | #### API请求示例 295 | 296 | 所有受保护的API端点都需要在请求头中包含`X-API-Key`： 297 | 298 | ```bash 299 | # 获取API Key (假设为: abc123def456789) 300 | 301 | # 通过API创建实例（使用默认前缀） 302 | curl -X POST http://localhost:9090/api/v1/instances \ 303 | -H "X-API-Key: abc123def456789" \ 304 | -d '{"url":"server://0.0.0.0:10101/0.0.0.0:8080?tls=1"}' 305 | 306 | # 使用自定义前缀 307 | curl -X POST http://localhost:9090/admin/v1/instances \ 308 | -H "X-API-Key: abc123def456789" \ 309 | -d '{"url":"server://0.0.0.0:10101/0.0.0.0:8080?tls=1"}' 310 | 311 | # 列出所有运行实例 312 | curl http://localhost:9090/api/v1/instances \ 313 | -H "X-API-Key: abc123def456789" 314 | 315 | # 控制实例（用实际实例ID替换{id}） 316 | curl -X PATCH http://localhost:9090/api/v1/instances/{id} \ 317 | -H "X-API-Key: abc123def456789" \ 318 | -d '{"action":"restart"}' 319 | ``` 320 | 321 | #### 公共端点 322 | 323 | 以下端点不需要API Key身份验证： 324 | - `GET {prefix}/v1/openapi.json` - OpenAPI规范 325 | - `GET {prefix}/v1/docs` - Swagger UI文档 326 | 327 | ## 双向数据流说明 328 | 329 | NodePass支持灵活的双向数据流配置： 330 | 331 | ### 客户端单端转发模式 332 | - **客户端**：在本地隧道地址监听，使用连接池技术直接转发到目标地址 333 | - **连接池优化**：预建立TCP连接，消除连接延迟，提供高性能转发 334 | - **无需服务端**：独立运行，不依赖服务端握手 335 | - **使用场景**：本地代理、简单端口转发、测试环境、高性能转发 336 | 337 | ### 服务端接收模式 338 | - **服务端**：在target_addr监听传入连接，通过隧道转发到客户端 339 | - **客户端**：连接到本地target_addr提供服务 340 | - **使用场景**：将内网服务暴露给外网访问 341 | 342 | ### 服务端发送模式 343 | - **服务端**：连接到远程target_addr获取数据，通过隧道发送到客户端 344 | - **客户端**：在本地监听，接收来自服务端的连接 345 | - **使用场景**：通过隧道代理访问远程服务 346 | 347 | 系统会根据隧道地址和目标地址自动选择合适的操作模式： 348 | - 如果客户端的隧道地址为本地地址，启用单端转发模式 349 | - 如果目标地址是本地地址，使用服务端接收模式 350 | - 如果目标地址是远程地址，使用服务端发送模式 351 | 352 | ## 隧道密钥（Tunnel Key） 353 | 354 | NodePass使用隧道密钥来验证客户端和服务端之间的连接。密钥可以通过两种方式指定： 355 | 356 | ### 密钥获取规则 357 | 358 | 1. **显式密钥**：在URL中指定用户名部分作为密钥 359 | ```bash 360 | # 使用"mypassword"作为隧道密钥 361 | nodepass server://mypassword@10.1.0.1:10101/10.1.0.1:8080 362 | nodepass client://mypassword@10.1.0.1:10101/127.0.0.1:8080 363 | ``` 364 | 365 | 2. **端口派生密钥**：如果未指定用户名，系统将使用端口号的十六进制值作为密钥 366 | ```bash 367 | # 端口10101的十六进制值为"2775"，将作为隧道密钥 368 | nodepass server://10.1.0.1:10101/10.1.0.1:8080 369 | nodepass client://10.1.0.1:10101/127.0.0.1:8080 370 | ``` 371 | 372 | ### 握手流程 373 | 374 | 客户端与服务端的握手过程如下： 375 | 376 | 1. **客户端连接**：客户端连接到服务端的隧道地址 377 | 2. **密钥验证**：客户端发送加密的隧道密钥 378 | 3. **服务端验证**：服务端解密并验证密钥是否匹配 379 | 4. **配置同步**：验证成功后，服务端发送隧道配置信息，包括： 380 | - 数据流向模式 381 | - 最大连接池容量 382 | - TLS安全模式 383 | 5. **连接确立**：握手完成，开始数据传输 384 | 385 | 这种设计确保了只有拥有正确密钥的客户端才能建立隧道连接，同时允许服务端统一管理连接池容量。 386 | 387 | ## 下一步 388 | 389 | - 了解[配置选项](/docs/zh/configuration.md)以微调NodePass 390 | - 探索常见部署场景的[使用示例](/docs/zh/examples.md) 391 | - 理解NodePass内部[工作原理](/docs/zh/how-it-works.md) 392 | - 如果遇到问题，请查看[故障排除指南](/docs/zh/troubleshooting.md) -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing to NodePass 2 | 3 | Thank you for your interest in contributing to NodePass! We welcome all kinds of contributions, from bug reports and feature requests to code improvements and documentation updates. 4 | 5 | ## Table of Contents 6 | 7 | - [Organization](#organization) 8 | - [Code of Conduct](#code-of-conduct) 9 | - [Getting Started](#getting-started) 10 | - [Development Setup](#development-setup) 11 | - [Contributing Guidelines](#contributing-guidelines) 12 | - [Code Style and Standards](#code-style-and-standards) 13 | - [Testing](#testing) 14 | - [Documentation](#documentation) 15 | - [Submitting Changes](#submitting-changes) 16 | - [Community and Support](#community-and-support) 17 | 18 | ## Code of Conduct 19 | 20 | Please read and follow our [Code of Conduct](CODE_OF_CONDUCT.md). We are committed to providing a welcoming and inclusive environment for all contributors. 21 | 22 | ## Getting Started 23 | 24 | ### Prerequisites 25 | 26 | - **Go** 1.25+ (as specified in `go.mod`) 27 | - **Git** for version control 28 | - **Docker** (optional, for container-based development and testing) 29 | - Basic knowledge of TCP/UDP networking concepts 30 | - Familiarity with TLS/SSL concepts for security features 31 | 32 | ### Understanding the Architecture 33 | 34 | NodePass is built on a three-tier architecture: 35 | 36 | - **Server Mode**: Accepts incoming tunnel connections with configurable security 37 | - **Client Mode**: Establishes outbound connections to tunnel servers 38 | - **Master Mode**: Provides RESTful API for dynamic instance management 39 | 40 | Key components: 41 | 42 | - `/cmd/nodepass/`: Main application entry point and core dispatch logic 43 | - `/internal/`: Core implementation packages (server, client, master, common utilities) 44 | - `/docs/`: Comprehensive documentation in English and Chinese 45 | - External dependencies: NodePassProject ecosystem libraries for certificates, connections, logging, and pooling 46 | 47 | ## Development Setup 48 | 49 | ### 1. Fork and Clone 50 | 51 | ```bash 52 | # Fork the repository on GitHub, then clone your fork 53 | git clone https://github.com/YOUR_USERNAME/nodepass.git 54 | cd nodepass 55 | 56 | # Add the upstream repository 57 | git remote add upstream https://github.com/yosebyte/nodepass.git 58 | ``` 59 | 60 | ### 2. Install Dependencies 61 | 62 | ```bash 63 | # Download and install dependencies 64 | go mod download 65 | 66 | # Verify dependencies 67 | go mod verify 68 | ``` 69 | 70 | ### 3. Build and Test 71 | 72 | ```bash 73 | # Build the application 74 | go build -o nodepass ./cmd/nodepass 75 | 76 | # Test the build 77 | ./nodepass "server://localhost:10101/127.0.0.1:8080?log=debug&tls=0" 78 | ``` 79 | 80 | ### 4. Development with Docker (Optional) 81 | 82 | ```bash 83 | # Build development container 84 | docker build --build-arg VERSION=dev -t nodepass:dev . 85 | 86 | # Run in container 87 | docker run --rm -p 10101:10101 nodepass:dev "server://:10101/127.0.0.1:8080?log=debug&tls=0" 88 | ``` 89 | 90 | ## Contributing Guidelines 91 | 92 | ### Types of Contributions 93 | 94 | - **Bug Reports**: Help us identify and fix issues 95 | - **Feature Requests**: Suggest new features or improvements 96 | - **Documentation**: Improve existing docs or add new ones 97 | - **Code Contributions**: Bug fixes, feature implementations, refactoring 98 | - **Translations**: Help translate documentation to other languages 99 | - **Testing**: Add test cases and improve test coverage 100 | 101 | ### Reporting Issues 102 | 103 | When reporting bugs or requesting features, please: 104 | 105 | 1. **Search existing issues** to avoid duplicates 106 | 2. **Use our issue templates** when available 107 | 3. **Provide detailed information**: 108 | - NodePass version and build information 109 | - Operating system and architecture 110 | - Network configuration details 111 | - Complete command-line arguments used 112 | - Expected vs. actual behavior 113 | - Relevant log output (use `log=debug` for detailed logs) 114 | - Steps to reproduce the issue 115 | 116 | ### Feature Requests 117 | 118 | For new features: 119 | 120 | 1. **Check the roadmap** and existing feature requests 121 | 2. **Describe the use case** clearly 122 | 3. **Explain the expected behavior** 123 | 4. **Consider backwards compatibility** 124 | 5. **Discuss implementation approach** if you plan to contribute code 125 | 126 | ## Code Style and Standards 127 | 128 | ### Go Code Style 129 | 130 | We follow standard Go conventions with project-specific guidelines: 131 | 132 | - Write idiomatic Go code following [Effective Go](https://golang.org/doc/effective_go.html) 133 | - Use `gofmt` for consistent formatting and `go vet` to catch common errors 134 | - Follow the single responsibility principle and prefer composition over inheritance 135 | - Use descriptive variable and function names with proper Go naming conventions 136 | - Include both Chinese and English comments for public APIs (maintaining project tradition) 137 | - Implement proper error handling with context wrapping 138 | - Use the project's logging framework consistently with appropriate log levels 139 | - Protect shared state with mutexes and use channels for goroutine coordination 140 | - Always handle goroutine cleanup with proper defer and recover patterns 141 | 142 | ### Configuration and CLI 143 | 144 | - Use URL-based configuration syntax: `scheme://[password@]host:port/target?param=value` 145 | - Support environment variables for sensitive configuration 146 | - Provide sensible defaults for all optional parameters 147 | - Validate configuration early in the application lifecycle 148 | 149 | ### Performance Considerations 150 | 151 | - Minimize allocations in hot paths 152 | - Use connection pooling for frequent connections 153 | - Implement graceful degradation under load 154 | - Profile memory and CPU usage for critical paths 155 | - Use buffered I/O where appropriate 156 | 157 | ## Testing 158 | 159 | ### Testing Strategy 160 | 161 | Currently, the project focuses on integration testing through real-world usage scenarios. We welcome contributions to improve test coverage: 162 | 163 | #### Manual Testing 164 | 165 | 1. **Basic Functionality**: Test server, client, and master modes with debug logging 166 | 2. **TLS Modes**: Verify all three TLS security levels (0, 1, 2) 167 | 3. **Protocol Support**: Test TCP tunneling and UDP forwarding with various applications 168 | 169 | #### Future Testing Goals 170 | 171 | We encourage contributions in these areas: 172 | - Unit Tests for individual functions and methods 173 | - Integration Tests for component interactions 174 | - Benchmark Tests for performance regression detection 175 | - Fuzzing Tests for security and robustness 176 | - End-to-End Tests for complete workflow validation 177 | 178 | ### Testing Guidelines 179 | 180 | When adding tests: 181 | - Use Go's standard testing package with `*_test.go` naming convention 182 | - Write table-driven tests where applicable 183 | - Include both positive and negative test cases 184 | - Test error conditions and edge cases 185 | - Use meaningful test names that describe the scenario 186 | 187 | ## Documentation 188 | 189 | ### Documentation Standards 190 | 191 | - **Write in clear, simple English** 192 | - **Include practical examples** for all features 193 | - **Maintain both English and Chinese versions** when possible 194 | - **Use consistent formatting** and structure 195 | - **Test all code examples** to ensure they work 196 | 197 | ### Documentation Structure 198 | 199 | - `README.md`: Project overview and quick start 200 | - `docs/en/`: English documentation 201 | - `docs/zh/`: Chinese documentation 202 | - Inline code comments for complex logic 203 | - API documentation for master mode endpoints 204 | 205 | ### Contributing to Documentation 206 | 207 | 1. **Update both language versions** when possible 208 | 2. **Test all examples** before submitting 209 | 3. **Use proper Markdown formatting** 210 | 4. **Include relevant screenshots** for UI components 211 | 5. **Cross-reference related documentation** 212 | 213 | ## Submitting Changes 214 | 215 | ### Pull Request Process 216 | 217 | 1. **Create a feature branch** from the latest `main`: 218 | ```bash 219 | git checkout main 220 | git pull upstream main 221 | git checkout -b feature/your-feature-name 222 | ``` 223 | 224 | 2. **Make your changes** following the guidelines above 225 | 226 | 3. **Test your changes** thoroughly by building the application and running real scenarios 227 | 228 | 4. **Commit your changes** with descriptive messages using [Conventional Commits](https://www.conventionalcommits.org/) format: 229 | - `feat`: New feature 230 | - `fix`: Bug fix 231 | - `docs`: Documentation changes 232 | - `refactor`: Code refactoring 233 | - `perf`: Performance improvements 234 | - `test`: Adding or updating tests 235 | 236 | 5. **Push to your fork** and create a pull request 237 | 238 | ### Commit Message Guidelines 239 | 240 | Use [Conventional Commits](https://www.conventionalcommits.org/) format: 241 | 242 | ``` 243 | [optional scope]: 244 | 245 | [optional body] 246 | 247 | [optional footer(s)] 248 | ``` 249 | 250 | **Examples:** 251 | - `feat(server): add support for IPv6 addresses` 252 | - `fix(client): resolve connection timeout issues in high-latency networks` 253 | - `docs: update installation guide with Docker instructions` 254 | - `refactor(common): simplify address parsing logic` 255 | 256 | ### Pull Request Guidelines 257 | 258 | **Before submitting:** 259 | 260 | - [ ] Code follows the project style guidelines 261 | - [ ] All tests pass (or explain why they should be skipped) 262 | - [ ] Documentation is updated if needed 263 | - [ ] Commit messages follow the conventional format 264 | - [ ] No merge conflicts with the main branch 265 | 266 | **In your pull request:** 267 | 268 | - [ ] Provide a clear description of changes 269 | - [ ] Reference any related issues 270 | - [ ] Include testing instructions 271 | - [ ] Add screenshots for UI changes 272 | - [ ] List any breaking changes 273 | 274 | ### Review Process 275 | 276 | Pull requests go through the following stages: 277 | 278 | 1. **Automated checks** run on all pull requests 279 | 2. **Code review** by project maintainers 280 | 3. **Testing** in various environments 281 | 4. **Documentation review** for user-facing changes 282 | 5. **Final approval** and merge 283 | 284 | ## Community and Support 285 | 286 | ### Communication Channels 287 | 288 | - **GitHub Issues**: Bug reports and feature requests 289 | - **Telegram Channel**: [@NodePassChannel](https://t.me/NodePassChannel) - Updates and announcements 290 | - **Telegram Group**: [@NodePassGroup](https://t.me/NodePassGroup) - Community discussion 291 | - **Discord**: [Join our server](https://discord.gg/2cnXcnDMGc) - Real-time chat 292 | 293 | ### Getting Help 294 | 295 | If you need help: 296 | 297 | 1. **Check the documentation** in the `docs/` directory 298 | 2. **Search existing issues** for similar problems 299 | 3. **Ask in our community channels** for general questions 300 | 4. **Create a GitHub issue** for bugs or feature requests 301 | 302 | ### Recognition 303 | 304 | We appreciate all contributions! Contributors will be: 305 | 306 | - **Listed in our contributors** section 307 | - **Mentioned in release notes** for significant contributions 308 | - **Invited to become maintainers** for consistent, high-quality contributions 309 | 310 | ### Maintainer Responsibilities 311 | 312 | Current maintainers handle: 313 | 314 | - **Code review** and pull request management 315 | - **Release planning** and version management 316 | - **Community management** and support 317 | - **Security** issue handling 318 | - **Roadmap** planning and prioritization 319 | 320 | --- 321 | 322 | Thank you for contributing to NodePass! Your contributions help make universal TCP/UDP tunneling more accessible and reliable for everyone. 323 | 324 | For questions about contributing, please reach out through our community channels or create a GitHub issue. 325 | -------------------------------------------------------------------------------- /docs/zh/troubleshooting.md: -------------------------------------------------------------------------------- 1 | # 故障排除指南 2 | 3 | 本指南帮助您诊断并解决使用NodePass时可能遇到的常见问题。对于每个问题，我们提供可能的原因和逐步解决方案。 4 | 5 | ## 连接问题 6 | 7 | ### 无法建立隧道连接 8 | 9 | **症状**：客户端无法连接到服务器的隧道端点，或连接立即断开。 10 | 11 | **可能的原因和解决方案**： 12 | 13 | 1. **网络连接问题** 14 | - 使用`ping`或`telnet`验证与服务器地址的基本连接 15 | - 检查指定的端口是否可达：`telnet server.example.com 10101` 16 | - 确保没有防火墙阻止隧道端口（通常为10101） 17 | 18 | 2. **服务器未运行** 19 | - 在Linux/macOS上使用`ps aux | grep nodepass`验证NodePass服务器是否运行 20 | - 检查服务器日志中的任何启动错误 21 | - 尝试重启服务器进程 22 | 23 | 3. **地址错误** 24 | - 仔细检查客户端命令中的隧道地址格式 25 | - 确保使用了正确的主机名/IP和端口 26 | - 如果使用DNS名称，验证它们是否解析为正确的IP地址 27 | 28 | 4. **TLS配置不匹配** 29 | - 如果服务器需要TLS但客户端不支持，连接将失败 30 | - 检查服务器日志中的TLS握手错误 31 | - 如果使用TLS模式2，确保证书配置正确 32 | 33 | ### 数据未通过隧道流动 34 | 35 | **症状**：隧道连接已建立，但应用程序数据未到达目的地。 36 | 37 | **可能的原因和解决方案**： 38 | 39 | 1. **目标服务未运行** 40 | - 验证目标服务在服务器和客户端两侧是否运行 41 | - 检查是否可以在本地直接连接到该服务 42 | 43 | 2. **端口冲突** 44 | - 确保目标端口没有被其他应用程序占用 45 | - 使用`netstat -tuln`检查端口使用情况 46 | 47 | 3. **协议不匹配** 48 | - 验证您是否在隧道传输正确的协议（TCP与UDP） 49 | - 某些应用程序需要特定的协议支持 50 | 51 | 4. **目标地址错误** 52 | - 仔细检查服务器和客户端命令中的目标地址 53 | - 对于服务器端目标，确保它们可从服务器访问 54 | - 对于客户端目标，确保它们可从客户端访问 55 | 56 | ### 连接稳定性问题 57 | 58 | **症状**：隧道最初工作但频繁断开或变得无响应。 59 | 60 | **可能的原因和解决方案**： 61 | 62 | 1. **网络不稳定** 63 | - 检查您的网络中是否有数据包丢失或高延迟 64 | - 考虑为生产部署使用更稳定的网络连接 65 | 66 | 2. **资源限制** 67 | - 监控客户端和服务器的CPU和内存使用情况 68 | - 如果资源耗尽，调整池参数（参见性能部分） 69 | - 在Linux/macOS上使用`ulimit -n`检查文件描述符限制 70 | 71 | 3. **超时配置** 72 | - 如果使用具有慢响应时间的UDP，调整`NP_UDP_DIAL_TIMEOUT` 73 | - 增加URL中的`read`参数用于长时间传输（默认：0） 74 | - 考虑为不稳定网络条件调整`NP_TCP_DIAL_TIMEOUT` 75 | 76 | 4. **服务器过载** 77 | - 检查服务器日志中的连接过载迹象 78 | - 调整`max`参数和`NP_SEMAPHORE_LIMIT`以处理负载 79 | - 考虑用多个NodePass实例水平扩展 80 | 81 | ## 证书问题 82 | 83 | ### TLS握手失败 84 | 85 | **症状**：连接尝试因TLS握手错误而失败。 86 | 87 | **可能的原因和解决方案**： 88 | 89 | 1. **无效证书** 90 | - 验证证书有效性：`openssl x509 -in cert.pem -text -noout` 91 | - 确保证书没有过期 92 | - 检查证书是否针对正确的域名/IP颁发 93 | 94 | 2. **证书文件丢失或无法访问** 95 | - 确认证书和密钥的文件路径正确 96 | - 验证文件权限允许NodePass进程读取它们 97 | - 通过文本编辑器打开证书检查文件是否损坏 98 | 99 | 3. **证书信任问题** 100 | - 如果使用自定义CA，确保它们被正确信任 101 | - 对于自签名证书，确认使用TLS模式1 102 | - 对于验证证书，确保CA链完整 103 | 104 | 4. **密钥格式问题** 105 | - 确保私钥格式正确（通常为PEM） 106 | - 检查私钥是否有密码保护（不直接支持） 107 | 108 | ### 证书更新问题 109 | 110 | **症状**：证书更新后，安全连接开始失败。 111 | 112 | **可能的原因和解决方案**： 113 | 114 | 1. **新证书未加载** 115 | - 重启NodePass强制加载新证书 116 | - 检查`RELOAD_INTERVAL`是否设置正确以自动检测变更 117 | 118 | 2. **证书链不完整** 119 | - 确保证书文件中包含完整的证书链 120 | - 验证链顺序：首先是您的证书，然后是中间证书 121 | 122 | 3. **密钥不匹配** 123 | - 验证新证书是否与私钥匹配： 124 | ```bash 125 | openssl x509 -noout -modulus -in cert.pem | openssl md5 126 | openssl rsa -noout -modulus -in key.pem | openssl md5 127 | ``` 128 | - 如果输出不同，证书和密钥不匹配 129 | 130 | ## 性能优化 131 | 132 | ### 高延迟 133 | 134 | **症状**：连接工作但有明显延迟。 135 | 136 | **可能的原因和解决方案**： 137 | 138 | 1. **池配置** 139 | - 增加`min`参数以准备更多连接 140 | - 减少`MIN_POOL_INTERVAL`以更快创建连接 141 | - 如果连接队列堆积，调整`NP_SEMAPHORE_LIMIT` 142 | 143 | 2. **网络路径** 144 | - 检查网络拥塞或高延迟链路 145 | - 考虑将NodePass部署在更靠近客户端或服务器的位置 146 | - 使用traceroute识别潜在瓶颈 147 | 148 | 3. **TLS开销** 149 | - 如果需要极低延迟且安全性不太重要，考虑使用TLS模式0 150 | - 为了平衡，使用带会话恢复的TLS模式1 151 | 152 | 4. **资源竞争** 153 | - 确保主机系统有足够的CPU和内存 154 | - 检查是否有其他进程竞争资源 155 | - 考虑为高流量部署使用专用主机 156 | 157 | ### CPU使用率高 158 | 159 | **症状**：NodePass进程消耗过多CPU资源。 160 | 161 | **可能的原因和解决方案**： 162 | 163 | 1. **池抖动** 164 | - 如果池不断创建和销毁连接，调整时间 165 | - 增加`MIN_POOL_INTERVAL`以减少连接创建频率 166 | - 为`min`和`max`连接池参数找到良好平衡 167 | 168 | 2. **过度日志记录** 169 | - 在生产环境中将日志级别从debug降低到info或warn 170 | - 检查日志是否写入缓慢设备 171 | 172 | 3. **TLS开销** 173 | - TLS握手需要大量CPU；考虑会话缓存 174 | - 如果证书验证不太重要，使用TLS模式1而不是模式2 175 | 176 | 4. **流量体积** 177 | - 高吞吐量可能导致CPU饱和 178 | - 考虑跨多个NodePass实例分配流量 179 | - 对于非常高的吞吐量，可能需要垂直扩展（更多CPU核心） 180 | 181 | ### 内存泄漏 182 | 183 | **症状**：NodePass内存使用随时间持续增长。 184 | 185 | **可能的原因和解决方案**： 186 | 187 | 1. **连接泄漏** 188 | - 确保`NP_SHUTDOWN_TIMEOUT`足够长以正确关闭连接 189 | - 检查自定义脚本或管理代码中的错误处理 190 | - 使用系统工具如`netstat`监控连接数量 191 | 192 | 2. **池大小问题** 193 | - 如果`max`参数非常大，内存使用会更高 194 | - 监控实际池使用情况与配置容量 195 | - 根据实际并发连接需求调整容量 196 | 197 | 3. **调试日志** 198 | - 在高流量场景中，大量调试日志可能消耗内存 199 | - 在生产环境中使用适当的日志级别 200 | 201 | ## UDP特定问题 202 | 203 | ### UDP数据丢失 204 | 205 | **症状**：UDP数据包无法通过隧道可靠转发。 206 | 207 | **可能的原因和解决方案**： 208 | 209 | 1. **缓冲区大小限制** 210 | - 如果UDP数据包较大，增加`UDP_DATA_BUF_SIZE` 211 | - 默认8192字节对某些应用程序可能太小 212 | 213 | 2. **超时问题** 214 | - 如果响应较慢，增加`NP_UDP_DIAL_TIMEOUT` 215 | - 调整`read`参数以获得更长的会话超时 216 | - 对于响应时间变化的应用程序，找到最佳平衡点 217 | 218 | 3. **高数据包率** 219 | - UDP一次处理一个数据报；非常高的速率可能导致问题 220 | - 考虑为高流量UDP应用增加池容量 221 | 222 | 4. **协议期望** 223 | - 一些UDP应用期望特定的数据包顺序或时序行为 224 | - NodePass提供尽力转发，但无法保证超出网络提供的UDP属性 225 | 226 | ### UDP连接跟踪 227 | 228 | **症状**：UDP会话过早断开或无法建立。 229 | 230 | **可能的原因和解决方案**： 231 | 232 | 1. **连接映射** 233 | - 验证客户端配置是否符合服务器期望 234 | - 检查防火墙是否超时UDP会话跟踪 235 | 236 | 2. **应用UDP超时** 237 | - 一些应用有内置UDP会话超时 238 | - 可能需要调整应用特定的keepalive设置 239 | 240 | ## DNS问题 241 | 242 | ### DNS解析失败 243 | 244 | **症状**：连接失败，显示"no such host"或DNS查找错误。 245 | 246 | **解决方案**： 247 | 248 | 1. **验证系统DNS配置** 249 | - 验证解析功能：`nslookup example.com` 250 | - 检查系统的DNS设置（NodePass使用系统解析器） 251 | - 确保网络连接正常工作 252 | 253 | 2. **网络连接问题** 254 | - 检查防火墙是否阻止UDP端口53 255 | - 验证域名可达性 256 | - 使用其他域名测试以隔离问题 257 | 258 | ### DNS缓存问题 259 | 260 | **症状**：解析返回过期IP，连接到错误端点。 261 | 262 | **解决方案**： 263 | 264 | 1. **调整缓存TTL**（默认5分钟） 265 | - 动态环境：`dns=1m` 266 | - 稳定环境：`dns=30m` 267 | 268 | 2. **负载均衡场景** 269 | - 使用较短TTL：`dns=30s` 270 | - 或直接使用IP地址避免DNS缓存 271 | 272 | ### DNS性能优化 273 | 274 | **症状**：连接延迟高，启动缓慢。 275 | 276 | **解决方案**： 277 | 278 | 1. **优化缓存TTL** 279 | - 稳定环境增加TTL：`dns=1h` 280 | - 动态环境减少TTL：`dns=1m` 281 | - 在新鲜度和性能之间取得平衡 282 | 283 | 2. **减少DNS查询** 284 | - 性能关键场景直接使用IP地址 285 | - 为稳定主机名增加TTL 286 | - 尽可能预解析地址 287 | 288 | ## 主控API问题 289 | 290 | ### API可访问性问题 291 | 292 | **症状**：无法连接到主控API端点。 293 | 294 | **可能的原因和解决方案**： 295 | 296 | 1. **端点配置** 297 | - 验证主控命令中的API地址和端口 298 | - 检查API服务器是否绑定到正确的网络接口 299 | 300 | 2. **TLS配置** 301 | - 如果使用HTTPS（TLS模式1或2），确保客户端工具支持TLS 302 | - 对于测试，使用`curl -k`跳过证书验证 303 | 304 | 3. **自定义前缀问题** 305 | - 如果使用自定义API前缀，确保所有请求中都包含它 306 | - 检查API客户端和脚本中的URL格式 307 | 308 | ### 实例管理失败 309 | 310 | **症状**：无法通过API创建、控制或删除实例。 311 | 312 | **可能的原因和解决方案**： 313 | 314 | 1. **JSON格式问题** 315 | - 验证请求体是有效的JSON 316 | - 检查API请求中的必填字段 317 | 318 | 2. **URL解析问题** 319 | - 确保实例URL格式正确，必要时进行URL编码 320 | - 验证URL参数使用正确格式 321 | 322 | 3. **实例状态冲突** 323 | - 无法删除运行中的实例，必须先停止 324 | - 在执行操作前先用GET检查当前实例状态 325 | 326 | 4. **权限问题** 327 | - 确保NodePass主控具有创建进程的足够权限 328 | - 检查任何引用的证书或密钥的文件系统权限 329 | 330 | ## 数据恢复 331 | 332 | ### 主控状态文件损坏 333 | 334 | **症状**：主控模式启动失败，显示状态文件损坏错误，或实例数据丢失。 335 | 336 | **可能的原因和解决方案**： 337 | 338 | 1. **使用自动备份文件恢复** 339 | - NodePass每小时自动创建备份文件 `nodepass.gob.backup` 340 | - 停止NodePass主控服务 341 | - 将备份文件复制为主文件：`cp nodepass.gob.backup nodepass.gob` 342 | - 重新启动主控服务 343 | 344 | 2. **手动状态文件恢复** 345 | ```bash 346 | # 停止NodePass服务 347 | pkill nodepass 348 | 349 | # 备份损坏的文件（可选） 350 | mv nodepass.gob nodepass.gob.corrupted 351 | 352 | # 使用备份文件 353 | cp nodepass.gob.backup nodepass.gob 354 | 355 | # 重新启动服务 356 | nodepass "master://0.0.0.0:9090?log=info" 357 | ``` 358 | 359 | 3. **备份文件也损坏时** 360 | - 删除损坏的状态文件：`rm nodepass.gob*` 361 | - 重新启动主控，将创建新的状态文件 362 | - 需要重新配置所有实例和设置 363 | 364 | 4. **预防性备份建议** 365 | - 定期备份 `nodepass.gob` 到外部存储 366 | - 调整备份频率：设置环境变量 `export NP_RELOAD_INTERVAL=30m` 367 | - 监控状态文件大小，异常增长可能表示问题 368 | 369 | **最佳实践**： 370 | - 在生产环境中，建议将 `nodepass.gob` 定期备份到不同的存储位置 371 | - 使用配置管理工具保存实例配置的文本形式备份 372 | 373 | ## 连接池类型问题 374 | 375 | ### QUIC连接池连接失败 376 | 377 | **症状**：启用`type=1`时QUIC连接池隧道无法建立。 378 | 379 | **可能的原因和解决方案**： 380 | 381 | 1. **UDP端口被阻止** 382 | - 验证服务器和客户端的UDP端口可访问 383 | - 检查防火墙规则：`sudo ufw allow 10101/udp`（Linux示例） 384 | - 使用`nc -u server.example.com 10101`测试UDP连接性 385 | - 某些ISP或网络会阻止或限制UDP流量 386 | 387 | 2. **TLS配置问题** 388 | - QUIC需要启用TLS（至少`tls=1`） 389 | - 如果设置了`type=1`但禁用TLS，系统会自动启用`tls=1` 390 | - 生产环境使用`tls=2`和有效证书 391 | - 检查QUIC连接的证书有效性 392 | 393 | 3. **客户端-服务器连接池类型不匹配** 394 | - 服务器和客户端必须使用相同的`type`设置 395 | - 带`type=1`的服务器需要带`type=1`的客户端 396 | - 带`type=0`的服务器需要带`type=0`的客户端 397 | - 检查日志中的"QUIC connection not available"错误 398 | 399 | 4. **模式兼容性** 400 | - QUIC仅在双端握手模式（mode=2）下工作 401 | - 单端转发模式（mode=1）不可用 402 | - 如果模式不兼容，系统将回退到TCP连接池 403 | 404 | ### WebSocket连接池连接失败 405 | 406 | **症状**：启用`type=2`时WebSocket连接池隧道无法建立。 407 | 408 | **可能的原因和解决方案**： 409 | 410 | 1. **HTTP/WebSocket端口被阻止** 411 | - 验证TCP端口支持WebSocket协议访问 412 | - 检查防火墙规则和代理配置 413 | - 某些代理或CDN可能干扰WebSocket升级 414 | - 使用WebSocket客户端工具测试连接性 415 | 416 | 2. **TLS配置问题** 417 | - WebSocket Secure（WSS）需要启用TLS（至少`tls=1`） 418 | - **WebSocket连接池不支持不加密模式** - type=2不允许使用tls=0 419 | - 如果设置了`type=2`但禁用TLS，系统将自动强制使用`tls=1` 420 | - 生产环境使用`tls=2`和有效证书 421 | - 检查WSS连接的证书有效性 422 | 423 | 3. **客户端-服务器连接池类型不匹配** 424 | - 服务器和客户端必须使用相同的`type`设置 425 | - 带`type=2`的服务器需要带`type=2`的客户端 426 | - 配置在握手时自动下发 427 | - 检查日志中的"WebSocket connection not available"错误 428 | 429 | ### HTTP/2连接池连接失败 430 | 431 | **症状**：启用`type=3`时HTTP/2连接池隧道无法建立。 432 | 433 | **可能的原因和解决方案**： 434 | 435 | 1. **TCP端口或HTTP/2协议被阻止** 436 | - 验证TCP端口支持HTTP/2协议访问 437 | - 检查防火墙规则和网络策略 438 | - 某些网络可能阻止或检查HTTPS流量 439 | - 使用支持HTTP/2的客户端工具测试连接性 440 | 441 | 2. **TLS配置问题** 442 | - HTTP/2需要启用TLS（至少`tls=1`） 443 | - 如果设置了`type=3`但禁用TLS，系统将自动强制使用`tls=1` 444 | - 生产环境使用`tls=2`和有效证书 445 | - HTTP/2需要TLS 1.3且支持ALPN（应用层协议协商） 446 | - 检查证书有效性和ALPN配置 447 | 448 | 3. **客户端-服务器连接池类型不匹配** 449 | - 服务器和客户端必须使用相同的`type`设置 450 | - 带`type=3`的服务器需要带`type=3`的客户端 451 | - 配置在握手时自动下发 452 | - 检查日志中的"HTTP/2 connection not available"错误 453 | 454 | 4. **模式兼容性** 455 | - HTTP/2连接池仅在双端握手模式（mode=2）下工作 456 | - 单端转发模式（mode=1）不可用 457 | - 如果模式不兼容，系统将回退到TCP连接池 458 | 459 | 5. **HTTP/2协议协商失败** 460 | - 验证ALPN扩展已启用并协商"h2"协议 461 | - 某些较旧的TLS实现可能不支持ALPN 462 | - 检查日志中的协议协商错误 463 | - 确保两端都支持基于TLS的HTTP/2 464 | 465 | ### QUIC连接池性能问题 466 | 467 | **症状**：QUIC连接池隧道性能低于预期或不如TCP连接池。 468 | 469 | **可能的原因和解决方案**： 470 | 471 | 1. **网络路径问题** 472 | - 某些网络会降低UDP流量的优先级或进行流量整形 473 | - 检查网络中间设备是否干扰QUIC 474 | - 考虑使用TCP连接池（`type=0`）进行对比测试 475 | - 监控丢包率 - QUIC在低丢包率下性能更好 476 | 477 | 2. **连接池容量配置** 478 | - 增加`min`和`max`参数以获得更高吞吐量 479 | - QUIC流共享单个UDP连接 - 需要足够容量 480 | - 使用`log=debug`监控流利用率 481 | - 在流数量和资源使用之间取得平衡 482 | 483 | 3. **证书开销** 484 | - TLS 1.3握手（QUIC强制要求）可能增加初始延迟 485 | - 使用0-RTT恢复实现更快重连 486 | - 确保正确的证书链以避免验证延迟 487 | 488 | 4. **应用兼容性** 489 | - 某些应用程序在QUIC流上可能无法达到最佳性能 490 | - 使用TCP和QUIC连接池进行对比测试 491 | - 对于需要严格顺序的应用考虑使用TCP连接池 492 | 493 | ### WebSocket连接池性能问题 494 | 495 | **症状**：WebSocket连接池隧道性能低于预期。 496 | 497 | **可能的原因和解决方案**： 498 | 499 | 1. **代理/CDN开销** 500 | - 通过代理的WebSocket连接可能增加延迟 501 | - 检查中间代理是否缓冲流量 502 | - 考虑使用TCP连接池（`type=0`）或QUIC连接池（`type=1`）进行对比测试 503 | - 直接连接通常比代理连接性能更好 504 | 505 | 2. **帧开销** 506 | - WebSocket协议为每条消息添加帧开销 507 | - 较大的消息大小减少相对开销 508 | - 监控帧大小并根据需要调整应用行为 509 | - 在延迟和吞吐量之间取得平衡 510 | 511 | 3. **TLS握手开销** 512 | - WSS需要为每个连接进行TLS握手 513 | - 使用连接池来分摊握手成本 514 | - 增加`min`和`max`参数以获得更好的性能 515 | 516 | ### QUIC流耗尽 517 | 518 | **症状**：使用QUIC时出现"流不足"错误或连接超时。 519 | 520 | **可能的原因和解决方案**： 521 | 522 | 1. **连接池容量过低** 523 | - 增加服务器端的`max`参数 524 | - 增加客户端的`min`参数 525 | - 在日志中监控活动流数量 526 | - 默认容量对于高并发场景可能不足 527 | 528 | 2. **流泄漏** 529 | - 检查应用是否正确关闭连接 530 | - 监控流数量随时间的逐渐增长 531 | - 重启实例以清除泄漏的流 532 | - 检查应用代码的连接处理 533 | 534 | 3. **QUIC连接断开** 535 | - 检查保活设置（通过`NP_REPORT_INTERVAL`配置） 536 | - 监控"QUIC connection not available"错误 537 | - NAT超时可能断开UDP连接 - 调整NAT设置 538 | - 如果网络延迟高，增加连接超时 539 | 540 | ### 连接池类型选择 541 | 542 | **何时使用QUIC连接池**（`type=1`）： 543 | - 移动网络或频繁变化的网络条件 544 | - 高延迟连接（卫星、长距离） 545 | - NAT密集环境，UDP穿透性能更好 546 | - 受益于流独立性的实时应用 547 | - 0-RTT重连提供价值的场景 548 | 549 | **何时使用WebSocket连接池**（`type=2`）： 550 | - 需要穿透HTTP代理或CDN的场景 551 | - 企业环境中仅允许HTTP/HTTPS流量 552 | - 防火墙阻止原始TCP连接的环境 553 | - 需要与现有网络基础设施兼容 554 | - Web代理或VPN替代方案 555 | 556 | **何时使用TCP连接池**（`type=0`）： 557 | - 阻止或严重限制UDP流量的网络 558 | - 需要严格TCP语义的应用 559 | - 具有UDP限制的企业环境 560 | - 最大兼容性要求 561 | - 测试显示TCP性能更好时 562 | 563 | **对比测试**： 564 | ```bash 565 | # 测试TCP连接池性能 566 | nodepass "server://0.0.0.0:10101/backend:8080?type=0&mode=2&log=event" 567 | nodepass "client://server:10101/127.0.0.1:8080?mode=2&log=event" 568 | 569 | # 测试QUIC连接池性能 570 | nodepass "server://0.0.0.0:10102/backend:8080?type=1&mode=2&log=event" 571 | nodepass "client://server:10102/127.0.0.1:8081?mode=2&log=event" 572 | 573 | # 测试WebSocket连接池性能 574 | nodepass "server://0.0.0.0:10103/backend:8080?type=2&mode=2&log=event" 575 | nodepass "client://server:10103/127.0.0.1:8082?mode=2&log=event" 576 | ``` 577 | 578 | 监控流量统计并根据观察到的性能进行选择。 579 | 580 | ## 下一步 581 | 582 | 如果您遇到本指南未涵盖的问题： 583 | 584 | - 查看[项目仓库](https://github.com/yosebyte/nodepass)中的已知问题 585 | - 将日志级别增加到`debug`以获取更详细信息 586 | - 查看[工作原理](/docs/zh/how-it-works.md)部分以更好地理解内部机制 587 | - 考虑加入社区讨论，从其他用户处获取帮助 -------------------------------------------------------------------------------- /docs/zh/how-it-works.md: -------------------------------------------------------------------------------- 1 | # NodePass 工作原理 2 | 3 | 本页解释了 NodePass 的内部架构和数据流机制，提供了不同组件如何交互以创建高效、安全的隧道的深入见解。 4 | 5 | ## 架构概述 6 | 7 | NodePass 创建了一个具有独立控制和数据通道的网络架构： 8 | 9 | 1. **控制通道（隧道）**： 10 | - 客户端和服务器之间的未加密 TCP 连接 11 | - 专门用于信号传输和协调 12 | - 在隧道生命周期内维持持久连接 13 | 14 | 2. **数据通道（目标）**： 15 | - 可配置的 TLS 加密选项： 16 | - **模式 0**：未加密数据传输（最快，安全性最低） 17 | - **模式 1**：自签名证书加密（良好安全性，无验证） 18 | - **模式 2**：验证证书加密（最高安全性，需要有效证书） 19 | - 按需为每个连接或数据报创建 20 | - 用于实际应用数据传输 21 | 22 | 3. **服务端模式操作**： 23 | - 在隧道端点监听控制连接 24 | - 当流量到达目标端点时，通过控制通道向客户端发送信号 25 | - 在需要时使用指定的 TLS 模式建立数据通道 26 | - 支持双向数据流：可以从服务端或客户端发起连接 27 | 28 | 4. **客户端模式操作**： 29 | - 连接到服务端的控制通道 30 | - **握手阶段**：服务端验证隧道密钥后，向客户端下发配置信息： 31 | - 数据流向模式（决定客户端接收或发送流量） 32 | - 最大连接池容量（由服务端统一管理和分配） 33 | - TLS安全级别（确保客户端使用正确的加密模式） 34 | - 监听指示传入连接的信号 35 | - 使用服务端指定的 TLS 安全级别创建数据连接 36 | - 在安全通道和本地目标之间转发数据 37 | - 支持双向数据流：根据目标地址自动选择数据流方向 38 | 39 | 5. **客户端单端转发模式**： 40 | - 当隧道地址为本地地址时（如127.0.0.1）自动启用 41 | - 客户端直接在本地监听端口，无需服务端的控制通道协调 42 | - 对于TCP和UDP协议使用直接连接建立方式 43 | - 适用于纯本地转发场景，减少网络开销和延迟 44 | - 支持TCP和UDP协议的高性能单端转发，采用优化的连接处理 45 | 46 | 5. **协议支持**： 47 | - **TCP**：具有持久连接的全双工流式传输，在客户端单端转发模式下优化了直接连接建立 48 | - **UDP**：具有可配置缓冲区大小和超时的数据报转发 49 | 50 | ## 数据传输流 51 | 52 | NodePass 通过其隧道架构建立双向数据流，支持 TCP 和 UDP 协议。系统支持三种数据流模式： 53 | 54 | ### 数据流模式说明 55 | - **服务端接收模式**：服务端在目标地址监听，客户端在本地监听，数据从目标地址流向客户端本地 56 | - **服务端发送模式**：服务端连接到远程目标地址，客户端在本地监听，数据从客户端本地流向远程目标 57 | - **客户端单端转发模式**：客户端在本地直接监听并转发到目标地址，无需服务端协调，使用直接连接建立实现优化转发 58 | 59 | 数据流模式根据隧道地址和目标地址自动确定： 60 | - 如果隧道地址是本地地址（localhost、127.0.0.1等），启用客户端单端转发模式 61 | - 如果目标地址是本地地址，使用服务端接收模式 62 | - 如果目标地址是远程地址，使用服务端发送模式 63 | 64 | ### 服务端流程（服务端接收模式） 65 | 1. **连接初始化**： 66 | ``` 67 | [目标客户端] → [目标监听器] → [服务器：目标连接已创建] 68 | ``` 69 | - 对于 TCP：客户端建立到目标监听器的持久连接 70 | - 对于 UDP：服务器在绑定到目标地址的 UDP 套接字上接收数据报 71 | 72 | 2. **信号生成**： 73 | ``` 74 | [服务端] → [生成唯一连接 ID] → [通过未加密的 TCP 隧道向客户端发送信号] 75 | ``` 76 | - 对于 TCP：生成 `//#1` 信号 77 | - 对于 UDP：生成 `//#2` 信号 78 | 79 | 3. **连接准备**： 80 | ``` 81 | [服务端] → [在池中创建具有配置的 TLS 模式的远程连接] → [等待客户端连接] 82 | ``` 83 | - 两种协议都使用相同的具有唯一连接 ID 的连接池机制 84 | - 根据指定模式（0、1 或 2）应用 TLS 配置 85 | 86 | 4. **数据交换**： 87 | ``` 88 | [目标连接] ⟷ [交换/传输] ⟷ [远程连接] 89 | ``` 90 | - 对于 TCP：使用 `conn.DataExchange()` 进行持续的双向数据流传输 91 | - 对于 UDP：使用可配置的缓冲区大小转发单个数据报 92 | 93 | ### 客户端流程 94 | 1. **信号接收**： 95 | ``` 96 | [客户端] → [从 TCP 隧道读取信号] → [解析连接 ID] 97 | ``` 98 | - 客户端根据 URL 方案区分 TCP 和 UDP 信号 99 | 100 | 2. **连接建立**： 101 | ``` 102 | [客户端] → [从池中检索连接] → [连接到远程端点] 103 | ``` 104 | - 此阶段的连接管理与协议无关 105 | 106 | 3. **本地连接**： 107 | ``` 108 | [客户端] → [连接到本地目标] → [建立本地连接] 109 | ``` 110 | - 对于 TCP：建立到本地目标的持久 TCP 连接 111 | - 对于 UDP：创建用于与本地目标交换数据报的 UDP 套接字 112 | 113 | 4. **数据交换**： 114 | ``` 115 | [远程连接] ⟷ [交换/传输] ⟷ [本地目标连接] 116 | ``` 117 | - 对于 TCP：使用 `conn.DataExchange()` 进行持续的双向数据流传输 118 | - 对于 UDP：读取单个数据报，转发它，使用超时等待响应，然后返回响应 119 | 120 | ### 客户端单端转发流程 121 | 1. **模式识别**： 122 | ``` 123 | [客户端] → [检测隧道地址为本地地址] → [启用单端转发模式] 124 | ``` 125 | - 自动检测隧道地址是否为localhost、127.0.0.1等本地地址 126 | - 启用单端转发模式，跳过服务端控制通道建立 127 | 128 | 2. **本地监听**： 129 | ``` 130 | [客户端] → [在隧道端口启动监听器] → [等待本地连接] 131 | ``` 132 | - 直接在指定的隧道端口启动TCP或UDP监听器 133 | - 无需连接到远程服务端，实现零延迟启动 134 | 135 | 3. **直接连接建立**： 136 | ``` 137 | [客户端] → [创建到目标地址的直接连接] → [建立目标连接] 138 | ``` 139 | - 对于TCP：为每个隧道连接直接建立到目标地址的TCP连接 140 | - 对于UDP：创建用于与目标地址交换数据报的UDP套接字 141 | - 消除连接池开销，提供更简单、更直接的转发路径 142 | 143 | 4. **优化转发**： 144 | ``` 145 | [本地连接] → [直接目标连接] → [数据交换] → [连接清理] 146 | ``` 147 | - 对于TCP：直接连接建立后进行高效数据交换 148 | - 对于UDP：直接转发数据报到目标地址，延迟最小 149 | - 简化的数据路径，确保可靠高效的转发 150 | 151 | ### 特定协议特性 152 | - **TCP 交换**： 153 | - 用于全双工通信的持久连接 154 | - 连接终止前的持续数据流传输 155 | - 具有自动重连的错误处理 156 | - **客户端单端转发优化**：为每个隧道连接直接建立连接，确保可靠高效的转发 157 | 158 | - **UDP 交换**： 159 | - 具有可配置缓冲区大小的一次性数据报转发 (`UDP_DATA_BUF_SIZE`) 160 | - 响应等待的读取超时控制 (`read`参数或默认0) 161 | - 针对低延迟、无状态通信进行了优化 162 | - **客户端单端转发优化**：直接转发机制，实现最低延迟 163 | 164 | ## 信号通信机制 165 | 166 | NodePass 通过 TCP 隧道使用复杂的基于 URL 的信号协议： 167 | 168 | ### 信号类型 169 | 1. **隧道信号**： 170 | - 格式：`#` 171 | - 目的：通知客户端 TLS 代号 172 | - 时机：在隧道握手时发送 173 | 174 | 2. **TCP 启动信号**： 175 | - 格式：`//#1` 176 | - 目的：请求客户端为特定 ID 建立 TCP 连接 177 | - 时机：当接收到目标服务的新 TCP 连接时发送 178 | 179 | 3. **UDP 启动信号**： 180 | - 格式：`//#2` 181 | - 目的：请求客户端处理特定 ID 的 UDP 流量 182 | - 时机：当在目标端口接收到 UDP 数据时发送 183 | 184 | ### 信号流程 185 | 1. **信号生成**： 186 | - 服务端为特定事件创建 URL 格式的信号 187 | - 信号以换行符终止，以便正确解析 188 | 189 | 2. **信号传输**： 190 | - 服务端将信号写入 TCP 隧道连接 191 | - 使用互斥锁防止对隧道的并发写入 192 | 193 | 3. **信号接收**： 194 | - 客户端使用缓冲读取器从隧道读取信号 195 | - 信号被修剪并解析为 URL 格式 196 | 197 | 4. **信号处理**： 198 | - 客户端将有效信号放入缓冲通道 (signalChan) 199 | - 专用 goroutine 处理来自通道的信号 200 | - 信号量模式防止信号溢出 201 | 202 | 5. **信号执行**： 203 | - 远程信号更新客户端的远程地址配置 204 | - 启动信号触发 `clientOnce()` 方法建立连接 205 | 206 | ### 信号弹性 207 | - 具有可配置容量的缓冲通道防止在高负载下信号丢失 208 | - 信号量实现确保受控并发 209 | - 对格式错误或意外信号的错误处理 210 | 211 | ## 连接池架构 212 | 213 | NodePass 实现了一个高效的连接池系统来管理网络连接，这是其性能优势的核心设计。NodePass支持三种连接池传输协议：传统的基于TCP的连接池、现代的基于QUIC的UDP连接池和基于WebSocket的连接池。 214 | 215 | ### 传输协议选择 216 | 217 | NodePass通过`type`参数提供三种连接池传输选项： 218 | 219 | 1. **基于TCP的连接池 (type=0, 默认)**： 220 | - 由`pool`库管理的传统TCP连接 221 | - 客户端和服务器之间的多个独立TCP连接 222 | - 在单独的TCP连接上进行标准TLS加密 223 | - 经过充分测试且广泛兼容的方法 224 | 225 | 2. **基于QUIC的连接池 (type=1)**： 226 | - 由`quic`库管理的基于UDP的多路复用流 227 | - 单个QUIC连接承载多个并发流 228 | - 强制使用TLS 1.3加密并支持0-RTT 229 | - 在高延迟和移动网络中性能优越 230 | 231 | 3. **基于WebSocket的连接池 (type=2)**： 232 | - 通过HTTP升级建立的WebSocket连接 233 | - 可以穿透HTTP代理和CDN 234 | - 使用标准HTTPS端口 235 | - 适合企业环境和防火墙限制场景 236 | 237 | ### QUIC连接池架构 238 | 239 | 当启用`type=1`时，NodePass使用QUIC协议进行连接池管理，具有以下特性： 240 | 241 | **流多路复用**： 242 | - 单个UDP连接承载多个双向流 243 | - 每个流代表一个独立的隧道连接 244 | - 流是独立的：一个流的丢包不影响其他流 245 | - 流级别的流量控制防止队头阻塞 246 | 247 | **连接建立**： 248 | - 服务器监听UDP端口并接受QUIC连接 249 | - 客户端与服务器建立单个QUIC连接 250 | - 服务器为每个传入连接生成唯一的流ID 251 | - 客户端使用提供的流ID按需打开新流 252 | 253 | **流生命周期**： 254 | 1. **流创建**（服务器端）： 255 | - 服务器接受来自授权客户端的新QUIC连接 256 | - 对于每个目标连接，服务器打开双向流 257 | - 服务器生成4字节随机流ID 258 | - 流ID发送给客户端用于关联 259 | 260 | 2. **流检索**（客户端）： 261 | - 客户端通过控制通道信号接收流ID 262 | - 客户端从QUIC连接中检索相应的流 263 | - 流被包装为`net.Conn`以保持兼容性 264 | - 流用于与目标端点进行数据交换 265 | 266 | 3. **流终止**： 267 | - 数据交换完成后关闭流 268 | - 优雅关闭并正确清理 269 | - QUIC连接保持活跃以供未来的流使用 270 | 271 | **动态管理**： 272 | - 基于流创建成功率调整连接池容量 273 | - 流创建间隔根据连接池利用率自适应 274 | - 在最小/最大边界内自动流容量扩缩 275 | - 保活机制维护QUIC连接健康 276 | 277 | **安全特性**： 278 | - 所有QUIC连接强制使用TLS 1.3加密 279 | - 支持三种TLS模式： 280 | - 模式0/1：InsecureSkipVerify用于测试/开发 281 | - 模式2：生产环境完整证书验证 282 | - 服务器端可用客户端IP限制 283 | - ALPN协议协商（"np-quic"） 284 | 285 | **性能优势**： 286 | - 减少连接开销：所有流使用单个UDP套接字 287 | - 0-RTT连接恢复实现更快重连 288 | - 具有流级别优先级的更好拥塞控制 289 | - 与多个TCP连接相比改善NAT穿透 290 | - 在丢包场景中降低延迟（无队头阻塞） 291 | 292 | ### WebSocket连接池架构 293 | 294 | 当启用`type=2`时，NodePass使用WebSocket协议进行连接池管理，具有以下特性： 295 | 296 | **HTTP升级机制**： 297 | - 通过标准HTTP升级请求建立WebSocket连接 298 | - 兼容HTTP/1.1代理和CDN 299 | - 使用标准的80（ws）或443（wss）端口 300 | - 支持自定义HTTP头部用于身份验证和路由 301 | 302 | **连接建立**： 303 | - 服务器在TCP端口上监听HTTP请求 304 | - 客户端发起HTTP升级请求到WebSocket 305 | - 握手完成后，连接升级为全双工WebSocket 306 | - 服务器为每个传入连接分配唯一的连接ID 307 | 308 | **连接生命周期**： 309 | 1. **连接创建**（服务器端）： 310 | - 服务器接受来自授权客户端的HTTP升级请求 311 | - 验证WebSocket握手参数（Origin、协议等） 312 | - 升级连接并将其添加到连接池 313 | - 生成连接ID发送给客户端用于关联 314 | 315 | 2. **连接检索**（客户端）： 316 | - 客户端通过控制通道接收连接ID 317 | - 客户端从WebSocket连接池中检索对应连接 318 | - 连接被包装为`net.Conn`以保持兼容性 319 | - 连接用于与目标端点进行数据交换 320 | 321 | 3. **连接终止**： 322 | - 数据交换完成后发送WebSocket关闭帧 323 | - 优雅关闭并正确清理底层TCP连接 324 | - 支持关闭原因码和描述信息 325 | 326 | **动态管理**： 327 | - 基于连接创建成功率调整连接池容量 328 | - 连接创建间隔根据连接池利用率自适应 329 | - 在最小/最大边界内自动连接容量扩缩 330 | - Ping/Pong帧维护连接健康状态 331 | 332 | **安全特性**： 333 | - 支持WSS（WebSocket Secure）通过TLS加密 334 | - WebSocket连接池需要启用TLS加密 335 | - 两种TLS模式支持： 336 | - 模式1：自签名证书的WSS 337 | - 模式2：生产环境完整证书验证的WSS 338 | - Origin验证防止跨站WebSocket劫持 339 | - 支持自定义身份验证头部 340 | 341 | **穿透优势**： 342 | - 使用标准HTTP/HTTPS端口，易于穿透防火墙 343 | - 兼容企业HTTP代理和负载均衡器 344 | - 可通过CDN和反向代理部署 345 | - 与HTTP流量混合，降低检测和封锁风险 346 | - 需要启用TLS加密以确保安全 347 | 348 | ### 设计哲学 349 | 连接池的设计遵循"预热优于冷启动"的原则，通过预先建立连接消除网络延迟。这种设计理念借鉴了现代高性能服务器的最佳实践，将连接建立的成本分摊到系统启动阶段，而非在关键路径上承担这一开销。 350 | 351 | 三种连接池类型共享这一理念，但实现方式不同： 352 | - **TCP连接池**：预先建立多个独立TCP连接 353 | - **QUIC连接池**：在单个QUIC连接上预先创建多个流 354 | - **WebSocket连接池**：预先建立多个WebSocket连接 355 | 356 | ### 池设计 357 | 1. **池类型**： 358 | - **客户端池**：预先建立到远程端点的连接/流，采用主动式连接管理 359 | - **服务器池**：管理来自客户端的传入连接/流，采用被动式连接接收 360 | 361 | 2. **池组件**： 362 | - **连接/流存储**：线程安全的连接ID到net.Conn对象的映射，支持高并发访问 363 | - **ID通道**：用于可用连接ID的缓冲通道，实现无锁的快速分配 364 | - **容量管理**：基于使用模式的动态调整，实现智能扩缩容 365 | - 最小容量由客户端设置，确保客户端具备基础连接保障 366 | - 最大容量由服务端在握手时统一下发，实现全局资源协调 367 | - **间隔控制**：连接/流创建之间的基于时间的限流，防止网络资源过载 368 | - **连接工厂**：可定制的连接创建函数 369 | - TCP模式：标准TCP拨号和TLS握手 370 | - QUIC模式：流管理和多路复用 371 | - WebSocket模式：HTTP升级和握手处理 372 | 373 | ### 先进性设计 374 | 1. **零延迟连接**： 375 | - 预建立的连接池消除了TCP三次握手的延迟 376 | - TLS握手在连接池初始化时完成，避免运行时加密协商开销 377 | - 连接预热策略确保池中始终有可用的热连接 378 | - **QUIC增强**：0-RTT支持进一步降低重连延迟 379 | 380 | 2. **智能负载感知**： 381 | - 基于实时连接使用率的动态池管理 382 | - 预测性连接创建，根据历史使用模式提前准备连接 383 | - 自适应超时和重试机制，应对网络波动 384 | 385 | ### 连接生命周期 386 | 1. **连接创建**： 387 | - 连接/流创建数量不超过配置的容量，确保资源可控性 388 | - 每个连接都分配一个唯一ID，支持精确的连接跟踪和管理 389 | - ID和连接存储在池中，采用写时复制和延迟删除策略 390 | - **TCP模式**：创建带有可选TLS的独立TCP连接 391 | - **QUIC模式**：在共享QUIC连接上打开双向流 392 | - **WebSocket模式**：通过HTTP升级建立WebSocket连接 393 | 394 | 2. **连接获取**： 395 | - 客户端使用连接ID检索连接，支持精确匹配和快速查找 396 | - 服务端从池中检索下一个可用连接，采用轮询或最少使用策略 397 | - 在返回前验证连接有效性，包括网络状态和TLS会话检查 398 | 399 | 3. **连接使用**： 400 | - 获取时从池中移除连接，避免重复使用冲突 401 | - 用于端点之间的数据交换，采用高效的零拷贝传输 402 | - 采用一次性使用模型，确保连接状态的干净性 403 | 404 | 4. **连接终止**： 405 | - 使用后立即关闭连接，避免资源泄漏 406 | - 正确释放系统资源，包括文件描述符和内存缓冲区 407 | - 错误处理确保异常情况下的干净终止 408 | 409 | ### 会话管理与状态维护 410 | 1. **有状态的UDP处理**： 411 | - 将无状态的UDP协议转换为有状态的会话处理 412 | - 智能的会话超时管理，平衡资源使用和响应性 413 | - 会话复用机制，减少连接建立开销 414 | 415 | 2. **TCP连接管理**： 416 | - 连接池管理，实现高效的资源利用 417 | - 连接池条目的一次性使用模型，确保状态的干净性 418 | - 连接健康监控和自动清理 419 | 420 | 3. **跨协议统一管理**： 421 | - 统一的连接生命周期管理，简化系统复杂性 422 | - 协议无关的监控和统计，提供一致的观测体验 423 | - 灵活的协议转换能力，支持异构网络环境 424 | 425 | ## 信号通信与协调机制 426 | 427 | NodePass 的信号系统体现了分布式系统设计的精髓： 428 | 429 | ### 信号设计原理 430 | 1. **事件驱动架构**： 431 | - 基于事件的异步通信模式，避免阻塞等待 432 | - 发布-订阅模式的信号分发，支持多订阅者 433 | - 信号的优先级管理，确保关键事件的及时处理 434 | 435 | 2. **可靠性保障**： 436 | - 信号的持久化机制，防止关键信号丢失 437 | - 重试和确认机制，确保信号的可靠传递 438 | - 信号的幂等性设计，避免重复执行的副作用 439 | 440 | 3. **性能优化**： 441 | - 批量信号处理，减少系统调用开销 442 | - 信号压缩和合并，优化网络带宽使用 443 | - 异步信号处理，避免阻塞主处理流程 444 | 445 | ### 分布式协调 446 | 1. **一致性保证**： 447 | - 分布式锁机制，确保关键操作的原子性 448 | - 状态同步协议，保持多节点间的数据一致性 449 | - 冲突解决策略，处理并发操作的竞争条件 450 | 451 | 2. **故障处理**： 452 | - 节点故障检测，及时发现和隔离故障节点 453 | - 自动故障转移，保证服务的连续性 454 | - 状态恢复机制，支持故障后的快速恢复 455 | 456 | ### 池管理 457 | 1. **容量控制**： 458 | - 最小容量保证：确保始终有足够的预热连接可用 459 | - 最大容量限制：防止过度资源消耗，保护系统稳定性 460 | - 基于需求模式的动态缩放，响应流量变化 461 | 462 | 2. **间隔控制**： 463 | - 最小间隔限制：防止连接创建风暴，保护网络资源 464 | - 最大间隔限制：确保及时响应连接需求 465 | - 自适应基于时间的限流以优化资源使用 466 | 467 | 3. **动态池适应**： 468 | 连接池采用双重自适应机制以确保最佳性能： 469 | 470 | **A. 容量调整** 471 | - 池容量根据实时使用模式动态调整，实现智能扩缩容 472 | - 基于连接创建成功率的反馈调节：低成功率时收缩容量以减少资源浪费 473 | - 高成功率时扩展容量以满足增长需求 474 | - 渐进缩放防止系统震荡，提供平滑的性能过渡 475 | - 严格遵守配置的容量边界，确保系统可控性 476 | 477 | **B. 间隔调整** 478 | - 创建间隔根据池空闲连接数实时调整 479 | - 低空闲率时加速连接创建，确保供应充足 480 | - 高空闲率时放缓创建节奏，避免资源浪费 481 | - 防止在低需求期间对网络资源造成压力 482 | - 在池耗尽的高需求期间加速连接创建，保证服务质量 483 | 484 | 4. **性能优化策略**： 485 | - **预测性扩容**：基于历史使用模式预测未来需求 486 | - **分层连接管理**：不同优先级的连接采用不同的管理策略 487 | - **批量操作优化**：连接的批量创建和销毁，减少系统调用开销 488 | - **连接亲和性**：基于地理位置或网络拓扑的智能连接分配 489 | 490 | ## 数据交换机制 491 | 492 | NodePass 的数据交换机制体现了现代网络编程的最佳实践： 493 | 494 | ### 高性能数据传输 495 | 1. **零拷贝架构**： 496 | - 数据在内核空间直接传输，避免用户空间的多次拷贝 497 | - 减少CPU开销和内存带宽占用 498 | - 支持大文件和高吞吐量场景的优化传输 499 | 500 | 2. **异步I/O模型**： 501 | - 非阻塞的事件驱动架构，最大化并发处理能力 502 | - 基于epoll/kqueue的高效事件循环 503 | - 智能的读写缓冲区管理，平衡内存使用和性能 504 | 505 | 3. **流量统计与监控**： 506 | - 实时的字节级流量统计，支持精确的带宽控制 507 | - 分协议的流量分析，便于性能调优 508 | - 连接级别的性能指标，支持细粒度监控 509 | - 实时跟踪TCP和UDP活动连接数，便于容量规划和性能分析 510 | 511 | ### 协议优化 512 | 1. **TCP优化**： 513 | - 智能的TCP_NODELAY配置，减少小包延迟 514 | - Keep-alive机制确保长连接的可靠性 515 | - 拥塞控制算法的自适应选择 516 | 517 | 2. **UDP优化**： 518 | - 会话式UDP处理，支持有状态的数据报交换 519 | - 智能超时管理，平衡响应性和资源使用 520 | - 数据报去重和乱序处理 521 | 522 | ## 主控API架构 523 | 524 | 在主控模式下，NodePass提供RESTful API进行集中管理，体现了云原生架构的设计理念： 525 | 526 | ### 架构设计哲学 527 | 主控模式采用"统一管理，分布式执行"的架构模式，将控制平面与数据平面分离。这种设计使得系统具备了企业级的可管理性和可观测性，同时保持了数据传输的高性能。 528 | 529 | ### API组件 530 | 1. **HTTP/HTTPS服务器**： 531 | - 在配置的地址和端口上监听，支持灵活的网络部署 532 | - 可选的TLS加密，与隧道服务器使用相同安全模式，确保管理通道的安全性 533 | - 可配置的API前缀路径，支持反向代理和API网关集成 534 | 535 | 2. **实例管理**： 536 | - 基于内存的高性能实例注册表，支持快速查询和更新 537 | - 基于UID的实例标识，确保全局唯一性 538 | - 每个实例的状态跟踪（运行中、已停止等），支持实时状态监控 539 | 540 | 3. **RESTful端点**： 541 | - 标准CRUD操作，遵循REST设计原则 542 | - 实例控制操作（启动、停止、重启），支持远程生命周期管理 543 | - 健康状态报告，提供实时的系统健康信息 544 | - OpenAPI规范支持，便于API文档生成和客户端开发 545 | 546 | ### 实例生命周期管理 547 | 1. **实例创建**： 548 | - 基于URL的配置，类似于命令行，降低学习成本 549 | - 基于实例类型的动态初始化，支持多种部署模式 550 | - 实例创建前的参数验证，确保配置正确性 551 | 552 | 2. **实例控制**： 553 | - 启动/停止/重启能力，支持远程运维操作 554 | - 可配置超时的优雅关闭，确保数据完整性 555 | - 终止时的资源清理，防止资源泄漏 556 | 557 | 3. **API安全**： 558 | - API连接的TLS加密选项，保护管理通信安全 559 | - 与隧道服务端相同的安全模式，统一安全策略 560 | - 证书管理支持，简化HTTPS部署 561 | 562 | ## 系统架构的先进性 563 | 564 | ### 分层解耦设计 565 | NodePass 采用了现代软件架构的分层设计原则： 566 | 567 | 1. **传输层分离**： 568 | - 控制通道与数据通道的彻底分离，避免控制信息干扰数据传输 569 | - 不同协议的独立优化，TCP和UDP各自采用最优策略 570 | - 多路复用支持，单一隧道承载多个应用连接 571 | 572 | 2. **安全层可插拔**： 573 | - 模块化的TLS实现，支持不同安全级别的灵活选择 574 | - 证书管理的自动化，减少运维复杂性 575 | - 密钥轮换机制，增强长期安全性 576 | 577 | 3. **管理层云原生**： 578 | - API优先的设计理念，所有功能均可通过API访问 579 | - 容器化友好的配置方式，支持现代DevOps实践 580 | - 无状态设计，便于水平扩展 581 | 582 | ### 性能优化理念 583 | 1. **延迟优化**： 584 | - 预连接池消除冷启动延迟 585 | - 智能路由减少网络跳数 586 | - 批量处理减少系统调用开销 587 | 588 | 2. **吞吐量优化**： 589 | - 零拷贝数据传输最大化带宽利用 590 | - 并发连接管理支持高并发场景 591 | - 自适应缓冲区大小优化内存使用 592 | 593 | 3. **资源优化**： 594 | - 智能连接复用减少资源消耗 595 | - 动态容量调整适应负载变化 596 | - 垃圾回收优化减少暂停时间 597 | 598 | ### 可靠性保障 599 | 1. **故障隔离**： 600 | - 连接级别的故障隔离，单点故障不影响整体服务 601 | - 自动重连机制，透明处理网络波动 602 | - 优雅降级策略，在资源不足时保证核心功能 603 | 604 | 2. **状态管理**： 605 | - 分布式状态同步，确保多实例间的一致性 606 | - 持久化关键状态，支持故障恢复 607 | - 版本化配置管理，支持回滚操作 608 | 609 | ## NodePass 架构创新总结 610 | 611 | ### 技术创新点 612 | 1. **连接池预热技术**： 613 | - 革命性地消除了网络隧道的冷启动延迟 614 | - 将传统的"按需建连"转变为"预热待用" 615 | - 显著提升了首次连接的响应速度 616 | 617 | 2. **分离式架构设计**： 618 | - 控制平面与数据平面的彻底分离 619 | - 信令通道与数据通道的独立优化 620 | - 实现了高性能与高可管理性的完美结合 621 | 622 | 3. **自适应资源管理**： 623 | - 基于实时负载的智能扩缩容 624 | - 预测性的资源分配策略 625 | - 故障自愈的弹性系统设计 626 | 627 | ### 行业领先优势 628 | 1. **性能优势**： 629 | - 零延迟连接建立，业界领先的响应速度 630 | - 高并发处理能力，支持企业级应用场景 631 | - 智能路由优化，最短路径数据传输 632 | 633 | 2. **可靠性优势**： 634 | - 多层次的故障隔离和恢复机制 635 | - 分布式架构的高可用保障 636 | - 优雅降级的服务质量保证 637 | 638 | 3. **安全性优势**： 639 | - 端到端的加密保护 640 | - 多层次的安全防护体系 641 | - 符合企业级安全标准 642 | 643 | ### 适用场景与价值 644 | 1. **企业级应用**： 645 | - 微服务架构的服务网格 646 | - 混合云环境的网络连接 647 | - 跨地域的服务访问 648 | 649 | 2. **开发运维**： 650 | - 本地开发环境的快速搭建 651 | - 测试环境的灵活配置 652 | - 生产环境的流量管理 653 | 654 | 3. **网络优化**： 655 | - 网络延迟的大幅降低 656 | - 带宽利用率的显著提升 657 | - 连接稳定性的可靠保障 658 | 659 | NodePass 通过其创新的架构设计和技术实现，为现代网络应用提供了一个高性能、高可靠、高安全的隧道解决方案，代表了网络隧道技术的发展方向。 660 | 661 | ## 下一步 662 | 663 | - 有关部署NodePass的实际示例，请参阅[示例页面](/docs/zh/examples.md) 664 | - 要根据您的特定需求优化NodePass，请探索[配置选项](/docs/zh/configuration.md) 665 | - 如果遇到任何问题，请查看[故障排除指南](/docs/zh/troubleshooting.md) -------------------------------------------------------------------------------- /docs/en/usage.md: -------------------------------------------------------------------------------- 1 | # Usage Instructions 2 | 3 | NodePass creates tunnels with an unencrypted TCP control channel and configurable TLS encryption options for data exchange. This guide covers the three operating modes and explains how to use each effectively. 4 | 5 | ## Command Line Syntax 6 | 7 | The general syntax for NodePass commands is: 8 | 9 | ```bash 10 | nodepass ":///?log=&tls=&crt=&key=&dns=&min=&max=&mode=&type=&dial=&read=&rate=&slot=&proxy=¬cp=<0|1>&noudp=<0|1>" 11 | ``` 12 | 13 | Where: 14 | - ``: Specifies the operating mode (`server`, `client`, or `master`) 15 | - ``: The tunnel endpoint address for control channel communications 16 | - ``: The destination address for business data with bidirectional flow support (or API prefix in master mode) 17 | 18 | ### Query Parameters 19 | 20 | Common query parameters: 21 | - `log=`: Log verbosity level (`none`, `debug`, `info`, `warn`, `error`, or `event`) 22 | - `dns=`: DNS cache TTL duration (default: `5m`, supports time units like `1h`, `30m`, `15s`, etc.) 23 | - `min=`: Minimum connection pool capacity (default: 64, set by client) 24 | - `max=`: Maximum connection pool capacity (default: 1024, set by server and delivered to client) 25 | - `mode=`: Run mode control (`0`, `1`, or `2`) - controls operational behavior 26 | - `type=`: Connection pool type (`0` for TCP pool, `1` for QUIC UDP pool, `2` for WebSocket/WSS pool, `3` for HTTP/2 pool, default: 0, server-side only) 27 | - `dial=`: Source IP address for outbound connections (default: `auto`, supports both IPv4 and IPv6) 28 | - `read=`: Data read timeout duration (default: 0, supports time units like 30s, 5m, 1h, etc.) 29 | - `rate=`: Bandwidth rate limit in Mbps (default: 0 for unlimited) 30 | - `slot=`: Maximum concurrent connection limit (default: 65536, 0 for unlimited) 31 | - `proxy=`: PROXY protocol support (default: `0`, `1` enables PROXY protocol v1 header transmission) 32 | - `notcp=<0|1>`: TCP support control (default: `0` enabled, `1` disabled) 33 | - `noudp=<0|1>`: UDP support control (default: `0` enabled, `1` disabled) 34 | 35 | TLS-related parameters (server/master modes only): 36 | - `tls=`: TLS security level for data channels (`0`, `1`, or `2`) 37 | - `crt=`: Path to certificate file (when `tls=2`) 38 | - `key=`: Path to private key file (when `tls=2`) 39 | 40 | Connection pool type (server mode only): 41 | - `type=`: Connection pool type (`0` for TCP pool, `1` for QUIC UDP pool, `2` for WebSocket/WSS pool, default: 0) 42 | - Server configuration is automatically delivered to client during handshake 43 | - Client does not need to specify type parameter 44 | 45 | ## Operating Modes 46 | 47 | NodePass offers three complementary operating modes to suit various deployment scenarios. 48 | 49 | ### Server Mode 50 | 51 | Server mode establishes tunnel control channels and supports bidirectional data flow forwarding. 52 | 53 | ```bash 54 | nodepass "server:///?log=&tls=&crt=&key=&dns=&type=&max=&mode=&dial=&read=&rate=&slot=&proxy=¬cp=<0|1>&noudp=<0|1>" 55 | ``` 56 | 57 | #### Parameters 58 | 59 | - `tunnel_addr`: Address for the TCP tunnel endpoint (control channel) that clients will connect to (e.g., 10.1.0.1:10101) 60 | - `target_addr`: The destination address for business data with bidirectional flow support (e.g., 10.1.0.1:8080) 61 | - `log`: Log level (debug, info, warn, error, event) 62 | - `dns`: DNS cache TTL duration (default: 5m, supports time units like `1h`, `30m`, `15s`, etc.) 63 | - `type`: Connection pool type (0, 1, 2, 3) 64 | - `0`: Use TCP-based connection pool (default) 65 | - `1`: Use QUIC-based UDP connection pool with stream multiplexing(requires TLS, minimum `tls=1`) 66 | - `2`: Use WebSocket/WSS-based connection pool 67 | - `3`: Use HTTP/2-based connection pool with multiplexed streams (requires TLS, minimum `tls=1`) 68 | - Configuration is automatically delivered to client during handshake 69 | - `tls`: TLS encryption mode for the target data channel (0, 1, 2) 70 | - `0`: No TLS encryption (plain TCP/UDP) 71 | - `1`: Self-signed certificate (automatically generated) 72 | - `2`: Custom certificate (requires `crt` and `key` parameters) 73 | - `crt`: Path to certificate file (required when `tls=2`) 74 | - `key`: Path to private key file (required when `tls=2`) 75 | - `max`: Maximum connection pool capacity (default: 1024) 76 | - `mode`: Run mode control for data flow direction 77 | - `0`: Automatic detection (default) - attempts local binding first, falls back if unavailable 78 | - `1`: Force reverse mode - server binds to target address locally and receives traffic 79 | - `2`: Force forward mode - server connects to remote target address 80 | - `dial`: Source IP address for outbound connections to target (default: `auto` for system-selected IP) 81 | - `read`: Data read timeout duration (default: 0, supports time units like 30s, 5m, 1h, etc.) 82 | - `rate`: Bandwidth rate limit (default: 0 means no limit) 83 | - `slot`: Maximum concurrent connection limit (default: 65536, 0 means unlimited) 84 | - `proxy`: PROXY protocol support (default: `0`, `1` enables PROXY protocol v1 header before data transfer) 85 | - `notcp`: TCP support control (default: `0` enabled, `1` disabled) 86 | - `noudp`: UDP support control (default: `0` enabled, `1` disabled) 87 | 88 | #### How Server Mode Works 89 | 90 | Server mode supports automatic mode detection or forced mode selection through the `mode` parameter: 91 | 92 | **Mode 0: Automatic Detection** (default) 93 | - Attempts to bind to `target_addr` locally first 94 | - If successful, operates in reverse mode (server receives traffic) 95 | - If binding fails, operates in forward mode (server sends traffic) 96 | 97 | **Mode 1: Reverse Mode** (server receives traffic) 98 | 1. Listens for TCP tunnel connections (control channel) on `tunnel_addr` 99 | 2. Binds to and listens for incoming TCP and UDP traffic on `target_addr` 100 | 3. When a connection arrives at `target_addr`, it signals the connected client through the control channel 101 | 4. Creates a data channel for each connection with the specified TLS encryption level 102 | 103 | **Mode 2: Forward Mode** (server sends traffic) 104 | 1. Listens for TCP tunnel connections (control channel) on `tunnel_addr` 105 | 2. Waits for clients to listen locally and receive connections through the tunnel 106 | 3. Establishes connections to remote `target_addr` and forwards data 107 | 108 | #### Examples 109 | 110 | ```bash 111 | # Automatic mode detection with no TLS encryption 112 | nodepass "server://10.1.0.1:10101/10.1.0.1:8080?log=debug&tls=0" 113 | 114 | # Force reverse mode with self-signed certificate 115 | nodepass "server://10.1.0.1:10101/10.1.0.1:8080?log=debug&tls=1&mode=1" 116 | 117 | # Force forward mode with custom certificate 118 | nodepass "server://10.1.0.1:10101/192.168.1.100:8080?log=debug&tls=2&mode=2&crt=/path/to/cert.pem&key=/path/to/key.pem" 119 | 120 | # QUIC pool with automatic TLS 121 | nodepass "server://10.1.0.1:10101/192.168.1.100:8080?log=debug&type=1&mode=2" 122 | 123 | # WebSocket pool with custom certificate 124 | nodepass "server://10.1.0.1:10101/192.168.1.100:8080?log=debug&type=2&tls=2&mode=2&crt=/path/to/cert.pem&key=/path/to/key.pem" 125 | 126 | # HTTP/2 pool with automatic TLS 127 | nodepass "server://10.1.0.1:10101/192.168.1.100:8080?log=debug&type=3&mode=2&tls=1" 128 | ``` 129 | 130 | ### Client Mode 131 | 132 | Client mode connects to a NodePass server and supports bidirectional data flow forwarding. 133 | 134 | ```bash 135 | nodepass "client:///?log=&dns=&min=&mode=&dial=&read=&rate=&slot=&proxy=¬cp=<0|1>&noudp=<0|1>" 136 | ``` 137 | 138 | #### Parameters 139 | 140 | - `tunnel_addr`: Address of the NodePass server's tunnel endpoint to connect to (e.g., 10.1.0.1:10101) 141 | - `target_addr`: The destination address for business data with bidirectional flow support (e.g., 127.0.0.1:8080) 142 | - `log`: Log level (debug, info, warn, error, event) 143 | - `dns`: DNS cache TTL duration (default: 5m, supports time units like `1h`, `30m`, `15s`, etc.) 144 | - `min`: Minimum connection pool capacity (default: 64) 145 | - `mode`: Run mode control for client behavior 146 | - `0`: Automatic detection (default) - attempts local binding first, falls back to handshake mode 147 | - `1`: Force single-end forwarding mode - local proxy with connection pooling 148 | - `2`: Force dual-end handshake mode - requires server coordination 149 | - `dial`: Source IP address for outbound connections to target (default: `auto` for system-selected IP) 150 | - `read`: Data read timeout duration (default: 0, supports time units like 30s, 5m, 1h, etc.) 151 | - `rate`: Bandwidth rate limit (default: 0 means no limit) 152 | - `slot`: Maximum concurrent connection limit (default: 65536, 0 means unlimited) 153 | - `proxy`: PROXY protocol support (default: `0`, `1` enables PROXY protocol v1 header before data transfer) 154 | - `notcp`: TCP support control (default: `0` enabled, `1` disabled) 155 | - `noudp`: UDP support control (default: `0` enabled, `1` disabled) 156 | 157 | **Note**: Connection pool type configuration is automatically received from the server during handshake. Clients do not need to specify the `type` parameter. 158 | 159 | #### How Client Mode Works 160 | 161 | Client mode supports automatic mode detection or forced mode selection through the `mode` parameter: 162 | 163 | **Mode 0: Automatic Detection** (default) 164 | - Attempts to bind to `tunnel_addr` locally first 165 | - If successful, operates in single-end forwarding mode 166 | - If binding fails, operates in dual-end handshake mode 167 | 168 | **Mode 1: Single-End Forwarding Mode** 169 | 1. Listens for TCP and UDP connections on the local tunnel address 170 | 2. Uses connection pooling technology to pre-establish TCP connections to target address, eliminating connection latency 171 | 3. Directly forwards received traffic to the target address with high performance 172 | 4. No handshake with server required, enables point-to-point direct forwarding 173 | 5. Suitable for local proxy and simple forwarding scenarios 174 | 175 | **Mode 2: Dual-End Handshake Mode** 176 | - **Client Receives Traffic** (when server sends traffic) 177 | 1. Connects to the server's TCP tunnel endpoint (control channel) 178 | 2. Listens locally and waits for connections through the tunnel 179 | 3. Establishes connections to local `target_addr` and forwards data 180 | 181 | - **Client Sends Traffic** (when server receives traffic) 182 | 1. Connects to the server's TCP tunnel endpoint (control channel) 183 | 2. Listens for signals from the server through this control channel 184 | 3. When a signal is received, establishes a data connection with the TLS security level specified by the server 185 | 4. Creates a connection to `target_addr` and forwards traffic 186 | 187 | #### Examples 188 | 189 | ```bash 190 | # Automatic mode detection - Local proxy listening on port 1080, forwarding to target server 191 | nodepass "client://127.0.0.1:1080/target.example.com:8080?log=debug" 192 | 193 | # Force single-end forwarding mode - High performance local proxy 194 | nodepass "client://127.0.0.1:1080/target.example.com:8080?mode=1&log=debug" 195 | 196 | # Force dual-end handshake mode - Connect to NodePass server and adopt its TLS security policy 197 | nodepass "client://server.example.com:10101/127.0.0.1:8080?mode=2" 198 | 199 | # Connect with debug logging and custom connection pool capacity 200 | nodepass "client://server.example.com:10101/192.168.1.100:8080?log=debug&min=128" 201 | 202 | # Resource-constrained configuration with forced mode 203 | nodepass "client://server.example.com:10101/127.0.0.1:8080?mode=2&min=16&log=info" 204 | 205 | # Resource-constrained configuration - Small connection pool 206 | nodepass "client://server.example.com:10101/127.0.0.1:8080?min=16&log=info" 207 | 208 | # Client automatically receives pool type configuration from server (no type parameter needed) 209 | nodepass "client://server.example.com:10101/127.0.0.1:8080?mode=2&min=128&log=debug" 210 | 211 | # Client for real-time applications (pool type config from server) 212 | nodepass "client://server.example.com:10101/127.0.0.1:7777?mode=2&min=64&read=30s" 213 | ``` 214 | 215 | ### Master Mode (API) 216 | 217 | Master mode runs a RESTful API server for centralized management of NodePass instances. 218 | 219 | ```bash 220 | nodepass "master://[]?log=&tls=&crt=&key=" 221 | ``` 222 | 223 | #### Parameters 224 | 225 | - `api_addr`: Address where the API service will listen (e.g., 0.0.0.0:9090) 226 | - `prefix`: Optional API prefix path (e.g., /management). Default is `/api` 227 | - `log`: Log level (debug, info, warn, error, event) 228 | - `tls`: TLS encryption mode for the API service (0, 1, 2) 229 | - `0`: No TLS encryption (HTTP) 230 | - `1`: Self-signed certificate (HTTPS with auto-generated cert) 231 | - `2`: Custom certificate (HTTPS with provided cert) 232 | - `crt`: Path to certificate file (required when `tls=2`) 233 | - `key`: Path to private key file (required when `tls=2`) 234 | 235 | #### How Master Mode Works 236 | 237 | In master mode, NodePass: 238 | 1. Runs a RESTful API server that allows dynamic management of NodePass instances 239 | 2. Provides endpoints for creating, starting, stopping, and monitoring client and server instances 240 | 3. Includes Swagger UI for easy API exploration at `{prefix}/v1/docs` 241 | 4. Automatically inherits TLS and logging settings for instances created through the API 242 | 243 | #### API Endpoints 244 | 245 | All endpoints are relative to the configured prefix (default: `/api`): 246 | 247 | **Protected Endpoints (Require API Key):** 248 | - `GET {prefix}/v1/instances` - List all instances 249 | - `POST {prefix}/v1/instances` - Create a new instance with JSON body: `{"url": "server://0.0.0.0:10101/0.0.0.0:8080"}` 250 | - `GET {prefix}/v1/instances/{id}` - Get instance details 251 | - `PATCH {prefix}/v1/instances/{id}` - Update instance with JSON body: `{"action": "start|stop|restart"}` 252 | - `DELETE {prefix}/v1/instances/{id}` - Delete instance 253 | - `GET {prefix}/v1/events` - Server-Sent Events stream (SSE) 254 | - `GET {prefix}/v1/info` - Get system information 255 | 256 | **Public Endpoints (No API Key Required):** 257 | - `GET {prefix}/v1/openapi.json` - OpenAPI specification 258 | - `GET {prefix}/v1/docs` - Swagger UI documentation 259 | 260 | #### Examples 261 | 262 | ```bash 263 | # Start master with HTTP using default API prefix (/api) 264 | nodepass "master://0.0.0.0:9090?log=info" 265 | 266 | # Start master with custom API prefix (/management) 267 | nodepass "master://0.0.0.0:9090/management?log=info" 268 | 269 | # Start master with HTTPS (self-signed certificate) 270 | nodepass "master://0.0.0.0:9090/admin?log=info&tls=1" 271 | 272 | # Start master with HTTPS (custom certificate) 273 | nodepass "master://0.0.0.0:9090?log=info&tls=2&crt=/path/to/cert.pem&key=/path/to/key.pem" 274 | ``` 275 | 276 | ## Managing NodePass Instances 277 | 278 | ### Creating and Managing via API 279 | 280 | NodePass master mode provides RESTful API for instance management, and all API requests require authentication using an API Key. 281 | 282 | #### API Key Retrieval 283 | 284 | When starting master mode, the system automatically generates an API Key and displays it in the logs: 285 | 286 | ```bash 287 | # Start master mode 288 | nodepass "master://0.0.0.0:9090?log=info" 289 | 290 | # The log output will show: 291 | # INFO: API Key created: abc123def456... 292 | ``` 293 | 294 | #### API Request Examples 295 | 296 | All protected API endpoints require the `X-API-Key` header: 297 | 298 | ```bash 299 | # Get API Key (assume: abc123def456789) 300 | 301 | # Create instance via API (using default prefix) 302 | curl -X POST http://localhost:9090/api/v1/instances \ 303 | -H "X-API-Key: abc123def456789" \ 304 | -d '{"url":"server://0.0.0.0:10101/0.0.0.0:8080?tls=1"}' 305 | 306 | # Using custom prefix 307 | curl -X POST http://localhost:9090/admin/v1/instances \ 308 | -H "X-API-Key: abc123def456789" \ 309 | -d '{"url":"server://0.0.0.0:10101/0.0.0.0:8080?tls=1"}' 310 | 311 | # List all running instances 312 | curl http://localhost:9090/api/v1/instances \ 313 | -H "X-API-Key: abc123def456789" 314 | 315 | # Control an instance (replace {id} with actual instance ID) 316 | curl -X PATCH http://localhost:9090/api/v1/instances/{id} \ 317 | -H "X-API-Key: abc123def456789" \ 318 | -d '{"action":"restart"}' 319 | ``` 320 | 321 | #### Public Endpoints 322 | 323 | The following endpoints do not require API Key authentication: 324 | - `GET {prefix}/v1/openapi.json` - OpenAPI specification 325 | - `GET {prefix}/v1/docs` - Swagger UI documentation 326 | 327 | ## Bidirectional Data Flow Explanation 328 | 329 | NodePass supports flexible bidirectional data flow configuration: 330 | 331 | ### Client Single-End Forwarding Mode 332 | - **Client**: Listens on local tunnel address, uses connection pooling technology to directly forward to target address 333 | - **Connection Pool Optimization**: Pre-establishes TCP connections, eliminates connection latency, provides high-performance forwarding 334 | - **No Server Required**: Operates independently without server handshake 335 | - **Use Case**: Local proxy, simple port forwarding, testing environments, high-performance forwarding 336 | 337 | ### Server Receives Mode 338 | - **Server**: Listens for incoming connections on target_addr, forwards through tunnel to client 339 | - **Client**: Connects to local target_addr to provide services 340 | - **Use Case**: Expose internal services to external access 341 | 342 | ### Server Sends Mode 343 | - **Server**: Connects to remote target_addr to fetch data, sends through tunnel to client 344 | - **Client**: Listens locally to receive connections from server 345 | - **Use Case**: Access remote services through tunnel proxy 346 | 347 | The system automatically selects the appropriate operation mode based on tunnel and target addresses: 348 | - If the client's tunnel address is a local address, enables single-end forwarding mode 349 | - If target address is a local address, uses Server Receives Mode 350 | - If target address is a remote address, uses Server Sends Mode 351 | 352 | ## Tunnel Key 353 | 354 | NodePass uses tunnel keys to authenticate connections between clients and servers. The key can be specified in two ways: 355 | 356 | ### Key Derivation Rules 357 | 358 | 1. **Explicit Key**: Specify the username part in the URL as the key 359 | ```bash 360 | # Use "mypassword" as the tunnel key 361 | nodepass server://mypassword@10.1.0.1:10101/10.1.0.1:8080 362 | nodepass client://mypassword@10.1.0.1:10101/127.0.0.1:8080 363 | ``` 364 | 365 | 2. **Port-Derived Key**: If no username is specified, the system uses the hexadecimal value of the port number as the key 366 | ```bash 367 | # Port 10101's hexadecimal value "2775" will be used as the tunnel key 368 | nodepass server://10.1.0.1:10101/10.1.0.1:8080 369 | nodepass client://10.1.0.1:10101/127.0.0.1:8080 370 | ``` 371 | 372 | ### Handshake Process 373 | 374 | The handshake process between client and server is as follows: 375 | 376 | 1. **Client Connection**: Client connects to the server's tunnel address 377 | 2. **Key Authentication**: Client sends encrypted tunnel key 378 | 3. **Server Verification**: Server decrypts and verifies if the key matches 379 | 4. **Configuration Sync**: Upon successful verification, server sends tunnel configuration including: 380 | - Data flow direction 381 | - Maximum connection pool capacity 382 | - TLS security mode 383 | 5. **Connection Established**: Handshake complete, data transmission begins 384 | 385 | This design ensures that only clients with the correct key can establish tunnel connections, while allowing the server to centrally manage connection pool capacity. 386 | 387 | ## Next Steps 388 | 389 | - Learn about [configuration options](/docs/en/configuration.md) to fine-tune NodePass 390 | - Explore [examples](/docs/en/examples.md) of common deployment scenarios 391 | - Understand [how NodePass works](/docs/en/how-it-works.md) under the hood 392 | - Check the [troubleshooting guide](/docs/en/troubleshooting.md) if you encounter issues -------------------------------------------------------------------------------- /docs/zh/examples.md: -------------------------------------------------------------------------------- 1 | # 使用示例 2 | 3 | 本页提供了NodePass在各种部署场景中的实际示例。这些示例涵盖了常见用例，可以根据您的具体需求进行调整。 4 | 5 | ## 基本服务器设置与TLS选项 6 | 7 | ### 示例1：无TLS加密 8 | 9 | 当速度比安全性更重要时（例如，在受信任网络中）： 10 | 11 | ```bash 12 | nodepass "server://0.0.0.0:10101/127.0.0.1:8080?log=debug&tls=0" 13 | ``` 14 | 15 | 这会启动一个NodePass服务器，它： 16 | - 在所有接口的10101端口上监听隧道连接 17 | - 将流量转发到localhost:8080 18 | - 使用debug日志记录详细信息 19 | - 不对数据通道使用加密（最快性能） 20 | 21 | ### 示例2：自签名证书 22 | 23 | 为了平衡安全性和易于设置（推荐大多数情况）： 24 | 25 | ```bash 26 | nodepass "server://0.0.0.0:10101/127.0.0.1:8080?log=debug&tls=1" 27 | ``` 28 | 29 | 此配置： 30 | - 自动生成自签名证书 31 | - 提供加密而无需证书管理 32 | - 保护数据流量免受被动窃听 33 | - 适用于内部或测试环境 34 | 35 | ### 示例3：自定义域名证书 36 | 37 | 对于需要验证证书的生产环境： 38 | 39 | ```bash 40 | nodepass "server://0.0.0.0:10101/127.0.0.1:8080?log=debug&tls=2&crt=/path/to/cert.pem&key=/path/to/key.pem" 41 | ``` 42 | 43 | 这一设置： 44 | - 使用您提供的TLS证书和私钥 45 | - 提供具有证书验证的最高安全级别 46 | - 适合生产环境和面向公众的服务 47 | - 允许客户端验证服务器的身份 48 | 49 | ## 连接到NodePass服务器 50 | 51 | ### 示例4：基本客户端连接 52 | 53 | 使用默认设置连接到NodePass服务器： 54 | 55 | ```bash 56 | nodepass client://server.example.com:10101/127.0.0.1:8080 57 | ``` 58 | 59 | 此客户端： 60 | - 连接到server.example.com:10101的NodePass服务器 61 | - 将接收到的流量转发到localhost:8080 62 | - 自动采用服务器的TLS安全策略 63 | - 使用默认的info日志级别 64 | 65 | ### 示例5：带调试日志的客户端 66 | 67 | 用于故障排除连接问题： 68 | 69 | ```bash 70 | nodepass client://server.example.com:10101/127.0.0.1:8080?log=debug 71 | ``` 72 | 73 | 这启用了详细输出，有助于识别： 74 | - 连接建立问题 75 | - 信号处理 76 | - 数据传输详情 77 | - 错误情况 78 | 79 | ### 示例6：运行模式控制 80 | 81 | 通过明确的模式设置控制操作行为： 82 | 83 | ```bash 84 | # 强制服务器以反向模式运行（服务器接收流量） 85 | nodepass "server://0.0.0.0:10101/0.0.0.0:8080?mode=1&tls=1" 86 | 87 | # 强制客户端以单端转发模式运行（高性能本地代理） 88 | nodepass "client://127.0.0.1:1080/remote.example.com:8080?mode=1" 89 | 90 | # 强制客户端以双端握手模式运行（需要服务器协调） 91 | nodepass "client://server.example.com:10101/127.0.0.1:8080?mode=2&log=debug" 92 | ``` 93 | 94 | 这些配置： 95 | - **服务器 mode=1**：强制反向模式，服务器本地绑定目标地址 96 | - **客户端 mode=1**：强制单端转发模式，使用直接连接实现高性能 97 | - **客户端 mode=2**：强制双端握手模式，适用于需要服务器协调的场景 98 | - 当自动检测不符合部署需求时使用模式控制 99 | 100 | ## 通过防火墙访问数据库 101 | 102 | ### 示例7：数据库隧道 103 | 104 | 启用对防火墙后的数据库服务器的安全访问： 105 | 106 | ```bash 107 | # 服务器端(位于安全网络外部)使用TLS加密 108 | nodepass server://:10101/127.0.0.1:5432?tls=1 109 | 110 | # 客户端(位于防火墙内部) 111 | nodepass client://server.example.com:10101/127.0.0.1:5432 112 | ``` 113 | 114 | 此配置： 115 | - 创建到PostgreSQL数据库（端口5432）的加密隧道 116 | - 允许安全访问数据库而不直接将其暴露于互联网 117 | - 使用自签名证书加密所有数据库流量 118 | - 使远程数据库在客户端上显示为本地服务 119 | 120 | ## 安全的微服务通信 121 | 122 | ### 示例8：服务间通信 123 | 124 | 启用微服务之间的安全通信： 125 | 126 | ```bash 127 | # 服务A(消费API)使用自定义证书 128 | nodepass "server://0.0.0.0:10101/127.0.0.1:8081?log=warn&tls=2&crt=/path/to/service-a.crt&key=/path/to/service-a.key" 129 | 130 | # 服务B(提供API) 131 | nodepass client://service-a:10101/127.0.0.1:8082 132 | ``` 133 | 134 | 此设置： 135 | - 在两个微服务之间创建安全通道 136 | - 使用自定义证书进行服务身份验证 137 | - 将日志限制为仅警告和错误 138 | - 使服务A的API在服务B上显示为本地服务 139 | 140 | ## 协议屏蔽和流量过滤 141 | 142 | ### 示例9：屏蔽代理协议 143 | 144 | 阻止SOCKS和HTTP代理使用你的隧道： 145 | 146 | ```bash 147 | # 屏蔽SOCKS和HTTP代理协议的服务器 148 | nodepass "server://0.0.0.0:10101/app.backend.com:8080?block=12&tls=1" 149 | 150 | # 连接到受保护服务器的客户端 151 | nodepass "client://server.example.com:10101/127.0.0.1:8080" 152 | ``` 153 | 154 | 此配置： 155 | - 屏蔽所有SOCKS4/4a/5代理连接（`block`包含`1`） 156 | - 屏蔽所有HTTP代理方法如CONNECT、GET、POST（`block`包含`2`） 157 | - 仅允许应用特定协议通过隧道 158 | - 用于防止在应用隧道上滥用代理 159 | 160 | ### 示例10：屏蔽TLS嵌套场景 161 | 162 | 当外层已提供安全保护时，防止嵌套TLS加密： 163 | 164 | ```bash 165 | # 使用TLS加密并屏蔽内部TLS连接的服务器 166 | nodepass "server://0.0.0.0:10101/0.0.0.0:8080?tls=1&block=3" 167 | 168 | # 客户端自动继承TLS设置 169 | nodepass "client://server.example.com:10101/127.0.0.1:8080" 170 | ``` 171 | 172 | 此设置： 173 | - 使用TLS加密隧道本身（`tls=1`） 174 | - 屏蔽加密隧道内的TLS握手（`block=3`） 175 | - 防止不必要的双重加密开销 176 | - 有助于识别应用尝试添加冗余TLS的错误配置 177 | 178 | ### 示例11：综合安全策略 179 | 180 | 执行严格的安全策略，仅允许应用流量： 181 | 182 | ```bash 183 | # 具有综合协议屏蔽的生产服务器 184 | nodepass "server://0.0.0.0:10101/secure-app.internal:443?tls=2&crt=/path/to/cert.pem&key=/path/to/key.pem&block=123&slot=500" 185 | 186 | # 强制加密的客户端 187 | nodepass "client://prod-server.example.com:10101/127.0.0.1:8443?log=warn" 188 | ``` 189 | 190 | 此配置： 191 | - 使用经过验证的自定义证书以获得最大安全性（`tls=2`） 192 | - 屏蔽SOCKS代理（`block`包含`1`） 193 | - 屏蔽HTTP代理（`block`包含`2`） 194 | - 屏蔽嵌套TLS连接（`block`包含`3`） 195 | - 将并发连接限制为500以控制资源 196 | - 仅记录警告和错误以减少噪音 197 | 198 | ### 示例12：开发环境的选择性协议屏蔽 199 | 200 | 在开发环境中允许HTTP流量同时屏蔽代理： 201 | 202 | ```bash 203 | # 仅屏蔽SOCKS协议的开发服务器 204 | nodepass "server://127.0.0.1:10101/localhost:3000?block=1&log=debug" 205 | 206 | # 开发客户端 207 | nodepass "client://127.0.0.1:10101/localhost:8080" 208 | ``` 209 | 210 | 此设置： 211 | - 屏蔽SOCKS协议但允许HTTP请求 212 | - 适用于需要HTTP方法的Web应用测试 213 | - 防止开发人员隧道传输SOCKS代理流量 214 | - 启用调试日志记录以进行故障排除 215 | 216 | ## 带宽速率限制 217 | 218 | ### 示例13：带速率限制的文件传输服务器 219 | 220 | 控制文件传输服务的带宽使用： 221 | 222 | ```bash 223 | # 服务端：限制文件传输带宽为100 Mbps 224 | nodepass "server://0.0.0.0:10101/127.0.0.1:8080?log=info&tls=1&rate=100" 225 | 226 | # 客户端：连接时限制为50 Mbps 227 | nodepass "client://fileserver.example.com:10101/127.0.0.1:3000?log=info&rate=50" 228 | ``` 229 | 230 | 此配置： 231 | - 限制服务器带宽为100 Mbps以防止网络拥塞 232 | - 客户端进一步限制下载速度为50 Mbps以实现公平共享 233 | - 允许文件传输的同时为其他服务保留带宽 234 | - 使用TLS加密确保文件传输安全 235 | 236 | ### 示例14：物联网传感器数据收集的保守限制 237 | 238 | 对于带宽有限或按流量计费的物联网设备： 239 | 240 | ```bash 241 | # 服务器：接受物联网数据，限制为5 Mbps 242 | nodepass "server://0.0.0.0:10101/127.0.0.1:1883?log=warn&rate=5" 243 | 244 | # 物联网设备客户端：发送传感器数据，限制为2 Mbps 245 | nodepass "client://iot-gateway.example.com:10101/127.0.0.1:1883?log=error&rate=2" 246 | ``` 247 | 248 | 此设置： 249 | - 限制服务器为5 Mbps用于从多个物联网设备收集传感器数据 250 | - 单个物联网客户端限制为2 Mbps以防止单一设备消耗所有带宽 251 | - 最小日志记录（warn/error）以减少物联网设备的资源使用 252 | - 高效适用于MQTT或其他物联网协议 253 | 254 | ### 示例15：开发环境速率控制 255 | 256 | 在带宽约束下测试应用程序： 257 | 258 | ```bash 259 | # 模拟慢速网络条件进行测试 260 | nodepass "client://api.example.com:443/127.0.0.1:8080?log=debug&rate=1" 261 | 262 | # 带监控的高速开发服务器 263 | nodepass "server://0.0.0.0:10101/127.0.0.1:3000?log=debug&rate=500" 264 | ``` 265 | 266 | 此配置： 267 | - 客户端模拟1 Mbps连接用于测试慢速网络场景 268 | - 开发服务器限制为500 Mbps并提供详细日志记录用于调试 269 | - 帮助识别不同带宽约束下的性能问题 270 | 271 | ## 物联网设备管理 272 | 273 | ### 示例16：物联网网关 274 | 275 | 创建物联网设备的中央访问点： 276 | 277 | ```bash 278 | # 中央管理服务器 279 | nodepass "server://0.0.0.0:10101/127.0.0.1:8888?log=info&tls=1" 280 | 281 | # 物联网设备 282 | nodepass client://mgmt.example.com:10101/127.0.0.1:80 283 | ``` 284 | 285 | 此配置： 286 | - 使分布式物联网设备能够安全连接到中央服务器 287 | - 使用自签名证书提供足够的安全性 288 | - 允许嵌入式设备安全地暴露其本地Web界面 289 | - 通过单一端点集中设备管理 290 | 291 | 292 | ## 多网卡系统与源IP控制 293 | 294 | ### 示例17：指定网络接口选择 295 | 296 | 在多网卡系统上控制出站连接使用的网络接口： 297 | 298 | ```bash 299 | # 服务器为出站连接使用特定源IP（适用于策略路由） 300 | nodepass "server://0.0.0.0:10101/remote.backend.com:8080?dial=10.1.0.100&mode=2&tls=1" 301 | 302 | # 客户端为目标连接使用特定源IP（适用于防火墙规则） 303 | nodepass "client://server.example.com:10101/127.0.0.1:8080?dial=192.168.1.50&mode=2" 304 | ``` 305 | 306 | 此配置： 307 | - 强制出站连接使用特定的本地IP地址 308 | - 适用于具有多个网络接口的系统（例如，独立的公网/内网） 309 | - 通过源IP启用基于策略的路由 310 | - 如果指定地址失败，自动回退到系统选择的IP 311 | - 支持IPv4和IPv6地址 312 | 313 | ### 示例18：网络分段和VLAN路由 314 | 315 | 通过特定网络段或VLAN引导流量： 316 | 317 | ```bash 318 | # 服务器通过管理网络路由流量（10.0.0.0/8） 319 | nodepass "server://0.0.0.0:10101/mgmt.backend.local:8080?dial=10.200.1.10&mode=2&log=info" 320 | 321 | # 服务器通过生产网络路由流量（172.16.0.0/12） 322 | nodepass "server://0.0.0.0:10102/prod.backend.local:8080?dial=172.16.50.20&mode=2&log=info" 323 | 324 | # 客户端使用自动源IP选择（默认行为） 325 | nodepass "client://server.example.com:10101/127.0.0.1:8080?dial=auto" 326 | ``` 327 | 328 | 此设置： 329 | - 在网络层分离管理和生产流量 330 | - 确保流量基于源IP遵循指定的网络路径 331 | - 符合要求基于源的路由的网络安全策略 332 | - 自动回退防止配置错误导致的连接失败 333 | - `dial=auto`（默认）让系统选择合适的源IP 334 | 335 | **源IP控制使用场景**： 336 | - **多网卡服务器**：具有不同网络的多个网卡的系统 337 | - **策略路由**：需要特定源IP的网络策略 338 | - **防火墙合规**：匹配按源地址过滤的防火墙规则 339 | - **负载分配**：在多个网络链路之间分配出站流量 340 | - **网络测试**：模拟来自特定网络位置的流量 341 | 342 | ## DNS缓存TTL配置 343 | 344 | ### 示例19：稳定的企业网络 345 | 346 | 为稳定的内部服务使用较长的TTL： 347 | 348 | ```bash 349 | # 服务端：为稳定的内部主机名使用1小时缓存TTL 350 | nodepass "server://0.0.0.0:10101/internal-api.corp.local:8080?dns=1h&mode=2&tls=1" 351 | 352 | # 客户端：使用相同的TTL以保持一致行为 353 | nodepass "client://tunnel.corp.local:10101/127.0.0.1:8080?dns=1h" 354 | ``` 355 | 356 | 此配置： 357 | - 为稳定的内部服务使用1小时DNS缓存TTL 358 | - 减少企业网络中的DNS查询开销 359 | - 通过最小化DNS查找提高连接性能 360 | - 适用于DNS稳定的生产环境 361 | 362 | ### 示例20：动态DNS环境 363 | 364 | 为频繁变化的DNS记录使用较短的TTL： 365 | 366 | ```bash 367 | # 服务端：为动态DNS使用30秒缓存TTL 368 | nodepass "server://0.0.0.0:10101/dynamic.example.com:8080?dns=30s&tls=1&log=info" 369 | 370 | # 客户端：为负载均衡场景使用短TTL 371 | nodepass "client://server.example.com:10101/127.0.0.1:8080?dns=30s" 372 | ``` 373 | 374 | 此设置： 375 | - 为动态环境使用30秒DNS缓存TTL 376 | - 为负载均衡服务实现更快的故障转移 377 | - 确保连接使用当前的DNS记录 378 | - 适合IP频繁变化的云环境 379 | 380 | ### 示例21：开发和测试 381 | 382 | 为开发环境禁用缓存： 383 | 384 | ```bash 385 | # 开发服务器：不使用DNS缓存以立即更新 386 | nodepass "server://0.0.0.0:10101/dev.backend.local:8080?dns=0&tls=0&log=debug" 387 | 388 | # 测试客户端：不使用缓存以立即查看DNS更改 389 | nodepass "client://dev-server.local:10101/127.0.0.1:8080?dns=0&log=debug" 390 | ``` 391 | 392 | 此配置： 393 | - 禁用DNS缓存(dns=0)以立即更新 394 | - 每次连接都执行新的DNS查找 395 | - 在开发期间DNS记录频繁变化时很有用 396 | - 帮助在测试期间识别DNS相关问题 397 | 398 | ### 示例22：混合环境的自定义TTL 399 | 400 | 使用适中的TTL平衡性能和新鲜度： 401 | 402 | ```bash 403 | # 生产API：10分钟缓存以平衡性能 404 | nodepass "server://0.0.0.0:10101/api.example.com:8080?dns=10m&tls=1&mode=2" 405 | 406 | # 暂存环境：2分钟缓存以更快更新 407 | nodepass "server://0.0.0.0:10102/staging.example.com:8080?dns=2m&tls=1&mode=2" 408 | 409 | # 客户端：默认5分钟缓存 410 | nodepass "client://server.example.com:10101/127.0.0.1:8080" 411 | ``` 412 | 413 | 此设置： 414 | - 生产环境使用10分钟TTL以获得良好性能 415 | - 暂存环境使用2分钟TTL以更快地更新DNS 416 | - 客户端使用默认5分钟TTL 417 | - 每个环境针对其使用场景进行优化 418 | 419 | **DNS缓存TTL使用场景**： 420 | - **企业网络**：为稳定的内部主机名使用长TTL(1h) 421 | - **动态DNS**：为频繁变化的记录使用短TTL(30s-1m) 422 | - **负载均衡**：短TTL实现更快的故障转移 423 | - **性能优化**：较长的TTL降低连接延迟 424 | - **高可用性**：适中的TTL平衡新鲜度和性能 425 | 426 | ## 高可用性与负载均衡 427 | 428 | ### 示例23：多后端服务器负载均衡 429 | 430 | 使用目标地址组实现流量均衡分配和自动故障转移： 431 | 432 | ```bash 433 | # 服务端：配置3个后端Web服务器 434 | nodepass "server://0.0.0.0:10101/web1.internal:8080,web2.internal:8080,web3.internal:8080?mode=2&tls=1&log=info" 435 | 436 | # 客户端：连接到服务端 437 | nodepass "client://server.example.com:10101/127.0.0.1:8080?log=info" 438 | ``` 439 | 440 | 此配置： 441 | - 流量自动轮询分配到3个后端服务器，实现负载均衡 442 | - 当某个后端服务器故障时，自动切换到其他可用服务器 443 | - 故障服务器恢复后自动重新接入流量 444 | - 使用TLS加密确保隧道安全 445 | 446 | ### 示例24：数据库主从切换 447 | 448 | 为数据库配置主从实例，实现高可用访问： 449 | 450 | ```bash 451 | # 客户端：配置主从数据库地址（单端转发模式） 452 | nodepass "client://127.0.0.1:3306/db-primary.local:3306,db-secondary.local:3306?mode=1&log=warn" 453 | ``` 454 | 455 | 此设置： 456 | - 优先连接主数据库，主库故障时自动切换到从库 457 | - 单端转发模式提供高性能本地代理 458 | - 应用程序无需修改，透明地实现故障转移 459 | - 仅记录警告和错误，减少日志输出 460 | 461 | ### 示例25：API网关后端池 462 | 463 | 为API网关配置多个后端服务实例： 464 | 465 | ```bash 466 | # 服务端：配置4个API服务实例 467 | nodepass "server://0.0.0.0:10101/api1.backend:8080,api2.backend:8080,api3.backend:8080,api4.backend:8080?mode=2&tls=1&rate=200&slot=5000" 468 | 469 | # 客户端：从API网关连接 470 | nodepass "client://apigateway.example.com:10101/127.0.0.1:8080?rate=100&slot=2000" 471 | ``` 472 | 473 | 此配置： 474 | - 4个API服务实例形成后端池，轮询分配请求 475 | - 服务端限制带宽200 Mbps，最大5000并发连接 476 | - 客户端限制带宽100 Mbps，最大2000并发连接 477 | - 单个实例故障不影响整体服务可用性 478 | 479 | ### 示例26：地域分布式服务 480 | 481 | 配置多地域服务节点，优化网络延迟： 482 | 483 | ```bash 484 | # 服务端：配置多地域节点 485 | nodepass "server://0.0.0.0:10101/us-west.service:8080,us-east.service:8080,eu-central.service:8080?mode=2&log=debug" 486 | ``` 487 | 488 | 此设置： 489 | - 配置3个不同地域的服务节点 490 | - 轮询算法自动分配流量到各个地域 491 | - Debug日志帮助分析流量分布和故障情况 492 | - 适用于全球分布式应用场景 493 | 494 | **目标地址组最佳实践：** 495 | - **地址数量**：建议配置2-5个地址，过多会增加故障检测时间 496 | - **健康检查**：确保后端服务有自己的健康检查机制 497 | - **端口一致性**：所有地址使用相同端口或明确指定每个地址的端口 498 | - **监控告警**：配置监控系统跟踪故障转移事件 499 | - **测试验证**：部署前在测试环境验证故障转移和负载均衡行为 500 | 501 | ## PROXY协议集成 502 | 503 | ### 示例27：负载均衡器与PROXY协议集成 504 | 505 | 启用PROXY协议支持，与负载均衡器和反向代理集成： 506 | 507 | ```bash 508 | # 服务端：为HAProxy/Nginx集成启用PROXY协议v1 509 | nodepass "server://0.0.0.0:10101/127.0.0.1:8080?log=info&tls=1&proxy=1" 510 | 511 | # 客户端：启用PROXY协议以保留客户端连接信息 512 | nodepass "client://tunnel.example.com:10101/127.0.0.1:3000?log=info&proxy=1" 513 | ``` 514 | 515 | 此配置： 516 | - 在数据传输开始前发送PROXY协议v1头部 517 | - 通过隧道保留原始客户端IP和端口信息 518 | - 使后端服务能够看到真实的客户端连接详情 519 | - 兼容HAProxy、Nginx和其他支持PROXY协议的服务 520 | - 有助于维护准确的访问日志和基于IP的访问控制 521 | 522 | ### 示例28：Web应用的反向代理支持 523 | 524 | 使NodePass后的Web应用能够接收原始客户端信息： 525 | 526 | ```bash 527 | # 为Web应用启用PROXY协议的NodePass服务器 528 | nodepass "server://0.0.0.0:10101/127.0.0.1:8080?log=warn&tls=2&crt=/path/to/cert.pem&key=/path/to/key.pem&proxy=1" 529 | 530 | # 后端Web服务器（如Nginx）配置以处理PROXY协议 531 | # 在nginx.conf中： 532 | # server { 533 | # listen 8080 proxy_protocol; 534 | # real_ip_header proxy_protocol; 535 | # set_real_ip_from 127.0.0.1; 536 | # ... 537 | # } 538 | ``` 539 | 540 | 此设置： 541 | - Web应用接收原始客户端IP地址而不是NodePass隧道IP 542 | - 启用正确的访问日志记录、分析和安全控制 543 | - 支持连接审计的合规性要求 544 | - 适用于支持PROXY协议的Web服务器（Nginx、HAProxy等） 545 | 546 | ### 示例29：数据库访问与客户端IP保留 547 | 548 | 为数据库访问日志记录和安全维护客户端IP信息： 549 | 550 | ```bash 551 | # 启用PROXY协议的数据库代理服务器 552 | nodepass "server://0.0.0.0:10101/127.0.0.1:5432?log=error&proxy=1" 553 | 554 | # 通过隧道连接的应用客户端 555 | nodepass "client://dbproxy.example.com:10101/127.0.0.1:5432?proxy=1" 556 | ``` 557 | 558 | 优势： 559 | - 数据库日志显示原始应用服务器IP而不是隧道IP 560 | - 启用基于IP的数据库访问控制正常工作 561 | - 维护安全和合规的审计轨迹 562 | - 兼容支持PROXY协议的数据库（适当配置的PostgreSQL） 563 | 564 | **PROXY协议重要说明：** 565 | - 目标服务必须支持PROXY协议v1才能正确处理头部 566 | - PROXY头部仅对TCP连接发送，不支持UDP流量 567 | - 头部包含：协议（TCP4/TCP6）、源IP、目标IP、源端口、目标端口 568 | - 如果目标服务不支持PROXY协议，连接可能失败或行为异常 569 | - 在生产环境部署前，请在非生产环境中充分测试启用PROXY协议的配置 570 | 571 | ## 容器部署 572 | 573 | ### 示例30：容器化NodePass 574 | 575 | 在Docker环境中部署NodePass： 576 | 577 | ```bash 578 | # 为容器创建网络 579 | docker network create nodepass-net 580 | 581 | # 部署使用自签名证书的NodePass服务器 582 | docker run -d --name nodepass-server \ 583 | --network nodepass-net \ 584 | -p 10101:10101 \ 585 | ghcr.io/yosebyte/nodepass "server://0.0.0.0:10101/web-service:80?log=info&tls=1" 586 | 587 | # 部署Web服务作为目标 588 | docker run -d --name web-service \ 589 | --network nodepass-net \ 590 | nginx:alpine 591 | 592 | # 部署NodePass客户端 593 | docker run -d --name nodepass-client \ 594 | -p 8080:8080 \ 595 | ghcr.io/yosebyte/nodepass client://nodepass-server:10101/127.0.0.1:8080?log=info 596 | 597 | # 通过http://localhost:8080访问Web服务 598 | ``` 599 | 600 | 此配置： 601 | - 在服务之间创建容器化隧道 602 | - 使用Docker网络连接容器 603 | - 仅向主机公开必要端口 604 | - 提供对内部Web服务的安全访问 605 | 606 | ## 主控API管理 607 | 608 | ### 示例31：集中化管理 609 | 610 | 为多个NodePass实例设置中央控制器： 611 | 612 | ```bash 613 | # 使用自签名证书启动主控API服务 614 | nodepass "master://0.0.0.0:9090?log=info&tls=1" 615 | ``` 616 | 617 | 然后您可以通过API调用管理实例： 618 | 619 | ```bash 620 | # 创建服务器实例 621 | curl -X POST http://localhost:9090/api/v1/instances \ 622 | -H "Content-Type: application/json" \ 623 | -d '{"url":"server://0.0.0.0:10101/0.0.0.0:8080?tls=1"}' 624 | 625 | # 创建客户端实例 626 | curl -X POST http://localhost:9090/api/v1/instances \ 627 | -H "Content-Type: application/json" \ 628 | -d '{"url":"client://localhost:10101/127.0.0.1:8081"}' 629 | 630 | # 列出所有运行实例 631 | curl http://localhost:9090/api/v1/instances 632 | 633 | # 控制实例（用实际实例ID替换{id}） 634 | curl -X PUT http://localhost:9090/api/v1/instances/{id} \ 635 | -H "Content-Type: application/json" \ 636 | -d '{"action":"restart"}' 637 | ``` 638 | 639 | 此设置： 640 | - 为所有NodePass实例提供中央管理界面 641 | - 允许动态创建和控制隧道 642 | - 提供用于自动化和集成的RESTful API 643 | - 包含内置的Swagger UI，位于http://localhost:9090/api/v1/docs 644 | 645 | ### 示例32：自定义API前缀 646 | 647 | 为主控模式使用自定义API前缀： 648 | 649 | ```bash 650 | # 使用自定义API前缀启动 651 | nodepass "master://0.0.0.0:9090/admin?log=info&tls=1" 652 | 653 | # 使用自定义前缀创建实例 654 | curl -X POST http://localhost:9090/admin/v1/instances \ 655 | -H "Content-Type: application/json" \ 656 | -d '{"url":"server://0.0.0.0:10101/0.0.0.0:8080?tls=1"}' 657 | ``` 658 | 659 | 这允许： 660 | - 与现有API网关集成 661 | - 用于安全或组织目的的自定义URL路径 662 | - 在http://localhost:9090/admin/v1/docs访问Swagger UI 663 | 664 | ### 示例33：实时连接和流量监控 665 | 666 | 通过主控API监控实例的连接数和流量统计： 667 | 668 | ```bash 669 | # 获取实例详细信息，包括连接数统计 670 | curl -H "X-API-Key: your-api-key" http://localhost:9090/api/v1/instances/{id} 671 | 672 | # 响应示例（包含TCPS和UDPS字段） 673 | { 674 | "id": "a1b2c3d4", 675 | "alias": "网站代理", 676 | "type": "server", 677 | "status": "running", 678 | "url": "server://0.0.0.0:10101/127.0.0.1:8080", 679 | "restart": true, 680 | "pool": 64, 681 | "ping": 25, 682 | "tcps": 12, 683 | "udps": 5, 684 | "tcprx": 1048576, 685 | "tcptx": 2097152, 686 | "udprx": 512000, 687 | "udptx": 256000 688 | } 689 | 690 | # 使用SSE实时监控所有实例状态变化 691 | curl -H "X-API-Key: your-api-key" \ 692 | -H "Accept: text/event-stream" \ 693 | http://localhost:9090/api/v1/events 694 | ``` 695 | 696 | 此监控设置提供： 697 | - **实时连接数跟踪**：TCPS和UDPS字段显示当前活动连接数 698 | - **性能分析**：通过连接数和流量数据评估系统负载 699 | - **容量规划**：基于历史连接数据进行资源规划 700 | - **故障诊断**：异常的连接数变化可能指示网络问题 701 | 702 | ## 连接池类型 703 | 704 | ### 示例34: 基于QUIC的流多路复用隧道 705 | 706 | 使用QUIC协议进行连接池管理，在高延迟网络中提供更优性能： 707 | 708 | ```bash 709 | # 服务器端：启用QUIC连接池 710 | nodepass "server://0.0.0.0:10101/remote.example.com:8080?type=1&mode=2&tls=1&log=debug" 711 | 712 | # 客户端：自动从服务器接收连接池类型配置 713 | nodepass "client://server.example.com:10101/127.0.0.1:8080?mode=2&min=128&log=debug" 714 | ``` 715 | 716 | 此配置： 717 | - 使用QUIC协议进行基于UDP的多路复用流 718 | - 单个QUIC连接承载多个并发数据流 719 | - 强制使用TLS 1.3加密（自动启用） 720 | - 在丢包场景中性能更好（无队头阻塞） 721 | - 通过0-RTT支持改善连接建立 722 | - 客户端在握手时自动接收服务器的连接池类型配置 723 | 724 | ### 示例35: 使用自定义TLS证书的QUIC连接池 725 | 726 | 在生产环境部署带有验证证书的QUIC隧道： 727 | 728 | ```bash 729 | # 服务器端：使用自定义证书的QUIC连接池 730 | nodepass "server://0.0.0.0:10101/backend.internal:8080?type=1&mode=2&tls=2&crt=/etc/nodepass/cert.pem&key=/etc/nodepass/key.pem" 731 | 732 | # 客户端：自动接收连接池类型配置并进行证书验证 733 | nodepass "client://tunnel.example.com:10101/127.0.0.1:8080?mode=2&min=64&log=info" 734 | ``` 735 | 736 | 此设置： 737 | - 使用验证证书实现最高安全性 738 | - QUIC协议提供强制TLS 1.3加密 739 | - 适用于生产环境 740 | - 客户端进行完整证书验证 741 | - 连接池类型配置自动从服务器下发 742 | 743 | ### 示例36: WebSocket连接池穿透HTTP代理 744 | 745 | 在企业防火墙后使用WebSocket连接池： 746 | 747 | ```bash 748 | # 服务器端：启用WebSocket连接池（需要TLS） 749 | nodepass "server://0.0.0.0:10101/internal.backend:8080?type=2&mode=2&tls=1&log=info" 750 | 751 | # 客户端：自动接收WebSocket配置 752 | nodepass "client://wss.tunnel.com:10101/127.0.0.1:8080?mode=2&min=64" 753 | ``` 754 | 755 | 此配置： 756 | - 使用WebSocket协议可以穿透HTTP代理和CDN 757 | - **需要TLS加密** - 最少`tls=1`，生产环境建议使用带证书的`tls=2` 758 | - 使用标准HTTPS端口，容易通过防火墙 759 | - 与现有Web基础设施兼容 760 | - 支持全双工通信 761 | - 适合企业环境中仅允许HTTP/HTTPS流量的场景 762 | - 客户端自动采用服务器的连接池类型配置 763 | - **注意**：WebSocket连接池不支持不加密模式（tls=0） 764 | 765 | ### 示例37: 高并发环境的HTTP/2连接池 766 | 767 | 使用HTTP/2连接池实现高效的多路复用流和协议优化： 768 | 769 | ```bash 770 | # 服务器端：启用HTTP/2连接池（需要TLS） 771 | nodepass "server://0.0.0.0:10101/backend.internal:8080?type=3&mode=2&tls=1&log=info" 772 | 773 | # 客户端：自动接收HTTP/2配置 774 | nodepass "client://h2.tunnel.com:10101/127.0.0.1:8080?mode=2&min=64" 775 | ``` 776 | 777 | 此配置： 778 | - 使用HTTP/2协议在单个TLS连接上实现多路复用流 779 | - **需要TLS加密** - 最少`tls=1`，生产环境建议使用带证书的`tls=2` 780 | - HPACK头部压缩减少带宽使用 781 | - 高效解析的二进制帧协议 782 | - 每个流的流量控制实现最优资源利用 783 | - 与HTTP/2感知的代理和负载均衡器配合使用 784 | - 适合HTTP/HTTPS仅支持策略的环境 785 | - 客户端自动采用服务器的连接池类型配置 786 | - 适用于受益于流多路复用的高并发场景 787 | 788 | ### 示例38: 移动/高延迟网络的QUIC连接池 789 | 790 | 针对移动网络或卫星连接进行优化： 791 | 792 | ```bash 793 | # 服务器端：带自适应池大小的QUIC连接池 794 | nodepass "server://0.0.0.0:10101/api.backend:443?type=1&mode=2&max=512&tls=1&log=info" 795 | 796 | # 客户端：自动接收连接池类型，配置较大最小连接池用于移动网络 797 | nodepass "client://mobile.tunnel.com:10101/127.0.0.1:8080?mode=2&min=256&log=warn" 798 | ``` 799 | 800 | 此配置： 801 | - QUIC的基于UDP传输在NAT环境中表现更好 802 | - 更大的连接池大小补偿网络切换 803 | - 流多路复用减少连接开销 804 | - 更好地处理丢包和抖动 805 | - 0-RTT重连在网络变化后实现更快恢复 806 | - 客户端自动采用服务器的连接池类型配置 807 | 808 | ### 示例39: 连接池类型性能对比 809 | 810 | TCP、QUIC、WebSocket和HTTP/2连接池的并排比较： 811 | 812 | ```bash 813 | # 传统TCP连接池（默认） 814 | nodepass "server://0.0.0.0:10101/backend.example.com:8080?type=0&mode=2&tls=1&log=event" 815 | nodepass "client://server.example.com:10101/127.0.0.1:8080?mode=2&min=128&log=event" 816 | 817 | # QUIC连接池（现代方法） 818 | nodepass "server://0.0.0.0:10102/backend.example.com:8080?type=1&mode=2&tls=1&log=event" 819 | nodepass "client://server.example.com:10102/127.0.0.1:8081?mode=2&min=128&log=event" 820 | 821 | # WebSocket连接池（代理穿透） 822 | nodepass "server://0.0.0.0:10103/backend.example.com:8080?type=2&mode=2&tls=1&log=event" 823 | nodepass "client://server.example.com:10103/127.0.0.1:8082?mode=2&min=128&log=event" 824 | 825 | # HTTP/2连接池（多路复用流） 826 | nodepass "server://0.0.0.0:10104/backend.example.com:8080?type=3&mode=2&tls=1&log=event" 827 | nodepass "client://server.example.com:10104/127.0.0.1:8083?mode=2&min=128&log=event" 828 | ``` 829 | 830 | **TCP连接池优势**： 831 | - 与网络基础设施更广泛兼容 832 | - 已建立的协议，行为可预测 833 | - 在某些企业环境中支持更好 834 | 835 | **QUIC连接池优势**： 836 | - 通过0-RTT连接恢复降低延迟 837 | - 跨流无队头阻塞 838 | - 更好的拥塞控制和丢失恢复 839 | - 改善NAT穿透能力 840 | - 单个UDP套接字减少资源使用 841 | 842 | **WebSocket连接池优势**： 843 | - 可以穿透HTTP代理和CDN 844 | - 使用标准HTTP/HTTPS端口 845 | - 与现有Web基础设施集成 846 | - 适合企业防火墙环境 847 | 848 | **HTTP/2连接池优势**： 849 | - 在单个TCP连接上高效的流多路复用 850 | - HPACK头部压缩减少带宽 851 | - 高效解析的二进制协议 852 | - 每个流的流量控制实现资源优化 853 | - 与HTTP/2感知的基础设施配合使用 854 | - 适合HTTP/HTTPS仅支持策略的环境 855 | 856 | ### 示例40: 实时应用的QUIC连接池 857 | 858 | 为游戏、VoIP或视频流配置QUIC隧道： 859 | 860 | ```bash 861 | # 服务器端：为实时流量优化的QUIC设置 862 | nodepass "server://0.0.0.0:10101/gameserver.local:7777?type=1&mode=2&tls=1&read=30s&slot=10000" 863 | 864 | # 客户端：自动从服务器接收连接池类型配置 865 | nodepass "client://game.tunnel.com:10101/127.0.0.1:7777?mode=2&min=64&read=30s" 866 | ``` 867 | 868 | 此设置： 869 | - QUIC的流级别流量控制防止流之间的干扰 870 | - 在有损网络中比TCP连接池延迟更低 871 | - 30秒读取超时快速检测陈旧连接 872 | - 大槽位限制支持许多并发玩家/流 873 | - 减少连接建立开销 874 | - 客户端自动采用服务器的连接池类型配置 875 | 876 | **连接池类型使用场景总结**： 877 | - **TCP连接池**：标准企业环境、最大兼容性、稳定网络 878 | - **QUIC连接池**：移动网络、高延迟链路、实时应用、复杂NAT环境 879 | - **WebSocket连接池**：HTTP代理穿透、企业防火墙限制、Web基础设施集成 880 | - **HTTP/2连接池**：HTTP/HTTPS仅支持策略、高并发Web流量、与HTTP/2感知基础设施集成 881 | 882 | ## 下一步 883 | 884 | 现在您已经了解了各种使用示例，您可能想要： 885 | 886 | - 了解[配置选项](/docs/zh/configuration.md)以进行微调 887 | - 理解NodePass内部[工作原理](/docs/zh/how-it-works.md) 888 | - 查看[故障排除指南](/docs/zh/troubleshooting.md)了解常见问题 -------------------------------------------------------------------------------- /.github/copilot-instructions.md: -------------------------------------------------------------------------------- 1 | # NodePass Development Guide 2 | 3 | ## Architecture Overview 4 | 5 | NodePass is a Go-based TCP/UDP tunneling solution with a **tri-modal architecture** (Server/Client/Master) built on separation of control and data channels. 6 | 7 | ### Core Components 8 | 9 | - **`cmd/nodepass/`**: Entry point with URL-based configuration parsing 10 | - `main.go`: Simple entry that invokes `start()` with version injection 11 | - `core.go`: URL parser, logger initialization, TLS mode selection, core factory (`createCore()`) 12 | - **`internal/`**: Three operational modes sharing `common.go` base (~1970 lines): 13 | - `server.go`: Accepts tunnel connections via `tunnelHandshake()`, binds target addresses, supports bidirectional data flow 14 | - `client.go`: Initiates tunnel connections, supports single-end forwarding (`singleStart()`) and dual-end handshake (`commonStart()`) 15 | - `master.go`: RESTful API server with instance management, SSE events, gob persistence (~2165 lines) 16 | - `common.go`: Shared functionality - DNS caching, buffer pools, slot management, connection routing 17 | - **External packages** (NodePassProject org on GitHub): 18 | - `pool`: TCP connection pooling with auto-scaling (min/max capacity) 19 | - `quic`: QUIC transport with 0-RTT support 20 | - `npws`: WebSocket transport adapter 21 | - `conn`: Utilities (`DataExchange`, `StatConn` for traffic accounting, `RateLimiter` for bandwidth control) 22 | - `logs`: Structured logger with levels (none/debug/info/warn/error/event) 23 | - `cert`: TLS certificate generation and management 24 | 25 | ### Data Flow Modes 26 | 27 | 1. **Server Receives Mode** (Reverse): Server binds target address locally → signals client → client connects back → data flows: External → Server → Client → Target 28 | 2. **Server Sends Mode** (Forward): Server connects to remote target → client signals server → server creates outgoing connection → data flows: Client → Server → Remote Target 29 | 3. **Client Single-End Forwarding**: Client binds tunnel address locally (e.g., `127.0.0.1:8080`) → direct forwarding to target without server coordination (no control channel) 30 | 31 | Mode selection is **automatic** via `initTargetListener()` success/failure. Server tries binding target address; if successful = mode 1 (reverse), if fails = mode 2 (forward). Client tries binding tunnel address; if successful = single-end, if fails = dual-end. Force with `mode` query parameter (`0`=auto, `1`=reverse/single, `2`=forward/dual). 32 | 33 | ## URL-Based Configuration 34 | 35 | All configuration through URL scheme: `://@/?` 36 | 37 | **URL Structure Examples:** 38 | ``` 39 | server://password@0.0.0.0:10101/127.0.0.1:8080?tls=1&max=512 40 | client://password@server.com:10101/localhost:8080?min=64&type=1 41 | master://0.0.0.0:9090/api?log=debug&tls=2&crt=/path/cert.pem&key=/path/key.pem 42 | ``` 43 | 44 | **Critical query parameters:** 45 | - `log`: Log level - `none`|`debug`|`info`(default)|`warn`|`error`|`event` 46 | - `tls`: Encryption mode - `0` (plain TCP/UDP), `1` (self-signed cert in memory), `2` (custom cert with `crt`/`key` files) 47 | - Mode 0: No encryption, fastest but insecure 48 | - Mode 1: Auto-generated self-signed cert, no verification, protects against passive sniffing 49 | - Mode 2: Custom certificate with validation, requires both `crt` and `key` parameters pointing to PEM files 50 | - **Note**: QUIC transport (`type=1`) requires minimum `tls=1` 51 | - `type`: Pool transport protocol - `0` (TCP pool, default), `1` (QUIC with 0-RTT), `2` (WebSocket) 52 | - `mode`: Force run mode - `0` (auto-detect via binding), `1` (server=reverse/client=single-end), `2` (server=forward/client=dual-end) 53 | - `dns`: DNS cache TTL duration (default `5m`, accepts Go duration syntax like `30s`, `10m`, `1h`) 54 | - `min`: Client minimum pool capacity (default `64`) 55 | - `max`: Server maximum pool capacity (default `1024`) 56 | - `rate`: Bandwidth limit in **Mbps * 8** (e.g., `rate=100` = 100Mbps = 12.5MB/s; internal unit is bytes/sec, computed as rate*125000) 57 | - `slot`: Max concurrent connections - TCP+UDP combined (default `65536`, `0`=unlimited) 58 | - `proxy`: PROXY protocol version - `0` (disabled), `1` (v1 text format), `2` (v2 binary format) 59 | - `read`: Connection read timeout (default `0` = infinite, accepts Go duration like `30s`, `5m`) 60 | - `dial`: Local bind IP for outgoing connections (default `auto` = system routing, or specific IP like `192.168.1.100`) 61 | - Automatic fallback to system routing if specified IP fails (logged as "fallback to system auto") 62 | - `notcp`: Disable TCP forwarding - `0` (enabled), `1` (disabled) 63 | - `noudp`: Disable UDP forwarding - `0` (enabled), `1` (disabled) 64 | 65 | **Password field usage:** The `@` password portion in URLs (e.g., `mykey@server:10101`) becomes `tunnelKey` for authentication - it's NOT a system password, just a shared secret for tunnel validation. Server compares incoming `tunnelKey` via XOR+base64 encoding in handshake. 66 | 67 | Examples in `docs/en/examples.md`, full configuration reference in `docs/en/configuration.md`. 68 | 69 | ## Development Workflow 70 | 71 | ### Building 72 | 73 | ```bash 74 | # Development build 75 | cd cmd/nodepass 76 | go build -ldflags "-X main.version=dev" 77 | 78 | # Release build (via goreleaser) 79 | goreleaser build --snapshot --clean 80 | 81 | # Docker build (multi-stage, scratch-based final image) 82 | docker build --build-arg VERSION=dev -t nodepass:dev . 83 | ``` 84 | 85 | Build produces single static binary with no external dependencies. The `-ldflags "-X main.version=..."` injects version into `main.version` variable displayed in `exit()` banner. 86 | 87 | ### Testing Patterns 88 | 89 | **No test suite exists** - all testing is manual via URL invocations. Common test scenarios: 90 | 91 | ```bash 92 | # Server mode (binds :10101 for tunnel, forwards to local 8080) 93 | nodepass "server://:10101/127.0.0.1:8080?log=debug&tls=1" 94 | 95 | # Client mode (connects to server:10101, creates local listener on :8080) 96 | nodepass "client://server:10101/127.0.0.1:8080?min=128&log=debug" 97 | 98 | # Master API mode (launches API server on :10101 with /api prefix) 99 | nodepass "master://:10101/api?log=debug&tls=1" 100 | 101 | # Test QUIC transport with bandwidth limiting 102 | nodepass "server://:10101/127.0.0.1:8080?type=1&tls=1&rate=100" 103 | 104 | # Test multi-target load balancing (comma-separated targets) 105 | nodepass "client://server:10101/target1.com:80,target2.com:80,target3.com:80?mode=2" 106 | ``` 107 | 108 | **Debugging tips:** 109 | - Use `log=debug` to see connection lifecycle events, pool operations, handshake details 110 | - Check `DataExchange` log messages for connection completion status and byte counts 111 | - Monitor pool capacity with `Active()` and `Capacity()` calls logged periodically 112 | - TLS handshake failures appear as "access denied" warnings - verify `tunnelKey` matches 113 | - DNS resolution issues trigger fallback to cached addresses with warning logs 114 | 115 | ### Environment Tuning 116 | 117 | Performance constants in `common.go` (lines 93-105) are environment-configurable via `NP_*` prefix: 118 | 119 | ```bash 120 | # Increase semaphore limit for high concurrency (default 65536) 121 | export NP_SEMAPHORE_LIMIT=131072 122 | 123 | # Larger TCP buffer for high-bandwidth links (default 16384) 124 | export NP_TCP_DATA_BUF_SIZE=32768 125 | 126 | # Extend handshake timeout for slow networks (default 5s) 127 | export NP_HANDSHAKE_TIMEOUT=10s 128 | 129 | # Pool connection acquisition timeout (default 5s) 130 | export NP_POOL_GET_TIMEOUT=10s 131 | 132 | # Pool scaling intervals (defaults: min=100ms, max=1s) 133 | export NP_MIN_POOL_INTERVAL=50ms 134 | export NP_MAX_POOL_INTERVAL=2s 135 | 136 | # Health check report frequency (default 5s) 137 | export NP_REPORT_INTERVAL=10s 138 | 139 | # Service restart cooldown (default 3s) 140 | export NP_SERVICE_COOLDOWN=5s 141 | 142 | # Graceful shutdown timeout (default 5s) 143 | export NP_SHUTDOWN_TIMEOUT=10s 144 | 145 | # TLS certificate reload interval for mode 2 (default 1h) 146 | export NP_RELOAD_INTERVAL=30m 147 | ``` 148 | 149 | All duration values accept Go duration syntax (`s`, `m`, `h`). Changes require restart to take effect. 150 | 151 | ## Code Conventions 152 | 153 | ### Logging 154 | 155 | Use structured logging with `logger` from `logs.Logger`. Six levels: none/debug/info/warn/error/event. Format strings with `%v` placeholders: 156 | 157 | ```go 158 | logger.Debug("TLS cert reloaded: %v", crtFile) 159 | logger.Info("Server started: server://%v@%v/%v", key, tunnel, target) 160 | logger.Warn("tunnelHandshake: access denied: %v", remoteAddr) 161 | logger.Error("Certificate load failed: %v", err) 162 | logger.Event("Traffic stats: TCP RX=%d TX=%d", tcpRX, tcpTX) 163 | ``` 164 | 165 | **Never use `fmt.Printf`** except in `exit()` help banner. All user-facing output goes through logger. 166 | 167 | ### Error Handling 168 | 169 | Wrap errors with context using `fmt.Errorf` with `%w` verb for error chain preservation: 170 | 171 | ```go 172 | return fmt.Errorf("start: initTunnelListener failed: %w", err) 173 | return fmt.Errorf("tunnelHandshake: decode failed: %w", err) 174 | ``` 175 | 176 | Functions return `error` as last return value. Restart logic uses `err != nil && err != io.EOF` pattern - `io.EOF` signals graceful shutdown, other errors trigger restart after `serviceCooldown`. 177 | 178 | ### Connection Pool Interface 179 | 180 | All transport types (`pool.ServerPool`, `quic.ServerPool`, `npws.ServerPool`) implement unified `TransportPool` interface (defined in `common.go` line 92): 181 | 182 | ```go 183 | type TransportPool interface { 184 | // IncomingGet retrieves connection from server pool by ID with timeout 185 | IncomingGet(timeout time.Duration) (string, net.Conn, error) 186 | 187 | // OutgoingGet retrieves connection from client pool for given ID with timeout 188 | OutgoingGet(id string, timeout time.Duration) (net.Conn, error) 189 | 190 | // Flush signals pool to drop all connections and reset state 191 | Flush() 192 | 193 | // Close terminates pool and all managed connections 194 | Close() 195 | 196 | // Ready reports if pool has reached minimum capacity 197 | Ready() bool 198 | 199 | // Active returns current active connection count 200 | Active() int 201 | 202 | // Capacity returns maximum pool capacity 203 | Capacity() int 204 | 205 | // Interval returns current auto-scaling interval 206 | Interval() time.Duration 207 | 208 | // AddError increments error counter for health monitoring 209 | AddError() 210 | 211 | // ErrorCount returns cumulative error count 212 | ErrorCount() int 213 | 214 | // ResetError clears error counter 215 | ResetError() 216 | } 217 | ``` 218 | 219 | Connection IDs are generated via FNV hash: `hash := fnv.New64a(); hash.Write([]byte); id := hex.EncodeToString(hash.Sum(nil))`. Server generates IDs for incoming connections, client receives IDs via control channel. 220 | 221 | ### Buffer Pool Management 222 | 223 | **Critical**: Always return buffers to prevent memory leaks. Pools are initialized in constructor with `sync.Pool`: 224 | 225 | ```go 226 | tcpBufferPool: &sync.Pool{ 227 | New: func() any { 228 | buf := make([]byte, tcpDataBufSize) 229 | return &buf 230 | }, 231 | } 232 | ``` 233 | 234 | Usage pattern: 235 | ```go 236 | buffer := c.getTCPBuffer() // Acquire from pool 237 | defer c.putTCPBuffer(buffer) // ALWAYS return via defer 238 | // Use buffer for I/O operations... 239 | ``` 240 | 241 | UDP buffers follow identical pattern with `getUDPBuffer()`/`putUDPBuffer()`. Buffer sizes configurable via `NP_TCP_DATA_BUF_SIZE` (default 16384) and `NP_UDP_DATA_BUF_SIZE` (default 16384). 242 | 243 | ### Slot Management 244 | 245 | Connection slots limit concurrent connections via atomic counters. Check before accepting connections: 246 | 247 | ```go 248 | if !c.tryAcquireSlot(isUDP) { 249 | logger.Warn("Slot limit reached: %d", c.slotLimit) 250 | conn.Close() 251 | return 252 | } 253 | defer c.releaseSlot(isUDP) 254 | ``` 255 | 256 | Slots are combined TCP+UDP count. `slotLimit=0` disables limit. Slot tracking uses `atomic.AddInt32()` for thread-safe counters. 257 | 258 | ### Context Management 259 | 260 | Each mode initializes context in `start()` method: 261 | 262 | ```go 263 | func (c *Common) initContext() { 264 | c.ctx, c.cancel = context.WithCancel(context.Background()) 265 | } 266 | ``` 267 | 268 | Graceful shutdown via `shutdown(ctx, stopFunc)` helper: 269 | 1. Calls `stopFunc()` to close listeners/pools 270 | 2. Waits for `ctx.Done()` or `shutdownTimeout` (default 5s) 271 | 3. Logs completion/timeout status 272 | 273 | Restart loop pattern in `Run()` methods: 274 | ```go 275 | for ctx.Err() == nil { 276 | if err := c.start(); err != nil && err != io.EOF { 277 | c.logger.Error("Client error: %v", err) 278 | c.stop() 279 | select { 280 | case <-ctx.Done(): 281 | return 282 | case <-time.After(serviceCooldown): // 3s default 283 | } 284 | logInfo("Client restart") 285 | } 286 | } 287 | ``` 288 | 289 | Use `contextCheckInterval` (50ms) in tight loops: `select { case <-ctx.Done(): return; case <-time.After(contextCheckInterval): }` 290 | 291 | ### Traffic Accounting 292 | 293 | All connections wrapped in `conn.StatConn` for automatic byte counting and rate limiting: 294 | 295 | ```go 296 | targetConn = &conn.StatConn{ 297 | Conn: targetConn, 298 | RX: &c.tcpRX, // Points to Common's atomic uint64 counter 299 | TX: &c.tcpTX, // Points to Common's atomic uint64 counter 300 | Rate: c.rateLimiter, // Optional rate limiter (nil if rate=0) 301 | } 302 | ``` 303 | 304 | Counters updated atomically on every Read/Write. Master mode reads counters to compute traffic deltas. `DataExchange()` from `conn` package handles bidirectional copy with automatic accounting: 305 | 306 | ```go 307 | conn.DataExchange(connA, connB, readTimeout, buffer1, buffer2) 308 | ``` 309 | 310 | Rate limiting initialized via `initRateLimiter()` if `rateLimit > 0` (rate in bytes/sec = query param * 125000). 311 | 312 | ## Master Mode Specifics 313 | 314 | ### Instance Management 315 | 316 | Instances stored in `sync.Map` (concurrent-safe), persisted to `gob/nodepass.gob` using `gob` encoding. State file layout: 317 | - API key (auto-generated 32-byte hex on first start) 318 | - Instance map serialization with all fields except those tagged `gob:"-"` 319 | 320 | Key `Instance` struct fields: 321 | ```go 322 | type Instance struct { 323 | ID string // 8-char hex identifier 324 | Alias string // User-friendly name 325 | Type string // "server" or "client" 326 | Status string // "running", "stopped", "error" 327 | URL string // Original user-provided URL 328 | Config string // Computed URL with all defaults filled 329 | Restart bool // Auto-restart policy 330 | Meta Meta // Metadata with peer info and tags 331 | cmd *exec.Cmd // Running subprocess (not serialized) 332 | stopped chan struct{} // Shutdown coordination (not serialized) 333 | // Traffic baseline tracking (not serialized) 334 | TCPRXBase/TCPTXBase/UDPRXBase/UDPTXBase uint64 335 | } 336 | ``` 337 | 338 | Instance lifecycle: 339 | 1. **Create**: `POST /instances` with URL → generates ID → spawns subprocess → stores in `sync.Map` → persists to gob 340 | 2. **Monitor**: Periodic goroutine reads `/proc//status` for traffic stats, computes deltas from baseline 341 | 3. **Update**: `PATCH /instances/{id}` with actions: `start`, `stop`, `restart`, `reset-traffic`, `toggle-restart` 342 | 4. **Delete**: `DELETE /instances/{id}` → stops subprocess → removes from map → re-persists gob 343 | 344 | Subprocess management uses `exec.CommandContext()` with instance-specific context. Logs captured via custom `InstanceLogWriter` that parses structured logs and emits SSE events. 345 | 346 | ### SSE Events 347 | 348 | Real-time updates via `/events` endpoint (Server-Sent Events). Event types and payloads: 349 | 350 | - `initial`: Full instance list on connection (sent once per subscriber) 351 | - `create`: New instance created (includes full Instance object) 352 | - `update`: Instance state changed (includes full Instance object with updated fields) 353 | - `delete`: Instance removed (includes ID only) 354 | - `shutdown`: Master shutting down (no payload) 355 | - `log`: Instance log line (includes `instance.id` and `logs` fields) 356 | 357 | Subscribers stored in `sync.Map` with unique IDs. Event broadcasting via `notifyChannel` (buffered channel). Connection management pattern: 358 | 359 | ```go 360 | subscriber := &Subscriber{id: generateID(), channel: make(chan *InstanceEvent, 100)} 361 | m.subscribers.Store(subscriber.id, subscriber) 362 | defer m.subscribers.Delete(subscriber.id) 363 | 364 | for { 365 | select { 366 | case event := <-subscriber.channel: 367 | fmt.Fprintf(w, "event: %s\ndata: %s\n\n", event.Type, jsonData) 368 | flusher.Flush() 369 | case <-r.Context().Done(): 370 | return 371 | } 372 | } 373 | ``` 374 | 375 | ### API Authentication 376 | 377 | Auto-generated API key on first start. Special instance ID `********` (8 asterisks) reserved for key operations: 378 | - `GET /instances/********`: Retrieve current API key 379 | - `PATCH /instances/********` with `{"action": "restart"}`: Regenerate API key 380 | 381 | Protected endpoints check `X-API-Key` header. Public endpoints: `/openapi.json`, `/docs` (Swagger UI). 382 | 383 | Key validation pattern: 384 | ```go 385 | if apiKey := r.Header.Get("X-API-Key"); apiKey != m.apiKey { 386 | http.Error(w, "Unauthorized", http.StatusUnauthorized) 387 | return 388 | } 389 | ``` 390 | 391 | ### TCPing Functionality 392 | 393 | Built-in connectivity testing via `GET /tcping?target=host:port`. Concurrent limit enforced via buffered semaphore (`tcpingSem chan struct{}` with capacity 10). Returns JSON: 394 | 395 | ```json 396 | { 397 | "target": "example.com:443", 398 | "connected": true, 399 | "latency": 42, 400 | "error": null 401 | } 402 | ``` 403 | 404 | Timeout handling: 1s for semaphore acquisition, 5s for TCP dial. Latency measured in milliseconds. 405 | 406 | ## Integration Points 407 | 408 | ### External Package Boundaries 409 | 410 | - **`github.com/NodePassProject/pool`**: TCP connection pooling with dynamic scaling 411 | - **`github.com/NodePassProject/quic`**: QUIC-based transport (0-RTT support) 412 | - **`github.com/NodePassProject/npws`**: WebSocket transport wrapper 413 | - **`github.com/NodePassProject/conn`**: Connection helpers (`DataExchange`, `StatConn`, `RateLimiter`) 414 | - **`github.com/NodePassProject/cert`**: TLS certificate generation/management 415 | 416 | When modifying transport behavior, coordinate with corresponding package version in `go.mod`. 417 | 418 | ### DNS Caching 419 | 420 | Custom DNS resolution via `dnsCacheEntry` stored in `sync.Map` with TTL. Functions: `getTunnelTCPAddr()`, `getTargetTCPAddr()`. 421 | 422 | ### Handshake Protocol 423 | 424 | **Server-side handshake** (`server.go` lines 208-279): 425 | 1. Creates HTTP server with `HandlerFunc` on `tunnelListener` 426 | 2. Validates incoming HTTP GET request to path `/` 427 | 3. Extracts `Authorization` header and verifies Bearer token using HMAC-SHA256: 428 | - Client sends: `Authorization: Bearer ` 429 | - Server verifies via `hmac.Equal()` constant-time comparison 430 | 4. Extracts client IP from `RemoteAddr()` (strips port if present) 431 | 5. Responds with JSON config containing: 432 | ```json 433 | { 434 | "flow": "", // Direction: "+" or "-" 435 | "max": , // Server pool capacity 436 | "tls": "", // TLS mode: "0", "1", or "2" 437 | "type": "" // Transport: "0" (TCP), "1" (QUIC), "2" (WS) 438 | } 439 | ``` 440 | 6. Closes HTTP server after successful handshake 441 | 7. Recreates `tunnelListener` for subsequent pool connections 442 | 443 | **Client-side handshake** (`client.go` lines 231-273): 444 | 1. Constructs HTTP GET request to `http:///` 445 | 2. Sets `Host` header to `tunnelName` for DNS-based routing 446 | 3. Generates HMAC-SHA256 token: `hex.EncodeToString(hmac.New(sha256.New, []byte(tunnelKey)).Sum(nil))` 447 | 4. Sends `Authorization: Bearer ` header 448 | 5. Receives JSON response and decodes config 449 | 6. Updates local configuration: 450 | - `dataFlow`: Controls connection direction 451 | - `maxPoolCapacity`: Adopts server's pool size 452 | - `tlsCode`: Applies server's TLS settings to data connections 453 | - `poolType`: Switches transport type if needed 454 | 7. Logs loaded configuration for debugging 455 | 456 | **Authentication mechanism**: HMAC-SHA256 provides cryptographic authentication without transmitting the raw `tunnelKey`. Token generation in `common.go` lines 248-256 uses standard library `crypto/hmac` and `crypto/sha256`. 457 | 458 | ### Load Balancing & Failover 459 | 460 | Multi-target support via comma-separated addresses in URL path. `dialWithRotation()` (`common.go` lines 385-450) implements: 461 | - Round-robin distribution using atomic counter 462 | - Automatic failover on connection errors 463 | - Single-target fast path optimization 464 | - Dynamic DNS resolution per attempt 465 | 466 | Example: `client://server:10101/target1:80,target2:80,target3:80` rotates across three backends. 467 | 468 | ## Common Pitfalls 469 | 470 | 1. **TLS Mode vs Pool Type**: `tls` parameter applies to data channel, `type` parameter selects transport (QUIC requires `tls=1` minimum) 471 | 2. **URL Password Field**: Used as `tunnelKey` for authentication - not actual password 472 | 3. **Buffer Pool Management**: Always return buffers via `putTCPBuffer()`/`putUDPBuffer()` to prevent leaks 473 | 4. **Signal Channel Buffering**: `signalChan` has `semaphoreLimit` capacity - blocks if full 474 | 5. **Instance Config vs URL**: Master stores both user-provided URL and computed config string with all defaults 475 | 476 | ## Key File References 477 | 478 | - **`internal/common.go`** (1970 lines): Core shared functionality 479 | - Lines 29-85: `Common` struct definition with all shared fields 480 | - Lines 93-122: Environment-configurable performance constants 481 | - Lines 140-165: Buffer pool management (`getTCPBuffer`, `putTCPBuffer`, `getUDPBuffer`, `putUDPBuffer`) 482 | - Lines 168-200: Slot management (`tryAcquireSlot`, `releaseSlot`) 483 | - Lines 250-270: Handshake encoding/decoding (`xor`, `encode`, `decode`) 484 | - Lines 385-450: Load balancing with failover (`dialWithRotation`) 485 | - Lines 722-726: Rate limiter initialization 486 | - Lines 1229, 1568: `DataExchange` calls for bidirectional traffic 487 | 488 | - **`internal/server.go`** (320 lines): Server mode implementation 489 | - Lines 32-62: Server constructor with pool initialization 490 | - Lines 65-106: Run loop with restart logic 491 | - Lines 109-183: Start sequence and mode detection 492 | - Lines 194-320: Tunnel handshake with concurrent connection acceptance 493 | 494 | - **`internal/client.go`** (273 lines): Client mode implementation 495 | - Lines 33-61: Client constructor 496 | - Lines 111-132: Mode detection logic (single-end vs dual-end) 497 | - Lines 135-210: Pool initialization per transport type 498 | - Lines 218-273: Tunnel handshake with config reception 499 | 500 | - **`internal/master.go`** (2165 lines): Master API server 501 | - Lines 67-90: Master struct definition 502 | - Lines 91-124: Instance struct with traffic tracking 503 | - Lines 138-145: InstanceEvent for SSE 504 | - Lines 330+: RESTful handlers and instance management 505 | 506 | - **`cmd/nodepass/core.go`** (165 lines): Entry point and configuration 507 | - Lines 17-35: URL parsing and core creation 508 | - Lines 38-59: Logger initialization 509 | - Lines 62-75: Core factory (`createCore`) 510 | - Lines 78-143: TLS configuration with three modes 511 | -------------------------------------------------------------------------------- /docs/en/troubleshooting.md: -------------------------------------------------------------------------------- 1 | # Troubleshooting Guide 2 | 3 | This guide helps you diagnose and resolve common issues you might encounter when using NodePass. For each problem, we provide possible causes and step-by-step solutions. 4 | 5 | ## Connection Issues 6 | 7 | ### Unable to Establish Tunnel Connection 8 | 9 | **Symptoms**: Client cannot connect to the server's tunnel endpoint, or connection is immediately dropped. 10 | 11 | **Possible Causes and Solutions**: 12 | 13 | 1. **Network Connectivity Issues** 14 | - Verify basic connectivity with `ping` or `telnet` to the server address 15 | - Check if the specified port is reachable: `telnet server.example.com 10101` 16 | - Ensure no firewall is blocking the tunnel port (typically 10101) 17 | 18 | 2. **Server Not Running** 19 | - Verify the NodePass server is running with `ps aux | grep nodepass` on Linux/macOS 20 | - Check server logs for any startup errors 21 | - Try restarting the server process 22 | 23 | 3. **Incorrect Addressing** 24 | - Double-check the tunnel address format in your client command 25 | - Ensure you're using the correct hostname/IP and port 26 | - If using DNS names, verify they resolve to the correct IP addresses 27 | 28 | 4. **TLS Configuration Mismatch** 29 | - If server requires TLS but client doesn't support it, connection will fail 30 | - Check server logs for TLS handshake errors 31 | - Ensure certificates are correctly configured if using TLS mode 2 32 | 33 | ### Data Not Flowing Through the Tunnel 34 | 35 | **Symptoms**: Tunnel connection established, but application data isn't reaching the destination. 36 | 37 | **Possible Causes and Solutions**: 38 | 39 | 1. **Target Service Not Running** 40 | - Verify the target service is running on both server and client sides 41 | - Check if you can connect directly to the service locally 42 | 43 | 2. **Port Conflicts** 44 | - Ensure the target port isn't already in use by another application 45 | - Use `netstat -tuln` to check for port usage 46 | 47 | 3. **Protocol Mismatch** 48 | - Verify you're tunneling the correct protocol (TCP vs UDP) 49 | - Some applications require specific protocol support 50 | 51 | 4. **Incorrect Target Address** 52 | - Double-check the target address in both server and client commands 53 | - For server-side targets, ensure they're reachable from the server 54 | - For client-side targets, ensure they're reachable from the client 55 | 56 | ### Connection Stability Issues 57 | 58 | **Symptoms**: Tunnel works initially but disconnects frequently or becomes unresponsive. 59 | 60 | **Possible Causes and Solutions**: 61 | 62 | 1. **Network Instability** 63 | - Check for packet loss or high latency in your network 64 | - Consider a more stable network connection for production deployments 65 | 66 | 2. **Resource Constraints** 67 | - Monitor CPU and memory usage on both client and server 68 | - Adjust pool parameters if resources are being exhausted (see Performance section) 69 | - Check file descriptor limits with `ulimit -n` on Linux/macOS 70 | 71 | 3. **Timeout Configuration** 72 | - Adjust `NP_UDP_DIAL_TIMEOUT` if using UDP with slow response times 73 | - Increase `read` parameter in URL for long-running transfers (default: 0) 74 | - Consider adjusting `NP_TCP_DIAL_TIMEOUT` for unstable network conditions 75 | 76 | 4. **Overloaded Server** 77 | - Check server logs for signs of connection overload 78 | - Adjust `max` parameter and `NP_SEMAPHORE_LIMIT` to handle the load 79 | - Consider scaling horizontally with multiple NodePass instances 80 | 81 | ## Certificate Issues 82 | 83 | ### TLS Handshake Failures 84 | 85 | **Symptoms**: Connection attempts fail with TLS handshake errors. 86 | 87 | **Possible Causes and Solutions**: 88 | 89 | 1. **Invalid Certificate** 90 | - Verify certificate validity: `openssl x509 -in cert.pem -text -noout` 91 | - Ensure the certificate hasn't expired 92 | - Check that the certificate is issued for the correct domain/IP 93 | 94 | 2. **Missing or Inaccessible Certificate Files** 95 | - Confirm file paths to certificates and keys are correct 96 | - Verify file permissions allow the NodePass process to read them 97 | - Check for file corruption by opening certificates in a text editor 98 | 99 | 3. **Certificate Trust Issues** 100 | - If using custom CAs, ensure they are properly trusted 101 | - For self-signed certificates, confirm TLS mode 1 is being used 102 | - For verified certificates, ensure the CA chain is complete 103 | 104 | 4. **Key Format Problems** 105 | - Ensure private keys are in the correct format (usually PEM) 106 | - Check for passphrase protection on private keys (not supported directly) 107 | 108 | ### Certificate Renewal Issues 109 | 110 | **Symptoms**: After certificate renewal, secure connections start failing. 111 | 112 | **Possible Causes and Solutions**: 113 | 114 | 1. **New Certificate Not Loaded** 115 | - Restart NodePass to force loading of new certificates 116 | - Check if `RELOAD_INTERVAL` is set correctly to automatically detect changes 117 | 118 | 2. **Certificate Chain Incomplete** 119 | - Ensure the full certificate chain is included in the certificate file 120 | - Verify chain order: your certificate first, then intermediate certificates 121 | 122 | 3. **Key Mismatch** 123 | - Verify the new certificate matches the private key: 124 | ```bash 125 | openssl x509 -noout -modulus -in cert.pem | openssl md5 126 | openssl rsa -noout -modulus -in key.pem | openssl md5 127 | ``` 128 | - If outputs differ, certificate and key don't match 129 | 130 | ## Performance Optimization 131 | 132 | ### High Latency 133 | 134 | **Symptoms**: Connections work but have noticeable delays. 135 | 136 | **Possible Causes and Solutions**: 137 | 138 | 1. **Pool Configuration** 139 | - Increase `min` parameter to have more connections ready 140 | - Decrease `MIN_POOL_INTERVAL` to create connections faster 141 | - Adjust `NP_SEMAPHORE_LIMIT` if connection queue is backing up 142 | 143 | 2. **Network Path** 144 | - Check for network congestion or high-latency links 145 | - Consider deploying NodePass closer to either the client or server 146 | - Use a traceroute to identify potential bottlenecks 147 | 148 | 3. **TLS Overhead** 149 | - If extreme low latency is required and security is less critical, consider using TLS mode 0 150 | - For a balance, use TLS mode 1 with session resumption 151 | 152 | 4. **Resource Contention** 153 | - Ensure the host system has adequate CPU and memory 154 | - Check for other processes competing for resources 155 | - Consider dedicated hosts for high-traffic deployments 156 | 157 | ### High CPU Usage 158 | 159 | **Symptoms**: NodePass process consuming excessive CPU resources. 160 | 161 | **Possible Causes and Solutions**: 162 | 163 | 1. **Pool Thrashing** 164 | - If pool is constantly creating and destroying connections, adjust timings 165 | - Increase `MIN_POOL_INTERVAL` to reduce connection creation frequency 166 | - Find a good balance for `min` and `max` pool parameters 167 | 168 | 2. **Excessive Logging** 169 | - Reduce log level from debug to info or warn for production use 170 | - Check if logs are being written to a slow device 171 | 172 | 3. **TLS Overhead** 173 | - TLS handshakes are CPU-intensive; consider session caching 174 | - Use TLS mode 1 instead of mode 2 if certificate validation is less critical 175 | 176 | 4. **Traffic Volume** 177 | - High throughput can cause CPU saturation 178 | - Consider distributing traffic across multiple NodePass instances 179 | - Vertical scaling (more CPU cores) may be necessary for very high throughput 180 | 181 | ### Memory Leaks 182 | 183 | **Symptoms**: NodePass memory usage grows continuously over time. 184 | 185 | **Possible Causes and Solutions**: 186 | 187 | 1. **Connection Leaks** 188 | - Ensure `NP_SHUTDOWN_TIMEOUT` is sufficient to properly close connections 189 | - Check for proper error handling in custom scripts or management code 190 | - Monitor connection counts with system tools like `netstat` 191 | 192 | 2. **Pool Size Issues** 193 | - If `max` parameter is very large, memory usage will be higher 194 | - Monitor actual pool usage vs. configured capacity 195 | - Adjust capacity based on actual concurrent connection needs 196 | 197 | 3. **Debug Logging** 198 | - Extensive debug logging can consume memory in high-traffic scenarios 199 | - Use appropriate log levels for production environments 200 | 201 | ## UDP-Specific Issues 202 | 203 | ### UDP Data Loss 204 | 205 | **Symptoms**: UDP packets are not reliably forwarded through the tunnel. 206 | 207 | **Possible Causes and Solutions**: 208 | 209 | 1. **Buffer Size Limitations** 210 | - If UDP packets are large, increase `UDP_DATA_BUF_SIZE` 211 | - Default of 8192 bytes may be too small for some applications 212 | 213 | 2. **Timeout Issues** 214 | - If responses are slow, increase `NP_UDP_DIAL_TIMEOUT` 215 | - Adjust `read` parameter for longer session timeouts 216 | - For applications with variable response times, find an optimal balance 217 | 218 | 3. **High Packet Rate** 219 | - UDP is handled one datagram at a time; very high rates may cause issues 220 | - Consider increasing pool capacity for high-traffic UDP applications 221 | 222 | 4. **Protocol Expectations** 223 | - Some UDP applications expect specific behavior regarding packet order or timing 224 | - NodePass provides best-effort forwarding but cannot guarantee UDP properties beyond what the network provides 225 | 226 | ### UDP Connection Tracking 227 | 228 | **Symptoms**: UDP sessions disconnect prematurely or fail to establish. 229 | 230 | **Possible Causes and Solutions**: 231 | 232 | 1. **Connection Mapping** 233 | - Verify client configurations match server expectations 234 | - Check for firewalls that may be timing out UDP session tracking 235 | 236 | 2. **Application UDP Timeout** 237 | - Some applications have built-in UDP session timeouts 238 | - May need to adjust application-specific keepalive settings 239 | 240 | ## DNS Issues 241 | 242 | ### DNS Resolution Failures 243 | 244 | **Symptoms**: Connections fail with "no such host" or DNS lookup errors. 245 | 246 | **Solutions**: 247 | 248 | 1. **Verify System DNS Configuration** 249 | - Verify resolution works: `nslookup example.com` 250 | - Check system's DNS settings (NodePass uses system resolver) 251 | - Ensure network connectivity is working 252 | 253 | 2. **Network Connectivity** 254 | - Check if firewall blocks UDP port 53 255 | - Verify domain reachability 256 | - Test with alternative domains to isolate issue 257 | 258 | ### DNS Caching Problems 259 | 260 | **Symptoms**: Resolution returns stale IPs, connections go to wrong endpoints. 261 | 262 | **Solutions**: 263 | 264 | 1. **Adjust Cache TTL** (default 5 minutes) 265 | - Dynamic environments: `dns=1m` 266 | - Stable environments: `dns=30m` 267 | 268 | 2. **Load Balancing Scenarios** 269 | - Use shorter TTL: `dns=30s` 270 | - Or use IP addresses directly to bypass DNS caching 271 | 272 | ### DNS Performance Optimization 273 | 274 | **Symptoms**: High connection latency, slow startup. 275 | 276 | **Solutions**: 277 | 278 | 1. **Optimize Cache TTL** 279 | - Increase TTL for stable environments: `dns=1h` 280 | - Reduce TTL for dynamic environments: `dns=1m` 281 | - Balance between freshness and performance 282 | 283 | 2. **Reduce DNS Queries** 284 | - Use IP addresses directly for performance-critical scenarios 285 | - Increase TTL for stable hostnames 286 | - Pre-resolve addresses when possible 287 | 288 | ## Master API Issues 289 | 290 | ### API Accessibility Problems 291 | 292 | **Symptoms**: Cannot connect to the master API endpoint. 293 | 294 | **Possible Causes and Solutions**: 295 | 296 | 1. **Endpoint Configuration** 297 | - Verify API address and port in the master command 298 | - Check if the API server is bound to the correct network interface 299 | 300 | 2. **TLS Configuration** 301 | - If using HTTPS (TLS modes 1 or 2), ensure client tools support TLS 302 | - For testing, use `curl -k` to skip certificate validation 303 | 304 | 3. **Custom Prefix Issues** 305 | - If using a custom API prefix, ensure it's included in all requests 306 | - Check URL formatting in API clients and scripts 307 | 308 | ### Instance Management Failures 309 | 310 | **Symptoms**: Cannot create, control, or delete instances through the API. 311 | 312 | **Possible Causes and Solutions**: 313 | 314 | 1. **JSON Format Issues** 315 | - Verify request body is valid JSON 316 | - Check for required fields in API requests 317 | 318 | 2. **URL Parsing Problems** 319 | - Ensure instance URLs are properly formatted and URL-encoded if necessary 320 | - Verify URL parameters use the correct format 321 | 322 | 3. **Instance State Conflicts** 323 | - Cannot delete running instances without stopping them first 324 | - Check current instance state with GET before performing actions 325 | 326 | 4. **Permission Issues** 327 | - Ensure the NodePass master has sufficient permissions to create processes 328 | - Check file system permissions for any referenced certificates or keys 329 | 330 | ## Data Recovery 331 | 332 | ### Master State File Corruption 333 | 334 | **Symptoms**: Master mode fails to start showing state file corruption errors, or instance data is lost. 335 | 336 | **Possible Causes and Solutions**: 337 | 338 | 1. **Recovery using automatic backup file** 339 | - NodePass automatically creates backup file `nodepass.gob.backup` every hour 340 | - Stop the NodePass master service 341 | - Copy backup file as main file: `cp nodepass.gob.backup nodepass.gob` 342 | - Restart the master service 343 | 344 | 2. **Manual state file recovery** 345 | ```bash 346 | # Stop NodePass service 347 | pkill nodepass 348 | 349 | # Backup corrupted file (optional) 350 | mv nodepass.gob nodepass.gob.corrupted 351 | 352 | # Use backup file 353 | cp nodepass.gob.backup nodepass.gob 354 | 355 | # Restart service 356 | nodepass "master://0.0.0.0:9090?log=info" 357 | ``` 358 | 359 | 3. **When backup file is also corrupted** 360 | - Remove corrupted state files: `rm nodepass.gob*` 361 | - Restart master, which will create new state file 362 | - Need to reconfigure all instances and settings 363 | 364 | 4. **Preventive backup recommendations** 365 | - Regularly backup `nodepass.gob` to external storage 366 | - Adjust backup frequency: set environment variable `export NP_RELOAD_INTERVAL=30m` 367 | - Monitor state file size, abnormal growth may indicate issues 368 | 369 | **Best Practices**: 370 | - In production environments, recommend regularly backing up `nodepass.gob` to different storage locations 371 | - Use configuration management tools to save text-form backups of instance configurations 372 | 373 | ## Connection Pool Type Issues 374 | 375 | ### QUIC Pool Connection Failures 376 | 377 | **Symptoms**: QUIC pool tunnel fails to establish when `type=1` is enabled. 378 | 379 | **Possible Causes and Solutions**: 380 | 381 | 1. **UDP Port Blocked** 382 | - Verify UDP port is accessible on both server and client 383 | - Check firewall rules: `sudo ufw allow 10101/udp` (Linux example) 384 | - Test UDP connectivity with `nc -u server.example.com 10101` 385 | - Some ISPs or networks block or throttle UDP traffic 386 | 387 | 2. **TLS Configuration Issues** 388 | - QUIC requires TLS to be enabled (minimum `tls=1`) 389 | - If `type=1` is set but TLS is disabled, system auto-enables `tls=1` 390 | - For production, use `tls=2` with valid certificates 391 | - Check certificate validity for QUIC connections 392 | 393 | 3. **Client-Server Pool Type Mismatch** 394 | - Both server and client must use same `type` setting 395 | - Server with `type=1` requires client with `type=1` 396 | - Server with `type=0` requires client with `type=0` 397 | - Check logs for "QUIC connection not available" errors 398 | 399 | 4. **Mode Compatibility** 400 | - QUIC only works in dual-end handshake mode (mode=2) 401 | - Not available in single-end forwarding mode (mode=1) 402 | - System will fall back to TCP pool if mode incompatible 403 | 404 | ### WebSocket Pool Connection Failures 405 | 406 | **Symptoms**: WebSocket pool tunnel fails to establish when `type=2` is enabled. 407 | 408 | **Possible Causes and Solutions**: 409 | 410 | 1. **HTTP/WebSocket Port Blocked** 411 | - Verify TCP port is accessible with WebSocket protocol support 412 | - Check firewall rules and proxy configurations 413 | - Some proxies or CDNs may interfere with WebSocket upgrade 414 | - Test connectivity with WebSocket client tools 415 | 416 | 2. **TLS Configuration Issues** 417 | - WebSocket Secure (WSS) requires TLS to be enabled (minimum `tls=1`) 418 | - **WebSocket pool does NOT support unencrypted mode** - `tls=0` is not allowed for type=2 419 | - If `type=2` is set but TLS is disabled, system will automatically enforce `tls=1` 420 | - For production, use `tls=2` with valid certificates 421 | - Check certificate validity for WSS connections 422 | 423 | 3. **Client-Server Pool Type Mismatch** 424 | - Both server and client must use same `type` setting 425 | - Server with `type=2` requires client with `type=2` 426 | - Configuration is automatically delivered during handshake 427 | - Check logs for "WebSocket connection not available" errors 428 | 429 | ### HTTP/2 Pool Connection Failures 430 | 431 | **Symptoms**: HTTP/2 pool tunnel fails to establish when `type=3` is enabled. 432 | 433 | **Possible Causes and Solutions**: 434 | 435 | 1. **TCP Port or HTTP/2 Protocol Blocked** 436 | - Verify TCP port is accessible with HTTP/2 protocol support 437 | - Check firewall rules and network policies 438 | - Some networks may block or inspect HTTPS traffic 439 | - Test connectivity with HTTP/2-capable client tools 440 | 441 | 2. **TLS Configuration Issues** 442 | - HTTP/2 requires TLS to be enabled (minimum `tls=1`) 443 | - If `type=3` is set but TLS is disabled, system will automatically enforce `tls=1` 444 | - For production, use `tls=2` with valid certificates 445 | - HTTP/2 requires TLS 1.3 with ALPN (Application-Layer Protocol Negotiation) 446 | - Check certificate validity and ALPN configuration 447 | 448 | 3. **Client-Server Pool Type Mismatch** 449 | - Both server and client must use same `type` setting 450 | - Server with `type=3` requires client with `type=3` 451 | - Configuration is automatically delivered during handshake 452 | - Check logs for "HTTP/2 connection not available" errors 453 | 454 | 4. **Mode Compatibility** 455 | - HTTP/2 pool only works in dual-end handshake mode (mode=2) 456 | - Not available in single-end forwarding mode (mode=1) 457 | - System will fall back to TCP pool if mode incompatible 458 | 459 | 5. **HTTP/2 Protocol Negotiation Failures** 460 | - Verify ALPN extension is enabled and negotiates "h2" protocol 461 | - Some older TLS implementations may not support ALPN 462 | - Check logs for protocol negotiation errors 463 | - Ensure both endpoints support HTTP/2 over TLS 464 | 465 | ### QUIC Pool Performance Issues 466 | 467 | **Symptoms**: QUIC pool tunnel has lower performance than expected or worse than TCP pool. 468 | 469 | **Possible Causes and Solutions**: 470 | 471 | 1. **Network Path Issues** 472 | - Some networks deprioritize or shape UDP traffic 473 | - Check if network middleboxes are interfering with QUIC 474 | - Consider testing with TCP pool (`type=0`) for comparison 475 | - Monitor packet loss rates - QUIC performs better with low loss 476 | 477 | 2. **Pool Capacity Configuration** 478 | - Increase `min` and `max` parameters for higher throughput 479 | - QUIC streams share single UDP connection - adequate capacity needed 480 | - Monitor stream utilization with `log=debug` 481 | - Balance between stream count and resource usage 482 | 483 | 3. **Certificate Overhead** 484 | - TLS 1.3 handshake (mandatory for QUIC) can add initial latency 485 | - Use 0-RTT resumption for faster reconnection 486 | - Ensure proper certificate chain to avoid validation delays 487 | 488 | 4. **Application Compatibility** 489 | - Some applications may not work optimally over QUIC streams 490 | - Test with both TCP and QUIC pools to compare performance 491 | - Consider TCP pool for applications requiring strict ordering 492 | 493 | ### WebSocket Pool Performance Issues 494 | 495 | **Symptoms**: WebSocket pool tunnel has lower performance than expected. 496 | 497 | **Possible Causes and Solutions**: 498 | 499 | 1. **Proxy/CDN Overhead** 500 | - WebSocket connections through proxies may add latency 501 | - Check if intermediate proxies are buffering traffic 502 | - Consider using TCP pool (`type=0`) or QUIC pool (`type=1`) for comparison 503 | - Direct connections usually perform better than proxied 504 | 505 | 2. **Frame Overhead** 506 | - WebSocket protocol adds framing overhead to each message 507 | - Larger message sizes reduce relative overhead 508 | - Monitor frame sizes and adjust application behavior if needed 509 | - Balance between latency and throughput 510 | 511 | 3. **TLS Handshake Overhead** 512 | - WSS requires TLS handshake for each connection 513 | - Use connection pooling to amortize handshake costs 514 | - Increase `min` and `max` parameters for better performance 515 | 516 | ### QUIC Stream Exhaustion 517 | 518 | **Symptoms**: "Insufficient streams" errors or connection timeouts when using QUIC. 519 | 520 | **Possible Causes and Solutions**: 521 | 522 | 1. **Pool Capacity Too Low** 523 | - Increase `max` parameter on server side 524 | - Increase `min` parameter on client side 525 | - Monitor active stream count in logs 526 | - Default capacity may be insufficient for high-concurrency scenarios 527 | 528 | 2. **Stream Leaks** 529 | - Check application properly closes connections 530 | - Monitor stream count over time for gradual increase 531 | - Restart instances to clear leaked streams 532 | - Review application code for connection handling 533 | 534 | 3. **QUIC Connection Dropped** 535 | - Check keep-alive settings (configured via `NP_REPORT_INTERVAL`) 536 | - Monitor for "QUIC connection not available" errors 537 | - NAT timeout may drop UDP connection - adjust NAT settings 538 | - Increase connection timeout if network latency is high 539 | 540 | ### Connection Pool Type Decision 541 | 542 | **When to Use QUIC Pool** (`type=1`): 543 | - Mobile networks or frequently changing network conditions 544 | - High-latency connections (satellite, long-distance) 545 | - NAT-heavy environments where UDP traversal is better 546 | - Real-time applications benefiting from stream independence 547 | - Scenarios where 0-RTT reconnection provides value 548 | 549 | **When to Use WebSocket Pool** (`type=2`): 550 | - Need to traverse HTTP proxies or CDNs 551 | - Corporate environments allowing only HTTP/HTTPS traffic 552 | - Environments where firewalls block raw TCP connections 553 | - Need compatibility with existing web infrastructure 554 | - Web proxy or VPN alternative solutions 555 | 556 | **When to Use TCP Pool** (`type=0`): 557 | - Networks that block or severely throttle UDP traffic 558 | - Applications requiring strict TCP semantics 559 | - Corporate environments with UDP restrictions 560 | - Maximum compatibility requirements 561 | - When testing shows better performance with TCP 562 | 563 | **Comparison Testing**: 564 | ```bash 565 | # Test TCP pool performance 566 | nodepass "server://0.0.0.0:10101/backend:8080?type=0&mode=2&log=event" 567 | nodepass "client://server:10101/127.0.0.1:8080?mode=2&log=event" 568 | 569 | # Test QUIC pool performance 570 | nodepass "server://0.0.0.0:10102/backend:8080?type=1&mode=2&log=event" 571 | nodepass "client://server:10102/127.0.0.1:8081?mode=2&log=event" 572 | 573 | # Test WebSocket pool performance 574 | nodepass "server://0.0.0.0:10103/backend:8080?type=2&mode=2&log=event" 575 | nodepass "client://server:10103/127.0.0.1:8082?mode=2&log=event" 576 | ``` 577 | 578 | Monitor traffic statistics and choose based on observed performance. 579 | 580 | ## Next Steps 581 | 582 | If you encounter issues not covered in this guide: 583 | 584 | - Check the [project repository](https://github.com/yosebyte/nodepass) for known issues 585 | - Increase the log level to `debug` for more detailed information 586 | - Review the [How It Works](/docs/en/how-it-works.md) section to better understand internal mechanisms 587 | - Consider joining the community discussion for assistance from other users -------------------------------------------------------------------------------- /docs/zh/configuration.md: -------------------------------------------------------------------------------- 1 | # 配置选项 2 | 3 | NodePass采用极简方法进行配置，所有设置都通过命令行参数和环境变量指定。本指南说明所有可用的配置选项，并为各种部署场景提供建议。 4 | 5 | ## 日志级别 6 | 7 | NodePass提供六种日志详细级别，控制显示的信息量： 8 | 9 | - `none`：禁用日志记录 - 不显示任何日志信息 10 | - `debug`：详细调试信息 - 显示所有操作和连接 11 | - `info`：一般操作信息(默认) - 显示启动、关闭和关键事件 12 | - `warn`：警告条件 - 仅显示不影响核心功能的潜在问题 13 | - `error`：错误条件 - 仅显示影响功能的问题 14 | - `event`：事件记录 - 显示重要的操作事件和流量统计 15 | 16 | 您可以在命令URL中设置日志级别： 17 | 18 | ```bash 19 | nodepass server://0.0.0.0:10101/0.0.0.0:8080?log=debug 20 | ``` 21 | 22 | ## TLS加密模式 23 | 24 | 对于服务器和主控模式，NodePass为数据通道提供三种TLS安全级别： 25 | 26 | - **模式0**：无TLS加密（明文TCP/UDP） 27 | - 最快性能，无开销 28 | - 数据通道无安全保护（仅在受信任网络中使用） 29 | 30 | - **模式1**：自签名证书（自动生成） 31 | - 设置简单的良好安全性 32 | - 证书自动生成且不验证 33 | - 防止被动窃听 34 | 35 | - **模式2**：自定义证书（需要`crt`和`key`参数） 36 | - 具有证书验证的最高安全性 37 | - 需要提供证书和密钥文件 38 | - 适用于生产环境 39 | 40 | TLS模式1示例（自签名）： 41 | ```bash 42 | nodepass server://0.0.0.0:10101/0.0.0.0:8080?tls=1 43 | ``` 44 | 45 | TLS模式2示例（自定义证书）： 46 | ```bash 47 | nodepass "server://0.0.0.0:10101/0.0.0.0:8080?tls=2&crt=/path/to/cert.pem&key=/path/to/key.pem" 48 | ``` 49 | 50 | ## 运行模式控制 51 | 52 | NodePass支持通过`mode`查询参数配置运行模式，以控制客户端和服务端实例的行为。这在自动模式检测不适合的部署场景中提供了灵活性。 53 | 54 | ### 客户端模式控制 55 | 56 | 对于客户端实例，`mode`参数控制连接策略： 57 | 58 | - **模式0**（默认）：自动模式检测 59 | - 首先尝试本地绑定隧道地址 60 | - 如果成功，以单端转发模式运行 61 | - 如果绑定失败，以双端握手模式运行 62 | 63 | - **模式1**：强制单端转发模式 64 | - 本地绑定隧道地址并直接转发流量到目标 65 | - 使用直接连接建立实现高性能 66 | - 无需与服务器握手 67 | 68 | - **模式2**：强制双端握手模式 69 | - 始终连接到远程服务器建立隧道 70 | - 数据传输前需要与服务器握手 71 | - 支持双向数据流协调 72 | 73 | 示例： 74 | ```bash 75 | # 强制客户端以单端转发模式运行 76 | nodepass "client://127.0.0.1:1080/target.example.com:8080?mode=1" 77 | 78 | # 强制客户端以双端握手模式运行 79 | nodepass "client://server.example.com:10101/127.0.0.1:8080?mode=2" 80 | ``` 81 | 82 | ### 服务端模式控制 83 | 84 | 对于服务端实例，`mode`参数控制数据流方向： 85 | 86 | - **模式0**（默认）：自动流向检测 87 | - 首先尝试本地绑定目标地址 88 | - 如果成功，以反向模式运行（服务器接收流量） 89 | - 如果绑定失败，以正向模式运行（服务器发送流量） 90 | 91 | - **模式1**：强制反向模式 92 | - 服务器本地绑定目标地址并接收流量 93 | - 入站连接转发到已连接的客户端 94 | - 数据流：外部 → 服务器 → 客户端 → 目标 95 | 96 | - **模式2**：强制正向模式 97 | - 服务器连接到远程目标地址 98 | - 客户端连接转发到远程目标 99 | - 数据流：客户端 → 服务器 → 外部目标 100 | 101 | 示例： 102 | ```bash 103 | # 强制服务器以反向模式运行 104 | nodepass "server://0.0.0.0:10101/0.0.0.0:8080?mode=1" 105 | 106 | # 强制服务器以正向模式运行 107 | nodepass "server://0.0.0.0:10101/remote.example.com:8080?mode=2" 108 | ``` 109 | 110 | ## DNS解析配置 111 | 112 | NodePass使用系统内置的DNS解析器，具有智能缓存功能，可提高性能和可靠性。DNS缓存减少了查询开销并防止解析延迟。 113 | 114 | - `dns`：DNS缓存TTL持续时间（默认：5m） 115 | - 指定已解析的主机名在重新查询前缓存多长时间 116 | - 接受时间持续时间格式：`1h`、`30m`、`15s`、`500ms`等 117 | - 较长的TTL减少DNS查询开销，但可能缓存过时记录 118 | - 较短的TTL确保更新的DNS数据，但增加查询频率 119 | - 设置为`0`以禁用缓存（每次连接都查询DNS） 120 | - 适用于客户端和服务端模式，用于解析所有主机名 121 | 122 | **DNS缓存特性：** 123 | - **系统集成**：使用操作系统的原生DNS解析器以实现最大兼容性 124 | - **智能缓存**：已解析的主机名会使用可配置的TTL进行缓存，以减少查询开销 125 | - **自动过期**：缓存条目在TTL过期后自动删除 126 | - **IP地址绕过**：直接IP地址跳过DNS解析以获得最高效率 127 | - **协议感知**：自动处理IPv4和IPv6地址 128 | - **线程安全**：并发DNS查找被安全地缓存并在连接之间共享 129 | 130 | 示例： 131 | ```bash 132 | # 使用默认5分钟缓存TTL 133 | nodepass "server://0.0.0.0:10101/example.com:8080" 134 | 135 | # 为稳定域名设置1小时缓存TTL 136 | nodepass "server://0.0.0.0:10101/internal.example.com:8080?dns=1h" 137 | 138 | # 为动态DNS设置30秒缓存TTL 139 | nodepass "client://server.example.com:10101/database.local:3306?dns=30s" 140 | 141 | # 完全禁用DNS缓存（每次连接都查询） 142 | nodepass "server://0.0.0.0:10101/service.example.com:8080?dns=0" 143 | 144 | # 与其他参数组合 145 | nodepass "server://0.0.0.0:10101/backend.example.com:8080?dns=10m&log=info&tls=1&mode=2" 146 | ``` 147 | 148 | **DNS配置使用场景：** 149 | - **企业网络**：对稳定的内部主机名使用较长的TTL（例如1h） 150 | - **动态DNS**：对频繁变化的DNS记录使用较短的TTL（例如30s） 151 | - **高可用性**：较长的TTL减少DNS服务器负载并提高可靠性 152 | - **负载均衡**：较短的TTL使负载均衡服务能更快切换 153 | - **性能**：较长的TTL通过减少DNS查询来降低连接延迟 154 | 155 | **DNS缓存行为：** 156 | - 缓存TTL通过`dns`查询参数配置（默认：5分钟） 157 | - 过期条目被删除，下次访问时执行新的查找 158 | - 缓存是每个实例的，不在NodePass进程之间共享 159 | - IP地址永远不会被缓存（直接使用，不需要DNS查找） 160 | - 系统DNS解析器用于所有主机名查找 161 | 162 | **重要说明：** 163 | - 支持IPv4和IPv6地址 164 | - DNS解析超时由操作系统控制 165 | - 使用目标地址组时，每个地址独立解析 166 | - DNS解析适用于隧道地址和目标地址 167 | - 隧道地址DNS解析在启动时发生一次 168 | - 目标地址DNS解析使用缓存进行重复连接 169 | 170 | ## 出站连接源IP控制 171 | 172 | NodePass支持指定用于连接目标地址的出站本地IP地址。此功能对于具有多个网络接口且需要显式控制流量路由的系统很有用。 173 | 174 | - `dial`：出站连接的源IP地址（默认：auto） 175 | - 值为`auto`或省略：系统根据路由表自动选择源IP 176 | - 有效IP地址：强制所有出站连接使用指定的本地IP地址 177 | - 适用于TCP和UDP到目标地址的连接 178 | - 适用于客户端和服务端模式 179 | - 如果指定地址失败，自动回退到系统选择的IP 180 | - 无效的IP地址会触发错误日志并回退到自动模式 181 | 182 | `dial`参数提供对NodePass用于出站连接的网络接口的精确控制，支持高级网络配置，例如： 183 | 184 | 示例： 185 | ```bash 186 | # 服务器为出站连接指定特定源IP 187 | nodepass "server://0.0.0.0:10101/remote.example.com:8080?dial=10.1.0.100" 188 | 189 | # 客户端为目标连接指定特定源IP 190 | nodepass "client://server.example.com:10101/127.0.0.1:8080?dial=192.168.1.50" 191 | 192 | # 与其他参数组合使用 193 | nodepass "server://0.0.0.0:10101/remote.example.com:8080?log=info&tls=1&dial=10.1.0.100&mode=2" 194 | ``` 195 | 196 | **源IP控制使用场景：** 197 | - **多宿主系统**：控制用于出站流量的网络接口 198 | - **策略路由**：确保流量基于源IP使用特定路由 199 | - **网络分段**：通过特定VLAN或网络区域引导流量 200 | - **防火墙规则**：匹配按源IP过滤的特定防火墙规则 201 | - **负载分配**：在多个网络链路之间分配出站流量 202 | - **测试**：模拟来自特定网络位置或接口的流量 203 | 204 | **自动回退行为：** 205 | - 如果无法绑定指定的IP地址（例如，系统上不存在），NodePass会记录错误并自动回退到系统选择的IP 206 | - 回退仅在每个实例中发生一次 - 回退后，所有后续连接都使用自动模式 207 | - 回退以ERROR级别记录以提高可见性："dialWithRotation: fallback to system auto due to dialer failure" 208 | 209 | **重要说明：** 210 | - 指定的IP必须存在于本地系统上并正确配置 211 | - 源IP仅适用于到目标地址的出站连接，不适用于隧道连接 212 | - 支持IPv4和IPv6地址（地址族必须与目标地址匹配） 213 | - 绑定失败会触发自动回退以防止连接失败 214 | - 此参数不影响传入的隧道连接或服务器监听地址 215 | 216 | ## 连接池类型 217 | 218 | NodePass支持三种连接池类型，用于双端握手模式下的隧道连接管理。每种类型都提供不同的传输协议和性能特征。 219 | 220 | - `type`: 连接池类型（默认：0） 221 | - 值0：使用基于TCP的连接池（传统连接池库） 222 | - 值1：使用基于QUIC的连接池（UDP多路复用流） 223 | - 值2：使用基于WebSocket/WSS的连接池（HTTP升级连接） 224 | - 值3：使用基于HTTP/2的连接池（单TLS连接多路复用流） 225 | - 仅适用于双端握手模式（mode=2） 226 | - 如果尚未配置TLS则自动启用（最低tls=1） 227 | - 服务端配置在握手时自动下发给客户端 228 | 229 | ### TCP连接池 (type=0) 230 | 231 | 传统的基于TCP的连接池，提供最大的兼容性和可靠性。 232 | 233 | **优势：** 234 | - 最大的网络兼容性，几乎所有网络均支持TCP 235 | - 严格TCP语义和顺序保证 236 | - 在低丢包率网络中性能稳定 237 | - 企业环境广泛接受 238 | - 在稳定网络中延迟低 239 | 240 | **使用场景：** 241 | - 阻止或限制UDP流量的网络 242 | - 需要严格TCP语义的应用 243 | - 企业环境中的默认选择 244 | - 最大兼容性需求 245 | 246 | ### QUIC连接池 (type=1) 247 | 248 | 基于QUIC协议的现代连接池，提供基于UDP的多路复用流。 249 | 250 | **优势：** 251 | - **多路复用**：在单个UDP连接上实现多个流 252 | - **降低延迟**：通过0-RTT支持实现更快的连接建立 253 | - **更好的丢包恢复**：流级别的流量控制和拥塞管理 254 | - **NAT穿透**：基于UDP的协议在NAT和防火墙环境中表现更好 255 | - **内置加密**：所有QUIC连接强制使用TLS 1.3加密 256 | 257 | **使用场景：** 258 | - 移动网络或频繁变化的网络条件 259 | - 高延迟连接（卫星、长距离） 260 | - NAT密集环境 261 | - 实时应用，受益于流独立性 262 | - 需要0-RTT重连的场景 263 | 264 | **要求：** 265 | - 必须启用TLS模式（tls=1或tls=2） 266 | - 仅在双端握手模式下可用（mode=2） 267 | - 需要UDP端口可访问 268 | 269 | ### WebSocket连接池 (type=2) 270 | 271 | 基于WebSocket协议的连接池，通过HTTP升级建立连接。 272 | 273 | **优势：** 274 | - **代理穿透**：可以穿透HTTP代理和CDN 275 | - **防火墙友好**：使用标准HTTP/HTTPS端口，容易通过防火墙 276 | - **Web基础设施兼容**：与现有Web基础设施集成 277 | - **双向通信**：支持全双工通信 278 | - **广泛支持**：所有现代浏览器和平台支持 279 | 280 | **使用场景：** 281 | - 需要穿透HTTP代理或CDN 282 | - 企业环境仅允许HTTP/HTTPS流量 283 | - 防火墙阻止原始TCP连接 284 | - 需要与现有网络基础设施兼容 285 | - Web代理或VPN替代方案 286 | 287 | **要求：** 288 | - **必须启用TLS** - WebSocket连接池必须使用WSS（加密）。需要至少`tls=1`，生产环境推荐`tls=2` 289 | - 仅在双端握手模式下可用（mode=2） 290 | - 需要TCP端口支持WebSocket升级 291 | - **重要**：类型2不支持不加密模式（tls=0）。如果指定tls=0与type=2，系统将自动强制使用tls=1 292 | 293 | ### HTTP/2连接池 (type=3) 294 | 295 | 基于HTTP/2协议的连接池，在单个TLS连接上提供多路复用流。 296 | 297 | **优势：** 298 | - **流多路复用**：在单个TCP连接上实现多个独立流 299 | - **头部压缩**：HPACK压缩减少带宽使用 300 | - **二进制协议**：高效的二进制帧减少解析开销 301 | - **流量控制**：每个流和连接级别的流量控制 302 | - **服务端推送**：优化数据传输模式的潜力 303 | - **TLS集成**：原生TLS 1.3支持与强加密 304 | - **防火墙友好**：使用标准HTTPS端口和协议模式 305 | 306 | **使用场景：** 307 | - 仅允许HTTP/HTTPS策略的企业环境 308 | - 需要协议级优化和效率的网络 309 | - 受益于流多路复用的高并发场景 310 | - 需要代理穿透和性能的环境 311 | - 需要精细流量控制的应用 312 | - 具有HTTP/2感知负载均衡器或代理的基础设施 313 | 314 | **要求：** 315 | - 必须启用TLS模式（tls=1或tls=2） 316 | - 仅在双端握手模式下可用（mode=2） 317 | - 需要HTTP/2协议支持（NodePass内置） 318 | 319 | ### 配置示例 320 | 321 | ```bash 322 | # TCP连接池（默认） 323 | nodepass "server://0.0.0.0:10101/remote.example.com:8080?type=0&mode=2&tls=1" 324 | 325 | # QUIC连接池（自动启用TLS） 326 | nodepass "server://0.0.0.0:10101/remote.example.com:8080?type=1&mode=2" 327 | 328 | # WebSocket连接池（使用自定义TLS证书） 329 | nodepass "server://0.0.0.0:10101/remote.example.com:8080?type=2&tls=2&crt=/path/to/cert.pem&key=/path/to/key.pem" 330 | 331 | # HTTP/2连接池（带TLS的多路复用流） 332 | nodepass "server://0.0.0.0:10101/remote.example.com:8080?type=3&mode=2&tls=1" 333 | 334 | # 客户端自动采用服务器的连接池类型配置 335 | nodepass "client://server.example.com:10101/127.0.0.1:8080?mode=2" 336 | ``` 337 | 338 | **重要说明：** 339 | - 仅需服务端配置`type`参数 - 客户端自动接收配置 340 | - **WebSocket连接池（type=2）需要TLS**：至少`tls=1`。如果type=2但未配置TLS，系统会自动设置tls=1 341 | - 所有连接池类型仅在双端握手模式下可用（mode=2或带远程地址的mode=0） 342 | - 不适用于单端转发模式（mode=1） 343 | 344 | **连接池类型使用场景：** 345 | - **TCP连接池**：标准企业环境、最大兼容性、稳定网络 346 | - **QUIC连接池**：高延迟网络、移动网络、实时应用、复杂NAT环境 347 | - **WebSocket连接池**：HTTP代理穿透、企业防火墙限制、Web基础设施集成 348 | - **HTTP/2连接池**：HTTP/HTTPS仅支持策略、高并发场景、协议级优化需求 349 | 350 | ## 连接池容量参数 351 | 352 | 连接池容量参数仅适用于双端握手模式，通过不同方式进行配置： 353 | 354 | - `min`: 最小连接池容量（默认: 64）- 由客户端通过URL查询参数设置 355 | - `max`: 最大连接池容量（默认: 1024）- 由服务端确定，在握手过程中下发给客户端 356 | 357 | **重要说明**： 358 | - 客户端设置的`max`参数会被服务端在握手时传递的值覆盖 359 | - `min`参数由客户端完全控制，服务端不会修改此值 360 | - 在客户端单端转发模式下，不使用连接池，这些参数被忽略 361 | - 适用于所有连接池类型（type=0, type=1, type=2） 362 | 363 | 示例： 364 | ```bash 365 | # 客户端设置最小连接池为32，最大连接池将由服务端决定 366 | nodepass "client://server.example.com:10101/127.0.0.1:8080?min=32" 367 | 368 | # 使用自定义池容量的客户端（连接池类型由服务端配置） 369 | nodepass "client://server.example.com:10101/127.0.0.1:8080?min=128" 370 | ``` 371 | 372 | ## 数据读取超时 373 | 374 | `read`参数用于控制数据读取超时行为： 375 | 376 | - `read`: 数据读取超时时间（默认: 0，表示无超时） 377 | - 值为0或省略：无数据读取超时 378 | - 正整数加时间单位：设置读取超时时间 379 | - 值格式：整数后跟单位（`s`表示秒，`m`表示分钟，`h`表示小时） 380 | - 示例：`30s`（30秒），`5m`（5分钟），`1h`（1小时） 381 | - 如果在超时时间内未接收到数据，连接将被关闭 382 | - 适用于客户端和服务端模式 383 | 384 | 示例： 385 | ```bash 386 | # 设置数据读取超时为5分钟 387 | nodepass "client://server.example.com:10101/127.0.0.1:8080?read=5m" 388 | 389 | # 设置数据读取超时为30秒，适用于快速响应应用 390 | nodepass "client://server.example.com:10101/127.0.0.1:8080?read=30s" 391 | 392 | # 设置数据读取超时为1小时，适用于长时间传输 393 | nodepass "client://server.example.com:10101/127.0.0.1:8080?read=1h" 394 | 395 | # 默认行为：无超时（省略read参数或设置为0） 396 | nodepass "client://server.example.com:10101/127.0.0.1:8080" 397 | ``` 398 | 399 | **数据读取超时使用场景：** 400 | - **连接管理**：防止空闲连接无限期消耗资源 401 | - **资源控制**：根据预期的数据传输模式设置适当的超时时间 402 | - **网络可靠性**：优雅处理网络中断，通过自动清理 403 | 404 | ## 速率限制 405 | NodePass支持通过`rate`参数进行带宽速率限制，用于流量控制。此功能有助于防止网络拥塞，确保多个连接间的公平资源分配。 406 | 407 | - `rate`: 最大带宽限制，单位为Mbps（兆比特每秒） 408 | - 值为0或省略：无速率限制（无限带宽） 409 | - 正整数：以Mbps为单位的速率限制（例如，10表示10 Mbps） 410 | - 同时应用于上传和下载流量 411 | - 使用令牌桶算法进行平滑流量整形 412 | 413 | 示例： 414 | ```bash 415 | # 限制带宽为50 Mbps 416 | nodepass "server://0.0.0.0:10101/0.0.0.0:8080?rate=50" 417 | 418 | # 客户端100 Mbps速率限制 419 | nodepass "client://server.example.com:10101/127.0.0.1:8080?rate=100" 420 | 421 | # 与其他参数组合使用 422 | nodepass "server://0.0.0.0:10101/0.0.0.0:8080?log=error&tls=1&rate=50" 423 | ``` 424 | 425 | **速率限制使用场景：** 426 | - **带宽控制**：防止NodePass消耗所有可用带宽 427 | - **公平共享**：确保多个应用程序可以共享网络资源 428 | - **成本管理**：在按流量计费的网络环境中控制数据使用 429 | - **QoS合规**：满足带宽使用的服务级别协议 430 | - **测试**：模拟低带宽环境进行应用程序测试 431 | 432 | ## 连接槽位限制 433 | 434 | NodePass提供连接槽位限制功能，用于控制最大并发连接数并防止资源耗尽。此功能有助于在高负载条件下维持系统稳定性和可预测的性能。 435 | 436 | - `slot`：最大总连接数限制（默认：65536） 437 | - 值为0或省略：无连接限制（无限并发连接） 438 | - 正整数：TCP和UDP连接合计的最大并发连接数 439 | - 适用于客户端和服务端模式 440 | - 超出限制的连接将被拒绝，直到有槽位可用 441 | - TCP和UDP连接分别跟踪，但执行合并限制 442 | 443 | 槽位限制提供了一种断路器机制，防止NodePass接受超过系统有效处理能力的连接。当达到限制时，新的连接尝试会被立即拒绝而不是排队，这有助于为现有连接维持低延迟。 444 | 445 | 示例： 446 | ```bash 447 | # 限制总并发连接数为1000 448 | nodepass "server://0.0.0.0:10101/0.0.0.0:8080?slot=1000" 449 | 450 | # 客户端500连接限制 451 | nodepass "client://server.example.com:10101/127.0.0.1:8080?slot=500" 452 | 453 | # 与其他参数组合使用 454 | nodepass "server://0.0.0.0:10101/0.0.0.0:8080?log=info&tls=1&slot=2000&rate=100" 455 | ``` 456 | 457 | **连接槽位限制使用场景：** 458 | - **资源保护**：通过限制并发连接防止系统过载 459 | - **内存管理**：在高流量场景中控制内存使用 460 | - **性能一致性**：通过避免资源争用维持可预测的延迟 461 | - **容量规划**：为基础设施容量规划设置已知限制 462 | - **DoS防护**：提供对连接洪水攻击的基本保护 463 | - **服务稳定性**：确保关键服务在负载下保持响应 464 | 465 | **槽位配置最佳实践：** 466 | - **小型系统**：为资源受限环境设置保守限制（100-1000） 467 | - **高性能系统**：根据可用内存和CPU配置更高限制（10000-50000） 468 | - **负载测试**：通过在预期负载下的性能测试确定最佳限制 469 | - **监控**：跟踪连接使用情况以识别是否需要调整限制 470 | - **预留空间**：在理论系统限制以下预留20-30%的空间以确保稳定性 471 | 472 | ## PROXY协议支持 473 | 474 | NodePass支持PROXY协议v1，用于在通过负载均衡器、反向代理或其他中介服务转发流量时保留客户端连接信息。 475 | 476 | - `proxy`：PROXY协议支持（默认：0） 477 | - 值0：禁用 - 不发送PROXY协议头部 478 | - 值1：启用 - 在数据传输前发送PROXY协议v1头部 479 | - 支持TCP4和TCP6连接 480 | - 兼容HAProxy、Nginx和其他支持PROXY协议的服务 481 | 482 | PROXY协议头部包含原始客户端IP、服务器IP和端口信息，即使流量通过NodePass隧道，也允许下游服务识别真实的客户端连接详情。 483 | 484 | 示例： 485 | ```bash 486 | # 为服务端模式启用PROXY协议v1 487 | nodepass "server://0.0.0.0:10101/0.0.0.0:8080?proxy=1" 488 | 489 | # 为客户端模式启用PROXY协议v1 490 | nodepass "client://server.example.com:10101/127.0.0.1:8080?proxy=1" 491 | 492 | # 与其他参数组合使用 493 | nodepass "server://0.0.0.0:10101/0.0.0.0:8080?log=info&tls=1&proxy=1&rate=100" 494 | ``` 495 | 496 | **PROXY协议使用场景：** 497 | - **负载均衡器集成**：通过负载均衡器转发时保留客户端IP信息 498 | - **反向代理支持**：使后端服务能够看到原始客户端连接 499 | - **日志和分析**：维护准确的客户端连接日志用于安全和分析 500 | - **访问控制**：允许下游服务应用基于IP的访问控制 501 | - **合规性**：满足连接日志记录和审计的监管要求 502 | 503 | **重要说明：** 504 | - 目标服务必须支持PROXY协议v1才能正确处理头部 505 | - PROXY头部仅对TCP连接发送，不支持UDP 506 | - 头部格式遵循HAProxy PROXY协议v1规范 507 | - 如果目标服务不支持PROXY协议，将导致连接失败 508 | 509 | ## TCP支持控制 510 | 511 | NodePass默认支持TCP流量隧道。`notcp`参数允许您在只需要处理UDP流量时禁用TCP支持，这样可以减少资源使用并简化配置。 512 | 513 | - `notcp`: TCP支持控制（默认: 0） 514 | - 值为0：启用TCP支持 - TCP和UDP流量都将被隧道传输 515 | - 值为1：禁用TCP支持 - 仅UDP流量将被隧道传输，TCP连接被忽略 516 | - 适用于客户端和服务器模式 517 | - 禁用时，不分配TCP相关资源（缓冲区、连接、会话） 518 | 519 | 示例： 520 | ```bash 521 | # 启用TCP支持（默认行为） 522 | nodepass "server://0.0.0.0:10101/0.0.0.0:8080?notcp=0" 523 | 524 | # 禁用TCP支持，仅处理UDP场景 525 | nodepass "server://0.0.0.0:10101/0.0.0.0:8080?notcp=1" 526 | 527 | # 客户端禁用TCP 528 | nodepass "client://server.example.com:10101/127.0.0.1:8080?notcp=1" 529 | 530 | # 与其他参数结合 531 | nodepass "server://0.0.0.0:10101/0.0.0.0:8080?log=info&tls=1¬cp=1" 532 | ``` 533 | 534 | **TCP支持控制使用场景：** 535 | - **仅UDP服务**：仅需要隧道传输UDP应用时禁用TCP 536 | - **资源优化**：通过避免TCP处理开销减少内存和CPU使用 537 | - **安全性**：防止受限环境中的TCP攻击或不需要的流量 538 | - **简化配置**：不需要TCP隧道时更容易设置 539 | - **网络隔离**：更好地控制TCP和UDP流量处理 540 | 541 | **重要说明：** 542 | - 禁用TCP时，发送到隧道的任何TCP连接将被静默丢弃 543 | - 切换到notcp=1时，现有的TCP会话将被终止 544 | - 当notcp=1时，TCP缓冲池和会话管理被禁用 545 | 546 | ## UDP支持控制 547 | 548 | 除了TCP之外，NodePass还支持UDP流量隧道。`noudp`参数允许您在只需要处理TCP流量时禁用UDP支持，这样可以减少资源使用并简化配置。 549 | 550 | - `noudp`: UDP支持控制（默认: 0） 551 | - 值为0：启用UDP支持 - TCP和UDP流量都将被隧道传输 552 | - 值为1：禁用UDP支持 - 仅TCP流量将被隧道传输，UDP数据包将被忽略 553 | - 适用于客户端和服务端模式 554 | - 禁用时，不会分配UDP相关的资源（缓冲区、连接、会话） 555 | 556 | 示例： 557 | ```bash 558 | # 启用UDP支持（默认行为） 559 | nodepass "server://0.0.0.0:10101/0.0.0.0:8080?noudp=0" 560 | 561 | # 为仅TCP场景禁用UDP支持 562 | nodepass "server://0.0.0.0:10101/0.0.0.0:8080?noudp=1" 563 | 564 | # 禁用UDP的客户端 565 | nodepass "client://server.example.com:10101/127.0.0.1:8080?noudp=1" 566 | 567 | # 与其他参数组合使用 568 | nodepass "server://0.0.0.0:10101/0.0.0.0:8080?log=info&tls=1&noudp=1" 569 | ``` 570 | 571 | **UDP支持控制使用场景：** 572 | - **仅TCP服务**：仅隧道传输TCP应用时禁用UDP 573 | - **资源优化**：通过避免UDP处理开销减少内存和CPU使用 574 | - **安全性**：在受限环境中防止基于UDP的攻击或不需要的流量 575 | - **简化配置**：不需要UDP隧道时更容易设置 576 | - **网络隔离**：更好地控制TCP和UDP流量处理 577 | 578 | **重要说明：** 579 | - 禁用UDP时，发送到隧道的任何UDP数据包都将被静默丢弃 580 | - 切换到noudp=1时，现有的UDP会话将被终止 581 | - 当noudp=1时，UDP缓冲池和会话管理被禁用 582 | 583 | ## 协议屏蔽 584 | 585 | NodePass提供细粒度的协议屏蔽功能，防止特定协议通过隧道传输。这对于需要阻止某些协议同时允许其他协议的安全策略非常有用。 586 | 587 | `block`参数使用数字字符串，其中每个数字代表一个协议类别： 588 | - `1`：屏蔽SOCKS协议（SOCKS4/4a/5） 589 | - `2`：屏蔽HTTP协议（所有HTTP方法） 590 | - `3`：屏蔽TLS/SSL协议（加密连接） 591 | 592 | 可以通过以任意顺序包含相应数字来屏蔽多个协议。参数值可以包含重复数字而不影响行为。 593 | 594 | ### 配置选项 595 | 596 | - `block`：协议屏蔽控制（默认：未设置或`0`） 597 | - 未设置或`0`：允许所有协议（不屏蔽） 598 | - 包含`1`：屏蔽SOCKS4、SOCKS4a和SOCKS5协议 599 | - 包含`2`：屏蔽HTTP协议（GET、POST、CONNECT等） 600 | - 包含`3`：屏蔽TLS/SSL握手（0x16内容类型） 601 | 602 | ### 示例 603 | 604 | 仅屏蔽SOCKS协议： 605 | ```bash 606 | nodepass "server://0.0.0.0:10101/0.0.0.0:8080?block=1" 607 | ``` 608 | 609 | 仅屏蔽HTTP协议： 610 | ```bash 611 | nodepass "server://0.0.0.0:10101/0.0.0.0:8080?block=2" 612 | ``` 613 | 614 | 同时屏蔽SOCKS和HTTP： 615 | ```bash 616 | nodepass "server://0.0.0.0:10101/0.0.0.0:8080?block=12" 617 | # 或者 618 | nodepass "server://0.0.0.0:10101/0.0.0.0:8080?block=21" 619 | ``` 620 | 621 | 屏蔽所有三个协议类别： 622 | ```bash 623 | nodepass "server://0.0.0.0:10101/0.0.0.0:8080?block=123" 624 | # 或任意组合如：321、213、312等 625 | ``` 626 | 627 | 与其他安全设置结合： 628 | ```bash 629 | nodepass "server://0.0.0.0:10101/0.0.0.0:8080?log=info&tls=1&block=12&slot=1024" 630 | ``` 631 | 632 | ### 检测机制 633 | 634 | NodePass使用高效的协议检测，开销极小： 635 | 636 | - **SOCKS检测**：检查传入连接的前2个字节 637 | - SOCKS4/4a：检查版本字节`0x04`和命令字节`0x01`/`0x02` 638 | - SOCKS5：检查版本字节`0x05`和有效的方法计数 639 | 640 | - **HTTP检测**：扫描最多8个字节以查找HTTP方法模式 641 | - 识别大写字母后跟空格字符 642 | - 检测所有标准HTTP方法（GET、POST、CONNECT、DELETE等） 643 | - 也检测自定义HTTP方法和WebDAV扩展 644 | 645 | - **TLS检测**：检查第一个字节的TLS握手 646 | - 识别TLS握手记录类型`0x16` 647 | - 阻止TLS 1.0、1.1、1.2和1.3握手 648 | 649 | ### 使用场景 650 | 651 | **在隧道服务中屏蔽代理协议：** 652 | ```bash 653 | # 仅允许应用流量，屏蔽代理协议 654 | nodepass "server://0.0.0.0:10101/app.backend.local:8080?block=12" 655 | ``` 656 | 657 | **执行加密策略：** 658 | ```bash 659 | # 仅允许加密流量，屏蔽明文协议 660 | nodepass "server://0.0.0.0:10101/0.0.0.0:443?block=12&tls=2" 661 | ``` 662 | 663 | **防止TLS嵌套：** 664 | ```bash 665 | # 当外层已加密时阻止嵌套TLS 666 | nodepass "server://0.0.0.0:10101/0.0.0.0:8080?tls=1&block=3" 667 | ``` 668 | 669 | ### 重要说明 670 | 671 | - 协议检测发生在连接建立时（接收到的第一批字节） 672 | - 被屏蔽的连接会立即关闭并记录警告日志 673 | - 此功能增加的CPU开销极小（通常每个连接<0.1ms） 674 | - 协议屏蔽适用于单端和双端转发模式 675 | - 与`notcp`/`noudp`结合使用可实现完整的流量控制 676 | 677 | ## 目标地址组与负载均衡 678 | 679 | NodePass支持配置多个目标地址以实现高可用性和负载均衡。目标地址组功能仅适用于出口端（流量最终到达的目的地），不应在入口端使用。 680 | 681 | ### 目标地址组配置 682 | 683 | 目标地址组通过逗号分隔多个地址来配置，NodePass会自动在这些地址之间进行轮询和故障转移： 684 | 685 | ```bash 686 | # 服务端配置多个后端目标（正向模式，mode=2） 687 | nodepass "server://0.0.0.0:10101/backend1.example.com:8080,backend2.example.com:8080,backend3.example.com:8080?mode=2&tls=1" 688 | 689 | # 客户端配置多个本地服务（单端转发模式，mode=1） 690 | nodepass "client://127.0.0.1:1080/app1.local:8080,app2.local:8080?mode=1" 691 | ``` 692 | 693 | ### 轮询策略 694 | 695 | NodePass采用轮询（Round-Robin）算法，结合故障转移和负载均衡特性： 696 | 697 | - **负载均衡**：每次成功建立连接后，自动切换到下一个目标地址，实现流量均匀分布 698 | - **故障转移**：当某个地址连接失败时，立即尝试下一个地址，确保服务高可用 699 | - **自动恢复**：失败的地址会在轮询周期中重新尝试，故障恢复后自动接入流量 700 | 701 | ### 使用场景 702 | 703 | 目标地址组适用于以下场景： 704 | 705 | - **高可用性部署**：多个后端服务器实现故障自动切换 706 | - **负载均衡**：流量均匀分布到多个后端实例 707 | - **灰度发布**：逐步将流量切换到新版本服务 708 | - **地域分布**：根据网络拓扑选择最优路径 709 | 710 | ### 重要说明 711 | 712 | - **仅适用于出口**：目标地址组只能配置在流量的最终目的地 713 | - ✓ 服务端正向模式（mode=2）：`server://0.0.0.0:10101/target1:80,target2:80` 714 | - ✓ 客户端单端转发模式（mode=1）：`client://127.0.0.1:1080/target1:80,target2:80` 715 | - ✗ 隧道地址不支持：不要在隧道地址使用多地址配置 716 | 717 | - **地址格式**：所有地址必须使用相同的端口或明确指定每个地址的端口 718 | - **协议一致性**：地址组中的所有地址必须支持相同的协议（TCP/UDP） 719 | - **线程安全**：轮询索引使用原子操作，支持高并发场景 720 | 721 | 示例配置： 722 | 723 | ```bash 724 | # 正确示例：服务端配置3个后端Web服务器 725 | nodepass "server://0.0.0.0:10101/web1.internal:8080,web2.internal:8080,web3.internal:8080?mode=2&log=info" 726 | 727 | # 正确示例：客户端配置2个本地数据库实例 728 | nodepass "client://127.0.0.1:3306/db-primary.local:3306,db-secondary.local:3306?mode=1&log=warn" 729 | 730 | # 错误示例：不要在隧道地址使用多地址（会导致解析错误） 731 | # nodepass "server://host1:10101,host2:10101/target:8080" # ✗ 错误用法 732 | ``` 733 | 734 | ## URL查询参数配置及作用范围 735 | 736 | NodePass支持通过URL查询参数进行灵活配置,不同参数在 server、client、master 模式下的适用性如下表： 737 | 738 | | 参数 | 说明 | 默认值 | 可选值 | server | client | master | 739 | |------|------|--------|--------|:------:|:------:|:------:| 740 | | `log` | 日志级别 | `info` | `none`/`debug`/`info`/`warn`/`error`/`event` | O | O | O | 741 | | `tls` | TLS加密模式 | `0` | `0`/`1`/`2` | O | X | O | 742 | | `crt` | 自定义证书路径 | N/A | 文件路径 | O | X | O | 743 | | `key` | 自定义密钥路径 | N/A | 文件路径 | O | X | O | 744 | | `dns` | DNS缓存TTL | `5m` | `30s`/`5m`/`1h`等 | O | O | X | 745 | | `sni` | 主机名指示 | `none` | 主机名 | X | O | X | 746 | | `min` | 最小连接池容量 | `64` | 正整数 | X | O | X | 747 | | `max` | 最大连接池容量 | `1024` | 正整数 | O | X | X | 748 | | `mode` | 运行模式控制 | `0` | `0`/`1`/`2` | O | O | X | 749 | | `type` | 连接池类型 | `0` | `0`/`1`/`2`/`3` | O | X | X | 750 | | `dial` | 出站源IP地址 | `auto` | `auto`/IP地址 | O | O | X | 751 | | `read` | 数据读取超时 | `0` | `0`/`30s`/`5m`等 | O | O | X | 752 | | `rate` | 带宽速率限制 | `0` | `0`或正整数(Mbps) | O | O | X | 753 | | `slot` | 最大连接数限制 | `65536` | `0`或正整数 | O | O | X | 754 | | `proxy` | PROXY协议支持 | `0` | `0`/`1` | O | O | X | 755 | | `block` | 协议屏蔽 | `0` | `0`/`1`/`2`/`3` | O | O | X | 756 | | `notcp` | TCP支持控制 | `0` | `0`/`1` | O | O | X | 757 | | `noudp` | UDP支持控制 | `0` | `0`/`1` | O | O | X | 758 | 759 | - O：参数有效，推荐根据实际场景配置 760 | - X：参数无效，忽略设置 761 | 762 | **最佳实践：** 763 | - server/master 模式建议配置安全相关参数（如 tls、crt、key），提升数据通道安全性。 764 | - client/server 双端握手模式建议根据流量和资源情况调整连接池容量（min/max），优化性能。 765 | - 当自动检测不符合部署需求时或需要跨环境一致行为时，使用运行模式控制（mode）。 766 | - 配置速率限制（rate）以控制带宽使用，防止共享环境中的网络拥塞。 767 | - 配置连接池类型（type）时仅需在服务端设置 - 客户端在握手时自动接收配置。 768 | - 仅需要隧道传输UDP流量时设置`notcp=1`，以减少资源使用并简化配置。 769 | - 仅需要隧道传输TCP流量时设置`noudp=1`，以减少资源使用并简化配置。 770 | - 使用`block`参数通过屏蔽特定协议类别（SOCKS/HTTP/TLS）来执行安全策略。 771 | - 日志级别（log）可在所有模式下灵活调整，便于运维和排查。 772 | 773 | ## 环境变量 774 | 775 | 可以使用环境变量微调NodePass行为。以下是所有可用变量的完整列表，包括其描述、默认值以及不同场景的推荐设置。 776 | 777 | | 变量 | 描述 | 默认值 | 示例 | 778 | |----------|-------------|---------|---------| 779 | | `NP_SEMAPHORE_LIMIT` | 信号缓冲区大小 | 65536 | `export NP_SEMAPHORE_LIMIT=2048` | 780 | | `NP_TCP_DATA_BUF_SIZE` | TCP数据传输缓冲区大小 | 16384 | `export NP_TCP_DATA_BUF_SIZE=65536` | 781 | | `NP_UDP_DATA_BUF_SIZE` | UDP数据包缓冲区大小 | 16384 | `export NP_UDP_DATA_BUF_SIZE=16384` | 782 | | `NP_HANDSHAKE_TIMEOUT` | 握手操作超时 | 5s | `export NP_HANDSHAKE_TIMEOUT=30s` | 783 | | `NP_UDP_READ_TIMEOUT` | UDP读取操作超时 | 30s | `export NP_UDP_READ_TIMEOUT=60s` | 784 | | `NP_TCP_DIAL_TIMEOUT` | TCP连接建立超时 | 5s | `export NP_TCP_DIAL_TIMEOUT=60s` | 785 | | `NP_UDP_DIAL_TIMEOUT` | UDP连接建立超时 | 5s | `export NP_UDP_DIAL_TIMEOUT=30s` | 786 | | `NP_POOL_GET_TIMEOUT` | 从连接池获取连接的超时时间 | 5s | `export NP_POOL_GET_TIMEOUT=60s` | 787 | | `NP_MIN_POOL_INTERVAL` | 连接创建之间的最小间隔 | 100ms | `export NP_MIN_POOL_INTERVAL=200ms` | 788 | | `NP_MAX_POOL_INTERVAL` | 连接创建之间的最大间隔 | 1s | `export NP_MAX_POOL_INTERVAL=3s` | 789 | | `NP_REPORT_INTERVAL` | 健康检查报告间隔 | 5s | `export NP_REPORT_INTERVAL=10s` | 790 | | `NP_SERVICE_COOLDOWN` | 重启尝试前的冷却期 | 3s | `export NP_SERVICE_COOLDOWN=5s` | 791 | | `NP_SHUTDOWN_TIMEOUT` | 优雅关闭超时 | 5s | `export NP_SHUTDOWN_TIMEOUT=10s` | 792 | | `NP_RELOAD_INTERVAL` | 证书重载/状态备份间隔 | 1h | `export NP_RELOAD_INTERVAL=30m` | 793 | 794 | ### 连接池调优 795 | 796 | 连接池参数是双端握手模式下性能调优中的重要设置，在客户端单端转发模式下不适用： 797 | 798 | #### 池容量设置 799 | 800 | - `min` (URL参数)：确保最小可用连接数 801 | - 太低：流量高峰期延迟增加，因为必须建立新连接 802 | - 太高：维护空闲连接浪费资源 803 | - 推荐起点：平均并发连接的25-50% 804 | 805 | - `max` (URL参数)：防止过度资源消耗，同时处理峰值负载 806 | - 太低：流量高峰期连接失败 807 | - 太高：潜在资源耗尽影响系统稳定性 808 | - 推荐起点：峰值并发连接的150-200% 809 | 810 | #### 池间隔设置 811 | 812 | - `NP_MIN_POOL_INTERVAL`：控制连接创建尝试之间的最小时间 813 | - 太低：可能以连接尝试压垮网络 814 | - 推荐范围：根据网络延迟和预期负载，100ms-500ms 815 | 816 | - `NP_MAX_POOL_INTERVAL`：控制连接创建尝试之间的最大时间 817 | - 太高：流量高峰期可能导致池耗尽 818 | - 推荐范围：根据预期流量模式，1s-5s 819 | 820 | #### 连接管理 821 | 822 | - `NP_SEMAPHORE_LIMIT`：控制信号缓冲区大小 823 | - 太小：容易导致信号丢失 824 | - 太大：内存使用增加 825 | - 推荐范围：1000-5000 826 | 827 | ### UDP设置 828 | 829 | 对于严重依赖UDP流量的应用： 830 | 831 | - `NP_UDP_DATA_BUF_SIZE`：UDP数据包缓冲区大小 832 | - 对于发送大UDP数据包的应用增加此值 833 | - 默认值(16384)适用于大多数情况 834 | - 考虑为媒体流或游戏服务器增加到16384或更高 835 | 836 | - `NP_UDP_READ_TIMEOUT`：UDP读取操作超时 837 | - 默认值(30s)适用于大多数UDP应用场景 838 | - 控制UDP连接在无数据传输时的最大等待时间 839 | - 对于实时性要求高的应用（如游戏、VoIP）可以适当减小此值以快速检测断线 840 | - 对于允许间歇性传输的应用可以增加此值以避免误判超时 841 | 842 | - `NP_UDP_DIAL_TIMEOUT`：UDP连接建立超时 843 | - 默认值(5s)为大多数应用提供良好平衡 844 | - 对于高延迟网络或响应缓慢的应用增加此值 845 | - 对于需要快速故障切换的低延迟应用减少此值 846 | 847 | ### TCP设置 848 | 849 | 对于TCP连接的优化： 850 | 851 | - `NP_TCP_DATA_BUF_SIZE`：TCP数据传输缓冲区大小 852 | - 默认值(32768)为大多数应用提供良好平衡 853 | - 对于需要大缓冲区的高吞吐量应用增加此值 854 | - 考虑为批量数据传输和流媒体增加到65536或更高 855 | 856 | - `NP_TCP_DIAL_TIMEOUT`：TCP连接建立超时 857 | - 默认值(5s)适用于大多数网络条件 858 | - 对于网络条件不稳定的环境增加此值 859 | - 对于需要快速判断连接成功与否的应用减少此值 860 | 861 | ### 连接池管理设置 862 | 863 | - `NP_POOL_GET_TIMEOUT`：从连接池获取连接时的最大等待时间 864 | - 默认值(5s)为连接建立提供充足时间 865 | - 对于高延迟环境或使用大型连接池时增加此值 866 | - 对于需要快速故障检测的应用减少此值 867 | - 在客户端单端转发模式下不使用连接池，此参数被忽略 868 | 869 | ### 服务管理设置 870 | 871 | - `NP_REPORT_INTERVAL`：控制健康状态报告频率 872 | - 较低值提供更频繁的更新但增加日志量 873 | - 较高值减少日志输出但提供较少的即时可见性 874 | 875 | - `NP_RELOAD_INTERVAL`：控制检查TLS证书变更的频率 876 | - 较低值更快检测证书变更但增加文件系统操作 877 | - 较高值减少开销但延迟检测证书更新 878 | 879 | - `NP_SERVICE_COOLDOWN`：尝试服务重启前的等待时间 880 | - 较低值更快尝试恢复但可能在持续性问题情况下导致抖动 881 | - 较高值提供更多稳定性但从瞬态问题中恢复较慢 882 | 883 | - `NP_SHUTDOWN_TIMEOUT`：关闭期间等待连接关闭的最长时间 884 | - 较低值确保更快关闭但可能中断活动连接 885 | - 较高值允许连接有更多时间完成但延迟关闭 886 | 887 | ## 推荐配置 888 | 889 | 以下是常见场景的推荐环境变量配置： 890 | 891 | ### 高吞吐量配置 892 | 893 | 对于需要最大吞吐量的应用（如媒体流、文件传输）： 894 | 895 | URL参数： 896 | ```bash 897 | # 高吞吐量服务器，1 Gbps速率限制和高连接容量 898 | nodepass "server://0.0.0.0:10101/0.0.0.0:8080?max=8192&rate=1000&slot=10000" 899 | 900 | # 高吞吐量客户端，500 Mbps速率限制和高连接容量 901 | nodepass "client://server.example.com:10101/127.0.0.1:8080?min=128&rate=500&slot=5000" 902 | ``` 903 | 904 | 环境变量： 905 | ```bash 906 | export NP_MIN_POOL_INTERVAL=50ms 907 | export NP_MAX_POOL_INTERVAL=500ms 908 | export NP_SEMAPHORE_LIMIT=8192 909 | export NP_TCP_DATA_BUF_SIZE=65536 910 | export NP_UDP_DATA_BUF_SIZE=32768 911 | export NP_POOL_GET_TIMEOUT=60s 912 | export NP_REPORT_INTERVAL=10s 913 | ``` 914 | 915 | ### 低延迟配置 916 | 917 | 对于需要最小延迟的应用（如游戏、金融交易）： 918 | 919 | URL参数： 920 | ```bash 921 | # 低延迟服务器，适度速率限制和适度连接限制 922 | nodepass "server://0.0.0.0:10101/0.0.0.0:8080?max=4096&rate=200&slot=3000" 923 | 924 | # 低延迟客户端，适度速率限制和适度连接限制 925 | nodepass "client://server.example.com:10101/127.0.0.1:8080?min=256&rate=200&slot=2000" 926 | ``` 927 | 928 | 环境变量： 929 | ```bash 930 | export NP_MIN_POOL_INTERVAL=50ms 931 | export NP_MAX_POOL_INTERVAL=500ms 932 | export NP_SEMAPHORE_LIMIT=4096 933 | export NP_TCP_DIAL_TIMEOUT=5s 934 | export NP_UDP_DIAL_TIMEOUT=5s 935 | export NP_POOL_GET_TIMEOUT=15s 936 | export NP_REPORT_INTERVAL=1s 937 | ``` 938 | 939 | ### 资源受限配置 940 | 941 | 对于在资源有限系统上的部署（如IoT设备、小型VPS）： 942 | 943 | URL参数： 944 | ```bash 945 | # 资源受限服务器，保守速率限制和低连接限制 946 | nodepass "server://0.0.0.0:10101/0.0.0.0:8080?max=512&rate=50&slot=500" 947 | 948 | # 资源受限客户端，保守速率限制和低连接限制 949 | nodepass "client://server.example.com:10101/127.0.0.1:8080?min=16&rate=50&slot=200" 950 | ``` 951 | 952 | 环境变量： 953 | ```bash 954 | export NP_MIN_POOL_INTERVAL=200ms 955 | export NP_MAX_POOL_INTERVAL=2s 956 | export NP_SEMAPHORE_LIMIT=512 957 | export NP_TCP_DIAL_TIMEOUT=20s 958 | export NP_UDP_DIAL_TIMEOUT=20s 959 | export NP_POOL_GET_TIMEOUT=45s 960 | export NP_REPORT_INTERVAL=30s 961 | export NP_SHUTDOWN_TIMEOUT=3s 962 | ``` 963 | 964 | ## 下一步 965 | 966 | - 查看[使用说明](/docs/zh/usage.md)了解基本操作命令 967 | - 探索[使用示例](/docs/zh/examples.md)了解部署模式 968 | - 了解[NodePass工作原理](/docs/zh/how-it-works.md)以优化配置 969 | - 如果遇到问题，请查看[故障排除指南](/docs/zh/troubleshooting.md) --------------------------------------------------------------------------------