Cleep 0.4.4 介绍与选型指南

目标：本篇面向想把「Google Keep 式便签」私有化到自家服务器或 NAS 的读者，基于 Cleep 官方 GitHub 仓库、Releases/CHANGELOG、GHCR 镜像仓库与 shields.io 徽章的联网溯源（查询日期 2026-10-25），讲清 Cleep 是什么、架构与功能边界如何、数据放在哪，并与 Joplin、Memos、Trilium、SiYuan、SilverBullet 等主流自托管笔记方案做量化选型对比，帮助读者快速判断「Cleep 适不适合我」。本篇为纯溯源认知篇，不含本地实测结论；部署、配置与运维的实测内容见本专栏后续篇章。

一、环境信息

本篇是联网溯源型认知篇，不依赖特定本机环境。文中全部事实均来自官方渠道，来源与查询日期逐条标注：

• 查询日期：2026-10-25
• 官方仓库：https://github.com/blindpassasjer/cleep （Apache-2.0 许可证）
• 官方镜像仓库（GHCR）：https://github.com/blindpassasjer/cleep/pkgs/container/cleep （ghcr.io/blindpassasjer/cleep）
• 官方在线演示（Demo）：https://blindpassasjer.github.io/cleep/ （纯浏览器内 mock 后端的静态演示）
• 变更日志：https://github.com/blindpassasjer/cleep/blob/main/CHANGELOG.md
• 社区热度取证方式：GitHub 星数通过 shields.io 徽章接口（img.shields.io/github/stars/...）取证，未直连 api.github.com 计数接口

当前官方渠道的版本信息（2026-10-25 实查）：

⚠️ 注意：GHCR 镜像目前只发布 latest 与 sha-<commit> 两类标签，没有 0.4.4 这样的版本号标签；latest 始终跟随 main 分支最新构建。生产环境建议按 digest 锁定镜像（见本专栏部署篇）。

二、软件概述

Cleep 是一款开源自托管的 Google Keep 替代品（官方自述「A self-hosted, open-source Google Keep alternative」，仓库描述「Yet another Google Keep clone」）。它把 Google Keep 的核心体验——彩色便签网格、清单（checklist）、置顶/归档/回收站、标签归类——完整搬到自己的服务器上：数据落在自己的 PostgreSQL 数据库与本地文件夹里，手机、平板、电脑通过浏览器（或安装为 PWA 应用）访问同一份数据，没有订阅费、没有广告、没有第三方读取你的笔记。

项目由个人开发者维护（GitHub 用户 blindpassasjer，挪威），2025 年 8 月首次公开，2026 年 9 月发布第一个打标签的版本 v0.2.0，随后一个半月内快速迭代到 v0.4.4（2026-10-02）。截至 2026-10-25，GitHub 星数 39，属于早期小众项目——功能完成度已经可用，但社区规模与成熟度远不及 Joplin/Memos 等老牌项目，选型时要把这一点计入风险（见第七章）。

一句话定位：如果你要的是「Google Keep 的界面与手感 + 数据完全在自己手里」，Cleep 是目前开源世界里还原度最高的选项之一；如果你要的是文档型知识库或 Markdown 本地文件流派，往下看第七章的对比表。

三、核心架构

Cleep 是一个典型的「单页应用 + 单体 API + 关系库」三层架构，组件极少、可审计性强（官方原话：「no framework lock-in, no managed cloud service required, just a small, readable codebase you can actually audit」）：

• 前端：React 18 + TypeScript + Vite 构建的单页应用，同时是可安装的 PWA（Service Worker 离线壳、「添加到主屏幕」）。官方另提供一个纯静态的 Demo 构建（VITE_DEMO=true），用浏览器 localStorage 模拟后端，部署在 GitHub Pages 上供试用。
• 后端：Node.js（>= 18）+ Express 单体 API 服务，会话（session）制认证，内置按 IP 的速率限制（登录、上传、链接预览三类独立限流器），安全响应头（CSP/X-Frame-Options/Referrer-Policy 等）默认全开。
• 数据库：PostgreSQL（官方 Compose 模板使用 postgres:16-alpine），通过 Drizzle ORM 访问；首次启动自动执行 schema 迁移，无需手工建库建表。v0.4.4 实测库内共 8 张表（users/sessions/notes/labels/note_labels/attachments/link_previews/app_settings）。
• 附件存储：照片、视频、录音等附件不进数据库，直接写入宿主机可见的普通文件夹（Compose 部署默认 ./data/attachments/<用户ID>/<笔记ID>/<文件>），可以像普通文件一样浏览、备份、迁移。

