管理节点配置文件

## 写在前面（请先读）

本文件是 **面向客户现场修改** 的配置入口，通常放在安装目录下的：

`larkxr-admin/application.properties`

系统启动时会读取这里的配置。改完后一般需要 **重启管理后台服务** 才会生效。

### 使用原则

1. **只改需要改的项**，其余保持默认即可。
2. **不要随便删掉配置项名称**，只改等号右边的值。
3. 若某项在本文件中 **没有出现**，但业务上确实需要改（例如华为 OBS、渲染阈值、验证码开关等），请在本文件 **末尾追加** 对应配置行，格式见文末「附录」。
4. Windows 路径里的反斜杠必须写成 **双反斜杠**，例如：`D:\\larkxr-standlone\\appli`。
5. 带 `#` 开头的是注释，不会生效；需要启用某行时，去掉行首 `#`。

### 配置值怎么写

| 类型 | 写法示例 | 说明 |
|------|----------|------|
| 开关 | `true` / `false` | 开 / 关 |
| 端口 | `8184` | 纯数字 |
| 地址 | `192.168.1.10` 或域名 | 不要带多余空格 |
| 空值 | `某配置=` | 等号右边留空表示不填 |
| 列表 | `http://a.com,http://b.com` | 多个用英文逗号分隔 |

---

## 一、部署形态与服务端口

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

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

| 值 | 含义 |
|----|------|
| `true` | 单机版：一台机器既管后台，又跑渲染（Standalone 常见） |
| `false` | 分离部署：管理机和渲染机分开 |

**建议：** 单机交付包保持 `true`；多机集群改成 `false`。

---

### `server.port`

**做什么：** 管理后台 HTTP 服务监听端口。

**默认：** `8184`  
**说明：** 浏览器访问后台一般是 `http://服务器IP:8184`。若端口被占用，改成空闲端口，并同步改防火墙/反向代理。

---

### `server.node-ip`

**做什么：** 本机对外使用的服务器 IP（或可被其他节点访问到的地址）。

**说明：**

- 单网卡通常填本机局域网 IP，如 `192.168.0.28`。
- 留空时，部分功能会尝试自动识别；现场网络复杂时 **建议手动填写**。
- 后面数据库地址若写成 `${server.node-ip}`，会跟着这项走。

---

## 二、数据库

### `spring.datasource.server-address`

**做什么：** MySQL（或兼容库）所在主机地址。

**默认示例：** `${server.node-ip}`（跟上面的服务器 IP 相同）  
**多机时：** 若数据库装在别的机器，改成数据库机器的 IP。

---

### `spring.datasource.port`

**做什么：** 数据库端口。

**Standalone 常见默认：** `13306`（安装包内嵌数据库常用映射端口）  
**自建 MySQL 常见：** `3306`

按实际数据库端口填写。

---

### `spring.datasource.username` / `spring.datasource.password`

**做什么：** 数据库登录账号和密码。

**说明：** 必须与真实数据库账号一致，否则后台无法启动或无法读写数据。

---

### `spring.datasource.password-encrypt`

**做什么：** 配置文件里的数据库密码是否为 **加密后的密文**。

| 值 | 含义 |
|----|------|
| `false` | 明文密码（现场最常见） |
| `true` | 已按产品要求加密，系统会先解密再连库 |

**注意：** 当前项目内置 `application.yaml` 中通常没有这一项；客户包若已提供，按安装说明使用。不确定时保持 `false`，并使用明文密码。

---

## 三、Redis（缓存）

### `spring.redis.enable`

**做什么：** 是否启用 Redis。

| 值 | 含义 |
|----|------|
| `false` | 不用 Redis（单机/轻量部署常见） |
| `true` | 启用 Redis（集群、高并发或依赖缓存的功能时打开） |

打开后还需保证 Redis 服务可用，并配置密码等。

---

### `spring.data.redis.password`

**做什么：** Redis 访问密码。

仅在启用 Redis 时有意义。若 Redis 无密码，可留空（以现场 Redis 实际配置为准）。

**若还需改 Redis 主机/端口/库号**，请在本文件末尾追加（见附录）：

