API Server 配置

配置文件支持使用 ${VAR:default} 语法进行环境变量注入。如果环境变量未设置，将使用默认值。常见的做法是通过不同的 .env、.env.development、.env.prod 进行注入，当然也可以直接修改配置写死一个值。

日志配置

日志配置用于控制应用程序的日志输出行为：

logger:
  level: "${APISERVER_LOGGER_LEVEL:info}"                                         # 日志级别：debug, info, warn, error
  format: "${APISERVER_LOGGER_FORMAT:console}"                                    # 日志格式：json, console
  output: "${APISERVER_LOGGER_OUTPUT:stdout}"                                     # 输出方式：stdout, file
  file_path: "${APISERVER_LOGGER_FILE_PATH:/var/log/unla/apiserver.log}"          # 日志文件路径（当 output 为 file 时）
  max_size: ${APISERVER_LOGGER_MAX_SIZE:100}                                      # 日志文件最大大小（MB）
  max_backups: ${APISERVER_LOGGER_MAX_BACKUPS:3}                                  # 保留的备份文件数量
  max_age: ${APISERVER_LOGGER_MAX_AGE:7}                                          # 备份文件保留天数
  compress: ${APISERVER_LOGGER_COMPRESS:true}                                     # 是否压缩备份文件
  color: ${APISERVER_LOGGER_COLOR:true}                                           # 控制台输出是否使用颜色
  stacktrace: ${APISERVER_LOGGER_STACKTRACE:true}                                 # 错误日志是否包含堆栈跟踪

日志级别

支持 debug, info, warn, error 四个级别

输出格式

支持 json 结构化输出和 console 可读格式

文件轮转

自动管理日志文件大小和数量

堆栈跟踪

错误日志可包含详细的调用栈信息

国际化配置

国际化配置用于支持多语言界面：

i18n:
  path: "${APISERVER_I18N_PATH:/etc/unla/i18n}"                                   # 翻译文件路径

翻译文件路径应该包含各种语言的翻译文件，用于支持多语言用户界面。

聊天消息数据库配置

该配置主要针对后台的聊天消息存储的配置（当然这里是可以和代理配置存放在同一个数据库），主要用于存储 Web 界面中的聊天会话和消息数据。

聊天消息数据库主要用于存储通过 Web 界面进行的 MCP 聊天记录，与网关代理配置的存储是分开的。

支持的数据库

目前支持 3 种数据库：

SQLite3

适合开发环境和小规模部署

PostgreSQL

推荐用于生产环境

MySQL

传统关系型数据库选择

配置示例

database:
  type: "${APISERVER_DB_TYPE:sqlite}"               # 数据库类型（sqlite,postgres, mysql）
  host: "${APISERVER_DB_HOST:localhost}"            # 数据库主机地址
  port: ${APISERVER_DB_PORT:5432}                   # 数据库端口
  user: "${APISERVER_DB_USER:postgres}"             # 数据库用户名
  password: "${APISERVER_DB_PASSWORD:example}"      # 数据库密码
  dbname: "${APISERVER_DB_NAME:./unla.db}"          # 数据库名称或文件路径
  sslmode: "${APISERVER_DB_SSL_MODE:disable}"       # 数据库连接的 SSL 模式

若有需要增加数据库支持可以到 Issue 里请求支持，或者可以直接实现对应的 impl 并提交 PR :)

网关代理存储配置

这里是用来存放网关代理配置的，也就是对应的从 MCP 到 API 映射的那个配置。目前支持 2 种存储方式：

db 存储

存到数据库，每个配置是一条记录。目前支持三种数据库：SQLite3、PostgreSQL、MySQL

api 存储

通过 API 端点存储配置，允许使用外部配置管理系统

revision_history_limit 参数控制系统保留的配置版本历史数量，有助于配置变更的回滚和审计。默认保留 10 个版本。

配置示例

storage:
  type: "${GATEWAY_STORAGE_TYPE:db}"                                      # 存储类型：db, api
  revision_history_limit: ${GATEWAY_STORAGE_REVISION_HISTORY_LIMIT:10}    # 保留的版本历史数量

  # 数据库配置（当 type 为 'db' 时使用）
  database:
    type: "${GATEWAY_DB_TYPE:sqlite}"                   # 数据库类型（sqlite,postgres, mysql）
    host: "${GATEWAY_DB_HOST:localhost}"                # 数据库主机地址
    port: ${GATEWAY_DB_PORT:5432}                       # 数据库端口
    user: "${GATEWAY_DB_USER:postgres}"                 # 数据库用户名
    password: "${GATEWAY_DB_PASSWORD:example}"          # 数据库密码
    dbname: "${GATEWAY_DB_NAME:./unla.db}"              # 数据库名称或文件路径
    sslmode: "${GATEWAY_DB_SSL_MODE:disable}"           # 数据库连接的 SSL 模式

  # API 配置（当 type 为 'api' 时使用）
  api:
    url: "${GATEWAY_STORAGE_API_URL:}"                  # API 端点 URL
    configJSONPath: "${GATEWAY_STORAGE_API_CONFIG_JSON_PATH:}"  # API 响应中配置的 JSON 路径
    timeout: "${GATEWAY_STORAGE_API_TIMEOUT:30s}"       # 请求超时时间

通知配置

通知配置模块主要是用来当配置更新的时候如何让 mcp-gateway 感知到更新并进行热重载而无需重启服务。

支持的通知方式

signal

通过发送操作系统信号量来通知，类似 kill -SIGHUP <pid> 或者 nginx -s reload 这种方式

api

