概述

本文档是一个对 ThingJS 项目离线部署包的获取、安装、配置、授权、更新、迁移等方面进行说明的技术文档。

本文档会以 ThingJS 平台“在线开发”为默认环境进行介绍。涉及 ThingJS 离线开发环境的内容会将与“在线开发”差异部分在各章节内容中增加小节补充说明。

说明

在 ThingJS 3D 可视化开发平台“在线开发”（https://www.thingjs.com） 、ThingJS离线开发等环境完成项目开发后，开发人员可将所完成开发的项目离线部署到自己的私有服务器上。这时候就会使用到该项目的“ThingJS项目离线部署包”。

“ThingJS 项目离线部署包”可由已开通“VIP 商业开发者”或购买“离线部署永久授权”的账号从“在线开发”环境进行下载；或由 ThingJS 离线开发环境生成。

ThingJS 免费用户无法下载项目离线部署包。当然，虽然免费用户不能下载离线部署包，但他们可在 ThingJS 平台完整测试 ThingJS API 调用及大部分功能。

（注：一般商业项目的开发和部署，建议通过购买 ThingJS 3D 可视化开发平台的“ThingJS 3D 可视化套餐”（https://www.thingjs.com/guide/price/） 来完成，以提高商业项目开发的便捷度和效率。）

硬件配置

安装服务器推荐配置

（注：(1)若需在 CPU 为 ARM 的 Linux 服务器上进行部署，请先咨询平台客服;

(2)不支持在 Docker 中进行部署。）

浏览器客户端推荐配置

离线部署包类型说明

“ThingJS 项目离线部署包”分为“临时部署包”和“永久部署包”两种类型。

临时部署包

“临时部署包”仅用于需项目离线部署的用户在离线部署环境测试之用。用户若需在私有服务器部署商业或正式应用的，请使用“永久部署包”。

已开通“VIP 商业开发者”的账号可在“在线开发”中获取“临时部署包”；购买“离线开发授权”的用户可在离线开发环境生成项目的“临时部署包”。

“临时部署包”在完成授权后（自助在 ThingJS 网站获取授权码），默认有效期为 7 天；“临时部署包”的 3D 可视化项目画面背景中会显示 ThingJS 官方水印；7 天授权过期后，原“临时部署包”访问链接将自动显示项目离线部署管理页面，无法再正确加载原 3D 可视化项目画面。此时，用户可再次申请一个临时授权码，或升级到“永久部署包”重新激活来使用。

“ThingJS 项目离线部署包”含“更新项目”功能。无论 3D 场景变更、脚本变更、资源变更等，开发者都可对已部署项目进行更新操作。但“更新项目”功能对“临时部署包”项目是有限制的。对于用“临时部署包”部署的项目，若需要更新的，只能使用“永久部署包”进行项目更新。完成更新后，该“临时部署包”部署的项目也会自动升级为“永久部署包”项目。也就是说，“临时部署包”项目无法通过另一个“临时部署包”来完成更新。

实际上，“临时部署包”不支持作为“更新部署包”进行任何项目更新。无论原部署项目是“临时部署包”项目，还是“永久部署包”项目均不支持。

（注：“临时部署包”升级为“永久部署包”时，机器码文件将自动更新升级，会导致当前授权失效。此时，需申请永久授权码方可再次激活授权。）

永久部署包

只有购买“离线部署永久授权”的账号才可获取“永久部署包”。

“永久部署包”必须使用“永久授权码”进行授权激活（首次获取需联系平台商务人员）。完成授权后授权将永久有效，同时在 3D 可视化项目画面背景中也不会显示 ThingJS 官方水印。

“永久部署包”支持作为“更新部署包”进行项目更新。“永久部署包”在授权成功后，将拥有“服务器迁移”功能。

（注：如需购买“离线部署永久授权”，请咨询在线客服，或者拨打 ThingJS 平台客服电话 400-666-9832。）

获取

准备 CPS 文件

需使用 ThingJS 平台项目离线部署包功能，需先开通了 VIP 商业开发授权。免费用户无法下载项目离线部署包。

当 VIP 开发者在 ThingJS 平台“在线开发”环境完成一个项目开发，准备进行项目离线部署包下载时，需了解一下项目部署包配置文件：CPS 文件。

