> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unla.amoylab.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Gateway Proxy Configuration

> Detailed MCP Gateway proxy service configuration guide

## HTTP Service Proxy Configuration

The following is a specific configuration example for HTTP service proxy, including routing, tools and other configurations:

```yaml theme={null}
name: "mock-server"              # Proxy service name, globally unique
tenant: "default"                # Tenant identifier for multi-tenant scenarios

# Routing configuration
routers:
  - server: "mock-server"       # Service name
    prefix: "/gateway/user"         # Route prefix, globally unique, non-repeatable, recommended to distinguish prefixes by service or domain+module

    # CORS configuration
    cors:
      allowOrigins:             # Development and test environments can be fully open, production should be opened as needed. (Most MCP Clients do not need to open cross-origin)
        - "*"
      allowMethods:             # Allowed request methods, open as needed, for MCP (SSE and Streamable) usually only these 3 methods are needed
        - "GET"
        - "POST"
        - "PUT"
        - "OPTIONS"
      allowHeaders:
        - "Content-Type"        # Must be allowed
        - "Authorization"       # Required for authentication needs to support carrying this key in requests
        - "Mcp-Session-Id"      # For MCP, must support carrying this key in requests, otherwise Streamable HTTP cannot be used normally
        - "mcp-protocol-version" # MCP protocol version header for protocol version negotiation
      exposeHeaders:
        - "Mcp-Session-Id"      # For MCP, when cross-origin is enabled, this key must be exposed, otherwise Streamable HTTP cannot be used normally
        - "mcp-protocol-version" # MCP protocol version header
      allowCredentials: true    # Whether to add Access-Control-Allow-Credentials: true header

# Service configuration
servers:
  - name: "mock-server"               # Service name, must match server in routers
    description: "Mock User Service"  # Service description
    allowedTools:                     # List of allowed tools (subset of tools)
      - "register_user"
      - "get_user_by_email"
      - "update_user_preferences"
      - "update_user_avatar"
    config:                                           # Service-level configuration, can be referenced in tools via {{.Config}}
      Cookie: 123                                     # Hardcoded configuration
      Authorization: 'Bearer {{ env "AUTH_TOKEN" }}'  # Configuration from environment variables, usage is '{{ env "ENV_VAR_NAME" }}'

# Tool configuration
tools:
  - name: "register_user"                                   # Tool name
    description: "Register a new user"                      # Tool description
    method: "POST"                                          # HTTP method for requesting target (upstream, backend) service
    endpoint: "http://localhost:5236/users"                 # Target service address
    headers:                                                # Request header configuration for carrying headers when requesting target service
      Content-Type: "application/json"                      # Hardcoded request header
      Authorization: "{{.Config.Authorization}}"            # Use value from service configuration
      Cookie: "{{.Config.Cookie}}"                          # Use value from service configuration
    args:                         # Parameter configuration
      - name: "username"          # Parameter name
        position: "body"          # Parameter position: header, query, path, body, form-data
        required: true            # Whether parameter is required
        type: "string"            # Parameter type
        description: "Username"   # Parameter description
        default: ""               # Default value
      - name: "email"
        position: "body"
        required: true
        type: "string"
        description: "Email"
        default: ""
    requestBody: |-                       # Request body template for dynamically generating request body, e.g., values extracted from parameters (MCP request arguments)
      {
        "username": "{{.Args.username}}",
        "email": "{{.Args.email}}"
      }
    responseBody: |-                      # Response body template for dynamically generating response body, e.g., values extracted from response
      {
        "id": "{{.Response.Data.id}}",
        "username": "{{.Response.Data.username}}",
        "email": "{{.Response.Data.email}}",
        "createdAt": "{{.Response.Data.createdAt}}"
      }

  - name: "get_user_by_email"
    description: "Get user by email"
    method: "GET"
    endpoint: "http://localhost:5236/users/email/{{.Args.email}}"
    args:
      - name: "email"
        position: "path"
        required: true
        type: "string"
        description: "Email"
        default: ""
    responseBody: |-
      {
        "id": "{{.Response.Data.id}}",
        "username": "{{.Response.Data.username}}",
        "email": "{{.Response.Data.email}}",
        "createdAt": "{{.Response.Data.createdAt}}"
      }

  - name: "update_user_preferences"
    description: "Update user preferences"
    method: "PUT"
    endpoint: "http://localhost:5236/users/{{.Args.email}}/preferences"
    headers:
      Content-Type: "application/json"
      Authorization: "{{.Request.Headers.Authorization}}"
      Cookie: "{{.Config.Cookie}}"
    args:
      - name: "email"
        position: "path"
        required: true
        type: "string"
        description: "Email"
        default: ""
      - name: "isPublic"
        position: "body"
        required: true
        type: "boolean"
        description: "Whether the user profile is public"
        default: "false"
      - name: "showEmail"
        position: "body"
        required: true
        type: "boolean"
        description: "Whether to show email in profile"
        default: "true"
      - name: "theme"
        position: "body"
        required: true
        type: "string"
        description: "User interface theme"
        default: "light"
      - name: "tags"
        position: "body"
        required: true
        type: "array"
        items:
          type: "string"
          enum: ["developer", "designer", "manager", "tester"]
        description: "User role tags"
        default: "[]"
      - name: "settings"
        position: "body"
        required: false
        type: "object"
        description: "User custom settings as key-value pairs"
        default: "{}"
      - name: "notifications"
        position: "body"
        required: false
        type: "array"
        description: "User notification preferences"
        items:
          type: "object"
          properties:
            type:
              type: "string"
              description: "Notification type (email, push, sms)"
            channel:
              type: "string"
              description: "Notification channel (marketing, system, security)"
            enabled:
              type: "boolean"
              description: "Whether this notification is enabled"
            frequency:
              type: "number"
              description: "Notification frequency (0: realtime, 1: daily, 2: weekly, 3: monthly)"
        default: "[]"
    requestBody: |-
      {
        "isPublic": {{.Args.isPublic}},
        "showEmail": {{.Args.showEmail}},
        "theme": "{{.Args.theme}}",
        "tags": {{.Args.tags}},
        "settings": {{ toJSON .Args.settings }},
        "notifications": {{ .Args.notifications }}
      }
    responseBody: |-
      {
        "id": "{{.Response.Data.id}}",
        "username": "{{.Response.Data.username}}",
        "email": "{{.Response.Data.email}}",
        "createdAt": "{{.Response.Data.createdAt}}",
        "preferences": {
          "isPublic": {{.Response.Data.preferences.isPublic}},
          "showEmail": {{.Response.Data.preferences.showEmail}},
          "theme": "{{.Response.Data.preferences.theme}}",
          "tags": {{.Response.Data.preferences.tags}},
          "settings": {{ toJSON .Response.Data.preferences.settings }},
          "notifications": {{ toJSON .Response.Data.preferences.notifications }}
        }
      }

  - name: "update_user_avatar"
    description: "Update user avatar using a URL via multipart form"
    method: "POST"
    endpoint: "http://localhost:5236/users/{{.Args.email}}/avatar"
    headers:
      Authorization: "{{.Request.Headers.Authorization}}"
      Cookie: "{{.Config.Cookie}}"
    args:
      - name: "email"
        position: "path"
        required: true
        type: "string"
        description: "Email of the user"
        default: ""
      - name: "url"
        position: "form-data"
        required: true
        type: "string"
        description: "The avatar image URL"
        default: ""
    responseBody: |-
      {
        "message": "{{.Response.Data.message}}",
        "avatarUrl": "{{.Response.Data.avatarUrl}}"
      }
```

