heicode-mananger/docs/deployment/Heicode-Manager-更换部署服务配置清单.md

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

⚠️ 2026-06-10 勘误：下列「普通 sub / 蜂群 + /api/swarms + SWARM_RUNTIME_*」属旧「HM 主导编排」模型，已作废。当前权威模型：单 Agent 走「模板 Agent + AM」（heicode-am-contract.md）；多 Agent 蜂群归 agent_swarm（HeiCode Swarm）仓（Master-Agent 编排），HM 侧 deferred，契约待 agent_swarm#2 冻结。见 docs/integration/heicode-swarm-deferred.md。本节 env 仅为历史记录（蜂群开关当前 SWARM_RUNTIME_ENABLED=false）。

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 侧继续补真实执行数据一致性和产物回写