CMDB 资产管理（1）：系列总览与学习路线

本文是 devopsX 平台中“CMDB 资产管理”连续系列的第 1 篇，也是顶级模块的长期总览与学习导航。原规划稿已经完成为可独立运行、可测试、可审计、可从源码 ZIP 还原的 v1.0.0。正文不再把候选功能写成“以后补充”，而是只记录已经落盘、已经验证和明确未验证的边界。

文档版本v1.0.0
更新时间2026-09-16 23:43:56 +0800
当前状态第 1 篇总览、四篇完整教程、两篇完整源码汇总和独立源码 ZIP 均已完成；连续编号为（1）至（7），七篇文章已公开并通过远程回读与 HTTP 200 验证
Django Appcmdb，与 accounts 平级
前端方式Django Templates；没有 Vue、React、Node.js 或独立前端工程
项目结构保留 django-admin startproject devopsX 的标准双层结构；不创建 backend/，不把内层配置包改名为 config/

1 教程与源码导航

本模块统一采用连续文章编号，必须按照第 1 篇到第 7 篇阅读。第 1 篇是当前总览与学习路线；第 2～5 篇是完整实现教程，正文章节编号从第 1 章连续到第 36 章，没有在分篇处重新编号；第 6～7 篇是最终源码汇总，只在完整文件边界切分。

顺序文章内容范围链接
1CMDB 资产管理（1）：系列总览与学习路线（当前篇）模块定位、系列导航、数据所有权、同步边界、验证证据与学习路线当前页面
2CMDB 资产管理（2）：从应用首页到云资产模型第 1～9 章：环境、项目、App、数据所有权、模型、迁移、Admin、列表与详情CMDB 资产管理（2）：从应用首页到云资产模型
3CMDB 资产管理（3）：云资源发现、同步与变更历史第 10～18 章：DTO、Adapter、Fake Provider、同步、对账、生命周期与变更历史CMDB 资产管理（3）：云资源发现、同步与变更历史
4CMDB 资产管理（4）：权限、搜索、拓扑、导入导出与 API第 19～27 章：权限、POST 写操作、筛选分页、拓扑、标签、CSV 与 JSON APICMDB 资产管理（4）：权限、搜索、拓扑、导入导出与 API
5CMDB 资产管理（5）：阿里云 ECS、MySQL 与最终验收第 28～36 章：阿里云 Adapter、响应完整性、MySQL 边界、回归、打包与扩展CMDB 资产管理（5）：阿里云 ECS、MySQL 与最终验收
6CMDB 资产管理（6）：v1.0.0 源码汇总（上篇）最终 ZIP 第 1～37 项CMDB 资产管理（6）：v1.0.0 源码汇总（上篇）
7CMDB 资产管理（7）：v1.0.0 源码汇总（下篇）最终 ZIP 第 38～69 项CMDB 资产管理（7）：v1.0.0 源码汇总（下篇）

2 模块定位与独立边界

CMDB 负责云基础设施资产的统一建模、发现、对账、查询、导入导出和变化追踪。它是 devopsX 中一个独立 Django App，不等于整个平台，也不把其他业务模块的职责吸收到自己内部。

2.1 已实现的核心对象

  • CloudProvider：云厂商定义和 Adapter 标识。
  • CloudAccount：云账号元数据、稳定账号键、凭据环境变量前缀和地域白名单。
  • CloudRegion：云地域。
  • CloudAvailabilityZone：归属于地域的可用区。
  • ComputeInstance：当前 v1.0.0 的具体云资源类型。
  • ComputeInstanceTag：区分 Provider 标签和 CMDB 人工标签。
  • SyncRun：一次同步的触发方式、状态、数量、错误和完成时间。
  • ComputeInstanceChange：创建、更新、缺失、恢复和退役的字段级变化历史。

2.2 与其他 App 的关系

accounts/、cmdb/ 以及以后新增的 bastion/、automation/、deployment/、kubernetes/ 等 App 都位于外层项目根目录下，彼此平级。CMDB 不嵌套在 accounts 内，也不依赖尚未实现的跳板机、自动化、发布、监控、工单或审计 App。

其他模块以后通过稳定资产 ID、公开查询服务或版本化 API 使用 CMDB 数据，不应导入 CMDB 的视图、表单或私有同步实现，更不能绕过 CMDB 服务直接改写其数据表。

3 数据所有权与稳定身份

3.1 三类数据所有权

所有权代表字段同步规则
云厂商权威Provider Resource ID、实例名称、规格、原始状态、IP、地域、可用区、Provider 标签完整有效快照可以更新这些字段
CMDB 本地权威账号显示名称、account_key、credential_profile、地域白名单、人工标签云同步不得覆盖
对账生成生命周期、missing_since、retired_at、同步统计、变化历史只能由同步和受控退役流程维护

3.2 稳定身份

云账号使用“云厂商 + account_key”作为稳定身份；云主机使用“云账号 + 云厂商资源 ID”作为稳定身份。名称和 IP 都可能变化，因此不能用于去重。相同快照重复同步不会新增重复资产，这就是本项目中的幂等性。

