部署与启动说明（MxServiceCode / MxCAD 转换程序）

基于安装包实际目录与启动脚本整理。

一、程序位置（固定临时路径）

两类包：单独转换程序（MxConvert，仅含 mxcadassembly）与后端服务（MxServiceCode，同时含后端服务和转换程序，即完整超集）。下载地址以 入口指引 的"链接清单"为准（按需要 + 平台取对应行；Linux 包为 Ubuntu 20.04 x86_64 构建）。

固定临时路径（只下载一次，跨会话复用；系统清理临时目录后重新下载即可）：

• Windows：%TEMP%\MxCAD\（%TEMP% 为用户 Temp 目录环境变量，命令中直接使用，无需手动展开）
• Linux：/tmp/MxCAD/

按 入口指引 的排查步骤执行：先判断任务需要什么，再查看临时路径下有什么——什么都没有 → 按需要下载对应 zip（只需转换程序 → 单独 MxConvert 包；需要后端服务 → MxServiceCode 包，内含转换程序）解压到临时路径；只有转换程序 → 仅需转换程序时先做"三、试用版有效期检测"即可用，需要后端时清空重下后端包；已解包后端包 → 做过期检测 + 完整性验证，不完整清空重下。重新下载前必须先清空临时路径（各包目录结构固定，后端包是完整超集）。不要扫描用户机器其他目录。

解压后（Windows：顶层只有一个目录 MxServiceCode_TryVersion\，与 zip 同名）

MxServiceCode_TryVersion\    ← 解压后的顶层目录（与 zip 同名）
├── MxServiceCode\
│   ├── NODE.JS后台程序开发.doc   ← 官方后台开发教程（非 API 文档）
│   ├── MxServiceCode.sln        ← 解决方案文件
│   └── MxServiceCode\           ← 工程目录（以下命令在此执行）
│       ├── bin\node.exe          ← 内置 Node 运行时
│       ├── mxapp.js              ← 入口（命令行）
│       ├── src\                  ← TS 源码（mxcad\ 为 API 类，sample\ 为示例，MxCommand.ts 为命令注册）
│       ├── Mx2DNode.node         ← 原生模块
│       ├── package.json          ← npm run build 编译
│       ├── test.bat              ← 测试脚本
│       ├── empty_template.dwg    ← 空白模板
│       ├── A3.dwg / BT.DWG       ← 图框 / 图签示例图块
│       └── t1.dwg / tree.dwg     ← 测试图纸
└── MxCAD\
    └── Release\                 ← 格式转换程序目录（mxcadassembly.exe + 运行依赖 dll + mxcad_ini.json、mxcode.bin、mxiconv.data + **fonts\** + files\）

解压后（Linux：顶层只有一个目录 MxServiceCode_TryVersion\，与 zip 同名）

MxServiceCode_TryVersion\    ← 解压后的顶层目录（与 zip 同名）
├── MxServiceCode\
│   ├── NODE.JS后台程序开发.doc   ← 官方后台开发教程
│   └── MxServiceCode\           ← 工程目录（无 .sln；内置运行时为 node 而非 bin\node.exe，
│                                 另含 start_demo_MxServiceCode.sh、start_demo_systemlib_MxServiceCode.sh、Linux启动说明.txt）
└── Linux\
    └── MxCAD\                   ← 格式转换程序目录（mxcadassembly + 运行依赖 mx/so + mxcad_ini.json、mxcode.bin、mxiconv.data + **fonts\** + files\）

转换程序目录 = Windows 临时路径下 MxServiceCode_TryVersion\MxCAD\Release\、Linux 临时路径下 MxServiceCode_TryVersion\Linux\MxCAD\（单独 MxConvert 包则为 MxConvert_TryVersion\ 目录本身）；前端预览图纸所需字体 = 该目录下的 fonts\（复制它即可）。

二、运行 MxServiceCode 命令（无需启动任何服务）

命令方式为独立进程，直接调用内置 node：

Windows（工程目录下）：

bin\node.exe mxapp.js getcaddata file=t1.dwg outfile=t1.dwg.json

Linux（工程目录下）：

./node mxapp.js getcaddata file=t1.dwg outfile=t1.dwg.json linux=1

无参数运行 node mxapp.js 可打印版本信息与日志路径。

⚠️ 内置 Node 版本限制（实测）：bin\node.exe 为 v10.9.0，仅支持 CommonJS——ESM（import 语法 / .mjs）直接报 SyntaxError；也没有 fetch、可选链等新特性。用内置 node 写辅助脚本一律用 CommonJS（require）+ .js；需要 ESM 时改用系统 Node。

Linux 首次部署（权限配置）

chmod 777 start_demo_MxServiceCode.sh
./start_demo_MxServiceCode.sh     # 脚本内已完成 mxcadassembly、mx/so、Mx2DNode.node、node 的 chmod

出错时改用 ./start_demo_systemlib_MxServiceCode.sh（使用 systemLib 目录下的原生库）。

三、格式转换程序 mxcadassembly（独立调用）

Windows（转换程序目录下，两种形式等价，按 shell 选）：

• cmd / PowerShell（裸 JSON，即官方文档形式，无需编码）：

mxcadassembly.exe {"srcpath":"1.dwg","outname":"_trial.mxweb","outpath":"./out"}

• Git Bash（百分号编码串 + 引号；该 shell 下裸 JSON 会返回 read file error，实测）：

mxcadassembly.exe "[%7B%22srcpath%22%3A%221.dwg%22%2C%22outname%22%3A%22_trial.mxweb%22%2C%22outpath%22%3A%22.%2Fout%22%7D]"

