## 概述

本教程介绍如何在 Linux 系统上，通过挂载 Windows 共享文件夹（SMB/CIFS 协议），并结合 Python 的 `watchdog` 库实现对共享目录的实时文件监控。

---

## 一、原理介绍

### 1.1 SMB/CIFS 协议

**SMB**（Server Message Block）是微软开发的网络文件共享协议，Windows 的"共享文件夹"功能就基于此协议。**CIFS**（Common Internet File System）是 SMB 的一个早期方言，现在通常混用这两个名称。

```
┌─────────────────┐         局域网          ┌─────────────────┐
│   Linux 客户端   │  ←── SMB/CIFS (445) ──→ │  Windows 服务端  │
│                 │                          │                 │
│  /mnt/share/    │  ←── 挂载映射 ──────────  │  \\server\share │
└─────────────────┘                          └─────────────────┘
```

核心要点：

- 通信端口：**TCP 445**（SMB 直连）
- Linux 内核通过 `cifs.ko` 内核模块实现客户端支持
- 挂载后，远程共享目录对 Linux 来说就像本地目录一样可读写

### 1.2 CIFS 挂载原理

`mount -t cifs` 命令调用内核的 CIFS 文件系统驱动，建立一个持久的 TCP 连接到 Windows 机器，并将远程目录映射到本地挂载点。挂载成功后：

- 所有对挂载点的文件操作（读/写/列目录）都会通过网络转发到 Windows
- 对 Linux 上层应用（包括 Python）完全透明，就像操作本地文件一样

### 1.3 watchdog 的工作机制

`watchdog` 是一个 Python 文件系统监控库，支持多种底层实现：

| 观察器类型        | 底层机制                                                     | 适用场景         |
| ----------------- | ------------------------------------------------------------ | ---------------- |
| `Observer`        | `inotify`（Linux）/ `FSEvents`（macOS）/ `ReadDirectoryChangesW`（Windows） | 本地文件系统     |
| `PollingObserver` | 定时轮询，对比文件列表快照                                   | 网络挂载、跨平台 |

**为什么网络挂载必须用 `PollingObserver`？**

`inotify` 是 Linux 内核提供的文件系统事件通知机制，它只能监听**本地文件系统**的内核事件。CIFS 挂载虽然看起来像本地目录，但文件变更发生在远程 Windows 机器上，Linux 内核不会产生 `inotify` 事件。

`PollingObserver` 的工作方式：

```
每隔 N 秒
  ├── 扫描目录，生成当前文件快照（路径 + 修改时间 + 大小）
  ├── 与上次快照对比
  │   ├── 新增文件 → 触发 on_created 事件
  │   ├── 修改时间变化 → 触发 on_modified 事件
  │   └── 文件消失 → 触发 on_deleted 事件
  └── 保存当前快照，等待下次轮询
```

---

## 二、环境准备

### 2.1 安装系统依赖

```bash
# Ubuntu / Debian
sudo apt update
sudo apt install -y cifs-utils

# CentOS / RHEL
sudo yum install -y cifs-utils

# 验证安装
modinfo cifs
```

### 2.2 安装 Python 依赖

```bash
pip install watchdog
```

或者在使用 `uv` 的项目中：

```bash
uv pip install watchdog
```

---

## 三、挂载 Windows 共享文件夹

### 3.1 查看 Windows 上的共享名称

在挂载之前，先确认 Windows 机器上开放了哪些共享：

```bash
# 列出目标机器的所有共享（会提示输入密码）
smbclient -L //<Windows机器IP> -U <用户名>
```

输出示例：

```
Sharename       Type      Comment
---------       ----      -------
shared_data     Disk      
IPC$            IPC       Remote IPC
```

找到 `Type` 为 `Disk` 的条目，那就是可挂载的共享文件夹名。

### 3.2 创建挂载点

挂载点是 Linux 上的一个空目录，作为远程共享的"入口"：

```bash
sudo mkdir -p /mnt/windows_share
```

### 3.3 执行挂载

```bash
sudo mount -t cifs //<Windows机器IP>/<共享名> /mnt/windows_share \
  -o username=<用户名>,password=<密码>,vers=3.0
```

参数说明：

| 参数             | 说明                                    |
| ---------------- | --------------------------------------- |
| `-t cifs`        | 指定文件系统类型为 CIFS                 |
| `vers=3.0`       | 使用 SMB 3.0 协议（推荐，安全性更好）   |
| `username`       | Windows 账户用户名                      |
| `password`       | Windows 账户密码                        |
| `uid=1000`       | 可选，指定挂载后文件的 Linux 所有者 UID |
| `gid=1000`       | 可选，指定挂载后文件的 Linux 所有者 GID |
| `iocharset=utf8` | 可选，处理中文文件名时建议加上          |

### 3.4 验证挂载

```bash
# 查看挂载状态
mount | grep cifs

# 列出共享目录内容
ls -la /mnt/windows_share
```

### 3.5 使用凭据文件（更安全）

避免密码出现在命令行历史中，推荐使用凭据文件：

