从JWT密钥轮换到Trivy镜像扫描:ai-shortVideo-pipeline安全清单完整指南

原创2026-10-30 18:39:341,453 阅读

从JWT密钥轮换到Trivy镜像扫描:ai-shortVideo-pipeline安全清单完整指南

本指南面向首次部署 ai-shortVideo-pipeline(myAiVideos)的新手与运维同学,用一份可直接照做的安全清单,把这套「FastAPI 编排 + Spring Boot 网关」的短视频生产管线从密钥管理、访问鉴权、限流熔断、内容安全到Docker 镜像扫描一次性讲透。跟着本文走一遍,你的生产环境就能少踩 90% 的安全坑。

📋 为什么短视频 AI 管线需要一份安全清单?

ai-shortVideo-pipeline 是一条「飞书一句话 → 自动产出可发布短视频」的端到端流水线。它同时调度多家大模型 API(DeepSeek / Qwen / GLM / Kling / 火山 TTS)、读写 PostgreSQL / Redis / MinIO,并对外暴露 HTTP 与 SSE 接口。

这意味着它天然持有三类"高价值资产":

资产 泄露后果 本项目对应位置
AI 厂商 API Key 账单被盗刷、配额耗尽 .env + 网关环境变量
JWT 签名密钥 任意人可伪造合法 token 调用全部接口 GATEWAY_AUTH_JWT_SECRET
数据库 / 对象存储凭证 成片与用户数据被拖库 docker-compose.yaml

🎯 一句话:谁能控制密钥,谁就能控制这条管线。 下面 8 项安全控制,就是围绕"守住密钥 + 挡住非法访问 + 可审计可追溯"三层目标展开的。

1. 密钥强制必填:从源头杜绝"裸奔启动"

很多项目栽在"本地用默认弱密钥,顺手带到生产"。本项目把这道防线写死在了 docker-compose.yaml 里——网关的 JWT 密钥使用了 compose 的强制变量语法 :?:

GATEWAY_AUTH_JWT_SECRET: "${GATEWAY_AUTH_JWT_SECRET:?GATEWAY_AUTH_JWT_SECRET must be set in .env (no fallback to dev secret; generate via `openssl rand -base64 32`)}"

这意味着:只要 .env 里没配 GATEWAY_AUTH_JWT_SECRET,docker compose up 会直接启动失败,而不是悄悄回落到某个开发密钥。这是新手最容易忽略、却最能"防蠢"的一道闸门。

生成一个合格的强随机密钥只需一行:

openssl rand -base64 32

在代码侧,JwtService.java 还会对密钥长度做二次校验——HS256 要求密钥 >= 32 bytes,不足会直接抛 IllegalStateException 拒绝启动。

✅ 清单第 1 项:永远用 openssl rand -base64 32 生成密钥,绝不复用示例值、绝不让密钥进 Git。

2. JWT 密钥轮换:每 90 天换一把锁

密钥用久了就有被拖库、被内鬼拿走的概率,所以定期轮换是生产标配。docs/operations-manual.md 第 4.1 节给出了标准四步轮换流程:

# 1. 生成新密钥
NEW=$(openssl rand -base64 32)

# 2. 写入 .env
sed -i "s|^GATEWAY_AUTH_JWT_SECRET=.*|GATEWAY_AUTH_JWT_SECRET=${NEW}|" .env

# 3. 重启网关
docker compose up -d --force-recreate gateway

# 4. 通知客户端重新签 token;旧 token 立即失效

这里有个新手必须理解的取舍:HS256 是对称签名,密钥一旦换掉,旧 token 会立刻失效。所以轮换时要同步通知所有客户端(飞书机器人、CLI、前端)重新签发。

鉴权过滤逻辑在 JwtAuthFilter.java:它从 Authorization: Bearer <token> 解析密钥,解析失败 / 过期会返回结构化 401,并把 trace_id 带进响应体方便排查;成功后把 userId / tenantId 注入 exchange 与 MDC,供下游审计与计量使用。

✅ 清单第 2 项:把「JWT 密钥轮换(90 天)」写进值班日历;轮换时确认所有客户端都已换新 token。

