安全合规

1. 页面概览

1.1 是什么

「安全合规」页（对应前端源码 action/web/src/views/apollo/SecurityPage.vue，页面标题「Apollo 安全合规」）是 LightApollo 的安全与合规操作台（对齐 TAD-10）。页面用三个 Tab 拆成三块能力：合规总览（overview）用九张 summary 卡汇总项目安全态势并提供一个可手动调用的「安全门禁评估」表单；扫描与漏洞（scan）围绕制品做 SBOM 物料清单生成、漏洞扫描触发与扫描结果查看；安全策略（policies）管理策略清单与内置策略模板。整页回答的是「上生产前怎么证明安全」：先登记制品 → 生成 SBOM → 触发扫描 → 建立安全策略 → 提交资源快照做门禁预演 → 在「部署与漂移」页真正激活部署时，由同一套策略引擎在激活前强制执行门禁。 理解本页要先建立一个双评估入口的概念。安全策略引擎（deny_latest_tag / require_signature / critical_vuln / no_plaintext_secret / require_resource_limits / custom 六类规则）存在两个调用点：一是本页 Tab1 里的「安全门禁手动评估」表单，它是演示/预演入口，提交一段资源快照 JSON，后端按当前启用的策略求值并返回 allow / warn / deny 决策与命中违规清单；二是部署链路上的真实门禁——后端在「期望状态从 draft 激活为 active」之前（见第 5.4 节）对声明执行同一套 Evaluate，决策为 deny 时直接以 403 拒绝激活，把带病声明拦在生产之前。本页的手动评估能让你在不上真实部署的情况下，把资源快照喂给策略引擎观察决策，是理解「为什么那条部署会被拦下来」的最短路径。 页面的数据流大致为「读（Tab1 汇总 / Tab2 扫描结果 / Tab3 策略与模板）→ 写（新建策略、启停、删除、应用模板、触发 SBOM/扫描、门禁评估）」。输入主要是策略表单字段与资源快照 JSON、以及所选制品 id；输出是后端返回的决策/违规/报告 JSON 在卡片、徽标与表格中的渲染。项目 id 暂用常量 1（PROJECT_ID=1，default 项目），本页所有列表都挂在项目 1 下，后续才支持从 URL 取项目参数。 典型使用链路（演示视角的完整闭环）：① 先在「制品管理」页登记制品（拿到 artifact id）；② 回本页 Tab2 选中该制品点「生成 SBOM」再点「触发扫描」，观察漏洞报告与分级计数；③ 到 Tab3「应用」内置模板（如「禁止生产 latest 标签」）或手动新建 deny 级策略；④ 回 Tab1 在资源快照里放 {"tags":["latest"]} 之类触发 deny 的内容点「执行评估」，观察 decision=deny 与违规行；⑤ 到「部署与漂移」页激活关联该制品的期望状态声明，若声明 digest 关联了扫描出的 Critical 漏洞或声明带 latest 标签，真实部署同样会被拒绝——两个入口共享同一套策略与审计，形成「策略→门禁→审计」闭环。

1.2 核心价值/能力表

1.3 一句话总结

本页把「制品 SBOM/扫描 → 安全策略 → 门禁决策 → 合规汇总」串成部署前的安全闭环，让策略与漏洞状态在浏览器里可观察、可预演，并强制阻断带病制品进入生产。

2. 访问入口

2.1 路由与菜单

相邻页（侧边栏顺序）：告警自愈 alerts.md（前）、配置管理 configs.md（后）、制品管理 artifacts.md（Tab2 的制品下拉数据来源）、部署与漂移 deployments.md（真实部署门禁在此页的激活/sync 动作上触发）、用户管理 admin-users.md（权限点授给角色后决定本页可见性）。

2.2 认证与权限

• 路由 requiresAuth: true：未登录访问被前端路由守卫拦到 /apollo/login（登录态为独立 apollo_token，2026-09-12 修订后不再回退读取旧 aip_token）。
• 后端安全端点全部注册在 protected 组，按权限点鉴权：策略/合规读取用 security:read（PermSecurityRead）、策略写与删除用 security:write（PermSecurityWrite）、扫描触发/门禁评估/启停/应用模板用 security:execute（PermSecurityExecute）。403 时 apolloClient 统一 alert('无权限执行该操作')。
• 前端 401（apollo_token 失效）由响应拦截器清 token 并跳转 /apollo/login。
• 注意区分：门禁评估接口本身要求 security:execute，而「部署链路上的自动门禁」是后端进程内部调用（不经 HTTP 鉴权），只认策略引擎，与本页登录态无关。

2.3 端口与 API 前缀

