維運

群暉 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 中重新部署專案。

反向代理時，建議在自訂標題裡加入常見轉發 header，例如：

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 設計