纳入绚丽增强层重交付：smart-parking-delivery-20261014（zip+解压双存档），子模块锁定660c2bc，登记同步更新

2026-10-14 11:25:02 +08:00
parent d5ff06d723
commit 680aa18240
38 changed files with 641 additions and 7 deletions
@@ -0,0 +1,65 @@
+# 部署注意事项
+
+项目：智慧停车综合管理平台
+更新日期：2026-10-10
+
+## 一、部署前检查
+
+1. **Docker 可用性**：执行 `docker --version` 与 `docker compose version` 确认版本满足 20.10+ / Compose v2+；Linux 确保服务已启动（`systemctl status docker`）。
+2. **端口占用**：启动前确认 `4010 / 4012 / 4015`（或自定义端口）未被占用：
+   - Windows：`netstat -ano | findstr :4010`
+   - Linux：`ss -lntp | grep -E '4010|4012|4015'`
+3. **磁盘空间**：预留至少 10 GB 可用空间（镜像 + 数据卷 + 录屏/地图素材）。
+4. **防火墙/安全组**：放通应用端口（4010）与 RTMP（4015）；**数据库端口 4012 不要对公网开放**。
+5. **时间同步**：生产服务器开启 NTP 时间同步，避免 JWT 与报警时间异常。
+
+## 二、部署中注意事项
+
+1. **环境变量**：复制 `.env.example` 为 `.env`，至少修改 MySQL root 口令；不要把含真实口令的 `.env` 提交到公共仓库（`.env` 已加入 `.gitignore`）。
+2. **首次启动**：`docker compose up -d` 会构建镜像、初始化数据库并导入示例数据，耗时取决于网络与机器性能，请勿中断。
+3. **健康判断**：使用 `docker compose ps`，应用容器状态为 `healthy` 后再访问；如长时间 `unhealthy`，用 `docker compose logs --tail=200 app` 排查。
+4. **数据卷**：数据库数据保存在持久化数据卷中；执行 `docker compose down` 不删数据，**加 `-v` 参数会删除数据卷导致数据丢失，务必谨慎**。
+
+## 三、混合内容 / HTTPS
+
+1. 若前端通过 HTTPS 访问，页面内的 HLS 视频与 AI 接口也需为 HTTPS，否则浏览器会拦截混合内容。
+2. TokenFree 接口本身为 HTTPS；自建/第三方媒体地址需保证与页面协议一致，或在反向代理统一 TLS 卸载。
+3. 建议在 Nginx/网关层统一配置证书（如 Let's Encrypt）并反代应用与媒体服务。
+
+## 四、直播与算法端
+
+1. 摄像头 RTSP/RTMP 源必须从部署主机可达；建议先用 `ffmpeg -i <源地址>` 验证源流正常。
+2. 算法端与后端通过 WebSocket 通信，需保证二者网络互通、管理员账号配置正确。
+3. 多路视频或高分辨率场景建议算法端独立部署并使用 GPU；CPU 推理路数过多会导致卡顿与漏报。
+4. RTMP/HLS 直播存在数秒延迟属正常（HLS 分片机制）；如需更低延迟可调整分片时长或改用 WebRTC 方案（另行定制）。
+
+## 五、浏览器兼容性
+
+1. 推荐使用最新版 Chrome / Edge；平台依赖 ES2020、HLS、CSS backdrop-filter。
+2. 部分老旧浏览器不支持玻璃模糊效果，会降级为半透明背景，不影响功能。
+3. AI Key 等配置存于浏览器 localStorage，更换浏览器/清理缓存后需要重新配置。
+
+## 六、升级与回滚
+
+1. **升级**：备份数据卷 → 拉取/构建新镜像 → `docker compose up -d`；数据库结构如有变更需按迁移说明执行。
+2. **回滚**：保留上一版本镜像 tag，异常时通过指定旧镜像 tag 重新启动；恢复升级前的数据卷备份。
+3. 建议交付/升级前导出数据库备份：
+   `docker compose exec mysql mysqldump -uroot -p<口令> <数据库名> > backup.sql`
+
+## 七、安全加固建议
+
+1. 首次登录立即修改 admin/operator 默认密码。
+2. 为数据库设置强口令并仅监听内网；生产环境关闭不必要的端口暴露。
+3. 反向代理层开启访问日志、限流与超时配置；对外服务启用 HTTPS。
+4. 定期更新 Docker、基础镜像与操作系统补丁。
+
+## 八、常见问题速查
+
+| 现象 | 排查方向 |
+| --- | --- |
+| 页面打不开 | 应用容器是否 healthy、端口/防火墙是否放通 |
+| 登录失败 | 数据库是否初始化完成、账号是否被修改、时间是否同步 |
+| 视频黑屏 | 摄像头源是否可达、RTMP 端口、混合内容策略、HLS 分片是否生成 |
+| AI 无响应 | API Key 是否正确、接口地址是否可达、模型名是否被服务商支持 |
+| 报警不触发 | 算法端是否在线、规则是否启用、检测目标/阈值是否合理 |
+| 容器反复重启 | `docker compose logs app` 查看依赖（DB 未就绪/口令错误/端口冲突） |