概述

数据库凭证安全（零暴露版）是一项文档型技能，旨在指导如何使用 MGC Blackbox 安全管理数据库凭证。支持 MySQL、PostgreSQL、SQLite、MariaDB 等多种数据库。该技能使 AI 代理能够在执行数据库操作时，始终不暴露数据库密码或连接字符串给 AI 模型。

本技能不含任何可执行代码，适用于自动审批流程，安全性高。

本技能实现的功能

阅读本说明后，AI 代理将能够：

• 将数据库凭证（MySQL、PostgreSQL、SQLite、MariaDB 等）安全地存储在 MGC Blackbox 中
• 在运行时检索凭证，且 AI 不会看到明文内容
• 通过本地脚本执行数据库查询
• 安全管理多个数据库连接
• 在不修改代码的情况下完成凭证轮换

先决条件

1. 安装 MGC Blackbox：pip install mgc-blackbox
2. 启动 MGC 服务：mgc（默认运行于 http://127.0.0.1:57219）
3. 令牌文件路径：~/.mgc/database/mgc_black_box/.mgc_token

存储数据库凭证

步骤一：准备凭证文件

创建一个包含数据库连接信息的 JSON 文件：

{
  "host": "localhost",
  "port": 3306,
  "database": "my_database",
  "user": "db_user",
  "password": "your_password"
}

步骤二：存入 MGC

重要提示： 对于 AI 代理，请使用 MCP 工具。CLI 可能在某些环境中引发端口冲突。

推荐方式：MCP 接口

• 使用 mgc_save MCP 工具存储凭证
• 使用 mgc_get MCP 工具检索凭证

替代方式：CLI（仅限本地开发）

mgc_save info_type=config info_owner=my_database < credentials.json

数据库凭证使用模式（概念性）

本地脚本模式

一个安全的数据库脚本应遵循以下流程：

1. 从 MGC 获取凭证（对 AI 不可见）
2. 使用获取的凭证连接数据库
3. 执行查询操作
4. 返回结果（仅非敏感数据）

脚本不得打印或暴露数据库凭证。

概念性代码结构

function execute_query(sql):
    credentials = retrieve_from_mgc("my_database")
    connection = connect(credentials)
    result = connection.execute(sql)
    connection.close()
    return result

MGC Blackbox API 参考

服务端点

• 基础地址：http://127.0.0.1:57219
• 令牌文件路径：~/.mgc/database/mgc_black_box/.mgc_token
• 令牌：从令牌文件读取的字符串，所有 API 调用均需提供

获取凭证 API

端点： /api/mgc/sensitive/get

方法： POST

请求头：

• X-MGC-Token: （从令牌文件读取的字符串）
• Content-Type: application/json

请求体字段：

• info_type: "config"
• info_owner: 自定义标识符

响应字段：

• code: 状态码
• data.content: 存储的凭证 JSON 字符串

保存凭证 API

端点： /api/mgc/sensitive/save

方法： POST

请求头： 与上述相同

请求体字段：

• info_type: "config"
• info_owner: 标识符
• content: 凭证的 JSON 字符串

提示： 用户也可通过 MGC WebUI 手动存储凭证，访问地址为 http://127.0.0.1:57218/skill

安全最佳实践

1. 不要在代码中硬编码凭证
2. 使用 MGC 进行凭证存储
3. 仅在运行时检索凭证
4. 不要记录或打印凭证
5. 定期轮换凭证
6. 每个数据库使用独立凭证

常见使用模式

Python 数据库连接（概念性）

import mysql.connector

def get_connection(credentials):
    return mysql.connector.connect(
        host=credentials["host"],
        port=credentials["port"],
        database=credentials["database"],
        user=credentials["user"],
        password=credentials["password"]
    )

def execute_query(sql):
    creds = retrieve_from_mgc("my_mysql")
    conn = get_connection(creds)
    cursor = conn.cursor()
    cursor.execute(sql)
    result = cursor.fetchall()
    cursor.close()
    conn.close()
    return result

使用场景

• 数据库管理脚本
• 自动化备份任务
• 数据迁移工具
• 应用程序数据库访问
• 多环境管理（开发 / 预发布 / 生产）

许可证

MIT