NIM Key Manager

NIM Key Manager

为你自己的 NVIDIA Build/NIM 账户提供可自托管、可用于生产环境的 API 密钥管理器 — 支持加密存储、辅助轮换、过期检测、用量统计、项目、RBAC、审计、Web 控制面板和 Claude MCP 连接器。几分钟即可部署自己的实例；所有配置均通过环境变量完成。

与 NVIDIA 无关。 这是一个独立的开源项目，与 NVIDIA Corporation 无关，也未获得其认可或赞助。“NVIDIA”“NVIDIA Build”和“NIM”仅用于说明本软件适用的服务；产品和公司名称均归其各自所有者所有。

NVIDIA 服务条款。 NVIDIA Build 不提供用于以编程方式创建或轮换密钥的公共 API（你可以在 build.nvidia.com 生成密钥），且 不得与第三方共享或重新分发 API 密钥。因此，本项目旨在让你在自己的实例上管理自己的密钥：唯一的出站调用是官方的只读验证端点 GET https://integrate.api.nvidia.com/v1/models。它不会自动操作或抓取 NVIDIA 门户，也不是一个向他人提供密钥的服务。

部署你自己的实例（无需本地设置）

1. 点击按钮（或选择 Use this template → Create repository，然后在 Render 中选择 New → Blueprint 并选择你的派生仓库）。Render 会读取 render.yaml 并自动配置所有内容：
   • 托管的 PostgreSQL 数据库，
   • 带健康检查的 Docker 化 Web 服务，
   • 密钥 JWT_SECRET、ENCRYPTION_MASTER_KEY 和 MCP_OAUTH_JWT_SIGNING_KEY（由 Render 的密钥管理器生成并存储），
   • 从数据库注入的 DATABASE_URL。
2. 出现提示时，设置 FIRST_ADMIN_EMAIL 和 FIRST_ADMIN_PASSWORD（你的初始管理员将在首次启动时创建；此项为必填，因为无法通过 HTTP 请求创建首位管理员）。
3. 打开服务 URL：在 / 登录，在 /docs 查看 API。
4. 每次向 main 推送都会运行 CI（lint + 类型检查 + 测试 + 构建）；所有检查通过后，Render 会自动重新部署（检查失败的提交不会部署）。容器启动时会运行迁移（alembic upgrade head）。

更倾向于使用其他托管平台？任何支持运行 Docker 容器和 PostgreSQL 的平台都可以 — 参见 docs/deployment.md。

在 Claude 中使用（MCP 连接器）

同一部署还会在 ‹BASE›/mcp 提供 Model Context Protocol 服务器，你可以将其添加到 Claude 作为自定义连接器。Claude 使用 OAuth 2.1 进行身份验证（默认使用 GitHub，也可选用 Google），并可列出/检查密钥、分发可直接使用的密钥、注册/轮换/撤销密钥以及管理项目——并具有与 REST API 相同的 RBAC 和审计跟踪。只有列在 MCP_ALLOWED_IDENTITIES 中的身份才能连接（默认拒绝）。连接器是可选的：在设置下方的 OAuth 凭据之前，/mcp 会保持关闭，其他所有功能均可正常运行。

1. 创建 GitHub OAuth App，并将回调地址设为 ‹BASE›/auth/callback；复制 Client ID/Secret。
2. 在 Render 中设置 MCP_GITHUB_CLIENT_ID、MCP_GITHUB_CLIENT_SECRET 和 MCP_ALLOWED_IDENTITIES（你的 GitHub 数字用户 ID 和/或电子邮件地址，而不是登录名：curl -s https://api.github.com/users/YOUR-LOGIN | jq .id；连接器创建的用户默认是查看者，除非你设置 MCP_DEFAULT_ROLE）。其他配置已在 render.yaml 中。
3. 在 Claude 中：Settings → Connectors → Add custom connector → URL ‹BASE›/mcp → Connect。

完整指南（Google、工具参考、安全性、故障排除）：docs/connector.md。

功能

