# nat-traverse

**Repository Path**: hackor/nat-traverse

## Basic Information

- **Project Name**: nat-traverse
- **Description**: 类似花生壳的内网映射穿透软件，支持 TCP / HTTP / HTTPS 隧道。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-03
- **Last Updated**: 2026-08-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# NAT-Traverse

## Project Introduction

NAT-Traverse is an open-source NAT traversal and internal network penetration solution. It supports TCP, HTTP, and HTTPS protocols, capable of helping users quickly establish secure and stable data tunnels to enable network communication across NATs and firewalls.

## Core Features

- **Multi-protocol Support**: Supports three tunnel types: TCP, HTTP, and HTTPS
- **Secure Authentication**: Token-based authentication mechanism, supports JWT verification
- **Visual Management**: Provides a web management interface supporting tunnel management, user management, alert configuration, etc.
- **Real-time Monitoring**: Provides Prometheus metrics interfaces, supports traffic statistics and online status monitoring
- **Alert Notifications**: Supports multiple notification channels (Webhook, Email, DingTalk, WeChat Work, Lark)
- **Automatic Certificates**: Supports automatic SSL certificate application via ACME protocol
- **Data Backup**: Supports automatic backup and manual recovery to ensure data security

## System Architecture

NAT-Traverse adopts a modular design, mainly including the following core components:

### Control Server
Responsible for client authentication, tunnel establishment, heartbeat maintenance, and other control plane functions.

### Tunnel Manager
Manages the lifecycle of all tunnels, including creation, monitoring, closing, and other operations.

### Proxy Server
Provides TCP and HTTP proxy capabilities, handling tunnel data forwarding.

### HTTP Router
Supports HTTPS domain resolution and SNI routing, achieving multi-domain shared tunnels.

### API Server (Management API)
Provides RESTful API interfaces, supporting management backend and third-party system integration.

## Quick Start

### Docker Deployment (Recommended)

```bash
# Clone the project
git clone https://gitee.com/hackor/nat-traverse.git
cd nat-traverse

# Configure environment variables
cp packages/server/.env.example packages/server/.env
# Edit .env file to configure necessary parameters

# Start services
docker-compose up -d
```

### Manual Deployment

Please refer to the [Deployment Documentation](docs/ARCHITECTURE.md) for detailed deployment architecture and configuration requirements.

## Usage Guide

### 1. Server Deployment

```bash
# Install dependencies
npm install

# Build project
npm run build

# Start service
./start-server.sh
```

### 2. Client Connection

```bash
# Start client after configuring AUTH_TOKEN
AUTH_TOKEN=your_token ./start-client.sh
```

### 3. Admin Panel

After the service starts, access `http://your-server:80` to enter the management interface. The default admin username and password are configured via environment variables.

## API Documentation

For complete API documentation, please refer to the [API Documentation](docs/API.md), including:

- Authentication Management (Login, Change Password)
- Tunnel Management (List, Details, Configuration, Traffic Statistics)
- Statistics (Dashboard, Traffic Overview)
- User Management
- Token Management
- Alert Configuration
- System Management
- Audit Logs

## Configuration Instructions

### Environment Variables

Main configuration items are located in `packages/server/.env`:

| Variable Name | Description | Default Value |
|--------|------|--------|
| `ADMIN_PASSWORD` | Admin Password | - |
| `JWT_SECRET` | JWT Secret | Auto-generated |
| `ACME_EMAIL` | ACME Certificate Registration Email | - |
| `BACKUP_ENABLED` | Enable Automatic Backup | true |
| `BACKUP_CRON` | Backup Cron Expression | 0 3 * * * |

### Notification Configuration

Supports configuring multiple alert notification channels:

- **Webhook**: Configure webhook URL for custom notifications
- **Email**: SMTP email server configuration
- **DingTalk**: DingTalk Robot Webhook
- **WeChat Work**: WeChat Work App Message
- **Lark**: Lark Robot Webhook

## Backup & Recovery

The system supports automatic scheduled backups and manual recovery. For details, please refer to the [Backup Recovery Guide](deploy/BACKUP_RECOVERY.md).

## Development Guide

### Environment Setup

1. Install Node.js 20+
2. Install project dependencies:
```bash
npm install
```
3. Build common package:
```bash
npm run build --workspace=packages/common
```
4. Start development services:
```bash
# Start server
npm run dev --workspace=packages/server

# Start admin panel
npm run dev --workspace=packages/admin
```

### Run Tests

```bash
# Run all tests
npm test

# Run single package test
npm run test --workspace=packages/server
```

## Project Structure

```
nat-traverse/
├── packages/
│   ├── server/          # Server core code
│   ├── client/          # Client proxy
│   ├── admin/           # Admin panel frontend
│   ├── common/          # Common type definitions
│   └── data/            # Data storage
├── docs/                # Documentation
├── deploy/              # Deployment related
├── nginx/               # Nginx configuration
├── scripts/             # Installation scripts
└── systemd/             # Systemd service configuration
```

## Contributing

Contributions or suggestions are welcome. Please refer to the [Contributing Guide](CONTRIBUTING.md) for detailed development processes and code standards.

## Changelog

Please refer to [CHANGELOG.md](CHANGELOG.md) for version update history.

## License

This project is open source under the MIT License.

## Contact

- Project Address: https://gitee.com/hackor/nat-traverse
- Issue Feedback: https://gitee.com/hackor/nat-traverse/issues