# Linux-Router

**Repository Path**: du_chinese/linux-router

## Basic Information

- **Project Name**: Linux-Router
- **Description**: Ubuntu Linux 路由器自动配置方案

将 Ubuntu 系统快速配置为功能完整的软路由器，支持多网卡路由、DHCP 服务、无线 AP、WiFi 客户端、NAT 转发等功能。

核心特性：多网卡路由、无线 AP 自动创建、DHCP 服务、NAT 转发、一键自动化配置、systemd 开机自启动

快速开始：安装依赖 → 配置参数 → 执行脚本，三步完成路由器配置
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-11-02
- **Last Updated**: 2025-11-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Ubuntu 路由器配置方案

本目录包含将 Ubuntu 系统配置为功能完整路由器的完整方案文档。

**作者**：杜更新 (dugengxin@jrsensing.com) | **公司**：[上海极锐星瀚传感技术有限公司](https://www.jrsensing.com/)

## 📋 文档说明

### 1. REQUIREMENTS.md - 需求文档
详细的功能需求和非功能需求说明，包含：
- 原始需求分析
- 优化后的完整需求列表
- 功能需求（FR-001 至 FR-028）
- 非功能需求（性能、可靠性、安全性等）
- 需求优先级分类
- 验收标准

**适用对象**：项目管理者、需求分析师、开发人员

### 2. NETWORK_ROUTER_DESIGN.md - 技术方案设计文档
完整的技术实施方案，包含：
- 网络拓扑结构设计
- 核心组件选型
- 详细实施方案步骤
- 配置文件示例
- 技术架构说明
- 测试验证清单
- 实施注意事项
- 后续扩展建议

**适用对象**：系统管理员、网络工程师、开发实施人员

## 🎯 项目目标

将一台配备 6 个有线网卡和 1 个支持虚拟 AP 的无线网卡的 Ubuntu 系统，配置为具备以下功能的路由器：

- ✅ WAN 口自动获取公网 IP
- ✅ 5 个 LAN 口提供 DHCP 服务
- ✅ 无线 AP 自动创建和管理
- ✅ WiFi 客户端模式支持
- ✅ NAT 转发和路由功能
- ✅ 开机自启动所有服务
- ✅ 内网固定 IP 和域名访问

## 📁 文档结构

```
ubuntu-router-config/
├── README.md                      # 本文件
├── docs/                          # 文档目录
│   ├── REQUIREMENTS.md            # 需求文档
│   ├── NETWORK_ROUTER_DESIGN.md   # 技术方案设计文档
│   ├── README_SCRIPTS.md          # 自动化脚本使用指南
│   └── QUICKSTART.md              # 快速开始指南
├── router_setup.py                # 主配置脚本（Python）
├── install.sh                     # 安装脚本（Shell）
├── uninstall.sh                   # 卸载脚本（Shell）
├── config.yaml.example            # 配置文件模板
└── scripts/
    └── monitor.sh                 # 服务监控脚本
```

**注意**：在 `ubuntu-router-config` 目录外部还有打包脚本：
- `pack_router.py` - Python 打包脚本

使用这些脚本可以将整个配置目录打包为 tar.gz 文件，方便分发和备份。

## 🚀 快速开始

### 方法一：使用自动化脚本（推荐）

1. **安装依赖**
   ```bash
   sudo bash install.sh
   ```

2. **配置参数**
   ```bash
   cp config.yaml.example config.yaml
   nano config.yaml  # 根据实际情况修改配置
   ```

3. **执行配置**
   ```bash
   sudo python3 router_setup.py
   ```

4. **验证配置**
   ```bash
   sudo bash scripts/monitor.sh
   ```

详细说明请参考 **README_SCRIPTS.md**

### 方法二：手动配置

1. **阅读需求文档**（REQUIREMENTS.md）
   - 了解完整的功能需求
   - 确认需求优先级
   - 查看验收标准

2. **阅读技术方案**（NETWORK_ROUTER_DESIGN.md）
   - 了解网络拓扑结构
   - 熟悉技术选型和组件
   - 查看配置示例

3. **开始实施**
   - 按照技术方案中的实施步骤操作
   - 参考配置示例进行配置
   - 使用测试验证清单进行验证

## 📝 需求优化说明

原始需求已进行以下优化和补充：

### 新增功能
- ✅ 网络接口自动识别与管理
- ✅ WAN 口静态 IP 配置支持
- ✅ 服务依赖管理
- ✅ 服务故障自动恢复
- ✅ 配置热重载功能
- ✅ 监控与日志记录

### 需求细化
- ✅ DHCP 配置详细参数（地址池、租约时间等）
- ✅ AP 配置详细参数（加密方式、信道选择等）
- ✅ WiFi 客户端优先级和自动切换
- ✅ AP 与客户端模式共存/切换机制
- ✅ 域名访问的多种实现方式

### 架构优化
- ✅ LAN 口统一桥接设计
- ✅ 网络拓扑可视化
- ✅ 服务依赖关系明确
- ✅ 配置文件结构化

## 🔧 核心技术栈

- **网络配置**：netplan / NetworkManager
- **网桥管理**：bridge-utils / ip link
- **DHCP 服务**：dnsmasq
- **无线 AP**：hostapd
- **WiFi 客户端**：wpa_supplicant
- **NAT/路由**：iptables / nftables
- **mDNS 服务**：avahi-daemon
- **服务管理**：systemd

## ⚠️ 注意事项

1. **硬件兼容性**：确认无线网卡支持 AP 模式和 nl80211 驱动
2. **接口命名**：现代 Ubuntu 使用可预测的网络接口命名，需要先识别实际接口名称
3. **模式切换**：部分无线网卡不支持 AP+STA 同时运行，需要实现模式切换
4. **权限要求**：配置网络需要 root 权限
5. **备份配置**：修改系统网络配置前建议备份原始配置

## 📞 后续支持

实施过程中如遇到问题，可参考：
- 各组件官方文档
- 技术方案中的"实施注意事项"章节
- 测试验证清单进行故障排查

## 📄 文档版本

- **版本**：v1.0
- **创建日期**：2025-11-02
- **最后更新**：2025-11-02

## 👥 作者信息

- **公司**：上海极锐星瀚传感技术有限公司
- **作者**：杜更新
- **邮箱**：dugengxin@jrsensing.com
- **网站**：https://www.jrsensing.com/

## 📜 开源许可

本项目采用 [MIT License](LICENSE) 开源协议。

Copyright (c) 2025 上海极锐星瀚传感技术有限公司

## 📌 关键特性对比

| 特性 | 原始需求 | 优化后需求 |
|------|---------|-----------|
| WAN 口 | DHCP 获取 IP | DHCP + 静态 IP 可选 |
| LAN 口 | 5 个网卡提供 DHCP | 统一桥接 + 详细 DHCP 配置 |
| 无线 AP | 自动创建，可配置 | 自动创建 + 完整参数配置 + 故障恢复 |
| WiFi 客户端 | 支持连接外部 WiFi | 支持连接 + 优先级 + 自动切换 |
| 开机自启动 | 支持 | systemd 服务 + 依赖管理 |
| 内网访问 | 固定 IP 或域名 | 固定 IP + mDNS + 自定义域名 |

---

## 🛠️ 自动化脚本

本项目提供了完整的自动化配置脚本，可以快速完成路由器配置：

- **router_setup.py** - Python 主配置脚本，自动化执行所有网络配置
- **install.sh** - 自动安装所需软件包和依赖
- **uninstall.sh** - 一键卸载所有配置
- **config.yaml.example** - 配置文件模板，包含所有可配置选项

**推荐使用自动化脚本**，可以大大简化配置过程，减少出错概率。

详细使用方法请参考 **README_SCRIPTS.md**

---

## 📦 打包分发

项目根目录提供了打包脚本，可以将整个配置目录打包为 tar.gz 文件：

### 使用 Python 脚本
```bash
python3 pack_router.py
```

打包脚本会自动：
- 排除临时文件和敏感配置（如 `config.yaml`）
- 保留示例配置文件（`config.yaml.example`）
- 生成带时间戳的压缩包名称
- 显示压缩包大小和内容预览

生成的压缩包可以直接分发给其他 Ubuntu 系统使用。

---

**提示**：
- **快速部署**：使用自动化脚本（docs/README_SCRIPTS.md）
- **深入了解**：阅读 docs/REQUIREMENTS.md 了解需求，docs/NETWORK_ROUTER_DESIGN.md 了解技术方案
- **打包分发**：使用外部的 `pack_router.py` 脚本