Web 服务与 Docker

services/opentransd 是仓库内置的一个 HTTP/Web 服务，用来把 OpenTrans 的协议转换能力直接暴露为浏览器页面和 API。

适用场景

它特别适合：

• 协议调试
• 团队内部自助转换工具
• 示例分享
• 回归验证
• 文档演示环境

如果你要做的是完整生产网关，通常更推荐基于 SDK 二次封装，而不是直接把这个服务当成所有业务逻辑入口。

服务入口

仓库中的位置：

• 可执行入口：services/opentransd/cmd/opentransd
• HTTP 实现：services/opentransd/internal/server
• 静态首页：services/opentransd/internal/server/static/index.html

本地启动

go run ./services/opentransd/cmd/opentransd

默认端口：

8080

修改端口：

PORT=9090 go run ./services/opentransd/cmd/opentransd

启动后可以访问：

• GET /: 浏览器转换页面
• GET /healthz: 健康检查

HTTP 路由

方法	路径	说明
GET	/	浏览器转换页面
GET	/healthz	健康检查
GET POST	/convert	返回原始转换结果
GET POST	/api/convert	返回带元信息的 JSON 包装

完整参数说明见：HTTP Service API

Docker 启动

直接使用 Docker Hub 已发布镜像

如果你只是想快速启动一个可用实例，直接拉取已经发布的镜像即可：

docker run --rm -p 8080:8080 -e PORT=8080 xy200303/opentrans:latest

如果你希望固定到当前 main 分支对应镜像，也可以使用：

docker run --rm -p 8080:8080 -e PORT=8080 xy200303/opentrans:main

启动后访问：

http://localhost:8080

使用 docker compose

docker compose -f services/opentransd/docker-compose.yml up --build

手动构建并运行

docker build -f services/opentransd/Dockerfile -t opentrans .
docker run --rm -p 8080:8080 -e PORT=8080 opentrans

转换接口示例

POST /convert

curl -X POST "http://localhost:8080/convert?kind=request&source=openai&target=claude&pretty=1" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1-mini",
    "messages": [
      {"role": "user", "content": "hello"}
    ]
  }'

GET /api/convert

http://localhost:8080/api/convert?kind=request&source=openai&target=claude&body=%7B%22model%22%3A%22gpt-4.1-mini%22%2C%22messages%22%3A%5B%7B%22role%22%3A%22user%22%2C%22content%22%3A%22hello%22%7D%5D%7D

浏览器分享链接

首页会自动把输入内容编码成 body_b64 分享链接：

http://localhost:8080/?kind=request&source=openai&target=claude&body_b64=...&autorun=1

这对于以下场景很有帮助：

• 复现 bug
• 分享协议样例
• 让同事直接打开就看到同一份输入输出

上线建议

如果你希望把这个服务放进更正式的环境，建议额外补上这些外围能力：

• 认证与权限控制
• 请求限流
• 访问日志
• tracing
• timeout 和熔断
• 反向代理和 TLS 终止

相关文档

• HTTP Service API
• CI/CD 与发布
• 常见问题与排障