guanlan-src

观澜·如东样板 v2 0.4.0 — 单包全量离线应用 (Windows / Linux / macOS)

= Windows 的 .venv\Scripts\python.exe, 或 Linux·macOS 的 .venv/bin/python;

   命令里路径写 / 即可两平台通用; Windows 也可以只双击 .bat, 不必敲命令。

★ 本包不含 输入数据(data/) · 产物/输出数据(outputs/) · 运行日志(logs/、run/、任何 .log/.jsonl) · 临时文件(缓存/备份/系统索引)(用户令 2026-09-17; 打包方法与逐条理由见第五节): 解压安装后页面会显示"无产物"; 把现场数据包放好后跑一次重算(第四节), 页面立刻有数。 随包内容 = 程序/配置/门户与三维资产/交付文档/离线依赖轮子/便携运行时 (没有数据、产物、日志)。

一、安装 (约 10 分钟; 安装目录不要有空格和中文) Windows : 解压到 D:\guanlan\app → 双击 install.bat (自动选 Python → 建 .venv → 包内轮子离线装依赖) Linux : 解压到 /opt/guanlan → sh install.sh (麒麟 V10 / 统信 UOS 20 / Ubuntu / CentOS / macOS;

                                                        多版本机器: GUANLAN_PY=/usr/bin/python3.11 sh install.sh)

没装 Python 的机器也能装: 包内有便携运行时(Windows / Linux x86_64 / Linux aarch64), 安装脚本自动用。 离线边界: Windows 侧包内带全部轮子, 完全离线可装; Linux·macOS 侧包内没带轮子, install.sh 会自动 改为联网安装 —— 要离线装就把对应平台轮子放进 wheels/linux_x86_64 或 wheels/macos_arm64 再装。 模型(可选, 只影响问答与本地审核页): ollama pull qwen3:8b / deepseek-r1:14b / bge-m3

二、启动 / 停止 Windows : 双击 check.bat 全绿 → 双击「启动观澜」快捷方式(安装时自动建: 根目录 + 桌面各一份;

        同一目标还有一份 ASCII 名的 start_guanlan.lnk 供控制台/脚本引用;
        目标 = .venv\Scripts\pythonw.exe, **完全不出现命令窗口**) 或双击 start.bat
        (会闪一下窗口 —— .bat 是控制台程序, 想完全无窗就用上面那个快捷方式)   停止: 双击 stop.bat

Linux : guanlan.py check → guanlan.py serve 停止: guanlan.py stop 三个入口: 门户 http://127.0.0.1:28084/ · 工作台 /detail/ · 运维控制台 /ops 排障要看见实时日志: 双击 start.bat console (前台模式, 关窗即停服务); 本包不含 VBScript, 无窗口启动不依赖 Windows 脚本宿主(WSH 被策略禁用的服务器上同样可用)。 ★ .bat 一律纯 ASCII(英文): 中文写进批处理会随控制台代码页被曲解, 现场出现过"注释被当命令执行"。

中文说明请看本文件与 docs/; 机器守卫见 src/entry_refs.py(guanlan.py check 会报一行)。

