为什么需要一个轻量化网盘​

常见的文件共享需求其实很朴素：

• 手机想访问电脑上的某个文件
• 局域网内给同事传个大文件
• 在外面想远程访问家里的资料
• 给备份工具（Rclone、Restic）提供一个 WebDAV 目标

如果你用过 Nextcloud 或 ownCloud，大概会感受到：为了实现这些简单的需求，你得维护一套 LAMP/LEMP 环境、一个数据库、定期的安全更新——这还没算上 PHP 带来的性能开销。对于个人或小团队来说，这套方案过于沉重。

另一方面，python3 -m http.server 倒是轻量，但只能下载、不能上传，更别提搜索和权限控制了。

dufs 刚好填补了这个空白：一个 Rust 编写的单二进制文件服务器，同时提供 Web UI 和 WebDAV 协议，支持上传、搜索、权限控制，甚至可以用 curl 完成所有操作。

dufs 是什么​

dufs 是一个用 Rust 编写的轻量级文件服务器，核心特性：

一个二进制、零依赖、默认端口 5000，dufs 一条命令即可启动。

WebDAV：被低估的协议​

WebDAV（Web Distributed Authoring and Versioning）是 HTTP 的扩展协议，在标准 HTTP 方法（GET、PUT、DELETE）基础上增加了 PROPFIND、MKCOL、COPY、MOVE 等方法，使得客户端可以像操作本地文件系统一样操作远程文件。

为什么 WebDAV 重要​

1. 系统级挂载：Windows、macOS、Linux 原生支持将 WebDAV 映射为网络驱动器，文件管理器直接访问
2. 应用生态丰富：大量笔记软件（Joplin）、备份工具（Rclone、Restic、Duplicati）、同步工具原生支持 WebDAV
3. 跨平台：不依赖特定客户端，任何支持 WebDAV 的软件都能对接
4. HTTP 基础：走标准 HTTP/HTTPS 端口，穿透防火墙和代理天然友好

各平台 WebDAV 客户端​

💡 Windows 原生 WebDAV 的坑：默认 50MB 文件大小限制需要改注册表（FileSizeLimitInBytes），且使用 HTTPS 时证书验证较严格。推荐用 RaiDrive 替代。

权限控制与鉴权​

dufs 的权限模型设计得简洁但够用，核心是 账号 + 路径 + 权限 三元组：

鉴权方式​

dufs 同时支持 Basic Auth 和 Digest Auth，默认使用 Digest Auth（更安全，密码不在网络中明文传输）。

# Digest Auth（默认）
curl --user admin:pass123 --digest http://your-server:5000/

# Basic Auth
curl --user admin:pass123 http://your-server:5000/

权限规则格式​

-a "用户名:密码@/路径:权限"

• :rw 表示读写权限，不加则只读
• @/ 前面不写用户名密码表示匿名用户
• 多条规则用 | 分隔

实际场景示例​

# 管理员：完全读写权限
-a "admin:secretpass@/:rw"

# 普通用户：只能读写 /share 目录
-a "user:userpass@/share:rw"

# 匿名用户：只读访问 /public 目录
-a "@/public"

# 组合：管理员全权 + 匿名只读
-a "admin:secretpass@/:rw|@/"

重要细节​

账号权限受全局权限约束。如果 dufs 启动时没有开启 --allow-upload，即使账号被授予 :rw 权限，也无法上传。这意味着你可以用全局开关做硬性限制，用账号权限做细粒度控制。

dufs 还支持 哈希密码，避免在命令行或配置文件中暴露明文密码，对生产环境更友好。

和其他方案对比​

选择建议：

• 需要团队协作、日历、联系人 → Nextcloud
• 只需要 Web 文件管理界面 → Filebrowser（本站也有部署教程）
• 需要轻量 + WebDAV + 文件管理 → dufs
• 纯内网共享、不需要外网访问 → Samba

我的用法​

我的典型使用场景：

