Joplin 部署教程

Joplin 是一款开源的笔记管理工具，支持跨平台同步、Markdown 编辑、加密存储等功能。本教程将详细讲解 Joplin 服务端（Joplin Server）与客户端的部署流程，适用于个人或小型团队使用，涵盖环境准备、安装配置、同步测试等全环节。

1. 部署前准备

在开始部署前，需完成环境检查、工具安装及资源准备，确保后续步骤顺利进行。

1.1 确认硬件与系统要求

Joplin Server 对硬件要求较低，推荐配置如下：

CPU：1 核及以上（推荐 2 核，支持多用户并发）
内存：1GB 及以上（推荐 2GB，避免同步时内存不足）
存储：初始需 10GB 空闲空间（根据笔记数量动态扩容）
操作系统：支持 Linux（Ubuntu 20.04+/CentOS 8+）、Windows Server 2019+、macOS Server，本教程以 Ubuntu 22.04 LTS 为例。

1.2 安装必备工具

通过终端执行以下命令，安装部署所需的基础工具：

# 更新系统软件包
sudo apt update && sudo apt upgrade -y

# 安装 Docker 与 Docker Compose（推荐用 Docker 部署，简化依赖管理）
sudo apt install -y docker.io docker-compose-plugin

# 启动 Docker 服务并设置开机自启
sudo systemctl start docker
sudo systemctl enable docker

# 验证 Docker 是否安装成功（显示版本信息即正常）
docker --version
docker compose version

# （可选）添加当前用户到 docker 组，避免每次执行 docker 需 sudo
sudo usermod -aG docker $USER

# 注：添加后需重新登录终端生效

1.3 准备域名与端口（可选）

若需通过公网访问 Joplin Server，需准备一个域名（如 joplin.example.com），并将域名解析到服务器 IP。
开放必要端口：默认需开放 22（SSH，可选）、80（HTTP，用于 Let’s Encrypt 证书申请）、443（HTTPS，Joplin 同步端口）。执行以下命令开放端口：

sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable  # 启用防火墙（若未启用）
sudo ufw status   # 验证端口开放状态

2. Joplin Server 部署（Docker 方式）

Joplin 官方推荐用 Docker Compose 部署服务端，包含 PostgreSQL 数据库（存储笔记数据）和 Joplin Server 应用本身，步骤如下：

2.1 创建部署目录

首先创建一个专用目录，用于存放 Docker Compose 配置文件和数据：

# 创建主目录
mkdir -p /opt/joplin-server
cd /opt/joplin-server

# 创建数据子目录（用于持久化存储数据库和日志）
mkdir -p data/postgres logs

2.2 编写 Docker Compose 配置文件

在 /opt/joplin-server 目录下创建 docker-compose.yml 文件，内容如下（可根据需求调整参数）：

version: '3'

services:
  # PostgreSQL 数据库服务
  postgres:
    image: postgres:16-alpine  # 使用轻量的 Alpine 版本
    container_name: joplin-postgres
    restart: always  # 容器异常时自动重启
    environment:
      POSTGRES_USER: joplin  # 数据库用户名（自定义，建议保持 joplin）
      POSTGRES_PASSWORD: your_strong_postgres_password  # 数据库密码（替换为强密码）
      POSTGRES_DB: joplin  # 数据库名称（自定义，建议保持 joplin）
    volumes:
      - ./data/postgres:/var/lib/postgresql/data  # 数据持久化到本地目录
    networks:
      - joplin-network  # 加入自定义网络，与 Joplin Server 通信

  # Joplin Server 应用服务
  joplin-server:
    image: joplin/server:latest  # 使用最新版 Joplin Server
    container_name: joplin-server
    restart: always
    depends_on:
      - postgres  # 依赖 PostgreSQL 服务，确保数据库先启动
    environment:
      # 数据库连接配置（需与上方 PostgreSQL 参数一致）
      DB_CLIENT: pg
      DB_HOST: postgres
      DB_PORT: 5432
      DB_USER: joplin
      DB_PASSWORD: your_strong_postgres_password  # 与上方 POSTGRES_PASSWORD 相同
      DB_DATABASE: joplin
      
      # Joplin Server 核心配置
      APP_BASE_URL: https://joplin.example.com  # 替换为你的域名（含 https://）
      PORT: 22300  # Joplin Server 内部端口（默认 22300，无需修改）
      ADMIN_TOKEN: your_strong_admin_token  # 管理员令牌（用于初始化管理员账号，需自定义强密码）
    volumes:
      - ./logs:/home/joplin/logs  # 日志持久化到本地目录
    ports:
      - "22300:22300"  # 宿主机端口:容器端口（若需修改宿主机端口，左侧可改，如 8080:22300）
    networks:
      - joplin-network

