# 观澜 · 如东样板 v2 — 离线应用 使用说明书 v0.2 (2026-09-08)

> v0.2 变更: 支持 **国产化 Linux** (银河麒麟 V10 / 统信 UOS 20, x86_64 与 aarch64) · **Ollama 离线安装** · **Python 多版本机器可指定, 无 3.11+ 时用包内便携运行时** · 修 xzy 测试报告 5 条 (tzdata / 数据路径 / 主轴承跳转 / 报警台数口径 / 报告章节跳转) · 中文表达按 OEM 术语基准替换。

## 1. 这是什么
一套**纯离线**的风电场数据分析应用 (如东海上风电场, 西门子 SWT-4.0-130, 38 台): 把运行数据、状态监测、报警、工单、油样落到每台机组的正确部件上, 给出带证据、带边界、带责任人的检修结论; **判断在代码里, 本机模型只负责问答、解释与引用, 不发明结论**。软件不含任何联网功能。

包内七个模块 (统一入口 `http://127.0.0.1:28084/`):
| 路径 | 模块 | 用途 |
|---|---|---|
| `/` | 中文门户 | 总览 / 系统架构 / 方法 / 经验发现 / 案例 / 文档 (含治理清单) |
| `/detail/` | 综合详细分析工作台 | 系统矩阵、检修助手、问答区、汇报纸 (含结构化事实契约) |
| `/cms/` | CMS 振动诊断 | 六层振动模型逐台判读 |
| `/sim/` `/sim/sys/` | 仿真与回放 · 四系统合页 | 液压等系统仿真台 (案例判据标定用) |
| `/viewer/` | 三维拆装工作台 | 部件层级三维 |
| `/release/r1` `/release/r2` | Release 层 (只读) | 契约生 Verdict / 老结论分层 |
| `/healthz` `/api/version` | 自检 | 模块状态、指纹 |

## 2. 系统要求
| 项 | 最低 | 推荐 |
|---|---|---|
| 系统 | Windows 10 64 位 · **银河麒麟 V10** · **统信 UOS 20** · Ubuntu 20.04+ · CentOS 8+ | Windows 11 / 麒麟 V10 SP3 |
| 架构 | x86_64 | x86_64 或 aarch64 (两套离线轮子都在包内) |
| Python | 3.11+ ; **机器上没有也行** —— 包内带便携运行时 3.12.14 (麒麟/统信自带多为 3.7/3.9, 跑不了本项目依赖) | 3.12.x |
| 内存 | 16 GB | 32 GB |
| 磁盘 | 5 GB + 三维资产 1 GB | 另加模型 30–60 GB (SSD) |
| 显卡 (只影响问答/本地审核) | 无 (CPU 慢档, 首答 30–60 s) | NVIDIA ≥ 12 GB; ≥ 24 GB 可开 27B 升档 |
| Ollama | 可选; 离线安装包在 `vendor/ollama/` (Windows 1.5 GB / Linux 1.4 GB, **单独交付不在主包**) | 同左 |
安装目录不要带空格和中文 (例 `D:\guanlan\app` 或 `/opt/guanlan`)。

