Ubuntu 24.04 安装 OmniTools 0.7.0 指南

目标：在 Ubuntu 24.04 服务器上以「源码构建 + Nginx 托管 + systemd 服务化」的方式从零安装 OmniTools 0.7.0，给出完整的依赖链、逐条实测命令与回显、两条真实排障实录（GitHub 直连失败、.mjs MIME 类型缺失），并对照官方打包制品发行形态给出方案选择建议。全文命令均在 Ubuntu 24.04.5 LTS 真机实测通过。

一、环境信息

操作系统：Ubuntu 24.04.5 LTS（Noble Numbat）x86_64，实测 cat /etc/os-release 回显：

PRETTY_NAME="Ubuntu 24.04.5 LTS"
NAME="Ubuntu"
VERSION_ID="24.04"
VERSION="24.04.5 LTS (Noble Numbat)"

软件：OmniTools 0.7.0（tag v0.7.0，commit 5f8f4c7）；
构建工具链：Node.js 20.20.2（npm 10.8.2，NodeSource 官方源安装）、git 2.43.0；
Web 服务：nginx/1.24.0 (Ubuntu)，监听 8143 端口；
部署路径：源码 /opt/omni-tools，站点根 /var/www/omnitools；
内存 18GB、磁盘余量 147GB（构建期 node_modules 约 1.6GB，产物 dist/ 约 46MB，构建峰值内存约 2GB）；
网络说明：Ubuntu 官方 apt 源直连可用（实测 apt-get update 拉取 33.6MB/29s）；GitHub 直连实测失败（现象见 8.1 节），走代理 192.168.1.62:7897 后可用。

二、前置条件

一台 Ubuntu 24.04 服务器，具备 root 或 sudo 权限；
服务器可访问外网（apt 与 npm 下载依赖；完全离线环境可先在有网机器构建，再把 dist/ 目录整体拷贝到内网服务器，见 6.2 节方案对比）；
端口 8143 未被占用（本指南监听端口，可按需更换；ss -ltn | grep 8143 无输出即为空闲）；
基础工具 curl 与 git（步骤 4.1 安装）。

三、版本选型说明

3.1 为什么选 0.7.0

OmniTools 目前处于 0.x 阶段，最新发布即功能最全的一版：v0.7.0 于 2026-10-20 发布（GitHub Releases 页实查），包含 12 大类 128 个工具（v0.7.0 源码逐目录统计），且本批实测其构建（tsc 类型检查 + Vite 打包）、全量单元测试（695 个用例）、Nginx 托管与浏览器访问全部通过，可直接投产。

3.2 运行时依赖链

OmniTools 0.7.0 的依赖链比常规 Web 应用短——它构建后是纯静态站点，没有自己的服务端进程：

构建期（一次性）：Node.js 20 + npm + git + GitHub 源码
        │ npm install（1148 个依赖包）
        │ npm run build（tsc && vite build）
        ▼
运行期（常驻）：Nginx（systemd 托管） ──► 静态托管 dist/ 产物
        ▼
浏览器端：React 单页应用，全部工具在浏览器内计算（WASM/Worker），服务器零计算

要点：Node.js 只在构建期需要；若在另一台有网机器上构建好 dist/，运行服务器连 Node.js 都不需要，只要有 Nginx。数据面无需数据库、无需消息队列。

3.3 官方发行形态对照

官方 README 的 Self-host/Run 一节主推「打包制品」发行：官方将应用连同内建 Nginx 打包为约 28MB 的自包含轻量制品，获取与启动为「拉取 iib0011/omni-tools 官方制品 → 启动 → 把宿主机 8080 端口转发到制品内监听的 80 端口」三步，启动后无需额外配置即可访问（转述官方 README，查询日期 2026-10-28；制品内建 Nginx 与本指南 4.7 节的两处站点适配一致，对照见 6.2 节）。本指南主线采用源码构建直装，适合需要纳入既有 systemd 运维体系、复用统一 Nginx 或部署在隔离内网的场景。

四、方案 A：源码构建直装（主线方案）

4.1 方案说明与基础依赖

方案 A 在目标服务器上拉取 v0.7.0 源码，用 Node.js 20 构建出静态产物，交给本机 Nginx 托管，由 systemd 管理 Nginx 常驻。先安装基础工具：