# 自定义网络（隔离容器通信）
networks:
  joplin-network:
    driver: bridge

配置参数说明：

POSTGRES_PASSWORD 和 DB_PASSWORD：必须保持一致，建议使用大小写字母 + 数字 + 特殊符号的强密码（如 JoplinDB@2024!）。
APP_BASE_URL：若用公网访问，需填写域名（如 https://joplin.example.com）；若仅内网访问，可填写服务器内网 IP（如 http://192.168.1.100:22300）。
ADMIN_TOKEN：后续初始化管理员账号需用到，建议记录下来（如 Admin@Joplin2024!）。

2.3 启动 Joplin Server

在 /opt/joplin-server 目录下执行以下命令，启动服务：

# 后台启动容器（-d 表示后台运行）
docker compose up -d

# 查看容器运行状态（若 STATUS 为 Up，则启动成功）
docker compose ps

# 查看 Joplin Server 日志（确认是否有报错）
docker compose logs -f joplin-server

日志验证：若日志中出现 Server is running on port 22300，则表示 Joplin Server 启动成功。

2.4 配置 HTTPS 加密（可选，推荐公网访问时配置）

若通过公网访问，需配置 HTTPS 加密（避免数据明文传输），推荐用 Nginx Proxy Manager 实现（简化反向代理和证书申请）。

2.4.1 部署 Nginx Proxy Manager

在 /opt 目录下创建 nginx-proxy 目录，编写 docker-compose.yml：

version: '3'
services:
  app:
    image: 'jc21/nginx-proxy-manager:latest'
    restart: always
    ports:
      - '80:80'  # HTTP 端口（用于证书申请）
      - '443:443'  # HTTPS 端口（用户访问端口）
      - '81:81'  # Nginx Proxy Manager 管理界面端口
    volumes:
      - ./data:/data
      - ./letsencrypt:/etc/letsencrypt
    networks:
      - joplin-network  # 加入与 Joplin Server 相同的网络

networks:
  joplin-network:
    external: true  # 使用已有的 joplin-network 网络（避免重复创建）

启动 Nginx Proxy Manager：

1 2	`cd /opt/nginx-proxy docker compose up -d`

2.4.2 配置反向代理与 HTTPS 证书

访问 Nginx Proxy Manager 管理界面：在浏览器输入 http://服务器IP:81，默认账号密码为 admin@example.com / changeme，首次登录需修改密码。
添加反向代理：

点击左侧 Proxy Hosts → Add Proxy Host。
Domain Names：输入你的域名（如 joplin.example.com）。
Scheme：选择 http。
Forward Hostname / IP：输入 joplin-server（Docker 容器名，因在同一网络可直接访问）。
Forward Port：输入 22300（Joplin Server 内部端口）。
勾选 Cache Assets 和 Block Common Exploits（可选，增强性能和安全性）。

申请 HTTPS 证书：

点击 SSL 标签页 → Request a New SSL Certificate。
勾选 Force SSL（强制 HTTPS 访问）和 HTTP/2 Support（启用 HTTP/2）。
输入邮箱（用于证书到期提醒），勾选 I agree to the Let’s Encrypt Terms of Service。
点击 Save，等待证书申请完成（约 10 秒，需确保域名已解析到服务器 IP，且 80 端口开放）。

验证 HTTPS：在浏览器输入 https://joplin.example.com，若显示 “Joplin Server” 登录界面，且地址栏有小绿锁，则 HTTPS 配置成功。

3. Joplin Server 初始化（创建管理员账号）

Joplin Server 启动后，需通过 API 初始化管理员账号，步骤如下：

3.1 执行初始化命令

在服务器终端执行以下命令（需替换 APP_BASE_URL 和 ADMIN_TOKEN 为 docker-compose.yml 中配置的值）：

