使用场景
微光集里的 Share,是想把网盘里的资料也放进自己的内容入口。整体介绍见 关于本站:微光集。
OpenList 已经有存储挂载、文件操作、分享和下载能力,我需要的是让这些内容出现在网站里,沿用微光集的目录、标签和预览交互。
文件仍交给 OpenList 管,网站负责组织入口和补上适合阅读的界面。
实现内容
Share 分成访客空间、管理员空间和分享项目三个范围:
| 范围 | 进入方式与用途 |
|---|---|
| 访客空间 | 普通访问者浏览 OpenList 已开放的目录 |
| 管理员空间 | 本站管理员登录后取得 OpenList 会话,执行文件管理 |
| 分享项目 | 使用独立分享标识访问文件或目录,按需验证提取码 |
页面提供目录浏览、排序、预览、下载、链接复制,以及权限允许的上传、重命名、移动、复制、删除等操作。分享项目可以补充标签、说明、别名和评论权限,也能进入全站搜索、标签页、星轨图和 RSS。
进入全站内容索引的是“分享项目首页”。项目内部的一百个文件,不会自动变成一百篇独立内容。
对接入口与部署关系
公开路径沿用本站 Share 页面:
/Share/访客/…
/Share/空间/…
/Share/分享/{分享标识}/…配置分成两种地址:后端访问 OpenList 的内部地址,以及浏览器访问的公开地址。两者不要求相同。
文件浏览、操作:浏览器 → OpenList 公开 API
分享元数据改动:浏览器 → 本站 Go 桥接 → OpenList
导航与内容索引:Go 读取 OpenList 只读数据库 → 本站统一索引因此,这一部分不能笼统地说成“所有请求都由本站后端代理”。实际文件 API 使用公开文件服务地址,部分涉及本站元数据和评论权限的操作才经过 Go。
登录和访问权限
管理员空间不再提供一套独立的 OpenList 登录表单,而是从本站统一身份接口取得文件服务会话。
浏览器随后使用 OpenList Token 发起允许的文件操作,真正的路径范围、用户权限仍由文件服务校验。界面按钮只是对应权限的入口,不承担最终授权。
访客和分享项目可以匿名访问,但需要继续传入正确的路径和提取码。分享内部通过 /@s/{分享标识}/… 这样的文件服务路径定位。
分享不存在、过期或者达到访问次数上限时,不能继续把原页面当成正常项目展示。用户主动取消、切换文件和离开页面时,相关请求也会取消。
说明、标签与评论的约定
本站会读取分享已有的 header、readme,并在 OpenList 分享备注里保存结构化元数据。例如:
{
"tags": ["资料", "微光集"],
"sharedAt": "2026-11-16T00:00:00+08:00",
"order": 10,
"comment": true,
"jellyfin": false,
"aliases": {
"/安装说明.md": "先看这里"
}
}comment 控制普通用户能否评论,jellyfin 控制媒体匹配,aliases 用相对分享根目录的文件路径配置显示名,也就是别名,方便展示。
这是微光集对备注的约定,并非 OpenList 原生字段。管理界面的快捷修改会合并已有元数据。
分享评论复用 Artalk评论系统对接 中的页面权限。
加密分享的正文受提取码保护。当前星轨图可以使用已存储的项目关联信息。
使用的 API
以下原生接口相对于 OpenList 公开或内部服务地址,具体调用地址由使用场景决定。
| OpenList 接口 | 用途 |
|---|---|
POST /api/auth/login、GET /api/me | 管理会话建立、用户权限确认 |
GET /api/public/settings | 文件预览等公开配置 |
POST /api/fs/list、POST /api/fs/get | 目录、文件信息与下载地址 |
POST /api/fs/dirs | 目录选择等场景的子目录读取 |
PUT /api/fs/put | 文件上传 |
POST /api/fs/mkdir、…/rename、…/move、…/copy、…/remove | 文件管理操作 |
GET /api/share/get?id=… | 分享配置读取 |
POST /api/share/create、…/update、…/delete?id=… | 分享创建、编辑、删除 |
/d/{文件路径} | 文件下载,按文件服务规则携带签名 |
| 本站接口 | 用途 |
|---|---|
GET /api/public/quartz/entries | 导航可用的访客与分享入口 |
POST /api/drive/share-page、…/share-create、…/share-update、…/share-delete | 分享操作与本站元数据、评论权限桥接 |
/internal/share/route | 供反向代理验证 Share 深层路径,返回实际页面或错误状态 |
入口索引还会只读查询 OpenList 的 x_users、x_meta、x_sharing_dbs 等表。这部分依赖当前数据库结构,升级 OpenList 时需要一起检查适配器。
文件预览
普通图片、文本、Markdown、音视频等文件,按文件类型使用合适的预览器。管理员的文件管理操作仍在原目录范围内完成。
设置了jellyfin: true并且能够匹配 Jellyfin 的媒体,走另一条专门的媒体链路:查找媒体条目、读取海报和简介、选择音轨与字幕、协商播放方式,再由 Jellyfin 执行必要的转码,详见:Jellyfin媒体播放对接
这里的媒体请求使用独立的媒体公开地址,并保留文件或分享的授权信息。OpenList 负责文件访问范围,Jellyfin 负责媒体能力,微光集负责把它们组合到页面里。
预览器如何接入
文件列表和文件内容是两条链路。OpenList 的 fs/list、fs/get 提供文件类型、大小、存储驱动和下载地址;本站再结合公开配置生成可选预览器,文件本身仍从文件服务读取。
OpenList 文件信息 + /api/public/settings
↓ 根据格式、驱动和分享设置选择预览器
Share 预览区域
├─ 图片:现有图片预览
├─ 办公文档 / PDF:JitViewer 或备用渲染器
├─ 文本 / Markdown:代码或排版预览
├─ 音视频:播放器
└─ 压缩包:读取目录,再预览包内文件同一个文件可以切换不同预览方式,选择会写入页面的 preview 参数。预览开关、分享是否允许预览、压缩包是否默认展开,以及文件类型和大小,都会影响可用选项与默认顺序。
不支持的文件仍保留文件信息和下载操作;组件加载失败或超时,也会回退到文件视图并显示原因。
使用的预览组件
| 文件 / 场景 | 组件与处理方式 |
|---|---|
| DOCX、XLSX、PPTX、PDF,以及 CSV、TSV、OFD 的预览入口 | 优先使用独立部署的 JitViewer,具体格式效果取决于 SDK |
| PDF 备用预览 | 浏览器原生 PDF,或基于 PDFium 的 EmbedPDF |
| Word 备用预览 | docx-preview配合 JSZip,在浏览器解析 DOCX |
| Excel 备用预览 | ExcelJS,解析 XLSX 并显示工作表与单元格 |
| PowerPoint 备用预览 | PPTXjs 及其依赖,在浏览器转换展示 PPTX |
| Markdown | marked 解析,DOMPurify 清理 HTML;提供普通与自动换行两种模式 |
| 文本、代码 | highlight.js 高亮,或使用只读 Monaco Editor;支持选择文本编码 |
| 普通图片 | 现有图片预览组件;部分 HEIF / HEIC 等格式使用解码预览 |
| 普通视频 | Artplayer,按格式接入 HLS 或 mpegts 等播放能力 |
| 音频 | APlayer |
| 360° 视频 | egjs View360 |
| Flash | Ruffle,通过 WebAssembly 模拟播放 |
终端录屏 .cast | asciinema-player |
| 压缩包 | OpenList 压缩包 API,本站展示目录和包内文件入口 |
.torrent、.url | 展示种子信息,或读取快捷方式中的有效网址 |
Monaco 在这里用于只读查看,虽然菜单叫“文本编辑器”,并没有接入修改后保存回 OpenList 的能力。旧版二进制 DOC、XLS、PPT 也不能按 DOCX、XLSX、PPTX 的支持情况理解。
JitViewer 的部署与改造
JitViewer 独立运行,本站通过 /jit-viewer/ 反向代理接入。嵌入时传入以下信息:
| 参数 | 用途 |
|---|---|
file | 已取得的文件访问地址 |
name、size | 真实文件名与大小,分享名称没有后缀时也能按原文件识别 |
embed=1 | 隐藏独立页面的地址输入栏 |
theme | 初始亮暗主题 |
channel | 校验父页面与预览器之间的消息 |
Share → 同源 JitViewer iframe
↓ /jit-viewer/file/ 受限文件代理
OpenList 文件接口
↓
浏览器内解析与渲染文件代理只接受本站 Drive 的 /d/、/p/、/sd/、/sad/、/ae/ 等文件路径,保留访问所需的签名、提取码和压缩包密码,不作为任意网址或管理接口的代理。链接文件流式转发,不为预览生成一份服务端转换文件。
本站补上了下载进度、就绪和错误消息,避免文件还在解析时就提前结束加载。父页面校验消息来源、发送窗口及通道;亮暗切换通过消息调用 SDK 的 setTheme,网页全屏也沿用现有页面能力。
嵌入界面保留缩放、旋转、翻页与全屏,下载入口统一放在 Share 原有操作区域。本地调整还包括 PPTX 根据容器尺寸排版,以及缩放时保留已解析的幻灯片,减少重新解析导致的黑屏。
当前部署已验证 DOCX、XLSX、PPTX、PDF;CSV、TSV、OFD 虽然已有入口,仍应以实际文件的渲染结果为准。旧版 DOC 不支持,现有二进制 XLS、PPT 测试也不能正常按压缩包格式解析,因此不作为首选预览。
预览隔离与资源加载
多数内置渲染器在隔离 iframe 中运行,避免第三方组件的样式、全局变量影响主页面。文件和预览资源按需要读取,通过消息回传下载进度、就绪、错误及内容高度,父页面负责加载状态和预览区域尺寸。
JitViewer 为了使用同源消息和自身能力,单独允许同源 iframe;浏览器原生 PDF 也有专门的加载方式。
组件资源有本站静态资源、Drive 静态资源以及外部 CDN 几种来源,当前并非全部离线自托管。
HTML 文件以隔离页面展示,并以原文件地址解析相对资源;Markdown 内容会先清理 HTML。切换文件、预览器或离开页面时,会取消相应请求并清理旧预览实例。
压缩包内文件预览
压缩包使用 OpenList 的 POST /api/fs/archive/meta 和 POST /api/fs/archive/list 读取目录与文件信息,保留原文件路径、分享提取码;加密压缩包额外提交 archive_pass。
选择包内文件后,再通过对应文件接口取得内容,交回同一套预览器。
能否查看目录或读取内部文件,还取决于 OpenList 的驱动、压缩格式及服务端配置。前端展示了入口,并不代表所有压缩格式都能在线解压预览。
对应实现
quartz/components/scripts/drivePreviewOptions.ts:预览方式、格式与公开配置的对应关系。quartz/components/scripts/drivePreview.ts:预览选择、加载状态、iframe 生命周期与消息桥接。quartz/components/scripts/drivePreviewSandbox.ts:内置格式渲染器与组件加载。quartz/components/scripts/preview/videoRenderer.ts:普通视频播放与字幕等交互。quartz/components/scripts/driveArchivePreview.ts:压缩包目录、密码和包内文件预览。- 独立部署的
jit-viewer:SDK 页面、受限文件代理和本站嵌入适配。
另外一个用途:友链头像存储
友链头像也借用了 OpenList,目录固定为 /Vault/MicroLight/avatar/。
后台下载头像后先算源文件哈希,命中压缩缓存时直接复用;需要处理时保留动画、压缩,再根据结果文件的 SHA-256 命名上传。前台通过本站头像接口读取,不直接暴露管理凭据。
这里的“相同文件”按实际字节判断。原 PNG 与压缩后的 WebP 看上去一样,文件哈希仍然不同。