McpHelper.PostgreSQL 1.0.9

McpHelper.PostgreSQL

McpHelper PostgreSQL 数据库认证扩展，提供基于 PostgreSQL 数据库的 API Key 认证功能。

功能特性

• 数据库认证 - 从 PostgreSQL 数据库验证 API Key
• 认证缓存 - 内置缓存机制，减少数据库查询
• 认证日志 - 可选的认证日志记录功能
• 健康检查 - 支持数据库连接健康检查
• 高性能 - 支持连接池和集群部署

安装

dotnet add package McpHelper.PostgreSQL

依赖

目标框架

• .NET 10.0

快速开始

1. 基础使用

using McpHelper.Extensions;

var builder = WebApplication.CreateBuilder(args);

// 注册核心中间件
builder.Services.AddMcpHelper();

// 添加 PostgreSQL 认证
builder.Services.AddPostgresAuthentication(options =>
{
    options.ConnectionString = "Host=localhost;Database=mydb;Username=user;Password=pass";
    options.TableName = "api_keys";
    options.KeyColumnName = "key";
});

var app = builder.Build();
app.MapMcpHelper();
app.Run();

2. 完整配置

builder.Services.AddPostgresAuthentication(options =>
{
    // 数据库连接字符串
    options.ConnectionString = "Host=localhost;Database=mydb;Username=user;Password=pass;Pooling=true;Maximum Pool Size=100";

    // 表和列配置
    options.TableName = "api_keys";
    options.KeyColumnName = "key";

    // 可选：缓存配置
    options.EnableCache = true;
    options.CacheExpirationMinutes = 30;

    // 可选：认证日志
    options.EnableAuthLog = true;
    options.LogTableName = "auth_logs";
});

配置选项

DatabaseOptions

数据库表结构

API Key 表

CREATE TABLE api_keys (
    id SERIAL PRIMARY KEY,
    key VARCHAR(64) NOT NULL UNIQUE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    is_active BOOLEAN DEFAULT true,
    description VARCHAR(255),
    expires_at TIMESTAMP,
    rate_limit INTEGER DEFAULT 1000
);

-- 创建索引
CREATE INDEX idx_api_keys_key ON api_keys(key);
CREATE INDEX idx_api_keys_is_active ON api_keys(is_active);

-- 插入示例数据
INSERT INTO api_keys (key, description) VALUES
    ('your-api-key-1', 'Development Key'),
    ('your-api-key-2', 'Production Key');

认证日志表（可选）

CREATE TABLE auth_logs (
    id SERIAL PRIMARY KEY,
    key VARCHAR(64) NOT NULL,
    success BOOLEAN NOT NULL,
    ip_address VARCHAR(45),
    user_agent VARCHAR(500),
    timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 创建索引（用于查询优化）
CREATE INDEX idx_auth_logs_timestamp ON auth_logs(timestamp);
CREATE INDEX idx_auth_logs_key ON auth_logs(key);

-- 分区表（可选，用于大量日志）
CREATE TABLE auth_logs_partitioned (
    id SERIAL,
    key VARCHAR(64) NOT NULL,
    success BOOLEAN NOT NULL,
    ip_address VARCHAR(45),
    user_agent VARCHAR(500),
    timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP
) PARTITION BY RANGE (timestamp);

使用示例

创建 API Key

using Npgsql;

// 插入新的 API Key
await using var connection = new NpgsqlConnection(connectionString);
await connection.OpenAsync();

await using var command = connection.CreateCommand();
command.CommandText = @"
    INSERT INTO api_keys (key, description, expires_at)
    VALUES (@key, @description, @expiresAt)";

command.Parameters.AddWithValue("@key", Guid.NewGuid().ToString("N"));
command.Parameters.AddWithValue("@description", "My API Key");
command.Parameters.AddWithValue("@expiresAt", DateTime.UtcNow.AddDays(30));

await command.ExecuteNonQueryAsync();

验证 API Key

认证由中间件自动处理，只需在请求头中添加：

X-Api-Key: your-api-key

完整示例项目

参见 McpHelper.Example.PostgresAuth。

连接字符串配置

基础连接字符串

Host=localhost;Database=mydb;Username=user;Password=pass

生产环境推荐配置

Host=localhost;Database=mydb;Username=user;Password=pass;
Pooling=true;
Maximum Pool Size=100;
Minimum Pool Size=5;
Connection Lifetime=300;
Connection Idle Lifetime=60;
Keepalive=30;
Command Timeout=30;

连接字符串参数说明

认证缓存

启用缓存后，验证通过的 API Key 会被缓存：

• 缓存时间：默认 30 分钟
• 自动刷新：缓存过期后自动重新查询
• 内存存储：使用内存缓存，重启后清空
• 分布式缓存：可扩展为 Redis 等分布式缓存

认证日志

启用日志后，每次认证尝试都会记录：

健康检查

PostgreSQL 认证扩展会自动注册数据库连接工厂：

builder.Services.AddHealthChecks()
    .AddNpgSql(connectionString, name: "postgres-auth");

性能优化建议

数据库层面

1. 创建合适的索引

   CREATE INDEX idx_api_keys_key ON api_keys(key);
   CREATE INDEX idx_api_keys_is_active ON api_keys(is_active) WHERE is_active = true;
   

2. 定期清理日志

   DELETE FROM auth_logs WHERE timestamp < NOW() - INTERVAL '30 days';
   

3. 使用连接池：确保连接字符串中启用 Pooling=true

应用层面

1. 启用缓存：减少数据库查询
2. 调整缓存时间：根据安全需求调整
3. 监控连接池：确保连接池大小合适

与其他认证方式对比

相关项目

• McpHelper.Core - 核心库
• McpHelper.SQLite - SQLite 数据库认证扩展

许可证

MIT License