企业官网建设流程全解析

1. 为什么我又把笔记从云端搬回了自己的硬盘

三年前我把所有工作笔记迁到了Notion，去年又折腾了一轮印象笔记，今年年初我做了一个让同事觉得"倒退"的决定：把主力笔记系统换成了一套跑在自己服务器上的开源Markdown工具。原因不复杂——我受够了几件事：公司内网环境下云端笔记加载转圈、某次服务商调整套餐导致我导出笔记时格式全乱、以及我越来越在意那些包含客户信息的会议记录到底存在谁的硬盘上。

如果你也有类似感受，那这篇内容就是写给你的。我下面要聊的，是一类支持自建服务器的开源Markdown笔记工具，它能做到Notion和印象笔记八成的核心体验，同时把数据控制权完全交回你手里，而且不花一分钱。适合三类人看：一是对数据隐私有要求的开发者或自由职业者；二是想给团队搭一套内部知识库的技术负责人；三是单纯想搞明白"自建笔记"到底靠不靠谱、值不值得折腾的普通用户。

先说结论，免得你看到一半发现方向不对：这类工具不是Notion的像素级复刻，它的强项在纯文本存储、Markdown原生、离线优先、可自托管这四点上。你要的是花哨的数据库视图和AI自动补全，那它可能满足不了你；你要的是"我的笔记永远是我的，换台电脑、换个服务商都能打开"，那它就是对的选择。接下来我会从选型逻辑、部署实操、Markdown的坑、数据迁移、日常维护几个角度，把我踩过的路完整讲一遍。

2. 自建Markdown笔记工具到底解决了哪些真问题

2.1 数据主权：你的笔记不该被某家公司的服务器绑架

云端笔记最隐蔽的风险不是收费，而是格式锁定。你在Notion里写的带嵌套数据库的页面，导出成Markdown后层级会塌掉；印象笔记的富文本粘到别处经常带一堆内联样式。这些工具用"便利"换走了你数据的可移植性。而自建Markdown工具的核心逻辑是：每篇笔记就是一个.md纯文本文件，存在你自己的磁盘上，用任何文本编辑器都能打开。

这意味着什么？意味着十年后哪怕这个开源项目停止维护了，你的笔记依然是一堆能读的文本文件，不会变成打不开的乱码。我实测过，把整个笔记目录打包拷到另一台机器，用VS Code直接打开，所有内容、图片引用、内部链接全部完好。这种"随时能跑路"的底气，是云端服务给不了的。

2.2 离线优先：断网、内网、飞机上都能写

自建方案通常采用"本地优先"架构：笔记先写进本地文件，再通过同步机制推送到服务器。我在高铁上、在客户内网里、在飞机模式下都写过笔记，体验和联网时没有任何区别，等网络恢复后自动同步。这一点对经常出差或者办公网络受限的人特别重要。

对比一下就很清楚：云端笔记断网基本等于砖头，自建方案断网照写不误。这不是什么高深技术，就是架构选择带来的差异——把"能不能用"的决定权从网络状态手里拿回来。

2.3 成本与可控性：一台低配服务器就能撑起整个团队

很多人以为自建很贵，其实算笔账就明白了。一台2核2G的入门云服务器，年费通常在百元级别，跑一套笔记服务绰绰有余。如果放在家里的旧电脑或树莓派上，成本几乎为零。团队场景下，十个人共用一台服务器，人均成本可以忽略不计。

更重要的是可控性：备份策略你自己定，访问权限你自己管，升级节奏你自己掌握。我给自己定的规则是每天凌晨自动打包备份到另一块硬盘，保留最近30天。这套机制用一条定时脚本就能实现，比研究云端服务的导出限制省心得多。

2.4 和Notion、印象笔记的能力边界对照

为了让你不抱错误期待，我把三者的核心能力做了个对照：

看这张表你就明白了：自建方案是用"花哨功能"换"数据自由"。如果你的笔记主要是文字、代码片段、会议记录、读书笔记这类内容，那它完全够用；如果你重度依赖看板、日历、关系型数据库，那还是老老实实用Notion。

3. 选型时我重点看的五个硬指标

市面上的开源Markdown笔记工具不少，我前后试了五六款，最后留下的是那种"该有的都有、不该有的都没有"的类型。下面这五个指标是我筛选时的核心依据，你也可以照着这个清单去评估。

3.1 存储格式是否真的"纯Markdown"

