server-deploy/joplin/README.md

Joplin Server 部署指南

开源笔记同步服务器，支持端到端加密，配合 Joplin 客户端实现多端同步。

功能特性

• 多端同步（Windows / macOS / Linux / Android / iOS）
• 端到端加密（E2EE）
• Markdown 编辑，完整笔记本管理
• Web Clipper 浏览器剪藏
• REST API 扩展
• 丰富的插件生态

技术栈

组件	版本	说明
Joplin Server	latest	笔记同步服务器
PostgreSQL	16-alpine	关系型数据库
Nginx	系统包	反向代理 + HTTPS 接入
Docker	最新版	容器运行环境

前置条件

1. 一台 Linux 服务器（Ubuntu 22.04/24.04 推荐）
2. 一个已解析到服务器的域名（如 joplin.example.com）
3. 服务器 80/443 端口可从外网访问
4. 至少 512MB 可用内存（PostgreSQL + Joplin Server）

目录结构

joplin/
├── docker-compose.yml    # 容器编排（Joplin Server + PostgreSQL）
├── .env.example          # 配置模板
├── deploy.sh             # 一键部署脚本
├── backup.sh             # 备份脚本
├── uninstall.sh          # 完全卸载脚本
├── nginx/
│   └── joplin.conf       # Nginx 反向代理配置
└── README.md             # 本文件

服务器上的数据目录：

/data/joplin/db/          # PostgreSQL 数据
/var/backups/joplin/      # 备份文件

快速部署

第一步：上传文件到服务器

# 在本地执行，上传 joplin 目录
scp -r joplin/ root@<服务器IP>:/opt/joplin

# 如果服务器上还没有部署过 base（首台服务或全新服务器），还需上传 base
scp -r base/ root@<服务器IP>:/opt/base

第二步：登录服务器执行部署

ssh root@<服务器IP>

# 如果是全新服务器，先安装基础环境
cd /opt/base
cp .env.example .env
# 可选：编辑 .env 配置 Docker 镜像加速
bash setup.sh

# 部署 Joplin Server
cd /opt/joplin
bash deploy.sh
# 首次运行会生成 .env，按提示修改配置后重新运行
vi .env
bash deploy.sh

第三步：配置域名解析

在域名服务商（如阿里云 DNS）添加 A 记录：

记录类型	主机记录	记录值
A	joplin	<服务器公网IP>

第四步：登录管理后台

1. 浏览器访问 https://joplin.yourdomain.com
2. 默认账号: admin@localhost
3. 默认密码: admin

⚠️ 安全提醒：请立即登录并修改默认密码！

配置说明

.env 配置项

变量	说明	默认值
JOPLIN_DOMAIN	访问域名	必填
CERTBOT_EMAIL	Let's Encrypt 邮箱	必填
POSTGRES_PASSWORD	数据库密码	必填
POSTGRES_DATABASE	数据库名	joplin
POSTGRES_USER	数据库用户	joplin
JOPLIN_IMAGE	Joplin Server 镜像	joplin/server:latest
POSTGRES_IMAGE	PostgreSQL 镜像	postgres:16-alpine
JOPLIN_DB_DIR	数据库数据目录	/data/joplin/db
BACKUP_DIR	备份目录	/var/backups/joplin
MAILER_ENABLED	启用邮件	0

客户端配置

桌面端（Windows / macOS / Linux）

1. 下载 Joplin 桌面客户端：https://joplinapp.org/help/install
2. 打开设置 → 同步
3. 同步目标选择 Joplin Server
4. 填写：
   • 服务器 URL: https://joplin.yourdomain.com
   • 邮箱: admin@localhost（或你修改后的邮箱）
   • 密码: 你的登录密码
5. 点击「检查同步配置」确认连接成功

Android

从以下渠道下载 Joplin Android 客户端：

• GitHub Releases: https://github.com/laurent22/joplin-android/releases （下载 .apk）
• F-Droid: 搜索 "Joplin"
• Google Play: 搜索 "Joplin"

同步配置与桌面端相同。

iOS

从 App Store 搜索 "Joplin" 下载，同步配置与桌面端相同。

启用端到端加密（推荐）

1. 在任意一个客户端中：设置 → 加密 → 启用端到端加密
2. 设置加密密码（务必牢记，丢失无法恢复数据）
3. 其他客户端同步后会提示输入加密密码

注意：启用 E2EE 后，Web 界面将无法查看笔记内容（因为服务器无法解密），仅客户端可用。

日常运维

查看日志

