PHAST-SAFETI二次开发教程（02）：环境与许可——安装、Veracity 授权、Knowledge Centre 与版本档案
版本声明块
- 工具与软件：Phast™ 与 Safeti™ 的版本主线为 9.x；历史锚点版本为 8.4（64 位架构）、8.6（CFD 池火）、8.7（CFD 射流火）与 8.x（埋地管道、火球）。具体版本号一律以官方 Knowledge Centre 的发布说明为准。
- 语言与环境：官方 Python 库 PyPWS 要求 Python 3.11 及以上；官方 API 客户端形态为 Excel、Python、.NET 与 TypeScript 四种。
- 本文目标：把"装得上、授权通、版本对得上、令牌管得住"这四件事一次做对，并交付一套可复用的环境自检脚本。
一句话结论：二次开发的环境地基由四块砖构成——安装介质与发布说明统一走官方 Knowledge Centre，商用授权走 Veracity 商店（按 Individual 或 Network 形态、以订阅、租赁或永久方式购买），Phast API 调用依赖官方发放的访问令牌，而所有版本号必须落进你的项目档案并以官方发布说明为唯一判据；这四件事各有对应的自检动作，任何一块含糊都会在后续脚本里变成难查的故障。
〇、本篇要解决的认知问题
- Q1：Phast™ 与 Safeti™ 的许可形态有哪些？为什么安装前必须先问清授权类型？
- Q2：软件从哪买、从哪下、发布说明在哪看？为什么"客户门户"这个词现在不该再用？
- Q3：Phast API 一定要访问令牌吗？令牌应该怎么放、怎么轮换？
- Q4：为什么本系列反复强调"版本先声明"？版本档案在项目里具体长什么样？
- Q5：除了文档，官方还有哪些可以学的资源（培训、网络研讨会、用户会议）？
一、机制解析
1.1 许可形态：先问清"谁的许可、怎么算钱"
Phast™ 与 Safeti™ 是商业闭源软件，任何二次开发都建立在合法授权之上。授权决策要回答三个正交问题：
| 问题 | 常见选项 | 对二次开发的影响 |
|---|---|---|
| 授权对象 | Individual（单机绑定） | 脚本运行的那台机器必须是授权机器 |
| 授权对象 | Network（网络浮动） | 多台机器/CI 节点可竞争使用许可，适合批处理农场 |
| 付费模式 | 订阅 / 租赁 / 永久 | 决定你的自动化流水线能持续多久、续期节奏如何 |
| 授权期限 | 短至 1 天、长至 3 年 | 短期授权适合培训与冲刺项目，不宜承载长期流水线 |
为什么必须先问清：这直接决定架构。若你规划一个跑在服务器上的批量流水线，却只买了 Individual 单机授权，脚本在服务器上会因找不到授权而失败——这不是代码问题，是授权形态问题，改代码永远改不好。
1.2 渠道：Veracity 商店与 Knowledge Centre 各管什么
官方把"交易"和"资料"分成了两处，务必分清：
| 事务 | 官方入口 | 说明 |
|---|---|---|
| 购买/订阅/续期 | Veracity 商店（如 https://store.veracity.com/phast） | 商业交易与授权凭证 |
| 安装介质下载 | Knowledge Centre 软件下载页 | 官方安装包 |
| 发布说明 | Knowledge Centre 发布说明页 | 版本变更的唯一权威判据 |
| 技术文档与用户手册 | Knowledge Centre 技术文档、用户手册页 | 建模细节、数据层次定义 |
| 视频与网络研讨会 | Knowledge Centre 网络研讨会页 | 含 Phast API 专题、9.1 概览、Phast 到 Safeti 过渡等 |
经验法则：把 Knowledge Centre 当作"唯一书架"收藏夹里的第一条。该站的帮助资源历史上曾以"客户门户"的名义被提及，如今统一由 Knowledge Centre 承载——在项目文档里请统一写 Knowledge Centre，不要再写旧称，否则新人会找不到入口。
1.3 令牌：API 通道的入场券
Phast API / Phast Web Services 是托管服务形态的接口（门户 https://phastwebservices.dnv.com/ ，计算端点形如https://phastwebservices.dnv.com/api/analytics/v1/）。调用它需要向 DNV 获取访问令牌（access token）。这带来三条工程纪律：
- 令牌不进代码。它等价于账号凭证，写进脚本就等于写进版本库（铁律 5）。
- 令牌会过期。设计流水线时必须把"令牌续期/轮换"当成一个正常运维动作，而不是事故。
- 令牌有权限范围。若某类计算被拒绝，先怀疑授权范围与令牌有效期，再怀疑代码。
铁律 5（令牌与许可不硬编码）：access token 与许可信息不得写入脚本或仓库，一律走环境变量或密钥管理服务。这条铁律在 16~20 篇的实战里会被反复引用，但纪律必须在第 02 篇就立起来，因为坏习惯一旦形成就很难改。
1.4 版本档案：把"以发布说明为准"落到文件上
官方发布节奏以"主线 9.x + 历史 8.x"的形式演进，同一功能在不同小版本可能变化。因此你的项目里必须有一个明确记录版本的地方。最小可用的版本档案应包含五项：
project_versions.md（建议放在仓库根目录） ------------------------------------------ [产品版本] Phast(TM) 9.x / Safeti(TM) 9.x —— 取值来源：Knowledge Centre 发布说明 + 客户端"关于"页 [API 目标] https://phastwebservices.dnv.com/api/analytics/v1/ —— 取值来源：getAnalyticsApiTarget() [Python ] 3.11+ —— 取值来源：python --version（官方 PyPWS 要求） [PyPWS ] 4.2.25 或本项目锁定版本 —— 取值来源：pip show pypws [记录时间] 2026-09-23 —— 每次升级产品、API 构建或 PyPWS 后更新本行铁律 1（版本先声明）：每篇教程都标注适用版本；差异处必须点明。在项目里，这条铁律的落地形式就是上面这个文件——它让"三个月后结果对不上"这类问题从玄学变成可查的差分。
1.5 学习资源：把官方材料用足
除文档站外，官方还提供 Phast/Safeti/KFX 培训课程、Knowledge Centre 上的网络研讨会录像（含"Ask the experts - Phast API"专题），以及面向用户的用户会议（议程常含 Phast API 与 CFD 主题）。建议把网络研讨会当作 API 变更的第一手来源——它比二手博客可靠得多。
二、完整操作与脚本/API 代码逐段剖析
2.1 安装与授权核对（操作步骤清单）
步骤 1 登录 Veracity 商店，确认本项目的授权形态（Individual 还是 Network）、付费模式与到期日 步骤 2 打开 Knowledge Centre 的软件下载页，下载与授权匹配的 Phast(TM)/Safeti(TM) 安装包 步骤 3 安装并首次启动，在"关于"或标题栏确认显示的版本号（例如 9.x 主线） 步骤 4 打开 Knowledge Centre 的发布说明页，记录你实际安装版本的变更点（尤其影响接口与结果的） 步骤 5 在安装目录/帮助菜单中找到用户手册入口，核对 Study Folder / Study / Scenario 的官方定义 步骤 6 若为 Network 授权，确认许可服务器地址已配置，并在一台"非开发机"上试跑验证能否取到许可 步骤 7 若要走 API 通道，向 DNV 申请访问令牌，确认有效期限与权限范围 步骤 8 把令牌写入本机环境变量（不要写进任何文件），记录轮换计划 步骤 9 安装 Python 3.11+ 与 pypws，运行本篇的自检脚本，把结果归档进版本档案 步骤 10 把上述信息填进 project_versions.md，提交进仓库（令牌除外）2.2 环境自检脚本（PowerShell）
第一道自检在操作系统层完成：解释器版本、包版本、令牌变量、网络可达性。
# env_check.ps1 —— 二次开发环境自检（Windows PowerShell）# 用法：powershell -ExecutionPolicy Bypass -File env_check.ps1# 1) 解释器版本：官方 PyPWS 要求 Python 3.11 及以上python--version# 打印形如 Python 3.11.x；低于 3.11 直接不满足官方要求# 2) 官方 Python 库是否已安装及其版本pip show pypws# 关注 Name/Version/Location 三行；Location 用于确认装进了哪个环境# 3) 访问令牌是否已配置（只判断“有没有”，绝不回显内容）if($env:PHAST_API_TOKEN){# 环境变量存在即为真Write-Output"PHAST_API_TOKEN: 已配置（长度$($env:PHAST_API_TOKEN.Length)字符）"}else{Write-Output"PHAST_API_TOKEN: 未配置 —— 通道 B 将无法调用（见铁律 5）"}# 4) 官方托管端点可达性（只做连通性判断，不提交任何业务请求）try{$r=Invoke-WebRequest-Uri"https://phastwebservices.dnv.com/"-MethodHead-TimeoutSec15Write-Output"Phast Web Services 门户可达，HTTP 状态:$($r.StatusCode)"}catch{Write-Output"Phast Web Services 门户不可达，请检查代理/防火墙策略：$($_.Exception.Message)"}逐行要点：python --version与pip show pypws必须在同一个虚拟环境里执行，多版本 Python 共存时"装上了却导不进"几乎都是环境错位；令牌检查只输出长度不输出内容，是为了让日志可安全归档；连通性用HEAD请求，避免在自检阶段产生任何计算类调用。
2.3 API 目标与授权自检（Python）
第二道自检在 Python 层完成：确认脚本侧到底会调用谁。
# api_check.py —— 通道 B 的接口目标与授权状态自检（只读，不产生业务计算）importos# 读环境变量，避免硬编码令牌frompypws.utilitiesimportgetAnalyticsApiTarget# 官方工具函数：返回当前 API 调用目标defmain()->None:target=getAnalyticsApiTarget()# 打印脚本真实要调用的地址print(f"[1] Phast API 目标:{target}")expected="phastwebservices.dnv.com"# 期望的官方域名片段ok=expectedinstr(target)# 用域名片段做粗判，防止被代理指到别处print(f"[2] 目标是否为官方托管端点:{ok}")ifnotok:# 不匹配时给出明确指引，而不是静默继续print(" 请检查代理、PAC 脚本或 pypws 配置，务必回到官方门户核对")token=os.environ.get("PHAST_API_TOKEN","")# 只从环境变量取（铁律 5）print(f"[3] 访问令牌是否已配置:{bool(token)}")print(f"[4] 令牌长度:{len(token)}")# 打印长度便于判断是否被截断，仍不回显内容base_env=os.environ.get("PYPWS_BASE_URL","")# 部分部署会通过环境变量覆盖基址print(f"[5] 自定义基址是否设置:{bool(base_env)}")if__name__=="__main__":main()# 输出五项结论，直接抄进项目版本档案逐行要点：getAnalyticsApiTarget()是本篇唯一的"官方接口"调用，属于诊断类工具函数；域名片段比对是廉价的护栏，能拦住"在企业代理下悄悄指向测试环境"这类事故；整个脚本不构造任何计算对象、不消耗计算资源，因此可以放进 CI 的启动前检查里。
铁律 7（改完必验）：每个自动化结果须与官方 GUI 结果或官方案例做一致性回归。环境自检是回归的前提：如果连"调的是谁、是什么版本"都不确定，回归就无从谈起。
三、常见报错与排查
报错 3-1：pip show pypws有输出，但脚本from pypws...报ModuleNotFoundError。
现象：包明明装了，导入却失败。根因：多解释器共存，pip装进了 A 环境的 site-packages，而运行脚本的是 B 解释器。解法：用python -m pip show pypws让"安装"和"运行"强制绑定到同一个解释器；长期方案是用虚拟环境并在项目里固定解释器路径。
报错 3-2：解释器版本低于 3.11。
现象：安装或导入阶段直接失败。根因：官方 PyPWS 要求 Python 3.11 及以上。解法：安装 3.11+ 并重建虚拟环境；不要试图在老版本上打补丁——接口兼容性没有官方承诺，省下的十分钟会在后面翻倍还回去。
报错 3-3：桌面许可取不到（Network 授权场景）。
现象：客户端启动报许可类错误，或长时间卡在"正在获取许可"。根因：许可服务器地址/端口不可达，或所有浮动许可都被占用。解法：先确认网络与服务器配置，再用同网段另一台机器做对照试验；在 CI 场景下要为许可竞争做排队与重试设计，否则夜间批量会大面积失败。
报错 3-4：令牌失效（401/403 类响应）。
现象：调用被拒。根因：令牌过期、权限范围不含目标能力，或令牌被写死在代码里且已轮换。解法：把令牌统一收到环境变量或密钥管理（铁律 5），在流水线里加"令牌有效期检查"这一前置步骤；轮换令牌时只改配置，不改代码，这是判断你的凭据治理是否合格的试金石。
报错 3-5：脚本结果与"昨天"不一致，但代码没改。
现象：同一脚本、同一输入，输出漂移。根因：产品版本、API 构建或 PyPWS 版本在期间被升级（API 门户可见构建号会随时间更新），而你没有任何记录。解法：建立 §1.4 的版本档案并在每次升级后更新；排查时先对齐四项版本（产品、API 构建、Python、PyPWS），再进入物理层面的比对。
四、动手练习
- 练习 1（授权建档）：为你的项目写一份
project_versions.md，至少记录产品版本、API 目标、Python 版本、PyPWS 版本与记录时间五项。判定：文件能被另一位同事在五分钟内看懂并复现你的环境。 - 练习 2（跑通自检）：完整执行 §2.2 与 §2.3 两段脚本。判定：五项结论全部有输出；令牌检查只出现布尔值与长度、日志中不含令牌明文。
- 练习 3（版本差异调研）：打开 Knowledge Centre 的发布说明页，找出你当前版本相对上一版本的三条变更，判断哪一条会影响后果计算结果、哪一条只影响界面。判定：能把"影响结果"与"影响体验"的变更分开记录。
- 练习 4（凭据审计）：检查你的工作目录与版本库历史，确认没有任何文件包含令牌或许可信息。判定：
git log历史中也不存在（历史泄漏比当前泄漏更危险，需要立即轮换令牌）。 - 练习 5（Network 授权演练，可选）：若具备 Network 授权条件，在两台机器上同时启动计算，观察许可竞争行为并记录现象。判定：能说清"许可耗尽时客户端表现是什么"，为第 13 篇的队列重试设计做铺垫。
五、小结与下一篇预告
本篇把地基打完了：授权形态决定架构能不能落地，Knowledge Centre是下载与发布说明的唯一权威入口，访问令牌是通道 B 的入场券且必须走环境变量（铁律 5），版本档案是"结果可复现"的最小载体（铁律 1）。请把"装得上、授权通、版本对得上、令牌管得住"当作启动任何自动化项目前的四个检查项。
第 03 篇《界面与数据模型》将正式进入产品内部：Study Folder / Study / Scenario 三层数据层次各自承载什么、场景输入区的四类内容（物料、源项、气象与地面、结果选项）、全局设置与局部覆盖的优先关系、以及结果视图（2D 图、3D 视图、地图/plot plan、表格与 Word/Excel 报告）各自适合承接什么产物——并给出一张"界面层级与可自动化输入项"的映射表，为第 16 篇的 API 实体做铺垫。
本篇认知问题回显（FAQ）
Q1：Phast™ 与 Safeti™ 的许可形态有哪些，为什么安装前必须先问清授权类型？
A：授权对象上分 Individual（单机绑定）与 Network（网络浮动）两种形态，付费模式上有订阅、租赁与永久之分，授权期限可短至 1 天、长至 3 年。必须先问清，是因为它决定架构：脚本运行在哪台机器上、能否多节点并行、流水线能持续多久，全由授权决定。若规划服务器批量流水线却只买 Individual 单机授权，脚本会因取不到授权而失败，这不是代码问题，改代码解决不了。
Q2：软件从哪买、从哪下、发布说明在哪看？"客户门户"这个词为什么不该再用？
A：购买、订阅与续期走 Veracity 商店（如 https://store.veracity.com/phast）；安装介质、发布说明、技术文档、用户手册、视频与网络研讨会统一由官方 Knowledge Centre 承载。帮助资源历史上曾以"客户门户"的名义被提及，如今统一为 Knowledge Centre，因此项目文档里应统一写 Knowledge Centre，避免新人在旧称下找不到入口。
Q3：Phast API 一定要访问令牌吗？令牌应该怎么放、怎么轮换？
A：Phast API / Phast Web Services 是托管服务形态的接口（门户 https://phastwebservices.dnv.com/ ，端点形如 https://phastwebservices.dnv.com/api/analytics/v1/），调用需向 DNV 获取访问令牌。令牌等价于账号凭证，必须走环境变量或密钥管理服务，不得写入脚本或仓库（铁律 5）。它还会过期且带权限范围，因此流水线要把"有效期检查与轮换"当作正常运维动作；轮换时只改配置、不改代码。
Q4：为什么强调"版本先声明"？版本档案在项目里长什么样？
A：官方以主线 9.x 加历史 8.x 的节奏演进，同一功能在不同小版本可能变化，而 Phast API 门户的构建号也会随时间更新。若不记录版本，"同一脚本昨天对今天不对"就会变成玄学。版本档案的最小形态是一个随仓库提交的文件，记录产品版本、API 目标、Python 版本、PyPWS 版本与记录时间五项；每次升级产品、API 构建或 PyPWS 后更新，升级前先看官方发布说明。
Q5：除文档外还有哪些官方学习资源？
A：官方提供 Phast/Safeti/KFX 培训课程；Knowledge Centre 上有网络研讨会录像，其中包括"Ask the experts - Phast API"专题、Phast 9.1 概览与 Phast 到 Safeti 过渡等主题；另有面向用户的用户会议，议程常包含 Phast API 与 CFD 主题。建议把网络研讨会作为接口与版本变更的第一手来源，优先于任何二手博客。