一般情况下，ThingJS 平台的离线部署包生成程序会自动打包项目所引用的场景和模型，但因为开发人员程序写法多样，离线部署包生成程序很难一一识别这些实际需要打包的场景、模型，所以“在线开发”环境给每个项目都增加了一个 CPS 配置文件，辅助项目离线部署包打包。

为确保项目中所引用的场景和模型能够被完整离线打包，需在在线开发中自行配置项目对应的 CPS 文件后再进行“ThingJS 项目离线部署包”的申请。

CPS 文件配置方法如下：

例如，在线开发中，需要进行离线部署的项目如下图所示：

项目中引用了一个场景 ('/api/scene/15fc31d71fba01bc0a093xxx')，和一个模型 ('/api/models/ABCF7A3F0BDA48B7B7A8C9C94824359D/0/gltf/')。

点击打开当前项目下对应的 CPS 文件，CPS 文件初始内容如下图所示：

将需要离线的场景 URL 填入 scenes 配置项中，模型 URL 填入 models 配置项中，如下图所示。

保存即配置完成。

场景文件将被打包至离线部署包的/web/scene/目录下，模型文件将被打包至离线部署包的/web/models/目录下。

申请下载

入口

在线开发中，申请“ThingJS 项目离线部署包”需到“离线部署管理”面板中进行，“离线部署管理”面板的入口有两处：

（1）快捷入口，如下图所示位置：

（2）菜单—项目(P) —部署项目—离线部署

申请

“离线部署管理”面板如下图所示：

根据需求选择对应的离线部署包类型（临时部署、永久部署）进行申请。

在弹出的对话框中选择需要部署离线部署包的服务器系统（Windows、Linux）。

确认后，“离线部署管理”面板中将新增一条“离线部署包”记录，“操作”栏会显示部署包生成百分比，请耐心等待“离线部署包”生成。

下载

“离线部署包”生成后，即可进行下载操作，点击“下载”按钮，将“离线部署包”下载至本地。

安装

Windows 服务器

将获取到的 Windows 版本的“ThingJS 项目离线部署包”压缩包解压至需要部署的目录下，解压后如下图所示：

双击运行 start.exe 即可启动离线部署服务，离线部署服务默认的端口号为 9000，如需修改请参考第 4.1 节的内容。服务使用期间，请勿关闭服务控制台窗口。

Linux

将获取到的 Linux 版本的“ThingJS 项目离线部署包”压缩包解压至需要部署的目录下。注意：需使用 7za 解压，命令为：7za x offline.zip -r -o./offline。

解压后文件结构如下图所示：

通过命令 chmod u+x start 为 start 文件增加执行权限。

执行 start 启动服务，离线部署服务默认的端口号为 9000，如需修改请参考第 4.1 节的内容。

为保证进程能够保持在后台运行，可在 screen（多重视窗管理程序）中执行，或使用其他后台执行的方法。

可通过命令 netstat –napl | less 或 ps axu | grep start | less 查看端口情况。

若要关闭离线部署服务，可通过 kill -9 PID 命令结束相应进程。

配置

本章介绍了几种常见的“ThingJS 项目离线部署包”支持的配置方法，请勿自行更改未说明的离线部署包中其他的文件内容，以免发生不可预期的部署问题，导致部署失败。

修改服务启动端口

“ThingJS 项目离线部署服务”默认端口号为 9000，可以通过配置离线部署包中 system\conf 目录下的 application.properties 文件来修改端口号。

用文本编辑器打开 application.properties，修改 server.port 为新端口号。

注意不要和原来的服务端口冲突，若端口冲突会无法启动离线部署服务，如下图所示：

配置 HTTPS 访问（可选）

（注：若服务不需要开启 HTTPS 访问，可跳过该节。）

通过配置 Nginx，开启 HTTPS 服务，并代理到离线部署服务，配置如下图所示：

修改登录密码

为确保离线部署项目的安全，请在首次使用默认密码登录后尽快修改登录密码。

成功登录“项目离线部署管理”界面后，如图所示，点击“修改密码”，

在弹出的对话框中输入需要修改的新密码，即可完成登录密码的修改。

密码将以“密文”的形式保存在离线部署包 system\conf 目录下的 application.properties 文件中，如忘记密码，可自行“删除”配置文件中的密码设置项，即可自动恢复默认密码（admin），如下图所示。

（注：请勿擅自填写密码设置项的内容。）

瓦片地址服务配置

