与个人知识库集成路径

基于 个人知识库系统 现有架构：2C4G VPS · Gitea · MkDocs · Nginx · Memos
目标：只读预览 · 完全本地 · 可渐进落地

---

1. 推荐路线（三阶段）

阶段	内容	预估工时	新增资源
P0	kkFileView Docker + 子域 + Gitea raw 预览	2～4h	~512MB–1GB RAM
P1	MkDocs PDF 内嵌 + 笔记内预览链接模板	1～2h	无
P2	AList 附件库 + iframe 接 kkFileView	3～5h	~128MB RAM

不建议现阶段同机部署 OnlyOffice/Collabora（与 Memos、Gitea、MkDocs 构建争内存）。

---

2. P0：kkFileView 部署草案

2.1 目录规划（VPS）

/opt/kkfileview/
├── docker-compose.yml
└── data/              # 可选：转换缓存挂载

2.2 docker-compose.yml（示例）

services:
  kkfileview:
    image: keking/kkfileview:4.4.0
    container_name: kkfileview
    restart: unless-stopped
    ports:
      - "127.0.0.1:8012:8012"
    environment:
      - KKFILEVIEW_BASE_URL=https://preview.teacherhome.top
    volumes:
      - ./data:/opt/kkfileview/file

镜像 tag 以 Docker Hub keking/kkfileview 最新为准；国内拉取可沿用 DaoCloud 镜像前缀 + docker tag（与个人知识库 001-docker镜像拉取超时 预案一致）。

2.3 Nginx 反代（示例）

server {
    listen 443 ssl http2;
    server_name preview.teacherhome.top;

    # ssl_certificate ...（Let's Encrypt，同现有 Certbot 流程）

    location / {
        proxy_pass http://127.0.0.1:8012;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_read_timeout 300s;
        client_max_body_size 100m;
    }
}

2.4 预览 URL 生成规则

Gitea 私有仓 raw 文件（需可访问；私有仓要 token 或内网）：

文件地址:
https://git.teacherhome.top/{owner}/{repo}/raw/branch/{path/to/file.docx}

预览地址:
https://preview.teacherhome.top/onlinePreview?url={Base64(文件地址)}

JavaScript 示例（MkDocs 自定义脚本或书签工具）：

function previewUrl(fileUrl) {
  const encoded = btoa(unescape(encodeURIComponent(fileUrl)));
  return 'https://preview.teacherhome.top/onlinePreview?url=' + encodeURIComponent(encoded);
}

Python 示例（构建脚本 / CLI）：

import base64, urllib.parse

def preview_url(file_url: str, base="https://preview.teacherhome.top") -> str:
    b64 = base64.b64encode(file_url.encode()).decode()
    return f"{base}/onlinePreview?url={urllib.parse.quote(b64)}"

2.5 私有仓鉴权（重要）

kkFileView 需要 HTTP 拉取到文件字节。私有 Gitea 可选：

方式	做法
A. 部署 token	raw URL 带 ?token=（临时、仅预览服务可达）
B. 静态附件目录	Nginx alias 只读目录，不对公网开放 listing
C. 内网预览	preview 子域仅 Tailscale / IP 白名单
D. 公开仓附件	附件放公开 repo 的 assets/（敏感文件不适用）

个人场景推荐 B 或 C：附件同步到 VPS /data/knowledge-attachments/，Nginx 仅允许 kkFileView 源 IP 或签名访问。

---

3. P1：MkDocs 集成

3.1 PDF 站内嵌入

mkdocs.yml：

markdown_extensions:
  - attr_list
plugins:
  - search
  - mkdocs-pdf

笔记中：

![调研报告](../assets/report.pdf){ type=application/pdf style="min-height:60vh;width:100%" }

3.2 Office / 其他格式：跳转预览

在笔记中统一用链接模板（可做成 Snippet）：

📎 [下载原文件](https://git.../raw/.../方案.docx) · [在线预览](https://preview.teacherhome.top/onlinePreview?url=...)

或在 docs/overrides/main.html 增加「预览」按钮（后续迭代）。

3.3 附件目录约定（建议）

knowledge-base/
├── 03-素材库/
│   ├── attachments/          # 大文件、Office、PDF
│   │   ├── 2026-05/
│   │   └── ...
│   └── ...

• Git：小 PDF/图片直接进仓；>10MB 考虑 Git LFS 或不同步到仓、仅 VPS 侧
• MkDocs：nav 不必暴露 attachments 全文，仅在引用处链接

---

4. P2：AList 附件库（可选）

4.1 角色

• 提供 文件夹浏览、搜索、WebDAV
• Office / CAD / 压缩包预览走 kkFileView iframe

4.2 iframe 配置（管理后台 → 预览）

参考 AList Discussion #3908：

{
  "doc,docx,xls,xlsx,ppt,pptx,pdf,zip,rar,7z": {
    "kkFileView": "https://preview.teacherhome.top/onlinePreview?url=$b_url"
  }
}

4.3 与个人知识库关系

入口	用途
notes.*	成体系文档阅读（MkDocs）
git.*	版本管理、raw 链接
files.*（AList 示例子域）	附件浏览与预览
preview.*	kkFileView 预览引擎（也可仅被 iframe 调用）

---

5. 验收清单

P0 完成标准

• [ ] https://preview.* 可打开 kkFileView 首页
• [ ] 公网可访问的一个 .pdf / .docx 测试文件能预览
• [ ] 中文文件名正常
• [ ] 转换失败时有明确错误页（非 502）
• [ ] 内存占用在 2C4G 机器上可接受（空闲 <1.5GB 总占用）

P1 完成标准

• [ ] MkDocs 站点内至少 1 篇笔记嵌入 PDF 成功
• [ ] 至少 1 个 Office 附件通过预览链接打开

P2 完成标准（若做）

• [ ] AList 挂载目录可浏览
• [ ] 点击 docx/xlsx 走 kkFileView 而非微软在线

---

6. 与现有服务端口规划（示例）

服务	端口	公网
Memos	5230	memos.*
Gitea	3000	git.*
MkDocs	静态	notes.*
kkFileView	8012	preview.*
AList	5244	files.*（可选）

---

7. 备选：纯前端轻量方案（不部署 kkFileView）

若 仅 docx/xlsx/pdf/pptx 且文件体积小：

1. 在 VPS 或 CDN 托管一个静态页（Vue + vue-office）
2. URL 参数传入 Gitea raw 地址
3. 浏览器端解析，无 LibreOffice

缺点：无 zip/cad/旧格式；大 Excel 卡顿；私有文件需处理 CORS 与鉴权。

仅适合「快速验证」，长期仍建议 kkFileView。

---

8. 决策记录（便于复盘）

决策	选项	结论	理由
预览引擎	kkFileView vs OnlyOffice	kkFileView	只读预览、格式全、2C4G 可承受
Office 在线	微软 vs 自建	自建 kkFileView	完全本地、无文件大小/域名限制
附件入口	仅 Git vs AList	先 Git 链接，后 AList	渐进式，降低运维面
MkDocs PDF	内嵌 vs 外链	内嵌	阅读体验好，插件成熟

---

9. 相关文档

• 方案总览与选型
• 项目清单
• 个人知识库技术实现