Joplin Server 登录失败？99% 的人都踩在 PostgreSQL 权限这个坑里

Joplin Server 登录失败？99% 的人都踩在 PostgreSQL 权限这个坑里

一份不踩坑的 Joplin Server + PostgreSQL Docker 部署模板

适用场景：

• Debian / Ubuntu VPS
• NAS / 家用服务器
• Docker / Docker Compose
• 不想再被权限、登录、同步问题折磨

一、推荐目录结构（先把坑挖对）

/joplin
├── docker-compose.yml
├── .env
├── postgres-data/ # PostgreSQL 数据目录
└── joplin-data/ # Joplin Server 数据目录（可选）

📌 关键原则

• 数据目录 只给容器用
• 不要混进 Web 面板、Nginx、宝塔目录
• 不要图省事放在 /root

二、.env 文件（强烈推荐）

# PostgreSQL
POSTGRES_DB=joplin
POSTGRES_USER=joplin
POSTGRES_PASSWORD=strong_password_here

# Joplin Server
APP_BASE_URL=https://joplin.example.com
APP_PORT=22300

📌 好处：

• 不明文写进 compose
• 以后改配置不用动主文件
• 更像“生产环境”

三、docker-compose.yml（核心模板）

这份是「可以直接跑」的版本

version: "3.9"

services:
postgres:
image: postgres:15
container_name: joplin–postgres
restart: unless–stopped
environment:
POSTGRES_DB: ${POSTGRES_DB}
POSTGRES_USER: ${POSTGRES_USER}
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
volumes:
– ./postgres–data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER}"]
interval: 10s
timeout: 5s
retries: 5

joplin:
image: joplin/server:latest
container_name: joplin–server
depends_on:
postgres:
condition: service_healthy
restart: unless–stopped
environment:
APP_BASE_URL: ${APP_BASE_URL}
APP_PORT: ${APP_PORT}
DB_CLIENT: pg
POSTGRES_HOST: postgres
POSTGRES_PORT: 5432
POSTGRES_DATABASE: ${POSTGRES_DB}
POSTGRES_USER: ${POSTGRES_USER}
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
ports:
– "22300:22300"

四、🔥 最关键的一步：权限初始化（99% 的坑在这）

在第一次启动前，一定要执行：

cd /joplin

mkdir -p postgres-data
sudo chown -R 999:999 postgres-data
sudo chmod -R 700 postgres-data

为什么是 999:999？

• PostgreSQL 官方镜像运行用户：

  postgres (UID 999)

📌 这是你之前遇到：

could not open file "base/16384/xxxx": Permission denied

的根本原因。

五、启动服务（标准流程）

docker compose up -d

查看状态：

docker compose ps

你应该看到：

• joplin-postgres → healthy
• joplin-server → running

六、首次登录 & 初始化

https://joplin.example.com

或（没上反代）：

http://服务器IP:22300

email: admin@localhost
password: admin

• 修改管理员密码
• 新建普通用户
• 不要长期用 admin 同步

七、为什么这个模板「不容易翻车」

✅ 1️⃣ 明确 UID 权限

• 不用 chmod 777
• 不用 root 运行数据库
• PostgreSQL 官方推荐方式

✅ 2️⃣ 使用 healthcheck

depends_on:
postgres:
condition: service_healthy

避免：

Joplin 启动时数据库还没准备好 → 各种诡异错误

✅ 3️⃣ 环境变量清晰可控

• DB_CLIENT 强制 pg
• HOST 用 service name（postgres）
• 不走 localhost，不走 IP

八、反向代理（可选，但强烈推荐）

Nginx 示例（核心即可）：

location / {
proxy_pass http://127.0.0.1:22300;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-For $remote_addr;
}

并确保：

APP_BASE_URL=https://joplin.example.com

📌 否则同步 token、附件 URL 会出问题

九、升级方式（安全）

docker compose pull
docker compose down
docker compose up -d

📌 不要删数据目录
📌 不要随便换 Postgres 大版本

十、快速排错清单（收藏级）

十一、一句话总结（模板精髓）

Joplin Server 稳不稳，不在配置多复杂，
在于：PostgreSQL 的数据目录权限有没有一开始就做对。