taijibaga/heicode-mananger
9
0
Fork 0
Code Issues 12 Pull Requests Actions Packages Projects 1 Releases Wiki Activity
Files
6dbfc98552fdb9c72b5ef70c9af0ff14afdfbbc2
heicode-mananger/docs/deployment/Heicode-Manager-更换部署服务配置清单.md
T
chenchenandClaude Opus 4.8 0fe1d20d67 feat(agent): unify agnet→agent and implement client/runtime unification spec v0.1 core 
按桌面客户端统一方案 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>
2026-06-01 23:45:10 +08:00

9.6 KiB
Raw Blame History

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 为准：

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 / 蜂群联调配置

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：

AGENT_CALLBACK_SIGNING_SECRET=<生产 callback 签名密钥>

正式方案建议用 Azure Key Vault 托管该签名密钥，减少明文环境变量。

2.3 Azure Key Vault 配置

AZURE_KEY_VAULT_URL=https://heicode-kv.vault.azure.net

如果新服务使用 user-assigned managed identity，还需要：

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 里必须存在：

agent-callback-signing-key

建议 Secret value 为 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 到新服务。

需要保证：

HEICODE_PUBLIC_BASE_URL=https://code.xinghanlab.com

因为 Manager 发给 Agent Manager 的 callback 地址会基于它生成：

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 基础接口

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 健康

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 侧继续补真实执行数据一致性和产物回写
Reference in New Issue View Git Blame Copy Permalink