💡 技术拓展：自托管笔记的数据存储路线主要有三种——

路线	代表	特点	取舍
关系数据库	Cleep（PostgreSQL）、HedgeDoc	多用户、事务与权限模型成熟	多一个数据库组件
嵌入式 SQLite	Memos、SiYuan	单进程零依赖、备份即拷目录	多人并发能力弱
纯本地文件（Markdown）	SilverBullet、Joplin（文件同步）、Obsidian	数据可读性最强、配合任意同步盘	服务端协作能力弱

Cleep 选择了「PostgreSQL + 文件目录」组合：笔记正文入库、附件落盘，兼顾多用户与数据可搬运性。

四、功能特性

以下功能清单取自官方 README 与 CHANGELOG（2026-10-25 查询），标注 实测 的条目同时经本专栏部署实测验证：

• 便签与清单：彩色便签网格、置顶、归档、回收站（删除进回收站可恢复/撤销）；v0.4.0 起一条笔记内可混排文本段落与清单区块，清单可整note与文本互相转换；勾选完成的清单项自动下沉到底部；输入已勾选项时智能提示「恢复已有项」而不是新建重复项。
• 附件：照片、视频、以及直接从浏览器录音的音频附件（录音依赖 HTTPS 安全上下文）；附件按用户/笔记分目录落盘 （实测）。
• 链接预览卡片：笔记中的每个 URL 自动生成卡片（OpenGraph 图 → 页面主图 → favicon → 域名占位图的降级链），图片由 Cleep 服务端抓取并中转，严格 CSP 下也能渲染、外部站点看不到读者 IP；v0.4.4 专门修复了 IPv6 变形地址绕过 SSRF 防护等安全问题 （实测 /api/link-preview 返回标题/图片/站点名/favicon）。
• 标签与筛选：标签（Label/Collection）归类、多选批量操作、多标签 Any/All 组合筛选。
• 搜索：全库搜索（前端即时过滤）。
• 键盘快捷键：/ 搜索、c 新建便签、l 新建清单、g n/a/t 视图跳转、? 查看完整列表，手感对齐 Google Keep。
• 多用户：会话制登录；注册默认关闭，首个管理员账号由环境变量引导创建，其余账号由管理员在后台创建；管理员可将锁定用户重置密码（系统生成临时密码）（实测）。
• 单条笔记加密锁定：v0.4 起支持对单条笔记设置密码锁定（数据库中存 lockSalt/lockVerifier/lockIv/lockAuthTag/encryptedBlocks 字段，内容为加密存储）。
• 数据主权：设置页一键「导出全部数据」为 zip（notes.json + labels.json + attachments 目录）（实测）；支持从 Google Takeout 导出的 Keep zip 一键导入（标题、清单、颜色、标签、置顶/归档状态与媒体全部迁移，回收站条目跳过）。
• PWA：可安装到手机/桌面主屏幕，带离线应用壳；需要 HTTPS（或 localhost）安全上下文，纯 http://<nas-ip>:6169 下浏览器不注册 Service Worker（应用本体仍正常可用）。
• 一键部署：官方仓库自带 docker-compose.yml（Postgres + 应用两个服务）与 .env.example，docker compose up -d 即可；数据库迁移在启动时自动执行 （实测启动日志逐行见部署篇）。

已知限制（官方明示或实测确认）：

• UI 目前只有英文，无官方中文界面（README 无 i18n 机制；公众号原文亦指出「目前还不支持原生中文显示」）。
• 没有原生手机 App：移动端形态是「浏览器 + PWA」，与 Google Keep 的原生 App 体验有差距（推送提醒、系统级分享菜单等缺失）。
• 无公开注册/邀请链接：注册开关默认关闭，多用户靠管理员后台逐个建号，适合家庭/小团队，不适合开放注册场景。
• 提醒（Reminder）能力缺失：Google Keep 的时间/地点提醒在 Cleep 中没有对应物，待办提醒需求需另找方案。
• 项目极早期：v0.2.0（2026-09-08）才开始打版本标签，星数 39（2026-10-25），尚无第三方生态（无 Web Clipper、无 API 文档、无第三方客户端）。

