Tři podtypy podrobně

Tři podtypy se vzájemně vylučují — každá aplikace patří pouze do jednoho:

Podtyp	Povinná pole v config.ini	Klíčový identifikátor
iframe (interní otevření)	type, path	"type": "iframe", "open_path": false
Externí otevření (nová karta)	path	"open_path": true (bez pole type)
Služba bez UI	Žádná pole související se stránkou	Bez polí path, open_path ani type

Pravidlo vzájemného vyloučení: type a open_path se nesmí objevit společně — iframe používá "type": "iframe"; externí otevření používá "open_path": true; aplikace bez UI nepoužívá ani jedno. Jejich kombinování povede k nedefinovanému chování a zamítnutí při recenzi.

Interní otevření WebUI (vložení iframe)

Pro aplikace, kde je backend místní spustitelnou službou a frontend statickým WebUI, otevíraným v rámci desktopu TOS jako vložený iframe.

Struktura adresářů:

/usr/local/<app_id>/
├── config.ini
├── bin/
│   └── <binary_name>
├── <app_id>.lang
├── webui.bz2                     # 【Required】Frontend page archive
├── images/
│   └── icons/
│       └── <icon_file>.svg
├── init.d/
│   └── <system_id>.service
├── <app_id>.env                  # 【Optional】Environment variable configuration file
└── depends/                      # 【Optional】Dependency file directory
    ├── bin/                      # Executable files
    ├── lib/                      # Dynamic libraries (.so)
    ├── etc/                      # Configuration files
    ├── data/                     # Runtime data (databases/cache/state)
    └── logs/                     # Logs

Minimální konfigurace 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"
}

Hlavní požadavky:

1. Pole type musí být "iframe".
2. Formát pole path je "/<app_id>/".
3. webui.bz2 je pevný název souboru a nesmí být změněn na žádný jiný název.
4. Balíček deb musí obsahovat spustitelný program umístěný v /usr/local/<app_id>/bin/<binary_name>.
5. Specifikace pole config.ini.package musí přísně odpovídat specifikaci package balíčku Debian.
6. Backendová služba poskytuje HTTP rozhraní externě prostřednictvím Unix Socketu a při spuštění musí naslouchat na /var/api/<app_id>.sock.
7. Pokud /var/api neexistuje, musí být automaticky vytvořen; staré soubory socketu musí být před spuštěním vyčištěny.
8. Oprávnění souboru socketu musí umožňovat přístup platformového proxy.
9. Požadavky frontendu na backendová rozhraní musí procházet cestou platformového proxy s pevným formátem /v2/proxy/<app_id>.
10. Požadavky frontendu musí nést autentizační hlavičky platformy, včetně X-Csrf-Token a Cookie v hlavičkách požadavku.

Specifikace souboru socketu:

• Režim oprávnění: 0660 (čtení/zápis pro vlastníka a skupinu)
• Vlastník: <appid>:<appid> (odpovídá uživateli služby)
• Podporuje trvalá připojení HTTP (keep-alive)
• Podporuje nejméně 100 souběžných připojení
• Časový limit nečinného připojení: 30 sekund

7. Požadavky frontendu na backendová rozhraní musí procházet cestou platformového proxy: /v2/proxy/<app_id>/<api_name>.
8. Požadavky frontendu musí nést autentizační hlavičky platformy.

Konfigurace CORS a preflight požadavků: Backend musí zpracovávat preflight požadavky CORS (metoda OPTIONS) pro platformový proxy. Povolte následující:

• Origin: webový původ TOS
• Methods: GET, POST, PUT, DELETE, OPTIONS
• Headers: Content-Type, X-Csrf-Token, Cookie
• Credentials: true

Externí otevření WebUI (nová karta)

Pro aplikace, kde je backend místní spustitelnou službou a frontend statickým WebUI, otevíraným v nové kartě prohlížeče.

Struktura adresářů:

