类别	路径	说明
部署代码	`Dockerfile` `docker-compose.yml` `.dockerignore`	node:22-slim 镜像 + 双服务编排，改文档无需重建镜像
站点配置	`docusaurus.config.ts` `sidebars.ts` `tsconfig.json` `package.json` `package-lock.json`	中文站、md 解析策略、mermaid、自动侧边栏
自研工具·导入引擎	`tools/import/lib.mjs` `tools/import/import.mjs`	md→mdx 转换 + 关键词自动分类 + 链接/附件重写，零第三方依赖
自研工具·编辑平台	`tools/editor/server.mjs` `tools/editor/ui.mjs`	单文件 HTTP 服务 + 内嵌 SPA，仅用 `marked` 一个依赖
主题定制	`src/` `static/`	首页、分类角标样式、favicon 等
内容	`docs/`（含各类 `assets/`） `blog/`	已导入并转换完成的 mdx 成品，本身即归档对象
杂项	`README.md` `.gitignore` `scripts/`	文档 + 推送脚本

❌ 不提交（已列入 .gitignore）

node_modules/ build/（构建产物）.docusaurus/ .run/ *.log .swc-cache/ .npm-cache/ .docker-config/（缓存、日志、容器辅助目录）

⏳ 待定：原始 md 文档库（非代码，Gitea 对接后另行建仓归档）

这些是导入引擎的输入源，目前不是 git 仓库，等 Gitea 对接方式确定后建议各自建独立仓库（保留原始 md，与本仓库的转换产物分开演进）：

源目录	内容	对应站内分类
`/home/ai/dsh-workspace/ragflow`	RAGFlow 知识库设计、标底/彩页/参数表、vm 运维手册	网络、AI 部分
`/home/ai/dsh-workspace/vm迁移`	虚拟机迁移方案	网络
`/home/ai/dsh-workspace/llm-creat`	本地大模型部署（含子项目 qwen38-flash-next-2x3090 的 docs/notes/packaging）	AI
`/home/ai/dsh-workspace/ai-work`	脚本与图片为主，少量 md	—

⚠️ 注意：文档内容含内网 IP、拓扑、招投标参数等敏感信息，Gitea 仓库请建为私有，并关闭开放注册。

部署与运行（Docker Compose）

cd site
docker compose up -d           # 启动两个服务（首次带 --build 构建镜像）
docker compose down            # 停止
docker compose logs -f site    # 日志；docker compose restart <site|editor> 重启单个服务
docker compose ps              # 状态（两个服务都有健康检查）

容器	端口	内容
`kb-site`	3000	Docusaurus 开发服务器（热更新）
`kb-editor`	3200	编辑/导入平台

机制要点：

代码/文档热挂载：./ 整目录挂到容器 /app，宿主改文件容器即时生效；容器内以 uid=1000 运行，写回宿主的文件属主仍是当前用户，git 照常可用。
命名卷：kb_node_modules（来自镜像 npm ci，遮蔽宿主目录）、kb_docusaurus_cache（dev 编译缓存）。只有改 package.json 依赖时才需 docker compose down -v && docker compose up -d --build。
文档源只读挂载：宿主 /home/ai/dsh-workspace → 容器 /data，「服务器路径导入」填 /data/... 路径。
机器上跑着 ragflow 等其它容器，3000/3200 已确认无冲突。

日常使用

编辑：打开 :3200 → 左树选文档 → 改 → Ctrl+S → 刷新 :3000（实测保存后 ~0.5s 完成重编译）。支持新建、删除、实时预览。

导入 md：平台「导入文档」→ 服务器路径（/data/xxx，目录递归）或浏览器上传；分类选「自动」或手动。命令行等价：

docker compose run --rm site node tools/import/import.mjs /data/文档目录 --dry-run  # 预演
docker compose run --rm site node tools/import/import.mjs /data/文档目录             # 导入
docker compose run --rm site node tools/import/import.mjs /data/x.md --category network

分类规则：关键词打分。网络=交换/路由/组网/拓扑/VLAN/BGP/招投标参数等；AI=大模型/RAG/GPU/vLLM/Agent/MCP 等；其余→其他。分错了直接挪文件：docs/network|ai|misc（显示名由各目录 _category_.json 控制）。

导入引擎做了什么（md → mdx）

MDX 安全化：正文 {→{'{'}、非白名单 <tag>→<、尖括号自动链接→显式链接、class=→className=、for=→htmlFor=；代码块/行内代码原样保护
front matter 自动补齐：标题取首个 H1（并入 title 防重复渲染）、slug 用原文件名、sidebar_position 递增
引用重写：指向被导入文档的相对链接→站内 URL；本地图片/csv/json/脚本→拷入 docs/<分类>/assets/<slug>/ 并可下载；指向未导入 .md 的引用→降级为行内代码（防死链）
站点侧兜底：全局 markdown.format:'md'（HTML 表格/注释/<br> 兼容）；单页要写 JSX 时 front matter 加 format: mdx

编辑平台 API（tools/editor/server.mjs，零框架）

方法	路径	用途
GET	`/`	SPA 界面
GET	`/api/tree`	docs/+blog 文件树（含各篇 title）
GET/POST	`/api/file`	读/存文档（限 docs、blog，仅 md/mdx，防穿越）
POST	`/api/delete`	删除文档
POST	`/api/preview`	markdown → HTML 预览
POST	`/api/import-paths`	按服务器路径导入（支持 dryRun）
POST	`/api/import-upload`	浏览器上传导入

环境变量：EDITOR_PORT（默认 3200）、EDITOR_HOST（默认 0.0.0.0）。

Git 约定与 Gitea 对接（待接入）

当前：本地仓库（本目录为根），分支 main，历史即文档变更史（showLastUpdateTime 依赖它，页面会显示最后更新时间）。
提交身份目前是占位的 docs-bot <docs@local>，推 Gitea 前建议换成你的账号： git config user.name "…" && git config user.email "…"

接入脚本已备好（等你给出地址/令牌后用）：

./scripts/push-to-gitea.sh http://<gitea>:3000/<org>/kb-site.git

日常内容维护节奏建议：编辑器改完 → git add -A && git commit → push（可加 cron/CI 自动推送）。

生产导出（可选）

docker compose run --rm site npx docusaurus build   # 产物 site/build/，纯静态

nginx 直接 root .../site/build，location / { try_files $uri $uri/index.html =404; }。

环境备忘（重装/迁移必看）

docusaurus.config.ts 中 future.v4 保持关闭：该 flag 启用 @swc/html 原生压缩，本机 / 属主为 nobody，SWC 缓存根校验必败（ERR_SWC_NATIVE_CACHE）。容器内属主正常，但为可复现暂不打开。
宿主机 npm 若要用：export npm_config_cache=<工作区>/.npm-cache（/home/ai/.npm 不可写）；容器内无此问题。
宿主 docker CLI 需 export DOCKER_CONFIG=<工作区>/.docker-config（/home/ai/.docker 不可写）。
破链监控：构建/运行期 onBrokenLinks/onBrokenMarkdownImages 均为 warn，导入新文档后瞄一眼 docker compose logs site。

README.md Unescape Escape

知识库 / 博客站（kb-site）

Gitea 归档清单（什么该提交、什么不该）

✅ 提交：本仓库 kb-site（= 本目录整体）