用海外云服务器自建 Joplin Server 笔记同步服务完整教程：端到端加密、离线优先与多设备同步实战（2026 最新版）

Meta Description: 2026 最新 Joplin Server 自建教程：海外云服务器用 Docker Compose 部署 Joplin Server + PostgreSQL，配 Nginx + HTTPS、端到端加密、多设备同步、备份升级与故障排查，附价格表与 10 条问答。

关键词：Joplin Server 搭建教程、自建笔记同步服务器、Joplin 端到端加密、Markdown 笔记自托管、Docker 部署 Joplin Server、Joplin PostgreSQL 配置、Joplin 多设备同步、Joplin 和 Nextcloud 区别、Joplin 和 Wiki.js 区别、海外云服务器自建笔记

前言

如果你要的不是「一个多人协作的团队知识库」，也不是「把文件丢进云盘同步」，而是——自己的笔记，以 Markdown 存在本地，离线也能写，换设备时通过自己的服务器安全地同步，而且连服务器管理员都看不懂内容——那么你要的正是 Joplin + Joplin Server。

Joplin 是一款开源笔记应用（Windows / macOS / Linux / Android / iOS / 命令行全覆盖），数据以 Markdown 落地，支持导入 Evernote 的 .enex 归档，也有浏览器剪藏插件；而 Joplin Server 是官方提供的同步服务端，你可以把它装在自己的服务器上，让所有设备通过一个只有你知道的地址互相同步。它和「用 Nextcloud 的 WebDAV 同步 Joplin」最大的区别在于：Joplin Server 走的是为 Joplin 定制的同步协议（增量同步、效率更高），并且额外提供笔记分享与发布到互联网的能力。

更关键的一点：Joplin 的端到端加密（E2EE）开启后，笔记在离开你设备之前就已经加密，服务器上存放的只是密文——同步服务商、云主机商、乃至 Joplin 开发者本人都无法读取你的笔记内容。本文给出一份可直接复制执行的完整教程，从服务器选型、Docker Compose 部署、Nginx + HTTPS、初始化管理员、多设备接入、开启端到端加密，一路讲到分享/发布、安全加固、备份升级、故障排查，最后附一份配置价格对比表和 10 条常见问题解答。

🚀 需要一台海外云服务器来跑 Joplin Server？通过 5.chengzicloud.cloud 购买阿里云国际版 / 腾讯云国际版 / AWS，享专属折扣。

一、先搞清楚：Joplin Server 解决什么问题（与站内方案的分工）

一句话概括：Joplin 是「客户端（笔记 App）」，Joplin Server 是「服务端（同步与分享）」。 你真正每天打开的是客户端，服务端只在同步时被调用——它不提供完整的笔记编辑界面，这也是很多人第一次访问 https://notes.example.com 时觉得「界面怎么这么简陋」的原因。它主要负责三件事：接收并保存各设备同步上来的数据、在不同用户之间分享笔记、把笔记发布成公开网页。

1.1 它和「云盘同步」「团队 Wiki」的根本区别

很多人会问：我都已经会用 Nextcloud 了，为什么还要装一个 Joplin Server？关键在于同步的对象和协议完全不同：

一句话选型：要「多人共建知识库」选 Wiki.js，要「通用私有云盘」选 Nextcloud，要「扫件归档」选 Paperless-ngx，要「存网页稍后读」选 wallabag；只有当你需要「个人 Markdown 笔记 + 端到端加密 + 多端同步」时，才轮到 Joplin Server。

1.2 「离线优先」到底意味着什么

Joplin 的笔记默认存在本地（桌面端是本地 SQLite 数据库 + 附件目录），打开就能写，完全不需要联网；同步是后台异步发生的——你改完一条笔记，客户端会在后台把它推给服务器。这意味着：

• 飞机上、地铁里、断网时照常写，不丢内容；
• 服务器临时挂掉，不影响你继续记笔记，只是暂时同步不出去；
• 就算服务器数据全丢（只要某台设备还在），从该设备重新同步就能把数据推回去。

