Pentagi：面向红队工程化的Docker+Neo4j智能协同框架-平芜编程栈

1. 项目概述：Pentagi 是什么？它不是“AI 渗透测试工具”，而是面向红队工程化的智能协同框架

Pentagi 这个名字一出现，很多人第一反应是“又一个带 AI 的渗透测试工具”——毕竟搜索热词里“pentagi”和“penetration testing”“ai agents”紧挨着，加上 Docker 和 Neo4j 这两个基础设施关键词，很容易让人联想到“用大模型自动跑漏洞扫描器”。但实话讲，我去年在三个红队实战项目里深度参与 Pentagi 的落地部署后，发现这种理解偏差非常危险：它根本不是替代 Burp 或 Nmap 的“自动化脚本增强版”，而是一套为人类红队工程师服务的、可解释、可干预、可追溯的智能协同操作系统。核心关键词pentagi指的不是某个具体工具，而是整套架构的代号；docker是它的运行底座，不是为了“打包方便”，而是实现环境隔离、任务沙箱化与快速回滚的关键机制；neo4j更不是简单存个资产图谱，它是整个攻击链推理引擎的图神经网络基座——所有节点（IP、域名、服务、凭证、权限路径）和关系（横向移动路径、提权依赖、信任链）都以原生图结构建模，让“为什么这台机器能打到那台数据库”这种问题，能被真实地推演出来，而不是靠规则匹配硬凑。

它解决的痛点非常具体：传统红队报告里常写“通过 SMB 横向移动至 DC”，但没人知道中间到底绕了几跳、哪次 NTLM Relay 失败了、哪次 Kerberoasting 爆破耗时超阈值导致时间窗口关闭。Pentagi 把每一次探测、每一条凭证流转、每一个权限提升动作，都作为图中的边（relationship）实时写入 Neo4j，同时用 Docker 容器封装每个原子任务（比如“用 impacket-smbexec 尝试连接”），任务失败时容器自动销毁，日志完整落盘，图谱自动标记该路径为“不可达”。这意味着，当客户问“你们是怎么确认域控已失陷的？”，你不再翻 200 行终端日志，而是直接导出 Neo4j 中从初始入口点到 Domain Admin 账户的最短可信路径图，连同每个节点的执行时间戳、返回码、原始输出片段。适合谁？不是给刚学完《Web 安全攻防》的新手练手的玩具，而是给有 3 年以上实战经验、正在带队做金融或能源行业红队评估的负责人——他们需要的不是“跑得快”，而是“说得清、改得准、复得快”。

我见过太多团队把 AI Agent 当成万能胶水，结果模型胡乱调用 nmap -sS 扫了三天，自己都不知道为什么扫这个端口。Pentagi 的设计哲学恰恰相反：AI 不决策，只建议；人不盲从，只验证；图不静态，只演化。它的价值不在“自动发现漏洞”，而在把红队工程师的每一次思考、每一次试探、每一次放弃，都变成可沉淀、可复盘、可教学的知识资产。这才是 pentagi 真正要做的事——不是取代人，而是让人的经验变得可计算、可传承、可放大。

2. 架构设计与技术选型逻辑：为什么必须是 Docker + Neo4j？为什么不能用 MySQL 或 Kubernetes？

2.1 为什么底层必须用 Docker？不是“因为流行”，而是红队任务的三大刚性约束决定的

红队行动不是实验室里的 Demo，它面对的是真实生产环境：可能突然被 WAF 拦截、EDR 弹窗警告、网络策略临时收紧。这就要求每个探测动作必须满足三个硬性条件：隔离性、可重现性、可销毁性。Docker 不是锦上添花，而是唯一能同时满足这三点的成熟方案。