3. AI 厂商 API Key 轮换与「未配置 ≠ 故障」

大模型密钥泄露通常意味着真金白银的被盗刷。docs/operations-manual.md 第 4.2 节建议:在各厂商控制台轮换 Key 后,更新 .env 并重启相关容器:

docker compose up -d --force-recreate orchestrator worker gateway

这里有个很值得新手学习的优雅降级设计。网关的 LlmRouter.java 在多模型 failover 时,会区分三类错误:

  • 4xx → 业务错误,直接抛 BusinessErrorException,不重试;
  • 5xx / timeout → 上游故障,计入失败计数、触发熔断切换;
  • config(未配 key) → 既不计入失败计数,也不触发黑名单,只在调用链里记一条 config。

💡 为什么这么设计?注释写得很直白:"配置错误是运维问题,不是 SLO 问题"。这样当某家 key 还没填好时,不会把失败计数器"污染"掉,运维能清楚地区分"我忘了配 key"和"上游真的挂了"。

✅ 清单第 3 项:为每家大模型建立独立轮换周期;发现 Key 异常立即在控制台作废并轮换。

4. 网关多层纵深防御:限流 / 熔断 / 审计 / 全链路追踪

网关是整个系统的"城门",它用一串按顺序执行的 WebFilter 构成纵深防御。在 gateway/README.md 里能清楚看到这个执行链:

HIGHEST_PRECEDENCE       → TraceIdFilter   ← 必须最先,401 也要带 trace_id
HIGHEST_PRECEDENCE + 10 → JwtAuthFilter   ← 鉴权
... 业务 Controller ...
LOWEST_PRECEDENCE        → AuditLogFilter  ← 最后,能拿到最终 status

4.1 全链路 TraceId:一条请求全程可追溯

TraceIdFilter.java 会读取请求头 X-Trace-Id,客户端没传就自动生成一个 UUID32,并同时写回响应头 + 注入 MDC,再透传给下游 Python 服务。排查任何一次异常,grep 一个 trace_id 就能串起 Java / Python 两侧的完整日志。

4.2 双层限流:用户级 + 全局令牌桶

RateLimitFilter.java 采用 Resilience4j 令牌桶,对每个接口做用户级 + 全局两层限流(规则来自 RateLimitProperties.java)。命中上限时返回 429,并带上 Retry-After、X-RateLimit-Remaining 等标准头,同时向 Prometheus 打点 gateway.ratelimiter.rejected。

