IT-Tools 部署教程：自建 JSON、编码与时间戳工具箱

开始前

排查接口时要格式化 JSON，检查请求时要解码 URL，整理配置时又要换算时间戳。每次搜索一个在线工具，常常打开的是不同网站，也很难判断粘贴进去的内容会经过哪些服务。

IT-Tools 把这类小工具放在一个界面里，可以用 Docker 部署到自己的 VPS。它适合个人和小团队作为固定入口，但自托管地址并不自动保证所有输入都不会外发。要处理敏感材料，仍需了解具体工具实现、浏览器扩展和页面加载行为。

部署前先确认 VPS 的磁盘、内存和公网访问条件，也可以查看雨云云服务器；注册时填写优惠码 `KuZhuJi`。

常用工具与适用场景

IT-Tools 项目面向开发与 IT 工作提供一组工具。安装前可以在演示站用虚构文本查看自己需要的功能，再建立私人实例。选型时把“经常使用”和“偶尔好奇”分开，首页快捷方式优先留给日常工作。

例如维护接口的人，常用 JSON 处理、编码转换、时间相关工具；维护网站的人，常用 URL、文本和哈希工具。团队还可以记录几个常见排错样本，用同一份输入验证输出，减少“不同人打开了不同工具”的沟通成本。

这些工具适合检查和转换，不能替代应用本身的校验。JSON 格式化成功只能说明输入满足相应解析条件；一个 JWT 能被解码，不能证明签名正确、令牌有效或授权充足。

也不要因为工具箱能计算哈希，就把它当成密码存储方案。文件完整性检查、签名验证和密码派生有不同目的，具体操作应依据项目所用的协议或安全要求。

一个容器就能开始

VPS 上准备好 Docker Engine 与 Compose 插件。选一个不会与现有服务冲突的回环端口，例如8088：

mkdir -p ~/it-tools
cd ~/it-tools

保存 `compose.yaml`：

services:
  it-tools:
    image: ghcr.io/corentinth/it-tools:latest
    ports:
      - "127.0.0.1:8088:80"
    restart: unless-stopped

官方也提供 Docker Hub 镜像，示例采用 GitHub 容器仓库入口。不要把不同维护者发布的同名镜像当成完全一样的构建。先验证所选镜像来源与版本，再固定标签或摘要。

docker compose config --quiet
docker compose up -d
docker compose logs --tail=80 it-tools
ssh -L 18088:127.0.0.1:8088 user@your-server

浏览器打开 `http://127.0.0.1:18088`。这一类工具页不必先引入数据库、缓存服务和宿主机目录，基础部署配置更容易恢复。也没有理由为它挂载 Docker socket，或给容器访问服务器上的 SSH 私钥。

访问失败时先检查容器状态与端口冲突，再检查 SSH 转发。容器内部端口80与宿主机8088不是同一个地址；把反向代理指向容器内的 `127.0.0.1:80`，通常不会连接到宿主机上的服务。

从私人入口到固定域名

个人偶尔使用，可以一直保留隧道。团队需要固定入口时，通过已有反向代理提供 HTTPS。Caddy 的简单示例为：

tools.example.com {
    reverse_proxy 127.0.0.1:8088
}

域名指向 VPS，证书与访问路径确认后，用另一台设备测试。普通静态工具页与包含私人操作数据的页面应按实际用途安排访问范围；需要仅团队可用时，认证可以放在现有访问网关或反向代理层。

不要在没有核对的情况下把一个嵌套路径当成部署地址。项目构建时的资源基路径可能影响 JavaScript 和 CSS 请求，独立子域名通常更容易排错。如果必须用 `/tools/`，应按当前项目构建与代理要求验证，不只看首页 HTML 有内容。

页面打不开工具或样式错乱时，在浏览器检查失败的静态资源请求。出现404可能是路径重写，旧脚本与新 HTML 混用则可能来自缓存。先验证资源地址与版本，再决定清除哪一层缓存。

用非敏感样本验证三个常见场景

第一个场景是接口数据。把一段小 JSON 格式化，检查数组、数字、布尔值和空值是否保留，再拿格式有错的样本观察提示。修复生产数据前，先确认工具有没有按预期保留字段，而不是只看缩进更好看。

{
  "job": "nightly-export",
  "enabled": true,
  "lastRun": null,
  "attempts": 2
}

第二个场景是 URL 编码。完整 URL、路径与查询参数的编码方式不能乱用。参数值包含空格、`&` 或中文时，先单独处理该值，再交给应用构建请求；不要把整个 URL 反复编码后，期待服务端自动猜出原意。

第三个场景是时间。Unix 时间戳可能以秒或毫秒表示，显示出来的当地时间也受时区影响。将应用日志中的原始值、单位与时区一起记录，再核对转换结果。漏掉单位，常会得到一个看似格式正确却完全不对的日期。

