WebDAV 同步备份

从侧边栏「多端同步」进入 WebDAV 页面。先保存连接设置，再选择「立即同步」或「立即备份本机」。配置管理中的本地加密导出、导入、模板和历史恢复保持不变。

连接设置

WebDAV 地址填写已有基础目录的完整 HTTP(S) 地址，例如 https://dav.example.com/remote.php/dav/files/user/，而不是仅填写网站首页。基础目录必须存在；不要包含用户名密码、查询参数或 URL 片段。
目录前缀默认为 LinkPort/；留空保存时也会使用该默认值。允许相对多级目录，不允许绝对路径、..、反斜杠或连续斜杠。上传时通过 MKCOL 创建前缀下需要的子目录，不创建基础目录。
支持 Basic 用户名/密码（包括服务商应用密码）；匿名目录将用户名和密码均留空。建议 HTTPS；HTTP 的登录信息可能被窃听。不支持自动跳转、Digest、OAuth 或自签名证书跳过校验。
编辑已保存设置时，登录密码留空且地址、用户名均未改变才保留旧密码；更改地址或用户名后需要重新填写。勾选清除密码可显式移除旧密码。
加密口令不是 WebDAV 登录密码。口令为 12–1024 字节；所有同步设备使用相同口令。保存口令留空保留原值；手动操作可填写仅本次使用的口令，自动同步必须保存口令。更换口令应使用新的前缀，并在所有设备重新配置。
自动同步默认关闭，开启后默认每 5 分钟执行，允许 1–10080 分钟。服务停止期间不执行，重启不补跑全部错过的周期。手动同步或备份会更新最近执行时间，下次自动同步从该时间重新计算。

登录密码与保存的加密口令在本机加密存储，接口仅返回是否已保存，不回传秘密。上传前使用 AES-256-GCM 加密，PBKDF2-SHA256（600000 次）派生密钥，每次使用随机盐和 nonce。明文配置需小于 16 MiB（预留加密认证标签空间），远端加密文件上限 24 MiB。

多端同步

各设备使用相同基础地址、目录前缀和加密口令；共享文件为 <prefix>/sync/configuration.json。

同步范围包含目标、代理、资产文件及凭据、项目/环境选项、网关监听配置、访问控制和账号映射，新增、修改、删除均会传播。审计日志、个人登录凭据、API Token、配置历史、设备 SSH 身份、WebDAV 设置与网关运行状态保留在设备本地；外部文件路径不会自动转成文件资产。

初次同步且远端无文件时上传本机配置；本机为空时可拉取远端，两端相同则记录一致状态。初次两端均有不同配置时要求选择。
此后基于上次同步内容判断：仅本机变化时推送，仅远端变化时拉取；两端均变化则暂停并显示冲突。
冲突选择「保留本机配置」或「采用远端配置」作用于完整同步范围，包含删除，不进行字段合并。选择期间任一端再次变化会使旧选择失效，需要重新同步确认。
远端共享文件被删除不会直接清空本机，而是提示冲突，可确认保留本机配置重新建立共享文件。
应用远端配置前必须停止本机全部网关；应用后网关仍保持停止，启动前核对监听 IP 和端口。设备 SSH 身份不随远端替换。

服务需支持 GET、PUT、MKCOL，读取已有同步文件时返回强 ETag，并正确执行 If-Match / If-None-Match: * 条件写入。不支持这些条件的服务不能安全多端同步，不提供强制覆盖降级。PUT 响应可不含 ETag，下一次读取仍要求强 ETag。目录创建接受 201 或表示目录已存在的 405，其余错误终止操作。重定向不自动跟随，服务商错误响应正文不进入界面或日志。

同步配置替换和基线写入沿用同一个短数据库事务，确保本地内容与基线一致；设置更新与基线清除也保持原子性。网络传输不放入数据库事务，任务通过设备锁和数据库租约避免重入。

具体比较规范化后配置的 SHA-256，而不是含随机盐的密文，也不使用设备时间决定哪端胜出。记本机哈希为 L、远端为 R、本机上次同步基线为 B；已有基线且远端文件存在时：

条件	动作
L = R	无需传输，更新一致基线
L ≠ B，R = B	推送本机
L = B，R ≠ B	拉取远端
L ≠ R，且两端均不等于 B	暂停并要求人工选择

更改 WebDAV 地址、前缀或用户名会重置本机基线，按首次接入重新判断，不沿用其他目录的同步历史。

独立加密备份与恢复

「立即备份本机」在 <prefix>/backups/<UTC时间戳>-<随机值>.json 创建独立加密文件，不读取或修改共享同步文件，不替换本机配置，不推进同步基线，也不消除已有冲突。每次备份使用不同文件名和条件创建，避免覆盖旧备份。其内容范围与同步快照一致；它不是包含主密钥、审计的完整 SQLite 灾备。

页面最近执行时间、成功/错误和动作记录当前由同步与备份共用；成功备份会更新最近成功并清除上次任务错误，但不代表同步冲突已解决或远端同步成功，冲突标志仍保留。

恢复方法：

用自己的 WebDAV 客户端下载所需备份文件。
打开「配置管理」导入该 JSON 文件，输入备份时使用的加密口令。
先查看导入预览，再确认导入；按配置导入规则处理资源，而非静默整体替换数据库。详见配置备份。

当前不提供远端文件列表、在线选择恢复、自动备份轮转或自动删除；独立快照由用户手动触发，定时开关仅执行多端同步。备份留存及清理使用 WebDAV 客户端管理，不要误删共享同步文件。运行实例的完整灾备仍需停服并备份完整数据目录。

从 S3 升级

WebDAV 替代原 S3 页面、调度任务和 API，旧 /api/v1/configuration/s3/* 路由返回 404。旧 S3 设置、状态表和远端文件保留，不删除、不自动迁移或继续上传；WebDAV 独立初始化设置及同步基线，自动同步默认关闭。

部署新版本前先停止自己管理的本地服务，备份完整 data 目录。首次运行新版本会新增 webdav_sync_settings / webdav_sync_state 表，不覆盖旧 S3 数据。随后填写 WebDAV 地址与凭据，建议使用空的新前缀，并先手动备份或同步确认。旧版回退可能重新使用旧 S3 自动设置，回退前需检查旧配置，不能假定 WebDAV 已迁移回 S3。

API

需要个人会话；写请求必须通过 CSRF 校验，禁止 API Token，响应不缓存。

方法	路径	用途
GET / PUT	`/api/v1/configuration/webdav/settings`	读取脱敏设置 / 保存连接及调度设置
GET	`/api/v1/configuration/webdav/status`	最近执行、下次运行、冲突状态
POST	`/api/v1/configuration/webdav/sync`	手动同步
POST	`/api/v1/configuration/webdav/backup`	独立备份本机

设置字段为 endpoint、prefix、username、password、clearPassword、passphrase、automatic、intervalMinutes。只读秘密状态为 hasPassword、hasPassphrase。

同步与备份请求可含 passphrase，留空使用保存值；无额外参数时仍发送 {}。处理同步冲突时传 resolution: "local" / "remote" 及状态接口返回的 localHash、remoteHash，独立备份不接受冲突选择。成功结果包含 endpoint、key 和 action：同步为 pushed / pulled / unchanged，备份为 backed_up。

验证边界

协议和双端同步测试使用 Go HTTP fixture，浏览器端到端使用新构建程序、隔离数据库和本机 Node WebDAV fixture，覆盖真实管理 API 到上传的链路，但未连接外部真实 WebDAV 服务。实际全量与专项测试结果见测试记录。

7.9 KiB Raw Blame History Unescape Escape