寻径

一次 Intel iGPU 硬件编码失效的排查：GuC / HuC / firmware 才是关键

Fri, 30 Jan 2026 13:47:26 GMT

前言

鄙人最近开始优化Homelab架构，打算做算存分离，遂把Jellyfin等容器开始移向我的N5095小主机上，但存在无法硬件编码的情况，排查了一下午，换了许多的镜像都无法成功，故折腾了一翻，才有了这篇文章，旨在帮助后人在再次遇到此类问题时能有些许帮助

正文

环境

硬件平台：

CPU：Intel Jasper Lake N5095（Gen11 iGPU）
无独显

系统环境：

Debian 13 (trixie)
Kernel: 6.12.x
Docker + docker-compose

服务：

Jellyfin（nyanmisaka/jellyfin）
使用 QSV / VAAPI 硬件转码

现象描述

鄙人在转移服务时，发现同一套Jellyfin配置下，在QNAP-464C2（同样也是N5095）上可以正常运行硬件编码，但是在Debian13上无法播放，FFmpeg日志中只有一句：

FFmpeg exited with code 234

在尝试关闭硬件编码后，一切正常，但性能很烂，QSV解码+软件编码在4K80Mbps HDR10 转码20Mbps SDR色调映射时转码帧率只有20，而且CPU打满影响其他容器，这肯定是无法满足正常需求的已经确定的是：

QSV解码能正常运行
/dev/dri/renderD128在容器中是存在的
vainfo在容器中也是正常的
intel_gpu_top也能正常看到有调用

一切都指向硬件解码是完好的，但硬件编码就是无法正常使用

突破点

我在QNAP上排查到这一步时：

sudo dmesg | grep -i guc
sudo dmesg | grep -i huc

结果中有部分是这样的:

[    5.960585] [drm] GuC communication enabled
[    5.971545] i915 0000:00:02.0: [drm] GuC firmware i915/ehl_guc_33.0.4.bin version 33.0 submission:disabled
[    5.982316] i915 0000:00:02.0: [drm] HuC firmware i915/ehl_huc_9.0.0.bin version 9.0 authenticated:yes

然后我在Debian上敲了一样的命令，发现什么都没有，感觉完全没有加载查询了一下，Debian没有安装Intel的非自由固件

解决方案

安装固件包

sudo apt update
sudo apt install firmware-misc-nonfree firmware-intel-misc

装完后查看

ls /lib/firmware/i915/ | grep ehl

应当能看到

ehl_guc_70.1.1.bin
ehl_huc_9.0.0.bin

修改GRUB，添加i915.enable_guc=3

GRUB_CMDLINE_LINUX_DEFAULT="quiet i915.enable_guc=3"

更新GRUB并重启

sudo update-grub
sudo reboot

重启后再次查看dmesg，应当看到类似以下的内容

[   34.982106] Setting dangerous option enable_guc - tainting kernel
[   36.726000] i915 0000:00:02.0: [drm] GT0: GuC firmware i915/ehl_guc_70.1.1.bin version 70.1.1
[   36.742212] i915 0000:00:02.0: [drm] GT0: GUC: submission enabled
[   36.742214] i915 0000:00:02.0: [drm] GT0: GUC: SLPC disabled
[   36.726021] i915 0000:00:02.0: [drm] GT0: HuC firmware i915/ehl_huc_9.0.0.bin version 9.0.0
[   36.741869] i915 0000:00:02.0: [drm] GT0: HuC: authenticated for all workloads

Jellyfin配置参考

docker-compose.yml:

services:
  jellyfin:
    image: nyanmisaka/jellyfin:latest
    container_name: Jellyfin
    privileged: true
    network_mode: host
    restart: unless-stopped
    devices:
      - /dev/dri/renderD128:/dev/dri/renderD128
    volumes:
      - ./config:/config
      - ./cache:/cache
      - ./media:/media
      - /etc/localtime:/etc/localtime:ro
    environment:
      - TZ=Asia/Shanghai

jellyfin:

自定义注解鉴权

Mon, 03 Feb 2025 08:01:21 GMT

在Service层里鉴权固然方便，也是我一直使用的方式，但是，如果我需要级联调用service，就会导致重复鉴权，这一点是没必要的，所以打算把鉴权提取出来。

开始

1. 注解

创建一个注解类

@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD, ElementType.TYPE})
@Documented
public @interface RequirePermission {
    Role[] value();
}

