|
| 1 | +# 📘 NodePass Deployment and Management Guide |
| 2 | + |
| 3 | +`np.sh`: One-click deployment of the NodePass main program, providing high-performance TCP/UDP tunneling with multi-system support and flexible configuration. |
| 4 | +`dash.sh`: One-click deployment of the NodePassDash control panel, simplifying tunnel management and monitoring with containerization and HTTPS support. |
| 5 | + |
| 6 | +- Stable: v1.15.0 |
| 7 | +- Development: v1.15.0 |
| 8 | +- LTS: v1.15.0 |
| 9 | + |
| 10 | +--- |
| 11 | + |
| 12 | +## 📑 Table of Contents |
| 13 | + |
| 14 | +- [Introduction](#introduction) |
| 15 | +- [System Requirements](#system-requirements) |
| 16 | +- [1. `np.sh` Script (Main Program Installation)](#1-npsh-script-main-program-installation) |
| 17 | + - [Features](#features) |
| 18 | + - [Deployment Methods](#deployment-methods) |
| 19 | + - [Interactive Deployment](#interactive-deployment) |
| 20 | + - [Non-interactive Deployment](#non-interactive-deployment) |
| 21 | + - [Quick Commands](#quick-commands) |
| 22 | + - [Directory Structure](#directory-structure) |
| 23 | +- [2. `dash.sh` Script (Control Panel Installation)](#2-dashsh-script-control-panel-installation) |
| 24 | + - [Features](#features-1) |
| 25 | + - [Usage Instructions](#usage-instructions) |
| 26 | + - [Uninstallation Instructions](#uninstallation-instructions) |
| 27 | + - [Update Version](#update-version) |
| 28 | + - [Reset Password](#reset-password) |
| 29 | +- [Feedback](#feedback) |
| 30 | +- [Deployment Screenshots](#deployment-screenshots) |
| 31 | + |
| 32 | +--- |
| 33 | + |
| 34 | +## Introduction |
| 35 | + |
| 36 | +**NodePass** is a universal TCP/UDP tunneling solution with a control-data separation architecture, supporting zero-latency connection pools and multi-mode communication for high-performance, secure access across network restrictions. |
| 37 | + |
| 38 | +--- |
| 39 | + |
| 40 | +## System Requirements |
| 41 | + |
| 42 | +- **Operating System**: Compatible with Debian, Ubuntu, CentOS, Fedora, Alpine, Arch, OpenWRT, and more |
| 43 | +- **Architecture**: Supports x86_64 (amd64), aarch64 (arm64), armv7l (arm) |
| 44 | +- **Permissions**: Requires root privileges to run |
| 45 | + |
| 46 | +--- |
| 47 | + |
| 48 | +## 1. `np.sh` Script (Main Program Installation) |
| 49 | + |
| 50 | +### Features |
| 51 | + |
| 52 | +- ✅ Multi-system support |
| 53 | +- 🌐 Bilingual interface (Chinese/English) |
| 54 | +- 🔍 Automatic detection of architecture and dependencies |
| 55 | +- 🔧 Flexible configuration of ports, API prefixes, and TLS modes |
| 56 | +- 🔐 Supports no encryption, self-signed certificates, or custom certificates |
| 57 | +- 🛠️ One-click service start, stop, restart, and uninstall |
| 58 | +- 🔄 Automatic updates to the latest version |
| 59 | +- 🐳 Automatic recognition of container environments |
| 60 | +- 📦 Supports installation of stable, development, and classic versions (LTS Long Term Support) |
| 61 | + |
| 62 | +--- |
| 63 | + |
| 64 | +### Deployment Methods |
| 65 | + |
| 66 | +#### Interactive Deployment |
| 67 | + |
| 68 | +``` |
| 69 | +bash <(wget -qO- https://run.nodepass.eu/np.sh) |
| 70 | +``` |
| 71 | +or |
| 72 | +``` |
| 73 | +bash <(curl -sSL https://run.nodepass.eu/np.sh) |
| 74 | +``` |
| 75 | + |
| 76 | +Follow the prompts to provide the following information: |
| 77 | + |
| 78 | +- Language selection (default: Chinese) |
| 79 | +- Server IP (If it is 127.0.0.1, you can choose to create an instance with an intranet penetration API.) |
| 80 | +- Port (leave blank for auto-assigned port in the 1024–8192 range) |
| 81 | +- API prefix (default: `api`) |
| 82 | +- TLS mode (0: no encryption, 1: self-signed certificate, 2: custom certificate) |
| 83 | + |
| 84 | +--- |
| 85 | + |
| 86 | +#### Non-interactive Deployment |
| 87 | + |
| 88 | +<details> |
| 89 | + <summary>Example 1: No TLS encryption</summary> |
| 90 | + |
| 91 | +``` |
| 92 | +bash <(curl -sSL https://run.nodepass.eu/np.sh) \ |
| 93 | + -i \ |
| 94 | + --language zh \ |
| 95 | + --server_ip 127.0.0.1 \ |
| 96 | + --user_port 18080 \ |
| 97 | + --version stable \ |
| 98 | + --prefix api \ |
| 99 | + --tls_mode 0 |
| 100 | +``` |
| 101 | + |
| 102 | +</details> |
| 103 | + |
| 104 | +<details> |
| 105 | + <summary>Example 2: Self-signed certificate</summary> |
| 106 | + |
| 107 | +``` |
| 108 | +bash <(curl -sSL https://run.nodepass.eu/np.sh) \ |
| 109 | + -i \ |
| 110 | + --language en \ |
| 111 | + --server_ip localhost \ |
| 112 | + --user_port 18080 \ |
| 113 | + --version dev \ |
| 114 | + --prefix api \ |
| 115 | + --tls_mode 1 |
| 116 | +``` |
| 117 | + |
| 118 | +</details> |
| 119 | + |
| 120 | +<details> |
| 121 | + <summary>Example 3: Custom certificate</summary> |
| 122 | + |
| 123 | +``` |
| 124 | +bash <(curl -sSL https://run.nodepass.eu/np.sh) \ |
| 125 | + -i \ |
| 126 | + --language zh \ |
| 127 | + --server_ip 1.2.3.4 \ |
| 128 | + --user_port 18080 \ |
| 129 | + --version lts \ |
| 130 | + --prefix api \ |
| 131 | + --tls_mode 2 \ |
| 132 | + --cert_file </path/to/cert.pem> \ |
| 133 | + --key_file </path/to/key.pem> |
| 134 | +``` |
| 135 | + |
| 136 | +</details> |
| 137 | + |
| 138 | +--- |
| 139 | + |
| 140 | +### Quick Commands |
| 141 | + |
| 142 | +After installation, the `np` shortcut command is created: |
| 143 | + |
| 144 | +| Command | Description | |
| 145 | +|-----------|--------------------------------------| |
| 146 | +| `np` | Display interactive menu | |
| 147 | +| `np -i` | Install NodePass | |
| 148 | +| `np -u` | Uninstall NodePass | |
| 149 | +| `np -v` | Upgrade NodePass | |
| 150 | +| `np -t` | Switch between stable, dev and lts | |
| 151 | +| `np -o` | Start/stop service | |
| 152 | +| `np -k` | Change API key | |
| 153 | +| `np -s` | View API information | |
| 154 | +| `np -h` | Display help information | |
| 155 | + |
| 156 | +--- |
| 157 | + |
| 158 | +### Directory Structure |
| 159 | + |
| 160 | +``` |
| 161 | +/etc/nodepass/ |
| 162 | +├── data # Configuration data |
| 163 | +├── nodepass # Main program symlink pointing to the currently used kernel file |
| 164 | +├── np-dev # Development version kernel file |
| 165 | +├── np-lts # Classic version (LTS Long Term Support) kernel file |
| 166 | +├── np-stb # Stable version kernel file |
| 167 | +├── nodepass.gob # Data storage file |
| 168 | +└── np.sh # Deployment script |
| 169 | +``` |
| 170 | + |
| 171 | +--- |
| 172 | + |
| 173 | +## 2. `dash.sh` Script (Control Panel Installation) |
| 174 | + |
| 175 | +### Features |
| 176 | + |
| 177 | +- 🚀 One-click deployment of NodePassDash control panel |
| 178 | +- 🐧 Supports Debian, Ubuntu, CentOS |
| 179 | +- 🔧 Automatic detection of system and dependencies |
| 180 | +- 🌍 Host network mode is used, enabling seamless integration with host APIs |
| 181 | +- 🐳 Supports Docker and Podman for container deployment |
| 182 | +- 🔄 Automatic reverse proxy configuration (with HTTPS support) |
| 183 | +- 🔐 Automatic CA SSL certificate issuance (for domain-based deployment) |
| 184 | +- 📂 Automatic mounting of logs and public resource directories |
| 185 | + |
| 186 | +--- |
| 187 | + |
| 188 | +### Usage Instructions |
| 189 | + |
| 190 | +1. **Run the script**: |
| 191 | + |
| 192 | +``` |
| 193 | +bash <(wget -qO- https://run.nodepass.eu/dash.sh) |
| 194 | +``` |
| 195 | +or |
| 196 | +``` |
| 197 | +bash <(curl -sSL https://run.nodepass.eu/dash.sh) |
| 198 | +``` |
| 199 | + |
| 200 | +2. **Provide information**: |
| 201 | + |
| 202 | +- Domain or IP: Entering a domain enables HTTPS reverse proxy and SSL certificate issuance; entering an IP skips reverse proxy and Caddy installation. |
| 203 | +- Port: Default is 3000, customizable. |
| 204 | + |
| 205 | +3. **Container deployment**: |
| 206 | + |
| 207 | +- Automatically uses Docker or Podman to run the control panel container |
| 208 | +- Checks for port conflicts |
| 209 | + |
| 210 | +4. **Mounted directories**: |
| 211 | + |
| 212 | +| Host Path | Container Path | Purpose | |
| 213 | +|-----------------------------|---------------------|---------------| |
| 214 | +| `~/nodepassdash/logs` | `/app/logs` | Log files | |
| 215 | +| `~/nodepassdash/db` | `/app/db` | Database | |
| 216 | + |
| 217 | +5. **Completion prompt**: The script will output the access address and admin account details upon completion. |
| 218 | + |
| 219 | +### Uninstallation Instructions |
| 220 | + |
| 221 | +To uninstall the NodePassDash control panel: |
| 222 | + |
| 223 | +``` |
| 224 | +bash <(wget -qO- https://run.nodepass.eu/dash.sh) uninstall |
| 225 | +``` |
| 226 | +or |
| 227 | +``` |
| 228 | +bash <(curl -sSL https://run.nodepass.eu/dash.sh) uninstall |
| 229 | +``` |
| 230 | + |
| 231 | +This will clean up the container, configuration files, and mounted directories. |
| 232 | + |
| 233 | +### Update Version |
| 234 | + |
| 235 | +Update the NodePassDash container: |
| 236 | + |
| 237 | +``` |
| 238 | +bash <(wget -qO- https://run.nodepass.eu/dash.sh) update |
| 239 | +``` |
| 240 | +or |
| 241 | +``` |
| 242 | +bash <(curl -sSL https://run.nodepass.eu/dash.sh) update |
| 243 | +``` |
| 244 | + |
| 245 | +This will update based on the local and remote versions. |
| 246 | + |
| 247 | +### Reset Password |
| 248 | + |
| 249 | +``` |
| 250 | +bash <(wget -qO- https://run.nodepass.eu/dash.sh) resetpwd |
| 251 | +``` |
| 252 | +or |
| 253 | +``` |
| 254 | +bash <(curl -sSL https://run.nodepass.eu/dash.sh) resetpwd |
| 255 | +``` |
| 256 | + |
| 257 | +--- |
| 258 | + |
| 259 | +## Deployment Screenshots |
| 260 | + |
| 261 | +<img width="690" alt="image" src="https://github.com/user-attachments/assets/893a3856-ec69-488f-bb99-5df26b4fb4e7" /> |
| 262 | + |
| 263 | +<img width="690" alt="image" src="https://github.com/user-attachments/assets/61e01872-f401-485d-aa9a-8c1388e76a5b" /> |
| 264 | + |
| 265 | +--- |
| 266 | + |
| 267 | +## Feedback |
| 268 | + |
| 269 | +For installation or usage issues, please submit feedback at [GitHub Issues](https://github.com/NodePassProject/npsh/issues). |
| 270 | + |
| 271 | +--- |
| 272 | + |
| 273 | +## Deployment Screenshots |
| 274 | + |
| 275 | +<img width="690" alt="image" src="https://github.com/user-attachments/assets/893a3856-ec69-488f-bb99-5df26b4fb4e7" /> |
| 276 | + |
| 277 | +<img width="690" alt="image" src="https://github.com/user-attachments/assets/61e01872-f401-485d-aa9a-8c1388e76a5b" /> |
0 commit comments