知识库阅读

来源：halo-kb/知识库架构设计.md → ## A) 分类（Categories）体系（原文 6838 字符）

A) 分类（Categories）体系

A.1 设计原则

原则	说明
一层一个"工作线"	一级分类不是技术名词，而是你花时间的地方。看到分类名就能想起"我最近在这上面干了什么"
一篇文章一个主分类	Halo 允许一篇文章属于多个分类，但本方案约定只选 1 个主分类；确有交叉时用标签表达，不新增第二个分类
深度不超过 3 级	分类是导航，不是知识图谱。超过 3 级说明该用标签或搜索
稳定性优先	分类半年不动一次。一个新分类的诞生应是"开了一条新产品线"，不是"学了个新框架"
分类不承载"状态"	不建「进行中」「已完成」「待整理」这类分类——那是工作流，不是知识分类；工作流用文章元数据或草稿状态表达

A.2 一级分类（8 个）

name 为 Halo 的 metadata.name（DNS 风格小写标签），slug 为前台路由别名（默认路由 /categories/{slug}），priority 用于排序（数字越小越靠前）。

name	displayName	slug	parent	priority	一句话用途
`cat-tunnel`	内网穿透与隧道	`tunnel`	—	10	自研隧道工具的架构、部署、协议与排错（`intranet-tunnel` 主线）
`cat-cloud-ops`	云服务器与运维	`cloud-ops`	—	20	阿里云 ECS、宝塔、nginx、DNS、证书、发布与回滚
`cat-selfhost`	自托管与 NAS	`selfhost`	—	30	飞牛 OS/NAS、Docker 自托管服务栈、Halo 站点本身的建设
`cat-backend`	后端与自研服务	`backend`	—	40	Go 服务端实现、API 设计与契约、并发与数据一致性
`cat-frontend`	前端与客户端	`frontend`	—	50	Vue/Web 管理端、Wails 桌面端、移动端 App
`cat-data`	数据与存储	`data-storage`	—	60	PostgreSQL/SQLite 实践、备份恢复、迁移与数据修复
`cat-ai`	AI 与效率工具	`ai-tools`	—	70	大模型接入（DeepSeek）、AI 插件、编码代理与自动化
`cat-review`	项目实录与复盘	`project-review`	—	80	按项目而非按技术切分的里程碑、版本发布、事故复盘

为什么单列 cat-review：技术分类回答"这是什么技术"，但用户真正想回看的是"那个项目当时怎么做的"。项目复盘与技术笔记必须能分开检索，否则复盘会被技术细节淹没。

A.3 二级分类（20 个）

v2 校正：v1 标题曾写「18 个」，而本节清单逐条数下来是 20 条（3+3+3+9+2）——清单才是权威。落地时以清单为准建了 20 个，实测与实例一致。

落地状态（2026-09-13 实测）：20 个二级分类已全部创建，层级（spec.parent）与 priority 全部核对通过。

空分类的处理（v2 新增规则）：v1 曾建议「第一批只建 8 个一级分类，二级在某一级下积累 ≥ 5 篇文章时再建，否则会造成大量空分类，前台分类列表反而更难用」。落地时按清单全量建了 20 个二级，于是这个担心真的发生了——实测 Ethereal 的分类组件把一级与二级平铺在同一列表里（首页一度列出全部 29 个分类，其中 28 个是空的，访客点进去全是空页）。

处置：20 个二级分类全部设为 hideFromList = true，前台分类列表只保留 8 个一级分类 + 既有的「默认分类」（实测首页分类入口从 29 个降到 9 个）。

增量规则（取代 v1 的「按需创建」建议）：二级分类不需要再建；某个二级分类积累到第 1 篇文章时，把它改回可见即可：
python H:\Works\halo-kb\scripts\adjust_taxonomy.py --apply --task unhide --slugs <slug>

内网穿透与隧道（parent: `cat-tunnel`）

name	displayName	slug	priority	用途
`cat-tunnel-arch`	隧道架构与协议	`tunnel-architecture`	10	控制面/数据面划分、连接复用、统计口径、边缘配置渲染
`cat-tunnel-deploy`	隧道部署	`tunnel-deploy`	20	云服务器端、NAS 端、客户端 Docker 化、域名与证书接入
`cat-tunnel-debug`	隧道排错	`tunnel-debug`	30	域名不生效、流量统计为 0、客户端连不上等具体故障

