ghcr.io/sharevb/it-tools:2026.9.27

容器镜像重要变更

由于基础镜像已更换为 nginx-unpriviledged，容器现在默认监听端口为 8080 而非 80。因此您需要更新端口映射配置，例如将原有映射 8080:80 修改为 8080:8080。

您可以通过环境变量 PORT 覆盖容器监听端口，对应 Docker 启动参数为 -e PORT=8888。

您还可以通过环境变量 BASE_URL 配置应用在子路径下提供服务，对应 Docker 启动参数为 -e BASE_URL=/it-tools/，无需重新构建镜像，详情请参考https://github.com/sharevb/it-tools/blob/master/docs/host-in-subfolder.md文档。

如果需要容器支持监听 IPv6 地址，需先启用系统 IPv6 支持，参考文档：[***]。您也可以通过 Docker 参数 -v "./nginx.conf:/etc/nginx/templates/default.conf.template" 挂载自定义的 nginx.conf 配置文件（需移除配置中的 listen [::]:8080; 语句）实现 IPv6 监听。

Proxmox 安装

在 Proxmox VE Shell 中执行以下命令：

bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/alpine-it-tools.sh)"

构建要求

构建本项目仅需约 8GB 内存。在 4 核设备上实测，pnpm build 峰值内存占用约为 6.5GB，可在 Node 默认堆内存配置下完成构建——大部分构建工作由 rolldown 以 Rust 实现的逻辑执行，而非运行在 JavaScript 堆内存中。

欢迎提交 PR

特别欢迎针对 UI 优化和翻译相关的贡献，其他类型的贡献也同样欢迎。 如果您希望支持该 IT Tools 分支项目，可以为开发者买杯咖啡。

推荐启用 HTTPS

部分工具（例如 PGP 加密）依赖仅能在 HTTPS/SSL 环境中使用的 Web*** API。此外，如果要使用 PWA 功能，也必须启用 HTTPS。 因此即使是内部部署场景，也建议您通过 DNS Challenge 方式使用 Let's Encrypt 启用 HTTPS。 相关 DNS Challenge 参考文档：

• [***]
• https://doc.traefik.io/traefik/user-guides/docker-compose/acme-dns/
• [] CyberPanel 相关参考文档：[]

在线访问体验变更

您可以访问以下地址查看本分支的最新改动：https://sharevb-it-tools.vercel.app/ 或 https://sharevb.github.io/it-tools/

在上游主分支更新合并前，您可以使用本项目提供的镜像获得包含本分支及其他贡献者 PR 的最新 IT Tools 版本，直接在 docker-compose 或 quadlet 配置中引用即可。

• 本仓库每个分支推送都会触发 GitHub Action 自动构建，生成的镜像可在镜像仓库页面查看。 （感谢 gitmotion 提供本分叉 README 的参考模板）

贡献者

向所有已作出贡献的开发者致以诚挚感谢！

Windows 开发环境配置

推荐在 Windows 环境下搭配 VSCode 使用 WSL2 进行开发。由于部分依赖存在兼容性问题，直接在 Windows 原生环境中开发可能会遇到异常。

新增功能

• 合并了几乎所有 IT Tools 的上游工具 PR，其中包含 192 项本分支独立开发的工具
• 解决了原 IT Tools 项目中 95% 的已提 Issue
• 支持全界面多语言翻译（由 Google 翻译生成）
• 新增大量全新工具
• 大量 Bug 修复与体验增强
• 多项 Docker 镜像定制化功能，详见下文

容器镜像

GitHub Container Registry 地址：ghcr.io/sharevb/it-tools:latest

Docker Hub 地址：sharevb/it-tools:latest

docker run --pull always --restart unless-stopped -p 8080:8080 sharevb/it-tools:latest

其他可用镜像标签：latest-en（仅包含英文语言包版本）

容器构建阶段会预压缩 dist/assets 目录下的 JavaScript、CSS 和 WebAssembly 文件。Nginx 会在客户端支持 gzip 时直接提供对应的 .gz 压缩文件（包括经过反向代理转发的请求场景），否则提供原始文件。该压缩过程在构建时仅执行一次，无需每次请求时实时压缩。HTML 文件不会被预压缩，以保证运行时的 BASE_URL 重写逻辑可以正常工作。

在 Docker Compose 文件中使用

services:
  it-tools:
    container_name: it-tools
    image: sharevb/it-tools:latest
    pull_policy: always
    restart: unless-stopped
    ports:
      - 8080:8080

在 Podman Quadlet 文件中使用

[Unit]
Description=IT Tools container
After=network-online.target

[Container]
AutoUpdate=registry
Image=ghcr.io/sharevb/it-tools:latest
PublishPort=8080:8080
Label=io.containers.autoupdate=registry

[Install]
WantedBy=multi-user.target default.target

