安装和配置 Experience Service > 配置参数
  
配置参数
* 
如果使用安装程序安装 Experience Service，则这些参数由安装程序配置。
本节介绍了可用于配置 Experience Service 时所需的各种配置参数。这些配置参数的值可使用以下方法指定：
1. 启动服务时，在命令行中指定配置参数的值。具体方法为：在命令行中输入参数名称，前缀为双破折号 (--)，参数名称后面紧接着参数值。例如，--port 3000。
2. 使用环境变量来指定配置参数的值。具体方法为：创建一个名称与配置参数相对应的环境变量，并将环境变量的值设置为所需参数的值。除了嵌套配置参数之外，环境变量的名称应与配置参数相同。在这种情况下，分隔符必须使用双下划线 (__) 而不是点 (.)。例如，若要指定 db.connectionString 的值，创建的环境变量名称应为 db__connectionString。
3. 在服务的 configuration.json 文件 (位于根安装目录中) 中指定配置参数的值。
基本身份验证配置参数
* 
如果要配置单一登录身份验证，请参阅下面的“单一登录（SSO）身份验证配置参数”部分。
Experience Service 使用 ThingWorx 进行身份验证。安装程序会将 Experience Service 配置为使用您在安装过程中确定的 ThingWorx 服务器进行身份验证。
如有必要，您可以使用以下配置参数手动配置身份验证：
参数
说明
authentication.type
如果使用“基本身份验证”，则必须将此参数设置为 twxUser。
authentication.baseURL
用于进行身份验证的 ThingWorx 服务器的 URL。例如，https://twx.example.com:8443
authentication.authorization.appKey
Experience Service 读取 ThingWorx 群组成员身份时所需的 ThingWorx 应用程序密钥。群组成员资格用于决定用户所属的 Experience Service 角色及已授予的权限。
有关配置授权应用程序密钥的详细信息，请参阅配置对 ThingWorx 群组成员身份的访问权限。
authentication.authorization.refreshRate
该参数用于决定 Experience Service 各角色的成员身份与 ThingWorx 群组的成员身份之间的同步频率。该值以毫秒为单位。
默认情况下，该值设置为 5 分钟。该值的最快速度可以设置为 30 秒。
单一登录（SSO）身份验证配置参数
本部分介绍其他身份验证配置参数，以及为支持 Experience Service SSO 配置对现有配置参数所作的修改。
参数
说明
authentication.type
在配置 Experience Service 使用 SSO 时，必须将其设置为 openidUser。
authentication.baseUrl
ThingWorx 服务器的 URL。当使用基本身份验证时，该服务器用于身份验证，并且用于组成员资格同步 (无论身份验证类型)。例如，https://twx.example.com:8443。
authentication.authorization.refreshRate
该参数用于决定 Experience Service 各角色的成员身份与 ThingWorx 群组的成员身份之间的同步频率。该值以毫秒为单位。
默认情况下，该值设置为 5 分钟。该值的最快速度可以设置为 30 秒。
authentication.openid.issuer
将其值设置为与PingFederate 配置的“SSO 配置参数”部分所确定的 <as-base-url> 参数相同。
authentication.openid.clientId
将其值设置为与PingFederate 配置的“SSO 配置参数”部分所确定的 <es-client-id> 参数相同。
authentication.openid.clientSecret
将其值设置为与PingFederate 配置的“SSO 配置参数”部分所确定的 <es-client-secret> 参数相同。
authentication.openid.redirectUri
将其值设置为与PingFederate 配置的“SSO 配置参数”部分所确定的 <es-redirect-uri> 参数相同。
authentication.openid.session.maxAge
当用户通过使用 OpenID Connect 的 Experience Service 进行身份验证时，将为该用户创建一个会话。此属性指定：在会话失效且用户必须重新进行身份验证之前，会话有效的持续时间。此设置的默认单位为毫秒。但是，可以通过将单位名称附加到值来指定其他单位。例如，"10 hours"。支持下列单位：
• 秒：seconds、s
• 分钟：minutes、m
• 小时：hours、hrs、hour、h
• 天：days、day、d
authentication.openid.externalScope
这是使用 oauth2 访问 ThingWorx API 所必需的。此值应与 ThingWorx 中配置的值相同，以使用 ThingWorx 作为资源提供者。
authentication.openid.esScope
将其值设置为与PingFederate 配置的“SSO 配置参数”部分所确定的 <es-scope> 参数相同。
authentication.openid.studioClientId
输入 Studio 客户端 ID 的名称。此字段的默认值为 PTC_Studio_Client_ID。但是，若已将其配置为其他值，则必须在此处输入。
authentication.openid.claimsMapping.username
将其设置为 OpenID Connect Policy 中标识的 sub 属性的值。有关详细信息，请参阅OpenID 策略配置中的步骤 9。
下面是一个 JSON 示例，可用于配置 Experience Service 使用 OpenID Connect 和 OAuth2:
"authentication": {
"type": "openidUser",
"baseUrl": "https://twx.example.vuforia.io:8443",
"authorization": {
"appKey": "",
"refreshRate": "300000",
"useAclDbBackend": false
},
"openid": {
"issuer": "https://twx.example.vuforia.io:8443",
"clientId": "es-client",
"clientSecret": "es-client_1234",
"session:" {
"maxAge": "2 minutes",
"secret": "0c8ad6dkhd7976986knd87ea"
},
"externalScope": "THINGWORX"
}
},
内容存储
Experience Service 会将项目和表示等相关内容存储在文件系统中。使用以下配置参数可配置这些存储内容：
* 
如果在群集中部署 Experience Service，请确保群集中运行的所有实例都可访问这些数据存储目录 (projects.store、reps.store 和 upgrade.store)。
参数
说明
projects.storePath
项目内容存储目录的路径。
projects.staticOps.maxAge
指定将项目内容下载到客户端时的系统响应中最长时间标头的值。
reps.storePath
表示库内容存储目录的路径。
reps.staticOps.maxAge
指定将表示内容下载到客户端时的系统响应中最长时间标头的值。
upgrade.storePath
迁移程序成功文件存储目录的路径。这些文件用于表示升级迁移程序成功完成其数据迁移任务的时间，以免重复执行迁移。
* 
为这些配置参数指定的路径可以是绝对路径，也可以是相对路径。绝对路径以“/”开头，指向的是文件系统的根目录，而相对路径以“./”开头，指向的是 Experience Service 的安装目录。
数据库
Experience Service 支持以下数据库软件：
• SQLite
• PostgreSQL
* 
SQLite 会随 Experience Service 一起安装。PostgreSQL 必须单独获取和安装。
初次启动 Experience Service 时，它会在数据库中创建所有必要的表。使用以下配置参数可配置 Experience Service 所使用的数据库：
参数
说明
dbHandler
将此参数设置为以下任一值：
• SQLiteHandler (如果使用 SQLite)
• postgresHandler (如果使用 PostgreSQL)
db.datafilePath
此参数仅在使用 SQLite 并指定了 SQLite 数据文件路径时适用。Experience Service 在启动时如不存在数据文件，则会创建数据文件。
* 
为此配置参数指定的路径可以是绝对路径，也可以是相对路径。绝对路径以“/”开头，指向的是文件系统的根目录，而相对路径以“./”开头，指向的是 Experience Service 的安装目录。
在 Windows 上，绝对路径的开头可以是 "/" 或驱动器号，例如 "C:/"。如果绝对路径以 "/" 开头，则将该路径视为相对于驱动器的根目录 (包含 Experience Service 安装目录)。
db.connectionString
此参数仅在使用 PostgreSQL 并指定了 PostgreSQL 数据库的连接字符串时适用。连接字符串的格式如下所示：
postgres://<数据库用户名>:<数据库密码>@<主机>:<端口>/<数据库名称>
使用的凭据必须具有足够权限才能在 PostgreSQL 数据库中创建新的数据库表。
* 
如果使用的 PostgreSQL 实例与 ThingWorx 服务器上的相同，则 Experience Service 与 ThingWorx 服务器必须使用不同的数据库名称和登录/用户名。
域名
在某些情况下，Experience Service 必须知道用于访问其服务的域名。如果该 Experience Service 已在 Global Experience Index (GXI) 中注册，则 Experience Service 的域名必须与 GXI 中注册的域名相同。此值通常是 Experience Service 所在主机的完全限定域名 (FQDN)。但是，如果 Experience Service 部署在代理的后面，该值则为代理的 FQDN。
域名的值通常在安装时指定。但是，您也可手动配置域名，将 defaultDomainName 配置参数的值设置为相应的值即可。
IRS Federation
默认情况下，Experience Service 会配置为使用 IRS federation。在使用 IRS federation 时，如果 Experience Service 接收到针对其他域的 ThingMark 查询请求，则 Experience Service 会将此请求转发到该其他域注册的 Experience Service。Experience Service 会收集所有围绕该 ThingMark 发布的本地体验，并将这些体验与该域所注册 Experience Service 的返回结果结合在一起。
参数
说明
enable_irs_federation
将此参数设置为 true 可启用 IRS federation，而将其设置为 false 则禁用 IRS federation。
domain_id_resolver
查询来自其他 Experience Service 的体验时所用的基本 URL。此参数仅在启用 IRS federation 时是必填项。通常，必须使用 PTC 所提供的 Global Experience Index (GXI) 的基本 URL：
https://gxi.vuforia.io/VuforiaExperienceService/id-resolution/resolutions/
有关详细信息，请参阅标识解析服务（IRS）联合。
日志文件的位置
Experience Service 会将日志消息写入 stdout 和 stderr，以便管理员根据自己的部署环境采用相应方式来捕捉这些日志消息。如果将日志消息捕捉到了文件中，则可将 Experience Service 配置为允许具有相应权限的用户下载这些日志文件。有关捕捉和下载日志消息的详细信息，请参阅捕获日志消息。
使用以下配置参数可配置日志文件的位置：
参数
说明
logsPath
glob 模式，用于描述日志文件的相应路径。默认情况下，此参数被设置为 /var/logs/thingserver.log*。这样，/var/logs 中所有以 thingserver.log 开头的文件即可用于下载。
* 
为此配置参数指定的路径应以“/”开头，用于指定与文件系统根目录相对的路径。
在 Windows 上，绝对路径的开头可以是 "/" 或驱动器号，例如 "C:/"。如果绝对路径以 "/" 开头，则将该路径视为相对于驱动器的根目录 (包含 Experience Service 安装目录)。
端口
您可以使用端口配置参数来配置 Experience Service 侦听连接的端口。
代理
在代理后端部署 Experience Service 可能会影响服务的某些功能。trustProxy 配置属性可用于确保 Experience Service 在部署于代理后端时能够正常工作。正确配置此参数将确保 Experience Service：
• 对于在其日志消息中发送请求的客户端，包括正确的 IP 地址
• 对于体验列表中包括的体验 URL，使用正确的协议（例如，当响应由 Vuforia View 发送的 ThingMark 查询时）
trustProxy 配置属性的值决定了 Experience Service 确定客户端 IP 地址的方式，以及如何确定用于体验 URL 的协议。
trustProxy 设置
客户端 IP
协议
false (默认值)
发送请求的客户端的 IP
请求的协议
true
X-Forwarded-For 标头中最左侧的条目
X-Forwarded-Proto 标头的值
IP 筛选器条件
在筛选列表以移除匹配指定筛选条件的所有条目之后，X-Forwarded-For 标头中最右侧的条目（有关如何构建筛选条件的详细信息，请参阅下方内容）
X-Forwarded-Proto 标头的值
integer (n)
X-Forwarded-For 标头右侧第 n 个条目
X-Forwarded-Proto 标头的值
除了按上述内容配置 Experience Service 之外，还必须将代理配置为使用以下标头发送相应的信息：
• X-Forwarded-For
• X-Forwarded-Proto
以下选项可用于构建对 X-Forwarded-For 标头中 IP 地址进行筛选的条件。
筛选器选项
待筛选的地址
loopback
所有属于以下子网的地址：
• IPv4: 127.0.0.1/8
• IPv6: ::1/128
linklocal
所有属于以下子网的地址：
• IPv4: 169.254.0.0/16
• IPv6: fe80::/10
uniquelocal
所有属于以下子网之一的地址：
• IPv4: 10.0.0.0/8, 172.16.0.0/12, or 192.168.0.0/16
• IPv6: fc00::/7
<ip address>
指定的 IP 地址（例如，203.0.113.13）
这些选项可组合为以逗号分隔的列表，且要求至少包括其中一个子网选项。有关筛选条件的示例，请参阅下面的示例。
以下为 trustProxy 配置参数的有效设置示例。
用例
trustProxy 参数设置
忽略 X-Forwarded-* 标头中的信息。
false
将 X-Forwarded-For 标头中的所有条目 (最左侧除外) 视为已知的受信任代理。最左侧的条目被视为客户端 IP。
true
仅将本地主机视为已知的受信任代理。
"loopback"
将本地主机和 IP 地址 203.0.113.13 和 203.0.113.15 作为受信任的代理。
"loopback, 203.0.113.13,203.0.113.15"
将本地主机和本地网络上的任意主机视为已知的受信任代理
"loopback, linklocal, uniquelocal"
领域
安装程序会自动配置 Experience Service 所使用的领域，使其与 ThingWorx 服务器的领域相同。以下说明适用于您需要手动配置领域的情况。
Experience Service 可配置为向客户端发送的身份验证质询时在 WWW-Authenticate 标头中包含相应的领域。若要配置 Experience Service 应在 WWW-Authenticate 标头中包含的值，请将领域参数设置为所需领域的名称。
默认情况下，Experience Service 所使用的身份验证领域为：*。
以下是 ThingWorx 使用的默认身份验证领域：
• 对于 ThingWorx8.0 或更低版本，默认的身份验证领域为：*
• 对于 ThingWorx 8.1，默认的身份验证领域是：ThingWorx
* 
您的 ThingWorx 服务器可能已被配置为使用非默认的领域。
若要确定 ThingWorx 所使用的身份验证领域：
1. 打开终端，并在命令行中输入以下命令：
curl -is https://<ThingWorx-Core-Host-Port>/ThingWorx/Things | grep -i www-authenticate
其中，<ThingWorx-Core-Host-Port> 应替换为 ThingWorx 服务器的相应主机名和端口号。例如：
curl -is https://my-twx.example.com:3124/ThingWorx/Things | grep -i www-authenticate
2. 输出格式大致如下：
www-authenticate: Basic realm=*
realm= 后接的值应是 ThingWorx 服务器所使用的身份验证领域。
ThingWorx 代理
Experience Service 需要 ThingWorx 服务器进行用户身份验证和用户组成员身份管理。此外，Experience Service 服务器还可作为代理，用于由 Vuforia Studio 和 Vuforia View 共同使用的 ThingWorx 服务器。安装程序将 Experience Service 配置为代理在安装过程中确定的 ThingWorx 服务器。如有必要，您也可以使用以下配置参数手动配置 ThingWorx 代理：
参数
说明
proxies.0.autoRewrite
如果设置为 true，则 Experience Service 将更改 ThingWorx 服务器提供的所有重定向 URI，以使客户端通过代理重定向回来。例如，假设 Experience Service 的 ThingWorx 代理位于 https://es.example.com/Thingworx，并且被代理的 ThingWorx 服务器位于 https://twx.example.com/Thingworx。如果 ThingWorx 服务器将客户端重定向到 https://twx.example.com/Thingworx/something，则 Experience Service 会将此 URL 重写为 https://es.example.com/Thingworx/something。如果该属性设置为 false，则 Experience Service 不会重写这些重定向 URI。
proxies.0.protocolRewrite
该参数可标识重写重定向 URI 时使用的协议。例如，假设 Experience Service 在安全 HTTPS 模式下运行，但 ThingWorx 服务器在不安全 HTTP 模式下运行。在这种情况下，必须将此参数设置为与 HTTPS 相同，以便在重写重定向 URI 时，使用 Experience Service 代理所用的协议。
proxies.0.secure
如果设置为“true”，则 Experience ServiceThingWorx 代理将拒绝经过代理的 ThingWorx 服务器所使用的未经授权 (自签名) 证书。因此，如果被代理的 ThingWorx 服务器使用的是自签名证书，则必须将此参数设置为 false。
websocketProxies.0.autoRewrite
此参数用于控制 Web 套接字代理的重定向重写行为，方法与 proxies.0.autoRewrite 参数控制 HTTP 代理的重写行为相同。
websocketProxies.0.protocolRewrite
此参数用于控制重写 Web 套接字代理的重定向 URI 时所使用的协议，方法与 proxies.0.protocolRewrite 参数控制 HTTP 代理的重写行为相同。有效的协议选择是 ws 或 wss。
websocketProxies.0.secure
此参数控制 Web 套接字代理是否拒绝未经授权 (自签名) 证书的方法，与 proxies.0.secure 参数控制 HTTP 代理是否拒绝未授权 (自签名) 证书的方法相同。
proxies.0.disabled
如果设置为 true，则此参数将禁用 ThingWorx 代理。如果设置为 false，则将启用代理。
proxies.0.target
ThingWorx 服务器的基本 URL。此 URL 必须以“/Thingworx”结尾。例如，https://twx.acme.com:8443/Thingworx。
proxies.0.appKey
ThingWorx 应用程序密钥 ­ 用于 Experience Service 授予对 ThingWorx 数据的公开体验访问权限。有关公开体验和配置 ThingWorx 公开访问权限的详细信息，请参阅配置 ThingWorx 的公开访问权限。
websocketProxies.0.disabled
如果设置为 true，则此参数将禁用 ThingWorx Web 套接字代理。如果设置为 false，则将启用代理。
websocketProxies.0.target
基本 URL - 用于在客户端和 ThingWorx 服务器之间建立 Web 套接字连接。该 URL 必须兼容 proxies.0.target 的指定值。例如，如果将 proxies.0.target 设置为 https://twx.acme.com:8443/Thingworx，则必须将该参数设置为 wss://twx.acme.com:8443。
* 
请勿使用 Experience Service 的 ThingWorx 代理将 Edge 设备与混搭连接到 ThingWorx 服务器。而应该直接连接 ThingWorx 服务器 (使用替代端口、ELB 等)。Experience Service 的 ThingWorx 代理无法处理 EDGE 设备流量的相关工作负荷，而且部分 Edge SDK 也无法使用代理。
TLS 证书
* 
如果在群集中部署 Experience Service，请确保集群中运行的所有实例都可访问这些密钥和证书文件的位置。
默认情况下，Experience Service 使用 HTTPS 协议来加密服务和客户端之间的通信。
有关详细信息，请参阅传输层安全性 (TLS) 证书。
使用以下配置参数可配置用于加密的证书：
* 
可以为 PEM 属性 (httpsKeyPath、httpsCrtPath 和 httpsCaPath) 或 PCKS12 (PFX) 属性 (httpsPfxPath) 两者之一指定值，但不能同时指定两者。
参数
说明
httpsKeyPath
PEM 编码私钥所在文件的路径。
httpsCrtPath
PEM 编码公用证书所在文件的路径。
httpsCaPath
中间证书颁发机构的 PEM 编码公用证书所在证书包文件的路径。
httpsCertPassphrase
用于解密 PEM 编码私钥或 PCKS12 (PFX) 编码存档文件的密码短语。
httpsPfxPath
PCKS12 (PFX) 编码存档文件所在文件的路径。
* 
为这些配置参数指定的路径可以是绝对路径，也可以是相对路径。绝对路径以“/”开头，指向的是文件系统的根目录，而相对路径以“./”开头，指向的是 Experience Service 的安装目录。
在 Windows 上，绝对路径的开头可以是 "/" 或驱动器号，例如 "C:/"。如果绝对路径以 "/" 开头，则将该路径视为相对于驱动器的根目录 (包含 Experience Service 安装目录)。
可选参数
以下可选配置参数可手动添加到 configuration.json 文件。
参数
说明
nohttp2
添加此参数并将其设置为 true，以便将体验期间用相机小组件拍摄的图像保存到 ThingWorx 中的信息库。
例如：
{
…..
"nossl":true,
"nohttp2":true
}
高级模型目标参数
以下可选配置参数可手动添加到 configuration.json 文件。
参数
说明
hmtg.credentials.baseUrl
模型目标服务 URL。此参数预先填充。值为：
https://vws.vuforia.com
hmtg.credentials.tokenPath
OAuth2 身份验证的 HTTP 请求路径。此参数预先填充。值为：
oauth2/token
hmtg.credentials.amtgPath
高级模型目标生成的 HTTP 请求路径。此参数预先填充。值为：
modeltargets/advancedDatasets
hmtg.credentials.accessKey
必须从 PTC 技术支持获取此参数的值。有关详细信息，请参阅启用高级模型目标生成的申请信息。
hmtg.credentials.secretKey
必须从 PTC 技术支持获取此参数的值。有关详细信息，请参阅启用高级模型目标生成的申请信息。
发布参数
以下可选配置参数可手动添加到 configuration.json 文件。
参数
说明
publicAccess
对于 Vuforia Studio 中“访问”字段设置为“公开”的项目，禁用或启用发布这些项目的功能。
例如：
{
…..
"publicAccess":{
"disabled": true
}