phonerail/site

site —— 需求文档的网页版（VitePress）

把项目根的 需求文档.md 渲染成一个可搜索、带目录的静态站。

cd site
npm install          # 首次
npm run dev          # 本地预览  http://localhost:5173/
npm run build        # 产出静态站到 site/.vitepress/dist/
npm run preview      # 预览构建产物

内容从哪来

唯一事实来源是 D:\DCDC\需求文档.md。 npm run dev / npm run build 之前会自动跑 scripts/sync-docs.mjs， 把它拷成 site/docs/index.md。

⚠️ site/docs/ 下的文件是生成物，不要在里面改内容 —— 改了会在下次同步时被覆盖。 要改内容就改项目根的 需求文档.md。

为什么要拷而不是让 VitePress 直接指向项目根：srcDir 指到 D:\DCDC 之后， 那里的 .md 编译出的虚拟模块要 import 'vue/server-renderer'，而 node_modules 在 site/ 下（是子目录不是父目录），Rollup 解析不到，构建会直接失败。

想再加一篇（比如设计文档 / PROGRESS）

改 scripts/sync-docs.mjs 里的 PAGES：

const PAGES = [
  ['需求文档.md', 'index.md'],
  ['五路直供电源板设计.md', 'design.md']   // 新增
]

再在 .vitepress/config.mts 的 themeConfig.nav / sidebar 里加一项即可。 （设计文档有 432 KB / 6900 行，会是一个很长的单页，建议单独放一条 nav。）

站点结构上的两个决定

1. 需求文档就是首页，没有另做 landing page —— 这个站只有一篇正文， 多一层入口只会多一次点击。
2. 侧边栏是从 需求文档.md 的 ## 标题现算的，不是手写的常量。 正文加一章，侧边栏自动就有，不会漏。

代价是 config.mts 里得自己实现一份和 VitePress 一致的 slugify() （@mdit-vue/shared 打包在 vitepress 内部，外面 import 不到）。 两边只要差一个字符，侧边栏链接就会静默跳空——页面照样打开，只是不滚动，肉眼很难发现。 所以 npm run build 之后会自动跑 scripts/check-anchors.mjs， 拿构建产物里真实的标题 id 对一遍生成的锚点，对不上就让构建失败。

部署（home 服务器）

线上地址：http://phonerail.home.example:7755/ —— 挂在统一门户后面，要先登录。

更新内容只要一条命令（在 Git Bash 里，从 site/ 跑）：

bash deploy/deploy.sh

它做三件事：npm run build → tar over ssh 同步到 /root/phonerail-docs → 回读验证。

项	值
静态文件	10.5.5.13:/root/phonerail-docs
nginx	/etc/nginx/conf.d/phonerail-docs.conf（源在 deploy/nginx-phonerail-docs.conf）
监听	127.0.0.1:7757 —— 只给门户反代用
门户注册	应用表 key=phonerail / port=7757，授权 admin + staff + viewer

⚠️ 7757 故意只绑 loopback。 这台机器实测是大范围 / DMZ 转发，绑 0.0.0.0 的端口 默认公网可达，而应用端口那一路是不带门禁的 —— 现有 12 个应用就是这个状态。 绑 loopback 之后，唯一入口只剩门户，代价是内网直连 10.5.5.13:7757 也进不来。

改了 deploy/nginx-phonerail-docs.conf 之后要单独推一次：

scp deploy/nginx-phonerail-docs.conf 10.5.5.13:/etc/nginx/conf.d/phonerail-docs.conf
ssh 10.5.5.13 'nginx -t && systemctl reload nginx'

改了应用注册信息（改名 / 换端口 / 增删应用）走门户 → 应用管理，然后：

ssh 10.5.5.13 'python3 /root/portal/deploy/gen-vhosts.py --write'

其它

• 搜索：本地搜索（不联网）。默认分词器会把整段中文当成一个 token， 已在 config 里换成 Intl.Segmenter 分词，中文能搜出来。

• 矢量框图：markdown 里写成

  ```diagram=system
  （这里仍然是 ASCII 框图）
  ```
  

  的代码块，站点上会被替换成 site/diagrams/<名字>.svg 的内联 SVG（当前三张： system / layers / links）。内联而不是 <img>，是为了让 SVG 用页面的 CSS 变量 跟着明暗主题走。找不到对应 svg 时退回渲染成普通代码块，站点不会崩。

  ⚠️ ASCII 与 SVG 是两份，改框图内容要改两处。 保留 ASCII 是有意的：它既是 GitHub / 编辑器里的可读降级，也是 SVG 的 alt 内容。 颜色一律用 custom.css 里的 --dg-* 变量与 .dg-box / .dg-key 这类 class， SVG 文件里不要写死颜色，否则深色主题下会瞎。

• 告警块：正文里以 ⚠️ / ❌ 开头的引用块会渲染成橙色警告卡片， ✅ 开头的渲染成绿色。这个转换在 config.mts 的 markdown 插件里做， 不改 markdown 源文件 —— 所以原稿在 GitHub / 编辑器里看仍然正常。

• 版心加宽到 1080px：文档里 5~6 列的需求表在默认的 688px 下会被压成一堆折行。