本站文档怎么读

2026-09-13

项目实录与复盘

Halo/事故复盘

文章摘要

|

来源：halo-kb/README.md → ## 阅读约定（原文 378 字符）

阅读约定

证据标注（全文沿用，请按标注判断可信度）：

标注	含义
【实测】	对真实实例发过 HTTP 请求、或直接读过 NAS 上的文件/容器/数据库，附状态码、字节数或原始输出
【推断】	由实测事实外推，未直接验证
【未确认】	明确没有验证的项。不要当结论用，也不要在下游决策里引用

凭据约定：本文档不含任何真实令牌、口令、密钥。所有示例统一用占位符 <TOKEN> 表示；正文中出现的凭据一律是"存在何处、如何轮换"的描述，不是值。示例命令从环境变量读取凭据，不落盘。

诚实约定：本文档不替读者拍板。各报告之间存在矛盾的地方并列写出，并标出"以哪一份为准、为什么"；没有实测支撑的一律标【未确认】。

来源：halo-kb/README.md → ## 一、一页纸摘要（原文 3600 字符）

一、一页纸摘要

1.1 本次做成了什么（全部有实测证据）

#	成果	关键数字 / 判据
1	实例基线摸清	Halo Pro 2.26.1（三处互证）、PostgreSQL 15.4、Compose 部署、容器 `Halo`/`PostgreSQL`、端口 `28090→8090`
2	Halo CLI 装好并接通	`@halo-dev/cli@1.3.0`，profile `local` → `http://<内网IP>:28090`，PAT 只读验证通过（身份 `sushike`，`super-role`）
3	插件选型核实 + 新装两个	新装并启用 `halo-plugin-minidocs`（显示名「知识库」）v1.0.2、`portfolio`（显示名「项目集」）v1.0.0；实例插件总数 22（含既有 20）
4	信息架构设计并落地	8 个一级 + 20 个二级分类、45 个标签，全部 HTTP 201 落地；73 条回读字段断言全通过；重跑零新增（幂等）
5	MiniDocs 知识库建成	知识库 `tech-docs`（显示名「技术文档库」）38 节点树，父子关系 38/38 正确；匿名阅读开启后 403 → 200，7 个公开端点全部 200
6	页面与展示配置完成	新增菜单项「文档」→`/docs`、「项目」→`/portfolio`；新建并发布页面 `skills`（技能栈）、`timeline`（履历）；主题出厂演示文案 7 个字段已替换
7	Gitea → 项目集真实同步	2 个私有仓库录入项目集，`/portfolio` 从「共 0 个项目」变为「共 2 个项目」；同步脚本 48 项自测 + 回读校验 44 项断言全通过
8	备份已真实演练	产物落在 `/vol1/1000/docker/halo/backups/`，`sha256sum -c` 四项全 OK；非破坏性恢复验证通过（临时库 34 表 / 391 extensions 一致，`pg_restore` error 0 行）
9	安全与运维审计	端口暴露面、HTTP vs HTTPS、凭据清单（脱敏）、PG 角色权限、`keys/` 目录权限问题，逐条给出判据与处置建议

1.2 本次没有做成什么（最重要的一节，请务必读完）

用户提出的三项 AI 需求，全部判决为「当前不可实现」【实测，见第九章】：

需求	判决	一句话根因
① AI 问答交互页（前台访客多轮对话）	❌ 当前不可实现	AI Foundation 的 16 个 HTTP 端点无一面向访客，jar 内也没有聊天页
② AI 辅助创作（编辑器内润色/摘要/大纲）	❌ 当前不可实现	AI Foundation jar 内无任何编辑器扩展，`ui-plugin.json` 的 `extensionPoints` 为空
③ AI 增强搜索（语义检索替代关键词）	❌ 当前不可实现	实例产生不了任何向量：`embeddingModelName` 为 `null`，且 DeepSeek 在 AI Foundation 里只有 language adapter、没有 embedding adapter

配套的四条硬证据（详见第九章）：

实例当前产生不了任何向量：default-model-slots 只返回 {"languageModelName":"deepseek-…-flash-…"}；15 家供应商类型里 11 家支持 embedding，DeepSeek 不在其中。
AI Foundation 的 RAG 只是"中间件"不是"知识库"：run.halo.aifoundation.rag 包只有接口与中间件（RagRetriever、RagLanguageModelMiddleware、RagMiddlewares…），没有任何具体检索实现。
不能用 MiniDocs 当知识源：对 AI Foundation 全 jar 搜索 minidocs / knowledgebase → 0 命中；MiniDocs 侧也没有任何检索 API。
当前搜索是关键词检索：搜索引擎扩展点的唯一实现是 LuceneSearchEngine，搜索组件只调用 POST /apis/api.halo.run/v1alpha1/indices/-/search（请求体只有 keyword/limit/高亮标签），与 AI Foundation 零集成（observed-caller-plugins 实测 []）。

另有两条相关的未达成：

ai-assistant（AI 助手 2.2.3，付费插件）因 invalid license 拒绝启动 —— 用户已决定本轮不启用。它其实是上述三项需求的"正主"（自带编辑器 AI 增强、AI 总结、RAG 仓库与相似度检索）。
MiniDocs 的"检索"目前只有关键词检索：知识库前台自带搜索框，走的是插件/主题的关键词匹配，不是语义检索。

1.3 当前站点长什么样【实测，匿名访问】

匿名（不带任何 Authorization）逐条验证，全部 HTTP 200：

路径	内网	公网隧道	页面内容判据
`/`	200	200	含「俗世客的思行小筑」
`/docs`	200	200	MiniDocs 知识库首页，含「技术文档库」
`/docs/view/tech-docs`	200	—	知识库详情，72465 字节，含 38 节点树与导语
`/portfolio`	200	200	项目集，含「项目作品集」与「共 2 个项目」
`/about`	200	200	关于页（仍是出厂占位文案，见第十四章）
`/skills`	200	200	技能栈页（数据为空，主题 `extendPages.skills` 为 `{}`）
`/timeline`	200	200	履历页（数据为空）
`/rss.xml`	200	—	含公网域名 `<服务名>.tunnel.sushike.cloud`

导航栏最终顺序：首页｜文章｜默认分类｜关于｜文档｜项目。

⚠️ 探测匿名可访问性时必须禁止跟随重定向：Halo 对未认证的 /apis/* 一律返回 302 → /login?authentication_required，若 curl 跟随重定向会拿到登录页的 200，被误判成"匿名可读"。

1.4 复现这套东西的最小路径（5 步）

1) 装 CLI 并登录        → 第三章（注意：halo config set 不存在，见 3.2）
2) 装两个插件           → 第四章（halo-plugin-minidocs v1.0.2、portfolio v1.0.0）
3) 建分类 / 标签         → 第五章（scripts/create_taxonomy.py，幂等）
4) 建知识库与 38 节点树  → 第五章 5.6（scripts/minidocs_setup.ps1，幂等）
5) 建页面 / 菜单 / 同步项目 → 第七、八章（configure_site_display.py、gitea_to_halo.py）

每一步都有"预期输出"与回读判据；不要只看退出码（第三章 3.2 会给出为什么）。

来源：intranet-tunnel/README.md → ## 目录（原文 391 字符）

一、架构设计
二、目录结构
三、端口规划
四、快速开始
五、Nginx 网关配置
六、管理后台
七、REST API
八、数据库与多驱动支持
九、控制协议
十、安全与 DDoS 防护
十一、扩展功能
十二、登录增强（图形验证码与短信验证码）
十三、管理端 UI 现代化改造
十四、实测记录
十五、常见问题

俗世客的思行小筑