渲染节点配置文件

## 写在前面（请先读）

渲染节点配置入口，通常放在安装目录下的：

`larkxr-render/application.properties`

改完后一般需要 **重启渲染节点相关服务（含 Agent / 渲染服务）** 才会全部生效。

### 使用原则

1. **只改需要改的项**，其余保持安装包默认即可。  
2. **不要删配置项名称**，只改等号右边的值。  
3. 若某项在本文件中 **没有出现**，但业务上确实需要改，请在本文件 **末尾追加**。  
4. Windows 路径里的反斜杠写成 **双反斜杠**，例如：`D:\\larkxr\\appli`；路径 **结尾不要带斜杠**。  
5. 以 `#` 开头的是注释；需要启用被注释的行时，去掉行首 `#`。  
6. 本机有多张网卡、或管理节点不在本机时，请务必核对本文件中的 **IP / 管理端地址**。

### 配置值怎么写

| 类型 | 写法示例 | 说明 |
|------|----------|------|
| 开关 | `true` / `false` | 开 / 关 |
| 端口 | `10002` | 纯数字 |
| 地址 | `192.168.0.18` 或 `http://192.168.0.20:8181` | 不要多余空格 |
| 空值 | `某配置=` | 等号右边留空表示不填 |
| 列表 | `192.168.0.11,192.168.0.12` | 多个用英文逗号分隔 |

## 一、部署形态与管理端地址

### `pxy.host.as-admin-render-mixed-node`

**做什么：** 管理节点和渲染节点是否装在 **同一台机器**（单机一体）。

| 值 | 含义 |
|----|------|
| `true` | 单机版：本机既有管理后台，又跑渲染（Standalone 常见） |
| `false` | 分离部署：本机只做渲染，管理端在别的机器 |

**建议：** 单机交付保持 `true`；独立渲染机改成 `false`，并正确填写下面的管理端地址。

---

### `pxy.admin-server.url`

**做什么：** 中心管理服务器地址（渲染节点要向谁注册、听谁调度）。

**格式示例：** `http://192.168.0.20:8181`  
**单机常见：** `http://localhost:8181`（实际端口以管理端 `server.port` 为准，很多版本是 `8184`，请与管理后台一致）

**说明：**

- 管理端不在本机时，必须改成管理机的真实 `http://IP:端口`。  
- 若写成 `localhost`，系统有时会用本机局域网 IP 替换；多机部署请直接写管理机 IP，更稳妥。

---

## 二、本机网络与节点身份

### `pxy.host.local-ip`

**做什么：** 本机 **私网 / 局域网 IP**。

其他节点、管理端通常靠这个地址找到本渲染机。多网卡时务必填对要用的那张网卡 IP。

---

### `pxy.host.public-ip`

**做什么：** 本机 **公网 IP**。

通常不需要填写，只有当管理节点和渲染节点不在一个局域网中的时候填写。

---

### `pxy.host.prefer-public-ip`

**做什么：** 通过 **端口映射** 对外提供服务时，希望对外使用的公网 IP。

例如内网机经路由器映射出去，这里填映射用的公网地址。不需要可留空。

---

### `pxy.host.preferred-networks`

**做什么：** 多网卡时，优先选用哪个 **IP 前缀** 作为本机 IP。

示例：希望用 `192.168.10.x` 网段，可填 `192.168.10`。  
`local-ip` 已手动填准时，这项可留空。

---

### `pxy.host.probe-public-ip-url` / `pxy.host.probe-prefer-public-ip-url`

**做什么：** 是否通过访问某个 URL **自动探测外网 IP**。

示例：`https://api.ipify.org`  
是否开启按场景决定：能手动填公网 IP 时，可不配；动态公网或不好记时再开。探测失败不影响内网部署，但公网相关能力可能不准。

---

### `pxy.host.node-name`

**做什么：** 渲染节点在集群里显示的名称。

示例：`Node-01`  
多台机器请起不同名字，方便在管理后台辨认。

---

### `pxy.host.region-id` / `pxy.host.region-name`

**做什么：** 本节点所属 **集群分区** 的 ID 和名称。

