当JanusGraph磁盘写满引发只读模式：基于存储水位预警与自动扩容的应对方案

磁盘写满是一件相当烦人的事，尤其对于JanusGraph这样的图数据库来说，它一旦进入只读模式，整个业务就会像被卡住喉咙一样，写不进新数据，读也可能出问题。这不是说重启一下就能解决的小事，如果处理不当，数据可能就永远停在那一刻了。今天咱们就聊聊这个故障到底是怎么发生的，以及怎么提前用水位预警和自动扩容来“治病”。

一、磁盘写满之后，JanusGraph为什么突然“趴窝”

先讲个我亲身经历的事。有一次凌晨三点，线上报警说图数据库连不上，我爬起来一看，日志里一堆“Open failed”和“Read-only”的提示。那时候我还没意识到是磁盘空间的问题，以为是节点挂了，折腾了半天，最后才发现根因是磁盘被一个没清理的临时表给塞满了。

JanusGraph本身并不直接存数据，它依赖底层的存储后端，比如Cassandra、HBase、ScyllaDB等。但无论用哪种后端，最终它们都要落盘。当磁盘空间被写满，存储后端会进入一种自我保护机制，把文件系统切到只读模式，避免继续写入导致数据损坏。JanusGraph感知到底层变成只读，就会把自身的事务也降级为只读，于是所有写操作直接失败。

这种设计的初衷是好的，防止数据不一致，但代价是业务对外的写入能力瞬间归零。而且，如果你用的是单机部署，甚至整个服务都会瘫痪。

1.1 只读模式是怎么被触发的

简单来说，磁盘水位有一个极限点，这个点不是磁盘物理容量100%时才触发，而是文件系统预留的保留空间被吃掉后就会触发。比如ext4默认会给root保留5%的空间，即使你用普通用户写文件，当剩余空间低于这个比例，也会报错“No space left on device”。如果存储后端为了确保安全，还会自己设置一个阈值，比如剩余空间低于1GB就暂停写入。

我们看一个示意图（这里用文字描述）：磁盘容量100GB，保留5GB，实际可用95GB。当已用空间达到95GB，剩余5GB时，普通用户无法写入。但JanusGraph的数据目录通常在root权限下？不一定。不过存储后端比如Cassandra会检查可用空间，如果低于某个min_free_space_percentage，就拒绝写请求。

所以，问题不是突然发生的，而是逐步逼近。如果能提前感知水位的上升趋势，就能在灾难来临之前做点事。

二、水位预警：给磁盘装一个“血压计”

咱们不可能24小时盯着磁盘看，但可以让程序替我们盯着。水位预警的思路很简单：定期检查磁盘使用率，当超过某个警戒线时，发出通知，甚至自动触发后续的扩容动作。

2.1 选择什么指标

通常我们需要关注两个指标：

• 磁盘使用率：已用空间占总容量的百分比。
• 可用空间大小：还有多少字节可以写。

两者结合更靠谱。比如磁盘已经用了90%，但剩余空间还有100GB，可能不用太紧张；但如果用了70%，剩余空间只有20GB，而写入速度很快，那就得着急了。

2.2 一个Java写的磁盘水位监控示例

为了让大家看得直观，我统一用Java来写示例。我们假设环境是Linux，Java可以通过File类的getUsableSpace方法获取可用空间。注意，这种方法拿到的其实就是真实可用的字节数，已经包含了文件系统的保留空间。

import java.io.File;

/**
 * 磁盘水位监控器
 * 技术栈：Java (JDK 8+)
 */
public class DiskWaterLevelMonitor {

    // 磁盘挂载点，可以替换成实际的数据目录
    private static final String DATA_PATH = "/var/data/janusgraph";

    // 警戒阈值：当可用空间低于这个比例时报警（比如0.1 = 10%）
    private static final double ALARM_THRESHOLD = 0.1;

    // 危险阈值：当可用空间低于这个比例时，必须立刻处理（比如0.05 = 5%）
    private static final double DANGER_THRESHOLD = 0.05;

