figmar
63bcb47ed0
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 线。
134 lines
6.9 KiB
Markdown
134 lines
6.9 KiB
Markdown
# 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：某次提交引入回归（单点回退）
|
||
|
||
```bash
|
||
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：整条线回退（例如新线在真机上不可用）
|
||
|
||
```bash
|
||
git checkout main # 或 backup/pre-sync-v0.24.1
|
||
pnpm install && pnpm build
|
||
cd ~/.dsh/profiles/<profile> && pnpm install
|
||
# ⌘Q 重启
|
||
```
|
||
|
||
### 场景 C：profile 依赖/config 被改坏
|
||
|
||
```bash
|
||
cd ~/.dsh/profiles/<profile>
|
||
cp package.json package.json.bak.$(date +%s) # 先备份
|
||
bash <插件仓库>/scripts/switch.sh aps # 或 upstream，脚本会重写依赖与 bundle 行
|
||
pnpm install
|
||
# ⌘Q 重启
|
||
```
|
||
|
||
**回滚验收**：重启后按 [04-部署指南](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-部署指南](04-部署指南) §1.1（不匹配 = 静默禁用） |
|
||
| 每月/大改前 | 锚点是否已推远端 | `git ls-remote <remote> \| grep -E 'heads/(main\|sync)\|tags/apes'` |
|
||
| 异常时 | 诊断条与控制台 | 页面左下角红条；控制台 `[dsh-apes-sidebar]` 前缀 |
|
||
|
||
## 五、备份与配置铁律
|
||
|
||
- **改任何 profile 配置前先备份**，改完**回读验证**（不要假定写入即生效）：
|
||
|
||
```bash
|
||
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 会启动进**恢复模式**。
|
||
改完务必回读校验类型：
|
||
|
||
```bash
|
||
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
|
||
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-故障排查](06-故障排查) §1 |
|
||
| 界面正常但面板层级错乱 | 面板宿主挂载点/层叠上下文问题 | 见 [02-系统架构](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）。
|