[Service]
Restart=always

搭配自托管配套 Docker 服务使用

部分工具依赖额外的 Docker 服务运行：HTTPS/DNS 工具/网络 Ping 工具、HTML 转 PDF、Docker 镜像下载、多链接批量下载、短链接解析以及 TCP/UDP 端口测试工具。 完整部署示例请参考：docker-with-services

过滤工具列表与添加首页自定义内容

您可以通过将自定义 home.custom.md 文件挂载到容器内路径 /usr/share/nginx/html，在首页添加自定义内容。

您也可以通过将 tools-filter.json 配置文件挂载到容器内路径 /usr/share/nginx/html 实现可用工具的过滤。配置支持以下正则过滤规则：

{
  "excludeCategoryFilterRegex": "",
  "includeCategoryFilterRegex": "",
  "excludeToolsFilterRegex": "",
  "includeToolsFilterRegex": ""
}

分类过滤规则匹配英文分类名称，工具过滤规则匹配工具的访问路径/URL。 完整示例请参考：docker-tools-filter-and-home-content

添加自定义外部工具

您可以通过将 external-tools.json 配置文件挂载到容器内路径 /usr/share/nginx/html，添加自定义外部工具（支持链接跳转或 Markdown 内容渲染），配置结构如下：

[
  {
    "name": "GitHub",
    "path": "/github",
    "description": "Link to Github",
    "keywords": ["github"],
    "category": "Links",
    "href": "https://github.com"
  },
  {
    "name": "Some text",
    "path": "/some-text",
    "description": "Some description",
    "keywords": ["some"],
    "category": "Links",
    "markdownContent": "Some useful **text**\n\nin *markdown*"
  }
]

完整示例请参考：docker-tools-filter-and-home-content

运行时设置工具默认参数与界面默认语言

完整配置示例请参考：docker-with-services。

您可以通过将 tools-settings.json 配置文件挂载到容器内路径 /usr/share/nginx/html，设置工具的默认参数。 该 JSON 文件为两级结构，第一级对应工具名称，第二级对应参数名称：

{
  "regex-tester": {
    "multi": true,
    "regex": "some regex",
    "global": false
  }
}

您可以在项目源代码的 src/tools 子目录下找到所有工具的名称和参数名称，示例参数定义代码片段：

const global = useQueryParamOrStorage({ storageName: 'regex-tester:g', name: 'global', defaultValue: true });

{
  "regex-tester": {
    "global": false
  }
}

• 针对 const value = useQueryParam({ tool: 'barcode-gen', name: 'text', defaultValue: '123456789' }); 的配置示例： const value = useQueryParam({ tool: 'barcode-gen', name: 'text', defaultValue: '123456789' });

{
  "barcode-gen": {
    "text": "4356"
  }
}

• 针对 const width = useITStorage('ascii-text-drawer:width', 80); 的配置示例： const width = useITStorage('ascii-text-drawer:width', 80);

{
  "ascii-text-drawer": {
    "width": 80
  }
}

如需定义默认 UI 语言，请在 JSON 中添加 default_locale 键：

default_locale

{
  "default_locale": "fr"
}

使用自定义默认语言构建镜像

docker build -t it-tools-fr --build-arg VITE_LANGUAGE=fr .
docker run -d --name it-tools-fr --restart unless-stopped -p 8080:8080 it-tools-fr

在子路径（/it-tools/）下托管应用

/it-tools/ 容器会从你通过 BASE_URL 指定的任意路径提供应用服务，相关配置不会预先固化在镜像中，因此常规的 latest 镜像即可适配任意子路径，无需重新构建，也不需要使用子路径专属标签：

BASE_URL latest

services:
  it-tools:
    image: ghcr.io/sharevb/it-tools:latest
    restart: unless-stopped
    environment:
      BASE_URL: /it-tools/
    ports:
      - 8080:8080

也可使用命令：docker run -d --name it-tools -e BASE_URL=/it-tools/ -p 8080:8080 ghcr.io/sharevb/it-tools:latest。

docker run -d --name it-tools -e BASE_URL=/it-tools/ -p 8080:8080 ghcr.io/sharevb/it-tools:latest BASE_URL 支持 it-tools、/it-tools 和 /it-tools/ 三种格式，默认值为 /。

BASE_URL it-tools /it-tools /it-tools/ 你仍需在前端配置反向代理（例如 Nginx Proxy Manager、Traefik、caddy 等），将 /it-tools/ 路径的请求转发至容器。无论反向代理是在转发前去除前缀（proxy_pass http://it-tools:8080/;）还是保留完整前缀直接转发（proxy_pass http://it-tools:8080;），容器均可正常处理。