这一点和「Web 版 Wiki / 云笔记」是本质区别：后者的数据在服务器，服务不可用你就无法工作；Joplin 恰恰相反。

1.3 Joplin Server 不适合谁

• 想要浏览器里即开即写：Joplin 有 Web 版，但自建 Joplin Server 的重心在同步；如果你要的是「打开网页就是编辑器」，Wiki.js 更合适；
• 要多人实时协同编辑同一条笔记：Joplin 的分享是「把笔记本共享给另一个用户」，不是 Google Docs 那种实时光标协同；
• 打算拿它对外提供付费笔记服务：Joplin Server 的个人使用许可禁止商用，详细边界见下一节。

二、部署前的三条前置条件（先确认，再动手）

2.1 许可证：个人可以免费用，商用不行

Joplin 的应用程序是开源的（AGPL），但 Joplin Server 服务端使用一份专门的许可——Joplin Server Personal Use License，核心条款是：

• 允许非商业用途的个人与专业笔记、与他人分享笔记、同步数据，免费；
• 允许你把访问权限开放给他人，前提是你自己不是商业实体、且双方都不用它产生任何形式的利润；
• 禁止将软件用于商业用途，也禁止向他人收费提供访问。

也就是说：个人自用、家用、自己记笔记，完全免费且合法；但如果你想在组织内给几十个同事用、或者拿它做对外服务，就需要购买 Joplin Server Business 许可。官方公开定价为：2–10 用户 3.33 欧元/用户/月，11–50 用户 2.92 欧元/用户/月，51 用户以上 2.50 欧元/用户/月（按年付对应 40 / 35 / 30 欧元每人每年），并提供 14 天免费试用。对比官方托管版 Joplin Cloud 个人版 2.99 欧元/月起，自建 + 个人许可的组合在合规前提下成本最低——但这条合规红线必须先看清。

2.2 一个可用于 HTTPS 的域名（重要）

Joplin Server 有一个环境变量 APP_BASE_URL，它就是客户端将要访问的最终公网地址。这个值必须与实际访问地址完全一致（协议、域名、端口、路径都要对上），否则客户端会同步失败、附件无法下载。因此：

• 需要：一个能解析到你服务器的域名，加上一张有效的 TLS 证书（走 Nginx 反代 + Let's Encrypt 即可，见第四节）；
• 建议：就用子域名（如 notes.example.com），不要挂子目录，省去路径拼接的坑；
• 不建议：直接暴露 IP + 端口对外同步——明文 HTTP 会让 E2EE 之外的所有东西（账号密码、令牌、附件元数据）裸奔。

2.3 数据库：生产环境请用 PostgreSQL

官方 README 写得很直白：默认会使用 SQLite，但这基本只用于「测试和评估」服务器；生产环境应当连接数据库。因此本文一律采用官方推荐的组合：Joplin Server 容器 + PostgreSQL 16 容器，两者由 Docker Compose 编排。

服务器规格上，Joplin Server 是一个 Node.js 服务，本身很轻：个人自用 1 核 1G 起步即可，2 核 2G 更从容。真正需要留意的是磁盘——数据库容量会随笔记数、附件（图片、PDF 等）持续增长。若附件较多，建议把存储驱动切到文件系统或 S3（见第八节），让数据库只留元数据。

三、第一步：Docker Compose 部署 Joplin Server + PostgreSQL

3.1 服务器初始化与安全加固

先做最小加固：只放行 SSH / HTTP / HTTPS，禁密码登录、装 fail2ban。完整清单见站内《网站安全加固指南》，这里给最关键的三步（Ubuntu / Debian）：

ufw allow 22/tcp
ufw allow 80/tcp
ufw allow 443/tcp
ufw enable
apt install -y fail2ban
systemctl restart fail2ban

切记先确认自己是用密钥登录的再禁用密码登录，否则会把自己锁在门外。

3.2 安装 Docker 与 Compose

curl -fsSL https://get.docker.com | sh
docker --version
docker compose version

