企业官网建设流程全解析

TDgpt Windows 打包与离线安装指南：基于 win_release.py 与 Inno Setup 的完整交付流程

【免费下载链接】TDengineHigh-performance, scalable time-series database designed for Industrial IoT (IIoT) scenarios项目地址: https://gitcode.com/GitHub_Trending/tde/TDengine

本文聚焦 TDengine Analytics Node（TDgpt）在 Windows 平台上的打包、离线分发与静默安装。全文以 tools/tdgpt/packaging/README-CN.md 为主线骨架，结合 packaging/win_release.py、packaging/build_offline_assets.py、packaging/installer/tdgpt.iss 与 script/install.py 等源码进行纵深验证与扩充。读者读完可独立完成基础安装包与外部离线 tar 包的制作、理解安装器内部行为，并能在无系统 Python 的目标机上完成静默部署与故障排查。

一、适用范围与交付形态

当前 Windows 交付只保留两条安装路径：

• 基础安装包 + 在线安装：安装包本身不携带 Python 运行时与虚拟环境，首次在线安装时目标机需在PATH中提供 Python3.10/3.11/3.12；
• 基础安装包 + 外部离线 tar 包：离线 tar 包内含 Python runtime、主 venv 与模型 payload，安装器通过系统内置tar.exe引导 Python，不要求目标机自带 Python。

旧的full-offline一体包模式已经删除，社区版与企业版均遵循上述两条路径交付。

二、打包目录与主要文件

packaging/目录下是与打包直接相关的文件（见 tools/tdgpt/packaging）：

packaging/ ├── win_release.py # Windows 打包主入口 ├── build_offline_assets.py # 生成外部离线 tar 资源包 ├── test_win_release.py # 针对 win_release.py 的单元测试 ├── installer/ │ ├── tdgpt.iss # Inno Setup 模板 │ └── taosanode-service.xml # WinSW 服务模板 ├── bin/ # 可选本地缓存（WinSW.exe / uv.exe） ├── README.md └── README-CN.md script/ ├── install.py # Windows 安装逻辑 ├── uninstall.py # Windows 卸载逻辑 └── taosanode_service.py # 服务与模型统一管理脚本

各文件职责如下：

• win_release.py：主入口，负责校验环境、整理安装载荷（staging）、生成tdgpt.iss与install.bat/uninstall.bat、下载 WinSW，最终调用 Inno Setup 编译器（ISCC.exe）产出.exe安装包。其main()流程（win_release.py#L1037-L1092）为：校验 Python 版本 → 解析参数 → 清理并重建发布目录 → 依次复制配置/代码/资源/依赖/runtime/模型/企业文件/服务脚本/图标 → 下载 WinSW 并生成配置 → 生成批处理脚本 → 渲染 ISS 脚本 → 调用 ISCC 构建安装器。
• build_offline_assets.py：将 Python runtime、主 venv、模型 venv 与 seed 包中的模型 payload 组装为外部离线 tar 包，并写入offline-assets-manifest.txt清单。
• installer/tdgpt.iss：Inno Setup 模板，含安装向导的 [Code] 段（安装模式选择、离线包检测、服务注册、进度页等），其中{{VERSION}}、{{APP_NAME}}、{{SOURCE_DIR}}等占位符由win_release.py的create_iss_script()替换（win_release.py#L911-L945）。
• installer/taosanode-service.xml：WinSW 服务模板，定义了服务 IDTaosanode、执行命令、环境变量（PYTHONPATH、TAOSANODE_CONFIG、TAOSANODE_DISABLE_CONSOLE_LOG、TAOSANODE_REDIRECT_STDIO）、失败重启策略与 30 秒停止超时。
• install.py：安装核心逻辑，负责 venv 创建、依赖安装、离线包导入、模型部署与服务注册，支持通过--progress-file向安装向导回传进度。
• uninstall.py：卸载逻辑，由uninstall.bat调用。
• taosanode_service.py：服务与模型统一管理脚本，提供start/stop/status、start-service/stop-service、wait-ready、model-start/model-stop/model-status等子命令。

