简介这是一款支持私有部署的云端存储双链笔记软件面向重视数据安全与知识管理的个人用户及开发者同时集成个人博客功能可在 Windows、Mac、网页客户端与移动端之间无缝切换。资源包共 1023 个文件约 23.74MB以 Java 后端源码545 个和 Vue 前端组件102 个为主体辅以 TypeScript、SCSS、XML、JSON 等配置与样式文件并包含 Dockerfile、SQL、Shell 脚本及多份 adoc 说明文档构成完整的前后端工程结构。已有 361 人学习下载。通过该资源读者可获取双链笔记的网状知识组织实现思路、跨平台实时同步机制、私有部署方案与博客模块的工程代码适合用于二次开发、功能定制或学习全栈项目架构目录层次清晰便于按模块检索与调试。1. 私有部署的双链笔记从云端同步到个人博客一套能自己掌控的知识库如果你受够了在线笔记服务突然改政策、导出格式残缺、或者免费版限制附件数量那这套支持私有部署的云端存储双链笔记软件值得看一眼。它把笔记数据放在你自己的服务器上客户端覆盖 Windows、Mac、网页端和网页移动端同时内置了个人博客功能——你写的笔记可以直接以博客形式对外分享。核心能力是双链笔记用[[ ]]语法把不同笔记关联成网状结构而不是传统的文件夹树状层级。适合谁适合对数据隐私敏感、又想要跨设备实时同步、还希望顺手把知识沉淀成公开博客的从业者。下面从部署到双链实操再到博客配置和踩坑一步步拆。2. 私有部署落地从 Docker 到反向代理的完整链路2.1 为什么选私有部署而不是 SaaS 笔记在线笔记服务的问题不是功能不够而是控制权不在你手里。导出格式受限、附件存储额外收费、服务条款随时可能变。私有部署的本质是把数据主权拿回来笔记存在你自己的服务器磁盘上数据库你随时能备份附件走你自己的对象存储或本地目录。这套软件支持 Docker 部署意味着你不需要手动配 Java 环境、不需要编译前端资源一条docker compose up -d就能跑起来。另一个选私有部署的理由是博客功能。在线笔记的分享链接通常带平台水印和跳转限制而私有部署后绑定自己的域名博客就是完全独立的站点。搜索引擎收录、自定义样式、访问统计这些都能自己控制。常见做法是一台 2 核 4G 的轻量服务器 Docker 反向代理Nginx 或 Caddy足够支撑个人和小团队使用。如果附件多再加一个对象存储或挂载大容量磁盘。2.2 Docker 部署实操compose 文件与关键参数先确认服务器已安装 Docker 和 Docker Compose。如果用的是 Windows 做开发机建议在 WSL2 里跑 Docker避免路径挂载的权限问题。下面是部署用的 compose 配置我一般会按这个结构来写version: 3.8 services: blossom: image: blossom-app:latest container_name: blossom-note restart: unless-stopped ports: - 8080:8080 # 应用对外端口后面反向代理指向这里 environment: - DB_HOSTmysql # 数据库主机名用 compose 服务名 - DB_PORT3306 - DB_NAMEblossom - DB_USERblossom - DB_PASSyour_password_here - STORAGE_TYPElocal # 附件存储方式local 或 s3 - STORAGE_PATH/data/attachments - BLOG_ENABLEtrue # 开启博客模块 volumes: - ./data/attachments:/data/attachments # 附件持久化 - ./data/logs:/app/logs # 日志持久化排查问题用 depends_on: - mysql mysql: image: mysql:8.0 container_name: blossom-mysql restart: unless-stopped environment: - MYSQL_ROOT_PASSWORDroot_password_here - MYSQL_DATABASEblossom - MYSQL_USERblossom - MYSQL_PASSWORDyour_password_here volumes: - ./data/mysql:/var/lib/mysql # 数据库文件持久化千万别丢 command: --character-set-serverutf8mb4 --collation-serverutf8mb4_unicode_ci逻辑说明应用容器和数据库容器分开数据库用 MySQL 8.0 并强制 utf8mb4 字符集否则双链笔记里的中文和特殊符号会乱码。STORAGE_TYPE设为local时附件存本地磁盘适合单机部署如果有多节点或想用云存储改成s3并补上 endpoint 和密钥。BLOG_ENABLE控制博客模块是否加载不需要对外分享可以关掉减少攻击面。参数说明DB_PASS和MYSQL_PASSWORD必须一致这是最常见的翻车点。STORAGE_PATH挂载到宿主机目录迁移时直接打包这个目录就行。restart: unless-stopped保证服务器重启后容器自动拉起。启动命令docker compose up -d docker compose logs -f blossom # 查看启动日志确认没有报错看到日志里出现Started BlossomApplication之类的字样说明应用起来了。浏览器访问http://服务器IP:8080应该能看到登录页。2.3 反向代理与 HTTPSCaddy 配置示例直接暴露 8080 端口不安全也不方便绑域名。用 Caddy 做反向代理最省事它会自动申请和续期 Lets Encrypt 证书。Caddyfile 配置note.yourdomain.com { reverse_proxy localhost:8080 encode gzip header { X-Content-Type-Options nosniff X-Frame-Options DENY } }逻辑说明reverse_proxy把外部请求转发到本地 8080encode gzip压缩响应体加快加载两个 header 是基础安全头。Caddy 自动处理 HTTPS你只需要把域名解析到服务器 IP。如果用的是 Nginx配置里要加client_max_body_size 50m;否则上传大附件会返回 413。这个坑我踩过当时传一个 30M 的 PDF 一直失败查了半天才发现是 Nginx 默认限制 1M。3. 双链笔记的核心机制从语法到知识网络构建3.1 双链语法与解析逻辑双链笔记的核心不是花哨的图谱而是[[笔记标题]]这种语法在编辑时自动建立双向关联。当你在笔记 A 里写[[笔记B]]系统会在笔记 B 的「反向链接」区域自动显示笔记 A 的引用。这个机制让知识不再是孤岛而是可以沿着链接跳转的网状结构。这套软件的双链解析在服务端完成意味着即使你在不同客户端编辑链接关系也会实时同步。常见做法是先建「索引笔记」作为入口比如「读书笔记索引」「项目复盘索引」然后在具体笔记里用双链指回索引。这样打开索引就能看到所有关联内容。搜索功能依赖search_all.js.btl和search.js.btl这类模板文件它们定义了搜索结果的渲染逻辑。如果你要改搜索排序或高亮规则需要动这些文件。DubboSearch.btl则是 Dubbo 接口相关的搜索模板说明后端用了 Dubbo 做服务治理。3.2 知识网络构建索引笔记与标签的配合光有双链不够还需要标签做横向分类。我的习惯是双链做纵向关联概念之间的引用标签做横向分类状态、领域、优先级。比如一条笔记可以同时有[[分布式事务]]的双链和#待整理的标签。构建步骤建一个「总索引」笔记列出所有领域入口每个入口用双链指向领域索引。领域索引笔记里用双链列出该领域下的具体笔记。具体笔记里用双链引用相关概念用标签标记状态。定期打开图谱视图检查有没有孤立节点——孤立节点说明这条笔记没有被任何其他笔记引用需要补链接。图谱视图是双链笔记的「黑匣子」它把链接关系可视化让你一眼看出知识结构哪里密集、哪里稀疏。但别沉迷图谱好看关键是链接背后的逻辑是否成立。3.3 跨平台同步的配置要点Windows、Mac、网页端、网页移动端四个客户端同步依赖服务端的 API。配置时注意两点一是 API 地址要填对外可访问的域名不要填localhost否则手机端连不上二是如果用了 HTTPS客户端也要用https://开头混合内容会被浏览器拦截。移动端是网页版意味着不需要装 App浏览器打开就能用。好处是跨平台无成本坏处是没有原生推送。如果你需要离线编辑网页端支持 PWA 模式在浏览器里「添加到主屏幕」就能像 App 一样打开。4. 个人博客模块从笔记到公开站点的配置与避坑4.1 博客发布流程与权限控制博客模块的本质是把选定的笔记渲染成公开页面。不是所有笔记都适合公开所以需要一套发布控制机制。常见做法是在笔记属性里加publish: true标记只有带这个标记的笔记才会出现在博客列表里。或者单独建一个「博客」文件夹该文件夹下的笔记自动公开。配置步骤在应用设置里开启博客模块设置博客标题、描述、favicon。选择博客的 URL 路径前缀比如/blog。在笔记里标记哪些要公开。访问https://note.yourdomain.com/blog查看效果。权限控制方面博客默认是公开只读。如果需要密码保护可以在反向代理层加 Basic Auth或者在应用层配置访问密码。注意博客页面会暴露笔记的创建时间和更新时间如果介意需要在模板里隐藏这两个字段。4.2 自定义域名与 SEO 基础配置绑定自定义域名后博客就是一个独立站点。SEO 基础配置包括每篇博客自动生成title和meta description这两项通常取自笔记标题和摘要。如果摘要为空搜索引擎会抓取正文前 150 字左右。sitemap.xml和robots.txt一般由应用自动生成路径通常是/sitemap.xml和/robots.txt。提交到搜索引擎后收录速度取决于域名权重和内容质量。新域名通常需要几周才能被收录。一个容易忽略的点博客页面的图片如果存在私有附件目录外部访问会 403。需要把博客用到的图片放到公开目录或者在反向代理里放行附件路径的读权限。4.3 博客与笔记的双向隔离博客公开的内容和私有笔记之间要有隔离。我的做法是博客只发布「成品」笔记草稿和碎片笔记永远不标记公开。另外双链在博客页面里的行为要确认如果笔记 A 公开、笔记 B 不公开A 里的[[笔记B]]链接在博客上应该显示为纯文本而不是可点击链接否则会暴露私有笔记的存在。这个隔离逻辑需要在模板里处理。检查AllInOne.css和相关的.btl模板文件确认公开页面渲染时对未公开笔记的双链做了降级处理。如果没有需要手动改模板。5. 避坑与排查部署和日常使用中的五个血泪教训5.1 数据库字符集导致中文乱码现象笔记里的中文显示为???或乱码方块。原因MySQL 容器启动时没有指定 utf8mb4 字符集默认用了 latin1。解决在 compose 文件的 mysql 服务里加command: --character-set-serverutf8mb4 --collation-serverutf8mb4_unicode_ci然后删除./data/mysql目录重新初始化。注意删库前先确认没有重要数据或者先导出再重建。5.2 附件上传失败返回 413现象上传超过 1M 的图片或 PDF 时浏览器显示 413 Request Entity Too Large。原因反向代理Nginx 或 Caddy默认请求体大小限制。解决Nginx 加client_max_body_size 50m;到 server 块Caddy 默认没有限制但如果前面还有一层云负载均衡需要在云控制台也调大限制。这个坑的排查顺序是先看反向代理日志再看应用日志最后看云平台限制。5.3 双链在博客页面暴露私有笔记标题现象博客上某篇公开笔记里[[私有笔记标题]]显示为可点击链接点击后 404 但标题已经泄露。原因模板没有对未公开笔记做降级处理。解决找到渲染双链的模板文件通常是.btl后缀加判断逻辑如果目标笔记未公开则只渲染纯文本不加a标签。改完后清缓存重启应用。5.4 移动端网页无法登录现象手机浏览器打开网页端输入账号密码后一直转圈或提示网络错误。原因API 地址配置成了localhost或内网 IP手机不在同一网络时无法访问。解决在应用设置里把 API 地址改成对外域名确保手机能解析并访问。如果用了自签名证书手机浏览器会拦截需要换成受信任的证书。5.5 Docker 重启后数据丢失现象服务器重启后笔记和附件全部消失。原因compose 文件里没有配置 volumes 持久化数据存在容器内部容器重建后数据丢失。解决确保 mysql 的/var/lib/mysql和应用的附件目录都挂载到了宿主机。已经丢失的数据如果没备份基本找不回来——这是最贵的后悔药。从那以后我每次写 compose 文件第一件事就是检查 volumes。6. 进阶技巧用搜索模板和 API 做自动化知识流转6.1 自定义搜索模板提升检索效率search_all.js.btl和search.js.btl这两个文件控制搜索结果的渲染。默认搜索可能只匹配标题但你可以改成同时匹配正文和标签。修改逻辑通常是调整查询语句和渲染模板。比如在search_all.js.btl里把查询字段从title扩展到title, content, tags这样搜「分布式」时正文里提到分布式的笔记也会出现。改完后需要清应用缓存并重启。测试方法搜一个只出现在正文里的关键词看能否命中。如果没命中检查模板里的字段名是否和数据库列名一致。6.2 通过 API 做笔记自动归档这套软件通常提供 REST API可以用脚本把外部内容自动写入笔记。比如用 Python 脚本把 RSS 订阅的新文章自动存成笔记import requests API_BASE https://note.yourdomain.com/api TOKEN your_api_token_here def create_note(title, content, tags): resp requests.post( f{API_BASE}/notes, headers{Authorization: fBearer {TOKEN}}, json{ title: title, content: content, tags: tags, publish: False # 默认不公开后续手动标记 } ) if resp.status_code 200: print(f笔记创建成功: {title}) else: print(f失败: {resp.status_code} {resp.text}) # 调用示例 create_note(今日阅读分布式系统设计, 正文内容..., [阅读, 分布式])逻辑说明Authorization头传 API Tokenpublish: False保证自动创建的笔记不会直接公开。参数说明API_BASE换成你的域名TOKEN在应用设置里生成。这个脚本可以配合 cron 定时跑把外部信息流自动归档到笔记系统里后续再用双链做关联。6.3 定期备份与恢复验证私有部署最大的风险是数据丢失。我的习惯是每天凌晨用mysqldump导出数据库同时打包附件目录存到另一台机器或对象存储。备份脚本#!/bin/bash DATE$(date %Y%m%d) BACKUP_DIR/backup/blossom/$DATE mkdir -p $BACKUP_DIR # 导出数据库 docker exec blossom-mysql mysqldump -u blossom -pyour_password blossom $BACKUP_DIR/blossom.sql # 打包附件 tar -czf $BACKUP_DIR/attachments.tar.gz -C ./data attachments # 删除 7 天前的备份 find /backup/blossom -type d -mtime 7 -exec rm -rf {} \;关键是恢复验证每季度至少做一次恢复演练把备份的 SQL 导入一个新容器确认笔记和双链关系完整。没验证过的备份等于没有备份——这是另一颗后悔药。从那以后我每次改完 compose 或升级版本都强制走一遍备份恢复流程确认数据能回来才继续用。希望帮到你。本文还有配套的精品资源点击获取