网站维护#

公开 GitHub Pages 源码位于 site/。网站为静态双语页面：index.html 为英文，zh.html 为中文。保持内容与锚点对应，共用 styles.css 和 app.js。

设计与产品预览#

沿用控制台中性底色、白色内容面、细边框、8px 卡片圆角和蓝色主操作。首页以明确标记的交互示意展示应用、路由、指标、交付和可观测。example.com 域名和资源值是示例数据，不是真实集群或截图。路由关系说明应与连通性及健康检查区分。

示意使用原生 HTML/SVG，无需远程图片。标签页支持方向键、Home、End。JavaScript 还提供移动菜单和命令复制；核心内容与文档在无 JavaScript 时仍可阅读。

Geist 字体与许可证自托管于 site/assets/fonts/，中文使用平台 CJK 字体。既有品牌资产仍保留，不加载旧装饰性首屏图片。

构建与预览#

使用与 CI 一致的 Python 3.12：

python -m venv /tmp/luma-site-venv
/tmp/luma-site-venv/bin/python -m pip install Markdown==3.8.2
/tmp/luma-site-venv/bin/python scripts/build-site.py
python scripts/check-site.py
python -m http.server 5182 --directory _site

打开 http://localhost:5182/ 或 http://localhost:5182/zh.html。模拟项目 Pages 前缀时，把产物复制到 luma/ 目录并托管父目录；所有本地 URL 都必须在此前缀下工作。

构建复制静态资源与原始文档，再将 docs/**/*.md（排除内部 docs/research/）渲染为同目录 HTML。支持 Markdown 表格、围栏代码和页内目录。文档相对链接改写为 HTML，仓库代码和目录链接指向 GitHub。Mermaid 保留为代码示例，不执行远程渲染器。

编辑 Markdown 源码，不编辑生成 HTML。重要指南加入 scripts/build-site.py 的 GUIDES，按需同步两种首页入口。不要提交 _site/。输出含 .luma-site-output 标记；后续构建只替换带标记目录，拒绝覆盖其他非空目录。

发布#

相关变更进入 main 或手动触发时，.github/workflows/pages.yml 构建并部署网站。它安装固定版本 Markdown 渲染器，通过 GitHub Pages 发布 _site 产物。

本地构建不等于公开发布。合并发布前检查中英文、窄屏导航、预览标签、命令复制与文档链接。

中文文档#

每篇公开英文指南都有对应的 *.zh-CN.md 中文源文件。原本就是中文的文档保留原路径。更新正文时同步维护译文；命令、配置键和围栏代码示例须保持一致。CLI 帮助在两个语言版本中均保留终端实际输出。先运行 CLI 参考生成器，再将更新后的帮助代码块同步到中文参考。

中文页面使用中文导航，并将文内文档链接指向中文版本。显式标题 ID（{#original-heading-id}）保留已有英文章节链接及语言切换位置。翻译新增章节时，请添加对应 ID。中英文首页应链接到各自语言的文档。发布前，scripts/check-site.py 检查中文覆盖、译文代码块、章节 ID 和本地链接。

控制台预览的 25 个左侧菜单和子菜单均可切换对应示例页面，面包屑与选中状态同步更新。顶部五个快捷标签共用同一导航状态，并支持方向键、Home 和 End。维护时须同步中英文菜单目标及示例页面。