# ZFile Pro Windows 使用说明

## 快速开始

- 双击 `ZFile 管理器.bat` 进入统一数字菜单。
- 启动、停止、重启、状态、日志、更新、回滚、管理员重置和系统服务均从该菜单操作。
- 进入“服务管理”时会自动弹出 UAC 管理员确认，普通功能不会无故申请管理员权限。

发布包只保留一个 Windows BAT 入口。`ZFile 管理器.bat` 只调用 `bin\zfile-manager.exe`，不依赖 Windows PowerShell、curl、tar、OpenSSL 或第三方解压软件。更新下载、RSA 数字签名验证、SHA-256 校验、安全解压、备份和失败回滚均由管理器完成。

直接执行 `bin\zfile-manager.exe` 或无参数执行 `ZFile 管理器.bat` 会进入数字菜单。该 BAT 仍支持命令行子命令，例如：

```bat
"ZFile 管理器.bat" status
"ZFile 管理器.bat" version
"ZFile 管理器.bat" update --check
```

管理器会将操作结果和耗时记录到 `zfile.log.path` 对应目录下的 `manager.log`，锁文件和 PID 文件也存放在该目录，安装目录日常运行时不需要写权限。单文件达到 10 MB 后轮转并保留 5 份。日志不会记录密码、Token、授权头或更新地址查询参数。

双击进入菜单时窗口会持续保留；命令执行失败时入口会等待按键，避免错误窗口直接关闭。计划任务和无人值守调用可使用 `"ZFile 管理器.bat" <命令>`，设置 `ZFILE_NO_PAUSE=1` 可关闭失败暂停。注册系统服务后，启动、停止、重启、状态和环境诊断会自动改用 Windows 服务控制管理器，不会再启动第二份便携进程。

## Windows 系统服务

双击 `ZFile 管理器.bat` 后选择“服务管理”，管理器会通过 Windows 原生 UAC 自动打开管理员窗口，不依赖 PowerShell。服务名称为 `zfile`，Windows 显示名称为 `ZFile`。

命令行也可直接使用。`service status` 可在普通 CMD 中查询；安装、启停、重启、修改开机自启和卸载需要使用管理员 CMD：

```bat
"ZFile 管理器.bat" service install --auto
"ZFile 管理器.bat" service start
"ZFile 管理器.bat" service status
"ZFile 管理器.bat" service disable
"ZFile 管理器.bat" service uninstall
```

服务默认使用独立的 `NT SERVICE\zfile` 虚拟服务账户。管理器会为安装目录授予读取和执行权限，并为解析后的日志、SQLite 数据目录授予写权限。若存储源需要访问其他本地目录、SMB 共享或域资源，需要由管理员额外授予该虚拟账户权限，或在 Windows 服务管理器中将服务登录账户改为具有相应权限的专用账户。

服务注册成功后，管理器会显示服务名称并再次提示权限要求。后续启动、停止、重启、开机自启和卸载统一从 `ZFile 管理器.bat` 的“服务管理”菜单进入。

注册服务时会保存当时解析后的日志和数据库绝对路径，避免服务账户变化导致 `${user.home}` 指向另一套数据目录。

可在 CMD 中使用以下命令：

```bat
bin\zfile-manager.exe diagnose
bin\zfile-manager.exe service status
bin\zfile-manager.exe logs --manager
bin\zfile-manager.exe logs --tail --lines 200
"ZFile 管理器.bat" update --list-backups
"ZFile 管理器.bat" update --rollback
"ZFile 管理器.bat" update --rollback 备份目录名 --yes
```

启动、停止、更新、回滚和管理员重置具有排他锁，同一安装目录不会同时执行两个可能冲突的管理操作。回滚前还会自动建立当前版本的安全备份。

更新备份包含程序、静态资源、入口脚本和 `application.properties`。SQLite 数据库会在停服后一起备份和恢复；MySQL/PostgreSQL 必须使用数据库工具单独备份。若新版本已经执行 Flyway，先恢复数据库，再使用 `--external-db-restored --yes` 显式确认程序回滚，否则管理器会拒绝执行。

检测到 MySQL/PostgreSQL 更新时，交互菜单会先要求确认数据库已经自行备份。非交互更新必须同时使用 `--yes --external-db-backed-up`，否则管理器会拒绝开始下载和安装。

交互菜单查看日志时可输入最近行数，直接回车默认 100 行。重置管理员密码时，密码直接回车会生成并显示随机强密码；手动设置密码需隐藏输入两次，成功结果不会回显密码。环境诊断只进行本机检查，不主动访问网络。

管理器自身使用固定版本的 go-legacy-win7 构建，目标兼容 Windows 7、Windows Server 2008 R2、Windows 8/8.1、Windows Server 2012/2012 R2 及更新的 x64 Windows。系统仍需保留可用的 TLS 1.2 和受信任根证书，才能连接 HTTPS 更新服务器。

ZFile 主程序由 GraalVM Native Image 构建，它与 Go 管理器是两个独立程序。发布流程会在当前 Windows 构建环境执行冒烟测试，但 Windows 7/8.1 和 Server 2008 R2/2012 R2 上的主程序兼容性仍需在真实旧系统中单独验证。
