部署指南

补编设计稿，编写日期：2026-10-20。本文描述待实现的部署方案，不证明服务、安装包、配置或部署能力已经存在。 实际实施状态以阅读导航为准；技术约束以项目根目录 AGENTS.md 为准。

文档边界与参数来源

• 本文用于准备实施与验收，不授权连接生产服务器、创建真实账号、配对真实设备或执行上线操作。
• 架构选择及运行参数统一引用设计决策与参数基线中的编号。
• D01、D02 确定首版服务形态与任务分发方式；D03、D04、D05 分别约束网页会话、浏览器出口和 Windows 运行方式。
• 容量使用 P01，任务期限使用 P02，连接检测使用 P03，数据保留使用 P09，备份恢复目标使用 P10。
• 参数基线中的建议默认值是待验证、待上线确认的目标，不代表已通过压测或已有可用性承诺。
• 当前没有可据以执行的 Compose、Nginx、环境文件、迁移命令或安装脚本；实现后由 README 记录实际命令，本文不虚构可运行指令。

开工前需要解决的问题

以上为影响正确实现的前置问题。正式域名、证书、备份服务与生产管理员信息属于上线准备；开发环境工作不因这些生产信息尚缺而一概停止。

目标部署拓扑

• 浏览器访问同源 HTTPS 入口；Nginx 提供 Web 静态资源，并代理 HTTP API 和 WebSocket。
• API 按 D01 以模块化单体运行，首版明确采用单 API 实例、单 worker；内嵌分发扫描器由该实例管理生命周期。
• MySQL 8.4 LTS 保存业务事实；任务、事件、待分发记录及审计具有明确的事务边界，详见 D02。
• Windows Agent 从已登记设备主动建立 WSS 出站连接，不接受公网入站控制连接。
• Compose 管理服务器组件；Nginx 可以由宝塔统一管理，但仍是同一个对外入口，不同时建立另一个 Caddy 入口。
• Redis、独立任务队列和独立协调组件不作为首版必需依赖；扩容必须重新设计连接归属、分发协调和撤销传播，不能仅增加 worker。
• 试点规模以 P01 为上限设计假设；达到建议容量并不自动意味着性能已经通过验收。

网络与入口配置要求

• 若保留 HTTP 入口，仅用于证书验证或跳转 HTTPS；不得通过 HTTP 接收生产登录或设备凭据。
• Nginx 应支持 WebSocket 升级，连接相关超时与 P03 协调，并限制请求体、消息及连接资源。
• 代理头只信任已配置的反向代理，不能直接信任客户端提交的转发来源、协议或身份信息。
• 长期凭据不得放入 WebSocket URL；日志规则同时覆盖查询参数、认证头、Cookie 和敏感请求体。
• TLS 校验失败应停止连接并报告原因；不提供跳过校验选项，也不以自签名但未受信任的证书冒充生产有效 TLS。

配置、凭据与运行账号

• 实现时提供仅含字段说明和占位符的环境变量示例；真实环境文件、备份、私钥和设备秘密不得提交仓库。
• 应用使用普通数据库业务账号；迁移账号与运行账号分离，迁移权限不保留在正常运行环境中。
• 数据库连接采用 mysql+asyncmy，编码和主外键比较规则遵循根规范，不通过入口服务启动时自动建表。
• 设备凭据使用 Windows DPAPI 或 Credential Manager 等受保护存储；不得复用网页用户会话或密码。
• 首个管理员通过一次性初始化流程创建；不提供默认管理员密码，不开启公开注册。
• 生产管理员必须完成 MFA 配置与验证；恢复访问流程需要身份核验、凭据失效和审计记录。
• 按 D03 落实 Cookie 会话的 Secure、HttpOnly、SameSite 和适用 CSRF 防护；禁用用户时撤销其会话及相关订阅。
• 后续模型、聊天与扩展能力未交付时，应从接口和执行器层验证禁用状态，不能仅隐藏菜单。

首次部署流程

