chenchenandClaude Opus 4.8
0fe1d20d67
按桌面客户端统一方案 v0.1 + agent_management Sub Mode Runtime 对接,强制全量统一,不留兼容。
命名统一(强制,无兼容):
- 全仓 agnet/Agnet/AGNET → agent/Agent/AGENT:后端 Go(路由 /api/agent/*、env AGENT_*、
结构体/函数、19 个文件改名)、前端(agent-console/agent-hub、/api/agent 调用、i18n)、
DB(表 agent_*、列 agent_id)、compose/.env、文档、脚本。
- DB 加幂等迁移 renameAgnetTablesToAgent():启动时 rename 老 agnet_* 表/列,保住生产数据。
统一方案核心(10 项):
- callback 统一 /api/agent/callbacks/runtime-events(路由/广播URL/函数名)。
- artifact 兜底判定改用 Runtime 权威信号 metadata.synthesized(§7.2)+ 结构化 artifact_type。
- Manager→Runtime 路径对齐 /api/agent/sub-agile/deployments(§2.2),{deployment_id} 回退 swarm_id。
- 状态裁决 display_status:Manager 唯一裁判,completed 无有效产物→needs_codegen/
completed_without_deliverable(§10.6),接入 detail/timeline/workflow。
- GET /api/heicode/capabilities 能力发现(§6)。
- 模型策略 per_role(role_models)+ 收集 allowed_model_ids(§9)。
- resource_binding_id→secret_ref 服务端解析,客户端不再 inline secret_ref(§17.6)。
- 客户端统一路由层 /api/heicode/sub-agile|swarm/*(task≡deployment,复用控制面)+ workflow 投影。
- 日志分层 user_logs/debug_logs(§13)。
验证:go build ./... + go test(controller/router/model/middleware)全绿;前端 tsc -b + rsbuild build 通过。
待部署:VM .env 的 AGNET_*→AGENT_*;启动迁移自动 rename 表;其他三仓库需同步切到 /api/agent。
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
109 lines
3.2 KiB
Markdown
109 lines
3.2 KiB
Markdown
# 06. 安全与凭证管理说明
|
|
|
|
## 核心原则
|
|
|
|
Heicode 是 SaaS 产品，不能把凭证管理转嫁给用户，也不能让密钥散落在 Git、Markdown、日志或子 Agent 长期状态中。
|
|
|
|
安全目标：
|
|
|
|
1. 用户授权资源，平台托管凭证。
|
|
2. Heicode 服务端数据库只保存元数据和 `secret_ref`。
|
|
3. 长期密钥进入密钥保管器。
|
|
4. 子 Agent 只拿短期、最小权限、可审计凭证。
|
|
5. 高危操作必须由客户端审批。
|
|
|
|
## 凭证分类
|
|
|
|
| 凭证 | 示例 | 存放位置 |
|
|
|------|------|----------|
|
|
| Git 凭证 | GitHub token、SSH key | 密钥保管器 |
|
|
| 云凭证 | Azure、AWS、GCP access key | 密钥保管器 |
|
|
| 数据库凭证 | DB password、connection secret | 密钥保管器 |
|
|
| CodeGW 服务凭据 | 内部服务 token | 服务环境或密钥保管器 |
|
|
| 短期凭证 | 临时云 token、临时 Git token | 运行时注入，TTL 到期失效 |
|
|
|
|
## 密钥保管器
|
|
|
|
用户可见名称：密钥保管器。
|
|
|
|
技术实现：Azure Key Vault。生产环境中 Manager 通过 VM Managed Identity 访问 Key Vault，不在业务数据库保存明文密钥。
|
|
|
|
用户不需要直接登录 Azure Key Vault，也不需要看到 Key Vault 控制台。
|
|
|
|
## Secret Broker 流程
|
|
|
|
```text
|
|
用户绑定资源
|
|
-> Heicode 接收授权结果
|
|
-> Heicode Secret Broker 写入 Azure Key Vault
|
|
-> Azure Key Vault 返回或形成 azkv://... 形式的 secret_ref
|
|
-> Heicode DB 保存 secret_ref
|
|
-> 前端只展示脱敏引用和状态
|
|
```
|
|
|
|
Heicode 接口不得返回明文密钥。日志、错误信息、审计摘要也不得包含明文密钥。
|
|
|
|
## 子 Agent 访问凭证
|
|
|
|
子 Agent 不保存长期密钥。
|
|
|
|
推荐流程：
|
|
|
|
```text
|
|
Heicode 生成 Resource Grant
|
|
-> Agent 平台部署子 Agent
|
|
-> Agent 平台绑定运行时身份
|
|
-> 子 Agent 请求使用资源
|
|
-> 高危操作先走客户端审批
|
|
-> 审批通过后派生短期凭证
|
|
-> 短期凭证注入运行时
|
|
-> TTL 到期或任务结束后失效
|
|
```
|
|
|
|
## 高危操作
|
|
|
|
高危操作包括：
|
|
|
|
- 生产环境部署。
|
|
- 云资源创建、删除、扩缩容。
|
|
- 数据库迁移或写入。
|
|
- 访问生产密钥。
|
|
- 大额模型预算消耗。
|
|
|
|
审批必须记录：
|
|
|
|
- 审批人。
|
|
- 审批时间。
|
|
- 操作类型。
|
|
- 资源范围。
|
|
- 风险等级。
|
|
- TTL。
|
|
- 对应 deployment 或任务。
|
|
|
|
## 禁止事项
|
|
|
|
1. 禁止把 token 写入 Git。
|
|
2. 禁止把密钥写入 Markdown。
|
|
3. 禁止前端返回明文密钥。
|
|
4. 禁止在日志中打印密钥。
|
|
5. 禁止把长期云密钥注入子 Agent。
|
|
6. 禁止把 Azure Key Vault 管理入口作为普通用户入口暴露。
|
|
7. 禁止把 CodeGW key 原文交给客户端长期保存。
|
|
|
|
## 用户侧解释
|
|
|
|
推荐文案：
|
|
|
|
> Heicode 会把你的授权凭证存入密钥保管器。平台只在你授权的范围内，为对应任务和角色生成短期访问能力。密钥不会写入 Git、文档、日志或子 Agent 长期状态。
|
|
|
|
## 验收标准
|
|
|
|
| 验收项 | 标准 |
|
|
|--------|------|
|
|
| 数据库 | 只保存 `secret_ref`，不保存明文密钥 |
|
|
| 前端 | 不显示明文密钥 |
|
|
| 日志 | 不包含 token、password、private key、access key |
|
|
| 子 Agent | 不保存长期凭证 |
|
|
| 高危操作 | 有客户端审批记录 |
|
|
| Azure Key Vault | 普通用户不可直接进入；Manager 仅通过受控后端身份访问 |
|