云笔记管理器教程：Go + Markdown 的自托管笔记系统

各种项目 23 分前 0 0

笔记放在第三方平台，担心数据不在自己手里；用本地文件，又没有搜索、分类、手机访问。云笔记管理器就是为这个需求做的自托管方案：Go 开发的 Markdown 笔记系统，前端原生 HTML/CSS/JavaScript，后端 Gin + GORM + SQLite，一个二进制文件就能跑，支持 Markdown 实时预览、目录树、分类标签、图片粘贴上传、导入导出，还有单篇笔记密码和公开展示加密码保护的管理后台。本文把部署、配置与日常使用完整讲一遍。

一、项目简介

云笔记管理器（仓库名 note-manager）是 git.cnbugs.com 上 AI-Agent 组织的一个开源项目。它的定位很清晰：一个人的云笔记，部署在自己的服务器上，数据存在自己的 SQLite 文件里。没有复杂的微服务，没有外部数据库依赖，编译出一个二进制就能运行。

仓库：git.cnbugs.com/AI-Agent/note-manager
后端：Go 1.21+ / Gin / GORM / SQLite
前端：原生 HTML/CSS/JavaScript（无前端框架）
代码高亮：Highlight.js
数据：SQLite 单文件（data/notes.db）
部署：单二进制 + systemd，或 Docker

二、功能特性

功能	说明
Markdown 编辑	支持 Markdown 语法，编辑时右侧实时预览
代码高亮	Highlight.js 支持多种编程语言的语法高亮
目录管理	创建文件夹归类笔记，支持嵌套子目录
树形结构	左侧目录树导航，层级清晰
分类标签	按分类和标签组织笔记
搜索功能	快速搜索标题和内容
收藏置顶	收藏与置顶重要笔记
图片粘贴	编辑区直接 Ctrl+V 粘贴图片，自动上传并插入
导入导出	支持 Markdown 文件的导入与导出
笔记密码	单篇笔记可设置访问密码
前后端分离	公开展示的前台 + 密码保护的管理后台

三、技术架构

项目是经典的 Go 分层结构，代码按职责分包，前后端分离但部署在一起：

note-manager/
├── config/         # 配置管理
├── handler/        # HTTP 处理器（admin/auth/image/note）
├── middleware/     # 中间件（auth/cors/session）
├── model/          # 数据模型（note/user）
├── repository/     # 数据访问层
├── router/         # 路由配置
├── service/        # 业务逻辑层
├── web/            # 前端资源
│   ├── index.html          # 前台展示页面
│   └── admin/              # 后台管理页面
├── data/           # 数据库目录
└── main.go         # 入口文件

请求链路是 Gin 路由 → 中间件（鉴权、跨域、会话）→ handler → service → repository → SQLite。前台与后台是两套页面：前台 index.html 负责公开展示与阅读，后台 admin/ 负责笔记管理，中间用会话（session）做登录态。前端没有用 Vue 或 React，是原生 HTML/CSS/JavaScript，页面轻、加载快，改样式直接改 web/ 下的文件即可。

四、适用场景

个人知识库：技术笔记、读书笔记、工作记录都放进来，按目录与标签组织，搜索一下就能找到。
公开技术博客的底座：前台公开展示，写好的笔记直接对外可见，不用再维护一套博客系统。
团队内部文档：小团队共用一个后台，笔记按目录分项目，重要文档设密码。
运维手册：操作步骤、故障记录、命令速查写成 Markdown，贴图直接 Ctrl+V，手机上也能查。
替代第三方笔记：数据在自己服务器的 SQLite 文件里，导出就是标准 .md 文件，不怕平台关停或改价。

五、编译与部署

# 克隆仓库
git clone https://git.cnbugs.com/AI-Agent/note-manager.git
cd note-manager

# 编译（需要 Go 1.21+）
go build -o note-manager .

# 启动（默认端口 8080）
./note-manager

启动后访问：前台展示 http://localhost:8080/，后台管理 http://localhost:8080/admin/，默认管理密码是 admin123，第一次登录后建议立刻改掉。

生产环境用 systemd 托管，服务文件模板在仓库的 deploy/note-manager.service，思路和常规 Go 服务一样：

# /etc/systemd/system/note-manager.service（按实际路径调整）
[Unit]
Description=Note Manager
After=network.target

[Service]
Type=simple
WorkingDirectory=/opt/note-manager
Environment="PORT=8080"
Environment="DB_PATH=/opt/note-manager/data/notes.db"
Environment="ADMIN_PASS=your-strong-password"
Environment="UPLOAD_DIR=/opt/note-manager/uploads"
ExecStart=/opt/note-manager/note-manager
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

systemctl daemon-reload
systemctl enable --now note-manager
systemctl status note-manager
journalctl -u note-manager -f

六、配置详解：环境变量

环境变量	默认值	说明
PORT	8080	服务端口
DB_PATH	data/notes.db	数据库路径（SQLite 单文件）
ADMIN_PASS	admin123	管理后台密码
UPLOAD_DIR	uploads	图片上传目录

配置项很少，四个环境变量就管完了。生产部署最少改两项：ADMIN_PASS 改成强密码，DB_PATH 与 UPLOAD_DIR 指到数据盘或备份目录。数据库是 SQLite 单文件，备份就是复制 data/notes.db 与 uploads/ 目录，不用装数据库服务，也不用做 dump。

七、前台使用：公开阅读

