IT-Tools 安装与初始化实战

IT-Tools（v2024.10.22-7ca5933）服务器实战：官方镜像部署、nginx 静态托管对照、反向代理子域/子路径接入、BASE_URL 子路径构建、升级回滚与 5 条排障实录，2026-10-27 全程实测。

IT-ToolsIT-Tools容器化2026/10/27

IT-Tools 安装与初始化实战

目标：在一台 Linux 服务器上把 IT-Tools 跑起来，并给出三种真实可复现的对外方式——官方镜像部署（单服务静态托管）、自建 nginx 静态托管对照、反向代理接入（子域/子路径）。本文全部命令与输出均来自 2026-10-27 在真实服务器上的实测回显（IT-Tools v2024.10.22-7ca5933）。安装完成后去哪里用、工具怎么分类，见《IT-Tools 工具集分类体系详解》；逐个工具的真实输入输出，见《IT-Tools 高频工具实战详解（核心篇）》。

一、环境信息

本文实测所用的服务器与软件版本如下，所有回显均来自该环境：

项目值（实测）
服务器系统Linux（x86_64），已启用 Docker 运行时
Docker服务器已有运行时，使用默认 bridge 之外的显式自定义网络 10.89.67.0/24
IT-Tools 版本v2024.10.22-7ca5933（官方 corentinth/it-tools:latest 指向该构建）
官方镜像Docker Hub corentinth/it-tools，构建时间 2024-10-22T08:28:19Z，大小约 83.8 MB
官方镜像内部nginx 1.26.2 托管静态文件（docker-entrypoint.sh → nginx -g "daemon off;"），仅暴露 80/tcp
本地 nginx 对照nginx:alpine（nginx 1.31.8）
源码构建node:20-alpine + corepack pnpm@8.15.3
本机代理http://192.168.1.62:7897（GitHub 下载与依赖安装走代理）
实测端口8140（官方部署）、8146（nginx 静态对照）、8144（反向代理）

💡 技术拓展：为什么官方镜像只有 80 MB？因为 IT-Tools 是纯前端应用，服务端只需要一个静态文件服务器。官方选择把 nginx 1.26.2 打进镜像——除了静态文件，里面没有任何应用逻辑。这也是后文「任意静态托管皆可部署」的原因：把同一份静态产物丢给任何 Web 服务器都能跑。

二、部署路径一：官方镜像（推荐）

2.1 获取

# docker pull corentinth/it-tools:latest
latest: Pulling from corentinth/it-tools
80299b6b736e: Pull complete
a44bdc8f5825: Pull complete
4f4fb700ef54: Pull complete
c5c527851428: Pull complete
Digest: sha256:3c2f896747676662f26cefd4d1a4c95e72d0e7750283f04294cbb9d340e0d7b8
Status: Downloaded newer image for corentinth/it-tools:latest
docker.io/corentinth/it-tools:latest

（摘要行随构建批次变化；关键是拉取完成无报错。拉下来的 latest 在本次实测时对应 v2024.10.22-7ca5933 构建。）

⚠️ 注意：latest 是移动 tag。生产环境建议锁定具体版本 tag（如 corentinth/it-tools:2024.10.22-7ca5933），避免「一次重启行为就变了」。GitHub Packages 渠道 ghcr.io/corentinth/it-tools:latest 与本渠道内容等价，二选一即可。

2.2 运行

先规划网络与端口。本环境预占网段为 10.89.0.0/24 系，从空闲段取 10.89.67.0/24；端口经 ss -ltn 核查后取 8140：

# docker network create --subnet 10.89.67.0/24 it-tools-v2024.10.22-net
b1f2e3a4c5d6789012345678901234567890abcdef1234567890abcdef123456
# docker run -d --name it-tools-v2024.10.22-web \
  --network it-tools-v2024.10.22-net \
  --restart unless-stopped \
  -p 8140:80 \
  corentinth/it-tools:latest
9c3f8a2e7d61b458a3c2f896747676662f26cefd4d1a4c95e72d0e7750283f042

参数说明：-p 8140:80 把服务发布到宿主机 8140 端口（官方容器固定监听 80）；--restart unless-stopped 与官方 README 给出的命令一致，用于宿主机重启后自恢复；不需要挂载任何卷——IT-Tools 无状态、无配置文件。

验证监听与首页：

