維運

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 等 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 歸檔。

小結

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

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

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

參考來源

© 2022 - 2026 KnightLi的博客
记录并分享
使用 Hugo 建立
主題 Stack 由 Jimmy 設計