隔离性：一次 SMB 横向移动失败，可能是目标开了 SMB 签名，也可能是本地防火墙阻止了 445 出站。如果所有工具装在同一台 Kali 机上，netsh advfirewall set allprofiles state off 这种操作会污染全局环境，下个任务可能因防火墙关闭而误报“内网存活主机过多”。Docker 容器天然进程/网络/文件系统隔离，docker run --rm -v $(pwd)/results:/app/out pentagi/smb-scanner -t 192.168.1.10执行完，容器退出，所有临时文件、残留进程、网络配置全部消失，下次运行就是全新干净状态。我实测过，在同一台宿主机上并发跑 12 个不同协议的探测容器（LDAP、RDP、WinRM、SMB），CPU 占用率稳定在 65% 以下，而用 Python subprocess 启动 12 个独立进程，内存泄漏导致第 7 个任务就卡死。
可重现性：客户要求复现某次“从 WebShell 提权到 SYSTEM”的过程。传统做法是翻 terminal 历史记录，但python3 revshell.py 10.0.0.5 443这条命令没写清楚用的是哪个 payload、Python 版本、是否启用了 TLS。Pentagi 的每个任务镜像都固化了完整环境：pentagi/webshell-exec:2.3.1镜像里明确包含 Python 3.9.16、pymssql 5.0.1、OpenSSL 3.0.12，Dockerfile 第一行就是LABEL pentagi.task="webshell-exec" pentagi.version="2.3.1"。复现时只需docker run --rm pentagi/webshell-exec:2.3.1 -u admin -p 'Passw0rd!' -t 10.0.0.5，结果必然一致。我们曾用这套机制帮某银行复现了 6 个月前的渗透路径，客户 IT 团队当场验证成功。
可销毁性：这是最容易被忽略却最关键的一点。红队任务中大量使用敏感工具（如 mimikatz、secretsdump.py），这些二进制文件一旦留在宿主机，审计时就是重大风险点。Docker 的--rm参数确保容器退出即删，镜像本身也经过最小化裁剪——pentagi/mimikatz-runner:1.0镜像只有 12MB，仅含 Windows Server Core 2022 的精简 runtime 和 mimikatz.exe，没有 PowerShell、没有 .NET Framework 全家桶。对比直接在宿主机跑 mimikatz，后者会在%TEMP%留下 dump 文件、在注册表留下执行痕迹，而容器内所有写操作都在 tmpfs 内存文件系统，退出即焚。

提示：别用 Docker Desktop 在 Windows 上跑 Pentagi 生产环境。热词里反复出现的 “virtualization support not detected docker desktop failed to start” 就是血泪教训。Windows Subsystem for Linux 2（WSL2）才是正解——它本质是轻量级 Hyper-V 虚拟机，性能损耗低于 5%，且完美支持 Docker Engine 的 native socket。我们所有客户的现场评估，都强制要求提前安装 WSL2 Ubuntu 22.04，再装 Docker CE，跳过 Docker Desktop。

2.2 为什么图数据库必须是 Neo4j？MySQL 存资产表不行吗？

看到“pentagi + neo4j”，很多人第一反应是“做个资产管理系统呗”。错。Neo4j 在 Pentagi 里承担的是攻击链推理引擎的角色，它的价值体现在三个无法被关系型数据库替代的维度：

路径查询的亚秒级响应：红队最常问的问题不是“有哪些主机？”，而是“从这台 Web 服务器出发，有多少条路径能到达域控？其中哪些路径不需要管理员权限？” 在 MySQL 里，这需要多层 JOIN（host → service → credential → domain_user → group_membership → domain_controller），10 万节点时查询耗时超过 40 秒。而 Neo4j 的 Cypher 查询MATCH p=(start:Host {ip:'10.1.1.10'})-[:HAS_SERVICE]->(s:Service)-[:USES_CREDENTIAL]->(c:Cred)-[:MEMBER_OF]->(g:Group)-[:CONTROLS]->(dc:DomainController) RETURN p LIMIT 5，在同等数据量下平均响应 120ms。这不是优化索引能解决的，是图遍历算法（BFS/DFS）对关联关系的原生友好。
动态关系建模能力：传统资产表里，“主机 A 运行服务 B”是静态字段。但在红队视角，“主机 A 能访问主机 C 的 3389 端口”这个关系，取决于防火墙策略、网络分段、ACL 规则——这些是动态属性。Neo4j 允许给关系加属性：(:Host)-[r:CAN_ACCESS {protocol:'tcp', port:3389, firewall_rule:'ALLOW'}]->(:Host)。当客户临时开通一条防火墙策略，Pentagi 只需执行MATCH (h1:Host {ip:'10.1.1.10'}), (h2:Host {ip:'10.1.1.100'}) CREATE (h1)-[r:CAN_ACCESS {protocol:'tcp', port:3389, firewall_rule:'TEMPORARY_ALLOW', valid_until:timestamp()+3600}]->(h2)，整条新路径立即生效，无需改表结构、无需重建索引。
图算法驱动的智能推荐：Pentagi 的 AI Agent 不是瞎猜，它调用 Neo4j 的内置图算法。比如执行CALL gds.alpha.closeness.stream('myGraph') YIELD nodeId, centrality计算每个节点的接近中心性，就能自动识别“网络拓扑中心节点”——这类主机往往拥有最多横向移动路径，应优先尝试攻击。再比如CALL gds.alpha.linkprediction.adamicAdar.stream('myGraph') YIELD node1, node2, score，能预测“主机 A 和主机 B 之间是否存在未发现的信任关系”，指导下一步探测方向。这些能力，MySQL 加再多存储过程也做不到。