3.3 创建工作目录与配置文件

mkdir -p /opt/joplin && cd /opt/joplin

先写 .env（口令请用 openssl rand -base64 24 生成随机串，不要照抄示例值）：

APP_BASE_URL=https://notes.example.com
POSTGRES_DATABASE=joplin
POSTGRES_USER=joplin
POSTGRES_PASSWORD=换成一串随机口令
POSTGRES_PORT=5432

再写 docker-compose.yml。下面这份基于官方示例改写，只保留 server 这一组（即 Joplin Server + PostgreSQL 两个容器），并补上持久化卷与「只绑本机」的端口映射：

services:
  db:
    image: postgres:16
    volumes:
      - ./data/postgres:/var/lib/postgresql/data
    networks:
      - app-network
    restart: unless-stopped
    environment:
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - POSTGRES_USER=${POSTGRES_USER}
      - POSTGRES_DB=${POSTGRES_DATABASE}

  app:
    image: joplin/server:latest
    depends_on:
      - db
    ports:
      - "127.0.0.1:22300:22300"
    networks:
      - app-network
    restart: unless-stopped
    environment:
      - APP_PORT=22300
      - APP_BASE_URL=${APP_BASE_URL}
      - DB_CLIENT=pg
      - POSTGRES_HOST=db
      - POSTGRES_PORT=${POSTGRES_PORT}
      - POSTGRES_DATABASE=${POSTGRES_DATABASE}
      - POSTGRES_USER=${POSTGRES_USER}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}

networks:
  app-network:

三个细节值得强调：

1. 127.0.0.1:22300:22300：把端口只绑到本机回环地址，外部无法直连，所有流量必须经过 Nginx 反代。这比裸开 22300:22300 安全得多。
2. ./data/postgres 卷：PostgreSQL 的数据目录必须持久化，否则删了容器数据就没了。
3. DB_CLIENT=pg + POSTGRES_HOST=db：前者告诉服务端用 PostgreSQL 而非 SQLite，后者指向 Compose 里的服务名 db（容器网络内解析）。

官方镜像还提供另一个 profile：full 会额外拉起 Transcribe 服务（把图片/手写内容转成文字）与它的独立数据库，但该服务对资源要求相当高（官方示例给的是 16G 内存、4 CPU 的上限）。个人笔记场景完全不需要，本文只用 server 这一组。

3.4 启动并确认服务健康

docker compose up -d
docker compose ps
docker compose logs -f app

日志里通常会看到数据库迁移（migration）记录，随后出现服务已就绪的提示（按 Ctrl+C 退出日志跟随）。再在本机自测一下：

curl -I http://127.0.0.1:22300

能返回 HTTP 响应（通常是 200 或一个跳转）就说明服务端进程活着。此时还不要急着用——先配好 HTTPS 反代。

四、第二步：Nginx 反向代理 + HTTPS

4.1 安装 Nginx 与 Certbot

apt install -y nginx certbot python3-certbot-nginx

4.2 申请证书

systemctl stop nginx
certbot certonly --standalone -d notes.example.com
systemctl start nginx

证书会存到 /etc/letsencrypt/live/notes.example.com/。若你服务器上已经有别的站点在用 Nginx，就别停服务，改用 certbot certonly --nginx -d notes.example.com 走 Nginx 插件签发。证书与反向代理的完整原理见站内《Nginx 反向代理 + SSL 证书配置完整指南》。

4.3 写站点配置

新建 /etc/nginx/sites-available/joplin：

server {
    listen 80;
    server_name notes.example.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name notes.example.com;

    ssl_certificate     /etc/letsencrypt/live/notes.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/notes.example.com/privkey.pem;

    client_max_body_size 200m;

    location / {
        proxy_pass http://127.0.0.1:22300;
        proxy_http_version 1.1;
        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_read_timeout 300s;
        proxy_send_timeout 300s;
    }
}

启用并检查：