```properties
spring.data.redis.host=localhost
spring.data.redis.port=6379
spring.data.redis.database=0
```

---

## 四、WebSocket 代理与 HTTPS 测试证书

### `pxy.proxy.enable`

**做什么：** 是否开启 WebSocket 代理。

| 值 | 含义 |
|----|------|
| `true` | 开启（常见默认，便于客户端经管理端转发信令/数据） |
| `false` | 关闭 |

一般保持 `true`，除非有明确的自定义网关方案。

---

### `pxy.https.test-cert.enable`

**做什么：** 是否启用内置/测试用 HTTPS 证书相关能力。

| 值 | 含义 |
|----|------|
| `false` | 不使用测试证书（正式环境建议） |
| `true` | 开启测试证书（仅联调/临时 HTTPS 验证） |

**说明：** 当前项目 `application.yaml` 中通常没有这项；客户包有该项时，生产环境请保持 `false`，正式证书走 Nginx/负载均衡等正规方式。

---

## 五、应用同步与分区

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

**做什么：** 是否优先在 **同一分区（区域）内** 的节点之间同步应用包。

| 值 | 含义 |
|----|------|
| `false` | 不强制分区内优先（默认） |
| `true` | 开启：跨地区公网部署时可加快同步、少占外网带宽 |

**说明：**

- 写在管理平台上：对整个集群策略生效。
- 写在渲染节点上：通常只影响该节点。

单机或同机房小集群一般保持 `false`。

---

## 六、调度 / 分配策略（用户发起启动应用时怎么选机器）

### `pxy.dispatch-policy.auto-cal-region`

**做什么：** 是否自动按「域/分区」做就近分配。

| 值 | 含义 |
|----|------|
| `true` | 支持按域就近分配 |
| `false` | 不支持按域分配；系统本身未分区时，关闭可降低分配接口延迟 |

无分区需求时可考虑 `false`。

---

### `pxy.dispatch-policy.check-appli-reserve`

**做什么：** 分配时是否检查「预启动 / 预期启动」信息。

| 值 | 含义 |
|----|------|
| `true` | 检查（使用了预启动功能时必须为 true） |
| `false` | 不检查；此时系统里 **不要** 再配预启动信息，否则任务数量统计会不准 |

---

### `pxy.dispatch-policy.check-server-load`

**做什么：** 分配时是否检查服务器负载（忙不忙）。

| 值 | 含义 |
|----|------|
| `true` | 检查负载，尽量避开过载机器（推荐） |
| `false` | 不检查负载 |

---

### `pxy.dispatch-policy.check-appli-sync`

**做什么：** 分配时是否检查应用是否已同步到目标渲染节点。

| 值 | 含义 |
|----|------|
| `true` | 检查：未同步完的节点尽量不分配（推荐） |
| `false` | 不检查 |

---

### `pxy.dispatch-policy.enable-wait-queue`

**做什么：** 资源不足时是否开启 **排队等待**。

| 值 | 含义 |
|----|------|
| `true` | 开启排队：暂时没空位时进入等待队列 |
| `false` | 不排队：没空位通常直接失败/拒绝 |

---

### `pxy.dispatch-policy.enable-exclude-mode`

**做什么：** 是否开启 **独占模式**（资源独占相关策略）。

| 值 | 含义 |
|----|------|
| `false` | 关闭（默认） |
| `true` | 开启独占模式 |

按产品方案/合同能力开启，不要随意打开。

---

### `pxy.dispatch-policy.enable-multi-region-dispatch`

**做什么：** 是否支持 **跨多区域** 分配。

| 值 | 含义 |
|----|------|
| `false` | 关闭（单区域/默认） |
| `true` | 开启多区域分配 |

多地机房、多分区业务才需要打开。

---

## 七、接口限流

### `pxy.rate-limit.built-in.enable`

**做什么：** 是否开启系统内置限流，防止接口被刷爆。

| 值 | 含义 |
|----|------|
| `true` | 开启（推荐） |
| `false` | 关闭 |