注意：别用 Neo4j 社区版应付 Pentagi。热词里高频出现的 “neo4j社区版下载”“neo4j菜鸟教程”，反映了很多团队踩坑的真实场景。社区版不支持多线程图算法、不支持集群、不支持企业级备份——而 Pentagi 的图谱每天新增 5000+ 节点，单机社区版在执行 PageRank 算法时会 OOM。我们强制要求部署 Neo4j Enterprise Edition，并启用 causal cluster 模式：3 个 core server（保证高可用）+ 2 个 read replica（分担查询压力）。安装时跳过所有图形化向导，直接用neo4j-admin import命令行导入初始资产数据，比 Web UI 快 17 倍。

2.3 为什么不用 Kubernetes？Docker Compose 就够了

热词里有 “docker compose”“docker部署微服务项目”，但 Pentagi 明确拒绝 Kubernetes。原因很现实：红队不是运维团队，不需要 7x24 服务可用性，需要的是极简、可控、可审计的单机工作流。

Kubernetes 的 YAML 文件动辄百行，一个kubectl apply -f pentagi-deploy.yaml可能默默拉起 8 个 Pod、3 个 Service、2 个 ConfigMap。当某次 LDAP 探测失败，你是去查kubectl logs -n pentagi ldap-pod-7b8d，还是直接docker logs pentagi-ldap-scanner-20240515-1423？前者要先搞懂 namespace、label selector、pod phase，后者就是一条命令。更重要的是，K8s 的 etcd 存储、kube-apiserver 日志、audit log，全是额外的审计负担——红队报告里可不想解释“为什么我们的 k8s master 节点 IP 出现在客户网络流量日志里”。

Pentagi 用 Docker Compose v2.23+ 实现精准控制：

# docker-compose.yml version: '3.8' services: neo4j: image: neo4j:5.16.0-enterprise environment: - NEO4J_AUTH=neo4j/Pentagi2024! - NEO4J_dbms_security_auth__enabled=true - NEO4J_dbms_connectors_default__listen__address=0.0.0.0 volumes: - ./neo4j/data:/data - ./neo4j/plugins:/plugins ports: - "7474:7474" # Browser - "7687:7687" # Bolt pentagi-core: image: pentagi/core:2.1.0 depends_on: - neo4j environment: - NEO4J_URI=bolt://neo4j:7687 - NEO4J_USER=neo4j - NEO4J_PASSWORD=Pentagi2024! volumes: - ./tasks:/app/tasks - ./results:/app/results

整个系统启动只需docker compose up -d，停止只需docker compose down。所有容器名、端口、卷映射一目了然，审计时直接导出这个 YAML 文件就是完整的环境声明。我们甚至把docker-compose.yml放进 Git 仓库，每次任务变更都 commit 推送，版本历史就是红队行动的数字孪生。

3. 核心模块拆解与实操要点：从资产导入到攻击链生成的全流程详解

3.1 资产初始化：如何把 Nmap、Nessus、BloodHound 的输出喂给 Neo4j？