# 替换为你的配置
APP_BASE_URL="https://joplin.example.com"
ADMIN_TOKEN="your_strong_admin_token"

# 发送初始化请求（创建管理员账号，默认用户名 admin@localhost，密码 admin）
curl -X POST ${APP_BASE_URL}/api/users/register \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${ADMIN_TOKEN}" \
  -d '{"email":"admin@localhost","password":"admin","name":"Administrator"}'

成功验证：若返回 {“id”:1,”email”:”admin@localhost“,”name”:”Administrator”…}，则管理员账号创建成功。

3.2 登录 Joplin Server 管理界面

在浏览器访问 https://joplin.lxztzp.top（或 http://服务器IP:22300，内网访问时）。
输入管理员账号：admin@localhost，密码：admin，点击 Login。
首次登录会强制修改密码：输入原密码 admin，再输入新密码（建议与 ADMIN_TOKEN 区分，且为强密码），点击 Update Password。
进入管理界面后，可点击左侧 Users 管理用户（如创建普通用户）、Settings 查看服务器配置。

4. Joplin 客户端部署与同步配置

Joplin 客户端支持 Windows、macOS、Linux、Android、iOS 及网页版，以下以 Windows 客户端 为例，讲解安装与同步配置步骤。

4.1 下载并安装客户端

访问 Joplin 官网下载页：https://joplinapp.org/download/。
根据系统选择对应版本：Windows 选择 Joplin Desktop (Portable or Installer)，推荐下载安装版（.exe 文件）。
双击安装文件，按提示完成安装（默认下一步即可）。

4.2 配置客户端与服务端同步

打开 Joplin 客户端，首次启动会提示 “欢迎使用 Joplin”，点击 Skip（跳过向导）。
进入主界面后，点击顶部菜单栏工具 → 选项（或按 Ctrl+, 快捷键）。
在左侧导航栏选择同步，配置同步参数：

同步目标：选择 Joplin Server。
Joplin Server URL：输入你的服务端地址（如 https://joplin.example.com，公网访问）或 http://服务器IP:22300（内网访问）。
账号邮箱：输入管理员账号（如 admin@localhost）或普通用户邮箱（若已创建）。
密码：输入对应账号的密码（即 3.2 步修改后的密码）。

点击 检查同步配置，若提示 “同步配置已验证”，则配置正确；若报错，需检查服务端地址、账号密码是否正确，以及服务器端口是否开放。
点击确定保存配置，返回主界面，点击左侧工具栏的同步按钮（或按 Ctrl+S），开始首次同步（首次同步为空，后续创建笔记后会自动同步）。

4.3 移动端客户端配置（以 Android 为例）

在应用商店搜索 “Joplin”，下载并安装官方客户端（或从官网下载 APK）。
打开客户端，点击右上角设置图标 → 同步。
同步服务 选择 Joplin Server，输入 服务器 URL、邮箱、密码，点击验证。
验证通过后，点击同步按钮，即可与服务端同步笔记。

5. 常见问题与解决方案

5.1 服务端启动失败，日志提示 “数据库连接超时”

原因：PostgreSQL 服务未启动，或 DB_PASSWORD 与 POSTGRES_PASSWORD 不一致。
解决方案：

执行 docker compose ps 查看 joplin-postgres 容器是否为 Up 状态，若不是，执行 docker compose restart postgres 重启。
核对 docker-compose.yml 中 POSTGRES_PASSWORD 和 DB_PASSWORD 是否完全一致，修改后执行 docker compose up -d –force-recreate 重新创建容器。

5.2 客户端同步时报 “SSL 证书错误”

原因：HTTPS 证书未生效，或客户端未信任自签证书（若用自签证书）。
解决方案：

公网访问：确认 Nginx Proxy Manager 证书申请成功（管理界面中 SSL 状态为 OK），且域名解析正确。
内网访问：可暂时关闭 HTTPS（删除 Nginx 反向代理，直接用 http://服务器IP:22300 访问），或在客户端导入自签证书。

5.3 管理员账号忘记密码

解决方案：通过 API 重置密码，执行以下命令（替换 APP_BASE_URL、ADMIN_TOKEN 和新密码）：