## Configuration Explanation

### 1. Basic Configuration

<AccordionGroup>
  <Accordion icon="gear" title="port">
    MCP Gateway service listening port, default 5235
  </Accordion>

  <Accordion icon="file" title="pid">
    Process ID file path for process management and reloading
  </Accordion>

  <Accordion icon="clock" title="reload_interval">
    Configuration reload interval, default 600s
  </Accordion>

  <Accordion icon="toggle" title="reload_switch">
    Whether to enable automatic configuration reloading
  </Accordion>
</AccordionGroup>

A configuration can be treated as a namespace, recommended to distinguish by service or domain. A service contains many API interfaces, each API interface corresponds to a Tool.

* `name`: Proxy service name, globally unique, used to identify different proxy services
* `tenant`: Tenant identifier for data isolation and permission management in multi-tenant scenarios

### 2. Routing Configuration

Routing configuration is used to define request forwarding rules:

```yaml theme={null}
routers:
  - server: "mock-server"       # Service name, must match name in servers
    prefix: "/gateway/user"         # Route prefix, globally unique, non-repeatable
```

Currently, by default, 3 endpoints are derived based on `prefix`:

* SSE: `${prefix}/sse`, e.g., `/gateway/user/sse`
* SSE: `${prefix}/message`, e.g., `/gateway/user/message`
* StreamableHTTP: `${prefix}/mcp`, e.g., `/gateway/user/mcp`

