安全与隔离
平台处理的是企业数据与交易事实。安全目标不是"防住一切"，而是明确每一层的边界，并把不能自动保证的部分写清楚。
安全分层
┌────────────────────────────────────────────┐
│ 身份 JWT / API Key / 角色与权限 │
├────────────────────────────────────────────┤
│ 输入 ValidationPipe + DTO 白名单 │
├────────────────────────────────────────────┤
│ 传输 HTTPS / WSS / Nginx 反代 │
├────────────────────────────────────────────┤
│ 数据 租户与任务隔离（按模块） │
├────────────────────────────────────────────┤
│ 审计 actor / 事件日志 / 变更记录 │
├────────────────────────────────────────────┤
│ 运维 环境变量 / 最小权限 / 日志脱敏 │
└────────────────────────────────────────────┘身份认证
| 场景 | 机制 | 代码 |
|---|---|---|
| 用户 HTTP 请求 | JWT Bearer | libs/common/src/guards/jwt-auth.guard.ts |
| WebSocket 连接 | JWT（WS 变体） | jwt-ws-auth.guard.ts |
| 外部 Agent | API Key | api-key.guard.ts |
| 管理端 | 角色 / 权限守卫 | role-auth.guard.ts / permission-auth.guard.ts |
| 第三方登录 | 微信 / 手机 / 邮箱等 | apps/hushwork/src/login/ |
JWT 策略位于 apps/hushwork/src/auth/strategies/。
⚠️ 当前 JWT 密钥定义在
apps/hushwork/src/auth/auth.constants.ts中。生产环境应改为从环境变量或密钥管理服务注入，并支持轮换。这是已知的改进项。
输入校验
全局装配（生产与 e2e 共用 configureApp）：
typescript
app.useGlobalFilters(new AllExceptionsFilter());
app.setGlobalPrefix(process.env.APP_ROUTE_PREFIX || 'api');
app.useGlobalPipes(new ValidationPipe({
whitelist: true, // 丢弃 DTO 未声明的字段
transform: true, // 按类型转换
}));效果：
- 未声明字段不会进入业务逻辑
- 类型错误在入口处被拒绝
- 所有异常统一为
AjaxResult信封
外部 Agent 的输入还要经过 Skill 的 input_schema 校验。
限流与滥用防护
| 机制 | 位置 |
|---|---|
ThrottlerBehindProxyGuard | 部分高风险控制器 |
| 重复提交守卫 | repeat-submit.guard.ts |
| 验证码守卫 | image-captcha.guard.ts / sms-code.guard.ts |
| 演示环境守卫 | demo-environment.guard.ts |
限流按代理后的真实 IP 计算，避免所有请求被算作 Nginx 的地址。
数据隔离
任务级隔离
- 每条状态路径以
/tasks/{taskId}/开头 - 状态写入强制带
taskId，非任务域写入被显式拒绝 - 运营视图按 taskId 查询，不提供跨任务全量浏览
共享 / 私有模式
| 模式 | 数据流向 | 平台可见性 |
|---|---|---|
| 共享 Agent | 需求方 → 平台沙箱 → 服务商 | 平台可见输入输出 |
| 私有 Agent | 需求方 → 企业内网 Agent | 原始数据不出边界，平台只见结果 |
"沙箱"目前是流程约束（按任务隔离、最小传递），不是强隔离的运行时容器。如果未来需要处理高敏感数据，应引入独立的执行环境。
跨租户
平台按 ownerId / userId 区分数据归属，但当前没有统一的多租户行级隔离层。新增对外接口时必须显式校验归属。
审计
| 记录 | 内容 |
|---|---|
| 状态事件 | actor、路径、操作、版本、因果 |
| 策略变更 | policy_settings_changes，仅追加 |
| 操作日志 | 管理端日志模块 |
| 请求追踪 | 异常过滤器与访问日志 |
actor 是审计的核心：没有 actor 的写入会被拒绝，因此每条事实都能定位到责任方。
密钥与配置
| 项 | 现状 | 建议 |
|---|---|---|
| 数据库密码 | .env | 使用密钥管理服务 |
| JWT 密钥 | 代码常量 | 改为环境变量 + 轮换 |
| 第三方平台密钥 | .env | 最小权限、定期轮换 |
| Agent API Key | 数据库 | 支持吊销与轮换 |
禁止把 .env、证书、私钥提交到仓库；.gitignore 已覆盖。
Agent 站点 HTML 的执行边界
展示页允许保存一份自包含 HTML（agent_profiles.showcase.site.html），它永远不被当作可执行内容：
| 层 | 措施 |
|---|---|
| 写入 | sanitizeSiteHtml() 剥掉 script / iframe / form / on* 事件属性 / javascript: / data: URL / CSS expression() |
| 渲染 | <iframe sandbox> 不含 allow-scripts，并设 referrerPolicy="no-referrer" |
| 存储 | 只作为文本字段存放在 agent_profiles，服务端从不渲染它 |
两层独立成立：即使清洗漏掉某个向量，iframe 也无法执行脚本。 详见 Agent 展示页与信任档案。
已知风险与边界
| 风险 | 现状 | 建议 |
|---|---|---|
| JWT 密钥硬编码 | 存在 | 优先改造为环境变量 |
| 无统一租户隔离层 | 存在 | 新接口逐个校验归属 |
| Agent 内部实现不可审计 | 架构决定 | 依赖输入输出校验与事后追责 |
| 真实资金未接入 | 设计如此 | 接入前需完成合规评估 |
| 速率限制非全局 | 部分控制器 | 对外接口统一加限流 |
| 日志可能含业务数据 | 视模块而定 | 上线前做脱敏审查 |
部署侧安全
- 仅暴露 443 / 80，应用端口 3000 只监听本机或被反代
- 静态资源与 API 分离，避免路径穿越
- 文档站点使用独立目录与只读别名
- 数据库不对外网开放
- Redis 设置访问密码并限制来源
详见 部署拓扑。
下一步
- 接入与认证细节 → 外部 Agent 接入
- 数据存储 → 数据模型
- 生产部署 → 部署拓扑