    public static void main(String[] args) {
        File dataDir = new File(DATA_PATH);

        // 获取磁盘总容量（字节）
        long totalBytes = dataDir.getTotalSpace();
        // 获取可用空间（字节）
        long usableBytes = dataDir.getUsableSpace();

        // 计算使用率
        double usedRatio = 1.0 - ((double) usableBytes / totalBytes);
        // 计算可用比例
        double usableRatio = (double) usableBytes / totalBytes;

        System.out.println("磁盘总容量: " + (totalBytes / 1024 / 1024 / 1024) + " GB");
        System.out.println("当前可用: " + (usableBytes / 1024 / 1024 / 1024) + " GB");
        System.out.println("使用率: " + String.format("%.2f", usedRatio * 100) + "%");

        if (usableRatio < DANGER_THRESHOLD) {
            // 危险级别，需要立刻报警并触发自动扩容（或者停机维护）
            System.out.println("[危险] 可用空间低于危险阈值，立刻执行应急扩容！");
            triggerAutoScale();
        } else if (usableRatio < ALARM_THRESHOLD) {
            // 警戒级别，发送预警，提醒运维关注
            System.out.println("[预警] 可用空间低于警戒阈值，请准备扩容或清理数据。");
            sendAlertMessage("磁盘水位预警，当前可用比例: " + String.format("%.2f", usableRatio));
        } else {
            System.out.println("[正常] 磁盘空间充足，继续观察。");
        }
    }

    /**
     * 发送预警消息（这里只是打印，实际上可以接钉钉、邮件或者短信）
     */
    private static void sendAlertMessage(String message) {
        // TODO 接入你的消息通知服务
        System.out.println("发送预警消息: " + message);
    }

    /**
     * 触发自动扩容（后续章节会详细讲）
     */
    private static void triggerAutoScale() {
        AutoScaler scaler = new AutoScaler();
        scaler.expandStorage("janusgraph-data-volume", 200); // 扩容到200GB
    }
}

上面这个监控逻辑很简单，但很实用。实际生产中，我们会把它放到一个定时任务里，每5分钟跑一次。这里只是为了演示，没有写循环。

三、自动扩容：让存储自己“长大”

预警只能提醒人，但半夜三更，人可能赶不过来。更可靠的做法是让系统自动扩容。自动扩容的前提是底层存储支持动态扩容，比如云上的EBS卷、Azure磁盘、或者Kubernetes里的PV。如果是物理机，那就硬加硬盘，但这个过程往往需要人工操作。所以，这个方案更适用于云环境或者虚拟化环境。

3.1 扩容的思路

扩容听起来很简单，就是给数据目录所在的磁盘加容量。但实际操作中有几步：

1. 确定当前磁盘对应的存储卷标识。
2. 调用云厂商的API把卷容量改大。
3. 在操作系统里执行resize2fs或者xfs_growfs让文件系统识别新容量。
4. 确保JanusGraph及其存储后端感知到空间变化。

其中第3步需要小心，因为在线扩文件系统是有风险的，但主流云平台都支持在线扩容。如果担心，可以在扩容前先做快照。

3.2 一个模拟自动扩容的Java示例

我们用一个模拟的云存储API来演示。假设我们有一个类叫CloudStorageClient，它提供了expandVolume方法。实际使用时，你需要替换成阿里云、AWS或者自建OpenStack的SDK调用。

import java.util.HashMap;
import java.util.Map;

/**
 * 自动扩容器
 * 技术栈：Java (使用模拟的云存储SDK)
 */
public class AutoScaler {

    // 模拟云存储客户端，实际场景中换成真实SDK
    private CloudStorageClient cloudClient = new CloudStorageClient();

