项目笔记:从博客、自学中心到私人笔记

文章目录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。

这次没有把所有设想都塞进首版。多用户注册、微信登录和更复杂的笔记管理,不属于当前已经交付的功能。先让公开内容能持续更新、私人笔记能够日常使用,再根据真实使用情况决定下一步。

项目设计确定之后,剩下的问题就是如何让它稳定地运行在小服务器上:镜像怎样构建,域名怎样连接到服务,数据如何在重复发布时保留。这些配置和命令放在部署笔记中继续记录。