三、打包机预置要求

3.1 基础安装包打包前置条件

1. 已安装 Python3.10、3.11或3.12，并且可直接从PATH调用。这一点在 win_release.py#L69-L81 的check_python_version()中被强制校验：主版本必须为 3，次版本必须是 10/11/12，否则直接sys.exit(1)。
2. 已安装Inno Setup 6（需要其命令行编译器ISCC.exe）。
3. 当前源码目录完整，至少包含：
   • packaging/win_release.py
   • packaging/installer/tdgpt.iss
   • script/install.py
   • script/uninstall.py
   • script/taosanode_service.py
4. 如果希望基础安装包内附带模型归档文件，需要提前准备模型归档目录，例如：
   • tdtsfm.tar.gz、timemoe.tar.gz、moirai.tar.gz、chronos.tar.gz、timesfm.tar.gz、moment-large.tar.gz

3.2 离线 tar 打包额外前置条件

生成 Windows 离线安装使用的外部 tar 包，还需要准备：

1. 一个主 venv 目录（对应 taosanode 的主虚拟环境）；
2. 零个或多个模型 venv 目录（如moirai_venv、chronos_venv、timesfm_venv、momentfm_venv）；
3. 二选一准备 Python runtime 来源：
   • 已准备好的 Python runtime 目录，目录下包含python.exe；
   • packaging/bin/uv.exe，或者通过--uv-exe显式指定一个可用的uv.exe；
4. 一个可选的 seed package：用于带入已有离线模型 payload，也可以带入已有模型 venv payload。

3.3 可选本地缓存

• packaging/bin/WinSW.exe：基础安装包打包时复用本地 WinSW 缓存；如果没有，脚本会尝试从 GitHub 下载（win_release.py#L981-L1015 的download_winsw()先查本地缓存，命中则直接复制，未命中则下载并回写缓存）。
• packaging/bin/uv.exe：离线 tar 打包时自动准备 Python runtime；如果已传入--python-runtime-dir，则不依赖它。

3.4 路径与工具说明

• ISCC.exe默认路径为C:\Program Files (x86)\Inno Setup 6\ISCC.exe，也可以通过--iscc-path显式指定。check_inno_setup()（win_release.py#L890-L908）还会依次探测 32/64 位 Program Files 下的 Inno Setup 6/5。
• win_release.py不会把 Python runtime 或虚拟环境直接打进基础安装包（详见下文“基础安装包里包含什么”）。
• 当build_offline_assets.py未显式传入--python-runtime-dir时，会优先使用packaging/bin/uv.exe（源码常量DEFAULT_UV_EXE，见 build_offline_assets.py#L18）。

四、目标机器要求

• Windows 10（1803 或更高版本）或 Windows Server 2019+。
• 目标机器需要已安装Microsoft Visual C++ Redistributable x64 14.44 或更高版本；建议安装最新支持的 VC++ 2015-2022 运行库。该最低版本在 tdgpt.iss#L14-L17 中以MinVCRuntimeMajor 14/MinVCRuntimeMinor 44的形式编码，安装器会据此做运行库检测。
• 在线首次安装时，目标机器需要在PATH中提供 Python3.10/3.11/3.12。
• 离线安装时，不要求系统自带 Python——安装器会通过系统内置的tar.exe（Windows 10 1803+ 自带）从离线 tar 包中自动引导 Python 运行时。

五、基础安装包里包含什么

固定包含：

• cfg/（含taosanode.config.py与package-metadata.json，后者记录 edition、app_name、product_full_name、package_name、product_name、version、resource_package_url，见 win_release.py#L283-L310）；
• lib/（taosanalytics 包本体，复制时排除__pycache__、*.pyc、.git*，并回写__init__.py中的__version__，见 win_release.py#L315-L349）；
• resource/；
• requirements/（源码根目录下所有requirements*.txt）；
• bin/（taosanode_service.py与生成的六个批处理脚本）；
• install.py、install.bat；
• uninstall.py、uninstall.bat；
• WinSW 可执行文件和 XML（taosanode-winsw.exe+taosanode-winsw.xml）；
• package metadata。

