在 1Panel 上⽤ Docker 部署 Fast Note Sync Service (FNS)并配置域名访问的完整教程

Administrator 4 阅读

本文记录一次完整的自托管笔记同步部署过程:在 1Panel 中通过 Docker Compose 部署 Fast Note Sync Service(FNS),配置反向代理实现域名访问,并解决 Let's Encrypt 申请证书时反复出现的 x509: cannot parse IP address of length 0 错误。全文按“需求 → 环境 → 部署 → 域名 → 证书排错 → 验证”的顺序展开,配置和命令可直接照做。


目录

  1. 需求背景

  2. 环境与前置条件

  3. 用 Docker Compose 部署 FNS

  4. 配置域名反向代理

  5. 申请 HTTPS 证书与排错

  6. 在 Obsidian 中完成同步配置

  7. 安全与维护建议

  8. 备选方案:Cloudflare Tunnel

  9. 总结

  10. 附录:检查清单与常用命令


一、需求背景

我需要一个自托管的笔记同步服务,把 Obsidian 里的笔记在多台设备间实时同步,要求:

  1. 数据完全掌握在自己手里,不依赖第三方云笔记服务;

  2. 支持 WebSocket 实时同步,而非定时轮询;

  3. 通过自己的域名 + HTTPS 访问,方便在外网设备上使用;

  4. 部署和维护尽量简单,最好能在一台已经装了 1Panel 的服务器上完成。

Fast Note Sync Service(FNS) 正好满足前三点:它是开源的 Obsidian 同步服务端,提供 Docker 镜像,支持 API + WebSocket 双通道。而 1Panel 自带 Docker Compose 编排、反向代理和证书管理,两者结合可以把部署成本降到很低。

图 1:整体拓扑示意——Obsidian 客户端 → 域名/HTTPS → 1Panel 反向代理 → FNS 容器。请替换为你自己的截图。


二、环境与前置条件

项目

说明

服务器

一台有公网 IPv4 的 Linux 服务器(示例为 Debian/Ubuntu 系)

面板

已安装 1Panel(本文基于 1Panel 当前稳定版)

容器运行时

1Panel 内置 Docker 与 Docker Compose

域名

示例域名 ob.xxxx.xxx,已添加 A 记录指向服务器公网 IP

客户端

Obsidian + Fast Note Sync 插件

提示:如果你的域名同时配置了 AAAA(IPv6)记录,而服务器 IPv6 实际不通,后续证书申请极易失败。建议先只保留 A 记录,见第五节。


三、用 Docker Compose 部署 FNS

3.1 进入编排页面

登录 1Panel,左侧菜单依次点击 容器 → 编排 → 创建编排。

图 2:1Panel「容器 → 编排」页面,点击「创建编排」。请替换为你的实际截图。

3.2 填写名称与 Compose 配置

为项目命名(例如 fns),在编辑器中粘贴以下配置:

services:
  fast-note-sync-service:
    image: haierkeys/fast-note-sync-service:latest
    container_name: fast-note-sync-service
    restart: always
    ports:
      - "9000:9000"   # Web 管理面板与 API 端口
      - "9001:9001"   # WebSocket 同步端口(新版建议一并映射)
    volumes:
      - ./storage:/fast-note-sync/storage  # 笔记与附件数据
      - ./config:/fast-note-sync/config    # 配置文件

说明:官方 Docker Run 示例有时只映射 9000,但 Compose 示例及新版 WebSocket 分离特性建议同时映射 9001。两者都映射可以避免“网页能开、同步不通”的问题。

3.3 部署并确认运行状态

点击部署后,回到 容器 列表,确认 fast-note-sync-service 状态为“运行中”。

图 3:容器列表中 FNS 状态为「运行中」。请替换为你的实际截图。

此时在浏览器访问:

http://服务器IP:9000

如果能看到 FNS 的管理界面,说明服务端已正常启动。

图 4:首次访问 FNS 管理面板,注册管理员账号的界面。请替换为你的实际截图。

3.4 初始化管理员与 Vault

  1. 注册管理员:首次访问需注册账号,该账号即管理员;

  2. 创建 Vault:登录后创建一个笔记库(Vault);

  3. 复制 API 配置:点击“复制 API 配置”,后续粘贴到 Obsidian 插件中。


四、配置域名反向代理