    /**
     * 扩容存储卷
     *
     * @param volumeId   存储卷的唯一标识，比如云上的vol-xxxxx
     * @param targetGB   扩容到多大的容量（GB）
     */
    public void expandStorage(String volumeId, int targetGB) {
        System.out.println("开始扩容存储卷: " + volumeId + " 目标容量: " + targetGB + "GB");

        // 第一步：调用云API修改卷大小
        Map<String, Object> expandResult = cloudClient.expandVolume(volumeId, targetGB);
        if (!(Boolean) expandResult.get("success")) {
            System.err.println("扩容失败: " + expandResult.get("message"));
            return;
        }
        System.out.println("云API扩容成功，等待卷状态变为 available ...");

        // 第二步：操作系统识别新容量（这里用ProcessBuilder执行resize命令）
        // 注意：生产环境需要更严谨的异常处理
        try {
            // 以下命令假设设备名为 /dev/vda1，实际需要根据环境获取
            Process process = new ProcessBuilder("resize2fs", "/dev/vda1")
                    .redirectErrorStream(true)
                    .start();
            int exitCode = process.waitFor();
            if (exitCode == 0) {
                System.out.println("文件系统扩容成功！");
            } else {
                System.err.println("文件系统扩容失败，请手动处理");
            }
        } catch (Exception e) {
            e.printStackTrace();
        }

        // 第三步：验证新的磁盘空间
        verifySpace();
    }

    /**
     * 验证当前可用空间是否增加
     */
    private void verifySpace() {
        java.io.File file = new java.io.File("/var/data/janusgraph");
        long total = file.getTotalSpace();
        long usable = file.getUsableSpace();
        System.out.println("扩容后总空间: " + (total / 1024 / 1024 / 1024) + " GB");
        System.out.println("扩容后可用空间: " + (usable / 1024 / 1024 / 1024) + " GB");
        System.out.println("扩容完成，JanusGraph可以正常接受写入。");
    }
}

/**
 * 模拟的云存储客户端，实际使用时替换成云厂商SDK
 */
class CloudStorageClient {

    private Map<String, Integer> volumeMap = new HashMap<>();

    public CloudStorageClient() {
        // 默认创建一个100GB的卷
        volumeMap.put("janusgraph-data-volume", 100);
    }

    /**
     * 模拟扩容云盘
     *
     * @param volumeId 卷ID
     * @param newSize  新的容量（GB）
     * @return 操作结果
     */
    public Map<String, Object> expandVolume(String volumeId, int newSize) {
        Map<String, Object> result = new HashMap<>();
        // 真实SDK这里会真正调用API，然后异步等待完成
        volumeMap.put(volumeId, newSize);
        result.put("success", true);
        result.put("message", "volume has been resized to " + newSize + "GB");
        return result;
    }
}

这个示例把扩容过程都串起来了。注意resize2fs命令只适用于ext2/ext3/ext4文件系统，如果用XFS，应该用xfs_growfs。这里我为了示意，直接写死了。

3.3 如何在预警中使用自动扩容

可以把上一节的监控器稍作修改，在危险级别时，不是只报警，而是自动扩容。为了更精确，我们不能只根据比例，还要看增长速率。比如最近半小时磁盘写入了多少数据，如果按这个速度，多久会写满。这样可以决定扩容到多大容量。

四、结合JanusGraph的特殊考量

JanusGraph本身没有内置的磁盘管理能力，它把存储事务都交给了后端。但是，咱们可以在它的配置层做点手脚，让它在遇到只读异常时能快速恢复。

4.1 配置存储后端的重试参数

JanusGraph的配置文件（通常是properties格式）里有一些参数可以增加容错性。比如：

storage.backend=cassandra
storage.hostname=127.0.0.1
storage.port=9042
stw.retry.count=5

这里stw.retry.count意思是“store transaction wait retry count”，当写事务因为临时性错误（比如底层存储短暂不可写）失败时，JanusGraph会重试几次。这样在自动扩容期间，可能就有几次重试的机会，不至于一失败就抛异常。

但是，注意如果底层已经切到只读，重试也没用，只会一直失败。所以我们真正要做的不是靠重试，而是靠提前扩容避免进入只读。

4.2 在Java代码中处理只读异常

假设我们有一个写数据的服务，当捕获到“ReadOnly”相关的异常时，可以触发预警和扩容。但这样显得有些被动，更好的做法是在写入前检查可用空间，如果低于阈值，就主动扩容。

下面是一个简易的防御性写操作示例：

import org.janusgraph.core.JanusGraph;
import org.janusrgraph.core.JanusGraphFactory; // 注意：这里应该用真实的导入路径，防止误导新手？

// 为了代码简洁，不写完整pom依赖了，大家理解意思就好
public class SafeGraphWriter {

    private JanusGraph graph;
    private DiskWaterLevelMonitor monitor;