```bash
# 创建凭据文件
sudo nano /etc/smb_credentials

# 文件内容
username=<用户名>
password=<密码>
domain=<域名或WORKGROUP>

# 限制文件权限，只有 root 可读
sudo chmod 600 /etc/smb_credentials
```

挂载时引用：

```bash
sudo mount -t cifs //<Windows机器IP>/<共享名> /mnt/windows_share \
  -o credentials=/etc/smb_credentials,vers=3.0
```

### 3.6 设置开机自动挂载（可选）

编辑 `/etc/fstab`，添加一行：

```
//<Windows机器IP>/<共享名>  /mnt/windows_share  cifs  credentials=/etc/smb_credentials,vers=3.0,_netdev  0  0
```

`_netdev` 选项告诉系统等网络就绪后再挂载。

---

## 四、Python 监控脚本

### 4.1 基础版本

```python
import time
import logging
from watchdog.observers.polling import PollingObserver
from watchdog.events import FileSystemEventHandler

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s [%(levelname)s] %(message)s"
)
logger = logging.getLogger(__name__)


class ShareFolderHandler(FileSystemEventHandler):
    """处理共享文件夹中的文件系统事件"""

    def on_created(self, event):
        if not event.is_directory:
            logger.info(f"新文件创建: {event.src_path}")
            self.process_new_file(event.src_path)

    def on_modified(self, event):
        if not event.is_directory:
            logger.info(f"文件已修改: {event.src_path}")

    def on_deleted(self, event):
        logger.info(f"文件已删除: {event.src_path}")

    def on_moved(self, event):
        logger.info(f"文件已移动: {event.src_path} → {event.dest_path}")

    def process_new_file(self, path: str):
        """处理新文件的业务逻辑"""
        try:
            with open(path, "r", encoding="utf-8") as f:
                content = f.read()
            logger.info(f"文件内容长度: {len(content)} 字符")
            # 在这里添加你的业务处理逻辑
        except Exception as e:
            logger.error(f"处理文件失败: {e}")


def start_watcher(watch_path: str, poll_interval: int = 5):
    """
    启动文件监控

    Args:
        watch_path: 要监控的目录路径（挂载点）
        poll_interval: 轮询间隔，单位秒
    """
    handler = ShareFolderHandler()

    # 关键：使用 PollingObserver 而非默认的 Observer
    observer = PollingObserver(timeout=poll_interval)
    observer.schedule(handler, watch_path, recursive=True)
    observer.start()

    logger.info(f"开始监控目录: {watch_path}（轮询间隔: {poll_interval}s）")

    try:
        while True:
            time.sleep(1)
            if not observer.is_alive():
                logger.error("Observer 意外停止，正在重启...")
                observer.start()
    except KeyboardInterrupt:
        logger.info("收到中断信号，正在停止监控...")
        observer.stop()

    observer.join()
    logger.info("监控已停止")


if __name__ == "__main__":
    MOUNT_PATH = "/mnt/windows_share"  # 替换为你的挂载点路径
    start_watcher(MOUNT_PATH, poll_interval=5)
```

### 4.2 生产级版本（带过滤、去重、异常恢复）

```python
import time
import logging
from pathlib import Path
from watchdog.observers.polling import PollingObserver
from watchdog.events import FileSystemEventHandler, FileCreatedEvent

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s [%(levelname)s] %(message)s"
)
logger = logging.getLogger(__name__)


class RobustShareHandler(FileSystemEventHandler):
    """
    生产级共享文件夹事件处理器

    特性：
    - 文件类型过滤
    - 事件去重（防止短时间内重复触发）
    - 异常隔离，单个文件处理失败不影响整体
    """

    def __init__(self, watch_extensions: list[str] = None):
        super().__init__()
        # 只处理指定扩展名的文件，None 表示处理所有文件
        self.watch_extensions = watch_extensions
        self._processed: set[str] = set()

    def _should_process(self, path: str) -> bool:
        """判断是否需要处理该文件"""
        if self.watch_extensions is None:
            return True
        return Path(path).suffix.lower() in self.watch_extensions

    def on_created(self, event: FileCreatedEvent):
        if event.is_directory or not self._should_process(event.src_path):
            return

        # 简单去重：同一文件短时间内只处理一次
        if event.src_path in self._processed:
            return
        self._processed.add(event.src_path)

        logger.info(f"检测到新文件: {event.src_path}")
        self._safe_process(event.src_path)

    def on_modified(self, event):
        if event.is_directory or not self._should_process(event.src_path):
            return
        # 文件修改时清除去重记录，允许重新处理
        self._processed.discard(event.src_path)
        logger.info(f"文件已更新: {event.src_path}")

    def on_deleted(self, event):
        self._processed.discard(event.src_path)
        logger.info(f"文件已删除: {event.src_path}")

    def _safe_process(self, path: str):
        """带异常隔离的文件处理"""
        try:
            self.process_file(path)
        except Exception as e:
            logger.error(f"处理文件 {path} 时出错: {e}", exc_info=True)

    def process_file(self, path: str):
        """
        核心业务逻辑，子类可重写此方法

        Args:
            path: 新文件的完整路径
        """
        logger.info(f"正在处理: {path}")
        # 示例：读取 JSON 文件
        if path.endswith(".json"):
            import json
            with open(path, "r", encoding="utf-8") as f:
                data = json.load(f)
            logger.info(f"JSON 数据键: {list(data.keys()) if isinstance(data, dict) else '数组'}")


class SMBWatcherService:
    """SMB 共享文件夹监控服务"""

    def __init__(
        self,
        mount_path: str,
        poll_interval: int = 5,
        watch_extensions: list[str] = None,
    ):
        self.mount_path = mount_path
        self.poll_interval = poll_interval
        self.handler = RobustShareHandler(watch_extensions)
        self.observer: PollingObserver | None = None

    def start(self):
        """启动监控服务"""
        if not Path(self.mount_path).exists():
            raise RuntimeError(f"挂载点不存在: {self.mount_path}，请先执行挂载命令")

        self.observer = PollingObserver(timeout=self.poll_interval)
        self.observer.schedule(self.handler, self.mount_path, recursive=True)
        self.observer.start()
        logger.info(f"监控服务已启动: {self.mount_path}")

    def stop(self):
        """停止监控服务"""
        if self.observer:
            self.observer.stop()
            self.observer.join()
            logger.info("监控服务已停止")

    def run_forever(self):
        """持续运行，支持 Ctrl+C 优雅退出"""
        self.start()
        try:
            while True:
                time.sleep(1)
        except KeyboardInterrupt:
            pass
        finally:
            self.stop()


if __name__ == "__main__":
    service = SMBWatcherService(
        mount_path="/mnt/windows_share",   # 替换为你的挂载点
        poll_interval=5,                   # 每 5 秒轮询一次
        watch_extensions=[".json", ".csv", ".xlsx"],  # 只监控这些类型
    )
    service.run_forever()
```