压测或特殊联调可临时关闭，生产建议开启。

---

## 八、阿里云密钥（OSS 等）

### `pxy.ali-cloud.access-key-id` / `pxy.ali-cloud.access-key-secret`

**做什么：** 阿里云访问密钥，主要用于 **OSS 对象存储** 等云能力。

**说明：**

- 使用阿里云 OSS 存应用/图片时必填。
- 不用阿里云存储可留空。
- 密钥属于敏感信息，不要发给无关人员，不要提交到公开仓库。

---

## 九、对象存储通用项

### `pxy.storage.protocol`

**做什么：** 访问存储时使用的协议。

常见值：`http` 或 `https`  
按对象存储/下载地址实际支持的协议填写。

---

### `pxy.storage.img-bucket`

**做什么：** 存放图片的桶（Bucket）名称。默认 `image`。

---

### `pxy.storage.appli-bucket`

**做什么：** 存放应用包的桶名称。默认 `appli`。

---

### `pxy.storage.file-bucket`

**做什么：** 存放其他文件的桶名称。默认 `files`。

**说明：** 使用 OSS/OBS 时，请先在云控制台创建同名桶，或确认产品支持启动时自动创建。

---

## 十、本地存储

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

**做什么：** 上传文件/应用包在本地磁盘的初始保存路径。

**写法示例：**

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

留空时，系统通常使用安装目录下的默认 `appli` 路径。

---

### `pxy.storage.type.local.unzip-enable`

**做什么：** 上传后是否自动解压应用包。

| 值 | 含义 |
|----|------|
| `true` | 自动解压（常见） |
| `false` | 不解压 |

---

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

**做什么：** 使用共享磁盘时的节点列表（哪些节点共享同一块应用盘）。

一般单机留空；共享存储架构按实施文档填写。

---

## 十一、阿里云 OSS 接入点

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

**做什么：** 阿里云 OSS 的接入地址（Endpoint）。

**选用建议：**

| 场景 | 示例 |
|------|------|
| 集群都在阿里云同一地域 VPC 内 | 内网：`oss-cn-beijing-internal.aliyuncs.com`（省流量） |
| 跨公网、跨地域同步 | 外网：`oss-cn-beijing.aliyuncs.com` |

不用 OSS 时留空。地域代码按实际桶所在区域修改。

---

## 十二、与第三方系统的回调

### `pxy.collaboration.start-appli-callback`

**做什么：** 渲染任务 **开始** 时，回调您方业务系统的 URL。

例：`http://您的业务服务器/api/larkxr/start`  
不需要对接可留空。

---

### `pxy.collaboration.stop-appli-callback`

**做什么：** 渲染任务 **结束** 时的回调 URL。

不需要对接可留空。

---

## 十三、跨域安全（CORS）

### `pxy.security.access-control-allow-origin`

**做什么：** 允许哪些前端域名跨域访问管理接口。

**说明：** 用于限制客户端来源。配置 IP 时通常要带端口，例如：`http://192.168.0.10:8080`。多个用逗号分隔。留空则按产品默认策略处理。

---

### `pxy.security.upload-control-allow-origin`

**做什么：** **文件上传接口** 额外允许的来源域名列表。

上传页与后台不在同一域名时重点配置，防止无关站点调用上传接口。

---

## 十四、NAT 转发（没有公网 IP 时）

当渲染机在内网、外网客户端连不上时，可用 NAT 转发组件把流量“转”出去。

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

| 值 | 含义 |
|----|------|
| `false` | 关闭（有公网或不需要转发时） |
| `true` | 开启 NAT 转发 |

---

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

**做什么：** NAT 运行角色。

| 值 | 含义 |
|----|------|
| `client` | 管理节点作为 NAT **客户端**，去连独立的 NAT Server |
| `server` | 配合独立部署的 NAT 服务端模式使用 |

按实施方案选择，不要混用错角色。

---

### `pxy.nat-proxy.server-mode.api-server-address`

**做什么：** NAT Server 的 API 地址。

示例：`http://192.168.0.6:8183`  
管理节点与 NAT 服务不在同一台机器时必填；协议、IP、端口按实际改。

