一、Crumbs介绍

1.1 Crumbs项目简介

Crumbs 是一款由 Bretzel 应用宇宙推出的、支持自托管且优先离线使用的笔记应用。它专为注重隐私安全的用户设计，无论是记录日常灵感还是管理个人知识库，都能让你在完全掌控自己数据的前提下，享受流畅、安全的笔记体验。

1.2 Crumbs主要特点

• 丰富的笔记体验：全面支持 Markdown 语法、待办清单与图片附件，并提供多达 12 种配色主题随心切换。
• 高效的组织管理：支持通过 #标签 分类、置顶重要笔记，以及归档和回收站功能，让信息管理井井有条。
• 强大的全文检索：内置全文搜索引擎，能够快速精准地在笔记标题、正文内容及标签中查找所需信息。
• 完善的版本控制：自动记录笔记的版本历史，支持随时浏览并一键还原到之前的任意修改版本。
• 便捷的笔记共享：支持在同一实例内与其他用户安全地分享笔记，轻松实现信息的协作与互通。
• 灵活的消息通知：提供可选的 SMTP 邮件服务，及时推送笔记共享、安全警报及账户动态等重要通知。
• 出色的离线能力：作为 PWA 应用支持一键安装，利用 IndexedDB 结合 LWW CRDT 技术实现完美的离线使用与同步。
• 强大的 AI 扩展：内置 MCP 服务器，允许 Claude Code 等 AI 助手直接接入并智能化管理你的笔记内容。
• 安全的多用户认证：采用 Argon2 算法保障账户安全，并支持 Google、GitHub 及 OIDC 等第三方 OAuth/SSO 登录。
• 极简的部署方式：提供高度容器化的支持，仅需一条 Docker 命令即可快速完成私有化环境的搭建与运行。

二、本次实践规划

2.1 本地环境规划

本次实践为个人测试环境，操作系统版本为 Ubuntu 24.04.2 LTS。

2.2 本次实践介绍

1.本次实践部署环境为个人测试环境，生产环境请谨慎；
2.在Docker环境下部署Crumbs自托管笔记应用。

三、本地环境检查

3.1 检查Docker服务状态

检查Docker服务是否正常运行，确保Docker正常运行。

root@jeven:~# systemctl status docker
● docker.service - Docker Application Container Engine
     Loaded: loaded (/usr/lib/systemd/system/docker.service; enabled; preset: enabled)
     Active: active (running) since Thu 2026-02-05 00:27:40 CST; 1s ago
TriggeredBy: ● docker.socket
       Docs: https://docs.docker.com
   Main PID: 841698 (dockerd)
      Tasks: 65
     Memory: 73.5M (peak: 77.1M)
        CPU: 975ms
     CGroup: /system.slice/docker.service

3.2 检查Docker版本

检查Docker版本

root@jeven:~# docker -v
Docker version 28.5.0, build 887030f

3.3 检查docker compose 版本

检查Docker compose版本，确保2.0以上版本。

root@jeven:~# docker compose version
Docker Compose version v2.39.4

四、拉取Crumbs镜像

下载Crumbs镜像，执行以下命令：

root@jeven:~# docker pull ghcr.io/bretzel-app/crumbs:0.28.3
0.28.3: Pulling from bretzel-app/crumbs
ff86ea2e5edc: Already exists
82dd35b9bc5d: Pull complete
d0513e5eafd9: Pull complete
539f12fec8ec: Pull complete
bba7366a523c: Pull complete
d80b5cf71a9f: Pull complete
1e3933667442: Pull complete
ecd657a7617b: Pull complete
eac099b9d35d: Pull complete
3154080fdf5b: Pull complete
bfc6e36d6f25: Pull complete
Digest: sha256:23cccfb2cbd018e2d671c7f1094becd6a3bcaf5de5fe1bb5460557bc2f1f459e
Status: Downloaded newer image for ghcr.io/bretzel-app/crumbs:0.28.3
ghcr.io/bretzel-app/crumbs:0.28.3

五、部署Crumbs服务

5.1 创建部署目录

• 创建部署目录

mkdir -p /data/crumbs/data  && cd /data/crumbs

• 在测试环境中，为了方便操作，我们直接为挂载目录设置了完全权限。但在生产环境中，请务必根据实际安全需求，配置更精细、严格的权限控制方案。

chmod -R 777   /data/crumbs

5.2 docker-cli方式部署（可选）

如果想要使用docker-cli方式部署，可参考以下命令部署。（可选）

docker run -d \
  --name=crumbs \
  --restart=unless-stopped \
  -p 5660:3000 \
  -v $(pwd)/data:/data \
 ghcr.io/bretzel-app/crumbs:0.28.3

5.3 创建Crumbs容器

本次实践我们采用 Docker Compose 方式进行部署，这也是我推荐的方式。首先我们需要创建并编辑 docker-compose.yaml 文件，请注意宿主机映射端口可根据您的实际情况自行设置，务必避免端口冲突。

vim docker-compose.yaml

version: '3'

services:
  crumbs:
    image: ghcr.io/bretzel-app/crumbs:0.28.3
    container_name: crumbs
    restart: always
    ports:
      - "5660:3000"
    volumes:
      - /data/crumbs/data:/data

执行以下命令，创建Crumbs容器。

docker compose up -d

5.4 查看Crumbs容器状态

检查Crumbs容器运行状态，确保Crumbs容器正常启动。

root@jeven:/data/crumbs# docker compose ps
WARN[0000] /data/crumbs/docker-compose.yaml: the attribute `version` is obsolete, it will be ignored, please remove it to avoid potential confusion
NAME      IMAGE                               COMMAND                   SERVICE   CREATED          STATUS                    PORTS
crumbs    ghcr.io/bretzel-app/crumbs:0.28.3   "docker-entrypoint.s…"   crumbs    29 seconds ago   Up 28 seconds (healthy)   0.0.0.0:5660->3000/tcp, [::]:5660->3000/tcp

5.5 检查Crumbs容器日志

检查容器运行日志，确保Crumbs服务正常运行。

docker compose logs

六、访问Crumbs服务

6.1 访问Crumbs初始页

浏览器地址： http://<个人的服务器IP>:5660，访问Crumbs初始页。如果无法访问，请确保宿主机的防火墙已关闭或已放行相关端口，对于云服务器还需配置相应的安全组规则。

6.2 创建账号

自行填写账号信息，创建登录账号。

6.3 编辑笔记

编辑笔记内容后，效果如下所示：

七、总结

本次实践成功使用 Docker 完成了 Crumbs 自托管笔记应用的部署，充分体验了其轻量级与隐私优先的特性。通过简单的容器化操作，我们不仅实现了数据的本地化存储，还有效保障了个人知识资产的安全与独立。Crumbs 简洁易用的界面配合灵活的 Docker 部署方式，使其成为构建个人专属知识库的理想选择。