sudo apt-get update
sudo apt-get install -y curl git nginx

实测回显（输出节选（实测首尾））：

Get:19 http://archive.ubuntu.com/ubuntu noble-backports/universe amd64 Packages [36.0 kB]
Fetched 33.6 MB in 29s (1159 kB/s)
Setting up git (1:2.43.0-1ubuntu7.4) ...
Processing triggers for libc-bin (2.39-0ubuntu8.9) ...

验证版本：

nginx -v && git --version

nginx version: nginx/1.24.0 (Ubuntu)
git version: 2.43.0

4.2 安装 Node.js 20（构建工具链）

官方构建描述声明以 Node.js 20 为构建基础环境（v0.7.0 官方构建描述实读）。Ubuntu 24.04 官方源的 nodejs 包版本偏旧，按 NodeSource 官方脚本配置 Node 20 源后安装：

curl -fsSL https://deb.nodesource.com/setup_20.x -o /tmp/nodesource_setup.sh
sudo bash /tmp/nodesource_setup.sh
sudo apt-get install -y nodejs

实测回显（输出节选（实测首尾））：

2026-10-28 14:20:08 - You can use N|solid Runtime as a node.js alternative
Setting up nodejs (20.20.2-1nodesource1) ...
Processing triggers for systemd (255.4-1ubuntu8.18) ...

验证：

node -v && npm -v

v20.20.2
10.8.2

4.3 获取 v0.7.0 源码

git clone --branch v0.7.0 --depth 1 https://github.com/iib0011/omni-tools.git /opt/omni-tools
cd /opt/omni-tools && git rev-parse --short HEAD && git describe --tags --exact-match

⚠️ 网络说明：GitHub 直连在当时环境实测失败（报 GnuTLS recv error (-110)，完整现象与解决见 8.1 节），已改走代理；代理可用时同一条 clone 命令加环境变量即可：

export http_proxy=http://192.168.1.62:7897 https_proxy=http://192.168.1.62:7897
git clone --branch v0.7.0 --depth 1 https://github.com/iib0011/omni-tools.git /opt/omni-tools

实测回显（输出节选（实测首尾））：

Note: switching to '5f8f4c7b92060f904b40fafb0649701921fe7746'.
You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by switching back to a branch.

验证版本与仓库体积：

5f8f4c7
v0.7.0
9.8M	/opt/omni-tools

4.4 安装项目依赖

cd /opt/omni-tools
npm install --no-audit --no-fund

实测回显：

added 1148 packages in 32s

依赖落盘约 1.6GB（du -sh node_modules 实测），国内网络慢时可同样走代理（export http_proxy=... https_proxy=... 后再执行 npm install，实测 1148 包在半分钟级完成）。

4.5 构建

npm run build

实测回显（输出节选（实测首尾））：

> omni-tools@0.7.0 build
> tsc && vite build

vite v5.4.20 building for production...
dist/assets/index-DR-NHKWD.js                                       622.11 kB │ gzip:  72.50 kB
（中间为 228 个产物文件逐个输出）
dist/assets/ToolMultipleImageInput-B2lvA6na.js                      2,732.15 kB │ gzip: 672.75 kB
✓ built in 15.65s

tsc 无报错、✓ built 即成功。产物统计（实测）：

du -sh dist && find dist -type f | wc -l

46M	/opt/omni-tools/dist
228

4.6 部署产物到站点根目录

sudo mkdir -p /var/www/omnitools
sudo cp -r /opt/omni-tools/dist/. /var/www/omnitools/
ls /var/www/omnitools

实测回显：

_redirects  apple-touch-icon.png  assets  favicon-96x96.png  favicon.ico  favicon.png  favicon.svg  gs.js  index.html  locales  robots.txt  site.webmanifest  web-app-manifest-192x192.png  web-app-manifest-512x512.png

4.7 Nginx 站点配置（含两处必需适配）

新建站点配置 /etc/nginx/sites-available/omnitools.conf：

