# 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

## 项目简介

NAT-Traverse 是一款开源的 NAT 穿透与内网穿透解决方案，支持 TCP、HTTP、HTTPS 协议，能够帮助用户快速建立安全稳定的数据隧道，实现跨 NAT/防火墙的网络通信。

## 核心功能

- **多协议支持**：支持 TCP、HTTP、HTTPS 三种隧道类型
- **安全认证**：基于 Token 的认证机制，支持 JWT 验证
- **可视化管控**：提供 Web 管理界面，支持隧道管理、用户管理、告警配置等
- **实时监控**：提供 Prometheus 指标接口，支持流量统计和在线状态监控
- **告警通知**：支持多种通知渠道（Webhook、邮件、钉钉、企业微信、飞书）
- **自动证书**：支持 ACME 协议自动申请 SSL 证书
- **数据备份**：支持自动备份和手动恢复，确保数据安全

## 系统架构

NAT-Traverse 采用模块化设计，主要包含以下核心组件：

### 控制通道 (Control Server)
负责客户端认证、隧道建立、心跳维护等控制平面功能。

### 隧道管理 (Tunnel Manager)
管理所有隧道的生命周期，包括创建、监控、关闭等操作。

### 代理服务 (Proxy Server)
提供 TCP 和 HTTP 代理能力，处理隧道数据的转发。

### HTTP 路由器 (HTTP Router)
支持 HTTPS 域名解析和 SNI 路由，实现多域名共享隧道。

### API Server (管理 API)
提供 RESTful API 接口，支持管理后台和第三方系统集成。

## 快速开始

### Docker 部署（推荐）

```bash
# 克隆项目
git clone https://gitee.com/hackor/nat-traverse.git
cd nat-traverse

# 配置环境变量
cp packages/server/.env.example packages/server/.env
# 编辑 .env 文件，配置必要参数

# 启动服务
docker-compose up -d
```

### 手动部署

请参考 [部署文档](docs/ARCHITECTURE.md) 了解详细的部署架构和配置要求。

## 使用指南

### 1. 服务端部署

```bash
# 安装依赖
npm install

# 构建项目
npm run build

# 启动服务
./start-server.sh
```

### 2. 客户端连接

```bash
# 配置认证Token后启动客户端
AUTH_TOKEN=your_token ./start-client.sh
```

### 3. 管理后台

服务启动后，访问 `http://your-server:80` 进入管理界面，默认管理员账号密码由环境变量配置。

## API 文档

完整的 API 接口文档请参阅 [API 文档](docs/API.md)，包含：

- 认证管理（登录、修改密码）
- 隧道管理（列表、详情、配置、流量统计）
- 统计信息（仪表盘、流量总览）
- 用户管理
- Token 管理
- 告警配置
- 系统管理
- 审计日志

## 配置说明

### 环境变量

主要配置项位于 `packages/server/.env`：

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `ADMIN_PASSWORD` | 管理员密码 | - |
| `JWT_SECRET` | JWT 密钥 | 自动生成 |
| `ACME_EMAIL` | ACME 证书注册邮箱 | - |
| `BACKUP_ENABLED` | 是否启用自动备份 | true |
| `BACKUP_CRON` | 备份定时表达式 | 0 3 * * * |

### 通知配置

支持配置多种告警通知渠道：

- **Webhook**：配置 webhook URL 用于自定义通知
- **邮件**：SMTP 邮件服务器配置
- **钉钉**：钉钉机器人 Webhook
- **企业微信**：企业微信应用消息
- **飞书**：飞书机器人 Webhook

## 备份与恢复

系统支持自动定时备份和手动恢复功能。详情请参考 [备份恢复指南](deploy/BACKUP_RECOVERY.md)。

## 开发指南

### 环境搭建

1. 安装 Node.js 20+
2. 安装项目依赖：
```bash
npm install
```
3. 构建公共包：
```bash
npm run build --workspace=packages/common
```
4. 启动开发服务：
```bash
# 启动服务端
npm run dev --workspace=packages/server

# 启动管理后台
npm run dev --workspace=packages/admin
```

### 运行测试

```bash
# 运行所有测试
npm test

# 运行单包测试
npm run test --workspace=packages/server
```

## 项目结构

```
nat-traverse/
├── packages/
│   ├── server/          # 服务端核心代码
│   ├── client/          # 客户端代理
│   ├── admin/           # 管理后台前端
│   ├── common/          # 公共类型定义
│   └── data/            # 数据存储
├── docs/                # 文档
├── deploy/              # 部署相关
├── nginx/               # Nginx 配置
├── scripts/             # 安装脚本
└── systemd/             # Systemd 服务配置
```

## 贡献指南

欢迎贡献代码或提出建议。请参考 [贡献指南](CONTRIBUTING.md) 了解详细的开发流程和代码规范。

## 更新日志

请参考 [CHANGELOG.md](CHANGELOG.md) 了解版本更新历史。

## 许可证

本项目采用 MIT 许可证开源。

## 联系方式

- 项目地址：https://gitee.com/hackor/nat-traverse
- 问题反馈：https://gitee.com/hackor/nat-traverse/issues