服务器模式

服务器模式提供 HTTP 服务，支持通过 REST API 进行远程调用，适合集成到其他工具链中。

启动服务器

基本启动

bash

qt --run

服务将在 http://127.0.0.1:9999 启动。

指定配置文件

bash

qt --run --config config.toml

后台运行（Linux/macOS）

bash

nohup qt --run > server.log 2>&1 &

使用 systemd 服务（Linux）

创建服务文件 /etc/systemd/system/qt-tool.service：

ini

[Unit]
Description=QT Tool Server
After=network.target

[Service]
Type=simple
User=your_user
WorkingDirectory=/path/to/qt-tool
ExecStart=/path/to/qt --run
Restart=on-failure

[Install]
WantedBy=multi-user.target

启动服务：

bash

sudo systemctl daemon-reload
sudo systemctl enable qt-tool
sudo systemctl start qt-tool

API 接口

基础信息

Base URL: http://127.0.0.1:9999
Content-Type: application/json
响应格式: JSON

通用响应格式

所有接口返回统一的响应格式：

json

{
  "success": true,
  "message": "操作成功",
  "data": { ... }
}

错误响应：

json

{
  "success": false,
  "message": "错误描述",
  "data": null
}

接口列表

1. 测试接口

GET /process/test

测试服务是否正常运行。

请求示例：

bash

curl http://127.0.0.1:9999/process/test

响应示例：

json

{
  "success": true,
  "message": "测试成功",
  "data": "测试成功"
}

2. 获取配置列表

GET /process/configs

获取所有可用的输出配置。

请求示例：

bash

curl http://127.0.0.1:9999/process/configs

响应示例：

json

{
  "success": true,
  "message": "获取配置文件成功",
  "data": [
    {
      "name": "Android 图标",
      "description": "Android 应用图标",
      "base_path": "./android"
    },
    {
      "name": "iOS 图标",
      "description": "iOS 应用图标",
      "base_path": "./ios"
    }
  ]
}

3. 获取文件类型限制

GET /process/limits?config_index=0

获取指定配置的允许文件类型。

请求参数：

参数	类型	必填	说明
config_index	number	是	配置索引（从 0 开始）

请求示例：

bash

curl "http://127.0.0.1:9999/process/limits?config_index=0"

响应示例：

json

{
  "success": true,
  "message": "获取可选的配置后缀成功",
  "data": [".png", ".svg"]
}

4. 检查文件是否存在

POST /process/check

检查目标文件是否已存在。

请求体：

json

{
  "name": "icon.png",
  "config_index": 0
}

请求参数：

参数	类型	必填	说明
name	string	是	文件名
config_index	number	是	配置索引

请求示例：

bash

curl -X POST http://127.0.0.1:9999/process/check \
  -H "Content-Type: application/json" \
  -d '{"name":"icon.png","config_index":0}'

响应示例（文件不存在）：

json

{
  "success": true,
  "message": "请求校验文件成功",
  "data": true
}

响应示例（文件已存在）：

json

{
  "success": true,
  "message": "请求校验文件成功",
  "data": false
}

5. 处理 ZIP 文件

POST /process

处理 ZIP 文件并解压到指定目录。

请求体：

json

{
  "name": "icon.png",
  "path": "/path/to/input.zip",
  "config_index": 0
}

请求参数：

参数	类型	必填	说明
name	string	是	输出文件名（必须以 .png 结尾）
path	string	是	ZIP 文件的绝对路径
config_index	number	是	配置索引

请求示例：

bash

curl -X POST http://127.0.0.1:9999/process \
  -H "Content-Type: application/json" \
  -d '{
    "name": "icon.png",
    "path": "/home/user/icons.zip",
    "config_index": 0
  }'

响应示例（成功）：

json

{
  "success": true,
  "message": "处理文件完成",
  "data": null
}

响应示例（失败）：

json

{
  "success": false,
  "message": "ZIP 文件内容格式与配置文件(Android 图标)不符合",
  "data": null
}

完整工作流示例

以下是一个完整的工作流程，展示如何使用 API 处理文件：

bash

#!/bin/bash

# 1. 测试服务
echo "1. 测试服务..."
curl -s http://127.0.0.1:9999/process/test

# 2. 获取配置列表
echo -e "\n2. 获取配置列表..."
curl -s http://127.0.0.1:9999/process/configs | jq .

# 3. 获取第一个配置的文件类型限制
echo -e "\n3. 获取文件类型限制..."
curl -s "http://127.0.0.1:9999/process/limits?config_index=0"

# 4. 检查文件是否存在
echo -e "\n4. 检查文件是否存在..."
curl -s -X POST http://127.0.0.1:9999/process/check \
  -H "Content-Type: application/json" \
  -d '{"name":"icon.png","config_index":0}'

# 5. 处理 ZIP 文件
echo -e "\n5. 处理 ZIP 文件..."
curl -s -X POST http://127.0.0.1:9999/process \
  -H "Content-Type: application/json" \
  -d '{
    "name": "icon.png",
    "path": "/home/user/icons.zip",
    "config_index": 0
  }'

CORS 支持

服务器默认启用了 CORS（跨域资源共享），允许来自任何源的请求。这方便了浏览器插件和前端应用的调用。

日志和记录

日志文件

服务器运行时会生成日志文件，位于：

Linux/macOS: ~/.config/qt-tool/record.log
Windows: %APPDATA%\qt-tool\record.log

处理记录

每次处理操作都会被记录，记录文件位于：

Linux/macOS: ~/.config/qt-tool/record.json
Windows: %APPDATA%\qt-tool\record.json

记录格式：

json

[
  {
    "key": "unique_key",
    "is_success": true,
    "timestamp": 1700000000000
  }
]

日志上传

服务器会在后台自动上传处理记录到指定服务器。

故障排除

服务无法启动

检查端口是否被占用：

bash

# Linux/macOS
lsof -i :9999

# Windows
netstat -ano | findstr :9999

检查配置文件是否正确：

bash

qt --run --config my_config.toml

请求超时

检查防火墙设置，确保允许访问指定端口。

处理失败

查看日志文件获取详细错误信息：

bash

tail -f ~/.config/qt-tool/record.log

下一步

查看详细的配置说明
了解浏览器插件的使用方法
查看 API 文档了解更多接口细节

服务器模式 ​

启动服务器 ​

基本启动 ​

指定配置文件 ​

后台运行（Linux/macOS） ​

使用 systemd 服务（Linux） ​

API 接口 ​

基础信息 ​

通用响应格式 ​

接口列表 ​

1. 测试接口 ​

2. 获取配置列表 ​

3. 获取文件类型限制 ​

4. 检查文件是否存在 ​

5. 处理 ZIP 文件 ​

完整工作流示例 ​

CORS 支持 ​

日志和记录 ​

日志文件 ​

处理记录 ​

日志上传 ​

故障排除 ​

服务无法启动 ​

请求超时 ​

处理失败 ​

下一步 ​

服务器模式

启动服务器

基本启动

指定配置文件

后台运行（Linux/macOS）

使用 systemd 服务（Linux）

API 接口

基础信息

通用响应格式

接口列表

1. 测试接口

2. 获取配置列表

3. 获取文件类型限制

4. 检查文件是否存在

5. 处理 ZIP 文件

完整工作流示例

CORS 支持

日志和记录

日志文件

处理记录

日志上传

故障排除

服务无法启动

请求超时

处理失败

下一步