安装、更新与文件关联

Navop 提供 macOS、Windows 和 Linux 桌面版本。安装包、系统架构和版本号必须相互匹配；升级前应先保存正在编辑的 SQL、Notes 和远程文件，并结束手动事务与传输任务。

文档中的安装、更新和文件关联说明以当前稳定发布版为准。下载页中的版本号、架构后缀和校验文件是判断安装包是否匹配的唯一依据，不要使用搜索引擎中来历不明的镜像。

下载并安装

从官网下载中心选择最新稳定版。macOS 根据设备选择 Apple Silicon 或 Intel 构建，将应用拖入“应用程序”；Windows 使用对应安装包完成安装；Linux 按发布页提供的格式安装，并确认桌面环境允许启动图形应用。

首次启动若被 macOS Gatekeeper 拦截，应先确认安装包来自项目正式发布页，再到“系统设置 → 隐私与安全性”允许打开。Windows 或 Linux 的安全软件提示也应先核对文件来源和版本，不要通过关闭全局安全策略来规避检查。企业设备如受管理员策略管理，请由管理员批准安装。

安装包选择表

平台	设备/架构	推荐文件	适用场景
macOS	Apple Silicon	navop-<version>-macos-arm64.dmg 或 navop-<version>-macos-arm64.tar.gz	M 系列 Mac
macOS	Intel	navop-<version>-macos-x64.dmg 或 navop-<version>-macos-x64.tar.gz	Intel Mac
Windows	x86_64	navop-<version>-windows-x64.msi	MSI 安装包，提供开始菜单、桌面快捷方式和稳定的文件关联
Windows	x86_64	navop-<version>-windows-x64.exe	EXE 安装包，封装同一套当前用户 MSI 安装流程
Windows	x86_64	navop-<version>-windows-x64.zip	免安装运行；数据仍保存在 Windows 用户目录
Windows	x86_64	navop-<version>-windows-x64-portable.zip	数据与程序放在同一目录、可整体移动
Linux	x86_64	navop-<version>-linux-x64.tar.gz、navop-<version>-linux-x64-portable.tar.gz、navop_<version>_amd64.deb、navop-<version>-1.x86_64.rpm、navop_<version>_amd64.AppImage	按发行版和桌面环境选择
Linux	ARM64	navop-<version>-linux-arm64.tar.gz、navop-<version>-linux-arm64-portable.tar.gz	ARM64 设备

每个发布版本的 sha256sums.txt 用于校验下载完整性。企业环境应在安装前保存版本号、文件名和校验值，便于回溯。

Windows 安装版

常规安装可以选择 navop-<version>-windows-x64.msi 或 navop-<version>-windows-x64.exe；32 位 Windows 请下载名称中明确包含 win32 的安装包，例如 navop-<version>-win32.exe。EXE 安装包内嵌并启动同一套 MSI 安装流程，因此两者默认都安装到当前用户目录，创建开始菜单和桌面快捷方式，注册支持的文件关联，使用正常的 Windows 用户数据目录，并支持记住主密钥后自动解锁。使用默认的当前用户安装位置时不需要管理员权限。

Windows 免安装 ZIP

普通 navop-<version>-windows-x64.zip（32 位版本为 navop-<version>-win32.zip）只包含常规的 navop.exe，使用前需要完整解压。它不会安装快捷方式或文件关联，但仍使用正常的 Windows 用户数据目录，并支持记住主密钥后自动解锁。除非要主动启用下述便携模式，否则不要在程序旁放置 navop.portable。

从 v0.10.1 或更早版本的 Windows ZIP 升级

IMPORTANT

v0.10.1 及更早版本的普通 Windows ZIP 实际上已经包含 navop.portable，因此这些用户当前使用的是便携模式。升级时请下载新的 navop-<version>-windows-x64-portable.zip（32 位版本名称包含 win32），备份并完整保留旧目录中的 data，同时确保 navop.portable 仍与 navop.exe 同级。

不要为了切换版本而直接删除旧目录中的 navop.portable。删除标记只会让 Navop 改用正常的 Windows 用户数据目录，并不会自动复制或迁移原来的便携数据。

如果将新的普通 navop-<version>-windows-x64.zip 或 navop-<version>-win32.zip 解压到一个全新目录，或改用 MSI/EXE 安装版，Navop 将使用正常的 Windows 用户数据目录。此时原有连接、设置和扩展可能看起来消失，但旧便携目录中的数据并未被删除；安装程序也不会自动迁移该目录。需要改用安装版时，请先保留完整的旧便携目录和主密钥，确认迁移后的数据可用后再清理旧目录。

