运维

群晖 DSM 7.x 安装 Joplin Server：Container Manager 项目部署教程

整理在群晖 DSM 7.x 上通过 Container Manager 项目功能部署 Joplin Server 的方法，包括目录准备、Docker Compose 配置、APP_BASE_URL、首次登录、客户端同步、反向代理和外网访问建议。

在群晖 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：

  1. 点击左侧 项目；
  2. 点击 新增 或 Create；
  3. 项目名称填写 joplin-server；
  4. 路径选择刚才创建的 /docker/joplin；
  5. 来源选择 创建 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

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

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

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

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

后台操作：

  1. 进入 Users；
  2. 点击 Add user；
  3. 填写邮箱和密码；
  4. 保存。

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

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

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

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

  1. 进入 设置 或 Options / Settings；
  2. 打开 同步 或 Synchronization；
  3. 同步目标选择 Joplin Server；
  4. Joplin Server URL 填写前面配置的 APP_BASE_URL；
  5. 用户名填写管理员邮箱或普通用户邮箱；
  6. 密码填写对应账号密码；
  7. 点击 检查同步配置 或 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 域名。

大致流程是：

  1. 准备一个域名或 DDNS；
  2. 在路由器上把 443 端口转发到群晖；
  3. 在群晖 控制面板 -> 登录门户 -> 高级 -> 反向代理服务器 中新增规则；
  4. 来源填写 https://joplin.example.com:443；
  5. 目标填写 http://127.0.0.1:22300 或 http://群晖内网IP:22300；
  6. 为域名申请并绑定 HTTPS 证书；
  7. 把 Compose 里的 APP_BASE_URL 改成 https://joplin.example.com；
  8. 在 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 镜像或容器配置。镜像可以重新下载，数据库才是你的数据。

小结

在群晖 DSM 7.x 上安装 Joplin Server，核心步骤其实很少：

  • File Station 里准备 docker/joplin/postgres_data；
  • Container Manager 用项目功能创建 Compose；
  • 改好 POSTGRES_PASSWORD 和 APP_BASE_URL；
  • 首次登录后立刻修改管理员密码；
  • 客户端同步目标选择 Joplin Server；
  • 外网访问优先考虑 Tailscale / WireGuard，或者配置 HTTPS 反向代理。

真正容易踩坑的是 APP_BASE_URL。只要这个地址写对，数据库目录持久化做好，Joplin Server 在群晖上会是一套很稳定的私有笔记同步方案。

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