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 等 header，避免 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 中重新部署專案。

反向代理時，建議在自訂標題裡加入常見轉發 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 鏡像或容器設定。鏡像可以重新下載，資料庫才是你的資料。

小結

Joplin Server 的 Docker Compose 部署並不複雜，真正容易踩坑的地方主要是三處：

APP_BASE_URL 必須寫成客戶端實際存取的地址；
預設管理員密碼 admin 必須立刻修改；
沒有 SMTP 時，新使用者要去後台 Emails 頁面複製啟用連結。

內網使用時，http://IP:22300 就能完成同步。公網使用時，建議用 HTTPS 反向代理，並調好上傳大小限制。只要這幾步處理好，Joplin Server 就是一套很穩定的私有筆記同步方案。