Windows 便携版

解压与首次启动

Windows -portable.zip 是独立的便携版，官方压缩包中包含：

navop.exe
navop.portable

navop.portable 是启用便携模式的标记文件，必须与 navop.exe 保持在同一目录。不要直接在 ZIP 压缩包内运行，也不建议删除或重命名该文件。请先将压缩包完整解压到当前用户可写的普通目录，例如：

D:\Apps\NavopPortable\
├── navop.exe
└── navop.portable

然后双击 navop.exe，或在 PowerShell 中运行：

.\navop.exe

首次启动后，Navop 会在可执行文件旁自动创建 data 目录：

D:\Apps\NavopPortable\
├── navop.exe
├── navop.portable
└── data\
    ├── config\
    ├── state\
    └── cache\

便携目录必须可写。不要放在 Program Files、只读目录或只读移动介质中；使用 U 盘或移动硬盘时，也应确认介质连接稳定且允许写入。目录不可写时，Navop 会拒绝启动。

数据目录与主密钥

便携版把配置、应用状态和缓存分别保存在 data/config、data/state 和 data/cache，便于连同程序一起移动或备份。**默认情况下，便携模式不会持久化主密钥，每次启动都必须重新输入。**用户可以在设置中明确选择把可自动恢复的加密副本保存到 data/state/key_storage。

此选项有显著安全风险：文件加密使用程序内置密钥，而不是设备绑定保护。任何同时获得应用程序和完整 data 目录的人都可能恢复主密钥。仅在理解并接受此风险时启用。忘记的主密钥仍不能仅靠重新下载或重装 Navop 恢复；只有此前已启用该选项，并保留匹配的完整应用程序和 data 副本时，才可能自动恢复。

请将主密钥独立保管，不要以明文形式放入便携目录或同一个 U 盘。data 中可能包含连接配置、状态、扩展和缓存，不要公开分享、提交到 Git，或存放在不可信的云同步目录中。

更新便携版

便携模式不支持应用内安装更新，也不会执行自动更新检查。手动检查更新仍可用于了解新版本，但确认更新时会打开 GitHub Releases，需要自行下载新的 Windows -portable.zip。

不要把新版本直接覆盖到正在使用的旧目录。推荐按以下步骤升级：

1. 保存 SQL、Notes 和远程文件，提交或回滚手动事务，并等待 SFTP、远程编辑等任务结束。
2. 完全退出 Navop。
3. 备份旧便携目录，至少备份完整的 data 目录。
4. 下载匹配当前架构的新 Windows -portable.zip，解压到一个新的空目录。
5. 将旧版本的整个 data 目录复制到新目录，与新版本的 navop.exe 同级。
6. 确认新目录中仍有与 navop.exe 同级的 navop.portable。
7. 启动新版本并输入原主密钥，检查版本、连接、扩展、Notes、主题和快捷键。
8. 验证完成后再删除旧目录；需要回退时，可先保留旧目录副本。

例如：

D:\Apps\
├── NavopPortable-old\
│   ├── navop.exe
│   ├── navop.portable
│   └── data\
└── NavopPortable-new\
    ├── navop.exe
    ├── navop.portable
    └── data\   ← 从旧版本复制

迁移、文件关联与安全

移动便携版前应完全退出 Navop，并确保事务、传输和远程编辑任务已结束。通常可以移动整个便携目录，但不要让两个 Navop 实例或两台设备同时写入同一份 data。

便携模式不会自动注册 .db、.duckdb 和 .md 的系统文件关联。仍可从 Navop 内打开文件，或使用 Windows“打开方式”手动选择 navop.exe；若移动了便携目录，手工建立的“打开方式”路径可能失效。需要稳定文件关联、开始菜单/桌面快捷方式、应用内更新或系统持久化主密钥时，应选择 .msi 或 EXE 安装版。

移动介质丢失可能暴露加密数据和相关元数据。迁移到新设备后仍需输入正确主密钥；验证新副本可以正常使用之前，不要删除原目录或备份。

高级启动方式

官方 Windows -portable.zip 已包含 navop.portable，普通使用无需额外参数。调试或自定义部署时，也可以通过以下方式启用便携模式或指定数据目录：

# 临时启用便携模式，默认使用 navop.exe 旁的 data 目录
.\navop.exe --portable

# 指定数据目录；该参数本身也会启用便携路径模式
.\navop.exe --data-dir "E:\NavopData"

# 通过环境变量启用便携模式
$env:NAVOP_PORTABLE = "1"
.\navop.exe