可选包含：

• 通过--model-dir复制进来的模型归档文件，落在<install_dir>\model\。

明确不包含：

• python/runtime；
• 已解压的虚拟环境；
• 已解压的模型目录。

与源码一致：基础安装包本身不内置runtime 与 venv（win_release.py#L1063-L1071 明确输出 “Base installer does not require bundled runtime, venv, or model validation”），模型归档打包是可选的，不再是必填项。

六、用法：win_release.py 打包命令

6.1 基本命令

# Community 版本 python packaging/win_release.py -e community -v 3.4.1.0.0325 # Enterprise 版本 python packaging/win_release.py -e enterprise -v 3.4.1.0.0325 # 打包时附带模型归档文件 python packaging/win_release.py -e community -v 3.4.1.0.0325 -m D:\models # 打包目录中的全部已识别模型归档 python packaging/win_release.py -e community -v 3.4.1.0.0325 -m D:\models -a # 自定义输出目录 python packaging/win_release.py -e community -v 3.4.1.0.0325 -o D:\tdgpt-release\20260325-r7 python packaging/win_release.py -e enterprise -v 3.4.1.0 --resource-package-version 1.1

6.2 参数说明

参数校验细节（win_release.py#L146-L197）：

• 版本号只允许数字和点，长度须小于 16，且匹配^[0-9]+\.([0-9]+\.){1,3}[0-9]+$；
• -e仅接受enterprise/community；
• 未显式传--resource-package-url时，会按模板https://downloads.tdengine.com/tdengine-historian/tdgpt-resource-pkg/tdengine-tdgpt-model-resource-{version}.tar.gz生成默认下载 URL（build_default_resource_package_url，win_release.py#L65-L66）。

6.3 模型归档说明

如果传入--model-dir，win_release.py的copy_model_files()（win_release.py#L388-L419）会识别并复制这类归档文件：

• tdtsfm.tar.gz（始终尝试复制）
• timemoe.tar.gz（始终尝试复制）
• moirai.tar.gz（仅-a时）
• chronos.tar.gz（仅-a时）
• timesfm.tar.gz（仅-a时）
• moment-large.tar.gz（仅-a时）

这些归档文件都是可选的。即使不附带任何模型归档，也可以正常生成基础安装包。

七、生成外部离线 tar 包

Windows 离线安装所用的外部 tar 包，由 build_offline_assets.py 生成。

需要准备的输入：

• 一个主 venv 目录；
• 零个或多个模型 venv 目录；
• 一个 Python runtime 目录，或者提供uv.exe让脚本自动准备；
• 一个可选的 seed package，用来带入离线模型 payload。

典型命令（Windows cmd 下使用^换行）：

python packaging/build_offline_assets.py ^ --output-file D:\offline-tar\tdengine-tdgpt-offline-assets-3.4.1.0.0325-windows-x64.tar ^ --seed-package D:\offline-seed\tdgpt-model-seed.tar ^ --python-runtime-dir C:\TDengine\python311 ^ --main-venv-dir C:\TDengine\taosanode\venvs\venv ^ --extra-venv-dir C:\TDengine\taosanode\venvs\moirai_venv ^ --extra-venv-dir C:\TDengine\taosanode\venvs\chronos_venv ^ --extra-venv-dir C:\TDengine\taosanode\venvs\timesfm_venv ^ --extra-venv-dir C:\TDengine\taosanode\venvs\momentfm_venv

如果不想提前准备 Python runtime 目录，也可以让脚本通过uv.exe自动准备：

python packaging/build_offline_assets.py ^ --output-file D:\offline-tar\tdengine-tdgpt-offline-assets-3.4.1.0.0325-windows-x64.tar ^ --main-venv-dir C:\TDengine\taosanode\venvs\venv ^ --extra-venv-dir C:\TDengine\taosanode\venvs\moirai_venv ^ --extra-venv-dir C:\TDengine\taosanode\venvs\chronos_venv ^ --extra-venv-dir C:\TDengine\taosanode\venvs\timesfm_venv ^ --extra-venv-dir C:\TDengine\taosanode\venvs\momentfm_venv ^ --uv-exe packaging\bin\uv.exe ^ --python-version 3.11

