简介这是一款支持私有部署的云端存储双链笔记软件面向重视数据安全与知识管理的个人用户及开发者同时集成个人博客功能可在 Windows、Mac、网页客户端与移动端之间无缝切换。资源包共 1023 个文件以 545 个 Java 后端源码、102 个 Vue 与 78 个 TypeScript 前端代码为主体另含 75 张 png 图片、40 个 scss 样式、29 个 xml 配置及 md、json、yml 等文档与构建文件压缩包约 23.74MB整体呈现前后端分离的工程结构。已有 361 人学习下载。借助双链笔记的非线性网状结构用户可在关键词与主题间自由跳转配合实时同步与私有云存储兼顾知识检索效率与隐私安全开发者亦可基于源码进行二次开发或自定义功能适合作为全栈项目学习与私有化部署实践的参考。1. 私有部署的双链笔记为什么我把博客、网盘和知识库塞进同一个服务去年团队要把散落在各人电脑里的技术文档收拢试过几个方案纯云笔记数据不在自己手里自建 Wiki 又和日常笔记割裂。后来我把一套支持私有部署的云端存储双链笔记软件跑在内网服务器上Windows、Mac、网页端、手机浏览器都能连顺带把个人博客也挂了上去。这套东西的核心价值就三点数据落在自己机器上、双链把零散笔记织成网、多端同步不用来回导文件。它适合谁适合手里有一台常开的 NAS 或云主机、愿意花一个下午折腾 Docker、又不想把技术笔记交给第三方平台的人。下面我按「选型理由 → 部署步骤 → 参数怎么调 → 坑在哪」的顺序把整套流程讲清楚你照着做基本能复现。2. 双链笔记的私有部署选型为什么是 Docker 而不是裸装2.1 双链、云端存储、博客三合一到底意味着什么先把概念拆开。双链笔记指的是笔记之间用[[笔记名]]这种语法互相引用系统会自动生成反向链接让你看到「哪些笔记提到了当前这篇」。这和传统文件夹分类是两种思路文件夹是树双链是网。云端存储指的是所有笔记存在服务端客户端只负责渲染和编辑换设备不用同步文件。博客则是把部分笔记以网页形式公开出去。这三件事能塞进一个服务是因为它们的底层都是同一份 Markdown 数据。双链靠解析 Markdown 里的引用语法博客靠把指定笔记本渲染成 HTML云端存储靠服务端统一管理文件。常见做法是选一个已经把这三点做进同一套代码的开源项目用 Docker 拉起而不是自己拼三个工具。我一般会优先看项目是否提供官方镜像、是否支持 SQLite 和 PostgreSQL 两种存储、有没有内置的反向代理配置。选型时重点看这几个维度数据存储格式是不是纯 Markdown决定你以后能不能随时迁走、是否支持多用户决定能不能给团队用、客户端覆盖是否包含 Windows 和 Mac 原生应用决定日常体验、有没有移动端网页适配决定手机上能不能看。这四点里纯 Markdown 存储是最关键的后悔药——哪怕哪天不用这个软件了笔记还能用任何编辑器打开。2.2 用 Docker Compose 拉起服务的最小配置私有部署最省事的方式是 Docker Compose。下面这份配置我用了很久跑在内网一台 2 核 4G 的机器上足够。# docker-compose.yml version: 3 services: notes: image: 项目官方镜像 # 换成你选定的项目镜像名 container_name: notes-server restart: unless-stopped # 崩溃或重启后自动拉起 ports: - 8080:8080 # 宿主机端口:容器端口 volumes: - ./data:/data # 笔记数据持久化到宿主机 - ./config:/config # 配置文件目录 environment: - TZAsia/Shanghai # 时区影响笔记时间戳 - STORAGE_TYPEsqlite # 小规模用 sqlite团队用 postgres - AUTH_ENABLEDtrue # 开启登录鉴权逻辑说明volumes这两行是整个部署的命根子笔记数据必须挂到宿主机否则容器一删数据全没。restart: unless-stopped保证服务器重启后服务自动恢复。STORAGE_TYPE选 sqlite 适合个人单文件、零配置如果多人同时编辑换成 postgres 并加一个数据库服务。参数说明端口映射左边是宿主机端口右边是容器内端口别改右边。TZ一定要设否则笔记的创建时间会差 8 小时双链的时间线视图会乱。AUTH_ENABLED如果部署在公网必须开内网可以视情况关掉省去登录麻烦。启动命令就一行docker compose up -d # 后台启动 docker compose logs -f # 看启动日志确认没有报错启动后浏览器访问http://服务器IP:8080能进登录页就说明服务起来了。第一次进去先建一个笔记本随便写两篇笔记用[[另一篇]]互相引用看反向链接面板有没有自动出现——这是验证双链功能是否正常的最快方法。2.3 Windows 和 Mac 客户端怎么连自建服务网页端能用不代表客户端能用客户端连自建服务通常要填服务器地址。Windows 和 Mac 客户端下载安装后在设置里找「服务器地址」或「同步」选项填http://你的服务器IP:8080然后输入你在网页端注册的账号密码。这里有个容易翻车的点客户端默认可能连的是官方云服务你得手动切到「自建/私有服务器」模式。Mac 上如果提示证书错误是因为你用了 HTTPS 但证书是自签的内网环境直接用 HTTP 就行。Windows 客户端如果连不上先检查防火墙有没有放行 8080 端口命令行跑netstat -ano | findstr 8080看端口有没有在监听。移动端不用装 App直接用手机浏览器访问同一个地址大部分这类项目都做了响应式适配编辑和查看都够用。如果你想要更好的移动体验可以把它加到主屏幕看起来和原生 App 差不多。3. 把笔记变成博客反向代理和公开笔记本的配置3.1 用 Nginx 反代同时暴露笔记和博客服务默认跑在 8080直接暴露端口不优雅也不方便加 HTTPS。常见做法是前面挂一个 Nginx用不同路径区分笔记和博客。server { listen 80; server_name notes.example.com; # 换成你的域名或内网IP location / { proxy_pass http://127.0.0.1:8080; # 笔记主服务 proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } location /blog/ { proxy_pass http://127.0.0.1:8080/blog/; # 博客路径 proxy_set_header Host $host; } }逻辑说明proxy_set_header这几行是把真实客户端 IP 传给后端否则服务端日志里全是 Nginx 的 IP排查问题时没法定位是谁在访问。location /blog/把博客单独拎出来方便以后加缓存或限流。参数说明server_name填域名或内网 IP 都行内网用 IP 更省事。如果你要上 HTTPS用 certbot 签证书后把listen 80改成listen 443 ssl并加上证书路径这块网上教程很多不展开。配置完跑nginx -t检查语法然后nginx -s reload重载。访问http://你的地址/blog/应该能看到博客首页。3.2 哪些笔记本该公开、哪些必须锁死博客功能的关键是「选择性公开」。不是所有笔记都适合发出去我的习惯是建两个顶层笔记本一个叫public一个叫private。只有public下的笔记会渲染到博客private下的永远只在自己账号里可见。在软件设置里找到「发布」或「博客」选项指定公开的笔记本。有些项目支持给单篇笔记加publish: true的前置元数据这样更灵活——同一篇笔记想公开就加这行不想公开就删掉。这里要提醒一句公开笔记本里的双链如果指向了私有笔记有些项目会把私有笔记的标题也暴露出去。部署完一定要用无痕窗口访问一遍博客点几个链接确认没有泄露不该公开的内容。这个检查我每次改完公开设置都会做一遍血泪经验。3.3 博客的访问速度和 SEO 基础设置自建博客默认没有 CDN访问速度取决于你服务器的带宽。内网访问无所谓公网访问如果慢可以在 Nginx 里加一层缓存location /blog/ { proxy_pass http://127.0.0.1:8080/blog/; proxy_cache_valid 200 10m; # 成功响应缓存10分钟 add_header Cache-Control public; }逻辑说明博客内容更新频率低缓存 10 分钟能大幅减少后端压力。Cache-Control告诉浏览器也缓存回头客加载更快。SEO 方面这类项目一般会自动生成 sitemap你只需要在 Nginx 里确保/sitemap.xml和/robots.txt能正常访问。如果博客要被人搜到记得在设置里填上站点标题和描述别用默认值。4. 避坑与排查部署这类软件最容易翻车的五个地方4.1 数据卷没挂对容器一删笔记全没现象docker compose down之后再up登录进去发现笔记空了。原因volumes写成了容器内路径或者用了匿名卷数据存在容器层里容器删除就没了。解决确认docker-compose.yml里是./data:/data这种宿主机路径映射。部署完先docker inspect 容器名 | grep -A5 Mounts看挂载对不对再开始写笔记。养成习惯正式用之前先删一次容器重建确认数据还在。4.2 客户端连不上网页却正常现象浏览器能打开Windows 或 Mac 客户端一直转圈或报连接失败。原因客户端可能默认走 HTTPS而你服务是 HTTP或者客户端填的地址带了多余路径。解决地址只填到端口比如http://192.168.1.10:8080后面不要加/。如果客户端强制 HTTPS在设置里找「允许不安全连接」之类的开关打开。Mac 上还要检查系统代理有没有拦截本地地址。4.3 双链反向链接不显示现象写了[[某笔记]]但目标笔记的反向链接面板是空的。原因笔记名拼写不一致或者目标笔记还没创建。双链匹配是精确匹配差一个空格都不行。解决点一下那个[[ ]]链接如果目标笔记不存在系统一般会提示创建创建后反向链接才会出现。另外检查笔记标题有没有特殊字符有些项目对#、/这类字符处理有问题。4.4 多人同时编辑导致内容覆盖现象两个人改同一篇笔记后保存的把先保存的覆盖了。原因sqlite 不支持高并发写入或者项目本身没有做冲突合并。解决团队用就换 postgres并且约定好不同时改同一篇。更稳妥的做法是开启版本历史功能出问题能回滚。如果项目支持打开「编辑锁」或「实时协作」模式。4.5 公网部署没开鉴权被爬现象服务器日志里一堆陌生 IP 在扫路径甚至笔记被搜索引擎收录了。原因AUTH_ENABLED关了或者博客把私有笔记本也公开了。解决公网部署必须开鉴权博客只公开指定笔记本。再加一层 Nginx 的 basic auth 或 IP 白名单双保险。定期看访问日志发现异常 IP 直接封。5. 进阶用 API 把笔记接入自动化流程服务跑稳之后最有价值的进阶玩法是用它的 API 做自动化。这类项目通常提供 REST API你可以用脚本批量导入笔记、定时备份、或者把其他工具的数据同步进来。先拿到 API Token一般在设置里的「开发者」或「API」页面生成。然后写个 Python 脚本批量创建笔记import requests API http://192.168.1.10:8080/api TOKEN 你的API令牌 HEADERS {Authorization: fBearer {TOKEN}} def create_note(title, content, notebookpublic): 创建一篇笔记notebook 指定归属笔记本 payload { title: title, content: content, notebook: notebook, publish: notebook public # public 笔记本自动发布到博客 } r requests.post(f{API}/notes, jsonpayload, headersHEADERS) r.raise_for_status() # 非200直接抛错方便定位 return r.json() # 批量导入本地 Markdown 文件 import glob, os for path in glob.glob(./notes/*.md): name os.path.splitext(os.path.basename(path))[0] with open(path, encodingutf-8) as f: create_note(name, f.read()) print(f已导入: {name})逻辑说明publish字段根据笔记本自动判断public 下的笔记直接进博客省去手动发布。raise_for_status()是关键请求失败立刻报错不会静默丢数据。参数说明API地址换成你自己的TOKEN别硬编码在脚本里用环境变量传。批量导入前先拿一篇笔记试确认字段名和项目实际 API 一致——不同项目的字段名可能叫content或body以官方 API 文档为准。再进一步可以配一个定时任务每天凌晨把笔记目录打包备份# 每天凌晨3点备份数据目录 0 3 * * * tar -czf /backup/notes-$(date \%Y\%m\%d).tar.gz /path/to/data备份文件保留最近 30 天用find /backup -name notes-*.tar.gz -mtime 30 -delete清理旧包。这套组合拳下来你的笔记既在自建服务里随时可查又有离线备份兜底还能通过 API 和其他工具打通。我自己踩过最深的坑是早期没做备份一次误操作把数据目录清了找回来花了整整两天。从那以后任何自建服务我第一件事就是配定时备份第二件事才是研究功能。希望帮到你。本文还有配套的精品资源点击获取
