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 等 header，避免 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的博客