server {
    listen 8143;
    listen [::]:8143;
    server_name _;
    root /var/www/omnitools;
    index index.html;

    # 单页应用路由回退：未命中静态文件时统一回入口页（与官方制品内配置一致）
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 带内容哈希的静态资源长缓存
    location /assets/ {
        expires 30d;
        add_header Cache-Control "public, immutable";
    }

    gzip on;
    gzip_comp_level 5;
    gzip_min_length 1024;
    gzip_types text/plain text/css application/javascript application/json image/svg+xml;
}

逐项说明：listen 8143 为服务监听端口（按需更换）；try_files ... /index.html 是单页应用路由的必需项，缺了它刷新任意工具页会 404（官方制品内同样有这条适配，官方构建描述实读）；/assets/ 下的文件名带内容哈希、内容变更即改名，可放心 30 天长缓存并标记 immutable；gzip 对 1MB 级主 JS 实测压缩到约四分之一（见 4.8 验证）。

启用站点并停用默认站点：

sudo ln -sf /etc/nginx/sites-available/omnitools.conf /etc/nginx/sites-enabled/omnitools.conf
sudo rm -f /etc/nginx/sites-enabled/default

⚠️ 还有一处必做适配：构建产物里有 4 个 .mjs 扩展名文件（pdf.worker.min-*.mjs、ort.bundle.min-*.mjs 等），Ubuntu 24.04 的 Nginx 默认 MIME 表未收录 .mjs，会按 application/octet-stream 返回，浏览器拒绝将其作为模块脚本执行，导致 PDF 工具与 AI 抠图工具白屏（实测复现，见 8.2 节）。修复方法是按官方制品内同样的做法给 MIME 表补上映射：

sudo sed -i -E "s|(application/javascript\s+)js;|\1js mjs;|" /etc/nginx/mime.types
grep -n "javascript" /etc/nginx/mime.types

实测回显：

8:    application/javascript                           js mjs;

4.8 systemd 托管与整体验证

Nginx 在 Ubuntu 24.04 自带 systemd 单元（nginx.service），直接托管并设开机自启：

sudo nginx -t
sudo systemctl enable --now nginx
sudo systemctl restart nginx
systemctl is-active nginx

实测回显：

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
active

逐项验证（全部实测回显）：

curl -sI http://localhost:8143/ | head -6

HTTP/1.1 200 OK
Server: nginx/1.24.0 (Ubuntu)
Date: Wed, 28 Oct 2026 14:32:30 GMT
Content-Type: text/html
Content-Length: 834
Last-Modified: Wed, 28 Oct 2026 14:32:17 GMT

# 单页应用回退：访问不存在的深层路径应返回入口页而非 404
curl -s -o /dev/null -w "%{http_code} %{content_type}\n" http://localhost:8143/image/compress

200 text/html

# gzip 生效：1.1MB 主 JS 压缩后约 272KB
curl -sI -H "Accept-Encoding: gzip" http://localhost:8143/assets/index-uZupkAMA.js | grep -iE "content-encoding|cache-control"

Cache-Control: max-age=2592000
Cache-Control: public, immutable
Content-Encoding: gzip

# .mjs 修复生效：模块脚本以 application/javascript 返回
curl -sI http://localhost:8143/assets/pdf.worker.min-DRfK9UlP.mjs | grep -i content-type

Content-Type: application/javascript

# 翻译包可达（界面多语言依赖）
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8143/locales/en/translation.json

浏览器打开 http://<服务器IP>:8143，出现 OmniTools 首页（按分类分组的工具卡片）即安装完成；导航栏底部可见 v0.7.0 (5f8f4c7) 版本标识。

4.9 升级、回滚与多版本管理

升级到新版本：拉取新 tag、重建、覆盖站点根（用户无状态，无数据迁移步骤）：

cd /opt/omni-tools
git fetch --tags && git checkout v0.8.0        # 以实际最新 tag 为准；tag 清单用 git tag -l 查看
npm install --no-audit --no-fund
npm run build
sudo cp -r dist/. /var/www/omnitools/
sudo systemctl reload nginx

回滚：git checkout v0.7.0 后重跑 npm install && npm run build && cp 即回到旧版；建议升级前先备份 /var/www/omnitools（tar czf /root/omnitools-0.7.0-backup.tgz -C /var/www omnitools），失败可直接解回。多版本并存：将不同版本构建产物部署到 /var/www/omnitools-0.7.0、/var/www/omnitools-0.8.0，在 Nginx 里以多 server 块（不同端口）或 alias 方式并行提供。

