本地优先运行

OINK 的本地优先原则很简单：由主题提供的功能，不得暗中依赖公共 CDN、构建期下载或未经配置的公共服务。完整发行包能够在网络隔离环境中构建，其核心页面也能在该环境中浏览。

本地优先覆盖的范围

主题会从生成后的站点提供以下依赖：

这些资源提交在 assets/ 或 static/ 中。Hugo 会按照站点 baseURL 发布它们，部署在子路径时也不例外。

本地优先不覆盖的范围

OINK 无法让作者任意添加的内容自动离线。以下项目仍然是显式网络选择：

• 外部链接、远程图片、视频、iframe 与 API 规范；
• Algolia、Google CSE 等托管搜索；
• 分析、评论、身份提供商与其他 SaaS 集成；
• 作者主动选择远程渲染器时的 PlantUML 或 Diagrams.net。

使用这些功能的页面仍然可以是有效页面，但站点不应再宣称该页面能够完全离线使用。

依赖服务的图表

PlantUML 与 Diagrams.net 不同于纯浏览器库：其常规工作流依赖渲染或编辑服务。因此 OINK 不提供隐含的公共端点。

启用 PlantUML 却未设置 params.plantuml.svg_image_url，或启用 Diagrams.net 却未设置 params.drawio.drawio_server 时，构建会失败并给出可操作的错误信息。你可以配置受控的本地端点、发布预渲染图片，或者明确选择远程服务：

params:
  plantuml:
    enable: true
    svg: true
    svg_image_url: https://diagrams.internal.example/plantuml/svg/
  drawio:
    enable: true
    drawio_server: https://diagrams.internal.example/

为了继续渲染继承而来的图表示例，OINK 文档回归站显式配置了公共演示服务。这是样例站自己的选择，不是主题默认值，也不应复制到网络隔离站点。

本地搜索

设置：

params:
  offlineSearch: true

Hugo 会为每种语言生成搜索索引。浏览器对拉丁文字查询使用本地 Lunr 搜索，对 CJK 文本使用本地子串回退。查询内容不会离开站点。

为了提高搜索质量，请编写清晰的标题与摘要、设置正确的页面语言，并排除不应进入公开客户端索引的生成页面或敏感页面。本地索引可被每位访客下载，不能充当访问控制手段。

页面级资源加载

OINK 不会给每个页面都加载所有运行时。Mermaid、KaTeX、Markmap、Swagger UI、Redoc、Asciinema、ECharts、Infographic 与轮播，会根据页面功能标记按需选取。不使用某个组件的页面不会收到对应运行时。

同一页包含多个相同组件实例时，运行时仍只会加入一次。在 Hugo 流水线允许的情况下，生产资源会生成指纹，便于提供完整性元数据并使用长期缓存。

第三方来源追踪

VENDOR.json 是随附依赖的机器可读清单。每项依赖都会记录：

• 名称与固定版本；
• 原始来源；
• 适用的许可证文件；
• 已选取产物的路径与 SHA-256 值；
• 维护者更新流程。

主题会在 vendor 资源旁保留相应许可证。更新运行时意味着同时更新产物、许可证与 NOTICE 材料、校验值和测试，使整个变更可以一次性审查。

获取离线归档

使用 Oink release 附带的版本化主题归档与 checksum。把两个文件传入隔离环境后运行：

shasum -a 256 -c oink-vX.Y.Z.tar.gz.sha256
tar -xzf oink-vX.Y.Z.tar.gz
mkdir -p product-docs/themes
mv oink-vX.Y.Z product-docs/themes/oink

让隔离站点使用解压后的传统主题：

theme: oink

归档必须包含 go.mod、hugo.yaml、布局、资源、静态文件、翻译、LICENSE、NOTICE 与 VENDOR.json。在断网构建中使用前，应先检查归档内容。

验证隔离站点

有意义的网络隔离验收必须同时覆盖构建阶段与浏览器阶段：

1. 从已经验证的主题归档和空 Hugo 缓存开始；
2. 阻断出站 HTTP、HTTPS 与 Go Module 代理；
3. 运行 Hugo 生产构建命令；
4. 浏览生成结果中的英文与中文页面；
5. 操作搜索、深色模式、图表、API 文档与内容组件；
6. 检查全部 HTML 和 CSS 子资源 URL，确认没有意外远程来源。

项目站点回归套件会针对本地主题候选版本执行这些检查。一次成功只能证明被测提交与环境；每个候选版本以及每次随附依赖更新后都应重新验证。

内容安全策略

本地资源让严格的内容安全策略（CSP）更容易实现，但 OINK 不会为所有站点虚构一份万能策略。作者行内 HTML、ECharts unsafe 模式、分析服务、远程规范与自定义集成都可能改变所需指令。

请从能够支持已审查功能的最小策略开始。让 ECharts 保持结构化数据模式，避免任意行内脚本，只为站点主动启用的集成增加远程来源。