• Apollo 后端端口 18082。Vite 开发代理把 /apollo-api 前缀 rewrite 为 /api 转发（后端路由注册在 /api/v1），客户端 baseURL /apollo-api/v1。
• 统一响应 envelope {code,message,data,request_id}：拦截器在 code===0 时把 response.data 解包为业务数据，页面 const { data } = await apiClient.get(...) 直接拿业务数据；data 可能是数组或 {items,...} 等对象，页面用 toList 健壮解析。
• 例外：门禁评估决策为 deny 时后端返回 HTTP 403 的 fail envelope（code:40301），会先触发拦截器的全局 alert('无权限执行该操作')，页面 catch 再把 403 body 的 data 解析出来正常渲染决策与违规列表（已修复（提交 412e9c48），SecurityPage.vue:692-702；详见 4.3）。

3. 界面布局

┌──────────────────────────────────────────────────────────────┐
│ Apollo 安全合规                             [新建安全策略]       │
│ alert-info：安全合规（TAD-10）…部署前强制安全门禁…               │
│ [操作结果提示条（v-if alert.message，可「关闭」）]               │
├──────────────────────────────────────────────────────────────┤
│ Tab：合规总览 | 扫描与漏洞 | 安全策略                          │
├──────────────────────────────────────────────────────────────┤
│ ┌ Tab1 合规总览 ────────────────────────────────────────────┐ │
│ │ 九张 summary 卡：策略数/启用策略/评估次数(近30天)/deny决策/ │ │
│ │  warn决策/allow决策/扫描制品数/含漏洞制品/漏洞条目数         │ │
│ │ ┌ 安全门禁手动评估（Security Gate）卡片 ────────────────┐ │ │
│ │ │ 项目id(禁用=1)/资源类型select/资源id/resource_data JSON│ │ │
│ │ │ [执行评估] → 评估结果区：decision 徽标 + policy_count + │ │ │
│ │ │  evaluated_at + 违规表（策略名/规则类型/级别/原因）      │ │ │
│ │ └───────────────────────────────────────────────────────┘ │ │
│ └────────────────────────────────────────────────────────────┘ │
│ ┌ Tab2 扫描与漏洞 ──────────────────────────────────────────┐ │
│ │ 制品漏洞扫描（SBOM / Scan）：制品下拉[生成 SBOM][触发扫描] │ │
│ │ SBOM 结果块（format/生成时间/sbom_data JSON）              │ │
│ │ 漏洞报告块：状态徽标 + C/H/M/L 卡 + 漏洞条目表              │ │
│ │ 项目漏洞报告（项目 #1）：制品行汇总表                      │ │
│ └────────────────────────────────────────────────────────────┘ │
│ ┌ Tab3 安全策略 ────────────────────────────────────────────┐ │
│ │ 安全策略（n）：ID/名称/分类/规则类型/级别/生效环境/描述/    │ │
│ │   启用(开关按钮)/操作(编辑/删除)                          │ │
│ │ 内置策略模板（5 类安全基线）：模板名称/分类/规则类型/级别/  │ │
│ │   描述/操作(应用)                                         │ │
│ └────────────────────────────────────────────────────────────┘ │
├──────────────────────────────────────────────────────────────┤
│ ┌ 新建/编辑安全策略弹窗（modal，@click.self 可关）───────────┐ │
│ │ 新建安全策略 | 编辑安全策略 #id（项目 #1）       [关闭]     │ │
│ │ 名称* 分类* 规则类型* 级别* 生效环境JSON(可选) 描述         │ │
│ │ [取消] [创建/保存]                                         │ │
│ └────────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘

各板块职责：

4. 交互元素

4.1 页头、顶部说明与操作结果提示条

页面状态用一组 ref 维护：loading（四个布尔位 policies/templates/vuln/projVulns，注意无 compliance 位）、busy（当前操作键字符串，非空即全局互斥——所有行内/页头按钮 :disabled="!!busy"）、alert（单槽提示）、summary、gateForm/gateResult、artifacts/selectedArtifactId/lastSbom/vulnReport/findings/projVulns、policies/templates、policyModal/policyForm。注意 busy 是全局互斥位：任一写操作（评估/SBOM/扫描/保存策略/启停/删除/应用模板）进行中，其余全部操作按钮同时禁用；Tab 内的查看类操作与 Tab 切换不受 busy 影响。

4.2 Tab1：合规总览 summary 卡

页面挂载（onMounted）即调 GET /projects/1/compliance-report，把响应解包对象按别名兜底映射进 summary，由 2×? 排布（flex wrap）的九张卡渲染。各卡取值（后端字段在 5.3 列出）：

