光隙第一版本文档
设计
光隙博客 — 版本文档
版本 1.0.0 | 2026-07-19
版本概述
「光隙」个人博客树洞网站第一版。Next.js 16 + TypeScript + Tailwind CSS 4 + SQLite 单体全栈架构，部署至阿里云 2核2G 服务器（Alibaba Cloud Linux 3.2104 LTS）。
采用"完整骨架 + 核心闭环优先"策略——打通内容发布、图片上传、邀请注册、私密访问、后台管理的完整链路。
技术栈
| 类别 | 技术 | 版本 |
|---|---|---|
| 框架 | Next.js (App Router) | 16.x |
| 语言 | TypeScript | 5.x |
| 样式 | Tailwind CSS | 4.x |
| 数据库 | SQLite (Prisma ORM) | 5.22 |
| 认证 | iron-session (Cookie Session) | 8.x |
| 密码 | bcryptjs | 3.x |
| 图片 | sharp (libvips) | 0.35 |
| Markdown | react-markdown + remark + rehype | - |
| 代码高亮 | highlight.js (GitHub Dark) | 11.x |
| 灯箱 | yet-another-react-lightbox | 3.x |
| 进程管理 | PM2 (500M 内存保护) | - |
| 反向代理 | Nginx | 1.x |
已实现功能
前台（5 个页面）
| 页面 | 路径 | 说明 |
|---|---|---|
| 首页 | / | 全屏沉浸式，左侧个人卡片 + Hero 区 + 三个模块入口卡 |
| 学习记录 | /notes | 公开列表（搜索/分类筛选） + 详情页（Markdown/代码高亮/目录） |
| 摄影作品 | /photos | 公开相册网格 + 瀑布流 + Lightbox 大图 |
| 日常感悟 | /thoughts | 登录后可见，列表/详情/私密留言/阅读记录 |
| 登录/注册 | /login /register | Session 认证 + 邀请码注册（事务防并发） |
后台（8 个模块）
| 模块 | 路径 | 说明 |
|---|---|---|
| 仪表盘 | /admin | 文章/照片/留言/阅读统计 + 存储概览 |
| 内容管理 | /admin/content | 新建/编辑/草稿/发布/软删除 + Markdown 编辑器 |
| 摄影管理 | /admin/photos | 新建相册 + 批量上传 + sharp 生成展示图/缩略图 |
| 朋友管理 | /admin/friends | 查看/启用/禁用 + 阅读和留言统计 |
| 邀请码 | /admin/invites | 生成/作废/状态追踪（7天有效期） |
| 私密留言 | /admin/messages | 按文章/用户查看 + 管理员逐条回复 |
| 阅读记录 | /admin/records | 时间线（30分钟去重） |
| 站点设置 | /admin/settings | 昵称/签名/邮箱/GitHub/手机号/头像等 |
API（21 个端点）
- 认证：
loginregisterlogoutme - 日常感悟：
threadmessagesread - 图片：
upload（sharp 处理，WebP 输出） - 后台 CRUD：
postsalbumsphotosusersinvitesmessagesrecordstagscategoriessettingsdashboard
文件清单
项目根目录/
├── src/
│ ├── app/
│ │ ├── (home)/ 首页（独立全屏布局）
│ │ ├── (site)/ 前台页面（Header + Footer 布局）
│ │ │ ├── notes/ 学习记录
│ │ │ ├── photos/ 摄影作品
│ │ │ └── thoughts/ 日常感悟
│ │ ├── admin/ 后台管理（侧栏布局）
│ │ ├── login/ 登录
│ │ ├── register/ 注册
│ │ └── api/ 21 个 API 路由
│ ├── components/ 7 个共享组件
│ └── lib/ 5 个核心服务
├── prisma/
│ └── schema.prisma 12 个数据模型
├── scripts/
│ ├── seed.ts 快速种子脚本
│ └── init.ts 交互式初始化向导
├── storage/ 图片存储（按年月）
├── docs/ 项目文档
├── ecosystem.config.js PM2 配置（standalone 模式）
├── next.config.ts standalone + 50MB 上传 + 图片优化关闭
├── package.json 25 个依赖
└── .env 环境变量
- 页面文件：16 个
- API 路由：21 个
- 共享组件：7 个
- 核心服务：5 个
- 数据模型：12 个
- 配置文件：8 个
- 脚本：2 个
总文件数：62 个（不含 node_modules 和 .next）
数据模型
| 模型 | 说明 |
|---|---|
| User | 用户（admin/friend 角色，active/disabled 状态） |
| InviteCode | 邀请码（7天有效，单次使用，可作废） |
| Post | 文章（note/thought 类型，draft/published/deleted 状态） |
| Category | 分类（学习记录用） |
| Tag | 标签（Post 和 Photo 共用） |
| PostTag | 文章-标签关联 |
| Album | 相册 |
| Photo | 照片（原图/展示图/缩略图，OSS 归档预留） |
| PhotoTag | 照片-标签关联 |
| CommentThread | 留言线程（每用户每文章唯一） |
| Message | 消息（朋友和管理员互相回复） |
| ReadRecord | 阅读记录（30分钟去重） |
| SiteSettings | 站点设置（key-value） |
安全策略
- 密码：bcrypt 10 轮加盐哈希
- Session：iron-session 加密 Cookie，7 天有效期，生产环境 secure + httpOnly + sameSite
- 权限：页面层布局守卫 + API 层函数守卫，双重校验
- 注册：邀请码原子消费（Prisma 事务 + updateMany 防竞态）
- 账号禁用：每次请求从数据库实时校验状态（非 Session 缓存）
- 登录：安全跳转校验（防 open redirect）
- SQLite：单连接通道 + 5 秒写入超时
设计规范
- 配色：落日晚霞渐变（
#afa88d→#5aa4ae） + 60% 暗色遮罩 - 前台首页：深蓝
#0a192f系卡片 + 橙色#ff7f50强调 - 桌面端：首页左右分栏，列表页最大宽度限制
- 移动端：汉堡菜单、抽屉侧栏、瀑布流自适应列数
- 后台：侧栏导航，克制实用风格
已知限制
| 项目 | 说明 |
|---|---|
| 多管理员 | 不支持，仅单管理员 |
| 密码找回 | 不支持，需管理员手动处理 |
| 公开评论 | 不做，仅私密留言 |
| 系列文章 | 第一版不做 |
| OSS 归档 | 字段和状态预留，实际归档未启用 |
| 邮件通知 | 不支持 |
| 自动备份 | 未配置，需手动备份 |