Joplin 客户端与服务端

安装和更新

$ wget -O - https://raw.githubusercontent.com/laurent22/joplin/dev/Joplin_install_and_update.sh | bash

默认安装目录为 ~/.joplin/：

$ tree ~/.joplin/
/home/yewq/.joplin/
├── Joplin.AppImage
└── VERSION

1 directory, 2 files

• 【文档】Installation

由于从 Ubuntu 22.04 开始，不内置 libfuse2，而是升级到 libfuse3。但前者是 appimage 所需的。所一需要手动安装

$ sudo apt install libfuse2

• 【Issuse】App doesn't open on Ubuntu 22.04 #6612
• 【FAQ】Desktop application will not launch on Linux

自定义样式

userchrome.css：用于自定义 markdown 编辑器样式

userstyle.css：用于自定义 markdown 查看器和富文本编辑器样式

• 【博客】Introduction to customising Joplin (userchrome.css & userstyle.css)

侧边栏目录

nav.table-of-contents ul {     list-style-type: none;     margin-top: 0px;     margin-bottom: 0px; }

nav.table-of-contents>ul {      top: 5px;     right: 0px;     z-index: 99;          font-size: 12px;     position: fixed;     padding: 15px;          border-radius: 10px 0px 0px 10px;     margin: 0px;          overflow: hidden;     height: 90%;     width: 5px;     transition: .2s; }

nav.table-of-contents::after {     content: "[目录 - 请将你的鼠标移至程序的右边]";     color: black; }    

nav.table-of-contents>ul:hover {     background: #F8F8F8;     box-shadow: -5px 0px 10px 0px rgba(0,0,0,0.15);      width: 30%;     color: none;     overflow: scroll; }      

nav.table-of-contents>ul:hover::before {     content: "目录" }        

nav.table-of-contents>ul:hover li {     display: list-item; }          

nav.table-of-contents li {     display: none;     white-space: nowrap;     overflow: hidden;     margin: 0px;     padding: 0px; }  

#rendered-md {     width: 100%;     }

• 【博客】使用 VSCode + Joplin 作为笔记工具
• 【博客】Joplin如何实现炫酷的侧边栏目录-Joplin实现侧边栏目录实例

Anchor Link 笔记间引用

Copy Anchor Link：在渲染标题后添加可以直接复制的锚链接

• 【论坛】Internal URL/hyperlink
• 【主页】Copy Anchor Link

配置文件

配置文件位于 ~/.config/joplin-desktop 目录：

$ tree -L 1 ~/.config/joplin-desktop
/home/yewq/.config/joplin-desktop
├── ipc_secret_key.txt
├── lock
├── log-cross-app-ipc.txt    # 
├── profile-lyun             # A 用户配置和数据库
├── profiles.json            # 配置索引
├── profile-yewq             # B 用户配置和数据库
├── settings.json            # 全局配置
├── userstyle.css            # 已渲染 Markdown 的自定义样式表
└── window-state-prod.json   # 最后一次窗口状态，用于写一次应用启动时恢复

3 directories, 7 files

默认的配置文件 default，其会直接在 ~/.config/joplin-desktop 根目录中存储笔记数据库等文件。新建的配置文件是 profile-xxx，后者为随机 base64 编码字符。为了更具辨识，我删除了默认的配置文件和其相关文件，并将新建的配置修改其目录名为 profile-yewq，还需要修改 profiles.json，其中记录了目录名与前端显示名的映射：

$ vim ~/.config/joplin-desktop/profiles.json
{
	"version": 2,
	"currentProfileId": "yewq",
	"profiles": [
		{
			"name": "yewq",
			"id": "yewq"
		},
		{
			"name": "lyun",
			"id": "lyun"
		}
	]
}

配置文件目录中存储的文件：

$ tree -L 1 ~/.config/joplin-desktop/profile-yewq
/home/yewq/.config/joplin-desktop/profile-yewq
├── cache
├── database.sqlite            # 笔记数据库
├── deletion_log_20260103.txt
├── JoplinBackup
├── log.txt                    # 运行日志
├── resources                  # 附件
├── settings.json              # 用户设置
└── tmp

5 directories, 4 files

• Joplin Backup 插件的默认备份路径是 /home/yewq/JoplinBackup。在工具 ---> 选项 ---> Backup ---> 路径中修改为 /home/yewq/.config/joplin-desktop/profile-yewq/，即可将备份放置在个人配置目录下。插件的配置是记录在 database.sqlite 数据库中，每个用户间配置隔离。
• 日志文件为 /home/yewq/.config/joplin-desktop/profile-yewq/log.txt

目前配置方面还有些混乱，一部分配置放在用户配置中，一部分放在全局配置中。

Markdown editor: Render markup in editor：在 Markdown 编辑器中渲染除开光标所在行
Markdown editor: Render images：在 Markdown 编辑器中渲染图片
Markdown editor: Highlight active line：在 Markdown 编辑器中高亮光标所在行

Joplin Server

使用 Docker 部署 Joplin Server，默认使用 SQLite 数据库，容器中路径为 /home/joplin/packages/server/db-prod.sqlite，以挂载卷的形式持久化该数据库。

1. 由于只挂载宿主机上的一个文件，需要提前创建该文件，否则 docker 默认会创建同名文件夹；
2. joplin 容器中默认使用 joplin 用户，需要修改文件的访问权限；

$ sudo touch db-prod.sqlite
$ sudo chmod 666 db-prod.sqlite

### 需要指定 APP_BASE_URL 环境变量，joplin server 会验证来者的入口
$ sudo docker run \
--name joplin-server \
--restart always \
--publish 22300:22300 \
--volume /opt/joplin/db-prod.sqlite:/home/joplin/packages/server/db-prod.sqlite \
--env APP_BASE_URL=https://joplin.yewq.cn \
--detach \
joplin/server:latest

Nginx 反向代理配置：

$ sudo vim /etc/nginx/conf.d/joplin.conf
server {
    listen 80;
    server_name joplin.yewq.cn;

    client_max_body_size 0;

    location / {
        proxy_pass       http://127.0.0.1:22300;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
	
        proxy_request_buffering off;
        proxy_buffering  off;
    }
}

• 网址：https://joplin.yewq.cn
• 默认用户名：admin@localhost
• 默认密码：admin

Joplin Server 中存储笔记的 Item

笔记本：

{
    "deleted_time": 0,
    "user_data": "",
    "icon": "",
    "master_key_id": "",
    "is_shared": 0,
    "encryption_cipher_text": "",
    "user_updated_time": 1767422945839,
    "user_created_time": 1767422945839,
    "created_time": 1767422945839,
    "title": "aaa"
}

笔记：内容文本记录在 body 字段

{
    "deleted_time": 0,
    "user_data": "",
    "master_key_id": "",
    "conflict_original_id": "",
    "is_shared": 0,
    "markup_language": 1,
    "encryption_cipher_text": "",
    "user_updated_time": 1766414469671,
    "user_created_time": 1651913833026,
    "order": 0,
    "application_data": "",
    "source_application": "net.cozic.joplin-desktop",
    "source": "joplin-desktop",
    "todo_completed": 0,
    "todo_due": 0,
    "is_todo": 0,
    "source_url": "",
    "author": "",
    "altitude": "0.0000",
    "longitude": "112.98832703",
    "latitude": "28.19222069",
    "is_conflict": 0,
    "created_time": 1651913833026,
    "title": "joplin",
    "body": "<content>"
}

Revision：在 metadata_diff 中的 parent_id 记录了其父 Item 的 ID

{
    "created_time": 1766414595230,
    "encryption_cipher_text": "",
    "metadata_diff": "{\"new\":{\"id\":\"389734cea57f4d58a8c1e77852fa42af\",\"parent_id\":\"27210ee06aeb453a82324281bde69013\"}",
    "body_diff": "[{\"diffs\":[[1,\""]],\"start1\":0,\"start2\":0,\"length1\":0,\"length2\":4617}]",
    "title_diff": "[{\"diffs\":[[1,\"joplin\"]],\"start1\":0,\"start2\":0,\"length1\":0,\"length2\":6}]",
    "item_updated_time": 1766414469671,
    "item_id": "389734cea57f4d58a8c1e77852fa42af",
    "item_type": 1
}