## 3. 安装 (首次, 约 10 分钟)
### 3.1 Windows
1. 解压 `..._program.zip` 到 `D:\guanlan\app`; 再解压 `..._viewer.zip` (得 `release\viewer\`)、`..._deliverables.zip` (得 `release\如东\`)。
2. 双击 **`install.bat`** (或 `powershell -ExecutionPolicy Bypass -File install.ps1`)。脚本会:
   列出机器上所有 Python 并选 ≥3.11 → 没有就解包内便携运行时 → 建 `.venv` → 从 `wheels\win_amd64` **离线**装依赖 → 写配置 → 装 Ollama (若 `vendor\ollama\OllamaSetup.exe` 在位, 静默安装) → 自检。
   - 多版本机器指定: `install.ps1 -Python "C:\Python312\python.exe"`
   - 强制用包内运行时: `install.ps1 -UseBundledPython`
   - 跳过 Ollama: `install.ps1 -SkipOllama`
3. 双击 `check.bat` 全绿 → `start.bat`。

### 3.2 银河麒麟 / 统信 UOS / 其它 Linux
```bash
tar 或 unzip 解包到 /opt/guanlan     # 目录不要带空格与中文
cd /opt/guanlan && sh install.sh      # 自动识别发行版与架构, 选 Python, 离线装依赖
# 多版本机器指定: GUANLAN_PY=/usr/bin/python3.11 sh install.sh
.venv/bin/python guanlan.py serve     # 启动; 停止用 ... stop
```
`install.sh` 找不到 3.11+ 时自动解包内便携运行时 (`vendor/python/cpython-3.12*-<架构>-*.tar.gz`), 不需要联网、不需要编译。
Ollama (可选): 包内有 `vendor/ollama/ollama-linux-amd64.tar.zst` 时
```bash
sudo tar -I zstd -C /usr -xf vendor/ollama/ollama-linux-amd64.tar.zst
sudo useradd -r -s /bin/false -m -d /usr/share/ollama ollama    # 已有则跳过
ollama serve &
```
麒麟/统信若无 zstd: `sudo yum install zstd` 或 `sudo apt install zstd`。

### 3.3 模型 (离线)
在**有网**机器上 `ollama pull qwen3:8b deepseek-r1:14b bge-m3` (显存 ≥24 GB 再 `qwen3.8:27b`), 然后把整个模型目录拷到内网机同位置:
- Windows `%USERPROFILE%\.ollama\models` · Linux `/usr/share/ollama/.ollama/models` 或 `~/.ollama/models`
拷完 `ollama list` 能看到模型即可。**没有模型时问答不可用, 其余页面照常。**

### 3.4 离线件怎么来的 (维护方用)
在有网机器上: `python scripts/fetch_offline_deps.py all --targets win_amd64,linux_x86_64,linux_aarch64`
下载各平台轮子 + 便携 Python + Ollama 安装包, 校验值写进 `vendor/MANIFEST.json`。

## 4. 日常使用
- **启动**: 双击 `start.bat` (约 10–30 s, 自动打开浏览器到 `http://127.0.0.1:28084/`)。
- **停止**: 双击 `stop.bat`。
- **自检**: 双击 `check.bat` (Python/依赖/数据/发布件/端口/模型/模型可用性检查)。
- **状态**: 终端里 `.venv\Scripts\python.exe guanlan.py status`。
- 所有服务只监听本机 (127.0.0.1); 局域网他人访问需要另行配置, 本版不开。

### 4.1 门户与工作台怎么看
- 门户每页首屏一句话; "经验发现" 与 "案例" 页的每条结论旁有三枚标签: **证据级** (定论 / 准定论·预警 / 候选 / 参考 / 数据不足 / 撤回)、**审级**、**处置措施** (谁、什么时候、做什么)。候选不进业主正文。
- 工作台 `/detail/`: 系统矩阵 (38 台 × 九系统判级) → 点台号看证据窗; 检修助手 (检修四链); **问答区**: 选模型 (默认 8B; 复杂问题会自动升档到 27B 并在尾注标明), 回答后自动附"结构化事实契约"引文块; 引不到契约条时会明写"未被契约背书"。汇报纸可导出。
- `/cms/`: 每台机组六层判读, 机制未定不点零件。
- **运维控制台** (2026-09-12 新增; 2026-09-16 起菜单入口为门户「**数据重算**」): 停/启服务 · 执行重算 · 清除产物 —— 一个按钮一件事。
  按钮按**真实状态**启用 (不能做的动作是灰的; 后端同样校验并返回 409, 直接打 API 也绕不过);
  "启动服务"起来后会自动打开门户; "停止组件服务"**保留控制台本身**(否则点完页面就没了);
  "清除产物"是**直接删除、不留备份**(2026-09-16 用户令; 要随包件用
  `scripts\products_restore_missing.py --stash <交付包.zip>` 从交付包补齐), 不动 `data\raw\`。
  页面同时显示各服务端口状态、产物件数、逐件来源台账、验收锚点, 以及当前任务的进度/退出码/日志尾巴。

### 4.2 问答的可信边界
- 台号与数字必须能回抓到源记录, 回抓不到的句子被校闸拦下并提示; 两档模型都拦则**不出文并给原因** (不会硬编)。
- 模型只转述本体与契约, 不产生新判级; 答案里出现的判级词都来自契约。
- 模型未启动或崩溃时页面提示"本机模型未启动"(HTTP 503), **不会静默改用别的来源**。

## 5. 离线模型
| 档 | 模型 | 用途 | 显存 |
|---|---|---|---|
| 默认问答 | qwen3:8b | 所有提问首选 | ≥ 6 GB (CPU 可跑, 慢) |
| 升档 | qwen3.8:27b | 8B 校闸没过时自动重答一次 | ≥ 20 GB |
| 审核票 | deepseek-r1:14b (+ 27B 第二票) | 交叉审核初筛 (**离线审级**, 非独立审级) | ≥ 10 GB |
| 检索 | bge-m3 | 向量检索 | 2 GB |
配置在 `configs\models.json`; 换模型 = 改这里 + `ollama pull`, 不改任何结论。
**模型闸** (`src\ontology\llm_gate.py`) 对每次调用: 固定随机种子与温度 (同问同证据同答) · 同一时刻只一个生成请求 · 瞬断自动重试一次 · 连续 3 次失败熔断 60 s 并明示 · 每次调用写审计日志 `logs\llm_audit.jsonl` (模型摘要、提示指纹、参数、耗时、输出指纹)。
**已知答案回放**: 服务运行中执行 `.venv\Scripts\python.exe guanlan.py qa --n 6 --budget 300`, 六道固定问题必须出文、引用期望结论编号、校闸全过、在预算内 → 结果在 `logs\known_answer_*.json`。换模型或升级后**必跑**。

## 6. 目录结构
```
D:\guanlan\app\
  guanlan.py            启动器 (check / serve / status / stop / open / qa)
  start.bat stop.bat check.bat install.ps1
  configs\serve.json    端口、发布目录、Python 路径
  configs\models.json   模型档
  configs\{farms,contracts,canonical}\   场配置、数据契约、canonical 字典
  src\                  分析代码 (windscada / windcms / ontology / sop)
  scripts\              服务与工具脚本
  outputs\rudong\       如东产物: windscada (parquet) / ontology (本体) / sop (findings) / guanlan (事实契约) / windcms / m5_cms_tcm
  release\              门户 portal.html / 仿真服务 / viewer 三维资产 / 如东 治理清单交付件
  resources\            仿真回放资产
  wheels\win_amd64\     离线依赖轮子
  logs\  run\           日志 (各服务 + 模型审计) / 运行时 pid
  docs\                 本说明书、系统设计与样板、系统工程意见
```

## 7. 配置
- **端口**: `configs\serve.json`。注意 v0.1 里网关的上游端口表 (`scripts\guanlan_gateway.py` ROUTES) 仍是硬编码, 改端口须两处同步 (v0.2 合并)。
- **数据目录**: 本版程序与数据在同一目录; 升级时按 §8 备份 `outputs\` 与 `release\`。
- **编码**: 启动器与批处理已设 `PYTHONUTF8=1`; 若终端显示乱码, 先 `chcp 65001`。

## 8. 每期数据分析与升级
- ~~本版 (v0.1) 包内**不含**从原始 SCADA 重生成产物的链~~ → **2026-09-12 更新: 重算链已进包**。
  一条命令: `.venv\Scripts\python.exe scripts\rebuild_all.py` (含 SCADA 侧 10 个构建器, 逐台读 ~14 GB, 约 15 分钟;
  只换了台账类数据时加 `--skip-scada`, 约 2 分钟); 等价操作: 运维控制台 `/ops` → "执行重算"。
  链路: 放数据 → 三门台账 → 月度派生件 → 补齐缺件 → 本体(码表/铺开/决策链/趋势/检索/参数表) → 本体审计,
  并自动重启组件服务 (网关保留, 所以控制台页面不会断)。
  两条**必须如实知道的边界**: ① 随包里有一批产物**没有生成端** (如 `pitch_daily`、`pc_monthly_bins`、
  CMS/TCM 兼容链), 重算后再由随包件补齐 —— 每件的来源逐条记在 `outputs\rudong\_provenance.json`
  (`raw-derived` = 由 `data\raw` 重算 / `shipped` = 用随包件补齐); ② 补齐后某页仍无数据,
  看 `docs\重算缺口与补件清单_v0.1.md` (哪件缺 · 卡住哪个页面 · 找谁补 · 补齐判据)。
- 新一期数据的分析仍可由维护方 (Claude + 工程师) 在分析机上执行, 以**更新包**交付: 包含新的
  `outputs\rudong\` 与 `release\` 及变化摘要、审级件、人裁记录。有了重算链, 现场换数据也可自行重算,
  步骤与验收见 `docs\重算操作手册_v0.1.md` (§0 一条命令 · §0b 控制台 · §5b 清产物/恢复)。
- **应用更新包**: `stop.bat` → 把当前 `outputs\` 与 `release\` 整目录复制到 `D:\guanlan\backup\<日期>\` → 解压更新包覆盖 → `check.bat` → `start.bat` → 打开 `/api/version` 核对指纹与更新说明一致。
- **程序升级**: 同上, 先备份再覆盖程序文件; 数据不动; 升级后必跑 `check.bat` 与 `guanlan.py qa`。回滚 = 用备份目录覆盖回去。
- 每期出门前的审级 (离线): 本地两票初筛 + 工程师审; 确诊与含经济数字的结论额外要求数据回抓、两票一致、签字。

## 9. 常见故障
| 现象 | 原因 | 处理 |
|---|---|---|
| `start.bat` 报端口占用 | 别的程序占了 28084/18033/18020/18791/18792/64292 | `stop.bat` 后重试; 仍占则改 `configs\serve.json` (见 §7) |
| 页面显示"本机模型未启动" / 问答 503 | Ollama 没起或模型没拉 | 开始菜单启动 Ollama; `ollama list` 确认模型; `check.bat` |
| 问答很慢 (> 1 min) | CPU 档或显存不足 | 看 `check.bat` 的探针耗时; 显存 < 12 GB 时只用 8B, 关掉升档 (models.json profiles) |
| 治理清单页 not found | `release\如东\` 未解压 | 解压 `_deliverables.zip` 到程序目录 |
| 三维页空白 | `release\viewer\` 未解压 | 解压 `_viewer.zip` |
| 中文乱码 | 终端编码 | `chcp 65001`; 启动器已强制 UTF-8 |
| 杀毒软件拦截 | 嵌入 Python 或 Ollama 被误报 | 把 `D:\guanlan` 加入信任目录 |
| 服务起了页面打不开 | 浏览器代理把 127.0.0.1 也走代理 | 浏览器代理例外加 `127.0.0.1` |
日志: `logs\gateway.log` `logs\detail.log` `logs\cms.log` … ; 模型调用: `logs\llm_audit.jsonl`。

## 10. 版本与校验
- 版本号在 `VERSION`; 包内 `SHA256SUMS.txt` 列出三个 zip 的校验值, 解压前请核对 (`certutil -hashfile <文件> SHA256`)。
- `http://127.0.0.1:28084/api/version` 显示代码指纹、门户指纹、事实契约条数与 sha。

## 11. 已知限制 (v0.1, 如实)
- 本版打包与验证在 macOS 分析机上完成 (同一套 Python 代码, 启动器与安装逻辑为跨平台); **Windows 与国产化 Linux 的首装尚未在真实目标机上跑过** —— 首装时请把 `check.bat` / `install.sh` 的输出反馈给维护方。
- Ollama 离线包体积 1.4–1.6 GB, **不在主程序包内**, 单独交付 (或用 `scripts/fetch_offline_deps.py` 自取)。
- 工作台服务是单文件大程序 (5,000 行), 计划 P2 拆分; 不影响使用。
- 不含从原始数据重生成产物的链 (P0); 不含训练回路。
- 问答复杂题 (逐台列举类) 在 27B 升档下可能需要 5–15 分钟。