4 Provider Adapter 与同步对账

4.1 Adapter 边界

Provider 层把不同云 SDK 的响应转换为统一、冻结的 DTO 和 DiscoverySnapshot。同步服务只认识标准化快照，不认识阿里云 SDK Response，也不接受 Provider 直接写 ORM。当前提供：

  • 确定性的 Fake Provider，用于教学、回归和错误场景复现；
  • 阿里云 ECS SDK V2 Adapter，用于地域、可用区、实例、标签和分页映射；
  • 统一的 sync_account(...) 同步入口。

4.2 完整快照与部分快照

只有“完整、成功、范围与账号配置相符”的权威快照，才允许把本次没有发现的旧资源标记为 missing。分页中途失败、响应节点缺失、地域集合异常、白名单范围不一致或 Provider 报错时，快照不能触发破坏性缺失对账。

4.3 生命周期

状态含义主要转换
present当前完整权威快照发现该资产首次发现、字段更新或从 missing 恢复
missing完整权威快照不再发现该资产再次发现时自动恢复为 present
retired用户执行了有权限控制的明确退役操作以后再次发现也不会自动恢复

退役不是硬删除。对 missing 资产执行退役会清空并审计 missing_since；已经 retired 的行再次被发现时，Provider 字段和最后发现时间仍可刷新，但同步不会自动取消退役，也不会静默改写其既有退役语义。

4.4 并发与故障边界

同步具有账号级准入、SQLite 写锁缓解、MySQL select_for_update、陈旧运行恢复、替代运行 fencing 和配置变更 fencing。Provider 网络调用发生在数据库长事务之外；应用快照前再次核对账号配置和运行身份，避免旧运行覆盖新配置。

5 页面、权限、CSV 与 API

5.1 页面能力

  • CMDB 首页与按权限可见的统计数据。
  • 云厂商、云账号、实例、同步运行和变化详情。
  • 关键词搜索、厂商/账号/地域/状态筛选、安全排序白名单和分页。
  • Provider → Account → Region → Zone → Instance 的服务端树形拓扑。
  • Provider 标签与人工标签的独立展示和维护。
  • 权限感知的导航、按钮、链接和 403 返回路径。

5.2 Admin 所有权边界

CloudProvider 和 CloudAccount 可以在 Admin 中配置；地域、可用区、实例、Provider 标签、同步运行和变化历史是同步或审计结果，在 Admin 中只读。人工标签通过受控的 CMDB POST 表单维护，不通过可编辑 inline 混入 Provider 标签。

5.3 CSV

  • 云账号 CSV 先预览、再确认导入。
  • 非法表头、重复身份、超大文件、非法编码和敏感字段会被拒绝。
  • 可选列缺失时保留数据库原值，不把“没有提供”错误理解成“清空”。
  • 实例 CSV 导出会中和电子表格公式注入。

5.4 JSON API

v1 使用 Django JsonResponse、Session 认证和 Django 权限，不引入 DRF、GraphQL 或外部 Token 体系。账号 API 支持分页，page_size 限制为 1～100；同步错误按冲突、上游失败和业务校验分别映射为 409、502 和 422。

6 安全边界

  • 数据库只保存环境变量前缀，例如 ALIYUN_DEMO，不保存 AccessKey、Secret、Token 或明文密码。
  • 真实阿里云值只允许从对应环境变量读取，不进入数据库、日志、聊天、博客、源码或 ZIP。
  • Provider 异常对外转换为稳定错误码和脱敏消息；意外异常原文不写入同步日志。
  • 写操作使用 POST、CSRF 和权限控制；匿名请求重定向登录，无权限请求返回 403。
  • 生产设置缺少必要 Secret 或安全开关时 fail closed，不用开发默认值冒充生产配置。

7 最终验证证据

“已验证”只表示实际执行并获得结果的项目；外部条件缺失的部分单独列出，不能用 SQLite、mock 或端口可达替代真实认证。

项目实际结果边界
PythonCPython 3.10.8，64 位本地实际运行版本
Django5.2.17最终依赖版本
python-dotenv1.2.3最终依赖版本
SQLite 测试105 项全部通过确定性教学与回归路径
测试分布accounts 5；Aliyun 18；API 9；CSV 13；models 8；sync 33；views 19总计 105
随机顺序四进程完整通过，最终 seed 为 2147873966用于发现测试顺序依赖
Django 检查check 无问题；迁移无漂移；compileall 通过不替代浏览器验收
生产配置16 个 fail-closed 场景通过；安全环境下 check --deploy 通过不等于真实生产基础设施整体上线
静态文件128 个文件实际收集成功收集结果不进入源码 ZIP
浏览器主要页面、权限、只读 Admin、控制台、服务端日志和失败网络请求检查通过真实云与真实 MySQL 不在浏览器证据内
MySQL8.0.46 客户端/服务握手、127.0.0.1:3306 和 mysqlclient 导入可用没有数据库认证凭据，未执行 MySQL migration/tests；不能写成 MySQL 已通过
阿里云SDK 已安装；18 项 Adapter 合同/响应结构测试和真实 SDK 模型字段检查通过没有真实只读凭据，未执行真实阿里云账号 smoke test；不能把 mock 写成真实云验证
冷启动归档从最终 ZIP 全新解压后，105 项测试再次通过证明交付包不是只在原工作目录可用