对于离线的地图项目，因为地图瓦片资源数据量较大，这部分内容的离线需要开发人员自己来做。当前支持加载 ZXY 格式的地图服务，如果已有自己的地图服务，可在创建地图的时候设置，方法如下：

打开部署目录下的 web\map.json 文件，找到配置瓦片图层的地方：

倾斜摄影数据配置

ThingJS 3D 可视化平台支持倾斜摄影数据，若需要在项目中使用倾斜摄影，平台提供倾斜摄影 osgb 数据转换处理上图服务，可咨询平台客服。

在项目离线部署时，请将 ThingJS 平台为您转换处理后的倾斜摄影数据复制到部署目录的\web\lib 文件夹下，需保证路径中有正确的 tileset.json 文件以及相对的倾斜摄影文件夹。如下图所示：

然后需要手动修改离线部署包中的主脚本，将 3dtiles 的服务地址更换为离线部署包相对地址“./lib/tileset.json”。如下图所示：

单服务器多项目部署配置

在默认情况下，仅可以下载单服务器单项目部署包，如有单服务器部署多项目的需求，需要购买“单服务器多项目部署授权”。

购买“单服务器多项目部署授权”后，将拥有下载多项目对应的“项目资源包”的功能，该“项目资源包”含有项目资源文件及对应的更新程序。

将得到的“项目资源包”解压至已离线部署的根目录下，如下图所示。

Windows 环境下可以直接执行更新程序update.exe ，Linux环境下执行./update。执行前确保原部署服务已停止，否则无法正确完成更新。

已部署的离线部署包将升级为“单服务器多项目部署包”，重新启动离线部署服务 ，向官方申请对应项目数的“多项目授权码”，授权通过后，即可通过“/project/目录名/”的方式访问对应的项目。

服务请求配置

离线部署服务请求 Response Headers 中 Access-Control-Allow-Origin 默认不允许跨域，可以通过配置离线部署包中 system\conf 目录下的 application.properties文件来修改。如下图所示，修改 server.origin 为允许请求的 origin 白名单。

授权

访问“项目离线部署管理”界面

根据服务启动信息，访问“项目离线部署管理”界面（http://ip:port/admin）。

访问“项目离线部署管理”界面，需要进行登录操作，用户名和密码初始默认都为“admin”（为确保离线部署项目的安全，请在首次登录后尽快修改密码，参考第 4.3 节内容），登录界面如下图所示：

登录成功后即可进入到“项目离线部署管理”界面，如下图所示：

授权“临时部署包”

ThingJS 3D 可视化开发平台当前有效的“VIP 商业开发者”，可在“ThingJS 在线开发平台”（https://www.thingjs.com/guide/?m=sample） 获取7天临时授权码文件对“临时部署包”进行授权。请按以下章节描述的步骤逐步进行操作。

下载机器码文件

首先在机器码文件列表中，下载当前有效的机器码文件：

将该机器码文件下载至本地：

申请临时授权码文件

访问“ThingJS 在线开发平台”，打开部署项目（如本例所示，部署项目为“0dh22110151”）的“离线部署管理”面板，找到机器码文件对应的离线部署包的记录，点击 “上传机器码文件”按钮。

如本例所示，机器码文件为“xxx_0dh22110151_211019134038_211019152410_B.mach”，需找到对应的离线部署包“xxx_0dh22110151_211019134038”进行授权申请：

在弹出的对话框中上传对应的机器码文件（3.2.0 版本以下的离线部署包用户，可通过粘贴机器码的方式获取）。

成功上传正确的机器码文件后，即可申请获取对应的授权码文件（本例中对应的授权码文件为“xxx_0dh22110151_211019134038_xxxxxxxx_B.lic”），下载授权码文件到本地。如图所示：

完成授权

返回到“项目离线部署管理”界面，在当前有效的机器码文件一栏中选择“授权”按钮，上传所获取的对应的授权码文件。

如本例所示，为机器码文件“xxx_0dh22110151_211019134038_211019152410_B.mach”，上传对应的授权码文件“xxx_0dh22110151_211019134038_xxxxxxxx_B.lic”，即可完成授权。

授权成功后，可通过点击“预览”按钮直接进行项目预览，或通过访问根目录链接进行项目预览。

需要注意的是，“临时部署包”通过“临时授权码”授权成功后，有效期为 7 天。如需永久授权，请更新升级为“永久部署包”（参考第 6 章），或直接使用“永久部署包”进行授权。