工具输出用于提交工单时，保留必要上下文，但去掉令牌、账号和私人内容。一个解码后的请求可能比原始字符串更容易暴露信息，不能因为是“排障结果”就直接复制到公开评论里。

准备独立实例时，可在雨云选择适合的云服务器配置，优惠码 `KuZhuJi`。配置按实际任务选择，数据库和附件另做备份。

输入内容与外部请求

浏览器页面中的计算可以在客户端完成，但不能对所有功能一概而论。项目代码、外部资源、浏览器插件和使用习惯都影响数据路径。正式处理敏感内容前，在非敏感样本上观察网络请求，并核对所用工具的实现。

即使当前页面没有外发请求，敏感内容还可能留在剪贴板、浏览器恢复会话、扩展或录屏里。密码、私钥和完整生产访问令牌，应优先使用已有受控流程处理，不必为了统一入口全部粘进网页。

团队可以约定适合输入的内容：去标识的日志片段、测试数据、公开字段和虚构令牌。涉及真实用户数据时，先在本地按既定方式删掉不必要字段。这个约定比在页面页脚写一句笼统的“完全安全”更有操作性。

页面上新增工具也应重新评估。更新后菜单更多，不代表所有新功能都适合当前团队使用。关注需要连接外部服务或依赖不同算法的变化，保留清楚的使用范围。

版本固定后，恢复成本很低

基础 IT-Tools 配置没有数据库，但仍要保存 Compose、镜像摘要、域名和代理配置。若另外增加认证网关，也要把它的恢复材料单独纳入管理。只备份工具容器不一定能恢复访问入口。

升级前记录正在使用的镜像，阅读发布说明，换到目标版本后验证最常用的几种工具。首次试用的 `latest` 不适合长期作为唯一版本记录，因为同一个名字以后可能指向不同构建。

可以从镜像信息中记录摘要：

docker image inspect ghcr.io/corentinth/it-tools:latest \
  --format '{{json .RepoDigests}}'

若尚未获得仓库摘要，不能自行拼一个。固定确认过的镜像以后，再测试重新创建容器：入口是否可用、静态资源是否加载、常用样本输出是否一致。这个过程无需真实生产令牌。

浏览器里保存的偏好也不应默认由服务器备份。书签、最近使用项或其他本地状态的保存位置，要按具体版本确认。迁移后菜单恢复，不代表每位成员的浏览器习惯也一起恢复。

需要增加服务器时，可以打开雨云选购页面，填写优惠码 `KuZhuJi`；迁移前保留数据与原有部署配置。

一个 JWT 调试场景，需要把解码与验证分开

接口返回了401，维护者打开令牌查看工具，看到里面有用户名与过期时间。到这一步只说明编码内容可以解析，还不知道签名是否有效，发行者是否可信，接收方是否正确，或者服务端时钟是否偏差。

可以用虚构令牌熟悉字段结构，再回到应用的认证日志核对失败阶段。不要把生产签名密钥粘进工具页面，期待一次按钮点击代替应用验证；认证库、密钥来源和算法允许范围需要按项目机制检查。

过期时间与当前时间比较时，将单位和时区写清。某个客户端因为缓存继续使用旧令牌，也可能造成相同错误。解码页面没有看见异常，不能因此断言接口服务器错误。

同样的边界也适用于文件哈希。两边采用同一算法、读取同一份完整文件，结果相同可以用于相应完整性对照；若来源本身未经核对，一串相同的哈希不会证明发布者身份。签名与官方校验资料是另一项验证。

升级后检查静态资源

升级后先打开首页，再进入最常用的几个工具，不要只确认页面标题。某个旧资源被浏览器缓存，新页面可能在切换工具时才报错。用一个新会话重复样本，可以帮助区分客户端缓存与构建本身的问题。

测试时记录工具名称、输入样本、期望结果和实际结果。样本只用虚构文本，可存入内部说明。若新旧版本处理不同，先查对应工具的实现或变更，而不是默默替换结果继续用。

对团队而言，这份小样本比“界面都能打开”更能支持更新决定。确认版本符合工作需求后，再调整固定镜像标识，保留上一版以便处理静态部署问题。

给工具箱留一份短说明

工具多不等于使用频率高。团队说明写清域名、负责维护的人、镜像版本、允许输入的材料和几个常见样本即可。遇到结果分歧时，先回到样本与具体算法，而不是争论谁使用的网页更好看。

工具箱可承担重复的小操作；涉及部署、数据修复与安全判断，结果仍要经过相应验证。把界限安排清楚，一个简单容器就能减少日常切换网站的时间，也不会逐渐成为难以解释的数据入口。