1. 网盘替代：浏览器访问 dufs 的 Web UI 上传下载文件，手机和电脑通用
2. WebDAV 挂载：Windows 上用 RaiDrive 把 dufs 挂载为本地磁盘，像操作本地文件一样操作远程文件
3. 备份目标：Rclone 定期备份重要数据到 dufs 的 WebDAV 端口
4. 临时共享：需要给同事传文件时，丢到 dufs 的共享目录，给个链接即可

具体部署方式见教程：Dufs 部署

总结​

dufs 用最简单的方式覆盖了个人网盘的核心需求：文件管理 + WebDAV + 权限控制。对于不需要 Nextcloud 那种全家桶功能的用户来说，dufs 是一个非常优雅的选择——Rust 带来的低资源占用和单二进制部署，让维护成本几乎为零。

如果你的需求更复杂（多人协作、在线编辑、插件生态），Nextcloud 依然是更好的选择。但对于「我就是想简单存取文件、挂个网盘、做个备份目标」这个场景，dufs 值得一试。

架构背景​

我目前的开发环境是这样的：Jenkins 跑在本地内网机器上，而 Nginx 站点部署在云服务器上。这会带来一个核心矛盾——GitHub Webhook 无法直接回调内网的 Jenkins。

解决方案是 FRP 内网穿透：在云服务器部署 FRP 服务端，本地部署 FRP 客户端，将 Jenkins 端口映射到云服务器公网端口。而 Jenkins 构建完成后，主动 SSH 连接云服务器上传文件——这是出站连接，不受 NAT 限制，不需要 FRP 参与。

开发者 push → GitHub Webhook → 云服务器:31000 (FRP穿透) → 本地 Jenkins 触发
→ 拉代码 → pnpm install → pnpm run build → SSH直连云服务器上传 build/ → nginx reload → 站点更新

FRP 内网穿透的完整配置不是本文重点，请先参考 FRP 内网穿透教程 完成搭建。

前提条件​

Jenkins 的 Docker 部署请参考 Docker 安装 Jenkins

SSH 免密配置请参考 Jenkins SSH 密钥配置。

第一步：Jenkins 插件准备​

Jenkins 初始化时，直接选择 安装社区推荐插件（Install suggested plugins） 即可。这会自动装好 Pipeline、Git、Credentials Binding 等核心插件。

之后额外手动安装两个插件：

进入 Manage Jenkins → Plugins → Available plugins，依次搜索安装即可。

第二步：配置 Node.js 全局工具​

安装 NodeJS 插件后，需要在全局工具配置中添加 Node.js：

1. 进入 Manage Jenkins → Global Tool Configuration（旧版为 Manage Jenkins → Global Tool Configuration）
2. 滚动到 NodeJS installations 区域，点击 Add NodeJS
3. 填写配置：

4. 点击 Save

原理：首次构建时，插件会自动从 nodejs.org 下载对应版本的 Node.js 到 $JENKINS_HOME/tools/ 下，后续构建直接复用，无需在容器里手动安装。容器重建后只要挂载了 /var/jenkins_home，已下载的 Node.js 也不会丢失。

注意：NodeJS 插件下载的是 glibc 编译的二进制文件。本文使用的 jenkins/jenkins:lts-jdk21 基于 Debian（glibc），可以正常运行。不要使用 Alpine 镜像，否则会因为 musl libc 不兼容导致 node: not found。

为什么用 pnpm 而不是 npm ci​

本项目最初使用 npm ci 安装依赖，在 Jenkins 中遇到了 Exit handler never called! 报错。这是 npm 内部 agent-base 的一个已知 bug（npm/cli#9386）：当依赖数超过并发连接上限（默认 15）且网络出现超时时，请求会永久卡住。

改用 pnpm 后，得益于其全局 store + 硬链接机制，首次构建后几乎不需要网络请求，从根本上绕开了这个问题。同时构建速度也有显著提升：

npm ci（首次）：    从 registry 下载所有包 → 全量写入 node_modules
pnpm install（首次）：从 registry 下载到全局 store → 硬链接到 node_modules
pnpm install（后续）：直接从 store 硬链接到 node_modules（几乎零网络请求）