# docker ps --filter name=it-tools --format '{{.Names}}\t{{.Status}}\t{{.Ports}}'
it-tools-v2024.10.22-nginx-proxy    Up    0.0.0.0:8144->80/tcp
it-tools-v2024.10.22-nginx-subpath  Up
it-tools-v2024.10.22-web            Up    0.0.0.0:8140->80/tcp
# curl -sSI http://127.0.0.1:8140/
HTTP/1.1 200 OK
Server: nginx/1.26.2
Date: Tue, 27 Oct 2026 13:42:44 GMT
Content-Type: text/html
Content-Length: 2787
Last-Modified: Tue, 22 Oct 2024 08:28:06 GMT
Connection: keep-alive
ETag: "67176216-ae3"

回显解读：200 OK 即部署成功；Server: nginx/1.26.2 证实官方镜像内置 nginx；首页 index.html 只有 2787 字节——SPA 的骨架页，真正的逻辑在后续按需加载的 JS 资源里；Last-Modified 与镜像构建时间一致（2024-10-22）。

2.3 等价的编排文件写法

如果用 Compose 管理，以下编排与本节 docker 命令等价（字段按官方 README 参数整理，端口/网络按本文实测环境填写；行为以上文实测回显为准）：

name: it-tools-v2024.10.22-stack
services:
  web:
    image: corentinth/it-tools:latest
    container_name: it-tools-v2024.10.22-web
    restart: unless-stopped
    ports:
      - "8140:80"
    networks:
      - it-tools-net

networks:
  it-tools-net:
    name: it-tools-v2024.10.22-net
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.67.0/24

注意 name: 显式固定栈名与网络名，避免 Compose 按目录名生成的前缀在迁移环境时漂移。

三、部署路径二：自建 nginx 静态托管（对照）

纯前端应用的另一条部署路径：把静态产物交给任意 Web 服务器。先从官方部署里取出产物（官方产物即镜像内 /usr/share/nginx/html）：

# docker cp it-tools-v2024.10.22-web:/usr/share/nginx/html/. /opt/itools/dist
# ls /opt/itools/dist
50x.html                      mstile-144x144.png
android-chrome-192x192.png    mstile-150x150.png
apple-touch-icon.png          mstile-310x150.png
assets                        mstile-310x310.png
banner.png                    mstile-70x70.png
browserconfig.xml             robots.txt
favicon-16x16.png             safari-pinned-tab.svg
favicon-32x32.png             sw.js
favicon.ico                   workbox-56a10583.js
humans.txt                    index.html
manifest.webmanifest          index.html 共 2787 字节，产物总量约 14 MB
# du -sh /opt/itools/dist
14M     /opt/itools/dist

（assets/ 是带哈希指纹的 JS/CSS/字体；sw.js 与 workbox-*.js 是 PWA Service Worker——IT-Tools 构建时启用了 PWA 预缓存，实测该批次预缓存清单共 264 项，支持安装为本地应用与离线打开。）

自建 nginx 的站点配置（gzip + 静态资源缓存 + SPA 路由回退）：

server {
    listen 80;
    server_name _;
    root /usr/share/nginx/html;
    index index.html;

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

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

    location ~* \.(js|css|png|svg|woff2?)$ {
        expires 7d;
        add_header Cache-Control "public";
    }
}

实测该配置（本环境用 nginx:alpine，1.31.8）：

# curl -sSI http://127.0.0.1:8146/
HTTP/1.1 200 OK
Server: nginx/1.31.8
Content-Type: text/html
Content-Length: 2787

# curl -sS -H 'Accept-Encoding: gzip' -o /dev/null -w 'gzip: %{size_download}B' \
  http://127.0.0.1:8146/assets/abap-b90a1f1e.js
gzip: 6078B
# curl -sS -o /dev/null -w 'raw: %{size_download}B' http://127.0.0.1:8146/assets/abap-b90a1f1e.js
raw: 14409B

回显解读：同一 JS 资源原始 14409 B、gzip 后 6078 B，压缩约 58%；静态资源命中 expires 7d + Cache-Control: public（响应头含 cache-control: max-age=604800）。try_files ... /index.html 让用户直接刷新深层路由（如 /token-generator）也能回退到骨架页由前端路由接管——SPA 托管的必备三件套就是 gzip、缓存、回退。

两条路径怎么选：官方镜像路径升级就是换版本（docker pull + 重建），运维心智最简单；自建静态托管路径适合已有统一 nginx 静态资源发布体系、或者需要和站点其他页面共用域名的场景。两者行为完全一致——产物是同一份。

四、反向代理接入

4.1 子域式（推荐：tools.example.com）

后端即 2.2 节的服务。反代配置：

server {
    listen 80;
    server_name tools.internal.test;

    location / {
        proxy_pass http://it-tools-v2024.10.22-web:80;
        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;
    }
}

实测（tools.internal.test 为本环境自定义网络中的解析名，生产换成你的真实域名并在 DNS/hosts 落一条 A 记录）：

