TeamOS Wiki

主题

Wiki 图片视频管理规范 ​

本文给所有要往 wiki 里塞图片、视频、PDF 等二进制资产的人和 agent 看。一句话总结：正常拖进文件夹、正常 git add 即可，仓库已配 Git LFS 自动接管。

1. 为什么要有规范 ​

Git 本身擅长存文本（一行改 → 一行 diff），不擅长存二进制（一个像素改 → 整张图重存）。如果不管，仓库大小很快从几 MB 涨到几 GB，clone 慢、push 慢、CI 慢，最后没人愿意用。

我们的方案：

  • 文本（.md）走普通 Git
  • 二进制（图片/视频/PDF/Office/设计稿）走 Git LFS，仓库里只存 120 字节的 pointer，真正的二进制存在 GitHub LFS 服务器
  • 你写内容时完全感受不到：![](path/to/image.png) 还是普通 markdown 写法

2. 放哪里 ​

2.1 目录约定 ​

wiki-vault/
└── canon/                        ← 你写的页面
    ├── 品类/
    │   └── 蒸汽挂烫机.md
    └── _assets/                  ← 所有资产统一这里
        ├── 蒸汽挂烫机/           ← 按主题分子目录
        │   ├── bsr-trend.png
        │   ├── 拆解图.jpg
        │   └── unboxing.mp4
        └── _common/              ← 多页复用的图（如 logo、icon）
            └── 86lux-logo.png

规则：

  • 一个主题/页面对应一个 _assets/<主题名>/ 子目录
  • 多页共享的资产放 _assets/_common/
  • ECS 上 Hermes 写 drafts 时，资产放 drafts/<agent>/_assets/<topic>/，promote 时一起搬

2.2 在 markdown 里怎么引用 ​

始终用相对路径：

markdown
<!-- canon/品类/蒸汽挂烫机.md 里 -->
![BSR 趋势](../_assets/蒸汽挂烫机/bsr-trend.png)

<!-- 视频 -->
<video src="../_assets/蒸汽挂烫机/unboxing.mp4" controls width="600"></video>

不要用：

  • ❌ 绝对路径 /Users/xxx/... —— 别人 clone 后路径不对
  • ❌ wiki.86lux.net/... URL —— 站点搬域名后全断
  • ❌ Obsidian 默认的 !<span class="wikilink-dead" title="未找到: image.png" style="color:#c33;border-bottom:1px dashed #c33">image.png</span> 嵌入（除非你知道 VitePress 渲染兼容性，目前不建议）
  • ❌ 图床外链（imgur、微信图床）—— 几个月后会被删，wiki 烂尾

2.3 Obsidian 默认附件路径设置（推荐） ​

Obsidian → Settings → Files & Links：

  • Default location for new attachments：选 In subfolder under current folder → 填 _assets
  • New link format：选 Relative path to file
  • Use Wikilinks：开（虽然图片走 ![]() 不走 [[]]）

这样你截图直接 ⌘V 粘贴进 Obsidian 时，会自动存到 <当前页所在目录>/_assets/，并生成相对路径引用。

3. Git LFS 自动跟踪哪些后缀 ​

仓库根的 .gitattributes 已配，下列后缀全部自动走 LFS，你什么都不用做：

类别后缀
图片.png .jpg .jpeg .gif .webp .bmp .tiff .heic（大小写都跟踪）
视频.mp4 .mov .webm .mkv .avi .m4v
音频.mp3 .wav .m4a .flac .ogg
大档案.pdf .zip .tar .tar.gz .tgz .7z .rar
Office.docx .xlsx .pptx
设计稿.psd .ai .sketch .fig .xd

不走 LFS 的（保持普通文本 diff）：

  • .svg —— 通常很小且是文本，diff 友好
  • .md .txt .json .yaml .csv —— 显然
  • .html .css .js —— 显然

要新增类型，编辑 .gitattributes 加一行 *.xxx filter=lfs diff=lfs merge=lfs -text。

4. 大小指南 ​

资产类型推荐上限超了怎么办
截图1 MB用 Squoosh / TinyPNG 压一下再传
高清照片5 MB压到 1920px 长边 + 80% jpg 质量
视频50 MB压到 1080p H.264 < 5 Mbps，或外链 B 站
PDF20 MB压缩 PDF，或拆成多份
设计源文件（PSD/AI）200 MB仅必要时上传，更建议存 Figma/网盘+留链接
任何单文件硬上限 100 MBGitHub LFS 单文件 hard limit