失败行为：已修复（本批）——fetchCompliance 失败时写 complianceErr（SecurityPage.vue:657-660，取 errMsg(err)），模板以 v-if="complianceErr" 渲染独立错误态（红色「加载失败：{msg}」+「重试」按钮，:60-67），与正常九张卡 v-else 互斥渲染，不再出现「失败提示与九张 0 值卡同屏」的误导；点「重试」重新调用 fetchCompliance。该接口不在任何 Tab 切换时重复请求，只在页面挂载与「策略写操作成功后」（新建/编辑/启停/删除/应用模板的成功路径）由页面主动重拉。

4.3 Tab1：安全门禁手动评估表单（Security Gate）

「安全门禁手动评估（Security Gate）」卡片是整页最重要的预演入口。卡片正文解释文案：模拟部署前门禁检查：提交资源快照（tags / digest / signer_id / config / vulns / environment），由启用策略求值汇总 allow / warn / deny 决策并记录审计轨迹。

点「执行评估」后的行为（handleEvaluateGate）：先把 resource_data trim 后 JSON.parse——语法错误走 showAlert('resource_data 不是合法 JSON：' + e.message, 'alert-error') 直接返回，不发请求。合法则组装 payload {project_id:1, resource_type, resource_id:trim 后, resource_data:对象} 提交。成功（allow/warn）或 HTTP 403（deny）都会把结果放进 gateResult 并展示评估结果区：

• 评估结果区：第一行 <strong>评估结果：</strong> + decision 徽标（allow 绿 / warn 橙 / deny 红）+ 命中启用策略 {{policy_count ?? '-'}} 条 · 评估时间 {{formatTime(evaluated_at)}}。
• 无违规（violations 空）显示 全部启用策略通过，未命中违规。；有违规渲染违规表：策略名 / 规则类型 / 级别 / 原因（原因空显示 -）。gateResult.violations 元素含 policy_name/rule_type/severity/reason。
• 提示条：decision 为 allow/warn 时 success 安全门禁评估完成：decision=allow；deny 时 alert-error（后端 deny 走 403，见下方「deny 边界」）。

deny 边界（与直觉相反，务必知晓）：后端把 deny 决策作为 HTTP 403 返回（envelope code:40301，body 携带 data:{decision,policy_count,violations,evaluated_at}），因此： 1. apolloClient 响应拦截器先对 403 执行 alert('无权限执行该操作')——浏览器会先弹一个系统级 alert； 2. 页面 catch 会识别 403 body：已修复（提交 412e9c48） 当 err.response.status===403 且 body.data.decision 存在时，把 body.data 赋给 gateResult 并提示 安全门禁评估完成：decision=deny（策略拦截），详见下方违规列表（SecurityPage.vue:692-702）——deny 的违规表与普通 allow/warn 一样正常渲染； 3. 非上述形态（网络错/非 deny 业务错）仍走 showAlert('安全门禁评估失败：' + errMsg(err), 'alert-error')。 失败提示统一 安全门禁评估失败：{errMsg}（网络/非 deny 业务错时）或先弹「无权限执行该操作」（403 deny，随后即渲染违规表）。

4.4 Tab2：制品下拉与工具栏

制品列表本身由 onMounted 的 fetchArtifacts（GET /projects/1/artifacts）加载，失败提示 加载制品列表失败：{msg}。制品 id 默认选中第一项后，watch 会立刻触发一次漏洞报告加载。

4.5 Tab2：SBOM 结果块与漏洞报告块

「生成 SBOM」成功后，在工具栏下方渲染 SBOM 块（.sbom-block）：头行 SBOM：{{format||'-'}}（制品 #{{artifact_id || selectedArtifactId}}） + 生成时间 {{generated_at||created_at}}（格式化后），正文 JSON.stringify(sbom_data, null, 2) 的 code block 原文展示 SPDX JSON。注意：本页用「触发扫描」接口（POST /artifacts/:id/scan）后不自动展示 SBOM，SBOM 块只由「生成 SBOM」驱动；漏洞报告块与 SBOM 块相互独立，各自有值才渲染。 漏洞报告块（.vuln-block）数据来自 GET /artifacts/{selectedId}/vulnerabilities，页面对多形态响应做 parseVulnPayload 兼容（详见 5.3/5.4）。渲染内容：

findings 表格列：级别（severity 徽标 critical 红 / high 橙 / medium 黄 / low 蓝）/ 漏洞编号（mono，vuln_id）/ 组件包（package_name）/ 安装版本 / 修复版本 / 描述，空字段以 - 兜底。加载中显示 加载漏洞报告...；尚未扫描/未选制品的提示文案：选择制品后点击"触发扫描"生成漏洞报告；切换制品会自动加载已有报告。 后端对「未扫描」返回 404（制品尚未扫描，请先调用 POST /artifacts/:id/scan），页面提示 加载漏洞报告失败：{msg} 并把报告置空。