不做分区/就近分配时可留空；多地机房时按实施规划填写，并与管理端分区策略一致。

---

### `pxy.host.region-type`

**做什么：** 分区类型。

| 值 | 含义 |
|----|------|
| `0` | 非定向分区（默认常见） |
| `1` | 定向分区 |

按产品分区方案设置，勿随意改。

---

## 三、应用同步

### `pxy.sync.enable`

**做什么：** 本节点是否参与从中心/其他节点 **同步应用包**。

| 值 | 含义 |
|----|------|
| `true` | 开启同步（常见） |
| `false` | 不同步（仅特殊场景，如全靠本地已安装应用） |

---

### `pxy.sync.usable-low-limit`

**做什么：** 磁盘剩余空间下限，单位 **GB**。低于该值会触发清理等相关逻辑。

客户包常见默认：`20`；工程 yaml 里也有 `15` 一类默认。按磁盘大小调整，太小容易装不下应用。

---

### `pxy.sync.max-duration`

**做什么：** 单次同步允许的最长时间，单位 **分钟**。超时按产品逻辑中止/失败处理。

常见默认：`300`（5 小时）。大包、慢网可适当加大。

---

### `pxy.sync.region-inner.enable`

**做什么：** 是否优先从 **同一分区内** 的节点拉应用包。

| 值 | 含义 |
|----|------|
| `true` | 开启：跨地区时可更快、少占外网带宽 |
| `false` | 关闭 |

**说明：** 写在渲染节点上只影响 **本节点**；管理端同类配置则影响整集群策略。

---

### `pxy.sync.delete-zip`

**做什么：** 解压完成后是否删除 zip 安装包。

| 值 | 含义 |
|----|------|
| `false` | 保留 zip（便于再次分发/分区内同步，占磁盘） |
| `true` | 删 zip 省空间；需结合「是否还要给别人当同步源」「中心存储是否可靠」综合考虑 |

---

## 四、本地 / 共享存储

### `pxy.storage.appli-save-path`

**做什么：** 应用程序包在本机的保存目录（**结尾不要带目录符**）。

示例：

```properties
pxy.storage.appli-save-path=D:\\larkxr\\appli
```

留空时：单机混合部署往往会落到管理端旁的默认 `appli` 目录；独立渲染机则用本节点安装目录下的 `appli`。

可配置多个存储路径（多磁盘场景），按产品约定用列表形式填写；一般现场先配一个即可。

---

### `pxy.storage.disk-share-node-list`

**做什么：** 多台机器共用同一块共享盘（如 NAS）时，填写 **共用该盘的节点 IP 列表**。

单机或每台本地盘可留空。

---

### `pxy.storage.disk-share-with-admin`

**做什么：** 渲染节点是否与管理节点 **共用同一块应用盘**。

| 值 | 含义 |
|----|------|
| `false` | 不共用（常见） |
| `true` | 与管理端共享磁盘 |

按存储架构选择。

---

## 五、阿里云 OSS

### `pxy.storage.type.oss.endpoint`

**做什么：** 本节点访问阿里云 OSS 的接入地址。

| 场景 | 建议 |
|------|------|
| 节点都在阿里云同一 VPC | 用 **内网** endpoint，省流量（需去掉注释并改成对应地域内网地址） |
| 跨公网、跨机房 | 用 **外网** endpoint，如 `oss-cn-beijing.aliyuncs.com` |

不用 OSS 时，可按实施要求留空或保持默认；实际能否拉包还取决于管理端存储类型与密钥。

---

### `pxy.storage.type.oss.downloadType`

**做什么：** OSS 下载方式。

| 值 | 含义 |
|----|------|
| `1` | 分片下载 + 断点续传（推荐，大包更稳） |
| `2` | 流式下载 |
| `3` | 整体下载到本地文件 |

一般保持 `1`。

---

## 六、Agent 代理服务（渲染侧配套）

> 客户包里的 `pxy.agent-server.*` 描述「代理服务」地址；工程里 Agent 自身监听端口对应 `server.port`（常见 `8089`）。现场以安装包说明为准，改端口时注意防火墙一并放行。

