服务器部署可道云实现文档在线查看及分享，并通过syncthing实时同步文件

背景与选型

我有一台刷了 [[低配电脑变超低功耗，功能全的Linux服务器 | Ubuntu 24.04]] 系统的家庭服务器，并部署了可道云（Kodbox），实现在外网通过域名随时查看本地文档、在线预览和分享。

为什么选可道云而不是别的？ 核心原因是部署后可道云能直接在线预览 Office 系文档（Word / Excel / PPT）。我之前尝试过 Nextcloud、Cloudreve 等开源云盘，它们对文档预览的支持都需要额外部署 OnlyOffice 等服务：虽然最终也能跑起来，但在网络和服务器配置一般的情况下会明显卡顿，而且在云盘或插件升级后，经常冒出各种难以排查的问题。可道云把文档预览做成了内置能力，省去一堆折腾，对"就想方便看文档"的人来说更省心。

这个"卡"到底卡在哪？ 值得说清楚，因为这决定你该选哪个：

• Nextcloud 是 PHP 应用，每个请求都要走一遍 PHP-FPM → 框架加载 → 数据库查询的完整链路，本身就不算轻

• 更关键的是文档预览要靠外挂服务：OnlyOffice Document Server 或 Collabora 是独立进程（Node/Java 实现），自己就要吃 1-2 GB 内存，还要和云盘之间做一次"取文件 → 渲染 → 回传"的跨服务调用。小内存机器上这一跳就是卡顿的来源

• 可道云同样是 PHP，但它把文档预览做成了内置模块，少了跨服务调用这一跳

所以结论不是"可道云技术更强"，而是少一跳服务、少一个升级面。后者其实更重要：多一个独立组件，就多一个版本兼容的坑 —— 云盘升级、插件没跟上、接口变了，报错还特别难查。对家用场景来说，"少依赖"比"功能多"更值钱。

部署可道云

整个部署我借助 1Panel 应用商店完成，步骤很少：

1. 打开 1Panel 的应用商店，搜索并安装 kodbox、redis、mariadb 三个应用。其中 kodbox 是主程序，redis 和 mariadb 分别作为缓存与数据库，是它的运行依赖。

2. 在已安装的 mariadb 里新建一个数据库，并创建一个专用账号，记录下数据库名、用户名和密码，后面配置要用。

3. 启动 kodbox，在初始化向导里填入刚才的数据库信息，完成部署。

4. 更新系统 / 升级应用，否则有些依赖插件无法正常启动。可道云某些功能模块对运行环境版本有要求，保持系统更新能避免很多奇怪的报错。

为什么必须单独建数据库和账号？ 不要图省事用 root 账号连库。可道云只是一个应用，它不需要数据库管理员权限；一旦应用被攻破，用专用低权限账号只能读写自己那一个库，用 root 则是整个数据库实例沦陷。这是"最小权限"原则在自托管里最常见的落地方式。

另外，redis 在这里承担的是缓存和会话，可道云大量依赖它做文件列表缓存与并发锁。Redis 挂了会表现为"登录后立刻掉线"或"刷新卡住" —— 遇到这类怪现象，先检查 redis 容器是否正常。

通过 IPv6 访问本地文件

服务器通常没有公网 IPv4，我选择走 IPv6 + Lucky 插件的路线实现外网访问：参考"使用 lucky 插件，通过 ipv6 访问本地服务器"一文，把可道云的 Web 端口通过 Lucky 反向代理映射到自己的域名上。这样在外面用手机或电脑打开域名就能访问家里的文档。

安装 syncthing（实现双向同步）

这里有个关键痛点：可道云自带的客户端只有"单向增量同步"——电脑端修改的文件能同步到服务器，但服务器上修改的文件无法同步回电脑端。这对我这种"在家和公司都要改同一份文件"的场景不够用。因此我引入 Syncthing 实现双向实时同步，保证无论在哪台设备上改，另一台都能同步到最新版本。

单向 vs 双向，差别比想象中大：

双向同步并不是"把单向反过来"这么简单 —— 一旦两端都能改，就必然存在"同一时刻两边都改了同一个文件"的情况。Syncthing 的解法不是自动合并（它没法知道你的语义），而是保留两份、生成冲突文件让你手动处理。所以用双向同步之前，先接受一个事实：它会给你制造偶尔的"冲突文件"，这是功能特性，不是 bug。

1. 服务器端安装 syncthing，用 docker 一条命令拉起：

docker run -d --name syncthing --restart unless-stopped -e TZ=Asia/Shanghai -p 8384:8384 -p 22000:22000/tcp -p 22000:22000/udp -p 21027:21027/udp -v /mnt/mydisk/tools/syncthing:/var/syncthing -v /mnt:/mnt:rslave syncthing/syncthing

端口说明：8384 是 Web 管理界面，22000 用于设备间数据传输（TCP/UDP），21027 是局域网自动发现端口。若跨设备同步，这几处都要在防火墙放行。

rslave 这个参数是什么？ 它是挂载传播模式：-v /mnt:/mnt:rslave 的意思是"允许容器内对 /mnt 下子挂载的变化传播回宿主机"。为什么要加？因为服务器 /mnt 下面往往挂着多块磁盘 / 网络共享，而 Docker 启动容器时会"快照"当时的挂载状态 —— 如果不加 rslave，后挂上的盘在容器里是看不见的。这就是"明明插了新硬盘，Syncthing 里就是找不到目录"的原因，加个参数就解决。