有些工具号称支持Markdown，实际上是把内容存进数据库，只在导出时才转成Markdown。这种"伪Markdown"要警惕——它照样会锁定你。真正的纯Markdown方案，笔记目录里就是一个个.md文件，图片放在assets之类的子目录，用相对路径引用。

判断方法很简单：部署完之后去服务器的数据目录看一眼，如果能看到.md文件，那就是真的；如果只有一堆.db或.json，那就要打个问号。我用的这套工具，数据目录结构清晰到可以直接用grep全文搜索，这点深得我心。

3.2 同步机制是否可靠且冲突可解

多设备同步是刚需，但同步必然涉及冲突处理。好的方案会在两台设备同时改同一篇笔记时，生成冲突副本而不是直接覆盖，让你手动合并。我踩过一次坑：早期用的一款工具冲突时直接以最后写入为准，结果我在手机上改的一段内容被电脑上的旧版本覆盖了，找都找不回来。

现在的方案我特意测过冲突场景：手机和电脑同时改同一段，同步后会出现一个带时间戳的冲突文件，两边内容都在，手动合并即可。虽然麻烦一点，但至少数据不丢。

3.3 检索能力：全文搜索和标签体系

笔记一多，搜索就是命根子。我要求两个能力：全文搜索（包括代码块里的内容）和标签过滤。纯Markdown方案在这点上反而有优势，因为可以用系统级的搜索工具，比如ripgrep，速度极快。

# 用ripgrep在笔记目录里全文搜索关键词 rg "客户需求" ~/notes --type md -l

这条命令能在毫秒级列出所有包含"客户需求"的笔记文件。标签体系则靠Markdown的frontmatter实现，在文件开头写：

--- tags: [客户, 会议记录] date: 2024-05-20 ---

工具会自动解析这些元数据并建立索引，点标签就能筛出相关笔记。

3.4 部署难度：Docker一键起还是手动编译

对大多数人来说，Docker部署是最省事的路径。一条docker compose up -d就能跑起来，升级时换个镜像标签重启即可。我优先选支持Docker官方镜像的项目，省去配环境、装依赖的麻烦。

如果你连Docker都不想装，那就要看项目是否提供单文件二进制。有些用Go或Rust写的工具，直接下载一个可执行文件就能跑，连运行时都不用装。这种对小白最友好，但功能通常也相对精简。

3.5 社区活跃度：别选一个已经停更的项目

开源项目最怕"作者跑路"。我判断活跃度看三个信号：GitHub上最近三个月的提交记录、issue的响应速度、以及是否有持续的版本发布。一个半年没更新的项目，哪怕功能再合心意，我也不敢把重要数据托付给它。

提示：选型时优先看项目的release页面，如果最新版本是两年前发布的，基本可以放弃了。活跃项目通常每月都有小版本迭代。

4. 从零部署一套自建笔记服务的完整过程

这部分是实操核心，我以Docker Compose部署为例，把每一步的意图和注意事项都讲清楚。你照着做，半小时内能跑起来。

4.1 服务器准备与基础环境

先准备一台服务器，配置不用高，2核2G足够个人使用，团队用4核4G更稳。系统我推荐Ubuntu 22.04 LTS，长期支持、社区资料多。登录后先做基础加固：

# 更新系统包 sudo apt update && sudo apt upgrade -y # 安装Docker和Compose插件 sudo apt install -y docker.io docker-compose-plugin # 把当前用户加入docker组，免sudo sudo usermod -aG docker $USER # 重新登录使权限生效

这里有个细节：usermod之后必须重新登录一次，否则docker命令还是要sudo。我第一次弄的时候没注意，折腾了半天以为装错了。

4.2 用Docker Compose编排服务

新建一个目录放配置文件，然后写docker-compose.yml。下面是一个典型结构，我加了详细注释：

version: "3.8" services: notes: image: your-note-app:latest # 替换成实际镜像名 container_name: my-notes restart: unless-stopped # 服务器重启后自动拉起 ports: - "8080:8080" # 左边是宿主机端口，可改 volumes: - ./data:/app/data # 笔记数据挂载到宿主机，关键！ - ./uploads:/app/uploads # 图片附件目录 environment: - TZ=Asia/Shanghai # 时区，影响笔记时间戳 - DB_PATH=/app/data/notes.db # 索引数据库路径

最关键的一行是volumes挂载。它把容器内的数据目录映射到宿主机的./data，这样即使容器删了重建，笔记也不会丢。我见过有人没做挂载，升级时容器一删数据全没，哭都来不及。

启动服务：

docker compose up -d docker compose logs -f # 看日志确认启动成功