五、快速开始（最小可用示例）

以下为官方 README 给出的最小部署流程（2026-10-25 查询自仓库首页；逐步实测回显见本专栏《Cleep 0.4.4 Docker Compose 部署指南》）：

# 1. 克隆官方仓库并准备环境变量文件
git clone https://github.com/blindpassasjer/cleep.git
cd cleep
cp .env.example .env

# 2. 编辑 .env，至少填入：
#    SESSION_SECRET（用 openssl rand -hex 32 生成）
#    POSTGRES_PASSWORD 与 DATABASE_URL（两处密码保持一致）
#    ADMIN_EMAIL / ADMIN_PASSWORD（可选，首启自动创建首个管理员账号）

# 3. 启动
docker compose up -d

# 4. 浏览器打开 http://<服务器IP>:6169 ，用上一步的管理员账号登录

部署后所有数据都在两个普通目录里：./data/postgres（库文件）与 ./data/attachments（附件），备份脚本 scripts/backup.sh（pg_dump + tar）与恢复脚本 scripts/restore.sh 随仓库附带。

六、适用场景与限制

适合：

• NAS/家庭服务器用户想要一个「全家共用的 Google Keep」：购物清单、家务待办、随手记，手机电脑平板打开网页就是同一份数据。
• 注重数据主权的个人用户：数据在自家 Postgres 与普通文件夹里，导出 zip 即可整体带走，Google Keep 迁移成本极低（官方导入器）。
• 想要一个小而可审计代码库的自托管爱好者：React + Express + Drizzle 单体架构，全仓代码量小，安全响应头/限流/SSRF 防护等默认内置。

不适合：

• 需要原生移动端体验（推送提醒、桌面小组件、系统分享）的用户——Cleep 只有 Web/PWA。
• 需要中文界面或对 UI 本地化有硬性要求的团队。
• 需要富文本知识库/双链/大纲的场景——那是 Trilium、SiYuan、SilverBullet 的领域（见下章对比）。
• 需要成熟生态与长期维护保障的生产团队——项目星数 39、个人维护、0.x 版本号，属于「可用但早期」。

七、同类选型对比

以下竞品均为本站已交付专栏的自托管笔记/知识库项目，关键维度数据为 2026-10-25 实查（星数来源 shields.io 徽章），「本站专栏」列给出对应介绍篇链接：

💡 表格解读：Cleep 的唯一「独占生态位」是 Google Keep 手感 + 官方 Keep 导入器——从 Google Keep 搬家到自托管，目前几乎没有第二个开源项目做得这么直接；代价是它最年轻、社区最小、无中文 UI、无原生 App。要闪念流选 Memos，要全平台原生客户端选 Joplin，要知识库选 Trilium/SiYuan/SilverBullet。

「如果…则…」选型建议：

• 如果你刚从 Google Keep 出来、想要一样的卡片墙和清单体验 → Cleep。
• 如果你主要记录碎片想法、以时间线回顾为主 → Memos。
• 如果你需要手机原生 App、桌面端离线、端到端加密同步 → Joplin。
• 如果你要构建个人知识库（层级树/双链/块引用）→ Trilium 或 SiYuan（中文支持更好）。
• 如果你信奉「我的笔记必须是一堆能直接用编辑器打开的 .md 文件」→ SilverBullet。

八、参考链接

• Cleep 官方仓库：https://github.com/blindpassasjer/cleep （查询日期 2026-10-25）
• Cleep Releases/Tags 页：https://github.com/blindpassasjer/cleep/tags （v0.4.4，2026-10-02）
• Cleep CHANGELOG：https://github.com/blindpassasjer/cleep/blob/main/CHANGELOG.md
• Cleep 在线演示：https://blindpassasjer.github.io/cleep/
• GHCR 镜像仓库：https://github.com/blindpassasjer/cleep/pkgs/container/cleep
• 星数取证（shields.io）：https://img.shields.io/github/stars/blindpassasjer/cleep.json
• Google Takeout（Keep 导出入口）：https://takeout.google.com/
• 本站相关专栏：《Memos 介绍与选型指南》、《Joplin 介绍与选型指南》、《Trilium 介绍与选型指南》、《SiYuan 3.8.8 介绍与选型指南》、《HedgeDoc 介绍与选型指南》