7.1 离线 tar 参数说明

7.2 命名建议与包内结构

建议离线资源包命名为：

tdengine-tdgpt-offline-assets-<version>-windows-x64.tar

生成的 tar 包中通常包含：

• python/runtime/
• venvs/venv/
• venvs/<extra_venv>/
• 从--seed-package带入的模型 payload（重映射到model/<模型名>/下，别名映射见 build_offline_assets.py#L19-L28）
• offline-assets-manifest.txt（清单，含generated_at、bundle_kind、main_venv、models=、extra_venvs=等条目，见 build_offline_assets.py#L233-L257）

7.3 推荐交付流程

1. 先用win_release.py生成基础安装包；
2. 再用build_offline_assets.py生成外部离线 tar 包；
3. 两个文件一起交付；
4. 用户在 Windows 安装向导里选择Offline package，并选中这个 tar 文件。

八、输出产物

生成的安装包文件名为：

tdengine-tdgpt-oss-<version>-windows-x64.exe tdengine-tdgpt-enterprise-<version>-windows-x64.exe

对应源码中的package_name = f"{product_name}-{version}-windows-x64"（win_release.py#L181-L183），其中product_name依据 edition 取tdengine-tdgpt-oss或tdengine-tdgpt-enterprise。

九、静默安装与命令行安装

安装器支持完全静默（无人值守）安装，适用于脚本化部署和 All-in-One 打包场景。/OFFLINE与/ONLINE参数由 tdgpt.iss 的 [Code] 段通过ExpandConstant('{param:OFFLINE|}')读取。

9.1 静默离线安装（不需要系统 Python）

tdgpt-setup.exe /VERYSILENT /NORESTART /OFFLINE="D:\packages\tdengine-tdgpt-offline-assets-3.4.1.0.0325-windows-x64.tar"

传入/OFFLINE后，安装器自动使用离线模式。Python 运行时通过系统tar.exe从 tar 包中引导，无需系统自带 Python。

9.2 静默在线安装（需要系统 Python）

tdgpt-setup.exe /VERYSILENT /NORESTART /ONLINE=1

静默安装的默认模式是离线模式。若要强制在线模式，请传入/ONLINE=1。对于首次在线安装，目标机仍需在PATH中提供 Python 3.10–3.12；如果针对所选安装路径没有可用 Python 运行时，安装日志会记录明确的错误信息。

9.3 Python 发现优先级

安装过程中，install.bat按以下顺序查找 Python 解释器（win_release.py#L736-L806 中生成的install.bat逻辑）：

1. 已有 venv Python—<install_dir>\venvs\venv\Scripts\python.exe（升级场景）；
2. 已有 packaged runtime—<install_dir>\python\runtime\python.exe（之前已解压过）；
3. 系统 Python— PATH 中的python或python3（在线模式）；
4. 从离线 tar 引导— 使用tar.exe从离线包中只抽取python/runtime/到临时目录_bootstrap，然后用该 Python 执行install.py。

_bootstrap临时目录在安装完成后自动清理（install.py中cleanup_offline_package_cache()负责清理离线包缓存，见 install.py#L586-L594）。

此外，install.py还有一个细节：当离线导入的 Python 不是打包自带的 runtime 时（is_unsafe_offline_import_python，install.py#L315-L363），会重新以 bundled Python 或外部 Python 拉起自己，确保离线依赖安装时的 Python 解释器安全。

9.4 All-in-One (AIO) 集成示例

REM install-all.bat AIO 打包示例 installers\tdgpt-setup.exe /VERYSILENT /NORESTART /OFFLINE="%CD%\offline-packages\tdengine-tdgpt-offline-assets-3.4.1.0.0325-windows-x64.tar" if errorlevel 1 ( echo TDgpt 安装失败 exit /b 1 ) echo TDgpt 安装成功

