# 驾驶舱开发／生产环境配置

## 配置分工

| 文件 | 用途 |
| --- | --- |
| [通用环境](<../.env>) | 旧插件开关维持 false，应用入口已彻底移除插件扫描 |
| [开发环境](<../.env.development>) | real 数据源、开发 API/WS 与公开图片地址 |
| [生产环境](<../.env.production>) | real 数据源与同源代理路径，不绑定生产服务器 IP |
| [本机挂载模板](<../.env.local.example>) | 复制为本机覆盖文件后配置 GIS 与模型的实际目录，不进入 Git |
| [部署地图模板](<../deploy/cockpit.config.json>) | 生产构建的地图参数来源；不含密钥或本机磁盘路径 |

服务地址及唯一入口约定见 [项目规则](<../AGENTS.md>)。旧预览模式配置已隔离，不再使用 pre.dev / pre.build / FES_ENV=predev。

## 开发与生产不再互相污染

开发时已有 [本机运行时 JSON](<../public/cockpit/config.json>) 仍然优先，当前场景和业务改动不变。干净检出没有该文件时，[配置插件](<../src/common/cockpitEnvPlugin.js>) 使用部署地图模板加开发环境连接值返回配置。地图数据仍需要单独提供。

生产时关闭整个 public 目录的自动复制。配置插件从部署地图模板生成 `cockpit/config.json`，再用本次生产环境覆盖 `dataSource / api.baseUrl / ws.url / images.baseUrl`。**不读取或复制本机 JSON**，不会把现场临时模型参数或开发接口悄悄带入生产。需要变更生产场景时更新部署地图模板，或者在部署后修改服务器上的运行时配置。

两个环境均使用 `VITE_COCKPIT_CONFIG_URL=auto`，新产物无需再向 HTML 手动注入开关。已发布旧产物不会因修改源码环境文件自动改变。

## 生产代理契约

| 公开路径 | 需要部署的内容 |
| --- | --- |
| /api/cockpit/v1 | 驾驶舱只读 API |
| /ws/deviceStatus | WebSocket，代理必须传递 Upgrade/Connection |
| /minio/pipe/ | 公开图片和附件；只填公开 endpoint，不提供 MinIO 私钥 |
| /gis/dem-lod/ | 地形目录，含 layer.json 和 terrain 瓦片 |
| /gis/pic-ring0/ 至 /gis/pic-ring3/ | 分层影像，必须保留 TMS 的 reverseY 语义 |
| /gis/cad-bim/ | 城市模型实际引用闭包，包含跨版本模型、JSON 和贴图 |

这些路径只是配置契约，不表示 Nginx 或资产已经部署。HTTP 页面自动使用 ws，HTTPS 页面自动使用 wss。内网边界、HTTPS、跨域及缓存由部署方配置。

## 环境覆盖与安全

应用配置优先级仍为：内置默认 → VITE 环境兜底 → 运行时 JSON；宿主明确注入配置对象时直接使用该对象。

FES 会先把通用和本机环境变量写入 process.env，Vite 再加载 mode 环境。因此**不要在通用或本机覆盖文件中写开发 API/WS/图片基址**，否则可能覆盖生产值。开发差异写入 `.env.development.local`，生产差异写入 `.env.production.local`（均不入库）。

`VITE_` 值对浏览器公开。禁止存储数据库密码、MinIO accessKey/secret、短信密钥或带凭据/签名的图片基址。`VITE_APP_ENV` 只是标识，不是构建模式开关。

环境修改要到下一次获授权启动或构建时才生效；本次没有运行 build/dev/debug、浏览器验收，也没有提交推送。