# local_share

**Repository Path**: ai0223/local_share

## Basic Information

- **Project Name**: local_share
- **Description**: 高速局域网传输文件。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-11-11
- **Last Updated**: 2026-11-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LocalShare

跨平台 (Windows / Linux) 局域网高速文件传输 C++ 控制台程序，基于 **Boost.Asio (`stream_file` + C++20 协程)** 与 **Modern CMake (C++20)** 构建，纯命令行交互，无 UI 开销，专为千兆及万兆局域网满速文件分发设计。

---

## 🌟 特性 (Features)

- **极致性能**：
  - 自动调优套接字参数：启用 `TCP_NODELAY`，默认设置 4 MB 套接字收发缓冲区（`SO_SNDBUF` / `SO_RCVBUF`）。
  - **C++20 协程 + `boost::asio::stream_file` 双缓冲异步流水线**：Windows 基于 IOCP、Linux 基于 `io_uring`，磁盘异步读写与 Socket 异步收发并行重叠，配合 Scatter-Gather 缓冲区规避冗余内存深拷贝。
  - **并发 ACK 流水线 (`SendAllFiles && ReadAllAcks`)**：消除海量小文件传输时的逐文件 RTT 等待开销。
  - **单句柄打开与磁盘预分配**：Windows (`CreateFileW` + `stream_file::resize`) 与 Linux (`posix_fallocate`)，减少打开系统调用与磁盘碎片。
- **跨平台一致性**：
  - 原生支持 Windows (MSVC 2022 / Clang) 与 Linux (GCC 11+ / Clang 14+)。
  - 线协议统一采用 UTF-8 路径编码与严格路径穿越防御（过滤 `..`、盘符及根目录），支持单文件与含中文/Unicode 的多级目录递归传输。
- **数据完整性保障**：
  - 采用编译期生成的 **Slicing-by-8** IEEE 802.3 CRC32 查表算法，单遍累积计算逐块与全文件校验和，接收端落盘前即刻比对。
- **优良的 Console 交互**：
  - 实时吞吐率（MB/s / Gbps，指数加权平滑过滤速率抖动）。
  - 百分比进度、已传大小/总大小、剩余时间 (ETA) 估算及当前文件指示。
  - 优雅的 Ctrl+C 信号拦截与网络通道安全中断。

---

## 🛠️ 构建与环境要求 (Building)

### 1. Windows 环境 (基于 VideoLinkProbe 参考规范)

- **编译工具链**：VS 2022 (MSVC x64) + Ninja + CMake 3.20+
- **第三方依赖 (Boost)**：
  - 默认路径：`D:/dev_libs/boost_1_88_0`（已在 CMake 和 `.vscode/settings.json` 中预设）
- **命令行快速编译**：

  ```cmd
  call "d:\Program Files\Microsoft Visual Studio\2022\Professional\VC\Auxiliary\Build\vcvars64.bat"
  cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
  cmake --build build --config Release
  ```

- **VS Code 集成**：
  - Windows 环境：将 `.vscode/settings.windows.json` 复制或重命名为 `.vscode/settings.json`。
  - Linux 环境：将 `.vscode/settings.linux.json` 复制或重命名为 `.vscode/settings.json`。
  - 打开 VS Code，CMake Tools 插件将自动读取该配置并启用 Ninja 与 clangd。直接选择 `[Release]` 或 `[RelWithDebInfo]` 点击下方状态栏 `Build` 即可。

### 2. Linux 环境 (Ubuntu / Debian / RHEL / Arch)

> **依赖说明**：需要 Boost >= 1.88（可自行编译安装并指定 `-DBOOST_ROOT=/path/to/boost`）以及 **`liburing`**。Linux 环境下 `boost::asio::stream_file` 必须基于 `io_uring` 异步引擎运行，构建前必须安装系统开发库：

- **安装基础构建工具与 liburing**：

  ```bash
  # Ubuntu / Debian
  sudo apt-get update && sudo apt-get install -y cmake ninja-build build-essential pkg-config liburing-dev

  # Fedora / RHEL 9+
  sudo dnf install -y cmake ninja-build gcc-c++ pkgconfig liburing-devel

  # Arch Linux
  sudo pacman -S cmake ninja base-devel pkgconf liburing
  ```

- **命令行快速构建**：

  ```bash
  # 构建（若 Boost 安装在非标准路径，可通过 -DCMAKE_PREFIX_PATH 指定）
  cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
  cmake --build build
  ```

---

## 🚀 使用指南 (Usage)

编译生成的可执行文件位于 `build/bin/`：

- `local_share`（统一 CLI）
- `local_share_recv`（独立接收端）
- `local_share_send`（独立发送端）
- `test_transfer`（回路自测套件）

### 1. 接收端 (Receiver)

在接收文件的主机上启动监听：

