使用场景
微光集的内容越来越多,除了 Obsidian 里的文章,还有文件分享、代码仓库、视频,以及日历、活动统计和服务状态这些日常信息。
如果每接入一个服务,就给它单独做一套导航、标签和搜索,最后还是几个互不相关的页面。我希望这些东西保留各自适合的使用方式,同时能够在一个站点里被找到、引用和管理。
关于本站:微光集 更偏向介绍网站是什么,这篇记录内部的模块构成,以及这些模块是怎样接到一起的。具体平台的 API 和改造细节,放在各自的对接文章里。
源数据由原来的服务管理,微光集维护自己的内容索引、页面交互和管理能力。
模块构成
先从页面上能看到的部分划分:
| 范围 | 模块 | 负责内容 |
|---|---|---|
| 内容入口 | 文章、Share、Repo、Video | 四类内容的阅读、浏览与详情交互 |
| 内容发现 | 视界、目录、搜索、流光、星轨图、流新、拾遗、RSS | 用不同方式找到同一批内容 |
| 首页与个人信息 | 星域、星历、彗星、寻径、活动与平台资料 | 内容分布、日常记录、来访及外部入口 |
| 交流 | Artalk 评论、Bilibili 只读评论、友链、反馈 | 评论与站点交流 |
| 状态与管理 | 星枢、配置、数据、任务、告警、账户 | 查看运行情况并维护本站 |
它们底下共用几层能力:页面构建、运行时 API、统一索引、身份权限、缓存和后台任务。
整体架构
当前部署由 Quartz、Go、MySQL、Nginx 组成,使用同一份 Docker Compose 管理。Artalk 也在这份部署中,OpenList、Jellyfin、Gitea 等服务保留各自的部署和数据。
Obsidian 文章 / 页面源码
↓ Quartz 构建与监听
静态页面、前端脚本、私有内容快照
↓ ↓ 构建成功通知
Nginx Quartz Server / Go
↓ ↕
浏览器 MySQL
↕ ↕
文件、评论、媒体等入口 第三方服务与必要的只读数据各层职责
| 层 | 主要技术 | 在微光集里负责什么 |
|---|---|---|
| 页面与构建 | Quartz 4、TypeScript、组件与 SCSS | 文章处理、页面生成、前端打包、文件监听 |
| 浏览器交互 | 页面脚本、共享组件、Canvas / WebGL | 目录、弹框、抽屉、星轨、播放器、管理表单 |
| 业务后端 | Go | 身份、配置、内容索引、统计、同步、权限与平台适配 |
| 本站存储 | MySQL | 本站业务记录、平台快照、配置及缓存 |
| 访问入口 | Nginx | 静态文件、路由分发、反向代理及域名接入 |
Quartz 在服务器上持续运行,是因为需要监听笔记和源码,并不是每次访问文章都临时生成 HTML。Go 也持续运行,负责那些需要鉴权、数据库或后台处理的工作。
文件下载、Artalk 原生评论、Jellyfin 原生服务和 Bilibili 播放器各有访问链路。
四类内容入口
文章:从 Obsidian 到静态页面
文章源文件仍然是 Markdown,frontmatter 记录标签、日期、发布状态、评论开关和加密设置等信息。
保存笔记
↓ 文件监听
解析 Markdown、Obsidian 内链及属性
↓ 应用发布规则与页面插件
生成 HTML、资源与成功快照
↓ 发布页面,通知 Go
统一索引与评论权限更新正文、目录和大部分阅读结构在构建阶段生成。Obsidian 的 [[笔记]]、标题锚点,以及文章中的本站 Share、Repo、Video 项目链接,会在处理过程中保留为可导航的链接或关联信息。
Obisidian笔记有独特的meta元素控制一些功能,见笔记meta
发布和公开发现也分开处理。没有发布的笔记不应进入公开页面;仅链接可见、加密等情况则按各自规则决定入口、正文和关联的可见范围。
加密文章在浏览器中通过 Web Crypto 解密,使用 PBKDF2 派生密钥和 AES-GCM 读取正文。公开星轨可以展示索引中已保存的关系,但不会为了画图额外请求解密正文。
标签和关联可能暴露主题及项目关系。正文受保护,不代表所有元数据也需要隐藏;当前站点明确允许未解密时展示已有星轨关系。
Share:文件与分享项目
Share 复用 OpenList 的文件能力,分为访客空间、管理员空间和分享项目。
文件目录按需读取,进入某个文件后,再按格式选择图片、文本、办公文档、音视频或压缩包预览。预览器不会把每个文件变成独立文章,进入统一索引的是分享项目首页。
办公文档与 PDF 优先使用 JitViewer;普通视频使用 Artplayer;满足条件的媒体可以继续接入 Jellyfin。Jellyfin 负责播放协商与必要的转码,OpenList 负责文件访问范围。
具体实现见 OpenList文件分享对接、Jellyfin媒体播放对接。
Repo:仓库与代码阅读
Repo 把仓库列表、README、目录、文件、提交、差异和 Release 放进本站的阅读布局。
Gitea 提供现有仓库与镜像,GitHub 保留上游代码、Release 和部分活动资料的角色。本站后端读取必要的仓库信息及现有 Git 存储,再提供受限的详情接口。
仓库首页进入统一索引,默认分支根目录的 README 用于搜索和项目关联;分支、文件、提交等详情继续按需请求。这样搜索能找到项目,读代码时又不必把整个仓库塞进内容目录。
仓库中的相对链接按当前文件、仓库和版本解析,图片转成对应资源地址,Markdown 渲染后再清理 HTML。图表、代码高亮等能力按需要加载。
镜像同步与网页读取分开:同步负责让 Gitea 追上上游,浏览器读取当前可用版本。详细流程见 Gitea代码仓库对接。
Video:视频资料与平台播放
Video 后台同步 Bilibili 视频及系列资料,在本站组织标题、发布时间、简介、封面、分集和相关视频。
播放仍使用 Bilibili 官方 iframe。本站不托管平台视频文件,也不把普通文件播放器和 Bilibili 播放器混成同一条链路。
视频首页进入统一索引,简介中的本站项目链接参与关联。评论从 Bilibili 按需读取,保留原生热门排序与分页能力;访问者需要发表评论时,使用“前往 B 站评论”入口。
统一索引:四类内容怎样共用一套发现能力
文章、分享、仓库和视频有不同的数据来源,但用于发现内容的信息相近:标题、地址、日期、标签和关联。
本站在 MySQL 的 content 表中维护统一记录,用 type 区分来源,并通过 extra 保留类型特有信息。
| 字段 | 作用 |
|---|---|
type、source_id | 来源类型与来源中的稳定标识 |
slug、href | 关联标识与可访问地址 |
title、description | 标题和可公开摘要 |
published_at、updated_at | 发布时间与更新时间 |
tags、links | 标签及站内关联 |
encrypted | 加密状态 |
search_text | 允许用于搜索的文本 |
revision、event_revision | 识别内容变化与重复事件 |
extra | 仓库语言、视频系列、原始文章路径等附加信息 |
进入索引的范围
| 来源 | 索引范围 |
|---|---|
| 文章 | 按发布规则处理后的文章信息及允许公开的文本 |
| Share | 分享项目首页;普通分享可索引首页直接文件名,不递归扫描全部目录 |
| Repo | 仓库首页与默认分支根 README |
| Video | 视频条目及简介等资料 |
管理员文件空间不进入公开索引,加密内容不会公开搜索正文。
目录、星域数量、流光、星轨、流新和拾遗共用 /api/site/content。搜索按关键词调用 /api/site/content/search,需要正文时才读取相应搜索字段,普通目录读取不带整篇内容。
统一索引用于发现,真正打开文件、仓库分支或视频详情时,仍调用各自业务接口。
来源变化怎样合并
来源同步先比较记录,有新增、修改或删除时才更新数据库,并同步必要的纪事和订阅元数据。上游故障会作为失败处理,保留已有有效记录,避免把“请求失败”误当成“来源已经清空”。
文章来自成功构建快照;Share、Repo 结合操作事件与后台检查;Video 在同步、详情刷新或管理操作后通知索引任务。
文章的标签修改写回笔记,再等待 Quartz 发布;Share 编辑沿用分享元数据;Repo、Video 的人工标签保留在本站索引中。这些写入位置不同,是为了让各自的源数据与后续同步能够对应。
目前标签按现有来源与人工维护规则工作,主标签、随从标签的映射方案尚未实施。
内容发现模块
视界与目录
视界把四类内容按时间组织,目录则保留各自的结构:文章目录、仓库语言、视频系列,以及 Share 的文件与分享入口。
流光与搜索
流光围绕标签组织不同类型的项目,搜索围绕关键词查找标题、摘要和允许检索的内容。
这里复用同一份索引,不让每个页面各自请求一遍 OpenList、Gitea 和 Bilibili,再在浏览器中临时拼结果。管理操作完成后使相关缓存失效,下一次读取反映最新索引。
星轨图
星轨图使用 D3 计算节点布局,再由 PixiJS 绘制节点、文字和连线。
内容与标签形成图结构,正文或简介中的站内引用补充项目之间的关系。微光集节点作为视觉中心,布局结果再配合围绕中心的旋转、拖动、缩放及悬停预览。
力导向布局和整体旋转是两件事。 新增节点会改变布局计算,已有节点的位置可能随之变化,并不意味着围绕中心的旋转失效。它也不是每个节点都固定在一条圆轨道上的天体模拟。
本地小图和展开大图复用图的数据与渲染逻辑;文章、分享、仓库、视频可以按类型筛选。加密状态的小标识只负责展示,不另外生成一套解密后的关系索引。
流新、拾遗与 RSS
| 模块 | 使用方式 |
|---|---|
| 流新 | 根据内容变化发现近期更新 |
| 拾遗 | 从已有公开内容中随机发现,按类型提供预览 |
| RSS | 按发布时间输出最近发布的公开内容 |
RSS 由 Go 从索引生成,/index.xml 包含四类内容,/articles.xml 只包含文章;两者均取最近发布的 20 条,不使用更新时间把旧内容重新顶上来。
全部订阅使用文章 ✒️、仓库 🍵、分享 🔗、视频 🎬 区分类型,仅文章订阅不加类型 emoji。首页订阅弹框预览三篇,并提供全部、文章两种链接的复制与打开;head 的自动发现仍指向原本的 /index.xml。
首页模块:个人信息与日常记录
首页由模板生成,静态布局与运行时数据分开。页面先保留模块位置,动态数据就绪后再填充,避免每次请求完成都重新推动布局。
| 模块 | 数据来源与实现思路 |
|---|---|
| 个人资料与平台活动 | 后端读取并缓存 GitHub、Bilibili 等资料,页面展示聚合结果 |
| 星域 | 从统一索引统计四类内容并提供入口 |
| 星历 | 读取私有日记中的限定标记,生成日期统计,不公开日记正文。关于日记:日记日报方案 |
| 拾遗 | 复用内容索引和对应类型的预览 |
| 彗星 | 用访客摘要生成 Canvas 画面,详情打开后才读取分页记录 |
| 寻径 | 使用站点配置维护外部链接与订阅入口 |
| 活动统计 | ActivityWatch 汇总,以及独立的实时活动状态来源 |
星历按月份读取并共享相邻月份缓存;文件变化后等待一段安静期再聚合,避免连续保存时重复扫描。
彗星的记录和展示是两个接口:POST /api/visitors/visit 记录真实导航,统计与分页记录接口只负责读取,不会因为打开详情就新增一次访问。星体和轨迹在浏览器绘制,光晕等重复元素预绘制后复用,页面隐藏或离开视口时暂停绘制。
活动统计中的“汇总”和“此刻状态”也分开。汇总按窗口活动与非离开时段计算,实时状态走现有状态服务,具体见 ActivityWatch活动统计对接。
评论、友链与反馈
两种评论来源,共用展示样式
本站文章、允许评论的 Share 和 Repo 使用 Artalk。普通访问者沿用昵称、邮箱的评论方式;管理员身份与评论权限由本站已有桥接处理。
Bilibili 评论保持只读,使用自己的读取和分页接口,但和 Artalk 共用评论计数、排序、加载、头像布局及置顶等展示样式。
本站评论需要点赞能力,Bilibili 部分只展示平台评论;热门排序也分别交给 Artalk 和 Bilibili 的原生能力处理。具体身份与页面权限见 Artalk评论系统对接。
友链
友链记录、审核状态、巡检、RSS 和头像刷新由后端管理。前端读取可公开的数据,后台提供编辑、审核、排序和头像维护。
头像先比较源文件哈希,命中已有压缩结果时复用;需要处理时保留动画并压缩,根据结果哈希存入文件服务。刷新失败会保留当前头像,记录原因等待重试。
这份缓存是友链头像的处理结果。评论用户的 Cravatar 探测与前端生成头像属于另一条链路,不能因为它们都叫头像,就共用同一个授权或缓存键。
反馈
反馈是本站的数据入口,提交后由后端保存和管理。管理权限、提交校验与通知凭据保留在服务端,浏览器只负责表单交互。
通知、审核
反馈与友链同时接入了Astrbot推送消息及LLM处理,详见AstrBot通知与审核对接。
星枢与后台管理
星枢把公开状态和管理员操作放在同一套界面体系中,但公开接口和管理接口分开。
| 范围 | 负责内容 |
|---|---|
| 状态展示 | 服务资源、监控、活动与运行纪事 |
| 站点配置 | 页面资料、外部入口、服务接入及各模块设置 |
| 数据维护 | 友链、评论、反馈及对应业务记录 |
| 任务 | 周期、事件、恢复任务的状态、配置、日志和重试 |
| 告警 | 上游调用、后台任务及服务异常的归档与处理 |
| 账户 | 管理员身份、密码、TOTP 和会话相关维护 |
配置由后端 schema 描述,包含字段类型、分类、默认值、范围与公开性。管理页据此生成已有表单,服务地址、API Key 等字段放进对应服务分类,不再给每个服务维护一份独立配置界面。
公开设置只返回允许公开的字段。管理员能编辑某个密钥,并不意味着这个字段可以进入首页聚合或前端通用缓存。
身份与服务接入
管理员认证使用密码与 TOTP,登录后建立本站会话。前端显示登录状态只影响入口与交互,管理 API 仍逐次校验权限。
不同服务的凭据和用户上下文保留各自作用:OpenList 会话用于文件管理,Jellyfin API Key 用于上游鉴权并结合配置用户协商播放,Artalk 负责原生评论身份。本站统一入口不代表把这些凭据变成一个可以任意访问所有服务的 Token。
任务与告警
周期任务适合检查外部来源,事件任务适合响应构建和数据变化,恢复任务处理已经失败的工作。
任务记录真实的开始、结束、结果和日志,异常项提供重试入口;队列则反映等待与执行中的工作。
告警保留在管理员范围内,由实际请求或任务失败分支采集。
更新与缓存
构建成功后才发布
Quartz 不先清空线上目录,而是在独立版本目录中生成新产物。成功后原子切换 public/current,失败时继续提供上一份成功页面。
文件变化 → 候选版本构建
├─ 失败:保留现有页面
└─ 成功:切换 current → 写成功快照 → 通知 Go 更新索引页面目录切换是原子的,但页面发布与私有快照不是跨目录数据库事务,两者之间仍有处理顺序。
Go 启动时补读已有快照,正常收到发布事件后再处理变化,避免每秒扫描没有变化的文章。构建端用受控子进程承载编译后的构建实例,完整重载释放旧进程,避免不断导入新模块导致旧内存长期积累。
请求共用与页面清理
前端使用共享请求缓存合并同键并发读取,多个组件需要索引时不重复拉取。一个组件退出只取消自己的订阅,全部调用者离开后才中断底层请求。
缓存键包含必要的账号、路径或权限范围;退出登录或写入成功后使对应缓存失效。播放器、事件监听、计时器和页面请求接入现有离页清理,避免 SPA 导航后旧页面还在继续工作。
后端进程缓存负责合并请求和减少上游压力,MySQL 快照负责重启后保留数据。
文件下载、媒体流、表单提交和权限校验保留自己的生命周期,不直接套用公开查询缓存。
对应实现
| 位置 | 对应模块 |
|---|---|
quartz.config.ts、quartz.layout.ts | 页面构建配置与组件布局 |
quartz/home/ | 首页模板、模块配置与图标 |
quartz/components/scripts/ | 页面交互、共享请求、预览及管理界面 |
quartz/plugins/emitters/ | 文章及动态页面入口产物 |
quartz/util/contentSnapshot.ts | 成功文章构建快照 |
quartz/cli/buildProcess*.mjs | 构建子进程、发布锁与热更新生命周期 |
quartz-server/internal/application/ | 后端模块装配、启动与关闭 |
quartz-server/internal/httpapi/ | 公开、管理与服务适配 HTTP 入口 |
quartz-server/internal/content/ | 四源索引、搜索、RSS 等内容能力 |
quartz-server/internal/openlist/、repo/、video/、jellyfin/ | 文件、代码、视频和媒体服务适配 |
quartz-server/internal/auth/、settings/、credentials/ | 身份、配置与凭据 |
quartz-server/internal/taskruns/、alerts/ | 任务记录与异常处理 |
quartz-server/database/init.sql | 本站库表定义 |
上表中前端路径相对于 Quartz 工程,后端路径相对于项目根目录。全局边界和维护约定继续以项目中的 README.md、architecture/service-rules.md、architecture/cache.md 为准。
目前的取舍
这套结构适合我现在的个人网站:文章尽量提前构建,动态内容按需读取,共用索引和组件,专业服务继续做它们擅长的事情。
代价是需要维护适配边界。第三方数据库结构、平台 API、浏览器媒体支持和组件资源来源都可能变化;缓存能够缓解短期故障,不能替代权限校验,也不能保证上游永久可用。
后面增加内容类型或页面功能时,我会先看它能否接入已有索引、组件和任务,再决定是否确实需要新增一条链路。