4.6 Tab2：项目漏洞报告（项目 #1）

卡片标题 项目漏洞报告（项目 #{{ PROJECT_ID }}），数据来自 onMounted 的 fetchProjVulns（GET /projects/1/vulnerabilities）。空态文案 暂无漏洞报告，先去 Tab 制品管理登记并扫描制品。；有数据渲染表格列：制品（artifactLabel + #id）/ 状态 / 扫描器 / Critical / High / Medium / Low / 扫描时间，各分级列空值显示 0。加载失败提示 加载项目漏洞报告失败：{msg}。 已修复（提交 412e9c48）：后端该接口返回 {project_id, artifact_count, vulnerable_count, totals:{critical,high,medium,low}, artifacts:[{artifact_id,name,version,scan_status,report?,findings?}]}；页面 fetchProjVulns 现优先 toList(data?.artifacts)，并按需回退数组/reports/report 形态（SecurityPage.vue:793-813），再把每行的 report 字段平铺（status 取 report.status || scan_status || status，scanner 取 report.scanner || scanner），项目漏洞汇总表因此能正常渲染。

4.7 Tab3：安全策略表

卡片标题 安全策略（{{policies.length}}），右上内嵌 新建安全策略（btn-sm）。加载失败提示 加载安全策略失败：{msg}；空态 暂无安全策略，点击"新建安全策略"或从下方模板快速应用（项目 #1）。。表格列：ID / 名称 / 分类 / 规则类型 / 级别 / 生效环境 / 描述 / 启用 / 操作：

• 分类徽标 categoryLabel(category)：image（镜像）/ config（配置）/ compliance（合规）/ deploy（部署），样式固定映射（image 蓝/config 橙/compliance 红/deploy 绿，未识别灰）。
• 规则类型列 ruleTypeLabel(rule_type) 显示中文长名（见附录 A RULE_TYPES）。
• 级别徽标：deny 红 / warn 橙。
• 生效环境列 envSummary(environments)：JSON 数组转逗号串；空/null 显示 全部环境。
• 启用列开关按钮：p.enabled ? '已启用'（btn-success） : '已停用'（btn-outline），!busy 才可点。

4.8 Tab3：内置策略模板与「应用」

卡片标题 内置策略模板（5 类安全基线）。数据来自 onMounted 的 fetchTemplates（GET /security-policies/templates），空态 暂无模板。。表格列：模板名称 / 分类 / 规则类型 / 级别 / 描述 / 操作（应用）。5 类模板逐字名称与描述见附录 B（源码 security.ListTemplates()）。

卡片底部 muted：应用模板按 (project_id, name) 幂等创建策略并默认启用。——同模板重复「应用」不会建第二条，而是返回已存在的策略（HTTP 201 Created，幂等命中视为已就绪）。

4.9 新建/编辑安全策略弹窗

弹窗头：{{ mode==='create' ? '新建安全策略' : '编辑安全策略 #'+policy.id }}（项目 #{{ PROJECT_ID }}）。字段：

底部按钮：取消（btn-outline，仅关弹窗）与提交按钮（busy==='savePolicy' 显示 保存中...；否则 create 模式显示 创建、edit 模式显示 保存）。提交效果：

弹窗为本地模态，点遮罩（@click.self）或「关闭」可放弃未保存内容，不触发请求。

5. 后端关联

5.1 API 客户端

action/web/src/api/apolloClient.js：axios 实例 baseURL /apollo-api/v1、timeout 30000ms、请求拦截器对所有请求附加 Authorization: Bearer <token>（token 仅取 apollo_token，不回退 aip_token）。响应拦截器：HTTP 2xx 且 code===0 时把 response.data 解包为业务数据；HTTP 2xx 但 code!==0 拒绝；4xx/5xx 提取 body.message || body.error 并把 message 别名写入 error.response.data.error 后 reject——401 清 token 并跳 /apollo/login（登录页自身 401 不跳，避免死循环），403 alert('无权限执行该操作')。页面各 catch 统一以 err.response?.data?.message || err.response?.data?.error || err.message（errMsg）展示后端错误。 403 双提示是本页常态：门禁 deny 的 HTTP 403 先触发拦截器系统级 alert('无权限执行该操作')，再被页面 catch 解析 body.data 并提示 安全门禁评估完成：decision=deny（策略拦截），详见下方违规列表（SecurityPage.vue:692-702）——演示时会看到浏览器原生 alert + 页内 alert 条两个提示，属预期现象。

5.2 端点表