云服务器与运维（parent: `cat-cloud-ops`）

name	displayName	slug	priority	用途
`cat-cloud-aliyun`	阿里云 ECS	`cloud-aliyun`	10	实例、Workbench CLI、安全组、云 API 调用
`cat-cloud-baota`	宝塔与 nginx	`cloud-baota`	20	站点配置、反代、443 接管、reload 机制
`cat-cloud-dns-cert`	域名 · DNS · 证书	`cloud-dns-cert`	30	泛解析、ACME 签发与续期、DNS-01、证书覆盖范围

自托管与 NAS（parent: `cat-selfhost`）

name	displayName	slug	priority	用途
`cat-nas-fnos`	飞牛 OS 与 NAS	`nas-fnos`	10	NAS 系统层、存储卷、文件权限、FNOS 特有行为
`cat-docker`	Docker 与编排	`docker-orchestration`	20	compose、镜像归档、卷与 bind mount、容器排错
`cat-halo`	Halo 站点	`halo-site`	30	Halo 部署、主题、插件、内容与信息架构

后端 / 前端 / 数据 / AI（parent 见左）

name	displayName	slug	parent	priority	用途
`cat-go`	Go 服务端	`go-service`	`cat-backend`	10	Go 工程实践、并发、错误处理、构建与交叉编译
`cat-api`	API 与契约	`api-contract`	`cat-backend`	20	接口设计、移动端兼容层、字段契约与核对脚本
`cat-vue`	Vue 与 Web 前端	`vue-web`	`cat-frontend`	10	Vue 3 组件、构建、浏览器端排错
`cat-client-app`	桌面与移动客户端	`desktop-mobile-client`	`cat-frontend`	20	Wails 桌面端、移动端 App、跨端接口适配
`cat-postgres`	PostgreSQL	`postgres`	`cat-data`	10	事务与锁、死锁、时区、`timestamptz`
`cat-sqlite`	SQLite	`sqlite`	`cat-data`	20	锁与并发、DSN 参数、嵌入式场景
`cat-backup`	备份与恢复	`backup-restore`	`cat-data`	30	数据库备份、镜像归档、灾难恢复演练
`cat-llm`	大模型接入	`llm-integration`	`cat-ai`	10	DeepSeek/供应商配置、提示词、RAG、流式输出
`cat-agent`	编码代理与自动化	`coding-agent`	`cat-ai`	20	AI 编码代理协作、自动化脚本、批量操作

项目实录与复盘（parent: `cat-review`）

name	displayName	slug	priority	用途
`cat-review-tunnel`	项目：intranet-tunnel	`review-intranet-tunnel`	10	该项目的版本里程碑、发布记录、关键缺陷复盘
`cat-review-halo`	项目：Halo 站点	`review-halo-site`	20	站点建设过程、主题/插件变更、内容体系演进

A.4 分类字段填写规范（Halo 实际支持的字段）

依据官方文档文章的「新建文章分类」设置说明，Halo 分类支持以下字段，本方案的填写约定如下：

Halo 字段	是否填	约定
名称（`displayName`）	必填	用上表中文名，不带编号、不带 emoji
别名（`slug`）	必填	用上表英文短横线形式；一旦发布不再修改（改了旧链接会 404）
上级分类	按表	二级分类必须挂到对应一级下
描述	建议	写"这个分类收什么、不收什么"，一句话
封面图	不填	由主题列表页统一风格，避免每类封面不一致
自定义模板 / 自定义文章模板	不填	Ethereal 的 `category.html` / `post.html` 已满足；除非后续要做专题页
在列表中隐藏（`hideFromList`）	按内容决定	v2 校正：v1 写「不填」。实测语义是——为 `true` 时该分类从前台分类列表里移除，但分类页 URL 仍可正常访问（实测 `/categories/sqlite` 返回 HTTP 200、标题正常），文章归属也不受影响。现行约定：新建的空分类一律先设 `true`，积累首篇文章后改回 `false`。
阻止文章级联查询	不填	本文档体系不使用父分类级联语义
元数据	不填	当前主题未使用分类元数据