Syncthing 为什么不需要公网 IP / 端口映射？ 它的连接策略是分层的：先尝试局域网直连（利用 21027 的 UDP 广播发现同一网段的设备，速度最快）；跨网络时尝试 NAT 打洞直连；都失败才退回**公共中继节点（relay）**转发。所以哪怕你两台机器都在严格 NAT 后面，它也能同步 —— 只是走中继时速度会受中继带宽限制。理解这一点，你就能解释"为什么有时候同步很快、有时候很慢"。

2. 通过 IPv6 + Lucky 方式给 Syncthing 的 Web 界面配置外网域名，方便在外网管理（参考上文链接）。

3. 电脑端安装 syncthing：到 https://syncthing.net/downloads/ 下载对应系统版本，解压后运行 syncthing.exe，浏览器访问 http://127.0.0.1:8384/ 即可打开设置页面。

4. 电脑端设置开机自启：打开 syncthing.exe 所在文件夹，新建一个文档，把文件名改为 syncthing.vbs，编辑内容为：

CreateObject("wscript.shell").run "syncthing.exe -no-browser",0

按下 win+R，输入 shell:startup 打开系统的"启动"文件夹，把 syncthing.vbs 复制进去。这样每次开机 Syncthing 都会静默后台运行（-no-browser 表示不自动弹浏览器），省去手动启动的麻烦。

有个安全提醒：Syncthing 的 8384 界面本身没有密码（首次打开会引导你设置）。如果你按第 2 步把它映射到了公网域名，务必先设置用户名密码，否则等于把整个文件树的管理权限敞开在互联网上 —— 谁都点得动"删除文件夹"。

设置 syncthing 实时同步文件

1. 服务器端新建同步文件夹：在可道云的数据目录 /opt/1panel/apps/kodbox/kodbox/site/data/files 下新建一个 sync 文件夹，并把用户和用户组权限设置为 1000（与容器内运行用户一致），否则 Syncthing 写入会权限不足。

2. 编辑 syncthing 的 docker 容器，添加挂载：把服务器本机目录 /opt/1panel/apps/kodbox/kodbox/site/data/files/sync 映射为容器内的 /sync。因为 Syncthing 运行在容器里，它要能读写可道云的存储目录，就必须通过这个挂载打通。

3. 服务器端 Syncthing 添加同步文件夹：文件夹路径选择容器里的 /sync，并配置好设备 ID，把它与电脑端的 Syncthing 配对。

4. 同步建立后，回到可道云的本地存储，就能看到 sync 文件夹里自动出现了同步过来的文件。之后无论你在家还是公司修改文件，另一台设备都会实时更新，真正做到"同一份文件两端同步改"。

⚠️ 90% 的 Syncthing 权限报错，根因都在 UID 上

第 1 步那个"权限设置为 1000"，很多人照抄了但不明白为什么，一旦换个镜像或换台机器就又报 permission denied。原理是：

• Syncthing 官方镜像默认以 1000:1000 这个非 root 用户运行（这是容器安全惯例，不是可道云的要求）

• 而它要写入的目录，属主是宿主机上的某个 UID。如果两边对不上，容器内进程就没有写权限

所以要么把宿主目录改成 1000:1000（推荐），要么在运行参数里加 -u 0:0 以 root 运行（不推荐，等于放弃容器隔离）。判断方法很简单：报权限错时，先在宿主上看目录属主 ls -ld，再进容器看进程身份 id，两侧一致就对了。

冲突文件与版本恢复

同步用久了一定会遇到这两个东西，先认识一下：

• 冲突文件：命名类似 报告.sync-conflict-20260921-103000-ABCDEFG.docx。Syncthing 不会自动合并，只是把两份都留着。处理方式就是人工比对、留下要的那份、删掉另一份。减少冲突的实用办法：避免两台机器同时编辑同一个文件（尤其别开着同一个大文件改）。

• .stversions 目录：如果开了"简单文件版本控制"，被覆盖或删除的旧版本会存进这里。误删文件时，先来这里找，往往能救回来 —— 这相当于给你的同步加了一层撤销键。

三条路线，怎么选

到这一步其实可以把同类需求摆在一起看：

如果你写的主要是 Markdown 笔记，那用 Obsidian 的同步方案会比"云盘 + Syncthing"轻得多 —— 笔记是纯文本，冲突容易理解，社区也有专门插件处理版本：Obsidian 多端同步插件方案。

如果你想要的是笔记应用本身（带网页端、手机端、历史版本），那 Joplin 更对路，自建服务端也很简单：自建 Joplin Server 笔记同步服务。

小结

这套方案的思路是：可道云负责"在线看与分享"，Syncthing 负责"双向同步编辑"，两者通过同一个磁盘目录打通。优点是文档预览体验好、文件修改不丢、跨设备一致；缺点是 Syncthing 需要维护设备配对与端口放行，初次配置略繁琐。如果你只有"单机上传查看"的需求，可道云自带的单向同步就够用，不必上 Syncthing。