Docker-Panel Wiki：从 Markdown 到 VitePress 发布链的源码走读
打开 Docker-Panel Wiki 时，读者看到的是一套完整的中文 Docker-Panel 使用站点：安装、导航页、容器管理、Agent 节点、备份升级和故障自检都已经按页面组织好。但这个仓库本身并不是 Docker-Panel 的后端实现，也没有容器 API、数据库服务或 Agent 服务端源码；Wiki 仓库负责的是“如何把产品知识交付给读者”。
固定提交 945bc780 的源码可以分成四层：docs/ 下的 Markdown 内容，.vitepress/config.mts 的站点和导航配置，.vitepress/theme/ 下的 Vue 首页与主题增强，以及 .github/workflows/deploy-wiki.yml 中的 GitHub Pages 发布链。VitePress 把 Markdown 转成页面，Vue 只接管自定义首页和截图占位等交互，GitHub Actions 再把构建目录交给 Pages。
这套组织方式值得学习的地方，是把“产品文档信息架构”和“文档站界面”放在同一个可版本化仓库里：内容页面可以通过 Markdown 审阅，导航和主题通过 TypeScript/Vue 扩展，最终仍然生成静态站点。代价也很明确：首页文案、功能流程和主题样式存在代码耦合，文档仓库无法证明 Docker-Panel 本体的运行时行为，截图与支付二维码等资源还需要单独治理。
本文不按文件名逐个罗列，而是先建立内容站点的全景，再沿“启动配置 -> Markdown 页面 -> 主题渲染 -> 静态构建 -> GitHub Pages 部署”主链路深入，并补充首页交互、截图占位、路径基址和内容边界等分支。没有安装依赖、启动 VitePress 或执行 GitHub Actions；文中的运行结论均标为仓库声明或固定提交下的静态阅读结果。
GitHub 仓库信息
| 信息 | 内容 |
|---|---|
| 项目标题 | Docker-Panel Wiki |
| 项目描述 | 面向 NAS 与 Linux Docker 环境的 Docker-Panel 中文 Wiki，覆盖安装、服务导航、容器管理、Compose、Agent、监控、备份升级和故障排查。 |
| GitHub 仓库 | 980513Myb/docker-panel-wiki |
| 官网地址 | 未知（已检索但未找到可靠官网；仓库通过 GitHub Pages 发布） |
| 主要开发语言 | GitHub Languages API 未返回可用语言；固定提交中可见 Markdown、TypeScript、Vue 和 CSS |
| 开源许可证 | 未知（固定提交未发现可核对的许可证声明） |
| 最近代码更新 | 2026-08-21（GitHub pushed_at，核对日期：2026-09-11） |
先画出源码地图
这个仓库的主要交付物是知识库和站点，而不是一个可独立运行的 Docker 管理服务。目录可以按职责裁剪成下面几组：
docker-panel-wiki/
├── docs/ # Markdown 页面与站点内容
│ ├── index.md # custom-home 首页 frontmatter
│ ├── Installation.md # Docker Compose、Docker Run、首次登录
│ ├── Usage.md # 导航、容器、Compose、Agent 和配置说明
│ ├── Configuration.md # 环境变量、挂载和 Docker Labels
│ ├── Troubleshooting.md # 按现象组织的排障路径
│ ├── *.md # FAQ、备份、定时重启、版本日志等专题
│ ├── .vitepress/config.mts # VitePress 配置、导航、侧栏和构建基址
│ └── .vitepress/theme/ # 自定义首页、布局钩子和样式
├── docker-compose.yml # 独立运行 Wiki 的容器编排
├── package.json # pnpm、VitePress 开发与构建命令
├── pnpm-lock.yaml # 锁定依赖版本
└── .github/workflows/
└── deploy-wiki.yml # main push -> Pages 构建与部署| 模块或文件 | 放了什么 | 在链路中的职责 |
|---|---|---|
docs/*.md | 安装、使用、配置、FAQ、故障和版本说明 | 作为 VitePress 的 Markdown 输入，按文件路径生成页面路由 |
docs/.vitepress/config.mts | 语言、站点元数据、base、导航、侧栏、搜索和 Markdown 选项 | 组装文档站运行时配置，并决定本地与 Pages 的路径差异 |
docs/.vitepress/theme/HomePage.vue | 首页布局、流程卡片、控制台模拟视图和移动端菜单 | 在 layout: custom-home 时接管首页，提供产品化交互 |
docs/.vitepress/theme/Layout.vue | useData()、生命周期钩子和截图占位转换 | 在默认布局外包一层页面增强，处理文档中的 截图： 标记 |
docs/.vitepress/theme/style.css | 首页、文档页 hero、截图槽位与响应式规则 | 把主题组件和 Markdown 中的 HTML 片段统一成视觉系统 |
docker-compose.yml | Wiki 容器的端口和站点目录 | 提供仓库声明的本地容器预览路径；不是 Docker-Panel 后端 |
deploy-wiki.yml | checkout、pnpm、Node 22、构建和 Pages 部署 | 把 main 分支的源码转换成 GitHub Pages artifact |
目录树回答“内容和代码在哪里”，但还不能说明一篇 Markdown 怎样成为可访问页面。真正的运行关系要从 VitePress 配置开始。
核心能力不是后端 API，而是内容交付
用 Markdown 固定产品知识边界
docs/Installation.md 把 Docker Compose、Docker Run、ARM64、默认登录、挂载和安装后验证放在一页；docs/Usage.md 再把导航页、自动地址、容器卡片、Compose、Agent、SSH、镜像、代理、自动恢复和通知按使用区域组织。页面内容还会明确一些容易被误解的边界，例如 Docker Socket 必须读写挂载、Compose 目录只读时不能保存 YAML、删除 Compose 项目实际对应 docker compose down。
这说明文档不是简单的功能目录。页面通过表格、警告块、命令和截图占位把“配置 -> 操作 -> 结果 -> 风险”串起来；Configuration.md 又用环境变量表和 Docker Labels 示例把可配置的契约集中起来。内容层的扩展方式是新增 Markdown 页面或补充既有专题，而不是修改一套后端路由。
用配置把内容变成一套站点
config.mts 中的 nav 和 sidebar 是文档信息架构的单一入口之一。顶级导航固定指向安装、使用、故障自检和版本日志；侧栏根据 /Installation、/Usage 等前缀匹配页面，并把长篇 Usage.md 的关键锚点列成可扫描的目录。
export default defineConfig({
lang: 'zh-CN',
title: 'Docker-Panel Wiki',
cleanUrls: true,
themeConfig: {
nav: [
{ text: '首页', link: '/' },
{ text: '安装教程', link: '/Installation' },
{ text: '使用教程', link: '/Usage' }
]
}
})cleanUrls: true 让生成的访问路径不暴露 .html；outline、本地搜索翻译、上一页/下一页和深色模式文案则把 VitePress 默认主题变成中文文档产品。导航更新不需要改 Markdown 内容，但链接必须与文件路径和标题锚点同步，这也是该结构最容易出现的维护点。
用 Vue 首页表达产品工作方式
docs/index.md 只有 layout: custom-home 的 frontmatter。Layout.vue 通过 useData() 读取 frontmatter.layout，匹配后渲染 HomePage.vue；其他页面继续交给 DefaultTheme.Layout。因此首页不是一篇普通 Markdown，而是一个独立的 Vue 交互面。
HomePage.vue 用 ConsoleMode 把首页控制台分为 automation、monitoring 和 agent 三种视图，用 activeStep 配合 setInterval 每 2.2 秒轮换自动化流程；移动端菜单由 mobileMenuOpen 控制。页面里展示的 CPU、内存、节点和事件流是演示数据，不能当成 Docker API 的运行结果。这个判断很关键：视觉上的“实时控制台”属于首页表现层，真实容器状态仍由 Docker-Panel 主程序提供。
用截图槽位保留隐私边界
文档中写入 > 截图：... 时，Layout.vue 在挂载后扫描所有 blockquote。如果文本以“截图：”开头，且尚未处理，就替换成带 screenshot-slot 类的 HTML，并附带 SCREENSHOT SLOT 和隐藏域名、密钥、Token、个人信息的提醒。这样文章可以先保留截图位置，又不会把研究阶段的占位误当成真实图片。
截图占位转换也带来一个边界：该逻辑依赖浏览器端 onMounted 和 DOM 扫描，只在客户端挂载后发生；静态 HTML 初始仍然保留原始 blockquote。新增截图标记时，作者需要同时检查主题脚本、无脚本阅读体验和最终图片资源。
本地环境与构建入口
仓库声明的 Node 路径是 Node.js 22，包管理器固定为 pnpm@11.7.0，主要依赖是 VitePress 1.6.4、Vue 3.5.13 和 @lucide/vue。package.json 只有三个站点命令：
pnpm install
pnpm docs:dev # VitePress dev，端口 888
pnpm docs:build # 构建 docs 到 ../site
pnpm docs:preview # 预览已构建站点，端口 888这些命令来自固定提交的 package.json，本次没有安装依赖或启动站点。若要在源码目录验证，工作目录应是仓库根；成功信号应包括开发服务器监听 888，或 docs:build 在 site/ 产生静态文件。端口已被占用、pnpm 版本不匹配、锁文件无法解析和缺少图片资源，都会在进入浏览器验收前暴露。
仓库还提供 docker-compose.yml 作为 Wiki 的容器化本地预览入口。固定提交中的服务会在容器内启用 Corepack、冻结安装 pnpm 依赖，再以 0.0.0.0 监听文档开发服务器；README 给出的本地路径是：
docker compose up -d浏览器访问 http://127.0.0.1:888，成功信号是容器保持运行且该地址能打开首页；停止预览使用 docker compose down。这个 Compose 配置只是文档站的本地预览入口，不能替代 Docker-Panel 的生产部署，也不能证明文档描述的容器管理功能已经在本地运行。本次没有执行这组命令。
从源码看站点架构
正在准备渲染...
查看源码
flowchart LR
M[docs/*.md 内容] --> V[VitePress Markdown 管线]
C[config.mts] --> V
V --> T{页面布局}
T --> H[index.md layout: custom-home]
T --> D[DefaultTheme.Layout]
H --> HV[HomePage.vue]
D --> L[Layout.vue]
L --> S[截图占位 DOM 增强]
V --> O[site/ 静态输出]
O --> P[GitHub Pages]| 功能 | 首要阅读位置 | 继续追踪的边界 |
|---|---|---|
| 新增文档页面 | docs/*.md | 是否需要在 config.mts 的 sidebar 增加入口 |
| 首页交互 | docs/index.md、HomePage.vue | frontmatter.layout 是否仍为 custom-home |
| 页面通用增强 | Layout.vue | useData()、onMounted、page.relativePath 变化时的重装饰 |
| 站点路径与搜索 | config.mts | GITHUB_ACTIONS 是否改变 base，本地与 Pages URL 是否一致 |
| 截图占位 | Layout.vue、style.css | blockquote 文本前缀、CSS 类和最终资产是否匹配 |
| 发布结果 | deploy-wiki.yml | site/ 是否上传为 Pages artifact，main push 是否触发工作流 |
源码地图的一个认知转折是：docs/ 看起来像普通 Markdown 集合，但 config.mts 通过路径前缀把页面编排为产品化导航；另一个转折是：首页控制台展示了 Docker 管理概念，却只拥有前端状态和定时器，真实 Docker 控制权并不在这个仓库里。
启动与初始化链路
这个仓库没有 Node 服务端 main()。启动链路由命令、VitePress CLI 和配置文件共同完成：
正在准备渲染...
查看源码
sequenceDiagram
participant U as 开发者
participant N as package.json
participant VP as VitePress CLI
participant C as config.mts
participant R as docs/
participant B as 浏览器
U->>N: pnpm docs:dev
N->>VP: vitepress dev docs --port 888
VP->>C: 加载 defineConfig
C->>VP: 返回 base、nav、sidebar、themeConfig
VP->>R: 读取 Markdown 与 frontmatter
VP-->>B: 提供开发服务器页面
B->>C: 根据路由选择布局
C-->>B: DefaultTheme 或 HomePage.vue初始化时最重要的分支是 process.env.GITHUB_ACTIONS：本地开发和预览使用 /，GitHub Actions 构建时使用 /docker-panel-wiki/。favicon 也沿用同一分支。如果把 Pages 的 base 改成根路径，页面可能仍能生成，但资源和内部链接会在项目子路径下失效；如果本地误用仓库子路径，开发服务器又会出现反向问题。
页面加载后，Layout.vue 执行 decorateScreenshotSlots()；如果当前页面不是自定义首页，VitePress 默认布局仍负责目录、正文、搜索和页脚。watch(() => page.value.relativePath, ...) 处理客户端路由切换，确保新的文档页面也会重新装饰截图占位。
核心链路矩阵
| 链路 | 入口 | 关键决策 | 跨模块交接 | 可观察结果 | 失败位置 |
|---|---|---|---|---|---|
| 开发启动 | docs:dev | 使用本地 base: / | package.json -> VitePress -> config | 888 端口开发站点 | pnpm、端口、依赖或配置错误 |
| 文档页面 | 任意 docs/*.md | frontmatter 与路径决定布局 | Markdown -> VitePress -> DefaultTheme | 搜索、侧栏、正文和锚点 | 文件名、链接或 sidebar 不一致 |
| 首页交互 | docs/index.md | layout: custom-home | frontmatter -> Layout.vue -> HomePage.vue | 自动流程、监控和 Agent 视图切换 | Vue 编译、资源基址或浏览器 JS |
| 截图占位 | > 截图：... | 是否已添加 screenshot-slot | Markdown blockquote -> DOM 扫描 -> CSS | 槽位提示和隐私提醒 | 脚本未挂载或文本前缀改变 |
| Pages 发布 | main push | GITHUB_ACTIONS=true | Actions -> pnpm -> site/ -> Pages | GitHub Pages 生产站点 | workflow、锁文件、构建或 Pages 权限 |
下面分别展开这些链路中最能代表仓库设计的几条。
文档页面怎样被编排
docs/Usage.md 不是通过路由控制器注册的，而是由文件名和 Markdown frontmatter 进入 VitePress。页面的 next 元数据提供“下一篇”导航；config.mts 又通过 sidebar 把 Usage 内部锚点映射成可扫描的目录。两者结合后，读者既能按页面顺序阅读，也能直接跳到“自动地址”“Agent 节点管理”或“消息通知”。
页面内容中的 HTML 片段也属于源码边界的一部分：<section class="dp-page-hero"> 为文档页提供产品化标题区，style.css 再为这些片段设置统一间距、颜色和响应式布局。HTML 与 CSS 的组合让 Markdown 拥有更强的视觉表达力，但也意味着内容作者必须知道主题 CSS 的类名契约；只改 CSS 类名会影响多个文档页面。
内容中的 Docker 命令和环境变量描述主要来自 Wiki 本身，而不是本仓库的运行时调用。源码走读可以确认“文档怎样组织”，不能单凭这些页面确认 Docker-Panel 主程序是否真的按每一句话执行。
首页交互链路：演示状态与真实状态分开
HomePage.vue 在 onMounted 中建立定时器，把 activeStep 从 0 到 4 循环；控制台的自动化视图根据 activeStep % 4 高亮前四个流程步骤。用户点击“实时监控”或“Agent 节点”时，consoleMode 改变，Vue 条件渲染切换整块控制台内容。onBeforeUnmount 清理定时器，避免离开首页后继续更新。
首页交互链路没有 API 请求、WebSocket 或 Docker SDK。监控表格中的 12.4%、1.82 GB、3 个节点和事件流文案是静态演示状态；源码层面能确认交互和生命周期，不能把这些数值解释成真实主机指标。对文档站而言，静态演示适合展示产品心智模型；对运维系统而言，静态演示也提醒读者不要把营销首页当成观测端点。
截图占位链路：从 Markdown 到 DOM
截图占位处理是一个小但完整的客户端链路：
- 文档作者写入
> 截图：容器管理 / 状态筛选与操作菜单。 - VitePress 将 blockquote 渲染成
<blockquote>。 onMounted调用decorateScreenshotSlots()，遍历所有 blockquote。- 函数检查文本前缀和
screenshot-slot类，避免重复处理。 innerHTML替换为槽位标题、原始说明和隐私提示。style.css为.screenshot-slot提供视觉边界。
这里没有外部图片上传器，也没有自动截屏。二进制图片仍然存放在仓库的 docs/assets/ 或 docs/public/assets/，而占位逻辑只负责提醒和布局。若未来改成动态图片服务，需要重新定义资产许可、隐私脱敏和构建可复现性，不能只把 innerHTML 换成 <img>。
Pages 构建与发布链路
固定提交的 .github/workflows/deploy-wiki.yml 在 main push 或手动触发时运行，权限包含 pages: write 和 id-token: write。工作流顺序是 checkout、配置 Pages、安装 pnpm 11.7.0、设置 Node 22、pnpm install --frozen-lockfile、执行 pnpm docs:build、上传 site artifact，最后由 actions/deploy-pages@v4 发布。
正在准备渲染...
查看源码
flowchart TD
A[push main / workflow_dispatch] --> B[checkout 固定仓库内容]
B --> C[Node 22 + pnpm 11.7.0]
C --> D[pnpm install --frozen-lockfile]
D --> E[pnpm docs:build]
E --> F[site/ 静态产物]
F --> G[upload-pages-artifact]
G --> H[deploy-pages]构建时 GITHUB_ACTIONS 为真，config.mts 将 base 切换为 /docker-panel-wiki/，这使 Pages 项目站点能够从仓库名子路径加载资源。工作流没有运行 pnpm docs:dev，也没有执行 Docker Compose；部署产物是静态 HTML、CSS、JavaScript 和资源文件。
分支、失败与降级
本地路径与 Pages 路径
isGitHubPages 控制 base 和 favicon 路径，sitemap 主机名则在 config.mts 中固定为 GitHub Pages 地址。最常见的错误不是 Markdown 语法，而是新增资源使用了硬编码根路径，导致 Pages 子路径下丢失；新增导航链接也需要遵循 VitePress 的相对路由和 base 处理方式。
自定义首页与默认布局
只有 docs/index.md 设置 layout: custom-home，其他页面走默认主题。删除或拼写错误会让首页退回普通文档布局；反过来，如果把普通页面误设为 custom-home，HomePage.vue 会渲染完整控制台而不是正文。这个分支由 frontmatter 决定，不由文件名决定。
只读内容与可写运行目录
Wiki 的 Docker Compose 预览是文档站的运行方式，不会给文档容器注入 Docker Socket，也不会因此拥有管理主机容器的能力。安装页中关于 /var/run/docker.sock、/app/data 和 DOCKER_COMPOSE_ROOTS 的说明，属于 Docker-Panel 主程序的部署知识；本仓库只能承载和发布这些说明。
构建失败与证据边界
锁文件、Node/pnpm 版本、主题 TypeScript、Markdown 链接和静态资源都会影响 docs:build。本次没有执行构建，因此不能报告“站点已成功生成”；只能确认工作流声明的命令和固定提交中的配置。若要验证，应在临时工作区安装依赖并观察 site/，再单独检查 Pages workflow run。
设计取舍与可学习之处
值得学习的边界
- 内容与站点配置分层：Markdown 负责知识，
config.mts负责导航和全局元数据，主题目录负责视觉和交互，职责容易定位。 - 静态优先的发布模型：构建结果是静态站点，部署面小，回滚可以回到某个 Git 提交，适合文档和版本日志。
- 显式产品化入口：用
layout: custom-home只给首页特殊能力，普通文档仍享受 VitePress 默认主题，避免所有页面都被自定义组件接管。 - 隐私提醒靠近内容：截图槽位在页面渲染时追加密钥和个人信息提醒，降低临时截图直接公开的风险。
代价与不足
- 主题与 Markdown 类名耦合：
dp-page-hero、dp-flow、screenshot-slot等类名同时出现在内容和 CSS 中，缺少组件级类型检查，重构时容易出现视觉回归。 - 首页演示数据是静态的：控制台交互不能作为真实 Docker 指标来源；读者需要回到 Docker-Panel 主项目验证运行行为。
- 资产治理没有在构建脚本中体现：仓库含品牌图、截图和支付二维码，许可证、隐私和更新策略需要额外审查；工作流只负责构建，没有内容资产扫描门。
- 导航维护依赖手工同步：新增页面通常要同时改文件、sidebar、next/prev 和资源路径，缺少自动死链或页面覆盖检查。
- 许可证状态未确认：固定提交没有可核对的 SPDX 许可证文件，不能把 Wiki 或其中图片默认为可自由再分发。
适合怎样的源码学习
这个仓库适合以下学习目标：
- 想理解 VitePress 如何以文件路径、frontmatter 和主题配置组成中文知识库。
- 想学习 Vue 自定义首页如何与 VitePress 默认布局共存。
- 想观察静态站点怎样处理 GitHub Pages 子路径、搜索、侧栏和部署 artifact。
- 想研究 Markdown 内容、HTML 片段和 CSS 主题之间的协作边界。
这个 Wiki 仓库不适合作为以下问题的源码入口：
- Docker-Panel 如何调用 Docker Engine、维护 SQLite 或执行容器升级。
- Agent 如何认证、同步远程节点和上报资源指标。
- 面板后端如何处理登录、通知、备份和恢复。
这些问题应该转向 Docker-Panel 主程序仓库；本 Wiki 只能提供面向用户的操作说明和截图线索。与 MkDocs、Docusaurus 或普通 VitePress 模板相比，本仓库的独特点不在文档引擎本身，而在“产品化首页 + 运维知识内容 + Docker-Panel 专题边界”的组合。
采用场景与同类比较
如果团队已经使用 GitHub 管理 Docker-Panel 的中文运维资料，希望首页有产品化入口、正文能按版本审阅，并且愿意维护少量 Vue 和 CSS，那么这个仓库的结构是合适的。Docker-Panel Wiki 尤其适合 NAS 用户手册、个人运维知识库和围绕一个自托管产品持续维护的中文文档站。若团队需要多人在线编辑、权限审批、全文检索服务端或运行时指标看板，静态 Wiki 的能力就不够，应把文档交给专门平台，把监控交给真正的控制面板。
| 维度 | Docker-Panel Wiki | 普通 VitePress 模板 | MkDocs | Docusaurus |
|---|---|---|---|---|
| 定位 | 围绕 Docker-Panel 的中文运维知识库与产品化首页 | 通用 Vue 驱动静态文档站 | Python 生态的 Markdown 文档站 | React 生态的文档与版本站点 |
| 内容模型 | Markdown + frontmatter + 手工 sidebar/锚点 | Markdown/MDX 与主题配置 | Markdown + YAML 配置与插件 | Markdown/MDX + React 页面和版本配置 |
| 主题扩展 | Vue 自定义首页、共享 Layout、CSS 类名契约 | Vue 主题与组件 | Jinja 主题、插件和 CSS | React 组件、主题和插件 |
| 发布方式 | GitHub Pages 工作流，site/ 静态产物；另有容器化本地预览 | 通常接入任意静态托管 | 通常接入任意静态托管 | 通常接入任意静态托管或 GitHub Pages |
| 维护成本 | 内容、VitePress 配置、Vue 首页和产品截图需要一起维护 | 主要维护内容与主题 | 需要 Python/MkDocs 依赖和主题配置 | 需要 Node/React 依赖，版本化能力更完整但结构更重 |
| 更适合 | 单一产品、中文运维流程、需要产品化首页的仓库 | 轻量通用文档和 Vue 生态团队 | Python 团队和配置驱动文档 | 多版本、多语言、React 组件较多的文档平台 |
表格中的同类定位来自各项目公开文档和默认架构，不能替代对具体版本的构建测试。选择 Docker-Panel Wiki 的理由不是文档引擎本身的创新，而是该仓库把 Docker-Panel 的操作知识、视觉入口和 Pages 发布约束放在了同一个提交历史里。
总结与下一步
Docker-Panel Wiki 的源码主线是一条静态内容交付链：Markdown 页面承载 Docker-Panel 知识，config.mts 编排路由、侧栏、搜索和 Pages 子路径，Layout.vue 与 HomePage.vue 增加产品化首页和截图占位，GitHub Actions 最后把 VitePress 的 site/ 目录交给 Pages。仓库边界也同样清楚：这里没有 Docker Engine、SQLite、Agent 认证或容器升级实现。
从源码学习的最佳入口是先追 docs/index.md -> Layout.vue -> HomePage.vue，再看 config.mts 的导航和 deploy-wiki.yml 的构建发布；从产品问题学习则应回到 Installation.md、Usage.md、Configuration.md，并把涉及真实容器行为的结论交叉核对 Docker-Panel 主程序仓库。这样既能理解文档站如何工作，也不会把演示首页误当成后端控制面板。
若继续扩展这个 Wiki，优先补自动死链检查、图片与二维码的许可/隐私扫描、导航覆盖测试和版本化部署记录；这些改动比继续堆叠首页演示数据更能降低长期维护成本。
调试与继续阅读路径
遇到页面问题时，可以按故障类型选择入口：
| 现象 | 先看哪里 | 判断方向 |
|---|---|---|
| 首页没有产品化控制台 | docs/index.md、Layout.vue | 检查 layout: custom-home 和主题导入 |
| 页面链接在 Pages 失效 | config.mts 的 base、导航和 Markdown 链接 | 检查 GITHUB_ACTIONS 分支和 /docker-panel-wiki/ 前缀 |
| 截图提示没有样式 | Layout.vue、style.css | 检查 blockquote 前缀、类名和客户端挂载 |
| 侧栏没有新页面 | config.mts 的路径前缀 sidebar | 检查文件名、链接和大小写 |
| Actions 构建失败 | deploy-wiki.yml、package.json、pnpm-lock.yaml | 检查 Node/pnpm、锁文件、主题 TypeScript 和资源 |
| 文档说法与产品不一致 | docs/Usage.md、docs/Configuration.md、Docker-Panel 主仓库 | 区分 Wiki 静态说明和主程序运行事实 |
推荐的源码阅读顺序是：先读 docs/index.md 与 config.mts，再读 Layout.vue 和 HomePage.vue，然后回到 Installation.md、Usage.md、Configuration.md 看内容契约，最后读 deploy-wiki.yml 理解发布边界。这样能先建立“静态站点怎样工作”的模型，再判断每条 Docker 运维说明是否需要到另一个仓库追证。
参考资料
- docker-panel-wiki 固定提交
- VitePress 文档，用于核对配置、主题和静态构建模型。
- VitePress 默认主题，用于理解
DefaultTheme.Layout和文档页面的基础能力；版本可能随上游变化。 - GitHub Pages Actions 文档，用于理解
configure-pages、artifact 和deploy-pages的发布关系。 - Vue 生命周期文档，用于理解
onMounted、onBeforeUnmount和首页定时器的边界。 - MkDocs 官方文档，用于比较 Python 配置驱动的 Markdown 文档站；比较结论不是对当前仓库的运行时测试。
- Docusaurus 官方文档，用于比较 React/MDX、多版本和插件化文档站；版本差异需要按具体项目重新核对。