### 3. CORS Configuration

Cross-Origin Resource Sharing (CORS) configuration is used to control access permissions for cross-origin requests:

```yaml theme={null}
cors:
  allowOrigins:             # Development and test environments can be fully open, production should be opened as needed. (Most MCP Clients do not need to open cross-origin)
    - "*"
  allowMethods:             # Allowed request methods, open as needed, for MCP (SSE and Streamable) usually only these 3 methods are needed
    - "GET"
    - "POST"
    - "OPTIONS"
  allowHeaders:
    - "Content-Type"        # Must be allowed
    - "Authorization"       # Required for authentication needs to support carrying this key in requests
    - "Mcp-Session-Id"      # For MCP, must support carrying this key in requests, otherwise Streamable HTTP cannot be used normally
  exposeHeaders:
    - "Mcp-Session-Id"      # For MCP, when cross-origin is enabled, this key must be exposed, otherwise Streamable HTTP cannot be used normally
  allowCredentials: true    # Whether to add Access-Control-Allow-Credentials: true header
```

<Warning>
  Usually, MCP Clients do not need to open cross-origin
</Warning>

### 4. Service Configuration

Service configuration is used to define service metadata, associated tool lists, and service-level configuration:

```yaml theme={null}
servers:
  - name: "mock-server"               # Service name, must match server in routers
    namespace: "user-service"         # Service namespace for service grouping
    description: "Mock User Service"  # Service description
    allowedTools:                     # List of allowed tools (subset of tools)
      - "register_user"
      - "get_user_by_email"
      - "update_user_preferences"
    config:                                           # Service-level configuration, can be referenced in tools via {{.Config}}
      Cookie: 123                                     # Hardcoded configuration
      Authorization: 'Bearer {{ env "AUTH_TOKEN" }}'  # Configuration from environment variables, usage is '{{ env "ENV_VAR_NAME" }}'
```

Service-level configuration can be referenced in tools via `{{.Config}}`. This can be hardcoded in the configuration file or obtained from environment variables. For environment variable injection, reference using `{{ env "ENV_VAR_NAME" }}`.

### 5. Tool Configuration

Tool configuration is used to define specific API call rules. Each parameter can set a default value (default), which will be automatically used when the parameter is not provided in the MCP request.

#### 5.1 Request Parameter Assembly

When requesting the target service, parameter assembly is involved. Currently there are several sources:

1. `.Config`: Extract values from service-level configuration
2. `.Args`: Extract values directly from request parameters
3. `.Request`: Values extracted from the request, including request headers `.Request.Headers`, request body `.Request.Body`, etc.

Parameter position (position) supports the following types:

* `header`: Parameter will be placed in request headers
* `query`: Parameter will be placed in URL query string
* `path`: Parameter will be placed in URL path
* `body`: Parameter will be placed in JSON format request body
* `form-data`: Parameter will be placed in multipart/form-data format request body, for file upload scenarios

Parameter type (type) supports the following types:

* `string`: String type
* `number`: Number type
* `boolean`: Boolean type
* `array`: Array type, needs to be used with `items` to define array element types
* `object`: Object type, can use `properties` to define object structure

For complex `array` type parameters, detailed element structures can be defined:

```yaml theme={null}
- name: "notifications"
  position: "body"
  required: false
  type: "array"
  description: "User notification preferences"
  items:
    type: "object"
    properties:
      type:
        type: "string"
        description: "Notification type (email, push, sms)"
      enabled:
        type: "boolean"
        description: "Whether this notification is enabled"
  default: "[]"
```

When using `form-data` as parameter position, no need to specify `requestBody`, the system will automatically assemble parameters into multipart/form-data format.

Additionally, `header` and `query` parameters are auto-injected into the downstream request (Header key equals the parameter name; Query is appended to the URL). For example:

```yaml theme={null}
args:
  - name: "username"   # Sends header: Username: <value>
    position: "header"
  - name: "traceId"    # Appends ?traceId=<value> to URL
    position: "query"
```

<CardGroup cols={3}>
  <Card title="Client (MCP Request)" icon="terminal">
    Example arguments from MCP client:

    ```json theme={null}
    {
      "username": "alice",
      "traceId": "t-123",
      "avatarUrl": "https://img.example.com/1.png"
    }
    ```
  </Card>

  <Card title="MCP Gateway" icon="api">
    * `header` is auto-written to downstream headers (key = param name)
    * `query` is auto-appended to the URL query string
    * `form-data` is auto-assembled as multipart/form-data

    Tool config snippet:

    ```yaml theme={null}
    tools:
      - name: demo
        method: POST
        endpoint: http://example.com/api/users
        args:
          - name: username   # Header: Username: alice
            position: header
          - name: traceId    # URL: ?traceId=t-123
            position: query
          - name: avatarUrl  # form field: avatarUrl=...
            position: form-data
    ```
  </Card>

  <Card title="Downstream Service (HTTP Request)" icon="globe">
    Actual request sent to downstream:

    ```http theme={null}
    POST /api/users?traceId=t-123 HTTP/1.1
    Host: example.com
    Username: alice
    Content-Type: multipart/form-data; boundary=---BOUNDARY

    ---BOUNDARY
    Content-Disposition: form-data; name="avatarUrl"

    https://img.example.com/1.png
    ---BOUNDARY--
    ```
  </Card>
</CardGroup>

For JSON format request body, assembly is needed in `requestBody`, for example:

```yaml theme={null}
    requestBody: |-
      {
        "isPublic": {{.Args.isPublic}},
        "showEmail": {{.Args.showEmail}},
        "theme": "{{.Args.theme}}",
        "tags": {{.Args.tags}}
      }
```

Including `endpoint` (target address) can also use the above sources to extract values, such as `http://localhost:5236/users/{{.Args.email}}/preferences` which extracts values from request parameters.

#### 5.2 Response Parameter Assembly

Response body assembly is similar to request body assembly:

1. `.Response.Data`: Values extracted from response, response must be in JSON format to be extractable
2. `.Response.Body`: Directly pass through the entire response body, ignoring response content format and directly passing to client

Both extract values via `.Response`, for example:

```yaml theme={null}
    responseBody: |-
      {
        "id": "{{.Response.Data.id}}",
        "username": "{{.Response.Data.username}}",
        "email": "{{.Response.Data.email}}",
        "createdAt": "{{.Response.Data.createdAt}}"
      }
```

## Configuration Storage

Gateway proxy configuration can be stored in the following two ways:

<CardGroup cols={2}>
  <Card title="Database Storage (Recommended)" icon="database">
    * Supports SQLite3, PostgreSQL, MySQL
    * Each configuration stored as a record
    * Supports dynamic updates and hot reloading
  </Card>

  <Card title="File Storage" icon="folder">
    * Each configuration stored separately as a YAML file
    * Similar to Nginx vhost configuration method
    * File name recommended to use service name, such as `mock-server.yaml`
  </Card>
</CardGroup>

## MCP Service Proxy Configuration

In addition to proxying HTTP services, MCP Gateway also supports proxying MCP services. Currently, stdio, SSE, and streamable-http three transport protocols are all supported.

### Configuration Example

The following is a complete MCP service proxy configuration example:

```yaml theme={null}
name: "proxy-mcp-exp"
tenant: "default"

routers:
  - server: "amap-maps"
    prefix: "/gateway/stdio-proxy"
    cors:
      allowOrigins:
        - "*"
      allowMethods:
        - "GET"
        - "POST"
        - "OPTIONS"
      allowHeaders:
        - "Content-Type"
        - "Authorization"
        - "Mcp-Session-Id"
      exposeHeaders:
        - "Mcp-Session-Id"
      allowCredentials: true
  - server: "mock-user-sse"
    prefix: "/gateway/sse-proxy"
    cors:
      allowOrigins:
        - "*"
      allowMethods:
        - "GET"
        - "POST"
        - "OPTIONS"
      allowHeaders:
        - "Content-Type"
        - "Authorization"
        - "Mcp-Session-Id"
      exposeHeaders:
        - "Mcp-Session-Id"
      allowCredentials: true
  - server: "mock-user-mcp"
    prefix: "/gateway/streamable-http-proxy"
    cors:
      allowOrigins:
        - "*"
      allowMethods:
        - "GET"
        - "POST"
        - "OPTIONS"
      allowHeaders:
        - "Content-Type"
        - "Authorization"
        - "Mcp-Session-Id"
      exposeHeaders:
        - "Mcp-Session-Id"
      allowCredentials: true

mcpServers:
  - type: "stdio"
    name: "amap-maps"
    command: "npx"
    args:
      - "-y"
      - "@amap/amap-maps-mcp-server"
    env:
      AMAP_MAPS_API_KEY: "{{.Request.Headers.Apikey}}"

  - type: "sse"
    name: "mock-user-sse"
    url: "http://localhost:3000/gateway/user/sse"

  - type: "streamable-http"
    name: "mock-user-mcp"
    url: "http://localhost:3000/gateway/user/mcp"
```

### Configuration Explanation

#### 1. MCP Service Types

MCP Gateway supports the following three types of MCP service proxies:

<AccordionGroup>
  <Accordion icon="terminal" title="stdio Type">
    * Communicate with MCP service processes via standard input/output
    * Suitable for MCP services that need local startup, such as third-party SDKs
    * Configuration parameters include `command`, `args`, and `env`
  </Accordion>

  <Accordion icon="stream" title="SSE Type">
    * Forward MCP client requests to upstream services supporting SSE
    * Suitable for existing MCP services supporting SSE protocol
    * Only need to configure `url` parameter pointing to upstream SSE service address
  </Accordion>

  <Accordion icon="globe" title="streamable-http Type">
    * Forward MCP client requests to upstream services supporting streamable HTTP
    * Suitable for existing upstream services supporting MCP protocol
    * Only need to configure `url` parameter pointing to upstream MCP service address
  </Accordion>
</AccordionGroup>

#### 2. stdio Type Configuration

stdio type MCP service configuration example:

```yaml theme={null}
mcpServers:
  - type: "stdio"
    name: "amap-maps"                                   # Service name
    command: "npx"                                      # Command to execute
    args:                                               # Command arguments
      - "-y"
      - "@amap/amap-maps-mcp-server"
    env:                                                # Environment variables
      AMAP_MAPS_API_KEY: "{{.Request.Headers.Apikey}}"  # Extract value from request headers
```