### `pxy.agent-server.ip`

**做什么：** 代理服务 IP，通常为本机，常见 `localhost`。

---

### `pxy.agent-server.port`

**做什么：** 代理服务端口。常见 `8089`。

若与工程 `server.port` 一致，改一端时要考虑另一端是否也要同步（按交付组件实际读取关系确认）。

---

## 七、渲染服务连接与上报

### `pxy.render-server.connect-agent-timeout`

**做什么：** 渲染服务连接本机 Agent 的超时时间，单位 **毫秒**。默认常见 `3000`。

机器忙或启动慢时可适当加大。

---

### `pxy.render-server.rpt-interval.rsc-monitor`

**做什么：** 资源监控（CPU/GPU/内存等）上报间隔，单位毫秒。建议范围 **2000–5000**。

---

### `pxy.render-server.rpt-interval.task-status`

**做什么：** 任务状态上报间隔，单位毫秒。建议 **2000–5000**。

---

### `pxy.render-server.rpt-interval.vr-performance`

**做什么：** VR 性能指标上报间隔，单位毫秒。建议 **2000–5000**。

间隔过小增加开销；过大则管理端看到的状态刷新变慢。

---

## 八、渲染监听地址、端口与证书

### `pxy.render-server.listen-ip`

**做什么：** 渲染服务监听的 IP。留空通常表示按默认网卡/全部可用地址策略（以产品行为为准）。多网卡需要绑定时再填。

---

### `pxy.render-server.listen-port`

**做什么：** 渲染服务 TCP 端口。默认常见 `10002`。  
防火墙、安全组、端口映射都要放行。

---

### `pxy.render-server.ssl-port`

**做什么：** 渲染服务 SSL（HTTPS/加密）TCP 端口。默认常见 `10004`。

---

### `pxy.render-server.credential.key-file-name`

**做什么：** SSL 私钥文件名（`.key`）。使用 HTTPS 且需要 RTT 探测等能力时配置。

---

### `pxy.render-server.credential.crt-file-name`

**做什么：** SSL 证书文件名（`.crt`）。证书文件一般放在节点安装目录下的证书目录（如 `ssl-cert`），按实施文档放置。

---

### `pxy.render-server.credential.cert-domain-url`

**做什么：** 证书对应的域名。单域名证书有时能自动读出；多域名/通配符证书请手动填写。

---

### `pxy.render-server.client-timeout`

**做什么：** 客户端连接超时，单位毫秒。常见默认 `20000`。

---

### `pxy.render-server.larkxr.appli-port`

**做什么：** 应用连接 LarkXR 使用的端口。常见 `10003`。

---

### `pxy.render-server.udp-min` / `pxy.render-server.udp-max`

**做什么：** 流媒体 **UDP 端口区间**。

示例：`10011`–`10040`  
做端口映射对外服务时，**每台节点区间不要冲突**，并在路由器/防火墙上映射完整区间。

---

### `pxy.render-server.stream-timeout`

**做什么：** 流媒体连接超时，单位毫秒。常见 `30000`。

---

### `pxy.render-server.taskinfo.delay-close-duration`

**做什么：** 延迟关闭任务时等待的时长（毫秒）。常见 `20000`。用于避免短暂断线立刻杀任务等场景。

---

## 九、手柄、算力系数与 GPU

### `pxy.render-server.gamepad`

**做什么：** 使用的游戏手柄数量。`0` 表示不按手柄数量特殊配置（常见）。

---

### `pxy.render-server.coefficient`

**做什么：** 渲染服务器「异构因子 / 能力系数」。用于调度时衡量相对算力。常见默认 `100`。  
高性能机可调高、弱机调低，需与调度策略一起规划，不要随意乱改。

---

### `pxy.render-server.gpu-cnt`

**做什么：** 本机 GPU 数量。默认 `1`。  
主要在配置了「单卡最大并发上限」时有意义。

---

### `pxy.render-server.gpu-max-concurrent-cnt`

**做什么：** **单块 GPU** 允许的最大并发路数。`0` 表示不限制。

用于防止一卡跑过多数目导致卡顿。

