AstrBot T2I Router

AstrBot 简易文转图请求路由

简介

AstrBot T2I Router 是一个用 Go 编写的简易文转图后端路由器，主要用于在多个 text2image 服务实例之间选择可用后端，并保证图片生成后的数据查询请求继续落到同一个后端。

它会在收到生成请求时按配置顺序检查后端连通性，选择第一个可用后端；当生成接口返回 ID 后，路由器会记录 id -> 后端地址 的绑定关系。之后客户端访问 /text2img/data/{id} 时，路由器会根据绑定关系返回 307 重定向到对应后端。

功能特性

• 支持多个文转图后端地址，按配置顺序选择第一个可连通后端。
• 支持 HTTP / HTTPS 后端，未写协议时默认补全为 http://。
• POST /text2img/generate：
  • 请求体 JSON 中 json 为 true 时，由路由器转发请求、读取响应并绑定图片 ID。
  • 请求体 JSON 中 json 不为 true 或无法解析时，直接返回 307 Temporary Redirect。
• GET /text2img/data/{id}：根据已绑定 ID 返回 307 Temporary Redirect。
• 绑定表支持 TTL 过期与后台分批清理，避免长期运行内存无限增长。
• HTTP 客户端、后端连通性检查均支持超时配置。
• 未匹配路由返回 404 Not Found。

工作流程

客户端
  |
  | POST /text2img/generate, body 中 json=true
  v
T2I Router
  |
  | 依次检查 config.json 中的后端地址
  | 选择第一个可连通后端
  v
后端 text2img 服务
  |
  | 返回 JSON，例如 {"data":{"id":"data/rendered_1145141919_1a2b3c4d.jpeg"}}
  v
T2I Router
  |
  | 内部绑定 rendered_1145141919_1a2b3c4d.jpeg -> 该后端
  | 返回后端响应 JSON
  v
客户端

之后：
客户端 GET /text2img/data/rendered_1145141919_1a2b3c4d.jpeg
  -> T2I Router 根据 rendered_1145141919_1a2b3c4d.jpeg 找到后端
  -> 返回 307 Location: 后端/text2img/data/rendered_1145141919_1a2b3c4d.jpeg

环境要求

• Go 1.22 或更高版本（更低版本需手动修改 go.mod ）

构建

go build -o t2irou .

Windows 下也可以构建为：

go build -o t2irou.exe .

运行

默认读取当前目录下的 config.json，监听 :8160：

./t2irou

指定配置文件和端口：

./t2irou -config config.json -port 8765

也可以使用兼容写法：

./t2irou config.json 8765

配置文件

简单数组格式

适合只配置后端地址的场景：

[
  "192.168.25.3:8999",
  "https://t2i.example.com",
  "https://t2i.soulter.top"
]

对象格式

推荐用于生产部署，可配置监听地址、超时和绑定有效期：

{
  "listen": ":8160",
  "addresses": [
    "192.168.25.3:8999",
    "192.168.25.2:8999",
    "192.168.25.11:8999",
    "https://t2i.soulter.top",
    "https://t2i.rcfortress.site"
  ],
  "ping_timeout": "2s",
  "request_timeout": "30s",
  "binding_ttl": "24h",
  "cleanup_interval": "5m"
}

字段说明：

字段	类型	默认值	说明
listen	string	:8160	HTTP 服务监听地址，例如 :8160 或 127.0.0.1:8160。
port	string	空	仅指定端口时可用，例如 8160，优先级低于命令行参数。
addresses	string[]	无	后端服务地址列表，按顺序尝试；不带协议时自动补 http://。
ping_timeout	duration	2s	检查后端 TCP 连通性的超时时间。
request_timeout	duration	30s	转发生成请求到后端时的 HTTP 客户端超时时间。
binding_ttl	duration	1h	图片 ID 与后端地址绑定关系的有效期。
cleanup_interval	duration	5m	后台清理过期绑定的间隔。

duration 使用 Go 的时间格式，例如：500ms、2s、5m、24h。

路由说明

POST /text2img/generate

用于发起文转图任务。

当请求体 JSON 中 json 为 true 时，路由器会转发请求并读取后端响应：

{
  "json": true
}

此时路由器会解析后端响应中的：

{
  "data": {
    "id": "data/rendered_1145141919_1a2b3c4d.jpeg"
  }
}

并在内部绑定：

rendered_1145141919_1a2b3c4d.jpeg -> 实际处理该请求的后端地址

如果请求体中 json 不为 true，路由器不会读取后端响应，而是直接返回：

307 Temporary Redirect
Location: <选中的后端>/text2img/generate

GET /text2img/data/{id}

用于获取生成结果数据。

例如：

GET /text2img/data/rendered_1145141919_1a2b3c4d.jpeg

如果 rendered_1145141919_1a2b3c4d.jpeg 已绑定到某个后端，路由器返回：

307 Temporary Redirect
Location: <绑定后端>/text2img/data/rendered_1145141919_1a2b3c4d.jpeg

如果 ID 未绑定或已过期，返回 500 Internal Server Error。

其他路径

返回 404 Not Found。

示例

启动路由器：

./t2irou -config config.json -port 8160

发送生成请求：

curl -X POST http://127.0.0.1:8160/text2img/generate \
  -H "Content-Type: application/json" \
  -d '{"json":true,"html":"<b>test</b>"}'

查询数据：

curl -i http://127.0.0.1:8160/text2img/data/{id}

如果绑定存在，将看到类似：

HTTP/1.1 307 Temporary Redirect
Location: http://192.168.25.3:8999/text2img/data/rendered_1145141919_1a2b3c4d.jpeg

注意事项

• 后端连通性检查是 TCP 连接检查，不是 ICMP ping。
• 当前选择策略是“按配置顺序选择第一个可连通后端”，不是轮询或负载均衡。
• 绑定信息存储在进程内存中，程序重启后会丢失。
• /text2img/data/{id} 只接受单段 ID，包含额外 / 的路径会返回 404。