以下端点后端路由见 action/products/apollo/server/server.go（security 段约 944-961 行），全部带权限中间件（第 6 章详述）。前端统一用 apolloClient，因此 URL 前缀为 /apollo-api/v1；下表写后端实际路径（前缀 /api/v1）。

5.3 响应结构示例

以下示例取自后端 handler 构造与既有测试期望（security_handlers.go、security/ 包、stage_d_smoke_test.go），页面看到的实际 JSON 即 envelope 解包后的 data。 GET /projects/1/compliance-report（envelope 解包后）：

{
  "project_id": 1,
  "total_policies": 6,
  "enabled_policies": 5,
  "evaluations_30d": 12,
  "allow_count": 7,
  "denied_count": 3,
  "warn_count": 2,
  "scanned_artifacts": 4,
  "vulnerable_artifacts": 2,
  "vuln_count": 5
}

字段即九张 summary 卡的取值；total_policies/enabled_policies 统计口径为 project_id=? OR project_id=0（项目 + 全局合并），其余计数取自项目维度。前端 fetchCompliance 对每个字段做别名兜底（total_policies→policy_count→policies 等），当前后端字段与之匹配。 POST /security-gate/evaluate（决策 allow/warn，HTTP 200）：

{
  "project_id": 1,
  "resource_type": "artifact",
  "resource_id": "artifact-3",
  "decision": "warn",
  "policy_count": 5,
  "violations": [
    {
      "policy_name": "部署必须签名",
      "rule_type": "require_signature",
      "severity": "warn",
      "reason": "资源缺少 signer_id，无法验证签名"
    }
  ],
  "evaluated_at": "2026-09-07T05:00:00.123Z"
}

decision 取 deny（任一 deny 级违规命中）> warn（仅 warn 级违规）> allow（全部通过）。policy_count 是参与求值的启用策略数（含环境过滤前计数），violations 为命中违规数组。 POST /security-gate/evaluate（决策 deny，HTTP 403 + fail envelope）：

{
  "code": 40301,
  "message": "部署被安全策略拒绝: 禁止生产 latest 标签: 制品使用了 latest 标签，禁止部署",
  "data": {
    "decision": "deny",
    "policy_count": 5,
    "violations": [
      {
        "policy_name": "禁止生产 latest 标签",
        "rule_type": "deny_latest_tag",
        "severity": "deny",
        "reason": "制品使用了 latest 标签，禁止部署"
      }
    ],
    "evaluated_at": "2026-09-07T05:01:00.123Z"
  },
  "request_id": "req_..."
}

这是本页最需要理解的形态差异：deny 决策不放在 HTTP 200 的 envelope 里，而是用 HTTP 403 承载（code 与 middleware 的 40301 一致），data 中照常携带完整评估明细。页面拦截器因此走 403 分支（系统 alert + 走 catch）；已修复（提交 412e9c48） catch 会把 403 body 的 data 写入 gateResult 并渲染违规表（SecurityPage.vue:692-702）——见 4.3。 GET /artifacts/3/vulnerabilities（envelope 解包后，report 与 findings 为同级字段）：

{
  "artifact_id": 3,
  "report": {
    "id": 11,
    "artifact_id": 3,
    "scanner": "zy_builtin",
    "status": "vulnerable",
    "total_critical": 1,
    "total_high": 1,
    "total_medium": 0,
    "total_low": 1,
    "scanned_at": "2026-09-07T05:02:00.123Z",
    "created_at": "2026-09-07T05:02:00.123Z"
  },
  "findings": [
    {
      "id": 31,
      "report_id": 11,
      "vuln_id": "CVE-2024-27080",
      "severity": "critical",
      "package_name": "nginx",
      "installed_version": "1.22.0",
      "fixed_version": "1.24.1",
      "description": ""
    },
    {
      "id": 32,
      "report_id": 11,
      "vuln_id": "RULE-LATEST-TAG",
      "severity": "low",
      "package_name": "demo-web",
      "installed_version": "1.2.0",
      "description": "制品使用 latest 标签，无法溯源到不可变版本"
    }
  ]
}

关键形态点：findings 与 report 平级，而非嵌套在 report 里。页面 parseVulnPayload 现优先命中 data.report 分支（SecurityPage.vue:752-774），把 vulnReport 置为嵌套的 report 对象、findings 取平级的 data.findings（平级读不到时回退 data.report.findings）——status/count 出自 report、findings 表照常渲染，两处均正确（见 4.5）。report.status 枚举 scanning/clean/vulnerable/error；report.scan_result_path（omitempty，扫描报告落盘路径）未扫描或为 error 时可缺省。未扫描访问本接口后端 404：{code:40400..., message:"制品尚未扫描，请先调用 POST /artifacts/:id/scan"}。 GET /projects/1/vulnerabilities（envelope 解包后，汇总对象）：

