Skip to content

本地服务挂载原始资源

使用对原始文件进行转换再去挂载的逻辑,有一个好处,就是可以根据不同的任务情况,实现不同的转换结果,这样只需要维护一个原始文件,但最终用在不同的场景中。

本文就是说明了这样一个场景:我一般会有一个本地服务,用的全是本地已有的资源,没有外部的请求。比如字体是提前下载好的、取消站点统计等等,这样浏览器打开和切换文章很快,基本是无感的。

而很自然地,本地服务不会像公开站点一样,有大资源限制,他是可以查看任何如视频文件这种大资源的。但是这就导致一个问题:我不可能像公开站点那样,把资源再复制一份到 docs/asset 目录中,因为大资源最后统计出来大小很大。正确做法是直接挂载原始资源。本文就是讲的实现这样一个需求。

1. 先理解三个结论

  1. 共用的是中间 Markdown,公开站点与本地站点分别生成 HTML。 公开 HTML 可以显示“未在线发布”,本地 HTML 可以在同一位置显示播放器或 PDF 阅读框。
  2. 资源网址不等于磁盘文件位置。 本地服务收到 /asset/... 请求后,可以查表读取 done/ 中的原文件,不要求站点输出目录中存在一份同名副本。
  3. 文件转换、资源复制、网页展示是三个独立步骤。 Word/PPT 可以先生成本地 PDF 缓存,再决定是否复制进发布目录;视频可以直接读取原文件,无须转换或复制。

这一机制主要解决超限资源和独立视频的本地使用问题。普通小图片、小 PDF 等资源仍可沿用原来的复制发布流程。

2. 整体结构

原始内容:D:\Blog\done\
    │
    │ 转换、链接处理、资源登记
    ▼
共享中间文件:D:\BlogSite\masterAllen.github.io\docs\
    │
    ├─ 普通正文、普通资源链接
    └─ 本地资源标记 + resource_cards 元数据
    │
    │ Zensical 根据不同构建配置渲染主题模板
    ├──────────────────────────┐
    ▼                          ▼
公开 HTML                    本地 HTML
local_resources: false       local_resources: true
    │                          │
显示未发布说明                显示播放器、图片或 PDF 阅读框
不生成该卡片的资源请求链接       浏览器请求本地 /asset/... 地址
                               │
                               ▼
                         本地资源服务查登记表
                               │
                   ┌───────────┴────────────┐
                   ▼                        ▼
             读取 done/ 原文件         读取 .resource-cache/ PDF
                   │                        │
                   └───────────┬────────────┘
                               ▼
                         返回文件内容给浏览器

关键:中间生产的 Markdown 是共用的,条件判断发生在主题模板渲染 HTML 时。

3. 转中间 Markdown

3.1 本地资源登记表

转换的时候会维护一个本地资源登记表,位置为:

D:\Blog\scripts\web\configs\local_resources.json

里面包含了许多条目,记录了本地资源,比如:

{
  "8e59c60ed849360b8e104a04de0384b7": {
    "source": "D:\\Blog\\done\\系统性知识\\Computer-Network\\00.Network_Judge\\demo.mp4",
    "conversion": null,
    "kind": "video",
    "name": "demo.mp4",
    "url": "/asset/video/9f31d4a0058ae150ec42806b529c99b2/demo.mp4",
    "fragment": "",
    "style": "",
    "bytes": 65602125
  },
}

字段含义:

字段 含义
KEY 卡片 ID
source 本地服务实际读取的源文件,或本地 PDF 缓存文件
conversion 是否需要请求时转换;普通资源为 null,大 Office 原文件为 word 或 ppt
kind 最终展示类型,例如 video、image、pdf、html
name 展示名称
url 未进行 URL 百分号编码的逻辑资源路径
fragment 需要保留的 URL 后缀,例如图片的 #w65
style 从相应 HTML 元素提取的样式,例如已有的 zoom
bytes 登记时对应源文件的大小

需要注意 local_resource.json 只记录那些需要特别处理的文件,普通一些小图片之类的,还是会按照原来的逻辑处理。不然这个文件最后会非常大,每次重新写会很麻烦。

3.2 中间 Markdown 的资源元数据

转中间 Markdown 时保存渲染需要的信息,不保存登记表中的 source 和 conversion 字段:

---
comments: true
hide:
  - toc
resource_cards:
  - id: 8e59c60ed849360b8e104a04de0384b7
    marker: '<!--blog-resource:8e59c60ed849360b8e104a04de0384b7-->'
    url: /asset/video/9f31d4a0058ae150ec42806b529c99b2/demo.mp4
    kind: video
    name: demo.mp4
    megabytes: '62.56'
    fragment: ''
    style: ''
  - id: 8fe0d22925eff941df89f5a76a6f8185
    marker: '<!--blog-resource:8fe0d22925eff941df89f5a76a6f8185-->'
    url: /asset/html/76885b19a4c5c21bca97e07a1ece4840/demo.html
    kind: html
    name: demo.html
    megabytes: '47.91'
    fragment: ''
    style: ''
---

每个 id 对于文章的一个资源引用。这里的 marker 表示正文中的资源引用标记。比如转换后的 markdown 中内容为:

下面是视频:

<!--blog-resource:8e59c60ed849360b8e104a04de0384b7-->

下面是 HTML 演示:

<!--blog-resource:8fe0d22925eff941df89f5a76a6f8185-->

后续转 HTML 的时候,会有不同的行为(见下个章节),公开构建的网站如下:

下面是视频:

demo.mp4:此资源未在线发布

下面是 HTML 演示:

demo.html:此资源未在线发布