pnpm 全局 store 位于 ~/.local/share/pnpm/store（容器内即 /var/jenkins_home/.local/share/pnpm/store），由于已挂载 -v /opt/jenkins/data:/var/jenkins_home，store 会随容器持久化，重建容器也不会丢失。

第三步：配置 SSH 服务器​

进入 Manage Jenkins → System，找到 SSH Servers 区域：

Name:             cloud-server
Hostname:         你的云服务器公网 IP
Username:         deploy
Remote Directory: /

⚠️ Remote Directory 是根目录，不是家目录！

Publish Over SSH 插件中，remoteDirectory（Jenkinsfile 里的）始终拼接在 SSH Server 配置的 Remote Directory 之后，即使以 / 开头也是如此。也就是说，最终远程路径 = SSH Server Remote Directory + remoteDirectory。

举例：如果 SSH Server 的 Remote Directory 设为 /home/deploy，Jenkinsfile 里 remoteDirectory: '/var/www/cludix-doc'，实际文件会传到 /home/deploy/var/www/cludix-doc——这不是我们想要的。

正确做法：将 SSH Server 的 Remote Directory 设为 /，让 Jenkinsfile 中的 remoteDirectory 使用绝对路径 /var/www/cludix-doc，这样拼接后才是正确的部署路径。

点击 Advanced 配置认证（密钥认证推荐），点击 Test Configuration 确认连通。

第四步：配置 Git 凭据​

进入 Manage Jenkins → Credentials → System → Global credentials：

第五步：配置 GitHub Webhook​

因为 FRP 已将 Jenkins 映射到云服务器端口，GitHub 可以回调到：

http://你的云服务器IP:31000/github-webhook/

GitHub 仓库 → Settings → Webhooks → Add webhook：

Payload URL:  http://你的云服务器IP:31000/github-webhook/
Content type: application/json
Events:       Just the push event

Jenkins Pipeline 任务中勾选 Build Triggers → GitHub hook trigger for GITScm polling。

第六步：创建 Pipeline 任务​

1. New Item → 输入名称 → 选择 Pipeline → OK
2. 勾选 This project is parameterized（可选，方便切换分支）：

参数名: BRANCH
类型: String Parameter
默认值: main

3. Pipeline 区域，Definition 选择 Pipeline script，粘贴以下内容。

Jenkinsfile 完整内容​