五、方案 B：官方打包制品发行

官方维护着约 28MB 的自包含轻量制品（内建 Nginx 与全部依赖），面向「拉下来就能用」的场景。按官方 README 的 Self-host/Run 一节：获取与启动为三步——拉取 iib0011/omni-tools 官方制品、启动、把宿主机 8080 端口转发到制品内监听的 80 端口；启动后无需额外配置即可访问（转述官方 README，查询日期 2026-10-28）。制品内部与本指南方案 A 的关键适配完全一致：内建 Nginx 已包含 .mjs MIME 修正与 try_files 单页回退（v0.7.0 官方构建描述实读：构建段用 Node.js 20 执行 npm run build，托管段把 dist/ 产物交给内建 Nginx 并打上这两处补丁）。

方案 B 的取舍：优点是零依赖、秒级拉起、升级只换制品；局限是托管进程形态由制品决定，不易并入主机上已有的 Nginx/统一接入层，定制站点配置（改端口、加缓存策略、加访问控制）需按制品内的配置文件方式调整。两种形态的详细对照见 6.2 节。

六、方案对比与选择建议

6.1 对照表

维度	方案 A：源码构建直装	方案 B：官方打包制品
前置依赖	Node.js 20 + git + Nginx（构建期）；仅 Nginx（运行期）	无（制品自包含）
版本	任意 tag 可选（git checkout）	跟随官方发布
监听端口	自定（本指南 8143）	制品内 80，启动时映射宿主端口
站点定制	完全自由（改写 Nginx 配置即可）	受制品内配置约束
与既有接入层合并	天然支持（同一 Nginx 多 server）	需再接一层转发
systemd 管理对象	nginx.service（发行版自带单元）	制品自带的进程管理
离线部署	可（他机构建后拷 dist/）	可（制品整体导入）
升级方式	git checkout + 重建 + 覆盖	换新制品
体积	产物 46MB（源码 9.8MB + node_modules 1.6GB 构建期临时）	约 28MB

6.2 选择建议

服务器已有 Nginx 统一接入、需要自定义端口/缓存/访问控制、或要并入现有 systemd 运维监控体系的，选方案 A；临时起一个内部工具站、不想动任何主机配置、或在内网快速验证的，选方案 B。两方案产物完全一致（同一份 dist/），后续切换无迁移成本。

七、配置说明

方案 A 安装后的配置面由三部分组成，逐项说明如下（构建期参数与多语言配置的完整逐项验证见《OmniTools 0.7.0 配置参数详解》）：

Nginx 站点配置 /etc/nginx/sites-available/omnitools.conf：监听端口、站点根、SPA 回退、静态资源缓存与 gzip，四段配置块与逐项语义见 4.7 节；
MIME 表 /etc/nginx/mime.types：需包含 .mjs → application/javascript 映射（4.7 节 ⚠️ 适配项），缺失时 PDF/AI 抠图工具不可用；
站点根目录 /var/www/omnitools：只读静态内容，无需特定属主权限（Nginx 以 www-data 运行，默认可读）；该目录整体即应用，备份/迁移以目录为单位进行。

应用本身没有服务端配置文件、没有环境变量：构建版本号在 package.json 中声明、构建时注入产物；界面语言由浏览器端 localStorage 的 lang 键决定。这是纯前端架构的直接结果——服务器侧可调的只有托管层。

八、常见问题（FAQ）

8.1 git clone GitHub 报 GnuTLS recv error (-110)

现象（实测原文）：

Cloning into '/opt/omni-tools'...
fatal: unable to access 'https://github.com/iib0011/omni-tools.git/': GnuTLS recv error (-110): The TLS connection was non-properly terminated.

定位：TLS 连接被中途掐断，属网络出口对该链路的干扰，非仓库或参数问题（重试同报错）。解决：走可用代理重试：

export http_proxy=http://192.168.1.62:7897 https_proxy=http://192.168.1.62:7897
git clone --branch v0.7.0 --depth 1 https://github.com/iib0011/omni-tools.git /opt/omni-tools