ln -s /etc/nginx/sites-available/joplin /etc/nginx/sites-enabled/joplin
nginx -t
systemctl reload nginx

四个容易被忽略、但一定会出问题的点：

1. X-Forwarded-Proto $scheme 必须带上。服务端要靠它判断「外部访问的是 HTTPS」，很多「登录后跳回 HTTP」「分享链接是 http://」的怪问题都出在这里。
2. client_max_body_size：Nginx 默认只允许 1 MB 的请求体，而 Joplin 同步附件（图片、PDF）走的就是请求体——不改这一项，稍大一点的附件就会同步失败（表现为 413）。这里给了 200m，按需调整。
3. 同步是普通 HTTP 请求，不需要 WebSocket。这一点和站内 ntfy 推送服务必须配 WebSocket 的情况不同，Joplin 只用轮询式的 HTTP 请求，反代配置更简单。
4. APP_BASE_URL 必须和 server_name 完全一致。你在浏览器里敲的是 https://notes.example.com，那 .env 里就写 https://notes.example.com，多一个 :22300、少一个 https 都会导致客户端 404 或附件链接失效。

HTTP/2 的写法随 Nginx 版本变了：Nginx 1.25.1 及更早版本用上面的 listen 443 ssl http2;；1.25.1 之后推荐写成 listen 443 ssl; 再加一行 http2 on;。写错会直接 nginx -t 报错，按你的实际版本选一种即可。

4.4 让服务端知道自己跑在 HTTPS 后面

既然现在只通过 HTTPS 对外提供服务，顺手把 Cookie 的安全标志打开，编辑 .env 追加一行（默认值是 false）：

COOKIES_SECURE=true

然后重建容器让配置生效：

docker compose up -d

此时浏览器访问 https://notes.example.com，应该能看到 Joplin Server 的登录界面了。

五、第三步：初始化管理员与「上线必改」的三项

5.1 登录默认管理员

官方镜像启动时会创建一个默认管理员账号：邮箱 admin@localhost，密码 admin（密码可用环境变量 DEFAULT_ADMIN_PASSWORD 在首次启动前改掉）。第一次登录后，这个密码必须立刻修改。

具体做法：登录后在页面右上角选择 Profile，修改管理员密码（也可以同时把邮箱改成你自己的真实邮箱——分享、发布、通知等功能都以邮箱作为账号标识）。

5.2 上线必改的三项

5.3 给自己建一个「日常账号」

安全实践上，不要拿管理员账号做日常同步。在后台 Users 里新增一个普通用户（用自己的真实邮箱），日常记笔记、手机端同步都用这个账号；管理员账号只在改配置、管用户时才登录。这样即使日常账号的密码在某一台设备上泄露，攻击者也拿不到后台管理权限。

5.4 可选：打开邮件通知

邮件不是必需的，但打开之后「密码重置」「分享通知」才有邮件可发。相关变量（默认关闭）包括：

MAILER_ENABLED=true
MAILER_HOST=smtp.example.com
MAILER_PORT=465
MAILER_SECURITY=tls
MAILER_AUTH_USER=你的发件账号
MAILER_AUTH_PASSWORD=你的发件口令
[email protected]
MAILER_NOREPLY_NAME=Joplin Server

自建邮局可参考站内《邮件服务器搭建教程》；不想自建，用任意第三方 SMTP 即可。

六、第四步：客户端接入（桌面 / 手机 / 命令行）

6.1 桌面端（推荐第一台设备用桌面版）

打开 Joplin 桌面端 → 工具（Tools）→ 选项（Options）→ 同步（Synchronisation）：

1. 同步目标（Synchronisation target） 选 Joplin Server；
2. 填入 Joplin Server URL：https://notes.example.com（注意：不要带 / 结尾的路径，也不要带端口）；
3. 填入 Email：就是你刚创建的那个用户邮箱；
4. 填入 Password：该用户的密码；
5. 点 Check synchronisation configuration 验证，通过后点 Synchronise。

