Cartography项目开发者指南：从环境搭建到模块开发

前言

Cartography是一个强大的资产关系映射工具，能够将云环境中的各类资源及其关系可视化到Neo4j图数据库中。本文将从开发环境搭建、测试方法到自定义模块开发，全面介绍Cartography项目的开发流程。

开发环境搭建

Python虚拟环境方式

基础环境准备

1. Neo4j数据库安装

   • 可以选择Docker方式或原生安装方式
   • 确保Neo4j服务正常运行，默认监听7687端口

2. Python环境配置

   • 需要Python 3.10版本
   • 推荐使用虚拟环境隔离项目依赖

3. 源码获取与安装

   • 克隆项目源码到本地目录
   • 执行可编辑安装命令，使本地修改能够即时生效

运行项目

安装完成后，可以直接从源码运行Cartography：

uv run cartography --neo4j-uri bolt://localhost:7687

此时对源码的任何修改都会在下次运行时生效。

测试环境配置

1. 测试依赖安装

   • 使用--dev参数安装开发依赖
   • --frozen参数确保使用锁定的依赖版本

2. 集成测试环境变量

   • 集成测试需要本地运行的Neo4j实例
   • 可以通过环境变量指定测试使用的Neo4j实例地址

3. 测试执行

   • 代码风格检查：make test_lint
   • 单元测试：make test_unit
   • 集成测试：make test_integration（会清空测试数据库）

开发Docker环境

Cartography提供了专门的开发Docker镜像，与生产镜像相比有以下特点：

1. 执行可编辑安装，便于开发调试
2. 包含完整的测试依赖
3. 不预设入口点，支持自定义脚本

Docker-compose开发流程

1. 构建开发镜像

   docker build -t cartography-cncf/cartography-dev -f dev.Dockerfile ./
   

2. 测试执行

   • 代码风格检查：docker-compose run --rm cartography-dev make test_lint
   • 单元测试：docker-compose run --rm cartography-dev make test_unit
   • 集成测试：docker-compose run --rm cartography-dev make test_integration

3. 自定义脚本运行

   docker-compose run --rm cartography-dev python custom_script.py
   

手动Docker命令

对于不使用docker-compose的场景，可以直接使用docker命令：

1. 启动Neo4j测试容器

   docker run --publish=7474:7474 --publish=7687:7687 --network cartography-network -v data:/data --name cartography-neo4j --env=NEO4J_AUTH=none neo4j:4.4-community
   

2. 执行集成测试

   docker run --rm --network cartography-network -e NEO4J_URL=bolt://cartography-neo4j:7687 cartography-cncf/cartography-dev make test_integration
   

自定义同步命令开发

Cartography默认会同步所有内置的intel模块，但开发者可以创建自定义同步脚本，只包含需要的模块：

from cartography import cli
from cartography import sync
from cartography.intel import aws
from cartography.intel import create_indexes

def build_custom_sync():
    s = sync.Sync()
    s.add_stages([
        ('create-indexes', create_indexes.run),
        ('aws', aws.start_aws_ingestion),
    ])
    return s

def main(argv):
    return cli.CLI(build_custom_sync(), prog='cartography').main(argv)

if __name__ == '__main__':
    import sys
    sys.exit(main(sys.argv[1:]))

这种自定义脚本既保留了Cartography CLI的全部功能，又可以根据实际需求灵活配置同步模块。

新intel模块开发指南

开发新的intel模块是扩展Cartography功能的主要方式，基本流程包括：

1. 数据收集：编写代码从目标系统获取数据
2. 数据转换：将原始数据转换为图数据库节点和关系
3. 数据加载：使用Neo4j驱动将数据写入数据库
4. 索引创建：为提高查询效率创建必要的索引

每个intel模块应该专注于单一数据源，并遵循Cartography已有的数据模型约定，确保与其他模块的数据能够正确关联。

结语

本文详细介绍了Cartography项目的开发环境配置、测试方法以及自定义开发流程。无论是使用Python虚拟环境还是Docker容器，开发者都可以快速搭建起开发环境。通过自定义同步脚本和开发新的intel模块，可以灵活扩展Cartography的功能，满足特定的资产映射需求。