Android端运行Netty gRPC服务器报channel not registered to an event loop错误

异常触发原因 #

• 传输层依赖冲突：项目同时引入了grpc-netty-shaded（Netty服务端/客户端通用传输实现）和grpc-okhttp（仅适用于gRPC客户端的传输实现），两类传输依赖初始化时会抢占Netty通道、事件循环的选型逻辑，导致通道注册失败。
• Android平台适配问题：Netty默认的初始化逻辑没有针对Android平台做适配，部分Android系统的Java NIO Selector实现存在兼容性缺陷，不显式指定事件循环组和通道类型时，默认逻辑无法完成通道到事件循环的绑定。
• 初始化逻辑缺失：原有初始化代码没有显式声明Netty服务端的Boss、Worker事件循环组，也没有指定服务端通道类型，默认逻辑在Android环境下会出现链路断裂，抛出注册失败异常。

解决方案 #

1. 清理冗余依赖 #

移除仅用于客户端的grpc-okhttp依赖，调整后的依赖配置如下：

implementation 'io.grpc:grpc-kotlin-stub:1.2.0'
implementation 'io.grpc:grpc-netty-shaded:1.40.1'
implementation 'io.grpc:grpc-stub:1.40.1'
implementation 'io.grpc:grpc-protobuf-lite:1.40.1'
implementation 'com.google.protobuf:protobuf-kotlin-lite:3.18.1'

2. 适配Android平台调整初始化逻辑 #

显式指定Netty服务端的事件循环组与通道类型，修改后的初始化代码如下：

// 分别创建Boss（处理连接请求）、Worker（处理业务读写）事件循环组，线程数可按需调整
val bossGroup = NioEventLoopGroup(1)
val workerGroup = NioEventLoopGroup()
try {
    val grpcServer = NettyServerBuilder.forPort(7001)
        .bossEventLoopGroup(bossGroup)
        .workerEventLoopGroup(workerGroup)
        // 显式指定服务端使用NIO通道类型
        .channelType(NioServerSocketChannel::class.java)
        .addService(Service())
        .build()
        .start()
    // 注册进程销毁钩子，退出时优雅关闭服务释放资源
    Runtime.getRuntime().addShutdownHook(Thread {
        grpcServer.shutdown()
        bossGroup.shutdownGracefully()
        workerGroup.shutdownGracefully()
    })
    // 阻塞当前线程避免服务直接退出，按需调整等待逻辑
    grpcServer.awaitTermination()
} catch (e: Exception) {
    // 异常场景下释放资源
    bossGroup.shutdownGracefully()
    workerGroup.shutdownGracefully()
    e.printStackTrace()
}

3. 补充系统权限配置 #

在AndroidManifest.xml中添加必要的网络权限：

<!-- 基础网络权限 -->
<uses-permission android:name="android.permission.INTERNET" />
<!-- 若需要其他设备访问当前Android设备的gRPC服务，添加以下权限 -->
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

注意：Android 9（API 28）及以上系统默认禁止明文传输，若你的gRPC服务未启用TLS加密，需要在AndroidManifest.xml的application节点添加android:usesCleartextTraffic="true"配置，否则会被系统拦截连接。

内容的提问来源于stack exchange，提问作者Dmitry Zaytsev