授权“永久部署包”

“永久部署包”必须使用“永久授权码”进行授权激活。

同 5.2.1 所述，需先获得离线部署包当前有效的“机器码文件”，然后将该“机器码文件”发送给 ThingJS 平台商务人员，获取离线部署包对应的“永久授权码文件”，最后返回到“项目离线部署管理”界面，同 5.2.3 所述完成“永久部署包”的授权。

更新

为方便开发人员对已部署的“ThingJS 项目离线部署包”进行项目内容的更新，“ThingJS 项目离线部署包”提供“更新项目”的功能。

获取“更新部署包”

首先，同第 2 章所述，获取一个当前已部署项目对应的需要进行更新的“离线部署包”（只可更新当前已部署项目的离线部署包）作为“更新部署包”，需要注意的是，只有“永久部署包”才可以作为“更新部署包”进行项目更新。

更新项目

在“项目离线部署管理”界面中，切换页签到“更新项目”，点击“上传更新包”按钮，上传获取到的“更新部署包”。

如果您当前已部署的“离线部署包”为“临时部署包”，“更新项目”成功后，当前“临时部署包”自动更新升级为“永久部署包”，当前的临时授权将失效，升级为“永久部署包”后，需对该“永久部署包”进行“永久授权”（参考第 5.3 节内容）。

如果您当前已部署的“离线部署包”为“永久部署包”，“更新项目”将仅更新项目内容，并不会影响已有授权。

更新成功，并正确授权后，即可预览更新项目内容后的离线部署项目。

迁移

变更部署服务器，或改变部署服务器的硬件信息（如硬盘、CPU、网卡等）需重新授权，如确需对已永久部署的“ThingJS 项目离线部署包”进行环境变更，请按本章节内容迁移“ThingJS 项目离线部署包”。

获取新机器码文件

首先，获取到需要在新服务器环境中部署的离线部署包（永久部署包），该部署包可以是已永久部署的离线部署包的副本，也可以按第 2 章所述获取当前已部署项目的新的离线部署包（永久部署包）。

将获取到的离线部署包正确部署到新的服务器环境中，启动后访问部署在新服务器环境中的离线部署包的“项目离线部署管理”界面，下载当前有效的新的“机器码文件”至本地。

获取迁移码文件

返回到已永久部署的离线部署包的“项目离线部署管理”界面，点击“迁移”按钮，获取“迁移码文件”。

（注：执行迁移操作后，当前机器授权将失效，且无法再次授权激活。）

将生成的“迁移码文件”下载至本地。

获取新授权码文件

访问“ThingJS 在线开发平台”，打开已部署项目，点击“项目—更新项目”。

选择“离线部署迁移（在线开发）”。

在弹出的“离线部署迁移”面板中，从上到下依次上传 7.2 节获取的“迁移码文件”，和 7.1 节获取的“新机器码文件”。

成功上传该项目对应的正确的“迁移码文件”和“新机器码文件”后，即可申请“新机器码文件”对应的新的“授权码文件”，如下图所示：

完成新服务器的授权

访问部署在新服务器环境中的离线部署包的“项目离线部署管理”界面，在当前有效的机器码文件一栏中选择“授权”按钮，上传 7.3 节中获取的新的对应的授权码文件，即可完成新服务器的授权。

常见问题（FAQ）

Q1. 在线开发正常运行项目，离线部署后访问 127.0.0.1:9000，3D场景展示出错

答：用于部署的网络服务器一般不强调显示，故显卡较差，甚至无独立显卡。而 3D 场景显示对显卡要求较高，直接在服务器上 127.0.0.1 访问，服务器显卡不足以支持 3D 场景渲染展示，往往场景会显示出错。故可用有独立显卡的客户机浏览器访问该服务器场景，来验证 3D 场景显示是否正常。

Q2. Windows 环境下，start.exe 启动失败

答：常见的 start.exe 启动失败、发生闪退的情况是，当前 Windows 环境中离线部署服务的端口号已被其他服务占用，请检查端口占用情况，或为离线部署服务配置其他可使用的端口号。

Q3. Windows 环境下，start.exe 卡住，服务无反应

答：这种情况一般是鼠标不小心点击了服务程序窗口，导致服务程序暂停，需手动于服务程序窗口中敲击回车来解决。

Q4. 地图瓦片和离线前不一致

