### **一、 webdav 和网盘的关系**

**WebDAV**不是又一个新的网盘服务，而是一种经典、开放且强大的技术协议

只要是存储系统，都可以使用 webdav 作为标准访问接口，让任何支持 webdav 的客户端访问存储系统。

它就像一把神奇的钥匙，能让你将家里的电脑、NAS 或任何一台服务器，变成一个完全由你掌控的、跨平台的“私人数据中心”。



### **二、 什么是 WebDAV？—— 你的私人“云”钥匙**

简单来说，WebDAV (Web-based Distributed Authoring and Versioning) 是一个诞生于上世纪的互联网标准协议。

别被它拗口的名字吓到，你可以把它想象成：

*   **一个“网络U盘”**：它让你可以像访问本地文件夹一样，通过网络直接读取、写入、修改服务器上的文件。
*   **一扇“通用大门”**：因为它是一个开放标准，无数的 App 和设备都支持它。无论是苹果、安卓还是Windows，无论是笔记软件、视频播放器还是文件管理器，都可以通过这扇门，访问你同一个数据仓库。

它的核心优势，正是我们这个时代最稀缺的东西：`数据私有`、`开放通用`、`成本低廉`。

### **三、 为什么选择 WebDAV？—— 四大核心应用场景**

WebDAV 的魅力不在于它技术有多新潮，而在于它能切实解决我们数字生活中的具体问题。

#### **场景一：多平台笔记同步的心脏 (for Obsidian, Joplin)**

对于像 Obsidian、Joplin 这样的笔记软件用户来说，WebDAV 是实现多设备同步的“平价法拉利”。你不再需要依赖昂贵的官方同步服务，只需简单配置，就能让你的知识库在手机、平板和电脑间无缝漫游，安全又私密。

#### **场景二：科研与学习的利器 (for Zotero)**

Zotero 用户的普遍痛点是免费的附件同步空间（300MB）捉襟见肘。而通过 WebDAV，你可以将 Zotero 的文献附件指向自己的服务器。这意味着你的文献库空间可以无限扩展——你的硬盘有多大，空间就有多大！

#### **场景三：私人影音库的遥控器 (for nPlayer, Infuse)**

想象一下，你家里的 NAS 或服务器上存着上百G的高清电影和剧集。有了 WebDAV，你只需在手机或平板的 nPlayer、Infuse 等播放器里添加一个地址，就能随时随地在线播放它们，无需下载，即点即看，如同拥有一个私人的 Netflix。

#### **场景四：跨平台文件访问的桥梁**

随时随地，打开手机上的文件管理器（如 Solid Explorer），就能直接访问、管理你家里电脑的文件。临时需要一份报告？打开手机就能取用。想给朋友分享一张照片？直接从服务器上就能分享，无需先下载到手机。

### **四、 如何搭建？—— Docker 部署，轻松拥有**

对于现代玩家而言，Docker 是部署服务的最佳方式，它干净、独立、迁移方便。我们将介绍两种主流的、通过 Docker 搭建 WebDAV 服务的方法：**Alist** 和 **Nextcloud**。

#### **方案一：Alist —— 轻量而强大的文件列表与 WebDAV 中心**

Alist 是一个神奇的程序，它能挂载多种网盘（阿里云盘、百度网盘等）和本地存储，并提供一个统一的、美观的列表界面，同时，它也内置了强大的 WebDAV 服务。

**操作步骤：**

1.  在家里的电脑或服务器上创建一个文件夹，例如 `alist`。
2.  在 `alist` 文件夹内，创建一个名为 `docker-compose.yml` 的文件，并粘贴以下内容：

    ```yaml
    version: '3.3'
    services:
        alist:
            image: 'xhofe/alist:latest'
            container_name: alist
            volumes:
                - './data:/opt/alist/data' # 将配置文件映射到当前目录的data文件夹
            ports:
                - '5244:5244' # 冒号左边的 5244 可以改成你喜欢的任何未被占用的端口
            restart: always
            environment:
                - PUID=0
                - PGID=0
                - UMASK=022
    ```

