What Is the CasaOS Gateway Service and How Does It Create Routes?

The CasaOS Gateway service is a lightweight reverse-proxy that dynamically registers API routes at startup to expose internal services through a single entry point, while supporting runtime port changes without restarting the application.

The CasaOS Gateway service acts as the central traffic controller for the IceWhaleTech/CasaOS ecosystem, hiding internal service complexity behind a unified HTTP interface. Implemented in the github.com/IceWhaleTech/CasaOS-Common/external package, this component programmatically constructs a routing table that maps URL prefixes to internal service endpoints. Understanding how the CasaOS Gateway service initializes and manages these routes is essential for debugging connectivity issues or extending the platform's API surface.

Core Architecture and Initialization

The Gateway service lifecycle begins when the main server instantiates a management object via external.NewManagementService(RuntimePath). In service/service.go (lines 48-50), the application creates this instance and stores it in the global service repository, making it accessible throughout the application via MyService.Gateway().

The ManagementService Interface

The gateway implements the external.ManagementService interface, which defines three critical operations for runtime operation:

• CreateRoute: Registers new URL prefixes and their upstream targets
• ChangePort: Modifies the listening socket without service restart
• GetPort: Retrieves the current listening port for status reporting

How the CasaOS Gateway Service Creates Routes

During system startup, the Gateway service builds a routing table by iterating over predefined API prefixes. In main/main.go (lines 52-57), the application registers each route by calling CreateRoute with a model.Route struct:

err = service.MyService.Gateway().CreateRoute(&model.Route{
    Path:   "/v1/file",
    Target: "http://" + listener.Addr().String(),
})

The Route Structure

Each entry in the gateway's routing table follows the Route struct defined in model/route.go:

type Route struct {
    Path   string // URL prefix, e.g., "/v1/sys" or "/v1/file"
    Target string // Destination address, e.g., "http://127.0.0.1:8080"
}

When an HTTP request arrives, the Gateway matches the longest Path prefix and proxies the request to the corresponding Target. This design allows external clients to communicate through a single address (written to casaos.url at launch) while internal services remain isolated on localhost ports.

Dynamic Port Management

The CasaOS Gateway service supports runtime port reconfiguration through a background goroutine in main/main.go (lines 81-85). When config.ServerInfo.HttpPort specifies a new value, the system invokes:

err := service.MyService.Gateway().ChangePort(&changePort)

This method updates the gateway's listening socket immediately, after which CasaOS removes the port configuration from the runtime config file. Other services query the active port via MyService.Gateway().GetPort(), as seen in service/system.go for health-check endpoints and status reporting.

Implementation Details and Source Files

The Gateway service relies on several key files across the CasaOS codebase:

• service/service.go: Initializes the gateway using external.NewManagementService and stores the instance in the global service repository
• main/main.go: Registers all API prefixes via Gateway().CreateRoute and handles port changes via Gateway().ChangePort
• service/system.go: Consumes the gateway API through MyService.Gateway().GetPort() for system status reporting
• github.com/IceWhaleTech/CasaOS-Common/external: External package containing the ManagementService interface and underlying proxy implementation (often leveraging Caddy or Traefik libraries)
• model/route.go: Defines the Route structure consumed by the gateway's routing table

Summary

• The CasaOS Gateway service functions as a reverse-proxy that exposes internal APIs through a unified entry point.
• Routes are created programmatically at startup using CreateRoute with Path and Target parameters defined in model.Route.
• The gateway supports hot port changes via ChangePort without requiring application restart.
• External clients only need to know the gateway address written to casaos.url, while internal services remain hidden behind the proxy.
• Key operations are implemented in service/service.go, main/main.go, and the CasaOS-Common/external package.

Frequently Asked Questions

What is the primary purpose of the CasaOS Gateway service?

The CasaOS Gateway service acts as a lightweight reverse-proxy that consolidates access to CasaOS's internal microservices. It exposes a single HTTP endpoint for external clients while routing requests to various internal services (like file management, system controls, and cloud integrations) based on URL path prefixes.

How does the Gateway service handle API route registration?

At startup, the main application iterates through predefined API prefixes in main/main.go and calls Gateway().CreateRoute() for each endpoint. Each call accepts a model.Route struct containing a Path (URL prefix) and Target (internal service URL), which the gateway adds to its internal routing table for request proxying.

Can the CasaOS Gateway port be changed without restarting the system?

Yes. The Gateway service supports runtime port modification through the ChangePort method. A background goroutine monitors configuration changes and invokes this method to update the listening socket dynamically, allowing port adjustments without service interruption or restart.

Where is the Gateway service initialized in the CasaOS codebase?

The Gateway service initializes in service/service.go (lines 48-50) through a call to external.NewManagementService(RuntimePath). This creates the management object that implements the external.ManagementService interface and stores it in the global MyService repository for access across the application.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}