9.5 检查安装结果

静默安装完成后，可通过以下方式确认：

• 退出码：0= 成功，非零 = 失败；
• 安装日志：C:\TDengine\taosanode\log\install.log；
• 服务状态：sc query Taosanode。

十、安装器行为

10.1 安装向导行为

• 默认推荐安装来源为Offline package；
• 选择离线模式后，安装器会优先在同目录查找tdengine-tdgpt-resource.tar、tdengine-tdgpt-resource.tar.gz、tdengine-tdgpt-resource-*.tar、tdengine-tdgpt-resource-*.tar.gz或tdengine-tdgpt-resource-*.tgz，若未找到再回退到配置的资源包文件名和兼容旧的tdengine-tdgpt-offline-assets-<version>-windows-x64.tar（检测逻辑见 tdgpt.iss#L215-L329 的DetectDefaultOfflinePackage/DetectDefaultModelResourcePackage）；
• 如果打包时没有显式传入--resource-package-url，win_release.py会用--resource-package-version生成默认下载 URL，默认值是1.0，默认资源包后缀改为更省体积的.tar.gz；
• 仍然保留在线安装路径；
• Windows 服务固定自动安装，不再作为可选项展示；
• 升级安装默认复用现有venvs和模型文件；
• 离线首次安装必须提供一个外部 tar 包；
• 离线升级时可以把 tar 路径留空，直接复用现有 runtime 和模型文件；
• 支持/OFFLINE命令行参数，用于静默安装时预设离线包路径。

10.2 批处理包装脚本行为

• start-taosanode.bat、stop-taosanode.bat、status-taosanode.bat都要求<install_dir>\venvs\venv\Scripts\python.exe存在；
• start-model.bat、stop-model.bat、status-model.bat同样固定依赖这个主 venv Python；
• 这些脚本不会回退到系统python；
• start-model.bat和stop-model.bat在不带参数时都会默认作用于all。

这些行为在源码生成逻辑中清晰可见：六个批处理脚本都通过python_guard先检查主 venv Python 是否存在（不存在即报错退出），start-taosanode.bat还会区分“服务已注册”（走start-service+wait-ready --timeout 90）与“进程模式”（走start），见 win_release.py#L499-L709。

十一、服务与模型命令

11.1 服务管理

net start Taosanode net stop Taosanode sc query Taosanode C:\TDengine\taosanode\bin\start-taosanode.bat C:\TDengine\taosanode\bin\stop-taosanode.bat C:\TDengine\taosanode\bin\status-taosanode.bat

服务定义来自 installer/taosanode-service.xml：服务 ID 为Taosanode，可执行文件指向<install_dir>\venvs\venv\Scripts\python.exe，启动参数为taosanode_service.py start --foreground，并注入PYTHONPATH（指向lib）、TAOSANODE_CONFIG（指向cfg\taosanode.config.py）、TAOSANODE_DISABLE_CONSOLE_LOG、TAOSANODE_REDIRECT_STDIO（重定向到log\taosanode.app.log）等环境变量；启动类型为Automatic（自动 + 延迟启动），失败时先 10 秒、再 20 秒重启，之后放弃，1 小时后重置失败计数，停止超时为 30 秒。

11.2 模型管理

C:\TDengine\taosanode\bin\start-model.bat C:\TDengine\taosanode\bin\start-model.bat all C:\TDengine\taosanode\bin\stop-model.bat all C:\TDengine\taosanode\bin\status-model.bat

批处理脚本内部实际调用taosanode_service.py的model-start/model-stop/model-status子命令（见 taosanode_service.py#L1574 起的ModelManager.start/stop与main()的命令分发）。

11.3 直接调用 Python 脚本

如果要直接调用 Python 脚本，应使用主 venv 的 Python：

