工具接入指南

下载静态工具模板 · 下载后台工具模板

# 我的工具箱 / Tools Hub

线上入口：https://tools.8977777.xyz/ ；管理入口：https://tools.8977777.xyz/_hub/

这是一次安装、持续添加工具的基座。每个 ZIP 安装包对应一个工具，固定使用 `/<id>/` 路径。所有工具共用域名与 HTTPS。管理页面可以安装、更新、启停、卸载和修改管理员密码。首页和已启用工具公开可访问；敏感业务工具应实现自己的登录。管理员才能安装工具。由于同域部署，工具必须是自己信任的代码。

## 日常使用

1. 登录管理入口，选择 ZIP 文件，点击安装 / 更新工具。
2. 新工具自动显示在首页；相同 id 的安装包更新现有工具，失败保留原版本。
3. 停用会隐藏入口并阻止访问，后台容器同时停止。启用会重新启动。
4. 卸载删除程序、容器和入口，但保留该 id 的 `/data` 数据。重新安装相同 id 可继续读取。
5. 更新期间后台工具新旧容器会短暂同时运行；数据结构迁移必须兼容旧版，安装器不负责回滚业务数据。

## 安装包规范 v1

ZIP 根目录直接包含 `tool.json`，不要额外套一层目录。最大上传 64 MB，解压后最多 192 MB、5000 个文件。不允许路径穿越、符号链接、设备文件或加密 ZIP。

```json
{
  "id": "my-tool",
  "name": "我的工具",
  "version": "1.0.0",
  "description": "一句话描述用途",
  "icon": "✦",
  "type": "static"
}
```

id 为 2–40 位小写字母、数字、连字符，以字母开头，作为永久路径和数据标识。不能用 api、admin、assets、favicon、health、robots 或以下划线开头的名称。name 最多 80 字符，version 最多 40，description 最多 300，icon 是最多 8 字符的文本或 emoji。

### 纯前端工具

```
tool.json
public/
  index.html
  assets/...
```

所有网页资源放在 public。Vite 构建时设置 `base: '/my-tool/'`，Vue Router 使用 `createWebHistory(import.meta.env.BASE_URL)`。路径中无扩展名的前端路由自动回退到 index.html；缺失 JS/CSS 返回 404。所有资源、请求路径均须兼容工具前缀；不要假设部署在 `/`。

浏览器 localStorage/IndexedDB 按域名共享，应使用工具 id 作为键名前缀。Service Worker scope 不能超过自身工具路径。返回基座首页使用 `/`。

### 带后台工具

```json
{
  "id": "my-api-tool", "name": "后台工具", "version": "1.0.0",
  "type": "container", "port": 8080, "health": "/health",
  "description": "带数据持久化的小应用", "icon": "⚙"
}
```

ZIP 包含 tool.json、Dockerfile 和构建所需代码。服务器为 Linux ARM64，基础镜像须支持 ARM64。容器须监听 `0.0.0.0:$PORT`；健康检查路径须返回 2xx/3xx，不要求登录。首次构建最多 10 分钟，启动等待约 1–2 分钟。工具暂限一个 HTTP 容器；WebSocket 不支持。可调用已有的外部数据库，但其凭证应通过受控服务器配置管理，不放入公开模板。

基座自动注入：
- `PORT`：manifest 中的端口。
- `BASE_PATH`：例如 `/my-api-tool/`，供前端构造资源与接口地址。
- `DATA_DIR=/data`：持久化目录，升级、停用、卸载均保留。

代理会去除工具路径前缀：浏览器 `/my-api-tool/api/hello` 对应容器 `/api/hello`。设置 `X-Forwarded-Prefix`；根路径重定向和 Cookie Path 自动加工具前缀。响应正文不自动改写，因此应用须正确生成带 BASE_PATH 的资源地址。容器仅绑定服务器回环端口，限制 512 MB 内存、1 CPU、128 进程，不授予特权，不挂载 Docker socket，删除 Linux capabilities。默认基础镜像 root 用户可写 /data；自定义非 root 镜像需另行安排数据目录权限。

### 电池应用现有后台接入

电池工具为 static 包，额外指定 `"api":"http://127.0.0.1:3180"`，基座仅代理 `/battery/api/*`。这是服务端显式允许的已有服务；其他任意地址会拒绝。前端使用已有后台及数据库，不复制业务记录。

## 交给以后开发者的说明

> 请把新工具打包为 Tools Hub v1 安装包：ZIP 根目录放 tool.json。纯前端放 public/index.html，所有路径兼容 /<id>/；带后台则提供支持 Linux ARM64 的 Dockerfile，监听 PORT，使用 BASE_PATH 构造浏览器路径，数据存 DATA_DIR=/data，并提供无登录的健康检查。不要新增域名、证书或修改 OpenResty。给我可直接上传到工具箱的 ZIP。

## 服务器运维

- 安装目录：`/home/ubuntu/tools-hub`
- 状态目录：`/home/ubuntu/tools-hub/state`（包含管理员密码哈希、SQLite 工具目录、版本文件、工具数据）。
- 服务：`tools-hub.service`，systemd 自动启动，监听 `127.0.0.1:3190`。
- 查看状态：`sudo systemctl status tools-hub`
- 日志：`sudo journalctl -u tools-hub -n 100`
- 修改密码：进入安装目录，执行 `python3 server.py --root state --set-password`，然后 `sudo systemctl restart tools-hub` 撤销旧会话。
- 备份：暂停工具写入后备份整个 state 目录；电池数据仍按原应用备份数据库和截图。SQLite 可用 sqlite3 backup 或停服务复制。恢复还需重建后台容器并刷新其端口记录（重新上传相同安装包）。
- 后台容器可在 1Panel 容器列表中看到，名称以 toolhub- 开头。基座服务由 systemd 管理。
- OpenResty 配置：`/opt/1panel/apps/openresty/openresty/conf/conf.d/tools.8977777.xyz.conf`。共用现有 1panel 站点证书路径，证书需持续包含 tools.8977777.xyz，续期后重载 OpenResty。不要删除共享证书目录。
- 首版未直接修改 1Panel 内部数据库，所以新站点配置不登记到面板网站列表。应用安装和入口管理都在基座内完成。

测试：`cd tools-hub && python3 -m unittest discover -s tests -v`。