同步间隔默认是 300 秒（5 分钟），可以在同一屏把间隔调短（例如 60 秒）让自己感觉更「实时」，代价是请求更频繁。

6.2 手机端

Android / iOS 客户端在 配置（Configuration）→ 同步（Synchronisation） 里填同样三项：URL、邮箱、密码，选同步目标为 Joplin Server。手机端首次同步建议在 Wi-Fi 下进行。

6.3 命令行（终端应用）

官方提供命令行版 Joplin，适合在服务器上做批量导入导出或自动化备份：

npm install -g joplin
joplin

进去后是交互式提示符，用冒号命令配置同步目标（9 就是 Joplin Server）：

:config sync.target 9
:config sync.9.path https://notes.example.com
:config sync.9.username 你的邮箱
:config sync.9.password 你的密码
:sync

几个常用命令：

// 同步一次
:sync

// 查看当前同步配置
:config sync.target
:config sync.9.path

// 从 Evernote 归档导入（.enex 文件）
:import /path/to/我的笔记.enex

// 导出全部笔记为 JEX 归档（迁移或备份）
:export /path/to/backup.jex jex

6.4 首次同步要有点耐心

第一台设备推全量数据时，会逐条创建笔记与附件，笔记多、附件大的话可能要跑很久。经验法则：让它跑完，不要中途取消——中断后虽然可以重来，但会浪费一次全量计算。后续同步都是增量的（Joplin Server 的同步协议只传变化部分），会快得多。

七、第五步：开启端到端加密（顺序错了会出乱子）

这是 Joplin 最值得自建的一个理由，也是最容易做错顺序的一步。官方文档给出的流程如下：

7.1 先在第一台设备开启

1. 在第一台设备（官方建议用桌面端或终端应用，因为它们算力更强、加密全量数据更快）打开 加密（Encryption） 配置页，点击 Enable encryption；
2. 输入一个密码——这就是 Master Key 密码，它用来加密你的全部笔记。官方明确说明：出于安全考虑，这个密码无法找回，务必牢记；
3. 等当前同步任务结束后，点一次 Synchronise，把所有笔记加密后重新上传到服务端；
4. 耐心等它跑完。因为所有数据都要重新加密发送，笔记和附件多的话可能非常久——官方特别提醒：即使界面看起来卡住了，大概率它还在跑，不要取消，实在不行让它跑一整夜。

7.2 再逐台同步其余设备

1. 打开下一台设备，点 Synchronise，等同步完成——这台设备会收到主密钥并要求你输入主密钥密码，输入后 E2EE 会自动在这台设备上启用；再点一次 Synchronise 并等它完成；
2. 对每一台设备重复第 5 步。

7.3 三条必须记住的规则

• 绝对不要在多台设备上并行手动打开加密。官方明确警告：这样可能产生多个加密密钥（Joplin 支持多密钥，但那几乎肯定不是你想要的结果）。正确姿势是「先在第一台开好并同步完，其他设备只做同步」。
• 主密钥密码丢了就是丢了。只要还有任意一台已启用 E2EE 的设备在手，你仍能读取笔记；但如果你在所有设备上都没了这台设备，服务器上的密文就彻底不可解。
• 关闭 E2EE 也要一台一台来：官方建议同样逐台关闭，每关一台都等同步跑完。

7.4 开启加密后，服务器上还剩什么

开启之后，笔记正文、标题、附件在离开你的设备之前就已被加密，服务器数据库里保存的是密文——云主机商、机房、乃至 Joplin 开发者本人都无法读取内容（官方原话是连开发者自己也无法访问）。代价是一点点性能开销：每次同步都要加密解密，所以官方也提醒「先想清楚是否真的需要」。

建议：开启 E2EE 之前先手动导出一份 JEX 备份（桌面端「文件 → 导出 → JEX」）。加密+全量重传是个不可逆的大动作，有一份离线备份在手会安心得多。备份的整体思路与站内《服务器备份与容灾恢复方案》一致。

八、进阶能力：存储、分享、发布与时间同步

