外观
重截控制台界面图
docs/assets/screenshots/ 里的配图由 apps/control/scripts/screenshots.mjs 批量生成： 用系统 Chrome（playwright-core，不下载浏览器）打生产控制台。
准备凭据
工具需要一个生产 admin token。两种给法，二选一：
bash
# ① 文件（gitignored）
echo '<admin token>' > apps/control/.screenshots-token
# ② 环境变量
export DN42_ADMIN_TOKEN='<admin token>'注入方式是预置 localStorage（dn42.admin.token / dn42.admin.apiBase）， 等价于「API Token」登录——不走登录表单，因此不会触发人机验证。
跑
bash
cd apps/control
node scripts/screenshots.mjs # 全量
node scripts/screenshots.mjs --list # 列出全部镜头
node scripts/screenshots.mjs --only flaps # 只截 id 含 "flaps" 的镜头启动时会打印当前配置，并自动挑一个 online 节点作为节点详情类镜头的样板：
控制台 https://console.natlan.io → 控制面 https://api.natlan.io，节点样板 hkg1，语言 zh，默认暗色可调项
| 环境变量 | 缺省 | 说明 |
|---|---|---|
SHOT_BASE | https://console.natlan.io | 截哪个前端 |
SHOT_API | https://api.natlan.io | 注入给前端的控制面地址 |
SHOT_LOCALE | zh | 界面语言 |
视口固定 1600×1000，deviceScaleFactor: 2（出 2 倍图）。
输出到两个地方
| 目标 | 用途 | 是否提交 |
|---|---|---|
docs/assets/screenshots/*.png | 本文档体系的配图（reference/apps/control.md 引用） | 提交 |
apps/control/shots/backend-images/wui-*.png | 覆盖控制器仓库 docs/images/ 的同名旧图 | gitignored，手工搬运 |
三类镜头
| 类型 | 定位方式 |
|---|---|
| 整页 | 直接访问路径截全页 |
| 节点详情 | 路径里的 @NODE@ 替换成自动挑出的节点 id |
| 组件级 | 按 widget 标题子串定位 section.widget 元素截图 |
组件级镜头会先把 widget 头对齐到固定 topbar 下方（.content 内部才是滚动容器）， 再按视口坐标裁剪——避开长表触发的整元素滚动拼接。
约定
- 文档配图默认暗色，只有
dashboard-hero额外出一版亮色。 - 向导镜头只在弹窗里翻页，永不点击最后一步的「创建对等连接」。这是在生产实例上 截图，任何写操作都会真的落地。
- 截图前会等
networkidle，并等到页面上没有.skeleton/[data-skeleton]才拍， 避免拍到骨架屏。
更新配图后
bash
git status docs/assets/screenshots/
git commit -am "docs: 重截控制台配图"如果界面版式变了，顺带检查 reference/apps/control.md 里的功能表述是否还准确——配图和文字必须描述同一个版本。
故障
GET /ui/nodes <状态码>——token 无效或控制面不可达：token 过期或写错了。 用 curl -H "Authorization: Bearer <token>" https://api.natlan.io/control/v1/ui/session 单独验一下。
「机群为空，无法截节点详情」：控制面里没有节点。整页镜头仍可用 --only 单独跑。
Chrome 启动失败：工具用的是 channel: 'chrome'（系统安装的 Chrome）， 不是 Playwright 自带的浏览器。装一个 Chrome 即可。