Prism/internal/api/openapi/spec.yaml

openapi: 3.0.3
info:
  title: Prism Management API
  description: |
    Prism 代理网关管理接口（默认端口 8080）。

    除 `auth/login`、`auth/status` 与 OpenAPI 文档外，启用登录后需在请求头携带以下任一凭证：
    - `Authorization: Bearer <token>`（登录接口返回的短期 token）
    - `Authorization: Bearer <api_key>` 或 `X-API-Key: <api_key>`（在系统设置中申请的 API Key）
  version: 1.0.0
  contact:
    name: Prism

servers:
  - url: /api/v1
    description: 管理 API v1

tags:
  - name: Auth
  - name: Dashboard
  - name: Subscriptions
  - name: Proxies
  - name: Countries
  - name: Outbound
  - name: Rules
  - name: TrafficLogs
  - name: Settings
  - name: System
  - name: Logs

paths:
  /auth/login:
    post:
      tags: [Auth]
      summary: 登录
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [password]
              properties:
                password:
                  type: string
      responses:
        '200':
          description: 登录成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          description: 登录尝试过多

  /auth/status:
    get:
      tags: [Auth]
      summary: 是否启用登录认证
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  enabled:
                    type: boolean

  /api-keys:
    get:
      tags: [Auth]
      summary: API Key 列表
      security:
        - bearerAuth: []
      responses:
        '200':
          description: OK
    post:
      tags: [Auth]
      summary: 申请 API Key
      description: 完整 Key 仅在创建响应中返回一次，请妥善保存
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
      responses:
        '201':
          description: Created

  /api-keys/{id}:
    parameters:
      - $ref: '#/components/parameters/IdPath'
    delete:
      tags: [Auth]
      summary: 吊销 API Key
      security:
        - bearerAuth: []
      responses:
        '200':
          description: OK

  /dashboard:
    get:
      tags: [Dashboard]
      summary: 监控大盘
      security:
        - bearerAuth: []
      parameters:
        - name: live_domain_limit
          in: query
          schema:
            type: integer
            default: 50
            maximum: 500
        - name: live_domain_offset
          in: query
          schema:
            type: integer
            default: 0
        - name: live_node_limit
          in: query
          schema:
            type: integer
            default: 50
            maximum: 500
        - name: live_node_offset
          in: query
          schema:
            type: integer
            default: 0
        - name: period_domain_limit
          in: query
          schema:
            type: integer
            default: 50
            maximum: 500
        - name: period_domain_offset
          in: query
          schema:
            type: integer
            default: 0
        - name: period_node_limit
          in: query
          schema:
            type: integer
            default: 50
            maximum: 500
        - name: period_node_offset
          in: query
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: OK

  /connections:
    get:
      tags: [Dashboard]
      summary: 当前活跃连接
      security:
        - bearerAuth: []
      responses:
        '200':
          description: OK

  /subscriptions:
    get:
      tags: [Subscriptions]
      summary: 订阅列表
      security:
        - bearerAuth: []
      responses:
        '200':
          description: OK
    post:
      tags: [Subscriptions]
      summary: 创建订阅
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Subscription'
      responses:
        '201':
          description: Created

  /subscriptions/{id}:
    parameters:
      - $ref: '#/components/parameters/IdPath'
    put:
      tags: [Subscriptions]
      summary: 更新订阅
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Subscription'
      responses:
        '200':
          description: OK
    delete:
      tags: [Subscriptions]
      summary: 删除订阅
      security:
        - bearerAuth: []
      responses:
        '200':
          description: OK

  /subscriptions/{id}/refresh:
    parameters:
      - $ref: '#/components/parameters/IdPath'
    post:
      tags: [Subscriptions]
      summary: 刷新订阅
      security:
        - bearerAuth: []
      responses:
        '200':
          description: OK

  /proxies:
    get:
      tags: [Proxies]
      summary: 节点列表
      security:
        - bearerAuth: []
      parameters:
        - name: source
          in: query
          schema:
            type: string
            enum: [manual, subscription]
        - name: subscription_id
          in: query
          schema:
            type: integer
        - name: country
          in: query
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
            maximum: 500
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: OK
    post:
      tags: [Proxies]
      summary: 添加手动节点
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                type:
                  type: string
                raw_config:
                  type: string
      responses:
        '201':
          description: Created

  /proxies/export:
    get:
      tags: [Proxies]
      summary: 导出手动节点
      security:
        - bearerAuth: []
      parameters:
        - name: format
          in: query
          schema:
            type: string
            enum: [json, links, text, txt]
            default: json
      responses:
        '200':
          description: 文件下载

  /proxies/import:
    post:
      tags: [Proxies]
      summary: 导入手动节点
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                mode:
                  type: string
                  enum: [append, replace]
                text:
                  type: string
                nodes:
                  type: array
                  items:
                    type: object
      responses:
        '200':
          description: OK

  /proxies/{id}:
    parameters:
      - $ref: '#/components/parameters/IdPath'
    put:
      tags: [Proxies]
      summary: 更新节点
      security:
        - bearerAuth: []
      responses:
        '200':
          description: OK
    delete:
      tags: [Proxies]
      summary: 删除手动节点
      security:
        - bearerAuth: []
      responses:
        '200':
          description: OK

  /proxies/{id}/test:
    parameters:
      - $ref: '#/components/parameters/IdPath'
    post:
      tags: [Proxies]
      summary: 单节点测速
      security:
        - bearerAuth: []
      responses:
        '200':
          description: OK

  /proxies/test-all:
    post:
      tags: [Proxies]
      summary: 全部节点测速
      security:
        - bearerAuth: []
      responses:
        '200':
          description: OK

  /proxies/rebuild-countries:
    post:
      tags: [Proxies]
      summary: 重新识别节点国家
      security:
        - bearerAuth: []
      responses:
        '200':
          description: OK

  /countries:
    get:
      tags: [Countries]
      summary: 国家统计
      security:
        - bearerAuth: []
      responses:
        '200':
          description: OK

  /outbound:
    get:
      tags: [Outbound]
      summary: 出站概览
      security:
        - bearerAuth: []
      responses:
        '200':
          description: OK

  /outbound/groups/{name}:
    parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
    put:
      tags: [Outbound]
      summary: 切换策略组节点
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [proxy]
              properties:
                proxy:
                  type: string
      responses:
        '200':
          description: OK

  /outbound/default-policy:
    put:
      tags: [Outbound]
      summary: 设置默认出站
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [policy]
              properties:
                policy:
                  type: string
      responses:
        '200':
          description: OK

  /traffic-logs:
    get:
      tags: [TrafficLogs]
      summary: 请求日志
      security:
        - bearerAuth: []
      parameters:
        - name: keyword
          in: query
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: OK

  /rules:
    get:
      tags: [Rules]
      summary: 规则列表
      security:
        - bearerAuth: []
      parameters:
        - name: source
          in: query
          schema:
            type: string
      responses:
        '200':
          description: OK
    post:
      tags: [Rules]
      summary: 添加手动规则
      security:
        - bearerAuth: []
      responses:
        '201':
          description: Created

  /rules/export:
    get:
      tags: [Rules]
      summary: 导出手动规则
      security:
        - bearerAuth: []
      parameters:
        - name: format
          in: query
          schema:
            type: string
            enum: [json, text, txt, clash]
            default: json
      responses:
        '200':
          description: 文件下载

  /rules/import:
    post:
      tags: [Rules]
      summary: 导入手动规则
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                mode:
                  type: string
                  enum: [append, replace]
                text:
                  type: string
                rules:
                  type: array
                  items:
                    type: object
      responses:
        '200':
          description: OK

  /rules/merged:
    get:
      tags: [Rules]
      summary: 合成规则预览
      security:
        - bearerAuth: []
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
        - name: offset
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: OK

  /rules/test:
    post:
      tags: [Rules]
      summary: 规则命中测试
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [url]
              properties:
                url:
                  type: string
      responses:
        '200':
          description: OK

  /rules/{id}:
    parameters:
      - $ref: '#/components/parameters/IdPath'
    put:
      tags: [Rules]
      summary: 更新规则
      security:
        - bearerAuth: []
      responses:
        '200':
          description: OK
    delete:
      tags: [Rules]
      summary: 删除手动规则
      security:
        - bearerAuth: []
      responses:
        '200':
          description: OK

  /settings:
    get:
      tags: [Settings]
      summary: 获取系统设置
      security:
        - bearerAuth: []
      responses:
        '200':
          description: OK
    put:
      tags: [Settings]
      summary: 更新系统设置
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties:
                type: string
      responses:
        '200':
          description: OK

  /logs:
    get:
      tags: [Logs]
      summary: 运行日志
      security:
        - bearerAuth: []
      parameters:
        - name: level
          in: query
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: OK

  /audit-logs:
    get:
      tags: [Logs]
      summary: 审计日志
      security:
        - bearerAuth: []
      responses:
        '200':
          description: OK

  /system/status:
    get:
      tags: [System]
      summary: 系统状态
      security:
        - bearerAuth: []
      responses:
        '200':
          description: OK

  /system/reload:
    post:
      tags: [System]
      summary: 重载内核
      security:
        - bearerAuth: []
      responses:
        '200':
          description: OK

  /system/geo:
    get:
      tags: [System]
      summary: Geo 数据状态
      security:
        - bearerAuth: []
      responses:
        '200':
          description: OK

  /system/geo/update:
    post:
      tags: [System]
      summary: 更新 Geo 数据
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                force:
                  type: boolean
      responses:
        '200':
          description: OK

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 登录 token 或 API Key（prism_ 开头）
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: 系统设置中申请的 API Key

  parameters:
    IdPath:
      name: id
      in: path
      required: true
      schema:
        type: integer
        format: int64

  schemas:
    Subscription:
      type: object
      properties:
        name:
          type: string
        url:
          type: string
        type:
          type: string
          description: auto / clash / links
        interval_sec:
          type: integer
        enabled:
          type: boolean

    Error:
      type: object
      properties:
        error:
          type: string

  responses:
    Unauthorized:
      description: 未授权
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'