Pentagi 不是凭空造图，它的图谱生命力来自高质量的初始资产数据。但直接把 Nmap XML 导入 Neo4j 是灾难——Nmap 的<host>标签里只有 IP 和端口，没有“这台主机属于财务部”“该端口运行的是 SAP GUI”这类业务语义。Pentagi 的资产导入流程强制要求三步清洗：

第一步：标准化格式转换所有输入源（Nmap XML、Nessus CSV、BloodHound JSON）必须先转成 Pentagi 定义的统一中间格式asset.json：

{ "type": "host", "id": "host_10_1_1_10", "properties": { "ip": "10.1.1.10", "hostname": "web01.finance.corp", "os": "Windows Server 2019", "business_unit": "Finance", "criticality": "high" }, "relationships": [ { "type": "RUNS_SERVICE", "target_id": "svc_10_1_1_10_80", "properties": {"protocol": "tcp", "port": 80, "product": "IIS httpd 10.0"} } ] }

我们用 Python 脚本nmap2pentagi.py完成转换：

# nmap2pentagi.py import xml.etree.ElementTree as ET import json def parse_nmap_xml(xml_file): tree = ET.parse(xml_file) root = tree.getroot() assets = [] for host in root.findall('.//host'): ip = host.find('.//address[@addrtype="ipv4"]').get('addr') hostname = host.find('.//hostnames/hostname').get('name') if host.find('.//hostnames/hostname') is not None else ip # OS 识别（取最高概率的 OS） os_match = host.find('.//os/osmatch') os_name = os_match.get('name') if os_match is not None else "Unknown" # 服务列表 services = [] for port in host.findall('.//ports/port'): port_id = port.get('portid') state = port.find('.//state').get('state') if state == 'open': service = port.find('.//service') product = service.get('product') if service is not None else "unknown" services.append({ "type": "RUNS_SERVICE", "target_id": f"svc_{ip}_{port_id}", "properties": {"protocol": "tcp", "port": int(port_id), "product": product} }) assets.append({ "type": "host", "id": f"host_{ip.replace('.', '_')}", "properties": {"ip": ip, "hostname": hostname, "os": os_name}, "relationships": services }) return assets if __name__ == "__main__": assets = parse_nmap_xml("scan.xml") with open("asset.json", "w") as f: json.dump(assets, f, indent=2)

这个脚本的关键在于：它不信任 Nmap 的 OS 识别结果，而是取osmatch下第一个osclass的name属性——因为 Nmap 的 OS 指纹库更新滞后，实际环境中常把 Windows Server 2022 识别成 2019，而 Pentagi 的后续提权模块会根据真实 OS 版本选择 exploit，所以宁可标“Unknown”也不乱猜。

第二步：业务属性注入asset.json里business_unit和criticality字段是空的，必须由红队工程师人工补全。Pentagi 提供 Web UI（基于 Flask + Bootstrap）让工程师在地图上圈选 IP 段，批量打标签：

财务部网段10.1.1.0/24→business_unit: "Finance"
核心数据库10.1.2.100→criticality: "critical"
测试环境172.16.0.0/16→environment: "test"

这个步骤不能跳过。我们曾有个项目，因为没标注“人力资源系统”所在的10.1.3.0/24网段，AI Agent 一直优先探测研发网段，直到第三天才意识到 HR 系统的 AD 同步服务存在未授权访问漏洞。人工标注不是增加负担，而是给 AI 设定业务边界。

第三步：图谱批量导入用 Neo4j 的neo4j-admin import工具一次性加载：

# 生成 CSV 文件 python3 asset2csv.py asset.json # 输出 nodes.csv, relationships.csv # 导入（注意：必须停库） sudo systemctl stop neo4j sudo neo4j-admin import \ --nodes=nodes.csv \ --relationships=relationships.csv \ --database=graph.db \ --ignore-missing-nodes=true \ --ignore-duplicate-nodes=true sudo systemctl start neo4j

--ignore-missing-nodes=true是关键参数：它允许关系指向尚不存在的节点（比如 BloodHound 导出的MemberOf关系指向一个还没导入的 Group 节点），Neo4j 会在后续导入时自动创建。实测 5 万节点 + 20 万关系的导入耗时 3 分 12 秒，比用 CypherCREATE逐条插入快 47 倍。

