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 包：
Sense\scripts\build\build-windows.bat
生成包并正确配置后，可从仓库根运行：
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、真机或生产行为明确标注。
Sense 批量开通与容量配额配置排错
数据库迁移 2026082812000_quota.go 首次创建统一配额配置：读取当次迁移进程的可选 SENSE_PROVISIONING_QUOTA 正整数作为初值，未设置或无效时使用 16。迁移完成后，运行期配额以 PostgreSQL sense_quota_settings 为事实源，并由“容量与配额”页面受控调整；后续修改环境变量不会覆盖数据库值。每个批量开通批次仍记录创建时的配额与占用快照。
升级后看不到“容量与配额”时，确认迁移成功并重新登录刷新动态菜单。implementation_operator、site_admin、viewer 可读取容量；只有 site_admin 可调整配额和重新启用设备。调整必须填写原因。降低配额不会停止已有流；当占用达到或超过配额时，新增和启用返回冲突。
页面显示“配额配置不可读取”时，先确认 sense_quota_settings 的 ID 1 记录存在、limit 为 1–100000 的整数且数据库可读；不要通过手工插入设备绕过安全闸。配置不可读时已有流和查询应继续，新设备、重新启用和批量开通写入会返回服务不可用。32/64/128 的“未验证”状态不能作为容量承诺。
批量导入被拒绝时还应检查模板只含 line_number/name/location/address，地址必须为不带账号、查询参数或片段的 HTTP(S) ONVIF 地址。条目失败时按页面原因检查网络、获准网段、凭据和接入状态；仅重试失败项，不删除已成功设备。日志、导出和问题记录不得粘贴摄像头凭据。
Sense 边缘节点状态排错
升级后看不到“边缘节点”菜单时，先确认数据库迁移 2026082813000_edge_node.go 已成功，再重新登录或刷新动态菜单。implementation_operator、site_admin、viewer 均只有列表和详情读取权限，本模块没有网页写入、删除或远程控制接口。
节点超过 90 秒没有心跳即显示离线。离线时页面继续显示最后已知的隧道、视频、负载和回填状态，并标明陈旧时长，这不表示通道仍实时可用。心跳恢复但通道未收敛时显示“恢复中”，应分别检查控制隧道、视频数据面和回填队列。当前版本只提供 Sense 内部投影入口，不包含外部心跳接入协议或跨节点回填执行；没有节点数据时不会自动生成演示节点。
Sense MediaMTX 分片配置与排错
主 MediaMTX 继续使用 SENSE_MEDIAMTX_MODE、SENSE_MEDIAMTX_BINARY、SENSE_MEDIAMTX_CONFIG 和 SENSE_MEDIAMTX_API。可选 SENSE_MEDIAMTX_CAPACITY 为正整数；留空时使用数据库中的当前统一配额。
额外分片通过 SENSE_MEDIAMTX_SHARDS_FILE 指向仓库外 JSON 文件。相对路径按 Windows 交付包根目录解析；示例结构见包内 config\mediamtx-shards.example.json。每项必须包含唯一 id、名称、本机回环 Control API 和正容量，mode 只能为 external。文件不得包含摄像头账号、密码、数据库连接或其他秘密。
额外 MediaMTX 进程由部署方独立启动并为各实例分配不冲突的 API、RTSP 及其他监听端口；Sense 只做健康探测和路径管理，不启停这些外部进程。升级后看不到“媒体分片”时，确认迁移 2026082814000_media_shard.go 成功并重新登录刷新动态菜单。
页面“运行异常”表示最近一次 Control API 探测失败；“状态已陈旧”表示运行循环已超过 30 秒没有更新探测结果。故障时先在详情定位设备/Profile/路径，不要手工改数据库归属。迁移预检不会执行迁移；任何实际跨分片迁移都必须另建高风险工单和回退方案。
Sense 可靠投递运维与排错
升级后应执行包含 2026082815000_outbox.go 的数据库迁移。看不到“可靠投递”菜单时，先确认迁移成功，再重新登录或刷新动态菜单。页面提供等待投递、重试、处理中/租约和死信数量；未配置正式 connector 时队列保留，不影响 Sense 设备接入、实时监看和其他核心能力。
积压时先查看状态、可用时间、租约、尝试次数和最近脱敏错误。processing 长时间不恢复时检查 worker 是否仍运行、数据库时间与租约是否过期；不要手工清空租约或删除消息。dead 只能由 implementation_operator 或 site_admin 在排除根因后填写恢复原因重新排队，原业务记录、幂等键和失败历史必须保留。
日志、页面和 API 不得输出内部 payload、外部凭据或机器身份。production 配置不得启用测试 sink。正式 Brain/Bell connector、机器身份、共享 schema 和跨项目 E2E 必须通过后续协调工单交付；停用 relay 可以作为回退，但不得删除未投递记录或永久幂等收据。
Sense 运维告警运行与排错
升级后必须执行包含 2026082816000_ops_alert.go 的数据库迁移。看不到“运维告警”菜单时，先确认迁移成功，再重新登录或刷新动态菜单。viewer 只能查看列表和详情；implementation_operator、site_admin 可使用“刷新状态”、确认和恢复。
“刷新状态”只读取 Sense 数据库中已有的设备接入、媒体路由、媒体分片和边缘节点健康投影。没有对应健康投影时不会伪造演示告警；先检查上游模块是否已完成探测或心跳入库。分片超过 30 秒没有探测、节点超过 90 秒没有心跳会被判定异常。
确认后仍显示活动告警是正常行为：确认只代表有人处理。源状态健康后进入“恢复观察”，稳定满 5 分钟才能确认恢复；期间复发会返回待确认或已确认。恢复操作被拒绝时先刷新列表，检查健康状态、观察起始时间和页面版本，不要手工改表或删除历史。
运维告警排错不得粘贴设备地址、Stream URI、摄像头凭据、JWT、Cookie 或数据库连接。需要回退时可停止使用刷新/处置入口，但不得删除 sense_ops_alerts 或 sense_ops_alert_transitions 历史；规则语义变化必须另建工单。
Sense↔Brain 契约部署边界
yovision.source-config/v1 与 yovision.runtime-status/v1 已冻结，但当前没有因此新增监听端口、服务进程、机器凭据或根级编排。#148/#149 只交付 contracts/** Schema、样例、兼容说明和契约测试；实际 Sense↔Brain 传输、认证、超时、退避、重启恢复及配置/状态 adapter 由后续 #151、#152 实现和验收。
因此现阶段部署仍按 Sense、Brain 各自独立入口进行，不得手工共享数据库、用户 JWT/Cookie、摄像头凭据、文件目录或临时 JSON 字段来提前打通。需要停用或回退时保持两端独立运行，并保留上一已确认的配置与最后已知状态；未知协议主版本必须停止摄取而不是覆盖投影。
机器身份部署与轮换边界
#151 已冻结机器身份和传输基础，#152/#153 已验收业务 adapter/connector；运行时仍必须使用正式配置、迁移和独立机器身份，不得手工拼接临时共享凭据。
部署时为每个调用实例独立生成 Ed25519 私钥，保存到仓库外受 ACL/秘密存储保护的位置；产品配置只记录私钥路径、principal、kid、目标 audience 和最小 scope。消费者从仓库外公钥注册表读取受信 principal/kid。不得把私钥、完整令牌、Authorization header、管理员密码、浏览器 JWT/Cookie 或 query token写入配置样例、日志、工单和备份。
传输固定使用 HTTPS，TLS 最低 1.2并验证证书链与主机名。轮换按“先登记新公钥 → 调用方切换新 kid → 验证流量 → 24 小时内移除旧 key”执行；应急吊销直接禁用 principal 或 key，并同时停用相关 connector。回退保持 Sense、Brain、Bell 独立运行，保留 Outbox、Receipt、Event 和最后已知状态。
#152/#153 已为各产品接入独立持久原子 (principal,jti) replay store并覆盖重启恢复；内存 replay store 仍只用于适配测试或不重启的单进程原语。
#152/#153 connector 部署与回退
升级前先备份 Sense、Bell 各自 PostgreSQL，并在停服窗口执行正式迁移：
- Sense：
2026083112000_brain_runtime.go、2026083112000_bell_connector.go。 - Bell：
2026083112000_event_ingress.go。
迁移缺失时 connector 必须拒绝启动，不得依赖运行时 AutoMigrate 临时补表。Sense 只使用默认数据库注册 ingress 和 Worker，Bell 使用自己的默认数据库；不得指向共享数据库。
Brain 的标准事件出口在自身 JSON 配置的 event_export 对象中启用。必须配置 HTTPS origin、producer/site/severity、仓库外私钥路径、独立 principal/kid 和严格 transport policy；关闭时配置只保留 {"enabled": false}，CLI 恢复原 JSON Lines 独立输出。endpoint 只能是 HTTPS origin，固定追加 /v1/events。
Sense 运行变量：
SENSE_EVENT_INGRESS_ENABLED：注册 Brain→SensePOST /v1/events与证据读取入口。SENSE_MACHINE_PRINCIPAL_REGISTRY：仓库外 Brain/Bell 公钥注册表。SENSE_EVIDENCE_OWNER_ID：Sense 证据所有者逻辑标识。SENSE_BELL_CONNECTOR_ENABLED：启动 Bell Outbox Worker。SENSE_BELL_ENDPOINT、SENSE_RELAY_ID：Bell HTTPS origin 与 relay 实例标识。SENSE_BELL_PRINCIPAL_ID、SENSE_BELL_KEY_ID、SENSE_BELL_PRIVATE_KEY_PATH：Sense→Bell 独立机器身份。SENSE_BELL_RELAY_INTERVAL_MS：100–60000 ms；未配置时 2000 ms。
Bell 运行变量：
BELL_EVENT_INGRESS_ENABLED：注册POST /v1/events。BELL_MACHINE_PRINCIPAL_REGISTRY：仓库外 producer/relay 公钥注册表。BELL_EVIDENCE_RESOLVER_ENABLED：启用 Bell→Sense 证据解析。BELL_SENSE_EVIDENCE_ENDPOINT、BELL_SENSE_PRINCIPAL_ID、BELL_SENSE_KEY_ID、BELL_SENSE_PRIVATE_KEY_PATH：Sense HTTPS origin 与 Bell 独立证据读取身份。
推荐启动顺序：完成两端迁移 → 启动 Bell ingress → 启动 Sense ingress/relay → 启用 Brain event_export。#152 的配置/状态 adapter 已有持久状态、重放与恢复接口，部署级 HTTP 托管和根级进程编排在 #154 统一绑定，不能用临时共享文件或数据库替代。
回退时关闭 Brain event_export.enabled、Sense 两个 connector 开关和 Bell ingress/evidence 开关；保留 last-known-good、运行投影、InboundEvent、EvidenceRecord、Outbox、ReplayToken、Receipt、Event 与审计。不得删除事实、关闭 TLS/验签或改用网页登录态。
三项目可选根级部署编排
工单 #154 已于 2026-08-31 验收。根级编排只组合 Sense、Brain、Bell 已审核交付包，不复制产品实现，也不改变三端独立交付边界。事实入口如下：
- 清单 Schema：
deploy/coordination/coordination.schema.json - 无秘密示例：
deploy/coordination/coordination.example.json - 操作说明：
deploy/coordination/README.md - 启动、停止、状态入口：
scripts/runtime/coordination/{start,stop,status}-yovision.ps1，并提供同名 BAT 包装器
生产或验收环境必须先把示例清单复制到仓库外受控目录，并分别准备仓库外 Sense、Brain、Bell 环境文件和每实例独立私钥。Sense/Bell 使用不同数据库、数据库角色、账户空间、浏览器 origin、Cookie、JWT、端口、包、数据目录和日志目录；三端机器 principal、key id 和私钥文件也不得复用。清单只记录版本、路径和公开标识，不保存密码、JWT、token 或私钥内容。
从仓库根目录使用：
pwsh -NoProfile -File scripts/runtime/coordination/start-yovision.ps1 -Manifest C:\YoVision\config\coordination.json -ValidateOnly
pwsh -NoProfile -File scripts/runtime/coordination/start-yovision.ps1 -Manifest C:\YoVision\config\coordination.json -Product bell,sense,brain
pwsh -NoProfile -File scripts/runtime/coordination/status-yovision.ps1 -Manifest C:\YoVision\config\coordination.json -Product all
pwsh -NoProfile -File scripts/runtime/coordination/stop-yovision.ps1 -Manifest C:\YoVision\config\coordination.json -Product brain
启动顺序为 Bell → Sense → Brain，停止顺序反向。启动时 all 只包含 enabled=true 的产品；停止和状态查询时 all 覆盖三端，避免停用配置后遗留进程。编排状态只保存 PID、版本、清单摘要和命令归属元数据；停止前必须核对 PID、启动器与命令令牌，归属不匹配时拒绝终止。单端启动失败只清理该端新进程，不自动停止其他端。
升级时每次只替换一个独立包并更新精确版本，先备份 Sense/Bell，再按 Bell → Sense → Brain 验证，最后启用 connector。回退时先停用 Brain event export、Sense ingress/relay 与 Bell ingress/evidence connector，再使用各产品独立入口回退包或恢复数据库；不得删除 Outbox、Receipt、Event、运行投影、replay 或审计事实。16 路只是当前交付配额，不是编排器硬上限；真实生产包、PostgreSQL、客户 PKI、真机容量与长稳仍需部署环境验收。
三项目协调 E2E 验收入口
工单 #155 已于 2026-08-31 验收，并通过 PR #170 合入 dev@0276bce。该入口只用于隔离开发/验收，不是生产部署、生产迁移或现场容量测试：
pwsh scripts/e2e/coordination/run-coordination-e2e.ps1
入口要求 PowerShell 7、冻结的 Go 1.26.5 工具链、Brain 可用 Python 环境、PostgreSQL 17 命令行工具，以及 Sense/Bell 各自独立 E2E 已记录的本机依赖。PostgreSQL 工具默认从 D:\pgsql17\bin 读取，可通过 -PostgresBin 指定其他安装目录；Python 默认优先使用 Brain\.venv\Scripts\python.exe，也可通过 -Python 指定。不得为通过测试而连接生产数据库、客户设备或生产服务。
每次运行会在系统临时目录创建专属 PostgreSQL cluster，使用非 5432 动态 loopback 端口，并为 Sense、Bell 创建随机且不同的 database owner 和 database。测试凭据只存在于当前进程和临时测试范围，不进入仓库。入口按顺序执行冻结契约、三端 connector/持久化故障验证，并默认继续执行 Sense、Brain、Bell 各自已有的独立 E2E。
-SkipIndependentProductE2E 只用于定位协调 harness 自身故障；使用该参数的结果不能作为 #155 或 MVP #156 验收证据。-KeepTemporary 只用于受控保留失败诊断，目录可能包含一次性测试数据，排查完成后按明确绝对路径清理，不得提交或共享。
入口在 finally 中只停止自己启动的临时 PostgreSQL 和下游测试拥有的进程，核对端口关闭，并扫描临时日志是否出现本轮随机秘密。成功的最终判据是全部阶段退出码为 0，输出末行包含 COORDINATION_E2E passed，且 git status --short 没有产品源码或配置改动。
该验收证明版本化契约、配置/状态、匿名事件、Sense Outbox、Bell Receipt/Event/Alert/ack/close、离线恢复、身份/重放/冲突/证据降级及三端独立运行；不证明真实 GPU/生产模型、真实摄像头、通知供应商、生产迁移、16 路长稳或客户现场效果。