项目笔记:从博客、自学中心到私人笔记
文章目录CONTENTS ↓
起点是想有一个自己的站点:写博客、展示作品,再把平时学习的课程整理到一起。后来又加上一个具体需求——做一个只给自己使用的笔记应用。
这些内容虽然都属于“个人站点”,使用方式却不一样。博客和课程主要用来阅读,笔记应用需要登录、编辑和保存。如果把它们都按同一种应用来做,就容易把简单的内容页面也做得很重。
这篇记录项目的需求、结构和功能设计。Docker、HTTPS、数据备份和 GitHub Actions 的实践,单独放在部署笔记中。文中的域名全部使用 example.com 作为示例。
先把站点分成三个入口
根域名是一张简单的导航页,只保留博客、自学中心和项目三个入口。它负责告诉访问者“这里有什么”,不承担复杂的应用功能。
内容站和笔记应用各自使用独立的子域名:
| 示例入口 | 提供什么 |
|---|---|
example.com |
导航页:博客、自学中心、项目 |
blog.example.com |
博客文章、课程内容、项目介绍、关于 |
note.app.example.com |
需要登录的私人笔记应用 |
内容站顶部的导航是博客、学习中心、项目和关于,课程入口页的标题叫“自学中心”。笔记应用也有项目介绍页,访问者可以了解它的用途,但真正的笔记内容必须登录后才能访问。
这种划分让公开内容和私人数据有清晰的入口。域名分开只是组织方式,笔记是否可以被读取,仍然要由后端认证和权限检查决定。
为什么选择 Astro、React、Go 和 SQLite
选择技术栈时有两个明确约束:使用主流技术,尽量节省服务器资源。现有服务器只有 2 核 CPU、2 GB 内存,因此不希望为了几个静态页面就维持多套运行服务。
| 部分 | 技术 | 在本项目中的作用 |
|---|---|---|
| 公开内容站 | Astro + TypeScript | 将文章、课程和介绍页构建成静态文件 |
| 文章和课程 | Markdown / MDX | 用文本管理内容,需要时嵌入组件 |
| 笔记界面 | React + TypeScript | 管理表单、列表、登录和编辑状态 |
| 业务接口 | Go | 处理认证、密码和笔记读写 |
| 数据保存 | SQLite | 在单用户场景下保存账号、会话和笔记 |
这里选择 Astro,是因为公开站点的大部分内容在发布时就能确定。页面生成后可以直接由静态文件服务器提供,不需要常驻一个前端开发服务器。
笔记界面则有持续的交互状态:追加内容组、校验表单、保存后返回列表、处理登录状态等,因此使用 React 来组织这些行为。
Go API 从首版就存在。笔记不是只存在浏览器里的演示数据,登录验证和数据保存都需要后端承担。SQLite 则让当前应用不必单独维护数据库服务;将来出现多实例或更复杂的并发写入要求,再评估是否迁移。
一个仓库,保留清楚的目录边界
虽然存在多个入口和服务,这次没有拆成多个仓库。项目初期由自己维护,前后端接口也会一起变化,放在一个仓库更容易同步修改和验证。
主要目录按职责组织:
src/ pages/ 公开站点页面 content/ blog/ 博客文章 study/ 自学课程apps/ notes/ React 笔记前端services/ api/ Go 后端deploy/ Docker、Caddy、发布脚本.github/workflows/ 自动构建和部署流程同一个仓库并不意味着所有代码都要一起运行。公开站点和笔记前端分别构建,API 独立运行;目录边界让后续增加功能时仍然能找到各自的位置。
现在的日常开发放在 dev 分支,准备上线时再合并到 main。这样,写到一半的功能和文章可以先在开发分支里整理。
自学中心按课程组织,而不是按文章堆放
自学中心的内容来自已有学习项目中适合公开的部分。目前只有 TypeScript,但结构需要能够继续容纳其他课程。
阅读路径分为三层:
课程选择 → 章节列表 → 章节正文课程选择页采用封面卡片的方式,让读者先判断想学什么;进入课程后,再按章节顺序阅读。章节还可以带有标签和相关内容链接,方便知识之间的跳转。
这里不把个人学习记录原样发布。课程知识与私人进度、练习过程需要分开,公开构建只包含确认可以展示的内容。
自学中心本身也作为一个项目展示:项目页讲它解决什么问题,课程页负责实际阅读,避免把介绍和使用流程混在一起。
私人笔记先解决一种具体的记录方式
笔记应用没有一开始就做成复杂的知识库。它围绕一种记录方式展开:读到别人的一句话后,先写自己的理解,再保留原文引用。
因此,一条笔记不是只有一个大文本框,而是由有顺序的内容组组成:
一条笔记 第一组 自己的话 引用别人的话(可选) 第二组 自己的话 引用别人的话(可选) ……新建页面默认显示一组输入区域,自己的话在上,引用在下。点击添加按钮,就在下面追加一组。输入界面始终至少保留一组,避免删除后不知道该从哪里继续输入。
把自己的话放在前面,是为了让记录的重点落在理解和思考上。引用可以帮助保存上下文,但不能独立组成一组有效内容。
保存规则也在一开始就确定下来:
| 输入情况 | 保存时的行为 |
|---|---|
| 自己的话有内容,引用为空 | 正常保存 |
| 自己的话和引用都有内容 | 正常保存 |
| 只有引用,没有自己的话 | 提示补充自己的话,不能提交 |
两项经过 trim 后都为空 |
移除这一组,不写入数据库 |
| 所有组经过清理后都为空 | 不创建笔记,关闭新建页并返回列表 |
这些规则让“添加了几组又没写”“只输入了空格”“最后放弃新建”等情况有确定的行为,也避免数据库中出现没有实际内容的空笔记。
登录后的默认页面是笔记列表,并提供明显的添加按钮。先把进入、记录、保存、再次找到内容这条路径做顺,再考虑搜索、分类和其他扩展。
登录从邮箱密码开始
最初考虑过 Google OAuth,也预留了微信登录的方向。但对一个目前只给自己使用的应用来说,先让登录过程独立、可用更重要,因此默认采用邮箱和密码。
当前不开放注册,只允许配置中的本人账号使用。Google 登录按钮暂时隐藏,后端能力保留为可选项;微信只是预留方向,没有作为已完成的功能对外展示。
首次启动生成随机初始密码。第一次登录后必须修改密码,在完成前不能访问笔记。之后也可以主动修改密码,需要验证当前密码,修改后其他登录会话失效。
这一流程把首次初始化和日常使用区分开。默认密码只用于开始使用,已有账号在正常重启或重新发布后,不会再次被初始化。
前端负责提示和引导,后端负责执行限制。即使绕过界面直接访问接口,也不能跳过登录或首次改密要求。
移动端优先影响的是使用过程
移动端优先不只是让页面在小屏幕上缩小。对这个项目,更具体的要求是:
- 导航和课程入口容易找到,不需要依赖桌面端的侧栏。
- 文章按单列阅读,代码块可以横向滚动,不撑宽整个页面。
- 笔记列表中的添加入口足够明显。
- 自己的话和引用上下排列,保持从思考到引用的输入顺序。
- 表单错误在当前操作位置能被理解,保存后的去向明确。
桌面端可以利用更多空间,但不应该改变核心操作。用手机新建一条笔记,和用电脑新建一条笔记,应该遵循同一套规则。
当前做到了什么
当前项目已经有导航页、博客、自学中心、项目介绍,以及带登录和修改密码功能的私人笔记应用。TypeScript 课程已迁移到公开内容结构中,笔记通过 Go API 保存到 SQLite。
这次没有把所有设想都塞进首版。多用户注册、微信登录和更复杂的笔记管理,不属于当前已经交付的功能。先让公开内容能持续更新、私人笔记能够日常使用,再根据真实使用情况决定下一步。
项目设计确定之后,剩下的问题就是如何让它稳定地运行在小服务器上:镜像怎样构建,域名怎样连接到服务,数据如何在重复发布时保留。这些配置和命令放在部署笔记中继续记录。