```bash
# 启动接收端，监听 9876 端口，保存到当前目录（单次传输完成即退出）
local_share recv -p 9876 -d ./received_files

# 持续守护监听模式（多次接收）
local_share recv -p 9876 -d ./received_files -c

# 调整网络缓冲区为 8MB
local_share recv -p 9876 -d ./received_files --buffer-size 8192
```

### 2. 发送端 (Sender)

在发送文件的主机上发起传输：

```bash
# 发送单个大文件
local_share send -h 192.168.1.100 -p 9876 -f ./large_archive.zip

# 递归发送整个目录
local_share send -h 192.168.1.100 -p 9876 -d ./my_datasets

# 自定义分块大小为 1MB (1024KB)，套接字缓冲区为 8MB
local_share send -h 192.168.1.100 -p 9876 -f ./video.mp4 --chunk-size 1024 --buffer-size 8192
```

### 3. 执行自动化自测试 (Test Transfer)

验证本机网络回环传输与数据一致性：

```bash
./build/bin/test_transfer
```

---

## 📦 安装与打包 (Install & Packaging)

项目已集成标准的 `CMake install` 与 `CPack`，并提供了跨平台一键部署与打包脚本。

### 1. Windows 打包（绿色 ZIP 免安装包 / NSIS 安装向导）

- **脚本一键打包（推荐）**：
  直接双击或在命令行运行 `scripts/package.bat`（或在 PowerShell 中运行 `scripts/package.ps1`），脚本会自动检测 VS 2022 环境并编译打包：

  ```cmd
  :: 打包为绿色免安装 ZIP（默认，输出至 build/packages/）
  scripts\package.bat

  :: 打包为 NSIS 安装程序（需系统预装 NSIS）
  scripts\package.bat NSIS
  ```

- **纯 CMake / CPack 命令行**：

  ```cmd
  cmake --build build --config Release
  cd build && cpack -G ZIP
  ```

> 打包生成的 ZIP 压缩包已自动包含可执行程序及所需的 Boost 动态运行时 DLL，解压即可运行。

### 2. Linux 安装与打包

- **一键安装到用户目录（推荐，无需 sudo 权限）**：
  默认安装至 `~/.local`（对应可执行程序安装到 `~/.local/bin`，现代 Ubuntu/Debian 默认已将其加入 PATH）：

  ```bash
  # 部署到 ~/.local（普通用户默认）
  ./scripts/install.sh

  # 或自定义安装目录
  ./scripts/install.sh --prefix /opt/local_share
  ```

- **一键打包（生成 `.tar.gz` 发布包）**：

  ```bash
  ./scripts/package.sh
  ```

- **纯 CMake 原生安装指令**：

  ```bash
  cmake --install build --prefix ~/.local
  ```

---

## 📁 项目目录结构

```text
.
├── .agents/skills/             # C++ 与 CMake 架构及性能审查技能
├── .vscode/                    # VS Code 配置文件 (clangd, CMake Tools, 调试 launch)
│   ├── settings.windows.json   # Windows 环境模板 (Boost 路径 D:/dev_libs/boost_1_88_0, clangd, Ninja)
│   ├── settings.linux.json     # Linux 环境模板 (/usr/local, clangd, Ninja)
│   ├── settings.json           # 本地当前生效配置 (已加入 .gitignore，从模板复制)
│   ├── launch.json             # 跨平台 (MSVC / GDB) 一键调试配置
│   └── tasks.json              # 构建与测试任务
├── cmake/                      # 编译与构建辅助模块
├── include/local_share/        # 公开接口头文件
│   ├── protocol.hpp            # 二进制报文头、帧格式与序列化
│   ├── socket_tuning.hpp       # TCP_NODELAY 与收发缓冲区调优
│   ├── crc32.hpp               # 高性能 IEEE 802.3 CRC32 计算类
│   ├── file_io.hpp             # 目录递归扫描、路径规范化与空间预分配
│   ├── progress_bar.hpp        # 终端平滑刷新进度条与 EMA 速率平滑器
│   ├── sender.hpp              # 发送端核心引擎
│   └── receiver.hpp            # 接收端核心引擎
├── scripts/                    # 跨平台构建、安装与打包脚本
│   ├── package.bat             # Windows 自动探测 VS 环境并打 ZIP/NSIS 包
│   ├── package.ps1             # Windows PowerShell 打包脚本
│   ├── package.sh              # Linux CPack TGZ 打包脚本
│   └── install.sh              # Linux 非 root 一键部署脚本 (默认 ~/.local)
├── src/
│   ├── core/                   # 核心静态库实现
│   └── apps/                   # 控制台程序入口 (local_share, send, recv)
├── test/
│   └── test_transfer.cpp       # 回路传输与数据校验单元测试
├── .clang-format               # 代码风格格式化规范 (Google C++ 规范)
├── .gitignore                  # Git 忽略文件列表
├── CMakeLists.txt              # Modern CMake 顶层构建脚本
├── GEMINI.md                   # 项目工程约束规范
└── README.md                   # 项目说明文档
```

---

## 📜 许可证 (License)

本项目采用 MIT 许可证，可自由商用与修改。