3.  在该目录下打开终端（或命令提示符），运行命令：`docker-compose up -d`
4.  等待片刻，Alist 就运行起来了。访问 `http://你的IP地址:5244`，后台管理页面会提示你初始管理员密码。
5.  登录后，务必先修改密码。然后在“存储” -> “添加”中，选择“本机存储”，填入挂载路径 `/opt/alist/data`（或其他你想暴露的服务器路径），即可将本地文件夹通过 Alist 管理。
6.  Alist 的 WebDAV 服务是自动开启的，地址通常是 `http://你的IP地址:5244/dav`。

#### **方案二：Nextcloud —— 功能全面的私人云套件**

Nextcloud 不仅仅是一个 WebDAV 服务，它是一整套开源的私人云解决方案，包含了文件同步、日历、联系人、在线Office等功能，堪称“自建的 Google Drive”。

**操作步骤：**

1.  同样，创建一个 `nextcloud` 文件夹，并在里面新建 `docker-compose.yml` 文件：

    ```yaml
    version: '3'
    services:
      db:
        image: postgres:latest
        restart: always
        volumes:
          - ./db:/var/lib/postgresql/data
        environment:
          - POSTGRES_DB=nextcloud
          - POSTGRES_USER=nextcloud
          - POSTGRES_PASSWORD=your_strong_password_here # 请务必修改成一个安全的密码
  
      app:
        image: nextcloud:latest
        restart: always
        ports:
          - 8080:80 # 冒号左边的 8080 可以改成你喜欢的端口
        links:
          - db
        volumes:
          - ./nextcloud:/var/www/html
        environment:
          - POSTGRES_HOST=db
          - POSTGRES_DB=nextcloud
          - POSTGRES_USER=nextcloud
          - POSTGRES_PASSWORD=your_strong_password_here # 和上面数据库的密码保持一致
    ```

2.  在该目录下运行命令：`docker-compose up -d`
3.  首次访问 `http://你的IP地址:8080`，会进入 Nextcloud 的安装向导。创建一个管理员账户，然后在数据库配置部分，选择 PostgreSQL，并填入上面 `docker-compose.yml` 文件中你设置的数据库信息（数据库用户、密码、名称都是 `nextcloud`，主机是 `db`）。
4.  安装完成后，登录你的 Nextcloud。在左下角“设置” -> “移动与桌面设备”里，你就能找到你的专属 WebDAV 地址。它通常是这样的格式：`http://你的IP地址:8080/remote.php/dav/files/你的用户名/`

**Alist vs Nextcloud 如何选？**
*   **选 Alist**：如果你只想拥有一个轻量、快速、能统一管理多种存储并提供 WebDAV 接口的工具。
*   **选 Nextcloud**：如果你需要一个功能全面的私人办公和生活协作套件，WebDAV 只是其中一项功能。

### **五、 如何使用？—— 全平台客户端配置指南**

配置 WebDAV 客户端非常简单，万变不离其宗，你只需要记住四个关键信息：

> **WebDAV 配置四要素：**
> *   **服务器地址：** `http://<你的IP或域名>:<端口号>`
> *   **路径 (Path)（如果有的话）：** 例如 Alist 是 `/dav`，Nextcloud 是 `/remote.php/dav/files/用户名/`
> *   **用户名：** 你的登录账号
> *   **密码：** 你的登录密码

以 nextcloud 为例


