From dd712724efa3fab82c5ff63d71bef5ae6a21e25d Mon Sep 17 00:00:00 2001 From: "ye.zou" Date: Fri, 13 Feb 2026 14:06:54 +0800 Subject: [PATCH 1/2] doc: complete module index with keyword lookup and cross-module deps Add keyword-to-module lookup table for agent search efficiency, cross-module dependency hints from Feb 2026 fix patterns, and full plugin index covering all 30+ open-source plugins. Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 185 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 185 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000000..f948f2d6c8 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,185 @@ +# ZStack Java 项目规则 + +## 关键词速查 (Agent 优先用这个定位模块) + + + + +| 关键词 (中/英) | 模块路径 | 入口类 | +|---|---|---| +| 推理服务, inference, 模型部署, vLLM | `premium/plugin-premium/ai/` | `AIModelManagerImpl`, `VmModelServiceBackend` | +| AI, 模型管理, dataset | `plugin/ai/` | `AIModelManagerImpl` | +| DHCP, hostname, metadata, userdata, 扁平网络 | `plugin/flatNetworkProvider/` | `FlatDhcpBackend`, `FlatUserdataBackend` | +| 云主机, VM, 虚拟机, 启动, 停止, 迁移 | `compute/` | `VmInstanceManagerImpl` | +| GPU, PCI, 显卡, vGPU, SR-IOV | `premium/plugin-premium/container/` + `plugin/kvm/` | `HamiGpuManagerImpl`, `PciDeviceManagerImpl` | +| 安全组, security group, 规则 | `plugin/securityGroup/` | `SecurityGroupManagerImpl` | +| 负载均衡, LB, SLB | `plugin/loadBalancer/` | `LoadBalancerManagerImpl` | +| 端口转发, port forwarding | `plugin/portForwarding/` | `PortForwardingManagerImpl` | +| VIP, EIP, 弹性IP | `plugin/vip/` + `plugin/eip/` | `VipManagerImpl`, `EipManagerImpl` | +| 存储, 主存储, 卷 | `storage/` | `PrimaryStorageManagerImpl` | +| Ceph | `plugin/ceph/` | `CephPrimaryStorageFactory` | +| 本地存储, local storage | `plugin/localstorage/` | `LocalStorageFactory` | +| ZBS, MDS | `plugin/zbs/` | (ZBS 存储驱动) | +| 网络, L3, L2, IP | `network/` | `L3NetworkManagerImpl` | +| VXLAN, VPC 网络 | `plugin/vxlan/` | `VxlanNetworkFactory` | +| SDN, H3C | `plugin/sdnController/` | `H3cVcfcSdnControllerFactory` | +| KVM, 宿主机, host | `plugin/kvm/` | `KVMHostFactory` | +| 账户, 权限, quota, admin | `identity/` | `AccountManagerImpl` | +| IAM, 项目, 角色 | `premium/iam2/` | `IAM2ManagerImpl` | +| Zaku, 容器, k8s, GPU quota | `premium/plugin-premium/iam2-container/` | `IAM2ContainerManagerImpl` | +| 镜像, image | `image/` | `ImageManagerImpl` | +| HA, 高可用, 故障切换 | `premium/ha/` | `HaManagerImpl` | +| LongJob, 长任务, 下载 | `core/` (longjob 子包) | `LongJobManagerImpl` | +| 灰度升级, grayscale | `premium/plugin-premium/src/` | `GrayscaleUpgradeManagerImpl` | +| ZQL, 查询, search | `search/` | `QueryFacadeImpl` | +| 备份, backup, zbox | `premium/plugin-premium/zboxbackup/` | `ZBoxBackupFactory` | +| 裸金属, bare metal | `premium/baremetal2/` | `BareMetal2InstanceManagerImpl` | +| GuestTools, VM tools, qga | `premium/guesttools/` | `GuestToolsManagerImpl` | +| 策略路由, policy route | `premium/plugin-premium/policyRoute/` | `VyosPolicyRouteBackend` | +| 组播, multicast, PIMD | `premium/plugin-premium/multicast-router/` | `MulticastRouterManagerImpl` | +| 监控, zwatch, 告警 | `premium/zwatch/` | `ZWatchManagerImpl` | +| ACL, 访问控制 | `plugin/acl/` | `AccessControlListManagerImpl` | +| LDAP, 登录 | `plugin/ldap/` + `premium/plugin-premium/iam2-ldap-plugin/` | `LdapManagerImpl` | +| SSO, CAS, OAuth, SAML | `premium/plugin-premium/sso-plugin/` | `CasClientManagerImpl`, `OAuth2ManagerImpl` | +| 虚拟路由器, VR, vyos | `plugin/virtualRouterProvider/` | `VirtualRouterManagerImpl` | +| OVN, OVS | `premium/plugin-premium/ovn/` | `OvnControllerVmKvmFactory` | +| CDP, 数据保护, 快照 | `premium/cdp/` | (CdpManagerImpl) | +| 计费, billing | `premium/billing/` | (BillingManagerImpl) | +| NFS | `plugin/nfsPrimaryStorage/` | `NfsPrimaryStorageFactory` | +| 端口镜像, port mirror | `premium/plugin-premium/portMirror/` | `PortMirrorManagerImpl` | +| 流量计, flow meter | `premium/plugin-premium/flowMeter/` | `FlowMeterManagerImpl` | +| VPC 防火墙 | `premium/plugin-premium/vpcFirewall/` | `VpcFirewallManagerImpl` | + +## 跨模块依赖 (改 A 时也要检查 B) + + + +| 改动模块 | 经常联动的模块 | 原因 | +|---|---|---| +| `premium/plugin-premium/ai/` | `plugin/flatNetworkProvider/` | 推理 VM 的 DHCP/hostname/metadata | +| `premium/plugin-premium/ai/` | `compute/` | VM 创建/systemTags/生命周期 | +| `premium/plugin-premium/ai/` | `core/` (longjob) | LongJob cancel/rerun/recoverable 模式 | +| `premium/plugin-premium/iam2-container/` | Zaku API (外部) | GPU quota key 映射，必须查 Zaku 文档 | +| `plugin/securityGroup/` | `premium/plugin-premium/iam2project-securitygroup-plugin/` | IAM 项目级安全组检查 | +| `plugin/loadBalancer/` | `premium/` (灰度升级) | SLB 在灰度期间需保护 | +| `plugin/vip/` | `plugin/eip/` + `plugin/portForwarding/` | 共享 VIP 资源，并发操作需串行化 | +| `plugin/kvm/` | `premium/plugin-premium/container/` | GPU 直通/PCI 设备 | +| `premium/guesttools/` | `plugin/flatNetworkProvider/` | NIC 同步覆盖 DHCP 配置 | + +## 模块完整索引 + +### 核心模块 + +| 模块 | 路径 | 入口类 | 说明 | +|---|---|---|---| +| Header | `header/` | 各 VO/Inventory | API 数据模型定义 | +| Core | `core/` | `GlobalConfigFacadeImpl`, `LongJobManagerImpl` | 核心引擎(消息总线/DB/LongJob) | +| Utils | `utils/` | (工具函数) | 通用工具库 | +| Compute | `compute/` | `VmInstanceManagerImpl` | 虚拟机生命周期 | +| Storage | `storage/` | `PrimaryStorageManagerImpl` | 存储卷管理 | +| Network | `network/` | `L3NetworkManagerImpl` | 网络资源 | +| Identity | `identity/` | `AccountManagerImpl` | 账户/Quota 管理 | +| Image | `image/` | `ImageManagerImpl` | 镜像管理 | +| Search | `search/` | `QueryFacadeImpl` | ZQL 查询引擎 | +| Configuration | `configuration/` | `ConfigurationManagerImpl` | 全局配置 | +| REST | `rest/` | `RESTApiFacadeImpl` | REST API 层 | + +### 开源插件 (plugin/) + +| 插件 | 路径 | 入口类 | 说明 | +|---|---|---|---| +| ACL | `plugin/acl/` | `AccessControlListManagerImpl` | 访问控制列表 | +| ApplianceVM | `plugin/applianceVm/` | `ApplianceVmFactory` | 系统 VM 基类 | +| Ceph | `plugin/ceph/` | `CephPrimaryStorageFactory`, `CephBackupStorageFactory` | Ceph 存储 | +| EIP | `plugin/eip/` | `EipManagerImpl` | 弹性 IP | +| FlatNetwork | `plugin/flatNetworkProvider/` | `FlatDhcpBackend`, `FlatUserdataBackend` | 扁平网络(DHCP/metadata) | +| HostNIC | `plugin/hostNetworkInterface/` | `LldpManagerImpl` | 主机网卡/LLDP | +| KVM | `plugin/kvm/` | `KVMHostFactory` | KVM 虚拟化驱动 | +| LDAP | `plugin/ldap/` | `LdapManagerImpl` | LDAP 登录 | +| LoadBalancer | `plugin/loadBalancer/` | `LoadBalancerManagerImpl` | 负载均衡 | +| LocalStorage | `plugin/localstorage/` | `LocalStorageFactory` | 本地存储 | +| NFS | `plugin/nfsPrimaryStorage/` | `NfsPrimaryStorageFactory` | NFS 存储 | +| PortForwarding | `plugin/portForwarding/` | `PortForwardingManagerImpl` | 端口转发 | +| SDN Controller | `plugin/sdnController/` | `H3cVcfcSdnControllerFactory` | H3C SDN | +| SecurityGroup | `plugin/securityGroup/` | `SecurityGroupManagerImpl` | 安全组 | +| SshKeyPair | `plugin/sshKeyPair/` | `SshKeyPairManagerImpl` | SSH 密钥对 | +| Vhost | `plugin/vhost/` | (VhostManager) | vhost 重连管理 | +| VIP | `plugin/vip/` | `VipFactory` | 虚拟 IP | +| VirtualRouter | `plugin/virtualRouterProvider/` | `VirtualRouterManagerImpl` | 虚拟路由器 | +| VXLAN | `plugin/vxlan/` | `VxlanNetworkFactory` | VXLAN 网络 | +| AI (开源) | `plugin/ai/` | `AIModelManagerImpl` | AI 模型管理(开源部分) | +| ZBS | `plugin/zbs/` | (ZBS 存储驱动) | ZBS 分布式存储 | +| Directory | `plugin/directory/` | `DirectoryManagerImpl` | 目录服务 | +| CBD | `plugin/cbd/` | (CBD 存储) | CBD 块存储 | +| Expon | `plugin/expon/` | `ExponStorageFactory` | Expon 存储 | +| Xinfini | `plugin/xinfini/` | (Xinfini 存储) | Xinfini 存储 | + +### Premium 插件 (premium/plugin-premium/) + +> 详细索引见 `premium/CLAUDE.md`。以下列出高频模块。 + +| 插件 | 路径 | 入口类 | 说明 | +|---|---|---|---| +| AI Premium | `premium/plugin-premium/ai/` | `AIModelManagerImpl`, `ModelServiceSubManager` | 推理服务/模型部署 | +| Container/GPU | `premium/plugin-premium/container/` | `ContainerManagerImpl`, `HamiGpuManagerImpl` | 容器+GPU 管理 | +| IAM2 Container | `premium/plugin-premium/iam2-container/` | `IAM2ContainerManagerImpl` | Zaku 集成/GPU Quota | +| PolicyRoute | `premium/plugin-premium/policyRoute/` | `VyosPolicyRouteBackend` | VPC 策略路由 | +| SSO | `premium/plugin-premium/sso-plugin/` | `CasClientManagerImpl`, `OAuth2ManagerImpl` | SSO 登录 | +| Multicast | `premium/plugin-premium/multicast-router/` | `MulticastRouterManagerImpl` | 组播路由 | +| PortMirror | `premium/plugin-premium/portMirror/` | `PortMirrorManagerImpl` | 端口镜像 | +| VpcFirewall | `premium/plugin-premium/vpcFirewall/` | `VpcFirewallManagerImpl` | VPC 防火墙 | +| FlowMeter | `premium/plugin-premium/flowMeter/` | `FlowMeterManagerImpl` | 流量计 | +| OVN | `premium/plugin-premium/ovn/` | `OvnControllerVmKvmFactory` | OVN SDN | +| SR-IOV | `premium/plugin-premium/macvlan/` | `VmMacVlanNicFactory` | SR-IOV 网卡 | +| ZBoxBackup | `premium/plugin-premium/zboxbackup/` | `ZBoxBackupFactory` | ZBox 备份 | +| BlockStorage | `premium/plugin-premium/block-primary-storage/` | `BlockPrimaryStorageManagerImpl` | 块存储 | +| Mevoco/灰度 | `premium/plugin-premium/src/` | `GrayscaleUpgradeManagerImpl` | 灰度升级管理 | + +### Premium 顶级模块 (premium/) + +> 详细索引见 `premium/CLAUDE.md` + +| 模块 | 路径 | 入口类 | 说明 | +|---|---|---|---| +| IAM2 | `premium/iam2/` | `IAM2ManagerImpl` | 身份和访问管理 | +| BareMetal2 | `premium/baremetal2/` | `BareMetal2InstanceManagerImpl` | 裸金属 | +| Hybrid | `premium/hybrid/` | `AliyunNetworkServiceBase` | 混合云 | +| HA | `premium/ha/` | `HaManagerImpl` | 高可用 | +| CDP | `premium/cdp/` | (CdpManagerImpl) | 连续数据保护 | +| AutoScaling | `premium/autoscaling/` | `AutoScalingManagerImpl` | 自动伸缩 | +| FaultTolerance | `premium/faulttolerance/` | `FaultToleranceManagerImpl` | 故障容错 | +| DRS | `premium/drs/` | (DrsManagerImpl) | 分布式资源调度 | +| ZWatch | `premium/zwatch/` | `ZWatchManagerImpl` | 监控告警 | +| GuestTools | `premium/guesttools/` | `GuestToolsManagerImpl` | VM Tools | +| Billing | `premium/billing/` | (BillingManagerImpl) | 计费 | +| SNS | `premium/sns/` | (通知服务) | 通知服务 | + +## 代码探索优先规则 + +ZStack 核心业务逻辑由 `APIxxxxMsg` 消息驱动。探索业务流程时，优先按此链路追踪: + +1. **入口**: `APIxxxxMsg.java` — 消息定义（字段、校验注解） +2. **处理**: `handle(APIxxxxMsg msg)` — handler 方法（业务主逻辑） +3. **返回**: `APIxxxxEvent` / `APIxxxxReply` — 结果定义 + +### Explore Agent 搜索策略 +- **先查关键词速查表**，直接跳到对应模块，不要盲目 grep 全仓库 +- 如果速查表没命中，用 `Grep "APIxxxxMsg"` 或 `Grep "handle(API.*Msg"` 定位入口 +- 如果 handler 里调用了 `xxxExtensionPoint`，继续追踪 `@Extension` 实现类 +- Sub-manager 模式: 大 Manager 拆分后，handler 可能在 `XxxSubManager.java` 中，不要只看主 Manager +- **检查跨模块依赖表**: 如果改动模块有联动模块，一并检查 + +### 日志分析起点 +- ZStack 日志中 `API msg[APIxxxxMsg]` 是请求入口标记 +- 从这里开始追踪 `task[uuid]` 或 `job[uuid]` 可以串联完整调用链 +- 错误日志搜索: 先找 `ERROR` + 相关 `APIxxxxMsg` 名称，再按 uuid 上下文展开 + +## 构建约定 +- 单模块编译: `mvn compile -pl -am -Dmaven.test.skip` +- Premium 子模块有独立 git 仓库: `cd premium && git remote -v` 确认 remote +- 首次构建或 vendor JAR 更新后: `./runMavenProfile build` + +## 代码风格 +- 事务使用 `new SQLBatch() { ... }.execute()`，不用 `dbf.runInTransaction()` +- `@Transient accountUuid` 由 `OwnedByAccountAspect.aj` 自动填充，无需手动 fallback +- 拆分大类时遵循 Extension/SPI 模式 (`@Extension` 注解、`SubManager` 接口) From 870fdc6e7c4bfcd135eccdfdf74f2fe9bf99cb85 Mon Sep 17 00:00:00 2001 From: "ye.zou" Date: Fri, 13 Feb 2026 14:08:28 +0800 Subject: [PATCH 2/2] [compute]: skip VmAttachNicOnHypervisorFlow when VM is stopped Resolves: ZSTAC-76466 Change-Id: I0821dd9e563da0186465af28f68982fafdf8145f --- compute/src/main/java/org/zstack/compute/vm/VmInstanceBase.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/compute/src/main/java/org/zstack/compute/vm/VmInstanceBase.java b/compute/src/main/java/org/zstack/compute/vm/VmInstanceBase.java index d8c8be6532..7122eddc14 100755 --- a/compute/src/main/java/org/zstack/compute/vm/VmInstanceBase.java +++ b/compute/src/main/java/org/zstack/compute/vm/VmInstanceBase.java @@ -2285,8 +2285,8 @@ void rollback() { setAdditionalFlow(flowChain, spec); if (self.getState() == VmInstanceState.Running) { flowChain.then(new VmInstantiateResourceOnAttachingNicFlow()); + flowChain.then(new VmAttachNicOnHypervisorFlow()); } - flowChain.then(new VmAttachNicOnHypervisorFlow()); flowChain.done(new FlowDoneHandler(completion) { @Override