figmar/apes-sidebar
1
0
Fork 0
Code Issues 1 Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
main
apes-sidebar/docs/wiki/05-运维手册.md
T
figmar 63bcb47ed0
CI / ci (push) Canceled after 0s
Details
CI / ci-windows (push) Canceled after 0s
Details
CI / plugin-mount (push) Canceled after 0s
Details
docs(wiki): 建立项目百科（需求分析 → 架构 → 功能 → 部署 → 运维 → 排障 → 开发与测试） 
Gitea 的 wiki 此前是空的。本次把百科的**源文件版本化进仓库**（docs/wiki/），
再用脚本发布到 wiki——文档因此与代码同源、可 review、可回溯，而不是只存在于网页上。

八页（Home 作为导航与项目速览）：

  Home          项目速览 / 两条版本线的宿主兼容性差异 / 文档地图 / 谱系说明
  01-需求分析    五条核心需求（现象·根因·验收标准·状态）+ 非目标与约束 + 需求→实现→锚点
  02-系统架构    host/client 分层与产物、三层接口面、面板宿主层叠契约与 isolate 陷阱、关键不变量
  03-功能说明    面板/预览器总表、信息层三 tab 数据来源、HTML 预览交付方式、i18n 与令牌、配置面
  04-部署指南    宿主版本矩阵与选线决策、profile 接线（file: + bundles）、构建、验收清单、卸载与切换
  05-运维手册    分支/tag 策略与回滚剧本、发布纪律（版本三元组/非确定性产物）、巡检、备份铁律、诊断
  06-故障排查    8 类症状 → 根因 → 处置（含本会话实机定位过的全部案例）+ 定位手法
  07-开发与测试  工程约定、目录、门禁基线、测试分层与契约 spec、扩展点、测量式 re-base 方法

脚本 scripts/push-wiki.sh：幂等发布（POST 新建 / PATCH 覆盖），凭据走 git credential helper
（临时 netrc，600，退出即删），不落盘、不进 argv。已实测：8 页全部发布成功，复推为更新。

内容纪律：只写**本次会话实证过**的事实（提交号、行数、层级取值、产物大小、宿主版本矩阵、
静默禁用机制、re-base 步骤），未验证的部分明确标注为待验证或已知限制；并如实说明本仓库
历代承载过 v1 / v2 / 当前 fork 三代实现，本百科描述的是 main 上的 fork 线。
2026-10-04 01:19:31 +08:00

6.9 KiB
Raw Permalink Blame History

05 · 运维手册

本篇是日常运维、升级与回滚的操作手册。所有命令都以「先留锚点、再动手、改完回读验证」为原则。

一、版本线与分支策略（当前远端实况）

ref 指向 含义 / 用途
main 4422001 旧宿主线：插件 1.2.0，上游基线 v0.19.1，peer ^0.1.5-rc.1。本机 DSH Desktop 2.0.10 正在跑这条
sync/v0.24.1 e5bbef1 新宿主线：插件 1.3.0，上游基线 v0.24.1，peer ^0.2.0-rc.1。待 ≥0.2.0 宿主实机验证
backup/pre-sync-v0.19.1 96cc334 v0.19.1 re-base 之前的状态（旧 fork 三角色 tab 版）
backup/pre-sync-v0.24.1 4422001 v0.24.1 re-base 之前的 main（等价于当前 main，作为下次升级的锚点）
tags/apes-v1.1.0-pre-sync 96cc334 与上面第一支 backup 同一提交，tag 形式的锚点
tags/apes-v1.2.0 4422001 当前已验收的 1.2.0 线

纪律：任何 re-base / 大改之前，先建 backup/pre-sync-<新基线> 分支 + apes-v<版本> tag， 并推送到远端（本地锚点在多人/多机场景等于不存在）。

二、回滚剧本

场景 A：某次提交引入回归（单点回退）

cd <插件仓库>
git log --oneline -5                 # 定位可疑提交
git revert <sha>                     # 保留历史的回退（推荐）
# 或整体丢弃：git reset --hard <上一提交>
pnpm typecheck && pnpm build && pnpm test
cd ~/.dsh/profiles/<profile> && pnpm install   # file: 是复制语义，必须重装
# ⌘Q 完全退出 DSH → 重启

场景 B：整条线回退（例如新线在真机上不可用）

git checkout main                    # 或 backup/pre-sync-v0.24.1
pnpm install && pnpm build
cd ~/.dsh/profiles/<profile> && pnpm install
# ⌘Q 重启

场景 C：profile 依赖/config 被改坏

cd ~/.dsh/profiles/<profile>
cp package.json package.json.bak.$(date +%s)     # 先备份
bash <插件仓库>/scripts/switch.sh aps            # 或 upstream，脚本会重写依赖与 bundle 行
pnpm install
# ⌘Q 重启

回滚验收：重启后按 04-部署指南 §三 的验收清单逐条核对（至少「右列一套侧边栏」 与「三个信息层 tab 存在」两条）。