注意这个Role是一个权限的枚举类

2. 在Controller打上注解

可以在类上注解

@RequirePermission({Role.systemAdministrator})
public class UniversityController

也可以在方法上注解

    @RequirePermission({Role.systemAdministrator})
    @ApiOperation("登陆接口")
    @PostMapping("/login")
    public Response<LoginResultVO> login(@RequestBody LoginForm loginForm)

3. 在AOP中解析

定义切点

    @Pointcut("@within(*.api.annotation.RequirePermission) || @annotation(*.api.annotation.RequirePermission)")
    public void permissionCheck() {}

定义方法

    @Around("permissionCheck()")
    public Object checkPermission(ProceedingJoinPoint joinPoint) throws Throwable {
        MethodSignature signature = (MethodSignature) joinPoint.getSignature();
        Method method = signature.getMethod();

        RequirePermission methodAnnotation = AnnotationUtils.findAnnotation(method, RequirePermission.class);

        // 获取类上的注解
        RequirePermission classAnnotation = AnnotationUtils.findAnnotation(method.getDeclaringClass(), RequirePermission.class);

        // 优先使用方法上的注解，如果没有则使用类上的注解
        Role[] requiredRoles = methodAnnotation != null ? methodAnnotation.value() :
                classAnnotation != null ? classAnnotation.value() : new Role[0];
        //TODO: 权限校验

        return joinPoint.proceed();
    }

部署到阿里云CDN的注意事项

Mon, 30 Dec 2024 05:48:21 GMT

起因

我一开始把博客部署在DCDN上，但是发现DCDN不会缓存图片/文件接口，于是我到了CDN。 CDN确实一开始用的很爽，都缓存了，但是，我发现，即使params改变了，阿里云居然返回的都是同样的json。我一开始以为是前端的问题，还去把前端一些url路径从params转为了query，发现任然不济于事。接着翻了翻阿里云CDN的文档，要设置Cache-Control: no-cache

解决

在Spring拦截器里给json接口添加上Cache-Control: no-cache就好了

@ControllerAdvice
public class GlobalResponseHeaderAdvice {

    @ModelAttribute
    public void setGlobalCacheControl(HttpServletRequest request, HttpServletResponse response) {
        String uri = request.getRequestURI();

        // 排除特定接口
        if (uri.startsWith("/api/file/download/")) {
            return;
        }

        // 默认添加 Cache-Control: no-cache
        response.setHeader("Cache-Control", "no-cache");
    }
}

vite部署到nginx的一些常见问题

Fri, 20 Dec 2024 05:07:47 GMT

路由问题

vue router运行在hash模式下，会有/#/，觉得很丑，然后就运行在了history模式下，但是，这么模式下需要注意一些问题：如果你没有在nginx里配置好的话，就会导致刷新页面404。所以，需要在nginx里配置好try_files:

location / {
    try_files $uri $uri/ /index.html;
}

api代理问题

相信大家在使用vite的过程中为了隐藏后端真实网址使用过vite的代理服务器吧，类似于这种

proxy: {
      '/api': {
        target: 'http://localhost:port/',
        changeOrigin: true
      }
}

我当时认为，只要在vite里配置好代理就不需要操心了，我在main.js里配置了一些init方法，如果init报错就不创建App。其次，我也配置了上文提到的try_files，所以这就导致了看不到任何的404报错，最后去除掉try_files才定位到问题。所以，即使在vite里配置好代理，也仅限于开发的情况下有效，在项目上线时仍然要在nginx里配置代理:

location /api/ {
    proxy_pass http://localhost:port/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

nginx会把/api/给删除，所以需要注意一下你的后端配置。这下就可以正常访问后端接口了

第十七周

Wed, 18 Dec 2024 09:17:06 GMT

做了什么

最近心血来潮，想要开发一个属于自己的博客

个人博客的前端 & 后端的基础开发，已经完成绝大多数功能

TODO

友链、工具和主页的前后端开发，以及一些细节样式 & 动画的完善
大学物理
计组
至于仿微信，，等有空再完善吧（狗头

TODO（长远下个学期？）

学习MQ和servlet（虽然说Spring Boot很牛逼，但是基础还是得打好）
学习jsp（下个学期的专业课之一）
学习CSS 和 vite
深入学习数据库

接入CloudFlare的人机验证接口

Thu, 12 Dec 2024 12:37:41 GMT

开始

先去 CloudFlare 注册一个账号并且开通拿到 Turnstile 的站点密钥和密钥

前端以vue为例如何使用人机验证

先导入CloudFlare提供的验证接口

onMounted(() => {
  const script = document.createElement('script');
  script.src = 'https://challenges.cloudflare.com/turnstile/v0/api.js';
  script.async = true;
  script.onload = () => {
    loadTurnstile();
  };
  document.head.appendChild(script);
});

function loadTurnstile() {
  turnstile.render('#example-container', {
    sitekey: "<你拿到的站点密钥>",
    callback: function (token) {
      console.log(`Challenge Success ${token}`);
    },
  });
}

接下来在你的这个页面任何想验证的地方

<div id="example-container" data-sitekey="<你拿到的站点密钥>"></div>

完成以上操作后，你就可以在你的站点看到人机验证码(ps这个页面我随便写的没有调整样式)

但是这样还是不够的，需要后端配合二次验证

后端需要对前端拿到的token进行验证，这里以java为例如果你使用的是maven，需要导入依赖

<dependency>
      <groupId>org.apache.httpcomponents</groupId>
      <artifactId>httpcore</artifactId>
      <version>4.4.16</version>
</dependency>
<dependency>
      <groupId>org.apache.httpcomponents</groupId>
      <artifactId>httpclient</artifactId>
      <version>4.5.14</version>
</dependency>

接下来创建一个工具类

import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.entity.StringEntity;
import org.apache.http.util.EntityUtils;
import org.json.JSONObject;
/**
 * @author ATRI <miko217@xnu.edu.cn>
 */
public class TurnstileUtil {
    private static final String VERIFY_URL = "https://challenges.cloudflare.com/turnstile/v0/siteverify";
    private static final String SECRET_KEY = "<替换为你的密钥>";

    /**
     * 验证 Turnstile Token 是否有效
     *
     * @param token 用户提交的 Turnstile Token
     * @return 验证结果，true 表示验证通过，false 表示失败
     */
    public static boolean validateToken(String token) {
        try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
            HttpPost httpPost = new HttpPost(VERIFY_URL);

            JSONObject requestBody = new JSONObject();
            requestBody.put("secret", SECRET_KEY);
            requestBody.put("response", token);

            httpPost.setEntity(new StringEntity(requestBody.toString()));
            httpPost.setHeader("Content-type", "application/json");

            CloseableHttpResponse response = httpClient.execute(httpPost);
            String responseString = EntityUtils.toString(response.getEntity());
            JSONObject jsonResponse = new JSONObject(responseString);

            return jsonResponse.getBoolean("success");
        } catch (Exception e) {
            e.printStackTrace();
            return false;
        }
    }
}

接下来需要在你任何想要认证的地方

if (!TurnstileUtil.validateToken(token)) { //这个token是前端经过验证后拿到的
     throw new ServiceException(ResponseType.TURNSTILE_VERIFICATION_FAILED);
}

接下来已经接入CloudFlare的接口了

第十五周

Wed, 11 Dec 2024 11:39:47 GMT

第十五周

做了什么

前端

修改密码
修改个人信息
初始化ws
初始化本地数据库
数据库常用操作封装（自己封装~~MyBatis~~?）
能够展示会话列表
能够从本地数据库中拿到聊天记录
发送文本消息

后端

Redisson 的 RTpoic Pub/Sub
所有的WS编写
发送消息接口
上传文件接口
后端基本完结

TODO

!important：前端完成发送多媒体消息和美化展示文本消息
!important：前端完成消息的实时加载
~~对CUD操作引入MQ~~
把对于大宗文件，上传到OSS中
后端的一些TODO（大多都是insert or update)

寻径

一次 Intel iGPU 硬件编码失效的排查：GuC / HuC / firmware 才是关键

前言

正文

环境

现象描述

突破点

解决方案

Jellyfin配置参考

自定义注解鉴权

开始

1. 注解

2. 在Controller打上注解

3. 在AOP中解析

部署到阿里云CDN的注意事项

起因

解决

vite部署到nginx的一些常见问题

路由问题

api代理问题

第十七周

做了什么

TODO

TODO（长远 下个学期？）

接入CloudFlare的人机验证接口

开始

第十五周

第十五周

做了什么

前端

后端

TODO

TODO（长远下个学期？）