C:\TDengine\taosanode\venvs\venv\Scripts\python.exe C:\TDengine\taosanode\bin\taosanode_service.py start C:\TDengine\taosanode\venvs\venv\Scripts\python.exe C:\TDengine\taosanode\bin\taosanode_service.py model-start all

十二、日志

当前 Windows 侧关键日志文件包括：

• <install_dir>\log\install.log
• <install_dir>\log\uninstall.log
• <install_dir>\log\install-progress.log
• <install_dir>\log\taosanode-service.log
• <install_dir>\log\taosanode.app.log
• <install_dir>\log\model_*.log

说明：

• 服务管理日志是taosanode-service.log；
• taosanode-service.wrapper.log、*.out.log、*.err.log这类 WinSW wrapper 日志，不属于当前默认日志链路（taosanode-service.xml#L10 中<log mode="none"/>已关闭 WinSW 自身日志）；
• install.log与uninstall.log分别由install.bat/uninstall.bat初始化并写入（win_release.py#L758-L779、win_release.py#L836-L853）；
• 模型启动/停止日志按模型写入model_*.log（win_release.py 生成的start-model.bat中提示 “Logs are written under ..\log\model_*.log”）。

十三、常见问题

13.1 打包在调用 ISCC 之前失败

• 检查打包机 Python 版本（必须是 3.10/3.11/3.12，见check_python_version()）；
• 检查版本号格式是否合法（只允许数字和点、长度小于 16）；
• 检查输出目录是否可被删除并重建（clean_release_dir()会先shutil.rmtree再重建）。

13.2 找不到 ISCC

• 安装 Inno Setup 6；
• 如果ISCC.exe不在默认路径下，显式传入--iscc-path。

13.3 批处理脚本提示主 Python 环境缺失

• 检查<install_dir>\venvs\venv\Scripts\python.exe是否存在；
• 如果是离线安装，确认离线 tar 已成功导入，必要时重新执行安装；
• 如果是在线安装，可重新执行安装以重建主 venv。

13.4 启动命令返回了，但就绪检测未确认成功

• 检查<install_dir>\log\taosanode-service.log；
• 检查<install_dir>\log\taosanode.app.log；
• 执行status-taosanode.bat；
• 执行sc query Taosanode。

start-taosanode.bat会调用taosanode_service.py wait-ready --timeout 90做就绪检测（taosanode_service.py#L1359），90 秒内未确认就绪即提示查看上述日志与状态命令。

十四、本次审查结论与实现一致性

本 README 已按当前代码实现重新对齐，核对范围包括：

• packaging/win_release.py
• packaging/installer/tdgpt.iss
• script/install.py
• script/taosanode_service.py

本次修正的重点有：

• 删除已经下线的full-offline相关表述；
• 明确基础安装包不内置 runtime 和 venv；
• 明确离线安装不依赖系统 Python；
• 明确批处理脚本固定依赖主 venv Python；
• 修正日志文件名，去掉过时的 WinSW wrapper 日志说明；
• 明确 Windows 服务是自动安装；
• 明确模型归档打包是可选能力，不再是必填；
• 新增静默安装文档，包括/OFFLINE参数说明；
• 新增 Python 发现优先级文档；
• 新增 AIO 集成示例；
• 新增 Windows 10 1803+ 的tar.exe引导要求说明。

十五、延伸阅读

• 打包入口与完整流程：packaging/win_release.py
• 离线资源包构建：packaging/build_offline_assets.py
• Inno Setup 模板（含向导 Code 段）：packaging/installer/tdgpt.iss
• WinSW 服务模板：packaging/installer/taosanode-service.xml
• 安装逻辑（venv 创建、离线导入、进度上报）：script/install.py
• 卸载逻辑：script/uninstall.py
• 服务与模型统一管理：script/taosanode_service.py
• TDgpt 配置（含模型注册表与默认模型端点）：cfg/taosanode.config.py
• 打包脚本单元测试：packaging/test_win_release.py

【免费下载链接】TDengineHigh-performance, scalable time-series database designed for Industrial IoT (IIoT) scenarios项目地址: https://gitcode.com/GitHub_Trending/tde/TDengine