pipeline {
    agent any

    // 使用 NodeJS Plugin 管理的 Node.js 环境
    // 名称必须与 Global Tool Configuration 中配置的一致
    tools {
        nodejs 'NodeJS-20'
    }

    environment {
        // ===== Git 配置 =====
        GIT_REPO    = 'https://github.com/yunqilee69/cludix-doc.git'
        GIT_CRED    = 'git-credentials'

        // ===== SSH 部署配置（云服务器） =====
        SSH_SERVER  = 'cloud-server'
        REMOTE_DIR  = '/var/www/cludix-doc'

        // ===== 构建产物目录（Docusaurus 输出到 build/） =====
        BUILD_DIR   = 'build'
    }

    stages {

        // ==================== 阶段1：拉取代码 ====================
        stage('Checkout') {
            steps {
                echo '📌 拉取代码...'
                git branch: "${params.BRANCH ?: 'main'}",
                    credentialsId: "${GIT_CRED}",
                    url: "${GIT_REPO}"
            }
        }

        // ==================== 阶段2：安装依赖 ====================
        stage('Install Dependencies') {
            steps {
                echo '📦 安装依赖（pnpm + 淘宝镜像）...'
                sh '''
                    pnpm config set registry https://registry.npmmirror.com
                    pnpm install --frozen-lockfile
                '''
            }
        }

        // ==================== 阶段3：构建 ====================
        stage('Build') {
            steps {
                echo '🔨 构建 Docusaurus 项目...'
                sh 'pnpm run build'
            }
            post {
                success {
                    echo '✅ 构建成功，build 目录已生成'
                    sh 'ls -lh build/ | head -10'
                }
            }
        }

        // ==================== 阶段4：部署到云服务器 ====================
        stage('Deploy to Cloud') {
            steps {
                echo '🚀 通过 SSH 部署到云服务器...'

                sshPublisher(
                    continueOnError: false,
                    failOnError: true,
                    publishers: [
                        sshPublisherDesc(
                            configName: "${SSH_SERVER}",
                            verbose: true,
                            transfers: [
                                sshTransfer(
                                    // Docusaurus 构建产物在 build/ 目录
                                    sourceFiles: 'build/**/*',
                                    // 去掉 build 前缀，避免远程出现 build/build/ 嵌套
                                    removePrefix: 'build',
                                    remoteDirectory: "${REMOTE_DIR}",
                                    execCommand: """
                                        echo '📁 文件传输完成'

                                        # 备份当前版本
                                        BACKUP_DIR="/var/www/backups/\$(date +%Y%m%d_%H%M%S)"
                                        sudo mkdir -p \${BACKUP_DIR}
                                        sudo cp -r ${REMOTE_DIR}/* \${BACKUP_DIR}/ 2>/dev/null || true
                                        echo "📦 已备份至 \${BACKUP_DIR}"

                                        # 修正文件权限
                                        sudo chown -R www-data:www-data ${REMOTE_DIR}
                                        sudo chmod -R 755 ${REMOTE_DIR}

                                        # 检测 Nginx 配置并重载
                                        echo '🔄 重载 Nginx...'
                                        sudo nginx -t && sudo systemctl reload nginx

                                        echo '✅ 部署完成！'
                                    """
                                )
                            ]
                        )
                    ]
                )
            }
        }
    }

    post {
        success {
            echo '🎉 流水线执行成功！站点已更新。'
        }
        failure {
            echo '❌ 流水线执行失败，请检查日志'
        }
        always {
            echo '🧹 流水线结束'
        }
    }
}

云服务器 Nginx 配置​

云服务器 /etc/nginx/conf.d/cludix-doc.conf：

server {
    listen       80;
    server_name  your-domain.com;

    root /var/www/cludix-doc;
    index index.html;

    # SPA 路由支持（Docusaurus 需要）
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 静态资源缓存
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff2?)$ {
        expires 30d;
        add_header Cache-Control "public, immutable";
    }

    # 禁止访问隐藏文件
    location ~ /\. {
        deny all;
    }
}

云服务器 sudo 免密配置：

sudo visudo

# 添加
deploy ALL=(ALL) NOPASSWD: /usr/sbin/nginx -t, /usr/bin/systemctl reload nginx, /bin/mkdir, /bin/cp, /usr/bin/chown, /bin/chmod

端到端验证​

# 1. FRP 连通性
curl http://你的云服务器IP:31000    # 返回 Jenkins 页面

# 2. SSH 连通性
ssh deploy@你的云服务器IP "echo ok"

# 3. Webhook 连通性（GitHub 仓库 Settings → Webhooks）
# 最近一次 Delivery 状态码 200

# 4. 手动触发构建（Jenkins → Build Now）
# 全阶段绿灯 ✅

# 5. 验证站点
curl -I http://your-domain.com   # 200 OK

完整链路：

git push → GitHub Webhook → 云服务器:31000 (FRP穿透) → 本地 Jenkins
→ Checkout → pnpm install → pnpm run build
→ SSH 上传 build/ 到云服务器 → nginx -t → systemctl reload nginx
→ 站点更新 ✅

常见问题​

小结​

整条链路涉及四个核心环节：FRP 穿透解决入站、Jenkins 流水线解决构建、SSH 传输解决部署、Nginx reload 解决生效。每一环都有独立的原子文档可以深入，本文将它们串联成一个完整的专题。

Blog 和文档的区别​

Blog：围绕专题解决一类问题​

Blog 更适合记录“范围性问题”。它不一定只回答一个命令怎么写，而是把一个主题里的背景、约束、尝试、取舍和结论串起来。

比如当前这类“自动化部署链路搭建”内容，就不仅是 Jenkins 的某个配置项，而是会同时涉及：