{
  "project_id": 1,
  "artifact_count": 4,
  "vulnerable_count": 2,
  "totals": { "critical": 1, "high": 1, "medium": 0, "low": 1 },
  "artifacts": [
    {
      "artifact_id": 3,
      "name": "demo-web",
      "version": "1.2.0",
      "scan_status": "vulnerable",
      "report": { "id": 11, "scanner": "zy_builtin", "status": "vulnerable" },
      "findings": [ { "id": 31, "vuln_id": "CVE-2024-27080", "severity": "critical", "package_name": "nginx" } ]
    }
  ]
}

已修复（提交 412e9c48）：页面 fetchProjVulns 现读 data.artifacts 并把每行的 report 平铺（status 取 report.status || scan_status、scanner 取 report.scanner || scanner，SecurityPage.vue:793-813），汇总表按「制品/状态/扫描器/Critical/High/Medium/Low/扫描时间」正常渲染。 GET /projects/1/security-policies（数组，单项 SecurityPolicy） 与 GET /security-policies/templates（数组） 见 5.4 后的模板清单；策略行关键字段：id/project_id/name/category/rule_type/severity/description/environments/enabled/created_at/updated_at（rule_config/environments omitempty，environments 空数组时页面显示「全部环境」）。

5.4 关键机制

六类规则与三档决策聚合。策略引擎（security/policy.go）把启用的策略逐条对资源数据求值：deny_latest_tag（tags 含可变标签即违规）、require_signature（signer_id 与 digest 须非空）、critical_vuln（vulns 中含 critical 级即违规）、no_plaintext_secret（config 文本含 password=/secret=/api_key= 模式即违规）、require_resource_limits（config 未声明 resources.limits 即违规）、custom（正则/匹配模式自定义，见 policy.go evaluateRule）。每条命中生成一条 Violation{policy_name,rule_type,severity,reason}；聚合规则是任一 deny 级违规→deny；否则任一 warn 级违规→warn；全过→allow。参与求值的策略 = 项目 + 全局（project_id=? OR project_id=0）中 enabled=true 者，并按资源 environment 做环境过滤（策略 environments 空 = 全部环境生效）。注意 project_id=0（全局）查询时只取全局策略——这正是门禁评估/激活路径与页面项目 #1 语义不同的根源（见下文）。 每次评估都落审计与历史。Evaluate 尾部调 persistEvaluation：把评估结果（project/resource/decision/违规）写入 policy_evaluation_results 表——合规总览的近 30 天计数与决策分布即由此统计。门禁 deny 还会在安全门禁的两种入口（手动 evaluate、部署链路）各落一条审计动作（SECURITY_GATE_EVALUATE denied / SECURITY_POLICY_APPLY_TEMPLATE 等，见第 6 章），与「审计日志」页贯通。 部署链路上的真实门禁（左移门禁）。后端把同一策略引擎接进期望状态激活动作，形成「先证安全再上线」的强制检查点：gitops.SyncEngine（gitops/service.go，激活新声明 draft→active 前，约 202 行）与期望状态激活 handler（server/handlers.go 的 handleActivateDesiredState，draft→active 前，286 行）都会调用 server 层注入的 apolloSecurityGate.EvaluateDeployment（server/server.go 166-232 行）。该适配器把声明组装成 EvaluateRequest：ResourceType=deployment、ResourceID="{projectID}:{声明名}"（如 1:order-api，跨项目同名声明审计可区分）、ResourceData 携带 digest/signer_id/config(整份声明)/vulns——其中 vulns 按 decl.Digest 匹配 artifacts.sha256 或 storage_path="bundle://{digest}" 关联的漏洞严重级（findVulnsByDigest），查不到扫描结果不误拦。决策 deny → 返回 403 AUTHZ_ERROR，激活被拒、声明保持 draft（Sync 场景整次 sync 置 failed 并把已处理声明并入失败历史供回滚）；warn 不拦截。该门禁还覆盖审批语义的分工：require_approval 通道的审批是「软门禁」（未过审不激活但 sync 成功），deny 是「硬门禁」（整次 sync 失败）。注意激活 handler 用 projectID=0 评估（server/handlers.go:308，DesiredState 为全局资源），故只有全局策略参与；已修复（提交 412e9c48）后模板「应用」落地的项目 #1 策略与页面新建的项目 #1 策略一样，都不会拦截手动激活路径——本页已无任何入口可创建全局策略（见第 6 章边界）。回滚（Rollback）属应急恢复不走门禁。 SBOM 与扫描的实现。SBOM 生成器产出 SPDX-2.3（请求 format 目前恒 spdx）JSON，写入 sbom 表（字段见 5.3），同制品单条幂等覆盖。扫描器 zy_builtin（security/scanner.go）是内置模拟实现（非真实 Trivy/Syft）：先建 report（status=scanning）并回写制品 vulnerability_scan_status=scanning，随后跑四条内置规则——RULE-PLAINTEXT-SECRET（metadata/storage_path/tags 含明文密钥模式，high）、RULE-LATEST-TAG（tags 含 latest，low）、RULE-NO-SHA256（缺 sha256，low）、RULE-UNSIGNED-BUNDLE（bundle 制品 metadata 无 signer_id，medium）——再按制品 metadata 声明的 packages 依赖列表对 7 条小型 CVE 库（nginx CVE-2024-27080、log4j-core CVE-2021-44228、openssl CVE-2023-0286、spring-core CVE-2022-22965、jackson-databind CVE-2020-36518、guava CVE-2023-2976、mysql CVE-2022-27456，均为 critical/high/medium/low 样例）做版本命中；完成把 report 置 clean/vulnerable 并回写制品状态、扫描报告落盘 data/security/reports。也就是说「触发扫描」得到的漏洞报告内容是规则命中 + 样例库命中的合成物，可复现但非真实漏洞库。 模板应用的幂等与策略命名空间。POST /security-policies/templates/{name}/apply 后端（handleApplyPolicyTemplate）按 ?project_id（缺省 0）解析归属；ApplyTemplate 按 (project_id,name) 唯一约束创建策略并 enabled=true，已存在则幂等返回现有策略（HTTP 201）。模板策略的 default_config 会写入 rule_config（如 deny_latest_tag 的 {tag:"latest", message:"制品使用了 latest 标签，禁止部署"}），供 evaluateRule 取用。已修复（提交 412e9c48）：页面调用 apply 时显式带 ?project_id=${PROJECT_ID}（SecurityPage.vue:977），模板落地为项目 #1 策略而非全局。 compliance-report 统计口径：策略数统计 project_id=? OR project_id=0（合并项目+全局）；scanned_artifacts 按项目下已扫描制品计数、vulnerable_artifacts 按检出漏洞的制品计数、vuln_count 累加漏洞条目。总览卡因此会比「安全策略（项目 #1）」表内的行数多出全局策略数——两处数字不必一致，属设计而非缺陷。