A.5 分类 vs 标签的边界（可直接照做的判定流程）

拿到一个新词，问三个问题：
  1. 它会不会随技术演进不断新增？   会 → 标签
  2. 它是不是我工作版图里稳定的板块？ 是 → 分类
  3. 同一篇文章可能同时属于多个这样的词吗？ 是 → 标签（分类约定唯一）

反例与判定（v2 按实测校正）：

先分清两件事——slug 相同与显示名相同，后果完全不同：

情形	实测结论（2026-09-13）	是否禁止
分类与标签的 slug 字符串相同	Halo 允许：两者是独立模型，路由分别是 `/categories/{slug}` 与 `/tags/{slug}`。实测 `/categories/tunnel` 与 `/tags/tunnel` 各自渲染正确，标题分别是「分类：内网穿透与隧道」与「标签：内网穿透」，互不干扰	不禁。本实例有意保留了 `tunnel` / `sqlite` / `backup-restore` 三组同 slug
分类与标签的 `displayName` 完全相同	前台侧边栏的「文章分类」与「文章标签」两个组件会显示一模一样的文字，读者与作者都无法判断该去哪个入口	禁止

反例（明确禁止）：

❌ 分类与标签使用完全相同的显示名。落地后实测发现 3 组踩线——分类 cat-postgres/cat-sqlite/cat-backup 的显示名与标签 postgresql/sqlite/backup-restore 一字不差。

→ 已就地消歧：分类改为「PostgreSQL 实践」「SQLite 实践」「数据备份与恢复」，标签名保持不变。只动 displayName，不动 slug，因此 URL 与既有链接完全不受影响。

❌ 为同一个概念既建分类又建标签——这是更根本的重复：一个词若已是稳定的工作板块，就不该再作为技术实体标签出现。

→ 正确：Go 是语言，主体身份放在标签 go；分类用「Go 服务端」表达"我在 Go 服务端这条工作线上做的事"。 → 正确：Docker 是技术实体，只做标签 docker；它的上级领域是「自托管与 NAS」或「云服务器与运维」。

❌ 建「排错」分类。

→ 正确：排错是动作，只做标签 troubleshooting；具体故障归入它所属的技术领域分类。

⚠️ 本实例的遗留取舍（待用户裁决，本次未删任何一条）：按上述第一条判据，B.3 清单里仍有 16 组词与 A 节分类语义重合（go ↔「Go 服务端」、docker ↔「Docker 与编排」、docker-compose/nginx ↔「宝塔与 nginx」、sqlite ↔「SQLite 实践」、postgresql ↔「PostgreSQL 实践」、backup-restore ↔「数据备份与恢复」、api ↔「API 与契约」等）。它们的显示名已不重复，不构成前台歧义，故本次全部保留；是否要把与分类重合的标签并入分类（这需要删除标签），见文末「落地后修正记录 · 待决项」。

分工总表：

维度	分类	标签
回答的问题	属于哪条工作线	涉及什么技术/动作
结构	树形，≤3 级	扁平，无层级
数量	一级 8 个，二级 20 个（均已建）	首批 45 个（已建），可增长（上限见 B.4）
变更频率	半年一次	随时
每篇用量	恰好 1 个	2~5 个
是否出现在 URL	是（`/categories/{slug}`）	是（`/tags/{slug}`）
前台入口	分类导航栏 / 分类侧边栏组件	标签云侧边栏组件 / 标签页

来源：halo-kb/知识库架构设计.md → ## B) 标签（Tags）体系（原文 4894 字符）

B) 标签（Tags）体系

B.1 命名规范