curl -X PUT ${APP_BASE_URL}/api/users/1/password \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${ADMIN_TOKEN}" \
  -d '{"password":"new_strong_password"}'

其中 users/1 表示 ID 为 1 的用户（默认管理员账号 ID 为 1）。

6. 服务端维护与安全优化

6.1 数据备份

Joplin 数据主要存储在 PostgreSQL 数据库中，建议定期备份：

# 进入部署目录
cd /opt/joplin-server

# 备份 PostgreSQL 数据库（保存为 joplin_backup_日期.sql）
docker exec joplin-postgres pg_dump -U joplin joplin > ./data/backups/joplin_backup_$(date +%Y%m%d).sql

# （可选）压缩备份文件
gzip ./data/backups/joplin_backup_$(date +%Y%m%d).sql

可将上述命令添加到 crontab 中，实现自动备份（如每天凌晨 2 点备份）：

# 编辑定时任务
crontab -e
# 添加以下内容（每天 2:00 执行备份）
0 2 * * * cd /opt/joplin-server && docker exec joplin-postgres pg_dump -U joplin joplin > ./data/backups/joplin_backup_$(date +%Y%m%d).sql && gzip ./data/backups/joplin_backup_$(date +%Y%m%d).sql

6.2 服务端版本更新

Joplin Server 会定期发布新版本（修复漏洞、新增功能），建议定期更新，步骤如下（更新前务必先备份数据，参考 6.1 节）：

6.2.1 查看当前版本与最新版本

查看当前运行的 Joplin Server 版本：

1	`docker inspect --format '{{ index .Config.Labels "org.opencontainers.image.version" }}' joplin-server`

查看官方最新版本：访问 Joplin Server Docker 仓库，确认 latest 标签对应的版本（或指定具体版本号，如 2.12.1）。

6.2.2 执行更新操作

1	`docker inspect --format '{{ index .Config.Labels "org.opencontainers.image.version" }}' joplin-server`

验证更新：登录 Joplin Server 管理界面，点击右上角头像 → About，查看版本号是否与最新版一致。

6.3 安全优化进阶

6.3.1 限制访问 IP（仅允许指定 IP 访问）

若仅需内网或特定设备访问，可通过 ufw 限制端口访问来源：

# 进入部署目录
cd /opt/joplin-server

# 停止当前运行的容器
docker compose down

# 拉取最新镜像（若指定版本，需修改 docker-compose.yml 中 image 为 joplin/server:2.12.1）
docker pull joplin/server:latest

# 重新启动容器（自动使用新镜像）
docker compose up -d

# 查看更新后日志，确认无报错
docker compose logs -f joplin-server

6.3.2 容器安全配置

修改 docker-compose.yml，添加非 root 用户运行、限制容器权限等配置：

services:
  joplin-server:
    # 新增以下配置
    user: "1000:1000"  # 使用宿主机普通用户 UID:GID（避免 root 权限运行，执行 id 命令可查看当前用户 UID）
    cap_drop:
      - ALL  # 禁用所有 Linux 能力，减少攻击面
    read_only: true  # 容器文件系统设为只读（仅日志目录需可写，需调整 volumes 权限）
    volumes:
      - ./logs:/home/joplin/logs:rw  # 仅日志目录设为可写
      - /etc/timezone:/etc/timezone:ro  # 挂载时区文件（可选，确保容器与宿主机时区一致）
      - /etc/localtime:/etc/localtime:ro

修改后执行 docker compose up -d –force-recreate 生效。

6.3.3 日志监控与轮转

避免日志文件过大占满磁盘，可配置 logrotate 实现日志轮转：

创建日志轮转配置文件：

1	`sudo nano /etc/logrotate.d/joplin-server`

写入以下内容：