---

### `pxy.render-server.gpu.blacklist`

**做什么：** 多 GPU 时，禁用某些 GPU（填 GPU-LUID）。  
LUID 可在渲染服务启动日志中查看。不需要禁用时留空。

---

## 十、默认分辨率与 VR 监听

### `pxy.render-server.resolution-width` / `resolution-height`

**做什么：** 渲染默认分辨率宽高。常见 `1920` × `1080`。  
实际应用还可能按应用配置/客户端适配覆盖。

---

### `pxy.render-server.vr.listen-ip`

**做什么：** VR 应用渲染监听 IP。一般可留空。

---

### `pxy.render-server.vr.random-port`

**做什么：** VR 渲染是否使用动态端口。

| 值 | 含义 |
|----|------|
| `false` | 固定/按既有端口策略（常见） |
| `true` | 动态端口 |

开动态端口时，防火墙策略更难写死，按实施要求选择。

---

## 十一、音频与退出行为

### `pxy.render-server.audio`

**做什么：** 是否开启声音支持。`true` 开启（常见）。

---

### `pxy.render-server.force-close`

**做什么：** 退出应用时是否强制关闭相关进程。`true` 更干净，避免残留；特殊调试可关。

---

## 十二、2D / 远程桌面（应用共享）模式

> 以下项面向 2D 共享会话场景。若现场只做 VR/3D 串流、不做 2D 桌面共享，多数可保持默认。

### `pxy.render-server.remote-desktop.single-session`

**做什么：** 是否「1 个用户账号对应 1 个 Session」。注释说明 **目前只支持 `true`**。

---

### `pxy.render-server.remote-desktop.session-cnt`

**做什么：** 预创建用户数量（在 `pre-create=true` 时）相关计数。常见示例 `3`。  
「一用户多 Session」类能力当前注释标明不支持，勿按旧文档乱配。

---

### `pxy.render-server.remote-desktop.keepalive-cnt`

**做什么：** 2D 模式保持存活的 session 数量相关配置。常见示例 `6`。

---

### `pxy.render-server.remote-desktop.pre-create`

**做什么：** 启动时是否提前创建 2D 用户。

| 值 | 含义 |
|----|------|
| `false` | 不预创建（常见） |
| `true` | 预创建，启动稍慢但首次接入可能更快 |

---

### `pxy.render-server.remote-desktop.random-psw`

**做什么：** 2D 模式是否使用随机密码。`false` 则用下面的固定密码。

---

### `pxy.render-server.remote-desktop.psw`

**做什么：** 2D 模式固定初始密码。  
属于敏感信息，生产环境请改成强密码并妥善保管。

---

### `pxy.render-server.remote-desktop.width` / `height`

**做什么：** 2D 模式分辨率。`0` 表示使用启动管理器里的配置；常见直接写 `1920`/`1080`。

---

## 十三、虚拟声卡

### `pxy.virtual-audio-driver.device-cnt`

**做什么：** 虚拟音频设备数量。`0` 表示不额外创建。  
需要多路独立音频捕获/播放时再按实施文档增加。

---

## 十四、ICE / TURN（连通与中继）

### `pxy.ice.server.uri`

**做什么：** TURN 服务器地址。格式示例：`turn:47.94.38.44:13478`

**自动填充说明（客户包注释）：**

- 单机且只有一个 IP 时，可能自动用本机 IP 拼 turn 地址；  
- 集群且已配置管理端 URL 时，可能自动用管理节点 IP 对应的 turn 地址。

一般可先留空让系统自动；有独立 TURN 时再手动填写。

---

### `pxy.ice.server.username` / `pxy.ice.server.password`

**做什么：** TURN 认证用户名和密码。必须与 Turn 服务端配置一致。

---

### `pxy.ice.transport`（可选，常被注释）

**做什么：** 穿透模式。

| 值 | 含义 |
|----|------|
| `1` | 仅走 TURN 转发 |
| `3` | P2P 或 TURN（默认常见） |

不写则通常按默认 `3`。纯受限网络可考虑强制 `1`。

追加示例：

```properties
pxy.ice.transport=3
```