---

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

**做什么：** NAT Server 的 IP 或域名（client 模式必填）。

---

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

**做什么：** NAT Server 监听客户端连接的端口。默认 `20001`。

---

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

**做什么：** NatServer 下发的 ClientKey（接入密钥）。必须与 NAT 服务端一致。

---

## 十五、ICE / Coturn（穿透与中继）

### `pxy.ice.server.enable`

**做什么：** 是否启动内置 coturn / ICE 相关服务，辅助 WebRTC 在复杂网络下连通。

| 值 | 含义 |
|----|------|
| `true` | 启用 |
| `false` | 不启用 |

是否开启以交付方案为准；Windows/Linux 对 Turn 用户持久化能力有差异，按产品说明部署。

**若还需配置 realm 等**，可追加：

```properties
pxy.ice.server.realm=larkxr
```

---

## 十六、版本与授权

### `pxy.edition.type`

**做什么：** 产品发行版类型。

| 值 | 含义 |
|----|------|
| `0` | 国内版 |
| `1` | 海外版 |

按采购版本设置，勿随意改。

---

### `pxy.licence.type`

**做什么：** 授权方式。

| 值 | 含义 |
|----|------|
| `0` | 订阅制 |
| `1` | 授权码 |

与商务合同/交付授权方式保持一致。

---

## 十七、LarkXR Manager 托管组件开关

> 以下项在客户包 `application.properties` 中常见；当前工程内置 `application.yaml` 可能未列出。含义以「是否由管理器拉起/托管该组件」理解。

### `pxy.larkxr-manager.service.mysql.enable`

是否由 Manager 管理/拉起 MySQL 相关服务组件。单机一体常见 `true`。

### `pxy.larkxr-manager.service.nginx.enable`

是否由 Manager 管理 Nginx。需要 Manager 管 Web 反向代理时保持 `true`。

### `pxy.larkxr-manager.service.redis.enable`

是否由 Manager 管理 Redis。未用 Redis 时常为 `false`。

### `pxy.larkxr-manager.service.admin.enable`

是否由 Manager 管理 Admin 管理后台进程。通常 `true`。

**建议：** 无特殊运维方案时，保持安装包默认值；改前请与实施人员确认，避免 Manager 与手工启停冲突。

---

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

| 场景 | 优先检查的配置 |
|------|----------------|
| 单机首次开机 | `server.node-ip`、数据库地址/端口/密码、`as-admin-render-mixed-node=true` |
| 改后台访问端口 | `server.port` |
| 数据库在别的机器 | `spring.datasource.server-address` / `port` / 账号密码 |
| 启用 Redis | `spring.redis.enable=true` + Redis 密码/主机端口 |
| 用阿里 OSS | 阿里云 AK/SK、`oss.endpoint`、三个 bucket、`storage.protocol` |
| 本地存应用包 | `appli-save-path`、解压开关 |
| 无公网 IP | `pxy.nat-proxy.*` 整组 |
| 对接客户业务系统 | start/stop callback |
| 限制上传来源 | 两个 CORS 相关项 |
| 多地机房 | 分区同步、多区域分配、就近分配相关项 |

---

## 附录 A：当前项目有、但properties 没有的配置

下面这些配置现场若需要调整，请 **追加到 `application.properties` 末尾**
### A1. 管理节点是 Docker，是否开启「本地已安装」

```properties
#管理节点是 Docker：默认会藏掉「本地已安装」；只有设成 true 才会显示。
#当管理节点是Docker 渲染节点是Windows 可以打开这个开关
pxy.storage.enable-deploy-local-exe-app=false
```

### A2. 华为云 OBS

```properties
# 三者都填才会启用 OBS；桶名仍用 pxy.storage.appli-bucket / img-bucket 等
pxy.storage.type.obs.endpoint=obs.cn-north-4.myhuaweicloud.com
pxy.storage.type.obs.ak=您的AK
pxy.storage.type.obs.sk=您的SK
```

### A3. 渲染服务器资源阈值 / 2D 共享会话数