本地构建的网站如下:

下面是视频:

[播放器]

下面是 HTML 演示:

[HTML 阅读框]

resource_files.add_metadata() 负责这个功能,它会扫描正文标记,从登记表提取相应记录,将所需字段写入 resource_cards。

4. 共用 Markdown 如何生成不同 HTML

4.1 构建配置说明

之所以能生成不同 HTML,是因为构建配置不同。

公开配置和本地配置的关键就在于,这个 local_resources 的值不同。

extra:
  local_resources: false

Mkdocs/Zensical 转换的时候可以利用这些配置来生成不同的 HTML。比如核心条件可以简化理解为(简化理解,后面会详细解释实际逻辑):

{% if config.extra.local_resources %}
  <!-- 根据资源类型生成本地预览与链接 -->
{% else %}
  <!-- 生成未在线发布说明 -->
{% endif %}

4.2 模板渲染顺序

Zensical 将 Markdown 转为 page.content
    ↓
base.html 检查 page.meta.resource_cards(也就是 5.2 节所说的文章开头保存的信息)
    ↓
有资源卡片时使用 resource-content.html(见下文 6.3 节)
    ↓
逐个读取资源元数据,每个数据使用 resource-card.html 生成卡片 HTML(见下文 6.4 节)
    ↓
将 page.content 中对应注释标记替换为卡片 HTML

4.3 统筹替换逻辑

resource-content.html 是我们新增的主题模板片段,负责统筹处理把正文里的标记替换成资源卡片 HTML。

{% set rendered = namespace(content=page.content) %}

{% for resource in page.meta.resource_cards | d([]) %}
  {% set card %}
    {% include "partials/resource-card.html" %}
  {% endset %}

  {% set rendered.content = rendered.content | replace(resource.marker, card) %}
{% endfor %}

{{ rendered.content | safe }}

它的工作过程是:

  1. 取得当前文章的正文 page.content。
  2. 遍历文章的 resource_cards 列表。
  3. 为每个资源生成卡片 HTML。
  4. 找到正文中对应的 marker,替换成这张卡片。
  5. 输出替换后的正文。

4.4 单文件替换逻辑

resource-card.html 负责生成单个资源卡片 HTML,他会来判断是公开还是本地预览。然后根据判断结果生成不同的 HTML。

<span class="blog-resource">
  {% if config.extra.local_resources %}

    {# 这里生成本地播放器、图片或 PDF 阅读框 #}

  {% else %}

    <span>
      {{ resource.name }} · {{ resource.megabytes }} MB:
      此资源未在线发布,可在本地服务中查看。
    </span>

  {% endif %}
</span>

所以最终调用关系是:

base.html
  → resource-content.html:遍历资源,替换正文标记
      → resource-card.html:判断配置,生成每张卡片;这里公开站点和本地站点就会有不同内容

5. 两种本地服务的读取方式

本地挂载 http 服务,用于访问站点,启动入口:

python -X utf8 D:\Blog\scripts\web\serve_local_site.py

这里的 URL 有两种类型,一种是文章页面,一种是资源请求:

http://127.0.0.1:8000/系统性知识/
http://127.0.0.1:8000/asset/video/<哈希>/demo.mp4

脚本里面会判断 URL 类型,他会注册 /asset/ 资源路由:

local_resource.py
def handlers(fallback_root=None):
    return [
        (
            r'/asset/(.*)',
            ResourceHandler,
            {
                'path': settings.srcdir,
                'fallback_root': fallback_root,
            },
        ),
    ]

其中 r'/asset/(.*)' 表示:匹配 /asset/ 开头的请求,交给 ResourceHandler。而后续就是去查找本地登记表,看看是否有这个哈希,如果没有就回退读取 asset 中已有的普通静态资源。

本地登记表会维护一个 url_to_value 的查找表,所以查找速度是 O(1),很快:

# 登记表加载或变化时,建立一次索引
resources_by_url = {
    item['url']: item
    for item in registry.values()
}

# 每次请求直接查找
record = resources_by_url.get(url)
这里为什么不直接用 http://127.0.0.1:8000/asset/video/<哈希> 这种形式?

如果这里的哈希是 KEYID,那么这样直接是 O(1) 复杂度,查找很快。

但这个会带来一些问题,最最主要的是缩放图片时比较麻烦。假设原文中同一图片出现两次:

![第一次](large.png#w50)
![第二次](large.png#w65)

当前卡片 ID 的计算包含宽度后缀,因此两处的 ID 不同,可以简称为 A、B。

旧 URL 是:

/asset/image/目录哈希/large.png#w50
/asset/image/目录哈希/large.png#w65

图片缩放功能去掉 #w50、#w65 后,两个地址相同,于是知道:这是同一原图出现了两次,第二张对应原文中的第二次引用。

改成 KEYID 地址后:

/asset/image/A#w50
/asset/image/B#w65

去掉宽度后,地址仍然不同。原来的前端分组逻辑会把它们当成两张不同图片,只把选中的一张发给编辑接口;而接口从原文中找到的是两次引用。数量对不上,就会拒绝。

可以处理,但是这样太过麻烦了。所以使用直接查找 url 的方式,而且也是维护一个查找表,无非内存多用一点而已了。

细节

  1. 例如,一份 PDF 以前只有 5 MB,允许发布;后来变成 20 MB,转为本地专用时,需要删除之前的发布副本。转换过程会处理一下这种情况。

  2. 本地文件名有很多不好的字符,比如空格、百分号等等等,所以转 url 会在生成元数据时进行百分号编码。

Comments

本文阅读 Loading 次 本站访问 Loading 次 访客 Loading 人