1- Hoarder 项目安装与使用文档 (待修正)

1.1- 一、项目简介

Hoarder 是一款功能强大的自托管应用程序，主要用于书签管理。它支持保存链接、笔记和图像等多种类型的信息，并且具备基于 AI 的自动标记功能以及高效的全文搜索功能，方便用户快速检索和管理自己保存的内容。

1.2- GitHub

hoarder

https://github.com/hoarder-app/hoarder

1.3- doc

doc

https://docs.hoarder.app/

1.4- 二、安装指南

1.4.1- （一）系统要求

1. 操作系统：支持主流的 Linux、Windows 和 macOS 操作系统。
2. 硬件要求：建议至少具备 1GB 内存和 10GB 可用磁盘空间，具体需求可能因数据量大小和使用场景而有所不同。

1.4.2- （二）软件依赖安装

1. Node.js
   • 前往 Node.js官方网站 下载并安装最新的 LTS（长期支持）版本。
   • 安装完成后，在终端中输入 node -v 和 npm -v 命令，确认 Node.js 和 npm（Node.js 包管理器）是否成功安装。
2. pnpm 包管理器
   • 如果未安装 pnpm，可以在终端中执行以下命令进行安装：npm install -g pnpm。
   • 安装完成后，输入 pnpm -v 命令验证安装情况。
3. 数据库（以 PostgreSQL 为例）
   • 前往 PostgreSQL官方网站 下载并安装适合您操作系统的版本。
   • 安装过程中，根据提示设置数据库管理员密码和其他相关参数。
   • 安装完成后，启动 PostgreSQL 服务。您可以使用数据库管理工具（如 pgAdmin）连接到数据库服务器，确认数据库服务正常运行。
4. Meilisearch
   • 前往 Meilisearch官方网站 下载并安装适合您操作系统的版本。
   • 启动 Meilisearch 服务，默认情况下，它将在 http://localhost:7700 上运行。您可以通过访问该地址（在浏览器中输入 http://localhost:7700）来确认服务是否启动成功。

1.4.3- （三）获取项目代码

1. 打开终端（在 Windows 上可以使用命令提示符或 PowerShell，在 Linux 和 macOS 上使用默认终端）。

2. 使用 cd 命令进入您想要安装项目的目录，例如：cd /your/directory/path。

3. 执行以下命令从 GitHub 克隆项目仓库：

   git clone https://github.com/hoarder-app/hoarder.git
   

1.4.4- （四）安装项目依赖项

1. 进入克隆下来的项目目录：

   cd hoarder
   

2. 运行以下命令安装所有依赖项：

   pnpm install
   

   此过程可能需要一些时间，因为它会下载和安装项目所需的所有 Node.js 模块。

1.4.5- （五）配置环境变量

1. 在项目根目录下，复制 .env.sample 文件为 .env：

   cp.env.sample.env
   

2. 使用文本编辑器打开 .env 文件，配置以下重要环境变量：

   • DATABASE_URL：
     • 格式为 postgresql://user:password@localhost:5432/hoarder（示例）。
     • 将 user 替换为您在安装 PostgreSQL 时设置的用户名，password 替换为相应的密码，localhost 如果数据库在本地运行，可保持不变，5432 是 PostgreSQL 默认端口，如果您修改了端口，需要使用修改后的端口号，hoarder 是数据库名称，您可以根据需要修改。
   • MEILISEARCH_HOST：
     • 设置为 http://localhost:7700（如果 Meilisearch 在本地以默认配置运行）。如果您在不同的主机或端口上运行 Meilisearch，需要相应地修改此地址。
   • MEILISEARCH_API_KEY：
     • 如果 Meilisearch 启用了 API 密钥验证，在此处输入您的 API 密钥。如果没有启用，可以留空。
   • 其他环境变量（如身份验证相关、AI 服务相关等）：
     • 根据项目文档的详细说明进行配置。这些变量可能涉及到应用程序的高级功能，如与外部 AI 服务的连接参数、用户认证方式等。

1.4.6- （六）初始化数据库

1. 在项目目录下的终端中，运行以下命令执行数据库迁移：

   pnpm prisma migrate dev
   

   此命令将根据项目中的数据库迁移脚本创建和更新数据库表结构，确保数据库为应用程序的运行做好准备。