8.1 存储驱动：别让附件把数据库撑大

默认情况下，Joplin Server 把同步上来的内容直接存进数据库（STORAGE_DRIVER 的默认值是 Type=Database）。笔记少、附件少时这完全没问题；但一旦你开始往笔记里塞图片、PDF，数据库体积会涨得很快，备份和迁移都会变慢。官方提供了两种外置存储：文件系统和 S3 兼容对象存储。

新装即用文件系统存储，只要在 .env 里加：

STORAGE_DRIVER=Type=Filesystem; Path=/path/to/storage

用 S3 则写成：

STORAGE_DRIVER=Type=S3; Region=你的区域; AccessKeyId=你的KEY; SecretAccessKeyId=你的SECRET; Bucket=你的桶

已经跑了一段时间想迁移（数据库 → 文件系统/S3）稍复杂，官方流程分两步：

1. 先启用「新存储 + 回退存储」，让新内容写入新存储、读取时找不到再回查旧存储：

STORAGE_DRIVER=Type=Filesystem; Path=/path/to/dir
STORAGE_DRIVER_FALLBACK=Type=Database; Mode=ReadAndWrite

其中 Mode 有两种：ReadAndClear 会在条目搬到新存储后清掉旧存储里的副本，适合直接迁移；ReadAndWrite 则把内容同时写进新旧两处，纯粹为了安全——万一新存储有问题还能退回旧的。

1. 老数据（那些再也没被更新过的条目）会一直留在数据库里，需要执行一次搬移命令：

docker exec -it 容器ID node packages/server/dist/app.js storage import --connection 'Type=Filesystem; Path=/path/to/dir'

搬完后用一条 SQL 自查（content_storage_id 大于 1 就表示已经不在数据库里了）：

SELECT count(*), content_storage_id FROM items GROUP BY content_storage_id;

自建 S3 可参考站内《MinIO 对象存储搭建教程》。

8.2 笔记分享：把某个笔记本共享给另一个用户

自建 Joplin Server 同样支持笔记本分享（服务端就有 shares / share_users 两组接口）。在桌面端右键某个笔记本 → Share notebook，填入接收者的邮箱（对方必须是你这个实例上的用户），对方下次同步时会收到通知，接受后笔记本就会出现在他的列表里，双方对笔记的修改彼此可见。你也可以随时移除某个接收者，或取消整个共享。

开了端到端加密之后共享还能用吗？能，而且原理很漂亮：共享时客户端会为这个笔记本生成一把 NOTEBOOK_KEY，用发送方的主密码加密；邀请接收者时，这把密钥会被解密并以接收者的公钥重新加密随邀请下发；接收者接受后用自己的私钥取出它，再用自己的主密码重新加密保存。也就是说——每个用户手里都有一份用自己主密码保护的笔记本密钥，而公钥/私钥只用来传递这把密钥，端到端加密与共享并不冲突。

需要说明的是，官方文档里标注为 Joplin Cloud Pro / Teams 的能力（例如笔记本级的「只读 / 可编辑」权限细分、发布页自定义横幅）属于官方托管版的增值功能，自建实例上没有这些选项。

8.3 发布笔记：把单条笔记变成公开网页

在桌面端右键一条笔记（可多选，每条各自一个链接）→ Publish note…，弹出的对话框里点 Copy shareable link 就能拿到一个公开链接，任何人打开浏览器都能读到这条笔记和它的附图；你之后修改笔记，链接里的内容会自动更新。不想公开了，再右键那条笔记，在同一个对话框里点分享图标即可取消发布。

8.4 邮件通知、LDAP 与多因素认证（企业向，可选）

• 邮件：把 MAILER_ENABLED 设为 true 并配好 MAILER_HOST / MAILER_PORT（默认 465）/ MAILER_SECURITY / MAILER_AUTH_USER / MAILER_AUTH_PASSWORD / MAILER_NOREPLY_EMAIL / MAILER_NOREPLY_NAME，用于密码重置与分享通知；
• LDAP：支持多组 LDAP 目录（LDAP_1_、LDAP_2_，含 USER_AUTO_CREATION 自动建号），适合已有目录服务的团队；
• SAML 单点登录：SAML_ENABLED 配合 SP/IdP 配置文件；
• 多因素认证：MFA_ENABLED（默认关闭）可开启，配合 MFA_ENCRYPTION_KEY 使用。