Environment variables can be set via the `env` field, supporting value extraction from requests, for example `{{.Request.Headers.Apikey}}` means extract the Apikey value from request headers.

#### 3. SSE Type Configuration

SSE type MCP service configuration example:

```yaml theme={null}
mcpServers:
  - type: "sse"
    name: "mock-user-sse"                           # Service name
    url: "http://localhost:3000/gateway/user/sse"   # Upstream SSE service address, usually ends with /sse, actual depends on upstream service
```

#### 4. streamable-http Type Configuration

streamable-http type MCP service configuration example:

```yaml theme={null}
mcpServers:
  - type: "streamable-http"
    name: "mock-user-mcp"                           # Service name
    url: "http://localhost:3000/gateway/user/mcp"   # Upstream MCP service address, usually ends with /mcp, actual depends on upstream service
```

#### 5. Routing Configuration

For MCP service proxy, routing configuration is similar to HTTP service proxy. CORS should be configured according to actual situation (usually production environments generally do not enable cross-origin):

```yaml theme={null}
routers:
  - server: "amap-maps"               # Service name, must match name in mcpServers
    prefix: "/gateway/stdio-proxy"    # Route prefix, globally unique
    cors:
      allowOrigins:
        - "*"
      allowMethods:
        - "GET"
        - "POST"
        - "OPTIONS"
      allowHeaders:
        - "Content-Type"
        - "Authorization"
        - "Mcp-Session-Id"        # MCP service must include this header
      exposeHeaders:
        - "Mcp-Session-Id"        # MCP service must expose this header
      allowCredentials: true
```

<Warning>
  For MCP services, `Mcp-Session-Id` in request and response headers must be supported, otherwise clients cannot use it normally.
</Warning>

## Advanced Configuration

### Notifier Configuration

Notifier is used to configure reload notifications, supporting multiple methods:

<AccordionGroup>
  <Accordion icon="signal" title="Signal Notification">
    Notify via system signals, suitable for single-machine deployment

    ```yaml theme={null}
    notifier:
      type: "signal"
      signal:
        signal: "SIGHUP"
        pid: "/var/run/mcp-gateway.pid"
    ```
  </Accordion>

  <Accordion icon="api" title="API Notification">
    Notify via HTTP API, suitable for remote management

    ```yaml theme={null}
    notifier:
      type: "api"
      api:
        port: 5235
        target_url: "http://localhost:5235/_reload"
    ```
  </Accordion>

  <Accordion icon="database" title="Redis Notification">
    Notify via Redis publish/subscribe, suitable for cluster deployment

    ```yaml theme={null}
    notifier:
      type: "redis"
      redis:
        cluster_type: "single"
        addr: "localhost:6379"
        topic: "mcp-gateway:reload"
    ```
  </Accordion>
</AccordionGroup>

### Environment Variable Injection

Environment variables can be used in configuration, supporting default values:

```yaml theme={null}
# Basic syntax
port: ${MCP_GATEWAY_PORT:5235}  # Use environment variable, default value 5235

# String format
logger:
  level: "${LOGGER_LEVEL:info}"  # Use environment variable, default value info

# Use in service configuration
config:
  ApiKey: '{{ env "API_KEY" }}'
  BaseUrl: '{{ env "API_BASE_URL" "http://localhost:8080" }}'  # With default value
```

### Template Functions

In request and response body templates, template functions can be used to handle complex data:

<AccordionGroup>
  <Accordion icon="function" title="toJSON">
    Convert objects or arrays to JSON strings for handling complex data structures

    ```yaml theme={null}
    requestBody: |-
      {
        "settings": {{ toJSON .Args.settings }},
        "notifications": {{ toJSON .Args.notifications }}
      }
    ```
  </Accordion>

  <Accordion icon="variable" title="Direct Use">
    For simple arrays and objects, variables can be used directly

    ```yaml theme={null}
    requestBody: |-
      {
        "tags": {{.Args.tags}},
        "preferences": {{ .Args.preferences }}
      }
    ```
  </Accordion>