规则	约定	理由
大小写	一律小写	Halo 标签按 slug 生成 URL，大小写混用会出现 `Go` 与 `go` 两个标签
单复数	一律单数（`plugin` 而非 `plugins`）	避免 `plugin`/`plugins` 分裂；专有名词按官方写法（如 `wails`）
分隔符	多词用短横线 `-`（`docker-compose`）	与 URL 兼容；不用空格、下划线、驼峰
显示名	`displayName` 保留官方大小写（如 `PostgreSQL`、`Docker Compose`、`Wails`）	前台可读性靠显示名，不靠 slug
版本号	不进标签	版本写进文章元信息块或标题（`v1.2.1`），否则会不断分裂
与分类关系	标签不与分类共用同一个 `displayName`（slug 相同不构成冲突，见 A.5 实测表）	避免前台两个组件出现同名入口
语言	中文标签仅用于无法用英文准确表达的场景	英文标签更通用、更稳定

B.2 粒度控制（三层，比例受限）

层级	例子	占比建议
实体层（技术/平台/工具）	`go`、`postgresql`、`docker`、`nginx`	≈ 70%
动作层（做的事）	`troubleshooting`、`backup-restore`、`performance`	≈ 20%
场景层（特殊情况）	`postmortem`、`migration`、`security`	≈ 10%

禁止：状态词（进行中、待整理、TODO）、情绪词、人名、公司名、时间词（2026）。

B.3 首批标签清单（45 个）

v2 校正：v1 标题曾写「38 个」，而本节清单逐条数下来是 45 条（6+5+7+9+5+4+6+3）——规则被自己的清单突破。落地时以清单为准建了 45 条（其中 halo 复用实例既有的「Halo」标签，未新建），实测实例标签总数正好 45，与清单一致。标题已改为 45。

name 与 slug 一致（Halo 标签同样使用 DNS 风格标识），displayName 为前台显示名。

① 语言与运行时（6）

name / slug	displayName	适用场景
`go`	Go	Go 语言特性、工程实践、交叉编译
`nodejs`	Node.js	脚本、构建工具链、npm/pnpm
`typescript`	TypeScript	类型系统、tsconfig、Vue 项目的类型问题
`java`	Java	Halo 本体、Java 插件、JVM 相关
`shell`	Shell	bash/sh 脚本、远程运维命令
`powershell`	PowerShell	Windows 侧脚本与转义坑

② 前端与客户端（5）

name / slug	displayName	适用场景
`vue`	Vue	Vue 3 组件、SFC、构建
`vite`	Vite	构建配置、HMR、打包产物
`wails`	Wails	桌面端打包、embed 占位、绑定生成
`astro`	Astro	主题源码（Ethereal 基于 Astro 构建）
`tailwindcss`	Tailwind CSS	样式类、主题样式定制

③ 后端与数据（7）

name / slug	displayName	适用场景
`api`	API	接口设计、REST 约定、版本化
`postgresql`	PostgreSQL	事务、锁、死锁、时区
`sqlite`	SQLite	嵌入式数据库、并发限制
`gorm`	GORM	Go ORM 用法与坑
`mysql`	MySQL	出现 MySQL 场景时使用（当前主库为 PG）
`redis`	Redis	缓存、分布式锁（出现即用）
`migration`	数据迁移	表结构/数据搬迁、字段对齐

④ 部署与运维（9）

name / slug	displayName	适用场景
`docker`	Docker	镜像、容器、网络
`docker-compose`	Docker Compose	编排、env_file、卷挂载、服务启停
`nginx`	Nginx	反代、TLS 终止、配置校验与 reload
`baota`	宝塔面板	面板接管站点、配置被模板覆盖的坑
`acme`	ACME / acme.sh	证书签发与自动续期
`systemd`	systemd	服务单元、path unit 监听触发
`gitea`	Gitea	私有仓库、Release、附件上传
`release`	版本发布	打包、镜像归档、发布流程
`ci`	CI/CD	流水线、自动化构建

⑤ 网络与域名（5）

name / slug	displayName	适用场景
`dns`	DNS	解析记录、泛解析、API 调用
`tls`	TLS / HTTPS	证书链、SAN、握手失败
`reverse-proxy`	反向代理	转发规则、SNI、真实 IP
`tunnel`	内网穿透	隧道建立、端口复用、连接保活
`aliyun`	阿里云	ECS、云 API、安全组

⑥ 自托管与 NAS（4）