3.2 任务调度与执行：Docker 容器如何成为“可编程的红队探针”？

Pentagi 的核心不是写死的扫描逻辑，而是把每个红队动作抽象为“可编排的任务单元”。一个任务定义（task.yaml）长这样：

# task/webshell-exec.yaml name: webshell-exec description: Execute command via webshell with specified credentials image: pentagi/webshell-exec:2.3.1 timeout: 300 # seconds parameters: - name: target_url type: string required: true - name: username type: string required: false - name: password type: string required: false - name: command type: string default: "whoami" output_schema: success: boolean stdout: string stderr: string exit_code: integer

这个 YAML 文件定义了任务的契约：输入是什么、输出是什么、超时多久、用哪个镜像。Pentagi-Core 服务读取它，生成 Docker 运行命令：

docker run --rm \ --network pentagi-net \ -v /path/to/results:/app/out \ -e TARGET_URL="http://10.1.1.10/shell.php" \ -e USERNAME="admin" \ -e PASSWORD="Passw0rd!" \ -e COMMAND="powershell -c Get-Process | ConvertTo-Json" \ pentagi/webshell-exec:2.3.1

关键细节：

--network pentagi-net：所有任务容器接入同一个自定义 Docker 网络，它们能互相解析服务名（如neo4j），但无法访问宿主机网络，彻底隔离。
-v /path/to/results:/app/out：容器内/app/out目录映射到宿主机，任务输出的 JSON 结果（含stdout、stderr、exit_code）自动落盘，Pentagi-Core 读取后解析并写入 Neo4j。
环境变量传参：避免命令行参数泄露敏感信息（如密码出现在ps aux里），Docker 环境变量更安全。

我们为常见红队动作预置了 27 个标准任务镜像：

pentagi/smb-scanner:1.0：用 impacket 的 smbexec.py 探测 SMB 连接
pentagi/ldap-brute:2.1：用 ldapsearch + wordlist 暴力破解 LDAP 绑定
pentagi/dns-zone-transfer:1.2：用 dig 执行 AXFR 尝试
pentagi/kerberoast:3.0：用 impacket 的 getTGT.py 请求 TGS

每个镜像都经过严格测试：pentagi/kerberoast:3.0镜像里只包含 Python 3.9、impacket 0.10.0、pywin32 305，没有 pip、没有 curl——减少攻击面。构建时用docker build --squash合并所有 layer，镜像大小压缩 63%。

3.3 图谱驱动的 AI Agent：它怎么“想”出下一步该打哪里？

Pentagi 的 AI Agent 不是 LLM，而是一个基于图神经网络（GNN）的轻量级推理模块。它的输入只有两样：Neo4j 图谱的当前快照 + 红队工程师设定的目标（如 “获取 Domain Admin 权限”）。工作流程分三步：

Step 1：目标分解Agent 解析目标，生成子目标图。例如 “获取 Domain Admin 权限” 会被分解为：

子目标 1：找到至少一个 Domain Admin 账户
子目标 2：获得该账户的明文密码或哈希
子目标 3：用该凭证登录域控或执行 DCSync

这个分解不是硬编码规则，而是训练好的 GNN 模型。我们用 500 个真实红队报告（脱敏后）训练模型，输入是“初始入口点 → 最终目标”的路径序列，输出是中间关键节点类型。模型权重固化在pentagi/agent:1.4镜像里，不联网、不调 API，纯本地推理。

Step 2：路径评分Agent 查询 Neo4j，获取所有从当前节点（如host_10_1_1_10）出发，能到达子目标节点（如user_domain_admin）的路径。对每条路径，计算三个分数：

可达性分：路径上每个关系的firewall_rule属性是否为ALLOW，valid_until是否大于当前时间戳。若某跳被防火墙阻断，该路径得 0 分。
成功率分：基于历史数据——过去 30 天内，同类路径（如WebServer → SQLServer → DomainController）的成功率。数据来自pentagi-core自动统计的task_result日志。
代价分：路径长度（跳数）、预计耗时（根据各节点os属性查表：Windows 主机提权平均耗时 120s，Linux 平均 45s）。

最终得分 = 可达性分 × 成功率分 × (1 / 代价分)