三、发布 / 变更纪律

  1. 版本三元组必须一致：
    • package.json 的 version
    • dsh.plugin.json 的 version
    • src/client/service.ts 的 SIDEBAR_SERVICE_VERSION 三者不一致会被单元测试（tests/service.spec.ts）直接拦下——不要改其中一个而忘了另一个。
  2. 门禁三连必过：pnpm typecheck && pnpm build && pnpm test。当前基线：main 131 个测试文件 / 1367 通过；sync/v0.24.1 141 个文件 / 1515 通过（另有 9 个 skip）。
  3. 产物非字节确定性：两次构建的字节数可能相同但 sha 不同。因此「改完代码 → 让 profile 用旧副本」 永远不成立；必须重新 pnpm build + 让 profile 重新安装。
  4. 发布方式：本 fork 未发布 npm 包，发布 = 推分支/tag + 目标机器 git fetch && checkout && pnpm build
    • profile 重装。发布前把 README.md 与 docs/wiki/ 一并更新（wiki 见 §六）。
  5. 不要顺手改无关文件：re-base 时保持「只带自己的增量」，避免下次升级冲突面扩大。

四、日常巡检清单

频率 检查项 命令 / 判据
每次部署后 版本三元组一致 见 §三.1
每次部署后 产物标记齐全 grep -c 'apes:agents' lib/client.js（>0）、grep -c 'dsh-desktop-content-viewport' lib/client.js（>0）
每次部署后 profile 副本已刷新 比对 lib/client.js 与 ~/.dsh/profiles/<p>/node_modules/dsh-apes-sidebar/lib/client.js 的 sha256
每次升级宿主/插件 宿主版本 ↔ peer 范围 见 04-部署指南 §1.1（不匹配 = 静默禁用）
每月/大改前 锚点是否已推远端 git ls-remote <remote> | grep -E 'heads/(main|sync)|tags/apes'
异常时 诊断条与控制台 页面左下角红条；控制台 [dsh-apes-sidebar] 前缀

五、备份与配置铁律

  • 改任何 profile 配置前先备份，改完回读验证（不要假定写入即生效）：

    cp ~/.dsh/profiles/<profile>/package.json{,.bak.$(date +%s)}
# 改完：
python3 -c "import json;json.load(open('$HOME/.dsh/profiles/<profile>/package.json'));print('JSON OK')"

  • DSH 应用配置的类型陷阱：部分字段（如材质/透明度类的 macosMaterial）必须是字符串 （"off" / "transparent"）。若被写成 YAML 布尔（false），DSH 会启动进恢复模式。 改完务必回读校验类型：

    python3 -c "import yaml;d=yaml.safe_load(open('$HOME/.dsh/settings.yaml'));v=d.get('macosMaterial');print(v, type(v).__name__)"

  • 不要回滚/手工编辑 profile 的 pnpm-lock.yaml：由 pnpm 重建；手工改会导致解析错乱。

  • 凭据不进仓库：远端推送用系统凭据助手（git credential fill），仓库内不写 token。

六、百科（wiki）本身的维护

百科源文件版本化在仓库 docs/wiki/，通过脚本推送到 Gitea wiki：

bash scripts/push-wiki.sh            # 推送/更新全部页面（幂等：有则 PATCH，无则 POST）
bash scripts/push-wiki.sh 05-运维手册 # 只推一页

凭据来自 git credential fill（与推送代码同一套，不落盘）。修改文档的推荐流程： 改 docs/wiki/*.md → 提交到仓库 → 跑脚本推送，这样 wiki 与代码同源可回溯。

七、诊断与日志

信号 含义 位置
左下角红色诊断条 [dsh-apes-sidebar] <phase> error: … client 生命周期某阶段抛错（mount / native / 懒加载等） 页面左下角（z-index: 2147483000），同时 console.error 打前缀
控制台 [dsh-apes-sidebar] … 同上，且带上具体阶段名 开发者工具 Console
「插件像没装」且无任何日志 宿主兼容性预检失败（peer 不匹配）→ 静默禁用 只能靠版本矩阵排查，见 06-故障排查 §1
界面正常但面板层级错乱 面板宿主挂载点/层叠上下文问题 见 02-系统架构 §四

八、性能与容量

项 观察值 说明
lib/client.js ≈ 0.9 MB 主 bundle，始终加载
lib/client-mermaid.js ≈ 7 MB（+12 MB map） 懒加载，仅在需要渲染 Mermaid 时拉取
lib/client-editor.js ≈ 2 MB 懒加载，仅打开编辑器时
lib/client-terminal.js ≈ 0.5 MB 懒加载，仅打开终端时
全量测试 约 3–4 分钟 变更后按需跑全量，日常可只跑相关 spec

主 bundle 不应静态引入上述重型库；新增重型依赖一律走 src/client/chunks/（懒加载 chunk）。

Reference in New Issue View Git Blame Copy Permalink