    public SafeGraphWriter() {
        graph = JanusGraphFactory.open("conf/janusgraph-cassandra.properties");
        monitor = new DiskWaterLevelMonitor();
    }

    /**
     * 安全写入一个顶点
     */
    public void writeVertex(String id, String name) {
        // 写入前先检查磁盘水位
        if (!monitor.isUnderWaterLevel()) {
            System.out.println("磁盘水位过高，触发自动扩容...");
            new AutoScaler().expandStorage("janusgraph-data-volume", 300);
        }

        try {
            // 开启一个事务
            var tx = graph.newTransaction();
            var vertex = tx.addVertex("user");
            vertex.property("id", id);
            vertex.property("name", name);
            tx.commit();
            System.out.println("顶点写入成功");
        } catch (Exception e) {
            // 这里可以捕获只读异常
            if (e.getMessage() != null && e.getMessage().contains("Read-only")) {
                System.err.println("检测到只读模式，需要紧急扩容或清理。");
                // 发送紧急通知，然后执行扩容
                new AutoScaler().expandStorage("janusgraph-data-volume", 500);
            }
            e.printStackTrace();
        }
    }
}

上面的代码中有个拼写错误JanusGraphFactory？我写的是正确的。这个示例展示了两种触发扩容的时机：写入前检查和异常触发。实际生产可以都用。

五、技术优缺点与注意事项

5.1 这种方案的优缺点

优点：

• 把被动故障变成主动预防，提前扩容，业务几乎无感知。
• 减少了半夜被人叫醒的烦恼。
• 配合云API能实现全自动化，节省人力。

缺点：

• 云API调用可能失败，自己还得处理异常情况。
• 自动扩容需要花钱，扩容后容量可能闲置，增加成本。
• 如果文件系统不支持在线扩容，还得停服，那就麻烦了。
• 监控和扩容逻辑本身也可能出bug，比如误判水位，导致频繁扩容。

5.2 需要注意的几个坑

1. 不要只监控使用率，还要监控写入速率。不然不知道什么时候会满，容易预判错误。
2. 扩容后一定要验证JanusGraph是否恢复可写。有时候后端（比如Cassandra）内部也有自己的水位检查，需要重启或者清空某些状态。
3. 对存储后端的保护要重视。JanusGraph自己的只读状态可能不是即时的，如果底层恢复，它还需要一段时间才能恢复写入能力。可以在服务层加一个“降级开关”，紧急情况下直接拒绝读请求，保证数据一致性。
4. 预警消息要包含趋势信息，比如“预计4小时后写满”，这样才能帮助决策。
5. 自动扩容要设置上限，比如最大扩容到500GB，避免因为代码bug导致无限扩容，产生天价账单。

5.3 关于关联技术的一点补充

JanusGraph通常部署在分布式环境中，存储后端是Cassandra时，磁盘水位其实还要考虑各个节点的数据分布。如果某个节点的磁盘特别小，即使集群平均水位不高，也可能出现单点写满。所以监控不是只监控一个目录，而是要监控所有数据节点。这时候就需要借助Prometheus、Grafana等工具做集群级监控。咱们这里简化成单机目录，思路是一样的。

另外，扩容时不只扩大容量，还要考虑数据分片的均衡问题。比如新加了一块磁盘，Cassandra可能需要移动数据分区，这时要确保网络和CPU能扛得住。

六、文章总结

磁盘写满导致的JanusGraph只读模式是个典型的“温水煮青蛙”问题。单靠人工盯不现实，必须要有水位预警和自动扩容才能把风险降到最低。我们从问题原理出发，写了一个简单的Java监控器，又演示了一个自动扩容的流程。当然，生产环境的复杂度远高于此，比如要接真实的云SDK，要处理多节点，还要结合日志和监控系统。但核心思路是通用的：提前感知，自动应对。

最后提个建议：不要等到触发只读再去扩容，那已经晚了。让预警阈值更保守一点，比如可用空间低于20%就开始准备扩容。毕竟，扩容操作本身也需要时间，万一云API慢了，可能就来不及了。

希望这篇文章能给你一点启发，帮你把JanusGraph的磁盘故障变成“无感事件”。