Joplin Server 怎么安装？Docker Compose 私有同步服务器设置教程

Joplin Server 是 Joplin 官方提供的同步服务器。自己搭一套以后，笔记数据可以放在自己的 VPS、NAS 或家用服务器上，多端同步也不用依赖第三方网盘。

目前最省心的部署方式是 Docker Compose：一个 PostgreSQL 数据库容器，一个 Joplin Server 容器，配置好 APP_BASE_URL 后就能给电脑和手机端同步使用。

下面是一套偏实用的安装流程，适合 Ubuntu、Debian、CentOS、群晖、Unraid、OpenMediaVault 等能跑 Docker 的环境。

准备条件

开始前先确认这些条件：

一台能长期运行的服务器或 NAS；
已安装 Docker 和 Docker Compose；
如果只在内网同步，可以直接用内网 IP；
如果要外网同步，建议准备域名和 HTTPS 反向代理；
提前想好数据库密码，不要直接使用示例密码。

如果你只是家里几台设备同步，http://内网IP:22300 就能跑起来。如果要手机在外面同步，建议用 Nginx Proxy Manager、Caddy、Traefik 或类似工具做 HTTPS，不建议直接把裸 HTTP 服务暴露到公网。

创建 Joplin 工作目录

先在服务器上准备一个目录，专门存放 Joplin Server 的配置和数据库数据：

1
2


mkdir -p /data/joplin
cd /data/joplin

目录可以按自己的习惯调整，例如 /opt/joplin、/volume1/docker/joplin。关键是数据库目录要持久化，不要让 PostgreSQL 数据跟着容器删除。

编写 docker-compose.yml

在工作目录里创建 Compose 文件：

1

nano docker-compose.yml

写入下面这份配置：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


version: '3.8'

services:
  db:
    image: postgres:16
    container_name: joplin-db
    restart: unless-stopped
    volumes:
      - ./data/postgres:/var/lib/postgresql/data
    environment:
      - POSTGRES_USER=joplin
      - POSTGRES_PASSWORD=change_this_database_password
      - POSTGRES_DB=joplin

  app:
    image: joplin/server:latest
    container_name: joplin-app
    depends_on:
      - db
    restart: unless-stopped
    ports:
      - "22300:22300"
    environment:
      - APP_PORT=22300
      - APP_BASE_URL=http://your-server-ip:22300
      - DB_CLIENT=pg
      - POSTGRES_USER=joplin
      - POSTGRES_PASSWORD=change_this_database_password
      - POSTGRES_DATABASE=joplin
      - POSTGRES_HOST=db
      - POSTGRES_PORT=5432

这里最需要改的是两处：

POSTGRES_PASSWORD：数据库密码，db 和 app 两个服务里必须完全一致；
APP_BASE_URL：客户端以后访问 Joplin Server 的固定地址。

APP_BASE_URL 很关键。它必须写成客户端真正能访问到的地址：

只在内网使用：http://192.168.1.10:22300
用公网 IP 访问：http://your-public-ip:22300
使用域名和 HTTPS：https://joplin.example.com

如果你后面改了访问地址，最好同步修改 APP_BASE_URL 并重启服务，否则客户端同步、网页跳转或附件链接可能会出问题。

启动 Joplin Server

在 docker-compose.yml 所在目录执行：

1

docker compose up -d

查看容器状态：

1

docker compose ps

如果第一次启动比较慢，可以看日志：

1

docker compose logs -f

正常情况下，Joplin Server 会监听 22300 端口。浏览器访问你设置的 APP_BASE_URL，能打开登录页面就说明基础部署成功。

首次登录后台

Joplin Server 默认管理员账号是：

1

admin@localhost

默认密码是：

1

admin

第一次登录后，先做一件事：立刻修改管理员密码。不要让默认密码留在服务器上，尤其是这个服务能从公网访问时。

登录后台后，可以进入 Change Password 页面，把 admin 改成一个足够强的密码。

创建日常同步账号

不建议直接用管理员账号同步笔记。更稳的做法是创建一个普通用户账号，日常电脑和手机都用这个普通账号同步。

后台操作步骤：

进入 Users；
点击 Add user；
填写你日常使用的邮箱和密码；
创建用户。

这里有一个常见坑：如果没有配置 SMTP 邮件服务器，Joplin Server 会提示发送了激活邮件，但你实际收不到邮件。

解决方法也很简单：