个人自用场景这几项都可以不管，保持默认即可。

8.5 为什么 Joplin Server 比「WebDAV 同步」快

这值得单独说一句，因为它是「自建服务端」而不是「拿网盘凑合」的核心价值。Joplin Server 实现的是增量同步（delta sync）：客户端带着一个 cursor（本质是「时间点」）去问服务端「从这个点之后有哪些变化」，服务端只回传变化事件（create / update / delete）以及对应的文件元数据——一条请求就能拿到变化清单，不用把目录整个扫一遍。而且服务端会自动压缩冗余事件：同一文件多次修改只回一个 update；先建后改只回一个 create（带最新版本）；先建后删则什么都不回（对客户端来说这个文件从未存在过）；多次修改后删除只回一个 delete。

这套机制带来的直接体验是：笔记越写越多，每次同步要传的东西却仍然只有你真正改过的那几项。这也解释了它的两个提醒：cursor 是分页的，limit 参数只是「建议值」——因为事件被压缩后实际返回条数可能少于 limit，但绝不会多。

九、安全加固清单：别让笔记服务器变成「公开的登录页」

9.1 服务器层（必做）

• 只放行 22 / 80 / 443，其余端口全部关掉；用 ufw 或 iptables 都行；
• Docker 端口绑定回环地址：127.0.0.1:22300:22300，让 22300 无法从公网直达，所有流量必须过 Nginx；
• 禁密码登录、只留密钥，装 fail2ban 防 SSH 爆破；
• 系统时间必须准：Joplin Server 会校验客户端与服务器的时间漂移，MAX_TIME_DRIFT 默认 2000 毫秒，NTP_SERVER 默认 pool.ntp.org:123。服务器时间跑偏会导致同步被拒，确保 chrony / ntpd / systemd-timesyncd 正常工作；
• 定期 docker compose pull && docker compose up -d 更新镜像，跟上官方的安全修复。

9.2 应用层（必做）

• 改掉默认管理员密码（admin@localhost / admin 是公开的默认值）；
• COOKIES_SECURE=true（走 HTTPS 时必须开）；
• 日常用普通账号，不用管理员账号同步；
• SIGNUP_ENABLED 保持 false：这是默认值，意味着实例不对外开放自助注册，账号一律由管理员在后台创建——这正是你想要的；
• ERROR_STACK_TRACES 保持关闭：报错时不要把堆栈和文件路径泄露给访问者；
• 开启 MFA_ENABLED（可选但推荐）：多一层验证码，后台账号更稳。

9.3 Nginx 层（可选但有效）

给登录接口加一道限速，能让暴力破解的成本高到离谱。先在 http 块里声明限速区（把下面这一行加到 /etc/nginx/nginx.conf 的 http { } 内部）：

limit_req_zone $binary_remote_addr zone=joplin_login:10m rate=10r/m;

