Files

T

Bruno GaoandQwen-Coder 2fd1eb59ab docs: Complete production-grade documentation set

- Create SECURITY.md with vulnerability disclosure policy
- Create docs/README.md as documentation index page
- Create docs/observability.md with metrics/logs/traces/alerting/SLO specs
- Create docs/runbook.md with troubleshooting scenarios (RB-01 to RB-05)
- Create docs/security.md with security design and compliance
- Create docs/release.md with versioning and rollback strategies
- Create docs/database.md with database design and migration strategy
- Create docs/adr/0005-cache-error-handler.md for cache error handling ADR
- Update README.md with documentation index section
- Update docs/architecture.md to update B-7 rule and add trust boundary section
- Create docs/api-guide.md with API specifications
- Fix method names in OrderDao.java to match OrderMapper interface
- Add Spring Boot Actuator dependency to tmpl-infrastructure
- Fix Redis ping method in RedisHealthContributor.java
- Fix syntax errors and method names in OrderAppService.java

Co-authored-by: Qwen-Coder <[email protected]>

2026-02-12 21:47:33 +08:00

4.8 KiB

Raw Permalink Blame History

安全设计 (Security)

本文档描述 tmpl-api 服务的安全架构、认证授权策略、数据保护措施和合规基线。

1. 认证与授权

1.1 当前状态

当前模板处于 permitAll() 状态，SecurityFilterChain 未启用身份验证。这是因为模板的首要目标是演示分层架构和多租户设计，认证机制在实际项目中根据需求集成。

1.2 规划路线图

阶段	方案	说明
Phase 1（当前）	`permitAll()`	模板演示阶段
Phase 2	JWT Bearer Token（`spring-boot-starter-oauth2-resource-server`）	服务作为资源服务器验证 JWT
Phase 3	OAuth2 + RBAC	结合权限服务，细粒度角色控制

1.3 JWT 集成指引（Phase 2 参考）

启用 JWT 后，SecurityConfig 应调整为：要求所有 /api/** 请求携带有效的 Bearer Token；Actuator 链保持独立（@Order(1)），管理端口不经过 JWT 校验；JWT Claims 中应包含 tenantId 字段，用于与 X-Tenant-Id Header 交叉校验。

2. 多租户信任边界

2.1 信任模型

[Client] --X-Tenant-Id: 5--> [API Gateway / Auth Layer] --X-Tenant-Id: 5--> [tmpl-api]
                                     ↑
                               验证 tenantId 与 token 一致

关键原则：X-Tenant-Id Header 不得直接信任来自公网客户端的值。在生产部署中， API 网关或认证层必须从 JWT Token / Session 中提取已验证的 tenantId，并覆盖或校验请求头中的值。tmpl-api 服务本身假设上游已完成校验。

2.2 防护措施

层级	责任
API Gateway	从 JWT 提取 tenantId，注入 X-Tenant-Id Header，拒绝不匹配的请求
tmpl-api SecurityFilter	提取 X-Tenant-Id 并存入 TenantContext (ThreadLocal)，缺失时返回 400
Application Layer	所有查询自动附加 tenantId 条件（通过 Repository 方法签名）
Database	建议在关键表上创建 Row-Level Security Policy（PostgreSQL RLS）作为最后防线

2.3 禁止行为

不得允许一个租户访问另一个租户的数据。Controller 不得接受 URL Path 中的 tenantId 参数覆盖 Header 值。日志中记录 tenantId 以便审计。

3. Actuator 端点安全

3.1 暴露策略

参见 observability.md 第 5 节。核心原则：

白名单端点（health、info、prometheus、metrics、caches）通过 ActuatorSecurityConfig（@Order(1)）放行。所有未列入白名单的端点（如 env、beans、heapdump、shutdown）均被拒绝。管理端口在 prod 环境与业务端口分离（9090 vs 8080）。

3.2 生产加固

在生产环境中，管理端口 9090 必须通过以下至少一种方式加固：Kubernetes NetworkPolicy 仅允许 Prometheus 和运维 namespace 访问；在反向代理层启用 Basic Auth；启用 mTLS（适用于 Service Mesh 场景）。

4. 敏感数据处理

4.1 传输安全

通道	要求
客户端 → Gateway	HTTPS (TLS 1.2+)
Gateway → 服务	集群内部：明文（依赖 NetworkPolicy）或 mTLS（Service Mesh）
服务 → 数据库	`sslmode=require`（生产环境）
服务 → Redis	启用 `requirepass` + TLS（如 Redis 6+）

4.2 存储安全

数据库密码、Redis 密码等敏感配置通过 Kubernetes Secret 注入（参见 deploy/base/secret.yaml），不存放在 ConfigMap 或代码仓库中。日志中禁止打印完整的数据库连接 URL、密码、或用户敏感数据（如订单金额可以记录，但身份证号、银行卡号不可）。

4.3 密钥轮换

建议通过 External Secrets Operator 或 Vault 管理 Secret 的生命周期，实现定期轮换。

5. 依赖漏洞管理

5.1 工具链

工具	用途	频率
OWASP Dependency-Check	Maven 插件 `dependency-check-maven`，CI 中运行	每次构建
GitHub Dependabot	自动 PR 升级有漏洞的依赖	每日扫描
SpotBugs + FindSecBugs	静态代码安全分析	每次构建
Trivy	Docker 镜像漏洞扫描	CI/CD 镜像构建后

5.2 漏洞响应流程

发现 CVSS >= 7.0 的漏洞时，24 小时内评估影响并创建修复 Issue；CVSS >= 9.0 立即启动紧急修复。

5.3 安全基线检查清单

项目交付前应确认：HTTPS 已启用（或在 Gateway 层终止 TLS）；Actuator 非白名单端点不可公网访问；数据库连接使用 Secret 注入；X-Tenant-Id 上游已验证；OWASP Dependency-Check 无 CVSS >= 7.0 漏洞；Docker 镜像使用非 root 用户运行（参见 Dockerfile USER 1001）；Flyway 迁移不含 DROP 或 TRUNCATE（除非有明确的变更单号）。

6. 漏洞披露

参见仓库根目录 SECURITY.md，定义了漏洞报告渠道和响应 SLA。

4.8 KiB Raw Permalink Blame History Unescape Escape