三、重算与产物 (门户菜单「数据重算」, 或直接开 http://127.0.0.1:28084/ops) 一个按钮一件事: 停/启服务 · 执行重算 · 清除产物。按钮按真实状态启用(不能做的灰, 后端也拒绝, 直接打 API 返回 409); "启动服务"起来后自动打开门户; "停止组件服务"保留控制台本身; 同时刻只允许 一个动作, 页面上有进度/退出码/实时日志尾巴。重算进行中按钮按设计禁用 —— 那不是坏了。 ★ 清除产物 = 直接删除, 不留备份(用户令 2026-09-16; 旧的 --on 还原已移除), 不动 data/raw、release;

要补回"包内没有生成端"的随包件: <PY> scripts/products_restore_missing.py --stash <交付包.zip>

★ 清完产物后页面会显示"无产物"(工作台左栏/CMS 页都会给出"缺哪件、怎么补"的说明, 不会崩) ——

跑一次第四节的重算即恢复; 若某页仍打不开, 先看 /healthz 与 logs/<组件>.log 尾部。

四、放数据后重算 (一条命令; 控制台点"执行重算"等价) scripts/raw_data_check.py --src <现场包目录> ★ 先体检: 结构/命名/增量(新增·跳过·冲突) + 放置指导 scripts/place_raw_data.py --src <现场包目录> --scope full 放数据(同尺寸自动跳过, 可反复跑;

   落位前自动跑体检, "同名不同大小"的冲突会拦下, 确要覆盖加 --force)

scripts/rebuild_all.py [--skip-scada] [--src <现场包目录>] 默认含 SCADA 侧约 15 分钟;

   只换台账类数据加 --skip-scada(约 2 分钟); --dry-run 只看计划; 完事自动重启组件服务。

放置规范与常见错误: docs/输入数据放置指导_v0.1.md (目录树/命名/增量语义/放完跑什么) 算成功判据: /detail/ 左栏「系统维护」两屏, 或 -m src.ontology.maintenance 重算后应达锚点: 报警 39211 · 工单 5876 · 油样 404 · temp_monthly 19494 · 本体 9702 对象(审计 0 问题)

五、打包 (做交付包; 用户令 2026-09-17) 一条命令就够(不需要任何开关); Windows 也可以直接双击 pack.bat:

Windows : 双击 pack.bat            或  <PY> scripts/pack_dist.py
Linux   : sh pack.sh               或  <PY> scripts/pack_dist.py
pack.bat dry      只预演: 报表里会打什么、多大, 以及逐条排除理由(不写文件)
pack.bat verify   对已打好的 zip 做开箱验证: 解压 → 离线安装 → 起服务核验页面 → 清理
<PY> scripts/pack_dist.py --out <目标.zip>     指定输出路径

输出: 默认写到安装目录的上一级, 文件名 guanlan-v<版本>dist<日期>.zip

    (例: 装到 D:\guanlan\app, 则产物在 D:\guanlan\guanlan-v0.4.0_dist_20260917.zip)

★ 包里不含这四类(默认口径; 每条理由都写进包内 dist-manifest.json):

① 输入数据     data/                    现场原始件; 例外要带用 --with-data (约 31 GB)
② 产物/输出数据 outputs/                 目标机放数据后 place_raw_data.py + rebuild_all.py 重算;
                                        无生成端的那批用 products_restore_missing.py --stash <交付包.zip>
③ 运行日志     logs/ run/ 以及**任何位置**的 *.log、*.jsonl (含 logs/build、logs/legacy)
④ 临时文件     各种缓存(*_cache、__pycache__、.pytest_cache、.npm-cache、.qa-profile)、
               编辑器临时与备份(*.tmp *.bak* *.old *.orig *.rej *.swp *~ ~$*)、
               系统索引(.DS_Store、Thumbs.db、desktop.ini), 以及 .git/.venv/*.pyc/*.lnk/顶层 *.zip

包里有: src/ scripts/ guanlan.py · configs/ · release/(门户/仿真/三维/交付件) · resources/ · reference/ ·

         docs/ · README 与 测试须知 · wheels/ · vendor/ · install/check/start/stop/pack 脚本 · requirements.txt

打完自查: 包内 dist-manifest.json 记着 version / no_data / no_products / no_logs / no_temp + 逐条排除理由;

        打包器自己还会核"入口脚本引用的文件都在包里"与"入口脚本编码守则", 不合格的包会被删掉并返回非 0。

要让页面开箱即有数(例外做法): scripts/pack_dist.py --with-products

六、必读 (如实) · 页面的数来自 outputs/<场站> 下的产物, 产物由 data/raw 下的原始件算出来(下一级目录名=场站名, 扫描辨识)。

本包两样都没带: 没有 data/raw 时重算会"没有源件可算", 没有 outputs/ 时页面显示"无产物"。

· 有一批产物没有生成端(pitch_daily、pc_monthly_bins、CMS/TCM 链等): 从交付包按需补齐

(products_restore_missing.py --stash <交付包.zip>), 补齐后逐件来源见 outputs/<场站>/_provenance.json。

· 某页没数据: 先看控制台的退出码与 logs/, 再看 docs/重算缺口与补件清单_v0.1.md。

包内含: 程序与配置 / 门户与仿真 / 三维资产 release/viewer / 治理清单交付件 release/如东(客户交付物勿外传) /

    离线依赖轮子 wheels/ / 便携运行时 vendor/ / 交付文档 docs/ / 打包脚本 pack.bat · pack.sh

包内不含: data/(输入数据) · outputs/(产物) · logs/ run/(运行日志) · 临时文件与缓存 ·

      .venv(安装时重建) · .git(版本库)

详细说明: docs/系统设计说明.md(§9 交付包组成 · §11 配置与日志口径) · docs/重算操作手册_v0.1.md

      docs/数据目录结构与落位约定_v0.2.md · docs/重算缺口与补件清单_v0.1.md
      docs/输入数据放置指导_v0.1.md · docs/振动数据接入_v0.1.md · docs/说明书_观澜如东样板v2_v0.2.md

七、服务化 (装成 Windows 服务 / systemd; 用户令 2026-09-17) Windows (管理员 PowerShell): scripts/service_ctl.py install 注册为 Windows 服务(开机自起)

                            <PY> scripts/service_ctl.py install --dry-run  先看它要做什么(免管理员)
                            不想提权: <PY> scripts/service_ctl.py install --user-login   登录后自启

Linux (root): sudo scripts/service_ctl.py install 写 guanlan.service + systemctl enable --now 起停状态: scripts/service_ctl.py status|start|stop|restart|uninstall 装了服务就不必再双击快捷方式; 手工启动(start.bat / guanlan.py serve)仍然可用, 两者互不冲突。 ★ 安装时会先检查是否已安装及版本: 读 <安装目录>/install-info.json 与本包版本比较,

同版本/升级/降级/老安装无版本记录 四类都会提示并询问是否重装;
跳过询问用 install.bat -Force (Linux: sh install.sh --force)。版本单一真源 = src/version.py。