WsgiDAV 配置参数详解

目标：系统梳理 WsgiDAV 4.3.5 配置文件（YAML 为主，也支持 JSON）的关键参数，帮助读者理解 provider、域控制、认证、目录浏览、锁/属性管理器与日志配置，正确搭建生产 WebDAV 服务。

WsgiDAV 配置可通过 -c 显式指定，默认读取当前目录下的 wsgidav.yaml / wsgidav.json。配置文件遵循 PEP8 风格，多数键可省略（用默认值）。以下按功能模块分节说明。

1. 顶层：host / port

host: 0.0.0.0          # 绑定地址，默认 localhost（仅本机）
port: 8080             # 监听端口，默认 8080

键	默认值	说明
`host`	`localhost`	绑定地址；`0.0.0.0` 对外
`port`	`8080`	监听端口

2. 共享目录：provider_mapping

定义路由到 DAV provider 的映射。最常用是文件系统 provider（fs）：

provider_mapping:
  "/":
    root: /data/share

目录列表：

DIR_ROOT_DIRECTORY = "root"
DIR_PROP_PROVIDER = "prop_manager"
DIR_LOCK_PROVIDER = "lock_storage"

其他内置 provider：

# 1) 文件系统 provider（最常用）
provider_mapping:
  "/": { root: /data/share }

# 2) 临时目录 provider
provider_mapping:
  "/tmp": { provider: tmp, persist: false }

# 3) 内存 provider
provider_mapping:
  "/mem": { provider: memory }

# 4) 多目录 / 每用户子目录
provider_mapping:
  "/":
    root: /data
    # 下面是属性/锁存储（可选）
    prop_manager: true
    lock_storage: true

provider 类型：fs（默认，文件系统）、tmp（临时目录）、memory（内存）。root 指定共享根目录绝对路径。prop_manager/lock_storage 可指向对应存储配置。

复合示例（多目录）:

provider_mapping:
  "/":
    root: /data
  "/public":
    provider: fs
    root: /srv/public

<realm> 即 provider 的挂载路径（如上 /、/public），同时用作认证 realm 标识。

3. 认证：SimpleDomainController（simple_dc）

simple_dc 是默认域控制器，用配置里的 user_mapping 校验用户，使用 realm 作为隔离单元：

simple_dc:
  user_mapping:
    "<realm>":
      "<用户名>": { password: "...", roles: ["..."] }

完整示例：

simple_dc:
  user_mapping:
    "*":                       # '*' 为通用默认（未单独列出的 realm 生效）
      john:
        password: john123
    "/":                       # 精确匹配 realm '/'
      admin:
        password: admin123
        roles: ["admin"]
      bob:
        password: bob123

realm 与 user_mapping 键必须对齐：WsgiDAV 计算 realm 后，去 user_mapping 里找对应键（"/"）或默认键（"*"）。写错会报： Missing configuration simple_dc.user_mapping["/"] (or "*"): realm is not accessible!

* 键为"兜底"定义，给未精确列出的 realm 提供默认用户集。

关键点：

密码为字面明文。WsgiDAV 的 simple_dc 不解析 {PLAIN} 之类前缀，直接按字符串比较。需更安全的散列策略可换用自定义 DomainController。
roles：用户角色列表，可被 HTTPAuthenticator / 权限检查使用。示例如 ["admin"]。

user_mapping 的某个 realm 置 True 表示允许匿名访问：

simple_dc:
  user_mapping:
    "*": True        # 所有 realm 匿名可访问（不推荐生产）

4. HTTP 认证：http_authenticator

可调整 Basic/Digest 认证行为（使用默认时多数键可省略）：

http_authenticator:
  domain_controller: null      # 默认按 simple_dc/unknown_dc 推断
  accept_basic: true           # 接受 Basic 认证
  accept_digest: false         # 接受 Digest 认证
  default_to_digest: false     # 是否默认 Digest 优先
  # digest_auth_timeout: ...

accept_basic: true 与未配置 SSL 组合时，日志会警告 Basic authentication is enabled: It is highly recommended to enable SSL. 生产应启用 TLS 或用 Digest。

5. 目录浏览：dir_browser

dir_browser 提供 HTML 目录列表（默认开启）：

dir_browser:
  enabled: true
  # htdocs_path: ...    # 自定义静态资源路径（一般不需改）
  # response_trailer: ... # 列表尾部追加 HTML
  # davmount_auto_add: false

开启后对集合 GET 请求返回 HTML 页面（<title>WsgiDAV - Index of / </title>），而不是 PROPFIND XML。可用成员链接、排序等。