6. 权限与安全

• 认证分层：全部端点走独立 apollo_token（Bearer），列表/写接口按权限点 security:read/write/execute、制品读取用 artifact:read 鉴权；未登录 40101、无权限 40301，均由拦截器统一处理。
• 部署门禁是强制检查点：期望状态激活（draft→active）前与 GitOps sync 激活路径都会执行策略引擎，deny 硬拦截（HTTP 403）——它不依赖本页登录态，属后端进程内调用，无法从页面绕过。
• 全局 vs 项目策略边界：已修复（提交 412e9c48）后模板「应用」也带 ?project_id=1，与页面「新建安全策略」一样落地项目 #1（SecurityPage.vue:977）——本页已没有任何入口可创建全局策略（project_id=0）。而激活门禁以 project_id=0 评估只查全局策略（server/handlers.go:308），因此经本页创建/应用的策略都不会拦截手动激活；要让 deny 基线拦截手动激活，须由后端/脚本在全局作用域创建策略。项目 #1 级策略只在门禁手动评估与 Sync 目标项目路径（projectID>0）上生效。
• 敏感信息：资源快照与策略描述按用户输入透传展示；漏洞报告/合规统计只含元数据与计数，不含明文密钥。门禁评估与模板应用每次调用落审计（含 denied/failed），越权探测与拒绝原因全程留痕，可在「审计日志」页查到 SECURITY_GATE_EVALUATE / SECURITY_POLICY_APPLY_TEMPLATE 等动作。
• 写操作防护：删除策略有 confirm；启停无 confirm 但单次点击只切反态且成功后即刷新，无级联副作用；busy 全局互斥防并发写。deny 的 403 双弹窗（系统 alert + 页内错误条）是拦截器既有行为，非页面单独实现。

7. 常见问题与排错