答：原因主要是地图瓦片资源未离线打包，打包时默认带了谷歌影像前 5 级的瓦片，所以我们需要参考第4.3节替换地图瓦片服务。关于支持的地图瓦片服务(ZXY 标准瓦片)格式说明如下：将地图全幅显示时的图片从左上角开始，往下和往右进行切割，切割的大小默认为 256*256 像素，左上角的格网行号为 0，列号为 0，往下和往右依次递增。如下图所示：

目前主流互联网地图基本都使用该格式地图瓦片，ArcGIS Server、SuperMap iServer 发布的地图瓦片服务也是 ZXY 标准瓦片。

Q5. 场景、模型未离线打包

答：一般情况，离线程序会自动打包项目所引用场景和模型，因为开发人员程序写法多样，离线程序很难一一识别，所以加了 cps 配置文件，辅助打包。如遇项目引用场景或模型未离线打包的情况，需在在线开发中自行配置项目对应的 cps 文件并重新打包。

cps 文件配置方法如下：

例如，在线开发中，需要进行离线部署的项目如下图所示：

项目中引用了一个场景 ('/api/scene/18ddd5cc8424cfcd7f7d7955)，和一个模型 ('/api/models/8CF6171F7EE046968B16E10181E8D941/0/gltf/')。点击打开当前项目下该项目对应的 cps 文件，初始 cps 文件内容如下图所示：

将 cps 文件下面的配置示例注释打开。

将需要离线的场景 URL 填入 scenes 配置项中，模型 URL 填入 models 配置项中。

保存后重新下载离线部署包。

场景文件将打包至离线部署包的/web/scene/目录下，模型文件将打包至离线部署包的/web/models/目录下。

Q6. 360 解压离线部署包有问题

答：360 压缩软件解压离线部署包会出现如下情况：

请使用 7-Zip 或其他支持 7z 格式的压缩软件进行解压。

Q7. 倾斜摄影数据访问不到，控制台报错 404

答：两种解决方案。

方案一：将 web/lib/tileset.json 该文件中的特殊字符‘+’进行转义处理，使用编辑器打开该文件之后，全局替换‘+’字符变成‘%2B’字符。修改之后，保存即可。重新刷新项目之后既可访问。

方案二：单独启动一个服务，来访问倾斜摄影的数据，推荐使用 node.js 启动服务。首先在命令行中安装 http-server 服务，可以输入 npm install http-server –g 进行安装。安装完成之后进入 web\lib 目录下，输入命令 http-server --cors -p 8088，来启动服务。启动之后修改脚本中倾斜摄影地址为 http://{本机 ip}:8088/tileset.json 即可。

Q8. ChartBuilder 项目离线部署后看不到图表内容

答：需要在访问端口后拼/chart 来查看 ChartBuilder 项目，例如：http://127.0.0.1:9000/chart（服务地址:服务端口/chart）

Q9. ChartBuilder 项目离线部署后显示 127.0.0.1 拒绝了连接请求

答：ChartBuilder 项目离线部署后，默认为 3D 内容配置的是本地 9000 端口，如使用 ip+自定义端口的方式访问，需要自行修改 scene.def 文件中的 iframeURL 为使用的 ip+端口。如下图所示：

Q10. ThingJS项目离线部署包V3.2.0版本与旧版本相比，有什么区别

答：ThingJS项目离线部署包V3.2.0版本与旧版本相比.区别如下：

（1）增加了“项目离线部署管理”界面；

（2）强调了“临时部署包”和“永久部署包”两个概念，具体请查看本文档的第1.3节内容；

（3）原“机器码”、“授权码”全部升级为“文件”的形式；

（4）新增“登录”功能；

（5）新增“更新项目”功能；

（6）完善“日志系统”，如遇到部署问题请下载日志文件发送给平台客服人员；

（7）完善“错误码信息”，如遇到授权失败问题，请先查看本文档第9章的“错误码对照表”。

Q11. 更新项目后，控制台接口“/get/PublicKey”报404

答：是后台程序未更新，导致接口“/get/PublicKey”没有请求到，请手动将离线部署包中的start程序替换为最新版本并重启。

Q12. 9.12服务配置在二级路由下，控制台报错404

答：两种解决方案。

方案一：Nginx配置如下两个路径。注：bigMap为需要的二级路由名

方案二：手动将项目中引用到的绝对路径改为相对路径。

错误码对照表