/it-tools/ proxy_pass http://it-tools:8080/; proxy_pass http://it-tools:8080; 仅在反向代理配置去除前缀的场景下有一点注意事项：不带尾部斜杠的 /it-tools 路径无法到达容器，你需要在代理侧配置重定向，参考示例中的 location /it-tools { return 301 /it-tools/; }。如果代理直接转发完整前缀，该重定向操作会由容器自动完成。

/it-tools location /it-tools { return 301 /it-tools/; } 你可以参考示例中的 docker-compose.yml 和 nginx.conf 配置文件运行演示环境：

git clone https://github.com/sharevb/it-tools
cd it-tools/docker-subfolder-sample/
docker compose up

随后访问地址 http://localhost/it-tools/ 即可使用应用。

以下两点需要留意：

• 使用 --build-arg BASE_URL=/it-tools/ 方式构建镜像依然有效，但该参数现在仅会修改镜像的默认配置，运行时设置的环境变量优先级更高。 --build-arg BASE_URL=/it-tools/

[!IMPORTANT] 在只读根文件系统环境中，配置模板无法在容器启动时重新渲染，因此除非将 /etc/nginx/conf.d 设置为可写（通过挂载 tmpfs 或 emptyDir 实现），否则 BASE_URL（以及 PORT）配置不会生效，相关提示信息会记录在容器日志中。 BASE_URL PORT /etc/nginx/conf.d

使用自定义子路径构建

• 执行 BASE_URL="/it-tools/" pnpm build 构建项目 BASE_URL="/it-tools/" pnpm build
• 将生成的 dist 文件夹重命名为 it-tools，即可通过地址 https://your-domain.com/it-tools 提供服务 dist it-tools https://your-domain.com/it-tools

为 GitHub Pages 构建部署

• 在你 Fork 的仓库中，进入 Settings

Pages 页面，选择 GitHub Actions 作为部署源，启用 GitHub Pages 构建与部署选项

• 将以下 GitHub Actions 配置添加到你的仓库中：https://github.com/sharevb/it-tools/tree/chore/all-my-stuffs/.github/workflows/sharevb-github-pages-publish.yml

添加身份认证

假设你已经通过反向代理托管 it-tools，你可以在反向代理侧配置 forward-auth 规则，强制访问者完成身份认证。

• 提供了 Nginx 官方配置指南，也可获取其他反向代理环境的配置说明
• Nginx Proxy Manager 分步配置指南 （感谢 @jogerj 贡献内容）

部署为 LXC 容器

在 Proxmox VE 环境中，你可以直接使用该 Docker 镜像创建 LXC 容器：

sudo lxc-create -n sharevb-it-tools -t oci -- --url docker://ghcr.io/sharevb/it-tools:latest

贡献指南

推荐的 IDE 配置

如需在 Windows 的 WSL2 环境中安装 VSCode，请参考官方文档：[***]

VSCode 需要安装以下扩展：

• Volar（请先禁用 Vetur）
• TypeScript Vue Plugin (Volar)
• Oxc（包含 oxlint + oxfmt）
• i18n Ally

并配置以下设置项：

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "oxc.oxc-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.oxc": "always"
  },
  "i18n-ally.localesPaths": ["locales", "src/tools/*/locales"],
  "i18n-ally.keystyle": "nested"
}

TS 中 .vue 导入的类型支持

.vue 文件默认无法被 TypeScript 处理类型信息，因此我们使用 vue-tsc CLI 替代 tsc 完成类型检查。在编辑器中，需要安装 TypeScript Vue Plugin (Volar) 才能让 TypeScript 语言服务识别 .vue 类型。

如果你觉得独立的 TypeScript 插件运行速度不够快，Volar 还提供了性能更优的「接管模式（Take Over Mode）」，可通过以下步骤启用：

1. 从 VSCode 命令面板运行「Extensions: Show Built-in Extensions」 Extensions: Show Built-in Extensions
2. 找到「TypeScript and JavaScript Language Features」，右键点击选择「Disable (Workspace)」 TypeScript and JavaScript Language Features Disable (Workspace)
3. 从命令面板运行「Developer: Reload Window」重启 VSCode 窗口 Developer: Reload Window

项目初始化

pnpm install --ignore-scripts

开发环境编译与热重载

pnpm dev

生产环境类型检查、编译与压缩

pnpm build

使用 Vitest 运行单元测试

pnpm test:unit

使用 Playwright 运行端到端测试

Playwright 会自行启动 pnpm preview 服务，因此需要先完成项目构建：

pnpm preview

pnpm build
pnpm test:e2e

如果要直接对接开发服务进行调试，可保持 pnpm dev 运行状态，让测试直接指向开发服务，此时 Playwright 不会自行启动预览服务：

pnpm dev

E2E_BASE_URL=http://localhost:5173 pnpm test:e2e

开发服务采用按需编译路由的模式，首次冷启动运行测试时可能会因响应超时导致断言失败，你可以提前打开一次应用页面，或者重新运行测试即可。