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


目录
一、需求背景
我需要一个自托管的笔记同步服务,把 Obsidian 里的笔记在多台设备间实时同步,要求:
数据完全掌握在自己手里,不依赖第三方云笔记服务;
支持 WebSocket 实时同步,而非定时轮询;
通过自己的域名 + HTTPS 访问,方便在外网设备上使用;
部署和维护尽量简单,最好能在一台已经装了 1Panel 的服务器上完成。
Fast Note Sync Service(FNS) 正好满足前三点:它是开源的 Obsidian 同步服务端,提供 Docker 镜像,支持 API + WebSocket 双通道。而 1Panel 自带 Docker Compose 编排、反向代理和证书管理,两者结合可以把部署成本降到很低。
图 1:整体拓扑示意——Obsidian 客户端 → 域名/HTTPS → 1Panel 反向代理 → FNS 容器。请替换为你自己的截图。
二、环境与前置条件
提示:如果你的域名同时配置了 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
注册管理员:首次访问需注册账号,该账号即管理员;
创建 Vault:登录后创建一个笔记库(Vault);
复制 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 中完成同步配置
在 FNS 管理面板重新复制 API 配置;
打开 Obsidian 的 Fast Note Sync 插件设置,将服务器地址从
http://IP:9000替换为https://ob.xxxx.xxx;粘贴 API 配置,保存并测试连接。
图 8:Obsidian 插件中填入域名与 API 配置。请替换为你的实际截图。
验证要点:
网页能通过域名打开 ≠ 同步正常,务必在 Obsidian 中实际触发一次同步,确认笔记双向更新;
若网页正常但同步失败,优先回头检查 4.2 节的 WebSocket 三行配置。
七、安全与维护建议
关闭公开注册:初始化完成后,在 FNS 配置文件中设置:
user:
register-is-enable: false
防止他人随意注册。
定期备份数据卷:
./storage与./config目录包含笔记与配置,建议纳入定期备份;保持 HTTPS:公网传输笔记数据务必全程加密;
记录证书续期方式:若用 DNS 账号自动验证,续期可自动化;若用手动 TXT 验证,需在到期前手动续期。
八、备选方案:Cloudflare Tunnel
如果服务器没有公网 IP,或不想开放入站端口,可使用 Cloudflare Tunnel:
在服务器运行
cloudflared;在 Cloudflare 面板创建隧道;
将域名指向:
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 插件设置等),并保证每张图有对应的图注。