Supernote 私有云部署完整指南：从零到一在群晖上搭建私人同步服务器

一、写在前面

Supernote 是一款专注于书写体验的电纸书设备，官方提供云端同步功能。但对于注重数据隐私的用户来说，将笔记同步到自己的 NAS 上才是理想方案。本文记录了在群晖 DS923+ 上完整部署 Supernote 私有云服务的全过程，包括踩过的所有坑和解决方案。

适用环境：

• 群晖 DSM 7.x（已安装 Docker/Container Manager）
• 拥有公网 IP 和域名（已配置 DDNS）
• Supernote 设备（本文使用 Nomad）

二、部署架构

┌─────────────┐ HTTPS(9443) ┌─────────────┐
│  Supernote  │ ──────────► │    路由器    │
│    Nomad    │ ◄────────── │   端口转发   │
└─────────────┘ HTTPS(9443) └──────┬──────┘
                                   │
                               HTTPS(9443)
                                   ▼
┌─────────────┐ HTTP(19072) ┌─────────────┐
│ SynologyNAS │ ◄────────── │   反向代理   │
│  (DSM 7.x)  │             │ (Login Portal)│
└──────┬──────┘             └──────┬──────┘
       │                           │
       └───────────┬───────────────┘
                   │
           ┌───────┴───────┐
           │    Docker     │
           │   Container   │
           │    Manager    │
           └───────┬───────┘
                   │
     ┌─────────────┼───────────────┐
     │             │               │
     ▼             ▼               ▼
┌───────────┐ ┌───────────┐ ┌─────────────┐
│  mariadb  │ │   redis   │ │   notelib   │
│   :3306   │ │   :6379   │ │             │
└───────────┘ └───────────┘ └─────────────┘
     │              │              │
     └──────────────┼──────────────┘
                    │
            ┌───────┴───────┐
            │   supernote-  │
            │    service    │
            │     :19072    │
            └───────────────┘

三、准备工作

3.1 环境确认

项目	要求	检查方法
群晖型号	DS923+（其他支持 Docker 的型号亦可）	-
DSM 版本	7.x 及以上	控制面板 → 信息中心
Docker	已安装 Container Manager	套件中心搜索
域名	已配置 DDNS	控制面板 → 外部访问 → DDNS
SSL 证书	已获取 Let’s Encrypt 证书	控制面板 → 安全 → 证书

3.2 目录结构准备

通过 SSH 登录群晖，创建以下目录：

# 创建主目录
sudo mkdir -p /volume1/supernote/data
sudo mkdir -p /volume1/supernote/recycle
sudo mkdir -p /volume1/supernote/logs/cloud
sudo mkdir -p /volume1/supernote/logs/app
sudo mkdir -p /volume1/supernote/logs/web
sudo mkdir -p /volume1/supernote/convert
# 修改所有者（将"你的用户名"替换为实际用户名）
sudo chown -R 你的用户名:users /volume1/supernote
# 设置权限
sudo chmod -R 755 /volume1/supernote

3.3 权限设置的坑

⚠️ 坑点 1：File Station 中看不到新建的文件夹

在 SSH 中用 sudo 创建的目录，默认属于 root 用户，在群晖 File Station 中不可见。

解决方案：

