运维

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

整理 Joplin Server 私有同步服务器的 Docker Compose 安装方法，包括 PostgreSQL 配置、APP_BASE_URL 设置、管理员初始化、普通用户激活、客户端同步和反向代理 HTTPS 注意事项。

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 改成一个足够强的密码。

创建日常同步账号

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

后台操作步骤：

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

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

解决方法也很简单：

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

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

配置 Joplin 客户端同步

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

  1. 打开 设置 或 Options；
  2. 进入 同步 或 Synchronization；
  3. 同步目标选择 Joplin Server；
  4. Joplin Server URL 填写你的 APP_BASE_URL；
  5. Email / Username 填写刚创建并激活的普通用户邮箱；
  6. Password 填写该用户密码；
  7. 点击 检查同步设置 或 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 归档。

小结

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

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

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

参考来源

© 2022 - 2026 KnightLi的博客
记录并分享
使用 Hugo 构建
主题 Stack 由 Jimmy 设计