/opt/joplin-server/logs/*.log {
    daily          # 每天轮转一次
    rotate 7       # 保留 7 天的日志
    compress       # 压缩旧日志（gzip）
    delaycompress  # 延迟压缩（保留当天日志不压缩）
    missingok      # 日志文件不存在时不报错
    notifempty     # 日志为空时不轮转
    create 0644 root root  # 新建日志文件的权限和所有者
}

测试日志轮转是否生效：

1 2	`sudo logrotate -f /etc/logrotate.d/joplin-server ls /opt/joplin-server/logs/ # 查看是否生成压缩日志（如 app.log.1.gz）`

7. 数据迁移（服务器更换场景）

若需将 Joplin 数据迁移到新服务器，步骤如下：

7.1 旧服务器数据备份

按 6.1 节执行数据库备份，得到 joplin_backup_20240520.sql.gz（示例文件名）。
备份 docker-compose.yml 配置文件（方便新服务器复用参数）：

1	`cp /opt/joplin-server/docker-compose.yml ~/joplin-compose-backup.yml`

将备份文件（.sql.gz 和 docker-compose.yml）通过 scp 传到新服务器：

1
2
3

# 旧服务器执行，将文件传到新服务器的 /opt 目录
scp ~/joplin_backup_20240520.sql.gz root@新服务器IP:/opt/
scp ~/joplin-compose-backup.yml root@新服务器IP:/opt/

7.2 新服务器数据恢复

在新服务器按 1.2 节安装 Docker 与 Docker Compose，按 2.1 节创建部署目录。
将备份的 docker-compose.yml 复制到 /opt/joplin-server/，并修改 APP_BASE_URL、DB_PASSWORD 等参数（若新服务器域名 / IP 变更）。
启动 PostgreSQL 服务（仅启动数据库，不启动 Joplin Server）：

1
2
3

# 旧服务器执行，将文件传到新服务器的 /opt 目录
scp ~/joplin_backup_20240520.sql.gz root@新服务器IP:/opt/
scp ~/joplin-compose-backup.yml root@新服务器IP:/opt/

解压备份文件并恢复到数据库：

# 解压备份文件
gzip -d /opt/joplin_backup_20240520.sql.gz

# 将备份文件复制到 PostgreSQL 容器内
docker cp /opt/joplin_backup_20240520.sql joplin-postgres:/tmp/

# 执行恢复命令（需输入数据库密码，即 docker-compose.yml 中的 DB_PASSWORD）
docker exec -it joplin-postgres psql -U joplin -d joplin -f /tmp/joplin_backup_20240520.sql

恢复完成后，启动 Joplin Server 并验证：

1
2
3

docker compose up -d
# 查看日志确认无报错，登录客户端验证数据是否完整
docker compose logs -f joplin-server

8. Joplin Server 卸载

若需停止并卸载 Joplin Server，步骤如下（卸载前建议备份数据）：

# 1. 停止并删除容器
cd /opt/joplin-server
docker compose down

# 2. 删除部署目录（含数据和配置，谨慎操作！）
sudo rm -rf /opt/joplin-server

# 3. （可选）删除 Nginx Proxy Manager（若已部署）
cd /opt/nginx-proxy
docker compose down
sudo rm -rf /opt/nginx-proxy

# 4. （可选）删除 Docker 镜像（释放空间）
docker rmi joplin/server:latest postgres:16-alpine jc21/nginx-proxy-manager:latest

9. 进阶常见问题补充

9.1 客户端同步速度慢

原因：服务器带宽不足、数据库索引未优化、同步文件过大（如附件）。
解决方案：

检查服务器带宽：通过 iftop 命令查看网络占用，升级带宽（公网场景）。
优化数据库索引：

docker exec -it joplin-postgres psql -U joplin -d joplin
# 执行索引优化命令（Joplin 数据库默认已建索引，若异常可重建）
REINDEX DATABASE joplin;
\q  # 退出数据库

拆分大附件：在客户端将超过 100MB 的附件压缩为分卷压缩包，再上传同步。

9.2 服务端频繁崩溃（OOM 内存溢出）

原因：服务器内存不足，Joplin Server 进程被系统杀死。
解决方案：

查看内存使用：free -h，若内存不足（如可用内存 < 512MB），升级服务器内存。
限制容器内存：修改 docker-compose.yml，为 Joplin Server 添加内存限制：

services:
  joplin-server:
    deploy:
      resources:
        limits:
          memory: 1G  # 限制最大使用 1GB 内存

重启容器：docker compose up -d –force-recreate。

blog > Docker技术

#joplin

Joplin 部署教程

http://tanzipeng.github.io/p/0de5eb0a73b24251b0570ed287206854/

作者

Tan ZiPeng

发布于

2025年9月11日

许可协议

提示词模板上一篇

Terraria 开服指南下一篇