• 迁移失败时不得继续启动不兼容应用；保留日志和备份，由负责人按发布方案处理。
• 配对成功不等于获得任务权限；设备、用户与能力授权必须单独完成。
• 部署检查不得使用真实个人浏览器会话作为自动化上下文，也不得以临时开放任意 Shell 方式绕过未实现的安装流程。

Windows Agent 安装与运行

• 首版采用 D05：由标准用户可见安装和启动，在已确认的运行账号与交互会话中执行。
• 浏览器使用独立 Playwright 上下文，不读取个人浏览器的 Cookie、密码或会话目录。
• 安装资料应说明数据范围、网络连接、凭据保存位置、启动方式、停止方式及卸载后的凭据处理。
• Agent 仅执行已登记且被当前策略批准的能力；未知协议、未知字段、过期任务和不匹配设备任务必须拒绝。
• 分发消息可重发，但本地持久记录负责避免重复执行；重连后先对账，无法确认副作用的任务进入 unknown_outcome。
• 任务期限按 P02、连接检测按 P03；离线判定不是任务未执行的证明，也不授权自动重试。
• Agent 发布来源和升级操作遵循更新与版本发布，不得把人工安装流程描述成已有自动更新器。

健康检查、监控与数据治理

• 规划存活接口为 /api/v1/health/live：仅反映进程是否能响应，不泄露内部配置、凭据或详细异常。
• 规划就绪接口为 /api/v1/health/ready：反映数据库可用性、迁移兼容性和关键运行组件是否就绪；详细诊断仅对受控管理访问开放。
• 上述接口目前属于设计，不能据本文宣称已经实现；具体返回 Schema 与状态码随接口契约交付。
• 就绪失败应阻止继续接收新执行请求；已经执行中的任务仍需保留对账与结果接收路径，不能直接重置任务状态。
• 监控覆盖任务积压、执行失败、未知结果、设备离线、分发器停滞、数据库连接、存储空间及备份失败。
• 日志与事件使用 correlation_id 关联，保留期按 P09；删除任务结果不应破坏仍需保留的审计引用。
• 清理规则分别处理业务结果、审计和应用日志；未来聊天、截图及文件的策略在启用相应能力前落实。

备份与故障恢复

• 按 P10 准备加密备份、异机保存、保留和恢复演练；备份应包含数据库及恢复所需配置，密钥另行受控保护。
• RPO、RTO 是上线前确认的建议目标，必须依据实际数据量、备份间隔、传输和恢复演练结果评估，不作未经验证的保证。
• 恢复前先隔离旧实例和分发器，确认目标库、备份时间、密钥可用性与允许的数据丢失范围。
• 恢复后保持分发关闭，核对用户撤销、设备凭据、任务状态及 Agent 本地记录，避免旧备份使已撤销权限或已执行任务重新生效。
• 如果没有可靠的备份后撤销记录，继续关闭登录和新执行，使全部旧网页会话与设备凭据失效，重新核准用户、设备与授权后再配对；不能仅依赖恢复库或设备自报认定权限有效。执行名额只在证明执行器已停止后释放。
• 无法证实结果的任务保留 unknown_outcome 并人工核实；数据恢复不能把历史待分发记录直接当成新的执行授权。
• 恢复演练需记录实际耗时、可恢复时间点、数据一致性问题及修复项，然后由负责人判断是否达到 P10。

生产上线门禁

• 真实 MySQL 8.4 迁移、事务、幂等和并发验证完成；真实 Windows 闭环与模拟验证分别列出。
• 对象级授权、用户和设备撤销、配对码复用、消息重复、取消、超时、未知结果及重连均有验证证据。
• 有效 TLS/WSS、生产管理员 MFA、数据库非公网、普通运行账号及迁移身份隔离全部验收。
• D04 的浏览器网络限制经过真实访问验证，不能用 URL 字符串单元测试代替网络边界验收。
• 备份可恢复、监控告警可到达负责人、日志脱敏与 P09 清理机制可验证，发布和回滚职责明确。
• 未通过适用门禁时记录阻塞项并保持试验或禁用状态；补齐文档、构建成功或模拟通过均不等同于生产可用。