Skip to main content

后端服务规范

WebUI 内部打开（Unix Socket 模式）​

后端可执行文件安装到：

/usr/local/<app_id>/bin/<binary_name>

后端必须创建并监听 Unix Socket：

/var/api/<app_id>.sock

要求：

  1. /var/api 不存在时必须自动创建。
  2. 启动前必须清理旧 socket 文件。
  3. socket 文件权限必须允许平台代理访问。
  4. 后端接口协议为 HTTP-over-Unix-Socket。
  5. 后端应优雅处理 SIGTERM，便于 systemd 停止服务。

标准日志规范：

日志级别用途
ERROR服务故障、启动错误、数据损坏
WARN弃用功能、可恢复错误、配置问题
INFO服务生命周期事件（启动/停止）、版本信息、配置已加载
DEBUG详细诊断信息 — DEBUG 级别日志必须在生产环境中禁用，仅用于开发调试阶段

标准输出格式：

[YYYY-MM-DD HH:MM:SS] [LEVEL] [component] message

示例：

[2026-05-11 16:30:00] [INFO] [main] 服务已在端口 8686 上启动

对于 systemd 管理的服务，优先使用 stdout/stderr 输出日志 — systemd journal 会自动捕获两者。

服务崩溃自动重启限制
  • 最大重启尝试次数：60 秒内 5 次
  • 超出限制后，服务进入失败状态
  • 应用中心在重启限制超出后显示服务为"异常"
  • 必须在 systemd 服务文件中显式配置 StartLimitBurst=5 和 StartLimitIntervalSec=60 两个参数。

Socket 文件规范：

  • 权限模式：0660（属主和属组读写）
  • 属主：<appid>:<appid>（与服务用户匹配）
  • 支持 HTTP keep-alive 连接
  • 至少支持 100 个并发连接
  • 空闲连接超时时间：30 秒

前端请求后端接口时必须走平台代理路径：/v2/proxy/<app_id>/<api_name>。

前端请求必须携带平台鉴权 header。

跨域和预检请求配置： 后端必须为平台代理处理 CORS 预检请求（OPTIONS 方法）。允许以下内容：

  • Origin：TOS Web 源
  • Methods：GET, POST, PUT, DELETE, OPTIONS
  • Headers：Content-Type, X-Csrf-Token, Cookie
  • Credentials：true

WebUI 外部打开（HTTP 端口模式）​

后端可执行文件安装到：

/usr/local/<app_id>/bin/<binary_name>

后端直接监听 <listen_port> 提供 HTTP 接口。

要求：

  1. 直接监听 <listen_port>。
  2. 提供静态 WebUI 首页。
  3. 提供健康检查接口。
  4. 提供业务 API 路由，具体业务由应用自行定义。
  5. 优雅处理 SIGTERM 和 SIGINT。

推荐固定路由：

GET /
GET /health

业务 API 推荐命名：

/api/<resource>

如需兼容系统入口，可同时支持：

/<app_id>/api/<resource>
/v2/proxy/<app_id>/<resource>
/v2/proxy/<app_id>/api/<resource>