diff --git a/Deployment-and-Operations.-.md b/Deployment-and-Operations.-.md new file mode 100644 index 0000000..43fa563 --- /dev/null +++ b/Deployment-and-Operations.-.md @@ -0,0 +1,74 @@ +# YoVision 部署与运维 + +## 文档信息 + +- 系统:YoVision +- 当前常驻实例:Sense +- 适用环境:Windows 本机开发/验收与 Sense Windows 交付包 +- 维护入口:工单 #108 后由长期 Wiki 持续维护 +- 安全边界:本文不记录数据库密码、管理员密码、摄像头凭据、JWT/会话密钥或 Gitea token + +## 部署范围与边界 + +当前可核对的常驻服务是 Sense。Brain 尚未初始化,Bell 新 GoAdmin 基线尚未完成,因此不在本页提供虚构的生产部署命令。三个交付单元保持独立配置、数据、身份、版本和发布边界;跨项目编排必须另建协调工单。 + +## 目录与入口 + +- Sense 项目目录启动入口:`Sense\start_sense.bat` +- Windows 交付包:`Sense\dist\sense-windows-amd64` +- 包内启动入口:`Sense\dist\sense-windows-amd64\start-sense.bat` +- 包内配置:`Sense\dist\sense-windows-amd64\config\sense.env` +- 项目配置源:`Sense\config\sense.env` +- 构建入口:`Sense\scripts\build\build-windows.bat` +- 本机 Supervisor 根目录:`D:\supervisor` + +`Sense\start_sense.bat` 只定位并调用交付包入口、透传参数和退出码;它不读取配置、不自动构建,也不直接启动 Go 或 Node 开发服务。MediaMTX 是否随包启动由 Sense 包内运行脚本和配置控制。 + +## 配置与秘密 + +- 生产模式必须提供有效 PostgreSQL 连接和应用安全配置;变量名及无敏感示例以项目或交付包中的 `.env.example` 为准。 +- 配置文件和进程环境中的秘密不得提交到 Git、工单、Wiki、日志或示例。 +- Sense、Bell 必须使用不同数据库角色、用户库、JWT/会话密钥和 Cookie;Brain 使用独立机器身份。 +- 修改服务账号、权限、端口、数据库、媒体二进制或持久化目录前必须建立相应工单并说明回退。 + +## 构建与启动 + +从 Sense 目录生成 Windows 包: + +```powershell +Sense\scripts\build\build-windows.bat +``` + +生成包并正确配置后,可从仓库根运行: + +```powershell +Sense\start_sense.bat +``` + +临时演示模式可透传 `demo` 参数;演示数据随进程停止而丢失,不得作为生产部署。 + +## Supervisor 常驻实例 + +本机 Supervisor 的 YoVision Sense 实例由工单 #106 建立。Supervisor 配置、启动停止命令、工作目录、环境文件和日志位置以 `D:\supervisor` 中的当前实例配置为准。修改该外部目录前必须建立工单并确认精确目标;仓库不得复制其中的秘密。 + +## 健康检查与日志 + +- 默认 Sense 访问地址以当前配置为准;已验收的本机默认地址为 `http://127.0.0.1:18080/`。 +- 先确认端口监听和 HTTP 页面,再检查 Sense 结构化日志、PostgreSQL 连接、数据库迁移以及 MediaMTX 进程和路径状态。 +- 日志不得输出数据库密码、摄像头凭据、会话 Cookie、JWT secret 或 token。 +- 具体视频、迁移和登录故障按 `Troubleshooting` 页面处理。 + +## 停止、升级与回退 + +- 手工前台启动时在原控制台正常终止进程;Supervisor 托管时使用该实例的受控停止方式,避免同时启动第二个占用相同端口的进程。 +- 升级前记录当前 Git 提交、交付包版本、数据库备份/恢复方案和配置差异。 +- 数据库迁移、凭据、权限或不可逆操作属于高风险,必须另建工单并等待确认。 +- 回退优先恢复上一已验收交付包和对应配置;涉及数据库迁移时只能使用该迁移工单确认的回退方案。 + +## 最小验收 + +- 启动入口、工作目录、配置来源和端口与实际一致。 +- Sense 页面与必要 API 可访问,数据库迁移成功。 +- MediaMTX 启用时进程、路径和播放链路状态可定位。 +- Supervisor 不会与手工进程重复占用端口。 +- 日志和文档没有秘密;未验证的 Brain、Bell、真机或生产行为明确标注。