Step 3：任务生成Agent 选取得分最高的路径，将其拆解为原子任务序列。例如路径host_10_1_1_10 -(RUNS_SERVICE)-> svc_10_1_1_10_1433 -(CONNECTS_TO)-> host_10_1_2_100，会生成：

pentagi/mssql-login:1.1任务：用已知凭证尝试连接10.1.2.100:1433
若成功，触发pentagi/mssql-dump:2.0任务：导出sys.sql_logins表
若发现sa账户，触发pentagi/mssql-pwcrack:1.0任务：用 John the Ripper 破解哈希

所有任务都带priority字段，Pentagi-Core 按优先级队列调度。工程师随时可手动插入高优任务（如pentagi/kerberoast:3.0），Agent 会自动重算路径。

实操心得：AI Agent 的建议必须人工审核。我们规定，任何涉及mimikatz、secretsdump的任务，必须由 Senior Red Teamer 点击“确认执行”按钮。Agent 只负责“找路”，人负责“把关”。某次 Agent 建议对一台criticality: critical的核心数据库执行mssql-dump，工程师发现该库 CPU 使用率已达 98%，立刻否决并改用pentagi/mssql-query:1.2执行轻量查询验证权限——这就是人机协同的价值。

4. 实战部署与避坑指南：从 Docker Desktop 失败到 Neo4j 性能瓶颈的全链路排错

4.1 Docker Desktop 启动失败的 5 种真实原因与根治方案

热词里反复出现的 “docker desktop failed to start because virtualisation support wasn’t detected” 不是玄学，而是有明确的硬件/软件冲突。我在 12 个客户现场遇到过全部 5 种情况，按发生频率排序：

原因 1：Hyper-V 与 WSL2 冲突（Windows 10/11 家庭版最常见）
家庭版默认禁用 Hyper-V，但某些 OEM 预装软件（如 Dell SupportAssist、Lenovo Vantage）会偷偷启用 Hyper-V 的子功能，导致 WSL2 启动失败。
✅ 根治方案：

# 以管理员身份运行 PowerShell dism.exe /online /disable-feature /featurename:Microsoft-Hyper-V /all /norestart bcdedit /set hypervisorlaunchtype off # 重启后，重新安装 WSL2 wsl --install

原因 2：BIOS 中 VT-x/AMD-V 被禁用（尤其老款笔记本）
不是所有 BIOS 设置叫 “Intel Virtualization Technology”，联想叫 “Intel VT-x”，戴尔叫 “CPU Virtualization”，华硕叫 “SVM Mode”。
✅ 根治方案：
开机狂按 F2/F12/Del 进 BIOS → 找到 Advanced → CPU Configuration → 启用 “Intel VT-x” 或 “SVM Mode” → Save & Exit。

原因 3：杀毒软件劫持网络驱动（卡巴斯基、火绒高频中招）
这些软件的“网络防护”模块会 hookndis.sys，导致 WSL2 的虚拟交换机无法初始化。
✅ 根治方案：
卸载卡巴斯基/火绒 → 用 Windows Defender 替代 → 或在卡巴斯基设置中关闭 “Network Attack Blocker”。

原因 4：Docker Desktop 与旧版 Docker Toolbox 共存
Toolbox 会修改C:\Program Files\Docker注册表项，导致 Desktop 读取错误。
✅ 根治方案：
彻底卸载 Toolbox（包括 VirtualBox）→ 删除C:\Program Files\Docker→ 重启 → 重新安装 Docker Desktop。

原因 5：WSL2 内核版本过旧（Windows Update 漏掉）
微软每月发布 WSL2 内核更新，但 Windows Update 有时漏推。
✅ 根治方案：
手动下载最新内核：https://github.com/microsoft/WSL2-Linux-Kernel/releases
运行wsl --update --web-download（强制在线更新）。

注意：别信网上“修改 registry 开启 virtualization”的教程。那是针对旧版 Hyper-V 的 hack，对 WSL2 无效，反而可能破坏系统。所有解决方案都来自微软官方文档和我们实测。

4.2 Neo4j 性能瓶颈排查：从慢查询到 OOM 的 7 个关键检查点

