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

Fri, 05 Jun 2026 21:31:17 +0800

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`

写入下面这份配置：

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`

默认密码是：

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 反向代理片段可以参考：

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 就是一套很稳定的私有笔记同步方案。

自托管 on KnightLi的博客