编辑器

WYSIWYG：What You See Is What You Get，所见即所得；类似于 Microsoft Office Word 一样，所见的排版格式即打印出来的格式。Joplin 内置了富编辑器，可以实现直接编辑排版格式。

OCR

OCR：Optical Character Recognition，光学字符识别。在 Joplin 中，OCR 只会识别附件中的文本；右键附件，可以查看 OCR 识别出的文本。

Joplin 基于 Electron，而 Electron 又基于 Chromium 和 Node.js，所以其使用 JavaScript 语言编程。JavaScript 的 Tesseract.js 库提供了 OCR API，这一个基于 Tesseract 的移植库，其需要基于神经网络的模型文件 traineddata，不同的语言有不同的模型。

• 开启设置：工具 ---> 选项 ---> 常规 ---> 启用光学字符识别 (OCR)

• Joplin 可以配置模型文件下载路径：工具 ---> 选项 ---> 常规 ---> 显示高级选项 ---> OCR：语言数据 URL 或路径

• 【文档】Optical Character Recognition (OCR)

Joplin Plugins

1. 在线浏览插件，并获取插件名
2. 在插件中搜索插件名进行下载
3. 或者直接下载插件，从文件安装

• 【主页】Joplin Plugins

参考资料

1. 【主页】Joplin
2. 【文档】Joplin
3. 【源码】joplin

调整系统字体大小为小数倍后，TOC 目录在点击一次后，无法再次滚动

• 打开开发者工具，找到 TOC 的渲染 HTML：<nav class="table-of-contents">...</nav>
• 在元素中选择事件监听器，关闭 wheel joplin-container-content 的被动式监听后，可以发现滚动正常
• 应该和它主动关闭默认的滚动处理函数有关；
• 它判断如果是小数倍字体放大，会导致编辑器和阅读器滚动时不一致；所以自己编写了滚动函数来保持一致；源代码：joplin/packages/app-desktop/gui/note-viewer/index.html contentElement.addEventListener('wheel', webviewLib.logEnabledEventHandler

v3.1.20 版本编辑器样式变化

• Markdown 编辑器在 v3.0.x 和 v3.1.x 之间有所更改，一些 css 类也发生了更改

• 【论坛】Userchrome.css 尚未应用