cd /opt/joplin
docker compose logs -f
docker compose logs -f joplin      # 仅 Joplin Server
docker compose logs -f joplin-db   # 仅 PostgreSQL
docker compose logs --tail 100

备份

cd /opt/joplin
bash backup.sh

备份内容包括：

• PostgreSQL 数据库（使用 pg_dump，格式为 custom）
• 部署配置（docker-compose.yml + .env + nginx/）

备份文件保存在 /var/backups/joplin/，自动清理 30 天前的旧备份。

恢复备份

# 查看可用备份
ls /var/backups/joplin/

# 确保容器运行中
cd /opt/joplin && docker compose up -d

# 恢复数据库
docker compose exec -T joplin-db pg_restore \
    -U joplin -d joplin --clean \
    < /var/backups/joplin/<日期>/joplin-db.dump

# 重启服务
docker compose restart

升级

cd /opt/joplin

# 1. 备份当前数据
bash backup.sh

# 2. 拉取新镜像
docker compose pull

# 3. 停止旧容器并启动新容器
docker compose down
docker compose up -d

# 4. 检查运行状态
docker compose ps
docker compose logs --tail 20

停止 / 启动

cd /opt/joplin
docker compose down      # 停止
docker compose up -d     # 启动
docker compose restart   # 重启

用户管理

创建新用户

1. 以管理员登录 Web 界面
2. 进入「Admin」→「Users」→「Add user」
3. 填写邮箱和密码

修改管理员密码

1. 以 admin@localhost 登录 Web 界面
2. 点击右上角用户图标 → Profile
3. 修改密码

完全卸载

如果需要从服务器上完全移除 Joplin Server，使用卸载脚本：

cd /opt/joplin
bash uninstall.sh

脚本会交互式确认每个危险操作，按顺序执行：

步骤	操作	确认方式
0	卸载前备份（可选）	y/N
1	停止并删除 Joplin + PostgreSQL 容器	输入 YES
2	删除 Docker 镜像	自动
3	删除 Nginx 站点配置并重载	自动
4	删除 Let's Encrypt SSL 证书	自动
5	清理 Certbot 定时任务（仅当无其他证书时）	自动
6	删除数据目录	输入 DELETE
7	删除部署目录 /opt/joplin	y/N

备份目录 /var/backups/joplin/ 始终保留，不会被删除。

手动卸载步骤（不使用脚本）

cd /opt/joplin

# 1. 建议先备份
bash backup.sh

# 2. 停止并删除容器
docker compose down -v

# 3. 删除 Docker 镜像（可选）
docker image rm joplin/server:latest postgres:16-alpine

# 4. 删除 Nginx 配置
rm -f /etc/nginx/sites-enabled/joplin /etc/nginx/sites-available/joplin
nginx -t && systemctl reload nginx

# 5. 删除 SSL 证书
certbot delete --cert-name 你的域名

# 6. 删除数据目录（⚠ 不可恢复）
rm -rf /data/joplin

# 7. 删除部署目录（可选）
rm -rf /opt/joplin

# 备份目录保留在 /var/backups/joplin/

故障排查

容器无法启动

# 查看容器状态
docker compose ps

# 查看详细日志
docker compose logs --tail 50

# 常见原因：PostgreSQL 密码不一致
# 解决：删除数据库目录并重建
docker compose down -v
rm -rf /data/joplin/db
docker compose up -d

SSL 证书申请失败

# 检查域名解析是否正确
dig joplin.yourdomain.com

# 检查 80 端口是否可访问
curl -I http://joplin.yourdomain.com

# 查看 Certbot 日志
cat /var/log/letsencrypt/letsencrypt.log

访问返回 502

# 检查容器是否运行
docker compose ps

# 检查 22300 端口
curl -I http://127.0.0.1:22300/api/ping

# 检查 Nginx 配置
nginx -t

客户端同步失败

# 检查服务器是否正常响应
curl https://joplin.yourdomain.com/api/ping

# 应返回类似：{"status":"ok","message":"Joplin Server is running"}

# 检查服务器日志
cd /opt/joplin && docker compose logs --tail 50 joplin

上传大文件失败

Nginx 默认配置已设置 client_max_body_size 200m。如需调整：

# 修改 /etc/nginx/sites-available/joplin 中的 client_max_body_size
vi /etc/nginx/sites-available/joplin
nginx -t && systemctl reload nginx

端口说明

端口	协议	说明
80	TCP	HTTP → HTTPS 重定向
443	TCP	HTTPS（Nginx 反向代理）
22300	TCP	Joplin Server HTTP（仅监听 127.0.0.1）