# 通过环境变量指定数据目录
$env:NAVOP_DATA_DIR = "E:\NavopData"
.\navop.exe

NAVOP_PORTABLE 支持 1、true、yes 或 on。数据目录的选择优先级为 --data-dir、--portable、NAVOP_DATA_DIR、NAVOP_PORTABLE/navop.portable，最后才是常规安装模式。指定的数据目录必须可写；建议使用绝对路径，因为相对路径会按启动 Navop 时的当前工作目录解析。

Linux Flatpak

Navop 也在 FlatPark 上架为开发者认可的社区 Flatpak 软件包。添加 FlatPark 软件源并为当前用户安装：

flatpak --user remote-add --if-not-exists flatpark https://dl.flatpark.org/flatpark.flatpakrepo
flatpak --user install flatpark dev.navop.Navop

Flatpak 软件包运行在沙盒中，部分集成功能可能需要授予额外权限。详细说明与问题排查请参阅 FlatPark 软件包页面。

首次启动与本地权限

启动后先选择界面语言、主题和默认启动页。SSH、SFTP、网络数据库和远程桌面需要访问局域网或互联网；系统弹出本地网络、防火墙或钥匙串权限时，应根据实际连接范围授权。Notes 目录、外部编辑器和自定义字体需要相应文件系统权限。

建议先创建一个不含生产凭据的测试连接，确认 DNS、代理、防火墙和证书链都正常。需要使用连接导入、远程桌面 Provider、数据库扩展或 ACP Agent 时，再从扩展市场安装对应组件。

应用内更新与回退

MSI、EXE 安装版和普通 ZIP 版可在设置的“更新”区域开启自动检查，或手动检查新版本。应用内更新会下载适合当前平台的构建；开始前关闭正在使用的连接，提交或回滚手动事务，并等待 SFTP 传输结束。更新完成后重新启动，检查连接、扩展和快捷键是否正常。Windows -portable.zip 便携版需要按照上面的“更新便携版”步骤手工升级。

若新版本与关键扩展不兼容，可先导出必要配置并从 Releases 重新安装上一稳定版。回退不会替代数据备份：本地配置格式可能随版本演进，降级前应保留 Navop 数据目录副本。不要用未知来源的旧安装包覆盖当前版本。

更新前可以按下面的顺序做一次检查：

1. 保存 SQL 编辑器和 Notes 中的未保存内容。
2. 提交或回滚所有手动事务。
3. 等待 SFTP 上传、下载、解压和远程编辑任务完成。
4. 记录当前 Navop 版本和已安装扩展版本。
5. 安装更新并重启后，先测试一个低风险连接，再恢复日常工作。

macOS 如果确认安装包来源可信但仍被系统隔离，可执行 sudo xattr -rd com.apple.quarantine /Applications/Navop.app 后重新打开；不要把关闭系统保护作为长期安装方案。

文件关联与命令行打开

Navop 支持通过系统打开 .db、.duckdb 和 .md 文件。SQLite/DuckDB 文件会创建或打开本地数据库连接，.md 文件会进入 Notes Markdown 编辑器。若系统未自动建立关联，可在操作系统的“打开方式”中选择 Navop 并设置为默认应用。

打开数据库文件前确认它不是仍由其他程序独占写入的生产文件；必要时先复制副本。打开外部 Markdown 时，Notes 会围绕文件所在位置工作，相关图片和资源路径仍受本地目录权限与相对路径影响。

卸载与保留数据

卸载应用程序本体通常不会自动删除全部本地设置、连接密文、Notes 或扩展缓存。若只是重装，不要清理数据目录；若要彻底移除，应先导出需要保留的资料、停止同步并确认团队资源已经交接，再按当前系统删除应用与用户数据。

仅靠重装无法恢复忘记的主密钥。若已启用便携主密钥持久化，自动恢复还需要匹配的应用程序和完整 data 目录，其中包括 data/state/key_storage。清除本地数据前，必须确认已记住主密钥并了解同步状态；团队 Owner 还应确认其他管理员和团队密钥状态，避免唯一可管理设备被移除。

安装后验证清单

• [ ] Navop 可以启动并显示正确版本。
• [ ] 可以打开 Demo Orders (SQLite) 或一个测试连接。
• [ ] 主题、语言和字体设置可以保存。
• [ ] .db、.duckdb 和 .md 文件关联符合预期。
• [ ] 已安装扩展在扩展市场或设置中显示为可用。
• [ ] 更新前后主密钥、连接密文和 Notes 目录仍在预期位置。