以下问题均能从 SecurityPage.vue 的 catch/alert 文案、后端 handler/策略引擎代码与既有测试复现。 1. 点「执行评估」先弹系统 alert「无权限执行该操作」、再看到 deny 违规表：原因是决策为 deny 时后端用 HTTP 403 返回（含 data 明细），拦截器对 403 统一弹「无权限」。处理：这是预期行为不是权限问题——页面已能正常展示 deny 的违规表（提交 412e9c48，SecurityPage.vue:692-702）：系统 alert 后页内即渲染 decision=deny 与违规清单，无需再 curl 直调。 2. 评估总是 allow，期望被 deny 却没有：原因可能是①目标策略未启用；②策略 environments 限定了环境而资源快照的 environment 不匹配；③策略挂在项目 #1 而快照求值时…——注意页面评估 payload 恒带 project_id=1，后端会加载项目+全局策略，若你在「安全策略」Tab 建的策略 enabled=false 则不参与。处理：确认策略 enabled 开关为「已启用」、environments 留空或与快照 environment 匹配、severity 为 deny；再用 {"tags":["latest"],"environment":"prod"} 命中 deny_latest_tag 模板复现。 3. 合规总览的「策略数」比 Tab3 表格行数多：原因是总览统计口径是「项目 + 全局策略」合并（project_id=1 OR project_id=0），而 Tab3 只列项目 #1；模板「应用」落地的全局策略会计入总览但不显示在策略表。处理：属设计差异，可用「安全策略（n）」表的 n 与总览对照确认全局策略数 = 差值。 4. 漏洞报告显示为空态或扫描进行中，刷新也不变：status=scanning 时报告尚未生成（扫描进行中，请稍后刷新查看结果。），clean 时本就无条目（暂无漏洞条目（clean）。）。处理：等后端扫描完成（本页扫描器同步执行，通常立即完成）后重进制品或再点「触发扫描」刷新；仍为空则确认制品下拉已选中、且该制品确实执行过扫描（未扫描后端 404）。 5. 「漏洞报告」「项目漏洞报告」为空：属正常空态/加载中。已修复（提交 412e9c48）：项目漏洞报告列表现解析后端 artifacts 键并平铺 report 字段（SecurityPage.vue:793-813）、制品漏洞报告优先读 data.report（:752-774），有数据即渲染。处理：若仍为空，确认该制品确实执行过扫描（未扫描后端 404）、或状态为 scanning（尚未出结果）。 6. 「应用」模板提示失败：原因是模板名经 encodeURIComponent 编码后路径不匹配（含中文等需编码字符但后端未按编码解）或后端 security 服务未接线返回 404/500。处理：确认后端路由 POST /security-policies/templates/:name/apply 存在（server.go 954 行）；重复应用为幂等返回既有策略（仍 201），可在策略表确认是否已创建；已修复（提交 412e9c48）：调用带 ?project_id=${PROJECT_ID}，模板落地为项目 #1 策略（SecurityPage.vue:977）。 7. 删除/启停策略按钮点了没反应或报「无权限」：原因是 busy 非空（有其它写操作进行中）时按钮禁用不可点；或当前 apollo_token 主体缺 security:write/execute 权限点。处理：等其它操作完成再看按钮态；到「角色管理」页把 security:* 权限点授给当前角色后重进。 8. 扫描后制品状态与报告不一致：扫描是同步的——POST /scan 返回时 report 已定态（clean/vulnerable）。若 Tab2 漏洞报告状态徽标还是旧值，多为 fetchVulnReport 早于扫描写回。处理：再点一次「触发扫描」（成功后自动重拉报告），或刷新页面看制品 vulnerability_scan_status。 9. 想验证真实部署也会被 deny 拦截：在制品管理登记制品并扫描出 critical 漏洞（或声明 digest 关联 bundle），应用「Critical 漏洞拒绝」模板到全局，再到「期望状态/部署与漂移」页激活引用该 digest 的声明。处理：激活应被 403 拒绝并保持 draft；在审计日志搜 SECURITY_GATE_EVALUATE（denied）确认拦截，而非只看本页手动评估。 10. curl 直调门禁接口怎么写：curl -X POST http://127.0.0.1:18082/api/v1/security-gate/evaluate -H "Authorization: Bearer {apollo_token}" -H "Content-Type: application/json" -d '{"project_id":1,"resource_type":"artifact","resource_id":"demo","resource_data":{"tags":["latest"]}}'——deny 时返回 403 的 envelope（data 含 violations），allow/warn 返回 200。

8. 已知缺陷与边界

附录 A：页面文案速查（与 SecurityPage.vue 逐字一致）

附录 B：5 类内置策略模板（与 security.ListTemplates() 一致）

分类取值：image / config / compliance / deploy；RULE_TYPES 六项长名（前端下拉逐字）：deny_latest_tag（禁止 latest 标签） / require_signature（部署必须签名） / critical_vuln（Critical 漏洞拒绝） / no_plaintext_secret（禁止明文密钥） / require_resource_limits（必须设置资源限制） / custom（自定义模式匹配）。