Turtl 0.1.3 介绍与选型指南

目标：回答「Turtl 是什么、加密与同步架构如何、能做什么、适合什么场景、与同类产品如何取舍」，为是否采用 Turtl 自建端到端加密笔记服务提供选型依据。本文内容基于官方 GitHub 组织、官网与 server 仓库源码联网溯源，查询日期 2026-11-02；配套部署与接口实测见 《Turtl 0.1.3 Docker Compose 部署指南》、《Turtl 0.1.3 REST API 使用详解》。

一、环境信息

• 溯源对象：Turtl 开源项目（GitHub 组织 turtl，官网 turtl.it，同步后端仓库 turtl/server）
• 溯源渠道：GitHub 组织仓库列表与 README、server 仓库提交订阅源（server-commits.atom）与 Releases 订阅源（releases.atom）、shields.io 星数徽章、Docker Hub 检索、server 源码（package.json、Dockerfile、helpers/、models/）
• 查询日期：2026-11-02
• 后端版本：0.1.3（server/package.json 的 version 字段，仓库无 Release tag）
• 许可证：AGPL-3.0（server/package.json 的 license 字段）

二、软件概述

Turtl 是一款**端到端加密（end-to-end encryption, E2EE）**的开源笔记程序，覆盖网页、桌面、移动三类客户端：笔记在客户端加密后才发给服务器，服务器（以及服务器管理员）只存密文，看不到笔记明文。官方对 server 职责的界定（README 原文归纳）是四件事：账号管理（注册/登录/删除）、数据存储、同步、权限与共享。

技术栈与沿革（来源：官方仓库 README 与源码，查询日期 2026-11-02）：

• 后端为 Node.js（Express），数据库要求 PostgreSQL >= 9.6（README「Running the server」明示）；核心逻辑另有 JS（turtl/js）与 Rust（turtl/core、turtl/core-rs）两套实现。
• 早期架构以 CouchDB + gatekeeper 组件做同步后端；当前 turtl 组织下已无 gatekeeper 仓库，新一代 server（0.1.x）用自研同步协议取代——本文以新架构 0.1.3 为准。
• 维护状态：server 仓库最后一次提交为 2021-03-05（server-commits.atom 取证），从未发布 GitHub Release（releases.atom 为空），公共制品仓库未提供官方预构建制品（Docker Hub turtl 命名空间检索命中 0）。属于休眠但功能链路完整的项目，可部署跑通（见 《Turtl 0.1.3 Docker Compose 部署指南》）。

组织内主要仓库与星数（shields.io，查询日期 2026-11-02）：

💡 说明：单看 server 星数（631）不大，评估此类项目应看整个组织的仓库矩阵与功能完整度，而非单一仓库热度。

三、核心架构

Turtl 是「多端客户端 + 单一同步服务器 + PostgreSQL」结构，客户端承担全部加解密，服务器只做密文存取与同步日志：

客户端(web/desktop/mobile)
  │  明文→客户端加密("iv:ciphertext")→HTTPS
  ▼
turtl/server (Node.js/Express, 端口 8181)
  ├─ users 控制器   账号/认证/确认/删除
  ├─ sync 控制器    增量与全量同步(核心)
  ├─ spaces 控制器  空间成员/邀请/角色
  ├─ files 控制器   附件(本地盘或 S3)
  └─ health 等      健康检查/反馈/错误日志
  ▼
PostgreSQL >= 9.6(只存密文与元数据)

加密模型（源码事实：models/user.js、helpers/auth.js）：

• 全部业务数据以 body 字段承载，格式为 iv:ciphertext（两段 base64、冒号分隔），由客户端加密产生，服务器原样存取、不做任何解析。
• 登录凭据不是用户密码：客户端生成一个不透明 auth blob 作为凭据，服务器落库的是 pbkdf2(auth, app.secure_hash_salt, 2 次迭代, base64)。源码注释明确说明只迭代 2 次是有意为之——blob 本身是高熵随机值，这层哈希只为防止「拖库即得凭据」，不承担口令抗爆破职责。
• app.secure_hash_salt 同时用于服务端私有数据的 PBKDF2 加密保护（100000 次迭代），是全局机密：更换盐值后所有既有账号的 auth 校验立即失效。
• 共享密钥：同步对象的 keys 数组承载空间共享的密钥封装（如 {"type":"link","priv":"<封装密钥>","to":"<公钥>"}），接收方以自己的私钥（注册时上传的 pubkey）解开，从而多人可共读同一空间而服务器无从参与解密。

💡 技术拓展：加密笔记的存储模型不止「端到端加密」一种，常见三类对比——

模型	服务器可见性	代表产品	取舍
零知识 E2EE（客户端加密，服务器只存密文）	只见密文与不透明凭据	Turtl、Standard Notes	托管方无法读取/搜索；忘密钥即数据不可恢复，密钥管理复杂
服务端加密（SSE）	服务器持有密钥	普通网盘/数据库落盘加密	运维简单，但托管方可解密
口令派生密钥 + 服务端校验	存 KDF 哈希	Joplin 端到端加密模式	折中方案，安全性取决于口令强度

