曾志威
408f346ab1
Replace active S3 sync with encrypted WebDAV synchronization and independent backups. Support explicit empty passwords and unauthenticated MongoDB, Redis, HTTP and HTTPS targets. Include migration, design and validation documentation. Validation: build and go vet passed; Playwright 113 passed with 4 existing failures. Full Go run reproduced the existing cluster discovery test failure. Preserve unrelated SSH fingerprint changes outside this commit.
5.3 KiB
单 SQLite 持久化
当前行为（2026-09-21）
Windows、Linux、macOS 使用同一套单文件存储。新建数据目录只需要 serviceport.sqlite；管理员、目标、网关、代理、文件资产、历史配置、审计命令、输出、连接事件、内部随机主密钥和自动 TLS 证书/私钥都保存在其中。应用不再读取 SERVICEPORT_MASTER_KEY，不提供外部主密钥运行模式，也不再提供 generate-key 命令。
默认位置为工作目录 data/serviceport.sqlite，可用 SERVICEPORT_DATA 指定。Windows 回环管理模式保留当前目录优先、旧 AppData 次之的查找行为；serviceport data-path 只查询路径，不初始化数据。Linux/macOS 不使用 Windows AppData。登录、远程管理认证、CSRF 与协议权限限制不因密钥入库而放宽。
SQLite 在运行、写入或异常退出后可能存在 -wal、-shm、-journal 文件。这些不是额外的业务数据库，但不能在运行时删除，也不能在未完成 checkpoint 时只复制主文件。正常关闭所有数据库连接后才可仅备份/迁移 SQLite。程序被强制终止后应先恢复并正常关闭，或使用 SQLite 一致性备份工具。Windows 使用命名互斥量，Linux/macOS 使用主数据库文件的 advisory flock，不为新库创建 desktop.lock。
安全边界
字段仍使用随机密钥 AES-GCM 编码，但密钥与密文在同一个 SQLite 内，因此不再提供对数据库文件持有者的保密隔离。拿到完整数据库即能恢复保存的凭据。文件必须视同包含明文密码的敏感材料：限制目录/文件权限，使用磁盘加密；离机备份另行加密。Windows 不再绑定 DPAPI 用户或机器，Linux/macOS 新建文件权限为 0600，已有文件权限不自动改写。
从旧版本迁移
- 停止旧服务，备份整个旧数据目录，包括 SQLite、WAL、
audit/、tls/和master-key.dpapi。不要让新旧版本同时运行。 - Windows DPAPI 旧库：在原 Windows 机器、原用户下运行
serviceport migrate-data。该命令迁移后退出，不监听端口、不启动网关、不连接真实目标。正常启动也可执行同样的初始化，但升级建议先运行离线命令。 - 旧外部主密钥库：运行
serviceport migrate-key，在不回显的终端提示中输入原 Base64 密钥。它仅用于一次性解密校验/入库，不重新引入环境变量运行模式。原密钥丢失无法恢复；不会生成替代密钥覆盖旧库。 - 审计分库按日期顺序合并，命令输出分块保持顺序。每个分库在一个事务中写入及记录迁移标记，中断后重试不重复导入；冲突报错。全部完成后不再读取旧审计目录，新日志只写主库。审计分页游标/输出序号是内部定位值，迁移后须重新加载列表，不复用旧页面游标。
- 自动 TLS 导入旧
tls/cert.pem和tls/key.pem，不更换有效身份；新库自动生成 localhost 自签名证书。损坏、缺半边的旧证书直接报错，不偷偷重建。 - 迁移不删除旧 DPAPI、审计或 TLS 文件；保留作回退材料。确认迁移成功并停服后，复制只有 SQLite到一个新目录即可独立运行，旧目录可作为归档。后续不再需要外部密钥文件。不要用旧版程序直接打开升级后的数据库；回退请恢复完整升级前备份。
初始化元数据表与密钥行需原子提交，防止崩溃留下“表存在但密钥未写入”的数据库。密钥已有但损坏或缺失时拒绝启动，不自动替换。审计导入事务用于保证数据与迁移标记一致，不涉及外部调用；日常保留期清理先按时间索引查最多 500 个 rowid，再按这些 ID 删除，级联删除对应输出。
TLS 与可移植性的范围
自动证书默认覆盖 localhost、127.0.0.1、::1，有效期一年。停止服务后运行 serviceport export-ca，标准输出为公开 CA PEM，可另存后配置客户端信任，私钥不导出。该导出文件只供客户端使用，不是服务启动依赖。
显式的 SERVICEPORT_TLS_CERT / SERVICEPORT_TLS_KEY 自定义证书仍优先，适用于正式域名/证书轮换；使用者主动配置的外部文件仍需自行管理。目标中主动填写的 SSH/kubeconfig 等文件路径也不会自动吸收入库；要完全可移植，请上传为文件资产并使用资产引用。WebDAV 配置备份仍是原配置包语义，不等同于包含审计和主密钥的 SQLite 灾备。
验证
新增隔离 SQLite 测试覆盖：新库仅留主文件、只复制 SQLite 后管理员/命令/输出/TLS 恢复、旧密钥迁移及错误密钥拒绝、跨日审计导入和重启幂等、分页、保留期级联清理。Windows 定向测试覆盖真实 DPAPI 旧密钥读取与无文件进程锁。完整验证结果记录于 docs/change-rationale.md；未将 fixture 测试视为真实上游服务器验证。
2026-09-21 本机按用户明确要求，在完整备份、离线迁移及单文件副本验证后删除了运行目录的 master-key.dpapi，复核没有重新生成。此项为已授权的本机清理，不是启动时自动删除其他旧目录的策略。Go 全量测试、vet、三平台编译通过；前端构建和 Playwright 受环境子进程权限限制，详见变更记录。