⚠️ 新手提醒:/actuator/** 与 /health 默认在限流白名单里。生产环境不要让网关 8080 端口直接暴露公网,前面应加反向代理——否则任何人都能扫你的健康检查与指标。

4.3 熔断降级:保护昂贵的大模型调用

KlingService.java 用 Resilience4j 的三态熔断器(CLOSED / HALF_OPEN / OPEN)保护 Kling 图生视频调用。当熔断进入半开状态时,applyDowngrade 会自动把生成 mode 降级为 std,在可用性与成本之间取平衡,避免雪崩。

4.4 审计日志:谁在什么时候动了什么

AuditLogFilter.java 放在过滤器链最末,为每个请求落一条含 method / path / status / latency / user / tenant / trace 七个字段的审计日志。做安全回溯时,这就是你的"行车记录仪"。

✅ 清单第 4 项:给 429 / 401 配置监控告警;定期用 trace_id 抽查审计日志,确认能还原任意一次请求。

5. 内容安全:关键词守卫 + 提示词清洗

短视频内容直接面对监管与平台风控,"内容安全"是硬指标。本项目在编排层设了两道闸:

  • 关键词守卫 core/guard.py:content_guard() 对文本做敏感词拦截,命中即拒绝。词表由 config/settings.py 的 blocked_keywords 维护(默认覆盖政治、赌博、色情、毒品、诈骗等类目)。
  • 视觉提示词清洗 layers/L3_visual/prompt_safety.py:sanitize_visual_prompt() 在送入 Kling 文生图前,剔除品牌词、UI/文字类触发词,并追加一段 textless guard,从源头减少画面里的伪文字、伪 Logo——既降低合规风险,也提升出片质量。

✅ 清单第 5 项:上线前根据行业属性扩充 blocked_keywords;把内容安全拦截率纳入日常监控。

6. Trivy 镜像扫描:别让基础镜像成为后门

容器里跑着 Python 3.11 和 JDK 21,基础镜像中的系统组件漏洞往往是最容易被忽视的攻击面。docs/operations-manual.md 第 4.5 节把镜像扫描列为例行公事:

# 扫描构建产物镜像中的已知漏洞
trivy image ai-platform-app:latest
trivy image ai-platform-gateway:latest

本项目在镜像构建上也已经做了正确的"基线动作",为 Trivy 扫出更干净的结果打下基础:

  • 网关 gateway/Dockerfile 采用多阶段构建:maven:3.9-eclipse-temurin-21 负责编译,最终只把产物拷进轻量的 eclipse-temurin:21-jre-alpine,大幅缩小攻击面;
  • 并且显式创建了非 root 用户 spring,以 USER spring:spring 运行——一旦容器逃逸,攻击者拿到的也只是低权限账户,而不是 root。

✅ 清单第 6 项:把 trivy image 纳入 CI,对 Critical/High 级别漏洞设置阻断;定期 bump 基础镜像 tag。

7. 密钥卫生与端口暴露原则

最后两块"低成本、高收益"的安全习惯:

哪些文件绝不能进 Git(docs/operations-manual.md 第 4.3 节):

.env                 # 所有密钥
data/logs/           # 含敏感数据的 trace
output/              # 生成内容
data/hf_cache/       # 模型缓存

可用 gitleaks 扫描提交历史,确认没有密钥泄露:

gitleaks detect --source . --verbose

端口暴露原则(第 4.4 节):

端口 生产建议
80 / 443 公网(仅前端与必要 API)
8080(网关) 不直接暴露——前置反向代理
8000(FastAPI) 不公开——仅限内网
5432 / 6379 / 9000 / 9001 不公开——绑定 127.0.0.1 或内网 IP

✅ 清单第 7 项:.env 加进 .gitignore 并定期跑 gitleaks;数据库 / 缓存 / 对象存储端口一律只绑内网。

8. 部署安全检查清单(Copy-Paste 版)

把前 7 项浓缩成上线前可逐项打勾的清单:

  • [ ] .env 中 GATEWAY_AUTH_JWT_SECRET 由 openssl rand -base64 32 生成,且未在 Git 中
  • [ ] 所有 AI 厂商 API Key、KLING_*、MINIO_ROOT_PASSWORD 均已轮换为生产值
  • [ ] docker compose up 成功(证明密钥必填校验通过)
  • [ ] 网关 8080 前置反向代理,未直接暴露公网
  • [ ] 5432 / 6379 / 9000 / 9001 仅绑定内网 / 127.0.0.1
  • [ ] 限流规则已按接口配好,429 / 401 已接监控告警
  • [ ] 审计日志 + trace_id 抽查可还原一次完整请求
  • [ ] 内容安全 blocked_keywords 已按行业扩充
  • [ ] trivy image 与 gitleaks 已纳入 CI,无 Critical/High 残留
  • [ ] JWT 密钥轮换(90 天)已写入值班日历

总结

ai-shortVideo-pipeline 的安全设计可以概括成三道防线:

  1. 守住密钥——compose 强制必填 + 定期轮换 + 不落地 Git;
  2. 挡住非法访问——JWT 鉴权、双层限流、熔断降级、内容安全守卫;
  3. 可审计可追溯——全链路 trace_id + 七字段审计日志 + Trivy / gitleaks 例行扫描。

对新手来说,不必一开始就自建完整的 WAF 或零信任体系——先把上面这份 10 项清单做完,你的短视频 AI 管线就已经比绝大多数项目安全得多。等流量上来后,再按需叠加 RS256 + KMS、分布式限流、WAF 等进阶能力即可。

📚 延伸阅读:architecture.md(整体架构与治理机制)、docs/operations-manual.md(完整运维手册)、gateway/README.md(网关横切关注点详解)。

登录后查看全文
ai-shortVideo-pipeline