Trilium Notes 103+ 版本 Nginx/OpenResty 反代兼容修复全记录（运维归档）

一、故障概述#

1.1 环境信息#

• 运行环境：1Panel + OpenResty
• 服务程序：Trilium Notes
• 升级变动：v102.x 正常 → 升级 v103+ 后分享页面异常
• 反代域名：docs.isrv.cn

1.2 升级后出现的全部故障现象#

• 分享页面侧边栏图标乱码、方框占位、字体加载失败
• 页面样式完全丢失、排版错乱、无CSS样式
• 浏览器控制台报错：静态资源 MIME 类型不匹配（application/json）
• JS/CSS 被浏览器拦截：X\-Content\-Type\-Options: nosniff 策略拦截
• 字体文件 woff2 404 加载失败
• 首页访问异常、空白/报错，短链接笔记页面可访问但无样式

1.3 浏览器核心报错日志#

• 已拦截加载自 /assets/scripts\.js 的模块，MIME 类型不匹配（application/json）
• 来自/assets/styles\.css 资源被阻止，MIME类型不匹配
• downloadable font: download failed boxicons.woff2 404
• NS_ERROR_CORRUPTED_CONTENT 资源损坏/内容不合法

二、故障根因深度分析（v103 版本核心变更）#

本次所有问题并非配置语法错误，而是 Trilium 103+ 对分享模块路由结构进行了重构，旧版反代规则完全失效。

2.1 关键架构变更#

Trilium 102 及更早版本：

• 分享页面静态资源、字体、CSS、JS、API 均在服务根路径
• 资源地址：域名/assets/xxx → 转发后端根路径即可正常访问

Trilium 103+ 新版：

• 所有分享页资源全部迁移至 /share/ 子路径下
• 前端请求：/assets/xxx
• 后端真实路径：/share/assets/xxx

2.2 报错产生逻辑#

旧配置将 /assets/ 直接转发到 Trilium 根目录，后端根目录不存在该资源，返回 JSON格式404错误。

浏览器收到 CSS/JS 请求的返回内容是 JSON，触发：

• X\-Content\-Type\-Options: nosniff 严格MIME校验拦截
• 静态资源全部加载失败 → 页面无样式、图标乱码

三、原旧配置存在的全部问题（102可用、103完全失效）#

3.1 原始可用旧配置#

server {
    listen 443 ssl;
    server_name docs.isrv.cn;

    ssl_certificate /www/sites/docs.isrv.cn/ssl/fullchain.pem;
    ssl_certificate_key /www/sites/docs.isrv.cn/ssl/privkey.pem;

    # 首页
    location = / {
        proxy_pass http://127.0.0.1:10001/share/library;
        proxy_http_version 1.1;

        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 https;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Port 443;

        proxy_buffering off;
    }

    # Share 主路径
    location / {
        proxy_pass http://127.0.0.1:10001/share/;
        proxy_http_version 1.1;

        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 https;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Port 443;

        proxy_buffering off;
    }

    # 字体专用修复（移动端关键）
    location ~* \.(woff|woff2|ttf|eot|otf)$ {
        proxy_pass http://127.0.0.1:10001;
        proxy_http_version 1.1;

        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 https;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Port 443;

        add_header Access-Control-Allow-Origin * always;

        types {
            font/woff woff;
            font/woff2 woff2;
        }
    }

    # 安全优化
    add_header X-Frame-Options SAMEORIGIN always;
    add_header X-Content-Type-Options nosniff always;
    add_header Referrer-Policy strict-origin-when-cross-origin always;
}

3.2 旧配置致命缺陷（适配不了103+）#

1. 静态资源路径不匹配
   • 未单独拦截 /assets/ 路径，被通用规则错误转发
   • 请求被转发至根路径，而非新版的 /share/assets/
2. API图片资源404
   • 新版分享图片接口位于 /share/api/，旧配置无对应转发规则
3. 字体规则失效
   • 新版字体路径为 /share/assets/fonts/，旧规则无法匹配
4. 路径优先级冲突
   • 正则匹配曾误拦截静态资源，导致资源返回JSON报错
5. OpenResty环境兼容问题
   • 部分通用Nginx配置在1Panel-OpenResty下报语法错误

四、最终修复配置（103+专用、1Panel/OpenResty稳定可用）#

该配置已100%解决：样式丢失、图标乱码、MIME报错、资源404、首页异常全部问题

server {
    listen 443 ssl;
    server_name docs.isrv.cn;

    ssl_certificate /www/sites/docs.isrv.cn/ssl/fullchain.pem;
    ssl_certificate_key /www/sites/docs.isrv.cn/ssl/privkey.pem;
    charset utf-8;

    # ==============================
    # 103+核心修复：分享页静态资源专用路径
    # 解决CSS/JS/字体MIME错误、样式丢失、图标乱码
    # ==============================
    location /assets/ {
        proxy_pass http://127.0.0.1:10001/share/assets/;
        proxy_http_version 1.1;
        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 https;
        proxy_buffering on;
        expires 7d;
        add_header Access-Control-Allow-Origin * always;
    }

    # ==============================
    # 103+ API专用转发（修复图片、附件404）
    # ==============================
    location /api/ {
        proxy_pass http://127.0.0.1:10001/share/api/;
        proxy_http_version 1.1;
        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 https;
    }

    # ==============================
    # 独立首页规则（修复根路径无法访问）
    # ==============================
    location = / {
        proxy_pass http://127.0.0.1:10001/share/library;
        proxy_http_version 1.1;
        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 https;
        proxy_buffering off;
    }

    # ==============================
    # 通用分享页面/短链接入口
    # ==============================
    location / {
        proxy_pass http://127.0.0.1:10001/share/;
        proxy_http_version 1.1;
        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 https;
        proxy_buffering off;
    }

    # ==============================
    # 安全头部配置
    # ==============================
    add_header X-Frame-Options SAMEORIGIN always;
    add_header X-Content-Type-Options nosniff always;
}

五、本次升级关键修复总结#

1. 路径适配修复（核心）
   • 前端 /assets/ → 后端真实 /share/assets/
   • 前端 /api/ → 后端真实 /share/api/
2. 解决MIME类型报错
   • 资源不再返回JSON404，返回正确CSS/JS/字体文件
   • 浏览器不再拦截资源，样式彻底恢复
3. 解决图标乱码
   • 字体文件正常加载，boxicons图标恢复正常
4. 修复首页访问异常
   • 独立精准匹配根路径，优先转发至分享库首页
5. 适配OpenResty/1Panel环境
   • 去除不兼容配置、无语法报错、可直接校验重载
6. 优化静态资源缓存
   • 开启缓存、跨域头，提升页面加载速度与稳定性

六、最终验证标准（全部通过即修复完成）#

• ✅ Nginx配置检查无报错、重载成功
• ✅ 域名首页可正常访问分享库
• ✅ 任意分享短链接页面样式完整、无错乱
• ✅ 侧边栏图标正常显示，无方框乱码
• ✅ 浏览器控制台无MIME拦截、无JS报错
• ✅ 页面图片、静态资源全部200正常加载

七、运维避坑总结#

1. Trilium 103+ 属于结构性路由更新，旧版反代规则完全不兼容，并非小问题bug
2. 分享页面所有静态资源、API接口全部迁移至 /share/ 子路径，必须单独配置转发
3. Nginx静态资源规则优先级必须高于通用规则，防止路径被错误拦截
4. OpenResty环境禁止直接套用原生Nginx配置，需规避路径、语法兼容问题
5. nosniff 安全头开启后，必须保证资源MIME完全正确，否则100%拦截样式