
Hoarder
用 Docker 自建 Hoarder 书签与笔记服务并完成初始配置
Hoarder 是一款可自托管的开源书签与笔记应用,能把链接、笔记和图片集中存放,并支持全文搜索、标签与列表整理。本文从零开始,用 Docker Compose 部署 Hoarder,配置密钥与访问地址,注册首个管理员账号,并说明日常启停与后台任务查看方法。
Hoarder 是一款开源、可自托管的书签与笔记应用,目标是把链接、随手笔记和图片集中到一个地方管理。它会在保存链接时自动抓取标题、描述和配图,支持全文搜索,还可以借助 AI 自动生成标签;书签能打标签、归入自定义列表,并能在瀑布流、网格、列表三种视图之间切换。它提供浏览器扩展(Chrome 插件与 Firefox 附加组件)以及 iOS、Android 客户端,方便随手收藏。适合希望把收藏数据握在自己手里、又不想在多个工具之间来回切换的个人用户或小团队。本文用 Docker Compose 完成部署与初始配置,涉及镜像版本、功能与配额的信息请以官网当前说明为准。如果你还想对比其他自托管方案,可以看看站内的 Hoarder 工具页。
准备工作
在动手之前,先确认下面几项条件都已满足,否则后面的步骤容易卡住。
- Docker 与 Docker Compose:Hoarder 通过容器方式运行,宿主机必须已安装 Docker 和 Docker Compose。可以用
docker --version与docker compose version检查;如果命令不存在,先按所用发行版的官方方式安装 Docker Engine 与 Compose 插件。 - 操作系统:Linux、Windows、macOS 都可以,既可以跑在本地机器上,也可以跑在云服务器上。不同系统上 Docker 的安装方式不同,但 Compose 文件本身是通用的。
- 一个可访问的地址:本地使用时用
http://localhost:3000即可;部署在云服务器上时,需要准备服务器的 IP 或域名,并确保对应端口在防火墙或安全组中放行。 - (可选)OpenAI API Key:只有希望启用 AI 自动打标签时才需要。不配置也能正常使用书签、笔记、图片、标签、列表和全文搜索等核心功能。
- (可选)openssl:用于生成随机的密钥字符串。大多数 Linux 发行版自带,macOS 也自带;Windows 上可以在 Git Bash 或 WSL 中执行。
另外建议提前想清楚数据存放位置。Hoarder 的容器会把数据写入挂载卷,默认位置在 Compose 文件里定义;如果希望把数据放到独立磁盘或备份目录,最好在第一次启动前就改好,避免运行一段时间后再迁移。
操作步骤
第一步:创建项目目录
为 Hoarder 单独建一个目录,用来存放 Compose 文件和 .env 环境变量文件。这样后续升级、备份、停止服务时都在同一个位置操作。
mkdir ~/hoarder/ && cd ~/hoarder/
进入目录后,后续所有命令都在这个目录下执行。
第二步:获取 docker compose 文件
把 Hoarder 的 Compose 文件下载到刚创建的目录中。文件里定义了 Web 服务、数据存储、全文搜索等组件以及它们之间的依赖关系,通常不需要逐项修改就能启动。
wget <compose 文件地址>
如果宿主机上没有 wget,用 curl -O 加同样的地址也可以。下载完成后可以用 ls 确认文件已存在,再用编辑器打开浏览一遍,重点看两处:数据卷的挂载路径,以及环境变量部分。
第三步:按需调整数据卷与 AI 配置
这一步是可选的,但建议至少检查一次。
- 修改数据卷位置:如果默认的卷路径所在分区空间不足,或者你希望把数据放到专门的备份盘,用任意文本编辑器打开 Compose 文件,把卷的宿主机路径改成目标目录。改完保存即可,不需要改动容器内的路径。
- 启用 AI 自动打标签:在 Compose 文件的 environment 段中填入 OpenAI API Key。配置之后,保存书签时可以由模型自动推断标签;不填则只能手动打标签。是否启用、按什么计费,请以 OpenAI 官网当前信息为准。
第四步:创建 .env 文件
在同一个目录下新建名为 .env 的文件,写入以下三个变量:
HOARDER_VERSION=latest
NEXTAUTH_SECRET=2fjLEIJKKl016/nJmlZnp2UpvaFCccwMkVan1ufigxqsuOtD
MEILI_MASTER_KEY=tZcjeGqwy8DEu7GqxbBupvLexsSSEit7FchT4WnAmi0ewxPb
NEXTAUTH_URL=
三个变量的含义如下:
HOARDER_VERSION:镜像版本标签,示例中为latest。生产环境如果希望升级可控,可以改成具体的版本号,具体可用标签以官网当前信息为准。NEXTAUTH_SECRET:用于会话与令牌签名的密钥,必须替换成自己生成的值,不要直接使用示例字符串。MEILI_MASTER_KEY:全文搜索组件的管理密钥,同样需要替换成自己生成的值。NEXTAUTH_URL:应用对外访问的完整地址。本地部署填http://localhost:3000;部署在云服务器上时,必须改成服务器的实际地址,例如http://你的服务器IP:3000或对应的域名。这一项填错会导致登录后跳转异常。
生成随机密钥可以用 openssl:
openssl rand -base64 36
执行两次,分别把输出填入 NEXTAUTH_SECRET 和 MEILI_MASTER_KEY。注意 .env 里不要留多余的空格或引号,变量名与等号之间也不要加空格。
第五步:启动服务
在项目目录下执行:
docker compose up -d
-d 表示后台运行。首次执行会拉取镜像,耗时取决于网络状况。命令返回后可以用下面的命令确认容器状态:
docker compose ps
如果某个容器反复重启,先看日志定位原因:
docker compose logs -f
常见原因是端口被占用、数据卷路径没有写权限,或者 .env 中的变量缺失。
第六步:注册首个账号
服务启动后,用浏览器打开 NEXTAUTH_URL 中配置的地址,默认是 http://localhost:3000。首次访问会进入注册页面,填写姓名、邮箱、密码并确认密码即可完成注册。
需要注意:第一个注册的账号会被指定为管理员。因此部署完成后应尽快完成注册,避免服务暴露在公网时被他人抢先创建管理员账号。注册成功后会自动跳转到仪表盘。
第七步:熟悉仪表盘与常用设置
进入仪表盘后就可以开始添加书签链接、写简单笔记、保存图片,并给它们打标签或加入列表。默认布局是瀑布流(masonry),可以切换成网格或列表视图。
两个值得先看的页面:
- Admin 页面:查看用户数量、书签数量、服务器版本,以及后台任务的状态,包括抓取(crawling)、索引(indexing)和推断(inference)。如果新保存的书签标题或配图迟迟没有出现,或者搜索不到刚存的内容,先来这里确认对应任务是否还在排队或已经失败。
- Settings 页面:修改当前账号的密码,以及生成新的 API Key。API Key 供移动端或第三方客户端调用接口时使用。
第八步:停止与重新启动
需要停止服务时,回到项目目录执行:
cd ~/hoarder/
docker compose down
该命令会停止并移除容器,但不会删除数据卷,数据仍然保留。之后在同一目录执行 docker compose up -d 即可恢复运行。如果确实要清空数据,需要额外删除对应的卷,这一步不可逆,操作前请先备份。
一个完整示例
下面把前面的步骤串成一次从零开始的部署,假设部署在本地 Linux 机器上,使用默认端口 3000,并启用 AI 自动打标签。
1. 建目录并进入
mkdir ~/hoarder/ && cd ~/hoarder/
2. 下载 Compose 文件
wget <compose 文件地址>
ls -l
3. 生成两个随机密钥
openssl rand -base64 36
openssl rand -base64 36
把两次输出分别记下来,下一步要用。
4. 写 .env 文件
HOARDER_VERSION=latest
NEXTAUTH_SECRET=<第一次生成的字符串>
MEILI_MASTER_KEY=<第二次生成的字符串>
NEXTAUTH_URL=http://localhost:3000
5. 在 Compose 文件的 environment 段填入 OpenAI API Key,用于自动打标签;如果暂时不需要,跳过这一步。
6. 启动并检查
docker compose up -d
docker compose ps
确认所有容器处于运行状态后,浏览器访问 http://localhost:3000。
7. 注册管理员账号,填写姓名、邮箱、密码,提交后进入仪表盘。
8. 验证功能:保存一个网页链接,观察标题、描述和配图是否被自动抓取;给它加一个标签并放入一个列表;再用搜索框搜索刚保存的内容,确认全文搜索可用。如果启用了 AI 打标签,稍等片刻后检查标签是否自动出现。
9. 需要停机时
cd ~/hoarder/
docker compose down
至此一次完整的部署、初始化与验证流程结束。
注意事项
- 首个账号即管理员:注册顺序决定权限归属。服务一旦可被公网访问,应第一时间完成注册,否则存在被他人抢先注册的风险。
- NEXTAUTH_URL 必须与实际访问地址一致:本地用 localhost,云服务器用服务器 IP 或域名。地址不一致时,登录后的跳转和回调可能失败。
- 密钥不要沿用示例值:
NEXTAUTH_SECRET与MEILI_MASTER_KEY都应使用openssl rand -base64 36自行生成,并妥善保管.env文件,不要提交到公开仓库。 - 自动抓取可能失败:链接的标题、描述和图片是自动获取的,带验证码的页面可能抓不到配图,此时需要手动编辑书签信息。
- 后台任务有延迟:抓取、索引和推断是异步执行的,新保存的内容可能不会立刻出现在搜索结果中。可以在 Admin 页面查看任务进度。
- AI 打标签依赖外部服务:只有配置了 OpenAI API Key 才会启用自动标签,且会产生相应的调用费用,具体价格与额度以 OpenAI 官网当前信息为准。不配置不影响其他功能。
- 移动端连接失败:如果手机客户端提示网络请求失败,优先检查
NEXTAUTH_URL是否填的是手机可以访问到的地址,以及服务器防火墙是否放行了对应端口;localhost 在手机上指向手机自身,不能用于连接电脑上的服务。 - 深色模式目前仅限 Web 端:浏览器扩展和移动客户端不提供深色模式。
- 版本与功能以官网为准:镜像标签、可用功能、客户端支持情况都可能随版本变化,部署前请核对官网当前信息。