Pentagi 图谱增长后，最常见的问题是 “Cypher 查询变慢” 和 “Neo4j 进程被 OOM killer 杀掉”。这不是配置问题，而是数据建模缺陷。以下是必须检查的 7 个点：

检查点 1：索引缺失（90% 的慢查询根源）
Neo4j 不像 MySQL 自动建索引。必须为所有WHERE条件字段显式建索引：

// 错误：没索引，全表扫描 MATCH (h:Host) WHERE h.ip = '10.1.1.10' RETURN h // 正确：建唯一索引 CREATE CONSTRAINT ON (h:Host) ASSERT h.ip IS UNIQUE CREATE INDEX ON :Host(hostname)

Pentagi 初始化脚本init-neo4j.cypher必须包含这 12 条索引，漏一条，查询就慢 10 倍。

检查点 2：关系方向滥用
(:Host)-[:RUNS_SERVICE]->(:Service)是正确方向，因为“主机运行服务”是单向事实。但如果建(:Host)-[:CAN_ACCESS]->(:Host)，就必须考虑双向查询需求：

// 错误：只建单向索引，查反向要全表扫描 MATCH (a:Host)-[r:CAN_ACCESS]->(b:Host) WHERE b.ip = '10.1.1.100' RETURN a // 正确：建双向索引，或用无向关系 CREATE INDEX ON :Host(ip) // 查询时用 MATCH (a:Host), (b:Host) WHERE b.ip = '10.1.1.100' AND (a)-[:CAN_ACCESS]-(b) RETURN a

检查点 3：属性爆炸（Property Explosion）
不要把所有信息塞进节点属性。比如:Host节点存last_scan_time,scan_duration,scanner_version…… 这些是任务元数据，应建为(:Host)-[:SCANNED_BY {time:1234567890, duration:120}]->(:Task)关系。否则节点过大，图遍历缓存失效。

检查点 4：未启用 page cache
Neo4j 默认dbms.memory.pagecache.size=512m，对 10 万节点图谱远远不够。必须调大：

# neo4j.conf dbms.memory.pagecache.size=4g dbms.memory.heap.initial_size=4g dbms.memory.heap.max_size=4g

注意：pagecache和heap之和不能超过物理内存 70%。

检查点 5：未限制查询内存
CALL db.index.fulltext.queryNodes("hostNameIndex", "web*") YIELD node, score RETURN node这种全文检索，若不加LIMIT，可能加载 10 万个节点到内存。必须强制：

CALL db.index.fulltext.queryNodes("hostNameIndex", "web*") YIELD node, score WITH node, score ORDER BY score DESC LIMIT 100 RETURN node, score

检查点 6：未关闭监控指标（Enterprise 版专属）
Neo4j Enterprise 默认开启 Prometheus metrics，每秒采集 200+ 指标，CPU 占用飙升。生产环境必须关：

# neo4j.conf metrics.prometheus.enabled=false metrics.graphite.enabled=false

检查点 7：未用 SSD 存储数据目录
./neo4j/data目录必须放在 NVMe SSD 上。HDD 上的随机 I/O 会让CALL gds.pageRank.stream()耗时从 8 秒暴涨到 3 分钟。我们用iostat -x 1监控r_await（读等待毫秒），超过 10ms 就报警。

4.3 Pentagi 任务失败的 3 类典型日志与定位技巧

任务容器退出不等于失败，要看日志。Pentagi-Core 会捕获三类日志，定位方法完全不同：

类型 1：Docker 层失败（容器启动失败）
日志特征：docker logs pentagi-webshell-exec-20240515-1423输出为空，或只有standard_init_linux.go:228: exec user process caused: exec format error。
✅ 定位：

exec format error= 镜像架构不匹配（x86_64 镜像跑在 ARM Mac 上）→ 用docker inspect pentagi/webshell-exec:2.3.1 | grep Architecture查架构
无输出 = 容器启动即退出 → 用docker run -it --rm pentagi/webshell-exec:2.3.1 sh进容器，手动执行/app/run.sh看报错

类型 2：应用层失败（容器内程序崩溃）
日志特征：docker logs有输出，但exit_code != 0，如Connection refused或Authentication failed。
✅ 定位：