Turtl 取第一类：明文与密钥全在客户端，服务器是「哑密文管道」，这也是其选型价值与运维风险（不可找回）的共同来源。

数据模型（源码事实：models/space.js、models/sync.js）：user → space（空间，成员带 owner/editor/commenter/viewer 四种角色）→ board（面板）→ note（笔记）；附件独立走文件通道存本地盘或 S3。同步模型：服务器在 sync 表维护单调递增的同步日志，客户端每次推送产生新 sync_id，之后以 GET /sync?sync_id=N 拉增量、首次登录以 GET /sync/full 拉全量。

四、功能特性

五、快速开始

server 仓库自带官方部署件（README「Running the server (via docker-compose)」）：一个 Dockerfile（node:11-alpine 基座）+ 一个 docker-compose.yml，一条 docker-compose up 同时起 server 与 PostgreSQL：

version: '2.1'

services:
  turtl-server:
    build:
      context: ./
    environment:
      TURTL_DB_HOST: postgres-db
      TURTL_DB_PORT: 5432
      TURTL_DB_DATABASE: turtl
      TURTL_DB_USER: turtl
      TURTL_DB_PASSWORD: turtl
      TURTL_APP_SECURE_HASH_SALT: abuHassN892MMn
    ports:
      - 8181:8181
    depends_on:
      postgres-db:
        condition: service_healthy

  postgres-db:
    image: postgres:11-alpine
    environment:
      POSTGRES_PASSWORD: turtl
      POSTGRES_USER: turtl
      POSTGRES_DB: turtl
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U turtl"]
      interval: 10s
      timeout: 5s
      retries: 5

⚠️ 注意：官方 README 同时警告——该 compose 未配数据卷，「cancel 之后数据即丢」；生产必须为 PostgreSQL 加卷，并把 TURTL_APP_SECURE_HASH_SALT 换成自己的长随机值。《Turtl 0.1.3 Docker Compose 部署指南》 给出了生产化改写与全流程实测。

不用 Docker 的裸机形态（官方 README「Running the server」）：

git clone https://github.com/turtl/server
cd server/
npm install
cp config/config.yaml.default config/config.yaml   # 改 db.* 与 app.secure_hash_salt
./scripts/init-db.sh
node server.js

前置要求 Node >= 8、PostgreSQL >= 9.6 及专用库/账号。

六、适用场景与限制

适用场景：

• 对数据主权要求高的个人/小团队笔记：零知识架构，服务器管理员读不出内容。
• 内网自托管：单同步服务 + PostgreSQL 即可跑通全部功能，API 面小且清晰（见 《Turtl 0.1.3 REST API 使用详解》）。
• 端到端加密同步协议的研读样本：sync/space/keys 模型规整，适合学习「服务器不可见内容」的共享密钥封装设计。

限制与不适用（选型红线）：

• 维护休眠：server 自 2021-03 无提交、无 Release、未提供官方预构建制品；官方构建定义基于 node:11-alpine，该运行时已 EOL，安全补丁需自行维护或更换基座重新构建。
• 无口令找回：auth blob 由客户端生成，服务器不知道任何「密码」；客户端密钥丢失即数据永久不可读。
• 账号确认依赖邮件插件：email 插件默认关闭，未配 SMTP 时新账号长期 confirmed=false，分享/邀请受限。
• 版本固定只能靠 commit：无 tag 无 releases，锁版本需自行记录 commit 哈希。
• 客户端生态老旧：桌面端基于当年 Electron/NW.js 技术栈，移动客户端长期未更新；若需要开箱即用的现代客户端，应看活跃维护的同类产品。

七、同类选型对比

选型建议：

• 必须「零知识 E2EE + 全端客户端 + 自建同步服务器」，且能接受长期自维护一个休眠项目 → Turtl 架构最纯粹，部署与 API 面都小（本专栏四篇：选型、部署、配置、REST API 可完整覆盖落地）。
• 要 E2EE 笔记但不想自建服务器、要活跃维护 → Joplin（同步到任意现成存储）。
• 要商业级零知识笔记、可自托管服务端 → Standard Notes。
• 不需要 E2EE、更重个人知识库结构与双向链接 → Trilium（选社区延续版 TriliumNext）。

八、参考链接

• 官方组织：https://github.com/turtl
• server 仓库：https://github.com/turtl/server （README/Dockerfile/commits.atom/releases.atom，查询日期 2026-11-02）
• 官网：https://turtl.it
• 桌面客户端：https://github.com/turtl/desktop
• Web 客户端：https://github.com/turtl/js
• 同类自托管笔记选型对照：《Standard Notes 介绍与选型指南》、《Joplin 介绍与选型指南》