Debian VPS 使用 Docker 部署 Joplin Server 全流程实战教程

发表于 更新于 分类于 ， ， 阅读次数： 评论数：

Debian VPS 使用 Docker 部署 Joplin Server 全流程实战教程

一篇从 0 到 1 的 Joplin Server 私有化部署实战博客，适合个人知识库、团队笔记、多端同步场景。

一、为什么要自建 Joplin Server？

如果你正在使用 Joplin 作为主力笔记工具，自建 Joplin Server 会带来这些好处：

  • 🔐 数据完全掌控（不依赖第三方云）

  • ⚡ 同步速度快（VPS 本地直连）

  • 👥 支持多用户协作

  • 📦 兼容全平台客户端（Windows / macOS / Linux / iOS / Android）

  • 🔄 原生端到端加密（E2EE）

本文采用 Docker + PostgreSQL，这是官方最推荐、也是最稳定的部署方式。

二、环境准备

1️⃣ 系统与基础条件

  • Debian 11 / Debian 12

  • 一台公网 VPS（1C1G 即可）

  • 已解析的域名（可选，但强烈建议）

2️⃣ 更新系统

1
2
apt update && apt upgrade -y

三、安装 Docker 与 Docker Compose

安装 Docker

1
2
3
4
5
curl -fsSL https://get.docker.com | bash

systemctl enable docker
systemctl start docker

安装 Docker Compose Plugin

1
2
apt install docker-compose-plugin -y

验证：

1
2
docker compose version

四、创建 Joplin Server 目录

1
2
3
mkdir -p /opt/joplin-server
cd /opt/joplin-server

五、编写 docker-compose.yml

新建文件：

1
2
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-postgres
    restart: unless-stopped
    volumes:
      - ./postgres:/var/lib/postgresql/data
    environment:
      POSTGRES_PASSWORD: joplin_db_password
      POSTGRES_USER: joplin
      POSTGRES_DB: joplin

  app:
    image: joplin/server:latest
    container_name: joplin-server
    restart: unless-stopped
    depends_on:
      - db
    ports:
      - "22300:22300"
    environment:
      APP_PORT: 22300
      APP_BASE_URL: https://joplin.example.com
      DB_CLIENT: pg
      POSTGRES_PASSWORD: joplin_db_password
      POSTGRES_DATABASE: joplin
      POSTGRES_USER: joplin
      POSTGRES_HOST: db

关键参数说明

| 参数 | 说明 |

| —————– | —————— |
| APP_BASE_URL | 必须与访问地址完全一致 |

| POSTGRES_PASSWORD | 数据库密码，务必修改 |
| 22300 | Joplin Server 默认端口 |

六、启动 Joplin Server

1
2
docker compose up -d

查看状态：

1
2
docker compose ps

查看日志：

1
2
docker logs -f joplin-server

出现以下信息说明启动成功：

1
2
3

Server is running on port 22300

七、配置 Nginx 反向代理（推荐）

安装 Nginx

1
2
apt install nginx -y

创建站点配置

1
2
nano /etc/nginx/sites-available/joplin

1
2
3
4
5
6
7
8
9
10
11
12
13
server {
    listen 80;
    server_name joplin.example.com;

    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;
    }
}

启用站点：

1
2
3
ln -s /etc/nginx/sites-available/joplin /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx

八、启用 HTTPS（Let’s Encrypt）

1
2
3
apt install certbot python3-certbot-nginx -y
certbot --nginx -d joplin.example.com

✔ 自动配置 HTTPS
✔ 自动续期证书

九、初始化 Joplin 管理后台

浏览器访问：

1
2
3

https://joplin.example.com

默认管理员账号：

1
2
3
4

邮箱：admin@localhost
密码：admin

⚠️ 首次登录后立即修改密码

十、Joplin 客户端同步配置

客户端 → 设置 → 同步

| 项目 | 填写内容 |

| ———- | ——————————————————– |
| 同步目标 | Joplin Server |

| Server URL | https://joplin.example.com |
| Email | 用户邮箱 |

| Password | 用户密码 |

点击 检查同步配置 → 成功

十一、升级与维护

升级 Joplin Server

1
2
3
4
cd /opt/joplin-server
docker compose pull
docker compose up -d

数据备份建议

1
2
docker exec -t joplin-postgres pg_dump -U joplin joplin > joplin_backup.sql

十二、常见问题排查

登录白屏 / 502

1
2
docker logs joplin-server

无法连接数据库

  • POSTGRES_PASSWORD 是否一致

  • POSTGRES_HOST 是否为 db

  • postgres 容器是否正常

同步失败

  • APP_BASE_URL 是否正确

  • 是否混用 http / https

十三、进阶玩法

  • ☁️ 对接 S3 / MinIO 存储

  • 👥 多人协作笔记

  • 🔐 Cloudflare Tunnel 隐藏端口

  • 🧠 与 Nextcloud/WebDAV 迁移对比

  • 📝 写作型 Markdown 知识库

结语

至此，你已经拥有了一套 完全私有、可控、安全的 Joplin Server 服务端。对于长期写作、技术笔记、个人知识管理来说，这是非常值得的一次部署。