# Nginx Stream + SSL Preread 自动分流方案

> 基于 Nginx stream 模块 + ssl_preread 的 TCP 层协议检测自动分流，支持多子域名、多端口，HTTP 自动跳转 HTTPS。

## 项目概述

本方案使用 Nginx 的 `stream` 模块配合 `ssl_preread` 功能，在 **TCP 层**（OSI 第 4 层）检测入站流量类型并自动分流：

- **TLS 流量** → Nginx SSL 终结 → 反向代理到内网 HTTP 服务
- **明文 HTTP 流量** → 301 永久重定向到 HTTPS

用户无论输入 `http://` 还是 `https://`，均可自动获得 HTTPS 加密访问。

## 架构特点

- ✅ **TCP 层分流**：不解密 TLS，性能开销极低
- ✅ **多子域名支持**：chanking / mqtt / baolin 等子域名独立配置
- ✅ **协议自动检测**：通过 ssl_preread 预读 ClientHello 判断协议
- ✅ **HTTP 自动跳转**：明文流量 301 重定向到 HTTPS
- ✅ **端口隔离**：每个外网端口独立 stream server + 独立 map 变量
- ✅ **配置模块化**：主配置与子域名配置分离，便于独立维护
- ✅ **WebSocket 支持**：完整透传 Upgrade 头
- ✅ **安全加固**：TLSv1.2/1.3、HSTS、强加密套件、通配符证书

## 端口与域名映射表

| 域名 | 外网端口 | 后端服务 | HTTPS 内部端口 | HTTP 跳转端口 | 用途 |
|------|---------|---------|---------------|-------------|------|
| **chanking.zhonjin.com** | 40130 | 127.0.0.1:5004 | 5005 | 5006 | 主 Web 服务 |
| **mqtt.zhonjin.com** | 40715 | 127.0.0.1:8085 | 5007 | 5008 | MQTT 服务 |
| **baolin.zhonjin.com** | 40716 | 127.0.0.1:5000 | 5009 | 5010 | 宝林服务 A |
| **baolin.zhonjin.com** | 40719 | 127.0.0.1:5001 | 5011 | 5012 | 宝林服务 B |

## 数据流

```
外网请求 (HTTP/HTTPS)
    │
    ▼
stream 端口监听 (40130/40715/40716/40719)
    │
    ├─ ssl_preread 检测协议
    │
    ├─ TLS 流量 ──→ HTTPS server (SSL 终结) ──→ proxy_pass 后端 HTTP 服务
    │
    └─ 明文 HTTP ──→ HTTP server ──→ 301 重定向到 HTTPS
```

## 配置文件结构

```
/etc/nginx/
├── nginx.conf                      # 主配置（40130 + 全局参数 + include）
├── conf.d/
│   └── zhonjin_http.conf           # 子域名 HTTP 服务（mqtt/baolin）
└── stream.d/
    └── zhonjin_stream.conf         # 子域名 Stream 分流（mqtt/baolin）
```

## 快速部署

### 1. 安装 Nginx

```bash
sudo apt update
sudo apt install -y nginx-full certbot python3-certbot-nginx
```

### 2. 申请通配符 SSL 证书

```bash
sudo certbot certonly --manual --preferred-challenges dns \
    -d zhonjin.com -d "*.zhonjin.com"
```

### 3. 部署配置

```bash
sudo mkdir -p /etc/nginx/conf.d /etc/nginx/stream.d
sudo cp nginx.conf /etc/nginx/nginx.conf
sudo cp zhonjin_http.conf /etc/nginx/conf.d/zhonjin_http.conf
sudo cp zhonjin_stream.conf /etc/nginx/stream.d/zhonjin_stream.conf
sudo nginx -t && sudo systemctl reload nginx
```

### 4. 配置防火墙

```bash
sudo ufw allow 40130/tcp
sudo ufw allow 40715/tcp
sudo ufw allow 40716/tcp
sudo ufw allow 40719/tcp
```

### 5. 验证

```bash
# HTTPS 访问
curl -I https://chanking.zhonjin.com:40130
curl -I https://mqtt.zhonjin.com:40715
curl -I https://baolin.zhonjin.com:40716
curl -I https://baolin.zhonjin.com:40719

# HTTP 跳转（应返回 301）
curl -I http://chanking.zhonjin.com:40130
curl -I http://mqtt.zhonjin.com:40715
curl -I http://baolin.zhonjin.com:40716
curl -I http://baolin.zhonjin.com:40719
```

## 项目文件说明

| 文件 | 说明 |
|------|------|
| [nginx.conf](./nginx.conf) | 主配置文件（全局参数 + 40130 端口 + include 指令） |
| [zhonjin_http.conf](./zhonjin_http.conf) | 子域名 HTTP 服务配置（include 到 http 块） |
| [zhonjin_stream.conf](./zhonjin_stream.conf) | 子域名 Stream 分流配置（include 到 stream 块） |
| [zhonjin.com.conf](./zhonjin.com.conf) | 配置总览说明文档 |
| [CHANGELOG.md](./CHANGELOG.md) | 变更日志（持续更新） |
| [TECH_DOC.md](./TECH_DOC.md) | 完整技术方案文档（持续更新） |
| [RASPBERRYPI_SETUP.md](./RASPBERRYPI_SETUP.md) | 树莓派 5 部署指南 |
| [QA_ARCHIVE.md](./QA_ARCHIVE.md) | 技术问答归档（持续更新） |
| [git_push.sh](./git_push.sh) | Git 仓库初始化与推送脚本 |

## 环境要求

| 组件 | 最低版本 | 推荐版本 |
|------|----------|----------|
| Nginx | 1.11.5+ | 1.26+ |
| 操作系统 | Ubuntu 22.04 | Ubuntu 24.04 / 树莓派 5 |
| SSL 证书 | Let's Encrypt 通配符 | Let's Encrypt + 自动续期 |

### 必需 Nginx 模块

- `ngx_stream_module` — TCP/UDP 代理
- `ngx_stream_ssl_preread_module` — TLS ClientHello 预读
- `ngx_http_ssl_module` — HTTP SSL 终结
- `ngx_http_v2_module` — HTTP/2 支持

## 安全配置

- **TLS 协议**：仅 TLSv1.2 / TLSv1.3
- **HSTS**：max-age=31536000（1 年）
- **加密套件**：ECDHE + AES-GCM 系列
- **内部端口**：仅监听 127.0.0.1，外部不可直接访问
- **版本隐藏**：`server_tokens off`
- **通配符证书**：`*.zhonjin.com` 覆盖所有子域名

## 扩展新端口

详见 [TECH_DOC.md - 端口扩展指南](./TECH_DOC.md#14-端口扩展指南)

简要步骤：
1. 在 `zhonjin_http.conf` 中添加 HTTPS server + HTTP 跳转 server
2. 在 `zhonjin_stream.conf` 中添加 map + stream server
3. 配置防火墙放行新端口
4. `sudo nginx -t && sudo systemctl reload nginx`

## Git 仓库

```bash
# 克隆仓库
git clone https://git.zhonjin.com:40717/steven_roc/nginx-stream-ssl-preread.git

# 首次推送（使用 git_push.sh）
chmod +x git_push.sh
./git_push.sh
```

## 许可证

MIT License

## 维护者

- **steven_roc**
- 仓库地址：`https://git.zhonjin.com:40717/steven_roc`

---

*本项目文档持续更新，详见各文档说明。*