/usr/local/<app_id>/
├── config.ini
├── bin/
│   └── <binary_name>
├── <app_id>.lang
├── webui.bz2                     # 【Required】Frontend page archive
├── images/
│   └── icons/
│       └── <icon_file>.svg
├── nginx/
│   └── <app_id>.conf             # 【Required】Nginx configuration file
├── init.d/
│   └── <system_id>.service
├── <app_id>.env                  # 【Optional】Environment variable configuration file
└── depends/                      # 【Optional】Dependency file directory
    ├── bin/                      # Executable files
    ├── lib/                      # Dynamic libraries (.so)
    ├── etc/                      # Configuration files
    ├── data/                     # Runtime data (databases/cache/state)
    └── logs/                     # Logs

Minimální konfigurace 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
}

Hlavní požadavky:

1. open_path musí být true.
2. Pole path musí odpovídat trase konfiguračního souboru nginx a vést na externě poskytované HTTP rozhraní.
3. Balíček aplikace musí obsahovat konfigurační soubor nginx <app_id>.conf, jehož název souboru musí odpovídat config.ini.id.
4. Backend přímo naslouchá na <listen_port> a poskytuje HTTP rozhraní.
5. Balíček deb musí obsahovat spustitelný program umístěný v /usr/local/<app_id>/bin/<binary_name>.
6. Specifikace pole config.ini.package musí přísně odpovídat specifikaci package balíčku Debian.

Pravidla naslouchání portům:

• Musí naslouchat na 0.0.0.0 (všechna síťová rozhraní); naslouchání pouze na 127.0.0.1 je zakázáno. Naslouchání pouze na adrese loopback znemožňuje externí přístup.
• Nesmí zabírat systémem rezervované porty (22, 80, 443, 8181, 5050)
• Doporučený rozsah portů: 8000–19999

Šablona konfiguračního souboru Nginx:

Vytvořte v /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;
}

Požadavky na správu konfigurace Nginx:

• Oprávnění konfiguračního souboru: 644 (čtení/zápis pro vlastníka, čtení pro skupinu a ostatní)
• Konfigurační soubor musí být umístěn v /usr/local/<app_id>/nginx/<app_id>.conf
• Direktiva platformového nginx include načítá konfigurace v abecedním pořadí; konflikty portů mezi aplikacemi se řeší použitím jedinečných portů — dvě aplikace nemohou sdílet stejný port
• Rotace logů: přístupové/chybové logy nginx spravuje platforma; nevytvářejte vlastní logy nginx
• Nesmí obsahovat bloky server {}; používejte pouze bloky location /<app_id>/ {}

Služba bez UI

Pro aplikace služeb na pozadí bez rozhraní.

Struktura adresářů:

/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                  # 【Optional】Environment variable configuration file
└── depends/                      # 【Optional】Dependency file directory
    ├── bin/                      # Executable files
    ├── lib/                      # Dynamic libraries (.so)
    ├── etc/                      # Configuration files
    ├── data/                     # Runtime data (databases/cache/state)
    └── logs/                     # Logs

Minimální konfigurace 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"
}

Hlavní požadavky:

1. Aplikace bez UI nepotřebují pole související s frontendem, jako jsou path, type, open_path, resize, maxmin, width, height.
2. Archiv frontendu webui.bz2 není vyžadován.
3. Adresář nginx/ není vyžadován.
4. Balíček deb musí obsahovat spustitelný program umístěný v /usr/local/<app_id>/bin/<binary_name>.
5. Specifikace pole config.ini.package musí přísně odpovídat specifikaci package balíčku Debian.

Požadavky na hlášení stavu: Aplikace bez UI musí hlásit svůj provozní stav, aby platforma mohla detekovat selhání:

• Type jednotky služby systemd by měl být simple nebo forking
• Pomocí ExecStartPost systemd potvrďte úspěšné spuštění
• App Center zobrazuje „Running"/„Stopped"/„Abnormal" na základě stavu služby systemd
• Při selhání zajistí zotavení automatický restart systemd (nakonfigurovaný v souboru služby)