然后在站点配置里，把登录接口单独拎出来限速（其余 location 保持本文 4.3 的写法不变）：

    location /api/login {
        limit_req zone=joplin_login burst=5 nodelay;
        proxy_pass http://127.0.0.1:22300;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

改完照例 nginx -t && systemctl reload nginx。

9.4 官方内置的加固选项

Joplin Server 提供了一层基于 Node.js 的加固机制：服务入口在启用加固时会设置一组 NODE_OPTIONS（目前包含 --disable-proto=delete 这类用于缩减攻击面的选项），官方文档把它单列了一个页面（Joplin Server hardening）。使用官方镜像时这些由镜像自身按官方设定处理，你不需要额外操作——知道它在，是为了向上汇报安全时能说清楚。

十、海外云服务器配置推荐与价格对比

下表价格为当日直读官方定价页的档位-规格映射（DigitalOcean Droplet 与 AWS Lightsail）；阿里云国际版 / 腾讯云国际版为区间参考，实际以控制台为准（价格随地域、套餐调整，这里只做量级参考）。

选型口诀：个人笔记，1 GB 内存就能跑；磁盘比内存重要。 Joplin Server 本体只是一个 Node 进程加一个 PostgreSQL，占用很轻——DO 的 $6 档（1 核 1G / 25 GB）或 Lightsail 的 $7 档（1 GB）就足够个人使用；把预算加在磁盘和流量上更划算。只有当你把附件全留在数据库、笔记量很大，或者打算开官方的 full profile（会多起一个很吃资源的 Transcribe 服务），才需要考虑 2 核 2G 以上的档位。

声明：本文价格数据采集于 2026 年 10 月，仅为公开官网参考区间，实际以各家官网实时价格为准，金额单位均为美元（USD）。

十一、备份、升级与故障排查

11.1 备份：三样东西，少一样都可能白干

比站内很多服务更简单——Joplin Server 的「全部家当」就三处：

1. PostgreSQL 数据库（笔记元数据与内容，若没切存储驱动则附件也在里面）。逻辑备份一条命令：

docker compose exec -T db pg_dump -U joplin joplin > backup_$(date +%F).sql

1. .env 文件：里面有数据库口令和 APP_BASE_URL，恢复时没有它就得重新对一遍配置；
2. 存储目录（只有你启用了文件系统驱动或 S3 才有）：文件系统驱动的话就是上面配置里的 Path 所指目录，一起打包即可；S3 则由对象存储自身负责。

恢复同站内其他服务一样，定期演练一次才算真备份，思路参考《服务器备份与容灾恢复方案》。

11.2 升级

cd /opt/joplin
docker compose pull
docker compose up -d
docker compose logs -f app

三句话要点：升级前先做 11.1 的备份；镜像启动时会自动执行数据库迁移（日志里能看到），不要手动改数据库结构；如果你希望升级出问题时能退回去，就把 compose 里的 image: joplin/server:latest 固定成一个具体版本号（先到 Docker Hub 的 tag 列表确认该版本真实存在），需要回滚时把 tag 改回上一个版本再 up -d 即可。

11.3 故障排查速查表

推荐方案

综合成本与体验，给两套可以直接照抄的组合：

方案 A：个人自用（预算优先）

• 香港 / 新加坡节点，1 核 1G、25 GB SSD、1 TB 月流量（DO / Lightsail 约 $6–$7）；
• 按本文第三至第五节用 Docker Compose 部署 Joplin Server + PostgreSQL 16，Nginx + Let's Encrypt 提供 HTTPS，22300 只绑本机；
• 附件走文件系统存储或直接 S3，数据库只留元数据；
• 在第一台设备开启 E2EE，主密钥密码离线记牢；
• 每天 pg_dump 备份数据库 + .env。

方案 B：小团队/重度使用（体验优先）

• 2 核 2G～4 核 4G、80 GB SSD 以上（约 $12–$24）；
• 存储驱动切到 S3 兼容对象存储 + CDN，本机只留数据库；
• 打开邮件通知（密码重置、分享提醒）与 MFA；
• 用普通账号做日常同步，管理员账号只在后台操作时登录；
• 给 /api/login 加 Nginx 限速，并监控容器与磁盘水位。

部署后的日常维护：每月 docker compose pull && docker compose up -d 跟一次版本（先备份）；定期查看 docker compose logs app 有没有数据库连接或存储异常；用 11.1 的 SQL 看一眼内容分布，判断要不要做存储迁移；主密钥密码单独抄一份离线保存——它和服务器无关，是唯一「丢了就真丢了」的东西。

🚀 需要海外云服务器来部署 Joplin Server？通过 5.chengzicloud.cloud 购买阿里云国际版 / 腾讯云国际版 / AWS，享专属折扣。