容器 IP 能访问后,接下来把域名指过去。FNS 依赖 WebSocket 做实时同步,反向代理必须正确传递 Upgrade 头,否则会出现“网页能打开、Obsidian 同步失败”。

4.1 创建反向代理网站

在 1Panel 左侧菜单进入 网站 → 创建网站,类型选 反向代理:

  • 主域名:ob.xxxx.xxx

  • 代理地址:http://127.0.0.1:9000

若容器使用独立 IP,则代理地址填:

http://容器IP:9000

图 5:1Panel 创建反向代理网站,填写域名与代理地址。请替换为你的实际截图。

4.2 确保 WebSocket 支持

进入该网站设置,找到 反向代理 或 配置文件,确认包含以下三行:

proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

这三行是 FNS 实时同步的关键。如果 1Panel 的“开启 WebSocket”开关没有生成 Connection "upgrade" 这一行,请手动补全后保存。

4.3 验证 HTTP 访问

此时用浏览器访问:

http://ob.xxxx.xxx

应能打开 FNS 管理界面。确认无误后,再进入证书配置环节。


五、申请 HTTPS 证书与排错

5.1 遇到的错误

在 1Panel 网站 SSL 选项卡中申请 Let's Encrypt 证书,选择 HTTP 验证,连续两次失败,日志如下:

2026/11/16 12:07:38 开始申请证书,域名 [ob.xxxx.xxx],方式 [HTTP]
2026/11/16 12:07:40 申请 [ob.xxxx.xxx] 证书失败,x509: cannot parse IP address of length 0

2026/11/16 12:11:58 开始申请证书,域名 [ob.xxxx.xxx],方式 [HTTP]
2026/11/16 12:12:00 申请 [ob.xxxx.xxx] 证书失败,x509: cannot parse IP address of length 0

x509: cannot parse IP address of length 0 不是 Let's Encrypt 直接返回的错误,而是 1Panel 底层证书工具(lego)在解析配置或网络响应时读到了空白的 IP 字段。常见诱因包括:服务器 IPv6 不可达、域名存在错误的 AAAA 记录、本地 DNS 解析异常等。

5.2 逐项排查与解决方案

① 禁用服务器 IPv6(最可能有效)

1Panel 官方文档提到,开启 IPv6 但实际不可达的机器容易导致证书申请失败,因为验证时会优先走 IPv6。SSH 登录服务器执行:

sysctl -w net.ipv6.conf.all.disable_ipv6=1
sysctl -w net.ipv6.conf.default.disable_ipv6=1

如需永久生效,写入 /etc/sysctl.conf:

cat >> /etc/sysctl.conf <<'EOF'
net.ipv6.conf.all.disable_ipv6=1
net.ipv6.conf.default.disable_ipv6=1
EOF

sysctl -p

执行后回 1Panel 重试申请。

② 清理域名解析记录

去域名 DNS 管理后台检查 ob.xxxx.xxx:

  • 若存在指向不通 IPv6 的 AAAA 记录,直接删除,只保留指向服务器公网 IPv4 的 A 记录;

  • 确认 A 记录指向的 IP 就是当前 1Panel 服务器的公网 IP,无填错或留空;

  • 若存在 CNAME 记录(尤其 CDN 相关),可能干扰验证,申请时可勾选“禁用 CNAME”。

图 6:域名 DNS 后台,删除错误的 AAAA 记录,仅保留正确的 A 记录。请替换为你的实际截图。

③ 在申请页面调整设置

  • 手动指定公共 DNS:在申请界面将 DNS 服务器填为 8.8.8.8 或 114.114.114.114,避开云服务器本地 DNS(如 127.0.0.53)的解析异常;

  • 勾选“跳过 DNS 验证”:有用户反馈在服务器有 IPv6 绑定的情况下,勾选此项后 HTTP 方式申请成功。

④ 切换验证方式(绕过 HTTP 验证)

如果 HTTP 方式持续报同一错误,改走 DNS 验证:

  • 手动解析验证:申请页面选“手动解析”,1Panel 生成一条 TXT 记录,手动到域名服务商后台添加后回面板确认。此方式不依赖服务器 HTTP 服务与 IP 解析,可绕开当前报错;

  • DNS 账号自动验证:若域名服务商在 1Panel 支持列表内(如阿里云、Cloudflare),配置 DNS 账号让 1Panel 自动添加记录,这是最稳定的长期方案。

⑤ 兜底方案

重启面板:

1pctl restart