回到管理员后台；
打开 Emails 菜单；
找到那封未发出的激活邮件；
复制里面的激活链接；
在浏览器新标签页打开链接，完成账号激活。

激活后，这个普通用户就可以用于客户端同步了。

配置 Joplin 客户端同步

在电脑端或手机端 Joplin App 中设置同步：

打开 设置 或 Options；
进入 同步 或 Synchronization；
同步目标选择 Joplin Server；
Joplin Server URL 填写你的 APP_BASE_URL；
Email / Username 填写刚创建并激活的普通用户邮箱；
Password 填写该用户密码；
点击 检查同步设置 或 Check sync configuration。

如果检查通过，就可以保存并开始同步。

如果检查失败，优先确认三件事：

客户端能不能直接打开 APP_BASE_URL；
APP_BASE_URL 是否和 Compose 文件里一致；
普通用户是否已经激活，而不是只创建未激活。

外网访问建议使用 HTTPS

如果只在家里 Wi-Fi 或内网使用，HTTP 访问通常够用。但如果要公网同步，建议加反向代理和 HTTPS。

常见方案包括：

Nginx Proxy Manager；
Caddy；
Traefik；
手写 Nginx 配置。

反向代理时，APP_BASE_URL 必须写最终给客户端访问的 HTTPS 地址，例如：

1

- APP_BASE_URL=https://joplin.example.com

如果你用 Nginx 手动配置，建议至少注意两点：

调大上传限制，例如 client_max_body_size 100M;，否则带大附件的笔记可能同步失败；
正确转发 Host、X-Forwarded-For、X-Forwarded-Proto 等头，避免 Joplin Server 判断 URL 或协议时出错。

一个简化的 Nginx 反向代理片段可以参考：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


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

    client_max_body_size 100M;

    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;
    }
}

如果你用 Nginx Proxy Manager，通常只需要把域名反代到服务器的 22300 端口，然后开启 SSL 证书即可。记得同时把 Compose 里的 APP_BASE_URL 改成 HTTPS 域名。

常见问题

修改 APP_BASE_URL 后不生效

修改 docker-compose.yml 后，需要重新创建容器：

1

docker compose up -d

如果仍然异常，可以先确认容器环境变量是否真的更新。不要只改文件但没有重启服务。

客户端同步提示网络错误

优先检查：

手机或电脑能否在浏览器打开 Joplin Server；
反向代理证书是否正常；
APP_BASE_URL 是否写成客户端实际访问的地址；
防火墙是否放行 22300 或 HTTPS 端口；
普通用户是否已经激活。

大附件同步失败

如果通过 Nginx 或其他反向代理访问，先检查上传大小限制。Nginx 默认限制可能偏小，建议设置：

1

client_max_body_size 100M;

如果笔记附件更大，可以继续调高。

不配置 SMTP 可以用吗

可以。个人或家庭使用时，不配置 SMTP 也能跑。创建用户后的激活邮件可以在后台 Emails 页面直接查看并复制激活链接。

如果是多人团队长期使用，建议配置 SMTP，用户注册、密码重置和通知会更完整。

备份建议

Joplin Server 最重要的数据在 PostgreSQL 里，也就是示例里的：

1

/data/joplin/data/postgres

至少要定期备份这个目录，或者用 PostgreSQL 的 pg_dump 做数据库备份。只备份 Joplin Server 容器本身没有意义，容器可以重新拉，数据库才是你的笔记同步数据。

另外，客户端本地也会保留一份笔记数据，但不要把它当成唯一备份。真正稳妥的做法是服务器数据库备份 + 客户端本地副本 + 必要时导出 JEX 归档。

群晖 DSM 7.x 部署 Joplin Server

在群晖 DSM 7.x 上部署 Joplin Server，最方便的方式是使用 Container Manager 的“项目”功能。它本质上就是 Docker Compose：一个 PostgreSQL 数据库容器，一个 Joplin Server 容器，群晖负责拉镜像、建容器和日常启动管理。

这篇是群晖专门版，重点放在 File Station 目录、Container Manager 项目、局域网访问、外网同步和反向代理这些实际操作上。如果你已经会在 Linux 服务器上手写 docker-compose.yml，流程会很熟；如果你主要用群晖图形界面，也可以照着做。

适合什么场景

Joplin Server 适合想把笔记同步数据放在自己设备上的用户。它可以让 Windows、macOS、iOS、Android 等客户端通过自己的服务器同步，而不是依赖第三方网盘。

在群晖上部署比较适合这些情况：