Linux（转换程序目录下，裸 JSON 加单引号即可）：

chmod -R 777 mxcadassembly ./mx/so/*
./mxcadassembly '{"srcpath":"1.dwg","outname":"_trial.mxweb","outpath":"./out"}'

（等价备选形式：./mxcadassembly '[%7B%22srcpath%22%3A%221.dwg%22%2C%22outname%22%3A%22_trial.mxweb%22%2C%22outpath%22%3A%22.%2Fout%22%7D]'）

参数形式约定：程序接受两种等价形式——① 裸 JSON（官方文档形式，cmd / PowerShell / Linux bash 直接可用，bash 下用单引号包裹）；② 百分号十六进制编码串 + 一层方括号（如 {"a":1} → [%7B%22a%22%3A1%7D]，MxServiceCode 内部使用，Git Bash 必须用此形式）。MxServiceCode 内部的 MxUtility.callMxCadAssembly 已封装此逻辑，二开时优先通过 TS API 调用，不要手动拼命令。

⚠️ 常见坑（实测）

• 编码必须带 % 前缀；误用纯十六进制（如 7b2261223a317d）会返回 {"code":1,"message":"read file error"}
• cmd.exe / 批处理中 % 是批处理变量引用：百分号编码串会被展开破坏（返回 {"code":1,"message":"read file error"}），cmd 下必须用裸 JSON 形式
• Windows 上 python 可能是 Store 占位程序（静默无输出）；生成编码参数的临时脚本用内置 bin\node.exe
• convert 命令不可用时（wgh 已废弃，见《MxServiceCode命令参考.md》详解 1），DWG→mxweb 以本独立调用为唯一途径；mxcad 前端只认 mxweb

试用版有效期检测

转换程序为试用版，期限 6 个月。临时路径中已有转换程序，使用前必须先做测试转换（命令行方式，无需 GUI；在转换程序目录执行，用包内自带测试图如 1.dwg，输出目录先建好）：

Windows（cmd / PowerShell）：mxcadassembly.exe {"srcpath":"1.dwg","outname":"_trial.mxweb","outpath":"./out"}；Windows（Git Bash）：mxcadassembly.exe "[%7B%22srcpath%22%3A%221.dwg%22%2C%22outname%22%3A%22_trial.mxweb%22%2C%22outpath%22%3A%22.%2Fout%22%7D]"；Linux：./mxcadassembly '{"srcpath":"1.dwg","outname":"_trial.mxweb","outpath":"./out"}'

• 返回 {"code":0,"message":"ok"} → 有效可用，直接使用。
• 返回非 0 → 读 %TEMP%\MxNode\mxcad_*.log 中的版本串（每次运行都会记录，格式实测样本：MxCAD TryVersion:7.0(2026-10-21 11:16)(64bit)(cooperate)）：
  • 括号内日期（如 2026-10-21）= 试用起始日；当前日期 − 试用起始日 > 5 个月 → 过期，重新下载 zip 解压覆盖临时路径（地址见入口指引"链接清单"）
  • 未过期 → 程序环境异常，按日志排错

常用 JSON 参数（详见官方《图纸转换详细说明》）：

• 转换：{"srcpath":"a.dwg","outname":"a.mxweb","outpath":"./out"}（路径相对转换程序目录；outname 后缀决定目标格式；mxweb 转 dwg 必须显式带 .dwg/.dxf；outpath 目录必须预先存在）
• 裁剪 DWG：{"cmd":"cut_dwg","bd_pt1_x":0,"bd_pt1_y":0,"bd_pt2_x":100,"bd_pt2_y":100,"srcpath":"a.dwg","outname":"cut.dwg"}
• 输出 PDF：{"srcpath":"a.dwg","outname":"a.pdf","outpath":"./out","ret_page_extents":true,"width":"2000","height":"2000","colorPolicy":"mono"}——不带 cmd 字段（带则返回 {"code":201}）；输出位置与其他转换规则一致：输出目录为 outpath（省略时回退转换程序目录），文件名为 outname（outname 为绝对路径时直接写该位置）
• srcpath/outpath/outname 均支持绝对路径（含中文路径）
• ⚠️ cmd 参数域（如 print_to_pdf 等）属于 MxServiceCode 后端服务接口，mxcadassembly.exe 直调仅上述参数有效

四、二开工作流

1. 修改 src/sample/*.ts 或新增文件（API 见《Mx2DNode二开API参考.md》）
2. 在 src/MxCommand.ts 注册命令（见《MxServiceCode命令参考.md》第六节）
3. 编译：npm run build（node_modules 已内置；如缺失用 bin\node.exe node_modules\typescript\bin\tsc --build）
4. 用 bin\node.exe mxapp.js <命令> 参数=值 debug=1 验证

五、日志

• 路径：%TEMP%\MxNode（Linux 同规则）
• 每次命令结束输出 logs end；debug=1 时日志更详细
• 异常返回 {"code":-4,"message":"js程序异常，详细见日志"} 时查日志文件

六、附带资源说明

文件	用途
empty_template.dwg	空白模板，Mx2DDraw.getEmptyTemplateDwgFilePath() 指向它
A3.dwg / BT.DWG	图框 / 图签示例（BT 块含属性定义），testParamDrawTk 使用
t1.dwg / tree.dwg	测试图纸 / 图块（tree 图块用于 testParamDraw）
mxcad_ini.json（转换程序目录下）	转换程序配置（字体路径等），勿随意修改
fonts\	字体目录（DWG 中 SHX/TTF 字体依赖）