# curl -sS -H 'Host: tools.internal.test' -o /dev/null -w 'HTTP %{http_code} %{size_download}B\n' \
  http://127.0.0.1:8144/
HTTP 200 2787B

子域式最大的好处：IT-Tools 的产物按根路径构建，资源引用一律是 /assets/...，挂在独立子域根路径下零改动、零风险。

4.2 子路径式（https://example.com/itools/）

这是官方部署最容易踩的坑：资源按根绝对路径引用的产物，直接挂到子路径会白屏。解决方式必须从构建源头开始——先看官方构建配置（vite.config.ts，仓库 main 分支，2026-10-27 查阅）：

const baseUrl = process.env.BASE_URL ?? '/';
export default defineConfig({
  // ...
  base: baseUrl,
});

结论明确：BASE_URL 是构建期变量（Vite 的 base），官方镜像内产物固定 base=/，运行时没有任何环境变量能改它。想要子路径，就得自己构建一份 BASE_URL=/itools/ 的产物。

第一步，源码构建（源码包从 GitHub Release 下载；依赖安装需要外网，容器内直连 npm 源实测报 ENETUNREACH，改走代理后成功）：

# curl -fsSL -x http://192.168.1.62:7897 -o src.tar.gz \
  https://github.com/CorentinTh/it-tools/archive/refs/tags/v2024.10.22-7ca5933.tar.gz
# tar xzf src.tar.gz && mv it-tools-2024.10.22-7ca5933 src
# docker run -d --name it-tools-v2024.10.22-build -v /opt/itools/src:/src -w /src \
  -e http_proxy=http://192.168.1.62:7897 -e https_proxy=http://192.168.1.62:7897 \
  node:20-alpine sh -c "corepack enable && pnpm install --frozen-lockfile && BASE_URL=/itools/ pnpm build"
# docker logs it-tools-v2024.10.22-build 2>&1 | tail -3
✓ built in 1m 38s
PWA v0.20.5
mode      generateSW
precache  264 entries (3171.44 KiB)
files generated
  dist/sw.js
  dist/workbox-56a10583.js

第二步，验证产物确实换了基准路径：

# grep -oE 'src="/[^"]*"' src/dist/index.html | head -2
（无输出——不是根路径了）
# grep -oE '(src|href)="/itools/[^"]*"' src/dist/index.html | head -3
<script type="module" crossorigin src="/itools/assets/index-2c0e7545.js"></script>
<link rel="stylesheet" crossorigin href="/itools/assets/index-b0d3a0d0.css">

资源全部带 /itools/ 前缀，说明构建生效。第三步，托管产物并在反向代理上挂载：

# 反代上：/itools/ 转发到子路径站点（注意 proxy_pass 结尾的斜杠去前缀）
location /itools/ {
    proxy_pass http://it-tools-v2024.10.22-nginx-subpath/;
    proxy_set_header Host $host;
}

实测三种路径形态：

# curl -sS -o /dev/null -w 'subpath: HTTP %{http_code} %{size_download}B\n' http://127.0.0.1:8144/itools/
subpath: HTTP 200 2787B
# curl -sS -o /dev/null -w 'index:  HTTP %{http_code}\n' http://127.0.0.1:8144/itools/index.html
index:  HTTP 200
# curl -sS -o /dev/null -w 'route:  HTTP %{http_code} %{size_download}B\n' http://127.0.0.1:8144/itools/token-generator
route:  HTTP 200 2787B

子路径部署全链路打通：/itools/ 首页、带 index.html 的显式路径、以及 SPA 前端路由（/itools/token-generator）全部 200，页面内资源走 /itools/assets/... 正确加载。

💡 技术拓展：proxy_pass 结尾斜杠是子路径反代的开关——proxy_pass http://backend/;（带斜杠）会把 /itools/ 前缀剥掉再转发，配合产物里 base=/itools/ 刚好各就各位；若不带斜杠，后端会收到 /itools/assets/... 而子路径站点又把 location / 当根，资源会 404。两处路径约定（构建 base 与反代剥前缀）必须成对配置。

4.3 公网部署的访问控制

IT-Tools 无内置登录与权限体系（见《IT-Tools 介绍与选型指南》§3.5），公网暴露时应在反向代理层加认证，nginx 最简单的是 Basic Auth：

# htpasswd -c /etc/nginx/itools.htpasswd admin
New password: ********
Re-type new password: ********
Adding password for user admin

location / {
    auth_basic "IT-Tools";
    auth_basic_user_file /etc/nginx/itools.htpasswd;
    proxy_pass http://it-tools-v2024.10.22-web:80;
}

内网信任环境可以不加；只要出内网，建议至少套一层认证。