NAS 长期开机，适合做家庭或个人同步服务器；
只想在局域网内同步电脑和手机；
希望通过 Tailscale、WireGuard 或反向代理实现外网同步；
想用 Container Manager 图形界面管理容器，而不是全程 SSH。

如果你只是临时试用 Joplin，不一定要上 Joplin Server；Joplin 也支持 WebDAV、S3、Dropbox 等同步方式。但如果你想长期自托管，Joplin Server 会更完整。

第一步：在 File Station 中准备目录

打开群晖的 File Station，进入 docker 共享文件夹。

新建一个目录：

1

docker/joplin

再在 joplin 目录下新建一个子目录：

1

postgres_data

最后目录结构大致是：

1
2
3


docker/
└── joplin/
    └── postgres_data/

postgres_data 用来保存 PostgreSQL 数据库。Joplin Server 的同步数据主要在数据库里，所以这个目录必须持久化。以后更新容器、重建容器，只要这个目录还在，数据就不会跟着容器消失。

第二步：用 Container Manager 创建项目

打开群晖的 Container Manager：

点击左侧 项目；
点击 新增 或 Create；
项目名称填写 joplin-server；
路径选择刚才创建的 /docker/joplin；
来源选择 创建 docker-compose.yml。

然后把下面的 Compose 配置复制进去：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


version: '3'

services:
  db:
    image: postgres:16
    container_name: joplin-db
    volumes:
      - ./postgres_data:/var/lib/postgresql/data
    restart: unless-stopped
    environment:
      - POSTGRES_PASSWORD=change_this_database_password
      - POSTGRES_USER=joplin_user
      - POSTGRES_DB=joplin_db

  app:
    image: joplin/server:latest
    container_name: joplin-server
    depends_on:
      - db
    ports:
      - "22300:22300"
    restart: unless-stopped
    environment:
      - APP_PORT=22300
      - APP_BASE_URL=http://192.168.1.100:22300
      - DB_CLIENT=pg
      - POSTGRES_PASSWORD=change_this_database_password
      - POSTGRES_DATABASE=joplin_db
      - POSTGRES_USER=joplin_user
      - POSTGRES_PORT=5432
      - POSTGRES_HOST=db

这里有两处必须改：

POSTGRES_PASSWORD：数据库密码，两处必须完全一致；
APP_BASE_URL：Joplin 客户端真正访问服务器的地址。

如果你只在局域网内使用，把 APP_BASE_URL 改成群晖内网 IP：

1

- APP_BASE_URL=http://192.168.1.100:22300

如果你已经配置好 HTTPS 反向代理，直接写外网域名：

1

- APP_BASE_URL=https://joplin.example.com

APP_BASE_URL 不要随便填。Joplin 客户端同步、网页跳转、附件链接都依赖它。你用什么地址访问，就应该写什么地址。

确认无误后，继续点击下一步，直到完成。Container Manager 会自动下载 postgres:16 和 joplin/server:latest，然后启动两个容器。

第三步：确认容器状态

项目创建完成后，在 Container Manager 的项目页面查看 joplin-server。

正常情况下会有两个容器：

joplin-db
joplin-server

如果状态都是绿色运行中，就可以继续下一步。

如果没有正常启动，先看项目日志。常见问题通常是：

数据库密码两处不一致；
postgres_data 目录权限异常；
群晖的 22300 端口已经被其他服务占用；
YAML 缩进被改坏。

第四步：首次登录 Joplin Server

在浏览器中打开：

1

http://群晖IP:22300

例如：

1

http://192.168.1.100:22300

默认管理员账号是：

1

admin@localhost

默认密码是：

1

admin

第一次登录后，立刻修改管理员密码。这个步骤不要跳过，尤其是你准备给它配置外网访问时。

如果后台允许修改管理员邮箱，也建议改成你自己的邮箱，方便后续识别账号。

第五步：要不要新建普通用户

如果只是一个人用，直接用修改后的管理员账号同步也能跑。不过更规范的做法是新建一个普通用户，用普通用户同步笔记，管理员只负责管理后台。

后台操作：

进入 Users；
点击 Add user；
填写邮箱和密码；
保存。

如果你没有配置 SMTP，系统会提示发送激活邮件，但你实际收不到。这时可以进入后台的 Emails 页面，找到那封未发出的激活邮件，复制里面的激活链接，在浏览器打开即可激活账号。

个人使用时，不配置 SMTP 也没问题。多人长期使用时，建议再补 SMTP，否则注册、激活、密码重置会比较麻烦。