1. 代码仓库触发 Jenkins 任务。
2. Jenkins 拉取代码并执行构建脚本。
3. 构建环境通过代理访问外部依赖源。
4. 构建产物打包成 Docker 镜像。
5. 镜像推送到 Docker 仓库。
6. 目标服务器拉取镜像并重启服务。

这些内容放在 Blog 里更自然，因为读者通常需要先理解“整条链路怎么协作”，再定位自己要落地或排查的环节。

Blog 还适合记录：

• 一个专题的完整配置过程，例如 Jenkins 的一系列配置和使用。
• 一个 bug 的发现、定位、尝试和最终解决过程。
• 某个方案为什么这样设计，以及中间放弃过哪些做法。
• 多个工具组合使用时的上下文，例如 Jenkins、Docker、代理、仓库和服务器部署之间的关系。

文档：回答一个原子问题​

文档区更适合放“原子化答案”。每一篇文档尽量只说明一个具体、清晰、边界明确的事情，读者可以直接搜索、打开、照做或引用。

例如：

• Docker 如何安装。
• 如何用 Docker 部署 MySQL。
• 某个 Java 报错的原因和处理方式。
• 某个 Nebula 模块的配置项、接口、DDL 或使用说明。

如果一篇内容可以被命名成“如何做某一件具体的事”，并且不依赖很长的前因后果，它通常更适合放在文档区。

当前文档站是怎么设计的​

这个站点的阅读入口按内容类型拆开：

• 专题：对应 Blog，用来阅读跨多个工具、配置和系统的大型问题处理过程。
• 教程：按 Linux、Windows、macOS、Docker、Kubernetes、CI/CD、Java、数据库、网络等场景组织，适合找“怎么做”。
• 踩坑：同样按技术场景分类，适合找“为什么出错、怎么修”。
• Nebula：按模块组织框架能力，每个模块下再拆成概览、业务能力、配置、DDL、接口、设计实现和使用指南。
• 搜索：站点会索引文档、Blog 和页面，适合在不知道分类时直接检索关键字。

文档区的侧边栏采用自动生成方式：新增内容时，优先把文档放进对应目录；目录页使用 index.md；分类元数据通过 _category_.json 维护名称、顺序和可点击入口。这样可以让目录结构、页面 URL 和侧边栏尽量保持稳定。

推荐阅读方式​

先判断自己在找什么​

如果你想了解一个专题的完整背景，先看 Blog。例如自动化部署相关内容，就应该先从专题文章理解 Jenkins、脚本、代理、Docker 仓库和服务器部署之间的关系。

如果你只想完成一个明确动作，直接去文档区。例如“Docker 安装”“Docker 部署 MySQL”“某个报错怎么修”这类问题，不需要先读一篇长文。

再选择入口​

• 找操作步骤：优先看 教程。
• 找故障处理：优先看 踩坑。
• 找框架模块说明：优先看 Nebula。
• 找完整方案、排查过程、设计思路：优先看 专题。
• 不确定放在哪里：直接用搜索。

最后回到原子文档落地​

Blog 通常负责把问题讲完整，但真正落地时，仍然应该回到原子文档确认具体命令、配置项和注意事项。也就是说：

1. 用 Blog 建立上下文。
2. 用文档执行具体步骤。
3. 遇到报错时到踩坑区检索。
4. 如果问题跨多个环节，再回到 Blog 看完整链路。

后续内容应该怎么写​

后续新增内容时，可以按下面的规则判断放在哪里：

• 放 Blog：一个专题、一条链路、一次完整排查、一个 bug 的解决过程、一个方案的思考过程。
• 放文档：一个明确动作、一个清晰配置、一个具体命令、一个可独立复用的问题答案。

例如 Jenkins 的一系列配置和使用，可以作为 Blog 记录完整部署链路；而“Docker 安装”“Docker 部署 MySQL”这类内容，则应该拆成独立文档，方便搜索和复用。

这样的分工可以让 Blog 保留真实的问题现场，也让文档区保持短、准、可检索。