实测代理下克隆成功（回显见 4.3 节）。当前渠道状态（2026-10-28 实测）：GitHub 直连不可用，代理 192.168.1.62:7897 可用；npm 走代理同速可用。

8.2 浏览器打开 PDF/AI 抠图工具白屏，控制台报模块脚本 MIME 错误

现象：站点可访问、多数工具正常，但 PDF 类与 AI 抠图类工具一直加载不出；浏览器控制台提示以 application/octet-stream 返回的模块脚本被拒绝执行。定位（服务器侧复现实测）：

curl -sI http://localhost:8143/assets/pdf.worker.min-DRfK9UlP.mjs | grep -i content-type

Content-Type: application/octet-stream

根因：构建产物含 4 个 .mjs 文件，Ubuntu 24.04 的 /etc/nginx/mime.types 默认只映射 js 不映射 mjs，Nginx 按二进制流返回，浏览器对模块脚本执行严格的 MIME 校验直接拒绝。解决：按 4.7 节 ⚠️ 的 sed 命令补上映射并 reload，复测：

Content-Type: application/javascript

官方打包制品内已内置同样修正（v0.7.0 官方构建描述实读），方案 A 自建托管时必须自己补上。

8.3 npm install 或 npm run build 很慢/卡住

依赖规模大（1148 包、node_modules 约 1.6GB），跨境网络下易超时。实测走代理后 npm install 32 秒完成、npm run build 15.65 秒完成（回显见 4.4/4.5 节）。做法：

export http_proxy=http://192.168.1.62:7897 https_proxy=http://192.168.1.62:7897
npm install --no-audit --no-fund

⚠️ 网络说明（2026-10-28 实测）：npm 官方源直连缓慢，走代理稳定可用；构建机无法走代理时，可在有网机器构建后仅拷贝 dist/ 到目标服务器（运行期不需要 node_modules）。

8.4 刷新或直接访问工具页返回 404

根因：Nginx 站点缺 try_files $uri $uri/ /index.html; 回退（4.7 节配置块第一段），单页应用路由由前端接管，深层路径必须回退到入口页。补上配置后 sudo nginx -t && sudo systemctl reload nginx，实测 /image/compress 返回 200 text/html。

九、卸载与清理

按安装的逆序逐项删除：

sudo systemctl disable --now nginx      # 若 Nginx 仅为此应用部署，停用并取消自启
sudo rm -f /etc/nginx/sites-enabled/omnitools.conf /etc/nginx/sites-available/omnitools.conf
sudo rm -rf /var/www/omnitools           # 站点产物
sudo rm -rf /opt/omni-tools              # 源码与构建目录（含 1.6GB node_modules）
sudo apt-get purge -y nodejs             # 仅在无其他 Node.js 使用方时执行
sudo sed -i -E "s|(application/javascript\s+)js mjs;|\1js;|" /etc/nginx/mime.types   # 还原 MIME 表
sudo nginx -t && sudo systemctl reload nginx

确认清理干净：

ss -ltn | grep 8143; ls /var/www/omnitools /opt/omni-tools 2>&1

实测回显（端口无监听、目录不存在）：

ls: cannot access '/var/www/omnitools': No such file or directory
ls: cannot access '/opt/omni-tools': No such file or directory

十、参考链接

官方仓库与 README（Self-host/Run 一节，查询日期 2026-10-28）：https://github.com/iib0011/omni-tools
v0.7.0 源码与官方构建描述（托管适配依据）：https://github.com/iib0011/omni-tools/blob/v0.7.0/Dockerfile
Releases 页（版本时间线）：https://github.com/iib0011/omni-tools/releases
NodeSource Node.js 20 安装脚本：https://deb.nodesource.com/setup_20.x
Nginx try_files 文档：https://nginx.org/en/docs/http/ngx_http_core_module.html#try_files
本专栏系列篇章：组件定位与同类对比见《OmniTools 介绍与选型指南》，构建与托管参数逐项验证见《OmniTools 0.7.0 配置参数详解》，构建测试与维护命令见《OmniTools 0.7.0 常用 CLI 命令与工具详解》。