第六步：配置 Joplin 客户端同步

打开电脑或手机上的 Joplin 客户端：

进入 设置 或 Options / Settings；
打开 同步 或 Synchronization；
同步目标选择 Joplin Server；
Joplin Server URL 填写前面配置的 APP_BASE_URL；
用户名填写管理员邮箱或普通用户邮箱；
密码填写对应账号密码；
点击 检查同步配置 或 Check synchronization configuration。

检查成功后保存，然后开始同步。

如果检查失败，先确认客户端能不能在浏览器里打开 Joplin Server。很多同步问题不是 Joplin 本身的问题，而是 APP_BASE_URL 写错、账号未激活、反向代理证书异常或手机不在同一个网络里。

外网同步方案一：Tailscale 或 WireGuard

最安全、最省心的外网同步方式，是把手机和电脑通过 VPN 接回家里的内网。

常见选择：

Tailscale；
WireGuard；
ZeroTier。

这样做的好处是：Joplin Server 不需要直接暴露到公网。Joplin 客户端里的 URL 仍然可以填群晖内网地址，例如：

1

http://192.168.1.100:22300

手机在外面时，先连 Tailscale 或 WireGuard，再打开 Joplin 同步即可。

如果你不想处理公网 IP、DDNS、证书和端口转发，这条路线最稳。缺点是每台外部设备都要先接入 VPN。

外网同步方案二：群晖反向代理和 HTTPS

如果你希望 Joplin 在任何网络下都能直接同步，可以给它配置 HTTPS 域名。

大致流程是：

准备一个域名或 DDNS；
在路由器上把 443 端口转发到群晖；
在群晖 控制面板 -> 登录门户 -> 高级 -> 反向代理服务器 中新增规则；
来源填写 https://joplin.example.com:443；
目标填写 http://127.0.0.1:22300 或 http://群晖内网IP:22300；
为域名申请并绑定 HTTPS 证书；
把 Compose 里的 APP_BASE_URL 改成 https://joplin.example.com；
在 Container Manager 中重新部署项目。

反向代理时，建议在自定义标题里加入常见转发头，例如：

1
2
3
4


Host: $host
X-Real-IP: $remote_addr
X-Forwarded-For: $proxy_add_x_forwarded_for
X-Forwarded-Proto: $scheme

如果你使用的是群晖内置反向代理界面，不同 DSM 小版本的字段名称可能略有差异，按界面里的“自定义标题”或“WebSocket”相关选项添加即可。

另外，Joplin 同步大附件时可能会遇到上传大小限制。如果你用 Nginx Proxy Manager 或手写 Nginx，建议设置：

1

client_max_body_size 100M;

群晖内置反向代理没有这个选项时，可以先测试普通附件同步。如果经常同步大文件，Nginx Proxy Manager 或 Caddy 会更灵活。

修改 APP_BASE_URL 后要重新部署

很多人第一次先用内网 IP 测试，后来改成 HTTPS 域名。这种做法没问题，但不要只改客户端。

你需要同时修改 Container Manager 项目里的 Compose 配置：

1

- APP_BASE_URL=https://joplin.example.com

然后重新部署项目，让容器环境变量生效。

如果 APP_BASE_URL 仍然是旧地址，可能出现这些问题：

客户端检查同步失败；
登录后跳转到错误地址；
附件链接异常；
反向代理下显示协议不对。

备份重点

群晖上最重要的是这个目录：

1

docker/joplin/postgres_data

它保存了 PostgreSQL 数据库，也就是 Joplin Server 的核心同步数据。建议把它纳入 Hyper Backup 或其他备份计划。

更稳的做法是：

定期备份 docker/joplin/postgres_data；
Joplin 客户端本地保留一份笔记；
重要笔记定期导出 JEX；
更新容器前先确认备份可用。

不要只备份 Joplin Server 镜像或容器配置。镜像可以重新下载，数据库才是你的数据。

小结

Joplin Server 的 Docker Compose 部署并不复杂，真正容易踩坑的地方主要是三处：

APP_BASE_URL 必须写成客户端实际访问的地址；
默认管理员密码 admin 必须立刻修改；
没有 SMTP 时，新用户要去后台 Emails 页面复制激活链接。

内网使用时，http://IP:22300 就能完成同步。公网使用时，建议用 HTTPS 反向代理，并调好上传大小限制。只要这几步处理好，Joplin Server 就是一套很稳定的私有笔记同步方案。