1.4.7- （七）启动应用程序

1. 在终端中运行以下命令启动应用程序的开发服务器：

   pnpm dev
   

2. 启动成功后，打开浏览器，访问 http://localhost:3000（默认端口）。如果您在 .env 文件中修改了端口号，请使用修改后的端口访问。此时，您应该可以看到 Hoarder 应用程序的界面。

1.5- 三、使用指南

1.5.1- （一）用户注册与登录

1. 注册账号
   • 打开浏览器并访问应用程序地址（如 http://localhost:3000）。
   • 在首页上，找到 " 注册 " 按钮并点击。
   • 在注册页面中，填写用户名、有效的电子邮件地址和密码。确保密码强度符合安全要求（通常包含字母、数字和特殊字符）。
   • 填写完成后，点击 " 注册 " 按钮完成账号创建过程。
2. 登录账号
   • 在应用程序首页，点击 " 登录 " 按钮。
   • 在登录页面中，输入您注册时使用的电子邮件地址和密码。
   • 点击 " 登录 " 按钮，成功登录后，您将进入应用程序的主界面。

1.5.2- （二）书签管理

1. 添加书签
   • 通过粘贴链接添加：
     • 在应用程序界面中，点击 " 添加书签 " 按钮（通常以 “+” 号图标表示）。
     • 在弹出的添加书签窗口中，将您想要保存的链接粘贴到指定的输入框中。
     • 应用程序会自动获取链接的标题、描述信息（如果有），以及可能的图像预览（如果链接页面包含图像）。
     • 根据需要，可以对自动获取的信息进行编辑和修改。
     • 点击 " 保存 " 按钮完成书签添加。
   • 编写笔记添加：
     • 点击 " 添加书签 " 按钮后，在输入框中直接输入文字笔记内容。
     • 可以为笔记添加标题（如果需要），并设置其他相关属性（如标签等，部分功能可能在后续步骤中自动生成或手动添加）。
     • 点击 " 保存 " 按钮保存笔记作为书签。
   • 拖放图像添加：
     • 找到应用程序界面中用于添加图像书签的区域（可能有明确的图像添加提示）。
     • 将本地的图像文件（支持常见的图像格式，如 JPEG、PNG 等）直接拖放到该区域。
     • 应用程序会对图像进行处理（可能包括提取图像中的文本信息，取决于是否启用 OCR 功能）。
     • 添加相关的标题和描述信息（如果需要），然后点击 " 保存 " 按钮完成图像书签的添加。
2. 查看书签列表
   • 登录成功后，默认会显示书签列表页面（如果不是，可以在导航菜单中找到 " 书签 " 选项并点击进入）。
   • 在这里，您可以看到所有已保存的书签的简要信息，包括标题、部分内容预览（如链接的标题或笔记的开头部分）和可能的图像预览（如果是图像书签）。
3. 编辑书签
   • 在书签列表中，找到想要编辑的书签条目。
   • 每个书签条目通常会有一个编辑按钮（一般以铅笔图标表示），点击该按钮进入编辑模式。
   • 在编辑页面中，可以修改书签的各种信息，如标题、链接（如果是链接书签）、笔记内容、相关标签等。
   • 修改完成后，点击 " 保存 " 按钮保存更改。
4. 删除书签
   • 在书签列表中，找到要删除的书签条目。
   • 每个书签条目通常有一个删除按钮（一般以垃圾桶图标表示），点击该按钮。
   • 系统会提示您确认删除操作，点击 " 确认 " 后，书签将被永久删除。
5. 分类书签
   • 创建书签列表：
     • 点击页面上的 " 列表 " 选项卡（如果有）。
     • 在列表页面中，点击 " 创建新列表 " 按钮。
     • 输入新列表的名称（例如 " 工作相关 “、” 学习资料 " 等），然后点击 " 创建 " 按钮完成新列表的创建。
   • 将书签添加到列表：
     • 在编辑书签（如上述编辑书签步骤）时，会有一个选项用于选择将书签添加到哪个列表中。
     • 从下拉菜单中选择相应的列表名称，然后保存书签，书签将被分类到指定的列表中。
     • 您也可以在书签列表页面中，通过批量操作（如果支持）将多个书签添加到同一个列表中。

