开发者进阶：自托管 Joplin Server 部署

适用版本：Joplin 3.x

笔记管理实验室 · 发布于 2026 年 10 月 14 日 · 更新于 2026 年 11 月 10 日

本教程给出命令行常用命令和 Docker 自托管的完整步骤。

一、安装命令行版

适用于 macOS、Linux、Windows（WSL）和 FreeBSD，通过 npm 安装。命令行版与桌面端共享同一套数据目录，但两者不建议同时打开同一配置，避免数据冲突；命令行版更适合服务器与 CI 环境。官方 CLI 文档见 Joplin 终端版文档。

NPM_CONFIG_PREFIX=~/.joplin-bin npm install --loglevel=error -g joplin
sudo ln -s ~/.joplin-bin/bin/joplin /usr/bin/joplin

二、高频命令与自动化

joplin use 我的笔记   # 切换笔记本
joplin mknote "测试"  # 新建笔记
joplin sync          # 同步
joplin export --format jex --path ./backup  # 导出备份

把这些命令写进 crontab 即可实现定时同步、自动备份；配合官方数据 API（Python/JavaScript）还能做 RSS 抓取、批量重命名等自动化。更多命令可以用 joplin help 查看，常用子命令包括 mkbook、mvnote、rmnote、tag 等。命令行版还支持 joplin export --format md 导出 Markdown，适合与其他工具联动。定时任务建议先手动执行一次确认输出正常，再写入 crontab；备份文件保留最近 30 天即可，避免磁盘占用过大。如果服务器在国内，自托管 Joplin Server 前请确认带宽与延迟可以接受；个人笔记同步流量不大，但数据库和文件卷建议使用 SSD，冷启动时会快很多。使用命令行时注意不要在同一台机器上同时打开桌面端和终端版编辑同一配置，以免数据冲突。

三、用 Docker 自托管 Joplin Server

git clone https://github.com/laurent22/joplin.git
cd joplin/packages/server
cp .env.example .env   # 修改数据库和管理员密码
docker compose up -d

服务默认监听 22300 端口，用 Nginx 或 Caddy 配置反向代理 + HTTPS；客户端同步目标选 Joplin Server，填入域名和账号即可。部署前先确认服务器开放 22300 端口并配置防火墙；数据库建议使用 PostgreSQL，避免 SQLite 在大并发下性能不足。Nginx 配置示例可以参考官方仓库的 examples 目录，HTTPS 证书可用 Let's Encrypt 免费申请并配置自动续期。完整的自托管步骤与常见环境变量说明见 Joplin Server 官方部署说明，里面列出了环境变量与部署要点；部署过程中遇到问题，可以先检查 docker compose logs 的输出，再结合官方文档排查。部署后建议定期更新镜像版本，数据库备份文件也应加密保存。

注意

请务必给 PostgreSQL 数据库配置定时备份，并妥善保管管理员密码。自托管后，数据库与文件系统都要定期备份：PostgreSQL 用 pg_dump，文件卷直接打包；恢复演练可以每季度做一次，具体见数据备份与恢复实战。如果只是个人同步，坚果云 WebDAV 更省心，方案对比见同步方案全面对比。

四、常见问题

自托管后手机能同步吗？

能。Joplin Server 是官方同步后端，桌面端、移动端、终端版都可以连接。如果 Docker 启动失败，先运行 docker compose logs 查看错误日志，多数是端口被占用或环境变量配置错误。