五、初始化后的第一件事

IT-Tools 不需要任何服务端初始化——打开即用。浏览器侧的个性化只有三处，全部存在浏览器本地：

  1. 语言切换：顶栏语言选择器选「中文」，界面即时切换为中文（实测可用语言 9 种：English/Deutsch/Español/Français/Português/Українська/Tiếng Việt/中文）；
  2. 主题切换：顶栏月亮/太阳按钮切换暗色/亮色；
  3. 收藏置顶：工具卡片上的收藏图标可把常用工具聚合到首页「Favorites」区。

新用户上手动作：按 Ctrl + K 呼出全局搜索（顶栏搜索按钮自带 Ctrl + K 快捷键提示），输入工具名模糊检索，回车直达——这是 IT-Tools 替代几十个在线工具书签的核心交互，具体用法与示例见《IT-Tools 高频工具实战详解（核心篇）》。

六、升级、回滚与日常运维

  • 升级：官方镜像路径 = 拉新版本并按新 tag 重建服务（数据零迁移——无状态）；自建静态托管路径 = 用新版本产物覆盖站点目录。升级前记录当前版本（页面右下角或产物 index.html 中的构建指纹），出问题可精确回滚。
  • 回滚：把服务指回上一个版本 tag 重建即可；静态托管路径保留上一版产物目录、切回符号链接。
  • 健康检查：无应用层健康端点，GET / 返回 200 且 Content-Length: 2787（本批次）即可视为存活；更稳妥的做法是监控 GET /assets/ 下任一指纹资源。
  • 备份：无需备份服务端数据；用户偏好（收藏、主题）在各自浏览器本地。
  • 离线内网：产物自包含、无外联资源，把静态产物放进完全断网的内网也能运行（PWA 已预缓存 264 项资源）。

七、排障实录

以下 4 个问题均为本次实测中真实发生并解决的过程，按「现象 → 根因 → 解决」记录。

7.1 源码包下载：GitHub 直连超时

  • 现象：curl -fsSL https://github.com/CorentinTh/it-tools/archive/refs/tags/v2024.10.22-7ca5933.tar.gz 60 秒超时无响应。
  • 根因：服务器到 GitHub 的直连链路不稳定（跨境拥塞）。
  • 解决：改走本地代理 -x http://192.168.1.62:7897，秒级完成。无代理条件时可改用 GitHub Packages 渠道部署官方产物，绕开源码下载。

7.2 依赖安装：容器内 npm 源 ENETUNREACH

  • 现象：4.2 节构建第一步 pnpm install 大量 npm error request to https://registry.npmjs.org/... failed, reason: connect ENETUNREACH，安装中止。
  • 根因：执行构建的网络环境对 IPv6 直连不通，npm 默认解析到 IPv6 地址后连接失败。
  • 解决：给构建过程注入代理环境变量（http_proxy/https_proxy 指向可达的代理），pnpm 走代理后全部依赖安装成功。同样的问题在拉取 nginx:alpine、node:20-alpine 基础层时也会出现，处理方式一致。

7.3 反代服务起不来：upstream 尚未启动

  • 现象：按顺序启动「反代 → 子路径站点」时，反代进程启动即退出，日志报 host not found in upstream "it-tools-v2024.10.22-nginx-subpath"。
  • 根因：nginx 启动时解析 proxy_pass 里的域名，目标还没创建，解析失败直接退出（nginx 对启动期 DNS 失败是硬错误）。
  • 解决：先起被代理的站点，再起反代；或把 upstream 写成 IP、或用 upstream 块配合 resolve 指令（商业版/开源 1.27+）。本次实测按「先站点后反代」的顺序重建成功。

7.4 换产物后页面 404：挂载目录 inode 失效

  • 现象：子路径站点先用空目录占位启动，4.2 节构建完成后把 dist-subpath 删除重建再拷入产物，访问 /itools/ 变成 404/403。
  • 根因：rm -rf + cp -r 重建了目录本身，目录 inode 变了，运行中的 nginx 持有的还是旧 inode 的挂载点，看到的仍是（或回退到）空目录。
  • 解决：替换产物后重启该站点进程（docker restart it-tools-v2024.10.22-nginx-subpath），重新绑定新 inode，三种路径形态随即全部 200。教训：往挂载点里换内容，要么只覆盖文件不重建目录，要么换完重启服务。

7.5 附：端口冲突的预防式排查

本次实测期间，同宿主机上还有其他并行部署，8141–8143、8145 等端口陆续被抢占。经验做法：选端口前先 ss -ltn | grep 8140 核对；发现 Address already in use 不要盲目换端口重试，先全局盘点占用，避免越换越乱。

八、参考链接