1.5.3- （三）搜索书签

1. 在应用程序界面的顶部，通常会有一个明显的搜索框。
2. 在搜索框中输入关键词（可以是书签的标题、内容中的单词、笔记中的短语、标签等）。
3. 应用程序会立即对所有书签进行全文搜索，并在下方显示与关键词相关的书签结果列表。您可以点击结果列表中的书签条目查看详细信息。

1.5.4- （四）AI 自动标记功能

1. 当您添加书签或编辑书签时，应用程序会在后台自动使用 AI 技术为书签添加相关标签。
2. 在书签的详细信息页面中，您可以查看自动生成的标签。这些标签可以帮助您更好地分类和检索书签。
3. 如果您对自动生成的标签不满意，可以手动编辑或添加新的标签（在编辑书签页面中进行操作）。

1.5.5- （五）其他功能使用

1. OCR 功能（如果支持）
   • 对于添加的图像书签，应用程序可能会尝试使用 OCR（光学字符识别）技术提取图像中的文本信息。
   • 提取的文本将可用于搜索和其他相关操作。您可以在图像书签的详细信息页面中查看是否成功提取了文本以及提取的内容。
2. 浏览器插件（如果安装）
   • 如果您安装了 Hoarder 的浏览器插件（支持 Chrome、Firefox 等主流浏览器，具体安装方法可在项目文档或应用程序中查找）。
   • 在浏览网页时，当您想要保存当前页面为书签时，可以点击浏览器插件图标。
   • 插件会自动获取页面的相关信息（如标题、链接、部分内容）并将其保存到 Hoarder 应用程序中，操作过程非常便捷。
3. RSS 订阅自动保存（如果配置）
   • 如果您在应用程序中配置了 RSS 订阅（具体配置方法参考项目文档中的相关章节）。
   • 应用程序会按照设定的时间间隔自动从订阅源中获取新内容，并将其保存为书签。
   • 新保存的书签会出现在书签列表中，可以按照常规的书签管理方式进行处理。

1.6- 四、常见问题与解决方法

1. 安装过程中出现依赖项安装失败问题
   • 检查网络连接是否正常，确保能够正常访问 npm 或 pnpm 的官方仓库。
   • 如果是特定依赖项安装失败，可以尝试手动安装该依赖项。例如，如果某个 Node.js 模块安装失败，可以在终端中使用 npm install <module-name> 或 pnpm install <module-name>（将 <module-name> 替换为实际的模块名称）命令进行手动安装。
   • 有些依赖项可能需要特定的操作系统环境或其他软件的支持。检查相关依赖项的文档，确认是否满足其安装条件。
2. 数据库连接问题
   • 确认 DATABASE_URL 环境变量的配置是否正确，包括用户名、密码、主机地址和端口号等信息。
   • 检查数据库服务是否正常启动，可以使用数据库管理工具连接到数据库服务器进行检查。
   • 如果数据库需要特定的权限设置，确保应用程序使用的数据库用户具有足够的权限（如创建表、插入数据等权限）。
3. 应用程序启动后无法正常访问问题
   • 检查应用程序启动时是否有报错信息。如果有报错信息，根据报错内容查找问题原因。常见的问题可能包括端口被占用（尝试修改应用程序的运行端口）、缺少某些关键配置等。
   • 确认防火墙或安全软件是否阻止了应用程序的访问。如果是，可以将应用程序添加到信任列表或允许访问的列表中。
4. 搜索功能不准确问题
   • 检查是否有新添加的书签尚未被索引。有些情况下，全文搜索索引可能需要一些时间来更新。您可以尝试等待一段时间后再次进行搜索。
   • 确认搜索关键词的输入是否正确。如果关键词包含特殊字符或拼写错误，可能会导致搜索结果不准确。
   • 如果问题仍然存在，可能是 Meilisearch 的配置问题。检查 MEILISEARCH_HOST 和 MEILISEARCH_API_KEY 等环境变量的配置，以及 Meilisearch 服务本身是否正常运行。