From 27d465c2506ca107fe01606aab130d44cfdb5dec Mon Sep 17 00:00:00 2001 From: QiuSW <105186638@qq.com> Date: Mon, 31 Aug 2026 16:32:48 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=90=8C=E6=AD=A5=E6=A0=B9=E7=BA=A7?= =?UTF-8?q?=E9=83=A8=E7=BD=B2=E7=BC=96=E6=8E=92=E8=AF=B4=E6=98=8E=20(#168)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/02-architecture-and-code-map.md | 27 +++++++++++++++-- docs/04-local-development-and-verification.md | 28 +++++++++++++++-- docs/06-troubleshooting.md | 30 +++++++++++++++++-- docs/delivery/deployment-and-operations.md | 30 +++++++++++++++++-- 4 files changed, 107 insertions(+), 8 deletions(-) diff --git a/docs/02-architecture-and-code-map.md b/docs/02-architecture-and-code-map.md index 5df3be5..b3894a1 100644 --- a/docs/02-architecture-and-code-map.md +++ b/docs/02-architecture-and-code-map.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Architecture-and-Code-Map wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Architecture-and-Code-Map.- -wiki_revision: b25498f58c690f787f0b572788617ef6b0d8ea7d -synchronized_at: 2026-08-31T07:23:02Z +wiki_revision: 77af1bb5a71d7b89e74b1905ca11b6040dc0d1eb +synchronized_at: 2026-08-31T08:25:26Z # 架构与代码地图 @@ -359,3 +359,26 @@ v1 使用 HTTPS 上的 Ed25519 短期请求绑定 JWS。每个部署实例拥有 Sense/Bell 使用 Go 标准库 Ed25519，Brain 冻结 `cryptography==50.0.1`。固定跨语言向量证明 Go/Python 可互相验签。#151 只提供身份、注册表、传输策略及可注入 replay 接口；#152/#153 才注册业务 endpoint，并必须使用各产品独立的持久原子 replay store验证重启，不能共享数据库。 + + +## 可选协调部署层 + +工单 #154 已于 2026-08-31 验收。根级协调部署层位于 `deploy/coordination/**` 与 `scripts/runtime/coordination/**`，它只负责声明、校验和调用三个独立产品入口： + +```text +仓库外 coordination.json + ├─ Sense 独立包 / env / DB / 端口 / 数据 / 日志 / 机器身份 + ├─ Brain 独立包 / env / 端口 / 数据 / 日志 / 机器身份 + └─ Bell 独立包 / env / DB / 端口 / 数据 / 日志 / 机器身份 + ↓ +coordination-common.ps1 + ├─ 封闭清单与隔离断言 + ├─ 单端或选择性组合 start/stop/status + ├─ 健康检查、版本和清单摘要 + └─ PID + 启动器 + 命令令牌归属保护 +``` + +`coordination.schema.json` 定义版本 `yovision.coordination/v1`；`coordination.example.json` 只提供不可投产占位。公共实现 `coordination-common.ps1` 解析外部 env 数据但不执行其内容，校验产品命令位于各自包内、秘密路径位于仓库和包外，并拒绝路径、端口、数据库身份、JWT、Cookie 或机器身份复用。三个薄入口脚本分别调用公共实现，BAT 只透传参数和退出码。 + +协调层不拥有业务数据或契约，不共享用户表、JWT、Cookie、数据库内部模型、摄像头凭据或产品实现。它不替代 `contracts/**`，也不让任一产品成为另一产品的启动前置；connector 可关闭，三端核心能力继续独立运行。根级运行状态位于清单指定的 `runtime_root\state`，产品日志仍归各自日志目录和产品入口管理。 + diff --git a/docs/04-local-development-and-verification.md b/docs/04-local-development-and-verification.md index ae35320..d965638 100644 --- a/docs/04-local-development-and-verification.md +++ b/docs/04-local-development-and-verification.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Local-Development-and-Verification wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Local-Development-and-Verification.- -wiki_revision: 59f6eb5816b5d3f78c85ef902053c5fc45b8e6e9 -synchronized_at: 2026-08-31T07:33:54Z +wiki_revision: 7e5ec44eb0afec0b84010ce6cf82177491272c70 +synchronized_at: 2026-08-31T08:25:49Z # 本地开发与验证 @@ -751,3 +751,27 @@ git diff --check 工单验收未使用客户 PKI、生产 PostgreSQL、真实三端网络或生产流量；这些结果只能由 #154 部署和 #155 E2E 补充。Sense 本地候选原子 Outbox 当前没有生产创建 caller，也不得据此声明本地产生链已完整接通。 + + +## 根级编排本地验证 + +工单 #154 的编排验证只使用仓库外临时目录和假交付包，不需要真实密码、数据库或客户 PKI。先运行清单和脚本验证： + +```powershell +pwsh -NoProfile -File scripts/runtime/coordination/start-yovision.ps1 -Manifest C:\YoVision\config\coordination.json -ValidateOnly +pwsh -NoLogo -NoProfile -File deploy/coordination/tests/coordination-smoke.ps1 +``` + +冒烟测试必须返回 0，并覆盖 Sense、Brain、Bell 分别启动/状态/停止、Brain+Bell 选择性组合、停止单端不影响另一端、单端启动失败隔离、端口占用与重复端口拒绝、重复数据库身份拒绝、无归属 PID 保护、清单漂移诊断、退出码和状态清理。测试创建的目录必须解析在系统临时目录内，结束时只清理该测试目录。 + +仓库闭环验证： + +```powershell +python dev_scripts/harness.py check --strict +python -m unittest discover -s tests -v +python dev_scripts/harness.py sync --check +git diff --check +``` + +这些测试证明编排和隔离控制，不证明真实产品包、生产 PostgreSQL、客户 PKI、真实摄像头/GPU、供应商服务、容量或长稳表现。真实契约闭环与 Brain/Bell 离线、重启、重复/冲突及证据降级由后续 E2E 工单验证。 + diff --git a/docs/06-troubleshooting.md b/docs/06-troubleshooting.md index 080cd88..c17a37a 100644 --- a/docs/06-troubleshooting.md +++ b/docs/06-troubleshooting.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Troubleshooting wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Troubleshooting -wiki_revision: fdd44bfe589d65cbce6ec085878abae2702d59e7 -synchronized_at: 2026-08-31T07:23:47Z +wiki_revision: 0d4a70626b4ab8cc65df3d8a56975376684dd284 +synchronized_at: 2026-08-31T08:26:11Z # 故障排查 @@ -195,3 +195,29 @@ synchronized_at: 2026-08-31T07:23:47Z 日志只记录稳定错误码、request/correlation ID、已认证 principal/kid 和脱敏业务引用；不得记录私钥、令牌、完整 Authorization、摄像头凭据、内部证据路径或事件完整敏感载荷。 + + +## 根级协调编排排错 + +工单 #154 已于 2026-08-31 验收；本节适用于已验收的可选根级编排。 + +先使用与启动时相同的仓库外清单查询状态： + +```powershell +pwsh -NoProfile -File scripts/runtime/coordination/status-yovision.ps1 -Manifest C:\YoVision\config\coordination.json -Product all +``` + +| 现象/状态 | 检查 | 安全处理 | +|---|---|---| +| 清单校验失败 | 检查包、env、私钥路径是否存在且位于仓库和包外；检查三端端口、目录、数据库、Cookie、JWT、账户和身份是否独立 | 修正仓库外清单或环境文件；不得放宽隔离断言或把秘密写进仓库 | +| `port ... is already in use` | 用状态命令确认是否已有受管实例，再检查对应监听端口 | 先按归属停止旧实例或为产品分配独立端口；不得终止未知进程 | +| `stopped` | 没有该产品状态文件 | 按需单独启动；不代表其他产品异常 | +| `unhealthy` | 进程仍归属本实例，但 HTTP/进程健康检查失败 | 查看该产品独立 `coordination.err.log`、`coordination.out.log` 和产品日志；修复该端，不自动重启其他端 | +| `stale` / `ownership-mismatch` | PID 已复用、启动器或命令令牌与状态不符 | 不会停止该进程；人工核对进程与状态文件，确认归属后再处理 | +| `stale` / `manifest-drift` | 运行中的实例来自不同清单摘要 | 使用原清单安全停止，或确认归属后停止再以新清单启动；不得用新清单覆盖运行事实 | +| 单端启动失败 | 查看该端协调日志、产品日志和退出码 | 编排只清理该端新进程；确认其他端状态，修复失败端后单独重试 | +| connector 使对端成为启动强依赖 | connector 开关或产品配置错误 | 关闭对应 event export、ingress、relay 或 evidence connector，恢复三端独立运行；保留 Outbox/Receipt/Event 等持久事实 | +| 停止命令拒绝执行 | 状态归属不匹配，或产品停止入口返回非零 | 不使用无条件 taskkill；先核对 PID、启动器、命令令牌和产品停止日志 | + +日志和状态不得包含环境变量值、密码、JWT、token、私钥、完整 Authorization、摄像头凭据或客户数据。协调层故障时可停止使用根级入口并恢复三个产品各自的已验收启动脚本，不删除数据或共享事实。 + diff --git a/docs/delivery/deployment-and-operations.md b/docs/delivery/deployment-and-operations.md index fbea3e8..f25d62f 100644 --- a/docs/delivery/deployment-and-operations.md +++ b/docs/delivery/deployment-and-operations.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Deployment-and-Operations wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Deployment-and-Operations.- -wiki_revision: fa7e2031338cbca0f669f5d5a72a073670114882 -synchronized_at: 2026-08-31T07:35:46Z +wiki_revision: f71d21296bc4d402046a52903e6e9ac0583dbd66 +synchronized_at: 2026-08-31T08:27:50Z # YoVision 部署与运维 @@ -188,3 +188,29 @@ Bell 运行变量： 回退时关闭 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 或私钥内容。 + +从仓库根目录使用： + +```powershell +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、真机容量与长稳仍需部署环境验收。 + -- 2.34.1