name / slug	displayName	适用场景
`nas`	NAS	存储卷、共享目录、权限
`fnos`	飞牛 OS	FNOS 特有行为（如 `sed -i` 改权限）
`self-hosted`	自托管	自建服务的取舍与对比
`halo`	Halo	Halo 本体、主题、插件、内容体系

⑦ 工程方法与排错（6）

name / slug	displayName	适用场景
`troubleshooting`	排错记录	一切"现象 → 根因 → 修复 → 判据"型文章
`postmortem`	事故复盘	线上故障的时间线与改进项
`performance`	性能优化	耗时分析、缓存、构建提速
`security`	安全	鉴权、令牌、暴露面、最小权限
`backup-restore`	备份与恢复	备份策略、恢复演练、数据找回
`testing`	测试与验证	断言设计、"先验证再发布"的实践

⑧ AI（3）

name / slug	displayName	适用场景
`ai`	AI	AI 能力接入与应用的通用入口
`deepseek`	DeepSeek	供应商配置、模型选择、连通性
`prompt`	提示词	提示词工程、上下文组织

刻意不设的标签：halo-theme-ethereal（已在正文与分类中体现）、intranet-tunnel（项目名 → 归 cat-review-tunnel 分类）、2026（时间不进标签）。

B.4 防止「标签爆炸」的治理规则

入库前置检查：新建标签前先在标签列表按 slug 搜一遍。Halo 不会阻止你建语义重复的标签（docker-compose 与 compose 会同时存在）。
同义词映射表（放在本文件，提交前对照）：

想到的词	一律改用
`compose` / `dockercompose`	`docker-compose`
`pg` / `postgres`	`postgresql`
`node` / `node.js`	`nodejs`
`https` / `cert` / `certificate`	`tls`
`nginx-reverse-proxy` / `反代`	`reverse-proxy`
`debug` / `fix` / `bug`	`troubleshooting`
`内网穿透` / `frp` / `natapp`	`tunnel`

阈值收敛：单个标签下文章数 < 3 篇且连续 3 个月无新增 → 合并进上位标签（如 gorm 并入 go）。
单篇上限：一篇文章 2~5 个标签。超过 5 个时先自问是不是该拆文——标签堆砌通常意味着文章混装了两三个主题。
全站上限：站点文章数 < 50 时，标签总数控制在 ≤ 50，其中已建的 45 条是审定基线，不占用增量额度。

v2 校正的理由：v1 写的上限是「≤ 40」，而本节清单本身就有 45 条，规则被自己的清单突破（这是本次处理的 4 处文档自相矛盾之一）。落地时以清单为准建了 45 条，与实例实测一致。上限因此调整为 50：既给增量留出 5 个空位，也不必为了迁就一个整数，去删掉已审定、语义各不相同的标签。
达到上限时：新增一个必须先合并一个——优先合并「零文章且连续 3 个月无新增」的近义项（见第 3 条），而不是动高频标签。
候选精简清单（待用户裁决，本次一条未删）：mysql、redis、java、astro、gorm、ci、release、performance、postmortem、security、migration、prompt 目前均为 0 篇文章引用，属于"先建后用"的预留位。若决定把总数压回 40 条，可从这些里合并 5 条。

季度盘点：每季度末看一次标签云（Ethereal 侧边栏有「文章标签」组件），对只有 1 篇文章的标签做合并决策。
禁止用标签做"待办标记"或"系列编号"（系列一、part-2）——系列关系用文章间链接表达。

来源：halo-kb/分类标签冲突处理.md → ## 一、结论摘要（TL;DR）（原文 810 字符）

一、结论摘要（TL;DR）

4 处冲突的诊断结论与处置：