```properties
pxy.render-server.resource-alarm-threshold=85
pxy.render-server.cpu-limit=90
pxy.render-server.memory-limit=90
pxy.render-server.gpu-limit=90
# 0 表示不检查显存占用；建议不超过 90
pxy.render-server.gpu-memory-limit=90
pxy.render-server.remote-desktop.enable=true
# 每块 GPU 支持的 2D 共享并发路数，单卡建议 5
pxy.render-server.remote-desktop.session-cnt-per-gpu=5
```

### A4. 客户端体验相关

```properties
pxy.client.log-level=warn
# 单位：秒
pxy.client.rtt-limit-interval=30
pxy.client.rrt-limit=80
pxy.client.share-url=true
```

### A6. 心跳清理时长（毫秒）

```properties
# 节点多久没心跳视为下线
pxy.clear-job.server-no-heartbeat-duration=12000
# 任务多久没心跳视为关闭
pxy.clear-job.taskinfo-no-heartbeat-duration=20000
```

### A7. 同步并发数 / 启动重置集群状态

```properties
# 同时同步的最大数量
pxy.sync.max-sync-cnt=3
# 启动时是否把集群状态重置为离线
pxy.cluster.reset-on-startup=true
```

### A8. Manager 延迟启动（开机自启场景）

```properties
# 开机后延迟多少秒再启动 LarkXR 服务，单位：秒
pxy.larkxr-manager.start-delay-time=10
```

### A9. 地图密钥（后台用到地图能力时）

```properties
pxy.map.baidu.ak=
pxy.map.baidu.sk=
pxy.map.amap.ak=
pxy.map.amap.sk=
```

### A10. 本机网络相关（多网卡时）

```properties
# 优先使用的网段，用于自动选 IP
pxy.host.preferred-networks=
pxy.host.local-ip=
```

### A11. WebSocket 代理类型

```properties
pxy.proxy.type=ws
```

### A12. Tomcat 连接能力（高并发时才改）

```properties
server.tomcat.max-connections=10240
server.tomcat.threads.max=1000
server.tomcat.threads.min-spare=50
server.tomcat.accept-count=1000
```

> 未列出的内部项（日志路径、Flyway、Thymeleaf 等）一般 **不需要客户修改**，保持产品默认即可。

---

## 附录 B：追加配置的正确写法示例

在 `application.properties` **文件最后** 增加，例如：

```properties
########## 现场追加：华为 OBS ##########
pxy.storage.type.obs.endpoint=obs.cn-north-4.myhuaweicloud.com
pxy.storage.type.obs.ak=XXXX
pxy.storage.type.obs.sk=YYYY

########## 现场追加：关闭登录验证码（仅内网联调）##########
pxy.security.check-verify-code=false
```

保存后重启管理后台服务。

---

## 附录 C：与内置 application.yaml 的关系（给实施人员）

| 说明 | 内容 |
|------|------|
| 客户改哪里 | 安装目录下的 `application.properties` |
| 开发包里还有什么 | 工程内 `admin/src/main/resources/application.yaml` 更全 |
| 覆盖关系 | 外部 `application.properties` 通常用于覆盖/补充打包进程序的默认配置 |
| 两边都有的项 | 以现场最终生效的外部 properties 为准（改完需重启验证） |
| properties 没有的项 | 需要改时 → **追加到 application.properties**，不要只改源码里的 yaml 却不交付给客户 |

---

## 修改后检查清单

1. 配置文件编码建议使用 UTF-8，避免中文注释乱码。  
2. 无多余空格、未闭合引号、中文逗号。  
3. 端口、防火墙、安全组已放行。  
4. 数据库/Redis/OSS 账号密码与真实环境一致。  
5. 重启管理服务后，用浏览器打开 `http://服务器IP:端口` 验证可登录。  
6. 涉及存储切换时，到管理后台确认存储类型与桶/路径是否正确。

---

如有与贵司合同方案不一致的开关（独占、多区域、NAT、授权类型等），请以 **交付实施文档 / 厂商实施工程师指导** 为准。
`)

管理节点 配置文件

管理节点配置文件