也可在配置中关闭：

dir_browser:
  enabled: false

6. 锁管理器：lock_storage

WebDAV LOCK/UNLOCK 需要锁存储，默认 LockStorageDict（进程内）：

lock_storage:
  # 使用内置内存锁
  use_multi_lock_manager: false    # 多进程共享锁

更常见是把锁/属性存储配置为文件或数据库（生产多进程）：

# 基于 dict（默认，进程内）
lock_storage: true

# 用 SQLite 持久化
lock_storage:
  type: sqlite
  db: /var/lib/wsgidav/locks.db

单进程默认没问题；gunicorn 多 worker / 多机时，务必使用可共享的锁存储（如 sqlite/数据库），否则 LOCK 互斥失效。

7. 属性管理器：prop_manager

用于存储 DAV 属性（PROPPATCH/PROPFIND 的自定义属性），默认无（None）：

# 用内存字典
prop_manager:
  enable: true

生产多进程建议持久化（支持 sqlite / database 等后端）。属性数据用于 D:displayname 自定义属性、resourcetype 等。

8. 日志：verbose / summary

verbose: 4        # 日志详细度 0..5（默认 3），越高越详细
summary: True     # 请求结束后打印摘要行（每个请求一行）

键	默认值	说明
`verbose`	`3`	0=quiet ~ 5=最详
`summary`	`True`	每个请求末打印摘要日志

也可用命令行 -v/-q 增减 verbose。verbose: 4 时会打印 401 认证失败、方法执行时长等详细信息，排障很有用。

9. SSL（TLS）

cheroot server 支持内置 SSL：

ssl_certificate: /etc/wsgidav/cert.pem
ssl_private_key: /etc/wsgidav/key.pem

配置后可改 port 为 443（HTTPS 默认端口）并以 https:// 访问。--ssl-adapter {builtin,pyopenssl} 选适配器（默认 builtin）。生产应使用受信任的域名证书。

10. 命令行参数对照

flag	对应配置	默认
`-p`	`port`	8080
`-H`	`host`	localhost
`-r`	`root`（provider）	无
`-c / --no-config`	config path	当前目录 wsgidav.yaml
`--auth`	domain_controller	simple_dc
`--server`	server	cheroot
`--ssl-adapter`	ssl adapter	builtin
`-v / -q`	verbose	3

11. 一份生产可参考的完整配置

# /etc/wsgidav.yaml
host: 0.0.0.0
port: 8080

provider_mapping:
  "/":
    root: /data/share
    prop_manager: true
    lock_storage: true

simple_dc:
  user_mapping:
    "/":
      admin:
        password: "{env}ADMIN_PASS"
        roles: ["admin"]
      bob:
        password: bob123
    "*": false

http_authenticator:
  accept_basic: true
  accept_digest: false

dir_browser:
  enabled: true

lock_storage:
  use_multi_lock_manager: false

prop_manager:
  enable: true

# ssl_certificate: /etc/wsgidav/cert.pem
# ssl_private_key: /etc/wsgidav/key.pem

verbose: 4
summary: True

⚠️ WsgiDAV 的 simple_dc 不支持 {env} 取环境变量密码（部分版本通过 {env} 支持？）。为最稳妥，生产建议用 Apache htpasswd 生成的 bcrypt 散列 + 自定义 DomainController，或保险起见直接写明文 + 文件权限保护。本文以明文演示，请根据你的实际版本确认哈希支持。

12. 常见问题

Q1：Missing configuration simple_dc.user_mapping["/"]？ user_mapping 缺 / 键。provider realm / 必须能在这个映射里找到（或 *）。

Q2：登录 401？ 密码字面明文；用户名存在；realm 匹配；必要时 verbose: 4 看认证失败日志。

Q3：多 worker 锁失效？ 多进程用共享 lock_storage（sqlite/db），别用默认进程内 dict。

Q4：想让某用户只读？ WsgiDAV 通过权限/角色控制；roles: [] 或配合反向代理/ACL。若需按目录精细权限，需借助 dav_provider 的 readonly 或上层授权（本文 WsgiDAV 默认不加细粒度 W ACL——权限主要靠操作系统/角色实现）。

13. 参考链接

官方配置文档：https://wsgidav.readthedocs.io/en/latest/run-configure.html
官方仓库：https://github.com/mar10/wsgidav
RFC 4918：https://www.rfc-editor.org/rfc/rfc4918
SimpleDomainController 源码：https://github.com/mar10/wsgidav/blob/master/wsgidav/dc/simple_dc.py