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>
298 lines
9.6 KiB
Markdown
298 lines
9.6 KiB
Markdown
# Heicode Manager 更换部署服务配置清单
|
||
|
||
本文用于后续将 Heicode Manager 从当前 Azure VM 迁移到 Azure Container Apps、AKS、App Service Container 或其他容器托管服务时核对配置。结论先写清楚：**更换部署服务不是只切换域名**，必须同时迁移身份、密钥、环境变量、持久化、网络访问和回调地址。
|
||
|
||
## 1. 当前生产环境事实
|
||
|
||
| 项目 | 当前情况 |
|
||
|------|----------|
|
||
| 生产入口 | `https://code.xinghanlab.com` |
|
||
| 当前承载方式 | Azure VM 上运行 Docker 容器 |
|
||
| VM | `heicode` |
|
||
| Resource Group | `HEICODE` |
|
||
| 区域 | `southeastasia` |
|
||
| 应用容器 | `heicode` |
|
||
| 数据库 | Azure PostgreSQL: `heicode.postgres.database.azure.com` / DB `heicode` |
|
||
| Redis | Azure Redis: `heicode.redis.cache.windows.net:6380`，TLS |
|
||
| Runtime/Agent Manager | `http://20.212.121.126` |
|
||
| 当前 Runtime 创建入口 | `/api/swarms` |
|
||
| 当前线上版本参考 | `1.4.18` |
|
||
|
||
当前 VM 的 Managed Identity 状态：生产验证时 Azure metadata 返回 `Identity not found`，说明当前 VM 还没有可用的托管身份，或没有配置正确的 user-assigned identity。
|
||
|
||
## 2. 迁移时必须保留的核心环境变量
|
||
|
||
### 2.1 Manager 基础配置
|
||
|
||
这些变量要从当前 VM `.env` 迁到新服务，具体值以生产 `.env` 为准：
|
||
|
||
```env
|
||
SQL_DSN=<Azure PostgreSQL 连接串>
|
||
REDIS_CONN_STRING=<Azure Redis TLS 连接串>
|
||
SESSION_SECRET=<现有生产会话密钥>
|
||
CRYPTO_SECRET=<现有生产加密密钥>
|
||
FRONTEND_BASE_URL=https://code.xinghanlab.com
|
||
HEICODE_PUBLIC_BASE_URL=https://code.xinghanlab.com
|
||
```
|
||
|
||
注意：
|
||
|
||
- `SESSION_SECRET` / `CRYPTO_SECRET` 不能更换，否则可能影响现有登录态、加密数据或历史兼容。
|
||
- 数据库和 Redis 不应迁成容器内本地服务，继续使用 Azure 托管服务。
|
||
|
||
### 2.2 Agent Manager / 普通 sub / 蜂群联调配置
|
||
|
||
```env
|
||
AGENT_RUNTIME_ENABLED=true
|
||
AGENT_RUNTIME_BASE_URL=http://20.212.121.126
|
||
AGENT_RUNTIME_CREATE_PATH=/api/swarms
|
||
AGENT_RUNTIME_STOP_PATH=/api/swarms/{swarm_id}/stop
|
||
AGENT_RUNTIME_APPROVAL_DECISION_PATH=/api/swarms/{swarm_id}/approvals/{approval_id}
|
||
AGENT_RUNTIME_HEALTH_PATH=/api/agent/health
|
||
AGENT_RUNTIME_TIMEOUT_SECONDS=15
|
||
AGENT_RUNTIME_SERVICE_TOKEN=<生产 service token>
|
||
AGENT_CALLBACK_TOKEN=<生产 callback 兼容 token>
|
||
AGENT_RUNTIME_CALLBACK_SIGNING_SECRET_REF=azkv://heicode-kv.vault.azure.net/secrets/agent-callback-signing-key
|
||
```
|
||
|
||
当前生产为了让 Agent Manager 自动 callback 先跑通，配置了 HMAC fallback：
|
||
|
||
```env
|
||
AGENT_CALLBACK_SIGNING_SECRET=<生产 callback 签名密钥>
|
||
```
|
||
|
||
正式方案建议用 Azure Key Vault 托管该签名密钥，减少明文环境变量。
|
||
|
||
### 2.3 Azure Key Vault 配置
|
||
|
||
```env
|
||
AZURE_KEY_VAULT_URL=https://heicode-kv.vault.azure.net
|
||
```
|
||
|
||
如果新服务使用 user-assigned managed identity，还需要：
|
||
|
||
```env
|
||
AZURE_CLIENT_ID=<user-assigned managed identity client id>
|
||
```
|
||
|
||
如果使用 system-assigned managed identity，通常不需要配置 `AZURE_CLIENT_ID`。
|
||
|
||
## 3. Managed Identity 和 Key Vault 授权
|
||
|
||
迁到新服务后，VM 的身份不会自动跟过去。每种承载服务都要重新确认身份。
|
||
|
||
| 部署服务 | 要做什么 |
|
||
|----------|----------|
|
||
| Azure Container Apps | 给 Container App 开启 system-assigned identity，或挂载 user-assigned identity |
|
||
| AKS | 使用 workload identity 或 pod identity，并给对应身份授权 |
|
||
| App Service Container | 给 App Service 开启 managed identity |
|
||
| 新 Azure VM | 给新 VM 开启 system-assigned identity，或绑定 user-assigned identity |
|
||
|
||
Key Vault：`heicode-kv`
|
||
|
||
至少需要授权：
|
||
|
||
| 用途 | 权限 / RBAC |
|
||
|------|-------------|
|
||
| 读取 callback 签名密钥 | `secrets/get` |
|
||
| 健康检查列举能力 | `secrets/list` |
|
||
| Manager 写入资源密钥 PutSecret | `secrets/set` |
|
||
|
||
使用 Azure RBAC 时可参考：
|
||
|
||
| 场景 | 角色 |
|
||
|------|------|
|
||
| 只读取 Secret | `Key Vault Secrets User` |
|
||
| 读取并写入 Secret | `Key Vault Secrets Officer` |
|
||
|
||
Key Vault 里必须存在：
|
||
|
||
```text
|
||
agent-callback-signing-key
|
||
```
|
||
|
||
建议 Secret value 为 JSON：
|
||
|
||
```json
|
||
{"callback_signing_secret":"实际签名密钥"}
|
||
```
|
||
|
||
## 4. 持久化文件和日志
|
||
|
||
当前 VM 容器通过 bind mount 保存容器内文件。迁移到容器托管服务时不能继续依赖 VM 本地磁盘。
|
||
|
||
需要确认这些路径是否存在生产数据：
|
||
|
||
| 路径 | 用途 | 迁移建议 |
|
||
|------|------|----------|
|
||
| `/data` | 上传文件、运行时数据、应用持久文件 | 迁到 Azure Files、Blob Storage 或服务支持的持久卷 |
|
||
| `/app/logs` | 应用日志 | 迁到平台日志、Azure Monitor 或持久卷 |
|
||
|
||
迁移前要确认：
|
||
|
||
- 哪些文件必须保留。
|
||
- 哪些文件可以重建。
|
||
- 新服务重启、扩缩容后文件是否仍存在。
|
||
- 多副本部署时文件是否共享一致。
|
||
|
||
## 5. 网络和防火墙
|
||
|
||
迁移后新服务必须能访问：
|
||
|
||
| 目标 | 端口 / 协议 | 说明 |
|
||
|------|-------------|------|
|
||
| Azure PostgreSQL | `5432` / TLS | Manager 主库 |
|
||
| Azure Redis | `6380` / TLS | 缓存、会话或队列 |
|
||
| Agent Manager | `http://20.212.121.126` | 普通 sub / 蜂群 Runtime |
|
||
| Azure Key Vault | `https://heicode-kv.vault.azure.net` | 读取 callback 签名密钥和资源密钥 |
|
||
| NewAPI / 模型网关 | 以生产配置为准 | 模型调用、计费、渠道 |
|
||
|
||
需要特别核对：
|
||
|
||
- PostgreSQL 防火墙是否允许新服务出站 IP。
|
||
- Redis 防火墙/VNet 是否允许新服务访问。
|
||
- Key Vault 防火墙是否允许新服务访问。
|
||
- 如果使用 VNet 集成，DNS 解析是否正常。
|
||
- Agent Manager 使用 IP 联调时，后续切域名要同步更新 `AGENT_RUNTIME_BASE_URL`。
|
||
|
||
## 6. 域名和回调地址
|
||
|
||
域名是最后切换项，不是迁移的第一步。
|
||
|
||
迁移前建议流程：
|
||
|
||
1. 新服务先使用临时域名或默认域名启动。
|
||
2. 配好数据库、Redis、Key Vault、Agent Manager 环境变量。
|
||
3. 使用临时域名完成全量冒烟。
|
||
4. 确认 callback URL 是否仍为正式域名。
|
||
5. 再切 `code.xinghanlab.com` 到新服务。
|
||
|
||
需要保证：
|
||
|
||
```env
|
||
HEICODE_PUBLIC_BASE_URL=https://code.xinghanlab.com
|
||
```
|
||
|
||
因为 Manager 发给 Agent Manager 的 callback 地址会基于它生成：
|
||
|
||
```text
|
||
https://code.xinghanlab.com/api/agent/callbacks/swarm-events
|
||
```
|
||
|
||
如果临时域名联调，要么设置临时 `HEICODE_PUBLIC_BASE_URL`，要么确保正式域名已经能路由到新服务。
|
||
|
||
## 7. Container Apps 迁移示例核对
|
||
|
||
如果目标是 Azure Container Apps，至少要完成：
|
||
|
||
| 项目 | 必须确认 |
|
||
|------|----------|
|
||
| 镜像 | 使用与生产代码一致的镜像版本 |
|
||
| 环境变量 | 从 VM `.env` 迁移到 Container App secrets/env |
|
||
| Managed Identity | 开启 system-assigned 或绑定 user-assigned |
|
||
| Key Vault 权限 | 给 Container App identity 授权 `secrets/get/list/set` |
|
||
| PostgreSQL | 防火墙允许 Container App 出站 |
|
||
| Redis | 防火墙/VNet/TLS 正常 |
|
||
| 持久化 | `/data`、`/app/logs` 替换为 Azure Files/Blob/平台日志 |
|
||
| 域名 | `code.xinghanlab.com` 绑定和证书 |
|
||
| HTTPS | callback URL 必须是 HTTPS |
|
||
| 副本数 | 多副本下文件、会话、任务状态不能依赖本地内存 |
|
||
|
||
## 8. 上线前真实验证清单
|
||
|
||
迁移后必须真实点击或接口验证，不只看容器启动。
|
||
|
||
### 8.1 基础接口
|
||
|
||
```bash
|
||
curl -fsS https://code.xinghanlab.com/api/status
|
||
```
|
||
|
||
确认：
|
||
|
||
- `success=true`
|
||
- `version` 为本次发布版本
|
||
- `start_time` 已更新
|
||
|
||
### 8.2 登录和用户态接口
|
||
|
||
使用测试用户登录后验证：
|
||
|
||
- 登录成功。
|
||
- `/api/agent/user/deployments` 返回正常。
|
||
- 页面 `https://code.xinghanlab.com/deployments` 可打开。
|
||
|
||
### 8.3 Key Vault 健康
|
||
|
||
```text
|
||
GET /api/secret-store/status
|
||
```
|
||
|
||
期望：
|
||
|
||
- `configured=true`
|
||
- `reachable=true`
|
||
|
||
如果仍返回 `Identity not found`，说明新服务 identity 没配置好。
|
||
|
||
### 8.4 普通 sub / Agent Manager 联调
|
||
|
||
通过 Manager 创建普通 sub 敏捷 run，确认：
|
||
|
||
- Manager 返回本地 `deployment_id=dep_*`
|
||
- Manager 持久化 `runtime_swarm_id=swm_*`
|
||
- Agent Manager 自动 callback 写入 Manager timeline
|
||
- `/events` 有 `callback.*`
|
||
- `/timeline` 有 callback 项
|
||
- 不出现明文密钥
|
||
|
||
### 8.5 蜂群模式联调
|
||
|
||
确认：
|
||
|
||
- 蜂群创建入口可用。
|
||
- Runtime callback 可入库。
|
||
- 任务、事件、artifact、timeline 查询正常。
|
||
- 蜂群模式与普通 sub 模式不要混用字段语义。
|
||
|
||
### 8.6 模型调用和 NewAPI
|
||
|
||
确认：
|
||
|
||
- 模型列表可加载。
|
||
- 测试用户能拿到模型分组。
|
||
- 客户端模型调用有返回。
|
||
- NewAPI 日志能看到请求。
|
||
- 计费/额度扣减符合预期。
|
||
|
||
## 9. 切换和回滚建议
|
||
|
||
切换前：
|
||
|
||
- 保留 VM 当前部署，不要立即销毁。
|
||
- 新服务通过临时域名跑通全流程。
|
||
- 备份当前 `.env`。
|
||
- 记录当前 git commit、镜像 tag、数据库连接、Redis 连接。
|
||
|
||
切换时：
|
||
|
||
- 降低 DNS TTL。
|
||
- 切 `code.xinghanlab.com`。
|
||
- 立刻跑第 8 节冒烟。
|
||
|
||
回滚时：
|
||
|
||
- 将域名切回 VM。
|
||
- 保留数据库不回滚，除非确认新服务做了不兼容迁移。
|
||
- 检查 callback 是否有重复事件；Manager callback 按 `event_id` / `idempotency_key` 去重。
|
||
|
||
## 10. 当前遗留事项
|
||
|
||
| 项目 | 当前状态 | 后续动作 |
|
||
|------|----------|----------|
|
||
| 普通 sub 创建链路 | 已通过生产真实接口验证 | 保持 |
|
||
| Agent Manager 自动 callback | 已通过 HMAC fallback 验证入库 | 后续切到 Key Vault 正式密钥 |
|
||
| Azure Key Vault | URL 已配置，但 Managed Identity 返回 `Identity not found` | 给当前 VM 或未来服务配置 Managed Identity 并授权 Key Vault |
|
||
| Agent Manager 运行结果 | Runtime 状态可查，但目前返回 `tokens_used=0`、`artifacts=[]`，agent 仍显示 `running` | 需要 Agent Manager 侧继续补真实执行数据一致性和产物回写 |
|
||
|