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 ★ 别的机器怎么打开 (用户令 2026-09-19「观澜改为监听所有 IP」): 出厂已是 this 口径 ——

configs/serve.json 的 "public_host": "0.0.0.0" ⇒ 门户网关绑所有网卡, 别的机器开
http://<本机IP>:28084/ 。**只有门户网关**对外, 组件(detail/cms/viewer/sim)仍绑 127.0.0.1。
Windows 还要放行入站端口: netsh advfirewall firewall add rule name=guanlan28084 dir=in action=allow protocol=TCP localport=28084
只给本机用就把它改回 ""(跟 host) 或 "127.0.0.1"; 也可以填某个内网 IP 只放那一个地址。改完重启服务。
★★ 页面**没有鉴权** ⇒ 对外监听等于把全场运行数据摊开。请同时限来源 (防火墙只放自己的 IP / 反代加认证),
   不要直接挂公网; 只给运维看时更稳的是 public_host 留空 + SSH 隧道
   (ssh -L 28084:127.0.0.1:28084 <user>@<服务器>) —— 启动日志里每次都会提醒这一条。

★ 无人值守/远程部署: 用 Windows 服务(开机自启 + 崩溃自动重启):

(管理员) <PY> scripts\service_ctl.py install        服务名 = guanlan (显示名「观澜·如东样板 v2 …」)
查状态: sc query guanlan   ·   Linux 对应 systemd 单元 guanlan.service
★ 反面教材(2026-09-19 实逮): 用 SSH 会话里跑 <PY> guanlan.py serve 起的服务, **会话断开就被一起收掉**
  (SSH 作业对象随会话结束终止子进程) ⇒ 远程部署一律用服务, 别用 SSH 前台起。

排障要看见实时日志: 双击 start.bat console (前台模式, 关窗即停服务); 本包不含 VBScript, 无窗口启动不依赖 Windows 脚本宿主(WSH 被策略禁用的服务器上同样可用)。 ★ .bat 一律纯 ASCII(英文): 中文写进批处理会随控制台代码页被曲解, 现场出现过"注释被当命令执行"。

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

三、重算与产物 (门户菜单「数据重算」, 或直接开 http://127.0.0.1:28084/ops) ★ 输入数据自动扫描识别 (用户令 2026-09-19): data/raw 下逐族指纹 (件数/体积/最新时间/清单摘要),

与上次快照比 —— 有新增/变化就报出来并列出"该跑哪几步":
  <PY> scripts/raw_scan.py                 # 看当前状态
  <PY> scripts/raw_scan.py --check         # 与快照比: rc=0 无变化 · rc=4 有新数据 · rc=5 还没基线
  <PY> scripts/raw_scan.py --write         # 记/更新基线 (重算链第 ①b 步每次都会顺手记)
→ 重算链里它就是 **①b 步**; 想让"新数据不被 --skip-* 漏掉", 用:
  <PY> scripts/rebuild_all.py --auto       # 先扫一遍: 新数据落在被跳过的族里就自动取消跳过
→ 服务侧看门狗 (默认关, 现场自己开): configs/serve.json 的 "raw_watch"
  {"enabled": true, "minutes": 30, "auto_rebuild": false}
  开了以后每 30 分钟扫一次, 有新数据就写 logs/service.log 并列出该跑的步; auto_rebuild=true 时
  顺手发起一次重算 (与运维控制台同一条路; 已在跑则不重复发起)。

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

要补回"包内没有生成端"的随包件: **运行期不由交付包补齐**(用户令 2026-09-17) —— 放原始件后重跑重算, 或由研发补生成端(逐族可逆性见 docs §13.6); 仅离线人工补救时可用 <PY> scripts/products_restore_missing.py --stash <…>

★ 清完产物后页面会显示"无产物"(工作台左栏/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>     指定输出路径

输出: 默认写到安装目录的上一级, 文件名 app_guanlang_v<版本号>.zip

    (例: 装到 D:\guanlan\app 且本包版本 2.6.0, 则产物在 D:\guanlan\app_guanlang_v2.6.0.zip)

★ 版本号规则 (用户令 2026-09-17): 编号 v<大版本号>.<中版本号>.<小版本号>, 例 v2.5.0

  大版本号 —— 系统解决方案、架构或核心功能改变
  中版本号 —— 非核心功能新增、减少、修改
  小版本号 —— 消缺完善
版本号只写在 src/version.py 一行(VERSION), 打包器/安装脚本/安装记录/自检都读它;
改完跑 <PY> scripts/version_log.py --write 让 docs/版本记录.md 跟上(自检会校验两者一致);
看当前版本与规则: <PY> guanlan.py version

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

① 输入数据     data/                    现场原始件; 例外要带用 --with-data (约 31 GB)
② 产物/输出数据 outputs/                 目标机放数据后 place_raw_data.py + rebuild_all.py 重算;
                                        无生成端的那批**运行期不从交付包补**(用户令 2026-09-17), 由研发补生成端(docs §13.6)
③ 运行日志     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/uninstall 脚本 · 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 链等): 从交付包按需补齐

(**运行期不从交付包补**: 放原始件后重算; 缺生成端的族由研发补, 见 docs §13.6), 逐件来源见 outputs/<场站>/_provenance.json。

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

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

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

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

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

七、服务化 (装成 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。

八、卸载 (用户令 2026-09-17) Windows : 双击 uninstall.bat Linux / macOS : sh uninstall.sh 带开关的用法 (两种平台一样):

--dry-run      只打印"将要做什么", 一个字节都不动 (先看这个最稳妥)
--yes          不再询问, 直接执行 (脚本/无人值守用)
--purge        连 数据/产物/日志/虚拟环境 一起删 (会再问一次; 加 --keep-logs 保留日志)
--all          连程序本体一起删 (删不掉的逐条列出, 并给一条收尾命令)
--selftest     自检: 六个步骤齐全 + dry-run 无副作用

默认只拆"本程序装上去的东西", 顺序是:

① 停服务(服务化常驻体 + 手工启动的组件)  ② 注销服务(sc.exe delete / systemctl disable; 需管理员/root)
③ 撤开机自启(登录自启项)  ④ 删快捷方式(启动观澜.lnk / start_guanlan.lnk, 含桌面)
⑤ 清运行态(run/、*.pid)  ⑥ 删安装记录 install-info.json (删掉它 = 这台机器回到"没装过")

★ 默认保留: data/(输入数据) · outputs/(产物) · logs/ · .venv/ · 整棵程序目录。

卸载程序 ≠ 销毁数据; 要连数据一起清, 显式给 --purge。

★ 程序目录不自己删(Windows 上正在跑的 python.exe 就在 .venv 里, 删自己必然只删一半):

要清干净用 --all, 或卸载完直接删目录 `rmdir /s /q <安装目录>`。

免管理员也能卸: 服务注销那一步缺权限时照做其余步骤, 并打印你该手工执行的那两条命令。

详细说明: docs/系统设计说明.md(§9 交付包组成 · §11 配置与日志口径 · §14 服务化与卸载 · §15 版本管理与打包命名)

      docs/版本记录.md(版本号规则与版本表) · 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