浏览器访问http://你的服务器IP:8080，能看到登录界面就成功了。

4.3 反向代理与HTTPS配置

直接暴露8080端口不安全，也不方便记。我用Nginx做反向代理，配上HTTPS。如果你有域名，用Let's Encrypt免费证书；没有域名，内网用自签证书也行。

server { listen 443 ssl; server_name notes.yourdomain.com; ssl_certificate /etc/letsencrypt/live/notes.yourdomain.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/notes.yourdomain.com/privkey.pem; location / { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }

X-Forwarded-Proto这行别漏，否则应用可能生成错误的内部链接，导致图片加载不出来。这个坑我踩过，排查了半天才发现是代理头没传对。

4.4 首次登录后的必做配置

登录进去别急着写笔记，先把这几件事配好：

1. 修改默认管理员密码，别用初始密码。
2. 设置数据备份路径，确认挂载目录可写。
3. 配置同步客户端，在电脑和手机上装好客户端，填服务器地址和账号。
4. 测试冲突处理，故意在两台设备改同一篇，看冲突文件是否正常生成。

注意：首次同步前，先在客户端建一篇测试笔记，确认能正常上传到服务器，再去导入大量旧笔记。顺序反了的话，出问题不好定位。

5. Markdown写作里那些让人抓狂的细节

自建工具的核心是Markdown，而Markdown看似简单，实际用起来坑不少。我把高频问题整理出来，都是真实踩过的。

5.1 换行：为什么我按了回车却没换行

这是Markdown新手第一大坑。标准Markdown里，单个回车不会产生换行，需要行尾加两个空格或者空一行。很多人从富文本编辑器转过来，习惯性按一次回车，结果渲染出来还是同一段。

这是第一行 这是第二行（行尾有两个空格，会换行） 这是另一段（中间空了一行）

不同工具对换行的处理还不一样，有的支持"硬换行"选项，开启后单回车即换行。我建议统一用空行分段，行尾双空格做段内换行，这样兼容性最好。

5.2 表格：从Markdown转Excel的正确姿势

热词里"markdown表格转换excel"出现频率很高，说明这是普遍需求。Markdown表格长这样：

| 姓名 | 部门 | 工时 | |------|------|------| | 张三 | 研发 | 160 | | 李四 | 测试 | 152 |

要转成Excel，最省事的办法是复制表格内容，粘到支持Markdown的编辑器里，再导出为CSV，用Excel打开。或者用命令行工具pandoc：

pandoc notes.md -o notes.xlsx

pandoc是文档转换的瑞士军刀，Markdown转Word、转PDF、转Excel都能干。我处理周报时经常用它批量转换。

5.3 图片路径：相对路径还是绝对路径

自建笔记的图片管理有个原则：用相对路径，别用绝对路径。相对路径让整个笔记目录可以整体搬迁，换服务器、换电脑都不受影响。

![架构图](./assets/architecture.png)

如果工具支持粘贴图片自动上传，那它会自动生成正确的相对路径，你就不用操心。我用的这套工具，截图后直接Ctrl+V，图片自动存到assets目录并插入引用，非常顺手。

5.4 数学公式与特殊符号

写技术笔记难免要写公式。Markdown用$...$包裹行内公式，$$...$$包裹块级公式：

行内公式：$E = mc^2$ 块级公式： $$ \sum_{i=1}^{n} x_i $$

前提是工具启用了数学渲染（通常基于KaTeX或MathJax）。如果渲染不出来，去设置里找"数学公式"开关打开。至于圈1到圈19这种特殊符号，直接复制Unicode字符即可：①②③...⑲，或者用输入法的特殊符号面板。

6. 把旧笔记从Notion和印象笔记搬过来

迁移是最容易劝退的环节，但方法对了其实不难。核心思路是：先导出成Markdown，再批量修正格式，最后导入。

6.1 Notion导出：选对格式很关键

Notion的导出选项里，一定要选Markdown & CSV，不要选HTML。Markdown导出会保留基本的标题、列表、代码块结构，但数据库视图会变成CSV文件，需要手动整理。

导出后你会得到一个压缩包，解压后是一堆.md文件和对应的assets目录。这时候别急着导入，先做两件事：一是检查图片引用路径是否正确，二是把CSV里的表格内容手动合并回相关笔记。

6.2 印象笔记导出：ENEX格式的转换

印象笔记导出的是.enex格式，需要转换。有个开源工具evernote-to-markdown能批量处理：

# 安装转换工具 pip install evernote-to-markdown # 批量转换 evernote-to-markdown --input notes.enex --output ./converted

转换后同样要检查格式，尤其是代码块和表格，印象笔记的富文本转Markdown经常出问题。

6.3 批量修正格式的脚本技巧

迁移过来的笔记常见问题：多余的空行、错乱的标题层级、失效的图片链接。我写了个简单的Python脚本批量处理：

import os import re def clean_markdown(filepath): with open(filepath, 'r', encoding='utf-8') as f: content = f.read() # 合并连续空行 content = re.sub(r'\n{3,}', '\n\n', content) # 修正标题层级（示例：把####降为###） content = re.sub(r'^####', '###', content, flags=re.MULTILINE) with open(filepath, 'w', encoding='utf-8') as f: f.write(content) for root, dirs, files in os.walk('./converted'): for file in files: if file.endswith('.md'): clean_markdown(os.path.join(root, file))

跑一遍脚本，格式能整齐不少。剩下的细节再手动调。

6.4 迁移后的验证清单

导入完成后，别以为就完事了。我列了个验证清单，逐项检查：

• 随机抽10篇笔记，确认内容完整、无乱码
• 检查所有图片是否正常显示
• 测试内部链接（[[笔记名]]）是否跳转正常
• 搜索几个关键词，确认全文索引已建立
• 在手机端同步一次，确认多端一致

这套流程走下来，几百篇笔记的迁移大概花一个下午，比想象中快。

7. 日常维护：备份、升级和性能调优

自建服务跑起来只是开始，长期稳定运行靠的是维护习惯。这部分讲讲我日常怎么打理。

7.1 备份策略：3-2-1原则的落地

备份遵循3-2-1原则：3份数据、2种介质、1份异地。我的做法是：

#!/bin/bash # 每日备份脚本 DATE=$(date +%Y%m%d) BACKUP_DIR=/backup/notes mkdir -p $BACKUP_DIR # 打包笔记目录 tar -czf $BACKUP_DIR/notes-$DATE.tar.gz /path/to/notes/data # 保留最近30天 find $BACKUP_DIR -name "notes-*.tar.gz" -mtime +30 -delete # 同步到异地（示例用rsync到另一台机器） rsync -avz $BACKUP_DIR/ user@backup-host:/remote/backup/

把脚本加到crontab，每天凌晨自动跑。异地那份可以放另一台服务器，或者加密后传对象存储。

7.2 版本升级：先备份再动手

升级前必须备份，这是铁律。然后拉新镜像重启：

docker compose pull docker compose up -d

如果新版本有问题，回滚也简单：把docker-compose.yml里的镜像标签改回旧版本，重新up -d即可。我一般会等新版本发布一周、看社区没大问题再升，避免当小白鼠。

7.3 性能调优：笔记多了之后怎么办

笔记超过几千篇后，搜索可能变慢。几个优化方向：

• 定期重建索引：多数工具提供重建索引的命令，清理冗余数据
• 拆分大文件：单篇笔记别超过几千行，拆成多篇用链接关联
• 升级硬件：如果服务器内存吃紧，加到4G会明显改善

我实测下来，五千篇笔记在2核2G的机器上搜索响应仍在可接受范围，超过一万篇才需要考虑升级配置。

8. 几个我踩过的坑和对应的解法

最后分享几个真实踩过的坑，都是文档里不会写、但实际会遇到的。

坑一：时区没设对，笔记时间全乱。容器默认UTC时间，导致笔记时间戳比实际早8小时。解法是在docker-compose.yml里加TZ=Asia/Shanghai环境变量。

坑二：图片目录权限问题。容器内用户和宿主机用户UID不一致，导致图片写入失败。解法是给挂载目录设宽松权限，或者指定容器运行用户。

坑三：同步客户端版本不匹配。服务器升级后，旧版客户端连不上。解法是客户端和服务器尽量保持同版本，升级时一起升。

坑四：误删笔记找不回。纯Markdown方案没有回收站的话，删了就真没了。解法是开启工具的回收站功能，或者依赖每日备份恢复。

坑五：反向代理后WebSocket连不上。实时协作功能依赖WebSocket，Nginx默认不转发。解法是在代理配置里加Upgrade和Connection头：

proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade";

这几个坑我都亲身经历过，写出来是希望你别重复踩。自建笔记这件事，前期折腾一两个小时，换来的是长期的数据安心，我觉得很值。等你跑顺了，会发现它比想象中省心——毕竟，自己的东西，自己说了算。