---

## 十五、NAT 转发（无公网 IP 时）

### `pxy.nat-proxy.enable`

| 值 | 含义 |
|----|------|
| `false` | 关闭（有直连公网或不需要穿透时） |
| `true` | 开启 NAT 转发客户端 |

---

### `pxy.nat-proxy.client-mode.server-host`

**做什么：** NAT Server 的 IP 或域名。

---

### `pxy.nat-proxy.client-mode.server-port`

**做什么：** NAT Server 端口。常见 `20001`。

---

### `pxy.nat-proxy.client-mode.client-key`

**做什么：** NatServer 发放的接入密钥，必须一致。

渲染节点作为 NAT **客户端** 连到 NAT 服务；具体拓扑以实施文档为准。

---

## 十六、与管理端通信安全

### `pxy.security.admin-key` / `pxy.security.admin-secret`

**做什么：** 渲染节点与中心管理通信用的安全密钥。

**为什么需要：**  
默认常靠 IP 白名单放行；跨网、节点多、IP 不规则时白名单难维护，可改用密钥认证，减少加白名单的麻烦。

密钥需与管理端侧约定一致；留空则按默认白名单等方式处理。

---

## 十七、常见现场该改什么（速查）

| 场景 | 优先检查 |
|------|----------|
| 单机首次开机 | `as-admin-render-mixed-node=true`、`admin-server.url`、`local-ip`、`node-name` |
| 独立渲染机加入集群 | `as-admin-render-mixed-node=false`、管理端真实 URL、本机 IP、节点名 |
| 多网卡选错 IP | `local-ip` 或 `preferred-networks` |
| 需要公网访问 | `public-ip` / `prefer-public-ip` 或探测 URL；UDP/TCP 端口映射 |
| 应用同步慢/跨地区 | `region-inner.enable`、OSS 内外网 endpoint、磁盘空间下限 |
| 换应用存放盘 | `appli-save-path` |
| 共享 NAS | `disk-share-node-list`、`disk-share-with-admin` |
| 无公网 IP | `nat-proxy.*` |
| HTTPS / RTT 探测 | SSL 证书三项 + `ssl-port` |
| 限制单卡并发 | `gpu-cnt`、`gpu-max-concurrent-cnt` |
| 禁用某块显卡 | `gpu.blacklist`（查启动日志 LUID） |
| 跨网免白名单 | `admin-key` / `admin-secret` |

---

## 附录 A：

需要时请 **追加到 application.properties 末尾**。

### A1. 华为 OBS 接入点

```properties
# 按节点所在区域选择；管理端若用 OBS，渲染节点通常也要能访问对应 endpoint
pxy.storage.type.obs.endpoint=obs.cn-north-1.myhuaweicloud.com
```

### A2. 同步下载超时与分片（单位以产品实现为准，常见为秒 / MB）

```properties
pxy.sync.download.connectTimeout=15
pxy.sync.download.readTimeout=60
pxy.sync.download.defaultPartSize=100
```

### A3. 是否使用共享盘开关

```properties
pxy.storage.use-share-disk=false
```

### A4. 测试/运维类（生产慎用）

```properties
# true：模拟渲染节点上线（测试用）；生产必须 false
pxy.render-server.ignore-for-test=false
# 获取 GPU 信息失败时是否忽略错误
pxy.render-server.ignore-gpu-info=false
# 与管理端通信方式：0=WebSocket，1=REST API
pxy.render-server.admin-conn-mode=0
```

### A5. 夜间自动重启

```properties
pxy.render-server.night-reboot=false
# 格式 HH:mm，例如凌晨 3 点
pxy.render-server.night-reboot-time=03:00
```

### A6. Agent 自身 HTTP 端口（对应工程 server.port）

```properties
server.port=8089
```

若与 `pxy.agent-server.port` 同时存在，请保持一致，避免组件互相连错端口。

### A7. S3 相关（若交付启用 S3）

```properties
pxy.storage.type.s3.downloadType=1
pxy.storage.type.s3.max-concurrency=1
```

具体还要按管理端/存储方案补全密钥等项，以实施文档为准。

---