然后立即重试申请。

也可以用 acme.sh 在命令行手动申请证书,将生成的 .crt 与 .key 上传到 1Panel「证书」管理,再绑定到网站,彻底绕开面板申请逻辑。

5.3 成功开启 HTTPS

证书申请成功后,在 SSL 选项卡启用证书并开启强制 HTTPS。此时访问:

https://ob.xxxx.xxx

应正常打开,浏览器地址栏显示锁标识。

图 7:浏览器访问 https://ob.xxxx.xxx 显示锁标识。请替换为你的实际截图。


六、在 Obsidian 中完成同步配置

  1. 在 FNS 管理面板重新复制 API 配置;

  2. 打开 Obsidian 的 Fast Note Sync 插件设置,将服务器地址从 http://IP:9000 替换为 https://ob.xxxx.xxx;

  3. 粘贴 API 配置,保存并测试连接。

图 8:Obsidian 插件中填入域名与 API 配置。请替换为你的实际截图。

验证要点:

  • 网页能通过域名打开 ≠ 同步正常,务必在 Obsidian 中实际触发一次同步,确认笔记双向更新;

  • 若网页正常但同步失败,优先回头检查 4.2 节的 WebSocket 三行配置。


七、安全与维护建议

  1. 关闭公开注册:初始化完成后,在 FNS 配置文件中设置:

user:
  register-is-enable: false

防止他人随意注册。

  1. 定期备份数据卷:./storage 与 ./config 目录包含笔记与配置,建议纳入定期备份;

  2. 保持 HTTPS:公网传输笔记数据务必全程加密;

  3. 记录证书续期方式:若用 DNS 账号自动验证,续期可自动化;若用手动 TXT 验证,需在到期前手动续期。


八、备选方案:Cloudflare Tunnel

如果服务器没有公网 IP,或不想开放入站端口,可使用 Cloudflare Tunnel:

  1. 在服务器运行 cloudflared;

  2. 在 Cloudflare 面板创建隧道;

  3. 将域名指向:

http://127.0.0.1:9000

FNS 服务端设置中也提供了对 Cloudflare Tunnel 的支持及连接保活验证。缺点是国内访问速度可能稍慢。


九、总结

本次部署的核心链路是:

Docker Compose 起 FNS
→ 反向代理绑域名并透传 WebSocket
→ 申请并启用 HTTPS
→ Obsidian 填域名完成同步

真正卡住进度的是证书申请阶段的 x509: cannot parse IP address of length 0,它本质上是 IP 解析异常(多为 IPv6 不可达或错误 AAAA 记录)导致的。按“禁用 IPv6 / 清理 AAAA / 换 DNS 验证”的顺序排查基本可以解决。希望这篇记录能帮到同样在自托管笔记同步路上踩坑的你。


十、附录:检查清单与常用命令

10.1 部署检查清单

  • 1Panel 已安装并正常运行

  • Docker Compose 编排已创建

  • 9000 端口可访问 FNS 管理面板

  • 9001 端口已映射,避免 WebSocket 同步异常

  • 域名 A 记录已指向服务器公网 IPv4

  • 不必要或错误的 AAAA 记录已删除

  • 反向代理已创建并指向 FNS 端口

  • Nginx 已包含 WebSocket 三行配置

  • HTTPS 证书已申请并启用

  • 已开启强制 HTTPS

  • Obsidian 插件已填入域名和 API 配置

  • 已实际触发一次双向同步验证

  • 已关闭公开注册

  • 已配置数据目录备份

10.2 常用排查命令

查看容器状态:

docker ps | grep fast-note-sync

查看容器日志:

docker logs -f fast-note-sync-service

测试域名解析:

dig ob.xxxx.xxx A
dig ob.xxxx.xxx AAAA

测试 HTTP 访问:

curl -I http://ob.xxxx.xxx

测试 HTTPS 访问:

curl -I https://ob.xxxx.xxx

重启 1Panel:

1pctl restart

临时禁用 IPv6:

sysctl -w net.ipv6.conf.all.disable_ipv6=1
sysctl -w net.ipv6.conf.default.disable_ipv6=1

图片占位说明:文中 images/xx.png 为占位路径,发布前请替换为你部署过程中实际截取的图片(1Panel 编排页、容器状态、反向代理配置、DNS 后台、HTTPS 成功页、Obsidian 插件设置等),并保证每张图有对应的图注。