文档部署与运维

本站是 VitePress 静态站，不包含服务端应用或运行时密钥。

仓库 docs/ 是唯一事实源，docs/diy-guide/ 是本站源码。发布目录只接受从明确 Git 提交构建出的产物；不得从 VPS、.vitepress/dist/ 或工具生成的 Repowiki 反向同步内容。

本地构建

Set-Location docs/diy-guide
npm ci
npm run build

VitePress 会生成 .vitepress/dist/ 和 sitemap.xml；robots.txt 来自 public/。 发布前应连续构建两次，并比较页面清单与关键文件的 SHA-256。

原子发布布局

生产目录采用不可变 release 与当前软链接：

/var/www/kards-docs/
├── releases/
│   └── <git-commit>/
└── current -> releases/<git-commit>

推荐发布顺序：

1. 将本地构建产物上传到新的 <git-commit> 目录；
2. 按清单逐文件校验 SHA-256；
3. 目录权限设为 755，文件权限设为 644；
4. 以临时软链接加原子改名切换 current；
5. 验证首页、引擎页、DIY 页、sitemap、robots 和真实 404；
6. 验证失败则把 current 切回上一 release。

不得直接覆盖正在提供服务的目录，也不得把目录设为全员可写。

Web 服务器

静态路由应依次尝试：

{path}
{path}/
{path}.html

找不到时返回真实 404，不应把任意路径回退到首页。变更配置前创建备份，运行配置校验， 校验成功后再 reload。

回滚与保留

保留至少一个已验证 release 和最近一次 Web 配置备份。回滚只切换软链接与必要的配置 备份，不删除问题 release，便于离线比较。旧版单目录部署可保留为只读应急副本，但不再 作为活动根目录。