sudo chown -R 你的用户名:users /volume1/supernote
sudo chmod -R 755 /volume1/supernote ```

⚠️ 坑点 2：Docker 容器无法写入数据
即使目录权限已设置，容器内服务仍可能因用户身份不匹配而无法写入。
解决方案：在 File Station 中为 supernote 文件夹设置 Everyone 的读写权限：

1. 右键文件夹 → 属性 → 权限
2. 添加 Everyone → 勾选读取和写入
3. 勾选"应用到子文件夹"

四、部署 Docker 容器

4.1 创建 docker-compose.yml

在 /volume1/supernote/ 目录下创建 docker-compose.yml 文件：

name: supernote
services:
  mariadb:
    image: mariadb:10.6.24
    container_name: supernote-mariadb
    networks:
      - supernote-net
    environment:
      MYSQL_ROOT_PASSWORD: "你的强密码"
      MYSQL_DATABASE: supernotedb
      MYSQL_USER: "supernote_user"
      MYSQL_PASSWORD: "你的数据库密码"
    volumes:
      - mariadb_data:/var/lib/mysql
      - ./supernotedb.sql:/docker-entrypoint-initdb.d/supernotedb.sql:ro
    restart: unless-stopped
  redis:
    image: redis:7.4.7
    container_name: supernote-redis
    networks:
      - supernote-net
    volumes:
      - redis_data:/data
    command: redis-server --requirepass '你的Redis密码' --dir /data --dbfilename dump.rdb
    restart: unless-stopped
  notelib:
    image: docker.io/supernote/notelib:6.9.3
    container_name: supernote-notelib
    networks:
      - supernote-net
    restart: unless-stopped
  supernote-service:
    image: docker.io/supernote/supernote-service:26.02.23
    container_name: supernote-service
    networks:
      - supernote-net
    ports:
      - "127.0.0.1:19072:8080"
    volumes:
      - /volume1/supernote/recycle:/home/supernote/recycle
      - /volume1/supernote/data:/home/supernote/data
      - /volume1/supernote/logs/cloud:/home/supernote/cloud/logs
      - /volume1/supernote/logs/app:/home/supernote/logs
      - /volume1/supernote/logs/web:/var/log/nginx
      - /volume1/supernote/convert:/home/supernote/convert
      - /etc/localtime:/etc/localtime:ro
    environment:
      MYSQL_DATABASE: supernotedb
      MYSQL_USER: "supernote_user"
      MYSQL_PASSWORD: "你的数据库密码"
      REDIS_HOST: redis
      REDIS_PORT: 6379
      REDIS_PASSWORD: "你的Redis密码"
    depends_on:
      - mariadb
      - redis
      - notelib
    restart: unless-stopped
networks:
  supernote-net:
    name: supernote-net
volumes:
  mariadb_data:
  redis_data:

非常重要！！ 一定要记得将上面yml文件中的数据库密码修改成自己的密码！
推荐通过password等等密码管理器生成密码后填入上面文件中

4.2 下载数据库初始化文件

  cd /volume1/supernote
  curl -O https://supernote-private-cloud.supernote.com/cloud/supernotedb.sql

4.3 配置国内镜像源（解决拉取超时问题）

⚠️ 坑点 3：Docker 镜像拉取超时
国内访问 Docker Hub 极不稳定，必须配置镜像加速。
解决方案：编辑 /etc/docker/daemon.json：

  sudo vi /etc/docker/daemon.json

添加以下内容（使用 2026 年实测可用的镜像源）：

{
  "registry-mirrors": [
    "https://docker.1ms.run",
    "https://docker.xuanyuan.me",
    "https://docker.m.daocloud.io"
  ]
}

重启 Docker 服务：

sudo synoservicecfg --restart docker

4.4 拉取镜像并启动

cd /volume1/supernote
sudo docker-compose up -d

⚠️ 坑点 4：Docker 权限不足
如果遇到 permission denied while trying to connect to the Docker daemon socket 错误：

# 将当前用户加入 docker 组
sudo synogroup --add docker 你的用户名
# 重新登录 SSH 使权限生效

4.5 验证服务状态

# 检查容器状态
sudo docker-compose ps
# 测试服务是否响应
curl -I http://127.0.0.1:19072

预期输出包含 HTTP/1.1 200 OK。

五、配置反向代理

5.1 DSM 反向代理设置

下面的工作就需要进入群晖NAS的DSM系统，在图形界面下进行了。

进入：Control Panel → Login Portal → Advanced → Reverse Proxy

点击 Create，填写以下内容：

配置项	值
Reverse Proxy Name	Supernote
Source Protocol	HTTPS
Source Hostname	www.yourdomain.com
Source Port	9443（或其他未被占用的端口）
Destination Protocol	HTTP
Destination Hostname	localhost
Destination Port	19072

⚠️ 坑点 5：目的地协议错误
千万注意：目的地协议必须是 HTTP，不是 HTTPS！容器内运行的是 HTTP 服务，用 HTTPS 会导致连接失败。

5.2 配置自定义请求头（WebSocket 支持）

在 Custom Header 选项卡中，点击 Create → WebSocket，会自动添加两条必要的 header：

Header Name	Value
Upgrade	$http_upgrade
Connection	$connection_upgrade

⚠️ 坑点 6：缺少 WebSocket 头导致同步失败
如果不配置这两条，Supernote 设备将无法自动同步。

5.3 SSL 证书配置

进入 Control Panel → Security → Certificate，为你的域名绑定 SSL 证书（建议使用 Let’s Encrypt 免费证书）。

⚠️ 坑点 7：端口 443 被占用
群晖默认占用 443 端口。解决方案：使用其他端口（如 9443），并在反向代理和路由器转发中保持一致。

六、配置路由器端口转发

登录路由器管理后台，添加端口转发规则：

配置项	值
外部端口	9443
内部 IP	群晖的局域网 IP
内部端口	9443

七、域名 DNS 配置
⚠️ 坑点 8：DNS 解析不完整

在域名 DNS 管理后台（Cloudflare/阿里云/腾讯云等），需要同时配置：

记录类型	主机记录	记录值
A	@	你的公网 IP
A	www	你的公网 IP

或者用 CNAME 记录将 @ 指向 www。

为什么需要两条？
• www.domain.com 和 domain.com 是不同的主机名
• 反向代理中配置的主机名必须与访问地址完全匹配

八、Supernote 设备端配置

8.1 退出官方账户

进入：设置 → 我的账号 → 退出登录

8.2 启用私有云

⚠️ 坑点 9：找不到私有云选项
私有云入口不在"云盘"中，而是在：
设置 → 安全与隐私 → 私有云

开启后填写：

配置项	值
服务器地址	https://www.yourdomain.com:9443
用户名	在私有云 Web 页面注册的账号
密码	对应的密码

8.3 注册账户

首次使用前需要在电脑浏览器中注册：

访问 https://www.yourdomain.com:9443

点击 Register

填写邮箱（建议 Gmail，部分邮箱收不到验证邮件）

设置密码

查收验证邮件完成注册

8.4 测试同步

在 Supernote 设备上：

新建一个测试笔记

手动触发同步

登录私有云 Web 页面，确认笔记已同步

九、版本选择的重要说明

⚠️ 坑点 10：使用错误的服务版本
Supernote 私有云服务有多个版本，功能差异显著：

版本	发布日期	关键特性	推荐度
25.09.19	2025年9月	早期版本，功能不完整	❌ 不推荐
25.11.24	2025年11月	支持私有云基础功能	⚠️ 可用但不完美
25.12.17	2025年12月	支持 HTTPS 自动同步	✅ 推荐
26.02.23	2026年3月	修复重要安全问题	✅ 强烈推荐

务必使用 26.02.23 或 25.12.17 版本，否则 HTTPS 自动同步可能无法正常工作。

十、完整操作命令速查

# 1. SSH 登录群晖
ssh 用户名@NAS_IP

# 2. 创建目录并设置权限
sudo mkdir -p /volume1/supernote/{data,recycle,logs/{cloud,app,web},convert}
sudo chown -R 用户名:users /volume1/supernote
sudo chmod -R 755 /volume1/supernote

# 3. 下载数据库文件
cd /volume1/supernote
curl -O https://supernote-private-cloud.supernote.com/cloud/supernotedb.sql

# 4. 配置 Docker 镜像源
sudo vi /etc/docker/daemon.json

# 添加 registry-mirrors 配置

# 5. 重启 Docker
sudo synoservicecfg --restart docker

# 6. 启动服务
sudo docker-compose up -d

# 7. 验证
sudo docker-compose ps
curl -I http://127.0.0.1:19072

十一、常见问题排查

问题现象	可能原因	解决方案
镜像拉取超时	国内网络问题	配置镜像加速源
File Station 看不到文件夹	目录属于 root	chown 修改所有者
容器无法写入数据	权限不足	设置 Everyone 读写权限
反向代理 404	主机名不匹配	检查来源主机名与访问域名一致
设备连接失败	目的地协议错误	改为 HTTP，不是 HTTPS
同步不自动	缺少 WebSocket 头	添加 Upgrade/Connection 头
外网无法访问	端口未转发	配置路由器端口转发
域名访问失败	DNS 解析不完整	添加 @ 记录的 A/CNAME

十二、总结

部署 Supernote 私有云的核心步骤：

• 准备环境：群晖 Docker + 域名 + SSL 证书
• 部署容器：四个服务（mariadb、redis、notelib、supernote-service）
• 配置反向代理：HTTPS 外网访问 → HTTP 本地服务
• 网络打通：路由器端口转发 + DNS 解析
• 设备连接：安全与隐私中开启私有云

整个过程中最容易踩的坑：

• 目录权限（chown 和 Everyone）
• 镜像源配置（国内必须加速）
• 反向代理目的地协议（HTTP 不是 HTTPS）
• DNS 解析（需要 @ 记录）
• 服务版本（必须用 26.02.23+）

附录：使用的端口清单

端口	用途	协议	是否暴露外网
19072	upernote-service 容器端口	HTTP	否（仅本地）
9443	反向代理外网访问端口	HTTPS	是
3306	MariaDB（可选，通常不暴露）	-	否
6379	Redis（可选，通常不暴露）	-	否

本文记录了完整的部署过程，希望能帮助后来者少走弯路。如有问题欢迎交流讨论。