LinkPort/docs/webdav-sync.md

WebDAV 同步备份

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

连接设置

2026-10-07 UI 修复：编辑未保存时，刷新设置或离开当前页面须确认，取消保留草稿；请求进行中禁用刷新、密码清除和自动同步开关，避免请求结果覆盖中途修改。同步失败与随后状态刷新失败同时发生时保留原始同步错误；同步成功但状态刷新失败时明确说明操作已完成，不提示重复同步。密码提示与服务端保持一致：仅地址和用户名都未改变时留空保留旧密码。这些改动不改变 WebDAV API 或存储格式。新增浏览器 fixtures 验证上述行为，不连接真实 WebDAV 服务。

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

WebDAV 登录密码在本机加密保存，接口只返回 hasPassword，不回传密码。配置包内的业务凭据用于恢复/同步，远端 JSON 包含这些凭据；这与配置管理的手动加密导出是不同入口。

多端同步

各设备使用相同基础地址和目录前缀，并具备读写权限；共享文件为 <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 创建独立 JSON 配置文件，不读取或修改共享同步文件，不替换本机配置，不推进同步基线，也不消除已有冲突。每次备份使用不同文件名和条件创建，避免覆盖旧备份。其内容范围与同步快照一致；它不是包含主密钥、审计的完整 SQLite 灾备。

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

恢复方法：

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

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

从 S3 升级

WebDAV 替代原 S3 页面、调度任务和 API，旧 /api/v1/configuration/s3/* 路由返回 404。S3 设置存储已删除，不再创建、读取或校验旧 S3 设置；WebDAV 独立初始化设置及同步基线，自动同步默认关闭。真实数据库与远端文件不在本次代码清理中修改。

当前使用 schema 3 数据库及版本 2 配置包；保留旧数据库的本地启动迁移，远端版本 1 配置包仍不直接导入，两者不属于同一种迁移。新环境请使用新的数据路径与远端前缀。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、automatic、intervalMinutes。只读秘密状态为 hasPassword。

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

验证边界

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