通过调用一个 API 的方式通知，mcp-gateway 会监听一个独立的端口

redis

通过 redis 的发布/订阅功能通知，适合单机或集群部署时使用

composite

组合通知，通过多种方式组合，默认 signal 和 api 一定会开启

通知角色

sender

发送者，负责发送通知，apiserver 只能走这个模式

receiver

接收者，负责接收通知，单机的 mcp-gateway 建议只走这个模式

both

既是发送者又是接收者，集群部署的 mcp-gateway 可以走这个方式

配置示例

notifier:
  role: "${APISERVER_NOTIFIER_ROLE:sender}"  # 角色：'sender'（发送者）或 'receiver'（接收者）
  type: "${APISERVER_NOTIFIER_TYPE:signal}"  # 类型：'signal'（信号）、'api'、'redis' 或 'composite'（组合）

  # 信号配置（当 type 为 'signal' 时使用）
  signal:
    signal: "${APISERVER_NOTIFIER_SIGNAL:SIGHUP}"                       # 要发送的信号
    pid: "${APISERVER_NOTIFIER_SIGNAL_PID:/var/run/mcp-gateway.pid}"    # PID 文件路径

  # API 配置（当 type 为 'api' 时使用）
  api:
    port: ${APISERVER_NOTIFIER_API_PORT:5235}                                           # API 端口
    target_url: "${APISERVER_NOTIFIER_API_TARGET_URL:http://localhost:5235/_reload}"    # 重载端点

  # Redis 配置（当 type 为 'redis' 时使用）
  redis:
    addr: "${APISERVER_NOTIFIER_REDIS_ADDR:localhost:6379}"                             # Redis 地址
    password: "${APISERVER_NOTIFIER_REDIS_PASSWORD:UseStrongPasswordIsAGoodPractice}"   # Redis 密码
    db: ${APISERVER_NOTIFIER_REDIS_DB:0}                                                # Redis 数据库编号
    topic: "${APISERVER_NOTIFIER_REDIS_TOPIC:mcp-gateway:reload}"                       # Redis 发布/订阅主题

超级管理员配置

超级管理员配置用于设置系统初始管理员账户，每次启动 apiserver 会自动检测是否存在，若不存在会自动创建。

super_admin:
  username: "${SUPER_ADMIN_USERNAME:admin}"                                     # 超级管理员用户名
  password: "${SUPER_ADMIN_PASSWORD:changeme-please-use-a-secure-password}"     # 超级管理员密码（生产环境请修改）

强烈建议生产环境或者公网环境使用强密码！

JWT 配置

JWT 配置用于设置 web 认证相关的参数：

jwt:
  secret_key: "${APISERVER_JWT_SECRET_KEY:changeme-please-generate-a-random-secret}"  # JWT密钥（生产环境请修改）
  duration: "${APISERVER_JWT_DURATION:24h}"                                           # Token有效期

强烈建议生产环境或者公网环境使用强密码！

OAuth 登录配置

OAuth 配置用于支持第三方登录功能，目前支持 Google 和 GitHub 登录。配置了对应的 client_id 和 client_secret 后，Web 界面会自动启用 OAuth 登录选项。

oauth:
  # Google OAuth 配置
  google:
    client_id: "${OAUTH_GOOGLE_CLIENT_ID:}"                    # Google OAuth Client ID
    client_secret: "${OAUTH_GOOGLE_CLIENT_SECRET:}"            # Google OAuth Client Secret

  # GitHub OAuth 配置
  github:
    client_id: "${OAUTH_GITHUB_CLIENT_ID:}"                    # GitHub OAuth Client ID
    client_secret: "${OAUTH_GITHUB_CLIENT_SECRET:}"            # GitHub OAuth Client Secret

Google 登录

支持 Google 账户登录，需要在 Google Cloud Console 配置 OAuth 应用

GitHub 登录

支持 GitHub 账户登录，需要在 GitHub 创建 OAuth 应用

只有配置了对应的 client_id 和 client_secret 才会启用相应的 OAuth 登录选项
OAuth 登录与本地账户登录可以同时使用
首次通过 OAuth 登录的用户会自动创建账户

配置文件位置

默认情况下，配置文件应放置在以下位置：

容器部署：/app/configs/apiserver.yaml
二进制部署：./configs/apiserver.yaml

您可以通过环境变量或命令行参数指定自定义的配置文件路径。

快速开始

安装部署

配置说明

Web 配置

客户端使用

开发文档

API 文档

端点示例

日志配置

日志级别

输出格式

文件轮转

堆栈跟踪

国际化配置

聊天消息数据库配置

支持的数据库

SQLite3

PostgreSQL

MySQL

配置示例

网关代理存储配置

配置示例

通知配置

支持的通知方式

signal

api

redis

composite

通知角色

配置示例

超级管理员配置

JWT 配置

OAuth 登录配置

Google 登录

GitHub 登录

配置文件位置

​日志配置

日志级别

输出格式

文件轮转

堆栈跟踪

​国际化配置

​聊天消息数据库配置

​支持的数据库

SQLite3

PostgreSQL

MySQL

​配置示例

​网关代理存储配置

​配置示例

​通知配置

​支持的通知方式

signal

api

redis

composite

​通知角色

​配置示例

​超级管理员配置

​JWT 配置

​OAuth 登录配置

Google 登录

GitHub 登录

​配置文件位置

日志配置

国际化配置

聊天消息数据库配置

支持的数据库

配置示例

网关代理存储配置

配置示例

通知配置

支持的通知方式

通知角色

配置示例

超级管理员配置

JWT 配置

OAuth 登录配置

配置文件位置