Backend Service Specification

WebUI Internal Open (Unix Socket Mode)

The backend executable is installed at:

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

The backend must create and listen on a Unix Socket:

/var/api/<app_id>.sock

Requirements:

1. /var/api must be auto-created if it does not exist.
2. Old socket files must be cleaned up before startup.
3. Socket file permissions must allow platform proxy access.
4. The backend interface protocol is HTTP-over-Unix-Socket.
5. The backend should gracefully handle SIGTERM for systemd service stopping.

Standard Log Specification:

Log Level	Use
ERROR	Service failures, startup errors, data corruption
WARN	Deprecated features, recoverable errors, configuration issues
INFO	Service lifecycle events (startup/shutdown), version information, configuration loaded
DEBUG	Detailed diagnostic information — DEBUG level logs must be disabled in production environments, only used during development and debugging

Standard Output Format:

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

Example:

[2026-05-11 16:30:00] [INFO] [main] Service started on port 8686

For systemd-managed services, prefer stdout/stderr for log output — systemd journal automatically captures both.

Service Crash Auto-Restart Limits

• Maximum restart attempts: 5 times within 60 seconds
• Once the limit is exceeded, the service enters a failed state
• The App Center displays the service as "Abnormal" after the restart limit is exceeded
• The parameters StartLimitBurst=5 and StartLimitIntervalSec=60 must be explicitly configured in the systemd service file.

WebUI External Open (HTTP Port Mode)

The backend executable is installed at:

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

The backend directly listens on <listen_port> to provide HTTP interfaces.

Requirements:

1. Directly listen on <listen_port>.
2. Serve the static WebUI homepage.
3. Provide a health check endpoint.
4. Provide business API routes; specific business logic is defined by the application.
5. Gracefully handle SIGTERM and SIGINT.

Recommended Fixed Routes:

GET /
GET /health

Recommended Business API Naming:

/api/<resource>

For compatibility with the system entry point, the following may also be supported simultaneously:

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