• 安全的密钥注册 — 使用 AES-256-GCM 加密静态数据（密钥通过 HKDF-SHA256 从平台密钥管理器中的密钥派生）。绝不以明文存储或记录。
• 辅助轮换与审计 — 你在 NVIDIA 账户中创建新密钥并粘贴，然后系统会执行原子交换（新密钥启用，旧密钥撤销，并通过 rotated_from_id 建立沿袭关联）。
• 过期检测 — 每小时运行一次后台任务，并提供维护端点；可配置 expiring_soon 标记。
• 定期验证 — 每 6 小时（可配置）自动对 NVIDIA 执行检查，并标记无效/已撤销的密钥。
• 密钥分发 — GET /api/v1/keys/dispense 返回最近最少使用的有效密钥（LRU），可按全局或项目范围返回，并记录使用情况。
• 项目 — 按使用方/工作负载对密钥分组。
• 统计信息 — 按状态统计库存、密钥分发情况和使用时间序列。
• 安全性 — JWT（访问令牌 + 刷新令牌）、admin/manager/viewer 角色、速率限制，以及对每项敏感操作的不可变审计记录。
• Claude 连接器（MCP） — 位于 /mcp 的 OAuth 安全保护 MCP 服务器（见上文）。
• 运维 — 结构化 JSON 日志、/metrics 上的 Prometheus 指标（需管理员令牌或 METRICS_TOKEN）、/health 健康检查、/docs OpenAPI 文档。

架构

app/
├── domain/           # Enums and domain exceptions (no dependencies)
├── application/      # Use cases (services) and ports (interfaces)
│   └── services/     # auth, users, keys, projects, stats, audit
├── infrastructure/   # Adapters: SQLAlchemy (repositories) and NVIDIA gateway
├── api/              # FastAPI: routers, schemas, deps, rate limiting
├── mcp/              # Claude connector: MCP server, OAuth and identity mapping
├── dashboard/        # Lightweight SPA served at /
├── tasks/            # Scheduled jobs (APScheduler)
└── core/             # Config, crypto, security, logging

务实的整洁架构：依赖关系向内指向；应用层不了解 FastAPI，并通过 KeyValidator 端口访问 NVIDIA。详情和设计决策见 docs/architecture.md。

技术栈：Python 3.12 · FastAPI · FastMCP（Claude 连接器）· SQLAlchemy 2（异步）· 托管 PostgreSQL · Alembic · Docker · GitHub Actions · Render（Blueprint）· structlog · Prometheus · slowapi · APScheduler。

API 快速入门

BASE=https://your-service.onrender.com

# Log in (the admin was created on first boot)
TOKEN=$(curl -s $BASE/api/v1/auth/login -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","password":"your-password"}' | jq -r .access_token)

# Register a key created at build.nvidia.com (validating it against NVIDIA)
curl -s $BASE/api/v1/keys -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"name":"prod-1","api_key":"nvapi-...","validate_remote":true}'

# Get an available key (LRU) to use in your application
curl -s "$BASE/api/v1/keys/dispense" -H "Authorization: Bearer $TOKEN"

更多示例（轮换、项目、统计信息、审计）见 docs/api-examples.md。可在 /docs 查看交互式 OpenAPI 文档。

角色

操作	查看者	管理者	管理员
查看密钥、项目和统计信息	✅	✅	✅
注册 / 验证 / 轮换 / 撤销 / 分发密钥	❌	✅	✅
管理项目	❌	✅	✅
删除密钥、管理用户、读取审计日志	❌	❌	✅

开发与测试

部署并不需要这些，但项目完全支持：

pip install -e ".[dev]"
pytest --cov=app          # required coverage gate: 85% (currently ~94%)
ruff check . && mypy app
docker compose up         # local stack with PostgreSQL

安全

威胁模型、加密细节和设计决策见 docs/security.md。要点：使用从密钥管理器派生的密钥（HKDF）进行 AES-256-GCM 加密，使用 SHA-256 指纹在不暴露密钥的情况下去重，使用短时效签名 JWT，使用 argon2 对密码进行哈希处理，按 IP 限流，审计每项敏感操作；除显式的发放端点外，日志和响应中不包含明文密钥。报告漏洞，请参阅 SECURITY.md。

贡献

欢迎贡献——请参阅 CONTRIBUTING.md 和行为准则。README.es.md 中提供了简短的西班牙语概览。

许可证

MIT——请参阅 LICENSE。