![image.png](https://oss.silon.vip/img/8df759399bc8ae308237d22e9d117b4e.image.webp)

![image.png](https://oss.silon.vip/img/bcdd4cadca57db1a07c90c9082474112.image.webp)


这里就是 webdav 的 地址
用户名和密码则为 nextcloud 的用户账号和密码

为了安全起见，建议为 webdav 专门注册一个 app 授权，不使用用户的默认密码



**各平台推荐应用：**

![image.png](https://oss.silon.vip/img/2266dbb93f4798a3fcd16d665b0eefdd.image.webp)


### **六、 避坑指南：使用 WebDAV 必须知道的事**

享受自由的同时，责任也随之而来。请务必牢记以下几点：

1.  **安全第一：公网访问必须使用 HTTPS！**
    如果你打算在外网访问你的 WebDAV，直接使用 HTTP 等于在互联网上“裸奔”，账号密码和数据都可能被窃取。请务必使用 Nginx Proxy Manager 或 Caddy 等反向代理工具，为你的服务套上一个免费的 SSL 证书，实现 HTTPS 加密访问。

2.  **性能认知：它并非万能**
    WebDAV 非常适合看电影、同步笔记附件等大文件和低频次操作。但它不适合同步大量、细碎的文件（如代码项目），这种场景下，专业的同步工具 Syncthing 会是更好的选择。

3.  **数据备份：自建不等于高枕无忧**
    切记：**WebDAV 是访问方式，不是备份方案！** 你的服务器硬盘可能会损坏。请务必为你的重要数据建立独立的备份策略，例如使用 NAS 的 RAID，或定期将数据备份到另一块硬盘或云端。

webdav搭建及基本使用

gunicorn 使用及常见工程化配置

在团队开发中，pre-commit 是非常常用的代码质量保障工具。但不少 Windows 用户在使用 pre-commit 时，会遇到 `ExecutableNotFoundError: Executable /bin/sh not found` 的报错。本文将详细分析原因，并给出完整的解决方案。




## 1. 问题现象

在 Windows 下执行 `git commit` 时，出现如下报错：

```
An unexpected error has occurred: ExecutableNotFoundError: Executable `/bin/sh` not found
Check the log at C:\Users\用户名\.cache\pre-commit\pre-commit.log
```

pre-commit.log 里会有类似堆栈：

```
pre_commit.parse_shebang.ExecutableNotFoundError: Executable `/bin/sh` not found
```

## 2. 问题原因分析

### 2.1 pre-commit hook 兼容模式

pre-commit 在安装时，如果检测到 `.git/hooks/pre-commit.legacy` 文件，会进入兼容模式（migration mode），优先执行 legacy hook。很多老的 hook 脚本是 shell 脚本，shebang 为 `/bin/sh`，而 Windows 没有这个解释器，导致报错。

### 2.2 配置 language: system

如果 pre-commit hook 配置为 `language: system`，pre-commit 可能会尝试用 shell 执行 entry，也会导致依赖 `/bin/sh`。

### 2.3 entry 配置不当

如果 entry 只写了命令名（如 `pylint`），部分 pre-commit 版本会用 shell 执行，间接依赖 `/bin/sh`。

## 3. 解决方案

### 3.1 删除 legacy hook

进入项目的 `.git/hooks` 目录，删除 `pre-commit.legacy` 文件：

```powershell
Remove-Item .git\hooks\pre-commit.legacy
```

### 3.2 强制重新安装 pre-commit hook

```powershell
pre-commit install -f
```

这样只会用 pre-commit 的 hook，不再兼容老的 shell 脚本。

### 3.3 修改 .pre-commit-config.yaml 配置

推荐将 `language` 设置为 `python`，并将 `entry` 改为 `python -m pylint`，如下：

```yaml
- repo: local
  hooks:
    - id: pylint
      name: pylint
      entry: python -m pylint
      language: python
      types: [python]
      args: [
          "--rcfile=pyproject.toml",
          "-rn", # Only display messages
          "-sn", # Don't display the score
        ]
```

这样 pre-commit 会直接用 Python 解释器运行，不再依赖 shell。

### 3.4 检查其他 hook

如果还有其他 hook（如 trailing-whitespace、end-of-file-fixer 等），请确认它们是否需要 shell 环境。大部分 Python 相关的 hook 都能在 Windows 下正常运行。

### 3.5 升级 pre-commit

确保 pre-commit 版本为 4.x 及以上：

```powershell
pip install -U pre-commit
```

### 3.6 清理 pre-commit 缓存

```powershell
pre-commit clean
```


## 4. 总结

Windows 下 pre-commit 报 `/bin/sh not found`，99% 是 legacy hook 或配置问题。只要：

- 删除 legacy hook
- 配置 language: python，entry: python -m xxx
- 强制安装 pre-commit hook

即可彻底解决。

Windows 下 pre-commit 报 `/bin/sh not found` 问题全解析与解决方案

Python代码标准化

# pylint 介绍

Pylint 是一个用于 Python的静态代码分析器。它会检查错误、强制执行编码标准、寻找代码异味，并可以就如何重构代码提出建议。





## python代码检查配合

 pylint 一起使用的项目包括
 
- ruff（非常快速，内置自动修复功能，并从流行的 linter 中提取大量检查，但实现方式为 rust ）
- flake8（一个使用 ast 直接实现你自己的检查的框架）
- mypy
- pyright / pylance 或 pyre（类型检查）
- bandit（安全导向的检查）
- black 和 isort（自动格式化）
- autoflake（自动移除未使用的导入或变量）
- pyupgrade（自动升级到更新的 Python 语法）
- pydocstringformatter（自动 pep257 格式化）

## 版本说明

开发环境中应该使用指定的pylint版本，保证效果统一

- 在主要版本发布（ 1.0.0 ）中，会改变其他所有内容（pylint 选项、json 输出、开发 API 等），同时仍然尽量减少干扰。
- 在次要版本（ 1.2.0 ）中，添加检查、移除检查、移除已结束生命周期的 Python 解释器、升级 astroid 的次要/主要版本，并修复误报。
- 在补丁版本（ 1.2.3 ）中，仅修复误报和崩溃。

## 在markdown中使用pylint 徽章

效果如下

[![linting: pylint](https://img.shields.io/badge/linting-pylint-yellowgreen)](https://github.com/pylint-dev/pylint)


在任何 Markdown 文件中添加该行即可
```
[![linting: pylint](https://img.shields.io/badge/linting-pylint-yellowgreen)](https://github.com/pylint-dev/pylint)

```


# pylint 安装与配置

## pylint 安装

Pylint 可以通过包管理器进行安装

```
pip install pylint
```

如果需要使用pylint提供的拼写检查需要额外安装

```
pip install pylint[spelling]
```


## pylint的使用

```
pylint 需要检查的文件夹或文件路径
```


![image.png](https://oss.silon.vip/img/b838aa2dbeaa6c736a2356817c5d3c11.image.webp)

## pylint 配置

### 生成配置文件

Pylint 支持多种配置文件格式

- .pylintrc（RC 文件）
    - .pylintrc 文件通常是独立存在的，专门用于 Pylint 的配置
    - 项目已经使用 .pylintrc 并且配置较为简单，建议使用
- TOML 的配置（通常集成在 pyproject.toml 中）
    - Python 工具配置的标准（如 Poetry、Black 等）一般都写在该文件中
    - 希望将所有工具的配置集中管理，且项目配置较为复杂，建议使用

可以使用 --generate-toml-config 或 --generate-rcfile 生成一个示例配置文件。

```
# 生成 rc 文件在当前目录
pylint --generate-rcfile > .pylintrc

# 生成 toml 文件在当前目录
pylint --generate-toml-config > pyproject.toml
```

创建时可以预设一些选项
```
pylint --disable=bare-except,invalid-name --class-rgx='[A-Z][a-z]+' --generate-toml-config
```



### 各部分常用配置说明及参考


#### 基本配置

```
[tool.pylint.main]
# 启用持久化缓存
persistent = true

# 根据机器的CPU核心数设置, 0 为自动检查核心数
jobs = 0 

# 用于版本依赖性检查的最低 python 版本
py-version = "3.11"
```

#### 命名规范

```
[tool.pylint.basic]
# 命名风格
variable-naming-style = "snake_case"
function-naming-style = "snake_case"
class-naming-style = "PascalCase"
const-naming-style = "UPPER_CASE"

# 禁止使用的变量名
bad-names = ["a", "tmp", "temp", "test"]

# 允许的好变量名
good-names = ["i", "j", "k", "ex", "Run", "_"]

# 函数、方法至少多少行需要写docling注释，-1为必写，0为不写
docstring-min-length = 5

# 允许在名称中使用的正则表达式（覆盖命名风格）
# 比如允许变量名以“_”开头
variable-rgx = "^_?[a-z][a-z0-9_]{2,29}$"
```

#### 代码复杂度的限制

```
[tool.pylint.design]

# 哪些class不计入父类数量计算
ignored-parents = "object,abc.ABC"

# 最大函数参数数
max-args = 5

# class字段数量上限，Model/Serializer/Forms 可能有较多字段
max-attributes = 15

# if 语句中的布尔表达式数量
max-bool-expr = 5

# 函数/方法中的分支数量
max-branches = 10

# 局部变量数量
max-locals = 15

# class多重继承数量
max-parents = 5

# 与 max-args 同步
max-positional-arguments = 5

# public方法数量
max-public-methods = 20

# return 数量限制
max-returns = 6

# 一个函数最大行数
max-statements = 60

# class 至少应该有几个public方法
min-public-methods = 1
```

#### 代码格式

```
# 预期的行尾格式，可根据团队环境选择。对于跨平台开发，推荐使用 LF。
expected-line-ending-format = "LF"

# 允许行长度超过限制的正则表达式
ignore-long-lines = "^\\s*(# )?<?https?://\\S+>?$"

# 括号内要求的缩进空格数
indent-after-paren = 4

# 缩进使用的字符串，推荐使用4个空格
indent-string = "    "

# 单行最大字符数
max-line-length = 120

# 模块的最大行数
max-module-lines = 1000

# 允许类体只有单一语句时与声明在同一行
# class Configuration: setting = True
single-line-class-stmt = false

# 允许if体只有单一语句且无else时与测试条件在同一行
# if is_active: status = "Active"
single-line-if-stmt = flase
```

#### import 检查

```
[tool.pylint.imports]
# 允许在任何级别导入的模块列表，一般放内置和第三方库
allow-any-import-level = ["os", "sys", "django"]

# 分类明确标准库
known-standard-library = [
    "os",
    "sys",
    "math",
    "json",
    "logging",
]

# 分类明确第三方库
known-third-party = [
    "django",
    "rest_framework",
    "enchant",
    "requests",
]
```

#### pylint检查警告配置

``` 
[tool.pylint."messages control"]

# 仅显示以下置信度级别的警告
confidence = [
  "HIGH",
  "CONTROL_FLOW",
  "INFERENCE",
  "INFERENCE_FAILURE",
  "UNDEFINED",
]

# 禁用不相关或不必要的消息
disable = [
  "raw-checker-failed",
  "bad-inline-option",
  "locally-disabled",
  "file-ignored",
  "suppressed-message",
  "useless-suppression",
  "deprecated-pragma",
  "use-symbolic-message-instead",
  "use-implicit-booleaness-not-comparison-to-string",
  "use-implicit-booleaness-not-comparison-to-zero",
  "C0103",  # 变量命名长度过短或过长（根据需要调整）
  "W0511",  # TODO和FIXME注释（根据团队规范决定是否禁用）
]
```

#### 注释检查

常见的注释标签在检查范围内可帮助团队及时发现和处理潜在问题
```
[tool.pylint.miscellaneous]

# 要考虑的注释标签列表
notes = ["FIXME", "XXX", "TODO"]

# 注释标签的正则表达式
notes-rgx = "^(FIXME|XXX|TODO)\b"
```

#### 代码重构提示

```
[tool.pylint.refactoring]

# 函数/方法体中嵌套块的最大数量
max-nested-blocks = 5

# 永不返回的函数的完整名称
never-returning-functions = ["sys.exit", "argparse.parse_error"]

# 使用非空分隔符连接字符串列表时，Pylint会建议使用str.join方法
suggest-join-with-non-empty-separator = true
```

#### pylint 检查报告

```
[tool.pylint.reports]

# 全局评估报告的评价公式
evaluation = "max(0, 0 if fatal else 10.0 - ((float(5 * error + warning + refactor + convention) / statement) * 10))"

# 消息模板
msg-template = "{path}:{line}: [{msg_id}({symbol}), {obj}] {msg}"

# 输出格式，用颜色区分不同类型的消息，提升可读性
output-format = "colorized"

# 是否显示完整报告
reports = false

# 启用评估分数
score = true

```


#### 代码相似度计算

一般不进行修改

```
[tool.pylint.similarities]

# 在相似度计算中忽略注释
ignore-comments = true

# 在相似度计算中忽略文档字符串
ignore-docstrings = true

# 在相似度计算中忽略导入语句
ignore-imports = true

# 在相似度计算中忽略函数签名
ignore-signatures = true

# 相似度的最小行数
min-similarity-lines = 4
```


#### 拼写检查

该功能需要安装pylint 的spell检查包

```
[tool.pylint.spelling]

# 限制拼写错误建议的数量
max-spelling-suggestions = 4

# 拼写词典名称（保持为空，使用默认词典）
spelling-dict = ""

# 忽略拼写检查的注释指令
spelling-ignore-comment-directives = "fmt: on,fmt: off,noqa:,noqa,nosec,isort:skip,mypy:"

# 不进行拼写检查的单词列表（根据项目需求添加）
spelling-ignore-words = "POST,GET,PUT,PATCH,DELETE,URL,HTTP"

# 私有词典文件路径（如有需要）
spelling-private-dict-file = ""

# 将未知单词存储到私有词典
spelling-store-unknown-words = false
```

#### 类型检查

```
[tool.pylint.typecheck]

# 上下文管理器装饰器列表
contextmanager-decorators = ["contextlib.contextmanager"]

# 动态设置的成员列表（根据项目需要添加）
generated-members = ["objects", "manager", "verbose_name"]

# 忽略mixin类中缺失的成员
ignore-none = true

# 对不透明推断的对象忽略成员检查
ignore-on-opaque-inference = true

# 忽略mixin成员的检查
ignored-checks-for-mixins = [
  "no-member",
  "not-async-context-manager",
  "not-context-manager",
  "attribute-defined-outside-init",
]

# 忽略成员检查的类名
ignored-classes = [
  "optparse.Values",
  "thread._local",
  "_thread._local",
  "argparse.Namespace",
]

# 缺失成员时显示提示
missing-member-hint = true

# 缺失成员提示的最小编辑距离
missing-member-hint-distance = 1

# 缺失成员提示的最大选项数
missing-member-max-choices = 1

# 定义mixin类的正则模式
mixin-class-rgx = ".*[Mm]ixin"

# 改变被装饰函数签名的装饰器列表（根据项目需要添加）
signature-mutators = ["functools.wraps"]
```

#### 变量使用

```
[tool.pylint.variables]
# 允许的全局未使用变量
allow-global-unused-variables = true

# 允许覆盖内置名称的变量列表
allowed-redefined-builtins = ["len", "id"]

# 允许作为回调函数标识的名称前缀或后缀
callbacks = ["cb_", "_cb"]

# 匹配虚拟变量名称的正则表达式
dummy-variables-rgx = "_+$|(_[a-zA-Z0-9_]*[a-zA-Z0-9]+?$)|dummy|^ignored_|^unused_"

# 忽略的参数名称正则表达式
ignored-argument-names = "_.*|^ignored_|^unused_"

# 允许重新定义内置函数的模块列表
redefining-builtins-modules = [
  "six.moves",
  "past.builtins",
  "future.builtins",
  "builtins",
  "io",
]
```


# 开发环境配置

## 编辑器集成

https://pylint.readthedocs.io/en/latest/user_guide/installation/ide_integration/index.html

## 代码pre-commit 检查

https://pylint.readthedocs.io/en/latest/user_guide/installation/pre-commit-integration.html

一、 webdav 和网盘的关系

Gunicorn 使用及常见工程化配置

1. 什么是 Gunicorn？

Python 代码标准化工程实践

pylint 介绍