#	冲突	诊断结论（实测）	本次处置
1	标签 45 条 > 设计自设上限 40	属实，且是文档自相矛盾：B.3 清单本身就有 45 条（标题却误写 38），B.4 规则又写"≤ 40"	改文档：上限调为 ≤ 50，45 条作为审定基线；列出 12 个 0 引用标签作候选精简清单。不删标签
2	20 个二级分类全为空	属实，且比预想更严重：实测 Ethereal 把一级与二级平铺在同一列表，首页一次性列出全部 29 个分类入口，其中 28 个是空页	改数据：20 个二级分类全部 `hideFromList=true`。前台分类入口 29 → 9
3	7 组「分类与标签同名」	按可判定口径拆开：`displayName` 完全相同的 3 组（会真的在前台显示成一样的字）、同 slug 的 3 组、语义重合的 16 组	改数据：3 组完全同名的分类改名消歧（只动显示名，URL 不变）→ 同名组 3 → 0
4	3 组分类与标签同 slug	实测不构成冲突：`/categories/x` 与 `/tags/x` 是两条独立路由，前台各自渲染正确	保留不动（改动反而会改 URL）

一句话总结：本次只改了「看得见的歧义」——把 20 个空分类从列表入口藏起来、把 3 个与标签撞名的分类改个显示名；一条分类或标签都没删，一个 slug 都没动，既有的 /categories/* 与 /tags/* 链接全部保持有效。

来源：halo-kb/分类标签落地记录.md → ## 五、最终清单（回读校验）（原文 5441 字符）

五、最终清单（回读校验）

5.1 分类树（29 条，按 `/-/tree` 实测返回顺序）

层级	metadata.name	slug	displayName	priority	permalink
一级	`76514a40-…`（既有）	`default`	默认分类	0	`/categories/default`
一级	`cat-tunnel`	`tunnel`	内网穿透与隧道	10	`/categories/tunnel`
二级	`cat-tunnel-arch`	`tunnel-architecture`	└ 隧道架构与协议	10	`/categories/tunnel-architecture`
二级	`cat-tunnel-deploy`	`tunnel-deploy`	└ 隧道部署	20	`/categories/tunnel-deploy`
二级	`cat-tunnel-debug`	`tunnel-debug`	└ 隧道排错	30	`/categories/tunnel-debug`
一级	`cat-cloud-ops`	`cloud-ops`	云服务器与运维	20	`/categories/cloud-ops`
二级	`cat-cloud-aliyun`	`cloud-aliyun`	└ 阿里云 ECS	10	`/categories/cloud-aliyun`
二级	`cat-cloud-baota`	`cloud-baota`	└ 宝塔与 nginx	20	`/categories/cloud-baota`
二级	`cat-cloud-dns-cert`	`cloud-dns-cert`	└ 域名 · DNS · 证书	30	`/categories/cloud-dns-cert`
一级	`cat-selfhost`	`selfhost`	自托管与 NAS	30	`/categories/selfhost`
二级	`cat-nas-fnos`	`nas-fnos`	└ 飞牛 OS 与 NAS	10	`/categories/nas-fnos`
二级	`cat-docker`	`docker-orchestration`	└ Docker 与编排	20	`/categories/docker-orchestration`
二级	`cat-halo`	`halo-site`	└ Halo 站点	30	`/categories/halo-site`
一级	`cat-backend`	`backend`	后端与自研服务	40	`/categories/backend`
二级	`cat-go`	`go-service`	└ Go 服务端	10	`/categories/go-service`
二级	`cat-api`	`api-contract`	└ API 与契约	20	`/categories/api-contract`
一级	`cat-frontend`	`frontend`	前端与客户端	50	`/categories/frontend`
二级	`cat-vue`	`vue-web`	└ Vue 与 Web 前端	10	`/categories/vue-web`
二级	`cat-client-app`	`desktop-mobile-client`	└ 桌面与移动客户端	20	`/categories/desktop-mobile-client`
一级	`cat-data`	`data-storage`	数据与存储	60	`/categories/data-storage`
二级	`cat-postgres`	`postgres`	└ PostgreSQL	10	`/categories/postgres`
二级	`cat-sqlite`	`sqlite`	└ SQLite	20	`/categories/sqlite`
二级	`cat-backup`	`backup-restore`	└ 备份与恢复	30	`/categories/backup-restore`
一级	`cat-ai`	`ai-tools`	AI 与效率工具	70	`/categories/ai-tools`
二级	`cat-llm`	`llm-integration`	└ 大模型接入	10	`/categories/llm-integration`
二级	`cat-agent`	`coding-agent`	└ 编码代理与自动化	20	`/categories/coding-agent`
一级	`cat-review`	`project-review`	项目实录与复盘	80	`/categories/project-review`
二级	`cat-review-tunnel`	`review-intranet-tunnel`	└ 项目：intranet-tunnel	10	`/categories/review-intranet-tunnel`
二级	`cat-review-halo`	`review-halo-site`	└ 项目：Halo 站点	20	`/categories/review-halo-site`

层级、顺序与设计文档 A.2/A.3 完全一致（8 个一级各挂其二级，一级按 priority 10→80 升序）。

5.2 标签清单（45 条）

metadata.name	slug	displayName	permalink
`go`	`go`	Go	`/tags/go`
`nodejs`	`nodejs`	Node.js	`/tags/nodejs`
`typescript`	`typescript`	TypeScript	`/tags/typescript`
`java`	`java`	Java	`/tags/java`
`shell`	`shell`	Shell	`/tags/shell`
`powershell`	`powershell`	PowerShell	`/tags/powershell`
`vue`	`vue`	Vue	`/tags/vue`
`vite`	`vite`	Vite	`/tags/vite`
`wails`	`wails`	Wails	`/tags/wails`
`astro`	`astro`	Astro	`/tags/astro`
`tailwindcss`	`tailwindcss`	Tailwind CSS	`/tags/tailwindcss`
`api`	`api`	API	`/tags/api`
`postgresql`	`postgresql`	PostgreSQL	`/tags/postgresql`
`sqlite`	`sqlite`	SQLite	`/tags/sqlite`
`gorm`	`gorm`	GORM	`/tags/gorm`
`mysql`	`mysql`	MySQL	`/tags/mysql`
`redis`	`redis`	Redis	`/tags/redis`
`migration`	`migration`	数据迁移	`/tags/migration`
`docker`	`docker`	Docker	`/tags/docker`
`docker-compose`	`docker-compose`	Docker Compose	`/tags/docker-compose`
`nginx`	`nginx`	Nginx	`/tags/nginx`
`baota`	`baota`	宝塔面板	`/tags/baota`
`acme`	`acme`	ACME / acme.sh	`/tags/acme`
`systemd`	`systemd`	systemd	`/tags/systemd`
`gitea`	`gitea`	Gitea	`/tags/gitea`
`release`	`release`	版本发布	`/tags/release`
`ci`	`ci`	CI/CD	`/tags/ci`
`dns`	`dns`	DNS	`/tags/dns`
`tls`	`tls`	TLS / HTTPS	`/tags/tls`
`reverse-proxy`	`reverse-proxy`	反向代理	`/tags/reverse-proxy`
`tunnel`	`tunnel`	内网穿透	`/tags/tunnel`
`aliyun`	`aliyun`	阿里云	`/tags/aliyun`
`nas`	`nas`	NAS	`/tags/nas`
`fnos`	`fnos`	飞牛 OS	`/tags/fnos`
`self-hosted`	`self-hosted`	自托管	`/tags/self-hosted`
`c33ceabb-…`（既有）	`halo`	Halo	`/tags/halo`
`troubleshooting`	`troubleshooting`	排错记录	`/tags/troubleshooting`
`postmortem`	`postmortem`	事故复盘	`/tags/postmortem`
`performance`	`performance`	性能优化	`/tags/performance`
`security`	`security`	安全	`/tags/security`
`backup-restore`	`backup-restore`	备份与恢复	`/tags/backup-restore`
`testing`	`testing`	测试与验证	`/tags/testing`
`ai`	`ai`	AI	`/tags/ai`
`deepseek`	`deepseek`	DeepSeek	`/tags/deepseek`
`prompt`	`prompt`	提示词	`/tags/prompt`

5.3 既有记录未被改动（硬约束核对）

记录	基线 version	现在 version	基线 creationTimestamp	现在 creationTimestamp	判定
默认分类	2	2	2026-09-13T11:04:52.413784422Z	2026-09-13T11:04:52.413784422Z	✓ 未改动
Halo 标签	3	3	2026-09-13T11:04:52.683109924Z	2026-09-13T11:04:52.683109924Z	✓ 未改动

来源：halo-kb/minidocs-落地记录.md → ## 5. 创建的树形目录（38 个节点）（原文 3171 字符）

5. 创建的树形目录（38 个节点）

与 知识库架构设计.md C.2 的设计树逐节点一一对应。 name = metadata.name = spec.slug = 设计稿里的 [doc: xxx] 标识；priority 照抄设计稿。

技术文档库 (KnowledgeBase: tech-docs, publicVisible=true)
│
├─ 00 · 从这里开始                        start-here              p10  [root]
│   ├─ 本站文档怎么读                     readme-first            p10
│   ├─ 环境与账号速查（脱敏）             env-cheatsheet          p20
│   └─ 文档写作规范（用本仓库模板）       writing-guide           p30
│
├─ 10 · 内网穿透与隧道                    tunnel                  p20  [root]
│   ├─ 架构与控制面/数据面划分            tunnel-architecture     p10
│   ├─ 部署                               tunnel-deploy           p20
│   │   ├─ 云服务器端部署                 tunnel-deploy-cloud     p10
│   │   ├─ NAS 端部署                     tunnel-deploy-nas       p20
│   │   └─ 客户端 Docker 部署             tunnel-deploy-client    p30
│   ├─ 域名与证书接入                     tunnel-domain-tls       p30
│   └─ 排错手册                           tunnel-troubleshoot     p40
│       ├─ 隧道域名访问异常               ts-domain-not-work      p10
│       └─ 流量统计恒为 0                 ts-stats-zero           p20
│
├─ 20 · 云服务器与运维                    cloud                   p30  [root]
│   ├─ 阿里云 ECS 与 Workbench CLI        cloud-aliyun            p10
│   ├─ 宝塔与 nginx 反代                  cloud-baota-nginx       p20
│   ├─ DNS 与 ACME 证书签发续期           cloud-dns-acme          p30
│   └─ 发布与回滚流程                     cloud-release           p40
│
├─ 30 · 自托管与 NAS                      selfhost                p40  [root]
│   ├─ 飞牛 OS 使用要点                   nas-fnos                p10
│   ├─ Docker 服务栈清单                  docker-stack            p20
│   ├─ Halo 站点（本博客）                halo-site               p30
│   │   ├─ 部署与升级                     halo-deploy             p10
│   │   ├─ 主题与插件清单                 halo-theme-plugins      p20
│   │   └─ 内容体系与分类标签规范         halo-content-spec       p30
│   └─ 数据备份与恢复演练                 selfhost-backup         p40
│
├─ 40 · 开发规范                          dev-guide               p50  [root]
│   ├─ Go 服务端约定                      dev-go                  p10
│   ├─ 前端与客户端约定                   dev-frontend            p20
│   ├─ API 契约与字段核对                 dev-api-contract        p30
│   └─ 提交与备份纪律                     dev-git                 p40
│
├─ 50 · 排错总索引（按症状找）            troubleshooting-index   p60  [root]
│   ├─ 容器与部署类                       ts-index-docker         p10
│   ├─ 网络与域名类                       ts-index-network        p20
│   └─ 数据库类                           ts-index-db            p30
│
└─ 99 · 归档                              archive                 p90  [root]
    └─ 已废弃方案留档                     archive-deprecated      p10

统计：顶级 7 个，总计 38 个节点；最深路径 tunnel → tunnel-deploy → tunnel-deploy-cloud（知识库根算第 1 层，共 3 层，符合设计稿「≤3 级」的建议）。

正文处理（本次的内容决策，如实记录）

节点类型	`raw` / `content`
分组节点（有子节点，共 13 个）	`> 本节为目录分组节点，用于组织子文档，请从左侧子节点进入。`
叶子节点（共 25 个）	`> 本文档待补充。`

设计稿 C.1 明确「目录树里的每个"文件夹"也是一个文档节点（可以只做分组、不写正文）」。本次给分组节点补了一句导语、给叶子节点留了「待补充」占位，目的是避免点进去是纯空白页。这两句是本次新写的内容，不属于设计稿原文，后续填正文时直接覆盖即可。 phase 统一为 published（不是 draft）——因为匿名可见性依赖发布状态，未发布的节点匿名读不到。