---

## 五、常见问题排查

### 挂载失败：`No such file or directory`

挂载点目录不存在，先创建：

```bash
sudo mkdir -p /mnt/windows_share
```

### 挂载失败：`mount error(13): Permission denied`

- 检查用户名密码是否正确
- 确认 Windows 上该用户有访问该共享的权限
- 尝试加上 `domain=WORKGROUP` 参数

### 挂载失败：`mount error(115): Operation now in progress`

网络不通，检查：

```bash
# 测试网络连通性
ping <Windows机器IP>

# 测试 SMB 端口
nc -zv <Windows机器IP> 445
```

### 中文文件名乱码

挂载时加上字符集参数：

```bash
-o ...,iocharset=utf8
```

### watchdog 检测不到变化

确认使用的是 `PollingObserver` 而非 `Observer`：

```python
# 错误：inotify 无法监控网络挂载
from watchdog.observers import Observer

# 正确：轮询方式，兼容网络挂载
from watchdog.observers.polling import PollingObserver
```

### 轮询延迟太高

减小 `poll_interval`，但注意间隔越小，网络 I/O 越频繁：

```python
# 每 2 秒轮询一次（最小建议值）
PollingObserver(timeout=2)
```

---

## 六、架构总结

```
Windows 共享文件夹
       │
       │  SMB/CIFS (TCP 445)
       ▼
Linux CIFS 内核模块
       │
       │  VFS（虚拟文件系统层）
       ▼
挂载点 /mnt/windows_share
       │
       │  定时轮询（PollingObserver）
       ▼
watchdog 事件系统
       │
       ├── on_created  → 处理新文件
       ├── on_modified → 处理变更
       └── on_deleted  → 处理删除
```

整个方案的核心思路：**利用 CIFS 将网络路径透明化为本地路径，再用轮询方式绕过 inotify 对网络文件系统的限制**，从而实现跨系统的文件监控。



本教程介绍如何在 Linux 系统上，通过挂载 Windows 共享文件夹（SMB/CIFS 协议），并结合 Python 的 watchdog 库实现对共享目录的实时文件监控。

Linux 监控 Windows 共享文件夹完整教程

测试开发工程师

开发工具

本教程详细讲解Linux系统挂载Windows共享文件夹(SMB/CIFS协议)的方法，并配合Python watchdog库实现实时文件监控。涵盖环境配置、挂载步骤、监控脚本编写及常见问题排查，帮助开发者实现跨系统的文件监控解决方案。特别说明网络挂载必须使用PollingObserver轮询机制。

文件系统

Windows

Python

CentOS

Ubuntu

Linux

JSON

2026采购季 | AI焕新·智启新局

domain

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云AI代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

功能1上新10个字符

功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符。

功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符。

功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符

功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符

功能4上新

文章&问答评论现已支持表情

全新交互，全新视觉，新增快捷键、悬浮工具栏、高亮块等功能并同时优化现有功能，全面提升创作效率和体验

社区富文本编辑器全新改版！诚邀体验～ 

精选全网热门MCP server，让你的AI更好用 🚀

💥开发者 MCP广场重磅上线！

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

Linux 监控 Windows 共享文件夹完整教程-腾讯云开发者社区-腾讯云

Linux 监控 Windows 共享文件夹完整教程

Linux 监控 Windows 共享文件夹完整教程

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