</AccordionGroup>

<Note>
  Using the `toJSON` function ensures complex objects and arrays are correctly serialized to JSON format, especially suitable for nested structures and data containing special characters.
</Note>

### Complex Parameter Processing Example

The following is a complete example of handling complex parameters, showing how to define and use object and array type parameters:

```yaml theme={null}
args:
  - name: "settings"
    position: "body"
    required: false
    type: "object"
    description: "User custom settings as key-value pairs"
    default: "{}"
  - name: "notifications"
    position: "body"
    required: false
    type: "array"
    description: "User notification preferences"
    items:
      type: "object"
      properties:
        type:
          type: "string"
          description: "Notification type (email, push, sms)"
        channel:
          type: "string"
          description: "Notification channel (marketing, system, security)"
        enabled:
          type: "boolean"
          description: "Whether this notification is enabled"
        frequency:
          type: "number"
          description: "Notification frequency (0: realtime, 1: daily, 2: weekly, 3: monthly)"
    default: "[]"

requestBody: |-
  {
    "settings": {{ toJSON .Args.settings }},
    "notifications": {{ .Args.notifications }}
  }

responseBody: |-
  {
    "settings": {{ toJSON .Response.Data.preferences.settings }},
    "notifications": {{ toJSON .Response.Data.preferences.notifications }}
  }
```

### File Upload Processing

Supports file upload scenarios:

```yaml theme={null}
args:
  - name: "file"
    position: "form-data"
    required: true
    type: "string"
    description: "File to upload"
  - name: "description"
    position: "form-data"
    required: false
    type: "string"
    description: "File description"
```

## Best Practices

<AccordionGroup>
  <Accordion icon="shield-check" title="Security">
    * Use environment variables to store sensitive information (such as database passwords, API keys)
    * Limit CORS Origins in production environments, avoid using "\*"
    * Enable OAuth2 authentication and appropriate authorization mechanisms
    * Regularly rotate API keys and tokens
    * Use encrypted Redis connections to store session data
  </Accordion>

  <Accordion icon="zap" title="Performance">
    * Set reasonable timeout and reload intervals
    * Use Redis clusters to improve session storage performance
    * Choose appropriate log levels, avoid excessive debug logs
    * Use connection pools to reduce connection overhead
    * Cache frequently called APIs
    * Avoid complex calculations in templates
  </Accordion>

  <Accordion icon="tools" title="Maintainability">
    * Use meaningful tool and service names
    * Add detailed description information
    * Keep configuration files clean and readable
    * Configure log rotation to avoid disk space shortage
    * Monitor PID files and process status
    * Set appropriate notifier types for configuration management convenience
    * Regularly check and update configurations
  </Accordion>

  <Accordion icon="test-tube" title="Testing">
    * Thoroughly test configurations in development environments
    * Use mock services for integration testing
    * Verify all parameters and response formats
    * Test error handling and edge cases
  </Accordion>
</AccordionGroup>

## Configuration Validation

Before applying configuration, it is recommended to perform the following validations:

<Steps>
  <Step title="Syntax Check">
    Ensure YAML syntax is correct with no indentation errors
  </Step>

  <Step title="Environment Variable Verification">
    Check if all required environment variables are set
  </Step>

  <Step title="Storage Connection Test">
    Verify database or Redis connection configuration is correct
  </Step>

  <Step title="Reference Verification">
    Check if all reference relationships are correct, such as server name matching
  </Step>

  <Step title="Template Verification">
    Verify Go Template syntax and variable references
  </Step>

  <Step title="Endpoint Testing">
    Ensure all endpoints are accessible
  </Step>

  <Step title="Permission Verification">
    Ensure PID file path has write permissions
  </Step>
</Steps>

<Note>
  For more information on Go Template usage, please refer to [Template Usage Guide](/en/configuration/templates).
</Note>