三种子类型详解

三种子类型互斥 — 每个应用只能属于其中一种：

子类型	config.ini 必填字段	关键标识
iframe（内部打开）	`type`、`path`	`"type": "iframe"`、`"open_path": false`
外部打开（新标签页）	`path`	`"open_path": true`（不写 `type` 字段）
无 UI 服务	无页面相关字段	不写 `path`、`open_path`、`type` 字段

互斥规则： type 和 open_path 不可同时出现 — iframe 用 "type": "iframe"；外部打开用 "open_path": true；无 UI 两者皆不写。混用将导致行为未定义，审核时驳回。

WebUI 内部打开（iframe 嵌入）

适用于后端为本地可执行服务、前端为静态 WebUI，在 TOS 桌面内嵌 iframe 打开的应用。

目录结构：

/usr/local/<app_id>/
├── config.ini
├── bin/
│   └── <binary_name>
├── <app_id>.lang
├── webui.bz2                     # 【必填】前端页面压缩包
├── images/
│   └── icons/
│       └── <icon_file>.svg
├── init.d/
│   └── <system_id>.service
├── <app_id>.env                  # 【可选】环境变量配置文件
└── depends/                      # 【可选】依赖文件目录
    ├── bin/                      # 可执行文件
    ├── lib/                      # 动态库 (.so)
    ├── etc/                      # 配置文件
    ├── data/                     # 运行数据（数据库/缓存/状态）
    └── logs/                     # 日志

config.ini 最小配置：

{
  "id": "<app_id>",
  "icon": "/images/icons/<icon_file>.svg",
  "exec": true,
  "version": "<app_version>",
  "category": ["Utilities"],
  "platform": "x86_64",
  "system_id": "<system_id>",
  "package": "<deb_package_name>",
  "application_type": "deb",
  "path": "/<app_id>/",
  "type": "iframe"
}

核心要求：

type 字段必须为 "iframe"。
path 字段格式为 "/<app_id>/"。
webui.bz2 是固定文件名，不能写成其他名称。
deb包必须包含可执行程序，可执行程序存放地址 /usr/local/<app_id>/bin/<binary_name>。
config.ini.package 字段规范必须严格符合Debian包的 package 规范。
后端服务通过 Unix Socket 对外提供 HTTP 接口，启动时必须在 /var/api/<app_id>.sock 监听。
/var/api 不存在时必须自动创建；启动前必须清理旧 socket 文件。
socket 文件权限必须允许平台代理访问。
前端请求后端接口时必须走平台代理路径，固定格式为 /v2/proxy/<app_id>。
前端请求必须携带平台鉴权所需 header，请求header中携带 X-Csrf-Token 和 Cookie。

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 外部打开（新标签页）

适用于后端为本地可执行服务、前端为静态 WebUI，在浏览器新标签页打开的应用。

目录结构：

/usr/local/<app_id>/
├── config.ini
├── bin/
│   └── <binary_name>
├── <app_id>.lang
├── webui.bz2                     # 【必填】前端页面压缩包
├── images/
│   └── icons/
│       └── <icon_file>.svg
├── nginx/
│   └── <app_id>.conf             # 【必填】Nginx 配置文件
├── init.d/
│   └── <system_id>.service
├── <app_id>.env                  # 【可选】环境变量配置文件
└── depends/                      # 【可选】依赖文件目录
    ├── bin/                      # 可执行文件
    ├── lib/                      # 动态库 (.so)
    ├── etc/                      # 配置文件
    ├── data/                     # 运行数据（数据库/缓存/状态）
    └── logs/                     # 日志

config.ini 最小配置：

{
  "id": "<app_id>",
  "icon": "/images/icons/<icon_file>.svg",
  "exec": true,
  "version": "<app_version>",
  "category": ["Utilities"],
  "platform": "x86_64",
  "system_id": "<system_id>",
  "package": "<deb_package_name>",
  "application_type": "deb",
  "path": "http://${ip}:8686",
  "open_path": true
}

核心要求：

open_path 必须为 true。
path 字段必须对应 nginx 配置文件的路由，并且可以解析到对外提供的 HTTP 接口。
应用包必须携带 nginx 配置文件 <app_id>.conf，文件名必须与 config.ini.id 对应。
后端直接监听 <listen_port> 提供 HTTP 接口。
deb包必须包含可执行程序，可执行程序存放地址 /usr/local/<app_id>/bin/<binary_name>。
config.ini.package 字段规范必须严格符合Debian包的 package 规范。

端口监听规则：

必须监听 0.0.0.0（所有网络接口），禁止仅监听 127.0.0.1。仅监听本地回环地址会阻止外部访问。
禁止占用系统保留端口（22、80、443、8181、5050）
推荐端口范围：8000-19999

Nginx 配置文件模板：

在 /usr/local/<app_id>/nginx/<app_id>.conf 创建：

location /<app_id>/ {
    proxy_pass http://127.0.0.1:<listen_port>/;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Nginx 配置管理要求：

配置文件权限：644（属主读写，属组和其他只读）
配置文件必须放置在 /usr/local/<app_id>/nginx/<app_id>.conf
平台 Nginx 的 include 指令按字母顺序加载配置；应用间端口冲突通过唯一端口解决 — 两个应用不能共享同一端口
日志轮转：Nginx 访问/错误日志由平台管理；请勿写入自己的 nginx 日志
禁止包含 server {} 块；仅使用 location /<app_id>/ {} 块

无 UI 服务

适用于没有操作页面的后台服务应用。

目录结构：

/usr/local/<app_id>/
├── config.ini
├── bin/
│   └── <binary_name>
├── <app_id>.lang
├── images/
│   └── icons/
│       └── <icon_file>.svg
├── init.d/
│   └── <system_id>.service
├── <app_id>.env                  # 【可选】环境变量配置文件
└── depends/                      # 【可选】依赖文件目录
    ├── bin/                      # 可执行文件
    ├── lib/                      # 动态库 (.so)
    ├── etc/                      # 配置文件
    ├── data/                     # 运行数据（数据库/缓存/状态）
    └── logs/                     # 日志

config.ini 最小配置：

{
  "id": "<app_id>",
  "icon": "/images/icons/<icon_file>.svg",
  "exec": true,
  "version": "<app_version>",
  "category": ["Utilities"],
  "platform": "x86_64",
  "system_id": "<system_id>",
  "package": "<deb_package_name>",
  "application_type": "deb"
}

核心要求：

无 UI 应用不需要 path、type、open_path、resize、maxmin、width、height 等前端相关字段。
不需要 webui.bz2 前端压缩包。
不需要 nginx/ 目录。
deb包必须包含可执行程序，可执行程序存放地址 /usr/local/<app_id>/bin/<binary_name>。
config.ini.package 字段规范必须严格符合Debian包的 package 规范。

状态上报要求： 无 UI 应用必须上报其运行状态，以便平台检测故障：

systemd 服务单元的 Type 应为 simple 或 forking
使用 systemd 的 ExecStartPost 确认成功启动
应用中心基于 systemd 服务状态显示"运行中"/"已停止"/"异常"
故障时，systemd 自动重启（在服务文件中配置）处理恢复

WebUI 内部打开（iframe 嵌入）​

WebUI 外部打开（新标签页）​

无 UI 服务​

WebUI 内部打开（iframe 嵌入）

WebUI 外部打开（新标签页）

无 UI 服务