超过 100 MB 的文件 Git LFS 会拒收。超大视频 / 设计稿不要硬塞，传到对象存储或视频平台，wiki 里留链接 + 截图缩略图。

5. LFS 配额与成本 ​

GitHub LFS 的 付费基础版（已开通，$5/月）：

  • 50 GB 存储
  • 50 GB / 月下载流量

按当前规模这个量级管够，不用担心。

如果某天接近上限：

6. 实战范例 ​

范例 1：粘一张截图进笔记 ​

  1. 在 Obsidian 里打开 public/品类/蒸汽挂烫机.md
  2. 截图后 ⌘V 粘贴
  3. Obsidian 自动存到 public/品类/_assets/蒸汽挂烫机-2026-04-17.png，并写入 ![](_assets/蒸汽挂烫机-2026-04-17.png)
  4. 保存
  5. Claude Code → "发布 wiki"
  6. vault-publish 自动跑 git add public/，PNG 走 LFS 上传，commit + push

push 时你会看到：

Uploading LFS objects: 100% (1/1), 245 KB | 110 KB/s, done.

这就是 LFS 在干活。

范例 2：传一份视频 ​

bash
# 假设你有一个 35 MB 的开箱视频
cp ~/Desktop/unboxing.mp4 wiki-vault/canon/_assets/蒸汽挂烫机/unboxing.mp4

在页面里：

html
<video src="../_assets/蒸汽挂烫机/unboxing.mp4" controls width="600"></video>

发布。VitePress 渲染时会变成可播放的 <video> 元素。

范例 3：超大视频不能塞 ​

500 MB 的产品宣传 4K 视频？别塞。

  • 上传到 B 站 / 阿里云 OSS / 飞书云空间
  • wiki 里嵌入 iframe 或留链接
  • 同时存一张视频封面图 + 30 秒压缩版预览（< 50MB）作为 LFS

7. 故障排查 ​

7.1 我 push 时报 LFS 相关错误 ​

batch response: This repository is over its data quota.

→ 流量/存储超了，让 Allen 加 data pack。

ERROR: file is X MB, but LFS file size limit is 100 MB.

→ 单文件超 100MB，按 §4 处理（外链/拆分/压缩）。

7.2 我 clone 后图片打不开 ​

bash
git lfs install   # 装 hook
git lfs pull      # 拉所有 LFS 实际文件

如果你只 clone 了仓库但 LFS 没装，工作区里图片会是 120 字节的 pointer 文本，浏览器/Obsidian 打不开。

7.3 我想确认某个文件确实走了 LFS ​

bash
cd wiki-vault
git lfs ls-files | grep <filename>

能看到说明 LFS 跟踪了。

bash
git show HEAD:path/to/image.png | head -3

如果输出是 version https://git-lfs.github.com/spec/v1 三行 pointer，说明 git 仓库里只存了 pointer（正确）。如果输出是 PNG 二进制乱码，说明这文件没走 LFS（错误，可能 .gitattributes 加得晚）。

7.4 历史文件没走 LFS 现在想迁 ​

bash
git lfs migrate import --include="*.png,*.jpg" --everything
git push --force origin main   # 改写了历史，需要 force push

⚠️ 改写历史是破坏性操作，所有人需要重新 clone。找 Allen 协调时间窗口操作。

8. 不要做的事 ​

  • ❌ 用 git add -A 或 git add .（会把 personal/ 也加进去）
  • ❌ 把 100 MB+ 的源 PSD / AI 设计稿硬塞 LFS（外链）
  • ❌ 把同一张图复制 5 份分别放 5 个目录（用相对路径或 _common/ 共享）
  • ❌ 在 markdown 里写 base64 嵌入图（<img src="data:image/png;base64,...">），单页变 MB 级、wikilink 插件还可能不认
  • ❌ 删掉某张图前不搜全 wiki 是否还有引用
  • ❌ 改图片名不更新引用（用 IDE 全局替换或先 rg "old-name"）

关联 ​

TeamOS · docs as code · canon=权威知识，drafts=候选区

© 86lux.net