浏览笔记：打开前台首页，所有公开笔记按目录与分类展示，点标题进入阅读页。
分类筛选：按分类过滤笔记，快速定位某一类内容。
搜索：搜索框同时匹配标题与正文，找一篇旧笔记不用翻目录。
阅读体验：Markdown 渲染、代码高亮、响应式布局，手机与电脑都能看。

前台是公开展示用的，不需要登录。想把某些笔记只留给自己看，有两种办法：一是给单篇笔记设访问密码，二是只把公开的笔记放在前台展示的分类里。权限的粒度是“整篇笔记”，不是按段落控制的。

八、后台管理：写笔记的完整流程

8.1 笔记管理

新建笔记：点击左侧目录上方的“+”按钮。
编辑笔记：点击笔记列表中的笔记进入编辑。
删除笔记：点击笔记编辑区的删除按钮。
置顶/收藏：点击笔记编辑区的星标/图钉按钮，重要笔记排在前面。

8.2 目录管理

新建目录：点击左侧目录上方的文件夹图标。
嵌套目录：先选中父目录，再创建子项，就能建多层目录树。
删除目录：会同时删除目录下所有内容，删之前确认好，删了没有回收站。

8.3 编辑器使用

左侧：Markdown 编辑区；右侧：实时预览。
分割线：可拖动调整左右比例。
粘贴图片：直接在编辑区 Ctrl+V 粘贴图片，自动上传并插入到光标处，不用先传图再贴链接。

8.4 导入导出

导出笔记：选择一个笔记，点击「导出」按钮下载 Markdown 文件，内容就是标准 .md，拿到任何编辑器都能打开。
导入笔记：点击「导入」按钮，选择 .md 文件创建笔记，适合把本地积累的 Markdown 批量迁进来。

8.5 笔记密码

为重要笔记设置访问密码，查看带密码的笔记时需要输入密码。这个密码是按篇设置的，和后台登录密码（ADMIN_PASS）是两回事：后台密码管“能不能进管理界面”，笔记密码管“这篇笔记能不能看”。

九、Markdown 语法速查

编辑器支持标准 Markdown 语法，常用写法如下：

# 一级标题
## 二级标题
### 三级标题

**粗体文字**
*斜体文字*
***粗斜体***

~~删除线~~

> 引用文本

- 无序列表
* 另一种无序列表

1. 有序列表
2. 第二项

[链接文字](https://example.com)
![图片描述](image-url)

代码块用三个反引号包裹，后面跟语言名就能高亮：

```javascript
function hello() {
  console.log("Hello World!");
}
```

```go
package main

import "fmt"

func main() {
    fmt.Println("你好")
}
```

十、API 接口

仓库里有一份 API.md，详细列出了后端接口。按项目结构，接口分四类：认证（auth）、笔记（note）、图片（image）、管理（admin），由 handler/ 下的 auth_handler.go、note_handler.go、image_handler.go、admin_handler.go 实现，鉴权走 middleware/auth.go 与 session.go。写脚本批量导入笔记或做二次开发时，直接看仓库里的 API.md 为准，本文不逐条转述，避免版本对不上。

需要提醒一点：前台是公开展示的，API 的读接口同样不需要登录就能访问。部署到公网时，如果笔记里有敏感内容，记得给单篇笔记设密码，或者用 Nginx 的 basic_auth 再挡一层。

十一、常见问题

问题	原因与处理
启动后打不开页面	先看进程在不在、端口对不对：ss -tlnp \| grep 8080；再看日志有没有报错；确认防火墙放行了 8080
忘记后台密码	后台密码是 ADMIN_PASS 环境变量，改环境变量后重启服务即可；不要直接改数据库
图片粘贴后不显示	检查 UPLOAD_DIR 目录是否存在、进程有没有写权限；再看浏览器控制台有没有报错
删除目录后笔记没了	删除目录会同时删除目录下所有内容，且没有回收站，删之前先导出备份
搜索不到某篇笔记	搜索匹配标题与内容，确认笔记不是被设了密码或放在未公开的分类里
升级后打不开	先备份 data/notes.db 与 uploads/，再拉新代码重新编译；数据库文件一般向前兼容，升级前备份是底线

十二、运维与备份建议

备份就两样东西：data/notes.db（全部笔记）与 uploads/（全部图片），每天定时复制一份到异地或对象存储，恢复时直接放回去就能用。
改默认密码：ADMIN_PASS 默认 admin123，第一次部署就改掉；公网部署时后台入口建议再加一层 Nginx basic_auth 或 IP 白名单。
反向代理：生产环境用 Nginx 反代 8080，顺手上 HTTPS（证书可以用 AutoSSL 自动管理），不要把 8080 直接暴露在公网。
定期导出：重要笔记定期用导出功能存一份 .md 到本地，Markdown 是纯文本，任何时候都能打开，不依赖这个系统。
升级流程：停服务 → 备份 data/ 与 uploads/ → 拉代码重新编译 → 启动验证，没问题再放行。

云笔记管理器的优点就一个字：轻。一个二进制、一个 SQLite 文件、四种环境变量，就能跑起一个带目录树、搜索、标签、图片粘贴的 Markdown 笔记系统，数据完全在自己手里。它不追求 Notion 那种协作与花哨功能，适合一个人、一台服务器、长期积累知识库。如果你正在找自托管笔记方案，先把它跑起来写一周笔记，顺手了再决定要不要长期用。

声明：本站所有文章，如无特殊说明或标注，均为本站原创发布。任何个人或组织，在未征得本站同意时，禁止复制、盗用、采集、发布本站内容到任何网站、书籍等各类媒体平台。如若本站内容侵犯了原著者的合法权益，可联系我们进行处理。

Go Markdown 云笔记