BentoPDF 自托管 Nginx 部署完全指南:WASM、SharedArrayBuffer 与 MIME 配置实战

原创2026-09-21 15:14:261,702 阅读
文章标签:前端

BentoPDF 自托管 Nginx 部署完全指南:WASM、SharedArrayBuffer 与 MIME 配置实战

BentoPDF 是一个以隐私优先为理念的 PDF 工具集,所有处理都在浏览器本地完成,静态站点形态决定了它非常适合用 Nginx 直接托管。本文以仓库中的 Nginx 部署文档 为主体,完整给出从源码构建、站点配置、SSL 签发到故障排查的全流程方案,并结合仓库内的生产 Nginx 配置与构建脚本,讲清 WASM MIME 类型、跨源隔离响应头和预压缩资源这几处最容易踩坑的底层原理。读完本文,你将能够在一台 Ubuntu/Debian 服务器上用 Nginx 独立托管一个功能完整的 BentoPDF 实例,并具备定位常见部署故障的能力。

一、部署前准备

在开始之前,请确认服务器满足以下条件:

  • Ubuntu/Debian 服务器(本文所有命令均基于该系统验证);
  • Nginx 已安装(通过 sudo apt install nginx 或发行版包管理器安装);
  • SSL 证书(推荐使用 Let's Encrypt,第 5 步会给出自动签发方案)。

需要特别说明的是,BentoPDF 是纯静态站点——没有数据库、没有后端服务,部署的本质就是把 dist 目录里的文件用 Nginx 正确地「喂」给浏览器,并让响应头满足 WASM 运行时的跨源隔离要求。

二、第一步:构建项目

克隆仓库并执行构建:

git clone https://github.com/alam00000/bentopdf.git
cd bentopdf
npm install
npm run build

构建产物输出到 dist 目录。从仓库根目录的 package.json 可以看到,npm run build 是一个多阶段流水线:先生成博客页面与静态工具链接,再执行 tsc 类型检查与 vite build,随后依次执行 SEO 页面增强、i18n 多语言页面生成、sitemap 生成、安全响应头生成和 SEO 审计。构建产物中不仅包含工具页面,还包含 public/libreoffice-wasm 下的 LibreOffice WASM 运行时(soffice.js、soffice.wasm.gz、soffice.data.gz、soffice.worker.js 等)以及 public/pdfjs-viewer 等 PDF 查看器资源。

品牌定制(可选)

如果你希望以自有品牌对外提供服务,可以在构建前设置环境变量:

VITE_BRAND_NAME="AcmePDF" VITE_BRAND_LOGO="images/acme-logo.svg" npm run build
  • VITE_BRAND_NAME:站点头部与底部展示的品牌名称,默认 BentoPDF;
  • VITE_BRAND_LOGO:相对于 public/ 目录的 Logo 路径;
  • 此外还有 VITE_FOOTER_TEXT(页脚版权文本)等构建期变量。

这些变量在 vite.config.ts 中通过 handlebars 插件注入模板上下文,并经由 define 编译进产物;在 Dockerfile 中也以 ARG/ENV 形式暴露,因此无论源码构建还是 Docker 构建,品牌定制方式完全一致。其余构建期选项(BASE_URL、SIMPLE_MODE、VITE_DEFAULT_LANGUAGE、DISABLE_TOOLS 等)均可在构建时组合使用,详见 自托管总览文档。

三、第二步:拷贝文件到 Web 根目录

sudo mkdir -p /var/www/bentopdf
sudo cp -r dist/* /var/www/bentopdf/
sudo chown -R www-data:www-data /var/www/bentopdf

这里将 dist 的全部内容复制到 /var/www/bentopdf,并把属主改为 Nginx 运行用户 www-data,确保 Nginx 进程对文件有读取权限。

四、第三步:Nginx 站点配置详解

创建站点配置文件 /etc/nginx/sites-available/bentopdf,内容如下(这是文档给出的完整生产配置,请整段使用):

server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    # SSL Configuration
    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;

    root /var/www/bentopdf;
    index index.html;

    # Gzip compression
    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/wasm;
    gzip_min_length 1000;

    # WASM MIME type
    types {
        application/wasm wasm;
    }

    # Required headers for SharedArrayBuffer (LibreOffice WASM)
    # These must be on every response - especially HTML pages
    add_header Cross-Origin-Embedder-Policy "require-corp" always;
    add_header Cross-Origin-Opener-Policy "same-origin" always;
    add_header Cross-Origin-Resource-Policy "cross-origin" always;

    # Security headers
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;

    # Pre-compressed LibreOffice WASM binary
    location ~* /libreoffice-wasm/soffice\.wasm\.gz$ {
        gzip off;
        types {} default_type application/wasm;
        add_header Content-Encoding gzip;
        add_header Cache-Control "public, immutable";
        add_header Cross-Origin-Embedder-Policy "require-corp" always;
        add_header Cross-Origin-Opener-Policy "same-origin" always;
    }

    # Pre-compressed LibreOffice WASM data
    location ~* /libreoffice-wasm/soffice\.data\.gz$ {
        gzip off;
        types {} default_type application/octet-stream;
        add_header Content-Encoding gzip;
        add_header Cache-Control "public, immutable";
        add_header Cross-Origin-Embedder-Policy "require-corp" always;
        add_header Cross-Origin-Opener-Policy "same-origin" always;
    }

    # Cache static assets
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|wasm)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
        add_header Cross-Origin-Embedder-Policy "require-corp" always;
        add_header Cross-Origin-Opener-Policy "same-origin" always;
    }

    # SPA routing - serve index.html for all routes
    location / {
        try_files $uri $uri/ /index.html;
        add_header Cross-Origin-Embedder-Policy "require-corp" always;
        add_header Cross-Origin-Opener-Policy "same-origin" always;
    }
}

下面逐段拆解这份配置的每一个关键决策。

4.1 HTTP 跳转与 SSL

第一个 server 块监听 80 端口,用 return 301 https://$server_name$request_uri; 把所有明文流量永久重定向到 HTTPS。第二个块监听 443 ssl http2,通过 ssl_certificate / ssl_certificate_key 指向 Let's Encrypt 证书。注意:BentoPDF 的 LibreOffice 文档转换依赖 SharedArrayBuffer,而浏览器只在安全上下文(HTTPS 或 http://localhost)中启用它,因此 HTTPS 不只是锦上添花,而是文档类工具(Word/ODT/Excel/PPT 转 PDF)能否工作的硬性前提。

4.2 Gzip 压缩

gzip on;
gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/wasm;
gzip_min_length 1000;

对文本类资源和 WASM 开启动态 gzip,小于 1000 字节的文件不压缩(压缩开销大于收益)。不过这里有一个进阶点:BentoPDF 的构建流水线本身就会产出预压缩资源(见 4.5 节),动态 gzip 主要服务于未被预压缩的文本文件。

4.3 WASM MIME 类型

types {
    application/wasm wasm;
}

Nginx 自带 mime.types 未必包含 wasm 扩展名,未识别扩展名会以 application/octet-stream 下发,浏览器会拒绝执行。此处在 server 块内补充映射,确保 .wasm 响应携带正确的 Content-Type: application/wasm。

4.4 跨源隔离响应头(最关键的一步)

add_header Cross-Origin-Embedder-Policy "require-corp" always;
add_header Cross-Origin-Opener-Policy "same-origin" always;
add_header Cross-Origin-Resource-Policy "cross-origin" always;

这三条头是 BentoPDF 的「命门」:LibreOffice WASM 运行时的多线程线程池需要 SharedArrayBuffer,而浏览器只会在页面满足**跨源隔离(cross-origin isolated)**时才暴露该 API。Cross-Origin-Embedder-Policy: require-corp(COEP)要求页面加载的所有子资源要么同源、要么显式允许跨源加载;Cross-Origin-Opener-Policy: same-origin(COOP)确保顶层窗口与其 opener 隔离;Cross-Origin-Resource-Policy: cross-origin(CORP)放行必要的跨源资源。always 参数保证即使响应码为非 200(如 404)也携带这些头。

务必注意:这些头必须出现在每一个响应上,尤其是 HTML 页面本身——因为 SharedArrayBuffer 的可用性取决于顶层文档的跨源隔离状态。因此下面几乎每个 location 块都重复声明了 COEP/COOP,这并非冗余,而是由 Nginx 的行为决定的:location 块内的 add_header 会整体覆盖(而非合并)server 级的 add_header。只要某个 location 自己声明了 add_header,就必须把 COEP/COOP 一并写上,否则该位置的响应就会丢失跨源隔离头。

4.5 预压缩 LibreOffice WASM 二进制与数据

location ~* /libreoffice-wasm/soffice\.wasm\.gz$ {
    gzip off;
    types {} default_type application/wasm;
    add_header Content-Encoding gzip;
    add_header Cache-Control "public, immutable";
    add_header Cross-Origin-Embedder-Policy "require-corp" always;
    add_header Cross-Origin-Opener-Policy "same-origin" always;
}

仓库中的 public/libreoffice-wasm 目录存放的是已经 gzip 压缩过的 soffice.wasm.gz 与 soffice.data.gz(文件后缀本身就是 .gz)。浏览器端的加载器 src/js/utils/libreoffice-loader.ts 会直接请求 soffice.wasm.gz,并通过 DecompressionStream('gzip') 在浏览器内解压。因此 Nginx 必须:

  • gzip off; 关闭动态压缩,防止对已经压缩的字节流二次压缩;
  • types {} default_type application/wasm; 清空继承的类型映射,强制 soffice.wasm.gz 以 application/wasm 类型下发;
  • add_header Content-Encoding gzip; 显式告知浏览器响应体是 gzip 编码的。

soffice.data.gz 与之同理,只是 default_type 为 application/octet-stream(数据段不是 WASM 可执行文件)。Cache-Control: public, immutable 与 expires 1y 用于长效缓存这些体积较大的静态资源。

4.6 静态资源缓存

location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|wasm)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
    add_header Cross-Origin-Embedder-Policy "require-corp" always;
    add_header Cross-Origin-Opener-Policy "same-origin" always;
}

带 hash 指纹的静态资源(Vite 构建产物默认 assets/[name]-[hash])可以安全地缓存一年,immutable 告诉浏览器缓存期间无需重新验证。同时不要忘记在 location 级重复 COEP/COOP 头。

4.7 SPA 路由回退

location / {
    try_files $uri $uri/ /index.html;
    add_header Cross-Origin-Embedder-Policy "require-corp" always;
    add_header Cross-Origin-Opener-Policy "same-origin" always;
}

BentoPDF 使用 Vite 构建,工具页面的路由在构建期被拍平成静态 HTML(见 vite.config.ts 的 flattenPagesPlugin),但出于稳妥考虑,try_files 仍会为不存在的路径回退到 index.html,避免刷新深层链接时 404。

五、第四步:启用站点

sudo ln -s /etc/nginx/sites-available/bentopdf /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
  • ln -s 建立软链接,将站点从 sites-available 启用;
  • nginx -t 先做语法检查,任何配置错误都会在这里暴露;
  • systemctl reload nginx 平滑重载配置,不中断现有连接。

六、第五步:用 Let's Encrypt 签发 SSL 证书

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.com

certbot --nginx 会自动识别 Nginx 配置中的 server_name、签发证书,并改写站点配置以启用 HTTPS(包括自动配置证书路径和 80→443 跳转)。签发完成后,记得回到配置中核对 ssl_certificate 路径是否与 certbot 写入的一致。

七、子目录部署(可选)

如果你想把 BentoPDF 挂在已有域名的子路径(如 https://your-domain.com/pdf/)下,需要同时改两处。

Nginx 侧:

location /pdf/ {
    alias /var/www/bentopdf/;
    try_files $uri $uri/ /pdf/index.html;
}

构建侧(关键:必须与 Nginx 路径一致):

BASE_URL=/pdf/ npm run build

BASE_URL 在 vite.config.ts 中被读取并作为 Vite 的 base 与 handlebars 模板的 baseUrl;构建结束后,rewriteHtmlPathsPlugin(vite.config.ts)会把 HTML 内所有 href="/..."、src="/..."、content="/..." 的根绝对路径改写成 BASE_URL 前缀,从而保证子目录部署下所有静态资源与页面链接都指向 /pdf/ 之下。反过来,如果你改了 BASE_URL 却没有匹配的 Nginx location,页面将加载不出任何资源。

八、性能调优

在 nginx.conf 的 http {} 块中加入以下指令:

http {
    # Enable sendfile
    sendfile on;
    tcp_nopush on;
    tcp_nodelay on;

    # Increase buffer sizes
    client_max_body_size 100M;

    # Worker connections
    worker_connections 2048;
}
  • sendfile on:让内核直接在内核态完成文件传输,绕过用户态拷贝,是静态文件服务的标配;
  • tcp_nopush / tcp_nodelay:分别优化大文件与小包/交互式请求的 TCP 传输;
  • client_max_body_size 100M:BentoPDF 的 PDF 处理全部在浏览器本地完成,请求体通常很小;此值主要影响反向代理场景下代理转发大文件(如 Office 文档)的上限,可按需调整;
  • worker_connections 2048:提高单 worker 的并发连接数。

作为对照,仓库根目录的 nginx.conf 是官方 Docker 镜像内置的生产配置,其中 gzip_static on; 会优先直接发送预压缩的 .gz 文件(避免每个请求重复压缩),gzip_comp_level 9 配合预压缩产物,以及按文件类型分类的 expires 1y 缓存策略,都值得参考。

九、故障排查

9.1 WASM 不加载

如果控制台提示 WASM 相关错误,首先确认 MIME 类型已设置:

types {
    application/wasm wasm;
}

响应头必须为 Content-Type: application/wasm。此外,若浏览器报错 expected magic word 00 61 73 6d, found 1f 8b 08 08,说明浏览器收到的是未解压的 gzip 字节流——根因是预压缩的 soffice.wasm.gz 响应缺少 Content-Encoding: gzip 头(见 4.5 节),而不是 WASM 文件本身损坏。

9.2 Sign PDF 或表单填写器白屏(.mjs MIME 错误)

症状:签名 PDF(Sign PDF)、表单填写(Form Filler)等工具打开后查看器空白,浏览器控制台报错:

Failed to load module script: The server responded with a non-JavaScript
MIME type of "application/octet-stream". Strict MIME type checking is
enforced for module scripts per HTML spec.

原因:BentoPDF 内置的 PDF 查看器(用于 Sign PDF、Form Filler 等工具,位于 public/pdfjs-viewer 与 public/pdfjs-annotation-viewer)以 ES Module 形式发布,文件扩展名为 .mjs。Nginx 自带的 mime.types 默认不包含 .mjs 映射,于是以 application/octet-stream 下发,浏览器基于 HTML 规范的严格 MIME 检查会拒绝执行模块脚本。

修复方法一:编辑 /etc/nginx/mime.types,在已有的 application/javascript 行上追加 mjs:

application/javascript    js mjs;

注意:不要新增第二条 application/javascript 行!Nginx 按行解析 mime.types,同一类型到扩展名的映射只有一行生效,部分版本会静默忽略重复行。必须在原有行上修改。

修复方法二:不修改全局文件,只在 server 块内局部覆盖:

types {
    application/javascript js mjs;
    application/wasm wasm;
}

修改后重载:

sudo nginx -t && sudo systemctl reload nginx

验证:打开浏览器 DevTools → Network,找到失败的 .mjs 请求,检查 Content-Type 响应头,应为 application/javascript 而非 application/octet-stream。如果外层还有 CDN 或反向代理,每层都可能重新嗅探类型,需要逐层排查。

9.3 Word/ODT/Excel 转 PDF 不工作

症状:Word、ODT、Excel、PowerPoint 转 PDF 卡住或无法启动。

原因:LibreOffice WASM 依赖 SharedArrayBuffer,其可用需要同时满足两个条件:

  1. 页面处于跨源隔离状态——每一个响应都携带 Cross-Origin-Embedder-Policy: require-corp 与 Cross-Origin-Opener-Policy: same-origin;
  2. 页面处于安全上下文——HTTPS 或 http://localhost。http://192.168.x.x 这类局域网 HTTP 地址不算安全上下文,浏览器会禁用 SharedArrayBuffer,这种情况下没有任何响应头配置能修复,只能给站点启用 HTTPS(或本地回环访问)。

另外再次强调 Nginx 的 add_header 继承规则:location 块内的 add_header 会覆盖(而不是合并)server 级的 add_header。因此凡是有自己的 add_header 的 location(缓存、预压缩资源、SPA 路由等),都必须同时带上 COEP/COOP 头。

验证方法:

curl -I https://your-domain.com/ | grep -i cross-origin

正常输出应包含:

cross-origin-embedder-policy: require-corp
cross-origin-opener-policy: same-origin
cross-origin-resource-policy: cross-origin

如果 Nginx 前面还有一层反向代理(如云负载均衡、另一台 Nginx),请确保这层代理透传这些响应头,不要在代理层剥离或改写。也可以在浏览器 DevTools 控制台运行以下脚本做端到端验证:

console.log(window.crossOriginIsolated); // 应为 true
console.log(typeof SharedArrayBuffer);   // 应为 "function"

9.4 502 Bad Gateway

BentoPDF 本身是静态站点,正常情况下不会有上游服务;502 通常出现在「Nginx 反向代理到其他服务」的部署形态中。先查看错误日志定位:

sudo tail -f /var/log/nginx/error.log

十、从仓库源码理解这些配置的由来

前面几节反复强调的头、MIME 与预压缩逻辑,并非凭空要求,仓库里每一处都有对应的实现证据:

  • 官方镜像的生产配置:仓库根目录的 nginx.conf 是 Docker 镜像内置配置,可见 types { application/javascript mjs; }、gzip_static on;、对 soffice.wasm.gz / soffice.data.gz 的 Content-Encoding gzip 处理,以及按扩展名分类的 expires 1y,与本文第 4 节的目标完全一致,可作为自建配置的对照范本;
  • 预压缩资源从何而来:构建脚本 scripts/compress-static-assets.mjs 会对 dist 中超过 1 KB 的 .wasm、.data、.zip、.json 文件执行 gzip(level 9)与 Brotli(level 11)预压缩;vite.config.ts 中的 viteCompression 插件则负责对 JS/CSS/HTML 等产物生成 .gz 与 .br。这就是「构建产物里直接存在 soffice.wasm.gz」的原因;
  • 浏览器端如何消费预压缩文件:src/js/utils/libreoffice-loader.ts 明确以 application/wasm 请求 soffice.wasm.gz,并用 DecompressionStream('gzip') 在浏览器内解压——所以服务端必须如实标注 Content-Encoding: gzip,否则浏览器会把 gzip 原始字节当作 WASM 解析,抛出 expected magic word 00 61 73 6d, found 1f 8b 08 08;
  • 开发/预览环境的一致性:vite.config.ts 在 dev server 与 preview server 中都注入了 Cross-Origin-Opener-Policy: same-origin 与 Cross-Origin-Embedder-Policy: require-corp,保证本地开发与生产 Nginx 行为一致;
  • 多语言与 SEO 说明:构建会按 22 种语言生成目录化页面(见 vite.config.ts 的 SUPPORTED_LANGUAGES),并使用 try_files 风格的静态路由;若做公开部署,关于 canonical 与 noindex 的取舍可参考 STATIC-HOSTING.md 与 docs/self-hosting/index.md。

十一、部署完成后的验证清单

上线前按顺序自查一遍,可以避免绝大多数「看起来部署了但功能不全」的问题:

  1. curl -I https://your-domain.com/ 检查 cross-origin-embedder-policy、cross-origin-opener-policy 头存在;
  2. 检查 .wasm 响应 Content-Type: application/wasm、.wasm.gz 响应带 Content-Encoding: gzip;
  3. 检查 .mjs 请求 Content-Type: application/javascript;
  4. 浏览器打开一个 LibreOffice 类工具(如 Word 转 PDF),控制台执行 window.crossOriginIsolated 应输出 true;
  5. 用局域网 IP(http://192.168.x.x)访问时文档转换不可用属于预期行为——请改用 HTTPS 域名。

按本文步骤完成构建、拷贝、配置与 SSL 签发后,你的 BentoPDF 实例即可在 Nginx 上稳定运行,所有 PDF 工具包括依赖 WASM 与 SharedArrayBuffer 的文档转换能力都能完整工作。

登录后查看全文
bentopdf