8 源码 ZIP 与可恢复性

ZIP 文件名devopsX-CMDB资产管理-v1.0.0.zip
应用源码文件67
附加清单文件2
ZIP 条目69
精确大小78,816 字节
SHA-2562a2c9b44c4c63207ac65644947c4c40166ae8f871519ed035bb8001b62c8823c
路径结构包内直接从项目根相对路径开始，没有多余的顶层 devopsX/ 前缀
源码上篇ZIP 第 1～37 项
源码下篇ZIP 第 38～69 项

SOURCE_FILE_LIST.txt 记录有序的 69 个条目；SOURCE_SHA256SUMS.txt 校验除自身外的 68 个条目。源码汇总中的 69 个完整文件块经过 HTML 反转义后与 ZIP 原始字节逐项比较，包含 CRLF 的文件也能精确恢复。

ZIP 通过当前对话的文件交付能力直接提供，不上传第三方文件服务。本页不伪造、不猜测下载 URL。需要核对本地文件时，应同时核对文件名、78,816 字节大小和上面的 SHA-256。

9 市面产品参考与本项目取舍

本实现没有复制任何第三方项目的代码或整体架构，而是参考成熟 CMDB 和云资产产品反复出现的共同原则，再按 Django 单体教学项目的边界自行设计和验证。

参考方向吸收的概念本项目没有照搬的部分
蓝鲸 bk-cmdb模型与实例、业务拓扑、批量导入导出、审计和稳定 API 边界不实现其大型平台、动态模型引擎和微服务体系
NetBoxsource of truth、显式资源关系、标签、对象变化和过滤式 API不实现完整 DCIM/IPAM、插件生态和网络设备模型
iTop外部数据同步、稳定身份、对账、缺失/退役生命周期和数据质量不实现完整 ITSM 与通用 CI 关系引擎
CloudQuery 与 AWS ConfigProvider Adapter、完整快照、跨账号发现和资源时间线不实现大规模采集调度、数据湖或云厂商全资源覆盖
ServiceNow IRE只用于解释“识别与对账”的思想不实现企业级识别规则引擎

最终保留的共同原则是：稳定资源 ID、云厂商字段与本地字段分权、同步幂等、失败快照不能误标缺失、资产不硬删除、关系可追溯、变化可审计。v1.0.0 的目标不是功能数量最大，而是先形成一个可运行、可解释、可测试的正确闭环。

10 v1.0.0 明确不包含什么

  • 腾讯云、华为云和 AWS 的真实 Adapter。
  • 独立 VPC、SLB、RDS、Kubernetes、网络设备或机房资源模型。
  • 动态 CI 类型、自定义字段设计器、通用关系图和多租户。
  • Celery、Redis、分布式锁、定时调度和长任务 heartbeat。
  • 云实例启动、停止、重启、删除或任何写云操作。
  • SSH、跳板机、批量命令、文件分发、应用发布和自动化执行。
  • 监控、告警、工单审批和跨模块操作审计。
  • DRF、GraphQL、外部 Token API 和对象级权限。

当前同步在 Web/API 请求内同步执行，会占用 worker；快照完全保存在进程内；ORM 同步是逐行操作并带有 N+1 特征；CSV 导出使用缓冲响应；拓扑和同步详情会加载完整可见数据；SQLite 不能模拟生产数据库并发；没有分布式锁。长时间有效运行超过陈旧超时后可能被替代并重复调用 Provider，但 fencing 会阻止旧运行应用数据。这些都是明确接受的 v1 边界，不应在文档中隐藏。

11 学习与维护建议

  1. 第一次学习时从第 1 篇开始，按文章给出的执行目录、文件路径和命令逐项操作，不要直接跳到最终源码。
  2. 需要对照完整文件时使用源码上、下篇；需要快速启动时使用同版本 ZIP。
  3. 每完成一个检查点就运行对应测试并打开页面观察，不要等到第 36 章才第一次启动项目。
  4. 扩展新云厂商时实现同一 Adapter 协议，不把 SDK 调用写进视图或同步服务。
  5. 扩展新资源类型时先明确稳定身份、字段所有权、完整快照语义和变化审计，再增加模型与页面。
  6. 真实接入 MySQL 或阿里云后，要把新的真实证据与当前 SQLite/mock 证据分开记录，不覆盖原始边界。

本入口页只维护 CMDB 模块的稳定导航、版本事实、验证边界和交付校验。具体实现、逐行解释、命令、预期输出、常见错误和练习均位于四篇连续教程；每个最终文件的完整内容位于两篇源码汇总。

posted @ 2026-08-26 10:59  小家电维修  阅读(5)  评论(0)    收藏  举报