企业官网建设流程全解析

• 桌面应用

QOwnNotes TUI 是一款面向键盘操作（keyboard-first）的终端笔记浏览器与编辑器，专门用于浏览和编辑本地、与 QOwnNotes 兼容的 Markdown 笔记文件夹。它可以直接复用 QOwnNotes 中已配置的笔记文件夹，并遵循 QOwnNotes 的笔记排序设置，因此安装后即可立刻开始处理你现有的笔记。读完本文，你将掌握 TUI 的安装（含 Nix 方式）、命令行启动、完整按键映射，并理解它如何以只读方式读取 QOwnNotes 的应用数据库（notes.sqlite）与 QSettings 配置，实现"开箱即用"。

什么是 QOwnNotes TUI

QOwnNotes TUI 是一个运行在终端里的轻量级笔记工具，核心定位与 QOwnNotes 桌面应用互补：桌面端负责完整的图形化编辑、预览与同步管理，而 TUI 让你在 SSH 会话、无图形界面环境或纯键盘工作流中，也能流畅地浏览和编辑同一批本地 Markdown 笔记。

它的核心特性包括：

• 直接使用 QOwnNotes 配置的笔记文件夹：读取 QOwnNotes 中登记的所有笔记文件夹，并遵循其笔记排序设置（此时 QOwnNotes 的应用数据库以只读方式打开，不会破坏桌面端数据）。
• 完整的终端笔记操作：可以在终端里创建、编辑、搜索、语法高亮笔记，根据笔记内容重命名，以及在确认后安全删除笔记。
• 自动保存与冲突检测：修改会被自动保存，并检测外部修改导致的冲突（例如桌面端或其他终端会话同时改动了同一篇笔记）。
• 可配置主题与鼠标支持：支持自定义主题，也支持鼠标操作。
• Nix 支持：提供 Nix 包与Home Manager 模块，方便 Nix 用户直接集成。
• Shell 补全：可为Bash、Fish、Zsh等 Shell 自动生成命令补全。

安装 QOwnNotes TUI

通过 Release 页面下载

访问 QOwnNotes TUI 的latest release 页面，下载与你操作系统和 CPU 架构匹配的版本即可。建议优先选择官方发布页提供的预编译二进制，它们通常已内置 Shell 补全与主题资源。

通过 Nix 直接运行

如果你使用 Nix，可以直接从源码构建并运行，无需手动下载：

nix run github:qownnotes/qownnotes-tui -- --notes-dir ~/Notes

这里--notes-dir ~/Notes直接指定了要打开的笔记文件夹。Nix 包装会在安装时自动为 Bash、Fish 和 Zsh 生成 Shell 补全，无需额外配置。

::: tip Nix 用户还可以把 TUI 包装为 Home Manager 模块，随系统配置一起声明式地安装和升级，便于在多台机器上保持一致环境。 :::

命令行用法

指定笔记文件夹启动

qownnotes-tui --notes-dir ~/Notes

--notes-dir接受一个本地路径，TUI 会以该文件夹为笔记根目录启动。

不指定参数：自动读取 QOwnNotes 已配置的文件夹

如果不提供任何笔记文件夹参数，TUI 会读取 QOwnNotes 中配置的全部笔记文件夹，并默认打开"当前文件夹"（即 QOwnNotes 中最近激活的那个）。

这一行为的底层逻辑可以从本仓库源码中得到印证：

• notefolder.cpp 中的NoteFolder::fetchAll()从应用数据库取出全部笔记文件夹记录；
• notefolder.cpp 中的setAsCurrent()会把当前文件夹 ID 写入 QSettings 的currentNoteFolderId键，并把本地路径写入notesPath键——这正是 TUI 定位"当前文件夹"所依赖的配置来源；
• notefolder.cpp 中的currentLocalPath()在桌面端读取currentNoteFolderId对应的localPath，并以notesPath作为回退值。

也就是说，只要你在 QOwnNotes 里配置过笔记文件夹，TUI 无需任何重复配置就能直接沿用。

按键映射速查

TUI 采用经典的终端分栏布局：左侧是笔记文件夹/笔记列表，右侧是预览或编辑器。以下是最常用的按键：

使用技巧：

• 在任意界面按?可随时调出完整帮助，不必死记快捷键；
• n/Ctrl-n创建的是时间戳命名的新笔记，与 QOwnNotes 桌面端"新建带时间戳笔记"的行为保持一致，保证文件名在文件夹内唯一；
• e进入编辑器后，所有修改都会自动保存（也可用Ctrl-s手动触发），无需担心丢失；
• 当其他程序（如 QOwnNotes 桌面端）同时修改了正在编辑的笔记时，TUI 会检测到外部修改冲突并给出提示，避免覆盖对方的内容。

深入理解：TUI 如何安全复用 QOwnNotes 的数据

应用数据库以只读方式打开

QOwnNotes 把笔记元数据、标签关系、排序信息等存放在每个笔记文件夹内的 SQLite 数据库文件中。从仓库源码可以看到，这个数据库固定命名为notes.sqlite，位于笔记文件夹根目录：

• databaseservice.cpp：getNoteFolderDatabasePath()返回NoteFolder::currentLocalPath()与notes.sqlite拼接的路径；
• databaseservice.cpp：连接时使用QSQLITE驱动，并设置QSQLITE_OPEN_URI;QSQLITE_BUSY_TIMEOUT=5000，即对数据库操作设置了 5 秒的忙等待超时。

TUI 打开这份数据库时只读，因此不会写入任何索引或状态，也就不会污染桌面端正在使用的数据；同时配合 SQLite 的锁与忙等待机制，桌面端与 TUI 可以安全地并存访问同一笔记文件夹。

排序设置来自 QSettings

QOwnNotes 的全局设置通过 Qt 的QSettings持久化。仓库源码中：

• main.cpp 设置了组织名PBE、应用名QOwnNotes（带构建变体后缀），这是所有配置键的命名空间；
• settingsservice.cpp 封装了对QSettings的读写，并支持IniFormat覆盖文件；
• 每个笔记文件夹的专属设置以NoteFolder-<id>/<key>形式存储，见 notefolder.cpp 的setSettingsValue()与settingsValue()。

TUI 正是通过读取这份配置（以及notes.sqlite中的文件夹记录）来获知"有哪些笔记文件夹、当前是哪个、按什么规则排序"，从而做到与桌面端一致的目录结构与笔记顺序。

笔记即纯文本 Markdown

与 QOwnNotes 桌面端一致，TUI 处理的笔记本质是文件夹里的.md纯文本文件。仓库中 note.h 的getFileName()、getNoteText()、Note::addNote()等接口表明：笔记的名称来自文件名，正文来自文件内容。TUI 的"根据内容重命名"、"语法高亮"、"全文搜索"全部建立在直接读写这些文本文件之上，因此任何 Markdown 编辑器（或 Git）都能与 TUI 共存互操作，这也是 QOwnNotes 生态"文件即笔记"设计哲学的终端延伸。

小结

QOwnNotes TUI 为纯键盘与终端场景提供了完整的笔记工作流：一条nix run或一个--notes-dir参数即可上手，自动继承 QOwnNotes 的文件夹配置与排序规则；创建、搜索、编辑、重命名、安全删除等操作全部在终端内完成；自动保存与外部冲突检测保障数据安全。对于需要在服务器、SSH 会话或极简工作流中管理 QOwnNotes 笔记的用户，这是一个开箱即用、与桌面端数据天然兼容的选择。

• 桌面应用